commit a5d1dec495a56b60c9b44a2baa47cd456ed7c9ba Author: AskaEth Date: Wed Nov 11 21:41:38 2026 +0800 release: v0.2.4 里程碑快照（孤儿提交，无父；树 = dev 68362e5） 本批内容见 CHANGELOG.md 的 0.2.4 段。按 D41 用孤儿快照推 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..a9f8391 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,336 @@ +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 + # ---- 下载页选项区的四条像素守门（M127）：先出图，再把路径喂给 `--lib` ---- + # 之前这四条靠开发者本机手动设 `ULL_DL_*_SHOT`（不设就 SKIP），而本文件里 grep 这些 + # 变量零命中 ⇒ **CI 里一次都没跑过**。空跑的守门长期等于没有，所以这两步是它们的第一处 + # 常驻调用点。（另有一道保险：变量缺失且 `CI` 已设置时，守门自己会失败而不是跳过。 + # 于是将来谁把下面出图那步重构掉，构建会红。） + # + # **为什么只在 Windows**：断言里有几条直接量墨迹（行高 44、版本号墨迹条数、图标药丸 + # 40×40），这些数字按本仓字体栈（Segoe UI / Consolas）标定；Linux/macOS runner 上 + # 这套字体不存在，回退字体的字高与行距一变就是假红。同一条限制也写在 + # `crates/app-iced/src/pages/download/tests/options_shot/feed.rs` 的模块文档里 + # （非 Windows 喂了图会当场失败），不靠「碰巧只配了一处」。 + - name: 出四张像素守门用的图并写进 $GITHUB_ENV（仅 Windows） + if: runner.os == 'Windows' + shell: bash + run: | + set -euo pipefail + shots="$RUNNER_TEMP/dl-shots" + mkdir -p "$shots" + render() { # $1=宽 $2=文件名 + cargo run -q -p unlucky-app-iced --example pages_demo -- --screen=download \ + --width="$1" --height=760 --screenshot="$shots/$2" \ + --screenshot-theme=light --software-renderer + } + # ready700：**不设** ULL_DL_DEMO（缺省就是 ready，还没选版本） + render 700 ready700.png + export ULL_DL_DEMO=options-fabric # 其余三张都是「选中版本 + 选项区展开」 + render 700 chips700.png + render 736 compact736.png + render 1180 wide1180.png + for shot in ready700 chips700 compact736 wide1180; do + test -s "$shots/$shot.png" || { echo "::error::$shot.png 没出图"; exit 1; } + done + ls -l "$shots" + { + echo "ULL_DL_READY_SHOT=$shots/ready700.png" + echo "ULL_DL_CHIPS_SHOT=$shots/chips700.png" + echo "ULL_DL_COMPACT_SHOT=$shots/compact736.png" + echo "ULL_DL_OPTIONS_SHOT=$shots/wide1180.png" + } >> "$GITHUB_ENV" + # 单独跑一遍只为**取证**：日志里那行 `test result: ok. 4 passed` 是「守门真跑了」的 + # 直接证据（紧接着的 `--workspace` 那步会再跑一遍，热的，代价可忽略）。 + - name: 四条像素守门（已喂图，仅 Windows） + if: runner.os == 'Windows' + run: cargo test -p unlucky-app-iced --lib options_shot + # 断言红的时候要先看到那张图（否则「像素不对」只有一句话，没有现场）。 + - name: 上传喂进守门的四张图（失败也传） + if: always() && runner.os == 'Windows' + uses: actions/upload-artifact@v4 + with: + name: dl-shots + path: ${{ runner.temp }}/dl-shots/ + if-no-files-found: warn + # 同 clippy：`--workspace` 不含 `unlucky-app`（M118），Slint 退役树不再被 `--all-targets` 拉起。 + # 也因此**不要**再写 `--exclude unlucky-app`：它已不是成员，那面旗子只会打一条 + # `excluded package(s) … not found in workspace` 的警告然后空转（实测 exit 0，不报错）。 + # + # ---- 取证（M147）：下面是同一件事的两个平台版本，不是两条不同的测试 ---- + # M144 的三条红里两条已在 docker 里定位到行，第三条 `test (windows)` 在 run 里只留下 + # `Process completed with exit code 1`——而 cargo 自己的失败码是 **101**，所以那个 1 的 + # 来源不明（包装层洗码 / 进程被杀，两说都未排除）。job log 要登录才能读（匿名 403）， + # 但**注解匿名可读**（`GET /check-runs//annotations` → 200，M144 实证）。所以这三件 + # 事各自对准一种「看不见」： + # 1) `--no-fail-fast`：cargo 默认在第一个失败的 target 就停（M144 实测 Linux 只跑了 + # 7 个 test binary 就退出），后面还有没有第二条失败完全看不到； + # 2) 把 `error` / `failures:` / panicked 行升成 `::error::` 注解：拿不到 job log 时， + # 注解是匿名侧唯一能取到的失败正文； + # 3) 显式打印 cargo 的退出码：把「包装层把码洗成 1」「cargo 真失败（101）」「进程被杀 + # 只给码、零诊断」三种情形分开——这正是 M144 没定的那一半。 + - name: cargo test --workspace --all-targets（ubuntu，失败升注解） + if: runner.os == 'Linux' + run: | + log="$RUNNER_TEMP/cargo-test.log" + # 默认 shell 带 `-e` + `pipefail`：管道里 cargo 一失败就会在 tee 之后立刻退出， + # 下面三行永远跑不到。所以这段先关 `-e`，自己取 `PIPESTATUS[0]`（cargo 的码， + # 不是 tee 的码）。 + set +e + cargo test --workspace --all-targets --no-fail-fast 2>&1 | tee "$log" + code=${PIPESTATUS[0]} + set -e + echo "cargo exit=$code" + if [ "$code" -ne 0 ]; then + # `%` 是 workflow command 的保留字符，要转成 `%25`，否则注解正文会被截断。 + grep -E '^(error(\[E[0-9]+\])?:|failures:|test result: FAILED|thread .* panicked at| *--> )' "$log" \ + | head -40 | sed 's/%/%25/g; s/^/::error::/' || true + fi + exit "$code" + - name: cargo test --workspace --all-targets（windows，失败升注解） + if: runner.os == 'Windows' + shell: pwsh + env: + # M171 跨卷守卫：runner 到底有没有第二块可写卷没有核实手段，所以不赌 —— 显式声明豁免。 + # 豁免是惰性的：真探到第二块卷时它不参与判断（见 install_xdev_cases 的真值表用例）。 + ULL_XDEV_TEST_WAIVE: "1" + run: | + # pwsh 没有 PIPESTATUS（那是 bash 语法）：拿 `$LASTEXITCODE` —— Tee-Object 是 cmdlet， + # 不会把它改掉，所以它是 cargo 自己的码。 + $log = Join-Path $env:RUNNER_TEMP 'cargo-test.log' + cargo test --workspace --all-targets --no-fail-fast 2>&1 | Tee-Object -FilePath $log + $code = $LASTEXITCODE + Write-Host "cargo exit=$code" + if ($code -ne 0) { + # 正则不锚 `error:` 那一支：pwsh 把原生 stderr 折成 ErrorRecord 后行首可能多一截前缀， + # 锚死会漏行；`%` 是 workflow command 的保留字符，转成 `%25`。 + Select-String -Path $log -Pattern '(error(\[E\d+\])?:|^failures:|test result: FAILED|thread .* panicked at|^\s+--> )' | + Select-Object -First 40 | + ForEach-Object { Write-Host "::error::$($_.Line.Replace('%', '%25'))" } + } + exit $code + + 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 + # M196：PR 阶段就拦住「产物退回 CUI(3)」。判据是产物 PE 头的 `Subsystem` 字段，不是源码文本—— + # 这个 bug 的原始形态正是「源码写了、打在另一棵树上」，任何只看 `grep windows_subsystem` 的守卫 + # 都抓不住它。发布侧同一份脚本再跑一次（`release-build.yml`），两处判据同一个真源。 + - name: PE 子系统门禁（GUI 产物必须 WINDOWS_GUI/2，CLI 产物必须 CONSOLE/3） + if: runner.os == 'Windows' + shell: bash + run: | + set -euo pipefail + PY=$(command -v python3 || command -v python) + "$PY" packaging/check_pe_subsystem.py \ + --gui target/release/unlucky-launcher-iced.exe \ + --cli target/release/ull.exe + + # 运行时冒烟（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 + + # M169：更新链路的**端到端验收**（发现新版本 → 下载 → 长度/SHA256 双检 → 就位；篡改摘要 / + # 篡改包体 / 截断必须拒绝且不动现有安装；重复 apply 的幂等终态）。 + # + # 独立 job、只在 Windows：夹具的「真形状」只在 Windows 成立——真实产物是裸 `.exe` + + # `portable-exe`，而 Linux/macOS 是 `.tar.gz` + `portable-zip`（会被 `ensure_self_replaceable` + # 直接拒）。在 ubuntu 上跑绿只能证明「一个世上不存在的 linux portable-exe 能装上」，是假绿 + # （r1 复审 P2-4）。 + # + # 本 job 的步骤名 `update-e2e` 是**唯一**被允许出现 `update-test-source` 的地方，判据在 + # `packaging/check_test_source_off.py` 的 `ALLOWED_STEP`：文件名 / 步骤名 / `--test + # update_e2e_test` 三者任一不符即红——改这里的 name 或 run 之前先读那段注释。 + # + # 慢是已知的（release + fat LTO，本机实测 7 分钟；不发 debug 档：`debug_assertions`、优化与 + # panic 行为都不一样，用 debug 跑这条 E2E 就失去了它存在的理由）。tower 明确：能跑起来比跑得快重要。 + update-e2e: + name: update-e2e (windows x64) + runs-on: windows-latest + timeout-minutes: 45 + env: + # 同 test 作业：跨卷 e2e 守卫在没有第二块卷的 runner 上需要显式豁免，否则会判红。 + ULL_XDEV_TEST_WAIVE: "1" + steps: + - uses: actions/checkout@v4 + - uses: dtolnay/rust-toolchain@stable + - uses: Swatinem/rust-cache@v2 + - name: update-e2e + run: > + cargo test --release -p unlucky-cli --features update-test-source + --test update_e2e_test --test update_e2e_tamper_test diff --git a/.github/workflows/dev-guards.yml b/.github/workflows/dev-guards.yml new file mode 100644 index 0000000..be56b68 --- /dev/null +++ b/.github/workflows/dev-guards.yml @@ -0,0 +1,133 @@ +name: Dev Guards + +# 日常线门禁（M133）。 +# +# 为什么需要这个文件：本仓日常开发线是 `dev`，日常合并**不走 PR**（见 DevDocs/AGENTS.md §8 双仓纪律： +# Gitea `dev` = 日常线）。而 ci.yml 与 guards.yml 只挂在 `push: branches: [main]` + `pull_request` 上 +# ⇒ fmt / clippy / 文件行数≤400 / 三条零依赖守门在**日常线上一次都没跑过**。第一个可见后果： +# `packaging/README.md` 涨到 401 行、超全仓红线无人拦，直到文档普查才被发现（M131 才修回 398）。 +# 「门禁存在但日常线上永不运行」= 空跑的门禁，长期等于没有。 +# +# 口径：**只补「快、且坏了会静默腐化」的那几道**，且不复制守门脚本： +# - `guards` 作业直接 `uses: ./.github/workflows/guards.yml` —— 六道守门（core-no-ui / +# presenter-no-ui / design-zero-dep / unsafe-scope / file-size / licenses）跑的是与 main 同一份脚本， +# dev 与 main 的判据永远同源。main / PR / dispatch 的触发与作业一个字没动。 +# - `fmt` / `clippy` 在本文件里各写一份：ci.yml 的作业背后挂着 build / test / runtime-smoke 整条矩阵， +# 整份复用等于把 dev 的成本翻倍；这两条命令与 ci.yml 逐字一致，方便对照与同步。 +# +# 刻意**不上** dev 的（判断依据见 M133 报告，这里只记结论）： +# - 全量 `cargo test`：`clippy --all-targets` 已经把测试**代码**类型检查过一遍（「测试编译不过了」 +# 这类静默腐化会被它抓到），而「断言暂时红了」在施工中间态是常态、不是腐化；test 是 2 个 OS × +# 全量编译+运行，留给 main 与发布前的最终门更划算。 +# - build release / runtime-smoke：它们是「能不能发」的门，dev 每次 push 跑一遍换不到新信息。 +# +# 成本控制（dev push 很频繁，这是硬要求）： +# 1. `concurrency` 取消**同一个 ref** 上的旧运行：连推三次只留最后一次，被取消的旧运行基本不计费。 +# 2. clippy 只在「这次推送碰过 Rust 侧文件」时跑：只改文档（*.md / LICENSE / NOTICE / .gitignore） +# 的推送跳过编译。判据**保守**——非 push、base 不可解析（force-push / 首次推送）、diff 取不到、 +# 出现任何不在白名单里的路径，一律照跑：宁可多跑一次，不许假绿。 +# 刻意**不**用 `on.push.paths` 过滤整个工作流：file-size 正是要在「只改文档」的推送里跑的那道门 +# （README 401 行就是这么漏的），整条过滤掉等于自废武功。 + +on: + push: + branches: [dev] + workflow_dispatch: + +env: + CARGO_TERM_COLOR: always + RUST_BACKTRACE: 1 + +concurrency: + group: dev-guards-${{ github.ref }} + cancel-in-progress: true + +jobs: + # 六道守门原样来自 guards.yml（那边加了 `workflow_call:` 触发，纯新增）。本文件不重写它们的脚本： + # unsafe-scope 的词法器一旦有第二份副本，就会出现「dev 绿、main 红」的双真相。 + guards: + name: 架构与合规守门（同 main 口径） + uses: ./.github/workflows/guards.yml + + # GPU 证据门禁（M253 r1 P2-1）：与 main **同一份** workflow，理由同上 —— 判据只能有一份。 + # dev 上 `evidence` 照样显式跳过（无 GPU、无产物，见该文件的 probe job），所以实际拿到的是 + # `selftest` 那一半：19 条向量 + 三个退出码 0/1/2 + 接线自检，成本就是一次 python 自测。 + # 不另加「只跑自测」的开关：那会给这道门禁多开一个「可以合法关掉真判据」的旋钮。 + gpu-evidence: + name: GPU 证据门禁（同 main 口径；无 GPU 只跑自测） + uses: ./.github/workflows/gpu-evidence.yml + + 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 + + # 只跑 ubuntu：clippy 的判据是类型层 lint，跨平台差异极少（Windows 专属行为由 main/PR 上的 + # windows-latest 槽位与 test 里的像素守门兜）；两个 OS 都上会把 dev 的编译成本直接翻倍。 + clippy: + name: clippy (ubuntu) + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + # 要 diff 出「这次推了哪些文件」就得有 base commit；浅 clone 会让下面的判据退化成 + # 「一律照跑」（保守，但不再省成本），所以这里取全历史。 + fetch-depth: 0 + - name: 本次推送是否碰过 Rust 侧文件（只碰文档则跳过编译） + id: scope + env: + EVENT: ${{ github.event_name }} + BEFORE: ${{ github.event.before }} + SHA: ${{ github.sha }} + run: | + set -uo pipefail + run=yes + note="照跑：默认（未进入可判定的 push 分支）" + if [ "$EVENT" != "push" ]; then + note="照跑：非 push 事件（手动 dispatch）没有可信 diff" + elif [ -z "${BEFORE:-}" ] || [ "$BEFORE" = "0000000000000000000000000000000000000000" ]; then + note="照跑：base 为首次推送（before 全 0）" + elif ! git rev-parse --verify -q "${BEFORE}^{commit}" >/dev/null 2>&1; then + note="照跑：base commit 不可解析（force-push / 历史被改写）" + else + changed=$(git diff --name-only "$BEFORE" "$SHA" 2>/dev/null || true) + if [ -z "$changed" ]; then + note="照跑：diff 为空（可能是增量不可得）" + else + # 白名单判定：只有「全部改动都落在这些非 Rust 路径上」才跳过编译。 + # 反向写法（黑名单 .rs）更省事，但漏一个路径就等于漏一次编译检查。 + others=$(printf '%s\n' "$changed" \ + | grep -vE '\.md$' \ + | grep -vxE 'LICENSE|NOTICE|\.gitignore' || true) + if [ -z "$others" ]; then + run=no + note="跳过：本次只碰文档类路径 —— $(printf '%s ' $changed)" + else + note="照跑：本次改动了非文档路径 —— $(printf '%s ' $others)" + fi + fi + fi + echo "$note" + echo "run=$run" >> "$GITHUB_OUTPUT" + - name: Linux 图形栈构建依赖（winit / wgpu 编译期需要） + if: steps.scope.outputs.run == 'yes' + 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 + if: steps.scope.outputs.run == 'yes' + with: + components: clippy + - uses: Swatinem/rust-cache@v2 + if: steps.scope.outputs.run == 'yes' + # 与 ci.yml 的 clippy 作业逐字一致（`--workspace` 不含已退役的 `unlucky-app`，见 M118）。 + - name: cargo clippy --workspace --all-targets -D warnings + if: steps.scope.outputs.run == 'yes' + run: cargo clippy --workspace --all-targets -- -D warnings diff --git a/.github/workflows/gpu-evidence.yml b/.github/workflows/gpu-evidence.yml new file mode 100644 index 0000000..8804e51 --- /dev/null +++ b/.github/workflows/gpu-evidence.yml @@ -0,0 +1,233 @@ +name: GPU evidence + +# GPU 截图证据门禁（M253：把 M249 的 `packaging/check_gpu_shot.py` 接进 CI）。 +# +# **为什么新开一个文件，不并进 guards.yml**：guards.yml 已是 399 行、红线 400（`file-size` 那道门 +# 就扫 `*.yml`），挂一个 job 必越线；`release-build.yml` 正好 400 行、动它得先拆。这与 +# `release-guard.yml` 当初单独成文的理由逐字相同（那份文件头：「那份文件已经 398 行（400 行红线）， +# 再挂一个 job 必越线」）。 +# +# 口径（塔定，M253 Context 原文）：**CI runner 无 GPU 时必须显式 skip 并写明原因，不得静默 pass**。 +# 落到这份文件的三条硬规矩 —— 它们由 `packaging/tests/gpu_shot_ci_selftest.py` 机器校验 +# （33 条「改绿」变异逐条重放、10 类封闭清单），不是靠这几行注释自律；那份脚本的 docstring 写清它**保证什么、 +# 保证不了什么**（r1 复审实测：上一版 19 条变异漏 11 条，所以这里不敢再写「不可能」）： +# ① `selftest` job **无条件**跑 `--self-test`：它证明「尺子合格」，不需要 GPU、也不需要真产物； +# 同一 job 再用真 CLI 走一遍三个退出码（0 过 / 1 判据不过 / 2 用法错）。 +# ② 真实产物判据只在 `probe` job 探到**工作区里真有可用产物**时才跑。 +# ③ **跳过与通过分开写**：跳过的做法是让 `evidence` job 的 `if:` 不成立 —— 它在 Actions 里显示 +# **灰色 skipped**，不是一个绿色的 ✓；同时 `probe` 在 job summary 里写明缺什么、为什么， +# 并打 `::warning::` 说明「本次没有判过任何真实产物」。 +# +# 载体依赖：整个 `gpu-evidence.yml` 被删掉/替换后，**没有任何东西会跑这个自检** —— 守门人住在被守对象自己的文件里（`guards.yml` 已经 399/400 行，塞不进去）。 +# 所以改这道门禁时请连自检一起想：自检只认「上面那张封闭清单」，不宣称「不可能被改成总是绿」。 +# +# 判据本身（六条 + `--expect-refuse` 三条）与能证/不能证：`packaging/docs/gpu-evidence.md`。 +# 改这份文件先跑 `python3 packaging/tests/gpu_shot_ci_selftest.py`。 + +on: + push: + branches: [main] + pull_request: + workflow_dispatch: + inputs: + shot_log: + description: 'stderr 日志路径（需带 ULL_GPU_LOG=info，例 DevDocs/artifacts/gpu-probe/a1-gpu.stderr.log）；留空则按下面的约定路径判' + required: false + default: '' + shot_png: + description: '同一运行的 PNG 路径；负例（expect_refuse=true）可留空' + required: false + default: '' + expect_refuse: + description: '按负例口径判（--expect-refuse：要求 via=refuse 且一张图都没出）' + type: boolean + default: false + # 日常线 `dev` 复用**同一份**判据与接线（r1 P2-1）：`dev-guards.yml` 里 + # `uses: ./.github/workflows/gpu-evidence.yml`。理由与 guards.yml 的 `workflow_call:` 逐字相同： + # 判据只能有一份，两份各自演进迟早出现「dev 绿、main 红」的双真相；而 `dev-guards.yml` 文件头 + # 自己写着「空跑的门禁等于没有」。dev 上 `evidence` 照样显式跳过（无 GPU、无产物），所以 dev 拿到的 + # 是 `selftest` 那一半：19 条向量 + 三个退出码 + 接线自检，成本就是一次 python 自测。 + workflow_call: + +jobs: + selftest: + name: GPU 判据自测（不需 GPU；跳过 ≠ 已验证） + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: 判据实现自测（19 条向量，数据在 packaging/tests/gpu_shot_vectors.json） + id: vectors + run: python3 packaging/check_gpu_shot.py --self-test + # 自测走的是判据**函数**，退出码是 `main()` 的那一行。这里用真 CLI 把三个码都走一遍： + # 少了这一步，「退出码永远 0」这种回归在 CI 上照样全绿（门禁自己变成假绿）。 + - name: 退出码语义（0 过 / 1 判据不过 / 2 用法错） + id: exitcodes + run: | + set -uo pipefail + work="$RUNNER_TEMP/gpu-shot-exitcodes" + mkdir -p "$work" + # 用自测脚手架现造一份能过的一对（同一份 synth_log/synth_png，避免第二套手工拼装） + python3 - "$work" <<'PY' + import sys + from pathlib import Path + sys.path[:0] = ["packaging", "packaging/tests"] + from gpu_shot_selftest import SELFTEST_SIZE, synth_log, synth_png + + root = Path(sys.argv[1]) + (root / "pass.stderr.log").write_text(synth_log(size=SELFTEST_SIZE), encoding="utf-8") + (root / "pass.png").write_bytes(synth_png("content", SELFTEST_SIZE)) + (root / "red.stderr.log").write_text(synth_log(renderer="tiny-skia"), encoding="utf-8") + PY + expect() { # expect <期望退出码> <说明> <命令...> + want="$1"; note="$2"; shift 2 + set +e + "$@" > "$work/out.txt" 2>&1 + got=$? + set -e + cat "$work/out.txt" + if [ "$got" -ne "$want" ]; then + echo "::error::退出码语义不对：$note 期望 $want，实际 $got。判据脚本的 0/1/2 是整条门禁的接口，变了就是门禁变了。" + exit 1 + fi + echo "OK: $note → exit=$got" + } + expect 0 "正例（合成日志 + 合成 PNG，六条判据全过）" \ + python3 packaging/check_gpu_shot.py "$work/pass.stderr.log" "$work/pass.png" + expect 1 "CPU 档日志（renderer=tiny-skia，判据点名判红）" \ + python3 packaging/check_gpu_shot.py "$work/red.stderr.log" "$work/pass.png" + expect 2 "用法错（一个位置参数都没给）" \ + python3 packaging/check_gpu_shot.py + - name: 接线自检（33 条「改绿」变异必须重放为红；覆盖边界见脚本 docstring） + id: wiring + run: python3 packaging/tests/gpu_shot_ci_selftest.py + + probe: + name: GPU 证据 — 探测可用产物与硬件适配器 + runs-on: ubuntu-latest + outputs: + available: ${{ steps.detect.outputs.available }} + log: ${{ steps.detect.outputs.log }} + png: ${{ steps.detect.outputs.png }} + reason: ${{ steps.detect.outputs.reason }} + steps: + - uses: actions/checkout@v4 + - name: 探测样例产物与硬件适配器（只探测、不判定） + id: detect + env: + SHOT_LOG: ${{ github.event.inputs.shot_log }} + SHOT_PNG: ${{ github.event.inputs.shot_png }} + EXPECT_REFUSE: ${{ github.event.inputs.expect_refuse }} + EVENT: ${{ github.event_name }} + run: | + set -uo pipefail + default_dir=DevDocs/artifacts/gpu-probe + default_stem=gpu-shot + log_path="" + png_path="" + available=false + reason="" + + if [ -n "${SHOT_LOG:-}" ]; then + # ① dispatch 显式点了名：**给了却找不到 = 红**。若「明确说要判、东西不在」能退化成跳过， + # 那又是一次假绿 —— 有意为之的输入缺失是错误，不是 skip。 + if [ ! -f "${SHOT_LOG}" ]; then + echo "::error::dispatch 指定了 shot_log=${SHOT_LOG}，但工作区里没这个文件 —— 显式要求判定的输入缺失按红处理（不跳过）" + exit 1 + fi + if [ -n "${SHOT_PNG:-}" ] && [ ! -f "${SHOT_PNG}" ]; then + echo "::error::dispatch 指定了 shot_png=${SHOT_PNG}，但工作区里没这个文件 —— 同上，按红处理" + exit 1 + fi + if [ "${EXPECT_REFUSE:-false}" != "true" ] && [ -z "${SHOT_PNG:-}" ]; then + echo "::error::正例（expect_refuse=false）必须给 shot_png；只有负例可以省略 PNG" + exit 1 + fi + log_path="${SHOT_LOG}" + png_path="${SHOT_PNG:-}" + available=true + reason="dispatch 显式指定产物（${log_path}）" + elif [ -f "${default_dir}/${default_stem}.stderr.log" ] && [ -f "${default_dir}/${default_stem}.png" ]; then + # ② 约定路径：一次取证 = 一份干净的 stderr + 同一次运行的那张图 + # （`--diff`/拼接会骗过判据，见 gpu-evidence.md §5 第 1/7 条）。 + log_path="${default_dir}/${default_stem}.stderr.log" + png_path="${default_dir}/${default_stem}.png" + available=true + reason="工作区里有约定产物（${default_dir}/${default_stem}.*）" + else + # ③ 什么都没有 —— 这是 GitHub 托管 runner 的常态：托管 runner 没有 GPU， + # 而样例产物也不在仓库里（`DevDocs/` 被 .gitignore 忽略，图不进仓库）。 + # 必须显式跳过 + 写明原因，不许静默 pass。 + if compgen -G '/dev/dri/renderD*' >/dev/null; then + adapter='本机有硬件适配器（/dev/dri/renderD*）' + elif command -v nvidia-smi >/dev/null 2>&1 && nvidia-smi -L >/dev/null 2>&1; then + adapter='本机有硬件适配器（nvidia-smi -L 有输出）' + else + adapter='无硬件适配器（/dev/dri 下没有 renderD*，也没有可用的 nvidia-smi）' + fi + reason="${adapter}，且工作区里没有可用的样例产物（约定路径要求 stderr 日志与同次运行的 PNG 同时存在；DevDocs/ 被 .gitignore 忽略，图不进仓库；event=${EVENT}）" + fi + + { + echo "available=${available}" + echo "log=${log_path}" + echo "png=${png_path}" + echo "reason=${reason}" + } >> "$GITHUB_OUTPUT" + + if [ "${available}" = "true" ]; then + echo "GPU 证据：${reason} —— 交给 evidence job 跑真实产物判据（0 过 / 1 判据不过）" + else + echo "GPU 证据：${reason}，跳过真实产物判据（判据实现自测已过：那证明「尺子合格」，不证明「这张图是 GPU 出的」）" + # warning 而不是 notice：这一趟运行**看起来是绿的**，必须在 UI 上留一条黄条说清它没判过。 + echo "::warning::GPU 证据：跳过（${reason}）—— 本次运行没有判过任何真实产物，不构成「GPU 证据已验证」" + fi + + { + echo "## GPU 证据（M253）" + echo + if [ "${available}" = "true" ]; then + echo "- 结论：**跑真实产物判据**（${reason}）" + echo "- 产物：${log_path}" + if [ -n "${png_path}" ]; then echo "- PNG：${png_path}"; else echo "- PNG：无（负例口径 ${EXPECT_REFUSE:-false}）"; fi + echo "- 判定看 \`evidence\` job 的退出码（0 过 / 1 判据不过 / 2 用法错）；这里是「有东西可判」，不是「判过了」。" + else + echo "- 结论：**⏭ 跳过（未验证）** —— ${reason}" + echo "- 「这张图真是 GPU 档出的」这件事，**本次没有判过**；跳过不等于通过。" + echo "- 已经验过的是尺子本身：\`--self-test\`（19 条向量）与三个退出码 0/1/2（\`selftest\` job）。" + echo "- 想让它变成真判定，只有两条**在这个 CI 运行里真能执行**的路：" + echo " ① \`workflow_dispatch\` 填 \`shot_log\` / \`shot_png\`，且两个文件必须**已被 checkout 下来**" + echo " —— checkout 只拿已跟踪文件，所以产物得先提交进被 dispatch 的那个 ref；" + echo " ② 把一对产物提交到 \`${default_dir}/${default_stem}.stderr.log\` + \`${default_dir}/${default_stem}.png\`" + echo " 再对那个 ref 跑一次（\`${default_dir}\` 在 .gitignore 里，要用 \`git add -f\`；" + echo " 或改放到任一已跟踪目录，用 ① 的输入指过去）。" + echo " 就地往 workspace 里拷文件（不提交）在 CI 上做不到：那次运行 checkout 的树里没有 DevDocs/。" + fi + } >> "$GITHUB_STEP_SUMMARY" + + evidence: + name: GPU 证据 — 真实产物判据 + needs: [selftest, probe] + # 第 ③ 条规矩就在这一行：没有可用产物 ⇒ 整个 job 不运行，UI 上是灰色 skipped， + # 不是一个绿色 ✓。这正是「跳过」与「通过」分开写的地方（r1 复审实核过这条 if 的语义）。 + if: needs.probe.outputs.available == 'true' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: 判定（0 过 / 1 判据不过 / 2 用法错；退出码即结论，不许被 || true 吞掉） + id: judge + env: + LOG: ${{ needs.probe.outputs.log }} + PNG: ${{ needs.probe.outputs.png }} + EXPECT_REFUSE: ${{ github.event.inputs.expect_refuse }} + run: | + set -uo pipefail + echo "GPU 证据：判 ${LOG}" + if [ "${EXPECT_REFUSE:-false}" = "true" ]; then + if [ -n "${PNG}" ]; then + python3 packaging/check_gpu_shot.py "$LOG" --expect-refuse "$PNG" + else + python3 packaging/check_gpu_shot.py "$LOG" --expect-refuse + fi + else + python3 packaging/check_gpu_shot.py "$LOG" "$PNG" + fi diff --git a/.github/workflows/guards.yml b/.github/workflows/guards.yml new file mode 100644 index 0000000..1feddf2 --- /dev/null +++ b/.github/workflows/guards.yml @@ -0,0 +1,399 @@ +name: Guards + +# ⚠ 本文件所有 `run:` 都在 `bash -e {0}` 下跑（GitHub 未指定 shell 时的默认值），脚本里的 +# `set -uo pipefail` **关不掉 -e**：裸管道 / 裸赋值 `x=$(… | grep …)` 零命中时会把整步静默杀死， +# 一条 `::error::` 都不打（M142 在 release-build.yml 栽过，M156 在这里补账）。探测一律 `if ! x=$(…)` 或 `$(… || true)`。 + +# 架构与合规守门（与 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；M196 起两处） +# +# M118（D26）：根 Cargo.toml 已 `exclude = ["crates/app"]`（Slint 退役树）。逐条核对过本文件， +# **没有**任何一条守卫以 `--workspace` 为前提，所以排除不会让它们空转： +# ① core-no-ui / presenter-no-ui / design-zero-dep —— 「manifest 文本 + `cargo tree -p `」 +# 口径，被守的 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: + # M133：日常线 `dev` 复用**同一份**守门脚本（`.github/workflows/dev-guards.yml` 里 + # `uses: ./.github/workflows/guards.yml`）。这是**纯新增的触发方式**：上面三条与下面全部作业 + # 一字未动，main / PR / dispatch 的触发与判据与加这行之前逐字相同。 + # 为什么复用而不是复制：判据只能有一份。两份 unsafe 词法器（110 行状态机）各自演进，迟早出现 + # 「dev 绿、main 红」的双真相，那时 dev 门禁就变成了装饰品。 + workflow_call: + +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' + # 与下方 presenter / design 的 `if ! tree=$(…)` 对称：cargo tree 自己失败（改名 / 解析失败）时裸赋值会被 -e 静默杀死，只剩 exit code 1 无注解。 + if ! tree=$(cargo tree -p unlucky-core --edges normal --prefix none); then + echo "::error::cargo tree -p unlucky-core 执行失败 —— crate 是否仍叫 unlucky-core？" + exit 1 + fi + 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" + # 「零命中」本来就该是绿的正路，但裸赋值会把 grep 的 exit 1 交给 -e（见文件头）： + # M156 之前这里每次零命中都整步红且零注解 —— presenter-no-ui 自 M89 引入起从未绿过。 + hits=$(printf '%s\n' "$tree" | grep -vE '^unlucky-presenter v' | grep -iE "$forbidden" || true) + 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`（`SetLayeredWindowAttributes` 没有安全替代）。 + # M196 加了第二处：控制台附着（`AttachConsole`）同样只有 Win32 一条路。两处各自成文件， + # 判据是**集合相等**而不是「黑名单命中」： + # - 任何第三个显式放行 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/console.rs\ncrates/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 秒。 + # `git grep` 零匹配 exit 1 + pipefail → 裸赋值同样会被 -e 静默杀死（见文件头）。 + 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 || true) + 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 落点（不在期望集合里）：" + printf '%s\n' "$extra" | sed 's/^/ - /' + fi + if [ -n "$(printf '%s\n' "$EXPECTED" | grep -vxF "$actual" || true)" ]; then + echo "::error::期望集合里的落点没被扫到（放行属性被删 / 文件改名搬走？）：" + printf '%s\n' "$EXPECTED" | grep -vxF "$actual" | sed 's/^/ - /' || true + fi + echo "::error::unsafe 的 FFI 只允许住在上面的期望集合里（D36 / M196）。新的 unsafe 能力要先立 mission：改守门 + 更新定案，不要顺手放行。" + exit 1 + fi + echo "OK: 全仓显式放行 unsafe 的文件恰好等于期望集合" + + 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-build.yml b/.github/workflows/release-build.yml new file mode 100644 index 0000000..c7c0c67 --- /dev/null +++ b/.github/workflows/release-build.yml @@ -0,0 +1,400 @@ +name: Release / build（可复用） + +# Release 流水线的**构建侧**（M145 拆分：`release.yml` 与 `packaging/README.md` 都顶到 400 行红线，下一处改动必越线）。 +# M145 时本文件 = 拆分前 `.github/workflows/release.yml` 的 `build` job **逐字搬家**，改动只有四个矩阵键换成同名入参： +# `matrix.slot` → `inputs.slot`、`matrix.os` → `inputs.os`、`matrix.build_dir` → `inputs.build_dir`、 +# `matrix.rustflags` → `inputs.rustflags`。 +# **M164 改了两步**（只这两步）：① `Windows ARM64 工具链体检` → `工具链取证`（不再 exit 1，判定权交回编译器； +# 理由见该步上方的长注释）；② `cargo build` 步给 arm64 槽位显式备齐 target / `LIB`+`INCLUDE` / arm64 `link.exe`。 +# **M184 加了一步**：`linux-x64` 的 xvfb 运行时冒烟（真渲一帧 + `[theme]` / `[backend] final` 日志断言 + 像素判定）—— +# 这一档进了 `PUBLISH_SLOTS`，「发出去的包真能跑」从此由 CI 每轮证明；判据只在 `linux-x64` 槽位上跑（arm64 没有 +# 对应的运行时证据，不给它加一条没验证过的门禁）。同一轮把 arm64 的失败收尾注解按槽位分支。 +# 矩阵**仍由调用方** `release.yml` 的 `plan` job 生成并在外层展开（矩阵不能带 `if`，`strategy` 可读 `needs`）， +# 本文件只跑**单个槽位**，不持有槽位表 —— 改槽位只改 `release.yml` 里那一处。 +# `env` 必须在被调方重复声明：**被调工作流不继承调用方的 workflow 级 `env`**（CARGO_TERM_COLOR / RUST_BACKTRACE +# 都是构建产物的实参：前者只影响日志着色，后者决定 panic 是否打回溯）。 + +on: + workflow_call: + inputs: + slot: + description: "槽位键，同 plan matrix 的 slot（如 windows-x64 / linux-arm64）" + type: string + required: true + os: + description: "runner 标签，同 plan matrix 的 os（如 windows-latest / windows-11-arm）" + type: string + required: true + build_dir: + description: "产物根，同 plan matrix 的 build_dir（六槽位一律 target/release）" + type: string + required: true + rustflags: + description: "RUSTFLAGS，同 plan matrix 的 rustflags（两个 Windows 槽位为 -C target-feature=+crt-static，其余空）" + type: string + required: false + default: "" + # （M149）微软登录用的 Azure 公共客户端 id（公共客户端 id 随二进制一起分发，不按高密级处理，但**不进 git + # 文件**：真值放仓库 Secret，用户在仓库设置里录入）。`required: false` 是刻意的——调用方没传（本地、 + # 没有 runner 的镜像站、以及 Secret 尚未录入时）求值为空串，`client_id.rs` 把空白当「没配」， + # 于是非官方构建不烘 id，官方构建才烘。**调用方必须显式传**（`secrets: inherit` 或按名传）； + # 没传时这里是空，不会报错。 + secrets: + ULL_MSA_CLIENT_ID: + description: "Azure 公共客户端 id，烘进发布二进制（构建期 option_env!）；留空 = 不烘" + required: false + +env: + CARGO_TERM_COLOR: always + RUST_BACKTRACE: 1 + +# 与拆分前 build job 拿到的凭据范围一致（可复用工作流的权限只取调用方与本文件的**交集**，故两边都声明 read）。 +permissions: + contents: read + +jobs: + build: + name: build (${{ inputs.slot }}) + runs-on: ${{ inputs.os }} + permissions: + contents: read + steps: + - uses: actions/checkout@v4 + + - name: Linux 图形栈构建依赖（winit / wgpu 编译期需要） + 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 + + # （M141/M142 → **M164 判定权移交**）windows-arm64 跑在**原生** `windows-11-arm` 上。本步**只取证，不判定**： + # M141/M142 的版本用 `find` 猜 SDK 的 `um/arm64/kernel32.lib` 在不在，猜缺就 `exit 1` —— 结果 v0.2.1~v0.2.3 + # 五轮全红在**这一步**、下面 `cargo build` 一次都没跑过（第 7 步永远 skipped），"arm64 修不好"始终是探针给的 + # 结论、不是编译器给的。而它跟自己打的快照自相矛盾：v0.2.3 的注解原文是 + # `[arm64sdk] SDK Lib 版本→um 架构: 10.0.22621.0→um:[arm,arm64,x64,x86,] 10.0.26100.0→um:[arm64,x64,x86,]` + # 同一份注解里却报 `kernel32=缺失`（同一个 `find` 模式在本地合成目录树上命中，故这条路本身不可靠）。 + # M164 把红绿交回编译器与链接器：本步只打印实况（vswhere 组件查询 / 目录里 .lib **计数** / arm64 link.exe + # 路径），一条 `::error::` 都不写、永不 `exit 1`；红不红由 `cargo build` 与静态 CRT 导入表门禁决定。 + # 也不再自动补装：runner 镜像是 Windows 11 Arm64 + Visual Studio 2026（`windows-11-arm` 自 2026-09 切到 VS2026， + # VS 在 `C:\Program Files\Microsoft Visual Studio\18\Enterprise`），其镜像清单 + # （actions/runner-images 的 `images/windows/Windows11-VS2026-Arm64-Readme.md`）里 `VC.Tools.ARM64`、 + # `Windows11SDK.26100`、`Windows11SDK.22621` 三件都已装好；M142 那次 `setup.exe modify` 反倒返回非 0。 + # 注解仍每条一行（job 日志下载要 token，check-run 注解不用；多行会被拼成一行截断）。 + - name: Windows ARM64 工具链取证（只打印实况，红绿交给编译器） + if: inputs.slot == 'windows-arm64' + shell: bash + run: | + set +e; set -uo pipefail # -e 由 runner 命令行注入，只能显式关 + say() { printf '::%s::[arm64sdk] %s\n' "$1" "$2"; return 0; } + shopt -s nullglob # 计数走 glob 不走 find：find 的管道 + errexit 正是 M141 的死因 + vswhere="C:/Program Files (x86)/Microsoft Visual Studio/Installer/vswhere.exe" + [ -x "$vswhere" ] || say warning "找不到 vswhere（$vswhere）：下面会是 0 命中，那不代表工具链缺东西" + # ① 组件：用 vswhere 自己的 `-requires`（权威查询），不拿「某个文件名存在」当替身。 + for comp in Microsoft.VisualStudio.Component.VC.Tools.ARM64 \ + Microsoft.VisualStudio.Component.Windows11SDK.26100 \ + Microsoft.VisualStudio.Component.Windows11SDK.22621; do + hit="" + [ -x "$vswhere" ] && hit=$("$vswhere" -latest -products '*' -requires "$comp" -property installationPath 2>/dev/null | head -n1 || true) + if [ -n "$hit" ]; then say notice "组件 $comp: 已装（$hit）" + else say warning "组件 $comp: 未装 / 这台 VS 不认这个 id（继续看下面的实际 .lib 计数）"; fi + done + # ② 实况计数：`+crt-static` 要 VC 的 `lib/arm64/libcmt.lib`，链接要 SDK 的 `um/arm64/*.lib`。 + for root in "C:/Program Files/Microsoft Visual Studio" "C:/Program Files (x86)/Microsoft Visual Studio"; do + hits=( "$root"/*/*/VC/Tools/MSVC/*/lib/arm64/libcmt.lib ) + say notice "VC $root → lib/arm64/libcmt.lib ${#hits[@]} 个${hits[0]:+（首个 ${hits[0]}）}" + done + for root in "C:/Program Files (x86)/Windows Kits/10/Lib" "C:/Program Files/Windows Kits/10/Lib"; do + [ -d "$root" ] || { say notice "SDK $root：不存在"; continue; } + for ver in "$root"/*/; do + libs=( "$ver"um/arm64/*.lib ) + say notice "SDK $(basename "$ver") → um/arm64/*.lib ${#libs[@]} 个" + done + done + # ③ arm64 链接器候选：宿主 arm64 的优先（原生），x64 托管的次之。下面 cargo 步会显式导出它。 + for p in 'VC/Tools/MSVC/*/bin/Hostarm64/arm64/link.exe' 'VC/Tools/MSVC/*/bin/Hostx64/arm64/link.exe'; do + hit="" + [ -x "$vswhere" ] && hit=$("$vswhere" -latest -products '*' -find "$p" 2>/dev/null | head -n1 || true) + say notice "link.exe 候选 $p → ${hit:-未命中}" + done + echo "取证完毕：本步不判红；arm64 的结论只看下面的 cargo build / 链接 / 导入表门禁" + + # M118（D26）：**Slint 版停发** —— GUI 只有 `unlucky-launcher-iced`（`crates/app` 已 exclude，不进 workspace）。 + # 产物名由 make_artifacts.py 的 `asset_stem()` 生成 `<名字>_<版本号>_<平台>_<架构>`；不传 `--target`（M140 起全原生）。 + # （M149）`ULL_MSA_CLIENT_ID` 经 `option_env!` 烘进二进制（`crates/core/src/auth/microsoft/client_id.rs`）： + # 官方产物自带微软登录所需的配置，装完即可登录；运行期同名环境变量仍优先于它，可覆盖。 + # 值来自仓库 Secret（不进 git 文件）；Secret 没配时这里是空串，client_id.rs 把空白当「没配」， + # 于是非官方构建不烘 id。想自己烘一份就从源码构建：`ULL_MSA_CLIENT_ID= cargo build`。 + # （M164）arm64 槽位在编译前把工具链**显式**备齐，不再依赖「runner 反正自带」这种默契： + # ① `rustup target add aarch64-pc-windows-msvc`：宿主机本来就是 aarch64-pc-windows-msvc，这句在原生 + # runner 上是幂等 no-op；它把「缺 std」这类失败挡在编译前（缺 target 时 rustc 只会说找不到 crate std）； + # ② MSVC 的 `LIB` / `INCLUDE` 用微软自己的 `vcvarsall.bat arm64` 取（**不手搓路径**：少一个目录就是 + # LNK1181），本步 `export` 一次、同时写进 `$GITHUB_ENV` 供下游 dumpbin / 打包步； + # ③ arm64 的 `link.exe` 用 vswhere 定位后显式导出 `CARGO_TARGET_AARCH64_PC_WINDOWS_MSVC_LINKER` + # （Hostarm64 原生优先、Hostx64 次之）。**②必须先于③**：只覆盖链接器而不给 LIB，rustc 会在 + # `link.exe` 里撞 `LNK1181: cannot open input file 'kernel32.lib'`——那正是我们要定位的错误，不是要制造的错误。 + # ①②③ 全是「定位不到就打印原因继续」，不用启发式决定红绿：真缺工具链时让链接器自己报出来。 + - name: cargo build --release --locked + shell: bash + env: + RUSTFLAGS: ${{ inputs.rustflags }} + ULL_MSA_CLIENT_ID: ${{ secrets.ULL_MSA_CLIENT_ID }} + SLOT: ${{ inputs.slot }} + BUILD_DIR: ${{ inputs.build_dir }} + run: | + set -euo pipefail + echo "host=$(rustc -vV | sed -n 's/^host: //p') slot=$SLOT build_dir=$BUILD_DIR" + if [ "$SLOT" = "windows-arm64" ]; then + rustup target add aarch64-pc-windows-msvc + rustup target list --installed + vswhere="C:/Program Files (x86)/Microsoft Visual Studio/Installer/vswhere.exe" + if [ -x "$vswhere" ]; then + # ② MSVC 的 LIB/INCLUDE。**别把 vcvarsall 的路径直接塞给 `cmd //c "..."`**：MSYS 会把参数里的 + # `"` 改写成 `\"` 再交给 cmd.exe，而 cmd 的 /c 引号剥离接不住这一层，只会报 + # `'\"C:\...\vcvarsall.bat\"' 不是内部或外部命令` —— 结果 LIB/INCLUDE 全空、只剩 `set` 的空输出 + # （M164 复审实测）。故本步改为往 `$RUNNER_TEMP` 写一个 **CRLF** 的 wrapper .bat，引号留在 + # .bat 自己的 `call "..."` 里（由 cmd 解析，路径带空格也没事），`cmd //c` 只收**不含引号**的 + # 相对文件名（先 cd 进去），彻底绕开 MSYS 的引号改写。 + tmp=${RUNNER_TEMP:-${TEMP:-/tmp}} + mkdir -p "$tmp" + vcvars="" + # `-find` 是**单值**参数且官方文档给的是反斜杠形态：两种形态各试一次（与下面 dumpbin 步同规矩）， + # 只赌一种就等于再写一个「静默退化成 warning」。 + for pat in 'VC\Auxiliary\Build\vcvarsall.bat' 'VC/Auxiliary/Build/vcvarsall.bat'; do + vcvars=$("$vswhere" -latest -products '*' -find "$pat" 2>/dev/null | head -n1 || true) + [ -n "$vcvars" ] && break + done + dump="" + if [ -n "$vcvars" ]; then + # CRLF 是必须的：cmd 解析只有 LF 的 .bat 会漏行/报错。 + { printf '@echo off\r\n' + printf 'call "%s" arm64 >nul 2>&1\r\n' "${vcvars//\//\\}" + printf 'set\r\n'; } > "$tmp/ull-msvc-arm64.bat" + dump=$(cd "$tmp" && cmd //c ull-msvc-arm64.bat 2>/dev/null | tr -d '\r') || dump="" + echo "wrapper: $tmp/ull-msvc-arm64.bat ← $vcvars（set 输出 ${#dump} 字符）" + fi + for key in LIB INCLUDE; do + value=$(printf '%s\n' "$dump" | sed -n "s/^${key}=//p" | head -n1) + if [ -n "$value" ]; then + export "$key=$value" + printf '%s=%s\n' "$key" "$value" >> "$GITHUB_ENV" + echo "env $key=${value:0:90}…（${#value} 字符）" + else + echo "::warning::[arm64] 没拿到 $key（vcvarsall=${vcvars:-未定位}）：留空交给 rustc 自己探测 VS" + fi + done + found="" + for p in 'VC\Tools\MSVC\*\bin\Hostarm64\arm64\link.exe' 'VC/Tools/MSVC/*/bin/Hostarm64/arm64/link.exe' \ + 'VC\Tools\MSVC\*\bin\Hostx64\arm64\link.exe' 'VC/Tools/MSVC/*/bin/Hostx64/arm64/link.exe'; do + [ -n "$found" ] && break + hit=$("$vswhere" -latest -products '*' -find "$p" 2>/dev/null | head -n1 || true) + [ -n "$hit" ] && found=${hit//\\//} + done + if [ -n "$found" ]; then + export CARGO_TARGET_AARCH64_PC_WINDOWS_MSVC_LINKER="$found" + printf 'CARGO_TARGET_AARCH64_PC_WINDOWS_MSVC_LINKER=%s\n' "$found" >> "$GITHUB_ENV" + echo "linker: $found" + else + echo "::warning::[arm64] 没定位到 arm64 link.exe：让 rustc 自己找（真的失败时错误里会带路径）" + fi + else + echo "::warning::[arm64] 没有 vswhere：target 已加，链接器交给 rustc 自己探测" + fi + fi + cargo build --release --locked --bin unlucky-launcher-iced --bin ull + # 产物清单只给 windows-arm64 打：两档已发布的 x64（windows-x64 / linux-x64）这一步零变化，不额外给它们 + # 加失败面（linux-x64 的证据在它自己那条 xvfb 运行时冒烟步里）。 + if [ "$SLOT" = "windows-arm64" ]; then + ls -l "$BUILD_DIR"/unlucky-launcher-iced* "$BUILD_DIR"/ull* || true + fi + + # （M190）版本资源门禁：**读产物字节**，不信构建日志。`build.rs` 里写了 `CompanyName` 不等于 + # 它进了 PE——资源在链接期被丢掉、或被后处理覆盖，都只有读回来才看得见。判据（字段值、四段式 + # 版本号、FIXEDFILEINFO 的 dwFileVersion）全在 `packaging/check_pe_version.py`，本机可跑。 + # 只在 Windows 槽位跑：Linux/macOS 产物没有 PE 头，那边 `build.rs` 整段不执行（见 + # `packaging/pe_version.rs` 文件头）。**工具缺失也 fail**：找不到 python 就等于门禁失效。 + - name: PE 版本资源读回（CompanyName / ProductName / 版权 / 版本号真的在产物里） + if: runner.os == 'Windows' + shell: bash + env: + BUILD_DIR: ${{ inputs.build_dir }} + run: | + set -euo pipefail + PY=$(command -v python3 || command -v python) + if [ -z "$PY" ]; then echo "::error::找不到 python，PE 版本资源门禁无法运行（门禁不降级）"; exit 1; fi + # 版本号与 Cargo.toml **同源**：`[workspace.package] version = "x.y.z"`。 + version=$(sed -n 's/^version = "\(.*\)"/\1/p' Cargo.toml | head -n1) + echo "expect-version=$version" + "$PY" packaging/check_pe_version.py "$BUILD_DIR/unlucky-launcher-iced.exe" "$BUILD_DIR/ull.exe" --expect-version "$version" + + - name: Windows 单文件自检（导入表不得出现 VC++ 可再发行 DLL） + if: runner.os == 'Windows' + shell: bash + env: + # 校验的是**构建产物**（iced bin 原始名）；对外名 `unlucky-launcher` 由 make_artifacts.py 落盘时才换上。 + EXE: ${{ inputs.build_dir }}/unlucky-launcher-iced.exe + run: | + set -euo pipefail + # +crt-static 是否真生效只看导入表：出现 VCRUNTIME/MSVCP/msvcr/ucrtbase 就是还得装可再发行包，fail。 + # dumpbin 定位链（三级，全不命中才 fail —— 门禁不降级）：① vswhere ② find 兜底（两个 VS 根都扫）③ PATH + # （排最后是刻意的：最不可控）。dumpbin 在 MSVC 的**宿主**工具目录里：x64 runner 是 `Hostx64/x64`，arm64 + # runner（M140）是 `Hostarm64/arm64`（反向不行——x64 上挑 Hostarm64 是跑不起来的二进制）。 + pats=('VC/Tools/MSVC/*/bin/Hostx64/x64/dumpbin.exe') + if [ "${RUNNER_ARCH:-X64}" = "ARM64" ]; then + pats=('VC/Tools/MSVC/*/bin/Hostarm64/arm64/dumpbin.exe' "${pats[@]}") + fi + VSWHERE="C:/Program Files (x86)/Microsoft Visual Studio/Installer/vswhere.exe" + DUMPBIN="" + VIA="" + if [ -x "$VSWHERE" ]; then + # `-find` 是**单值**参数：一次传多个 pattern 只有一个生效（3.x 取最后一个 —— 老写法里 Hostarm64 因此永远 + # 轮不到），故每个 pattern 各起一次定位器，不赌它取哪个。反斜杠形态优先（官方文档即此形式），再试正斜杠。 + for p in "${pats[@]}"; do + for pat in "${p//\//\\}" "$p"; do + hit=$("$VSWHERE" -latest -products '*' -find "$pat" 2>/dev/null | head -n1 || true) + if [ -n "$hit" ]; then DUMPBIN=${hit//\\//}; VIA="vswhere"; break 2; fi + done + done + fi + if [ -z "$DUMPBIN" ]; then + # VS 根形如 <年>/<版次>（2022/Enterprise、2022/BuildTools……），固定层数的 glob 会踩空，按模式扫。 + find_pat=() + for p in "${pats[@]}"; do find_pat+=(-o -path "*/$p"); done + DUMPBIN=$(find "C:/Program Files/Microsoft Visual Studio" \ + "C:/Program Files (x86)/Microsoft Visual Studio" \ + -maxdepth 11 -type f \( "${find_pat[@]:1}" \) 2>/dev/null | head -n1 || true) + if [ -n "$DUMPBIN" ]; then VIA="find"; fi + fi + if [ -z "$DUMPBIN" ]; then + hit=$(command -v dumpbin || true) + if [ -n "$hit" ]; then DUMPBIN=$hit; VIA="PATH"; fi + fi + # 工具缺失同样 fail："找不到就跳过"等于让这道门禁在最需要它的时候静默失效。 + 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: PE 子系统门禁（GUI=WINDOWS_GUI/2，CLI=CONSOLE/3；判据与理由见 packaging/README.md §15） + if: runner.os == 'Windows' + shell: bash + run: | + PY=$(command -v python3 || command -v python) + "$PY" packaging/check_pe_subsystem.py --gui "${{ inputs.build_dir }}/unlucky-launcher-iced.exe" --cli "${{ inputs.build_dir }}/ull.exe" + + # （M184）linux-x64 的**运行时门禁**：这一档已进 PUBLISH_SLOTS，所以「发出去的包真能开窗渲出一帧」得由 CI 每轮证明， + # 不能只靠一次性的本机验收（证据与实测输出见 `packaging/docs/linux-evidence.md`）。 + # **只在 linux-x64 槽位上跑**：判据是按 x64 软渲染实测标定的；`linux-arm64` 上这条链一次都没验过（没有 arm64 的 + # xvfb 证据），写成无条件的 `runner.os == 'Linux'` 就等于给一个没验证过的槽位加一条会红的判据——正是 M171 那个 + # 「豁免行要单独落」的同类事故。宁可这条只在有证据的槽位上真跑。 + - name: Linux x64 运行时冒烟（xvfb 真渲一帧 + 主题/后端日志断言） + if: inputs.slot == 'linux-x64' + shell: bash + env: + BUILD_DIR: ${{ inputs.build_dir }} + run: | + set -euo pipefail + sudo apt-get update + sudo apt-get install -y --no-install-recommends xvfb xauth \ + libxkbcommon-x11-0 libx11-6 libxcursor1 libxrandr2 libxi6 libfontconfig1 fonts-dejavu-core + out="$RUNNER_TEMP/linux-smoke" + mkdir -p "$out/data" + log="$out/launcher.log" + # 退出码单独取：`tee` 之后的 `$?` 是 tee 的，管道里 cargo/launcher 的失败会被吞成 0。 + set +e + xvfb-run -a --server-args="-screen 0 1280x1024x24" \ + "$BUILD_DIR/unlucky-launcher-iced" --software-renderer \ + --screenshot "$out/linux-x64-first-frame.png" --data-dir "$out/data" 2>&1 | tee "$log" + code=${PIPESTATUS[0]} + set -e + echo "launcher exit=$code" + # 两条日志断言（两行都是**恒开**的，不依赖 ULL_ACCEPTANCE）： + # `[theme] source=…flavor=…follows_system=…` 证明主题是按预期来源定的（截图通道默认 Light）， + # `[backend] final=… result=started` 证明渲染后端真的起来了（而不是起来前就崩了）。 + grep -q '^\[theme\] source=' "$log" || { echo "::error::缺少 [theme] 行（主题来源没打印）"; exit 1; } + grep -q '^\[backend\] final=.* result=started' "$log" || { echo "::error::缺少 [backend] final=… result=started（渲染后端没起来）"; exit 1; } + python3 packaging/check_screenshot.py "$out/linux-x64-first-frame.png" --json + ls -l "$out" + exit "$code" + + - name: 上传 Linux x64 首帧图（失败也传，人眼复核用） + if: always() && inputs.slot == 'linux-x64' + uses: actions/upload-artifact@v4 + with: + name: linux-x64-first-frame + path: ${{ runner.temp }}/linux-smoke/ + if-no-files-found: warn + + - name: 打包（产物 + SHA256SUMS） + shell: bash + env: + # 不把 `${{ }}` 直接拼进 bash 脚本：git ref 名允许 `$`/反引号/`"`，一律经 env 传入再展开。 + REF_TYPE: ${{ github.ref_type }} + TAG: ${{ github.ref_name }} + SLOT: ${{ inputs.slot }} + BUILD_DIR: ${{ inputs.build_dir }} + run: | + set -euo pipefail + # git-bash 与 Linux/macOS runner 的 python 入口名不一致，先探一遍。 + PY=$(command -v python3 || command -v python) + # 槽位与产物根都从矩阵来（M140 起六个槽位都是 target/release），脚本据此定位产物并回读 + # 可执行文件头校验架构：arm64 槽位现在是**真跑** `ull --version`，「宿主≠产物就跳过」只留给本地交叉。 + 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-${{ inputs.slot }} + path: dist + if-no-files-found: error + retention-days: 14 + + # （M142/M164）arm64 若红在别的步骤（cargo / 链接 / 打包 / 导入表门禁），也要有一条注解说清「红在哪」和 + # 「不挡发布」——只剩一句 `Process completed with exit code 1.` 的教训见上面那条体检步骤。 + # M164 起本槽位的红**只可能来自真实构建链路**（体检已降级为取证、永不 exit 1），所以这条注解同时也是 + # 「arm64 到底能不能编出来」的答案所在：红了就把上面的编译器/链接器原文当根因，别再回去改体检。 + # M184：Linux arm64 进来（它现在是 `mode: ci`，tag 推送默认就编），措辞按槽位分支 —— 两个 arm64 都**不在**发布名单里， + # 但理由不同：windows-arm64 等「能不能出 PE」的答案，linux-arm64 等「真机跑不跑得起来」的答案。 + - name: arm64 失败收尾注解（红不挡发布） + if: failure() && (inputs.slot == 'windows-arm64' || inputs.slot == 'linux-arm64') + shell: bash + env: + SLOT: ${{ inputs.slot }} + run: | + set -euo pipefail + if [ "$SLOT" = "linux-arm64" ]; then + reason="本槽位只有构建证据、运行时完全未验（没有 ARM64 真机跑过一帧）" + else + reason="失败步骤见本 job 的步骤名（M164 起只会是 cargo build / 链接 / 导入表门禁 / 打包，体检步不再判红）" + fi + echo "::error::[$SLOT] 本槽位已红：$reason。PUBLISH_SLOTS 当前是 windows-x64 + linux-x64 ⇒ 本次 Release 仍照发那两档，$SLOT 的产物不进 Release" diff --git a/.github/workflows/release-guard.yml b/.github/workflows/release-guard.yml new file mode 100644 index 0000000..5669e01 --- /dev/null +++ b/.github/workflows/release-guard.yml @@ -0,0 +1,94 @@ +name: Release guard + +# 发布标记语义守门（M163）：**push tag 默认创建稳定版**这条不许只靠注释保证。 +# +# 判据全部在 `packaging/check_release_semantics.py`，它做四件事： +# ① 标记表：push tag（空串）的 create **不含** --prerelease；dispatch true ⇒ 预发布； +# dispatch false ⇒ create 稳定、edit 显式摘标记；非法取值必须抛。 +# ② 真 bash 往返：把 `packaging/release_marker.py --emit-bash` 的产物 source 进 bash， +# 读回 create_mark / edit_mark 两个数组——证明流水线**真跑的那段代码**对，不只是函数对。 +# ③ release-publish.yml 的可执行内容里没有 --prerelease 字面量：标记只能从那张表来。 +# ④ release.yml 的 dispatch 默认值 == false（读 YAML 结构，不是 grep 字符串）。 +# 最后一步 `--self-mutation` 是这条守门自己的变异自测：把「默认值改回 true」「塞回字面量」 +# 「表里 push 分支改成预发布」逐项注入临时副本，断言守门**每一项都红**、基线绿。守门自己 +# 抓不住回归时它会先红，所以这条断言不会变成装饰品。 +# +# 为什么不并进 guards.yml：那份文件已经 398 行（400 行红线），再挂一个 job 必越线。 +# 改 `release.yml` 的 prerelease 输入 / 改那段 `gh release` 时，先跑 +# `python3 packaging/check_release_semantics.py`（本机可用 `python`，脚本会自己找 bash）。 +# +# （M164）同一个 job 还挂**发布名单守卫** `packaging/check_publish_slots.py`：`PUBLISH_SLOTS` 与槽位表/产物 +# 必须对得上。PR 阶段跑源码级断言（名单非空、每项都是 `release.yml` 槽位表里的 `mode: ci` 档）—— +# 名单里写错一个字此前只会表现为「Release 侧一个也不匹配、齐全性检查红在别处」，根因要翻两层日志； +# `--self-test` 再注入 11 条回归（缺资产 / 拼错 / 声明了 probe 档 / 名单声明了没产物 / 有产物没声明 / +# `mode: ci` 却没产物 / 声明的 `linux-x64` 构建红了必须拦住发布 / 提前把 `linux-arm64` 写进名单必须红）证明它会红。 +# 发布侧那道「产物 ⇄ 名单」的运行时断言在 `release-publish.yml`（同一份脚本，`--dist`）。 +# +# （M169）同一个 job 再挂**测试通道守门** `packaging/check_test_source_off.py`：core/cli/presenter/ +# app-iced 各有一条 `update-test-source` feature，打开后 `core::update::job::default_source` 可以被 +# 两个环境变量指向任意本地目录——而更新链路的终点是**替换用户盘上的 exe**。它默认关，官方发布产物 +# 里不许有它：守门扫 `.github/workflows/**`（含复合 action）、`packaging/**` 递归脚本、 +# `Makefile`/`justfile`/`Taskfile`、各 `Cargo.toml`（`default` 里带上它也红）与 `.cargo/config*.toml` +# （`--cfg feature="…"` 与 `rustc-wrapper` 都能绕过 `--features`）。**唯一允许**是 `ci.yml` 里名为 +# `update-e2e` 的那一步（且必须带 `--test update_e2e_test`，文件名/步骤名/参数任一不符即红）。 +# `--self-test` 注入 26 条真实回归 + 6 条防误杀/放行用例（另加基线；条数以 `--self-test` 输出为准）， +# 该红的红、该绿的绿。 + +on: + push: + branches: [main] + pull_request: + workflow_dispatch: + +permissions: + contents: read + +jobs: + release-semantics: + name: 发布标记语义守门（push tag → 稳定版） + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: 标记表自检（push tag ⇒ 稳定版） + run: python3 packaging/release_marker.py --self-test + - name: 语义断言（标记表 / bash 往返 / 流水线只用表 / dispatch 默认值） + run: python3 packaging/check_release_semantics.py + - name: 变异自测（守门抓不抓得住回归） + run: python3 packaging/check_release_semantics.py --self-mutation + - name: 发布名单守卫自测（声明⇒必须有产物 / 有产物没声明⇒显式警告） + run: python3 packaging/check_publish_slots.py --self-test + - name: 发布名单与矩阵槽位一致（拼错字 / 声明了 probe 档 当场红） + run: python3 packaging/check_publish_slots.py + # M169：`update-test-source` 这条 feature 能让更新源指向任意本地目录，而更新链路的终点是 + # 替换用户盘上的 exe。它**默认关**、官方发布产物里不许有它，这条由脚本自动断言（不再靠注释）： + # 扫 `.github/workflows/**`（含复合 action）、`packaging/**` 递归脚本、`Makefile`/`justfile`/ + # `Taskfile` 与各 `Cargo.toml`；归属按 `jobs.*.steps[]` 的**列表项**判，落不到具名步骤的行一律红。 + # 唯一允许：本仓 `ci.yml` 里名为 `update-e2e` 的那一步（且必须带 `--test update_e2e_test`）。 + - name: 测试通道守门自测（注入变异，该红的红、该绿的绿） + run: python3 packaging/check_test_source_off.py --self-test + - name: 发布产物不含测试通道（workflow / 打包脚本 / Cargo default 都不许开） + run: python3 packaging/check_test_source_off.py + # M190：签名脚本与 PE 版本资源门禁自己的自检。前者验 RFC 8032 向量（Ed25519 实现错了就发不出 + # 能被验过的签名），后者把「口径表 ⇄ pe_version.rs」「四段式版本号换算」对拍，并造一个没有版本 + # 资源的假 PE 断言判据**会红**（否则那道门禁对任何输入都绿，等于没有）。 + - name: 清单签名脚本自检（RFC 8032 向量 + 信任表标记解析） + run: python3 packaging/sign_manifest.py --self-test + - name: PE 版本资源判据自检（口径表对拍 + 假 PE 必红） + run: python3 packaging/check_pe_version.py --self-test + # M190 r1 复审 P1-1：`.github/workflows/release-build.yml` 的 sed 替换串里混进过一枚裸 0x01 + # （本意是 `\1`）。GitHub 解析这种文件会直接失败 ⇒ **整个 run 起不来**，而所有文本扫描型守卫 + # 都看不见它（它们把 workflow 读成文本）。这条用**真 YAML 解析器** parse 全部 workflow， + # 外加一条「C0 控制字符」字节判据（两种失败模式各自独立报 `::error file=…,line=…`）。 + # PyYAML 在 GitHub runner 上自带；万一缺失，脚本自己装一次，仍失败则红（门禁不降级）。 + - name: workflow YAML 自检（注入 0x01 / 坏结构必须红） + run: python3 packaging/check_workflows_yaml.py --self-test + - name: workflow 全部可被真 YAML 解析器 parse（无裸控制字符） + run: python3 packaging/check_workflows_yaml.py + # M190 r3：`update-test-key` 是**信任锚的开关**（把公开的测试公钥并进信任表）。它只许由 + # `crates/presenter` 的 `[dev-dependencies]` 打开；进了发布构建就等于「谁都能签出官方更新」。 + # 判据：core 的 `Cargo.toml` 只许自己的声明、presenter 只许 `[dev-dependencies]` 段内、 + # 其余（workflow / packaging 脚本 / 根 Cargo.toml / cargo 配置）出现即红。 + - name: 测试公钥守门自检（注入 workflow / dependencies / 根 Cargo.toml 三处变异） + run: python3 packaging/check_test_key_off.py --self-test + - name: 测试公钥不进发布构建（只许 presenter 的 dev-dependencies） + run: python3 packaging/check_test_key_off.py diff --git a/.github/workflows/release-publish.yml b/.github/workflows/release-publish.yml new file mode 100644 index 0000000..7585c2f --- /dev/null +++ b/.github/workflows/release-publish.yml @@ -0,0 +1,221 @@ +name: Release / publish（可复用） + +# Release 流水线的**发布侧**（M145 拆分：`release.yml` 顶到 400 行红线）。本文件 = 拆分前 `release.yml` 的 `release` +# job **逐字搬家**：裁剪白名单外的槽位产物、重算全量 `SHA256SUMS.txt`、渲染 `packaging/release-notes.md` 模板、 +# `gh release create/edit` 的同 tag 幂等，全部照旧。留在调用方 `release.yml` 的只有三件事：`needs: build`、 +# tag 门禁 `if: always() && !cancelled() && github.ref_type == 'tag'`、以及 `permissions: contents: write` 的授予。 +# **M164 新增一步**（其余仍照旧）：下载 artifact 之后、裁剪之前的「发布名单守卫」`packaging/check_publish_slots.py` +# —— 原来那份「名单内少一档就 fail」的内联循环搬进那个脚本，并补上反方向（有产物没声明 ⇒ `::warning::` 未发布）。 +# 与拆分前的三处等价改写（都只涉及"从哪里读"，不涉及行为）： +# ① `secrets.GITHUB_TOKEN` → 本文件声明的入参 secret `PUBLISH_TOKEN`（调用方透传 `secrets.GITHUB_TOKEN`）。 +# 可复用工作流**拿不到**调用方未显式传入的 secret，写 `secrets.GITHUB_TOKEN` 会静默为空 → gh 401。 +# ② `inputs.prerelease`（原为 `workflow_dispatch` 的输入）→ `github.event.inputs.prerelease`（**字符串**形态的同一个 +# 值：`push` 触发时不存在 ⇒ 空串，dispatch 时是 `"true"`/`"false"`）。**三种取值各自创建什么**（M163）由 +# `packaging/release_marker.py` 一张表定义：空串 ⇒ 新建稳定版、edit 不碰标记；`true` ⇒ 新建成预发布； +# `false` ⇒ 新建稳定版、edit 显式摘掉标记。本文件把那两个数组 `source` 出来用，自己**不写** case； +# `packaging/check_release_semantics.py` 断言「本文件的可执行内容里没有 --prerelease 字面量」。 +# 为什么不用 `workflow_call` 入参转一道：dispatch 的 `inputs.prerelease` 是 +# **boolean**，而「空值 vs true/false」这条三态语义只有字符串能表达 —— 布尔入参无法取空，硬塞进字符串入参则是 +# 类型不符（`uses` 的 `with:` 会按被调方声明的类型校验；actionlint 当场报 `bool value cannot be assigned`）。 +# 取 event 上的字符串形态既保住三态，又不需要任何类型转换。 +# ③ `PUBLISH_SLOTS` / `runs-on` / `permissions` 的**内容**未动，只是被调方必须自己声明（被调方不继承调用方的 +# workflow 级 `env`；权限取调用方与本文件的交集 —— 两边都声明 `contents: write` 才拿得到写权）。 + +on: + workflow_call: + secrets: + PUBLISH_TOKEN: + description: "调用方透传 `secrets.GITHUB_TOKEN`（本 job 已声明 contents: write，`gh release` 用它发版）" + required: true + # （M190 r1 复审 P1-2）**必须在这里声明**：可复用工作流只拿得到自己声明过的 secret，调用方 + # `release.yml` 按名传了这一个，若被调方不声明，它要么在调用处报错、要么静默求值为空串—— + # 两种结局都是「用户已把钥录进 Secret，发布仍在签名步红，而错误文案反过来指控 Secret 没配」。 + # `required: false` 是刻意的：缺省为空串，由签名步的 `::error::` + `exit 1` 做 fail-closed + # （与 `release-build.yml` 的 `ULL_MSA_CLIENT_ID` 同一模式），失败信息才和事实一致。 + ULL_MANIFEST_SIGNING_KEY: + description: "清单签名私钥（JSON：key_id + seed_hex）；未配置时签名步 fail-closed、不出 Release" + required: false + +# 权限取交集：调用方 release.yml 的 release job 与本文件都声明 contents: write，交集才是 write（不声明则被收窄成 read）。 +permissions: + contents: write + +jobs: + release: + name: GitHub Release + runs-on: ubuntu-latest + permissions: + contents: write + env: + # ── 发布白名单：唯一决定「哪几个槽位进 Release」的开关（空格分隔，键同 matrix.slot）── + # **M184 起是 `windows-x64` + `linux-x64`**：`linux-x64` 已真机验过 —— release 产物在 Linux 真机（WSLg 真窗口） + # 渲出一帧、主题/后端日志齐全，并有一条同槽位的 xvfb 运行时门禁常驻在 `release-build.yml`（证据与实测输出见 + # `packaging/docs/linux-evidence.md`）。进名单的代价是「每轮发版都得真出这个包」：齐全性检查是「名单内少一档就 fail」， + # 所以这条名单同时也是「linux-x64 构建红了就挡住整次发布」的闸 —— 与任务要求一致（声明为 ci 就得真能出包）。 + # **`linux-arm64` 不在名单里，且这一轮刻意不放**：它只有构建证据，运行时完全没有证据（没有 ARM64 真机跑过一帧， + # 也没有 arm64 的 xvfb 冒烟）。解锁条件 = arm64 真机（或原生 runner）上真跑出一帧 + 主题日志 → 再把键加进这一行。 + # 只加进矩阵不加进名单时，它的产物会被下面的裁剪步删掉，但守卫会先打 `::warning::` 明说「未发布、会被裁掉」， + # 不是静默丢弃（这条是任务里点名要验的反方向）。 + # `windows-arm64` 同理仍不在名单（M142/M164：它的五轮红全红在误判的体检步，判定权已交回编译器，等下一 tag 的 CI 证）。 + # **可逆，且只是一行**：真出包之后把键加进这一行（`"windows-x64 linux-x64 <新键>"`），齐全性检查与 SHA256SUMS + # 自动跟着扩，再同步 README §1/§9 与 release-notes.md 两张表。 + # 判据不再靠注释保证：`packaging/check_publish_slots.py`（下面第二个 step 跑它；PR 阶段由 release-guard.yml + # 跑同一份脚本）两个方向都查——声明了缺产物 ⇒ `::error::` + exit 1；有产物但没声明 ⇒ `::warning::` 明说未发布。 + # macOS 两档仍未验证，默认连构建都不跑（M139）。 + PUBLISH_SLOTS: "windows-x64 linux-x64" + steps: + - uses: actions/checkout@v4 + + - uses: actions/download-artifact@v4 + with: + path: dist + merge-multiple: true + + # （M164）发布名单守卫：**声明了就必须有产物**（名单内某个槽位缺 GUI 或 CLI 就红，少一档不发版）， + # 反方向的「产物在、名单没声明」则打 `::warning::` 明说未发布 —— M142 之后那个方向是**静默**的（裁剪步只 + # echo 一行 `drop:`，没有注解、也没有非零退出），一个真编出来的 arm64 会被就地 `rm` 掉而没人知道。 + # 判据全在 `packaging/check_publish_slots.py`：同一份代码本地可跑，`--self-test` 注入 11 条回归断言该红的红。 + # 它跑在**裁剪前**的全量集上（裁剪只删名单外的文件），所以是原来「裁剪后再查」那次检查的严格超集。 + - name: 发布名单守卫（声明 ⇒ 必须有产物；有产物没声明 ⇒ 显式未发布） + shell: bash + run: | + set -euo pipefail + python3 packaging/check_publish_slots.py --dist dist --slots "$PUBLISH_SLOTS" + + - name: 裁掉白名单外的槽位产物（构建取证 ≠ 发布） + shell: bash + run: | + set -euo pipefail + # 槽位键 `windows-x64` 落到文件名是 `windows_x64`（asset_stem），故取文件名里的「平台_架构」两段比白名单。 + keep=" " + for slot in $PUBLISH_SLOTS; do keep+="${slot//-/_} "; done + for f in dist/*; do + base=${f##*/} + [ "$base" = "SHA256SUMS.txt" ] && continue + platform_arch=${base%.exe}; platform_arch=${platform_arch%.tar.gz}; platform_arch=${platform_arch#*_*_} + case "$keep" in + *" $platform_arch "*) + echo "publish: $base" + ;; + *) + echo "drop: $base（$platform_arch 不在发布白名单：macOS 两档未构建验证 / 两个 arm64 槽位待真机跑一帧；仍留在 dist- artifact 里取证）" + rm -f "$f" + ;; + esac + done + + - name: 重算全量 SHA256SUMS + shell: bash + run: | + set -euo pipefail + ls -l dist + # 齐全性（名单内每个槽位 GUI 与 CLI 都要在）**已由上上步的「发布名单守卫」断言**，且那一步看的是裁剪前的 + # 全量集 —— 同一套规则只留一份实现，免得两处判据漂开。这里只负责重算摘要：各槽位各写一份 SHA256SUMS.txt， + # 合并后只有一份是真的，故在 Release 侧按已发布的资产重算。 + cd dist + rm -f SHA256SUMS.txt + sha256sum unlucky-launcher_* ull_* > SHA256SUMS.txt + sha256sum -c SHA256SUMS.txt + cat SHA256SUMS.txt + + - name: 生成更新清单 manifest.json（D50：固定名挂 Release 资产） + shell: bash + env: + TAG: ${{ github.ref_name }} + RELEASE_BASE: ${{ github.server_url }}/${{ github.repository }}/releases/download + run: | + set -euo pipefail + # 先自验再产文件：golden 对拍 + 「DTO 严格解析」镜像（未知字段 / 摘要长度 / size=0 / 版本重复 + # 这些在发布步当场炸，而不是变成用户机器上的「查不到更新」）。零第三方依赖，毫秒级。 + python3 packaging/make_manifest.py --self-test + # 事实来源是上一步**重算**出来的 dist/SHA256SUMS.txt：清单不另算一份摘要，两者不可能不一致。 + # url 钉死 tag（不是 latest）：清单里每条都指向与它自报版本相符的字节。 + # min_supported / notes 刻意先不写：前者是「收回老版本支持」的发布策略（未拍板，写错会强制升级）， + # 后者在 Release 正文里已有，两处各写一份迟早漂。 + python3 packaging/make_manifest.py \ + --dist dist \ + --version "$TAG" \ + --channel stable \ + --asset-base-url "$RELEASE_BASE/$TAG" \ + --released-at "$(date -u +%Y-%m-%dT%H:%M:%SZ)" + + # （M190）清单签名：**签不上就不发版**。私钥只从仓库 Secret `ULL_MANIFEST_SIGNING_KEY` 进环境变量， + # 本步 `set +x` 且只回显**公钥**（日志里永远不出现私钥）。四条命令任一非零 ⇒ 本步红 ⇒ 不出 Release： + # ① `--self-test`：RFC 8032 向量（签名脚本自己没坏） + # ② `--check-pinned-keyring`：Secret 里的钥**必须**已在 `crates/core/src/update/trust.rs` 钉住 + # （签出一份客户端不认的清单，比不发版更糟） + # ③ `--sign`：签的就是上一步落盘的 `dist/manifest.json` 原始字节，产出 `dist/manifest.json.sig` + # 红了的处置见 `packaging/docs/signing.md` §4 那张表（缺什么、怎么补，都写在脚本的 stderr 里）。 + - name: 签更新清单（Ed25519；签不上就阻断发布） + shell: bash + env: + ULL_MANIFEST_SIGNING_KEY: ${{ secrets.ULL_MANIFEST_SIGNING_KEY }} + run: | + set -euo pipefail + set +x + PY=$(command -v python3 || command -v python) + if [ -z "$PY" ]; then echo "::error::找不到 python，签名步骤无法运行（签名门禁不降级）"; exit 1; fi + "$PY" packaging/sign_manifest.py --self-test + if [ -z "${ULL_MANIFEST_SIGNING_KEY:-}" ]; then + echo "::error::仓库 Secret ULL_MANIFEST_SIGNING_KEY 没配（或为空）：没有签名私钥就不发版。" + echo "::error::补法见 packaging/docs/signing.md §3：python3 packaging/sign_manifest.py --generate-key，把打印的 JSON 贴进 Secret、把 PinnedKey 那行贴进 crates/core/src/update/trust.rs" + exit 1 + fi + "$PY" packaging/sign_manifest.py --check-pinned-keyring + "$PY" packaging/sign_manifest.py --sign dist/manifest.json + # ④ 产出后**用 trust.rs 里钉住的公钥回验一遍**：复现「客户端会怎么判」，而不是信签名脚本 + # 自己那句「签好了」。私钥不需要参与，所以这一步跑在同一个环境里也不多一个泄露面。 + "$PY" packaging/sign_manifest.py --verify-pinned dist/manifest.json + ls -l dist/manifest.json dist/manifest.json.sig + + - 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.PUBLISH_TOKEN }} + TAG: ${{ github.ref_name }} + PRERELEASE: ${{ github.event.inputs.prerelease }} + shell: bash + run: | + set -euo pipefail + base_flags=(--title "Unlucky Launcher $TAG" --notes-file release-body.md) + # ── 预发布标记：判据只在 packaging/release_marker.py（M163），本文件不写 case ── + # 三种触发各自创建什么（那张表是唯一真相源）： + # push tag（PRERELEASE 为空） → create 不带标记（**稳定版**）、edit 不碰标记 + # dispatch prerelease=true → create / edit 都带预发布标记 + # dispatch prerelease=false → create 不带标记、edit 显式摘掉预发布标记 + # 空值必须是稳定版：GitHub 的 releases/latest 只指向**非 prerelease** 的最新 Release，而 + # 自更新清单固定取 `releases/latest/download/manifest.json`（D50）—— push tag 打成预发布， + # 更新通道就是 404（v0.2.2 至今如此，M163 修的就是这条；v0.2.2 那个 Release 保留为历史预发布）。 + # 先落文件再 source，不用 `source <(...)`：非法的 prerelease 取值要让这一步当场红， + # 进程替换里的失败会被 `set -e` 吞掉。 + marks=/tmp/release-marks.sh + python3 packaging/release_marker.py --emit-bash --prerelease "${PRERELEASE:-}" > "$marks" + source "$marks" + echo "create_mark=(${create_mark[*]:-}) edit_mark=(${edit_mark[*]:-})" + # Windows 单 exe 装不下 LICENSE/NOTICE/README.md，故三份与产物并列挂 Release（条款随包）；`ull` 是独立资产。 + # manifest.json 是更新清单（D50）：固定文件名，客户端问 `releases/latest/download/manifest.json`。 + # `manifest.json.sig` 必须与清单一起上传：客户端取清单后取它旁边的签名（`GitHubReleaseSource` + # 拼的地址是 `<产物根>/manifest.json.sig`），漏传等于让所有人都验签失败（M190）。 + assets=(dist/unlucky-launcher_* dist/ull_* dist/manifest.json dist/manifest.json.sig 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/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..03ceff7 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,155 @@ +name: Release + +# 发布流水线：tag `v*` → **默认构建四个槽位**（原生 `windows-latest` / `windows-11-arm` / `ubuntu-22.04` / +# `ubuntu-22.04-arm`）→ 单文件产物 + SHA256SUMS → artifact + GitHub Release。**push tag 默认创建稳定版**（M163：不带 +# `--prerelease`，否则 `releases/latest` 永远 404、自更新通道取不到清单）；同 tag 重跑幂等（覆盖资产与说明、不 create、 +# 不碰标记）。 +# **构建 ≠ 发布**：只有 `PUBLISH_SLOTS` 里的槽位才进 Release 与 SHA256SUMS ——**M184 起是 `windows-x64` + `linux-x64`**。 +# `linux-x64` 本轮翻牌的依据在 `packaging/docs/linux-evidence.md`：x86_64 槽位在 `ubuntu-22.04`（glibc 2.35，与本地 +# WSLg 验证同一地板）真编出 release 产物、真开窗渲出一帧，`release-build.yml` 里还有一条同槽位的 xvfb 运行时门禁 +# ——「声明为 ci 就必须真能跑出帧」，不是「矩阵里写了就算支持」。 +# **`linux-arm64` 本轮只构建、不发布**：它没有任何运行时证据（没有 ARM64 真机跑过一帧，也没有 arm64 的 xvfb 冒烟）。 +# 解锁条件写在 `packaging/release-notes.md` 与 `packaging/docs/compliance-support-boundaries.md` §9 ——真机跑一帧之后 +# 才把键加进 `PUBLISH_SLOTS`，不拿没跑过的包去发（M184 tower 裁决）。 +# `windows-arm64` 仍留矩阵里取证、红了不挡 x64 发布（M142/M164：它那五轮红全红在一个误判的编译前体检步，该门禁已拆， +# 判定权交回编译器）。`macos-*` 两档从未验证，默认连构建都不跑（M139：省配额、不留红叉）；整表六槽位取证走 +# `gh workflow run release.yml -f all_slots=true`（槽位表在 `plan`）。 +# 名单 ⇄ 产物两个方向都有守卫（M164）：`packaging/check_publish_slots.py`（PR 阶段在 release-guard.yml，发布侧在 +# release-publish.yml 的 `--dist` 模式）——声明了缺产物 ⇒ 红；有产物没声明 ⇒ `::warning::` 明说未发布。 +# 契约唯一真相源 packaging/README.md，打包本体 packaging/make_artifacts.py（本地与 CI 同一份脚本）。`inputs.prerelease` +# 只在 **tag ref** 上 dispatch 才可达（跑 tag 得 `gh workflow run release.yml --ref v0.2.1`）；分支 ref 的 dispatch 与 +# push 一样被 release job 的 `if: github.ref_type == 'tag'` 挡在发布之外。 +# +# M145 拆分（本文件与 packaging/README.md 都已顶到 400 行红线，下一处改动必越线）：本文件只留**触发 + 槽位表 + 编排**， +# 两个 job 的实体各搬一份可复用工作流（`workflow_call`），步骤逐字未改： +# - `.github/workflows/release-build.yml` = 原 `build` job 全流程（Linux 依赖 / arm64 工具链取证（M164 起只取证）/ +# cargo build / 静态 CRT 导入表门禁 / 打包 / 归档自检 / 上传 artifact / arm64 收尾注解），矩阵键换成同名 `inputs.*`。 +# - `.github/workflows/release-publish.yml` = 原 `release` job 全流程（`PUBLISH_SLOTS` 白名单 / 裁剪 / 重算 +# SHA256SUMS / 渲染说明 / `gh release` 幂等），`secrets.GITHUB_TOKEN` 改为显式透传的 secret。 +# （M164 在裁剪前插了一步「发布名单守卫」：主线 7 步，本分支 8 步。） +# `on` / `env` / `permissions` / `concurrency` 与 `plan` 的槽位表**一字未动**。 + +on: + push: + tags: + - "v*" + workflow_dispatch: + inputs: + all_slots: + description: "构建全部六个槽位（含未验证的 macOS 两档）；默认只跑四个（Windows 两档 + Linux 两档）" + type: boolean + default: false + prerelease: + # 默认 false（M163）：这是「新建 / 改写 Release 打不打预发布」的唯一开关，默认值必须落在稳定版上—— + # Actions 页面点一次 "Run workflow" 就是这条默认值在决定新版本进不进稳定通道。 + # 三种触发各自创建什么由 packaging/release_marker.py 一张表定义，守门在 + # packaging/check_release_semantics.py（`.github/workflows/release-guard.yml` 跑它）。 + description: "标记为 pre-release（默认 false = 稳定版；仅在 tag ref 上 dispatch 时才生效）" + type: boolean + default: false + +env: + CARGO_TERM_COLOR: always + RUST_BACKTRACE: 1 + +permissions: + contents: read + +concurrency: + group: release-${{ github.ref }} + cancel-in-progress: false + +jobs: + # M139：矩阵不写死在 `build` 里，改由本 job 按 `inputs.all_slots` 生成 —— 矩阵不能带 `if`，而 `jobs..strategy` + # 可读 `needs`，故用 `fromJSON(needs.plan.outputs.matrix)`。**槽位表只在下面这一处**，改槽位只改这里。 + plan: + name: 选槽位（默认四个：Windows 两档 + Linux 两档） + runs-on: ubuntu-latest + outputs: + matrix: ${{ steps.pick.outputs.matrix }} + steps: + - name: 生成 build 矩阵（`all_slots=true` 才整表六槽位） + id: pick + shell: bash + env: + ALL_SLOTS: ${{ inputs.all_slots }} + run: | + set -euo pipefail + python3 - "$ALL_SLOTS" >> "$GITHUB_OUTPUT" <<'PY' + import json, sys + # 槽位表（唯一真相源）。mode："ci" = 默认在 CI 里构建；"probe" = 未验证，仅 all_slots=true 时构建。 + # **没有交叉槽位**（M140）：每槽在自己的架构上原生构建，故无 `target` 键、产物一律在 target/release。 + # 要加回交叉槽位：`target` 键 + `build_dir=target//release` + `rustup target add` 与 cargo 的 `--target`。 + SLOTS = [ + # Windows x64：MSVC + 静态 CRT（+crt-static）→ exe 不依赖 VC++ 可再发行包，双击即用的单文件。 + dict(slot="windows-x64", os="windows-latest", build_dir="target/release", rustflags="-C target-feature=+crt-static", mode="ci"), + # Windows arm64：**原生** `windows-11-arm`（4C/16G，公开仓库免费）。该标签自 2026-09 起是 + # **Windows 11 Arm64 + Visual Studio 2026** 镜像（VS 在 `C:\Program Files\Microsoft Visual Studio\18`）， + # 镜像清单里 `VC.Tools.ARM64` 与 `Windows11SDK.22621/26100` 都装好了。M140 前是在 windows-latest 上交叉； + # v0.2.1~v0.2.3 的红全红在 M141/M142 那个**编译前体检**步（cargo 永远 skipped），M164 已把它降级为只取证。 + # 原生还让 `ull --version` 冒烟真跑，dumpbin 走 Hostarm64 分支。 + dict(slot="windows-arm64", os="windows-11-arm", build_dir="target/release", + rustflags="-C target-feature=+crt-static", mode="ci"), + # ↓ Linux 两档（M184）：**都改为 `mode: ci`** —— tag 推送默认就编，不再只在 `all_slots=true` 的取证跑里出现。 + # Linux 固定 22.04 而非 latest：否则 glibc 地板跟着 runner 漂移（22.04 = glibc 2.35，与本地 WSLg 验证同一地板）。 + # 两档的差别只在「有没有运行时证据」，而这件事由 `PUBLISH_SLOTS`（发布侧那一行）决定，不在这里： + # `linux-x64` 已真机验过（release 产物在 WSLg 真窗口渲出一帧 + 同槽位的 xvfb 门禁，证据见 + # `packaging/docs/linux-evidence.md`）⇒ 进名单；`linux-arm64` 只有构建、**运行时完全未验**（没有 arm64 真机 + # 跑过一帧）⇒ 不进名单，产物照出 artifact 供取证，靠 `check_publish_slots.py` 打 `::warning::` 明说未发布。 + # **别把 arm64 直接加进名单**：解锁条件是真机跑一帧，不是「构建绿了」。 + dict(slot="linux-x64", os="ubuntu-22.04", build_dir="target/release", rustflags="", mode="ci"), + dict(slot="linux-arm64", os="ubuntu-22.04-arm", build_dir="target/release", rustflags="", mode="ci"), + # ↓ 两档 macOS **未验证，不纳入 CI**：从未真构建成功、也没在真机跑过，默认一个都不编；`all_slots=true` 时照编 + # （将来验证 macOS 的唯一入口，别删）。真机验过后：mode 改 "ci" + 键加进 PUBLISH_SLOTS + + # 同步 README §1/§9 与 release-notes.md。 + # macOS：latest = arm64；Intel x64 用 macos-15-intel（macos-13 已下线）。 + dict(slot="macos-arm64", os="macos-latest", build_dir="target/release", rustflags="", mode="probe"), + dict(slot="macos-x64", os="macos-15-intel", build_dir="target/release", rustflags="", mode="probe"), + ] + keep = [s for s in SLOTS if s["mode"] == "ci" or sys.argv[1] == "true"] + print("matrix=" + json.dumps({"include": keep}, separators=(",", ":"))) + print("本次构建槽位：" + " ".join(s["slot"] for s in keep), file=sys.stderr) + PY + + # 构建实体在 release-build.yml（`workflow_call`）。矩阵仍由上面 `plan` 生成、**在外层展开**：`strategy.matrix` + # 必须在调用侧求值（被调方只按单个槽位的四个入参跑），所以 `matrix.*` 只出现在这个 job 的 `with:` 里。 + build: + name: build (${{ matrix.slot }}) + needs: plan + strategy: + fail-fast: false + matrix: ${{ fromJSON(needs.plan.outputs.matrix) }} + # 可复用工作流的权限只取「调用方 ∩ 被调方」，且不继承调用方的 `env`：两边都声明 read（与原 build job 一致）。 + permissions: + contents: read + uses: ./.github/workflows/release-build.yml + with: + slot: ${{ matrix.slot }} + os: ${{ matrix.os }} + build_dir: ${{ matrix.build_dir }} + rustflags: ${{ matrix.rustflags }} + secrets: + # （M149）微软登录的公共客户端 id：值来自仓库 Secret，被调方把它烘进发布二进制（`option_env!` 注入）。 + # 可复用工作流拿不到调用方未显式传入的 secret，故必须按名传（与下面 PUBLISH_TOKEN 同一模式， + # 不用 `inherit`：那会把仓库全部 secret 一起透进被调方）。Secret 未录入时求值为空串，被调方把空白 + # 当「没配」——产物只是不带 id，不会拿空 id 去联网。 + ULL_MSA_CLIENT_ID: ${{ secrets.ULL_MSA_CLIENT_ID }} + + release: + name: GitHub Release + needs: build + # `always()` + `!cancelled()`：白名单外的槽位（`windows-arm64`、`linux-arm64`，以及只在 `all_slots` 取证跑里 + # 存在的 macOS 两档）红了**不能连坐**那两档已发布的 —— 真正拦发布的是被调方「发布白名单齐全性」那一步： + # 白名单里少任何一个才 fail（M184 之后 `linux-x64` 也在白名单里，它红了就该拦）。 + # tag 门禁留在这里（不在被调方）：分支 ref 的 dispatch 连发布 job 都不该起。 + if: always() && !cancelled() && github.ref_type == 'tag' + # `contents: write` 必须由**调用方**授予：可复用工作流只能收窄权限、不能提权（交集语义）。 + permissions: + contents: write + uses: ./.github/workflows/release-publish.yml + secrets: + # 可复用工作流拿不到调用方未显式传入的 secret；`gh release` 用的就是这一枚安装令牌。 + PUBLISH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + # （M190）清单签名私钥：被调方 release-publish.yml 用它签 `manifest.json`。没配时是空串， + # 签名步会带着「缺什么、怎么补」的注解当场红（宁可不出 Release，也不出未签名的 Release）。 + ULL_MANIFEST_SIGNING_KEY: ${{ secrets.ULL_MANIFEST_SIGNING_KEY }} diff --git a/.github/workflows/signing-status.yml b/.github/workflows/signing-status.yml new file mode 100644 index 0000000..693d889 --- /dev/null +++ b/.github/workflows/signing-status.yml @@ -0,0 +1,121 @@ +name: Signing status（播报，不是门禁） + +# 第一句就是口径：**这是播报，不是门禁。它红了不代表不能合，它绿了也不代表签名就绪。** +# 就绪度的结论只在 job summary 的三行字里（`packaging/check_signing_ready.py --line` 写的）， +# 不在 job 的颜色里。**本 workflow 不应被设为 required check**（GitHub 侧分支保护里不要勾它）。 +# +# 为什么要有它（M255）：M254（CLAIMAUDIT）查出 `crates/core/src/update/trust.rs` 的 `PRODUCTION` +# 表在 `PINNED-KEYS` 标记之间是空的，而空表一律 `KeyringEmpty` 拒装 ⇒ 今天任何正式二进制都验不过任何 +# 清单（fail-closed，用户端表现为「更新永远失败」）。工具链早就齐了，缺的是**可见性**：这三行读数让 +# 「今天差什么」在每次运行里都摆在台面上，而不是等发版时才发现。 +# +# 口径四条（由 `packaging/tests/signing_ready_wiring_selftest.py` 的接线判据机器校验，不是靠注释自律）： +# ① 就绪度那一步抓 `rc=$?` 之后**恒 `exit 0`** —— 未就绪用 `::warning::` 播报，不用 error 级注解 +# （error 会让人以为构建挂了，与播报定位直接冲突）。真正的红留在 `release-publish.yml` 的签名步： +# 那里今天必然红是**对的**，因为签不出来的产物本来就不能发。 +# ② 文件名/名字都不带 guards、check 字样：它不是守卫，是一条状态播报。 +# ③ 本文件**刻意不声明 `workflow_call:`**：没有这个触发器，别的 workflow 就没法 `uses:` 它 —— +# 「不能被接进 dev 线变成必需检查」是一条机制，不是一句嘱咐。接线自检另外扫全部 workflow， +# 任何 `uses: …/signing-status.yml` 出现即红（防的是有人先加 workflow_call 再接进来）。 +# ④ **生产签名种子只在 `refs/heads/main` 上注入**，且**没有 `pull_request` 触发**（M255 r1 P2-1）。 +# 这条是本文件唯一的**安全**口径，别为了「PR 上也能看读数」把它放开： +# - 仓库内分支的 PR / 任意分支的 dispatch **拿得到**仓库 Secret（只有 fork / Dependabot 拿不到）； +# - 而这把种子能给**全量已安装客户端**签出被信任的清单（自更新链 = 用户端 RCE）， +# 既有设计把它锁在 tag ref 后面（`release.yml` 的 `if: … github.ref_type == 'tag'`）。 +# - 播报**不需要**在 PR 上跑：PR 改了 `check_signing_ready.py` 时，CI 会在那个 PR 自己的代码上执行它， +# 若同时注入种子，等于把种子交给任何能推分支的人。 +# 门由两行 env 表达（同一个条件、同一个地方可审）：钥给 main，非 main 则给 `ULL_SIGNING_KEY_WITHHELD` +# 一个原因串 —— 于是 ② 读成「未判定」而不是「没配」（把策略说成缺配是一次假读数）。 +# +# 判据本体与 0/1/2 的语义：`packaging/check_signing_ready.py` 的文件头； +# 人类要做的那几步：`packaging/docs/signing-runbook.md`。 + +on: + push: + branches: [main] + # ⚠ 刻意**没有** `pull_request`（见口径④）。要读 PR 的签名就绪度，就跑 push 到分支或对着 main dispatch。 + workflow_dispatch: + +permissions: + contents: read + +jobs: + # 尺子自测：它红 = **判据脚本坏了**（不是「签名没就绪」）。两者措辞在 summary 里分开写。 + # 这一步照常会红，因为「尺子坏了」本来就该有人看见 —— 但它不阻断任何东西：本 workflow 独立、 + # 非必需，也不在 `dev-guards.yml` 的 `uses:` 里。 + selftest: + name: 判据自测（三行/退出码/变异重放/接线） + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: 判据本体（三行 / 0/1/2 / 两向退出码变异 / --key 用法错 / 指针章节） + run: python3 packaging/tests/signing_ready_selftest.py + # 接线单独一份（400 行红线）：播报不是门禁、**生产种子只在 main 注入**、文档指针真的存在， + # 以及「去掉 ref 门 / 加回 pull_request / 改坏文档路径 ⇒ 必须红」三处变异重放。 + - name: 接线（ref 门 / 不被别的 workflow 复用 / 无 error 级注解 / 文档路径存在性 + 三处变异） + run: python3 packaging/tests/signing_ready_wiring_selftest.py + - name: 真跑三种情形（今天的状态 / 假 PinnedKey 副本 / 用法错） + run: | + set -uo pipefail + work="$RUNNER_TEMP/signing-ready" + mkdir -p "$work" + # 结论只打印，不判定：这里要的是「三种情形各自的退出码与三行读数长什么样」， + # 判据在上一跑的 selftest 里。所有 `|| true` 只为让这一步本身不变红。 + run_and_show() { # run_and_show <说明> <命令...> + note="$1"; shift + echo "── $note" + python3 packaging/check_signing_ready.py "$@" 2>&1 || true + echo + } + run_and_show "今天的状态（真实 trust.rs：表空 ⇒ 未就绪）" + # 副本夹一条假 PinnedKey（**不碰真实 trust.rs**）：造出「就绪」的正路长什么样。 + python3 - "$work" <<'PY' + import sys + from pathlib import Path + + trust = Path("crates/core/src/update/trust.rs").read_text(encoding="utf-8") + begin = trust.index(">>> PINNED-KEYS >>>") + len(">>> PINNED-KEYS >>>") + end = trust.index("<<< PINNED-KEYS <<<") + fake = ' PinnedKey { key_id: "demo-not-a-real-key", public_key_hex: "' + "ab" * 32 + '" },\n' + Path(sys.argv[1], "trust-with-fake-key.rs").write_text( + trust[:begin] + "\n" + fake + trust[end:], encoding="utf-8" + ) + PY + run_and_show "副本夹一条假 PinnedKey（②仍缺钥 ⇒ 仍未就绪，但 ① 会变就绪）" \ + --trust "$work/trust-with-fake-key.rs" + run_and_show "用法错（不存在的 trust.rs ⇒ 2）" --trust "$work/nope/trust.rs" || true + + # 播报：只把三行搬进 job summary，不看颜色。 + status: + name: 签名就绪度（播报） + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + # ② 要读「环境里有没有钥」，所以把 Secret 传进来 —— **只在 main ref 上**（口径④）。 + # 门是下面这两行 env（同一个条件），不是 `if:`：这样非 main 的运行照样跑完三行读数， + # 只是 ② 读成「未判定」，而不是整个 job 被跳过后一片空白。 + # ⚠ 这两行是安全边界，接线自检钉着它们（去掉 ref 门 / 加回 pull_request 都会当场红）。 + - name: 三行就绪度（脚本给 0/1/2；本步恒 exit 0） + env: + ULL_MANIFEST_SIGNING_KEY: ${{ github.ref == 'refs/heads/main' && secrets.ULL_MANIFEST_SIGNING_KEY || '' }} + ULL_SIGNING_KEY_WITHHELD: ${{ github.ref == 'refs/heads/main' && '' || '非 main ref（按设计不注入 Secret；要读这一行请对 main 跑）' }} + run: | + set -uo pipefail + set +e + python3 packaging/check_signing_ready.py --line > "$RUNNER_TEMP/signing-ready.txt" 2>&1 + rc=$? + set -e + cat "$RUNNER_TEMP/signing-ready.txt" + case "$rc" in + 0) echo "::notice::签名就绪：信任表非空，且环境里的钥与它同源。这是一条播报，不是门禁。" ;; + 1) echo "::warning::签名未就绪（或 ② 未判定）：该做什么见 packaging/docs/signing-runbook.md §2 的下单清单。" ;; + *) echo "::warning::就绪度脚本用不了（rc=$rc，用法错）：这是尺子的问题，不是签名状态 —— 看上面的 stderr。" ;; + esac + { + echo + echo "- 本 workflow 是**播报**，不是门禁：**不应被设为 required**，也不阻断任何其它 job。" + echo "- 颜色 ≠ 结论：绿色只说明脚本跑完了；结论只看上面三行（尤其 ①「信任表」）。" + echo "- **Secret 只在 \`refs/heads/main\` 上注入**（生产签名种子锁在 main / tag 后面）；非 main ref 的 ② 显示「未判定」而不是「没配」。" + echo "- 真门禁在哪：\`release-publish.yml\` 的签名步（\`--check-pinned-keyring\` / \`--sign\` / \`--verify-pinned\`）。" + } >> "$GITHUB_STEP_SUMMARY" + exit 0 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..e01e8ea --- /dev/null +++ b/.gitignore @@ -0,0 +1,37 @@ +# 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/ + +# Python bytecode (packaging/*.py 本地跑过就会生成；提交它会让每次 spawn 都打 WIP 快照) +__pycache__/ +*.pyc + +# IDE +.idea/ +.vscode/ +*.iml + +# OS +Thumbs.db +.DS_Store + +# 签名私钥：绝不入库（M255 手册产出的本地副本） +.signing/ +**/signing-secret*.json +**/ull-signing/ 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/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..9d15937 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,58 @@ +# 更新日志 + +> 自上而下由新到旧。版本号与 `Cargo.toml` 同源；二进制 `unlucky-launcher --version` 打同一个号。 +> 只记**对外可感知的变化**（用户能看到、能用到、能感觉到稳的），不记内部重构流水账。 + +--- + +## 0.2.4 — 未发布（当前 `dev`） + +这一批的主线是「把存档区做成真正能用」，以及把验证方式从「看起来对」改成「能被证伪」。 + +**存档** +- 存档列表可重命名（行内输入，回车即提交）、删除（二次确认）、备份导出为 zip +- **游戏运行时写操作被拦下并给出明确原因**——此前在 Linux 上删一个正在跑的世界会成功 +- 截图区从「一行文件名」变成**缩略图墙**：真解码、最大边 160px、单次最多 60 张、单张超 8 MiB 跳过；「未生成预览」与「文件过大」是两种不同的格子，失败逐条可见 + +**外观** +- **强调色自定义真的生效**：填了色，按钮 / 进度条 / 图标跟随；中性底与描边不动（既定语义） +- 非法色值给红框 + 结构化原因，且**不写盘**；手打过程中不闪红，离开输入格或按回车才判 +- 三处组件配色改走主题角色（描边、进度轨道、Elevated 底色），不再对着设计稿比色值 + +**交互** +- 单行输入框支持**回车提交**：存档重命名、强调色两处接上；未接的既有调用点行为不变 + +**发布与验证** +- GPU 截图证据门禁接进 CI：无 GPU 时**显式跳过**，「跳过」与「通过」分开呈现，不会伪装成已验证 +- 新增**签名就绪度**播报与操作手册：一条命令看清「签名还差什么」；播报只播报，不是门禁 +- 修掉一处会让 CI 把**生产签名种子**交给 PR 代码的接线（仓库内分支的 PR 拿得到仓库 Secret） +- 合并态全量测试在每次合并后的 tip 上重跑，不再只看定向验证 + +**已知问题** +- **自动更新链路是断的**：正式签名信任表为空，任何发布二进制都验不过（fail-closed）。通道本身已接到底，缺的是「一把被钉住的公钥 + 一份签名 Release」 +- Ink 主题下 Elevated 卡片层级几乎看不出（对比约 1.03:1） +- Windows 路径在界面上仍显示正斜杠 +- macOS 两档构建仍是 `probe`，从未真构建、也没在真机跑过 + +--- + +## 0.2.3 — 2026-11-08 + +- 首次进入**稳定更新通道**（`latest` 指向本版；此前的版本只在预览通道） +- 断点与续传、镜像选路、崩溃弹窗与现场日志导出等前序能力在本版收敛完成 + +> 注：`main` 采用孤儿快照发布，`v0.2.3..HEAD` 之类的区间日志不可用；本条目按发布记录与 README 口径编写。 + +--- + +## 0.2.1 — 2026-11-06 + +- 早期公开版本：安装、启动、日志与设置四项主流程可用 +- 具体条目从简（发布记录以 tag 为准） + +--- + +## 0.2.0 — 2026-11-05 + +- 首个公开预览版本 +- 具体条目从简（发布记录以 tag 为准） diff --git a/Cargo.lock b/Cargo.lock new file mode 100644 index 0000000..0018be4 --- /dev/null +++ b/Cargo.lock @@ -0,0 +1,6506 @@ +# 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 = "base64ct" +version = "1.8.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2af50177e190e07a26ab74f8b1efbfe2ef87da2116221318cb1c2e82baf7de06" + +[[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 = "const-oid" +version = "0.9.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c2459377285ad874054d797f3ccebf984978aa39129f6eafde5cdc8315b612f8" + +[[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 = "curve25519-dalek" +version = "4.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "97fb8b7c4503de7d6ae7b42ab72a5a59857b4c937ec27a3d4539dba95b5ab2be" +dependencies = [ + "cfg-if", + "cpufeatures 0.2.17", + "curve25519-dalek-derive", + "digest", + "fiat-crypto", + "rustc_version", + "subtle", + "zeroize", +] + +[[package]] +name = "curve25519-dalek-derive" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f46882e17999c6cc590af592290432be3bce0428cb0d5f8b6715e4dc7b383eb3" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[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 = "der" +version = "0.7.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e7c1832837b905bbfb5101e07cc24c8deddf52f93225eee6ead5f4d63d53ddcb" +dependencies = [ + "const-oid", + "zeroize", +] + +[[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 = "ed25519" +version = "2.2.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "115531babc129696a58c64a4fef0a8bf9e9698629fb97e9e40767d235cfbcd53" +dependencies = [ + "pkcs8", + "signature", +] + +[[package]] +name = "ed25519-dalek" +version = "2.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "70e796c081cee67dc755e1a36a0a172b897fab85fc3f6bc48307991f64e4eca9" +dependencies = [ + "curve25519-dalek", + "ed25519", + "serde", + "sha2", + "subtle", + "zeroize", +] + +[[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 = "fiat-crypto" +version = "0.2.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "28dea519a9695b9977216879a3ebfddf92f1c08c05d984f8996aecd6ecdc811d" + +[[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 = "pkcs8" +version = "0.10.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f950b2377845cebe5cf8b5165cb3cc1a5e0fa5cfa3e1f7f55707d8fd82e0a7b7" +dependencies = [ + "der", + "spki", +] + +[[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.6.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ec0be4795e2f6a28069bec0b5ff3e2ac9bafc99e6a9a7dc3547996c5c816922c" +dependencies = [ + "getrandom 0.2.17", +] + +[[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_spanned" +version = "1.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9c187e0a369471c550af028cba56d4f4fa2a489ad28151ae95a4d340a2a8b782" +dependencies = [ + "serde_core", +] + +[[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 = "signature" +version = "2.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "77549399552de45a898a580c1b41d445bf730df867cc44e6c0233bbc4b8329de" +dependencies = [ + "rand_core 0.6.4", +] + +[[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 = "spki" +version = "0.7.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d91ed6c858b01f942cd56b37a94b3e0a1798290327d1236e4d9cf4eaca44d29d" +dependencies = [ + "base64ct", + "der", +] + +[[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" +version = "1.1.0+spec-1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f8195ca05e4eb728f4ba94f3e3291661320af739c4e43779cbdfae82ab239fcc" +dependencies = [ + "indexmap", + "serde_core", + "serde_spanned", + "toml_datetime", + "toml_parser", + "toml_writer", + "winnow", +] + +[[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 = "toml_writer" +version = "1.2.0+spec-1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "009dbb7700f11c55ef83aebbe4c0e9cf1f1ac0844bd8d6f00dc38f302026e13a" + +[[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.4" +dependencies = [ + "axum", + "futures-util", + "rig-agent", + "rig-core", + "rmcp", + "serde", + "serde_json", + "tokio", + "unlucky-core", +] + +[[package]] +name = "unlucky-app-iced" +version = "0.2.4" +dependencies = [ + "iced", + "image", + "log", + "unlucky-cli", + "unlucky-core", + "unlucky-design", + "unlucky-i18n", + "unlucky-presenter", + "winresource", +] + +[[package]] +name = "unlucky-cli" +version = "0.2.4" +dependencies = [ + "serde", + "serde_json", + "tokio", + "unlucky-agent", + "unlucky-core", + "winresource", +] + +[[package]] +name = "unlucky-core" +version = "0.2.4" +dependencies = [ + "ed25519-dalek", + "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.4" + +[[package]] +name = "unlucky-i18n" +version = "0.2.4" + +[[package]] +name = "unlucky-palette-extract" +version = "0.2.4" +dependencies = [ + "image", + "unlucky-design", +] + +[[package]] +name = "unlucky-presenter" +version = "0.2.4" +dependencies = [ + "ed25519-dalek", + "serde", + "serde_json", + "unlucky-core", + "unlucky-palette-extract", +] + +[[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 = "winresource" +version = "0.1.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a2bc6d36480b829272a5bdabf08e6dca8004761c1da7e35efef800540c66221b" +dependencies = [ + "toml", + "version_check", +] + +[[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..5dd957e --- /dev/null +++ b/Cargo.toml @@ -0,0 +1,171 @@ +[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.4" +edition = "2021" +license = "Apache-2.0" +authors = ["AskaEth "] +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"] } + +# M190（core::update::ed25519）：清单签名**验签**用官方实现，不再自写曲线算术。 +# M190 r1 复审的裁定：信任锚不许用自写密码学（非规范编码/小阶点/批量验证差异的后果是 +# 「验签通过但本不该通过」）。BSD-3-Clause，在 deny.toml 白名单内。 +# 只开 `std`（不用 `rand_core`/`batch`/`fast` 这类可选面）：本仓的签名侧在 +# `packaging/sign_manifest.py`，二进制里只有「验」这一半。 +ed25519-dalek = { version = "2", default-features = false, features = ["std"] } + +# 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..0803e9c --- /dev/null +++ b/README.md @@ -0,0 +1,446 @@ +# Unlucky Launcher (ULL) + +**English** · [简体中文](README.zh-CN.md) + +> **Official project home**: ｜ downloads, issues and +> release notes all live there: +> +> **Version in this README: `0.2.4`** — `unlucky-launcher --version` prints the same number. + +Unlucky Launcher 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 — and covers the launcher job from installing a version to reading a crash report: instances +and versions, mod loaders and modpacks, mods / resource packs / shaders, per-instance Java, Microsoft +/ third-party / offline accounts, and a crash diagnosis that runs locally on a YAML rule engine. +Nothing of yours goes through a service of ours: account tokens stay on the machine. + +![The instances page: the local instance list on the left; on the right the selected instance's +version, loader, isolation mode and last-played time](docs/images/instances-en-light.png) + +*The instances page — 1180×760, English UI, light theme. The instance names are test data, not +anybody's real setup. That `Launch failed · exit0 静默失败` line is also an honest sight of a known +gap: the reason text is still raw Chinese straight out of the launch layer (see +[Not done yet](#not-done-yet)).* + +## What works today + +### Instances, versions and launching + +- **Instances** — a list-detail page: the local instance list on the left; on the right the selected + instance's version, loader, isolation mode (an isolated game directory or the shared one), + files-on-disk state and last-played time, with Play / Stop. Narrow windows switch panes instead of + stacking them. +- **Where an instance comes from** — installing a version (with a name, loader and loader version) + or importing a modpack. The instances page's own **New instance / Import / Duplicate / Open folder + / Delete** buttons are **not wired yet**: they are placeholder actions that only write a line to + stderr (`crates/app-iced/src/app/update/page_messages.rs`), and the instance wizard is the pending + piece (`crates/app-iced/src/pages/mod.rs`, deviation #8). +- **Version management** — a three-column rail (version type / major version / search) over the + Mojang version list: release, snapshot and ancient versions, plus loader selection and a loader + version when you install. Cancelling an installation really stops it — the in-flight file is cut, the + job ends at the next stage boundary, and no instance is registered + (`crates/presenter/src/host/dispatch.rs:61-88`). The CLI can plan the same install without + downloading (`ull install --dry-run`: per-role file counts, total size, and one source-chain sample + per file category; the full file list is in `--json`). +- **Launching** — a 10-stage command-line assembly (`crates/core/src/launch/`), per-instance JVM and + game arguments, a native-library pass, and a JSONL session record for every run. Process trees are + killed as trees, not as one PID. +- **Per-instance launch arguments** — JVM arguments, game arguments, memory, the Java executable and + the graphics backend (`default` / `opengl` / `vulkan`) live in the instance file under `launch.*`, + and every field falls back on its own: instance → global setting → factory default, so an instance + that only sets memory does not wipe the global JVM arguments. JVM arguments are *appended* (global + first, instance last, so the JVM's last-one-wins rule makes the instance win). An out-of-range + memory value counts as "not set" instead of producing `-Xmx0m`, an empty field means "follow", and + the backend row only appears for game versions that have it. The CLI and the GUI read the same + resolved values (`crates/core/src/game/launch_overrides.rs`). +- **Crash diagnosis is real and local** — `crates/core/src/diagnose` collects five kinds of signals + (exit code, `latest.log`, `crash-reports`, `hs_err_pid` files, environment snapshot including the + mod list), matches them against a YAML rule set, and shows the findings with fix actions on the + logs page. No model, no network: it works offline and on a machine with no GPU. + +### Mod loaders, packs and the content library + +- **Loaders** — Fabric, Quilt, NeoForge and Forge. Forge/NeoForge versions that need the official + installer `processors` really run them, with a managed JDK if the machine has none. +- **Modpacks** — import a CurseForge manifest, a Modrinth `.mrpack`, or a MultiMC/Prism instance; + export as `.mrpack` or a CurseForge manifest. Cancelling an **import** is interface-level only: the + panel closes and the result is discarded, but the import thread runs to the end, because `core`'s + import request has no cancel token yet (`crates/presenter/src/host/addon/pack.rs:28-42`). +- **Import conflicts are decided per file** — before anything is written, the scan lists every + conflicting file (what it is, why it conflicts, how big it is) in pages of 40, and three entries + decide the batch: keep all, overwrite all, or choose per item — unpicked rows stay on "keep". Files + that do not conflict are never rewritten, and the report still names every conflict afterwards. +- **Content library** — modpacks / mods / resource packs / shaders with keyword, source, version, + loader and sort filters, paged results, and one-click *install into this instance*. +- **Online source: Modrinth, anonymously** — search goes through `/v2/search` with facets taken from + the target instance (project type, game version, loader); project details and version lists follow, + and a remote entry whose hash is known is completed through `/v2/version_file/`. No API key, + and no POST: the download engine has no request-body field, so hashes are looked up one GET at a + time. Being offline is its own state — "not connected" — never "no matching content". +- **What that page will refuse, and says so on the row** — a modpack cannot be installed *from* the + library (packs go through the import pipeline above); CurseForge's *install* is disabled because + its file endpoint is not wired; and an item whose game version or loader does not match the target + instance is disabled with the mismatch spelled out. Nothing fails silently. +- **CurseForge search needs a key** — set `ULL_CF_API_KEY` before launching; without it that source + is greyed out in the source filter. The key stays in the environment: it is not written to the + settings file and not logged (`crates/presenter/src/host/addon.rs`). + +### Java + +A managed JDK per instance, with a four-vendor fallback chain ordered by region — Temurin first, then +Oracle before Microsoft inside mainland China (measured 28× faster there) and Microsoft before Oracle +elsewhere, Zulu last — overridable through the `java.vendorPriority` setting +(`crates/core/src/game/java/vendor.rs`). Mirrors are region-aware too. `java list` shows every JDK it +can actually see (including the ones the official launcher downloaded), `java install ` fetches +one. The game's JDK is the launcher's data, not its own dependency. + +### Accounts + +Three tracks on one page: + +- **Microsoft** — OAuth 2.0 device code flow → Xbox Live → XSTS → `api.minecraftservices.com`. +- **Third-party community auth servers** (authlib-injector style). +- **Local offline profiles**, for isolated testing. + +**Microsoft sign-in works out of the box in official builds.** Release binaries carry the Azure public +client id they need (a public client id, not a credential — it ships inside the binary), so there is +nothing to configure before signing in. Setting `ULL_MSA_CLIENT_ID=` still overrides it: the +variable is read at startup, so restart the launcher after changing it. Building from source bakes in +whatever that variable holds at build time (`ULL_MSA_CLIENT_ID= cargo build`). A build with no id +anywhere stops before any network call, and its alert says exactly what is missing: the title +"Microsoft sign-in is not configured", a body naming `ULL_MSA_CLIENT_ID=` (set it, or build with +it, then restart), and `Code: msa_not_configured`. It offers no Retry button, because retrying in that +same process cannot help. Every other sign-in failure keeps the older shape: one category line plus +its own `Code:` line, with the full reason only in the launcher log. Community auth servers and local +profiles need no id. + +### Look and language + +- **One UI stack** — iced 0.14 + Material 3 Expressive, a self-drawn title bar, an animated + navigation rail, light / dark / follow-system. +- **Appearance** — window background image with a colour pipeline (panel colours can be derived from + the wallpaper), per-panel transparency, and whole-window transparency on Windows. On Windows 11 + and Server 2025 the system is asked for rounded corners; macOS and Linux leave corners to the + desktop's own rules; nothing is drawn by hand. +- **CPU fallback** — `--software-renderer` keeps the interface rendering on machines with no usable + GPU or broken drivers, and the backend probe falls back on its own when no adapter is usable. On + that path panel-level translucency and blur are switched off (window-level transparency still + works) and the settings panel says so. +- **Localisation** — system-language detection, an explicit override in settings, and persistence + across restarts. Most copy comes from one message catalogue (`crates/i18n`). + **Boundary, stated because it is easy to over-read that sentence**: the anti-hard-coding guard + (`crates/app-iced/src/pages/instances/tests/i18n.rs`) scans the instances page sources only, not + every screen; a hard-coded *Chinese* literal has no ASCII word for it to match, so nothing catches + that class; and the appearance panel's older controls are still hard-coded English + (`crates/app-iced/src/pages/appearance/section.rs`), so a Chinese UI still shows them in English. + +### The assistant, and the MCP server + +These are two different things and the README should not blur them: + +- **The in-app assistant is a placeholder shell today.** Its transport is scripted + (`crates/app-iced/src/presenter/transport.rs`), no real model is connected, and the UI says so in + four places on every screen it appears — subtitle, input placeholder, empty-state body, and a + "Simulated" chip. The session state, unread count, draft, confirm flow and named failure codes are + real presenter state; only the model behind them is not there yet. +- **The MCP server is real.** `ull agent serve` exposes the launcher core to external agent tools as + an MCP server over stdio or Streamable HTTP, loopback only (`127.0.0.1`, default port 47823), + read-only unless `agent.mcp.allow_write=true`. The same ten tool specs (`crates/agent/src/tools/`) + feed both shapes, and both go through the same executor — schema validation, sensitivity tiers, + audit trail. `ull agent config` prints ready-made Claude Code / Cursor snippets. + +### Command line + +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. + +```bash +unlucky-launcher # GUI +unlucky-launcher --software-renderer # GUI, CPU renderer +unlucky-launcher instances list # CLI, no window +unlucky-launcher --json launch 1.20.1 # CLI, global options before the command +unlucky-launcher --version # CLI, version + OS summary +``` + +The dispatch 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 lives in exactly one place +(`crates/cli/src/cli/parse.rs`), so both binaries accept the same set by construction. `ull --help` +lists them all: `instances`, `install`, `launch`, `pack import`, `accounts`, `sessions`, `logs`, +`diag`, `config`, `java`, `update`, `agent`, `version`, `help`. + +### Updates, and the stable channel + +- **Self-update is real, and GUI and CLI share one core.** The settings panel's Update group and + `ull update check` / `ull update apply` both build the same `core::update::Job` + (`crates/core/src/update/`): fetch the manifest at `releases/latest/download/manifest.json`, compare + versions, admit the channel, verify length + SHA256, then swap the binary atomically — rename the + old file aside, move the new one in, roll back if that fails. A running Windows exe can be + *renamed* but not overwritten, which is why the swap is a rename. +- **Four outcomes, never conflated**: up to date / update available / a newer version exists but ships + no artifact for this platform / the check itself failed (offline, broken manifest, channel + mismatch). A failed check is never reported as "up to date". +- **Only the stable channel is published.** `update.channel` defaults to `stable`; beta / alpha / + nightly are modelled and reserved. A manifest is admitted only when both its declared channel and + the version's own pre-release stage agree — a manifest can lie, a version number cannot. +- **Why a release has to be marked stable**: `releases/latest/download/*` only points at the newest + **non-prerelease** release, and the manifest address is pinned there. `0.2.3` is the first release + created without the pre-release flag (`0.2.2` stays a historical pre-release). Which trigger creates + which marker — push tag ⇒ stable, dispatch `prerelease=true` ⇒ pre-release — is one table + (`packaging/release_marker.py`), with a guard over it (`packaging/check_release_semantics.py`). +- **Nothing installs itself behind your back.** The check at startup can be turned off + (`update.auto_check`, the same key the CLI reads), and installing is a button or an explicit + `ull update apply`. Debug builds can rehearse the whole chain against a local directory source + (`ULL_UPDATE_DIR`); release builds do not contain that path at all. + +### Where the logs are + +Everything the launcher writes on its own side lives under `/logs/`. The settings page has +a **Log folder** row that shows that path with *Open folder* and *Copy path*; the logs page header has +*Open folder* as well. The data root is `/.ULL` in portable mode, `/ULL` +in standard mode, and `/.ULL` in custom mode — the same value the settings page displays +as the launcher data directory. + +| Path | What it is | +|---|---| +| `logs/launcher.log` | The launcher's own runtime log: boot probe, font/theme decisions, backend choice, **the named reason when a render backend fails to start**, and every launch attempt (command line facts, spawn result, exit). Rolled over at 1 MiB into `logs/launcher.1.log`, exactly **one** old copy kept, so it cannot grow without bound. | +| `logs/launcher.1.log` | The previous 1 MiB, replaced on the next rollover. | +| `logs/game/.jsonl` | One JSONL event stream per launch: the command line (secrets redacted), every stdout/stderr line, exit code. | +| `logs/game/index.jsonl` | The one-line-per-session index the logs page lists. | +| `logs/install.log` | Install pipeline journal, one line per stage. | +| `logs/session-log-location.json` | A record of where session logs live and where they used to live. Rewritten on every start. | +| `data/agent/sessions/game/…` | **Read-only compatibility**: sessions written by older builds. They are still listed and still openable; nothing is moved and nothing is deleted. | + +The game's own files are not in there — they sit in the instance's run directory: `logs/latest.log`, +`crash-reports/crash-*.txt`, and `hs_err_pid*.log`. **`crash-reports/` only exists when the JVM lived long +enough to write one.** If a mod, a missing library, or a wrong Java kills the game before Minecraft +initialises, the game never gets that far, and the honest evidence is the session JSONL plus +`launcher.log` — not a crash report. That is how the game behaves, not something the launcher is +hiding. + +### Not done yet + +This list is the reason to believe the rest. None of it is hidden behind marketing copy. + +- **No installer.** You download a file and run it — there is no setup step, and updates replace that + file in place instead of installing anything (see [Updates](#updates-and-the-stable-channel)). +- **The update path has only been exercised against a local directory source.** The whole chain + (manifest → download → SHA256 → rename/rollback) ran with a debug build and a fixture, because the + real `releases/latest/download/manifest.json` was unreadable while `0.2.2` was still a pre-release. + The first observation on the live stable channel happens after `0.2.3` ships. +- **Several buttons are placeholders.** On the instances page: *New instance*, *Import*, *Duplicate*, + *Open folder*, *Delete*. In the settings frame: *Save*, *Reset + section*, *Add override*. Each writes `[page] 占位动作 …` to stderr and changes nothing — instance + management from the GUI is the instance-wizard work still outstanding, and settings change as you + edit them rather than on a Save. +- **Linux x64 is published, and "published" means "it runs", not "it looks finished".** The release workflow + builds `linux-x64` on a native Ubuntu 22.04 runner by default and ships it, because the release artifact itself + was started under a real display server (WSLg), opened a window, rendered a non-blank frame and printed its + theme/backend lines — and that same check is now a per-slot CI gate on every release + (`packaging/docs/linux-evidence.md` has the raw output). Nobody has yet looked at it on a real desktop + distribution: dragging, resizing, font metrics and CJK shaping on a real desktop session are unverified. + Two things from the Windows list are simply not code paths on Linux, so there is nothing to verify: whole-window + transparency needs a native window handle the app does not have there (`hwnd=none`), and rounded corners are + delegated to the desktop compositor (`corner=policy=system`) instead of being drawn by the app. + `linux-arm64` is built (native `ubuntu-22.04-arm`) but **not** published — no ARM64 machine has ever run it, so + the artifact stays as build evidence only. +- **macOS is not built by the release workflow, and it is not finalised.** It has two rounds of real-device + evidence (Apple Silicon), which is why the build exists at all — but the menu-bar name, the placement of the + three window buttons (macOS puts them top-left; ours are drawn top-right), and 300s+ steady state still need a + real machine. macOS builds are unsigned, so the first launch needs the Gatekeeper quarantine attribute cleared + (`xattr -d com.apple.quarantine`). The macOS runtime smoke job is a manual `workflow_dispatch` probe with + `continue-on-error`, not a gate; `gh workflow run release.yml -f all_slots=true` builds the two slots for + evidence, but they are never published. +- **The content library is cramped at low window heights**, and the window height is not wired into + the page model yet — the page lays itself out for a nominal height rather than the one it gets. +- **Launch-side failure text is not structured.** The tile takes a Chinese sentence straight from the + launch layer (`crates/core/src/launch/exit_analysis.rs`) instead of a reason code the UI could + translate — which is exactly the `静默失败` you can see in the English screenshot above. +- **The in-app assistant has no model behind it** (see above). The MCP server does. +- **Install progress is stage-level**, not byte-level, on the content-library install path. +- **No native file chooser.** Import takes drag-and-drop or a pasted path. +- **Android/Termux is experimental and not promised**: no released asset targets it. A GUI build is + possible from source via the glibc toolchain (`packaging/docs/termux-glibc-build.md`, branch notes: + [`README.termux.md`](README.termux.md)); it was verified on-device twice: once on CPU software rendering, once with GPU acceleration via a self-built Mesa/turnip stack (see the evidence in README.termux.md). + +## Download and run + +Grab the file for your platform from +[Releases](https://github.com/AskaEth/Unlucky-Launcher/releases). Names follow +`unlucky-launcher___`; the single source of truth for that shape is +`packaging/make_artifacts.py::asset_stem()`: + +| Slot | Asset | Shape | +|------|-------|-------| +| `windows-x64` | `unlucky-launcher__windows_x64.exe` | bare `.exe`, double-click to run | +| `linux-x64` | `unlucky-launcher__linux_x64.tar.gz` | one archive, one top-level directory; glibc 2.35+ and the X11/Wayland + fontconfig stack | +| `windows-arm64` | `unlucky-launcher__windows_arm64.exe` | bare `.exe` — **built, not published**, see below | +| `linux-arm64` | `unlucky-launcher__linux_arm64.tar.gz` | same — **built, not published** (no runtime evidence yet) | +| `macos-arm64` | `unlucky-launcher__macos_arm64.tar.gz` | same — **not built** by the release workflow | +| `macos-x64` | `unlucky-launcher__macos_x64.tar.gz` | same — **not built** by the release workflow | +| every published slot | `ull___[.exe]` | bare CLI binary, its own asset | +| all | `SHA256SUMS.txt` | `sha256sum -c` eats it directly | + +**This release publishes `windows-x64` and `linux-x64`, and nothing else.** The publish job keeps only the slots +named in `PUBLISH_SLOTS` (`.github/workflows/release-publish.yml`) and deletes every other artifact before it +writes `SHA256SUMS.txt`, so a row marked **not published** is a naming rule, not a downloadable asset. A guard +(`packaging/check_publish_slots.py`) watches all three relations: a slot named in the list whose artifacts are +missing turns the release red (that is also what makes a red `linux-x64` build block the release), artifacts that +exist for an unlisted slot get an explicit "not published" warning instead of being deleted quietly, and a +`mode: ci` slot that produced nothing at all warns too — a red slot must never be visible only as a missing row. + +Of the unlisted rows, CI builds two. `windows-arm64` is built natively on GitHub's `windows-11-arm` runner +(Windows 11 Arm64 + Visual Studio 2026); every ARM64 failure so far came from a pre-build toolchain probe that +aborted before `cargo build` ran, that probe is now evidence-only, and the next CI run is the first real answer to +whether the slot can produce a binary. `linux-arm64` is built natively on `ubuntu-22.04-arm` (same glibc 2.35 floor +as x64) and is unpublished for a different reason: **nothing has ever run it on ARM64 hardware**. One frame plus the +theme/backend log lines on a real ARM64 machine is the unlock condition; until then the artifact is build evidence. + +Each UNIX archive contains the executable plus `LICENSE`, `NOTICE` and `README.md`, in one top-level +directory. Windows ships a bare `.exe` (a single file cannot carry the texts), so those three +documents are attached to the release next to it — downloading the Windows binary does not strip the +licence. Download links never carry implementation detail in the name, and the binary inside an +archive is always called `unlucky-launcher`. + +On Linux x64 that is the whole install: + +```bash +tar -xzf unlucky-launcher__linux_x64.tar.gz +cd unlucky-launcher__linux_x64 +./unlucky-launcher # add --software-renderer if there is no usable GPU adapter +``` + +It asks for glibc 2.35+ (the slot is built on Ubuntu 22.04), `libxkbcommon`, `fontconfig` and `libGL`; on +Debian/Ubuntu `sudo apt-get install libxkbcommon0 libfontconfig1 libgl1 libx11-6 libxcursor1 libxrandr2 libxi6` +covers the load-time set, and the bare `ull__linux_x64` beside the archive needs no display at all. + +The two shapes 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 or a CI container where no window can exist. On Linux that floor is glibc ≥ 2.35 +(the slots build on Ubuntu 22.04) — an older distribution needs a source build +(`packaging/README.md` §4). Pick `ull` when there is no desktop, `unlucky-launcher ` when +there is. Both print the same CLI text and each names itself after the file you ran — `argv[0]` with +its directory and a trailing `.exe` removed, nothing else (`crates/cli/src/cli/program.rs`), so the +`ull` asset prints `ull ·`, the binary inside an archive prints `unlucky-launcher ·`, and a local +`cargo build` prints `unlucky-launcher-iced ·`. + +Minimum platform baseline: **Windows 10**; Windows 8.1 / 8 / 7 are not supported. macOS 12+ on Apple +Silicon and Intel, Linux x64 / arm64 (`crates/core/src/platform/os_info.rs` holds the baseline +check). On Windows 10/11 the builds use the standard toolchain (MSVC / GNU), built the same way as +upstream cargo. On Linux, X11 is the preferred path today and Wayland is the long-term direction. +Capability differences are feature gates with runtime probing, never a compile-time "this platform +gets less". + +First run with a Microsoft account? Nothing to configure — official builds carry the client id; see +[Accounts](#accounts). Nothing else needs configuring. + +## Build from source + +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/ +cargo deny check licenses bans sources # dependency licences (required in CI) +``` + +What the build produces: + +- A build from source carries no Microsoft client id by default. Set `ULL_MSA_CLIENT_ID` at build time + to bake one in (`ULL_MSA_CLIENT_ID= cargo build`); official release binaries already carry one + — see [Accounts](#accounts). +- `unlucky-launcher-iced` — the GUI, and the CLI in the same file: it answers every subcommand listed + above. `iced` is cargo's bin name, not a download name — `packaging/make_artifacts.py` stages that + same build as `unlucky-launcher___` and names the binary + `unlucky-launcher` inside the archive. +- `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 ` writes one frame and exits — that 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 + +**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: it +renders one real frame under Xvfb, then asserts the PNG is not blank, and a red result blocks the +merge. The macOS probe is not there yet — manual dispatch only, result recorded but not enforced. + +| Workflow | Content | +|----------|---------| +| `.github/workflows/ci.yml` | fmt + clippy + test + release build (Windows / Linux matrix); Linux runtime smoke (Xvfb, one real frame, PNG asserted non-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 licence and source guard | +| `.github/workflows/release.yml` | tag `v*` → build the four default slots (`windows-x64` + `windows-arm64` + `linux-x64` + `linux-arm64`) on native runners → single-file artifacts + `SHA256SUMS.txt` → GitHub Release (publishes `windows-x64` and `linux-x64`; `linux-x64` also gets a per-slot Xvfb first-frame gate; `-f all_slots=true` builds all six slots for evidence) | +| `.github/workflows/release-guard.yml` | release-marker semantics: push tag ⇒ a **stable** release, dispatch `prerelease=true` ⇒ pre-release; the table lives in `packaging/release_marker.py` and the guard mutation-tests itself | + +## Architecture and 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-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 CI 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 | + +## License and acknowledgements + +- **This project**: Apache License 2.0, see [LICENSE](LICENSE); third-party notices in + [NOTICE](NOTICE). +- **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.termux.md b/README.termux.md new file mode 100644 index 0000000..14d54ed --- /dev/null +++ b/README.termux.md @@ -0,0 +1,59 @@ +# Unlucky Launcher · Termux 适配（`termux-glibc` 分支） + +这条分支把启动器带到 **Termux（Android）**：用 glibc 工具链编出 `aarch64-unknown-linux-gnu` +二进制，在 **termux-x11** 里跑 GUI；同时补上 Termux 平台识别、系统 JDK 安装与中文字体。 + +> 给主线的改动清单、兼容性说明与合并指南见 +> [`TERMUX-ADAPTATION.md`](TERMUX-ADAPTATION.md)。 + +## 已验证 + +| 项 | 状态 | 证据 | +| --- | --- | --- | +| 源码构建（GUI + CLI） | ✅ | Rust 1.99.1 gnu + clang/lld + glibc 运行时；GPU 构建（wgpu）默认带 CPU 兜底 | +| 窗口显示 | ✅ | termux-x11 `:0`，横屏 1657×1067，首帧 ~60 ms（GPU） | +| 中文 | ✅ | 启动时注册 `/system/fonts/NotoSansCJK-Regular.ttc` | +| 微软登录 id | ✅ | 构建期注入，日志 `client_id=configured source=build` | +| 横屏适配 | ✅ | 默认窗口按 X 屏幕等比自适应（`source=termux-screen`） | +| Java 发现 | ✅ | `JAVA_HOME`/PATH + `$PREFIX/lib/jvm` 扫描 | +| Java 自动安装 | ✅ | `ull java install 17` 由内置镜像装完 openjdk-17（约 20 s） | +| GPU（wgpu） | ✅ | 自编 Mesa 26.2.6 + KGSL；wgpu 选中 Adreno 840（Vulkan/turnip） | +| Minecraft 运行 | ✅ | 真机 1.20.4 跑通：glibc JRE + arm64 natives + softpipe GL，主菜单在 X11 渲染 | + +## 快速开始 + +完整配方（工具链、patchelf、linker、门禁）见 +[`packaging/docs/termux-glibc-build.md`](packaging/docs/termux-glibc-build.md)。最短路径： + +```sh +termux-x11 :0 -ac & +DISPLAY=:0 ./unlucky-launcher-iced # 默认 auto：有驱动走 GPU，没有则自动降级 CPU +``` + +- GPU 驱动不随 Termux 源提供，需要按构建文档 §5 自己编一次 Mesa 26 + ICD； + 不装也能跑，只是 `auto` 会落到 tiny-skia（CPU）。 +- 想强制某一侧：`--renderer=gpu` / `--software-renderer`。 +- 窗口尺寸默认按屏幕自适应；`ULL_WINDOW_SIZE=1520x900` 可覆盖。 +- Java：`ull java install 17|21|25` 在 Termux 上默认用系统包（内置镜像 + 隔离 apt 状态）。 +- **数据根**：Portable 模式按**可执行文件所在目录**生成 `.ULL` / `.minecraft`； + 换目录启动会看到另一套实例（`--data-dir` 目前接受并忽略）。 + +## 已知边界 + +- 仅单机（OnePlus 15 / Android 17）验证，试验级、不在发布矩阵内。 +- **GPU**：已打通，但驱动是自编的（Mesa 26.2.6 + KGSL），装到 + `$PREFIX/glibc/{lib,share/vulkan/icd.d}` 后应用会自动启用；Termux 官方源里的 + glibc Mesa 太旧（24.2.6 不认识 Adreno 840）。驱动缺失时自动降级 CPU，不会崩。 +- **MC**：Android 原生 natives 走不通（LWJGL 没有官方 Android/bionic 产物，且 GLFW 的 + 窗口模型与 termux-x11 的 X11 不兼容）。有效路线是 glibc JVM，已真机跑通 1.20.4： + Temurin 21 JRE（patchelf 后直接执行）+ Linux arm64 natives（启动器自动改写/镜像兜底） + + softpipe GL。非致命项：narrator 的 flite 缺失、LWJGL JNI 版本告警； + softpipe 是软件渲染，帧率有限，zink（硬件 GL）仍卡 DRI3。 +- Termux 上三条测试失败是环境差异（`/proc/*/children`、长路径脱敏、mtime flaky）， + PC 的 Linux CI 不受影响。 + +## 后续 + +1. zink 的 DRI3 问题（硬件 GL；当前 softpipe 可跑但慢）——这是 MC 帧率的主要瓶颈 +2. 剪贴板/IME 在 termux-x11 下的行为验证 +3. narrator/flite 与音频设备（当前 missing 但不阻断） diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 0000000..9742baa --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,377 @@ +# Unlucky Launcher (ULL) + +[English](README.md) · **简体中文** + +> **官方项目主页**： ｜ 下载、议题、发布说明都在这里： +> +> +> **本文档对应版本：`0.2.3`**——`unlucky-launcher --version` 打出来的是同一个号。 + +Unlucky Launcher 是一个用 Rust 写的免费开源 **Minecraft: Java 版**启动器（Apache-2.0）。每个平台就是 +**一个原生二进制**——没有安装包、没有捆绑运行时、没有 WebView——从装一个版本到读懂一次崩溃，它把启动器 +该做的事都覆盖了：实例与版本、加载器与整合包、Mod / 资源包 / 光影、逐实例 Java、微软 / 第三方社区服 / +本地离线账户，以及一套在本地按 YAML 规则跑的崩溃诊断。你的数据不经过我们自己的任何服务：账户令牌只 +留在本机。 + +![实例页：左侧是本地实例列表，右侧是所选实例的版本、加载器、隔离方式与上次游玩时间](docs/images/instances-en-light.png) + +*实例页——1180×760，英文界面，浅色档。实例名是测试数据，不是谁的真实存档。图里那句 +`Launch failed · exit0 静默失败` 也正好是一处已知缺口的诚实样子：那行原因仍是启动层直接抛出来的中文 +原文（见[还没做](#还没做)）。* + +## 现在能用什么 + +### 实例、版本与启动 + +- **实例**——list-detail 版式：左侧是本地实例列表；右侧是所选实例的版本、加载器、隔离方式（独立游戏 + 目录或共享目录）、文件是否在盘上、上次游玩时间，以及 Play / Stop。窄窗是把两个面板整页切换，不是上下堆。 +- **实例从哪来**——装一个版本（带实例名、加载器与加载器版本），或者导入一个整合包。实例页自己的 + **新建实例 / 导入 / 复制 / 打开文件夹 / 删除** 五个按钮**还没接后端**：它们是占位动作，点了只往 + stderr 写一行（`crates/app-iced/src/app/update/page_messages.rs`），欠的是实例向导 + （`crates/app-iced/src/pages/mod.rs` 偏离 #8）。 +- **版本管理**——三栏（版本类型 / 主版本 / 搜索）读 Mojang 版本清单：正式版、快照、远古版；安装时可选 + 加载器与加载器版本。取消安装是真停：在下一个段边界收手，在飞的那个文件就地掐断，且不登记实例 + （`crates/presenter/src/host/dispatch.rs:61-88`）。命令行还能只出计划不下载（`--dry-run`：按类的文件数 + 与总大小，人类可读输出里每类给一个源链样本；整份文件清单在 `--json` 里）。 +- **启动**——10 阶段命令行组装（`crates/core/src/launch/`）、逐实例 JVM 与游戏参数、原生库解压落位， + 每次运行留一份 JSONL 会话记录。进程按**进程树**杀，不是只杀一个 PID。 +- **实例级启动参数**——JVM 参数、游戏参数、内存、Java 可执行文件与图形后端（`default` / `opengl` / + `vulkan`）落在实例文件的 `launch.*` 里，**每项各自回落**：实例 → 全局设置 → 出厂默认，所以只填了内存的 + 实例不会把全局 JVM 参数一起顶掉。JVM 参数是**追加**（全局先、实例后，JVM 同名选项后出现者赢）；越界的 + 内存值当作「没填」，而不是拿 `-Xmx0m` 把 JVM 启动弄崩；留空即「跟随」。游戏版本够低时后端那一行直接不 + 出现。CLI 与 GUI 读的是同一份生效值（`crates/core/src/game/launch_overrides.rs`）。 +- **崩溃诊断是真的、也是本地的**——`crates/core/src/diagnose` 采五类信号（退出码、`latest.log`、 + `crash-reports`、`hs_err_pid`、含 mod 清单的环境快照），按 YAML 规则集匹配，把结论与修复动作显示在 + 日志页上。不接模型、不联网：断网能用，没有 GPU 的机器也能用。 + +### 加载器、整合包与内容库 + +- **加载器**——Fabric、Quilt、NeoForge、Forge。需要跑官方 installer `processors` 的 Forge/NeoForge 版本 + 会真跑一遍；机器上没有 Java 时先装一个托管 JDK。 +- **整合包**——导入 CurseForge 清单、Modrinth `.mrpack`、MultiMC/Prism 实例；导出为 `.mrpack` 或 + CurseForge 清单。**导入**的取消只是界面级：面板立刻收回、结果作废，但后台那次导入会跑到底——core 的 + 导入请求还没有取消令牌（`crates/presenter/src/host/addon/pack.rs:28-42`）。 +- **导入冲突逐文件决策**——写盘之前先扫一遍：每个冲突文件（是什么、为什么冲突、多大）分页列出（每页 40 + 条），三个入口定这一批——全部保留、全部覆盖、逐项选择（没点过的行留在「保留」）。不冲突的文件一律不重 + 写，导入报告事后仍逐条列出全部冲突。 +- **内容库**——整合包 / Mod / 资源包 / 光影，带关键词、来源、版本、加载器与排序筛选，分页结果， + 以及一键**装入这个实例**。 +- **在线源：Modrinth（匿名）**——检索走 `/v2/search`，facets 从目标实例推出来（项目类型、游戏版本、 + 加载器）；详情与版本列表随后取，已知摘要的远端条目再用 `/v2/version_file/` 补全。不需要 API key， + 也不发 POST（下载引擎没有请求体字段，所以摘要一条一条 GET 查）。离线是**独立的一态**——「未联网」， + 绝不说成「没有匹配的内容」。 +- **这一页会拒绝什么，就写在那一行上**——整合包**不能**从内容库直接装（整合包走上面的导入管线）； + CurseForge 的「装入」是禁用态，因为它的文件端点还没接通；游戏版本或加载器对不上目标实例的条目也是 + 禁用态，并把不匹配写清楚。没有一条是静默失败的。 +- **CurseForge 检索要 key**——启动前设 `ULL_CF_API_KEY`，没有它这个来源在来源筛选里是灰的。key 只活在 + 环境变量里：不写进配置文件、不进日志（`crates/presenter/src/host/addon.rs`）。 + +### Java + +逐实例的托管 JDK，四家发行版的回退链**按地区排**——Temurin 打头，国内是 Oracle 先于 Microsoft +（那边实测快 28×）、国外反过来，Zulu 收尾——可用 `java.vendorPriority` 设置整体覆盖 +（`crates/core/src/game/java/vendor.rs`）。镜像也按地区选。`java list` 把它真能找到的每个 JDK 都列出来 +（包括官方启动器自己下的那些），`java install <主版本>` 拉一个。游戏要的 JDK 是启动器的数据，不是启动器 +本身的依赖。 + +### 账户 + +三条轨道在同一页： + +- **微软**——OAuth 2.0 设备码流程 → Xbox Live → XSTS → `api.minecraftservices.com`。 +- **第三方社区认证服**（authlib-injector 一类）。 +- **本地离线档案**，用于隔离测试。 + +**微软登录在官方构建里开箱即用。** 发布版二进制已内置它需要的 Azure 公共客户端 id（公共客户端 id 不是 +凭据，本来就随二进制一起分发），所以登录前不需要任何配置。设 `ULL_MSA_CLIENT_ID=` 仍可覆盖内置值： +变量在启动时读取，改完要**重启启动器**。从源码构建时该变量有什么就烘什么（`ULL_MSA_CLIENT_ID= cargo build`， +经 `option_env!` 烧进二进制）。两处都没有 id 的构建点登录**不会联网**，弹窗直接说清是这一项没配：标题 +「微软登录未配置」，正文点名 `ULL_MSA_CLIENT_ID=`（设好或构建时注入后重启），并带 +`代码：msa_not_configured`；它**不给重试按钮**，因为在同一个进程里重试必然是同一个错。其它登录失败仍是 +老样子：一句分类文案 + `代码：<码>`，完整原因只在启动器日志里。第三方社区服与本地档案不需要 id。 + +### 外观与语言 + +- **只有一套 UI 栈**——iced 0.14 + Material 3 Expressive，自绘标题栏、带动效的导航轨，浅色 / 深色 / + 跟随系统。 +- **外观**——窗口背景图与取色链路（面板配色可从壁纸推出来）、面板透明度、整窗透明度（Windows）。Windows 11 + 与 Server 2025 上向系统请求外框圆角；macOS 与 Linux 交给桌面合成器自己的规则；我们不自己画圆角。 +- **CPU 兜底**——`--software-renderer` 让没有可用 GPU 或驱动有问题的机器照样正常显示；没有可用适配器时， + 后端探测自己退到 CPU。这条路上**面板级**半透明与模糊会关掉（**窗口级**透明度照常可用），设置面板会写明。 +- **本地化**——跟随系统语言探测、设置里可显式切换、重启后保持。绝大多数文案来自同一份消息目录 + （`crates/i18n`）。**边界，因为上面这句很容易被读大**：防硬编码的守门 + （`crates/app-iced/src/pages/instances/tests/i18n.rs`）只扫实例页源码，不是每一屏；写死的中文字面量里 + 没有 ASCII 单词可以匹配，这一类它抓不到；外观面板的老控件还是硬编码英文 + （`crates/app-iced/src/pages/appearance/section.rs`），中文界面下它们仍显示英文。 + +### 助手，以及 MCP server + +这是两件不同的事，README 不该含糊： + +- **启动器内的助手今天还是占位壳。** 它的 transport 是脚本化的 + （`crates/app-iced/src/presenter/transport.rs`），没有接真实模型，而且界面上它出现的每一屏都用四处明说 + 这一点——副标题、输入框占位符、空态正文，以及一枚「模拟」胶囊。会话状态、未读数、草稿、确认流程与具名 + 失败码都是真的 presenter 状态；缺的只是它们后面的模型。 +- **MCP server 是真的。** `ull agent serve` 把启动器内核以 MCP server 形态（stdio 或 Streamable HTTP） + 开放给外部 Agent 工具，只监听回环（`127.0.0.1`，默认端口 47823），除非 + `agent.mcp.allow_write=true` 否则只读。十个工具规格（`crates/agent/src/tools/`）同时喂给两种形态，两条 + 路都过同一个执行器——schema 校验、敏感分级、审计留痕。`ull agent config` 能打印现成的 Claude Code / + Cursor 配置片段。 + +### 命令行 + +GUI 二进制在跑任何 UI 代码之前就先认全部 CLI 子命令——不开窗、不探渲染器、不扫字体。另有一份更轻的 `ull` +产物，命令集相同，却一个图形栈都不链接。 + +```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`），所以两个二进制认的命令集天然一致。`ull --help` 会全列出来：`instances`、 +`install`、`launch`、`pack import`、`accounts`、`sessions`、`logs`、`diag`、`config`、`java`、`update`、 +`agent`、`version`、`help`。 + +### 自更新与稳定通道 + +- **自更新是真的，而且 GUI 与 CLI 共用同一个内核。** 设置页的「更新」组与 `ull update check` / + `ull update apply` 造的是同一个 `core::update::Job`（`crates/core/src/update/`）：取 + `releases/latest/download/manifest.json`、比版本、过渠道准入、校验长度 + SHA256，再原子换包——把旧文件 + 改名挪开、把新的搬进去，失败就回滚。Windows 上正在运行的 exe 能**改名**、不能覆盖，所以换包是改名。 +- **四种结论不许混**：已是最新 / 有可装的更新 / 有更高版本但里面没有本平台产物 / 检查本身失败（断网、清单坏、 + 渠道不符）。失败绝不会被说成「已是最新」。 +- **只发布 stable 通道。** `update.channel` 默认 `stable`；beta / alpha / nightly 已建模但不发。清单准入要两条 + 同时成立——清单自称的渠道与版本号里的预发布阶段：清单会撒谎，版本号不会。 +- **为什么发布必须被标成稳定版**：`releases/latest/download/*` 只指向**非 prerelease** 的最新 Release，而清单 + 地址就钉在它上面。`0.2.3` 是第一个不带预发布标记建出来的版本（`0.2.2` 保留为历史预发布）。「哪种触发创建什么 + 标记」只有一张表（`packaging/release_marker.py`），并由 `packaging/check_release_semantics.py` 守着。 +- **没有任何东西背着你自动安装。** 启动时的检查可以关掉（`update.auto_check`，CLI 读的是同一个键），安装要么是 + 点按钮，要么是显式 `ull update apply`。调试构建可以拿本地目录源把整条链演练一遍（`ULL_UPDATE_DIR`）；发布 + 构建里**不存在**这条路径。 + +### 日志在哪 + +启动器自己这一侧写的东西全在 `<数据根>/logs/` 一个目录里。设置页有一行**日志文件夹**，直接显示这个 +路径，旁边是 *打开文件夹* 与 *复制路径*；日志页页头也有 *打开文件夹*。 + +![设置页「通用」分组：日志文件夹一行，显示 D:/ULL-Demo/.ULL/logs，旁边是「打开目录」与「复制路径」两个按钮，下面是解释文案](docs/images/logs-folder-zh.png) + +*设置页 → 通用 → 日志文件夹。路径就是当前实际生效的日志根（便携 / 标准 / 自定义三种数据模式各自不同）， +打开失败时这一行照样显示，右按钮把路径送进剪贴板。* + +数据根按三种模式取值：便携是 `/.ULL`，标准是 `<用户应用数据目录>/ULL`，自定义是 +`<自定义根>/.ULL`——与设置页显示的「启动器数据目录」是同一个值。 + +| 路径 | 是什么 | +|---|---| +| `logs/launcher.log` | 启动器自己的运行日志：后端探测、字体/主题决策、后端选择、**渲染后端起不来时的具名原因**，以及每一次启动（命令行事实、spawn 结果、退出码）。满 1 MiB 滚成 `logs/launcher.1.log`，**只留一份**旧档，所以它不会无限长大。 | +| `logs/launcher.1.log` | 上一份 1 MiB，下次滚动时被替换。 | +| `logs/game/.jsonl` | 每次启动一份 JSONL 事件流：命令行（已脱敏）、每一行 stdout/stderr、退出码。 | +| `logs/game/index.jsonl` | 一会话一行摘要的索引，日志页左栏读的就是它。 | +| `logs/install.log` | 安装流水：每个阶段一行。 | +| `logs/session-log-location.json` | 会话日志现在在哪、以前在哪的记录，每次启动重写。 | +| `data/agent/sessions/game/…` | **只读兼容**：旧版本写下的会话。仍然列得出来、打得开；不搬动、不删除任何一个文件。 | + +游戏自己的文件不在这里，而在实例的运行目录里：`logs/latest.log`、`crash-reports/crash-*.txt`、 +`hs_err_pid*.log`。**`crash-reports/` 只在 JVM 活到那一步时才存在。** 模组、缺库或 Java 选错把游戏 +弄死在 Minecraft 初始化之前时，游戏根本没机会写它——那种时候诚实的证据是会话 JSONL 与 +`launcher.log`，不是崩溃报告。这是游戏的行为，不是启动器藏了什么。 + +### 还没做 + +这份清单是让人相信上面那些话的理由。没有一条藏在宣传话术后面。 + +- **没有安装包。** 下个文件直接跑——没有安装步骤；更新是就地替换那个文件，不装任何东西 + （见[自更新与稳定通道](#自更新与稳定通道)）。 +- **更新链路只用本地目录源演练过。** 整条链（清单 → 下载 → SHA256 → 改名/回滚）是拿调试构建 + 夹具跑的， + 因为 `0.2.2` 还是预发布期间读不到真实的 `releases/latest/download/manifest.json`。线上稳定通道的第一次 + 观察要等 `0.2.3` 发出去之后。 +- **有一批按钮是占位。** 实例页：*新建实例*、*导入*、*复制*、*打开文件夹*、*删除*。 + 设置页框架：*保存*、*重置本组*、*添加覆盖*。点下去只往 stderr 写一行 `[page] 占位动作 …`，什么都不改 + ——图形界面里的实例管理就是还欠着的那块实例向导；设置项是边改边生效，而不是靠「保存」。 + （日志页与设置页的「打开日志文件夹」**不再**是占位：它真的会打开 `<数据根>/logs`，见[日志在哪](#日志在哪)。） +- **Linux x64 已发布，但「已发布」= 真能跑，不等于观感已定型。** 发布流水线默认就在原生 Ubuntu 22.04 上编 + `linux-x64` 并发出去，依据是：release 产物本身在真显示服务（WSLg）下起过窗、渲出一帧非空白画面、主题与渲染 + 后端的日志行齐全（实测输出见 `packaging/docs/linux-evidence.md`），而且同一条判据已经常驻成发布流水线里 + **这个槽位**的门禁。还没人看过的：真实桌面发行版上的拖动/缩放，以及真桌面会话里的字体度量与中文整形。 + 「整窗透明度」与「圆角」这两条在 Linux 上**根本没有代码路径**（不是未验）：前者要窗口句柄，Linux 上拿不到 + （`hwnd=none`）；后者交给桌面合成器（`corner=policy=system`），我们不自己画。 + `linux-arm64` 只是**编出来了，没发布**——没有任何 ARM64 机器跑过它一帧，产物只作构建证据留着。 +- **macOS 不由发布流水线构建，也未定型。** 有两轮真机证据（Apple Silicon），构建因此存在——但菜单栏显示名、 + 三个窗口按钮的位置（macOS 习惯在左上，我们自绘在右上）、300s+ 稳态仍需真机复核。macOS 产物未签名， + 首次启动要自己清掉 Gatekeeper 隔离标记（`xattr -d com.apple.quarantine`）。macOS 运行期冒烟是手动 + `workflow_dispatch` 的探针、带 `continue-on-error`，不是门禁；`gh workflow run release.yml -f all_slots=true` + 能编这两档取证，但它们从不发布。 +- **内容库页在低窗口高度下会挤**，而且窗口高度还没接进页面模型——这一页按一个名义高度排版，而不是按它 + 真正拿到的高度。 +- **启动侧失败提示未结构化。** 磁贴直接采用启动层抛出的中文句子 + （`crates/core/src/launch/exit_analysis.rs`），而不是一个界面能翻译的原因码——上面那张英文截图里的 + `静默失败` 就是它。 +- **启动器内的助手背后没有模型**（见上）。MCP server 有。 +- **内容库的安装进度是阶段级**，不是字节级。 +- **没有原生文件选择框。** 导入靠拖拽或粘贴路径。 +- **Android/Termux 是试验级、不承诺**：发布矩阵里没有面向它的资产。GUI 可以经 glibc 工具链源码自建（见 `packaging/docs/termux-glibc-build.md`，分支说明见 [`README.termux.md`](README.termux.md)），已真机验证两条路径各一次：CPU 软渲染，以及自编 Mesa/turnip 栈的 GPU 加速（证据见 `README.termux.md`）。 + +## 下载与运行 + +从 [Releases](https://github.com/AskaEth/Unlucky-Launcher/releases) 拿你那个平台的文件。文件名形如 +`unlucky-launcher_<版本>_<平台>_<架构>`；这个形状的唯一真相源是 +`packaging/make_artifacts.py::asset_stem()`： + +| 槽位 | 产物 | 形态 | +|------|------|------| +| `windows-x64` | `unlucky-launcher_<版本>_windows_x64.exe` | 裸 `.exe`，双击即用 | +| `linux-x64` | `unlucky-launcher_<版本>_linux_x64.tar.gz` | 单个归档，解压出一个顶层目录；要 glibc 2.35+ 与 X11/Wayland + fontconfig 那一套 | +| `windows-arm64` | `unlucky-launcher_<版本>_windows_arm64.exe` | 裸 `.exe` —— **编了、不发布**，见下 | +| `linux-arm64` | `unlucky-launcher_<版本>_linux_arm64.tar.gz` | 同上 —— **编了、不发布**（运行时零证据） | +| `macos-arm64` | `unlucky-launcher_<版本>_macos_arm64.tar.gz` | 同上 —— 发布流水线**不构建** | +| `macos-x64` | `unlucky-launcher_<版本>_macos_x64.tar.gz` | 同上 —— 发布流水线**不构建** | +| 每个已发布槽位 | `ull_<版本>_<平台>_<架构>[.exe]` | 裸 CLI 文件，独立资产 | +| 全平台 | `SHA256SUMS.txt` | `sha256sum -c` 可直吃 | + +**本版发布 `windows-x64` 与 `linux-x64`，就这两档。** 发布 job 只留 `PUBLISH_SLOTS` 里点名的槽位 +（`.github/workflows/release-publish.yml`），其余产物在写 `SHA256SUMS.txt` 之前就被删掉——所以表里标 +**不发布** 的行是命名规则，不是本版可下载的资产。三条关系都有守卫（`packaging/check_publish_slots.py`）： +名单里点名了却没产物 ⇒ Release 变红（`linux-x64` 构建红了就挡住整次发布，靠的就是这条）；产物在、名单没点名 +⇒ 显式打「未发布」警告，不再静默删掉；`mode: ci` 的槽位本次连产物都没有（那一档红了）⇒ 也打警告。 + +不发布的行里 CI 真编两档。`windows-arm64` 在 GitHub 原生 `windows-11-arm`（Windows 11 Arm64 + Visual Studio +2026）上编来取证——**诚实一句**：此前每一次 arm64 红都红在**编译前的工具链体检**，`cargo build` 一次都没跑过； +M164 把那个体检降级成只取证，所以**下一条 tag 的 CI 才是第一次真正问编译器**。`linux-arm64` 在原生 +`ubuntu-22.04-arm`（与 x64 同 glibc 地板）上编，不发布的理由完全不同：**没有任何 ARM64 机器跑过它**。 +解锁条件 = 真机渲出一帧 + 主题/后端日志行，之后才把键加进 `PUBLISH_SLOTS`。 + +Linux x64 的安装就是解开归档直接跑： + +```bash +tar -xzf unlucky-launcher_<版本>_linux_x64.tar.gz +cd unlucky-launcher_<版本>_linux_x64 +./unlucky-launcher # 没有可用 GPU 适配器就加 --software-renderer +``` + +载入期要 glibc 2.35+、`libxkbcommon`、`fontconfig`、`libGL`；Debian/Ubuntu 上 +`sudo apt-get install libxkbcommon0 libfontconfig1 libgl1 libx11-6 libxcursor1 libxrandr2 libxi6` 就够。 +与归档并列的裸 `ull_<版本>_linux_x64` 连显示都不需要。 + +UNIX 归档里是二进制加 `LICENSE`、`NOTICE`、`README.md`，都在一个顶层目录下。Windows 发的是裸 `.exe` +（一个文件装不下这三份文本），所以这三份作为并列资产挂在 Release 上——下 Windows 二进制不会把许可条款 +弄丢。下载链接里不带实现细节字样，归档里的二进制名永远是 `unlucky-launcher`。 + +这两种形态不是重复品。GUI 二进制开窗时要用图形栈（X11 / Wayland / GL 走 `dlopen`，启动时直接链接 +`libfontconfig`）；`ull` 除了 glibc 什么都不需要，所以在没有窗口的服务器、CI 容器上跑得起来。Linux 上这个 +地板是 glibc ≥ 2.35（槽位在 Ubuntu 22.04 上构建）——更老的发行版得源码自建（`packaging/README.md` §4）。 +没有桌面就用 `ull`，有桌面就用 `unlucky-launcher <子命令>`。两者打出来的 CLI 文案是同一套，自称的名字跟着 +**你敲的那个文件**走——`argv[0]` 去掉目录与结尾的 `.exe`，别的都不剥 +（`crates/cli/src/cli/program.rs`），所以 `ull` 打印 `ull ·`，归档里那个二进制打印 +`unlucky-launcher ·`，本地 `cargo build` 出来的打印 `unlucky-launcher-iced ·`。 + +最低平台基线：**Windows 10**；Windows 8.1 / 8 / 7 不在支持范围内。macOS 12+（Apple Silicon 与 Intel）， +Linux x64 / arm64（基线判定在 `crates/core/src/platform/os_info.rs`）。Windows 10/11 的产物由标准工具链 +（MSVC / GNU）构建，构建方式与上游 cargo 一致。Linux 上 X11 是当前首选路径，Wayland 是大方向。能力差异 +一律用 feature gate + 运行期探测表达，绝不做成「这个平台天生少一块」的编译期裁剪。 + +第一次用微软账户？不用配置——官方构建已内置客户端 id，见[账户](#账户)。其它都不需要配置。 + +## 从源码构建 + +前置： + +- 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 编译期要用 + +```bash +cargo fmt --all --check # 格式 +cargo clippy --workspace --all-targets -- -D warnings # 静态检查（零 warning 门禁） +cargo test --workspace # 测试 +cargo build --release # bin 落在 target/release/ +cargo deny check licenses bans sources # 依赖许可（CI 必跑） +``` + +编出来的 bin： + +- 从源码构建默认不带微软客户端 id：想让产物自带，就在构建时设 `ULL_MSA_CLIENT_ID`（`ULL_MSA_CLIENT_ID= + cargo build`）；官方发布产物已内置，见[账户](#账户)。 +- `unlucky-launcher-iced`——GUI，同时也是 CLI：同一个文件认上面列的全部子命令。名字里的 `iced` 是 cargo + 的 bin 名，不是下载名——`packaging/make_artifacts.py` 把同一次构建落成 + `unlucky-launcher_<版本>_<平台>_<架构>`，归档里的二进制名写成 `unlucky-launcher`。 +- `ull`——CLI 的独立无 UI 构建：同一套命令、不链接图形栈、体积更小，给完全没有显示设备的机器用。 + +渲染开关： + +- `unlucky-launcher-iced --software-renderer` 强制 tiny-skia（`ICED_BACKEND=tiny-skia`）； + `--screenshot ` 出一帧图后退出——这是 CI 无头冒烟 job 用的验收通道 +- 没有可用适配器时，iced 版靠显式后端探测自己退到 CPU + +**CI 门禁。** 每次推送到 `main` 与每个 PR 都跑 fmt / clippy（warnings 视为错误）/ 全量测试，Linux 无头 +渲染冒烟与它们同级、是硬门禁：在 Xvfb 里真渲染一帧，再断言 PNG 非空白，红了就不许合。macOS 探针还不算 +——只手动 dispatch，结果留证据但不作为流水线结论。 + +| 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` / `crates/presenter` / `crates/design` 零 UI 守门、单文件 ≤400 行守门、cargo-deny 许可与来源守门 | +| `.github/workflows/release.yml` | tag `v*` → 构建默认四档（`windows-x64` + `windows-arm64` + `linux-x64` + `linux-arm64`，各自原生 runner）→ 单文件产物 + `SHA256SUMS.txt` → GitHub Release（发布 `windows-x64` 与 `linux-x64`；`linux-x64` 另有一条同槽位的 Xvfb 首帧门禁；`-f all_slots=true` 才整表六槽位取证） | +| `.github/workflows/release-guard.yml` | 发布标记语义守门：push tag ⇒ **稳定版**、dispatch `prerelease=true` ⇒ 预发布；标记表在 `packaging/release_marker.py`，守门会对自己做变异自测 | + +## 架构与模块地图 + +``` +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-iced # iced UI（bin `unlucky-launcher-iced`）：workspace 里唯一的 GUI bin +├── crates/cli # CLI（bin `ull`）：headless，零 UI +└── packaging # 单文件产物矩阵与发布脚本 +``` + +层间纪律：`app-iced` → `presenter` → `core` / `agent`。`design` 与 `i18n` 只被壳层与 presenter 消费； +它们都不得反过来依赖渲染框架，CI 守门会拦。 + +`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 检测 | + +## 许可证与致谢 + +- **本项目**：Apache License 2.0，见 [LICENSE](LICENSE)；第三方声明见 [NOTICE](NOTICE)。 +- **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/TERMUX-ADAPTATION.md b/TERMUX-ADAPTATION.md new file mode 100644 index 0000000..441c59a --- /dev/null +++ b/TERMUX-ADAPTATION.md @@ -0,0 +1,144 @@ +# Termux 适配：方案、改动清单与合并指南 + +> 分支：`termux-glibc`（基于 `origin/dev`，15 个提交，分叉点 `87ab878`，合并前 HEAD `e987e02`） +> 目的：让主线快速了解这组代码改了什么、为什么、怎么验证、如何合并。 + +## TL;DR + +- **构建**：为 Termux 编出 `aarch64-unknown-linux-gnu`（glibc）二进制，在 termux-x11 里跑 GUI。 + Android 原生 target 走不通（winit 的 android 后端需要 NativeActivity），所以不用它。 +- **已跑通**：GUI（CPU 与 GPU 两条渲染路径）、中文、横屏自适应、JDK 发现与系统包安装、 + MC 1.20.4（glibc JRE + arm64 natives + softpipe GL，真机进游戏）。 +- **未收口**：MC 启动参数支持（由主线后续补）、MC 硬件 GL（zink 卡 DRI3）、剪贴板/IME。 +- **对主线的影响**：所有行为都由 **运行时 Termux 识别 / `cfg(target_os = "linux")` / + 文件存在** 三选一 gate 住，Windows / macOS / 普通 Linux 的默认路径不变。 + +## 方案 + +### 1. 平台识别 + +`crates/core/src/platform/termux.rs`：用 `TERMUX_VERSION` 或默认 `PREFIX` +（`/data/data/com.termux/files/usr`）识别 Termux，推导 `$PREFIX` 与 `$PREFIX/lib/jvm`。 +不把路径写死到调用方，也不改 `OsFamily`（Android 上仍按 Linux 家族处理）。 + +### 2. JDK：发现 + 安装 + +- **发现**：`game/java/discover.rs` 的 Unix 扫描根追加 `$PREFIX/lib/jvm`， + 环境可注入（`standard_roots_in`）。补上「Termux 装了 openjdk 但没设 JAVA_HOME/PATH」的盲点。 +- **安装**：新增 `game/java/termux.rs`。Termux 的 openjdk 是 `.deb`（bionic）， + 与 Temurin 的 zip/tar.gz 不是同一形态，所以**委托包管理器**： + - 内置 SAU / TUNA / USTC / 官方四个 termux-main 镜像，按顺序 `apt-get update && install`； + - lists/cache 隔离在 `$PREFIX/tmp/ull-java-termux/`，不污染用户 apt 配置；装完清理； + - 装完从 `$PREFIX/lib/jvm` 定位，幂等（已装则不走网络）。 +- **vendor 接线**：`JdkVendor::Termux`（17/21/25）。Termux 上缺省安装先试系统包， + 失败再走归档链；`--vendor termux` 只走系统包。设置白名单与契约测试同步。 + +### 3. 字体 + +`crates/app-iced/src/fonts.rs`：Termux 上把 `/system/fonts/NotoSansCJK-Regular.ttc` +注册进 cosmic-text（fontdb 不扫 Android 字体目录），中文不再显示方框。 + +### 4. 窗口（横屏优先） + +`app/boot/termux_window.rs`：Termux 上默认窗口按当前 X 屏幕等比自适应 +（日志 `size_source=termux-screen`），横屏铺满、竖屏不溢出； +`ULL_WINDOW_SIZE` 覆盖与 1180×760 验收基准不变。 + +### 5. GPU（启动器） + +- 驱动是自编的 **Mesa 26.2.6 + KGSL**，装在 `$PREFIX/glibc/{lib,share/vulkan/icd.d}`； + 构建/安装步骤见 `packaging/docs/termux-glibc-build.md` §5。 +- `app/boot/termux_gpu.rs`：glibc 构建 + Termux + ICD 文件存在时，在探测前设 + `VK_ICD_FILENAMES` / `VK_DRIVER_FILES`；用户显式设置不覆盖。 +- 实测 wgpu 选中 Adreno 840（turnip Mesa 26.2.6）；无驱动自动降级 tiny-skia。 + +### 6. Minecraft 运行链 + +- **natives**：1.19+ 的清单把 natives 作为独立库条目（`org.lwjgl:...:natives-linux`）， + Linux/aarch64 上改写成 `natives-linux-arm64`（`Library::linux_arm64_native_name`， + install 与 launch 共用）；Mojang 的 `libraries.minecraft.net` 对 arm64 一律 404， + 下载兜底到阿里云 Maven（`install/libraries.rs`）。 +- **JVM**：用 glibc 的 Temurin JRE（patchelf 后直接执行），bionic 的 Termux JVM + 加载不了 glibc natives。 +- **GL**：glibc Mesa 的 zink 在 termux-x11 下卡 `DRI3 not available`， + 子进程默认带 `MESA_LOADER_DRIVER_OVERRIDE=swrast` + `LIBGL_ALWAYS_SOFTWARE=1` + （`launch/defaults.rs`，用户自定义环境变量可覆盖）。 + +## 改动清单 + +| 文件 | 改动 | 平台隔离 | +| --- | --- | --- | +| `core/platform/termux.rs`（新） | Termux 识别、`$PREFIX`/JVM 根 | 纯函数，按环境判断 | +| `core/platform/mod.rs` | 导出新模块 | — | +| `core/game/java/discover.rs` | `$PREFIX/lib/jvm` 扫描 | Unix + Termux 判断 | +| `core/game/java/termux.rs`（新） | 镜像/隔离 apt 安装、`installed_home` | 仅 Termux 可执行 | +| `core/game/java/vendor.rs` / `source.rs` / `install.rs` | `JdkVendor::Termux` 与安装分派 | Termux 上才启用 | +| `core/setting/keys.rs` + 契约测试 | 白名单加 `termux` | 跨平台可选，非 Termux 明确报错 | +| `cli/commands/java_vendors.rs`、`cli/cli/help.rs`、`presenter/host/java.rs` | 展示与帮助文案 | 展示层 | +| `core/game/library.rs` | `linux_arm64_native_name` / 分类器改写 | 仅 linux+arm64 | +| `core/game/install/libraries.rs` | 现代 natives 条目改写 + Maven 兜底 | 仅 linux+arm64 | +| `core/launch/defaults.rs` | Termux softpipe 环境默认值 | `cfg(linux)` + Termux | +| `presenter/host/launch.rs`、`cli/commands/snapshot.rs` | classpath 用改写后的 arm64 坐标 | 仅 linux+arm64 | +| `app-iced/fonts.rs` | Android CJK 字体注册 | 仅 Termux | +| `app-iced/boot/termux_window.rs`（新） | 横屏自适应 | 仅 Termux | +| `app-iced/boot/termux_gpu.rs`（新） | 自动启用自编 ICD | 仅 glibc+Termux+文件存在 | +| `app-iced/Cargo.toml` | 新增 `unlucky-core` 依赖 | 复用平台识别 | +| `README.termux.md`（新）、`packaging/docs/termux-glibc-build.md`（新） | 分支说明与构建配方 | 文档 | +| `README.md` / `README.zh-CN.md` / 支持矩阵两处 | Termux 行同步 | 文档 | + +## 行为变化与兼容性 + +- 新增 `JdkVendor::Termux` 会改变 `VENDOR_IDS` / `JDK_VENDORS` 的允许值集合 + （契约测试已同步）。非 Termux 上显式选它会在安装时明确报「只在 Termux 里可用」， + 默认回退序**不含** termux，PC 行为不变。 +- Linux/aarch64 的 LWJGL3 natives 会被改写；x86_64、Windows、macOS 不受影响。 +- `app-iced` 直接依赖 `unlucky-core`（此前通过 cli/presenter 间接依赖）。 +- 所有 Termux 专属路径都需要运行时识别或文件存在才会生效；普通 Linux 桌面不会触发。 + +## 合并指南 + +1. ~~`git fetch origin && git rebase origin/dev`~~ → **实际按用户令走 `--no-ff` 合并** + （M156）：`git merge --no-ff origin/termux-glibc`，15 个原提交一字未改地留在历史里， + 按平台识别 → 字体 → 文档 → Java → GPU → natives → MC 的分组可整组 revert。 + 与 dev 前进的 12 个提交**零文本冲突**（交集只有 `Cargo.lock` / 两个 README / + `crates/app-iced/Cargo.toml`）。 +2. PR base：`dev`。CI 门禁：`fmt` / `clippy --workspace --all-targets -D warnings` / + `test --workspace --all-targets` / `cargo deny`（本机没装 deny，PC 上补跑）。 +3. 本机已知、**不影响 PC CI** 的三条失败： + - `unlucky-core --test launch`：`/proc//task//children`（Android 内核没有） + - 同测试：长路径被脱敏成 `` + - `presenter settings_bridge`：mtime 热重载偶发（flaky，单跑 3 次 2 过 1 挂） +4. **不要提交**：`dist/`、`.gnu/`、任何 `ULL_MSA_CLIENT_ID` 值（仓库 Secret）。 +5. 合并后建议真机再跑一次：`--software-renderer` 截图 + `ull java install 17` + MC 启动。 +6. **PC 门禁发现的两处、已在 M156 就地修掉**（都只在 Windows/PC 侧才暴露， + 所以在 Termux 上跑门禁看不出来）： + - `game/java/discover.rs` 的两个 `#[cfg(unix)]` 测试，导入没跟着 gate + → Windows 上 `-D warnings` 判「未使用导入」。已把两个 `use` 同样 gate 成 `#[cfg(unix)]`； + 代价是这两个用例在 Windows 上不编译（由 Linux CI 覆盖）。 + - 本分支把 `game/java/install.rs`（456 行）与 `game/install/libraries.rs`（409 行） + 顶过了 400 行红线（`guards.yml` 的 `file-size`）。已按步骤拆出 + `install/termux_install.rs`、`install/one.rs`、`install/libraries/arm64_natives.rs`， + 行为不变、用例原样留在原处。 + +## 验证矩阵（本机） + +| 项 | 结果 | +| --- | --- | +| GUI 截图（横屏 1657×1067） | ✅ 中文正常，`client_id=configured source=build` | +| GPU 渲染 | ✅ wgpu 选中 Adreno 840（turnip Mesa 26.2.6）；降级路径也验证过 | +| `ull java install 17` | ✅ SAU 镜像约 20 s，装完清理，`java list` 可见 | +| MC 1.20.4 | ✅ 真机安装（740 MB）→ 主菜单 → 建世界 → 进游戏 | +| fmt / clippy / 核心测试 | ✅ 475 条核心测试通过，clippy 零告警 | + +## 后续路线 + +1. **MC 启动参数**（主线功能，另行排期）：当前 `ull launch` 不接受自定义 JVM/游戏参数。 +2. **MC 硬件 GL**：修 glibc GLX 的 DRI3（让 zink 生效），或改用 VulkanMod。 +3. 剪贴板 / IME 在 termux-x11 下的行为验证。 +4. narrator/flite 与音频设备（当前缺失但不阻断）。 +5. GPU 驱动分发：目前每次都要按文档自编 Mesa；可考虑脚本化/预编译产物。 + +## 回滚策略 + +全部改动按提交分组（platform → fonts → docs → java → gpu → natives → mc）， +可按组 revert；Termux 专属逻辑都有运行时/文件存在 gate，回滚不会波及 PC 路径。 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..db18ec1 --- /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.4" } + +# 序列化：工具 JSON Schema 是手写 serde_json::Value（不引 schemars）， +# 工具结果 / 审计记录 / 事件流都用 serde derive。 +serde.workspace = true +serde_json.workspace = true + +# LLM Provider + agent 循环。**锁精确版本**：rig 12 周 5 个 minor、CHANGELOG 满是 breaking +# （DevDocs/PlanDoc/02-ai-agent-design.md §0 + research/02 §7 R1）。升级必须单独提交并跑回放回归。 +# 依赖面收口：整个 crate 只有 src/brain/rig.rs 允许 `use rig_*`。 +# feature `reqwest`：rig-core 0.45 的 default 只有 derive + rustls，HTTP 客户端要显式开；TLS 走 rustls +# （免 OpenSSL，对 Win7/MinGW 友好，见 research/02 §7 R3）。 +rig-core = { version = "=0.45.0", features = ["reqwest"] } +# TODO(M16-P1): 目前**声明但未使用**——对话循环/工具编排是自研的（要在中间插确认与审计）。 +# 保留是为了把版本按 02 §0 钉死；P1 接 rig 的 agent 运行时（工具服务句柄 / rig-cassette 回放 / +# rig-rmcp 让内置 agent 吃 MCP）时再真正消费。若 P1 决定彻底不用，删这一行即可。 +rig-agent = "=0.45.0" + +# 异步运行时（rig 的 HTTP/流式需要）与流工具（消费 rig 的 Stream）。 +tokio.workspace = true +futures-util.workspace = true + +# MCP server（M39）：rmcp 3.8 投影 + stdio / Streamable HTTP 传输。 +# 依赖面收口纪律与 rig 相同——整个 crate 只有 src/mcp/ 允许 `use rmcp::`。 +rmcp.workspace = true +axum.workspace = true + +[lints] +workspace = true 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）。 +//! +//! 落盘位置由装配处给（`/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` 通常是 `/agent/audit`；目录按需创建。 + #[must_use] + pub fn new(dir: impl Into, 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>, +} + +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 { + self.records.lock().map(|r| r.clone()).unwrap_or_default() + } + + /// 按工具名筛出记录（测试断言用）。 + #[must_use] + pub fn records_for(&self, tool: &str) -> Vec { + 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, + } +} + +/// 便捷：给出数据根下的审计目录（`/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, + }, + /// 工具结果回灌。 + Tool { + /// 对应调用 id。 + call_id: String, + /// 工具名（Ollama 原生靠 `tool_name` 配对，不是 id）。 + name: String, + /// 结果 JSON 字符串。 + content: String, + }, +} + +impl ChatMessage { + /// 便捷：系统消息。 + #[must_use] + pub fn system(content: impl Into) -> Self { + Self::System { + content: content.into(), + } + } + + /// 便捷：用户消息。 + #[must_use] + pub fn user(content: impl Into) -> Self { + Self::User { + content: content.into(), + } + } + + /// 便捷：工具结果消息。 + #[must_use] + pub fn tool( + call_id: impl Into, + name: impl Into, + content: impl Into, + ) -> 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, + /// 工具定义（双投影的 rig 侧载荷）。 + pub tools: Vec, + /// 采样温度。 + pub temperature: Option, + /// token 上限。 + pub max_tokens: Option, +} + +/// token 用量（本地模型可能不报）。 +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)] +pub struct Usage { + /// 输入 token。 + pub prompt_tokens: Option, + /// 输出 token。 + pub completion_tokens: Option, +} + +/// 一次补全结果。 +#[derive(Debug, Clone, Default, PartialEq)] +pub struct ChatReply { + /// 文本正文。 + pub text: String, + /// 工具调用（非空 ⇒ 循环继续）。 + pub tool_calls: Vec, + /// 用量。 + pub usage: Option, +} + +impl ChatReply { + /// 纯文本回复。 + #[must_use] + pub fn text(text: impl Into) -> Self { + Self { + text: text.into(), + tool_calls: Vec::new(), + usage: None, + } + } + + /// 带工具调用的回复。 + #[must_use] + pub fn with_tool_calls(tool_calls: Vec) -> 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, +} + +impl EventDeltaObserver { + /// 用事件流构造。 + #[must_use] + pub fn new(sink: Arc) -> 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>, +} + +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> + 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 Result, 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 = 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) -> 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, + audit: Arc, + gate: Arc, + policy: ConfirmPolicy, + clock: SharedClock, + sink: Arc, + guidance: DenyGuidance, + confirm_seq: AtomicU64, +} + +impl ToolExecutor { + /// 装配（默认拒绝口径 = 内置对话：[`DenyGuidance::InApp`]）。 + pub fn new( + registry: Arc, + audit: Arc, + gate: Arc, + policy: ConfirmPolicy, + clock: SharedClock, + sink: Arc, + ) -> 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..047a7f2 --- /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`，含 tool_call 事件。 +//! 本 crate 的落地形态是 [`chat::ChatProvider::complete`]（`request + observer → ChatReply`）： +//! rig 0.45 的流在 [`rig`] 适配层里展开成增量回调，循环侧只消费「文本增量 + 工具调用」两件事。 +//! **rig 依赖面收口在 [`rig`] 一个文件**，本文件不 `use rig_*`。 +//! +//! ## 对话循环（02 文档 §3.3） +//! +//! ```text +//! run_turn(user_input) +//! ├─ provider.complete(request) ← 流式增量经 EventDeltaObserver → UI +//! ├─ 有 tool_calls → ToolExecutor.execute（校验/确认/YOLO/审计）→ Tool 消息回灌 +//! └─ 没有 tool_calls → 结束，返回最终文本 +//! ``` +//! +//! 三条不变量： +//! 1. **system prompt 每轮重新注入**，不进历史（改提示词立刻生效，也不会被压缩逻辑吃掉）； +//! 2. 工具结果**永远回灌**（包括失败），模型才有机会改正； +//! 3. 步数上限 [`DEFAULT_MAX_STEPS`] 兜底，防止模型在两个工具间打转烧 token。 + +pub mod chat; +pub mod exec; +pub mod provider; +pub mod rig; + +use std::fmt; +use std::sync::Arc; + +use crate::audit::AuditSink; +use crate::clock::SharedClock; +use crate::confirm::{ConfirmGate, ConfirmPolicy}; +use crate::event::{AgentEvent, AgentEventSink}; +use crate::registry::ToolRegistry; + +pub use chat::{ + ChatMessage, ChatProvider, ChatReply, ChatRequest, DeltaObserver, EventDeltaObserver, + NoopObserver, ProviderFactory, ProviderFuture, ToolCall, Usage, +}; +pub use exec::{ToolExecOutcome, ToolExecutor}; +pub use provider::{ProviderConfig, ProviderError, ProviderFailure, ProviderKind}; + +/// 一轮对话最多几轮工具调用。 +pub const DEFAULT_MAX_STEPS: usize = 8; + +/// 内置系统提示词（P0 版本；P2 会按实例上下文按需注入）。 +#[must_use] +pub fn default_system_prompt() -> String { + [ + "你是 Unlucky-Launcher（ULL，Minecraft 启动器）的内置助手。", + "你能调用工具：读配置（get_config）、改配置（set_config）、列出游戏会话（list_game_sessions）、", + "读会话日志（read_game_log）、跑崩溃规则引擎（diagnose_crash）。", + "纪律：", + "1. 先查后改：改任何配置前先用 get_config 确认键名与现值。", + "2. 崩溃问题先看 diagnose_crash 的规则结论；规则未命中或需要更多信息时，才用 read_game_log", + " 取 stderr / exit / crash_found，不要拉全量日志。", + "3. 只能改 get_config 列出的可写键。敏感键会要求用户确认：被拒绝就换方案，不要重复尝试同一改动。", + "4. 用中文回答，给用户可以立即执行的下一步；不确定时直说不确定，不要编造规则或日志内容。", + ] + .join("\n") +} + +/// 循环参数。 +#[derive(Debug, Clone)] +pub struct BrainConfig { + /// 最多几轮工具调用。 + pub max_steps: usize, + /// 系统提示词。 + pub system_prompt: String, +} + +impl Default for BrainConfig { + fn default() -> Self { + Self { + max_steps: DEFAULT_MAX_STEPS, + system_prompt: default_system_prompt(), + } + } +} + +impl BrainConfig { + /// 自定义提示词（步数用默认）。 + #[must_use] + pub fn with_system_prompt(system_prompt: impl Into) -> Self { + Self { + max_steps: DEFAULT_MAX_STEPS, + system_prompt: system_prompt.into(), + } + } +} + +/// 循环的旁路依赖（审计/确认/时钟/事件）。 +pub struct BrainDeps { + /// 审计出口。 + pub audit: Arc, + /// 确认闸门（P0 = [`crate::confirm::NoUiGate`]）。 + pub gate: Arc, + /// YOLO 等策略快照。 + pub policy: ConfirmPolicy, + /// 时间源。 + pub clock: SharedClock, + /// 事件出口。 + pub sink: Arc, +} + +impl BrainDeps { + /// 装配。 + pub fn new( + audit: Arc, + gate: Arc, + policy: ConfirmPolicy, + clock: SharedClock, + sink: Arc, + ) -> 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, + registry: Arc, + executor: ToolExecutor, + config: BrainConfig, + sink: Arc, +} + +impl Brain { + /// 装配。 + pub fn new( + provider: Arc, + registry: Arc, + deps: BrainDeps, + config: BrainConfig, + ) -> Self { + let executor = ToolExecutor::new( + Arc::clone(®istry), + 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, + user_input: &str, + ) -> Result { + 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..62525d6 --- /dev/null +++ b/crates/agent/src/brain/provider.rs @@ -0,0 +1,324 @@ +//! Provider 四态端点配置（02 文档 §2）。 +//! +//! | 形态 | 端点 | 备注 | +//! |------|------|------| +//! | OpenAI 兼容（默认） | `base_url` + `api_key` + `model` | 覆盖 OpenAI/DeepSeek/Qwen/GLM/**本地 llama.cpp server**（`http://127.0.0.1:8080/v1`）/LM Studio | +//! | Anthropic 原生 | `api_key` + `model` | Claude 系列（没有可用的 Rust 单厂商 SDK，见 research/02 §3.6） | +//! | Ollama 原生 | `http://127.0.0.1:11434` | 本地另一种主流 | +//! | 禁用 | — | 完全关闭 agent，规则引擎（`diagnose_crash`）仍可用 | +//! +//! 本文件只放**配置与校验**；对话协议在 [`super::chat`]。这样 rig 的 pre-1.0 破坏面 +//! （research/02 §7 R1）被关在 [`super::rig`] 一个文件里，这里连 rig 的名字都不出现。 + +use std::fmt; + +use serde::{Deserialize, Serialize}; + +#[path = "provider/failure.rs"] +mod failure; + +pub use failure::ProviderFailure; + +/// 本地 llama.cpp server 的默认 OpenAI 兼容端点（research/02 §5.1）。 +pub const LLAMACPP_DEFAULT_BASE_URL: &str = "http://127.0.0.1:8080/v1"; +/// Ollama 默认端点（research/02 §5.2）。 +pub const OLLAMA_DEFAULT_BASE_URL: &str = "http://127.0.0.1:11434"; +/// Anthropic 官方 API 端点。 +pub const ANTHROPIC_DEFAULT_BASE_URL: &str = "https://api.anthropic.com"; + +/// Provider 四态。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum ProviderKind { + /// OpenAI 兼容（含本地 llama.cpp / LM Studio / DeepSeek / Qwen…）。 + OpenAiCompatible, + /// Anthropic 原生。 + Anthropic, + /// Ollama 原生。 + Ollama, + /// 完全禁用 agent。 + Disabled, +} + +impl ProviderKind { + /// 该形态是否必须提供 API key（本地推理通常不需要）。 + #[must_use] + pub fn requires_api_key(self) -> bool { + matches!(self, Self::Anthropic) + } + + /// 该形态的默认端点（OpenAI 兼容没有统一默认值，必须显式填； + /// 本地 llama.cpp 走 [`ProviderConfig::llamacpp_local`] 带的显式默认）。 + #[must_use] + pub fn default_base_url(self) -> &'static str { + match self { + Self::OpenAiCompatible => "", + Self::Anthropic => ANTHROPIC_DEFAULT_BASE_URL, + Self::Ollama => OLLAMA_DEFAULT_BASE_URL, + Self::Disabled => "", + } + } + + /// 配置键 `ai.provider` 的取值 → 形态（M174）。 + /// + /// **不能用 serde**：`#[serde(rename_all = "snake_case")]` 把本枚举写成 + /// `open_ai_compatible`（见本文件末尾的用例），而 schema 的允许值表 + /// （`core::setting::keys::AI_PROVIDERS`）与设置页存的是 `openai_compatible`。两个词表必须在这里 + /// 显式对上，否则「设置里存的值」读不到——这正是 M174 之前 agent 侧一次都没读过设置的原因。 + /// 未知值给 `None`（由调用方回落默认，不猜）。 + #[must_use] + pub fn from_setting(value: &str) -> Option { + match value.trim() { + "openai_compatible" => Some(Self::OpenAiCompatible), + "anthropic" => Some(Self::Anthropic), + "ollama" => Some(Self::Ollama), + "disabled" => Some(Self::Disabled), + _ => None, + } + } + + /// 本形态在 `ai.provider` 里的取值（[`Self::from_setting`] 的逆；写回设置时用）。 + #[must_use] + pub fn setting_value(self) -> &'static str { + match self { + Self::OpenAiCompatible => "openai_compatible", + Self::Anthropic => "anthropic", + Self::Ollama => "ollama", + Self::Disabled => "disabled", + } + } + + /// 设置页展示名。 + #[must_use] + pub fn display_name(self) -> &'static str { + match self { + Self::OpenAiCompatible => "OpenAI 兼容", + Self::Anthropic => "Anthropic 原生", + Self::Ollama => "Ollama 原生", + Self::Disabled => "已禁用", + } + } +} + +/// Provider 配置（设置 → AI 的一份快照）。 +/// +/// `api_key` 只在进程内存在，**任何日志/审计/事件都不得带它**—— +/// `Debug` 是手写的（掩码 key），要连形态一起看用 [`ProviderConfig::redacted_debug`]。 +#[derive(Clone, PartialEq, Serialize, Deserialize)] +pub struct ProviderConfig { + /// 四态。 + pub kind: ProviderKind, + /// 端点；空串表示用 [`ProviderKind::default_base_url`]。 + pub base_url: String, + /// 模型名；`Disabled` 时可为空。 + pub model: String, + /// API key（本地推理可空）。 + pub api_key: Option, + /// 采样温度。 + pub temperature: Option, + /// 单次回复 token 上限。 + pub max_tokens: Option, +} + +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) -> Self { + self.api_key = Some(api_key.into()); + self + } + + /// 带上温度。 + #[must_use] + pub fn with_temperature(mut self, temperature: f32) -> Self { + self.temperature = Some(temperature); + self + } + + /// agent 是否启用。 + #[must_use] + pub fn is_enabled(&self) -> bool { + self.kind != ProviderKind::Disabled + } + + /// 实际使用的端点（空则回落默认值）。 + #[must_use] + pub fn resolved_base_url(&self) -> &str { + if self.base_url.trim().is_empty() { + self.kind.default_base_url() + } else { + self.base_url.trim() + } + } + + /// 配置是否可用（装配期调用一次，错就进设置页提示而不是等到对话时炸）。 + /// + /// # Errors + /// 禁用、缺模型名、缺端点、缺 API key 时返回可读错误。 + pub fn validate(&self) -> Result<(), ProviderError> { + if !self.is_enabled() { + return Err(ProviderError::classified( + ProviderFailure::NotConfigured, + "AI 已禁用：请在设置 → AI 中选择端点（规则引擎诊断不受影响）", + )); + } + if self.model.trim().is_empty() { + return Err(ProviderError::classified( + ProviderFailure::NotConfigured, + "没有配置模型名（model）", + )); + } + if self.resolved_base_url().trim().is_empty() { + return Err(ProviderError::classified( + ProviderFailure::NotConfigured, + format!("{} 需要填写端点（base_url）", self.kind.display_name()), + )); + } + if self.kind.requires_api_key() + && self + .api_key + .as_deref() + .is_none_or(|key| key.trim().is_empty()) + { + return Err(ProviderError::classified( + ProviderFailure::NotConfigured, + format!("{} 需要 API key", self.kind.display_name()), + )); + } + Ok(()) + } + + /// 可打印的形态描述（**key 已掩码**，给日志/审计/设置页用）。 + #[must_use] + pub fn redacted_debug(&self) -> String { + let key = match self.api_key.as_deref() { + None => "无".to_string(), + Some(k) if k.trim().is_empty() => "无".to_string(), + Some(_) => crate::redact::MASK.to_string(), + }; + format!( + "{} base_url={} model={} api_key={key}", + self.kind.display_name(), + self.resolved_base_url(), + if self.model.is_empty() { + "（未设置）" + } else { + &self.model + }, + ) + } +} + +impl fmt::Debug for ProviderConfig { + /// 手写 Debug：**key 掩码**（`api_key` 是唯一不能出现在日志里的字段）。 + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.debug_struct("ProviderConfig") + .field("kind", &self.kind) + .field("base_url", &self.resolved_base_url()) + .field("model", &self.model) + .field( + "api_key", + &self.api_key.as_deref().map(|_| crate::redact::MASK), + ) + .field("temperature", &self.temperature) + .field("max_tokens", &self.max_tokens) + .finish() + } +} + +/// Provider 层错误（消息面向用户 + **结构化分类**：`kind` 由 `brain::rig` 的适配层从 rig 的 +/// `ErrorReport` 翻译，见 [`failure`]）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ProviderError { + kind: ProviderFailure, + message: String, +} + +impl ProviderError { + /// 从可读文本构造（分类是 [`ProviderFailure::Other`]：调用方不知道结构化原因时用它）。 + #[must_use] + pub fn new(message: impl Into) -> Self { + Self { + kind: ProviderFailure::Other, + message: message.into(), + } + } + + /// 带分类构造（`brain::rig` 的 `map_error` 与 [`ProviderConfig::validate`] 用）。 + #[must_use] + pub fn classified(kind: ProviderFailure, message: impl Into) -> Self { + Self { + kind, + message: message.into(), + } + } + + /// 失败分类（「测试连接」按它分档）。 + #[must_use] + pub fn kind(&self) -> ProviderFailure { + self.kind + } +} + +impl fmt::Display for ProviderError { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str(&self.message) + } +} + +impl std::error::Error for ProviderError {} + +#[cfg(test)] +#[path = "provider/tests.rs"] +mod tests; diff --git a/crates/agent/src/brain/provider/failure.rs b/crates/agent/src/brain/provider/failure.rs new file mode 100644 index 0000000..7b78a37 --- /dev/null +++ b/crates/agent/src/brain/provider/failure.rs @@ -0,0 +1,62 @@ +//! Provider 失败的**结构化分类**（M174 r1 复审 P2-5）：一次「测试连接」失败到底属于哪一类。 +//! +//! ## 为什么不是字符串匹配 +//! +//! r1 的版本对 `ProviderError` 的 `Display` 做子串匹配（找 `"401"` / `"connection refused"` / +//! `"timed out"`），有三个真问题：①URL / 请求 id / 模型名里出现 `401` 这类数字就误判（假阳）； +//! ②「连接被拒」的实际文本是 `Http client error: error sending request for url (…)`，不含 +//! `connection refused`，只能靠补一个更宽的 `error sending request` 兜住——**这是在猜文本**； +//! ③文本随 rig / reqwest 版本漂，升级一次就静默错档（复审实测：`closed_port_is_unreachable` +//! 一度偶发红）。 +//! +//! 现在分类由 [`super::rig`] 的适配层从 rig 0.45 的**结构化报告**（`ErrorReport`：`kind` / +//! `http_status` / `code`）翻译出来，本文件只放枚举与「给界面看的稳定名」。本模块不认识 rig。 +//! +//! ## 六档口径 +//! +//! | 档 | 判据（`super::rig::map_error`） | 界面含义 | +//! |---|---|---| +//! | [`ProviderFailure::NotConfigured`] | 配置不完整（`validate()` 拒绝）——**没有发请求** | 先把配置填完 | +//! | [`ProviderFailure::Auth`] | 有 HTTP 状态且是 401 / 403，或 rig 明确报「凭据被拒」 | 密钥/权限不对 | +//! | [`ProviderFailure::ModelNotFound`] | 有 HTTP 状态 404，或响应体的机器码是 `model_not_found` | 端点通了，模型不存在 | +//! | [`ProviderFailure::Unreachable`] | 传输层失败：连接被拒 / DNS / TLS / 响应被截断（**没有拿到任何回应**） | 端点不可达 | +//! | [`ProviderFailure::Timeout`] | 调用方的时限（探测的 8 秒）或 rig 报 `ErrorKind::Timeout` / 传输层 `io::ErrorKind::TimedOut` | 太慢或端点不响应 | +//! | [`ProviderFailure::Other`] | 其余（JSON / URL / 请求构造 / 5xx 之类） | 请求失败（详情见下） | + +/// 一次 provider 调用的失败分类（见模块文档的六档表）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum ProviderFailure { + /// 配置不完整：**没有发出任何请求**。 + NotConfigured, + /// 鉴权失败（401 / 403 / 凭据被拒）。 + Auth, + /// 模型不存在（404 / `model_not_found`）。 + ModelNotFound, + /// 端点不可达（传输层失败，没拿到任何回应）。 + Unreachable, + /// 超时（调用方时限或传输层超时）。 + Timeout, + /// 其它（协议 / 解析 / 5xx / 未知）。 + Other, +} + +impl ProviderFailure { + /// 稳定名（日志 / CLI / 测试断言用；界面文案走 i18n）。 + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::NotConfigured => "not_configured", + Self::Auth => "auth", + Self::ModelNotFound => "model_not_found", + Self::Unreachable => "unreachable", + Self::Timeout => "timeout", + Self::Other => "other", + } + } + + /// 「配置不完整」以外都意味着**请求真的发出去了**（守卫②/③的判据）。 + #[must_use] + pub const fn sent_a_request(self) -> bool { + !matches!(self, Self::NotConfigured) + } +} diff --git a/crates/agent/src/brain/provider/tests.rs b/crates/agent/src/brain/provider/tests.rs new file mode 100644 index 0000000..d47d6f8 --- /dev/null +++ b/crates/agent/src/brain/provider/tests.rs @@ -0,0 +1,107 @@ +//! [`super`] 的用例（M174 r1 复审 P2-5 拆出来：`provider.rs` 撞了 400 行硬线）。 +//! +//! 拆的是**纯搬移**：一条断言都没改。分类那半边的新用例在 `failure` 的模块文档里指路， +//! 结构化分类本身由 `brain/rig.rs` 的 `map_error` 产生，用例在 `probe` 的真服务器那几条。 + +use super::*; + +#[test] +fn local_defaults_match_research() { + assert_eq!( + ProviderConfig::llamacpp_local("qwen2.5").resolved_base_url(), + LLAMACPP_DEFAULT_BASE_URL + ); + assert_eq!( + ProviderConfig::ollama("llama3").resolved_base_url(), + OLLAMA_DEFAULT_BASE_URL + ); + assert_eq!( + ProviderConfig::anthropic("claude-sonnet-4").resolved_base_url(), + ANTHROPIC_DEFAULT_BASE_URL + ); +} + +#[test] +fn setting_vocabulary_round_trips() { + // 设置里存的是 `openai_compatible`（schema 的 `AI_PROVIDERS`），不是 serde 的 + // `open_ai_compatible`：两个词表必须是这里这一对映射，否则「用户在设置页选的值」 + // agent 侧读出来是 None（M174 的根因）。 + for kind in [ + ProviderKind::OpenAiCompatible, + ProviderKind::Anthropic, + ProviderKind::Ollama, + ProviderKind::Disabled, + ] { + assert_eq!(ProviderKind::from_setting(kind.setting_value()), Some(kind)); + } + assert_eq!( + ProviderKind::from_setting(" ollama "), + Some(ProviderKind::Ollama) + ); + assert_eq!(ProviderKind::from_setting("open_ai_compatible"), None); + assert_eq!(ProviderKind::from_setting(""), None); + // schema 的允许值表与本枚举的取值表是**同一个集合**（一方加了另一方没加就红）。 + assert_eq!( + unlucky_core::setting::keys::AI_PROVIDERS, + [ + ProviderKind::OpenAiCompatible.setting_value(), + ProviderKind::Anthropic.setting_value(), + ProviderKind::Ollama.setting_value(), + ProviderKind::Disabled.setting_value(), + ] + ); +} + +#[test] +fn validate_requires_model_base_url_and_key() { + assert!(!ProviderConfig::disabled().is_enabled()); + assert!(ProviderConfig::disabled().validate().is_err()); + assert!(ProviderConfig::llamacpp_local("").validate().is_err()); + assert!(ProviderConfig::llamacpp_local("qwen").validate().is_ok()); + // OpenAI 兼容必须显式给端点 + assert!(ProviderConfig::openai_compatible("", "gpt-4o-mini") + .validate() + .is_err()); + assert!( + ProviderConfig::openai_compatible("https://api.deepseek.com/v1", "deepseek-chat") + .validate() + .is_ok() + ); + assert!(ProviderConfig::anthropic("claude").validate().is_err()); + assert!(ProviderConfig::anthropic("claude") + .with_api_key("sk-ant") + .validate() + .is_ok()); +} + +#[test] +fn redacted_debug_never_leaks_key() { + let config = ProviderConfig::openai_compatible("https://api.deepseek.com/v1", "deepseek-chat") + .with_api_key("sk-super-secret"); + let text = config.redacted_debug(); + assert!(!text.contains("sk-super-secret"), "{text}"); + assert!(text.contains(crate::redact::MASK)); + // `{:?}` 也必须掩码：Debug 是 panic 消息/日志的默认出口。 + let debug = format!("{config:?}"); + assert!(!debug.contains("sk-super-secret"), "{debug}"); + assert!(debug.contains(crate::redact::MASK), "{debug}"); +} + +#[test] +fn empty_base_url_falls_back_to_default() { + let mut config = ProviderConfig::ollama("llama3"); + config.base_url = String::new(); + assert_eq!(config.resolved_base_url(), OLLAMA_DEFAULT_BASE_URL); +} + +#[test] +fn four_states_serialize_as_snake_case() { + assert_eq!( + serde_json::to_string(&ProviderKind::OpenAiCompatible).unwrap(), + "\"open_ai_compatible\"" + ); + assert_eq!( + serde_json::to_string(&ProviderConfig::disabled()).unwrap(), + "{\"kind\":\"disabled\",\"base_url\":\"\",\"model\":\"\",\"api_key\":null,\"temperature\":null,\"max_tokens\":null}" + ); +} diff --git a/crates/agent/src/brain/rig.rs b/crates/agent/src/brain/rig.rs new file mode 100644 index 0000000..27ce6d0 --- /dev/null +++ b/crates/agent/src/brain/rig.rs @@ -0,0 +1,345 @@ +//! rig 适配层：[`ChatProvider`] 的**唯一**实现，也是整个 crate 唯一允许 `use rig_*` 的文件。 +//! +//! 依赖面收窄纪律（`DevDocs/PlanDoc/02-ai-agent-design.md` §0 + research/02 §7 R1）： +//! rig 是 pre-1.0、12 周 5 个 minor、CHANGELOG 满是 `[**breaking**]`（0.43 把 MCP 拆出 rig-agent、 +//! 0.45 升 rmcp 3.5 并改 owned connection）。所以把它关在这一个文件里：它变了，只有这里编译失败， +//! [`super::ChatProvider`] 以上的循环/编排/审计一行不用动。 +//! +//! ## 0.45 的接线（实读源码，非照文档猜） +//! +//! ```text +//! ProviderConfig ─┬─ OpenAiCompatible → OpenAIConfig::new(key).with_base_url(url).client().chat(model) +//! ├─ Anthropic → AnthropicConfig::new(key).with_base_url(url).client().completion(model) +//! ├─ Ollama → OllamaConfig::new().with_base_url(url).client().completion(model) +//! └─ Disabled → 不构造（Brain::run_turn 已提前返回） +//! ↓ Model.erase() +//! DynModel（wire + transport 擦除，本文件只持有这一个类型） +//! ``` +//! +//! 循环侧只要两件事：流式文本增量、以及折好的 [`ChatReply`]（文本 + 工具调用）。 +//! 所以这里用 `model.stream(request)` 边转发 [`StreamEvent::Text`] 增量给 [`DeltaObserver`]， +//! 最后 `Streamed::finish()` 拿到完整 [`CompletionResponse`]——工具调用从响应里取， +//! 不自己拼分片 JSON（拼分片是 rig 的 `ReplyFold` 已经做过的事）。 +//! +//! ## 三个已确认的坑 +//! +//! 1. **llama.cpp 默认端点就是 `http://localhost:8080/v1`**（`providers/llamacpp/mod.rs`）， +//! 与 [`LLAMACPP_DEFAULT_BASE_URL`] 一致。这里统一走 OpenAI 方言 + 显式 base_url： +//! llama.cpp / LM Studio / DeepSeek 都是 OpenAI 兼容面，方言差异主要在默认端点与特有位 +//! （`chat_template_kwargs`、`num_ctx`）——真要下发这些，再换成 `providers::llamacpp` 方言或 +//! Ollama 的 `native_completion`。 +//! 2. **Ollama 原生方言的工具结果用 `tool_name` 配对（没有 id）**，OpenAI 方言用 `tool_call_id`。 +//! 这里走 rig 的 `Ollama::completion`（OpenAI 兼容 `/v1/chat/completions`），由 rig 负责回灌形状； +//! 要下发 `num_ctx`（崩溃日志几千行，上下文必须可配）才需要 `native_completion`，留作 P1。 +//! 3. **取消**：`Streamed` 是普通 future/stream，丢弃即断开——P0 用「丢弃 future」实现停止生成， +//! P1 接 UI 的「停止」按钮时按 rig 的取消语义（drop stream）对齐即可，不需要 unsafe。 +//! +//! ## 逃生口（保留但不是 Plan A） +//! +//! rig 的破坏变更真伤到（或 Rust 1.92 MSRV 追不上 rig 的 1.97.1）时：换 `genai` +//! （provider + function calling，无 agent 循环）或自己写 OpenAI 方言（约 300~500 行）。 +//! **代价只是实现一个新的 [`ChatProvider`]**——这正是把它关在一个文件里的意义。 +//! +//! [`LLAMACPP_DEFAULT_BASE_URL`]: super::provider::LLAMACPP_DEFAULT_BASE_URL +//! [`StreamEvent::Text`]: rig_core::streaming::StreamEvent::Text + +use std::sync::Arc; + +use futures_util::StreamExt; +use rig_core::completion::{CompletionRequest, ToolDefinition as RigToolDefinition}; +use rig_core::error::{ErrorKind, ProviderError as RigError}; +use rig_core::message::{ + AssistantContent as RigAssistantContent, AssistantMessage as RigAssistantMessage, CallId, + Message as RigMessage, Text as RigText, ToolCall as RigToolCall, ToolFunction, + ToolName as RigToolName, ToolResult, ToolResultContent, UserContent, +}; +use rig_core::operation::Completion; +use rig_core::providers::anthropic::AnthropicConfig; +use rig_core::providers::ollama::OllamaConfig; +use rig_core::providers::openai::OpenAIConfig; +use rig_core::streaming::{Item, StreamEvent}; +use rig_core::DynModel; + +use super::chat::{ + ChatMessage, ChatProvider, ChatReply, ChatRequest, DeltaObserver, ProviderFactory, + ProviderFuture, +}; +use super::provider::{ProviderConfig, ProviderError, ProviderFailure, ProviderKind}; + +/// 锁定的 rig 版本（与 `Cargo.toml` 的唯一记录点，避免两处不一致）。 +pub const RIG_VERSION_PIN: &str = "=0.45.0"; + +/// 擦掉 wire / transport 之后的补全模型——本文件对外只暴露这一个 rig 类型之外的东西。 +type ErasedModel = DynModel; + +/// 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 { + 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) + }) + } +} + +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 { + 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 { + 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::, _>>()?; + + 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 { + 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>, 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 { + let mut text = streamed; + let mut tool_calls = Vec::new(); + for part in &response.choice { + match part { + RigAssistantContent::Text(chunk) => { + if text.is_empty() { + text.push_str(&chunk.text); + } + } + RigAssistantContent::ToolCall(call) => { + if let Some(raw) = call.function.invalid_arguments.as_deref() { + return Err(ProviderError::new(format!( + "模型返回的工具调用参数不是 JSON 对象（工具 `{}`）：{raw}", + call.function.name.as_str() + ))); + } + tool_calls.push(super::chat::ToolCall { + id: call.id.to_string(), + name: call.function.name.as_str().to_string(), + arguments: serde_json::Value::Object(call.function.arguments.clone()), + }); + } + // 推理链/图片/未知块不进对话循环（P0 只消费文本 + 工具调用）。 + _ => {} + } + } + Ok(ChatReply { + text, + tool_calls, + usage: Some(super::chat::Usage { + prompt_tokens: response + .usage + .input_tokens + .and_then(|v| u32::try_from(v).ok()), + completion_tokens: response + .usage + .output_tokens + .and_then(|v| u32::try_from(v).ok()), + }), + }) +} + +/// rig 错误 → 本方错误：**分类取自 rig 的结构化报告**（`ErrorReport` 的 `kind` / +/// `http_status` / `code`），不猜 `Display` 文本（M174 r1 复审 P2-5）。 +/// +/// | rig 侧信号 | 本方分类 | +/// |---|---| +/// | `http_status ∈ {401, 403}` | [`ProviderFailure::Auth`] | +/// | `http_status == 404` | [`ProviderFailure::ModelNotFound`]（OpenAI 兼容面的 404 只可能是模型不在，`/chat/completions` 本身是固定路径；Anthropic 的 404 也是同一语义） | +/// | `code == "model_not_found"` / `"model_not_found_error"` | [`ProviderFailure::ModelNotFound`] | +/// | `ErrorKind::Timeout` 或传输层 `io::ErrorKind::TimedOut` | [`ProviderFailure::Timeout`] | +/// | `ErrorKind::Http`（连接被拒 / DNS / TLS / 截断） | [`ProviderFailure::Unreachable`] | +/// | 其余（JSON / URL / 请求构造 / 5xx / 未知） | [`ProviderFailure::Other`] | +fn map_error(error: RigError) -> ProviderError { + let report = error.report(); + let kind = match report.kind { + ErrorKind::Timeout => ProviderFailure::Timeout, + ErrorKind::Http => { + if transport_timed_out(&error) { + ProviderFailure::Timeout + } else { + ProviderFailure::Unreachable + } + } + ErrorKind::ProviderResponse | ErrorKind::Provider => match report.http_status { + Some(401 | 403) => ProviderFailure::Auth, + Some(404) => ProviderFailure::ModelNotFound, + _ if matches!( + report.code.as_deref(), + Some("model_not_found" | "model_not_found_error") + ) => + { + ProviderFailure::ModelNotFound + } + _ => ProviderFailure::Other, + }, + _ => ProviderFailure::Other, + }; + ProviderError::classified(kind, report.message) +} + +/// 传输层失败里有没有「超时」：沿 `source()` 链找 `io::ErrorKind::TimedOut` +/// （reqwest 把超时折在 transport error 里，rig 只留一个 `Box`）。 +/// +/// 结构化判据（类型 + `ErrorKind`），不是文本匹配：这条路径上的其它失败（连接被拒、DNS、 +/// TLS）都归 `Unreachable`。 +fn transport_timed_out(error: &RigError) -> bool { + let RigError::Http(http_error) = error else { + return false; + }; + let mut source = std::error::Error::source(http_error); + for _ in 0..8 { + let Some(cause) = source else { return false }; + if let Some(io) = cause.downcast_ref::() { + return io.kind() == std::io::ErrorKind::TimedOut; + } + source = cause.source(); + } + false +} + +/// 工具名 → rig 的 [`RigToolName`]（空名是唯一的非法输入）。 +fn tool_name(name: &str) -> Result { + RigToolName::new(name) + .map_err(|_| ProviderError::new("工具名不能为空（ToolSpec 注册阶段应已拦截）")) +} + +#[cfg(test)] +#[path = "rig/tests.rs"] +mod tests; diff --git a/crates/agent/src/brain/rig/tests.rs b/crates/agent/src/brain/rig/tests.rs new file mode 100644 index 0000000..5ffa21c --- /dev/null +++ b/crates/agent/src/brain/rig/tests.rs @@ -0,0 +1,82 @@ +//! [`super`]（rig 适配层）的用例（M174 r1 复审 P2-5 拆出来：结构化映射让 `rig.rs` 撞了 400 行）。 +//! +//! 纯搬移。分类的端到端证据不在本文件：那要真 HTTP，用例在 +//! `crates/cli/src/commands/agent/probe/tests.rs`（四类各一台假服务器）。 + +use super::*; + +fn tool(id: &str, name: &str) -> super::super::chat::ToolCall { + super::super::chat::ToolCall { + id: id.to_string(), + name: name.to_string(), + arguments: serde_json::json!({ "path": "appearance.theme_mode" }), + } +} + +#[test] +fn disabled_config_is_rejected_before_touching_the_network() { + let Err(err) = RigProvider::new(ProviderConfig::disabled()) else { + panic!("禁用态应在构造阶段被拒"); + }; + assert!(err.to_string().contains("禁用")); +} + +#[test] +fn anthropic_without_key_is_rejected() { + assert!(RigProvider::new(ProviderConfig::anthropic("claude-sonnet-4")).is_err()); + assert!( + RigProvider::new(ProviderConfig::anthropic("claude-sonnet-4").with_api_key("sk-ant")) + .is_ok() + ); +} + +#[test] +fn local_states_build_offline() { + assert!(RigProvider::new(ProviderConfig::llamacpp_local("qwen2.5-7b")).is_ok()); + assert!(RigProvider::new(ProviderConfig::ollama("llama3.1")).is_ok()); +} + +#[test] +fn request_maps_messages_and_tools() { + let request = ChatRequest { + model: "mock".to_string(), + messages: vec![ + ChatMessage::system("你是助手"), + ChatMessage::user("把主题换成浅色"), + ChatMessage::Assistant { + text: String::new(), + tool_calls: vec![tool("call_1", "set_config")], + }, + ChatMessage::tool("call_1", "set_config", "{\"status\":\"written\"}"), + ], + tools: vec![crate::registry::ToolDefinition { + name: "set_config".to_string(), + description: "改配置".to_string(), + input_schema: serde_json::json!({ "type": "object" }), + }], + temperature: Some(0.5), + max_tokens: Some(512), + }; + let built = build_request(&request).expect("应能构造"); + assert_eq!(built.chat_history.len(), 4); + assert_eq!(built.tools.len(), 1); + assert_eq!(built.tools[0].name.as_str(), "set_config"); + assert_eq!(built.temperature, Some(0.5)); + assert_eq!(built.max_tokens, Some(512)); + // 工具结果在 rig 0.45 里是 user 角色的 ToolResult 内容块 + let json = serde_json::to_string(&built.chat_history[3]).expect("可序列化"); + assert!(json.contains("toolresult"), "{json}"); +} + +#[test] +fn empty_history_is_a_readable_error() { + let request = ChatRequest { + model: "m".to_string(), + messages: Vec::new(), + tools: Vec::new(), + temperature: None, + max_tokens: None, + }; + let err = build_request(&request).unwrap_err(); + assert!(err.to_string().contains("对话历史为空")); +} 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` 的简写。 +pub type SharedClock = Arc; + +/// 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 + 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>, + default: ConfirmDecision, +} + +impl ScriptedGate { + /// 依次给出 `decisions`，耗尽后返回 `default`。 + #[must_use] + pub fn new( + decisions: impl IntoIterator, + 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, + }, + /// 工具调用被拒绝（策略或用户）。 + 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>, +} + +impl MemoryEventSink { + /// 空 sink。 + #[must_use] + pub fn new() -> Self { + Self::default() + } + + /// 取快照。 + #[must_use] + pub fn events(&self) -> Vec { + 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, +} + +impl MpscSink { + /// 包一个 `std::sync::mpsc::Sender`。 + #[must_use] + pub fn new(tx: Sender) -> 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 `）；`None` = 不校验（仅限回环监听时允许）。 + pub token: Option, + /// 是否只暴露只读工具（默认 **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 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 { + 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(®istry); + 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(®istry).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(®istry()) { + 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:/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 `。设置里为空 = 不校验（只允许回环监听， +//! `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 = + 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, 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 ", + ) + .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, + visible: Arc>, + 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, + executor: Arc, + session_id: impl Into, + 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 = 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 { + (*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) -> ToolRoute { + 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, + _context: RequestContext, + ) -> Result { + Ok(ListToolsResult::with_all_items(self.tools())) + } + + async fn call_tool( + &self, + request: CallToolRequestParams, + context: RequestContext, + ) -> Result { + let call_context = ToolCallContext::new(self, request, context); + self.router.call(call_context).await + } + + fn get_tool(&self, name: &str) -> Option { + 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, read_only: bool) -> (RegistryServer, Arc) { + 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(®istry) + }; + 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 { + 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(®istry), 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 = 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,}.jsonl` | +//! | [`DiagnosePort`] | `diagnose_crash` | M15 · 规则引擎 | +//! +//! 形状依据（以对方文件为准，改字段先改对方文件）： +//! - `DevDocs/SubAgentsTalk/launch-接口约定.md` §2/§5（事件行 + 索引行） +//! - `DevDocs/SubAgentsTalk/agent-ToolSpec约定.md`（本 crate 对外的对齐说明） +//! +//! 错误一律用 `Result`：错误文本会**原样进工具结果**给模型与用户看 +//! （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 = Result; + +/// agent 需要的全部端口。装配处（`crates/app` / `ull agent serve`）用它一次性注入。 +#[derive(Clone)] +pub struct Ports { + /// 配置读写（M12）。 + pub setting: Arc, + /// 游戏会话与日志（M18）。 + pub sessions: Arc, + /// 崩溃规则引擎（M15）。 + pub diagnose: Arc, + /// 实例 / 版本 / Java（M14 + M33）。 + pub game: Arc, + /// 账户元数据（M31，**只有公开字段**，凭据永不出口）。 + pub accounts: Arc, +} + +// ───────────────────────────── 配置（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, + /// 写入后的值。 + 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; + /// 写单个键（值校验由实现方负责），返回 diff。 + fn set(&self, path: &str, value: &Value) -> PortResult; + /// **AI 可写白名单**（含敏感分级）。不在表里的键 agent 一律拒绝。 + fn writable_keys(&self) -> Vec; + /// 配置 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, + /// 实例显示名。 + pub instance_name: Option, + /// MC 版本。 + pub game_version: Option, + /// 启动时间（RFC3339 UTC）。 + pub started_at: Option, + /// 结束时间；会话未结束时为 `None`。 + pub ended_at: Option, + /// 时长毫秒。 + pub duration_ms: u64, + /// 退出码；未正常结束时可能缺失。 + pub exit_code: Option, + /// `exit_type`：`normal|application_error|jvm_error|sigkill|sigterm|killed|interrupted`。 + pub exit_type: Option, + /// 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, +} + +/// `read_game_log` 的查询条件：**按事件 seq 切片**，不是按行号 +/// （stdout/stderr 是一行一事件，但同一条日志行可能被切成多块，见 launch §1）。 +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct LogQuery { + /// 起始 `seq`（含）。 + pub from_seq: Option, + /// 结束 `seq`（含）。 + pub to_seq: Option, + /// 只要这些 `kind`（空 = 全部）。未知 kind 由实现方忽略而不是报错（前向兼容）。 + pub kinds: Vec, + /// 最多返回多少条事件（工具层已钳到 [`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, + /// 首事件时间。 + pub first_ts: Option, + /// 末事件时间。 + pub last_ts: Option, + /// 本次返回的事件（已按 seq 升序）。 + pub events: Vec, +} + +/// 会话端口（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>; + /// 按 [`LogQuery`] 切片读取一个会话的事件流。 + fn read_log(&self, session_id: &str, query: &LogQuery) -> PortResult; +} + +// ───────────────────────── 崩溃诊断（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, +} + +/// 一条诊断候选（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, + /// 该候选的修复动作。 + pub fix_actions: Vec, +} + +/// 退出摘要（M15 `DiagnosisRecord::exit`，与 launch 的 `exit` 事件同源）。 +#[derive(Debug, Clone, Default, Serialize, PartialEq)] +pub struct ExitSummary { + /// 退出码。 + pub code: Option, + /// `normal|application_error|jvm_error|sigkill|sigterm|killed|interrupted`。 + pub exit_type: Option, + /// 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, + /// 被抑制的次要候选。 + pub secondary: Vec, + /// 会话级关键片段（`crash_found.excerpt` / `hs_err` 摘要，已脱敏）。 + pub evidence: Vec, + /// 退出摘要。 + 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; +} 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, + /// 实例级 Java 覆盖路径（未覆盖时为 `None`）。 + pub java_path: Option, + /// 上次启动时刻（Unix 毫秒；从未启动为 `None`）。 + pub last_played_at: Option, +} + +/// 已安装版本的摘要（`versions//` 的存在性 + 可读的元信息）。 +#[derive(Debug, Clone, Default, Serialize, PartialEq, Eq)] +pub struct VersionSummary { + /// 版本 id。 + pub id: String, + /// 版本 JSON 里声明的 `type`（`release` / `snapshot` / 加载器自报），读不到为 `None`。 + pub kind: Option, + /// 被几个实例引用。 + 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, + /// 主版本号（8 / 17 / 21）。 + pub major: Option, + /// 发行方（temurin / oracle / microsoft / zulu …）。 + pub vendor: Option, + /// 来源类别（`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, + /// 托管 JDK 的扫描根。 + pub managed_roots: Vec, + /// 探测到的候选（已去重，优先级从高到低）。 + pub candidates: Vec, +} + +// ──────────────────────────── 账户（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, + /// 创建时刻（Unix 毫秒）。 + pub created_at_ms: u64, +} + +/// 游戏资产端口（M14 实例/版本 + M33 Java 探测）。 +pub trait GamePort: Send + Sync { + /// 全部实例（按上次启动时间倒序）。 + fn list_instances(&self) -> PortResult>; + /// 已安装版本清单。 + fn list_versions(&self) -> PortResult>; + /// Java 现状（候选 + 托管根 + 默认内存）。 + fn java_status(&self) -> PortResult; +} + +/// 账户端口（M31）。实现方只允许读 `AccountStore::accounts()`（`AccountMeta`）， +/// **不得**调用 `credentials()`——那是凭据出口，agent 侧没有对应字段可以承接。 +pub trait AccountPort: Send + Sync { + /// 账户清单（公开字段）。 + fn list_accounts(&self) -> PortResult>; +} + +#[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：`` / `` / +//! ``），所以这里不重复实现那套；本模块只兜两件事： +//! 1. 审计日志里的参数可能含 API key（`set_config` 能改 AI 端点）→ 按键名掩码； +//! 2. 日志正文万一含用户主目录绝对路径（旧会话、第三方 mod 输出）→ 掩码用户名段。 +//! +//! 幂等：对已脱敏文本再跑一遍结果不变（`` / `***` 原样保留）。 + +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("") { + 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 ` → `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("/.minecraft"), "/.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） +//! ├─ 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`，注册表只是索引。 + +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>, + index: BTreeMap, +} + +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> { + self.index.get(name).and_then(|i| self.specs.get(*i)) + } + + /// 全部工具（按注册顺序，模型看到的顺序稳定）。 + #[must_use] + pub fn specs(&self) -> &[Arc] { + &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 { + self.specs.iter().map(|s| s.definition()).collect() + } + + /// 只读子集（P1 的 `--readonly` 外部 MCP 模式用）。 + #[must_use] + pub fn read_only_definitions(&self) -> Vec { + 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 { + 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, +} + +/// 待确认的操作详情（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) -> Self { + Self { + content, + summary: summary.into(), + confirmation: None, + } + } + + /// 需要确认（本次**没有**产生副作用）。 + #[must_use] + pub fn needs_confirmation( + summary: impl Into, + 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 Result + 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> { + 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 { + validate(schema, args) + .err() + .and_then(|errors| errors.into_iter().next()) +} + +fn validate_at(schema: &Value, value: &Value, path: &str, errors: &mut Vec) { + 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 = 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, + value: &Value, + path: &str, + errors: &mut Vec, +) { + 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 { + 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, + events: BTreeMap>, +} + +impl MockSessions { + /// 空数据。 + #[must_use] + pub fn new() -> Self { + Self::default() + } + + /// 加一个会话及其事件流。 + pub fn add(&mut self, summary: GameSessionSummary, events: Vec) { + 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) { + 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> { + let mut out: Vec = 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 { + 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) { + 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, +} + +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 { + 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, + versions: Vec, + java: JavaStatus, + fail: Option, +} + +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 { + self.fail.clone() + } +} + +impl GamePort for MockGame { + fn list_instances(&self) -> PortResult> { + self.fail().map_or_else(|| Ok(self.instances.clone()), Err) + } + + fn list_versions(&self) -> PortResult> { + self.fail().map_or_else(|| Ok(self.versions.clone()), Err) + } + + fn java_status(&self) -> PortResult { + self.fail().map_or_else(|| Ok(self.java.clone()), Err) + } +} + +/// 内存账户端口：一个离线账户。**只有公开字段**，凭据无处可放。 +#[derive(Debug, Clone)] +pub struct MockAccounts { + accounts: Vec, + fail: Option, +} + +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> { + 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, + values: Mutex>, + fail_set: Mutex>, + set_calls: Mutex, +} + +/// 与 `PlanDoc/04` §3 / M12 `setting-接口约定.md` §8 的键表一致的默认白名单 +/// （覆盖三档敏感度；`ai.api_key` 这类凭据是 `writable=false`，**故意不在这里**）。 +fn default_keys() -> Vec { + 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 { + 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 { + self.values + .lock() + .ok() + .and_then(|v| v.get(path).cloned()) + .ok_or_else(|| format!("配置键 `{path}` 没有值")) + } + + fn set(&self, path: &str, value: &Value) -> PortResult { + 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 { + 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, +) -> 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 = 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) -> 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(®istry(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(®istry(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, +) -> Result<(), RegistryError> { + registry.register(get_config_spec(Arc::clone(&port)))?; + registry.register(set_config_spec(port)) +} + +fn get_config_spec(port: Arc) -> 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::>(), + }), + 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) -> 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 { + 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) -> 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, +) -> 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 = report + .candidates + .iter() + .map(|c| render_candidate(c, max_evidence_lines)) + .collect(); + let secondary: Vec = 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 = 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 { + 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 { + 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 { + 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::().ok().map(|n| n * scale) +} + +fn cap_lines(lines: &[String], max_lines: usize) -> Vec { + 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) -> 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) -> 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) -> 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//` 下真实存在的载荷），带类型与被几个实例引用。判断「实例的载荷缺没缺」时配合 list_instances 的 version_present 一起看。", + object(&[("limit", limit_schema())], &[]), + handler, + ) +} + +fn java_status_spec(port: Arc) -> ToolSpec { + let handler: ToolFn = Arc::new(move |_ctx: &ToolCtx, _args: &Value| { + let status = port.java_status().map_err(ToolError::Port)?; + let majors: Vec = 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(®istry(), 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(®istry(), 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(®istry(), 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 { + 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, +) -> 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 = 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 取最后一行）； +//! - 日志读 `.jsonl`，**按 `seq` 切片 + 按 `kind` 过滤**，不是按行号。 +//! +//! 两条防 token 爆炸的硬约束： +//! 1. 单次最多 [`MAX_LOG_EVENTS`] 条事件（默认 [`DEFAULT_LOG_EVENTS`]）； +//! 2. 单条 payload 里的字符串超过 [`MAX_PAYLOAD_CHARS`] 截断。 +//! +//! 脱敏：launch 落盘前已经做过一遍（`` / ``），本工具再跑一遍 +//! [`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, +) -> Result<(), RegistryError> { + registry.register(list_sessions_spec(Arc::clone(&port)))?; + registry.register(read_log_spec(port)) +} + +fn list_sessions_spec(port: Arc) -> 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) -> 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 = 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 = page.events.iter().map(render_event).collect(); + let kind_summary = page + .kind_counts + .iter() + .map(|(kind, count)| format!("{kind}×{count}")) + .collect::>() + .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!["list_game_sessions", "diagnose_crash"] + ); +} + +#[test] +fn step_limit_stops_runaway_loop() { + // 每一步都要求调工具，永远不会给最终回答。 + let script: Vec = (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(®istry)` 的 `(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(®istry); + 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 = tool_attrs(®istry) + .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(®istry()) { + 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(®istry).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 = 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) -> 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(®istry) + }; + 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) { + 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::().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::(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::(data.trim()) { + return value; + } + } + panic!("响应体既不是 JSON 也不是 SSE：{body}"); +} + +async fn initialize(addr: SocketAddr) -> Option { + 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 { + 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::(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 = 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(future: F) -> F::Output { + let mut future: Pin> = 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>, + requests: Mutex>, + fail_with: Option, +} + +impl MockProvider { + /// 用默认模型名（本地 llama.cpp 形态）回放脚本。 + #[must_use] + pub fn new(script: Vec) -> 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 { + 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::>().chunks(4) { + observer.on_delta(&chunk.iter().collect::()); + } + } + Ok(reply) + }) + } +} + +/// 装配好的测试环境。 +pub struct Harness { + /// 对话循环。 + pub brain: Brain, + /// 审计出口（内存）。 + pub audit: Arc, + /// 事件出口（内存）。 + pub events: Arc, + /// mock provider（查请求）。 + pub provider: Arc, + /// mock 配置端口（查是否真的写入）。 + pub settings: Arc, + /// 工具注册表。 + pub registry: Arc, +} + +impl Harness { + /// P0 默认形态：无确认 UI（`NoUiGate`，敏感操作 fail-closed）+ 非 YOLO。 + /// 确认请求本身仍会作为 [`unlucky_agent::event::AgentEvent::ConfirmRequested`] 发出。 + #[must_use] + pub fn new(script: Vec) -> Self { + Self::with_gate(script, ConfirmPolicy::default(), |_sink| Arc::new(NoUiGate)) + } + + /// YOLO：自动放行全部（除破坏性）。 + #[must_use] + pub fn yolo(script: Vec) -> Self { + Self::with_gate(script, ConfirmPolicy { yolo: true }, |_sink| { + Arc::new(AutoApproveGate) + }) + } + + /// 用指定的（可能失效/禁用的）provider 装配，其余同 [`Harness::new`]。 + #[must_use] + pub fn from_provider(provider: Arc) -> Self { + Self::build(provider, ConfirmPolicy::default(), |_sink| { + Arc::new(NoUiGate) + }) + } + + /// 自定义闸门 + 策略。 + #[must_use] + pub fn with_gate( + script: Vec, + policy: ConfirmPolicy, + make_gate: impl FnOnce(Arc) -> Arc, + ) -> Self { + Self::build(Arc::new(MockProvider::new(script)), policy, make_gate) + } + + fn build( + provider: Arc, + policy: ConfirmPolicy, + make_gate: impl FnOnce(Arc) -> Arc, + ) -> 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, + gate, + policy, + clock, + events.clone() as Arc, + ); + let brain = Brain::new( + provider.clone(), + Arc::clone(®istry), + 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 { + 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 = 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..1605a4c --- /dev/null +++ b/crates/app-iced/Cargo.toml @@ -0,0 +1,108 @@ +[package] +name = "unlucky-app-iced" +description = "Unlucky-Launcher 桌面壳（iced 0.14 重写版）：M3 Expressive 骨架 / 令牌适配 / 截图通道" +version.workspace = true +edition.workspace = true +license.workspace = true +authors.workspace = true +repository.workspace = true +rust-version.workspace = true +publish.workspace = true + +# 并存期（D26）：Slint 版仍是 `crates/app` 的 `unlucky-launcher`，本 crate 出 +# `unlucky-launcher-iced`。两个 package 在同一 target 目录产出同名 bin 会冲突， +# 所以**翻牌前不许改回 `unlucky-launcher`**（步骤见 SubAgentsTalk/app-iced-骨架与翻牌.md）。 +[[bin]] +name = "unlucky-launcher-iced" +path = "src/main.rs" + +[lib] +name = "unlucky_app_iced" +path = "src/lib.rs" + +[dependencies] +# 令牌唯一真源（M61）：颜色/排版/形状/间距/图标几何全部只从这里取。 +unlucky-design = { path = "../design", version = "0.2.4" } + +# 平台识别（Termux / $PREFIX 路径）唯一真源：字体注册这类平台适配不再各写一份环境判断。 +unlucky-core = { path = "../core", version = "0.2.4" } + +# M85：UI 框架无关的宿主层（DTO / 状态 reducer / host）。**只登记依赖，本 mission 不接线**—— +# 页面用它的时机由后续 iced 页面 mission 决定（接线流程见 crates/presenter/src/lib.rs 的 crate 文档）。 +# 与 Slint 版共用同一套 host 与状态语义，这是 D26「重写只换渲染」的落点。 +unlucky-presenter = { path = "../presenter", version = "0.2.4" } + +# UI 框架（D26 锁定 iced 0.14）。**不得依赖 slint**。 +# 关掉默认 features 后必须显式给执行器（M60 踩坑 Q2：否则 `No futures executor has been enabled`）， +# 这里给 `thread-pool`（iced 自己的默认执行器，不额外引 tokio 运行时）。 +# `wgpu` 由本 crate 的 `gpu` feature 打开，于是「仅 CPU」体积基线用 `--no-default-features` 就能量到。 +iced = { version = "=0.14.0", default-features = false, features = [ + "tiny-skia", + "crisp", + "advanced", + # M93：背景图要真图直出 ⇒ 需要渲染器的 image 支持。用 `image-without-codecs` 而不是 + # `image` 是刻意的：后者会打开 `image/default` 的全套编解码器；前者的编解码能力由本 crate + # 依赖表里那条 `image` 的 features 决定（png / jpeg / bmp），不必把 webp/tiff/exr/gif 拖进来。 + "image-without-codecs", + "svg", + "thread-pool", +] } + +# 截图落 PNG + 背景图解码（M93）：png 是截图通道，jpeg/bmp 是用户真会挑的背景图/壁纸格式 +# （M73 的壁纸探测不筛扩展名）。仍不开 default-features——那会拖进 avif/ravif/webp/tiff 一整套。 +image = { version = "0.25", default-features = false, features = [ + "png", + "jpeg", + "bmp", +] } + +# M82：同一个二进制也带 CLI 子命令（`unlucky-launcher-iced instances list` …）， +# 进 UI 之前分发，命中就把控制权交给 `unlucky_cli::run`。依赖方向 app-iced → cli → +# core/agent 不违反 core 零 UI 铁律（core 的依赖树里没有 cli）。零 UI 依赖的 `ull` +# 仍在 `crates/cli`，给没有图形库的机器用——两者不是重复品。 +unlucky-cli = { path = "../cli", version = "0.2.4" } + +# M92（D28）：国际化地基（语言探测 / 消息目录 / 中文字体策略）。零依赖 crate——它拿不到 iced， +# 所以系统字体扫描留在这里（`src/fonts/cjk.rs`），本 crate 只把族名喂给它的纯函数。 +unlucky-i18n = { path = "../i18n", version = "0.2.4" } + +# M97：判据表第 8 行的取证通道。`iced_wgpu` 在真创建设备时会 `log::info!("Selected: {adapter:#?}")`， +# 但进程里从来没人装 logger，于是「看不见」被当成了「没发生」。这里装一个只放行 `iced_wgpu*` / +# `wgpu*` 的 logger（见 `src/renderer/log_bridge.rs`），把这行捞出来。 +# 已是 iced 传递依赖树里的版本（0.4.34），不新增任何传递依赖；MIT OR Apache-2.0，许可白名单内。 +log = { version = "0.4", features = ["std"] } + +# X11 / Wayland 后端与 Linux 主题检测只在 Linux 上启用：macOS 没有 X11/Wayland（走 Metal + +# 系统外观），Windows 走 DX12，这三个 feature 在那边没有意义。同一个包在两处写 features 是 +# **取并集**（Cargo 的 feature 解析是加法），所以 Linux 上拿到的仍是上面 5 个 + 这 3 个， +# Windows / macOS 只拿上面那 5 个（`cargo tree --target` 可复核）。 +# 诚实边界：这**不**解决「iced 版至今没在 macOS 上编过」这件事——`iced_winit` 已把 `mundy` +# 放在 `cfg(target_os = "linux")` 段里，这三个 feature 在非 Linux 上本来就不拉依赖，这里只是 +# 让本仓库的依赖图按平台自述清楚，不再把 Linux 专属能力写成全平台事实。 +[target.'cfg(target_os = "linux")'.dependencies] +iced = { version = "=0.14.0", default-features = false, features = [ + "x11", + "wayland", + "linux-theme-detection", +] } + +[features] +default = ["gpu"] +# 硬件渲染后端（wgpu→Vulkan/DX12）。关闭后只剩 tiny-skia（CPU），用于体积基线与无 GPU 机器。 +gpu = ["iced/wgpu"] +# M169：把「本地更新源」这条测试通道编进 GUI（默认关）。人工验收更新链路时的构建方式： +# ULL_UPDATE_DIR= ULL_UPDATE_TEST_SOURCE=1 \ +# cargo run -p unlucky-app-iced --features update-test-source +# ⚠ `-p` 只认 **package** 名（`unlucky-app-iced`），`unlucky-launcher-iced` 是它在 [[bin]] 里 +# 声明的 bin 名——写成 `-p unlucky-launcher-iced` 会 `package(s) … not found`（r1 复审 P2-1）。 +# 转发给 presenter 与内嵌的 cli（两者都依赖 core，feature 取并集）；官方发布构建不带它。 +update-test-source = ["unlucky-presenter/update-test-source", "unlucky-cli/update-test-source"] + +[lints] +workspace = true + +# M190：把版本资源写进 PE（Windows「属性 → 详细信息」里的发布者/产品/版权/版本）。 +# 只在 windows 目标上真跑（`build.rs` 先看 CARGO_CFG_TARGET_OS，其它平台直接返回）， +# 共享口径在 `packaging/pe_version.rs`（两个 bin 各 include 一次，署名不会漂）。 +[build-dependencies] +winresource = "0.1" diff --git a/crates/app-iced/build.rs b/crates/app-iced/build.rs new file mode 100644 index 0000000..30cd908 --- /dev/null +++ b/crates/app-iced/build.rs @@ -0,0 +1,14 @@ +//! `unlucky-launcher-iced` 的 PE 版本资源（M190）。 +//! +//! 与 `crates/cli/build.rs` 同一份共享口径（`packaging/pe_version.rs`）：两个产物的 +//! CompanyName / ProductName / LegalCopyright / 版本号必须逐字相同。 +//! +//! ⚠ 本文件**只**写版本资源，不碰子系统：PE 的 `Subsystem` 由 rustc 的 +//! `windows_subsystem` 属性决定（本分支上还没有那个属性，是 M196 的事），版本资源与子系统是两件事。 +//! 判据：`packaging/check_pe_version.py` 会把它读到的 `subsystem` 打出来，加资源前后必须一致。 + +include!("../../packaging/pe_version.rs"); + +fn main() { + emit_pe_version_resource("unlucky-launcher-iced"); +} 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 ] \ + [--height ] [--theme=light|dark] [--screenshot-theme=light|dark] \ + [--screenshot ] [--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/adopt.rs b/crates/app-iced/src/app/adopt.rs new file mode 100644 index 0000000..b6db869 --- /dev/null +++ b/crates/app-iced/src/app/adopt.rs @@ -0,0 +1,261 @@ +//! 「导入已有版本」向导（M223 GUIADOPT）：实例页页头的入口 + 一张盖在页面上的向导卡。 +//! +//! ## 四段（与 presenter 的 `AdoptState` 一一对应） +//! +//! | 段 | 画什么 | 从哪来 | 文件 | +//! |---|---|---|---| +//! | Pick | 候选版本 + 目标档 + 实例名 | `AdoptEvent::Scan` | [`pick`] | +//! | Preview | 落点 / 隔离档 / **`target_notes()` 原文** | `AdoptEvent::Planned` | [`panes`] | +//! | Failed | 稳定码 + 人读原因 + **`problems[]` 逐条** | `AdoptEvent::Failed` | [`panes`] | +//! | Done | 实例名 / 运行目录 / 提示原文 | `AdoptEvent::Done` | [`panes`] | +//! +//! 「现在画哪一段」的判据只有一处：presenter 的 `AdoptState::stage`，外面套一条收窄 +//! [`Form::stage`]——`Preview` 只在用户**点过预检**（`Form::checked`）之后才算数。收窄的理由： +//! 共享档 / 版本目录档一被点选就要显示后果原文（§5.2），那要用一次**零写盘**的预检换； +//! 但那次结果不该把用户直接甩到确认页（实例名还没填完）。 +//! +//! 卡壳与页脚在 [`shell`]（定高可滚 / 收高两种几何），三段视图在 [`pick`] 与 [`panes`]， +//! 等宽与正文小工具在 `text`，D30 出图种子在 `shot`（`ULL_ADOPT_STATE`，只在 `--screenshot` 下生效）。 +//! +//! ## 三条纪律（契约 §5 的 1/2/3） +//! +//! 1. **运行目录不派生**：Preview / Done 上那个路径**原样**来自回程事件（缺省档可能带 `-2` 后缀， +//! 只有 core 知道最后用了哪个）。本模块没有任何「拼一个目录名」的代码。 +//! 2. **后果话术不重写**：共享档 / 版本目录档的后果句在 Preview 段**逐条**画 `plan.notes` +//! （core `target_notes()` 的原文）。Pick 段只放一句短提示（选之前就得知道会碰别人的目录）， +//! 真正的后果原文在确认按钮之前一定会出现。 +//! 3. **不折叠问题**：Failed 段把 `problems` 一条一行画出来，标题只说「导入失败」，原因全在下面。 +//! +//! ## 为什么是「盖一层」而不是实例页里的一段 +//! +//! 向导有四段状态、每段内容都不一样，塞进 list-detail 的正文列会把版式判据（424 散文宽、 +//! 列表独立滚动）搅乱。盖一层与 M187 的模态同一手法（遮罩 + 居中卡），但**不是** +//! `DialogQueue` 那种「标题 + 正文 + 两个按钮」的窄形态：向导要画候选列表、单选档位与输入框。 +//! +//! ## 表单字段归 `App`，事件真相归 presenter +//! +//! [`Form`] 只装「用户正在填的东西」（选中哪个版本、展示名、目标档、有没有在等回程）； +//! 候选、预检、失败、完成全部来自 `AppState.adopt`（presenter 的 `AdoptState`）。两边各管一半， +//! 于是「画出来的落点」与「真正写盘的落点」永远是同一份事实。 + +mod panes; +mod pick; +mod shell; +/// D30 出图用的状态夹具（只在 `--screenshot` 下按环境变量生效）。 +pub(crate) mod shot; +mod text; + +#[cfg(test)] +mod tests; + +use iced::widget::{container, mouse_area, opaque, Space}; +use iced::{Alignment, Background, Element, Length}; + +use unlucky_design::spacing::Space as Sp; +use unlucky_i18n::{Catalog, Lang}; +use unlucky_presenter::dto::{ + AdoptCandidateView, AdoptPlanView, AdoptStage, AdoptState, AdoptTargetView, +}; + +use crate::app::components::feedback::dialog::scrim; +use crate::theme::Ui; + +use super::message::Message; + +/// 向导卡宽度：比模态卡（560）宽一档——候选行要放「版本 id + 状态」，目标档是三枚 chip。 +const CARD_WIDTH: f32 = 640.0; + +/// 卡片的最大高（窗口更矮时整卡按窗口走：内容在中间区滚）。 +const CARD_MAX_HEIGHT: f32 = 620.0; + +/// 正在等哪一条命令的回程。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub enum Busy { + /// 空闲（可以点） + #[default] + Idle, + /// 正在扫描 `versions/` + Scanning, + /// 正在预检（零写盘） + Checking, + /// 正在真正登记 + Importing, +} + +impl Busy { + /// 有没有在等回程。 + #[must_use] + pub const fn waiting(self) -> bool { + !matches!(self, Self::Idle) + } +} + +/// 向导的表单态（**归 `App`**，页面借一帧）。 +#[derive(Debug, Default)] +pub struct Form { + /// 面板开着吗 + pub open: bool, + /// 选中的版本 id（`None` = 还没选） + pub selected: Option, + /// 展示名（空 = 用版本 id） + pub name: String, + /// 运行目录档（缺省 [`AdoptTargetView::InstanceDir`]，**不是** isolated） + pub target: AdoptTargetView, + /// 在等在飞的那一条命令 + pub busy: Busy, + /// 用户已经点过「预检」（没点过就留在 Pick 段，哪怕后台已经顺手算过一次落点）。 + /// + /// 为什么要有这一位：共享档 / 版本目录档一旦被点选，界面就要立刻显示 `target_notes()` 的 + /// **后果原文**（契约 §5.2）——那是 core 唯一会产出这段文字的地方，所以点选时顺手发一次 + /// **零写盘**的预检。但那一次结果不该把用户甩到「可以导入」的确认页：确认必须由显式的 + /// `Check` 触发。于是 `checked` 记住「这次预检是不是用户要的」。 + pub checked: bool, +} + +impl Form { + /// 打开面板（回到 Pick 段、清掉上一轮的选中与名字）。 + pub fn open(&mut self) { + *self = Self { + open: true, + busy: Busy::Scanning, + ..Self::default() + }; + } + + /// 关掉面板（全清）。 + pub fn close(&mut self) { + *self = Self::default(); + } + + /// 回程到了：不在等任何东西了。 + pub fn settled(&mut self) { + self.busy = Busy::Idle; + } + + /// 当前该画哪一段：`Preview` 只在用户**点过预检**之后才算数，其余按 `AdoptState::stage()`。 + /// + /// 这条收窄是为了「点选共享档 ⇒ 立刻看到后果原文」而不把用户直接甩到确认页： + /// 自动预检的结果落在 Pick 段里当**提示**读，用户点「预检」之后才进确认段。 + #[must_use] + pub fn stage(&self, adopt_state: &AdoptState) -> AdoptStage { + match adopt_state.stage() { + AdoptStage::Preview if !self.checked => AdoptStage::Pick, + other => other, + } + } + + /// 后台算出来、且**对得上当前选择**的预检（对不上 = 过期的结果，一律不画）。 + /// + /// 两个判据缺一不可： + /// - **目标档一致**：改了档之后旧 plan 的 `notes` 说的是别的目录； + /// - **版本 id 一致**：换了版本之后旧 plan 的 `notes` 说的是别的版本目录 + /// （版本目录档的后果原文里带 `versions/`，拿它当新版本的后果就是撒谎）。 + /// + /// 没有选中版本时也返回 `None`：那一刻没有任何版本可言，画谁的预检都不成立。 + /// 这两条都不是「选中即重扫」带来的——`Select` 只改本地字段、不发命令（落点见 + /// `app/update/adopt.rs`），所以过期判定只能在这里做。 + #[must_use] + pub fn fresh_plan<'a>(&self, adopt_state: &'a AdoptState) -> Option<&'a AdoptPlanView> { + let selected = self.selected.as_deref()?; + adopt_state + .plan + .as_ref() + .filter(|plan| plan.target == self.target && plan.version_id == selected) + } + + /// 当前选中的候选（选中项已不在列表里时返回 `None`，界面自动退回「请选择」）。 + #[must_use] + pub fn candidate<'a>(&self, adopt_state: &'a AdoptState) -> Option<&'a AdoptCandidateView> { + let id = self.selected.as_deref()?; + adopt_state + .scan + .as_ref()? + .candidates + .iter() + .find(|candidate| candidate.version_id == id) + } +} + +/// 向导消息（`crate::app::Message::Adopt` 的载荷）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum AdoptMessage { + /// 打开向导（实例页页头「导入」） + Open, + /// 关掉（点遮罩 / 关闭按钮） + Close, + /// 选中一个候选版本 + Select(String), + /// 改展示名 + Name(String), + /// 改运行目录档 + Target(AdoptTargetView), + /// 预检（零写盘） + Check, + /// 确认登记（唯一写盘入口） + Confirm, + /// 从 Preview / Failed 退回候选列表（等价于重新扫一次） + Back, +} + +/// 向导消息 → app 消息。 +fn adopt(message: AdoptMessage) -> Message { + Message::Adopt(message) +} + +// --------------------------------------------------------------- 视图 + +/// 把向导叠在页面之上（没打开时原样返回页面树）。 +pub(super) fn layer<'a>( + ui: &'a Ui, + base: Element<'a, Message>, + form: &'a Form, + adopt_state: &'a AdoptState, + lang: Lang, +) -> Element<'a, Message> { + if !form.open { + return base; + } + let catalog = lang.catalog(); + let backdrop = mouse_area( + container(Space::new()) + .width(Length::Fill) + .height(Length::Fill) + .style(move |_theme| container::Style { + background: Some(Background::Color(scrim(ui))), + ..container::Style::default() + }), + ) + .on_press(adopt(AdoptMessage::Close)); + + // 透明的一层只负责居中；吃点击的 `opaque` 只包卡片（点卡内不关，点遮罩才关）。 + let centered = container(opaque(shell::card(ui, form, adopt_state, catalog))) + .width(Length::Fill) + .height(Length::Fill) + .align_x(Alignment::Center) + .align_y(Alignment::Center) + .padding(ui.space(Sp::X6)); + + iced::widget::stack![base, backdrop, centered].into() +} + +/// 中间区（按段交给 `pick` / `panes`）。 +pub(super) fn middle<'a>( + ui: &'a Ui, + form: &'a Form, + adopt_state: &'a AdoptState, + stage: AdoptStage, + catalog: Catalog, +) -> Element<'a, Message> { + match stage { + AdoptStage::Pick => pick::pick( + ui, + form, + adopt_state.scan.as_ref(), + form.fresh_plan(adopt_state), + catalog, + ), + AdoptStage::Preview => panes::preview(ui, form.fresh_plan(adopt_state), catalog), + AdoptStage::Failed => panes::failed(ui, adopt_state.failure.as_ref(), catalog), + AdoptStage::Done => panes::done(ui, adopt_state.done.as_ref(), catalog), + } +} diff --git a/crates/app-iced/src/app/adopt/panes.rs b/crates/app-iced/src/app/adopt/panes.rs new file mode 100644 index 0000000..e3675f4 --- /dev/null +++ b/crates/app-iced/src/app/adopt/panes.rs @@ -0,0 +1,127 @@ +//! Preview / Failed / Done 三段。 +//! +//! | 段 | 画什么 | 判据 | +//! |---|---|---| +//! | Preview | 生效运行目录（**回程给的**）+ 隔离档 + `notes` 原文逐条 | `AdoptEvent::Planned` | +//! | Failed | 稳定码 + `problems[]` 逐条 | `AdoptEvent::Failed` | +//! | Done | 实例名 + 运行目录 + `notes` 原文逐条 | `AdoptEvent::Done` | +//! +//! 三段都不自己算路径、不自己写后果句：`run_dir` 与 `notes` 是 core 的返回值原样。 +//! 缺省档会带 `-2`/`-3` 后缀（两个不同展示名可能落到同一个物理目录），**只有 core 知道** +//! 最后用了哪个——页面对它再做一次派生就会与真正启动时用的目录分叉。 + +use iced::widget::column; +use iced::{Element, Length}; + +use unlucky_design::color::Role; +use unlucky_design::spacing::Space as Sp; +use unlucky_i18n::{Catalog, Key}; +use unlucky_presenter::dto::{AdoptDoneView, AdoptFailureView, AdoptPlanView}; + +use crate::theme::Ui; + +use super::super::message::Message; +use super::text::{field_line, isolation_label, mono, problem_line, wrapped}; + +/// 预检结果：落点 + 隔离档 + 后果原文。 +pub(super) fn preview<'a>( + ui: &'a Ui, + plan: Option<&'a AdoptPlanView>, + catalog: Catalog, +) -> Element<'a, Message> { + let Some(plan) = plan else { + return wrapped( + ui, + catalog.text(Key::AdoptScanning).to_string(), + ui.color(Role::OnSurfaceVariant), + ); + }; + let mut body = column![ + field_line(ui, catalog.text(Key::AdoptInstanceName), &plan.name), + field_line( + ui, + catalog.text(Key::AdoptPlanRunDir), + &plan.run_dir.display().to_string() + ), + field_line( + ui, + catalog.text(Key::AdoptPlanIsolation), + &isolation_label(plan.isolation, catalog), + ), + ] + .spacing(ui.space(Sp::X2)) + .width(Length::Fill); + + // 后果话术：core `target_notes()` 的原文，一条一行、一个字不改 + for note in &plan.notes { + body = body.push(wrapped(ui, note.clone(), ui.color(Role::OnSurfaceVariant))); + } + body.into() +} + +/// 失败：稳定码 + **problems 逐条**。 +pub(super) fn failed<'a>( + ui: &'a Ui, + failure: Option<&'a AdoptFailureView>, + catalog: Catalog, +) -> Element<'a, Message> { + let Some(failure) = failure else { + return wrapped( + ui, + catalog.text(Key::AdoptScanning).to_string(), + ui.color(Role::OnSurfaceVariant), + ); + }; + let mut body = column![mono(ui, failure.code.clone())] + .spacing(ui.space(Sp::X2)) + .width(Length::Fill); + + if failure.problems.is_empty() { + body = body.push(wrapped( + ui, + failure.message.clone(), + ui.color(Role::OnSurfaceVariant), + )); + return body.into(); + } + body = body.push(wrapped( + ui, + catalog.text(Key::AdoptProblemCount).to_string(), + ui.color(Role::OnSurfaceVariant), + )); + for problem in &failure.problems { + body = body.push(problem_line(ui, problem)); + } + body.into() +} + +/// 完成：实例名 + 运行目录 + 提示原文。 +pub(super) fn done<'a>( + ui: &'a Ui, + done: Option<&'a AdoptDoneView>, + catalog: Catalog, +) -> Element<'a, Message> { + let Some(done) = done else { + return wrapped(ui, String::new(), ui.color(Role::OnSurfaceVariant)); + }; + let mut body = column![ + field_line(ui, catalog.text(Key::AdoptInstanceName), &done.name), + field_line( + ui, + catalog.text(Key::AdoptPlanRunDir), + &done.run_dir.display().to_string() + ), + field_line( + ui, + catalog.text(Key::AdoptPlanIsolation), + &isolation_label(done.isolation, catalog), + ), + ] + .spacing(ui.space(Sp::X2)) + .width(Length::Fill); + + for note in &done.notes { + body = body.push(wrapped(ui, note.clone(), ui.color(Role::OnSurfaceVariant))); + } + body.into() +} diff --git a/crates/app-iced/src/app/adopt/pick.rs b/crates/app-iced/src/app/adopt/pick.rs new file mode 100644 index 0000000..a3467fa --- /dev/null +++ b/crates/app-iced/src/app/adopt/pick.rs @@ -0,0 +1,228 @@ +//! Pick 段：候选列表 + 目标档 + 实例名。 +//! +//! **可导入的候选才可点**：不可导入的行把 `problems` 逐条列在下面但不接点击——点它只会换来 +//! 一条注定被 core 拒绝的命令（`adopt_not_adoptable`），而用户从行上已经看到了原因。 +//! +//! 目标档三枚 chip 的**短提示**在选中时立刻换（共享/版本目录档用 `Error` 色）； +//! **后果原文**不在这里——它在 Preview 段逐条画 `plan.notes`（core `target_notes()` 的原文）。 + +use iced::widget::{button, column, container, row}; +use iced::{Alignment, Background, Border, Color, Element, Length}; + +use unlucky_design::color::Role; +use unlucky_design::shape::ShapeScale; +use unlucky_design::spacing::Space as Sp; +use unlucky_design::typography::TypeRole; +use unlucky_i18n::{Catalog, Key}; +use unlucky_presenter::dto::{AdoptCandidateView, AdoptPlanView, AdoptScanView, AdoptTargetView}; + +use crate::app::components::inputs::{text_field, Field}; +use crate::app::components::selection::{chip, Chip}; +use crate::pages::frame; +use crate::theme::Ui; + +use super::super::message::Message; +use super::text::{label, problem_line, target_label, wrapped}; +use super::{adopt, AdoptMessage, Form}; + +/// Pick 段整体。 +pub(super) fn pick<'a>( + ui: &'a Ui, + form: &'a Form, + scan: Option<&'a AdoptScanView>, + plan: Option<&'a AdoptPlanView>, + catalog: Catalog, +) -> Element<'a, Message> { + let Some(scan) = scan else { + // 扫描还没回来：一行进度文案（不做假进度条） + return wrapped( + ui, + catalog.text(Key::AdoptScanning).to_string(), + ui.color(Role::OnSurfaceVariant), + ); + }; + + let mut body = column![].spacing(ui.space(Sp::X3)).width(Length::Fill); + if scan.is_empty() { + let dir = scan.versions_dir.display().to_string(); + body = body.push(wrapped( + ui, + catalog.render(Key::AdoptEmpty, &[("dir", &dir)]), + ui.color(Role::OnSurfaceVariant), + )); + } else { + body = body.push(label(ui, catalog.text(Key::AdoptSelectLabel))); + body = body.push(candidate_list(ui, form, scan, catalog)); + } + + body = body.push(frame::divider(ui).map(Message::Page)); + body = body.push(label(ui, catalog.text(Key::AdoptTargetLabel))); + body = body.push(target_row(ui, form, catalog)); + // 后果原文（契约 §5.2）：共享档 / 版本目录档一被点选就显示 core `target_notes()` 的原文—— + // 这一条来自**零写盘**的自动预检（见 `AdoptMessage::Target` 的落点），不是界面另写的一句。 + if let Some(plan) = plan { + for note in &plan.notes { + body = body.push(wrapped(ui, note.clone(), ui.color(Role::OnSurfaceVariant))); + } + } + body = body.push(text_field( + ui, + Field::new(form.name.as_str()).label(catalog.text(Key::AdoptNameLabel)), + |value| adopt(AdoptMessage::Name(value)), + )); + body.into() +} + +/// 候选列表（可滚，定高：列表再长页脚按钮也留在卡里）。 +fn candidate_list<'a>( + ui: &'a Ui, + form: &'a Form, + scan: &'a AdoptScanView, + catalog: Catalog, +) -> Element<'a, Message> { + let rows = column( + scan.candidates + .iter() + .map(|candidate| candidate_row(ui, form, candidate, catalog)) + .collect::>(), + ) + .spacing(ui.space(Sp::X1)) + .width(Length::Fill); + + rows.into() +} + +/// 一条候选。 +fn candidate_row<'a>( + ui: &'a Ui, + form: &'a Form, + candidate: &'a AdoptCandidateView, + catalog: Catalog, +) -> Element<'a, Message> { + let selected = form.selected.as_deref() == Some(candidate.version_id.as_str()); + + let mut items = column![row![ + frame::text_role( + ui, + TypeRole::BodyLarge, + selected, + candidate.version_id.as_str(), + ui.color(Role::OnSurface), + ) + .map(Message::Page), + container(status(ui, candidate, selected, catalog)) + .width(Length::Fill) + .align_x(Alignment::End), + ] + .width(Length::Fill) + .align_y(Alignment::Center)] + .spacing(ui.space(Sp::X1)) + .width(Length::Fill); + + // 问题逐条（不折叠）：候选阶段就把「为什么不能导入」说清楚 + for problem in &candidate.problems { + items = items.push(problem_line(ui, problem)); + } + + let body = container(items) + .width(Length::Fill) + .padding(ui.space(Sp::X2)) + .style(move |_theme| container::Style { + background: selected.then(|| Background::Color(ui.color(Role::SecondaryContainer))), + border: Border { + radius: ui.radius_dp(ShapeScale::Medium), + ..Border::default() + }, + ..container::Style::default() + }); + + if !candidate.adoptable() { + // 不可导入的行**不可点**（也就不存在「点了才被告知不行」这条路） + return body.into(); + } + button(body) + .width(Length::Fill) + .padding(0) + .style(|_theme, _status| button::Style { + background: None, + text_color: Color::TRANSPARENT, + border: Border::default(), + shadow: iced::Shadow::default(), + snap: true, + }) + .on_press(adopt(AdoptMessage::Select(candidate.version_id.clone()))) + .into() +} + +/// 候选右侧那枚状态（可导入 / N 个问题 / 已被某实例使用）。 +fn status<'a>( + ui: &'a Ui, + candidate: &AdoptCandidateView, + selected: bool, + catalog: Catalog, +) -> Element<'a, Message> { + if !candidate.adoptable() { + let count = candidate.problems.len().to_string(); + return wrapped( + ui, + catalog.render(Key::AdoptBlocked, &[("count", &count)]), + ui.color(Role::Error), + ); + } + if let Some(name) = candidate.registered.first() { + return wrapped( + ui, + catalog.render(Key::AdoptRegistered, &[("name", name)]), + ui.color(Role::OnSurfaceVariant), + ); + } + if selected { + return chip(ui, Chip::current(catalog.text(Key::AdoptReady))); + } + wrapped( + ui, + catalog.text(Key::AdoptReady).to_string(), + ui.color(Role::OnSurfaceVariant), + ) +} + +/// 三枚目标 chip（缺省档在最前；共享 / 版本目录档必须**明确点选**）。 +fn target_row<'a>(ui: &'a Ui, form: &'a Form, catalog: Catalog) -> Element<'a, Message> { + let chips = AdoptTargetView::ALL + .into_iter() + .map(|target| { + chip( + ui, + Chip::filter( + target_label(target, catalog), + form.target == target, + adopt(AdoptMessage::Target(target)), + ), + ) + }) + .collect::>(); + + column![ + row(chips).spacing(ui.space(Sp::X2)).width(Length::Fill), + target_hint(ui, form.target, catalog), + ] + .spacing(ui.space(Sp::X1)) + .width(Length::Fill) + .into() +} + +/// 目标档的一句话说明（点选后立刻换）。**不是后果原文**：原文在 Preview 段逐条画 +/// `plan.notes`（core `target_notes()`）。 +fn target_hint<'a>(ui: &'a Ui, target: AdoptTargetView, catalog: Catalog) -> Element<'a, Message> { + let key = match target { + AdoptTargetView::InstanceDir => Key::AdoptTargetInstanceDirHint, + AdoptTargetView::Shared => Key::AdoptTargetSharedHint, + AdoptTargetView::VersionDir => Key::AdoptTargetVersionDirHint, + }; + let color = if target.touches_foreign_dir() { + ui.color(Role::Error) + } else { + ui.color(Role::OnSurfaceVariant) + }; + wrapped(ui, catalog.text(key).to_string(), color) +} diff --git a/crates/app-iced/src/app/adopt/shell.rs b/crates/app-iced/src/app/adopt/shell.rs new file mode 100644 index 0000000..35a6051 --- /dev/null +++ b/crates/app-iced/src/app/adopt/shell.rs @@ -0,0 +1,198 @@ +//! 向导卡的外壳与页脚（M223 从 `app/adopt.rs` 搬出，守 400 行硬线）。 +//! +//! | 函数 | 职责 | +//! |---|---| +//! | [`card`] | 卡壳（标题 + 说明 + 中间区 + 页脚）、定高/收高两种几何、遮罩上的那一张卡 | +//! | [`title_text`] / [`subtitle`] | 四段的标题与一句说明（文案全部来自 i18n 目录） | +//! | [`footer`] | 按段给按钮组合；在等回程时主按钮禁用 | +//! +//! ## 这个文件不是「纯搬移」 +//! +//! 它**起于**一次搬移：`app/adopt.rs` 落笔 412 行越过 `components::gate` 的 400 行硬线， +//! 于是把卡壳 / 标题 / 页脚搬到这里。但**同一个提交里**这三块还改过行为与几何，逐条如下 +//! （复审对 diff 时按这几条看，别按「一行未改」看）： +//! +//! | 改了什么 | 为什么 | +//! |---|---| +//! | `card` 拆成「定高 + 中间区可滚」（Pick / Failed）与「按内容收高」（Preview / Done）两种几何 | 原来只给 `max_height`，内容一高就被裁：页脚按钮与实例名整排不可见（出图时抓到） | +//! | `footer` 的「关闭」只在 Pick / Preview 出现 | Failed / Done 的主按钮就是关闭，再给一枚文字关闭就是两枚一模一样的按钮 | +//! | `subtitle` 的 Preview 文案改成「版本名 · 目标档」 | 原来打「隔离档 · 目标档」，同屏两个「共用目录」 | +//! +//! 调用方仍是 `app/adopt.rs` 的 `layer` 与 `middle`。 + +use iced::widget::{column, container, row, scrollable, Space}; +use iced::{Background, Element, Length}; + +use unlucky_design::color::Role; +use unlucky_design::elevation::MaterialLayer; +use unlucky_design::shape::ShapeScale; +use unlucky_design::spacing::Space as Sp; +use unlucky_design::typography::TypeRole; +use unlucky_i18n::{Catalog, Key}; +use unlucky_presenter::dto::{AdoptStage, AdoptState}; + +use crate::app::components::buttons::{self, Button}; +use crate::pages::frame; +use crate::theme::Ui; + +use super::super::message::Message; +use super::text::{target_label, wrapped}; +use super::{adopt, middle, AdoptMessage, Form, CARD_MAX_HEIGHT, CARD_WIDTH}; + +/// 卡片本体：标题 + 一句说明 + 中间（按段） + 页脚按钮。 +pub(super) fn card<'a>( + ui: &'a Ui, + form: &'a Form, + adopt_state: &'a AdoptState, + catalog: Catalog, +) -> Element<'a, Message> { + let stage = form.stage(adopt_state); + let middle = middle(ui, form, adopt_state, stage, catalog); + let head = column![ + frame::text_role( + ui, + TypeRole::HeadlineSmall, + true, + title_text(stage, catalog), + ui.color(Role::OnSurface), + ) + .map(Message::Page), + wrapped( + ui, + subtitle(stage, adopt_state, catalog), + ui.color(Role::OnSurfaceVariant) + ), + frame::divider(ui).map(Message::Page), + ] + .spacing(ui.space(Sp::X3)) + .width(Length::Fill); + + let tail = column![ + frame::divider(ui).map(Message::Page), + footer(ui, form, adopt_state, stage, catalog), + ] + .spacing(ui.space(Sp::X3)) + .width(Length::Fill); + + // 列表段（Pick / Failed）**定高 + 中间区可滚**：内容再长，页脚按钮也不会被裁掉 + // （第一版就是被裁掉的）。短内容段（Preview / Done）按内容高收，不留一大片空白。 + let list_stage = matches!(stage, AdoptStage::Pick | AdoptStage::Failed); + let card = if list_stage { + let body = column![ + head, + scrollable(middle) + .height(Length::Fill) + .style(frame::scroll_style(ui)), + tail, + ] + .spacing(ui.space(Sp::X3)) + .width(Length::Fill); + container(body) + .width(Length::Fixed(CARD_WIDTH)) + .height(Length::Fixed(CARD_MAX_HEIGHT)) + } else { + let body = column![head, middle, tail] + .spacing(ui.space(Sp::X3)) + .width(Length::Fill); + container(body) + .width(Length::Fixed(CARD_WIDTH)) + .max_height(CARD_MAX_HEIGHT) + }; + + card.padding(ui.space(Sp::X6)) + .style(move |_theme| container::Style { + background: Some(Background::Color(ui.layer(MaterialLayer::Overlay))), + border: ui.outlined(ShapeScale::ExtraLarge), + ..container::Style::default() + }) + .into() +} + +/// 段标题（四段各一句）。 +pub(super) fn title_text(stage: AdoptStage, catalog: Catalog) -> &'static str { + match stage { + AdoptStage::Pick => catalog.text(Key::AdoptTitle), + AdoptStage::Preview => catalog.text(Key::AdoptPlanTitle), + AdoptStage::Failed => catalog.text(Key::AdoptFailureTitle), + AdoptStage::Done => catalog.text(Key::AdoptDoneTitle), + } +} + +/// 标题下那句说明（Pick 段说清「什么都不复制」；Done 段说清「去实例列表启动」）。 +pub(super) fn subtitle(stage: AdoptStage, adopt_state: &AdoptState, catalog: Catalog) -> String { + match stage { + AdoptStage::Pick => catalog.text(Key::AdoptSubtitle).to_string(), + // 预检：版本名 · 目标档（隔离档在正文里单独一行，重复一遍只会更吵） + AdoptStage::Preview => adopt_state + .plan + .as_ref() + .map(|plan| format!("{} · {}", plan.name, target_label(plan.target, catalog))) + .unwrap_or_default(), + AdoptStage::Failed => adopt_state + .failure + .as_ref() + .map(|failure| failure.message.clone()) + .unwrap_or_default(), + AdoptStage::Done => catalog.text(Key::AdoptDoneHint).to_string(), + } +} + +/// 页脚按钮（按段给不同组合；在等回程时主按钮禁用）。 +pub(super) fn footer<'a>( + ui: &'a Ui, + form: &'a Form, + adopt_state: &'a AdoptState, + stage: AdoptStage, + catalog: Catalog, +) -> Element<'a, Message> { + let busy = form.busy.waiting(); + + let primary: Element<'a, Message> = match stage { + AdoptStage::Pick => { + let ready = form.candidate(adopt_state).is_some_and(|c| c.adoptable()) && !busy; + if ready { + buttons::filled( + ui, + Button::new(catalog.text(Key::AdoptPreview), adopt(AdoptMessage::Check)), + ) + } else { + buttons::filled(ui, Button::disabled(catalog.text(Key::AdoptPreview))) + } + } + AdoptStage::Preview if !busy => buttons::filled( + ui, + Button::new( + catalog.text(Key::AdoptConfirm), + adopt(AdoptMessage::Confirm), + ), + ), + AdoptStage::Preview => { + buttons::filled(ui, Button::disabled(catalog.text(Key::AdoptConfirm))) + } + // 失败 / 完成：主按钮就是关掉（Done 不用「去列表看」——实例已经在列表里了） + AdoptStage::Failed | AdoptStage::Done => buttons::filled( + ui, + Button::new(catalog.text(Key::AdoptClose), adopt(AdoptMessage::Close)), + ), + }; + + let mut actions = row![].spacing(ui.space(Sp::X2)).width(Length::Fill); + // Preview / Failed 给一条「退回候选列表」（= 重新扫一次，代价只有一次读目录） + if matches!(stage, AdoptStage::Preview | AdoptStage::Failed) { + actions = actions.push(buttons::text( + ui, + Button::new(catalog.text(Key::AdoptBack), adopt(AdoptMessage::Back)), + )); + } + actions = actions.push(container(Space::new()).width(Length::Fill)); + // 失败/完成段的主按钮就是「关闭」，再给一枚文字「关闭」就是两枚一模一样的按钮 + if matches!(stage, AdoptStage::Pick | AdoptStage::Preview) { + actions = actions.push(buttons::text( + ui, + Button::new(catalog.text(Key::AdoptClose), adopt(AdoptMessage::Close)), + )); + } + actions = actions.push(primary); + + column![actions].width(Length::Fill).into() +} diff --git a/crates/app-iced/src/app/adopt/shot.rs b/crates/app-iced/src/app/adopt/shot.rs new file mode 100644 index 0000000..cd48a14 --- /dev/null +++ b/crates/app-iced/src/app/adopt/shot.rs @@ -0,0 +1,205 @@ +//! 出图用的向导状态夹具（D30 视觉验收的输入）。 +//! +//! ## 为什么要有它 +//! +//! 向导是**四段有状态**的界面，而截图通道只跑一次 `view()`（第 3 帧落盘），没有真人点按钮。 +//! 组件库的做法是 `--screen=gallery` + `ForcedState`，页面层的做法是 `pages/instances/demo.rs` +//! 的 `DEMO`——同一类要求，同一类做法：**给渲染器一份确定的状态**，而不是让截图去赌异步时序。 +//! +//! ## 哪些是真、哪些是夹具（复审请照这条核对） +//! +//! | 内容 | 来源 | +//! |---|---| +//! | 候选 / 问题 / 失败原因 | **夹具**（合成的 id 与问题文本，只为把版面撑到真实形态） | +//! | 运行目录 / 隔离档 | 夹具（固定路径，便于两张图逐像素对照） | +//! | **后果原文** | **真**：`unlucky_core::game::adopt::target_notes()` 现算，一个字不抄 | +//! | 文案（标题/标签/按钮） | **真**：`unlucky_i18n` 目录 | +//! | 渲染 | **真**：`--software-renderer`（tiny-skia）1180×760，与产品路径同一棵控件树 | +//! +//! 也就是说：这些图证明**版面与文案**，不证明 core 的判据（判据的证据在 `host/adopt/tests.rs` +//! 与 `core/tests/adopt/`）。 +//! +//! ## 怎么用 +//! +//! ```text +//! ULL_ADOPT_STATE=pick|pick-selected|empty|preview|shared|failed|done \ +//! unlucky-launcher-iced.exe --software-renderer --screenshot [--screenshot-theme dark] +//! ``` +//! +//! 只在 `--screenshot` 已经给了的情况下生效（交互模式读这个环境变量没有意义，直接忽略）。 + +use std::path::PathBuf; + +use unlucky_core::game::adopt::{target_notes, AdoptTarget}; +use unlucky_presenter::dto::{ + AdoptCandidateView, AdoptDoneView, AdoptEvent, AdoptFailureView, AdoptIsolationView, + AdoptPlanView, AdoptProblemView, AdoptScanView, AdoptState, AdoptTargetView, +}; + +use super::{Busy, Form}; + +/// 夹具里的版本目录（只是**画**出来的路径，不碰盘）。 +const VERSIONS_DIR: &str = "D:/minecraft/.minecraft/versions"; + +/// 夹具里的数据区运行目录。 +const INSTANCE_RUN_DIR: &str = "D:/ULL/.ULL/data/instances/Better-MC"; + +/// 夹具里的游戏根。 +const GAME_ROOT: &str = "D:/minecraft/.minecraft"; + +/// 环境变量名（见模块文档）。 +pub(crate) const ENV: &str = "ULL_ADOPT_STATE"; + +/// 按名字造一份「打开着的向导」；不认识的名字返回 `None`（不影响正常启动）。 +pub(crate) fn seed(name: &str) -> Option<(Form, AdoptState)> { + let name = name.trim().to_ascii_lowercase(); + let mut form = Form { + open: true, + ..Form::default() + }; + let mut state = AdoptState::default(); + + match name.as_str() { + // 扫描完成、还没选版本（列表里三态齐全：可导入 / 已登记 / 有问题） + "pick" => { + state.apply(AdoptEvent::Scan(Box::new(scan_view()))); + form.busy = Busy::Idle; + } + // 扫描完成、**已选中一个可导入的版本**（选中行底色 + 预检按钮启用态） + "pick-selected" => { + state.apply(AdoptEvent::Scan(Box::new(scan_view()))); + form.selected = Some("1.20.1".to_string()); + form.busy = Busy::Idle; + } + // 游戏根下真没有版本（空态） + "empty" => { + state.apply(AdoptEvent::Scan(Box::new(AdoptScanView { + versions_dir: PathBuf::from(VERSIONS_DIR), + candidates: Vec::new(), + }))); + form.busy = Busy::Idle; + } + // 选中缺省档（InstanceDir）并点过预检 + "preview" => { + state.apply(AdoptEvent::Scan(Box::new(scan_view()))); + state.apply(AdoptEvent::Planned(Box::new(plan_view( + AdoptTargetView::InstanceDir, + AdoptIsolationView::Custom, + INSTANCE_RUN_DIR, + )))); + form.selected = Some("1.20.1".to_string()); + form.checked = true; + form.busy = Busy::Idle; + } + // 选中共享档（Shared）：后果原文由 core `target_notes()` 现算 + "shared" => { + state.apply(AdoptEvent::Scan(Box::new(scan_view()))); + state.apply(AdoptEvent::Planned(Box::new(plan_view( + AdoptTargetView::Shared, + AdoptIsolationView::Shared, + GAME_ROOT, + )))); + form.selected = Some("1.20.1".to_string()); + form.target = AdoptTargetView::Shared; + form.checked = true; + form.busy = Busy::Idle; + } + // 预检失败：两条问题逐条列出（不许折叠成一句） + "failed" => { + state.apply(AdoptEvent::Scan(Box::new(scan_view()))); + state.apply(AdoptEvent::Failed(Box::new(AdoptFailureView { + code: "adopt_not_adoptable".to_string(), + message: "版本 1.19.4 不能登记：清单不是合法 JSON".to_string(), + problems: vec![ + AdoptProblemView { + code: "manifest_invalid_json".to_string(), + message: format!( + "清单不是合法 JSON {VERSIONS_DIR}/1.19.4/1.19.4.json：expected `,` or `}}` at line 12 column 3" + ), + }, + AdoptProblemView { + code: "missing_parent".to_string(), + message: "版本 1.19.4 继承的父版本 1.19.3 不在盘上".to_string(), + }, + ], + }))); + form.selected = Some("1.19.4".to_string()); + form.checked = true; + form.busy = Busy::Idle; + } + // 登记完成 + "done" => { + state.apply(AdoptEvent::Scan(Box::new(scan_view()))); + state.apply(AdoptEvent::Done(Box::new(AdoptDoneView { + instance_id: "2f1c0a5e-7f4b-4c1d-9a2e-6b8d5c3a1f70".to_string(), + name: "Better MC".to_string(), + version_id: "1.20.1-fabric-0.15.0".to_string(), + isolation: AdoptIsolationView::Custom, + run_dir: PathBuf::from(INSTANCE_RUN_DIR), + dir_created: true, + notes: target_notes(&AdoptTarget::InstanceDir, &PathBuf::from(INSTANCE_RUN_DIR)), + }))); + form.selected = Some("1.20.1-fabric-0.15.0".to_string()); + form.checked = true; + form.busy = Busy::Idle; + } + _ => return None, + } + Some((form, state)) +} + +/// 一份扫描结果（三态齐全）。 +fn scan_view() -> AdoptScanView { + AdoptScanView { + versions_dir: PathBuf::from(VERSIONS_DIR), + candidates: vec![ + AdoptCandidateView { + version_id: "1.20.1".to_string(), + jar_present: true, + inherits: Vec::new(), + registered: Vec::new(), + problems: Vec::new(), + }, + AdoptCandidateView { + version_id: "1.20.1-fabric-0.15.0".to_string(), + jar_present: false, + inherits: vec!["1.20.1-fabric-0.15.0".to_string(), "1.20.1".to_string()], + registered: vec!["Better MC".to_string()], + problems: Vec::new(), + }, + AdoptCandidateView { + version_id: "1.19.4".to_string(), + jar_present: true, + inherits: Vec::new(), + registered: Vec::new(), + problems: vec![AdoptProblemView { + code: "manifest_invalid_json".to_string(), + message: format!( + "清单不是合法 JSON {VERSIONS_DIR}/1.19.4/1.19.4.json：expected `,` or `}}` at line 12 column 3" + ), + }], + }, + ], + } +} + +/// 一份预检结果。**`notes` 由 core 现算**（共享档/版本目录档的后果原文只有一处）。 +fn plan_view( + target: AdoptTargetView, + isolation: AdoptIsolationView, + run_dir: &str, +) -> AdoptPlanView { + let core_target = match target { + AdoptTargetView::InstanceDir => AdoptTarget::InstanceDir, + AdoptTargetView::Shared => AdoptTarget::Shared, + AdoptTargetView::VersionDir => AdoptTarget::VersionDir, + }; + AdoptPlanView { + version_id: "1.20.1".to_string(), + name: "1.20.1".to_string(), + target, + isolation, + run_dir: PathBuf::from(run_dir), + notes: target_notes(&core_target, &PathBuf::from(run_dir)), + } +} diff --git a/crates/app-iced/src/app/adopt/tests.rs b/crates/app-iced/src/app/adopt/tests.rs new file mode 100644 index 0000000..2697f6f --- /dev/null +++ b/crates/app-iced/src/app/adopt/tests.rs @@ -0,0 +1,287 @@ +//! `app::adopt` 的用态用例（M223）：表单态 + 四段投影。 +//! +//! 抓得住： +//! - `Form` 的生命周期（open 清上一轮 / close 全清 / settled 解除等待）； +//! - `candidate()` 在选中项不在列表里时返回 `None`（界面自动退回「请选择」）； +//! - 四段的文案真源（标题/后果原文/问题逐条）能从 `AdoptState` 投影出来。 +//! +//! 抓不住：**像素**（那是 D30 的截图通道）；也不抓 core 的判据（那是 `host/adopt/tests.rs`）。 + +use unlucky_i18n::{Key, Lang}; +use unlucky_presenter::dto::{ + AdoptCandidateView, AdoptDoneView, AdoptEvent, AdoptFailureView, AdoptIsolationView, + AdoptPlanView, AdoptProblemView, AdoptScanView, AdoptStage, AdoptState, AdoptTargetView, +}; + +use super::*; + +fn candidate(version_id: &str, problems: Vec) -> AdoptCandidateView { + AdoptCandidateView { + version_id: version_id.to_string(), + jar_present: true, + inherits: Vec::new(), + registered: Vec::new(), + problems, + } +} + +fn state_with_scan() -> AdoptState { + let mut state = AdoptState::default(); + state.apply(AdoptEvent::Scan(Box::new(AdoptScanView { + versions_dir: std::path::PathBuf::from("/game/versions"), + candidates: vec![candidate("1.20.1", Vec::new())], + }))); + state +} + +/// 打开 ⇒ 关闭：上一轮的选中与名字都要清掉（否则下次打开画的是上一次的草稿）。 +#[test] +fn open_and_close_reset_the_form() { + let mut form = Form::default(); + form.open(); + assert!(form.open); + assert_eq!(form.busy, Busy::Scanning); + assert_eq!(form.target, AdoptTargetView::InstanceDir); + + form.selected = Some("1.20.1".to_string()); + form.name = "生存".to_string(); + form.close(); + assert!(!form.open); + assert!(form.selected.is_none()); + assert!(form.name.is_empty()); + + // 再开一次也不该带着上一轮的选中项 + form.open(); + assert!(form.selected.is_none()); +} + +/// `settled` 只解除等待，不动用户填的东西（回程不该清表单）。 +#[test] +fn settling_keeps_what_the_user_typed() { + let mut form = Form::default(); + form.open(); + form.selected = Some("1.20.1".to_string()); + form.name = "生存".to_string(); + form.settled(); + assert_eq!(form.busy, Busy::Idle); + assert_eq!(form.selected.as_deref(), Some("1.20.1")); + assert_eq!(form.name, "生存"); +} + +/// 选中项不在候选列表里 ⇒ `candidate()` 是 `None`（界面不能对着一个不存在的版本画「预检」）。 +#[test] +fn candidate_is_none_when_the_selection_vanished() { + let state = state_with_scan(); + let mut form = Form { + selected: Some("1.20.1".to_string()), + ..Form::default() + }; + assert!(form.candidate(&state).is_some()); + form.selected = Some("9.9.9".to_string()); + assert!(form.candidate(&state).is_none()); +} + +/// 四段的标题与后果原文都从目录来（不写死英文字面量、不重写 core 的后果句）。 +#[test] +fn the_four_stages_project_from_the_event_state() { + let catalog = Lang::ZhCn.catalog(); + let mut state = state_with_scan(); + + // Pick + assert_eq!(state.stage(), AdoptStage::Pick); + assert_eq!( + shell::title_text(state.stage(), catalog), + catalog.text(Key::AdoptTitle), + "标题走目录" + ); + assert!(shell::subtitle(state.stage(), &state, catalog).contains("不复制")); + + // Preview：`notes` 是 core `target_notes()` 的原文，界面一个字都不许改 + let note = + "运行目录 = /game（共享档）：mods/saves/config 会落在别人的 .minecraft 里".to_string(); + state.apply(AdoptEvent::Planned(Box::new(AdoptPlanView { + version_id: "1.20.1".to_string(), + name: "1.20.1".to_string(), + target: AdoptTargetView::Shared, + isolation: AdoptIsolationView::Shared, + run_dir: std::path::PathBuf::from("/game"), + notes: vec![note.clone()], + }))); + assert_eq!(state.stage(), AdoptStage::Preview); + assert_eq!( + state.plan.as_ref().map(|plan| plan.notes.first().cloned()), + Some(Some(note.clone())), + "后果原文必须原样留着" + ); + + // Failed：problems 逐条（不折叠） + state.apply(AdoptEvent::Failed(Box::new(AdoptFailureView { + code: "adopt_not_adoptable".to_string(), + message: "版本 1.19.4 不能登记".to_string(), + problems: vec![ + AdoptProblemView { + code: "manifest_missing".to_string(), + message: "没有清单".to_string(), + }, + AdoptProblemView { + code: "missing_parent".to_string(), + message: "缺父版本 1.20.1".to_string(), + }, + ], + }))); + assert_eq!(state.stage(), AdoptStage::Failed); + assert_eq!( + state.failure.as_ref().map(|f| f.problems.len()), + Some(2), + "两条问题一条都不许吞" + ); + assert_eq!( + shell::title_text(state.stage(), catalog), + catalog.text(Key::AdoptFailureTitle) + ); + + // Done + state.apply(AdoptEvent::Done(Box::new(AdoptDoneView { + instance_id: "id-1".to_string(), + name: "1.20.1".to_string(), + version_id: "1.20.1".to_string(), + isolation: AdoptIsolationView::Shared, + run_dir: std::path::PathBuf::from("/game"), + dir_created: false, + notes: vec![note], + }))); + assert_eq!(state.stage(), AdoptStage::Done); + assert_eq!( + shell::title_text(state.stage(), catalog), + catalog.text(Key::AdoptDoneTitle) + ); +} + +/// 中英两套目录的向导文案都不是占位（`text()` 回落到 key 名就是这个用例要抓的假绿）。 +#[test] +fn both_catalogs_have_the_wizard_wording() { + for lang in [Lang::En, Lang::ZhCn] { + let catalog = lang.catalog(); + for key in [ + Key::AdoptTitle, + Key::AdoptSubtitle, + Key::AdoptScanning, + Key::AdoptEmpty, + Key::AdoptSelectLabel, + Key::AdoptReady, + Key::AdoptTargetLabel, + Key::AdoptTargetInstanceDir, + Key::AdoptTargetShared, + Key::AdoptTargetVersionDir, + Key::AdoptNameLabel, + Key::AdoptPreview, + Key::AdoptConfirm, + Key::AdoptBack, + Key::AdoptClose, + Key::AdoptPlanTitle, + Key::AdoptPlanRunDir, + Key::AdoptPlanIsolation, + Key::AdoptFailureTitle, + Key::AdoptProblemCount, + Key::AdoptDoneTitle, + Key::AdoptDoneHint, + ] { + let value = catalog.text(key); + assert!(!value.is_empty(), "{key:?} 在 {lang:?} 是空的"); + assert_ne!( + value, + format!("{key:?}"), + "{key:?} 在 {lang:?} 没进目录（回落成了 key 名）" + ); + } + } + // 共享档的短提示必须把「会写进别人的 .minecraft」说清楚（选之前就得知道） + let hint = Lang::En.catalog().text(Key::AdoptTargetSharedHint); + assert!(hint.contains(".minecraft"), "{hint}"); +} + +/// 「点选共享档 ⇒ 立刻看到后果原文」但**不**把用户甩到确认页： +/// 预检结果到了也只是 Pick 段里的提示，直到用户点过「预检」(`checked`) 才进 Preview。 +/// +/// 抓得住：把 `Form::stage` 写回直接取 `AdoptState::stage()`（点一次共享档就跳到确认页， +/// 实例名还没来得及改）；或忘了 `fresh_plan` 的目标一致性判据（改档之后画上一档的后果原文）。 +#[test] +fn a_foreign_target_shows_its_notes_without_jumping_to_confirm() { + let mut state = state_with_scan(); + let note = + "运行目录 = /game（共享档）：mods/saves/config 会落在别人的 .minecraft 里".to_string(); + state.apply(AdoptEvent::Planned(Box::new(AdoptPlanView { + version_id: "1.20.1".to_string(), + name: "1.20.1".to_string(), + target: AdoptTargetView::Shared, + isolation: AdoptIsolationView::Shared, + run_dir: std::path::PathBuf::from("/game"), + notes: vec![note.clone()], + }))); + + let mut form = Form { + open: true, + selected: Some("1.20.1".to_string()), + target: AdoptTargetView::Shared, + ..Form::default() + }; + + // 自动预检回来但用户没点「预检」：仍是 Pick 段，notes 当作提示可读 + assert_eq!(form.stage(&state), AdoptStage::Pick); + assert_eq!( + form.fresh_plan(&state) + .map(|plan| plan.notes.first().cloned()), + Some(Some(note.clone())), + "后果原文必须能取到" + ); + + // 点过「预检」之后才进确认段 + form.checked = true; + assert_eq!(form.stage(&state), AdoptStage::Preview); + + // 换了目标档：上一档的预检作废（不再当后果原文画） + form.target = AdoptTargetView::VersionDir; + assert!(form.fresh_plan(&state).is_none(), "过期的预检不许画"); +} + +/// **P2-2**：`fresh_plan` 必须按**版本 id** 过期，不只是目标档。 +/// +/// 场景：先选 1.20.1 + 版本目录档（notes 说 `versions/1.20.1`），再改选 1.19.4——目标档没变， +/// 旧的预检结果若不按版本过滤就会继续当「这个版本的后果原文」画出来，那是一句假话。 +/// +/// 抓得住：`fresh_plan` 只看 `plan.target == self.target`（第一次修法就是这样漏的）。 +/// 抓不住：core 真的会不会为 1.19.4 算出同一段 notes（那是 `target_notes()` 的活）。 +#[test] +fn fresh_plan_expires_when_the_selected_version_changes() { + let mut state = state_with_scan(); + state.apply(AdoptEvent::Planned(Box::new(AdoptPlanView { + version_id: "1.20.1".to_string(), + name: "1.20.1".to_string(), + target: AdoptTargetView::VersionDir, + isolation: AdoptIsolationView::Isolated, + run_dir: std::path::PathBuf::from("/game/versions/1.20.1"), + notes: vec!["运行目录 = 版本目录 /game/versions/1.20.1".to_string()], + }))); + + let mut form = Form { + open: true, + selected: Some("1.20.1".to_string()), + target: AdoptTargetView::VersionDir, + checked: true, + ..Form::default() + }; + assert!( + form.fresh_plan(&state).is_some(), + "对得上版本与目标档时应当可读" + ); + + // 改选另一个版本：目标档没变，但旧预检说的是别的版本的目录 + form.selected = Some("1.19.4".to_string()); + assert!( + form.fresh_plan(&state).is_none(), + "换了版本之后旧预检必须过期（否则画的是 1.20.1 的后果原文）" + ); + // 没选版本时同样不该画（`None` = 没有任何版本的预检可言） + form.selected = None; + assert!(form.fresh_plan(&state).is_none()); +} diff --git a/crates/app-iced/src/app/adopt/text.rs b/crates/app-iced/src/app/adopt/text.rs new file mode 100644 index 0000000..04e6e23 --- /dev/null +++ b/crates/app-iced/src/app/adopt/text.rs @@ -0,0 +1,88 @@ +//! 向导里的小工具：等宽行、可换行正文、标签、问题行、档位人话。 +//! +//! 单独一个文件只为守 400 行硬线（AGENTS §3.1）：三段视图（`pick` / `panes`）与卡壳 +//! （`adopt.rs`）都要用它们，放哪儿都会让那一处越线。 + +use iced::widget::text::LineHeight; +use iced::widget::{column, text}; +use iced::{Color, Element, Font, Length, Pixels}; + +use unlucky_design::color::Role; +use unlucky_design::typography::TypeRole; +use unlucky_i18n::{Catalog, Key}; +use unlucky_presenter::dto::{AdoptIsolationView, AdoptProblemView, AdoptTargetView}; + +use crate::pages::frame; +use crate::theme::Ui; + +use super::super::message::Message; + +/// 段内的次级标签（`LabelMedium` + `OnSurfaceVariant`）。 +pub(super) fn label<'a>(ui: &'a Ui, value: &'a str) -> Element<'a, Message> { + frame::text_role( + ui, + TypeRole::LabelMedium, + false, + value, + ui.color(Role::OnSurfaceVariant), + ) + .map(Message::Page) +} + +/// 等宽一行（路径 / 机读码要能逐字读）。 +pub(super) fn mono<'a>(ui: &'a Ui, value: String) -> Element<'a, Message> { + let style = ui.style(TypeRole::BodySmall); + text(value) + .size(style.size_px) + .line_height(LineHeight::Absolute(Pixels(style.line_height_px))) + .font(Font { + family: iced::font::Family::Name(ui.families().mono), + ..Font::DEFAULT + }) + .color(ui.color(Role::OnSurface)) + .width(Length::Fill) + .wrapping(iced::widget::text::Wrapping::WordOrGlyph) + .into() +} + +/// 一段可换行的正文（长路径只按词折行会把卡顶破，所以按词或字形折）。 +pub(super) fn wrapped<'a>(ui: &'a Ui, value: String, color: Color) -> Element<'a, Message> { + frame::text_role_owned(ui, TypeRole::BodySmall, false, value, color).map(Message::Page) +} + +/// 「标签 + 值」一行（值用等宽）。 +pub(super) fn field_line<'a>(ui: &'a Ui, label_text: &'a str, value: &str) -> Element<'a, Message> { + column![label(ui, label_text), mono(ui, value.to_string())] + .spacing(0.0) + .width(Length::Fill) + .into() +} + +/// 一条问题：稳定码（等宽） + 人读原因（`Error` 色）。**一条都不许折叠**。 +pub(super) fn problem_line<'a>(ui: &'a Ui, problem: &'a AdoptProblemView) -> Element<'a, Message> { + column![ + mono(ui, problem.code.clone()), + wrapped(ui, problem.message.clone(), ui.color(Role::Error)), + ] + .spacing(0.0) + .width(Length::Fill) + .into() +} + +/// 隔离档的人话（沿用实例页已有的两条；`custom` 就是缺省档，直接说「在 ULL 数据区新建」）。 +pub(super) fn isolation_label(isolation: AdoptIsolationView, catalog: Catalog) -> String { + match isolation { + AdoptIsolationView::Isolated => catalog.text(Key::InstancesIsolationIsolated).to_string(), + AdoptIsolationView::Shared => catalog.text(Key::InstancesIsolationShared).to_string(), + AdoptIsolationView::Custom => catalog.text(Key::AdoptTargetInstanceDir).to_string(), + } +} + +/// 目标档的短标签。 +pub(super) fn target_label(target: AdoptTargetView, catalog: Catalog) -> &'static str { + match target { + AdoptTargetView::InstanceDir => catalog.text(Key::AdoptTargetInstanceDir), + AdoptTargetView::Shared => catalog.text(Key::AdoptTargetShared), + AdoptTargetView::VersionDir => catalog.text(Key::AdoptTargetVersionDir), + } +} diff --git a/crates/app-iced/src/app/appearance.rs b/crates/app-iced/src/app/appearance.rs new file mode 100644 index 0000000..a03ece3 --- /dev/null +++ b/crates/app-iced/src/app/appearance.rs @@ -0,0 +1,133 @@ +//! App 侧的外观动作：**下发整窗 α / 写回配置 / 打取证日志**。 +//! +//! 三件事各自只有一条路，且都从这里出去（`update` 只负责把它们按消息串起来）： +//! +//! | 动作 | 唯一落点 | 为什么 | +//! |---|---|---| +//! | 下发整窗 α | [`App::apply_window_alpha`] → `app::window_alpha::dispatch` | 判据在 `platform`、FFI 在 `platform/win32`，这里只做「取 α → 交给执行侧 → 记日志」 | +//! | 写回配置 | [`App::persist_appearance`]（8 个 UI 字段）+ `AppCommand::SetSetting`（另外**三个**只读键） | 每个键**只有一个写者**：`AppearancePrefs` 里没有 `window_opacity` / `palette_source` / `window_corner`，它们只能走 schema 指令 | +//! | 取证日志 | [`App::log_appearance`] | 一行里同时有请求值、生效值、下发字节与 FFI 结局 | +//! +//! ## 为什么「写回」要分两条路 +//! +//! `SettingsBridge::persist` 收的是 `AppearancePrefs`（背景图四件 + 面板 α + 玻璃 + 强调色）， +//! 它的实现是「先读文件当前值，再覆盖我们改的那几个字段」——所以用它写**它覆盖的键**最省事， +//! 也不会把用户的自定义强调色冲掉。而 `appearance.window_opacity` / `appearance.palette_source` / +//! `appearance.window_corner` 不在那个结构里（它们是「只读下层键」，见 +//! `presenter::prefs::AppearanceBase` 的**四个**字段：整窗 α / 标题栏三态 / 配色来源 / 窗口圆角）， +//! 写它们只能走 schema 白名单指令 `AppCommand::SetSetting`（真 host 用 `SettingStore::set` 落盘）。 +//! 其中「标题栏三态」目前**没有 UI 写者**（D37 的接线未落地），所以走 `SetSetting` 的是**三个**键。 + +use crate::app::diag::diag; +use unlucky_presenter::dto::AppCommand; + +use crate::pages::appearance::Change; + +use super::state::App; +use super::window_alpha::{self, Dispatch}; + +impl App { + /// 把当前整窗 α 交给执行侧（补 `WS_EX_LAYERED` + `SetLayeredWindowAttributes`）并记一行日志。 + /// + /// 没有句柄时**也打日志**（`hwnd=none`）：不能让「α 没生效」这件事只体现为「屏幕上没变化」。 + pub(super) fn apply_window_alpha(&self, context: &str) { + let Some(hwnd) = self.hwnd else { + self.log_appearance(context, None); + return; + }; + let alpha = crate::platform::effective_window_alpha( + self.appearance.backend, + f64::from(self.appearance.window_opacity), + ); + let dispatch = window_alpha::dispatch(hwnd, alpha); + self.log_appearance(context, Some(&dispatch)); + } + + /// 取证日志：`[appearance] <状态行> layered=… outcome=…`。 + /// + /// 数值来自 [`crate::pages::appearance::State::log_line`]（请求值 / 生效值 / 下发字节）， + /// 尾巴来自执行侧。**这一行就是「透明度到底设成了多少」的证据**——RDP 上的观感不可信。 + pub(super) fn log_appearance(&self, context: &str, dispatch: Option<&Dispatch>) { + let mut line = self.appearance.log_line(context); + if let Some(dispatch) = dispatch { + line.push(' '); + line.push_str(&dispatch.describe()); + } else { + line.push_str(" layered=skipped outcome=no-window"); + } + diag!("{line}"); + } + + /// 设置页改了一项外观。 + pub(super) fn on_appearance(&mut self, change: Change) { + let needs_window = self.appearance.apply(change.clone()); + + // 配色来源 / 背景图可能变了 ⇒ `Ui` 可能要改用解析出的方案。 + self.rebuild_ui(); + self.view_dirty = true; + self.refresh_view(); + + match change.key() { + // 三个只读下层键（整窗 α / 配色来源 / 窗口圆角）：走 schema 指令 + // （`SettingsBridge` 的结构里没有它们；标题栏三态还没有 UI 写者，不在此列）。 + Some(_) + if matches!( + change, + Change::WindowOpacity(_) | Change::PaletteSource(_) | Change::Corner(_) + ) => + { + if let (Some(key), Some(value)) = (change.key(), change.value()) { + self.dispatch(AppCommand::SetSetting { + key: key.to_owned(), + value, + }); + } + } + // 其余键：走 bridge（M250 起强调色也在这条路上，取的是上一次合法值）。 + Some(_) => self.persist_appearance(), + None => {} + } + + if needs_window { + self.apply_window_alpha("change"); + } else { + self.log_appearance("change", None); + } + // M116：圆角档位变了要**重新判定 + 重新下发**（与整窗 α 是两条独立的管线）。 + self.apply_window_corner("change"); + } + + /// 重读配置后同步外观（热切：外部 CLI / AI 改完 1 秒内生效）。 + pub(super) fn reload_appearance(&mut self) { + let (prefs, _theme) = self.bridge.load(); + let base = self.bridge.load_base(); + self.appearance.reload(&prefs, &base); + self.appearance_prefs = prefs; + self.rebuild_ui(); + self.view_dirty = true; + self.apply_window_alpha("reload"); + // M116：外部（CLI / AI）改了 `appearance.window_corner` 也要热生效。 + self.apply_window_corner("reload"); + } + + /// 把外观写回 `launcher.json`（本页控件管的那批字段 + 强调色；其余键原样保留）。 + fn persist_appearance(&mut self) { + let mut prefs = self.appearance_prefs.clone(); + prefs.bg_image_enabled = self.appearance.bg_enabled; + prefs.bg_image = self.appearance.bg_path.clone(); + prefs.bg_fill = self.appearance.bg_fill; + prefs.bg_dim = self.appearance.bg_dim; + prefs.panel_alpha = self.appearance.panel_alpha; + prefs.glass = self.appearance.glass; + // M250：强调色也是「UI 写入字段」了——取**上一次合法值**（非法手输不写盘，见 `accent::Accent`）。 + prefs.accent_color = self.appearance.accent.persist_value().to_owned(); + + self.bridge.persist(&prefs, self.theme_mode); + self.appearance_prefs = prefs; + + match self.bridge.path() { + Some(path) => diag!("[settings] 外观已写回 {}", path.display()), + None => diag!("[settings] 外观未落盘（数据根解析不出来，内存态运行）"), + } + } +} 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 { + 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 { + 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..82f8362 --- /dev/null +++ b/crates/app-iced/src/app/boot.rs @@ -0,0 +1,263 @@ +//! 启动编排：**探测 → 字体 → 打印诊断 → 起 iced**（四步，别把它撑回一坨）。 +//! +//! ## 三条纪律（每条都对应一次返工） +//! +//! 1. **后端起不来时的两条路策略不同**（判据表第 8/9 行）：交互启动换进程重开、取证启动 +//! （`--screenshot`）拒绝出图 —— 实现与测试都在 [`fallback`]。 +//! 2. **窗口设置只有一个产地**（[`diagnostics::window_settings`]），`[window]` / `[caps]` 两行日志 +//! 从**同一个** `&window::Settings` 取字段。M98 r1 p2-1 的教训：把 `decorations=false` 写进 +//! 格式化串，等于让日志与真实行为可以各走各的（踩坑记录 U1）。 +//! 3. **没测过的就写 `skipped`**，不许拿 `0ms` 冒充实测（[`diagnostics::report_font`] 的 `probe`）。 +//! +//! 为什么重开必须是**换进程**：Windows 实测本进程里再 `run()` 一次直接 panic +//! （`iced_winit-0.14.1/src/lib.rs:81` → `Create event loop: RecreationAttempt`）。 + +use crate::app::diag::diag; +use std::time::{Duration, Instant}; + +use iced::Task; + +use unlucky_design::color::SchemeFlavor; + +use crate::cli::Options; +use crate::fonts; +use crate::probe; +use crate::renderer::{self, acceptance, Decision}; +use crate::theme::Families; + +use super::message::Message; +use super::state::{App, STARTED}; +use super::{MIN_SIZE, WINDOW_SIZE}; + +mod diagnostics; +mod fallback; +mod termux_gpu; +mod termux_window; + +use fallback::{on_failure, respawn, OnFailure}; + +/// 启动 iced（阻塞到退出）。`--diff` 不走这里，见 `main.rs`。 +pub(crate) fn run(options: Options) -> iced::Result { + let _ = STARTED.set(Instant::now()); + let boot_started = Instant::now(); + + // ① 探测（判据取在哪、日志在 `report_boot` 里统一打） + // Termux + glibc 构建：装了我们自编的 turnip ICD 就先生效，auto 也能选到 GPU。 + termux_gpu::enable(); + let boot = boot_probe(&options); + let decision = boot.decision; + diagnostics::report_boot(&options, &boot.probe, &decision); + + // ② 字体（`fonts` 自己打两行既有日志；新加的那行在 `report_font` 里） + let font_started = Instant::now(); + let resolved = fonts::resolve(); + let font_ms = font_started.elapsed(); + diag!("[font] 求值耗时 {:.0} ms", font_ms.as_secs_f64() * 1000.0); + diag!("{}", resolved.describe()); + if resolved.has_synthetic() { + diag!( + "[font] 警告：有字重落在「合成加粗」档（观感降级），D28 后半（CDN 字体/按档换字族）要处理" + ); + } + let families = resolved.families(); + + // ③ 打印（主题来源 + 字体回退链 + 启动耗时） + // 截图模式：`--screenshot-theme` > `--theme` > **Light**（唯一取值口 `Options::capture_flavor`）。 + // **不再有**「等系统主题到达」的闸门——CI 的 xvfb 没有主题会话，等它就是挂死（见 cli 文档）。 + if options.screenshot.is_some() && options.shot_flavor().is_none() { + diag!("[shot] 未指定主题，按 Light 出图（D30 可复现；CI 冒烟依赖这条默认值）"); + } + let flavor = options.capture_flavor().unwrap_or(SchemeFlavor::Light); + diagnostics::report_theme(&options, flavor); + diagnostics::report_font( + resolved.platform, + boot.probe_ms, + font_ms, + boot_started.elapsed(), + ); + + // ④ 起 iced（失败按判据表第 8/9 行分流；具名原因在分流之前就打到同一个 stderr 上了） + let launch_started = Instant::now(); + let result = match launch(&options, families, flavor, decision.primary) { + Err(iced::Error::GraphicsCreationFailed(error)) => { + renderer::report_failure(decision.primary, &error); + match on_failure(decision, options.screenshot.as_ref()) { + Some(OnFailure::Respawn(fallback)) => { + respawn(decision.primary, fallback, &error.to_string()) + } + Some(OnFailure::Refuse) => { + // 取证启动：**拒绝降级出图**（换了后端出的图会让报告撒谎）。 + diag!( + "[gpu] 拒绝降级出图：本次是取证启动（--screenshot {}），换后端出的图会撒谎。", + options + .screenshot + .as_ref() + .map_or_else(String::new, |path| path.display().to_string()) + ); + diag!( + "[gpu] 想用 CPU 出图请显式加 --renderer=cpu / --software-renderer（CI 就是这么跑的）。" + ); + Err(iced::Error::GraphicsCreationFailed(error)) + } + None => Err(iced::Error::GraphicsCreationFailed(error)), + } + } + other => other, + }; + let launch_elapsed = launch_started.elapsed(); + + diagnostics::report_outcome( + &decision, + result.as_ref().err().map(|error| { + renderer::named_graphics_error(error).unwrap_or_else(|| error.to_string()) + }), + acceptance::failure_via(decision.fallback.is_some(), options.screenshot.is_some()), + if options.screenshot.is_some() { + "screenshot" + } else { + "interactive" + }, + launch_elapsed, + ); + + result +} + +/// 按一次后端启动 iced。`backend` 决定这次写进 `ICED_BACKEND` 的唯一一项。 +fn launch( + options: &Options, + families: Families, + flavor: SchemeFlavor, + backend: renderer::Kind, +) -> iced::Result { + std::env::set_var("ICED_BACKEND", backend.env_value()); + + let boot_options = options.clone(); + + // M98：`ULL_WINDOW_SIZE=1520x900` 覆盖尺寸（矩阵的「最小 / 宽屏」两档靠它，且必须走**真外壳** + // ——`pages_demo` example 的标题栏是留白带，出不了「三键位置」那张图）。 + // Termux：没有环境覆盖时，默认尺寸按 X 屏幕等比自适应（横屏优先）， + // 失败就退回 1180×760 的验收尺寸。 + let (default_size, default_source) = termux_window::default_size( + (WINDOW_SIZE.width, WINDOW_SIZE.height), + (MIN_SIZE.width, MIN_SIZE.height), + ) + .unwrap_or(((WINDOW_SIZE.width, WINDOW_SIZE.height), "default")); + let (size, size_source) = + acceptance::window_size(default_size, (MIN_SIZE.width, MIN_SIZE.height)); + let size_source = if size_source == "default" { + default_source + } else { + size_source + }; + let settings = diagnostics::window_settings(size); + // 两行日志与开窗用的是**同一个** settings（见模块文档纪律 2） + diagnostics::report_window(&settings, options.scale_factor, size_source); + + let application = iced::application( + move || { + ( + App::new(boot_options.clone(), families, flavor), + Task::done(Message::Boot), + ) + }, + App::update, + App::view, + ) + .title(App::title) + .theme(App::theme) + .subscription(App::subscription) + .default_font(default_font(families)) + .window(settings); + + match options.scale_factor { + Some(scale) => application.scale_factor(move |_| scale).run(), + None => application.run(), + } +} + +/// [`boot_probe`] 的产物：判据 + 探测到的适配器 + **探测耗时（没测就是 `None`）**。 +/// +/// 为什么把 `Probe` 带出来：`[env]` 的 `gpu=` / `hardware=` 必须是**这一次真枚举到的**结果 +/// （再枚举一遍多花 0.65~1.2 s，还可能给出不同状态）。判据与诊断看同一份数据。 +struct Boot { + decision: Decision, + probe: probe::Probe, + probe_ms: Option, +} + +/// 渲染后端探测 + 写 `ICED_BACKEND`，返回判据产物（供 `run` 决定要不要换进程重开）。 +fn boot_probe(options: &Options) -> Boot { + // 「上一步失败后重开」的那一次：别再探（会得到同一个结论，然后无限重开）。兜底必须是 None + // ——由 `decision::fallback_round` 单点保证。 + if let Some(kind) = renderer::forced_fallback() { + let decision = renderer::fallback_round(kind); + std::env::set_var("ICED_BACKEND", kind.env_value()); + diag!( + "[probe] 本次是降级重开（{}={}）：跳过探测 -> ICED_BACKEND={}", + renderer::FALLBACK_ENV, + kind.env_value(), + kind.env_value() + ); + diag!("[probe] {}", decision.describe()); + // 验收要 `[env]` 里的真实适配器：这一轮**也枚举一次，并如实计时**（没计时就 `None` + // ⇒ 日志写 `probe=skipped`，不写 0ms）。 + let (probe, probe_ms) = if acceptance::enabled() { + let started = Instant::now(); + let probe = probe::Probe::run(); + (probe, Some(started.elapsed())) + } else { + (probe::Probe::default(), None) + }; + return Boot { + decision, + probe, + probe_ms, + }; + } + + // 只有 `auto` 需要探测（`cpu`/`gpu` 的决策与硬件无关，枚举 13 个适配器本机要 0.65~1.2 s）。 + // 验收模式例外：`[env]` 那行要 GPU 名，不管请求是哪个后端。 + let needs_probe = options.backend == crate::Backend::Auto || acceptance::enabled(); + let probe_started = Instant::now(); + let probe = if needs_probe { + probe::Probe::run() + } else { + probe::Probe::default() + }; + let probe_ms = needs_probe.then(|| probe_started.elapsed()); + + // `ULL_PREFLIGHT=1` 时先自己验一遍 wgpu（判据表第 7 行）；默认不跑，见 preflight 模块文档。 + let preflight = renderer::preflight::run_if_requested(); + let decision = probe::apply_with_preflight(options.backend, &probe, preflight.as_ref()); + + if cfg!(feature = "gpu") { + match probe_ms { + Some(elapsed) => diag!( + "[probe] 探测耗时 {:.0} ms（wgpu 实例 + 全后端适配器枚举）", + elapsed.as_secs_f64() * 1000.0 + ), + None => diag!( + "[probe] 探测耗时 跳过（--renderer={} 与硬件无关，未枚举）", + options.backend.name() + ), + } + } + Boot { + decision, + probe, + probe_ms, + } +} + +/// 默认字体（正文档解析出来的族）。 +fn default_font(families: Families) -> iced::Font { + iced::Font { + family: iced::font::Family::Name(families.text), + ..iced::Font::DEFAULT + } +} + +#[cfg(test)] +#[path = "boot/tests.rs"] +mod tests; 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..aeba49c --- /dev/null +++ b/crates/app-iced/src/app/boot/diagnostics.rs @@ -0,0 +1,115 @@ +//! 启动阶段的**验收诊断编排**：把 `app/boot.rs` 的 `run()` 收成「探测 → 字体 → 打印 → 起 iced」。 +//! +//! ## 为什么单独一个文件（M98 r1 p2-1 的根因） +//! +//! 第一版把 `[window] requested … resizable=true decorations=false transparent=false` 直接写在 +//! 格式化串里，而 `boot.rs` 给窗口的 `settings` 是另一处常量 —— 两者**没有任何绑定**。定向变异 +//! 把 `settings.decorations` 改成 `true`，371 个测试全绿，而验收包里 `[caps] decorations=true` 与 +//! `[window] decorations=false` 会互相矛盾（踩坑记录 U1：常量冒充观测结果）。 +//! +//! 现在：窗口设置由 [`window_settings`] **一处**产生，日志由 [`report_window`] 从**同一个 +//! `&window::Settings`** 取字段。钉死它的守门测试在 `boot/tests.rs`（`window_settings_*`）。 +//! +//! 另一件事：所有「跑没跑」都要能如实说。降级重开那一轮没计时就写 `probe=skipped`， +//! 不许拿 `0ms` 冒充一次实测（M98 r1 p3-1）。 + +use std::time::Duration; + +use iced::window; + +use unlucky_design::color::SchemeFlavor; +use unlucky_design::typography::Platform as FontPlatform; + +use crate::cli::Options; +use crate::probe::Probe; +use crate::renderer::{acceptance, Decision}; + +use super::MIN_SIZE; +use crate::app::APP_TITLE; + +/// 产品窗口设置（**唯一产地**：`launch()` 用它开窗，`[window]` / `[caps]` 从它取字段）。 +/// +/// `ULL_WINDOW_SIZE` 的覆盖在 `boot.rs` 解析成 `size` 后从这里进来 —— 日志与真窗口永远同源。 +pub(super) fn window_settings(size: (f32, f32)) -> window::Settings { + window::Settings { + size: iced::Size::new(size.0, size.1), + min_size: Some(MIN_SIZE), + // 自绘三键（M93）：窗口**不许**带系统装饰，否则 macOS 上会出现原生标题栏 + 自绘三键两套。 + // + // M182：这一行**同时**是「macOS 四角是直角」的原因——winit 见到 `decorations: false` + // 会给出 `NSWindowStyleMask::Borderless`（没有 `Titled`），而窗口服务器只给 titled 窗 + // 做圆角裁剪。链条与「要不要迁移原生标题栏」的口径写在 `platform::macos` 的模块文档里， + // 改动这一行之前先读那一页（迁移必须连同撤掉自绘三键一起做，否则两套控件打架）。 + decorations: false, + resizable: true, + // M93 / D36：整窗 α 需要 `WS_EX_LAYERED`，但这里给不了——`window::Settings` 没有扩展样式 + // 字段，写它只有 `Get/SetWindowLongPtrW`（`unsafe`，全仓只允许出现在 + // `platform/win32/transparency.rs`）。所以 α 下发在拿到句柄之后（`Message::WindowHandle`）。 + transparent: false, + ..window::Settings::default() + } +} + +/// `[window] requested` + `[caps]` 两行，**都从同一个 `settings` 取**（不给手抄字面量的机会）。 +pub(super) fn report_window(settings: &window::Settings, scale: Option, 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, + 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, + 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..2c3fe06 --- /dev/null +++ b/crates/app-iced/src/app/boot/fallback.rs @@ -0,0 +1,121 @@ +//! 起步后端失败后的**兜底/重开**一簇：判据、进程环境交接、`respawn`、退出码透传。 +//! +//! 从 `app/boot.rs` 拆出来的理由：这一簇**与启动编排零耦合**，但已有 5 条测试，而且它是 +//! M97 判据表第 8/9 行的落点。`boot.rs` 那边只负责「什么时候调它」。 +//! +//! ## 为什么必须换进程（别改回进程内重试） +//! +//! Windows 实测本进程里再 `run()` 一次直接 panic +//! （`iced_winit-0.14.1/src/lib.rs:81` → `Create event loop: RecreationAttempt`），winit 一个进程 +//! 只能建一次事件循环。 + +use crate::app::diag::diag; +use crate::renderer::Decision; +use crate::renderer::{self, acceptance, Kind}; + +/// 起步后端失败后的去向（判据表第 8 行 vs 第 9 行——**两条路策略不同，别合成一条**）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(super) enum OnFailure { + /// 交互启动：安全网优先，换进程用这个后端重开。 + Respawn(Kind), + /// 取证启动：红着退出，**不出图**。 + Refuse, +} + +/// 纯判据：起步后端失败时走哪条路。 +/// +/// `evidence` 非空 = 本次是取证启动（带 `--screenshot`）；返回 `None` = 没有兜底可用 +/// （`--renderer=cpu` / 未编 wgpu），原样把错误交回去。抽成纯函数只为一个理由：这条分支以前 +/// **没有任何测试**，`respawn` / `Refuse` 两条路可以被静默改反（M97 r1 p2-1 就是这么测出来的）。 +pub(super) fn on_failure( + decision: Decision, + evidence: Option<&std::path::PathBuf>, +) -> Option { + let fallback = decision.fallback?; + Some(match evidence { + Some(_) => OnFailure::Refuse, + None => OnFailure::Respawn(fallback), + }) +} + +/// 降级重开要传给子进程的环境变量（**两条缺一不可**）。 +/// +/// ① `ICED_BACKEND`：让子进程直接用 `fallback` 跑。 +/// ② [`renderer::FALLBACK_ENV`]：**防无限重开的闸门**——子进程见它就必须跳过探测 +/// （`boot_probe` 的第一个分支），否则会算出同一个结论、再失败、再 respawn。 +/// +/// 抽成纯函数是为了让「漏传其中之一」变成**测试能抓到**的错误：两条都是静默失效型 +/// （漏 ① 重开又跑一遍 wgpu、漏 ② 无限重开），线上极难看出来。 +pub(super) fn fallback_env(fallback: Kind) -> [(&'static str, &'static str); 2] { + [ + ("ICED_BACKEND", fallback.env_value()), + (renderer::FALLBACK_ENV, fallback.env_value()), + ] +} + +/// 安全网：起一个**新进程**用 `fallback` 后端重开，然后带着它的退出码退出。 +/// +/// 只在**交互启动**时走到这里（取证启动宁可红着退出也不换后端出图）；子进程看到 +/// [`renderer::FALLBACK_ENV`] 必须跳过探测，否则无限递归重开（闸门在 `boot_probe` 入口）。 +pub(super) fn respawn(failed: Kind, fallback: Kind, error: &str) -> ! { + let exe = std::env::current_exe().unwrap_or_else(|err| { + diag!("[gpu] 降级重开失败：拿不到自身路径（{err}）"); + std::process::exit(exit_code(None)); + }); + diag!( + "[gpu] 降级 → {}（{} 已失败，原因见上两行；换一个进程重开：winit 不允许同进程建两次事件循环）。\ + 下一次的日志从 `[probe] 本次是降级重开` 开始。", + fallback.name(), + failed.name() + ); + // `[backend] final` 一行把「哪个后端失败了、去了哪、为什么」收在一起（可 grep 的单一结论行）。 + // 这里 `final=` 装的是**兜底**（进程即将带着它重开）；`via=respawn` 说明它是换进程去的。 + acceptance::report_backend_failed(failed, Some(fallback), Some(fallback), "respawn", error); + + let status = fallback_command(&exe, std::env::args_os().skip(1), fallback).status(); + + // 退出码**透传**子进程的：上层脚本/CI 靠它判断成败。写错的失效方式是「安静地给出一个错 + // 结论」——不崩、不静默降级、不无限重开，只是让 CI 把失败当成功。 + let code = match status { + Ok(status) => exit_code(status.code()), + Err(err) => { + diag!("[gpu] 降级重开失败：{err}"); + exit_code(None) + } + }; + std::process::exit(code) +} + +/// 子进程退出码 → 本进程退出码。 +/// +/// `None` = 子进程被信号杀死（只有 Unix）：走兜底码而**不是** panic、也不是 0——上层判据是 +/// 「非零 = 失败」，「拿不到退出码」和「退出码是某个非零值」对脚本是一回事。 +pub(super) fn exit_code(code: Option) -> i32 { + /// 重开失败 / 拿不到退出码时的兜底码（与 `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, + fallback: Kind, +) -> std::process::Command { + // 子进程就是本 GUI exe 自己（PE Subsystem=2，本来就不会分到控制台），所以这一处今天闪不了； + // 走 `quiet` 是为了让「app-iced 里除 opener 外不留裸构造」这条规则整体可被守卫钉住——将来 + // 某天把降级重开换成控制台辅助程序时，不会从这里漏出一块黑框（M217）。 + let mut command = unlucky_core::platform::child::quiet(program); + command.args(args).envs(fallback_env(fallback)); + command + .stdin(std::process::Stdio::inherit()) + .stdout(std::process::Stdio::inherit()) + .stderr(std::process::Stdio::inherit()); + command +} diff --git a/crates/app-iced/src/app/boot/termux_gpu.rs b/crates/app-iced/src/app/boot/termux_gpu.rs new file mode 100644 index 0000000..ee14b8f --- /dev/null +++ b/crates/app-iced/src/app/boot/termux_gpu.rs @@ -0,0 +1,58 @@ +//! Termux 上自动启用随附的 Vulkan ICD（glibc 侧 turnip，`ull_freedreno.json`）。 +//! +//! 背景：Termux 软件源里的 glibc Mesa（24.2.6）不认识 Adreno 840，硬件 GPU 需要用 +//! `packaging/docs/termux-glibc-build.md` §5 里自编的 Mesa 26（KGSL）。驱动装在 +//! `$PREFIX/glibc/share/vulkan/icd.d/ull_freedreno.json` 时，这里在探测之前把它设进 +//! `VK_ICD_FILENAMES` / `VK_DRIVER_FILES`，让 `auto` 也能选到 GPU。 +//! +//! 只在 **glibc 构建**（`target_os = "linux"`）上生效：Termux 原生（bionic）构建的 +//! `target_os = "android"`，glibc 驱动对它没有意义。用户显式设了这两个变量时不覆盖。 + +use std::path::{Path, PathBuf}; + +use unlucky_core::platform::paths::ProcessEnv; +use unlucky_core::platform::termux; + +/// 随附 ICD 的相对路径（相对 `$PREFIX`）。 +const ICD_REL: &str = "glibc/share/vulkan/icd.d/ull_freedreno.json"; + +/// 在 GPU 探测之前调用：装了就启用，没装就什么都不做。 +pub(super) fn enable() { + if !cfg!(target_os = "linux") { + return; + } + if std::env::var_os("VK_ICD_FILENAMES").is_some() + || std::env::var_os("VK_DRIVER_FILES").is_some() + { + return; + } + let Some(prefix) = termux::prefix(&ProcessEnv) else { + return; + }; + let icd = icd_path(&prefix); + if icd.is_file() { + std::env::set_var("VK_ICD_FILENAMES", &icd); + std::env::set_var("VK_DRIVER_FILES", &icd); + } +} + +/// `$PREFIX` 下随附 ICD 的路径（纯函数，测试用）。 +fn icd_path(prefix: &Path) -> PathBuf { + prefix.join(ICD_REL) +} + +#[cfg(test)] +mod tests { + use super::icd_path; + + #[test] + fn icd_path_is_under_the_glibc_prefix() { + let path = icd_path(std::path::Path::new("/data/data/com.termux/files/usr")); + assert_eq!( + path, + std::path::PathBuf::from( + "/data/data/com.termux/files/usr/glibc/share/vulkan/icd.d/ull_freedreno.json" + ) + ); + } +} diff --git a/crates/app-iced/src/app/boot/termux_window.rs b/crates/app-iced/src/app/boot/termux_window.rs new file mode 100644 index 0000000..079841f --- /dev/null +++ b/crates/app-iced/src/app/boot/termux_window.rs @@ -0,0 +1,117 @@ +//! Termux / termux-x11 下的窗口尺寸自适应（横屏优先）。 +//! +//! 验收尺寸（1180×760）是 D30 的硬要求，不能改；但手机显示器可能横屏远大于它 +//! （例如 2066×1272）或竖屏略小。这里只在**运行时**把「默认尺寸」换成按当前 X +//! 屏幕算出的最大等比矩形；`ULL_WINDOW_SIZE` 覆盖仍然优先（见 `acceptance::window_size`）。 +//! +//! 只在 Termux + 有 `DISPLAY` 时探测；`xdpyinfo` 缺失/解析失败一律回默认，不影响其它平台。 + +use unlucky_core::platform::paths::ProcessEnv; +use unlucky_core::platform::termux; + +/// 屏幕四周留白（像素）。 +const MARGIN: f32 = 32.0; +/// 最大放大倍数：大屏上也不把窗口撑成巨屏。 +const MAX_SCALE: f32 = 2.0; +/// `xdpyinfo` 里尺寸那一行的前缀。 +const DIMENSIONS_PREFIX: &str = "dimensions:"; + +/// Termux 上的默认窗口尺寸：按 X 屏幕等比放大/缩小，失败返回 `None`（用调用方默认）。 +/// +/// `default` / `min` 由调用方传入（[`super::WINDOW_SIZE`] / [`super::MIN_SIZE`]）， +/// 这里不复制常量。 +#[must_use] +pub(super) fn default_size( + default: (f32, f32), + min: (f32, f32), +) -> Option<((f32, f32), &'static str)> { + if !termux::is_termux(&ProcessEnv) || std::env::var_os("DISPLAY").is_none() { + return None; + } + let screen = x_screen_size()?; + Some((fit_screen(default, min, screen), "termux-screen")) +} + +/// 在 `screen` 里放一个保持 `default` 宽高比的最大矩形（保留留白，不突破 `min`）。 +#[must_use] +pub(super) fn fit_screen(default: (f32, f32), min: (f32, f32), screen: (f32, f32)) -> (f32, f32) { + if screen.0 <= 0.0 || screen.1 <= 0.0 || default.0 <= 0.0 || default.1 <= 0.0 { + return default; + } + let available = ( + (screen.0 - MARGIN * 2.0).max(1.0), + (screen.1 - MARGIN * 2.0).max(1.0), + ); + let scale = (available.0 / default.0) + .min(available.1 / default.1) + .min(MAX_SCALE); + let width = (default.0 * scale).max(min.0).min(screen.0); + let height = (default.1 * scale).max(min.1).min(screen.1); + (width, height) +} + +/// 当前 X 屏幕尺寸（`xdpyinfo` 的 `dimensions: WxH pixels`）。 +fn x_screen_size() -> Option<(f32, f32)> { + // 非 Windows 上 `quiet` 是原样返回（POSIX 没有「spawn 就新开一个终端」这回事）；走它是为了 + // 不在整棵 `crates/` 的子进程守卫里开一个「Termux 专用」例外（M217）。 + let output = unlucky_core::platform::child::quiet("xdpyinfo") + .output() + .ok()?; + if !output.status.success() { + return None; + } + let text = String::from_utf8_lossy(&output.stdout); + let line = text + .lines() + .find(|line| line.trim_start().starts_with(DIMENSIONS_PREFIX))?; + let value = line.split_whitespace().nth(1)?; + let (width, height) = value.split_once('x')?; + Some((width.parse().ok()?, height.parse().ok()?)) +} + +#[cfg(test)] +mod tests { + use super::fit_screen; + + const DEFAULT: (f32, f32) = (1180.0, 760.0); + const MIN: (f32, f32) = (880.0, 560.0); + + fn close(actual: (f32, f32), expected: (f32, f32)) { + assert!( + (actual.0 - expected.0).abs() < 0.5 && (actual.1 - expected.1).abs() < 0.5, + "expected {expected:?}, got {actual:?}" + ); + } + + #[test] + fn landscape_screen_scales_up_keeping_aspect() { + // 2066×1272：留白后 2002×1208，高度是瓶颈 → 1875.6×1208。 + close( + fit_screen(DEFAULT, MIN, (2066.0, 1272.0)), + (1875.58, 1208.0), + ); + } + + #[test] + fn portrait_screen_still_fits_width() { + // 1272×2066：宽度是瓶颈 → 1208×778。 + close(fit_screen(DEFAULT, MIN, (1272.0, 2066.0)), (1208.0, 778.03)); + } + + #[test] + fn huge_screen_is_capped_at_two_times() { + close(fit_screen(DEFAULT, MIN, (4000.0, 3000.0)), (2360.0, 1520.0)); + } + + #[test] + fn tiny_screen_never_goes_below_min_or_overflow() { + let (width, height) = fit_screen(DEFAULT, MIN, (800.0, 600.0)); + assert_eq!(width, 800.0, "宽度受屏幕限制"); + assert_eq!(height, 560.0, "高度不小于最小尺寸"); + } + + #[test] + fn invalid_screen_falls_back_to_default() { + assert_eq!(fit_screen(DEFAULT, MIN, (0.0, 0.0)), DEFAULT); + } +} 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::>(), + args.iter().map(OsStr::new).collect::>(), + "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/diag.rs b/crates/app-iced/src/app/diag.rs new file mode 100644 index 0000000..658d231 --- /dev/null +++ b/crates/app-iced/src/app/diag.rs @@ -0,0 +1,169 @@ +//! 启动期诊断行的**双写**：stderr + `<.ULL>/logs/launcher.log`（M188）。 +//! +//! ## 为什么要有这一层 +//! +//! 双击启动的 GUI 进程**没有 stderr 去向**（Windows 上根本没有控制台）。此前 `[font]` / +//! `[probe]` / `[theme]` / `[appearance]` / `[gpu]` 这些诊断只走 `eprintln!`，于是「启动器视角 +//! 到底发生了什么」在事故之后一个字都不剩——用户投诉的「只有一个安装日志」有一半是它。 +//! +//! 现在这些行同时进 `launch::launcher_log`： +//! +//! ```text +//! diag!("[font] 求值耗时 {:.0} ms", ms) → stderr: [font] 求值耗时 12 ms +//! → launcher.log: 2026-… [font] 求值耗时 12 ms +//! ``` +//! +//! scope 就是行首那个 `[tag]`，所以日志行与老用法**长得一样**，`grep '\[gpu\]'` 仍然好使。 +//! +//! ## 哪些行进日志、哪些只进 stderr +//! +//! 判据（M188 复审后收紧成这一句）：**逐帧度量不接；显式取证开关与一次性事故行可接。** +//! +//! | 进日志 | 只进 stderr | +//! |---|---| +//! | 启动编排（探测结论 / 字体重建 / 主题来源 / 后端最终值 / 降级重开） | **验收与出图矩阵的逐帧度量**：`[window]` / `[perf]` / `[caps]` / `[theme] source=`（`renderer::acceptance/**`，一次启动上百行） | +//! | **一次性事故行**：`[gpu] 初始化失败（具名）` / `[gpu] 失败详情（具名）`（`renderer::report_failure`）、`[gpu] iced_wgpu: …Selected: AdapterInfo…`（`log_bridge`）、`[probe] request=… -> ICED_BACKEND=…`（`probe::apply_with_preflight`）、`[gpu-preflight]`（`ULL_PREFLIGHT=1`） | 组件几何探针的断言输出（`components/**` 的 `[feedback-probe]` / gallery 页面里的 `[gallery]`） | +//! | 用户动作的结果（打开目录、写设置失败、更新忽略/应用、语言没落盘） | 每条日志行的正文里再套一层括号（不是标签，见 [`split_scope`]） | +//! | 显式开关下的一次性行：`[tick]`（`ULL_TICK_TRACE=1`，≈1 行/秒 ≈ 4.8 小时才滚一次）、`[shot]` 的通道提示 | — | +//! +//! 为什么逐帧行不许接：`launcher.log` 有 1 MiB 上限（滚成 `launcher.1.log`，只留一份）， +//! 逐帧写会在几分钟内把「事故现场」冲掉。反过来，`report_failure` 那两行**就是**事故本体—— +//! 双击启动没有 stderr，把它们留在 stderr 等于在最该有日志的路径上什么都没有（M188 复审 P2-1）。 + +/// 行首没有 `[tag]` 时的默认 scope。 +pub const APP_SCOPE: &str = "app"; + +/// 记一行诊断：stderr 照旧，另外进启动器日志（best-effort，写不进去也不影响启动）。 +pub(crate) fn emit(line: &str) { + eprintln!("{line}"); + let (scope, message) = split_scope(line); + unlucky_core::launch::launcher_log::record(scope, message); +} + +/// `[font] 求值耗时 12 ms` → (`font`, `求值耗时 12 ms`)。 +/// +/// scope 只认「短、无空白、非空」的方括号前缀：`[a b]` 这种是正文而不是标签，别把整行拆坏。 +pub(crate) fn split_scope(line: &str) -> (&str, &str) { + let Some(rest) = line.strip_prefix('[') else { + return (APP_SCOPE, line); + }; + let Some((scope, tail)) = rest.split_once(']') else { + return (APP_SCOPE, line); + }; + if scope.is_empty() || scope.len() > 24 || scope.contains(char::is_whitespace) { + return (APP_SCOPE, line); + } + (scope, tail.trim_start()) +} + +/// 双写一行诊断（`diag!("[scope] 正文")`，参数同 `eprintln!`）。 +macro_rules! diag { + ($($arg:tt)*) => {{ + crate::app::diag::emit(&format!($($arg)*)); + }}; +} + +pub(crate) use diag; + +/// 串行化「会改 `launcher_log` 全局目录」的用例。 +/// +/// `core::launch::launcher_log` 是**进程级单例**（目录 + 缓冲），而 app-iced 的测试二进制里 +/// 有两条用例会 `set_dir` 到自己的临时目录（本文件的滚动闸、`app/dialog/tests.rs` 的启动事实闸）。 +/// 它们必须串行，否则互相把对方的落点改走——那是两条闸互相打架，不是产品问题。 +#[cfg(test)] +pub(crate) static LOG_STATE_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(()); + +#[cfg(test)] +mod tests { + use super::split_scope; + + #[test] + fn the_leading_bracket_becomes_the_scope() { + assert_eq!( + split_scope("[font] 求值耗时 12 ms"), + ("font", "求值耗时 12 ms") + ); + assert_eq!(split_scope("[gpu]"), ("gpu", "")); + // 正文里的方括号不是标签 + assert_eq!( + split_scope("[page] 占位动作 [x] pressed"), + ("page", "占位动作 [x] pressed") + ); + } + + #[test] + fn lines_without_a_tag_fall_back_to_the_default_scope() { + assert_eq!(split_scope("没有标签的一行"), ("app", "没有标签的一行")); + assert_eq!( + split_scope("[a b] 空白不是标签"), + ("app", "[a b] 空白不是标签") + ); + } + + /// 守门②：**启动器日志的滚动真的会发生**，写超上限之后文件仍然有界。 + /// + /// ## 为什么要「重试」 + /// + /// `launcher_log` 是**进程级单例**（目录 + 缓冲），而同进程里还有一条用例 + /// （`app/dialog/tests.rs` 的 `boot_facts_are_recorded_into_the_launcher_log`）会 + /// `set_dir` 到它自己的临时目录。两边撞上时我这几行的落点就换了人，所以每一轮都要 + /// **从头跑一遍**（登记 → 造超限 → 追加 → 看有没有滚），并且用「我这份超限文件有没有被 + /// rename」判断这一轮是不是真的跑在我目录上。重试不是放宽断言：每轮该发生的都得真发生。 + /// + /// 变异证明：删掉 `core::launch::launcher_log::append` 里那段「超限就 rename 成 launcher.1.log」， + /// 每一轮都不会出现 `launcher.1.log`，本条在重试用尽后红。 + #[test] + fn the_launcher_log_rolls_over_and_stays_bounded() { + use unlucky_core::launch::launcher_log; + + let _guard = super::LOG_STATE_LOCK + .lock() + .unwrap_or_else(|error| error.into_inner()); + + let dir = std::env::temp_dir().join(format!("ull-launcher-log-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&dir); + std::fs::create_dir_all(&dir).expect("建夹具目录"); + let path = dir.join(launcher_log::FILE_NAME); + let rolled = dir.join("launcher.1.log"); + let oversize = usize::try_from(launcher_log::MAX_BYTES).expect("上限能塞进 usize") + 16; + + for _ in 0..50 { + let _ = std::fs::remove_file(&path); + let _ = std::fs::remove_file(&rolled); + launcher_log::set_dir(&dir); + if launcher_log::path() != Some(path.clone()) { + continue; // 这一轮被别人的 set_dir 抢先了 + } + launcher_log::record("boot", "第一行"); + std::fs::write(&path, vec![b'x'; oversize]).expect("造一份超限日志"); + if launcher_log::path() != Some(path.clone()) { + continue; + } + launcher_log::record("boot", "滚过之后这一行必须在新文件里"); + if launcher_log::path() != Some(path.clone()) { + continue; // 追加落到了别人的目录，这一轮不算 + } + + // 到这儿为止，追加**确实**落在本目录：超限就必须滚。 + assert!(rolled.is_file(), "超限之后旧档必须滚成 launcher.1.log"); + let size = std::fs::metadata(&path).expect("新文件").len(); + assert!( + size < launcher_log::MAX_BYTES, + "滚完之后新文件必须远小于上限：{size}" + ); + let text = std::fs::read_to_string(&path).expect("读新文件"); + assert!(text.contains("滚过之后这一行"), "{text}"); + + // 只留一份历史：再滚一次仍然是 `launcher.1.log`，不会长出 launcher.2.log。 + std::fs::write(&path, vec![b'y'; oversize]).expect("再造一份超限日志"); + launcher_log::record("boot", "第二次滚动"); + assert!(rolled.is_file()); + assert!(!dir.join("launcher.2.log").exists(), "历史只留一份"); + assert!(std::fs::metadata(&path).expect("新文件").len() < launcher_log::MAX_BYTES); + + std::fs::remove_dir_all(&dir).ok(); + return; + } + panic!("50 轮都撞上别的用例在改全局日志目录，这一条没能真正跑起来"); + } +} diff --git a/crates/app-iced/src/app/dialog.rs b/crates/app-iced/src/app/dialog.rs new file mode 100644 index 0000000..9eb707d --- /dev/null +++ b/crates/app-iced/src/app/dialog.rs @@ -0,0 +1,390 @@ +//! 模态对话框（M187 接通 `DialogQueue`）+ 启动失败卡片。 +//! +//! ## 为什么先补这一层 +//! +//! 接线审计（M177）的结论很硬：`DialogQueue` / `DialogRequest` 在 app-iced 里**零引用**， +//! 所有弹窗都画不出来。于是「像 PCL2 / HMCL 那样，启动失败时弹一个带崩溃说明的框」这件事 +//! 在此之前根本无处落脚。本模块是最小可用的一层： +//! +//! ```text +//! presenter AppState::dialogs（唯一队列） +//! │ current() +//! ▼ +//! dialog::current(lang, request, card) ← 纯视图模型（测试打这里） +//! │ +//! ▼ +//! dialog::view::layer(ui, base, modal) ← 模态遮罩 + 卡片 + 主/次按钮 +//! ``` +//! +//! 交互：主按钮 / 次按钮 / 点遮罩 / `Esc` 都关当前条（`DialogQueue::close_current`）。 +//! +//! ## 崩溃卡片额外带什么 +//! +//! `DialogRequest`（presenter 的 DTO）只有标题/正文/按钮，而这次用户要的是**证据**： +//! 退出码、一句人话原因、**文件路径**、可展开的崩溃说明、以及三个按钮（导出 / 打开文件夹 / +//! 复制路径）。这些东西不进 `DialogRequest`——它是 presenter 的公共 DTO，塞进 UI 专用字段 +//! 会把「谁拥有证据」搅浑。做法是：队列管**弹窗**，[`CrashCard`] 管**这次失败的事实**， +//! 两者按 `DialogId` 绑定，见 [`App::open_failure_dialog`]。 +//! +//! 事实来源是 `unlucky_core::launch::crash_report`（启动线程收尾时登记的现场）。这里只读它， +//! 不重算：**界面不读盘、不猜原因**。 + +use unlucky_core::launch::crash_report::{CrashReport, Evidence}; +use unlucky_i18n::catalog::{Catalog, Key}; +use unlucky_i18n::Lang; +use unlucky_presenter::dialogs::{DialogId, DialogKind, DialogSource}; + +use crate::app::state::App; + +pub(super) mod export; +#[cfg(test)] +mod tests; +pub(super) mod view; + +/// 崩溃卡片：一次失败的**事实**（不含任何结论）。 +#[derive(Debug, Clone)] +pub struct CrashCard { + /// 现场。 + pub report: CrashReport, + /// 「详细崩溃说明」是否展开。 + pub expanded: bool, + /// 与哪一条队列请求绑定（关掉它时把卡片一起清掉）。 + pub dialog: DialogId, + /// 上一次动作的结论（导出到哪 / 打不开文件夹的原因）。 + /// + /// 为什么写在卡片里而不是只推 Toast：app-iced 的 Toast 通道**至今没有任何渲染点** + /// （`state.toasts` 只被推入与过期，`view` 里一次都没读）。导出这种「必须看见落到哪」的 + /// 结果不能挂在一条不显示的通道上。 + pub outcome: Option, +} + +/// 弹窗消息。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum Message { + /// 主按钮。 + Primary, + /// 次按钮。 + Secondary, + /// 点遮罩 / Esc。 + Dismiss, + /// 展开 / 收起详细说明。 + Toggle, + /// 打开日志文件夹。 + OpenFolder, + /// 复制全部路径。 + CopyPaths, + /// 复制第 `index` 条路径（`Modal::paths` 的下标）。 + CopyPath(usize), +} + +/// 视图模型：**测试与渲染共用**的一份「这一屏该出现什么」。 +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub(super) struct Modal { + /// 标题。 + pub title: String, + /// 正文（每行一段；都是运行时拼出来的 owned 字符串）。 + pub body: Vec, + /// 主按钮文字。 + pub primary: String, + /// 次按钮文字（`None` = 不画）。 + pub secondary: Option, + /// 是否有次按钮（`Progress` 没有）。 + pub blocking_progress: bool, + /// 崩溃卡片（普通弹窗为 `None`）。 + pub card: Option, + /// 动作结论（导出路径 / 失败原因）；`None` = 还没有动作。 + pub notice: Option, +} + +/// 崩溃卡片的展示内容。 +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub(super) struct CardView { + /// 展开 / 收起按钮的文字。 + pub toggle: String, + /// 当前的展开态。 + pub expanded: bool, + /// （标签, 路径）列表——**逐条可点**（点了复制该条）。 + pub paths: Vec<(String, String)>, + /// 详细说明的小标题（`None` = 没有可展开的内容）。 + pub detail_title: Option, + /// 详细说明的正文行。 + pub detail_lines: Vec, + /// 三个按钮的文字。 + pub actions: [String; 3], +} + +impl Modal { + /// 正文全文（测试与「复制摘要」共用；换行拼起来）。 + #[must_use] + #[cfg(test)] + pub fn body_text(&self) -> String { + self.body.join("\n") + } +} + +/// 从队列当前条与卡片造视图模型（**纯函数**：不读盘、不看 App）。 +#[must_use] +pub(super) fn current( + lang: Lang, + request: &DialogRequestView<'_>, + card: Option<&CrashCard>, +) -> Modal { + let catalog = Catalog::of(lang); + let mut modal = Modal { + title: request.title.to_string(), + body: vec![request.body.to_string()], + primary: request.primary.to_string(), + secondary: request.secondary.map(str::to_string), + blocking_progress: request.blocking_progress, + card: None, + notice: None, + }; + if let Some(card) = card { + let detail = detail_of(&catalog, card); + modal.body = failure_body(&catalog, &card.report); + modal.primary = catalog.text(Key::CrashDialogExport).to_string(); + modal.secondary = Some(catalog.text(Key::CrashDialogClose).to_string()); + modal.card = Some(CardView { + toggle: catalog + .text(if card.expanded { + Key::CrashDialogHideDetail + } else { + Key::CrashDialogShowDetail + }) + .to_string(), + expanded: card.expanded, + paths: path_rows(&catalog, &card.report), + detail_title: detail.0, + detail_lines: detail.1, + actions: [ + catalog.text(Key::CrashDialogExport).to_string(), + catalog.text(Key::CrashDialogOpenFolder).to_string(), + catalog.text(Key::CrashDialogCopyPaths).to_string(), + ], + }); + modal.notice = card.outcome.clone(); + } + modal +} + +/// 队列当前条的最小视图（避免把 `DialogRequest` 的细节漏进页面层）。 +pub(super) struct DialogRequestView<'a> { + /// 标题。 + pub title: &'a str, + /// 正文。 + pub body: &'a str, + /// 主按钮。 + pub primary: &'a str, + /// 次按钮。 + pub secondary: Option<&'a str>, + /// 进度框不可点主按钮。 + pub blocking_progress: bool, +} + +impl<'a> DialogRequestView<'a> { + /// 从 presenter 的请求取视图。 + pub(super) fn of(request: &'a unlucky_presenter::dialogs::DialogRequest) -> Self { + Self { + title: &request.title, + body: &request.body, + primary: request.kind.primary_label(), + secondary: request.kind.secondary_label(), + blocking_progress: request.kind.is_blocking_progress(), + } + } +} + +/// 失败正文：退出码 + **一句人话原因** + 证据形态。 +/// +/// 三件事都必须有——用户投诉的原话是「找半天没找到崩溃日志」，所以第三句不是锦上添花： +/// 它要么指向游戏写的那份，要么明确说「这次没有，下面是捕获到的输出」。 +fn failure_body(catalog: &Catalog, report: &CrashReport) -> Vec { + let mut body = Vec::new(); + if let Some(code) = report.exit_code { + body.push(catalog.render(Key::CrashDialogExitCode, &[("code", &code.to_string())])); + } + if let Some(stage) = &report.stage { + let label = stage_label(catalog, stage); + body.push(catalog.render(Key::CrashDialogStageReason, &[("stage", label)])); + } else if report.exit_code == Some(0) { + body.push(catalog.text(Key::CrashDialogSilentFailure).to_string()); + } else { + body.push(catalog.text(Key::CrashDialogStartedThenDied).to_string()); + } + body.push( + match report.evidence() { + Evidence::GameCrashReport => catalog.text(Key::CrashDialogCrashReportFound), + Evidence::CapturedOutput => catalog.text(Key::CrashDialogNoGameLog), + Evidence::Nothing => catalog.text(Key::CrashDialogNoLogAtAll), + } + .to_string(), + ); + body +} + +/// 装配阶段 slug → 文案（**不**复用 core 的中文诊断串）。 +fn stage_label(catalog: &Catalog, slug: &str) -> &'static str { + let key = match slug { + "version_manifest" => Key::LaunchStageVersionManifest, + "inheritance" => Key::LaunchStageInheritance, + "instance_config" => Key::LaunchStageInstanceConfig, + "isolation" => Key::LaunchStageIsolation, + "identity" => Key::LaunchStageIdentity, + _ => Key::LaunchStageSpawn, + }; + catalog.text(key) +} + +/// 路径行（**启动器日志目录 + 该实例 latest.log + crash-reports 目录 + 会话 JSONL**）。 +fn path_rows(catalog: &Catalog, report: &CrashReport) -> Vec<(String, String)> { + let mut rows = Vec::new(); + if let Some(log) = &report.session_log { + rows.push(( + catalog.text(Key::CrashDialogSessionLog).to_string(), + log.display().to_string(), + )); + } + if let Some(dir) = &report.launcher_logs { + rows.push(( + catalog.text(Key::CrashDialogLauncherLogs).to_string(), + dir.display().to_string(), + )); + } + if let Some(path) = report.latest_log_path() { + rows.push(( + catalog.text(Key::CrashDialogGameLog).to_string(), + path.display().to_string(), + )); + } + if let Some(dir) = report.crash_reports_dir() { + rows.push(( + catalog.text(Key::CrashDialogCrashReports).to_string(), + dir.display().to_string(), + )); + } + rows +} + +/// 详细说明：有崩溃报告贴 Description/栈片段，否则贴启动器捕获的尾巴。 +fn detail_of(catalog: &Catalog, card: &CrashCard) -> (Option, Vec) { + let report = &card.report; + if let Some(artifact) = report + .artifacts + .iter() + .find(|artifact| artifact.source == "crash_report") + { + let mut lines = Vec::new(); + if let Some(excerpt) = &artifact.excerpt { + lines.extend(excerpt.lines().map(str::to_string)); + } else { + lines.push(artifact.path.display().to_string()); + } + let title = format!( + "{} {}", + catalog.text(Key::LogsDiagnosisTitle), + artifact.path.display() + ); + return (Some(title), lines); + } + if report.stderr_tail.is_empty() { + return (None, Vec::new()); + } + let title = catalog.render( + Key::CrashDialogCapturedTail, + &[("count", &report.stderr_tail.len().to_string())], + ); + (Some(title), report.stderr_tail.clone()) +} + +// --------------------------------------------------------------- 与 App 的接线 + +impl App { + /// 队列当前条 → 视图模型（`view()` 与测试共用同一个入口）。 + pub(super) fn dialog_modal(&self) -> Option { + let request = self.state.dialogs.current()?; + let view = DialogRequestView::of(request); + let card = self + .dialog_card + .as_ref() + .filter(|card| card.dialog == request.id); + Some(current(self.lang(), &view, card)) + } + + /// 收到一次启动收尾：失败就弹框（成功不打扰）。 + /// + /// 只在**真的失败**时弹：`LogOutcome::Ok` 且没有阶段失败 ⇒ 什么都不做，与既有 Toast 口径一致。 + pub(super) fn open_failure_dialog( + &mut self, + finished: &unlucky_presenter::dto::LaunchFinished, + ) { + let failed = finished.outcome != unlucky_presenter::dto::LogOutcome::Ok + || finished.failure.is_some(); + if !failed { + return; + } + let Some(report) = unlucky_core::launch::crash_report::failing_launch() else { + return; + }; + if !finished.session.is_empty() && report.session != finished.session { + // 登记的是另一场（并发启动）：不拿它去解释这一场。 + return; + } + let catalog = self.lang().catalog(); + let crashed = report.started(); + let title = catalog.text(if crashed { + Key::CrashDialogTitleCrashed + } else { + Key::CrashDialogTitleFailed + }); + let summary = self.dialog_summary(&report); + let at = self.lang(); + let id = self.state.dialogs.push( + DialogSource::UserAction, + title, + summary, + DialogKind::Confirm { + primary: Catalog::of(at).text(Key::CrashDialogExport).to_string(), + secondary: Catalog::of(at).text(Key::CrashDialogClose).to_string(), + }, + ); + self.dialog_card = Some(CrashCard { + report, + // 默认展开：正文已经说「下面是捕获的最后若干行」，收着就成了空口承诺。 + expanded: true, + dialog: id, + outcome: None, + }); + self.view_dirty = true; + } + + /// 队列标题下的那一行摘要（弹窗正文由 [`current`] 按卡片重算，这里给它一份独立可读的短句）。 + fn dialog_summary(&self, report: &CrashReport) -> String { + let catalog = self.lang().catalog(); + match report.exit_code { + Some(code) => catalog.render(Key::CrashDialogExitCode, &[("code", &code.to_string())]), + None => catalog.text(Key::CrashDialogTitleFailed).to_string(), + } + } + + /// 关掉当前弹窗（主/次按钮、遮罩、`Esc` 共用）。 + pub(super) fn close_dialog(&mut self) { + let closed = self.state.dialogs.current().map(|request| request.id); + self.state.dialogs.close_current(); + if self + .dialog_card + .as_ref() + .is_some_and(|card| closed == Some(card.dialog)) + { + self.dialog_card = None; + } + self.view_dirty = true; + } + + /// 展开 / 收起详细说明。 + pub(super) fn toggle_dialog_detail(&mut self) { + if let Some(card) = &mut self.dialog_card { + card.expanded = !card.expanded; + self.view_dirty = true; + } + } +} diff --git a/crates/app-iced/src/app/dialog/export.rs b/crates/app-iced/src/app/dialog/export.rs new file mode 100644 index 0000000..f44f79b --- /dev/null +++ b/crates/app-iced/src/app/dialog/export.rs @@ -0,0 +1,217 @@ +//! 失败卡片的三个动作：导出诊断包 / 打开文件夹 / 复制路径。 +//! +//! 与 [`super`] 分开是因为职责不同：那边管**弹窗与事实**，这边管**把事实带出界面**。 +//! 打包本体在 `unlucky_core::launch::crash_bundle`（脱敏、上限、清单都在那一处）， +//! 本文件只负责「放哪、叫什么名字、怎么打开」。 + +use std::path::PathBuf; + +use unlucky_core::launch::crash_bundle::{self, BundleEntry, BundleSpec}; +use unlucky_core::launch::crash_report::CrashReport; +use unlucky_i18n::catalog::{Catalog, Key}; +use unlucky_i18n::Lang; + +/// 一次导出的结论（**成功也带事实**：路径、字节数、有没有文件被截断）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct Exported { + /// 给用户看的那一句（已本地化）。 + pub text: String, + /// 是否成功。 + pub ok: bool, + /// 有几个文件被截断（`>0` 时界面要明说「证据是残的」）。 + pub truncated: usize, +} + +/// 导出诊断包：打到「启动器日志目录 / exports / 一场一个文件名」。 +/// +/// 返回的那句话说清**落到哪、多少字节**（用户要的第一件事就是「文件在哪」）； +/// 有文件被截断时再补一句——别让用户以为包里的证据是完整的。 +pub(crate) fn export(report: &CrashReport, lang: Lang) -> Exported { + let catalog = Catalog::of(lang); + let Some(logs) = &report.launcher_logs else { + return Exported { + text: catalog.render( + Key::CrashDialogExportFailed, + &[("error", "no launcher log dir")], + ), + ok: false, + truncated: 0, + }; + }; + let stamp = + unlucky_core::launch::time::format_rfc3339_millis(unlucky_core::launch::time::now()) + .replace([':', '.', 'T'], "-") + .trim_end_matches('Z') + .to_string(); + let name = if report.session.is_empty() { + &report.instance + } else { + &report.session + }; + let target = crash_bundle::default_target_dir(logs).join(format!("crash-{name}-{stamp}.zip")); + match crash_bundle::write_bundle(&spec_of(report), &target) { + Ok(bundle) => { + let mut text = catalog.render( + Key::CrashDialogExportDone, + &[ + ("bytes", &bundle.bytes.to_string()), + ("path", &bundle.path.display().to_string()), + ], + ); + if bundle.truncated > 0 { + text.push('\n'); + text.push_str(&catalog.render( + Key::CrashDialogExportTruncated, + &[("count", &bundle.truncated.to_string())], + )); + } + Exported { + text, + ok: true, + truncated: bundle.truncated, + } + } + Err(error) => Exported { + text: catalog.render(Key::CrashDialogExportFailed, &[("error", &error)]), + ok: false, + truncated: 0, + }, + } +} + +/// 现场 → 诊断包清单（**进包的东西必须与弹窗上列出的路径一致**）。 +fn spec_of(report: &CrashReport) -> BundleSpec { + let mut entries: Vec = Vec::new(); + let push = |entries: &mut Vec, group: &'static str, path: &std::path::Path| { + if path.exists() { + entries.push(BundleEntry::new(group, path)); + } + }; + if let Some(logs) = &report.launcher_logs { + push(&mut entries, "launcher", &logs.join("launcher.log")); + push(&mut entries, "launcher", &logs.join("launcher.1.log")); + push(&mut entries, "launcher", &logs.join("install.log")); + } + if let Some(session) = &report.session_log { + // 源文件名就是会话 id：钉成 `session.jsonl`，包内名与清单名同时不再泄漏 id， + // 也不会出现「清单写 而包里是原始 id」（r1 复审 P2-2）。 + if session.exists() { + entries.push(BundleEntry::named("session", session, "session.jsonl")); + } + } + for artifact in &report.artifacts { + // `latest.log` 在下面单独收一次（它同时是扫描结果与固定项，重复收会变成两份）。 + if artifact.source != "latest_log" { + push(&mut entries, "game", &artifact.path); + } + } + if let Some(latest) = report.latest_log_path() { + push(&mut entries, "game", &latest); + } + if let Some(json) = &report.version_json { + push(&mut entries, "instance", json); + } + let mut secrets = vec![report.session.clone()]; + secrets.retain(|secret| !secret.is_empty()); + BundleSpec { + instance: report.name.clone(), + version: report.version.clone(), + session: report.session.clone(), + exit_code: report.exit_code, + exit_type: report.exit_type.clone(), + uptime_ms: report.uptime_ms, + command: report.command.clone(), + java: report.java.clone(), + system: report.system.clone(), + notes: report.note_lines(), + missing: report.missing_lines(), + entries, + secrets, + home: std::env::var("USERPROFILE") + .or_else(|_| std::env::var("HOME")) + .ok() + .map(PathBuf::from), + } +} + +/// 打开「日志文件夹」：有现场就开实例运行目录，否则开启动器日志目录。 +/// +/// 平台差异只在这里一处（`explorer` / `open` / `xdg-open`），不往业务代码里散写 `cfg`。 +pub(crate) fn open_folder(report: &CrashReport, lang: Lang) -> String { + let catalog = Catalog::of(lang); + let target = report + .run_dir + .clone() + .filter(|dir| dir.is_dir()) + .or_else(|| report.launcher_logs.clone().filter(|dir| dir.is_dir())); + let Some(dir) = target else { + return catalog.render( + Key::CrashDialogOpenFailed, + &[("error", "no folder on disk")], + ); + }; + match open_dir(&dir) { + Ok(()) => String::new(), + Err(error) => catalog.render(Key::CrashDialogOpenFailed, &[("error", &error)]), + } +} + +/// 打开一个目录（M188：设置页/日志页的「打开日志文件夹」也走这里，**不再另写一套 `cfg`**）。 +/// +/// 失败文本带完整路径：调用方把它显示/记日志出来，用户至少能照着路径去找。 +pub(crate) fn open_dir(dir: &std::path::Path) -> Result<(), String> { + if !dir.is_dir() { + return Err(format!("{}（目录不存在）", dir.display())); + } + spawn_opener(dir).map_err(|error| format!("{}（打开失败：{error}）", dir.display())) +} + +/// 平台各自的「打开这个目录」实现。 +/// +/// ## 为什么这三处**故意**不走 `unlucky_core::platform::child::quiet`（M217） +/// +/// 这一处 spawn 的**目的就是让桌面上出现一个可见的东西**（文件管理器窗口 / Finder 窗口 / +/// 桌面环境的文件管理器）。`quiet` 的语义是「把子进程的窗口抑制掉」，用在这里是把目的本身 +/// 抑制掉——改错了用户点「打开文件夹」就只看到「打不开」的报错。 +/// +/// 而且从窗口角度也不需要它：`explorer.exe` / `open` / `xdg-open` 自己都是 GUI 侧程序，由 +/// 无控制台的 GUI 父进程 spawn 时 Windows 不会给它们新建控制台。所以这三处在 +/// `crates/core/tests/child_quiet_guard.rs` 的 `ALLOWED_ROLES` 里登记成「目录打开器」角色， +/// **不是**漏网。别把它们改成 `quiet`。 +#[cfg(target_os = "windows")] +fn spawn_opener(dir: &std::path::Path) -> Result<(), String> { + // `explorer` 不用 shell：路径里的空格与 `&` 不会被当成命令分隔符。 + std::process::Command::new("explorer") + .arg(dir) + .spawn() + .map(|_| ()) + .map_err(|error| error.to_string()) +} + +#[cfg(target_os = "macos")] +fn spawn_opener(dir: &std::path::Path) -> Result<(), String> { + std::process::Command::new("open") + .arg(dir) + .spawn() + .map(|_| ()) + .map_err(|error| error.to_string()) +} + +#[cfg(not(any(target_os = "windows", target_os = "macos")))] +fn spawn_opener(dir: &std::path::Path) -> Result<(), String> { + std::process::Command::new("xdg-open") + .arg(dir) + .spawn() + .map(|_| ()) + .map_err(|error| error.to_string()) +} + +/// 「复制路径」的一段文本（每条一行，标签 + 路径）。 +pub(crate) fn paths_text(report: &CrashReport) -> String { + report + .path_lines() + .into_iter() + .map(|(label, path)| format!("{label}: {}", path.display())) + .collect::>() + .join("\n") +} diff --git a/crates/app-iced/src/app/dialog/tests.rs b/crates/app-iced/src/app/dialog/tests.rs new file mode 100644 index 0000000..41c379a --- /dev/null +++ b/crates/app-iced/src/app/dialog/tests.rs @@ -0,0 +1,344 @@ +//! 弹窗的三条守卫：**队列真的被消费**、**运行时中文真的进了正文**、**两种失败说两句话**。 +//! +//! ## 这些用例抓得住什么 / 抓不住什么（说在明处） +//! +//! | 用例 | 抓得住 | 抓不住 | +//! |---|---|---| +//! | [`queue_drives_the_modal_through_refresh_view`] | 队列里有请求 ⇒ `refresh_view` 之后 `view()` 拿到的模型里就有它（把消费点删掉即红） | 像素：`view()` 是否真的把控件塞进 iced 树（由 `DevDocs/artifacts/m187/` 的截图守） | +//! | [`runtime_chinese_reaches_the_body`] | 运行时拼出来的中文（`render` / `format!` 的 owned 串）确实在正文里 | 字形是否栅格化出来（同上，wgpu / tiny-skia 并排图） | +//! | [`two_failure_shapes_say_two_different_things`] | 没有 crash-report 时**不会**说成「有崩溃报告」，而且必须贴出捕获行 | 那句话读起来顺不顺（review） | +//! +//! 「owned 文字在 wgpu 下丢字」这条 M190 的怀疑在本 branch 上**没有复现**（A/B 图见 +//! `DevDocs/artifacts/m187/ab-wgpu.png` 与 `ab-tinyskia.png`）：同一串中文走 `text_role` 与 +//! `text_role_owned` 在两种后端下逐字相同。所以这里不编一条「为了变绿而改渲染路径」的断言。 + +use std::path::PathBuf; + +use unlucky_core::launch::crash_report::{self, ArtifactFact, CrashReport}; +use unlucky_i18n::catalog::Key; +use unlucky_i18n::Lang; +use unlucky_presenter::dialogs::{DialogKind, DialogQueue, DialogSource}; +use unlucky_presenter::dto::{LaunchFinished, LogOutcome}; + +use super::{current, path_rows, CrashCard, DialogRequestView}; + +use crate::app::state::App; +use crate::cli::Options; +use crate::theme::Families; + +const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", +}; + +fn headless() -> App { + use unlucky_presenter::mock::MockBackend; + use unlucky_presenter::settings_bridge::SettingsBridge; + App::with_presenter( + Options::default(), + FAMILIES, + unlucky_design::color::SchemeFlavor::Light, + Box::new(MockBackend::new()), + SettingsBridge::memory_only(), + ) +} + +fn report(with_crash_report: bool, tail: Vec) -> CrashReport { + let run_dir = PathBuf::from("/instances/survival"); + let artifacts = if with_crash_report { + vec![ArtifactFact { + source: "crash_report".to_string(), + path: run_dir.join("crash-reports/crash-2026-11-08.txt"), + excerpt: Some("Description: Initializing game".to_string()), + }] + } else { + Vec::new() + }; + CrashReport { + instance: "survival".to_string(), + name: "生存".to_string(), + version: "1.20.4-fabric".to_string(), + session: "9f2c".to_string(), + session_log: Some(PathBuf::from("/sessions/game/9f2c.jsonl")), + version_json: Some(PathBuf::from("/game/versions/1.20.4/1.20.4.json")), + launcher_logs: Some(PathBuf::from("/logs")), + run_dir: Some(run_dir), + artifacts, + exit_code: Some(1), + exit_type: "application_error".to_string(), + uptime_ms: 1_000, + command: "javaw -Xmx4096m".to_string(), + java: "javaw.exe (21)".to_string(), + system: "os=windows".to_string(), + stage: None, + stage_detail: None, + stderr_tail: tail, + } +} + +/// 守卫①：队列消费。请求进队列 ⇒ `refresh_view` 之后模型里有它；空队列 ⇒ 没有。 +/// +/// **变异证明**：把 `refresh_view` 末尾那行 `self.dialog_model = self.dialog_modal();` 删掉， +/// 本用例第二段立刻红（`dialog_model` 恒 `None`）。 +#[test] +fn queue_drives_the_modal_through_refresh_view() { + let mut app = headless(); + app.refresh_view(); + assert!( + app.dialog_model.is_none(), + "空队列不该画任何弹窗（现状：队列零引用，弹窗从不渲染）" + ); + + let title = app.lang().catalog().text(Key::CrashDialogTitleFailed); + app.state.dialogs.push( + DialogSource::UserAction, + title, + "正文一行", + DialogKind::Confirm { + primary: "主要".to_string(), + secondary: "次要".to_string(), + }, + ); + app.view_dirty = true; + app.refresh_view(); + + let modal = app.dialog_model.as_ref().expect("队列里有请求就必须有模型"); + assert_eq!(modal.title, title); + assert_eq!(modal.primary, "主要"); + assert_eq!(modal.secondary.as_deref(), Some("次要")); +} + +/// 守卫②：**运行时拼出来的中文**必须真的进正文（owned 串走 `Catalog::render` / `format!`）。 +/// +/// **变异证明**：把 `failure_body` 里的 `catalog.render(Key::CrashDialogExitCode, …)` 换成固定 +/// 英文，本用例第一处断言立刻红。 +#[test] +fn runtime_chinese_reaches_the_body() { + let lang = Lang::ZhCn; + let card = CrashCard { + report: report(false, vec!["java.lang.RuntimeException: boom".to_string()]), + expanded: true, + dialog: 1, + outcome: None, + }; + let mut queue = DialogQueue::new(); + queue.push( + DialogSource::UserAction, + "游戏崩溃", + "", + DialogKind::Confirm { + primary: String::new(), + secondary: String::new(), + }, + ); + let request = queue.current().expect("当前条"); + let view = DialogRequestView::of(request); + let modal = current(lang, &view, Some(&card)); + let body = modal.body_text(); + + // 退出码那句是 `render`（带参数）拼出来的：必须带中文与数字。 + assert!(body.contains("退出码 1"), "{body}"); + assert!(body.contains("游戏进程起来了"), "{body}"); + // 没有 crash-report 时必须说「没生成」+「下面是捕获的行」。 + assert!(body.contains("没有生成崩溃报告"), "{body}"); + assert!(body.contains("捕获"), "{body}"); + // 英文界面里同样的三句不许出现中文（反向守卫：i18n 不是只往一个方向写）。 + let en = current(Lang::En, &view, Some(&card)); + assert!(!en.body_text().contains('崩'), "{}", en.body_text()); +} + +/// 守卫③：两种失败**说两句不同的话**，而且都可以导出（事实齐全）。 +#[test] +fn two_failure_shapes_say_two_different_things() { + let lang = Lang::ZhCn; + let with = report(true, vec!["stack line".to_string()]); + let without = report(false, vec!["Error: could not find java.dll".to_string()]); + + assert_ne!(with.evidence(), without.evidence()); + let with_card = CrashCard { + report: with.clone(), + expanded: true, + dialog: 1, + outcome: None, + }; + let without_card = CrashCard { + report: without.clone(), + expanded: true, + dialog: 1, + outcome: None, + }; + let mut queue = DialogQueue::new(); + queue.push( + DialogSource::UserAction, + "t", + "", + DialogKind::Error { + primary: "p".to_string(), + hint: None, + }, + ); + let request = queue.current().unwrap(); + let view = DialogRequestView::of(request); + + let crash = current(lang, &view, Some(&with_card)); + let no_log = current(lang, &view, Some(&without_card)); + assert_ne!(crash.body_text(), no_log.body_text()); + assert!(crash.body_text().contains("写出了崩溃报告")); + assert!(!no_log.body_text().contains("写出了崩溃报告")); + // 没有 crash-report 的那一态仍然有可展开的细节（贴的是捕获行）与四条路径。 + assert!(no_log.card.as_ref().expect("卡片").detail_title.is_some()); + assert_eq!(path_rows(&lang.catalog(), &without).len(), 4); + assert!(path_rows(&lang.catalog(), &without) + .iter() + .any(|(_, path)| path.ends_with("latest.log"))); +} + +/// 弹窗开/关与卡片的绑定：关掉之后两样都要空（否则下一次失败会读到上一次的现场）。 +#[test] +fn closing_the_dialog_clears_the_card() { + let mut app = headless(); + crash_report::publish(report(false, vec!["line".to_string()])); + let finished = LaunchFinished { + id: "survival".to_string(), + session: "9f2c".to_string(), + outcome: LogOutcome::Crashed, + exit_code: Some(1), + uptime_ms: 1_000, + failure: None, + }; + app.open_failure_dialog(&finished); + assert!(app.state.dialogs.current().is_some(), "失败必须弹框"); + assert!(app.dialog_card.is_some()); + + app.close_dialog(); + assert!(app.state.dialogs.current().is_none()); + assert!(app.dialog_card.is_none()); +} + +/// 成功收尾不打扰用户。 +#[test] +fn a_successful_launch_does_not_pop_anything() { + let mut app = headless(); + crash_report::publish(report(false, Vec::new())); + let finished = LaunchFinished { + id: "survival".to_string(), + session: "9f2c".to_string(), + outcome: LogOutcome::Ok, + exit_code: Some(0), + uptime_ms: 90_000, + failure: None, + }; + app.open_failure_dialog(&finished); + assert!(app.state.dialogs.current().is_none()); +} + +/// P2-1：**卡片那一层只能是卡片大**。 +/// +/// 抓得住什么：r1 复审实测的那个 bug —— `mouse_area(整窗居中容器)` 的命中区是整窗， +/// 卡片外任何一次点击都先被它捕获，遮罩永远收不到（「点遮罩关闭」形同虚设）。 +/// `Widget::size_hint()` 不需要渲染器就能问，所以这条能在单测里跑：卡片层若声明 +/// `Fill`/`Fill`，就等于「命中区 = 整窗」。 +/// +/// **抓不住什么**：端到端指针派发（本仓没有事件 harness，`Element` 的 `layout`/`update` +/// 需要真渲染器）。所以这条守的是**结构属性**，不是「点一下真的关了」。 +#[test] +fn the_card_layer_is_card_sized_so_the_backdrop_can_be_clicked() { + use iced::Length; + + let mut app = headless(); + app.state.dialogs.push( + DialogSource::UserAction, + "t", + "b", + DialogKind::Confirm { + primary: "p".to_string(), + secondary: "s".to_string(), + }, + ); + let modal = { + let request = app.state.dialogs.current().expect("当前条"); + let view = DialogRequestView::of(request); + super::current(app.lang(), &view, None) + }; + let plane = super::view::card_plane(app.ui(), &modal); + let hint = iced::advanced::Widget::size_hint(plane.as_widget()); + // 任一维是 `Fill` 就意味着「跟随父级 = 整窗」（外层是 Fill 的居中容器）， + // 命中区于是变成整窗 —— 那正是 r1 抓到的原实现。 + assert_ne!( + hint.width, + Length::Fill, + "卡片层宽度不能 Fill（会撑成整窗）" + ); + assert_ne!( + hint.height, + Length::Fill, + "卡片层高度不能 Fill（会撑成整窗）" + ); +} + +/// P1-1：遮罩必须是**不透明预合成**，而且两档都**压暗**（深色档尤其）。 +/// +/// 抓得住 r1 实测的那个 p1：`Role::OnSurface @ 32%` 在深色档是「近白 @32%」⇒ 遮罩把整窗 +/// 提亮（实测 (9,21,28) → (129,138,145)）。这里用亮度直接判方向：遮罩必须比画布暗。 +/// +/// 抓不住：具体色值对不对（那是令牌层的事）。 +#[test] +fn the_backdrop_is_an_opaque_precomposite_and_darkens_both_flavors() { + use unlucky_design::color::{Role, SchemeFlavor}; + use unlucky_design::elevation::MaterialLayer; + use unlucky_design::typography::Platform; + + let luma = |color: iced::Color| 0.2126 * color.r + 0.7152 * color.g + 0.0722 * color.b; + + for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] { + let ui = crate::theme::Ui::with_platform(flavor, Platform::Windows, FAMILIES); + // 断言**视图真正用的那一份**（不是组件层的默认值）：改回「OnSurface @32%」这里就红。 + let backdrop = super::view::backdrop_color(&ui); + assert_eq!( + backdrop.a, 1.0, + "{flavor:?}：遮罩必须是不透明预合成（D27：CPU 档零半透明）" + ); + + let canvas = crate::theme::to_iced( + unlucky_design::color::Scheme::baseline(flavor) + .get(MaterialLayer::Canvas.surface_role()), + ); + assert!( + luma(backdrop) < luma(canvas), + "{flavor:?}：遮罩必须比画布暗（当前 lane {:.3} vs 画布 {:.3}）—— 用 Role::OnSurface 当遮罩会在深色档把整窗提亮", + luma(backdrop), + luma(canvas) + ); + assert_eq!(Role::Surface, MaterialLayer::Canvas.surface_role()); + } +} + +/// P2-4：启动那一拍的**事实**确实进了启动器日志（登记目录后一次刷出）。 +/// +/// 抓得住：记录函数被拆掉/改空（缓冲里就什么都没有）。 +/// 抓不住：`on_boot` 有没有调它 —— 那靠这条用例旁边的调用点与 `host/launch.rs` 的 `set_dir`， +/// 真机第一次崩溃才是最终验收闸门（复审与我的一致口径）。 +#[test] +fn boot_facts_are_recorded_into_the_launcher_log() { + // 与 `app/diag.rs` 的滚动闸串行：两条用例都动同一个进程级单例目录。 + let _guard = crate::app::diag::LOG_STATE_LOCK + .lock() + .unwrap_or_else(|error| error.into_inner()); + let dir = std::env::temp_dir().join(format!("ull-m187-bootlog-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&dir); + std::fs::create_dir_all(&dir).expect("建目录"); + unlucky_core::launch::launcher_log::set_dir(&dir); + + let app = headless(); + crate::app::update::boot_env::record_boot_log(&app); + + let path = dir.join(unlucky_core::launch::launcher_log::FILE_NAME); + let text = std::fs::read_to_string(&path).expect("launcher.log"); + assert!(text.contains("[boot] app boot"), "{text}"); + assert!(text.contains("theme="), "{text}"); + assert!(text.contains("window="), "{text}"); +} + +#[path = "tests/export.rs"] +mod export; diff --git a/crates/app-iced/src/app/dialog/tests/export.rs b/crates/app-iced/src/app/dialog/tests/export.rs new file mode 100644 index 0000000..8fd2d21 --- /dev/null +++ b/crates/app-iced/src/app/dialog/tests/export.rs @@ -0,0 +1,85 @@ +//! 导出的用例：真的落盘、真的报字节数、真的在有截断时说一句。 +//! +//! 从 `tests.rs` 拆出（那个文件贴着 400 行硬线）。共用父模块的 `report()` 夹具。 + +use unlucky_i18n::Lang; + +use super::report; +use crate::app::dialog::export; + +/// 导出：真的落盘、真的报出路径与字节数（**没有 crash-report 也要能导出**）。 +#[test] +fn export_writes_a_bundle_even_without_a_crash_report() { + let root = std::env::temp_dir().join(format!("ull-m187-export-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&root); + std::fs::create_dir_all(root.join("logs")).expect("建目录"); + std::fs::write(root.join("logs").join("launcher.log"), "[launch] boom\n").expect("写日志"); + + let mut spec_report = report(false, vec!["Error: boom".to_string()]); + spec_report.launcher_logs = Some(root.join("logs")); + spec_report.session_log = None; + spec_report.run_dir = None; + spec_report.version_json = None; + + let done = export::export(&spec_report, Lang::ZhCn); + let text = done.text.clone(); + assert!(done.ok, "{text}"); + assert_eq!(done.truncated, 0); + assert!(text.contains("已导出"), "{text}"); + assert!(text.contains("字节"), "{text}"); + + let exports = root.join("logs").join("exports"); + let files: Vec<_> = std::fs::read_dir(&exports) + .expect("导出目录") + .filter_map(Result::ok) + .collect(); + assert_eq!(files.len(), 1, "一次导出只该落一个包"); + let size = files[0].metadata().expect("元数据").len(); + assert!(size > 0, "包不该是空文件"); + assert!( + text.contains(&size.to_string()), + "报出来的字节数要与磁盘一致：{text} / {size}" + ); +} + +/// P3-4：`truncated > 0` 时**界面上那一句**真的出现（r2 复审登记的那条没有用例）。 +/// +/// 抓得住：把 `Exported.text` 里「有文件被截断」那句删掉/短路（变异证明见报告）。 +/// 抓不住：那句话排版好不好看（视觉）。 +#[test] +fn a_truncated_export_says_so_in_the_notice() { + use unlucky_core::launch::crash_bundle::MAX_ENTRY_BYTES; + + let root = std::env::temp_dir().join(format!("ull-m187-trunc-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&root); + std::fs::create_dir_all(root.join("logs")).expect("建目录"); + std::fs::create_dir_all(root.join("game").join("logs")).expect("建目录"); + std::fs::write(root.join("logs").join("launcher.log"), "boot\n").expect("写日志"); + + // 略超上限的 latest.log：必须用**真实日志行**填充 —— 同一字符的 4 MiB 会被 + // 「长不透明串」脱敏规则整段替换成占位符，长度就不超限了（那测的是脱敏不是截断）。 + let line = "2026-11-08T15:30:12.441Z [Render thread/INFO]: loading chunk\n"; + let mut big = String::new(); + while big.len() < usize::try_from(MAX_ENTRY_BYTES).expect("常数") + 256 { + big.push_str(line); + } + std::fs::write(root.join("game").join("logs").join("latest.log"), &big).expect("写大日志"); + + let mut report = report(false, Vec::new()); + report.launcher_logs = Some(root.join("logs")); + report.run_dir = Some(root.join("game")); + report.session_log = None; + report.version_json = None; + + let done = export::export(&report, Lang::ZhCn); + assert!(done.ok, "{}", done.text); + assert_eq!( + done.truncated, 1, + "这份 latest.log 必须真的被截断（>4 MiB）" + ); + assert!( + done.text.contains("已截断"), + "界面上没有说「有文件被截断」：{}", + done.text + ); +} diff --git a/crates/app-iced/src/app/dialog/view.rs b/crates/app-iced/src/app/dialog/view.rs new file mode 100644 index 0000000..d96c2e7 --- /dev/null +++ b/crates/app-iced/src/app/dialog/view.rs @@ -0,0 +1,299 @@ +//! 模态层的控件树：**遮罩 + 卡片 + 主/次按钮**，正文与路径全部来自 [`super::Modal`]。 +//! +//! ## 命中语义（为什么点遮罩能关、点卡片不关） +//! +//! `iced::widget::Stack` 的 `update` 从上往下（后画的先收）派发，遇到 `shell.is_event_captured()` +//! 立刻停。所以三层的顺序是： +//! +//! ```text +//! stack![ 页面树, 遮罩（mouse_area→Dismiss，整窗）, 居中容器（透明）→ opaque(卡片) ] +//! ``` +//! +//! 卡片那层用 `opaque` 把卡片内的左键按下**吃掉**（[`super::Message`] 不需要再有一条专用 +//! 消息），于是点卡片里的空白不会冒到遮罩去关框；卡片里的按钮自己会先捕获。 +//! **`opaque` 只包卡片**是这条语义成立的前提：包住整窗居中容器的话，命中区就变成整窗， +//! 遮罩永远收不到按下（r1 复审 P2-1 抓到的原实现）。 + +use iced::widget::text::LineHeight; +use iced::widget::{button, column, container, mouse_area, row, scrollable, text, Space}; +use iced::{Alignment, Background, Border, Color, Element, Font, Length, Pixels, Shadow}; + +use unlucky_design::color::Role; +use unlucky_design::component_map::Component; +use unlucky_design::elevation::MaterialLayer; +use unlucky_design::spacing::Space as Sp; +use unlucky_design::typography::TypeRole; + +use crate::app::components::buttons; +use crate::app::components::feedback::dialog::scrim; +use crate::app::components::feedback::panel::DialogGeometry; +use crate::pages::frame; +use crate::theme::Ui; + +use super::super::message::Message; +use super::{Message as DialogMessage, Modal}; + +/// 卡片内**滚动区**高度（详情 + 路径在这里滚；页脚按钮永远在卡片里）。 +const SCROLL_HEIGHT: f32 = 300.0; +/// 有导出结论时滚动区让出的高度（那一段会多占两行，不让就只能压扁页脚按钮）。 +const SCROLL_HEIGHT_WITH_NOTICE: f32 = 210.0; +/// 卡片最大高（兜底：不许把边框撑出屏幕）。 +const CARD_HEIGHT: f32 = 660.0; + +/// 把模态层叠在 `base` 上（没有弹窗时由调用方原样返回 `base`，这里是纯叠加）。 +/// +/// ## 三层的命中语义（r1 复审 P2-1 的修法） +/// +/// ```text +/// stack![ 页面树, 遮罩(mouse_area→Dismiss, 整窗), 居中容器(透明) → opaque(卡片) ] +/// ``` +/// +/// 关键在于**卡片那层只有卡片那么大**：`opaque(卡片)` 的命中区就是卡片本身，点卡片里 +/// 只会被它吃掉（`shell.capture_event`），点卡片外则**继续往下走**到遮罩 → `Dismiss`。 +/// 反例（r1 抓到的原实现）：`mouse_area(整窗居中容器).on_press(Swallow)` —— 整窗都在它 +/// 的 bounds 里，任何一次卡片外点击都先被它捕获，遮罩永远收不到，于是「点遮罩关闭」 +/// 只存在于注释里。 +pub(crate) fn layer<'a>( + ui: &'a Ui, + base: Element<'a, Message>, + modal: &'a Modal, +) -> Element<'a, Message> { + let backdrop = mouse_area( + container(Space::new()) + .width(Length::Fill) + .height(Length::Fill) + .style(move |_theme| container::Style { + background: Some(Background::Color(backdrop_color(ui))), + ..container::Style::default() + }), + ) + .on_press(Message::Dialog(DialogMessage::Dismiss)); + + // 透明的一层只负责居中；会吃点击的 `opaque` 只包卡片。 + let centered = container(card_plane(ui, modal)) + .width(Length::Fill) + .height(Length::Fill) + .align_x(Alignment::Center) + .align_y(Alignment::Center) + .padding(ui.space(Sp::X6)); + + iced::widget::stack![base, backdrop, centered].into() +} + +/// 遮罩色：**组件层那一份不透明预合成**（黑 @0.32 叠在画布上）。 +/// +/// 为什么不自己拿 `Role::OnSurface` 加 α：它在深色档是 **tone 90（近白）**，32% 铺上去会把 +/// 整窗**提亮**（r1 复审实测 (9,21,28) → (129,138,145)）；而且 α 混色在 wgpu/tiny-skia 两档 +/// 合成口径不同（linear vs sRGB），D27 要求 CPU 档零半透明。组件层 [`scrim`] 两件事都解决了。 +/// +/// 单独成函数是为了让 [`super::tests`] 断言**视图真正用的那一份**（P1 的守卫）。 +pub(super) fn backdrop_color(ui: &Ui) -> Color { + scrim(ui) +} + +/// 卡片层：`opaque` 让「卡片内的点击」被吃掉，不再冒到遮罩（点遮罩才关）。 +/// +/// 可见性放宽到 `pub(super)` 只为让 [`super::tests`] 能断言它的 `size_hint`（P2-1 的守卫）。 +pub(super) fn card_plane<'a>(ui: &'a Ui, modal: &'a Modal) -> Element<'a, Message> { + iced::widget::opaque(card(ui, modal)) +} + +/// 卡片本体（**尺寸 = 内容**，不声明 `Fill` —— 见 [`layer`] 的命中语义）。 +fn card<'a>(ui: &'a Ui, modal: &'a Modal) -> Element<'a, Message> { + // 几何全部走组件层（r1 复审 P1 的纪律项：别绕过现成的 Dialog 档）。 + let geometry = DialogGeometry::of(ui); + let shape = Component::Dialog.spec().shape; + + // 头（标题 + 三句正文）与脚（按钮）**固定**，中间那段滚——按钮滚出屏幕等于功能不存在 + // （视觉复审在日志页踩过同一坑：诊断卡把摘要页脚顶出去了）。 + let mut header = column![].spacing(ui.space(Sp::X2)).width(Length::Fill); + header = header.push(role( + ui, + TypeRole::HeadlineSmall, + true, + modal.title.as_str(), + )); + for line in &modal.body { + header = header.push(wrapped(ui, line.as_str(), ui.color(Role::OnSurface))); + } + + let mut middle = column![].spacing(ui.space(Sp::X2)).width(Length::Fill); + if let Some(card) = &modal.card { + // **详细说明在前、路径在后**：用户先要知道「发生了什么」，再要「文件在哪」。 + if card.expanded { + if let Some(title) = &card.detail_title { + middle = middle.push(role(ui, TypeRole::LabelMedium, false, title.as_str())); + } + for line in &card.detail_lines { + middle = middle.push(mono(ui, line.clone())); + } + middle = middle.push(frame::divider(ui).map(Message::Page)); + } + for (index, (label, path)) in card.paths.iter().enumerate() { + middle = middle.push( + button( + column![ + role(ui, TypeRole::LabelMedium, false, label.as_str()), + mono(ui, path.clone()), + ] + .spacing(0.0) + .width(Length::Fill), + ) + .width(Length::Fill) + .padding(0) + .style(|_theme, _status| button::Style { + background: None, + text_color: Color::TRANSPARENT, + border: Border::default(), + shadow: Shadow::default(), + snap: true, + }) + .on_press(Message::Dialog(DialogMessage::CopyPath(index))), + ); + } + } + + let mut footer = column![].spacing(ui.space(Sp::X1)).width(Length::Fill); + if let Some(notice) = &modal.notice { + footer = footer.push(wrapped(ui, notice.as_str(), ui.color(Role::Primary))); + } + footer = footer.push(actions(ui, modal)); + + // 中间那段给**定高**预算：`Shrink` 会让滚动区按内容高排版，把页脚顶到卡片外面 + // （实测第一版就是这样：导出/关闭两个按钮整排不可见）。 + let body = if modal.card.is_some() { + column![ + header, + scrollable(middle).height(Length::Fixed(if modal.notice.is_some() { + SCROLL_HEIGHT_WITH_NOTICE + } else { + SCROLL_HEIGHT + })), + frame::divider(ui).map(Message::Page), + footer, + ] + } else { + column![header, frame::divider(ui).map(Message::Page), footer,] + } + .spacing(ui.space(Sp::X3)) + .width(Length::Fill); + + // 宽度取官方**上限** 560（`DialogGeometry::max_width`）而不是本项目默认 480： + // 崩溃卡片多两行路径 + 三枚辅助按钮，480 会把主按钮压成竖排（实测过）。 + // 边界：组件层日后若改宽度，这里不会跟（已记 P3 台账）。 + container(body) + .width(Length::Fixed(geometry.max_width)) + .max_height(CARD_HEIGHT) + .padding(geometry.padding) + .style(move |_theme| container::Style { + background: Some(Background::Color(ui.layer(MaterialLayer::Overlay))), + border: ui.outlined(shape), + ..container::Style::default() + }) + .into() +} + +/// 底部按钮区：**两行**——辅助操作（开文件夹 / 复制路径 / 展开）在上，主次按钮在下靠右。 +/// +/// 为什么分两行：五个按钮塞一行在 560 的卡宽里会把主按钮压成竖排（实测第一版就是这样， +/// 「导出诊断包」被挤成两行单字）。 +fn actions<'a>(ui: &'a Ui, modal: &'a Modal) -> Element<'a, Message> { + let mut column_actions = column![].spacing(ui.space(Sp::X2)).width(Length::Fill); + + if let Some(card) = &modal.card { + column_actions = column_actions.push( + row![ + buttons::outlined( + ui, + buttons::Button::new( + card.actions[1].as_str(), + Message::Dialog(DialogMessage::OpenFolder), + ), + ), + buttons::outlined( + ui, + buttons::Button::new( + card.actions[2].as_str(), + Message::Dialog(DialogMessage::CopyPaths), + ), + ), + buttons::text( + ui, + buttons::Button::new( + card.toggle.as_str(), + Message::Dialog(DialogMessage::Toggle), + ), + ), + ] + .spacing(ui.space(Sp::X2)) + .align_y(Alignment::Center), + ); + } + + let mut line = row![Space::new().width(Length::Fill)].spacing(ui.space(Sp::X2)); + if let Some(secondary) = &modal.secondary { + line = line.push(buttons::text( + ui, + buttons::Button::new( + secondary.as_str(), + Message::Dialog(DialogMessage::Secondary), + ), + )); + } + if !modal.blocking_progress { + line = line.push(buttons::filled( + ui, + buttons::Button::new( + modal.primary.as_str(), + Message::Dialog(DialogMessage::Primary), + ), + )); + } + column_actions.push(line.align_y(Alignment::Center)).into() +} + +/// 令牌排版档的文字（`pages::frame` 的那一套，映射成本层的消息类型）。 +fn role<'a>( + ui: &'a Ui, + role: TypeRole, + emphasized: bool, + content: &'a str, +) -> Element<'a, Message> { + frame::text_role( + ui, + role, + emphasized, + content, + ui.color(Role::OnSurfaceVariant), + ) + .map(Message::Page) +} + +/// 等宽文字（路径 / 堆栈 / 捕获输出——这些必须能一眼看出字符边界）。 +fn mono<'a>(ui: &'a Ui, content: String) -> Element<'a, Message> { + let style = ui.style(TypeRole::BodySmall); + text(content) + .size(style.size_px) + .line_height(LineHeight::Absolute(Pixels(style.line_height_px))) + .font(Font { + family: iced::font::Family::Name(ui.families().mono), + ..Font::DEFAULT + }) + .color(ui.color(Role::OnSurface)) + .width(Length::Fill) + .wrapping(iced::widget::text::Wrapping::WordOrGlyph) + .into() +} + +/// 正文一段：令牌排版档 + 按词折行（长路径只按词折会把卡片顶破）。 +fn wrapped<'a>(ui: &'a Ui, content: &'a str, color: Color) -> Element<'a, Message> { + let style = ui.style(TypeRole::BodyMedium); + text(content) + .size(style.size_px) + .line_height(LineHeight::Absolute(Pixels(style.line_height_px))) + .font(ui.font_of(style)) + .color(color) + .width(Length::Fill) + .wrapping(iced::widget::text::Wrapping::WordOrGlyph) + .into() +} diff --git a/crates/app-iced/src/app/logs_folder.rs b/crates/app-iced/src/app/logs_folder.rs new file mode 100644 index 0000000..25ca4ab --- /dev/null +++ b/crates/app-iced/src/app/logs_folder.rs @@ -0,0 +1,121 @@ +//! 「日志文件夹」在 app 侧的唯一解析口（M188）：路径从哪来、点了按钮之后开哪个目录。 +//! +//! ## 为什么不在页面里现拼路径 +//! +//! 日志根 = `<启动器数据目录>/logs`，而「启动器数据目录」是三模式解析（便携 / 标准 / 自定义） +//! 的结果。那条解析链只有一份实现（`core::platform::data_dir` + `presenter::settings_bridge`）， +//! 页面若自己拼 `exe_dir/.ULL/logs`，标准模式与自定义模式的用户就会看到一个**不存在的目录**。 +//! +//! 本模块只做两件事： +//! +//! 1. 从设置桥给定的 `config/launcher.json` 反推 ``，再用 `LauncherLayout::logs()` 取分区 +//! （分区名只从 core 的 `layout` 来，不手拼字符串）； +//! 2. 打开前先确认目录真的在（不在就建），失败时给出的文本**带完整路径**——用户至少能照着去翻。 +//! +//! ## 谁来登记 +//! +//! `App::new` 拿到设置桥之后调 [`register`]：那是本进程唯一知道「实际生效的数据根」的地方 +//! （`--data-dir` 也在这里生效）。没登记时（`pages_demo` 出图通道、单测）退回 +//! `platform::data::layout()`——同一份解析链的缓存版本。 + +use std::path::{Path, PathBuf}; +use std::sync::OnceLock; + +use unlucky_core::platform::layout::LauncherLayout; +use unlucky_presenter::settings_bridge::SettingsBridge; + +static LOGS_DIR: OnceLock> = OnceLock::new(); + +/// `/config/launcher.json` → `/logs`（**只有**这一条形状，别处不许手拼）。 +pub(crate) fn logs_dir_of(config: &Path) -> Option { + let home = config.parent()?.parent()?; + Some(LauncherLayout::new(home).logs()) +} + +/// 登记本进程的日志目录（`App::new` 在第一帧之前调一次；重复调用以**第一次**为准）。 +pub(crate) fn register(bridge: &SettingsBridge) { + let _ = LOGS_DIR.set(bridge.path().and_then(logs_dir_of)); +} + +/// 本进程的日志目录。 +/// +/// - 已登记且解析出来 ⇒ 那条； +/// - 已登记但解析不出来（内存态桥）⇒ `None`：页面照实说「数据根没解析出来」，不猜一个目录； +/// - 还没登记（`pages_demo` / 单测）⇒ 退回 `platform::data::layout()`。 +pub(crate) fn logs_dir() -> Option { + match LOGS_DIR.get() { + Some(known) => known.clone(), + None => crate::platform::data::layout().map(|layout| layout.logs()), + } +} + +/// 确保日志目录存在（不在就建），返回给用户看的路径。 +/// +/// 失败文本里**带完整路径**：界面把这段话原样显示出来，用户能复制去自己找。 +pub(crate) fn prepare(dir: &Path) -> Result { + std::fs::create_dir_all(dir) + .map_err(|error| format!("{}（这个目录建不出来：{error}）", dir.display()))?; + if !dir.is_dir() { + return Err(format!("{}（这个路径不是一个目录）", dir.display())); + } + Ok(dir.to_path_buf()) +} + +/// 打开日志文件夹：解析 → 确保存在 → 交给平台打开器。 +/// +/// # Errors +/// +/// 返回的文本永远带路径（`...logs` 那一串），可以直接贴给用户/贴进 issue。 +pub(crate) fn open() -> Result { + let dir = logs_dir().ok_or_else(|| { + "日志目录：数据根没解析出来（启动器拿不到自己所在的目录；用 --data-dir 指定一个）" + .to_string() + })?; + let dir = prepare(&dir)?; + crate::app::dialog::export::open_dir(&dir)?; + Ok(dir) +} + +#[cfg(test)] +mod tests { + use super::*; + + /// 落点形状：`/config/launcher.json` → `/logs`。 + /// + /// 变异证明：把 `logs_dir_of` 里的 `LauncherLayout::logs` 换成 `cache`，这条立刻红。 + #[test] + fn the_log_folder_is_the_logs_partition_next_to_config() { + let config = PathBuf::from("/tmp/ull-home/.ULL/config/launcher.json"); + assert_eq!( + logs_dir_of(&config), + Some(PathBuf::from("/tmp/ull-home/.ULL/logs")) + ); + // 少了 config 那一层就没有 `` 可言：宁可不猜。 + assert_eq!(logs_dir_of(Path::new("launcher.json")), None); + } + + /// **目录真的存在**（守门③）：`prepare` 在不在时把它建出来，并且返回同一个路径。 + /// + /// 变异证明：删掉 `create_dir_all` 那一行，`is_dir` 立刻为假。 + #[test] + fn prepare_creates_the_folder_and_reports_the_same_path() { + let root = std::env::temp_dir().join(format!("ull-logs-folder-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&root); + let dir = root.join(".ULL/logs"); + assert!(!dir.is_dir(), "夹具目录不该已经存在"); + let prepared = prepare(&dir).expect("应当建得出来"); + assert_eq!(prepared, dir); + assert!(dir.is_dir(), "打开之前必须真的存在"); + std::fs::remove_dir_all(&root).ok(); + } + + /// 失败文本带路径（「不许只在成功时可用」）。 + #[test] + fn a_failure_names_the_path_it_could_not_use() { + let file = std::env::temp_dir().join(format!("ull-logs-notadir-{}", std::process::id())); + std::fs::write(&file, b"x").expect("写夹具"); + let error = prepare(&file).expect_err("一个文件不是目录"); + assert!(error.contains(&file.display().to_string()), "{error}"); + std::fs::remove_file(&file).ok(); + } +} diff --git a/crates/app-iced/src/app/message.rs b/crates/app-iced/src/app/message.rs new file mode 100644 index 0000000..f9ec644 --- /dev/null +++ b/crates/app-iced/src/app/message.rs @@ -0,0 +1,108 @@ +//! 应用消息：单一大枚举。 +//! +//! 纪律：本枚举是**唯一**的消息类型，`view` 产出的所有回调都必须落到这里；组件库与页面层 +//! 各自用自己的 `Message`（组件契约 §2 的泛型纪律），由 `view` 做一次 `.map` 接上。 +//! +//! ## 三类输入（M90） +//! +//! | 来源 | 变体 | 落点 | +//! |---|---|---| +//! | 窗口/框架 | `Boot` / `WindowReady` / `Window` / `Frame` / `Captured` / 三个 caption | [`super::update`] 直接处理 | +//! | **时间** | `Frame`（忙碌，33 ms 闸门）+ `Heartbeat`（空闲，1 Hz） | presenter 的 TICK 节拍：`backend.tick` + `drain_events` + `apply` | +//! | **页面** | `Page(pages::Message)` | 导航 → `AppState::navigate`；启动/停止 → `AppCommand` | + +use iced::{window, window::Direction}; + +use unlucky_presenter::router::Route; + +use crate::pages; +use crate::shell::NavItem; + +use super::components; + +/// 消息（单一大枚举）。 +#[derive(Debug, Clone)] +pub enum Message { + /// 启动即发一次（`iced::application` 的 boot 闭包）。 + Boot, + /// `window::latest()` 的结果。 + WindowReady(Option), + /// 系统主题探测结果（只可能在**交互模式**出现，截图模式必有主题）。 + 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), + /// 页面消息（导航 / 启动 / 停止 / 占位动作）。 + Page(pages::Message), + /// **AI 助手栏 / 独立页**的消息（M104：三档状态、输入框、拖拽、键盘）。 + /// + /// 为什么不走 `pages::Message`：助手栏是**外壳级视图**（它挂在任何页面右边），不是某一页的 + /// 消息；塞进页面枚举还要动 `app/update/page_messages.rs` 的穷尽 match（那个文件正被未合的 + /// M101 改），绕开它就少一处 rebase 面。落点是 `app/update/agent.rs`。 + Agent(crate::shell::agent::Message), + /// 外壳导航轨点选（`src/shell/nav.rs` 的回调仍然发这一条；收到就翻成同一个路由跳转）。 + /// + /// M90 起产品界面用 `pages` 里的真 `NavigationRail`，这条变体是给**外壳回退路径** + /// （`Route::Agent`）留的——`shell` 不在本 mission 的 scope 里，不能删它的消息。 + Select(NavItem), + /// 按下标题栏 → 拖窗。 + DragWindow, + /// 边缘热区：开始缩放（方向由坐标决定）。 + ResizeStart(Direction), + /// 最小化。 + Minimize, + /// 最大化/还原。 + ToggleMaximize, + /// 关窗退出。 + Close, + /// 截图回来了。 + Captured(window::Screenshot), + /// gallery（组件库 harness）里的演示交互。 + Demo(components::gallery::DemoMessage), + /// 模态对话框（M187）：主/次按钮、遮罩、展开、导出、打开文件夹、复制路径。 + Dialog(super::dialog::Message), + /// 导入已有版本向导（M223）：打开 / 选版本 / 选目标 / 预检 / 确认 / 关闭。 + /// + /// 落点是 `app/update/adopt.rs`。页面只发一条入口意图 + /// （`pages::Message::Action(pages::Action::Import)`），向导自己的四段状态都在这里收口。 + Adopt(super::adopt::AdoptMessage), +} + +/// 外壳导航项 → 路由（导航项只在一级页之间有对应；AI 项对应 [`Route::Agent`]）。 +/// +/// 这是 `NavItem → Route` 的**唯一**转换点：外壳（`src/shell/nav.rs`）与页面导航轨 +/// （`pages::NAV`）最终都落到同一个 `Route`，所以两条入口不会各走一套页面语义。 +pub(super) fn route_of(nav: NavItem) -> Route { + match nav { + NavItem::Instances => Route::Instances, + NavItem::Download => Route::Download, + NavItem::Logs => Route::Logs, + NavItem::Settings => Route::Settings, + NavItem::Ai => Route::Agent, + // 轨底头像位（M114）：账户是一级页，但**不在主序列**里 + NavItem::Account => Route::Accounts, + } +} + +/// 路由 → 外壳导航项（[`route_of`] 的逆；外壳 rail 与 caption 键都按它高亮）。 +/// +/// `Route::Detail(_)` 高亮「实例」（与 `Route::nav()` 同源）。 +pub(super) fn nav_item_of(route: &Route) -> NavItem { + match route { + Route::Instances | Route::Detail(_) => NavItem::Instances, + // M109：内容库与版本管理共用「下载」那一个导航项（B1 裁定） + Route::Download | Route::Content => NavItem::Download, + Route::Logs => NavItem::Logs, + Route::Settings => NavItem::Settings, + Route::Agent => NavItem::Ai, + Route::Accounts => NavItem::Account, + } +} diff --git a/crates/app-iced/src/app/mod.rs b/crates/app-iced/src/app/mod.rs new file mode 100644 index 0000000..4f428d9 --- /dev/null +++ b/crates/app-iced/src/app/mod.rs @@ -0,0 +1,75 @@ +//! Elm 三件套：`State` / `Message` / `update` + `view` 接线，以及启动序列。 +//! +//! 启动序列：①探测渲染后端并写 `ICED_BACKEND`（必须在 `run()` 之前，M60 Q1）→ ②求值字体栈 +//! （D28 前半）→ ③`iced::application(..).run()`（1180×760、无边框自绘标题栏）→ ④首个 `view()` +//! 打耗时；截图模式第 3 帧落盘后退出（无边框窗首帧可能是旧尺寸，M60 坑 #5）。 +//! +//! ## 为什么拆成目录（M90） +//! +//! 本文件原来是**单个 400 行的 `app.rs`**：正好卡在「单文件 ≤400 行、动它前必须先拆」的硬门槛上 +//! （AGENTS 的文件上限 + 本 mission 的第一条任务）。拆法与职责： +//! +//! | 文件 | 职责（**只做这一件事**） | +//! |---|---| +//! | [`state`] | [`App`] 字段 + 构造（presenter 三件在此持有）+ 主题切换 | +//! | [`message`] | [`Message`] 枚举与「导航项 → 路由」的翻译 | +//! | [`update`] | 全部 `Message` 分支 + 「用户动作 → `AppCommand`」的派发与事件回流 | +//! | [`subscription`] | 帧事件（截图）与 presenter 的 TICK 节拍 | +//! | [`view`] | `view` / `theme` / `title` | +//! | [`boot`] | [`run`]：后端探测 → 字体 → `iced::application(..)` | +//! +//! 拆分的每一步都保持**可观察行为不变**（截图四件套 `--screenshot` / `--screenshot-theme` / +//! `--screen=gallery` / `--diff` 出图逐字节相同），presenter 接线是在拆分**之后**另一步做的。 +//! +//! ## 组件库为什么还在本模块下声明 +//! +//! `src/lib.rs` 是五条组件线共用的文件，改它必然冲突；`#[path]` 保证物理路径仍是 +//! `src/components/`（组件目录自己的归属规则不变），逻辑路径仍是 `crate::app::components` +//! （组件源码里的文档与测试都按这个路径写）。 + +mod adopt; +mod appearance; +mod backend; +mod boot; +pub(crate) mod diag; +mod dialog; +pub(crate) mod logs_folder; +mod message; +mod state; +mod subscription; +mod update; +mod view; +mod window_alpha; + +#[cfg(test)] +mod tests; + +pub(crate) use boot::run; +pub use message::Message; + +// 组件库（D39）在本文件声明：`src/lib.rs` 是五条组件线共用的文件，改它必然冲突； +// `#[path]` 保证物理路径仍是 `src/components/`（组件目录自己的归属规则不变）。 +// +// M90：可见性从 `mod` 放到 `pub(crate) mod` —— 页面层（`src/pages/**`）要**用**真组件 +// （`components::buttons` / `navigation` / `divider`），而 `app` 不是它的父模块。 +// 只放开 crate 内可见，组件目录的归属规则一字不改。 +#[path = "../components/mod.rs"] +pub(crate) mod components; + +/// 验收窗口尺寸（1180×760 @100% DPI —— D30 的硬要求）。 +pub const WINDOW_SIZE: iced::Size = iced::Size { + width: 1180.0, + height: 760.0, +}; + +/// 产品名（自绘标题栏的标题；`'static` 好让 view 借用）。 +pub const APP_TITLE: &str = "Unlucky Launcher"; + +/// 窗口最小尺寸（再小骨架会挤坏：88 导航 + 页面留白 + 卡片）。 +const MIN_SIZE: iced::Size = iced::Size { + width: 880.0, + height: 560.0, +}; + +/// 截图落盘的帧号（见模块文档）。 +const CAPTURE_AT_FRAME: u32 = 3; diff --git a/crates/app-iced/src/app/state.rs b/crates/app-iced/src/app/state.rs new file mode 100644 index 0000000..318da94 --- /dev/null +++ b/crates/app-iced/src/app/state.rs @@ -0,0 +1,246 @@ +//! 应用状态：**只放字段与构造**，不放消息分支（那是 [`super::update`] 的事）。 +//! +//! ## presenter 三件（`crates/presenter/src/lib.rs` crate 文档 §4） +//! +//! | 字段 | 谁给 | 干什么 | +//! |---|---|---| +//! | `backend: Box` | [`build_backend`](unlucky_presenter::backend::build_backend) | 派发 [`AppCommand`](unlucky_presenter::dto::AppCommand)、收 [`AppEvent`](unlucky_presenter::dto::AppEvent) | +//! | `bridge: SettingsBridge` | [`SettingsBridge::open`](unlucky_presenter::settings_bridge::SettingsBridge::open) | 读一次外观/主题，之后每 N 拍问「文件变了吗」 | +//! | `state: AppState` | [`AppState::new`](unlucky_presenter::state::AppState::new) | **唯一**的状态写入口（`apply` / `navigate`） | +//! +//! `view: pages::Model` 是**展示转换的缓存**：presenter 快照 → 页面要画的东西。 +//! 它在**状态真的变了**时重建（[`App::view_dirty`] 门控，M90 r2/P2-1 起），不是每拍重建—— +//! 重建要把 N 个实例的名字/版本串克隆一遍，30 Hz 空转没有意义。缓存成字段是为了让 +//! `view(&self)` 能只借 `&self`：iced 的 `view` 签名不允许返回一棵借用局部变量的树。 +//! +//! ## 本文件只管「有哪些字段」 +//! +//! M119 起按功能拆出去（`state.rs` 当时正好 400 行、零余量）： +//! +//! | 子文件 | 内容 | +//! |---|---| +//! | [`construct`] | 两个构造器 + 字段初始化表 | +//! | [`refresh`] | [`App::refresh_view`]（快照 → 视图模型的唯一转换点） | +//! | [`theme`] | `Ui` 重算 / 主题档 / [`App::has_screenshot`] | +//! | [`boot_probe`] | 启动探针（`ULL_*` 取证开关与首帧日志） | + +use std::time::Instant; + +use iced::window; + +use unlucky_presenter::dto::Backend; +use unlucky_presenter::prefs::ThemeMode; +use unlucky_presenter::settings_bridge::SettingsBridge; +use unlucky_presenter::state::AppState; + +use crate::cli::Options; +use crate::pages; +use crate::theme::{Families, Ui}; +use crate::ui::lang::LangState; + +/// presenter 的 TICK 节拍（33 ms ≈ 30 fps）——**忙碌态**的节拍。 +/// +/// 与 Slint 版的 `TICK_MS` 同值：`backend.tick(..)` 的时间推进、toast 过期、 +/// `theme::config_poll_due` 的计数都按这个节拍走，两个 UI 版的时间语义因此一致。 +pub(super) const TICK_MS: u64 = 33; + +/// [`TICK_MS`] 的 `Duration` 形态。 +pub(super) const TICK: std::time::Duration = std::time::Duration::from_millis(TICK_MS); + +/// **空闲态**的低频心跳（1 Hz，M90 r3 / P2-2）。 +/// +/// 空闲时不能订阅 `window::frames()`：那条订阅会自持重绘循环（实测软件渲染约 500 帧/秒）， +/// 而空闲时唯一需要的时钟是「偶发一次」——外部 CLI / AI 工具改 `launcher.json` 后的热切 +/// （presenter 的 `theme::config_poll_due` 语义是 30 × 33 ms ≈ 1 秒一拍）。 +/// +/// 实现用的是 `Task::perform(async { sleep(1s) })` 的自续链：[`App::heartbeat`]。它每秒只唤醒 +/// 一次、只触发**一帧**重绘，而 `frames()` 是每秒几百帧。为什么不用 `iced::time::every`： +/// 它挂在 tokio/smol 后端下，本 crate 的执行器是 thread-pool（Cargo.toml 不在 scope）。 +/// +/// **M192 的第三条时钟不在这里**：动效（`components::motion`）也只在「有轨道」时借用帧订阅， +/// 最后一个轨道到期就清空 ⇒ 下一拍 [`App::needs_frames`] 自动退回这条 1 Hz 心跳。 +pub(super) const IDLE_TICK: std::time::Duration = std::time::Duration::from_secs(1); + +/// 派发指令后保持帧订阅的观察窗（见 [`App::watch_until`]）。 +/// +/// 3 秒够真 host 把「命令已受理」的第一条事件交回来；之后由「有 Busy/Running 实例」这个条件续订。 +pub(super) const WATCH_WINDOW: std::time::Duration = std::time::Duration::from_secs(3); + +mod boot_probe; +// M224: 出图取证用的 MODS 夹具（`ULL_MODS_FIXTURE`；产品路径零影响） +mod construct; +mod mods_shot; +mod refresh; +// M235: 出图取证用的 SAVES 夹具（`ULL_SAVES_FIXTURE=1`） +mod saves_shot; +mod theme; + +/// iced 侧的 presenter 接线层（M119）：物理目录 `src/presenter/`，逻辑名字在 `crate::app::state` 下。 +/// +/// 为什么用 `#[path]` 而不是在 `lib.rs` 加一行 `mod presenter;`：本 mission 的 scope 不含 +/// `lib.rs` / `app/mod.rs`，而 `shell::agent` 挂 `pages/agent/` 是同一个先例。没有第二份实现。 +#[path = "../presenter/mod.rs"] +pub(super) mod presenter; + +pub(crate) use boot_probe::{log_first_frame, STARTED}; + +/// 应用状态：UI 状态 + presenter 三件 + 展示转换缓存。 +pub struct App { + /// 启动参数（截图/主题/画面开关）。 + pub(super) options: Options, + /// 字体族（切主题时重建 [`Ui`] 要用）。 + pub(super) families: Families, + /// 令牌求值器（浅/深两套）。 + pub(super) ui: Ui, + /// 后端通道（真 host 或 mock）。 + pub(super) backend: Box, + /// 设置持久化桥。 + 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, + /// 窗口句柄（`window::latest()` 之后才有）。 + pub(super) window: Option, + /// 已画的帧数（截图闸门用）。 + pub(super) frames: u32, + /// 视图模型重建次数（P2-1 的可观测计数：空闲态 100 拍里必须是 0 增长）。 + pub(super) refreshes: u64, + /// 首屏快照到位后是否已经自动选中过第一行（list-detail 的桌面惯例，见 `update::auto_select`）。 + pub(super) auto_selected: bool, + /// 上一次看到的**中文字体下载状态**（M168）。 + /// + /// 下载在后台线程里推进，状态是一份进程级快照（`fonts::install::status`）。这里存一份是为了 + /// 「变了才重建视图模型」：设置页那一行因此自己会从「正在获取」翻成「已就绪 / 失败」， + /// 而空闲态不会为了它每拍白重建一次。 + pub(super) font_seen: crate::fonts::install::CjkInstall, + /// 窗口高度（背景图平铺网格的视口判据；宽度在 `width`）。 + pub(super) height: f32, + /// 外观运行期状态（M93）：面板 α / 背景图 / 配色来源 / 诊断。 + pub(super) appearance: pages::appearance::State, + /// 设置文件里那 8 个「UI 写入」外观字段的最近快照（写回时只改我们真改了的字段， + /// 没动过的字段原样保留；M250 起强调色也在「真改了」的那一列里）。 + pub(super) appearance_prefs: unlucky_presenter::prefs::AppearancePrefs, + /// 窗口句柄（`Message::WindowHandle` 之后才有；非 Windows 平台恒 `None`）。 + pub(super) hwnd: Option, + /// 设置页各组自己的运行期状态（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>`）。 + /// + /// **只留 UI 态**：会话内容 / 未读 / busy 在 `agent_host` 的 rail 上（M119 起）。 + pub(super) agent: crate::shell::agent::AgentUi, + /// AI 助手的 presenter 句柄（M119）：四个契约 + 事件队列 + 具名错误。 + /// + /// 为什么单独一份 `AppState` 而不是把 `state` 交给它：`Presenter` 的可写状态后门 + /// （`state_mut`）只在 presenter crate 的 `#[cfg(test)]` 里存在，而 `app/subscription.rs` + /// 等处仍要直读 `App.state`。所以口径是——**`App.state` 管除 rail 外的一切，这个句柄管 rail**； + /// `AppEvent::Agent` 只喂这里（`App.state.ai` 从此不再被读，也不再被写）。 + pub(super) agent_host: presenter::AgentHost, + /// 下载页的安装草稿（M105：选中版本 + 加载器 + 加载器版本 + 实例名）。 + /// + /// 为什么住在 `App` 而不是页面模型：`refresh_view` 每次事件都把 `self.view` 整棵重建， + /// 页面自己存不住「用户正在填但还没确认」的东西；这与分类筛选（`view.download.category`） + /// 是同一个理由、同一个做法。 + pub(super) download_draft: pages::InstallDraft, + /// 已经提示过的取消次数（M105）：`AppState::install_cancelled` 是「发生过几次取消」， + /// 这里是「其中几次已经弹过提示」。两者不等 ⇒ 弹一次 i18n 提示。 + pub(super) install_cancelled_seen: u64, + /// 已经提示过的启动收尾次数（M161）：`AppState::launch_ends` 是「收尾过几场」， + /// 这里是「其中几场已经弹过 Toast」。两者不等 ⇒ 弹一次（与 `install_cancelled_seen` 同构）。 + pub(super) launch_ends_seen: u64, + /// 已经提示过的启停失败（M224）：`(实例, 文件, 大类)`。同一条失败重复到达不重弹。 + /// + /// 为什么不用计数器（与上面两条不同）：失败是**并发可交错**的（A 的文件失败、B 的列表成功、 + /// A 又失败），计数差说明不了"哪一条没提示过"，三元组才是幂等键。 + pub(super) mods_failed_seen: Option<(String, String, unlucky_presenter::dto::ModFailureKind)>, + /// 内容库页的页面内选择（M109）：内容类型 / 选中项目 / 目标实例 / 关键词草稿。 + /// + /// 为什么在 `App` 而不是 presenter：这四样是「用户在这一屏上点了什么」，重建快照不该冲掉； + /// 而检索条件与结果（会跨页存活、要被事件写）在 `AppState::content`。放进 `view` 模型也 + /// 不行——`refresh_view` 每次都用快照重建模型，选择会被冲回默认值。 + pub(super) content: pages::content::PageState, + /// 账户页的**表单状态**（三条轨道的输入串；密码只活在这一次请求里）。 + pub(super) account_form: pages::account::Form, + /// 账户页视图模型（与 `view` 同一条「状态变了才重建」的门控）。 + pub(super) account: pages::account::Page, + /// 实例页「启动参数」区的表单（M157）：五项 + 脏标记 + 绑定的实例 id。 + /// + /// 住在 `App` 的理由与 `download_draft` 完全一致：`refresh_view` 每次都整棵重建 + /// `pages::Model`，用户正在输入的内容存不到视图模型里。重播种点在 + /// [`App::refresh_view`]（`LaunchForm::sync`，换实例必重播种、同实例的脏草稿不覆盖）。 + pub(super) launch_form: pages::LaunchForm, + /// 实例页「导入已有版本」向导的表单态（M223）：选中版本 / 展示名 / 目标档 / 在等回程。 + /// + /// 住在 `App` 的理由与 `launch_form` 一致：向导跨帧（扫描 → 选 → 预检 → 确认）， + /// 而候选/预检/失败/完成这些**事件真相**在 `AppState.adopt`（presenter），不在这里。 + pub(super) adopt_form: super::adopt::Form, + /// 启动失败弹窗的**事实**（M187）：与 `state.dialogs` 里的当前条按 id 绑定。 + /// + /// 为什么事实不塞进 `DialogRequest`：那是 presenter 的公共 DTO，弹窗与「这次失败的现场」 + /// 是两件事——队列管弹窗的排队与按钮，卡片管证据（路径 / 崩溃摘要 / 捕获输出）。 + pub(super) dialog_card: Option, + /// 弹窗的**视图模型**（在 [`App::refresh_view`] 里重建；`view()` 只借它）。 + /// + /// 为什么不像页面那样现算：`Element` 借字符串，现算的模型是局部变量，`view()` 一返回就 + /// 悬空（编译期就过不去）。与 `view` / `account` 两张缓存同一条理由、同一个门控。 + pub(super) dialog_model: Option, + /// 皮肤/头像解码缓存（M114：同一张皮肤只解一次）。 + pub(super) avatars: pages::account::avatar::Cache, + /// 上一次**真下发过**的圆角判定指纹（M116 r1 复审 P2-4：判定没变就不重下、不重记日志）。 + /// + /// `None` = 还没下发过（首屏 `boot` 那一次）。指纹类型见 + /// [`crate::platform::win32::corner::CornerApplied`]。 + pub(super) corner_applied: Option, +} + +impl App { + /// iced 侧的**设置组快照**（M201）：presenter 的 `CoreEvent::SettingsChanged` 回流进来的那一份。 + /// + /// 真值只有一份——presenter 的 `AppState::settings_groups`（`apply_core` 是它唯一的写入口， + /// 由 host 的 `refresh_all` / `SetSetting` 分支发出来）。这里**不另存一个字段**：那会变成第二份 + /// 真相，两份在 `pump` 之间必然有一步不一致（而「界面上是旧值、盘上是新值」正是本 mission 要 + /// 消灭的形状）。要画的那一份是 [`pages::Model::settings`]（`refresh_view` 里从同一个字段克隆）。 + /// + /// `#[cfg(test)]`：产品路径不需要这个入口（页面拿的是 `Model.settings`，同一份数据的投影）， + /// 断言需要它——「App 认的值变了吗」必须能直接从 App 上问，不能去问页面模型（那是下游）。 + #[cfg(test)] + pub(crate) fn settings_snapshot(&self) -> &[unlucky_presenter::dto::SettingGroupView] { + &self.state.settings_groups + } +} 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..1cfcd75 --- /dev/null +++ b/crates/app-iced/src/app/state/boot_probe.rs @@ -0,0 +1,61 @@ +//! 启动期取证：后端选项的换算 + 首帧耗时那一行日志。 +//! +//! 从 `app/state.rs` 拆出（rebase 到 5adac23 之后 `state.rs` 顶到 401 行）。这两件事都属于 +//! 「进程启动那一刻记了什么」，与 `App` 的状态机无关；`state.rs` 只留 `pub(super) use` 再导出， +//! 于是 `app/boot.rs`（`use super::state::STARTED`）与 `app/view.rs`（`log_first_frame`）的既有路径一字未变。 + +use crate::app::diag::diag; +use std::sync::atomic::{AtomicBool, Ordering}; +use std::sync::OnceLock; +use std::time::Instant; + +use crate::cli::Options; +use unlucky_presenter::backend::AppOptions; + +/// 进程内「run() 开始」的时刻（首帧耗时基线）。 +pub(crate) static STARTED: OnceLock = 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 ` 不会往那个目录写东西。 + data_root: options.data_dir.clone(), + mock: options.screenshot.is_some() && !real_host_in_screenshot(), + } +} + +/// 取证开关 `ULL_SCREENSHOT_REAL_HOST=1`：让**截图通道**接真 host（默认关）。 +/// +/// ## 为什么需要它（M201） +/// +/// 截图通道恒 `mock: true`（D30：同一份代码出同一张图），而 `MockBackend` **不发** +/// `CoreEvent::SettingsChanged` ⇒ 设置页拿不到任何真值，只能拍演示行。可「设置页里改了就生效」 +/// 这件事的正脸图**必须带真值**：M193 用户的投诉就是「图上有 8 threads，追下去是假的」。 +/// 这条开关把出图的**数据源**换成真 host（`--data-dir` 指一个临时根），渲染通道与落盘一字不改。 +/// +/// ## 边界（别把它当产品行为） +/// +/// - 默认关；开了它就不再满足 D30 的可复现（数据来自磁盘，两台机器会不同），所以**只用于取证**； +/// - 它只改 `mock` 这一位，不碰任何业务分支（`build_backend` 的其余两条路仍然照旧）； +/// - 与 `ULL_START_ROUTE` / `ULL_SETTINGS_GROUP` 同一族：只影响这一次进程。 +fn real_host_in_screenshot() -> bool { + std::env::var("ULL_SCREENSHOT_REAL_HOST") + .ok() + .is_some_and(|raw| raw.trim() == "1") +} + +/// 首帧耗时日志（只在第一次 `view()` 打一行）。 +pub(crate) fn log_first_frame() { + if FIRST_FRAME_LOGGED.swap(true, Ordering::Relaxed) { + return; + } + if let Some(started) = STARTED.get() { + diag!( + "[boot] first frame in {:.0} ms（run() 开始 → 首次 view，含后端探测与字体扫描）", + started.elapsed().as_secs_f64() * 1000.0 + ); + } +} 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..6a9c2ff --- /dev/null +++ b/crates/app-iced/src/app/state/construct.rs @@ -0,0 +1,185 @@ +//! `App` 的两个构造器（从 `state.rs` 搬出来守 400 行硬线；M119 拆，纯搬不改）。 +//! +//! | 构造器 | 谁用 | 碰不碰磁盘 | +//! |---|---|---| +//! | [`App::new`](super::App::new) | 生产（`main` → `boot`） | 按启动参数选后端 + 打开设置桥 | +//! | [`App::with_presenter`](super::App::with_presenter) | 单测（后端与桥都由调用方给） | **不碰** | +//! +//! 两个都走 `with_presenter`：生产路径只是先造好后端与桥。**字段初始化表**也在这一个文件里 +//! （构造 = 字段表 + 三件外部依赖），加字段时只改这一处。 + +use iced::window; + +use unlucky_design::color::SchemeFlavor; +use unlucky_presenter::backend::{build_backend, config_path}; +use unlucky_presenter::dto::Backend; +use unlucky_presenter::prefs::ThemeMode; +use unlucky_presenter::settings_bridge::SettingsBridge; +use unlucky_presenter::state::AppState; + +use crate::cli::Options; +use crate::pages; +use crate::theme::{Families, Ui}; +use crate::ui::lang::LangState; + +use super::super::WINDOW_SIZE; +use super::boot_probe::app_options; +use super::App; + +impl App { + /// 生产构造：按启动参数选后端、打开设置桥。 + /// + /// **截图通道强制 mock**：出图要可复现（D30），真 host 会按本机盘上的实例清单画面， + /// 同一份代码在两台机器上出不了同一张图。交互模式走真 host（数据根解析不出来时 + /// [`build_backend`] 自己退回 mock）。 + pub(in crate::app) fn new(options: Options, families: Families, flavor: SchemeFlavor) -> Self { + let backend = build_backend(&app_options(&options)); + // P2-2：设置桥必须与后端指向**同一个数据根**。早先这里无条件 `SettingsBridge::open()` + // （按便携配置解析），于是 `--data-dir X` 会出现「实例来自 X、主题/设置读写默认根」的一进程 + // 两个数据根。Slint 版是同一条口径：`app/src/ui_bind.rs` 的 + // `Some(root) => SettingsBridge::with_path(config_path(root))`。 + let bridge = match &options.data_dir { + Some(root) => SettingsBridge::with_path(config_path(root)), + None => SettingsBridge::open(), + }; + // M188：日志目录也在这一拍登记——它是从**同一份**设置桥反推的（`--data-dir` 同样生效）， + // 所以设置页显示的路径与 `launcher.log` 的真实落点不会各说各话。 + crate::app::logs_folder::register(&bridge); + Self::with_presenter(options, families, flavor, backend, bridge) + } + + /// 注入式构造（单测用：后端与桥都由调用方给，**不碰磁盘**）。 + pub(in crate::app) fn with_presenter( + options: Options, + families: Families, + flavor: SchemeFlavor, + backend: Box, + bridge: SettingsBridge, + ) -> Self { + let width = WINDOW_SIZE.width; + let height = WINDOW_SIZE.height; + // 主题档：截图通道**不读机器配置**（D30：同一份代码在两台机器上要出同一张图）—— + // 由 `--screenshot-theme` 钉死（浅 → Silver / `light`，深 → Ink / `dark`）。 + // 产品路径才读 `appearance.theme_mode`。复审 P2：此前这里两种通道都读文件， + // 设置页「主题」那一行的选中态会随出图机器的配置漂移。 + let theme_mode = match options.screenshot.is_some() { + true => match options.shot_flavor().unwrap_or(SchemeFlavor::Light) { + SchemeFlavor::Light => ThemeMode::Light, + SchemeFlavor::Dark => ThemeMode::Dark, + }, + false => bridge.load().1, + }; + // 外观两半分开读：`load()` 给 8 个 UI 写入字段，`load_base()` 给 4 个只读下层键 + // （整窗 α / 标题栏三态 / 配色来源 / 窗口圆角）。M93 之前这些键在 app 侧**根本读不到**。 + // + // 截图通道**不读用户配置**（D30：同一份代码在两台机器上要出同一张图）：外观一律取出厂值， + // 矩阵需要的值由 `ULL_APPEARANCE_*` 显式灌进来。 + let (appearance_prefs, appearance_base) = if options.screenshot.is_some() { + ( + unlucky_presenter::prefs::AppearancePrefs::factory(), + unlucky_presenter::prefs::AppearanceBase::factory(), + ) + } else { + (bridge.load().0, bridge.load_base()) + }; + // 面板 α / 玻璃的降级判据要的是**实际**后端，不是 `--renderer` 的请求值（复审 r1 P2-2）： + // 默认 `Auto` + 无独显时请求是 Auto、实际是 tiny-skia，只看请求值就会漏掉 D36 的强制项。 + let backend_tier = super::super::backend::effective_backend(options.backend); + let mut appearance = pages::appearance::State::new( + &appearance_prefs, + &appearance_base, + backend_tier, + flavor, + ); + // 取证开关（D30）：`ULL_SETTINGS_GROUP=<下标>` 直达设置页的某一组（出图要看见语言行）。 + if let Some(index) = + crate::ui::lang::screenshot_settings_group(options.screenshot.is_some()) + { + appearance.selected_group = index; + } + // 界面语言（M106）：**M92 已经探测对了，问题是一直没人用**——`pages::Model.lang` 此前在 + // `view::model` 里被写死成 `Lang::En`，于是中文系统上开出来的是全英文界面。 + let lang = LangState::boot(&bridge, options.screenshot.is_some()); + // M168（复审 r2 P2-2）：出图通道**不许联网**——`log_cjk` 那一拍会走 `after_probe`， + // 一台 zh-locale 且没有中文字体的机器上会真的下 17 MiB，并可能在出图过程中注册新字体 + // （D30：同一份代码要出同一张图）。产品路径不设这个开关。 + crate::fonts::install::set_offline(options.screenshot.is_some()); + let mut view = pages::Model::new( + pages::Screen::Instances, + width, + height, + Some(pages::Screen::Instances.nav()), + ); + view.lang = lang.lang(); + + let mut app = Self { + ui: Ui::new(flavor, families), + families, + options, + backend, + bridge, + state: AppState::new(), + ticks: 0, + config_due_at: unlucky_presenter::theme::CONFIG_POLL_TICKS, + theme_mode, + lang, + last_tick: std::time::Instant::now(), + width, + view, + view_dirty: false, + watch_until: None, + window: None::, + frames: 0, + refreshes: 0, + auto_selected: false, + // M168：中文字体下载状态。构造这一拍 `lang.log_cjk()` 与启动编排的 `fonts::resolve()` + // 已经可能发起下载，所以初值就取**当前快照**（不能假定是 Unknown，否则第一拍会白重建）。 + font_seen: crate::fonts::install::status(), + height, + appearance, + appearance_prefs, + hwnd: None, + settings: pages::settings::Groups::default(), + // 出厂是**空会话**（M119 删了 M104 的样本会话）；取证开关 `ULL_AGENT_*` 的档位 + // 与夹具在 `boot_agent` 里落地（它要先让 presenter 知道栏可见性，见那里）。 + agent: crate::shell::agent::AgentUi::new(), + agent_host: super::presenter::AgentHost::from_env(), + // 下载页安装草稿（M105）：出厂态 = 没选中、原版、两个空串 + download_draft: pages::InstallDraft::default(), + launch_form: pages::LaunchForm::default(), + adopt_form: super::super::adopt::Form::default(), + install_cancelled_seen: 0, + launch_ends_seen: 0, + mods_failed_seen: None, + dialog_card: None, + dialog_model: None, + content: pages::content::PageState::default(), + account_form: pages::account::Form::new(), + account: pages::account::Page::build( + &AppState::new(), + &pages::account::Form::new(), + &mut pages::account::avatar::Cache::default(), + unlucky_i18n::Lang::En, + width, + ), + avatars: pages::account::avatar::Cache::default(), + corner_applied: None, + }; + // M229：设置页「主题」行的选中态来自设置组自有状态（`language_appearance::State::theme`）， + // 唯一写者是 `App::set_theme_mode`；这里把启动时读到的档位灌进去，首帧才不会画错档。 + app.settings.language_appearance.theme = theme_mode; + // 配色来源档可能已经指向一张背景图：那时 `Ui` 必须由解析出的方案构造，而不是色板。 + app.rebuild_ui(); + // M174：助手配置的首屏值（真值来自 `config/launcher.json`；截图通道走 `ULL_AI_STATE`）。 + app.hydrate_ai_settings(); + // M175：Java 分组的首屏值 + **首屏自动扫一次盘**（截图通道走 `ULL_JAVA_STATE`）。 + // M223: adopt wizard screenshot seed (evidence channel only; `ULL_ADOPT_STATE`). + app.hydrate_adopt_state(); + app.hydrate_java_settings(); + // 两行日志：①档位 + 探测结论 + 生效语言 ②中文策略（D28 缺字体不许静默）。 + // 下一个人据此分得清「探测错了」还是「探测对了但没用上」。 + app.lang.log(); + app.lang.log_cjk(); + app + } +} diff --git a/crates/app-iced/src/app/state/mods_shot.rs b/crates/app-iced/src/app/state/mods_shot.rs new file mode 100644 index 0000000..8b9c096 --- /dev/null +++ b/crates/app-iced/src/app/state/mods_shot.rs @@ -0,0 +1,97 @@ +//! 出图取证用的 MODS 夹具（`ULL_MODS_FIXTURE=1`）。 +//! +//! # 它解决什么 +//! +//! D30 的 MODS 区截图需要一屏**有内容的列表**。产品路径的列表来自后台线程（列 `mods/` → 快照）， +//! 而截图通道在第 3 帧就出图（`CAPTURE_AT_FRAME`）：那条后台往返来不及完成，截出来会是 +//! 「正在读取 mods/…」。M157 的启动参数区、M222 的下载页、M223 的导入都是同一个问题， +//! 处理方式一致：**状态注入**，且注入点放在「快照 → 页面模型」之前，于是转换逻辑照样被执行。 +//! +//! # 边界（不要把它读成产品能力） +//! +//! - 只在环境变量存在时生效；产品路径读不到它 ⇒ 一帧都不影响； +//! - 它注入的是**快照**（[`ModListView`]），不是页面模型——`Mods::from_state` 的转换、 +//! 计数、`.old` 徽标、在飞置灰走的都是产品代码； +//! - 真实链路由两条端到端用例钉住（`host::mods::tests` 在真盘上列目录 + 启停）。 + +/// 夹具开关是否打开（`ULL_MODS_FIXTURE` 非空且不为 `0`）。 +#[must_use] +pub fn enabled() -> bool { + std::env::var("ULL_MODS_FIXTURE") + .map(|value| { + let value = value.trim(); + !value.is_empty() && value != "0" + }) + .unwrap_or(false) +} + +/// 一份固定快照（实例 id 用调用方给的那个）。 +/// +/// `dir` 故意留空：夹具不碰路径（这一版页面也不画它），写一个假路径反而会被当成"真的派生结果"。 +#[must_use] +pub fn view(instance: &str) -> unlucky_presenter::dto::ModListView { + use unlucky_presenter::dto::{ModEntryView, ModListView}; + + let entry = |file: &str, name: &str, enabled: bool, bytes: u64, old: bool| ModEntryView { + file: file.to_string(), + name: name.to_string(), + enabled, + bytes, + old, + }; + // 夹具不碰路径：`dir` 留空（页面这一版不画它，它只是 DTO 的一部分）。 + let dir = String::new(); + + ModListView { + instance: instance.to_string(), + dir, + exists: true, + entries: vec![ + entry( + "sodium-fabric-0.5.11.jar", + "sodium-fabric-0.5.11.jar", + true, + 1_048_576, + false, + ), + entry( + "iris-fabric-1.8.5.jar", + "iris-fabric-1.8.5.jar", + true, + 2_621_440, + false, + ), + entry( + "jei-1.20.4-forge-17.3.0.49.jar.disabled", + "jei-1.20.4-forge-17.3.0.49.jar", + false, + 1_363_148, + false, + ), + entry( + "aether-1.20.1-1.0.0.jar.old", + "aether-1.20.1-1.0.0.jar", + true, + 7_340_032, + true, + ), + entry( + "create-1.20.1-0.5.1.f.jar.disabled", + "create-1.20.1-0.5.1.f.jar", + false, + 4_194_304, + false, + ), + entry( + "fabric-api-0.92.2+1.20.4.jar", + "fabric-api-0.92.2+1.20.4.jar", + true, + 2_097_152, + false, + ), + ], + skipped: Vec::new(), + running: false, + known: true, + } +} 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..1ea443f --- /dev/null +++ b/crates/app-iced/src/app/state/refresh.rs @@ -0,0 +1,234 @@ +//! 快照 → 视图模型的重建口径（从 `state.rs` 搬出来守 400 行硬线；M119 拆，纯搬不改）。 +//! +//! 全仓只有 [`App::refresh_view`] 这一个「presenter 快照 → 页面要画的东西」的转换点， +//! 由 [`App::view_dirty`](super::App) 门控（M90 r2/P2-1 起）：只有真的改了状态的事情才置位， +//! 30 Hz 空转不重建（重建要把 N 个实例的名字/版本串克隆一遍）。 + +use unlucky_presenter::dto::{AppCommand, ModsCommand, SavesCommand}; + +use super::{mods_shot, saves_shot}; +use unlucky_presenter::toast::ToastKind; + +use crate::app::view; +use crate::pages; + +use unlucky_presenter::router::Route; + +use super::App; + +impl App { + /// 把 presenter 的快照转换成页面视图模型（**展示转换在 UI 侧做**）。 + /// + /// 代价是「克隆 N 个实例的名字/版本串」，所以只在 [`App::view_dirty`] 置位时调用（P2-1）。 + pub(in crate::app) fn refresh_view(&mut self) { + // **不变式先对齐再算宽度**（M104 / 复审 r1 P2-1）：`Route::Agent` ⟺ `RailState::Detached`。 + // 每一次路由变化都会走到这里，所以它是「档位 ↔ 路由」的唯一点；放在算宽度之前， + // 是为了让模型拿到的 `content_width` 与页面头部读到的档位来自同一份状态。 + self.sync_agent_route(); + // M119：把「栏可见吗」写回 presenter（未读口径的输入，两个窄入口：`navigate` + `prefs_mut`）。 + // 必须在 `sync_agent_route` 之后：档位刚被它对齐过，这里读到的才是这一帧的真值。 + self.sync_agent_presenter(); + + // M105：取消安装的提示语在**这里**弹（`refresh_view` 是事件 apply 之后必经的那一处）。 + // 文案由页面层求（`pages::cancelled_toast`），presenter 只发信号 —— + // 否则会出现「选项区英文、取消弹窗中文」的同屏两语（复审 P2-2）。 + if self.state.install_cancelled != self.install_cancelled_seen { + self.install_cancelled_seen = self.state.install_cancelled; + // M106：提示语跟着**生效语言**走（M105 留的 `view::ui_lang()` 占位已删——它恒英文， + // 中文界面会弹出英文提示，那正是 M105 r1 复审 P2-2 要堵的同屏两语）。 + let text = pages::cancelled_toast(self.lang()); + self.state.toasts.push(ToastKind::Info, text); + } + + // M161：启动收尾的提示语也在这里弹（presenter 只发结构：结局 + 退出码 + 失败阶段）。 + // 此前 presenter 直接推一条自己拼好的中文 Toast，英文界面会弹中文。 + if self.state.launch_ends != self.launch_ends_seen { + self.launch_ends_seen = self.state.launch_ends; + if let Some(finished) = self.state.last_launch_end.as_deref() { + let text = view::instances::launch_toast(finished, self.lang()); + let kind = if finished.outcome == unlucky_presenter::dto::LogOutcome::Ok + && finished.failure.is_none() + { + ToastKind::Success + } else { + ToastKind::Error + }; + self.state.toasts.push(kind, text); + // M187：失败要**弹窗**（Toast 会自己消失，崩溃现场不能只靠它）。 + let ended = finished.clone(); + self.open_failure_dialog(&ended); + } + } + + // M224：详情页 ⇄ MODS 区的绑定与取数（换实例就重新列一次 mods/）。 + // **必须在建模型之前**：它会把快照写进 presenter 状态，而下一行 `model()` 就读那份状态 + // （放在 `model()` 之后等于这一帧画的是旧快照——M224 出图实测：注入的夹具要等下一帧）。 + self.sync_mods(); + // M235：详情页 ⇄ SAVES 区的绑定与取数（换实例就重新列一次存档）。同样是**建模型之前**。 + self.sync_saves(); + // M224：启停失败的提示语（presenter 只发结构，文案在这里按 i18n 现求）。 + self.note_mods_failure(); + // M247（复审 r1 P2-1）：被确认的世界已经从快照里消失 ⇒ 收起那个确认框。 + // 不这样的话主按钮就是一次静默空操作（点了没删、也不说一句）。 + self.settle_saves_confirm(); + + // 分类是**页面自己持有的过滤条件**（真 host 丢弃 `ListVersions` 的分类参数）： + // 重建视图模型时带回去，否则每次事件都会把 chip 打回「全部」（复审 P2-1）。 + let category = self.view.download.category; + // 草稿同理（M105）：它也是页面自己持有的输入，重建模型时带回去， + // 否则每来一条事件（连安装进度都算）用户填的加载器就被抹回「原版」。 + let draft = self.download_draft.clone(); + // 右栏占掉的宽度先扣掉：面板展开时页面按更窄的宽度排版（「收缩而不是溢出」，M104） + let width = self.agent.content_width(self.width); + // M106：语言形参跟着 `LangState` 走（`draft` 那一位是 M105 的安装草稿）。 + self.view = super::super::view::model( + &self.state, + width, + self.height, + self.options.force_state, + category, + &draft, + self.lang(), + &self.content, + ); + // M157：启动参数表单的重播种（换实例必重播种、同实例的脏草稿不覆盖）。 + self.sync_launch_form(); + // 账户页（M114）：与 `view` 同一次门控重建（实现见 `view/account_page.rs`， + // 皮肤解码走缓存，所以重复重建不重解图）。 + self.rebuild_account_page(width); + // M187：弹窗的视图模型也在这一处重建——`view()` 只借 `&self`，放不进局部变量 + // （Element 借字符串，局部一死树就悬空）。全仓「快照 → 视图模型」只在这里发生。 + self.dialog_model = self.dialog_modal(); + self.view_dirty = false; + self.refreshes += 1; + } + + /// 收掉「被确认的世界已经不在快照里」的那个删除确认框（M247，复审 r1 P2-1）。 + /// + /// 判据由 presenter 给（`SavesState::take_closed_confirm`：那个世界从快照里消失了）， + /// **框的 id 也由它带着**——所以只收我们自己那个框，崩溃卡片/进度框一概不碰。 + /// + /// 为什么必须收：目标已经作废，主按钮就成了一次**静默空操作**（用户点了「删除世界」， + /// 框关了、什么也没发生、也没一句解释）。少删是安全的，但"看起来坏了"不是可接受的结果。 + fn settle_saves_confirm(&mut self) { + let Some(dialog) = self.state.saves.take_closed_confirm() else { + return; + }; + if self + .state + .dialogs + .current() + .is_some_and(|current| current.id == dialog) + { + self.close_dialog(); + } + } + + /// 把详情页当前实例的启动参数快照灌进表单（唯一的重播种点，见 `pages/instances/state.rs`）。 + /// + /// 不在详情页（或实例已不在快照里）时解绑：下次进详情页会重新播种， + /// 免得「A 的草稿被当成 B 的初值」。 + fn sync_launch_form(&mut self) { + let Route::Detail(id) = self.state.route() else { + self.launch_form.bound = None; + return; + }; + match self + .state + .instances + .iter() + .find(|instance| &instance.id == id) + { + Some(instance) => { + let view = instance.launch.clone(); + self.launch_form.sync(&view); + } + None => self.launch_form.bound = None, + } + } + + /// 详情页 ⇄ MODS 区的绑定与取数。 + /// + /// 判据只有一条：**绑定变了**（进详情页 / 换实例 / 退出详情页）。 + /// - 绑定函数自己会清掉旧快照（A 的列表不许画在 B 的详情页上，见 presenter 的 `ModsState::bind`）； + /// - 绑定之后手上没有快照 ⇒ 派一条 `AppCommand::Mods(List)` 去后台列目录。 + /// + /// 为什么放在 `refresh_view` 里：它是**唯一**的「路由变了」漏斗（点行、返回、首屏自动选中都走它）。 + /// 派发会再进一次 `refresh_view`（`dispatch` → `pump` → 重建），但那时 `bound` 已经相等， + /// 这一支直接返回，不会重复发请求、也不会无限递归。 + fn sync_mods(&mut self) { + let wanted = match self.state.route() { + Route::Detail(id) => Some(id.clone()), + _ => None, + }; + if self.state.mods.bound == wanted { + return; + } + self.state.bind_mods(wanted.as_deref()); + let Some(id) = wanted else { + return; + }; + // 出图取证（`ULL_MODS_FIXTURE=1`）：后台往返赶不上第 3 帧出图，注入一份固定快照。 + // 产品路径读不到这个变量 ⇒ 下面这行什么都不做（见 `mods_shot` 的模块文档）。 + if mods_shot::enabled() { + self.state.mods.changed(mods_shot::view(&id)); + return; + } + // **不走 `App::dispatch`**：那条路会为「等第一条事件」把帧订阅打开 3 秒（`watch_until`）， + // 而这里只是"进详情页顺手后台列一次目录"——结果在下一拍心跳（1 Hz）落地就够了。 + // 走观察窗会把 M192 的「空闲不烧帧」守卫打红（`subscription` 的三条用例立刻红：实测过）。 + self.backend + .dispatch(AppCommand::Mods(Box::new(ModsCommand::List(id)))); + } + + /// 详情页 ⇄ SAVES 区的绑定与取数（M235）。 + /// + /// 判据与 `sync_mods` **一字不差**：绑定变了（进详情页 / 换实例 / 退出详情页）才动； + /// 绑定之后手上没有快照 ⇒ 派一条 `AppCommand::Saves(List)` 去后台列目录。 + /// + /// 不弹 Toast：存档区的失败就地画在卡片里（带「重试」），再弹一条是同一件事说两遍。 + fn sync_saves(&mut self) { + let wanted = match self.state.route() { + Route::Detail(id) => Some(id.clone()), + _ => None, + }; + if self.state.saves.bound == wanted { + return; + } + self.state.bind_saves(wanted.as_deref()); + let Some(id) = wanted else { + return; + }; + // 出图取证（`ULL_SAVES_FIXTURE=1`）：后台往返赶不上第 3 帧出图，注入一份固定快照。 + // 产品路径读不到这个变量 ⇒ 下面这行什么都不做（见 `saves_shot` 的模块文档）。 + if saves_shot::enabled() { + saves_shot::seed(self, &id); + return; + } + // **不走 `App::dispatch`**：那条路会为「等第一条事件」把帧订阅打开 3 秒， + // 这里只是"进详情页顺手后台列一次目录"，结果在下一拍心跳落地就够了（M224 同款理由： + // 走观察窗会把 M192 的「空闲不烧帧」守卫打红）。 + self.backend + .dispatch(AppCommand::Saves(Box::new(SavesCommand::List(id)))); + } + + /// 启停失败的提示语：每条**新**失败弹一次 Toast。 + /// + /// 判据是 `(实例, 文件, 大类)` 三元组：同一个文件连点两次、每次都失败在同一个大类上时， + /// **只弹一次**——第二次是同一件事的重复，再弹就是刷屏（用户已经看见了那句红字）。 + /// 换了文件、换了实例、或失败大类变了（例如"不覆盖冲突"变成"被占用"），三元组就变了， + /// 于是照样会再弹一次：提示语跟的是"新事实"，不是"点击次数"。 + fn note_mods_failure(&mut self) { + let Some(failure) = self.state.mods.failed.as_ref() else { + self.mods_failed_seen = None; + return; + }; + let key = (failure.instance.clone(), failure.file.clone(), failure.kind); + if self.mods_failed_seen.as_ref() == Some(&key) { + return; + } + let text = pages::mods_failure_line(failure, self.lang().catalog()); + self.state.toasts.push(ToastKind::Error, text); + self.mods_failed_seen = Some(key); + } +} diff --git a/crates/app-iced/src/app/state/saves_shot.rs b/crates/app-iced/src/app/state/saves_shot.rs new file mode 100644 index 0000000..94ed75b --- /dev/null +++ b/crates/app-iced/src/app/state/saves_shot.rs @@ -0,0 +1,266 @@ +//! 出图取证用的 SAVES 夹具（`ULL_SAVES_FIXTURE=1`）。 +//! +//! # 它解决什么 +//! +//! D30 的 SAVES 区截图需要一屏**有内容的列表**（世界 + 截图）。产品路径的列表来自后台线程 +//! （列 `saves/` → 快照），而截图通道在第 3 帧就出图（`CAPTURE_AT_FRAME`）：那条后台往返来不及 +//! 完成，截出来会是「正在读取 saves/…」。M157 / M222 / M223 / M224 都是同一个问题，处理方式一致： +//! **状态注入**，注入点放在「快照 → 页面模型」之前，于是转换逻辑照样被执行。 +//! +//! # 边界（不要把它读成产品能力） +//! +//! - 只在环境变量存在时生效；产品路径读不到它 ⇒ 一帧都不影响； +//! - 它注入的是**快照**（[`SavesListView`]），不是页面模型——`Saves::from_state` 的时间格式化、 +//! 计数、「有图标」标记走的都是产品代码； +//! - 真实链路由端到端用例钉住：`core::game::saves::tests`（真盘只读列举）与 +//! `presenter::host::saves::tests`（派生运行目录 → 快照）。 +//! +//! ```text +//! ULL_SAVES_FIXTURE=1 ULL_INSTANCE_STATE=demo ULL_START_ROUTE=instances \ +//! unlucky-launcher-iced --screenshot=saves.png --software-renderer +//! ``` + +/// 夹具开关是否打开（`ULL_SAVES_FIXTURE` 非空且不为 `0`）。 +#[must_use] +pub fn enabled() -> bool { + std::env::var("ULL_SAVES_FIXTURE") + .map(|value| { + let value = value.trim(); + !value.is_empty() && value != "0" + }) + .unwrap_or(false) +} + +/// 2024-05-01 10:00 UTC（写死的 UTC 毫秒，不是"现在"）。 +/// +/// 写死有两个原因：两张主题图要能逐像素对照；而且它能证明「毫秒 → `YYYY-MM-DD HH:MM UTC`」 +/// 这条换算在页面上真的走通了（`docs` 里的期望值就是这个时刻）。 +const NEWEST: u64 = 1_714_557_600_000; +/// 比 [`NEWEST`] 早 32 天。 +const MIDDLE: u64 = NEWEST - 32 * 24 * 3_600_000; +/// 比 [`NEWEST`] 早 42 天。 +const OLDEST: u64 = NEWEST - 42 * 24 * 3_600_000; + +/// 一份固定快照（实例 id 用调用方给的那个）。 +/// +/// 其中一个世界/一张截图的 mtime 是 `None`：那是「时间未知」这条分支的唯一出图证据。 +#[must_use] +pub fn view(instance: &str) -> unlucky_presenter::dto::SavesListView { + use unlucky_presenter::dto::{ + SavesListView, ScreenshotPreview, ScreenshotThumbFailure, ScreenshotThumbKind, + ScreenshotView, WorldView, + }; + + let world = |dir: &str, icon: bool, modified_ms: Option| WorldView { + dir: dir.to_string(), + icon, + modified_ms, + }; + let shot = |file: &str, bytes: u64, modified_ms: Option, preview: ScreenshotPreview| { + ScreenshotView { + file: file.to_string(), + bytes, + modified_ms, + preview, + } + }; + + SavesListView { + instance: instance.to_string(), + dir: "D:/ULL/.ULL/data/instances/Better-MC/saves".to_string(), + exists: true, + worlds: vec![ + world("Better World", true, Some(NEWEST)), + world("Redstone Lab", true, Some(MIDDLE)), + world("Skyblock", false, Some(OLDEST)), + world("Test Flat", false, None), + ], + screenshots_dir: "D:/ULL/.ULL/data/instances/Better-MC/screenshots".to_string(), + screenshots_exists: true, + // 四张截图，把缩略图墙的**四种格子**一次摆出来（M251）： + // ① 白天（真像素）② 黄昏（真像素）③ 「未生成预览」占位 ④ 具名的失败原因。 + // 像素是**合成的**（下面 `scene`）：夹具不连真实解码器，出图只证明墙的排版与状态， + // 解码由 presenter 的 `host::saves::thumbs` 用例用真 PNG 钉住。 + screenshots: vec![ + shot( + "2024-05-01_10.00.00.png", + 1_887_436, + Some(NEWEST), + ScreenshotPreview::Ready(scene(1)), + ), + shot( + "2024-04-30_21.14.05.png", + 2_097_152, + Some(MIDDLE), + ScreenshotPreview::Ready(scene(2)), + ), + shot( + "2024-04-20_08.30.00.png", + 964_608, + None, + ScreenshotPreview::NotGenerated, + ), + shot( + "2024-04-11_19.02.41.png", + 9_437_184, + Some(OLDEST), + ScreenshotPreview::Failed(ScreenshotThumbFailure { + kind: ScreenshotThumbKind::TooLarge, + detail: "9437184 > 8388608".to_string(), + }), + ), + ], + skipped: Vec::new(), + // 出图夹具不造回执：默认那一张就是「刚列完目录」的样子。 + // 要看「备份成功那句话」长什么样，用 `ULL_SAVES_FIXTURE=backed-up`（见 `seed`）。 + last_op: None, + } +} + +/// 夹具形态（由 `ULL_SAVES_FIXTURE` 的取值决定；未知值 = 默认那一种）。 +/// +/// | 取值 | 出图抓什么 | +/// |---|---| +/// | `1`（或任何未知值） | 有内容的列表：世界行右侧的重命名 / 备份 / 删除 | +/// | `rename` | 行内重命名进行中（输入框 + 改名/取消） | +/// | `confirm` | 删除的二次确认模态框 | +/// | `backed-up` | 备份成功的回执那句话（带落点路径与大小） | +/// | `running` | 「游戏正在运行，先退出再操作」那条写失败（M247 的在飞闸门） | +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Mode { + /// 默认：列表 + 行操作区。 + Plain, + /// 行内重命名进行中。 + Rename, + /// 删除确认模态。 + Confirm, + /// 备份成功的回执。 + BackedUp, + /// 写操作被「游戏在运行」挡下。 + Running, +} + +fn mode() -> Mode { + match std::env::var("ULL_SAVES_FIXTURE") + .unwrap_or_default() + .trim() + { + "rename" => Mode::Rename, + "confirm" => Mode::Confirm, + "backed-up" => Mode::BackedUp, + "running" => Mode::Running, + _ => Mode::Plain, + } +} + +/// 注入这一屏需要的状态（**只走产品路径的入口**：`changed` / `start_rename` / `ask_delete` / +/// `dialogs.push`，一处新渲染分支都没有）。 +pub fn seed(app: &mut crate::app::state::App, instance: &str) { + let mode = mode(); + let mut view = view(instance); + if mode == Mode::BackedUp { + view.last_op = Some(unlucky_presenter::dto::SavesOped::BackedUp { + dir: "Better World".to_string(), + file: "Better World-20240501-100000.zip".to_string(), + path: "D:/ULL/.ULL/data/exports/saves/Better World-20240501-100000.zip".to_string(), + bytes: 84_213_760, + skipped: 0, + }); + } + let first = view.worlds.first().map(|world| world.dir.clone()); + app.state.saves.changed(view); + let Some(dir) = first else { + return; + }; + match mode { + Mode::Rename => app.state.saves.start_rename(&dir), + // 在飞闸门那条失败（`host::saves::dispatch` 在 `running` 时直接回它）。 + Mode::Running => app + .state + .saves + .failed(unlucky_presenter::dto::SavesFailureView { + instance: instance.to_string(), + file: dir, + op: Some(unlucky_presenter::dto::SavesFailureOp::Rename), + kind: unlucky_presenter::dto::SavesFailureKind::GameRunning, + detail: String::new(), + }), + Mode::Confirm => { + let (title, body, primary, secondary) = + crate::pages::saves_delete_prompt(app.lang().catalog(), &dir); + let dialog = app.state.dialogs.push( + unlucky_presenter::dialogs::DialogSource::UserAction, + title, + body, + unlucky_presenter::dialogs::DialogKind::Confirm { primary, secondary }, + ); + app.state.saves.ask_delete(dialog, &dir); + } + Mode::Plain | Mode::BackedUp => {} + } +} + +/// 一张**合成的**缩略图（160×90 RGBA）：天空渐变 + 地面 + 太阳/月亮。 +/// +/// 为什么合成而不是读真图：夹具的职责是「让页面有东西可画」，而它跑在截图通道的第 3 帧—— +/// 真解码要真的有一张 PNG 在盘上、还要等后台线程回来。合成像素让出图**确定**（两张主题图 +/// 逐像素可比），并且明确地不假装自己是解码证据（那由 presenter 的用例负责）。 +/// +/// `tone`：`1` = 白天（亮天空 + 绿地面），其余 = 黄昏（橙天空 + 暗地面）。同一套几何， +/// 两种配色——墙上两格一眼能看出"每格各画各的"。 +fn scene(tone: u8) -> unlucky_presenter::dto::ThumbnailView { + const W: u32 = 160; + const H: u32 = 90; + // 地平线在 2/3 高度（截图里天空总比地面多）。 + const HORIZON: u32 = H * 2 / 3; + let (sky_top, sky_bottom, ground, sun): ([u8; 3], [u8; 3], [u8; 3], [u8; 3]) = if tone == 1 { + ( + [128, 176, 240], + [200, 224, 248], + [86, 138, 66], + [255, 246, 186], + ) + } else { + ([96, 66, 96], [232, 148, 96], [58, 74, 48], [255, 214, 150]) + }; + let mut pixels = Vec::with_capacity((W * H * 4) as usize); + for y in 0..H { + for x in 0..W { + let (r, g, b) = if y < HORIZON { + // 天空：从顶到底线性插值（`t` = 0..=255 的定点比例）。 + let t = y * 255 / HORIZON.max(1); + let mix = |from: u8, to: u8| -> u8 { + let span = i32::from(to) - i32::from(from); + (i32::from(from) + span * t as i32 / 255) as u8 + }; + ( + mix(sky_top[0], sky_bottom[0]), + mix(sky_top[1], sky_bottom[1]), + mix(sky_top[2], sky_bottom[2]), + ) + } else { + // 地面：按 3px 一条的条纹给出「方块地形」的观感。 + let stripe = (y / 3) % 2 == 0; + let shade: u8 = if stripe { 0 } else { 14 }; + ( + ground[0].saturating_sub(shade), + ground[1].saturating_sub(shade), + ground[2].saturating_sub(shade), + ) + }; + // 太阳/月亮：右上角一个 18px 的圆（够小，不会盖住画面主体）。 + let (dx, dy) = (x as i32 - 126, y as i32 - 26); + let (r, g, b) = if dx * dx + dy * dy <= 18 * 18 { + (sun[0], sun[1], sun[2]) + } else { + (r, g, b) + }; + pixels.extend_from_slice(&[r, g, b, 255]); + } + } + unlucky_presenter::dto::ThumbnailView { + width: W, + height: H, + pixels, + } +} 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..154ce00 --- /dev/null +++ b/crates/app-iced/src/app/state/theme.rs @@ -0,0 +1,232 @@ +//! 主题与 `Ui` 的重算口径（从 `state.rs` 搬出来守 400 行硬线；M119 拆，纯搬不改）。 +//! +//! 三件事在这里：①`Ui` 什么时候重建（[`App::rebuild_ui`]）②主题档怎么定 +//! （[`App::set_flavor`] / [`App::apply_config_theme`]）③读当前求值器（[`App::ui`]）。 +//! +//! 截图通道的判据 [`App::has_screenshot`] 也放在这儿：上面三条里两条都要「截图不读用户配置」。 + +use crate::app::diag::diag; +use crate::app::message::Message; +use iced::Task; +use unlucky_design::color::SchemeFlavor; +use unlucky_presenter::prefs::ThemeMode; + +use crate::theme::Ui; + +use super::App; + +impl App { + /// 本次进程是否走截图通道。 + pub(in crate::app) fn has_screenshot(&self) -> bool { + self.options.screenshot.is_some() + } + + /// 切主题：重建 [`Ui`]（= 重建 Style），**不动任何 UI 状态**。 + /// + /// M93 起 `Ui` 有两个来源：配色来源取到了图（①②级）就用解析出的方案，否则用令牌 baseline。 + /// 所以这里改叫「重算 `Ui`」：先让外观状态记住新深浅（配色解析要它），再重建。 + pub(in crate::app) fn set_flavor(&mut self, flavor: SchemeFlavor) { + if self.ui.flavor() == flavor && self.appearance.flavor() == flavor { + return; + } + + self.appearance.set_flavor(flavor); + let previous = self.ui.name(); + self.rebuild_ui(); + diag!( + "[theme] {} -> {} (Theme::name 变化触发缓存重算)", + previous, + self.ui.name() + ); + } + + /// 按「强调色 / 配色来源是否接管」重建 [`Ui`]。 + /// + /// **优先级（M250）：显式强调色 > D38 取色方案 > 出厂品牌板**。手填的色是直接意图，取色是从 + /// 图片派生的，所以强调色只在用户真的填了合法值时压过取色——两条路都只决定「颜色来自哪里」， + /// `flavor`（明暗 / 跟随系统）仍由 `self.appearance.flavor()` 决定。 + /// + /// 色卡档（③）刻意继续走 `Scheme::baseline`：`resolve_source` 的色卡档返回的是 + /// `DEFAULT_CARD`（天蓝卡）方案，与令牌 baseline 逐色不同，应用它会把**全部既有验收图的 + /// 像素**改掉。这条偏离登记在 `pages::appearance` 的偏离表 #4。 + pub(in crate::app) fn rebuild_ui(&mut self) { + // 面板 α（D36）在这里注入 `Ui`：全仓所有表面色都从 `Ui::layer` 出去，所以这是**唯一** + // 生效点（外壳 / 三页卡片 / 外观分组卡片 / 空态图标块自动同源，调用点没有机会各处自乘）。 + let panel_alpha = self.appearance.effective_panel_alpha(); + // 三选一规则只在 `theme::tokens` 里写一遍：出图 harness 也调它（两头各抄一份迟早 + // 出现「图上有强调色、产品里没有」，而那种偏差在图上看不出来）。 + let (ui, colors) = crate::theme::tokens( + self.appearance.flavor(), + self.appearance.accent.color(), + self.appearance.derived_scheme().copied(), + self.families, + ); + match colors { + crate::theme::Colors::Accent => { + // M250：一行里同时给「强调色生效了」与「取色方案被谁压住」，两件事都能读出来。 + diag!( + "[appearance] accent={} → Ui::with_accent（只换 primary/secondary/tertiary；取色方案 palette={} 被压住）", + self.appearance.accent.log_token(), + self.appearance.palette_level() + ); + } + crate::theme::Colors::Scheme => { + diag!( + "[appearance] palette={} → Ui::from_scheme（取色方案接管 49 个角色）", + self.appearance.palette_level() + ); + } + crate::theme::Colors::Board => { + // 非法值：**保持出厂板**，但错行留在设置页（不静默），日志里也留一条。 + if let Some(error) = self.appearance.accent.error() { + diag!("[appearance] accent 非法（{error:?}）→ 出厂板，错行见设置页"); + } + } + } + self.ui = ui.with_panel_alpha(panel_alpha); + } + + /// 按设置文件里的主题模式切一次外观；`--theme` 显式给了就不动。 + /// + /// **截图通道直接跳过**：`--screenshot` 的主题唯一取值口是 `Options::capture_flavor` + /// （D30 可复现），读本机 `launcher.json` 会让同一份代码在两台机器上出不同的图。 + /// + /// `ThemeMode::Auto` 不在这里处理：那要看系统主题（`iced::system::theme()` 的结果在 + /// `Message::SystemTheme` 里落地）。 + pub(in crate::app) fn apply_config_theme(&mut self) { + if self.has_screenshot() || self.options.theme.is_some() { + return; + } + let mode = self.bridge.load().1; + self.theme_mode = mode; + // M229：设置页那一行画的是这个字段（唯一写者见 [`App::set_theme_mode`]）。 + self.settings.language_appearance.theme = mode; + match mode { + ThemeMode::Light => self.set_flavor(SchemeFlavor::Light), + ThemeMode::Dark => self.set_flavor(SchemeFlavor::Dark), + ThemeMode::Auto => {} + } + } + + /// 换主题档（M229：设置页「通用 → 主题」→ `pages::Message::Theme`）。 + /// + /// 四件事：①改 `theme_mode`（唯一真相）②同步设置页那一行的档位 ③重建 `Ui`（色板换了， + /// `Theme::name` 与 49 个角色一起变，iced 才会重算缓存）④落盘 `appearance.theme_mode`。 + /// `Auto` 自己没有颜色，要等系统回答——所以返回 `iced::system::theme()` 那个 Task， + /// 由既有的 `Message::SystemTheme` 分支落地（它只在 `theme_mode == Auto` 时吃这条消息）。 + pub(in crate::app) fn set_theme_mode(&mut self, mode: ThemeMode) -> Task { + self.settings.language_appearance.theme = mode; + if mode == self.theme_mode { + return Task::none(); + } + self.theme_mode = mode; + + let prefs = self.appearance_prefs.clone(); + self.bridge.persist(&prefs, mode); + match self.bridge.path() { + Some(path) => diag!("[theme] mode={} 已写回 {}", mode.as_str(), path.display()), + None => diag!( + "[theme] mode={} 未落盘（数据根解析不出来，内存态运行）：重启会回到旧值", + mode.as_str() + ), + } + + match mode { + ThemeMode::Light => { + self.set_flavor(SchemeFlavor::Light); + self.after_theme_switch(); + Task::none() + } + ThemeMode::Dark => { + self.set_flavor(SchemeFlavor::Dark); + self.after_theme_switch(); + Task::none() + } + // 跟随系统：当前先按已有深浅画，紧接着由系统主题回答覆盖 + // （`set_flavor` 有「同档不重建」的保护，所以这里不必先猜一次）。 + ThemeMode::Auto => iced::system::theme().map(Message::SystemTheme), + } + } + + /// 换档之后重建视图模型 + 记一行取证日志（色板名就是证据：`ink` / `silver`）。 + fn after_theme_switch(&mut self) { + self.view_dirty = true; + self.refresh_view(); + diag!( + "[theme] mode={} board={} Theme::name={}", + self.theme_mode().as_str(), + self.board_name(), + self.ui.name() + ); + } + + /// 当前主题档（设置页那一行的选中态来自 `settings.groups`，这里是取证与测试的读数口）。 + pub(in crate::app) fn theme_mode(&self) -> ThemeMode { + self.theme_mode + } + + /// 当前色板名（日志与测试用：`ink` / `silver`；取色方案接管时仍报它所属深浅的那块）。 + pub(in crate::app) fn board_name(&self) -> &'static str { + self.ui.board().name() + } + + /// 当前令牌求值器（测试与截图日志用）。 + pub(in crate::app) fn ui(&self) -> &Ui { + &self.ui + } +} + +#[cfg(test)] +mod tests { + use super::super::App; + use crate::app::components::feedback::progress; + use crate::cli::Options; + use crate::pages::appearance::Change; + use crate::theme::Families; + use unlucky_design::color::{Color, SchemeFlavor}; + use unlucky_presenter::mock::MockBackend; + use unlucky_presenter::settings_bridge::SettingsBridge; + + const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", + }; + + /// 强调色接线（M250 ACCENTWIRE）的 App 级判据：`rebuild_ui` 真的换了令牌。 + /// + /// **这条是判据一的变异探针**：把 [`App::rebuild_ui`] 改回「恒走 `Ui::new` 出厂板」 + /// （或在它前面短路掉 `accent.color()` 分支），下面 `assert_ne!` 当场红——`pages/appearance` + /// 那条用例只证明「`Ui::with_accent` 能给出不同的色」，抓不到「谁去调它」。 + /// + /// 抓得住：接线不存在 / 被短路 / 强调色解析结果没进 `Ui`。 + /// 抓不住：像素（样式闭包被别处覆盖）——那是出图的事。 + #[test] + fn rebuild_ui_follows_the_configured_accent() { + let mut app = App::with_presenter( + Options::default(), + FAMILIES, + SchemeFlavor::Light, + Box::new(MockBackend::new()), + SettingsBridge::memory_only(), + ); + + // 出厂态：同一组件（进度指示条 = `Role::Primary`）取到的值 + let (_, factory_primary) = progress::linear_colors(app.ui()); + assert_eq!(app.ui().name(), "ull-silver"); + + // 设置页填色 → `on_appearance` 会 rebuild 一次（与真机路径同一个函数） + app.on_appearance(Change::Accent(Color::rgb(0x00, 0x6A, 0x5C).to_hex())); + let (_, accent_primary) = progress::linear_colors(app.ui()); + + assert_ne!( + factory_primary, accent_primary, + "填了自定义强调色，`rebuild_ui` 却还给出出厂板的 Primary ⇒ 接线没落地" + ); + assert_eq!( + app.ui().flavor(), + SchemeFlavor::Light, + "强调色只换颜色来源，不改明暗" + ); + } +} diff --git a/crates/app-iced/src/app/subscription.rs b/crates/app-iced/src/app/subscription.rs new file mode 100644 index 0000000..d49ce2a --- /dev/null +++ b/crates/app-iced/src/app/subscription.rs @@ -0,0 +1,350 @@ +//! 订阅：**按需**帧节拍（presenter 的 TICK）+ 窗口尺寸事件。 +//! +//! ## 为什么要「按需」 +//! +//! iced_winit 在处理完任何一条消息后都会 `request_redraw()`，而 `window::frames()` 监听的是 +//! `RedrawRequested` —— 于是「订阅帧 → 收 Frame → update → 再触发重绘」是一条**自持循环**： +//! 只要订阅着，窗口就永远在重绘（M90 r1 就是这样，CPU 空转）。 +//! +//! 现在只在**真的需要 33 ms 节拍**的时候订阅（[`App::needs_frames`]）： +//! +//! | 条件 | 为什么需要 33 ms 节拍 | +//! |---|---| +//! | 截图通道 | 第 3 帧要落盘 | +//! | **有动画在跑**（M192） | 动效时间轴要逐帧采样（帧泵自己按 16 ms 结算，见 `components::motion`） | +//! | 有 `Busy` / `Running` 实例 | 启动进度、日志尾随都靠 `backend.tick` 推进 | +//! | 有未过期的 toast | toast 按毫秒倒计时 | +//! | 刚派发过指令（3 s 观察窗） | 真 host 的异步事件要靠节拍抽出来 | +//! +//! 上面五条**共享同一个布尔**：订阅表里 `window::frames()` 只出现一处（写在同一个 `if` 里）， +//! 所以「动画」与「观察窗 / Busy」同时成立时也只有一条订阅——不双订阅靠的是结构，不是判重。 +//! +//! 空闲态**一条帧消息都不来** ⇒ 窗口不重绘、`refresh_view` 不跑（配合 `view_dirty`）。 +//! +//! ## 空闲态的时钟从哪来（M90 r3 / P2-2） +//! +//! r2 把空闲的帧订阅掐掉之后，`config_poll_due` 就再也没被调用过 —— 外部 CLI / AI 工具改 +//! `launcher.json` 后主题**永不生效**（不是「等下次交互」，是「等下一次 dispatch」）。这与 +//! D4「AI 能读改 ULL 配置」直接冲突。 +//! +//! 所以空闲态换成一个 **1 Hz 的自续心跳**（[`crate::app::message::Message::Heartbeat`]， +//! 由 `Task::perform(sleep(1s))` 驱动，见 `update::heartbeat`）：每秒醒一次、推进一拍 +//! presenter（内部按 33 ms 折算 30 拍，于是 `config_poll_due` 仍是「约 1 秒比对一次 mtime」）。 +//! +//! 为什么不用 `window::frames()` + 1 s 闸门来实现这个低频时钟：帧订阅**本身就是**自持重绘循环 +//! （iced_winit 处理完任何消息都 `request_redraw()`），闸门只能省掉 `advance()` 里的活，省不掉 +//! 整窗重绘——实测软件渲染约 **500 帧/秒**。心跳是「每秒一帧」，差三个数量级。 +//! +//! ## 已知代价（都登记，不藏） +//! +//! 1. **忙碌态仍是自持帧循环**：`Running`/`Busy` 一天不结束，就一天按帧刷（软件渲染实测约 +//! 970 帧/秒，refreshes 不增长 = 纯像素空转）。功能上需要 tick 来发现游戏退出，但「整段 +//! 运行期近千帧/秒重绘」是真实开销；要收口得让 `Running` 走更慢的时钟（follow-up）。 +//! 2. 心跳用 `thread::sleep` 占线程池一个线程 1 秒；1 Hz 下可接受，但不是优雅解法（正解仍是 +//! `iced::time::every` + tokio/smol，Cargo.toml 在 scope 外，已报 finding）。 + +use std::time::Instant; + +use iced::{window, Subscription}; + +use super::components::motion; +use super::message::Message; +use super::state::App; + +impl App { + /// 本次进程的订阅表。 + pub(super) fn subscription(&self) -> Subscription { + let frames = if self.needs_frames() { + window::frames().map(|_| Message::Frame) + } else { + Subscription::none() + }; + + // 断点 600 / 840 要跟着真窗口宽度走；截图模式的窗口尺寸由参数钉死，不吃 resize。 + let events = if self.has_screenshot() { + Subscription::none() + } else { + window::events().map(|(_, event)| Message::Window(event)) + }; + + // 键盘（M104）：`Esc` 收栗 / `Tab` 走焦点环 / `Enter` 激活焦点键。 + // + // 为什么订阅整条键盘流而不是自己挑键：`iced::keyboard::listen()` 是唯一的全窗键盘入口， + // 挑键与「什么状态下该做什么」的解释权放在 `app/update/agent.rs`（一眼看完）， + // 订阅表只负责搬运。截图通道不开它——D30 要可复现，键盘事件一个都不该进图。 + let keys = if self.has_screenshot() { + Subscription::none() + } else { + iced::keyboard::listen() + .map(|event| Message::Agent(crate::shell::agent::Message::Key(event))) + }; + + Subscription::batch([frames, events, keys]) + } + + /// 是否订阅帧事件（= 截图模式要帧数闸门）。 + pub(super) fn wants_frames(&self) -> bool { + self.has_screenshot() + } + + /// 现在要不要**时钟**（见模块文档的表）。 + pub(super) fn needs_frames(&self) -> bool { + self.has_screenshot() + // M192：只有动画在跑时才多这一条（帧泵清空轨道后立刻为假 ⇒ 退回 1 Hz 心跳）。 + || motion::needs_frames() + || !self.state.toasts.is_empty() + || !self.state.running().is_empty() + // M175：Java 扫描进行中（进度 3/7 要动起来，否则用户只看到「正在扫描」卡着）。 + || self.settings.java.scanning.is_some() + || self + .watch_until + .is_some_and(|deadline| Instant::now() < deadline) + } +} +#[cfg(test)] +mod tests { + //! 帧订阅的**有界**守卫（M192）：动画期间订阅、结束即退订、关掉动效一帧都不订阅。 + //! + //! ## 这一组按**运行时顺序**写（M192 r1 复审 P1-1 的教训） + //! + //! 第一版这里是「先 `motion::enter(...)` 再问 `needs_frames()`」——而 iced 的真实顺序是 + //! 「`update()`（订阅表在这里求值）→ `view()`」，于是这条守卫全绿、生产路径上却根本播不出来。 + //! 现在全部改走**真消息**：`app.update(Message::Page(Navigate(..)))` 之后再问订阅表， + //! 而且断言 `watch_until` 仍是 `None`（排除「观察窗顺手开了帧」这条假绿）。 + //! + //! 时间轴用 `motion::advance_by` 摆（不等真实时钟），每个用例在自己的线程上跑，互不干扰。 + + use super::*; + use crate::app::components::motion::{Slot, FRAME_MS}; + use crate::cli::Options; + use crate::pages; + use crate::theme::Families; + use unlucky_design::color::SchemeFlavor; + use unlucky_design::motion::MotionScale; + use unlucky_presenter::mock::MockBackend; + use unlucky_presenter::router::Route; + use unlucky_presenter::settings_bridge::SettingsBridge; + + const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", + }; + + /// 不碰磁盘、后端是 mock 的 App（与 `app/tests.rs` 的 `headless` 同构）。 + fn headless() -> App { + App::with_presenter( + Options::default(), + FAMILIES, + SchemeFlavor::Light, + Box::new(MockBackend::new()), + SettingsBridge::memory_only(), + ) + } + + /// 走到「真·空闲」：没有观察窗、没有忙碌实例、没有动画（首屏那一条 Boot 已跑完）。 + /// + /// `Boot` 自己就会起跑一次首屏动效（`on_boot` → `sync_motion`），所以必须先把它推完， + /// 否则后面的 `assert!(!needs_frames())` 测的是「动画还在跑」而不是「空闲」。 + fn idle_app() -> App { + motion::reset(); + motion::configure(MotionScale::STANDARD, None); + let mut app = headless(); + // 有窗口才谈得上动效（`sync_motion` 在没有窗口时直接返回，见它的文档） + app.window = Some(iced::window::Id::unique()); + let _ = app.update(Message::Boot); + app.watch_until = None; + run_until_idle(); + assert!(!motion::needs_frames(), "前提：首屏动效已经跑完"); + app + } + + /// 把时间轴推到全部轨道结束（每步 16 ms，上限 20 s）。 + fn run_until_idle() { + for _ in 0..1250 { + if !motion::needs_frames() { + return; + } + motion::advance_by(FRAME_MS); + } + } + + /// **按运行时顺序**：空闲态一条消息进来（换页）⇒ **同一拍**订阅表就要有帧；跑完立刻退订。 + /// + /// 变异证明：把起跑搬回 `view`（删掉 `App::update` 里的 `sync_motion`）⇒ 第一步的 + /// `assert!(app.needs_frames())` 红；把 `Pump::advance` 的「到期即删除」删掉 ⇒ 最后一步红。 + #[test] + fn a_state_change_opens_the_frame_subscription_in_the_same_tick() { + let mut app = idle_app(); + assert!(!app.needs_frames(), "前提：空闲交互态本来就不订阅帧"); + + // 用户点了一次导航轨：**一条**消息，之后不再补任何消息 + let _ = app.update(Message::Page(pages::Message::Navigate(Route::Download))); + + assert!( + app.watch_until.is_none(), + "换页不该打开观察窗（这里要证明帧是**动效**要来的，不是派发顺手开的）" + ); + assert!(motion::needs_frames(), "换页必须在同一拍起跑"); + assert!( + app.needs_frames(), + "同一拍的订阅表必须能看见轨道（iced 先算订阅表、后建视图 —— 复审 P1-1）" + ); + + run_until_idle(); + assert!(!motion::needs_frames(), "动画跑完帧泵必须清空"); + assert!( + !app.needs_frames(), + "动画结束后必须退回 1 Hz 心跳（占着帧订阅 = 空闲烧帧）" + ); + motion::reset(); + } + + /// 列表 ↔ 详情同样走「一条消息 ⇒ 当拍有帧」，且 `Detail` 槽真的是那条。 + #[test] + fn opening_a_detail_also_opens_the_frames_in_the_same_tick() { + let mut app = idle_app(); + // 出厂快照会自动选中第一条 ⇒ 先回列表，让「点进详情」真的是一次详情变化 + let _ = app.update(Message::Page(pages::Message::Navigate(Route::Instances))); + run_until_idle(); + assert!(!app.needs_frames()); + let _ = app.update(Message::Page(pages::Message::Navigate(Route::Detail( + "survival".to_string(), + )))); + assert!(app.needs_frames(), "点进详情必须当拍订阅帧"); + run_until_idle(); + assert!(!app.needs_frames()); + motion::reset(); + } + + /// 账户页 / AI 独立页**不归 pages 画**：切过去不起跑（否则白跑 300 ms 帧）；切回来照旧跑。 + #[test] + fn pages_that_render_elsewhere_do_not_start_a_track() { + let mut app = idle_app(); + let _ = app.update(Message::Page(pages::Message::Navigate(Route::Accounts))); + assert!( + !motion::needs_frames(), + "账户页没有 pages 树可动，不许白开帧" + ); + + let _ = app.update(Message::Page(pages::Message::Navigate(Route::Instances))); + assert!(motion::needs_frames(), "从账户页回到某一屏仍然是换页，要跑"); + run_until_idle(); + motion::reset(); + } + + /// **没有窗口就不起跑**：`window::frames()` 在没窗口时一条消息都不会有，起跑只是白占一档； + /// 首屏那一条也因此要等窗口到了才算「第一眼」。 + #[test] + fn without_a_window_nothing_animates() { + motion::reset(); + motion::configure(MotionScale::STANDARD, None); + let mut app = headless(); + assert!(app.window.is_none(), "前提：还没拿到窗口句柄"); + let _ = app.update(Message::Boot); + app.watch_until = None; + assert!(!motion::needs_frames(), "没有窗口 ⇒ 不许起跑"); + + // 窗口来了：首屏入场这时才开始（不是被启动期那棵空树吃掉） + let _ = app.update(Message::WindowReady(Some(iced::window::Id::unique()))); + assert!(app.needs_frames(), "窗口到了之后「首屏」才起跑"); + run_until_idle(); + motion::reset(); + } + + /// **`MotionScale::NONE` 真的零订阅**：不是「跑一遍 0 时长动画」。 + /// + /// 变异证明：把 `Pump::play` 的 `is_off()` 分支删掉 ⇒ 帧采样次数非 0，本用例红。 + #[test] + fn no_scale_requests_no_frames_at_all() { + motion::reset(); + let mut app = headless(); + app.window = Some(iced::window::Id::unique()); + let _ = app.update(Message::Boot); + app.watch_until = None; + motion::configure(MotionScale::NONE, None); + + // 三种状态变化：换页 / 换详情 / 再换回来 + let _ = app.update(Message::Page(pages::Message::Navigate(Route::Download))); + assert!(!app.needs_frames(), "关掉动效后换页一帧都不该订阅"); + let _ = app.update(Message::Page(pages::Message::Navigate(Route::Detail( + "survival".to_string(), + )))); + assert!(!app.needs_frames()); + run_until_idle(); + + assert!(!motion::needs_frames()); + assert_eq!(motion::samples(), 0, "NONE 档的帧采样次数必须是 0"); + motion::reset(); + } + + /// 帧订阅在**产品接线**里只出现一处：五条理由共享同一个布尔，所以不会出现「动画与 Busy 各订一条」。 + /// + /// 口径是**全仓 `src/**`**（复审 r1 备注：只扫 `subscription.rs` 抓不到别人另开订阅），只看 + /// 代码行（注释/文档里提到这个符号不算）。唯一允许的第二个文件是 `pages/harness.rs`—— + /// 那是 `pages_demo` 这条**独立 example** 自己的 iced app（不接 `App`、不进产品路径）。 + #[test] + fn there_is_exactly_one_frame_subscription() { + let src = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("src"); + let mut files = Vec::new(); + collect_rust_files(&src, &mut files); + assert!( + files.len() >= 40, + "只扫到 {} 个文件：扫描逻辑坏了", + files.len() + ); + + let mut hits = Vec::new(); + for path in files { + let text = std::fs::read_to_string(&path).expect("读源文件"); + let product = text.split("#[cfg(test)]").next().unwrap_or(&text); + let code = product + .lines() + .filter(|line| !line.trim_start().starts_with("//")) + .collect::>() + .join( + " +", + ); + let count = code.matches("window::frames()").count(); + if count > 0 { + let name = path + .strip_prefix(&src) + .unwrap_or(&path) + .to_string_lossy() + .replace(std::path::MAIN_SEPARATOR, "/"); + hits.push((name, count)); + } + } + + hits.sort(); + let expected = [ + ("app/subscription.rs".to_string(), 1_usize), + ("pages/harness.rs".to_string(), 1_usize), + ]; + assert_eq!( + hits, expected, + "`window::frames()` 只许出现在 `app/subscription.rs`（产品接线）\ + 与 `pages/harness.rs`（独立 example 的自有 app），且各一处" + ); + } + + /// 递归收集 `dir/**/*.rs`。 + fn collect_rust_files(dir: &std::path::Path, out: &mut Vec) { + for entry in std::fs::read_dir(dir).expect("读目录") { + let path = entry.expect("目录项").path(); + if path.is_dir() { + collect_rust_files(&path, out); + } else if path.extension().is_some_and(|ext| ext == "rs") { + out.push(path); + } + } + } + + /// 槽枚举的可见性检查：`Slot` 只经帧泵导出（页面拿不到「给我 250ms」这种口子）。 + #[test] + fn slots_are_the_three_documented_ones() { + assert_eq!(Slot::ALL.len(), 3); + assert_eq!(Slot::ALL.map(Slot::name), ["boot", "screen", "detail"]); + } +} diff --git a/crates/app-iced/src/app/tests.rs b/crates/app-iced/src/app/tests.rs new file mode 100644 index 0000000..a86769e --- /dev/null +++ b/crates/app-iced/src/app/tests.rs @@ -0,0 +1,386 @@ +//! `app` 的单测：主题切换、窗口尺寸、截图闸门、gallery 能构图，以及**presenter 接线的闭环**。 +//! +//! 闭环测试用的是 `MockBackend`（presenter 自带的假后端）：它走的是与真 host 完全相同的 +//! `dispatch → drain_events → AppState::apply → 视图模型` 通道，所以「点 Play → 状态真的变」 +//! 这件事在这里就能判死，不必等图形环境。 + +use unlucky_design::color::SchemeFlavor; +use unlucky_presenter::mock::MockBackend; +use unlucky_presenter::router::Route; +use unlucky_presenter::settings_bridge::SettingsBridge; + +#[cfg(test)] +mod appearance; +#[cfg(test)] +mod instances_save_loop; +#[cfg(test)] +mod presenter; + +use super::message::Message; +use super::state::App; +use super::{APP_TITLE, WINDOW_SIZE}; +use crate::cli::{Options, Screen}; +use crate::pages; +use crate::shell::agent::RailState; +use crate::shell::NavItem; +use crate::theme::Families; + +const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", +}; + +/// 不碰磁盘的 App（mock 后端 + 内存设置桥）。 +fn headless(options: Options, flavor: SchemeFlavor) -> App { + App::with_presenter( + options, + FAMILIES, + flavor, + Box::new(MockBackend::new()), + SettingsBridge::memory_only(), + ) +} + +fn screenshot_options() -> Options { + Options { + screenshot: Some(std::path::PathBuf::from("x.png")), + ..Options::default() + } +} + +#[test] +fn switching_flavor_rebuilds_styles_but_keeps_ui_state() { + let mut app = headless(Options::default(), SchemeFlavor::Light); + app.state.navigate(Route::Logs); + app.refresh_view(); + assert_eq!(app.ui().name(), "ull-silver"); + + app.set_flavor(SchemeFlavor::Dark); + + assert_eq!(app.ui().name(), "ull-ink", "切主题要换主题名"); + assert_eq!(app.state.route(), &Route::Logs, "切主题不许重置 UI 状态"); + assert_eq!(app.view.screen, pages::Screen::Logs, "视图模型跟着路由"); + assert!(app.options.screenshot.is_none(), "切主题不许改启动参数"); +} + +#[test] +fn window_size_is_the_acceptance_size() { + assert_eq!((WINDOW_SIZE.width, WINDOW_SIZE.height), (1180.0, 760.0)); + assert_eq!(APP_TITLE, "Unlucky Launcher"); +} + +#[test] +fn screenshot_mode_never_waits_for_the_system_theme() { + // 门禁依赖：CI 的 runtime-smoke 不带主题，xvfb 里也没有主题会话。 + let options = screenshot_options(); + assert!(!options.wants_system_theme(), "截图模式不许等系统主题"); + assert_eq!(options.capture_flavor(), Some(SchemeFlavor::Light)); + + let app = headless(options, SchemeFlavor::Light); + assert!(app.has_screenshot() && app.ui().name() == "ull-silver"); +} + +#[test] +fn gallery_screen_builds_a_tree() { + assert_eq!(Options::default().screen, Screen::Shell, "默认仍是产品骨架"); + let options = Options { + screen: Screen::Gallery, + ..Options::default() + }; + let app = headless(options, SchemeFlavor::Light); + // 真实像素由 `--screen=gallery --screenshot` 出图 + `gallery::probe` 量 + let _ = app.view(); +} + +#[test] +fn frames_are_only_requested_in_screenshot_mode() { + let mut app = headless(Options::default(), SchemeFlavor::Light); + assert!(!app.wants_frames(), "普通运行不订阅帧，避免每帧重绘"); + + app.options.screenshot = Some(std::path::PathBuf::from("x.png")); + assert!( + app.wants_frames(), + "截图模式必须订阅帧事件才能在第 3 帧出图" + ); +} + +// --------------------------------------------------------------- P2-1 按需节拍 + +/// 空闲态**不要每帧节拍**（但要有 1 Hz 心跳）。 +/// +/// 意图与 r2 那条 `an_idle_app_asks_for_no_clock` 一致：空闲时不许按帧循环跑（那会以每秒几百帧 +/// 的速度重绘整窗），改成「低频心跳」。断言拆成两半： +/// +/// 1. `needs_frames()` 为假 ⇒ **不订阅** `window::frames()`； +/// 2. 空闲时钟的周期 = [`IDLE_TICK`] = 1 s，且心跳每拍推进的 tick 预算 = 30（= 1 s / 33 ms）， +/// 这样 `theme::config_poll_due`（30 拍）仍是「约 1 秒比对一次 mtime」。 +/// +/// 抓得住：有人把「无条件订阅帧」改回来（第 1 半红）；有人把心跳周期改快/改慢（第 2 半红）。 +/// 抓不住：真实窗口的重绘次数（那要 `ULL_TICK_TRACE=1` 跑一次交互模式看日志，见报告）。 +#[test] +fn an_idle_app_uses_a_slow_heartbeat_instead_of_frames() { + let app = headless(screenshot_options(), SchemeFlavor::Light); + assert!(app.needs_frames(), "截图通道永远要帧（第 3 帧落盘）"); + + let mut idle = headless(Options::default(), SchemeFlavor::Light); + let _ = idle.update(Message::Boot); + assert!( + idle.needs_frames(), + "Boot 刚派发过 RefreshAll：3 秒观察窗内要节拍（等真 host 的首批事件）" + ); + + // 观察窗过期、也没有忙碌实例 ⇒ 空闲态不订阅帧事件（改走 1 Hz 心跳） + idle.watch_until = None; + assert!(!idle.needs_frames(), "空闲交互态：不订阅帧事件（只有心跳）"); + + // 派发之后观察窗重新打开 + let _ = idle.update(Message::Page(pages::Message::Navigate(Route::Detail( + "survival".to_string(), + )))); + let _ = idle.update(Message::Page(pages::Message::Launch( + "survival".to_string(), + ))); + assert!(idle.needs_frames(), "派发后观察窗内要有节拍"); + + // 进入 Busy 之后由「忙碌实例」这个条件自己续订（不靠观察窗） + idle.watch_until = None; + assert!( + idle.needs_frames(), + "有 Busy 实例时即便观察窗过期也要继续 tick" + ); +} + +/// 心跳的**节奏**：1 Hz，且每拍折算 30 个 33 ms 单位 ⇒ `config_poll_due` ≈ 每秒一次。 +/// +/// 抓得住：心跳周期常量、以及 `advance()` 里「按流逝时间折算 ticks」这条记账（改回 +/// `ticks += 1` 会让空闲态的配置轮询变成 30 秒一次，这条就红）。 +/// 抓不住：`Task::perform` 那条自续链真的每秒触发一次（那是运行期 trace 的事，见报告）。 +#[test] +fn the_idle_heartbeat_budgets_one_config_poll_per_second() { + use unlucky_presenter::theme::config_poll_due; + + assert_eq!( + super::state::IDLE_TICK, + std::time::Duration::from_secs(1), + "空闲心跳周期必须是 1 s" + ); + + let mut app = headless(Options::default(), SchemeFlavor::Light); + let _ = app.update(Message::Boot); + app.watch_until = None; + + // 一次空闲心跳（1 s）之后：ticks 增加 30，且正好落在 config 轮询点上 + let before = app.ticks; + app.advance(super::state::IDLE_TICK); + assert_eq!(app.ticks - before, 30, "1 s 应折算 30 个 33 ms 拍"); + assert!( + config_poll_due(app.ticks), + "空闲心跳每拍都要落在 config 轮询点上（ticks={}）", + app.ticks + ); +} + +/// 空闲态每拍**不再重建视图模型**（P2-1 的另一半：`refresh_view` 的 30 Hz × N 实例白克隆）。 +/// +/// 抓得住：把 `advance()` 里的 `if self.view_dirty` 去掉（改回无条件 `refresh_view()`）时， +/// 这条断言里的 `refreshes` 会从「不增长」变成「每拍 +1」。 +/// 抓不住：「重建一次花了多少微秒」（没有基准测试；量级判断见报告）。 +#[test] +fn idle_ticks_do_not_rebuild_the_view_model() { + let mut app = headless(Options::default(), SchemeFlavor::Light); + let _ = app.update(Message::Boot); + + let before = app.refreshes; + for _ in 0..100 { + app.advance(super::state::TICK); + } + assert_eq!( + app.refreshes, + before, + "空闲 100 拍：视图模型一次都不该重建（实际 +{}）", + app.refreshes - before + ); + + // 有事件进来时仍然要重建（否则页面不刷新） + let _ = app.update(Message::Page(pages::Message::Navigate(Route::Logs))); + assert!(app.refreshes > before, "导航之后必须重建一次"); +} +/// 视图模型跟着窗口宽度走（交互模式下 600 / 840 两条断点靠 resize 事件生效）。 +/// +/// M104 起 `view.window_width` 装的是**中栗可用宽度**（窗口 − 右栗 − 拖拽缝），所以这里按三档 +/// 各钉一个**字面量**：48 的折叠条与 320 的面板各自的减法都得对。 +/// （断言里不调 `agent.content_width(..)`——那是同义反复，实现错一处它照样绿。） +#[test] +fn resizing_the_window_rebuilds_the_view_model() { + let mut app = headless(Options::default(), SchemeFlavor::Light); + let _ = app.update(Message::Boot); + + // 出厂是 Collapsed(48) 档：中栗 = 窗口 − 48 + let _ = app.update(Message::Window(iced::window::Event::Resized( + iced::Size::new(1180.0, 760.0), + ))); + assert!( + (app.view.window_width - 1132.0).abs() < f32::EPSILON, + "1180 − 48（折叠条）= 1132，实际 {}", + app.view.window_width + ); + + let _ = app.update(Message::Window(iced::window::Event::Resized( + iced::Size::new(700.0, 600.0), + ))); + assert!( + (app.view.window_width - 652.0).abs() < f32::EPSILON, + "700 − 48（折叠条）= 652，实际 {}", + app.view.window_width + ); + + // Expanded(320) 档：中栗 = 窗口 − 320（面板）− 8（拖拽缝）= 852 + app.agent.expand(); + app.view_dirty = true; + app.refresh_view(); + assert!( + (app.view.window_width - 652.0).abs() < f32::EPSILON, + "700 上展开档不成立（上限 700 − 88 − 472 − 8 = 132 < 280）⇒ 实际按折叠条 48 算： 700 − 48 = 652，实际 {}", + app.view.window_width + ); + let _ = app.update(Message::Window(iced::window::Event::Resized( + iced::Size::new(1180.0, 760.0), + ))); + assert!( + (app.view.window_width - 852.0).abs() < f32::EPSILON, + "1180 − 320 − 8 = 852，实际 {}", + app.view.window_width + ); + + // Detached 档：右栗不占宽，中栗 = 窗口 = 1180。 + // **必须走路由**（`Select(Ai)`）：r1 之后「档位 = Detached」与「路由 = Agent」是一条不变式， + // 直接 `agent.detach()` 再手工 refresh 会被 `sync_agent_route` 立刻收回右栗（那正是要的语义）。 + let _ = app.update(Message::Select(NavItem::Ai)); + app.view_dirty = true; + app.refresh_view(); + assert!( + (app.view.window_width - 1180.0).abs() < f32::EPSILON, + "拆出后右栗不占宽：1180 − 0 = 1180，实际 {}", + app.view.window_width + ); + // 页面照旧能构图（窄窗退化到单列，不 panic） + let _ = app.view(); +} + +/// **不变式（复审 r1 的 P2-1）**：`Route::Agent` ⟺ `RailState::Detached`。 +/// +/// 走的是**真实路由入口**（外壳导航第五项 `Assistant` → `Message::Select(NavItem::Ai)`），不是 +/// 直接调 `agent.detach()`：r1 复现的 bug 正是「导航进页面时档位没变」，只测 `detach()` 抓不到它。 +/// +/// 抓得住：①进独立页后档位 = Detached（页头才会是 `Dock back` 而不是 `Open assistant`/`Pop out`）； +/// ②未读在进页时清零；③`Esc` 在独立页真的离开（不是只把档位改成折叠）；④从页上点别的导航， +/// 会话收回右栗（档位不再停在 Detached）。 +/// 抓不住：按钮在像素上长什么样（那要出图，见 `13/14` 两张）。 +#[test] +fn entering_the_agent_route_detaches_the_rail() { + let mut app = headless(Options::default(), SchemeFlavor::Light); + let _ = app.update(Message::Boot); + assert_eq!(app.agent.rail, RailState::Collapsed, "出厂是折叠档"); + // M119：出厂没有样本会话，未读由 presenter 按真事件累加 ⇒ 出厂就是 0 + assert_eq!(app.agent_host.rail().unread, 0, "出厂 0 条未读"); + + // ① 外壳导航第五项（真实入口） + let _ = app.update(Message::Select(NavItem::Ai)); + assert_eq!(app.state.route(), &Route::Agent); + assert_eq!( + app.agent.rail, + RailState::Detached, + "进了独立页，档位必须是 Detached——否则页头会画右栗才有的动作" + ); + assert_eq!(app.agent_host.rail().unread, 0, "进独立页即读"); + + // ③ Esc 真的离开这一页 + let _ = app.update(Message::Agent(crate::shell::agent::Message::Escape)); + assert_ne!(app.state.route(), &Route::Agent, "独立页上 Esc 必须离开"); + assert_eq!(app.agent.rail, RailState::Expanded, "收回到右栗展开档"); + + // ④ 从独立页点别的导航：会话收回右栗（档位不能停在 Detached） + let _ = app.update(Message::Select(NavItem::Ai)); + assert_eq!(app.agent.rail, RailState::Detached); + let _ = app.update(Message::Select(NavItem::Instances)); + assert_eq!(app.state.route(), &Route::Instances); + assert_eq!( + app.agent.rail, + RailState::Expanded, + "离开独立页 ⇒ 会话收回右栗（否则页走了、栏还是 0 宽）" + ); +} + +/// 同一条不变式的另一个入口：页面层的 `Navigate(Route::Agent)`（右栗里的 `pages::Message` 路径）。 +#[test] +fn the_page_navigation_entry_also_detaches() { + let mut app = headless(Options::default(), SchemeFlavor::Light); + let _ = app.update(Message::Boot); + // 走真消息（不是直接改字段）：这样「展开即读」的 `agent_mark_read` 也会真的发生 + let _ = app.update(Message::Agent(crate::shell::agent::Message::Expand)); + assert_eq!(app.agent.rail, RailState::Expanded); + + let _ = app.update(Message::Page(pages::Message::Navigate(Route::Agent))); + assert_eq!(app.state.route(), &Route::Agent); + assert_eq!(app.agent.rail, RailState::Detached); + assert_eq!(app.agent_host.rail().unread, 0); + + // 页面层回退（不是 Dock 消息）也要把档位收回来 + let _ = app.update(Message::Page(pages::Message::Navigate(Route::Instances))); + assert_eq!(app.agent.rail, RailState::Expanded); +} + +/// 截图模式不读设置文件里的主题（D30 可复现：两台机器出同一张图）。 +#[test] +fn screenshot_mode_ignores_the_settings_file_theme() { + let mut app = headless(screenshot_options(), SchemeFlavor::Light); + app.apply_config_theme(); + assert_eq!(app.ui().name(), "ull-silver", "截图模式的主题只认命令行"); +} + +/// 主题优先级：`--theme` > 配置文件 `appearance.theme_mode` > 系统主题。 +/// +/// r2 之前 `Message::SystemTheme` 无条件 `set_flavor`，于是「配置文件写 dark、系统是浅色」会 +/// 出现 `light -> dark -> light` 的一次抖动、配置永远不生效（r3 做 P2-2 的配置热切实测时暴露 +/// 出来，一并修）。 +/// +/// 抓得住：系统主题不许盖掉显式配置/命令行给出的主题（三条分支各一条断言）。 +/// 抓不住：真实桌面切换系统主题时的事件时序（只有消息级验证）。 +#[test] +fn the_system_theme_never_overrides_an_explicit_one() { + use unlucky_presenter::prefs::ThemeMode; + + // ① auto（内存桥默认）：系统主题说了算 + let mut auto = headless(Options::default(), SchemeFlavor::Light); + assert_eq!(auto.theme_mode, ThemeMode::Auto); + let _ = auto.update(Message::SystemTheme(iced::theme::Mode::Dark)); + assert_eq!(auto.ui().name(), "ull-ink", "auto 模式要跟随系统"); + + // ② 配置文件显式 dark：系统给浅色也不许改 + let mut pinned = headless(Options::default(), SchemeFlavor::Dark); + pinned.theme_mode = ThemeMode::Dark; + let _ = pinned.update(Message::SystemTheme(iced::theme::Mode::Light)); + assert_eq!( + pinned.ui().name(), + "ull-ink", + "配置文件说 dark，系统说 light：不许改" + ); + + // ③ 命令行 `--theme` 优先级最高 + let mut explicit = headless( + Options { + theme: Some(SchemeFlavor::Dark), + ..Options::default() + }, + SchemeFlavor::Dark, + ); + let _ = explicit.update(Message::SystemTheme(iced::theme::Mode::Light)); + assert_eq!( + explicit.ui().name(), + "ull-ink", + "--theme 优先级最高，系统主题不许盖" + ); +} + +mod theme; 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..5f05438 --- /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-silver"); + let baseline = crate::theme::Ui::new(SchemeFlavor::Light, FAMILIES); + assert_ne!( + app.ui().color(unlucky_design::color::Role::Primary), + baseline.color(unlucky_design::color::Role::Primary) + ); + std::fs::remove_dir_all(&dir).ok(); +} + +/// 抓得住：设置页在有外观状态时能真的构图（真控件树，含文本框/滑块/互斥按钮），并且 +/// 「外观」分组的下标与 `appearance::APPEARANCE_GROUP` 一致（点左列能切过去）。 +/// 抓不住：这些控件点下去之后的交互（`Message` 的落点由 `on_appearance` 的其它测试管）。 +#[test] +fn the_settings_page_renders_the_real_appearance_group() { + let mut app = headless(Options::default(), SchemeFlavor::Light); + app.state + .navigate(unlucky_presenter::router::Route::Settings); + app.refresh_view(); + assert_eq!(app.view.screen, Screen::Settings); + assert_eq!(app.appearance.selected_group, appearance::APPEARANCE_GROUP); + + let _tree = pages::page_with_appearance(&app.ui, &app.view, &app.appearance, &app.launch_form); + drop(_tree); + + // 切分组：只改视图状态，不落盘（`Change::SelectGroup` 的 key() == None）。 + app.appearance.apply(Change::SelectGroup(0)); + assert_eq!(app.appearance.selected_group, 0); + let _tree = pages::page_with_appearance(&app.ui, &app.view, &app.appearance, &app.launch_form); +} + +/// **P2-2 的守门（复审 r1）**：面板 α 只作用到允许半透明的层。 +/// +/// 抓得住：`Ui::layer(Canvas)` 在 α=0.55 时仍是不透明（标题栏/导航轨/页头带都取 Canvas， +/// 它们一旦透底，三个窗口键与导航文字就压在背景照片上）；`Card` / `Overlay` 必须真的吃到 α。 +/// 抓不住：真实合成后的观感（那由截图看）。 +#[test] +fn the_canvas_layer_stays_opaque_while_panels_take_the_alpha() { + use unlucky_design::elevation::MaterialLayer; + + let mut app = headless(Options::default(), SchemeFlavor::Light); + app.appearance.apply(Change::PanelAlpha(0.55)); + app.rebuild_ui(); + + let ui = app.ui(); + assert_eq!(ui.panel_alpha(), 0.55, "生效值进了 Ui"); + assert_eq!( + ui.layer(MaterialLayer::Canvas).a, + 1.0, + "窗口底（标题栏/导航轨/页头带）永远不透明——令牌的不变量" + ); + for layer in [MaterialLayer::Card, MaterialLayer::Overlay] { + assert!( + (ui.layer(layer).a - 0.55).abs() < 1e-6, + "{layer:?} 必须吃面板 α（实际 {}）", + ui.layer(layer).a + ); + } + + // CPU 档：α 被强制 1.0 ⇒ 连卡片也不透明。 + let mut cpu = headless( + Options { + backend: Backend::Cpu, + ..Options::default() + }, + SchemeFlavor::Light, + ); + cpu.appearance.apply(Change::PanelAlpha(0.55)); + cpu.rebuild_ui(); + assert_eq!(cpu.ui().layer(MaterialLayer::Card).a, 1.0, "CPU 档强制 1.0"); +} + +/// 抓得住：**把滑块从头拖到尾**（0.00 → 1.00 的 11 个档）时，状态里的整窗 α 与下发字节逐档单调 +/// 上升、且最低一档就是下限字节 21（= 0.0824 ≥ 0.08）、最后一档不透明（不给字节）。 +/// 这就是「拖动 → 实际 α」的链条在数值上的等价物；真机拖动的那一次由二进制日志举证。 +/// 抓不住：拖动的手感与真实观感（RDP 上不可信）。 +#[test] +fn a_slider_sweep_moves_the_alpha_and_the_byte_monotonically() { + let mut app = headless(Options::default(), SchemeFlavor::Light); + let mut bytes = Vec::new(); + for step in 0..=10 { + let fraction = step as f32 / 10.0; + let alpha = crate::pages::appearance::alpha::window_alpha_from_fraction(fraction); + app.appearance.apply(Change::WindowOpacity(alpha)); + let byte = app.appearance.window_alpha_byte(); + bytes.push(byte); + // 每一档都要能打出一行（数值而不是观感）。 + assert!(app.appearance.log_line("sweep").contains("window_alpha=")); + } + + assert_eq!(bytes[0], Some(21), "0% 一档 = 下限 0.08 → 21"); + assert_eq!(bytes[10], None, "100% 一档 = 不透明 → 不下发"); + let sent: Vec = 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/instances_save_loop.rs b/crates/app-iced/src/app/tests/instances_save_loop.rs new file mode 100644 index 0000000..1a350af --- /dev/null +++ b/crates/app-iced/src/app/tests/instances_save_loop.rs @@ -0,0 +1,145 @@ +//! 「启动参数保存失败」的**整环**回归（M157 r4 复审 P3-a）。 +//! +//! 仓里原来只有这条环的两半：`LaunchForm::sync` 的单测（本 crate 的 `pages/instances/state.rs`） +//! 与「Save 只派发不清脏」（`app/update/instances.rs`）。两半各自绿，但**接线**（消息 → +//! `dispatch` → 后端回事件 → `pump` → `refresh_view` → `sync_launch_form`）没有任何活着的断言。 +//! 把 `dirty = false` 提前到派发前，只有这条整环测试会红（单测两半都不会）。 +//! +//! 造的后端与真 host 的失败路径同形：收到 `SetInstanceLaunchArgs` 只回一条 Toast（错误的用户 +//! 可见反馈），**不回** `InstancesChanged`——盘上没改，快照还是旧的。 + +use std::cell::RefCell; +use std::rc::Rc; + +use unlucky_design::color::SchemeFlavor; +use unlucky_presenter::dto::{ + AppCommand, AppEvent, Backend, CoreEvent, InstanceRuntime, InstanceSummary, LaunchArgsView, + LoaderInfo, LoaderKind, +}; +use unlucky_presenter::router::Route; +use unlucky_presenter::settings_bridge::SettingsBridge; +use unlucky_presenter::toast::{Toast, ToastKind}; + +use crate::app::message::Message; +use crate::app::state::{App, TICK}; +use crate::cli::Options; +use crate::pages; +use crate::theme::Families; + +const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", +}; + +/// 失败路径的后端：命令进台账；`SetInstanceLaunchArgs` 只回一条错误 Toast。 +#[derive(Debug, Default)] +struct FailingSaveBackend { + dispatched: Rc>>, + queued: Vec, +} + +impl Backend for FailingSaveBackend { + fn drain_events(&mut self) -> Vec { + std::mem::take(&mut self.queued) + } + + fn dispatch(&mut self, command: AppCommand) { + self.dispatched.borrow_mut().push(command.clone()); + if matches!(command, AppCommand::SetInstanceLaunchArgs { .. }) { + // 真 host 在 `dispatch_inner` 的 Err 分支只发 toast（不发 InstancesChanged）。 + self.queued.push(AppEvent::Toast(Toast { + id: 0, + kind: ToastKind::Error, + text: "内存超出范围".to_string(), + remaining_ms: 0, + })); + } + } +} + +/// 盘上的实例快照：内存 4096、其余留空（= 保存失败时 pump 会带回来的那份）。 +fn snapshot() -> Vec { + vec![InstanceSummary { + id: "survival".to_string(), + name: "生存".to_string(), + mc_version: "1.20.4".to_string(), + loader: LoaderInfo { + kind: LoaderKind::Vanilla, + version: String::new(), + }, + last_played: None, + runtime: InstanceRuntime::Idle, + icon: None, + isolation: "isolated".to_string(), + version_id: "1.20.4".to_string(), + version_present: true, + launch: LaunchArgsView { + instance_id: "survival".to_string(), + memory_mb: Some(4096), + memory_effective_mb: 4096, + ..LaunchArgsView::default() + }, + }] +} + +fn app_with_snapshot() -> (App, Rc>>) { + let dispatched = Rc::new(RefCell::new(Vec::new())); + let backend = FailingSaveBackend { + dispatched: Rc::clone(&dispatched), + queued: vec![AppEvent::Core(CoreEvent::InstancesChanged(snapshot()))], + }; + let app = App::with_presenter( + Options::default(), + FAMILIES, + SchemeFlavor::Light, + Box::new(backend), + SettingsBridge::memory_only(), + ); + (app, dispatched) +} + +/// **保存失败不许吃掉草稿**（整环）：输入 `4g` → 点保存 → 后端回错误事件 → pump 重建视图。 +/// +/// 抓得住：①`Save` 在派发前清脏（草稿被旧快照覆盖成 4096）；②`LaunchForm::sync` 去掉 +/// `matches` 判据（同样覆盖）；③`pump` 没把事件喂进 `apply`/`refresh_view`（表单不会被播种， +/// 下面的前置断言会红）。 +/// 抓不住：真 host 的落盘失败（那是 `host::launch_args` 的单测射程）。 +#[test] +fn failed_save_keeps_the_draft_through_the_whole_loop() { + let (mut app, dispatched) = app_with_snapshot(); + + // 首屏快照到位 → 自动选中 → 表单按盘上的值播种。 + let _ = app.update(Message::Boot); + let _ = app.update(Message::Page(pages::Message::Navigate(Route::Detail( + "survival".to_string(), + )))); + app.advance(TICK); + assert_eq!(app.launch_form.memory, "4096", "首帧要按快照播种"); + assert!(!app.launch_form.dirty); + + // 用户把内存改成非法值（host 会拒），然后点保存。 + let _ = app.update(Message::Page(pages::Message::Instances( + pages::InstanceMessage::Memory("4g".to_string()), + ))); + assert_eq!(app.launch_form.memory, "4g"); + let _ = app.update(Message::Page(pages::Message::Instances( + pages::InstanceMessage::Save, + ))); + assert!( + dispatched + .borrow() + .iter() + .any(|command| matches!(command, AppCommand::SetInstanceLaunchArgs { .. })), + "保存要把命令派发出去" + ); + + // 失败回程：一条错误 Toast → pump → refresh_view → sync_launch_form（旧快照）。 + app.advance(TICK); + + assert_eq!( + app.launch_form.memory, "4g", + "保存失败后，pump 用旧快照把用户刚敲的内容冲掉了" + ); + assert!(app.launch_form.dirty, "草稿还在，脏标记也不能掉"); +} 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>>, + seeded: Vec, +} + +impl Backend for RecorderBackend { + fn drain_events(&mut self) -> Vec { + 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>>) { + 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/tests/theme.rs b/crates/app-iced/src/app/tests/theme.rs new file mode 100644 index 0000000..198b0f2 --- /dev/null +++ b/crates/app-iced/src/app/tests/theme.rs @@ -0,0 +1,187 @@ +//! 主题三档（Ink / Silver / 跟随系统）的落点测试（M229；从 `app/tests.rs` 拆出守 400 行）。 +//! +//! 这一份只管**用户点设置页那三枚 chip 之后**发生的事：换色板、同步设置组状态、落盘。 +//! `Auto`（跟随系统）那条路在 `app::tests::the_system_theme_never_overrides_an_explicit_one`。 + +use crate::app::message::Message; +use crate::app::state::App; +use crate::cli::Options; +use crate::pages; +use crate::theme::Families; +use unlucky_design::color::SchemeFlavor; +use unlucky_presenter::mock::MockBackend; +use unlucky_presenter::prefs::ThemeMode; +use unlucky_presenter::settings_bridge::SettingsBridge; + +const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", +}; + +/// 一个把配置写在临时文件里的 App：测「落盘」必须真的过文件（内存桥读回来永远是出厂值）。 +fn with_config() -> (App, std::path::PathBuf) { + let dir = std::env::temp_dir().join(format!("ull-theme-m229-{}", std::process::id())); + std::fs::create_dir_all(dir.join("config")).expect("临时目录"); + let path = dir.join("config/launcher.json"); + std::fs::write(&path, "{}").expect("写配置文件"); + + let app = App::with_presenter( + Options::default(), + FAMILIES, + SchemeFlavor::Light, + Box::new(MockBackend::new()), + SettingsBridge::with_path(&path), + ); + (app, dir) +} + +/// M229：设置页「通用 → 主题」三档（Ink / Silver / 跟随系统）真的换色板、真的落盘。 +/// +/// 抓得住：①`pages::Message::Theme` 没接进 `on_page`（点了没反应）②接了但不换 `Ui` +/// （只有选中态变了，界面颜色还是旧的）③同步设置组状态漏了（设置页首帧/刷新后画错档） +/// ④落盘漏了（重启回旧值——这里**真的过文件**：`with_config` 用 `SettingsBridge::with_path` 写临时 +/// 配置，再用同一路径重新 `load()` 读回；内存桥读回来永远是出厂值，验不了落盘）。 +/// 抓不住：色板好不好看、像素级差异（那要截图，见 `DevDocs/artifacts/m229/`）。 +#[test] +fn the_theme_message_switches_the_board_and_persists_it() { + let (mut app, dir) = with_config(); + assert_eq!(app.board_name(), "silver", "首帧是浅色主方案（Silver）"); + + // 选 Ink（= 深色主方案） + let _ = app.update(Message::Page(pages::Message::Theme(ThemeMode::Dark))); + assert_eq!(app.theme_mode(), ThemeMode::Dark); + assert_eq!(app.board_name(), "ink", "Ink 深板要真切过去"); + assert_eq!(app.ui().flavor(), SchemeFlavor::Dark); + assert_eq!( + app.settings.language_appearance.theme, + ThemeMode::Dark, + "设置页那一行的档位要跟着改" + ); + // 落盘：真的过了文件（重新打开同一个配置读回来就是 dark） + assert_eq!( + SettingsBridge::with_path(dir.join("config/launcher.json")) + .load() + .1, + ThemeMode::Dark, + "主题档要落盘" + ); + + // 选 Silver（= 浅色主方案） + let _ = app.update(Message::Page(pages::Message::Theme(ThemeMode::Light))); + assert_eq!(app.board_name(), "silver"); + assert_eq!(app.ui().flavor(), SchemeFlavor::Light); + assert_eq!( + SettingsBridge::with_path(dir.join("config/launcher.json")) + .load() + .1, + ThemeMode::Light + ); + + // 同一档再点一次：不许白重建 + let refreshes = app.refreshes; + let _ = app.update(Message::Page(pages::Message::Theme(ThemeMode::Light))); + assert_eq!(app.refreshes, refreshes, "同一档不该再重建视图模型"); + std::fs::remove_dir_all(&dir).ok(); +} + +/// **截图通道把主题档钉死在 `--screenshot-theme`**，不读机器上的 `launcher.json`（D30 可复现）。 +/// +/// 复审 r2 P2-a 指出：`construct.rs` 里新加的这条分支没有回归测试——于是「哪天有人把它改回 +/// `bridge.load().1`」不会有人发现，两次不同配置的机器又会出不同颜色的图。 +/// +/// 判据：**同一份截图参数 + 两份不同的机器配置 ⇒ 同一个档位**，且等于参数（浅→`Light`、深→`Dark`）； +/// 反证：非截图通道下同样两份配置**确实**分出两个档（否则这条测试等于没测到分支）。 +#[test] +fn the_screenshot_channel_pins_the_theme_mode_instead_of_reading_the_file() { + use std::path::{Path, PathBuf}; + + /// 写一份只含 `appearance.theme_mode` 的临时配置，并用它构造 App。 + fn with_mode( + dir_name: &str, + json: &str, + options: Options, + flavor: SchemeFlavor, + ) -> (App, PathBuf) { + let dir = + std::env::temp_dir().join(format!("ull-shot-theme-{dir_name}-{}", std::process::id())); + std::fs::create_dir_all(dir.join("config")).expect("临时目录"); + let path = dir.join("config/launcher.json"); + std::fs::write(&path, json).expect("写配置文件"); + let app = App::with_presenter( + options, + FAMILIES, + flavor, + Box::new(MockBackend::new()), + SettingsBridge::with_path(&path), + ); + (app, dir) + } + + fn cleanup(dir: &Path) { + std::fs::remove_dir_all(dir).ok(); + } + + let dark_file = r#"{"appearance":{"theme_mode":"dark"}}"#; + let light_file = r#"{"appearance":{"theme_mode":"light"}}"#; + + // ① 截图参数给浅色：机器配置是 dark 也一样出 Light（钉死值赢） + let shot_light = Options { + screenshot: Some(PathBuf::from("unused.png")), + screenshot_theme: Some(SchemeFlavor::Light), + ..Options::default() + }; + let (from_dark_file, d1) = with_mode( + "light-a", + dark_file, + shot_light.clone(), + SchemeFlavor::Light, + ); + let (from_light_file, d2) = with_mode("light-b", light_file, shot_light, SchemeFlavor::Light); + assert_eq!( + from_dark_file.theme_mode(), + ThemeMode::Light, + "截图模式下档位必须由 --screenshot-theme 决定，不许读文件里的 dark" + ); + assert_eq!( + from_dark_file.theme_mode(), + from_light_file.theme_mode(), + "两份机器配置必须出同一个档位" + ); + assert_eq!(from_dark_file.board_name(), "silver"); + assert_eq!(from_light_file.board_name(), "silver"); + + // ② 反方向：截图参数给深色 ⇒ 即使文件写 light 也是 Dark/Ink + let shot_dark = Options { + screenshot: Some(PathBuf::from("unused.png")), + screenshot_theme: Some(SchemeFlavor::Dark), + ..Options::default() + }; + let (from_light_file_dark, d3) = with_mode("dark-a", light_file, shot_dark, SchemeFlavor::Dark); + assert_eq!(from_light_file_dark.theme_mode(), ThemeMode::Dark); + assert_eq!(from_light_file_dark.board_name(), "ink"); + + // ③ 反证：非截图通道下，同样的两份配置**确实**分出两个档（证明这条分支真的存在） + let (interactive_dark, d4) = + with_mode("plain-a", dark_file, Options::default(), SchemeFlavor::Dark); + let (interactive_light, d5) = with_mode( + "plain-b", + light_file, + Options::default(), + SchemeFlavor::Light, + ); + assert_eq!( + interactive_dark.theme_mode(), + ThemeMode::Dark, + "产品路径要读文件" + ); + assert_eq!( + interactive_light.theme_mode(), + ThemeMode::Light, + "产品路径要读文件" + ); + + for dir in [d1, d2, d3, d4, d5] { + cleanup(&dir); + } +} diff --git a/crates/app-iced/src/app/update.rs b/crates/app-iced/src/app/update.rs new file mode 100644 index 0000000..ca9d02d --- /dev/null +++ b/crates/app-iced/src/app/update.rs @@ -0,0 +1,382 @@ +//! `update`：消息分支的**唯一**落点（含「用户动作 → 后端指令」的派发与事件回流）。 +//! +//! ## 数据流的三个入口（presenter crate 文档 §2） +//! +//! ```text +//! 用户动作 ──dispatch(AppCommand)──► backend ──► drain_events() ──► AppState::apply ──► 视图模型 +//! ▲ ▲ +//! └── pages::Message（导航/启动/停止）──────────────────┘ 忙碌 33 ms / 空闲 1 Hz +//! ``` +//! +//! 三条纪律： +//! +//! 1. **不做乐观回显**：点了「Play」不改本地状态，等 `InstanceRuntimeChanged` 事件回来才变 +//! （否则事件与本地状态打架时，磁贴与进度条会各说一套）； +//! 2. **状态只有一个写入口**：`AppState::apply`（事件）与 `AppState::navigate`（路由）； +//! 3. **只在状态变了才重建视图模型**：`refresh_view()` 是快照 → 页面的唯一转换点， +//! 由 `view_dirty` 门控（M90 r2/P2-1 起；此前是每拍无条件重建）。 +//! +//! ## 两个时钟（M90 r3 / P2-2） +//! +//! | 场景 | 时钟 | 周期 | 谁触发 | +//! |---|---|---|---| +//! | 截图 / **有动画在跑（M192）** / 有 Busy-Running 实例 / 有 toast / 派发后 3 s 观察窗 | `window::frames()` + 闸门 | 33 ms | [`App::needs_frames`] | +//! | 其余（空闲） | `Heartbeat` 自续链 | 1 s | [`App::heartbeat`] | +//! +//! 两条时钟不会同时干活：心跳在 `needs_frames()` 为真时**只续排、不推进**，忙碌结束自动接回。 +//! 动效那条**不新开循环**：它只是给同一个布尔加一个分支（有轨道才为真），轨道到期当场清空， +//! 下一拍就退回心跳（见 `components::motion`）。 + +use crate::app::components::motion; +use crate::app::diag::diag; +use std::time::Instant; + +use iced::{window, Task}; + +use unlucky_design::color::SchemeFlavor; +use unlucky_presenter::dto::AppCommand; +use unlucky_presenter::prefs::ThemeMode; +use unlucky_presenter::router::Route; + +use crate::pages; +use crate::renderer::Kind; + +use super::message::{route_of, Message}; +use super::state::{App, IDLE_TICK, TICK, WATCH_WINDOW}; +use super::CAPTURE_AT_FRAME; + +mod account; +// M223：导入已有版本向导（扫描 / 预检 / 确认 / 关闭 / 退回） +mod adopt; +mod agent; +mod appearance; +pub(super) mod boot_env; +mod clock; +mod content; +mod content_pack; +mod dialog; +mod dialog_fixture; +mod download; +mod instances; +mod motion_sync; +mod page_messages; +mod settings; +mod update_action; + +/// 这一条键盘事件是不是 `Esc` 按下。 +fn is_escape(event: &iced::keyboard::Event) -> bool { + matches!( + event, + iced::keyboard::Event::KeyPressed { + key: iced::keyboard::Key::Named(iced::keyboard::key::Named::Escape), + .. + } + ) +} + +impl App { + /// 一条消息进来，改状态并返回后续任务。 + /// + /// **分两段**：先派发（[`App::route_message`]），再同步一次动效的内容标识。第二段必须在 + /// `update` 里而不是 `view` 里：iced 求值订阅表**早于**建视图（`app/update/motion.rs` 的模块 + /// 文档有源码行号），在 `view` 里起跑的轨道当拍订阅不上，动画会退化成「一帧偏移 + 闪跳」。 + pub(super) fn update(&mut self, message: Message) -> Task { + let task = self.route_message(message); + self.sync_motion(); + task + } + + /// 把一条消息派发到它的落点（`update` 的正文；拆出来只为让 [`App::sync_motion`] 收尾）。 + fn route_message(&mut self, message: Message) -> Task { + match message { + Message::Boot => self.on_boot(), + Message::WindowReady(id) => { + self.window = id; + // M93：整窗 α 要 Win32 句柄，而 iced 只给 `window::Id`。`window::run` 是唯一能把 + // `&dyn Window`（实现了 `HasWindowHandle`）拿出来的入口。 + match id { + Some(id) => { + window::run(id, super::window_alpha::probe_hwnd).map(Message::WindowHandle) + } + None => Task::none(), + } + } + Message::WindowHandle(hwnd) => { + self.hwnd = hwnd; + match hwnd { + Some(_) => self.apply_window_alpha("boot"), + None => { + diag!("[appearance] hwnd=none（拿不到窗口句柄：整窗 α 无法下发）"); + self.log_appearance("boot", None); + } + } + // M116：圆角放在 α **之后**——α < 1 时那一步才补上 `WS_EX_LAYERED`， + // 先打圆角日志会把 `layered=` 记成 `off`（那正是我们要分辨的那一位）。 + self.apply_window_corner("boot"); + Task::none() + } + Message::SystemTheme(mode) => { + let flavor = match mode { + iced::theme::Mode::Dark => SchemeFlavor::Dark, + iced::theme::Mode::None | iced::theme::Mode::Light => SchemeFlavor::Light, + }; + diag!("[theme] 系统主题 = {mode:?}"); + // 优先级：`--theme` > 配置文件里的 `appearance.theme_mode` > 系统。 + // 早先这里无条件盖掉，于是「配置文件写 dark、系统是浅色」会出现 + // `light -> dark -> light` 的一次抖动，配置永远不生效（M90 r3 顺手修）。 + if self.options.theme.is_none() && self.theme_mode == ThemeMode::Auto { + self.set_flavor(flavor); + } + Task::none() + } + Message::Frame => self.on_frame(), + Message::Heartbeat => self.on_heartbeat(), + Message::Window(event) => { + match event { + window::Event::Resized(size) => { + self.width = size.width; + // 高度是背景平铺网格的视口判据之一（宽度早就有），以前只记宽是因为没有背景层。 + self.height = size.height; + self.view_dirty = true; + self.refresh_view(); + } + // M113: import/export —— 拖入整合包（本版唯一的选文件通道；窗口级事件， + // 所以入口收起时也照样接得住。细节在 `on_pack_dropped` / `on_pack_hover`） + window::Event::FileDropped(path) => return self.on_pack_dropped(path), + window::Event::FileHovered(_) => return self.on_pack_hover(true), + window::Event::FilesHoveredLeft => return self.on_pack_hover(false), + _ => {} + } + Task::none() + } + Message::Page(message) => self.on_page(message), + Message::Dialog(message) => dialog::on_dialog(self, message), + // M223：导入已有版本向导（打开 / 选版本 / 选目标 / 预检 / 确认 / 退回 / 关闭） + Message::Adopt(message) => self.on_adopt(message), + Message::Agent(message) => { + // `Esc` 先给弹窗：有弹窗时它属于「关掉这一层」，不属于 AI 栏的收起。 + if let crate::shell::agent::Message::Key(event) = &message { + if is_escape(event) && dialog::escape(self) { + return Task::none(); + } + } + self.on_agent(message) + } + // 外壳导航轨（`src/shell/nav.rs`）发来的点选：翻成同一次路由跳转 + Message::Select(nav) => { + self.state.navigate(route_of(nav)); + self.view_dirty = true; + self.refresh_view(); + Task::none() + } + Message::DragWindow => match self.window { + Some(id) => window::drag(id), + None => Task::none(), + }, + Message::ResizeStart(direction) => match self.window { + Some(id) => window::drag_resize(id, direction), + None => Task::none(), + }, + Message::Minimize => match self.window { + Some(id) => window::minimize(id, true), + None => Task::none(), + }, + Message::ToggleMaximize => match self.window { + Some(id) => window::toggle_maximize(id), + None => Task::none(), + }, + Message::Close => iced::exit(), + Message::Captured(screenshot) => self.on_captured(&screenshot), + Message::Demo(message) => { + // gallery 只是 harness：按下只打日志，不接业务（组件库要能脱离业务验收） + diag!("[gallery] {} pressed", message.id()); + Task::none() + } + } + } + + /// 启动：问窗口句柄 → 让后端发布首屏快照 → 决定主题。 + /// + /// **首屏快照在 `Boot` 就抽干**（不是等第一拍）：截图通道在第 3 帧落盘，33 ms 的节拍 + /// 未必来得及到达，等节拍会把空页面拍进图里。 + fn on_boot(&mut self) -> Task { + let mut tasks = vec![window::latest().map(Message::WindowReady)]; + + // M192：给动效帧泵定档（截图档关、CPU 档半速、GPU 档正常；`ULL_MOTION*` 可覆盖）。 + // 必须在第一次 `view()` 之前：页面主体的入场由 `pages::render` 采样，配置晚了首屏就没有动效。 + self.configure_motion(); + + // M117：启动日志一行 —— `[auth] msa client_id=configured|missing source=env|build|none`。 + // 判据（配没配 + 从哪来）在 `core::auth::microsoft::client_id_status()`，零网络； + // 本 crate 不直接依赖 core，所以经 `unlucky_cli`（已是本 crate 的依赖）出面， + // 免得 UI 侧把判据重算一遍、两份口径漂。日后看日志能一眼分辨 + // 「没配置」与「配了但登录失败」。 + diag!("{}", unlucky_cli::commands::msa_client_id_log_line()); + + // 主题优先级：显式 `--theme` / `--screenshot-theme` > 设置文件 > 系统。 + // 截图通道**不读设置文件**（D30 可复现：同一份代码在两台机器上要出同一张图）。 + self.apply_config_theme(); + + // M93 外观取证开关（`ULL_APPEARANCE_*`）+ 启动那一行数值日志。 + // 必须在 `refresh_view` 之前：设置页要画的就是这份状态。 + self.appearance.apply_env(); + self.rebuild_ui(); + self.log_appearance("boot", None); + // M187（r1 复审 P2-4）：启动这一拍的事实进启动器日志的缓冲（第一次启动时落盘）。 + boot_env::record_boot_log(self); + + // 交互模式且没显式指定主题 → 探系统；截图模式永不等（见 cli 模块文档） + if self.options.wants_system_theme() { + tasks.push(iced::system::theme().map(Message::SystemTheme)); + } + + // M104：助手栏的启动尾巴（窗口尺寸 adopt + 「拆出档直接落到独立页」）在 update/agent.rs。 + // **必须在 RefreshAll 之前**：那次 dispatch 会 `pump → auto_select`，把路由拉到实例详情， + // 而 `sync_agent_route` 看到「不在 Agent 页却还是 Detached」就会把档位收回来——顺序反了 + // 就会出现「`ULL_AGENT_RAIL=detached` 启动后停在实例页」（r2 实测踩到）。 + self.boot_agent(); + + // 「重新扫描实例目录 + 全部页面快照」：真 host 在这里发首批事件，mock 在构造时已预置 + self.dispatch(AppCommand::RefreshAll); + + // 取证开关 `ULL_START_ROUTE`：截图/冒烟直接落到某一页（`cli.rs` 不在本 mission 的 scope， + // 而「外观」分组只在设置页上，出矩阵必须能直达）。未知值忽略。 + if let Some(route) = boot_env::env_start_route() { + diag!("[boot] ULL_START_ROUTE → {route:?}"); + self.state.navigate(route); + // 直达某一页时不要再被「自动选中第一条实例」拉回详情页。 + self.auto_selected = true; + // M109：直达内容库时补一次检索（与页面内切换同一个入口） + self.ensure_content_loaded(); + } + account::force_account_state(self); + // M187：启动失败弹窗的取证夹具（`ULL_DIALOG_FIXTURE`），必须在 `refresh_view` 之前。 + if let Some(mode) = dialog_fixture::apply(self) { + diag!("[boot] ULL_DIALOG_FIXTURE → {mode}"); + } + + self.auto_select(); + self.view_dirty = true; + self.refresh_view(); + + // 空闲心跳从这里开始自续（它是唯一能在「没有帧事件」时戳醒 app 的时钟） + tasks.push(heartbeat()); + + Task::batch(tasks) + } + + /// M192：给帧泵定档（策略全在 [`boot_env::motion_scale`]，这里只搬输入）。 + fn configure_motion(&mut self) { + let pin = boot_env::env_motion_pin(); + let gpu = matches!( + super::backend::effective_kind(), + Some(crate::renderer::Kind::Wgpu) + ); + let scale = boot_env::motion_scale(self.options.screenshot.is_some(), gpu, pin.is_some()); + motion::configure(scale, pin); + // 打**帧泵实际拿到的**档位（不是刚算出的那个）：配置没生效时这一行会露馅。 + diag!( + "[motion] scale={:.2} pin={:?} gpu={} screenshot={}", + motion::scale().factor(), + pin, + gpu, + self.options.screenshot.is_some() + ); + } + + /// 空闲心跳：只有「不需要帧节拍」时才推进一拍，然后**无条件续排**下一拍。 + /// + /// 为什么无条件续排：忙碌结束（游戏退出、toast 过期、观察窗关闭）之后没有别的东西会叫醒 + /// app，心跳链必须一直在，才能把低频时钟接回去。忙碌期间它只是每秒醒一次、什么都不做。 + fn on_heartbeat(&mut self) -> Task { + // 动效时间轴也吃这一拍：窗口被遮挡 / 最小化 / 合成器不送绘制时，帧一个都不来，而 + // 「有轨道」又让下面的 1 Hz 推进整段停摆——那会让 `needs_frames()` 永远为真。心跳把 + // 轨道按单次上限（[`components::motion::pump::MAX_STEP_MS`]）推几步收尾，最坏的「没有帧」 + // 情况下 5 拍内自然退订；有帧时它只多推 64 ms/秒，看不出来。 + motion::advance(); + if !self.needs_frames() { + let now = Instant::now(); + let elapsed = now.saturating_duration_since(self.last_tick).max(IDLE_TICK); + self.last_tick = now; + self.advance(elapsed); + } + // M192 真机取证（`ULL_MOTION_FIXTURE_AT`）：到点就**真的**导航一次。放在 advance 之后 ⇒ + // 这一拍是货真价实的空闲态；跳转后由 `update` 收尾的 `sync_motion` 起跑（与点击同一条路）。 + self.motion_fixture_after_idle(); + heartbeat() + } + + /// 一帧画完：①动效时间轴推进 ②够 33 ms 就推进一拍 presenter ③截图模式在第 + /// [`CAPTURE_AT_FRAME`] 帧出图。 + /// + /// 时间闸门按**真实流逝时间**判（不是数帧）：掉帧不会把游戏启动进度拖慢， + /// 也不会在慢机器上把 1.5 s 的下载阶段拉成 4 s。 + fn on_frame(&mut self) -> Task { + self.frames += 1; + + // M192：动效时间轴。**每帧都调**，帧率上限在帧泵内部（16 ms 一次结算），所以忙碌态的 + // 近千 fps 不会变成近千次重排；动画结束后帧泵自动清空，下一拍订阅表就不再有 `frames()`。 + motion::advance(); + // 出图取证（`ULL_MOTION_FIXTURE`）：前两帧各做一次**真的**状态变化。 + // 没有这步，截图通道每一帧画的都是同一屏，页面切换 / 列表↔详情的入场就没有可拍的相位。 + // `ULL_MOTION_FIXTURE_AT`（真机空闲取证）在的时候**不跑**这一支：两条取证路互斥， + // 否则第 1 帧就把页面换成目标页，等 `_AT` 的心跳再跳同一个目标 = 标识没变 = 没有动效。 + if self.frames <= 2 && boot_env::env_motion_fixture_at().is_none() { + self.motion_fixture(); + } + + let now = Instant::now(); + let elapsed = now.saturating_duration_since(self.last_tick); + if elapsed >= TICK { + self.last_tick = now; + self.advance(elapsed); + } + + // 主题在启动时就已确定（截图模式必有主题，见 cli 模块文档），这里只剩帧数闸门 + if !self.wants_frames() || self.frames < CAPTURE_AT_FRAME { + return Task::none(); + } + + match self.window { + Some(id) => window::screenshot(id).map(Message::Captured), + None => Task::none(), + } + } + + /// 截图回来了：落盘 + 打一行取证日志，然后退出。 + fn on_captured(&mut self, screenshot: &window::Screenshot) -> Task { + let Some(path) = self.options.screenshot.clone() else { + return Task::none(); + }; + match crate::shot::save(screenshot, &path) { + Ok(summary) => { + diag!("{}", summary.describe()); + // M97：打**实际**后端名（`wgpu`/`tiny-skia`），不是请求值——`renderer=auto` 曾经出现在每张验收图的日志里。 + diag!( + "[shot] screen={} theme={} renderer={} route={:?}", + self.options.screen.name(), + crate::shot::flavor_slug(&self.ui), + super::backend::effective_kind().map_or("?", Kind::name), + self.state.route() + ); + } + Err(error) => diag!("[shot] 失败：{error}"), + } + + iced::exit() + } +} + +/// 空闲心跳的一拍：睡 1 秒再发 [`Message::Heartbeat`]。 +/// +/// 用 `Task::perform` + `std::thread::sleep` 而不是 `iced::time::every`：后者只在 tokio/smol +/// 后端提供（本 crate 的执行器是 thread-pool，Cargo.toml 不在 scope）。代价是每拍让线程池里 +/// 一个线程阻塞 1 秒——按 1 Hz 算，对线程池（默认 = CPU 数）是可接受的占用。 +fn heartbeat() -> Task { + 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..0851445 --- /dev/null +++ b/crates/app-iced/src/app/update/account.rs @@ -0,0 +1,233 @@ +//! 账户页消息的落点（M114）：页面只发意图，这里翻成 `AppCommand` 或本地的表单状态写入。 +//! +//! 三条纪律（与 `update.rs` 同源）： +//! +//! 1. **不做乐观回显**：切账户/删账户/登录都只派命令，等 `AccountsChanged` / +//! `DeviceLoginChanged` / `AuthlibLoginChanged` 回来才改列表； +//! 2. **密码只走一次**：`Submit` 把 `AuthlibRequest` 交给后端后立刻清掉表单里的密码 +//! （成功失败都清——重试用新输入，不在内存里多留一份凭据）； +//! 3. **表单态是纯 UI 状态**：输入框改动只写 `App::account_form` + 置脏，不派命令。 +//! +//! ## 返回 `Task`（M114 r2 / 复审 P2-1） +//! +//! 复制用户码/链接必须把 `iced::clipboard::write` 的 `Task` **交回 runtime**——iced 0.14 的 +//! `Task` 是惰性 stream，丢掉返回值等于永不执行（日志页的 Copy summary 就是正确写法）。 + +use iced::Task; +use unlucky_presenter::dto::{AccountKind, AppCommand, AuthlibRequest, DeviceLoginPhase}; + +use crate::app::Message; +use crate::pages::account::{Hint, Message as Account, Panel, Track}; + +use super::super::state::App; + +impl App { + /// 账户页消息。 + pub(super) fn on_account(&mut self, message: Account) -> Task { + // 复制是唯一需要**交回 Task** 的分支：先把它的 Task 抓出来，其余分支照旧改状态 + let clipboard = match &message { + Account::Copy(text) => Some(text.clone()), + _ => None, + }; + + match message { + Account::Open(track) => { + self.account_form.open(track); + self.account_form.hint = None; + self.view_dirty = true; + } + Account::ToggleAdd => { + self.account_form.section_open = !self.account_form.section_open; + self.account_form.hint = None; + self.view_dirty = true; + } + Account::Close => { + self.account_form.close(); + // 关面板必须把**两条轨**的登录态都收回 Idle（复审 r2 P2-1：只看 `busy()` 时， + // `Failed`/`Succeeded` 不在 busy ⇒ 状态仍是非 Idle ⇒ `Page::build` 又把面板 + // 强制回 Microsoft，按钮成了死按钮）。`CancelDeviceLogin` 在 host 侧本来就 + // 同时收两条轨并发 Idle，所以判据用「非 Idle」而不是「busy」。 + if self.state.device_login.phase != DeviceLoginPhase::Idle + || self.state.authlib_login.phase != DeviceLoginPhase::Idle + { + self.dispatch(AppCommand::CancelDeviceLogin); + } + self.view_dirty = true; + } + Account::DismissNotice => self.dispatch(AppCommand::DismissAccountNotice), + Account::Server(value) => { + self.account_form.server = value; + self.view_dirty = true; + } + Account::Login(value) => { + self.account_form.login = value; + self.view_dirty = true; + } + Account::Password(value) => { + self.account_form.password = value; + self.view_dirty = true; + } + Account::OfflineName(value) => { + self.account_form.offline_name = value; + self.view_dirty = true; + } + Account::Probe => { + let server = self.account_form.server.clone(); + if !server.trim().is_empty() { + self.dispatch(AppCommand::ProbeAuthlibServer(server)); + } + } + Account::Submit => match self.account_form.panel { + Panel::Offline => { + // 名字**不清空**：失败时用户还要看见自己输入的（复审 r1 P2-2 的另一半） + let name = self.account_form.offline_name.trim().to_string(); + if !name.is_empty() { + self.dispatch(AppCommand::AddOfflineAccount(name)); + } + } + Panel::Authlib => { + if self.account_form.authlib_ready() { + let request = AuthlibRequest::new( + self.account_form.server.clone(), + self.account_form.login.clone(), + std::mem::take(&mut self.account_form.password), + ); + self.dispatch(AppCommand::AddAuthlibAccount(request)); + } + } + Panel::Microsoft => return self.on_account(Account::StartDevice), + Panel::None => {} + }, + Account::StartDevice => self.dispatch(AppCommand::StartDeviceLogin), + Account::StartBrowser => self.dispatch(AppCommand::StartBrowserLogin), + Account::Cancel => { + self.account_form.close(); + self.dispatch(AppCommand::CancelDeviceLogin); + } + Account::Copy(_) => {} + Account::Switch(id) => self.dispatch(AppCommand::SwitchAccount(id)), + Account::Remove(id) => self.dispatch(AppCommand::RemoveAccount(id)), + Account::Relogin(id) => return self.relogin(&id), + } + self.refresh_view(); + + match clipboard { + Some(text) => iced::clipboard::write(text), + None => Task::none(), + } + } + + /// 「重新登录」按**账户类型**分派（复审 r1 P2-3）。 + /// + /// - 微软轨：走授权码流（原路）； + /// - 第三方轨：第三方站没有「一键重登」——预填服务器地址与登录名，让用户补密码； + /// - 本地档案：没有服务器账户可重登 ⇒ 明确说明，不假装能做。 + fn relogin(&mut self, id: &str) -> Task { + let Some(account) = self + .state + .accounts + .iter() + .find(|account| account.id == id) + .cloned() + else { + return Task::none(); + }; + self.account_form.hint = None; + match account.kind { + AccountKind::Microsoft => { + self.account_form.panel = Panel::Microsoft; + // M178：重登也走设备码（不依赖任何应用注册项）。想试浏览器再点面板里的次按钮。 + self.dispatch(AppCommand::StartDeviceLogin); + } + AccountKind::Authlib => { + self.account_form.open(Track::Authlib); + self.account_form.server = account.server_url.clone(); + self.account_form.login = account.login_name.clone(); + self.account_form.password.clear(); + self.account_form.hint = Some(Hint::AuthlibReauth); + self.view_dirty = true; + self.refresh_view(); + } + AccountKind::Offline => { + self.account_form.hint = Some(Hint::OfflineNoRelogin); + self.view_dirty = true; + self.refresh_view(); + } + } + Task::none() + } +} + +/// 取证开关 `ULL_ACCOUNT_STATE` 的落地（**只在 `--screenshot` 下生效**）。 +/// +/// 为什么需要：设备码过期要等 15 分钟、表单要手点两下，截图通道等不到自然发生的状态。 +pub(super) fn force_account_state(app: &mut App) { + if !app.has_screenshot() { + return; + } + let Ok(state) = std::env::var("ULL_ACCOUNT_STATE") else { + return; + }; + match state.trim().to_lowercase().as_str() { + // 设备码已过期：起点往前挪一小时（倒计时自己算出来就是 0） + "expired" => { + app.state.device_login_started = + Some(std::time::Instant::now() - std::time::Duration::from_secs(3_600)); + } + // M178：浏览器登录没走成、已回退设备码的那一态（设备码 + 一句「为什么 + 怎么修」）。 + // + // 为什么在 app 层造：真走到这一步要一次真网络请求（预检），截图通道要的是**确定性**。 + // 这里只替换登录视图本身——面板的渲染路径与真 host 完全同一条 + // （`apply_device_login` → `pages::account::panels::device_panel` → `login::panel`）。 + "msa-fallback" => { + app.account_form.panel = crate::pages::account::Panel::Microsoft; + app.state.apply_device_login( + unlucky_presenter::dto::DeviceLoginView::waiting( + "ABCD-EFGH", + "https://www.microsoft.com/link", + 900, + "", + ) + .with_browser_note(unlucky_presenter::dto::BrowserLoginNote::RedirectNotRegistered), + ); + } + // 第三方站**失败**态：面板打开 + mock 那边给出的 `AuthlibLoginChanged(Failed)` + "authlib-failed" => { + app.account_form.panel = crate::pages::account::Panel::Authlib; + app.account_form.server = "https://example.invalid/api/yggdrasil/".to_string(); + app.account_form.login = "alex@example.com".to_string(); + } + // 离线档案失败态：面板打开（横幅由 mock 的 notice 场景给） + "notice" => { + app.account_form.panel = crate::pages::account::Panel::Offline; + app.account_form.offline_name = "ab".to_string(); + } + // 第三方站表单：直接把面板打开并预填地址 + "authlib" | "authlib-form" => { + app.account_form.panel = crate::pages::account::Panel::Authlib; + if app.account_form.server.trim().is_empty() { + app.account_form.server = "https://littleskin.cn/api/yggdrasil/".to_string(); + } + app.account_form.login = "steve@example.com".to_string(); + app.account_form.password = "not-a-real-password".to_string(); + } + // 「关掉之后」：mock 给的是 failed 种子，这里按一次 Close（走真实的 + // `on_account` → `CancelDeviceLogin` 通道），出「面板真的关了」的对照图。 + "closed" => { + let _ = app.on_account(crate::pages::account::Message::Close); + } + // M178：登录入口面板（两个按钮 + 一行「没有浏览器时用这个」）。复审 r1 P2-5 的文案改动 + // 要有图可看：`device_login` 是 Idle ⇒ 面板落在空闲态（主按钮=设备码，次按钮=浏览器）。 + "msa-entry" => { + app.account_form.panel = crate::pages::account::Panel::Microsoft; + } + // 有账号时「Add an account」展开态（P2-4 的收敛后形态） + "add" => { + app.account_form.section_open = true; + } + _ => {} + } +} + +#[cfg(test)] +mod tests; 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..4d43d37 --- /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, countdown, .. + } => { + assert_eq!(code, "ABCD-EFGH", "用户码要上屏"); + assert!(!countdown.is_empty(), "倒计时在跑（文案由模型拼好）"); + } + other => panic!("进行中状态必须可见，实际 {other:?}"), + } + assert_eq!(app.account.panel, Panel::Microsoft, "面板要切到微软那条轨"); + let _ = app.view(); + + let _ = app.on_account(Account::Cancel); + assert_eq!(app.account.device, DevicePanel::Hidden, "取消要真的收掉"); + assert_eq!( + app.state.device_login.phase, + unlucky_presenter::dto::DeviceLoginPhase::Idle + ); +} + +/// 失败态①：**未实现 / 名字不合法** ⇒ 页面横幅给出结构化码（不是静默无语）。 +#[test] +fn an_invalid_profile_name_surfaces_a_named_failure() { + let mut app = with_rig(); + let _ = app.on_account(Account::Open(Track::Offline)); + // 名字不合法时**发送键是灰的**（与 host 同一份判据），所以这里直接派命令： + // 抓的是「host 真的回了一个结构化失败码」这条链路，而不是按钮的禁用态。 + assert!(!app.account_form.offline_ready()); + app.dispatch(unlucky_presenter::dto::AppCommand::AddOfflineAccount( + "ab".to_string(), + )); + + assert!(app.account.rows.is_empty(), "不合法的名字不入列表"); + let notice = app.account.notice.as_ref().expect("必须有横幅"); + assert_eq!(notice.code, AccountNoticeCode::OfflineNameInvalid); + assert!(notice.failure, "失败档（配色不同）"); + assert_eq!(notice.subject, "ab", "横幅要带上是哪个名字"); + // 文案走 catalog，中英各一条 + for lang in [Lang::En, Lang::ZhCn] { + assert!(!Catalog::of(lang) + .text(Key::AccountNoticeOfflineNameInvalid) + .is_empty()); + } + let _ = app.view(); +} + +/// 失败态②：**账户凭据失效** ⇒ 第三方轨面板进入 `Failed(BadCredentials)`（只带原因码）。 +/// +/// 为什么只断言原因码：M114 r3 起面板类型里**没有** `message`/`detail` 字段（原文只进 presenter +/// 日志），页面据码选 catalog 文案。这条测试与「页面画得出文案」之间的桥梁是 +/// `pages::account::login::failure_body_key`（同一 crate 内的穷尽 match，缺一条编译不过）。 +#[test] +fn expired_credentials_surface_a_named_failure_code() { + let mut app = headless(); + seed( + &mut app, + CoreEvent::AuthlibLoginChanged(AuthlibLoginView::failed_as( + LoginFailure::BadCredentials, + "服务器返回 401：凭据已失效（token=…已脱敏）", + )), + ); + app.account_form.open(Track::Authlib); + app.refresh_view(); + + assert_eq!( + app.account.authlib, + AuthlibPanel::Failed { + failure: LoginFailure::BadCredentials + }, + "凭据失效要落成具名原因码，而不是静默回 Idle" + ); + // 原因码对应的那句译文两套语言都得有 + for lang in [Lang::En, Lang::ZhCn] { + let text = Catalog::of(lang).text(Key::AccountFailureBadCredentials); + assert!(!text.trim().is_empty(), "{} 缺这条失败文案", lang.tag()); + } + // 原文不许出现在页面的任何可视文本里（M114 的凭据红线） + assert!( + !format!("{:?}", app.account).contains("服务器返回 401"), + "后端原文不许进页面模型" + ); + let _ = app.view(); +} + +// ---------------------------------------------------------------- M114 的既有回归闸 + +/// **复审 r2 P2-1 的回归闸**：登录失败/成功态下按 `Close`，面板必须真的关掉。 +/// +/// 为什么这条以前是死按钮：`Page::build` 只要 `device_login.phase != Idle` 就把面板强制 +/// 回 Microsoft，而 `Close` 只在 `busy()`（Requesting/Waiting）时才派 `CancelDeviceLogin` +/// ⇒ Failed/Succeeded 下点了没反应。现在判据改成「非 Idle」，两条轨都覆盖。 +/// +/// 抓得住：判据退回 `busy()`；`Close` 忘了 dispatch；`CancelDeviceLogin` 没有把状态收回 Idle。 +/// 抓不住：`CancelDeviceLogin` 在**真 host** 上的副作用（这里跑的是 mock，但 mock 已按 +/// 真 host 的契约发 Idle，见 `presenter/src/mock.rs`）。 +#[test] +fn close_really_closes_the_login_panel_on_both_tracks() { + // ① 微软轨：失败态 + let mut app = headless(); + seed( + &mut app, + CoreEvent::DeviceLoginChanged(DeviceLoginView { + phase: unlucky_presenter::dto::DeviceLoginPhase::Failed, + message: "微软拒绝了这次登录：AADSTS7000218（HTTP 403）".to_string(), + failure: Some(LoginFailure::NotWhitelisted), + ..DeviceLoginView::new() + }), + ); + assert_eq!(app.account.panel, Panel::Microsoft, "失败态面板要显示"); + let _ = app.on_account(Account::Close); + assert_eq!(app.account.panel, Panel::None, "Close 之后面板必须关掉"); + assert_eq!( + app.state.device_login.phase, + unlucky_presenter::dto::DeviceLoginPhase::Idle + ); + + // ② 微软轨：成功态（同样不在 busy 里） + let mut app = headless(); + seed( + &mut app, + CoreEvent::DeviceLoginChanged(DeviceLoginView::succeeded("Steve")), + ); + assert_eq!(app.account.panel, Panel::Microsoft); + let _ = app.on_account(Account::Close); + assert_eq!(app.account.panel, Panel::None, "成功提示也要能关掉"); + + // ③ 第三方轨：失败态 + let mut app = headless(); + seed( + &mut app, + CoreEvent::AuthlibLoginChanged(AuthlibLoginView { + phase: unlucky_presenter::dto::DeviceLoginPhase::Failed, + server: "https://example.invalid/api/yggdrasil/".to_string(), + server_name: String::new(), + message: "服务器返回 HTTP 404".to_string(), + failure: Some(LoginFailure::NotAuthlibServer), + account_name: String::new(), + }), + ); + app.account_form.open(Track::Authlib); + app.refresh_view(); + assert_eq!( + app.account.panel, + Panel::Authlib, + "第三方轨失败态面板要显示" + ); + let _ = app.on_account(Account::Close); + assert_eq!(app.account.panel, Panel::None, "第三方轨也要能关掉"); + assert_eq!( + app.state.authlib_login.phase, + unlucky_presenter::dto::DeviceLoginPhase::Idle + ); +} + +/// 表单态是纯 UI 状态：打开/关闭面板不派命令，但会把面板切对。 +/// +/// 抓得住：`Open` 忘了写 `panel`（点了轨道卡什么都不出现）、`close()` 不清密码。 +/// 抓不住：真实 dispatch 的副作用（那要真后端）。 +#[test] +fn the_form_state_follows_the_page_messages() { + let mut form = Form::new(); + assert_eq!(form.panel, Panel::None); + form.open(Track::Authlib); + assert_eq!(form.panel, Panel::Authlib); + form.password = "hunter2".to_string(); + form.close(); + assert_eq!(form.panel, Panel::None); + assert!(form.password.is_empty(), "关闭面板必须把一次性密码清掉"); +} + +/// 三张轨道卡默认收起（有账号时），`ToggleAdd` 展开（复审 r1 P2-4）。 +#[test] +fn the_add_section_starts_collapsed() { + let mut form = Form::new(); + assert!(!form.section_open); + form.section_open = true; + assert!(form.section_open); +} diff --git a/crates/app-iced/src/app/update/adopt.rs b/crates/app-iced/src/app/update/adopt.rs new file mode 100644 index 0000000..965ade4 --- /dev/null +++ b/crates/app-iced/src/app/update/adopt.rs @@ -0,0 +1,358 @@ +//! 「导入已有版本」向导的落点（M223 GUIADOPT）。 +//! +//! ## 四段各自发什么、等什么 +//! +//! | 用户动作 | 发什么 | 等什么回程 | +//! |---|---|---| +//! | 页头「导入」/ [`AdoptMessage::Open`] | `AdoptCommand::Scan` | `AdoptEvent::Scan` | +//! | 选目标 + 点「预检」/ [`AdoptMessage::Check`] | `AdoptCommand::Preview` | `Planned` / `Failed` | +//! | 点「确认导入」/ [`AdoptMessage::Confirm`] | `AdoptCommand::Confirm` | `Done` / `Failed` | +//! | 「返回」/ [`AdoptMessage::Back`] | `AdoptCommand::Scan`（重扫一次，顺手清掉预检/失败） | `Scan` | +//! | 「关闭」/ [`AdoptMessage::Close`] | `AdoptCommand::Dismiss` | `Cleared` | +//! +//! ## 三段纪律 +//! +//! 1. **不在本地判「能不能导入」**：候选可不可用、落点在哪、有哪些问题全部来自 presenter 的回程 +//! （`AdoptState`）。这里只把「用户点了什么」翻成命令； +//! 2. **确认只发用户填过的那份请求**（版本 + 名字 + 目标档），预检与确认**同一份**—— +//! 于是「预检 A、写 B」这种错位不可能发生； +//! 3. **在等回程时把主按钮并掉**（`Form::busy`）：连点两次「确认」不会写两条实例记录。 + +use iced::Task; +use unlucky_presenter::dto::{AdoptCommand, AdoptRequestView, AppCommand}; + +use crate::app::adopt::{AdoptMessage, Busy}; + +use super::super::message::Message; +use super::super::state::App; + +impl App { + /// 向导的一条消息。 + pub(super) fn on_adopt(&mut self, message: AdoptMessage) -> Task { + match message { + AdoptMessage::Open => { + self.adopt_form.open(); + self.dispatch_adopt(AdoptCommand::Scan); + } + AdoptMessage::Close => { + // 登记在飞时不吃「关闭」：core 那条线程已经开跑了，写了盘却不回报 Done + // 就会出现「实例已存在但界面什么都没说」——等它交卷（几十毫秒级）。 + if self.adopt_form.busy == Busy::Importing { + return Task::none(); + } + self.adopt_form.close(); + self.dispatch_adopt(AdoptCommand::Dismiss); + } + AdoptMessage::Select(version_id) => { + self.adopt_form.selected = Some(version_id); + } + AdoptMessage::Name(name) => self.adopt_form.name = name, + AdoptMessage::Target(target) => { + // 登记在飞时不吃「换档」：它会派一条零写盘的预览把 `adopt_epoch` +1， + // 于是在飞的 Confirm 交卷时 Done 被代次丢掉——实例写进去了，界面什么都没说。 + // 连本地档位也不改：界面上显示 A 档、盘上写的是 B 档，是最糟的一种不一致。 + if self.adopt_form.busy == Busy::Importing { + return Task::none(); + } + self.adopt_form.target = target; + // 换了目标档 ⇒ 上一档的预检作废（确认按钮不该继续亮着） + self.adopt_form.checked = false; + // 共享档 / 版本目录档会写进**别人的目录**：一被点选就把后果原文拿出来 + // （零写盘的预检，见 `Form::stage` 的收窄：这一次结果落在 Pick 段当提示读）。 + if target.touches_foreign_dir() { + if let Some(request) = self.adopt_request() { + self.adopt_form.busy = Busy::Checking; + self.dispatch_adopt(AdoptCommand::Preview(Box::new(request))); + } + } + } + AdoptMessage::Check => { + if let Some(request) = self.adopt_request() { + self.adopt_form.checked = true; + self.adopt_form.busy = Busy::Checking; + self.dispatch_adopt(AdoptCommand::Preview(Box::new(request))); + } + } + AdoptMessage::Confirm => { + if let Some(request) = self.adopt_request() { + self.adopt_form.busy = Busy::Importing; + self.dispatch_adopt(AdoptCommand::Confirm(Box::new(request))); + } + } + AdoptMessage::Back => { + // 同 Close / Target：登记在飞时「返回」会把 `adopt_epoch` +1（它派 Scan）， + // 在飞 Confirm 的 Done 就再也到不了界面。 + if self.adopt_form.busy == Busy::Importing { + return Task::none(); + } + // 退回候选列表 = 重新扫一次：`scan` 会把上一轮的预检/失败一起作废， + // 于是界面回到 Pick 段，不需要再给 core 加一个「清失败」的命令。 + self.adopt_form.checked = false; + self.adopt_form.busy = Busy::Scanning; + self.dispatch_adopt(AdoptCommand::Scan); + } + } + Task::none() + } + + /// 回程到了：这一条命令已经交卷（`pump` 收到 `CoreEvent::Adopt` 时调，见 `update/clock.rs`）。 + /// 出图通道的种子（`ULL_ADOPT_STATE`，与 `ULL_JAVA_STATE` / `ULL_AI_STATE` 同一族）。 + /// + /// **只在 `--screenshot` 下生效**：交互模式读这个环境变量没有意义（也没有人会设它）。 + /// 不认识的名字一律忽略，退回正常启动路径（向导保持关闭）。 + pub(in crate::app) fn hydrate_adopt_state(&mut self) { + if self.options.screenshot.is_none() { + return; + } + let Ok(raw) = std::env::var(crate::app::adopt::shot::ENV) else { + return; + }; + if let Some((form, state)) = crate::app::adopt::shot::seed(&raw) { + self.adopt_form = form; + self.state.adopt = state; + } + } + + pub(super) fn settle_adopt(&mut self) { + self.adopt_form.settled(); + } + + /// 当前表单能拼出的请求（没选版本就没有请求——按钮在那边也是禁用的）。 + fn adopt_request(&self) -> Option { + let version_id = self.adopt_form.selected.clone()?; + let name = self.adopt_form.name.trim(); + Some(AdoptRequestView { + version_id, + name: (!name.is_empty()).then(|| name.to_string()), + target: self.adopt_form.target, + }) + } + + fn dispatch_adopt(&mut self, command: AdoptCommand) { + self.dispatch(AppCommand::Adopt(Box::new(command))); + } +} + +#[cfg(test)] +mod tests { + use std::cell::RefCell; + use std::rc::Rc; + + use unlucky_design::color::SchemeFlavor; + use unlucky_presenter::dto::{ + AdoptCommand, AdoptEvent, AdoptTargetView, AppCommand, AppEvent, Backend, + }; + use unlucky_presenter::mock::MockBackend; + use unlucky_presenter::settings_bridge::SettingsBridge; + + use crate::app::adopt::{AdoptMessage, Busy}; + use crate::app::state::App; + use crate::cli::Options; + use crate::theme::Families; + + const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", + }; + + fn headless() -> App { + App::with_presenter( + Options::default(), + FAMILIES, + SchemeFlavor::Light, + Box::new(MockBackend::new()), + SettingsBridge::memory_only(), + ) + } + + /// 记账后端：把 `dispatch` 收到的命令留在台账里（`MockBackend` 只认自己那几条， + /// 「有没有派出去」根本看不见——而 P2-1 的判据正是「不许派」）。 + #[derive(Debug, Default)] + struct RecordingBackend { + dispatched: Rc>>, + } + + impl Backend for RecordingBackend { + fn drain_events(&mut self) -> Vec { + Vec::new() + } + + fn dispatch(&mut self, command: AppCommand) { + self.dispatched.borrow_mut().push(command); + } + } + + /// 带台账的 App（返回台账句柄，测试直接查「派了什么」）。 + fn recording() -> (App, Rc>>) { + let dispatched: Rc>> = Rc::new(RefCell::new(Vec::new())); + let app = App::with_presenter( + Options::default(), + FAMILIES, + SchemeFlavor::Light, + Box::new(RecordingBackend { + dispatched: Rc::clone(&dispatched), + }), + SettingsBridge::memory_only(), + ); + (app, dispatched) + } + + /// 台账里有没有派过某条 adopt 命令（只认命令种类，不看载荷内容）。 + /// + /// 写法是 `let ... else` + `matches!`：内层用 `match` 会被 clippy 判成 + /// `match expression looks like matches! macro`（deny 级，CI 的 `-D warnings` 直接红）。 + fn dispatched_adopt(ledger: &Rc>>, want: &str) -> bool { + ledger.borrow().iter().any(|command| { + let AppCommand::Adopt(command) = command else { + return false; + }; + matches!( + (&**command, want), + (AdoptCommand::Scan, "scan") + | (AdoptCommand::Preview(_), "preview") + | (AdoptCommand::Confirm(_), "confirm") + | (AdoptCommand::Dismiss, "dismiss") + ) + }) + } + + /// 打开向导 = 表单进入「在等扫描」+ 派一条 `Scan`。 + /// + /// 抓得住：`Open` 没派命令（面板永远停在「正在扫描」）、或忘了置 `Busy::Scanning`（没有等待态）。 + /// 抓不住：扫描真的返回了什么（那在 presenter 的 `host/adopt` 用例里）。 + #[test] + fn opening_the_wizard_asks_for_a_scan() { + let mut app = headless(); + let _ = app.on_adopt(AdoptMessage::Open); + assert!(app.adopt_form.open); + assert_eq!(app.adopt_form.busy, Busy::Scanning); + assert_eq!( + app.adopt_form.target, + AdoptTargetView::InstanceDir, + "缺省不是 isolated" + ); + } + + /// 没选版本时「预检 / 确认」不派命令（否则会发出一条 `version_id` 为空的请求）。 + /// + /// 抓得住：`adopt_request()` 在没有选中项时仍拼出请求（空版本 id 打到 core 换一句 + /// `adopt_version_not_found`，用户看到莫名其妙的失败）。 + #[test] + fn no_request_without_a_selected_version() { + let mut app = headless(); + let _ = app.on_adopt(AdoptMessage::Open); + let _ = app.on_adopt(AdoptMessage::Check); + assert_eq!(app.adopt_form.busy, Busy::Scanning, "Check 不该改等待态"); + let _ = app.on_adopt(AdoptMessage::Confirm); + assert_eq!(app.adopt_form.busy, Busy::Scanning); + } + + /// 选中 + 预检 = 一条 Preview 命令，且请求里的名字是**去过空白**的用户输入。 + #[test] + fn check_sends_the_form_as_a_preview_request() { + let mut app = headless(); + let _ = app.on_adopt(AdoptMessage::Open); + let _ = app.on_adopt(AdoptMessage::Select("1.20.1".to_string())); + let _ = app.on_adopt(AdoptMessage::Name(" 生存 ".to_string())); + let _ = app.on_adopt(AdoptMessage::Target(AdoptTargetView::Shared)); + let _ = app.on_adopt(AdoptMessage::Check); + assert_eq!(app.adopt_form.busy, Busy::Checking); + // 请求本体不在 App 上留副本：能证明意图的只有等待态与目标档 + assert_eq!(app.adopt_form.target, AdoptTargetView::Shared); + } + + /// 回程到了就解除等待（`settle_adopt` 由 `pump` 调）。 + #[test] + fn an_incoming_event_settles_the_wait() { + let mut app = headless(); + let _ = app.on_adopt(AdoptMessage::Open); + assert!(app.adopt_form.busy.waiting()); + app.settle_adopt(); + assert_eq!(app.adopt_form.busy, Busy::Idle); + // 事件真相进了 presenter 的状态（界面从它取词） + app.state.apply(unlucky_presenter::dto::AppEvent::Core( + unlucky_presenter::dto::CoreEvent::Adopt(Box::new(AdoptEvent::Cleared)), + )); + assert!(app.state.adopt.scan.is_none()); + } + + /// 共享档一被点选就发一条**预检**（零写盘），但**不**置 `checked`——确认页要用户点「预检」。 + /// + /// 抓得住：`Target` 分支忘了发预检（后果原文永远不出现，契约 §5.2 失守）、 + /// 或者顺手把 `checked` 也置上（点一下档位就跳到确认页）。 + #[test] + fn choosing_a_foreign_target_previews_but_waits_for_the_user() { + let mut app = headless(); + let _ = app.on_adopt(AdoptMessage::Open); + let _ = app.on_adopt(AdoptMessage::Select("1.20.1".to_string())); + let _ = app.on_adopt(AdoptMessage::Target(AdoptTargetView::Shared)); + assert_eq!(app.adopt_form.busy, Busy::Checking); + assert!(!app.adopt_form.checked, "确认页要等用户点「预检」"); + + // 缺省档不触发自动预检（它不会写进别人的目录） + let _ = app.on_adopt(AdoptMessage::Target(AdoptTargetView::InstanceDir)); + assert!(!app.adopt_form.checked); + } + + /// 登记在飞时「关闭」被忽略：core 已经在写了，关掉面板只会让 Done 无处可去。 + /// + /// 抓得住：Close 无条件清表单并 `Dismiss`（实例写成功了，界面却什么都没说）。 + #[test] + fn closing_is_ignored_while_the_registration_is_in_flight() { + let mut app = headless(); + let _ = app.on_adopt(AdoptMessage::Open); + let _ = app.on_adopt(AdoptMessage::Select("1.20.1".to_string())); + let _ = app.on_adopt(AdoptMessage::Check); + app.adopt_form.busy = Busy::Importing; + let _ = app.on_adopt(AdoptMessage::Close); + assert!(app.adopt_form.open, "登记在飞时不许把面板关掉"); + } + + /// **P2-1**：登记在飞时，除了 Close，「返回」与「换目标档」也必须早退。 + /// + /// 三条都是同一条病：它们都会派一条新命令把 `adopt_epoch` +1，于是在飞 Confirm 的 + /// `Done` 回来时被代次丢掉 —— 实例**写进去了**，界面却什么都没说（Close 那条早就守住了， + /// 唯独这两支漏了）。 + /// + /// 抓得住：`Back` 派了 `Scan`（旧 `Done` 被丢）、`Target` 派了 `Preview`（同上）， + /// 以及「守卫写了但写在改本地状态之后」（表单被改成新档位，而盘上写的是旧档位）。 + /// 抓不住：host 侧代次比较的真实时序（那在 presenter 的 `host/adopt` 那层）。 + #[test] + fn back_and_target_are_ignored_while_the_registration_is_in_flight() { + let (mut app, ledger) = recording(); + let _ = app.on_adopt(AdoptMessage::Open); + let _ = app.on_adopt(AdoptMessage::Select("1.20.1".to_string())); + let _ = app.on_adopt(AdoptMessage::Target(AdoptTargetView::InstanceDir)); + // 走到「确认」那一步：真的派一条 Confirm 出去 + let _ = app.on_adopt(AdoptMessage::Check); + let _ = app.on_adopt(AdoptMessage::Confirm); + assert!( + dispatched_adopt(&ledger, "confirm"), + "前提：确认要真的派出去" + ); + assert_eq!(app.adopt_form.busy, Busy::Importing); + ledger.borrow_mut().clear(); + + // 在飞期间点「返回」：不许派 Scan + let _ = app.on_adopt(AdoptMessage::Back); + assert!( + !dispatched_adopt(&ledger, "scan"), + "登记在飞时 Back 不许派 Scan（会把 Done 的代次顶掉）" + ); + assert_eq!(app.adopt_form.busy, Busy::Importing, "等待态不许被改掉"); + + // 在飞期间换目标档：不许派 Preview，也不许改本地档位 + let _ = app.on_adopt(AdoptMessage::Target(AdoptTargetView::Shared)); + assert!( + !dispatched_adopt(&ledger, "preview"), + "登记在飞时换档不许派 Preview（会把 Done 的代次顶掉）" + ); + assert_eq!( + app.adopt_form.target, + AdoptTargetView::InstanceDir, + "挡下来的点击不该改出界面与盘上不一致的档位" + ); + assert_eq!(app.adopt_form.busy, Busy::Importing); + } +} 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..79b5d16 --- /dev/null +++ b/crates/app-iced/src/app/update/agent.rs @@ -0,0 +1,382 @@ +//! 助手栏消息的落点（M104 建，M119 接线）：三档状态迁移 / 输入 / 键盘 / **presenter 四契约**。 +//! +//! ## 为什么单独一个文件 +//! +//! `app/update.rs` 已经贴着 400 行硬上限（M94 也因此把下载页四支拆到 `update/download.rs`）。 +//! 助手栏有十几个变体，塞回主文件必破线。 +//! +//! ## 分工：视图态 vs presenter 契约（M119 之后的分界线） +//! +//! | 消息 | 落到哪 | +//! |---|---| +//! | `Expand` / `Collapse` / `Dock` / `Escape` | **只改视图态**（`AgentUi`）+ 路由栈（离开/进入 `Route::Agent`）+ `agent_mark_read` | +//! | `Detach` | 视图态 + `Route::Agent`（压栈，`back()` 能回去）+ `agent_mark_read` | +//! | `Edit` | 视图态（草稿），并同步进 presenter 的草稿（`agent_set_draft`） | +//! | `Submit` | [`AgentHost::submit`] → `agent_submit`；失败**不留白**（具名错误进横幅） | +//! | `Stop` | `AppCommand::StopAgent`（真后端才收敛得出结果；同步 rig 下是 no-op） | +//! | `Confirm(accept)` | [`AgentHost::confirm`] → `agent_confirm`（YOLO 下 presenter 自己放行并记审计） | +//! | `Events(..)` | [`AgentHost::apply`] → `AppState::apply`（**事件回流的唯一落点**） | +//! | `DragStart` / `DragTo` / `DragEnd` | 视图态：吸附宽度 | +//! | `Key` / `Tab` / `Activate` | 键盘路径（`Tab` 的环要在流式中多一格，`busy` 从 rail 取） | +//! +//! **会话内容一行都不在这里攒**：`transcript` / `busy` / `unread` / `confirm` 全在 presenter 的 +//! `AgentRail` 上（M119 删掉了 M104 的自持副本）。 +//! +//! ## 事件为什么绕一圈消息再回来 +//! +//! `agent_submit` / `agent_confirm` 的端口是同步的，但**事件走队列**（见 +//! `app/state/presenter/transport.rs`）：抽队列的那一步必须和用户点击走同一条漏斗，否则两处各改 +//! 一次状态，流式标记与未读会打架。所以 [`App::drain_agent`] 抽出来之后立刻 +//! `on_agent(agent::Message::Events(..))` —— 同一条 `Message::Agent(..)` 通道。 + +use crate::app::diag::diag; +use iced::keyboard::{key, Key}; +use iced::Task; + +use unlucky_i18n::{Catalog, Key as TextKey}; +use unlucky_presenter::dto::AppCommand; + +use crate::app::MIN_SIZE; +use crate::app::WINDOW_SIZE; +use crate::shell::agent::demo::{self, Fixture}; +use crate::shell::agent::{self, Focus, RailState}; + +use super::super::state::presenter::agent::SubmitOutcome; +use super::*; + +#[cfg(test)] +mod tests; + +impl App { + /// 助手栏消息（`app::Message::Agent(..)` 的唯一落点）。 + pub(super) fn on_agent(&mut self, message: agent::Message) -> Task { + // M106 口径：文案走**生效语言**的目录，不再恒英文 + let catalog = Catalog::of(self.lang()); + + // 只有**几何**会变的几支才需要重建页面模型（`pages::Model` 里没有会话内容：会话在 + // presenter 的 rail 上，右栗自己那棵树每次 `view()` 都从 rail 现读）。复审 P3-9 的教训： + // 每敲一个字符都重建整张模型是白克隆。 + let geometry_changed = matches!( + message, + agent::Message::Expand + | agent::Message::Collapse + | agent::Message::Detach + | agent::Message::Dock + | agent::Message::DragTo(_) + | agent::Message::DragEnd + | agent::Message::Escape + | agent::Message::Activate + | agent::Message::Key(_) + ); + + match message { + agent::Message::Expand => { + self.agent.expand(); + // 「展开即读」是 presenter 的语义（`agent_mark_read`），壳只负责在正确的时刻调它 + self.agent_host.mark_read(); + } + agent::Message::Collapse | agent::Message::Escape => self.collapse_agent(), + agent::Message::Detach => { + self.agent.detach(); + self.agent_host.mark_read(); + self.state.navigate(Route::Agent); + } + agent::Message::Dock => { + self.agent.dock(); + self.agent_host.mark_read(); + self.leave_agent_page(); + } + agent::Message::DragStart => self.agent.drag_start(), + agent::Message::DragTo(x) => self.agent.drag_to(self.width, x), + agent::Message::DragEnd => self.agent.drag_end(), + agent::Message::Edit(action) => { + self.agent.edit(action); + // 草稿同步给 presenter（切形态不丢；它也是 rail 上唯一允许躺原文的字段） + self.agent_host.set_draft(self.agent.draft.text()); + } + agent::Message::Submit => self.submit_agent(), + agent::Message::Stop => self.dispatch(AppCommand::StopAgent), + agent::Message::Confirm(accept) => { + self.agent_host.confirm(accept); + self.drain_agent(); + } + agent::Message::Events(events) => { + for event in events { + self.agent_host.apply(event); + } + self.view_dirty = true; + } + agent::Message::Tab { shift } => { + let rail = self.agent_host.rail(); + let (busy, pending) = (rail.busy, rail.confirm.is_some()); + self.agent.step_focus(shift, busy, pending); + } + agent::Message::Activate => self.activate_focused(catalog), + agent::Message::Key(event) => return self.on_agent_key(event), + } + + // 待确认请求出现/消失时，把键盘焦点挪到（或挪离）确认条的按钮上 + self.sync_confirm_focus(); + // 档位 / 路由变了就要把「栏可见吗」写回 presenter（未读口径的输入） + self.sync_agent_presenter(); + if geometry_changed { + self.view_dirty = true; + self.refresh_view(); + } + Task::none() + } + + /// 发送：草稿 → `agent_submit` → 抽事件。 + /// + /// 三种结局各自有落点：发出去（清草稿）/ 后端失败（具名横幅，见 [`App::agent_failure`]）/ + /// presenter 拒收（日志一行——这三种情形正常情况下被禁用态挡住，够不着）。 + fn submit_agent(&mut self) { + let text = self.agent.draft.text(); + if text.trim().is_empty() { + return; + } + match self.agent_host.submit(text) { + SubmitOutcome::Sent => { + self.agent.clear_draft(); + self.agent_host.set_draft(String::new()); + self.drain_agent(); + } + SubmitOutcome::Failed(failure) => { + diag!("[agent] 提交失败（{}）", failure.code()); + } + SubmitOutcome::Rejected => { + diag!("[agent] presenter 拒收：空文本 / 上一轮未完 / 待确认 三闸该先挡住"); + } + } + } + + /// 抽干 presenter 的事件队列，**经既有 Message 通道**回流（见模块文档末节）。 + pub(crate) fn drain_agent(&mut self) { + let events = self.agent_host.drain(); + if events.is_empty() { + return; + } + let _ = self.on_agent(agent::Message::Events(events)); + } + + /// 把「栏可见吗」写回 presenter（`navigate` + `prefs_mut` 两个窄入口，见 `AgentHost`）。 + pub(crate) fn sync_agent_presenter(&mut self) { + let on_page = self.state.route() == &Route::Agent; + let collapsed = self.agent.rail == RailState::Collapsed; + self.agent_host.sync_visibility(on_page, collapsed); + } + + /// 失败横幅要显示的东西（`None` = 没有错误）。 + /// + /// 两个来源都取**展示输入**：具名原因码 → catalog 译文；或 presenter 已脱敏的这一轮原因。 + /// 壳在这一层不做任何脱敏（那是 presenter 的`scrub_text`），也不拼中英（那是 catalog 的事）。 + pub(crate) fn agent_failure(&self) -> Option> { + let catalog = self.lang().catalog(); + if let Some(failure) = self.agent_host.last_failure() { + return Some(agent::Failure { + title: TextKey::AgentErrorTitle, + body: catalog.text(failure.body_key()), + }); + } + self.agent_host + .rail() + .error + .as_deref() + .map(|body| agent::Failure { + title: TextKey::AgentErrorTitle, + body, + }) + } + + /// 待确认请求出现 ⇒ 焦点直接落在「允许」；消失 ⇒ 收回输入框。 + /// + /// **只挪焦点，不替用户打开键盘巡航**（M119 r2 / 复审 P2-2）：r1 在这里顺手把 + /// `keyboard_mode` 置真，而 `sync_confirm_focus` 是 `on_agent` 的无条件尾巴、`Events` 又由心跳 + /// 驱动——于是只要冒出待确认，全局键盘闸就被打开；用户发完那句话接着打下一句，第一个空格 + /// 就成了「批准写操作」。现在那道闸只由真实的键盘表态打开（`Tab`，见 `AgentUi::step_focus`； + /// 或者 `on_agent_key` 把按键送进来时用户本来就在键盘巡航）。 + /// + /// 键盘用户怎么走到确认条：待确认时焦点已经在这两个按钮上，**按一次 `Tab` 点亮焦点环即是 + /// 表态**（`step_focus` 里那条 arming 规则：这一次不移动焦点），之后 `Enter`/`Space` 就能裁决。 + /// + /// 唯一写入口：`on_agent` 末尾（任何会改动 rail 的分支之后都要经过它）。 + fn sync_confirm_focus(&mut self) { + let pending = self.agent_host.rail().confirm.is_some(); + let on_confirm = matches!(self.agent.focus, Focus::ConfirmAllow | Focus::ConfirmDeny); + if pending && !on_confirm { + self.agent.focus = Focus::ConfirmAllow; + diag!("[agent] 写操作待确认 → 焦点落到 Allow（Tab 点亮焦点环后 Enter/Space 裁决）"); + } else if !pending && on_confirm { + self.agent.focus = Focus::Composer; + self.agent.keyboard_mode = false; + } + } + + /// **不变式**：`route() == Route::Agent` ⟺ `agent.rail == RailState::Detached`（唯一同步点）。 + /// + /// 为什么需要它（复审 r1 的 P2-1，实测复现）：`agent.rail` 只在自己发 `Detach`/`Dock` 时变， + /// 而路由还能从三条**别的**路径进 `Route::Agent`——左侧导航第五项、`pages::Message::Navigate`、 + /// `ULL_START_ROUTE=agent`。脱钩的后果：从导航进独立页时头部出现「Open assistant」（那是 + /// 「展开右栗」的意思）、标题旁挂着不化的未读胶囊、`Esc` 也收不走页面。 + /// + /// 两条对向规则： + /// - **在**独立页上 ⇒ `Detached`（顺带按「拆出即读」清未读）； + /// - **不在**独立页上而档位还是 `Detached`（用户从页上点了别的导航）⇒ 会话收回右栗（`dock()`）， + /// 否则会话会「两头都没有」：页走了、栏还是 0 宽。 + /// + /// 调用点只有一个：`App::refresh_view` 的开头。每一次路由变化都会经过它，于是**模型算宽度时** + /// 与**画头部动作时**读到的永远是同一份档位。 + pub(crate) fn sync_agent_route(&mut self) { + let on_page = self.state.route() == &Route::Agent; + match (on_page, self.agent.rail) { + (true, RailState::Detached) | (false, RailState::Collapsed | RailState::Expanded) => {} + (true, _) => self.agent.detach(), + (false, RailState::Detached) => self.agent.dock(), + } + } + + /// 启动时助手栏要做的三件事（从 `on_boot` 搬出来：那边只许留一行调用，复审 P3-6）。 + /// + /// 1. **窗口尺寸 adopt**：唯一真源是 `boot.rs` 开窗时用的那一个（`ULL_WINDOW_SIZE` + 最小尺寸 + /// 钳位）。`App::with_presenter` 只认识常量 1180×760，不 adopt 的话验收矩阵开 900 / 1520 的窗 + /// 时页面还按 1180 排版（窄窗里内容被裁）。 + /// 2. **取证夹具**（`ULL_AGENT_*`）：先落档位，再**跑一轮真提交**——夹具不造消息，消息只能 + /// 由 presenter 产生（M119 的口径，见 `pages/agent/demo.rs`）。 + /// 3. **拆出档直接落到独立页**：`ULL_AGENT_RAIL=detached`（以及将来持久化的偏好）时，会话就在 + /// 独立页里，启动后不该停在实例页。 + pub(super) fn boot_agent(&mut self) { + let (window_size, _source) = crate::renderer::acceptance::window::window_size( + (WINDOW_SIZE.width, WINDOW_SIZE.height), + (MIN_SIZE.width, MIN_SIZE.height), + ); + self.width = window_size.0; + self.height = window_size.1; + + if let Some((ui, fixture)) = demo::from_env() { + self.agent = ui; + // 先让 presenter 知道「栏现在看得见吗」，再跑提交，未读口径才对 + self.sync_agent_presenter(); + match fixture { + Fixture::None => {} + Fixture::Turn | Fixture::Unread => { + let _ = self.agent_host.submit(demo::DEMO_QUESTION.to_string()); + self.drain_agent(); + } + Fixture::Armed => { + // 先跑一轮（写操作脚本会挂一个待确认），再按一次 `Tab`： + // 待确认时这一下只 arm、不移动焦点（见 `AgentUi::step_focus` 的 arming 规则） + let _ = self.agent_host.submit(demo::DEMO_QUESTION.to_string()); + self.drain_agent(); + let rail = self.agent_host.rail(); + let (busy, pending) = (rail.busy, rail.confirm.is_some()); + self.agent.step_focus(false, busy, pending); + } + Fixture::Focused => { + let rail = self.agent_host.rail(); + let (busy, pending) = (rail.busy, rail.confirm.is_some()); + self.agent.step_focus(false, busy, pending); + } + } + } + + if self.agent.rail == RailState::Detached && self.state.route() != &Route::Agent { + diag!("[agent] rail=detached → Route::Agent"); + self.state.navigate(Route::Agent); + // 直达独立页时不要再被「自动选中第一条实例」拉回详情页。 + self.auto_selected = true; + } + } + + /// 键盘订阅来的按键（`app/subscription.rs` 把整条键盘事件搬过来，解释权在这一层）。 + /// + /// 为什么不让订阅层直接翻成三个枚举：那样 `Escape`/`Tab`/`Enter` 的语义（什么状态下该做什么） + /// 会散在订阅表里；这里一眼能看完。 + fn on_agent_key(&mut self, event: iced::keyboard::Event) -> Task { + let iced::keyboard::Event::KeyPressed { key, modifiers, .. } = event else { + return Task::none(); + }; + + let message = match key { + Key::Named(key::Named::Escape) => agent::Message::Escape, + // 折叠档没有会话动作可巡航，`Tab` 不该被助手栏吃掉 + Key::Named(key::Named::Tab) if self.agent.rail == RailState::Collapsed => { + return Task::none(); + } + Key::Named(key::Named::Tab) => agent::Message::Tab { + shift: modifiers.shift(), + }, + // `Activate` 只在软焦点落在**按钮**上时才动手（输入框的 Enter 由 + // `text_editor::key_binding` 分流成「发送」，不能在这里重复发一次）。 + // + // M119 r1 / P2-2：`Space` 与 `Enter` 等价（键盘用户对确认条的习惯动作是空格）。 + // 它不会抢输入框里的空格：`activate_focused` 头一行就是 `keyboard_mode` 闸， + // 而用鼠标点进输入框时那道闸是关的（`AgentUi::edit` 的 `Click` 分支）。 + Key::Named(key::Named::Enter | key::Named::Space) => agent::Message::Activate, + _ => return Task::none(), + }; + + self.on_agent(message) + } + + /// `Esc` / `⌄`：展开 → 收起；独立页 → 收回右栗并离开 `Route::Agent`。 + fn collapse_agent(&mut self) { + let was_detached = self.agent.rail == RailState::Detached; + self.agent.collapse(); + if was_detached { + self.leave_agent_page(); + } + } + + /// 离开 AI 独立页：能回退就回退（`Detach` 是压栈的），否则回实例页。 + fn leave_agent_page(&mut self) { + if self.state.route() != &Route::Agent { + return; + } + if !self.state.back() { + self.state.navigate(Route::Instances); + } + } + + /// 键盘 `Enter`：激活软焦点上的按钮（`Tab` 环的顺序见 [`Focus`]）。 + /// + /// 焦点在 [`Focus::Composer`] 上时**什么都不做**：那一条路径由输入框自己的 `key_binding` + /// 负责（按 `Tab` 走到输入框并不等于真的把 iced 焦点交过去，两次发送会打架）。 + fn activate_focused(&mut self, catalog: Catalog) { + // 鼠标刚点过输入框（或从没按过 `Tab`）⇒ 这个 Enter 不归助手栏管 + if !self.agent.keyboard_mode { + return; + } + + let intent = match (self.agent.rail, self.agent.focus) { + (RailState::Collapsed, Focus::Collapse) => Some(agent::Message::Expand), + (RailState::Expanded, Focus::Collapse) => Some(agent::Message::Collapse), + (RailState::Expanded, Focus::Detach) | (RailState::Detached, Focus::Detach) => { + Some(if self.agent.rail == RailState::Detached { + agent::Message::Dock + } else { + agent::Message::Detach + }) + } + (_, Focus::ConfirmAllow) => Some(agent::Message::Confirm(true)), + (_, Focus::ConfirmDeny) => Some(agent::Message::Confirm(false)), + (_, Focus::Send) => Some(agent::Message::Submit), + (_, Focus::Stop) => Some(agent::Message::Stop), + // 折叠档没有「拆出」、独立页没有「收起」：焦点环按 `Focus::order` 不会落到这两格， + // 显式列成 None 只是为了让编译器确认这份 intent 表是穷尽的。 + (RailState::Collapsed, Focus::Detach) + | (RailState::Detached, Focus::Collapse) + | (_, Focus::Composer) => None, + }; + + if let Some(message) = intent { + let _ = self.on_agent(message); + } else { + // 「不得静默无反应」：焦点在输入框上按 Enter 由输入框自己处理，这里只留一行日志。 + diag!( + "[agent] Enter on focus={} handled by the composer", + self.agent.focus.name() + ); + let _ = catalog; + } + } +} 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..9031a18 --- /dev/null +++ b/crates/app-iced/src/app/update/appearance.rs @@ -0,0 +1,82 @@ +//! M116：窗口圆角的下发落点（`impl App::apply_window_corner`）。 +//! +//! ## 为什么单独成文件 +//! +//! 圆角与整窗 α 是**两条独立的管线**，只是都必须拿到 HWND、都在同一个时点下发： +//! +//! | 管线 | 判据 | 落点 | 键 | +//! |---|---|---|---| +//! | 整窗 α（D36） | `platform::effective_window_alpha` | `SetLayeredWindowAttributes` | `appearance.window_opacity` | +//! | 圆角（M116） | `platform::plan_corner` | `DwmSetWindowAttribute` | `appearance.window_corner` | +//! +//! 合在一个函数里会让「α 变了要不要重设圆角」这种问题变成实现细节；分开之后两个判据各自可测。 +//! +//! ## 日志为什么是**一行、六栏** +//! +//! `corner=policy=… source=dwm|square os=… excluded_reason=… radius=system pref=… readback=… frame=… layered=…` +//! +//! 用户报的现象是「别的窗口都有圆角，只有我们的没有」。没有这一行，事后无法区分 +//! 「没生效」「生效了但看不见」「这台系统根本没有这个能力」；`frame` / `layered` 两栏则是 +//! 「圆角为什么不生效」的两个现场读数：`frame=`（窗口形状）与 `layered=`（整窗 α 引入的分层位）。 +//! +//! ⚠️ **产品窗口不是 `WS_POPUP`**（M116 r4 复审订正）：winit 在 `decorations = false` 下给的是 +//! `WS_CAPTION|WS_BORDER|WS_CLIPSIBLINGS|WS_SYSMENU`（可缩放时再加 `WS_THICKFRAME` 与 min/max 键）， +//! `WS_POPUP` 只在**带 owner** 的弹出窗才加；无边框观感来自 `WM_NCCALCSIZE` 把客户区铺满。 +//! 所以真进程日志里 `frame=` 应是 `overlapped`（关掉 min/max 则 `other`），**永远不会是 `popup`**。 +//! 真正让系统忽略圆角请求的是**整窗 α 补的 `WS_EX_LAYERED`**（`layered=on`）。 +//! +//! `radius=system` 是刻意的：系统不暴露 DWM 的圆角半径，我们也不自己定一个数字 +//! （M116 取消了 8/12/16 固定档）。 + +use crate::app::diag::diag; +use crate::platform; +use crate::platform::win32::corner::{self, CornerApplied}; +use crate::platform::win32::transparency::{apply_corner, style_summary, CornerOutcome}; + +use super::super::state::App; + +impl App { + /// 把当前圆角策略下发到窗口，并打一行可分辨的日志。 + /// + /// ## 去重（M116 r1 复审 P2-4） + /// + /// 设置页的滑条（整窗 α / 面板 α / 暗化）每动一下都会走一次外观变更，而圆角与那些键无关。 + /// 判定完全没变时这里**直接返回**：不动窗口、不打日志。判据是 + /// [`corner::needs_redispatch`]（纯函数，有「同一策略 N 次只记 1 行」的测试）， + /// 指纹只含「策略 / 来源 / 原因码 / 有没有句柄」，不含只有真下发才拿得到的读数。 + /// + /// 没有句柄时**也打日志**（`window=none`）：不能让「没生效」只体现为屏幕上没变化。 + /// 句柄从无到有会让指纹变化 ⇒ 首次拿到 HWND 时必然重下一次。 + pub(crate) fn apply_window_corner(&mut self, context: &str) { + let policy = self.appearance.window_corner(); + let plan = platform::plan_corner( + policy, + platform::current_windows_version(), + self.appearance.backend, + ); + // 整窗 α < 1 ⇒ `window_alpha::dispatch` 会给窗口补 `WS_EX_LAYERED`；系统因此忽略圆角请求 + // （tower 裁定 A / D47）。这里只记**事实**：α 是否把我们自己的分层位打开了。 + let alpha_layered = self.appearance.window_opacity < 1.0; + let suppressed_by = alpha_layered.then_some("window_alpha"); + let next = CornerApplied::new(policy, &plan, self.hwnd.is_some(), alpha_layered); + if !corner::needs_redispatch(self.corner_applied.as_ref(), &next) { + return; + } + self.corner_applied = Some(next); + + // 行的形状只有一处（`corner::format_line`），因为那里能在没有窗口的环境里被单测钉住。 + // 关键的三栏必须在同一行：`pref=`（请求发出去了）、`layered=`（分层位在不在，来自 + // 整窗 α）、`frame=`（窗口形状 = `overlapped`，不是 `popup`）——否则以后只能猜是哪一条。 + let (outcome, style) = match self.hwnd { + Some(hwnd) => (apply_corner(hwnd, &plan).describe(), style_summary(hwnd)), + None => ( + CornerOutcome::NoWindow.describe(), + "frame=? layered=?".to_owned(), + ), + }; + diag!( + "{}", + corner::format_line(context, &plan, policy, &outcome, &style, suppressed_by) + ); + } +} 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..a075c27 --- /dev/null +++ b/crates/app-iced/src/app/update/boot_env.rs @@ -0,0 +1,173 @@ +//! 启动期的取证环境变量解析（`ULL_START_ROUTE` / 动效三个开关）。 +//! +//! 从 `app/update.rs` 原样搬出（那个文件在 M105/M106/M109/M113 之后贴着 400 行硬线）： +//! **纯函数、无状态**，只是取值表长到了十条。M192 在这里加的是动效那一组 +//! （[`motion_scale`] / [`env_motion_pin`] / [`env_motion_fixture`]）：档位策略只有这一处， +//! 帧泵自己不读环境变量。 + +use unlucky_design::motion::MotionScale; +use unlucky_presenter::router::Route; + +/// 取证开关 `ULL_START_ROUTE` 的取值解析（`settings` / `instances` / `download` / `content` / `logs`）。 +/// +/// 为什么是环境变量：`crates/app-iced/src/cli.rs` 不在 M93 的 scope，而外观矩阵必须在**设置页**上 +/// 出图。语义与 `ULL_APPEARANCE_*` / `ULL_TICK_TRACE` 一致：只影响这一次进程。 +pub(super) fn env_start_route() -> Option { + match std::env::var("ULL_START_ROUTE").ok()?.trim() { + "instances" => Some(Route::Instances), + "download" => Some(Route::Download), + "logs" => Some(Route::Logs), + "settings" => Some(Route::Settings), + // M104：AI 独立页也要能直达（三态矩阵的 Detached 那张） + "agent" => Some(Route::Agent), + // M109：内容库（截图矩阵要能直达；页面内的四条侧栏不在路由里） + "content" => Some(Route::Content), + // M114：账户页的 D30 矩阵要能直达（`cli.rs` 不在本 mission 的 scope） + "accounts" => Some(Route::Accounts), + _ => None, + } +} + +/// 动效档位与相位钉住（M192）：帧泵**只在产品的 `on_boot` 里定档**。 +/// +/// ## 为什么档位在这里算 +/// +/// 三个输入只有启动这一拍齐全：①是不是截图通道（`--screenshot`）②实际渲染后端 +/// （`backend::effective_kind()`，不是 `--renderer` 的请求值）③`ULL_MOTION` 的强制值。 +/// 帧泵自己（`components::motion`）不读环境变量，它只接受一个 [`MotionScale`]——这样动效策略 +/// 只有一处，测试也不必摆环境变量。 +/// +/// | 条件 | 档位 | 为什么 | +/// |---|---|---| +/// | `ULL_MOTION=off` | `NONE` | 一键关（排障 / 想量基线时用） | +/// | 截图通道，且没给 `ULL_MOTION_AT` | `NONE` | D30：出图不许有动画（否则第 3 帧抓到中间态，图就不可复现） | +/// | CPU 渲染（`tiny-skia`） | `HALF` | 时长减半 = 帧数减半。位移是**布局量**，CPU 档最贵的就是逐帧重排 | +/// | 其余（`wgpu`） | `STANDARD` | —— | +/// | `ULL_MOTION=half` / `full` | 强制 | 覆盖上表（出图矩阵要在 GPU 上量同一段动效） | +/// +/// 「减少动效」的用户开关**还不存在**（`core/src/setting` 里没有 animation key，见报告 follow-up）， +/// 所以本函数只认上面这些来源。 +pub(super) fn motion_scale(screenshot: bool, gpu: bool, pinned: bool) -> MotionScale { + match std::env::var("ULL_MOTION").ok().as_deref().map(str::trim) { + Some("off") | Some("none") => return MotionScale::NONE, + Some("half") => return MotionScale::HALF, + Some("full") => return MotionScale::STANDARD, + _ => {} + } + if pinned { + // 取证相位优先于「截图必须静」，否则多帧序列图一张都出不来。 + return MotionScale::STANDARD; + } + if screenshot { + return MotionScale::NONE; + } + if gpu { + MotionScale::STANDARD + } else { + MotionScale::HALF + } +} + +/// `ULL_MOTION_AT=`：把动画时钟钉在某一毫秒（多帧序列图取证）。 +/// +/// 语义与 `ULL_APPEARANCE_*` / `ULL_DIALOG_FIXTURE` 一致：只影响这一次进程。没有它，第 3 帧落在 +/// 动画的哪个相位取决于这台机器的渲染速度 —— 那样「0% / 50% / 100% 三张图」是抓阄抓出来的。 +pub(super) fn env_motion_pin() -> Option { + std::env::var("ULL_MOTION_AT") + .ok()? + .trim() + .parse::() + .ok() + .filter(|ms| ms.is_finite() && *ms >= 0.0) +} + +/// `ULL_MOTION_FIXTURE`：第 1 帧之后**真的**做一次状态变化（多帧序列图靠它）。 +/// +/// 为什么要制造变化：页面主体的入场只在「内容标识变了」时起跑（`motion::observe`），而截图通道 +/// 从第一帧起画的就是同一页——不制造一次真实的路由变化，就没有可拍的动效。 +#[derive(Debug, Clone)] +pub(super) enum MotionFixture { + /// 跳到一个一级页（走「换页」那一档）。 + Route(Route), + /// 「列表 → 详情」：先回列表（第 1 帧），再点进第一条实例（第 2 帧）。 + Detail, +} + +/// `ULL_MOTION_FIXTURE=`。 +pub(super) fn env_motion_fixture() -> Option { + Some(match std::env::var("ULL_MOTION_FIXTURE").ok()?.trim() { + "instances" => MotionFixture::Route(Route::Instances), + "download" => MotionFixture::Route(Route::Download), + "logs" => MotionFixture::Route(Route::Logs), + "settings" => MotionFixture::Route(Route::Settings), + "content" => MotionFixture::Route(Route::Content), + "detail" => MotionFixture::Detail, + _ => return None, + }) +} + +/// `ULL_MOTION_FIXTURE_AT=<秒>`：启动后第 N 次心跳（≈第 N 秒）**真的**导航一次。 +/// +/// ## 为什么需要它（真机空闲取证） +/// +/// 复审 r1 要求「空闲 ≥10 s 后点一次导航轨，看 `[tick] motion=` 涨多少」。本机工作区所在会话 +/// 没有前台窗口（`GetForegroundWindow()==0`），合成鼠标事件（`mouse_event` 与 +/// `PostMessage(WM_LBUTTONDOWN)` 都试过）递不进 iced 的输入层，所以这里换一条**同构**的路： +/// 由 1 Hz 心跳（空闲态本来就有的消息）在第 N 秒做一次真实的路由跳转。 +/// +/// 两条路在 `update` 之后**完全同一段代码**：消息 → `sync_motion`（起跑）→ `subscription()` +/// （同一拍看见轨道）→ `frames()`。差别只在「消息是谁产生的」，而这正是 P1 要验的那一段。 +pub(super) fn env_motion_fixture_at() -> Option { + std::env::var("ULL_MOTION_FIXTURE_AT") + .ok()? + .trim() + .parse::() + .ok() + .filter(|beats| *beats > 0) +} + +/// 把启动那一拍的**事实**写进启动器自己的日志（M187 / r1 复审 P2-4）。 +/// +/// ## 为什么这一拍只能「先记、后落」 +/// +/// `.ULL/logs` 的落点由 `platform::data_dir` 的三模式决定（要读配置、follow `redirect.json`）， +/// 那件事只有 presenter 的 `HostEnv` 做过。app 层拿不到它，于是这里只 `record` +/// （core 侧缓冲，最多 200 行）；presenter **构造 `HostEnv` 的那一刻**就调 +/// `launcher_log::set_dir`（M188 补上的那一半），缓冲一次刷进 `<.ULL>/logs/launcher.log`。 +/// +/// 效果正是用户投诉要的那份东西：他「双击 → 启动 → 崩 → 找日志」时，`launcher.log` 里从 +/// **启动这一拍**（主题 / 语言 / 路由 / 窗口 / 后端）一直写到退出，而不是只有 launch 那一段。 +/// +/// M188 之后边界也变了：`boot.rs` / `boot/fallback.rs` / `state/*` 那些 `eprintln!` 改走 +/// [`crate::app::diag::emit`]（stderr + 文件双写），同样靠这条缓冲接住——所以「一局都没开就崩」 +/// 的进程也会留下 `launcher.log`。 +pub(crate) fn record_boot_log(app: &super::super::state::App) { + use unlucky_core::launch::launcher_log; + + launcher_log::record("boot", "app boot"); + launcher_log::record( + "boot", + &format!( + "theme={} lang={:?} route={:?} window={:.0}x{:.0} screenshot={} instances={}", + app.ui().name(), + app.lang(), + app.state.route(), + app.width, + app.height, + app.has_screenshot(), + app.state.instances.len(), + ), + ); + launcher_log::record("boot", &unlucky_cli::commands::msa_client_id_log_line()); + // 后端这一拍也要在日志里：`[probe]` / `[backend]` 那几行由 `renderer::acceptance` 打到 + // stderr（那个模块不在 M188 的 scope），事故之后翻日志的人至少要看得出「这次用的是哪个后端」。 + launcher_log::record( + "boot", + &format!( + "backend request={} effective={} renderer_fallback={}", + app.options.backend.name(), + super::super::backend::effective_backend(app.options.backend).name(), + std::env::var(crate::renderer::FALLBACK_ENV).unwrap_or_else(|_| "-".to_string()), + ), + ); +} 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..90165f1 --- /dev/null +++ b/crates/app-iced/src/app/update/clock.rs @@ -0,0 +1,184 @@ +//! 节拍：推进一拍 / 派发指令 / 抽干事件（M119 从 `update.rs` 拆出来守 400 行硬线；纯搬不改）。 +//! +//! ## 为什么这三件必须在一起 +//! +//! `advance` → `pump` → `apply` → `refresh_view` 是同一条链：时间推进、事件抽干、状态落地、 +//! 视图重建。拆开看每一段都无害，合起来才是「presenter 的异步事件在 UI 侧怎么被消费」的答案。 +//! +//! ## 两个时钟的相位（M90 r3 / P2-2 的老账，代码里有细节） +//! +//! | 场景 | 时钟 | 周期 | +//! |---|---|---| +//! | 截图 / 有 Busy-Running 实例 / 有 toast / 派发后 3 s 观察窗 | `window::frames()` + 闸门 | 33 ms | +//! | 其余（空闲） | `Heartbeat` 自续链 | 1 s | +//! +//! ## M119 增加了什么 +//! +//! [`App::pump`] 里多了一行 [`App::drain_agent`]：AI 助手的事件队列和 core 的事件队列同拍抽干， +//! 于是「右栗的未读/流式状态」和页面快照共享同一个刷新节奏（不会一个 30 Hz、一个 1 Hz）。 + +use crate::app::diag::diag; +use std::time::{Duration, Instant}; + +use unlucky_presenter::dto::AppCommand; +use unlucky_presenter::theme::CONFIG_POLL_TICKS; + +use super::super::state::TICK_MS; +use super::*; + +impl App { + /// 推进一拍：后端消化时间 → 抽干事件 → 过期 toast → 偶发重读配置文件。 + /// + /// `elapsed` 是真实流逝时间（毫秒级抖动是正常的：`MockBackend` 的脚本按累计时长走）。 + pub(in crate::app) fn advance(&mut self, elapsed: Duration) { + self.backend.tick(elapsed); + self.pump(); + + self.state + .toasts + .expire(u64::try_from(elapsed.as_millis()).unwrap_or(u64::MAX)); + + // 设备码/授权码的倒计时（M114）：等待态每秒都要重画一次，否则「剩 900s」永远不动， + // 用户会以为卡死了——这正是任务里「不得只转圈」的那一条。 + if self.state.device_login.phase == unlucky_presenter::dto::DeviceLoginPhase::Waiting { + self.view_dirty = true; + } + // 中文字体下载（M168）：后台线程推进，这里只比对快照。变了就重建视图模型 ⇒ 设置页那一行 + // 从「正在获取中文字体…（16.9 MB）」翻到「已就绪 / 获取失败」，不需要用户再点一下。 + let font_status = crate::fonts::install::status(); + if font_status != self.font_seen { + self.font_seen = font_status; + self.view_dirty = true; + } + // Java 扫描（M175）：同一条「后台线程 + 快照」路数。进度（3/7）与结论都在里面， + // 扫描期间按帧跑（见 `subscription::needs_frames`），扫完回到 1 Hz。 + self.hydrate_java_scan(); + // `ticks` 的单位是**33 ms 的一拍**，不是「advance 被调了几次」：空闲心跳一次跨 1 s， + // 要记 30 拍，这样 `theme::config_poll_due`（30 拍 ≈ 1 秒）在两种时钟下语义一致。 + let ticks = elapsed.as_millis().div_euclid(u128::from(TICK_MS)); + let ticks = u64::try_from(ticks).unwrap_or(u64::MAX).max(1); + let bucket_before = self.ticks / 30; + self.ticks += ticks; + let bucket_after = self.ticks / 30; + + // 外部（AI / CLI）改了配置文件：主题跟着换，其余外观项等玻璃/背景 mission。 + // + // 判据用**跨越**而不是 presenter 的 `config_poll_due(ticks)`（整除）：两个时钟的相位不同 + // （帧节拍按 33 ms 累加、空闲心跳按 30 拍累加），整除判定一旦错过一次就**再也命中不了** + // ——实测 ticks=137 之后每拍 +30 永远不整除，配置轮询静默死掉。间隔真源仍是 + // `CONFIG_POLL_TICKS`（30 拍 × 33 ms ≈ 1 秒）。截图通道不轮询（D30 可复现）。 + let poll_due = self.ticks >= self.config_due_at; + if poll_due { + // 追到「当前 ticks 之后的第一个间隔点」，避免心跳把相位拖飞 + self.config_due_at = self.ticks + CONFIG_POLL_TICKS; + } + let reloaded = + !self.has_screenshot() && poll_due && self.bridge.reload_if_changed().is_some(); + if reloaded { + diag!("[settings] 配置文件变了，重读主题 + 外观"); + self.apply_config_theme(); + // M93：外观也热切（面板 α / 背景图 / 配色来源 / 整窗 α 都在里面）。 + self.reload_appearance(); + // M174：助手那四项也一样（`ull config set ai.* …` 改完 1 秒内可见；脏草稿不覆盖）。 + self.hydrate_ai_settings(); + // M175：Java 三键同理（外部改了内存 / JVM 参数 / 默认 JDK，设置页 1 秒内跟上）。 + self.hydrate_java_settings(); + } + + if self.view_dirty { + self.refresh_view(); + } + + // 取证开关（`ULL_TICK_TRACE=1`）：每跨过 30 拍（≈1 秒）打一行。 + // 忙碌态由帧节拍跨桶（≈1 行/秒），空闲态由心跳一次 +30 跨桶（**也是 1 行/秒**）—— + // 两种时钟都用同一把尺子，所以 trace 的密度本身就是「时钟在跑」的证据。 + if bucket_after != bucket_before && std::env::var_os("ULL_TICK_TRACE").is_some() { + diag!( + "[tick] n={} frames={} refreshes={} clock={} motion={}", + self.ticks, + self.frames, + self.refreshes, + if self.needs_frames() { + "frames" + } else { + "idle-1hz" + }, + // M192：动效时间轴已结算的帧数（每秒一行 ⇒ 这一列的增长速度就是动画的实际帧率， + // 也是「动画期间重绘成本」的记账口径，见报告） + crate::app::components::motion::samples() + ); + } + } + + /// 派发一条指令并**立刻**抽干它带出来的事件（不本地回显，等价于 Slint 版的 `dispatch`）。 + pub(in crate::app) fn dispatch(&mut self, command: AppCommand) { + self.backend.dispatch(command); + // 观察窗：命令发出后 3 秒内保持帧订阅，等后端把第一条事件交回来 + // （真 host 是异步的，派发瞬间状态还没变；不设这个窗口，空闲态的帧订阅永远不会打开）。 + self.watch_until = Some(Instant::now() + WATCH_WINDOW); + self.pump(); + } + + /// 抽干事件队列并逐条 `apply`（**唯一**的状态写入口）。 + pub(in crate::app) fn pump(&mut self) { + // M119：AI 助手的事件队列与 core 的事件队列**同拍**抽干（顺序无关：两个队列互不依赖）。 + // 抽出来的这批事件经 `Message::Agent(Events)` 回流，见 `update/agent.rs`。 + self.drain_agent(); + + let events = self.backend.drain_events(); + if events.is_empty() { + return; + } + let mut clean_scan = false; + for event in events { + // M160：预检之后**没有冲突**就不打扰用户——直接带着"全部保留"往下导。 + if matches!( + &event, + unlucky_presenter::dto::AppEvent::Core(unlucky_presenter::dto::CoreEvent::Pack( + pack + )) if matches!(&**pack, unlucky_presenter::dto::PackEvent::Scan(scan) if scan.is_clean()) + ) { + clean_scan = true; + } + // M223：导入向导「在等回程」只认事件到达（派发时置位、这里解除）， + // 于是连点「确认」不会写两条实例记录，界面也不会一直转圈。 + let settled_adopt = matches!( + &event, + unlucky_presenter::dto::AppEvent::Core(unlucky_presenter::dto::CoreEvent::Adopt(_)) + ); + self.state.apply(event); + if settled_adopt { + self.settle_adopt(); + } + } + self.view_dirty = true; + self.auto_select(); + self.refresh_view(); + // 派发放在循环之后：`dispatch` 自己会再 pump 一次，在循环里调会把事件顺序搅乱。 + if clean_scan { + self.continue_import_after_clean_scan(); + } + } + + /// 首屏快照到位后**自动选中第一行**（桌面 list-detail 的惯例：右栏不该开局就是空的）。 + /// + /// 只做一次：用户点「返回」回到列表后，再刷新实例列表也不会把他弹回详情页。 + /// 选中这件事走的是 `AppState::navigate`（路由栈），不是本地选中字段——于是「当前选中」 + /// 永远等于「路由栈顶」，用户点返回时栈语义自然成立。 + pub(in crate::app) fn auto_select(&mut self) { + if self.auto_selected || self.state.route() != &Route::Instances { + return; + } + let Some(first) = self + .state + .tiles() + .first() + .map(|cell| cell.instance.id.clone()) + else { + return; + }; + self.auto_selected = true; + self.state.navigate(Route::Detail(first)); + self.view_dirty = true; + } +} 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..34e2350 --- /dev/null +++ b/crates/app-iced/src/app/update/content.rs @@ -0,0 +1,238 @@ +//! 内容库页的消息落点（M109）：`pages::Message::Content(..)` 的穷尽分发。 +//! +//! ## 两件事分开（与 `update/download.rs` 同一条纪律） +//! +//! | 意图 | 谁改状态 | 派指令吗 | +//! |---|---|---| +//! | 关键词草稿 / 选中项目 / 目标实例 | `App::content`（页面内选择） | 不派 | +//! | 检索条件（类型/来源/排序/版本/加载器/关键词提交/翻页/重试） | `AppState::content`（presenter） | 派 `SearchContent` | +//! | 装入 | 谁都不改 | 派 `InstallContent` | +//! +//! 「装入」不改本地状态是关键：装上的证据是 `InstallProgress` 事件回流到安装面板 +//! （`pages/download::install_panel`），页面自己不做乐观回显。 +//! +//! ## 为什么条件写进 presenter 再派 +//! +//! `AppState::content.query` 是「当前结果对应哪份条件」的唯一真相：结果回来时 +//! `apply_content` 用它判「迟到的事件要不要丢」。页面自己存一份就会有两份真相。 + +use crate::app::diag::diag; +use unlucky_presenter::dto::{ + AppCommand, ContentDetailRequest, ContentInstallRequest, ContentQuery, ContentSource, + ExportRequestView, +}; + +use crate::pages::content::{Blocker, Content}; + +use super::*; + +impl App { + /// 进入内容库页时补一次检索（首个用户动作不该是「再点一下搜索」）。 + /// + /// 判据是 `AppState::content` 里还没有结果、也没有请求在飞：重复进出不重复打网络。 + pub(super) fn ensure_content_loaded(&mut self) { + if self.state.content.results.is_some() || self.state.content.pending { + return; + } + let query = ContentQuery::first(self.content.kind); + self.search_content(query); + } + + /// 页面消息（穷尽分发：漏一支报 E0004）。 + pub(super) fn on_content(&mut self, message: pages::content::Message) -> Task { + match message { + pages::content::Message::SetKind(kind) => { + // 换类型 = 换一份条件（facet 全变）：选中项作废，条件回到该类型的首页 + self.content.kind = kind; + self.content.selected = None; + let mut query = ContentQuery::first(kind); + // 保留用户已经选好的来源/排序/版本/加载器：换成默认值会让筛选条自己跳回去 + query.source = self.state.content.query.source; + query.sort = self.state.content.query.sort; + query.game_version = self.state.content.query.game_version.clone(); + query.loader = self.state.content.query.loader; + self.search_content(query); + } + pages::content::Message::QueryChanged(text) => { + self.content.draft = text; + self.view_dirty = true; + } + pages::content::Message::Search => { + let mut query = self.state.content.query.clone(); + query.text = self.content.draft.trim().to_string(); + query.offset = 0; + self.search_content(query); + } + pages::content::Message::SetSource(source) => { + if source == ContentSource::Curseforge && !self.curseforge_available() { + // 筛选条那条本来就是禁用的；这里再挡一次（防绕过 UI 的消息） + return Task::none(); + } + self.with_query(|query| query.source = source); + } + pages::content::Message::SetSort(sort) => self.with_query(|query| query.sort = sort), + pages::content::Message::SetVersion(version) => { + self.with_query(|query| query.game_version = version); + } + pages::content::Message::SetLoader(loader) => { + self.with_query(|query| query.loader = loader) + } + pages::content::Message::Select(id) => { + // M162：选中就拉这个项目的详情/版本列表（一条独立通道，失败只影响详情面板） + self.content.selected = Some(id.clone()); + self.state.content.request_detail(&id); + if let Some(request) = self.content_detail_request() { + self.dispatch(AppCommand::LoadContentDetail(Box::new(request))); + } + self.view_dirty = true; + } + pages::content::Message::SetTarget(id) => { + self.content.target = Some(id); + self.view_dirty = true; + } + pages::content::Message::LoadMore => { + let next = self.state.content.query.next_page(); + self.search_content(next); + } + pages::content::Message::Retry => { + let mut query = self.state.content.query.clone(); + query.offset = 0; + self.search_content(query); + } + pages::content::Message::Install => { + if let Some(request) = self.content_install_request() { + self.dispatch(AppCommand::InstallContent(Box::new(request))); + } + } + // M191：「只重试上次失败的那几项」。请求构造在 `pages/content/model.rs` + // （`retry_install_request`：载荷带 `retry: true`），这里只做转发。 + pages::content::Message::RetryFailed => { + let catalog = unlucky_i18n::Lang::En.catalog(); + let model = Content::from_snapshot(&self.state, &self.content, catalog); + if let Some(request) = model.retry_install_request() { + self.dispatch(AppCommand::InstallContent(Box::new(request))); + } + } + // M113: import/export —— 导入/导出区（细节在 `on_pack`） + pages::content::Message::Pack(message) => self.on_pack(message), + } + Task::none() + } + + /// 组一份导出请求（预检与写盘**共用同一份**，确认时原样发回）。 + /// + /// 没有选中实例就没有导出对象 ⇒ `None`。**「Save to」必须真的进请求** + /// （复审 r1 P1-1：以前这里硬编码 `target: None`，那个输入框是死的）。 + pub(super) fn pack_export_request(&self) -> Option { + 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 { + // 拖入是「现在就要看到结果」的动作：先把用户带到内容库页，再落草稿 + 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 { + // 状态没变就不重画：winit 对同一批文件会连发几次 hover 事件 + let changed = self.content.pack.hover != hover; + self.on_pack(pages::content::PackMessage::Hover(hover)); + if changed { + self.refresh_view(); + } + Task::none() + } + + /// 改一个筛选字段并**立刻重查**（第一页）。 + fn with_query(&mut self, change: impl FnOnce(&mut ContentQuery)) { + let mut query = self.state.content.query.clone(); + change(&mut query); + query.offset = 0; + self.search_content(query); + } + + /// 提交一次检索：条件先落进 presenter（迟到事件的判据），再派指令。 + fn search_content(&mut self, query: ContentQuery) { + self.state.set_content_query(query.clone()); + self.view_dirty = true; + self.dispatch(AppCommand::SearchContent(query)); + } + + /// CF 源可用吗（结果里带回的那一位；还没拉过 ⇒ `false`）。 + fn curseforge_available(&self) -> bool { + self.state + .content + .results + .as_ref() + .is_some_and(|results| results.curseforge) + } + + /// 详情的请求载荷（选中项 + 目标实例的版本/加载器；没有选中项就没有请求）。 + /// + /// 详情是**独立通道**：检索结果里只有 facets（支持哪些版本/加载器），拿不到「有哪些版本 + /// 可以装」；跟着检索一起拉等于每页多 N 次请求，所以只在选中时发一条。 + fn content_detail_request(&self) -> Option { + let catalog = unlucky_i18n::Lang::En.catalog(); + let model = Content::from_snapshot(&self.state, &self.content, catalog); + let hit = model.selected_hit()?; + let target = model + .targets + .iter() + .find(|target| Some(&target.id) == model.target.as_ref()); + Some(ContentDetailRequest { + project: hit.id.clone(), + source: hit.source, + game_version: target.map(|target| target.mc_version.clone()), + loader: target.map(|target| target.loader), + }) + } + + /// 组一份内容库的「装入」请求；闸门与页面上的按钮**同一个判据**（`Content::can_install`）。 + /// + /// 名字带 `content_`：M105 的版本安装已经占了 `install_request`（版本 → `CreateRequest`）， + /// 两者语义完全不同，撞名会被编译器拦下（本轮 rebase 撞过）。 + /// + /// 这里再判一次不是重复劳动：页面禁用的只是那一个按钮，消息仍然可能从别的路径进来， + /// 而 host 侧对整合包会直接回失败——三道闸门同一个结论，才不会出现「有的路能过」。 + fn content_install_request(&self) -> Option { + let catalog = unlucky_i18n::Lang::En.catalog(); + let model = Content::from_snapshot(&self.state, &self.content, catalog); + if !model.can_install() { + // 有原因就打印出来（取证用）；没有选中项时什么都不做 + for reason in model.blocker_reasons(catalog) { + diag!("[content] 装入被挡下：{reason}"); + } + if model.blockers.contains(&Blocker::NeedsPipeline) { + diag!("[content] 整合包装入未实现（M111）"); + } + return None; + } + let hit = model.selected_hit()?; + let target = model + .targets + .iter() + .find(|target| Some(&target.id) == model.target.as_ref())?; + Some(ContentInstallRequest { + project: hit.id.clone(), + title: hit.title.clone(), + // 整合包走不到这里：`ContentKind::Modpack` 的 `dir()` 是 `None` ⇒ 必然带 + // `Blocker::NeedsPipeline` ⇒ `can_install()` 为假。所以这里就是「单文件」那一类。 + kind: model.kind, + source: hit.source, + instance: target.id.clone(), + game_version: target.mc_version.clone(), + loader: target.loader, + // 普通装入：从根项目解起（「只重试这些」是另一条消息，`retry: true`） + retry: false, + }) + } +} diff --git a/crates/app-iced/src/app/update/content_pack.rs b/crates/app-iced/src/app/update/content_pack.rs new file mode 100644 index 0000000..fc875fd --- /dev/null +++ b/crates/app-iced/src/app/update/content_pack.rs @@ -0,0 +1,240 @@ +//! 整合包导入/导出区的消息落点（M113 + M160）：**从 `content.rs` 拆出来守 400 行硬线**。 +//! +//! ## 为什么单独一个文件 +//! +//! M160 给这一区加了预检、冲突清单、逐项决策三条通道，`content.rs` 到 409 行越线。拆的口径与 +//! 仓库其它拆分一致：**纯搬移**，`on_pack` 及其私有 helper（组请求）原样搬过来，别处一行不改。 +//! +//! ## 两条口径（与原来同一句） +//! +//! 1. **页内选择改本地状态**（路径草稿 / 目标实例 / 格式 / 包名 / 展开的冲突）——它们不属于业务 +//! 状态，不进 presenter； +//! 2. **意图只派指令，不做乐观回显**（导入 / 预检 / 确认 / 关面板）：进度、报告、预检结果全部由 +//! `CoreEvent::Pack` 回来（`dto::pack::event` 的 `PackState::apply` 是唯一写入点）。 +//! +//! ## M160 加的那条纪律 +//! +//! 点「导入」先发 `PackCommand::Scan`（只读），拿到 `PackEvent::Scan` 之后：**没有冲突就直接往下导** +//! （`clock::pump` 里的 `continue_import_after_clean_scan`），有冲突才画清单等用户点头。决策的缺省 +//! 档永远是 `KeepAll`——没问过用户就不会覆盖。 + +use unlucky_presenter::dto::{ + AppCommand, ConflictChoiceView, ConflictDecisionsView, ImportRequestView, PackCommand, +}; + +use crate::pages; + +use super::*; + +impl App { + /// 导入/导出区的消息（M113）。 + /// + /// 两条口径： + /// + /// 1. **页内选择改本地状态**（路径草稿 / 目标实例 / 格式 / 包名 / 展开的冲突）—— + /// 它们不属于业务状态，不进 presenter（同 `QueryChanged` 的处理）； + /// 2. **意图只派指令，不做乐观回显**（导入 / 预检 / 确认写盘 / 关面板）：进度、报告、预检结果 + /// 全部由 `CoreEvent::Pack` 回来（`dto::pack::event` 的 `PackState::apply` 是唯一写入点）。 + pub(super) fn on_pack(&mut self, message: pages::content::PackMessage) { + use pages::content::PackMessage; + match message { + PackMessage::Dropped(path) => { + // 拖进来的包属于「整合包」这一类：顺手把类型切过去，否则这一块根本不在屏上 + self.content.kind = unlucky_presenter::dto::ContentKind::Modpack; + self.content.pack.draft = path.display().to_string(); + self.content.pack.hover = false; + self.view_dirty = true; + } + PackMessage::Hover(hover) => { + self.content.pack.hover = hover; + self.view_dirty = true; + } + PackMessage::PathChanged(path) => { + self.content.pack.draft = path; + self.view_dirty = true; + } + PackMessage::SetInstance(instance) => { + self.content.pack.instance = instance; + self.view_dirty = true; + } + PackMessage::SetInstanceName(name) => { + self.content.pack.instance_name = name; + self.view_dirty = true; + } + PackMessage::SetFormat(format) => { + self.content.pack.format = format; + self.view_dirty = true; + } + PackMessage::SetExportName(name) => { + self.content.pack.export_name = name; + self.view_dirty = true; + } + PackMessage::SetExportVersion(version) => { + self.content.pack.export_version = version; + self.view_dirty = true; + } + PackMessage::SetOutput(path) => { + self.content.pack.output = path; + self.view_dirty = true; + } + PackMessage::ToggleConflict(path) => { + self.content.pack.expanded = if self.content.pack.expanded.as_deref() == Some(&path) + { + None + } else { + Some(path) + }; + self.view_dirty = true; + } + PackMessage::OpenExport => { + self.content.pack.export_open = true; + // 包名缺省取目标实例名（用户不该为一个名字再敲一遍键盘） + if self.content.pack.export_name.trim().is_empty() { + self.content.pack.export_name = + self.content.pack.instance.clone().unwrap_or_default(); + } + self.view_dirty = true; + } + PackMessage::AbortExport => { + self.content.pack.export_open = false; + // 连预检结果一起清：留着会让用户以为「还能再点一次确认」 + self.dispatch(AppCommand::Pack(Box::new(PackCommand::Dismiss))); + self.view_dirty = true; + } + PackMessage::Dismiss => { + // 报告 / 探测诊断 / 预检都在 presenter 里：关面板 = 让 host 清掉它们 + // （`PackEvent::Cleared`），于是界面回到入口态，浏览网格重新露出来 + self.content.pack.expanded = None; + self.dispatch(AppCommand::Pack(Box::new(PackCommand::Dismiss))); + self.view_dirty = true; + } + PackMessage::Import => { + // 先预检（M160）：没有冲突就直接导，有冲突就把清单画出来等用户点头。 + self.content.pack.pick_page = 0; + self.content.pack.pick_choices.clear(); + self.content.pack.pick_overwrite_all = false; + if let Some(request) = self.pack_import_request() { + self.dispatch(AppCommand::Pack(Box::new(PackCommand::Scan(Box::new( + request, + ))))); + } + } + PackMessage::PickPage(page) => { + self.content.pack.pick_page = page; + self.view_dirty = true; + } + PackMessage::TogglePick(path) => { + // 点一下就翻到另一侧，并把结果**原样记进表里**（保留也记）。 + // 表里为什么保留"保留"项：整批覆盖之后单独放回某几条时，「保留」必须能盖住 + // 整批档；等到发请求时 `PackPageState::decisions` 再把"与缺省档相同"的项过滤掉 + // （所以"一次都没点过"仍然等于 `KeepAll`）。 + let choice = self.content.pack.pick_choice(&path); + let flipped = match choice { + ConflictChoiceView::KeepUser => ConflictChoiceView::Overwrite, + ConflictChoiceView::Overwrite => ConflictChoiceView::KeepUser, + }; + self.content.pack.pick_choices.insert(path, flipped); + self.view_dirty = true; + } + PackMessage::PickKeepAll => { + self.content.pack.pick_overwrite_all = false; + self.content.pack.pick_choices.clear(); + self.view_dirty = true; + } + PackMessage::PickOverwriteAll => { + self.content.pack.pick_overwrite_all = true; + self.content.pack.pick_choices.clear(); + self.view_dirty = true; + } + PackMessage::ConfirmImport => { + let decisions = self + .content + .pack + .decisions(self.state.pack.import.scan.as_ref()); + if let Some(request) = self.pack_import_request_with(decisions) { + self.dispatch(AppCommand::Pack(Box::new(PackCommand::Import(Box::new( + request, + ))))); + } + } + PackMessage::CancelImport => { + // 取消 = 什么都不导（预检是只读的，没有东西要撤） + self.content.pack.pick_page = 0; + self.content.pack.pick_choices.clear(); + self.content.pack.pick_overwrite_all = false; + self.dispatch(AppCommand::Pack(Box::new(PackCommand::Dismiss))); + self.view_dirty = true; + } + PackMessage::Overwrite => { + // 「以包为准重新导入」：这条是**导入之后**从报告里点的，所以直接带整批覆盖再跑一遍。 + if let Some(request) = + self.pack_import_request_with(ConflictDecisionsView::OverwriteAll) + { + self.dispatch(AppCommand::Pack(Box::new(PackCommand::Import(Box::new( + request, + ))))); + } + } + PackMessage::Cancel => { + // 与面板上那个「取消」同一个指令：host 会把导入的取消标记与代次一起处理 + self.dispatch(AppCommand::CancelInstall); + } + PackMessage::Precheck => { + if let Some(request) = self.pack_export_request() { + // 先记下「这次预检对的是哪份请求」，确认写盘时原样发回 + self.state.pack.set_export_request(request.clone()); + self.view_dirty = true; + self.dispatch(AppCommand::Pack(Box::new(PackCommand::Export(Box::new( + request, + ))))); + } + } + PackMessage::Confirm => { + if let Some(request) = self.state.pack.export.request.clone() { + self.dispatch(AppCommand::Pack(Box::new(PackCommand::Confirm(Box::new( + request, + ))))); + } + } + } + } + + /// 预检干净（没有冲突）时直接往下导。 + /// + /// 这条是"不打扰不该打扰的文件"的另一半：清单为空时弹一屏"共 0 项冲突"只会让人以为出错了。 + /// 决策固定给 [`ConflictDecisionsView::KeepAll`]——即使预检与导入之间磁盘上突然多出个同名文件， + /// 结论也只会是"保留用户的"。 + pub(in crate::app) fn continue_import_after_clean_scan(&mut self) { + if let Some(request) = self.pack_import_request_with(ConflictDecisionsView::KeepAll) { + self.dispatch(AppCommand::Pack(Box::new(PackCommand::Import(Box::new( + request, + ))))); + } + } + + /// 组一份导入请求（路径草稿 → DTO）。草稿为空 ⇒ `None`（按钮不该发指令）。 + /// + /// **决策缺省是「全部保留」**（[`ConflictDecisionsView::default`]）：预检时还不知道有没有冲突， + /// 而 core 侧那份缺省同样落在保留上——所以"还没问过用户"绝不会变成"覆盖"。 + fn pack_import_request(&self) -> Option { + self.pack_import_request_with(ConflictDecisionsView::default()) + } + + /// 组一份带决策的导入请求（逐项 / 整批都从这里出去）。 + fn pack_import_request_with( + &self, + decisions: ConflictDecisionsView, + ) -> Option { + let draft = self.content.pack.draft.trim(); + if draft.is_empty() { + return None; + } + let name = self.content.pack.instance_name.trim(); + Some(ImportRequestView { + pack: std::path::PathBuf::from(draft), + instance: self.content.pack.instance.clone(), + instance_name: (!name.is_empty()).then(|| name.to_string()), + decisions, + }) + } +} diff --git a/crates/app-iced/src/app/update/dialog.rs b/crates/app-iced/src/app/update/dialog.rs new file mode 100644 index 0000000..06b546f --- /dev/null +++ b/crates/app-iced/src/app/update/dialog.rs @@ -0,0 +1,138 @@ +//! 弹窗消息的落点：关闭 / 展开 / 导出 / 打开文件夹 / 复制路径。 +//! +//! 只有两类副作用：**剪贴板**（返回 `Task`，必须交回 runtime）与**弹 Toast**（就地推）。 +//! 导出与打开文件夹是同步的本地动作（写一个 zip / 拉起一个 `explorer`），耗时都在毫秒级， +//! 不为它们单开线程——真要慢（网络盘）也是用户能感知的一次点击。 + +use iced::Task; +use unlucky_presenter::toast::ToastKind; + +use crate::app::dialog::{export, Message as DialogMessage}; +use crate::app::state::App; + +pub(super) fn on_dialog(app: &mut App, message: DialogMessage) -> Task { + match message { + DialogMessage::Primary => { + // M247：删除存档的二次确认——主按钮就是**真删**（这是本页唯一不可逆的动作）。 + // 目标记在 presenter 的状态里（`SavesState::confirm`）：模态队列只画框，不记"要删谁"。 + // + // **认框不认人**（复审 r1 P1-1）：只核销"当前这个框"登记的目标。哪怕某条关闭路径漏清， + // 崩溃卡片的「导出诊断包」也拿不走它——否则就是一次静默删世界。 + let current = app.state.dialogs.current().map(|request| request.id); + if let Some(dir) = current.and_then(|id| app.state.saves.take_confirm(id)) { + app.close_dialog(); + if let Some(instance) = app.selected_instance_id() { + app.state + .saves + .mark_pending(unlucky_presenter::state::SavesOp::Delete { + dir: dir.clone(), + }); + app.dispatch(unlucky_presenter::dto::AppCommand::Saves(Box::new( + unlucky_presenter::dto::SavesCommand::DeleteWorld { id: instance, dir }, + ))); + } + app.refresh_view(); + return Task::none(); + } + // 崩溃卡片的主按钮是「导出诊断包」；普通确认框的主按钮就是「关掉」。 + let Some(card) = app.dialog_card.clone() else { + app.close_dialog(); + return Task::none(); + }; + let done = export::export(&card.report, app.lang()); + // 结论**画在卡片里**：导出这种「必须看见落到哪」的结果不能只靠 Toast + // （app-iced 的 Toast 至今没有渲染点）。成败按 `write_bundle` 的真实结果判， + // 不看「launcher_logs 有没有值」——那只是入参齐全度（r1 复审 P3-2）。 + app.state.toasts.push( + if done.ok { + ToastKind::Success + } else { + ToastKind::Error + }, + done.text.clone(), + ); + if let Some(state) = &mut app.dialog_card { + state.outcome = Some(done.text); + } + app.view_dirty = true; + app.refresh_view(); + Task::none() + } + DialogMessage::Secondary | DialogMessage::Dismiss => { + // M247：取消/关掉删除确认框 ⇒ 忘掉那个目标（不然下一次点确定会删上一个）。 + // **只核销当前这个框的目标**（复审 r2 加固）：别人的框关掉时不该动我们的。 + if let Some(current) = app.state.dialogs.current().map(|request| request.id) { + app.state.saves.close_confirm(current); + } + app.close_dialog(); + // 立即重画：空闲态只有 1 Hz 心跳，只置 `view_dirty` 会让弹窗再留最多 1 秒 + // （r1 复审 P3-1）。 + app.refresh_view(); + Task::none() + } + DialogMessage::Toggle => { + app.toggle_dialog_detail(); + Task::none() + } + DialogMessage::OpenFolder => { + let Some(card) = app.dialog_card.clone() else { + return Task::none(); + }; + let problem = export::open_folder(&card.report, app.lang()); + if !problem.is_empty() { + if let Some(state) = &mut app.dialog_card { + state.outcome = Some(problem.clone()); + } + app.state.toasts.push(ToastKind::Error, problem); + app.view_dirty = true; + app.refresh_view(); + } + Task::none() + } + DialogMessage::CopyPaths => { + let Some(card) = app.dialog_card.clone() else { + return Task::none(); + }; + app.state.toasts.push( + ToastKind::Info, + app.lang() + .catalog() + .text(unlucky_i18n::catalog::Key::CrashDialogCopied), + ); + iced::clipboard::write(export::paths_text(&card.report)) + } + DialogMessage::CopyPath(index) => { + let Some(card) = app.dialog_card.clone() else { + return Task::none(); + }; + let Some((_, path)) = card.report.path_lines().into_iter().nth(index) else { + return Task::none(); + }; + app.state.toasts.push( + ToastKind::Info, + app.lang() + .catalog() + .text(unlucky_i18n::catalog::Key::CrashDialogCopied), + ); + iced::clipboard::write(path.display().to_string()) + } + } +} + +/// `Esc` 关弹窗（有弹窗时**先吃这一条**，不让它落到 AI 栏的 Esc 收起上）。 +pub(super) fn escape(app: &mut App) -> bool { + let Some(current) = app.state.dialogs.current().map(|request| request.id) else { + return false; + }; + // M247（复审 r1 P1-1）：**三条关闭路径都要清**——次按钮/遮罩清了，`Esc` 这条以前漏了， + // 于是"删存档 → Esc → 崩溃卡片 → 导出诊断包"会把那个世界静默删掉。 + // 现在还有 id 绑定兜一道（`take_confirm(current)`），这里是纵深防御的第二层。 + // 复审 r2 加固：清的时候**只清这个框自己的目标**（`close_confirm`），不碰别人的。 + app.state.saves.close_confirm(current); + app.close_dialog(); + app.refresh_view(); + true +} + +#[cfg(test)] +mod tests; diff --git a/crates/app-iced/src/app/update/dialog/tests.rs b/crates/app-iced/src/app/update/dialog/tests.rs new file mode 100644 index 0000000..206fc30 --- /dev/null +++ b/crates/app-iced/src/app/update/dialog/tests.rs @@ -0,0 +1,262 @@ +//! 主按钮 / Esc 的落点判据（M247，复审 r1 P1-1 / P2-1）：**接线**层，不是 presenter 的状态机。 +//! 一个 App + 一个只记账的后端，看"点了主按钮之后下发了什么"——「盘上的世界还在」在这里等价于 +//! 「没有下发 `DeleteWorld`」（app 不写盘，唯一写入口是 `host::saves::dispatch`）。 +//! 真实 `export()` 写没写 zip 由 `app/dialog/tests.rs` 的夹具覆盖，这里不造崩溃卡片。 + +use std::cell::RefCell; +use std::rc::Rc; + +use unlucky_design::color::SchemeFlavor; +use unlucky_presenter::dialogs::{DialogKind, DialogSource}; +use unlucky_presenter::dto::{ + AppCommand, AppEvent, Backend, CoreEvent, SavesCommand, SavesListView, WorldView, +}; +use unlucky_presenter::mock_data::mock_instances; +use unlucky_presenter::router::Route; +use unlucky_presenter::settings_bridge::SettingsBridge; + +use super::{escape, on_dialog}; +use crate::app::dialog::Message as DialogMessage; +use crate::app::message::Message; +use crate::app::state::App; +use crate::cli::Options; +use crate::pages; +use crate::theme::Families; + +const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", +}; +const DIR: &str = "Better World"; + +/// 只记账、按需喂事件的后端（与 `app/tests/presenter.rs` 的 recorder 同款）。 +#[derive(Debug, Default)] +struct SpyBackend { + dispatched: Rc>>, + events: Rc>>, +} + +impl Backend for SpyBackend { + fn drain_events(&mut self) -> Vec { + std::mem::take(&mut *self.events.borrow_mut()) + } + + fn dispatch(&mut self, command: AppCommand) { + self.dispatched.borrow_mut().push(command); + } +} + +/// 一个进到详情页、可喂事件、可记账的 App。 +struct Harness { + app: App, + dispatched: Rc>>, + events: Rc>>, +} + +impl Harness { + fn new() -> Self { + let dispatched = Rc::new(RefCell::new(Vec::new())); + let events = Rc::new(RefCell::new(vec![AppEvent::Core( + CoreEvent::InstancesChanged(mock_instances()), + )])); + let backend = SpyBackend { + dispatched: Rc::clone(&dispatched), + events: Rc::clone(&events), + }; + let mut harness = Self { + app: App::with_presenter( + Options::default(), + FAMILIES, + SchemeFlavor::Light, + Box::new(backend), + SettingsBridge::memory_only(), + ), + dispatched, + events, + }; + let _ = harness.app.update(Message::Boot); + assert_eq!( + harness.app.state.route(), + &Route::Detail("survival".to_string()), + "首屏该落在详情页（后面每一步都以它为前提交付目标）" + ); + harness + } + + /// 喂一条事件再抽干（`pump` 是唯一的 apply 入口，它顺带 `refresh_view`）。 + fn feed(&mut self, event: AppEvent) { + self.events.borrow_mut().push(event); + self.app.pump(); + self.app.refresh_view(); + } + + /// 点一次「删除 X」（页面消息的真实入口）。 + fn request_delete(&mut self) { + let _ = self.app.update(Message::Page(pages::Message::Instances( + pages::InstanceMessage::RequestDeleteWorld { + dir: DIR.to_string(), + }, + ))); + } + + /// 有没有下发过 `SavesCommand::DeleteWorld`（= core 会不会去删盘上的世界）。 + fn deleted(&self) -> bool { + self.dispatched.borrow().iter().any(|command| { + matches!( + command, + AppCommand::Saves(command) + if matches!(**command, SavesCommand::DeleteWorld { .. }) + ) + }) + } +} + +/// 一份 `saves/` 快照（`worlds` 决定"那个世界还在不在"）。 +fn snapshot(worlds: &[&str]) -> AppEvent { + AppEvent::Core(CoreEvent::Saves(Box::new(Ok(SavesListView { + instance: "survival".to_string(), + dir: "C:/mc/saves".to_string(), + exists: true, + worlds: worlds + .iter() + .map(|dir| WorldView { + dir: (*dir).to_string(), + icon: false, + modified_ms: None, + }) + .collect(), + screenshots_dir: "C:/mc/screenshots".to_string(), + screenshots_exists: false, + screenshots: Vec::new(), + skipped: Vec::new(), + last_op: None, + })))) +} + +/// **P1-1 事故链**：删存档 → `Esc` → 一个不相干的 `Confirm`（崩溃卡片的主按钮是「导出诊断包」） +/// → 点主按钮 ⇒ **没有** `DeleteWorld` 下发，框走它自己那条路（这里没有崩溃卡片 ⇒ 关框）。 +#[test] +fn escaping_the_delete_dialog_disarms_it_for_the_next_one() { + let mut harness = Harness::new(); + harness.request_delete(); + assert!( + harness.app.state.dialogs.current().is_some(), + "确认框没弹出来" + ); + assert!(harness.app.state.saves.confirm.is_some(), "目标没登记"); + + assert!(escape(&mut harness.app), "有框时 Esc 该被吃掉"); + assert!( + harness.app.state.saves.confirm.is_none(), + "Esc 之后目标还留着 —— 下一个框的主按钮会把它兑现" + ); + assert!(harness.app.state.dialogs.current().is_none()); + + // 不相干的框：崩溃卡片就是这个形态（`Confirm`，主按钮「导出诊断包」）。 + let _ = harness.app.state.dialogs.push( + DialogSource::UserAction, + "启动失败", + "退出码 1", + DialogKind::Confirm { + primary: "导出诊断包".to_string(), + secondary: "关闭".to_string(), + }, + ); + let _ = on_dialog(&mut harness.app, DialogMessage::Primary); + + assert!( + !harness.deleted(), + "Esc 之后那个目标被下一个框兑现了：世界被静默删除" + ); + assert!( + harness.app.state.dialogs.current().is_none(), + "主按钮该走它自己那条路（这里没有崩溃卡片 ⇒ 关框）" + ); +} + +/// **纵深防御（P1-1 的第二层）**：万一某条路径只关了框、**漏清**目标，下一个不相干的框 +/// 点主按钮也**拿不走**它 —— 因为 `take_confirm` 只有在"登记时那个框 == 当前框"时才交付。 +/// +/// 这条直接构造"漏清"状态（登记一个不存在的框 id），所以它**不依赖** `Esc` 那条路有没有清： +/// 去掉 id 校验，它立刻红。 +#[test] +fn a_leaked_target_cannot_be_redeemed_by_another_dialog() { + let mut harness = Harness::new(); + // 模拟事故形态：目标还挂着，但那个框早就不在了（登记 999 = 一个不存在的框）。 + harness.app.state.saves.ask_delete(999, DIR); + let _ = harness.app.state.dialogs.push( + DialogSource::UserAction, + "启动失败", + "退出码 1", + DialogKind::Confirm { + primary: "导出诊断包".to_string(), + secondary: "关闭".to_string(), + }, + ); + + let _ = on_dialog(&mut harness.app, DialogMessage::Primary); + + assert!( + !harness.deleted(), + "漏清的目标被别的框兑现了：世界被静默删除（P1-1 的事故形态）" + ); + assert!( + harness.app.state.saves.confirm.is_some(), + "别人的框不该顺手清掉我们的目标（清它的是关闭路径，不是主按钮）" + ); +} + +/// 反向：目标属于**当前**这个框时，主按钮仍然真的下发删除（没把功能关死）。 +#[test] +fn the_owning_dialog_still_deletes() { + let mut harness = Harness::new(); + harness.request_delete(); + let _ = on_dialog(&mut harness.app, DialogMessage::Primary); + + assert!(harness.deleted(), "自己的框点主按钮居然没删"); + assert!(harness.app.state.saves.confirm.is_none(), "取走即清"); + assert!( + harness.app.state.saves.pending.is_some(), + "该把那一行标成在飞（否则能连点）" + ); + assert!(harness.app.state.dialogs.current().is_none(), "框该关掉"); +} + +/// **P2-1**：世界还在 ⇒ 一拍无关快照（备份回程 / 打开文件夹回程）之后，主按钮照样删。 +#[test] +fn an_unrelated_snapshot_keeps_the_confirmation_redeemable() { + let mut harness = Harness::new(); + harness.request_delete(); + harness.feed(snapshot(&[DIR, "Other"])); + + assert!( + harness.app.state.saves.confirm.is_some(), + "无关快照把目标吃掉了：主按钮会变成静默空操作" + ); + assert!( + harness.app.state.dialogs.current().is_some(), + "框不该被收掉" + ); + let _ = on_dialog(&mut harness.app, DialogMessage::Primary); + assert!(harness.deleted(), "快照之后主按钮点了没反应"); +} + +/// **P2-1 的另一半**：世界从快照里消失 ⇒ 框被**收起来**（不是留一个点了没反应的按钮）， +/// 而且不下发删除（那个世界已经不存在了，下发只会换来一条 `WriteMissing` 噪音）。 +#[test] +fn a_vanished_world_closes_its_confirmation() { + let mut harness = Harness::new(); + harness.request_delete(); + harness.feed(snapshot(&["Other"])); + + assert!( + harness.app.state.saves.confirm.is_none(), + "作废的目标还留着" + ); + assert!( + harness.app.state.dialogs.current().is_none(), + "框没被收起：主按钮会是一次静默空操作" + ); + assert!(!harness.deleted(), "世界都不在了还下发删除"); +} diff --git a/crates/app-iced/src/app/update/dialog_fixture.rs b/crates/app-iced/src/app/update/dialog_fixture.rs new file mode 100644 index 0000000..bd1d9e5 --- /dev/null +++ b/crates/app-iced/src/app/update/dialog_fixture.rs @@ -0,0 +1,152 @@ +//! 启动失败弹窗的**取证夹具**（`ULL_DIALOG_FIXTURE`，只在 `--screenshot` 下生效）。 +//! +//! ## 为什么要有它 +//! +//! 弹窗要出两张图（「有 crash-report」/「只有捕获输出」），而真机上要复现一次崩溃得先让一个 +//! 真实的 MC 进程死掉——截图通道要的是**确定性**。做法与 `ULL_ACCOUNT_STATE` 同一档： +//! 在临时目录里造一份**真的文件树**（launcher.log / 会话 JSONL / crash-reports / latest.log）， +//! 于是弹窗上的路径是真路径、点「导出诊断包」真的会打出一个装得下这些文件的 zip。 +//! +//! 取值： +//! +//! | 值 | 现场 | +//! |---|---| +//! | `crash-report` | 游戏写了 `crash-reports/crash-*.txt`（证据一） | +//! | `no-logs` | 没有 crash-report、没有 latest.log，只有会话 JSONL 里的 stderr（证据二） | +//! | `export` | 同 `no-logs`，并在出图前**真的跑一次导出**（第三张图：路径 + 字节数） | +//! +//! 夹具只影响这一次进程；产品路径（`host/launch.rs` 收尾 → `crash_report::publish` → +//! `refresh_view` → 弹窗）与它完全同一条，这里只是**代填事实**。 + +use std::path::{Path, PathBuf}; + +use unlucky_core::launch::crash_report::{self, ArtifactFact, CrashReport}; +use unlucky_core::launch::crash_scan::{self, CrashSource}; +use unlucky_presenter::dto::{LaunchFinished, LogOutcome}; + +use crate::app::state::App; + +/// 现场根（`%TEMP%/ull-m187-fixture-`）。 +fn root() -> PathBuf { + std::env::temp_dir().join(format!("ull-m187-fixture-{}", std::process::id())) +} + +fn write(path: &Path, text: &str) { + if let Some(parent) = path.parent() { + let _ = std::fs::create_dir_all(parent); + } + let _ = std::fs::write(path, text); +} + +/// 出图用的夹具（`None` = 没有开关，什么都不做）。 +pub(super) fn apply(app: &mut App) -> Option { + let mode = std::env::var("ULL_DIALOG_FIXTURE").ok()?; + let mode = mode.trim().to_lowercase(); + if !app.has_screenshot() { + return None; + } + let root = root(); + let _ = std::fs::remove_dir_all(&root); + let logs = root.join("logs"); + write( + &logs.join("launcher.log"), + "2026-11-08T15:30:11.002Z [boot] renderer=wgpu\n\ + 2026-11-08T15:30:12.441Z [launch] instance=survival spawn game_dir=… java=javaw (21)\n\ + 2026-11-08T15:30:19.870Z [launch] instance=survival session=9f2c exit=1\n", + ); + write(&logs.join("install.log"), "installed 1.20.4-fabric\n"); + + let session = "9f2c4a1e-77bd-4f27-9d21-5b0a1f2c3d4e"; + let session_log = root + .join("sessions") + .join("game") + .join(format!("{session}.jsonl")); + write( + &session_log, + "{\"kind\":\"stdout\",\"payload\":{\"line\":\"[main/INFO]: Loading Minecraft 1.20.4\"}}\n\ + {\"kind\":\"stderr\",\"payload\":{\"line\":\"java.lang.RuntimeException: mixin injection failed\"}}\n\ + {\"kind\":\"stderr\",\"payload\":{\"line\":\"Caused by: java.lang.NoClassDefFoundError: org/lwjgl/glfw/GLFW\"}}\n\ + {\"kind\":\"exit\",\"payload\":{\"code\":1}}\n", + ); + let tail: Vec = vec![ + "[main/INFO]: Loading Minecraft 1.20.4".to_string(), + "java.lang.RuntimeException: mixin injection failed".to_string(), + "Caused by: java.lang.NoClassDefFoundError: org/lwjgl/glfw/GLFW".to_string(), + ]; + + let run_dir = root.join("instances").join("survival"); + let latest = run_dir.join("logs").join("latest.log"); + let version_json = root + .join("game") + .join("versions") + .join("1.20.4-fabric") + .join("1.20.4-fabric.json"); + write(&version_json, "{\"id\":\"1.20.4-fabric\"}\n"); + + let mut artifacts: Vec = Vec::new(); + if mode != "no-logs" { + write( + &run_dir + .join("crash-reports") + .join("crash-2026-11-08_15.30.19-client.txt"), + "---- Minecraft Crash Report ----\n\ + Time: 2026-11-08 15:30:19\n\ + Description: Initializing game\n\n\ + java.lang.RuntimeException: mixin injection failed\n\ + \tat net.fabricmc.loader.impl.launch.knot.Knot.init(Knot.java:142)\n\ + \tat net.minecraft.client.main.Main.main(Main.java:51)\n", + ); + write(&latest, "[15:30:12] [main/INFO]: Loading Minecraft 1.20.4\n[15:30:19] [Render thread/ERROR]: GLFW init failed\n"); + let since = std::time::SystemTime::now() - std::time::Duration::from_secs(120); + artifacts = crash_scan::scan(&run_dir, since, 8) + .into_iter() + .map(|artifact| ArtifactFact { + source: artifact.source.as_str().to_string(), + path: artifact.path, + excerpt: artifact.excerpt, + }) + .collect(); + } + + let report = CrashReport { + instance: "survival".to_string(), + name: "生存服的 1.20.4".to_string(), + version: "1.20.4-fabric".to_string(), + session: session.to_string(), + session_log: Some(session_log), + version_json: Some(version_json), + launcher_logs: Some(logs), + run_dir: Some(run_dir), + artifacts, + exit_code: Some(1), + exit_type: "application_error".to_string(), + uptime_ms: 7_400, + command: "javaw -Xmx4096m -Djava.library.path=… ".to_string(), + java: "C:/Program Files/Java/jdk-21/bin/javaw.exe (major 21)".to_string(), + system: "os=windows version=10.0.26100 arch=x86_64".to_string(), + stage: None, + stage_detail: None, + stderr_tail: tail, + }; + crash_report::publish(report); + let finished = LaunchFinished { + id: "survival".to_string(), + session: session.to_string(), + outcome: LogOutcome::Crashed, + exit_code: Some(1), + uptime_ms: 7_400, + failure: None, + }; + app.open_failure_dialog(&finished); + if mode == "export" { + // 走**真的**那一条：与用户点「导出诊断包」同一个处理函数。 + let _ = super::dialog::on_dialog(app, crate::app::dialog::Message::Primary); + } + Some(mode) +} + +/// 夹具里崩溃报告的来源名（与 `CrashSource::CrashReport` 同源，测试用）。 +#[allow(dead_code)] +pub(super) fn crash_report_source() -> &'static str { + CrashSource::CrashReport.as_str() +} 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>>); + + impl Backend for Recorder { + fn drain_events(&mut self) -> Vec { + 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>>); + +impl Backend for Recorder { + fn drain_events(&mut self) -> Vec { + 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>> = 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>> = 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>> = 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/instances.rs b/crates/app-iced/src/app/update/instances.rs new file mode 100644 index 0000000..f264e9e --- /dev/null +++ b/crates/app-iced/src/app/update/instances.rs @@ -0,0 +1,304 @@ +//! 实例页「启动参数」区的消息落点（M157）。 +//! +//! 三件事： +//! 1. **编辑**只改页面状态（`App::launch_form`）并置脏——不 dispatch，不打网络； +//! 2. **保存**派一条 [`AppCommand::SetInstanceLaunchArgs`]（整份五项补丁），回程由 +//! `InstancesChanged` 快照刷新页面（不做乐观回显，与 M90 的启动/停止同一条纪律）； +//! 3. **恢复跟随全局**只清表单（仍需用户点保存）——「点一下就写盘」会让误触直接生效。 +//! +//! **清脏的唯一时机是「回程快照等于表单」**：`LaunchForm::sync` 在「同实例 + 脏」时只在 +//! `matches(&view)` 成立时才清脏并重播种，其余情况原样保留草稿。保存本身**不清脏**——落盘成败 +//! 要等回程事件，写盘失败时旧快照回来必须留住用户敲的值（M157 r3 复审 P2-2）。 + +use iced::Task; +use unlucky_presenter::dialogs::{DialogKind, DialogSource}; +use unlucky_presenter::dto::{AppCommand, LaunchArgsPatch, ModsCommand, SavesCommand}; +use unlucky_presenter::state::SavesOp; + +use crate::pages::InstanceMessage; + +use super::super::message::Message; +use super::super::state::App; + +impl App { + /// 实例页详情列的一条消息（启动参数表单 + MODS 区）。 + pub(super) fn on_instance_message(&mut self, message: InstanceMessage) -> Task { + let Some(instance) = self.selected_instance_id() else { + return Task::none(); + }; + + match message { + // M224：启停一个 mod。**不做乐观翻面**——先把那个开关标成「请求在飞」（置灰）， + // 真状态等 host 回一份新快照（与 Save 分支同一条纪律）。 + // + // 这一支在 `bound_to` 守卫**之前**：MODS 区的启停只依赖「当前选中实例」， + // 与启动参数表单播没播种无关（守卫是给表单草稿用的，见下一条）。 + InstanceMessage::SetModEnabled { file, enabled } => { + self.state.mods.mark_pending(&file); + self.dispatch(AppCommand::Mods(Box::new(ModsCommand::SetEnabled { + id: instance, + file, + enabled, + }))); + return Task::none(); + } + // M235：重新列一次存档（失败后的「重试」也走这条）。 + // + // 与 `SetModEnabled` 一样放在 `bound_to` 守卫**之前**：存档区只认"当前选中实例"， + // 与启动参数表单播没播种无关（那条守卫是给表单草稿用的）。 + InstanceMessage::ReloadSaves => { + self.dispatch(AppCommand::Saves(Box::new(SavesCommand::List(instance)))); + return Task::none(); + } + // M235：打开存档文件夹——拉起哪个目录由 host 定（`saves/` → `screenshots/` → 运行目录）， + // 真正的 opener 在 `core::platform::opener`（平台差异不散到 app 这一层）。 + InstanceMessage::OpenSavesFolder => { + self.dispatch(AppCommand::Saves(Box::new(SavesCommand::OpenFolder { + id: instance, + }))); + return Task::none(); + } + // M247：行内重命名的三个动作。**输入过程不 dispatch**（只改 presenter 的草稿）， + // 提交才发命令——与启动参数表单「编辑只改状态，保存才派命令」同一条纪律。 + InstanceMessage::StartRenameWorld { dir } => { + self.state.saves.start_rename(&dir); + self.view_dirty = true; + self.refresh_view(); + return Task::none(); + } + InstanceMessage::RenameWorldChanged(text) => { + self.state.saves.edit_rename(text); + self.view_dirty = true; + self.refresh_view(); + return Task::none(); + } + InstanceMessage::CommitRenameWorld => { + let Some(draft) = self.state.saves.take_rename() else { + return Task::none(); + }; + // 空名字 / 没改 → 直接收起，不打后台：这两个不是"操作失败"，是"用户改主意了"。 + if draft.text.is_empty() || draft.text == draft.dir { + self.view_dirty = true; + self.refresh_view(); + return Task::none(); + } + self.state.saves.mark_pending(SavesOp::Rename { + dir: draft.dir.clone(), + }); + self.dispatch(AppCommand::Saves(Box::new(SavesCommand::RenameWorld { + id: instance, + dir: draft.dir, + to: draft.text, + }))); + return Task::none(); + } + InstanceMessage::CancelRenameWorld => { + self.state.saves.cancel_rename(); + self.view_dirty = true; + self.refresh_view(); + return Task::none(); + } + // M247：删除**先弹确认框**。确认目标是"哪个世界"必须记在状态里—— + // 主按钮落点在 `app/update/dialog.rs`，那里只有 `App`，没有这个页面。 + InstanceMessage::RequestDeleteWorld { dir } => { + let (title, body, primary, secondary) = + crate::pages::saves_delete_prompt(self.lang().catalog(), &dir); + // **先压框、拿到它的 id，再登记目标**：目标绑在那个框上（复审 r1 P1-1）—— + // 反过来（先登记再压框）会让"这一拍还没有框"的中间态挂在状态里，别的框的主按钮 + // 就有机会把它兑掉。 + let dialog = self.state.dialogs.push( + DialogSource::UserAction, + title, + body, + DialogKind::Confirm { primary, secondary }, + ); + self.state.saves.ask_delete(dialog, &dir); + self.view_dirty = true; + return Task::none(); + } + // M247：备份——落点由 host 定（`/exports/saves/`），回执里带完整路径。 + InstanceMessage::BackupWorld { dir } => { + self.state + .saves + .mark_pending(SavesOp::Backup { dir: dir.clone() }); + self.dispatch(AppCommand::Saves(Box::new(SavesCommand::BackupWorld { + id: instance, + dir, + dest: None, + }))); + return Task::none(); + } + // 表单还没对着这个实例（首帧还没播种）：不接编辑，免得改到别的实例上。 + _ if !self.launch_form.bound_to(&instance) => return Task::none(), + InstanceMessage::Jvm(text) => { + self.launch_form.jvm = text; + self.launch_form.dirty = true; + } + InstanceMessage::Game(text) => { + self.launch_form.game = text; + self.launch_form.dirty = true; + } + InstanceMessage::Memory(text) => { + self.launch_form.memory = text; + self.launch_form.dirty = true; + } + InstanceMessage::Java(text) => { + self.launch_form.java = text; + self.launch_form.dirty = true; + } + InstanceMessage::Backend(id) => { + self.launch_form.backend = id; + self.launch_form.dirty = true; + } + InstanceMessage::Reset => { + self.launch_form.reset(); + } + InstanceMessage::Save => { + // **不在这里清脏**：`dispatch` 只是把命令送出去，落盘成败要等回程事件。 + // 失败时（内存 `4g` / 写盘失败）pump 会带**旧快照**重建视图，脏标记若已清掉， + // `LaunchForm::sync` 就会用旧值覆盖用户刚敲的草稿（M157 r3 复审 P2-2）。 + // 清脏的唯一时机是「回程快照已经等于表单」——见 `LaunchForm::sync`。 + let patch: LaunchArgsPatch = self.launch_form.patch(); + self.dispatch(AppCommand::set_launch_args(&instance, patch)); + } + } + // 纯本地编辑：不重建视图模型（页面直接从表单画），只要一帧重绘即可——iced 在 + // 消息处理完之后本来就会画一帧，所以这里什么都不排。 + Task::none() + } + + /// 详情页当前选中的实例 id（不在详情页时为 `None`）。 + /// + /// `pub(in crate::app)`（M247）：删除确认框的主按钮在 `app/update/dialog.rs`，也要问同一个问题。 + pub(in crate::app) fn selected_instance_id(&self) -> Option { + match self.state.route() { + unlucky_presenter::router::Route::Detail(id) => Some(id.clone()), + _ => None, + } + } +} + +#[cfg(test)] +mod tests { + use unlucky_design::color::SchemeFlavor; + use unlucky_presenter::dto::LaunchArgsView; + use unlucky_presenter::settings_bridge::SettingsBridge; + + use crate::app::state::App; + use crate::cli::Options; + use crate::pages::{InstanceMessage, LaunchForm}; + + use crate::theme::Families; + + const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", + }; + + fn app_with_form() -> App { + let mut app = App::with_presenter( + Options::default(), + FAMILIES, + SchemeFlavor::Light, + Box::new(unlucky_presenter::mock::MockBackend::new()), + SettingsBridge::memory_only(), + ); + // 进详情页 + 直接放一份「已播种」的表单：本测试只验消息落点， + // 不验播种（那在 `LaunchForm::sync` 的单测里）。 + app.state.navigate(unlucky_presenter::router::Route::Detail( + INSTANCE.to_string(), + )); + app.launch_form = LaunchForm::from_view( + Some(INSTANCE), + &LaunchArgsView { + instance_id: INSTANCE.to_string(), + ..LaunchArgsView::default() + }, + ); + app + } + + /// 测试用的实例 id（mock 后端的实例快照里有它）。 + const INSTANCE: &str = "survival"; + + /// 编辑 → 脏；恢复 → 五项清空仍需保存；保存前不发命令。 + #[test] + fn editing_marks_dirty_and_reset_waits_for_save() { + let mut app = app_with_form(); + let _ = app.on_instance_message(InstanceMessage::Memory("6144".to_string())); + assert_eq!(app.launch_form.memory, "6144"); + assert!(app.launch_form.dirty); + + let _ = app.on_instance_message(InstanceMessage::Backend("vulkan".to_string())); + assert_eq!(app.launch_form.backend, "vulkan"); + + let _ = app.on_instance_message(InstanceMessage::Reset); + assert_eq!(app.launch_form.memory, ""); + assert_eq!(app.launch_form.backend, "default"); + assert!(app.launch_form.dirty, "恢复之后还得点保存才落盘"); + } + + /// **MODS 区的启停在表单守卫之前**（M224）：表单还没播种也照样能启停。 + /// + /// 抓得住：把 `SetModEnabled` 放回 `bound_to` 守卫之后——那时首帧的详情页点了开关 + /// 什么都不会发生（用户看到开关纹丝不动，也没有任何提示）。 + #[test] + fn mod_toggles_work_before_the_launch_form_is_bound() { + let mut app = app_with_form(); + // 页面已经打开（真路径上 `refresh_view` 的 `sync_mods` 会做这一步），但表单还没播种。 + app.state.bind_mods(Some(INSTANCE)); + app.launch_form = LaunchForm::from_view( + Some("other"), + &LaunchArgsView { + instance_id: "other".to_string(), + ..LaunchArgsView::default() + }, + ); + + let _ = app.on_instance_message(InstanceMessage::SetModEnabled { + file: "sodium.jar".to_string(), + enabled: false, + }); + + assert!( + app.state.mods.is_pending("sodium.jar"), + "启停被表单守卫挡住了（开关点了没反应）" + ); + } + + /// 表单没绑定到当前实例时不接编辑（否则草稿会写到别的实例上）。 + #[test] + fn edits_are_ignored_when_the_form_is_bound_elsewhere() { + let mut app = app_with_form(); + app.launch_form = LaunchForm::from_view( + Some("other"), + &LaunchArgsView { + instance_id: "other".to_string(), + ..LaunchArgsView::default() + }, + ); + let _ = app.on_instance_message(InstanceMessage::Memory("9999".to_string())); + assert_eq!(app.launch_form.memory, ""); + assert!(!app.launch_form.dirty); + } + + /// **保存只派发、不清脏**（M157 r3 复审 P2-2）：落盘成败要等回程事件， + /// 派发前清掉脏标记会让失败后的重播覆盖用户草稿。 + /// + /// 抓得住：Save 分支里又写回 `dirty = false`（那条路径在失败时丢草稿）。 + /// 抓不住：回程事件的真实时序——清脏判据在 `LaunchForm::sync` 的 + /// `confirmed_save_clears_dirty_and_reseeds` / `failed_save_keeps_the_draft` 里。 + #[test] + fn save_dispatch_keeps_the_dirty_flag() { + let mut app = app_with_form(); + let _ = app.on_instance_message(InstanceMessage::Memory("4g".to_string())); + assert!(app.launch_form.dirty); + let _ = app.on_instance_message(InstanceMessage::Save); + assert!( + app.launch_form.dirty, + "派发后仍要保留脏标记，等回程快照确认" + ); + assert_eq!(app.launch_form.memory, "4g", "派发不改表单内容"); + } +} diff --git a/crates/app-iced/src/app/update/motion_sync.rs b/crates/app-iced/src/app/update/motion_sync.rs new file mode 100644 index 0000000..3996dac --- /dev/null +++ b/crates/app-iced/src/app/update/motion_sync.rs @@ -0,0 +1,166 @@ +//! 动效的**起跑点**（M192 r1 复审 P1-1 修的正是这里）。 +//! +//! ## 为什么这条不能在 `view` 里 +//! +//! iced 0.14 的处理顺序是： +//! +//! ```text +//! 消息 ──► update() ← program.subscription() 在这里求值（iced_winit src/lib.rs:1338） +//! ──► build_user_interfaces() ← 这时才调 program.view（src/lib.rs:1233） +//! ``` +//! +//! 也就是说**订阅表的求值早于视图**。第一版把「内容标识变了 → 起跑」写在 `pages::render` +//! （= `view`）里，于是同一拍订阅表看不见轨道，`frames()` 要等下一条消息（最快鼠标抬起、 +//! 最慢 1 Hz 心跳）才打开；那一帧的 dt 又是整段空闲时长 ⇒ 轨道被当成「早已到期」清掉， +//! 用户看到的是一次 12/8px 的偏移闪跳，比硬切更难看。截图通道因为 `has_screenshot()` 恒真， +//! **结构上**不可能暴露这条。 +//! +//! 所以起跑搬到这里：`App::update` 处理完每一条消息后调 [`App::sync_motion`]， +//! 于是「轨道存在」对**同一拍**的 `subscription()` 可见，帧订阅当拍打开。 +//! +//! ## 标识从哪来 +//! +//! 从**路由**取（`AppState::route()` 是唯一真源），不从视图模型取：账户页 / AI 独立页不走 +//! `pages::render`，用路由才能表达「这一屏不归 pages 画」（`None`）——它们之间的切换不起跑， +//! 而「从它们回到某一屏」照旧跑换页那一档（复审 r1 结论 4 的硬切顺手收口）。 + +use unlucky_presenter::router::Route; + +use crate::app::components::motion; +use crate::pages; + +use super::boot_env::MotionFixture; + +use super::*; + +impl App { + /// 每条消息处理完之后同步一次内容标识（**必须在 `update` 里**，理由见模块文档）。 + pub(in crate::app) fn sync_motion(&mut self) { + // **还没有窗口就什么都不做**（也不记标识）：动效是画出来的东西，没有窗口时 + // `window::frames()` 一条消息也不会有，起跑只会白占一档。更要紧的是「首屏入场」的语义—— + // 等窗口到了再算「第一眼看到的内容」，否则首屏那一下会被启动期的空树吃掉。 + // 截图通道例外：它的窗口句柄也是异步到的，而序列图必须从第 1 帧就按钉住的相位画。 + if self.window.is_none() && !self.has_screenshot() { + return; + } + let route = self.state.route(); + let screen = screen_key(route); + let detail = match route { + Route::Detail(id) => Some(id.as_str()), + _ => None, + }; + motion::observe(screen, detail); + } + + /// 出图取证：让这一次进程真的发生一次「换页」或「列表 → 详情」（见 [`super::boot_env::MotionFixture`]）。 + pub(in crate::app) fn motion_fixture(&mut self) { + let Some(fixture) = super::boot_env::env_motion_fixture() else { + return; + }; + let route = match (fixture, self.frames) { + // 列表 → 详情：第 1 帧先回列表（详情收起来），第 2 帧再点进第一条实例。 + (MotionFixture::Detail, 1) => Route::Instances, + (MotionFixture::Detail, 2) => { + let Some(first) = self + .state + .tiles() + .first() + .map(|cell| cell.instance.id.clone()) + else { + return; + }; + Route::Detail(first) + } + (MotionFixture::Route(route), 1) => route, + _ => return, + }; + diag!("[motion] ULL_MOTION_FIXTURE → {route:?}"); + self.state.navigate(route); + self.view_dirty = true; + self.refresh_view(); + } + + /// 真机空闲取证：`ULL_MOTION_FIXTURE_AT=<秒>` 到点就**真的**导航一次（`on_heartbeat` 调）。 + /// + /// 为什么不用点击：[`super::boot_env::env_motion_fixture_at`] 的文档写了原因——本机会话没有 + /// 前台窗口，合成鼠标事件递不进 iced 的输入层。心跳这条路与点击在 `update` 之后是同一段代码。 + /// 返回 `true` = 这一拍真的跳了页。 + pub(in crate::app) fn motion_fixture_after_idle(&mut self) -> bool { + use std::sync::atomic::{AtomicU32, Ordering}; + /// 已经过去的心跳数（进程内一次；只有取证开关打开时才会用到）。 + static FIXTURE_BEATS: AtomicU32 = AtomicU32::new(0); + + let Some(target) = boot_env::env_motion_fixture_at() else { + return false; + }; + let beat = FIXTURE_BEATS.fetch_add(1, Ordering::Relaxed) + 1; + if beat != target { + return false; + } + let route = match boot_env::env_motion_fixture() { + Some(MotionFixture::Route(route)) => route, + Some(MotionFixture::Detail) => { + let Some(id) = self + .state + .tiles() + .first() + .map(|cell| cell.instance.id.clone()) + else { + return false; + }; + Route::Detail(id) + } + None => Route::Download, + }; + diag!("[motion] ULL_MOTION_FIXTURE_AT 到点（第 {beat} 次心跳）→ {route:?}"); + self.state.navigate(route); + self.view_dirty = true; + self.refresh_view(); + true + } +} + +/// 路由 → 屏的稳定键（`pages::Screen::ALL` 的下标 + 1；`None` = 不归 pages 画）。 +/// +/// 与 `pages::Screen::of` 同一判据（`Screen::Instances` ↔ `Route::Instances | Route::Detail(_)`）， +/// 只是把「有没有这一屏」也表达出来——`pages::Screen::of` 给的是 `Option`，这里 +/// 再折成 `Option` 给帧泵用。 +fn screen_key(route: &Route) -> Option { + let screen = pages::Screen::of(route)?; + pages::Screen::ALL + .iter() + .position(|candidate| *candidate == screen) + .map(|index| index as u64 + 1) +} + +#[cfg(test)] +mod tests { + use super::*; + + /// 路由 → 屏键：五个一级页各自唯一，`Detail` 归「实例」，账户/AI 不归 pages。 + #[test] + fn only_the_five_screens_get_a_key() { + let keys: Vec> = [ + Route::Instances, + Route::Download, + Route::Content, + Route::Settings, + Route::Logs, + Route::Detail("survival".to_string()), + Route::Accounts, + Route::Agent, + ] + .iter() + .map(screen_key) + .collect(); + + assert_eq!(&keys[..5], &[Some(1), Some(2), Some(3), Some(4), Some(5)]); + assert_eq!( + keys[5], + Some(1), + "详情页归「实例」那一屏（与 Screen::of 同源）" + ); + assert_eq!(keys[6], None, "账户页不归 pages 画"); + assert_eq!(keys[7], None, "AI 独立页不归 pages 画"); + } +} 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..5494647 --- /dev/null +++ b/crates/app-iced/src/app/update/page_messages.rs @@ -0,0 +1,257 @@ +//! 页面消息的落点（`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::app::diag::diag; +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 { + // 下载页的四支（含「刷新下载源」）在 `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)), + // M159：自更新动作（检查 / 下载安装 / 忽略 / 立即重启 / 开关自动检查） + pages::Message::Update(action) => return self.on_update_action(action), + 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), + // M229：换主题档（Ink / Silver / 跟随系统）——换 `Ui` 的色板 + 落盘 + // `appearance.theme_mode`。与语言行同一条「页面消息直接改本地 + 落盘」的路。 + pages::Message::Theme(mode) => return self.set_theme_mode(mode), + // 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(); + } + // M157：实例页「启动参数」区（编辑写进页面状态；保存才派发命令） + pages::Message::Instances(message) => return self.on_instance_message(message), + // M114：账户页（三轨登录 / 列表动作 / 表单输入） + pages::Message::Account(message) => return self.on_account(message), + // M188：日志页与设置页的「打开日志文件夹」——同一个落点，路径从设置桥反推 + // （三模式都对），失败文本带完整路径，并**送进剪贴板**（打不开时用户至少能粘出去）。 + pages::Message::Action(pages::Action::OpenLogs) => { + return match crate::app::logs_folder::open() { + Ok(dir) => { + diag!("[logs] 已打开日志文件夹 {}", dir.display()); + Task::none() + } + Err(error) => { + diag!("[logs] 打开日志文件夹失败：{error}"); + iced::clipboard::write(error) + } + }; + } + // M223：实例页页头「导入」——以前是占位动作（点了只打一行日志），现在是 + // 「导入已有版本」向导的入口（M221 的 core 能力 + M223 的 presenter/GUI 接线）。 + pages::Message::Action(pages::Action::Import) => { + return self.on_adopt(crate::app::adopt::AdoptMessage::Open); + } + // 还没接后端的占位动作：只打日志（哪几个、为什么，见 pages 模块文档的偏离登记） + pages::Message::Action(action) => { + diag!("[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()) { + diag!("[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 { + 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..314bd49 --- /dev/null +++ b/crates/app-iced/src/app/update/settings/ai_about.rs @@ -0,0 +1,170 @@ +//! 助手（AI）分组消息的落点（M174）：草稿编辑 / 保存 / 测试连接。 +//! +//! 消息口在 `pages/settings/ai_about.rs`（`pages::settings::ai_about::Message`）；状态与读写落在 +//! `pages/settings/ai/{state,store}.rs`。本文件只有三件事： +//! +//! | 消息 | 做什么 | +//! |---|---| +//! | `ToggleEnabled` / `PickProvider` / `EditBaseUrl` / `EditModel` / `EditKey` / `Reveal` | 只改草稿（`dirty = true`） | +//! | `Save` | 先 [`State::validate`](pages::settings::ai::State::validate)，再 `ai::store::save`（真写 `launcher.json`） | +//! | `Test` | `Task::perform` 起一次真探测（`unlucky_cli::commands::agent::probe`），结果走 `ProbeDone` | +//! +//! ## 为什么「保存」不派 `AppCommand::SetSetting` +//! +//! 那条指令是可序列化的 DTO，`ai.api_key` 走它就意味着明文进了命令通道（事件日志 / mock 回放都会 +//! 看到）。`pages/settings/ai/store.rs` 的模块文档记着完整理由：这里走的是同一条 schema 通路 +//! （`SettingStore::set` + `save`），只是不经过那条通道。 +//! +//! ## 为什么「测试」读文件而不是读草稿 +//! +//! 测的是**已经保存的那份配置**（`probe_file` 每次现读 `launcher.json`）。用户在输入框里改了但没 +//! 点保存时，按钮旁边那句「有未保存的改动」会提醒他——而不是偷偷拿草稿去测一个不存在的配置。 + +use super::super::*; + +use crate::pages::settings::ai::{Probe, ProbeResult}; + +impl App { + /// 助手分组的一条消息。 + pub(super) fn on_settings_ai_about( + &mut self, + message: pages::settings::ai_about::Message, + ) -> Task { + use pages::settings::ai_about::Message; + + match message { + Message::ToggleEnabled(enabled) => { + self.settings.ai_about.enabled = enabled; + self.touch(); + } + Message::PickProvider(provider) => { + self.settings.ai_about.provider = provider; + self.touch(); + } + Message::EditBaseUrl(value) => { + self.settings.ai_about.base_url = value; + self.touch(); + } + Message::EditModel(value) => { + self.settings.ai_about.model = value; + self.touch(); + } + Message::EditKey(secret) => { + self.settings.ai_about.key = secret; + self.touch(); + } + Message::Reveal(reveal) => { + self.settings.ai_about.reveal = reveal; + self.view_dirty = true; + } + Message::Save => return self.save_ai_settings(), + Message::Test => return self.test_ai_connection(), + Message::ProbeDone(result) => { + self.settings.ai_about.probe = Probe::Done(*result); + self.view_dirty = true; + } + } + + Task::none() + } + + /// 记一次「草稿变了」：清掉旧回执（它已经在说另一份配置了），并让视图重建。 + fn touch(&mut self) { + self.settings.ai_about.dirty = true; + self.settings.ai_about.notice = None; + self.view_dirty = true; + } + + /// 从真值（`config/launcher.json`）灌一次草稿；截图通道改用 `ULL_AI_STATE` 的种子。 + /// + /// 什么时候调：① 构造之后（首屏就要显示已存的值）；② 配置文件被外部改过（`update/clock.rs` + /// 的 mtime 轮询）——`ull config set ai.model …` 或 AI 的 `set_config` 改完 1 秒内可见。 + /// **脏草稿不覆盖**（[`State::hydrate`](pages::settings::ai::State::hydrate) 自己判）， + /// 否则外部一改文件就把用户正在输入的内容冲掉。 + pub(in crate::app) fn hydrate_ai_settings(&mut self) { + if self.options.screenshot.is_some() { + let raw = std::env::var("ULL_AI_STATE").unwrap_or_else(|_| "unconfigured".to_string()); + if let Some(state) = pages::settings::ai::State::screenshot_seed(&raw) { + self.settings.ai_about = state; + } + return; + } + let Some(path) = self.bridge.path().map(std::path::Path::to_path_buf) else { + return; + }; + let snapshot = pages::settings::ai::store::load(&path); + if self.settings.ai_about.hydrate(snapshot) { + self.view_dirty = true; + } + } + + /// 保存：本地校验 → 落盘 → 用**落盘后读回来的真值**刷新草稿。 + fn save_ai_settings(&mut self) -> Task { + use pages::settings::ai::{store, SaveNotice}; + + if let Err(refusal) = self.settings.ai_about.validate() { + self.settings.ai_about.notice = Some(SaveNotice::Refused(refusal)); + self.view_dirty = true; + return Task::none(); + } + let Some(path) = self.bridge.path().map(std::path::Path::to_path_buf) else { + self.settings.ai_about.notice = Some(SaveNotice::NoStorage); + self.view_dirty = true; + return Task::none(); + }; + + let saved = store::save(&path, &self.settings.ai_about); + match saved { + Ok(snapshot) => { + // 先清脏再 hydrate：我们刚写进去的就是这一份，不存在「冲掉用户输入」。 + self.settings.ai_about.dirty = false; + self.settings.ai_about.hydrate(snapshot); + self.settings.ai_about.key = pages::settings::ai::Secret::default(); + self.settings.ai_about.notice = Some(SaveNotice::Saved); + } + Err(reason) => { + self.settings.ai_about.notice = + Some(pages::settings::ai::SaveNotice::Failed(reason)); + } + } + self.view_dirty = true; + Task::none() + } + + /// 测试连接：真探测在后台跑（`probe_file` 现读设置文件），结果经 `ProbeDone` 回来。 + fn test_ai_connection(&mut self) -> Task { + if !self.settings.ai_about.can_test() { + return Task::none(); + } + let Some(path) = self.bridge.path().map(std::path::Path::to_path_buf) else { + self.settings.ai_about.probe = Probe::Done(ProbeResult::from_outcome( + unlucky_cli::commands::agent::probe::ProbeOutcome::NotConfigured { + missing: unlucky_cli::commands::agent::probe::Missing::BaseUrl, + }, + 0, + )); + self.view_dirty = true; + return Task::none(); + }; + + self.settings.ai_about.probe = Probe::Running; + self.view_dirty = true; + Task::perform( + async move { + let started = std::time::Instant::now(); + let outcome = unlucky_cli::commands::agent::probe::probe_file( + &path, + unlucky_cli::commands::agent::probe::DEFAULT_TIMEOUT, + ); + ProbeResult::from_outcome(outcome, started.elapsed().as_millis()) + }, + |result| { + Message::Page(pages::Message::Settings( + pages::settings::GroupMessage::AiAbout( + pages::settings::ai_about::Message::ProbeDone(Box::new(result)), + ), + )) + }, + ) + } +} 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..79057e5 --- /dev/null +++ b/crates/app-iced/src/app/update/settings/download.rs @@ -0,0 +1,75 @@ +//! Downloads 分组消息的落点（M201）：**设置写回**的那一段（M101 `SETTINGSMSG` 的漏斗不变）。 +//! +//! 消息口在 `pages/settings/download.rs`（`pages::settings::download::Message`）。本文件只有一件事： +//! 把「用户改了哪个键」翻成 `AppCommand::SetSetting` —— 那是 presenter 已有的写回闭环 +//! （`host/dispatch.rs` 的 `SetSetting` 分支：`settings::set` 落盘 → `apply_tuning` → 重新发 +//! `CoreEvent::SettingsChanged`）。 +//! +//! ## 不做乐观回显 +//! +//! 这里**不**改任何「当前值」：界面上的值是 presenter 快照（`pages::Model.settings`）的投影， +//! 只有 host 把 `SettingsChanged` 发回来才会变。理由与下载页的安装/启动同一条纪律——本地改一份、 +//! host 回来再改一次，两边打架时界面就会各说一套（尤其是写盘失败：乐观回显会让用户以为改成了）。 +//! +//! ## 文本行为什么要「应用」才提交 +//! +//! 见 `pages/settings/download.rs` 的文件头：每敲一个键写一次盘会把半截值落进去。所以 +//! `Edit` 只改本地草稿（`view_dirty` 都不用翻：草稿由 `States` 直接读），`Commit` 才派发。 +//! 提交之后草稿当场丢掉——快照随即成为唯一真值，写失败时行上会回到文件里的值 + presenter 的 +//! 错误 Toast 说清原因（比留着一个没生效的草稿更诚实）。 + +use super::super::*; + +use unlucky_presenter::dto::{find_row, AppCommand}; + +impl App { + /// Downloads 分组的一条消息。 + pub(super) fn on_settings_download( + &mut self, + message: pages::settings::download::Message, + ) -> Task { + use pages::settings::download::Message; + + match message { + Message::Set { key, value } => { + self.dispatch(AppCommand::SetSetting { key, value }); + Task::none() + } + Message::Edit { key, value } => { + // 只改草稿：`body` 每一帧都从 `Groups.download` 读它，所以这里不必重建视图模型。 + self.settings.download.edit(&key, value); + Task::none() + } + Message::Commit { key } => { + let value = self.pending_text(&key); + self.settings.download.clear(&key); + self.dispatch(AppCommand::SetSetting { key, value }); + Task::none() + } + // 动作行（「重新检测地区」）：键名与动作 id 都由 presenter 的快照给，取值被 + // `settings::set` 忽略（那条分支先认键、再解析值）。 + Message::Action { key } => { + self.dispatch(AppCommand::SetSetting { + key, + value: String::new(), + }); + Task::none() + } + } + } + + /// 这一行要提交的文本：本地草稿优先，否则用快照里的当前值（= 文件里的值）。 + /// + /// 空串是合法提交（「留空 = 跟随默认」是这一组真有的语义），所以只有**两者都缺**才返回空串。 + fn pending_text(&self, key: &str) -> String { + self.settings + .download + .pending(key) + .or_else(|| find_row(&self.view.settings, key).map(|row| row.value_text.clone())) + .unwrap_or_default() + } +} + +#[cfg(test)] +#[path = "download_tests.rs"] +mod tests; diff --git a/crates/app-iced/src/app/update/settings/download_tests.rs b/crates/app-iced/src/app/update/settings/download_tests.rs new file mode 100644 index 0000000..f13b1e5 --- /dev/null +++ b/crates/app-iced/src/app/update/settings/download_tests.rs @@ -0,0 +1,332 @@ +//! Downloads 组的**写回闭环**（M201）：`控件 → Message → AppCommand::SetSetting → 真 host 写盘 +//! → CoreEvent::SettingsChanged → App 的快照与页面模型`。 +//! +//! 为什么这条断言必须在 app 层：链子的两头都是「有状态的东西」——中间断在任何一环，页面层测试 +//! 都看不见（它只拿到一份已经画好的模型）。要问的是「用户点了以后，**盘上和 App 认的值**变了吗」， +//! 而不是「按钮的 `on_press` 里有没有构造消息」。 +//! +//! 两个后端都测，因为它们证明的事不同： +//! +//! | 用例 | 后端 | 证明 | +//! |---|---|---| +//! | 前四条 | 假后端（按 host 形状回快照） | 搬运：消息 → 命令、命令 → 快照、快照 → 模型 | +//! | 最后一条 | **真 `CoreHost` + 临时数据根** | 整条链：命令 → `settings::set` → `launcher.json` 真的变了 | + +use std::cell::RefCell; +use std::rc::Rc; + +use unlucky_design::color::SchemeFlavor; +use unlucky_presenter::dto::{ + AppCommand, AppEvent, Backend, CoreEvent, SettingControl, SettingGroupView, SettingRowView, +}; +use unlucky_presenter::settings_bridge::SettingsBridge; + +use crate::cli::Options; +use crate::pages; +use crate::pages::settings::download; +use crate::theme::Families; + +use super::*; + +/// 这一组要断言的那个键（与 presenter 快照里的键同名）。 +const CONCURRENCY: &str = "download.concurrency"; +/// 一个文本键（代理地址）。 +const PROXY_URL: &str = "download.proxy_url"; + +const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", +}; + +/// 一份只有下载组的快照：并发 = `concurrency`，代理 = `proxy`。 +/// +/// 行形状照 presenter 的 `host::settings::download::group` 抄（choice + 档位选项，text + 原文）， +/// 只保留本文件断言要用的那两行——这里守的是 app 侧的搬运，不是 presenter 的行文案。 +fn snapshot(concurrency: &str, proxy: &str) -> Vec { + let options = ["4", "8", "16"]; + let selected = i32::try_from( + options + .iter() + .position(|item| *item == concurrency) + .unwrap_or(1), + ) + .expect("装得下"); + vec![SettingGroupView::new("download", "下载与镜像（D7）") + .with(SettingRowView::choice( + CONCURRENCY, + "并发数", + "同时下载的文件数", + &options, + selected, + )) + .with(SettingRowView::text( + PROXY_URL, + "HTTP 代理", + "manual 模式生效", + proxy, + ))] +} + +/// 记下令、并按 host 的形状回一条 `SettingsChanged` 的后端。 +struct Hostish { + commands: Rc>>, + queued: Vec, + /// 回事件时用的快照（`SetSetting` 之后换成「值真的变了」的那一份）。 + state: RefCell<(String, String)>, +} + +impl Backend for Hostish { + fn drain_events(&mut self) -> Vec { + std::mem::take(&mut self.queued) + } + + fn dispatch(&mut self, command: AppCommand) { + self.commands.borrow_mut().push(command.clone()); + if let AppCommand::SetSetting { key, value } = command { + let mut state = self.state.borrow_mut(); + if key == CONCURRENCY { + state.0 = value; + } else if key == PROXY_URL { + state.1 = value; + } + // host 写盘之后重新发一份快照（`dispatch.rs` 的 `SetSetting` 分支就这一行）。 + self.queued + .push(AppEvent::Core(CoreEvent::SettingsChanged(snapshot( + &state.0, &state.1, + )))); + } + } +} + +/// 一个装着 [`Hostish`] 的 App + 那本命令账。 +fn app() -> (App, Rc>>) { + let commands = Rc::new(RefCell::new(Vec::new())); + let backend = Hostish { + commands: Rc::clone(&commands), + queued: Vec::new(), + state: RefCell::new(("8".to_string(), "http://127.0.0.1:7890".to_string())), + }; + let mut app = App::with_presenter( + Options::default(), + FAMILIES, + SchemeFlavor::Light, + Box::new(backend), + SettingsBridge::memory_only(), + ); + // 首屏：收一份 host 的快照（产品路径在 `on_boot` 的 `RefreshAll` 之后就是这样）。 + app.state + .apply(AppEvent::Core(CoreEvent::SettingsChanged(snapshot( + "8", + "http://127.0.0.1:7890", + )))); + app.refresh_view(); + (app, commands) +} + +/// 一条设置页消息走完漏斗。 +fn send(app: &mut App, message: pages::settings::download::Message) { + let message = pages::Message::Settings(pages::settings::GroupMessage::Download(message)); + let _ = app.on_page(message); +} + +/// **主用例**：点一个档位 ⇒ 命令发出去了 ⇒ host 回的快照进了 App ⇒ 页面模型跟着换。 +/// +/// 抓得住： +/// 1. handler 不派发 `AppCommand::SetSetting`（写回那一行被删）——这时假后端收不到命令、 +/// 也回不出事件，快照停在旧值，红（变异验证见报告）； +/// 2. `pages::Model` 不从快照取设置（`view::model` 那行 `settings:` 被删）——`app.view.settings` +/// 是空的，`current_value` 返回 `None`，红； +/// 3. App 侧**乐观回显**（点完就地改本地值、不等事件）——把假后端的回事件删掉后第 2 段仍会绿， +/// 所以本用例的「红」只证明闭合回路；它抓不住「有没有多存一份本地值」这一半。 +/// +/// 抓不住：真实点击（`Chip` 的 `on_press` 是否被真的按下）、host 是否真的落盘（那是最后一条的活）。 +#[test] +fn changing_a_choice_value_lands_in_the_app_snapshot_and_the_page_model() { + let (mut app, commands) = app(); + assert_eq!( + download::current_value(app.settings_snapshot(), CONCURRENCY).as_deref(), + Some("8"), + "开局认的是 host 给的那份" + ); + + send( + &mut app, + pages::settings::download::Message::Set { + key: CONCURRENCY.to_string(), + value: "4".to_string(), + }, + ); + + assert!( + commands.borrow().iter().any(|command| matches!( + command, + AppCommand::SetSetting { key, value } if key == CONCURRENCY && value == "4" + )), + "写回必须走已有的 `AppCommand::SetSetting`（实际下发：{:?}）", + commands.borrow() + ); + assert_eq!( + download::current_value(app.settings_snapshot(), CONCURRENCY).as_deref(), + Some("4"), + "App 的设置快照必须跟着 host 回来那份变（不是本地 State 变）" + ); + assert_eq!( + download::current_value(&app.view.settings, CONCURRENCY).as_deref(), + Some("4"), + "页面模型（这一帧要画的值）也必须是 4：控件画的是 `Model.settings`" + ); +} + +/// 文本行：`Edit` 只改草稿（**不发指令**），`Commit` 才带着草稿去写盘。 +/// +/// 抓得住：`Edit` 也派发（每敲一个键写一次盘）、`Commit` 用快照旧值而不是草稿（用户输入丢失）。 +/// 抓不住：输入框本身的按键路径（`text_field` 的 `on_input` 是组件既有实现）。 +#[test] +fn typing_a_text_value_only_commits_on_demand() { + let (mut app, commands) = app(); + + send( + &mut app, + pages::settings::download::Message::Edit { + key: PROXY_URL.to_string(), + value: "http://127.0.0.1:1080".to_string(), + }, + ); + assert!( + commands.borrow().is_empty(), + "输入过程中不许写盘（半截值会落进 launcher.json）" + ); + + send( + &mut app, + pages::settings::download::Message::Commit { + key: PROXY_URL.to_string(), + }, + ); + assert!( + commands.borrow().iter().any(|command| matches!( + command, + AppCommand::SetSetting { key, value } if key == PROXY_URL && value == "http://127.0.0.1:1080" + )), + "提交时带的必须是**草稿**里的那一串（不是快照里的旧值）：{:?}", + commands.borrow() + ); + assert_eq!( + download::current_value(app.settings_snapshot(), PROXY_URL).as_deref(), + Some("http://127.0.0.1:1080"), + "提交后快照换成 host 回来的新值" + ); +} + +/// 动作行（「重新检测地区」）：派发的是那一行的键，值留空（presenter 那条分支先认键、不看值）。 +/// +/// 抓得住：动作按钮被写成「什么都不发」、或者把键发成按钮文案。 +#[test] +fn an_action_row_dispatches_its_key() { + let (mut app, commands) = app(); + let key = "download.action.detect_region".to_string(); + + send( + &mut app, + pages::settings::download::Message::Action { key: key.clone() }, + ); + + assert!( + commands.borrow().iter().any(|command| matches!( + command, + AppCommand::SetSetting { key: sent, .. } if sent == &key + )), + "动作行必须走「按 schema 键写设置」那一条既有通路：{:?}", + commands.borrow() + ); +} + +/// 快照里没有本组时，页面**不许**自己编一行（`controls_of` 空 = 退回演示行）。 +/// +/// 抓得住：把演示行当成真值画（M193 用户的投诉形状）。 +/// 抓不住：`settings/mod.rs` 那条退回路径本身（那是 `demo_card` 的事）。 +#[test] +fn an_empty_snapshot_yields_no_controls() { + let (mut app, _commands) = app(); + app.state.settings_groups.clear(); + app.refresh_view(); + + assert!(download::controls_of(app.settings_snapshot()).is_empty()); + // 有快照时，本组的控件种类就是 presenter 给的那几行（这里两份：choice + text）。 + let kinds = download::controls_of(&snapshot("8", "")); + assert_eq!( + kinds, + vec![SettingControl::Choice, SettingControl::Text], + "控件种类照快照的 `control` 字段画，不许自己另定" + ); +} + +/// **真 host 端到端**：点「16」⇒ 「设置页里改了就生效」这句话的正面证据。 +/// +/// 链子全长：`Message::Set` → `AppCommand::SetSetting` → 真 `CoreHost` 的 `dispatch.rs` 分支 +/// （`settings::set` 校验 + 落盘 + `apply_tuning` + 重新发 `SettingsChanged`）→ `AppState` → +/// `pages::Model::settings`。断言落在**磁盘上那串字节**上，不是任何中间变量。 +/// +/// 抓得住： +/// 1. 只改本地、不派发（`Message::Set` 的分支被删）⇒ `launcher.json` 里没有 16，红； +/// 2. 派发了但 handler 用了错误的键/值 ⇒ 文件里那个键还是出厂 8，红； +/// 3. 快照没跟着 host 的回流走（`view::model` 那行 `settings:` 被删）⇒ 页面模型空，红； +/// 4. 写盘校验被绕过（`settings::set` 不再 `save()`）⇒ 文件不存在/没变，红。 +/// +/// 抓不住：真实鼠标点击（本用例从 `Message` 起跑，`Chip::filter` 的 `on_press` 不在其中）、 +/// 引擎是否立刻吃到新值（`apply_tuning` 与 `concurrency_probe` 由 presenter 的 +/// `the_concurrency_setting_reaches_the_real_download_engine` 守）、以及界面像素（截图的事）。 +#[test] +fn a_choice_change_reaches_the_real_settings_file() { + let dir = std::env::temp_dir().join(format!("ull-m201-writeback-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&dir); + std::fs::create_dir_all(dir.join(".ULL/config")).expect("config 目录"); + let config = dir.join(".ULL/config/launcher.json"); + + let env = unlucky_presenter::host::HostEnv::at_root(&dir); + let mut app = App::with_presenter( + Options { + data_dir: Some(dir.clone()), + ..Options::default() + }, + FAMILIES, + SchemeFlavor::Light, + Box::new(unlucky_presenter::host::CoreHost::new(env)), + // 设置桥也指向同一个根：不碰用户的真配置。 + SettingsBridge::with_path(unlucky_presenter::backend::config_path(&dir)), + ); + // 首屏：产品路径在 `on_boot` 里派的就是这一条（真 host 会发 `SettingsChanged`）。 + app.dispatch(AppCommand::RefreshAll); + assert_eq!( + download::current_value(app.settings_snapshot(), CONCURRENCY).as_deref(), + Some("8"), + "临时根里没有这个键 ⇒ 快照给的是出厂 8（也是引擎的生效值）" + ); + + send( + &mut app, + pages::settings::download::Message::Set { + key: CONCURRENCY.to_string(), + value: "16".to_string(), + }, + ); + + let written = std::fs::read_to_string(&config).expect("写回之后 launcher.json 必须存在"); + assert!( + written.contains("\"concurrency\": 16"), + "磁盘上必须真的有 16（这才是「设置页里改了就生效」）：{written}" + ); + assert_eq!( + download::current_value(app.settings_snapshot(), CONCURRENCY).as_deref(), + Some("16"), + "host 把新快照发回来了，App 认的也是 16" + ); + assert_eq!( + download::current_value(&app.view.settings, CONCURRENCY).as_deref(), + Some("16"), + "页面模型也换成了 16（下一帧控件画的就是它）" + ); + + std::fs::remove_dir_all(&dir).ok(); +} 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..399f998 --- /dev/null +++ b/crates/app-iced/src/app/update/settings/java.rs @@ -0,0 +1,352 @@ +//! Java 分组消息的落点（M175）：扫描 / 手动路径 / 默认 JDK / 内存 / JVM 参数。 +//! +//! 消息口在 `pages/settings/java.rs`（`pages::settings::java::Message`）；状态与读写落在 +//! `pages/settings/java/{state,store}.rs`。本文件只有四件事： +//! +//! | 消息 | 做什么 | +//! |---|---| +//! | `Scan` / `CancelScan` | 起一次后台真扫盘 / 置取消位（进度由心跳灌回状态） | +//! | `AddDraft` / `Add` | 只改草稿 / 严格校验（真跑 `java -version`）+ 写手动名单 | +//! | `SelectRuntime` | 写 `java.selected_path`（**立刻落盘**，与「设为默认」的语义一致） | +//! | `EditMemory` / `EditJvm` / `Save` | 改草稿 / 校验后写 `java.default_memory_mb` + `java.extra_args` | +//! +//! ## 为什么「设为默认」不攒到「保存」里 +//! +//! 它与内存 / JVM 参数是两件事：前者是**选择**（点哪个用哪个，与方案里其它单选控件一致）， +//! 后者是**编辑**（有草稿、有脏标记、有保存）。把选择也攒进保存队列，用户点完「设为默认」看到 +//! 界面还标着旧的默认值，只会以为没生效。 +//! +//! ## 版本门槛（「为什么选它」那句话的数据） +//! +//! `requirement_for(mc_version)` 是 core 的纯函数（静态表，读不到版本 JSON 时也成立）。 +//! 页面自己不看盘：本文件在每次 hydrate 时算好 [`Context`] 塞进状态，渲染器只负责画。 + +use super::super::*; +use crate::app::diag::diag; + +use crate::pages::settings::java::{Context, Layer, Notice, Requirement}; + +/// M197 的两个落点（各自一个 `impl App` 块）：真下载一个 JDK / 三个设置键。 +mod downloads; +mod prefs; + +impl App { + /// Java 分组的一条消息。 + pub(super) fn on_settings_java( + &mut self, + message: pages::settings::java::Message, + ) -> Task { + use pages::settings::java::Message; + + match message { + Message::Scan => return self.start_java_scan(), + Message::CancelScan => { + self.settings.java.scan.cancel(); + self.hydrate_java_scan(); + } + Message::AddDraft(value) => { + self.settings.java.add_draft = value; + self.settings.java.notice = None; + self.view_dirty = true; + } + Message::Add => self.add_java_manual(), + Message::SelectRuntime(binary) => self.select_java_default(&binary), + Message::EditMemory(value) => { + self.settings.java.memory = value; + self.touch_java(); + } + Message::EditJvm(value) => { + self.settings.java.jvm = value; + self.touch_java(); + } + Message::Save => self.save_java_settings(), + // M197：真下载一个 JDK + 三个设置键。落点各自一个 `impl App` 块（见 `mod` 声明）。 + Message::Download(major) => return downloads::on_download(self, major), + Message::EditInstallRoot(value) => return prefs::on_edit_install_root(self, value), + Message::ToggleAutoInstall(on) => return prefs::on_toggle_auto_install(self, on), + Message::MoveVendor { index, up } => return prefs::on_move_vendor(self, index, up), + Message::ResetPriority => return prefs::on_reset_priority(self), + Message::SavePrefs => return prefs::on_save_prefs(self), + } + + Task::none() + } + + /// 三键写盘成功之后，请 presenter 重发一次设置快照（M204）。 + /// + /// ## 为什么需要这一拍 + /// + /// 本组的三键（`java.default_memory_mb` / `java.extra_args` / `java.selected_path`）走的是页面 + /// 自己的 `SettingStore`（`pages/settings/java/store.rs`：`set` 几个键 + **一次** `save()`）， + /// **不经过** `AppCommand::SetSetting` 的写盘分支。而 `CoreEvent::SettingsChanged` 全仓只有两处 + /// 发出（`dispatch.rs` 的 `SetSetting` 分支、`host/mod.rs` 的 `refresh_all`）——不请一次， + /// `AppState::settings_groups` 里 java 组那几行会停在旧值，直到下一次任何别的写入。 + /// + /// ## 为什么不是 `AppCommand::RefreshAll` + /// + /// `refresh_all()` 除重发快照之外还会 `versions::spawn_list`（拉版本清单）与 + /// `start_update_check`（自更新检查）——每点一次「保存内存」打两个网络请求，代价与动作不相称。 + /// 动作键 `JAVA_REFRESH_ACTION` 走的是同一条 `SetSetting` 分支的四个副作用臂，不写盘、不发网络。 + /// + /// ## 抓得住 / 抓不住 + /// + /// 抓得住：`tests/java_refresh.rs` 的 `saving_the_java_form_refreshes_the_host_settings_snapshot` + /// 用**真 `CoreHost` + 临时数据根**跑完整链，摘掉这一行的 dispatch 就红（实测）。 + /// 抓不住：presenter 是否会因为**别的原因**（下一次外部写盘）自己刷新——所以那条用例的判据是 + /// 「写盘后**当场**快照里有新值」，而不是「最终会有」。 + fn request_settings_refresh(&mut self) { + self.dispatch(AppCommand::SetSetting { + key: unlucky_presenter::dto::JAVA_REFRESH_ACTION.to_string(), + value: String::new(), + }); + } + + /// 记一次「草稿变了」：清掉旧回执（它已经在说另一份配置了），并让视图重建。 + fn touch_java(&mut self) { + self.settings.java.dirty = true; + self.settings.java.notice = None; + self.view_dirty = true; + } + + /// 从真值（`config/launcher.json` + 手动名单 + 扫描快照）灌一次状态。 + /// + /// 什么时候调：① 构造之后（首屏就显示已存的值）；② 配置文件被外部改过（`update/clock.rs` + /// 的 mtime 轮询）。**脏草稿不覆盖**（`State::hydrate` 自己判）。 + /// + /// 首次调用会**自动发起一次扫描**（用户实测的头一条抱怨就是「设置页内并没有自动检测本机已 + /// 安装过的 Java 路径」）：已经扫完 / 正在扫 / 截图通道都不重扫，所以它只发生一次。 + /// + /// 截图通道的两档：`ULL_JAVA_STATE=` 用种子（D30 可复现）； + /// `ULL_JAVA_STATE=live` 走**真路径**（读本机配置 + 真扫盘），用来人工看一眼「别的机器上到底 + /// 扫到了什么」——它不是出图档，所以扫描判据按产品路径算。 + pub(in crate::app) fn hydrate_java_settings(&mut self) { + let seeded = self.options.screenshot.is_some(); + if seeded { + let raw = std::env::var("ULL_JAVA_STATE").unwrap_or_else(|_| "two".to_string()); + if raw.trim() != "live" { + if let Some(state) = pages::settings::java::State::screenshot_seed(&raw) { + self.settings.java = state; + } + return; + } + // `ULL_JAVA_STATE=live`：不灌种子，继续往下走真路径（读本机配置 + 真扫盘）。 + } + let Some(config) = pages::settings::java::store::config_of(&self.bridge) else { + self.settings.java = pages::settings::java::State::default(); + return; + }; + let snapshot = pages::settings::java::store::load(&config); + self.settings.java.manual = pages::settings::java::store::load_manual(&config); + let changed = self.settings.java.hydrate(snapshot); + // M197：三个设置键（安装目录 / 发行版顺序 / 缺 JDK 时自动准备）+ 它们的生效值与来源层。 + let prefs_changed = self + .settings + .java + .prefs + .hydrate(pages::settings::java::prefs_store::load(&config)); + self.settings.java.effective = + pages::settings::java::prefs_store::effective(&config, &self.settings.java.prefs); + let scan_changed = self.hydrate_java_scan(); + self.settings.java.context = self.java_context(); + if changed || prefs_changed || scan_changed { + self.view_dirty = true; + } + // 自动扫一次（首屏就该有真数据）。**没有 `cfg!(test)` 分叉**：单测走的也是这条生产入口， + // 删掉这一行 / 把实参翻成 `true` ⇒ `tests/java.rs` 的 + // `the_first_hydrate_starts_a_real_scan_by_itself` 立刻红（r3 复审 P3-3 的缺口）。 + // + // 实参为什么恒为 `false`：截图档的 `empty|two|editing` 在上面就 `return` 了，能走到这里的 + // 只有「不是截图」与「`live` 档」两种，而 `live` 按产品路径算（见本函数文档 D30 的例外）。 + self.auto_scan_java_if_due(false); + } + + /// 该自动扫就发起一次（判据在 [`pages::settings::java::store::auto_scan_due`]）。 + /// + /// 抽出来是为了让「取消过就不再自动扫」（r2 复审 P2-2）有个窄的落点；而**首屏真的调了它** + /// 这件事由生产入口自己守（`tests/java.rs` 的那条首屏用例），不再靠 `cfg!(test)` 把调用关掉。 + pub(in crate::app) fn auto_scan_java_if_due(&mut self, screenshot: bool) -> bool { + let report = self.settings.java.scan.report(); + if pages::settings::java::store::auto_scan_due(&report, screenshot) { + let _ = self.start_java_scan(); + return true; + } + false + } + + /// 把后台扫描的快照灌进状态。返回是否变了。 + /// + /// M197 起这一拍**也**灌一次下载作业的快照：`app/update/clock.rs` 每拍只调这一个入口， + /// 而复用它比改心跳的调用点便宜（`clock.rs` 不在本 mission 的 scope 里）。 + /// 代价写在 `settings/java/downloads.rs`：下载期间进度按 1 Hz 刷新。 + pub(in crate::app) fn hydrate_java_scan(&mut self) -> bool { + let report = self.settings.java.scan.report(); + let mut changed = self.settings.java.apply_scan(&report); + if self.hydrate_java_downloads() { + changed = true; + } + if changed { + self.view_dirty = true; + } + changed + } + + /// 起一次扫描（真扫盘：托管根 + `JAVA_HOME`/`PATH`/标准安装位置 + 手动名单）。 + fn start_java_scan(&mut self) -> Task { + let Some(config) = pages::settings::java::store::config_of(&self.bridge) else { + self.settings.java.notice = Some(Notice::NoStorage); + self.view_dirty = true; + return Task::none(); + }; + let manual = pages::settings::java::store::load_manual(&config) + .into_iter() + .map(std::path::PathBuf::from) + .collect::>(); + let roots = pages::settings::java::store::managed_roots(&config); + self.settings.java.notice = None; + if self.settings.java.scan.start(roots, manual, true) { + self.hydrate_java_scan(); + } + self.view_dirty = true; + Task::none() + } + + /// 手动加一条 JDK 路径：严格校验 → 进名单 → 立刻出现在列表里。 + fn add_java_manual(&mut self) { + let Some(config) = pages::settings::java::store::config_of(&self.bridge) else { + self.settings.java.notice = Some(Notice::NoStorage); + self.view_dirty = true; + return; + }; + let draft = self.settings.java.add_draft.clone(); + match pages::settings::java::store::add_manual(&config, &draft) { + Ok((binary, row)) => { + self.settings.java.manual = pages::settings::java::store::load_manual(&config); + if !self + .settings + .java + .runtimes + .iter() + .any(|known| pages::settings::java::same_path(&known.binary, &binary)) + { + self.settings.java.runtimes.push(row); + self.settings + .java + .runtimes + .sort_by_key(|runtime| runtime.major); + } + self.settings.java.add_draft = String::new(); + // 手动加的这条已经是「盘上真扫到的一行」，所以顺便把「还没扫描过」这一档收掉： + // 否则列表里明明有一行，状态行却写着「还没扫描过」。 + self.settings.java.scanned = true; + self.settings.java.notice = Some(Notice::Added(binary)); + } + Err(refusal) => self.settings.java.notice = Some(Notice::Refused(refusal)), + } + self.view_dirty = true; + } + + /// 把某个运行时设为默认（写 `java.selected_path`，写完读回）。 + fn select_java_default(&mut self, binary: &str) { + let Some(config) = pages::settings::java::store::config_of(&self.bridge) else { + self.settings.java.notice = Some(Notice::NoStorage); + self.view_dirty = true; + return; + }; + match pages::settings::java::store::set_selected(&config, binary) { + Ok(snapshot) => { + // **不许清脏**（r1 复审 P2-1）：这一次只写了 `java.selected_path`，内存与 JVM + // 参数的草稿一个字节都没落盘。`hydrate` 在 `dirty` 时本来就保留草稿、只刷新 + // `selected` / `saved_*`，所以这里唯一正确的做法是什么都不动。 + self.settings.java.hydrate(snapshot); + self.settings.java.context = self.java_context(); + self.settings.java.notice = Some(Notice::DefaultSet(binary.to_string())); + // M204：这一笔也写进 launcher.json 了（`java.selected_path`），请 host 重发快照。 + self.request_settings_refresh(); + } + Err(error) => self.settings.java.notice = Some(write_notice(error)), + } + self.view_dirty = true; + } + + /// 保存内存 + JVM 参数：本地校验 → 落盘 → 用**落盘后读回来的真值**刷新。 + fn save_java_settings(&mut self) { + let state = &self.settings.java; + if let Err(refusal) = state.validate() { + self.settings.java.notice = Some(Notice::Refused(refusal)); + self.view_dirty = true; + return; + } + let Some(config) = pages::settings::java::store::config_of(&self.bridge) else { + self.settings.java.notice = Some(Notice::NoStorage); + self.view_dirty = true; + return; + }; + match pages::settings::java::store::save(&config, &self.settings.java) { + Ok(snapshot) => { + // 先清脏再 hydrate：我们刚写进去的就是这一份，不存在「冲掉用户输入」。 + self.settings.java.dirty = false; + self.settings.java.hydrate(snapshot); + self.settings.java.context = self.java_context(); + self.settings.java.notice = Some(Notice::Saved); + // M204：内存 + JVM 参数已经落盘（一次 `store.save()`），请 host 重发快照。 + self.request_settings_refresh(); + } + Err(error) => self.settings.java.notice = Some(write_notice(error)), + } + self.view_dirty = true; + } + + /// 当前实例的上下文（版本门槛 + 生效内存来自哪一层）。 + /// + /// 「当前实例」= 路由栈顶是详情页时那个实例，否则列表第一行。没有实例 ⇒ 空上下文 + /// （页面就不画门槛那一行，也不假装有要求）。 + fn java_context(&self) -> Context { + let tiles = self.state.tiles(); + let routed = match self.state.route() { + unlucky_presenter::router::Route::Detail(id) => { + tiles.iter().find(|cell| &cell.instance.id == id) + } + _ => None, + }; + let Some(cell) = routed.or_else(|| tiles.first()) else { + return Context::default(); + }; + let instance = cell.instance; + let requirement = unlucky_core::game::java::requirement_for(&instance.mc_version); + Context { + required: Some(Requirement { + instance: instance.name.clone(), + version: instance.mc_version.clone(), + minimum: requirement.minimum, + maximum: requirement.maximum, + }), + layer: Some(match instance.launch.memory_mb { + Some(mb) => Layer::Instance { + instance: instance.name.clone(), + mb, + }, + None => Layer::Global, + }), + effective_memory_mb: Some(instance.launch.memory_effective_mb), + } + } +} + +/// 写盘失败 → 回执：三档都走 i18n key。 +/// +/// `WriteError::Schema` 里装的是 `core::setting::StoreError` 的 `Display`（**中文**）， +/// 直出会把 `Not saved: IO 失败 @ …` 塞进英文界面（r2 复审 P3-3）——所以只进 stderr 日志， +/// 界面上给一句页面自己的「写不进去」。 +/// +/// `pub(super)`：`tests/java.rs` 直接钉这一层的映射（M199 起页面侧已经撞不到 schema 那一档）。 +pub(super) fn write_notice(error: pages::settings::java::store::WriteError) -> Notice { + use pages::settings::java::store::WriteError; + match error { + WriteError::Refused(refusal) => Notice::Refused(refusal), + WriteError::Unwritable(reason) => Notice::Unwritable(reason), + WriteError::Schema(detail) => { + diag!("[java] 设置写盘失败：{detail}"); + Notice::WriteFailed + } + } +} diff --git a/crates/app-iced/src/app/update/settings/java/downloads.rs b/crates/app-iced/src/app/update/settings/java/downloads.rs new file mode 100644 index 0000000..2583b91 --- /dev/null +++ b/crates/app-iced/src/app/update/settings/java/downloads.rs @@ -0,0 +1,118 @@ +//! 「下载一个 JDK」的 App 层落点（M197）。 +//! +//! 三件事： +//! +//! | 函数 | 谁调 | 干什么 | +//! |---|---|---| +//! | [`App::start_java_download`] | `Download(major)` 消息 | 本地判据（目录/承接方/落点/是否已在跑）→ 起后台作业 | +//! | [`App::hydrate_java_downloads`] | 心跳那一拍（经 `hydrate_java_scan`） | 把作业快照灌成视图差量；**刚成功**时重扫 + 按 `java.auto_install` 决定要不要设为默认 | +//! +//! ## 为什么轮询挂在 `hydrate_java_scan` 上 +//! +//! M175 的扫描已经是「后台线程 + 快照 + 心跳比对」的形状，`app/update/clock.rs` 每拍只调 +//! `hydrate_java_scan()` 这一个入口。下载作业是同一族东西（后台线程 + 快照），所以复用那一拍， +//! `clock.rs` 一个字节都不用改——代价是**下载期间进度按 1 Hz 刷新**（帧时钟的判据在 +//! `app/subscription.rs` 的 `needs_frames`，那是本 mission scope 之外的文件）。百分比一秒动一次 +//! 对一次 100 MB 级的下载是够的；要紧的是它**会动**，而不是每秒动 60 次。 +//! +//! ## 装完之后为什么要重扫 +//! +//! 列表里那一行「已安装：…」来自**真扫盘的结论**（M175 的 `ScanSlot`），不是另存的安装记录。 +//! 装完不重扫，界面上就会出现「下载成功」与「列表里没有它」并存——正是本仓最忌讳的那种自相矛盾。 + +use iced::Task; + +use crate::app::message::Message; +use crate::app::state::App; +use crate::pages; + +use unlucky_core::game::java::catalog; + +use crate::pages::settings::java::{prefs_store, store}; + +impl App { + /// 下载并安装某个大版本（`Download(major)` 的落点）。 + /// + /// 四道本地判据，任何一道不过都在下载区顶上写清原因（点了没反应是禁止的）： + /// ① 目录里有这个大版本；② 没有别的作业在跑；③ 有可写的设置文件与能解析的落点； + /// ④ 这一档在这台机器上真有一家发行版承接（纯判据，不联网）。 + pub(super) fn start_java_download(&mut self, major: u32) { + use pages::settings::java::downloads::{gh_proxy_of_config, Refusal, Request}; + + self.settings.java.download_notice = None; + self.settings.java.notice = None; + self.view_dirty = true; + + if catalog::find(major).is_none() { + self.settings.java.download_notice = Some(Refusal::UnknownMajor); + return; + } + if self.settings.java.downloads.busy() { + self.settings.java.download_notice = Some(Refusal::Busy); + return; + } + let Some(config) = store::config_of(&self.bridge) else { + self.settings.java.download_notice = Some(Refusal::NoStorage); + return; + }; + let priority = self.settings.java.priority_vendors(); + let domestic = self.settings.java.effective.domestic; + if catalog::vendors_for(major, &priority, domestic).is_empty() { + self.settings.java.download_notice = Some(Refusal::NoVendor); + return; + } + let saved_root = self.settings.java.prefs.saved_install_root.clone(); + let Some(cache_root) = prefs_store::cache_root(&config) else { + self.settings.java.download_notice = Some(Refusal::NoStorage); + return; + }; + let Some(install_root) = prefs_store::install_root(&config, &saved_root) else { + // 有设置文件但解析不出落点（standard 模式读不到系统目录）：说这一句， + // 而不是含糊的「没有可用的设置文件」。 + self.settings.java.download_notice = Some(Refusal::RootUnresolved); + return; + }; + let started = self.settings.java.downloads.start(Request { + major, + cache_root, + install_root, + priority, + // `download.gh_proxy`（M197 的任务书那句「默认值可改」）：空 = 跟随内置默认， + // `off` = 关，其余 = 覆盖前缀。Java 页不画这一项的 UI（归 M193 的下载设置页）。 + gh_proxy: gh_proxy_of_config(&config), + }); + if !started { + self.settings.java.download_notice = Some(Refusal::Busy); + } + } + + /// 把作业快照灌成视图差量（心跳那一拍调）。返回是否变了。 + pub(in crate::app) fn hydrate_java_downloads(&mut self) -> bool { + let report = self.settings.java.downloads.report(); + if report == self.settings.java.download_seen { + return false; + } + let fresh = report + .success + .clone() + .filter(|success| self.settings.java.download_seen.success.as_ref() != Some(success)); + self.settings.java.download_seen = report; + if let Some(success) = fresh { + // 新装上的一份：先重扫（列表要出现它），再按 `java.auto_install` 决定默认值。 + let _ = self.start_java_scan(); + if self.settings.java.prefs.saved_auto_install + && self.settings.java.selected.trim().is_empty() + { + self.select_java_default(&success.binary); + } + } + self.view_dirty = true; + true + } +} + +/// 消息→落点的那一层（`java.rs` 的 match 里一行转发）。 +pub(super) fn on_download(app: &mut App, major: u32) -> Task { + app.start_java_download(major); + Task::none() +} diff --git a/crates/app-iced/src/app/update/settings/java/prefs.rs b/crates/app-iced/src/app/update/settings/java/prefs.rs new file mode 100644 index 0000000..a36dacc --- /dev/null +++ b/crates/app-iced/src/app/update/settings/java/prefs.rs @@ -0,0 +1,126 @@ +//! 三个设置键的 App 层落点（M197）：`java.installRoot` / `java.vendorPriority` / `java.auto_install`。 +//! +//! ## 为什么这三项单独一个「保存」 +//! +//! M175 的「保存」只写内存 + JVM 参数（`java.default_memory_mb` / `java.extra_args`），那是**运行时 +//! 参数**；这三项是**装到哪、按什么顺序找、缺 JDK 时怎么准备**——改了它们的副作用是「下一次下载 / +//! 下一次扫描的落点变了」，与内存那两项混在一个按钮里，用户就不清楚自己刚保存的到底是哪一半。 +//! 于是两段各有自己的脏标记与保存按钮，各回读各的键。 +//! +//! ## 保存之后为什么立刻重扫 +//! +//! `java.installRoot` 改了 ⇒ 托管根的集合变了 ⇒ 「已检测到的 JDK」那份列表可能整份不同。 +//! 保存成功就重扫一次，界面不会出现「落点写着新目录，列表还是旧目录里的 JDK」。 +//! +//! ## 回读校验 +//! +//! `prefs_store::save` 返回的是**落盘后从磁盘读回来**的真值，[`Prefs::adopt`] 把草稿与 +//! 「落盘真值」两半都对齐到它：用户看到的就是磁盘上那份（要是 schema 把值规整过，界面显示的是 +//! 规整后的结果，而不是他刚敲的那串——这一条正是「改完回读验证已落盘」）。 + +use iced::Task; + +use crate::app::message::Message; +use crate::app::state::App; +use crate::pages; + +use super::super::java::write_notice; + +impl App { + /// `java.installRoot` 草稿（只改草稿，不写盘）。 + pub(super) fn edit_java_install_root(&mut self, value: String) { + self.settings.java.prefs.install_root = value; + self.settings.java.notice = None; + self.settings.java.download_notice = None; + self.view_dirty = true; + } + + /// `java.auto_install` 开关（只改草稿）。 + pub(super) fn toggle_java_auto_install(&mut self, on: bool) { + self.settings.java.prefs.auto_install = on; + self.settings.java.notice = None; + self.view_dirty = true; + } + + /// 发行版顺序上移 / 下移一行。 + pub(super) fn move_java_vendor(&mut self, index: usize, up: bool) { + let domestic = self.settings.java.effective.domestic; + if up { + self.settings.java.prefs.move_up(index, domestic); + } else { + self.settings.java.prefs.move_down(index, domestic); + } + self.settings.java.notice = None; + self.view_dirty = true; + } + + /// 恢复地区默认序（= 把这个键写回空，让地区那一层重新生效）。 + pub(super) fn reset_java_priority(&mut self) { + self.settings.java.prefs.reset_priority(); + self.settings.java.notice = None; + self.view_dirty = true; + } + + /// 保存三个键：本地校验 → 落盘 → **用读回的真值**刷新草稿与生效值 → 重扫一次。 + pub(super) fn save_java_prefs(&mut self) { + use pages::settings::java::Notice; + + self.view_dirty = true; + if let Err(refusal) = self.settings.java.prefs.validate() { + self.settings.java.notice = Some(Notice::Refused(refusal)); + return; + } + let Some(config) = pages::settings::java::store::config_of(&self.bridge) else { + self.settings.java.notice = Some(Notice::NoStorage); + return; + }; + match pages::settings::java::prefs_store::save(&config, &self.settings.java.prefs) { + Ok(snapshot) => { + self.settings.java.prefs.adopt(snapshot); + self.settings.java.effective = pages::settings::java::prefs_store::effective( + &config, + &self.settings.java.prefs, + ); + // 落点 / 顺序变了：托管根的集合可能整份不同，立刻重扫一次。 + // 顺序要紧：`start_java_scan` 会清 `notice`，所以回执写在它之后。 + let _ = self.start_java_scan(); + self.settings.java.notice = Some(Notice::PrefsSaved); + // M204：三键也已落盘（`java.installRoot` / `java.auto_install` / `java.vendorPriority` + // 一次 `store.save()`），请 host 重发快照——否则 `AppState::settings_groups` 里 + // java 组那三行停在旧值，要等下一次任何别的写入才跟上。 + self.request_settings_refresh(); + } + Err(error) => self.settings.java.notice = Some(write_notice(error)), + } + } +} + +/// 消息→落点的那一层（`java.rs` 的 match 里一行转发）。 +pub(super) fn on_edit_install_root(app: &mut App, value: String) -> Task { + app.edit_java_install_root(value); + Task::none() +} + +/// `ToggleAutoInstall` 的转发。 +pub(super) fn on_toggle_auto_install(app: &mut App, on: bool) -> Task { + app.toggle_java_auto_install(on); + Task::none() +} + +/// `MoveVendor` 的转发。 +pub(super) fn on_move_vendor(app: &mut App, index: usize, up: bool) -> Task { + app.move_java_vendor(index, up); + Task::none() +} + +/// `ResetPriority` 的转发。 +pub(super) fn on_reset_priority(app: &mut App) -> Task { + app.reset_java_priority(); + Task::none() +} + +/// `SavePrefs` 的转发。 +pub(super) fn on_save_prefs(app: &mut App) -> Task { + app.save_java_prefs(); + 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 { + 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..ea48080 --- /dev/null +++ b/crates/app-iced/src/app/update/settings/tests.rs @@ -0,0 +1,400 @@ +//! 设置页分组消息分发的**守门测试**（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) { + 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 { + 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 {{\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; + + // M175：`Ping` 随演示行一起删了，改用一个**真变体**（改内存草稿）——它同样只经这条漏斗 + // 改 `App` 状态，所以证据强度不变，还顺带证明这条臂真的接到了 handler 上。 + let _ = app.update(Message::Page(pages::Message::Settings( + pages::settings::GroupMessage::Java(pages::settings::java::Message::EditMemory( + "4096".to_string(), + )), + ))); + + assert!( + app.view_dirty, + "java 线的消息没有走到 `on_settings_java`：消息漏斗在某一环断了" + ); +} + +// --------------------------------------------------------------- M174：助手配置的活路径 + +/// 一个指向临时目录的设置桥（真文件，不是内存态）。 +pub(super) fn bridged_app(label: &str) -> (App, std::path::PathBuf) { + let dir = std::env::temp_dir().join(format!( + "ull-ai-app-{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); + let app = App::with_presenter( + Options::default(), + Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", + }, + SchemeFlavor::Light, + Box::new(MockBackend::new()), + SettingsBridge::with_path(&path), + ); + (app, path) +} + +fn ai(message: pages::settings::ai_about::Message) -> Message { + Message::Page(pages::Message::Settings( + pages::settings::GroupMessage::AiAbout(message), + )) +} + +/// **M174 的活路径**：设置页那四条消息（改端点/模型/密钥）+ 保存，真的写进 `launcher.json`。 +/// +/// 抓得住：handler 没接 `Save`、`store::save` 没写某一个键、写错键名、密钥没落盘。 +/// 抓不住：用户真的点了那颗按钮（那是 iced 事件循环的事），也抓不住「保存后 agent 读到了」 +/// （那一半由 `unlucky-cli` 的 `probe_file` 用例证明：它读的就是这个文件）。 +#[test] +fn saving_the_ai_form_writes_the_real_settings_file() { + use pages::settings::ai_about::Message as Ai; + + let (mut app, path) = bridged_app("save"); + let _ = app.update(ai(Ai::PickProvider( + pages::settings::ai::ProviderId::OpenAiCompatible, + ))); + let _ = app.update(ai(Ai::EditBaseUrl("http://127.0.0.1:8080/v1".to_string()))); + let _ = app.update(ai(Ai::EditModel("qwen2.5-7b".to_string()))); + let _ = app.update(ai(Ai::EditKey(pages::settings::ai::Secret::new( + "sk-live-app-path", + )))); + let _ = app.update(ai(Ai::Save)); + + let text = std::fs::read_to_string(&path).expect("保存之后应当有配置文件"); + assert!( + text.contains("\"base_url\": \"http://127.0.0.1:8080/v1\""), + "{text}" + ); + assert!(text.contains("\"model\": \"qwen2.5-7b\""), "{text}"); + assert!( + text.contains("\"provider\": \"openai_compatible\""), + "{text}" + ); + assert!(text.contains("\"api_key\": \"sk-live-app-path\""), "{text}"); + + // 保存之后：草稿清干净、回执是「已保存」、密钥输入框清空（值已进文件，不再留在 UI 状态里）。 + let state = &app.settings.ai_about; + assert_eq!(state.notice, Some(pages::settings::ai::SaveNotice::Saved)); + assert!(!state.dirty); + assert!(state.key.is_empty()); + assert_eq!(state.key_chars, "sk-live-app-path".chars().count()); + let printed = format!("{state:?}"); + assert!( + !printed.contains("sk-live-app-path"), + "UI 状态泄漏密钥：{printed}" + ); + std::fs::remove_dir_all(path.parent().unwrap().parent().unwrap()).ok(); +} + +/// **非法值不保存**：端点没有协议头时，保存被拦下、文件不动、回执是具名拒绝原因。 +#[test] +fn refusing_to_save_leaves_the_file_untouched() { + use pages::settings::ai_about::Message as Ai; + + let (mut app, path) = bridged_app("refuse"); + let _ = app.update(ai(Ai::EditBaseUrl("http://127.0.0.1:8080/v1".to_string()))); + let _ = app.update(ai(Ai::EditModel("qwen".to_string()))); + let _ = app.update(ai(Ai::Save)); + let saved = std::fs::read_to_string(&path).expect("第一次应当写成"); + + let _ = app.update(ai(Ai::EditBaseUrl("api.deepseek.com/v1".to_string()))); + let _ = app.update(ai(Ai::Save)); + assert_eq!( + app.settings.ai_about.notice, + Some(pages::settings::ai::SaveNotice::Refused( + pages::settings::ai::state::Refusal::BaseUrl + )), + "没有协议头的端点必须被拦下，且要说清原因" + ); + let after = std::fs::read_to_string(&path).expect("读文件"); + assert_eq!(saved, after, "被拒绝的保存不许改动文件：{after}"); + std::fs::remove_dir_all(path.parent().unwrap().parent().unwrap()).ok(); +} + +/// **未配置时不发请求**（GUI 侧那一半）：缺模型名时点「测试连接」不会起任务、不留 Running 态。 +#[test] +fn testing_without_configuration_does_nothing() { + use pages::settings::ai_about::Message as Ai; + + let (mut app, path) = bridged_app("no-test"); + let _ = app.update(ai(Ai::EditBaseUrl("http://127.0.0.1:8080/v1".to_string()))); + // 模型名空着 ⇒ `can_test()` 为假 + assert!(app.settings.ai_about.missing().is_some()); + let _ = app.update(ai(Ai::Test)); + assert_eq!( + app.settings.ai_about.probe, + pages::settings::ai::Probe::Idle, + "未配置时点测试不该有任何探测态（更不该发请求）" + ); + std::fs::remove_dir_all(path.parent().unwrap().parent().unwrap()).ok(); +} + +/// M175 r1 复审的用例（拆出来守 400 行硬线；`gate::every_source_file_stays_under_the_line_limit` 会红）。 +#[path = "tests/java.rs"] +mod java; + +/// M204：Java 组写盘之后请 host 重发快照（动作键 `JAVA_REFRESH_ACTION`）。 +#[path = "tests/java_refresh.rs"] +mod java_refresh; diff --git a/crates/app-iced/src/app/update/settings/tests/java.rs b/crates/app-iced/src/app/update/settings/tests/java.rs new file mode 100644 index 0000000..5dcbc43 --- /dev/null +++ b/crates/app-iced/src/app/update/settings/tests/java.rs @@ -0,0 +1,374 @@ +//! M175 的 App 层用例：**「设为默认」不许吃掉未保存的内存 / JVM 草稿**（r1 复审 P2-1）。 +//! +//! 为什么单独一个文件：`tests.rs` 加上它之后 446 行，越过 400 行硬线 +//! （`app/components/gate.rs` 的 `every_source_file_stays_under_the_line_limit` 会判红）。 + +use super::bridged_app; +use crate::app::Message; +use crate::pages; + +// --------------------------------------------------------------- M175 r1 P2-1：设为默认不许吃草稿 + +/// 一条 Java 分组消息 → 页面消息。 +fn java(message: pages::settings::java::Message) -> Message { + Message::Page(pages::Message::Settings( + pages::settings::GroupMessage::Java(message), + )) +} + +/// 改内存 / JVM 草稿（还没保存）之后去点「设为默认」，**草稿必须还在**，而且仍算未保存。 +/// +/// 复审 r1 P2-1 的现场：旧代码在 `select_java_default` 里先 `dirty = false` 再 `hydrate`， +/// 于是只写了 `java.selected_path` 的一次操作把用户没保存的内存 / JVM 参数一起冲掉， +/// 一个字节都没落盘、也没有任何提示。 +/// +/// 变异证明：把 `dirty = false` 那一行加回 `select_java_default` ⇒ 这条红（内存回到 2048、 +/// JVM 回到空、`dirty` 变假）。 +#[test] +fn setting_the_default_jdk_keeps_unsaved_memory_and_jvm_drafts() { + let (mut app, path) = bridged_app("java-select"); + + let _ = app.update(java(pages::settings::java::Message::EditMemory( + "6144".to_string(), + ))); + let _ = app.update(java(pages::settings::java::Message::EditJvm( + "-XX:+UseG1GC".to_string(), + ))); + assert!(app.settings.java.dirty, "改过草稿就该是脏的"); + assert_eq!(app.settings.java.saved_memory, 2048, "落盘真值还没变"); + + let _ = app.update(java(pages::settings::java::Message::SelectRuntime( + "C:/jdk-21/bin/java.exe".to_string(), + ))); + + assert_eq!( + app.settings.java.selected, "C:/jdk-21/bin/java.exe", + "设为默认必须真的写进去" + ); + assert_eq!( + app.settings.java.memory, "6144", + "内存草稿被「设为默认」清掉了（P2-1 的数据丢失）" + ); + assert_eq!( + app.settings.java.jvm, "-XX:+UseG1GC", + "JVM 草稿被「设为默认」清掉了（P2-1 的数据丢失）" + ); + assert!( + app.settings.java.dirty, + "内存 / JVM 参数还没保存，不许标成已保存" + ); + assert_eq!(app.settings.java.saved_memory, 2048, "落盘真值仍然没变"); + std::fs::remove_dir_all(path.parent().unwrap().parent().unwrap()).ok(); +} + +// --------------------------------------------------------------- r3 P3-3：首屏自动扫必须有落脚点 + +/// **首屏自动扫一次盘**这件事必须在测试里有落脚点（r3 复审 P3-3）。 +/// +/// 现场：`hydrate_java_settings` 末尾那次 `if !cfg!(test) { auto_scan_java_if_due(...) }` 整行删掉、 +/// 或把实参翻成 `true`（截图抑制档），全套测试仍是绿的——于是「设置页从不自动检测本机 Java」 +/// 这个**用户实测的头号抱怨**回来时没人拦。 +/// +/// 为什么这条不是「再把判据测一遍」：判据（`auto_scan_due` 的四条）与取消语义已经有用例；这里要 +/// 证明的是**首屏这条路真的调了它**。所以走的是生产入口（`construct.rs` 构造时与心跳都调 +/// `hydrate_java_settings`）与生产作业（真扫盘），没有 `cfg!(test)` 分叉、也没有注入假作业。 +/// +/// 判据为什么同步可判、且与线程快慢无关：`ScanSlot::start_with` 在起线程**之前**就把 `running` +/// 置真（同一把锁里）；万一扫描线程已经跑完，`finished` 会留着。所以「真的起过一次扫描」= 这两个 +/// 位里至少有一个（空槽两者都是假）——不用等线程，也不看这台机器扫到了什么。 +/// +/// 变异证明：①删掉 `self.auto_scan_java_if_due(false);` 这一行 ⇒ 两位仍是假 ⇒ 红； +/// ②把它改成 `self.auto_scan_java_if_due(true);` ⇒ 被 `auto_scan_due` 的 `!screenshot` 挡掉 ⇒ 红。 +#[test] +fn the_first_hydrate_starts_a_real_scan_by_itself() { + let (mut app, path) = bridged_app("java-autoscan"); + // 构造那一刻已经自动扫过一次（同一个入口）；这里要重新演一遍「首屏」，所以换一个空槽。 + app.settings.java.scan = pages::settings::java::store::ScanSlot::default(); + + app.hydrate_java_settings(); + + let report = app.settings.java.scan.report(); + assert!( + report.running || report.finished, + "首屏 hydrate 没有自动发起扫描（快照是空的 {report:?}）：设置页就不会自己检测本机 Java\ + （r3 P3-3 的回归）" + ); + // 收尾：取消这次真扫盘，别让它在后台继续探测本机 PATH 上的 java。 + app.settings.java.scan.cancel(); + std::fs::remove_dir_all(path.parent().unwrap().parent().unwrap()).ok(); +} + +// --------------------------------------------------------------- r2 P2-2：取消之后不许自己重新起来 + +static HOLD: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(true); + +/// 一个会一直卡住的扫描作业（直到被取消）。 +fn held_job( + _candidates: &[unlucky_core::game::java::staged::Candidate], + cancelled: &dyn Fn() -> bool, + _progress: &mut dyn FnMut(usize, usize), +) -> Vec { + while !HOLD.load(std::sync::atomic::Ordering::SeqCst) && !cancelled() { + std::thread::sleep(std::time::Duration::from_millis(10)); + } + Vec::new() +} + +/// 取消过一次之后，**配置文件再变（心跳重读）也不会把扫描自己拉起来**，状态行仍是「已取消」。 +/// +/// 现场（r2 复审 P2-2）：被取消的扫描 `running=false` / `cancelled=true` / `finished` 仍是 +/// `false`，而 `auto_scan_due` 不看 `cancelled` ⇒ `clock.rs` 的 `reload_if_changed` 每变一次 +/// `launcher.json`（存内存、改主题、改语言都算）就重新起一个扫描线程，用户的取消被无声撤销。 +/// +/// 变异证明：把 `auto_scan_due` 里的 `!report.cancelled` 去掉 ⇒ 这里 `auto_scan_java_if_due` +/// 会真的起第二个线程，`scanning` 变 `Some`、状态行不再是「已取消」⇒ 本条红。 +#[test] +fn a_cancelled_scan_is_not_started_again_by_a_config_reload() { + use std::sync::atomic::Ordering; + use std::time::{Duration, Instant}; + + HOLD.store(false, Ordering::SeqCst); + let (mut app, path) = bridged_app("java-cancel"); + // 构造时已经自动扫过一次（首屏那条生产入口，见上一条用例）；换成空槽，让本用例自己起。 + app.settings.java.scan = pages::settings::java::store::ScanSlot::default(); + + // 真起一次扫描（注入卡住的作业），再取消，等线程退出：report 变成 + // cancelled=true / finished=false —— 正是复审指认的那个形状。 + let slot = app.settings.java.scan.clone(); + assert!(slot.start_with(Vec::new(), Vec::new(), false, held_job)); + slot.cancel(); + let deadline = Instant::now() + Duration::from_secs(5); + while slot.report().running && Instant::now() < deadline { + std::thread::sleep(Duration::from_millis(10)); + } + assert!(!slot.report().running, "取消之后线程必须退出"); + assert!(slot.report().cancelled); + assert!(!slot.report().finished); + + // 心跳那条路：把状态灌一次（`hydrate_java_scan`），再走「该自动扫就扫」的判据。 + app.hydrate_java_scan(); + assert!(app.settings.java.cancelled, "状态行要留着「已取消」"); + assert!(app.settings.java.scanning.is_none()); + + // 心跳那条路：走**生产入口**（`clock.rs` 每发现配置文件变了就调 `hydrate_java_settings`）， + // 它末尾那次自动发起必须被「取消过」这一条挡住。 + app.hydrate_java_settings(); + assert!( + !slot.report().running, + "取消过的扫描不许被自动重新拉起（P2-2：用户取消被无声撤销）：{:?}", + slot.report() + ); + app.hydrate_java_scan(); + assert!( + app.settings.java.scanning.is_none(), + "状态行不许回到「正在扫描」" + ); + assert!( + app.settings.java.cancelled, + "取消标记要保持到下一次手动扫描为止" + ); + + HOLD.store(true, Ordering::SeqCst); + std::fs::remove_dir_all(path.parent().unwrap().parent().unwrap()).ok(); +} + +// --------------------------------------------------------------- r2 P3-3：core 的中文串不许直出 + +/// 写盘被 schema 拒时，界面拿到的是**页面自己的 key**，而不是 `StoreError` 的中文 `Display`。 +/// +/// 现场（r2 复审 P3-3）：`WriteError::Schema(format!("{error}"))` 里 `core::setting::StoreError` +/// 的 `Display` 是中文（`IO 失败 @ …` / `文件只读，拒绝保存: …`），原样渲染就是 +/// `Not saved: IO 失败 @ …`。 +/// +/// M199 起页面侧已经撞不到这一档了（`java.extra_args` 超长先被 `State::validate` 具名拒掉，见下一条 +/// 用例），所以这里直接钉 `write_notice` 这一层的映射：`Schema` 只能变成页面自己的 key。 +/// +/// 变异证明：把 `Schema(detail)` 映射成 `Notice::Unwritable(NotDirty)` ⇒ 红；把它拼进 +/// `Notice::Refused` 的 detail ⇒ 红（Debug 里会出现那句中文）。 +#[test] +fn a_schema_rejection_surfaces_as_a_page_key_not_the_core_sentence() { + use pages::settings::java::store::WriteError; + + let notice = super::super::java::write_notice(WriteError::Schema( + "IO 失败 @ /tmp/launcher.json".to_string(), + )); + assert_eq!(notice, pages::settings::java::Notice::WriteFailed); + let printed = format!("{notice:?}"); + assert!( + !printed.contains("IO 失败"), + "core 的中文句子漏进了界面文案：{printed}" + ); +} + +/// 粘了 2000 字符的 JVM 参数：保存被**具名理由**拦下，而且文件一个字节都不动。 +/// +/// 现场（r3 复审 P3-4）：`java.extra_args` 的 `max_len=1024` 只在 schema 那一档，页面侧不判长度 +/// ⇒ 用户得到的是那句通用的「写不进去」，具体原因只在 stderr。本用例走的是 App 那条真保存路径。 +/// +/// 变异证明：删掉 `State::validate` 里的 `MAX_JVM_ARGS` 判据 ⇒ notice 变回 +/// `Notice::WriteFailed`（schema 那一档），本条红。 +#[test] +fn an_overlong_jvm_line_is_refused_with_its_own_reason() { + use pages::settings::java::Notice; + + let (mut app, path) = bridged_app("java-jvm-long"); + let too_long = "-D".to_string() + &"x".repeat(2000); + let _ = app.update(java(pages::settings::java::Message::EditJvm(too_long))); + let _ = app.update(java(pages::settings::java::Message::Save)); + + let notice = app + .settings + .java + .notice + .clone() + .expect("保存必须留下一条回执"); + let Notice::Refused(reason) = notice else { + panic!("超长参数要给自己的原因（「太长」），不是那句通用的「写不进去」：{notice:?}"); + }; + assert_eq!( + reason.label(), + unlucky_i18n::Key::SettingsJavaReasonJvmTooLong, + "拒绝原因必须落到「太长」那条文案上（中英各一句，见 i18n 金表）" + ); + assert!(!path.exists(), "被本地校验拒掉的保存不许碰磁盘"); + std::fs::remove_dir_all(path.parent().unwrap().parent().unwrap()).ok(); +} + +// --------------------------------------------------------------- M197：三个设置键 + 真下载的落点 + +/// 三键改完点保存：**真落盘**、草稿被读回值收尾、不再脏，并且保存顺手重扫一次。 +/// +/// 变异证明：`save_java_prefs` 里不调 `prefs.adopt(snapshot)` ⇒ 草稿还是 `" D:/JDKs "`、 +/// `dirty` 仍为真 ⇒ 本条红；不调 `start_java_scan` ⇒ `scan.report().running` 那条红。 +#[test] +fn saving_the_three_keys_writes_them_and_reads_them_back() { + use pages::settings::java::prefs_store; + + let (mut app, path) = bridged_app("java-prefs"); + // 落点用这个临时数据根下的绝对路径：Windows / macOS / Linux 上都是绝对的， + // 断言于是与平台无关（写 "D:/JDKs" 在非 Windows 上是相对路径，会被解析到数据根下）。 + let home = path.parent().unwrap().parent().unwrap().to_path_buf(); + let jdks = home.join("JDKs").display().to_string(); + let _ = app.update(java(pages::settings::java::Message::EditInstallRoot( + format!(" {jdks} "), + ))); + let _ = app.update(java(pages::settings::java::Message::ToggleAutoInstall( + false, + ))); + let _ = app.update(java(pages::settings::java::Message::MoveVendor { + index: 0, + up: false, + })); + assert!(app.settings.java.prefs.dirty(), "改过三键就该是脏的"); + + let _ = app.update(java(pages::settings::java::Message::SavePrefs)); + + assert_eq!( + app.settings.java.notice, + Some(pages::settings::java::Notice::PrefsSaved) + ); + assert!( + !app.settings.java.prefs.dirty(), + "保存并把读回值当草稿之后不该还脏" + ); + assert_eq!( + app.settings.java.prefs.install_root, jdks, + "草稿必须等于磁盘上那份（trim 过的），不是用户刚敲的原样" + ); + assert!( + !app.settings.java.prefs.saved_auto_install, + "auto_install 要真变成关" + ); + + // 冷读：另起一次 load，确认三个键都在文件里。 + let snapshot = prefs_store::load(&path); + assert_eq!(snapshot.install_root, jdks); + assert!(!snapshot.auto_install); + assert_eq!(snapshot.priority.len(), 4, "下移之后落盘的是整条链"); + assert_ne!(snapshot.priority[0], "temurin", "顺序真的被改过"); + assert!( + app.settings.java.scan.report().running, + "改了落点必须重扫一次，否则列表还停在旧目录里" + ); + // 生效值也跟着换了层级（设了 installRoot ⇒ 落点来自设置）。 + assert_eq!( + app.settings.java.effective.root, jdks, + "生效落点必须是刚保存的那一个" + ); + std::fs::remove_dir_all(path.parent().unwrap().parent().unwrap()).ok(); +} + +/// `java.auto_install` 开着且还没有默认 JDK：装完之后自动把新装的那份设为默认。 +/// +/// 变异证明：把 `hydrate_java_downloads` 里那段 `saved_auto_install && selected.is_empty()` +/// 的判据删掉 ⇒ 本条红（`selected` 还是空）；把关掉那一档的断言反过来说明判据不是恒真。 +#[test] +fn auto_install_adopts_the_fresh_jdk_when_no_default_is_set() { + use pages::settings::java::downloads::{Report, Success}; + + let (mut app, path) = bridged_app("java-adopt"); + app.settings.java.prefs.saved_auto_install = true; + app.settings.java.selected = String::new(); + app.settings.java.downloads.seed_report(Report { + job: None, + tries: Vec::new(), + failure: None, + success: Some(Success { + major: 21, + vendor: "Eclipse Temurin", + root: "D:/jdks/temurin/21".to_string(), + binary: "D:/jdks/temurin/21/bin/java.exe".to_string(), + source: Some("tuna".to_string()), + reused: false, + }), + }); + assert!(app.hydrate_java_downloads(), "快照变了就要重建视图"); + assert_eq!( + app.settings.java.selected, "D:/jdks/temurin/21/bin/java.exe", + "auto_install 开着 + 没有默认 JDK ⇒ 新装的那份自动成为默认" + ); + let snapshot = pages::settings::java::store::load(&path); + assert_eq!( + snapshot.selected, "D:/jdks/temurin/21/bin/java.exe", + "而且真写进了 java.selected_path" + ); + + // 关掉 auto_install 时同样的成功快照**不**改默认。 + let (mut app, path) = bridged_app("java-adopt-off"); + app.settings.java.prefs.saved_auto_install = false; + app.settings.java.selected = String::new(); + app.settings.java.downloads.seed_report(Report { + job: None, + tries: Vec::new(), + failure: None, + success: Some(Success { + major: 17, + vendor: "Eclipse Temurin", + root: "D:/jdks/temurin/17".to_string(), + binary: "D:/jdks/temurin/17/bin/java.exe".to_string(), + source: None, + reused: true, + }), + }); + assert!(app.hydrate_java_downloads()); + assert_eq!(app.settings.java.selected, "", "关掉就不许替用户改默认"); + std::fs::remove_dir_all(path.parent().unwrap().parent().unwrap()).ok(); +} + +/// 点一个目录里没有的大版本：立刻在下载区顶上写清原因，**不**起线程。 +/// +/// 变异证明：把 `start_java_download` 里 `catalog::find(major).is_none()` 那道判据删掉 ⇒ +/// `download_notice` 为 `None`，本条红（点了却什么都不说是禁止的）。 +#[test] +fn an_unknown_major_is_refused_on_the_spot() { + use pages::settings::java::downloads::Refusal; + + let (mut app, path) = bridged_app("java-dl-refuse"); + let _ = app.update(java(pages::settings::java::Message::Download(99))); + assert_eq!( + app.settings.java.download_notice, + Some(Refusal::UnknownMajor) + ); + assert!(!app.settings.java.downloads.busy(), "不该起任何作业"); + std::fs::remove_dir_all(path.parent().unwrap().parent().unwrap()).ok(); +} diff --git a/crates/app-iced/src/app/update/settings/tests/java_refresh.rs b/crates/app-iced/src/app/update/settings/tests/java_refresh.rs new file mode 100644 index 0000000..1d9e0dd --- /dev/null +++ b/crates/app-iced/src/app/update/settings/tests/java_refresh.rs @@ -0,0 +1,307 @@ +//! M204：Java 组**写盘成功之后请 host 重发设置快照**这一拍（`JAVA_REFRESH_ACTION`）。 +//! +//! ## 为什么需要这一条（缺口是什么） +//! +//! Java 组的三键（`java.default_memory_mb` / `java.extra_args` / `java.selected_path`）走的是页面 +//! 自己的 `SettingStore`（`pages/settings/java/store.rs`：`set` 几个键 + **一次** `save()`）—— +//! 那是**同步、原子**的一次落盘，但**不经过** `AppCommand::SetSetting` 的写盘分支。而 +//! `CoreEvent::SettingsChanged` 全仓只有两处发出：`host/dispatch.rs` 的 `SetSetting` 分支与 +//! `host/mod.rs` 的 `refresh_all`。于是三键写成功之后，`AppState::settings_groups` 里 java 组那几行 +//! 会**停在旧值**，直到下一次任何别的写入（改并发、改主题……）顺手带一份新快照回来。 +//! +//! M204 的修法：落盘成功之后派发一条动作键（`dto::JAVA_REFRESH_ACTION`，`host::settings::set` +//! 见到它只返回 `Ok(())`，不写盘），让 `SetSetting` 分支照常重发 `SettingsChanged`。**没有**改用 +//! `RefreshAll`：那个还会 `versions::spawn_list` 与 `start_update_check`，每点一次保存打两个网络请求。 +//! +//! ## 两条用例证明的事不同 +//! +//! | 用例 | 后端 | 证明 | +//! |---|---|---| +//! | 第一条 | **真 `CoreHost` + 临时数据根** | 写盘 ⇒ 快照真的变了（磁盘 + 快照两头的字节级证据） | +//! | 第二条 | 假后端（记账）+ 本地校验拒绝 | **被拒的保存不许请求刷新**（那一拍只该跟在真落盘之后） | + +use std::cell::RefCell; +use std::rc::Rc; + +use unlucky_design::color::SchemeFlavor; +use unlucky_presenter::dto::{find_row, AppCommand, AppEvent, Backend, SettingGroupView}; +use unlucky_presenter::settings_bridge::SettingsBridge; + +use crate::cli::Options; +use crate::pages; +use crate::theme::Families; + +use super::*; + +/// 本组要断言的键（与 presenter 快照 / schema 同名）。 +const JVM: &str = "java.extra_args"; + +const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", +}; + +/// 一条 Java 分组消息 → 页面消息（与 `tests/java.rs` 同一个漏斗）。 +fn java(message: pages::settings::java::Message) -> Message { + Message::Page(pages::Message::Settings( + pages::settings::GroupMessage::Java(message), + )) +} + +/// 快照里某个键的**上屏文本**（`None` = 快照里没这一行）。 +/// +/// 用 `value_text` 而不是控件序号：Java 组这三个键里 `extra_args` / `selected_path` 是 text 行， +/// `value_text` 就是文件里的原文；内存那一行是四档 choice（见报告「没做/没验」第 ③ 条）， +/// 它的**当前值**表达在 `options[selected]` 上，所以本文件不对内存行做取值断言——那会把 +/// 「presenter 的四档表达不了 6144」这件事伪装成绿。 +fn row_value(groups: &[SettingGroupView], key: &str) -> Option { + find_row(groups, key).map(|row| row.value_text.clone()) +} + +/// **主用例**：改内存 + JVM 参数 ⇒ 点保存 ⇒ 磁盘变了 **且** host 发回来的快照也变了。 +/// +/// 链子全长（与本组的产品路径逐段对应）：`Message::EditMemory/EditJvm` → `State` 草稿 → +/// `Message::Save` → `store::save`（一次 `store.save()` 写两个键）→ `request_settings_refresh()` +/// → 真 `CoreHost` 的 `SetSetting` 分支（`settings::set` 认动作键、不写盘）→ +/// `CoreEvent::SettingsChanged(settings::groups(env))` → `AppState::settings_groups` → +/// `pages::Model::settings`。断言落在**磁盘字节**与**快照文本**上，不落在任何中间变量上。 +/// +/// 抓得住： +/// 1. 摘掉 `request_settings_refresh()` 的 dispatch（`save_java_settings` 里那一行）⇒ 快照仍是 +/// 空串 ⇒ 红（**这就是本用例的变异验证**，且是本文件第二条都不红的唯一原因）； +/// 2. 写盘没真发生（`store::save` 的 `save()` 被删）⇒ 磁盘断言红； +/// 3. 动作键在 presenter 侧被当成真键（`host::settings::set` 少了那条早退）⇒ `store.set` 报 +/// 「未知键」⇒ 页面拿到 error Toast、快照不更新 ⇒ 红； +/// 4. 快照回流被丢掉（`view::model` 的 `settings:` 那行被删）⇒ `app.view.settings` 空 ⇒ 红。 +/// +/// 抓不住：真实鼠标点击（本用例从 `Message` 起跑）；「页面上的值是不是旧值」这一半——写盘成功后 +/// 页面本来就该显示新值，旧值那一半由 `tests/java.rs` 的拒绝用例守（本地校验不过时文件一个字节 +/// 不动、回执是具名原因）。 +#[test] +fn saving_the_java_form_refreshes_the_host_settings_snapshot() { + let dir = std::env::temp_dir().join(format!("ull-m204-java-refresh-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&dir); + std::fs::create_dir_all(dir.join(".ULL/config")).expect("config 目录"); + let config = dir.join(".ULL/config/launcher.json"); + + let env = unlucky_presenter::host::HostEnv::at_root(&dir); + let mut app = App::with_presenter( + Options { + data_dir: Some(dir.clone()), + ..Options::default() + }, + FAMILIES, + SchemeFlavor::Light, + Box::new(unlucky_presenter::host::CoreHost::new(env)), + // 设置桥也指向同一个根：不碰用户的真配置。 + SettingsBridge::with_path(unlucky_presenter::backend::config_path(&dir)), + ); + // 首屏：产品路径在 `on_boot` 里派的就是这一条（真 host 会发 `SettingsChanged`）。 + app.dispatch(AppCommand::RefreshAll); + assert_eq!( + row_value(app.settings_snapshot(), JVM).as_deref(), + Some(""), + "临时根里没有 `java.extra_args` ⇒ 快照这一行是空串（出厂值就是没有额外参数）" + ); + + let _ = app.update(java(pages::settings::java::Message::EditMemory( + "6144".to_string(), + ))); + let _ = app.update(java(pages::settings::java::Message::EditJvm( + "-XX:+UseG1GC".to_string(), + ))); + let _ = app.update(java(pages::settings::java::Message::Save)); + + let written = std::fs::read_to_string(&config).expect("写回之后 launcher.json 必须存在"); + assert!( + written.contains("\"default_memory_mb\": 6144"), + "磁盘上必须真的有 6144：{written}" + ); + assert!( + written.contains("-XX:+UseG1GC"), + "磁盘上必须真的有那段 JVM 参数：{written}" + ); + + assert_eq!( + row_value(app.settings_snapshot(), JVM).as_deref(), + Some("-XX:+UseG1GC"), + "host 必须为刚写进去的三键重发一次快照（否则 AppState 里这一行还是旧值）" + ); + assert_eq!( + row_value(&app.view.settings, JVM).as_deref(), + Some("-XX:+UseG1GC"), + "页面模型也得跟着换：下一帧画的是 `Model.settings`" + ); + + std::fs::remove_dir_all(&dir).ok(); +} + +// --------------------------------------------------------------- 被拒的保存不许请求刷新 + +/// 只记账、不回事件的后端（本用例只关心「有没有发出那条动作键」）。 +struct Recorder(Rc>>); + +impl Backend for Recorder { + fn drain_events(&mut self) -> Vec { + Vec::new() + } + + fn dispatch(&mut self, command: AppCommand) { + self.0.borrow_mut().push(command); + } +} + +/// 本地校验把保存拦下来时，**一次刷新都不许请求**：那一拍只该跟在真落盘之后。 +/// +/// 抓得住：把 `request_settings_refresh()` 挪到 `validate()` 之前（或无条件调用）⇒ 这里能看见 +/// 动作键 ⇒ 红。抓不住：写盘失败的回执文案（那是 `tests/java.rs` 的 `write_notice` 用例）。 +#[test] +fn a_refused_save_does_not_ask_for_a_refresh() { + use pages::settings::java::Notice; + + let commands = Rc::new(RefCell::new(Vec::new())); + let dir = std::env::temp_dir().join(format!("ull-m204-java-refuse-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&dir); + std::fs::create_dir_all(dir.join("config")).expect("config 目录"); + let path = dir.join("config/launcher.json"); + + let mut app = App::with_presenter( + Options::default(), + FAMILIES, + SchemeFlavor::Light, + Box::new(Recorder(Rc::clone(&commands))), + SettingsBridge::with_path(&path), + ); + // 128 MB 低于 schema 的下限（512）：本地校验就该拦下，不写盘。 + let _ = app.update(java(pages::settings::java::Message::EditMemory( + "128".to_string(), + ))); + let _ = app.update(java(pages::settings::java::Message::Save)); + + // 越界的内存要在本地就被拒（具名原因 = schema 下限 512 那条文案，不是通用的「写不进去」）。 + let notice = app + .settings + .java + .notice + .clone() + .expect("被拒的保存必须留下一条回执"); + let Notice::Refused(reason) = notice else { + panic!("越界的内存必须是具名的本地拒绝：{notice:?}"); + }; + assert_eq!( + reason.label(), + unlucky_i18n::Key::SettingsJavaReasonMemoryRange, + "拒绝原因要落到「超出允许范围」那条文案上" + ); + assert!(!path.exists(), "被拒的保存不许碰磁盘"); + assert!( + !commands.borrow().iter().any(|command| matches!( + command, + AppCommand::SetSetting { key, .. } + if key == unlucky_presenter::dto::JAVA_REFRESH_ACTION + )), + "没落盘就没有可刷新的事实（实际下发：{:?}）", + commands.borrow() + ); + + std::fs::remove_dir_all(&dir).ok(); +} + +/// 真的落盘时，动作键**必须**发出去（正面那一半；与第一条互为背书）。 +/// +/// 为什么还要这一条：第一条用真 `CoreHost`，它的失败可能是「快照没回来」的任意一环；这一条把 +/// 「到底有没有派出那条动作键」单独钉住，红的行号不同，排查时不必再猜是哪一环。 +/// +/// 抓得住：`request_settings_refresh()` 的键名写错（比如漏了 `action` 段）⇒ presenter 会把它当 +/// 真键报「未知键」，而这条用例在本层就能看见键名对不对。 +/// 抓不住：presenter 收到动作键之后有没有真的重发快照（那是第一条的事）。 +#[test] +fn a_successful_save_dispatches_the_refresh_action_key() { + let commands = Rc::new(RefCell::new(Vec::new())); + let dir = std::env::temp_dir().join(format!("ull-m204-java-dispatch-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&dir); + std::fs::create_dir_all(dir.join("config")).expect("config 目录"); + let path = dir.join("config/launcher.json"); + + let mut app = App::with_presenter( + Options::default(), + FAMILIES, + SchemeFlavor::Light, + Box::new(Recorder(Rc::clone(&commands))), + SettingsBridge::with_path(&path), + ); + let _ = app.update(java(pages::settings::java::Message::EditJvm( + "-XX:+UseG1GC".to_string(), + ))); + let _ = app.update(java(pages::settings::java::Message::Save)); + + assert!(path.exists(), "这一条的前提是保存真的落盘了（临时根可写）"); + assert!( + commands.borrow().iter().any(|command| matches!( + command, + AppCommand::SetSetting { key, .. } + if key == unlucky_presenter::dto::JAVA_REFRESH_ACTION + )), + "落盘之后必须派发动作键（实际下发：{:?}）", + commands.borrow() + ); + + std::fs::remove_dir_all(&dir).ok(); +} + +// --------------------------------------------------------------- 「立即扫描」真的接线 + +/// 「立即扫描」在 App 层是**真接线**的：`Message::Scan` ⇒ 起一次真扫盘（不是只画了颗按钮）。 +/// +/// 为什么这一条住在本文件（而不是 `tests/java.rs`）：那个文件 374 行、`tests.rs` 正好 400 行， +/// 再开一个模块文件就要往 `tests.rs` 加一行 `mod`（400 → 401，撞 `gate` 的 400 行红线）。 +/// 主题上也勉强算同一族：两者都是「设置页那一组对 App 做了什么」的守卫（这条守扫描入口， +/// 上面几条守写回闭环）。 +/// +/// 抓得住：`on_settings_java` 的 `Message::Scan => return self.start_java_scan()` 被改成 +/// `Task::none()`（只画按钮不接线 —— 用户在早期投诉里点名的那一条）⇒ `report().running` +/// 仍是 `false`、`scanning` 仍是 `None` ⇒ 红（实测见报告「变异验证」M3）。 +/// 抓不住：扫描**结论**是否写对了（那是 `pages/settings/java/tests/runtime.rs` 的事）， +/// 也抓不住真实鼠标点击（本用例从 `Message` 起跑）。 +#[test] +fn pressing_scan_starts_a_real_scan() { + // 用截图档构造（`Options.screenshot = Some(..)`）**只为一个目的**：让首屏那次 + // `auto_scan_java_if_due` 不发生（`hydrate_java_settings` 的截图分支灌种子后直接 return）， + // 于是「开局没有扫描在跑」这个前提是确定的。手动点「立即扫描」走的是**同一条产品代码** + // （`start_java_scan` → `ScanSlot::start`），截图档不拦它。 + let dir = std::env::temp_dir().join(format!("ull-m204-java-scan-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&dir); + std::fs::create_dir_all(dir.join("config")).expect("config 目录"); + let path = dir.join("config/launcher.json"); + let mut app = App::with_presenter( + Options { + screenshot: Some(std::path::PathBuf::from("m204-scan.png")), + ..Options::default() + }, + FAMILIES, + SchemeFlavor::Light, + Box::new(Recorder(Rc::new(RefCell::new(Vec::new())))), + SettingsBridge::with_path(&path), + ); + assert!( + !app.settings.java.scan.report().running, + "这一条的前提：构造时没有扫描在跑" + ); + + let _ = app.update(java(pages::settings::java::Message::Scan)); + + let report = app.settings.java.scan.report(); + assert!( + report.running, + "「立即扫描」必须真的起一条扫描线程：{report:?}" + ); + assert!( + app.settings.java.scanning.is_some(), + "状态行要能区分「正在扫描」（`scanning` 不能还是 None）" + ); + + // 别把这条用例起的真扫盘留给后面的用例：置取消位，线程会在下一个候选边界退出。 + app.settings.java.scan.cancel(); + std::fs::remove_dir_all(&dir).ok(); +} diff --git a/crates/app-iced/src/app/update/update_action.rs b/crates/app-iced/src/app/update/update_action.rs new file mode 100644 index 0000000..a3ace85 --- /dev/null +++ b/crates/app-iced/src/app/update/update_action.rs @@ -0,0 +1,234 @@ +//! 自更新动作的落点（M159）：`pages::Message::Update(UpdateAction)` → presenter 指令 / 重启。 +//! +//! 三条纪律： +//! +//! 1. **不做乐观回显**：点了「下载并安装」不改本地状态，等 `CoreEvent::Update` 回来才变 +//! （与启动/安装同一条：本地状态与事件流打架时，界面会自说一套）； +//! 2. 更新的**判断**（要不要提示、失败算什么、版本比较）全在 core/presenter，这里只转发； +//! 3. 「立即重启」是本文件唯一碰进程的地方：先按同样的命令行拉起新进程，再退出自己—— +//! 正因为替换已经完成（新 exe 就在原路径上），拉起来的就是新版本。 + +use crate::app::diag::diag; +use iced::Task; +use unlucky_presenter::dto::AppCommand; + +use crate::pages::UpdateAction; + +use super::super::message::Message; +use super::super::state::App; + +impl App { + /// 一条更新动作。 + pub(super) fn on_update_action(&mut self, action: UpdateAction) -> Task { + match action { + UpdateAction::CheckNow => { + if self.update_busy() { + return self.refuse_busy("立即检查"); + } + self.dispatch(AppCommand::CheckUpdate) + } + UpdateAction::Apply => { + if self.update_busy() { + return self.refuse_busy("下载并安装"); + } + self.dispatch(AppCommand::ApplyUpdate) + } + UpdateAction::Dismiss => self.dispatch(AppCommand::DismissUpdate), + UpdateAction::SetAutoCheck(on) => self.dispatch(AppCommand::SetUpdateAutoCheck(on)), + UpdateAction::RestartNow => return self.restart_now(), + } + Task::none() + } + + /// 有没有一条检查/下载正在跑。 + /// + /// 与 `pages::Update::busy()` **同一个判据**（`applying` 或 `status == Checking`）： + /// presenter 的 `begin_check` / `begin_apply` 在 inflight 时静默 `return None`， + /// 所以「忙碌」这件事必须在按下之前就挡住——否则用户点了没反应，还以为按钮坏了（M161）。 + /// + /// 这一层是**最后一道**：按钮已经画成禁用（`pages/settings/update.rs` 的 `can_check` / + /// `can_apply`），但快捷键/未来新增的入口仍会走到这里。 + fn update_busy(&self) -> bool { + let view = &self.state.update; + view.applying || view.outcome.is_checking() + } + + /// 忙碌时把这条动作丢掉（不派发、不乐观改状态），并在日志里留一行取证。 + fn refuse_busy(&self, what: &str) -> Task { + diag!("[update] 已有一条检查/下载在跑，忽略重复的「{what}」"); + Task::none() + } + + /// 立即重启：按同样的命令行拉起自己，然后退出。 + /// + /// 截图通道（`--screenshot`）**不重启**：那条路每跑一次就该落一张图然后退出，重启会覆盖同一 + /// 文件、并把取证进程拖成死循环。 + fn restart_now(&mut self) -> Task { + if self.options.screenshot.is_some() { + diag!("[update] 截图通道不重启（忽略「立即重启」）"); + return Task::none(); + } + match std::env::current_exe() { + Ok(exe) => { + let args: Vec = std::env::args_os().skip(1).collect(); + // 子进程是本 GUI exe 自己（Subsystem=2，不会分到控制台）；走 `quiet` 是为了让 + // 「app-iced 里除 opener 外不留裸构造」这条规则整体可被守卫钉住（M217）。 + let spawned = unlucky_core::platform::child::quiet(&exe) + .args(&args) + .spawn(); + match spawned { + Ok(child) => diag!( + "[update] 已拉起新进程 pid={}：{}", + child.id(), + exe.display() + ), + Err(error) => { + diag!("[update] 拉起新进程失败：{error}（请手动重启启动器）"); + return Task::none(); + } + } + } + Err(error) => { + diag!("[update] 取 current_exe 失败：{error}"); + return Task::none(); + } + } + iced::exit() + } +} + +#[cfg(test)] +mod tests { + use std::sync::{Arc, Mutex}; + + use iced::Task; + use unlucky_design::color::SchemeFlavor; + use unlucky_presenter::dto::{AppCommand, AppEvent, Backend}; + use unlucky_presenter::settings_bridge::SettingsBridge; + + use crate::app::state::App; + use crate::cli::Options; + use crate::pages::UpdateAction; + use crate::theme::Families; + + const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", + }; + + /// 记录命令流的假后端：把 `dispatch` 收到的每一条抄进共享表（动作接线断没断靠它判）。 + struct Recorder { + seen: Arc>>, + } + + impl Backend for Recorder { + fn drain_events(&mut self) -> Vec { + Vec::new() + } + + fn dispatch(&mut self, command: AppCommand) { + self.seen + .lock() + .unwrap_or_else(|poisoned| poisoned.into_inner()) + .push(command); + } + + fn tick(&mut self, _elapsed: std::time::Duration) {} + } + + fn app() -> (App, Arc>>) { + let seen = Arc::new(Mutex::new(Vec::new())); + let app = App::with_presenter( + Options::default(), + FAMILIES, + SchemeFlavor::Light, + Box::new(Recorder { + seen: Arc::clone(&seen), + }), + SettingsBridge::memory_only(), + ); + (app, seen) + } + + fn last(seen: &Arc>>) -> AppCommand { + seen.lock() + .unwrap_or_else(|poisoned| poisoned.into_inner()) + .last() + .cloned() + .expect("应当派发过一条命令") + } + + /// 四个转发动作各自交给后端**对应的**指令（串线会红）。 + #[test] + fn every_update_action_reaches_the_backend() { + let (mut app, seen) = app(); + + let _: Task<_> = app.on_update_action(UpdateAction::CheckNow); + assert_eq!(last(&seen), AppCommand::CheckUpdate); + + let _ = app.on_update_action(UpdateAction::Apply); + assert_eq!(last(&seen), AppCommand::ApplyUpdate); + + let _ = app.on_update_action(UpdateAction::Dismiss); + assert_eq!(last(&seen), AppCommand::DismissUpdate); + + let _ = app.on_update_action(UpdateAction::SetAutoCheck(false)); + assert_eq!(last(&seen), AppCommand::SetUpdateAutoCheck(false)); + } + + /// **忙碌时按下去不发命令**（M161：此前点了没反应，因为 presenter 在 inflight 时静默返回）。 + /// + /// 三条都要钉住：①`Checking` 时「立即检查」不派发；②`applying` 时「下载并安装」不派发； + /// ③忙碌结束后**恢回可点**（失败/超时不该把按钮永久钉死）。 + #[test] + fn pressing_while_busy_dispatches_nothing() { + let (mut app, seen) = app(); + + app.state.update.outcome = unlucky_presenter::dto::UpdateOutcome::Checking; + let _ = app.on_update_action(UpdateAction::CheckNow); + assert!( + seen.lock() + .unwrap_or_else(|poisoned| poisoned.into_inner()) + .is_empty(), + "正在检查时再按「立即检查」不许派发第二条命令" + ); + + // 检查回来（失败也算回来）：不忙了，能再点。 + app.state.update.outcome = unlucky_presenter::dto::UpdateOutcome::Failed( + unlucky_presenter::dto::UpdateFailureView::new("network", "连不上", true), + ); + let _ = app.on_update_action(UpdateAction::CheckNow); + assert_eq!(last(&seen), AppCommand::CheckUpdate, "失败之后要能重试"); + + // 下载/校验/替换期间：`Apply` 与 `CheckNow` 都不许派发。 + let before = seen.lock().unwrap_or_else(|p| p.into_inner()).len(); + app.state.update.applying = true; + let _ = app.on_update_action(UpdateAction::Apply); + let _ = app.on_update_action(UpdateAction::CheckNow); + assert_eq!( + seen.lock().unwrap_or_else(|p| p.into_inner()).len(), + before, + "applying 期间不许派发任何新的检查/安装" + ); + + // 应用结束：恢复可点。 + app.state.update.applying = false; + let _ = app.on_update_action(UpdateAction::Apply); + assert_eq!(last(&seen), AppCommand::ApplyUpdate, "失败/完成后恢回可点"); + } + + /// 截图通道不重启：取证进程不许把自己重启成死循环。 + #[test] + fn the_screenshot_channel_never_restarts() { + let (mut app, seen) = app(); + app.options.screenshot = Some(std::path::PathBuf::from("C:/Temp/shot.png")); + let _ = app.on_update_action(UpdateAction::RestartNow); + assert!( + seen.lock() + .unwrap_or_else(|poisoned| poisoned.into_inner()) + .is_empty(), + "重启不是一条后端指令（不该派发任何命令）" + ); + } +} diff --git a/crates/app-iced/src/app/view.rs b/crates/app-iced/src/app/view.rs new file mode 100644 index 0000000..b6858ed --- /dev/null +++ b/crates/app-iced/src/app/view.rs @@ -0,0 +1,282 @@ +//! `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; +pub(super) mod instances; +mod logs; +mod rail; +mod update; + +use instances::{detail_of, runtime_status_row, supporting_line}; +use logs::logs_model; +use update::update_of; + +/// 上一次记过的「设置页看到的组 + 主题」（`None` = 还没记过）。 +/// +/// 只给 [`note_screenshot_group`] 用：`view` 每帧都会跑，日志必须只在身份**变化**时落一行。 +/// 用 `Mutex` 而不是 `AtomicUsize` 位打包：主题是字符串（`ull-ink` / `ull-silver`）， +/// 把两件事挤进一个整数要引入「高半位 = 深色」这种与主题命名耦合的约定，不如老实用一对值。 +static SHOT_GROUP_LOGGED: std::sync::Mutex> = std::sync::Mutex::new(None); + +/// D30 §2.1 的「哪一行日志证明它是哪个组/主题」：出图通道专用的一行身份日志。 +/// +/// ## 为什么必须有 +/// +/// 举证图自带不了身份。M201 的事故就是 worker 交了一张「外观」页当下载组的证据，报告里的结论 +/// 建立在一个错的「这是哪个组」上，直到视觉 reviewer 自己重拍才发现。所以每张交付图都要能对上 +/// 一行日志：`[shot] settings route=Settings group=2 theme=ull-silver`。 +/// +/// ## 为什么只在变化时打 +/// +/// `App::view` 每帧都调用；每帧一行会把 `launcher.log` 刷满，反而没人能从中找到那一行。 +/// 判据是（组序号，主题名）这一对——同一次截图进程里最多两行（首帧 + 主题切一次）。 +/// +/// ## 为什么是 `try_lock` 而不是 `lock` +/// +/// 这里在 UI 线程的每帧路径上。`try_lock` 拿不到锁就**直接返回**（这一帧不打，下一帧还会再来， +/// 身份行只是晚一拍、不会丢），于是「界面帧永远不会被这把锁挡住」是**代码保证的**，不是靠 +/// 「今天只有一个调用点、锁里只有一次比较」这种会随改动失效的前提。M204 r1 复审把原先那句 +/// 「拿不到锁就不打」和当时用的阻塞 `lock()` 对上了：注释承诺的保证必须由代码提供。 +/// +/// **非截图通道一律不打**：交互模式下用户每点一次左列就多一行日志，没有价值。 +fn note_screenshot_group(screenshot: bool, route: &Route, group: usize, theme: &str) { + if !screenshot { + return; + } + let Ok(mut last) = SHOT_GROUP_LOGGED.try_lock() else { + return; + }; + let seen = (group, theme.to_string()); + if last.as_ref() == Some(&seen) { + return; + } + *last = Some(seen); + drop(last); + crate::app::diag::diag!("[shot] settings route={route:?} group={group} theme={theme}"); +} + +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(); + + // D30 §2.1：出图通道要有一行能**自证身份**的日志——「这张图是哪个设置组、哪个主题」。 + // 上一次 M201 的事故就是拿外观页当下载组的证据；图不自证身份，结论就无处落地。 + // 只对设置页打（左列那几组才有「哪个组」这件事）。 + if self.state.route() == &Route::Settings { + note_screenshot_group( + self.options.screenshot.is_some(), + self.state.route(), + self.appearance.selected_group, + self.ui().name(), + ); + } + + // `--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(); + // M187：页面树先立起来，再叠模态层（弹窗画在整窗之上，含标题栏区域）。 + let tree: Element<'_, Message> = 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, + // M201：下载组画真控件要的那份快照（`Model` 里那份，`refresh_view` 刚重建）。 + settings: &self.view.settings, + }, + // M106：设置页 General 组要画「当前档位 + 生效语言」。 + self.language(), + // M157：实例页「启动参数」区的表单（编辑态归 `App`，页面只借一帧）。 + &self.launch_form, + ) + .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(), + ), + }; + // 队列里有一条就叠一层模态（没有则原样返回）。模型由 `refresh_view` 维护。 + let tree = match self.dialog_model.as_ref() { + Some(modal) => super::dialog::view::layer(&self.ui, tree, modal), + None => tree, + }; + // M223：导入已有版本向导（实例页页头「导入」打开；没打开时原样返回页面树）。 + // 叠在模态**之上**：向导自己就是一层交互，模态只在崩溃/确认时出现，两者不会互相抢焦点。 + super::adopt::layer( + &self.ui, + tree, + &self.adopt_form, + &self.state.adopt, + self.lang(), + ) + } +} + +// --------------------------------------------------------------- 快照 → 视图模型 + +/// 把 presenter 的快照转成页面视图模型（**唯一**的展示转换点）。 +/// +/// `forced` 是 `--force-state` 的落点（P3-1）：它只影响**画出来的**状态层，不改任何状态机。 +/// +/// `width` 是**中栗可用宽度**（窗口 − 右栗 − 拖拽缝，由 `AgentUi::content_width` 算），不是窗口宽： +/// 页面布局系统仍按「一个窗口宽」扣左轨与页边距，所以右栗占掉的那一段必须在这里先减掉—— +/// 否则助手栏一展开，页面还按 1180 排版，内容就顶到面板底下了（任务里的「收缩而不是溢出」）。 +pub(super) fn model( + state: &AppState, + width: f32, + height: f32, + forced: Option, + 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 = 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_row(&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, + window_height: height, + 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), + // M224：详情页 MODS 区的列表 / 启停（presenter 的视图态 → 展示字段） + mods: instances::mods_of(state, catalog), + saves: instances::saves_of(state, catalog), + // M159：更新快照 → 页面视图（设置页「更新」区 + 顶部提示条都读它） + update: update_of(&state.update), + // M201：设置组快照（`SettingsChanged` 的回流结果）→ 页面视图。设置页的下载组从这里按 + // schema 键取当前值画控件；写回后 host 重新发 `SettingsChanged` ⇒ 下一次重建换新值。 + settings: state.settings_groups.clone(), + 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>, + overlay: Option>, + ) -> 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..4cc6fa5 --- /dev/null +++ b/crates/app-iced/src/app/view/instances.rs @@ -0,0 +1,283 @@ +//! 实例页的**展示转换**（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, Lang}; +use unlucky_presenter::dto::{ + InstanceRuntime, InstanceSummary, LaunchFailureCause, LaunchFailureStage, LaunchFinished, + LaunchStage, LoaderKind, LogOutcome, +}; +use unlucky_presenter::state::AppState; + +use crate::pages::{Detail, LaunchFacts, Meta, Mods, Saves}; + +/// 列表行的副文案：`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(crate) fn runtime_status(runtime: &InstanceRuntime, catalog: Catalog) -> Option { + 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())])) + } + // 失败有**两种形状**，各说各的话（复审 P1-1）： + // - `Stage`：进程**没起来** → 「哪一步 + 那一步的原文」（原文不翻译，是取证信息）； + // - `Crashed` / `SilentFailure`：**起来过** → 说结局（崩溃 / 疑似静默失败 + 退出码）， + // 绝不说成「启动游戏进程失败」。 + // + // 这一份是**详情页**用的全文（详情列会自动换行）；列表行那份是 [`runtime_status_row`] + // （单行、不许折行，见 D-M79-5）。 + InstanceRuntime::Failed { cause } => Some(failure_line(cause, catalog, true)), + } +} + +/// 一条失败状态行。 +/// +/// `with_detail = false` 是**列表行**那一档：`Stage` 只留「哪一步」，不带原文 +/// （原文可能是一长串路径，单行 overline 会把它裁成半截字）；结局类的两种形状本来就没有原文。 +fn failure_line(cause: &LaunchFailureCause, catalog: Catalog, with_detail: bool) -> String { + match cause { + LaunchFailureCause::Stage { stage, detail } if with_detail => catalog.render( + Key::LaunchStageFailed, + &[ + ("stage", failure_stage_label(*stage, catalog)), + ("detail", detail.as_str()), + ], + ), + LaunchFailureCause::Stage { stage, .. } => catalog.render( + Key::InstancesFailed, + &[("reason", failure_stage_label(*stage, catalog))], + ), + LaunchFailureCause::Crashed { exit_code } => { + let reason = match exit_code { + Some(code) => catalog.render(Key::InstancesCrashed, &[("code", &code.to_string())]), + // 平台没给退出码：只说「崩溃」，不编一个 0 出来。 + None => catalog.text(Key::LaunchOutcomeCrash).to_string(), + }; + catalog.render(Key::InstancesFailed, &[("reason", reason.as_str())]) + } + LaunchFailureCause::SilentFailure { .. } => { + // 静默失败的**关键信息是「exit 0 却没起来」**，不是退出码本身（复审 P1-1 第 ③ 条）。 + let reason = catalog.text(Key::InstancesSilentFailed).to_string(); + catalog.render(Key::InstancesFailed, &[("reason", reason.as_str())]) + } + } +} + +/// 列表行用的运行状态：**单行**（`ListItem` 的 overline 不折行，D-M79-5）。 +/// +/// 与 [`runtime_status`] 只差一处：失败时不带 `detail`——那一段是原始错误文本（可能是一长串 +/// 路径），放进 60/76 高的单行 overline 会被裁成半截字。全文在**详情页**（[`runtime_status`]）。 +pub(crate) fn runtime_status_row(runtime: &InstanceRuntime, catalog: Catalog) -> Option { + match runtime { + InstanceRuntime::Failed { cause } => Some(failure_line(cause, catalog, false)), + other => runtime_status(other, catalog), + } +} + +/// 失败阶段文案（presenter 给 slug，界面在这里选词）。 +/// +/// 与 [`stage_label`] 同一套做法：**不**复用 presenter 侧的任何中文常量。 +pub(crate) fn failure_stage_label(stage: LaunchFailureStage, catalog: Catalog) -> &'static str { + catalog.text(match stage { + LaunchFailureStage::VersionManifest => Key::LaunchStageVersionManifest, + LaunchFailureStage::Inheritance => Key::LaunchStageInheritance, + LaunchFailureStage::InstanceConfig => Key::LaunchStageInstanceConfig, + LaunchFailureStage::Isolation => Key::LaunchStageIsolation, + LaunchFailureStage::Identity => Key::LaunchStageIdentity, + LaunchFailureStage::Spawn => Key::LaunchStageSpawn, + }) +} + +/// 一次启动收尾的 Toast 文案（**唯一的产地**：presenter 只发结构，不拼句子）。 +/// +/// 三种结局各有各的说法：正常结束报时长，崩溃/静默失败报「结局 + 阶段 + 原文」， +/// 组装阶段就失败（`failure` 有值）报「哪一步 + 原文」。 +#[must_use] +pub(crate) fn launch_toast(finished: &LaunchFinished, lang: Lang) -> String { + let catalog = lang.catalog(); + if let Some(failure) = &finished.failure { + return catalog.render( + Key::LaunchStageFailed, + &[ + ("stage", failure_stage_label(failure.stage, catalog)), + ("detail", failure.detail.as_str()), + ], + ); + } + let outcome = catalog.text(match finished.outcome { + LogOutcome::Ok => Key::LaunchOutcomeNormal, + LogOutcome::Crashed => Key::LaunchOutcomeCrash, + LogOutcome::SilentFail => Key::LaunchOutcomeSilent, + }); + let seconds = format!("{:.1}", finished.uptime_ms as f64 / 1000.0); + catalog.render( + Key::LaunchToastEnded, + &[("outcome", outcome), ("seconds", seconds.as_str())], + ) +} + +/// 阶段文案：**不**复用 `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 { .. } + ), + // M157：启动参数区的**只读事实**（门槛 / 生效值 / 三态词表全部来自 presenter 快照， + // 页面不复制任何一条判据；表单值在 `App::launch_form`）。 + launch: LaunchFacts { + allowed: instance.launch.graphics_backend_allowed, + mc_version: instance.launch.mc_version.clone(), + min_version: instance.launch.graphics_backend_min_version.clone(), + memory_effective_mb: instance.launch.memory_effective_mb, + java_effective: instance.launch.java_effective.clone(), + backend_effective: instance.launch.graphics_backend_effective.clone(), + options: instance.launch.graphics_backend_options.clone(), + }, + } +} + +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(), + } +} + +/// 本地 Mod 的展示模型（M224）：presenter 的视图态 → 页面要画的东西。 +/// +/// 转换本体在 [`crate::pages::instances::mods`] 的 `from_state`（文案要用 `Texts`，那是页面层的 +/// 取词入口）——这里只把"当前语言"给过去，与 [`detail_of`] 同一条接法。 +pub(super) fn mods_of(state: &AppState, catalog: Catalog) -> Mods { + crate::pages::mods_from_state(&state.mods, catalog) +} + +/// 存档 / 截图的展示模型（M235）：presenter 的视图态 → 页面要画的东西。 +/// +/// 与 [`mods_of`] 同一条接法：转换本体在 `pages::instances::saves::from_state`（文案要用 +/// `Texts`），这里只把"当前语言"给过去。 +pub(super) fn saves_of(state: &AppState, catalog: Catalog) -> Saves { + crate::pages::saves_from_state(&state.saves, catalog) +} 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..4754aed --- /dev/null +++ b/crates/app-iced/src/app/view/logs/tests.rs @@ -0,0 +1,246 @@ +//! 日志页展示转换的守门测试（从 `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, + exit_code: Some(1), + uptime_ms: 3_000, + failure: None, + })); + + 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, + exit_code: Some(1), + uptime_ms: 3_000, + failure: None, + })); + 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..5d1a3bc --- /dev/null +++ b/crates/app-iced/src/app/view/tests.rs @@ -0,0 +1,310 @@ +//! `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; + +#[path = "tests/launch.rs"] +mod launch; + +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, + launch: unlucky_presenter::dto::LaunchArgsView::default(), + } +} + +/// **取证不变量（M100）**：`ForcedState` 的三档在产品路径上必须映射成「页面控件怎么画」。 +/// +/// 抓得住：① 谁把 `Rest` 映射成 Hovered/Pressed（那会让 `--screenshot` 的默认值反而画出状态层， +/// 与「取证密闭」正好相反，而且图看起来完全正常）；② 加了变体却映射到别的态这种复制粘贴错。 +/// 抓不住：`shell::overridden`（标题栏 / 导航轨按钮走的**另一处** match，断言在 `shell/tests.rs`）， +/// 也抓不住不消费 `model.forced` 的裸 `iced::button`（设置页「外观」区就是）。 +/// 测试用的薄包装：默认宽度 / 默认分类 / 空草稿 / **给定语言**。 +fn at_lang(state: &AppState, forced: Option, lang: Lang) -> pages::Model { + let draft = pages::InstallDraft::default(); + let page = pages::content::PageState::default(); + model( + state, + 1180.0, + 760.0, + forced, + pages::Category::All, + &draft, + lang, + &page, + ) +} + +/// 同 [`at_lang`]，语言取英文（绝大多数断言只关心「快照 → 模型」的映射，不关心译文）。 +fn at(state: &AppState, forced: Option) -> 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 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 { + 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/view/tests/launch.rs b/crates/app-iced/src/app/view/tests/launch.rs new file mode 100644 index 0000000..b1e62f8 --- /dev/null +++ b/crates/app-iced/src/app/view/tests/launch.rs @@ -0,0 +1,149 @@ +//! 启动失败/收尾的**文案**用例（从 `app/view/tests.rs` 拆出：那边 400 行到线）。 +//! +//! 这里的断言都钉**具体句子**（不是「字符串非空」）：磁贴与 Toast 必须说同一件事， +//! 「没起来」与「起来又崩」不许共用一句（M161 复审 P1-1）。 + +use super::*; + +/// 失败后磁贴要留「重试」，且行/详情文案按「哪一步 + 原文」给。 +#[test] +fn failed_instances_can_be_retried() { + // 进程**没起来**：说「哪一步 + 原文」。 + let failed = instance(InstanceRuntime::Failed { + cause: unlucky_presenter::dto::LaunchFailureCause::Stage { + stage: unlucky_presenter::dto::LaunchFailureStage::Spawn, + detail: "os error 5".to_string(), + }, + }); + // 列表行是**单行**：只放「哪一步」（原文太长会被 `Wrapping::None` 裁成半截字）。 + assert_eq!( + super::instances::runtime_status_row(&failed.runtime, Lang::En.catalog()).as_deref(), + Some("Launch failed · Starting the game process") + ); + // 详情页给全文（阶段 + 原文）。 + assert_eq!( + super::instances::runtime_status(&failed.runtime, Lang::En.catalog()).as_deref(), + Some("Launch failed · Starting the game process: os error 5") + ); + assert!( + detail_of(&failed, Lang::En.catalog()).can_launch, + "失败后要能重试" + ); +} + +/// **「没起来」与「起来又崩」不许说成同一句**（复审 P1-1 的文案面）。 +/// +/// 抓得住：崩溃/静默失败被塞回 `LaunchFailureStage::Spawn`（磁贴会写「启动游戏进程失败」， +/// 而进程明明起来了）；退出码漏成 `Some(1)` 这种 Debug 文本；静默失败丢掉 +/// 「exit 0 却没跑起来」这条信息。断言的是**具体句子**，不是「字符串非空」。 +#[test] +fn a_crash_after_start_is_not_worded_as_a_start_failure() { + use unlucky_presenter::dto::{LaunchFailureCause, LaunchFailureStage}; + + let line = |cause: LaunchFailureCause, lang: Lang| { + let runtime = InstanceRuntime::Failed { cause }; + let row = super::instances::runtime_status_row(&runtime, lang.catalog()).expect("行文案"); + let detail = super::instances::runtime_status(&runtime, lang.catalog()).expect("详情文案"); + (row, detail) + }; + + // ① 没起来：说阶段。 + let (row, detail) = line( + LaunchFailureCause::Stage { + stage: LaunchFailureStage::Spawn, + detail: "os error 5".to_string(), + }, + Lang::En, + ); + assert_eq!(row, "Launch failed · Starting the game process"); + assert_eq!( + detail, + "Launch failed · Starting the game process: os error 5" + ); + + // ② 起来又崩：说结局 + 数字退出码（不许出现 `Some(1)`）。 + let (row, detail) = line(LaunchFailureCause::Crashed { exit_code: Some(1) }, Lang::En); + assert_eq!(row, "Launch failed · the game crashed (exit 1)"); + assert_eq!(detail, row, "结局类没有「原文」可加，行与详情同一句"); + assert!(!detail.contains("Some("), "退出码不许漏 Debug：{detail}"); + assert!( + !detail.contains("Starting the game process"), + "进程起来了，不许说「启动游戏进程」：{detail}" + ); + + // ③ 静默失败：exit 0 却没跑起来 —— 这条信息不能丢。 + let (row, zh) = line( + LaunchFailureCause::SilentFailure { exit_code: Some(0) }, + Lang::ZhCn, + ); + assert_eq!(row, "启动失败 · 退出码 0，没起来"); + assert_eq!(zh, row); + assert!(row.contains("没起来"), "{row}"); + + // ④ 平台没给退出码：只说崩溃，不编一个 0 出来。 + let (row, _) = line(LaunchFailureCause::Crashed { exit_code: None }, Lang::En); + assert_eq!(row, "Launch failed · The game crashed"); +} + +/// +/// 此前 `LaunchFinished.summary` 是 presenter 拼的中文，英文界面上弹的就是中文； +/// 现在 presenter 只给结构（结局 + 退出码 + 失败阶段），文案在这里按 key 现求。 +/// +/// 抓得住：①谁把中文串再写回 presenter（英文那一行会露中文）；②失败时丢掉 `detail` +/// （原文是取证信息，不许翻也不许删）；③「跑起来再崩」被说成「启动失败在某一步」。 +#[test] +fn the_launch_toast_speaks_the_interface_language() { + use unlucky_presenter::dto::{ + LaunchFailureStage, LaunchFailureView, LaunchFinished, LogOutcome, + }; + + let finished = |outcome, failure| LaunchFinished { + id: "survival".to_string(), + session: "20261031T120000-abcd12".to_string(), + outcome, + exit_code: Some(1), + uptime_ms: 12_500, + failure, + }; + + // 正常结束：只报结局 + 时长（`正常结束 · 12.5 秒` / `Finished normally · 12.5s`）。 + let ok = finished(LogOutcome::Ok, None); + let en = super::instances::launch_toast(&ok, Lang::En); + let zh = super::instances::launch_toast(&ok, Lang::ZhCn); + assert_eq!(en, "Finished normally · 12.5s"); + assert_eq!(zh, "正常结束 · 12.5 秒"); + assert_ne!(en, zh, "切语言时提示语要变"); + + // 装配阶段失败：说清**哪一步**，并把原文原样带出来。 + let failed = finished( + LogOutcome::Crashed, + Some(LaunchFailureView::new( + LaunchFailureStage::InstanceConfig, + "permission denied (os error 5)", + )), + ); + let en = super::instances::launch_toast(&failed, Lang::En); + let zh = super::instances::launch_toast(&failed, Lang::ZhCn); + assert!( + en.starts_with("Launch failed · Reading the instance settings"), + "{en}" + ); + assert!(zh.starts_with("启动失败 · 读实例设置"), "{zh}"); + for text in [&en, &zh] { + assert!( + text.contains("permission denied (os error 5)"), + "原文（取证信息）不许丢：{text}" + ); + } + // 英文界面里不许出现中文（反之亦然）——这条是本次债的核心。 + assert!(!en.chars().any(is_cjk), "英文提示里混了中文：{en}"); + assert!( + !zh.contains("Launch failed"), + "中文提示里混了英文前缀：{zh}" + ); +} + +/// 有没有中文字符（上面那条「不许混语言」的判据）。 +fn is_cjk(ch: char) -> bool { + ('\u{4e00}'..='\u{9fff}').contains(&ch) +} diff --git a/crates/app-iced/src/app/view/update.rs b/crates/app-iced/src/app/view/update.rs new file mode 100644 index 0000000..ce179dd --- /dev/null +++ b/crates/app-iced/src/app/view/update.rs @@ -0,0 +1,157 @@ +//! presenter 的更新快照 → 页面视图模型（M159 的**唯一**展示转换点）。 +//! +//! 与 `view/instances.rs` 同一条分工：判断（要不要提示、是不是失败）在 presenter / core 已经做完， +//! 这里只把字段摆成「要画什么」。三条映射必须与 DTO 的判据保持一致： +//! +//! | DTO | 页面视图 | +//! |---|---| +//! | `UpdateOutcome::UpToDate` | [`UpdateStatus::UpToDate`]（**不是**失败） | +//! | `UpdateOutcome::Failed` | [`UpdateStatus::Failed`]（带原因，**不许**画成「已是最新」） | +//! | `UpdateOutcome::MissingArtifact` | [`UpdateStatus::MissingArtifact`]（发布侧漏项，单独一句话） | + +use unlucky_presenter::dto::{UpdateOutcome, UpdateView}; + +use crate::pages::{Update, UpdateStatus}; + +/// 快照 → 视图模型。 +pub(super) fn update_of(view: &UpdateView) -> Update { + Update { + current_version: view.current_version.clone(), + channel: view.channel.clone(), + auto_check: view.auto_check, + status: status_of(&view.outcome), + checked_at: view.checked_at.clone(), + applying: view.applying, + ready: view.ready.as_ref().map(|ready| ready.version.clone()), + skipped: view.skipped.clone(), + silent: view.silent, + } +} + +/// 结论 → 页面状态（四种结论一一对应，**不折叠**）。 +fn status_of(outcome: &UpdateOutcome) -> UpdateStatus { + match outcome { + UpdateOutcome::Idle => UpdateStatus::Idle, + UpdateOutcome::Checking => UpdateStatus::Checking, + UpdateOutcome::UpToDate { latest } => UpdateStatus::UpToDate { + latest: latest.clone(), + }, + UpdateOutcome::Available(candidate) => UpdateStatus::Available { + version: candidate.version.clone(), + size: candidate.size, + notes: candidate.notes.clone(), + forced: candidate.forced, + }, + UpdateOutcome::MissingArtifact { version } => UpdateStatus::MissingArtifact { + version: version.clone(), + }, + UpdateOutcome::Failed(failure) => UpdateStatus::Failed { + reason: failure.message.clone(), + retryable: failure.retryable, + }, + } +} + +#[cfg(test)] +mod tests { + use super::*; + use unlucky_presenter::dto::{ReadyUpdate, UpdateFailureView}; + + fn view(outcome: UpdateOutcome) -> UpdateView { + let mut view = UpdateView::new("0.2.2", "stable", true); + view.outcome = outcome; + view + } + + #[test] + fn failure_is_never_mapped_to_up_to_date() { + let mapped = update_of(&view(UpdateOutcome::Failed(UpdateFailureView::new( + "network", + "取更新清单失败：连接被重置", + true, + )))); + assert!( + matches!(&mapped.status, UpdateStatus::Failed { reason, retryable } if *retryable && !reason.is_empty()), + "失败必须原样带原因，实际 {:?}", + mapped.status + ); + assert!(mapped.banner().is_some(), "主动查出来的失败要弹提示条"); + + // 静默检查的失败：快照里仍是失败，但不弹条（离线是常态）。 + let mut silent = view(UpdateOutcome::Failed(UpdateFailureView::new( + "network", + "连不上", + true, + ))); + silent.silent = true; + let mapped = update_of(&silent); + assert!(matches!(mapped.status, UpdateStatus::Failed { .. })); + assert!(mapped.banner().is_none()); + } + + #[test] + fn the_four_outcomes_stay_distinct() { + let available = update_of(&view(UpdateOutcome::Available(Box::new( + unlucky_presenter::dto::UpdateCandidateView { + version: "0.2.3".to_string(), + size: 21_000_000, + notes: "修掉启动崩溃".to_string(), + forced: false, + }, + )))); + assert!(available.available().is_some()); + assert!(matches!( + available.banner(), + Some(crate::pages::Banner::Available { .. }) + )); + + let up_to_date = update_of(&view(UpdateOutcome::UpToDate { + latest: Some("0.2.2".to_string()), + })); + assert!(matches!(up_to_date.status, UpdateStatus::UpToDate { .. })); + assert!(up_to_date.banner().is_none()); + + let missing = update_of(&view(UpdateOutcome::MissingArtifact { + version: "0.2.3".to_string(), + })); + assert!(matches!( + missing.status, + UpdateStatus::MissingArtifact { .. } + )); + } + + #[test] + fn a_ready_update_turns_the_banner_into_the_restart_prompt() { + let mut view = view(UpdateOutcome::UpToDate { + latest: Some("0.2.3".to_string()), + }); + view.ready = Some(ReadyUpdate { + version: "0.2.3".to_string(), + path: "C:/ULL/unlucky-launcher.exe".to_string(), + backup: None, + }); + let mapped = update_of(&view); + assert_eq!(mapped.ready.as_deref(), Some("0.2.3")); + assert!(matches!( + mapped.banner(), + Some(crate::pages::Banner::Ready { .. }) + )); + } + + #[test] + fn a_skipped_update_keeps_the_snapshot_but_hides_the_banner() { + let mut view = view(UpdateOutcome::Available(Box::new( + unlucky_presenter::dto::UpdateCandidateView { + version: "0.2.3".to_string(), + size: 1, + notes: String::new(), + forced: false, + }, + ))); + view.skipped = Some("0.2.3".to_string()); + let mapped = update_of(&view); + assert_eq!(mapped.skipped.as_deref(), Some("0.2.3")); + assert!(mapped.available().is_some(), "候选要留着给设置页"); + assert!(mapped.banner().is_none()); + } +} 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..7ece895 --- /dev/null +++ b/crates/app-iced/src/app/window_alpha.rs @@ -0,0 +1,147 @@ +//! 整窗 α 的**执行侧**：句柄探测 → `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 { + // 只有 `RawWindowHandle::Win32` 那条臂用到它，其余平台只剩 `_ => None` + // ⇒ 无条件导入在非 Windows 上是 `unused_imports`（M147）。 + #[cfg(target_os = "windows")] + 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) -> 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"); + // 「做不到」的语义随平台不同（M147 实证：这条断言原先按 Windows 写死，Ubuntu 上 + // 622 passed / 1 failed）：Windows 上 FFI 真被调用并失败 ⇒ `Failed`；非 Windows 走 + // `transparency.rs` 的空实现 ⇒ `Unsupported`。两边都不许表现成 `Applied` / `Opaque`。 + #[cfg(target_os = "windows")] + assert!( + matches!(invalid.alpha, AlphaOutcome::Failed { .. }), + "{:?}", + invalid.alpha + ); + #[cfg(not(target_os = "windows"))] + assert_eq!( + invalid.alpha, + AlphaOutcome::Unsupported, + "非 Windows 的空实现必须如实说「这个平台不支持」，不许冒充成功" + ); + } + + /// 本机真窗口的取证由 `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, + /// 截图通道：给了路径就出图后退出。 + pub screenshot: Option, + /// `--screenshot-theme`（优先级高于 `--theme`）。 + pub screenshot_theme: Option, + /// 强制窗口缩放因子（验收要 100% DPI，即 `1`；`None` = 用系统 DPI）。 + pub scale_factor: Option, + /// `--diff ` 与 `--diff-scan `：逐像素对比（不开窗）与 ±n px 平移扫描。 + pub diff: Option<(PathBuf, PathBuf)>, + /// 见上（默认 0 = 不扫）。 + pub diff_scan: u32, + /// `--force-state=hover|pressed`：把按钮强制成某个状态便于截图取证（D30 的状态图）。 + pub force_state: Option, + /// `--screen=shell|gallery`：启动画面（`gallery` = 组件库视觉验收 harness）。 + pub screen: Screen, + /// `--data-dir `：当前**接受并忽略**（现役 Slint 版 CI 冒烟在用； + /// 真正的消费由后续页面 mission 接 `host`/`state` 时做）。 + pub data_dir: Option, +} + +/// 截图取证用的强制交互状态（只影响观感，不改变任何状态机）。 +/// +/// 五态完整矩阵由 `--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::parse(std::env::args().skip(1)) + } + + /// 从任意参数序列解析（`argv[1..]`，测试直接喂数组）。 + /// + /// # Errors + /// 同 [`Options::from_env`]。 + pub fn parse(args: impl IntoIterator) -> Result { + 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 { + self.screenshot_theme.or(self.theme) + } + + /// 本次进程真正要画的主题（**唯一取值口**）。 + /// + /// 截图模式（给了 `--screenshot`）**永远返回 `Some`**：`--screenshot-theme` > `--theme` > Light。 + /// 交互模式只有显式指定才有值（`None` = 等系统主题）。 + /// + /// ⚠️ **门禁依赖，不许把截图分支改回 `None`**：CI 的 runtime-smoke 打 + /// `--software-renderer --screenshot --data-dir `（不带主题），xvfb 里没有桌面主题 + /// 会话，M68 的「等系统主题到达再出图」闸门在这条路径上会把 runner 挂到超时（不是红，更难查）。 + pub fn capture_flavor(&self) -> Option { + 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, + inline: Option, + flag: &str, +) -> Result { + inline + .or_else(|| args.next()) + .ok_or_else(|| format!("{flag} 需要一个值")) +} + +fn flavor(raw: &str) -> Result { + 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::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 --data-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..411b902 --- /dev/null +++ b/crates/app-iced/src/components/buttons/assemble.rs @@ -0,0 +1,263 @@ +//! 装配与样式：五式共用的一条产线（尺寸 / 内边距 / 图标盒 / 状态层 / 描边）。 +//! +//! 单独成文件的原因：`mod.rs` 已经是「对外契约 + 变体角色表」，把绘制细节放一起会顶到 400 行红线； +//! 而且这条产线是**唯一**会把「令牌 → 像素」翻一次的地方，独立出来才好审。 +//! +//! 禁用态的合成底（[`Base`]，M234）也从这里往下传：`Button::base(..)` → [`StyleSpec::base`] → +//! `disabled_button_colors` / `disabled_button_content`。装配侧没有第二个猜底色的地方。 + +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 crate::icons; +use crate::theme::Ui; + +use super::super::interaction::{self, Base, Interaction}; +use super::super::layout; +use super::{Button, Geometry, Variant}; + +/// 一个按钮样式要的全部输入（避免 `style_closure` 长出七个位置参数）。 +#[derive(Debug, Clone, Copy)] +pub(crate) struct StyleSpec { + /// 容器填充角色；`None` = 透明（Outlined / Text / StandardIcon）。 + pub fill: Option, + /// 内容（文字 + 图标）角色。 + pub content: Role, + /// 描边角色；`None` = 无描边。 + pub border: Option, + /// 圆角档位（来自组件表，五式统一 `Full`）。 + pub shape: ShapeScale, + /// 描边宽度（`Geometry::stroke`：有描边的变体 = `stroke::HAIRLINE`，其余 0）。 + pub stroke: f32, + /// 圆角折算用的边长（药丸 = 可见高）。 + pub radius_side: f32, + /// **脚下那一层的底**（M234）：禁用态的 10% 容器与 38% 内容都叠在它上面。 + /// + /// 由构造点给（卡片 = `surfaces::elevated::BASE`、菜单项 = `inputs::menu::PANEL_BASE`、 + /// 直接摆在画布上 = [`Base::CANVAS`]）。M229 之前这里恒为 `Role::Surface`， + /// 卡片里的禁用按钮因此把 10% 叠在画布色上（M223 的「形丢失」）。 + pub base: Base, + /// 强制态（gallery 取证）；`None` = 跟随运行期的 `button::Status`。 + /// + /// **`Some(Enabled)` 与 `None` 不是一回事**：截图取证必须能强制「静息」，否则光标恰好停在 + /// 某个按钮上时那一格会被画成 hover（实测踩过：text 行 enabled 列出现不该有的灰底容器， + /// 看起来像 Text 按钮自带容器）。 + pub forced: Option, +} + +/// 五式共用的装配：**只画一处**，五个变体函数都走这里。 +pub(super) fn assemble<'a, M: Clone + 'a>( + ui: &'a Ui, + variant: Variant, + spec: Button<'a, M>, +) -> Element<'a, M> { + let geometry = Geometry::sized(ui, variant, spec.leading.is_some(), spec.size); + let (fill, content, _border) = variant.roles(); + let forced = spec.forced(); + + // 按钮家族没有浮层级高程：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, + spec.base, + forced, + content, + fill, + variant.disabled_content(), + ); + + // 标签排版跟尺寸档走：`ControlSize::label()` 已把「字号跟字级、字重固定 500」定死 + // （XS/S = LabelLarge 14、M = BodyLarge 16、L = HeadlineSmall 24、XL = HeadlineLarge 32）。 + let label_style = geometry.size.label(); + let label = text(spec.label) + .size(label_style.size_px) + .line_height(LineHeight::Absolute(Pixels(label_style.line_height_px))) + .font(ui.font_of(label_style)) + .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::(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::(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, text_style_spec(ui, variant, &spec)); + + 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(), + } +} + +/// `Button` → 样式描述：**装配的唯一接线点**（`assemble` 与单测都走这里）。 +/// +/// 抽出来的理由与 [`super::icon_style_spec`] 同源：`button::Style` 是闭包、`Element` 是黑盒， +/// 两者都不可内省，所以「禁用态的底到底传了哪一个」只能在**结构体**上断言。 +/// 写死一个 `StyleSpec` 再喂给 `style_closure` 的测试证明不了接线（M229 复审 P1-1 踩过）。 +pub(super) fn text_style_spec(ui: &Ui, variant: Variant, spec: &Button<'_, M>) -> StyleSpec { + let (fill, content, border) = variant.roles(); + let geometry = Geometry::sized(ui, variant, spec.leading.is_some(), spec.size); + StyleSpec { + fill, + content, + border, + shape: variant.shape(), + stroke: geometry.stroke, + radius_side: geometry.height, + base: spec.base, + forced: spec.forced(), + } +} + +/// 内容色（文字与图标共用）：禁用态走令牌的 38%，其余态就是角色色。 +/// +/// 单独成函数是为了让「内容色跟态走」这件事只有一处实现——`assemble`（文字按钮）与 `icon` +/// （图标按钮）都调它，两条路径不会再各自钉死满档色。 +/// 内容色：**禁用时的角色由调用方按变体给**（[`super::Variant::disabled_content`] / +/// [`super::IconVariant::disabled_content`]）——A1 里 FilledTonal 与 IconButton 是 `OnSurface`， +/// 其余是 `OnSurfaceVariant`，不能在这里统一写死。 +pub(super) fn content_color( + ui: &Ui, + base: Base, + forced: Option, + content: Role, + fill: Option, + disabled_content: Role, +) -> iced::Color { + match forced { + // 有容器：38% 叠在**按钮家族 10% 容器**上（Filled / Tonal / Elevated），容器再叠在 `base` 上 + Some(Interaction::Disabled) if fill.is_some() => { + interaction::disabled_button_content(ui, base, disabled_content, true) + } + // 无容器：38% 直接叠在 **base** 上（Text / Outlined / standard IconButton） + Some(Interaction::Disabled) => { + interaction::disabled_button_content(ui, base, 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 disabled = state + .is_disabled() + .then(|| interaction::disabled_button_colors(ui, spec.base)); + + let (background, text_color) = match disabled { + Some((container, content)) => { + // 透明容器在禁用态依然透明（官方只改内容透明度） + (spec.fill.map(|_| container), content) + } + None => { + // 有填充：状态层叠在**容器角色**上；透明容器：叠在表面色上（否则 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, spec.base, state, spec.content), + }; + (background, ui.color(spec.content)) + } + }; + + let border_color = match disabled { + Some((container, _content)) => container, + None => 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` 没有填充，可见反馈只能来自 +/// 叠在**内容角色**上的状态层——把它们当作「叠在 `base`（脚下那一层）上」求值，得到不透明实色。 +/// +/// 之所以单独一个函数：这是 M3 里唯一「容器不存在但状态层存在」的情形， +/// 三个变体共用一条口径，免得各自发挥。 +/// +/// M234 复审 P2-3：`base` 之前写死 `Role::Surface`，卡片里的 Text/Outlined 按钮抬起时 +/// 状态层叠在画布色上（与禁用支的口径不一致）。 +pub(super) fn transparent_state_color( + ui: &Ui, + base: Base, + state: Interaction, + content: Role, +) -> Option { + interaction::overlay_color(ui, state, content, base.role()) +} diff --git a/crates/app-iced/src/components/buttons/fab.rs b/crates/app-iced/src/components/buttons/fab.rs new file mode 100644 index 0000000..4bf5d8d --- /dev/null +++ b/crates/app-iced/src/components/buttons/fab.rs @@ -0,0 +1,227 @@ +//! FAB 四态（规格卡 `FAB / SMALL - DEFAULT - MEDIUM - EXTENDED`）。 +//! +//! ## 规格卡原值（`[spec]` = 图上的坐标/字号，几何全部来自 [`FabSize`] 的令牌访问器） +//! +//! | 档 | 尺寸 | 圆角 | 图标 | 标签 | 规格卡依据 | +//! |---|---|---|---|---|---| +//! | Small | 40×40 | 12（`Medium`） | 20 | — | `+` 徽章式小 FAB | +//! | Default | 56×56 | 16（`Large`） | 26 | — | M3 默认 FAB | +//! | Medium | 80×80 | 20（`LargeIncreased`） | 34 | — | 中大档 | +//! | Extended | 160×56（最小宽） | 16（`Large`） | 24 | 15 | `+ New`：起始内距 28、图标↔标签 8 | +//! +//! ## 配色：`PrimaryContainer` / `OnPrimaryContainer` +//! +//! 规格卡上四颗 FAB 都是**淡绿底 + 深绿字形**，M3 的对应角色正是 `primary-container` / +//! `on-primary-container`（`boards/ink.rs` 的 `[spec]` 行注释也这么标：`FAB 底` / `FAB 图标`）。 +//! 所以这里不引入新角色，也不画阴影——规格卡上是纯色块，M3 的 FAB 高程由容器色表达。 +//! +//! 色值不写在这份文档里：`tests/no_hardcoded_tokens.rs` 会扫 `src/**` 的十六进制色值， +//! 要核对数字请看 `boards/ink.rs` 的 `ANCHORS` 表（那是唯一真源）。 +//! +//! ## 为什么单独一个文件 +//! +//! 按钮家族（五式 × 五态 × 五档）已经在 `buttons/mod.rs` + `assemble.rs` 里贴着 400 行；FAB 的 +//! 几何与按钮**不共享**（圆角不是半高、图标随档放大、扩展态有自己的内距），硬塞进去只会让两边 +//! 的读取路径都变长。共享的只有 `interaction` 的状态层与图标烘焙工具。 + +use iced::widget::{button, container, row, text}; +use iced::{Alignment, Background, Border, Element, Length, Padding, Shadow}; + +use unlucky_design::color::Role; +use unlucky_design::icons::IconKind; +use unlucky_design::inkcat::size::FabSize; +use unlucky_design::typography::{TypeRole, TypeStyle, Weight}; + +use crate::icons; +use crate::theme::Ui; + +use super::super::interaction::{self, Base, Interaction}; +use super::super::layout; + +/// 扩展态右侧内距（px）。规格卡只量到起始 28（`FabSize::pad_start_px`），右侧没有量； +/// 取同值 **28** 让「图标 + 标签」在 160 宽里左右对称（`[估]`，与起始同源的唯一对称解）。 +pub const EXTENDED_PAD_END: f32 = 28.0; + +/// 一颗 FAB：图标必有，标签只有扩展态有；`on_press = None` 即禁用。 +#[derive(Debug, Clone)] +pub struct Fab<'a, M> { + icon: IconKind, + label: Option<&'a str>, + size: FabSize, + on_press: Option, + state: Option, +} + +impl<'a, M> Fab<'a, M> { + /// 标准 FAB（默认档 = 56）。 + pub fn new(icon: IconKind, on_press: M) -> Self { + Self { + icon, + label: None, + size: FabSize::Default, + on_press: Some(on_press), + state: None, + } + } + + /// 扩展态（药丸 + 图标 + 标签）。`label` 文案由调用方给（组件不碰 i18n）。 + pub fn extended(icon: IconKind, label: &'a str, on_press: M) -> Self { + Self { + label: Some(label), + size: FabSize::Extended, + ..Self::new(icon, on_press) + } + } + + /// 换档（Small / Default / Medium / Extended）。 + pub fn size(mut self, size: FabSize) -> Self { + self.size = size; + self + } + + /// 强制视觉态（gallery 取证用；运行期不要调）。 + pub fn state(mut self, state: Interaction) -> Self { + self.state = Some(state); + self + } +} + +/// 禁用态的内容色：`OnPrimaryContainer` @38% 叠在 **FAB 自己的容器**（`PrimaryContainer`）上。 +/// +/// ## 为什么底是 FAB 自己的容器，不是画布（M234 复审 P2-2） +/// +/// 五式按钮的禁用容器是「`OnSurface`@10% 叠在脚下那一层」——透明的那种甚至没有容器；所以它们的 +/// 内容要叠 `0.10 容器 → 父底`。FAB 不一样：`Interaction::Disabled.layer()` 是 `None`， +/// 样式闭包走 `None => Some(ui.color(Role::PrimaryContainer))`，**禁用时背景仍是满档 +/// `PrimaryContainer`**（官方 `FloatingActionButtonTokens` 也没有 DisabledContainerOpacity）。 +/// 所以内容只能叠 `PrimaryContainer` 本身，`on_container = false`——那一层 10% 在 FAB 身上 +/// 根本不存在，给了反而多算一层灰。 +/// +/// 修前传 `Base::CANVAS`：38% 的 `OnPrimaryContainer` 合在画布色上，出来是一块与 FAB 底无关的灰 +/// （Silver 浅色实测是一块灰 `rgb(0.549,0.627,0.667)`），而不是「深色字压在淡蓝容器上」 +/// 的应有结果（同板上正确值是 `rgb(0.329,0.561,0.737)`；数字见 artifacts/m234 的 README）。 +/// +/// `button()` 与样式闭包**共用这一个函数**：早先两处各写一遍，两次都传了同一个错值。 +fn content_color(ui: &Ui, forced: Option) -> iced::Color { + match forced { + Some(Interaction::Disabled) => interaction::disabled_button_content( + ui, + Base::of(Role::PrimaryContainer), + Role::OnPrimaryContainer, + false, + ), + _ => ui.color(Role::OnPrimaryContainer), + } +} + +/// 画一颗 FAB。 +pub fn fab<'a, M: Clone + 'a>(ui: &'a Ui, spec: Fab<'a, M>) -> Element<'a, M> { + let size = spec.size; + let forced = spec.state.or(if spec.on_press.is_none() { + Some(Interaction::Disabled) + } else { + None + }); + // 内容色（含禁用档）只走 `content_color` 一处 + let ink = content_color(ui, forced); + + let glyph = layout::fixed( + size.icon_px(), + size.icon_px(), + icons::view_at::(spec.icon, ink, size.icon_px()), + ); + + let content: Element<'a, M> = match spec.label { + // 扩展态：图标 + 标签（起始内距 28、间距 8，规格卡实测值） + Some(label) => { + let label_style = TypeStyle { + weight: Weight::Medium, + ..TypeRole::BodyMedium.style() + }; + let label_px = size.label_px(); + row![ + glyph, + text(label) + .size(label_px) + .font(ui.font_of(TypeStyle { + size_px: label_px, + ..label_style + })) + .color(ink), + ] + .spacing(size.gap_px()) + .align_y(Alignment::Center) + .padding(Padding { + top: 0.0, + right: EXTENDED_PAD_END, + bottom: 0.0, + left: size.pad_start_px(), + }) + .into() + } + None => container(glyph) + .width(Length::Fill) + .height(Length::Fill) + .align_x(Alignment::Center) + .align_y(Alignment::Center) + .into(), + }; + + let shape = size.shape(); + let radius = size.radius_px(); + let style = move |_theme: &iced::Theme, status: button::Status| { + let state = forced.unwrap_or_else(|| Interaction::from_status(status)); + let background = match state.layer() { + // 状态层叠在容器色上（与按钮族同一条 `overlay_color` 口径） + Some(_) => interaction::overlay_color( + ui, + state, + Role::OnPrimaryContainer, + Role::PrimaryContainer, + ) + .or(Some(ui.color(Role::PrimaryContainer))), + None => Some(ui.color(Role::PrimaryContainer)), + }; + let text_color = content_color(ui, Some(state)); + + button::Style { + background: background.map(Background::Color), + text_color, + border: Border { + radius: iced::border::Radius::new(radius), + ..Border::default() + }, + // 规格卡不画阴影；M3 的 FAB 高程靠容器色（rubric §7 的「L0/L1 不用阴影」同源） + shadow: Shadow::default(), + snap: true, + } + }; + + // 四档的宽都由令牌给（方态是边长、扩展态是**最小**宽 160）。 + // + // ⚠️ iced 0.14 的 `Length` 只有 `Fill/FillPortion/Shrink/Fixed`，**没有 Min**（本仓 G15 / G17-d + // 已登记同一堵墙），所以「最小宽随标签撑开」在这里退化成**固定宽**：标签比 160 内距容得下的 + // 更长时会被裁，短时也不会缩。登记为偏离（见 `FabSize::width_px` 的文档）；真要 Min 语义得等 + // iced 给 `Length::Min`，或在组件里先量文本再算宽——那要引字体度量，不在本轮。 + let width = Length::Fixed(size.width_px()); + + let element = button(content) + .width(width) + .height(Length::Fixed(size.height_px())) + .padding(Padding::default()) + .style(style); + + debug_assert!(radius > 0.0, "FAB 圆角必须来自 ShapeScale（{shape:?}）"); + debug_assert!( + matches!(size, FabSize::Extended) || size.pad_start_px() == 0.0, + "只有扩展态有起始内距" + ); + + match spec.on_press { + Some(message) => element.on_press(message).into(), + None => element.into(), + } +} + +#[cfg(test)] +mod tests; diff --git a/crates/app-iced/src/components/buttons/fab/tests.rs b/crates/app-iced/src/components/buttons/fab/tests.rs new file mode 100644 index 0000000..717c74f --- /dev/null +++ b/crates/app-iced/src/components/buttons/fab/tests.rs @@ -0,0 +1,115 @@ +//! FAB 的几何断言（四档尺寸/圆角/图标/内距，全部对着规格卡原值）。 +//! +//! 抓得住：档位与规格卡错位（例如把 Default 写成 48）、圆角被写成半高、扩展态内距悄悄改成 M3 的 16。 +//! 抓不住：图上好不好看（D30），以及 hover/pressed 的状态层（那走 `interaction` 的既有测试）。 +//! +//! 配色只钉**一条**（禁用内容色，M234 复审 P2-2）：FAB 没有禁用容器档，所以 38% 必须合在 +//! 自己的 `PrimaryContainer` 上，而不是画布色。其余配色仍由 `interaction` 的测试覆盖。 + +use unlucky_design::color::{Role, SchemeFlavor}; +use unlucky_design::inkcat::size::FabSize; +use unlucky_design::typography::Platform; + +use super::super::super::interaction::Interaction; +use crate::theme::{to_iced, Families, Ui}; + +fn ui(flavor: SchemeFlavor) -> Ui { + Ui::with_platform( + flavor, + Platform::Windows, + Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", + }, + ) +} + +#[test] +fn the_four_states_are_the_spec_sizes() { + for (size, width, height, radius) in [ + (FabSize::Small, 40.0, 40.0, 12.0), + (FabSize::Default, 56.0, 56.0, 16.0), + (FabSize::Medium, 80.0, 80.0, 20.0), + (FabSize::Extended, 160.0, 56.0, 16.0), + ] { + assert_eq!(size.width_px(), width, "{size:?} 宽"); + assert_eq!(size.height_px(), height, "{size:?} 高"); + assert_eq!(size.radius_px(), radius, "{size:?} 圆角"); + } + assert_eq!(FabSize::ALL.len(), 4); +} + +#[test] +fn only_the_extended_state_carries_a_label_and_its_inset() { + for size in [FabSize::Small, FabSize::Default, FabSize::Medium] { + assert_eq!(size.label_px(), 0.0, "{size:?} 不该有标签"); + assert_eq!(size.pad_start_px(), 0.0); + } + assert_eq!(FabSize::Extended.label_px(), 15.0); + assert_eq!(FabSize::Extended.pad_start_px(), 28.0); + assert_eq!(FabSize::Extended.gap_px(), 8.0); +} + +/// 图标随档放大（20 / 26 / 34），扩展态回到 24（它与标签同行，跟着文字尺度走）。 +#[test] +fn the_glyph_grows_with_the_smaller_states() { + assert!(FabSize::Small.icon_px() < FabSize::Default.icon_px()); + assert!(FabSize::Default.icon_px() < FabSize::Medium.icon_px()); + assert_eq!(FabSize::Extended.icon_px(), 24.0); +} + +/// 扩展态右内距是常量（不是散在 `Padding` 里的字面量 28），且与起始内距对称。 +#[test] +fn the_extended_pad_end_is_a_named_constant() { + use super::super::fab::EXTENDED_PAD_END; + use unlucky_design::inkcat::size::FabSize; + + assert_eq!(EXTENDED_PAD_END, 28.0); + assert_eq!( + EXTENDED_PAD_END, + FabSize::Extended.pad_start_px(), + "左右对称：规格卡只量到起始 28，右侧取同值" + ); +} + +/// **M234 复审 P2-2 的判据**：禁用 FAB 的内容色必须合在**自己的容器**上。 +/// +/// 走的是真实现（`fab::content_color`，`button()` 与样式闭包共用它）。抓得住：底又改回画布 +/// （那就是修前那块与 FAB 底无关的灰）、或有人把 `on_container` 打开（会多算一层 +/// 10% 的 `OnSurface` 灰）。抓不住：容器本身该不该在禁用时保持满档 `PrimaryContainer` +/// （那是 M3 FAB token 的口径问题，不由本测试裁决）。 +#[test] +fn disabled_fab_ink_composites_over_its_own_container() { + for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] { + let ui = ui(flavor); + let scheme = unlucky_design::color::BrandBoard::for_flavor(flavor).scheme(); + // 期望值独立算：38% 的 OnPrimaryContainer 叠在满档 PrimaryContainer 上 + let expected = to_iced( + scheme + .get(Role::OnPrimaryContainer) + .with_alpha(0.38) + .over(scheme.get(Role::PrimaryContainer)), + ); + let actual = super::content_color(&ui, Some(Interaction::Disabled)); + assert_eq!( + actual, expected, + "{flavor:?}：禁用 FAB 的内容色 = on-primary-container@38% 叠 PrimaryContainer" + ); + + // 反向：不许等于「叠画布」那一档（修前的错值） + let over_canvas = to_iced( + scheme + .get(Role::OnPrimaryContainer) + .with_alpha(0.38) + .over(scheme.get(Role::Surface)), + ); + assert_ne!(actual, over_canvas, "{flavor:?}：又合到画布上了"); + + // 非禁用档不受影响 + assert_eq!( + super::content_color(&ui, Some(Interaction::Enabled)), + ui.color(Role::OnPrimaryContainer) + ); + } +} 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..6c54a94 --- /dev/null +++ b/crates/app-iced/src/components/buttons/geometry.rs @@ -0,0 +1,119 @@ +//! 按钮家族的**内部几何**：一个数值都不写，全部由 `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::inkcat::size::ControlSize; +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, + /// 尺寸档（决定高、圆角折算边、内距与标签字级）。 + pub size: ControlSize, +} + +impl Geometry { + /// 按变体 + 有没有前置图标求值（默认 **S 档 = 40 高**，产品页用的就是这一档）。 + /// + /// `#[cfg(test)]`：产品路径一律走 [`Geometry::sized`]（`assemble` 里带上了尺寸档）， + /// 这里只给单测一个「S 档」的便捷入口，留成产品 API 只会让 `dead_code` 响。 + #[cfg(test)] + pub fn of(ui: &Ui, variant: Variant, leading_icon: bool) -> Self { + Self::sized(ui, variant, leading_icon, ControlSize::S) + } + + /// 按尺寸档求值（规格卡 `BUTTONS / XS - XL`）。 + /// + /// 内距取 [`ControlSize::pad_x`]（规格卡没写内距，那是 `[估]` 的「半高向下取 4 栅格、封顶 48」 + /// 推导值）；带前置图标时左侧再收 **4**（`Space::X1`）——药丸左半圆里图标要离弧远一点， + /// 与 M3 的「带图标左内距更小」是同一条观感规则。S 档因此是 **20 / 16 / 20**， + /// 而 M3 官方是 24 / 16 / 24：差 4，登记在 M229 报告里（规格卡没给内距，我们按它自己的 + /// 半高规则推，而不是回到官方值——否则五档里只有 S 一种内距口径）。 + pub fn sized(ui: &Ui, variant: Variant, leading_icon: bool, size: ControlSize) -> Self { + let (_, _, border) = variant.roles(); + let pad = size.pad_x(); + let start = if leading_icon { + pad - ui.space(Space::X1) + } else { + pad + }; + + Self { + height: size.height_px(), + padding: Padding { + top: 0.0, + right: pad, + bottom: 0.0, + left: start, + }, + // 图标盒固定 18（`IconSize::Button`）：规格卡五档按钮的图标都没单独写字号， + // 档位只放大容器与标签，不放大图标——那是按钮，不是 FAB。 + icon: IconSize::Button.px(), + gap: ui.space(Space::X2), + stroke: if border.is_some() { STROKE_PX } else { 0.0 }, + size, + } + } +} + +/// 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/icon_variant.rs b/crates/app-iced/src/components/buttons/icon_variant.rs new file mode 100644 index 0000000..3caa0fa --- /dev/null +++ b/crates/app-iced/src/components/buttons/icon_variant.rs @@ -0,0 +1,68 @@ +//! IconButton 的四式（规格卡 `ICON BUTTONS / FILLED - TONAL - OUTLINED - PLAIN`）。 +//! +//! M234 纯搬移：本文件原来只是 `buttons/mod.rs` 的第 166~225 行（`mod.rs` 已顶到 399 行， +//! 加 `.base(..)` 与 `icon_on` 之前必须先腾地方）。搬移**零行为改动**，`IconVariant` 的文档、 +//! 角色表、A1 出处一字未改；对外路径由 `mod.rs` 的 `pub use` 保持为 `buttons::IconVariant`。 + +use unlucky_design::color::Role; + +/// IconButton 的**四式**（规格卡 `ICON BUTTONS / FILLED - TONAL - OUTLINED - PLAIN`）。 +/// +/// 规格卡画了四颗：实心 / 色调 / 描边 / 纯图标。12b §2.5 只有前三式（Standard / Filled / Tonal）， +/// M229 按规格卡把 Standard 拆成 **Plain**（纯图标）与 **Outlined**（1px 描边圆圈）， +/// `Standard` 这个名字保留为 `Plain` 的别名语义，避免既有调用点全改。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +pub enum IconVariant { + /// 纯图标（规格卡 `PLAIN`）：容器透明、图标 `OnSurfaceVariant`（各态图标色不变，12b 2.4）。 + Plain, + /// 实心：`Primary` + `OnPrimary`。 + Filled, + /// Tonal：`SecondaryContainer` + `OnSecondaryContainer`。 + Tonal, + /// 描边：透明容器 + 1px `Outline`（规格卡第三颗，M229 新增）。 + Outlined, +} + +impl IconVariant { + /// 旧名字的别名：`Standard` = [`IconVariant::Plain`]（既有调用点不必改语义）。 + #[allow(non_upper_case_globals)] + pub const Standard: IconVariant = IconVariant::Plain; + + /// 四式全序（gallery 顺序 = 规格卡从左到右）。 + pub const ALL: [IconVariant; 4] = [ + IconVariant::Filled, + IconVariant::Tonal, + IconVariant::Outlined, + IconVariant::Plain, + ]; + + /// 稳定名字。 + pub const fn name(self) -> &'static str { + match self { + IconVariant::Plain => "plain", + IconVariant::Filled => "filled", + IconVariant::Tonal => "tonal", + IconVariant::Outlined => "outlined", + } + } + + /// **禁用态图标色**：四式都是 `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, Option) { + match self { + IconVariant::Plain => (None, Role::OnSurfaceVariant, None), + IconVariant::Filled => (Some(Role::Primary), Role::OnPrimary, None), + IconVariant::Tonal => ( + Some(Role::SecondaryContainer), + Role::OnSecondaryContainer, + None, + ), + IconVariant::Outlined => (None, Role::OnSurfaceVariant, Some(Role::Outline)), + } + } +} 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..c8589cd --- /dev/null +++ b/crates/app-iced/src/components/buttons/mod.rs @@ -0,0 +1,390 @@ +//! 按钮家族（`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 = **`Elevation::Level1.surface_role()`**（= `SurfaceContainerLow`）/`Primary`；Outlined 透明 + 1dp `Outline` + `OnSurfaceVariant`；Text 透明 + `OnSurfaceVariant` | [`Variant::roles`] | +//! | 1.9b | 与 A1 的登记差异（产品口径，M248） | Outlined 描边 A1 是 `OutlineVariant`，本项目取 **`Outline`**：1dp 边界属于**非文字元素**（目标 3:1，`design/color/mod.rs` 的对比度纪律），`OutlineVariant` 是装饰分隔线的角色；且 `IconVariant::Outlined` 一直是 `Outline`，两族由此统一 | [`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::inkcat::size::ControlSize; +use unlucky_design::shape::ShapeScale; + +use crate::icons; +use crate::theme::Ui; + +use super::interaction::{Base, Interaction}; +use super::layout; + +mod assemble; +mod fab; +mod geometry; +mod icon_variant; + +pub use fab::{fab, Fab}; +pub use geometry::{Geometry, IconGeometry}; +pub use icon_variant::IconVariant; + +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, + /// 带高程：L1 的容器面（`Elevation::Level1.surface_role()` = `SurfaceContainerLow`）+ `Primary` 文本。 + Elevated, + /// 描边：透明容器 + 1dp `Outline`（非文字元素角色；装饰分隔线才用 `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, Option) { + match self { + Variant::Filled => (Some(Role::Primary), Role::OnPrimary, None), + Variant::Tonal => ( + Some(Role::SecondaryContainer), + Role::OnSecondaryContainer, + None, + ), + // 容器面由**高程令牌**推导（L1 → `SurfaceContainerLow`）：不许在组件里再抄一遍角色名， + // 换层级口径只改 `elevation.rs` 一处（M248：P2 的落地方式是改来源，不是改色值）。 + Variant::Elevated => (Some(self.elevation().surface_role()), Role::Primary, None), + // 1dp 边界取 `Outline`（非文字元素、目标 3:1）；`OutlineVariant` 是装饰分隔线的角色， + // 拿它画边界在 Ink/Silver 上都到不了 3:1，也和 `IconVariant::Outlined` 不一致（M248：P3）。 + Variant::Outlined => (None, Role::OnSurfaceVariant, Some(Role::Outline)), + Variant::Text => (None, Role::OnSurfaceVariant, None), + } + } +} + +/// 一个按钮的装配描述（五式共用；**不持有任何状态所有权**）。 +/// +/// `on_press: Option` 就是 M3 的 enabled/disabled 开关——`None` = 禁用， +/// 与 `button::on_press_maybe` 的语义天然对齐（省掉一个 `disabled: bool` 字段， +/// 也就不会出现「有消息但画成禁用」这种自相矛盾的状态）。 +#[derive(Debug, Clone)] +pub struct Button<'a, M> { + label: &'a str, + on_press: Option, + leading: Option, + trailing: Option, + state: Option, + /// 尺寸档（规格卡 `BUTTONS / XS - XL`）。产品默认 **S（40 高）**，与 M3 `control_height` 同值。 + size: ControlSize, + /// **脚下那一层的底**（M234）：禁用态的 10% 容器与 38% 内容叠在它上面。 + base: Base, +} + +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, + size: ControlSize::S, + base: Base::CANVAS, + } + } + + /// 一个禁用的按钮（无消息）。禁用不是「另一种颜色」，见 `interaction::disabled_button_colors`。 + pub fn disabled(label: &'a str) -> Self { + Self { + label, + on_press: None, + leading: None, + trailing: None, + state: None, + size: ControlSize::S, + base: Base::CANVAS, + } + } + + /// 换尺寸档（`XS 32 / S 40 / M 56 / L 96 / XL 136`，圆角一律药丸）。 + /// + /// 产品页只用 **S**（= M3 `control_height` 40）；M / L / XL 是规格卡的梯子档，给 + /// 空态主行动与展示型入口留着，`--screen=gallery` 的矩阵会把五档一起拍出来。 + pub fn size(mut self, size: ControlSize) -> Self { + self.size = size; + self + } + + /// 前置图标（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 + } + + /// **告诉按钮它现在踩在什么底上**（M234）：禁用态的 10% 容器与 38% 内容都叠在这个底上。 + /// + /// 放进卡片/面板/浮层里**必须**给——不给就按 [`Base::CANVAS`] 合成，禁用态会与容器底 + /// 脱节（M223 的「CR 1.05、形丢失」）。容器自己的 `BASE` 常量就是标准答案： + /// 卡片 = [`super::surfaces::elevated::BASE`]、菜单项 = `super::inputs::menu::PANEL_BASE`。 + /// + /// iced 没有环境上下文（样式闭包只拿得到 `&Theme`），所以这条信息只能显式传： + /// 这是「组件不猜宿主」的代价，也是 M229 那条「参数在、全传死值」的修法。 + pub fn base(mut self, base: impl Into) -> Self { + self.base = base.into(); + self + } + + /// 视觉态：强制的先，否则「没有消息就是禁用」。 + pub(super) fn forced(&self) -> Option { + self.state.or(if self.on_press.is_none() { + Some(Interaction::Disabled) + } else { + None + }) + } +} + +/// 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 按钮（L1 的容器面 + `Primary` 文本，用色调差表达高程、不画阴影）。 +pub fn elevated<'a, M: Clone + 'a>(ui: &'a Ui, button: Button<'a, M>) -> Element<'a, M> { + assemble(ui, Variant::Elevated, button) +} + +/// Outlined 按钮（透明 + 1dp `Outline`）。 +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) +} + +/// 图标按钮的描边宽度：**有描边角色就有那一圈，没有就是 0**。 +pub(crate) fn icon_stroke(variant: IconVariant) -> f32 { + if variant.roles().2.is_some() { + crate::theme::STROKE_PX + } else { + 0.0 + } +} + +/// 图标按钮的**样式描述**（从 `icon()` 抽出来，好让它能被单测直接钉住）。 +/// +/// 为什么抽：`Style` 闭包不可内省，`icon()` 返回 `Element` 也看不进去——复审把 +/// `StyleSpec.stroke` 写死成 `0.0` 时，`icon_stroke()` 的纯函数测试照样绿（它测的是函数， +/// 不是**接线**）。现在「角色 → 填充/内容/描边」这件事在 `icon_style_spec` 里一次成型， +/// 单测断言的就是 `icon()` 真正塞进 `style_closure` 的那个结构体。 +pub(crate) fn icon_style_spec( + variant: IconVariant, + side: f32, + forced: Option, + base: Base, +) -> StyleSpec { + let (fill, content, border) = variant.roles(); + StyleSpec { + fill, + content, + border, + // 方形图标按钮同样是 full 圆角（40 → 20），档位取自组件表 + shape: Component::IconButton.spec().shape, + // M229 复审 P1-1：这里曾硬编码 `0.0`，于是 `Outlined` 与 `Plain` 逐像素相同。 + stroke: icon_stroke(variant), + radius_side: side, + base, + forced, + } +} + +/// IconButton（standard / filled / tonal）：40×40、图标 24、命中区 48。 +/// +/// **图标语汇纪律（视觉 reviewer P2-3）**：同一个控件里**不混用**填充字形（`IconPaint::Fill`， +/// 如 `Play`/`Stop`/`More`）与描边字形（`Stroke`）——混着放会让线宽看起来忽粗忽细。 +/// 允许实心字形，但只能出现在「主操作」这一处（例如播放按钮），其余位置一律描边； +/// gallery 的样例因此统一用描边图标（`Download` + `ChevronRight`），并有单测钉住。 +/// +/// `on_press: Option`（`None` = 禁用）与 `state` 分开给：前者是语义，后者是取证开关。 +/// +/// 这是 **画布版**（禁用底 = [`Base::CANVAS`]）：放进卡片/面板里请用 [`icon_on`] 给真实父底。 +pub fn icon<'a, M: Clone + 'a>( + ui: &'a Ui, + variant: IconVariant, + kind: IconKind, + on_press: Option, + state: Option, +) -> Element<'a, M> { + icon_on(ui, variant, kind, on_press, state, Base::CANVAS) +} + +/// 带**父底**的 IconButton（M234）：禁用态的 10% 容器与 38% 内容叠在 `base` 上。 +#[allow(clippy::too_many_arguments)] +pub fn icon_on<'a, M: Clone + 'a>( + ui: &'a Ui, + variant: IconVariant, + kind: IconKind, + on_press: Option, + state: Option, + base: impl Into, +) -> Element<'a, M> { + let base = base.into(); + let geometry = IconGeometry::of(ui); + let (fill, content, _) = 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, base, forced, content, fill, variant.disabled_content()); + let icon_box = + layout::centered_fixed(geometry.side, geometry.side, icons::view::(kind, glyph)); + + let style = style_closure(ui, icon_style_spec(variant, geometry.side, forced, base)); + + 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..efe0122 --- /dev/null +++ b/crates/app-iced/src/components/buttons/tests.rs @@ -0,0 +1,360 @@ +//! 按钮家族的单测（几何值 / 色彩角色 / 样式闭包）。 +//! +//! 这里测的是「函数与样式结构」；**像素级**的几何（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, Base, 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::(&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" + ); + // M229：内距取规格卡的 `ControlSize::pad_x`（S 档 = 20），不再是 12b 的 24。 + assert_eq!(geometry.padding.left, 20.0, "S 档 pad_x 20"); + assert_eq!(geometry.padding.right, 20.0, "S 档 pad_x 20"); + 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, + "带图标左侧再收 4（20 − 4）：与 12b 1.4 的 16 恰好同值" + ); + assert_eq!(with_icon.padding.right, 20.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 命中下限" + ); +} + +mod base; +mod icon; +mod roles; + +/// 视觉 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::Outline) + ), + "描边取 Outline（M248：非文字元素角色；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::(&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) -> StyleSpec { + let (fill, content, border) = variant.roles(); + StyleSpec { + fill, + content, + border, + shape: variant.shape(), + base: Base::CANVAS, + 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::Outline) + ); + 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, Base::CANVAS); + 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/buttons/tests/base.rs b/crates/app-iced/src/components/buttons/tests/base.rs new file mode 100644 index 0000000..85edbfa --- /dev/null +++ b/crates/app-iced/src/components/buttons/tests/base.rs @@ -0,0 +1,75 @@ +//! 禁用态**合成底**的接线判据（M234；从 `buttons/tests.rs` 拆出，守 400 行硬线）。 +//! +//! 判据走真装配路径（`Button::base` → `text_style_spec` → `style_closure`）， +//! 不是「自己拼一个 `StyleSpec` 再喂进去」——后者证明不了接线（M229 复审 P1-1 的教训）。 + +use iced::widget::button; +use iced::Background; + +use unlucky_design::color::Role; +use unlucky_design::color::SchemeFlavor; + +use super::super::Button; +use super::{light, style_closure, Variant}; +use crate::app::components::interaction::Base; +use crate::app::components::surfaces; +use crate::theme::to_iced; + +/// **M234 的接线判据**：禁用按钮的容器色必须在**它被告诉的那层底**上合成。 +/// +/// 走的是**真装配路径**：`Button::base(..)` → `text_style_spec`（接线）→ `style_closure` +/// （求值）。所以这条红了只有两种原因：① `assemble` 没把 `spec.base` 传下去； +/// ② `disabled_button_colors` 内部又写死了画布色。 +/// +/// 抓得住：卡片/面板里的禁用按钮叠错底（M223 的「CR 1.05、形丢失」就是这么来的）。 +/// 抓不住：调用点**忘了**调 `.base(..)`（编译期不报错，默认 `Base::CANVAS`）——那一半由 +/// `gallery` 的像素 probe（`ULL_GALLERY_SECTION=disabledbase`）与卡片场景守。 +#[test] +fn a_disabled_button_composites_over_the_base_it_is_given() { + use unlucky_design::color::BrandBoard; + + let ui = light(); + let card = surfaces::elevated::BASE; + + let spec = super::super::assemble::text_style_spec( + &ui, + Variant::Filled, + &Button::::disabled("卡片里"), + ); + assert_eq!( + spec.base, + Base::CANVAS, + "不调 `.base(..)` 时是画布底（默认值，语义写在 `Base::CANVAS` 的文档里）" + ); + + let card_spec = super::super::assemble::text_style_spec( + &ui, + Variant::Filled, + &Button::::disabled("卡片里").base(card), + ); + assert_eq!( + card_spec.base, card, + "接线：`Button::base` 必须原样进 `StyleSpec`" + ); + + let card_style = style_closure(&ui, card_spec)(&ui.theme(), button::Status::Disabled); + let canvas_style = style_closure(&ui, spec)(&ui.theme(), button::Status::Disabled); + + // 期望值独立算（写死 0.10 + 直接取色板角色），不调被测入口。 + let scheme = BrandBoard::for_flavor(SchemeFlavor::Light).scheme(); + let expected_card = to_iced( + scheme + .get(Role::OnSurface) + .with_alpha(0.10) + .over(scheme.get(Role::SurfaceContainer)), + ); + assert_eq!( + card_style.background, + Some(Background::Color(expected_card)), + "卡片里的禁用 Filled 按钮容器 = on-surface@10% 叠 **SurfaceContainer**" + ); + assert_ne!( + card_style.background, canvas_style.background, + "卡片底与画布底的合成结果必须不同（叠在画布上就是 M234 要修的那条）" + ); +} diff --git a/crates/app-iced/src/components/buttons/tests/icon.rs b/crates/app-iced/src/components/buttons/tests/icon.rs new file mode 100644 index 0000000..f378dc5 --- /dev/null +++ b/crates/app-iced/src/components/buttons/tests/icon.rs @@ -0,0 +1,53 @@ +//! 图标按钮的单测（M229 复审 P1-1 从 `buttons/tests.rs` 拆出，守 400 行硬线）。 +//! +//! 拆出来的只有「四式图标按钮的描边」这一组：`icon()` 曾经把 `StyleSpec.stroke` 写死 `0.0`， +//! 于是 `Outlined` 与 `Plain` 逐像素相同——判据在这里，渲染级的那一半在 `gallery/probe/rows.rs`。 + +use super::*; + +/// **M229 复审 P1-1 的回归门**：四种图标按钮里**只有 `Outlined` 有描边**。 +/// +/// 抓得住：`icon()` 里把 `stroke` 写死成 0（那样 Outlined 与 Plain 逐像素相同——正是复审量到的现场）。 +/// 抓不住：描边颜色对不对（那是 `IconVariant::roles` 的事，上面已有变体表测试）。 +/// +/// 渲染级的第二道在 `components/gallery/probe.rs`（`buttons` 段的 sheet 上数 Outlined 行的环像素、 +/// 并断言 Plain 行没有环），这一条是纯函数的、不依赖出图。 +#[test] +fn only_the_outlined_icon_variant_draws_a_ring() { + use super::super::{icon_stroke, icon_style_spec}; + + assert_eq!( + icon_stroke(IconVariant::Outlined), + crate::theme::STROKE_PX, + "Outlined 必须画 1px 环（否则与 Plain 逐像素相同）" + ); + assert_eq!( + icon_stroke(IconVariant::Outlined), + 1.0, + "全站描边 1px（rubric G7）" + ); + for plain in [IconVariant::Plain, IconVariant::Filled, IconVariant::Tonal] { + assert_eq!(icon_stroke(plain), 0.0, "{plain:?} 不该有描边"); + } + // 与角色表同源：有描边角色 ⇔ 有环。 + for variant in IconVariant::ALL { + assert_eq!( + icon_stroke(variant) > 0.0, + variant.roles().2.is_some(), + "{variant:?} 的描边与角色表不一致" + ); + // **接线断言**：`icon()` 真正塞进 `style_closure` 的那个结构体（`icon_style_spec`）。 + // 只测 `icon_stroke()` 抓不住「调用点写死 0」——第一版就是这样漏的（变异测试证明过）。 + let spec = icon_style_spec(variant, 40.0, None, Base::CANVAS); + assert_eq!( + spec.stroke, + icon_stroke(variant), + "{variant:?}：icon() 用的描边宽度与角色表不一致（调用点被写死了？）" + ); + assert_eq!( + spec.border.is_some(), + icon_stroke(variant) > 0.0, + "{variant:?}：描边角色与线宽必须同生同灭" + ); + } +} diff --git a/crates/app-iced/src/components/buttons/tests/roles.rs b/crates/app-iced/src/components/buttons/tests/roles.rs new file mode 100644 index 0000000..6a46393 --- /dev/null +++ b/crates/app-iced/src/components/buttons/tests/roles.rs @@ -0,0 +1,190 @@ +//! 角色语义 + 「可主题化」断言（M248：Elevated 底 / Outlined 描边）。 +//! +//! **判据不是「等于某个 hex」**：品牌色板本来就会被换（D38 的取色方案会整表接管 49 个角色）， +//! 钉死色值等于把「配色可自定义」这条路焊上。所以这里钉两件互相补位的事： +//! +//! 1. [`role_table_is_named_roles_not_colours`]：`Variant::roles()` 吐的是**角色名**；Elevated 的 +//! 容器还必须由**高程令牌**推导（`Elevation::Level1.surface_role()`），不许在组件里手抄一遍； +//! 2. [`styles_follow_the_scheme_across_boards_and_custom_accents`]：同一变体在 Ink / Silver / +//! 自定义种子方案（`Scheme::from_seed`）三套方案下，`button::Style` 里解出的颜色**分别等于 +//! 各自方案的该角色色值**，且三者互不相同。把「取角色」改成「取死值（`Role::Surface`）」 +//! 或「写死某套方案」都会被这条打红。 +//! +//! 抓不住什么： +//! - **令牌表里两个角色同值**时，换角色的变异只有第 1 条会红； +//! - **像素**：角色写对了、图上却是别的颜色（样式闭包被别处覆盖）——那是 `gallery/probe` 与出图的事。 + +use iced::widget::button; +use iced::Background; + +use unlucky_design::color::{BrandBoard, Role, Scheme, SchemeFlavor}; +use unlucky_design::elevation::Elevation; +use unlucky_design::typography::Platform; + +use super::super::{style_closure, IconVariant, Variant}; +use super::spec_of; +use crate::theme::{Ui, STROKE_PX}; + +/// 三套配色来源：两块出厂品牌板 + 一套 `Scheme::from_seed` 自定义种子方案。 +/// +/// 第三套是关键：品牌板是固化数据，**换不了**；只有「同一份组件代码吃进另一套方案就换色」 +/// 才叫可自定义（D38 的取色链就是这么接管 49 个角色的）。种子用 design 里的 +/// [`DEFAULT_SEED`]（取色链默认的天蓝）——它是令牌，不是本文件写下的色值字面量 +/// （`tests/no_hardcoded_tokens.rs` 拦 `#RRGGBB`，这条门禁是对的）。 +fn themes() -> Vec<(&'static str, Ui)> { + vec![ + ( + "ink", + Ui::with_board(BrandBoard::Ink, Platform::Windows, super::FAMILIES), + ), + ( + "silver", + Ui::with_board(BrandBoard::Silver, Platform::Windows, super::FAMILIES), + ), + ( + "custom", + Ui::from_scheme( + Scheme::from_seed(SchemeFlavor::Dark, unlucky_design::color::DEFAULT_SEED), + super::FAMILIES, + ), + ), + ] +} + +#[test] +fn role_table_is_named_roles_not_colours() { + // ---- P2：Elevated 的容器是**高程令牌的推论**，不是一个手抄的角色名 ---------- + assert_eq!(Variant::Elevated.elevation(), Elevation::Level1, "L1"); + assert_eq!( + Variant::Elevated.roles().0, + Some(Elevation::Level1.surface_role()), + "Elevated 的底必须由高程令牌推导（L1 → surface_role = SurfaceContainerLow），\ + 组件里不许再写一遍这个角色名" + ); + assert_ne!( + Elevation::Level1.surface_role(), + Role::Surface, + "L1 的容器面必须比画布高一档（否则 Elevated 与画布同色）" + ); + + // ---- P3：1dp 边界取 `Outline`；`OutlineVariant` 是装饰分隔线的角色 ---------- + assert_eq!( + Variant::Outlined.roles(), + (None, Role::OnSurfaceVariant, Some(Role::Outline)), + "Outlined 的 1dp 描边取 Outline（`design/color/mod.rs` 的对比度纪律：\ + Outline 是「非文字元素」角色、目标 3:1；OutlineVariant 是纯装饰分隔线）" + ); + // 同族一致性：图标按钮那一式一直是 Outline，此前文字按钮是 OutlineVariant ⇒ 全站两套描边 + assert_eq!( + IconVariant::Outlined.roles().2, + Some(Role::Outline), + "图标按钮 Outlined 与文字按钮 Outlined 必须是同一个描边角色" + ); +} + +/// 非文字元素的对比度下限 3:1（WCAG 1.4.11；`design/color/mod.rs` 的对比度纪律同一口径）。 +/// +/// 这条是 P3 的**理由**而不只是判据：`OutlineVariant` 在深/浅两块板上都到不了 3:1， +/// 拿它画按钮边界等于「看得见形状、量不出边界」。别把下限写死成某个角色的实测值—— +/// 换品牌板或换取色方案时，比例是**算出来的**，不是抄出来的。 +#[test] +fn outlined_boundary_meets_the_non_text_contrast_bar() { + for (name, ui) in themes() { + let scheme = ui.scheme(); + let boundary = scheme.contrast(Role::Outline, Role::Surface); + assert!( + boundary >= 3.0, + "{name}: Outline/Surface = {boundary:.2}，非文字元素下限是 3:1" + ); + // 报告用：装饰角色差多少（`--nocapture` 可见），不改判据 + eprintln!( + "[{name}] Outline/Surface={boundary:.2} · OutlineVariant/Surface={:.2}", + scheme.contrast(Role::OutlineVariant, Role::Surface) + ); + } +} + +#[test] +fn styles_follow_the_scheme_across_boards_and_custom_accents() { + let elevated = spec_of(Variant::Elevated, Some(super::Interaction::Enabled)); + let outlined = spec_of(Variant::Outlined, Some(super::Interaction::Enabled)); + + let mut elevated_fills = Vec::new(); + let mut outlined_strokes = Vec::new(); + + for (name, ui) in themes() { + let style = style_closure(&ui, elevated); + let idle = style(&ui.theme(), button::Status::Active); + let expected = ui.color(Elevation::Level1.surface_role()); + assert_eq!( + idle.background, + Some(Background::Color(expected)), + "{name}: Elevated 的底 = 本方案的 L1 容器面" + ); + assert_ne!( + idle.background, + Some(Background::Color(ui.color(Role::Surface))), + "{name}: Elevated 退化成画布色了（取死值 Surface 的变异会打红这条）" + ); + assert_eq!( + idle.text_color, + ui.color(Role::Primary), + "{name}: Elevated 标签 = Primary" + ); + + let style = style_closure(&ui, outlined); + let idle = style(&ui.theme(), button::Status::Active); + assert_eq!( + idle.border.color, + ui.color(Role::Outline), + "{name}: Outlined 描边 = Outline" + ); + assert_eq!(idle.border.width, STROKE_PX, "{name}: 描边 1dp"); + assert_eq!( + idle.text_color, + ui.color(Role::OnSurfaceVariant), + "{name}: Outlined 标签 = OnSurfaceVariant" + ); + + elevated_fills.push(expected); + outlined_strokes.push(idle.border.color); + } + + // 三套方案两两不同 ⇒「跟着配色来源走」这件事有实据（不是三套恰好同色） + for (index, (name, _)) in themes().iter().enumerate() { + for other in index + 1..elevated_fills.len() { + assert_ne!( + elevated_fills[index], elevated_fills[other], + "{name} 与第 {other} 套方案的 Elevated 底同色，可主题化没有实据" + ); + assert_ne!( + outlined_strokes[index], outlined_strokes[other], + "{name} 与第 {other} 套方案的 Outlined 描边同色" + ); + } + } +} + +/// 基线条：Ink（深）与 Silver（浅）两块**出厂**板必须给出不同的 Elevated 底与 Outlined 描边。 +/// +/// 与上一条分开写：上一条的三套方案里有一套是自定义的，这条只钉出厂外观—— +/// 哪怕有人把 `themes()` 改成只跑自定义方案，出厂这块的回归也还在。 +#[test] +fn ink_and_silver_resolve_the_same_roles_to_different_colours() { + let ink = Ui::with_board(BrandBoard::Ink, Platform::Windows, super::FAMILIES); + let silver = Ui::with_board(BrandBoard::Silver, Platform::Windows, super::FAMILIES); + for role in [ + Elevation::Level1.surface_role(), + Role::Outline, + Role::OnSurfaceVariant, + ] { + assert_ne!( + ink.color(role), + silver.color(role), + "{role:?} 在 Ink 与 Silver 上同色，说明它没跟着色板走" + ); + } + // 浅色板的 L1 容器必须比画布暗、深色板必须比画布亮（层级方向不能反） + assert!(silver.color(Role::Surface).r > silver.color(Role::SurfaceContainerLow).r); + assert!(ink.color(Role::Surface).r < ink.color(Role::SurfaceContainerLow).r); +} 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..e30c7d8 --- /dev/null +++ b/crates/app-iced/src/components/feedback/action.rs @@ -0,0 +1,175 @@ +//! 反馈家族里的两个**小动作件**：文字动作与图标动作。 +//! +//! ## 为什么不复用 `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`，`None` = 禁用；文字色降到 +//! `OnSurface@38%`，标签本身**不删**。禁用色的**底**是这两个动作件自己的容器角色 +//! （`InverseSurface` / `SurfaceContainerHigh`）——M234 起 +//! [`interaction::disabled_content_over_role`] 收任意底（[`interaction::Base`]），所以这里 +//! **直接传容器角色**，不再自己写一遍 α 合成（M234 之前那段本地合成会得到「38% 深字叠深底」，复审 P2-4）。 + +use iced::widget::{button, text}; +use iced::{Background, Border, Element, Length, Padding, Shadow}; + +use unlucky_design::color::Role; +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::Ui; + +use super::super::interaction::{self, Interaction}; +use super::super::layout; + +/// 禁用态内容色：`OnSurface@38%` 叠在**真实容器色**上。 +/// +/// 这两个动作件的底是 `InverseSurface`（Snackbar）与 `SurfaceContainerHigh`（Dialog）， +/// M234 之后 `interaction::disabled_content_over_role` 收任意 [`interaction::Base`]，所以 +/// 这里只把容器角色包成 `Base` 交给它——α（0.38）与叠法仍由 `interaction::disabled` 一处给， +/// 本文件零 α 字面量、也没有第二份合成实现。 +fn content_color(ui: &Ui, role: Role, container_role: Role, disabled: bool) -> iced::Color { + if !disabled { + return ui.color(role); + } + // M234：`disabled_content_over_role` 现在收**任意**底（`Base`），所以这里的本地合成可以删掉 + // ——底就是这两个动作件自己的容器角色（Snackbar = InverseSurface / Dialog = SurfaceContainerHigh）， + // α 与叠法仍由 `interaction::disabled` 那一处给（本文件零 α 字面量）。 + interaction::disabled_content_over_role( + ui, + interaction::Base::of(container_role), + Role::OnSurface, + false, + ) +} + +/// 一个文字动作（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, + forced: Option, +) -> 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, + forced: Option, +) -> 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::(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..1b07a13 --- /dev/null +++ b/crates/app-iced/src/components/feedback/dialog.rs @@ -0,0 +1,266 @@ +//! 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; +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, +} + +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 @ SCRIM_ALPHA` 叠在 `MaterialLayer::Canvas` 上之后的**实色**（D27）。 +/// +/// 叠的底是 [`Ui::scheme`]（品牌色板 / 取色方案）：M229 之前这里按 `Scheme::baseline(flavor)` +/// 重算，Ink 板上量到的是旧蓝中性底压出来的**偏蓝**遮罩；按品牌板合成才是中性绿黑 +/// （`scrim` 是 M3 定值纯黑，两板同值，差的是它下面的画布色）。 +pub fn scrim(ui: &Ui) -> iced::Color { + let scheme = ui.scheme(); + 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> { + 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, +) -> 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::(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 { + 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..1a2fae5 --- /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`、轨道 **`SurfaceContainerHighest`**（A1 `TrackColor` 是 `SecondaryContainer`；M248 按「轨道是背景尺」改口径，登记差异；旧值留作对照） | 组件层取角色 | +//! | 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 圆角 | 规格卡 **16**（`inkcat::metrics::SNACKBAR`；官方 `CornerExtraSmall` 是 4，M229 换肤按规格卡） | `panel::SnackbarGeometry::radius` | +//! | 14.3 | 单行 / 双行高 | 规格卡 **52** / **72**（+20；官方 48/68） | `panel::SnackbarGeometry::height_for` | +//! | 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..e53f62c --- /dev/null +++ b/crates/app-iced/src/components/feedback/mod.rs @@ -0,0 +1,91 @@ +//! **反馈类家族**：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`]，**底由容器给** +//! （[`interaction::Base`]）：`action.rs` 传的是这两个动作件自己的容器角色 +//! （`InverseSurface` / `SurfaceContainerHigh`），其余组件传 `Base::CANVAS`； +//! 禁用是**状态**（`on_press: Option` 为 `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..e867e88 --- /dev/null +++ b/crates/app-iced/src/components/feedback/panel.rs @@ -0,0 +1,153 @@ +//! 三件「面」的几何：Snackbar / Dialog / EmptyState（数值与出处见 [`super::geometry`] 的 G17 表）。 +//! +//! 为什么与进度分家：进度那两个是**带节奏的图形**（keyframes 与相位），这三件是**静态盒子** +//! （宽高/内距/圆角）。合在一个文件里会顶到 400 行红线（AGENTS.md §3-1）。 + +use unlucky_design::component_map::Component; +use unlucky_design::inkcat::metrics as inkcat; +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 { + /// 从令牌求值。 + /// + /// M229 换肤把**高与圆角**改成规格卡口径（`inkcat::metrics::SNACKBAR`：340×**52**、rx=**16**）： + /// 官方 `SnackbarTokens` 是 48 高 + `CornerExtraSmall(4)`，规格卡画成 52/16 —— M228 已把这条 + /// 差异登记为「换肤时取 `SNACKBAR`」。双行高仍按官方「每多一行 +20」推成 **72**（52 + 20）， + /// 与单行同 delta；宽上限 600 与边距 12 不动（它们不在规格卡上）。 + pub fn of(ui: &Ui) -> Self { + let spec = inkcat::SNACKBAR; + let single_height = spec.height; + Self { + min_width: 344.0, + max_width: 600.0, + single_height, + two_height: single_height + 20.0, + margin: ui.space(Space::X3), + pad_h: ui.space(Space::X4), + pad_v: 6.0, + gap: ui.space(Space::X2), + radius: spec.radius_px(), + } + } + + /// 按行数取高：`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..2bf9f99 --- /dev/null +++ b/crates/app-iced/src/components/feedback/pixel.rs @@ -0,0 +1,347 @@ +//! 像素取证的小工具（**仅测试**）：读 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 { + 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 { + 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] + } + + /// **合成图**（不读盘）：按 `(x, y) → RGB` 造一张 `width × height` 的图。 + /// + /// 只给回归用例用：有些几何错误在真截图上**不会自然出现**（例如「轨道被宿主裁短」—— + /// 真实渲染里轨道永远占满宿主，只有把像素涂掉才看得到，那是复审的一次性动作）。 + /// 合成图让这类形状变成可复现的夹具，见 `tests/bands.rs`。 + pub(super) fn from_rows( + width: usize, + height: usize, + pixel: impl Fn(usize, usize) -> [u8; 3], + ) -> Self { + let mut pixels = Vec::with_capacity(width * height); + for y in 0..height { + for x in 0..width { + pixels.push(pixel(x, y)); + } + } + Self { + width, + height, + pixels, + } + } +} + +/// 一个外接框（闭区间）。 +#[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::>() + .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::() / square; + let distance = (0..3) + .map(|i| (offset[i] - t * axis[i]).powi(2)) + .sum::() + .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 = 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 = 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) +} + +/// 按「**每行最长连续段** ≥ `min_run`」聚成的竖带。 +/// +/// 与 [`bands`] 的区别只在「一行算不算墨」的判法：`bands` 数**覆盖率 ≥50% 的像素个数**， +/// 本函数要求这些像素连成一长段。M248 换了进度轨道的角色之后，这个区别变成了分水岭： +/// +/// - 轨道从强调色族（`SecondaryContainer`）改成中性容器面（`SurfaceContainerHighest`）后， +/// 「画布 → 轨道」这条混色轴**正好穿过中性文字与中性容器面**：文字像素的投影 `t` 会 clamp 到 +/// 1.0、残差只剩 <8，于是整行文字都能被数成「轨道墨」（浅色板实测：命中行数从 2 条涨到 5 条， +/// 多出来的三条是图注文字，高度 6 / 2 / 6 行）； +/// - 按**连续段**判就不受影响：一行 12px 的字形边缘凑不出 200px 的连续同色段，而 360px 的轨道 +/// 一眼就能认出来。 +/// +/// 阈值的取值口径：轨道带最窄的整段是 200px 以上（线性进度宿主 320/360 宽，指示条压在轨道上 +/// 会把轨道切成几段，最长的那段仍 ≥200——不加指示条的确定态那一格是整条 360）。 +pub(super) fn bands_by_run( + shot: &Shot, + fill: Color, + under: Color, + min_run: usize, +) -> Vec<(usize, usize)> { + let mut found: Vec<(usize, usize)> = Vec::new(); + let mut current: Option = None; + for y in 0..shot.height { + let longest = runs(shot, y, fill, under) + .into_iter() + .map(|(_, len)| len) + .max() + .unwrap_or(0); + let hit = longest >= min_run; + match (hit, current) { + (true, None) => current = Some(y), + (false, Some(top)) => { + found.push((top, y - 1)); + current = None; + } + _ => {} + } + } + if let Some(top) = current { + found.push((top, shot.height - 1)); + } + found +} + +/// 某种颜色的**精确色**连通块（只用于「找着一大块实心」这种粗定位）。 +pub(super) fn blobs(shot: &Shot, color: Color, min_side: usize) -> Vec { + 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 { + let (target, base) = (rgb(ink), rgb(under)); + let mut found: Option = 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::(); + let to_base = pixel + .iter() + .zip(base) + .map(|(a, b)| u32::from(a.abs_diff(b))) + .sum::(); + 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..cd54a15 --- /dev/null +++ b/crates/app-iced/src/components/feedback/probe.rs @@ -0,0 +1,319 @@ +//! 反馈家族的**渲染层**几何断言：对着真截图量像素（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; +pub(super) mod track; + +use unlucky_design::color::{Role, SchemeFlavor}; +use unlucky_design::typography::Platform; + +use super::geometry::PHASE_055; +use super::pixel::{band_width, bands, bands_by_run, 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; + +/// 认定为「主色进度行」所需的连续主色段长度。 +/// +/// phase 0.55 的两段分别是 ≈24px 与 ≈165px，取 60 既收得住第二段、又挡得住文字行（实测 ≤22px）。 +const INDETERMINATE_MIN_RUN: usize = 60; + +/// 一条测试覆盖当前截图对应的那一段（段由 `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 active = ui.color(Role::Primary); + + // §12.1（厚度 / 宽度 / 圆角）搬去 `probe/track.rs`：那边撞了 400 行红线，见该文件文档。 + track::check(shot, ui); + + // ---- 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·12.4：phase 0.55 两段 {found:?}（行 {row}）"); +} + +/// 线性不定态那一行的 y：主色墨迹在**第一条轨道**里出现、且不在确定态行的最上一组。 +/// +/// 不想硬编码坐标（gallery 一改间距就失准），所以按「主色横带 + 排除最高那条带」找。 +/// +/// **按连续段判，不按计数判**（M248 修）：标题与图注的行里主色像素能凑到 20 个以上， +/// 按旧口径 `bands(.., 20)` 会把标题行（深色板实测 y≈64）当成第一组主色带，`found[1]` +/// 于是落在文字上、`runs` 只返回一个 11px 的段 —— 这条在**改前**就红（用改前的图 + 改前的 +/// 探针复现过，与换轨道颜色无关）。轨道行是 60px 以上的**连续**主色段，文字行不是。 +fn indeterminate_row(shot: &Shot, active: iced::Color, surface: iced::Color) -> usize { + let found = bands_by_run(shot, active, surface, INDETERMINATE_MIN_RUN); + assert!( + found.len() >= 2, + "至少要找到确定态行与不定态行两组主色横带，实测 {found:?}" + ); + // 第一组是确定态（0% 无墨、50%/100% 有墨），第二组是不定态 + let (top, bottom) = found[1]; + (top + bottom) / 2 +} + +/// §14：宽度上下限 + 单/双行高。 +fn check_snackbar(shot: &Shot, ui: &Ui) { + // 参考值写字面量：600 = SnackbarKt.ContainerMaxWidth，52/72 = 规格卡（单行 52 + 每多一行 20）。 + 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 = found + .iter() + .map(|band| band_width(shot, *band, bar, surface)) + .collect(); + let mut heights: Vec = 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, 52)), + "规格卡：单行高 52，实测高度集 {heights:?}" + ); + assert!( + heights.iter().any(|h| near(*h, 72)), + "双行高 72（52 + 20），实测高度集 {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 = 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..466f9d3 --- /dev/null +++ b/crates/app-iced/src/components/feedback/probe/circular.rs @@ -0,0 +1,159 @@ +//! 环形进度的渲染层判据（`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); + // M248：轨道改成容器面角色（与线性同源），参考值写字面角色，不从 `progress_roles()` 读回。 + let track = ui.color(Role::SurfaceContainerHighest); + 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 = 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 = (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 = 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 = (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 = 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 = 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/probe/track.rs b/crates/app-iced/src/components/feedback/probe/track.rs new file mode 100644 index 0000000..8b28748 --- /dev/null +++ b/crates/app-iced/src/components/feedback/probe/track.rs @@ -0,0 +1,112 @@ +//! 线性进度**轨道本身**的判据（§12.1：厚度 / 宽度 / 圆角）。 +//! +//! 从 `probe.rs` 拆出来（M248 r1 复审时那边正好 401 行，撞 400 红线）：顺着 `circular` / +//! `panels` 的同一先例，一族几何一个文件。 +//! +//! ## 取带规则（M248 r1 P2-1 / P2-2 的教训） +//! +//! 轨道的配色从强调色族换成中性容器面（`SurfaceContainerHighest`）之后，「画布 → 轨道」这条 +//! 混色轴正好穿过中性文字：按**计数**判（`bands`，一行里有多少个覆盖率 ≥50% 的像素）会把 +//! 图注行也数成轨道（浅色板实测多出 3 条假带：6/2/6 行）。所以这里改成按**连续段**判 +//! （`pixel::bands_by_run`）。 +//! +//! 复审判过这条改动：「换判据」的方向对，但第一版把阈值定成 200，**顺手丢了半个守卫**—— +//! 把 after 图里 0% 那条轨道右半截涂回画布色（连续段 160px = 轨道被宿主裁短的形态）之后， +//! 那一行直接不再成带，`check_linear` 靠另一条带照样绿。现在分两条判据： +//! +//! | 判据 | 常量 | 决定什么 | 实测口径（两套主题一致） | +//! |---|---|---|---| +//! | 成带 | [`TRACK_MIN_RUN`] = **100** | 这一行算不算轨道行 | 确定态行最长段 318~320、不定态行 306~308、文字行 **22** | +//! | 宽度 | [`TRACK_MIN_WIDTH`] = **300** | 这条轨道的宽度对不对 | 宿主 320/360，砍半（160）必须判不合格 | +//! +//! ⚠️ **别按「单条轨道」心算阈值**：`bands_by_run` 是按**整行**取最长连续段（三个宿主在同一 +//! y 上，取其中最长那一段），不是按单条 320 轨道取。按单条轨道算会得到 ~88px 的错值， +//! 于是把阈值定到 200，160px 的窄轨道就整行掉出判据——复审就是这么抓到第一版的漏洞的。 +//! +//! 取值区间由 `tests/bands.rs` 的合成图钉住（成带阈值调大到 >160、或小到 ≤22，那里都红）。 + +use unlucky_design::color::Role; + +use super::super::pixel::{band_width, bands_by_run, matches, near, rgb, runs, Shot}; +use crate::theme::Ui; + +/// 认定为「轨道行」所需的**连续**同色段长度。 +/// +/// `pub(crate)`：`tests/bands.rs` 的合成图要断言这两个阈值本身（`probe` 是 `#[cfg(test)]` 模块）。 +pub(crate) const TRACK_MIN_RUN: usize = 100; + +/// 轨道必须占满宿主带来的宽度（线性进度宿主 320/360，下限取 300）。 +pub(crate) const TRACK_MIN_WIDTH: usize = 300; + +/// `check` 的**取带规则**（`pub(crate)` 是为了让 `tests/bands.rs` 的合成图跑同一段逻辑）。 +/// +/// 抽函数而不是让用例直接调 `bands_by_run`：用例要能在「调用点被改回计数判据」时变红， +/// 那就得覆盖调用点本身。 +pub(crate) fn track_bands( + shot: &Shot, + track: iced::Color, + surface: iced::Color, +) -> Vec<(usize, usize)> { + bands_by_run(shot, track, surface, TRACK_MIN_RUN) +} + +/// §12.1：线性轨道的厚度（4 行）、宽度（占满宿主）、圆角（full）。 +/// +/// 参考值写字面量（A1）：**不能**从 `LinearGeometry` 读回期望值——那样把 4 改成 6 之后 +/// 「实测 6 == 期望 6」会照样绿，等于没有断言。轨道的**角色**同理，由调用方给字面角色 +/// （`SurfaceContainerHighest`），不从 `progress::progress_roles()` 读回。 +pub(super) fn check(shot: &Shot, ui: &Ui) { + let surface = ui.color(Role::Surface); + let track = ui.color(Role::SurfaceContainerHighest); + + let bar_bands = track_bands(shot, track, surface); + assert!( + bar_bands.len() >= 2, + "线性进度应有两条轨道带（确定态 + 不定态），实测 {bar_bands:?}：\ + 某一条整行掉出判据 = 它被裁到 <{TRACK_MIN_RUN}px 连不成段了" + ); + for (top, bottom) in &bar_bands { + let height = bottom - top + 1; + assert!( + near(height, 4), + "12.1：线性进度厚必须 4（A1 Height；实测 {height} @ 行 {top}）" + ); + // 宽度**单独**判（M248 r1 P2-1）：阈值 100 会把被裁短的轨道也认成一条带， + // 所以「窄了」不能再靠「找不到带」兜——复审反例（砍到 160px）走的就是这条路。 + let widest = band_width(shot, (*top, *bottom), track, surface); + assert!( + widest >= TRACK_MIN_WIDTH, + "12.1：轨道必须占满宿主（≥{TRACK_MIN_WIDTH}px 的连续段），实测最宽段 {widest}px @ 行 {top}" + ); + } + + // 圆角 full：条的四角必须透出底色（直角会把角填满）。 + let (top, _) = bar_bands[0]; + let (left, len) = runs(shot, top + 1, track, surface) + .into_iter() + .find(|(_, len)| *len >= TRACK_MIN_WIDTH) + .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)), + "条的中间必须有墨（否则是没画出来，不是圆角）" + ); + + // 覆盖面账（复审可对 `--nocapture` 输出核）：两条带**都在**厚度/宽度判据里； + // 不定态那条 5 行是含 1 行抗锯齿（`near(·, 4)` 容 ±1）。12.4 只量主色两端点，不量厚度。 + eprintln!( + "[feedback-probe] 轨道带 {} 条（高 {:?}）· 最宽段 {:?}", + bar_bands.len(), + bar_bands + .iter() + .map(|(top, bottom)| bottom - top + 1) + .collect::>(), + bar_bands + .iter() + .map(|band| band_width(shot, *band, track, surface)) + .collect::>(), + ); +} 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..fbf5b57 --- /dev/null +++ b/crates/app-iced/src/components/feedback/progress.rs @@ -0,0 +1,330 @@ +//! 进度指示器（`research/12b` §12）：`linear` 与 `circular`，各有确定态与不定态。 +//! +//! ## 两种形态、四种态 +//! +//! | 形态 | 确定态 | 不定态 | +//! |---|---|---| +//! | [`linear`] | 轨道 `SurfaceContainerHighest` + 指示条 `Primary`，厚 **4**、圆角 full | 官方 1750ms **双段**追逐（[`phase_segments`]） | +//! | [`circular`] | 40 环 + 4 线宽，弧长 = 数值 × 360° | 官方 6000ms（弧长 0.1↔0.87 + 旋转 **0→1440°**：全局 1080° 线性 + 关键帧 360°，[`CircularGeometry::indeterminate`]） | +//! +//! **轨道角色为什么是容器面（M248，与 A1 的登记差异）**：A1 的 +//! `LinearProgressIndicatorTokens.TrackColor` 是 `SecondaryContainer`，本项目取 +//! `SurfaceContainerHighest`。口径是「轨道 = 进度还剩多少的**背景尺**，属于表面层级； +//! 强调色只属于指示条」。取角色而不是色值，所以换品牌板 / 换 D38 取色方案它跟着变 +//! （判据见 `tests/progress.rs` 的 `track_is_the_highest_container_step_and_follows_the_scheme`）。 +//! 12b §12.2 的旧值仍留在 `geometry.rs` 的参考值表里当对照。 +//! +//! ## 为什么不定态要调用方给 `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 +} + +/// 进度家族的取色角色 `(轨道, 指示条)`。 +/// +/// **为什么要这个函数**：`Element` 是黑盒、`container::Style` 与 `svg::Style` 都是闭包， +/// 两者都不可内省（同 `buttons::icon_style_spec` 的教训：把 `stroke` 写死成 0 时纯函数测试照样绿）。 +/// 取色点收成这一对角色，单测才能钉住「取的是哪个角色」而不只是「渲染没 panic」。 +/// +/// 轨道 = `SurfaceContainerHighest`（比画布高一档以上的容器面，与输入框底同层）；指示条 = `Primary`。 +/// 环形与线性共用同一对：一根进度条两套配色口径就没人说得清哪个才是「进度」。 +pub(crate) const fn progress_roles() -> (Role, Role) { + (Role::SurfaceContainerHighest, Role::Primary) +} + +/// `linear()` 真正塞进样式闭包的两个颜色（单测断言的就是它，口径同 `StyleSpec`）。 +pub(crate) fn linear_colors(ui: &Ui) -> (iced::Color, iced::Color) { + let (track, active) = progress_roles(); + (ui.color(track), ui.color(active)) +} + +/// 环形进度的取色（与 [`linear_colors`] 同源）。 +pub(crate) fn circular_colors(ui: &Ui) -> (iced::Color, iced::Color) { + linear_colors(ui) +} + +/// 线性进度条（轨道 + 指示条，厚 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, active_color) = linear_colors(ui); + + 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_color, active_color) = circular_colors(ui); + let track = glyph(&geometry, ring_source(&geometry), track_color); + + // 0% 只画轨道（不画弧，也不画圆头小点）；100% 画整环（`A` 命令的首尾重合画不出整圆） + let active = if sweep < MIN_SWEEP_DEG { + None + } else if sweep >= FULL_SWEEP_DEG { + Some(glyph(&geometry, ring_source(&geometry), active_color)) + } else { + Some(glyph( + &geometry, + arc_source(&geometry, sweep, rotation), + active_color, + )) + }; + + 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!( + "" + ) +} + +/// 一段圆弧（`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!( + "" + ) +} + +/// 极角（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..fcf87ae --- /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 | 圆角 | **16**（规格卡 `rx=16`；官方 `CornerExtraSmall` 是 4，M229 换肤按规格卡） | `inkcat::metrics::SNACKBAR` | +//! | 14.2 | 容器色 | **`InverseSurface`**（高程 L3 是设计口头径，见下「不画阴影」） | [`Role::InverseSurface`] | +//! | 14.3 | 高 | 单行 **52**（规格卡 340×52；官方 48）/ 双行 **72**（+20） | [`SnackbarGeometry::height_for`] | +//! | 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, + state: Option, +} + +impl<'a, M> Snackbar<'a, M> { + /// 单行提示条（高 52，规格卡口径）。 + 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..7d74cf4 --- /dev/null +++ b/crates/app-iced/src/components/feedback/tests.rs @@ -0,0 +1,243 @@ +//! 纯函数级断言：几何对令牌、节奏对 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, Base, 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 bands; +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 / 宽度上限：规格卡 52 / 72 / 16，上限 600。 +#[test] +fn snackbar_heights_widths_and_radius_are_the_tokens() { + let geometry = SnackbarGeometry::of(&ui(SchemeFlavor::Light)); + // M229 换肤：高与圆角取规格卡（52 / 16），官方是 48 / `CornerExtraSmall(4)`。 + assert_eq!(geometry.height_for(1), 52.0, "规格卡 340×52"); + assert_eq!( + geometry.height_for(2), + 72.0, + "双行 = 单行 + 20（同官方 delta）" + ); + assert_eq!(geometry.radius, 16.0, "规格卡 rx=16（官方 4，登记差异）"); + 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); + // 期望值按**品牌色板**（= `Ui` 注入的那一份）：M229 复审 F1 之前这里用的是 + // `Scheme::baseline`，Ink 板上会得到偏蓝的遮罩（数值见 `DevDocs/artifacts/m229/README.md` §6）。 + let scheme = unlucky_design::color::BrandBoard::for_flavor(flavor).scheme(); + 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（品牌板）」" + ); + // F1 的回归门：不许回到 tone 派生的 baseline 上算。 + let baseline = Scheme::baseline(flavor); + assert_ne!( + expected, + to_iced( + baseline + .scrim() + .over(baseline.get(MaterialLayer::Canvas.surface_role())) + ), + "{flavor:?}：遮罩退回了 baseline（Ink 下会偏蓝）" + ); + 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, Base::CANVAS, 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/bands.rs b/crates/app-iced/src/components/feedback/tests/bands.rs new file mode 100644 index 0000000..12102aa --- /dev/null +++ b/crates/app-iced/src/components/feedback/tests/bands.rs @@ -0,0 +1,123 @@ +//! 探针**取带规则**的回归（M248 r1 复审 P2-1 / P2-2）——用合成图，不依赖真实截图。 +//! +//! ## 为什么必须用合成图 +//! +//! 真实渲染里轨道**永远占满宿主**，「轨道被裁短」这类几何回归在图上不会自然出现。 +//! 复审是手工把 after 图里 0% 那条轨道右半截涂回画布色才造出反例的（一次性动作）， +//! 而那一涂正好打中第一版的漏洞：阈值 200 时该行**直接不再被认成轨道行**， +//! `check_linear` 靠另一条带照样绿——「判据被放宽」在真实图上永远不露馅。 +//! 合成图把这个形状变成可复现夹具。 +//! +//! ## 两条用例各钉住什么 +//! +//! | 用例 | 钉住的取值区间 | 打红它的变异 | +//! |---|---|---| +//! | [`narrowed_track_is_still_a_band`] | `TRACK_MIN_RUN` ≤ 160（窄轨道必须仍成带），且 `TRACK_MIN_WIDTH` > 160（它必须过不了宽度判据） | ① 调用点换回计数判据 `bands(.., 200)`（窄轨道那条带消失 → `bands.len()` 变 1）；② `TRACK_MIN_WIDTH` 调到 ≤160（宽度判据失去区分力） | +//! | [`text_rows_are_never_track_bands`] | `TRACK_MIN_RUN` > 22（文字行最长连续段就是 22） | 阈值调到 ≤22（图注行会被数成轨道，正是第一版的假红） | +//! +//! **抓不住**：真实截图里轨道被裁/被折线的具体像素形态（那仍要复审涂图或用真实 probe）， +//! 也抓不住厚度那一条（厚度仍由真实截图的 `track::check` 判）。 + +use unlucky_design::color::{BrandBoard, Role}; +use unlucky_design::typography::Platform; + +use super::super::pixel::{band_width, rgb, Shot}; +use super::super::probe::track::{track_bands, TRACK_MIN_RUN, TRACK_MIN_WIDTH}; +use super::FAMILIES; +use crate::theme::Ui; + +/// 合成图的配色来源：用 Ink 板（深色）——轨道 `SurfaceContainerHighest` 与画布 `Surface` +/// 在这里是**两个不同的中性色**，正好复现「混色轴穿过中性文字」那一幕的坐标轴。 +fn strip_ui() -> Ui { + Ui::with_board(BrandBoard::Ink, Platform::Windows, FAMILIES) +} + +/// 一段横线：`y0..=y1` 行里前 `len` 个像素涂 `color`，其余留底色。 +fn strip( + width: usize, + height: usize, + rows: &[(usize, usize, usize)], + color: [u8; 3], + under: [u8; 3], +) -> Shot { + Shot::from_rows(width, height, |x, y| { + let hit = rows + .iter() + .any(|(top, bottom, len)| (*top..=*bottom).contains(&y) && x < *len); + if hit { + color + } else { + under + } + }) +} + +/// 复审反例的形态：**轨道比宿主窄一半**（160 = 320 宿主的一半）。 +/// +/// 阈值 200 的版本在这里会**只找到一条带**（窄的那条整行掉出判据）——这正是那条 p2 的漏判， +/// 所以 `bands.len() == 2` 是这条用例的主断言之一。 +#[test] +fn narrowed_track_is_still_a_band() { + let ui = strip_ui(); + let track = rgb(ui.color(Role::SurfaceContainerHighest)); + let surface = rgb(ui.color(Role::Surface)); + + // 360×20：y=5..8 是**被裁到 160px** 的轨道；y=12..15 是占满宿主的轨道。 + let shot = strip(360, 20, &[(5, 8, 160), (12, 15, 360)], track, surface); + + let bands = track_bands( + &shot, + ui.color(Role::SurfaceContainerHighest), + ui.color(Role::Surface), + ); + assert_eq!( + bands, + vec![(5, 8), (12, 15)], + "窄轨道也必须被认成一条带（TRACK_MIN_RUN={TRACK_MIN_RUN}；调大到 ≥160 时它会消失，\ + 于是 `check_linear` 只能看见另一条带、漏判——复审就是在这里抓到第一版的）" + ); + + let widths: Vec = bands + .iter() + .map(|band| { + band_width( + &shot, + *band, + ui.color(Role::SurfaceContainerHighest), + ui.color(Role::Surface), + ) + }) + .collect(); + assert_eq!(widths, vec![160, 360], "两条带的最宽连续段"); + assert!( + widths[0] < TRACK_MIN_WIDTH, + "窄轨道必须过不了宽度判据（TRACK_MIN_WIDTH={TRACK_MIN_WIDTH}），否则「轨道被裁短」\ + 这类回归会绿着过" + ); + assert!(widths[1] >= TRACK_MIN_WIDTH, "占满宿主的轨道必须过宽度判据"); +} + +/// 文字行永远不能进判据：图注行的最长连续段实测就是 **22px**（`after/gallery-progress-*`）。 +/// +/// 这条是「阈值别调得太小」的那一侧：阈值 ≤22 时，图注行会被数成轨道带， +/// 浅色板那次假红（`12.1：线性进度厚必须 4（实测 6 @ 行 63）`）就会回来。 +#[test] +fn text_rows_are_never_track_bands() { + let ui = strip_ui(); + let track = rgb(ui.color(Role::SurfaceContainerHighest)); + let surface = rgb(ui.color(Role::Surface)); + + // 6 行「文字」：每段 22px、段间隔 12px（字形与字距的粗略形态），整行铺满。 + let shot = Shot::from_rows(360, 6, |x, _y| if x % 34 < 22 { track } else { surface }); + + let bands = track_bands( + &shot, + ui.color(Role::SurfaceContainerHighest), + ui.color(Role::Surface), + ); + assert!( + bands.is_empty(), + "22px 的文字段不能算轨道行（TRACK_MIN_RUN={TRACK_MIN_RUN}；调到 ≤22 时这里会红，\ + 那正是浅色板假红 `实测 6 @ 行 63` 的来源），实测 {bands:?}" + ); +} 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..b32e7f0 --- /dev/null +++ b/crates/app-iced/src/components/feedback/tests/progress.rs @@ -0,0 +1,361 @@ +//! 进度两式的纯函数断言（`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::{BrandBoard, Role, Scheme, SchemeFlavor}; +use unlucky_design::shape::ShapeScale; +use unlucky_design::typography::Platform; + +use super::super::geometry::{phase_segments, CircularGeometry, LinearGeometry, PHASE_055}; +use super::super::keyframes::{KeyPoint, Keyframes}; +use super::super::progress::{ + circular_colors, layout_spans, linear_colors, portion_shares, progress_roles, Amount, Progress, +}; +use super::ui; +use crate::theme::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，给首值"); +} + +// ---- M248：进度轨道的角色语义与「可主题化」 --------------------------------- + +/// 轨道的配色判据**不是某个 hex**：两块出厂品牌板 + 一套自定义种子方案（`Scheme::from_seed`），轨道都必须解出 +/// 「本方案的容器面角色」，且三套互不相同。把取角色改成取死值（`Role::Surface`）或写死 +/// `SecondaryContainer`，这条都会红。 +/// +/// 抓不住什么：**像素**（角色对、图上却画错了）——那是 `super::super::probe` 的事； +/// 也抓不住「两个角色在令牌表里恰好同值」的情形，那条由这一个用例里的角色 pin 兜。 +#[test] +fn track_is_the_highest_container_step_and_follows_the_scheme() { + // 角色 pin：轨道 = 比画布高一档的容器面；指示条 = 强调色。 + // （A1 `LinearProgressIndicatorTokens.TrackColor` 是 `SecondaryContainer`，M248 按 + // 「轨道是背景尺、强调色只属于指示条」改口径，差异登记在 `geometry.rs` 的 12.2 行。） + assert_eq!( + progress_roles(), + (Role::SurfaceContainerHighest, Role::Primary), + "进度：轨道 SurfaceContainerHighest + 指示条 Primary" + ); + + // 第三套方案用**取色链的默认种子**（`DEFAULT_SEED`，天蓝）：design 的令牌，不是色值字面量。 + let themes = [ + ( + "ink", + Ui::with_board(BrandBoard::Ink, Platform::Windows, super::FAMILIES), + ), + ( + "silver", + Ui::with_board(BrandBoard::Silver, Platform::Windows, super::FAMILIES), + ), + ( + "custom", + Ui::from_scheme( + Scheme::from_seed(SchemeFlavor::Dark, unlucky_design::color::DEFAULT_SEED), + super::FAMILIES, + ), + ), + ]; + + let mut tracks = Vec::new(); + for (name, theme) in &themes { + let (track, active) = linear_colors(theme); + assert_eq!( + track, + theme.color(Role::SurfaceContainerHighest), + "{name}: 轨道 = 本方案的最高容器面" + ); + assert_ne!( + track, + theme.color(Role::Surface), + "{name}: 轨道退化成画布色了（取死值 Surface 的变异会打红这条）" + ); + assert_ne!( + track, + theme.color(Role::SecondaryContainer), + "{name}: 轨道又借回强调色族了" + ); + assert_eq!( + active, + theme.color(Role::Primary), + "{name}: 指示条 = Primary" + ); + assert_eq!( + circular_colors(theme), + (track, active), + "{name}: 环形取色与线性同源" + ); + tracks.push(track); + } + + assert_ne!(tracks[0], tracks[1], "Ink 与 Silver 的轨道必须不同色"); + assert_ne!( + tracks[0], tracks[2], + "换一套种子方案，轨道必须跟着变（可主题化的证据）" + ); +} 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..8e661a0 --- /dev/null +++ b/crates/app-iced/src/components/gallery/buttons.rs @@ -0,0 +1,176 @@ +//! 按钮家族的状态矩阵（D30：浅/深 × 五态）。 +//! +//! ## 矩阵形状 +//! +//! ```text +//! | enabled | hovered | pressed | focused | disabled | +//! filled | [btn] | [btn] | [btn] | [btn] | [btn] | +//! tonal | ... （下同） +//! elevated | +//! outlined | +//! text | +//! icon·filled | [ico] | ... +//! icon·tonal | +//! icon·outlined | ← M229 第四式（1px 环；此前与 plain 逐像素相同） +//! icon·plain | +//! ``` +//! +//! 45 个单元格共 5 列 × **9 行**（5 个文字变体 + **4 个图标变体**），一屏（1180×760）装不下， +//! 靠 `gallery/mod.rs` 的 scrollable 滚动；截图取的是**整窗**，所以首屏能看到前 8 行左右 +//! （最下面一行可能要滚动）。行序 = `Variant::ALL` 之后 `IconVariant::ALL`，`probe/rows.rs` +//! 的逐行表按同一顺序排。 +//! +//! ## 为什么每格都强制状态 +//! +//! 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::>(); + + 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::>(); + + 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：S 档高 40 · 圆角 full(20) · 内边距 20（带图标 16/20；M229 起按 ControlSize::pad_x）· 图标 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/disabledbase.rs b/crates/app-iced/src/components/gallery/disabledbase.rs new file mode 100644 index 0000000..f258f91 --- /dev/null +++ b/crates/app-iced/src/components/gallery/disabledbase.rs @@ -0,0 +1,210 @@ +//! 禁用态的**合成底**（M234）：同一批禁用控件摆在三种底上，一眼看出「叠的是哪一层」。 +//! +//! ## 这张图回答什么 +//! +//! M223 记的「CR 1.05、形丢失」是这么来的：`disabled.rs` 的入口收一个 `Role` 当合成底， +//! 而**所有调用点都传死 `Role::Surface`**——卡片（`SurfaceContainer`）与面板 +//! （`SurfaceContainerLow`）里的禁用控件于是把 10%（按钮族）/ 12%（面状控件族）那一层叠在 +//! **画布色**上，与它真正的底差一层。 +//! +//! 这里把三列**并排**摆出来，每列一块板、板底就是控件真踩的那层底： +//! +//! ```text +//! canvas Surface ← 页面底色 +//! card SurfaceContainer ← `surfaces::elevated::card` 的底（`elevated::BASE`） +//! panel SurfaceContainerLow ← Card 层（取景板 / 面板） +//! ``` +//! +//! 每列都是**同一族控件**：Filled/Outlined 禁用按钮、Filled 禁用字段、禁用开关与 chip、 +//! 禁用搜索条、禁用列表项、禁用滑块、禁用 tab。控件拿的都是这一列的 [`Base`]， +//! 所以列与列之间的差别只有「底」。 +//! +//! ## 判据（数值在 `probe/bases.rs`） +//! +//! 像素判据判的是**精确值**：卡列里的禁用按钮容器必须等于 `on-surface@10% 叠卡片底`， +//! 且**不等于**画布底那一档。注意量级：Ink/Silver 板上 `Surface` 与 `SurfaceContainer` +//! 只差个位数 RGB，10% 之后差 **≈1/255**——肉眼看不出来，所以这张图的用处是**取证**， +//! 不是「看出区别」。真判据在 `interaction::disabled::tests`（逐值）与 `probe/bases.rs`（像素）。 +//! +//! ```text +//! ULL_GALLERY_SECTION=disabledbase $EXE --software-renderer --screen=gallery \ +//! --screenshot out.png --screenshot-theme=light +//! ULL_GALLERY_SECTION=disabledbase ULL_GALLERY_SHOT=out.png \ +//! cargo test -p unlucky-app-iced gallery::probe +//! ``` + +use iced::widget::{column, container, row, text}; +use iced::{Background, Border, Element, Length, Padding}; + +use unlucky_design::color::Role; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; + +use crate::theme::Ui; + +use super::super::buttons::{self, Button}; +use super::super::inputs::{self, Field, SearchBar, Slider}; +use super::super::interaction::{self, Base, Interaction}; +use super::super::navigation::{self, ListItem, Tab, Tabs}; +use super::super::selection::{self, CheckValue, Checkbox, Chip, Radio, Switch}; +use super::{heading, DemoMessage}; + +/// 一列的底（**板画什么，控件就叠什么**）。 +const COLUMNS: [(&str, Base); 3] = [ + ("canvas · Surface", Base::CANVAS), + ( + "card · SurfaceContainer", + super::super::surfaces::elevated::BASE, + ), + ( + "panel · SurfaceContainerLow", + Base::of(Role::SurfaceContainerLow), + ), +]; + +/// 板宽：3 × 360 + 2 × 8 间距 = 1096 < 1180 − 2×24 页边距。 +const PLATE_WIDTH: f32 = 360.0; + +/// `#RRGGBB`（图上的色值要能直接和 probe 的期望值对上）。 +fn hex(color: iced::Color) -> String { + let channel = |v: f32| (v * 255.0).round() as u8; + format!( + "#{:02X}{:02X}{:02X}", + channel(color.r), + channel(color.g), + channel(color.b) + ) +} + +/// 整段（标题 + 三块并排的板）。 +pub(super) fn section<'a>(ui: &'a Ui) -> Element<'a, DemoMessage> { + let note = ui.style(TypeRole::BodySmall); + let columns = COLUMNS + .iter() + .copied() + .map(|(title, base)| plate(ui, title, base)) + .collect::>(); + + column![ + heading( + ui, + "disabled · 合成底 = 所在容器的底（M234）", + "10%（按钮族）/ 12%（面状控件族）/ 38%（内容）全部预合成成实色；\ + 三列控件相同，只有**脚下的底**不同", + ), + row(columns).spacing(ui.space(Space::X2)), + text( + "三列的控件完全相同，只有脚下的底不同。禁用容器保留 90% 的底差（10% 只叠 on-surface），所以列间差别 = 底差的九成（浅色 Silver 11/255、深色 Ink 6/255）。这张图是取证；判据在 `interaction::disabled::tests`（逐值）与 `gallery::probe` 的 disabledbase 段（精确像素）", + ) + .size(note.size_px) + .font(ui.font_of(note)) + .color(ui.color(Role::OnSurfaceVariant)), + ] + .spacing(ui.space(Space::X2)) + .into() +} + +/// 一块板：**底色就是这一列的 `base`**，控件全部把同一个 `base` 传进 `.base(..)`。 +/// +/// 板上写着这一列**算出来的**色值（同一入口：`disabled_button_colors` / `disabled_colors`）： +/// 三列只差 ≈1/255，肉眼判不了，图上的数字是给 reviewer 与 probe 对账用的。 +fn plate<'a>(ui: &'a Ui, title: &'a str, base: Base) -> Element<'a, DemoMessage> { + let caption = ui.style(TypeRole::BodySmall); + let label = text(title) + .size(caption.size_px) + .font(ui.font_of(caption)) + .color(ui.color(Role::OnSurface)); + let numbers = text(format!( + "底 {} · 禁用按钮(10%) {} · 禁用字段(12%) {}", + hex(ui.color(base.role())), + hex(interaction::disabled_button_colors(ui, base).0), + hex(interaction::disabled_colors(ui, base).0), + )) + .size(caption.size_px) + .font(ui.font_of(caption)) + .color(ui.color(Role::OnSurfaceVariant)); + + container( + column![ + column![label, numbers].spacing(ui.space(Space::X1)), + column_body(ui, base) + ] + .spacing(ui.space(Space::X2)), + ) + .width(Length::Fixed(PLATE_WIDTH)) + .padding(Padding::from(ui.space(Space::X2))) + .style(move |_theme| container::Style { + // 板底 = 这一列的 base；描边只为让 `canvas` 列也有边界（画布色与页面同色）。 + background: Some(Background::Color(ui.color(base.role()))), + border: Border { + color: ui.color(Role::OutlineVariant), + width: crate::theme::STROKE_PX, + radius: ui.radius_dp(unlucky_design::shape::ShapeScale::Medium), + }, + ..container::Style::default() + }) + .into() +} + +/// 一列控件：**同族不同底**，每条都显式传 `base`。 +fn column_body<'a>(ui: &'a Ui, base: Base) -> Element<'a, DemoMessage> { + let gap = ui.space(Space::X2); + column![ + row![ + buttons::filled(ui, Button::disabled("保存").base(base)), + buttons::outlined(ui, Button::disabled("取消").base(base)), + ] + .spacing(gap), + inputs::text_field( + ui, + Field::new("") + .label("名称") + .placeholder("禁用字段") + .state(Interaction::Disabled) + .base(base), + |_| DemoMessage::Pressed("field"), + ), + row![ + selection::checkbox( + ui, + Checkbox::disabled("勾选", CheckValue::Unchecked).base(base), + ), + selection::radio(ui, Radio::disabled("单选", false).base(base)), + selection::switch(ui, Switch::disabled("开关", false).base(base)), + selection::chip( + ui, + Chip::filter("标签", false, DemoMessage::Pressed("chip")) + .disabled() + .base(base), + ), + ] + .spacing(gap), + inputs::search_bar( + ui, + SearchBar::new("") + .placeholder("搜索") + .state(Interaction::Disabled) + .base(base), + |_| DemoMessage::Pressed("search"), + ), + navigation::list_item( + ui, + ListItem::new("列表项", DemoMessage::Pressed("item")) + .disabled() + .base(base), + ), + inputs::slider( + Slider::new(ui, 0.45) + .state(Interaction::Disabled) + .base(base), + ), + navigation::tabs( + ui, + Tabs::primary() + .tab(Tab::new("标签页", DemoMessage::Pressed("tab")).state(Interaction::Disabled),) + .base(base), + ), + ] + .spacing(gap) + .into() +} 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..207618f --- /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/§15：Linear 厚 4 圆角 full · Circular 40/4 · Snackbar 52/72 圆角 16 上限宽 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> { + 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, + content: impl Into>, +) -> 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%（轨道 SurfaceContainerHighest · 指示条 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> { + 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 · 双行 72（52+20）+ 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..e73baec --- /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> { + 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> { + 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::>(); + 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) · SurfaceContainerHighest（M229 r2 抬档：与 filled 字段同底）· 图标可视边 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::>(); + + 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..7a8ac2f --- /dev/null +++ b/crates/app-iced/src/components/gallery/mod.rs @@ -0,0 +1,395 @@ +//! `--screen=gallery` 的壳：**视觉验收 harness**（D30 / D39 §5），不是产品页面。 +//! +//! ## 它是什么、不是什么 +//! +//! - 是：**状态矩阵的取景框**。每个家族在自己的 `gallery/.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 起） +//! +//! **七段**（buttons / sizes / divider / selection / inputs / feedback / navigation）拼成一列、 +//! 外面套 `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` / `sizes` / `divider` / `selection` / `inputs` / `feedback` / `navigation`。 +//! 语义是「**不构建**没被选中的段」（不是构建后隐藏）：`column` 里根本不 push 它， +//! 于是该家族的 `view` 一行都不跑。未识别的值**回落 `all`** 并在 stderr 打一行提示 +//! （静默回落会让人拿错图还以为拍的是那一段）。 +//! +//! 为什么用环境变量而不是 `--screen=gallery:`：`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 disabledbase; +mod feedback; +mod inputs; +mod navigation; +#[cfg(test)] +mod probe; +#[cfg(test)] +mod scan; +mod selection; +mod sizes; + +/// 段落过滤的环境变量名（语义见模块文档「段落过滤」）。 +pub const SECTION_ENV: &str = "ULL_GALLERY_SECTION"; + +/// 段落开关：**构建**哪几段（`false` = 这一段连 `view` 都不跑）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +struct Sections { + buttons: bool, + disabledbase: bool, + sizes: bool, + divider: bool, + selection: bool, + inputs: bool, + feedback: bool, + navigation: bool, +} + +impl Sections { + /// 七段全渲染（默认）。 + const ALL: Self = Self { + buttons: true, + disabledbase: true, + sizes: true, + divider: true, + selection: true, + inputs: true, + feedback: true, + navigation: true, + }; + + /// 只有一段。 + fn only(name: &str) -> Option { + let mut sections = Self { + buttons: false, + disabledbase: false, + sizes: false, + divider: false, + selection: false, + inputs: false, + feedback: false, + navigation: false, + }; + match name { + "buttons" => sections.buttons = true, + "disabledbase" => sections.disabledbase = true, + "sizes" => sections.sizes = 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|disabledbase|sizes|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.disabledbase, "disabledbase"), + (self.sizes, "sizes"), + (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 · board={} · flavor={} · 1180×760 @100% DPI · \ + focus 与 pressed 同为 10%（令牌口径，图上一样是对的）", + ui.board().name(), + 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.disabledbase { + sections = sections.push(disabledbase::section(ui)); + } + if picked.sizes { + sections = sections.push(sizes::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::(ui), + label("list (左缩进 16)"), + divider::list::(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> { + 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::>>(); + 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::>(); + + 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..fb74e7e --- /dev/null +++ b/crates/app-iced/src/components/gallery/probe.rs @@ -0,0 +1,400 @@ +//! 渲染层几何断言：**对着真截图量像素**（M68 的教训：纯函数返回对，图可能是错的）。 +//! +//! `buttons::tests` 只能证明「几何结构体里的数字是 40/20/24」——M68 的药丸正是这样：单测全绿、 +//! 图上是 88×32（容器被 `center_x(Length::Fill)` 覆盖）。唯一能抓住这类错误的是**真渲染的像素**。 +//! CI 没有桌面，所以这里不自己开窗：先用 `--screen=gallery --screenshot` 出真窗截图，本测试读 +//! 那张 PNG 量几何、与令牌逐项比对。**没给图就跳过并大声说出来**（不静默通过）。 +//! +//! 复现命令（在 worktree 根目录；**必须同时给 `ULL_GALLERY_SECTION`**，只支持 `buttons` / `divider`）： +//! +//! ```text +//! EXE=${CARGO_TARGET_DIR:-target}/debug/unlucky-launcher-iced # 本仓纪律：一树一 target +//! OUT=${CARGO_TARGET_DIR:-target}/m229-probe && mkdir -p "$OUT" +//! +//! # ① 按钮矩阵（实心块 / 药丸 / 字形 / 逐行禁用色 / Outlined 环） +//! ULL_GALLERY_SECTION=buttons $EXE --software-renderer --screen=gallery \ +//! --screenshot "$OUT/buttons-light.png" --screenshot-theme=light +//! ULL_GALLERY_SECTION=buttons ULL_GALLERY_SHOT="$OUT/buttons-light.png" \ +//! cargo test -p unlucky-app-iced gallery::probe +//! +//! # ② 分隔线（`buttons` 段里没画线，必须单独出一张） +//! ULL_GALLERY_SECTION=divider $EXE --software-renderer --screen=gallery \ +//! --screenshot "$OUT/divider-light.png" --screenshot-theme=light +//! ULL_GALLERY_SECTION=divider ULL_GALLERY_SHOT="$OUT/divider-light.png" \ +//! cargo test -p unlucky-app-iced gallery::probe +//! ``` +//! +//! `all` **不支持**：gallery 整页比 1180×760 的视口高，分隔线段与按钮矩阵不可能同屏，而 sizes 段的 +//! 实心块又会被「按钮 40 高」的判据量到 —— 所以按段出图、按段断言，`all` 会被明确拒绝（见测试体）。 +//! +//! 量什么（每条对一个已发生过的错误）：实心块高 **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::{self, Base}; + +use super::scan::{matches, nearer, rgb, Shot}; + +mod bases; +mod rows; + +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 目录）。 +/// +/// 只把 `ULL_GALLERY_SHOT` 读成路径；**「这张图属于哪一段」由测试体开头那条 assert 管** +/// （`buttons` / `divider` 之外一律失败），这里不做校验——图与判据的配对是测试的前提条件， +/// 放在测试里读起来才连贯（复审 r3 P2-1：这段文档曾写「此处不满足就失败」，而 assert 早已搬走）。 +fn shot_path() -> Option { + 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); + + // 只认两种 sheet（`all` 与整页图都拒绝，理由见 [`shot_path`] 与模块文档）： + // `buttons` = 按钮矩阵的主判据；`divider` = 分隔线的两条判据（1px / 墨量覆盖率）。 + let section = std::env::var("ULL_GALLERY_SECTION") + .unwrap_or_default() + .trim() + .to_ascii_lowercase(); + assert!( + section == "buttons" || section == "divider" || section == "disabledbase", + "这份 probe 只支持 `ULL_GALLERY_SECTION=buttons`（按钮矩阵）/ `divider`（分隔线）/ `disabledbase`（禁用态合成底）；当前 {section:?}。`all` 不行：整页比视口高，分隔线段与按钮矩阵不可能同屏。" + ); + // 分隔线那段是**独立出口**：`divider` 段的 sheet 里没有按钮矩阵，判据也不同。 + if section == "divider" { + check_divider(&shot, &ui); + return; + } + // 禁用态合成底（M234）：三块板各按自己的底合成，判据在 `probe/bases.rs`。 + if section == "disabledbase" { + bases::check(&shot, &ui, flavor); + return; + } + + // ---- 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() + ); + + // **只判「按钮矩阵那一段」**：矩阵区由「第一块文字按钮（宽 > 60、高 40）」的顶边起、往下 9 行 + // + 8px。`buttons` 段的 sheet 里没有后续段，所以这条过滤是防御性的（`all` 现在被拒；将来若允许 + // 拼接多段，它保证判据只落在矩阵上，不会被别段的 chip/卡片撞到）。 + let matrix_top = primary + .iter() + .filter(|b| b.area() >= 800 && b.width() > 60 && (39..=41).contains(&b.height())) + .map(|b| b.top) + .min() + .expect("没找到文字按钮的实心块（矩阵不在画面里？）"); + let matrix_bottom = matrix_top + rows::ROW_COUNT * rows::ROW_STEP + 8; + + let mut label_button = None; + for bbox in &primary { + // 字形（OnPrimary）会把实心块割出小碎片，只判「成块的」（40×40 = 1600） + if bbox.area() < 800 { + continue; + } + // 矩阵之外（后续段）的实心块不在这条判据的量程里。 + if bbox.top >= matrix_bottom { + 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 = 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 的字形"); + + // ---- 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, Base::CANVAS); + assert!( + shot.bbox_of(rgb(disabled_container)) + .iter() + .any(|b| b.width() > 60), + "没找到禁用态实心按钮（12b 1.8：容器 = on-surface@10%）" + ); + + // 禁用态与描边环是**按矩阵行**判的，逐行表与判据搬去了 `probe/rows.rs`（守 400 行硬线）。 + rows::assert_matrix_rows(&shot, &ui, label_button.top, label_button.left); + + // 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） + 禁用容器 (on-surface@10%，按钮族) 命中 · 逐行禁用内容断言 {} 行通过 + 字形墨迹 {}px（24 盒应 16~26）", + flavor, + label_button.width(), + true_height, + top_inset, + primary.len(), + rows::ROW_COUNT, + glyph_width + ); +} + +/// `ULL_GALLERY_SECTION=divider` 的两条判据：分隔线 2 条（各摊 1~2 行）与单条墨量覆盖率 ≈1.0。 +/// +/// 单独成函数：`divider` 段的 sheet 没有按钮矩阵，走不到主流程的按钮判据；而主流程也不需要 +/// 分隔线（`buttons` 段的 sheet 里根本没画线，断言只会误报）。 +fn check_divider(shot: &Shot, ui: &Ui) { + let surface = rgb(ui.color(Role::Surface)); + let mut runs = 0usize; + 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）" + ); + eprintln!("[probe] OK section=divider：分隔线 {runs} 行、单条覆盖率 {coverage:.2}"); +} diff --git a/crates/app-iced/src/components/gallery/probe/bases.rs b/crates/app-iced/src/components/gallery/probe/bases.rs new file mode 100644 index 0000000..bbd1823 --- /dev/null +++ b/crates/app-iced/src/components/gallery/probe/bases.rs @@ -0,0 +1,222 @@ +//! `ULL_GALLERY_SECTION=disabledbase` 的像素判据：**禁用态叠的是哪一层底**（M234）。 +//! +//! ## 为什么必须用「精确匹配」而不是扫描工具的 `matches`（±10） +//! +//! Ink / Silver 板上 `Surface` 与 `SurfaceContainer` 只差个位数 RGB，10% 之后差 **≈1/255**： +//! `scan::matches` 的 ±10 容差会把「叠在画布上」与「叠在卡片上」判成同一个颜色—— +//! 那样这条判据就永远绿。所以本文件自己数**逐位相等**的像素（[`count_exact`]）， +//! 并且只数**板内**区域，避开页面底色。 +//! +//! ## 量什么 +//! +//! 1. 卡列 / 面板列里：禁用按钮容器（按钮族 10%）与禁用字段容器（面状族 12%）的像素值 +//! = 各自「@10%/12% 叠**该列板底**」；**不许**出现「叠画布底」那一档； +//! 2. 画布列（卡列左侧、同样的纵向范围）里反过来：出现画布档、且不是卡/面板档； +//! 3. 三档的期望值两两不同（哪一对相等，说明 `Base` 被丢了或两族 α 合流了）。 +//! +//! ## 抓得住 / 抓不住 +//! +//! - 抓得住：调用点把底传错（叠画布）或没传（默认 `Base::CANVAS`）——卡列里会出现画布档的像素 +//! 而缺卡片档；两族 α 合流、入口内部写死 `Role::Surface`，同样在这里红。 +//! - 抓不住：① 容器**自己**的画法（板底 vs 卡组件的 `BASE` 是否一致——那条由 +//! `surfaces::elevated::tests` 的「卡底必须是 SurfaceContainer」守）； +//! ② 页面里的真实卡片（pages/ 的调用点尚未接 `.base(..)`，见报告「没验的部分」）； +//! ③ GPU(wgpu) 档：本判据读的是 tiny-skia(`--software-renderer`) 出的图； +//! ④ 差 <1/255 的第三层底（例如 `SurfaceContainer` 与 `SurfaceContainerHigh` 的 10%）—— +//! 那种情况本文件会退化成「两档相等」，第 3 条断言会红，**不会静默放过**。 + +use unlucky_design::color::Role; + +use super::super::scan::{rgb, Shot}; +use crate::app::components::interaction::{self, Base}; +use crate::app::components::surfaces; +use crate::theme::Ui; + +/// 板子的最小尺寸（判据只认「一整列」，不许把某个控件误当成板）。 +const MIN_PLATE_W: usize = 300; +const MIN_PLATE_H: usize = 260; +/// 禁用按钮容器在板内的最少像素（Filled 药丸 40 高 × ≥58 宽，扣掉字形与圆角）。 +const MIN_BUTTON_PX: usize = 300; +/// 禁用字段容器的最少像素（板宽 ~336 × 56，扣掉标签与图标）。 +const MIN_FIELD_PX: usize = 3000; +/// 「正确档位 : 错误档位」的最小倍数。 +/// +/// 为什么不干脆要求「错误档位 = 0 px」：**抗锯齿会造出中间色**——板底与控件容器之间那一圈 +/// 1px 过渡像素会顺路撞上「另一档」的精确值（实测卡片列里 226/226/227 有 58 px，全是边缘）。 +/// 真实回归的量级完全不同（整颗按钮 ≈3000 px、整块字段 ≈18000 px），所以判据写成**倍数**： +/// 正确档位必须比错误档位多一个数量级。 +const STRAY_RATIO: usize = 10; + +/// 逐位相等的像素计数器（`scan::matches` 的 ±10 容差在这里不够用，见模块文档）。 +fn count_exact(shot: &Shot, color: [u8; 3], x0: usize, x1: usize, y0: usize, y1: usize) -> usize { + (y0..y1.min(shot.height)) + .map(|y| { + (x0..x1.min(shot.width)) + .filter(|x| shot.at(*x, y) == color) + .count() + }) + .sum() +} + +/// 一块板（`left..right × top..bottom`，闭区间；`x1`/`y1` 是开区间上界）。 +type Rect = (usize, usize, usize, usize); + +/// 按**逐位相等**的颜色切出竖列：每列 = 一段连续且够宽的 x，y 取该段内的最小/最大行。 +/// +/// 为什么不用 `scan::bbox_of`（±10 容差）：本板的三档底（`Surface` / `SurfaceContainer` / +/// `SurfaceContainerLow`）两两只差 5~11 个 RGB 单位，落在容差里会被并成一块 +/// （实测把卡片列与面板列判成同一块）。 +fn exact_columns(shot: &Shot, color: [u8; 3]) -> Vec { + let mut columns = Vec::new(); + let mut current: Option<(usize, usize, usize, usize)> = None; + for x in 0..shot.width { + let rows: Vec = (0..shot.height) + .filter(|y| shot.at(x, *y) == color) + .collect(); + match (&mut current, rows.first()) { + (None, Some(top)) => { + current = Some((x, x + 1, *top, rows[rows.len() - 1] + 1)); + } + (Some(col), Some(top)) => { + col.1 = x + 1; + col.2 = col.2.min(*top); + col.3 = col.3.max(rows[rows.len() - 1] + 1); + } + (Some(col), None) => { + if col.1 - col.0 >= MIN_PLATE_W && col.3 - col.2 >= MIN_PLATE_H { + columns.push(*col); + } + current = None; + } + (None, None) => {} + } + } + if let Some(col) = current { + if col.1 - col.0 >= MIN_PLATE_W && col.3 - col.2 >= MIN_PLATE_H { + columns.push(col); + } + } + columns +} + +fn find_plate(shot: &Shot, role: Role, ui: &Ui, name: &str) -> Rect { + let color = rgb(ui.color(role)); + let mut columns = exact_columns(shot, color); + assert_eq!( + columns.len(), + 1, + "{name} 列（{role:?} 底，{color:?}）应当恰好是 1 列，实测 {}： 板子尺寸判据 MIN {MIN_PLATE_W}×{MIN_PLATE_H}", + columns.len() + ); + columns.remove(0) +} + +/// 判据入口（`probe.rs` 的 `disabledbase` 分支调它）。 +pub(super) fn check(shot: &Shot, ui: &Ui, flavor: unlucky_design::color::SchemeFlavor) { + let card = Base::of(Role::SurfaceContainer); + let panel = Base::of(Role::SurfaceContainerLow); + + let card_rect = find_plate(shot, Role::SurfaceContainer, ui, "card"); + let panel_rect = find_plate(shot, Role::SurfaceContainerLow, ui, "panel"); + // 画布列：三列等宽等距（`disabledbase::PLATE_WIDTH` 固定 360、间距 8），所以它 = + // 卡列左侧同样宽的一列。画布板的底与页面同色（`Surface`），**没法**靠颜色切出来。 + let step = panel_rect.0 - card_rect.0; + assert!( + step > MIN_PLATE_W, + "两列间距 {step} 不合理（列宽 {MIN_PLATE_W} 起）—— 布局变了，画布列的镜像推算不再成立" + ); + let canvas_rect = (0, card_rect.0, card_rect.2, card_rect.3); + let canvas_left = card_rect.0.saturating_sub(step); + + let button = |base: Base| rgb(interaction::disabled_button_colors(ui, base).0); + let field = |base: Base| rgb(interaction::disabled_colors(ui, base).0); + + // 三档必须两两不同（哪一对相等就说明底被丢了 / 两族 α 合流了） + let (canvas_button, canvas_field) = (button(Base::CANVAS), field(Base::CANVAS)); + let (card_button, card_field) = (button(card), field(card)); + let (panel_button, panel_field) = (button(panel), field(panel)); + assert_ne!( + canvas_button, card_button, + "{flavor:?}：画布底与卡片底算出来的按钮容器相同 —— 底被丢了" + ); + assert_ne!( + canvas_field, card_field, + "{flavor:?}：画布底与卡片底算出来的字段容器相同" + ); + assert_ne!( + card_button, panel_button, + "{flavor:?}：卡片底与面板底必须可分" + ); + assert_ne!( + card_field, panel_field, + "{flavor:?}：卡片底与面板底必须可分" + ); + assert_eq!( + surfaces::elevated::BASE, + card, + "卡片列用的底就该是 `surfaces::elevated::BASE`（容器导出的那个常量）" + ); + + for (rect, base, wanted_button, wanted_field, name) in [ + (card_rect, card, card_button, card_field, "card"), + (panel_rect, panel, panel_button, panel_field, "panel"), + ] { + let (x0, x1, y0, y1) = rect; + // 两个计数**分开命名**：它们是不同量测对象，拿字段数去比按钮 stray 会让断言恒绿 + // （M234 复审 P2-1 的现场）。 + let button_hits = count_exact(shot, wanted_button, x0, x1, y0, y1); + assert!( + button_hits >= MIN_BUTTON_PX, + "{name} 列里「叠 {:?}」的禁用按钮容器只有 {button_hits} px（应 ≥{MIN_BUTTON_PX}）： 这一列的禁用控件没把真实父底传下去", + base.role() + ); + let field_hits = count_exact(shot, wanted_field, x0, x1, y0, y1); + assert!( + field_hits >= MIN_FIELD_PX, + "{name} 列里「叠 {:?}」的禁用字段容器只有 {field_hits} px（应 ≥{MIN_FIELD_PX}）", + base.role() + ); + + // 反向 ①：**按钮**档 —— 这一列里「叠画布」的按钮容器不许和「叠该列底」的比肩。 + // 这条抓的是「只修了一半」：同列里一部分按钮仍走画布底时，正确档与错误档的像素量接近。 + let stray_button = count_exact(shot, canvas_button, x0, x1, y0, y1); + assert!( + button_hits > stray_button * STRAY_RATIO, + "{name} 列里「叠 {:?}」的禁用按钮容器 {button_hits} px，而「叠画布」的**按钮容器** 有 {stray_button} px（要求前者 ≥ 后者 ×{STRAY_RATIO}）—— 这一列的按钮仍在按 Role::Surface 合成", + base.role() + ); + // 反向 ②：**字段**档（同理，各用各的计数） + let stray_field = count_exact(shot, canvas_field, x0, x1, y0, y1); + assert!( + field_hits > stray_field * STRAY_RATIO, + "{name} 列里「叠 {:?}」的禁用字段容器 {field_hits} px，而「叠画布」的**字段容器** 有 {stray_field} px（要求前者 ≥ 后者 ×{STRAY_RATIO}）—— 这一列的字段仍在按 Role::Surface 合成", + base.role() + ); + assert!( + base.role() != Role::Surface, + "{name} 列不该是画布底（判据自己写错了）" + ); + } + + // 画布列：反过来必须出现画布档 + let (_, cx1, cy0, cy1) = canvas_rect; + let cx0 = canvas_left; + let canvas_hits = count_exact(shot, canvas_button, cx0, cx1, cy0, cy1); + assert!( + canvas_hits >= MIN_BUTTON_PX, + "画布列里没有「叠画布」的禁用按钮容器 —— 对照组不成立" + ); + let canvas_card_hits = count_exact(shot, card_button, cx0, cx1, cy0, cy1); + assert!( + canvas_hits > canvas_card_hits * STRAY_RATIO, + "画布列里「叠画布」的禁用按钮容器 {canvas_hits} px，而「叠卡片底」的有 {canvas_card_hits} px —— 画布列的控件被传了卡片底" + ); + + eprintln!( + "[probe] OK section=disabledbase flavor={flavor:?}：\ + 画布列 x<{} · 卡片列左缘 x={}..{} · 面板列左缘 x={}..{}；\ + 按钮容器色 canvas {:?}（{canvas_hits} px）⇒ 三列各按自己的底合成\ + （两个数字都是列左缘横坐标，不是像素计数）", + card_rect.0, card_rect.0, card_rect.1, panel_rect.0, panel_rect.1, canvas_button + ); +} diff --git a/crates/app-iced/src/components/gallery/probe/rows.rs b/crates/app-iced/src/components/gallery/probe/rows.rs new file mode 100644 index 0000000..7472a14 --- /dev/null +++ b/crates/app-iced/src/components/gallery/probe/rows.rs @@ -0,0 +1,92 @@ +//! 矩阵**逐行**判据：禁用态内容色（12b 1.8）× 9 行 + 图标按钮第四式（Outlined）的 1px 环。 +//! +//! 从 `probe.rs` 纯搬移（M229 复审 P2：加第 9 行与环断言后 `probe.rs` 409 行，超 400 硬线）。 +//! 判据一行未改，只有入口从「行内代码」变成 [`assert_matrix_rows`]。 + +use unlucky_design::color::Role; + +use super::super::scan::{rgb, Shot}; +use crate::app::components::interaction; +use crate::app::components::interaction::Base; +use crate::theme::Ui; + +/// 矩阵行距（40 高按钮 + 8 间距）。 +pub(super) const ROW_STEP: usize = 48; +/// 行内扫描高度（可见 40 + 上下各 2 的余量）。 +const ROW_HEIGHT: usize = 44; +/// 矩阵行数（5 个文字变体 + 4 个图标变体）：probe 的汇总日志用它。 +pub(super) const ROW_COUNT: usize = 9; + +/// 逐行断言：①每一行的禁用内容色（A1 逐变体不同）②Outlined 图标行有环、Plain 行没有。 +pub(super) fn assert_matrix_rows(shot: &Shot, ui: &Ui, label_top: usize, label_left: usize) { + // 行序 = `gallery/buttons.rs` 先 `Variant::ALL`（5 行）再 `IconVariant::ALL`（**4 行**，M229 起 + // outlined 是第四式）：共 **9 行**。`on_container` 必须与 `assemble::content_color` 一致 + // ——图标按钮的 filled/tonal 有容器（`fill.is_some()`），outlined/plain 没有。 + let rows: [(usize, Role, bool, &str); 9] = [ + (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, true, "icon·filled"), // A1：IconButton 全是 OnSurface + (6, Role::OnSurface, true, "icon·tonal"), + (7, Role::OnSurface, false, "icon·outlined"), + (8, Role::OnSurface, false, "icon·plain"), + ]; + let column_from = shot.width * 2 / 3; // 矩阵最右列 = disabled 列 + for (index, role, on_container, name) in rows { + let y0 = label_top + index * ROW_STEP; + let y1 = y0 + ROW_HEIGHT; + // **与实现同源**：按钮族的内容色一律走 `disabled_button_content`（38% 叠在 10% 底上）。 + // 用面状控件族的 12% 底会让断言比实现宽一档，差的 1/255 会放跑「容器对内容错」。 + let ink = interaction::disabled_button_content(ui, Base::CANVAS, role, on_container); + let count = shot.count_in(rgb(ink), column_from, shot.width, y0, y1); + // 阈值 **30**：最窄的一行是只有 4 个字符的 `text` 变体（实测 38 px 墨迹，M229 复审后 + // 按钮内距 24→20 让标签左移，余量只剩 2 px）。角色接错时会掉到个位数甚至 0。 + assert!( + count > 30, + "{name} 行的禁用内容（{role:?}@38%）在 disabled 列里只有 {count} px —— 这一行没走 A1 的禁用角色" + ); + // 反向判据（不靠阈值）：**满档**内容色不许比 38% 的还多——那样说明这一行没降透明度。 + let full = shot.count_in(rgb(ui.color(role)), column_from, shot.width, y0, y1); + assert!( + full < count, + "{name} 行里满档 {role:?} 有 {full} px、38% 只有 {count} px：这一行的禁用透明度没生效" + ); + } + + // ---- M229 复审 P1-1：Outlined 图标按钮必须有 1px 环，Plain 必须没有 ---- + // + // 只有渲染层能证：`icon()` 曾把 `StyleSpec.stroke` 写死 0，Outlined 与 Plain 逐像素相同。 + // 纯函数那条在 `buttons::tests::only_the_outlined_icon_variant_draws_a_ring`（证明「传了 1.0」）， + // 这条证明「画出来了」。 + // **只能扫「环带」，且只能按「有没有墨」判**：1px 环在软渲染里是 Outline 叠画布的抗锯齿 + // 混色（实测左缘 `(110,124,110)`，而 Outline 本体是 `(123,138,123)`）——按颜色匹配会漏， + // 而且 `Outline` 与「字形压在画布上的边缘」在容差内几乎同色（扫整格会把 Plain 行数成 16 px 假环）。 + // + // 环带的判据是**几何 + 墨量**：40×40 圆按钮的左缘在 x = left…left+4（半径 20 的弧垂直中线处 + // 贴左），而 24×24 字形从 left+8 才开始 —— Plain 行这一段实测是纯画布色 0 px。 + let surface = rgb(ui.color(Role::Surface)); + let is_ink = |pixel: [u8; 3]| pixel.iter().zip(surface).any(|(a, b)| a.abs_diff(b) > 8); + let band_ink = |y0: usize| { + let mut n = 0; + for y in (y0 + 14)..(y0 + 26) { + for x in label_left..(label_left + 4) { + if is_ink(shot.at(x, y)) { + n += 1; + } + } + } + n + }; + let outlined = band_ink(label_top + 7 * ROW_STEP); + let plain = band_ink(label_top + 8 * ROW_STEP); + assert!( + outlined >= 4, + "Outlined 图标按钮这一行左缘没有环墨（{outlined} px）：`icon()` 的 stroke 又被写死了？" + ); + assert_eq!( + plain, 0, + "Plain 图标按钮这一行左缘出现了 {plain} px 环墨（Plain 不该有描边）" + ); +} 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 { + 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 { + 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 { + const MARGIN: usize = 3; + let mut ink: Option = 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/gallery/sizes.rs b/crates/app-iced/src/components/gallery/sizes.rs new file mode 100644 index 0000000..c8ff24c --- /dev/null +++ b/crates/app-iced/src/components/gallery/sizes.rs @@ -0,0 +1,123 @@ +//! 尺寸档矩阵：**按钮 XS~XL 五档** + **FAB 四态**（规格卡 `BUTTONS / XS - XL` 与 +//! `FAB / SMALL - DEFAULT - MEDIUM - EXTENDED`）。 +//! +//! ## 为什么单开一段（而不是塞进 `buttons`） +//! +//! `buttons` 段是「五式 × 五态 + 图标四式」的 40 格矩阵，一屏（1180×760）本来就贴着折叠线； +//! 五档梯子（最高 136）与四态 FAB（最宽 160）塞进去会被压到屏幕外——那样出的图**看不见**， +//! 等于没拍。所以按「一段 = 一个能一屏判完的问题」拆开： +//! +//! ```text +//! ULL_GALLERY_SECTION=sizes # 本段：尺寸梯子 + FAB 四态 +//! ``` +//! +//! ## 图上要能判什么 +//! +//! 1. 五档高度递增、圆角全部是**半高**（药丸），标签字号跟着档位升（14/14/16/24/32）； +//! 2. FAB 四态：40/56/80 三个方态 + 160×56 扩展态（图标 + 标签）； +//! 3. 配色：FAB 一律 `PrimaryContainer` / `OnPrimaryContainer`（规格卡上四颗都是淡绿底深绿字）。 +//! +//! 判不了：状态层（FAB 在这一段是静息态，五态矩阵在 `buttons` 段的按钮上验）、以及动效。 + +use iced::widget::{column, row}; +use iced::{Element, Length}; + +use unlucky_design::color::Role; +use unlucky_design::icons::IconKind; +use unlucky_design::inkcat::size::{ControlSize, FabSize}; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; + +use crate::theme::Ui; + +use super::super::buttons::{self, fab, Button, Fab}; +use super::super::interaction::Interaction; +use super::{heading, DemoMessage}; + +/// 整段（标题 + 五档梯子 + 四态 FAB + 图例）。 +pub(super) fn section<'a>(ui: &'a Ui) -> Element<'a, DemoMessage> { + let legend = ui.style(TypeRole::BodySmall); + + let ladder = row(ControlSize::ALL + .iter() + .map(|size| sized(ui, *size)) + .collect::>()) + .spacing(ui.space(Space::X4)) + .align_y(iced::Alignment::Center); + + let fabs = row(FabSize::ALL + .iter() + .map(|size| fab_cell(ui, *size)) + .collect::>()) + .spacing(ui.space(Space::X4)) + .align_y(iced::Alignment::Center); + + column![ + heading( + ui, + "sizes · buttons xs~xl + fab small~extended", + "规格卡：按钮 32/40/56/96/136（圆角 = 半高，标签 14/14/16/24/32 字重 500）；\ + FAB 40/r12 · 56/r16 · 80/r20 · 160×56/r16（图标 20/26/34/24，扩展态内距 28、间距 8）" + ), + labelled(ui, "buttons xs - xl", ladder.into()), + labelled(ui, "fab small - extended", fabs.into()), + iced::widget::text( + "图例：产品页的按钮只用 S 档（40，= M3 control_height）；M/L/XL 留给空态主行动与展示型入口。\ + FAB 四颗都是静息态，配色 PrimaryContainer / OnPrimaryContainer。", + ) + .size(legend.size_px) + .font(ui.font_of(legend)) + .color(ui.color(Role::OnSurfaceVariant)), + ] + .spacing(ui.space(Space::X2)) + .into() +} + +/// 一档 Filled 按钮（标签是档位名的大写：XS / S / M / L / XL。 +/// +/// **必须大写**：小写的 `l` 在 Inter/Segoe 里就是一根竖线，XL 会读成「x|」——第一版出图就是这么错的。 +fn sized<'a>(ui: &'a Ui, size: ControlSize) -> Element<'a, DemoMessage> { + let label: &'static str = match size { + ControlSize::Xs => "XS", + ControlSize::S => "S", + ControlSize::M => "M", + ControlSize::L => "L", + ControlSize::Xl => "XL", + }; + buttons::filled( + ui, + Button::new(label, DemoMessage::Pressed("size")).size(size), + ) +} + +/// 一颗 FAB（扩展态带标签；静息态强制，避免光标位置影响出图）。 +fn fab_cell<'a>(ui: &'a Ui, size: FabSize) -> Element<'a, DemoMessage> { + let spec = if matches!(size, FabSize::Extended) { + Fab::extended(IconKind::Plus, "New", DemoMessage::Pressed("fab")) + } else { + Fab::new(IconKind::Plus, DemoMessage::Pressed("fab")) + } + .size(size) + .state(Interaction::Enabled); + fab(ui, spec) +} + +/// 一行「小标题 + 内容」。 +fn labelled<'a>( + ui: &'a Ui, + label: &'a str, + content: Element<'a, DemoMessage>, +) -> Element<'a, DemoMessage> { + let style = ui.style(TypeRole::LabelSmall); + column![ + iced::widget::text(label) + .size(style.size_px) + .font(ui.font_of(style)) + .color(ui.color(Role::OnSurfaceVariant)), + iced::widget::container(content) + .width(Length::Fill) + .padding(iced::Padding::from([ui.space(Space::X2), 0.0])), + ] + .spacing(ui.space(Space::X1)) + .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) { + 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 { + 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 { + 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::() == 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..b8a4eec --- /dev/null +++ b/crates/app-iced/src/components/inputs/field.rs @@ -0,0 +1,363 @@ +//! 文本框（`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）。 +//! +//! ## 回车与失焦（P18 / M252）：只有回车是真的事件 +//! +//! `iced_widget-0.14.2/src/text_input.rs` 的 builder 一共这几条（**逐条从源码抄的**，别凭记忆）： +//! +//! | 方法 | 行 | 产物 | +//! |---|---|---| +//! | `on_input` / `on_input_maybe` | 172 / 184 | 每次改动后发一条消息 | +//! | `on_submit` / `on_submit_maybe` | 194 / 201 | **焦点在框内时**按回车发**一条**消息（`:1049-1053`：一个 `KeyPressed` 事件只 `publish` 一次；不在焦点内的回车走不到这里） | +//! | `on_paste` / `on_paste_maybe` | 208 / 218 | 粘贴 | +//! | ~~`on_unfocus`~~ | **整个文件 0 命中** | 失焦**没有**消息通道：`State::unfocus()`（`:1524`）与 `Focusable for State`（`:1563`）只改控件内部状态，不发消息 | +//! +//! 所以本封装的取舍是：**把有的事件透出去**（[`Field::on_submit`]），失焦继续用代理近似 +//! （回车 + 点到别的控件），**不为它去 fork iced**。`on_submit` 是**可选**的：不调 +//! [`Field::on_submit`] 时 `text_input` 的 `on_submit` 保持空（`on_submit_maybe(None)`）， +//! 回车**什么消息都不发**——全站既有调用点因此逐位不变（回归见 `tests.rs`）。 + +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::icons::IconKind; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; + +use crate::icons; +use crate::theme::Ui; + +use super::super::interaction::{Base, Interaction}; + +#[cfg(test)] +use super::super::interaction; +use super::super::layout; +use super::geometry::FieldGeometry; + +mod paint; +use paint::palette; + +/// 两式容器（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）。 +/// +/// `M` 是**消息类型**，只被 [`Field::on_submit`] 用到：不给提交回调时它跟 `on_input` 的消息同型， +/// 调用点照旧写 `Field::new(value)…`（类型由 `text_field` 的 `on_input` 一并推出，不用标注）。 +pub struct Field<'a, M> { + variant: FieldVariant, + value: &'a str, + label: Option<&'a str>, + placeholder: &'a str, + supporting: Option<&'a str>, + leading: Option, + trailing: Option, + error: bool, + state: Option, + width: Length, + secure: bool, + /// 脚下那一层的底（M234，禁用态合成用）。 + base: Base, + /// 回车要发的那条消息（P18；`None` = 回车什么都不发生，既有调用点全是这一档）。 + on_submit: Option M + 'a>>, +} + +impl<'a, M> Field<'a, M> { + /// 一个 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, + base: Base::CANVAS, + on_submit: None, + } + } + + /// **告诉字段它踩在什么底上**（M234）：禁用态的 12% 容器 / 描边与 38% 内容都叠在这个底上。 + /// + /// 放进卡片/面板里必须给（卡片 = `surfaces::elevated::BASE`）；不给就按画布合成， + /// 禁用字段会与容器底脱节（M223 的「形丢失」）。 + pub fn base(mut self, base: impl Into) -> Self { + self.base = base.into(); + self + } + + /// 选式（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 + } + + /// **回车提交**（P18 / M252）：焦点在框内时按回车，发这一条消息。 + /// + /// 不调就是「回车什么都不发生」——这是默认档，也是全站既有调用点的现状。 + /// 禁用态（[`Field::state`] = `Disabled`）里回车**不发**（与 `on_input` 同一条规矩： + /// 点不动的框也不该能提交）。 + pub fn on_submit(mut self, on_submit: impl Fn() -> M + 'a) -> Self { + self.on_submit = Some(Box::new(on_submit)); + self + } + + /// 回车那条消息（`None` = 没接 [`Field::on_submit`]，或这个状态不能交互）。 + /// + /// **唯一的读取口**：`text_field` 只从这里取，于是「接没接」「点不点得动」与「发不发」 + /// 是同一个事实——禁用态里回车不提交（与 `on_input` 同一条规矩）。 + fn submit_message(&self, state: Interaction) -> Option { + if state.is_disabled() { + return None; + } + self.on_submit.as_ref().map(|on_submit| on_submit()) + } +} + +/// 一个文本框（Filled / Outlined 由 [`Field::variant`] 选）。 +/// +/// 受控：值由外部持有，输入经 `on_input` 回传；`state` 强制成 `Disabled` 时输入被摘掉 +/// （`on_input_maybe(None)`），所以禁用字段真的点不动，不只是变灰。 +/// 回车（P18）：只在 [`Field::on_submit`] 被调过时才接（`on_submit_maybe`），没接就是 +/// 「回车什么都不发生」。 +pub fn text_field<'a, M: Clone + 'a>( + ui: &'a Ui, + field: Field<'a, M>, + 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.base, field.variant, state, field.error); + + // 提交消息只在**可交互**时接（禁用规则住在 `Field::submit_message` 里，可单测）。 + let submit = field.submit_message(state); + + 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) + }) + .on_submit_maybe(submit) + .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::(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::(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/paint.rs b/crates/app-iced/src/components/inputs/field/paint.rs new file mode 100644 index 0000000..436d693 --- /dev/null +++ b/crates/app-iced/src/components/inputs/field/paint.rs @@ -0,0 +1,125 @@ +//! 文本框的颜色求值（`research/12b` §9.4 / §9.7 / §9.8 的落点）。 +//! +//! M234 纯搬移：本文件原来是 `inputs/field.rs` 的 `Palette` + `palette()`（`field.rs` 已顶到 +//! 398 行，加 `.base(..)` 之前必须腾地方）。搬移只做了一件事以外的零改动——`palette()` 多收 +//! 一个 [`Base`]（禁用态的合成底，M234），其余角色映射一字未改。 + +use iced::Color; + +use unlucky_design::color::Role; + +use crate::theme::Ui; + +use super::super::super::interaction::{self, Base, Interaction}; +use super::super::geometry::FieldGeometry; +use super::FieldVariant; + +/// 一个字段在某一态下的全套颜色（9.4 / 9.7 / 9.8 的落点）。 +#[derive(Debug, Clone, Copy, PartialEq)] +pub(super) struct Palette { + /// 容器底色；`None` = 透明（Outlined）。 + pub(super) fill: Option, + /// 描边/指示线色。 + pub(super) line: Color, + /// 描边/指示线宽（1 或 2）。 + pub(super) stroke: f32, + /// 标签（`BodySmall`）。 + pub(super) label: Color, + /// 输入文本。 + pub(super) input: Color, + /// 前后图标。 + pub(super) icon: Color, + /// 辅助文本。 + pub(super) supporting: Color, + /// 占位文本。 + pub(super) placeholder: Color, +} + +/// 解析某一态的颜色（**唯一**做角色映射的地方）。 +/// +/// `base` 是字段**脚下那一层的底**（M234）：禁用态的 12% 容器与 38% 内容都叠在它上面 +/// （Filled 容器 / Outlined 描边 / 全部标签与文本）。调用点给真实父底，不写死 `Role::Surface`。 +pub(super) fn palette( + ui: &Ui, + base: Base, + 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, base).0; + let ink = interaction::disabled_content_over_role( + ui, + base, + 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), + } +} 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..9964492 --- /dev/null +++ b/crates/app-iced/src/components/inputs/field/tests.rs @@ -0,0 +1,308 @@ +//! field 的单测（从 `field.rs` 拆出：单文件 ≤400 行，AGENTS.md §3-1）。 + +use super::*; +use unlucky_design::color::Role; +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<'_, u8>, 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, + Base::CANVAS, + 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, + Base::CANVAS, + FieldVariant::Outlined, + Interaction::Hovered, + false, + ); + assert_eq!(hover.line, ui.color(Role::OnSurface)); + assert_eq!(hover.stroke, 1.0); + + let focus = palette( + &ui, + Base::CANVAS, + 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, + Base::CANVAS, + 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, + Base::CANVAS, + 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, Base::CANVAS).0; + + let filled = palette( + &ui, + Base::CANVAS, + FieldVariant::Filled, + Interaction::Disabled, + false, + ); + assert_eq!(filled.fill, Some(container)); + assert_eq!( + filled.input, + interaction::disabled_content_over_role(&ui, Base::CANVAS, Role::OnSurface, true) + ); + + let outlined = palette( + &ui, + Base::CANVAS, + 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, Base::CANVAS, 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, + Base::CANVAS, + FieldVariant::Filled, + Interaction::Enabled, + false + ) + .fill, + Some(ui.color(Role::SurfaceContainerHighest)), + "FilledTextFieldTokens.ContainerColor" + ); + assert_eq!(FieldGeometry::of(&ui, true, None).shape.dp(), 4.0); +} + +/// 本文件所在模块的源码（源码结构断言用，`pages::layout::source` 的同一条纪律）。 +const FIELD_SOURCE: &str = include_str!("../field.rs"); + +/// P18 / M252 判据 ④-a：`on_submit` 是**可选**的——不接就没有提交消息。 +/// +/// 抓得住：`Field::new(..)` 这条链（其余构造器全接上）给出 `None` ⇒ `text_field` 交给 +/// `text_input` 的是 `on_submit_maybe(None)`，回车**什么消息都不发**（全站既有调用点因此逐位 +/// 不变）；接了之后取到的正是那条消息（回调没被构造器吞掉）。 +/// 抓不住：回车键真的走到控件（iced 的键路径在 `Widget::update` 里，`Element` 没有内省接口， +/// 见 `pages::layout::source` 的模块文档；本仓也造不出 `iced::Renderer` 的测试替身）。 +#[test] +fn submit_is_opt_in() { + let plain: Field<'_, u8> = Field::new("实例一") + .variant(FieldVariant::Outlined) + .label("名称") + .placeholder("请输入") + .supporting("辅助说明") + .leading(IconKind::Folder) + .trailing(IconKind::Close) + .error() + .state(Interaction::Enabled) + .secure(false) + .base(Base::CANVAS); + assert_eq!( + plain.submit_message(Interaction::Enabled), + None, + "没调 `.on_submit` ⇒ 回车不发消息（既有调用点的行为）" + ); + + let wired: Field<'_, u8> = Field::new("实例一").on_submit(|| 7_u8); + assert_eq!( + wired.submit_message(Interaction::Enabled), + Some(7), + "接上的回调要被原样取出来" + ); + // 禁用态里回车不提交（与 `on_input` 同一条规矩：点不动的框也不该能提交） + assert_eq!( + wired.submit_message(Interaction::Disabled), + None, + "禁用字段不许回车提交" + ); +} + +/// 回归（T27 反例 ①）：`text_field` 必须把 `Field` 上的提交回调**转发**给 `text_input`。 +/// +/// iced 的 `Element` 没有内省接口，所以这条守的是**源码结构**（本仓既有同一条纪律，见 +/// `pages::layout::source` 的模块文档）。三条断言合起来才等于「转发」：有一**行代码**在调 +/// `on_submit_maybe`、它的实参不是写死的 `None`、消息确实来自 `Field::submit_message`（唯一读取口）。 +/// +/// **判据是「代码行」，不是「文本里还有那个字符串」**（M252 r1 的 P1-1）：断言走 +/// `source::code_line`，注释先被剥掉。所以下面这些改法都会红： +/// - 删掉 `.on_submit_maybe(..)` 那一行； +/// - 把它**注释掉**（`//` 行注释，或 `/*` 独占一行的块注释）； +/// - 改成 `.on_submit_maybe(None)` ——**即使同时**把 `let submit` 写成 `let _submit` 把 rustc 的 +/// unused-variable 兜底也绕掉（复审实测过：那样测试与 lint 两条线会同时静默）。 +/// +/// 抓不住：`text_input` 内部的键处理（iced 的实现）；等价重构（把值先赋给别的名字再传）—— +/// 那要同时改 needle，见 `pages::layout::source::code` 的边界一节。 +#[test] +fn text_field_forwards_the_submit_callback() { + let body = crate::pages::layout::source::function_body(FIELD_SOURCE, "pub fn text_field"); + let call = + crate::pages::layout::source::code_line(body, ".on_submit_maybe(").unwrap_or_else(|| { + panic!( + "`text_field` 里没有一行**代码**在调 `on_submit_maybe`（注释掉也算没有）：\n{body}" + ) + }); + assert!( + !call.contains("None"), + "提交消息被写死成 `None`（回车什么都不发，且功能静默失效）：{call}" + ); + assert!( + crate::pages::layout::source::code_text(body).contains("submit_message("), + "提交消息必须从 `Field::submit_message()` 取（唯一读取口；注释里写不算），实际函数体：\n{body}" + ); +} + +/// 回归（T27 反例 ②）：全站**只有那两处**（存档改名 / 强调色）接 `Field::on_submit`。 +/// +/// 为什么要扫源码：`text_field` 是全站共用控件，加了一个可选参数之后最容易出的错是 +/// **顺手把别的调用点也接上**——那会让一个「回车本来什么都不做」的输入框开始提交。 +/// 这条不靠「我看了一遍所有调用点」：白名单对不上就红；新增一处接线必须来这里登记， +/// 这份摩擦是故意的。 +/// +/// 抓得住：任何一处**新增/删除/注释掉**接在构建链上的 `.on_submit(..)`（本仓的链一律一行一条； +/// 注释先被 [`scan`] 剥掉，所以 `/*` 独占一行的块注释也算删除）。 +/// 抓不住：写在别处的同名文本（注释/字符串里的例子）、写成同一行的接线，也不管那两处接的 +/// 消息对不对（由 `pages` 侧各自的用例钉）。 +#[test] +fn submit_is_wired_only_at_the_two_call_sites() { + let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("src"); + let mut wired = Vec::new(); + scan(&root, &root, &mut wired); + wired.sort(); + assert_eq!( + wired, + vec![ + "pages/appearance/section/accent.rs".to_owned(), + "pages/instances/saves/rows.rs".to_owned(), + ], + "`Field::on_submit` 的调用点白名单变了（新接线要在这里登记）" + ); +} + +/// 递归找 `dir` 下**有一行代码以 `.on_submit(` 开头**的 `.rs`，记下相对 `root` 的路径（`/` 分隔）。 +/// +/// 谓词与三处接线守卫同一个（`source::has_code_line`）：注释与字符串里出现的 `.on_submit(` +/// 例子不算接线。代价是**写成同一行的接线扫不到**——本仓的构建链一律一行一条。 +/// +/// **测试文件跳过**（[`is_test_path`]）：守卫自己的 fixture 里有 `.on_submit(` 的样本（本文件、 +/// `pages/layout/source/code/tests.rs`），那不是调用点；测试也不会去接生产 UI。 +fn scan(root: &std::path::Path, dir: &std::path::Path, found: &mut Vec) { + let Ok(entries) = std::fs::read_dir(dir) else { + return; + }; + for entry in entries.flatten() { + let path = entry.path(); + if path.is_dir() { + scan(root, &path, found); + } else if path.extension().is_some_and(|ext| ext == "rs") && !is_test_path(&path) { + let Ok(text) = std::fs::read_to_string(&path) else { + continue; + }; + if crate::pages::layout::source::has_code_line(&text, ".on_submit(") { + let rel = path.strip_prefix(root).unwrap_or(&path); + found.push(rel.to_string_lossy().replace('\\', "/")); + } + } + } +} + +/// 这个路径是不是**测试模块**的文件：任一组件叫 `tests` / `tests.rs`，或文件名以 `_tests.rs` 收尾。 +/// +/// 本仓的测试文件就这几种形状（`*/tests.rs`、`*/tests/*.rs`、`*_tests.rs`），全部由 +/// `#[cfg(test)]` 或 `tests/` 目标挂载；生产文件的 inline `mod tests` 不在这里判（那些文件本身 +/// 也可能是真调用点，例如 `section/accent.rs`）。 +fn is_test_path(path: &std::path::Path) -> bool { + path.components().any(|component| { + let name = component.as_os_str().to_string_lossy(); + name == "tests" || name == "tests.rs" || name.ends_with("_tests.rs") + }) +} 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) -> 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..488521c --- /dev/null +++ b/crates/app-iced/src/components/inputs/menu.rs @@ -0,0 +1,367 @@ +//! 菜单（`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 为准。 +//! +//! 阴影不是所有用法都要：被放进**滚动视口**（会被裁切）的菜单要用 [`Menu::flat`]—— +//! CPU 后端画阴影时绕过裁切掩码，阴影会漏到视口外压暗下面的内容（M238，理由与实证见 +//! `menu/shadow.rs` 的 `flat` 文档）。 +//! +//! ## 分组分隔线 +//! +//! 复用 [`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}; + +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, Base, Interaction}; +use super::super::layout; +use super::geometry::MenuGeometry; + +mod shadow; + +use shadow::panel_shadow; + +/// 菜单里的一项。 +#[derive(Debug, Clone)] +pub struct MenuItem<'a, M> { + label: &'a str, + leading: Option, + trailing: Option, + on_press: Option, + selected: bool, + state: Option, +} + +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>, + width: Length, + shadow: bool, +} + +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, + shadow: true, + } + } + + /// 追加一项。 + 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, + /// 文本色。 + ink: Color, + /// 图标色（前置槽位；A1 是 `OnSecondaryContainer`）。 + icon: Color, + /// 圆角档位（选中指示器 8）。 + shape: ShapeScale, +} + +/// 解析一项的颜色：选中优先，其余按五态叠状态层（`interaction::overlay_color`）。 +fn item_palette(ui: &Ui, base: Base, state: Interaction, selected: bool) -> ItemPalette { + if state.is_disabled() { + // 禁用：内容 38%，叠在**菜单面板的底**上（项本身透明，透出来的就是面板色） + let ink = interaction::disabled_content_over_role(ui, base, 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 { + // 状态层叠在**菜单容器色**上（`PANEL_BASE` = SurfaceContainer），得到不透明结果（D27） + fill: interaction::overlay_color(ui, state, Role::OnSurface, base.role()), + ink: ui.color(Role::OnSurface), + icon: ui.color(Role::OnSecondaryContainer), + shape: ShapeScale::Small, + } +} + +/// 菜单弹出层的底（**面板画这个色，项就叠在它上面**）。 +/// +/// 8.2 的 `MenuTokens.ContainerColor = SurfaceContainer`：面板用 `ui.color(PANEL_BASE.role())` 画底， +/// 项的禁用态（38% 内容）与状态层拿同一个 [`Base`] 合成——两边同源，改色不会只改一半（M234）。 +pub const PANEL_BASE: Base = Base::of(Role::SurfaceContainer); + +/// 菜单弹出层（`SurfaceContainer` + L2 阴影；[`Menu::flat`] 时无阴影）。 +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 = panel_shadow(ui, elevation.shadow(), menu.shadow); + let panel = ui.color(PANEL_BASE.role()); + 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, PANEL_BASE, item, geometry), + // 分组分隔线：复用 `divider::full`（一像素线 + OutlineVariant），不自己画 + Entry::Divider => divider::full::(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, + ..container::Style::default() + }) + .into() +} + +/// 一行菜单项（用 `button` 承载命中与四态，几何与颜色自绘）。 +fn item_row<'a, M: Clone + 'a>( + ui: &'a Ui, + base: Base, + 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, + base, + 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::(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::(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, base, 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/shadow.rs b/crates/app-iced/src/components/inputs/menu/shadow.rs new file mode 100644 index 0000000..c84bbff --- /dev/null +++ b/crates/app-iced/src/components/inputs/menu/shadow.rs @@ -0,0 +1,54 @@ +//! 菜单「要不要画 L2 阴影」（M238）。 +//! +//! 从 `menu.rs` 拆出来只为守 400 行硬线（`components::gate::every_source_file_stays_under_the_line_limit`）： +//! 那边加完「内联列表口径」正好 400 行、零余量。搬移的是**新增**的两小块，没有改动既有逻辑。 + +use iced::{Color, Shadow, Vector}; + +use unlucky_design::color::Role; +use unlucky_design::elevation::ShadowSpec; + +use crate::theme::Ui; + +use super::Menu; + +impl<'a, M> Menu<'a, M> { + /// **内联列表口径**：不画 L2 阴影（容器色 / 圆角 / 项几何照旧）。 + /// + /// 用在「菜单被放进**会被裁切的容器**（滚动视口）」的场合——下载页的加载器版本列表就是 + /// 这一种：它是面板里的一串版本，不是浮在页面上的弹出层。 + /// + /// 为什么必须在这里让步而不是「让它裁掉」：`iced_tiny_skia` 0.14 画 quad 阴影时用 + /// `pixmap.draw_pixmap(.., mask: None)`（`iced_tiny_skia/src/engine.rs:136-143`），**绕过** + /// 了 `clip_mask` ⇒ 阴影照画到视口之外，压暗下面钉死区的实例名（M238 实测：浅色画面布 + /// `(249,249,250)` 被压成 `(231,231,232)`，−7.2%）。`iced_wgpu` 那条路走整层的 scissor + /// （`iced_wgpu/src/quad.rs:96-101`）⇒ 同一棵树在 GPU / CPU 两个后端上**画出来的不一样**。 + /// 不画阴影让两边一致，也把「浮层」语义收回到真正浮起来的地方。 + /// + /// 层级观感：`Component::Menu.spec().elevation` 仍是 **L2**（令牌表不动），真实浮层 + /// （gallery / 将来的下拉）照旧带阴影；只有「内联列表」这一种用法放弃阴影，靠 + /// `SurfaceContainer` 底色 + 4 圆角与画布区分（L1 卡片 → L2 菜单这条阶梯不被削平）。 + pub fn flat(mut self) -> Self { + self.shadow = false; + self + } +} + +/// 面板阴影：`elevated` 为假（[`Menu::flat`]）时给 `Shadow::default()`——**不是**把 α 调小， +/// 而是让 tiny-skia 的 `shadow.color.a > 0.0` 一判就直接跳过整块阴影绘制。 +/// +/// 单独抽出来是为了让「内联列表不画阴影」这条可断言：`Element` 没有几何/样式内省， +/// 单测只能钉这个纯函数（见 `menu/tests.rs`）。 +pub(super) fn panel_shadow(ui: &Ui, spec: ShadowSpec, elevated: bool) -> Shadow { + if !elevated { + return Shadow::default(); + } + Shadow { + color: Color { + a: spec.alpha, + ..ui.color(Role::Shadow) + }, + offset: Vector::new(0.0, spec.offset_y_px), + blur_radius: spec.blur_px, + } +} 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..84c0f33 --- /dev/null +++ b/crates/app-iced/src/components/inputs/menu/tests.rs @@ -0,0 +1,148 @@ +//! 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, PANEL_BASE, 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, PANEL_BASE, 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, PANEL_BASE, Interaction::Disabled, true); + assert_eq!(disabled.fill, None, "禁用项不留满档选中底色"); + assert_eq!( + disabled.ink, + interaction::disabled_content_over_role(&ui, PANEL_BASE, 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, PANEL_BASE, Interaction::Enabled, false); + assert_eq!(rest.fill, None, "静息不叠色（菜单底色透出来）"); + for state in [ + Interaction::Hovered, + Interaction::Pressed, + Interaction::Focused, + ] { + let fill = item_palette(&ui, PANEL_BASE, 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); + } +} + +/// M238：`flat()`（内联列表口径）**整块阴影不画**，不是「把 α 调小」。 +/// +/// 抓得住：有人把 `flat` 实现成「α × 0.5」或只改 blur（`Shadow{ alpha>0, blur=0 }` 在 tiny-skia 里 +/// 仍会走阴影分支），以及有人把 `menu()` 里那个 `panel_shadow(.., menu.shadow)` 的第三参写死成 +/// `true`（那样 flat 菜单又带上阴影、漏回视口外）。 +/// 抓不住：阴影**画出来**的效果（`Element` 没有样式内省）；这条只钉决策函数， +/// 画出来的证据是 736 那张像素图（`tests/options_shot/compact.rs`）。 +#[test] +fn flat_menus_skip_the_shadow_instead_of_toning_it_down() { + let ui = ui(SchemeFlavor::Light); + let spec = Elevation::Level2.shadow(); + + let elevated = panel_shadow(&ui, spec, true); + assert_eq!(elevated.blur_radius, 6.0); + assert_eq!((elevated.offset.x, elevated.offset.y), (0.0, 2.0)); + assert_eq!(elevated.color.a, 0.14, "浮层：令牌给的 α 原样上身"); + + let flat = panel_shadow(&ui, spec, false); + assert_eq!( + (flat.color.a, flat.blur_radius), + (0.0, 0.0), + "内联列表：α 与 blur 都归零（tiny-skia 见 α = 0 直接跳过整块阴影，不是淡一点）" + ); +} 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..9b14b4e --- /dev/null +++ b/crates/app-iced/src/components/inputs/mod.rs @@ -0,0 +1,45 @@ +//! **输入类家族**（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` 模块文档）。 +//! +//! 回车提交（P18）也是命名参数：`Field::new(value).on_submit(|| Msg::Commit)`。**不接就没有** +//! ——`Field` 的 `M` 由 `text_field` 的 `on_input` 推出，既有调用点一个都不用改。 + +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, +} + +/// 一张图里某颜色的连通块外接框（闭区间）。 +#[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 { + 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 { + 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 = None; + let mut last: Option = 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 { + 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 = 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 = (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..d774c71 --- /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::SurfaceContainerHighest)); + 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::>(); + 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(÷r_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 = 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..bfa15ee --- /dev/null +++ b/crates/app-iced/src/components/inputs/search.rs @@ -0,0 +1,374 @@ +//! 搜索（`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 | 容器色 / 高程 | **`SurfaceContainerHighest`** + **L0**（token 写 L3，默认值是 L0，按观感取 L0） | `Role::SurfaceContainerHighest` | +//! | 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, Base, 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, + state: Option, + width: Length, + /// 脚下那一层的底（M234，禁用态合成用）。 + base: Base, +} + +impl<'a> SearchBar<'a> { + /// 一条收起态搜索条（默认占位文案由页面给，组件内不拼中文）。 + pub fn new(value: &'a str) -> Self { + Self { + value, + placeholder: "", + trailing: Some(IconKind::Filter), + state: None, + width: Length::Fill, + base: Base::CANVAS, + } + } + + /// 占位文案。 + 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 + } + + /// **告诉药丸它踩在什么底上**（M234）：禁用态那 12% 的容器叠在这个底上。 + /// + /// 药丸自己的容器色是 `SurfaceContainerHighest`，但**禁用它不画那个色**——禁用画的是 + /// 「12% 叠父底」，所以这里要的是父底（卡片 = `surfaces::elevated::BASE`），不是它自己。 + pub fn base(mut self, base: impl Into) -> Self { + self.base = base.into(); + self + } +} + +/// 搜索条内的一行内容（bar 与 view 头部共用，保证「展开时头部不跳」——20.6）。 +#[allow(clippy::too_many_arguments)] +fn bar_content<'a, M: Clone + 'a>( + ui: &'a Ui, + base: Base, + value: &'a str, + placeholder: &'a str, + trailing: Option, + 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, base, 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::(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::(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 高、药丸、`SurfaceContainerHighest`、无可见阴影）。 +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() { + // 禁用：12% 叠在**药丸脚下的底**上（不是药丸自己的 SurfaceContainerHighest） + interaction::disabled_colors(ui, bar.base).0 + } else { + // 规格卡里搜索药丸与 filled 字段是**同一个底**（`SurfaceContainerHighest`）： + // M229 r1 用的是 `High`，比 filled 字段低一档，两块并排时能看出色差（复审 F2 裁决抬档）。 + let role = Role::SurfaceContainerHighest; + 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.base, + 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> { + // 展开面板**不跟着药丸抬档**：它是浮层（菜单语言，`SurfaceContainerHigh`）， + // 规格卡只画了收起的药丸。两块不同档是层级差，不是漏改（复审 F2 只裁药丸）。 + let panel_role = Role::SurfaceContainerHigh; + let panel = ui.color(panel_role); + 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, + Base::of(panel_role), + 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..c986bf2 --- /dev/null +++ b/crates/app-iced/src/components/inputs/slider.rs @@ -0,0 +1,392 @@ +//! 滑块（`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`] | +//! +//! **Pixel 级偏离 #9（M229 r3，塔裁决不改实现）**：禁用**激活轨**沿用 M3 的 `DisabledActiveTrack` **38%** +//! （规格卡只定义了面状控件族的 12%；两者是两个族，不是同一档的两个名字，取证见 artifacts README §6）。 +//! +//! ## 为什么必须自绘 +//! +//! 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 crate::theme::Ui; + +use super::super::interaction::{Base, Interaction, Tracker}; +use super::geometry::{SliderGeometry, HANDLE_HEIGHT, STOP_GAP, STOP_SIZE}; + +mod paint; +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, + on_change: Option M + 'a>>, + forced: Option, + /// 脚下那一层的底（M234，禁用态合成用）。 + base: Base, +} + +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, + base: Base::CANVAS, + } + } + + /// 离散值：`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 + } + + /// **告诉滑块它踩在什么底上**（M234）：禁用态的 12% 未激活轨与 38% 内容叠在这个底上。 + /// + /// 放进卡片/面板里必须给（卡片 = `surfaces::elevated::BASE`）。 + pub fn base(mut self, base: impl Into) -> Self { + self.base = base.into(); + self + } + + /// 当前比例（量化后）。 + fn value(&self) -> f32 { + quantize(self.fraction, self.steps) + } + + /// 禁用与否：没有回调就是禁用（与按钮 `on_press: Option` 同一口径）。 + 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 for Slider<'a, M> +where + M: Clone, + Renderer: iced::advanced::Renderer, +{ + fn size(&self) -> Size { + Size { + width: Length::Fill, + height: Length::Fixed(SliderGeometry::of(self.ui).height), + } + } + + fn tag(&self) -> tree::Tag { + tree::Tag::of::() + } + + 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::(); + if state.tracker.set_enabled(enabled) { + shell.request_redraw(); + } + + let mut target: Option = 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::().tracker.state()); + let disabled = state.is_disabled(); + let colors = paint::colors(ui, self.base, state, geometry.handle); + let (active_color, inactive_color, handle_color, handle_width) = ( + colors.active, + colors.inactive, + colors.handle, + colors.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 = 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::().dragging { + return mouse::Interaction::Grabbing; + } + if cursor.is_over(layout.bounds()) { + mouse::Interaction::Grab + } else { + mouse::Interaction::None + } + } +} + +impl<'a, M, Theme, Renderer> From> 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/paint.rs b/crates/app-iced/src/components/inputs/slider/paint.rs new file mode 100644 index 0000000..6d38fae --- /dev/null +++ b/crates/app-iced/src/components/inputs/slider/paint.rs @@ -0,0 +1,55 @@ +//! 滑块的颜色求值（M234 从 `slider.rs` 的 `draw` 里搬出来，顺手收一个 [`Base`]）。 +//! +//! 搬出来的两个理由：① `slider.rs` 已顶到 399 行，加 `.base(..)` 之前必须腾地方； +//! ② 禁用态那三笔颜色原来在 `draw` 里写死 `Role::Surface` 当合成底（M234 的病灶）， +//! 搬进纯函数后可以被单测直接钉住「叠在哪个底上」。 + +use iced::Color; + +use unlucky_design::color::Role; + +use crate::theme::Ui; + +use super::super::super::interaction::{self, Base, Interaction}; +use super::super::geometry::HANDLE_WIDTH_ACTIVE; + +/// 滑块一笔要的三个颜色 + handle 宽。 +#[derive(Debug, Clone, Copy, PartialEq)] +pub(super) struct Colors { + /// 激活段（左侧已走部分）。 + pub(super) active: Color, + /// 未激活段。 + pub(super) inactive: Color, + /// handle（4×44 竖条）。 + pub(super) handle: Color, + /// handle 宽（focus / pressed 收窄）。 + pub(super) handle_width: f32, +} + +/// 五态 → 三笔颜色（`HANDLE_WIDTH_ACTIVE` 只在 focus/pressed 用）。 +/// +/// 禁用（11.6）：激活段与 handle `OnSurface`@38%、未激活轨 @12%，三者都叠在 `base` 上 +/// ——`base` 是滑块**脚下那一层**（卡片 = `surfaces::elevated::BASE`），不是恒定的画布色。 +pub(super) fn colors(ui: &Ui, base: Base, state: Interaction, handle: f32) -> Colors { + if state.is_disabled() { + return Colors { + active: interaction::disabled_content_over_role(ui, base, Role::OnSurface, false), + inactive: interaction::disabled_colors(ui, base).0, + handle: interaction::disabled_content_over_role(ui, base, Role::OnSurface, false), + handle_width: handle, + }; + } + // 状态层只叠在 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, + _ => handle, + }; + Colors { + active: ui.color(Role::Primary), + inactive: ui.color(Role::SecondaryContainer), + handle: handle_color, + handle_width, + } +} 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) -> 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/base.rs b/crates/app-iced/src/components/interaction/base.rs new file mode 100644 index 0000000..81cfd2f --- /dev/null +++ b/crates/app-iced/src/components/interaction/base.rs @@ -0,0 +1,83 @@ +//! 禁用态的**底**：控件脚下那一层容器实际画出来的底色（M234）。 +//! +//! ## 为什么不是一个 `Role::Surface` +//! +//! 禁用态的容器（按钮 10% / 面状控件 12%）与内容（38%）都要**预先合成成不透明色** +//! （D27：GPU/CPU 两档逐像素一致，所以不许把 α 交给渲染器混合）。合成必须知道「叠在什么上」， +//! 而这个「什么」是**宿主容器**的属性，不是控件的属性： +//! +//! ```text +//! 画布（Surface） ← 页面底色 +//! └ 卡片（SurfaceContainer） ← `surfaces::elevated::card` +//! └ 面板（SurfaceContainerLow）← 取景板 / Card 层 +//! └ 禁用按钮（OnSurface@10% 叠在面板底上） +//! ``` +//! +//! M229 之前 `disabled.rs` 的入口签名是 `(ui, surface: Role)`，而**所有调用点都传死 +//! `Role::Surface`** —— 于是卡片里的禁用按钮把 10% 叠在画布色上，出来是一块与卡片底 +//! 不协调的灰（M223 记的「CR 1.05、形丢失」）。参数在、语义也在，只是没人给真值。 +//! +//! ## 纪律：底由**画那个底的容器**给 +//! +//! 每个自己画底的容器**导出 `BASE` 常量**，画的时候用同一个 `Role`、给子控件时给这个常量 +//! （见 [`super::super::surfaces::elevated::BASE`]、`inputs::menu::PANEL_BASE`）。两边同源， +//! 改色不会漂一半。 +//! +//! iced 没有「环境上下文」（样式闭包只拿得到 `&Theme`，拿不到父容器的样式），所以这条信息 +//! **只能显式往下传**：容器 → 控件（`.base(..)`）→ 禁用色求值。控件自己不猜。 +//! +//! ## 抓得住 / 抓不住 +//! +//! - 抓得住：合成用了哪个 `Role`（`interaction::disabled::tests` 的逐值断言、gallery 的像素 probe）； +//! - 抓不住：① 容器画的是**合成色**（半透明面板 α、状态层叠过的底）——`Base` 只装一个 `Role`； +//! ② 调用点给了**错的** `Role`（机制不校验语义，判据只能落在「给的底对不对」的像素上）； +//! ③ 忘了调 `.base(..)` 时回落到 [`Base::CANVAS`]，编译期不会报错（文档 + 像素 probe 兜）。 + +use unlucky_design::color::Role; + +/// 控件脚下那一层的底（容器自己画的角色，**不是**「反正是 surface」）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +pub struct Base(Role); + +impl Base { + /// 画布底（`Surface`）：控件**直接**摆在页面/画布上时用它。 + /// + /// 这也是各控件 `.base(..)` 的默认值——默认值只对「没有容器」这一种情形成立， + /// 放进卡片/面板/浮层里**必须**换成那个容器的 `BASE`。 + pub const CANVAS: Base = Base(Role::Surface); + + /// 从容器**画自己底时用的那个角色**构造（容器应导出一个 `BASE` 常量走这条路）。 + pub const fn of(role: Role) -> Self { + Self(role) + } + + /// 该底对应的角色（合成时取色用）。 + pub const fn role(self) -> Role { + self.0 + } +} + +/// 容器也可以直接把**自己的角色**传进来（`disabled_*` 的入口收 `impl Into`）： +/// 这样历史调用点不必全改签名，但语义只有一条——「你脚下那一层是谁」。 +impl From for Base { + fn from(role: Role) -> Self { + Self(role) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + /// 画布底就是画布角色：`Base` 不许偷偷改语义。 + #[test] + fn canvas_is_surface_and_of_keeps_the_role() { + assert_eq!(Base::CANVAS.role(), Role::Surface); + assert_eq!( + Base::of(Role::SurfaceContainer).role(), + Role::SurfaceContainer + ); + // 容器底与画布底**不是同一个值**：这一条红了说明 `Base` 把角色丢了 + assert_ne!(Base::of(Role::SurfaceContainer), Base::CANVAS); + } +} 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..59af725 --- /dev/null +++ b/crates/app-iced/src/components/interaction/disabled.rs @@ -0,0 +1,170 @@ +//! 禁用态的颜色口径：**两个族、两套 α**（M86 收口）。 +//! +//! ## 为什么不是「一个 12%」 +//! +//! 官方禁用 α 分两类（A 级：`material3-android-1.4.0.aar` 的字节码 ``）： +//! +//! | 族 | α | 官方 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}; + +use super::base::Base; + +// 四个入口都收 `impl Into`：容器导出的 `BASE` 常量（推荐）与裸 `Role`（历史调用点， +// 例如 `pages/settings/java/tests/marker.rs`）都能进来。**没有隐式默认值**——不给就是编译错误， +// 这一条正是 M229 缺的：参数在、语义在，只是调用点全传了 `Role::Surface`。 + +/// 禁用态内容色（**按角色、按有没有容器**求值）——A1 口径的入口（**面状控件族**的底）。 +/// +/// - `base`：控件**脚下那一层的底**（[`Base`]）。容器给的 `BASE` 常量，不是猜； +/// - `role`：由变体决定（Filled/Outlined/Text/Elevated = `OnSurfaceVariant`； +/// FilledTonal 与三式 IconButton = `OnSurface`，见 `Variant::disabled_content`）； +/// - `on_container = true`：叠在**面状控件族的 12% 容器**（[`DISABLED_SURFACE_ALPHA`]）上 +/// （Filled TextField / 有容器控件在 12% 底上求内容时），容器本身叠在 `base` 上； +/// `false`：直接叠在 `base` 上（Text / Outlined / standard IconButton / 描边类控件的内容）。 +/// +/// **按钮家族不要用这个函数**（按钮容器是 10%）：走 [`disabled_button_content`]。 +/// +/// 之前这里写死 `OnSurfaceVariant` 且只有一个「底」，导致 FilledTonal 与 IconButton 两族偏浅 +/// 15/255（视觉 r3 用像素量的）。 +pub fn disabled_content_over_role( + ui: &Ui, + base: impl Into, + role: Role, + on_container: bool, +) -> Color { + // **取 `Ui` 里已注入的方案**，不重算 baseline：M229 之后产品方案是品牌色板 + // （Ink / Silver），照 baseline 重算会画出旧的天蓝中性色（复审 F1）。 + disabled_content_with_alpha( + ui.scheme(), + base.into(), + 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, + base: impl Into, + role: Role, + on_container: bool, +) -> Color { + disabled_content_with_alpha( + ui.scheme(), + base.into(), + role, + on_container, + DISABLED_CONTAINER_ALPHA, + ) +} + +/// 两个族共用的内容色求值（「底」的 α 由调用方给）。 +fn disabled_content_with_alpha( + scheme: &Scheme, + base: Base, + role: Role, + on_container: bool, + container_alpha: f32, +) -> Color { + let underneath = scheme.get(base.role()); + let base = if on_container { + scheme + .get(Role::OnSurface) + .with_alpha(container_alpha) + .over(underneath) + } else { + underneath + }; + + 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`]（品牌色板 / 取色方案），**不是** `Scheme::baseline(flavor)`： +/// 后者是 tone 派生的旧口径，在 Ink 板上会让禁用容器偏蓝（复审 F1 的根因）。 +/// +/// 顺序必须「先容器后内容」：Compose 也是这么画的，先叠容器再叠 label， +/// 所以内容叠的角色是容器实色而不是底下的 surface。 +/// +/// ⚠️ **`base` 必须是控件脚下那一层的底**（[`Base`]）：M229 之前这里的参数名叫 `surface`， +/// 而 8 个调用点全传 `Role::Surface`，于是卡片/面板里的禁用控件把 12% 叠在画布色上（M234）。 +pub fn disabled_colors(ui: &Ui, base: impl Into) -> (Color, Color) { + disabled_colors_with_alpha(ui, base.into(), DISABLED_SURFACE_ALPHA) +} + +/// 禁用态的一对颜色 `(容器, 内容)`——**按钮家族**（10% 容器）。 +/// +/// - 容器 = `OnSurface` @ 10%（[`DISABLED_CONTAINER_ALPHA`]）叠在 `base` 上； +/// - 内容 = **默认** `OnSurfaceVariant` @ 38%；按变体的取值走 [`disabled_button_content`]。 +/// +/// 除了按钮家族，**没有别的消费者**：面状控件（chip / slider 轨道 / switch 轨道 / 描边）走 +/// [`disabled_colors`] 的 12%。 +pub fn disabled_button_colors(ui: &Ui, base: impl Into) -> (Color, Color) { + disabled_colors_with_alpha(ui, base.into(), DISABLED_CONTAINER_ALPHA) +} + +/// 两个族共用的求值：容器 = `OnSurface` @ `container_alpha` 叠在 `base` 上，内容 = 38% 叠在容器上。 +fn disabled_colors_with_alpha(ui: &Ui, base: Base, container_alpha: f32) -> (Color, Color) { + let scheme = ui.scheme(); + let underneath = scheme.get(base.role()); + let container = scheme + .get(Role::OnSurface) + .with_alpha(container_alpha) + .over(underneath); + // 这里是**默认口径**（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; diff --git a/crates/app-iced/src/components/interaction/disabled/tests.rs b/crates/app-iced/src/components/interaction/disabled/tests.rs new file mode 100644 index 0000000..7295fc5 --- /dev/null +++ b/crates/app-iced/src/components/interaction/disabled/tests.rs @@ -0,0 +1,381 @@ +//! 禁用态两族 α 与合成色的单测（M229 复审 F1 后从 `disabled.rs` 纯搬移，守 400 行硬线）。 +//! +//! 搬移之后**内容有改动**（不是一行未改）：既有两条「α 族」测试的期望值从 `Scheme::baseline` +//! 改成**品牌板**（F1 的修法就是换色源），并新增 `disabled_colors_follow_the_brand_board_not_the_tone_baseline` +//! 作为 F1 的回归门——它与两条族测试放在一起，读的人一眼能看到「族」与「色源」两件事。 + +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); + // 期望值按**品牌色板**（= `Ui` 注入的那一份），不是 tone 派生的 baseline。 + let scheme = unlucky_design::color::BrandBoard::for_flavor(flavor).scheme(); + 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, Base::CANVAS); + 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, Base::CANVAS); + 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); + // 期望值按**品牌色板**（= `Ui` 注入的那一份），不是 tone 派生的 baseline。 + let scheme = unlucky_design::color::BrandBoard::for_flavor(flavor).scheme(); + 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, Base::CANVAS); + 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, Base::CANVAS); + assert_ne!( + button, surface, + "{flavor:?}：10% 与 12% 必须落在不同像素值上（合成一个数就是这次要防的回归）" + ); + + // 内容色同理：按钮 38% 叠 10% 底 ≠ 面状 38% 叠 12% 底 + assert_ne!( + button_content, + disabled_content_over_role(&ui, Base::CANVAS, Role::OnSurfaceVariant, true), + "{flavor:?}：两族的「有容器」内容色不能同源" + ); + assert_eq!( + disabled_button_content(&ui, Base::CANVAS, Role::OnSurfaceVariant, true), + button_content, + "{flavor:?}：按钮内容入口必须与按钮颜色入口同源" + ); + // 无容器时两族完全一致（都叠 surface）——差异只在「有容器」那一支 + assert_eq!( + disabled_button_content(&ui, Base::CANVAS, Role::OnSurfaceVariant, false), + disabled_content_over_role(&ui, Base::CANVAS, Role::OnSurfaceVariant, false), + "{flavor:?}：没有容器时不该有族差异" + ); + } +} + +/// **M229 复审 F1 的回归门**：禁用态的合成必须跟着**品牌色板**走，不许偷偷回到 tone 派生的 baseline。 +/// +/// Ink 板的中性色是绿系（`on-surface` 与 `surface` 的 G 通道最高），baseline 是蓝系；所以只要 +/// 「禁用容器」在 Ink 下是绿系（`g >= b`）且与 baseline 算出来的值**不相等**，就说明它走的是板。 +/// +/// 抓得住：有人把三处 `Scheme::baseline(ui.flavor())` 写回去（那时本测试立刻红，且报出偏蓝的像素）。 +/// 抓不住：色板本身改了色相（那是 `design` 的 `anchors_pin_the_spec` 的事）。 +#[test] +fn disabled_colors_follow_the_brand_board_not_the_tone_baseline() { + use unlucky_design::color::BrandBoard; + + for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] { + let ui = ui(flavor); + let board = BrandBoard::for_flavor(flavor).scheme(); + let baseline = Scheme::baseline(flavor); + + // ① 面状控件族的容器（chip 描边 / slider 未激活轨 / switch 轨道） + let (surface, _surface_content) = disabled_colors(&ui, Base::CANVAS); + let expect_surface = to_iced( + board + .get(Role::OnSurface) + .with_alpha(DISABLED_SURFACE_ALPHA) + .over(board.get(Role::Surface)), + ); + assert_eq!( + surface, expect_surface, + "{flavor:?}：禁用容器必须按色板合成" + ); + + let baseline_surface = to_iced( + baseline + .get(Role::OnSurface) + .with_alpha(DISABLED_SURFACE_ALPHA) + .over(baseline.get(Role::Surface)), + ); + assert_ne!( + surface, baseline_surface, + "{flavor:?}：禁用容器退回了 baseline（这就是复审 F1 的蓝系像素）" + ); + + // ② 按钮族的容器 + let (button, _) = disabled_button_colors(&ui, Base::CANVAS); + assert_ne!(button, surface, "{flavor:?}：两族 α 仍要可区分"); + + // ③ 内容色（两个入口） + assert_eq!( + disabled_content_over_role(&ui, Base::CANVAS, Role::OnSurfaceVariant, true), + to_iced( + board + .get(Role::OnSurfaceVariant) + .with_alpha(DISABLED_CONTENT_ALPHA) + .over( + board + .get(Role::OnSurface) + .with_alpha(DISABLED_SURFACE_ALPHA) + .over(board.get(Role::Surface)) + ) + ), + "{flavor:?}：面状控件族内容色要按色板合成" + ); + assert_eq!( + disabled_button_content(&ui, Base::CANVAS, Role::OnSurfaceVariant, true), + to_iced( + board + .get(Role::OnSurfaceVariant) + .with_alpha(DISABLED_CONTENT_ALPHA) + .over( + board + .get(Role::OnSurface) + .with_alpha(DISABLED_CONTAINER_ALPHA) + .over(board.get(Role::Surface)) + ) + ), + "{flavor:?}：按钮族内容色要按色板合成" + ); + + // ④ **色相判据**（像素级的自证）：Ink 板的禁用容器是绿系（G 最高），baseline 是蓝系（B 最高）。 + // Ink 板：`on-surface` 与 `surface` 的 G 通道都高于 B 通道（两个中性角色都是绿黑）， + // 合成后仍是 G ≥ B；baseline 深色则是 B > G（天蓝中性）。浅色板上两者都是近中性， + // 所以只在深色档下判色相。 + if matches!(flavor, SchemeFlavor::Dark) { + let (r, g, b) = channels(surface); + assert!( + g >= b, + "{flavor:?}：禁用容器 {r}/{g}/{b} 仍是蓝系（G < B），说明没走 Ink 板" + ); + let (_, bg, bb) = channels(baseline_surface); + assert!(bb > bg, "对照组不合格：baseline 深色的禁用容器应当是蓝系"); + } + } +} + +/// **M234 的主判据**：禁用态的合成必须用**给的底**，不是画布色。 +/// +/// 卡片（`SurfaceContainer`）与面板（`SurfaceContainerLow`）里各放一个禁用控件时， +/// 10%（按钮族）/ 12%（面状族）那一层要叠在**卡/面板的底**上；叠在 `Surface` 上就是 M223 +/// 记的「CR 1.05、形丢失」。 +/// +/// 抓得住：① 入口把 `base` 丢了（内部又写死 `Role::Surface`）；② 入口把两个族的 α 合成一个数； +/// ③ 调用点给了画布底（这条测试只证「给了卡片底 → 算出卡片色」，调用点是否真的给了由 +/// `buttons::tests::a_disabled_button_composites_over_the_base_it_is_given` 与 gallery 的像素 +/// probe 分别守）。 +/// +/// 抓不住：① 容器画的是**合成色**（半透明面板 α、叠过状态层的底）——`Base` 只装一个 `Role`； +/// ② 卡/面板组件**画底时**用的角色与它导出的 `BASE` 不一致（`BASE` 的值本身由 +/// `surfaces::elevated::tests::the_card_base_constant_is_the_role_the_card_paints` 钉住， +/// 「card() 真的用了它」与「页面里的调用点传了它对不对」由 `gallery::probe` 的 disabledbase +/// 段守）；③ GPU(wgpu) 档（本测试是纯值，两档同源同值）。 +#[test] +fn disabled_paint_composites_over_the_base_it_is_given() { + use unlucky_design::color::BrandBoard; + use unlucky_design::color::Role; + + const BUTTON_ALPHA: f32 = 0.10; + const SURFACE_ALPHA: f32 = 0.12; + const CONTENT_ALPHA: f32 = 0.38; + + for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] { + let ui = ui(flavor); + let scheme = BrandBoard::for_flavor(flavor).scheme(); + let card = Base::of(Role::SurfaceContainer); + let panel = Base::of(Role::SurfaceContainerLow); + + // 期望值一律**独立算**（写死 α + 直接取色板角色），不调被测常量。 + let over = |base: Role, alpha: f32| { + to_iced( + scheme + .get(Role::OnSurface) + .with_alpha(alpha) + .over(scheme.get(base)), + ) + }; + + // ① 按钮族 10%：卡片底 / 面板底 / 画布底三档互不相等 + let (card_button, card_button_ink) = disabled_button_colors(&ui, card); + let (panel_button, _) = disabled_button_colors(&ui, panel); + let (canvas_button, canvas_button_ink) = disabled_button_colors(&ui, Base::CANVAS); + assert_eq!( + card_button, + over(Role::SurfaceContainer, BUTTON_ALPHA), + "{flavor:?}：卡片里的禁用按钮容器 = on-surface@10% 叠**卡片底**" + ); + assert_eq!( + panel_button, + over(Role::SurfaceContainerLow, BUTTON_ALPHA), + "{flavor:?}：面板里的禁用按钮容器 = on-surface@10% 叠**面板底**" + ); + assert_ne!(card_button, canvas_button, "{flavor:?}：卡片底 ≠ 画布底"); + assert_ne!(panel_button, canvas_button, "{flavor:?}：面板底 ≠ 画布底"); + assert_ne!(card_button, panel_button, "{flavor:?}：卡片底 ≠ 面板底"); + + // ② 面状控件族 12%（字段容器 / chip 容器 / switch 轨道） + let (card_surface, _) = disabled_colors(&ui, card); + let (panel_surface, _) = disabled_colors(&ui, panel); + let (canvas_surface, _) = disabled_colors(&ui, Base::CANVAS); + assert_eq!( + card_surface, + over(Role::SurfaceContainer, SURFACE_ALPHA), + "{flavor:?}：卡片里的禁用字段容器 = on-surface@12% 叠**卡片底**" + ); + assert_eq!( + panel_surface, + over(Role::SurfaceContainerLow, SURFACE_ALPHA), + "{flavor:?}：面板里的禁用字段容器 = on-surface@12% 叠**面板底**" + ); + assert_ne!(card_surface, canvas_surface); + assert_ne!(panel_surface, canvas_surface); + + // ③ 内容色也跟着底走（38% 叠在容器上 / 直接叠在底上，两支都要换底） + assert_eq!( + disabled_button_content(&ui, card, Role::OnSurfaceVariant, true), + to_iced( + scheme + .get(Role::OnSurfaceVariant) + .with_alpha(CONTENT_ALPHA) + .over( + scheme + .get(Role::OnSurface) + .with_alpha(BUTTON_ALPHA) + .over(scheme.get(Role::SurfaceContainer)) + ) + ), + "{flavor:?}：有容器的内容色 = 38% 叠(10% 叠卡片底)" + ); + assert_ne!( + card_button_ink, canvas_button_ink, + "{flavor:?}：内容叠的容器换了底" + ); + assert_ne!( + disabled_content_over_role(&ui, card, Role::OnSurface, false), + disabled_content_over_role(&ui, Base::CANVAS, Role::OnSurface, false), + "{flavor:?}：无容器时 38% 也必须叠在**给的底**上" + ); + } +} + +/// iced 颜色 → 8bit 通道（像素值，报告里的证据就用它）。 +fn channels(color: Color) -> (u8, u8, u8) { + ( + (color.r * 255.0).round() as u8, + (color.g * 255.0).round() as u8, + (color.b * 255.0).round() as u8, + ) +} 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..64487ac --- /dev/null +++ b/crates/app-iced/src/components/interaction/mod.rs @@ -0,0 +1,248 @@ +//! 交互状态层：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 字节码 `` 里的 `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` 会扫）。 +//! +//! ## 合成的「底」是参数，不是常量（M234） +//! +//! 四个入口都收一个 [`Base`]——控件**脚下那一层的底**，由画那个底的容器导出 +//! （`surfaces::elevated::BASE` / `inputs::menu::PANEL_BASE` / 各控件的 `.base(..)`）。 +//! M229 之前这个值恒等于 `Role::Surface`，于是卡片/面板里的禁用控件把 10%/12% 叠在画布色上 +//! （M223 的「CR 1.05、形丢失」）。**不许**在入口内部再写一个默认值回来。 +//! +//! ## 两个消费形态 +//! +//! 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 { + 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 { + state + .layer() + .map(|layer| ui.state_over(layer, content, container)) +} + +mod base; +mod disabled; + +pub use base::Base; +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> { + 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> { + 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> { + 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> { + 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` 之类。 + #[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..266cf07 --- /dev/null +++ b/crates/app-iced/src/components/mod.rs @@ -0,0 +1,65 @@ +//! 组件库（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） +//! scroll.rs ← M173：竖直滚动区的滚动条槽（轨道不压内容） +//! motion/ ← M192：动效帧泵（时间轴，不是控件家族；页面经 `pages::render` 用它） +//! selection/ ← 本文件只放桩；后续 mission 在自己的目录里填（§18/§19/§10/§13） +//! inputs/ ← 同上（§9/§20/§11/§8） +//! feedback/ ← 同上（§12/§14/§7/§15） +//! navigation/ ← 同上（§4/§6/§21/§16） +//! surfaces/ ← M229：ELEVATED CARD（规格卡 `CARD / DIALOG / SNACKBAR / LIST` 的第一格） +//! 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; +/// M192：动效帧泵（时间轴，不是控件家族）。页面只经 `pages::render` 用它，见模块文档。 +pub mod motion; +pub mod navigation; +pub mod scroll; +pub mod selection; +pub mod surfaces; + +#[cfg(test)] +mod gate; diff --git a/crates/app-iced/src/components/motion/mod.rs b/crates/app-iced/src/components/motion/mod.rs new file mode 100644 index 0000000..5919e1c --- /dev/null +++ b/crates/app-iced/src/components/motion/mod.rs @@ -0,0 +1,182 @@ +//! **动效帧泵**（M192）：design 的 motion 令牌 → iced 的**有界**帧订阅。 +//! +//! ## 这个模块解决什么 +//! +//! `crates/design/src/motion/` 里令牌一直齐着（16 档时长 / 可采样缓动 / 二维弹簧表 / +//! `MotionScale::NONE` 降级），但适配层从没消费过 ⇒ 所有状态变化都是硬切。本模块是那条缺失的 +//! 中间层：**谁能动**（[`Slot`]）、**动多久**（[`spec`] 的令牌表）、**什么时候该订阅帧** +//! （[`needs_frames`]）。 +//! +//! ## 有界泵的契约（四条，都有守卫） +//! +//! | 契约 | 为什么 | 守在哪 | +//! |---|---|---| +//! | 只在**有轨道**时订阅帧 | `window::frames()` 一订阅就自持重绘循环（实测几百帧/秒） | `pump::tests::a_finished_animation_stops_asking_for_frames` | +//! | 轨道到期**当场删除**，不靠「下次状态变化」 | 删晚了就是空闲烧帧 | 同上（把 `advance` 的清理删掉就红） | +//! | **时间轴推进**不密于 [`FRAME_MS`]（16 ms ≈ 62.5/s），且单次最多吃 [`pump::MAX_STEP_MS`] | 帧到得再快也只该改这么多次布局；空闲醒来时 stale 的帧基准不许把动画一帧杀完 | `pump::tests::frames_are_capped_at_sixty_per_second`、`pump::tests::a_stale_baseline_cannot_kill_the_track_in_one_sample` | +//! | 起跑**必须发生在 `update` 侧**（[`observe`]），`view` 侧只采样（[`sample`]） | iced 先算订阅表（`update()` 内部）后建视图 ⇒ 在 `view` 里插轨道当拍订阅不上，动画会退化成「一帧偏移 + 闪跳」 | `app::subscription::tests::a_state_change_opens_the_frame_subscription_in_the_same_tick` | +//! +//! ⚠️ **16 ms 只卡「采样与布局推进」，不卡整窗重绘。** 整窗重绘**跟随渲染器**： +//! 软件渲染实测 ≈**970 帧/秒**（一次 300 ms 的换页 ≈ **290 次整窗重绘** ≈ **0.30 核·秒**）， +//! GPU 档被 AutoVsync 限到 40~60 帧/秒。重绘次数是「订阅开着多久」的函数，与闸门无关。 +//! +//! 接法是**加进**既有那条链，不是另起一条：`App::needs_frames()` 多一个「有轨道」的分支， +//! 订阅表仍然是**一处** `if`（`app/subscription.rs`），所以与 `watch_until` / Busy 续订/ 心跳 +//! 天然不会双订阅——它们共享同一个布尔。 +//! +//! ## `MotionScale::NONE` 是**真归零** +//! +//! 关掉动效 ≠ 跑一遍 0 时长动画：`Pump::play` 在 `is_off()` 时**不插入轨道**，`progress` 于是 +//! 直接返回 `1.0`（到位），`needs_frames()` 恒为假 ⇒ **一帧都不订阅**。守卫见 +//! `pump::tests::none_scale_never_starts_a_track`。 +//! +//! ## 为什么是 thread-local 而不是 `App` 的字段 +//! +//! 它是**时间轴**（`(槽 → 进度)` 一张表 + 一个时钟），不是应用状态：没有任何业务语义，也不需要 +//! 跨进程持久。iced 在事件循环线程上串行调 `update` / `view`（这与 `App::update(&mut self)` 能存在 +//! 是同一条纪律），所以一个线程局部就够，且**测试天然隔离**（`cargo test` 每个用例一个线程， +//! 不会出现「另一条线的动画把 `needs_frames()` 顶成真」的假红）。 +//! +//! 仓内已有同样的先例（`pages/appearance/probe.rs`、`core/src/addon/pack/format/probe.rs` 都用了 +//! `#[allow(clippy::missing_const_for_thread_local)]`），所以这不是给本 crate 开的新口子。 +//! +//! ## 谁在什么时候调 +//! +//! | 时机 | 调用 | 在哪 | +//! |---|---|---| +//! | 每条消息处理完（**订阅表求值之前**） | [`observe`]：内容标识变了就起跑 | `App::sync_motion`（`app/update/motion.rs`） | +//! | 每帧画视图 | [`sample`]：只读当前位移 | `pages::render` | +//! | 每帧 | [`advance`]：推进时间轴 | `App::on_frame` | +//! +//! 页面**拿不到**时长/缓动/弹簧参数——那是 [`spec`] 的事。 +//! +//! 位移走 `container` 的 `padding`：动画期间内容比容器少几像素高，末帧归零后与静息**逐像素相同**。 +//! 不做逐像素 α（D27：CPU 档零运行时半透明）也不做模糊（同上），所以两个渲染后端出图一致。 + +mod pump; + +// 本 mission 里这五个只被测试与文档引用（产品路径只经 `observe`/`sample`/`shifted`，拿不到时长/缓动）， +// 所以显式 `allow` 一下——与 `interaction::Tracker` 那条同一条理由：它们是对外口径的一部分 +// （`spec` 是唯一一张规格表），不该因为「暂时没人调」就被删掉。 +#[allow(unused_imports)] +pub use pump::{offset, spec, Slot, Spec, FRAME_MS}; + +use std::cell::{Cell, RefCell}; +use std::time::Instant; + +use iced::widget::container; +use iced::{Element, Length, Padding}; + +use unlucky_design::motion::MotionScale; + +// clippy 1.99 的 `missing_const_for_thread_local` 对**已经是** `const { … }` 的初始化也报 +// （换过三种写法都照报，属于误报；复审 r1 已复核并确认，仓内 `pages/appearance/probe.rs` 等 +// 两处已有同样的 `allow`）。初始化确实已是常量，所以按项显式放过（上在宏外面不算，lint 是对 +// 展开后的 item 报的）。 +thread_local! { + /// 进程内唯一时间轴（见模块文档「为什么是 thread-local」）。 + #[allow(clippy::missing_const_for_thread_local)] + static PUMP: RefCell = const { RefCell::new(pump::Pump::new()) }; + /// 上次收到帧的时刻（`advance` 用它把「帧到达」换算成流逝毫秒）。 + #[allow(clippy::missing_const_for_thread_local)] + static LAST_FRAME: Cell> = const { Cell::new(None) }; +} + +/// 定档：`on_boot` 调一次（截图档给 `NONE`，CPU 档给 `HALF`，见 `app/update/boot_env.rs`）。 +pub fn configure(scale: MotionScale, pin: Option) { + PUMP.with(|pump| pump.borrow_mut().configure(scale, pin)); +} + +/// 当前档位。 +pub fn scale() -> MotionScale { + PUMP.with(|pump| pump.borrow().scale()) +} + +/// 已推进的帧数。 +pub fn samples() -> u64 { + PUMP.with(|pump| pump.borrow().samples()) +} + +/// 现在有没有动画在跑（`App::needs_frames` 的一个分支）。 +pub fn needs_frames() -> bool { + PUMP.with(|pump| pump.borrow().is_animating()) +} + +/// 页主体的内容**标识**：**每条消息处理完**调一次（`App::sync_motion`），标识变了就此起跑。 +/// +/// `screen` 是 `pages::Screen` 的稳定键（`None` = 这一屏不归 pages 画：账户页 / AI 独立页）， +/// `detail` 是详情页的实例 id。 +/// +/// ## 为什么必须在 update 侧（M192 r1 复审 P1-1） +/// +/// iced 0.14 的顺序是「消息 → `update()`（订阅表在**这里**求值）→ `build_user_interfaces` +/// （这时才调 `view`）」（iced_winit-0.14.1 `src/lib.rs:1222-1240`）。轨道若在 `view` 里插， +/// 同一拍的订阅表看不见它 ⇒ `frames()` 要等下一条消息（最快鼠标 / 最慢 1 Hz 心跳）才打开， +/// 而那一帧的 dt 是整段空闲时长 ⇒ 动画一帧走完，用户只看到一次偏移闪跳。 +/// +/// 起跑时**顺带把帧基准重置到「现在」**：空闲期没有帧，`LAST_FRAME` 是几分钟前的值， +/// 不重置的话第一帧仍会按整段空闲时长结算（第二道兜底是 [`pump::MAX_STEP_MS`]）。 +pub fn observe(screen: Option, detail: Option<&str>) { + let started = PUMP.with(|pump| pump.borrow_mut().observe(screen, detail)); + if started { + LAST_FRAME.with(|last| last.set(Some(Instant::now()))); + } +} + +/// 当前入场位移（**只采样、无副作用**）：`pages::render` 每帧调一次。 +pub fn sample() -> (f32, f32) { + PUMP.with(|pump| pump.borrow().offsets()) +} + +/// 推进时间轴（`App::on_frame` 每帧调一次）。 +pub fn advance() { + let now = Instant::now(); + let elapsed_ms = LAST_FRAME.with(|last| { + let previous = last.replace(Some(now)); + previous.map_or(0.0, |previous| { + now.saturating_duration_since(previous).as_secs_f64() * 1000.0 + }) + }); + PUMP.with(|pump| { + pump.borrow_mut().advance(elapsed_ms); + }); +} + +/// 把入场位移套到树上。 +/// +/// **总是**套这一层（位移为 `(0,0)` 时只是 `padding = 0`）：它是树的**根**，而 iced 的 +/// `Tree::diff` 按 widget tag 判等——根 tag 一换就重建整棵子树。若只在动画期间才套， +/// 动画起止两侧会各重建一次，页面内的滚动位置 / 焦点会被重置（复审 r1 提示的风险）。 +/// 常驻一层的代价是布局上多一个 `Fill` 容器（零内距时逐像素相同，出图基线已复验）。 +pub fn shifted<'a, M: 'a>( + element: impl Into>, + (dx, dy): (f32, f32), +) -> Element<'a, M> { + container(element.into()) + .width(Length::Fill) + .height(Length::Fill) + .padding(Padding { + top: dy, + right: 0.0, + bottom: 0.0, + left: dx, + }) + .into() +} + +#[cfg(test)] +pub fn reset() { + PUMP.with(|pump| *pump.borrow_mut() = pump::Pump::new()); + LAST_FRAME.with(|last| last.set(None)); +} + +/// 测试专用：按给定毫秒推进（`advance` 读真实时钟，单元测试不能等它）。 +#[cfg(test)] +pub fn advance_by(ms: f64) { + PUMP.with(|pump| { + pump.borrow_mut().advance(ms); + }); +} + +#[cfg(test)] +mod tests; diff --git a/crates/app-iced/src/components/motion/pump.rs b/crates/app-iced/src/components/motion/pump.rs new file mode 100644 index 0000000..749efee --- /dev/null +++ b/crates/app-iced/src/components/motion/pump.rs @@ -0,0 +1,348 @@ +//! 帧泵的**纯逻辑**：槽 / 规格表 / 时间轴 / 进度采样。 +//! +//! 这一层不认识 iced、不认识线程、不读环境变量——那些都在 [`super`]。分开的理由很实际： +//! 「帧间隔上限」「结束后必须清空」这两条守卫是**算术性质**，用本地 `Pump` 直接摆时间轴就能判死， +//! 不必起窗口、不必等真实时间（那两条最容易写成「看起来在跑」的假绿）。 +//! +//! ## 三个概念 +//! +//! | 名字 | 是什么 | 谁定 | +//! |---|---|---| +//! | [`Slot`] | 一个**同屏互斥**的动画位（首屏 / 换页 / 列表↔详情） | 本文件 | +//! | [`Spec`] | 该位的时长档 + 缓动档，**只能**是 design 令牌 | [`spec`]（全项目唯一一张表） | +//! | [`Pump`] | 一条时间轴 + 每槽最多一条轨道 | 本文件 | +//! +//! ## 为什么规格表在代码里而不是页面里 +//! +//! D31：弹簧/时长令牌是**表**，页面只许按表取、不许自调参数。所以页面拿不到「给我 250ms」这种 +//! 口子——它只能说「我要换页了」（[`Pump::enter`]），用哪一档由 [`spec`] 决定。改观感只改这张表。 + +use std::collections::BTreeMap; + +use unlucky_design::motion::{DurationToken, Easing, MotionScale}; +use unlucky_design::spacing::Space; + +/// 逐帧**推进时间轴**的最短间隔（16 ms ≈ 60 次/秒）。 +/// +/// ⚠️ **这只卡「采样与布局推进」，不卡整窗重绘。** 两个频率必须分开看： +/// +/// | 什么 | 频率 | 由谁决定 | +/// |---|---|---| +/// | 时间轴推进 / 位移采样（本常量） | ≤62.5 次/秒 | 这里 | +/// | **整窗重绘** | **跟随渲染器**：软件渲染实测 ≈**970 帧/秒**（一次 300 ms 的换页 ≈**290 次整窗重绘** ≈ **0.30 核·秒**）；GPU 档被 AutoVsync 限到 40~60 | `window::frames()` 一订阅，iced_winit 每条消息后都 `request_redraw()`（iced_winit-0.14.1 `src/lib.rs:1222-1240`） | +/// +/// 所以「动画期间最多 60fps」只对**采样**成立；重绘次数是订阅时长的函数，与 16 ms 无关。 +/// 为什么仍然要 16 ms：每帧重绘已经是既成事实（忙碌态本来就这样），16 ms 卡的是**布局重排** +/// 与 `pages::render` 的重建成本；两者的量级差一个数量级以上（见报告的性能记账）。 +pub const FRAME_MS: f64 = 16.0; + +/// 单次推进的**最大步进**（4 帧 = 64 ms）。 +/// +/// 为什么需要它：`advance` 的 dt 来自「上一帧到现在」，而空闲期根本没有帧——醒来的第一帧如果 +/// 按真实流逝（秒~分钟级）结算，`duration` 当场就被跨过 ⇒ 到期轨道被立刻删除 ⇒ 动画一帧走完 +/// （M192 r1 复审 P1-1 就是这么暴露的）。起点由 `motion::observe` 重置，这里再兜一道： +/// **任何一次采样最多只吃掉 4 帧的时长**，掉帧/被挂起时宁可把动画放慢，也不许把它一次性抹掉。 +pub const MAX_STEP_MS: f64 = FRAME_MS * 4.0; + +/// 一个动效槽。 +/// +/// 槽是**同屏互斥**的：三个槽都是「页主体入场」的不同触发点，同时跑会让位移叠加 +/// （首屏 16 + 换页 12 = 28px）。所以 [`Pump::play`] 起跑新槽时丢掉旧的——语义上也对： +/// 新的一次内容变化取代上一次。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)] +pub enum Slot { + /// 首屏进入：进程内只在第一帧跑一次。 + Boot, + /// 换页：路由换了（导航轨点选、返回、启动直达）。 + Screen, + /// 列表 ↔ 详情：同一页里的子视图切换（实例页点一行）。 + Detail, +} + +impl Slot { + /// 全部槽（遍历顺序稳定，写日志/断言用）。 + pub const ALL: [Slot; 3] = [Slot::Boot, Slot::Screen, Slot::Detail]; + + /// 稳定名字（日志与测试失败信息用；只有测试在调，故按 `cfg(test)` 编译）。 + #[cfg(test)] + pub const fn name(self) -> &'static str { + match self { + Slot::Boot => "boot", + Slot::Screen => "screen", + Slot::Detail => "detail", + } + } +} + +/// 一条轨道的规格：**时长档 × 缓动档**，两个都是 design 令牌。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct Spec { + /// 时长档（毫秒值经 [`MotionScale`] 缩放后生效）。 + pub duration: DurationToken, + /// 缓动曲线。 + pub easing: Easing, +} + +/// 槽 → 规格（**唯一**一张表）。 +/// +/// 三档时长取自令牌注释里对应场景的那一档（`Medium2` = 导航/tab 切换、`Medium3` = 卡片展开/ +/// 列表重排、`Medium4` = 面板开合），曲线**统一用 `Standard`**： +/// +/// - 整块页面的位移不是「元素从屏外飞入」，而是「屏内这块内容换了」——M3 把 `Standard` 定义为 +/// 「起止都在屏内的元素」，`*Decelerate` 是给「已经在高速运动、要迅速落定」的共享元素用的； +/// - 本地实测（`dev` 机器，见报告）：`EmphasizedDecelerate` 把 **75% 的位移压在 51 ms 内**走完 +/// （300 ms 档），12px 的整页平移会看起来像「跳一格」；`Standard` 同样时长下是 105 ms，落点更稳。 +pub const fn spec(slot: Slot) -> Spec { + match slot { + Slot::Boot => Spec { + duration: DurationToken::Medium4, + easing: Easing::Standard, + }, + Slot::Screen => Spec { + duration: DurationToken::Medium2, + easing: Easing::Standard, + }, + Slot::Detail => Spec { + duration: DurationToken::Medium3, + easing: Easing::Standard, + }, + } +} + +/// 槽 → 入场位移（像素；正值 = 从右下方向归位，末态恒为 `(0, 0)`）。 +/// +/// 幅度取**间距令牌**（4px 栅格）而不是新造一组数字：位移是布局量，和间距用同一把尺子， +/// 将来改栅格不会出现「间距 12、位移 14」这种两套刻度。 +pub fn offset(slot: Slot) -> (f32, f32) { + match slot { + Slot::Boot => (0.0, Space::X4.dp()), + Slot::Screen => (0.0, Space::X3.dp()), + Slot::Detail => (Space::X2.dp(), 0.0), + } +} + +/// 一条正在跑的轨道。 +#[derive(Debug, Clone, Copy)] +struct Track { + /// 起跑时刻（动画时间轴的坐标，毫秒）。 + start_ms: f64, + spec: Spec, +} + +/// 帧泵：一条时间轴 + 每槽一条轨道。 +/// +/// **默认是关的**（`MotionScale::NONE`）：产品启动时由 `App::on_boot` 按档位打开，而 +/// `pages_demo` 这类截图 harness 从不打开——D30 的「同一份代码出同一张图」因此不受动效影响。 +#[derive(Debug)] +pub struct Pump { + scale: MotionScale, + /// `Some(ms)` = 钉住相位（多帧序列图取证；见 `ULL_MOTION_AT`）。 + pin: Option, + now_ms: f64, + pending_ms: f64, + tracks: BTreeMap, + screen: Option, + detail: Option, + painted: bool, + samples: u64, +} + +impl Pump { + /// 出厂态：关着、没跑过、没有轨道。 + pub const fn new() -> Self { + Self { + scale: MotionScale::NONE, + pin: None, + now_ms: 0.0, + pending_ms: 0.0, + tracks: BTreeMap::new(), + screen: None, + detail: None, + painted: false, + samples: 0, + } + } + + /// 定档（启动一拍调一次）。 + /// + /// 顺带**重置内容标识**：iced 会在处理 `Boot` 之前先问一次 `view()`（实测：那一帧早于 + /// `on_boot` 的日志），于是「第一帧」发生在档位还没定下来的时候。不重置的话首屏入场就被那次 + /// 预渲染吃掉了（`painted = true`），之后标识再没变过 ⇒ Boot 槽永远不跑。 + pub fn configure(&mut self, scale: MotionScale, pin: Option) { + self.scale = scale; + self.pin = pin; + self.painted = false; + self.screen = None; + self.detail = None; + self.pending_ms = 0.0; + if scale.is_off() { + // 关掉动效 = 直接落终态：把在跑的轨道清掉，而不是让它跑一遍 0 时长。 + self.tracks.clear(); + } + } + + /// 当前档位。 + pub fn scale(&self) -> MotionScale { + self.scale + } + + /// 已推进的帧数（守卫与 `ULL_TICK_TRACE` 用）。 + pub fn samples(&self) -> u64 { + self.samples + } + + /// 时间轴（毫秒）。 + #[cfg(test)] + pub fn now_ms(&self) -> f64 { + self.now_ms + } + + /// 现在有没有动画在跑（= 要不要订阅帧）。 + pub fn is_animating(&self) -> bool { + !self.tracks.is_empty() + } + + /// 起跑一个槽（关着动效时什么都不做——**不是**跑一遍 0 时长动画）。返回 `true` = 真的起跑了。 + /// + /// 三个槽**互斥**：它们都是「页主体入场」的不同触发点，同时跑会让位移叠加（首屏 + 换页 = + /// 28px）。所以起跑新槽就丢掉旧的——语义上也对：新的一次内容变化取代上一次。 + pub fn play(&mut self, slot: Slot) -> bool { + self.tracks.clear(); + if self.scale.is_off() { + return false; + } + // 钉住相位时轨道的起点固定在 0：进度于是恒等于「钉住的毫秒 / 时长」， + // 与「谁在第几帧起跑」无关——这正是多帧序列图要的可复现性。 + let start_ms = if self.pin.is_some() { 0.0 } else { self.now_ms }; + self.tracks.insert( + slot, + Track { + start_ms, + spec: spec(slot), + }, + ); + true + } + + /// 采样：`0.0` = 刚起跑，`1.0` = 到位（**没有轨道就是到位**）。 + pub fn progress(&self, slot: Slot) -> f32 { + let Some(track) = self.tracks.get(&slot) else { + return 1.0; + }; + let duration = f64::from(self.scale.ms(track.spec.duration)); + if duration <= 0.0 { + return 1.0; + } + let elapsed = self.elapsed_ms() - track.start_ms; + let t = (elapsed / duration).clamp(0.0, 1.0) as f32; + track.spec.easing.sample(t) + } + + /// 当前动画时刻（钉住相位时恒为钉住值）。 + fn elapsed_ms(&self) -> f64 { + self.pin.unwrap_or(self.now_ms) + } + + /// 页主体的内容**标识**变了就起跑对应槽；**必须在 update 侧调**（见 `App::sync_motion`）。 + /// + /// ## 为什么不能放在 `view` 里（M192 r1 复审 P1-1，这是本轮最重要的一行注释） + /// + /// iced 0.14 的顺序是「消息 → `update()`（**`program.subscription()` 在这里求值**）→ + /// `build_user_interfaces`（这时才调 `view`）」（iced_winit-0.14.1 `src/lib.rs:1222-1240`， + /// 订阅表在 `update()` 内部的 `lib.rs:1338` 求值）。所以在 `view` 里插轨道，同一拍的订阅表 + /// **看不见**它，`frames()` 要等下一条消息（最快鼠标、最慢 1 Hz 心跳）才打开——那一段里 + /// 页面已经带着位移画过一帧，然后就没了：用户看到的是一次偏移闪跳。 + /// + /// 三条判据（顺序即优先级）： + /// 1. 第一次看到**归 pages 画的屏** → [`Slot::Boot`]； + /// 2. 屏变了 → [`Slot::Screen`]； + /// 3. 屏没变但详情变了 → [`Slot::Detail`]。 + /// + /// `screen == None`（账户页 / AI 独立页：它们不走 `pages::render`）**只记标识、不起跑**—— + /// 否则会白跑 300 ms 的帧却没人采样它；而「从这些页回到某一屏」因为标识从 `None` 变回 + /// `Some`，仍然会跑换页那一档。 + /// + /// 返回 `true` = 真的起跑了新轨道（调用方要重置帧基准，见 [`MAX_STEP_MS`]）。 + pub fn observe(&mut self, screen: Option, detail: Option<&str>) -> bool { + let mut started = false; + if !self.painted { + self.painted = true; + if screen.is_some() { + started = self.play(Slot::Boot); + } + } else if self.screen != screen { + if screen.is_some() { + started = self.play(Slot::Screen); + } + } else if self.detail.as_deref() != detail && screen.is_some() { + started = self.play(Slot::Detail); + } + self.screen = screen; + if self.detail.as_deref() != detail { + self.detail = detail.map(str::to_owned); + } + started + } + + /// 页主体的入场位移（**只采样，无副作用**）：`pages::render` 每帧调一次。 + /// + /// 三个槽的剩余量求和后**取整**：整像素位移不会让文字在动画期间发虚；末帧全部 `1.0` + /// ⇒ 恒为 `(0, 0)` ⇒ 与静息的布局逐像素相同。 + pub fn offsets(&self) -> (f32, f32) { + let mut dx = 0.0_f32; + let mut dy = 0.0_f32; + for slot in Slot::ALL { + let remaining = 1.0 - self.progress(slot); + let (ox, oy) = offset(slot); + dx += ox * remaining; + dy += oy * remaining; + } + (dx.round(), dy.round()) + } + + /// 推进时间轴。返回 `true` = 这一帧真的推进了（进度变了 ⇒ 要重画）。 + /// + /// 四步：①不满 [`FRAME_MS`] 就不动（采样上限）②**单次最多吃 [`MAX_STEP_MS`]**（掉帧 / + /// 被挂起 / 空闲醒来的第一帧都不许一次性跨过时长）③到期的轨道**当场删除**（这是「空闲不烧帧」 + /// 的唯一出口：删掉最后一个轨道之后 [`is_animating`](Self::is_animating) 立刻为假，下一拍订阅表 + /// 里就不再有 `window::frames()`）④钉住相位时时间轴不前进（取证专用）。 + pub fn advance(&mut self, dt_ms: f64) -> bool { + if self.tracks.is_empty() { + self.pending_ms = 0.0; + return false; + } + if dt_ms.is_finite() && dt_ms > 0.0 { + // ②：上限不是「省事」，是正确性——stale 的帧基准（空闲整段）会把轨道一帧杀完。 + self.pending_ms += dt_ms.min(MAX_STEP_MS); + } + if self.pending_ms < FRAME_MS { + return false; + } + let step = std::mem::take(&mut self.pending_ms); + if self.pin.is_none() { + self.now_ms += step; + } + self.samples += 1; + + let now = self.elapsed_ms(); + let finished: Vec = self + .tracks + .iter() + .filter(|(_, track)| { + let duration = f64::from(self.scale.ms(track.spec.duration)); + duration <= 0.0 || now - track.start_ms >= duration + }) + .map(|(slot, _)| *slot) + .collect(); + for slot in finished { + self.tracks.remove(&slot); + } + true + } +} + +impl Default for Pump { + fn default() -> Self { + Self::new() + } +} diff --git a/crates/app-iced/src/components/motion/tests.rs b/crates/app-iced/src/components/motion/tests.rs new file mode 100644 index 0000000..13e09af --- /dev/null +++ b/crates/app-iced/src/components/motion/tests.rs @@ -0,0 +1,345 @@ +//! 帧泵的守卫（M192）。全部用**本地** `Pump` 摆时间轴：不起窗口、不等真实时间，所以不会假绿。 +//! +//! 接线级的守卫（真消息 / 真订阅表）在 `app/subscription.rs` 的 `mod tests`：这一组只管算术。 + +use super::pump::{offset, spec, Pump, Slot, FRAME_MS, MAX_STEP_MS}; +use super::*; + +/// 标准档、没有钉相位的泵（出厂态是 `NONE`，见 [`Pump::new`]）。 +fn standard() -> Pump { + let mut pump = Pump::new(); + pump.configure(MotionScale::STANDARD, None); + pump +} + +/// 按「每帧 16 ms」推进到全部轨道结束（上限 20 s，防死循环）。 +fn settle(pump: &mut Pump) -> u64 { + let mut frames = 0; + for _ in 0..1250 { + if !pump.is_animating() { + break; + } + if pump.advance(FRAME_MS) { + frames += 1; + } + } + frames +} + +// ------------------------------------------------------------------ 令牌表 + +/// 规格**全部**来自 design 的令牌表，且落在 M3 的常规区间（改表会让这条红）。 +#[test] +fn every_slot_spec_is_a_registered_token_pair() { + for slot in Slot::ALL { + let spec = spec(slot); + let ms = spec.duration.ms(); + assert!( + (250..=500).contains(&ms), + "{}: 时长 {}ms 不在换页类动效的合理区间（克制优先）", + slot.name(), + ms + ); + // 缓动必须是真的曲线（端点 = 0/1） + assert!(spec.easing.sample(0.0).abs() < 1.0e-6); + assert!((spec.easing.sample(1.0) - 1.0).abs() < 1.0e-6); + // 位移必须来自间距栅格（4 的倍数），且不为零 + let (dx, dy) = offset(slot); + assert!( + dx > 0.0 || dy > 0.0, + "{}: 位移为 0 就没有入场感", + slot.name() + ); + assert_eq!(dx % 4.0, 0.0); + assert_eq!(dy % 4.0, 0.0); + assert!(dx.max(dy) <= 24.0, "{}: 位移过大（克制优先）", slot.name()); + } + // 表本身钉住：谁改了这三档，报告与出图都要跟着改 + assert_eq!(spec(Slot::Screen).duration.ms(), 300); + assert_eq!(spec(Slot::Detail).duration.ms(), 350); + assert_eq!(spec(Slot::Boot).duration.ms(), 400); +} + +// ------------------------------------------------------------------ 有界泵 + +/// **空闲不烧帧**：动画跑完 ⇒ `is_animating()` 立刻为假，且不再推进。 +/// +/// 抓得住：把 `advance` 里的「到期即删除」删掉（轨道永远留着 ⇒ 帧订阅永不退订），或把 +/// `is_animating` 改成恒真。两条都让本用例红。 +#[test] +fn a_finished_animation_stops_asking_for_frames() { + let mut pump = standard(); + assert!(pump.play(Slot::Screen), "起跑必须成功"); + assert!(pump.is_animating(), "起跑后必须有轨道（订阅帧的唯一理由）"); + + settle(&mut pump); + assert!( + !pump.is_animating(), + "动画结束必须**当场**退订（占着轨道 = 空闲烧帧）" + ); + assert_eq!(pump.progress(Slot::Screen), 1.0, "结束即到位"); + assert_eq!(pump.offsets(), (0.0, 0.0), "结束即归位"); + + // 再推进也不该有任何采样（订阅表里已经没有帧了） + let before = pump.samples(); + for _ in 0..60 { + assert!(!pump.advance(FRAME_MS), "没有轨道时推进必须返回 false"); + } + assert_eq!(pump.samples(), before, "空闲态一次采样都不该发生"); +} + +/// **采样频率上限**：帧到得再快，时间轴也只按 16 ms 结算（≈62.5 次/秒）。 +/// +/// 注意这条**不管整窗重绘**：重绘跟随渲染器（见 [`FRAME_MS`] 文档）。 +/// 抓得住：把 `pending_ms` 那道闸门删掉（每来一帧就推进 ⇒ 软件渲染下几百次/秒的重排）。 +#[test] +fn frames_are_capped_at_sixty_per_second() { + let mut pump = standard(); + pump.play(Slot::Screen); + + // 200 帧、每帧 1 ms（模拟 1000 fps 的渲染器） + let mut advanced = 0; + for _ in 0..200 { + if pump.advance(1.0) { + advanced += 1; + } + } + assert!( + advanced <= 13, + "200 ms 内最多 13 次推进（200/16），实测 {advanced} 次" + ); + assert!( + advanced >= 11, + "也别少得离谱（掉帧会看起来卡），实测 {advanced}" + ); + assert_eq!(pump.samples(), advanced); + // 时间轴按真实时间走，不受「帧被合并」影响 + assert!( + (pump.now_ms() - 192.0).abs() <= 16.0, + "时间轴应约 192 ms（12 × 16），实测 {}", + pump.now_ms() + ); +} + +/// **stale 帧基准不许把轨道一帧杀完**（M192 r1 复审 P1-1 的算术面）。 +/// +/// 运行时真出现过：空闲几分钟后第一条消息起跑轨道，第一帧的 dt 是整段空闲时长 ⇒ 立即到期 ⇒ +/// 动画一帧走完，用户只看到一次偏移闪跳。两道兜底：起跑时重置帧基准（`motion::observe`）与 +/// 单次最大步进 [`MAX_STEP_MS`]；这条守的是第二道。 +#[test] +fn a_stale_baseline_cannot_kill_the_track_in_one_sample() { + let mut pump = standard(); + pump.play(Slot::Screen); + + // 60 秒的「空闲间隔」当 dt + assert!(pump.advance(60_000.0)); + assert!( + pump.is_animating(), + "一次超长 dt 不许把轨道当场删掉（那就等于没有动画）" + ); + assert!( + pump.now_ms() <= MAX_STEP_MS + 1.0e-6, + "单次推进最多 {:?} ms，实测 {}", + MAX_STEP_MS, + pump.now_ms() + ); + assert!( + pump.progress(Slot::Screen) < 1.0, + "进度不许一步到位（那就是闪跳）" + ); + + // 正常帧间隔照样把动画跑完（没被抖动卡死） + settle(&mut pump); + assert!(!pump.is_animating()); +} + +/// 采样必须单调、且末尾回到 1.0（回弹类曲线不在本批，见 [`spec`] 的表）。 +#[test] +fn progress_is_monotone_and_lands_on_one() { + let mut pump = standard(); + pump.play(Slot::Detail); + let mut previous = 0.0; + for _ in 0..40 { + let value = pump.progress(Slot::Detail); + assert!(value >= previous, "进度倒退了：{previous} → {value}"); + previous = value; + if !pump.advance(FRAME_MS) { + break; + } + } + assert_eq!(previous, 1.0, "末帧必须到位"); +} + +// ------------------------------------------------------------------ NONE 降级 + +/// **`MotionScale::NONE` 是真归零**：不起轨道、不采样、位移恒为 0。 +/// +/// 抓得住：把 `play` 里的 `is_off()` 分支删掉（变成「跑一遍 0 时长动画」）——那样这个用例里 +/// `is_animating()` 会短暂为真、`samples` 会增长，帧订阅次数就不是 0 了。 +#[test] +fn none_scale_never_starts_a_track() { + let mut pump = Pump::new(); // 出厂即 NONE + assert!(pump.scale().is_off()); + + // 首屏 + 换页 + 换详情：三次状态变化都不许留下轨道 + assert!(!pump.observe(Some(1), None), "关掉动效时不许起跑"); + assert_eq!(pump.offsets(), (0.0, 0.0), "关掉动效必须直接落终态"); + assert!(!pump.is_animating()); + assert!(!pump.observe(Some(2), None)); + assert_eq!(pump.offsets(), (0.0, 0.0)); + assert!(!pump.observe(Some(2), Some("instance-7"))); + assert_eq!(pump.offsets(), (0.0, 0.0)); + assert!(!pump.is_animating()); + + for _ in 0..120 { + assert!(!pump.advance(FRAME_MS), "关掉动效后没有任何可推进的"); + } + assert_eq!(pump.samples(), 0, "NONE 档的帧订阅次数必须是 0"); +} + +/// 运行期把关掉动效（`configure(NONE)`）也要立刻落终态，而不是把在跑的动画「缩到 0 时长」。 +#[test] +fn switching_to_none_mid_flight_settles_immediately() { + let mut pump = standard(); + pump.play(Slot::Screen); + pump.advance(FRAME_MS); + assert!(pump.is_animating()); + + pump.configure(MotionScale::NONE, None); + assert!(!pump.is_animating(), "关掉动效必须当场清空轨道"); + assert_eq!(pump.progress(Slot::Screen), 1.0); + assert_eq!(pump.offsets(), (0.0, 0.0)); +} + +/// 半速档（CPU 渲染兜底）真的把时长减半：同样的时间轴推进，轨道更早结束。 +#[test] +fn half_scale_finishes_in_half_the_frames() { + let mut full = standard(); + full.play(Slot::Screen); + let full_frames = settle(&mut full); + + let mut half = Pump::new(); + half.configure(MotionScale::HALF, None); + half.play(Slot::Screen); + let half_frames = settle(&mut half); + + assert!(half_frames > 0 && full_frames > 0); + assert!( + half_frames * 2 <= full_frames + 2, + "半速档应约用一半帧数：full={full_frames} half={half_frames}" + ); +} + +// ------------------------------------------------------------------ 触发判据 + +/// 三个槽的触发优先级：首屏 Boot → 换屏 Screen → 同屏换详情 Detail。 +#[test] +fn identity_changes_pick_the_right_slot() { + let mut pump = standard(); + + // 首帧：Boot（位移是纵向 16） + assert!(pump.observe(Some(1), None), "首帧要跑 Boot 槽"); + let (dx, dy) = pump.offsets(); + assert_eq!(dx, 0.0); + assert_eq!(dy, offset(Slot::Boot).1, "首屏应有一个向下的入场位移"); + assert_eq!( + pump.progress(Slot::Screen), + 1.0, + "首帧不该顺带起跑 Screen 槽" + ); + settle(&mut pump); + assert!(!pump.observe(Some(1), None), "标识没变 ⇒ 不起跑"); + assert_eq!(pump.offsets(), (0.0, 0.0)); + + // 换屏：Screen（纵向） + assert!(pump.observe(Some(2), None)); + let (dx, dy) = pump.offsets(); + assert_eq!(dx, 0.0); + assert_eq!(dy, offset(Slot::Screen).1); + assert!(pump.progress(Slot::Screen) < 1.0, "换屏要跑 Screen 槽"); + settle(&mut pump); + + // 同屏换详情：Detail（横向） + assert!(pump.observe(Some(2), Some("instance-7"))); + let (dx, dy) = pump.offsets(); + assert_eq!(dx, offset(Slot::Detail).0, "列表↔详情是横向入场"); + assert_eq!(dy, 0.0); + assert!(pump.progress(Slot::Detail) < 1.0); + settle(&mut pump); + assert!(!pump.observe(Some(2), Some("instance-7"))); + assert_eq!(pump.offsets(), (0.0, 0.0)); +} + +/// 不归 pages 画的屏（账户页 / AI 独立页，`screen == None`）**不起跑**；回到某一屏照样跑。 +#[test] +fn screens_rendered_elsewhere_never_start_a_track() { + let mut pump = standard(); + assert!(pump.observe(Some(1), None), "首屏开机跑 Boot"); + settle(&mut pump); + + assert!(!pump.observe(None, None), "没有 pages 树可动 ⇒ 不许白开帧"); + assert!(!pump.is_animating()); + assert_eq!(pump.offsets(), (0.0, 0.0)); + + assert!( + pump.observe(Some(1), None), + "从账户页回到某一屏仍然是换页，要跑" + ); + assert_eq!(pump.offsets().1, offset(Slot::Screen).1); +} + +/// 换页会**取代**首屏那一档：位移不叠加（12px，不是 16+12）。 +#[test] +fn a_new_transition_supersedes_the_previous_one() { + let mut pump = standard(); + assert_eq!( + pump.offsets().1, + 0.0, + "还没 observe 时没有位移（采样是纯函数）" + ); + pump.observe(Some(1), None); + assert_eq!(pump.offsets().1, offset(Slot::Boot).1); + + // 首屏还没跑完就换页：位移必须是 Screen 那一档，而不是两档相加 + pump.observe(Some(2), None); + assert_eq!( + pump.offsets().1, + offset(Slot::Screen).1, + "新的一次内容变化应取代上一次（叠加会让位移变成两档之和）" + ); +} + +/// 同一屏同一详情重复绘制**永远不会**重新起跑（否则每帧都在重启动画 = 永远停不下来）。 +#[test] +fn repeated_paints_never_restart_the_animation() { + let mut pump = standard(); + pump.observe(Some(3), Some("instance-9")); + let frames = settle(&mut pump); + assert!(frames > 0); + + for _ in 0..30 { + assert!(!pump.observe(Some(3), Some("instance-9"))); + assert_eq!(pump.offsets(), (0.0, 0.0)); + } + assert!(!pump.is_animating(), "重复绘制不该起新轨道"); +} + +// ------------------------------------------------------------------ 取证相位 + +/// `ULL_MOTION_AT` 的钉住相位：时间轴不前进，进度恒定（多帧序列图靠它可复现）。 +#[test] +fn pinned_phase_freezes_the_clock() { + let mut pump = Pump::new(); + pump.configure(MotionScale::STANDARD, Some(150.0)); + pump.play(Slot::Screen); // 300 ms 档 ⇒ 钉在 150 = 一半 + + for _ in 0..10 { + pump.advance(FRAME_MS); + } + let progress = pump.progress(Slot::Screen); + assert!( + (progress - spec(Slot::Screen).easing.sample(0.5)).abs() < 1.0e-6, + "钉在 150/300 的进度应等于缓动曲线的中点，实测 {progress}" + ); + assert!(pump.is_animating(), "钉住的相位不会自然结束（取证专用）"); +} 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 { + icon: IconKind, + on_press: Option, +} + +impl AppBarAction { + /// 一个可点的图标动作。 + 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>, + trailing: Vec>, + 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) -> Self { + self.leading = Some(action); + self + } + + /// 追加一个后置动作（`OnSurfaceVariant`）。 + pub fn trailing(mut self, action: AppBarAction) -> 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, + 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::(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) -> Option { + 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..4727760 --- /dev/null +++ b/crates/app-iced/src/components/navigation/drawer.rs @@ -0,0 +1,147 @@ +//! 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::super::interaction::Base; +use super::geometry::{NavLayout, NavPaneGeometry}; + +mod item; +use item::{line, nav_row}; +pub use item::{NavGroup, NavItem}; + +/// 导航容器的底：§21.3 标准（常驻）= `Surface` + L0 —— 所以项的禁用内容叠在画布色上。 +/// +/// 与 [`navigation`] 的 `ui.layer(MaterialLayer::Canvas)` 同源（`Canvas` 的 surface_role 就是 +/// `Surface`），M234 之后「底」由这里给，项自己不猜。 +pub const BASE: Base = Base::of(Role::Surface); + +/// 导航容器（D33：`layout` 决定 88 还是 240，其余全同）。 +#[derive(Debug, Clone)] +pub struct Navigation<'a, M> { + layout: NavLayout, + groups: Vec>, +} + +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::(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::( + 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, BASE, 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..376c0da --- /dev/null +++ b/crates/app-iced/src/components/navigation/drawer/item.rs @@ -0,0 +1,298 @@ +//! 导航项的公共类型与一行渲染（`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, Base, 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, + pub(super) state: Option, +} + +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>, +} + +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, + /// 图标色。 + pub(super) icon: Color, + /// 标签色。 + pub(super) label: Color, +} + +pub(super) fn palette( + ui: &Ui, + base: Base, + layout: NavLayout, + state: Interaction, + selected: bool, +) -> ItemPalette { + if state.is_disabled() { + let ink = interaction::disabled_content_over_role(ui, base, 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, base.role()), + 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, + base: Base, + 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, base, 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::(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::( + 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::( + 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..660244e --- /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, BASE, 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, BASE, NavLayout::Rail, Interaction::Enabled, true); + let drawer = palette(&ui, BASE, 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, BASE, 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, BASE, 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, BASE, NavLayout::Drawer, Interaction::Disabled, true); + assert_eq!( + palette.icon, + interaction::disabled_content_over_role(&ui, BASE, 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..0fd2cfc --- /dev/null +++ b/crates/app-iced/src/components/navigation/list_item.rs @@ -0,0 +1,323 @@ +//! 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, base, OnSurface, false)` +//! （`base` = 行脚下的底，默认 [`Base::CANVAS`]）；用默认的 `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, Base, 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, + trailing: Option, + on_press: Option, + selected: bool, + state: Option, + /// 脚下那一层的底（M234，禁用态合成用）。 + base: Base, +} + +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, + base: Base::CANVAS, + } + } + + /// 加一行辅助文本 → **两行**项（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 + } + + /// **告诉列表项它踩在什么底上**（M234）：禁用态的 38% 内容叠在这个底上。 + pub fn base(mut self, base: impl Into) -> Self { + self.base = base.into(); + 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, + headline: Color, + supporting: Color, + leading: Color, + trailing: Color, +} + +fn palette(ui: &Ui, base: Base, state: Interaction, selected: bool) -> ItemPalette { + if state.is_disabled() { + // A1：ListItemDisabled*Color = OnSurface × 0.38（无容器时叠在 surface 上） + let ink = interaction::disabled_content_over_role(ui, base, 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 { + // 状态层叠在**行脚下的底**（`base`）上，得到不透明结果（D27）。 + // M234 复审 P2-3：原来写死 `Role::Surface`，卡片里的列表项抬起时会叠在画布色上。 + fill: interaction::overlay_color(ui, state, Role::OnSurface, base.role()), + 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, + item.base, + 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::( + ui, + overline, + typography_overline(), + colors.supporting, + )); + } + body = body.push(line::( + ui, + item.headline, + typography_headline(), + colors.headline, + )); + if let Some(supporting) = item.supporting { + body = body.push(line::( + 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::(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::(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 base = item.base; + let style = move |_theme: &iced::Theme, status: button::Status| { + let state = forced.unwrap_or_else(|| Interaction::from_status(status)); + let colors = palette(ui, base, 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..95e76e4 --- /dev/null +++ b/crates/app-iced/src/components/navigation/list_item/tests.rs @@ -0,0 +1,128 @@ +//! `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, Base::CANVAS, Interaction::Disabled, false); + let expected = + interaction::disabled_content_over_role(&ui, Base::CANVAS, 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, Base::CANVAS, 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, Base::CANVAS, 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, Base::CANVAS, Interaction::Enabled, false); + for state in [ + Interaction::Hovered, + Interaction::Focused, + Interaction::Pressed, + ] { + let active = palette(&ui, Base::CANVAS, 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> { + 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=` 再切成单块出图（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..8767661 --- /dev/null +++ b/crates/app-iced/src/components/navigation/probe.rs @@ -0,0 +1,395 @@ +//! 渲染层几何断言：**对着真截图量像素**（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 { + 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 { + 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 = 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 = 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, + interaction::Base::CANVAS, + Role::OnSurface, + false, + )); + let wrong = rgb(interaction::disabled_content_over_role( + &ui, + interaction::Base::CANVAS, + 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 = 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 = 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 = 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 = 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::>(); + 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::>(); + 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::>(); + 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, +} + +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 { + 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 { + 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 = (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 = 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 { + 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::() / 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..cb80db6 --- /dev/null +++ b/crates/app-iced/src/components/navigation/tabs.rs @@ -0,0 +1,373 @@ +//! 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, Base, 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, + selected: bool, + on_press: Option, + state: Option, +} + +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>, + /// 脚下那一层的底（M234，禁用态合成用）。 + base: Base, +} + +impl<'a, M> Tabs<'a, M> { + /// Primary tabs（3px 指示条）。 + pub fn primary() -> Self { + Self { + variant: TabsVariant::Primary, + tabs: Vec::new(), + base: Base::CANVAS, + } + } + + /// Secondary tabs（1px 分隔线）。 + pub fn secondary() -> Self { + Self { + variant: TabsVariant::Secondary, + tabs: Vec::new(), + base: Base::CANVAS, + } + } + + /// 追加一个 tab。 + pub fn tab(mut self, tab: Tab<'a, M>) -> Self { + self.tabs.push(tab); + self + } + + /// **告诉 tab 条它踩在什么底上**（M234）：禁用态的 38% 标签/指示条叠在这个底上。 + pub fn base(mut self, base: impl Into) -> Self { + self.base = base.into(); + self + } +} + +/// 一个 tab 的内容色（A1 的 `Active*` / `Inactive*` / 各态表，见模块文档）。 +fn content_color(ui: &Ui, base: Base, 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, base, 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, base: Base, state: Interaction, selected: bool) -> Option { + if !selected { + return None; + } + if state.is_disabled() { + return Some(interaction::disabled_content_over_role( + ui, + base, + 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(); + let base = tabs.base; + // 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, base, 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 单元（内容 + 底部条）。 +#[allow(clippy::too_many_arguments)] +fn tab_cell<'a, M: Clone + 'a>( + ui: &'a Ui, + base: Base, + 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, base, 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::(kind, color), + )); + } + content = content.push(label); + + let bar_height = geometry.bar(primary); + // 底层：内容自己决定宽度（Shrink），底部留出条的高度 —— 未选中的 Primary tab 也占同样的高 + let cell = 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, base, state, selected) + } else { + None + }; + let radius = geometry.indicator_radius(); + let mut stack = Stack::new().push(cell); + 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, base.role()); + 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..1029e50 --- /dev/null +++ b/crates/app-iced/src/components/navigation/tabs/tests.rs @@ -0,0 +1,154 @@ +//! `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::{self, Base}; + +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, Base::CANVAS, true, Interaction::Enabled, true), + ui.color(Role::Primary) + ); + assert_eq!( + content_color(&ui, Base::CANVAS, false, Interaction::Enabled, true), + ui.color(Role::OnSurface), + "6.5：Secondary 的选中项是 OnSurface" + ); + assert_ne!( + content_color(&ui, Base::CANVAS, 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, Base::CANVAS, primary, Interaction::Enabled, false), + ui.color(Role::OnSurfaceVariant) + ); + for state in [ + Interaction::Hovered, + Interaction::Focused, + Interaction::Pressed, + ] { + assert_eq!( + content_color(&ui, Base::CANVAS, 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, Base::CANVAS, Interaction::Enabled, false), + None + ); + assert_eq!( + bar_color(&ui, Base::CANVAS, Interaction::Enabled, true), + Some(ui.color(Role::Primary)) + ); + assert_eq!( + bar_color(&ui, Base::CANVAS, Interaction::Disabled, true), + Some(interaction::disabled_content_over_role( + &ui, + Base::CANVAS, + 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/scroll.rs b/crates/app-iced/src/components/scroll.rs new file mode 100644 index 0000000..e67baa1 --- /dev/null +++ b/crates/app-iced/src/components/scroll.rs @@ -0,0 +1,224 @@ +//! 滚动条**并排**在内容右侧，不压在内容上（M173）。 +//! +//! ## 根因（读 iced 0.14 的源码，不是猜测） +//! +//! `scrollable` 的竖直滚动条是**浮层**，而且内容区不扣任何横向内边距： +//! +//! - 内容拿到的约束仍是整个视口宽——`iced_widget-0.14.2/src/scrollable.rs:437` 那条 +//! `layout::padded(limits, self.width, self.height, Padding::ZERO, …)`：`Scrollbar::spacing` +//! 默认 `None`，右内边距**恒 0**； +//! - 轨道按视口右边缘定位——同文件 `scrollable.rs:1970-1980` +//! `x = bounds.x + bounds.width - total_scrollbar_width`，`total_scrollbar_width = +//! width.max(scroller_width) + 2 * margin`。 +//! +//! 于是轨道（本仓 6 + 2×2 = **10dp**）整条压在内容最右边那 10dp 上。屏幕上的观感就是 +//! 「滚动条骑在卡片右边缘」。 +//! +//! ## 为什么不用 iced 自己的 `Scrollbar::spacing(Some(..))` +//! +//! 它**只在滑块可见时**才预留（`scrollable.rs:478-500`：`if state.is_scrollbar_visible +//! { padding } else { 0.0 }`）。长页面 ⇄ 短页面切换时内容宽度会跳 10dp，卡片会横移—— +//! 那是另一个缺陷（`M173` 的判据要求「有无滚动条时内容宽度一致」）。 +//! +//! ## 本模块的做法：恒定槽位 +//! +//! 内容外面包一层「右侧恒留 `slot`」的容器，再交给 `scrollable`： +//! +//! ```text +//! 视口 0 ───────────────────────── 视口宽 − slot │ slot │ +//! │ 内容（可滚） │ 轨道 │ +//! ``` +//! +//! `内容可用宽度 = 视口宽 − slot` 与滑块在不在**无关**（因为内边距来自本模块，不来自 iced 的 +//! 可见性判断）。`slot = rail_width + 2 * margin` 与 iced 的 `total_scrollbar_width` 同口径， +//! 轨道整个落在槽里，滑块再内缩 `margin`，所以内容与滑块之间永远隔着 `margin`。 +//! +//! 逻辑像素（dp）：高 DPI 下 iced 按缩放因子整体放大，槽与轨道同比例，二者不会重新重叠。 +//! +//! ## 谁该用 +//! +//! 所有「内容宽度吃满视口」的竖直滚动区。设置页（`pages/settings/frame.rs`）是第一个用户； +//! 实例页列表列 / 详情列、日志面板、内容库正文、版本管理侧栏目前仍是 `scrollable(...)` 裸调， +//! 同一处重叠在那些页面上照样存在（M173 的 finding 里有清单）。 + +use iced::widget::{container, scrollable}; +use iced::{Element, Length, Padding, Theme}; + +/// 滚动条轨占的横向槽宽（dp）= 轨宽 + 两侧留白。 +/// +/// 与 iced 的 `total_scrollbar_width`（`width.max(scroller_width) + 2 * margin`）同一个式子： +/// 参数里的 `rail_width` 传的是 `Scrollbar::width` 与 `scroller_width` 的同一个值（本仓两者相等）。 +pub fn rail_slot(rail_width: f32, margin: f32) -> f32 { + rail_width + 2.0 * margin +} + +/// 内容可用宽度（dp）= 视口宽 − 槽宽。 +/// +/// 这条式子是本模块的**判据**：`components/scroll.rs` 的测试用 iced 的布局引擎真量一遍， +/// `pages/settings/tests/scroll_fit.rs` 在产品那条 `frame::scroll` 上再量一遍。 +/// 负数按 0 处理——视口比槽还窄时（产品窗口不会发生）宁可内容零宽，也不给 iced 送负宽。 +#[cfg(test)] +pub fn content_width(viewport: f32, slot: f32) -> f32 { + (viewport - slot).max(0.0) +} + +/// 竖直滚动区：内容右侧恒留 [`rail_slot`] 的槽，滚动条画在槽里。 +/// +/// `style` 就是 `scrollable::style` 回调（配色由调用方按令牌给），本模块只管几何。 +pub fn vertical<'a, Message, Renderer>( + rail_width: f32, + margin: f32, + style: impl Fn(&Theme, scrollable::Status) -> scrollable::Style + 'a, + content: impl Into>, +) -> Element<'a, Message, Theme, Renderer> +where + Message: 'a, + Renderer: iced::advanced::text::Renderer + 'a, +{ + scrollable(beside(rail_slot(rail_width, margin), content)) + .direction(scrollable::Direction::Vertical( + scrollable::Scrollbar::new() + .width(rail_width) + .scroller_width(rail_width) + .margin(margin), + )) + .height(Length::Fill) + .style(style) + .into() +} + +/// 内容 + 右侧槽位。容器宽度仍是 `Fill`（= 视口宽），扣掉的是**内容的**可用宽度。 +fn beside<'a, Message, Renderer>( + slot: f32, + content: impl Into>, +) -> Element<'a, Message, Theme, Renderer> +where + Message: 'a, + Renderer: iced::advanced::Renderer + 'a, +{ + container(content) + .width(Length::Fill) + .padding(Padding { + right: slot, + ..Padding::ZERO + }) + .into() +} + +#[cfg(test)] +mod tests { + //! ## 为什么这里的守卫是**真的布局**而不是源码扫描 + //! + //! iced 的控件树支持在测试里跑一遍布局：`iced_core` 在 debug 构建下给 `()` 实现了全套 + //! `Renderer` trait（`iced_core-0.14.0/src/renderer/null.rs`），所以 `Element<_, _, Theme, ()>` + //! 能被 `Widget::layout` 真正量出尺寸——**不需要开窗、不需要 GPU**。 + //! + //! 于是「内容可用宽度 = 视口宽 − 槽宽」是一条数值断言，而不是「看图觉得对」；把 + //! [`beside`] 的 `padding` 去掉，下面的 `content_width` 立刻变成 434 而断言红。 + //! + //! ⚠️ 诚实边界：`()` 的 Renderer 实现带 `#[cfg(debug_assertions)]`，所以这些测试在 + //! `cargo test --release` 下编不过（本仓 CI/本地一律 dev profile 跑测试）。 + + use iced::advanced::layout::Limits; + use iced::advanced::widget::Tree; + use iced::widget::{container, scrollable, space}; + use iced::{Rectangle, Size}; + + use super::*; + + /// 本仓的轨道参数（真源是 `pages/frame/pieces.rs` 的两个常量，这里按「用户取值」复核）。 + const RAIL: f32 = 6.0; + const MARGIN: f32 = 2.0; + /// 设置页表单列在 1180 宽窗口下的列宽（`measure_cap_px` = 424）。 + const VIEWPORT: f32 = 424.0; + /// 视口高（1180×760 减去页头/页边距后的量级；只要求「长页 > 视口」「短页 < 视口」）。 + const VIEWPORT_HEIGHT: f32 = 600.0; + /// 长页面（一定出滑块）与短页面（一定不出滑块）的内容高。 + const LONG: f32 = 4000.0; + const SHORT: f32 = 120.0; + + /// 真跑一遍布局，返回 (槽容器, 内容) 两个矩形。 + /// + /// 节点树：`scrollable → [槽容器（Fill 宽，右内边距 = slot） → [内容]]`，见 + /// `iced_core/src/layout.rs:201`（`padded` 的节点恒为「自己 + 一个子节点」）。 + fn laid_out(content_height: f32) -> (Rectangle, Rectangle) { + let filler: Element<'_, (), Theme, ()> = container(space()) + .width(Length::Fill) + .height(Length::Fixed(content_height)) + .into(); + + let mut element: Element<'_, (), Theme, ()> = + vertical::<(), ()>(RAIL, MARGIN, scrollable::default, filler); + let mut tree = Tree::new(element.as_widget()); + + let node = element.as_widget_mut().layout( + &mut tree, + &(), + &Limits::new(Size::ZERO, Size::new(VIEWPORT, VIEWPORT_HEIGHT)), + ); + + let gutter = node.children()[0].bounds(); + let content = node.children()[0].children()[0].bounds(); + + (gutter, content) + } + + /// **本 mission 的核心判据**：内容可用宽度 = 视口宽 − 滚动条槽，且与有没有滑块无关。 + #[test] + fn the_content_width_leaves_the_rail_its_own_slot() { + let slot = rail_slot(RAIL, MARGIN); + assert_eq!(slot, RAIL + 2.0 * MARGIN, "槽宽口径 = 轨宽 + 两侧留白"); + + let (_, long) = laid_out(LONG); + let (_, short) = laid_out(SHORT); + + assert_eq!( + long.width, + content_width(VIEWPORT, slot), + "长页面（出滑块）的内容宽度必须是「视口宽 − 槽宽」" + ); + assert_eq!( + short.width, + content_width(VIEWPORT, slot), + "短页面（不出滑块）的内容宽度必须**一样**：否则滑块一出现内容就横跳" + ); + assert_eq!(VIEWPORT - long.width, slot, "右侧扣掉的正好是槽宽"); + + // 滑块落在槽的中间：内容右缘 → margin → 滑块 → margin → 视口右缘。 + // 轨道按 iced 的算法定位（`scrollable.rs:1970-2005`：槽宽 = 轨宽 + 2×margin，滑块再内缩 margin）， + // 所以「内容右缘 + margin」就是滑块的左缘。 + let content_right = long.x + long.width; + let pill_left = content_right + MARGIN; + let pill_right = pill_left + RAIL; + assert_eq!( + pill_right + MARGIN, + VIEWPORT, + "滑块必须整个落在槽内（两侧各留 margin），否则「并排」变成「压着」" + ); + } + + /// 槽容器自己仍是满宽（`Fill`），否则页面为它预留的 424 会被再吃掉一截。 + #[test] + fn the_slot_wrapper_keeps_the_full_viewport_width() { + let (gutter, _) = laid_out(LONG); + assert_eq!(gutter.width, VIEWPORT); + } + + /// 左边界与宽度在长/短两态下**逐项相同**（M173 明写的「两张对照图 + 数值」里的数值部分）。 + #[test] + fn long_and_short_pages_share_the_same_left_edge_and_width() { + let (_, long) = laid_out(LONG); + let (_, short) = laid_out(SHORT); + + assert_eq!(long.x, short.x, "左边界必须一致"); + assert_eq!(long.width, short.width, "宽度必须一致"); + assert_eq!(short.x, 0.0, "槽只占右侧，左侧内边距为 0"); + } + + #[test] + fn content_width_never_goes_negative() { + assert_eq!(content_width(RAIL, rail_slot(RAIL, MARGIN)), 0.0); + assert_eq!(content_width(0.0, rail_slot(RAIL, MARGIN)), 0.0); + assert_eq!(content_width(VIEWPORT, 0.0), VIEWPORT); + } +} 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..d886112 --- /dev/null +++ b/crates/app-iced/src/components/selection/checkbox.rs @@ -0,0 +1,207 @@ +//! Checkbox（`research/15` §18 + 规格卡）：**18×18 / 圆角 4** / 描边向内收的 2px 框 / +//! 勾形 10.8dp 方头（路径比例 0.6 × 边长）/ indeterminate 形变为居中短横 / Ø40 状态层 / 48 命中区。 +//! +//! 尺寸口径（M229）：官方 `Checkbox.kt` 画 20×20 / rx2，规格卡画 `rect 18×18 rx4`，本实现取规格卡 +//! （`inkcat::metrics::CHECKBOX`）。勾形**比例不变**（0.2→0.8 的横向跨度），所以墨水跨度随边长从 +//! 12dp 变成 10.8dp。 +//! +//! ## 三条容易画错的（每条都有对应的像素断言或单测） +//! +//! 1. **描边向内**：外缘恒 **18**（§18.3 的尺寸换成本项目的 18）。iced 的 quad 渲染器把描边路径 +//! **向内缩半个线宽**（`iced_tiny_skia::engine::draw_quad`：`border_bounds + border_width / 2`）， +//! 与 Compose `drawBox` 的 `topLeft = stroke/2, size = side − stroke` 同一口径，所以 +//! 选中/未选中外缘同尺寸。 +//! 2. **勾不是图标**：勾形按路径比例画（`shell::glyph`），代码里**没有第二个 `IconKind`**（§18.6）。 +//! 3. **状态层是 Ø40 的圆**、命中区是 48：两者不同尺寸，所以外壳是透明的 48 按钮， +//! 里面套一个 40 的圆容器，再套 18 的方框（见 `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::{Base, 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, + error: bool, + state: Option, + /// 脚下那一层的底（M234，禁用态合成用）。 + base: Base, +} + +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, + base: Base::CANVAS, + } + } + + /// 禁用的复选框（无消息；禁用不是「另一种颜色」，见 `paint::checkbox` 的禁用分支）。 + pub fn disabled(label: &'a str, value: CheckValue) -> Self { + Self { + label, + value, + on_toggle: None, + error: false, + state: None, + base: Base::CANVAS, + } + } + + /// 校验失败态（§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 + } + + /// **告诉复选框它踩在什么底上**（M234）：禁用态的 38% 内容/描边叠在这个底上。 + pub fn base(mut self, base: impl Into) -> Self { + self.base = base.into(); + 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 base = spec.base; + 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, base, 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, base, 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, + base, + 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, base, 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..7f3a1a1 --- /dev/null +++ b/crates/app-iced/src/components/selection/chip.rs @@ -0,0 +1,279 @@ +//! 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 圆」那套。 +//! +//! ## 「选中」与「当前项」：两个档位，一套颜色（M206） +//! +//! 这两件事**不是**「选中 / 未选中」，而是「可点的选中」与「不可点的当前项」——它们必须长得 +//! **一样**（同一个视觉语汇），差别只在**有没有反馈**： +//! +//! | 档位 | 构造器 | 容器 / 文字 | 对比度下限 | 五态反馈 | 什么时候用 | +//! |---|---|---|---|---|---| +//! | A 可点选中 | [`Chip::filter`] `(label, true, msg)` | `SecondaryContainer` / `OnSecondaryContainer` | **≥ 4.5:1**（WCAG AA 正文；实测 7.21:1 浅 / 7.21:1 深） | 有（hover/pressed 状态层） | 点它**会改变**选中项（下载组的分段单选、预置项开关） | +//! | B 不可点当前项 | [`Chip::current`] | **同 A，一个像素都不差** | **≥ 4.5:1**（同 7.21:1） | **无**（没有可点性就没有反馈） | 「这就是当前生效的那个」，再点一次没有动作（Java 组的「默认」） | +//! | （不是档位）暂不可用 | [`Chip::badge`] / [`.disabled()`](Chip::disabled) | `OnSurface`@12% / @38% | **不适用**：它是禁用语汇（实测 1.84:1 浅 / 2.28:1 深） | — | 真的点不了（下载进行中把「安装」灰掉、LTS/基线这类标签） | +//! +//! **判据只有一句**：这个 chip 点下去**会不会改变**它表示的值？ +//! 会 → A；不会（它已经是当前值）→ B；**根本不能点**（忙/不可用）→ 禁用档。 +//! 尤其：**不许拿 `badge` 表示「当前默认」**——那是把「不可用」的语汇贴在「答案」上， +//! M204 实测出来就是整页最不可读的一段（1.84:1）。这一条不靠调用方记住，`Chip::current` +//! 与 `paint::current_item` 的文档 + `pages::settings::java::tests::marker` 的三条断言 +//! （对比度 / 同族 / 禁用语义）一起把它钉在组件层。 + +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::{Base, 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, + trailing: Option, + on_press: Option, + state: Option, + /// 「当前项」标记（[`Chip::current`]）：选中配色照画，但**不**降成禁用配色、也不吃五态。 + marker: bool, + /// 脚下那一层的底（M234，禁用态合成用）。 + base: Base, +} + +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) + } + + /// **纯展示**的 filter chip（选中态、无消息 ⇒ 永远不可交互）。 + /// + /// 与 `filter(label, true, msg).disabled()` 等价，但**不要求调用方编一条永远收不到的消息**。 + /// + /// ⚠️ **它不是「当前项」**（M206 纠正）：`badge` 走的是**禁用**配色（`OnSurface`@38% 叠 + /// surface，实测 **1.84:1 浅 / 2.28:1 深**），那是「暂不可用」的语汇。要表达「这行就是当前 + /// 生效的那个」，用 [`Chip::current`]——它和下载组的选中 chip 同一套颜色，7.21:1。 + /// 仍然用 `badge` 的两处都是**真禁用语义**：下载进行中把「安装」灰掉、以及 LTS/基线/推荐这类标签。 + pub fn badge(label: &'a str) -> Self { + Self { + label, + variant: ChipVariant::Filter, + selected: true, + leading: None, + trailing: None, + on_press: None, + state: None, + marker: false, + base: Base::CANVAS, + } + } + + /// **当前项**标记：`SecondaryContainer` + `OnSecondaryContainer`（与可点的选中 chip + /// **同一套配色**），没有消息 ⇒ 也不吃 hover / pressed / 禁用态。 + /// + /// 语义：「这一行就是当前生效的那个」。它与 [`Chip::filter`]`(label, true, msg)` 的差别 + /// **只在有没有动作**——点当前值不会改变任何东西，所以给它一个永远不响的消息是撒谎 + /// （`Message::Noop` 已删，见 `Chip::badge` 的旧注）。判据表见本文档开头的「选中与当前项」。 + /// + /// 为什么不能写成「`filter(.., true, ..)` + `.disabled()`」：`disabled()` 会走禁用配色 + /// （38% 文字、12% 容器），当前项就又变成不可读了——这正是 M206 要修的那件事。 + pub fn current(label: &'a str) -> Self { + Self { + label, + variant: ChipVariant::Filter, + selected: true, + leading: None, + trailing: None, + on_press: None, + state: None, + marker: true, + base: Base::CANVAS, + } + } + + /// 转成禁用：**只清消息**，图标 / 选中态 / 状态层全部保留（复审 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, + marker: false, + base: Base::CANVAS, + } + } + + /// 前置图标（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 它踩在什么底上**（M234）：禁用态那 12% 容器/描边与 38% 内容叠在这个底上。 + pub fn base(mut self, base: impl Into) -> Self { + self.base = base.into(); + self + } + + /// 静息时的外观——**唯一**把「这颗 chip 属于哪个档位」翻成颜色的地方。 + /// + /// `chip()` 用它求文字/图标色，测试也用它量对比度：档位的判据（当前项 / 选中 / 禁用） + /// 只有这一处，所以「实现改回旧配色」这类变异会被 + /// `pages::settings::java::tests::marker` 的对比度断言直接抓住。 + pub fn paint(&self, ui: &Ui) -> paint::ChipPaint { + let radius = ChipGeometry::of(ui).radius; + if self.marker { + return paint::current_item(ui, radius); + } + // 没有消息 = 禁用（`Chip::badge` 与 `.disabled()` 都走这里）。 + let state = if self.on_press.is_none() { + Interaction::Disabled + } else { + self.state.unwrap_or(Interaction::Enabled) + }; + paint::chip(ui, self.base, self.variant, self.selected, state, radius) + } +} + +/// 画一个 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 marker = spec.marker; + let forced = spec.state; + let base = spec.base; + + // 文字/图标色只看「选中 + 禁用」（A1：Filter/Input 的 label 色在 hover/focus/pressed 不变）， + // 所以这里静态求值；容器（含状态层）在样式闭包里跟态走。档位的判据在 `Chip::paint` 一处 + // （M206：当前项标记走 `paint::current_item`——**不是**禁用态。它的不可点性与「忙/不可用」 + // 是两件事：前者是「已经选中的那个」（选中配色），后者是「暂不可用」（38% 文字））。 + let at_rest = spec.paint(ui); + + 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::(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::(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| { + // 标记不吃五态：没有可点性就没有反馈（`--force-state` 也不该把它画成 hover）。 + let paint = if marker { + paint::current_item(ui, geometry.radius) + } else { + let state = forced.unwrap_or_else(|| Interaction::from_status(status)); + paint::chip(ui, base, 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..26f0581 --- /dev/null +++ b/crates/app-iced/src/components/selection/geometry.rs @@ -0,0 +1,259 @@ +//! 选择类家族的**几何**：值要么来自令牌，要么在此登记 G 编号（不散落在组件里）。 +//! +//! ## 参考值 → 落点 +//! +//! | # | 量 | 参考值 | 来源 | 落点 | +//! |---|---|---|---|---| +//! | 18.1 | Checkbox 外框 / 圆角 | 官方 **20×20** / **2**；**本项目取规格卡 18×18 / rx4** | `[源]` `Checkbox.kt:737-738` + 规格卡 `rect 18×18 rx4` | `inkcat::metrics::CHECKBOX` | +//! | 18.2 | Checkbox 描边 | **2**（选中时 0） | `[源]` `UnselectedOutlineWidth` / 规格卡 `stroke-width=2` | `inkcat::metrics::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**；**本项目取规格卡 18 Ø** / 2 | `[源]` `IconSize` / `RadioStrokeWidth` + 规格卡 `r=9` | `inkcat::metrics::RADIO` | +//! | 19.2 | Radio 内点 | **10**（不是 12） | `[源]` `DotSize=12`，绘制半径 12/2−2/2=5；规格卡 `r=5` 同为 10 Ø | `inkcat::metrics::RADIO_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::inkcat::metrics as inkcat; +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：**18×18** / 圆角 **4** / 描边 2 / 状态层 Ø40（M229 取规格卡口径，见模块表）。 + /// + /// 与官方 20×20 / 2dp 差 2px 与 2dp：规格卡画的是 `rect 18×18 rx4`，M228 的 `inkcat` 把这条 + /// 差异登记为「换肤时取 `CHECKBOX`」。4 是 `ShapeScale` 的刻度值，所以走容器层不违反 D32。 + pub fn checkbox(ui: &Ui) -> Self { + let metrics = metrics(Component::Checkbox); + let spec = inkcat::CHECKBOX; + Self { + side: spec.width, + stroke: inkcat::CHECKBOX_STROKE, + state_layer: metrics.state_layer, + hit: ui.metrics().touch_target, + gap: metrics.gap, + radius: spec.radius_px(), + // Checkbox 没有内点（内点是 radio 的语言，§19.6 明令两者不许混用） + inner_dot: 0.0, + } + } + + /// Radio：**18 Ø** / 环线 2 / 内点 **10** / 状态层 Ø40；圆角是**真圆**（`ShapeScale::Full`）。 + pub fn radio(ui: &Ui) -> Self { + let metrics = metrics(Component::Radio); + let spec = inkcat::RADIO; + Self { + side: spec.width, + stroke: inkcat::RADIO_RING, + state_layer: metrics.state_layer, + hit: ui.metrics().touch_target, + gap: metrics.gap, + radius: spec.radius_px(), + // 内点 **10**（§19.2：12 是含描边前的名义值，绘制半径 = 12/2 − 2/2 = 5）。 + // 规格卡实测同样是 10，所以这里取 `inkcat::RADIO_DOT`。 + inner_dot: inkcat::RADIO_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..11273ed --- /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/.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::>(); + + 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 **18×18 圆角 4** 描边 2（向内收）勾 10.8 方头 · \ + radio 外圈 **18** 环线 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..82ed456 --- /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 + 规格卡 | **18×18** / 圆角 **4** / 描边 2（向内收）/ 勾 10.8dp 方头 / Ø40 状态层 / 命中 48 | +//! | [`Radio`] | `research/15` §19 + 规格卡 | 外圈 **18** / 环线 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 +//! .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..31ca3e4 --- /dev/null +++ b/crates/app-iced/src/components/selection/paint/check.rs @@ -0,0 +1,89 @@ +//! Checkbox 的角色映射（`research/15` §18.2 / §18.7 / §18.8）。 + +use unlucky_design::color::Role; + +use crate::theme::Ui; + +use super::super::super::interaction::{Base, Interaction}; +use super::{disabled_ink, lifted, CheckboxPaint, Frame}; + +/// Checkbox 的外观。 +/// +/// **描边宽度恒 2**（禁用态也是 2，§18.8：禁用不是「变淡变细」）； +/// 选中态没有描边（`SelectedOutlineWidth = 0`，走填充分支）。 +pub fn checkbox( + ui: &Ui, + base: Base, + 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, base, Role::OnSurface)), + outline: (!selected).then(|| disabled_ink(ui, base, 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..369cc1d --- /dev/null +++ b/crates/app-iced/src/components/selection/paint/chip.rs @@ -0,0 +1,114 @@ +//! 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::{Base, 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, + base: Base, + 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, base, Role::OnSurface); + return ChipPaint { + frame: Frame { + fill: selected.then(|| disabled_container(ui, base)), + outline: (!selected).then(|| disabled_container(ui, base)), + 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, base, 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), + } +} + +/// 「**当前项**」标记的外观（M206）：**就是选中 chip 的那一套**，一个像素都不另起一套。 +/// +/// 为什么要一个具名入口而不是让调用点自己拼 `chip(.., Filter, true, Enabled, ..)`： +/// +/// 1. 这个语义（「这行就是当前生效的那个」）此前被画成了 [`super::super::Chip::badge`] 的 +/// **禁用**配色（`OnSurface`@38% 叠 surface，M204 实测 **1.84:1 浅 / 2.28:1 深**）——那是 +/// 「暂不可用」的语汇，而当前项不是不可用，它是**已经选中的那个**。修法不是给禁用配色调亮， +/// 而是让当前项改用**选中**的语汇； +/// 2. 与左侧导航里相邻的「下载」组的选中 chip（`Chip::filter(.., true, ..)`，容器 +/// `SecondaryContainer`、文字 `OnSecondaryContainer`，实测 **7.21:1 浅 / 7.21:1 深**） +/// **同族**：两页表达「选中」只用一套颜色，用户不用在两页之间切换心智模型。身份由 +/// `pages::settings::java::tests::marker` 的 +/// `the_current_default_marker_speaks_the_download_groups_language` 钉住——谁把其中一页 +/// 改成另一套配色，那条立刻红。具体的 8 bit 色值不写在这里：`tests/no_hardcoded_tokens.rs` +/// 连注释里的十六进制色值也拦，色值只该在报告与令牌表里出现。 +/// +/// 与选中 chip 的唯一差别**不在颜色**：标记没有消息（`on_press == None`），所以它不吃 hover / +/// pressed / disabled 五态（见 `Chip::current` 的文档）。对比度下限是 [`crate::components::selection::paint`] +/// 同一条正文口径（WCAG AA 4.5:1，`unlucky_design::palette::wcag::AA_TEXT`）。 +/// +/// 与选中 chip 的唯一差别**不在颜色**：标记没有消息（`on_press == None`），所以它不吃 hover / +/// pressed / disabled 五态（见 `Chip::current` 的文档）。对比度下限是 [`crate::components::selection::paint`] +/// 同一条正文口径（WCAG AA 4.5:1，`unlucky_design::palette::wcag::AA_TEXT`）。 +pub fn current_item(ui: &Ui, radius: f32) -> ChipPaint { + chip( + ui, + Base::CANVAS, + ChipVariant::Filter, + true, + Interaction::Enabled, + radius, + ) +} 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..ec4331a --- /dev/null +++ b/crates/app-iced/src/components/selection/paint/mod.rs @@ -0,0 +1,157 @@ +//! 选择类家族的**角色映射**：`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, Base, Interaction}; + +mod check; +mod chip; +mod radio; +mod switch; + +pub use check::{checkbox, checkbox_layer_role}; +pub use chip::{chip, current_item, 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, + /// 描边色；`None` = 不画描边。 + pub outline: Option, + /// 描边宽度（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, +} + +/// Switch 的外观：轨道 + 滑块 + 滑块内图标。 +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct SwitchPaint { + /// 轨道（52×32）。 + pub track: Frame, + /// 滑块。 + pub thumb: Color, + /// 滑块内图标（16）；`None` = 不画（未选中时官方色与轨道同色，画了也看不见）。 + pub icon: Option, +} + +/// Chip 的外观：容器 + 文字/图标。 +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct ChipPaint { + /// 容器。 + pub frame: Frame, + /// 文字。 + pub label: Color, + /// 前/后置图标。 + pub icon: Color, +} + +/// 状态层颜色：`content` 角色 @ 该态的 α 叠在 **`base`（控件脚下的底）** 上 +/// （不透明；α 的唯一实现点是 [`interaction::overlay_color`]，本目录零 α 字面量）。 +/// +/// M234 复审 P2-3：禁用支跟了 `base`，hover/focus/pressed 这一支却仍写死 `Role::Surface` +/// —— 卡片里的 checkbox/radio/chip 抬起来时会把状态层叠在画布色上（口径不一致比那 1/255 的 +/// 数值更麻烦）。现在两支同源。 +pub fn state_layer(ui: &Ui, base: Base, state: Interaction, content: Role) -> Option { + interaction::overlay_color(ui, state, content, base.role()) +} + +/// `OnSurface`@12% 叠 `base`（**容器**禁用色：Switch 轨道、Chip 未选中描边）。 +/// +/// `base` 是控件**脚下那一层的底**（M234）：画布 = [`Base::CANVAS`]、卡片 = +/// `surfaces::elevated::BASE`。M229 之前这里写死 `Role::Surface`，卡片里的禁用 chip +/// 于是把 12% 叠在画布色上。 +/// +/// 注意：Checkbox「选中且禁用」的**填充**不是这个 12%，A1 的 +/// `SelectedDisabledContainerOpacity = 0.38` → 见 [`disabled_ink`]（复审 P2-3）。 +pub(super) fn disabled_container(ui: &Ui, base: Base) -> Color { + interaction::disabled_colors(ui, base).0 +} + +/// 内容禁用色：`role` @38% 叠在 `base` 上（`on_container = false`）。 +pub(super) fn disabled_ink(ui: &Ui, base: Base, role: Role) -> Color { + interaction::disabled_content_over_role(ui, base, 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, base: Base, state: Interaction) -> Color { + if state.is_disabled() { + disabled_ink(ui, base, 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..da0112c --- /dev/null +++ b/crates/app-iced/src/components/selection/paint/radio.rs @@ -0,0 +1,49 @@ +//! Radio 的角色映射（`research/15` §19.3 / §19.4 / §19.5）。 + +use unlucky_design::color::Role; + +use crate::theme::Ui; + +use super::super::super::interaction::{Base, Interaction}; +use super::{disabled_ink, lifted, Frame, RadioPaint}; + +/// Radio 的外观。 +/// +/// **选中态 hover 不换色**：环与点在四态里都是 `Primary`（只有状态层变）。 +pub fn radio( + ui: &Ui, + base: Base, + selected: bool, + state: Interaction, + radius: f32, + stroke: f32, +) -> RadioPaint { + let ink = if state.is_disabled() { + disabled_ink(ui, base, 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..5c905c5 --- /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, Base, Interaction}; +use super::super::geometry::SwitchGeometry; +use super::{disabled_container, disabled_ink, lifted, Frame, SwitchPaint}; + +/// Switch 的外观。 +pub fn switch(ui: &Ui, base: Base, 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, base); + 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, base, Role::OnSurface)), + } + } else { + SwitchPaint { + track: Frame { + fill: Some(ui.color(Role::SurfaceContainerHighest)), + outline: Some(container), + stroke: geometry.track_stroke, + radius, + }, + thumb: disabled_ink(ui, base, 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 { + 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..b22f7dd --- /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 { + 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 { + 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::>() + .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::() / square; + (0.5..=1.0).contains(&t) + && (0..3) + .map(|i| (offset[i] - t * axis[i]).powi(2)) + .sum::() + .sqrt() + <= 14.0 +} + +/// 「墨迹块」：`fill` 与「底色→fill 的混色」都算墨，按外接框尺寸筛。 +/// +/// 踩过的两个坑：① 按「精确色」连通会把圆形的环切成碎片（每片面积很小，量不到内点）； +/// ② 按「更接近 fill 还是底色」判会让**另一种深色墨**混进来（`OnSurfaceVariant` 比 `Primary` +/// 更接近深色，于是未选中的框被当成 18×18 的 Primary 块）。所以判据是「落在混色线上」。 +pub(super) fn ink_boxes( + shot: &Shot, + color: Color, + under: Color, + min: usize, + max: usize, +) -> Vec { + 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 { + let mut ink: Option = 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..96ac5b8 --- /dev/null +++ b/crates/app-iced/src/components/selection/probe.rs @@ -0,0 +1,327 @@ +//! 选择类家族的**渲染层**几何断言：对着真截图量像素（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, Base, 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 就说明描边 + // 画到了框外。只数「18×18 有几块」的时候，「把其中一格放大成 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, Base::CANVAS).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, Base::CANVAS, 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：18×18 的禁用块不许是 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..cc93b8e --- /dev/null +++ b/crates/app-iced/src/components/selection/radio.rs @@ -0,0 +1,167 @@ +//! Radio button（`research/15` §19 + 规格卡）：外圈 **18** / 环线 **2** / 内点 **10**（不是 12）/ +//! 选中环+点 `Primary` / 未选中环 `OnSurfaceVariant`（hover 提到 `OnSurface`）/ Ø40 状态层。 +//! +//! ## 为什么它不是「基于 Checkbox 画的」 +//! +//! §19.6 明令：Radio **只能**是「2px 环 + 实心内点」，Checkbox **只能**是「2px 方框 + 勾/横」； +//! 两者尺寸相同（**18**）但形状语言不同，禁止混用。所以本文件是独立实现，**没有** import +//! `super::checkbox`（gallery 的 probe 另有一条断言：radio 的墨迹里不得出现方角像素）。 +//! +//! ## 几何怎么落到像素 +//! +//! 环：**18×18** 容器 + `Border { width: 2, radius: 9 }`。iced 的 quad 渲染器把描边路径向内缩 +//! 半个线宽（半径 9−1=8、路径外接 16），再以 2 描边 → 外缘正好 18、内缘 14。这与 Compose +//! `RadioButton.kt` 的「环半径 = side/2 − 1 且描边居中 → 外缘正好 side」逐像素同源， +//! 只看 side 取 18（规格卡 `r=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::{Base, 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, + state: Option, + /// 脚下那一层的底（M234，禁用态合成用）。 + base: Base, +} + +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, + base: Base::CANVAS, + } + } + + /// 禁用的单选框（无消息）。 + pub fn disabled(label: &'a str, selected: bool) -> Self { + Self { + label, + selected, + on_select: None, + state: None, + base: Base::CANVAS, + } + } + + /// 强制视觉态（gallery 取证用；运行期不要调）。 + pub fn state(mut self, state: Interaction) -> Self { + self.state = Some(state); + self + } + + /// **告诉单选框它踩在什么底上**（M234）：禁用态的 38% 环/内点叠在这个底上。 + pub fn base(mut self, base: impl Into) -> Self { + self.base = base.into(); + 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 base = spec.base; + let source = StateSource::new(spec.state, spec.on_select.is_some()); + + // 内点与环的颜色与 hover/pressed 无关（A1：选中态四态都是 `Primary`）， + // 只随「选中 + 禁用」变 —— 所以点的颜色在这里静态求值即可。 + let at_rest = paint::radio(ui, base, 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, base, 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, base, 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, base, 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, + live: Option>>, + 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, 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, + 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!( + "", + 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> { + 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..3dcec5b --- /dev/null +++ b/crates/app-iced/src/components/selection/switch.rs @@ -0,0 +1,190 @@ +//! 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::{Base, 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, + state: Option, + /// 脚下那一层的底（M234，禁用态合成用）。 + base: Base, +} + +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, + base: Base::CANVAS, + } + } + + /// 禁用的开关（无消息）。 + pub fn disabled(label: &'a str, value: bool) -> Self { + Self { + label, + value, + on_toggle: None, + state: None, + base: Base::CANVAS, + } + } + + /// 强制视觉态（gallery 取证用；运行期不要调）。 + pub fn state(mut self, state: Interaction) -> Self { + self.state = Some(state); + self + } + + /// **告诉开关它踩在什么底上**（M234）：禁用态的 12% 轨道 / 38% 滑块叠在这个底上。 + pub fn base(mut self, base: impl Into) -> Self { + self.base = base.into(); + 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 base = spec.base; + let source = StateSource::new(spec.state, spec.on_toggle.is_some()); + + // 滑块内的勾：颜色只随选中/禁用变（A1 的 `Selected*IconColor` 都是 `OnPrimaryContainer`）， + // 所以静态求值；未选中态官方图标色 = 轨道色（画了也看不见），因此不画。 + let at_rest = paint::switch(ui, base, 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::(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, base, 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, base, 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, base, 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..591726a --- /dev/null +++ b/crates/app-iced/src/components/selection/tests.rs @@ -0,0 +1,339 @@ +//! 选择类家族的单测：几何取自令牌、角色取自 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, Base, Interaction}; + +mod chip; +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); + // M229：取规格卡的 18×18 / rx4（官方 20×20 / 2dp，登记在 `inkcat` 模块）。 + assert_eq!(g.side, 18.0, "规格卡 rect 18×18"); + assert_eq!(g.radius, 4.0, "规格卡 rx=4（ShapeScale::ExtraSmall）"); + 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 × 18 = 10.8（比例不变，边长换成规格卡的 18） + assert!((g.check_span() - 10.8).abs() < 0.001, "18.4：勾横向 10.8dp"); + // 方头外扩：每端 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 - 13.63).abs() < 0.05, + "墨迹跨度 ≈13.63（10.8 + 2×1.41）" + ); +} + +/// §19.1 / §19.2：Radio 外圈 **18**（规格卡）、环线 2、**内点 10 不是 12**、真圆。 +#[test] +fn radio_inner_dot_is_ten_not_twelve() { + let ui = ui(); + let g = ControlGeometry::radio(&ui); + // M229：外圈取规格卡的 18 Ø（官方 20 Ø，登记在 `inkcat` 模块）。 + assert_eq!(g.side, 18.0, "规格卡 r=9 ⇒ 直径 18"); + assert_eq!(g.stroke, 2.0, "19.1：环线 2px"); + assert_eq!(g.radius, 9.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, + Base::CANVAS, + 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, Base::CANVAS, 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, + Base::CANVAS, + 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, + Base::CANVAS, + 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, + Base::CANVAS, + 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, Base::CANVAS, Role::OnSurface, false); + let container12 = interaction::disabled_colors(&ui, Base::CANVAS).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, Base::CANVAS, 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, + Base::CANVAS, + 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, + Base::CANVAS, + 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, Base::CANVAS, 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, Base::CANVAS, 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, Base::CANVAS, 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, Base::CANVAS, true, Interaction::Disabled); + assert_eq!( + disabled.thumb, + ui.color(Role::Surface), + "A1：DisabledSelectedHandleColor=Surface" + ); +} diff --git a/crates/app-iced/src/components/selection/tests/chip.rs b/crates/app-iced/src/components/selection/tests/chip.rs new file mode 100644 index 0000000..b57a60a --- /dev/null +++ b/crates/app-iced/src/components/selection/tests/chip.rs @@ -0,0 +1,92 @@ +//! Chip 角色与状态层的单测（M234 从 `selection/tests.rs` 纯搬移，守 400 行硬线）。 +//! +//! 搬移零改动：判据与注释一字未动，只是**换文件**（`tests.rs` 加了 `.base(..)` 之后到 422 行）。 + +use super::*; + +/// §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, + Base::CANVAS, + 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, + Base::CANVAS, + 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, + Base::CANVAS, + 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, + Base::CANVAS, + 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, Base::CANVAS, 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, Base::CANVAS, Interaction::Hovered, Role::OnSurface).unwrap(); + let pressed = + paint::state_layer(&ui, Base::CANVAS, Interaction::Pressed, Role::OnSurface).unwrap(); + assert_ne!(hover, pressed); +} diff --git a/crates/app-iced/src/components/surfaces/elevated.rs b/crates/app-iced/src/components/surfaces/elevated.rs new file mode 100644 index 0000000..54a59d1 --- /dev/null +++ b/crates/app-iced/src/components/surfaces/elevated.rs @@ -0,0 +1,151 @@ +//! **ELEVATED CARD**（规格卡 `CARD / DIALOG / SNACKBAR / LIST` 的第一个方框）。 +//! +//! ## 规格卡原值（`DevDocs/artifacts/components-ink.svg`，`[spec]`） +//! +//! | 项 | 值 | 出处 | +//! |---|---|---| +//! | 方框 | 300×150、**rx=16**（`inkcat::metrics::CARD`） | `rect x=64 y=1312 rx=16` | +//! | 底色 | **`SurfaceContainer`**（Ink 板上比画布 `Surface` 亮一档） | 规格卡卡底那一格的 `fill` | +//! | 内边距 | **24**（文字 `x=88` − 框 `x=64`） | 同上 | +//! | 描边 | **无**（`stroke="none"`） | 同上 | +//! | 上标注 | **11 / 600**（`LabelSmall` + 半粗，字距 1） | `ELEVATED CARD` 那行 | +//! | 标题 | **16 / 400**（`BodyLarge`） | `Night bridge, bright rails.` 那行 | +//! | 副文案 | 13 / 400 → **14**（`BodyMedium`；13 落在 12/14 之间，按 `inkcat::type_scale` 取较大档） | `night / bridge / cat` 那行 | +//! +//! ## 与 `pages::frame::card`（描边卡）的分工 +//! +//! - [`card`]：**靠层级差站立**的卡（无描边、`SurfaceContainer` 底、16 圆角）。规格卡的 +//! `ELEVATED CARD` 就是这一档，实例页的元信息卡用它； +//! - `pages::frame::card`：描边卡（`OutlineVariant` 1px + 卡片层底），大面积表单容器用它。 +//! +//! 两种卡并存是**有意的**：规格卡只画了 elevated 一种，而桌面端的长表单需要「弱一点的容器」 +//! （满屏都是 16 圆角 + 容器底，分隔线会看起来像浮块）。哪种卡用在哪儿由本节决定，不是随手挑。 + +use iced::widget::text::LineHeight; +use iced::widget::{column, container, text}; +use iced::{Background, Border, Element, Length, Padding, Pixels}; + +use unlucky_design::color::Role; +use unlucky_design::spacing::Space; +use unlucky_design::typography::{TypeRole, TypeStyle, Weight}; + +use crate::theme::Ui; + +use super::super::interaction::Base; + +/// 卡片的底（**这个容器画什么，子控件的禁用态就叠什么**）。 +/// +/// 卡内控件的禁用色必须拿这个常量，不许自己写 `Role::Surface`：M234 之前 8 个调用点全传 +/// 画布色，卡片里的禁用按钮于是把 10% 叠在画布上（M223 的「CR 1.05、形丢失」）。 +/// 与 [`card`] 的 `background` 用同一个 `Role`，改色不会漂。 +pub const BASE: Base = Base::of(Role::SurfaceContainer); + +/// ELEVATED CARD 的内边距：**20**（= `LayoutMetrics::card_padding`）。 +/// +/// 为什么不是规格卡量到的 **24**（卡片文字 `x=88` − 框 `x=64`）：本组件唯一的消费者是实例页的 +/// 元信息卡，外框是 `META_CARD_MIN_WIDTH`（160），卡内必须放下最长的值串（**12px 下实测 118px**； +/// 同一个串在 14px 下是 138px，见 [`TITLE_ROLE`]）。 +/// 24 ⇒ 内宽 112 ⇒ 值串折行 ⇒ 同排卡底不齐（M229 复审 P1-2 的现场）；20 ⇒ 内宽 120 ≥ 118， +/// 且**不动卡片宽度契约**（`pages/layout.rs` 的 160 一个字没改）。 +/// +/// 登记为 **Structural** 偏离：规格卡的 24 是 300×150 展示卡的数，密集网格用 20； +/// 将来真做展示卡就再开一档（现在的 `PAD` 名字对应的是密集卡，不是规格卡原值）。 +pub const PAD: f32 = 20.0; + +/// 值的字级：`BodySmall`（12/16）。 +/// +/// 展示卡的内距与字号（24 + `BodyLarge` 16）在 160 外框里放不下值串；14 档也不够：实测最长的 +/// 元信息值（时戳 `2026-10-29 19:22 UTC`）在 14px 下墨水宽 **138px**，而 160 − 2×20 = 120。 +/// 12px 下它就是 118px 级 ⇒ 放得下（余量见 `pages/instances/tests.rs` 的断言）。 +/// 「内距」与「字级」是一对：只改一个就会重新折行。 +pub const TITLE_ROLE: TypeRole = TypeRole::BodySmall; + +/// 一个 ELEVATED CARD 方框（只管壳：底、圆角、内边距；**无描边**）。 +/// +/// 消息类型与被包的内容同型，所以它能被任何页面复用（实例页 / 外观页 / 账户页各用自己的 +/// `Message`）——这是「组件不 import 业务消息」那条契约的落地方式。 +pub fn card<'a, M: 'a>(ui: &'a Ui, content: impl Into>) -> Element<'a, M> { + let shape = ui.card_shape(); + container(content) + .width(Length::Fill) + .padding(Padding::from([PAD, PAD])) + .style(move |_theme| container::Style { + // 规格卡的卡底是 **surface-container**（不是 `surface-container-low`）： + // 层级靠与画布（`surface`）的 tone 差表达，不靠描边。 + // 子控件的禁用态拿同一个角色（[`BASE`]）合成，两边不会漂。 + background: Some(Background::Color(ui.color(BASE.role()))), + border: Border { + radius: ui.radius_dp(shape), + ..Border::default() + }, + ..container::Style::default() + }) + .into() +} + +/// 一张规格卡的三段文字：上标注（可选）/ 标题 / 副文案（可选）。 +#[derive(Debug, Clone, Copy)] +pub struct Texts<'a> { + /// 上标注（`ELEVATED CARD` 那种小字标签）。 + pub overline: Option<&'a str>, + /// 值 / 标题（字级是 [`TITLE_ROLE`] = **12/400**）。 + pub title: &'a str, + /// 副文案（`BodyMedium` 14/400）。 + pub support: Option<&'a str>, +} + +/// 三段式内容（上标注 11/600 + 值 [`TITLE_ROLE`] **12/400** + 副文案 14/400，行间 4）。 +pub fn texts<'a, M: 'a>(ui: &'a Ui, parts: Texts<'a>) -> Element<'a, M> { + let mut stack = column![].spacing(ui.space(Space::X1)); + + if let Some(overline) = parts.overline { + stack = stack.push(role_text( + ui, + overline_style(), + overline, + Role::OnSurfaceVariant, + )); + } + stack = stack.push(role_text( + ui, + ui.style(TITLE_ROLE), + parts.title, + Role::OnSurface, + )); + if let Some(support) = parts.support { + stack = stack.push(role_text( + ui, + ui.style(TypeRole::BodyMedium), + support, + Role::OnSurfaceVariant, + )); + } + + stack.width(Length::Fill).into() +} + +/// 上标注的排版（`LabelSmall` 11/16，字重 **600**：规格卡 `font-weight=600`； +/// M3 的 `LabelSmall` 是 500，`emphasized` 是 700 —— 两个都不是 600，所以在这里显式给 600）。 +pub fn overline_style() -> TypeStyle { + TypeStyle { + weight: Weight::SemiBold, + ..TypeRole::LabelSmall.style() + } +} + +fn role_text<'a, M: 'a>( + ui: &'a Ui, + style: TypeStyle, + content: &'a str, + role: Role, +) -> Element<'a, M> { + text(content) + .size(style.size_px) + .line_height(LineHeight::Absolute(Pixels(style.line_height_px))) + .font(ui.font_of(style)) + .color(ui.color(role)) + .into() +} + +#[cfg(test)] +mod tests; diff --git a/crates/app-iced/src/components/surfaces/elevated/tests.rs b/crates/app-iced/src/components/surfaces/elevated/tests.rs new file mode 100644 index 0000000..aebe9b9 --- /dev/null +++ b/crates/app-iced/src/components/surfaces/elevated/tests.rs @@ -0,0 +1,92 @@ +//! ELEVATED CARD 的几何/排版断言（对着规格卡原值，不看渲染结果）。 +//! +//! 抓得住：圆角退回组件表的 12、内距/字级被改回规格卡的 24/16（元信息卡会折行）、 +//! 上标注变成 500/700 这些「悄悄改数」。 +//! 抓不住：底色对不对（要看 `Ui::color(SurfaceContainer)` 的来源，那条由 `theme` 的色板测试守）、 +//! 以及卡在页面里好不好看（D30 视觉判定）。 + +use super::*; +use unlucky_design::shape::ShapeScale; + +const FAMILIES: crate::theme::Families = crate::theme::Families { + text: "Segoe UI Variable Text", + display: "Segoe UI Variable Display", + mono: "Cascadia Mono", +}; + +fn ui(flavor: unlucky_design::color::SchemeFlavor) -> Ui { + Ui::with_platform( + flavor, + unlucky_design::typography::Platform::Windows, + FAMILIES, + ) +} + +#[test] +fn the_card_takes_the_spec_corner_and_the_tile_padding() { + let ui = ui(unlucky_design::color::SchemeFlavor::Dark); + assert_eq!(ui.card_shape(), ShapeScale::Large, "规格卡 rx=16"); + assert_eq!(ui.card_box().radius_px(), 16.0); + // 内距 **20**（不是规格卡的 24）：24 会让元信息卡的值串折行（复审 P1-2）， + // 20 与描边卡同源（`LayoutMetrics::card_padding`），卡片宽度契约不变。 + assert_eq!(PAD, 20.0); + assert_eq!( + PAD, + unlucky_design::spacing::LayoutMetrics::DESKTOP.card_padding + ); + assert_eq!(PAD % unlucky_design::spacing::GRID, 0.0, "仍在 4px 栅格上"); +} + +#[test] +fn the_typography_matches_the_spec_rows() { + let style = overline_style(); + assert_eq!(style.size_px, 11.0, "上标注 11px"); + assert_eq!(style.weight, Weight::SemiBold, "上标注 600（不是 500/700）"); + + // 值的字级：**12**（BodySmall），不是规格卡展示卡的 16 —— 16px 下时戳墨水宽 138px， + // 而 160 外框减两倍内距只有 120（复审 P1-2）。这条与 `pages/instances/tests.rs` 的不等式同源。 + let title = TITLE_ROLE.style(); + assert_eq!(TITLE_ROLE, TypeRole::BodySmall); + assert_eq!(title.size_px, 12.0, "值 12px"); + assert_eq!(title.weight, Weight::Regular, "值 400"); + + let support = TypeRole::BodyMedium.style(); + assert_eq!(support.size_px, 14.0, "副文案 13 → 取较大档 14"); + assert_eq!(support.weight, Weight::Regular); +} + +/// 卡片是**靠层级差站立**的：底色必须是 `SurfaceContainer`（画布上一档），不是画布色本身。 +#[test] +fn the_card_surface_sits_one_step_above_the_canvas() { + for board in unlucky_design::color::BrandBoard::ALL { + let scheme = board.scheme(); + assert_ne!( + board.get(Role::SurfaceContainer), + board.get(Role::Surface), + "{}：卡底与画布同色，卡会「消失」", + board.name() + ); + // 无描边：卡的存在感只能来自这一档色差，所以必须 > 1.0（差多少属观感，D30 判）。 + let card_vs_canvas = scheme.contrast(Role::SurfaceContainer, Role::Surface); + assert!( + card_vs_canvas > 1.0, + "{}：卡底对画布 {card_vs_canvas:.3}:1，看不出层级", + board.name() + ); + } +} + +/// **M234**：卡片的底在代码里只出现两次——[`card`] 的 `background` 与导出的 [`BASE`]， +/// 这两处必须同角色，否则卡里的禁用控件会合到另一层底上。 +/// +/// 抓得住：有人只改 `BASE`（或只改 `card`）导致两边漂开；抓不住：「`card()` 真的用了 +/// `BASE` 画底」这件事（`container::Style` 闭包不可内省，只能靠代码审阅与 +/// `gallery::probe` 的 disabledbase 段——那边的像素判据要求卡列里出现「叠卡片底」的禁用容器）。 +#[test] +fn the_card_base_constant_is_the_role_the_card_paints() { + assert_eq!( + super::BASE.role(), + Role::SurfaceContainer, + "`elevated::BASE` 必须就是卡底的角色（`card()` 的 background 用的是同一个值）" + ); +} diff --git a/crates/app-iced/src/components/surfaces/mod.rs b/crates/app-iced/src/components/surfaces/mod.rs new file mode 100644 index 0000000..bb21590 --- /dev/null +++ b/crates/app-iced/src/components/surfaces/mod.rs @@ -0,0 +1,7 @@ +//! 面类家族（目前只有 **ELEVATED CARD**，规格卡 `CARD / DIALOG / SNACKBAR / LIST` 的第一格）。 +//! +//! 为什么单开一个家族而不是塞进 `feedback`：`feedback` 是「系统对用户动作的回应」（进度 / 对话框 / +//! snackbar / 空态），卡是**静态容器**，语义上属于版式而不是反馈。家族边界写在这里，后来加 +//! 「带描边卡 / 列表行药丸」时按语义归位，不要因为「都在同一个规格卡小节里」就合进 `feedback`。 + +pub mod elevated; diff --git a/crates/app-iced/src/fonts.rs b/crates/app-iced/src/fonts.rs new file mode 100644 index 0000000..e1b123e --- /dev/null +++ b/crates/app-iced/src/fonts.rs @@ -0,0 +1,378 @@ +//! 字体基座（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`（见交接文档的启动日志）。 + +//! ## 不做什么 +//! +//! 本模块只做「系统字体优先」这一半，也没有能力判断 CJK 字形覆盖（那是 `ttf-parser` 查 cmap 的活， +//! M60 Q3 的 spike 做过）。中文字体的下载与注册在 [`install`] / [`cdn`]（M168 实装）。 +//! +//! ## 中文那一半（M92 / D28 后半 / M168 实装下载） +//! +//! 语言探测 + 「中文环境有没有中文字体」的判据在 [`cjk`]（判据本体在零依赖的 `unlucky_i18n::font`）， +//! 语言的真值源是 [`crate::platform::locale`]（Windows 上 `reg.exe` 读注册表，零 FFI）， +//! 结论作为 [`Resolved::cjk`] 进同一行启动日志。**英文环境结论恒为 `NotNeeded`**：不要求中文字体、 +//! 不下载任何字体（系统里已有的 CJK 族照旧躺在 iced 的字体库里，我们既不注册新的也删不掉——那是 +//! cosmic-text 的全局状态，不是本模块能管的事）。 +//! +//! 判出 `NeedsDownload` 之后**真的去下载**这件事在 [`install`]（M168）： +//! +//! ```text +//! fonts::resolve_with / fonts::cjk_for → 判据（这里） +//! fonts::install::after_probe → 只有 NeedsDownload 才发起（后台线程） +//! fonts::cdn::CdnFetcher → core::download 的共享引擎（sha256 校验 + 缓存） +//! fonts::install::register_into_font_system → 注册进 iced，随后的帧立刻能用中文字形 +//! ``` +//! +//! 两个入口都只是**发起**：17 MiB 的字体不许挡在开窗之前，失败也只降级（继续用系统字体）。 + +pub mod cdn; +mod cjk; +pub mod install; + +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::>() + .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::>() + .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) +} + +/// Termux 上把 Android 的系统 CJK 字体注册进 cosmic-text 的字体库。 +/// +/// 这套 glibc 构建跑在 Termux 里（`target_os = "linux"`），fontdb 只扫 Linux 的常规字体目录， +/// Android 的 `/system/fonts` 不在其中——不注册的话中文实例名与界面文案全是方框。 +/// 第一次调用加载一次；找不到任何候选字体时静默放过（由既有回退链兜底）。 +fn register_termux_fonts() { + use std::sync::OnceLock; + + use unlucky_core::platform::paths::ProcessEnv; + use unlucky_core::platform::termux; + + static REGISTERED: OnceLock<()> = OnceLock::new(); + REGISTERED.get_or_init(|| { + if !termux::is_termux(&ProcessEnv) { + return; + } + const CANDIDATES: &[&str] = &[ + "/system/fonts/NotoSansCJK-Regular.ttc", + "/system/fonts/NotoSansCJKSC-Regular.otf", + "/system/fonts/DroidSansFallback.ttf", + ]; + let Ok(mut font_system) = iced::advanced::graphics::text::font_system().write() else { + return; + }; + let db = font_system.raw().db_mut(); + for path in CANDIDATES { + if db.load_font_file(path).is_ok() { + return; + } + } + }); +} + +/// 同 [`resolve`]，但把配置里 `ui.language` 的显式值喂给中文策略（D28 的第一级）。 +/// +/// 只做「取真实字体库 + 交给 [`resolve_with_faces`]」两件事：真正的求值在后者，于是 +/// **「启动这一拍不发起下载」这件事有测试可打**（复审 r3 P2-2：`system_faces()` 不可注入， +/// 上一轮的修复没有任何用例守着，把 `after_probe` 加回来整套测试仍绿）。 +pub fn resolve_with(setting: Option<&str>) -> Resolved { + register_termux_fonts(); + resolve_with_faces(setting, system_faces().as_deref()) +} + +/// [`resolve_with`] 的**纯**求值：给定「某族装没装」的字面表，算出 [`Resolved`]。 +/// +/// `faces = None` 表示字体库读不出来（→ 中文策略 `Unprobeable`，不是「缺字体」）。 +/// +/// **这里不发起下载**（复审 r2 P2-2 ① / r3 P2-2）：启动那一拍（`boot.rs` / `pages/harness/app.rs`） +/// 拿到的 `setting` 是 `None`，只按系统 locale 判——zh-locale + 配置 `en_us` 的机器若在这里触发， +/// 就会白下 17 MiB，而随后 `App` 读到配置又把状态翻成「当前界面语言不需要中文字体」。 +/// 唯一的触发点是 [`cjk_for`]（`ui/lang.rs::log_cjk`，那一拍已经知道**生效语言**）。 +/// +/// 这条不变量由 `fonts::tests::resolving_fonts_never_starts_a_download` 守着。 +pub fn resolve_with_faces(setting: Option<&str>, faces: Option<&[Face]>) -> Resolved { + let platform = Platform::current(); + + let is_installed = |family: &str| -> bool { + faces.is_none_or(|faces: &[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)); + + // D28 后半：语言 + 中文环境的中文字体策略。`faces` 的 `None` 在这里是「字体库读不出来」， + // 适配层会把它翻成 `Unprobeable` 而不是「缺字体」（否则会误触发一次 CDN 下载）。 + let cjk_report = cjk::probe_with(setting, faces); + + Resolved { + platform, + families, + weights, + cjk: cjk_report, + } +} + +/// 语言切换后的中文策略重算（M106 判据）+ **唯一**的下载触发点（M168）：`setting` 是配置里 +/// `ui.language` 的**显式值**（`None` = 跟随系统，由 [`crate::platform::locale::SystemLocale`] 决定）。 +/// +/// 为什么需要它：启动那一轮（[`resolve`]）拿不到配置，只按系统 locale 判。用户在英文系统上 +/// 手选「简体中文」时，若不复算，策略会停在 `NotNeeded`——界面文字是中文、字体却没有中文字形， +/// 那就是白块。 +/// +/// **为什么触发只留在这里**（复审 r2 P2-2 ①）：这一拍的 `setting` 与 `LangChoice` 同源 +/// （`ULL_LANG` > 配置 > 系统 locale），也就是「界面实际用哪种语言」的那一份判据。 +/// 放在 [`resolve`] 里就会用「系统 locale」代表「用户选择」，zh-locale + 配置 `en_us` 的机器 +/// 会白下一次 17 MiB。 +/// +/// 两条通道各自靠什么做到「一次都不发」：**出图 harness**（`pages/harness/app.rs`）不经 +/// `App::with_presenter`，它零流量靠的是「[`resolve_with`] 根本不触发」；**`--screenshot`** +/// 走真 `App`，除了同一条不变量，还有 `install::set_offline(true)` 这道闸。别把前者的功劳 +/// 记到 `set_offline` 上（复审 r3 P2-4 ②）。 +pub fn cjk_for(setting: Option<&str>) -> CjkReport { + let report = cjk::probe_with(setting, system_faces().as_deref()); + install::after_probe(report.strategy); + report +} + +/// 一条系统字面（族名 + 字重）。 +/// +/// `pub` 是因为 [`resolve_with_faces`] 把它作为参数暴露出去（那是「启动不发起下载」的唯一 +/// 可测入口，复审 r3 P2-2）——`private_interfaces` 会拦「pub 函数收私有类型」。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub 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::>(); + 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> { + 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/cdn.rs b/crates/app-iced/src/fonts/cdn.rs new file mode 100644 index 0000000..5d022e8 --- /dev/null +++ b/crates/app-iced/src/fonts/cdn.rs @@ -0,0 +1,173 @@ +//! 真实字体下载器（M168）：把 `unlucky_i18n::font` 的 pin 接到 `unlucky_core::download`。 +//! +//! ## 一句话 +//! +//! ```text +//! i18n 的 CjkFont.source（常量：URL 候选 + sha256 + 字节数） +//! ↓ 允许设置改写首选 URL（`ui.font_cdn`） +//! core 的 FontSpec（值） +//! ↓ core::download::font::fetch_blocking（缓存 → 共享引擎 → 复验 → 原子落盘） +//! Vec（交给 install 注册进 iced 的字体系统） +//! ``` +//! +//! 本模块只做三件适配：常量 → 值、缓存根从哪来（[`crate::platform::data`]）、错误类别翻译。 +//! 判据与落盘都不在这里——那两半各有自己的守卫（`i18n::font` 的单测、`core::download::font` 的 +//! 单测）。 +//! +//! ## 「不联网」的三条路 +//! +//! | 情形 | 谁拦住 | +//! |---|---| +//! | 英文环境 / 系统已有字体 | `i18n::font::ensure` 根本不调 [`Fetcher`] | +//! | 同一进程第二次（缓存已在盘上） | `core::download::font` 的缓存分支（零 HTTP） | +//! | 二次启动 | 同上：缓存文件按 `` 命名，命中即不联网 | +//! +//! ## 设置改写只换 URL，不换哈希 +//! +//! `ui.font_cdn` 允许换成国内镜像（整条 URL）。**哈希与字节数仍是内置那一份**：镜像是同一份内容 +//! 的不同出口，给了别的内容就该被拒——宁可不下载，也不把没校验过的字节注册成字体。 + +use std::cell::Cell; +use std::path::PathBuf; + +use unlucky_core::download::font::{self as core_font, FontFetchError, FontSpec}; +use unlucky_i18n::font::{CjkFont, FetchError, Source}; + +use crate::platform::data; + +/// 字体下载器（一个进程用一份就够：无状态，除了缓存根）。 +#[derive(Debug, Clone)] +pub struct CdnFetcher { + cache_root: PathBuf, + spec: FontSpec, + /// 最近一次 `fetch` 是否**真的**命中缓存（`None` = 还没取过）。 + /// + /// 为什么不在调用方「取之前看一眼文件在不在」：那个判据会说谎——缓存文件若已损坏， + /// `core::download::font` 会删掉重下（零网络不成立），而「取之前在不在」仍然是 true。 + /// 复审 r1 次要项点名的就是这个：日志 `from_cache=true` 必须等于「这次没联网」。 + last_from_cache: Cell>, +} + +impl CdnFetcher { + /// 按 pin 建一个下载器（`cache_root` 由调用方给，便于测试与截图通道用临时根）。 + /// + /// # Errors + /// pin 与覆盖设置拼不出自洽的 spec 时返回人话错误（不发请求）。 + pub fn new(font: &CjkFont, cache_root: PathBuf) -> Result { + Ok(Self { + cache_root, + spec: spec_of(font)?, + last_from_cache: Cell::new(None), + }) + } + + /// 缓存文件是不是已经在盘上（只 stat，不做校验）。 + /// + /// 用途只有**诊断**（`[font] cjk-download start … cache_present=`）。它**不是**命中判据： + /// 真正的命中判定在 `core::download::font`（读出来 + 复验哈希与魔数），而「这次有没有联网」 + /// 只看 [`Self::was_cached`]——坏缓存会被删掉重下，那时这个函数仍然会返回 `true`。 + #[must_use] + pub fn has_cached(&self) -> bool { + core_font::cache_path(&self.cache_root, &self.spec).is_file() + } + + /// 最近一次 [`Fetcher::fetch`] 是否零网络命中缓存（`None` = 还没取过）。 + /// + /// 状态行与日志的 `from_cache` 只认这个值；`has_cached()` 只是「文件在不在」，两者不可互换。 + #[must_use] + pub fn was_cached(&self) -> Option { + self.last_from_cache.get() + } + + /// 缓存文件落点（诊断日志用）。 + #[must_use] + pub fn cache_file(&self) -> PathBuf { + core_font::cache_path(&self.cache_root, &self.spec) + } +} + +impl unlucky_i18n::font::Fetcher for CdnFetcher { + fn fetch(&self, _font: &'static CjkFont) -> Result, FetchError> { + let outcome = core_font::fetch_blocking(&self.cache_root, &self.spec).map_err(translate); + self.last_from_cache + .set(outcome.as_ref().ok().map(|fetch| fetch.from_cache)); + outcome.map(|fetch| fetch.bytes) + } +} + +/// i18n 的常量 pin + 设置覆盖 → core 的 `FontSpec`。 +/// +/// # Errors +/// 覆盖值不是 http(s) URL、或 pin 自身不自洽时返回 [`FetchError::Integrity`]。 +pub fn spec_of(font: &CjkFont) -> Result { + let Source::Pinned { + urls, + sha256, + bytes, + } = font.source; + + let mut candidates: Vec = urls.iter().map(|url| (*url).to_owned()).collect(); + if let Some(override_url) = data::font_cdn_override() { + // 覆盖值排在最前（用户显式选了它），内置候选留作后备：覆盖值挂了还能回落到默认镜像。 + candidates.insert(0, override_url); + } + + FontSpec::new(candidates, sha256, bytes) + .map_err(|error| FetchError::Integrity(error.to_string())) +} + +/// core 的三类错误 → i18n 的三类（字符串原样带过去，日志里能看到根因）。 +fn translate(error: FontFetchError) -> FetchError { + match error { + FontFetchError::Network(message) => FetchError::Network(message), + FontFetchError::Integrity(message) => FetchError::Integrity(message), + FontFetchError::Disk(message) => FetchError::Disk(message), + } +} + +#[cfg(test)] +mod tests { + use super::*; + use unlucky_i18n::font::NOTO_SANS_SC; + + /// pin → spec 的搬运：URL 候选、哈希、字节数一个都不许掉。 + /// + /// 抓得住：①漏搬 `sha256`（下载器就会「只要 200 就落盘」）；②把候选列表截成一条（备用镜像 + /// 静默消失）；③字节数被写成 0（大小上限判据失效）。 + /// 抓不住：`ui.font_cdn` 覆盖值在真机上读到什么（那要数据根 + 配置文件；见 `platform::data`）。 + #[test] + fn the_pin_survives_the_trip_to_core() { + let spec = spec_of(&NOTO_SANS_SC).expect("内置 pin 应自洽"); + let Source::Pinned { + urls, + sha256, + bytes, + } = NOTO_SANS_SC.source; + + assert!( + spec.urls.len() >= urls.len(), + "候选不该变少：{:?}", + spec.urls + ); + assert_eq!(spec.sha256, sha256); + assert_eq!(spec.bytes, bytes); + assert_eq!( + spec.urls[spec.urls.len() - urls.len()], + urls[0], + "内置首选不许被挤掉" + ); + } + + /// 缓存命中判定只看文件在不在（**不联网**）：一个刚建的空目录 ⇒ `has_cached() == false`。 + #[test] + fn an_empty_cache_root_is_not_a_hit() { + let dir = std::env::temp_dir().join(format!("ull-cdn-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&dir); + let fetcher = CdnFetcher::new(&NOTO_SANS_SC, dir.clone()).expect("下载器"); + assert!(!fetcher.has_cached()); + assert_eq!(fetcher.was_cached(), None, "还没取过 ⇒ 不知道"); + assert!(fetcher + .cache_file() + .ends_with("cjk-noto-sans-sc-a3041811a78c361b.ttf")); + } +} diff --git a/crates/app-iced/src/fonts/cjk.rs b/crates/app-iced/src/fonts/cjk.rs new file mode 100644 index 0000000..9d5be2a --- /dev/null +++ b/crates/app-iced/src/fonts/cjk.rs @@ -0,0 +1,189 @@ +//! 中文环境的 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，本 crate 不引依赖（M60 Q3 spike 做过）； +//! ②`Strategy::NeedsDownload` 之后的下载与注册（M168 已实装，见 [`super::cdn`] / +//! [`super::install`]：URL 与 sha256 钉在 `unlucky_i18n::font::NOTO_SANS_SC`，本模块只到判据为止）。 +//! +//! ## `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 { + 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/install.rs b/crates/app-iced/src/fonts/install.rs new file mode 100644 index 0000000..afe9f87 --- /dev/null +++ b/crates/app-iced/src/fonts/install.rs @@ -0,0 +1,361 @@ +//! 中文字体下载的**执行与状态**（M168）：谁触发、什么时候触发、结果怎么被看见。 +//! +//! ## 一句话 +//! +//! ```text +//! i18n::font::decide（判据） → Strategy +//! fonts::install::after_probe（触发） → 此刻要不要开始下载（一份进程级状态） +//! fonts::cdn::CdnFetcher（下载） → bytes 或三类错误 +//! fonts::install::register（注册） → iced 的字体系统里多一个族 +//! ``` +//! +//! ## 两个触发点（都在 `fonts.rs`，因为那里是判据的两个调用点） +//! +//! | 入口 | 时机 | 谁来 | +//! |---|---|---| +//! | [`super::resolve_with`] | 启动（按系统 locale / `ULL_LANG`） | `app/boot.rs` | +//! | [`super::cjk_for`] | 设置页切语言（`ui/lang.rs::log_cjk`） | 用户手选中文 | +//! +//! 两条路都只把**判据结论**交给 [`after_probe`]：只有 `NeedsDownload` 才会真的开始下载 +//! （英文环境 / 系统已有字体 / 探测不出，三路一次网络都不发；守卫见 `tests.rs`）。 +//! +//! ## 为什么下载在后台线程而不是启动那一拍 +//! +//! 一份 16.9 MiB 的字体在弱网下要几十秒。启动编排（`app/boot.rs`）是在**开窗之前**同步跑的， +//! 在那里下载等于「点了图标，窗口几十秒不出来」。所以：启动路径只**发起**，窗口照常起来， +//! 状态行（设置页 General 组）与 stderr 日志承担「正在获取 / 完成 / 失败」这三句话。 +//! +//! ## 失败**不是**致命错误 +//! +//! 任何一类失败（网络 / 校验 / 磁盘）都只让状态变成 [`CjkInstall::Failed`]： +//! 界面继续用系统字体（中文用户）+ 系统字体（英文用户），程序照常可用。这正是 D28 的要求 +//! （「下载失败不崩」）。 +//! +//! ## 状态是一份进程级快照 +//! +//! `App` 每秒（心跳）比对一次快照，变了就重建视图模型（设置页那一行因此自己会刷新）。 +//! 为什么不用 iced 的 `Task::stream` 推事件：本 crate 的执行器是 `thread-pool`（`Cargo.toml` +//! 的 feature 决定），推送通道要多一条生命周期不明的流；而「每秒看一眼快照」的代价是一把 +//! 短锁 + 一次比较，且天然不会在窗口关掉之后还往一个死掉的 channel 里写。 +//! +//! ## 截图通道 +//! +//! `ULL_FONT_STATUS=` 可把状态钉成任意一档（`system` / `downloading` / `ready` / `failed:network` +//! / `not-needed` / `unprobeable`），只为了出图——与 `ULL_LANG` / `ULL_APPEARANCE_*` 同一族 +//! 取证开关（D30 可复现：同一份代码出同一张图）。产品路径不设这个变量。 + +use std::sync::{Mutex, OnceLock}; + +use unlucky_i18n::font::{self, FetchError, Fetched, Fetcher, Strategy}; + +/// 失败类别（与 `unlucky_i18n::font::FetchError` 的三类一一对应）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum FetchClass { + /// 网络层。 + Network, + /// 校验层（哈希 / 魔数 / 大小上限）。 + Integrity, + /// 磁盘层。 + Disk, +} + +impl FetchClass { + /// 稳定类别名（日志用；UI 文案按它选 i18n key）。 + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::Network => "network", + Self::Integrity => "integrity", + Self::Disk => "disk", + } + } +} + +impl From<&FetchError> for FetchClass { + fn from(error: &FetchError) -> Self { + match error { + FetchError::Network(_) => Self::Network, + FetchError::Integrity(_) => Self::Integrity, + FetchError::Disk(_) => Self::Disk, + } + } +} + +/// 中文字体这一件的当前状态（设置页那一行与日志共用一份）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum CjkInstall { + /// 还没判定（启动前 / 判据没跑过）。 + Unknown, + /// 英文环境：不需要中文字体（D28 的第一条）。 + NotNeeded, + /// 系统里已有中文字体（含上一次下载后仍在字体库里的那份）。 + System { + /// 命中的族名。 + family: String, + }, + /// 探测不出（拿不到系统字体库）——**不下载**。 + Unprobeable, + /// 正在下载。 + Downloading { + /// 字节数（pin 里的期望值；用来写「16.9 MB」这种可核对的量）。 + bytes: u64, + }, + /// 已就绪（下载完成并注册进字体系统）。 + Ready { + /// 注册后的族名（真从字体库里读回来的，不是常量抄的）。 + family: String, + /// 是否零网络命中缓存。 + from_cache: bool, + }, + /// 失败（三类之一）——**不阻塞**，界面回落到系统字体照常可用。 + Failed { + /// 类别。 + class: FetchClass, + /// 人话原因（日志/诊断用；UI 只按类别选词）。 + message: String, + }, +} + +impl CjkInstall { + /// 是否正在下载（设置页要显示「进行中」，心跳也靠它决定要不要更勤地看图）。 + #[must_use] + pub const fn is_downloading(&self) -> bool { + matches!(self, Self::Downloading { .. }) + } + + /// 一行日志片段（`cjk-install=…`）。 + #[must_use] + pub fn describe(&self) -> String { + match self { + Self::Unknown => "cjk-install=unknown".to_owned(), + Self::NotNeeded => "cjk-install=not-needed".to_owned(), + Self::System { family } => format!("cjk-install=system(\"{family}\")"), + Self::Unprobeable => "cjk-install=unprobeable".to_owned(), + Self::Downloading { bytes } => format!("cjk-install=downloading({bytes} bytes)"), + Self::Ready { family, from_cache } => { + format!("cjk-install=ready(\"{family}\",from_cache={from_cache})") + } + Self::Failed { class, message } => { + format!("cjk-install=failed({},{message})", class.as_str()) + } + } + } +} + +/// 进程级状态（一份）。 +pub(super) fn slot() -> &'static Mutex { + static STATE: OnceLock> = OnceLock::new(); + STATE.get_or_init(|| Mutex::new(CjkInstall::Unknown)) +} + +/// 当前状态（设置页那一行、心跳、日志都读它）。 +#[must_use] +pub fn status() -> CjkInstall { + if let Some(forced) = capture_override() { + return forced; + } + slot() + .lock() + .unwrap_or_else(|poisoned| poisoned.into_inner()) + .clone() +} + +/// 截图通道的状态钉子（`ULL_FONT_STATUS=…`）。 +fn capture_override() -> Option { + static FORCED: OnceLock> = OnceLock::new(); + FORCED + .get_or_init(|| parse_capture(&std::env::var(CAPTURE_ENV).ok()?)) + .clone() +} + +/// 取证开关名（与 `ULL_LANG` / `ULL_APPEARANCE_*` 同族）。 +pub const CAPTURE_ENV: &str = "ULL_FONT_STATUS"; + +/// `ULL_FONT_STATUS` 的取值 → 状态（纯函数，截图夹具直接打这张表）。 +#[must_use] +pub fn parse_capture(raw: &str) -> Option { + let value = raw.trim(); + Some(match value { + "not-needed" => CjkInstall::NotNeeded, + "unprobeable" => CjkInstall::Unprobeable, + "system" => CjkInstall::System { + family: "Noto Sans SC".to_owned(), + }, + "downloading" => CjkInstall::Downloading { bytes: 17_772_300 }, + "ready" => CjkInstall::Ready { + family: "Noto Sans SC".to_owned(), + from_cache: true, + }, + "failed" | "failed:network" => CjkInstall::Failed { + class: FetchClass::Network, + message: "capture fixture".to_owned(), + }, + "failed:integrity" => CjkInstall::Failed { + class: FetchClass::Integrity, + message: "capture fixture".to_owned(), + }, + "failed:disk" => CjkInstall::Failed { + class: FetchClass::Disk, + message: "capture fixture".to_owned(), + }, + _ => return None, + }) +} + +/// 纯状态机：判据结论 + 下载器 + 注册器 → 结局（**不碰全局状态、不起线程**）。 +/// +/// 单测直接打这张表（守「不需要时一次都不联网」与「下载失败不崩」）。 +pub fn ensure_for( + strategy: Strategy, + fetcher: &dyn Fetcher, + register: &dyn Fn(Vec) -> Result, +) -> CjkInstall { + match font::ensure(strategy, fetcher) { + Ok(Fetched::NothingToDo) => CjkInstall::NotNeeded, + Ok(Fetched::AlreadySystem { family }) => CjkInstall::System { + family: family.to_owned(), + }, + Ok(Fetched::Unknown) => CjkInstall::Unprobeable, + Ok(Fetched::Downloaded(bytes)) => match register(bytes) { + Ok(family) => CjkInstall::Ready { + family, + from_cache: false, + }, + Err(message) => CjkInstall::Failed { + class: FetchClass::Disk, + message, + }, + }, + Err(error) => CjkInstall::Failed { + class: FetchClass::from(&error), + message: error.message().to_owned(), + }, + } +} + +/// 判据结论 + **当前状态** → 这一步该做什么（纯函数，不碰全局状态、不起线程）。 +/// +/// 这是幂等闸的**唯一判据**：`after_probe` 只是它的执行者。之所以拎成纯函数，是因为上一版 +/// 有一条「自称守卫、其实什么都没测」的用例（复审 r1 P2-4）：它在循环里断言一个从没被传进任何 +/// 函数的假下载器「没被调用」，恒绿。现在守卫直接打这张表——把 `Skip` 那一臂删掉，用例必红。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum Step { + /// 什么都不做（已经在下载 / 已就绪）。 + Skip, + /// 只把状态改成这个（零网络）。 + Apply(CjkInstall), + /// 真的发起一次下载。 + Start(&'static font::CjkFont), +} + +/// 判据表（判据本体就在这张表的 `match` 里，`after_probe` 不含任何判据）。 +/// +/// | 当前状态 | 策略 | 这一步 | +/// |---|---|---| +/// | **下载中**（任意策略） | 任意 | **`Skip`**（闸在最上面，见下） | +/// | `Ready` | 任意 | `Skip`（幂等：已就绪不再发起） | +/// | 其它 | `NotNeeded` / `System` / `Unprobeable` | `Apply`（只改状态，零网络） | +/// | 其它 | `NeedsDownload` | `Start`（失败过的重试只能由用户再切一次语言触发） | +/// +/// ## 为什么「下载中」要在**所有**策略之前先跳过（复审 r2 P2-2 ②） +/// +/// 上一版把 `is_downloading()` 只放在 `NeedsDownload` 分支里，于是「下载中 + `Unprobeable`」 +/// 会走 `Apply(Unprobeable)` —— 把状态从「正在下载」改回「无法探测」，而**线程还在飞**： +/// 下完之后 `Ready` 又把它盖回去，状态行在 30 秒里来回翻。当时给出的理由是「否则界面会停在 +/// 正在下载」——那个理由只对**僵死**的 `Downloading` 成立（线程 panic 才会僵死），而在飞是 +/// 常见情形。 +/// +/// ## 「僵死」那一半按构建档分两说（复审 r3 P2-1，别再当成一条统一的兜底） +/// +/// | 档 | panic 语义 | 线程 panic 之后 | +/// |---|---|---| +/// | `release`（`Cargo.toml` 的 `panic = "abort"`，发布就走它） | 进程直接 abort | 不存在「停在 Downloading」，因为**进程没了**；反过来说「下载失败不崩」在 panic 这一支上对本档**不成立**（注册路径 panic ⇒ 启动器整体死掉，不是降级） | +/// | `dev` / `test` / `fast`（unwind） | 栈展开 | `worker` 的 `catch_unwind` 把状态写成 `Failed`，闸因此不会卡死 | +/// +/// 也就是说：**闸前移在两种档下都安全**（release 靠「进程退出」，unwind 档靠 `catch_unwind`）， +/// 但 `catch_unwind` **不能**用来给「下载失败不崩」背书——它只在 unwind 档存在。字体注册路径的 +/// panic 在发布版仍会让启动器 abort，这是本 mission 未解决的一项（报告里列为未验/风险）。 +/// +/// `offline = true`（出图通道）时**永不** `Start`：D30 要求同一份代码出同一张图，而下载会额外 +/// 产生网络流量并可能在出图过程中注册新字体。 +#[must_use] +pub fn plan_with_offline(strategy: Strategy, current: &CjkInstall, offline: bool) -> Step { + if current.is_downloading() || matches!(current, CjkInstall::Ready { .. }) { + return Step::Skip; + } + match strategy { + Strategy::NotNeeded => Step::Apply(CjkInstall::NotNeeded), + Strategy::System { family } => Step::Apply(CjkInstall::System { + family: family.to_owned(), + }), + Strategy::Unprobeable => Step::Apply(CjkInstall::Unprobeable), + // 出图通道需要下载 ⇒ **什么都不做**（也不改状态）：写「不需要下载」是谎话， + // 写「正在下载」也是谎话（并没有在下载）。 + Strategy::NeedsDownload(_) if offline => Step::Skip, + Strategy::NeedsDownload(font) => Step::Start(font), + } +} + +/// 同 [`plan_with_offline`]，但按本进程当前的联网策略（生产判据入口）。 +#[must_use] +pub fn plan(strategy: Strategy, current: &CjkInstall) -> Step { + plan_with_offline(strategy, current, offline()) +} + +/// 判据结论 → 现在这一步的结局（生产入口；判据全在 [`plan`]，这里只执行）。 +/// +/// * 已经在下载 / 已就绪 → 什么都不做（幂等：切一次语言不会起第二条下载、不会重复注册 16.9 MiB）； +/// * 英文环境 / 系统已有 / 探测不出 → 只更新状态（零网络）； +/// * 上次失败过 → 只有再次切语言才会重试（用户显式动作），不会自己反复联网； +/// * 出图通道（[`set_offline`]）→ 永不发起。 +pub fn after_probe(strategy: Strategy) -> CjkInstall { + match plan(strategy, &status()) { + Step::Skip => status(), + Step::Apply(state) => { + update(state.clone()); + state + } + Step::Start(font) => { + worker::start(font); + status() + } + } +} + +/// 本进程是否**禁止**发起字体下载（出图通道用；D30：同一份代码出同一张图）。 +/// +/// 为什么需要它：截图/演示通道也会走 `App` 构造 → `lang.log_cjk()` → `cjk_for` → `after_probe`。 +/// 一台 zh-locale、没有中文字体的机器上，出图会真的下 16.9 MiB 并在出图过程中注册新字体—— +/// 这既产生流量，也让「同一份代码出同一张图」不再成立。 +pub fn set_offline(offline: bool) { + OFFLINE.store(offline, std::sync::atomic::Ordering::Relaxed); +} + +/// 当前是否处于 [`set_offline`] 的状态。 +#[must_use] +pub fn offline() -> bool { + OFFLINE.load(std::sync::atomic::Ordering::Relaxed) +} + +/// 进程级联网开关（默认允许）。 +static OFFLINE: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false); + +/// 状态变更时记一行（只有真变了才打，避免每秒刷一行）。 +pub(super) fn update(state: CjkInstall) { + let previous = { + let mut guard = slot() + .lock() + .unwrap_or_else(|poisoned| poisoned.into_inner()); + std::mem::replace(&mut *guard, state.clone()) + }; + if previous != state { + eprintln!("[font] {}", state.describe()); + } +} + +/// 下载线程 + 字体注册（`install/worker.rs`）：`start` 只在这里被触发。 +mod worker; + +#[cfg(test)] +#[path = "install/tests.rs"] +mod tests; diff --git a/crates/app-iced/src/fonts/install/tests.rs b/crates/app-iced/src/fonts/install/tests.rs new file mode 100644 index 0000000..8d1267f --- /dev/null +++ b/crates/app-iced/src/fonts/install/tests.rs @@ -0,0 +1,369 @@ +//! `fonts::install` 的守卫（M168）：**三条能变红的断言**，每条都写明「抓得住什么」。 +//! +//! 这些用例全部脱机：下载器是假的（记调用次数），注册器也是假的（记收到的字节）。真下载、真注册 +//! 进 iced 字体系统这两件事**不在**本文件的能力范围内（真注册要 iced 的全局字体系统，见报告）。 + +use std::cell::RefCell; + +use unlucky_i18n::font::{CjkFont, FetchError, Fetcher, Strategy, NOTO_SANS_SC}; + +use super::*; + +/// 假下载器：记调用次数与拿到的字体族名，返回预置结果。 +struct FakeFetcher { + calls: RefCell, + seen: RefCell>, + result: Result, FetchError>, +} + +impl FakeFetcher { + fn new(result: Result, FetchError>) -> Self { + Self { + calls: RefCell::new(0), + seen: RefCell::new(None), + result, + } + } + + fn calls(&self) -> usize { + *self.calls.borrow() + } +} + +impl Fetcher for FakeFetcher { + fn fetch(&self, font: &'static CjkFont) -> Result, FetchError> { + *self.calls.borrow_mut() += 1; + *self.seen.borrow_mut() = Some(font.family); + self.result.clone() + } +} + +/// 假注册器收到的字节长度（只关心「注册了几次、每次多大」）。 +type Registered = std::rc::Rc>>; + +/// 假注册器：记收到的字节数，返回一个族名。 +fn recorder() -> (Registered, impl Fn(Vec) -> Result) { + let seen = std::rc::Rc::new(RefCell::new(Vec::new())); + let recorder = std::rc::Rc::clone(&seen); + let register = move |bytes: Vec| { + recorder.borrow_mut().push(bytes.len()); + Ok("Noto Sans SC".to_owned()) + }; + (seen, register) +} + +/// 守卫 ①：**英文环境 / 系统已有字体 / 探测不出 ⇒ 一次都不联网**。 +/// +/// 抓得住：把 `ensure_for` 的判据换成「先试着下一下看看」、或 `after_probe` 里对这三种策略也走 +/// `start()`——本用例在 `fetcher.calls() == 0` 处当场红（这是新路径，不是 i18n 那条既有用例）。 +/// 抓不住：`after_probe` 起线程之后的真实网络行为（那由 `core::download::font` 的守卫与 +/// `CdnFetcher` 的缓存判定承担）。 +#[test] +fn the_three_idle_strategies_never_touch_the_fetcher() { + let (registered, register) = recorder(); + + let idle = FakeFetcher::new(Ok(vec![1, 2, 3])); + assert_eq!( + ensure_for(Strategy::NotNeeded, &idle, ®ister), + CjkInstall::NotNeeded + ); + assert_eq!( + ensure_for(Strategy::System { family: "SimSun" }, &idle, ®ister), + CjkInstall::System { + family: "SimSun".to_owned() + } + ); + assert_eq!( + ensure_for(Strategy::Unprobeable, &idle, ®ister), + CjkInstall::Unprobeable + ); + assert_eq!( + idle.calls(), + 0, + "英文 / 系统已有 / 探测不出：一次都不许调下载器" + ); + assert!(registered.borrow().is_empty(), "这三路不许注册任何字体"); + + // 反方向：真需要时才调一次（否则上面那三个 0 可能是「永远不调」的假绿）。 + let working = FakeFetcher::new(Ok(vec![9; 4096])); + assert_eq!( + ensure_for(Strategy::NeedsDownload(&NOTO_SANS_SC), &working, ®ister), + CjkInstall::Ready { + family: "Noto Sans SC".to_owned(), + from_cache: false + } + ); + assert_eq!(working.calls(), 1); + assert_eq!(working.seen.borrow().as_deref(), Some("Noto Sans SC")); + assert_eq!(*registered.borrow(), vec![4096]); +} + +/// 守卫 ②：**校验失败 ⇒ 状态 `Failed(integrity)`，且一个字节都不注册**。 +/// +/// 抓得住：把 `ensure_for` 的错误分支写成「失败也注册回落的字节」、或把类别压成 `network` +/// （设置页就会说「网络不通」，而真相是镜像给了不对的东西）。 +/// 抓不住：sha256 到底比得对不对（那是 `core::download::font` 的守卫）。 +#[test] +fn an_integrity_failure_registers_nothing_and_keeps_the_class() { + let (registered, register) = recorder(); + let broken = FakeFetcher::new(Err(FetchError::Integrity("sha256 不符".to_owned()))); + + let state = ensure_for(Strategy::NeedsDownload(&NOTO_SANS_SC), &broken, ®ister); + assert_eq!( + state, + CjkInstall::Failed { + class: FetchClass::Integrity, + message: "sha256 不符".to_owned() + } + ); + assert!(registered.borrow().is_empty(), "校验失败不许注册"); + assert!(!state.is_downloading(), "失败是终态：不再转圈、不阻塞界面"); +} + +/// 三类失败各归各的类别（设置页按类别选词，串了就等于对用户说错话）。 +#[test] +fn every_failure_class_survives_the_trip() { + let (_, register) = recorder(); + for (error, class) in [ + (FetchError::Network("超时".to_owned()), FetchClass::Network), + ( + FetchError::Integrity("哈希不符".to_owned()), + FetchClass::Integrity, + ), + (FetchError::Disk("磁盘满".to_owned()), FetchClass::Disk), + ] { + let fetcher = FakeFetcher::new(Err(error)); + let state = ensure_for(Strategy::NeedsDownload(&NOTO_SANS_SC), &fetcher, ®ister); + match state { + CjkInstall::Failed { class: got, .. } => assert_eq!(got, class), + other => panic!("应当是 Failed：{other:?}"), + } + } + + // 注册本身失败（字体系统锁毒掉 / 字体库不认）也要落到失败的磁盘档，而不是 Ok。 + let fetcher = FakeFetcher::new(Ok(vec![7; 8])); + let state = ensure_for( + Strategy::NeedsDownload(&NOTO_SANS_SC), + &fetcher, + &|_bytes| Err("字体系统锁被毒掉".to_owned()), + ); + assert!(matches!( + state, + CjkInstall::Failed { + class: FetchClass::Disk, + .. + } + )); +} + +/// 幂等闸（M168 复审 P2-4：这条以前是**假守卫**，现在打真判据）。 +/// +/// 复审的原话：上一版的循环体只断言「一个从没被传进任何函数的假下载器没被调用」，把 +/// `after_probe` 里的 `is_downloading() || Ready` 整段删掉它**依然全绿**。 +/// +/// 现在直接打 [`plan`]：删掉 `Skip` 那一臂（或把它改成 `Start`），本用例在 +/// `assert_eq!(plan(...), Step::Skip)` 处当场红。为什么这条闸不是可有可无：去掉之后每切一次 +/// 语言就 spawn 一条线程，线程会命中缓存（不联网）但会**再注册一遍 17 MiB 字体** +/// （`load_font(Cow::Owned)` 不做去重），内存随切换次数累积。 +/// +/// 抓得住：幂等判据被删/被改反（下载中、已就绪两种状态各自一行）。 +/// 抓不住：`after_probe` 真的 spawn 几条线程（那要真线程 + 真网络，见报告「未验」）。 +#[test] +fn a_started_or_finished_install_is_not_restarted() { + let downloading = CjkInstall::Downloading { bytes: 17_772_300 }; + let ready = CjkInstall::Ready { + family: "Noto Sans SC".to_owned(), + from_cache: true, + }; + + for current in [downloading, ready] { + assert_eq!( + plan_with_offline(Strategy::NeedsDownload(&NOTO_SANS_SC), ¤t, false), + Step::Skip, + "{current:?}：已经在下载 / 已就绪时再问一次，必须什么都不做" + ); + } + + // 反方向（否则上面两条可能是「永远 Skip」的假绿）：其余三种当前状态都要真的发起。 + for current in [ + CjkInstall::Unknown, + CjkInstall::NotNeeded, + CjkInstall::Failed { + class: FetchClass::Network, + message: "超时".to_owned(), + }, + ] { + assert_eq!( + plan_with_offline(Strategy::NeedsDownload(&NOTO_SANS_SC), ¤t, false), + Step::Start(&NOTO_SANS_SC), + "{current:?}：需要下载且还没成就该发起（失败后的重试也只能走这条）" + ); + } +} + +/// 三种「不需要下载」的策略在判据表里只产生 `Apply`（**零网络**），且状态文案对得上。 +/// +/// 这里显式给 `offline = false`（`plan_with_offline`）而不是用 `plan`：`plan` 会读进程级的 +/// `set_offline` 开关，而同进程里 `headless(screenshot_options())` 那 20+ 处会把它置 true 且 +/// 从不还原（复审 r3 P2-4 ①）——用 `plan` 的话这三条的结果取决于执行顺序。 +/// +/// 抓得住：谁把 `NotNeeded` / `System` / `Unprobeable` 的臂改成 `Start`（那就会替英文用户偷偷 +/// 下一次 17 MiB）；也抓得住「系统已有字体」被记成「需要下载」这种状态映射错。 +/// 抓不住：真线程行为（`after_probe` 的执行部分）。 +#[test] +fn the_idle_strategies_only_apply_state() { + assert_eq!( + plan_with_offline(Strategy::NotNeeded, &CjkInstall::Unknown, false), + Step::Apply(CjkInstall::NotNeeded) + ); + assert_eq!( + plan_with_offline( + Strategy::System { family: "SimSun" }, + &CjkInstall::Unknown, + false + ), + Step::Apply(CjkInstall::System { + family: "SimSun".to_owned() + }) + ); + // 复审 r2 P2-2 ② 改判：**下载中一律 Skip**，即使策略说「探测不出」。 + // 上一版在这里断言 `Apply(Unprobeable)`，理由是「否则界面会停在正在下载」——那个理由只对 + // 僵死成立（线程 panic），而在飞是常见情形：线程还在下，状态却被改成「无法探测」，下完又 + // 翻回「已就绪」，状态行在几十秒里来回翻。「僵死」那一半按构建档分两说（worker 模块文档）： + // unwind 档（dev/test/fast）由 `catch_unwind` 兜底；发布档 `panic = "abort"` 是进程退出， + // 不存在停在 Downloading 的状态。 + assert_eq!( + plan_with_offline( + Strategy::Unprobeable, + &CjkInstall::Downloading { bytes: 1 }, + false + ), + Step::Skip, + "在飞的下载不许被别的策略改写状态" + ); +} + +/// **下载中一律 `Skip`**（复审 r2 P2-2 ②）：四种策略挨个打一遍。 +/// +/// 抓得住：把 `is_downloading()` 那道闸挪回 `NeedsDownload` 分支里（上一版就是这样）—— +/// `Unprobeable` / `NotNeeded` / `System` 三行立刻红。 +/// 抓不住：worker 真的永不僵死（那要制造 panic，见 `worker` 的 `catch_unwind` 与报告的「没验」）。 +#[test] +fn every_strategy_skips_while_a_download_is_in_flight() { + let downloading = CjkInstall::Downloading { bytes: 17_772_300 }; + for strategy in [ + Strategy::NeedsDownload(&NOTO_SANS_SC), + Strategy::NotNeeded, + Strategy::System { family: "SimSun" }, + Strategy::Unprobeable, + ] { + assert_eq!( + plan_with_offline(strategy, &downloading, false), + Step::Skip, + "{strategy:?}：下载中不许改状态、不许起第二条线程" + ); + } +} + +/// 出图通道（`offline`）**永不发起下载**（D30：同一份代码出同一张图）。 +/// +/// 抓得住：删掉 `plan_with_offline` 里 `NeedsDownload(_) if offline => Skip` 那一臂 ⇒ 截图/演示 +/// 通道会在 zh-locale 且无中文字体的机器上真下 17 MiB，用例在 `Step::Skip` 处红。 +/// 抓不住：真出图时有没有产生流量（那要真机跑 `--screenshot`，见报告「没验」）。 +#[test] +fn the_screenshot_channel_never_starts_a_download() { + assert_eq!( + plan_with_offline( + Strategy::NeedsDownload(&NOTO_SANS_SC), + &CjkInstall::Unknown, + true + ), + Step::Skip, + "出图通道不许联网" + ); + assert_eq!( + plan_with_offline( + Strategy::NeedsDownload(&NOTO_SANS_SC), + &CjkInstall::Unknown, + false + ), + Step::Start(&NOTO_SANS_SC), + "正常通道该发起（否则上面那条可能是「永远 Skip」的假绿）" + ); + // 只改状态的三种策略在两条通道里表现一致（它们本来就不联网）。 + for strategy in [ + Strategy::NotNeeded, + Strategy::System { family: "SimSun" }, + Strategy::Unprobeable, + ] { + assert_eq!( + plan_with_offline(strategy, &CjkInstall::Unknown, false), + plan_with_offline(strategy, &CjkInstall::Unknown, true), + "{strategy:?}：不联网的策略与通道无关" + ); + } +} + +/// 截图钉子（D30）：每个 `ULL_FONT_STATUS` 取值都能解析成一档状态，坏值不猜。 +/// +/// 抓得住：出图夹具写了一个不存在的取值却静默出「未知」状态的图（报告就会撒谎）。 +#[test] +fn the_capture_switch_parses_every_state() { + assert_eq!(parse_capture("not-needed"), Some(CjkInstall::NotNeeded)); + assert_eq!(parse_capture("unprobeable"), Some(CjkInstall::Unprobeable)); + assert!(matches!( + parse_capture("system"), + Some(CjkInstall::System { .. }) + )); + assert!(matches!( + parse_capture("downloading"), + Some(CjkInstall::Downloading { .. }) + )); + assert!(matches!( + parse_capture("ready"), + Some(CjkInstall::Ready { + from_cache: true, + .. + }) + )); + for (raw, class) in [ + ("failed", FetchClass::Network), + ("failed:network", FetchClass::Network), + ("failed:integrity", FetchClass::Integrity), + ("failed:disk", FetchClass::Disk), + ] { + match parse_capture(raw) { + Some(CjkInstall::Failed { class: got, .. }) => assert_eq!(got, class, "{raw}"), + other => panic!("{raw} 应解析成 Failed：{other:?}"), + } + } + assert_eq!(parse_capture("bogus"), None); + assert_eq!(parse_capture(""), None); +} + +/// 一行日志片段：每种状态都能被 grep 到，且**不带换行**（启动日志按行解析）。 +#[test] +fn every_state_describes_itself_on_one_line() { + let states = [ + CjkInstall::Unknown, + CjkInstall::NotNeeded, + CjkInstall::System { + family: "SimSun".to_owned(), + }, + CjkInstall::Unprobeable, + CjkInstall::Downloading { bytes: 17_772_300 }, + CjkInstall::Ready { + family: "Noto Sans SC".to_owned(), + from_cache: false, + }, + CjkInstall::Failed { + class: FetchClass::Integrity, + message: "sha256 不符".to_owned(), + }, + ]; + for state in states { + let line = state.describe(); + assert_eq!(line.lines().count(), 1, "{line}"); + assert!(line.starts_with("cjk-install="), "{line}"); + } +} diff --git a/crates/app-iced/src/fonts/install/worker.rs b/crates/app-iced/src/fonts/install/worker.rs new file mode 100644 index 0000000..299008f --- /dev/null +++ b/crates/app-iced/src/fonts/install/worker.rs @@ -0,0 +1,164 @@ +//! 下载线程与字体注册（M168）：`install.rs` 的「动作」那一半。 +//! +//! ## 为什么拆出来 +//! +//! `install.rs` 是「状态 + 判据 + 触发」，已经贴着 400 行硬线。这里只放真正干活的两件： +//! +//! 1. [`start`]：起一条后台线程（进程内同时只有一条），把「正在下载 → 结果」写回状态槽； +//! 2. [`register_into_font_system`]：把字节交给 iced 的全局字体系统（运行时注册）。 +//! +//! ## 为什么下载在后台线程 +//! +//! 一份 16.9 MiB 的字体在弱网下要几十秒，而触发点（设置页切语言）在 UI 线程上。 +//! 在 UI 线程同步下完 = 窗口几十秒不响应。 +//! +//! ## 线程里做了什么（顺序即判据） +//! +//! ```text +//! CdnFetcher（缓存命中 ⇒ 零网络；否则共享引擎下载 + sha256 复验 + 整体时限） +//! → i18n::font::ensure 只有 NeedsDownload 才调 fetcher +//! → 成功：注册进 iced，状态 Ready{family, from_cache} +//! → 失败：状态 Failed{class}，**什么都不注册**（降级回系统字体，界面照常可用） +//! ``` +//! +//! ## panic 这件事分两档说（复审 r3 P2-1） +//! +//! | 档 | panic 语义 | 线程 panic 之后 | +//! |---|---|---| +//! | `release`（`Cargo.toml`：`panic = "abort"`，发布走它） | 进程 abort | 状态槽随进程消失（**不会**停在 Downloading）；但「降级回系统字体」**也不存在**——启动器整体退出 | +//! | `dev` / `test` / `fast`（unwind） | 栈展开 | [`run`] 里的 `catch_unwind` 把状态写成 `Failed` | +//! +//! 所以 `catch_unwind` 是**给 unwind 档的**，不能拿它给「下载失败不崩」背书：发布版在注册路径 +//! panic 时仍会 abort。要让发布版也降级，得让注册路径不 panic（或改成 `panic = "unwind"`， +//! 那属于发布 profile 的决定，不在本 mission）。 +//! +//! ## 诚实边界 +//! +//! - **抓得住**：状态流转、失败不注册、日志三行（start / ok / failed）； +//! - **抓不住**：真机上字体注册之后**出字的样子**（cosmic-text 用 `wght` 轴选字重这件事只核对了 +//! 上游源码，没有真机截图对照；macOS / Linux 完全没有真机），也抓不住发布档的 abort 行为 +//! （那要真跑一个 `--release` 的 panic 用例）。 + +use unlucky_i18n::font::{self, Strategy}; + +use super::{ensure_for, update, CjkInstall, FetchClass}; +use crate::fonts::cdn::CdnFetcher; +use crate::platform::data; + +/// 起一条后台下载（进程内同时只允许一条：`install::after_probe` 负责那道闸）。 +/// +/// 状态先落 `Downloading` 再起线程；**线程起不来时**立刻落 `Failed`（用 `Builder::spawn` 而不是 +/// 裸 `thread::spawn`：后者失败会 panic，而发布档 `panic = "abort"` ⇒ 整个启动器退出）。 +pub(super) fn start(font: &'static font::CjkFont) { + let font::Source::Pinned { bytes, .. } = font.source; + let Some(cache_root) = data::cache_root() else { + update(CjkInstall::Failed { + class: FetchClass::Disk, + message: "数据根解析不出来，字体无处可落".to_owned(), + }); + return; + }; + + let fetcher = match CdnFetcher::new(font, cache_root) { + Ok(fetcher) => fetcher, + Err(error) => { + update(CjkInstall::Failed { + class: FetchClass::from(&error), + message: error.message().to_owned(), + }); + return; + } + }; + + let cache_file = fetcher.cache_file(); + update(CjkInstall::Downloading { bytes }); + eprintln!( + "[font] cjk-download start family=\"{}\" bytes={bytes} file={} cache_present={}", + font.family, + cache_file.display(), + // 这条只是「文件在不在」（诊断用），**不是** from_cache：坏缓存会被删掉重下， + // 真正的命中结论在 `fetcher.was_cached()`（取完之后）。 + fetcher.has_cached() + ); + + let spawned = std::thread::Builder::new() + .name("ull-cjk-font".to_owned()) + .spawn(move || run(font, fetcher)); + + if let Err(error) = spawned { + update(CjkInstall::Failed { + class: FetchClass::Disk, + message: format!("起不了字体下载线程（{error}）"), + }); + } +} + +/// 线程体：取字体 → 注册 → 写终态（**一定**写终态，见模块文档「panic 这件事分两档说」）。 +fn run(font: &'static font::CjkFont, fetcher: CdnFetcher) { + let state = match std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| { + ensure_for( + Strategy::NeedsDownload(font), + &fetcher, + ®ister_into_font_system, + ) + })) { + Ok(state) => state, + Err(_) => CjkInstall::Failed { + class: FetchClass::Disk, + message: "字体安装线程 panic（已捕获，状态回到终态；界面继续用系统字体）".to_owned(), + }, + }; + + // `from_cache` 只认下载器**这次**的结论（复审 r1 次要项）：取之前「文件在不在」会说谎—— + // 坏缓存会被删掉重下，那时 `has_cached()` 还是 true，而真相是「联网下了一次」。 + let from_cache = fetcher.was_cached().unwrap_or(false); + let state = match state { + CjkInstall::Ready { family, .. } => CjkInstall::Ready { family, from_cache }, + other => other, + }; + + match &state { + CjkInstall::Ready { family, from_cache } => eprintln!( + "[font] cjk-download ok family=\"{family}\" from_cache={from_cache} \ + （中文字形现在由它兜底，界面不需要重启）" + ), + CjkInstall::Failed { class, message } => eprintln!( + "[font] cjk-download failed class={} {message}（降级：继续用系统字体，界面照常可用）", + class.as_str() + ), + other => eprintln!("[font] cjk-download {}", other.describe()), + } + update(state); +} + +/// 把字体字节注册进 iced 的**全局字体系统**（`iced_graphics` 的 `FontSystem::load_font`）。 +/// +/// 返回注册后的族名（从字体库里读回来的）：变量字体的 `name` 表里族名是 `Noto Sans SC`、 +/// 而默认实例是 Thin，所以**不能**假设「注册了就叫 NOTO_SANS_SC.family」——这里读回来核对。 +/// +/// # Errors +/// 字体系统锁被毒掉、或注册后字体库里找不到那个族（字节不是字体 / `fontdb` 不认）。 +pub fn register_into_font_system(bytes: Vec) -> Result { + let lock = iced::advanced::graphics::text::font_system(); + let mut font_system = lock + .write() + .map_err(|_| "字体系统的读写锁被毒掉（另一处注册 panic 过）".to_owned())?; + + font_system.load_font(std::borrow::Cow::Owned(bytes)); + + // 先把族名抄出来再判：`faces()` 的迭代器借着 `font_system`，直接链到 `ok_or_else` 会让 + // 那个借用活过守卫（E0597）。 + let families: Vec = font_system + .raw() + .db() + .faces() + .flat_map(|face| face.families.iter()) + .map(|(family, _)| family.clone()) + .collect(); + + families + .iter() + .find(|family| family.as_str() == font::NOTO_SANS_SC.family) + .cloned() + .ok_or_else(|| format!("注册后在字体库里找不到 \"{}\"", font::NOTO_SANS_SC.family)) +} diff --git a/crates/app-iced/src/fonts/tests.rs b/crates/app-iced/src/fonts/tests.rs new file mode 100644 index 0000000..d516123 --- /dev/null +++ b/crates/app-iced/src/fonts/tests.rs @@ -0,0 +1,214 @@ +//! `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); +} + +/// **求值字体不许发起下载**（复审 r3 P2-2：上一轮的修复没有任何用例守着）。 +/// +/// 用 `resolve_with_faces` 而不是 `resolve_with`：`system_faces()` 不可注入，拿不到「一台没有 +/// 中文字体的机器」。这里给一张只有拉丁族的脸表 ⇒ 中文环境判出 `NeedsDownload`。 +/// +/// 抓得住：把 `install::after_probe(cjk_report.strategy)` 加回求值路径（那正是 r2 判为 bug 的写法） +/// ——状态槽会从 `NotNeeded`/`Unknown` 变成 `Downloading`，下面那条断言当场红。 +/// 复审 r3 实测：加回去整套 `unlucky-app-iced --lib` **687 passed / 0 failed**（当时没有这条）。 +/// 抓不住：`App` 构造之后 `log_cjk` 那一拍会不会触发（那是 `cjk_for` 的职责，且它本来就该触发）。 +#[test] +fn resolving_fonts_never_starts_a_download() { + use unlucky_i18n::font::Strategy; + + use crate::fonts::install; + + // 只有拉丁族 ⇒ 中文环境一定判 needs-download，于是这条用例对「触发」是敏感的。 + let latin: Vec = ["Segoe UI", "Consolas"] + .iter() + .map(|family| Face { + family: (*family).to_owned(), + weight: 400, + }) + .collect(); + + let before = install::status(); + let resolved = resolve_with_faces(Some("zh_cn"), Some(&latin)); + let after = install::status(); + + assert_eq!( + resolved.cjk.strategy, + Strategy::NeedsDownload(&unlucky_i18n::font::NOTO_SANS_SC), + "这张脸表必须判出「需要下载」，否则下面的断言证明不了什么" + ); + assert!( + !after.is_downloading(), + "求值字体**不许**发起下载（状态从 {before:?} 变成了 {after:?}）" + ); +} 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!( + "", + render_px, icon.path + ) +} + +/// 图标的 SVG 句柄（按 `(种类, 渲染尺寸)` 缓存；句柄 id 是内容哈希，所以 iced 侧也能命中缓存）。 +fn handle(kind: IconKind, render_px: f32) -> svg::Handle { + static HANDLES: OnceLock>> = 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 尾不对", 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 = 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 { + 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 { + 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 { + 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::`，含 `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..e7cb392 --- /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` 落点之一；另一半是 M196 的控制台附着 | 窗口创建 / 业务开关 | +//! +//! ## 消费纪律 +//! +//! **组件层零硬编码色值/字号/半径/间距**：一律走 [`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 { + 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..e438ddd --- /dev/null +++ b/crates/app-iced/src/main.rs @@ -0,0 +1,145 @@ +//! 入口。所有实际逻辑在 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 ` 只读两张 PNG +//! 做逐像素对比（D30 的 GPU/CPU 几何一致性检查），不开窗。 +//! +//! 零 UI 依赖的 `ull` 仍然保留（D18）：它是唯一连 fontconfig 都不需要的产物， +//! 给服务器 / CI / Termux 这类没有图形库的机器用。 +//! +//! 退出码：`0` 成功 / `1` 截图有差异（diff 模式）或 CLI 用户错误 / `2` 参数或运行错误。 +//! +//! ## 为什么这里是 WINDOWS GUI 子系统（M196） +//! +//! 下面那条 `#![cfg_attr(windows, windows_subsystem = "windows")]` 直接改的是**产物 PE 头**的 +//! `Subsystem` 字段（CUI=3 → WINDOWS_GUI=2），这是「双击不再多一个常驻控制台宿主窗口」的 +//! 唯一机制：PE 头写 3 时由系统在启动时分配控制台（那个黑框），写 2 时系统不分配。 +//! +//! **为什么放这一层而不是 `build.rs`**：PE 子系统是**每个 bin 目标**的属性，而 `cfg_attr` 就是 +//! 它的原生长相——rustc 读到它就把标志写进链接出来的 PE 里，没有任何别的路径能改到那一行。 +//! `build.rs` 做不到这件事：它只能在编译**之前**跑（`cargo:rustc-link-arg` 之类确实能加链接参数， +//! 但那是「顺手改了链接命令行」的间接法，且在交叉/多 bin 时按 crate 而非按 target 生效）， +//! 更麻烦的是它把「这条 bin 是 GUI」这条事实挪到一个**看不见 bin 声明**的地方——本 crate 的 +//! `[[bin]]` 名是 `unlucky-launcher-iced`（不是 crate 名），读 `build.rs` 的人得先在 Cargo.toml +//! 里找回来。放 `main.rs` 顶上，事实与产物一一对应：改这个文件 = 改这个 bin。 +//! +//! 代价与补救见 [`unlucky_app_iced::platform::win32::console`]：GUI 子系统进程**不继承**父进程 +//! 的控制台，所以 `main()` 第一步就把输出接回父控制台（`AttachConsole`），CLI 子命令、 +//! `--diff`、`--screenshot` 的日志在 cmd / 终端里照样看得见；双击时没有父控制台，附着失败、 +//! 也绝不新建窗口。判据是**产物 PE 头的读数**，不是「代码看起来对」： +//! `packaging/check_pe_subsystem.py` 读 `Subsystem` 字段，非 2 即红（`release-build.yml` 里跑）。 +//! +//! 历史：同样的修复曾做过一次，但打在已退役的 Slint 树（`37d3039`，只改了 `crates/app/src/main.rs`）， +//! 而 `crates/app` 自 M118 起不在 workspace、不进发布矩阵——所以那一笔从未到这里。 +// M196：PE 头的子系统 = WINDOWS_GUI(2)。没有它，双击产物会多一个控制台宿主窗口。 +// 这一行只对 bin 目标有意义（lib 没有 PE 头），所以放在 main.rs 而不是 lib.rs。 +#![cfg_attr(windows, windows_subsystem = "windows")] + +use std::process::ExitCode; + +use unlucky_app_iced::platform::win32::console::attach_parent_console; +use unlucky_app_iced::shot; +use unlucky_app_iced::Options; + +fn main() -> ExitCode { + // M196 第一步：GUI 子系统进程默认没有控制台（stdout/stderr 是 0 号无效句柄）， + // 不接回来 CLI 输出与所有 eprintln 都会静默丢失。四种启动情形的实测表在 + // `platform/win32/console.rs` 顶部：重定向/管道两个句柄本来就可用（一个字节都不动）， + // cmd 里直接跑要 attach，双击时 attach 必失败且不会新建窗口。 + let console = attach_parent_console(); + if std::env::var_os("ULL_ACCEPTANCE").is_some() { + eprintln!("[console] {}", console.describe()); + } + + let args: Vec = 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 ] [--screenshot-theme=light|dark] \ + [--scale-factor ] [--diff ]" + ); + // M98：验收开关写在用法里，不然「日志怎么变详细了」只能靠翻文档。 + eprintln!( + "验收诊断：ULL_ACCEPTANCE=1（[console]/[env]/[backend]/[window]/[font]/[theme]/[perf]/[i18n]/[caps]）\ + ，ULL_WINDOW_SIZE=1520x900 覆盖窗口尺寸" + ); + // M201：设置页要出「带真值」的验收图，而截图通道默认强制 mock（mock 不发 + // `CoreEvent::SettingsChanged`）。这一条把**数据源**换成真 host，其余一字不改。 + eprintln!( + "取证：ULL_SCREENSHOT_REAL_HOST=1 让 --screenshot 接真 host（默认 mock；\ + 出图将不再可复现，只用于验收真值屏）" + ); + 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 { + 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 { + 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..d016ea6 --- /dev/null +++ b/crates/app-iced/src/pages/account.rs @@ -0,0 +1,178 @@ +//! 账户页（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_msa.rs"] +mod tests_msa; +#[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, + /// 皮肤原图（皮肤预览区用） + pub skin: Option, +} + +/// 解码缓存：同一个账户的同一张皮肤只解码一次。 +/// +/// 键 = 账户 id，值 = (皮肤来源串, 解码结果)。来源串变了（重新登录换了皮肤）就重解。 +#[derive(Debug, Default)] +pub struct Cache { + entries: BTreeMap, +} + +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 { + 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 { + 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..a11eaad --- /dev/null +++ b/crates/app-iced/src/pages/account/login.rs @@ -0,0 +1,400 @@ +//! 微软登录面板：设备码（用户码 + 链接 + **倒计时** + 过期重试）与授权码（浏览器 + 可复制链接 + 取消）。 +//! +//! ## 为什么不是「一个转圈」 +//! +//! 设备码的等待期可以长到 15 分钟。只画转圈的话，用户既不知道要做什么、也不知道还剩多久， +//! 更不知道已经过期了——M114 把这三件事都做成可见状态：用户码、链接、倒计时与「已过期，重试」。 +//! +//! ## 文案一律**借用模型里的串**（M178） +//! +//! 倒计时/回退说明这类运行时格式化出来的句子由 [`super::panels`] 在模型层拼好（带 i18n）， +//! 视图只拿 `&'a str` 画。为什么不在这里 `format!` 后交给 `frame::text_role_owned`： +//! 那条 owned 路径上的**中文画不出来**（实测：同一位置 ASCII 能画、`剩 15:00` 一片空白）， +//! 而借用路径正常。模型持有字符串、视图借用，两个问题一起消掉。 + +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::{BrowserLoginNote, 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, + countdown, + expired, + note, + } => device_code(ui, code, link, countdown, *expired, *note, catalog), + DevicePanel::Browser { + link, + countdown, + expired, + } => browser(ui, link, countdown, *expired, catalog), + DevicePanel::Failed { failure, note } => failed(ui, *failure, *note, catalog), + DevicePanel::Succeeded { name } => succeeded(ui, name, catalog), + } +} + +/// 空闲：两条流的入口。**主按钮是设备码**（M178）：它不依赖应用注册里的任何一项，是官方 +/// 产物上唯一开箱可用的路；浏览器流是右手的次要按钮（要注册 `http://localhost/auth`， +/// 没登记时在预检处直接回退设备码）。 +/// +/// 文案（复审 r1 P2-5）：主按钮写「使用 Microsoft 账户登录」而不是「改用设备码」； +/// 「没有浏览器时用这个」放在按钮下面一行说明里。 +fn idle<'a>(ui: &'a Ui, catalog: Catalog) -> Element<'a, PageMessage> { + let body = column![row![ + buttons::filled( + ui, + Button::new( + catalog.text(Key::AccountDeviceSignIn), + Account::StartDevice.into_page(), + ) + ), + buttons::outlined( + ui, + Button::new( + catalog.text(Key::AccountDeviceBrowser), + Account::StartBrowser.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)) + .push(frame::text_role( + ui, + TypeRole::BodySmall, + false, + catalog.text(Key::AccountDeviceFallbackHint), + ui.color(Role::OnSurfaceVariant), + )); + 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) +} + +/// 设备码等待态：码 + 链接 + 倒计时（`note` = 回退说明）。 +fn device_code<'a>( + ui: &'a Ui, + code: &'a str, + link: &'a str, + countdown: &'a str, + expired: bool, + note: Option, + 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 mut 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_line(ui, countdown, expired), + frame::text_role( + ui, + TypeRole::BodySmall, + false, + catalog.text(Key::AccountDeviceHint), + ui.color(Role::OnSurfaceVariant), + ), + ] + .spacing(ui.space(Space::X3)); + // 回退说明放在**动作行之前**：它解释的是「这个面板为什么是设备码」， + // 用户读完再决定复制码/取消（放在按钮下面会像脚注，读不到）。 + if let Some(text) = note_text(ui, note, catalog) { + body = body.push(text); + } + frame::card(ui, body.push(actions)) +} + +/// 授权码等待态：浏览器已拉起，链接可复制；过期可重试。 +fn browser<'a>( + ui: &'a Ui, + link: &'a str, + countdown: &'a str, + 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, countdown, expired), + actions, + ] + .spacing(ui.space(Space::X3)); + frame::card(ui, body) +} + +/// 倒计时 / 过期提示（**这一行是「不得只转圈」的落点**；文案由模型拼好，这里只定颜色与强调）。 +fn countdown_line<'a>(ui: &'a Ui, text: &'a str, expired: bool) -> Element<'a, PageMessage> { + if expired { + return frame::text_role(ui, TypeRole::LabelMedium, true, text, ui.color(Role::Error)); + } + frame::text_role( + ui, + TypeRole::LabelMedium, + false, + text, + ui.color(Role::OnSurfaceVariant), + ) +} + +/// 回退说明的**唯一文案出口**（视图与页面级断言共用：断言取样走这里，才是「视图会画的那句」）。 +pub(super) fn browser_note_text(note: BrowserLoginNote, catalog: Catalog) -> &'static str { + catalog.text(super::model::note_key(note)) +} + +/// 回退说明那一行（`None` = 没有这回事）。 +fn note_text<'a>( + ui: &'a Ui, + note: Option, + catalog: Catalog, +) -> Option> { + let note = note?; + // 用正文色而不是 `Error`：这不是失败态（设备码接着跑），画成红色会让人以为登录已经挂了。 + Some(frame::text_role( + ui, + TypeRole::BodySmall, + false, + browser_note_text(note, catalog), + ui.color(Role::OnSurfaceVariant), + )) +} + +/// 失败态：**M3 内联 alert**（左侧 `ErrorContainer` 图标块 + 标题/正文/Code + 重试/关闭）。 +/// +/// - 语言泄漏（r1 p1）：只画原因码对应的 i18n + 一行 `Code: …`，后端中文原文不上屏； +/// - 不许通栏实心红（tower r2）：面板底 `SurfaceContainerHigh` + 描边，`ErrorContainer` 只做图标块强调； +/// - 可操作的失败要有可读说明（M132）：缺 client id 换专属标题 + 「要设哪个环境变量」，且不给「重试」； +/// - M178：`note`（浏览器登录没走成）另起一行画在正文下面，两者都能看见。 +fn failed<'a>( + ui: &'a Ui, + failure: LoginFailure, + note: Option, + catalog: Catalog, +) -> Element<'a, PageMessage> { + let mut body = catalog.text(failure_body_key(failure)).to_string(); + if let Some(note) = note { + body.push_str("\n\n"); + body.push_str(browser_note_text(note, catalog)); + } + let code = catalog.render(Key::AccountFailureCode, &[("code", failure.code())]); + let mut actions: Vec> = Vec::new(); + if !matches!(failure, LoginFailure::MsaNotConfigured) { + actions.push(buttons::tonal( + ui, + Button::new( + catalog.text(Key::AccountDeviceRetry), + Account::StartDevice.into_page(), + ), + )); + } + actions.push(buttons::text( + ui, + Button::new( + catalog.text(Key::AccountDialogClose), + Account::Close.into_page(), + ), + )); + super::widgets::alert( + ui, + super::widgets::Tone::Error, + catalog.text(failure_title_key(failure)), + 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::MsaNotConfigured => Key::AccountFailureMsaNotConfigured, + LoginFailure::Other => Key::AccountFailureOther, + } +} + +/// 原因码 → i18n **标题** key。 +/// +/// 只有「缺 client id」有专属标题（M132）：标题写着 `Sign-in failed` 的话，用户会以为是自己 +/// 的账号/网络出了问题，而不会被指向那一项要补的配置。 +pub(super) fn failure_title_key(failure: LoginFailure) -> Key { + match failure { + LoginFailure::MsaNotConfigured => Key::AccountLoginNotConfigured, + _ => Key::AccountLoginFailed, + } +} 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..36d21eb --- /dev/null +++ b/crates/app-iced/src/pages/account/model.rs @@ -0,0 +1,352 @@ +//! 状态 → 账户页视图模型（页面层不认识 presenter 的其它类型，只认这里）。 +//! +//! 三条轨道在 UI 上只有三种「面板」：微软登录面板 / 第三方站表单 / 本地档案表单。 +//! 表单里那些**输入串**是纯 UI 状态，归 [`Form`]（app 层持有）；从 presenter 来的只有 +//! 账户列表、登录进度与倒计时。 + +use iced::widget::image; + +use unlucky_i18n::{Key, Lang}; +use unlucky_presenter::dto::{ + AccountKind, AccountNotice, AccountNoticeCode, AccountView, BrowserLoginNote, +}; +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, +} + +/// 一次性引导（由 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() + } +} + +/// 回退说明码 → i18n key（**唯一的「码→文案」映射点**；原文永远不上屏）。 +/// +/// 与 [`Track::title_key`] 同一种写法：页面只认 key，后端只给码，两边独立演进。 +#[must_use] +pub const fn note_key(note: BrowserLoginNote) -> Key { + match note { + BrowserLoginNote::RedirectNotRegistered => Key::AccountBrowserFallbackNotRegistered, + BrowserLoginNote::PreflightUnavailable => Key::AccountBrowserFallbackUnverified, + BrowserLoginNote::AttemptFailed => Key::AccountBrowserFallbackFailed, + } +} + +/// 列表行 / 当前账户卡片用的数据。 +#[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, + /// 皮肤原图（皮肤预览区） + pub skin: Option, +} + +/// 整页视图模型。 +#[derive(Debug, Clone, PartialEq)] +pub struct Page { + /// 账户行 + pub rows: Vec, + /// 当前启动账户在 `rows` 里的下标 + pub active: Option, + /// 打开的面板 + 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, + /// 一次性引导（重新登录的下一步） + pub hint: Option, +} + +/// 横幅的渲染数据（文案在视图层按 `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 = state + .accounts + .iter() + .map(|account| row_of(account, avatars, lang)) + .collect(); + let active = rows.iter().position(|row| row.active); + let remaining = state.device_code_remaining(); + let device = device_panel(&state.device_login, remaining, lang.catalog()); + // 登录在进行（或刚失败/刚成功）时，面板**必须**是微软那条轨：否则用户点了登录、 + // 后台已经在等设备码，页面上却只剩三张入口卡——那正是「只转圈」的另一种坏法。 + 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..b956329 --- /dev/null +++ b/crates/app-iced/src/pages/account/panels.rs @@ -0,0 +1,172 @@ +//! 两条登录流的面板态（微软设备码/授权码 + 第三方站校验/登录）。 +//! +//! 从 `model.rs` 拆出来守 400 行硬线：这些类型是「UI 要画什么」的枚举， +//! 判定逻辑（倒计时 → 已过期、服务发现 → 可用）也在这里，页面与表单只消费结果。 +//! +//! ## 为什么这里**没有** `message` / `detail` 字段（M114 r3 / 复审 r2 P2-2） +//! +//! 后端的原始诊断串是中文人话，只该进日志。r2 时它们还以 `message`/`detail` 存在于此， +//! 「页面把它们画上屏」只能靠一条**平行实现**的取样断言去拦（复审用变异证明那条断言是哑的）。 +//! 现在直接把字段删掉：视图**没有材料可画**，想画原文是编译错误——比任何测试都硬。 +//! 原文仍在 presenter 的 `DeviceLoginView/AuthlibLoginView::message` 里（只进 `eprintln!`）。 + +use unlucky_i18n::{Catalog, Key}; +use unlucky_presenter::dto::{ + AuthlibLoginView, BrowserLoginNote, DeviceLoginPhase, DeviceLoginView, LoginFailure, +}; + +/// 微软登录面板要画什么（每态都不同，**不允许只有一个转圈**）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum DevicePanel { + /// 没有登录在跑 + Hidden, + /// 正在申请设备码（进度文案由页面按 i18n 出） + Requesting, + /// 设备码等待用户操作 + Code { + /// 用户码 + code: String, + /// 验证链接 + link: String, + /// 倒计时那行**已经渲染好的文案**（`15:00 left` / `剩 15:00`；过期时是「已过期」） + /// + /// 为什么文案在模型层拼（M178）：`frame::text_role_owned` 那条 owned 文字路径 + /// **画不出中文**（ASCII 正常），倒计时在中文界面会整行消失。模型持有字符串、 + /// 视图用 `&'a str` 借用，两边都不依赖那条路径。 + countdown: String, + /// 是否已过期（决定颜色与「重试」按钮） + expired: bool, + /// 浏览器登录没走成、已回退到设备码的说明（M178；`None` = 没这回事） + note: Option, + }, + /// 授权码流：等浏览器回调 + Browser { + /// 授权链接（可复制） + link: String, + /// 倒计时那行已渲染好的文案（同上） + countdown: String, + /// 是否已过期 + expired: bool, + }, + /// 失败（**只有原因码**；原文在 presenter 的日志里） + Failed { + /// 原因码（页面据此选 i18n） + failure: LoginFailure, + /// 回退说明（浏览器登录没走成之后设备码也失败了；M178） + note: Option, + }, + /// 成功 + 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, + catalog: Catalog, +) -> DevicePanel { + let expired = remaining == Some(0); + let countdown = countdown_text(remaining, expired, catalog); + 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(), + countdown, + expired, + } + } else { + DevicePanel::Code { + code: view.user_code.clone(), + link: view.qr_link.clone(), + countdown, + expired, + note: view.browser_note, + } + } + } + DeviceLoginPhase::Failed => DevicePanel::Failed { + failure: view.failure.unwrap_or(LoginFailure::Other), + note: view.browser_note, + }, + DeviceLoginPhase::Succeeded => DevicePanel::Succeeded { + name: view.account_name.clone(), + }, + } +} + +/// 倒计时那一行的文案（`mm:ss` + i18n；过期/不知道有效期的两种情况都在这里收口）。 +/// +/// `mm:ss` 而不是 `900s`：人读的是分秒；数字与冒号在两种语言里同形，只有 `left`/`剩` 走 catalog。 +fn countdown_text(remaining: Option, expired: bool, catalog: Catalog) -> String { + if expired { + return catalog.text(Key::AccountDeviceExpired).to_string(); + } + remaining.map_or_else(String::new, |secs| { + let clock = format!("{:02}:{:02}", secs / 60, secs % 60); + catalog.render(Key::AccountDeviceCountdown, &[("time", &clock)]) + }) +} + +/// 第三方轨状态 → 面板态（顺带取出「校验通过的服务器名」）。 +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, + ¤t.name, + ui.color(Role::OnSurface), + ), + widgets::badge(ui, ¤t.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, + ¤t.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, + ¤t.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..70d6b91 --- /dev/null +++ b/crates/app-iced/src/pages/account/tests.rs @@ -0,0 +1,384 @@ +//! 账户页视图模型的判据（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` | 设备码「只转圈」/ 倒计时不是人话格式 | +//! | `a_missing_client_id_tells_the_user_what_to_configure` | **M132**：缺 client id 又被画成通用失败（用户得翻日志才知道要设变量） | +//! | `a_network_failure_does_not_look_like_a_missing_config` | **M132 反向锚**：网络失败被误标成「未配置」，提示变噪音 | + +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, + } +} + +pub(super) 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}"); +} + +/// **M132 的主锚**：缺 client id 时**UI 模型**给出的结论必须是「这一项没配 + 怎么补」。 +/// +/// 抓得住：这一类失败又退回通用的「登录失败 / 完整原因在启动器日志里」（原 bug）， +/// 或者文案只说「缺 id」却不告诉用户去设哪个变量。 +/// 抓不住：排版与配色（那靠截图）；也不证明视图真的照模型画（见 `tests_text` 的边界说明）。 +#[test] +fn a_missing_client_id_tells_the_user_what_to_configure() { + let mut state = AppState::new(); + state.apply(AppEvent::Core(CoreEvent::DeviceLoginChanged( + // 后端原文照旧进这里（只该进日志）：界面上一句都不许出现。 + DeviceLoginView::failed_as( + LoginFailure::MsaNotConfigured, + "微软登录未配置：缺少 Azure 公共客户端 id", + ), + ))); + let text = on_screen(&build(&state, &Form::new())); + assert!( + text.contains("not configured"), + "标题要说清「未配置」：{text}" + ); + assert!( + text.contains("ULL_MSA_CLIENT_ID"), + "要给出具体要设的变量名：{text}" + ); + assert!(text.contains(""), "示例只许用占位，不许写值：{text}"); + assert!(text.contains("msa_not_configured"), "{text}"); + assert!(!has_cjk(&text), "英文界面里出现了中文：{text}"); + // 不许退回「去翻日志」那句：那正是用户报的那个 bug。 + assert!( + !text.contains("full reason is in the launcher log"), + "{text}" + ); +} + +/// **反向锚（M132）**：普通网络失败不许也变成「未配置」——否则提示变噪音，用户会学会无视它。 +#[test] +fn a_network_failure_does_not_look_like_a_missing_config() { + let mut state = AppState::new(); + state.apply(AppEvent::Core(CoreEvent::DeviceLoginChanged( + DeviceLoginView::failed_as(LoginFailure::Unreachable, "连不上服务器：dns error"), + ))); + let text = on_screen(&build(&state, &Form::new())); + assert!(text.contains("unreachable"), "{text}"); + assert!(text.to_lowercase().contains("could not reach"), "{text}"); + assert!(!text.to_lowercase().contains("not configured"), "{text}"); + assert!(!text.contains("ULL_MSA_CLIENT_ID"), "{text}"); + assert!(text.contains("Sign-in failed"), "标题仍是通用失败：{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, + countdown, + expired, + .. + } => { + assert_eq!(code, "ABCD-EFGH"); + assert!( + countdown.contains("15:00"), + "倒计时要画成 mm:ss：{countdown}" + ); + 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 { + countdown, expired, .. + } => { + assert!(*expired, "过期必须被标出来（面板要画「已过期，重试」）"); + assert!(!countdown.is_empty(), "过期也要有一句人话，不是空行"); + } + 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_msa.rs b/crates/app-iced/src/pages/account/tests_msa.rs new file mode 100644 index 0000000..3439e19 --- /dev/null +++ b/crates/app-iced/src/pages/account/tests_msa.rs @@ -0,0 +1,126 @@ +//! M178 的登录回退判据（从 `tests.rs` 拆出来守 400 行硬线）。 +//! +//! 这两条钉的是**页面这一半**：浏览器登录没走成、已回退设备码时，用户看到的是 +//! i18n 那句「为什么 + 怎么修」，而不是 AAD 的原始报文。core 那一半（真的回退、不白开监听口） +//! 在 `crates/core/tests/auth/microsoft_msalogin.rs`。 + +use unlucky_i18n::Lang; +use unlucky_presenter::dto::{ + AppEvent, BrowserLoginNote, CoreEvent, DeviceLoginView, LoginFailure, +}; +use unlucky_presenter::state::AppState; + +use super::avatar::Cache; +use super::login::browser_note_text; +use super::model::{DevicePanel, Form, Page}; +use super::tests::build; +use super::tests_text::{has_cjk, on_screen}; + +/// 中文界面的同一页（`build` 钉死英文，这里要中文那一套）。 +fn build_zh(state: &AppState, form: &Form) -> Page { + Page::build(state, form, &mut Cache::default(), Lang::ZhCn, 1180.0) +} + +/// **M178 守卫（页面这一半）**：浏览器登录没走成、已回退设备码时，页面上要有一句**可读的** +/// 中文/英文说明（含「怎么修」），且**不是** AAD 的原始报文。 +/// +/// 抓得住：`browser_note` 在 `device_panel` 里被丢掉（面板就只剩用户码，用户不知道为什么 +/// 变成了设备码）、或有人把 presenter 的原始诊断串（`invalid_request ...`）画上屏。 +/// 抓不住：这句提示在 1180 宽下会不会换行难看（那靠出图给 tower 看）。 +#[test] +fn a_browser_fallback_shows_a_readable_note_not_the_raw_aad_error() { + let mut state = AppState::new(); + state.apply(AppEvent::Core(CoreEvent::DeviceLoginChanged( + DeviceLoginView { + message: "invalid_request: The provided value for the input parameter 'redirect_uri' \ +is not valid. The expected value is a URI which matches a redirect URI registered for this client \ +application." + .to_string(), + ..DeviceLoginView::waiting("ABCD-EFGH", "https://www.microsoft.com/link", 900, "") + } + .with_browser_note(BrowserLoginNote::RedirectNotRegistered), + ))); + let page = build(&state, &Form::new()); + + // 1. 面板态带着说明码（不是只剩一个用户码） + match &page.device { + DevicePanel::Code { note, code, .. } => { + assert_eq!(*note, Some(BrowserLoginNote::RedirectNotRegistered)); + assert_eq!(code, "ABCD-EFGH"); + } + other => panic!("回退后仍是设备码面板，实际 {other:?}"), + } + + // 2. 英文界面上画出来的那一段：是 i18n 文案、含可照抄的修法，且没有 AAD 原始报文/中文 + let text = on_screen(&page); + assert!(!has_cjk(&text), "英文界面不许出现中文：{text}"); + assert!( + text.contains("http://localhost/auth"), + "提示里要给出可照抄的重定向 URI：{text}" + ); + assert!( + text.to_lowercase().contains("redirect uri"), + "提示里要点名「重定向 URI」这一项：{text}" + ); + assert!( + !text.contains("invalid_request"), + "原始报文不许上屏：{text}" + ); + assert!(!text.contains("AADSTS"), "原始报文不许上屏：{text}"); + assert!(!text.contains("is not valid"), "原始报文不许上屏：{text}"); + + // 3. 中文界面同样走一遍（复审 r1 P2-4）：文案来自**视图自己的出口** + // `login::browser_note_text`，中文要有、可照抄的修法要有、AAD 原始码不许有。 + let zh = build_zh(&state, &Form::new()); + let zh_text = on_screen(&zh); + assert!(has_cjk(&zh_text), "中文界面要真有中文：{zh_text}"); + let note_text = browser_note_text( + BrowserLoginNote::RedirectNotRegistered, + Lang::ZhCn.catalog(), + ); + assert!( + note_text.contains("http://localhost/auth"), + "中文文案也要给出可照抄的重定向 URI：{note_text}" + ); + assert!(note_text.contains("重定向 URI"), "{note_text}"); + assert!(note_text.contains("设备码"), "{note_text}"); + for forbidden in ["invalid_request", "AADSTS", "is not valid", "{"] { + assert!( + !zh_text.contains(forbidden), + "中文界面混进了原始报文：{zh_text}" + ); + assert!( + !note_text.contains(forbidden), + "词条混进了原始报文：{note_text}" + ); + } + // 视图那一行的来源就是这一条文案：取样函数与视图共用同一个出口（不是测试另写映射）。 + assert_eq!( + browser_note_text(BrowserLoginNote::PreflightUnavailable, Lang::En.catalog()), + "Could not confirm that browser sign-in is usable, so it switched to a device code." + ); +} + +/// 回退之后设备码又失败：失败面板上**两者都要在**（失败原因 + 为什么没走浏览器）。 +#[test] +fn a_failed_device_login_keeps_the_fallback_note() { + let mut state = AppState::new(); + state.apply(AppEvent::Core(CoreEvent::DeviceLoginChanged( + DeviceLoginView::failed_as( + LoginFailure::Unreachable, + "连不上 login.microsoftonline.com", + ) + .with_browser_note(BrowserLoginNote::PreflightUnavailable), + ))); + let page = build(&state, &Form::new()); + match &page.device { + DevicePanel::Failed { failure, note } => { + assert_eq!(*failure, LoginFailure::Unreachable); + assert_eq!(*note, Some(BrowserLoginNote::PreflightUnavailable)); + } + other => panic!("应是失败面板，实际 {other:?}"), + } + let text = on_screen(&page); + assert!(!has_cjk(&text), "{text}"); + assert!(text.contains("unreachable"), "失败码要画出来：{text}"); +} 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..6afa153 --- /dev/null +++ b/crates/app-iced/src/pages/account/tests_text.rs @@ -0,0 +1,108 @@ +//! 「**模型这一层会给出什么**」的取样器：视图模型字段 + **按码做的 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::{browser_note_text, failure_body_key, failure_title_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(¬ice.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, + countdown, + note, + .. + } => { + out.push_str(code); + out.push_str(link); + // 倒计时文案由模型拼好（M178：owned 文字路径画不出中文）。 + out.push_str(countdown); + // M178：回退说明走**视图自己的**文案出口（`login::browser_note_text`）， + // 不是测试另写一份映射——否则视图哪天不画这一行，取样仍会绿。 + if let Some(note) = note { + out.push_str(browser_note_text(*note, catalog)); + } + } + DevicePanel::Browser { + link, countdown, .. + } => { + out.push_str(link); + out.push_str(countdown); + } + DevicePanel::Failed { failure, note } => { + out.push_str(catalog.text(failure_title_key(*failure))); + out.push_str(catalog.text(failure_body_key(*failure))); + out.push_str(&catalog.render(Key::AccountFailureCode, &[("code", failure.code())])); + if let Some(note) = note { + out.push_str(browser_note_text(*note, catalog)); + } + } + 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..7ef46a3 --- /dev/null +++ b/crates/app-iced/src/pages/account/widgets.rs @@ -0,0 +1,385 @@ +//! 本页小件：头像块（首字母块 / 真图）、章节标题、轨道徽标。 +//! +//! ## 令牌纪律 +//! +//! 本文件**零**色值 / 字号 / 半径字面量：颜色一律 [`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::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, + actions: Vec>, +) -> 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(ui.card_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 +//! ``` +//! +//! - **入**：全部是**借用**的纯数据。会话三件（`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>, + /// 「这是模拟助手」的**四处文案**（副标题 / 占位符 / 空态正文 / 标题胶囊）， + /// 全部由 [`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, +} + +/// 画会话视图（**右栗与独立页的唯一实现**）。 +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> = 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, + 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::(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, +) -> 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> = 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> { + 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> { + 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`，助手栏要自己的 +/// 消息类型——这是 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::() { + 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), + /// 按下拖拽缝。 + 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>, + /// 这套后端是不是模拟的（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> { + // 判档用**这一窗宽下实际生效**的档位：窗窄到放不下 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> { + 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::(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::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 { + 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, +} + +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, 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") && !hosts.contains("Vec"), + "宿主里不许出现自持的会话容器" + ); +} + +/// 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/accent.rs b/crates/app-iced/src/pages/appearance/accent.rs new file mode 100644 index 0000000..61b6984 --- /dev/null +++ b/crates/app-iced/src/pages/appearance/accent.rs @@ -0,0 +1,181 @@ +//! 强调色的**运行期状态**（M250 ACCENTWIRE）：输入原文 → 解析结果 → 生效色。 +//! +//! 这一层存在的理由：`appearance.accent_color` 此前是死线——键、输入框、presenter 往返都在， +//! 但造 tokens 的唯一入口恒走 `DesignTokens::brand(board)`，用户填了色界面没变化。接线要落地 +//! 的不只是「把 hex 喂进 `Scheme::from_accent`」，还有**失败要可见**： +//! +//! | 输入 | 生效配色 | `error()` | 落盘值 | +//! |---|---|---|---| +//! | 空串 | 出厂品牌板（`DesignTokens::brand`） | `None` | `""` | +//! | `006A5C` | `DesignTokens::with_accent`（只换三族） | `None` | `#` + `006A5C` | +//! | `zzzzzz` / 超长串 | **保持上一次合法的值**（不静默回退成出厂色） | `Some(..)` | 上一次合法的值 | +//! | `#12`（还没打完） | 同上（还没生效） | `None`，`pending` 里挂着 | 上一次合法的值 | +//! +//! 「保持上一次合法值」而不是「回退出厂板」是刻意的：回退会让「填错」和「填对但没生效」在屏幕上 +//! 长得一模一样，用户唯一的线索就只剩那条错行——而那正是这里要保证不被丢掉的。 +//! +//! ## 何时才算「错」（M250 r1 p2-3） +//! +//! 受控输入框**每敲一个字符**都会调 [`Accent::set`]。手打 `006A5C` 的过程里，前 5 个字符都是 +//! `Short`，若立刻亮红就会闪 5 次——用户没打错，只是没打完。所以只有两种情形立刻报错： +//! +//! 1. **不可能再靠打字变合法**：出现非十六进制字符（`Digit`）或超过 6 位（`Long`）——任何继续 +//! 输入都只会更错，立刻亮； +//! 2. **提交**（[`Accent::commit`]）：离开这一格、点到别的外观控件、**按回车**（P18，M252 接的 +//! `Change::AccentCommit`）、或配置读回。 +//! +//! 配置读回走 [`Accent::new`]（`commit` 语义）：文件里存着坏值必须**当场**看得见，不能等用户来点。 +//! +//! 解析本身不在这里：`AccentChoice::parse` 是唯一真相（`unlucky_presenter::prefs`），本文件只负责 +//! 把结果接到色值与 UI 上。 + +use unlucky_design::color::Color; +use unlucky_presenter::prefs::{AccentChoice, AccentError}; + +/// 出图矩阵的强调色开关（`ULL_APPEARANCE_ACCENT=#RRGGBB`；产品路径读 `launcher.json`）。 +/// +/// 放在本文件而不是 `state.rs` 的 `ENV_*` 那一族：`state.rs` 正好 400 行（硬线），这一条 +/// 属于强调色自己，跟 `Accent` 放一起也更好找。语义与其它 `ULL_APPEARANCE_*` 一致——只影响这次进程。 +pub const ENV_ACCENT: &str = "ULL_APPEARANCE_ACCENT"; + +/// 出图矩阵的第二档（`ULL_APPEARANCE_ACCENT_COMMIT=1`）：把 [`ENV_ACCENT`] 灌进来的值当作 +/// **已提交**（[`Accent::commit`]）。 +/// +/// P18 / M252：「打了一半就放着」的 `#12` 平时**不**亮红，按回车才亮。出图通道没有键盘，所以用这个 +/// 开关把那一帧拍下来——它拍的是 `commit()` 之后的**同一个状态**，不是另一条渲染分支。 +/// 语义同族：只影响这次进程，产品路径不读它。 +pub const ENV_ACCENT_COMMIT: &str = "ULL_APPEARANCE_ACCENT_COMMIT"; + +/// 强调色的运行期状态（`App` 经 `pages::appearance::State` 持有一份）。 +#[derive(Debug, Clone, PartialEq)] +pub struct Accent { + /// 输入框的原文（受控控件要它；非法输入也必须原样留着，否则用户看不见自己错在哪）。 + text: String, + /// 上一次**合法**的解析结果（非法输入不改它 —— 生效色因此不会跳回出厂板）。 + choice: AccentChoice, + /// 解析出来的强调色（`None` = 出厂板，强调色由品牌色板决定）。 + color: Option, + /// **现在要显示**的结构化原因（`None` = 不显示）。 + error: Option, + /// 已经打错、但「还可能被打字修好」的原因（输入中暂不显示，[`Accent::commit`] 才亮出来）。 + pending: Option, +} + +impl Accent { + /// 从配置读一份（启动时调一次）。配置里存着非法值时**当场**亮错行，不静默吞掉。 + #[must_use] + pub fn new(text: &str) -> Self { + let mut accent = Self { + text: text.to_owned(), + choice: AccentChoice::Factory, + color: None, + error: None, + pending: None, + }; + accent.retry(true); + accent + } + + /// 设置页改了一次输入（受控输入框：每敲一个字符都走这里）。 + /// + /// 「短但还可能是合法前缀」的输入只挂进 `pending`，不亮红（见模块文档 §何时才算「错」）。 + pub fn set(&mut self, text: &str) { + self.text = text.to_owned(); + self.retry(false); + } + + /// 配置被外部改写后重置（热切：CLI / AI 改完 1 秒内生效）。 + pub fn reset(&mut self, text: &str) { + *self = Self::new(text); + } + + /// 提交：把「输入中暂不报」的错亮出来。离开这一格就该走它（见 [`Accent::pending`]）。 + /// + /// 三个触发点：点到别的外观控件 / 按回车（P18 `Change::AccentCommit`）/ 配置读回。 + /// 幂等：已经亮着错再提交一次什么都不做。 + pub fn commit(&mut self) { + if self.error.is_none() { + self.error = self.pending.take(); + } + } + + /// 把 `ULL_APPEARANCE_ACCENT` / `ULL_APPEARANCE_ACCENT_COMMIT` 灌进来（不设 = 不动）。 + /// + /// 第一档 = 「像刚敲进去的」（走输入中规则）；再给它 `…_COMMIT=1` 就等于「刚按下回车」。 + /// 两档合起来才拍得出 P18 的对照：同一条 `#12`，回车前不亮、回车后亮红。 + pub fn apply_env(&mut self) { + let Ok(value) = std::env::var(ENV_ACCENT) else { + return; + }; + self.set(&value); + if std::env::var_os(ENV_ACCENT_COMMIT).is_some_and(|flag| flag != "0") { + self.commit(); + } + } + + /// 输入框原文。 + #[must_use] + pub fn text(&self) -> &str { + &self.text + } + + /// 要显示的结构化失败原因（`None` = 合法，或还没打完）。 + #[must_use] + pub fn error(&self) -> Option { + self.error + } + + /// 解析出来的强调色（`None` = 出厂板；`rebuild_ui` 与出图判据读它）。 + #[must_use] + pub fn color(&self) -> Option { + self.color + } + + /// 落盘值：`""` = 出厂，`#RRGGBB` = 自定义。**永远是上一次合法值**——非法手输不写盘。 + #[must_use] + pub fn persist_value(&self) -> &str { + self.choice.as_str() + } + + /// 取证日志里的一个词：`factory` / 规范化的 hex / `invalid(..)` / `pending(..)`。 + /// + /// 为什么日志要带这个：截图与真机复现只能靠一行文字分辨「强调色没生效」与「强调色生效了但 + /// 图上看不出来」——后者是这条 mission 的验收判据，前者是它的 bug。 + #[must_use] + pub fn log_token(&self) -> String { + if let Some(error) = self.error { + return format!("invalid({error:?})"); + } + if let Some(error) = self.pending { + return format!("pending({error:?})"); + } + if self.choice.as_str().is_empty() { + "factory".to_owned() + } else { + self.persist_value().to_owned() + } + } + + /// 按当前 `text` 重算：合法 ⇒ 换色 + 清错；非法 ⇒ **色不动**，按 `show` 决定报不报。 + fn retry(&mut self, show: bool) { + match AccentChoice::parse(&self.text) { + Ok(choice) => { + self.color = Color::from_hex(choice.as_str()); + self.choice = choice; + self.error = None; + self.pending = None; + } + Err(error) => { + // 只有「位数不足」还有机会靠继续打字补成合法；非 hex 字符与超 6 位已经回不了头。 + let hopeless = !matches!(error, AccentError::Short { .. }); + if show || hopeless { + self.error = Some(error); + self.pending = None; + } else { + self.pending = Some(error); + self.error = None; + } + } + } + } +} 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 { + 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..aa7d6e8 --- /dev/null +++ b/crates/app-iced/src/pages/appearance/background.rs @@ -0,0 +1,359 @@ +//! 背景图：**读盘解码（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_i18n::catalog::Key; +use unlucky_i18n::Lang; +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::note`]）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum LoadError { + /// 读文件失败：不存在 / 没权限 / 被占用。 + Io(String), + /// 解码失败：格式不认识（webp/tiff 等没开编码器）/ 文件截断 / 不是图片。 + Undecodable(String), + /// 图片头里的尺寸超限。 + TooLarge { + /// 宽。 + width: u32, + /// 高。 + height: u32, + }, +} + +/// 一条**可翻译**诊断：`key` + 已经格式化好的参数（模板里只有 `{name}`，见 [`Key`]）。 +/// +/// 为什么不是 `String`：文案表在金表里（M180 `I18NAPPEAR`），本模块只给「哪条 key + 哪些值」。 +/// 数字在这一层就格式化好（`{:.2}` / `{:?}` 这些格式说明词表不支持）。 +/// +/// 为什么 `types` 是 `String` 而不是 `&'static str`：`Io(reason)` / `Undecodable(reason)` 的原因来自 +/// 磁盘与解码库（运行时字符串），只能持有。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Note { + key: Key, + args: Vec<(&'static str, String)>, +} + +impl Note { + /// 组装一条（参数名必须与译文里的 `{name}` 逐字相同）。 + fn new(key: Key, args: Vec<(&'static str, String)>) -> Self { + Self { key, args } + } + + /// 这条诊断是哪条文案。 + #[must_use] + pub fn key(&self) -> Key { + self.key + } + + /// 参数（名 → 已成形的值）。 + #[must_use] + pub fn args(&self) -> Vec<(&str, &str)> { + self.args + .iter() + .map(|(name, value)| (*name, value.as_str())) + .collect() + } + + /// 按语言取整句（`{name}` 全替换；缺参时占位符原样留着，见 [`unlucky_i18n::catalog::Catalog::render`]）。 + #[must_use] + pub fn render(&self, lang: Lang) -> String { + lang.catalog().render(self.key, &self.args()) + } + + /// 英文基线里有没有这个子串。 + /// + /// 给**跨 mission 的既有断言**用（`app/tests/appearance.rs` 查「诊断里有没有说出原因」）， + /// 那条断言不在本 mission 的 scope 里、不能改成按 key 断言。UI 一律走 [`Self::render`]。 + #[must_use] + pub fn contains(&self, needle: &str) -> bool { + self.render(Lang::En).contains(needle) + } +} + +impl LoadError { + /// 可翻译诊断（设置页提示行与日志共用同一条 key）。 + #[must_use] + pub fn note(&self) -> Note { + match self { + Self::Io(reason) => Note::new( + Key::SettingsAppearanceBgReadFailed, + vec![("reason", reason.clone())], + ), + Self::Undecodable(reason) => Note::new( + Key::SettingsAppearanceBgDecodeFailed, + vec![("reason", reason.clone())], + ), + Self::TooLarge { width, height } => Note::new( + Key::SettingsAppearanceBgTooLarge, + vec![ + ("width", width.to_string()), + ("height", height.to_string()), + ("limit", MAX_SOURCE_EDGE.to_string()), + ], + ), + } + } +} + +/// 一张解码好的背景图。 +#[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, +} + +impl Image { + /// 从已解码的数据构造（测试也走这里，避免测试依赖磁盘）。 + #[must_use] + pub fn from_rgba(source: (u32, u32), width: u32, height: u32, rgba: Vec) -> Self { + Self { + source, + width, + height, + rgba, + } + } +} + +/// 读盘 + 解码 + 缩到 [`MAX_EDGE`] 内。 +/// +/// # Errors +/// 见 [`LoadError`]：读不到 / 解不开 / 头部尺寸超限。**不 return 默认色**——回落的决定在 +/// [`super::palette`]（它会往 `Provenance` 里留原因），这一层只管如实报告失败。 +pub fn load(path: &str) -> Result { + 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 { + 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(Note::new( + Key::SettingsAppearanceBgSmallTile, + vec![ + ("width", image.source.0.to_string()), + ("height", image.source.1.to_string()), + ("max", MAX_TILES.to_string()), + ], + )) +} + +/// 暗化系数（叠在图上那层底色的 α）：`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..b455372 --- /dev/null +++ b/crates/app-iced/src/pages/appearance/background/tests.rs @@ -0,0 +1,235 @@ +//! `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_i18n::catalog::Key; +use unlucky_i18n::Lang; +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（不许静默回默认色），且 note() 给出**哪条 key + 哪些参数**（句子在词表里）。 + // 抓不住：webp/tiff 这类没开编码器的格式具体报什么字符串（只钉分类，不钉解码库原文）。 + let missing = temp_file("missing", "bg.png"); + let error = load(missing.to_str().unwrap()).expect_err("不存在的路径必须报错"); + assert!(matches!(error, LoadError::Io(_)), "实际 {error:?}"); + let note = error.note(); + assert_eq!(note.key(), Key::SettingsAppearanceBgReadFailed); + assert!( + note.contains("could not be read"), + "英文基线要说出「读不出来」：{}", + note.render(Lang::En) + ); + + 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:?}"); + assert_eq!( + error.note().key(), + Key::SettingsAppearanceBgDecodeFailed, + "解不开与读不出来必须是两条 key（措辞与修法都不同）" + ); + 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:?}" + ); + let note = error.note(); + assert_eq!(note.key(), Key::SettingsAppearanceBgTooLarge); + assert!( + note.contains("too large"), + "英文基线要说出「太大」：{}", + note.render(Lang::En) + ); + let args = note.args(); + assert!( + args.contains(&("width", "9000")) && args.contains(&("height", "4")), + "宽高要作为参数传进去（不是写进译文）：{args:?}" + ); + assert!( + args.contains(&("limit", "8192")), + "上限走占位符而不是写进译文：{args:?}" + ); + // 上限不许再放宽（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_eq!(note.key(), Key::SettingsAppearanceBgSmallTile); + let args = note.args(); + assert!( + args.contains(&("width", "32")) && args.contains(&("height", "32")), + "尺寸作为参数：{args:?}" + ); + assert!( + args.contains(&("max", "64")), + "块数上限走占位符（`MAX_TILES` 改了不该动译文）：{args:?}" + ); + assert!( + note.render(Lang::En).contains("scaled up"), + "英文基线要说出「会被放大」：{}", + note.render(Lang::En) + ); + + // 非 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..bf4f52d --- /dev/null +++ b/crates/app-iced/src/pages/appearance/mod.rs @@ -0,0 +1,191 @@ +//! # 外观接线（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/` | 设置页「外观」分组（真控件）：壳 + 五段控件，M179 从单文件拆开 | 无 | +//! | `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] 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 accent; +pub mod alpha; +pub mod background; + +mod palette; +mod picture; +#[cfg(test)] +pub(crate) mod probe; +mod section; +mod state; +#[cfg(test)] +mod tests; + +/// 状态提示的 **tonal notice**（行数硬顶把 `section/` 撑开之后它仍放在模块根）。 +/// +/// `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), + /// 自定义强调色输入（M250：原文；空串 = 恢复出厂板）。 + Accent(String), + /// **强调色回车提交**（P18 / M252）：不带值，只表示「用户按了回车，把打了一半的东西定下来」。 + /// + /// 为什么不复用 `Accent(原文)`：那个是**每一次按键**（`Accent::set`，输入中不报短错）， + /// 而回车是 [`Accent::commit`](super::accent::Accent::commit) 的第三个触发点（另两个是 + /// 「点到别的外观控件」与「配置读回」）——把 `#12` 这种打了一半就放着的值亮成红框， + /// 同时**不写盘**（落盘永远取上一次合法值）。 + AccentCommit, + /// 设置页切分组（左列点选）。 + 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::Accent(_) => unlucky_presenter::prefs::keys::ACCENT_COLOR, + // 回车提交不产生新值，但**属于**强调色那一格 ⇒ 仍然点名到这个键（走 bridge 再写一次 + // 上一次合法值，见 `App::on_appearance`）。 + Self::AccentCommit => unlucky_presenter::prefs::keys::ACCENT_COLOR, + Self::SelectGroup(_) => return None, + }) + } + + /// 这条改动的落盘字符串形态（与 `schema` 的取值词表逐字一致）。 + /// + /// `None` = 不落盘（分组选择）。数字一律给 `f64` 的十进制字面量（`store.set` 按 schema 类型转）。 + /// + /// ⚠️ `Accent` 这一格的字符串是**用户原文**：真正落盘的值来自 + /// `State::current_values()` 的 `accent_color`（上一次**合法**值，见 `accent::Accent`）， + /// 因为非法手输不许写进配置。这里保留原文只为「每条改动都点名到自己的键」这条不变量。 + #[must_use] + pub fn value(&self) -> Option { + 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::Accent(text) => text.clone(), + // 回车**不改值**：真正的落盘值一直是 `current_values()` 里的上一次合法值。 + Self::AccentCommit => return None, + Self::SelectGroup(_) => return None, + }) + } +} 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..c20ecb9 --- /dev/null +++ b/crates/app-iced/src/pages/appearance/palette.rs @@ -0,0 +1,330 @@ +//! 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()` 翻成一条词表 key（M180：句子在 `catalog/settings/appearance.rs`， +//! 这里只给 key——中文界面下这句提示也是中文）。 +//! +//! ## 为什么不在这里做对比度 +//! +//! WCAG 收敛在 `unlucky_design` 里（`converge` + `check`，任何来源的方案都跑同一套）。本文件 +//! 只负责「选哪一级」，越俎代庖会让两条路径各有一套门禁。测试里仍然断言「任何一级的结果都 +//! `is_clean()`」，那是**验收**，不是实现。 + +use unlucky_design::color::{Scheme, SchemeFlavor}; +use unlucky_design::palette::{resolve_source, ImageInput, Level, Provenance}; +use unlucky_i18n::catalog::Key; +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> { + 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 + } + + /// 提示 key（`None` = 一级成功、没什么可解释的）。 + #[must_use] + pub fn note(&self) -> Option { + 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()` → 一条词表 key（M180：句子在 `catalog/settings/appearance.rs`）。 +/// +/// 键的完整表在 `unlucky_design::palette::resolve::Provenance::hint_key` 的文档里； +/// 这里只翻「本 mission 真会产生的那几个」，未识别键返回 `None` 而不是编一句话。 +#[must_use] +pub fn note(provenance: &Provenance) -> Option { + Some(match provenance.hint_key()? { + "palette.hint.background.undecodable" => Key::SettingsAppearancePaletteBgUndecodable, + "palette.hint.background.too-small" => Key::SettingsAppearancePaletteBgTooSmall, + "palette.hint.background.bad-dimensions" => Key::SettingsAppearancePaletteBgBadDimensions, + "palette.hint.background.no-opaque-pixels" => { + Key::SettingsAppearancePaletteBgNoOpaquePixels + } + "palette.hint.background.low-chroma" => Key::SettingsAppearancePaletteBgLowChroma, + "palette.hint.background.contrast" => Key::SettingsAppearancePaletteBgContrast, + "palette.hint.wallpaper.undecodable" => Key::SettingsAppearancePaletteWallpaperUndecodable, + "palette.hint.wallpaper.low-chroma" => Key::SettingsAppearancePaletteWallpaperLowChroma, + "palette.hint.wallpaper.too-small" => Key::SettingsAppearancePaletteWallpaperTooSmall, + "palette.hint.wallpaper.bad-dimensions" => { + Key::SettingsAppearancePaletteWallpaperBadDimensions + } + "palette.hint.wallpaper.no-opaque-pixels" => { + Key::SettingsAppearancePaletteWallpaperNoOpaquePixels + } + "palette.hint.wallpaper.contrast" => Key::SettingsAppearancePaletteWallpaperContrast, + "palette.hint.preset.contrast" => Key::SettingsAppearancePalettePresetContrast, + "palette.hint.adjusted" => Key::SettingsAppearancePaletteAdjusted, + _ => return None, + }) +} + +/// 生效层级**码值** → 已有的那三条档位 key（M180 复审 P2-2：中文界面里不许留机器码）。 +/// +/// 码值的全部来源只有两处，取值集合相同：`Level::code()`（`background-image` / `wallpaper` / +/// `preset`）与 `PaletteSource::as_str()`（同三个词）。所以三条 key 就够，**不新增平行词表**—— +/// 卡片底部「配色来源」用它们表示**用户选的**档，这一行用它们表示**回落之后真正生效**的档。 +/// +/// 未识别的码值落到 `background-image` 那条（宁可显示一个偏保守的档名，也不许把机器码漏进 +/// 中文界面——这条兜底本身由 `tests` 里的 `every_level_code_maps_to_its_own_sentence` 钉住）。 +/// `state.rs` 已贴 400 行线，所以这个映射住在本文件。 +#[must_use] +pub fn level_key(code: &str) -> Key { + match code { + "preset" => Key::SettingsAppearancePalettePreset, + "wallpaper" => Key::SettingsAppearancePaletteWallpaper, + _ => Key::SettingsAppearancePaletteBackground, + } +} + +#[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_i18n::catalog::Key; + 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(Key::SettingsAppearancePaletteBgUndecodable) + ); + 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_eq!( + resolved.note(), + Some(Key::SettingsAppearancePaletteBgLowChroma), + "灰图的回落原因要指名「彩度不足」" + ); + } + + #[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 + ); + } + + /// **M180 复审 P2-2 的守门**：生效层级的**每一个码值**都必须映射到它自己那条中文句子。 + /// + /// 抓得住：① 三个码值被映射到同一条 key（界面上分不出到底生效的是哪一级）； + /// ② 某条映射被删掉 / 写错（`preset` 落到 background 那条 ⇒ 中文界面说「取自背景图」）； + /// ③ 有人再加一级却忘了扩映射。 + /// 抓不住：译文本身的措辞（那是 `catalog/settings/appearance.rs` 的译文守卫的事）。 + /// + /// 变异证明：把 `"preset"` 那行删掉（落进兜底）⇒ 本条红，且 `assert_ne!` 直接点名码值。 + /// + /// 为什么这条必须有：`the_appearance_card_speaks_chinese` 断的是**整句**非 ASCII， + /// 而「配色：preset」里有汉字 ⇒ 整句非 ASCII ⇒ 那个守卫放过它。这个口子只能在这里堵。 + #[test] + fn every_level_code_maps_to_its_own_sentence() { + use super::level_key; + + let codes = ["background-image", "wallpaper", "preset"]; + let keys: Vec = codes.iter().copied().map(level_key).collect(); + assert_eq!( + keys, + vec![ + Key::SettingsAppearancePaletteBackground, + Key::SettingsAppearancePaletteWallpaper, + Key::SettingsAppearancePalettePreset, + ], + "码值与档位 key 必须一一对应" + ); + + // 三条中文句子互不相同（否则「映射对了」但界面上仍分不出层级）。 + let zh = unlucky_i18n::Lang::ZhCn.catalog(); + let mut texts: Vec<&str> = keys.iter().map(|key| zh.text(*key)).collect(); + let total = texts.len(); + texts.sort_unstable(); + texts.dedup(); + assert_eq!(texts.len(), total, "三条档位译文有重复：{texts:?}"); + } +} 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> { + 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::>(); + iced::widget::row(cells) + .width(Length::Fill) + .height(Length::Fixed(height)) + .into() + }) + .collect::>(); + + column(rows).width(Length::Fill).height(Length::Fill).into() +} diff --git a/crates/app-iced/src/pages/appearance/probe.rs b/crates/app-iced/src/pages/appearance/probe.rs new file mode 100644 index 0000000..b2f4774 --- /dev/null +++ b/crates/app-iced/src/pages/appearance/probe.rs @@ -0,0 +1,68 @@ +//! **测试专用**：记录「画一帧时从词表取出的每一条译文」。 +//! +//! ## 为什么需要这一层 +//! +//! 判据是「中文界面下外观分组渲染出来的字里必须含汉字」，但 iced 0.14 **没有**可以遍历控件树的 +//! 公开接口： +//! +//! - `Element::as_widget()` 拿到的是 `&dyn Widget`，而 `Widget::children()` 返回的是**状态** `Tree` +//! （不是子控件），没有 `as_any` 之类的向下转型口； +//! - 想走 `Widget::operate` 得自己造 `Tree` + 跑布局 + 传 `Renderer`，而单测里**没有渲染器** +//! （`pages/download/tests/options_screen.rs` 记的正是这条边界）。 +//! +//! 所以取证点退到「字进树之前」那一层：`section::t` / `section::tr` 是本分组**唯一**两个取词口， +//! 它们把每条译文顺手记一份（M180 起分成两份：`t()` 的 `&'static str` 与 `tr()` 替换完占位符的 +//! 整句），测试再断言这批字里有没有汉字。这不是「看源码字符串」那种假守卫——它要求真的把 +//! [`crate::pages::appearance::section`] 跑一遍（并且走 `settings::view` 的语言分发），只是不画像素。 +//! +//! ## 为什么是 thread-local +//! +//! `cargo test` 默认多线程跑，每个测试一个线程；thread-local 让并发测试的取证互不串台， +//! 也不需要加锁或串行化。 +//! +//! 整个模块只在 `#[cfg(test)]` 下编译，产品路径零代价。 + +use std::cell::RefCell; + +use unlucky_i18n::catalog::Key; + +// 自上次 `take` 以来记录下的 `(key, 译文)`，顺序 = 取词顺序（`t()` 取的 `&'static str`）。 +thread_local! { + // clippy 1.99.1（= 本仓 CI 的 stable）对这条 lint **误报**：初始化器已经写成 `const { … }` + // 它还是报「can be made const」。最小复现（clippy-driver 原地可验，无本仓任何符号）： + // `thread_local!{ static X: RefCell> = const { RefCell::new(Vec::new()) }; }` + // —— 同一个文件加不加 `const` 报同一句。等 clippy 修掉这条误报即可删掉本行 allow。 + #[allow(clippy::missing_const_for_thread_local)] + static TEXTS: RefCell> = const { RefCell::new(Vec::new()) }; +} + +// 自上次 `take_rendered` 以来记录下的 `(key, 整句)`：`tr()` 那条带占位符的路径（M180 加）。 +// +// 为什么单独一份而不是把上面那份改成 `String`：M179 的守卫 +// （`pages/settings/tests/appearance_section.rs::the_appearance_group_speaks_chinese_when_the_interface_does`） +// 断言的是 `&'static str`，那个文件不在 M180 的 scope 里、不能跟着改签名。两份记录各自的 +// `take*` 也各自清空，互不干扰。 +thread_local! { + #[allow(clippy::missing_const_for_thread_local)] + static RENDERED: RefCell> = const { RefCell::new(Vec::new()) }; +} + +/// 记一条（由 [`super::section::t`] 调用；不对外）。 +pub(crate) fn record(key: Key, text: &'static str) { + TEXTS.with(|texts| texts.borrow_mut().push((key, text))); +} + +/// 记一条**替换完占位符**的整句（由 [`super::section::tr`] 调用；不对外）。 +pub(crate) fn record_rendered(key: Key, text: String) { + RENDERED.with(|texts| texts.borrow_mut().push((key, text))); +} + +/// 取走并清空本线程记录下的取词（测试用）。 +pub(crate) fn take() -> Vec<(Key, &'static str)> { + TEXTS.with(|texts| std::mem::take(&mut *texts.borrow_mut())) +} + +/// 取走并清空本线程记录下的整句（测试用）。 +pub(crate) fn take_rendered() -> Vec<(Key, String)> { + RENDERED.with(|texts| std::mem::take(&mut *texts.borrow_mut())) +} diff --git a/crates/app-iced/src/pages/appearance/section/accent.rs b/crates/app-iced/src/pages/appearance/section/accent.rs new file mode 100644 index 0000000..da81fff --- /dev/null +++ b/crates/app-iced/src/pages/appearance/section/accent.rs @@ -0,0 +1,294 @@ +//! 外观分组第 ⓪ 段（视觉上排在最前）：**自定义强调色**（M250 ACCENTWIRE）。 +//! +//! 为什么这一段值得单开：`appearance.accent_color` 从 M41 起就有键、有 presenter 往返、 +//! 有 `ACCENT_PRESETS` 色板，却**没有任何 UI 写者**——造 tokens 的唯一入口恒走 +//! `DesignTokens::brand(board)`，用户即使改了配置文件，界面也不会变。接线之后这一段就是那条 +//! 链路的手动入口，也是**非法值唯一能被看见的地方**（错行紧贴输入框，不折叠、不写进日志了事）。 +//! +//! ## 三件控件对应的键与消息 +//! +//! | 控件 | 键 | 消息 | +//! |---|---|---| +//! | 强调色文本框（受控，输入即生效） | `appearance.accent_color` | [`Change::Accent`] | +//! | 「出厂」+ 8 个预设色块 | 同上（写入色板里的 hex） | [`Change::Accent`] | +//! | 非法值错行 | —（不进配置） | 无 | +//! +//! ## 色块为什么画成圆点而不是药丸 +//! +//! 9 颗写着十六进制串的药丸会变成一排噪声，而且色相要靠读字获取——色板控件的可见内容**就是** +//! 颜色本身。所以色块 = `ShapeScale::Full` 的实心圆 + 描边；选中态加粗描边（不靠色相区分： +//! 色块底下垫的是它自己的颜色，色相对比不可靠）。 + +use iced::widget::tooltip::{self, Tooltip}; +use iced::widget::{button, column, container, row, text, Space as Gap}; +use iced::{Background, Border, Element, Length, Padding, Shadow, Theme as IcedTheme}; + +use unlucky_design::color::Role; +use unlucky_design::shape::ShapeScale; +use unlucky_design::spacing::Space; +use unlucky_i18n::catalog::Key; +use unlucky_i18n::Lang; +use unlucky_presenter::prefs::{AccentError, ACCENT_PRESETS}; + +use crate::app::components::inputs::{text_field, Field}; +use crate::pages::Message; +use crate::theme::{to_iced, Ui, STROKE_PX}; + +use super::super::accent::Accent; +use super::super::state::State; +use super::super::Change; +use super::{choice, label, note_line, t, tr}; + +/// 把 ⓪ 段推进 `rows`。 +pub(super) fn push<'a>( + ui: &'a Ui, + state: &'a State, + lang: Lang, + rows: &mut Vec>, +) { + let accent = &state.accent; + + // 受控输入框 + 失败态：`Field::error()` 让框本身变成错误色，错行再补「错在哪」。 + let mut field = Field::new(accent.text()) + .label(t(Key::SettingsAppearanceAccent, lang)) + .placeholder("#RRGGBB") + // P18：回车 = 立即提交（把「打了一半就放着」的 `#12` 亮成红框 + 错行）。 + // **不是**逐键报错：敲字那条路（`Change::Accent`）照旧只在「不可能再变合法」时才亮红。 + .on_submit(accent_commit); + if accent.error().is_some() { + field = field.error(); + } + let input: Element<'a, Message> = text_field(ui, field, |value| { + Message::Appearance(Change::Accent(value)) + }); + rows.push( + column![label(ui, t(Key::SettingsAppearanceAccent, lang)), input] + .spacing(ui.space(Space::X1)) + .width(Length::Fill) + .into(), + ); + + rows.push(presets(ui, accent, lang)); + + // 非法值：**结构化的原因**，不是「格式不对」这种没法行动的一句话。 + if let Some(error) = accent.error() { + let text = reason(lang, error); + rows.push(note_line(ui, &text, ui.color(Role::Error))); + } + + // 说明：空 = 出厂板；自定义色只换三族（中性表面与 error 保持基线是 design 既定语义）。 + rows.push(note_line( + ui, + t(Key::SettingsAppearanceAccentHint, lang), + ui.color(Role::OnSurfaceVariant), + )); +} + +/// 回车那一下要发的那条消息——**唯一产地**（M252 / P18）。 +/// +/// 抽成函数是为了让「回车 = 提交」这件事在源码里只有一个写法：`section/accent.rs` 把它交给 +/// `Field::on_submit`，测试按它钉住「回车走的是 `AccentCommit` 而不是又一条 `Accent(原文)`」 +/// （后者是**逐键**路径，会把已经亮出来的错重新吞回去）。 +fn accent_commit() -> Message { + Message::Appearance(Change::AccentCommit) +} + +/// 「预设」两行：先「标签 + 出厂」，再一排 8 颗色块。 +/// +/// 为什么分两行：一行放 9 个控件在设置卡片的正文宽度里会被挤成「7 + 1」折行，最后一颗色块 +/// 孤零零掉到下一行（出图实测）。分两行是**有意**的排版，不是被挤出来的。 +fn presets<'a>(ui: &'a Ui, accent: &'a Accent, lang: Lang) -> Element<'a, Message> { + let current = accent.persist_value(); + let head = row![ + container(label(ui, t(Key::SettingsAppearanceAccentPresets, lang))) + .align_y(iced::Alignment::Center), + choice( + ui, + t(Key::SettingsAppearanceAccentFactory, lang), + current.is_empty(), + Change::Accent(String::new()), + ), + ] + .spacing(ui.space(Space::X2)) + .align_y(iced::Alignment::Center); + + let swatches: Vec> = ACCENT_PRESETS + .iter() + .map(|hex| swatch(ui, hex, current == *hex)) + .collect(); + + column![ + head, + row(swatches) + .spacing(ui.space(Space::X2)) + .align_y(iced::Alignment::Center), + ] + .spacing(ui.space(Space::X2)) + .width(Length::Fill) + .padding(Padding::from([ui.space(Space::X2), 0.0])) + .into() +} + +/// 一颗色块：实心圆 + 描边（选中态加粗）。点击写入该预设。 +fn swatch<'a>(ui: &'a Ui, hex: &'static str, selected: bool) -> Element<'a, Message> { + let fill = unlucky_design::color::Color::from_hex(hex).map(to_iced); + // 直径取控件高度的六成（40 → 24dp）：与药丸按钮同一行时不抢节奏。 + let diameter = ui.metrics().control_height * 0.6; + let ring = if selected { + ui.color(Role::OnSurface) + } else { + ui.color(Role::OutlineVariant) + }; + let width = if selected { STROKE_PX * 2.0 } else { STROKE_PX }; + let radius = ui.radius(ShapeScale::Full, diameter); + + let dot: Element<'a, Message> = button( + Gap::new() + .width(Length::Fixed(diameter)) + .height(Length::Fixed(diameter)), + ) + .padding(Padding::from(0.0)) + .style(move |_theme: &IcedTheme, status| button::Style { + background: fill.map(Background::Color), + text_color: ring, + border: Border { + color: match status { + button::Status::Hovered | button::Status::Pressed => ui.color(Role::OnSurface), + _ => ring, + }, + width, + radius, + }, + shadow: Shadow::default(), + snap: true, + }) + .on_press(Message::Appearance(Change::Accent(hex.to_owned()))) + .into(); + + // 色块本体只有颜色、没有字：补一条可读提示（hex），否则键盘与读屏用户只能靠位置辨色。 + Tooltip::new(dot, hint(ui, hex), tooltip::Position::Top).into() +} + +/// 色块的悬停提示：`Overlay` 底 + `BodySmall` 的 hex 原文（与 `pages/agent` 的 tooltip 同一手法）。 +fn hint<'a>(ui: &'a Ui, hex: &'a str) -> iced::widget::Container<'a, Message> { + let style = ui.style(unlucky_design::typography::TypeRole::BodySmall); + container( + text(hex.to_owned()) + .size(style.size_px) + .font(ui.font_of(style)) + .color(ui.color(Role::OnSurface)), + ) + .padding(Padding::from([ui.space(Space::X1), ui.space(Space::X2)])) + .style(move |_theme: &IcedTheme| container::Style { + background: Some(Background::Color( + ui.layer(unlucky_design::elevation::MaterialLayer::Overlay), + )), + border: Border { + radius: ui.radius_dp(ShapeScale::Small), + ..Border::default() + }, + ..container::Style::default() + }) +} + +/// 结构化原因 → 一句话（参数由 Rust 侧格式化，词表只认 `{name}`）。 +fn reason(lang: Lang, error: AccentError) -> String { + match error { + AccentError::Short { digits } => tr( + lang, + Key::SettingsAppearanceAccentShort, + &[("digits", &digits.to_string())], + ), + AccentError::Long { digits } => tr( + lang, + Key::SettingsAppearanceAccentLong, + &[("digits", &digits.to_string())], + ), + AccentError::Digit { ch } => tr( + lang, + Key::SettingsAppearanceAccentDigit, + &[("ch", &visible(ch))], + ), + } +} + +/// 把一个字符变成**看得见**的形态：控制字符 / 空白 / 零宽与双向控制符（`Cf`）一律写 `U+XXXX`。 +/// +/// 为什么不能直接 `ch.to_string()`：用户粘进来的可能是不换行空格、零宽空格或 RTL 覆盖符—— +/// 那几个字符在句子里**看不见**，错行会变成「强调色里有非十六进制字符：」后面一片空白， +/// 用户根本不知道自己错在哪。 +fn visible(ch: char) -> String { + if ch.is_alphanumeric() || ch.is_ascii_graphic() { + ch.to_string() + } else { + format!("U+{:04X}", u32::from(ch)) + } +} + +#[cfg(test)] +mod tests { + use super::visible; + + /// 本文件源码（源码结构断言用，与 `pages/layout/source.rs` 同一条纪律）。 + const SOURCE: &str = include_str!("accent.rs"); + + /// **M252 / P18 回车接线的判据**：`push` 里有一**行代码**接了 `on_submit`，实参整取等于 + /// `accent_commit`，且那个产地发的确实是 `AccentCommit`（提交）而不是 `Accent(原文)`（敲字）。 + /// + /// iced 的 `Element` 没有内省接口（见 `pages::layout::source` 的模块文档），所以「回车真的 + /// 按下去」在这里量不到——能钉住的是**它接的是哪条消息**。 + /// + /// - 抓得住：`.on_submit(..)` 被删掉 **或注释掉**（`source::code_line` 先剥注释，判的是**代码行**）； + /// 实参被换成同前缀的别的产地（`accent_commit_none`——`call_arguments` 是**整取**，不是子串）； + /// 接成 `Change::Accent(原文)`（那是**逐键**路径，`retry(false)` 会把已经亮起来的错吞回去）。 + /// - 抓不住：按键真的到达控件（iced 的 `Widget::update`）、以及红框/错行画没画（出图负责）。 + #[test] + fn the_accent_field_wires_enter_to_commit() { + let body = crate::pages::layout::source::function_body(SOURCE, "fn push"); + let line = + crate::pages::layout::source::code_line(body, ".on_submit(").unwrap_or_else(|| { + panic!("`push` 里没有一行**代码**接 `on_submit`（注释掉也算没有）：\n{body}") + }); + + // 实参**整取**（不是子串）：`accent_commit_none` 这种同前缀产地不许静默通过。 + assert_eq!( + crate::pages::layout::source::call_arguments(&line, ".on_submit("), + vec!["accent_commit"], + "回车必须接 `accent_commit`（唯一产地），实际接线：{line}" + ); + + // 产地本身发什么：先看**代码行**（注释里的字不算），再跑一次拿 `Debug` 文本核形态 + // （`Message` 没有 `PartialEq`）。 + let factory = crate::pages::layout::source::function_body(SOURCE, "fn accent_commit"); + assert!( + crate::pages::layout::source::code_lines(factory) + .iter() + .any(|line| line.contains("Change::AccentCommit")), + "产地必须发 `Change::AccentCommit`（提交），实际函数体：\n{factory}" + ); + assert_eq!( + format!("{:?}", super::accent_commit()), + format!( + "{:?}", + crate::pages::Message::Appearance(super::Change::AccentCommit) + ), + "回车那条消息必须是 `AccentCommit`（提交），不是 `Accent(原文)`（敲字）" + ); + } + + /// 错行里的字符必须**看得见**：不可见字符写成 `U+XXXX`，可见字符原样（r1 小事 2）。 + /// + /// 抓得住：把 `visible` 改回 `ch.to_string()`——`U+00A0` / `U+200B` 那两条立刻红（错行会变成 + /// 「强调色里有非十六进制字符：」后面一片空白，用户不知道自己错在哪）。 + /// 抓不住：句子本身（词表在 `unlucky-i18n`）。 + #[test] + fn invisible_characters_are_shown_as_code_points() { + assert_eq!(visible('\u{a0}'), "U+00A0", "不换行空格看不见"); + assert_eq!(visible('\u{200b}'), "U+200B", "零宽空格看不见"); + assert_eq!(visible('\u{202e}'), "U+202E", "RTL 覆盖符看不见"); + assert_eq!(visible(' '), "U+0020", "普通空格也看不见"); + assert_eq!(visible('z'), "z", "可见字符原样"); + assert_eq!(visible('#'), "#", "ASCII 标点原样"); + assert_eq!(visible('中'), "中", "非 ASCII 可见字符原样"); + } +} diff --git a/crates/app-iced/src/pages/appearance/section/bg_image.rs b/crates/app-iced/src/pages/appearance/section/bg_image.rs new file mode 100644 index 0000000..6c71e6b --- /dev/null +++ b/crates/app-iced/src/pages/appearance/section/bg_image.rs @@ -0,0 +1,144 @@ +//! 外观分组第 ④ ⑤ ⑥ ⑦ ⑧ 段：**背景图**——开关、路径、诊断、填充档、暗化强度。 +//! +//! 这五段挤在一起是因为它们读同一份 `bg_*` 状态，而且**诊断必须紧贴控件**（复审 r1 P2-3： +//! 读盘失败 / CPU 降级 / 配色回落这些提示落在折叠线以下等于没提示）。 + +use iced::widget::column; +use iced::{Element, Length}; + +use unlucky_design::color::Role; +use unlucky_design::spacing::Space; +use unlucky_i18n::catalog::Key; +use unlucky_i18n::Lang; +use unlucky_presenter::prefs::BgFill; + +use crate::app::components::inputs::{slider, text_field, Field, Slider}; +use crate::pages::Message; +use crate::theme::Ui; + +use super::super::background::{self, BG_DIM_MAX}; +use super::super::palette; +use super::super::state::State; +use super::super::Change; +use super::{choice, choice_row, fixed2, label, note_line, slider_row, t, tr, tr_note}; + +/// 把 ④ 开关、⑤ 路径、⑥ 诊断、⑦ 填充、⑧ 暗化按视觉顺序推进 `rows`。 +pub(super) fn push<'a>( + ui: &'a Ui, + state: &'a State, + lang: Lang, + rows: &mut Vec>, +) { + // ④ 背景图开关 + rows.push(choice_row( + ui, + t(Key::SettingsAppearanceBackgroundImage, lang), + vec![ + choice( + ui, + t(Key::SettingsAppearanceOff, lang), + !state.bg_enabled, + Change::BgEnabled(false), + ), + choice( + ui, + t(Key::SettingsAppearanceOn, lang), + state.bg_enabled, + Change::BgEnabled(true), + ), + ], + )); + + // ⑤ 路径（文本框：受控，输入即生效） + let path_field: Element<'a, Message> = text_field( + ui, + Field::new(&state.bg_path) + .label(t(Key::SettingsAppearanceImagePath, lang)) + .placeholder("D:/Pictures/background.png"), + |value| Message::Appearance(Change::BgImage(value)), + ); + rows.push( + column![ + label(ui, t(Key::SettingsAppearanceImagePath, lang)), + path_field + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill) + .into(), + ); + + // ⑥ 诊断（读盘失败 / 配色回落）——**不许静默**，且必须在**首屏可见处** + // （复审 r1 P2-3：文案落在折叠线以下等于没提示）。位置就在背景图那两行的紧下方。 + // + // CPU 档的「面板/玻璃被强制」那句**不在这里**：它是张卡级状态，挂在被禁用的面板滑块旁边 + // （`panel.rs` 的 `PanelOpacityForcedHint`），一屏只出现一次（M180 复审 P2-1）。 + for note in state.diagnostics() { + let text = tr_note(lang, note); + rows.push(note_line(ui, &text, ui.color(Role::Error))); + } + if let Some(note) = state + .image() + .and_then(|image| background::small_tile_note(image, state.bg_fill)) + { + let text = tr_note(lang, ¬e); + rows.push(note_line(ui, &text, ui.color(Role::OnSurfaceVariant))); + } + if let Some(key) = state.palette_note() { + rows.push(note_line( + ui, + t(key, lang), + ui.color(Role::OnSurfaceVariant), + )); + } + // 生效的配色层级：显示的是**回落之后真正生效**的那一级（与底部「配色来源」里用户选的那一档 + // 不一定相同）。码值 → 已有的三条档位 key（不新增平行词表），所以中文界面也读得懂。 + let level = tr( + lang, + Key::SettingsAppearancePaletteLevel, + &[("level", t(palette::level_key(state.palette_level()), lang))], + ); + rows.push(note_line(ui, &level, ui.color(Role::OnSurfaceVariant))); + + // ⑦ 填充 + rows.push(choice_row( + ui, + t(Key::SettingsAppearanceBgFill, lang), + vec![ + choice( + ui, + t(Key::SettingsAppearanceBgFillCover, lang), + state.bg_fill == BgFill::Cover, + Change::BgFill(BgFill::Cover), + ), + choice( + ui, + t(Key::SettingsAppearanceBgFillContain, lang), + state.bg_fill == BgFill::Contain, + Change::BgFill(BgFill::Contain), + ), + choice( + ui, + t(Key::SettingsAppearanceBgFillTile, lang), + state.bg_fill == BgFill::Tile, + Change::BgFill(BgFill::Tile), + ), + ], + )); + + // ⑧ 暗化 + rows.push(slider_row( + ui, + t(Key::SettingsAppearanceBgDim, lang), + format!("{:.0}%", state.bg_dim * 100.0), + tr( + lang, + Key::SettingsAppearanceBgDimHint, + &[("max", &fixed2(BG_DIM_MAX))], + ), + 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))), + ), + )); +} diff --git a/crates/app-iced/src/pages/appearance/section/colour_source.rs b/crates/app-iced/src/pages/appearance/section/colour_source.rs new file mode 100644 index 0000000..8b9c85f --- /dev/null +++ b/crates/app-iced/src/pages/appearance/section/colour_source.rs @@ -0,0 +1,47 @@ +//! 外观分组第 ⑨ 段：**配色来源**（背景图 / 壁纸 / 色卡三档；它选的正是 D38 三级优先序的起点）。 + +use iced::Element; +use unlucky_i18n::catalog::Key; +use unlucky_i18n::Lang; +use unlucky_presenter::prefs::PaletteSource; + +use crate::pages::Message; +use crate::theme::Ui; + +use super::super::state::State; +use super::super::Change; +use super::{choice, choice_row, t}; + +/// 把 ⑨ 配色来源推进行 `rows`。 +pub(super) fn push<'a>( + ui: &'a Ui, + state: &'a State, + lang: Lang, + rows: &mut Vec>, +) { + // ⑨ 配色来源 + rows.push(choice_row( + ui, + t(Key::SettingsAppearancePaletteSource, lang), + vec![ + choice( + ui, + t(Key::SettingsAppearancePaletteBackground, lang), + state.palette_source == PaletteSource::BackgroundImage, + Change::PaletteSource(PaletteSource::BackgroundImage), + ), + choice( + ui, + t(Key::SettingsAppearancePaletteWallpaper, lang), + state.palette_source == PaletteSource::Wallpaper, + Change::PaletteSource(PaletteSource::Wallpaper), + ), + choice( + ui, + t(Key::SettingsAppearancePalettePreset, lang), + state.palette_source == PaletteSource::Preset, + Change::PaletteSource(PaletteSource::Preset), + ), + ], + )); +} diff --git a/crates/app-iced/src/pages/appearance/section/mod.rs b/crates/app-iced/src/pages/appearance/section/mod.rs new file mode 100644 index 0000000..391b337 --- /dev/null +++ b/crates/app-iced/src/pages/appearance/section/mod.rs @@ -0,0 +1,289 @@ +//! 设置页「外观」分组（**真控件**）+ 背景层 Element + 面板层配色。 +//! +//! ## 控件与键的对应 +//! +//! | 控件 | 键 | 改动消息 | +//! |---|---|---| +//! | 强调色文本框 + 预设色块（M250） | `appearance.accent_color` | [`Change::Accent`] | +//! | 整窗透明度滑块（下限 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`] | +//! +//! ## 文件分工（M179 `I18NSEAM`：纯搬移 + 语言接线） +//! +//! 本模块原来是一个 395 行的 `section.rs`，而全仓行数守卫是 400（`components/gate.rs`）， +//! 剩 5 行——加不了任何东西。M179 按「一段控件一个文件」切开了它： +//! +//! | 文件 | 是什么 | +//! |---|---| +//! | 本文件（`section/mod.rs`） | **壳**：[`section`] 按顺序拼各段 + [`card`] 卡片 + 行控件（[`label`] / [`slider_row`] / [`choice_row`] / [`choice`] / [`note_line`]）+ 两个取词口 [`t`] / [`tr`] | +//! | [`window`] | ① 整窗透明度 + ② 窗口圆角（含「因整窗 α 不生效」的 notice 与说明段） | +//! | [`panel`] | ③ 面板透明度（CPU 档强制 1.0，值 / 生效值分开显示） | +//! | [`bg_image`] | ④ 背景图开关 + ⑤ 路径 + ⑥ 诊断 + ⑦ 填充 + ⑧ 暗化 | +//! | [`colour_source`] | ⑨ 配色来源（三档） | +//! +//! 拆分口径：**纯搬移**——每段的语句逐字搬过去，只有下面这几处机械改写（M179 报告里用「去空白/ +//! 去尾逗号 diff」逐段证明：改完之后与原文件逐字相同，断言一条没动）： +//! +//! 1. `rows = rows.push(…)` → `rows.push(…)`（壳现在传 `&mut Vec`）； +//! 2. `t(Key::X)` → `t(Key::X, lang)`（本 mission 的语言接线）； +//! 3. `super::notice(…)` → `super::super::notice(…)`（多了一层模块）； +//! 4. 唯一一处非 `Element` 实参：`rows.push(column![…])` → 末尾加 `.into()`（`Vec::push` 不做 `Into`）； +//! 5. rustfmt 因为多出来的 `, lang` 把两处调用换成了多行。 +//! +//! ## 语言（M179 接过管子，M180 补齐文案） +//! +//! [`t`] / [`tr`] 是**唯一**两个取词口（一个拿 `&'static str`、一个拿带占位符的 owned 句子）， +//! `lang` 从 `settings::view` 的 `Language.effective` → `Group.body` → [`section`] 一路递进来。 +//! M179 只把管子接通（当时本组 27 条文案里真正本地化的只有圆角那 5 条）；M180 `I18NAPPEAR` 把 +//! 剩下 22 条字面量与 `state.rs` / `background.rs` / `palette.rs` 的运行时诊断全部搬进 +//! `catalog/settings/appearance.rs`，于是中文界面上这一页的**卡片文案**没有一句是英文。 +//! +//! 两处例外（M180 复审 L-1 记下的口径）：① 写进 `{reason}` 的**原因串**里，来自本仓库自写的 +//! 两条（`"no path configured"`、`"unknown image format …"`）与 OS / 解码库给出的文本仍是英文—— +//! 它们是不可翻译的第三方或诊断原文；② `Windows 11` / `macOS` / `Linux` / `PNG` / `JPEG` / `BMP` +//! 这些专名。除此之外这一页不出现英文。 +//! +//! ## 为什么「值」与「生效值」分开显示 +//! +//! CPU 档下面板 α 被强制 1.0（D36），而用户请求值可能是 0.5。滑块位置按**生效值**画、旁边写 +//! 「requested 0.50 → forced 1.00」，这样「为什么拖了没反应」在界面上就有答案，而不是只躺在日志里。 + +use iced::widget::{button, column, container, row}; +use iced::{ + Alignment, Background, Border, Color, Element, Length, Padding, Shadow, 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_i18n::Lang; + +use crate::pages::{frame, Message}; +use crate::theme::Ui; + +use super::state::State; +use super::Change; + +mod accent; +mod bg_image; +mod colour_source; +mod panel; +mod window; + +/// 「外观」分组整块（一张卡）。 +/// +/// `lang` 是**这一次生效的语言**：`settings::view` 的 `Language.effective`（M179）。壳把各段按 +/// **视觉顺序**拼起来；每一段的语句逐字来自拆分前的 `section()`。 +pub fn section<'a>(ui: &'a Ui, state: &'a State, lang: Lang) -> Element<'a, Message> { + let mut rows: Vec> = Vec::new(); + + // M250：强调色排在最前 —— 它是「配色可自定义」这一页最直接的入口（键一直在，控件是新的）。 + accent::push(ui, state, lang, &mut rows); + window::push(ui, state, lang, &mut rows); + panel::push(ui, state, lang, &mut rows); + bg_image::push(ui, state, lang, &mut rows); + colour_source::push(ui, state, lang, &mut rows); + + card( + ui, + column(rows) + .spacing(ui.space(Space::X1)) + .width(Length::Fill), + ) +} + +/// 外观卡片：底色走 `ui.layer`（面板 α 的唯一来源），与其它页的卡片同源。 +fn card<'a>(ui: &'a Ui, content: impl Into>) -> Element<'a, Message> { + let shape = ui.card_shape(); + 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(shape), + ..container::Style::default() + }) + .into() +} + +// --------------------------------------------------------------- 行与控件 +// +// 五个行控件由各段共用，所以留在壳里（`pub(super)` = 只给 `section/` 下的兄弟模块用）。 + +pub(super) 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` 是**这一次生效的语言**，由 [`section`] 一路递下来（M179 `I18NSEAM` 之前这里按英文目录 +/// 取词，于是中文界面上本分组的 27 条文案里真正本地化 0 条）。现在这个函数是全模块 +/// **唯一**的取词点：谁硬编码英文，就不会经过这里——M180 `I18NAPPEAR` 已把这一页剩余的 22 处 +/// 字面量与全部运行时诊断搬进词表，见 `catalog/settings/appearance.rs` 的模块文档。 +pub(super) fn t(key: Key, lang: Lang) -> &'static str { + let text = lang.catalog().text(key); + // 测试专用：把「这一帧真的取了哪条译文」记一份（iced 0.14 的 `Element` 没有可遍历控件树的 + // 公开接口，所以「渲染出来的字是不是中文」只能在取词口取证，见 `appearance::probe`）。 + #[cfg(test)] + super::probe::record(key, text); + text +} + +/// 带占位符的句子（`{name}` 替换后的 owned 版本）。 +/// +/// 为什么不直接 `lang.catalog().render(...)`：这条路径也要进 [`t`] 那份取证记录 +/// （`probe::record_rendered`），否则「中文界面下这一页每一句都不是纯 ASCII」的守卫会漏掉所有 +/// 带数字的说明句。数值参数由调用方先格式化好（词表只认 `{name}`，不认 `{:.2}`）。 +pub(super) fn tr(lang: Lang, key: Key, args: &[(&str, &str)]) -> String { + let text = lang.catalog().render(key, args); + #[cfg(test)] + super::probe::record_rendered(key, text.clone()); + text +} + +/// 两位小数（`{:.2}` 这种格式说明由 Rust 侧做，词表里只留 `{name}`）。 +pub(super) fn fixed2(value: f32) -> String { + format!("{value:.2}") +} + +/// 一条 [`Note`]（key + 已格式化的参数）按语言取整句；与 [`tr`] 共用取证口。 +pub(super) fn tr_note(lang: Lang, note: &super::background::Note) -> String { + tr(lang, note.key(), ¬e.args()) +} + +pub(super) 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) +} + +/// 一行「标签 + 值 + 滑块 + 说明」。 +pub(super) 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() +} + +/// 一行「标签 + 一排互斥按钮」。 +pub(super) fn choice_row<'a>( + ui: &'a Ui, + title: &'a str, + choices: Vec>, +) -> 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`）。 +pub(super) 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/section/panel.rs b/crates/app-iced/src/pages/appearance/section/panel.rs new file mode 100644 index 0000000..665d711 --- /dev/null +++ b/crates/app-iced/src/pages/appearance/section/panel.rs @@ -0,0 +1,62 @@ +//! 外观分组第 ③ 段：**面板透明度**滑块（下限 0.4；CPU 档强制 1.0 并禁用滑块）。 + +use iced::Element; + +use unlucky_i18n::catalog::Key; +use unlucky_i18n::Lang; + +use crate::app::components::inputs::{slider, Slider}; +use crate::pages::Message; +use crate::theme::Ui; + +use super::super::alpha::{panel_alpha_from_fraction, panel_fraction, PANEL_ALPHA_FLOOR}; +use super::super::state::State; +use super::super::Change; +use super::{fixed2, slider_row, t, tr}; + +/// 把 ③ 面板透明度推进 `rows`。 +pub(super) fn push<'a>( + ui: &'a Ui, + state: &'a State, + lang: Lang, + rows: &mut Vec>, +) { + // ③ 面板透明度（CPU 档强制 1.0） + let forced = state.panel_is_forced(); + let panel_percent = if forced { + // 数值占位：`{requested}` 是请求值（词表不认 `{:.2}`，所以在这里先格式化成两位小数）。 + tr( + lang, + Key::SettingsAppearancePanelOpacityForcedValue, + &[("requested", &fixed2(state.panel_alpha))], + ) + } else { + format!("{:.0}%", state.effective_panel_alpha() * 100.0) + }; + let panel_hint = if forced { + t(Key::SettingsAppearancePanelOpacityForcedHint, lang).to_owned() + } else { + tr( + lang, + Key::SettingsAppearancePanelOpacityHint, + &[("floor", &fixed2(PANEL_ALPHA_FLOOR))], + ) + }; + 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.push(slider_row( + ui, + t(Key::SettingsAppearancePanelOpacity, lang), + panel_percent, + panel_hint, + !forced, + panel_control, + )); +} diff --git a/crates/app-iced/src/pages/appearance/section/window.rs b/crates/app-iced/src/pages/appearance/section/window.rs new file mode 100644 index 0000000..ff2ce98 --- /dev/null +++ b/crates/app-iced/src/pages/appearance/section/window.rs @@ -0,0 +1,87 @@ +//! 外观分组第 ① ② 段：**整窗**两件——整窗透明度滑块、窗口圆角（含 notice 与说明段）。 +//! +//! 这两段是唯一**一个控件牵动另一个控件**的地方：圆角「跟随系统」时把整窗透明度调低会让圆角失效 +//! （`DwmExtendFrameIntoClientArea` 的世界里没有半透明边框），所以只有这一对放在同一个文件里—— +//! notice 的判据（`corner == System && window_opacity < 1.0`）跨这两段。 + +use iced::widget::space; +use iced::Element; + +use unlucky_design::color::Role; +use unlucky_design::spacing::Space; +use unlucky_i18n::catalog::Key; +use unlucky_i18n::Lang; +use unlucky_presenter::prefs::WindowCorner; + +use crate::app::components::inputs::{slider, Slider}; +use crate::pages::Message; +use crate::theme::Ui; + +use super::super::alpha::{window_alpha_from_fraction, window_fraction, WINDOW_ALPHA_FLOOR}; +use super::super::state::State; +use super::super::Change; +use super::{choice, choice_row, fixed2, note_line, slider_row, t, tr}; + +/// 把 ① 整窗透明度与 ② 窗口圆角按视觉顺序推进 `rows`。 +pub(super) fn push<'a>( + ui: &'a Ui, + state: &'a State, + lang: Lang, + rows: &mut Vec>, +) { + // ① 整窗透明度 + let window_percent = format!("{:.0}%", state.window_opacity * 100.0); + rows.push(slider_row( + ui, + t(Key::SettingsAppearanceWindowOpacity, lang), + window_percent, + tr( + lang, + Key::SettingsAppearanceWindowOpacityHint, + &[("floor", &fixed2(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.push(choice_row( + ui, + t(Key::SettingsAppearanceCorner, lang), + vec![ + choice( + ui, + t(Key::SettingsAppearanceCornerSystem, lang), + corner == WindowCorner::System, + Change::Corner(WindowCorner::System), + ), + choice( + ui, + t(Key::SettingsAppearanceCornerSquare, lang), + 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.push(super::super::notice( + ui, + t(Key::SettingsAppearanceCornerSuspended, lang), + )); + let gap: Element<'a, Message> = space::vertical().height(ui.space(Space::X1)).into(); + rows.push(gap); + } + let tone = ui.color(Role::OnSurfaceVariant); + rows.push(note_line( + ui, + t(Key::SettingsAppearanceCornerHint, lang), + tone, + )); +} 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..2ceebef --- /dev/null +++ b/crates/app-iced/src/pages/appearance/state.rs @@ -0,0 +1,398 @@ +//! 外观的**运行期状态**：配置值 → 生效值（钳位 / 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_i18n::catalog::Key; +use unlucky_presenter::prefs::{ + AppearanceBase, AppearancePrefs, BgFill, PaletteSource, WindowCorner, +}; + +use crate::Backend; + +use super::accent::Accent; +use super::alpha::{self, effective_glass, effective_panel_alpha, panel_is_forced_opaque}; +use super::background::{self, Image, Note}; +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, + /// 自定义强调色（M250 ACCENTWIRE：输入原文 / 解析结果 / 生效方案 / 结构化错误都在里面）。 + pub accent: Accent, + /// 窗口圆角策略（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, + /// 读盘/解码失败的**可读诊断**（按发生顺序追加；`Note` = key + 参数，句子在词表里）。 + diagnostics: Vec, + /// 上一次的配色解析结果。 + resolved: Option, + /// 当前深浅（配色解析的输入）。 + 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, + accent: Accent::new(&prefs.accent_color), + 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()); + } + // 强调色的两档开关（`ULL_APPEARANCE_ACCENT` / `…_COMMIT`）收在 `accent` 自己的模块里： + // 本文件贴 400 行硬线，而那两个开关与 `Accent` 的状态机是一件事（见 `Accent::apply_env`）。 + self.accent.apply_env(); + 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 { + 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) + } + + /// 读盘/解码失败的诊断（设置页逐条显示；一条 = 一条 key + 它的参数）。 + #[must_use] + pub fn diagnostics(&self) -> &[Note] { + &self.diagnostics + } + + /// 配色来源的提示 key（`None` = 一级成功）。 + #[must_use] + pub fn palette_note(&self) -> Option { + 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; + // M250 p2-3 / P18：除「敲字」（`Accent`）以外都意味着这一格定下来了 ⇒ 提交；回车 `AccentCommit` 同路。 + if !matches!(change, Change::Accent(_)) { + self.accent.commit(); + } + 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::Accent(text) => { + self.accent.set(&text); + false + } + Change::AccentCommit => false, // P18 回车：语义就是「提交」，上面那条规则已 `commit()` + Change::SelectGroup(index) => { + self.selected_group = index; + false + } + } + } + + /// 写回配置用的快照（`SettingsBridge::persist` 覆盖的那 9 个字段）。 + /// + /// M250 起 `accent_color` 也在里面（以前恒给空串 ⇒ 设置页改的强调色落不了盘），给的是**上一次合法值**。 + #[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: self.accent.persist_value().to_owned(), + } + } + + /// 取证日志（**一行**，数值而不是观感）：`[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={} accent={} 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.accent.log_token(), + 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; + // M250：文件被外部改过（CLI / AI）时强调色也要热生效，错行同样重置。 + self.accent.reset(&prefs.accent_color); + 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.note()), + } + } + + 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 { + std::env::var(key) + .ok() + .and_then(|value| value.trim().parse::().ok()) + .filter(|value| value.is_finite()) +} diff --git a/crates/app-iced/src/pages/appearance/tests.rs b/crates/app-iced/src/pages/appearance/tests.rs new file mode 100644 index 0000000..22e4603 --- /dev/null +++ b/crates/app-iced/src/pages/appearance/tests.rs @@ -0,0 +1,287 @@ +//! `pages::appearance` 的单测：`Change` 的落盘映射（M93）+ **中文界面文案的取证守卫**（M180）。 +//! +//! 为什么是独立文件：`mod.rs` 已经 220 行上下，而 M180 要在模块里加三条取证用例。搬移口径与 +//! `background/tests.rs` 一致——既有两条用例**一字未动**，只是从 `mod.rs` 的行内 `mod tests` 挪到这里。 +//! +//! ## M180 的两条取证守卫，它们「抓得住什么」 +//! +//! iced 0.14 没有可遍历控件树的公开接口（见 [`super::probe`] 的模块文档），所以取证点只能是 +//! 取词口 `section::t` / `section::tr`。于是这一对守卫分工如下： +//! +//! | 守卫 | 抓得住 | 抓不住 | +//! |---|---|---| +//! | [`the_appearance_card_speaks_chinese`] | 中文界面下取到的每一条文案都是纯 ASCII（= 有人把某条 key 的英文写回中文表 / 中文表里放英文原句） | 硬编码字面量（它压根不过取词口） | +//! | [`every_appearance_card_key_is_drawn`] | 某一处控件被改回**写死英文**：那条 key 不再被取，集合里就少一个元素 | 新加一条字面量（新 key 还没有，集合不看它） | +//! +//! 两条合起来才等于「中文界面下外观卡片里不再出现英文字面量」——单看任一条都有一个真会发生的 +//! 漏网口，所以这里刻意写两条。 + +use super::{Change, APPEARANCE_GROUP}; +use unlucky_i18n::catalog::Key; +use unlucky_i18n::Lang; +use unlucky_presenter::prefs::{keys, BgFill, PaletteSource}; + +mod accent; + +/// 抓得住：每条改动都点名到自己那个 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); + // P18：回车提交不产生值，但它是强调色那一格的改动（`on_appearance` 据此再写一次上一次合法值） + assert_eq!( + Change::AccentCommit.key(), + Some(keys::ACCENT_COLOR), + "回车提交也要点名到自己那个 schema 键" + ); + assert_eq!( + Change::AccentCommit.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")); +} + +// --------------------------------------------------------------- 文案（M180 I18NAPPEAR） + +/// 画一帧外观卡片，取走这一帧从词表取到的**全部**字：`(key, 文案)`。 +/// +/// 三档状态各画一帧： +/// - [`Case::Factory`]：auto 档、没设背景图——覆盖常驻的标签 / 选项 / 说明； +/// - [`Case::Cpu`]：CPU 档——覆盖「强制 100%」那一行与软件渲染说明（这两条只在降级态出现）； +/// - [`Case::Dim`]：整窗 α 调低——覆盖「圆角暂时不生效」那条 notice。 +/// +/// 两条取词路径都要收：`t()` 的 `&'static str` 与 `tr()` 替换完占位符的整句（后者不进前者的记录）。 +fn appearance_texts(lang: Lang, case: Case) -> Vec<(Key, String)> { + use unlucky_design::color::SchemeFlavor; + use unlucky_presenter::prefs::{AppearanceBase, AppearancePrefs}; + + use super::probe; + use crate::cli::Backend; + use crate::theme::{Families, Ui}; + + const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", + }; + + let (backend, alpha) = match case { + Case::Factory | Case::BadAccent => (Backend::Auto, 1.0), + Case::Cpu => (Backend::Cpu, 1.0), + Case::Dim => (Backend::Gpu, 0.5), + }; + let mut state = super::State::new( + &AppearancePrefs::factory(), + &AppearanceBase::factory(), + backend, + SchemeFlavor::Light, + ); + if alpha < 1.0 { + state.apply(Change::WindowOpacity(alpha)); + } + if matches!(case, Case::BadAccent) { + // M250：错行只在失败态出现，所以「三档状态合起来覆盖本页全部 key」需要这一档。 + state.apply(Change::Accent("zzzzzz".to_owned())); + } + + let ui = Ui::new(SchemeFlavor::Light, FAMILIES); + // 前面几条用例可能留了记录：本线程的取证每次都从清空开始。 + probe::take(); + probe::take_rendered(); + + let _tree = super::section(&ui, &state, lang); + + let mut texts: Vec<(Key, String)> = probe::take() + .into_iter() + .map(|(key, text)| (key, text.to_owned())) + .collect(); + texts.extend(probe::take_rendered()); + + // 复审 L-2：`{name}` 换完还留着花括号 ⇒ 某处参数名与模板不一致（`("floor", …)` 写成 + // `("flor", …)` 时句子会原样显示「下限 {floor}」，而「整句非 ASCII」的守卫看不出来）。 + // 三档状态合起来覆盖本页全部 `tr()` 调用，所以这条断言是全覆盖的。 + for (key, text) in &texts { + assert!( + !text.contains('{'), + "{case:?}：{} 渲染后还留着占位符「{text}」——`tr()` 的参数名与模板对不上", + key.name() + ); + } + texts +} + +/// 画哪一档状态。 +#[derive(Debug, Clone, Copy)] +enum Case { + /// 工厂态（GPU / auto）。 + Factory, + /// CPU 降级态（面板 α 与玻璃被强制）。 + Cpu, + /// 整窗 α 调低（圆角暂时不生效）。 + Dim, + /// 强调色填了非法值（M250：错行 + 输入框失败态）。 + BadAccent, +} + +/// 这一页**常驻**的 key（三档状态合起来必须一个不缺地取到）。 +/// +/// 为什么是手写清单而不是「`Key::ALL` 里所有 `SettingsAppearance*`」：诊断一族（读盘失败 / 配色回落 / +/// 小图平铺）取决于运行时状态，单测里要让它们出现得造磁盘上的坏图；那些由 +/// `background/tests.rs` 与 `palette.rs` 的单测按 key 逐条钉（见各自的用例注释）。 +const CARD_KEYS: &[Key] = &[ + Key::SettingsAppearanceAccent, + Key::SettingsAppearanceAccentPresets, + Key::SettingsAppearanceAccentFactory, + Key::SettingsAppearanceAccentHint, + Key::SettingsAppearanceAccentDigit, + Key::SettingsAppearanceCorner, + Key::SettingsAppearanceCornerSystem, + Key::SettingsAppearanceCornerSquare, + Key::SettingsAppearanceCornerHint, + Key::SettingsAppearanceCornerSuspended, + Key::SettingsAppearanceWindowOpacity, + Key::SettingsAppearanceWindowOpacityHint, + Key::SettingsAppearancePanelOpacity, + Key::SettingsAppearancePanelOpacityHint, + Key::SettingsAppearancePanelOpacityForcedValue, + Key::SettingsAppearancePanelOpacityForcedHint, + Key::SettingsAppearanceBackgroundImage, + Key::SettingsAppearanceOff, + Key::SettingsAppearanceOn, + Key::SettingsAppearanceImagePath, + Key::SettingsAppearancePaletteLevel, + Key::SettingsAppearanceBgFill, + Key::SettingsAppearanceBgFillCover, + Key::SettingsAppearanceBgFillContain, + Key::SettingsAppearanceBgFillTile, + Key::SettingsAppearanceBgDim, + Key::SettingsAppearanceBgDimHint, + Key::SettingsAppearancePaletteSource, + Key::SettingsAppearancePaletteBackground, + Key::SettingsAppearancePaletteWallpaper, + Key::SettingsAppearancePalettePreset, +]; + +/// **M180 守门 ①**：中文界面下，外观卡片里取到的每一条文案都不是纯 ASCII。 +/// +/// 抓得住：某条 key 的中文译文被换成英文原句（中文表里出现纯 ASCII 的一句）；中文译文写成 +/// `PNG` / `Preset` 这种专名；`tr()` 那条路径把数字拼进英文模板（比如 `Colours: preset`）。 +/// 抓不住：硬编码字面量——它不过取词口，由 [`every_appearance_card_key_is_drawn`] 与 +/// `catalog/settings/appearance.rs` 的译文守卫合力守。 +/// +/// 变异证明：把 `SettingsAppearanceOff` 的中文改成 `"Off"` ⇒ 本条立刻红。 +#[test] +fn the_appearance_card_speaks_chinese() { + // 白名单：技术专名允许是纯 ASCII（现在一条都没有——`%` / 数字不在文案里，它们是参数）。 + const ASCII_OK: &[&str] = &[]; + + for case in [Case::Factory, Case::Cpu, Case::Dim, Case::BadAccent] { + let pairs = appearance_texts(Lang::ZhCn, case); + assert!( + pairs.len() >= 20, + "{case:?}：取词口只记到 {} 条文案，渲染路径没走到底（语言管子断了？）", + pairs.len() + ); + for (key, text) in &pairs { + if ASCII_OK.contains(&text.as_str()) { + continue; + } + assert!( + !text.is_ascii(), + "{case:?}：中文界面下外观卡片里出现了纯 ASCII 的文案「{text}」（{}）\ + ——写死英文，或中文表里放了英文原句", + key.name() + ); + } + } +} + +/// **M180 守门 ②（漏项）**：这一页每一处控件都必须从词表取词。 +/// +/// 抓得住：把某处 `t(Key::X, lang)` / `tr(lang, Key::X, …)` 改回写死的英文字面量——那条 key 不再 +/// 出现在取词记录里，集合比较当场红（这正是 M172 口径「22 处硬编码」的复发形态）。 +/// 抓不住：新加一条写死英文（它没有 key，也就没有「少了哪条」）。 +/// +/// 变异证明：把 `bg_image.rs` 里 `t(Key::SettingsAppearanceOff, lang)` 换回 `"Off"` ⇒ 本条红。 +#[test] +fn every_appearance_card_key_is_drawn() { + let mut seen: Vec = Vec::new(); + for case in [Case::Factory, Case::Cpu, Case::Dim, Case::BadAccent] { + seen.extend( + appearance_texts(Lang::ZhCn, case) + .into_iter() + .map(|(key, _)| key), + ); + } + + let missing: Vec<&str> = CARD_KEYS + .iter() + .filter(|key| !seen.contains(key)) + .map(|key| key.name()) + .collect(); + assert!( + missing.is_empty(), + "这些 key 一帧都没取到（控件被改回写死英文，或整段没画）：{missing:?}" + ); +} + +/// 英文界面下不许出现汉字（否则「含汉字」可能来自写死的中文，而不是词表）。 +#[test] +fn the_appearance_card_keeps_its_english_baseline() { + for case in [Case::Factory, Case::Cpu, Case::Dim, Case::BadAccent] { + let texts = appearance_texts(Lang::En, case); + let with_han: Vec<&(Key, String)> = texts + .iter() + .filter(|(_, text)| text.chars().any(is_han)) + .collect(); + assert!( + with_han.is_empty(), + "{case:?}：英文界面下外观卡片出现了汉字：{with_han:?}" + ); + } +} + +/// 有没有汉字（与 `pages/settings/tests/appearance_section.rs` 的 `is_han` 同一段码位）。 +fn is_han(ch: char) -> bool { + ('\u{4e00}'..='\u{9fff}').contains(&ch) +} diff --git a/crates/app-iced/src/pages/appearance/tests/accent.rs b/crates/app-iced/src/pages/appearance/tests/accent.rs new file mode 100644 index 0000000..75ea2aa --- /dev/null +++ b/crates/app-iced/src/pages/appearance/tests/accent.rs @@ -0,0 +1,321 @@ +//! 强调色接线的两条判据（M250 ACCENTWIRE）：判据一「两套配置下同一组件色值不同」、 +//! 判据二「非法值拿到结构化原因且不静默回退」。 +//! +//! 为什么从 `tests.rs` 再拆一层：这两条用例加起来 150 行，`tests.rs` 会越过 400 行硬线 +//! （M180 把它从 `mod.rs` 拆出来就是为了这个）。判据本身与写进 `tests.rs` 的版本逐字一致， +//! 只是换了落点。 + +use super::Change; + +/// 青绿（`00 6A 5C`）由 design 的 `Color` 拼出来：本 crate 的 `src/**` 不许出现十六进制色值 +/// 字面量（`tests/no_hardcoded_tokens.rs` 把测试文件也扫在内——那条门禁是对的，色值只能来自令牌）。 +const TEAL: unlucky_design::color::Color = unlucky_design::color::Color::rgb(0x00, 0x6A, 0x5C); + +/// 判据一：`accent_color` 为空 与 为青绿（见 [`TEAL`]）时，**同一组件取到的 primary 类角色色值必须不同**。 +/// +/// 取色点是 `progress::linear_colors`（进度条指示条 = `Role::Primary`，实心按钮的容器也是它）： +/// 断言的是**取到的值**，不是「没 panic」——把接线改回「恒走出厂板」，两边相等当场红。 +/// +/// 抓得住：① 接线不存在（两套 Ui 同色）；② 只改了 `Primary` 而漏掉 secondary/tertiary； +/// ③ 有人把 `Scheme::from_accent` 的中性基准换掉（下面那条 `assert_eq` 会红）。 +/// 抓不住：像素（样式闭包被别处覆盖）——那是出图与 `components/**` 的 probe 用例的事。 +#[test] +fn custom_accent_changes_the_component_colours_it_reaches() { + use crate::app::components::feedback::progress; + use crate::cli::Backend; + use crate::theme::{Families, Ui}; + use unlucky_design::color::{Role, Scheme, SchemeFlavor}; + use unlucky_presenter::prefs::{AppearanceBase, AppearancePrefs}; + + use super::super::State; + + const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", + }; + + let mut state = State::new( + &AppearancePrefs::factory(), + &AppearanceBase::factory(), + Backend::Gpu, + SchemeFlavor::Light, + ); + // 空配置 = 出厂板（`rebuild_ui` 的 `(None, None)` 分支同一条路） + assert!( + state.accent.color().is_none(), + "空串是「用出厂板」，不该被解析成自定义色" + ); + let factory = Ui::new(SchemeFlavor::Light, FAMILIES); + + // 填青绿 = `rebuild_ui` 的 `(Some(accent), _)` 分支 + state.apply(Change::Accent(TEAL.to_hex())); + assert_eq!(state.accent.error(), None, "合法 hex 不该报错"); + let accent = state.accent.color().expect("合法 hex 必须解析成颜色"); + let custom = Ui::with_accent(SchemeFlavor::Light, accent, FAMILIES); + + let (_, factory_primary) = progress::linear_colors(&factory); + let (_, custom_primary) = progress::linear_colors(&custom); + assert_eq!(factory_primary, factory.color(Role::Primary)); + assert_eq!(custom_primary, custom.color(Role::Primary)); + assert_ne!( + factory_primary, custom_primary, + "同一组件的 primary 类角色在两套配置下同色 ⇒ 强调色没接线" + ); + + // 强调族逐条跟着变（不只 primary）。 + // + // `OnPrimary` 刻意**不在**清单里：深浅两套方案的 on-primary 都是 tone 100/20 的白/深色， + // 强调色只换色相，这一格在两套方案下同为纯白——令牌表里两格同值是合法的，钉它会假红。 + // 「强调族真的换了色相」由下面三个色相承载角色负责：Primary / PrimaryContainer / Tertiary。 + let baseline = Ui::from_scheme(Scheme::baseline(SchemeFlavor::Light), FAMILIES); + for role in [ + Role::Primary, + Role::PrimaryContainer, + Role::Secondary, + Role::Tertiary, + ] { + assert_ne!( + custom.color(role), + baseline.color(role), + "{role:?} 没跟着强调色走" + ); + } + // **中性表面与 error 保持基线**：`Scheme::from_accent` 的既定语义（design 侧登记，不是没接线） + for role in [ + Role::Surface, + Role::SurfaceContainerHighest, + Role::OnSurface, + Role::Outline, + Role::Error, + Role::OnError, + ] { + assert_eq!( + custom.color(role), + baseline.color(role), + "{role:?} 被强调色染了：`Scheme::from_accent` 只换 primary/secondary/tertiary 三族" + ); + } +} + +/// 判据二：非法值必须拿到**结构化的原因**，生效色不回退、不写盘，tokens 仍可构造（不崩）。 +/// +/// 抓得住：把非法分支改成「静默回退出厂色」——`color()` 会变成 `None`、`persist_value()` 会变成 +/// 空串，三条断言当场红；把错误吞成 `bool`——`error()` 不再是 `Some(..)`，也红。 +/// 抓不住：错行在屏幕上到底画没画出来（`every_appearance_card_key_is_drawn` 的 `BadAccent` 档 +/// 证明取词口被走到；像素由出图负责）。 +#[test] +fn illegal_accent_reports_a_reason_and_never_silently_falls_back() { + use crate::cli::Backend; + use crate::theme::{Families, Ui}; + use unlucky_design::color::{Role, SchemeFlavor}; + use unlucky_presenter::prefs::{AccentError, AppearanceBase, AppearancePrefs}; + + use super::super::State; + + const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", + }; + + let mut state = State::new( + &AppearancePrefs::factory(), + &AppearanceBase::factory(), + Backend::Gpu, + SchemeFlavor::Light, + ); + state.apply(Change::Accent(TEAL.to_hex())); + let good = state.accent.color().expect("先放一个合法值"); + let good_primary = Ui::with_accent(SchemeFlavor::Light, good, FAMILIES).color(Role::Primary); + + // 超长串由合法值拼出来：`src/**` 的色值字面量门禁把注释与测试也算在内（那条门禁是对的）。 + // + // 三档里只有后两档**当场**亮：`#12` 是「还可能是合法前缀」（用户可能正打到一半），它的 + // 亮灯时机由 `accent_errors_only_appear_when_they_are_actionable` 与 `commit` 覆盖。 + let long = format!("{}00112233", TEAL.to_hex()); + for (text, expected) in [ + ("zzzzzz".to_owned(), AccentError::Digit { ch: 'z' }), + (long, AccentError::Long { digits: 14 }), + ] { + state.apply(Change::Accent(text.clone())); + assert_eq!( + state.accent.error(), + Some(expected), + "{text}: 不可能变合法的输入必须当场亮且原因结构化（不是一句 bool / 一句「格式不对」）" + ); + assert_eq!( + state.accent.color(), + Some(good), + "{text}: 静默回退出厂色了（非法输入不该改生效色）" + ); + assert_eq!( + state.accent.persist_value(), + TEAL.to_hex(), + "{text}: 非法值写进配置了" + ); + // tokens 仍可构造，取到的还是上一次合法色 + let ui = Ui::with_accent(SchemeFlavor::Light, state.accent.color().unwrap(), FAMILIES); + assert_eq!(ui.color(Role::Primary), good_primary); + } + + // `#12`：输入中不亮，**提交**后必须亮（否则「非法值可见」会在短输入上落空） + state.apply(Change::Accent("#12".to_owned())); + assert_eq!(state.accent.error(), None, "#12: 输入中先不亮"); + state.accent.commit(); + assert_eq!( + state.accent.error(), + Some(AccentError::Short { digits: 2 }), + "#12: 提交后必须亮且原因正确" + ); + assert_eq!(state.accent.color(), Some(good), "#12: 提交也不许改生效色"); + + // 空串是**合法**的「回出厂板」，不是错误 + state.apply(Change::Accent(String::new())); + assert_eq!(state.accent.error(), None, "空串不是错误"); + assert!(state.accent.color().is_none(), "空串 = 出厂板"); + assert_eq!(state.accent.persist_value(), ""); + + // 小写、缺 `#` 都吃得下；落盘一律规范化成大写的 `#RRGGBB` + state.apply(Change::Accent(TEAL.to_hex().to_lowercase())); + assert_eq!(state.accent.persist_value(), TEAL.to_hex()); + state.apply(Change::Accent( + TEAL.to_hex().trim_start_matches('#').to_owned(), + )); + assert_eq!(state.accent.persist_value(), TEAL.to_hex()); +} + +/// **p2-3**：错行与 `Field::error()` 的出现时机 —— 只在「提交」或「不可能再变合法」时。 +/// +/// 抓得住：把 `Accent::retry` 的延后逻辑删掉（所有错都立刻亮）⇒ 第一段当场红（手打青绿 +/// 的每一个前缀都会亮）；把 `commit` 改成空实现 ⇒ 第二段红（提交后不亮，等于「非法值不可见」）； +/// 把配置读回也走延后 ⇒ 第三段红。 +/// 抓不住：像素（红框与红字到底画没画）——那是出图与 `every_appearance_card_key_is_drawn` 的事。 +#[test] +fn accent_errors_only_appear_when_they_are_actionable() { + use crate::cli::Backend; + use unlucky_design::color::SchemeFlavor; + use unlucky_presenter::prefs::{AccentError, AppearanceBase, AppearancePrefs}; + + use super::super::State; + + let factory = AppearancePrefs::factory(); + let mut state = State::new( + &factory, + &AppearanceBase::factory(), + Backend::Gpu, + SchemeFlavor::Light, + ); + + // ① 手打青绿的过程：每个**合法前缀**都不许亮红（否则一次输入闪 5 次） + for prefix in ["#", "#0", "#00", "#006", "#006A", "#006A5"] { + state.apply(Change::Accent(prefix.to_owned())); + assert_eq!( + state.accent.error(), + None, + "{prefix:?}: 还没打完就亮红了（手打一个合法色会闪好几次）" + ); + assert!( + state.accent.color().is_none(), + "{prefix:?}: 没打完的输入不该生效" + ); + } + state.apply(Change::Accent(TEAL.to_hex())); + assert_eq!(state.accent.error(), None); + assert!(state.accent.color().is_some(), "打完了就该生效"); + + // ② 输入中留着不打完 ⇒ 不亮；**提交**（点到别的外观控件）⇒ 亮且原因正确 + state.apply(Change::Accent("#12".to_owned())); + assert_eq!(state.accent.error(), None, "输入中先不亮"); + state.apply(Change::PanelAlpha(0.8)); + assert_eq!( + state.accent.error(), + Some(AccentError::Short { digits: 2 }), + "离开这一格之后必须亮，否则非法值就不可见了" + ); + + // ③ 配置读回（`Accent::new`）⇒ **当场**亮，不等用户来点 + let bad = AppearancePrefs { + accent_color: "#12".to_owned(), + ..AppearancePrefs::factory() + }; + let loaded = State::new( + &bad, + &AppearanceBase::factory(), + Backend::Gpu, + SchemeFlavor::Light, + ); + assert_eq!( + loaded.accent.error(), + Some(AccentError::Short { digits: 2 }), + "配置文件里的坏值必须当场可见" + ); + assert!(loaded.accent.color().is_none(), "坏值不生效，走出厂板"); +} + +/// **P18 / M252 判据 ③**：回车 = 立即提交（`Change::AccentCommit`）。 +/// +/// 抓得住：① 把回车实现成「再走一次 `Accent(原文)`」——`retry(false)` 会把已经亮起来的错**吞回去**， +/// 第一段当场红；② 把 `State::apply` 开头那条「非敲字即提交」的规则删掉（回车不再提交）， +/// 第一段同样红；③ 回车把非法值写进配置（`persist_value` 变了），第二、三段红。 +/// 抓不住：真按下回车（iced 的键路径，见 `section/accent.rs` 的接线用例），也抓不住写盘那一下 +/// （`SettingsBridge::persist` 在 `app` 侧）——这里钉的是 `current_values().accent_color`， +/// 也就是**要写出去的那个值**。 +#[test] +fn enter_commits_a_half_typed_value_and_persists_only_legal_ones() { + use crate::cli::Backend; + use unlucky_design::color::SchemeFlavor; + use unlucky_presenter::prefs::{AccentError, AppearanceBase, AppearancePrefs}; + + use super::super::State; + + let mut state = State::new( + &AppearancePrefs::factory(), + &AppearanceBase::factory(), + Backend::Gpu, + SchemeFlavor::Light, + ); + + // ① 打了一半就放着：输入中**不**亮（逐键报错的规矩不许被回车改回来）…… + state.apply(Change::Accent("#12".to_owned())); + assert_eq!( + state.accent.error(), + None, + "输入中先不亮（手打一个合法色不该闪好几次）" + ); + // ……但回车必须亮，而且**不写盘**（落盘仍是上一次合法值 = 空串 = 出厂板） + state.apply(Change::AccentCommit); + assert_eq!( + state.accent.error(), + Some(AccentError::Short { digits: 2 }), + "回车之后 #12 必须亮红（打了一半放着也能被用户主动确认）" + ); + assert_eq!( + state.accent.persist_value(), + "", + "#12: 回车不许把非法值写盘" + ); + assert!(state.accent.color().is_none(), "#12: 也不许改生效色"); + assert_eq!( + state.current_values().accent_color, + "", + "写回配置的值仍是上一次合法值" + ); + + // ② 合法值回车：不报错、生效、写盘值就是规范化 hex + state.apply(Change::Accent(TEAL.to_hex().to_lowercase())); + state.apply(Change::AccentCommit); + assert_eq!(state.accent.error(), None, "合法值回车不该冒出错误"); + assert!(state.accent.color().is_some(), "合法值回车后仍生效"); + assert_eq!( + state.current_values().accent_color, + TEAL.to_hex(), + "合法值回车后写回配置的是规范化 hex" + ); + + // ③ 幂等：同一个值连按两次回车不出错、不改值 + state.apply(Change::AccentCommit); + state.apply(Change::AccentCommit); + assert_eq!(state.accent.error(), None); + assert_eq!(state.current_values().accent_color, TEAL.to_hex()); +} diff --git a/crates/app-iced/src/pages/content.rs b/crates/app-iced/src/pages/content.rs new file mode 100644 index 0000000..2a9b1bc --- /dev/null +++ b/crates/app-iced/src/pages/content.rs @@ -0,0 +1,117 @@ +//! # 内容库页（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 补依赖后换成字节级 | +//! +//! ## 安装失败之后：两档分组 + 「只重试这些」（M191） +//! +//! 装入失败且**有可重试项**时，页底那块失败面板换成 [`parts::retry_panel`]：按 +//! `InstallFailureKind` 分两段（不兼容 / 取不到，各有自己的词表文案），并给一个「只重试这 N 个」 +//! 的实心按钮。按钮发 [`Message::RetryFailed`]，app 层翻成 `AppCommand::InstallContent{retry: true}`， +//! host 拿上一轮的计划调 `DependencyPlan::retry_request()` ⇒ **只请求失败的那几个项目**。 +//! +//! 判据只有一条且在模型里（`RetryPanel::of`）：`stage == Failed && !retry.is_empty()`。 +//! 全成功、没有失败项、还在跑，三种情况都得到 `None`——**不渲染**，不是画一个灰按钮。 + +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, RetryGroup, RetryPanel, + 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, + window_height: f32, +) -> Element<'a, PageMessage> { + view::view(ui, metrics, model, lang, window_height) +} + +/// 演示数据（`pages_demo` 出图与单测用；产品路径走 `Content::from_snapshot`）。 +pub fn demo(kind: ContentKind, lang: Lang) -> Content { + demo::demo(kind, lang) +} + +/// 页头那条一级切换（版本管理页也要用同一个函数：两页共用一个入口才不会各画一套）。 +/// +/// `on_content` 是**调用方自己**的位置：内容库页传 `true`、版本管理页传 `false`。 +/// M229 复审 F3 之前这里写死 `true`，于是下载页页头的「内容库」也画成选中态（选中态反了）。 +pub(crate) fn section_switcher<'a>( + ui: &'a Ui, + catalog: unlucky_i18n::Catalog, + on_content: bool, +) -> Element<'a, PageMessage> { + parts::section_switcher(ui, catalog, on_content) +} 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..60023f4 --- /dev/null +++ b/crates/app-iced/src/pages/content/demo.rs @@ -0,0 +1,345 @@ +//! 内容库的演示数据（`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` / `install` / `cf` / `offline` / `retryfail` / `retryok` | 选状态（默认 `ok`；`offline` = M162 的未联网态；`retryfail` = M191 的「有失败项」，`retryok` = M191 的「全部成功」） | +//! +//! 只影响本来就用演示数据的 harness 路径；产品二进制里 `demo()` 根本不会被调用。 + +use unlucky_i18n::{Catalog, Key, Lang}; +use unlucky_presenter::dto::{ContentHit, ContentKind, ContentSort, ContentSource, LoaderKind}; + +use super::model::{ + blockers_of, Content, ContentQueryView, Hit, HitFacts, RetryPanel, Status, Target, VersionRow, +}; +use crate::pages::download::Download; + +/// M191「有失败项」那一屏：两档各几个项目，面板按档分组。 +/// +/// **走真判据**（[`RetryPanel::of`]），不手搓面板字段：出图与产品路径读同一个函数， +/// 判据一改这条演示就跟着变（否则演示图能一直画着一个已经不存在的面板）。 +fn retry_failure(instance: &str, catalog: Catalog) -> Option { + use unlucky_presenter::dto::{ + InstallFailureKind, InstallFailureView, InstallProgressView, InstallStage, + }; + let mut progress = InstallProgressView { + version: "Sodium".to_string(), + instance: instance.to_string(), + loader: "Fabric".to_string(), + stage: InstallStage::Failed, + files_done: 1, + files_total: 4, + ..InstallProgressView::new() + }; + // 三种可显示性各一条，与 host 侧 `plan::label_of` 的三种情况同形： + // 根项目 = 请求里的标题、下载失败 = 文件名、不兼容档 = 失败路径上现取的项目名。 + progress.retry = vec![ + InstallFailureView::new( + "AANobbMI", + "Sodium", + InstallFailureKind::Unreachable, + "下载 sodium-fabric-0.6.0.jar 失败（online_not_connected）：连不上 cdn.modrinth.com", + ), + InstallFailureView::new( + "P7dR8mSH", + "Entity Culling", + InstallFailureKind::Incompatible, + "没有匹配所选游戏版本/加载器（1.20.1 / fabric）的版本", + ), + InstallFailureView::new( + "1eAoo2KR", + "fabric-api-0.92.2+1.20.1.jar", + InstallFailureKind::Unreachable, + "下载 fabric-api-0.92.2+1.20.1.jar 失败（online_not_connected）：连不上 cdn.modrinth.com", + ), + ]; + RetryPanel::of(&progress, catalog) +} + +/// 一个固定的演示环境：两个实例（一个 Fabric / 一个 Forge）。 +fn targets() -> Vec { + 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 { + 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"; + // M162：「未联网」那一屏（与空态分开画） + let offline = state == "offline"; + // M162：详情通道的版本列表（真实路径来自 presenter 的 `ContentDetail`） + let demo_versions = if empty || offline { + Vec::new() + } else { + vec![ + VersionRow { + number: "mc1.20.1-0.5.11".to_string(), + kind: "release".to_string(), + file_name: Some("sodium-fabric-0.5.11.jar".to_string()), + line: catalog.render( + Key::ContentDetailVersionLine, + &[ + ("number", "mc1.20.1-0.5.11"), + ("kind", "Release"), + ("date", "2025-06-01"), + ], + ), + }, + VersionRow { + number: "mc1.20.1-0.5.10".to_string(), + kind: "beta".to_string(), + file_name: Some("sodium-fabric-0.5.10.jar".to_string()), + line: catalog.render( + Key::ContentDetailVersionLine, + &[ + ("number", "mc1.20.1-0.5.10"), + ("kind", "Beta"), + ("date", "2025-05-20"), + ], + ), + }, + ] + }; + // 「装入中」那一屏：面板就是下载页那块（同一个函数），用来证明它在内容库语义下也可读 + let installing = state == "install"; + // 空态与未联网态都**没有命中项**：离线时画出列表就是自相矛盾（列表本身就来自网络） + let list = if empty || offline { + 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 offline { + Status::Offline("connect timed out after 10s".to_string()) + } else 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 + }, + // M191：`retryfail` 画「有失败项」，`retryok` 画「全部成功」——后者走同一条判据， + // 得到 `None`（连按钮都不渲染）。 + retry: match state.as_str() { + "retryfail" => retry_failure("survival", catalog), + _ => None, + }, + versions: vec!["1.20.1".to_string(), "1.21.1".to_string()], + available_versions: demo_versions, + versions_note: None, + draft: if empty { + "quarkonium".to_string() + } else { + String::new() + }, + pack, + } +} + +#[cfg(test)] +mod tests { + use super::*; + + /// 「有失败项」那一屏的两档走**真判据**（`RetryPanel::of`），不是手搓的面板字段。 + #[test] + fn the_failure_screen_shows_both_tiers() { + let panel = retry_failure("survival", Lang::En.catalog()).expect("演示必须有面板"); + assert_eq!(panel.total, 3); + assert!(panel.has_both_tiers(), "{:?}", panel.groups); + assert_eq!( + panel.items_of(unlucky_presenter::dto::InstallFailureKind::Unreachable), + Some( + [ + // 根项目：名字来自请求标题 + "Sodium (AANobbMI)".to_string(), + // 下载失败：名字来自文件名 + "fabric-api-0.92.2+1.20.1.jar (1eAoo2KR)".to_string(), + ] + .as_slice() + ) + ); + // 不兼容档：失败路径上现取的项目名（不是 id） + assert_eq!( + panel.items_of(unlucky_presenter::dto::InstallFailureKind::Incompatible), + Some(["Entity Culling (P7dR8mSH)".to_string()].as_slice()) + ); + } +} 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..ae72915 --- /dev/null +++ b/crates/app-iced/src/pages/content/layout.rs @@ -0,0 +1,339 @@ +//! 内容库页的栏几何（纯函数 + 数值表）。 +//! +//! ## 为什么这一页自带一份几何 +//! +//! 任务书要求「与 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) + } +} + +/// 主列在**矮窗口**下切成「整列一个滚动条」的门槛（M161）。 +/// +/// ## 为什么需要这条门槛 +/// +/// 主列自上而下是：搜索条（48）+ 筛选四排（4×32 + 3×8 = 152）+ 计数头（20）+ 结果列表 + 「加载更多」（40） +/// 再加两条 `Space::X2` 间距。列表自己没有最小高度，于是窗口一矮，**列表视口只剩几十像素**： +/// 一行 `ListItem` 是 60/76 高，被切成半行——两行文字（overline + 标题）看起来像「折行挤压」。 +/// +/// ## 明确的两档行为（不是到处加滚动条） +/// +/// | 正文可用高 | 版面 | +/// |---|---| +/// | ≥ [`MIN_BODY_HEIGHT`] | 现状：**列表自己滚**（筛选条常驻，滚的时候不跑掉） | +/// | < [`MIN_BODY_HEIGHT`] | 主列整列变成**一个**纵向滚动区：列表按自然高度铺开，一行都不压 | +/// +/// 阈值 = 固定件（48 + 152 + 20 + 40 + 间距 ≈ 276）＋ 至少三整行（3×60 = 180）= 456， +/// 取 **460**（往上抹到 4 的倍数，给 divider / 取整留余量）。数值改了就改这里的算式与 +/// `layout/tests` 的等式用例。 +pub const MIN_BODY_HEIGHT: f32 = 460.0; + +/// 正文高度的两档行为。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum BodyMode { + /// 高够：列表自己滚（筛选条常驻） + Split, + /// 矮窗口：主列整列一个滚动区，列表按自然高度铺开 + ScrollWhole, +} + +impl BodyMode { + /// 判据（纯函数，测得到）。 + #[must_use] + pub fn of(body_height: f32) -> Self { + if body_height >= MIN_BODY_HEIGHT { + Self::Split + } else { + Self::ScrollWhole + } + } + + /// 列表要不要自己滚。 + #[must_use] + pub const fn list_scrolls(self) -> bool { + matches!(self, Self::Split) + } +} + +/// `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()); + } +} + +#[cfg(test)] +mod body_mode_tests { + use super::*; + + /// 门槛是**算出来的**：固定件（搜索 48 + 筛选 152 + 计数 20 + 加载更多 40 + 两条 8 间距） + /// 加三整行列表（3 × 60）。谁把 460 改成拍脑袋的数，这条会红。 + #[test] + fn the_minimum_body_height_is_fixed_parts_plus_three_rows() { + let fixed = 48.0 + 152.0 + 20.0 + 40.0 + 2.0 * Space::X2.dp(); + let three_rows = 3.0 * 60.0; + assert!( + MIN_BODY_HEIGHT >= fixed + three_rows, + "门槛 {MIN_BODY_HEIGHT} 小于「固定件 {fixed} + 三行 {three_rows}」——矮窗口还是会切半行" + ); + assert!( + MIN_BODY_HEIGHT <= fixed + three_rows + 16.0, + "门槛留了太多余量：{} 会把还放得下的窗口也推进「整列滚动」档", + MIN_BODY_HEIGHT - (fixed + three_rows) + ); + } + + /// 两档在门槛处切开，且只有 `Split` 让列表自己滚。 + #[test] + fn the_body_mode_flips_at_the_threshold() { + assert_eq!(BodyMode::of(MIN_BODY_HEIGHT), BodyMode::Split); + assert_eq!(BodyMode::of(MIN_BODY_HEIGHT - 0.5), BodyMode::ScrollWhole); + assert!(BodyMode::of(900.0).list_scrolls()); + assert!(!BodyMode::of(300.0).list_scrolls()); + } + + /// 最小窗口（880×560）落在**矮**档，验收到 760 不换版面——**正文可用高按真实外壳算**。 + /// + /// 复审 P2-2：早先这里是 `560 − 56 − 88 − 32` 反推的（三个数全错：真实是 titlebar 48 / + /// 两行页头 84 / Expanded 页边距 2×24 = chrome 180），结论碰巧对、但抓不住 metrics 漂移。 + /// 现在直接调 [`crate::pages::frame::body_height`]，chrome 从 token 现取。 + #[test] + fn the_minimum_window_size_uses_the_scrolling_body() { + use unlucky_design::color::SchemeFlavor; + use unlucky_design::typography::Platform; + + use crate::pages::frame; + use crate::pages::layout::{frame_metrics, PaneKit}; + use crate::theme::{Families, Ui}; + + let ui = Ui::with_platform( + SchemeFlavor::Light, + Platform::Windows, + Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", + }, + ); + // 880 宽 = 窗口最小尺寸（`app::MIN_SIZE.width`），属 Expanded。 + let metrics = frame_metrics(PaneKit::Single, 880.0); + let chrome = + ui.metrics().titlebar_height + ui.metrics().header_height(true) + 2.0 * metrics.gutter; + + // 真值：48 + 84 + 48 = 180。这条会随 token 改而红——那时请重看一眼两档版面。 + assert_eq!(chrome, 180.0, "外壳 chrome 与 design token 不一致"); + + // 最小窗口 560 高：正文只剩 380 < 460 ⇒ 整列滚动（本条债的真实场景）。 + let short = frame::body_height(&ui, metrics, 560.0, true); + assert_eq!(short, 560.0 - chrome); + assert_eq!( + BodyMode::of(short), + BodyMode::ScrollWhole, + "正文只剩 {short}" + ); + + // 验收尺寸 760 高：580 ≥ 460 ⇒ 列表自己滚（不换版面）。 + let tall = frame::body_height(&ui, metrics, 760.0, true); + assert_eq!(BodyMode::of(tall), BodyMode::Split); + + // 把门槛和**真实 chrome** 绑死：窗口高 = chrome + MIN 时必须还是 Split， + // 少 1px 就翻成整列滚动。chrome 涨到 100/页边距 40 这类漂移会让这条立刻红 + // （而不是像旧用例那样拿反推数字自说自话）。 + assert_eq!( + BodyMode::of(frame::body_height( + &ui, + metrics, + chrome + MIN_BODY_HEIGHT, + true + )), + BodyMode::Split + ); + assert_eq!( + BodyMode::of(frame::body_height( + &ui, + metrics, + chrome + MIN_BODY_HEIGHT - 1.0, + true + )), + BodyMode::ScrollWhole + ); + } +} 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..e8cad7d --- /dev/null +++ b/crates/app-iced/src/pages/content/message.rs @@ -0,0 +1,47 @@ +//! 内容库页的**自有**消息（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), + /// 换加载器过滤（`None` = 不限） + SetLoader(Option), + /// 选中一个项目（**页面内选中**，不 dispatch） + Select(String), + /// 选目标实例（一键装入的对象） + SetTarget(String), + /// 加载下一页 + LoadMore, + /// 同条件重试（失败态的出口） + Retry, + /// 装进目标实例 + Install, + /// **只重试上次失败的那几项**（M191；不是「整单重装」） + /// + /// app 层的落点：`AppCommand::InstallContent` 带 `retry: true`——host 拿上一轮的依赖计划 + /// 调 `DependencyPlan::retry_request()`，只重解失败项。 + RetryFailed, + /// 导入/导出区（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..8192881 --- /dev/null +++ b/crates/app-iced/src/pages/content/model.rs @@ -0,0 +1,378 @@ +//! 内容库页的视图模型：**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, Key}; + +use crate::pages::download::Download; + +mod items; +mod retry; + +pub(crate) use items::HitFacts; +pub(crate) use items::{capitalize, thousands}; +pub use items::{loader_name, Blocker, Hit, PageState, Status, Target, VersionRow}; +pub use retry::{RetryGroup, RetryPanel}; + +/// 内容库页要画的东西。 +#[derive(Debug, Clone, PartialEq)] +pub struct Content { + /// 当前内容类型（左栏四条侧栏的选中项） + pub kind: ContentKind, + /// 当前检索条件（筛选条 + 分页游标） + pub query: ContentQueryView, + /// 命中项 + pub hits: Vec, + /// 选中项 + pub selected: Option, + /// 当前状态 + pub status: Status, + /// 命中总数（`0` = 站点没给） + pub total: u32, + /// 还有下一页 + pub has_more: bool, + /// CurseForge 源可用（缺 key 时筛选条里那条禁用并说明） + pub curseforge: bool, + /// 目标实例候选 + pub targets: Vec, + /// 选中的目标实例 + pub target: Option, + /// 选中目标实例的可读标签（详情面板「装入到 …」） + pub target_label: Option, + /// 装入不上的原因（空 = 可以装） + pub blockers: Vec, + /// 安装面板的视图模型（**复用下载页那块**：`pages::download::install_panel`） + /// + /// 存整个 `Download` 而不是只存一帧视图：面板的入参就是 `&Download`，而 iced 的控件树 + /// 借用它 ⇒ 被借的东西必须活得比这一帧长（局部临时值不行）。 + pub panel: Option, + /// 「只重试这些」面板（M191）：`None` = 不渲染（全成功 / 没有失败项 / 还在跑）。 + /// + /// 与 `panel` 互斥地画：失败且有可重试项时，这块**顶替**下载页那块通用失败面板， + /// 一屏只有一个失败块（两个会说同一件事，还各自给一个「关闭」）。 + pub retry: Option, + /// 游戏版本筛选的候选（来自实例；去重、保持实例顺序） + pub versions: Vec, + /// 关键词草稿 + pub draft: String, + /// 导入/导出区（M113）：入口 + 进度 + 结果 + 导出预检 + pub pack: super::packui::Pack, + /// 选中项目的可用版本（M162：详情通道；空 = 还没拉到 / 站点没给） + pub available_versions: Vec, + /// 版本区的一句话说明（正在取 / 取不到：原因；`None` = 不必说） + pub versions_note: Option, +} + +/// 筛选条的展示态（数字/枚举都在这里，页面不再从 `ContentQuery` 里挖字段）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ContentQueryView { + /// 来源 + pub source: ContentSource, + /// 排序 + pub sort: ContentSort, + /// 游戏版本过滤 + pub version: Option, + /// 加载器过滤 + pub loader: Option, + /// 已提交的关键词（输入框显示的是 `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 = 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 = 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 = 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, + ); + + let (available_versions, versions_note) = + detail_view(content, page.selected.as_deref(), 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), + // M191：失败且有可重试项时这块才存在（全成功 ⇒ `None` ⇒ 视图里连按钮都没有） + retry: state + .install + .as_ref() + .and_then(|progress| RetryPanel::of(progress, catalog)), + versions, + draft: page.draft.clone(), + pack, + available_versions, + versions_note, + } + } + + /// 选中项在命中列表里的那一行（详情面板读它）。 + 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 { + 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(failure) = &content.failed { + // M162：没联网单独一态（空列表不能冒充「没有结果」） + return if failure.is_offline() { + Status::Offline(failure.detail.clone()) + } else { + Status::Failed(failure.detail.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`。 +fn content_install(state: &AppState, catalog: Catalog) -> Option { + state + .install + .as_ref() + .and_then(|progress| crate::pages::download::install_panel_model(progress, catalog)) +} + +/// 选中项目的版本列表 + 一句说明（详情通道；迟到结果按项目 id 丢）。 +/// +/// 三条优先级：**有结果就画结果** → 在飞就画「正在取」 → 失败才画原因。选中项变了而结果是 +/// 上一个项目的，一律当「没有」（`detail.project != selected`）——否则会画着 A 的版本列表 +/// 却高亮着 B。 +fn detail_view( + content: &ContentState, + selected: Option<&str>, + catalog: Catalog, +) -> (Vec, Option) { + let Some(selected) = selected else { + return (Vec::new(), None); + }; + if let Some(detail) = content.detail.as_ref().filter(|d| d.project == selected) { + let rows = detail + .versions + .iter() + .map(|version| VersionRow { + number: version.number.clone(), + kind: version.kind.clone(), + file_name: version.file_name.clone(), + line: catalog.render( + Key::ContentDetailVersionLine, + &[ + ("number", version.number.as_str()), + ("kind", capitalize(&version.kind).as_str()), + ("date", version.published.as_str()), + ], + ), + }) + .collect(); + return (rows, None); + } + if content.detail_pending { + return ( + Vec::new(), + Some(catalog.text(Key::ContentDetailFetching).to_string()), + ); + } + match &content.detail_failed { + Some(failure) => ( + Vec::new(), + Some(catalog.render( + Key::ContentDetailFetchFailed, + &[("reason", failure.detail.as_str())], + )), + ), + None => (Vec::new(), None), + } +} + +/// 兼容性判定（**纯函数**，单测直接钉它；见模块文档第 2 节）。 +/// +/// `hit` 是「选中项的两个支持列表」：`None` = 没选中，`Some((版本, 加载器))` = 选中了。 +/// **空列表 ≠ 不兼容**：站点没给数据时按「未知」处理，不许把「不知道」画成「不支持」。 +pub(super) fn blockers_of( + hit: Option>, + kind: ContentKind, + targets: &[Target], + target: Option<&str>, +) -> Vec { + 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::>(); + 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..378d05f --- /dev/null +++ b/crates/app-iced/src/pages/content/model/items.rs @@ -0,0 +1,259 @@ +//! 内容库页的类型：页面自留状态 / 四态 / 展示行 / 目标实例 / 装不上的原因。 +//! +//! 从 `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, + /// 目标实例 id（`None` = 没选 → 装入按钮禁用并说明） + pub target: Option, + /// 关键词输入框里的草稿（**未提交**；提交后才进 `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), + /// 未联网（M162）：**不是**「没有匹配的内容」，也不是普通失败——单独一屏， + /// 说清「要么联网要么没结果」这件事不可能靠空列表表达。 + Offline(String), +} + +impl Status { + /// 失败了吗（视图用它决定画错误面板还是列表）。 + pub const fn failed(&self) -> bool { + matches!(self, Self::Failed(_) | Self::Offline(_)) + } + + /// 未联网吗（视图据此画离线态而不是通用失败态）。 + pub const fn offline(&self) -> bool { + matches!(self, Self::Offline(_)) + } +} + +/// 版本列表的一行（M162：详情通道拉回来的 `ContentVersionView`）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct VersionRow { + /// 版本号（`mc1.20.1-0.5.11`） + pub number: String, + /// 版本类型（`release` / `beta` / `alpha`，站点原文） + pub kind: String, + /// 文件名（`None` = 站点没给） + pub file_name: Option, + /// 已经求好文案的一行（`版本号 · 类型 · 日期`） + pub line: String, +} + +/// 一条命中项的展示态（文案在这一层求好：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, + /// 支持的加载器（**站点原样的小写 facet**：兼容性判定要用它跟 `loader_facet` 比） + pub loaders: Vec, + /// 来源（行上标来源徽标） + 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::() + 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/retry.rs b/crates/app-iced/src/pages/content/model/retry.rs new file mode 100644 index 0000000..9606944 --- /dev/null +++ b/crates/app-iced/src/pages/content/model/retry.rs @@ -0,0 +1,153 @@ +//! 「只重试这些」面板的视图模型（M191）。 +//! +//! ## 它画的是什么 +//! +//! 安装失败之后，界面要说清「哪几项没装上、分别是哪种没装上」： +//! +//! ```text +//! 安装未完成 —— 3 项没装上 +//! 不兼容所选版本/加载器 +//! P7dR8mSH ← 拿不到名字时只画 id（合理兜底） +//! 取不到（网络 / 项目不存在） +//! Sodium (AANobbMI) ← 根项目：名字来自请求标题 +//! fabric-api-0.92.2.jar (1eAoo2KR) ← 下载失败：名字来自文件名 +//! [只重试这 3 个] [关闭] +//! ``` +//! +//! 每行是 `InstallFailureView::line()` 的结果（名字优先、id 次要）。名字是**语言中立**的站点 +//! 标题或文件名，不是 core 的中文散文——那条线（i18n R2）踩了就回不去。 +//! +//! ## 三条判据（都落在 [`RetryPanel::of`]，纯函数，用例直接钉） +//! +//! 1. **全成功不渲染**：`retry` 名单空 ⇒ `None` ⇒ 视图里连按钮都不存在（不是置灰）； +//! 2. **两档不混**：分组按 [`InstallFailureKind`] 分开，两档各有自己的标题 key； +//! 3. **只列名单里的**：条目原样来自 DTO（`presenter` 从 `DependencyPlan::retry_request()` +//! 的同一份失败名单产出），页面不自己挑、也不补「顺便重装根」。 +//! +//! ## 为什么这里不拼文案 +//! +//! 分组标题是 [`Key`]（i18n），条目是项目键（站点数据，不是文案）。拼一句带量的中文句子 +//! 会把语序写死——英文与中文的量词位置不同（`Retry just these 3` / `只重试这 3 个`）。 + +use unlucky_i18n::{Catalog, Key}; +use unlucky_presenter::dto::{ + ContentInstallRequest, ContentSource, InstallFailureKind, InstallFailureView, + InstallProgressView, InstallStage, LoaderKind, +}; + +/// 面板上的一个档位分组。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct RetryGroup { + /// 哪一档（顺序固定，见 [`InstallFailureKind::ALL`]） + pub kind: InstallFailureKind, + /// 这一档的标题 key（不硬编码中文） + pub title: Key, + /// 这一档要画的每一行（`名字 (id)`；拿不到名字时就只有 id，顺序 = 计划里的顺序） + pub items: Vec, +} + +/// 「只重试这些」面板（`None` = 不渲染：没有失败项、或已经全成功）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct RetryPanel { + /// 失败的那次装入的目标实例（重试只对这个实例生效） + pub instance: String, + /// 标题（已按词表渲染：带条数） + pub title: String, + /// 主按钮文字（已按词表渲染：`只重试这 N 个`） + /// + /// 存在这里而不是画的时候现拼：`Button::new` 要的是 `&'a str`，而词表渲染出来的是 + /// `String`——存进模型（与 `Hit` / `VersionRow.line` 同一手法）就不必为了一个标签 + /// 去改组件库的入参类型。 + pub action: String, + /// 按档分组（空组不出现） + pub groups: Vec, + /// 失败项总数（标题与按钮都用这个数） + pub total: usize, +} + +impl RetryPanel { + /// 进度快照 → 面板（**唯一**判据；`None` = 视图里不该出现这块）。 + /// + /// 只认 `Failed` 这一态：`Done` 没有可重试的东西，`Cancelled` 是用户自己停的 + /// （那条路上根本没有失败名单），`Planning`/`Downloading` 还在跑。 + #[must_use] + pub fn of(progress: &InstallProgressView, catalog: Catalog) -> Option { + if progress.stage != InstallStage::Failed || !progress.has_retry() { + return None; + } + let total = progress.retry.len(); + let count = total.to_string(); + let groups = InstallFailureKind::ALL + .into_iter() + .map(|kind| RetryGroup { + kind, + title: title_of(kind), + items: progress + .retry_of(kind) + .map(InstallFailureView::line) + .collect(), + }) + .filter(|group| !group.items.is_empty()) + .collect(); + Some(Self { + instance: progress.instance.clone(), + title: catalog.render(Key::ContentInstallFailedTitle, &[("count", count.as_str())]), + action: catalog.render(Key::ContentInstallRetryOnly, &[("count", count.as_str())]), + groups, + total, + }) + } + + /// 两档都在吗（「分组」这件事本身的判据：都出现时界面上是两段，不是一段）。 + #[must_use] + pub fn has_both_tiers(&self) -> bool { + self.groups.len() == 2 + } + + /// 某一档的条目（用例断言用）。 + #[must_use] + pub fn items_of(&self, kind: InstallFailureKind) -> Option<&[String]> { + self.groups + .iter() + .find(|group| group.kind == kind) + .map(|group| group.items.as_slice()) + } +} + +/// 档位 → 标题 key（**穷尽 match**：合并两档会少一条文案，用例会红）。 +#[must_use] +pub const fn title_of(kind: InstallFailureKind) -> Key { + match kind { + InstallFailureKind::Incompatible => Key::ContentInstallRetryIncompatible, + InstallFailureKind::Unreachable => Key::ContentInstallRetryUnreachable, + } +} + +impl super::Content { + /// 「只重试这些」那一次请求（M191；`None` = 没有可重试的面板 ⇒ 这个动作不存在）。 + /// + /// 载荷里 `retry: true` 是**唯一**的语义开关：host 收到它就不解根项目，而是拿上一轮的计划 + /// 调 `DependencyPlan::retry_request()`（只请求失败的那几个项目）。其余字段照旧填， + /// 是因为 `ContentInstallRequest` 的判据仍要能读（`project` / `title` 也用于日志）； + /// 这些字段在重试路径上**不被 host 读取**——过滤条件与落盘目录都来自那份计划。 + /// + /// 实例取**失败那次的**实例，不是页面上此刻选中的那个：用户可能已经换了目标实例。 + pub fn retry_install_request(&self) -> Option { + let retry = self.retry.as_ref()?; + let hit = self.selected_hit(); + let target = self + .targets + .iter() + .find(|target| target.id == retry.instance); + Some(ContentInstallRequest { + project: hit.map(|hit| hit.id.clone()).unwrap_or_default(), + title: hit.map(|hit| hit.title.clone()).unwrap_or_default(), + kind: self.kind, + source: hit.map_or(ContentSource::Modrinth, |hit| hit.source), + instance: retry.instance.clone(), + game_version: target.map_or_else(String::new, |target| target.mc_version.clone()), + loader: target.map_or(LoaderKind::Vanilla, |target| target.loader), + retry: true, + }) + } +} 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..f929fbf --- /dev/null +++ b/crates/app-iced/src/pages/content/model/tests.rs @@ -0,0 +1,364 @@ +//! 内容库视图模型的守门测试（M109）：四态判定、兼容性判定、装入闸门。 +//! +//! 全部是纯函数级断言（不开图形环境）：`status_of` / `blockers_of` / `Content::can_install` +//! 是页面「该画什么、按钮能不能按」的唯一判据，钉住它们比截图更早期。 + +use super::*; +use unlucky_i18n::Lang; +use unlucky_presenter::dto::{ + ContentDetail, ContentFailure, ContentFailureKind, ContentHit, ContentKind, ContentQuery, + ContentResults, ContentSource, ContentVersionView, 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 { + 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 { + 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, 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, 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(ContentFailure::new(ContentFailureKind::Server, "站点 503")); + let model = Content::from_snapshot(&state, &PageState::default(), Lang::En.catalog()); + assert_eq!(model.status, Status::Failed("站点 503".to_string())); + assert!(model.status.failed()); + assert!(!model.status.offline()); +} + +#[test] +fn no_network_is_its_own_state_not_an_empty_list() { + // M162：无网必须画「未联网」，不能与「没有匹配的内容」共用一个空态。 + let mut state = state_with(None, false); + state.content.results = Some(results(Vec::new(), 0)); + state.content.failed = Some(ContentFailure::offline("connect timed out")); + let model = Content::from_snapshot(&state, &PageState::default(), Lang::En.catalog()); + assert_eq!( + model.status, + Status::Offline("connect timed out".to_string()) + ); + assert!(model.status.offline()); + assert!(model.status.failed()); + assert_ne!(model.status, Status::Empty); +} + +#[test] +fn versions_come_from_the_detail_channel_of_the_selected_project() { + let mut state = state_with(Some(results(vec![hit(&["1.20.1"], &["fabric"])], 0)), false); + let mut page = PageState { + selected: Some("p1".to_string()), + ..PageState::default() + }; + // 详情还没到：说明「正在取」，不是「一个版本都没有」 + state.content.request_detail("p1"); + let model = Content::from_snapshot(&state, &page, Lang::En.catalog()); + assert!(model.available_versions.is_empty()); + assert!(model.versions_note.is_some()); + + state.content.apply_detail( + "p1", + ContentDetail { + project: "p1".to_string(), + title: "Sodium".to_string(), + description: "fast".to_string(), + body: String::new(), + versions: vec![ContentVersionView { + id: "v1".to_string(), + name: "Sodium 0.6.0".to_string(), + number: "mc1.20.1-0.6.0".to_string(), + kind: "release".to_string(), + game_versions: vec!["1.20.1".to_string()], + loaders: vec!["fabric".to_string()], + published: "2026-02-01T00:00:00Z".to_string(), + file_name: Some("sodium.jar".to_string()), + file_size: Some(2048), + }], + }, + ); + let model = Content::from_snapshot(&state, &page, Lang::En.catalog()); + assert_eq!(model.available_versions.len(), 1); + assert_eq!(model.available_versions[0].number, "mc1.20.1-0.6.0"); + assert!(model.available_versions[0].line.contains("mc1.20.1-0.6.0")); + assert!(model.versions_note.is_none()); + + // 换了选中项：上一个项目的版本列表不许画在这个项目下面 + page.selected = Some("p2".to_string()); + let model = Content::from_snapshot(&state, &page, Lang::En.catalog()); + assert!(model.available_versions.is_empty()); +} + +#[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, + launch: unlucky_presenter::dto::LaunchArgsView::default(), + }]; + 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", + "不能画「原版」" + ); +} + +// M191：安装失败的两档分组与「只重试这些」（按主题分卷，父文件已贴 400 行硬线） +// +// `#[path]` 显式给出：本文件自己是 `#[path = "model/tests.rs"]` 挂上去的，子模块默认按 +// 「父模块所在目录」找，会指到 `model/retry.rs`（视图模型本体）而不是这里的 `tests/retry.rs`。 +#[path = "tests/retry.rs"] +mod retry; diff --git a/crates/app-iced/src/pages/content/model/tests/retry.rs b/crates/app-iced/src/pages/content/model/tests/retry.rs new file mode 100644 index 0000000..f5ba6d0 --- /dev/null +++ b/crates/app-iced/src/pages/content/model/tests/retry.rs @@ -0,0 +1,158 @@ +//! M191：安装失败的两档分组 + 「只重试这些」（`super` 按主题分卷，父文件已贴 400 行硬线）。 +//! +//! 三条变异守门：两档不许合并 / 全成功不许渲染 / 重试只针对失败那次的实例。 + +use super::super::{Content, PageState, RetryPanel}; +use super::{hit, results, state_with}; + +use unlucky_i18n::{Key, Lang}; +use unlucky_presenter::dto::{ + InstallFailureKind, InstallFailureView, InstallProgressView, InstallStage, +}; + +/// 一份「两档都有」的失败进度快照。 +fn failed_progress() -> unlucky_presenter::dto::InstallProgressView { + let mut progress = InstallProgressView { + version: "Sodium".to_string(), + instance: "survival".to_string(), + stage: InstallStage::Failed, + files_done: 1, + files_total: 4, + ..InstallProgressView::new() + }; + // 三种可显示性各一条（与 `plan::label_of` 的三种情况同形）： + // 根项目用请求里的标题、下载失败用文件名、拿不到名的只画 id。 + progress.retry = vec![ + InstallFailureView::new( + "AANobbMI", + "Sodium", + InstallFailureKind::Unreachable, + "连不上 CDN", + ), + InstallFailureView::new( + "P7dR8mSH", + "Entity Culling", + InstallFailureKind::Incompatible, + "没有匹配的版本", + ), + InstallFailureView::new("1eAoo2KR", "", InstallFailureKind::Unreachable, "HTTP 404"), + ]; + progress +} + +/// 两档**分组**画，各有自己的标题；条目按档分开，不混成一段。 +/// +/// 变异守门②：把两档合并（`kind_of` 都映成 `Unreachable`，或 `title_of` 都返回同一个 key） +/// ⇒ `groups.len()` 变 1 / 两个 title 相同 ⇒ 这条红。 +#[test] +fn the_two_tiers_are_two_groups_with_two_labels() { + let panel = RetryPanel::of(&failed_progress(), Lang::En.catalog()).expect("有失败项就有面板"); + assert_eq!(panel.total, 3); + assert!(panel.has_both_tiers(), "{:?}", panel.groups); + // **P2-1 的守门**：有名字的画「名字 (id)」，没有名字的才只画 id + assert_eq!( + panel.items_of(InstallFailureKind::Incompatible), + Some(["Entity Culling (P7dR8mSH)".to_string()].as_slice()) + ); + assert_eq!( + panel.items_of(InstallFailureKind::Unreachable), + Some(["Sodium (AANobbMI)".to_string(), "1eAoo2KR".to_string()].as_slice()) + ); + // 变异守门：把标签置空 ⇒ 这一行退回裸 id，上面两条立刻红 + assert!( + panel + .items_of(InstallFailureKind::Unreachable) + .is_some_and(|items| items[0].starts_with("Sodium")), + "根项目必须显示请求里的标题，不是 id" + ); + let titles: Vec = panel.groups.iter().map(|group| group.title).collect(); + assert_ne!(titles[0], titles[1], "两档的标题 key 不许是同一个"); + // 文案来自词表（不是硬编码中文）：英文目录下这两句必须不同且不含中文 + let incompatible = Lang::En.catalog().text(titles[0]); + let unreachable = Lang::En.catalog().text(titles[1]); + assert_ne!(incompatible, unreachable); + assert!(incompatible.is_ascii(), "{incompatible}"); + assert!(unreachable.is_ascii(), "{unreachable}"); + // 按钮文字带条数，也来自词表 + assert!(panel.action.contains('3'), "{}", panel.action); + assert!(panel.action.is_ascii(), "{}", panel.action); +} + +/// 只有一档失败时只画一段（空组不出现——空的「取不到」标题会让用户以为那里也坏了）。 +#[test] +fn an_empty_tier_does_not_get_a_group() { + let mut progress = InstallProgressView { + stage: InstallStage::Failed, + ..InstallProgressView::new() + }; + progress.retry = vec![InstallFailureView::new( + "P7dR8mSH", + "Entity Culling", + InstallFailureKind::Incompatible, + "没有匹配的版本", + )]; + let panel = RetryPanel::of(&progress, Lang::En.catalog()).expect("有失败项就有面板"); + assert!(!panel.has_both_tiers()); + assert!(panel.items_of(InstallFailureKind::Unreachable).is_none()); +} + +/// **全成功时不渲染**：`Done` 且没有失败项 ⇒ 面板不存在（不是置灰，是连构造都没有）。 +/// +/// 变异守门③：把 `RetryPanel::of` 的判据去掉（恒返回 `Some`）⇒ 这条红。 +#[test] +fn a_fully_successful_install_has_no_retry_surface_at_all() { + let done = InstallProgressView { + version: "Sodium".to_string(), + instance: "survival".to_string(), + stage: InstallStage::Done, + files_done: 4, + files_total: 4, + ..InstallProgressView::new() + }; + assert!(RetryPanel::of(&done, Lang::En.catalog()).is_none()); + // 页面上也一样：状态是 Done ⇒ 页底那块既没有重试面板，也没有失败面板 + let mut state = state_with(Some(results(vec![hit(&["1.20.1"], &["fabric"])], 0)), false); + state.install = Some(done); + let model = Content::from_snapshot(&state, &PageState::default(), Lang::En.catalog()); + assert!(model.retry.is_none(), "全成功还在页面上画重试面板"); + assert!(model.panel.is_none()); + assert!(model.retry_install_request().is_none()); + + // 判据是**两半**：`Failed` **且** 名单非空。第一半单独钉住——就算快照里残留了名单 + // （不该发生，host 成功时会清），`Done` 也不画（r1 复审指出：只去掉这一半曾全绿）。 + let mut stale = InstallProgressView { + stage: InstallStage::Done, + ..InstallProgressView::new() + }; + stale.retry = failed_progress().retry; + assert!( + RetryPanel::of(&stale, Lang::En.catalog()).is_none(), + "Done 态不许画重试面板（判据是「失败且有名单」，不是「有名单」）" + ); + + // 第二半：失败但没有名单（例如整合包那条本地失败）同样不画：没有可重试的东西 + let mut failed = InstallProgressView { + stage: InstallStage::Failed, + ..InstallProgressView::new() + }; + failed.retry.clear(); + assert!(RetryPanel::of(&failed, Lang::En.catalog()).is_none()); +} + +/// 「只重试这些」发出去的是**失败那次的实例** + `retry: true`（不是页面此刻选中的实例， +/// 也不是一次新的根项目安装）。 +#[test] +fn the_retry_action_targets_the_failed_attempt() { + let mut state = state_with(Some(results(vec![hit(&["1.20.1"], &["fabric"])], 0)), false); + // 名单要有，否则这块入口根本不存在 + state.install = Some(failed_progress()); + + let model = Content::from_snapshot(&state, &PageState::default(), Lang::En.catalog()); + assert!(model.retry.is_some()); + let request = model.retry_install_request().expect("有面板就该有请求"); + assert!( + request.retry, + "重试必须是 retry: true（否则 host 会从根解起）" + ); + assert_eq!(request.instance, "survival"); +} 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..8ea46e3 --- /dev/null +++ b/crates/app-iced/src/pages/content/packui.rs @@ -0,0 +1,65 @@ +//! 整合包**导入 / 导出**区（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` 选态） | +//! +//! ## M160 新增的一屏 +//! +//! `model/pick.rs` + `view/pick.rs` 是**导入前的冲突清单**：分页（每页 `PAGE_SIZE` 条）、 +//! 三个入口、计数摘要、确认/取消。它出现的前提是 core 的预检给出了至少一条冲突—— +//! 没有冲突时页面连这一屏都不画（直接往下导）。 +//! +//! ## 本版明确的边界（报告里同样登记） +//! +//! - **没有系统文件选择框**：依赖树里没有 `rfd` 一类的对话框依赖，加它要动根 `Cargo.toml`、 +//! 过许可门禁、还要给 Linux 选后端（GTK / xdg-portal），直接影响「单文件产物」。所以入口是 +//! **拖拽（真能用）+ 路径输入框**，并且把原因写在界面上（[`model::Pack::no_dialog_note`]）。 +//! - **冲突是逐文件决策了（M160）**：点「导入」先跑一次**只读预检**（core 的 `scan_pack`）， +//! 没有冲突就直接导（不打扰用户）；有冲突就画那一屏清单——分页（[`model::PAGE_SIZE`] 条一页）、 +//! 「全部保留 / 全部覆盖 / 逐项」三个入口、计数摘要、确认与取消。**缺省永远是保留**： +//! 没点过的文件一个都不会被包内内容替换。仍然不支持的是「两者都留（改名）」——那要改落盘 +//! 布局，不在本轮。 + +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..2a150be --- /dev/null +++ b/crates/app-iced/src/pages/content/packui/demo.rs @@ -0,0 +1,345 @@ +//! 出图夹具（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` / `pick` / `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, ImportCancelView, + ImportErrorView, ImportFailureStageView, 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 { + 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 = 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()), + // M160：导入前的冲突清单（分页 + 三个入口 + 计数摘要） + "pick" => { + import.scan = Some(scan(312)); + // 停在第 2 页，且已经逐项点过两条「覆盖」——图上能同时看见分页与逐项状态 + page.pick_page = 1; + // 两条落到**第 2 页**的路径上：图上能同时看见「保留」与「覆盖」两种行状态 + page.pick_choices.insert( + "config/generated/module-041.toml".to_string(), + unlucky_presenter::dto::ConflictChoiceView::Overwrite, + ); + page.pick_choices.insert( + "config/generated/module-044.toml".to_string(), + unlucky_presenter::dto::ConflictChoiceView::Overwrite, + ); + } + "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()); + } + // 致命态（M161 分成三档出图：预检没过 / 已回滚 / 回滚没做完）。 + // `failed` 保留旧名字（= 已回滚），另外两个是新档位。 + "failed" | "failed_rolled_back" => { + let mut fatal = report(ImportStatusView::Failed, false); + fatal.error = Some(ImportErrorView { + code: "import_integrity".to_string(), + label: "Integrity check".to_string(), + message: "mods/sodium.jar: sha1 mismatch after write".to_string(), + hint: Some("Re-download the pack from its source".to_string()), + }); + fatal.rolled_back = true; + fatal.failure_stage = Some(ImportFailureStageView::RolledBack); + import.report = Some(fatal); + } + // 预检没过：**一个字节都没写**（与上一条只差 `failure_stage`，图上要能一眼分辨） + "failed_preflight" => { + 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; + fatal.rolled_back = true; + fatal.failure_stage = Some(ImportFailureStageView::NotStarted); + import.report = Some(fatal); + } + // 回滚没做完：目标目录可能与导入前不同 + "failed_incomplete" => { + let mut fatal = report(ImportStatusView::Failed, false); + fatal.error = Some(ImportErrorView { + code: "import_integrity".to_string(), + label: "Integrity check".to_string(), + message: "mods/sodium.jar: sha1 mismatch after write".to_string(), + hint: None, + }); + fatal.rolled_back = false; + fatal.failure_stage = Some(ImportFailureStageView::RollbackIncomplete); + 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, + failure_stage: None, + cancel: ImportCancelView::NotRequested, + }; + 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, + } +} + +/// 一条待决冲突（M160 预览清单的一行）。 +fn pending(index: usize) -> unlucky_presenter::dto::ImportConflictView { + // 前几条用真实形态的路径，其余按序号生成：截图里既要有可读的真实感，也要有"很多条"的证据。 + let path = match index { + 0 => "config/sodium-options.json".to_string(), + 1 => "mods/create-1.2.3.jar".to_string(), + 2 => "config/jei/jei-client.ini".to_string(), + 3 => "options.txt".to_string(), + _ => format!("config/generated/module-{index:03}.toml"), + }; + unlucky_presenter::dto::ImportConflictView { + path, + source: if index.is_multiple_of(3) { + unlucky_presenter::dto::ConflictSourceView::ClientOverrides + } else { + unlucky_presenter::dto::ConflictSourceView::Overrides + }, + reason: if index.is_multiple_of(2) { + unlucky_presenter::dto::ConflictReasonView::PreExisting + } else { + unlucky_presenter::dto::ConflictReasonView::UserModified + }, + disabled: false, + pack_sha1: "9f2c41ab77de3350aa1b8c0d5e6f708192a3b4c5".to_string(), + pack_size: 3_800 + (index as u64 * 37) % 900, + disk_sha1: "c1d2e3f4050617283940a5b6c7d8e9f0a1b2c3d4".to_string(), + disk_size: 4_100 + (index as u64 * 53) % 1_200, + base_sha1: (!index.is_multiple_of(2)) + .then(|| "3a7d90ff11bc22445566ef7788990011aabbccdd".to_string()), + } +} + +/// 预检结果（`count` 条冲突；图上靠分页只画当前这一页）。 +fn scan(count: usize) -> unlucky_presenter::dto::ImportScanView { + let conflicts: Vec = + (0..count).map(pending).collect(); + let lost_bytes = conflicts.iter().map(|each| each.disk_size).sum(); + let incoming_bytes = conflicts.iter().map(|each| each.pack_size).sum(); + unlucky_presenter::dto::ImportScanView { + target: PathBuf::from("C:/ULL/instances/survival/.minecraft"), + format: Some(PackFormatView::Modrinth), + pack_name: Some("Better MC".to_string()), + pack_version: Some("1.2.0".to_string()), + game_version: Some("1.20.1".to_string()), + conflicts, + unknown_remote: 4, + lost_bytes, + incoming_bytes, + notes: Vec::new(), + error: None, + } +} + +/// 导出预检：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..8b1a754 --- /dev/null +++ b/crates/app-iced/src/pages/content/packui/message.rs @@ -0,0 +1,69 @@ +//! 整合包导入/导出区的**自有**消息（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, + /// 展开/收起某一条冲突的三方明细 + ToggleConflict(String), + /// 冲突清单翻页（M160；页码会夹在 `[0, pages)` 里） + PickPage(usize), + /// 逐项切换某一条的处置（保留 ⇄ 覆盖） + TogglePick(String), + /// 整批档：全部保留（逐项里"覆盖"的那些一起清掉） + PickKeepAll, + /// 整批档：全部覆盖 + PickOverwriteAll, + /// 按当前选择开始导入 + ConfirmImport, + /// 取消这次导入（不写盘，回到入口态） + CancelImport, + /// 换目标实例（`None` = 按包名新建） + SetInstance(Option), + /// 换新实例名（`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..ac015ba --- /dev/null +++ b/crates/app-iced/src/pages/content/packui/model.rs @@ -0,0 +1,310 @@ +//! 导入/导出区的视图模型：**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`] +//! 是致命失败。两者字段类型不同、画的时候颜色与图标也不同，不可能混成一个列表。 +//! +//! 致命那一类内部还要再分三档（M161）：预检没过（一个字节都没写）/ 已回滚 / 回滚没做完， +//! 见 [`report::FatalKind`]——措辞、图标、底色三处都分开。 + +mod export; +mod pick; +mod progress; +mod report; + +pub use export::{format_label, request_of as request_export, Export, Preview}; +pub use pick::{Pick, PickRow}; +pub use progress::Running; +pub use report::{ConflictRow, FatalKind, Report, Row}; + +use std::collections::BTreeMap; + +use unlucky_i18n::{Catalog, Key}; +use unlucky_presenter::dto::{ + ConflictChoiceView, ConflictDecisionsView, 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, + /// 新实例名 + 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, + /// 冲突清单翻到第几页（0 起；M160） + pub pick_page: usize, + /// 逐项决策（**只存"覆盖"的路径**：保留 = 表里没有这条，于是"没点过"永远是保留） + pub pick_choices: BTreeMap, + /// 「全部覆盖」这一档是否被点过（整批档；逐项决策仍然优先于它） + pub pick_overwrite_all: bool, +} + +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, + pick_page: 0, + pick_choices: BTreeMap::new(), + pick_overwrite_all: false, + } + } +} + +impl PackPageState { + /// 用户在冲突清单上点的处置（逐项优先，其次整批档，缺省保留）。 + #[must_use] + pub fn pick_choice(&self, path: &str) -> ConflictChoiceView { + if let Some(choice) = self.pick_choices.get(path) { + return *choice; + } + if self.pick_overwrite_all { + ConflictChoiceView::Overwrite + } else { + ConflictChoiceView::KeepUser + } + } + + /// 把这一屏的选择变成发给宿主的那份决策。 + /// + /// 一个都没点 ⇒ `KeepAll`（与 core 的"全部保留"同一个语义）；点过 ⇒ `PerItem { default, items }`， + /// 其中 `default` 就是整批档。于是"全部覆盖之后又单独放回两条"也能表达（不需要把剩下几百条 + /// 全点一遍），而"没点过"永远落在保留上。 + #[must_use] + pub fn decisions( + &self, + scan: Option<&unlucky_presenter::dto::ImportScanView>, + ) -> ConflictDecisionsView { + use unlucky_presenter::dto::{ConflictDecisionView, ConflictDecisionsView}; + let default = if self.pick_overwrite_all { + ConflictChoiceView::Overwrite + } else { + ConflictChoiceView::KeepUser + }; + // 只发"与缺省档不同"的项：其余在 core 侧自然落到缺省档。 + let items: Vec = self + .pick_choices + .iter() + .filter(|(_, choice)| **choice != default) + .map(|(path, choice)| ConflictDecisionView { + path: path.clone(), + choice: *choice, + }) + .collect(); + // 冲突清单为空时，`PerItem` 没有对象，直接给整批档（语义等价、日志更短）。 + let empty = scan.is_none_or(|scan| scan.conflicts.is_empty()); + if items.is_empty() || empty { + return match default { + ConflictChoiceView::KeepUser => ConflictDecisionsView::KeepAll, + ConflictChoiceView::Overwrite => ConflictDecisionsView::OverwriteAll, + }; + } + ConflictDecisionsView::per_item(default, items) + } +} + +/// 一个实例候选（导入目标与导出源共用）。 +#[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, + /// 「看起来像 X，但缺 Y」（或「没有任何已知格式认领」） + pub lead: String, + /// 包里实际看到的标记（host 已截断，只给代表性几条） + pub saw: Vec, + /// 兜底说明（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, + /// 选中的目标实例 + pub instance: Option, + /// 新实例名 + pub instance_name: String, + /// 正在导入（有它就画那块面板） + pub running: Option, + /// 探测失败诊断 + pub probe: Option, + /// 用户点过取消、**结果还没回来**（面板已收回）。它只作占位：真实结局在 + /// `report.cancel` 里（已回滚 / 回滚没做完 / 取消太晚），所以文案不许在这里替结局下结论。 + pub cancelled: bool, + /// 取消提示的正文 + pub cancelled_note: &'static str, + /// 导入结果 + pub report: Option, + /// **导入前的冲突清单**（M160：`Some` 就画那一屏，别的东西都让位） + pub pick: Option, + /// 导出块 + pub export: Export, +} + +impl Pack { + /// presenter 快照 + 页面选择 → 视图模型（**唯一的真数据入口**）。 + pub fn of( + import: &ImportState, + export: &ExportState, + page: &PackPageState, + targets: &[Target], + catalog: Catalog, + ) -> Self { + let candidates: Vec = 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)), + pick: import.scan.as_ref().and_then(|scan| { + pick::pick_of( + scan, + page.pick_page, + &page.pick_choices, + page.pick_overwrite_all, + 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.pick.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, + /// 内联文件样例 + pub inline_sample: Vec, + /// `还有 N 个文件…` + pub more_line: Option, + /// core 的 `notes`（已知损失） + pub notes: Vec, +} + +/// 导出块。 +#[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, + /// 选中的实例 + pub instance: Option, + /// 包名 + 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, + /// 写盘完成行 + pub done: Option, + /// 失败原因 + pub failed: Option, +} + +/// 导出一块。 +pub(super) fn export_of( + state: &ExportState, + page: &PackPageState, + targets: Vec, + 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 = 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::>(); + 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/pick.rs b/crates/app-iced/src/pages/content/packui/model/pick.rs new file mode 100644 index 0000000..1877502 --- /dev/null +++ b/crates/app-iced/src/pages/content/packui/model/pick.rs @@ -0,0 +1,260 @@ +//! 导入**冲突清单**的视图模型（M160）：分页、计数、逐项处置。 +//! +//! # 为什么是分页而不是"一次画完" +//! +//! 冲突清单可能有几千条（一个用户改过很多配置的老实例）。`iced` 的每一行都是真实 widget， +//! 一次画几千行会同时拖慢布局与滚动，而用户真正要看的永远只有"这一屏"。所以模型里只出 +//! **当前这一页**（[`PAGE_SIZE`] 条），页面上的「上一页 / 下一页」改的是 +//! [`PackPageState::pick_page`]——数据本身留在 presenter 的 `ImportScanView` 里，页面不复制。 +//! +//! # 三个入口如何体现在计数上 +//! +//! | 用户点了 | 决策表 | 计数 | +//! |---|---|---| +//! | 全部保留 | [`ConflictDecisionsView::KeepAll`] | 覆盖 0 | +//! | 全部覆盖 | [`ConflictDecisionsView::OverwriteAll`] | 覆盖 = 全部 | +//! | 逐项 | `PerItem`（只列"覆盖"的那些，其余按保留） | 覆盖 = 点过的条数 | +//! +//! 页面显示的两个数直接来自 [`PackPageState::decisions`]、[`PackPageState::pick_choice`] 的计算， +//! 与发给 host 的那份决策**同源**——不会出现"界面说覆盖 3 个、实际覆盖 0 个"。 + +use std::collections::BTreeMap; + +use unlucky_i18n::{Catalog, Key}; +use unlucky_presenter::dto::{ + human_bytes, ConflictChoiceView, ConflictReasonView, ConflictSourceView, ImportConflictView, + ImportScanView, +}; + +/// 一页画多少行（一次画几千行是性能陷阱；40 行在一屏内可读且不滚动太多）。 +pub const PAGE_SIZE: usize = 40; + +/// 冲突清单块（导入前那一屏）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Pick { + /// 标题（`导入前：有 12 个文件已存在且内容不同`） + pub title: String, + /// 计数摘要（`保留 9 · 覆盖 3 · 覆盖将丢弃 2.4 MB`） + pub summary: String, + /// 缺省说明（"没改动的一律按保留"） + pub default_note: &'static str, + /// 判不了的远端条目（`Some` 才画那一行） + pub unknown_note: Option, + /// **当前页**的行（最多 [`PAGE_SIZE`] 条） + pub rows: Vec, + /// 当前页（0 起） + pub page: usize, + /// 总页数（至少 1） + pub pages: usize, + /// 区间说明（`第 1-40 项，共 312 项`） + pub range: String, + /// 保留几条 + pub keep_count: usize, + /// 覆盖几条 + pub overwrite_count: usize, + /// 能不能翻页 + pub can_prev: bool, + /// 能不能翻页 + pub can_next: bool, + /// 三个入口的文案 + pub keep_all: &'static str, + /// 三个入口的文案 + pub overwrite_all: &'static str, + /// 逐项按钮（保留）的文案 + pub row_keep: &'static str, + /// 逐项按钮（覆盖）的文案 + pub row_overwrite: &'static str, + /// 翻页文案 + pub prev: &'static str, + /// 翻页文案 + pub next: &'static str, + /// 确认导入 + pub confirm: String, + /// 取消导入 + pub cancel: &'static str, + /// 「全部保留」这一档当前是否生效（整批档切到保留时高亮） + pub keep_all_active: bool, + /// 「全部覆盖」这一档当前是否生效 + pub overwrite_all_active: bool, +} + +/// 清单里的一行。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct PickRow { + /// 实例内路径 + pub path: String, + /// 来源（`包内 overrides/` / `清单 files[]`） + pub source: String, + /// 成因（`本来就在` / `你改过`） + pub reason: String, + /// 两侧体积（`你的：2.1 MB · 包内：1.8 MB`） + pub sizes: String, + /// 当前处置（[`ConflictChoiceView::KeepUser`] = 保留） + pub choice: ConflictChoiceView, + /// 这一行按钮上写的字（点了就变成另一侧） + pub toggle: &'static str, +} + +impl PickRow { + /// 这一行是"覆盖"吗。 + #[must_use] + pub const fn overwrites(&self) -> bool { + matches!(self.choice, ConflictChoiceView::Overwrite) + } +} + +/// 从预检结果 + 页面选择造出这一块（`None` = 没有待决冲突，页面不该画它）。 +#[must_use] +pub fn pick_of( + scan: &ImportScanView, + page_number: usize, + per_item: &BTreeMap, + batch_overwrite: bool, + catalog: Catalog, +) -> Option { + if scan.conflicts.is_empty() { + return None; + } + let total = scan.conflicts.len(); + let pages = total.div_ceil(PAGE_SIZE).max(1); + let page = page_number.min(pages - 1); + let from = page * PAGE_SIZE; + let to = (from + PAGE_SIZE).min(total); + + let rows: Vec = scan.conflicts[from..to] + .iter() + .map(|conflict| row_of(conflict, per_item, batch_overwrite, catalog)) + .collect(); + + let overwrite_count = scan + .conflicts + .iter() + .filter(|conflict| { + effective(conflict.path.as_str(), per_item, batch_overwrite) + == ConflictChoiceView::Overwrite + }) + .count(); + let keep_count = total - overwrite_count; + // 覆盖会丢掉多少：只算"你真选了覆盖"的那些，避免用最坏数字吓人。 + let lost = scan + .conflicts + .iter() + .filter(|conflict| { + effective(conflict.path.as_str(), per_item, batch_overwrite) + == ConflictChoiceView::Overwrite + }) + .map(|conflict| conflict.disk_size) + .fold(0_u64, u64::saturating_add); + + Some(Pick { + title: catalog.render(Key::PackPickTitle, &[("count", &total.to_string())]), + summary: catalog.render( + Key::PackPickSummary, + &[ + ("keep", &keep_count.to_string()), + ("overwrite", &overwrite_count.to_string()), + ("bytes", &human_bytes(lost)), + ], + ), + default_note: catalog.text(Key::PackPickDefaultNote), + unknown_note: (scan.unknown_remote > 0).then(|| { + catalog.render( + Key::PackPickUnknownRemote, + &[("count", &scan.unknown_remote.to_string())], + ) + }), + rows, + page, + pages, + range: catalog.render( + Key::PackPickPage, + &[ + ("from", &(from + 1).to_string()), + ("to", &to.to_string()), + ("total", &total.to_string()), + ], + ), + keep_count, + overwrite_count, + can_prev: page > 0, + can_next: page + 1 < pages, + keep_all: catalog.text(Key::PackPickKeepAll), + overwrite_all: catalog.text(Key::PackPickOverwriteAll), + row_keep: catalog.text(Key::PackPickRowKeep), + row_overwrite: catalog.text(Key::PackPickRowOverwrite), + prev: catalog.text(Key::PackPickPrev), + next: catalog.text(Key::PackPickNext), + confirm: catalog.render(Key::PackPickConfirm, &[]), + cancel: catalog.text(Key::PackPickCancel), + keep_all_active: !batch_overwrite, + overwrite_all_active: batch_overwrite, + }) +} + +/// 一条冲突的**有效**处置：逐项优先，其次整批档，缺省保留（与 core 侧同一条规则）。 +fn effective( + path: &str, + per_item: &BTreeMap, + batch_overwrite: bool, +) -> ConflictChoiceView { + if let Some(choice) = per_item.get(path) { + return *choice; + } + if batch_overwrite { + ConflictChoiceView::Overwrite + } else { + ConflictChoiceView::KeepUser + } +} + +fn row_of( + conflict: &ImportConflictView, + per_item: &BTreeMap, + batch_overwrite: bool, + catalog: Catalog, +) -> PickRow { + let choice = effective(conflict.path.as_str(), per_item, batch_overwrite); + PickRow { + path: conflict.path.clone(), + source: source_label(conflict.source, catalog).to_owned(), + reason: reason_label(conflict.reason, catalog).to_owned(), + sizes: format!( + "{} · {}", + catalog.render( + Key::PackPickDisk, + &[("size", &human_bytes(conflict.disk_size))] + ), + catalog.render( + Key::PackPickIncoming, + &[("size", &human_bytes(conflict.pack_size))] + ) + ), + choice, + // 按钮写"点了会变成什么"：当前保留 ⇒ 按钮是「覆盖」。 + toggle: if matches!(choice, ConflictChoiceView::Overwrite) { + catalog.text(Key::PackPickRowKeep) + } else { + catalog.text(Key::PackPickRowOverwrite) + }, + } +} + +/// 来源的人读串。 +fn source_label(source: ConflictSourceView, catalog: Catalog) -> &'static str { + match source { + ConflictSourceView::Overrides => catalog.text(Key::PackPickSourceOverrides), + ConflictSourceView::ClientOverrides => catalog.text(Key::PackPickSourceClientOverrides), + ConflictSourceView::CurseForge | ConflictSourceView::Modrinth => { + catalog.text(Key::PackPickSourceManifest) + } + } +} + +/// 成因的人读串（复用导入报告那三句，不另造一套说法）。 +fn reason_label(reason: ConflictReasonView, catalog: Catalog) -> &'static str { + match reason { + ConflictReasonView::UserModified => catalog.text(Key::PackConflictUserModified), + ConflictReasonView::UserDeleted => catalog.text(Key::PackConflictUserDeleted), + ConflictReasonView::PreExisting => catalog.text(Key::PackConflictPreExisting), + } +} 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..35a7e94 --- /dev/null +++ b/crates/app-iced/src/pages/content/packui/model/progress.rs @@ -0,0 +1,125 @@ +//! 阶段与进度：**把导入进度映射成下载页那块面板的入参**（不另画一套进度 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, +} + +/// 细档位说明（`步骤 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, + // 整合包导入的失败不产生内容库分类（它有自己的报告视图）。 + failure_kind: None, + // 导入没有「只重试这些」这条路径（重试整个导入由导入区自己管）。 + retry: Vec::new(), + 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..593051c --- /dev/null +++ b/crates/app-iced/src/pages/content/packui/model/report.rs @@ -0,0 +1,335 @@ +//! 导入结果的视图模型：**三态 + 容忍域逐条 + 致命块**。 +//! +//! ## 为什么容忍域与致命域连字段类型都不同 +//! +//! 任务书：「失败原因逐条展示（能容忍的缺文件与致命错误必须视觉可区分）」。 +//! 只在颜色上区分不够——颜色一关掉（截图/高对比/色弱）就没了。所以： +//! +//! | 域 | 类型 | 画法 | +//! |---|---|---| +//! | 容忍（缺文件 / 被拒 component / 注记） | [`Row`]（路径 + 原因） | 中性容器 + `Info` 图标 + 逐条列表 | +//! | 致命（已回滚） | [`Fatal`]（大类 + 原文 + 建议 + 稳定码） | `ErrorContainer` + `Error` 图标 + 标题换措辞 | +//! +//! 一个 `Option` 与一个 `Vec` 之间没有「误合并」的写法，这比任何样式约定都硬。 + +use unlucky_i18n::{Catalog, Key}; +use unlucky_presenter::dto::{ + ConflictChoiceView, ConflictFileView, ConflictReasonView, ImportCancelView, ImportErrorView, + ImportFailureStageView, 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, + /// 磁盘 SHA-1（`None` = 文件不在） + pub disk_sha1: Option, + /// 展开中（展开才画三方哈希那行） + pub expanded: bool, +} + +/// 致命失败块（**两种措辞，不共用**）。 +/// +/// 为什么不是一句「失败」：`NotStarted`（预检就没过，一个字节都没写）与 `RolledBack` +/// （写进去了，又整包回滚干净）对用户是不同的消息——前者「去修包再试」，后者「刚才动过你的目录， +/// 已经复原」。M161 之前两者共用一句「已回滚 —— 目标目录零残留」，预检失败时那句话是假的。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum FatalKind { + /// 预检/装配阶段失败：目标目录**一个字节都没写** + NotStarted, + /// 写过目标目录，回滚**完整**完成 + RolledBack, + /// 写过，但回滚有失败项（目标目录可能与导入前不同） + RollbackIncomplete, +} + +impl FatalKind { + /// 图标（与 [`Fatal::title`] 各说一遍：颜色/图标关掉时标题仍然分得清）。 + #[must_use] + pub const fn icon(self) -> unlucky_design::icons::IconKind { + match self { + // 预检没过 = 「还没开始」，用警示而不是「已出错」：目录是干净的 + Self::NotStarted => unlucky_design::icons::IconKind::Warn, + Self::RolledBack => unlucky_design::icons::IconKind::Restore, + Self::RollbackIncomplete => unlucky_design::icons::IconKind::Error, + } + } +} + +/// 致命失败块。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Fatal { + /// 三种阶段之一（决定标题/图标/底色） + pub kind: FatalKind, + /// 标题（预检未通过 / 已回滚 / 回滚不完整） + pub title: String, + /// 大类名（`路径穿越` / `清单损坏` …） + pub label: String, + /// 具体是什么 + pub message: String, + /// 稳定码 + pub code: String, + /// 补救建议 + pub hint: Option, +} + +/// 导入结果块。 +#[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, + /// 缺文件标题 + pub missing_title: Option, + /// 缺文件逐条（容忍域） + pub missing: Vec, + /// 冲突标题 + pub conflicts_title: Option, + /// 冲突逐条 + pub conflicts: Vec, + /// 被拒 component 的标题（带计数，与下面逐条行数一致） + pub rejected_title: Option, + /// 被拒 component 逐条 + pub rejected: Vec, + /// 注记逐条 + pub warnings: Vec, + /// 能不能给「以包为准重新导入」（有冲突、且实例可用时才有意义） + pub can_overwrite: bool, + /// 「两者都留改名」为何不支持（有冲突时如实写） + pub overwrite_note: Option, + /// 这次运行与取消的关系（M195 r3：标题与图标按它分档，不许一句打天下） + pub cancel: ImportCancelView, + /// 取消的**补充说明**：只有「取消太晚」有——那种情况标题照常是"已导入/部分成功"， + /// 必须另起一句说清"你的取消没赶上，实例会保留、同名文件可能已被覆盖"。 + pub cancel_note: Option, +} + +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, 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, report.failure_stage, 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()), + cancel: report.cancel, + // 「取消太晚」那句只说给**真的跑完**的导入（复审 r3 P2-1）：推导那边已经保证 + // `Failed` 不会落到 `TooLate`，这里再看一眼状态是双保险——万一推导回归，也不会让 + // 红卡（"零残留"）与"已经跑完、文件可能被覆盖"同时出现在一屏上。 + cancel_note: (report.cancel == ImportCancelView::TooLate + && matches!( + report.status, + ImportStatusView::Success | ImportStatusView::Partial + )) + .then(|| catalog.text(Key::PackCancelTooLate).to_owned()), + } +} + +/// 字节数的人读串。 +fn human(report: &ImportReportView) -> String { + unlucky_presenter::dto::human_bytes(report.bytes_written) +} + +/// 标题：三态 + **失败阶段**（预检未通过 ≠ 已回滚，M161）。 +fn status_title(report: &ImportReportView, catalog: Catalog) -> &'static str { + match report.status { + ImportStatusView::Success => catalog.text(Key::PackStatusSuccess), + ImportStatusView::Partial => catalog.text(Key::PackStatusPartial), + // 三档取消各有各的话：已回滚（什么都没留下）/ 回滚没做完（要对一眼目录）/ + // 取消太晚（标题是真实状态，另有一句 cancel_note 说明"没赶上"）。 + ImportStatusView::Cancelled => match report.cancel { + ImportCancelView::RollbackIncomplete => catalog.text(Key::PackCancelIncomplete), + _ => catalog.text(Key::PackStatusCancelled), + }, + ImportStatusView::Failed => match report.failure_stage { + Some(ImportFailureStageView::NotStarted) => { + catalog.text(Key::PackStatusFailedNotStarted) + } + Some(ImportFailureStageView::RollbackIncomplete) => { + catalog.text(Key::PackStatusFailedIncomplete) + } + // `None` 不该出现（失败必有阶段）；退回「已回滚」这一句是旧行为， + // 只有拿不到阶段时才会走到（例如未来的旧版对端）。 + _ => catalog.text(Key::PackStatusFailed), + }, + } +} + +/// 副标题：包名 · 格式 · 游戏版本 · 加载器（缺哪个就不写哪个，不拼「未知」）。 +fn subtitle(report: &ImportReportView, catalog: Catalog) -> String { + let mut parts: Vec = 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, + stage: Option, + catalog: Catalog, +) -> Fatal { + let kind = match stage { + Some(ImportFailureStageView::NotStarted) => FatalKind::NotStarted, + Some(ImportFailureStageView::RollbackIncomplete) => FatalKind::RollbackIncomplete, + _ => FatalKind::RolledBack, + }; + let title = match kind { + FatalKind::NotStarted => catalog.text(Key::PackFatalTitleNotStarted), + FatalKind::RolledBack => catalog.text(Key::PackFatalTitle), + FatalKind::RollbackIncomplete => catalog.text(Key::PackFatalTitleIncomplete), + }; + Fatal { + kind, + title: title.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..fc8a39c --- /dev/null +++ b/crates/app-iced/src/pages/content/packui/model/tests.rs @@ -0,0 +1,387 @@ +//! 导入/导出区视图模型的守门（M113）：阶段映射、预检计数、三方哈希、容忍/致命分野。 +//! +//! 这里**不测画法**（画法靠出图），测的是「决策」：哪些数字进了哪一行、哪些字段被截短、 +//! 哪一态该出现哪一块。所有断言都能在没有图形环境的情况下跑。 + +mod cancel; +mod pick; +mod stage; + +use std::path::PathBuf; + +use unlucky_i18n::Lang; +use unlucky_presenter::dto::{ + ConflictChoiceView, ConflictFileView, ConflictReasonView, ExportClassView, ExportFileView, + ExportPreviewView, ImportCancelView, 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 = 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) -> 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, + failure_stage: None, + cancel: ImportCancelView::NotRequested, + }; + 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, + failure_stage: None, + cancel: ImportCancelView::NotRequested, + }; + // 「以包为准」只在导入到**已有实例**时给（复审 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, + failure_stage: None, + cancel: ImportCancelView::NotRequested, + }; + + 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, + "导入到已有实例时才给翻档动作" + ); +} diff --git a/crates/app-iced/src/pages/content/packui/model/tests/cancel.rs b/crates/app-iced/src/pages/content/packui/model/tests/cancel.rs new file mode 100644 index 0000000..d051f0f --- /dev/null +++ b/crates/app-iced/src/pages/content/packui/model/tests/cancel.rs @@ -0,0 +1,140 @@ +//! 取消的**三档真实结局**在界面上的分支（M195 r3）。 +//! +//! 口径：一句「已停手并回滚」打天下是假话——取消可能停在提交前（已回滚）、可能停在回滚没收尾 +//! （目标目录可能变了）、也可能**太晚**（管线已经跑完，实例保留、同名文件可能已被覆盖）。 +//! 这一族用例钉的就是"三档各说各的话"，以及"占位文案不再替结局下结论"。 + +use std::path::PathBuf; + +use unlucky_i18n::{Catalog, Key, Lang}; +use unlucky_presenter::dto::{ + ImportCancelView, ImportReportView, ImportStatusView, PackFormatView, +}; + +use super::super::report::report_of; +use super::super::PackPageState; + +fn catalog() -> Catalog { + Lang::En.catalog() +} + +fn report( + status: ImportStatusView, + cancel: ImportCancelView, + rolled_back: bool, +) -> ImportReportView { + ImportReportView { + status, + format: Some(PackFormatView::Multimc), + pack_name: Some("Better MC".to_string()), + pack_version: None, + game_version: Some("1.20.1".to_string()), + loader: None, + version_id: Some("1.20.1".to_string()), + target: PathBuf::from("C:/tmp/instance"), + files: Vec::new(), + conflicts: Vec::new(), + missing: Vec::new(), + rejected: Vec::new(), + warnings: Vec::new(), + error: None, + registered: None, + bytes_written: 0, + rolled_back, + failure_stage: None, + cancel, + } +} + +#[test] +fn a_rolled_back_cancel_says_it_is_cancelled_not_partially_installed() { + // 取消停在提交前：已回滚 ⇒ 标题是「已取消 —— 已回滚」，**不是**「部分成功」（那等于说装了一半）， + // 也不能出现「取消太晚」那句补充说明。 + let view = report( + ImportStatusView::Cancelled, + ImportCancelView::RolledBack, + true, + ); + let block = report_of(&view, &PackPageState::default(), catalog()); + + assert_eq!(block.title, catalog().text(Key::PackStatusCancelled)); + assert_ne!( + block.title, + catalog().text(Key::PackStatusPartial), + "已回滚的取消不许显示成「部分成功」" + ); + assert!(!block.installed(), "取消不是「装上了」"); + assert!(block.cancel_note.is_none(), "已回滚不需要「太晚」那句"); +} + +#[test] +fn an_incomplete_cancel_rollback_says_the_directory_may_differ() { + let view = report( + ImportStatusView::Cancelled, + ImportCancelView::RollbackIncomplete, + false, + ); + let block = report_of(&view, &PackPageState::default(), catalog()); + + assert_eq!(block.title, catalog().text(Key::PackCancelIncomplete)); + assert_ne!( + block.title, + catalog().text(Key::PackStatusCancelled), + "回滚没做完 ≠ 已回滚（这两句话不能混）" + ); +} + +#[test] +fn a_too_late_cancel_says_the_import_already_finished() { + // 取消来得太晚：状态是真实的 `Success`，另加一句「实例会保留、同名文件可能已被覆盖」。 + let view = report(ImportStatusView::Success, ImportCancelView::TooLate, false); + let block = report_of(&view, &PackPageState::default(), catalog()); + + assert_eq!(block.title, catalog().text(Key::PackStatusSuccess)); + assert_eq!(block.status, ImportStatusView::Success); + assert_ne!( + block.status, + ImportStatusView::Cancelled, + "太晚 ≠ 已回滚（状态是真的 Success/Partial）" + ); + assert_eq!( + block.cancel_note, + Some(catalog().text(Key::PackCancelTooLate).to_owned()), + "必须另外说清「取消没赶上」" + ); +} + +/// 三档的标题**互不相同**（把任意两档并成一句，这里就红）。 +#[test] +fn the_three_cancel_outcomes_have_three_different_titles() { + let titles = [ + report_of( + &report( + ImportStatusView::Cancelled, + ImportCancelView::RolledBack, + true, + ), + &PackPageState::default(), + catalog(), + ) + .title, + report_of( + &report( + ImportStatusView::Cancelled, + ImportCancelView::RollbackIncomplete, + false, + ), + &PackPageState::default(), + catalog(), + ) + .title, + report_of( + &report(ImportStatusView::Success, ImportCancelView::TooLate, false), + &PackPageState::default(), + catalog(), + ) + .title, + ]; + let unique: std::collections::BTreeSet<&String> = titles.iter().collect(); + assert_eq!(unique.len(), 3, "三档必须各说各的话：{titles:?}"); +} diff --git a/crates/app-iced/src/pages/content/packui/model/tests/pick.rs b/crates/app-iced/src/pages/content/packui/model/tests/pick.rs new file mode 100644 index 0000000..6fbf08d --- /dev/null +++ b/crates/app-iced/src/pages/content/packui/model/tests/pick.rs @@ -0,0 +1,189 @@ +//! 冲突清单（M160）的视图模型守门：分页、计数、三个入口 → 决策表。 +//! +//! 这里钉的是**不画**的那部分——一屏只出 `PAGE_SIZE` 行、翻页只换数据、计数与最终决策同源。 +//! 画法本身靠出图（`ULL_CONTENT_PACK=pick`）。 + +use std::collections::BTreeMap; + +use super::super::pick::{pick_of, PAGE_SIZE}; +use super::super::PackPageState; +use super::catalog; +use unlucky_presenter::dto::{ + ConflictChoiceView, ConflictDecisionsView, ConflictReasonView, ConflictSourceView, + ImportConflictView, ImportScanView, +}; + +/// `count` 条冲突的预检结果。 +fn scan(count: usize) -> ImportScanView { + ImportScanView { + target: std::path::PathBuf::from("instance"), + format: None, + pack_name: Some("Better MC".to_string()), + pack_version: None, + game_version: None, + conflicts: (0..count) + .map(|index| ImportConflictView { + path: format!("config/row-{index:03}.toml"), + source: ConflictSourceView::Overrides, + reason: ConflictReasonView::PreExisting, + disabled: false, + pack_sha1: "aa".repeat(20), + pack_size: 1_000, + disk_sha1: "bb".repeat(20), + disk_size: 2_000, + base_sha1: None, + }) + .collect(), + unknown_remote: 0, + lost_bytes: 0, + incoming_bytes: 0, + notes: Vec::new(), + error: None, + } +} + +fn pick( + scan: &ImportScanView, + page: usize, + per_item: &BTreeMap, + batch: bool, +) -> super::super::pick::Pick { + pick_of(scan, page, per_item, batch, catalog()).expect("有冲突就该画这一块") +} + +#[test] +fn only_the_current_page_is_drawn() { + let scan = scan(312); + let first = pick(&scan, 0, &BTreeMap::new(), false); + assert_eq!(first.rows.len(), PAGE_SIZE, "一屏只许画一页的行"); + assert_eq!(first.pages, 8, "312 条 / 40 条一页 = 8 页"); + assert_eq!(first.page, 0); + assert!(first.can_next, "还有下一页"); + assert!(!first.can_prev, "第一页没有上一页"); + assert_eq!(first.range, "Items 1-40 of 312"); + assert_eq!(first.rows[0].path, "config/row-000.toml"); + + let second = pick(&scan, 1, &BTreeMap::new(), false); + assert_eq!(second.page, 1); + assert_eq!( + second.rows[0].path, + format!("config/row-{PAGE_SIZE:03}.toml") + ); + assert_eq!(second.range, "Items 41-80 of 312"); + assert!(second.can_prev && second.can_next); +} + +#[test] +fn the_last_page_is_short_and_the_page_number_is_clamped() { + let scan = scan(312); + let last = pick(&scan, 7, &BTreeMap::new(), false); + assert_eq!(last.rows.len(), 312 - 7 * PAGE_SIZE, "最后一页只剩尾巴"); + assert_eq!(last.range, "Items 281-312 of 312"); + assert!(!last.can_next); + + // 页码越界（例如用户先在 300 条的清单上翻到第 6 页，再重扫一份 10 条的）⇒ 夹到最后一页。 + let clamped = pick(&scan, 99, &BTreeMap::new(), false); + assert_eq!(clamped.page, 7); +} + +#[test] +fn the_summary_counts_what_the_user_actually_picked() { + let scan = scan(10); + let keep_all = pick(&scan, 0, &BTreeMap::new(), false); + assert_eq!(keep_all.keep_count, 10); + assert_eq!(keep_all.overwrite_count, 0); + assert!(keep_all.summary.contains("Keep 10"), "{}", keep_all.summary); + assert!(keep_all.keep_all_active && !keep_all.overwrite_all_active); + + let mut per_item = BTreeMap::new(); + per_item.insert( + "config/row-001.toml".to_string(), + ConflictChoiceView::Overwrite, + ); + per_item.insert( + "config/row-004.toml".to_string(), + ConflictChoiceView::Overwrite, + ); + let mixed = pick(&scan, 0, &per_item, false); + assert_eq!(mixed.overwrite_count, 2); + assert_eq!(mixed.keep_count, 8); + // 丢弃量只算"真选了覆盖"的那两条（各 2 000 字节）。 + assert!( + mixed.summary.contains("Overwrite 2") || mixed.summary.contains("overwrite 2"), + "{}", + mixed.summary + ); + assert_eq!( + mixed.rows[1].choice, + ConflictChoiceView::Overwrite, + "点过的那一行要显示成覆盖" + ); + assert_eq!(mixed.rows[0].choice, ConflictChoiceView::KeepUser); + + let all = pick(&scan, 0, &BTreeMap::new(), true); + assert_eq!(all.overwrite_count, 10); + assert!(all.overwrite_all_active && !all.keep_all_active); +} + +#[test] +fn no_conflict_means_no_block() { + let scan = scan(0); + assert!( + pick_of(&scan, 0, &BTreeMap::new(), false, catalog()).is_none(), + "没有冲突就不该画这一屏（不打扰用户）" + ); +} + +#[test] +fn decisions_default_to_keep_all() { + let page = PackPageState::default(); + assert_eq!(page.decisions(None), ConflictDecisionsView::KeepAll); + // 逐项点一个"覆盖" ⇒ 逐项表里只有它，缺省档仍是保留。 + let mut page = PackPageState::default(); + page.pick_choices + .insert("mods/a.jar".to_string(), ConflictChoiceView::Overwrite); + let decisions = page.decisions(Some(&scan(3))); + assert_eq!(decisions.default_choice(), ConflictChoiceView::KeepUser); + assert_eq!(decisions.overwrite_count(), 1); + assert_eq!(decisions.len(), 1); +} + +#[test] +fn batch_overwrite_plus_a_kept_file_is_expressible() { + // 全部覆盖之后单独放回一条：缺省档是覆盖、逐项里那条是保留。 + let mut page = PackPageState { + pick_overwrite_all: true, + ..PackPageState::default() + }; + assert_eq!( + page.decisions(Some(&scan(3))), + ConflictDecisionsView::OverwriteAll, + "只点整批覆盖时不需要逐项表" + ); + page.pick_choices + .insert("mods/pin.jar".to_string(), ConflictChoiceView::KeepUser); + let decisions = page.decisions(Some(&scan(3))); + assert_eq!(decisions.default_choice(), ConflictChoiceView::Overwrite); + assert_eq!(decisions.keep_count(), 1); + assert_eq!(decisions.overwrite_count(), 0); +} + +#[test] +fn toggling_flips_the_row_and_clearing_the_batch_drops_per_item_choices() { + let mut page = PackPageState::default(); + let path = "mods/a.jar"; + assert_eq!(page.pick_choice(path), ConflictChoiceView::KeepUser); + page.pick_choices + .insert(path.to_string(), ConflictChoiceView::Overwrite); + assert_eq!(page.pick_choice(path), ConflictChoiceView::Overwrite); + + // 整批覆盖之后，那条逐项"保留"仍然优先于整批档。 + page.pick_overwrite_all = true; + page.pick_choices + .insert(path.to_string(), ConflictChoiceView::KeepUser); + assert_eq!(page.pick_choice(path), ConflictChoiceView::KeepUser); + assert_eq!( + page.pick_choice("mods/other.jar"), + ConflictChoiceView::Overwrite + ); +} diff --git a/crates/app-iced/src/pages/content/packui/model/tests/stage.rs b/crates/app-iced/src/pages/content/packui/model/tests/stage.rs new file mode 100644 index 0000000..e8582d2 --- /dev/null +++ b/crates/app-iced/src/pages/content/packui/model/tests/stage.rs @@ -0,0 +1,110 @@ +//! M161：导入失败的**两种阶段**不许共用一句话。 +//! +//! 从 `tests.rs` 拆出（那边贴着 400 行硬线）：本文件只守「预检没过（一个字节都没写）」与 +//! 「已回滚」的措辞/图标分野。夹具在父模块（`use super::*`）。 + +use unlucky_presenter::dto::{ImportCancelView, ImportFailureStageView}; + +use super::*; + +/// **「预检没过」与「已回滚」必须各说各的话**（M161 收的债）。 +/// +/// 此前两者共用 `rolled_back: true`，于是预检失败（一个字节都没写）也被写成 +/// 「已回滚 —— 目标目录零残留」——一个没发生的回滚。现在标题、图标、底色三处都分开， +/// 且 `NotStarted` 的标题**不许**出现「回滚 / rolled back」这类词（那才是真正的谎）。 +#[test] +fn the_two_failure_stages_never_share_one_sentence() { + fn failed(stage: Option) -> ImportReportView { + ImportReportView { + status: ImportStatusView::Failed, + format: Some(PackFormatView::Modrinth), + 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::new(), + rejected: Vec::new(), + warnings: Vec::new(), + error: Some(ImportErrorView { + code: "pack_traversal".to_string(), + label: "path traversal".to_string(), + message: "../etc/passwd".to_string(), + hint: None, + }), + registered: None, + bytes_written: 0, + rolled_back: true, + failure_stage: stage, + cancel: ImportCancelView::NotRequested, + } + } + + let zh = Lang::ZhCn.catalog(); + let not_started = report_of( + &failed(Some(ImportFailureStageView::NotStarted)), + &PackPageState::default(), + zh, + ); + let rolled_back = report_of( + &failed(Some(ImportFailureStageView::RolledBack)), + &PackPageState::default(), + zh, + ); + let incomplete = report_of( + &failed(Some(ImportFailureStageView::RollbackIncomplete)), + &PackPageState::default(), + zh, + ); + + // 三种标题互不相同（三态压力：谁把它们折叠回同一句，这里就红）。 + let titles = [ + not_started.title.as_str(), + rolled_back.title.as_str(), + incomplete.title.as_str(), + ]; + assert_eq!( + titles + .iter() + .collect::>() + .len(), + 3, + "三种失败阶段的标题撞了：{titles:?}" + ); + + // 「预检没过」那一句里不许出现「回滚」（那是没发生的事）。 + let fatal = not_started.fatal.expect("致命块"); + assert_eq!( + fatal.kind, + crate::pages::content::packui::model::FatalKind::NotStarted + ); + assert!( + !fatal.title.contains("回滚"), + "预检失败不该说「回滚」：{}", + fatal.title + ); + assert!(!not_started.title.contains("回滚"), "{}", not_started.title); + // 已回滚那一句必须说清「回滚」这件事。 + assert!( + rolled_back.title.contains("回滚"), + "已回滚那句要说明回滚：{}", + rolled_back.title + ); + // 图标分开：预检没过不是「错误」字形（目录没动过），回滚不完整才是。 + assert_ne!( + crate::pages::content::packui::model::FatalKind::NotStarted.icon(), + crate::pages::content::packui::model::FatalKind::RolledBack.icon(), + "两种阶段的图标不许一样" + ); + + // 成功/部分成功没有「失败阶段」可言。 + let mut ok = failed(None); + ok.status = ImportStatusView::Success; + ok.error = None; + assert!(report_of(&ok, &PackPageState::default(), zh) + .fatal + .is_none()); +} 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..41fd2a4 --- /dev/null +++ b/crates/app-iced/src/pages/content/packui/tests.rs @@ -0,0 +1,134 @@ +//! 导入/导出区的守门（M113）：四种出图态都装得满、入口文案都在。 +//! +//! 出图（D30）靠这几条夹具：任何一态装不满，截图就会是一块空容器，而不是「有话说」的界面。 +//! 视图模型的判定在 `model/tests.rs`，这里只管**夹具本身**。 + +use unlucky_i18n::Lang; + +use super::demo::pack_in; +use super::model::Pack; + +/// 出图态：导入中 / **导入前冲突清单（M160）** / 部分成功 / 导入后冲突账 / 导出预检。 +const STATES: [&str; 5] = ["importing", "pick", "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 the_pick_state_shows_a_paginated_conflict_list() { + // M160 的那一屏：只画一页、三个入口都在、计数与逐项状态一致。 + let (model, page) = pack_in("pick", Lang::En); + let pick = model.pick.expect("pick 态必须有冲突清单"); + // 一屏只画一页：行数上限来自 `model::pick::PAGE_SIZE`（40）。 + assert_eq!(pick.rows.len(), 40, "一屏一页（PAGE_SIZE）"); + assert_eq!(pick.pages, 8, "312 条 / 40 条一页"); + assert_eq!(pick.page, 1, "夹具停在第 2 页（0 起）"); + assert!(pick.can_prev && pick.can_next); + assert_eq!(pick.overwrite_count, 2, "夹具逐项点了两条覆盖"); + assert!( + pick.keep_all_active && !pick.overwrite_all_active, + "整批档停在缺省那一档（全部保留）" + ); + assert_eq!( + pick.rows[0].choice, + unlucky_presenter::dto::ConflictChoiceView::KeepUser, + "没点过的那一行必须是保留" + ); + // 页面自留的选择与模型一致（逐项那条显示成覆盖） + assert_eq!( + page.pick_choice("config/generated/module-041.toml"), + unlucky_presenter::dto::ConflictChoiceView::Overwrite + ); +} + +#[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..b98126d --- /dev/null +++ b/crates/app-iced/src/pages/content/packui/view.rs @@ -0,0 +1,263 @@ +//! 导入/导出区的画法：入口（拖拽 + 路径）→ 进度（**下载页那块面板**）→ 结果 → 导出预检。 +//! +//! ## 版面 +//! +//! ```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 pick; +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::pick::pick_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(pick) = &model.pick { + // 冲突清单优先于一切：用户此刻要做的决定就是"哪几个文件覆盖" + block = block.push(pick_block(ui, catalog, pick)); + } 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 { + // 取消过、**结果还没回来**：先留一句"正在停手"的占位（真实结局随后的报告给出， + // 已回滚 / 回滚没做完 / 取消太晚三档见 `model::report`） + 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> = 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::>()) + .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> { + 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::>(), + ) + .spacing(ui.space(Space::X1)) + .width(Length::Fill) + .into() +} + +/// 逐条列表的**有界**容器：条目多时给一个固定高度的滚动区。 +/// +/// 为什么必须要有界：这一块长在内容库页正列的上方，而整页没有滚动（只有结果列表自己滚）⇒ +/// 报告一长，「关闭 / 以包为准重新导入 / 确认写盘」这些动作就被顶出屏幕。出图时实测到了这一点 +/// （冲突态与导出预检态的动作按钮落在 900px 以下）。 +/// +/// 少于 `rows_threshold` 条时直接铺开：给两行内容套一个 120px 的空框，比溢出更难看。 +pub(super) fn bounded<'a>( + ui: &'a Ui, + content: impl Into>, + 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/pick.rs b/crates/app-iced/src/pages/content/packui/view/pick.rs new file mode 100644 index 0000000..17d86cf --- /dev/null +++ b/crates/app-iced/src/pages/content/packui/view/pick.rs @@ -0,0 +1,311 @@ +//! 冲突清单那一屏的画法（M160）：**分页** + 三个入口 + 计数摘要 + 确认/取消。 +//! +//! ## 版面 +//! +//! ```text +//! ┌ 导入前：有 312 个文件已存在且内容不同 ───────────────┐ +//! │ 保留 309 · 覆盖 3 · 覆盖将丢弃 2.4 MB │ +//! │ 没有改动的一律按「保留」：… │ +//! │ [全部保留我的] [全部覆盖] │ +//! ├ 第 1-40 项，共 312 项 [上一页] [下一页] │ +//! │ config/sodium-options.json 包内 overrides/ · 本来就在 │ +//! │ 你的：4.1 KB · 包内：3.8 KB [覆盖]│ +//! │ …（**只画当前这一页**） │ +//! ├ [按这些选择导入] [取消导入] │ +//! └─────────────────────────────────────────────────────┘ +//! ``` +//! +//! ## 三处「不误导」 +//! +//! 1. **缺省说明写在按钮下面**：用户不必猜"没点过的那 309 条会怎样"； +//! 2. **计数摘要里的丢弃量只算真选了覆盖的**：用最坏数字吓人不算如实； +//! 3. **按钮写的是"点了会变成什么"**（当前保留 ⇒ 按钮写「覆盖」），所以点一下就知道后果。 +//! +//! ## 为什么分页而不是滚动 +//! +//! 几千条冲突一次画完 = 几千个 widget：布局与滚动都卡。分页把 widget 数量钉在 +//! [`super::super::model::PAGE_SIZE`] 条以内，翻页只是换数据。 + +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_i18n::Catalog; + +use crate::app::components::buttons::{self, Button}; +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::{Pick, PickRow}; +use super::super::PackMessage; +use super::intent; + +/// 处置按钮槽的宽度（px）：取最宽状态「⟳ Overwrite」的实际占用再留余量， +/// 保证「Keep」与「Overwrite」两种状态的右边缘落在同一条线上。 +const TOGGLE_SLOT: f32 = 132.0; + +/// 整块。 +pub(super) fn pick_block<'a>( + ui: &'a Ui, + catalog: Catalog, + pick: &'a Pick, +) -> Element<'a, PageMessage> { + let mut block = column![ + frame::text_role( + ui, + TypeRole::TitleSmall, + true, + pick.title.as_str(), + ui.color(Role::OnSurface), + ), + // 计数摘要：这是"我要丢掉多少"的唯一一处数字，用强调色 + frame::text_role( + ui, + TypeRole::BodyMedium, + true, + pick.summary.as_str(), + ui.color(Role::Primary), + ), + frame::text_role( + ui, + TypeRole::BodySmall, + false, + pick.default_note, + ui.color(Role::OnSurfaceVariant), + ), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill); + + if let Some(note) = &pick.unknown_note { + block = block.push( + row![ + frame::glyph(IconKind::Warn, ui.color(Role::Tertiary), frame::ICON_PX), + frame::text_role( + ui, + TypeRole::BodySmall, + false, + note.as_str(), + ui.color(Role::Tertiary), + ), + ] + .spacing(ui.space(Space::X1)) + .align_y(Alignment::Center), + ); + } + + // 三个入口：整批保留 / 整批覆盖（逐项就是下面每行那个按钮） + block = block.push( + row![ + chip( + ui, + Chip::filter( + pick.keep_all, + pick.keep_all_active, + intent(PackMessage::PickKeepAll), + ), + ), + chip( + ui, + Chip::filter( + pick.overwrite_all, + pick.overwrite_all_active, + intent(PackMessage::PickOverwriteAll), + ), + ), + ] + .spacing(ui.space(Space::X2)), + ); + + // 分页头（当前页之外的行一律不画） + block = block.push(bounded( + column( + std::iter::once(pager(ui, catalog, pick)) + .chain(pick.rows.iter().map(|item| pick_row(ui, item))) + .collect::>(), + ) + .spacing(ui.space(Space::X1)) + .width(Length::Fill), + 375.0, + )); + + // 列表与动作行之间留出与其它区块一致的呼吸（复审 r1 视觉 2）：滚到底时最后一行会紧贴 + // 动作行，靠这层 padding 把两者分开（直接调列 spacing 会把行间距也一起拉开）。 + block = block.push( + container( + row![ + buttons::filled( + ui, + Button::new(pick.confirm.as_str(), intent(PackMessage::ConfirmImport)) + .leading(IconKind::Check), + ), + buttons::text( + ui, + Button::new(pick.cancel, intent(PackMessage::CancelImport)), + ), + ] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Center), + ) + .padding(Padding { + top: ui.space(Space::X2), + ..Padding::ZERO + }), + ); + + container(block) + .width(Length::Fill) + .padding(ui.space(Space::X3)) + .style(move |_theme| container::Style { + border: Border { + color: ui.color(Role::Outline), + width: 1.0, + radius: ui.radius_dp(ShapeScale::Large), + }, + background: Some(Background::Color(ui.color(Role::Surface))), + ..container::Style::default() + }) + .into() +} + +/// 分页头：区间 + 上一页 / 下一页。 +fn pager<'a>(ui: &'a Ui, _catalog: Catalog, pick: &'a Pick) -> Element<'a, PageMessage> { + let previous = if pick.can_prev { + buttons::text( + ui, + Button::new( + pick.prev, + intent(PackMessage::PickPage(pick.page.saturating_sub(1))), + ) + .leading(IconKind::ChevronDown), + ) + } else { + // 到边了就把按钮指回当前页（点了不动的死按钮比"没有按钮"更让人困惑） + buttons::text( + ui, + Button::new(pick.prev, intent(PackMessage::PickPage(pick.page))), + ) + }; + let next = if pick.can_next { + buttons::text( + ui, + Button::new(pick.next, intent(PackMessage::PickPage(pick.page + 1))) + .leading(IconKind::ChevronDown), + ) + } else { + buttons::text( + ui, + Button::new(pick.next, intent(PackMessage::PickPage(pick.page))), + ) + }; + // 分页行与行内控件共用同一条右锚点（复审 r1 视觉 3）：区间文案靠左，两个按钮用 + // `horizontal_space` 顶到右边，于是「Previous · Next」的右边缘与下面每一行的处置槽对齐。 + // 两个按钮进一个**右对齐的槽**，槽的右边缘就是行的右边缘 —— 于是它们的右端与下面每行的 + // 处置槽落在同一条线上（按钮自身的内边距也一起对齐，不会差那十几像素）。 + let buttons_slot = container( + row![previous, next] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Center), + ) + .width(Length::Fixed(TOGGLE_SLOT * 2.0)) + .align_x(Alignment::End); + row![ + frame::text_role( + ui, + TypeRole::LabelMedium, + false, + pick.range.as_str(), + ui.color(Role::OnSurfaceVariant), + ), + iced::widget::Space::new().width(Length::Fill), + buttons_slot, + ] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Center) + .width(Length::Fill) + .into() +} + +/// 一条冲突：**第一行**路径 + 处置按钮，**第二行**来源 · 成因 · 两侧体积。 +/// +/// 为什么两行：单行里塞四个字段（路径 / 来源 / 体积 / 按钮）会把路径压成一条窄柱， +/// 出图实测每行折成四五段——扫读成本比两行高得多。 +fn pick_row<'a>(ui: &'a Ui, item: &'a PickRow) -> Element<'a, PageMessage> { + // 两种取值都是**同一种几何**（等高的 pill），只是填充不同： + // · 当前=覆盖 ⇒ **tonal 填充**（这一行会被盖掉，是"待反悔"的那一档） + // · 当前=保留 ⇒ **描边**（缺省档；点了才会覆盖） + // 两种 pill 再各自右对齐进同宽度的槽，于是**右边缘落在同一条线**（复审 r1 视觉 1 的必修项）—— + // 之前一边是描边 pill、一边是无容器的文字按钮，宽窄与右端都不一致。 + let toggle = if item.overwrites() { + buttons::tonal( + ui, + Button::new( + item.toggle, + intent(PackMessage::TogglePick(item.path.clone())), + ) + .leading(IconKind::Refresh), + ) + } else { + buttons::outlined( + ui, + Button::new( + item.toggle, + intent(PackMessage::TogglePick(item.path.clone())), + ) + .leading(IconKind::Refresh), + ) + }; + // 路径那半列必须自己吃掉剩余宽度（`Length::Fill`），否则处置槽会紧跟文字、离右边缘一大截， + // 与分页行的右锚点对不上（出图实测：行内按钮停在 x≈680、分页按钮在 x≈780）。 + let path_slot = container(frame::text_role( + ui, + TypeRole::BodySmall, + false, + item.path.as_str(), + ui.color(Role::OnSurface), + )) + .width(Length::Fill); + // 处置按钮自己那一格：定宽 + 右对齐 ⇒ 两种取值的 pill 右边缘落在同一条线上。 + // 右侧再留 8dp：滚动条就贴在内容右边缘（出图实测 x≈791），pill 紧贴着它显得挤。 + let toggle_slot = container(toggle) + .width(Length::Fixed(TOGGLE_SLOT)) + .align_x(Alignment::End) + .padding(Padding { + right: ui.space(Space::X2), + ..Padding::ZERO + }); + let head = row![path_slot, toggle_slot] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Center) + .width(Length::Fill); + + let detail = frame::text_role_owned( + ui, + TypeRole::BodySmall, + false, + format!("{} · {} · {}", item.source, item.reason, item.sizes), + ui.color(Role::OnSurfaceVariant), + ); + + column![head, detail] + .spacing(ui.space(Space::X1)) + .width(Length::Fill) + .into() +} + +/// 有界容器：内容多时自己滚（与结果块的 `bounded` 同一条口径，但这里限高不同）。 +fn bounded<'a>( + content: impl Into>, + height: f32, +) -> Element<'a, PageMessage> { + iced::widget::scrollable(container(content).width(Length::Fill)) + .height(Length::Fixed(height)) + .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..5266371 --- /dev/null +++ b/crates/app-iced/src/pages/content/packui/view/report.rs @@ -0,0 +1,330 @@ +//! 结果块：三态标题 + 容忍域逐条 + 冲突逐条 + 致命块。 + +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, FatalKind, 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), + ), + // 「取消太晚」的那句补充说明（标题仍是真实的 `已导入 / 部分成功`）。 + frame::text_role( + ui, + TypeRole::BodySmall, + false, + report.cancel_note.as_deref().unwrap_or(""), + ui.color(Role::Tertiary), + ), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill); + + if let Some(fatal) = &report.fatal { + // 三种阶段各自的底色/图标：预检没过用 `SecondaryContainer`（**不是错的颜色**—— + // 目标目录一个字节都没写，没什么可修的残留），已回滚用 `ErrorContainer`， + // 回滚不完整留 `ErrorContainer`（它才是真的要对一眼目录的状态）。 + let (role, on_role) = match fatal.kind { + FatalKind::NotStarted => (Role::SecondaryContainer, Role::OnSecondaryContainer), + _ => (Role::ErrorContainer, Role::OnErrorContainer), + }; + block = block.push(marker_box( + ui, + role, + row![ + frame::glyph(fatal.kind.icon(), ui.color(on_role), frame::ICON_PX), + column![ + frame::text_role( + ui, + TypeRole::LabelLarge, + true, + fatal.title.as_str(), + ui.color(on_role), + ), + frame::text_role_owned( + ui, + TypeRole::BodyMedium, + false, + format!("{} · {}", fatal.label, fatal.code), + ui.color(on_role), + ), + frame::text_role( + ui, + TypeRole::BodySmall, + false, + fatal.message.as_str(), + ui.color(on_role), + ), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill), + ] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Start), + )); + 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::>() + ) + .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 { + use unlucky_presenter::dto::{ImportCancelView, ImportStatusView}; + match report.status { + ImportStatusView::Success => IconKind::Check, + ImportStatusView::Partial => IconKind::Warn, + ImportStatusView::Failed => IconKind::Error, + // 取消**不是错误**（M195）：停手用「关闭（叉）」这个描边字形（页面骨架只允许描边， + // 令牌层的 Play/Stop/More 是填充字形，见 `tests/no_hardcoded_tokens.rs` 的守门）， + // 回滚没做完才升级成 Warn，都不上红。 + ImportStatusView::Cancelled => match report.cancel { + ImportCancelView::RollbackIncomplete => IconKind::Warn, + _ => IconKind::Close, + }, + } +} + +pub(super) fn status_role(report: &Report) -> Role { + use unlucky_presenter::dto::{ImportCancelView, ImportStatusView}; + match report.status { + ImportStatusView::Success => Role::Primary, + ImportStatusView::Partial => Role::Tertiary, + ImportStatusView::Failed => Role::Error, + // 取消一档也不做成 `Role::Error`：用户自己点的，不该看起来像装坏了。 + ImportStatusView::Cancelled => match report.cancel { + ImportCancelView::RollbackIncomplete => Role::Tertiary, + _ => Role::OnSurfaceVariant, + }, + } +} 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..0d846ce --- /dev/null +++ b/crates/app-iced/src/pages/content/parts.rs @@ -0,0 +1,242 @@ +//! 内容库页的零件：筛选条 / 结果列表 / 详情面板 / 四态（加载 / 空 / 失败 / 无更多）/ 一级切换。 +//! +//! 全是既有真组件（`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::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}; + +mod detail; +mod filters; +mod retry; + +pub(crate) use detail::detail; +pub(crate) use filters::{filters, labelled}; +pub(crate) use retry::maybe as retry_panel; + +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() +} + +/// 结果列表。 +/// +/// 两档（M161，判据同 [`super::layout::BodyMode`]）： +/// +/// * `mode.list_scrolls()`：列表**自己滚**（筛选条常驻，高窗口的常态）； +/// * 否则：行按自然高度铺开，滚动交给外层主列——矮窗口里一行 `ListItem` 不许被压成半行。 +pub(super) fn list<'a>( + ui: &'a Ui, + catalog: Catalog, + model: &'a Content, + rails: Rails, + mode: super::layout::BodyMode, +) -> Element<'a, PageMessage> { + let rows = column( + model + .hits + .iter() + .map(|hit| hit_row(ui, model, hit)) + .collect::>(), + ) + .spacing(ui.space(ROW_GAP)) + .padding(Padding::from([0.0, ui.space(Space::X2)])) + .width(Length::Fill); + + let _ = catalog; + let inner: Element<'a, PageMessage> = if mode.list_scrolls() { + 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)), + ) + .height(Length::Fill) + .into() + } else { + // 自然高度（不给 `Fill`）：外层主列的那个滚动条负责滚。 + rows.into() + }; + container(inner) + .width(Length::Fixed(rails.list)) + .height(if mode.list_scrolls() { + Length::Fill + } else { + Length::Shrink + }) + .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), + ) +} + +/// 内容类型 → 图标（**借用**现有字形：图标集里还没有「整合包/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), + } +} + +mod status; + +pub(crate) use status::status_body; 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..e969276 --- /dev/null +++ b/crates/app-iced/src/pages/content/parts/detail.rs @@ -0,0 +1,212 @@ +//! 详情面板：选中项的支持范围 + 目标实例 + 装入（不兼容时**禁用并逐条给原因**）。 +//! +//! 从 `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)); + + // M162：可用版本（详情通道拉的；最多画 5 行——列表页负责「多」，这里只负责「有哪些」） + if model.available_versions.is_empty() { + if let Some(note) = model.versions_note.as_deref() { + body = body.push(frame::text_role( + ui, + TypeRole::BodySmall, + false, + note, + ui.color(Role::OnSurfaceVariant), + )); + } + } else { + let count = model.available_versions.len().to_string(); + let mut versions = column![frame::text_role_owned( + ui, + TypeRole::LabelMedium, + true, + catalog.render(Key::ContentDetailVersionCount, &[("count", count.as_str())]), + ui.color(Role::OnSurfaceVariant), + )] + .spacing(ui.space(Space::X1)); + for version in model.available_versions.iter().take(5) { + versions = versions.push(frame::text_role( + ui, + TypeRole::BodySmall, + false, + version.line.as_str(), + ui.color(Role::OnSurfaceVariant), + )); + } + body = body.push(versions); + } + + // 目标实例：一行 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::>() + .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..93f1264 --- /dev/null +++ b/crates/app-iced/src/pages/content/parts/filters.rs @@ -0,0 +1,167 @@ +//! 筛选条：来源 / 排序 / 游戏版本 / 加载器四组 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`（[`wrapped_row`]）：**不做自动换行**——屏幕太窄时 chip 会被裁掉， +/// 而不是折到第二行（`row` 没有 wrap 能力）。这是既定行为，别把这条注释读成「会自动换行」； +/// 宽度由列表列下限 424（[`super::layout::compact_min`]）兜住，正常窗口下不会撞到。 +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> { + 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` → 一行（顺序就是声明顺序）。 +pub(crate) fn wrapped_row<'a>( + ui: &'a Ui, + chips: Vec>, +) -> Element<'a, PageMessage> { + row(chips) + .spacing(ui.space(Space::X1)) + .align_y(Alignment::Center) + .into() +} diff --git a/crates/app-iced/src/pages/content/parts/retry.rs b/crates/app-iced/src/pages/content/parts/retry.rs new file mode 100644 index 0000000..7b7c750 --- /dev/null +++ b/crates/app-iced/src/pages/content/parts/retry.rs @@ -0,0 +1,140 @@ +//! 安装失败后的「只重试这些」面板（M191）。 +//! +//! ## 为什么这块画在内容库，而不是复用下载页那块失败面板 +//! +//! 下载页的失败面板讲的是「停在哪一步 + 打开日志」，而这里要讲的是**哪几项没装上、属于哪种 +//! 没装上、以及能不能只重试它们**。两件事混在一个块里会得到「失败 + 一堆条目 + 两个关闭」。 +//! 所以：有可重试名单时（[`RetryPanel::of`] 给了 `Some`）这块**顶替**通用失败面板， +//! 一屏只有一个失败块。 +//! +//! ## 三个控件行为 +//! +//! | 控件 | 消息 | 落点 | +//! |---|---|---| +//! | 只重试这 N 个 | [`ContentMessage::RetryFailed`] | `AppCommand::InstallContent{retry: true}`（host 只重解失败项） | +//! | 关闭 | [`PageMessage::CancelInstall`] | 清 install 快照（对没在跑的安装是安全 no-op，与下载页同一个出口） | +//! +//! 两个按钮都**按不动就不画**：没有名单时整块不存在（不是画一个灰按钮）。 + +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::theme::Ui; + +use super::super::model::{Content, RetryPanel}; +use super::intent; +use crate::pages::content::Message as ContentMessage; +use crate::pages::frame; +use crate::pages::Message as PageMessage; + +/// 整块面板（`model.retry` 为 `None` 时调用方不该调它——判据在模型里，不在这里）。 +pub(crate) fn retry_panel<'a>( + ui: &'a Ui, + catalog: Catalog, + panel: &'a RetryPanel, +) -> Element<'a, PageMessage> { + let head = row![ + frame::glyph(IconKind::Error, ui.color(Role::Error), frame::ICON_PX), + frame::text_role( + ui, + TypeRole::TitleSmall, + true, + panel.title.as_str(), + ui.color(Role::Error), + ), + ] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Center); + + let mut body = column![head] + .spacing(ui.space(Space::X2)) + .width(Length::Fill); + + // 两档分成两段：**各自的标题 + 各自的条目**（合并成一段就说不出「换版本还是检查网络」）。 + // 条目之间用 ASCII 逗号：项目键是站点数据，句读不是文案，不该在这里挑中文的「、」。 + for group in &panel.groups { + let items = group.items.join(", "); + body = body.push( + column![ + frame::text_role( + ui, + TypeRole::LabelMedium, + true, + catalog.text(group.title), + ui.color(Role::OnErrorContainer), + ), + frame::text_role_owned( + ui, + TypeRole::BodySmall, + false, + items, + ui.color(Role::OnErrorContainer), + ), + ] + .spacing(ui.space(Space::X1)), + ); + } + + body = body.push(frame::text_role( + ui, + TypeRole::BodySmall, + false, + catalog.text(Key::ContentInstallRetryHint), + ui.color(Role::OnErrorContainer), + )); + + let actions = row![ + // 主按钮：只重试这些（这个块存在的**唯一**理由） + buttons::filled( + ui, + Button::new(panel.action.as_str(), intent(ContentMessage::RetryFailed)) + .leading(IconKind::Refresh), + ), + buttons::text( + ui, + // 复用下载页那条现有的「关闭」：同一句话不另立一条要同步的 key（r1 复审 N2） + Button::new( + catalog.text(Key::DownloadDismiss), + PageMessage::CancelInstall + ), + ), + ] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Center); + + body = body.push(actions); + + container(body) + .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() +} + +/// 整页底部那块（判据在 [`Content::retry`]；`None` ⇒ 一帧都不画）。 +pub(crate) fn maybe<'a>( + ui: &'a Ui, + catalog: Catalog, + model: &'a Content, +) -> Option> { + model + .retry + .as_ref() + .map(|panel| retry_panel(ui, catalog, panel)) +} diff --git a/crates/app-iced/src/pages/content/parts/status.rs b/crates/app-iced/src/pages/content/parts/status.rs new file mode 100644 index 0000000..79bad48 --- /dev/null +++ b/crates/app-iced/src/pages/content/parts/status.rs @@ -0,0 +1,200 @@ +//! 内容库页的**状态层**：加载 / 空 / 失败 / 未联网 / 状态分派。 +//! +//! 从 `parts.rs` 拆出（M161 合入后那份越过了 400 行；状态层本来就是「一屏只有一个」的 +//! 独立东西，拆开后 `parts.rs` 只剩筛选条与列表）。四态各一支，判据在 +//! `model::Status`，这里只负责画。 +//! +//! **未联网（M162）与失败是两屏**：前者说「要么联网、要么真的没有」，后者说「拉取失败了」。 + +use iced::widget::{column, container, 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::feedback::{empty_state, EmptyState}; +use crate::theme::Ui; + +use super::super::model::{Content, Status}; +use super::intent; +use crate::pages::content::Message as ContentMessage; +use crate::pages::frame; +use crate::pages::Message as PageMessage; + +pub(crate) 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(crate) 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(crate) 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> { + container(content) + .width(Length::Fill) + .height(Length::Fill) + .align_x(Alignment::Center) + .align_y(Alignment::Center) + .into() +} + +/// 未联网态（M162）：与失败态同一套骨架，只是说清「要么联网、要么真的没有」这件事。 +pub(crate) fn offline<'a>( + ui: &'a Ui, + catalog: Catalog, + reason: &'a str, +) -> Element<'a, PageMessage> { + centered( + column![ + row![ + frame::glyph( + IconKind::Warn, + ui.color(Role::OnSurfaceVariant), + frame::ICON_PX + ), + frame::text_role( + ui, + TypeRole::TitleSmall, + true, + catalog.text(Key::ContentOfflineTitle), + ui.color(Role::OnSurface) + ), + ] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Center), + frame::text_role( + ui, + TypeRole::BodySmall, + false, + catalog.text(Key::ContentOfflineBody), + ui.color(Role::OnSurfaceVariant) + ), + frame::text_role( + ui, + TypeRole::BodySmall, + false, + reason, + ui.color(Role::OnSurfaceVariant) + ), + buttons::outlined( + ui, + Button::new( + catalog.text(Key::ContentRetry), + intent(ContentMessage::Retry) + ) + .leading(IconKind::Refresh), + ), + ] + .spacing(ui.space(Space::X2)) + .align_x(Alignment::Center), + ) +} + +/// 状态分派（四态各一支；`Ready` 由调用方画列表 + 详情）。 +pub(crate) fn status_body<'a>( + ui: &'a Ui, + catalog: Catalog, + model: &'a Content, +) -> Option> { + 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())), + // M162：未联网不是「没有结果」，也不是普通失败——单独一屏（标题/正文/图标都不同） + Status::Offline(reason) => Some(offline(ui, catalog, reason.as_str())), + Status::Ready => None, + } +} 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..1555846 --- /dev/null +++ b/crates/app-iced/src/pages/content/tests.rs @@ -0,0 +1,119 @@ +//! 内容库页的守门（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() + ); + } +} + +/// M191：「全部成功」那一屏（默认态）**没有**重试面板——出图与判据同源，不是手搓的。 +#[test] +fn the_default_demo_screen_has_no_retry_surface() { + for kind in ContentKind::ALL { + let model = demo(kind, Lang::En); + assert!( + model.retry.is_none(), + "{} 默认态不该有重试面板", + kind.slug() + ); + } +} + +/// M229 复审 F3 的回归门：页头一级切换的选中态由**调用方所在页**决定，不是写死「内容库」。 +/// +/// 抓得住：`download.rs` 又传回 `true`（下载页页头的「内容库」被画成选中，正是 F3 的现场）。 +/// 抓不住：像素长什么样（那要截图）；iced 的 `Element` 不可内省，所以这条从源码层面钉住调用点—— +/// 判据只有一行，读的人也不会误解。 +#[test] +fn the_download_header_marks_versions_selected_not_content() { + let download = include_str!("../download.rs"); + assert!( + download.contains("section_switcher(ui, catalog, false)"), + "下载页是「版本管理」那一侧，必须传 false（传 true = F3 复发）" + ); + let content_view = include_str!("view.rs"); + assert!( + content_view.contains("section_switcher(ui, catalog, true)"), + "内容库页自己那一份必须传 true" + ); +} 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..133a1e7 --- /dev/null +++ b/crates/app-iced/src/pages/content/view.rs @@ -0,0 +1,270 @@ +//! 内容库页的整页装配：页头（含一级切换）+ 左侧类型栏 + 主列（筛选/结果）+ 详情 + 安装面板。 +//! +//! ## 版面（几何在 [`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, + window_height: f32, +) -> Element<'a, PageMessage> { + let catalog = lang.catalog(); + // 正文可用高 → 版面两档（`Split`：列表自己滚；`ScrollWhole`：主列整列一个滚动条）。 + // 门槛与判据在 [`content_layout`] 里，那里有用例钉住「不算拍脑袋的数」。 + let body_height = frame::body_height(ui, metrics, window_height, true); + let mode = content_layout::BodyMode::of(body_height); + 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, mode)) +} + +fn body<'a>( + ui: &'a Ui, + metrics: FrameMetrics, + catalog: Catalog, + model: &'a Content, + mode: content_layout::BodyMode, +) -> 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, mode) + ] + .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, mode)); + 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); + // M191：有可重试的失败项时，这块**顶替**下载页那块通用失败面板（一屏只有一个失败块）； + // 没有名单时它连构造都不存在（`None`），不是画一个灰按钮。 + let retry = parts::retry_panel(ui, catalog, model); + if let Some(panel) = retry { + stack = stack.push(divider::full(ui)).push(panel); + } else 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() +} + +/// 主列：搜索条 + 筛选 + 计数 + 结果（或四态之一）。 +/// +/// `mode` 决定**谁滚**（M161，判据在 `content_layout::BodyMode`）： +/// +/// * `Split`：列表自己滚（筛选条常驻，高窗口的常态）； +/// * `ScrollWhole`：矮窗口——主列（含搜索条与筛选）整列进**一个**纵向滚动区，列表按自然高度铺开。 +/// 这样一行 `ListItem` 不会被压成半行（那看起来就是「折行挤压」），也不会出现「列表里一个滚动条、 +/// 外层又一个」的双滚动。 +fn main_column<'a>( + ui: &'a Ui, + catalog: Catalog, + model: &'a Content, + rails: Rails, + mode: content_layout::BodyMode, +) -> 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, mode)] + .spacing(ui.space(Space::X2)) + .width(Length::Fill); + // 列表高度：`Split` 吃掉剩余高度（自己滚）；`ScrollWhole` 按内容铺开（外层滚）。 + list = if mode.list_scrolls() { + list.height(Length::Fill) + } else { + list.height(Length::Shrink) + }; + // 紧凑档没有独立详情列：详情压在列表下面（整页替换的成本比「多一块」高） + 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() + }; + + // `ScrollWhole` 档：主列整列一个滚动区（列表按自然高度）。**只有这一处**加滚动条， + // 不在列表里再套一个（双滚动是「到处加滚动条糊」的典型症状）。 + let mut column = column![] + .spacing(ui.space(Space::X2)) + .width(Length::Fixed(rails.list)); + + // M113: import/export —— 只有整合包这一类才有「把本地的包装进来 / 把实例打出去」。 + // 其它三类（Mod / 资源包 / 光影）的导入就是把文件拖进目录，不属于本条任务。 + if model.kind == ContentKind::Modpack { + column = column + .push(super::packui::section(ui, catalog, &model.pack)) + .push(divider::full(ui)); + } + + column = column.push(head).push(body); + if mode.list_scrolls() { + return column.height(Length::Fill).into(); + } + iced::widget::scrollable(column.height(Length::Shrink)) + .direction(iced::widget::scrollable::Direction::Vertical( + iced::widget::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() +} + +/// 详情列（只在 `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..598176f --- /dev/null +++ b/crates/app-iced/src/pages/download.rs @@ -0,0 +1,272 @@ +//! **版本管理页**（原下载页）：三栏版面 —— 版本类型 / 主版本 / 列表 + 安装面板。 +//! +//! 用户令（信息架构调整）把这一页从「下载」改称「版本管理」：下载页只负责整合包与 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`，它不需要也不该认识 `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 { + 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`）；页面自己不读全局、不猜语言。 +/// 四参数的 [`view_sized`]：给**用不到窗口高度**的调用方（只有单测；产品路径走 +/// `pages::view` → [`view_sized`]，所以这条在非 test 构建里是死代码，`#[cfg(test)]` 收口）。 +#[cfg(test)] +pub fn view<'a>( + ui: &'a Ui, + metrics: FrameMetrics, + model: &'a Download, + lang: Lang, +) -> Element<'a, Message> { + view_sized(ui, metrics, model, lang, 760.0) +} + +/// 同 [`view`]，但显式给**窗口高度**（版本列表要按整行取高，见 [`rows::TailShare::list_height`]）。 +pub fn view_sized<'a>( + ui: &'a Ui, + metrics: FrameMetrics, + model: &'a Download, + lang: Lang, + window_height: f32, +) -> 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` 到达。 + // 本页是「版本管理」那一侧：`on_content = false`（传 true 会让「内容库」画成选中， + // 这正是 M229 复审 F3 的现场）。 + .action(content::section_switcher(ui, catalog, false)) + .action(buttons::text( + ui, + Button::new( + catalog.text(Key::DownloadRefresh), + Message::Action(Action::RefreshSources), + ), + )); + + // 正文列高度 = 窗口 − 标题栏 − 页头 − 上下页边距（唯一来源 [`frame::body_height`]）。 + // 版本列表要按**整行**取高，就得知道这一块有多高（D30 r2 S1b/S9）。 + let body_height = frame::body_height(ui, metrics, window_height, true); + frame::page( + ui, + metrics, + header, + body(ui, metrics, catalog, model, body_height), + ) +} + +/// 正文：加载态仍是居中占位；其余状态都长在三栏骨架上。 +fn body<'a>( + ui: &'a Ui, + metrics: FrameMetrics, + catalog: Catalog, + model: &'a Download, + body_height: f32, +) -> 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, body_height) + } else { + // 三栏不成立（可用宽 < 600）：类型与主版本原样退回顶部 chips，列表吃掉整条可用宽。 + // 高度分法跟着档位走：chips 档多花两行 chip，面板必须收回自己的预算（M125 缺陷 1）。 + // M227：这一档也改成「面板先保预算、列表按整行吃剩下的」——预算比三栏档紧得多 + // （`rows::CHIPS_PANEL_BUDGET` 192 vs 三栏档的 `rows::panel_budget`），清单见 `rows/tail.rs`。 + let state = install::panel_state(model); + let share = rows::TailShare::of(rails.tier, &state); + let list_height = share.list_height(body_height, rows::menu_items(&state)); + column![ + rails::stacked_chips(ui, catalog, model), + divider::full(ui), + rows::content(ui, catalog, model, share, list_height), + ] + .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..79e827f --- /dev/null +++ b/crates/app-iced/src/pages/download/demo.rs @@ -0,0 +1,339 @@ +//! 下载页的**演示数据**（截图 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 的安装选项区三态）/ +//! **`options-liteloader`**（M222：LiteLoader 已可装，取样点用它的最高原版 1.12.2）/ +//! **`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), + // M222 的取样点：选中 1.12.2 + LiteLoader（外加「这里只叠原版」那条中性说明） + Some("options-liteloader") => options_liteloader(catalog), + 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 = 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>) -> 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) +} + +/// M222 的取样点：**选中 1.12.2 + LiteLoader**（安装选项区的第四个状态）。 +/// +/// 为什么单独一个函数而不是复用 [`options`]：LiteLoader 的官方版本表只覆盖 `1.5.2`~`1.12.2`， +/// 而 [`demo_versions`] 是别处基线图的行集（`tests/view.rs` 钉着 8 行），不能为这个取样点改它。 +/// 这里只是给**本状态**的版本列表补一条 `1.12.2`，其余照旧走产品那条真转换 +/// [`Download::from_snapshot`]：图上的 chip 行、中性说明、确认键状态都是产品行为。 +fn options_liteloader(catalog: Catalog) -> Download { + const MC: &str = "1.12.2"; + let mut versions = demo_versions(); + versions.push(VersionSummary { + id: MC.to_string(), + kind: VersionKind::Release, + released: "2017-09-18".to_string(), + installed: false, + }); + let mut state = AppState::new(); + state.apply(AppEvent::Core(CoreEvent::VersionListChanged(versions))); + // 真版本表里 LiteLoader 对 1.12.2 只有这一条（快照分支），照实写。 + state.apply(AppEvent::Core(CoreEvent::LoaderVersions { + kind: Loader::LiteLoader.kind(), + mc_version: MC.to_string(), + result: Ok(vec!["1.12.2-SNAPSHOT".to_string()]), + })); + let draft = InstallDraft { + selected: Some(MC.to_string()), + loader: Loader::LiteLoader, + ..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 { + 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(), + // 演示里这次失败不是内容库那条路来的，不给分类（面板照旧画「失败 + 文案」）。 + failure_kind: None, + // 同理：没有失败名单 ⇒ 内容库那块「只重试这些」不出现（下载页也不画它）。 + retry: Vec::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 { + 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, + /// 桶里的版本数（列表列与命中数都读它）。 + pub count: usize, +} + +/// 把版本行归成桶：**按版本序降序**（`1.21` 在 `1.20` 前面），无主版本概念的桶排最后。 +/// +/// 只做聚合与排序，不决定「当前选中哪个桶」——那是页面状态，住在 `pages/Download` 里。 +#[must_use] +pub fn buckets(rows: &[super::model::VersionRow]) -> Vec { + let mut grouped: Vec = 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 = [ + ("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> = 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..f91a561 --- /dev/null +++ b/crates/app-iced/src/pages/download/install.rs @@ -0,0 +1,324 @@ +//! 安装面板（页面底部）：选中版本 → **安装选项** → 「安装」/ 进度 + 「取消」/ 失败 → 「打开日志」。 +//! +//! M105 之前这里是「选中版本 → 直接『安装』」：点下去就开工，加载器维度整个不存在 +//! （用户实跑的原话：「没是否有选择有前置加载器(版本选择)选项」）。选项区在 `options/`， +//! 本文件只管**面板形态的决策**（纯函数 [`panel_state`]）与「安装中 / 失败」两种形态。 +//! +//! ## 这一块为什么钉在底部而不是跟着列表滚 +//! +//! 列表装的是几十行版本；底部按钮如果跟着滚，用户在列表中间永远看不到「安装」在哪。 +//! 所以列表独立滚动（`rows::list`），面板固定占尾部一块高度。 +//! +//! **M125 的例外**：chips 档（窗口 < 736，竖栏退回顶部 chip 行）里这块面板太贵——它按内容高 +//! 钉死会把版本列表压成 18px 的缝。那一档改成「面板先保预算、列表按整行吃剩下的」 +//! （`rows::TailShare::Narrow`，预算见 `rows/tail.rs::CHIPS_PANEL_BUDGET`）——而且只在 +//! **面板真的占高度**时（`Options` / `Install`）；只画一行提示的 `Hint` 态仍钉死， +//! 否则 8 个版本的列表会被砍到 4 行（r1 复审 P2-1）。 +//! +//! ## 面板的滚动分层（M227 之后的实际形态） +//! +//! ```text +//! 版本行列表 scrollable ← 第 1 层（任何档位都在） +//! └ 选项区 scrollable（Shared / Narrow） ← 第 2 层（`options/view.rs::section`） +//! └ 加载器版本 menu 的 scrollable ← 第 3 层（`options/view.rs::version_menu_height`） +//! ``` +//! +//! **选项区自己滚**这一层是 M222 S7/S1b 之后才有的：`rows::content` 对 `PanelState::Options` +//! 不再整块套外层 `scrollable`（只有 `Install` 态还用外层那层）。 +//! +//! **鼠标落在内层上滚轮会不会冒泡到外层，本仓仍没有实测通道**（静态图拍不到滚动嵌套）。 +//! iced 在指针悬停于内层时由内层消费滚动，所以「滚到底之后继续滚会带动外层」属**未验证行为**； +//! 两个方向的坏结果分别是「面板卡住滚不动」与「一滚就跳到外层」。 +//! **M227 加了新的嵌套**：窄档里版本菜单在选项区的滚动区**之内**（三栏档它在钉死区、不嵌套）， +//! 于是窄档是「菜单 → 选项区 → （列表外层没有）」两级嵌套，这条未验项在窄档变得更相关。 +//! +//! ## 钉死页脚（M222 `6f87c8b` 起，M227 收窄） +//! +//! `options::section` 是「可滚的上半块 + 钉死的下半块」：三栏档钉死区是**说明行 + 版本菜单 + +//! 实例名**（D30 四审：菜单也钉住，否则它正好落在裁切线上）；chips 档（`Narrow`）钉死区 +//! **只剩实例名**——窄档的 459px 装不下「钉住菜单」+「3 整行列表」两个都要（算术见 +//! `rows/tail.rs::CHIPS_PANEL_BUDGET`），于是菜单进滚动区（滚得到、滚动条可见）。 +//! +//! ## 只有意图，没有乐观回显 +//! +//! | 控件 | 消息 | 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; +use super::rows::TailShare; + +/// 面板要画哪一种形态（**决策与画法分开**：决策是纯函数，单测直接钉它）。 +/// +/// 分开的理由就是本轮复审那件事：「装完之后面板还占着、用户再也装不了第二个版本」—— +/// 这是**决策**错了，画法本身没错；把决策抽出来，测试才能在不开图形环境的情况下断言它。 +#[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, + }, + } +} + +/// 底部的安装面板。 +/// +/// `share` = 分高方式（`rows::TailShare`，面板内部形态跟着它走）： +/// +/// - [`TailShare::Pinned`]：内容照原样铺开（面板按内容高钉在底部）； +/// - [`TailShare::Shared`]（三栏档 + 带版本列表的选项区）： +/// **滚动区** = head（版本 id + 安装按钮）+ 六枚加载器 chips； +/// **钉死区** = 说明行（有说明时；否则是「加载器版本」标签）+ 版本菜单 + 实例名输入框； +/// - [`TailShare::Narrow`]（chips 档 + 面板占高度）： +/// **滚动区** = head + 六枚 chips + 说明行 + 版本菜单； +/// **钉死区**只剩实例名输入框（理由与预算见 `rows/tail.rs::CHIPS_PANEL_BUDGET`）。 +/// +/// 菜单在 `Shared` 档是钉住的（D30 四审：裁切位置由钉死区高度决定，与窗宽无关，760 下它会正好 +/// 落在切线上），在 `Narrow` 档则**在滚动区里**——窄档没有多余高度同时钉住「菜单 + 3 整行列表」， +/// 而列表那 3 整行是 M125 像素守门的下限。两支的取舍都写在 `rows/tail.rs`。 +/// +/// **两支「面板先保预算」的分支（`Shared` / `Narrow`）的现实不同，别一概而论** +/// （`rows/tail.rs::TailShare::of`）： +/// +/// - **三栏档 + 带加载器版本列表**（`Shared`）：`has_loader_versions()` 要求 `problem.is_none()`， +/// 所以这一支滚动区里**只会有 head + chips**，错误行与它不可达； +/// - **chips 档**（`Narrow`）：`TailShare::of` 对 `Options`/`Install` 无条件 `Narrow`， +/// `problem` **可以是** `Some`（静态不兼容 / 版本列表取不到 / 空表三种），那时错误行 +/// **在滚动区里**、可能被滚走；`show_versions()` 为假时滚动区只剩 head + chips + 错误行， +/// 钉死区只有实例名。 +pub(super) fn panel<'a>(ui: &'a Ui, catalog: Catalog, model: &'a Download) -> Element<'a, Message> { + panel_with(ui, catalog, model, TailShare::Pinned) +} + +/// 同 [`panel`]，但显式给分高方式（只有 `rows::content` 需要）。 +pub(super) fn panel_with<'a>( + ui: &'a Ui, + catalog: Catalog, + model: &'a Download, + share: TailShare, +) -> 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, share), + PanelState::Hint => hint(ui, catalog), + }; + + // 上下各 12 的面板留白（`[X3, 0]` 的两元组是「垂直 / 水平」）。窄档预算把它算进去了。 + let panel = container(content) + .width(Length::Fill) + .padding(Padding::from([ui.space(Space::X3), 0.0])); + // 面板先保预算那两支：面板吃满自己那份（列表按整行取高之后剩下的高度）， + // 选项区的 `scrollable` 才有确定高度可吃。 + if matches!(share, TailShare::Pinned) { + panel.into() + } else { + panel.height(Length::Fill).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::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, + /// 整体进度 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, + /// 当前分类（从快照反推） + pub category: Category, + /// 选中的版本 id（`None` = 没选中 → 面板只给一句提示） + pub selected: Option, + /// 安装选项区（M105）：选中了版本、又没在装的时候才有 + pub options: Option, + /// 正在跑（或刚跑完）的安装 + pub install: Option, + /// 快照里有没有版本列表（`false` = 还没拉到 → 加载态） + pub loaded: bool, + /// 搜索词（presenter 的 `download_query` 原样；空串 = 不过滤） + pub query: String, + /// **跨分类**命中数：搜索时侧栏显示它，所以它不随当前分类变化 + pub hits: usize, + /// 选中的主版本桶（`None` = 全部；第二级侧栏的选中态，纯视图态） + pub selected_major: Option, + /// 类型栏被用户手动折叠（`true` = 64 图标条；宽度档自己也会折叠，两者取更窄的） + pub type_rail_folded: bool, + /// 主版本桶（第二级侧栏的数据源；由 [`Self::rows`] 聚合，所以只含**当前分类**的桶） + pub buckets: Vec, +} + +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::>(); + + 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 { + 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) -> 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..6f3ca8a --- /dev/null +++ b/crates/app-iced/src/pages/download/options.rs @@ -0,0 +1,39 @@ +//! 安装选项区（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 fade; +mod model; +#[cfg(test)] +mod s1_tests; +#[cfg(test)] +mod tests; +mod view; + +pub use model::{InstallDraft, Loader, OptionsView}; +pub(crate) use view::{section, version_menu_height}; diff --git a/crates/app-iced/src/pages/download/options/fade.rs b/crates/app-iced/src/pages/download/options/fade.rs new file mode 100644 index 0000000..9b6b9f7 --- /dev/null +++ b/crates/app-iced/src/pages/download/options/fade.rs @@ -0,0 +1,125 @@ +//! 选项区滚动视口底部的**淡出遮罩**（M227 返工）。 +//! +//! 单独一个文件只为守 400 行硬线（`components::gate::every_source_file_stays_under_the_line_limit`）。 + +use iced::widget::{column, container, space}; +use iced::{Color, Element, Length}; + +use unlucky_design::elevation::MaterialLayer; + +use crate::theme::Ui; + +use super::super::frame; +use super::super::Message; + +/// 窄档滚动视口底部的淡出高度（像素）。 +/// +/// 取值落在 8~12 这一段：视口在 660 处硬裁，版本菜单的容器上沿（639）露出来 21px 且**一个字形 +/// 都没有**——D30 返工把它判成「空壳蓝条」（深色下容器 `(22,33,41)` vs 画布 `(9,21,28)`， +/// CR 1.99，像渲染错而不是「下面还有内容」）。12px 遮罩让最后 12px 单调渐变到画布色， +/// 留下 8px 圆角上沿做发现性提示。 +pub(super) const VIEWPORT_FADE_PX: f32 = 12.0; + +/// 滚动视口底部的**淡出遮罩**：把内容在最后 `height` 像素内渐变到**画布色**。 +/// +/// 为什么需要它：`scrollable` 会硬裁内容（渲染层的 `with_layer`），裁切位置落在什么上面是不确定的 +/// ——窄档正落在版本菜单容器上沿，用户看到的是一条没有字形的色块，而不是「还能往下滚」。 +/// +/// 为什么是**画布色的 α 阶梯**而不是白/黑雾：遮罩的颜色必须等于它下方那块背景的颜色，否则 +/// 浅色档会浮出一层灰幕、深色档会浮出白雾。`ui.layer(MaterialLayer::Canvas)` 就是页面底色 +/// （含面板 α），于是浅色淡出到纸面、深色淡出到墨底，两档都不新增颜色；方向也对 +/// （内容向背景淡出，不是叠一层高光）。 +/// +/// 为什么用 12 条 1px 实色块拼：iced 0.14 没有渐变原语。1px 步进的 α 斜坡在 100% DPI 下与 +/// 连续渐变的差别在 1/255 量级——D30 的逐像素量测只会看到 α 单调、无硬边。 +/// +/// 形状上它必须**贴在视口内**（调用侧把它放在滚动区底部的 `stack!` 上）：视口下沿是 660， +/// 钉死区的实例名从 668 起，所以遮罩压不到任何控件（M227 返工的零回退证据就是逐像素 +/// 差异只有 648–660 这 12 行）。 +pub(super) fn viewport_fade<'a>(ui: &'a Ui, height: f32) -> Element<'a, Message> { + let canvas = ui.layer(MaterialLayer::Canvas); + let band_height = height / VIEWPORT_FADE_STEPS as f32; + + let mut bands = column![].width(Length::Fill); + for index in 0..VIEWPORT_FADE_STEPS { + let alpha = canvas.a * step_alpha(index); + bands = bands.push( + container(space::horizontal()) + .width(Length::Fill) + .height(Length::Fixed(band_height)) + .style(move |_theme| frame::filled(Color { a: alpha, ..canvas })), + ); + } + bands.into() +} + +/// 遮罩的条数：每条高 `VIEWPORT_FADE_PX / VIEWPORT_FADE_STEPS` 像素（现在是 1px）。 +/// +/// 单测直接对**这一对生产常量** + [`step_alpha`] 断言，所以改步数或改曲线都会当场变红 +/// ——M227 r2 复审实测过「单测空转」的形态：旧测试在函数体里又抄了一遍 `12`，改生产常量它照样绿。 +pub(super) const VIEWPORT_FADE_STEPS: usize = 12; + +/// 第 `index` 条（0 = 最上面、`VIEWPORT_FADE_STEPS - 1` = 视口底边）的**不透明度系数**。 +/// +/// 顶端 ≈0（几乎透出内容）→ 底端 = 1（完全是画布色，与视口外的背景接上）；`t^1.6` 让前几条更淡， +/// 观感是「内容渐隐到背景」，不是一层均匀的纱。 +pub(super) fn step_alpha(index: usize) -> f32 { + // t：0 < t <= 1（`index + 1` 让顶端不落在 0 上，否则第一条完全看不见）。 + let t = (index + 1) as f32 / VIEWPORT_FADE_STEPS as f32; + t.powf(1.6) +} + +#[cfg(test)] +mod tests { + use super::*; + + /// 遮罩的几何自检：**对生产常量断言**，不是对测试里抄的副本。 + /// + /// 抓得住（r2 复审指出的空转形态：旧测试在函数体里又抄了一遍 `12`，改生产常量照样绿）： + /// `VIEWPORT_FADE_STEPS` 改成 6（每档 2px ⇒ 见得到阶梯）、改成不能整除高度的数（半像素带）、 + /// `step_alpha` 写成常数（等于一层纯色幕）、把曲线拉直（`^1.0`，前几条不再更淡）、 + /// 或让末项小于 1（视口底边与画布之间留一道缝）。 + #[test] + fn the_fade_bands_are_one_pixel_and_the_ramp_is_convex_to_opaque() { + // ① 每条**恰好 1px**：这是设计口径（「12 条 1px 实色块」），也是「肉眼分不出阶梯」的前提。 + // 换成 6 条就是 2px/条、换成 5 条还会出半像素带 —— 两种都当场红。 + let band = VIEWPORT_FADE_PX / VIEWPORT_FADE_STEPS as f32; + assert_eq!( + VIEWPORT_FADE_STEPS as f32, VIEWPORT_FADE_PX, + "步数必须等于高度像素数：{VIEWPORT_FADE_PX}px 要 1px 一条，现在 {VIEWPORT_FADE_STEPS} 条 ⇒ {band}px/条" + ); + assert_eq!(band, 1.0, "每条恰好 1px"); + + // ② α 严格递增、除末条外都不透明（末条必须是画布色本身，与视口外无缝接上）。 + let mut previous = 0.0_f32; + let mut previous_delta = 0.0_f32; + for index in 0..VIEWPORT_FADE_STEPS - 1 { + let alpha = step_alpha(index); + let delta = alpha - previous; + assert!( + delta > 0.0, + "第 {index} 条的 α ({alpha}) 必须大于前一条 ({previous})：遮罩要单调变浓" + ); + assert!( + alpha < 1.0, + "第 {index} 条就已不透明，后面 {VIEWPORT_FADE_STEPS} 条白给" + ); + assert!( + delta >= previous_delta, + "第 {index} 条比前一条浓得更少（{delta} < {previous_delta}）：曲线要凸（t^1.6），否则顶端不再「几乎透出内容」" + ); + previous = alpha; + previous_delta = delta; + } + assert!( + step_alpha(0) < 0.1, + "最上面一条 α = {} 不够淡：遮罩顶端要几乎透出内容", + step_alpha(0) + ); + assert_eq!( + step_alpha(VIEWPORT_FADE_STEPS - 1), + 1.0, + "最末一条必须是画布色本身（否则与视口外的背景之间有一道缝）" + ); + } +} 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..d9cd8bd --- /dev/null +++ b/crates/app-iced/src/pages/download/options/model.rs @@ -0,0 +1,342 @@ +//! 安装选项的**决策**（无 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 表里没有条目； +//! - LiteLoader 的官方版本表**实测只有 16 个原版版本**（`1.5.2` ~ `1.12.2`，2026-11 取 +//! `dl.liteloader.com/versions/versions.json`），1.13 起它就不再发版，所以这两头都按 +//! 「官方没有构建」拒掉（不去查列表）。 + +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), + /// 查不到：人读原因（页面显示它并禁掉确认，不静默显示成空列表） + 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, + /// LiteLoader + LiteLoader, +} + +impl Loader { + /// 展示顺序（任务书的口径：原版 / Forge / NeoForge / Fabric / Quilt，LiteLoader 追加在末尾）。 + pub const ALL: [Loader; 6] = [ + Loader::Vanilla, + Loader::Forge, + Loader::NeoForge, + Loader::Fabric, + Loader::Quilt, + Loader::LiteLoader, + ]; + + /// 对应的 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, + Loader::LiteLoader => LoaderKind::LiteLoader, + } + } + + /// 从 presenter 词表回来（`OptiFine` 不是本页选项：它没有安装管线）。 + pub const fn of(kind: LoaderKind) -> Option { + 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::LiteLoader => Some(Loader::LiteLoader), + LoaderKind::OptiFine => 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", + Loader::LiteLoader => "LiteLoader", + } + } + + /// 这个加载器配不配这个原版版本（静态规则，见模块文档的判据表）。 + /// + /// 参数是 `(版本 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), + }, + // LiteLoader 官方版本表只到 1.12.2（最老 1.5.2），两头都是「官方没有构建」。 + // 预览版/快照同样没有（那 16 个原版版本全是正式版）。 + Loader::LiteLoader => match rank { + Some(version) if ((1, 5, 2)..=(1, 12, 2)).contains(&version) => Ok(()), + _ => 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, + /// 选中的加载器 + 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, + /// 加载器相关的**中性说明**（不是错误：不套错误色、不禁用确认键）。 + /// + /// 目前只有 LiteLoader 有：下载页只能装「原版 + 加载器」这一层，叠在 Forge 上要走命令行 + /// （M222 的边界，见 [`Key::DownloadOptionsLiteLoaderVanillaOnly`]）。把它塞进 `problem` + /// 会让用户以为这个组合不能装、还会按不下去确认键，所以单独一条。 + pub note: Option, + /// 本地已装（确认键给「已安装」禁用态） + 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, + }; + + // 中性说明：只解释「这一页能做到哪一层」，不参与确认键判定。 + let note = (loader == Loader::LiteLoader).then(|| { + catalog + .text(Key::DownloadOptionsLiteLoaderVanillaOnly) + .to_string() + }); + + // 四条同时成立才按得下去：不兼容没有、列表真的就位（原版不需要列表）、没装过。 + // 「列表没到位」既包括 `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, + note, + installed: row.installed, + can_confirm, + } + } + + /// 面板上会不会画出**加载器版本列表**（选项区最高的那一态）。 + /// + /// 判据与 `view::show_versions` 同源（原版没有、静态不兼容没有、取不到也没有）， + /// 但这里是**纯模型查询**：`rows::TailShare::of` 要在装配前就知道面板会不会长高。 + /// 用途（M222 D30 r1 S1）：带版本列表的选项区在三栏档实测把版本列表从 6 行压到 2.4 行， + /// 于是这类面板改走 `TailShare::Shared`：面板先吃预算、列表按整行吃剩下的。 + #[must_use] + pub fn has_loader_versions(&self) -> bool { + self.loader != Loader::Vanilla + && self.problem.is_none() + && matches!(&self.versions, LoaderVersionsView::Ready(items) if !items.is_empty()) + } + + /// 确认安装要提交的加载器版本（`None` = 让 core 用官方默认，只在原版路径出现）。 + pub fn loader_version_arg(&self) -> Option<&str> { + (!self.loader_version.is_empty()).then_some(self.loader_version.as_str()) + } + + /// 版本菜单里会有**几条**（`0` = 这一态不画菜单）。 + /// + /// 与 [`OptionsView::has_loader_versions`] 同源：判据一致（不是原版、没有静态原因、 + /// 列表真的就位），所以 `>0` ⟺ `has_loader_versions()`。 + /// 用途（M238）：三栏档的面板预算按菜单高**推导**（`rows/tail.rs::panel_budget`）—— + /// 菜单一行还是两行，差的是一整行列表（48px）。 + #[must_use] + pub fn loader_version_count(&self) -> usize { + match &self.versions { + LoaderVersionsView::Ready(items) if self.has_loader_versions() => items.len(), + _ => 0, + } + } +} diff --git a/crates/app-iced/src/pages/download/options/s1_tests.rs b/crates/app-iced/src/pages/download/options/s1_tests.rs new file mode 100644 index 0000000..eff1819 --- /dev/null +++ b/crates/app-iced/src/pages/download/options/s1_tests.rs @@ -0,0 +1,104 @@ +//! M222 D30 r1（S1）的装配判据：选项区变高时怎么分高、菜单占几行。 +//! +//! 单独一个文件是守 400 行硬线（`tests.rs` 已经装了 M105 那批兼容性/确认键的用例）。 +//! 这里的数字来自出图实测：1180×760 下版本行高 46.33px、选项区从 204px 长到 372px 时 +//! 版本列表从 6.0 行被压到 2.4 行。 + +use unlucky_i18n::Lang; +use unlucky_presenter::dto::{LoaderKind, VersionKind}; +use unlucky_presenter::state::AppState; + +use super::model::{Loader, OptionsView}; +use super::tests::{draft, row, state_with}; + +/// S1 的前置：加载器版本菜单**只按条目数占高**（一行为 64、两行为 112），不空撑两行。 +/// +/// 抓得住：菜单高度改回「固定两行」（LiteLoader 只有 1 条版本时白占 48px，正好把上面版本 +/// 列表挤掉一行）；或者有人把留白算丢（高度不是 64/112 这两个整行值，菜单项会被截半行）。 +#[test] +fn version_menu_height_counts_whole_items_only() { + use super::view::version_menu_height; + assert_eq!(version_menu_height(0), 64.0, "空表也按一行占（不塌成 0）"); + assert_eq!(version_menu_height(1), 64.0, "一条版本 = 一行项 + 上下留白"); + assert_eq!(version_menu_height(2), 112.0, "两条 = 两行"); + assert_eq!( + version_menu_height(50), + 112.0, + "再多也只露两行（余下靠菜单内滚动）" + ); +} + +/// S1（D30 r1）的装配判据：**带加载器版本列表**的选项区在三栏档与列表共享高度。 +/// +/// 实测背景（1180×760）：选项区从 204px 长到 372px 时，版本列表被压成 2.4 行（110px）， +/// 底缘切在第三行图标上；改成分高之后列表回到 4.6 行、面板自己可滚。 +/// +/// M227 起 chips 档单独一支（`Narrow`）：同样的「先保预算」思路，但钉死区只留实例名， +/// 因为窄档 459px 装不下「钉住菜单 + 3 整行列表」（算术见 `rows/tail.rs::CHIPS_PANEL_BUDGET`）。 +/// +/// 抓得住：有人把 arm 2 删掉（`TailShare::of` 只判 chips 档）——三栏档列表又会掉回 2 行； +/// 或者把它放宽成「任何选项区都共享」（原版没有版本列表时不该共享，那会把 6 行列表砍成 4 行）。 +#[test] +fn tall_options_panel_shares_height_at_every_tier() { + use crate::pages::download::install::PanelState; + use crate::pages::download::rows::TailShare; + use crate::pages::layout::VersionRailTier; + + let version_row = row("1.12.2", VersionKind::Release); + let with_versions = state_with( + LoaderKind::LiteLoader, + "1.12.2", + Ok(vec!["1.12.2-SNAPSHOT"]), + ); + let tall = OptionsView::of( + &version_row, + &with_versions, + &draft(Loader::LiteLoader), + Lang::En.catalog(), + ); + assert!(tall.has_loader_versions(), "LiteLoader 有版本列表"); + for tier in [ + VersionRailTier::Wide, + VersionRailTier::Narrow, + VersionRailTier::Compact, + VersionRailTier::Chips, + ] { + let expected = if tier == VersionRailTier::Chips { + TailShare::Narrow + } else { + TailShare::Shared + }; + assert_eq!( + TailShare::of(tier, &PanelState::Options(&tall)), + expected, + "{tier:?}：带版本列表的选项区必须与列表共享高度" + ); + } + + // 原版没有版本列表 ⇒ 仍然钉死（三栏档不该无谓共享）。 + let plain_state = AppState::new(); + let plain = OptionsView::of( + &version_row, + &plain_state, + &draft(Loader::Vanilla), + Lang::En.catalog(), + ); + assert!(!plain.has_loader_versions()); + for tier in [VersionRailTier::Wide, VersionRailTier::Compact] { + assert_eq!( + TailShare::of(tier, &PanelState::Options(&plain)), + TailShare::Pinned, + "{tier:?}：原版选项区没有版本列表，钉死" + ); + } + + // 不兼容（有 problem）时列表不画 ⇒ 也不该共享。 + let blocked_state = state_with(LoaderKind::LiteLoader, "1.13", Ok(Vec::new())); + let blocked = OptionsView::of( + &row("1.13", VersionKind::Release), + &blocked_state, + &draft(Loader::LiteLoader), + Lang::En.catalog(), + ); + assert!(!blocked.has_loader_versions(), "不兼容时没有版本列表"); +} 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..6084dbd --- /dev/null +++ b/crates/app-iced/src/pages/download/options/tests.rs @@ -0,0 +1,331 @@ +//! 安装选项的决策单测（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; + +pub(super) 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(), + ) +} + +pub(super) fn state_with(kind: LoaderKind, mc: &str, items: Result, &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::>() + }) + .map_err(str::to_string), + })); + state +} + +pub(super) 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) + ); + // LiteLoader 的官方版本表只有 1.5.2 ~ 1.12.2（16 个原版版本），两头都按「没有构建」拒。 + for id in ["1.5.2", "1.7.10", "1.12.2"] { + assert_eq!( + Loader::LiteLoader.supports(id, VersionKind::Release), + Ok(()), + "{id} 官方的确有 LiteLoader" + ); + } + for id in ["1.4.7", "1.13", "1.20.1"] { + assert_eq!( + Loader::LiteLoader.supports(id, VersionKind::Release), + Err(Incompat::Unsupported), + "{id} 上游没有 LiteLoader 构建" + ); + } + assert_eq!( + Loader::LiteLoader.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, + Loader::LiteLoader, + ] { + 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); +} + +/// 中性说明（M222）：只有 LiteLoader 带「这里只叠原版」那条，且它**不影响**确认键。 +/// +/// 抓得住：说明被塞进 `problem`（会让用户以为不能装、确认键按不下去）；或者说明跑到别家 +/// 加载器下面（Forge/Fabric 没有这条边界）。 +#[test] +fn liteloader_carries_a_neutral_note_without_blocking_confirm() { + let state = state_with( + LoaderKind::LiteLoader, + "1.12.2", + Ok(vec!["1.12.2-SNAPSHOT"]), + ); + let options = OptionsView::of( + &row("1.12.2", VersionKind::Release), + &state, + &draft(Loader::LiteLoader), + Lang::En.catalog(), + ); + let note = options.note.as_deref().expect("LiteLoader 应带中性说明"); + // 文案在 D30 五审后压成**单行**（两行 28px 是滚动区最大的可压项），断言随之改为 + // 「说清只支持原版父链、且确实只有一行」；完整命令行说法在 `ull help install` 里。 + assert!(note.contains("Vanilla parent only"), "{note}"); + assert_eq!(note.lines().count(), 1, "必须是一行：{note}"); + assert!(options.problem.is_none(), "中性说明不能变成错误"); + assert!(options.can_confirm, "说明不该禁用确认键"); + + // 中文目录同样给中文说明，且仍然不禁用确认键。 + let zh = state_with( + LoaderKind::LiteLoader, + "1.12.2", + Ok(vec!["1.12.2-SNAPSHOT"]), + ); + let options = OptionsView::of( + &row("1.12.2", VersionKind::Release), + &zh, + &draft(Loader::LiteLoader), + Lang::ZhCn.catalog(), + ); + let note = options.note.as_deref().expect("中文也要有说明"); + assert!(note.contains("只叠原版"), "{note}"); + assert!(options.can_confirm); + + // 别家加载器不带这条说明。 + for loader in [Loader::Vanilla, Loader::Fabric, Loader::Forge] { + let state = state_with(loader.kind(), "1.20.1", Ok(Vec::new())); + let options = OptionsView::of( + &row("1.20.1", VersionKind::Release), + &state, + &draft(loader), + Lang::En.catalog(), + ); + assert!( + options.note.is_none(), + "{loader:?} 不该带 LiteLoader 的说明" + ); + } +} 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..14fba7c --- /dev/null +++ b/crates/app-iced/src/pages/download/options/view.rs @@ -0,0 +1,394 @@ +//! 选项区的控件树（M105；窄档形态 M227）。 +//! +//! ## 版面（424 正文列里的四段，三栏档 `Shared`） +//! +//! ```text +//! ── 滚动区 ────────────────────────────────────── +//! 1.12.2 [安装] +//! [原版][Forge][NeoForge][Fabric][Quilt][LiteLoader] ← 六枚一行 +//! ── 钉死区 ────────────────────────────────────── +//! Vanilla parent only — Forge goes through the CLI ← 说明行；没有说明时是「加载器版本」标签 +//! ┌ 1.12.2-SNAPSHOT ┐ ← 官方那份列表（menu + 滚动，按条目数占高：1 条 64 / 2 条 112） +//! └───────────────────┘ +//! [实例名 ] +//! ``` +//! +//! 窄档（chips 档，可用宽 < 600，`rows::TailShare::Narrow`）**钉死区只剩实例名**，说明行与 +//! 菜单都进滚动区——那里的高度只够「钉住实例名 + 3 整行版本列表」，算术见 +//! `rows/tail.rs::CHIPS_PANEL_BUDGET`： +//! +//! ```text +//! ── 滚动区（首屏 104px = head 40 + 间距 4 + chips 32 + 间距 8 + 说明 20）── +//! 1.12.2 [安装] +//! [原版][Forge][NeoForge][Fabric][Quilt][LiteLoader] +//! Vanilla parent only — Forge goes through the CLI +//! ┌ 1.12.2-SNAPSHOT ┐ ← 露在折线下方，滚得到（滚动条在右） +//! ── 视口底 12px 淡出遮罩（`fade::viewport_fade`）──── +//! ── 钉死区 ────────────────────────────────────── +//! [实例名 ] +//! ``` +//! +//! - **钉死档**（原版等不带版本列表的面板）走第三条路：标签、说明、菜单、实例名都在同一列里 +//! 顺序铺开（`04` 基线图就是这一档，不能改）； +//! - 不兼容时的原因行（Error 色）在滚动区末尾（**窄档**可达；三栏档 + 带版本列表时 +//! `problem` 恒为 `None`，所以那支看不到它）； +//! - 说明只有 LiteLoader 有（`Key::DownloadOptionsLiteLoaderVanillaOnly`）； +//! - 窄档的滚动视口底边会硬裁内容（M227 返工前正切在版本菜单容器上沿，露出 21px 没有字形的 +//! 色块），所以那里铺一条 12px 淡出遮罩把内容渐变到画布色——遮罩在视口内（≤660）， +//! 压不到钉死区的实例名（≥668）。 +//! +//! ## 为什么加载器是**六枚一行**（M222 D30 r1 实测订正） +//! +//! 这里原先写「五家一起排会溢出 ⇒ 折成两行」，那是 M105 的推算。D30 的实测图（1180×760， +//! 正文列 424）是**六枚一行、末枚右缘约 404px**，没有溢出——所以示意与说明都改成了实际形态。 +//! chip 的几何仍是组件自己的真源（`ChipGeometry`），页面不许压它；再来第七家时先看图再决定 +//! 是否换行。 +//! +//! ## 为什么「不兼容」不禁用 chip、而是禁用确认键 +//! +//! 禁用的 chip 点不动，用户就**看不到原因**（那正是「选完才失败」的另一种形态）。 +//! 现在的做法：五家永远都能点，选中不兼容的那家时下面出现一行具名原因，同时「安装」变成禁用态。 +//! 于是「为什么不能装」和「怎么才能装」永远同屏。 + +use iced::widget::{column, container, row, scrollable, stack}; +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::rows::TailShare; +use super::super::Message; +use super::fade; +use super::model::{Loader, LoaderVersionsView, OptionsView}; + +// 加载器 chip 的顺序与集合**委派**给 `Loader::ALL`（原版 / Forge / NeoForge / Fabric / +// Quilt / LiteLoader）。这里原先是手写的五枚常量——同一份清单的第三处副本 +// （`dto::wizard_choices`、`Loader::ALL`、这里），M222 加 LiteLoader 时三处都得改，索性委派。 +// D30 r1 实测（1180×760 与 720×760 两种宽度、浅/深两套主题）：六枚 chip 排在一行， +// 末枚（LiteLoader）右缘约 404px，正文列 424 仍有余量；窄窗 720 下同一行也没有溢出。 + +/// 加载器版本菜单的**可见高度**（像素）：最多两行项 + 上下留白 8×2。 +/// +/// 项高 48 是 `MenuGeometry` 的真源；`Space::X2 = 8` 是上下留白 ⇒ 两行 = 112、一行 = 64。 +/// 为什么按**条目数**取（M222 D30 r1 S1）：LiteLoader 对 1.12.2 只有一条版本，原来固定撑到 +/// 两行高（112px），那 48px 纯属空档，却正好是把上面版本列表挤成 2.4 行的元凶之一。 +/// 单测 `options/view::tests` 直接钉这两档的数值。 +pub(crate) fn version_menu_height(items: usize) -> f32 { + const ITEM: f32 = 48.0; + let rows = items.clamp(1, 2) as f32; + rows * ITEM + Space::X2.dp() * 2.0 +} + +/// 选项区（面板的下半块）：**可滚的上半块 + 钉死的下半块**。 +/// +/// `share` = 分高方式（`rows::TailShare`，三个形态见 `install::panel_with` 的文档）： +/// +/// - `Pinned`（原版等不带版本列表的面板）走另一条路：标签、说明、菜单、实例名都在同一列里 +/// 顺序铺开（`04` 基线图就是这一档，不能改）； +/// - `Shared`（三栏档 + 带版本列表）： +/// - **滚动区**：head（版本 id + 安装按钮）+ 六枚加载器 chips； +/// - **钉死区**：说明行（有说明时；否则是「加载器版本」标签）+ 版本菜单 + 实例名输入框。 +/// - `Narrow`（chips 档 + 面板占高度，M227）： +/// - **滚动区**：head + 六枚 chips + 说明行 + 错误行 + **版本菜单**； +/// - **钉死区**：只有实例名输入框。 +/// +/// 为什么菜单在三栏档钉、在窄档滚：裁切位置由**钉死区高度**决定（D30 四审）， +/// 760 下菜单曾正好落在切线上（容器 642–706 只有 18px 可见、条目文字一格没画出来）。 +/// 三栏档把菜单一起钉住之后不再依赖首屏剩余高度分配；窄档没有那么多高度—— +/// 钉住菜单 + 说明 + 实例名要 180~228px，再加首屏 head+chips 76 就把列表挤到 ≤1 整行， +/// 而 M125 的像素守门要求 ≥3 整行。所以窄档只钉实例名，其余进滚动区（预算算术见 +/// `rows/tail.rs::CHIPS_PANEL_BUDGET`）。 +/// +/// D30 八审实测（1180×760，`Shared`）：滚动区可见高 ≈96–104px，内容（head 40 + chips 32 + +/// 间距 4）≈76px ⇒ head（墨迹 462–501）与六枚 chips（506–537，32px 四角闭合）完整在首屏。 +/// **M238 复量**（同一判据：视口 = 面板内容顶 → 钉死区上一行 − 8px 间距）：1180×760 与 736×760 +/// 修前都只有 **54px**（这解释了「六枚 chip 只露 10px」——不是 736 独有），修后 **98px**； +/// 900 档修前 62px、修后 106px。差数来源见 `rows/tail.rs::panel_budget`。 +/// 窄档 720×760 = **120px**，对首屏 104px（head 40 + 4 + chips 32 + 8 + 说明行 20）留 16px 余量 +/// ⇒ head、六枚 chips、说明行三者完整在首屏，版本菜单露出容器上沿（滚动条在右）。 +pub(crate) fn section<'a>( + ui: &'a Ui, + catalog: Catalog, + options: &'a OptionsView, + share: TailShare, +) -> 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); + + // 钉死档（原版 / 没有加载器版本列表）**保持旧结构**：标签与说明都在列内。 + // 为什么不一并改：`04` 是别处基线图的对照，它的面板矮、列表 6 行——把标签撤出会 + // 让面板矮 26px，列表涨到 302px（6.86 行）反而切出半行。方案 B 只对共享档生效。 + if matches!(share, TailShare::Pinned) { + let mut plain = 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 let Some(note) = &options.note { + plain = plain.push(frame::text_role( + ui, + TypeRole::BodySmall, + false, + note.as_str(), + ui.color(Role::OnSurfaceVariant), + )); + } + if show_versions(options) { + plain = plain.push(frame::text_role( + ui, + TypeRole::LabelMedium, + false, + catalog.text(Key::DownloadOptionsLoaderVersion), + ui.color(Role::OnSurfaceVariant), + )); + plain = plain.push(version_list(ui, catalog, options)); + } + if let Some(problem) = &options.problem { + plain = plain.push(frame::text_role( + ui, + TypeRole::BodySmall, + false, + problem.as_str(), + ui.color(Role::Error), + )); + } + plain = plain.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, + )); + return plain.into(); + } + + // 共享档的滚动区以 head + 六枚 chips 起头（方案 B，D30 六审裁决；错误行见下）。 + // + // 为什么把「安装选项」标签撤出滚动区：五审 82px → 六审 103px 的视口里， + // head(40) + 标签(17) + chips(32) + 两处间距(16) = 105px，差 2px 就把 chip 的底边框裁掉； + // 再塞说明（20px）就差 27~29px，说明整块 0 像素。 + // 并排标签（方案 C）在这里不可行：六枚 chip 实测已占 404px 正文列只有 424px， + // 加上「安装选项」必然横向溢出、把第六枚裁掉——那是拿一个已完成项换另一个。 + // 所以按塔授权的 B 落地：**说明**搬到钉死区（见下面的 `pinned`）；「安装选项」标签在 + // 共享档**删掉**（不是搬——八审裁决，见下三行），Pinned 档保留。滚动区只装控件。 + // 共享档**没有**「安装选项」标签：这是设计决定（D30 八审裁决）——六枚 chip 自解释， + // 且正文列只有 424px、六枚 chip 已占 404px，加标签必然横向裁掉最后一枚。 + // 原版等 Pinned 档仍保留该标签（见上面 `Pinned` 那条路）。 + let narrow = matches!(share, TailShare::Narrow); + let mut body = column![head, loader_row(ui, catalog, options)] + .spacing(ui.space(Space::X1)) + .width(Length::Fill); + + // 窄档：说明行（或「加载器版本」标签）与版本菜单**都进滚动区**——钉死区只剩实例名。 + // 顺序必须是 head → chips → 说明 → 菜单：预算（`CHIPS_PANEL_BUDGET`）保证前 104px 完整， + // 菜单露在折线下方（滚动条可见，滚得到）。 + if narrow && show_versions(options) { + body = body.push(versions_label(ui, catalog, options)); + } + + // 中性说明在三栏档**只在钉死区画一份**（八审：这里原先也画了一份，两处像素级重影）。 + // 窄档没有钉死的那一行（见上），所以它在这里画、也只画一次。 + if let Some(problem) = &options.problem { + body = body.push(frame::text_role( + ui, + TypeRole::BodySmall, + false, + problem.as_str(), + ui.color(Role::Error), + )); + } + + if narrow && show_versions(options) { + body = body.push(version_list(ui, catalog, options)); + } + + // 钉死区：三栏档是「说明/标签 + 菜单 + 实例名」，窄档只剩实例名。见 `section` 的文档。 + let mut pinned = column![].spacing(ui.space(Space::X2)).width(Length::Fill); + if !narrow && show_versions(options) { + pinned = pinned.push(versions_label(ui, catalog, options)); + pinned = pinned.push(version_list(ui, catalog, options)); + } + pinned = pinned.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, + )); + + let scroll_area: Element<'a, Message> = scrollable(body) + .height(Length::Fill) + .style(frame::scroll_style(ui)) + .into(); + + // 窄档：视口底部铺一条 12px 淡出遮罩（M227 返工 ①，理由见 `fade::viewport_fade`）。 + // 三栏档不铺：那里滚动区内容恒为 head 40 + 间距 4 + chips 32 = 76px，而视口 ≈118px， + // 永远不会出现「半截内容」；铺上去只是「画布盖画布」，反而动了 M222 已验的 1180 像素。 + let scroll_area: Element<'a, Message> = if narrow { + stack![ + scroll_area, + container(fade::viewport_fade(ui, fade::VIEWPORT_FADE_PX)) + .width(Length::Fill) + .height(Length::Fill) + .align_y(Alignment::End), + ] + .width(Length::Fill) + .height(Length::Fill) + .into() + } else { + scroll_area + }; + + column![scroll_area, pinned] + .spacing(ui.space(Space::X2)) + .height(Length::Fill) + .width(Length::Fill) + .into() +} + +/// 版本菜单上方那一行：**有中性说明就显示说明**（它讲的是「这一家的叠法」，位置就在版本菜单 +/// 正上方，语义对得上）；没有说明时才退回通用标签。 +/// +/// 高度相同（`BodySmall` 与 `LabelMedium` 都是一行），所以无论放滚动区还是钉死区都不改预算。 +/// 注意标签不是「搬」下来的：共享档的「安装选项」标签是**删掉**的（八审裁决，见 `section`）。 +fn versions_label<'a>( + ui: &'a Ui, + catalog: Catalog, + options: &'a OptionsView, +) -> Element<'a, Message> { + match &options.note { + Some(note) => frame::text_role( + ui, + TypeRole::BodySmall, + false, + note.as_str(), + ui.color(Role::OnSurfaceVariant), + ), + None => frame::text_role( + ui, + TypeRole::LabelMedium, + false, + catalog.text(Key::DownloadOptionsLoaderVersion), + ui.color(Role::OnSurfaceVariant), + ), + } +} + +/// 加载器版本这一段要不要画（见 `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 Loader::ALL.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) => { + // **内联列表口径**（M238）：这张菜单被套在下面的 `scrollable` 里，而 CPU 后端画 + // quad 阴影时绕过裁切掩码 ⇒ L2 阴影会漏出视口、把钉死区的实例名压暗 7.2% + // （浅色画像布 `(249,249,250)` → `(231,231,232)`）。理由与两后端差异见 + // `components::inputs::menu::shadow` 的 `flat` 文档。 + let mut list = Menu::new().width(Length::Fill).flat(); + 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(version_menu_height(items.len()))) + .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..353c165 --- /dev/null +++ b/crates/app-iced/src/pages/download/rails.rs @@ -0,0 +1,310 @@ +//! 版本管理页的**三栏装配**：类型栏 + 主版本栏 + 列表列（宽档不够时退回顶部 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::rows; + +pub(super) mod major; + +pub(super) use major::{major_entries, major_rail}; + +// 只有测试要从这里拿「一项画成什么样」的判定（lib 里由 `major_item` 内部消费） +#[cfg(test)] +pub(super) use major::{major_shape, MajorShape}; + +/// 类型栏里一项的图标。 +/// +/// 图标语汇只有 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, + body_height: f32, +) -> Element<'a, Message> { + // 分高方式与列表高度都从 `TailShare` 一处取（`Pinned` 档不给整行高度）。 + // M238：面板预算按版本菜单的行数推，所以 `list_height` 也要拿到那个条数。 + let state = super::install::panel_state(model); + let share = rows::TailShare::of(rails.tier, &state); + let list_height = share.list_height(body_height, rows::menu_items(&state)); + 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, share, list_height)) + .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> { + 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, tip_body(ui, label), Position::Right).into() +} + +/// tooltip 的正文盒子（`BodySmall` + `OnSurface` 叠 `Overlay` 层）：类型栏的图标项与 +/// 主版本栏图标条档的「全部版本」共用一份文字语言。 +fn tip_body<'a>(ui: &'a Ui, label: &'a str) -> Element<'a, Message> { + 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))) + .into() +} + +/// 选中态 → 图标按钮的三式（`Tonal` = 当前项，与 ListItem 的 `SecondaryContainer` 同色系）。 +fn select_variant(selected: bool) -> IconVariant { + if selected { + IconVariant::Tonal + } else { + IconVariant::Standard + } +} + +/// 栏标题（`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() +} + +/// 折叠 / 展开类型栏的图标按钮（`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, + ) +} + +/// 顶部 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/rails/major.rs b/crates/app-iced/src/pages/download/rails/major.rs new file mode 100644 index 0000000..4bb7eff --- /dev/null +++ b/crates/app-iced/src/pages/download/rails/major.rs @@ -0,0 +1,173 @@ +//! 第二栏（主版本桶）与「一项画成什么样」的判定（从 `rails.rs` 拆出来守 400 行红线）。 +//! +//! 两条渲染路径吃同一份数据：[`major_entries`] 产出 `[全部版本, 1.21, 1.20, …]`， +//! 竖栏（[`major_rail`]）与 chips 行（`rails::stacked_chips`）各画一遍。 +//! 图标条档（64 宽）里「全部版本」换图标 + tooltip 的取舍见 [`major_shape`]。 + +use iced::widget::{column, container}; +use iced::{Alignment, Element, Length}; + +use unlucky_design::spacing::Space; + +use unlucky_i18n::{Catalog, Key}; + +use unlucky_design::icons::IconKind; + +use crate::app::components::navigation::list_item::{list_item, ListItem}; +use crate::pages::download::group; +use crate::pages::download::model::Download; +use crate::pages::frame; +use crate::pages::layout::RAIL_ICON_WIDTH; +use crate::pages::Message; +use crate::theme::Ui; + +use super::{labeled, rail_title}; + +/// 第二栏：主版本桶（第一项永远是「全部版本」；没有主版本概念的版本不单独占一项）。 +pub(in crate::pages::download) 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, icon_only)); + } + + body.into() +} + +/// 第二级侧栏的一项（「全部版本」与每个主版本桶共用一套结构，好让**两条渲染路径** +/// ——竖栏与 chips 行 —— 都用同一份数据，测试也只钉这一份）。 +/// +/// 字段全部**借**模型里的桶标签与目录里的静态串：这两条渲染路径都要把标签塞进 iced 控件树， +/// 借本地的 `String` 会让整棵树的生命周期塌到函数作用域里（E0515）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(in crate::pages::download) struct MajorEntry<'a> { + /// 选中它要发的键（`None` = 「全部版本」） + pub key: Option<&'a str>, + /// 画出来的标签 + pub label: &'a str, + /// 此刻是否选中（**按生效值算**：搜索期间恒为「全部」，见 `group::bucket_selected`） + pub selected: bool, +} + +/// 一项在 iced 里**画成什么样**（纯函数产出，单测直接钉它 —— 两种形状的取舍见 [`major_shape`]）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(in crate::pages::download) enum MajorShape<'a> { + /// `ListItem` 单行文字（展开档的每一项、图标条档的桶标签） + Text(&'a str), + /// 图标 + tooltip 全称（图标条档的「全部版本」，见 [`major_shape`] 的宽度账） + Icon(&'a str), +} + +/// 图标条档画成什么样：**只有「全部版本」这一项不是文字**。 +/// +/// ## 64 宽的可见文本宽是 **32**，不是 40（M123 取证实测） +/// +/// `ListItem` 两侧内边距各 16（`pad_start` / `pad_end`），所以 64 宽的栏里文本格 +/// = 64 − 32 = **32**，再长就被 `clip(true)` 切掉。`BodyLarge` 16px 下： +/// +/// | 标签 | 墨迹（736×760 实测） | 32 的文本格里放得下？ | +/// |---|---|---| +/// | `1.21` | 26px（x=217..242） | ✓ 余量 **6** | +/// | `1.20` | 28px（x=217..244） | ✓ 余量 **4** | +/// | `24w` | 29px（x=216..244） | ✓ 余量 **3**（最紧的一条） | +/// | `All versions` | 墨迹画到 x=247，裁切边在 248 | ✗ 被切：实际只画出「All v」（缺陷 2 的原图） | +/// | `全部版本` | 4 全角字 × 16 = **64**（精确值，不是估计） | ✗ 只画得出「全部」，且顶到裁切边 | +/// +/// 桶标签的余量是 **3~6px**（视字形：`24w` 最紧 3，`1.21` 最松 6）。短标签「全部」= 2 × 16 = **32**， +/// 与文本格**一样宽、零余量**——比桶标签那 3~6px 更薄，裁不裁取决于字体渲染的小数位， +/// 是一个查不出也守不住的边界，所以「换短标签」这条退路不采用。于是图标条档的 +/// 「全部版本」**不画文字**：换成图标（字形见 [`major_shape`] 的下文）， +/// 全称进 tooltip（宽度不设限，中英文都完整）。 +/// +/// 桶标签本来就是 3~5 字符的短串，两档都照旧画原文。 +/// +/// ## 用哪个字形（r1 复审 P3-1） +/// +/// 这里用 **`IconKind::Logs`（文档 + 正文行）**，不用第一级「全部类型」那个网格 +/// （`category_icon(Category::All)`）：Compact 档两条 64 宽的栏在屏上相邻，若两级都用网格 + +/// 同一个 40×40 `Tonal` 药丸，**第一级「全部」与第二级「全部版本」像素级同形**， +/// 只能靠 hover 出 tooltip 才分得清是哪个轴。文档/清单字形读作「整份版本清单」， +/// 与网格（「全部类型」）分得开。 +/// +/// 更贴切的「版本 / 历史 / 层叠」字形本仓没有（图标语汇只有 28 个描边字形，登记在 +/// `unlucky_design::icons`），新增字形要动 `crates/design`（超出本页范围），此处按既有字形借用。 +pub(in crate::pages::download) const fn major_shape( + entry: MajorEntry<'_>, + icon_only: bool, +) -> MajorShape<'_> { + if icon_only && entry.key.is_none() { + MajorShape::Icon(entry.label) + } else { + MajorShape::Text(entry.label) + } +} + +/// 第二级侧栏要画的全部项：`[全部版本, 1.21, 1.20, …]`，顺序 = 桶的版本序。 +/// +/// 抽成纯函数是为了让「最后一个桶可点」这件事**可断言**（复审 P2-2 的要求）： +/// 竖栏与 chips 行都从这一份数据画，chips 行外面还套了横向滚动，所以「画得出来」= 「够得着」。 +/// 返回 `Vec` 而不是迭代器：调用方两处都要 len（chips 的宽度预算）与随机访问。 +pub(in crate::pages::download) fn major_entries<'a>( + catalog: Catalog, + model: &'a Download, +) -> Vec> { + 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 +} + +/// 主版本的一项：形状由 [`major_shape`] 决定（图标条档的「全部版本」是图标 + tooltip， +/// 其余都是 `ListItem` 单行文字）。 +fn major_item<'a>(ui: &'a Ui, entry: MajorEntry<'a>, icon_only: bool) -> Element<'a, Message> { + let press = Message::SelectMajor(entry.key.map(str::to_string)); + + match major_shape(entry, icon_only) { + MajorShape::Text(label) => { + let mut item = ListItem::new(label, press); + if entry.selected { + item = item.selected(); + } + list_item(ui, item) + } + // 图标条档的「全部版本」：图标（与本页第一级的「全部」同一个网格）+ 全称 tooltip。 + // 高度对齐 `ListItem` 的行高，两档的行节奏才一样。 + MajorShape::Icon(full) => { + container(labeled(ui, full, IconKind::Logs, entry.selected, press)) + .width(Length::Fill) + .height(Length::Fixed(ui.metrics().row_height)) + .align_x(Alignment::Center) + .align_y(Alignment::Center) + .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..d414a48 --- /dev/null +++ b/crates/app-iced/src/pages/download/rows.rs @@ -0,0 +1,364 @@ +//! 列表列：搜索条 + 计数头 + **单行**版本行 + 底部安装面板。 +//! +//! ## 这一列的职责边界 +//! +//! | 位置 | 画什么 | 消息 | +//! |---|---|---| +//! | 搜索条 | 真实控件的 `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` +//! 的扫描断言）。 +//! +//! ## 尾巴不能把列表压成缝（M125 缺陷 1） +//! +//! 这一列是 `column![搜索, 分隔线, 计数头, 列表(Fill), 尾巴]`：`body` 吃剩下的高度、`tail` +//! 按内容高钉死。iced 的 `Column` 不会把溢出交给滚动，所以**尾巴一高，列表就被压成一条缝**—— +//! M123 在 700×760 拍的 `02-options-fabric-en-light-chips700.png` 里，8 行版本只剩 **18px** +//! 可视高（行高 44），版本号一个字都读不出来，用户想换版本点不到。 +//! +//! 病根是 chips 档比三栏档多花两行 chip（tabs 48 + chips 48 + 两处间距），而选项区那一块 +//! 固定 ≈316px（版本行 40 + **六枚** loader chip 34 + 菜单 + 实例名 56；M222 之后菜单与实例名 +//! 都在面板钉死区，见 `options/view.rs::section`）。 +//! 同样的 760 高窗口里：三栏档列表还剩 158px（3 整行），chips 档只剩 18px。 +//! +//! 修法是 [`TailShare`] 三档：**不带加载器版本列表**的选项区在三栏档照旧钉死（面板整块在屏内）， +//! chips 档**且面板真的占高度** +//! （选项区展开 / 安装中）时改成「**面板先保预算、剩下按整行给列表**」 +//! （`tail::narrow_rows` + `CHIPS_PANEL_BUDGET = 192`）：700/720×760 下列表 **132px = 3 整行**、 +//! 面板拿走其余（208px）。M227 之前这一档是「Fill 与 Fill 五五分」——面板只分到 164px， +//! 钉死区（说明 + 菜单 + 实例名 ≈180px）把它吃穿，滚动区剩 0、head / 六枚 chip 全不在屏。 +//! 三栏档 + 带版本列表的选项区走另一支（`tail::whole_rows` + `tail::panel_budget`）： +//! 1180×760 列表 **132px = 3 整行**、面板 330px（滚动视口 98px），那里菜单与说明都钉在面板底部。 +//! M238 之前那支用的是**死的** `PANEL_BUDGET = 300`：面板实得 286px，滚动视口只有 54px +//! ⇒ 六枚 chip 被裁成 10px 的上缘（736 与 1180 同病，纵向预算与窗宽无关）。 +//! 「刚进页面还没选版本」（`Hint`，面板只有一行提示）**不共享**：那一态 main 本来就有 +//! **7 整行**在屏（不是 8：第 8 条墨迹其实是 `Pick a version, then install` 那句 hint， +//! 横向范围对不上版本号；700×760 上放 8 行要 352px，实测只剩 309~322px），五五分会砍成 +//! **4 整行**、下面留 ≈160px 空白（r1 复审 P2-1 的回归，r2 修回 7 整行）。 +//! +//! 这条判据按**档位**而不是按高度：页面的模型里只有 `window_width`，窗口高度没接进页面， +//! 所以「760 高到底够不够」在运行时是未知量（边界写在 [`TailShare`] 的文档里）。 +//! +//! ## 搜索的三条口径 +//! +//! | 情形 | 画什么 | 为什么 | +//! |---|---|---| +//! | 有命中 | 列表照常，侧栏**位置不动**，搜索条右侧显示「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::install::{self, panel_state, PanelState}; +use super::model::{Download, VersionRow}; +use super::states; + +mod tail; + +pub(crate) use tail::{menu_items, TailShare}; + +/// 列表列（三栏档与 chips 档共用一份）。 +/// +/// `share` 决定「列表」与「尾部面板」怎么分这块高度（真实分支见 `tail::TailShare::of`）： +/// `Pinned` = 面板按内容高钉在底部、列表吃剩下的；`Shared` / `Narrow` = 面板先吃预算、 +/// 列表按**整行**吃剩下的（`tail::whole_rows` / `tail::narrow_rows`，两者差别在面板内部 +/// 钉什么，见 `tail::CHIPS_PANEL_BUDGET`）。哪些组合走哪一支由那一处决定，这里不重复判。 +pub(super) fn content<'a>( + ui: &'a Ui, + catalog: Catalog, + model: &'a Download, + share: TailShare, + list_height: Option, +) -> 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 { + // 只有「面板先保预算」那两支（`Shared` / `Narrow`）才按整行取高：`Pinned` 档（面板矮） + // 实测已经是整行（`04` 图），取整反而会把它从 6 行缩到 5 行。 + let height = if matches!(share, TailShare::Pinned) { + None + } else { + list_height + }; + list(ui, catalog, model, &visible, height) + }; + + // 列表与尾部面板之间**总是**有一条分隔线（三态一致）：M123 的取证图里「选好了版本」 + // 那一态原先没有它，版本行与选项区第一行（版本号 + 安装按钮）读起来像同一块内容。 + let tail: Element<'a, Message> = column![ + divider::full(ui), + install::panel_with(ui, catalog, model, share) + ] + .spacing(ui.space(Space::X3)) + .width(Length::Fill) + .into(); + + // chips 档 / 带版本列表的选项区：面板吃满自己那份。 + // + // `PanelState::Options` 走**面板内部**的滚动（上半块可滚 + 实例名钉页脚，见 `install::panel`）， + // 所以这里不再整块套一层 scrollable——那一层曾让窄窗出现两条并列滚动条，也因为把实例名 + // 卷进滚动区而让它掉到首屏外（D30 r2 S7）。其它面板（安装中/失败）内容短，保留外层滚动。 + let tail: Element<'a, Message> = match (share, panel_state(model)) { + (TailShare::Pinned, _) | (_, PanelState::Options(_)) => tail, + (TailShare::Shared | TailShare::Narrow, _) => scrollable(tail) + .id(iced::widget::Id::new(PANEL_SCROLL_ID)) + .height(Length::Fill) + .style(frame::scroll_style(ui)) + .into(), + }; + + 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() +} + +/// 面板那一层 `scrollable` 的 Id（M222 D30 r1 S2 的出图取证用，见 `pages::harness`）。 +/// +/// 用途只有一个：窄窗（chips 档 / 带版本列表的选项区）里面板自己可滚，出图要证明 +/// 「实例名那格滚得到」——harness 拿到这个 Id 就能派一次 `scroll_to` 再拍。 +pub(crate) const PANEL_SCROLL_ID: &str = "download-panel"; + +/// 搜索条 + 清空按钮 + 命中数（三者一行；命中数只在有查询词时出现）。 +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], + height: Option, +) -> Element<'a, Message> { + let entries = column( + visible + .iter() + .map(|entry| version_row(ui, catalog, model, entry)) + .collect::>(), + ) + // 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), + )) + // `Some` = 面板先保预算那一档按**整行**取高（三栏档 `tail::whole_rows` / + // chips 档 `tail::narrow_rows`）；`None` = `Pinned`（面板矮）用 Fill。 + .height(height.map_or(Length::Fill, Length::Fixed)) + .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/tail.rs b/crates/app-iced/src/pages/download/rows/tail.rs new file mode 100644 index 0000000..707c694 --- /dev/null +++ b/crates/app-iced/src/pages/download/rows/tail.rs @@ -0,0 +1,318 @@ +//! 「列表与尾巴面板怎么分高」+ 版本行的整行取整（M125 / M222 D30 / M227 / M238）。 +//! +//! 从 `rows.rs` 拆出来的理由只有一条：那边撞 400 行硬线（项目自带 +//! `components::gate::every_source_file_stays_under_the_line_limit` 会判红）。本文件是 +//! [`TailShare`] 的**纯搬移**，加上 M222 新增的三个只读量（[`ROW_PITCH`] / [`LIST_CHROME`] / +//! [`whole_rows`]）与 M227 的 chips 档预算（[`CHIPS_STACK`] / [`CHIPS_LIST_CHROME`] / +//! [`CHIPS_PANEL_BUDGET`] / [`narrow_rows`]）。 +//! +//! M238 把三栏档那个钉死的 `PANEL_BUDGET = 300` 换成**按面板内容推导**的 [`panel_budget`] +//! （首屏 + 钉死区 + 内外边距 + 列表↔面板那层），理由：那个常数不含 [`TAIL_CHROME`]、 +//! 也不随版本菜单行数变，760/900 档下滚动视口只剩 54/62px，六枚 chip 被裁成 10px。 + +use crate::pages::layout::VersionRailTier; + +use crate::pages::download::install::PanelState; + +/// 列表与尾部面板怎么分这块高度（M125 缺陷 1 的修法；M227 拆出 chips 档一支）。 +/// +/// | 档位 × 面板形态 | 分法 | 为什么 | +/// |---|---|---| +/// | `Wide` / `Narrow` / `Compact` + 面板**不带**加载器版本列表 | [`TailShare::Pinned`] | 原版面板矮（`04` 实测列表 6 行），整块在屏内 | +/// | 任何档 + 选项区**带加载器版本列表** | [`TailShare::Shared`]：面板先吃 [`panel_budget`]，剩下按整行给列表（[`whole_rows`]） | 面板要「首屏 76 + 钉死区（说明 + 菜单 + 实例名）」才算完整；旧规则（对半分）把列表压到 110px，M238 前那个常数 300 又把滚动视口挤到 54px（六枚 chip 只露 10px）。现在 1180×760 是 **132px = 3 整行**、视口 98px | +/// | `Chips` + 面板**占高度**（选项区展开 / 安装中） | [`TailShare::Narrow`]：面板先吃 [`CHIPS_PANEL_BUDGET`]，剩下按整行给列表（[`narrow_rows`]） | 窄档可用高比三栏档少两行 chip（459 vs 580）⇒ 只钉实例名，head/chips/说明/菜单进滚动区；700/720×760 列表 **132px = 3 整行** | +/// | 任何档 + 只画 `Hint`（没选版本，面板只有一行） | [`TailShare::Pinned`] | 一行提示不值得让面板吃预算：700×760 下 main 是 **7 整行**在屏（不是 8——第 8 条墨迹其实是 `Pick a version, then install` 那句 hint，横向范围对不上版本号；要放 8 行得 352px，实测只剩 309~322px），对半分只剩 **4 整行**、下面留 160px 空白（r1 复审 P2-1，r2 修回 7） | +/// +/// 分高方式按「档位 + 面板形态」判；**具体像素**由窗口高度算（`pages/download.rs::view_sized` +/// 把 `model.window_height` 经 `frame::body_height` 传下来，见 [`whole_rows`] / [`narrow_rows`]）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(crate) enum TailShare { + /// 面板钉在底部（面板矮的档位）。 + Pinned, + /// 三栏档 + 带版本列表的选项区：面板先吃预算、列表按整行吃剩下的；钉死区含**说明/标签 + /// + 版本菜单 + 实例名**（D30 四审/八审判定：1180 档高度够，菜单钉住最省事）。 + Shared, + /// chips 档（可用宽 < 600）+ 面板占高度：同一套「先保预算、列表按整行」， + /// 但面板钉死区**只留实例名**，head / 六枚 chip / 说明 / 版本菜单全在滚动区 + /// （理由见 [`CHIPS_PANEL_BUDGET`]：459 里装不下「钉住菜单」+「3 整行列表」）。 + Narrow, +} + +impl TailShare { + /// 档位 + **面板形态** → 分高方式（纯函数，单测直接钉它）。 + /// + /// 三条 arm，**不是**「两个条件同时成立」才共享（M227 重写：旧文档只写 M125 那一条， + /// 把 arm 2 的「任何档位」漏了 —— r8 复审 improve finding）： + /// 1. `Chips`（可用宽 < 600，多花两行 chip、竖排预算最紧的那一档）**且**面板真占高度 + /// （`Options` 选中了版本 / `Install` 进度或失败）⇒ [`TailShare::Narrow`]； + /// 2. **任何档位**的 `Options` 只要 [`has_loader_versions`](super::super::options::OptionsView::has_loader_versions) + /// （选项区带加载器版本列表 ⇒ 钉死区 152~200px，见 [`panel_budget`]）⇒ [`TailShare::Shared`]。三栏档只走这条， + /// chips 档被 arm 1 先接走； + /// 3. 其余 ⇒ [`TailShare::Pinned`]：不带版本列表的 `Options`（原版 / 不兼容 / 空表）与 + /// `Hint`。 + /// + /// `Hint`（刚进页面还没选版本）只是**一行**提示（≈30px），让它吃预算会把列表从 **7 整行** + /// 砍到 **4 整行**、下半块留 ≈160px 空画布（r1 复审 P2-1 实测：main 在 700×760 的 + /// `Hint` 态是 7 整行——不是 8，第 8 条墨迹其实是 `Pick a version, then install` 那句 + /// hint，横向范围对不上版本号；r2 修回 7 整行）。所以 `Hint` **在任何档位都钉死**。 + pub(crate) fn of(tier: VersionRailTier, state: &PanelState<'_>) -> Self { + match (tier, state) { + // M227：chips 档（窄档）单独一支 —— 同一份「先保预算」思路，但钉死区只留实例名。 + (VersionRailTier::Chips, PanelState::Options(_) | PanelState::Install(_)) => { + Self::Narrow + } + // M222 D30 r1/r2：**带加载器版本列表**的选项区在任何档位都太高。三栏档修前 + // 面板 204→372px，版本列表被压到 2.4 行（110px）且底缘切在第三行图标上。 + // 现在走 Shared：面板先吃 `panel_budget`（按菜单行数推，M238），列表按**整行**取 + // （`whole_rows`，标定 44/97）⇒ 1180×760 列表 **132px = 3 整行**、面板 330px、 + // 滚动视口 98px（首屏 76 整块在屏）；900 档 264px = 6 整行、视口 106px。 + // 实例名与版本菜单都在面板钉死区（`options::section`）。 + (_, PanelState::Options(options)) if options.has_loader_versions() => Self::Shared, + _ => Self::Pinned, + } + } + + /// 列表视口该拿多少高（`None` = 面板按内容高钉死，列表吃剩下的 `Fill`）。 + /// + /// `column_height` 两个分支的入参口径一致：都传 + /// [`frame::body_height`](crate::pages::frame::body_height) 的返回值 + /// （chips 档上方那两行 chip 由 [`narrow_rows`] 自己扣，调用点不用管）。 + /// + /// `menu_items` 只有 `Shared` 档用得上（面板预算按版本菜单的行数推，见 [`panel_budget`]）； + /// 其余两支忽略它——调用点统一传 [`menu_items`] 的返回值即可。 + pub(crate) fn list_height(self, column_height: f32, menu_items: usize) -> Option { + match self { + Self::Pinned => None, + Self::Shared => Some(whole_rows(column_height, menu_items)), + Self::Narrow => Some(narrow_rows(column_height)), + } + } +} + +/// 版本行的**实测节距**（D30 三审：`04` 图行内下载图标的行首 265/309/353/397/441/485， +/// 节距恰 **44.0**；首行选中高亮矩形 253–296 也是 44px）。 +/// +/// 列表是 `Fill + scrollable` 时，视口高度不是节距整数倍就会切在某一行中间——D30 r2 实测 +/// `01` 是 245px（5.3 行），英文态露出 6px 竖干、中文态露出「预览版」上半截。`Shared` 与 +/// `Narrow` 两支都按整行取高，底缘落在行边界上。 +pub(crate) const ROW_PITCH: f32 = 44.0; + +/// 三栏档「列表以外、列内要扣掉的固定占位」（**列顶 156 → 列表顶 253**，D30 三审实测 = 97 +/// = 搜索条 56 + 间距 8 + 分隔线 1 + 间距 8 + 计数头 16 + 间距 8）。 +/// +/// 1180×760：正文列 580，面板按内容要 [`panel_budget`] ⇒ 列表 **132px = 3 整行**（M238 前是 +/// 176px = 4 整行，代价见 [`panel_budget`]）。 +/// **改搜索条 / 表头高度时要同步这个数。** +pub(crate) const LIST_CHROME: f32 = 97.0; + +/// 面板自身的上下内边距之和（`install::panel_with` 的 `Padding::from([Space::X3, 0])` = 12 + 12）。 +pub(crate) const PANEL_PAD_V: f32 = 24.0; + +/// 面板滚动区的**首屏**：head 40 + 间距 4 + 六枚 loader chip 32 = **76**。 +/// +/// 「首屏整块在屏」是本档的硬下限：低于它，chips 就被视口裁成一条缝（M238 实测 736×760 +/// 修前只剩 **10px**），而用户看不出「下面还有六枚 chip」——那正是 M227 在 chips 档消灭过的形态。 +pub(crate) const FIRST_SCREEN: f32 = 76.0; + +/// 选项区里「滚动区 ↔ 钉死区」的间距（`options::section` 的 `Space::X2`）。 +pub(crate) const SECTION_GAP: f32 = 8.0; + +/// `Shared` 档钉死区里**除版本菜单以外**的固定占位 = 说明/标签 16 + 间距 8 + 间距 8 + 实例名 56。 +pub(crate) const PINNED_CHROME: f32 = 88.0; + +/// 列表与面板之间那一层固定占位（`rows::content` 的 `tail`：间距 8 + 分隔线 1 + 间距 12）。 +pub(crate) const TAIL_CHROME: f32 = 21.0; + +/// 正文列高度 → 列表视口的**整行高度**（给三栏档的 `Shared` 分支用）。 +/// +/// 分高规则是「**面板按内容要够，剩下的按整行给列表**」——[`panel_budget`] 算的就是「够」 +/// （首屏 76 + 钉死区 + 面板内外边距），公式本身从 D30 起没变，变的是分子。 +/// +/// | 正文列 | 菜单行数 | 列表 | 面板 | 滚动视口 | +/// |---|---|---|---|---| +/// | 580（760 窗） | 2 行（≥2 条版本） | **132 = 3 整行** | 330 | **98** | +/// | 580 | 1 行（只有 1 条版本） | 176 = 4 整行 | 286 | 102 | +/// | 720（900 窗） | 2 行 | 264 = 6 整行 | 338 | 106 | +/// | 720 | 1 行 | 308 = 7 整行 | 294 | 110 | +/// +/// M238 之前这里钉死 `PANEL_BUDGET = 300`（不含 [`TAIL_CHROME`]）：760/900 档面板实得 +/// 286/294px，滚动视口被挤到 **54/62px**，六枚 chip 只露出 10px。预算必须**按内容推**， +/// 不能是一个跟菜单行数无关的常数。 +#[must_use] +pub(crate) fn whole_rows(column_height: f32, menu_items: usize) -> f32 { + let room = (column_height - LIST_CHROME - panel_budget(menu_items)).max(ROW_PITCH); + (room / ROW_PITCH).floor() * ROW_PITCH +} + +/// 三栏档面板「首屏整块 + 钉死区完整」要多少高（含列表↔面板那层 [`TAIL_CHROME`]）。 +/// +/// = 内边距 24 + 首屏 76 + 间距 8 + 钉死区（88 + 菜单高）+ 列表↔面板 21。 +/// +/// - 菜单 2 行（`≥2` 条加载器版本，`version_menu_height` 封顶两行）⇒ **329**； +/// - 菜单 1 行（只有一条）⇒ **281**。 +/// +/// 为什么把 [`TAIL_CHROME`] 算进来：它在**同一列**里吃高度，但不在面板盒子里。M238 前那个 +/// 300 没算它，于是「预算 300」实际只换来 **286px** 的面板（300 − 21 那层，再算上整行取整 +/// 多出的 7px），比面板需要的 308 少 22px——那 22px 就是从滚动视口里借的。 +#[must_use] +pub(crate) fn panel_budget(menu_items: usize) -> f32 { + PANEL_PAD_V + + FIRST_SCREEN + + SECTION_GAP + + PINNED_CHROME + + crate::pages::download::options::version_menu_height(menu_items) + + TAIL_CHROME +} + +/// 面板里那张版本菜单有几条（决定菜单高、进而决定 [`panel_budget`]）。 +/// +/// `0` = 这一态不画菜单（`Hint` / `Install` / 原版 / 不兼容 / 取不到版本表）；`Shared` 档只在 +/// `has_loader_versions()` 成立时才走，所以那里恒 ≥ 1。 +pub(crate) fn menu_items(state: &PanelState<'_>) -> usize { + match state { + PanelState::Options(options) => options.loader_version_count(), + PanelState::Hint | PanelState::Install(_) => 0, + } +} + +/// chips 档（可用宽 < 600）里 `rows::content` **上方**那一坨的实测高（M227）。 +/// +/// 分类 tabs 48 + 间距 8 + 主版本 chip 条 48 + 间距 8 + 分隔线 1 + 间距 8 = **121** +/// （720×760 实测：正文列顶 156 → `rows::content` 顶 277）。 +/// **改 `rails::stacked_chips` 的高度时同步这个数**（`Element` 没有几何内省，只能实测 + 常量）。 +pub(crate) const CHIPS_STACK: f32 = 121.0; + +/// chips 档里 `rows::content` 自身的固定占位（M227 实测）。 +/// +/// 列表之前：搜索条 56 + 间距 8 + 分隔线 1 + 间距 8 + 计数头 17 + 间距 8 = 98 +/// （实测内容顶 277 → 列表顶 375）；列表之后还要给尾部：间距 8 + 分隔线 1 + 间距 12 = 21 +/// （实测列表底 551 → 分隔线 559 → 面板顶 572）⇒ **119**。 +pub(crate) const CHIPS_LIST_CHROME: f32 = 119.0; + +/// chips 档里选项区**至少要拿到**的高度（M227 的窄档预算）。 +/// +/// 窄档的取舍：钉死区只留实例名，其余全进滚动区（`options::section` 的 `Narrow` 一支）。 +/// 预算 = 上下内边距 12×2 + 首屏内容 104 + 滚动区↔钉死区间距 8 + 实例名 56 = **192**； +/// 其中首屏 104 = head 40 + 间距 4 + 六枚 chip 32 + 间距 8 + 说明/标签行 20。 +/// +/// 为什么菜单在窄档**不钉**（三栏档是钉的）：700/720×760 的 `rows::content` 只有 **459**， +/// 若钉死区还要含菜单（说明 20 + 8 + 菜单 64~112 + 8 + 实例名 56 + 内边距 24 = 180~228）， +/// 再加首屏 head+chips 76 就是 256~304，列表只剩 ≤1 整行 —— 而 M125 的像素守门 +/// （`tests/options_shot/chips.rs` ②）要求 **≥3 整行 = 132**。两者在 459 里互斥， +/// 所以窄档把菜单放进滚动区（滚得到、滚动条可见），钉死区只留实例名。 +/// +/// 五审实测的坏形态（本预算要消灭的）：滚动区视口被钉死区吃成 **0**（五审记的「24px」其实是 +/// 面板内边距 12 + 间距 8 + 说明行顶端），head / 六枚 chip / 说明一个像素都不在屏； +/// 实例名输入框被挤成 **35px**（五审记 36），值墨迹的降部被自己的底边框裁掉。 +#[doc(alias = "窄档预算")] +pub(crate) const CHIPS_PANEL_BUDGET: f32 = 192.0; + +/// 正文列高度 → chips 档列表视口的**整行高度**（M227）。 +/// +/// 720×760：580 − 121（[`CHIPS_STACK`]）− 119（[`CHIPS_LIST_CHROME`]）− 192（[`CHIPS_PANEL_BUDGET`]） +/// = 148 ⇒ floor(148/44)×44 = **132px = 3 整行**；面板拿走剩下的 208（滚动区 120 ≥ 首屏 104）。 +/// 与 [`whole_rows`] 同一条公式，只是分子换成窄档的三段固定占位。 +#[must_use] +pub(crate) fn narrow_rows(column_height: f32) -> f32 { + let room = + (column_height - CHIPS_STACK - CHIPS_LIST_CHROME - CHIPS_PANEL_BUDGET).max(ROW_PITCH); + (room / ROW_PITCH).floor() * ROW_PITCH +} + +#[cfg(test)] +mod tests { + use super::*; + + /// 窄档预算的算术（M227）：760 档恰好 3 整行、面板剩下的高度够首屏 + 实例名。 + /// + /// 抓得住：把预算改小（列表涨到 4 整行 ⇒ 滚动区 < 首屏 104，说明行被切）或改大 + /// （列表掉到 2 整行 ⇒ M125 的像素守门 ② 红）。 + #[test] + fn the_chips_budget_keeps_three_whole_rows_at_760() { + let body = 580.0; // 760 − 标题栏 48 − 页头 84 − 上下页边距 48 + assert_eq!(narrow_rows(body), 132.0, "720×760 的 chips 档列表 = 3 整行"); + let panel = body - CHIPS_STACK - CHIPS_LIST_CHROME - narrow_rows(body); + assert_eq!(panel, 208.0, "面板拿剩下的那块"); + // 滚动区 = 面板 − 上下内边距 24 − 实例名 56 − 滚动区↔钉死区间距 8 + assert!( + panel - 24.0 - 56.0 - 8.0 >= 104.0, + "滚动区 {} < 首屏 104（head 40 + 4 + chips 32 + 8 + 说明 20）", + panel - 24.0 - 56.0 - 8.0 + ); + } + + /// **M238 的结构判据**：三栏档在 760 / 900 两档正文列下，面板的滚动视口都 ≥ 首屏 76。 + /// + /// 视口 = 面板高 − [`PANEL_PAD_V`] − [`SECTION_GAP`] − 钉死区（[`PINNED_CHROME`] + 菜单高）， + /// 面板高 = 正文列 − [`LIST_CHROME`] − 列表 − [`TAIL_CHROME`]。这条算术就是渲染层真正的 + /// 分高链路（`rails::three_column` → `rows::content` → `install::panel_with` → `options::section`）， + /// 每个加数都取自生产常量，不是测试里抄的副本。 + /// + /// 抓得住：把 `panel_budget` 退回「死的 300」（= M238 前的形态）⇒ 760 档视口 54、900 档 62， + /// 两条都红；把预算改成不含 [`TAIL_CHROME`] ⇒ 两者再各少 21；把 [`FIRST_SCREEN`] 调小 + /// （比如有人以为首屏只需 head + chips = 72）不明显红，但那属于口径调整，不属于回归。 + /// 抓不住：像素上 chips 到底露出几行（那要真图，见 `tests/options_shot/compact.rs`）； + /// 也不管 chips 档（`narrow_rows` 那一支另有它的钉子）。 + #[test] + fn the_three_column_panel_keeps_its_first_screen_at_760_and_900() { + let pinned = |items: usize| { + PINNED_CHROME + crate::pages::download::options::version_menu_height(items) + }; + let viewport = |body: f32, items: usize| { + let list = whole_rows(body, items); + let panel = body - LIST_CHROME - list - TAIL_CHROME; + panel - PANEL_PAD_V - SECTION_GAP - pinned(items) + }; + + // 硬判据先跑：**滚动视口 ≥ 首屏**（这是这条测试存在的理由，先红先看） + for (body, items) in [(580.0, 3), (580.0, 1), (720.0, 3), (720.0, 1)] { + assert!( + viewport(body, items) >= FIRST_SCREEN, + "正文列 {body} / 菜单 {items} 条：滚动视口只有 {}px < 首屏 {FIRST_SCREEN}px ⇒ \ + 六枚 chip 会被裁成一条缝（M238 修前 760 档实测 54px / chips 只露 10px）", + viewport(body, items) + ); + } + + // 紧接着钉住具体像素：它们让「视口够」不是靠偶然的取整余量。 + // 760 窗（正文列 580）：2 行菜单 = 3 整行列表；1 行菜单可以把第 4 行留下。 + assert_eq!( + whole_rows(580.0, 3), + 132.0, + "≥2 条版本 ⇒ 2 行菜单 ⇒ 3 整行列表" + ); + assert_eq!( + whole_rows(580.0, 1), + 176.0, + "只有 1 条版本 ⇒ 菜单 1 行 ⇒ 4 整行列表" + ); + assert_eq!(viewport(580.0, 3), 98.0); + assert_eq!(viewport(580.0, 1), 102.0); + + // 900 窗（正文列 720） + assert_eq!(whole_rows(720.0, 3), 264.0); + assert_eq!(whole_rows(720.0, 1), 308.0); + assert_eq!(viewport(720.0, 3), 106.0); + assert_eq!(viewport(720.0, 1), 110.0); + } + + /// 三栏档的预算**跟着菜单行数走**（M238）：菜单多一行，预算多 48，列表少一行。 + /// + /// 抓得住：`whole_rows` 的 `menu_items` 参数被忽略（两档预算相等）；`panel_budget` 漏掉 + /// [`TAIL_CHROME`]（329 → 308）；`PINNED_CHROME` 写小（那会让视口虚高、真图露馅）。 + #[test] + fn the_three_column_budget_follows_the_version_menu_height() { + assert_eq!(panel_budget(1), 281.0, "24 + 76 + 8 + 88 + 64 + 21"); + assert_eq!(panel_budget(2), 329.0, "菜单封顶两行 ⇒ 112"); + assert_eq!(panel_budget(3), panel_budget(2), "3 条以上也还是两行"); + assert_eq!(panel_budget(2) - panel_budget(1), 48.0, "一行的差 = 项高"); + } + + /// `list_height` 把三档的「列表吃多少」收敛到一处（`Pinned` = 不给定高）。 + #[test] + fn list_height_follows_the_share() { + assert_eq!(TailShare::Pinned.list_height(580.0, 0), None); + assert_eq!(TailShare::Shared.list_height(580.0, 3), Some(132.0)); + assert_eq!(TailShare::Narrow.list_height(580.0, 0), Some(132.0)); + } +} 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> { + 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..f864189 --- /dev/null +++ b/crates/app-iced/src/pages/download/tests.rs @@ -0,0 +1,310 @@ +//! 版本管理页的判据：**快照 → 模型 → 控件树**三段各自的断言。 +//! +//! 每条都写清「抓得住什么 / 抓不住什么」——这里只测纯转换与树能构建，**像素**由 +//! `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) -> 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 { + 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; + +// ------------------------------------------------- 选项区 × 三栏同屏（见 `tests/options_screen.rs`） + +mod options_screen; + +// ------------------------------------------------- 选项区 × 三栏的像素断言（见 `tests/options_shot.rs`） + +mod options_shot; 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..348af6c --- /dev/null +++ b/crates/app-iced/src/pages/download/tests/i18n.rs @@ -0,0 +1,108 @@ +//! 下载页的**文案守门**（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; 12] = [ + 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"), + // M125：主版本栏搬进 `rails/major.rs`（`VersionMajorTitle` / `VersionMajorAll` 的落点） + include_str!("../rails/major.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/options_screen.rs b/crates/app-iced/src/pages/download/tests/options_screen.rs new file mode 100644 index 0000000..8ef8bd0 --- /dev/null +++ b/crates/app-iced/src/pages/download/tests/options_screen.rs @@ -0,0 +1,188 @@ +//! 安装选项区 × 三栏**同屏**（M123 ①）：宽度怎么分、窄窗怎么退化、选项区在不在同一棵树里。 +//! +//! ## 为什么这条测试必须存在 +//! +//! 「安装选项区」（`download/options`）与「三栏」（`download/rails`）各自都出过图、也各自都有 +//! 断言，但它们**同屏**这件事从来没被验过。选项区挤在列表列的最底下：它一高，列表就矮； +//! 窗口一窄，两条栏一收，列表就窄。这两种挤压都不会让任何既有断言变红——那些断言分别只看 +//! 「宽度裁决的数字」「选项区的纯决策」「树能构建出来」，没有一条把它们放在同一屏里看。 +//! +//! ## 抓得住什么 / 抓不住什么 +//! +//! 抓得住：①七档宽度下 `VersionRails` 的三栏数字与 `pages/layout/rails.rs` 模块文档的表逐格一致； +//! ②选项区的三种状态（原版 / Fabric / 不兼容）在**每一档**上都能与两份侧栏的数据一起构建出树， +//! 而且列表列**从不低于** [`version_list_min_width`]（= 424：行内「版本号 + 类型 + 日期 + 安装」 +//! 四样仍在一行，不会因为宽度而折行/裁字）；③`Chips` 档两条栏归零、列表吃满可用宽（退化是 +//! 逐档下沉，不是「挤一挤」）。 +//! +//! 抓不住：**画出来长什么样**——两栏是不是真同屏、选项区有没有被窗口底边切掉、某一格文本会不会 +//! 仍被裁。前两条由同目录的 `tests/options_shot.rs`（像素断言，需 `ULL_DL_OPTIONS_SHOT`）在真 PNG +//! 上验证，文本本身由 `DevDocs/artifacts/m123/` 的图人工看。 +//! 更根本的一条：**没有 iced 的渲染器就拿不到布局**（`Element::layout` 要 `&Renderer`，而本 crate +//! 的 `Renderer` 在 `gpu` feature 下是 wgpu/tiny-skia 的 `fallback::Renderer`，测试里构造不出来）， +//! 所以这里断的是**喂给树的模型 + 裁决出来的数字**，不是 iced 亲手算的矩形。 + +use iced::Element; +use unlucky_i18n::Lang; +use unlucky_presenter::dto::{AncientKind, AppEvent, CoreEvent, VersionKind, VersionSummary}; +use unlucky_presenter::state::AppState; + +use crate::pages::download::model::{Category, Download}; +use crate::pages::download::{view, InstallDraft, Loader, Message}; +use crate::pages::layout::rails::version_list_min_width; +use crate::pages::layout::{frame_metrics, PaneKit, VersionRailTier, VersionRails}; + +use super::ui; + +/// 一档宽度的期望（数字来源：`pages/layout/rails.rs` 模块文档 §4 的数值表）。 +/// +/// 表里每一格都写死，**不**从被策源反算——否则「裁决算错了」与「表抄错了」会互相掩护。 +const WIDTHS: [(f32, VersionRailTier, f32, f32, f32); 7] = [ + (1180.0, VersionRailTier::Wide, 140.0, 140.0, 716.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), + // 812 = `Narrow` 档的门槛：类型栏已收成 64，列表仍停在 424 + (812.0, VersionRailTier::Narrow, 64.0, 140.0, 424.0), + // 736 = `Compact` 档：两条栏都收成 64，列表仍停在 424 + (736.0, VersionRailTier::Compact, 64.0, 64.0, 424.0), + // 700 = `Chips` 档：三栏不成立，列表吃满可用宽 + (700.0, VersionRailTier::Chips, 0.0, 0.0, 564.0), +]; + +/// 出图那一屏的演示版本表（三种形态就够：正式 / 预览 / 远古，两条侧栏都有内容）。 +fn versions() -> Vec { + fn row(id: &str, kind: VersionKind) -> VersionSummary { + VersionSummary { + id: id.to_string(), + kind, + released: "2026-09-20".to_string(), + installed: false, + } + } + + vec![ + row("1.21.9", VersionKind::Release), + row("1.20.4", VersionKind::Release), + row("24w14a", VersionKind::Snapshot), + row("rd-132211", VersionKind::Ancient(AncientKind::Classic)), + ] +} + +/// 选项态模型：`AppState` + 草稿 → **产品那条真转换**（与 `demo::options` 同一条路径）。 +/// +/// `cached` = 加载器版本列表（Fabric 那一屏才有；它是选项区里最高的一段，也正是「面板一高 +/// 列表就矮」的那一态）。 +fn options_model(version: &str, loader: Loader, cached: Option<&[&str]>) -> Download { + let catalog = Lang::En.catalog(); + let mut state = AppState::new(); + state.apply(AppEvent::Core(CoreEvent::VersionListChanged(versions()))); + if let Some(items) = cached { + state.apply(AppEvent::Core(CoreEvent::LoaderVersions { + kind: loader.kind(), + mc_version: version.to_string(), + result: Ok(items.iter().map(|item| (*item).to_string()).collect()), + })); + } + let draft = InstallDraft { + selected: Some(version.to_string()), + loader, + ..InstallDraft::default() + }; + Download::from_snapshot(&state, Category::All, &draft, catalog) +} + +/// 选项区的三种取样（原版 / Fabric 带版本列表 / NeoForge 对远古版不兼容）。 +fn samples() -> [(&'static str, Download); 3] { + [ + ("options", options_model("1.21.9", Loader::Vanilla, None)), + ( + "options-fabric", + options_model( + "1.21.9", + Loader::Fabric, + Some(&["0.16.5", "0.16.4", "0.15.11"]), + ), + ), + ( + "options-incompat", + options_model("rd-132211", Loader::NeoForge, None), + ), + ] +} + +/// 七档宽度 × 三种选项态：三栏数字一致、树能构建、列表列不被挤到 424 以下。 +/// +/// 424 这条是「不裁字」的宽度侧前提：行内四样的最小宽 `layout::rails::version_row_min_width()` +/// = 412 < 424，所以只要列表列 ≥ 424，版本号那一格就还有 12px 余量，四样不会折行。 +#[test] +fn the_options_state_keeps_all_three_columns_at_every_width() { + let ui = ui(); + let floor = version_list_min_width(); + let samples = samples(); + + for (width, tier, type_rail, major_rail, list) in WIDTHS { + let metrics = frame_metrics(PaneKit::Single, width); + let rails = VersionRails::of_metrics(metrics); + + assert_eq!(rails.tier, tier, "{width} 的档位"); + assert!((rails.type_rail - type_rail).abs() < 0.01, "{width} 类型栏"); + assert!( + (rails.major_rail - major_rail).abs() < 0.01, + "{width} 主版本栏" + ); + assert!((rails.list - list).abs() < 0.01, "{width} 列表列"); + assert!( + rails.list >= floor - 0.01, + "{width}：列表列 {} 低于行宽下限 {floor} ⇒ 行内四样会折行/裁字", + rails.list + ); + // 三栏档两条栏都 >0（同屏的前提）；Chips 档两条都归零、列表吃满（逐档下沉） + if rails.tier.is_three_column() { + assert!(rails.type_rail > 0.0 && rails.major_rail > 0.0, "{width}"); + } else { + assert_eq!((rails.type_rail, rails.major_rail), (0.0, 0.0), "{width}"); + } + + for (name, model) in &samples { + // 同一份模型里：两条栏的内容（4 个类型 / 主版本桶）+ 行 + 选项面板都在 + assert_eq!(Category::ALL.len(), 4, "第一栏是四个固定项"); + assert!(!model.buckets.is_empty(), "{name}@{width} 第二栏没有桶"); + assert!(!model.rows.is_empty(), "{name}@{width} 列表没有行"); + assert!( + model.options.is_some(), + "{name}@{width} 面板不是选项态——这张图就不再是「选项区 × 三栏」" + ); + // 树真的建得出来（两栏 + 列表 + 面板同一次装配） + let _: Element<'_, Message> = view(&ui, metrics, model, Lang::En); + } + } +} + +/// 窄窗退化是**逐档下沉**：类型栏先成图标条、再两条都成图标条，列表列在两种情形下都不低于 424。 +/// +/// 抓得住：某天有人为了「窄窗也放得下两条栏」把 64 改成 48 或把列表下限往下调 —— 那时这里的 +/// 逐档数字会先红。抓不住：图标条里的 tooltip 在真机上是否弹得出来（静态图拍不到 hover 层）。 +#[test] +fn the_narrow_tiers_step_down_before_they_squeeze_the_list() { + let mut previous = VersionRails::of_metrics(frame_metrics(PaneKit::Single, 2400.0)); + assert_eq!(previous.tier, VersionRailTier::Wide); + + for width in [1600.0, 1180.0, 1024.0, 900.0, 812.0, 736.0, 700.0, 600.0] { + let rails = VersionRails::of_metrics(frame_metrics(PaneKit::Single, width)); + // 档位只降不升，且降档时**收的是侧栏**，列表不会在降档的那一格突然变窄再变宽 + assert!( + rails.list >= version_list_min_width() - 0.01, + "{width}：列表列 {} 跌破 424", + rails.list + ); + if rails.tier.is_three_column() && previous.tier.is_three_column() { + assert!( + rails.type_rail <= previous.type_rail + 0.01 + && rails.major_rail <= previous.major_rail + 0.01, + "{width}：侧栏在宽窗上反而变宽了" + ); + } + previous = rails; + } +} diff --git a/crates/app-iced/src/pages/download/tests/options_shot.rs b/crates/app-iced/src/pages/download/tests/options_shot.rs new file mode 100644 index 0000000..24f42b6 --- /dev/null +++ b/crates/app-iced/src/pages/download/tests/options_shot.rs @@ -0,0 +1,375 @@ +//! 选项区 × 三栏的**像素**验收（M123 ①）：真 PNG 上的几何断言。 +//! +//! ## 为什么还要一条像素测试 +//! +//! [`super::options_screen`] 断的是「喂给树的模型 + 裁决出来的数字」，它抓不住**画出来**： +//! 两栏是不是真同屏、栏宽有没有按裁决落地、版本行有没有被压成一条缝、确认键是不是还在屏内。 +//! 那些只有图能回答——所以这里直接量 `pages_demo` 出的 PNG，按**产品自己的裁决函数** +//! （[`VersionRails::of_metrics`] + [`frame_metrics`]）推出每一栏该在的 x 区间，再要求像素同意。 +//! +//! ## 开关与跑法（`ULL_DL_*_SHOT` 喂图，四条出图命令见 `feed.rs` 的模块文档） +//! +//! 四条断言都靠环境变量拿到一张真 PNG。M127 之前的写法是「没有图就 SKIP」，于是在 CI 里 +//! **全是空跑**（`.github/` 里 grep 这些变量零命中）。现在按环境分档： +//! +//! - **只在 Windows runner 上跑**：断言量的行高/墨迹条数/药丸位置是按本仓字体栈 +//! （`Segoe UI`）标定的，Linux/macOS 的回退字体会让这些数字变样 ⇒ 假红。这条限制同时写在 +//! `.github/workflows/ci.yml` 的作业条件（`if: runner.os == 'Windows'`，出图与断言两步都带） +//! 和 `feed.rs` 的模块文档里，不靠「碰巧只配了一处」。 +//! - **CI 里没喂图 = 失败**，提示「守门未喂图」：将来谁把 CI 里出图那步重构掉，构建会红， +//! 而不是静静退回手动档。本机（非 CI）才允许跳过，并且会留一句提示。 +//! +//! 颜色**不**写死：`run_at` 只要求「同一段颜色连续」，栏与栏的边界按「颜色变了」判， +//! 于是浅色/深色都能跑同一条断言（实测浅色下 Card=(235,245,255)、Canvas=(246,250,255)）。 + +use unlucky_design::color::SchemeFlavor; +use unlucky_design::typography::Platform; + +use crate::pages::layout::rails::RAIL_GAP; +use crate::pages::layout::{available_width, frame_metrics, PaneKit, VersionRails}; +use crate::theme::{Families, Ui}; + +const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", +}; + +/// 1180 宽那张（`01-options-fabric-en-light.png`）。 +const WIDE_SHOT: &str = "ULL_DL_OPTIONS_SHOT"; +/// 700 宽那张（`02-options-fabric-en-light-chips700.png`）——chips 档回归守门用。 +const CHIPS_SHOT: &str = "ULL_DL_CHIPS_SHOT"; +/// 736 宽那张（`04-options-fabric-en-light-compact736.png`）——Compact 档主版本栏用。 +const COMPACT_SHOT: &str = "ULL_DL_COMPACT_SHOT"; +/// 700 宽、**不设 `ULL_DL_DEMO`**（= `ready`，还没选版本）那张——r1 复审 P2-1 的守门用。 +const READY_SHOT: &str = "ULL_DL_READY_SHOT"; + +fn ui() -> Ui { + Ui::with_platform(SchemeFlavor::Light, Platform::Windows, FAMILIES) +} + +/// 一张 RGB 图（只留本文件要用的那两件事：宽高 + 取点）。 +struct Shot { + width: usize, + height: usize, + pixels: Vec<[u8; 3]>, +} + +impl Shot { + fn load(path: &std::path::Path) -> Self { + let bytes = std::fs::read(path).expect("读截图"); + let image = image::load_from_memory(&bytes).expect("解 PNG").to_rgb8(); + let (width, height) = (image.width() as usize, image.height() as usize); + Self { + width, + height, + pixels: image.pixels().map(|pixel| pixel.0).collect(), + } + } + + fn at(&self, x: usize, y: usize) -> [u8; 3] { + self.pixels[y * self.width + x] + } + + /// `(起点, 长度)`：`(x, y)` 所在的那一段**同色**横条。 + fn run_at(&self, x: usize, y: usize) -> (usize, usize) { + let color = self.at(x, y); + let mut start = x; + while start > 0 && self.at(start - 1, y) == color { + start -= 1; + } + let mut end = x; + while end + 1 < self.width && self.at(end + 1, y) == color { + end += 1; + } + (start, end - start + 1) + } + + /// 在 `x` 这一竖列上，`[from, to)` 里**第一段**与 `background` 不同的连续区：`(top, height)`。 + /// + /// 用它量「第一行版本行有多高」：选中行有底色，行外是页面底色，两段一夹就是行高。 + fn first_filled_band( + &self, + x: usize, + from: usize, + to: usize, + background: [u8; 3], + ) -> Option<(usize, usize)> { + let filled = |y: usize| self.at(x, y) != background; + let top = (from..to.min(self.height)).find(|y| filled(*y))?; + let mut bottom = top; + while bottom + 1 < to.min(self.height) && filled(bottom + 1) { + bottom += 1; + } + Some((top, bottom - top + 1)) + } + + /// `[from, to)` 里最长的一段**同色**横条：`(y, 长度)`（颜色必须与底色不同）。 + /// + /// 用它找面板里那条实心「安装」按钮：它是列表列里唯一一条 ≥ 80px 的实色带。 + fn longest_run( + &self, + left: usize, + right: usize, + from: usize, + to: usize, + background: [u8; 3], + ) -> (usize, usize) { + let mut best = (0, 0); + for y in from..to.min(self.height) { + let mut run = 0; + let mut color = background; + for x in left..right { + let pixel = self.at(x, y); + if pixel == background { + color = background; + run = 0; + } else if pixel == color { + run += 1; + } else { + color = pixel; + run = 1; + } + if run > best.1 { + best = (y, run); + } + } + } + best + } + + /// 列表列里最后一行**有内容**的 y（`None` = 整列都是底色）。 + fn last_ink_row(&self, left: usize, right: usize, background: [u8; 3]) -> Option { + (0..self.height).rev().find(|y| { + (left..right).any(|x| { + let pixel = self.at(x, *y); + pixel + .iter() + .zip(background) + .map(|(a, b)| u32::from(a.abs_diff(b))) + .sum::() + > 12 + }) + }) + } + + /// `y` 这一行上、含 `x` 的那段**连续非底色**区：`(起点, 长度)`。 + /// + /// 与 [`Shot::run_at`] 的区别：颜色可以变（药丸底色 + 里面的图标墨迹算同一块）。 + fn fill_run( + &self, + y: usize, + left: usize, + right: usize, + x: usize, + background: [u8; 3], + ) -> (usize, usize) { + let filled = |x: usize| self.at(x, y) != background; + let mut start = x; + while start > left && filled(start - 1) { + start -= 1; + } + let mut end = x; + while end + 1 < right && filled(end + 1) { + end += 1; + } + (start, end - start + 1) + } + + /// `[from, to)` 里在 `[left, right)` 有墨迹的**条数**（两条之间空 ≥ 8 行才算两条）。 + /// + /// 用它数「读得出几个版本号」：一行版本号的文本墨迹约 11px 高、行距 44，中间空 30+ ⇒ + /// 一条对应一行。被压扁时整块只剩一条。 + fn ink_bands( + &self, + left: usize, + right: usize, + from: usize, + to: usize, + background: [u8; 3], + ) -> usize { + let mut bands = 0; + let mut gap = usize::MAX; + for y in from..to.min(self.height) { + let inked = (left..right).any(|x| self.at(x, y) != background); + if inked { + if gap >= 8 { + bands += 1; + } + gap = 0; + } else { + gap = gap.saturating_add(1); + } + } + bands + } + + /// 列表列里、`from` 起的**第一条薄通栏横线**的 y（`divider::full` 画的那条 1px 线）。 + /// + /// 用它量「版本列表到哪儿为止」：尾部面板上沿有一条通栏分隔线，它上面的高度就是列表拿到的。 + /// 只认**薄**线（上下两行都与它不同色）——选中行的底色带也是通栏的，那是 44px 的块，不是线。 + fn first_rule_y( + &self, + left: usize, + right: usize, + from: usize, + background: [u8; 3], + ) -> Option { + let thin = |y: usize| { + let color = self.at(left + 2, y); + color != background + && (left + 2..right.saturating_sub(2)).all(|x| self.at(x, y) == color) + && (y == 0 || self.at(left + 2, y - 1) != color) + && (y + 1 >= self.height || self.at(left + 2, y + 1) != color) + }; + (from..self.height).find(|y| thin(*y)) + } +} + +/// 三栏的 x 区间，全部从**产品自己的裁决函数**推出来（不是手抄的像素坐标）。 +struct Bands { + type_rail: (usize, f32), + major_rail: (usize, f32), + list: (usize, f32), +} + +fn bands(width: f32) -> Bands { + let ui = ui(); + let rails = VersionRails::of_metrics(frame_metrics(PaneKit::Single, width)); + // 可用宽 = 窗口 − 导航轨 − 两侧页边距 ⇒ 页边距反推出来（只有左侧那一份进左缘） + let avail = available_width(width); + let gutter = (width - avail - ui.metrics().nav_rail_width) / 2.0; + assert!( + (gutter - 24.0).abs() < 0.01, + "页边距应当是一格 24：{gutter}" + ); + let left = (width - avail - gutter).round() as usize; + assert_eq!( + left, + (ui.metrics().nav_rail_width + gutter).round() as usize, + "页左缘 = 导航轨 + 一格页边距" + ); + assert_eq!(left, 112, "harness 的导航轨 88 + 页边距 24"); + let type_rail = (left, rails.type_rail); + let major_rail = ( + left + rails.type_rail as usize + RAIL_GAP as usize, + rails.major_rail, + ); + // chips 档没有两条侧栏（宽度都是 0）：列表就是整条可用宽，左缘 = 页左缘。 + // 不分支的话会算成 `112 + 0 + 24 + 0 + 24 = 160`，右缘跟着冲出画面 22px + // （M125 缺陷 1 的守门就是在这里踩到「扫描越界读下一行像素」的）。 + let list = if rails.tier.is_three_column() { + ( + major_rail.0 + rails.major_rail as usize + RAIL_GAP as usize, + rails.list, + ) + } else { + (left, rails.list) + }; + Bands { + type_rail, + major_rail, + list, + } +} + +/// `01-options-fabric-en-light.png`（1180×760）上的四条断言。 +/// +/// 抓得住：①两条侧栏**同时**在同一条扫描线上画出来（不是只有一条、也不是其中一条塌成 0 宽）； +/// ②两条栏各自的像素宽度 = `VersionRails` 裁决出来的 140/140，栏间 24 的缝真的空着（栏没有重叠）； +/// ③版本行至少有一行**完整**（44 = `row_height`），即列表没有被面板压成「缝」； +/// ④选项区的确认键与「实例名」都在屏内（列表列最下面一行墨迹离窗口底边还有余量）。 +/// +/// 抓不住：文本有没有被裁（那要看字形宽度，见报告「没验的部分」）、hover/tooltip 层（静态图拍不到）、 +/// 深色主题下的对比度（本条只跑浅色图；深色另用同一 argv 换 `--screenshot-theme` 出图人看）。 +#[test] +fn an_options_shot_shows_both_rails_and_the_whole_panel() { + let Some(path) = feed(WIDE_SHOT) else { + return; + }; + let shot = Shot::load(&path); + assert_eq!( + (shot.width, shot.height), + (1180, 760), + "验收图必须 1180×760" + ); + + let bands = bands(1180.0); + let ui = ui(); + let y = 400; + + // ① 两条栏同时画在同一条扫描线上，且宽度 = 裁决值（像素边界一条不差） + for (name, (start, width)) in [("类型栏", bands.type_rail), ("主版本栏", bands.major_rail)] + { + let (run_start, run_len) = shot.run_at(start + 8, y); + assert_eq!( + (run_start, run_len as f32), + (start, width), + "{name}：像素区间与 `VersionRails` 裁决不一致（y={y}）" + ); + assert_ne!( + shot.at(start, y), + shot.at(start.saturating_sub(1), y), + "{name}：左缘没有边界" + ); + } + // 栏间 24 的缝真的空着（两条栏没有叠在一起），且列表列不是面板底色 + let gap_x = bands.type_rail.0 + bands.type_rail.1 as usize + RAIL_GAP as usize / 2; + assert_eq!( + shot.at(gap_x, y), + shot.at(gap_x - 1, y), + "两栏之间的缝被填掉了（栏重叠或间距丢失）" + ); + assert_ne!( + shot.at(gap_x, y), + shot.at(bands.type_rail.0, y), + "缝与栏同色 ⇒ 读不出「两条栏」" + ); + assert_ne!( + shot.at(bands.list.0 + 8, y), + shot.at(bands.major_rail.0, y), + "列表列被侧栏底色盖住了" + ); + + // ③ 完整的一行版本行：第一行（选中行）的底色带必须正好一行高（`row_height` = 44） + let canvas = shot.at(bands.list.0 + 2, 12); + let (_, row_height) = shot + .first_filled_band(bands.list.0 + 60, 235, 520, canvas) + .expect("列表列里应当有版本行"); + assert_eq!( + row_height as f32, + ui.metrics().row_height, + "版本行被裁/被压：实测可视行高 {row_height}，应为 {}", + ui.metrics().row_height + ); + + // ④ 选项区整块在屏内：列表列最下面的墨迹离底边还有余量（被切的话它会贴到 759） + let last = shot + .last_ink_row( + bands.list.0, + bands.list.0 + bands.list.1 as usize - 2, + canvas, + ) + .expect("列表列里应当有内容"); + assert!( + last + 8 < shot.height, + "选项区被窗口底边切掉：最后一行墨迹在 y={last}（图高 {}）", + shot.height + ); + assert!( + last > 600, + "选项区不在屏上：最后一行墨迹在 y={last}，解析应当有「实例名」那一格" + ); +} + +// ---- chips 档（缺陷 1）与 Compact 档（缺陷 2）的像素守门（拆出来守 400 行红线） + +mod chips; + +mod compact; + +mod feed; + +mod ready; + +use feed::feed; diff --git a/crates/app-iced/src/pages/download/tests/options_shot/chips.rs b/crates/app-iced/src/pages/download/tests/options_shot/chips.rs new file mode 100644 index 0000000..333a4ba --- /dev/null +++ b/crates/app-iced/src/pages/download/tests/options_shot/chips.rs @@ -0,0 +1,80 @@ +//! Chips 档（窗口 < 736、可用宽 < 600）的像素守门：M125 缺陷 1。 + +use super::{bands, feed, ui, Shot, CHIPS_SHOT}; + +/// `02-…-chips700.png`（700×760，`ULL_DL_CHIPS_SHOT`）——**M125 缺陷 1 的回归守门**。 +/// +/// 修前（M123 取证，2026-11-05，tiny-skia，700×760，`ULL_DL_DEMO=options-fabric`）： +/// chips 档多出两行 chip，选项区又整块钉在列表下面（316px），于是列表列只剩一条 **18px** 的缝， +/// 选中行的底色带实测 19px（行高 44）——版本号一个字读不出来，用户换不了版本。 +/// 修法见 `rows::TailShare`：chips 档改成「面板先保预算、列表按整行吃剩下的」 +/// （M227 起是 `TailShare::Narrow` + `rows/tail.rs::CHIPS_PANEL_BUDGET`，700/720×760 = 3 整行）。 +/// +/// ```text +/// ULL_DL_CHIPS_SHOT=02-options-fabric-en-light-chips700.png \ +/// cargo test -p unlucky-app-iced --lib options_shot +/// ``` +/// +/// 抓得住：①首行版本行的底色带 = 44（整行在屏）；②**列表区 ≥ 3 整行**（面板上沿那条通栏 +/// 分隔线就是下界）——这是窄档预算的硬下限：面板钉死区若重新钉住版本菜单（M227 之前的样子）， +/// 它在 459px 里只能再留 1 整行给列表；③面板头部在屏：断言在面板上沿分隔线下方 96px 的窗口 +/// （分隔线 514 ⇒ 窗口 518–610）里找一条 ≥ 80px 的同色带，窄档实测命中 **y=550、宽 94px**， +/// 那是**实心「安装」按钮的药丸本身**——版本菜单容器的上沿在 636–639，落在窗口之外，与本条无关 +/// （r2 复审订正：旧注释把「菜单容器的满宽底边」也列成可能来源，那是错的）。 +/// 「能换版本」与「能看见选项面板」是这条断言的成对验收。 +/// +/// 抓不住：文本有没有被**横向**裁掉（那要看字形宽度，见 `tests/rails.rs` 的标签断言与 +/// 报告里的量测表）、hover/tooltip 层（静态图拍不到）、面板内部滚动到底后长什么样 +/// （静态图只有一帧，只能拍到 scroll offset 0）——所以这里**不**断言「面板没被窗口底边切」： +/// chips 档的面板本来自己可滚，实例名钉在面板底部。**M227 起**滚动区首屏装 +/// head + 六枚 chip + 说明行（104px），版本菜单露在折线下方、滚得到。 +#[test] +fn a_chips_tier_shot_keeps_a_whole_version_row_readable() { + let Some(path) = feed(CHIPS_SHOT) else { + return; + }; + let shot = Shot::load(&path); + let bands = bands(700.0); + let canvas = shot.at(bands.list.0 + 2, 12); + let metrics = ui().metrics(); + + // ① 首行整行 44：这是 M123 原本写的那条（修好之后解 ignore，不许改期望值迁就现状） + let (row_top, row_height) = shot + .first_filled_band(bands.list.0 + 60, 360, 440, canvas) + .expect("列表列里应当有版本行"); + assert_eq!( + row_height as f32, metrics.row_height, + "Chips 档的版本行被压成 {row_height}px（应为 {}）", + metrics.row_height + ); + + // ② 版本列表那一块至少 3 整行高：尾部面板上沿的通栏分隔线就是列表的下界 + let right = bands.list.0 + bands.list.1 as usize - 2; + let rule = shot + .first_rule_y(bands.list.0, right, row_top, canvas) + .expect("找不到尾部面板上沿的分隔线（列表区的下界量不出来）"); + let rows_px = rule.saturating_sub(row_top) as f32; + assert!( + rows_px >= 3.0 * metrics.row_height, + "Chips 档的列表区只有 {rows_px}px（y={row_top}..{rule}），不足 3 整行（{}）：\ + 尾部面板把列表压扁了", + 3.0 * metrics.row_height + ); + + // ③ 面板在屏内：分隔线下面紧接着就是面板的头（那条实心「安装」按钮 = 一条 ≥ 80px 的实色带） + let (y, run) = shot.longest_run(bands.list.0, right, rule + 4, rule + 96, canvas); + assert!( + run >= 80, + "选项面板没画出来：分隔线 y={rule} 下方 96px 里最长只有 {run}px 的同色带（y={y}），\ + 看不到那条实心「安装」按钮" + ); + + // ④ 面板确实占了下半块（列表区的下界以上都归列表，以下归面板） + let last = shot + .last_ink_row(bands.list.0, right, canvas) + .expect("列表列里应当有内容"); + assert!( + last > rule + 100, + "选项面板没有占到下半块：最后一行墨迹在 y={last}，面板上沿在 y={rule}" + ); +} diff --git a/crates/app-iced/src/pages/download/tests/options_shot/compact.rs b/crates/app-iced/src/pages/download/tests/options_shot/compact.rs new file mode 100644 index 0000000..5d3865d --- /dev/null +++ b/crates/app-iced/src/pages/download/tests/options_shot/compact.rs @@ -0,0 +1,245 @@ +//! Compact 档（可用宽 600~675）的像素守门：M125 缺陷 2（主版本栏）+ M238（面板首屏 / 阴影越界）。 +//! +//! M238 两条都钉在**同一张 736×760 图**上（`04-…-compact736.png`）： +//! ①六枚 loader chip 整枚在屏（修前被面板预算挤得只剩 10px 高的上缘）； +//! ②版本菜单的 L2 阴影不许漏出滚动视口、压暗下面钉死区的实例名（修前浅色画面布 `(249,249,250)` +//! 被压成 `(231,231,232)`，−7.2%）。 + +use unlucky_design::color::Role; + +use super::{bands, feed, ui, Shot, COMPACT_SHOT}; + +/// iced 的 `Color` → 截图里的 8 位 RGB（tiny-skia 侧就是 `round(分量 × 255)`，截图不带 α）。 +fn rgb(color: iced::Color) -> [u8; 3] { + let channel = |value: f32| (value.clamp(0.0, 1.0) * 255.0).round() as u8; + [channel(color.r), channel(color.g), channel(color.b)] +} + +/// `y` 这一行里有多少段（每段 ≥ [`PILL_RUN_MIN`]）与 `color` 同色的连续像素。 +/// +/// 用来区分「一排药丸的描边」与「一条通栏分隔线」：两者可能是同一个颜色（分隔线也用 +/// `OutlineVariant`），但药丸是**多段**、分隔线是**一段通到底**。 +fn pill_runs(shot: &Shot, y: usize, left: usize, right: usize, color: [u8; 3]) -> usize { + let (mut runs, mut run) = (0, 0); + for x in left..right { + if shot.at(x, y) == color { + run += 1; + } else { + if run >= PILL_RUN_MIN { + runs += 1; + } + run = 0; + } + } + if run >= PILL_RUN_MIN { + runs += 1; + } + runs +} + +/// 药丸描边那一段的最小长度：32 高的圆角药丸（半径 16）在顶边/底边留下的直线段约 28~68px， +/// 取 16 足以跨过圆角收缩，又能甩掉侧边那 1px 竖线。 +const PILL_RUN_MIN: usize = 16; + +/// `y` 这一行在 `[left, right)` 里是否**整行同色**；是则给出那个颜色。 +fn uniform_row(shot: &Shot, y: usize, left: usize, right: usize) -> Option<[u8; 3]> { + let color = shot.at(left, y); + (left..right) + .all(|x| shot.at(x, y) == color) + .then_some(color) +} + +/// `04-…-compact736.png`（736×760，`ULL_DL_COMPACT_SHOT`）——**Compact 档主版本栏（缺陷 2）**。 +/// +/// 修前（M123 取证；本文件作者在 736×760 那张图上逐项量过）：主版本栏宽 64，`ListItem` +/// 两侧内边距各 16 ⇒ 文本格 **32**（x=216..247，裁切边 248）： +/// +/// | 标签 | 墨迹 | 结论 | +/// |---|---|---| +/// | `1.21` | 26px | 完整（余 6） | +/// | `1.20` | 28px | 完整（余 4） | +/// | `24w` | 29px | 完整（余 3，最紧） | +/// | `All versions` | 画到 x=247（裁切边 248） | **被切**：只剩「All v」 | +/// | `全部版本` | 4 全角字 = 64 > 32 | **被切**：只剩「全部」且顶到边 | +/// +/// 即桶标签的余量是 **3~6px**，而「全部版本」这条根本放不下。 +/// +/// 修后：图标条档的「全部版本」**不画文字**（`rails::major_shape` 的 `Icon` 分支）—— +/// 画成文档/清单字形（40×40 `Tonal` 药丸 + 全称 tooltip）。**不是**第一级那个网格： +/// 两条 64 栏相邻，同字形 + 同药丸会让「全部类型」与「全部版本」像素级同形（r1 复审 P3-1）。 +/// +/// 抓得住：①首项是 **40×40 的图标药丸**（不是 64 宽 × 44 高的通栏文字行）——谁把它改回 +/// 「画文字」（全称或短标签都会是通栏 44 行）这条立刻红；②药丸在 64 栏里**居中**（左右各 12）。 +/// 抓不住：图标字形对不对、tooltip 长什么样（静态图拍不到 tooltip；字形要看图）。 +/// +/// ## 为什么不用「文字墨迹右边界 ≤ 栏右内边界」这条（复审建议的那条） +/// +/// 它**在坏图上也是绿的**：修前那张图实测首项文字墨迹 x=216..247，而栏右内边界是 +/// `200 + 64 − 16 = 248` ⇒ 247 ≤ 248 成立（只剩 1px 余量）——「All **v**」明明被裁掉了， +/// 断言却过。这条比 r1 报告里写的更极端：差 1px 而不是 4px。 +/// 原因是 `ListItem` 的 `clip(true)` 让墨迹**永远**停在裁切边之前，边界的比较量不出「被裁」。 +/// 所以这里改钉**形状**：文字行是 64×44 的通栏带，图标按钮是 40×40 的居中药丸，两者像素可分。 +/// +/// **中文为什么没有同档图**：本仓的截图通道 `pages::demo_model` 把 `Model::new(..)` 的 +/// `lang` 写死成 `Lang::En`（`pages/model.rs:120`），`ULL_LANG` 只作用到 app 的 `App`， +/// 拍不出中文页面 —— 所以中文的结论走「数据面断言 + 算术」： +/// `tests/rails.rs` 的 `only_the_first_major_entry_switches_to_an_icon_in_the_icon_rail` +/// （中文与英文走**同一条**图标分支，键判据 `entry.key.is_none()` 与语言无关）与 +/// `the_icon_rail_text_box_is_32_and_only_bucket_labels_fit`（「全部版本」= 64 > 32）。 +#[test] +fn a_compact_tier_shot_draws_an_icon_for_the_first_major_entry() { + let Some(path) = feed(COMPACT_SHOT) else { + return; + }; + let shot = Shot::load(&path); + assert_eq!(shot.width, 736, "Compact 档那张必须是 736 宽"); + + let bands = bands(736.0); + let ui = ui(); + let rail_left = bands.major_rail.0; + let rail_right = rail_left + bands.major_rail.1 as usize; + let center = rail_left + bands.major_rail.1 as usize / 2; + // 栏的底色（`MaterialLayer::Card`）：取栏内空白处，不取窗口画布 + let card = shot.at(rail_left + 2, 500); + + // ① 首项的竖向量：40（图标按钮的边长）——文字行会是 44 + let (top, height) = shot + .first_filled_band(center, 156, 300, card) + .expect("主版本栏里应当有第一项"); + assert_eq!( + height as f32, + ui.metrics().control_height, + "Compact 档主版本栏首项应当是 40 高的图标按钮（y={top}），实测 {height}px —— \ + 回到「ListItem 文字行」就是 44" + ); + + // ② 横向：40 宽的药丸，在 64 栏里居中（左右各 12） + let (start, len) = shot.fill_run(top + height / 2, rail_left, rail_right, center, card); + assert_eq!( + (start, len as f32), + (rail_left + 12, ui.metrics().control_height), + "首项应当是 40 宽的居中药丸（栏 {rail_left}..{rail_right}），实测 x={start} 宽 {len} —— \ + 64 宽的通栏行说明它又画成文字了" + ); +} + +/// **M238 ①**：736×760 下六枚 loader chip **整枚**在面板滚动视口里（不是一条 10px 的缝）。 +/// +/// 修前实测（M238，`before-736x760-*.png`）：面板拿 286px、滚动视口只剩 **54px** +/// （head 40 + 间距 4 之后轮到 chips 只剩 10px），六枚 chip 的下边框一个像素都不在屏； +/// 修后（预算按面板内容推导，`rows/tail.rs::panel_budget`）：视口 **98px**，chip 描边 +/// 上下各一条（y=462 / y=493，高 31px）。 +/// +/// 抓得住：面板预算退回「死的 300」（视口 54 ⇒ 下边框消失，只剩上边框那一条描边行）、 +/// 或 chip 被任何东西裁掉下缘（判据是「**药丸描边**行至少有两条、且相距 ≥ 28」——圆角药丸的 +/// 上/下边框各是一排 ≥16px 的多段同色像素，裁掉任何一条都当场红；分隔线虽然同色但是**通栏 +/// 一段**，用段数把两者分开）。 +/// 抓不住：chip 的文案有没有被**横向**裁掉（要看字形宽度）、六枚到底是不是一行（那是 +/// `rails.rs` 的单测）、hover/焦点态。 +#[test] +fn a_compact_tier_shot_draws_the_whole_chip_row() { + let Some(path) = feed(COMPACT_SHOT) else { + return; + }; + let shot = Shot::load(&path); + let bands = bands(736.0); + let ui = ui(); + let left = bands.list.0 + 8; + let right = bands.list.0 + bands.list.1 as usize - 8; + + // 未选中的 chip 有 1px `OutlineVariant` 描边（选中项无描边，见 `selection/paint/chip.rs`） + let edge = rgb(ui.color(Role::OutlineVariant)); + let strokes: Vec = (400..560) + .filter(|y| pill_runs(&shot, *y, left, right, edge) >= 2) + .collect(); + assert!( + strokes.len() >= 2, + "chip 的描边行只有 {} 条（{strokes:?}）：六枚 chip 被面板视口裁成一条缝 \ + —— 下边框一个像素都不在屏，用户看不出「下面还有加载器 chip」", + strokes.len() + ); + let (top, bottom) = (strokes[0], strokes[strokes.len() - 1]); + assert!( + bottom - top >= 28, + "chip 的上下描边相距只有 {}px（y={top}..{bottom}）：chip 本体 32 高，\ + 被裁的话两个描边行会挨在一起", + bottom - top + ); +} + +/// **M238 ②**：版本菜单的 L2 阴影不许画到滚动视口之外（压暗下面钉死区的实例名）。 +/// +/// 修前实测（浅色）：菜单容器 `(238,238,239)` 底下那条 8px 缝、以及实例名框内的空白带 +/// 全被压成 `(231,231,232)`（−7.2%，与 M222/M227 视觉审记的「实例名被压暗 6.9%」同一处）， +/// 深色画面布 `(15,21,15)` 被压成 `(14,20,14)`。压暗带的**长度跟布局有关**：修前的旧预算下 +/// 是菜单底往下 54px 一整条；只把预算修好、阴影留着时缩到 8px（= blur 6 + offset 2 那圈）。 +/// 所以两条修法各管一半，判据按「缝 + 框内都必须纯画布色」写，两种布局都抓得住。 +/// 根因在 `iced_tiny_skia` 0.14：quad 阴影用 `draw_pixmap(.., mask: None)` 画 +/// （`engine.rs:136-143`），绕过裁切掩码；`iced_wgpu` 那条走整层 scissor（`quad.rs:96-101`）， +/// 于是同一棵树在 CPU / GPU 上画出来不一样。修法 = 不在这条滚动链里画阴影（`Menu::flat`）。 +/// +/// 抓得住：`Menu::flat` 被撤（阴影回来 ⇒ 缝与框内变成混合色）、α 被调大调小（只要非 0 就红）、 +/// 或者有人把菜单挪出滚动区又不裁（`uniform_row` 的定位仍会命中实例名框）。 +/// 抓不住：**滚动中**阴影会不会跟出来——静态图只有一帧，`pages::harness` 目前没有 +/// `scroll_to` 的派发通道（`rows.rs::PANEL_SCROLL_ID` 的注释是「拿到了就能派」，实际没人写）， +/// 所以「滚到中部/底部」这三态在本 mission 无法出图，只能靠「阴影根本不画」从机制上排除。 +#[test] +fn a_compact_tier_shot_keeps_the_menu_shadow_inside_the_scroll_viewport() { + let Some(path) = feed(COMPACT_SHOT) else { + return; + }; + let shot = Shot::load(&path); + let bands = bands(736.0); + let left = bands.list.0 + 8; + let right = bands.list.0 + bands.list.1 as usize - 8; + let canvas = shot.at(bands.list.0 + 2, 12); + + // 实例名框的两条通栏 1px 描边：整行同色，且「上 3 行」与「下 3 行」互为同色、又与它自己不同 + // ——通栏细线才满足这个形状；菜单块的边界不满足（块内 3 行是选中项底色）。 + let hairline = |y: usize| -> bool { + uniform_row(&shot, y, left, right).is_some_and(|color| { + matches!( + (uniform_row(&shot, y - 3, left, right), uniform_row(&shot, y + 3, left, right)), + (Some(above), Some(below)) if above == below && color != above + ) + }) + }; + let hairlines: Vec = (shot.height / 2..shot.height - 16) + .filter(|y| hairline(*y)) + .collect(); + assert!( + hairlines.len() >= 2, + "找不到实例名输入框的上下描边（命中 {hairlines:?}）：这条断言要靠它定位「钉死区」" + ); + let field_top = hairlines[hairlines.len() - 2]; + let field_bottom = hairlines[hairlines.len() - 1]; + assert!( + field_bottom > field_top + 40, + "实例名框只有 {}px 高（y={field_top}..{field_bottom}）：它被挤扁了，先修那一处再看阴影", + field_bottom - field_top + 1 + ); + + // ① 框上沿往上 8px = 「滚动视口 → 钉死区」的缝：必须**纯画布色** + let middle = (left + right) / 2; + for y in field_top - 8..field_top { + for x in [left + 8, middle, right - 16] { + assert_eq!( + shot.at(x, y), + canvas, + "y={y} x={x} 是 {:?} 而不是画布色 {canvas:?}：菜单的 L2 阴影漏出了滚动视口，\ + 压暗了视口下面那条 8px 的缝（M238 修前实测 −7.2%）", + shot.at(x, y) + ); + } + } + + // ② 框内标签以下的空白带也不许被压暗（修前那里是 231 而不是 249） + for y in field_top + 36..field_bottom - 8 { + assert_eq!( + shot.at(right - 24, y), + canvas, + "y={y} 的实例名框内是 {:?} 而不是画布色 {canvas:?}：阴影画到了框里面", + shot.at(right - 24, y) + ); + } +} diff --git a/crates/app-iced/src/pages/download/tests/options_shot/feed.rs b/crates/app-iced/src/pages/download/tests/options_shot/feed.rs new file mode 100644 index 0000000..8a43a88 --- /dev/null +++ b/crates/app-iced/src/pages/download/tests/options_shot/feed.rs @@ -0,0 +1,116 @@ +//! 像素守门的「喂图」通道：`ULL_DL_*_SHOT` 环境变量 → PNG 路径，以及**没喂图时该有多响**。 +//! +//! 四条像素断言（`chips` / `compact` / `ready` / 父模块的 wide）都从 [`feed`] 拿图。 +//! 为什么单独一个文件：调用侧只有一句 `let Some(path) = feed(KEY) else { return; };`， +//! 但「没图怎么办」是同一条策略——抄四份必然跑偏。M127 之前就是抄成了一律 `SKIP`， +//! 于是 CI 里四条全在**空跑**（`.github/` 与 `packaging/` 里 grep 这些变量零命中， +//! 说明从来没喂过图）；M127 把裁决收到这里，并让 CI 里缺图直接失败。 +//! +//! ## 手动出图的四条命令（CI 的 `test` 作业跑的就是这四条） +//! +//! ```text +//! # ready700：**不设** ULL_DL_DEMO（= ready，还没选版本） +//! cargo run -p unlucky-app-iced --example pages_demo -- --screen=download \ +//! --width=700 --height=760 --screenshot=ready700.png \ +//! --screenshot-theme=light --software-renderer +//! +//! # chips700 / compact736 / wide1180：都要 ULL_DL_DEMO=options-fabric +//! ULL_DL_DEMO=options-fabric cargo run -p unlucky-app-iced --example pages_demo -- \ +//! --screen=download --width=700 --height=760 --screenshot=chips700.png \ +//! --screenshot-theme=light --software-renderer +//! ULL_DL_DEMO=options-fabric cargo run -p unlucky-app-iced --example pages_demo -- \ +//! --screen=download --width=736 --height=760 --screenshot=compact736.png \ +//! --screenshot-theme=light --software-renderer +//! ULL_DL_DEMO=options-fabric cargo run -p unlucky-app-iced --example pages_demo -- \ +//! --screen=download --width=1180 --height=760 --screenshot=wide1180.png \ +//! --screenshot-theme=light --software-renderer +//! +//! ULL_DL_READY_SHOT=ready700.png ULL_DL_CHIPS_SHOT=chips700.png \ +//! ULL_DL_COMPACT_SHOT=compact736.png ULL_DL_OPTIONS_SHOT=wide1180.png \ +//! cargo test -p unlucky-app-iced --lib options_shot +//! ``` +//! +//! ## 只在 Windows runner 上可信 +//! +//! 断言里有几条直接量**墨迹**：`ready` 数「读得出几个版本号」的墨迹条数、`chips` 量首行 +//! 底色带与分隔线上下的高度、`compact` 量图标药丸的 40×40。这些数字是按父模块 `ui()` 里 +//! 那套字体栈（`Segoe UI` / `Consolas`）标定的。Linux / macOS runner 上这套字体不存在， +//! 回退字体的字高与行距一变，行高、墨迹条数、药丸位置跟着变 ⇒ **假红**。 +//! +//! 所以「像素断言只在 Windows runner 上跑」这条约束钉在**三处**，不靠「碰巧只配了一处」： +//! +//! 1. `.github/workflows/ci.yml` 的 `test` 作业：出图那步带 `if: runner.os == 'Windows'`； +//! 2. 同一作业的断言那步也带同一个条件，并把「为什么」写在那里； +//! 3. 本文件的 [`feed`]：非 Windows 上**喂了图**会当场失败（CI 里），不是静静地跑出假红。 +//! +//! ## 没喂图时：CI 里失败，本机跳过 +//! +//! | 环境 | 变量在 | 变量不在 | +//! |---|---|---| +//! | Windows + CI | 正常断言 | **失败**：「守门未喂图」 | +//! | Windows 本机 | 正常断言 | 跳过（一句提示） | +//! | 非 Windows + CI | **失败**：这条守门的标定前提不成立 | 跳过（本仓 CI 不在 Linux/macOS 上跑像素断言） | +//! | 非 Windows 本机 | 跑，但提示「数字可能不适用」 | 跳过（一句提示） | +//! +//! 目标是：将来谁把 CI 里出图那一步重构掉，构建会**红**，而不是静静退回手动档。 + +use std::path::PathBuf; + +/// CI 环境（GitHub Actions 在所有 runner 上都设这个）。 +fn in_ci() -> bool { + std::env::var_os("CI").is_some_and(|value| !value.is_empty()) +} + +/// `key` 指的截图路径；`None` = 没喂图，调用侧 `return`（跳过与失败的裁决已经在这里做完了）。 +/// +/// 空串当作没设：GitHub 的条件 env 很容易求出 `''`，而 `PathBuf::from("")` 会被后面那条 +/// 相对路径分支解析成**工作区根目录**，读它只会得到一句莫名其妙的「读截图」失败。 +pub(super) fn feed(key: &str) -> Option { + let Some(value) = std::env::var_os(key).filter(|value| !value.is_empty()) else { + not_fed(key); + return None; + }; + let path = PathBuf::from(value); + + if !cfg!(windows) { + // 非 Windows 上喂图：本机随意（只是数字可能不适用），CI 里说明标定前提被破坏了 + assert!( + !in_ci(), + "[options-shot] 在非 Windows runner 上喂了 {key}：这几条断言按 Windows 字体栈\ + （Segoe UI）标定，Linux/macOS 上跑出来的绿/红都不可信。\ + 像素守门只在 windows-latest 上跑，见 .github/workflows/ci.yml 的 test 作业。" + ); + eprintln!( + "[options-shot] 注意：{key} 喂在非 Windows 上，字体栈与标定时不同，\ + 数字可能对不上（这不是产品问题）。" + ); + } + + if path.is_absolute() || path.exists() { + return Some(path); + } + // `cargo test` 的 cwd 是 crate 目录，相对路径按**工作区根**解释 + let root = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../.."); + Some(root.join(path)) +} + +/// 没喂图时的统一裁决：CI（Windows）里**失败**，本机跳过并留一句提示。 +/// +/// 由 [`feed`] 在返回 `None` 之前调用——「跳过」这件事必须是响的，不能 `return` 了事。 +fn not_fed(key: &str) { + let message = format!( + "[options-shot] 守门未喂图：环境变量 {key} 没有设置。这条是**渲染层**像素断言，\ + 需要先用 pages_demo 现出真 PNG（四条命令见 tests/options_shot/feed.rs 的模块文档）。" + ); + // 只在 Windows + CI 上硬失败：非 Windows 上本来就不该喂图（见模块文档的表）， + // 那边缺图是**预期**，硬失败会误伤 Linux 那条矩阵。 + assert!( + !(cfg!(windows) && in_ci()), + "{message}\n\ + 当前是 CI 环境（CI 已设置）却拿到空路径 ⇒ CI 里出图那一步被重构掉了 / 条件写错了，\ + 构建必须红：空跑的守门等于没有守门。\ + 修法：.github/workflows/ci.yml 的 test 作业里出图与断言两步都要带这条——\ + `if: runner.os == 'Windows'`，且出图那步要把四个 ULL_DL_*_SHOT 写进 $GITHUB_ENV。" + ); + eprintln!("{message} SKIPPED（本机，非 CI）。"); +} diff --git a/crates/app-iced/src/pages/download/tests/options_shot/ready.rs b/crates/app-iced/src/pages/download/tests/options_shot/ready.rs new file mode 100644 index 0000000..265cca2 --- /dev/null +++ b/crates/app-iced/src/pages/download/tests/options_shot/ready.rs @@ -0,0 +1,80 @@ +//! 「还没选版本」那一态（`ULL_DL_DEMO` 不设 = `ready`）的像素守门：r1 复审 P2-1。 +//! +//! ## 为什么要单独守这一态 +//! +//! M125 r1 的 `TailShare::of` **只判档位**，于是 chips 档的「刚进页面」也被五五分： +//! 面板里只有一行提示（`PanelState::Hint`，≈30px），却拿走一半高度 ⇒ 700×760 下 +//! 只剩 **4 整行**可读、下半块留 ≈160px 空画布（main 那一态是 **7 整行**：不是 8， +//! 第 8 条墨迹其实是 `Pick a version, then install` 那句 hint，横向范围对不上版本号， +//! 而且 700×760 上放 8 行要 352px、实测只剩 309~322px。r2 修回 7 整行）。 +//! 同目录 `chips.rs` 只拍「选中 + 选项区展开」，正是这个盲区把回归放了过去。 +//! +//! 现在的判据：`Chips` **且**面板真占高度（`Options` / `Install`）才共享； +//! `Hint` 在任何档位都钉死（见 `rows::TailShare::of`）。 +//! +//! ```text +//! # 不设 ULL_DL_DEMO（= ready）出 700×760 那张 +//! cargo run -p unlucky-app-iced --example pages_demo -- \ +//! --screen=download --width=700 --height=760 --screenshot=ready700.png \ +//! --screenshot-theme=light --software-renderer +//! ULL_DL_READY_SHOT=ready700.png cargo test -p unlucky-app-iced --lib options_shot +//! ``` +//! +//! 抓得住：①列表区 **≥ 6 整行**（数版本号那列的墨迹条数，行距 44）；②尾部（提示那条 +//! 分隔线）在 6 行之后——五五分时它落在第 4 行下方，两条都立刻红。 +//! 抓不住：提示文案本身、hover/tooltip 层（静态图拍不到）；也不管「选中且展开」那一态 +//!（那是 `chips.rs` 的活）。 + +use super::{bands, feed, ui, Shot, READY_SHOT}; + +/// `ready` 那一态（700×760）：8 个版本里至少 6 行要在屏，尾部提示不许把列表压扁。 +/// +/// 修前实测（M125 r1，`TailShare::of` 只判档位的版本）：列表区 `374..559` = 185px = 4 行， +/// 版本号那列只有 4 条墨迹；面板那半块 185px 里只有一行 `Pick a version, then install`， +/// 其余是空白 —— 这条断言在那种图上是红的（4 < 6）。 +#[test] +fn a_ready_shot_keeps_the_whole_visible_list() { + let Some(path) = feed(READY_SHOT) else { + return; + }; + let shot = Shot::load(&path); + assert_eq!(shot.width, 700, "这条只认 700×760 那张（chips 档）"); + + let bands = bands(700.0); + let canvas = shot.at(bands.list.0 + 2, 12); + let metrics = ui().metrics(); + let right = bands.list.0 + bands.list.1 as usize - 2; + + // ① 第一行版本号的墨迹带（ready 态没有选中行，所以量的是**文本**而不是底色； + // x 取 `+100` 落在版本号那几个字上——`+60` 会落进「前置下载图标」与文字之间的空档） + let (first_ink, _) = shot + .first_filled_band(bands.list.0 + 100, 360, 440, canvas) + .expect("列表列里应当有版本行"); + + // ② 尾部（提示）上沿的分隔线：它上面的高度才是列表拿到的 + let rule = shot + .first_rule_y(bands.list.0, right, first_ink, canvas) + .expect("找不到尾部那条分隔线（列表区的下界量不出来）"); + + // ③ 数得出几个版本号：8 行里至少 6 行在屏 + let rows = shot.ink_bands( + bands.list.0 + 50, + bands.list.0 + 140, + first_ink, + rule, + canvas, + ); + assert!( + rows >= 6, + "ready 态只读得出 {rows} 个版本号（要求 ≥ 6 个，演示数据共 8 个）：\ + 面板那一行提示把列表对半切了（列表区 y={first_ink}..{rule}，\ + 共 {}px，行高 {}）", + rule - first_ink, + metrics.row_height + ); + assert!( + (rule - first_ink) as f32 >= 6.0 * metrics.row_height - metrics.row_height / 2.0, + "ready 态的列表区只有 {}px（y={first_ink}..{rule}），不足 6 整行", + rule - first_ink + ); +} 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..51c555b --- /dev/null +++ b/crates/app-iced/src/pages/download/tests/rails.rs @@ -0,0 +1,264 @@ +//! 两层侧栏的护栏（**变异可证**）+ 三栏宽度账。 +//! +//! 从 `download/tests.rs` 拆出来：那边已经贴着 400 行硬线。 + +use unlucky_i18n::{Catalog, Lang}; +use unlucky_presenter::dto::{AppEvent, CoreEvent, VersionKind, VersionSummary}; +use unlucky_presenter::state::AppState; + +use crate::app::components::navigation::geometry::{typography_headline, ListItemGeometry}; +use crate::pages::download::options::InstallDraft; +use crate::pages::download::rails::{major_entries, major_shape, MajorShape}; +use crate::pages::download::{Category, Download}; +use crate::pages::layout::{ + available_width, frame_metrics, measure_cap_px, PaneKit, VersionRailTier, VersionRails, + RAIL_GAP, RAIL_ICON_WIDTH, +}; + +use super::ui; + +/// 三栏要吃掉整条可用宽（不是 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 = (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" + ); +} + +// ------------------------------------ 图标条档（64 宽）的主版本栏画什么（M125 缺陷 2） + +/// 一份只有「两个桶」的模型（`1.21` / `1.20`），给标签相关的两条断言当夹具。 +fn bucket_model(catalog: Catalog) -> Download { + let versions: Vec = ["1.21.9", "1.20.4"] + .iter() + .map(|id| VersionSummary { + id: (*id).to_string(), + 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) +} + +/// **图标条档里只有首项换成图标**，桶标签照旧画文字——两种语言走同一条分支。 +/// +/// 抓得住：谁把首项改回文字（中英文各一条断言，英文会回到「All v」，中文回到只画得出两字）； +/// 或者把桶标签也一起换成图标（最后两条断言）。 +/// 抓不住：图标画得对不对称（像素在 `options_shot` 的紧凑档断言与报告里的图）。 +#[test] +fn only_the_first_major_entry_switches_to_an_icon_in_the_icon_rail() { + for (lang, full) in [(Lang::En, "All versions"), (Lang::ZhCn, "全部版本")] { + let catalog = lang.catalog(); + let model = bucket_model(catalog); + let entries = major_entries(catalog, &model); + + let first = entries[0]; + assert_eq!(first.key, None, "{lang:?}：第一项是「全部版本」"); + assert_eq!( + first.label, full, + "{lang:?}：数据层仍带全称（chips 档要它）" + ); + assert_eq!( + major_shape(first, true), + MajorShape::Icon(full), + "{lang:?}：图标条档的首项不画文字，全称只进 tooltip" + ); + assert_eq!( + major_shape(first, false), + MajorShape::Text(full), + "{lang:?}：展开档（140）照旧画全称" + ); + + let bucket = entries[1]; + assert_eq!(bucket.key, Some("1.21"), "{lang:?}：第二条是第一个主版本桶"); + assert_eq!(major_shape(bucket, true), MajorShape::Text("1.21")); + assert_eq!(major_shape(bucket, false), MajorShape::Text("1.21")); + } +} + +/// **宽度账**（算术，中英文各算一遍）：32px 的文本格里首项的全称放不下、桶标签放得下。 +/// +/// 这条是「为什么不画文字」的可核证依据，也是**中文结论**的那一半（另一半是上面那条 +/// 「中文走图标分支」）：中文全角字形 1em ⇒ 宽度是精确值，不是估计。 +#[test] +fn the_icon_rail_text_box_is_32_and_only_bucket_labels_fit() { + let ui = ui(); + let geometry = ListItemGeometry::of(&ui); + let text_box = RAIL_ICON_WIDTH - geometry.pad_start - geometry.pad_end; + assert_eq!(text_box, 32.0, "64 宽的栏 − 2×16 内边距"); + + let em = typography_headline().style().size_px; + assert_eq!(em, 16.0, "ListItem 主文本是 `BodyLarge` 16px"); + + // 中文：全角字形 = 1em ⇒ 「全部」= 32（与文本格同宽 ⇒ 零余量，所以短标签这条退路也不走） + assert_eq!(2.0 * em, text_box, "「全部」正好占满 32：零余量"); + assert!(4.0 * em > text_box, "「全部版本」= 64 > 32：画不出来"); + + // 英文：按 0.4em 的**下限**步进（`BodyLarge` 实测 0.43233em，这里取更保守的下限） + assert!( + 0.4 * em * 12.0 > text_box, + "「All versions」≥ 76.8 > 32：画不出来（改前图上就是「All v」）" + ); + // 桶标签 4 字符：下限步进 25.6 ≤ 32（736 那张图实测墨迹 26，余量 6） + assert!( + 0.4 * em * 4.0 <= text_box, + "「1.21」/「24w」≤ 32：放得下，照旧画文字" + ); +} 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, 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 { + 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..c3a3a7f --- /dev/null +++ b/crates/app-iced/src/pages/download/tests/view.rs @@ -0,0 +1,242 @@ +//! 控件树那一节：九个状态 × 四档宽度都要能构图（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![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('版'))); +} + +/// 列表与尾部面板怎么分高：**档位 + 面板形态** → 三档之一（`Pinned` / `Shared` / `Narrow`）。 +/// +/// 修前（M123）：面板一律按内容高钉在底部，700×760 的 chips 档里列表只剩 18px（0.4 行）。 +/// M125 r1 修法只判档位，又踩出另一条回归：chips 档「刚进页面还没选版本」（`Hint`，面板只有 +/// 一行提示）也被五五分，700×760 下只显示 **4 整行**、下半块留 ≈160px 空画布 +/// （复审 P2-1 实测；main 那一态是 **7 整行**——不是 8：第 8 条墨迹其实是 +/// `Pick a version, then install` 那句 hint，横向范围对不上版本号。r2 修回 7 整行）。 +/// +/// 现在的判据（M227 重写，旧文档只写了 M125 那一条条件 —— r8 复审 improve finding）： +/// ① `Chips` **且**面板真占高度（`Options` / `Install`）⇒ `Narrow`； +/// ② **任何档位**的 `Options` 只要带加载器版本列表 ⇒ `Shared`（三栏档只走这条）； +/// ③ 其余（含 `Hint`）⇒ `Pinned`。 +/// +/// 抓得住：①chips 档改回「Pinned」（面板把列表压成缝 ⇒ 像素守门 +/// `ready::a_ready_shot_keeps_the_whole_visible_list` / `chips::a_chips_tier_shot_…` 立刻红）； +/// ②三栏档也改成 `Narrow`（1180 下钉死区少了菜单与说明，`an_options_shot_…` 的量测会红）。 +/// 抓不住：**实际分到多少像素**（`iced` 的 `Element` 没有几何内省，那只能出图量）。 +#[test] +fn the_chips_tier_shares_the_height_only_when_the_panel_takes_room() { + use crate::pages::download::install::panel_state; + use crate::pages::download::options::{InstallDraft, Loader, OptionsView}; + use crate::pages::download::rows::TailShare; + use crate::pages::layout::VersionRailTier; + use unlucky_presenter::state::AppState; + + let catalog = Lang::En.catalog(); + let mut app = AppState::new(); + app.apply(unlucky_presenter::dto::AppEvent::Core( + unlucky_presenter::dto::CoreEvent::VersionListChanged(vec![version( + "1.21.9", + VersionKind::Release, + false, + )]), + )); + + let row = VersionRow::of(&version("1.21.9", VersionKind::Release, false), catalog); + // 选中版本 ⇒ 选项区（面板真的占高度） + let options = Download { + options: Some(OptionsView::of( + &row, + &app, + &InstallDraft { + selected: Some("1.21.9".to_string()), + loader: Loader::Vanilla, + loader_version: String::new(), + instance_name: String::new(), + }, + catalog, + )), + install: None, + loaded: true, + ..Download::default() + }; + // 刚进页面 ⇒ 只有一行提示 + let hint = Download { + options: None, + install: None, + loaded: true, + ..Download::default() + }; + + assert_eq!( + TailShare::of(VersionRailTier::Chips, &panel_state(&options)), + TailShare::Narrow, + "chips 档 + 选项区展开：窄档预算（面板只钉实例名，列表 3 整行）" + ); + assert_eq!( + TailShare::of(VersionRailTier::Chips, &panel_state(&hint)), + TailShare::Pinned, + "chips 档 + 只有一行提示：钉死（8 个版本要在屏）" + ); + for tier in [ + VersionRailTier::Wide, + VersionRailTier::Narrow, + VersionRailTier::Compact, + ] { + assert_eq!( + TailShare::of(tier, &panel_state(&options)), + TailShare::Pinned, + "{tier:?}：三栏档一律钉死（面板整块在屏）" + ); + assert_eq!(TailShare::of(tier, &panel_state(&hint)), TailShare::Pinned); + } + + // 两个装配点（三栏装配 / chips 分支）都**按档位 + 面板形态**传 + let chips_branch = include_str!("../../download.rs"); + let three_column = include_str!("../rails.rs"); + assert_eq!( + chips_branch.matches("TailShare::of(rails.tier,").count() + + three_column.matches("TailShare::of(rails.tier,").count(), + 2, + "三栏装配与 chips 分支都要把面板形态传进 TailShare::of" + ); +} diff --git a/crates/app-iced/src/pages/frame.rs b/crates/app-iced/src/pages/frame.rs new file mode 100644 index 0000000..817a5d5 --- /dev/null +++ b/crates/app-iced/src/pages/frame.rs @@ -0,0 +1,265 @@ +//! 页面骨架：**页头**（标题 + 副标题 + 可选操作区）+ **内容区**（列宽由 [`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, BASE, 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>, +} + +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> { + 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() +} + +/// 页面正文的**可用高度**（窗口高 − 自绘标题栏 − 页头带 − 上下页边距）。 +/// +/// M161：内容库要靠它决定「矮窗口换版面」。三个被减掉的量都取自 [`page`]/[`header_bar`] +/// 用的**同一个**来源（`Ui::metrics` 与 [`FrameMetrics::gutter`]），不另抄字面量—— +/// 谁改了页头高，这里跟着变。 +#[must_use] +pub fn body_height(ui: &Ui, metrics: FrameMetrics, window_height: f32, has_subtitle: bool) -> f32 { + let chrome = ui.metrics().titlebar_height + + ui.metrics().header_height(has_subtitle) + + 2.0 * metrics.gutter; + (window_height - chrome).max(0.0) +} + +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> { + 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> { + 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> { + container(content) + .width(Length::Fixed(block::prose_width(metrics))) + .into() +} + +/// 两列版面：左列 `secondary`（独立滚动区由调用方自己加 `scrollable`）+ 右列 `main`。 +/// +/// 两列都**显式**取布局系统给的宽度，不吃 Fill：列表列必须固定 336， +/// 详情列必须窄于可用宽度，否则又回到「全宽单卡」。 +pub fn panes<'a>( + metrics: FrameMetrics, + secondary: impl Into>, + main: impl Into>, +) -> 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> { + 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> { + 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..817e04c --- /dev/null +++ b/crates/app-iced/src/pages/frame/pieces.rs @@ -0,0 +1,360 @@ +//! 页面用的**占位控件**：卡片 / 分隔线 / 空态 / 文本按钮 / 图标 / 容器样式。 +//! +//! 全部走令牌（颜色、圆角、排版、间距、一像素线），但**没有完整状态机**—— +//! 这些是给页面骨架站稳版式用的临时件，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::app::components::interaction::Base; +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; + +/// 描边卡片**真正画出来的底色**（[`card`] 的 `background` 就是它）。 +/// +/// 装配方式与 `components` 的容器同一条纪律（M234）：容器自己画哪个角色，就导出哪个常量， +/// 里面放的控件用 `.base(BASE)` 把这条信息传下去——两边同源，改色不会漂一半。 +/// +/// 取值不是「反正是 surface」而是**画法本身**：`card()` 画的是 [`MaterialLayer::Card`] +/// （= `Role::SurfaceContainerLow`，乘面板 α），所以常量也从**同一个** `MaterialLayer` 取角色。 +/// `frame/tests.rs` 有一条断言把「画出来的颜色」与「常量」逐值对上，另有源码结构断言盯着 +/// `card()` 不许改画别的层。 +/// +/// ⚠️ 面板 α < 1（GPU 档的用户设置）时卡片画的是**半透明**合成色，而 [`Base`] 只装得下一个 +/// `Role`：禁用态会按不透明的角色色合成，与卡片实色差一个 α（M234 的 `base.rs` 已登记这条局限）。 +/// CPU 档（`--software-renderer` 验收图）α 恒为 1，两者逐值相同。 +pub const BASE: Base = Base::of(MaterialLayer::Card.surface_role()); + +/// 描边卡片（长表单容器）。圆角取**规格卡**的 16（`Ui::card_shape`），不是组件表的 12。 +/// +/// M229 换肤：规格卡 `CARD` 小节把卡片画成 `rx=16`，而 `component_map` 的 `OutlinedCard` 是 +/// `Medium(12)`（官方值）。M228 把这条差异登记为「换肤时取 `inkcat::metrics::CARD`」，这里就是那次取值； +/// 组件表的值不动（它还服务别的面）。描边仍走 `OutlineVariant` 1px。 +/// +/// M237：卡片里放的禁用 / 可交互控件要接 [`BASE`]（`.base(frame::BASE)`），否则它们会把 +/// 状态层与禁用色叠在画布色上——卡片内的禁用按钮因此看起来「形丢了」（M223 的视觉缺陷）。 +pub fn card<'a>(ui: &'a Ui, content: impl Into>) -> Element<'a, Message> { + let shape = ui.card_shape(); + 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(shape), + ..container::Style::default() + }) + .into() +} + +/// 一像素分隔线（`OutlineVariant`，厚度取令牌）。 +pub fn divider<'a>(ui: &'a Ui) -> Element<'a, Message> { + rule::horizontal::(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> { + 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` 完全解耦。 +/// +/// ⚠️ 状态层按**画布底**合成（`Role::Surface`）：它只服务页头带那一排动作（页头带就是 Canvas 层）。 +/// 放进卡片/面板里必须换成那个容器的 `BASE`——这里没有 `base` 形参，是因为今天零个卡内调用点； +/// 真要在卡里用它，加一个 `base` 参数而不是在这里猜（M237 登记的接线口径）。 +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!( + "", + 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..f29ec90 --- /dev/null +++ b/crates/app-iced/src/pages/frame/tests.rs @@ -0,0 +1,217 @@ +//! `frame` 的断言：空态 / 卡片 / 页头规格与一屏字号档。 +use super::pieces::{EMPTY_ICON_BLOCK, EMPTY_ICON_GLYPH}; +use super::*; + +use unlucky_design::color::{Role, SchemeFlavor}; +use unlucky_design::elevation::MaterialLayer; +use unlucky_design::shape::ShapeScale; +use unlucky_design::typography::Platform; + +use crate::app::components::interaction::Base; +use crate::pages::layout::{self, 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) }; +} + +/// 卡片圆角取**规格卡**的 16（M229 换肤），组件表 `OutlinedCard` 的 12 只作为对照保留。 +#[test] +fn card_uses_the_spec_corner_not_the_component_table() { + let ui = ui(); + assert_eq!(ui.card_shape(), ShapeScale::Large); + assert_eq!(ui.radius_dp(ui.card_shape()).top_left, 16.0); + // 组件表的官方值仍是 12（表不动，差异登记在 `inkcat` 模块与 M229 报告里）。 + assert_eq!(Component::OutlinedCard.spec().shape, ShapeScale::Medium); + assert_eq!(ui.radius_dp(ShapeScale::Medium).top_left, 12.0); +} + +#[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()); +} + +/// **`body_height` 用真的 `Ui::metrics` + `FrameMetrics` 算**（M161 复审 P2-2：这条函数此前 +/// 一条测试都没有，而④的「最小窗口」用例是拿 56/88/32 反推的——三个数全错）。 +/// +/// 抓得住：①`titlebar_height` / `header_height` / `gutter` 任何一个被改（chrome 变了， +/// 下面的等式立刻红）；②把两行页头当单行算（`has_subtitle` 被忽略）；③把页边距只减一遍。 +#[test] +fn body_height_subtracts_the_real_shell_chrome() { + let ui = ui(); + let metrics = frame_metrics(PaneKit::Single, 880.0); + let metrics_wide = frame_metrics(PaneKit::Single, 1180.0); + + let chrome = |two_line: bool| { + ui.metrics().titlebar_height + ui.metrics().header_height(two_line) + 2.0 * metrics.gutter + }; + + // 真值来自 token：自绘标题栏 48 + 两行页头 84 + 上下页边距 2×24 = 180。 + assert_eq!( + chrome(true), + 48.0 + 84.0 + 2.0 * 24.0, + "chrome 与 design token 不一致（titlebar_height / page_header_tall_height / Expanded gutter）" + ); + assert_eq!(body_height(&ui, metrics, 560.0, true), 560.0 - chrome(true)); + // 单行页头少 28（84 − 56 = `page_header_tall_height` − `page_header_height`）。 + assert_eq!( + body_height(&ui, metrics, 560.0, false), + 560.0 - chrome(false) + ); + assert!( + body_height(&ui, metrics, 560.0, true) < body_height(&ui, metrics, 560.0, false), + "带副标题的页头更高，正文可用高必须更小" + ); + // 窄窗（Compact < 600）页边距更小 ⇒ 同样窗口高下正文更高。 + let compact = frame_metrics(PaneKit::Single, 560.0); + assert_eq!(compact.class, crate::pages::layout::WidthClass::Compact); + assert!( + compact.gutter < metrics_wide.gutter, + "Compact 档的页边距应小于 Expanded（16 < 24）" + ); + assert!( + body_height(&ui, compact, 560.0, true) > body_height(&ui, metrics_wide, 560.0, true), + "页边距变小 ⇒ 正文可用高变大" + ); + // 窗口比外壳还矮时不返回负数（不许把版面算成 NaN/负值）。 + assert_eq!(body_height(&ui, metrics, 100.0, true), 0.0); +} + +/// **卡片导出的底 = 卡片真正画出来的底色**（M237）。 +/// +/// 抓得住：①`BASE` 被换成「看着像」的角色（`Surface` / `SurfaceContainer` / +/// `SurfaceContainerHighest` 都能通过「是个容器色」这种含糊的判据）；②`card()` 改画别的材质层 +/// 而常量没跟上（两边漂一半，卡片里的禁用控件又会与卡底脱节）。 +/// +/// 抓不住：面板 α < 1 时的**半透明**合成——`Ui::layer` 会把角色乘 α，而 [`Base`] 只装得下 +/// 一个 `Role`。CPU 验收档 α 恒 1，两者逐值相同；GPU 档的这条差已登记在 `pieces::BASE` 上。 +/// +/// 判据是**页面级像素**（截图量出来的那份，`pages/settings/tests/java_shot.rs`）的前置条件： +/// 这一条红了，那边的「叠卡片底」就是拿一个错的值在比。 +#[test] +fn the_card_base_is_the_colour_the_card_actually_paints() { + for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] { + let ui = Ui::with_platform( + flavor, + Platform::Windows, + Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", + }, + ); + + assert_eq!( + BASE.role(), + MaterialLayer::Card.surface_role(), + "{flavor:?}: 卡片底必须是 `card()` 画的那一层的角色" + ); + assert_eq!( + ui.layer(MaterialLayer::Card), + ui.color(BASE.role()), + "{flavor:?}: `card()` 画的颜色与 `BASE` 求出来的不是同一个值" + ); + // 卡片底 ≠ 画布底：相等的话「卡片里的禁用控件叠哪一层」永远看不出区别（判据恒绿） + assert_ne!(BASE, Base::CANVAS, "{flavor:?}: 卡片底不能是画布底"); + assert_ne!( + ui.color(BASE.role()), + ui.color(Role::Surface), + "{flavor:?}: 卡片色与画布色必须可分" + ); + } +} + +/// **源码结构**：`card()` 用 [`MaterialLayer::Card`] 画底，`BASE` 从**同一个**层取角色。 +/// +/// 为什么还要一条扫源码的：iced 的 `Element` 没有内省接口（容器样式是闭包），「画的是哪一层」 +/// 在运行期拿不到；而这件事本身就是契约——容器画什么，就导出什么。换个写法（先存进局部变量） +/// 会绕过它，那属于重构后要一起改判据的正常代价（与 `pages/tests.rs` 里 `frame::body` 那两条同源）。 +#[test] +fn the_card_base_and_the_card_paint_share_one_layer() { + const PIECES: &str = include_str!("pieces.rs"); + + let body = layout::source::function_body(PIECES, "pub fn card<'a>("); + assert!( + body.contains("ui.layer(MaterialLayer::Card)"), + "`frame::card` 的底色必须取 `MaterialLayer::Card`（`BASE` 就是从它推出来的）：\n{body}" + ); + + let base = layout::source::statement(PIECES, "pub const BASE"); + assert!( + base.contains("Base::of(") && base.contains("MaterialLayer::Card"), + "`frame::BASE` 必须从 `card()` 画的那一层取角色：{base}" + ); +} diff --git a/crates/app-iced/src/pages/harness.rs b/crates/app-iced/src/pages/harness.rs new file mode 100644 index 0000000..d0d1a32 --- /dev/null +++ b/crates/app-iced/src/pages/harness.rs @@ -0,0 +1,321 @@ +//! 截图 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::instances; +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, + /// 实例页「启动参数」区的表单（M157）：harness 没有 `App`，自己持有演示表单。 + form: instances::LaunchForm, + window: Option, + /// 窗口原生句柄（`window::raw_id` 的回值）。OS 侧密闭指标要在**真句柄**上读， + /// 拿不到就留 `None` ⇒ 日志记 `unknown`（不是 `off`）。 + hwnd: Option, + /// 窗口落点（`window::position` 的**返回值**，不是请求值）。 + placed: Option, + frames: u32, + /// 采样**已派发**（M100 r1 P2-1）：置位后不再请求第二张，避免「最后写入者说了算」。 + dispatched: bool, + /// **成功落盘**的次数（共享给 [`run`]，终态不变量读它）。 + /// + /// 只在 `shot::save` 返回 `Ok` 之后自增：这是「真的写出去了」，不是「我们打算写」（U1）。 + /// 正常必须恰好 1；打进日志让复审能数。 + written: Arc, + /// 本张图收到过几个鼠标事件（`Message::Pointer` 的计数）。 + /// + /// ⚠️ 它只证明「鼠标消息到没到」，**不**证明「像素会不会变」（复审实测：注入 12 个事件而像素 + /// 不变）。密闭的**主证据**是 `[caps] passthrough_ext=`，见 [`caps`]。 + pointer: u32, + /// 进程起点（`run()` 的开头）——`[perf]` 的首帧口径与产品路径一致：从进 `run()` 算。 + started: Instant, + /// 第一帧到达的时刻（相对 `started`）。`None` = 一帧都没到过。 + first_frame: Option, + /// 出这张图的后端（`wgpu` / `tiny-skia`）。图要能**自证来源**——以前它证不了（M97）。 + backend: &'static str, +} + +#[derive(Debug, Clone)] +enum Message { + Boot, + WindowReady(Option), + /// `window::raw_id` 的回值（原生句柄，OS 侧密闭指标要它）。 + RawId(u64), + /// `window::position` 的回值。 + Placed(Option), + /// `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 { + 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> = Vec::new(); + if self.request.passthrough { + eprintln!("[harness] 指针穿透已开：本窗口不再接收鼠标事件（取证专用）"); + tasks.push(window::enable_mouse_passthrough(id)); + } + tasks.push(window::raw_id::(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 { + 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(), &self.form) + .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..de198f9 --- /dev/null +++ b/crates/app-iced/src/pages/harness/app.rs @@ -0,0 +1,264 @@ +//! 截图 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 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` 来，打日志的是它算出来的生效值。 + // + // M250：**gallery 也要这一份** —— 强调色出图矩阵拍的是组件库（buttons + progress）， + // 而 `--appearance=real` 按设计只对设置页生效（`request.rs` 的守卫，别绕过它）。所以判据加 + // 一条：设了 `ULL_APPEARANCE_ACCENT` 就造状态，让 `Ui` 按强调色求值（设置页的语义不变）。 + let wants_accent = std::env::var_os(appearance::accent::ENV_ACCENT).is_some(); + let appearance = (request.real_appearance || wants_accent).then(|| { + let mut state = appearance::State::new( + &AppearancePrefs::factory(), + &AppearanceBase::factory(), + request.backend, + request.flavor, + ); + state.apply_env(); + // M159：`ULL_SETTINGS_GROUP=<下标>` 在 harness 里也生效（产品路径走 + // `app/state/construct.rs` 的同一条判据）。没有它就只能拍默认的「General」组， + // 而设置页有五组——「更新」组的验收图正是靠它拍出来的。 + if let Some(index) = + crate::ui::lang::screenshot_settings_group(request.screenshot.is_some()) + { + state.selected_group = index; + } + eprintln!( + "[harness] 外观真状态：window={:.2} panel={:.2}（生效 {:.2}）bg={} fill={:?} dim={:.2} \ + 配色来源={:?} accent={} 选中分组={}", + state.window_opacity, + state.panel_alpha, + state.effective_panel_alpha(), + state.bg_enabled, + state.bg_fill, + state.bg_dim, + state.palette_source, + state.accent.log_token(), + 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, boot.height); + // 截图通道把**消费 forced 的那批控件**（实例页）钉成常态，与产品 `--screenshot` + // 的 `ForcedState::Rest` 同一条纪律。它管不到设置页 / 外观区（那边不读 forced）， + // 那两屏的密闭靠窗口级 passthrough——别把这条当成万能的。 + if boot.screenshot.is_some() { + model.forced = Some(Interaction::Enabled); + } + // M250：gallery 出图也要能看见强调色。**规则不在这里抄** —— 调产品用的同一个 + // `theme::tokens`（优先级只定义一次）。如实补一句：harness 不建 `App`，所以这里 + // 没有 D38 取色方案（第三个实参恒 `None`），出图**不覆盖**那条分支。 + let (ui, _) = crate::theme::tokens( + boot.flavor, + appearance.as_ref().and_then(|state| state.accent.color()), + None, + families, + ); + ( + Harness { + ui, + model, + appearance: appearance.clone(), + form: crate::pages::demo_launch_form(), + 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) -> &'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, + /// 渲染后端请求。 + pub backend: Backend, + /// 强制缩放因子（截图要 100% DPI）。 + pub scale_factor: Option, + /// 设置页正文画**真控件**（`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) -> Result { + let mut request = Self::default(); + let mut theme: Option = None; + let mut shot_theme: Option = None; + let mut passthrough: Option = 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) + } + + /// 出图文件名片段（`[-real]---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, + inline: Option, + flag: &str, +) -> Result { + inline + .or_else(|| args.next()) + .ok_or_else(|| format!("{flag} 需要一个值")) +} + +fn number(raw: &str, flag: &str) -> Result { + raw.parse::() + .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 { + 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::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..5dfb092 --- /dev/null +++ b/crates/app-iced/src/pages/instances.rs @@ -0,0 +1,341 @@ +//! 实例页：**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 launch_args; +// M224: 详情页的 MODS 区（本地 mod 列表 + 启停开关） +mod mods; +// M235: 详情页的 SAVES 区（存档 / 截图的只读列表 + 打开文件夹） +mod saves; +mod state; +mod text; + +#[cfg(test)] +mod tests; + +#[cfg(test)] +pub(crate) use data::{DEMO, NOTE, SELECTED}; +pub(crate) use demo::{demo, demo_form}; +pub use mods::{from_state as mods_from_state, Mods}; +pub use saves::{from_state as saves_from_state, Saves}; + +/// 存档区失败的一句话（app 层就地画红字用；取词入口仍是 [`Texts`]）。 +/// +/// 本版**不弹 Toast**：只读列表的失败离用户的眼睛很近（就在卡片里），再弹一条是刷屏。 +pub fn saves_failure_line( + failure: &unlucky_presenter::dto::SavesFailureView, + catalog: unlucky_i18n::Catalog, +) -> String { + saves::failure_line(failure, Texts::of(catalog)) +} + +/// 删除世界的确认框文案：`(标题, 正文, 主按钮, 次按钮)`。 +/// +/// 模态框在 app 层建（`state.dialogs.push`），但**取词入口仍是本页的 [`Texts`]**——与 +/// [`saves_failure_line`] 同一条口径：页面文案只有一个入口，测试扫的也是那一份源码。 +pub fn saves_delete_prompt( + catalog: unlucky_i18n::Catalog, + dir: &str, +) -> (String, String, String, String) { + let texts = Texts::of(catalog); + ( + texts.saves_delete_title().to_string(), + texts.saves_delete_body(dir), + texts.saves_delete_confirm().to_string(), + texts.saves_cancel().to_string(), + ) +} + +/// 启停失败/读目录失败的一句话（app 层弹 Toast 用；取词入口仍是 [`Texts`]）。 +pub fn mods_failure_line( + failure: &unlucky_presenter::dto::ModFailureView, + catalog: unlucky_i18n::Catalog, +) -> String { + mods::failure_line(failure, Texts::of(catalog)) +} +pub use state::{LaunchForm, Message as InstanceMessage}; +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 = 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, + form: &'a LaunchForm, +) -> 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, + form, + &model.mods, + &model.saves, + forced, + texts, + ), + None => detail::detail_empty(ui, texts), + }, + ), + _ => match &block.detail { + Some(detail) => detail::narrow_detail( + ui, + metrics, + detail, + form, + &model.mods, + &model.saves, + 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, + 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::>(), + ) + .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 / 视觉复审 ②）。 + // + // M237：这一层画的是 `MaterialLayer::Card`（= `frame::BASE` 的同一个层），所以卡里的 + // 列表行把底传 `frame::BASE`（见 `list_row`）——不另立常量，避免同一层出现两个「真源」。 + 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, +) -> 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, +) -> 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); + } + // M237 复审 P2-1：列表卡画的是 `MaterialLayer::Card`（本文件 `list_column` 的 style）， + // 行的 hover / 按下状态层按 `base.role()` 合成（`components/navigation/list_item.rs::palette`）， + // 不给底就落回 `Base::CANVAS` —— 卡片里的行抬起时会叠在画布色上，与本轮修的禁用态同一类错。 + item = item.base(frame::BASE); + + 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..87e201d --- /dev/null +++ b/crates/app-iced/src/pages/instances/demo.rs @@ -0,0 +1,128 @@ +//! 实例页的**演示数据 → 视图模型**转换（M84 的出图基线靠这份数据）。 +//! +//! 只被 [`crate::pages::demo_model`] 用：产品路径的转换在 `app/view.rs`（presenter 快照 → 模型）。 +//! 两份数据源喂同一个渲染函数，这是 [`crate::pages::model`] 存在的理由。 + +use unlucky_i18n::{Catalog, Key, Lang}; +use unlucky_presenter::dto::LaunchArgsView; + +use super::super::model::{Detail, Instances, LaunchFacts, Meta, Row}; +use super::data::{DEMO, NOTE, SELECTED}; +use super::state::LaunchForm; + +/// 演示路径的目录：**恒英文**。 +/// +/// 为什么不是 `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, + launch: launch_facts(), + }; + + Instances { + rows, + detail: Some(detail), + } +} + +fn meta(label: &str, value: &str) -> Meta { + Meta { + label: label.to_string(), + value: value.to_string(), + } +} + +/// 启动参数区的演示事实（M157 的 D30 出图夹具）。 +/// +/// `ULL_LAUNCH_ARGS_FIXTURE=gated` 出「版本不够、三态灰化」那一屏；缺省（`open`）是 +/// 「26.2 实例 + Vulkan 可选」的正常态。**这是出图夹具，不是产品逻辑**：产品路径的门槛 +/// 来自 presenter 快照（core 的 `graphics_backend_allowed`），与这个环境变量无关。 +pub(crate) fn launch_facts() -> LaunchFacts { + let gated = gated_fixture(); + LaunchFacts { + allowed: !gated, + mc_version: if gated { "1.20.4" } else { "26.2-snapshot-2" }.to_string(), + min_version: "26.2-snapshot-2".to_string(), + memory_effective_mb: if gated { 2048 } else { 4096 }, + java_effective: "C:/Java/temurin-21/bin/java.exe".to_string(), + backend_effective: if gated { "default" } else { "vulkan" }.to_string(), + options: ["default", "opengl", "vulkan"] + .iter() + .map(|id| (*id).to_string()) + .collect(), + } +} + +/// 演示用的表单初值（页面状态的所有者是 `App`；harness 没有 `App`，自己持有一份）。 +/// +/// 返回**拥有**的表单而不是 `&'static`：出图/单测各自持有一份即可（一帧借用一次）， +/// 而 `static` 会让所有出图路径共享同一份可编辑状态（两个参数的控件现在都是单行 +/// `field::text_field` + `String`，不再是早先的多行编辑器）。 +pub(crate) fn demo_form() -> LaunchForm { + LaunchForm::from_view(Some(DEMO[SELECTED].name), &demo_view()) +} + +fn demo_view() -> LaunchArgsView { + let gated = gated_fixture(); + LaunchArgsView { + instance_id: DEMO[SELECTED].name.to_string(), + jvm_args: "-XX:+UseG1GC".to_string(), + game_args: "--fullscreen".to_string(), + memory_mb: (!gated).then_some(4096), + memory_effective_mb: if gated { 2048 } else { 4096 }, + java_path: String::new(), + java_effective: "C:/Java/temurin-21/bin/java.exe".to_string(), + graphics_backend: if gated { "default" } else { "vulkan" }.to_string(), + graphics_backend_effective: if gated { "default" } else { "vulkan" }.to_string(), + graphics_backend_allowed: !gated, + mc_version: if gated { "1.20.4" } else { "26.2-snapshot-2" }.to_string(), + graphics_backend_min_version: "26.2-snapshot-2".to_string(), + graphics_backend_options: ["default", "opengl", "vulkan"] + .iter() + .map(|id| (*id).to_string()) + .collect(), + } +} + +fn gated_fixture() -> bool { + std::env::var("ULL_LAUNCH_ARGS_FIXTURE") + .map(|value| value.trim().eq_ignore_ascii_case("gated")) + .unwrap_or(false) +} 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..68ef1e4 --- /dev/null +++ b/crates/app-iced/src/pages/instances/detail.rs @@ -0,0 +1,303 @@ +//! 实例页的**详情列**（M90 r2 从 `instances.rs` 拆出来：那边超过 400 行会被 guards 的 file-size 判红）。 +//! +//! 结构：标题行（名字 + 版本 + Play/Stop）→ 元信息网格（列数由 `layout::meta_columns` 决定） +//! → 一条分隔线 → 正文段 / 运行状态行 → 动作行（Duplicate / Open folder / Delete）。 +//! 窄窗（<840）时列表退成上一屏，本文件只画详情 + 一个「返回」按钮。 + +use iced::widget::{column, container, row, scrollable}; +use iced::{Alignment, Element, Length, Padding}; + +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::app::components::surfaces::elevated; +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::state::LaunchForm; +use super::Texts; + +// --------------------------------------------------------------- 详情列 + +pub(super) fn detail_column<'a>( + ui: &'a Ui, + metrics: FrameMetrics, + detail: &'a Detail, + form: &'a LaunchForm, + mods: &'a super::Mods, + saves: &'a super::Saves, + forced: Option, + 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); + // M224：MODS 区排在启动参数**之前**——详情列是一个滚动区，而启动参数卡本身就有一屏高， + // 排在它后面意味着「本地 mod 列表」永远在折叠线以下（M224 出图实测：1180×1000 完全看不见）。 + // 顺序因此是：身份（页头 + 元信息）→ 内容（MODS）→ 选项（启动参数）→ 动作。 + body = body.push(super::mods::section(ui, mods, forced, texts)); + // M235：SAVES 区紧跟 MODS 区（同为"内容"），理由与 MODS 一样：排在启动参数卡后面会落到 + // 折叠线以下——详情列是一个滚动区，而启动参数卡本身就有一屏高。 + body = body.push(super::saves::section(ui, saves, forced, texts)); + // M157：启动参数区在正文段之后、动作行之前（详情列 424px 内，卡片式）。 + body = body.push(super::launch_args::section(ui, &detail.launch, form, texts)); + + // 页头 + 元信息网格 + **一条**分隔线以下才是正文与操作区（M84 那两条线是占位时期的排版残留）。 + // + // M157 r2（D30 复审）：详情列的内容（正文段 + 启动参数卡 + 动作行）在 1180×1000 下**超出一屏**， + // 而这里原来没有滚动区 ⇒ Max memory 以下的控件被静默裁掉、够不着。现在整列套一个滚动区 + // （与左列列表同一套滚动条样式与宽度），被裁内容可达；滚动条是唯一入口，没有第二份状态。 + let content = body.push(action_row(ui, forced, texts)); + frame::left_aligned(metrics.column, scroller(ui, content)) +} + +pub(super) fn narrow_detail<'a>( + ui: &'a Ui, + metrics: FrameMetrics, + detail: &'a Detail, + form: &'a LaunchForm, + mods: &'a super::Mods, + saves: &'a super::Saves, + forced: Option, + 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); + // 顺序与宽窗那一支一致：内容（MODS）在选项（启动参数）之前，理由见 `detail_column`。 + body = body.push(super::mods::section(ui, mods, forced, texts)); + body = body.push(super::saves::section(ui, saves, forced, texts)); + body = body.push(super::launch_args::section(ui, &detail.launch, form, texts)); + + body = body.push(frame::text_role( + ui, + TypeRole::BodySmall, + false, + texts.narrow_note(), + ui.color(Role::OnSurfaceVariant), + )); + + frame::body( + metrics, + scroller(ui, body.push(action_row(ui, forced, texts))), + ) +} + +/// 详情列的滚动区（M157 r2）：与左列列表同一套滚动条几何（宽 6 / 内缩 2 / 同一 `style`）。 +/// +/// 右侧留 `Space::X2` 内缩：滚动条是**覆盖**在内容上的，不留这条缝时卡片的 1dp 描边会被 +/// 滚动条压住（D30 复审里「卡片右边框缺一截」就是它）。 +fn scroller<'a>(ui: &'a Ui, content: impl Into>) -> Element<'a, Message> { + let content = container(content) + .width(Length::Fill) + .padding(Padding::default().right(ui.space(Space::X2))); + 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) + .style(frame::scroll_style(ui)) + .into() +} + +/// 正文段（演示数据才有）与运行状态行（真数据才有）——两者都是可选的，顺序固定。 +/// +/// 散文段套 [`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, + 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）。不可用时退化成禁用态（只清消息，不改身份）。 + // + // M237：这一行**不在卡片里**（详情列直接铺在画布上），所以这两个按钮的底保持 + // `Base::CANVAS`——把卡底传进来反而会让禁用色叠错层。卡片内的控件（MODS / SAVES / + // 启动参数区）各自传 `frame::BASE`，见那几个模块。 + 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 { + // M229：元信息卡 = 规格卡的 **ELEVATED CARD**（无描边、`SurfaceContainer` 底、16 圆角）。 + // 内距 20 + 值 **12/400**（见 `elevated::PAD` / `elevated::TITLE_ROLE` 的登记）： + // 外框 160 − 2×20 = 120 必须放下 + // 最长值串，24 + 16 会让时戳折行、同排卡底不齐（复审 P1-2）。 + let card = elevated::card( + ui, + elevated::texts( + ui, + elevated::Texts { + overline: Some(cell.label.as_str()), + title: cell.value.as_str(), + support: None, + }, + ), + ); + 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, 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/launch_args.rs b/crates/app-iced/src/pages/instances/launch_args.rs new file mode 100644 index 0000000..e9d0543 --- /dev/null +++ b/crates/app-iced/src/pages/instances/launch_args.rs @@ -0,0 +1,242 @@ +//! 实例详情页的「启动参数」区（M157）。 +//! +//! | 控件 | 语义 | 消息 | +//! |---|---|---| +//! | JVM 参数（多行） | 实例层，与全局 `java.extra_args` **叠加**（实例段最高优先级） | [`Message::Jvm`] | +//! | 游戏参数（多行） | 实例层，追加在命令行最后 | [`Message::Game`] | +//! | 最大内存（单行数字） | 实例层；留空 = 跟随全局默认 | [`Message::Memory`] | +//! | Java 可执行文件（单行） | 实例层；留空 = 跟随全局 → 自动挑 | [`Message::Java`] | +//! | 图形后端（三态 chips） | `default` / `opengl` / `vulkan`；**版本不够时只灰化后两档**（`default` 始终可点）+ 提示 | [`Message::Backend`] | +//! +//! 两条判据刻意不在这里重算： +//! 1. **能不能用 `--graphicsBackend`** 来自 [`LaunchFacts::allowed`]（core 的 `graphics_backend_allowed`， +//! presenter 的 host 已经算好）——UI 不复制版本号比较； +//! 2. **生效值**（内存/Java/后端）同样来自 facts，表单里画的是实例层原文。 +//! +//! 文案全走 [`Texts`]（守门见 `instances/tests/i18n.rs` 的白名单与死 key 扫描）。 + +use iced::widget::{column, row}; +use iced::{Element, Length}; + +use unlucky_design::color::Role; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; + +use crate::app::components::buttons::{self, Button}; +use crate::app::components::inputs::{text_field, Field}; +use crate::app::components::selection::{chip, Chip}; + +use crate::theme::Ui; + +use super::super::frame::BASE; +use super::super::model::LaunchFacts; +use super::super::Message as PageMessage; +use super::state::{LaunchForm, Message}; +use super::Texts; + +/// 页内消息 → 页面消息（本文件的控件树统一画 `pages::Message`）。 +fn page(message: Message) -> PageMessage { + PageMessage::Instances(message) +} + +/// 「启动参数」区（在详情列的正文段之后、动作行之前）。 +pub(super) fn section<'a>( + ui: &'a Ui, + facts: &'a LaunchFacts, + form: &'a LaunchForm, + texts: Texts, +) -> Element<'a, PageMessage> { + // 段间距 X2（8dp）：卡内 5 个字段 + 三态 + 动作行在 424 宽下已经很长， + // 用 X3 会让详情列更长一屏；行内间距仍是 X1（4dp），读起来不挤。 + let mut body = column![frame_title(ui, texts.launch_title())] + .spacing(ui.space(Space::X2)) + .width(Length::Fill); + + body = body.push(args_field( + ui, + texts.launch_jvm(), + texts.launch_jvm_hint(), + form.jvm.as_str(), + |value| page(Message::Jvm(value)), + )); + body = body.push(args_field( + ui, + texts.launch_game(), + texts.launch_game_hint(), + form.game.as_str(), + |value| page(Message::Game(value)), + )); + body = body.push(text_field_with_hint( + ui, + texts.launch_memory(), + form.memory.as_str(), + super::super::frame::text_role_owned( + ui, + TypeRole::BodySmall, + false, + texts.launch_memory_hint(facts.memory_effective_mb), + ui.color(Role::OnSurfaceVariant), + ), + |value| page(Message::Memory(value)), + )); + body = body.push(text_field_with_hint( + ui, + texts.launch_java(), + form.java.as_str(), + super::super::frame::text_role_owned( + ui, + TypeRole::BodySmall, + false, + texts.launch_java_hint().to_string(), + ui.color(Role::OnSurfaceVariant), + ), + |value| page(Message::Java(value)), + )); + body = body.push(backend_row(ui, facts, form, texts)); + body = body.push(actions_row(ui, texts)); + + // 与相邻**表单卡**同一套卡壳（`frame::card`：内距 `card_padding` 20 + 卡片圆角 16 + 1px 描边）。 + // 注意元信息卡不在这条线上：它们现在是 ELEVATED CARD（无描边、内距 20、值 12px，见 `surfaces::elevated`）。 + super::super::frame::card(ui, body) +} + +/// 卡片标题：**与信息卡的标签同款**（`LabelMedium` 不加粗、`OnSurfaceVariant`）， +/// 复审 ③⑤ 抓的就是这里（原来用了 `emphasized = true`，比同屏其它标签重一档）。 +fn frame_title<'a>(ui: &'a Ui, title: &'a str) -> Element<'a, PageMessage> { + super::super::frame::text_role( + ui, + TypeRole::LabelMedium, + false, + title, + ui.color(Role::OnSurfaceVariant), + ) +} + +/// 一段参数输入 + 一行提示（单行受控输入；参数按空白切分，与 core 的 `tokenize` 同口径）。 +fn args_field<'a>( + ui: &'a Ui, + label: &'a str, + hint: &'a str, + value: &'a str, + on_input: impl Fn(String) -> PageMessage + 'a, +) -> Element<'a, PageMessage> { + column![ + text_field(ui, Field::new(value).label(label).base(BASE), on_input), + super::super::frame::text_role( + ui, + TypeRole::BodySmall, + false, + hint, + ui.color(Role::OnSurfaceVariant), + ), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill) + .into() +} + +/// 单行输入 + 一行提示（提示是**拥有的**字符串，所以不能走 `Field::supporting` 的借用口径）。 +fn text_field_with_hint<'a>( + ui: &'a Ui, + label: &'a str, + value: &'a str, + hint: Element<'a, PageMessage>, + on_input: impl Fn(String) -> PageMessage + 'a, +) -> Element<'a, PageMessage> { + column![ + text_field(ui, Field::new(value).label(label).base(BASE), on_input), + hint, + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill) + .into() +} + +/// 三态后端的「不下发」档（`GraphicsBackend::Default` 的稳定 id）。 +/// +/// UI 侧不依赖 core（分层：UI → presenter → core），所以在页面里落一个常量； +/// 词表本身仍来自 presenter 快照（[`LaunchFacts::options`]），这里只认「哪一个是安全档」。 +const BACKEND_DEFAULT: &str = "default"; + +/// 某一档 chip 在门限不满足时**是否仍可点**。 +/// +/// 抽成纯函数是为了让它可断言（`Element` 没有内省接口，画出来的禁用态测不到； +/// 见 `instances/tests/launch_args.rs`）。 +pub(crate) fn backend_chip_enabled(allowed: bool, id: &str) -> bool { + allowed || id == BACKEND_DEFAULT +} + +/// 三态后端：**版本不够时只灰掉 `opengl` / `vulkan`**，`default` 始终可点。 +/// +/// 为什么 `default` 不许一起灰：它是「不下发 `--graphicsBackend`」的安全档，写它永远不会被 +/// core 的版本门限拒绝。一起灰掉的话，用户手改实例文件、或在 CLI 里给旧版本实例写下 +/// `graphicsBackend: vulkan` 之后，UI 上就**回不到 `default`**——唯一的出路是「恢复跟随全局」， +/// 而那会连带清空 JVM / 游戏参数 / 内存 / Java 四项（M157 复审 P3）。 +fn backend_row<'a>( + ui: &'a Ui, + facts: &'a LaunchFacts, + form: &'a LaunchForm, + texts: Texts, +) -> Element<'a, PageMessage> { + let allowed = facts.allowed; + let mut chips = row![].spacing(ui.space(Space::X2)); + for id in &facts.options { + let label = texts.backend_label(id).unwrap_or(id.as_str()); + let selected = form.backend == *id; + let spec = Chip::filter(label, selected, page(Message::Backend(id.clone()))); + let spec = if backend_chip_enabled(allowed, id) { + spec + } else { + spec.disabled() + }; + // M237：启动参数区是一张 `frame::card`，chip 的禁用配色（12% 容器 / 38% 内容）叠卡底。 + chips = chips.push(chip(ui, spec.base(BASE))); + } + + let mut meta = column![ + super::super::frame::text_role( + ui, + TypeRole::BodySmall, + false, + texts.launch_backend(), + ui.color(Role::OnSurface), + ), + chips, + super::super::frame::text_role_owned( + ui, + TypeRole::BodySmall, + false, + texts.launch_effective(&facts.backend_effective), + ui.color(Role::OnSurfaceVariant), + ), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill); + + if !allowed { + // 灰化 + 明确提示：既不说「已生效」，也不静默吞掉用户的选择。 + meta = meta.push(super::super::frame::text_role_owned( + ui, + TypeRole::BodySmall, + false, + texts.launch_backend_gated(&facts.mc_version, &facts.min_version), + ui.color(Role::Error), + )); + } + meta.into() +} + +fn actions_row<'a>(ui: &'a Ui, texts: Texts) -> Element<'a, PageMessage> { + row![ + buttons::filled( + ui, + Button::new(texts.launch_save(), page(Message::Save)).base(BASE) + ), + buttons::text( + ui, + Button::new(texts.launch_reset(), page(Message::Reset)).base(BASE) + ), + ] + .spacing(ui.space(Space::X2)) + .into() +} diff --git a/crates/app-iced/src/pages/instances/mods.rs b/crates/app-iced/src/pages/instances/mods.rs new file mode 100644 index 0000000..815edf7 --- /dev/null +++ b/crates/app-iced/src/pages/instances/mods.rs @@ -0,0 +1,317 @@ +//! 实例详情页的 **MODS 区**（M224 · MODTOGGLE）：本地 mod 列表 + 启停开关。 +//! +//! # 位置与形状 +//! +//! 挂在详情列里、元信息网格之后、启动参数卡**之前**（`pages/instances/detail.rs` 的 `detail_column`）， +//! 动作行仍在最后。与启动参数区同一套卡片口径：[`frame::card`] + 一个 `LabelMedium` 小标 + 内容。 +//! +//! **为什么在启动参数之前**：详情列整列是一个滚动区，而启动参数卡本身就有近一屏高。MODS 排在它 +//! 后面时，1180×1000 下 MODS 区整块落在折叠线以下、根本看不见（M224 出图实测踩到过）。 +//! +//! # 为什么不自己再套一层滚动区 +//! +//! 详情列**整列**已经是滚动区（M157 r2 修的「Max memory 以下够不着」）。这里再套一个滚动条 +//! 会出现「滚动条里的滚动条」——1180×1000 下两个条都认得出来，用户不知道该拖哪一个。 +//! 列表多长就排多长，交给外层那一条。 +//! +//! # 开关三档 +//! +//! | 状态 | 开关 | 为什么 | +//! |---|---|---| +//! | 正常 | 可点（发 [`PageMessage::SetModEnabled`]） | — | +//! | 游戏在跑 | 禁用（不带消息） | Windows 上进程正持有 jar，rename 必然失败（host 侧也挡了一层） | +//! | 请求在飞 | 禁用 | 同一文件连点两次会发出两条 rename，第二条必然报「文件不在」 | +//! +//! **不做乐观回显**：开关画的是快照里的 `enabled`，点完等 host 回一份新快照才翻面。 +//! 与启动/停止同一条纪律（`app/update/instances.rs` 的 Save 分支）。 + +use iced::widget::{column, 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; +use unlucky_presenter::dto::{human_bytes, ModFailureView}; +use unlucky_presenter::state::ModsState; + +use crate::app::components::interaction::Interaction; +use crate::app::components::selection::{switch, Switch}; +use crate::theme::Ui; + +use super::super::frame; +use super::super::Message; +use super::state::Message as PageMessage; +use super::Texts; + +/// 一条 mod（纯展示字段，来源是 `presenter::dto::ModEntryView`）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Item { + /// 磁盘文件名（开关消息原样带回去）。 + pub file: String, + /// 展示名（去掉 `.disabled` / `.old`）。 + pub name: String, + /// 是否启用。 + pub enabled: bool, + /// 右侧副文案（大小 + 「旧版本残留」标记，已由 app 层拼好）。 + pub detail: String, + /// 这个文件的启停请求在飞（开关先禁用，不做乐观翻面）。 + pub pending: bool, +} + +/// MODS 区的展示模型（`Model::mods`）。 +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct Mods { + /// 这份数据属于哪个实例（`None` = 不在详情页 / 还没请求过）。 + pub bound: Option, + /// 正在读盘（详情页首帧：请求已发出、快照还没回来）。 + pub loading: bool, + /// 游戏在该实例上运行（开关只读）。 + pub running: bool, + /// 实例有 `mods/` 目录吗（`false` 且没有错误 ⇒ 还没装过模组）。 + pub exists: bool, + /// 读目录失败的人读原因（app 层按 i18n 拼好）。 + pub error: Option, + /// 列表。 + pub items: Vec, + /// 跳过条目数（符号链接 / 目录 / 读不出）。 + pub skipped: usize, + /// 计数行（`12 启用 · 3 禁用`）：**在这一层算好**，页面只借 `&str`。 + /// + /// 为什么不留到页面里 `format!`：iced 的 `Element` 只借这一帧的数据，页面函数返回的是 + /// **借用局部变量的树**，局部 `String` 一出栈就悬空（`E0515`）。所以"要显示的那句话" + /// 一律在视图模型里备好（与 `Detail::status` / `Row::supporting` 同一条做法）。 + pub count: String, + /// 跳过提示（`跳过 3 项`）。 + pub skipped_note: String, +} + +impl Mods { + /// 启用中的条数。 + #[must_use] + pub fn enabled_count(&self) -> usize { + self.items.iter().filter(|item| item.enabled).count() + } + + /// 禁用中的条数。 + #[must_use] + pub fn disabled_count(&self) -> usize { + self.items.len() - self.enabled_count() + } + + /// 有没有拿到一份快照（成功或失败都算；`loading` 中不算）。 + #[must_use] + pub fn loaded(&self) -> bool { + self.bound.is_some() && !self.loading + } + + /// 把某个文件的开关标成「请求在飞」（不做乐观翻面：`enabled` 不动）。 + pub fn mark_pending(&mut self, file: &str) { + if let Some(item) = self.items.iter_mut().find(|item| item.file == file) { + item.pending = true; + } + } +} + +/// presenter 的视图态 → 页面要画的东西（**唯一**的转换点，`app/view/instances.rs` 调）。 +/// +/// 两条口径： +/// +/// 1. **失败不清列表**：list 失败时保留上一份 `items`（用户还能看见列表，只是多一条红字）， +/// 只有"从来没有过快照"时才是一条纯错误态； +/// 2. **不做乐观翻面**：`enabled` 只来自快照，`pending` 只用来把开关置灰。 +#[must_use] +pub fn from_state(state: &ModsState, catalog: Catalog) -> Mods { + let texts = Texts::of(catalog); + let mut out = Mods { + bound: state.bound.clone(), + loading: state.bound.is_some() && state.view.is_none() && state.failed.is_none(), + ..Mods::default() + }; + if let Some(view) = &state.view { + out.running = view.running; + out.exists = view.exists; + out.skipped = view.skipped.len(); + // **先装列表再算计数**：`enabled_count()` 读的是 `out.items`（顺序反了会画出 `0 启用 · 0 禁用` + // ——M224 出图实测抓到过一次）。 + out.items = view + .entries + .iter() + .map(|entry| Item { + file: entry.file.clone(), + name: entry.name.clone(), + enabled: entry.enabled, + detail: item_detail(entry.bytes, entry.old, texts), + pending: state.is_pending(&entry.file), + }) + .collect(); + out.count = texts.mods_count(out.enabled_count(), out.disabled_count()); + out.skipped_note = texts.mods_skipped(out.skipped); + } + if let Some(failure) = &state.failed { + out.loading = false; + out.error = Some(failure_line(failure, texts)); + } + out +} + +/// 启停失败/读目录失败的一句话（**唯一产地**：Toast 与页面内红字共用）。 +#[must_use] +pub fn failure_line(failure: &ModFailureView, texts: Texts) -> String { + let reason = texts.mods_reason(failure.kind); + let sentence = if failure.file.is_empty() { + texts.mods_failed(reason) + } else { + texts.mods_toggle_failed(&failure.file, reason) + }; + if failure.detail.is_empty() { + return sentence; + } + format!("{sentence}（{}）", failure.detail) +} + +/// 右侧副文案：`1.2 MiB` 或 `1.2 MiB · 旧版本残留`。 +fn item_detail(bytes: u64, old: bool, texts: Texts) -> String { + let size = human_bytes(bytes); + if old { + format!("{size} · {}", texts.mods_old_badge()) + } else { + size + } +} + +/// 画 MODS 区（实例页唯一入口，`detail.rs` 调它）。 +pub(super) fn section<'a>( + ui: &'a Ui, + mods: &'a Mods, + forced: Option, + texts: Texts, +) -> Element<'a, Message> { + let mut body = column![head(ui, mods, texts)] + .spacing(ui.space(Space::X3)) + .width(Length::Fill); + + if mods.loading { + body = body.push(note(ui, texts.mods_loading())); + } else if let Some(error) = mods.error.as_deref() { + body = body.push(frame::text_role( + ui, + TypeRole::BodySmall, + false, + error, + ui.color(Role::Error), + )); + } else if !mods.exists { + body = body.push(note(ui, texts.mods_missing_dir())); + } else if mods.items.is_empty() { + body = body.push(note(ui, texts.mods_empty())); + } else { + // 只读原因放在列表**上面**：用户先看到"为什么点不动"，再去点。 + if mods.running { + body = body.push(note(ui, texts.mods_running())); + } + for item in &mods.items { + body = body.push(entry_row(ui, item, mods.running, forced)); + } + if mods.skipped > 0 { + body = body.push(note(ui, &mods.skipped_note)); + } + } + + frame::card(ui, body) +} + +/// 小标行：`MODS` + 计数（`12 启用 · 3 禁用`）。 +fn head<'a>(ui: &'a Ui, mods: &'a Mods, texts: Texts) -> Element<'a, Message> { + let mut line = row![frame::text_role( + ui, + TypeRole::LabelMedium, + false, + texts.mods_title(), + ui.color(Role::OnSurfaceVariant), + )] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Center) + .width(Length::Fill); + + // 计数只在"真有一份可用快照"时画：读盘中 / 读失败 / 空目录画 0·0 会像"这里什么都没有"。 + let show_count = mods.loaded() && mods.error.is_none() && !mods.items.is_empty(); + if show_count { + line = line.push(frame::text_role( + ui, + TypeRole::BodySmall, + false, + mods.count.as_str(), + ui.color(Role::OnSurfaceVariant), + )); + } + line.into() +} + +/// 一条 mod 的行：名字 + 副文案 + 开关。 +fn entry_row<'a>( + ui: &'a Ui, + item: &'a Item, + running: bool, + forced: Option, +) -> Element<'a, Message> { + let label = column![ + frame::text_role( + ui, + TypeRole::BodyMedium, + false, + item.name.as_str(), + ui.color(if item.enabled { + Role::OnSurface + } else { + Role::OnSurfaceVariant + }), + ), + frame::text_role( + ui, + TypeRole::BodySmall, + false, + item.detail.as_str(), + ui.color(Role::OnSurfaceVariant), + ), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill); + + let toggle = if running || item.pending { + Switch::disabled("", item.enabled) + } else { + Switch::new( + "", + item.enabled, + Message::Instances(PageMessage::SetModEnabled { + file: item.file.clone(), + enabled: !item.enabled, + }), + ) + }; + // M237：开关住在 `frame::card` 里，禁用态的 12% 轨道 / 38% 滑块要叠**卡底**（`frame::BASE`）， + // 不是画布底——否则「游戏在跑 / 请求在飞」那两档的开关会与卡片底色脱节。 + let toggle = toggle.base(frame::BASE); + // 出图取证（`--force-state`）把开关也钉到同一档：否则截图里只有按钮是 hover、 + // 开关还是静息态，视觉复审没法判"悬停时的开关长什么样"。 + let toggle = match forced { + Some(state) => toggle.state(state), + None => toggle, + }; + row![label, switch(ui, toggle)] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Center) + .width(Length::Fill) + .into() +} + +fn note<'a>(ui: &'a Ui, text: &'a str) -> Element<'a, Message> { + frame::text_role( + ui, + TypeRole::BodySmall, + false, + text, + ui.color(Role::OnSurfaceVariant), + ) +} diff --git a/crates/app-iced/src/pages/instances/saves.rs b/crates/app-iced/src/pages/instances/saves.rs new file mode 100644 index 0000000..81e3af1 --- /dev/null +++ b/crates/app-iced/src/pages/instances/saves.rs @@ -0,0 +1,261 @@ +//! 实例详情页的 **SAVES 区**（M235 · STOREMVP 读路径 + M247 · SAVESOPS 写操作）： +//! 存档 / 截图列表 + 打开文件夹 + **每行的重命名 / 备份 / 删除**。 +//! +//! # 位置与形状 +//! +//! 挂在详情列里、MODS 区之后、启动参数卡**之前**（`pages/instances/detail.rs` 的 `detail_column`）。 +//! 与 MODS 区同一套卡片口径：[`frame::card`] + 一个 `LabelMedium` 小标 + 内容。 +//! +//! **为什么在启动参数之前**：与 MODS 区同一个理由（M224 出图实测）——详情列整列是一个滚动区， +//! 而启动参数卡本身就有一屏高；排在它后面等于这整块落在折叠线以下、根本看不见。顺序因此是： +//! 身份（页头 + 元信息）→ 内容（MODS → SAVES）→ 选项（启动参数）→ 动作。 +//! +//! # 为什么不自己再套一层滚动区 +//! +//! 详情列**整列**已经是滚动区（M157 r2）。M224 踩过一次「滚动条里的滚动条」：1180×1000 下两个条 +//! 都认得出来，用户不知道该拖哪一个。这里同样只排内容，长度交给外层那一条。 +//! +//! # 行操作区（M247） +//! +//! 每个**世界**行右侧三个文字按钮：**重命名 / 备份 / 删除**（截图行没有操作区：截图不在这三个 +//! 写操作的范围里）。三档状态： +//! +//! | 状态 | 画什么 | 为什么 | +//! |---|---|---| +//! | 空闲 | 三个按钮 | — | +//! | 这一行的请求在飞 | 一句「正在处理…」顶替按钮 | 连点两次会发两条 rename/delete，第二条必然「世界已不在」 | +//! | 正在行内改名 | 输入框 + 「改名」/「取消」 | 见下 | +//! +//! **不做乐观回显**：行上的名字只来自快照，点完等 host 回一份新快照才变（与 MODS 区同一纪律）。 +//! +//! # 重命名为什么是行内输入，不是模态输入框 +//! +//! 现成的模态队列有 `DialogKind::Input`，但 app 侧的 `dialog::Message` 只有主/次按钮与关闭， +//! **没有「输入变了」这一条**——用输入模态等于重写一套可编辑模态。行内输入复用 +//! `components::inputs` 的单行框（与启动参数区同一个控件），一处新控件都不加。 +//! 输入缓冲住在 presenter 的 [`SavesState::draft`]（页面模型每帧从快照重建，缓冲留在页面里会被 +//! 每一次事件冲掉）。 +//! +//! # 删除为什么必须二次确认 +//! +//! 这是本页唯一**不可逆**的动作。点「删除」只发一条 +//! [`PageMessage::RequestDeleteWorld`]，真正的删除要等模态确认框的主按钮 +//! （`app/update/dialog.rs` 里那一支）。确认框复用仓内现成的模态队列（`state.dialogs`）， +//! 页面不新写弹窗。 +//! +//! # 失败与重试 +//! +//! 读盘失败画一条红字 + 一个「重试」（再发一条 `SavesCommand::List`）。**打开文件夹失败与写操作 +//! 失败不画重试**：那个动作的重试就是再点一次按钮，给一个会去重新列目录的「重试」是错的 +//! affordance（三种失败共用 `detail`，靠大类与 `op` 分别，见 [`failure_line`]）。 +//! +//! 写操作**成功**也有一句话（[`Saves::notice`]）：重命名 / 删除的结果列表上看得见，但备份的落点 +//! 看不见——「点了备份然后什么也没发生」是静默失败，所以回执里带上完整路径与字节数。 +//! +//! # 截图区是**缩略图墙**（M251 · SAVESHOTS，D54） +//! +//! | 变化 | 落点 | +//! |---|---| +//! | 截图不再是一行字，而是「图 + 副文案」的格子 | [`wall`]（2 列 = 同列元信息卡的栅格，见那个模块的文档） | +//! | 像素**不在**这里解，也不在渲染回调里解 | presenter 的后台线程（`host::saves::thumbs`）解好、随快照过来；本层只把 `Handle` 建一次（`model::from_state`） | +//! | 没有像素的格子**不许留白** | 占位框 + 一句短话；副文案把原因说全（超 8 MiB / 读不出 / 解不出 / 超 60 张预算） | +//! +//! ## 为什么拆成三个文件 +//! +//! 加完缩略图墙之后 `saves.rs` 会越过 400 行硬线：模型（[`model`]）、行与操作区（[`rows`]）、 +//! 墙（[`wall`]）各占一块，本文件只剩「卡片骨架 + 小标 + 空态 + 错误行」。 +//! 路径不变（[`model`] 的东西用 `pub use` 转出），`view/instances.rs` 与用例的 import 一行不改。 + +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 crate::app::components::buttons::{self, Button}; +use crate::app::components::interaction::Interaction; +use crate::theme::Ui; + +use super::super::frame; +use super::super::Message; +use super::forced_state; +use super::state::Message as PageMessage; +use super::Texts; + +mod model; +mod rows; +mod wall; + +/// 句柄 memo 的清空入口（只给用例：它是进程级 memo）。 +#[cfg(test)] +pub(super) use model::clear_handles; +pub use model::{failure_line, from_state, Row, Saves, Shot, ShotPreview}; +/// 「改名」那条消息的产地（实现在 [`rows`] 里）——只给用例用，与 `op_line` 同一条口径。 +#[cfg(test)] +pub(super) use rows::commit_rename; +/// 写操作成功那句话的产地（实现在 [`rows`] 里）。 +/// +/// 生产代码走 `model::from_state → rows::op_line`；这条 re-export 只给**用例**用 +/// （`tests/saves/write.rs` 从这里取），所以挂在 `cfg(test)` 下，免得非测试构建报未用导入。 +#[cfg(test)] +pub(super) use rows::op_line; + +/// 画 SAVES 区（实例页唯一入口，`detail.rs` 调它）。 +pub(super) fn section<'a>( + ui: &'a Ui, + saves: &'a Saves, + forced: Option, + texts: Texts, +) -> Element<'a, Message> { + let mut body = column![head(ui, saves, forced, texts)] + .spacing(ui.space(Space::X3)) + .width(Length::Fill); + + if saves.loading { + body = body.push(note(ui, texts.saves_loading())); + return frame::card(ui, body); + } + if let Some(error) = saves.error.as_deref() { + body = body.push(frame::text_role( + ui, + TypeRole::BodySmall, + false, + error, + ui.color(Role::Error), + )); + if saves.retryable { + body = body.push(buttons::text( + ui, + forced_state( + Button::new( + texts.saves_retry(), + Message::Instances(PageMessage::ReloadSaves), + ), + forced, + ) + // M237：卡片里的控件把底传成卡底（hover / 禁用状态层叠卡实色）。 + .base(frame::BASE), + )); + } + // 旧列表还在时照旧画出来（失败不清列表），用户能看见上一次读到的东西； + // 一份快照都没有时到此为止——**不许**在"读不了"下面再补一句"这里还没有世界"。 + if !saves.has_view { + return frame::card(ui, body); + } + } + if saves.missing { + body = body.push(note(ui, texts.saves_missing_dir())); + return frame::card(ui, body); + } + if saves.nothing_yet() { + body = body.push(note(ui, texts.saves_empty())); + return frame::card(ui, body); + } + // 写操作成功的回执（重命名 / 删除 / 备份）——放在列表**上面**：用户刚点的就是这里。 + if let Some(notice) = saves.notice.as_deref() { + body = body.push(note(ui, notice)); + } + + // 世界 → 截图，两组各一个小标；某一组为空时只给一句话，不留空小标。 + body = body.push(sub_head(ui, texts.saves_worlds())); + if saves.worlds.is_empty() { + body = body.push(note(ui, texts.saves_no_worlds())); + } else { + for item in &saves.worlds { + body = body.push(rows::world(ui, item, saves, forced, texts)); + } + } + body = body.push(sub_head(ui, texts.saves_screenshots())); + if saves.screenshots.is_empty() { + body = body.push(note(ui, texts.saves_no_screenshots())); + } else { + // 缩略图墙（M251）：一行两格（详情列 ≤424 宽，三格装不下），没像素的格子给占位框 + 原因。 + body = body.push(wall::grid(ui, &saves.screenshots)); + } + if saves.skipped > 0 { + body = body.push(note(ui, &saves.skipped_note)); + } + + frame::card(ui, body) +} + +/// 小标行：`SAVES` + 计数 + 右侧「打开存档文件夹」。 +fn head<'a>( + ui: &'a Ui, + saves: &'a Saves, + forced: Option, + texts: Texts, +) -> Element<'a, Message> { + // 左半是「存档 + 计数」，右半是「打开存档文件夹」：左半用一个吃满宽度的容器顶开， + // 按钮才会落在卡片右边缘（与 `head` 之外那些卡片的动作行同一套摆法）。 + let mut left = row![frame::text_role( + ui, + TypeRole::LabelMedium, + false, + texts.saves_title(), + ui.color(Role::OnSurfaceVariant), + )] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Center); + + // 计数只在"真有一份可用快照"时画：读盘中 / 读失败 / 空目录画 0·0 会像"这里什么都没有"。 + let show_count = saves.has_view + && saves.error.is_none() + && !saves.missing + && !(saves.worlds.is_empty() && saves.screenshots.is_empty()); + if show_count { + left = left.push(frame::text_role( + ui, + TypeRole::BodySmall, + false, + saves.count.as_str(), + ui.color(Role::OnSurfaceVariant), + )); + } + + // 「打开文件夹」始终可点：目录还没有时 host 会退到运行目录，失败也有就地说明 + // （见 `host::saves::open_target`）。 + let open = buttons::text( + ui, + forced_state( + Button::new( + texts.saves_open_folder(), + Message::Instances(PageMessage::OpenSavesFolder), + ), + forced, + ) + // M237：这枚按钮在 SAVES 卡里 ⇒ 状态层叠卡底（`frame::BASE`），不是画布底。 + .base(frame::BASE), + ); + row![ + container(left) + .width(Length::Fill) + .align_y(Alignment::Center), + open + ] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Center) + .width(Length::Fill) + .into() +} + +fn sub_head<'a>(ui: &'a Ui, text: &'a str) -> Element<'a, Message> { + frame::text_role( + ui, + TypeRole::LabelSmall, + false, + text, + ui.color(Role::OnSurfaceVariant), + ) +} + +fn note<'a>(ui: &'a Ui, text: &'a str) -> Element<'a, Message> { + frame::text_role( + ui, + TypeRole::BodySmall, + false, + text, + ui.color(Role::OnSurfaceVariant), + ) +} diff --git a/crates/app-iced/src/pages/instances/saves/model.rs b/crates/app-iced/src/pages/instances/saves/model.rs new file mode 100644 index 0000000..1f251fb --- /dev/null +++ b/crates/app-iced/src/pages/instances/saves/model.rs @@ -0,0 +1,334 @@ +//! SAVES 区的**视图模型**：快照 → 页面要画的东西（M235 的行 + M251 的缩略图墙）。 +//! +//! 从 `saves.rs` 拆出（M251：加完缩略图墙的模型之后那个文件会越过 400 行硬线）。 +//! 拆法是「**纯搬移 + 一族新增**」：`Row` / `Editing` / `Saves` / [`from_state`] / +//! [`failure_line`] 一律逐行搬来，只把截图那一族从「一行字」换成 [`Shot`]（缩略图 + 副文案）； +//! `saves.rs` 用 `pub use model::{…}` 保住原有路径，页面与用例的 import 一行不改。 +//! +//! # 缩略图的句柄为什么在这里建 +//! +//! [`from_state`] 是「快照 → 模型」的**唯一**转换点，而 `iced` 的 `Handle::from_rgba` 会把像素 +//! 搬进渲染器（一次上传）。渲染回调（`view()`）每帧都跑、`refresh_view` 只在事件之后跑， +//! 所以句柄只能在这里建一次：建在 `view()` 里等于每帧重传 6MB 纹理。 +//! +//! 这也正是 D54「**不许在渲染回调里解码**」的同一条纪律的延伸：解码在 presenter 的后台线程， +//! 句柄在这里，`view()` 只借。 + +use std::collections::HashMap; +use std::sync::{Mutex, OnceLock}; + +use iced::widget::image::Handle; + +use unlucky_i18n::Catalog; +use unlucky_presenter::dto::{ + SavesFailureKind, SavesFailureOp, SavesFailureView, ScreenshotPreview, ScreenshotThumbKind, + ScreenshotView, +}; +use unlucky_presenter::state::SavesState; + +use super::rows; +use super::Texts; + +/// 列表里的一个**世界**行。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Row { + /// 世界目录名（磁盘原样；写操作把它原样带回去当「源」）。 + pub name: String, + /// 右侧/下方副文案（时间、图标标记，已由这一层拼好）。 + pub detail: String, +} + +/// 缩略图墙上的一格（一张截图）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Shot { + /// 磁盘文件名（含扩展名）。墙上一格不印它（`160px` 放不下），但失败原因要能指认它。 + pub name: String, + /// 格子下面的副文案：正常时是「大小 · 时间」，没有预览时是**为什么**没有。 + pub detail: String, + /// 图本身（或占位）。 + pub preview: ShotPreview, +} + +/// 一格截图里的画面。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum ShotPreview { + /// 缩略图（句柄在 [`from_state`] 里建好；见模块文档）。 + Ready { + /// 已上传的 RGBA 句柄。 + handle: Handle, + }, + /// 没有可画的像素：框里一句话（「未生成预览」/ 具名原因）。 + Missing { + /// 短句（`160×90` 的框里放得下）。 + note: String, + }, +} + +/// 正在行内重命名的那一行（来源是 presenter 的 `SavesState::draft`）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Editing { + /// 哪个世界。 + pub dir: String, + /// 输入框里的内容（原样）。 + pub text: String, +} + +/// SAVES 区的展示模型（`Model::saves`）。 +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct Saves { + /// 这份数据属于哪个实例（`None` = 不在详情页 / 还没请求过）。 + pub bound: Option, + /// 正在读盘（进详情页首帧：请求已发出、快照还没回来）。 + pub loading: bool, + /// 读盘/打开/写操作失败的人读原因（app 层按 i18n 拼好）。 + pub error: Option, + /// 这一条失败能不能靠「再列一次」解决（只有读盘失败算）。 + pub retryable: bool, + /// 手里有没有一份**快照**（`false` = 只拿到了失败，"还没有世界"那几句不许画）。 + pub has_view: bool, + /// 两个目录都不存在（新实例的常态：还没进过游戏）。 + pub missing: bool, + /// 世界行。 + pub worlds: Vec, + /// 截图墙（新的在前，顺序由 core 给）。 + pub screenshots: Vec, + /// 计数行（`3 个世界 · 12 张截图`）：**在这一层算好**，页面只借 `&str`。 + /// + /// 为什么不留到页面里 `format!`：iced 的 `Element` 只借这一帧的数据，页面函数返回的是 + /// **借用局部变量的树**，局部 `String` 一出栈就悬空（`E0515`）。与 [`super::Row`] + /// 之外的 `Mods::count` 同一条做法。 + pub count: String, + /// 跳过条目数（符号链接 / 非图片 / 读不出）。 + pub skipped: usize, + /// 跳过提示（`跳过 3 项`）。 + pub skipped_note: String, + /// 正在行内重命名的那一行（`None` = 没有在改名）。 + pub editing: Option, + /// 有写操作在飞的那个世界（`None` = 空闲）。 + pub busy: Option, + /// 上一次写操作成功的那句话（`None` = 这一拍没有回执）。 + pub notice: Option, +} + +impl Saves { + /// 有没有拿到一份快照（成功或失败都算；`loading` 中不算）。 + #[must_use] + pub fn loaded(&self) -> bool { + self.bound.is_some() && !self.loading + } + + /// 两个目录都在、但里面什么都没有（**必须先有一份快照**：纯失败态不是"这里空的"）。 + #[must_use] + pub fn nothing_yet(&self) -> bool { + self.has_view && !self.missing && self.worlds.is_empty() && self.screenshots.is_empty() + } + + /// 这个世界的写操作在飞吗（那一行画「正在处理…」并把按钮拿掉）。 + #[must_use] + pub fn busy_with(&self, dir: &str) -> bool { + self.busy.as_deref() == Some(dir) + } + + /// 截图墙里有多少张**真出图**了（出图与用例的抓手：`0` 就是一张都没解出来）。 + #[must_use] + pub fn thumbnails(&self) -> usize { + self.screenshots + .iter() + .filter(|shot| matches!(shot.preview, ShotPreview::Ready { .. })) + .count() + } +} + +/// presenter 的视图态 → 页面要画的东西（**唯一**的转换点，`app/view/instances.rs` 调）。 +/// +/// 三条口径： +/// +/// 1. **失败不清列表**：list 失败时保留上一份 `worlds`/`screenshots`（用户还能看见旧列表， +/// 只是多一条红字），只有"从来没有过快照"时才是一条纯错误态； +/// 2. **不做乐观更新**：行上的名字只来自快照，写操作的"在飞"只用来置灰那一行； +/// 3. **回执只画一次**：`view.last_op` 是 host 写在快照里的，下一次普通 List 就没了。 +#[must_use] +pub fn from_state(state: &SavesState, catalog: Catalog) -> Saves { + let texts = Texts::of(catalog); + let mut out = Saves { + bound: state.bound.clone(), + loading: state.bound.is_some() && state.view.is_none() && state.failed.is_none(), + editing: state.draft.as_ref().map(|draft| Editing { + dir: draft.dir.clone(), + text: draft.text.clone(), + }), + busy: state.pending.as_ref().map(|op| op.dir().to_string()), + ..Saves::default() + }; + if let Some(view) = &state.view { + out.has_view = true; + out.missing = !view.exists && !view.screenshots_exists; + // 计数直接问快照（`view.world_count()`），不从刚装好的 `out.worlds` 再数一遍—— + // M224 出图实测过"先算计数后装列表"画出 `0 启用 · 0 禁用` 的那种顺序错，这里从根上绕开。 + out.worlds = view + .worlds + .iter() + .map(|world| Row { + name: world.dir.clone(), + detail: rows::world_detail(world.icon, world.modified_ms, texts), + }) + .collect(); + out.screenshots = view + .screenshots + .iter() + .map(|shot| shot_cell(&view.screenshots_dir, shot, texts)) + .collect(); + out.count = texts.saves_count(view.world_count(), view.screenshot_count()); + out.skipped = view.skipped_count(); + out.skipped_note = texts.saves_skipped(out.skipped); + out.notice = view.last_op.as_ref().map(|op| rows::op_line(op, texts)); + } + if let Some(failure) = &state.failed { + out.loading = false; + out.error = Some(failure_line(failure, texts)); + // 只有「读盘 / 列目录」失败才值得重试；写操作的重试就是再点一次那个按钮。 + out.retryable = failure.op.is_none() && failure.kind != SavesFailureKind::OpenFailed; + } + out +} + +/// 句柄缓存的条目上限（超过就整表清空）。 +/// +/// 一张 160×160 的 RGBA 最坏 ≈ 100KB ⇒ 120 条 ≈ **12MB 上限**；正常一屏 ≤60 张（≈6MB）。 +/// 与 presenter 的 `MAX_CACHE_ENTRIES`（也是 120）同量级：两层各自有天花板，不叠成无界。 +/// 清空而不是 LRU：代价是下一次 `refresh_view` 重传一遍（罕见），收益是这段逻辑没有顺序状态。 +const MAX_HANDLES: usize = 120; + +/// 句柄缓存：`(截图目录, 文件名, mtime, 字节数) → Handle`。 +/// +/// ## 为什么必须缓存（而不是每次 `from_state` 建一个新的） +/// +/// `Handle::from_rgba` 每次都生成一个**新 id**，而 `iced` 的渲染器按 id 缓存纹理：id 一变就 +/// 重新上传一遍像素。`from_state` 挂在 `refresh_view` 上，而 `refresh_view` 每个 UI 事件都跑 +/// （点一下、打一个字）——一屏 60 张就是「每次事件重传 ≈6MB」。M251 复审要求把这条成本消掉： +/// 缓存之后同一张图永远是同一个 id，纹理只上传一次。 +/// +/// ## 键为什么与 presenter 的缓存键同源 +/// +/// presenter 那边是 `(完整路径, mtime, 字节数)`（`host::saves::thumbs`），这里换成 +/// `(目录, 文件, mtime, 字节数)`——同一组事实，只是目录单独放一格，免得每次拼长串。 +/// 任一字段变了（文件被覆盖）就是另一张图 ⇒ 新 id ⇒ 重传，这也正是我们要的。 +fn handles() -> &'static Mutex> { + static HANDLES: OnceLock>> = OnceLock::new(); + HANDLES.get_or_init(|| Mutex::new(HashMap::new())) +} + +/// 句柄键的分隔符（`0x01`：文件名里不可能出现，也避免 `` 与 `` 撞键）。 +/// +/// 用 `push` 拼而不是 `format!`：`format!` 的模板串里带 `dir`/`u` 这类 ASCII 词，会被 +/// `pages/instances/tests/i18n.rs` 的「页面里不许写死英文文案」守门当成界面字面量抓走。 +const KEY_SEP: char = '\u{1}'; + +/// 取这张截图的句柄：命中就复用（id 不变 ⇒ 不重传），未命中才建一次。 +fn handle_for( + dir: &str, + shot: &ScreenshotView, + thumb: &unlucky_presenter::dto::ThumbnailView, +) -> Handle { + let mut key = String::with_capacity(dir.len() + shot.file.len() + 24); + key.push_str(dir); + key.push(KEY_SEP); + key.push_str(&shot.file); + key.push(KEY_SEP); + match shot.modified_ms { + Some(ms) => key.push_str(&ms.to_string()), + // 取不到时间：占一个不含数字的记号（不会与任何毫秒数撞上）。 + None => key.push('-'), + } + key.push(KEY_SEP); + key.push_str(&shot.bytes.to_string()); + let mut store = handles() + .lock() + .unwrap_or_else(|poison| poison.into_inner()); + if let Some(cached) = store.get(&key) { + return cached.clone(); + } + let handle = Handle::from_rgba(thumb.width, thumb.height, thumb.pixels.clone()); + if store.len() >= MAX_HANDLES { + store.clear(); + } + store.insert(key, handle.clone()); + handle +} + +/// 清空句柄缓存（**只给用例**：这是进程级 memo，用例之间必须能从已知状态起跑）。 +#[cfg(test)] +pub(in crate::pages::instances) fn clear_handles() { + handles() + .lock() + .unwrap_or_else(|poison| poison.into_inner()) + .clear(); +} + +/// 一张截图 → 墙上的一格（缩略图句柄 / 占位 + 副文案）。 +/// +/// **三种状态各有各的话**（D54 第 6 条：失败逐条可见）： +/// +/// | 快照里的状态 | 框里 | 副文案 | +/// |---|---|---| +/// | `Ready`（像素自洽） | 真图 | `大小 · 时间` | +/// | `Ready`（像素长度不对） | 「解不出这张图」 | `大小 · 时间`（防御性：壳层不该拿到坏像素） | +/// | `NotGenerated` | 「未生成预览」 | `大小 · 时间`（超预算没轮到） | +/// | `Failed` | 具名原因（太大 / 读不出 / 解不出） | `大小 · 时间`（原文留在 DTO 里，不上墙） | +fn shot_cell(dir: &str, shot: &ScreenshotView, texts: Texts) -> Shot { + let stamp = rows::shot_detail(shot.bytes, shot.modified_ms, texts); + match &shot.preview { + ScreenshotPreview::Ready(thumb) if thumb.is_consistent() => Shot { + name: shot.file.clone(), + detail: stamp, + // 句柄按 (目录, 文件, mtime, 大小) 复用：同一张图在后续每一次 `refresh_view` 里 + // 拿到的都是**同一个 id** ⇒ 渲染器不会重传纹理（见 [`handle_for`]）。 + preview: ShotPreview::Ready { + handle: handle_for(dir, shot, thumb), + }, + }, + // 像素长度与宽高对不上：壳层不该拿到这种数据，但拿到了也不能画成花屏。 + ScreenshotPreview::Ready(_) => missing( + shot, + texts.saves_preview_reason(ScreenshotThumbKind::Decode), + stamp, + ), + ScreenshotPreview::NotGenerated => missing(shot, texts.saves_preview_none(), stamp), + ScreenshotPreview::Failed(failure) => { + missing(shot, texts.saves_preview_reason(failure.kind), stamp) + } + } +} + +/// 「没有可画的像素」那一格：**框里说为什么**（短句），**格子下面照旧是大小与时间**。 +/// +/// 为什么原因不进副文案：`160px` 宽的格子里，「原因 + OS 原文」会摊成三行，把墙变得比图还吵； +/// 而 `ScreenshotThumbFailure::detail`（`9437184 > 8388608 字节` / `Access is denied.`）留在 +/// DTO 里，是排障用的原文，不是给墙看的正文。D54 第 6 条要的是「逐条、结构化、不是静默」—— +/// 那一句在框里，每条各说各的。 +fn missing(shot: &ScreenshotView, note: &str, stamp: String) -> Shot { + Shot { + name: shot.file.clone(), + detail: stamp, + preview: ShotPreview::Missing { + note: note.to_string(), + }, + } +} + +/// 失败的一句话（**唯一产地**：页面内红字用它，本版没有 Toast）。 +#[must_use] +pub fn failure_line(failure: &SavesFailureView, texts: Texts) -> String { + let reason = texts.saves_reason(failure.kind); + let sentence = match (failure.op, failure.kind) { + (Some(SavesFailureOp::Rename), _) => texts.saves_rename_failed(&failure.file, reason), + (Some(SavesFailureOp::Delete), _) => texts.saves_delete_failed(&failure.file, reason), + (Some(SavesFailureOp::Backup), _) => texts.saves_backup_failed(&failure.file, reason), + (None, SavesFailureKind::OpenFailed) => texts.saves_open_failed(reason), + (None, _) => texts.saves_failed(reason), + }; + if failure.detail.is_empty() { + return sentence; + } + format!("{sentence}（{}）", failure.detail) +} diff --git a/crates/app-iced/src/pages/instances/saves/rows.rs b/crates/app-iced/src/pages/instances/saves/rows.rs new file mode 100644 index 0000000..1fb041d --- /dev/null +++ b/crates/app-iced/src/pages/instances/saves/rows.rs @@ -0,0 +1,234 @@ +//! SAVES 区的一行与它的操作区（M247）。 +//! +//! 从 `saves.rs` 拆出：那个文件加完写操作的行内输入与三个按钮之后会越过 400 行硬线 +//! （拆法与仓库其它 `-p1/-p2` 一致——**纯搬移 + 一个函数一族**，判据留在 `saves.rs`）。 +//! +//! | 函数 | 画什么 | +//! |---|---| +//! | [`world`] | 一个世界：名字 + 副文案 +（空闲）重命名/备份/删除、（在飞）「正在处理…」、（改名中）输入框 + 改名/取消 | +//! | [`world_detail`] / [`shot_detail`] | 两行副文案（`shot_detail` 现在喂缩略图墙的格子，见 [`super::wall`]） | +//! +//! M251：原来给截图用的只读行 [`world_plain`] **已删**——截图改画缩略图墙（`super::wall`）， +//! 留着一个没人调的 `pub(super) fn` 只会在 `-D warnings` 下变成死代码告警。 +//! +//! 三枚按钮与「打开存档文件夹」同一条口径：`buttons::text` + `frame::BASE`（M237：卡片里的控件 +//! 把底传成卡底，hover/禁用状态才叠在卡实色上），出图取证时整行一起跟 `--force-state`。 +//! +//! 输入框用 `components::inputs::text_field`（与启动参数区同一个控件）。**回车 = 点「改名」** +//! （M252 / P18）：`Field::on_submit` 与右边那枚按钮共用 [`commit_rename`] 这一个消息产地， +//! 所以空名 / 原名不变 / 非法字符走的仍是原来那条校验（`app/update/instances.rs` 的空名与 +//! 「没改」两条短路 + `core::game::saves::write::boundary::check_name` 的路径规则）， +//! **回车没有绕开任何一道边界**。 + +use iced::widget::{column, row}; +use iced::{Alignment, Element, Length}; + +use unlucky_design::color::Role; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; +use unlucky_presenter::dto::{human_bytes, SavesOped}; + +use crate::app::components::buttons::{self, Button}; +use crate::app::components::inputs::{text_field, Field}; +use crate::app::components::interaction::Interaction; +use crate::theme::Ui; + +use super::super::forced_state; +use super::super::frame; +use super::super::state::Message as PageMessage; +use super::super::Message; +use super::super::Texts; +use super::{Row, Saves}; + +/// 一个世界行：名字 + 副文案 + 操作区（三档状态见模块文档与 `saves.rs`）。 +pub(super) fn world<'a>( + ui: &'a Ui, + item: &'a Row, + saves: &'a Saves, + forced: Option, + texts: Texts, +) -> Element<'a, Message> { + if let Some(editing) = saves.editing.as_ref().filter(|edit| edit.dir == item.name) { + return rename_row(ui, editing.text.as_str(), forced, texts); + } + let label = labels(ui, item, Role::OnSurface); + let dir = item.name.clone(); + let actions: Element<'a, Message> = if saves.busy_with(&dir) { + text_note(ui, texts.saves_busy(), Role::OnSurfaceVariant) + } else { + row![ + action( + ui, + texts.saves_rename(), + PageMessage::StartRenameWorld { dir: dir.clone() }, + forced + ), + action( + ui, + texts.saves_backup(), + PageMessage::BackupWorld { dir: dir.clone() }, + forced + ), + action( + ui, + texts.saves_delete(), + PageMessage::RequestDeleteWorld { dir }, + forced + ), + ] + .spacing(ui.space(Space::X1)) + .align_y(Alignment::Center) + .into() + }; + row![label, actions] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Center) + .width(Length::Fill) + .into() +} + +/// 行内重命名：输入框 + 「改名」/「取消」（占满整行，副文案让位）。 +fn rename_row<'a>( + ui: &'a Ui, + text: &'a str, + forced: Option, + texts: Texts, +) -> Element<'a, Message> { + let field = text_field( + ui, + Field::new(text) + // M237：输入框住在卡里 ⇒ 状态层与描边叠卡底。 + .base(frame::BASE) + .placeholder(texts.saves_rename_placeholder()) + .width(Length::Fill) + // P18：回车与右枚按钮**同一个**消息产地（见 `commit_rename` 的文档）。 + .on_submit(|| Message::Instances(commit_rename())), + |value| Message::Instances(PageMessage::RenameWorldChanged(value)), + ); + row![ + field, + action(ui, texts.saves_rename_confirm(), commit_rename(), forced), + action( + ui, + texts.saves_cancel(), + PageMessage::CancelRenameWorld, + forced + ), + ] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Center) + .width(Length::Fill) + .into() +} + +/// 「改名」那一下要发的那条页面意图——**按钮与回车共用的唯一产地**（M252 / P18）。 +/// +/// 为什么抽成一个函数：「回车走的是不是同一条路」在 iced 里量不到（`Element` 没有内省接口， +/// 见 `pages::layout::source` 的模块文档），能钉住的只有**两条路拿的是同一个 Message**—— +/// 于是「空名 / 原名不变 / 非法字符不许提交」那几道校验自动对回车同样成立。 +pub(crate) fn commit_rename() -> PageMessage { + PageMessage::CommitRenameWorld +} + +/// 名字 + 副文案（两行）。 +fn labels<'a>(ui: &'a Ui, item: &'a Row, color: Role) -> iced::widget::Column<'a, Message> { + column![ + frame::text_role( + ui, + TypeRole::BodyMedium, + false, + item.name.as_str(), + ui.color(color) + ), + frame::text_role( + ui, + TypeRole::BodySmall, + false, + item.detail.as_str(), + ui.color(Role::OnSurfaceVariant), + ), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill) +} + +/// 一枚行内文字按钮（统一套 `frame::BASE` 与 `--force-state`）。 +fn action<'a>( + ui: &'a Ui, + label: &'a str, + message: PageMessage, + forced: Option, +) -> Element<'a, Message> { + buttons::text( + ui, + forced_state(Button::new(label, Message::Instances(message)), forced).base(frame::BASE), + ) +} + +fn text_note<'a>(ui: &'a Ui, text: &'a str, color: Role) -> Element<'a, Message> { + frame::text_role(ui, TypeRole::BodySmall, false, text, ui.color(color)) +} + +/// 写操作成功后的一句话（**唯一产地**：卡片里那条成功提示）。 +/// +/// 备份那句必须带**完整路径**：落点在文件系统某处，用户得知道去哪找。 +#[must_use] +pub(crate) fn op_line(op: &SavesOped, texts: Texts) -> String { + match op { + SavesOped::Renamed { from, to } => texts.saves_renamed(from, to), + SavesOped::Deleted { dir } => texts.saves_deleted(dir), + SavesOped::BackedUp { + dir, + path, + bytes, + skipped, + .. + } => { + let mut line = texts.saves_backed_up(dir, path, &human_bytes(*bytes)); + if *skipped > 0 { + // 备份跳过链接这件事必须说出来：静默少打包几个文件比失败更坏。 + line.push_str(" · "); + line.push_str(&texts.saves_backup_skipped(*skipped)); + } + line + } + } +} + +/// 世界那一行的副文案：`2024-05-01 10:00 UTC`，有图标时再挂一个「有图标」。 +pub(super) fn world_detail(icon: bool, modified_ms: Option, texts: Texts) -> String { + let stamp = stamp(modified_ms, texts); + if icon { + format!("{stamp} · {}", texts.saves_world_icon()) + } else { + stamp + } +} + +/// 截图那一行的副文案：`1.2 MiB · 2024-05-01 10:00 UTC`。 +pub(super) fn shot_detail(bytes: u64, modified_ms: Option, texts: Texts) -> String { + format!("{} · {}", human_bytes(bytes), stamp(modified_ms, texts)) +} + +/// mtime（UTC 毫秒）→ `2024-05-01 10:00 UTC`；取不到就说"时间未知"（不拿 0 或当前时间糊）。 +/// +/// 换算走 `core::launch::time` 的 RFC3339 格式化，再按 `app/view/instances.rs::last_played` +/// 同一刀切开——**UTC 是 core 的口径，不做本地时区换算**（那属时间格式 mission）。 +fn stamp(modified_ms: Option, texts: Texts) -> String { + let Some(text) = modified_ms.and_then(stamp_utc) else { + return texts.saves_time_unknown().to_string(); + }; + text +} + +/// 毫秒 → `YYYY-MM-DD HH:MM UTC`（`None` = 早于 1970 / 溢出，不猜）。 +fn stamp_utc(ms: u64) -> Option { + let at = std::time::UNIX_EPOCH.checked_add(std::time::Duration::from_millis(ms))?; + let text = unlucky_core::launch::time::format_rfc3339_millis(at); + // `2024-05-01T10:00:00.000Z` → `2024-05-01 10:00 UTC`（切两段，不解析、不重排）。 + // 模板与 `app/view/instances.rs::last_played` **一字不差**：同一句话只能有一份写法， + // 页面源码的字面量白名单里也只有这一条（`instances/tests/i18n.rs` 的 `ALLOWED_LITERALS`）。 + let date = text.get(0..10)?; + let time = text.get(11..16)?; + Some(format!("{date} {time} UTC")) +} diff --git a/crates/app-iced/src/pages/instances/saves/wall.rs b/crates/app-iced/src/pages/instances/saves/wall.rs new file mode 100644 index 0000000..b8962e3 --- /dev/null +++ b/crates/app-iced/src/pages/instances/saves/wall.rs @@ -0,0 +1,126 @@ +//! 截图**缩略图墙**（M251 · SAVESHOTS，D54）。 +//! +//! ## 画什么 +//! +//! 每格 = 「图（或占位框）」+ 下面一行副文案，按 [`PER_ROW`] 列换行排。图的最大边由 +//! `palette_extract::THUMBNAIL_MAX_EDGE = 160` 定（解码那一侧），这里只负责**摆**： +//! +//! | 格子内容 | 画什么 | +//! |---|---| +//! | [`ShotPreview::Ready`] | `iced::widget::image::Handle` 已经是 RGBA 像素，直接画（**不再解码**） | +//! | [`ShotPreview::Missing`] | `160×90` 的描边占位框 + 一句短话（「未生成预览」/ 具名原因） | +//! +//! ## 为什么不用 `grid_row` +//! +//! iced 0.14 的基础控件里没有流式网格，而本仓没有引 `iced_aw` 之类的扩展 crate（多一个依赖要过 +//! `deny.toml`）。墙的行数是 `ceil(n / PER_ROW)`，用手写的 `column` + `row` 摆——比引一个 +//! 扩展 crate 便宜，也比让它自己换行可靠（换行行为不会被窗口宽度悄悄改掉）。 +//! +//! ## 宽高比 +//! +//! 缩略图的**长边是 160**，短边按原图比例（截图通常 16:9 ⇒ 160×90）。所以宽度钉死、高度 +//! `Shrink`：`iced` 的 image 控件在 `width = Fixed` / `height = Shrink` 下按原图比例取高， +//! 不拉伸（`ContentFit::Contain` 默认）。占位框反而钉死 `160×90`——它是"这里本该有一张图"的 +//! 占位，尺寸要可预测，不能让一句话把它撑变形。 +//! +//! ## 一行放几格（这条是**量出来的**，不是拍的） +//! +//! 详情列的宽度由 `pages::layout` 的 `FrameMetrics::column` 定，而它 `≤ measure_cap_px()` +//! （1180 窗宽下 = 424，见 `layout.rs` 的文档）。卡片还有左右内边距 ⇒ 实际内宽约 **370**。 +//! +//! 于是：**3 格 = 3 × 160 + 2 × 12 = 504px 装不下**（M251 第一次出图实测：第 3 格被挤成一条 +//! 竖条，`未生成预览` 四个字竖着排）。2 格 = `2 × 160 + 12 = 332px`，与同一列里元信息卡的 +//! 两列栅格（`META_CARD_MIN_WIDTH × 2 + META_GAP = 332`）**同宽**——这不是巧合，是同一列里 +//! 已经成立的节奏。 +//! +//! 代价写在明处：60 张 = 30 行，要滚很久。换 3 列只能把格子缩到 ~112px（图更小），D54 的 +//! `THUMBNAIL_MAX_EDGE = 160` 也就白解了；要真正做到「宽度自适应列数」得引一个栅格控件， +//! 那是新依赖，不在本 mission 的取舍里。 + +use iced::widget::{column, container, image, row}; +use iced::{Alignment, Background, Element, Length}; + +use unlucky_design::color::Role; +use unlucky_design::shape::ShapeScale; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; + +use crate::theme::Ui; + +use super::super::frame; +use super::super::Message; +use super::{Shot, ShotPreview}; + +/// 一格缩略图的宽（= 解码侧的最大边，两者必须同源：图比格子小会留白，比格子大会被缩）。 +const THUMB_WIDTH: f32 = 160.0; + +/// 占位框的高（16:9，与常见的截图宽高比一致）。 +const THUMB_HEIGHT: f32 = 90.0; + +/// 一行放几格（= 同一列里元信息卡的两列栅格；理由见模块文档）。 +const PER_ROW: usize = 2; + +/// 整面墙（`saves.rs` 的 `section` 调；空列表不该走到这里）。 +pub(super) fn grid<'a>(ui: &'a Ui, shots: &'a [Shot]) -> Element<'a, Message> { + let mut wall = column![].spacing(ui.space(Space::X3)).width(Length::Fill); + for chunk in shots.chunks(PER_ROW) { + let mut line = row![] + .spacing(ui.space(Space::X3)) + .align_y(Alignment::Start); + for shot in chunk { + line = line.push(cell(ui, shot)); + } + wall = wall.push(line); + } + wall.into() +} + +/// 一格：图或占位框 + 副文案。 +fn cell<'a>(ui: &'a Ui, shot: &'a Shot) -> Element<'a, Message> { + let picture: Element<'a, Message> = match &shot.preview { + ShotPreview::Ready { handle } => image(handle.clone()) + .width(Length::Fixed(THUMB_WIDTH)) + .height(Length::Shrink) + .border_radius(ui.radius_dp(ShapeScale::Small)) + .into(), + ShotPreview::Missing { note } => placeholder(ui, note.as_str()), + }; + column![ + picture, + frame::text_role( + ui, + TypeRole::BodySmall, + false, + shot.detail.as_str(), + ui.color(Role::OnSurfaceVariant), + ) + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fixed(THUMB_WIDTH)) + .into() +} + +/// 占位框：描边 + 容器色底 + 居中的那句短话。 +/// +/// 颜色全部走令牌（D55 第 3 条：组件源码里不许出现字面色值）；底用 `SurfaceContainerHigh` +/// 而不是画布色，是为了在卡片（`SurfaceContainerLow`）上还能看出"这里有一个格子"。 +fn placeholder<'a>(ui: &'a Ui, note: &'a str) -> Element<'a, Message> { + container(frame::text_role_centered( + ui, + TypeRole::BodySmall, + false, + note, + ui.color(Role::OnSurfaceVariant), + )) + .width(Length::Fixed(THUMB_WIDTH)) + .height(Length::Fixed(THUMB_HEIGHT)) + .padding(ui.space(Space::X2)) + .align_x(Alignment::Center) + .align_y(Alignment::Center) + .style(move |_theme| container::Style { + background: Some(Background::Color(ui.color(Role::SurfaceContainerHigh))), + border: ui.outlined(ShapeScale::Small), + ..container::Style::default() + }) + .into() +} diff --git a/crates/app-iced/src/pages/instances/state.rs b/crates/app-iced/src/pages/instances/state.rs new file mode 100644 index 0000000..29cb020 --- /dev/null +++ b/crates/app-iced/src/pages/instances/state.rs @@ -0,0 +1,332 @@ +//! 实例页的**页面状态**（M157）：启动参数区的表单。 +//! +//! ## 为什么状态在 app、页面只借一帧 +//! +//! iced 的 `view` 不能持有跨帧状态，而启动参数区是可编辑的（两个多行框 + 两行单行框 + +//! 三态 chips）。所以表单状态的所有者是 `App`（`app/state.rs` 的 `launch_form` 字段）， +//! 页面层只在这一帧借用；这与设置页「组状态归 `App`」是同一条纪律（`pages/settings/state.rs`）。 +//! +//! ## 与快照的关系（唯一的重播种点） +//! +//! [`LaunchForm::sync`] 由 `App::refresh_view` 调用： +//! +//! | 情况 | 行为 | +//! |---|---| +//! | 换了一个实例 | **重播种**（用户没写完的草稿不能串到别的实例上） | +//! | 同一个实例、没改过 | 重播种（保存/外部改了配置后跟着刷新） | +//! | 同一个实例、改过（`dirty`） | **不覆盖**（每来一条事件就把输入抹掉是不可接受的） | +//! +//! 「留空 = 跟随下一层」由提交时把空串原样交给 host 表达（`Some("")` = 清空）， +//! 表单自己不做任何回落计算——回落只发生在 core。 + +use unlucky_presenter::dto::{LaunchArgsPatch, LaunchArgsView}; + +/// 启动参数表单（五项 + 脏标记 + 绑定的实例 id）。 +#[derive(Debug)] +pub struct LaunchForm { + /// 这份草稿属于哪个实例（`None` = 还没播种）。 + pub bound: Option, + /// 实例级 JVM 参数（空白分隔的文本）。 + pub jvm: String, + /// 实例级游戏参数（空白分隔的文本）。 + pub game: String, + /// 最大堆（文本形态，空 = 跟随全局）。 + pub memory: String, + /// Java 可执行文件（空 = 跟随全局 / 自动挑）。 + pub java: String, + /// 图形后端（`default` / `opengl` / `vulkan`）。 + pub backend: String, + /// 用户改过、还没保存。 + pub dirty: bool, +} + +impl Default for LaunchForm { + fn default() -> Self { + Self::from_view(None, &LaunchArgsView::default()) + } +} + +impl LaunchForm { + /// 用一份快照播种（`bound` 为 `None` = 还没绑定实例）。 + #[must_use] + pub fn from_view(bound: Option<&str>, view: &LaunchArgsView) -> Self { + Self { + bound: bound.map(str::to_string), + jvm: view.jvm_args.clone(), + game: view.game_args.clone(), + memory: view.memory_mb.map(|mb| mb.to_string()).unwrap_or_default(), + java: view.java_path.clone(), + backend: view.graphics_backend.clone(), + dirty: false, + } + } + + /// 这份草稿是否正对着该实例。 + #[must_use] + pub fn bound_to(&self, id: &str) -> bool { + self.bound.as_deref() == Some(id) + } + + /// 重播种（见模块文档的三档）。 + /// + /// **脏草稿只在「落盘已确认」时被替换**：保存把命令派发出去之后，回程可能是一条错误事件 + /// （内存写了 `4g`、实例文件写不进去），那时 pump 会带着**旧快照**重建视图——如果这里无条件 + /// 覆盖，用户刚敲的东西就没了（M157 r3 复审 P2-2）。判据是「快照已经等于表单」： + /// 相等 ⇒ 这次保存落了盘，清脏并重播种；不相等 ⇒ 保留草稿等用户改。 + pub fn sync(&mut self, view: &LaunchArgsView) { + let same_instance = self.bound_to(&view.instance_id); + if same_instance && self.dirty { + if self.matches(view) { + self.dirty = false; + *self = Self::from_view(Some(&view.instance_id), view); + } + return; + } + *self = Self::from_view(Some(&view.instance_id), view); + } + + /// 表单当前内容是否与一份快照（= 盘上已持久化的值）完全一致。 + /// + /// **内存按数值比**：host 会把 `"04096"` / `"+4096"` 归一成 `4096` 落盘，回程快照给的是 + /// `Some(4096)`——按文本比会永远不等，于是表单一直脏、也不再跟随外部改动（r4 复审 P3-b）。 + /// 解析失败（用户正在敲半截）才退回文本口径。 + /// 其余字段直接比原文（JVM/游戏参数由 core 的 `tokenize` 消费，不做归一）。 + #[must_use] + pub fn matches(&self, view: &LaunchArgsView) -> bool { + self.jvm.trim() == view.jvm_args.trim() + && self.game.trim() == view.game_args.trim() + && self.memory_matches(view.memory_mb) + && self.java.trim() == view.java_path.trim() + && self.backend == view.graphics_backend + } + + /// 内存字段是否等于快照里的值（数值优先，解析失败退文本）。 + fn memory_matches(&self, persisted: Option) -> bool { + let typed = self.memory.trim(); + match (typed.parse::(), persisted) { + (Ok(typed), Some(persisted)) => typed == persisted, + // 空输入 = 跟随全局：快照那边也应当是「没有实例覆盖」。 + (Err(_), None) => typed.is_empty(), + _ => false, + } + } + + /// 提交补丁：**五项全给**（表单是整份可见的，不用增量语义会让「清空」无法表达）。 + #[must_use] + pub fn patch(&self) -> LaunchArgsPatch { + LaunchArgsPatch { + jvm_args: Some(self.jvm.clone()), + game_args: Some(self.game.clone()), + memory_mb: Some(self.memory.clone()), + java_path: Some(self.java.clone()), + graphics_backend: Some(self.backend.clone()), + } + } + + /// 「恢复跟随全局」：五项清空，脏标记置位（等用户点保存）。 + pub fn reset(&mut self) { + self.jvm.clear(); + self.game.clear(); + self.memory.clear(); + self.java.clear(); + self.backend = "default".to_string(); + self.dirty = true; + } +} + +/// 启动参数区的消息（`pages::Message::Instances` 的载荷）。 +/// +/// 只表达**页面意图**：编辑写进表单，保存/恢复才需要 app 层理解（前者 dispatch 一条 +/// `AppCommand::SetInstanceLaunchArgs`，后者只是清表单）。 +#[derive(Debug, Clone)] +pub enum Message { + /// 编辑 JVM 参数。 + Jvm(String), + /// 编辑游戏参数。 + Game(String), + /// 编辑最大内存（单行文本）。 + Memory(String), + /// 编辑 Java 路径（单行文本）。 + Java(String), + /// 选图形后端（三态 chips）。 + Backend(String), + /// 保存（派发命令）。 + Save, + /// 恢复跟随全局（清表单，仍需保存）。 + Reset, + /// 启停一个 mod（M224）：`file` 是**磁盘文件名**（含后缀），`enabled` 是期望状态。 + /// + /// 页面只发意图，落盘由 host 在后台线程做；回程是一份新快照（不做乐观回显）。 + SetModEnabled { + /// 磁盘文件名 + file: String, + /// 期望的启用状态 + enabled: bool, + }, + /// 重新列一次存档（M235）：读盘失败时的「重试」，也用于用户手动刷新。 + /// + /// 只发一条 `SavesCommand::List`——没有别的状态要复位（失败不清绑定，见 presenter 的 + /// `SavesState::failed`）。 + ReloadSaves, + /// 打开存档文件夹（M235）：拉起哪个目录由 host 决定（`saves/` → `screenshots/` → 运行目录）。 + OpenSavesFolder, + /// 开始**行内重命名**一个世界（M247）：那一行就地换成输入框 + 确定/取消。 + /// + /// 为什么是行内而不是模态输入框：现成的模态队列有 `DialogKind::Input`，但 app 侧的 + /// `dialog::Message` 只有「主按钮 / 次按钮 / 关闭」，**没有「输入变了」**这一条—— + /// 用输入模态等于重写一套可编辑模态。行内复用 `components::inputs` 的单行框，一处新控件都不用加。 + StartRenameWorld { + /// 磁盘目录名 + dir: String, + }, + /// 行内输入框的内容变了（原样存进 presenter 的草稿，不在前端过滤）。 + RenameWorldChanged(String), + /// 提交行内重命名（空名字 / 没改 → 直接收起，不打扰后台）。 + CommitRenameWorld, + /// 取消行内重命名。 + CancelRenameWorld, + /// 请求删除一个世界（M247）：**先弹确认框**，不直接删。 + RequestDeleteWorld { + /// 磁盘目录名 + dir: String, + }, + /// 备份一个世界（M247）：导出 zip 到启动器自己的 `exports/saves/`。 + BackupWorld { + /// 磁盘目录名 + dir: String, + }, +} + +#[cfg(test)] +mod tests { + use super::*; + + fn view(instance: &str, jvm: &str, memory: Option, backend: &str) -> LaunchArgsView { + LaunchArgsView { + instance_id: instance.to_string(), + jvm_args: jvm.to_string(), + game_args: String::new(), + memory_mb: memory, + memory_effective_mb: memory.unwrap_or(2048), + java_path: String::new(), + java_effective: String::new(), + graphics_backend: backend.to_string(), + graphics_backend_effective: backend.to_string(), + graphics_backend_allowed: true, + mc_version: "26.2".to_string(), + graphics_backend_min_version: "26.2-snapshot-2".to_string(), + graphics_backend_options: vec![ + "default".to_string(), + "opengl".to_string(), + "vulkan".to_string(), + ], + } + } + + /// 换实例必重播种；同实例的脏草稿不被事件冲掉。 + #[test] + fn sync_reseeds_per_instance_but_keeps_dirty_edits() { + let mut form = LaunchForm::default(); + form.sync(&view("a", "-Xss4m", Some(4096), "vulkan")); + assert_eq!(form.jvm, "-Xss4m"); + assert_eq!(form.memory, "4096"); + assert!(!form.dirty); + + // 用户改动 → 脏 → 同实例的快照刷新不许覆盖。 + form.memory = "8192".to_string(); + form.dirty = true; + form.sync(&view("a", "-Xss4m", Some(4096), "vulkan")); + assert_eq!(form.memory, "8192", "脏草稿被事件冲掉了"); + + // 换实例 → 重播种（草稿不串台）。 + form.sync(&view("b", "", None, "default")); + assert_eq!(form.memory, ""); + assert!(!form.dirty); + assert!(form.bound_to("b")); + } + + /// **保存失败不许吃掉草稿**（M157 r3 复审 P2-2）：脏表单 + 旧快照回来 ⇒ 原样保留。 + /// + /// 抓得住：`sync` 在「同实例 + 脏」时无条件重播种（用户敲的 `4g` 被磁盘上的 4096 覆盖）。 + /// 抓不住：真实事件时序（那在 `app/update/instances.rs` 的用例里按消息顺序模拟）。 + #[test] + fn failed_save_keeps_the_draft() { + let mut form = LaunchForm::from_view(Some("a"), &view("a", "", Some(4096), "default")); + // 用户把内存改成非法值（host 会拒），此时表单是脏的。 + form.memory = "4g".to_string(); + form.jvm = "-Xmx3g".to_string(); + form.dirty = true; + + // 回程事件带来的仍是**旧**快照（保存失败 ⇒ 盘上没变）。 + form.sync(&view("a", "", Some(4096), "default")); + + assert_eq!(form.memory, "4g", "失败后的重播把用户正在改的内存吃掉了"); + assert_eq!(form.jvm, "-Xmx3g"); + assert!(form.dirty, "草稿还在，脏标记也不能掉"); + } + + /// **保存成功要清脏**：回程快照等于表单 ⇒ 这一步算落盘确认，之后可以跟着外部变化重播种。 + #[test] + fn confirmed_save_clears_dirty_and_reseeds() { + let mut form = LaunchForm::from_view(Some("a"), &view("a", "", Some(4096), "default")); + form.memory = "8192".to_string(); + form.backend = "vulkan".to_string(); + form.dirty = true; + + form.sync(&view("a", "", Some(8192), "vulkan")); + assert!(!form.dirty, "盘上已经是这份值了，脏标记该清"); + assert_eq!(form.memory, "8192"); + + // 之后外部改了配置（比如 CLI 写入）⇒ 干净的表格跟着更新。 + form.sync(&view("a", "-Xss4m", Some(2048), "opengl")); + assert_eq!(form.memory, "2048"); + assert_eq!(form.jvm, "-Xss4m"); + } + + /// **内存按数值比**（r4 复审 P3-b）：`04096` / `+4096` 落盘后回程是 `4096`，必须判等。 + /// + /// 抓得住：`matches` 退回文本比较——那样这两类输入会永远「没保存成功」，表单一直脏、 + /// 之后外部改配置也不再重播种。 + #[test] + fn memory_is_compared_by_value_not_by_text() { + for typed in ["04096", "+4096", " 4096 "] { + let mut form = LaunchForm::from_view(Some("a"), &view("a", "", Some(4096), "default")); + form.memory = typed.to_string(); + form.dirty = true; + assert!( + form.matches(&view("a", "", Some(4096), "default")), + "`{typed}` 应判等" + ); + form.sync(&view("a", "", Some(4096), "default")); + assert!(!form.dirty, "`{typed}` 保存确认后要清脏"); + } + // 数值不等就是不等于；半截输入（解析失败）也不许判等。 + let mut form = LaunchForm::from_view(Some("a"), &view("a", "", Some(4096), "default")); + form.memory = "8".to_string(); + assert!(!form.matches(&view("a", "", Some(4096), "default"))); + form.memory = "4g".to_string(); + assert!(!form.matches(&view("a", "", Some(4096), "default"))); + // 清空 = 跟随全局：快照也得是「没有实例覆盖」。 + form.memory.clear(); + assert!(form.matches(&view("a", "", None, "default"))); + } + + /// 补丁五项全给：空串就是「清空」，不留 `None` 让 host 猜。 + #[test] + fn patch_always_covers_all_five_fields() { + let mut form = LaunchForm::from_view(Some("a"), &view("a", "", None, "default")); + form.memory = "6144".to_string(); + form.backend = "opengl".to_string(); + let patch = form.patch(); + assert_eq!(patch.jvm_args.as_deref(), Some("")); + assert_eq!(patch.memory_mb.as_deref(), Some("6144")); + assert_eq!(patch.graphics_backend.as_deref(), Some("opengl")); + + form.reset(); + assert!(form.dirty); + let patch = form.patch(); + assert_eq!(patch.jvm_args.as_deref(), Some("")); + assert_eq!(patch.memory_mb.as_deref(), Some("")); + assert_eq!(patch.graphics_backend.as_deref(), Some("default")); + } +} 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..7a09588 --- /dev/null +++ b/crates/app-iced/src/pages/instances/tests.rs @@ -0,0 +1,284 @@ +//! `instances` 的断言：演示数据、窄窗退化，以及**页面摆法**（源码结构断言）。 +use super::*; + +/// M120 的文案守门（中文无英文词 / 切语言真的变 / 页面里不许写死英文案·白名单）。 +mod i18n; + +/// M157 的门限判据（三态 chips 在版本不够时谁可点）。 +mod launch_args; + +/// M235 的存档区模型判据（快照 → 行 / 计数 / 失败线 / UTC 时间）。 +mod saves; + +/// M252 / P18 的**回车**接线（行内重命名：回车 = 点「改名」）。 +mod rename; + +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!( + source::code_text(&body).contains("ROW_SPACING"), + "列表行距必须从 ROW_SPACING 取（注释里写不算），不许另写：\n{body}" + ); + assert!( + source::code_text(&body).contains("LIST_BOTTOM_INSET"), + "底部内缩必须从 LIST_BOTTOM_INSET 取（注释里写不算）：\n{body}" + ); + + // ① 行容器的构建链上不许叠间距（`column![head, scroller]` 上的合法间距不在这条链里）。 + // 判据走「代码行」（`source::code_text` 剥注释）：注释掉的 `.spacing(..)` 等于没有间距。 + assert!( + !source::code_text(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） + // + // 判据走**代码文本**（`source::code_text` 剥注释）：注释掉的 `rows.spacing(..)` 不算「应用了间距」， + // 否则把那一行注释掉整条用例会绿着通过（T29 的同族退化）。 + let body = source::code_text(&body); + 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!( + source::code_text(body).contains("frame::prose("), + "正文段没有走 frame::prose（注释里写不算）：\n{body}" + ); + assert!( + !source::code_text(body).contains("frame::body("), + "正文段被塞进了整页块（会失去 72 字符行宽承诺）：\n{body}" + ); +} + +/// 元信息卡必须装得下**卡内最长的那条值**（视觉 r2：136 漏算 padding；M229 复审 P1-2 换成 +/// ELEVATED CARD 之后内距 24 + 值 16px 又让它折行，同排卡底不齐）。 +/// +/// ## 判据是「墨水宽 ≤ 内宽」，数值是**量出来的**（不是算出来的） +/// +/// 最长的那条值是 LAST PLAYED 的时戳 `2026-10-29 19:22 UTC`（20 字符，比加载器版本串长）。 +/// 量法：`page-instances-detail-dark.png`（1180×760，2 列布局）右卡的值行 y 440–448， +/// 墨水横向 706…823 = **118px**，而卡内宽 = 外框 − 2×内距。两个档位都量过： +/// +/// | 值字级 | 时戳墨水宽 | 160 外框（内宽 120）下 | +/// |---|---|---| +/// | `BodyMedium` 14 | **138px** | 放不下（折行 ⇒ 卡底不齐） | +/// | `BodySmall` **12** | **118px** | 放得下（余 2px；实际 2 列宽 206 余 62px） | +/// +/// 所以 `elevated::TITLE_ROLE` 是 `BodySmall`、`elevated::PAD` 是 20 —— 这两件事**必须一起改**， +/// 本测试把它们与卡片外框绑在同一条不等式上；任何一项回退（值改回 14、内距改回 24）都会红。 +#[test] +fn meta_card_value_fits_on_one_line_at_the_narrowest_card() { + use super::super::layout::{measure_cap_px, META_CARD_MIN_WIDTH, META_GAP}; + use crate::app::components::surfaces::elevated; + + /// 时戳在 `BodySmall`(12px) 下的墨水宽（量法见函数文档）。 + const TIMESTAMP_PX_AT_12: f32 = 118.0; + /// 同一个串在 `BodyMedium`(14px) 下的墨水宽——留在这里是为了让「改回 14」的人一眼看到代价。 + const TIMESTAMP_PX_AT_14: f32 = 138.0; + + // 量测对象是**产品那条格式化函数的输出**（`app::view::instances::last_played`： + // `{date} {time} UTC`），它的格式与两个边界样例由 `app/view/tests.rs::…last_played…` 钉着， + // 所以这里只钉「这条串有多少字」——20 字符，是全站最长的元信息值。 + const LONGEST_VALUE: &str = "2026-10-29 19:22 UTC"; + assert_eq!( + LONGEST_VALUE.chars().count(), + 20, + "最长元信息值的字符数变了就要重新量墨水宽" + ); + + // ① 字级与内距是**一对**：先钉住两个常量，再钉不等式（否则改字级不会红）。 + let role = elevated::TITLE_ROLE; + assert_eq!(role, unlucky_design::typography::TypeRole::BodySmall); + assert_eq!( + role.style().size_px, + 12.0, + "值字级必须是 12px（14px 下时戳 138px 放不下）" + ); + assert_eq!( + elevated::PAD, + 20.0, + "卡内距是 20（规格卡的 24 会挤到 166 > 160）" + ); + assert_eq!( + elevated::PAD, + unlucky_design::spacing::LayoutMetrics::DESKTOP.card_padding, + "内距与描边卡同源（20）" + ); + // 绑定成局部变量再过断言：全是常量的话 clippy 会判「常量断言」（评审集里的既有写法）。 + let measured_14 = TIMESTAMP_PX_AT_14; + let inner_min_width = META_CARD_MIN_WIDTH - 2.0 * elevated::PAD; + assert!( + measured_14 > inner_min_width, + "如果 14px 也能放下（{measured_14} ≤ {inner_min_width}），这条登记就该删掉" + ); + + // ② 最窄的外框（160）减掉两侧内距，必须放得下 12px 的时戳。 + let inner_min = META_CARD_MIN_WIDTH - 2.0 * elevated::PAD; + assert!( + inner_min >= TIMESTAMP_PX_AT_12, + "最窄卡内宽 {inner_min}px 装不下 {TIMESTAMP_PX_AT_12}px 的时戳（外框 {META_CARD_MIN_WIDTH} − 2×{}）", + elevated::PAD + ); + + // ③ 实际版面（2 列，行宽上限 424）也要放得下——这是出图那一档。 + let two_columns = (measure_cap_px() - META_GAP) / 2.0; + assert!( + two_columns - 2.0 * elevated::PAD >= TIMESTAMP_PX_AT_12, + "两列布局下卡内可用 {}px 装不下 {TIMESTAMP_PX_AT_12}px", + two_columns - 2.0 * elevated::PAD + ); + // 卡片宽度契约没动（复审要求「不破卡片宽度契约」）。 + assert_eq!(META_CARD_MIN_WIDTH, 160.0); +} + +#[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..106aec0 --- /dev/null +++ b/crates/app-iced/src/pages/instances/tests/i18n.rs @@ -0,0 +1,382 @@ +//! 实例页的**文案守门**（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 crate::pages::layout::source; + +use super::super::Texts; + +/// 中文界面里允许出现的 ASCII 词：**品牌名与技术标识**。 +/// +/// 每一条都要说清为什么： +/// +/// - `Java`：运行时品牌名（`JAVA` 那格的值域里也全是 `Temurin 21` 这类品牌串），翻成「爪哇」是错的； +/// - `pid`：进程号的技术标识。用户拿它去任务管理器里搜进程，翻成「进程」就丢了这条可操作性。 +const ALLOWED: &[&str] = &[ + "Java", + "pid", + "JVM", + "OpenGL", + "Vulkan", + "MiB", + // M224：`mods` 是**目录名**（文件系统事实）。中文界面上写成「模组目录」会让用户找不到那个 + // 文件夹——`mods/` 就是他要打开的那个东西，所以两套语言都原样写它。 + "mods", + // M235：`saves` / `screenshots` 同样是**目录名**（文件系统事实，玩家要照着去找）。 + // 「正在读取 saves/…」「还没有 saves/ 或 screenshots/ 目录」里的这两个词不许翻—— + // 翻成「存档目录」用户就对不上那两层文件夹了。 + "saves", + "screenshots", + // M247：`zip` 是**归档格式名**（备份导出成什么，玩家拿去给别的东西解压时看的也是这个词）。 + // 中文界面上写「压缩包」会让「备份出来的是 .zip 吗」这个问题没有答案。 + "zip", +]; + +/// 页面取词的六个源码文件（死 key 扫描与旧串扫描共用）。 +const PAGE_SOURCES: [(&str, &str); 12] = [ + ("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")), + // M251：存档 / 截图一族从 text.rs 拆出（那边越过 400 行）——新文件必须一起扫， + // 否则那四句缩略图文案会被当成「死 key」。 + ("instances/text/saves.rs", include_str!("../text/saves.rs")), + ( + "instances/launch_args.rs", + include_str!("../launch_args.rs"), + ), + ( + "app/view/instances.rs", + include_str!("../../../app/view/instances.rs"), + ), + // M224：MODS 区（本地 mod 列表 + 启停开关） + ("instances/mods.rs", include_str!("../mods.rs")), + // M235：SAVES 区（存档 / 截图的只读列表 + 打开文件夹） + ("instances/saves.rs", include_str!("../saves.rs")), + // M247：SAVES 区的行与操作区（重命名 / 备份 / 删除 + 行内输入框） + ("instances/saves/rows.rs", include_str!("../saves/rows.rs")), + // M251：SAVES 区的视图模型（快照 → 行/格子；缩略图句柄在这里建） + ( + "instances/saves/model.rs", + include_str!("../saves/model.rs"), + ), + // M251：截图缩略图墙 + ("instances/saves/wall.rs", include_str!("../saves/wall.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; 35] = [ + "{date} {time} UTC", + "isolated", + "shared", + "pid", + // M161：失败行由 `LaunchStageFailed` / `InstancesFailed` / `InstancesCrashed` 渲染， + // 占位符名是 `{stage}` / `{detail}` / `{reason}` / `{code}`（占位符名不是文案）； + // `{outcome}` / `{seconds}` 是收尾 Toast 的。 + "stage", + "detail", + "reason", + "code", + "outcome", + "seconds", + "Instances", + // M157：图形后端三态的**稳定 id**（与 core 的 `GraphicsBackend::IDS` 同一份词表）， + // `backend_label` 只认这三档，其余原样上屏。 + "default", + "opengl", + "vulkan", + // M157：`Catalog::render` 的占位符名（`{version}` / `{value}` / `{default}`），不是文案。 + "version", + "value", + // M157 r4：门槛文案的占位符名（版本号由 DTO 给，目录里不写死）。 + "min", + // M157：`instances/demo.rs` 的**出图夹具**（用户数据的形状，不是界面文案）： + // 一个示例 JVM 参数、两个示例 MC 版本、一个示例 Java 路径，以及夹具开关的环境变量名与取值。 + "-XX:+UseG1GC", + // M157 r2：示例游戏参数（同上，是夹具不是文案）。 + "--fullscreen", + "26.2-snapshot-2", + "1.20.4", + "C:/Java/temurin-21/bin/java.exe", + "ULL_LAUNCH_ARGS_FIXTURE", + // M161：示例「被门槛挡下」的取值（夹具）。 + "gated", + // M224：MODS 区四个 key 的**占位符名**（`{enabled}` / `{disabled}` / `{count}` / `{file}`）， + // 不是文案——`Catalog::render` 按名字取值，换成别的词就渲染不出来了。 + "enabled", + "disabled", + "count", + "file", + // M235：存档区计数那条的**占位符名**（`{worlds}` / `{shots}`），同样不是文案。 + "worlds", + "shots", + // M247：删除确认与写操作回执的**占位符名**（`{dir}` 世界名 / `{from}` `{to}` 改名两端 / + // `{path}` 备份落点 / `{size}` 人的可读字节数），都不是文案。 + "dir", + "from", + "to", + "path", + "size", +]; + +/// 抽出源码里的字符串字面量（够用的实现：本仓这五个文件没有 `\"` 转义、没有多行字符串）。 +/// +/// 按 `"` 切开取**奇数段**即可：`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 { + 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}"); + } + + // 失败那一行同理（M161：`InstancesFailed` 已被 `LaunchStageFailed` 取代——「哪一步」也要翻， + // 只有 `detail` 那段原文原样保留） + let args = [("stage", "Starting the game process"), ("detail", "exit 1")]; + let failed_en = Catalog::of(Lang::En).render(Key::LaunchStageFailed, &args); + let failed_zh = Catalog::of(Lang::ZhCn).render( + Key::LaunchStageFailed, + &[("stage", "启动游戏进程"), ("detail", "exit 1")], + ); + assert_eq!( + failed_en, + "Launch failed · Starting the game process: exit 1" + ); + assert_eq!(failed_zh, "启动失败 · 启动游戏进程：exit 1"); + for text in [&failed_en, &failed_zh] { + assert!(text.contains("exit 1"), "原文丢了：{text}"); + } + assert_ne!(failed_en, failed_zh, "切换语言时前半句要变"); +} + +/// **页面里不许再写死界面文案**（白名单）：带 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 / 目录。 + // + // M251：原来按下标取（`PAGE_SOURCES[5]`），插进一条新文件就整体错位——改成**按文件名取**， + // 以后再拆文件不必回来改下标（拆错文件时仍然会红：找不到那个名字就 panic）。 + let source = |name: &str| -> &'static str { + PAGE_SOURCES + .iter() + .find(|(file, _)| *file == name) + .map(|(_, source)| *source) + .unwrap_or_else(|| panic!("PAGE_SOURCES 里没有 {name}：拆文件之后忘了登记？")) + }; + assert!( + source::code_text(source("instances.rs")).contains("Texts::of("), + "实例页没有从 Texts 取词（注释里写不算）" + ); + assert!( + source::code_text(source("instances.rs")).contains("Header::new(texts.title())"), + "页头标题必须是词表里的那条（`Header::new` 里写死字符串 = 中文界面上顶着英文标题）" + ); + assert!( + source::code_text(source("instances/text.rs")).contains("Key::Instances"), + "text.rs 没有引用本族的 key（注释里写不算）" + ); + assert!( + source::code_text(source("app/view/instances.rs")).contains("Key::InstancesStage"), + "阶段标签没有走目录（注释里写不算）" + ); + assert!( + source::code_text(source("instances/launch_args.rs")).contains("texts.launch_title()"), + "启动参数区没有走目录（注释里写不算）" + ); +} + +/// **死 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/tests/launch_args.rs b/crates/app-iced/src/pages/instances/tests/launch_args.rs new file mode 100644 index 0000000..fe85333 --- /dev/null +++ b/crates/app-iced/src/pages/instances/tests/launch_args.rs @@ -0,0 +1,55 @@ +//! 「启动参数」区（M157）的**门限**判据：三态 chips 在版本不够时谁可点。 +//! +//! 为什么只测一个纯函数：iced 0.14 的 `Element` 没有内省接口，画出来的「禁用态」在测试里 +//! 拿不到（`Chip::disabled` 只是把 `on_press` 清成 `None`）。所以把判据抽成 +//! [`backend_chip_enabled`] 并在这里钉住——页面那一行必须调它（否则这条绿着也没意义， +//! 守门形状与 `instances/tests.rs` 的源码断言同一取舍）。 + +use super::super::launch_args::backend_chip_enabled; +use crate::pages::LaunchFacts; + +/// 门限满足：三档全可点。 +#[test] +fn every_backend_chip_is_clickable_when_the_gate_is_open() { + for id in ["default", "opengl", "vulkan"] { + assert!(backend_chip_enabled(true, id), "门限满足时 {id} 必须可点"); + } +} + +/// 门限不满足：只有 `default` 可点（它是「不下发」的安全档）。 +/// +/// 抓得住：把 `default` 一起灰掉（M157 复审 P3 的原状）——那时旧版本实例上写了 +/// `graphicsBackend: vulkan` 的用户在 UI 里回不到 `default`，只能「恢复跟随全局」 +/// （连带清空 JVM / 游戏参数 / 内存 / Java 四项）。 +#[test] +fn the_default_chip_stays_clickable_when_the_gate_is_closed() { + assert!( + backend_chip_enabled(false, "default"), + "门限不满足时 default 也必须可点：它是唯一永远合法的档" + ); + for id in ["opengl", "vulkan"] { + assert!( + !backend_chip_enabled(false, id), + "门限不满足时 {id} 必须灰掉（下发会被 core 拒绝）" + ); + } +} + +/// 词表与判据不许脱节：`default` 必须真在这份快照的 options 里，否则「安全档」无从点起。 +#[test] +fn the_gate_rule_covers_the_demo_option_table() { + let facts = LaunchFacts { + options: ["default", "opengl", "vulkan"] + .iter() + .map(|id| (*id).to_string()) + .collect(), + ..LaunchFacts::default() + }; + assert!( + facts + .options + .iter() + .any(|id| backend_chip_enabled(false, id)), + "门限关闭时至少有一档可点（否则三态整体锁死）" + ); +} diff --git a/crates/app-iced/src/pages/instances/tests/rename.rs b/crates/app-iced/src/pages/instances/tests/rename.rs new file mode 100644 index 0000000..4cb32b4 --- /dev/null +++ b/crates/app-iced/src/pages/instances/tests/rename.rs @@ -0,0 +1,84 @@ +//! M252 / P18：行内重命名的**回车**接线。 +//! +//! iced 的 `Element` 没有内省接口（见 `pages::layout::source` 的模块文档），所以「真按下回车会 +//! 发生什么」在单测里量不到。这里能钉住的两件事： +//! +//! | 断言 | 抓得住 | 抓不住 | +//! |---|---|---| +//! | [`enter_takes_the_same_message_as_the_rename_button`] | 「回车」与「点改名」共用的那条消息被换成别的（取消 / 重开…）；空名 / 原名不变 / 非法字符那几道校验因此**自动**对回车成立——它们挂在同一个 Message 后面 | 校验本身对不对（在 `app/update/instances.rs` 与 presenter，本 mission 一字未改） | +//! | [`the_rename_field_wires_enter`] | `rename_row` 里那枚输入框的 `.on_submit(..)` 被删掉 / 接成别的（T27 反例） | 回车键真的到达控件（那是 iced 的 `Widget::update`） | +//! +//! 也就是说：判据①「回车真的提交一次」里，**「提交的是什么」被钉住了，「按下去会不会到这儿」没有** +//! （理由与替代验证写在 M252 报告的「没验的部分」一节）。 + +use crate::pages::layout::source; + +use super::super::saves::commit_rename; +use super::super::state::Message as PageMessage; + +/// 回车与「改名」按钮共用同一个消息产地 ⇒ 走同一套校验。 +/// +/// `PageMessage` 只有 `Debug + Clone`（没有 `PartialEq`，那些枚举不在本 mission 的 scope）， +/// 所以这里比 `Debug` 文本：枚举的 `Debug` 打印变体名与字段，变体不同必然文本不同。 +/// +/// 这条只钉「产地生产什么」；**「两条路都用了这个产地」由 [`the_rename_field_wires_enter`] 钉** +/// （r1 复审 P2-1：上一版把两件事写进这里，而实际覆盖只在文本型断言里）。 +#[test] +fn enter_takes_the_same_message_as_the_rename_button() { + assert_eq!( + format!("{:?}", commit_rename()), + format!("{:?}", PageMessage::CommitRenameWorld), + "回车必须发「提交重命名」，不能是取消/重开/逐键输入" + ); + assert!( + !format!("{:?}", commit_rename()).contains("Cancel"), + "回车不许接到取消上（那会让用户按回车丢掉草稿）" + ); +} + +/// 回车与「改名」按钮**在源码里**都接 `commit_rename()`，且都没接第二种页面意图。 +/// +/// 判据是**代码行**（`source::code_line` 先剥注释），所以下面这些改法都会红： +/// - 把 `.on_submit(..)` 那一行删掉，或注释掉（`//` / `/*` 独占一行的块注释）； +/// - 把它接成别的页面意图（取消 / 重开 / 逐键输入）——按钮那一行同样不许； +/// - 让两条路走**不同**的产地（例如按钮仍写 `PageMessage::CommitRenameWorld` 字面量）： +/// 那时按钮那行不含 `commit_rename()`，第二条断言红。 +/// +/// 抓不住：回车键真的到达控件（那是 iced 的 `Widget::update`，见模块文档）；同一行里写完的 +/// 等价接线（本仓构建链一律一行一条）。 +#[test] +fn the_rename_field_wires_enter() { + let body = source::function_body(include_str!("../saves/rows.rs"), "fn rename_row"); + let enter = source::code_line(body, ".on_submit(").unwrap_or_else(|| { + panic!("`rename_row` 里没有一行**代码**接 `on_submit`（注释掉也算没有）：\n{body}") + }); + assert!( + enter.contains("commit_rename()"), + "回车必须接 `commit_rename()`（与「改名」按钮同一个产地）：{enter}" + ); + + let button = source::code_lines(body) + .into_iter() + .find(|line| line.contains("saves_rename_confirm()")) + .unwrap_or_else(|| panic!("找不到「改名」按钮那一行：\n{body}")); + assert!( + button.contains("commit_rename()"), + "「改名」按钮必须用同一个产地（RenameWorld 只有一处写法）：{button}" + ); + + // P2-1：两条路都只许这一个页面意图——接成别的（取消/重开/逐键输入）就是行为变了。 + for line in [&enter, &button] { + for other in [ + "CancelRenameWorld", + "StartRenameWorld", + "RenameWorldChanged", + "BackupWorld", + "RequestDeleteWorld", + ] { + assert!( + !line.contains(other), + "回车/按钮接成了别的页面意图（{other}）：{line}" + ); + } + } +} diff --git a/crates/app-iced/src/pages/instances/tests/saves.rs b/crates/app-iced/src/pages/instances/tests/saves.rs new file mode 100644 index 0000000..15227fa --- /dev/null +++ b/crates/app-iced/src/pages/instances/tests/saves.rs @@ -0,0 +1,257 @@ +//! 「存档区」（M235）的**模型**判据：快照 → 页面要画的东西。 +//! +//! 为什么只测一个纯函数：iced 0.14 的 `Element` 没有内省接口（与 `tests/launch_args.rs` +//! 同一取舍），画出来的行在测试里拿不到。所以把"快照 → 行/计数/失败线"全部压在 +//! [`saves::from_state`] 里，在这里逐条钉住——页面那一支只负责把这些字段画出来。 +//! +//! 守门形状：`detail.rs` 必须调 `saves::section(ui, saves, …)`（`instances/tests.rs` 的源码 +//! 结构断言盯着 `detail_column` 里 MODS 与 SAVES 的先后；这里守模型）。 + +use unlucky_presenter::dto::{ + SavesArea, SavesFailureKind, SavesFailureView, SavesListView, SavesSkipKind, SavesSkipView, + ScreenshotPreview, ScreenshotView, ThumbnailView, WorldView, +}; +use unlucky_presenter::state::SavesState; + +use super::super::saves::{failure_line, from_state}; +use super::super::Texts; +use unlucky_i18n::Lang; + +/// 2024-05-01 10:00 UTC（UTC 毫秒）。 +const STAMP: u64 = 1_714_557_600_000; + +fn view(instance: &str) -> SavesListView { + SavesListView { + instance: instance.to_string(), + dir: "C:/mc/saves".to_string(), + exists: true, + worlds: vec![WorldView { + dir: "Better World".to_string(), + icon: true, + modified_ms: Some(STAMP), + }], + screenshots_dir: "C:/mc/screenshots".to_string(), + screenshots_exists: true, + screenshots: vec![ScreenshotView { + file: "2024-05-01_10.00.00.png".to_string(), + bytes: 2_048, + modified_ms: None, + // M251：一像素的缩略图——这条用例只关心「格子/计数/副文案」的映射，不关心解码。 + preview: ScreenshotPreview::Ready(ThumbnailView { + width: 1, + height: 1, + pixels: vec![0x2E, 0x7D, 0x4F, 0xFF], + }), + }], + skipped: vec![SavesSkipView { + area: SavesArea::Screenshots, + file: "notes.txt".to_string(), + reason: SavesSkipKind::NotAnImage, + }], + last_op: None, + } +} + +/// 已绑定实例的视图态（`bind` 是 presenter 内部的 `pub(super)`，这里直接写字段—— +/// 它本来就是公开状态的一部分，与 `AppState::bind_saves` 走的是同一条路）。 +fn bound_state(instance: &str) -> SavesState { + SavesState { + bound: Some(instance.to_string()), + ..SavesState::default() + } +} + +/// 快照 → 行：世界带「有图标」，截图带大小；时间**按 UTC 切**，取不到就说"时间未知"。 +#[test] +fn the_snapshot_becomes_rows_with_stamps_and_badges() { + let mut state = bound_state("a"); + state.changed(view("a")); + let saves = from_state(&state, Lang::ZhCn.catalog()); + + assert!(!saves.loading); + assert!(!saves.retryable, "成功的快照不该带重试"); + assert_eq!(saves.worlds.len(), 1); + assert_eq!(saves.worlds[0].name, "Better World"); + let zh_icon = Texts::of(Lang::ZhCn.catalog()).saves_world_icon(); + assert!( + saves.worlds[0].detail.contains("2024-05-01 10:00 UTC"), + "世界的副文案要带 UTC 时间：{:?}", + saves.worlds[0].detail + ); + assert!( + saves.worlds[0].detail.contains(zh_icon), + "有 icon.png 的世界要带标记：{:?}", + saves.worlds[0].detail + ); + + assert_eq!(saves.screenshots.len(), 1); + assert_eq!( + saves.thumbnails(), + 1, + "带了像素的截图必须变成一格真图（不是占位）" + ); + assert!( + saves.screenshots[0].detail.contains("2.0 KB"), + "截图的副文案要带大小：{:?}", + saves.screenshots[0].detail + ); + assert!( + saves.screenshots[0] + .detail + .contains(Texts::of(Lang::ZhCn.catalog()).saves_time_unknown()), + "mtime 缺失时要说『时间未知』，不许拿 0 或当前时间糊：{:?}", + saves.screenshots[0].detail + ); + + // 计数与跳过：3 个世界 / 12 张截图这种句子在这一层拼好。 + assert_eq!(saves.count, "1 个世界 · 1 张截图"); + assert_eq!(saves.skipped, 1); + assert_eq!(saves.skipped_note, "跳过 1 项"); +} + +/// 首帧（已绑定、还没有快照）是 `loading`；没有绑定则什么都不算"已加载"。 +#[test] +fn a_bound_instance_without_a_snapshot_is_loading() { + let state = bound_state("a"); + let saves = from_state(&state, Lang::En.catalog()); + assert!(saves.loading); + assert!(!saves.loaded()); + + let idle = from_state(&SavesState::default(), Lang::En.catalog()); + assert!(!idle.loading, "不在详情页不该画『正在读取』"); + assert!(!idle.loaded()); +} + +/// 两个目录都不存在 ⇒ `missing`（画"还没有目录"那句，而不是"这里空空的"）。 +/// 目录在但里面什么都没有 ⇒ `nothing_yet`。 +#[test] +fn missing_directories_and_empty_ones_are_different_states() { + let mut state = bound_state("a"); + let mut gone = view("a"); + gone.exists = false; + gone.screenshots_exists = false; + gone.worlds.clear(); + gone.screenshots.clear(); + gone.skipped.clear(); + state.changed(gone); + let saves = from_state(&state, Lang::En.catalog()); + assert!(saves.missing); + assert!(!saves.nothing_yet(), "缺目录不该被当成『目录在但是空的』"); + + let mut state = bound_state("a"); + let mut empty = view("a"); + empty.worlds.clear(); + empty.screenshots.clear(); + empty.skipped.clear(); + state.changed(empty); + let saves = from_state(&state, Lang::En.catalog()); + assert!(!saves.missing); + assert!(saves.nothing_yet()); +} + +/// 失败：读盘失败**可重试**，打开文件夹失败**不可重试**（重试按钮会去重新列目录，那是错的动作）。 +/// +/// 抓得住：把两种失败合成一条「重试」；也抓得住"失败顺手把列表清掉"（用户看不见上一次读到的东西）。 +#[test] +fn only_list_failures_offer_a_retry() { + for (kind, retryable) in [ + (SavesFailureKind::DirUnusable, true), + (SavesFailureKind::InstanceUnavailable, true), + (SavesFailureKind::OpenFailed, false), + ] { + let mut state = bound_state("a"); + state.changed(view("a")); + state.failed(SavesFailureView { + instance: "a".to_string(), + file: String::new(), + op: None, + kind, + detail: "Access is denied.".to_string(), + }); + let saves = from_state(&state, Lang::En.catalog()); + assert!(!saves.loading); + assert_eq!(saves.retryable, retryable, "{kind:?} 的重试口径错了"); + assert!(saves.error.is_some(), "{kind:?} 没有画出失败"); + assert_eq!(saves.worlds.len(), 1, "{kind:?} 把旧列表清掉了"); + assert_eq!(saves.screenshots.len(), 1); + } +} + +/// **只拿到失败、一份快照都没有**时，不许被画成"这里还没有世界"。 +/// +/// 抓得住：`nothing_yet()` 只看"两个列表都空"——那样"读不了"会顶着两句"这里空空的"， +/// 用户会把权限问题读成"我没有存档"。 +#[test] +fn a_failure_without_a_snapshot_is_not_an_empty_list() { + let mut state = bound_state("a"); + state.failed(SavesFailureView { + instance: "a".to_string(), + file: String::new(), + op: None, + kind: SavesFailureKind::DirUnusable, + detail: "Access is denied.".to_string(), + }); + let saves = from_state(&state, Lang::En.catalog()); + assert!(saves.error.is_some()); + assert!(!saves.has_view, "没有快照却记成了有"); + assert!(!saves.nothing_yet(), "纯失败态被画成了空列表"); + assert_eq!(saves.count, "", "没有快照不该画计数"); +} + +/// 失败主句跟着语言与大类走，OS 原文只进括号（M161 的文案纪律）。 +#[test] +fn the_failure_line_follows_the_language_and_keeps_the_detail_in_brackets() { + let failure = SavesFailureView { + instance: "a".to_string(), + file: String::new(), + op: None, + kind: SavesFailureKind::DirUnusable, + detail: "Access is denied.".to_string(), + }; + let zh = failure_line(&failure, Texts::of(Lang::ZhCn.catalog())); + assert!(zh.starts_with("读取 saves/ 失败："), "{zh}"); + assert!(zh.ends_with("（Access is denied.）"), "{zh}"); + + let en = failure_line(&failure, Texts::of(Lang::En.catalog())); + assert!(en.starts_with("Could not read saves/:"), "{en}"); + assert!(en.contains("Access is denied."), "{en}"); + + // 没有原文时不留一对空括号。 + let bare = SavesFailureView { + detail: String::new(), + ..failure + }; + let text = failure_line(&bare, Texts::of(Lang::ZhCn.catalog())); + assert!(!text.contains('（'), "空原文留下了一对括号：{text}"); +} + +/// 时间换算：毫秒 → `YYYY-MM-DD HH:MM UTC`（跨年/闰日各钉一条，别只信一条）。 +#[test] +fn millisecond_stamps_are_rendered_in_utc() { + let stamp = |ms: u64| { + let mut state = bound_state("a"); + let mut view = view("a"); + view.worlds[0].modified_ms = Some(ms); + state.changed(view); + from_state(&state, Lang::En.catalog()).worlds[0] + .detail + .clone() + }; + // 1970-01-01 00:00 UTC（纪元） + assert!(stamp(0).starts_with("1970-01-01 00:00 UTC"), "{}", stamp(0)); + // 2024-05-01 10:00 UTC + assert!( + stamp(STAMP).starts_with("2024-05-01 10:00 UTC"), + "{}", + stamp(STAMP) + ); + // 2024-02-29 23:59 UTC（闰日） + assert!( + stamp(1_709_251_140_000).starts_with("2024-02-29 23:59 UTC"), + "{}", + stamp(1_709_251_140_000) + ); +} + +mod preview; +mod write; diff --git a/crates/app-iced/src/pages/instances/tests/saves/preview.rs b/crates/app-iced/src/pages/instances/tests/saves/preview.rs new file mode 100644 index 0000000..13d30bc --- /dev/null +++ b/crates/app-iced/src/pages/instances/tests/saves/preview.rs @@ -0,0 +1,172 @@ +//! 缩略图墙的**页面模型判据**（M251）——从 `tests/saves.rs` 拆出（那边加完句柄复用的两条之后越过 +//! 400 行硬线，与 `write.rs` 同一拆法）。 +//! +//! 这一族只钉「快照里的三种预览状态 → 页面模型」与「句柄复用」，**不**画像素： +//! `Element` 没有内省接口，画出来对不对只能看 `DevDocs/artifacts/m251/` 的图（README 里写明哪张 +//! 是排版、哪张是端到端真解码）。 + +use super::super::super::saves::clear_handles; +use super::super::super::saves::{from_state, Saves, ShotPreview}; +use super::super::super::Texts; +use super::{bound_state, view, STAMP}; +use unlucky_i18n::Lang; +use unlucky_presenter::dto::{ + ScreenshotPreview, ScreenshotThumbFailure, ScreenshotThumbKind, ScreenshotView, ThumbnailView, +}; + +/// 句柄 id 的取样口（只有 `Ready` 有句柄；别的一律 panic，免得断言在错误的状态上通过）。 +fn handle_id(saves: &Saves) -> iced::widget::image::Handle { + match &saves.screenshots[0].preview { + ShotPreview::Ready { handle } => handle.clone(), + other => panic!("第一格应当是缩略图，实际 {other:?}"), + } +} + +/// **缩略图墙的三种格子**（M251 · D54 第 6 条）：有像素 / 没轮到 / 具名失败，副文案各说各的。 +/// +/// 抓得住：①有像素却不画（`Ready` 被吞成占位）；②「没生成」与「失败」被合并成同一句 +/// （用户没法分辨"刷新一下可能就有了"与"得自己去修文件"）；③失败原因没上屏（原文丢掉）。 +/// 抓不住：像素画得对不对（`Element` 没有内省接口，只能靠 `DevDocs/artifacts/m251/` 的图）。 +#[test] +pub(super) fn every_preview_state_gets_its_own_caption() { + let texts = Texts::of(Lang::ZhCn.catalog()); + let mut snapshot = view("a"); + snapshot.screenshots = vec![ + ScreenshotView { + file: "ok.png".to_string(), + bytes: 2_048, + modified_ms: Some(STAMP), + preview: ScreenshotPreview::Ready(ThumbnailView { + width: 2, + height: 1, + pixels: vec![1, 2, 3, 4, 5, 6, 7, 8], + }), + }, + ScreenshotView { + file: "pending.png".to_string(), + bytes: 4_096, + modified_ms: Some(STAMP - 1), + preview: ScreenshotPreview::NotGenerated, + }, + ScreenshotView { + file: "huge.png".to_string(), + bytes: 9_437_184, + modified_ms: Some(STAMP - 2), + preview: ScreenshotPreview::Failed(ScreenshotThumbFailure { + kind: ScreenshotThumbKind::TooLarge, + detail: "9437184 > 8388608 字节".to_string(), + }), + }, + ]; + let mut state = bound_state("a"); + state.changed(snapshot); + let saves = from_state(&state, Lang::ZhCn.catalog()); + + assert_eq!(saves.thumbnails(), 1, "只有第一格有像素"); + assert!(matches!( + saves.screenshots[0].preview, + ShotPreview::Ready { .. } + )); + assert_eq!( + saves.screenshots[1].preview, + ShotPreview::Missing { + note: texts.saves_preview_none().to_string() + } + ); + assert_eq!( + saves.screenshots[2].preview, + ShotPreview::Missing { + note: texts + .saves_preview_reason(ScreenshotThumbKind::TooLarge) + .to_string() + } + ); + // 副文案三格一样是「大小 · 时间」：原因在框里，不把墙变得比图还吵（原文留在 DTO 里）。 + assert!( + saves.screenshots[1].detail.starts_with("4.0 KB"), + "没生成的那格也要有大小与时间：{:?}", + saves.screenshots[1].detail + ); + assert!( + saves.screenshots[2].detail.starts_with("9.0 MB"), + "失败的那格同样保留元数据：{:?}", + saves.screenshots[2].detail + ); +} + +/// 像素长度与宽高对不上时**不许**建句柄（`Handle::from_rgba` 不校验长度 ⇒ 画出来是花屏）。 +/// +/// 抓得住：把 `is_consistent()` 那道判断删掉（这时会走 `Ready`，`thumbnails()` 变 1 而断言要 0）。 +#[test] +pub(super) fn inconsistent_pixels_are_shown_as_a_failure_not_a_broken_image() { + let mut snapshot = view("a"); + snapshot.screenshots = vec![ScreenshotView { + file: "short.png".to_string(), + bytes: 10, + modified_ms: Some(STAMP), + preview: ScreenshotPreview::Ready(ThumbnailView { + width: 4, + height: 4, + pixels: vec![0; 15], + }), + }]; + let mut state = bound_state("a"); + state.changed(snapshot); + let saves = from_state(&state, Lang::ZhCn.catalog()); + assert_eq!(saves.thumbnails(), 0, "坏像素不该被当成图"); + assert_eq!( + saves.screenshots[0].preview, + ShotPreview::Missing { + note: Texts::of(Lang::ZhCn.catalog()) + .saves_preview_reason(ScreenshotThumbKind::Decode) + .to_string() + } + ); +} + +/// **句柄复用（M251 复审要求）**：同一张图两次 `from_state` 必须拿到**同一个 `Handle` id**。 +/// +/// 为什么这条是判据而不是细节：`Handle::from_rgba` 每次生成新 id，而 iced 的渲染器按 id 缓存 +/// 纹理——id 一变就把像素重传一遍。`from_state` 挂在 `refresh_view` 上（每个 UI 事件都跑）， +/// 一屏 60 张就是「每次事件重传 ≈6MB」。id 相同 ⇒ 纹理只上传一次。 +/// +/// 抓得住：把 `handle_for` 换回 `Handle::from_rgba(...)`（两次 id 必不相同）、键里漏掉 mtime/大小 +/// （文件变了却复用旧句柄，见下一条）。 +/// 抓不住：渲染器到底有没有复用纹理（那是 iced 内部，只能由「id 相同」推断）。 +#[test] +pub(super) fn the_same_screenshot_reuses_one_handle() { + clear_handles(); + let mut state = bound_state("a"); + state.changed(view("a")); + + let first = from_state(&state, Lang::ZhCn.catalog()); + let second = from_state(&state, Lang::ZhCn.catalog()); + assert_eq!( + handle_id(&first).id(), + handle_id(&second).id(), + "同一张图在两次 refresh_view 里必须复用同一个句柄（否则每帧重传纹理）" + ); +} + +/// 文件被覆盖（mtime 变）⇒ **必须换一个新句柄**（缓存键里含 mtime 的另一半证据）。 +/// +/// 抓得住：句柄键只按 `(目录, 文件名)`（截图被覆盖后仍画旧像素）。 +#[test] +pub(super) fn a_changed_screenshot_gets_a_new_handle() { + clear_handles(); + let mut state = bound_state("a"); + state.changed(view("a")); + let first = from_state(&state, Lang::ZhCn.catalog()); + + let mut changed = view("a"); + changed.screenshots[0].modified_ms = Some(STAMP + 1); + let mut state = bound_state("a"); + state.changed(changed); + let second = from_state(&state, Lang::ZhCn.catalog()); + + assert_ne!( + handle_id(&first).id(), + handle_id(&second).id(), + "mtime 变了就是另一张图，必须换句柄" + ); +} diff --git a/crates/app-iced/src/pages/instances/tests/saves/write.rs b/crates/app-iced/src/pages/instances/tests/saves/write.rs new file mode 100644 index 0000000..82a9000 --- /dev/null +++ b/crates/app-iced/src/pages/instances/tests/saves/write.rs @@ -0,0 +1,201 @@ +//! 存档**写操作**的页面模型判据（M247）——从 `tests/saves.rs` 拆出（那边越过 400 行）。 +//! +//! 三条都在 `from_state` 这一层钉：写失败的主句（哪一行 + 哪个动作 + 什么原因）、 +//! 「游戏在运行」不是「写盘失败」（不留重试按钮）、以及草稿 / 在飞 / 回执变成页面字段。 + +use super::super::super::saves::{failure_line, from_state, op_line}; +use super::super::super::Texts; +use super::{bound_state, view}; +use unlucky_i18n::Lang; +use unlucky_presenter::dto::{SavesFailureKind, SavesFailureOp, SavesFailureView, SavesOped}; +use unlucky_presenter::state::SavesOp; + +/// 写操作失败：**不画重试**（重试按钮会去重新列目录，那是错的动作），并且主句带**哪个世界**。 +/// +/// 抓得住：三种写失败被折叠成同一句「读取 saves/ 失败」——用户看不出是哪一行出了什么事。 +#[test] +fn write_failures_are_named_per_operation_and_never_retryable() { + let cases = [ + ( + SavesFailureOp::Rename, + SavesFailureKind::WriteConflict, + "重命名 Better World 失败：同名世界已存在", + ), + ( + SavesFailureOp::Delete, + SavesFailureKind::WriteMissing, + "删除 Better World 失败：那个世界已不在", + ), + ( + SavesFailureOp::Backup, + SavesFailureKind::WriteTooLarge, + "备份 Better World 失败：这个世界太大，一个 zip 装不下", + ), + ]; + for (op, kind, expected) in cases { + let failure = SavesFailureView { + instance: "a".to_string(), + file: "Better World".to_string(), + op: Some(op), + kind, + detail: String::new(), + }; + let line = failure_line(&failure, Texts::of(Lang::ZhCn.catalog())); + assert_eq!(line, expected); + + let mut state = bound_state("a"); + state.changed(view("a")); + state.failed(failure); + let saves = from_state(&state, Lang::ZhCn.catalog()); + assert!(!saves.retryable, "{op:?} 失败了还画着重试按钮"); + assert!(saves.error.is_some()); + assert_eq!(saves.worlds.len(), 1, "{op:?} 失败把列表清了"); + } +} + +/// 「游戏在跑」不是「写盘失败」：主句要直说先退出，而且**不画重试**。 +/// +/// 抓得住：把这条折进 `WriteFailed` —— 用户会看到「删除 A 失败：写盘失败」，然后以为是权限问题， +/// 反复重试；真正该做的事（退出游戏）一个字都没说。 +#[test] +fn a_running_game_says_exit_first_not_write_failed() { + let cases = [ + ( + SavesFailureOp::Rename, + "重命名 Better World 失败：游戏正在运行（先退出再操作）", + ), + ( + SavesFailureOp::Delete, + "删除 Better World 失败：游戏正在运行（先退出再操作）", + ), + ( + SavesFailureOp::Backup, + "备份 Better World 失败：游戏正在运行（先退出再操作）", + ), + ]; + for (op, expected) in cases { + let failure = SavesFailureView { + instance: "a".to_string(), + file: "Better World".to_string(), + op: Some(op), + kind: SavesFailureKind::GameRunning, + detail: String::new(), + }; + assert_eq!( + failure_line(&failure, Texts::of(Lang::ZhCn.catalog())), + expected + ); + assert!( + !expected.contains("写盘失败"), + "「游戏在跑」被说成了「写盘失败」" + ); + + let mut state = bound_state("a"); + state.changed(view("a")); + state.failed(failure); + let saves = from_state(&state, Lang::ZhCn.catalog()); + assert!(!saves.retryable, "{op:?}：在飞被拒还画重试按钮"); + assert_eq!(saves.worlds.len(), 1, "{op:?}：被拒把列表清了"); + } + // 英文那一侧同一条判据（主语不同、意思相同）。 + let failure = SavesFailureView { + instance: "a".to_string(), + file: "Better World".to_string(), + op: Some(SavesFailureOp::Delete), + kind: SavesFailureKind::GameRunning, + detail: String::new(), + }; + let en = failure_line(&failure, Texts::of(Lang::En.catalog())); + assert_eq!( + en, + "Could not delete Better World: the game is running (exit it first)" + ); +} + +/// 三样交互态（草稿 / 在飞 / 回执）都要变成页面字段：改名中的那一行、置灰的那一行、成功那句话。 +#[test] +fn draft_pending_and_receipt_become_page_fields() { + let mut state = bound_state("a"); + state.changed(view("a")); + state.start_rename("Better World"); + state.edit_rename("Renamed".to_string()); + let saves = from_state(&state, Lang::En.catalog()); + let editing = saves.editing.as_ref().expect("草稿没进页面模型"); + assert_eq!(editing.dir, "Better World"); + assert_eq!(editing.text, "Renamed"); + assert!(!saves.busy_with("Better World"), "还在打字就算在飞了"); + + state.mark_pending(SavesOp::Backup { + dir: "Better World".to_string(), + }); + let saves = from_state(&state, Lang::En.catalog()); + assert!(saves.editing.is_none(), "发请求时草稿该收起来"); + assert!(saves.busy_with("Better World")); + assert!(!saves.busy_with("Other")); + + // 回执：host 写在快照里，下一次普通 List 就没了。 + let mut done = view("a"); + done.last_op = Some(SavesOped::BackedUp { + dir: "Better World".to_string(), + file: "Better World-20240501-100000.zip".to_string(), + path: "D:/ULL/.ULL/data/exports/saves/Better World-20240501-100000.zip".to_string(), + bytes: 2_048, + skipped: 2, + }); + state.changed(done); + let saves = from_state(&state, Lang::ZhCn.catalog()); + let notice = saves.notice.as_deref().expect("回执没进页面模型"); + assert!(notice.contains("2.0 KB"), "回执要带大小：{notice}"); + assert!( + notice.contains("Better World-20240501-100000.zip"), + "{notice}" + ); + assert!( + notice.contains("跳过 2 个符号链接"), + "跳过的链接要报出来：{notice}" + ); + assert!(saves.busy.is_none(), "回程之后还在飞"); +} + +/// 三种回执的措辞（重命名 / 删除 / 备份）。 +#[test] +fn every_receipt_says_what_happened() { + let texts = Texts::of(Lang::ZhCn.catalog()); + assert_eq!( + op_line( + &SavesOped::Renamed { + from: "A".to_string(), + to: "B".to_string() + }, + texts + ), + "已把 A 改名为 B。" + ); + assert_eq!( + op_line( + &SavesOped::Deleted { + dir: "A".to_string() + }, + texts + ), + "已删除 A。" + ); + let backed_up = op_line( + &SavesOped::BackedUp { + dir: "A".to_string(), + file: "A.zip".to_string(), + path: "D:/x/A.zip".to_string(), + bytes: 0, + skipped: 0, + }, + texts, + ); + assert!( + backed_up.starts_with("已把 A 备份到 D:/x/A.zip"), + "{backed_up}" + ); + assert!( + !backed_up.contains("符号链接"), + "没跳过就别提链接：{backed_up}" + ); +} 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..876e301 --- /dev/null +++ b/crates/app-iced/src/pages/instances/text.rs @@ -0,0 +1,232 @@ +//! 实例页的**文案入口**：页面上一处可见英文字面量都不留，全部从目录取。 +//! +//! ## 为什么要有这一层（而不是在控件树里直接 `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}; +use unlucky_presenter::dto::ModFailureKind; + +/// 存档 / 截图一族的文案（M235 读路径 + M247 写操作 + M251 缩略图） +mod saves; + +/// 实例页 + 详情列的文案（一个 `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) + } + + // ------------------------------------------------------------- 启动参数（M157） + pub(super) fn launch_title(self) -> &'static str { + self.text(Key::InstancesLaunchTitle) + } + pub(super) fn launch_jvm(self) -> &'static str { + self.text(Key::InstancesLaunchJvm) + } + pub(super) fn launch_jvm_hint(self) -> &'static str { + self.text(Key::InstancesLaunchJvmHint) + } + pub(super) fn launch_game(self) -> &'static str { + self.text(Key::InstancesLaunchGame) + } + pub(super) fn launch_game_hint(self) -> &'static str { + self.text(Key::InstancesLaunchGameHint) + } + pub(super) fn launch_memory(self) -> &'static str { + self.text(Key::InstancesLaunchMemory) + } + /// 「留空 = 跟随全局默认（{default} MiB）」，`default` 是生效值（三级回落之后）。 + pub(super) fn launch_memory_hint(self, default_mb: u32) -> String { + self.0.render( + Key::InstancesLaunchMemoryHint, + &[("default", &default_mb.to_string())], + ) + } + pub(super) fn launch_java(self) -> &'static str { + self.text(Key::InstancesLaunchJava) + } + pub(super) fn launch_java_hint(self) -> &'static str { + self.text(Key::InstancesLaunchJavaHint) + } + pub(super) fn launch_backend(self) -> &'static str { + self.text(Key::InstancesLaunchBackend) + } + /// 「需游戏版本 {min} 及以上（本实例 {version}）」。 + /// + /// `min` 来自 DTO（`LaunchFacts::min_version` ← core 的 `GRAPHICS_BACKEND_MIN_VERSION`）， + /// **不在目录里硬编码版本号**——否则 core 一改门槛，文案会继续骗人（r4 复审 P3-c）。 + pub(super) fn launch_backend_gated(self, version: &str, min: &str) -> String { + self.0.render( + Key::InstancesLaunchBackendGated, + &[("version", version), ("min", min)], + ) + } + /// 「生效：vulkan」。 + pub(super) fn launch_effective(self, value: &str) -> String { + self.0 + .render(Key::InstancesLaunchEffective, &[("value", value)]) + } + /// 三态后端的显示名（稳定 id → 文案）；**未知 id 返回 `None`**（调用方原样上屏，不猜）。 + pub(super) fn backend_label(self, id: &str) -> Option<&'static str> { + Some(self.text(match id { + "default" => Key::InstancesBackendDefault, + "opengl" => Key::InstancesBackendOpengl, + "vulkan" => Key::InstancesBackendVulkan, + _ => return None, + })) + } + pub(super) fn launch_save(self) -> &'static str { + self.text(Key::InstancesLaunchSave) + } + pub(super) fn launch_reset(self) -> &'static str { + self.text(Key::InstancesLaunchReset) + } + + // ------------------------------------------------------------- MODS 区（M224） + pub(super) fn mods_title(self) -> &'static str { + self.text(Key::InstancesModsTitle) + } + /// 「12 启用 · 3 禁用」。 + pub(super) fn mods_count(self, enabled: usize, disabled: usize) -> String { + self.0.render( + Key::InstancesModsCount, + &[ + ("enabled", &enabled.to_string()), + ("disabled", &disabled.to_string()), + ], + ) + } + pub(super) fn mods_loading(self) -> &'static str { + self.text(Key::InstancesModsLoading) + } + pub(super) fn mods_empty(self) -> &'static str { + self.text(Key::InstancesModsEmpty) + } + pub(super) fn mods_missing_dir(self) -> &'static str { + self.text(Key::InstancesModsMissingDir) + } + pub(super) fn mods_running(self) -> &'static str { + self.text(Key::InstancesModsRunning) + } + pub(super) fn mods_old_badge(self) -> &'static str { + self.text(Key::InstancesModsOldBadge) + } + /// 「跳过 3 项」。 + pub(super) fn mods_skipped(self, count: usize) -> String { + self.0 + .render(Key::InstancesModsSkipped, &[("count", &count.to_string())]) + } + /// 读目录失败的主句：`读取 mods/ 失败：没有可用的 mods/ 目录`。 + pub(super) fn mods_failed(self, reason: &str) -> String { + self.0 + .render(Key::InstancesModsFailed, &[("reason", reason)]) + } + /// 启停失败的主句：`启停 x.jar 失败：同名文件已存在`。 + pub(super) fn mods_toggle_failed(self, file: &str, reason: &str) -> String { + self.0.render( + Key::InstancesModsToggleFailed, + &[("file", file), ("reason", reason)], + ) + } + /// 启停失败大类的短句（`ModFailureKind` → 一句话；未知取值不猜，原样上屏）。 + pub(super) fn mods_reason(self, kind: ModFailureKind) -> &'static str { + self.text(match kind { + ModFailureKind::Running => Key::InstancesModsReasonRunning, + ModFailureKind::InstanceUnavailable => Key::InstancesModsReasonInstance, + ModFailureKind::UnsafeName => Key::InstancesModsReasonName, + ModFailureKind::ModsDirUnusable => Key::InstancesModsReasonDirectory, + ModFailureKind::NotFound => Key::InstancesModsReasonMissing, + ModFailureKind::NotARegularFile => Key::InstancesModsReasonNotFile, + ModFailureKind::Collision => Key::InstancesModsReasonCollision, + ModFailureKind::Rename => Key::InstancesModsReasonRename, + }) + } + + 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 { + Key::ALL + .iter() + .copied() + .filter(|key| key.name().starts_with("Instances")) + } +} diff --git a/crates/app-iced/src/pages/instances/text/saves.rs b/crates/app-iced/src/pages/instances/text/saves.rs new file mode 100644 index 0000000..8c01969 --- /dev/null +++ b/crates/app-iced/src/pages/instances/text/saves.rs @@ -0,0 +1,214 @@ +//! 实例页文本入口的**存档 / 截图一族**（从 `text.rs` 拆出：那边加完缩略图那四句之后越过 +//! 400 行硬线，M251）。 +//! +//! 拆法是「**纯搬移 + 一族新增**」：M235 的读路径、M247 的写操作、M251 的缩略图三批 key 全在这一 +//! 个 `impl Texts` 块里，`text.rs` 保留导航 / 元信息 / MODS 那几族。两处都是 `impl Texts`（Rust +//! 允许这么写），调用方依旧写 `texts.saves_*()`，路径不变。 +//! +//! 口径与 `text.rs` 完全一致：**不拼中文**，每个方法只把 `Key` 翻成 `&'static str`（带占位符的用 +//! `Catalog::render` 现填）；带 `{reason}` / `{file}` 的句子由调用方把「已完成的事实」传进来。 + +use unlucky_i18n::Key; +use unlucky_presenter::dto::{SavesFailureKind, ScreenshotThumbKind}; + +use super::Texts; + +impl Texts { + // ------------------------------------------------------------- 存档区（M235） + pub(in crate::pages::instances) fn saves_title(self) -> &'static str { + self.text(Key::InstancesSavesTitle) + } + /// 「3 个世界 · 12 张截图」。 + pub(in crate::pages::instances) fn saves_count(self, worlds: usize, shots: usize) -> String { + self.0.render( + Key::InstancesSavesCount, + &[ + ("worlds", &worlds.to_string()), + ("shots", &shots.to_string()), + ], + ) + } + pub(in crate::pages::instances) fn saves_loading(self) -> &'static str { + self.text(Key::InstancesSavesLoading) + } + pub(in crate::pages::instances) fn saves_empty(self) -> &'static str { + self.text(Key::InstancesSavesEmpty) + } + pub(in crate::pages::instances) fn saves_missing_dir(self) -> &'static str { + self.text(Key::InstancesSavesMissingDir) + } + pub(in crate::pages::instances) fn saves_worlds(self) -> &'static str { + self.text(Key::InstancesSavesWorlds) + } + pub(in crate::pages::instances) fn saves_screenshots(self) -> &'static str { + self.text(Key::InstancesSavesScreenshots) + } + pub(in crate::pages::instances) fn saves_no_worlds(self) -> &'static str { + self.text(Key::InstancesSavesNoWorlds) + } + pub(in crate::pages::instances) fn saves_no_screenshots(self) -> &'static str { + self.text(Key::InstancesSavesNoScreenshots) + } + /// 「有图标」：只判 `icon.png` 存不存在。 + /// + /// M251 之后**仍未解**世界图标——缩略图墙只覆盖 `screenshots/`（D54 的范围）。这行字眼 + /// 原来写的是「缩略图墙不在 U3 范围内」，那句话今天已经失真（墙做了），改成现状描述。 + pub(in crate::pages::instances) fn saves_world_icon(self) -> &'static str { + self.text(Key::InstancesSavesWorldIcon) + } + pub(in crate::pages::instances) fn saves_time_unknown(self) -> &'static str { + self.text(Key::InstancesSavesTimeUnknown) + } + /// 「跳过 3 项」。 + pub(in crate::pages::instances) fn saves_skipped(self, count: usize) -> String { + self.0 + .render(Key::InstancesSavesSkipped, &[("count", &count.to_string())]) + } + pub(in crate::pages::instances) fn saves_open_folder(self) -> &'static str { + self.text(Key::InstancesSavesOpenFolder) + } + pub(in crate::pages::instances) fn saves_retry(self) -> &'static str { + self.text(Key::InstancesSavesRetry) + } + /// 读目录失败的主句：`读取 saves/ 失败：目录不可用`。 + pub(in crate::pages::instances) fn saves_failed(self, reason: &str) -> String { + self.0 + .render(Key::InstancesSavesFailed, &[("reason", reason)]) + } + /// 打开文件夹失败的主句：`打开文件夹失败：文件管理器没起来`。 + pub(in crate::pages::instances) fn saves_open_failed(self, reason: &str) -> String { + self.0 + .render(Key::InstancesSavesOpenFailed, &[("reason", reason)]) + } + /// 失败大类的短句（`SavesFailureKind` → 一句话；写操作那八类各有自己的话）。 + pub(in crate::pages::instances) fn saves_reason(self, kind: SavesFailureKind) -> &'static str { + self.text(match kind { + SavesFailureKind::DirUnusable => Key::InstancesSavesReasonDir, + SavesFailureKind::InstanceUnavailable => Key::InstancesSavesReasonInstance, + SavesFailureKind::OpenFailed => Key::InstancesSavesReasonOpen, + SavesFailureKind::WriteUnsafeName => Key::InstancesSavesReasonUnsafeName, + SavesFailureKind::WriteSymlink => Key::InstancesSavesReasonSymlink, + SavesFailureKind::WriteMissing => Key::InstancesSavesReasonMissing, + SavesFailureKind::WriteNotADirectory => Key::InstancesSavesReasonNotDir, + SavesFailureKind::WriteConflict => Key::InstancesSavesReasonConflict, + SavesFailureKind::WriteBoundary => Key::InstancesSavesReasonBoundary, + SavesFailureKind::WriteTooLarge => Key::InstancesSavesReasonTooLarge, + SavesFailureKind::GameRunning => Key::InstancesSavesReasonRunning, + SavesFailureKind::WriteFailed => Key::InstancesSavesReasonWrite, + }) + } + + // ------------------------------------------------- 存档写操作（M247 · SAVESOPS） + pub(in crate::pages::instances) fn saves_rename(self) -> &'static str { + self.text(Key::InstancesSavesRename) + } + pub(in crate::pages::instances) fn saves_backup(self) -> &'static str { + self.text(Key::InstancesSavesBackup) + } + pub(in crate::pages::instances) fn saves_delete(self) -> &'static str { + self.text(Key::InstancesSavesDelete) + } + /// 行内输入框的占位符（不是按钮文案：它说「该填什么」）。 + pub(in crate::pages::instances) fn saves_rename_placeholder(self) -> &'static str { + self.text(Key::InstancesSavesRenamePlaceholder) + } + pub(in crate::pages::instances) fn saves_rename_confirm(self) -> &'static str { + self.text(Key::InstancesSavesRenameConfirm) + } + pub(in crate::pages::instances) fn saves_cancel(self) -> &'static str { + self.text(Key::InstancesSavesCancel) + } + /// 「正在处理…」：写请求在飞时顶替那一行的操作区。 + pub(in crate::pages::instances) fn saves_busy(self) -> &'static str { + self.text(Key::InstancesSavesBusy) + } + pub(in crate::pages::instances) fn saves_delete_title(self) -> &'static str { + self.text(Key::InstancesSavesDeleteTitle) + } + /// 删除确认框的正文：`{dir} 和它里面的全部内容都会被删除，且不能撤销。` + pub(in crate::pages::instances) fn saves_delete_body(self, dir: &str) -> String { + self.0 + .render(Key::InstancesSavesDeleteBody, &[("dir", dir)]) + } + pub(in crate::pages::instances) fn saves_delete_confirm(self) -> &'static str { + self.text(Key::InstancesSavesDeleteConfirm) + } + /// 改名成功的回执：`已把 A 改名为 B。` + pub(in crate::pages::instances) fn saves_renamed(self, from: &str, to: &str) -> String { + self.0 + .render(Key::InstancesSavesRenamed, &[("from", from), ("to", to)]) + } + /// 删除成功的回执：`已删除 A。` + pub(in crate::pages::instances) fn saves_deleted(self, dir: &str) -> String { + self.0.render(Key::InstancesSavesDeleted, &[("dir", dir)]) + } + /// 备份成功的回执：`已把 A 备份到 D:/…／A-…zip（1.2 MiB）。` + pub(in crate::pages::instances) fn saves_backed_up( + self, + dir: &str, + path: &str, + size: &str, + ) -> String { + self.0.render( + Key::InstancesSavesBackedUp, + &[("dir", dir), ("path", path), ("size", size)], + ) + } + /// 「跳过 N 个符号链接」（备份时没跟随的那些）。 + pub(in crate::pages::instances) fn saves_backup_skipped(self, count: usize) -> String { + self.0.render( + Key::InstancesSavesBackupSkipped, + &[("count", &count.to_string())], + ) + } + /// 重命名失败的主句：`重命名 A 失败：同名世界已存在`。 + pub(in crate::pages::instances) fn saves_rename_failed( + self, + file: &str, + reason: &str, + ) -> String { + self.0.render( + Key::InstancesSavesRenameFailed, + &[("file", file), ("reason", reason)], + ) + } + /// 删除失败的主句。 + pub(in crate::pages::instances) fn saves_delete_failed( + self, + file: &str, + reason: &str, + ) -> String { + self.0.render( + Key::InstancesSavesDeleteFailed, + &[("file", file), ("reason", reason)], + ) + } + /// 备份失败的主句。 + pub(in crate::pages::instances) fn saves_backup_failed( + self, + file: &str, + reason: &str, + ) -> String { + self.0.render( + Key::InstancesSavesBackupFailed, + &[("file", file), ("reason", reason)], + ) + } + // ------------------------------------------------- 截图缩略图（M251 · SAVESHOTS） + /// 「这一格为什么没有图」的短句（`未生成预览` / 太大 / 读不出 / 解不出）。 + pub(in crate::pages::instances) fn saves_preview_reason( + self, + kind: ScreenshotThumbKind, + ) -> &'static str { + self.text(match kind { + ScreenshotThumbKind::TooLarge => Key::InstancesSavesPreviewTooLarge, + ScreenshotThumbKind::Unreadable => Key::InstancesSavesPreviewUnreadable, + ScreenshotThumbKind::Decode => Key::InstancesSavesPreviewDecode, + }) + } + + /// 「没轮到」那一句（超 60 张刷新预算 / 这一拍还没解到）。 + pub(in crate::pages::instances) fn saves_preview_none(self) -> &'static str { + self.text(Key::InstancesSavesPreviewNone) + } +} 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, + /// 主列所在 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..a3ad75d --- /dev/null +++ b/crates/app-iced/src/pages/layout/source.rs @@ -0,0 +1,245 @@ +//! **源码结构断言**的小工具：把某个函数的实现文本切出来（只给测试用）。 +//! +//! ## 为什么要读源码（而不是量 Element） +//! +//! iced 的 `Element` 没有几何内省接口（`size()` 只是 `Size`，取不到布局结果）， +//! 所以「页面把块摆在哪 / 有没有在行之间叠间距」在单测里**量不到**。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 + 字体栈，属另一个决定）。 +//! +//! ## 「接线在不在」必须走 [`code_line`]（T29，M252 r1 的 P1） +//! +//! 文本判据有个致命退化：把真接线**注释掉**、字符串留在注释里，`contains(..)` 照样绿。 +//! 所以断言「某处接了 `X`」时不许直接 `contains`，统一走 [`code_line`] / [`has_code_line`] +//! （注释剥掉、按行首判，边界见 [`code`] 的模块文档）。 + +mod code; + +pub(crate) use code::{code_line, code_lines, code_text, has_code_line}; + +/// 把 `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 = ;` +/// - `if let Some() = {`（`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/code.rs b/crates/app-iced/src/pages/layout/source/code.rs new file mode 100644 index 0000000..e3f1c6a --- /dev/null +++ b/crates/app-iced/src/pages/layout/source/code.rs @@ -0,0 +1,193 @@ +//! **剥注释**的行扫描：接线守卫的判据只能看「代码行」，不能看「文本里还有没有那个字符串」。 +//! +//! ## 为什么要有这个文件（T29 的第三次复发） +//! +//! 接线守卫是拿源码文本当判据的（`Element` 没有内省接口，见 [`super`] 的模块文档）。用 +//! `text.contains(".on_submit(")` 写时，把真接线**注释掉**就整条骗过：字符串还在，功能没了。 +//! M252 复审实测了四种注释型变异（行注释 / `/*` 独占一行的块注释 / `.on_submit_maybe(None)` +//! 再加 `let _submit` 绕掉 rustc 的 unused 兜底），**943 条用例一条不红**；同一批「真删除」 +//! 变异则每条都红。⇒ 守卫不是没用，是**只认一种改法**。 +//! +//! 所以：接线类断言一律先过 [`code_lines`]（注释剥掉、只留代码），再按**行首**判 [`code_line`]。 +//! +//! ## 剥什么（三条都要记） +//! +//! | 形态 | 处理 | +//! |---|---| +//! | `// …` / `/// …` / `//! …` | 剥到行尾 | +//! | `/* … */`，**跨行、可嵌套**（Rust 允许嵌套块注释） | 整段剥掉；行结构保留（只被注释占满的行变空串） | +//! | 字符串字面量里的 `//` / `/*`（`"http://x"`、`"a /* b"`） | **不剥**：字面量整段原样搬过去 | +//! | 字符字面量 `'"'` / `'\''` | 整段搬过去，不会误开字符串 | +//! +//! ## 剥不了什么（边界，改守卫前先读这一节） +//! +//! 1. **原始字符串没有被特判**：`r"…"` / `r#"…"#` 里那个 `"` 被当成普通字符串起点，于是 +//! 内容（含 `//`）原样保留——对**不含**引号的内容（`r"a // b"`）恰好是对的。含引号时会错位， +//! 而**含引号是常态不是例外**（JSON 字面量必然含 `"`）。实测（`git ls-files` + 逐字面量扫 +//! `r(#+)"`）：`crates/app-iced/src` 下 **9 处** `r#"`、其中 **8 处内容含 `"`**； +//! 全仓 `crates/**.rs` **291 处**。 +//! +//! 两个方向都要知道（都由 `code/tests.rs` 的用例钉住）： +//! +//! | 写法 | 偏差 | 方向 | +//! |---|---|---| +//! | `r#"a " b"#; // .on_submit(fake())` | 提前收尾后又开了一个「字符串」⇒ **尾部注释不被剥** | **假绿**（`code_text(..).contains(..)` 形式的断言会被骗） | +//! | `r#"{"url":"http://x"}"#; // …` | 截断到 `http:` 之后 ⇒ **多剥** | **假红** | +//! +//! **对本仓的三处接线守卫无影响**：它们判「行首就是那个调用」（[`code_line`]），而行首是 +//! `r#"…` 的行永远匹配不上；受影响的是 `code_text(..).contains(..)` 形式的旧断言 +//! （T29 清单里还有约 90 处）。三处被守卫的文件（`field.rs` / `saves/rows.rs` / +//! `section/accent.rs`）`r#"` 计数都是 0。 +//! 2. **跨行普通字符串**（行尾 `\` 续行）**不识别**：字符串状态每行复位，续行的下一行会当代码。 +//! 后果是**假红**（把字符串里的一段当代码看见，反而更啰嗦）。 +//! 3. 它**不判语义**：注释剥掉之后，「`.on_submit(..)` 在不在」仍然只是文本事实。等价重构 +//! （先赋值再调用）可能绕过——所以接线守卫的 needle 与写法要一起维护（见各守卫的 docstring）。 +//! +//! 除第 1 条里「内嵌引号」那个形态外，其余偏差都是**假红**：宁可假红，也不要「注释掉仍绿」。 + +/// 逐行的代码文本（注释已剥）。**行数与输入一一对应**：只被注释占满的行变成空串。 +/// +/// 保留行结构是为了让失败信息能直接对回源码行，也让「行首」这条谓词有意义。 +#[must_use] +pub(crate) fn code_lines(source: &str) -> Vec { + let mut lines = Vec::with_capacity(source.lines().count()); + // 块注释的嵌套深度（0 = 不在注释里）。跨行靠它带着走。 + let mut depth = 0_usize; + + for line in source.lines() { + let chars: Vec = line.chars().collect(); + let mut code = String::with_capacity(chars.len()); + let mut index = 0; + + while index < chars.len() { + let ch = chars[index]; + + if depth > 0 { + if ch == '/' && chars.get(index + 1) == Some(&'*') { + depth += 1; + index += 2; + } else if ch == '*' && chars.get(index + 1) == Some(&'/') { + depth -= 1; + index += 2; + } else { + index += 1; + } + continue; + } + + if ch == '/' && chars.get(index + 1) == Some(&'/') { + break; + } + if ch == '/' && chars.get(index + 1) == Some(&'*') { + depth = 1; + index += 2; + continue; + } + + if ch == '"' { + index = copy_string_literal(&chars, index, &mut code); + continue; + } + if ch == '\'' { + index = copy_char_literal(&chars, index, &mut code); + continue; + } + + code.push(ch); + index += 1; + } + + lines.push(code.trim_end().to_owned()); + } + + lines +} + +/// 把从 `start`（一个 `"`）起的字符串字面量原样搬进 `code`，返回下一个未处理的下标。 +/// +/// 「原样」= 里面的 `//`、`/*` 都不当注释（这条正是本模块存在的理由之一）。 +/// 行内没有闭合引号时搬到最后（跨行字符串见模块文档第 2 条边界）。 +fn copy_string_literal(chars: &[char], start: usize, code: &mut String) -> usize { + code.push(chars[start]); + let mut index = start + 1; + + while index < chars.len() { + let ch = chars[index]; + code.push(ch); + index += 1; + + match ch { + // 转义：把被转义的字符一起搬走（`\"` 不会提前收尾） + '\\' => { + if index < chars.len() { + code.push(chars[index]); + index += 1; + } + } + '"' => break, + _ => {} + } + } + + index +} + +/// 把从 `start`（一个 `'`）起的**字符字面量**原样搬过去；生命周期（`'a`）只搬那个引号。 +/// +/// 为什么值得单独判：`'"'` 会让「见到 `"` 就当字符串开头」的扫描器错位，于是整行的注释剥错。 +fn copy_char_literal(chars: &[char], start: usize, code: &mut String) -> usize { + code.push(chars[start]); + let index = start + 1; + + // `'\n'` / `'\''`：反斜杠 + 一个字符 + 收尾引号 + if chars.get(index) == Some(&'\\') && chars.get(index + 2) == Some(&'\'') { + for offset in index..index + 3 { + if let Some(ch) = chars.get(offset) { + code.push(*ch); + } + } + return index + 3; + } + + // `'x'`：一个字符 + 收尾引号 + if chars.get(index + 1) == Some(&'\'') { + if let Some(ch) = chars.get(index) { + code.push(*ch); + } + code.push('\''); + return index + 2; + } + + // 生命周期 / 未闭合：只搬引号，余下的照常扫 + index +} + +/// `source` 里第一条**去注释后行首是 `prefix`** 的代码行（`None` = 没有这样一行）。 +/// +/// 接线守卫统一用这个谓词：`code_line(rows_rs, ".on_submit(")` —— 那行被注释掉就查不到。 +#[must_use] +pub(crate) fn code_line(source: &str, prefix: &str) -> Option { + code_lines(source) + .into_iter() + .find(|line| line.trim_start().starts_with(prefix)) +} + +/// [`code_line`] 的布尔形态（全文件扫描那种只关心「有没有」的场合）。 +#[must_use] +pub(crate) fn has_code_line(source: &str, prefix: &str) -> bool { + code_line(source, prefix).is_some() +} + +/// 整份源码剥注释后的文本（行结构保留）。 +/// +/// **T29 的统一收敛口**：仓库里还有一批 `source.contains("…")` 形式的接线断言（见 M252 r1 +/// 报告的清单）。它们在问的是同一件事——「这段接线在不在」——只是写法更早。把 +/// `source.contains(..)` 换成 `code_text(&source).contains(..)` 是一行改动：判据方向不变， +/// 但「注释掉仍绿」这条退化被堵上。新写的断言优先用 [`code_line`]（能钉「行首是哪个调用」）。 +#[must_use] +pub(crate) fn code_text(source: &str) -> String { + code_lines(source).join("\n") +} + +#[cfg(test)] +mod tests; diff --git a/crates/app-iced/src/pages/layout/source/code/tests.rs b/crates/app-iced/src/pages/layout/source/code/tests.rs new file mode 100644 index 0000000..aebafb4 --- /dev/null +++ b/crates/app-iced/src/pages/layout/source/code/tests.rs @@ -0,0 +1,177 @@ +//! [`code_lines`] 自己的断言（门禁的门禁，T28：守卫守不到自己就等于没有）。 +//! +//! 这一族用例的形状统一：**喂一段源码文本 → 断言剥完剩下什么**。它们不读真文件，所以不会因为 +//! 别人改页面而假红；真文件上的效果由三处接线守卫自己证。 + +use super::{code_line, code_lines, has_code_line}; + +/// 行结构必须保留：只被注释占满的行是空串，代码行原样（去掉行尾空白）。 +#[test] +fn it_strips_line_comments_and_keeps_the_line_count() { + let source = "\ +let a = 1; // 尾注释 +// 整行注释 +/// 文档注释 +let b = 2; +/* 单行块注释 */ +let c = 3; +"; + let lines = code_lines(source); + assert_eq!(lines.len(), 6, "行数必须一一对应：{lines:?}"); + assert_eq!(lines[0], "let a = 1;"); + assert_eq!(lines[1], ""); + assert_eq!(lines[2], ""); + assert_eq!(lines[3], "let b = 2;"); + assert_eq!(lines[4], ""); + assert_eq!(lines[5], "let c = 3;"); +} + +/// 跨行 / 嵌套块注释：整段剥掉，注释结束处的代码要接着留下来。 +#[test] +fn it_strips_block_comments_across_lines_and_nested() { + let source = "\ +let a = 1; +/* 开头 /* 嵌套 */ 还在注释里 +.on_submit(comment_only()) <- 这一行整个在注释里 +*/ let b = 2; +let c = /* 行内 */ 3; +"; + let lines = code_lines(source); + assert_eq!(lines[0], "let a = 1;"); + assert_eq!(lines[1], ""); + assert_eq!(lines[2], "", "块注释里的「接线」不许当成代码"); + assert_eq!(lines[3], " let b = 2;", "注释结束后同一行的代码要留下"); + assert_eq!(lines[4], "let c = 3;"); +} + +/// 字符串字面量里的 `//` 与 `/*` **不剥**（否则会把后半行代码剥掉 ⇒ 假红方向）。 +#[test] +fn it_keeps_slashes_inside_string_literals() { + let source = r##" +let url = "http://example.com/a//b"; let after = 1; +let odd = "a /* not a comment */ b"; let tail = 2; +let raw = r#"a // b"#; let tail2 = 3; +"##; + let lines = code_lines(source); + assert!( + lines[1].contains("http://example.com/a//b"), + "{:?}", + lines[1] + ); + assert!( + lines[1].contains("let after = 1;"), + "字符串里的 `//` 不该吃掉后半行：{:?}", + lines[1] + ); + assert!(lines[2].contains("let tail = 2;"), "{:?}", lines[2]); + // 原始字符串**没有特判**：靠其中那个 `"` 偶然按普通字符串处理（模块文档边界第 1 条）。 + assert!(lines[3].contains("a // b"), "{:?}", lines[3]); + assert!(lines[3].contains("let tail2 = 3;"), "{:?}", lines[3]); +} + +/// 已知缺口（模块文档边界第 1 条）：原始字符串含内嵌引号时扫描器会错位，**两个方向都钉住**。 +/// +/// 不是「希望这样」，是「哪天修了要知道」；也是 `code_text(..).contains(..)` 形式旧断言的已知上限。 +#[test] +fn raw_strings_with_inner_quotes_are_a_known_gap() { + // ① 多剥 ⇒ 假红：`r#"{"url":"http://x"}"#` 那一行会被截断（字符串里的 `//` 当成注释）。 + let json = "let s = r#\"{\"url\":\"http://x\"}\"#; let after = 1;\n"; + assert!( + !code_lines(json)[0].contains("let after = 1;"), + "已知缺口（假红方向）：JSON 原始字符串那行的后半行被剥掉了", + ); + + // ② 漏剥 ⇒ 假绿：内嵌引号之后扫描器又开了一个「字符串」，**尾部注释不被剥**， + // 于是注释里的 `.on_submit(fake())` 会留在「代码」里 —— `code_text(..).contains(..)` + // 形式的断言会被它骗过（三处接线守卫按行首判，不受影响）。 + let sneaky = "let s = r#\"a \" b\"#; // .on_submit(fake())\n"; + let line = &code_lines(sneaky)[0]; + assert!( + line.contains(".on_submit(fake())"), + "已知缺口（假绿方向）：内嵌引号的原始字符串会让尾部注释留下，实际：{line:?}" + ); + assert!( + !has_code_line(sneaky, ".on_submit("), + "行首判不受这条影响：那一行的行首是 `let s = r#\"`，永远匹配不上" + ); +} + +/// 字符字面量里的引号不会让扫描器错位（`'"'` 之后还有注释与代码）。 +#[test] +fn char_literals_do_not_open_a_string() { + let source = "\ +let quote = '\"'; let after = 1; // 尾注释 +let nl = '\\n'; let more = 2; +let lifetime: &'a str = \"x\"; +"; + let lines = code_lines(source); + assert!(lines[0].contains("let after = 1;"), "{:?}", lines[0]); + assert!(!lines[0].contains("尾注释"), "{:?}", lines[0]); + assert!(lines[1].contains("let more = 2;"), "{:?}", lines[1]); + assert!(lines[2].contains("&'a str = \"x\""), "{:?}", lines[2]); +} + +/// 行首谓词：注释里的「接线」查不到，代码里的查得到（本模块的全部意义）。 +#[test] +fn the_line_predicate_only_sees_code() { + let commented = "\ +let field = text_field( + ui, + Field::new(text) + // .on_submit(|| Message::Instances(commit_rename())), + , + on_input, +); +"; + assert!( + !has_code_line(commented, ".on_submit("), + "注释掉的那一行不许被当成交接" + ); + + let blocked = "\ +let field = text_field( + ui, + Field::new(text) + /* + .on_submit(|| Message::Instances(commit_rename())), + */ + , + on_input, +); +"; + assert!( + !has_code_line(blocked, ".on_submit("), + "块注释掉的那一行不许被当成交接" + ); + + let wired = "\ +let field = text_field( + ui, + Field::new(text) + .on_submit(|| Message::Instances(commit_rename())), + on_input, +); +"; + let line = code_line(wired, ".on_submit(").expect("接在代码里就该查得到"); + assert!(line.contains("commit_rename()"), "{line}"); +} + +/// needle 带实参时才分得清「转发」与「写死 None」——这正是 M252 复审的第二格。 +#[test] +fn the_predicate_tells_a_wired_argument_from_a_hardcoded_none() { + let wired = " .on_submit_maybe(submit)\n"; + let none = " .on_submit_maybe(None)\n"; + assert!(has_code_line(wired, ".on_submit_maybe(")); + assert!( + has_code_line(none, ".on_submit_maybe("), + "两条都「有这一行」" + ); + + let picked = |source: &str| { + code_line(source, ".on_submit_maybe(") + .expect("有那一行") + .contains("None") + }; + assert!(!picked(wired), "传的是值，不是 None"); + assert!(picked(none), "写死 None 必须被认出来"); +} 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 { + 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 { + 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..f4b755f --- /dev/null +++ b/crates/app-iced/src/pages/logs/diagnostic.rs @@ -0,0 +1,220 @@ +//! 诊断结果区：**按置信度档分组**的结论卡片 + 可直接粘进 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, + // M237：页脚按钮在诊断卡（`panel::card`）里 ⇒ 状态层叠卡底，不是画布底。 + Button::new( + catalog.text(Key::LogsCopySummary), + Message::CopySummary(logs.summary()), + ) + .base(panel::BASE), + ), + ] + .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::>(), + ) + .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, +} + +/// 一次运行的结局（`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, + /// 会话时间（展示用短串 `10-29 18:40`，presenter 已经格式化好）。 + pub when: Option, + /// 结局。 + pub outcome: Option, + /// 页头副标题（`实例 · 时间 · 结局`）：**构造时**拼好（见 [`Logs::with_status`]）， + /// 页面只负责显示——i18n 的「一句话 = 一个 key」不许在渲染里拼句子。 + pub status: Option, + /// 有没有正在跑的会话（`live_session` 非空）。 + /// + /// 为什么需要它：session 索引只在会话**结束**时追加（`host::logs::sessions`），所以运行中的 + /// 那一场根本不在 `log_sessions` 里 ⇒ 拿不到实例名与结局。r3 之前这里直接退回 + /// 「当前没有运行中的实例」，于是**每次实时运行页头都在说反话**（视觉复审 r3 的 P2-3）。 + pub live: bool, + /// 日志行（顺序 = 文件顺序）。 + pub lines: Vec, + /// 诊断结论（顺序 = presenter 给的顺序，页面不重排）。 + pub findings: Vec, +} + +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 = 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, + lang: Lang, +) -> Option { + 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..a25ff8e --- /dev/null +++ b/crates/app-iced/src/pages/logs/panel.rs @@ -0,0 +1,96 @@ +//! 两块的共用外壳：**定高的卡片 + 内部独立滚动**。 +//! +//! ## 为什么必须定高（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::elevation::MaterialLayer; + +use crate::app::components::interaction::Base; +use crate::theme::Ui; + +use super::super::frame; +use super::super::Message; + +/// 本卡的底：**与 [`frame::BASE`] 是同一个常量**（两张卡画的是同一个 `Card` 材质层，只是 +/// 一张按内容撑高、一张定高）。 +/// +/// 卡片里的控件（`Copy summary` 这类 Text 按钮）要用 `.base(BASE)`：它们的 hover / 禁用状态层 +/// 都得叠在卡片实色上，不是画布上。 +pub const BASE: Base = frame::BASE; + +/// 定高卡片（`Card` 材质层 + `OutlinedCard` 形状与 **1px 描边**，与 `frame::card` 同一套令牌： +/// 实例页 / 下载页的卡都带这条描边，日志页的两张主卡不能例外）。 +pub fn card<'a>( + ui: &'a Ui, + height: Length, + content: impl Into>, +) -> Element<'a, Message> { + let shape = ui.card_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> { + 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> { + scroller(ui, content, true) +} + +fn scroller<'a>( + ui: &'a Ui, + content: impl Into>, + 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.(MainWindow.java:261) +E at net.minecraft.client.Minecraft.(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 = GROUPS.iter().map(|band| logs.group(*band).len()).collect(); + + // 抓得住：分组顺序被改成低置信度在前（最像主因的沉底）；空组也被画出一个标题。 + // 抓不住：组内顺序（页面刻意不重排 presenter 给的顺序）。 + assert_eq!(GROUPS[0], Confidence::High); + assert_eq!( + counts.iter().sum::(), + 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..bf13adc --- /dev/null +++ b/crates/app-iced/src/pages/message.rs @@ -0,0 +1,170 @@ +//! 页面消息与动作表（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::prefs::ThemeMode; +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), + /// 切主题档（M229：设置页「通用 → 主题」的 Ink / Silver / 跟随系统三档）。 + /// + /// 载荷是 `ThemeMode` 而不是色板枚举：Ink / Silver 就是 `dark` / `light` 两侧的**产品名**， + /// 第三档 `auto` 由系统深浅落到对应色板。落盘键仍是 `appearance.theme_mode`。 + Theme(ThemeMode), + /// 外观项改动（设置页「外观」分组 → `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), + /// 折叠 / 展开第一级（版本类型）侧栏（**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), + /// 实例页「启动参数」区的消息（**M157**）：编辑写进页面状态，保存才 dispatch。 + Instances(super::instances::InstanceMessage), + /// 自更新动作（**M159**）：提示条与设置页「更新」区共用一支。 + /// + /// 为什么是顶层变体而不是又一个 `GroupMessage`：更新动作是**跨页的一次性意图** + /// （检查 / 下载安装 / 忽略 / 立即重启），不是某一组的内部状态；设置页的「更新」组也不持有 + /// 任何字段（快照在 presenter 里）。与 M106 的 [`Self::Language`] 同一取舍，偏离已登记在 + /// `pages/settings/update.rs` 的模块文档里。 + Update(UpdateAction), + /// 账户页消息（**M114**：三轨登录 / 列表动作 / 表单输入；app 层翻成 `AppCommand`）。 + /// + /// 与 `Settings` 同一种做法：账户页自己的消息枚举在 `pages/account.rs`，这里只加一支入口。 + Account(crate::pages::account::Message), +} + +/// 自更新的用户动作（M159）。落点是 `app/update/update_action.rs`。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum UpdateAction { + /// 立即检查（手动；会清掉「忽略这个版本」） + CheckNow, + /// 下载 → 校验 → 替换（提示条与设置页共用一个动作） + Apply, + /// 忽略这个版本（本次会话不再弹提示条；设置页仍可手动装） + Dismiss, + /// 立即重启（新版本已就位，重启后生效） + RestartNow, + /// 开关「启动时检查更新」 + SetAutoCheck(bool), +} + +/// 页面动作清单（骨架期够用就行；接线时按业务语义重命名/扩充）。 +#[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..14d4a56 --- /dev/null +++ b/crates/app-iced/src/pages/mod.rs @@ -0,0 +1,368 @@ +//! # 页面层（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 update; + +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(crate) use instances::demo_form as demo_launch_form; +pub use instances::{ + mods_failure_line, mods_from_state, saves_delete_prompt, saves_failure_line, saves_from_state, + InstanceMessage, LaunchForm, Mods, Saves, +}; +pub use layout::{FrameMetrics, PageLayout, PaneKit, WidthClass}; +pub use logs::{Confidence, Finding, Level, Line, Logs, Outcome}; +pub use message::{Action, Message, UpdateAction}; +pub use model::{Detail, Instances, LaunchFacts, Meta, Model, Row}; +pub use screen::Screen; +pub use settings::Language; +pub use update::{Banner, Update, UpdateStatus}; + +use iced::widget::{column, container, row, space}; +use iced::{Element, Length}; + +use unlucky_design::elevation::MaterialLayer; +use unlucky_design::spacing::Space; + +use crate::app::components::motion; +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, + form: &'a instances::LaunchForm, +) -> Element<'a, Message> { + render( + ui, + model, + settings::States { + appearance: None, + groups: settings::demo_groups(), + // harness 路径没有 presenter 快照：空切片 ⇒ 各组画演示行（`Model::settings` 此时是空的）。 + settings: &model.settings, + }, + Language::default(), + form, + ) +} + +/// 同 [`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, + form: &'a instances::LaunchForm, +) -> Element<'a, Message> { + render( + ui, + model, + settings::States { + appearance: Some(appearance), + groups: settings::demo_groups(), + settings: &model.settings, + }, + Language::default(), + form, + ) +} + +/// 产品路径：带上**设置页那份只读状态**（外观运行期状态 + 各组自己的状态）。 +/// +/// 为什么要单独一个入口：组状态的所有者是 `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, + launch_form: &'a instances::LaunchForm, +) -> Element<'a, Message> { + render(ui, model, states, language, launch_form) +} + +fn render<'a>( + ui: &'a Ui, + model: &'a Model, + states: settings::States<'a>, + language: Language, + launch_form: &'a instances::LaunchForm, +) -> Element<'a, Message> { + let metrics = layout::frame_metrics(model.screen.kit(), model.window_width); + + let page = match model.screen { + Screen::Instances => instances::view(ui, metrics, model, launch_form), + // M106：下载页此前写死成 `Lang::En`，现在跟 `model.lang`（页面文案跟着界面语言走）。 + Screen::Download => download::view_sized( + ui, + metrics, + &model.download, + model.lang, + model.window_height, + ), + // M109：内容库页同样跟 `model.lang` + // M161：内容库要按**窗口高度**选版面（矮窗口不能把列表压扁）， + // 正文可用高由 `frame::body_height` 从窗口高减掉外壳算出（唯一来源）。 + Screen::Content => { + content::view(ui, metrics, &model.content, model.lang, model.window_height) + } + // M159：设置页「更新」组要画 presenter 的更新快照（不在 `States` 里，理由见该组文档）。 + Screen::Settings => settings::view(ui, metrics, states, language, &model.update), + Screen::Logs => logs::view(ui, metrics, &model.logs, model.lang), + }; + + // M159：自更新提示条挂在**每一页**的页头之上（有新版 / 正在下载 / 已就位时才出现）。 + // 为什么在这里而不是外壳里：外壳（`shell`）只认窗口装饰与导航，页面层才能按快照决定画什么； + // 而「每一页都要能看见」这条要求又决定了它不能只挂在实例页上。 + let tree: Element<'a, Message> = match update::banner(ui, &model.update, model.lang.catalog()) { + Some(banner) => column![banner, page] + .spacing(ui.space(Space::X3)) + .width(Length::Fill) + .height(Length::Fill) + .into(), + None => page, + }; + + // M192：主体入场（首屏 / 换页 / 列表↔详情）。**这里只采样**——「标识变了就起跑」在 update 侧 + // （`App::sync_motion`）：iced 先算订阅表后建视图，在 view 里插轨道当拍订阅不上（复审 P1-1）。 + // 静息时位移恒为 `(0, 0)`，`shifted` 常驻的那一层零内距，与没有动效时逐像素相同。 + motion::shifted(tree, motion::sample()) +} + +/// 整窗（**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, + form: &'a instances::LaunchForm, +) -> Element<'a, Message> { + app_with_appearance(ui, model, None, form) +} + +/// 同 [`app`]，但可以带上**外观运行期状态**。 +/// +/// `Some(state)` ⇒ 设置页「外观」分组画**真控件**（`pages/appearance/section/`）； +/// `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>, + form: &'a instances::LaunchForm, +) -> Element<'a, Message> { + // harness 路径没有真组状态：用演示状态（[`settings::demo_groups`]），外观状态照传。 + let body = render( + ui, + model, + settings::States { + appearance, + groups: settings::demo_groups(), + settings: &model.settings, + }, + Language::default(), + form, + ); + + 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` 转换）。 +/// +/// 实例 / 下载 / 日志三页带演示数据，设置页仍是占位视觉。 +/// +/// 高度也是模型的一部分（M161）：内容库在矮窗口下要换版面，出图时 `--height` 必须 +/// 真的传进来，否则「矮窗口那几张图」画的是高窗口的版面。 +pub fn demo_model(screen: Screen, window_width: f32, window_height: f32) -> Model { + let mut model = Model::new(screen, window_width, window_height, Some(screen.nav())); + // 出图的中英取证（M222）：`ULL_DL_LANG=zh` 时整页走中文目录。 + // + // 为什么需要这一行：页面文案来自 `model.lang`（`download::view(.., lang)` → `lang.catalog()`）， + // 而 `Model::new` 的 `lang` 写死 `En`、`demo_model` 之前也不碰它——所以 `LC_ALL=zh_CN.UTF-8` + // 对出图**完全无效**（`i18n::detect_env` 不在这条链上，Windows 上平台源还会压过 env）。 + // 只有 harness / 单测走 `demo_model`，产品路径由 `app/view.rs` 从 `AppState` 建模型，零影响。 + let lang = match std::env::var("ULL_DL_LANG").ok().as_deref().map(str::trim) { + Some("zh" | "zh_cn" | "zh-CN" | "zh_CN") => unlucky_i18n::Lang::ZhCn, + _ => unlucky_i18n::Lang::En, + }; + model.lang = lang; + match screen { + Screen::Instances => model.instances = instances::demo(), + Screen::Download => model.download = download::demo(lang.catalog()), + Screen::Content => model.content = content::demo(content::ContentKind::Mod, model.lang), + Screen::Logs => model.logs = logs::demo(model.lang), + // M159：设置页「更新」组的出图夹具（一个可装的新版本 + 一次成功检查）。 + // 只给这一页：其它页的基线图（尤其实例页的启动参数区）不该因为更新提示条而整体下移。 + Screen::Settings => model.update = update::demo(), + } + 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..fbef7b9 --- /dev/null +++ b/crates/app-iced/src/pages/model.rs @@ -0,0 +1,188 @@ +//! 视图模型：**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::update::Update; +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, +} + +/// 元信息卡：标签 + 值（`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, + /// 正文档（演示数据有；真实快照没有对应字段时为 `None`） + pub note: Option, + /// 运行状态行（`None` = 空闲，不占版面） + pub status: Option, + /// 「Play」可用 + pub can_launch: bool, + /// 「Stop」可用 + pub can_stop: bool, + /// 启动参数区的只读事实（M157） + pub launch: LaunchFacts, +} + +/// 启动参数区（M157）的**只读事实**：门槛、生效值、三态词表。 +/// +/// 可编辑的值不在这里——它们在页面状态 [`super::instances::LaunchForm`]（由 `App` 持有）。 +/// 这样「每来一条事件就重建视图模型」不会把用户正在输入的内容冲掉。 +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub struct LaunchFacts { + /// 这个版本能不能下发 `--graphicsBackend`（core 的版本门槛判定）。 + pub allowed: bool, + /// 判定依据的游戏版本（提示文案里给出）。 + pub mc_version: String, + /// 门槛的最低版本（`26.2-snapshot-2`；提示与测试共用一份来源）。 + pub min_version: String, + /// 生效最大堆（三级回落之后）。 + pub memory_effective_mb: u32, + /// 生效 Java（空 = 自动挑）。 + pub java_effective: String, + /// 生效图形后端。 + pub backend_effective: String, + /// 三态词表（`default` / `opengl` / `vulkan`）。 + pub options: Vec, +} + +/// 实例页要画的东西。 +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub struct Instances { + /// 列表列（顺序稳定 = 实例列表顺序） + pub rows: Vec, + /// 当前选中的实例详情（`None` = 没选中 → 空态） + pub detail: Option, +} + +/// 一屏的视图模型。 +#[derive(Debug, Clone, PartialEq)] +pub struct Model { + /// 当前路由落在哪个页面上 + pub screen: Screen, + /// 窗口宽度（**含外壳**：布局档位判据就是它） + pub window_width: f32, + /// 窗口高度（**含外壳**）。 + /// + /// 只有「矮窗口要换版面」这一类判据用它（M161：内容库在低高度下不能把列表压扁）—— + /// 宽度档位仍只看 [`Self::window_width`]。 + pub window_height: f32, + /// 导航轨高亮项（`None` = 没有高亮，如 AI 独立页） + pub active: Option, + /// 实例页的数据（其它三页还是占位视觉，不读） + pub instances: Instances, + /// 下载页的数据（M94：版本列表 / 选中 / 安装进度，全部来自 presenter 快照） + pub download: Download, + /// 日志页的数据（M95：presenter 快照 → 日志行 + 诊断结论，见 [`super::logs`]）。 + pub logs: Logs, + /// 内容库页的数据（M109：检索条件 / 命中项 / 装入闸门，见 [`super::content`]）。 + pub content: Content, + /// 自更新的展示状态（M159：设置页「更新」区 + 顶部提示条，见 [`super::update`]）。 + pub update: Update, + /// **设置组快照**（M201）：presenter 的 `CoreEvent::SettingsChanged` 回流的那一份 + /// （`AppState::settings_groups`，由 `presenter::host::settings::groups` 产出）。 + /// + /// 谁填：`app/view.rs` 的 `model()`（`state.settings_groups.clone()`）。用途只有一处—— + /// 设置页各组的 `body` 按 schema 键从它里面 `dto::find_row` 取**当前值**，画成可改的控件； + /// 写回走 `AppCommand::SetSetting`，落盘后 host 重新发一次 `SettingsChanged` ⇒ 这里换新的一份。 + /// + /// 为什么放在 `Model` 而不是别处：它就是「这一帧要画的设置值」，与 `update` 同一条形状 + /// （页面只认 `Model`，presenter 的快照不直接进页面层）。 + pub settings: Vec, + /// 界面语言（M106）：页面文案走 i18n key，语言由 app 层决定后灌进来。 + /// + /// 谁填：`app/state.rs` 的 `App::refresh_view`（`LangState::lang()` → `view::model(..)`）， + /// 即「用户档位 / 系统 locale → 生效语言」这条链的结论。**不是**基线值：M95 以前这里是 + /// `Lang::En` 占位，M106 之后中文系统上灌进来的是 `Lang::ZhCn`。 + pub lang: Lang, + /// 本地 Mod（M224）：详情页 MODS 区的列表 / 启停（见 [`super::instances::Mods`]）。 + /// + /// 谁填：`app/view/instances.rs` 的 `mods_of`（presenter 的 `AppState::mods` → 展示字段）。 + /// 空态（不在详情页 / 还没请求）是 `Mods::default()`，页面不画这一区。 + pub mods: super::instances::Mods, + /// 存档 / 截图（M235）：详情页 SAVES 区的只读列表（见 [`super::instances::Saves`]）。 + /// + /// 谁填：`app/view/instances.rs` 的 `saves_of`（presenter 的 `AppState::saves` → 展示字段）。 + /// 空态（不在详情页 / 还没请求）是 `Saves::default()`，页面照旧画这一次请求前的样子。 + pub saves: super::instances::Saves, + /// 取证用的强制交互态（`--force-state`）：`Some` 时页面里的控件按该态画。 + /// + /// M90 r2（P3-1）之前这个开关只作用到 `shell` 回退路径，产品页是**静默失效**的； + /// 现在由 `app/view.rs` 把 `cli::ForcedState` 翻成 `Interaction` 灌进模型。 + pub forced: Option, +} + +impl Model { + /// 空模型（只有外壳参数，页面数据全空）——窄窗退化与空态的构造入口。 + pub fn new( + screen: Screen, + window_width: f32, + window_height: f32, + active: Option, + ) -> Self { + Self { + screen, + window_width, + window_height, + active, + instances: Instances::default(), + download: Download::loading(), + logs: Logs::default(), + // 演示模型也从这个空壳起步（`demo_model` 再按页面填数据） + content: super::content::demo(unlucky_presenter::dto::ContentKind::Mod, Lang::En), + update: Update::default(), + // 空快照 = 这一帧没有设置数据（harness / `pages_demo`；`demo_model` 也不伪造一份， + // 见 `pages/settings/download.rs` 的「没有快照就画演示行」）。 + settings: Vec::new(), + mods: super::instances::Mods::default(), + saves: super::instances::Saves::default(), + 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, 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) -> 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::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 { + 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/mod.rs b/crates/app-iced/src/pages/settings/ai/mod.rs new file mode 100644 index 0000000..418b536 --- /dev/null +++ b/crates/app-iced/src/pages/settings/ai/mod.rs @@ -0,0 +1,30 @@ +//! 设置页「助手（AI）」分组（M174）：提供商 / 端点 / 模型 / 密钥 + 「测试连接」。 +//! +//! ## 为什么单独一个目录 +//! +//! `pages/settings/mod.rs` 里只挂一行 `mod ai;`（与 M173 的版面改动不碰面），本组的状态 / 读写 / +//! 渲染 / 用例都在这四个文件里：[`state`]（草稿 + 探测结论 + 校验）、[`store`]（真读写 +//! `config/launcher.json` 的 `ai.*` 五键）、[`view`]（一张卡片）与 `tests`。 +//! +//! ## 三条纪律（本组的全部安全面） +//! +//! 1. **密钥不进 DTO、不进日志、不进错误文案**：草稿是 [`state::Secret`]（`Debug` 手写成掩码）， +//! 落盘走 [`store::save`]（在进程内直接过 `core::setting` 的 schema，**不经过** +//! `AppCommand::SetSetting` 那条可序列化的指令通道——那条通道会把明文带进事件流/日志）； +//! 界面上默认掩码，只有用户点「显示」才明文。已存密钥的**长度**是唯一允许上屏的数值。 +//! 2. **空/非法值不保存**：[`state::State::validate`] 先拦（提供商词表、`http(s)://` 前缀、模型名）， +//! schema 再拦（越界/类型），两次都过才写盘。失败时界面上给的是拒绝原因，不是「已保存」。 +//! 3. **不配置就不可能发请求**：「测试连接」按钮在 [`state::State::can_test`] 为假时是禁用的， +//! 真发不发由 `unlucky_cli::commands::agent::probe` 里的 `to_config()` 再拦一次 +//! （假 provider 构造计数 == 0 的守卫在那里）。 + +pub mod outcome; +pub mod state; +pub mod store; +pub mod view; + +#[cfg(test)] +mod tests; + +pub use outcome::ProbeResult; +pub use state::{Probe, ProviderId, SaveNotice, Secret, State}; diff --git a/crates/app-iced/src/pages/settings/ai/outcome.rs b/crates/app-iced/src/pages/settings/ai/outcome.rs new file mode 100644 index 0000000..817c4a6 --- /dev/null +++ b/crates/app-iced/src/pages/settings/ai/outcome.rs @@ -0,0 +1,197 @@ +//! 「测试连接」的结论（**界面要画的那一份**）：缺项 / 分类 / 目标 / 耗时 / 脱敏详情。 +//! +//! 为什么从 `state.rs` 拆出来：那个文件被 400 行硬线卡着（`components/gate.rs` 的 +//! `every_source_file_stays_under_the_line_limit` 按全仓判红），而这几件是**纯数据 + 翻译**， +//! 与草稿状态机没有耦合。分类判断不在本文件：那是 +//! `unlucky_cli::commands::agent::probe` 的事（四类各有真 TCP 假服务器用例），这里只翻译。 + +use unlucky_i18n::Key; + +/// 缺哪一项（「未配置」时界面上要说清差什么）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum MissingField { + /// 已关闭 / 提供商是 disabled + Disabled, + /// 提供商取值不认识 + Provider, + /// 端点为空 + BaseUrl, + /// 模型名为空 + Model, + /// Anthropic 缺密钥 + ApiKey, +} + +impl MissingField { + /// 界面文案 key。 + #[must_use] + pub const fn label(self) -> Key { + match self { + Self::Disabled => Key::SettingsAiMissingDisabled, + Self::Provider => Key::SettingsAiReasonProvider, + Self::BaseUrl => Key::SettingsAiMissingBaseUrl, + Self::Model => Key::SettingsAiMissingModel, + Self::ApiKey => Key::SettingsAiMissingApiKey, + } + } +} + +/// 「测试连接」的结论大类。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum ProbeKind { + /// 通过 + Passed, + /// 鉴权失败 + Auth, + /// 模型不存在 + ModelNotFound, + /// 端点不可达 + Unreachable, + /// 超时 + Timeout, + /// 其它失败 + Failed, + /// 配置不完整，**没有发请求** + NotConfigured, +} + +impl ProbeKind { + /// 界面文案 key。 + #[must_use] + pub const fn label(self) -> Key { + match self { + Self::Passed => Key::SettingsAiTestPassed, + Self::Auth => Key::SettingsAiTestAuth, + Self::ModelNotFound => Key::SettingsAiTestModel, + Self::Unreachable => Key::SettingsAiTestUnreachable, + Self::Timeout => Key::SettingsAiTestTimeout, + Self::Failed => Key::SettingsAiTestOther, + Self::NotConfigured => Key::SettingsAiTestNotConfigured, + } + } + + /// 是不是「不通」那一类（界面用错误色）。 + #[must_use] + pub const fn is_failure(self) -> bool { + !matches!(self, Self::Passed) + } +} + +/// 一次探测的结论（数值 + 分类 + 脱敏后的详情）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ProbeResult { + /// 大类。 + pub kind: ProbeKind, + /// 未配置时缺的那一项。 + pub missing: Option, + /// 实际请求的端点（`resolved_base_url`）。 + pub base_url: String, + /// 实际请求的模型名。 + pub model: String, + /// 耗时（毫秒）。 + pub elapsed_ms: u128, + /// 脱敏后的原因（可能为空）。 + pub detail: String, +} + +impl ProbeResult { + /// 「测试连接」的结论（`unlucky_cli` 的探测器产出）→ 界面要画的那一份。 + /// + /// 只做**翻译**：分类判断全在 `unlucky_cli::commands::agent::probe`（那边有四条真 TCP 假 + /// 服务器用例逐个钉住），这里不重新猜一遍。`elapsed_ms` 由发起处计时（含建连 + 首 token）。 + #[must_use] + pub fn from_outcome( + outcome: unlucky_cli::commands::agent::probe::ProbeOutcome, + elapsed_ms: u128, + ) -> Self { + use unlucky_cli::commands::agent::probe::{Missing, ProbeOutcome}; + + let missing = match &outcome { + ProbeOutcome::NotConfigured { missing } => Some(match missing { + Missing::Disabled => MissingField::Disabled, + Missing::Provider => MissingField::Provider, + Missing::BaseUrl => MissingField::BaseUrl, + Missing::Model => MissingField::Model, + Missing::ApiKey => MissingField::ApiKey, + }), + _ => None, + }; + // r1 复审 P2-1：**失败也带 target**（端点 + 模型）。以前这里对失败类一律给空串，界面上 + // 就成了「目标： · 模型 …」，用户改完 key 也无法确认改的是不是那一份配置。 + let (kind, target, detail) = match outcome { + ProbeOutcome::NotConfigured { .. } => (ProbeKind::NotConfigured, None, String::new()), + ProbeOutcome::Passed { target } => (ProbeKind::Passed, Some(target), String::new()), + ProbeOutcome::Auth { target, detail } => (ProbeKind::Auth, Some(target), detail), + ProbeOutcome::ModelNotFound { target, detail } => { + (ProbeKind::ModelNotFound, Some(target), detail) + } + ProbeOutcome::Unreachable { target, detail } => { + (ProbeKind::Unreachable, Some(target), detail) + } + ProbeOutcome::Timeout { target, detail } => (ProbeKind::Timeout, Some(target), detail), + ProbeOutcome::Failed { target, detail } => (ProbeKind::Failed, Some(target), detail), + }; + Self { + kind, + missing, + base_url: target + .as_ref() + .map_or_else(String::new, |t| t.base_url.clone()), + model: target.map_or_else(String::new, |t| t.model.clone()), + elapsed_ms, + detail, + } + } + + /// 截图种子（`ULL_AI_STATE`）：**走 [`ProbeResult::from_outcome`] 的同一条路**。 + /// + /// 为什么必须这样（r1 复审 P2-1）：上一版种子直接手填 `ProbeResult` 的字段，于是「失败态 + /// 的目标是空串」这个缺陷只在产品路径上出现，截图永远看不见——**出图不镜像产品路径，等于 + /// 自欺**。现在种子只会伪造「探测结论是什么」，形状（哪些字段有值）由产品那条路决定。 + #[must_use] + pub fn screenshot_seed( + kind: ProbeKind, + base_url: String, + model: String, + elapsed_ms: u128, + ) -> Self { + use unlucky_cli::commands::agent::probe::{ProbeOutcome, Target}; + + let target = Target { base_url, model }; + let detail = "ProviderResponseError: status 401 Unauthorized: {\"error\":{\"message\":\"Incorrect API key provided\"}}"; + let outcome = match kind { + ProbeKind::Passed => ProbeOutcome::Passed { target }, + ProbeKind::Auth => ProbeOutcome::Auth { + target, + detail: detail.to_string(), + }, + ProbeKind::ModelNotFound => ProbeOutcome::ModelNotFound { + target, + detail: detail.to_string(), + }, + ProbeKind::Unreachable => ProbeOutcome::Unreachable { + target, + detail: "Http client error: error sending request".to_string(), + }, + ProbeKind::Timeout => ProbeOutcome::Timeout { + target, + detail: "8 s".to_string(), + }, + ProbeKind::Failed => ProbeOutcome::Failed { + target, + detail: detail.to_string(), + }, + // 未配置态没有 target，也就不该有「测过」的结论：种子里退到「没发请求」。 + ProbeKind::NotConfigured => ProbeOutcome::NotConfigured { + missing: unlucky_cli::commands::agent::probe::Missing::Model, + }, + }; + Self::from_outcome(outcome, elapsed_ms) + } + + /// 失败的三类之外的那几类（`NotConfigured` 没发请求）。 + #[must_use] + pub fn sent_a_request(&self) -> bool { + self.kind != ProbeKind::NotConfigured + } +} diff --git a/crates/app-iced/src/pages/settings/ai/state.rs b/crates/app-iced/src/pages/settings/ai/state.rs new file mode 100644 index 0000000..8525143 --- /dev/null +++ b/crates/app-iced/src/pages/settings/ai/state.rs @@ -0,0 +1,387 @@ +//! 「助手」分组的运行期状态：四条草稿 + 一颗探测结论 + 校验。 +//! +//! 状态住在 `pages::settings::Groups.ai_about`（[`State`]），由 `App` 持有： +//! 用户正在输入的值**不能**放进 `pages::Model`（那个模型每次事件都整棵重建，见 +//! `app/state.rs` 里 `download_draft` 的同一条理由）。 + +use unlucky_i18n::Key; + +use super::outcome::{MissingField, ProbeKind, ProbeResult}; + +/// 四个提供商（值 = `ai.provider` 的词表，真源是 `core::setting::keys::AI_PROVIDERS`， +/// `ai/tests.rs` 里对表）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub enum ProviderId { + /// OpenAI 兼容（含 llama.cpp / LM Studio / DeepSeek / Qwen） + #[default] + OpenAiCompatible, + /// Anthropic 原生 + Anthropic, + /// Ollama 原生 + Ollama, + /// 禁用 + Disabled, +} + +impl ProviderId { + /// 四态（界面上的顺序 = 这张表）。 + pub const ALL: [Self; 4] = [ + Self::OpenAiCompatible, + Self::Anthropic, + Self::Ollama, + Self::Disabled, + ]; + + /// `ai.provider` 的取值。 + #[must_use] + pub const fn setting(self) -> &'static str { + match self { + Self::OpenAiCompatible => "openai_compatible", + Self::Anthropic => "anthropic", + Self::Ollama => "ollama", + Self::Disabled => "disabled", + } + } + + /// 取值 → 四态（未知/空值回落 OpenAI 兼容，与 schema 的默认值同一档）。 + #[must_use] + pub fn from_setting(value: &str) -> Self { + match value.trim() { + "anthropic" => Self::Anthropic, + "ollama" => Self::Ollama, + "disabled" => Self::Disabled, + _ => Self::OpenAiCompatible, + } + } + + /// 该形态有没有统一默认端点（没有 ⇒ base_url 必填）。 + #[must_use] + pub const fn default_base_url(self) -> &'static str { + match self { + Self::OpenAiCompatible => "", + Self::Anthropic => "https://api.anthropic.com", + Self::Ollama => "http://127.0.0.1:11434", + Self::Disabled => "", + } + } + + /// 界面标签 key。 + #[must_use] + pub const fn label(self) -> Key { + match self { + Self::OpenAiCompatible => Key::SettingsAiProviderOpenAi, + Self::Anthropic => Key::SettingsAiProviderAnthropic, + Self::Ollama => Key::SettingsAiProviderOllama, + Self::Disabled => Key::SettingsAiProviderDisabled, + } + } +} + +/// 用户刚输入的密钥草稿：`Debug` 掩码，只有 [`Secret::expose`] 能拿到明文。 +/// +/// 为什么不用裸 `String`：`Groups` / `State` 都 `derive(Debug)`，`App` 里任何一处 `{:?}`（日志、 +/// panic 消息、测试断言失败输出）都会把明文打出来。类型自己守住这一条，比每次记得手写便宜。 +#[derive(Clone, Default, PartialEq, Eq)] +pub struct Secret(String); + +impl Secret { + /// 从输入框的内容构造。 + #[must_use] + pub fn new(value: impl Into) -> Self { + Self(value.into()) + } + + /// 是否空（空白串也算空）。 + #[must_use] + pub fn is_empty(&self) -> bool { + self.0.trim().is_empty() + } + + /// 明文（**只给落盘用**；不要拿它拼任何上屏/日志文本）。 + #[must_use] + pub fn expose(&self) -> &str { + self.0.trim() + } +} + +impl std::fmt::Debug for Secret { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + if self.is_empty() { + f.write_str("Secret(空)") + } else { + f.write_str("Secret(***)") + } + } +} + +/// 设置文件里那一份真值（`ai.*` 五键）。 +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub struct Snapshot { + /// `ai.enabled` + pub enabled: bool, + /// `ai.provider` + pub provider: ProviderId, + /// `ai.base_url` + pub base_url: String, + /// `ai.model` + pub model: String, + /// 已存密钥的字符数（0 = 没存）。**只带长度不带值**：DTO 里不该有密钥。 + pub key_chars: usize, +} + +/// 探测三态。 +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub enum Probe { + /// 还没测 + #[default] + Idle, + /// 正在测 + Running, + /// 测完了 + Done(ProbeResult), +} + +/// 保存结果（用户点「保存」之后的回执）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum SaveNotice { + /// 已落盘 + Saved, + /// 被校验拦下（没写盘） + Refused(Refusal), + /// schema/磁盘拒绝（没写盘） + Failed(String), + /// 设置文件不可用（内存态运行） + NoStorage, +} + +/// 拒绝保存的原因（本地校验，先于 schema）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Refusal { + /// 端点不是 http(s) + BaseUrl, + /// 缺模型名 + Model, +} + +impl Refusal { + /// 界面文案 key。 + #[must_use] + pub const fn label(self) -> Key { + match self { + Self::BaseUrl => Key::SettingsAiReasonBaseUrl, + Self::Model => Key::SettingsAiReasonModel, + } + } +} + +/// 「助手」分组的运行期状态。 +#[derive(Debug)] +pub struct State { + /// `ai.enabled` + pub enabled: bool, + /// `ai.provider` + pub provider: ProviderId, + /// `ai.base_url` 草稿 + pub base_url: String, + /// `ai.model` 草稿 + pub model: String, + /// 新密钥草稿（空 = 不改已存的那把） + pub key: Secret, + /// 已存密钥的字符数（0 = 没存） + pub key_chars: usize, + /// 是否明文显示密钥输入框 + pub reveal: bool, + /// 有未保存的改动 + pub dirty: bool, + /// 设置文件可用（内存态运行时置假：保存与测试都禁用） + pub storage: bool, + /// 上一次保存的回执 + pub notice: Option, + /// 探测结论 + pub probe: Probe, +} + +impl Default for State { + fn default() -> Self { + Self { + enabled: true, + provider: ProviderId::OpenAiCompatible, + base_url: String::new(), + model: String::new(), + key: Secret::default(), + key_chars: 0, + reveal: false, + dirty: false, + storage: false, + notice: None, + probe: Probe::Idle, + } + } +} + +impl State { + /// 用设置文件里的真值重置草稿（**只在没脏的时候**：不许冲掉用户正在输入的内容）。 + /// + /// 返回是否真的改了（调用方据此决定要不要重建视图模型）。 + pub fn hydrate(&mut self, snapshot: Snapshot) -> bool { + self.storage = true; + self.key_chars = snapshot.key_chars; + if self.dirty { + return false; + } + let changed = self.enabled != snapshot.enabled + || self.provider != snapshot.provider + || self.base_url != snapshot.base_url + || self.model != snapshot.model; + self.enabled = snapshot.enabled; + self.provider = snapshot.provider; + self.base_url = snapshot.base_url; + self.model = snapshot.model; + self.keep_probe_if_targeted(); + changed + } + + /// 端点/模型变了之后，「已通过」的旧结论不再是关于现在这套配置的——清掉，免得说谎。 + fn keep_probe_if_targeted(&mut self) { + if let Probe::Done(result) = &self.probe { + if result.base_url != self.resolved_base_url() || result.model != self.model.trim() { + self.probe = Probe::Idle; + } + } + } + + /// 实际生效的端点（空 = 用该形态的默认值）。 + #[must_use] + pub fn resolved_base_url(&self) -> String { + let draft = self.base_url.trim(); + if draft.is_empty() { + self.provider.default_base_url().to_string() + } else { + draft.to_string() + } + } + + /// 配置齐了没有（不齐时「测试连接」禁用，界面上说缺哪一项）。 + #[must_use] + pub fn missing(&self) -> Option { + if !self.enabled || self.provider == ProviderId::Disabled { + return Some(MissingField::Disabled); + } + if self.resolved_base_url().is_empty() { + return Some(MissingField::BaseUrl); + } + if self.model.trim().is_empty() { + return Some(MissingField::Model); + } + if self.provider == ProviderId::Anthropic && self.key.is_empty() && self.key_chars == 0 { + return Some(MissingField::ApiKey); + } + None + } + + /// 现在能不能点「测试连接」。 + #[must_use] + pub fn can_test(&self) -> bool { + self.storage && self.missing().is_none() && !matches!(self.probe, Probe::Running) + } + + /// 状态矩阵的三档（未配置 / 已配置 / 已通过 / 测试失败）。 + #[must_use] + pub fn status(&self) -> Status { + match &self.probe { + Probe::Done(result) if result.kind == ProbeKind::Passed => Status::Verified, + Probe::Done(result) if result.kind.is_failure() => Status::Failed, + _ if self.missing().is_some() => Status::Unconfigured, + _ => Status::Configured, + } + } + + /// 保存前校验（用户输入侧）；过不了就不写盘。 + /// + /// # Errors + /// 端点不是 `http(s)://` 或该形态缺模型名时返回原因。 + pub fn validate(&self) -> Result<(), Refusal> { + if self.provider == ProviderId::Disabled || !self.enabled { + return Ok(()); + } + let base_url = self.resolved_base_url(); + if base_url.is_empty() + || !(base_url.starts_with("http://") || base_url.starts_with("https://")) + { + return Err(Refusal::BaseUrl); + } + if self.model.trim().is_empty() { + return Err(Refusal::Model); + } + Ok(()) + } + + /// 取证开关 `ULL_AI_STATE`（只给 `--screenshot` 用，见 `app/state/construct.rs`）。 + /// + /// 为什么要它：D30 的状态矩阵要出「未配置 / 已配置并测过 / 测试失败」三张图，而真实路径要 + /// 点按钮、要联网。语义与 `ULL_UPDATE_STATE` / `ULL_ACCOUNT_STATE` 一致：只影响这一次进程。 + #[must_use] + pub fn screenshot_seed(raw: &str) -> Option { + let mut state = Self { + storage: true, + ..Self::default() + }; + match raw.trim() { + "unconfigured" => {} + "configured" => { + state.base_url = "https://api.deepseek.com/v1".to_string(); + state.model = "deepseek-chat".to_string(); + state.key_chars = 32; + } + other => { + let kind = match other { + "verified" => ProbeKind::Passed, + "failed-auth" => ProbeKind::Auth, + "failed-model" => ProbeKind::ModelNotFound, + "failed-unreachable" => ProbeKind::Unreachable, + "failed-timeout" => ProbeKind::Timeout, + _ => return None, + }; + state.base_url = "https://api.deepseek.com/v1".to_string(); + state.model = "deepseek-chat".to_string(); + state.key_chars = 32; + // r1 复审 P2-1：种子的**形状**必须由产品路径（`ProbeResult::from_outcome`）决定， + // 这里只伪造「结论是哪一档」。手填 `ProbeResult` 的字段会让「失败态目标为空」 + // 这类缺陷只在产品上出现、截图永远看不见。 + state.probe = Probe::Done(ProbeResult::screenshot_seed( + kind, + state.resolved_base_url(), + state.model.clone(), + 412, + )); + } + } + Some(state) + } +} + +/// 页头的状态档（D30 的状态矩阵：四档各自一句文案 + 一种颜色）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Status { + /// 未配置（缺项，按钮禁用） + Unconfigured, + /// 已配置（还没测或测过但目标改了） + Configured, + /// 连接已通过 + Verified, + /// 测试失败 + Failed, +} + +impl Status { + /// 文案 key。 + #[must_use] + pub const fn label(self) -> Key { + match self { + Self::Unconfigured => Key::SettingsAiStatusUnconfigured, + Self::Configured => Key::SettingsAiStatusConfigured, + Self::Verified => Key::SettingsAiStatusVerified, + Self::Failed => Key::SettingsAiStatusTestFailed, + } + } +} diff --git a/crates/app-iced/src/pages/settings/ai/store.rs b/crates/app-iced/src/pages/settings/ai/store.rs new file mode 100644 index 0000000..40c0f23 --- /dev/null +++ b/crates/app-iced/src/pages/settings/ai/store.rs @@ -0,0 +1,100 @@ +//! 「助手」分组的**真读写**：`config/launcher.json` 的 `ai.enabled` / `ai.provider` / +//! `ai.base_url` / `ai.model` / `ai.api_key` 五键。 +//! +//! ## 为什么在进程内直接过 `SettingStore`，不走 `AppCommand::SetSetting` +//! +//! `AppCommand` 是可序列化的 DTO（`dto/events.rs` 的 `derive(Serialize, Deserialize)`）， +//! 把 `ai.api_key` 塞进去就等于让明文进了「命令通道」——事件日志、调试转储、mock 后端的事件 +//! 回放都会看到它。M174 的守卫①要求密钥**不出进程内**，所以本组写盘走 +//! `core::setting::store::SettingStore`：schema 校验 + 原子写照旧（不自己拼 JSON、不绕 schema）， +//! 只是不经过那条可序列化的通道。这与 `SettingsBridge::persist` 写外观是同一条做法。 +//! +//! ## 为什么每次现读现写 +//! +//! `SettingStore::load` 每次从磁盘读一份（`HostEnv::store()` 也是这个口径），所以「读 → 改 → 存」 +//! 不会用启动时的旧快照盖掉别人刚写的键（AI / `ull config set` 是同一个文件的外部写者）。 + +use std::path::Path; + +use unlucky_core::setting::keys::launcher_schema; +use unlucky_core::setting::store::{SaveOutcome, SettingStore}; + +use super::state::{ProviderId, Snapshot, State}; + +/// 读一份真值。文件缺失/坏掉时 `SettingStore::load` 自己降级，这里只会读到 schema 默认值。 +#[must_use] +pub fn load(path: &Path) -> Snapshot { + let store = SettingStore::load(path, launcher_schema()); + snapshot(store.doc()) +} + +/// 把草稿落盘，返回**落盘后**再读回来的真值（界面据此刷新，而不是相信自己的草稿）。 +/// +/// # Errors +/// schema 拒绝（越界/类型/只读文件）或写盘失败时返回人话（已过 [`super::state::State::validate`]， +/// 所以这里只剩「schema/磁盘」这一类）。 +pub fn save(path: &Path, state: &State) -> Result { + let mut store = SettingStore::load(path, launcher_schema()); + // `Value` 是 `set` 的形参类型：用 `.into()` 让目标类型从签名推出，本 crate 就不必直接依赖 + // `serde_json`（`Cargo.toml` 不在本 mission 的 scope，加依赖要单独走）。 + store + .set("ai.enabled", state.enabled.into()) + .and_then(|()| store.set("ai.provider", state.provider.setting().to_string().into())) + .and_then(|()| store.set("ai.base_url", state.base_url.trim().to_string().into())) + .and_then(|()| store.set("ai.model", state.model.trim().to_string().into())) + .map_err(|error| format!("{error}"))?; + + // 密钥：草稿非空才写（空 = 保留已存的那一把，界面上写着这条规则）。 + if !state.key.is_empty() { + store + .set("ai.api_key", state.key.expose().to_string().into()) + .map_err(|error| format!("{error}"))?; + } + + // **只有 `SaveOutcome::Saved` 算成功**（M174 r2 复审）：`save()` 还有一档 `Skipped(reason)` + // ——只读（`$schema` 认不出 / 文件被更新版本的启动器写过）、不可信文件、没有脏键。旧代码 + // 用 `.is_ok()` 把这一档也当成功，于是「什么都没写进磁盘」在界面上是「已保存」，重启回旧值。 + match store.save() { + Ok(SaveOutcome::Saved(_)) => {} + Ok(SaveOutcome::Skipped(reason)) => { + return Err(format!("未写入磁盘（{}）", skip_reason(reason))); + } + Err(error) => return Err(format!("{error}")), + } + + // 落盘之后**真的从磁盘再读一份**：`store.doc()` 是这次改过的内存视图，它证明不了「文件里 + // 现在是什么」（上面那句注释在 r1 就有，代码却没照做——r2 复审按这句判的）。 + let reloaded = SettingStore::load(path, launcher_schema()); + Ok(snapshot(reloaded.doc())) +} + +/// `SkipReason` → 人话（`core` 的稳定名对用户没意义）。 +fn skip_reason(reason: unlucky_core::setting::store::SkipReason) -> &'static str { + use unlucky_core::setting::store::SkipReason; + match reason { + SkipReason::NotDirty => "没有改动", + SkipReason::ReadOnly => "配置文件只读：它被更新版本的启动器写过，或被标记为不可信", + SkipReason::Unreadable => "配置文件不可信（加载时就降级成只读）", + } +} + +/// 文档 → 快照（密钥只取长度，值不出本函数）。 +fn snapshot(doc: &unlucky_core::setting::document::SettingDocument) -> Snapshot { + let text = |key: &str| doc.effective_str(key).unwrap_or_default().to_string(); + let key_chars = doc + .effective_str("ai.api_key") + .map(str::trim) + .filter(|value| !value.is_empty()) + .map_or(0, |value| value.chars().count()); + Snapshot { + enabled: doc.effective_bool("ai.enabled").unwrap_or(true), + provider: ProviderId::from_setting(&text("ai.provider")), + base_url: text("ai.base_url"), + model: text("ai.model"), + key_chars, + } +} + +#[cfg(test)] +#[path = "store_tests.rs"] +mod tests; diff --git a/crates/app-iced/src/pages/settings/ai/store_tests.rs b/crates/app-iced/src/pages/settings/ai/store_tests.rs new file mode 100644 index 0000000..293e016 --- /dev/null +++ b/crates/app-iced/src/pages/settings/ai/store_tests.rs @@ -0,0 +1,211 @@ +//! [`super`] 的用例：真读写五键 + 密钥只留长度 + 非法值不落盘 + 外观写回不盖 AI 键。 +//! +//! | 用例 | 守什么 | 变异 | +//! |---|---|---| +//! | `five_keys_round_trip` | 四项 + 密钥都真的落进 `launcher.json` | 少写一个键 / 写错键名 | +//! | `snapshot_only_reports_key_length` | 快照里没有密钥值，只有长度 | 把 `api_key` 值放进 `Snapshot` | +//! | `empty_draft_keeps_the_stored_key` | 密钥输入框留空 = 保留旧密钥 | 无条件写空串覆盖 | +//! | `schema_rejects_and_nothing_is_written` | 非法值不保存 | 忽略 `set` 的 `Err` 直接 `save` | +//! | `external_edit_is_read_back` | 现读现写（别人的改动不被旧快照盖掉） | 缓存在内存里不回读 | +//! | `appearance_write_back_keeps_the_ai_keys` | **用户场景**：存完 AI 再改主题，值还在 | 两处任一方不重读 | +//! | `read_only_config_is_reported_as_a_failure` | 只读配置上保存**不许**报成功 | `save()` 恒返回 Ok | + +use std::path::PathBuf; + +use super::{load, save}; +use crate::pages::settings::ai::state::{ProviderId, Secret, State}; + +fn temp_config(label: &str) -> PathBuf { + let dir = std::env::temp_dir().join(format!( + "ull-ai-store-{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 +} + +fn draft() -> State { + State { + enabled: true, + provider: ProviderId::Anthropic, + base_url: "https://api.anthropic.com".to_string(), + model: "claude-sonnet-4".to_string(), + key: Secret::new("sk-ant-secret"), + dirty: true, + storage: true, + ..State::default() + } +} + +#[test] +fn five_keys_round_trip() { + let path = temp_config("roundtrip"); + let saved = save(&path, &draft()).expect("应当能保存"); + assert_eq!(saved.provider, ProviderId::Anthropic); + assert_eq!(saved.base_url, "https://api.anthropic.com"); + assert_eq!(saved.model, "claude-sonnet-4"); + assert_eq!(saved.key_chars, "sk-ant-secret".chars().count()); + + // 文件里真的是这五个键（不是我们内存里的对象）。 + let text = std::fs::read_to_string(&path).expect("读文件"); + assert!( + text.contains("\"base_url\": \"https://api.anthropic.com\""), + "{text}" + ); + assert!(text.contains("\"model\": \"claude-sonnet-4\""), "{text}"); + assert!(text.contains("\"provider\": \"anthropic\""), "{text}"); + assert!(text.contains("\"api_key\": \"sk-ant-secret\""), "{text}"); + + // 新开一份读回来（= 重启语义）。 + let reloaded = load(&path); + assert_eq!(reloaded, saved); + std::fs::remove_dir_all(path.parent().unwrap().parent().unwrap()).ok(); +} + +#[test] +fn snapshot_only_reports_key_length() { + let path = temp_config("length"); + let saved = save(&path, &draft()).expect("保存"); + // `Snapshot` 里唯一与密钥有关的字段是长度：类型上就没有 `String` 可以装明文。 + let printed = format!("{saved:?}"); + assert!( + !printed.contains("sk-ant-secret"), + "快照泄漏密钥：{printed}" + ); + assert_eq!(saved.key_chars, "sk-ant-secret".len()); + std::fs::remove_dir_all(path.parent().unwrap().parent().unwrap()).ok(); +} + +#[test] +fn empty_draft_keeps_the_stored_key() { + let path = temp_config("keep-key"); + save(&path, &draft()).expect("先存一把"); + let mut next = draft(); + next.key = Secret::default(); + next.model = "claude-opus-4".to_string(); + let saved = save(&path, &next).expect("再存一次（密钥留空）"); + assert_eq!(saved.model, "claude-opus-4"); + assert_eq!( + saved.key_chars, + "sk-ant-secret".chars().count(), + "密钥输入框留空时必须保留旧密钥" + ); + std::fs::remove_dir_all(path.parent().unwrap().parent().unwrap()).ok(); +} + +#[test] +fn schema_rejects_and_nothing_is_written() { + let path = temp_config("reject"); + save(&path, &draft()).expect("先存一份合法的"); + let before = std::fs::read_to_string(&path).expect("读文件"); + + // `ai.model` 的上限是 128 字符：越界的值必须被 schema 拒绝，**且文件不动**。 + let mut bad = draft(); + bad.model = "m".repeat(400); + bad.base_url = "https://example.invalid/v1".to_string(); + let error = save(&path, &bad).expect_err("越界模型名必须被拒"); + assert!(!error.is_empty()); + let after = std::fs::read_to_string(&path).expect("读文件"); + assert_eq!(before, after, "被拒绝的保存不该改动文件：{after}"); + std::fs::remove_dir_all(path.parent().unwrap().parent().unwrap()).ok(); +} + +#[test] +fn external_edit_is_read_back() { + let path = temp_config("external"); + save(&path, &draft()).expect("先存一份"); + // 外部写者（`ull config set ai.model …`）改一个键：我们不缓存，下一次读就是新值。 + std::fs::write( + &path, + r#"{"ai":{"enabled":true,"provider":"ollama","base_url":"http://127.0.0.1:11434","model":"llama3.1"}}"#, + ) + .expect("写文件"); + let reloaded = load(&path); + assert_eq!(reloaded.provider, ProviderId::Ollama); + assert_eq!(reloaded.model, "llama3.1"); + assert_eq!(reloaded.key_chars, 0, "外部把 api_key 删了，长度就该是 0"); + std::fs::remove_dir_all(path.parent().unwrap().parent().unwrap()).ok(); +} + +/// **P2-4 的用户场景原样**（r1 复审要求的用例）：设置页保存 AI 配置 → 同一秒内改主题 → 值还在。 +/// +/// 这一条与 `presenter/src/settings_bridge.rs` 的 `persist_keeps_keys_another_writer_just_saved` +/// 守的是同一个缺陷，但从**产品的两个写者**出发：`ai::store::save`（现读现写）与 +/// `SettingsBridge::persist`（长生命 store + 写前 reload）。任一方少了「写前现读」，这条红。 +#[test] +fn appearance_write_back_keeps_the_ai_keys() { + use unlucky_presenter::prefs::{AppearancePrefs, ThemeMode}; + use unlucky_presenter::settings_bridge::SettingsBridge; + + let path = temp_config("appearance-keeps-ai"); + // 外观桥先加载过一份文件（它的 store 就是从这里开始的旧快照）。 + let mut bridge = SettingsBridge::with_path(&path); + bridge.persist(&AppearancePrefs::factory(), ThemeMode::Light); + + // 用户在「助手」页保存配置（真落盘、含密钥）。 + let mut draft = draft(); + draft.key = Secret::new("sk-must-survive"); + save(&path, &draft).expect("保存 AI 配置"); + + // 紧接着用户去「外观」改主题（外观桥写回它那份整文档）。 + bridge.persist(&AppearancePrefs::factory(), ThemeMode::Dark); + + let text = std::fs::read_to_string(&path).expect("读文件"); + assert!( + text.contains("sk-must-survive"), + "密钥被外观写回盖掉了：{text}" + ); + assert!(text.contains("claude-sonnet-4"), "模型名也被盖掉了：{text}"); + assert_eq!(load(&path).key_chars, "sk-must-survive".chars().count()); + std::fs::remove_dir_all(path.parent().unwrap().parent().unwrap()).ok(); +} + +/// **P2-1（r2）第二条**：只读配置上的保存必须报**失败**，而不是「已保存」。 +/// +/// 现场：`$schema` 认不出（或文件被更新版本的启动器写过）⇒ `FileAccess::ReadOnly`。 +/// `SettingStore::save` 在这种文件上会 `Skipped(ReadOnly)`（**不是** Err），旧代码用 `.is_ok()` +/// 判定，于是「什么都没写进磁盘」在界面上是「已保存」，重启回旧值。 +/// +/// 抓得住：①把 `save()` 的 `SaveOutcome` 分支去掉（恒返回 Ok）；②把只读档当成功。 +/// 抓不住：`Skipped` 分支自身的文案（见 [`super::skip_reason`] 的单测）。 +#[test] +fn read_only_config_is_reported_as_a_failure() { + let path = temp_config("read-only"); + // `Invalid` 兼容档（`$schema` 前缀认不出）⇒ `FileAccess::ReadOnly`：值照读，不许改写。 + std::fs::write( + &path, + r#"{"$schema":"https://example.invalid/ull/launcher/9.9.9","ai":{"model":"keep-me"}}"#, + ) + .expect("写配置"); + let before = std::fs::read_to_string(&path).expect("读配置"); + + let error = save(&path, &draft()).expect_err("只读配置上的保存必须报失败"); + assert!( + error.contains("只读") || error.contains("只读文件") || error.contains("9.9.9"), + "错误文案要说得清为什么没写：{error}" + ); + assert_eq!( + std::fs::read_to_string(&path).expect("读配置"), + before, + "被只读闸门拦下的保存不许改动文件" + ); + std::fs::remove_dir_all(path.parent().unwrap().parent().unwrap()).ok(); +} + +/// `skip_reason` 的三档都有人话（`Skipped` 不许被静默当成成功）。 +#[test] +fn skip_reasons_are_named() { + use super::skip_reason; + use unlucky_core::setting::store::SkipReason; + + for reason in [ + SkipReason::NotDirty, + SkipReason::ReadOnly, + SkipReason::Unreadable, + ] { + assert!(!skip_reason(reason).is_empty(), "{reason:?} 没有文案"); + } +} diff --git a/crates/app-iced/src/pages/settings/ai/tests.rs b/crates/app-iced/src/pages/settings/ai/tests.rs new file mode 100644 index 0000000..9bef712 --- /dev/null +++ b/crates/app-iced/src/pages/settings/ai/tests.rs @@ -0,0 +1,390 @@ +//! 「助手」分组状态机的用例（M174）。 +//! +//! | 用例 | 守什么 | 变异（改成什么会红） | +//! |---|---|---| +//! | `provider_vocabulary_is_the_schema_vocabulary` | 四个取值 == `core::setting::keys::AI_PROVIDERS` | 词表里写 `open_ai_compatible` | +//! | `secret_debug_is_masked` | 密钥不进 `{:?}` | 把 `Secret` 改成 `String` | +//! | `validate_refuses_bad_endpoint_and_empty_model` | 空/非法值不保存 | 删掉 `starts_with("http")` 检查 | +//! | `missing_names_exactly_one_field` | 「未配置」说清缺哪一项 | 所有缺项都返回 `BaseUrl` | +//! | `can_test_is_false_until_configured` | 未配置时按钮禁用 | `can_test` 恒 `true` | +//! | `dirty_draft_is_not_overwritten` | 外部改动不冲掉用户输入 | `hydrate` 先无条件赋值 | +//! | `saving_a_new_target_drops_the_old_pass` | 端点/模型变了，旧「已通过」作废 | `keep_probe_if_targeted` 删掉 | +//! | `not_configured_outcome_carries_no_target` | 「没发请求」的结论里没有目标/详情 | 把 `ProbeOutcome::NotConfigured` 当失败类 | + +use unlucky_core::setting::keys::AI_PROVIDERS; +use unlucky_i18n::{Catalog, Lang}; + +use super::outcome::{MissingField, ProbeKind, ProbeResult}; +use super::state::{Probe, ProviderId, Refusal, Secret, Snapshot, State, Status}; + +fn configured() -> State { + State { + enabled: true, + provider: ProviderId::OpenAiCompatible, + base_url: "https://api.deepseek.com/v1".to_string(), + model: "deepseek-chat".to_string(), + key: Secret::new("sk-test"), + key_chars: 0, + dirty: false, + storage: true, + ..State::default() + } +} + +#[test] +fn provider_vocabulary_is_the_schema_vocabulary() { + let ours: Vec<&str> = ProviderId::ALL.iter().map(|id| id.setting()).collect(); + assert_eq!( + ours, AI_PROVIDERS, + "四个取值必须与 schema 的允许值表逐条相等" + ); + for id in ProviderId::ALL { + assert_eq!(ProviderId::from_setting(id.setting()), id); + } + // 未知值回落 OpenAI 兼容（与 schema 默认值同一档），不是 panic 也不是禁用。 + assert_eq!( + ProviderId::from_setting("open_ai_compatible"), + ProviderId::OpenAiCompatible + ); +} + +#[test] +fn secret_debug_is_masked() { + let secret = Secret::new("sk-live-LEAK-MARKER"); + let printed = format!("{secret:?}"); + assert!(!printed.contains("sk-live"), "Debug 漏了密钥：{printed}"); + assert!(printed.contains("***"), "应当显示掩码：{printed}"); + // 空草稿的 Debug 也要能分辨（否则「留空 = 保留旧密钥」这条规则在日志里看不出）。 + assert!(format!("{:?}", Secret::default()).contains("空")); + assert!(Secret::new(" ").is_empty()); +} + +/// **P2-2**：`Message::EditKey` 的 `Debug` 不许把密钥打进日志。 +/// +/// 现场（r1 复审）：载荷是裸 `String`，而 harness / 断言失败输出会把页面消息 `{:?}` 打出来 ⇒ +/// 明文 key 进 stderr 与 CI 日志。载荷改成 [`Secret`] 之后由它自己的 `Debug` 兜住。 +/// +/// 抓得住：谁把 `EditKey(String)` 改回去（`Secret` 的 Debug 掩码见 [`secret_debug_is_masked`]）。 +#[test] +fn the_key_message_never_prints_the_key() { + use crate::pages::settings::ai_about::Message; + + const SECRET: &str = "sk-live-MSG-LEAK-7c2f"; + let message = Message::EditKey(Secret::new(SECRET)); + let printed = format!("{message:?}"); + assert!( + !printed.contains(SECRET), + "页面消息的 Debug 泄漏了密钥（它会进日志/CI 输出）：{printed}" + ); + assert!(printed.contains("***"), "应当看得见掩码标记：{printed}"); + + // 整条投递口（`pages::Message`）也一样：它才是真的被一层层 `{:?}` 的那个类型。 + let page = + crate::pages::Message::Settings(crate::pages::settings::GroupMessage::AiAbout(message)); + let printed = format!("{page:?}"); + assert!( + !printed.contains(SECRET), + "页面消息漏斗泄漏了密钥：{printed}" + ); +} + +#[test] +fn validate_refuses_bad_endpoint_and_empty_model() { + let mut state = configured(); + assert_eq!(state.validate(), Ok(())); + + state.base_url = "api.deepseek.com/v1".to_string(); + assert_eq!( + state.validate(), + Err(Refusal::BaseUrl), + "没有协议头不算端点" + ); + + state.base_url = String::new(); + assert_eq!( + state.validate(), + Err(Refusal::BaseUrl), + "OpenAI 兼容形态没有默认端点，空值必须拒绝（不保存）" + ); + + state.base_url = "https://api.deepseek.com/v1".to_string(); + state.model = " ".to_string(); + assert_eq!(state.validate(), Err(Refusal::Model)); + + // Ollama 有默认端点：空 base_url 是合法的（生效值回落默认）。 + state.provider = ProviderId::Ollama; + state.base_url = String::new(); + state.model = "llama3".to_string(); + assert_eq!(state.validate(), Ok(())); + assert_eq!(state.resolved_base_url(), "http://127.0.0.1:11434"); + + // 禁用档：什么都不填也能保存（那正是「关掉助手」）。 + state.provider = ProviderId::Disabled; + state.model = String::new(); + assert_eq!(state.validate(), Ok(())); +} + +#[test] +fn missing_names_exactly_one_field() { + let mut state = configured(); + assert_eq!(state.missing(), None); + + state.enabled = false; + assert_eq!(state.missing(), Some(MissingField::Disabled)); + + let mut state = configured(); + state.base_url = String::new(); + assert_eq!(state.missing(), Some(MissingField::BaseUrl)); + + let mut state = configured(); + state.model = String::new(); + assert_eq!(state.missing(), Some(MissingField::Model)); + + // Anthropic 必须带密钥：草稿空 + 已存 0 字符 = 缺密钥。 + let mut state = configured(); + state.provider = ProviderId::Anthropic; + state.base_url = String::new(); + state.model = "claude-sonnet-4".to_string(); + state.key = Secret::default(); + state.key_chars = 0; + assert_eq!(state.missing(), Some(MissingField::ApiKey)); + // 已存过密钥（只有长度，没有值）就算配置齐了。 + state.key_chars = 40; + assert_eq!(state.missing(), None); +} + +#[test] +fn can_test_is_false_until_configured() { + let mut state = configured(); + assert!(state.can_test()); + + state.model = String::new(); + assert!(!state.can_test(), "缺模型名时「测试连接」必须禁用"); + + let mut state = configured(); + state.storage = false; + assert!(!state.can_test(), "没有设置文件时也禁用"); + + let mut state = configured(); + state.probe = Probe::Running; + assert!(!state.can_test(), "正在测的时候不许再点一次"); +} + +#[test] +fn dirty_draft_is_not_overwritten() { + let mut state = configured(); + state.base_url = "https://typed.example/v1".to_string(); + state.dirty = true; + let changed = state.hydrate(Snapshot { + enabled: true, + provider: ProviderId::Ollama, + base_url: "http://127.0.0.1:11434".to_string(), + model: "llama3".to_string(), + key_chars: 12, + }); + assert!(!changed); + assert_eq!( + state.base_url, "https://typed.example/v1", + "脏草稿不许被冲掉" + ); + assert_eq!(state.provider, ProviderId::OpenAiCompatible); + // 密钥长度不属于草稿：外部改了密钥，长度照样要更新（界面上的「已存 N 字符」不能骗人）。 + assert_eq!(state.key_chars, 12); + + // 不脏的时候照常灌入。 + let mut state = State::default(); + let changed = state.hydrate(Snapshot { + enabled: true, + provider: ProviderId::Ollama, + base_url: "http://127.0.0.1:11434".to_string(), + model: "llama3".to_string(), + key_chars: 0, + }); + assert!(changed); + assert_eq!(state.provider, ProviderId::Ollama); + assert!(state.storage, "灌过真值之后设置文件就是可用的"); +} + +#[test] +fn saving_a_new_target_drops_the_old_pass() { + let mut state = configured(); + state.probe = Probe::Done(ProbeResult { + kind: ProbeKind::Passed, + missing: None, + base_url: state.resolved_base_url(), + model: state.model.clone(), + elapsed_ms: 120, + detail: String::new(), + }); + assert_eq!(state.status(), Status::Verified); + + // 同一个目标重复灌入：结论仍然有效。 + let snapshot = Snapshot { + enabled: true, + provider: state.provider, + base_url: state.base_url.clone(), + model: state.model.clone(), + key_chars: 0, + }; + state.hydrate(snapshot); + assert_eq!( + state.status(), + Status::Verified, + "目标没变，别无故作废旧结论" + ); + + // 换了端点：旧结论不再关于现在这套配置。 + state.dirty = false; + state.hydrate(Snapshot { + enabled: true, + provider: ProviderId::OpenAiCompatible, + base_url: "https://other.example/v1".to_string(), + model: "deepseek-chat".to_string(), + key_chars: 0, + }); + assert_eq!(state.probe, Probe::Idle, "目标变了，旧「已通过」必须作废"); + assert_eq!(state.status(), Status::Configured); +} + +/// **P2-1**：失败结论必须带着「对哪个端点 / 哪个模型」，只有「没发请求」才允许没有 target。 +/// +/// 抓得住：`ProbeResult::from_outcome` 又把失败类的 target 丢掉（那正是 r1 复审的缺陷—— +/// 界面上显示成「目标： · 模型 …」，而截图因为走的是手填种子看不见它）。 +#[test] +fn failures_carry_the_target_that_was_dialed() { + use unlucky_cli::commands::agent::probe::{Missing, ProbeOutcome, Target}; + + let target = || Target { + base_url: "https://api.deepseek.com/v1".to_string(), + model: "deepseek-chat".to_string(), + }; + + let not_configured = ProbeResult::from_outcome( + ProbeOutcome::NotConfigured { + missing: Missing::Model, + }, + 0, + ); + assert_eq!(not_configured.kind, ProbeKind::NotConfigured); + assert_eq!(not_configured.missing, Some(MissingField::Model)); + assert!(not_configured.base_url.is_empty(), "没发请求就没有目标地址"); + assert!(not_configured.model.is_empty()); + assert!(!not_configured.sent_a_request()); + + for (outcome, expected) in [ + ( + ProbeOutcome::Auth { + target: target(), + detail: "401".to_string(), + }, + ProbeKind::Auth, + ), + ( + ProbeOutcome::ModelNotFound { + target: target(), + detail: "404".to_string(), + }, + ProbeKind::ModelNotFound, + ), + ( + ProbeOutcome::Unreachable { + target: target(), + detail: "refused".to_string(), + }, + ProbeKind::Unreachable, + ), + ( + ProbeOutcome::Timeout { + target: target(), + detail: "8 s".to_string(), + }, + ProbeKind::Timeout, + ), + ( + ProbeOutcome::Failed { + target: target(), + detail: "?".to_string(), + }, + ProbeKind::Failed, + ), + (ProbeOutcome::Passed { target: target() }, ProbeKind::Passed), + ] { + let result = ProbeResult::from_outcome(outcome, 5); + assert_eq!(result.kind, expected); + assert_eq!( + result.base_url, "https://api.deepseek.com/v1", + "{expected:?}" + ); + assert_eq!(result.model, "deepseek-chat", "{expected:?}"); + if expected != ProbeKind::Passed { + assert!(result.sent_a_request()); + } + } +} + +#[test] +fn screenshot_seed_covers_the_state_matrix() { + // 未配置 / 已配置 / 已通过 / 失败四档都要能出图（D30 的矩阵）。 + let unconfigured = State::screenshot_seed("unconfigured").expect("种子"); + assert_eq!(unconfigured.status(), Status::Unconfigured); + assert!(unconfigured.storage, "截图里也要如实显示「有设置文件」"); + + let configured = State::screenshot_seed("configured").expect("种子"); + assert_eq!(configured.status(), Status::Configured); + assert_eq!(configured.model, "deepseek-chat"); + + let verified = State::screenshot_seed("verified").expect("种子"); + assert_eq!(verified.status(), Status::Verified); + + let failed = State::screenshot_seed("failed-auth").expect("种子"); + assert_eq!(failed.status(), Status::Failed); + // P2-1：种子的**形状**要走产品路径（`ProbeResult::from_outcome`），所以失败态也带 target。 + // 上一版种子手填字段、把 target 填满，于是「产品上失败态目标是空串」这个缺陷截图看不见。 + if let Probe::Done(result) = &failed.probe { + assert_eq!(result.base_url, "https://api.deepseek.com/v1"); + assert_eq!(result.model, "deepseek-chat"); + assert!(!result.detail.is_empty(), "失败态应当带一句脱敏详情"); + } else { + panic!("失败种子没带上探测结论"); + } + assert!( + State::screenshot_seed("nonsense").is_none(), + "未知种子不伪造状态" + ); +} + +#[test] +fn every_key_used_here_exists_in_the_catalog() { + // 中英各一遍，逐条取词：目录里没这条 key 就编译不过（`Key` 是枚举）， + // 但**译文为空**这件事只有这里抓得住。 + let mut keys: Vec = ProviderId::ALL.iter().map(|id| id.label()).collect(); + keys.extend([ + MissingField::Disabled.label(), + MissingField::Provider.label(), + MissingField::BaseUrl.label(), + MissingField::Model.label(), + MissingField::ApiKey.label(), + Refusal::BaseUrl.label(), + Refusal::Model.label(), + Status::Unconfigured.label(), + Status::Configured.label(), + Status::Verified.label(), + Status::Failed.label(), + ProbeKind::Passed.label(), + ProbeKind::Auth.label(), + ProbeKind::ModelNotFound.label(), + ProbeKind::Unreachable.label(), + ProbeKind::Timeout.label(), + ProbeKind::Failed.label(), + ProbeKind::NotConfigured.label(), + ]); + for lang in [Lang::ZhCn, Lang::En] { + let catalog = Catalog::of(lang); + for key in &keys { + assert!( + !catalog.text(*key).trim().is_empty(), + "{key:?} 在 {lang:?} 下没有译文" + ); + } + } +} diff --git a/crates/app-iced/src/pages/settings/ai/view.rs b/crates/app-iced/src/pages/settings/ai/view.rs new file mode 100644 index 0000000..542ea6f --- /dev/null +++ b/crates/app-iced/src/pages/settings/ai/view.rs @@ -0,0 +1,360 @@ +//! 「助手」分组的一张卡片（M174）。 +//! +//! ## 版面（D30 的状态矩阵 + 数值） +//! +//! | 行 | 内容 | 数值 | +//! |---|---|---| +//! | 状态 | 未配置 / 已配置 / 连接已通过 / 测试失败 | 生效端点 + 模型名 | +//! | 开关 | 启用助手（`ai.enabled`） | — | +//! | 提供商 | 四态 filter chip（`ai.provider`） | 存的值 | +//! | 端点 | `base_url` 文本框 | 生效值（空 = 该形态默认） | +//! | 模型 | `ai.model` 文本框 | — | +//! | 密钥 | 密码框（默认掩码）+「显示」 | **只显示字符数**，不显示值 | +//! | 动作 | 保存 / 测试连接 | 测试结论带耗时（毫秒） | +//! +//! 「未配置」时「测试连接」是**禁用**的，并在下面直接说清缺哪一项——不是灰着什么都不说。 + +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::inputs::{text_field, Field, FieldVariant}; +use crate::app::components::selection::{chip, switch, Chip, Switch}; +use crate::pages::frame::{card, divider, text_role_owned}; +use crate::pages::settings::ai::outcome::ProbeKind; +use crate::pages::settings::ai::state::{Probe, ProviderId, SaveNotice, Secret, State, Status}; +use crate::pages::settings::{ai_about, GroupMessage, States}; +use crate::pages::Message; +use crate::theme::Ui; + +/// 一条本组消息 → 页面消息（左列/正文都用这一处，别在下面各写一遍）。 +fn msg(message: ai_about::Message) -> Message { + Message::Settings(GroupMessage::AiAbout(message)) +} + +/// 一张卡片（`pages::settings::form` 按下标把 `Lang` 递进来，见 `settings/mod.rs`）。 +pub(crate) fn body<'a>(ui: &'a Ui, states: States<'a>, lang: Lang) -> Element<'a, Message> { + body_of(ui, &states.groups.ai_about, lang) +} + +fn body_of<'a>(ui: &'a Ui, state: &'a State, lang: Lang) -> Element<'a, Message> { + let catalog = lang.catalog(); + let mut stacked = column![].spacing(ui.space(Space::X2)).width(Length::Fill); + + stacked = stacked.push(status_row(ui, catalog, state)); + stacked = stacked.push(divider(ui)); + stacked = stacked.push(enable_row(ui, catalog, state)); + stacked = stacked.push(divider(ui)); + stacked = stacked.push(provider_row(ui, catalog, state)); + stacked = stacked.push(divider(ui)); + stacked = stacked.push(endpoint_field(ui, catalog, state)); + stacked = stacked.push(model_field(ui, catalog, state)); + stacked = stacked.push(key_field(ui, catalog, state)); + stacked = stacked.push(divider(ui)); + stacked = stacked.push(actions_row(ui, catalog, state)); + stacked = stacked.push(hint_line(ui, catalog, state)); + + if let Some(notice) = &state.notice { + stacked = stacked.push(notice_line(ui, catalog, notice)); + } + if let Probe::Done(result) = &state.probe { + stacked = stacked.push(probe_line(ui, catalog, result.kind)); + // 目标行只在真有值时才画（r1 复审 P2-1 的第二道保险）：失败类现在**都会**带上 target， + // 但「没发请求」与将来的新档可能没有；空着画出来就是「目标： · 模型 · N 毫秒」。 + if !(result.base_url.is_empty() && result.model.is_empty()) { + stacked = stacked.push(text_role_owned( + ui, + TypeRole::BodySmall, + false, + catalog.render( + Key::SettingsAiTestTarget, + &[ + ("base_url", result.base_url.as_str()), + ("model", result.model.as_str()), + ("ms", result.elapsed_ms.to_string().as_str()), + ], + ), + ui.color(Role::OnSurfaceVariant), + )); + } + if !result.detail.trim().is_empty() { + stacked = stacked.push(text_role_owned( + ui, + TypeRole::BodySmall, + false, + catalog.render( + Key::SettingsAiTestDetail, + &[("detail", result.detail.as_str())], + ), + ui.color(Role::OnSurfaceVariant), + )); + } + } + + card(ui, stacked) +} + +/// 状态行：四档文案 + 生效端点 / 模型（数值直接上屏，不藏在提示里）。 +fn status_row<'a>(ui: &'a Ui, catalog: Catalog, state: &State) -> Element<'a, Message> { + let status = state.status(); + let color = match status { + Status::Failed => ui.color(Role::Error), + Status::Verified => ui.color(Role::Primary), + _ => ui.color(Role::OnSurfaceVariant), + }; + let target = if state.model.trim().is_empty() { + state.resolved_base_url() + } else { + format!("{} · {}", state.resolved_base_url(), state.model.trim()) + }; + let line = catalog.render( + Key::SettingsAiStatusLabel, + &[("status", catalog.text(status.label()))], + ); + row![ + container(text_role_owned(ui, TypeRole::BodyMedium, true, line, color)).width(Length::Fill), + text_role_owned(ui, TypeRole::BodySmall, false, target, color), + ] + .width(Length::Fill) + .align_y(Alignment::Center) + .into() +} + +fn enable_row<'a>(ui: &'a Ui, catalog: Catalog, state: &State) -> Element<'a, Message> { + column![ + switch( + ui, + Switch::new( + catalog.text(Key::SettingsAiEnable), + state.enabled, + msg(ai_about::Message::ToggleEnabled(!state.enabled)), + ), + ), + text_role_owned( + ui, + TypeRole::BodySmall, + false, + catalog.text(Key::SettingsAiEnableHint).to_string(), + ui.color(Role::OnSurfaceVariant), + ), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill) + .into() +} + +fn provider_row<'a>(ui: &'a Ui, catalog: Catalog, state: &State) -> Element<'a, Message> { + // `.wrap()`：四颗 chip 在 424 宽的正文列里放不下一行时**整颗换行**，而不是把最后一颗 + // 压成竖排（「已禁 / 用」那种断字）。`Wrapping` 只提供 `push`，所以先建后 wrap。 + let mut chips = row![] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Center); + for provider in ProviderId::ALL { + chips = chips.push(chip( + ui, + Chip::filter( + catalog.text(provider.label()), + state.provider == provider, + msg(ai_about::Message::PickProvider(provider)), + ), + )); + } + row![ + text_role_owned( + ui, + TypeRole::BodySmall, + false, + catalog.text(Key::SettingsAiProviderLabel).to_string(), + ui.color(Role::OnSurfaceVariant), + ), + chips.wrap(), + ] + .spacing(ui.space(Space::X2)) + .width(Length::Fill) + .align_y(Alignment::Center) + .into() +} + +fn endpoint_field<'a>(ui: &'a Ui, catalog: Catalog, state: &'a State) -> Element<'a, Message> { + let field = Field::new(&state.base_url) + .variant(FieldVariant::Outlined) + .label(catalog.text(Key::SettingsAiBaseUrl)) + .placeholder(catalog.text(Key::SettingsAiBaseUrlPlaceholder)) + .supporting(catalog.text(Key::SettingsAiBaseUrlHint)); + // 「生效：…」只在**回落默认值**（草稿为空、该形态有默认端点）时才值得说一句： + // 草稿就是生效值时它是废话，空着且没有默认值时它是空串（比不说更糟）。 + let effective = state.resolved_base_url(); + let mut block = column![text_field(ui, field, |value| msg( + ai_about::Message::EditBaseUrl(value) + ))] + .spacing(ui.space(Space::X1)) + .width(Length::Fill); + if !effective.is_empty() && effective != state.base_url.trim() { + block = block.push(text_role_owned( + ui, + TypeRole::BodySmall, + false, + catalog.render(Key::SettingsAiEffective, &[("value", effective.as_str())]), + ui.color(Role::OnSurfaceVariant), + )); + } + block.into() +} + +fn model_field<'a>(ui: &'a Ui, catalog: Catalog, state: &'a State) -> Element<'a, Message> { + let field = Field::new(&state.model) + .variant(FieldVariant::Outlined) + .label(catalog.text(Key::SettingsAiModel)) + .placeholder(catalog.text(Key::SettingsAiModelPlaceholder)); + text_field(ui, field, |value| msg(ai_about::Message::EditModel(value))) +} + +/// 密钥行：密码框 + 「显示 / 隐藏」chip + 已存状态（**只有字符数**）。 +fn key_field<'a>(ui: &'a Ui, catalog: Catalog, state: &'a State) -> Element<'a, Message> { + let chars = state.key_chars.to_string(); + let supporting = if state.key_chars > 0 { + catalog.render( + Key::SettingsAiApiKeyConfigured, + &[("chars", chars.as_str())], + ) + } else { + catalog.text(Key::SettingsAiApiKeyMissing).to_string() + }; + let field = Field::new(state.key.expose()) + .variant(FieldVariant::Outlined) + .label(catalog.text(Key::SettingsAiApiKey)) + .placeholder(catalog.text(Key::SettingsAiApiKeyPlaceholder)) + .secure(!state.reveal); + let toggle_label = if state.reveal { + catalog.text(Key::SettingsAiHide) + } else { + catalog.text(Key::SettingsAiShow) + }; + let toggle = chip( + ui, + Chip::filter( + toggle_label, + state.reveal, + msg(ai_about::Message::Reveal(!state.reveal)), + ), + ); + let field = container(text_field(ui, field, |value| { + msg(ai_about::Message::EditKey(Secret::new(value))) + })) + .width(Length::Fill); + column![ + row![field, toggle] + .spacing(ui.space(Space::X2)) + .width(Length::Fill) + .align_y(Alignment::Center), + // 「已存 N 字符 / 还没有密钥」这一行是**格式化出来的**（`Field::supporting` 借的是 + // `&'a str`，临时 String 借不进去），所以单独一行；它只讲长度，不讲值。 + text_role_owned( + ui, + TypeRole::BodySmall, + false, + supporting, + ui.color(Role::OnSurfaceVariant), + ), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill) + .into() +} + +fn actions_row<'a>(ui: &'a Ui, catalog: Catalog, state: &State) -> Element<'a, Message> { + let save_label = catalog.text(Key::SettingsAiSave); + let save = if state.dirty && state.storage { + buttons::filled(ui, Button::new(save_label, msg(ai_about::Message::Save))) + } else { + buttons::filled(ui, Button::disabled(save_label)) + }; + + let test_label = if matches!(state.probe, Probe::Running) { + catalog.text(Key::SettingsAiTesting) + } else { + catalog.text(Key::SettingsAiTest) + }; + let test = if state.can_test() { + buttons::tonal(ui, Button::new(test_label, msg(ai_about::Message::Test))) + } else { + buttons::tonal(ui, Button::disabled(test_label)) + }; + + row![save, test] + .spacing(ui.space(Space::X3)) + .align_y(Alignment::Center) + .into() +} + +/// 按钮为什么是灰的 / 下一步该做什么——**永远说清**，不留「点了没反应」。 +fn hint_line<'a>(ui: &'a Ui, catalog: Catalog, state: &State) -> Element<'a, Message> { + let (text, error) = if !state.storage { + (catalog.text(Key::SettingsAiNoStorage).to_string(), true) + } else if let Some(missing) = state.missing() { + ( + catalog.render( + Key::SettingsAiTestDisabled, + &[("missing", catalog.text(missing.label()))], + ), + false, + ) + } else if state.dirty { + (catalog.text(Key::SettingsAiUnsaved).to_string(), false) + } else { + (String::new(), false) + }; + text_role_owned( + ui, + TypeRole::BodySmall, + false, + text, + ui.color(if error { + Role::Error + } else { + Role::OnSurfaceVariant + }), + ) +} + +fn notice_line<'a>(ui: &'a Ui, catalog: Catalog, notice: &SaveNotice) -> Element<'a, Message> { + let (text, error) = match notice { + SaveNotice::Saved => (catalog.text(Key::SettingsAiSaved).to_string(), false), + SaveNotice::Refused(reason) => ( + catalog.render( + Key::SettingsAiRefused, + &[("reason", catalog.text(reason.label()))], + ), + true, + ), + SaveNotice::Failed(reason) => ( + catalog.render(Key::SettingsAiRefused, &[("reason", reason.as_str())]), + true, + ), + SaveNotice::NoStorage => (catalog.text(Key::SettingsAiNoStorage).to_string(), true), + }; + text_role_owned( + ui, + TypeRole::BodySmall, + false, + text, + ui.color(if error { Role::Error } else { Role::OnSurface }), + ) +} + +/// 测试结论一行：分类一句话（目标/耗时/详情在它下面三行）。 +fn probe_line<'a>(ui: &'a Ui, catalog: Catalog, kind: ProbeKind) -> Element<'a, Message> { + let error = kind.is_failure(); + text_role_owned( + ui, + TypeRole::BodyMedium, + true, + catalog.text(kind.label()).to_string(), + ui.color(if error { Role::Error } else { Role::Primary }), + ) +} 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..e855aff --- /dev/null +++ b/crates/app-iced/src/pages/settings/ai_about.rs @@ -0,0 +1,80 @@ +//! 设置页「助手（AI）」分组（M174）：左列第 6 组的**挂载点**与本线的消息口。 +//! +//! 本文件只留三样东西，正文/状态/读写都在 `pages/settings/ai/` 里： +//! +//! | 这里 | 内容 | +//! |---|---| +//! | [`GROUP`] | 左列名 / 图标 / 演示行（产品路径走 [`super::ai::view::body`]） | +//! | [`AI_GROUP`] | 本组在 `GROUPS` 里的下标（与 General / Update 同一条**按下标分发**：本组尚未迁到 `Group.body` 槽位，见下节） | +//! | [`Message`] | 本线的消息口（落点 `app/update/settings/ai_about.rs`） | +//! | [`State`] | 转发 `ai::State`（`Groups.ai_about` 的载荷类型不变，`settings/state.rs` 一行不用改） | +//! +//! ## 为什么 `body` 是 `None` 而不是 `Some(..)` +//! +//! `Group.body` 的槽位（M179 起）拿的是 [`States`](super::States) 与**生效语言** `Lang`——本组要的 +//! 两件它其实都装得下。本组仍走按下标分发，是因为**还没迁过去**：槽位要求返回 `Option`， +//! 而 `ai::view::body` 返回 `Element`，把本组（以及 Java 组）统一迁到槽位上是一次独立重构。 +//! M106 的语言行与 M159 的更新组当初也是同一个理由走上这条路，代价是 `settings/mod.rs` 多一行 `else if`。 +//! +//! ## 密钥纪律 +//! +//! [`Message::EditKey`] 的载荷是用户刚敲的明文（输入框必须有它），它**只**活在这个进程里： +//! 落盘走 `ai::store::save`（不经 `AppCommand::SetSetting` 那条可序列化通道）， +//! 上屏默认掩码（`State::reveal` 才明文），`Debug` 由 `ai::state::Secret` 掩码。 + +pub use super::ai::State; + +use unlucky_design::icons::IconKind; + +use super::Group; + +/// 本组在 [`super::GROUPS`] 里的下标（**必须是最后一个**：加组只追加不重排）。 +pub(crate) const AI_GROUP: usize = 5; + +/// 「助手」分组（左列名固定英文：左列是导航，与导航轨同源，不进 catalog）。 +pub(super) const GROUP: Group = Group { + name: "Assistant", + icon: IconKind::Ai, + // 只给 harness / 窄窗「按组堆叠」路径用的演示行：产品路径走 `ai::view::body`。 + rows: &[ + ("Provider", "OpenAI compatible"), + ("Endpoint", "https://api.deepseek.com/v1"), + ("Model", "deepseek-chat"), + ], + body: None, +}; + +/// 本线的消息（**只归本线**）：加变体只改本文件 + `app/update/settings/ai_about.rs`。 +#[derive(Debug, Clone)] +pub enum Message { + /// 启用开关（`ai.enabled`） + ToggleEnabled(bool), + /// 选提供商（`ai.provider`） + PickProvider(super::ai::ProviderId), + /// 端点草稿（`ai.base_url`） + EditBaseUrl(String), + /// 模型名草稿（`ai.model`） + EditModel(String), + /// 新密钥草稿（明文只在内存里；空 = 保留已存的那把）。 + /// + /// 载荷是 [`super::ai::Secret`] 而不是 `String`：**`Debug` 会打掩码**。这条消息会被 harness + /// 的 `{:?}` 打进 stderr（r1 复审 P2-2 的现场），也会出现在任何 `assert_eq!` 失败输出里， + /// 用裸 `String` 等于给密钥开了一条到日志的路。 + EditKey(super::ai::Secret), + /// 密钥输入框明文/掩码 + Reveal(bool), + /// 保存（校验 + 落盘） + Save, + /// 测试连接（异步；结果走 [`Message::ProbeDone`]） + Test, + /// 测试连接的结果（分类 + 数值 + 脱敏详情） + ProbeDone(Box), +} + +impl Message { + /// 一条本组消息 → 设置页的投递口（`pages::settings::GroupMessage::AiAbout`）。 + #[must_use] + pub fn into_group(self) -> super::GroupMessage { + super::GroupMessage::AiAbout(self) + } +} 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..ba2214c --- /dev/null +++ b/crates/app-iced/src/pages/settings/appearance.rs @@ -0,0 +1,47 @@ +//! 设置页「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/`（本文件只负责 +//! 把它挂进注册表），所以改控件时不用碰设置页目录。 +//! +//! M101 r2：本组的渲染器签名改成收 [`States`]（组状态 + 外观状态），于是「这一组要读哪些状态」 +//! 由本文件决定——`settings/mod.rs` 不再认识 `appearance::State`。 +//! +//! M179 `I18NSEAM`：签名再加一个 `lang`（`Group.body` 的槽位本身就带语言，见 `settings/mod.rs` 的 +//! `Body` 类型别名），于是这一组的中文界面文案真的走词表——此前它只能写死 `Lang::En`， +//! 因为渲染器拿不到「这一次生效的语言」。 + +use iced::Element; +use unlucky_design::icons::IconKind; +use unlucky_i18n::Lang; + +use crate::theme::Ui; + +use super::{Group, Message, States}; + +/// Appearance 分组。`body` 指着 [`body`]（它再转给 `pages/appearance/section/` 的真控件）； +/// 没有外观运行期状态时（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`。 +/// +/// `lang` 一路递给 `pages::appearance::section`——它是这一组唯一知道「界面现在是什么语言」的东西。 +fn body<'a>(ui: &'a Ui, states: States<'a>, lang: Lang) -> Option> { + states + .appearance + .map(|state| crate::pages::appearance::section(ui, state, lang)) +} 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..87454b6 --- /dev/null +++ b/crates/app-iced/src/pages/settings/download.rs @@ -0,0 +1,384 @@ +//! 设置页「Downloads」分组：并发 / 单源尝试次数 / 地区 / 镜像 / 代理 / GitHub 加速前缀（M201）。 +//! +//! **这一组归 download 线**：正文渲染器在本文件（`GROUP.body = Some(body)`），`settings/mod.rs` +//! 的注册表不用动。 +//! +//! 注意与下载页（`pages/download*`）的区别：那是「装哪个版本」，这里是「怎么下」的默认值。 +//! +//! ## 数据从哪来、写到哪去（M201 接的就是这条通路） +//! +//! ```text +//! presenter::host::settings::groups(&env) ← 真值（core schema 的键 + 生效值） +//! └─ CoreEvent::SettingsChanged(Vec) +//! └─ AppState::settings_groups ← presenter 的唯一写入口（apply_core） +//! └─ pages::Model.settings ← refresh_view：这一帧要画的设置值 +//! └─ settings::States.settings ← 本文件按 `id` 找到本组，逐行按 `control` 画 +//! └─ 控件（choice / text / action） +//! └─ Message → app/update/settings/download.rs +//! └─ AppCommand::SetSetting → host 写盘 + 重新发 SettingsChanged +//! ``` +//! +//! **闭环**：控件不回显自己点的结果（不做乐观回显）。点了以后界面变，只能是因为 host 把 +//! `SettingsChanged` 发回来了——那也正是「设置页里改了就生效」这句话的证据链。 +//! +//! ## 三件事分开画（这一组是「设置页里改不了」的修复落点） +//! +//! 1. **当前值**（choice 的选中 chip / text 的输入框）——来自快照，不来自任何字面量； +//! 2. **这一行在讲什么**（标题 + 说明）——说明里带着 presenter 算出来的「引擎生效值」， +//! 文件原值与生效值不一致时那句「原值 X 已按出厂 N 生效」也在里面（P3-5）； +//! 3. **怎么改**（点 chip / 输入 + 应用 / 点动作按钮）——写回走 `AppCommand::SetSetting`。 +//! +//! **没有快照**（harness / `pages_demo` / 首帧）时 `body` 返回 `None` ⇒ 退回去画 `GROUP.rows` +//! 那几行语义行（`frame::demo_card`）。那几行**说的不是值**（「出厂 8 · 可调 1~64」）， +//! 所以不会再把演示值当成真值（M193 用户投诉的形状）。 +//! +//! ## 文本行为什么要点「应用」 +//! +//! 每敲一个键就写一次盘会把半截值落进 `launcher.json`（`off` 敲到 `of` 时 schema 会让它通过）， +//! 而且 `store.set` 失败会弹一串 Toast。所以输入只改本地草稿（[`State::edit`]），点「应用」 +//! 才走 [`Message::Commit`] → `AppCommand::SetSetting`。 +//! +//! **为什么不是回车提交**：本仓的 `text_field`（`app/components/inputs/field.rs`）只暴露 `on_input`， +//! 没有 `on_submit` 的口子；给它加一个口子要动组件库（组件库有自己的验收线），所以这一版只有 +//! 「应用」这一颗按钮。回车提交登记为后续（见报告「没验/没做」）。 + +use std::collections::BTreeMap; + +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::{Key, Lang}; +use unlucky_presenter::dto::{SettingControl, SettingGroupView, SettingRowView}; +// `find_row` 只被 `#[cfg(test)]` 的探针用（产品路径按 `GROUP_ID` 取组、逐行画）。 +#[cfg(test)] +use unlucky_presenter::dto::find_row; + +use crate::app::components::buttons::{self, Button}; +use crate::app::components::inputs::{text_field, Field, FieldVariant}; +use crate::app::components::selection::{chip, switch, Chip, Switch}; +use crate::pages::frame::text_role_owned; +use crate::pages::Message as PageMessage; +use crate::theme::Ui; + +use super::frame::{card, divider}; +use super::{Group, States}; + +/// Downloads 分组。 +/// +/// `rows` 只在**没有快照**时画（harness / 首帧）：它们是语义行（出厂值 / 区间 / 三态）， +/// 不是当前值——M193 用户的投诉正是「把演示值当成了真值」。 +pub(super) const GROUP: Group = Group { + name: "Downloads", + icon: IconKind::Download, + rows: &[ + ("并发数", "出厂 8 · 可调 1~64"), + ("单源尝试次数", "出厂 3 · 含首次 · 0/1 = 只试一次"), + ("GitHub 加速前缀", "留空 = 跟随内置默认"), + ("关掉它", "填 off = 关闭"), + ("换掉它", "填 URL 前缀 = 覆盖"), + ], + body: Some(body), +}; + +/// 这一组在 presenter 快照里的 id（`setting::groups` 建组时给的那个）。 +const GROUP_ID: &str = "download"; + +/// Downloads 分组的运行期状态（M101 r2：**只归 download 线**）。 +/// +/// 只装「用户正在编辑、还没提交」的文本草稿。**当前值不在这里**——它来自 presenter 快照 +/// （`States::settings`），这里存一份就成了第二份真相。 +#[derive(Debug, Default)] +pub struct State { + /// schema 键 → 正在输入但还没提交的文本。 + drafts: BTreeMap, +} + +impl State { + /// 这一行此刻要显示的文本：有草稿用草稿，否则用快照里那个值（= 文件里的值）。 + pub(crate) fn text_of<'a>(&'a self, row: &'a SettingRowView) -> &'a str { + self.drafts + .get(&row.key) + .map_or(row.value_text.as_str(), String::as_str) + } + + /// 记一条草稿（`text_field` 的 `on_input` 落点；**不派发**任何指令）。 + pub(crate) fn edit(&mut self, key: &str, value: String) { + self.drafts.insert(key.to_string(), value); + } + + /// 这一行要提交的值（草稿优先）。`None` = 没草稿，调用方回落到快照里的值。 + pub(crate) fn pending(&self, key: &str) -> Option { + self.drafts.get(key).cloned() + } + + /// 丢掉一行的草稿（提交之后用：快照重新成为唯一真值）。 + pub(crate) fn clear(&mut self, key: &str) { + self.drafts.remove(key); + } +} + +/// Downloads 分组的消息（M101：**只归 download 线**，加变体只改本文件）。 +/// +/// 落点是 `app/update/settings/download.rs`；`pages/mod.rs` 与 `page_messages.rs` 都不用动（它们只认 +/// [`GroupMessage`](super::GroupMessage)）。 +#[derive(Debug, Clone)] +pub enum Message { + /// `choice` 行：选了一个选项 —— 直接提交（选择本身就是意图，没有「半截」状态）。 + Set { + /// schema 键（`download.concurrency`） + key: String, + /// 选项原文（`8` / `cn` / `off` 这类，写回时按 schema 的类型转换） + value: String, + }, + /// `text` 行：正在输入 —— **只改本地草稿**，不派发。 + Edit { + /// schema 键 + key: String, + /// 输入框里的整段文本 + value: String, + }, + /// `text` 行：提交（「应用」按钮 / 回车）。 + Commit { + /// schema 键 + key: String, + }, + /// `action` 行：动作按钮（例如「重新检测地区」）。 + Action { + /// 快照里那一行的键（动作 id 由 host 在 `settings::set` 里认） + key: String, + }, +} + +/// 把本组消息包进设置页那条**唯一**投递口（`pages::Message::Settings(GroupMessage::Download)`）。 +/// +/// 为什么必须有它：本模块里 `Message` 是本组自己的枚举，而 `Element` 的消息类型是 +/// `crate::pages::Message`（别名 [`PageMessage`]）。不包这一层，控件会带上本组的消息类型， +/// 于是 `settings/mod.rs` 那个 `and_then` 与页面树就对不上（编译期就红，不会静默丢消息）。 +fn msg(message: Message) -> PageMessage { + PageMessage::Settings(super::GroupMessage::Download(message)) +} + +// --------------------------------------------------------------- 正文 + +/// 整组正文：快照里按 [`GROUP_ID`] 找到本组，一行一个控件。 +/// +/// 返回 `None` = 这一帧没有本组的快照（harness / 首帧）⇒ `settings/mod.rs` 退回 `GROUP.rows`。 +/// +/// **行间距 = `Space::X3`（M201 r1 视觉复审 P2-1）**：分隔线的对比度只有 1.55:1（`OutlineVariant` +/// 本色，正常），「这是新的一行」这件事全靠**间距**承担。r1 复审实测这一组原本是 0 间距：说明末行 +/// 墨迹 → 分隔线只有 2–3px、分隔线 → 下一行标题 4–5px，100% 缩放下「地区判定」「镜像偏好」被读成 +/// 上一段说明的续行。 +/// +/// 为什么是 X3（12）而不是兄弟组的 X2（8）：本组每一行都是「标题 + 控件 + 多行说明」三段，比 Java +/// 组的行**密得多**，沿用 8 实测只到 8–9px（文本盒里 12–13px 的墨迹落在 16px 行盒中，盒间距 8 会被 +/// 吃掉 1px）；X3 把两侧都推到 12px 以上，落在「同族页 9–18px」的中段（实测见报告的表）。 +/// +/// 为什么不给 [`block`] 加 padding：那会把卡片的**第一行顶距**也撑开（卡内边距 20 + 12），与其它四组 +/// 的第一行不再对齐；`spacing` 只作用在子节点之间，首行顶距与末行底距仍是卡片的 20。 +fn body<'a>(ui: &'a Ui, states: States<'a>, lang: Lang) -> Option> { + let group = state_group(&states)?; + let drafts = &states.groups.download; + let catalog = lang.catalog(); + let mut stacked = column![].spacing(ui.space(Space::X3)).width(Length::Fill); + + for (index, item) in group.rows.iter().enumerate() { + if index > 0 { + stacked = stacked.push(divider(ui)); + } + stacked = stacked.push(match item.control { + SettingControl::Toggle => toggle_row(ui, item), + SettingControl::Choice => choice_row(ui, item), + SettingControl::Text => { + text_row(ui, item, drafts, catalog.text(Key::SettingsDownloadsApply)) + } + SettingControl::ReadOnly => read_only_row(ui, item), + SettingControl::Action => action_row(ui, item), + }); + } + + Some(card(ui, stacked)) +} + +/// 快照里的本组（`States::settings` 是 `Model.settings` 那一份）。 +fn state_group<'a>(states: &States<'a>) -> Option<&'a SettingGroupView> { + states.settings.iter().find(|group| group.id == GROUP_ID) +} + +/// 一行的标题（`BodyMedium`）。 +fn heading<'a>(ui: &'a Ui, item: &'a SettingRowView) -> Element<'a, PageMessage> { + text_role_owned( + ui, + TypeRole::BodyMedium, + false, + item.label.clone(), + ui.color(Role::OnSurface), + ) +} + +/// 一行的说明（`BodySmall`；P3-5 那句「原值 X 已按出厂 N 生效」就在这段文字里）。 +fn hint<'a>(ui: &'a Ui, item: &'a SettingRowView) -> Element<'a, PageMessage> { + text_role_owned( + ui, + TypeRole::BodySmall, + false, + item.description.clone(), + ui.color(Role::OnSurfaceVariant), + ) +} + +/// 标题 + 控件 + 说明（三行一组的常规排法）。 +fn block<'a>( + ui: &'a Ui, + item: &'a SettingRowView, + control: Element<'a, PageMessage>, +) -> Element<'a, PageMessage> { + column![heading(ui, item), control, hint(ui, item)] + .spacing(ui.space(Space::X1)) + .width(Length::Fill) + .into() +} + +/// 开 / 关两态（本组暂时没有 Toggle 行，但 `SettingControl` 是穷尽枚举，画法在这里定下来）。 +fn toggle_row<'a>(ui: &'a Ui, item: &'a SettingRowView) -> Element<'a, PageMessage> { + let key = item.key.clone(); + let toggle = switch( + ui, + Switch::new( + &item.label, + item.flag, + msg(Message::Set { + key, + // schema 的 Bool 键认 `true` / `false`（`settings::parse_value` 也认 on/off/1/0）。 + value: (!item.flag).to_string(), + }), + ), + ); + column![toggle, hint(ui, item)] + .spacing(ui.space(Space::X1)) + .width(Length::Fill) + .into() +} + +/// 分段单选：一个选项一颗 filter chip，选中的那颗是当前值。 +fn choice_row<'a>(ui: &'a Ui, item: &'a SettingRowView) -> Element<'a, PageMessage> { + let mut options = row![] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Center); + for (index, option) in item.options.iter().enumerate() { + let selected = i32::try_from(index) + .map(|index| index == item.selected) + .unwrap_or(false); + let key = item.key.clone(); + let value = option.clone(); + options = options.push(chip( + ui, + Chip::filter(option, selected, msg(Message::Set { key, value })), + )); + } + block(ui, item, options.into()) +} + +/// 单行文本 + 「应用」按钮（`on_input` 只改草稿，点按钮 / 回车才写盘）。 +fn text_row<'a>( + ui: &'a Ui, + item: &'a SettingRowView, + drafts: &'a State, + apply_label: &'a str, +) -> Element<'a, PageMessage> { + let key = item.key.clone(); + let field = Field::new(drafts.text_of(item)).variant(FieldVariant::Outlined); + let input = text_field(ui, field, move |value| { + msg(Message::Edit { + key: key.clone(), + value, + }) + }); + let apply = buttons::text( + ui, + Button::new( + apply_label, + msg(Message::Commit { + key: item.key.clone(), + }), + ), + ); + let controls = row![input, apply] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Center) + .width(Length::Fill); + block(ui, item, controls.into()) +} + +/// 只读一行（本组没有；`SettingControl` 是穷尽枚举）。 +fn read_only_row<'a>(ui: &'a Ui, item: &'a SettingRowView) -> Element<'a, PageMessage> { + block( + ui, + item, + text_role_owned( + ui, + TypeRole::BodySmall, + false, + item.value_text.clone(), + ui.color(Role::OnSurfaceVariant), + ), + ) +} + +/// 动作按钮（「重新检测地区」）。 +fn action_row<'a>(ui: &'a Ui, item: &'a SettingRowView) -> Element<'a, PageMessage> { + let button = buttons::tonal( + ui, + Button::new( + &item.label, + msg(Message::Action { + key: item.key.clone(), + }), + ), + ); + column![button, hint(ui, item)] + .spacing(ui.space(Space::X1)) + .width(Length::Fill) + .into() +} + +// --------------------------------------------------------------- 测试探针 + +/// 这一帧本组要画的**控件种类**（顺序 = 快照里的行序）。 +/// +/// 存在的理由：`Element` 没有内省接口，「页面画了哪几种控件」只能从行模型上问。测试用它区分 +/// 「画了真控件」与「退回了演示行」——这是 `body.is_some()` 之外唯一能看的东西。 +/// +/// `#[cfg(test)]`：产品路径不需要它（`body` 自己就在画），它只为断言存在。 +#[cfg(test)] +pub(crate) fn controls_of(settings: &[SettingGroupView]) -> Vec { + settings + .iter() + .find(|group| group.id == GROUP_ID) + .map(|group| group.rows.iter().map(|item| item.control).collect()) + .unwrap_or_default() +} + +/// 快照里本组某一行的**当前值**（choice 取选中的选项、text 取 `value_text`）。 +/// +/// 与 [`controls_of`] 同一条理由：页面把控件画出来之后，「它认为当前值是几」只能从这个入口问， +/// 不能从 `Element` 里读。 +#[cfg(test)] +pub(crate) fn current_value(settings: &[SettingGroupView], key: &str) -> Option { + let row = find_row(settings, key)?; + Some(match row.control { + SettingControl::Choice => row + .options + .get(usize::try_from(row.selected).ok()?) + .cloned() + .unwrap_or_default(), + // 其余三种控件的「当前值」就是 `value_text`（开关那一种用它表示 true/false）。 + SettingControl::Toggle + | SettingControl::Text + | SettingControl::ReadOnly + | SettingControl::Action => row.value_text.clone(), + }) +} 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..106b78b --- /dev/null +++ b/crates/app-iced/src/pages/settings/frame.rs @@ -0,0 +1,393 @@ +//! 设置页骨架：页头、左列分组导航、表单列的滚动区、演示卡片。 +//! +//! ## 为什么这里还再导出一批 `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, 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}; +use iced::{Alignment, Background, Border, Element, Length, Padding, Theme}; + +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::{Key, Lang}; + +use crate::pages::appearance::Change; +use crate::pages::{Action, Message}; +use crate::theme::Ui; + +use super::Group; + +/// 页头：标题 + 副标题 + 两个占位动作。 +/// +/// 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::>(), + ) + .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 下会超出可视区，所以这一层是必需的。 +/// +/// ## M173：滚动条**并排**在内容右侧 +/// +/// 原来这里是 `scrollable(content)` 裸调 + 轨宽 6 / 内缩 2。iced 的竖直滚动条是浮层：轨道按 +/// 视口右边缘定位（`iced_widget-0.14.2/src/scrollable.rs:1970`），而内容拿到的横向约束是**整个 +/// 视口宽**（同文件 `:437`，`Scrollbar::spacing` 默认 `None` ⇒ 右内边距 0）。于是滚动条占的那条 +/// 10dp 竖带（轨 6 + 两侧内缩 2×2）整条压在表单列最右边——用户看到的就是「滚动条骑在卡片上」。 +/// +/// 改法在 [`crate::app::components::scroll::vertical`]：内容右侧恒留一条 10dp 的槽，轨道画在槽里。 +/// 槽宽来自同一个式子 `轨宽 + 2 × margin`，所以： +/// +/// - 内容可用宽度 = 视口宽（424）− 槽宽（10）= **414**； +/// - 长页面（出滑块）与短页面（不出滑块）**内容宽度一致**——槽是内边距，不依赖 iced 的 +/// `is_scrollbar_visible`（那正是 `Scrollbar::spacing` 不能用在这里的理由：它只在可见时预留， +/// 滑块一出现内容就横跳 10dp）。 +/// +/// 数值由 `components/scroll.rs` 与 `tests/scroll_fit.rs` 的**布局级**断言钉住（`Renderer = ()` +/// 真跑 iced 的 `layout()`），不是看图。 +/// +/// 只泛型到 `Renderer` 是为了让上面那条断言能在 `()` 渲染器上跑；产品调用点不写泛型。 +pub(super) fn scroll<'a, Renderer>( + ui: &'a Ui, + content: impl Into>, +) -> Element<'a, Message, Theme, Renderer> +where + Renderer: iced::advanced::text::Renderer + 'a, +{ + crate::app::components::scroll::vertical( + SCROLLBAR_WIDTH, + SCROLLBAR_MARGIN, + scroll_style(ui), + content, + ) +} + +/// 演示行构成的一组设置 = 一张卡，行间 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() +} + +// --------------------------------------------------------------- M196 守门 + +/// M196：设置页正文**不许**在最后一组之后挂一张空态卡。 +/// +/// ## 守的是哪一件事 +/// +/// 用户 2026-11-08 在 M174 的助手页与 M175 的 Java 页都看到同一张不属于本页的空态卡（四格图标 + +/// 「没有逐实例覆盖」+ 说明被窗口下沿截断），两张图 1180×1100、卡片位置完全一致。根因是 +/// `settings/mod.rs` 的 `form()` 在分组循环之后**无条件**叠了一件固定 320dp 高的空态位 +/// （M84 骨架期的占位，M99 纯搬移时原样留下）——于是任何一组下面都长出同一张卡。 +/// +/// ## 两条判据怎么合起来咬死它 +/// +/// 正文由两半拼成：`mod.rs` 的 [`section_columns`](super::section_columns) **生产**「每组一件」的列， +/// `form` 只把它们堆起来再滚出去。于是： +/// +/// - [`the_form_stacks_nothing_but_its_sections`] 守**收尾**：正文的唯一来源是 `section_columns` +/// （`push(` 恰好一次、实参必须是循环变量、尾表达式是 `frame::scroll`）—— 多一件就红； +/// - [`the_form_holds_exactly_one_column_per_group`] 守**生产**：真调 `section_columns` 数它交出的 +/// 列数（窄窗 == `GROUPS.len()`，单选各组 == 1）—— 多塞一件就红，**不管那件叫什么名字**。 +/// +/// 两半合起来 = 「正文恰好这些列，没有尾巴」。 +/// +/// ## 为什么住在 `frame.rs` 而不是 `pages/settings/tests/` +/// +/// `tests/` 归四条 section 线所有（各改各的），而这里守的是**本文件与 `mod.rs` 之间的分工**： +/// 壳层不提供空态位、分发点不在尾部多堆一件。判据要是哪天挪进 `tests/`，也请原样保留这两条。 +/// +/// ## 抓得住 / 抓不住（据实写） +/// +/// 抓得住（四种变异都实测过）：①把卡折叠回循环 +/// （`stack = stack.push(section).push(frame::demo_card(…))`）⇒ 收尾那条数到 2 处 `push(`，红 +/// （与 `cargo fmt` 是否拆行无关）；②换成别的来源（`stack = stack.push(frame::text_role(…))`）⇒ +/// 实参不是 `section`，红；③塞进列清单（`section_columns` 里多 push 一件）⇒ 列数那条红； +/// ④整段改写成 `extend` / `chain` / 尾表达式再包一层 ⇒ 收尾那条红。 +/// 抓不住：**某一组自己的列里**换内容（比如某个分组真的需要自己的空态）。那不是本缺陷——本页允许 +/// 组内有空态，前提是它长在该组的列里、用本页语义的文案。`DevDocs/artifacts/m196/` 那组图是**当时** +/// 的证据，不是将来的防线（静态图只能证明「现在没有」）。 +#[cfg(test)] +mod no_stray_empty_state { + use unlucky_design::color::SchemeFlavor; + use unlucky_design::typography::Platform; + + use crate::pages::update::Update; + use crate::theme::{Families, Ui}; + + use super::super::{demo_groups, section_columns, Language, States, GROUPS}; + + /// 设置页的分发点（本文件是它的被调用方）。 + const FORM: &str = include_str!("mod.rs"); + + const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", + }; + + /// `form()` 的函数体：从它的签名取到下一个函数（`section_columns`）的签名之前。 + /// + /// 只取 `form` 自己：`section_columns` 里面有 `columns.push(`，那是另一条判据管的事。 + fn form_body() -> &'static str { + let start = FORM + .find("fn form<'a>(") + .expect("settings/mod.rs 里找不到 form()：分发点被改名了，本守门要跟着改"); + let rest = &FORM[start..]; + let end = rest + .find("\nfn section_columns") + .expect("settings/mod.rs 里找不到 section_columns()：列生产被改名了，本守门要跟着改"); + &rest[..end] + } + + fn ui() -> Ui { + Ui::with_platform(SchemeFlavor::Light, Platform::Windows, FAMILIES) + } + + /// `form()` 的函数体，**剥掉每行 `//` 之后的部分**：判据数的是代码，注释里的 `push(` 不算。 + fn form_code() -> String { + form_body() + .lines() + .map(|line| line.split("//").next().unwrap_or_default()) + .collect::>() + .join("\n") + } + + /// 演示 / harness 路径那份只读状态（与 `pages::page` 同源，不伪造第二份）。 + fn states() -> States<'static> { + States { + appearance: None, + groups: demo_groups(), + settings: &[], + } + } + + /// 判据 ①（**收尾**）：正文的柱子只有一个来源——`section_columns` 交出的那一列。 + /// + /// M195 r2 复审实测的盲区：原来数的是 `stack = stack.push(` 的出现**次数**，于是 + /// `stack = stack.push(section).push(frame::demo_card(ui, &[]));` 一句折叠里塞第二件时计数仍是 1 + /// （第二个 `.push(` 前面没有 `stack = `）⇒ 判据 ① 与 ② 同时绿。那是在数**写法**。现在按**角色** + /// 断言：循环头直接迭代 `section_columns`、`push(` 恰好一次且实参是那个循环变量、尾表达式恰好是 + /// `frame::scroll(ui, stack)`、没有 `extend`/`chain`/`once`/`concat`/`append`。`push(` 按**次数** + /// 数（拆行不影响），注释里的不算（先剥掉每行 `//`）。变异证明见模块文档的「抓得住」。 + #[test] + fn the_form_stacks_nothing_but_its_sections() { + let body = form_code(); + + assert!( + body.contains("for section in section_columns("), + "`form()` 的循环头必须直接迭代 `section_columns(...)`：正文节点的唯一来源就是它" + ); + + let pushes = body.matches("push(").count(); + assert_eq!( + pushes, 1, + "`form()` 里出现了 {pushes} 处 `push(`：分组循环里只该有一处。多出来的那一处就是\ + 「每组下面多一件」（M196 那张卡）——同一句里折叠成 `.push(a).push(b)` 也算两处" + ); + + let at = body.find("push(").expect("上面刚数过一次") + "push(".len(); + let argument = body[at..].split(')').next().unwrap_or_default().trim(); + assert_eq!( + argument, "section", + "被压进正文的必须是 `section_columns` 交出的那一列（循环变量 `section`），实际是 \ + `{argument}`：别的来源（演示卡 / 空态 / 任何控件）都不许进正文" + ); + + for append in ["extend(", "chain(", "once(", "concat(", "append("] { + assert!( + !body.contains(append), + "`form()` 用了 `{append}`：正文只许从 `section_columns` 逐列 push 进来" + ); + } + + let tail: Vec<&str> = body + .lines() + .map(str::trim) + .filter(|line| !line.is_empty()) + .collect(); + assert_eq!( + tail.iter().rev().take(2).copied().collect::>(), + vec!["}", "frame::scroll(ui, stack)"], + "`form()` 必须以 `frame::scroll(ui, stack)` 收尾（后面紧跟函数右花括号）：\ + 正文到最后一组就结束，别再包一层或往后叠东西" + ); + } + + /// 判据 ②（**生产**）：真跑 `section_columns`，量它到底交出几列。 + /// + /// 这是行为断言：调的是产品路径上那个真函数，**不认任何名字**。谁往正文里多塞一件（M196 那张 + /// 「没有逐实例覆盖」的卡当初就是这么塞的），列数就不等于组数。 + /// + /// 为什么不走 `tests/scroll_fit.rs` 那条「`()` 渲染器真跑布局」的路：`form` / `section_columns` + /// 交出的是**产品渲染器**的 `Element`，要按那条路量子节点数，得把 `general` / `update` / `ai` + /// 三条线的 `body` 一并泛型化（它们不在本 mission 的 scope 内）。量列数拿到的是同一个不变量， + /// 且不需要泛型。 + #[test] + fn the_form_holds_exactly_one_column_per_group() { + let ui = ui(); + let update = Update::default(); + + let narrow = section_columns(&ui, None, states(), Language::default(), &update); + assert_eq!( + narrow.len(), + GROUPS.len(), + "窄窗（按组堆叠）的正文应当是「每组一件」：多出来的那一件就是 M196 那张卡的位置" + ); + + for index in 0..GROUPS.len() { + let single = section_columns(&ui, Some(index), states(), Language::default(), &update); + assert_eq!( + single.len(), + 1, + "supporting-pane 只该画被选中的那一组（下标 {index}），实际拿到 {} 列", + single.len() + ); + } + } +} 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..4842889 --- /dev/null +++ b/crates/app-iced/src/pages/settings/general.rs @@ -0,0 +1,366 @@ +//! 设置页「General」分组：语言选择器 + 主题 / 启动页 / 关闭按钮（M106 接真控件）。 +//! +//! **这一组归 language+appearance 线**（M101 的分线口径）。 +//! +//! ## 这一组为什么特殊 +//! +//! 它**不走** `Group::body`：那个渲染器拿的是 [`States`](super::States) 与**生效语言** `Lang` +//! （M179 起；此前连 `Lang` 都没有），而语言行要的是「当前语言**档位** `LangChoice` + 生效语言」 +//! 这一对——档位不在 `States` 里。所以它由 `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` +//! 的头注释：为什么不写语言自称）。 +//! +//! ## 主题行已接真控件（M229），另两行仍只读 +//! +//! 主题三档（Ink / Silver / 跟随系统）在 M229 接成真控件：点一下换色板 + 落盘 +//! `appearance.theme_mode`（实现在 `general/theme.rs`，消息是 `pages::Message::Theme`）。 +//! 启动页 / 关闭按钮还没有后端（`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::spacing::Space; +use unlucky_design::typography::TypeRole; +use unlucky_i18n::catalog::Key; +use unlucky_i18n::LangChoice; + +use crate::fonts::install::{CjkInstall, FetchClass}; +use crate::pages::{frame, Language, Message}; +use crate::theme::Ui; + +use super::frame::{card, divider}; +use super::{Group, States}; + +mod theme; + +/// General 分组（左列名固定英文：左列是**导航**，与导航轨同源，不进 catalog）。 +pub(super) const GROUP: Group = Group { + name: "General", + icon: IconKind::Settings, + // 只给 harness（`pages_demo` 走 `appearance: None` 时）用的演示行：产品路径走 [`body`]。 + // 语言与主题那两行**不在**这里——它们的值跟着语言/档位变，写死在静态表里就是用户看到的假值 + // （语言 M106 移出、主题 M229 移出）。 + rows: &[ + ("Startup page", "Instances"), + ("Close button", "Exit to tray"), + ], + body: None, +}; + +/// 这一组的正文（**产品路径**）。 +pub(super) fn body<'a>(ui: &'a Ui, states: States<'a>, 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)); + // M168（D28 后半）：中文字体的下载状态行。紧贴语言行——用户在这里手选中文，反馈就该在这行下面， + // 而不是等他切到别的页面才发现「刚才那几秒在干嘛」。 + stacked = stacked.push(divider(ui)); + stacked = stacked.push(font_row(ui, language)); + + // M229：主题行接真控件（Ink / Silver / 跟随系统）。档位住在设置组的自有状态里 + // （`language_appearance::State::theme`），与语言行同一个排版：标题 + 三枚互斥 chip + 一句说明。 + stacked = stacked.push(divider(ui)); + stacked = stacked.push(theme::view( + ui, + &catalog, + states.groups.language_appearance.theme, + )); + + // M188：日志文件夹（路径 + 打开 + 复制路径）。放在「启动页/关闭按钮」之前——用户投诉 + // 「找不到崩溃日志」要的答案，不该埋在只读行后面。 + stacked = stacked.push(divider(ui)); + stacked = stacked.push(super::logs_row::folder_row(ui, &catalog)); + + // 启动页 / 关闭按钮：还没有后端，只读；文案已经进 catalog。 + for (label, value) in [ + (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) +} + +/// 中文字体状态行的**文案**（纯函数：状态 × 目录 → 一句话 + 可选的一句解释）。 +/// +/// 为什么单独拎出来：截图只能证明「画出来了」，而这里能被断言证明「四种状态的词都在、占位符都被 +/// 替换、两套目录都没有 `⟪missing⟫`」（见 `tests/general_section.rs`）。 +/// +/// 失败态**不写具体错误串**：那是给我们看的（`[font] cjk-download failed` 那行日志），用户只需要 +/// 知道「网络 / 内容 / 磁盘」里哪一类，以及「界面照常可用」。 +pub(super) fn font_status( + catalog: &unlucky_i18n::catalog::Catalog, + status: &CjkInstall, +) -> (String, Option) { + match status { + CjkInstall::Unknown => (catalog.text(Key::FontCjkStatusUnknown).to_owned(), None), + CjkInstall::Unprobeable => (catalog.text(Key::FontCjkStatusUnprobeable).to_owned(), None), + CjkInstall::NotNeeded => (catalog.text(Key::FontCjkStatusNotNeeded).to_owned(), None), + CjkInstall::System { family } => ( + catalog.render(Key::FontCjkStatusSystem, &[("family", family)]), + None, + ), + CjkInstall::Downloading { bytes } => ( + catalog.render( + Key::FontCjkStatusDownloading, + &[("size", &format_size(*bytes))], + ), + Some(catalog.text(Key::FontCjkStatusHint).to_owned()), + ), + CjkInstall::Ready { family, .. } => ( + catalog.render(Key::FontCjkReady, &[("family", family)]), + Some(catalog.text(Key::FontCjkStatusHint).to_owned()), + ), + CjkInstall::Failed { class, .. } => { + let reason = catalog.text(match class { + FetchClass::Network => Key::FontCjkReasonNetwork, + FetchClass::Integrity => Key::FontCjkReasonIntegrity, + FetchClass::Disk => Key::FontCjkReasonDisk, + }); + ( + catalog.render(Key::FontCjkStatusFailed, &[("reason", reason)]), + None, + ) + } + } +} + +/// 字节数 → 人话体积（17 772 300 B → `16.9 MB`，按 1 MiB = 1048576 B）。只用于「≈」级别的量。 +fn format_size(bytes: u64) -> String { + const MIB: f64 = 1024.0 * 1024.0; + let mib = bytes as f64 / MIB; + if mib >= 1.0 { + format!("{mib:.1} MB") + } else { + format!("{:.0} KB", bytes as f64 / 1024.0) + } +} + +/// 中文字体状态行：标签一行、状态一行（失败红、就绪主色）、需要时再补一句解释。 +/// +/// 为什么**竖排**而不是像主题那几行「标签左、取值右」：失败那句话是整句（「获取失败（网络不通）。 +/// 界面照常可用…」），塞进右列会把它压成一行挤掉标签（实测截图就是一整行红字、标签消失）。 +/// 语言行也是竖排（标题 + 选项 + 说明），这一行贴着它，观感一致。 +fn font_row<'a>(ui: &'a Ui, language: Language) -> Element<'a, Message> { + let catalog = language.effective.catalog(); + let status = crate::fonts::install::status(); + let (value, hint) = font_status(&catalog, &status); + let color = match status { + CjkInstall::Failed { .. } => ui.color(Role::Error), + CjkInstall::Ready { .. } | CjkInstall::System { .. } => ui.color(Role::Primary), + _ => ui.color(Role::OnSurfaceVariant), + }; + + let mut stacked = column![ + frame::text_role( + ui, + TypeRole::BodyMedium, + false, + catalog.text(Key::FontCjkStatusLabel), + ui.color(Role::OnSurface), + ), + container(frame::text_role_owned( + ui, + TypeRole::BodySmall, + false, + value, + color + )) + .width(Length::Fill), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill) + .padding(Padding::from([ui.space(Space::X2), 0.0])); + + if let Some(hint) = hint { + stacked = stacked.push(container(frame::text_role_owned( + ui, + TypeRole::BodySmall, + false, + hint, + ui.color(Role::OnSurfaceVariant), + ))); + } + + stacked.into() +} + +/// 语言行：标题 + 生效语言回显 + 三档互斥按钮 + 一句说明。 +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::>()) + .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/mod.rs` 的 `choice` 同款几何，但文案来自 catalog（那份是英文基线）。 +/// +/// **几何（M229）**：取规格卡的 chip（高 32、圆角 8、内距 16、未选中 1px `OutlineVariant`）， +/// 与同屏的主题三档 chips 完全同源——两行都是「并排的互斥筛选」，长得不一样会让读者以为是 +/// 两种控件（M229 第一版就是这样：语言 40 高药丸、主题 32 高方角，出图一眼就不齐）。 +fn chip<'a>(ui: &'a Ui, text: &'a str, selected: bool, choice: LangChoice) -> Element<'a, Message> { + let box_ = unlucky_design::inkcat::metrics::CHIP; + let height = box_.height; + let content_color = if selected { + ui.color(Role::OnSecondaryContainer) + } else { + ui.color(Role::OnSurfaceVariant) + }; + let border_color = ui.color(Role::OutlineVariant); + + button( + container(frame::text_role( + ui, + TypeRole::LabelLarge, + selected, + text, + content_color, + )) + .align_y(Alignment::Center), + ) + .height(height) + .padding(Padding::from([ + 0.0, + unlucky_design::inkcat::metrics::CHIP_PAD_X, + ])) + .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) { + // M237：这一组整个住在 `frame::card` 里，状态层叠**卡底**（不是画布）。 + Some(Background::Color(ui.state_over( + StateLayer::Hover, + Role::OnSurface, + frame::BASE.role(), + ))) + } else { + None + }; + + button::Style { + background, + text_color: content_color, + border: Border { + color: border_color, + width: if selected { + 0.0 + } else { + crate::theme::STROKE_PX + }, + radius: ui.radius(box_.shape, height), + }, + shadow: Shadow::default(), + snap: true, + } + }) + .on_press(Message::Language(choice)) + .into() +} diff --git a/crates/app-iced/src/pages/settings/general/theme.rs b/crates/app-iced/src/pages/settings/general/theme.rs new file mode 100644 index 0000000..8c4e6f6 --- /dev/null +++ b/crates/app-iced/src/pages/settings/general/theme.rs @@ -0,0 +1,164 @@ +//! 设置页「General → 主题」行：Ink / Silver / 跟随系统三档（M229）。 +//! +//! 从 `general.rs` 拆出来的理由只有一条：加这三档之后那个文件 474 行（400 行硬线）。 +//! 拆法是「整段搬走 + 一个 `pub(super) fn view` 入口」（起初叫 `row`，与 `iced::widget::row` +//! 撞名后改名）；搬出的函数体只改了「未选中态补 1px `OutlineVariant` 描边」这一处， +//! 目的是与同页语言行的 chip 同几何（复审 F2 之后两行才对齐）。 +//! +//! 三档的语义：**Ink = 深色主方案、Silver = 浅色主方案**，落盘取值仍是 `appearance.theme_mode` +//! 的 `dark` / `light`；第三档「跟随系统」= `auto`，由系统深浅落到对应色板 +//! （`BrandBoard::for_flavor`）。所以这里**不新增配置键**，旧配置读进来语义也一致。 + +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::inkcat::metrics as chipbox; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; +use unlucky_i18n::catalog::{Catalog, Key}; +use unlucky_presenter::prefs::ThemeMode; + +use crate::pages::{frame, Message}; +use crate::theme::Ui; + +/// 三档全序（Ink / Silver / 跟随系统）：`ThemeMode` 在 presenter，声明序是 `Auto/Light/Dark`， +/// 画出来的顺序按「深 → 浅 → 跟随」，所以这里另给一张表，不靠枚举声明序。 +pub(super) const THEME_MODES: [ThemeMode; 3] = [ThemeMode::Dark, ThemeMode::Light, ThemeMode::Auto]; + +/// 主题行：标题 + 三档互斥 chip + 一句说明（排版与语言行同族）。 +pub(super) fn view<'a>(ui: &'a Ui, catalog: &Catalog, mode: ThemeMode) -> Element<'a, Message> { + let head = row![ + container(frame::text_role( + ui, + TypeRole::BodyMedium, + false, + catalog.text(Key::SettingsTheme), + ui.color(Role::OnSurface), + )) + .width(Length::Fill) + .align_y(Alignment::Center), + frame::text_role( + ui, + TypeRole::LabelLarge, + true, + catalog.text(mode_label(mode)), + ui.color(Role::OnPrimaryFixedVariant), + ), + ] + .width(Length::Fill) + .align_y(Alignment::Center); + + let chips = row(THEME_MODES + .iter() + .map(|choice| { + chip( + ui, + catalog.text(mode_label(*choice)), + *choice == mode, + *choice, + ) + }) + .collect::>()) + .spacing(ui.space(Space::X1)) + .align_y(Alignment::Center); + + column![ + head, + chips, + frame::text_role( + ui, + TypeRole::BodySmall, + false, + catalog.text(Key::SettingsThemeHint), + ui.color(Role::OnSurfaceVariant), + ), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill) + .padding(Padding::from([ui.space(Space::X2), 0.0])) + .into() +} + +/// 一档主题的选项名（Ink / Silver / 跟随系统）。 +fn mode_label(mode: ThemeMode) -> Key { + match mode { + ThemeMode::Dark => Key::SettingsThemeInk, + ThemeMode::Light => Key::SettingsThemeSilver, + ThemeMode::Auto => Key::SettingsThemeFollowSystem, + } +} + +/// 一枚主题档位按钮（选中态 `SecondaryContainer`，未选中透明 + 1px `OutlineVariant`）。 +/// +/// 几何取规格卡的 chip（高 32、圆角 8，`inkcat::metrics::CHIP`）：主题三档是**可并排的筛选**， +/// 不是主行动按钮，用 chip 档比语言行那枚 40 高药丸更贴规格卡。 +fn chip<'a>(ui: &'a Ui, text: &'a str, selected: bool, mode: ThemeMode) -> Element<'a, Message> { + let box_ = chipbox::CHIP; + let height = box_.height; + let content_color = if selected { + ui.color(Role::OnSecondaryContainer) + } else { + ui.color(Role::OnSurfaceVariant) + }; + let border_color = ui.color(Role::OutlineVariant); + let stroke = crate::theme::STROKE_PX; + + button( + container(frame::text_role( + ui, + TypeRole::LabelLarge, + selected, + text, + content_color, + )) + .align_y(Alignment::Center), + ) + .height(height) + .padding(Padding::from([0.0, chipbox::CHIP_PAD_X])) + .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) { + // M237：主题三档同样住在设置卡里，状态层叠卡底（`frame::BASE`）。 + Some(Background::Color(ui.state_over( + StateLayer::Hover, + Role::OnSurface, + frame::BASE.role(), + ))) + } else { + None + }; + + button::Style { + background, + text_color: content_color, + border: Border { + color: border_color, + width: if selected { 0.0 } else { stroke }, + radius: ui.radius(box_.shape, height), + }, + shadow: Shadow::default(), + snap: true, + } + }) + .on_press(Message::Theme(mode)) + .into() +} + +#[cfg(test)] +mod tests { + use super::*; + + /// 三档 = 两块板 + 一种跟随，顺序是深 → 浅 → 跟随（换序会让「Ink 在最左」这条观感失守）。 + #[test] + fn the_three_modes_are_ink_silver_and_follow_system() { + assert_eq!( + THEME_MODES, + [ThemeMode::Dark, ThemeMode::Light, ThemeMode::Auto] + ); + assert_eq!(mode_label(ThemeMode::Dark), Key::SettingsThemeInk); + assert_eq!(mode_label(ThemeMode::Light), Key::SettingsThemeSilver); + assert_eq!(mode_label(ThemeMode::Auto), Key::SettingsThemeFollowSystem); + } +} 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..8fad52f --- /dev/null +++ b/crates/app-iced/src/pages/settings/java.rs @@ -0,0 +1,108 @@ +//! 设置页「Java」分组（M175）：运行时列表 / 默认 JDK / 内存 / JVM 参数。 +//! +//! 本文件只剩三样东西，正文 / 状态 / 读写都在 `pages/settings/java/` 里： +//! +//! | 这里 | 内容 | +//! |---|---| +//! | [`GROUP`] | 左列名 / 图标（正文走 [`view::body`]，`body` 槽位保持 `None`） | +//! | [`JAVA_GROUP`] | 本组在 `GROUPS` 里的下标（与 General / Update / Assistant 同一条**按下标分发**：本组要 `Lang`，`Group.body` 的签名里没有它） | +//! | [`Message`] | 本线的消息口（落点 `app/update/settings/java.rs`） | +//! +//! ## M101 的演示行去哪了 +//! +//! M101 留的 `rows: &[("Runtime","Temurin 21.0.4"), …]` 与绊线测试 +//! `the_java_group_is_still_demo_rows`（断言 `body.is_none()`）在 M175 一起删掉了： +//! 那三个值是**写死的演示字符串**，用户实测把它们当成了真检测结果 +//! （「它默认显示 Temurin 21.0.4 我甚至不能确定它是否是一个硬编码的值」）。 +//! 现在的真值来自三段真读盘：`core::game::java::staged`（扫描）、`core::game::java::manual` +//! （手动路径严格探测）、`config/launcher.json`（`java.*` 三键）。 +//! +//! `rows` 仍留成空切片：它是 `Group` 的字段（另外五组在用），而本组的 `body` 分发永远命中 +//! [`view::body`]，空切片不会被画出来——宁可空着，也不留一句会撒谎的演示值。 + +mod context; +mod download_view; +pub(crate) mod downloads; +mod fields; +pub(crate) mod prefs; +pub(crate) mod prefs_store; +mod prefs_view; +mod row; +pub(crate) mod scan; +mod seed; +mod state; +pub(crate) mod store; +pub(super) mod view; + +#[cfg(test)] +mod tests; + +pub use state::{same_path, Context, Layer, Notice, Requirement, State}; + +/// 测试里的注入作业要写 `Vec`（App 层在生产路径上只用 `State`，不需要这个名字）。 +#[cfg(test)] +pub use row::RuntimeRow; + +use unlucky_design::icons::IconKind; + +use super::Group; + +/// 本组在 [`super::GROUPS`] 里的下标（`GROUPS` 的顺序是 general / appearance / **java** / …）。 +/// +/// 写死 2 与 `groups[2]` 同一个来源：`tests/mod.rs` 的「左列顺序」把这张表钉住了。 +pub(crate) const JAVA_GROUP: usize = 2; + +/// Java 分组。 +pub(super) const GROUP: Group = Group { + name: "Java", + icon: IconKind::Folder, + // 空：产品路径与窄窗「按组堆叠」都走 `view::body`（见文件头「M101 的演示行去哪了」）。 + rows: &[], + body: None, +}; + +/// 本线的消息（**只归本线**）：加变体只改本文件 + `app/update/settings/java.rs`。 +#[derive(Debug, Clone)] +pub enum Message { + /// 手动触发一次自动扫描（真扫盘，后台线程；进度与结果由心跳灌回来） + Scan, + /// 取消正在跑的扫描 + CancelScan, + /// 手动路径输入框 + AddDraft(String), + /// 提交手动添加（严格校验：真跑 `java -version`） + Add, + /// 把某个运行时设为默认（写 `java.selected_path`） + SelectRuntime(String), + /// 默认内存草稿（MB 文本） + EditMemory(String), + /// JVM 额外参数草稿 + EditJvm(String), + /// 保存内存 + JVM 参数（校验 + 落盘 + 回读） + Save, + /// 下载并安装某个大版本的 JDK（M197：真下载，后台线程跑） + Download(u32), + /// `java.installRoot` 草稿 + EditInstallRoot(String), + /// `java.auto_install` 开关 + ToggleAutoInstall(bool), + /// 发行版顺序上移 / 下移一行（`index` 是有效顺序里的下标） + MoveVendor { + /// 有效顺序里的下标 + index: usize, + /// `true` = 上移，`false` = 下移 + up: bool, + }, + /// 发行版顺序恢复地区默认序（= 把这个键写回空） + ResetPriority, + /// 保存三个设置键（`installRoot` / `vendorPriority` / `auto_install`） + SavePrefs, +} + +impl Message { + /// 一条本组消息 → 设置页的投递口（`pages::settings::GroupMessage::Java`）。 + #[must_use] + pub fn into_group(self) -> super::GroupMessage { + super::GroupMessage::Java(self) + } +} diff --git a/crates/app-iced/src/pages/settings/java/context.rs b/crates/app-iced/src/pages/settings/java/context.rs new file mode 100644 index 0000000..2bff47d --- /dev/null +++ b/crates/app-iced/src/pages/settings/java/context.rs @@ -0,0 +1,181 @@ +//! 当前实例对 Java 的**要求**与「某个大版本够不够」的判定（M197 从 `state.rs` 拆出）。 +//! +//! M175 只回答了「满不满足」（一个 `bool`），于是**方向说不清**：1.12.2 只能吃 Java 8， +//! 用户手里是 Java 21 时旧文案写的是「低于要求：当前实例需要 Java 8 及以上」——那句话自相矛盾 +//! （21 当然 ≥ 8）。M197 的第三条任务（「不许静默失败，要说清这个版本需要 Java X，当前是 Y」） +//! 要求两个方向各说各的，所以这里改成带方向的 [`Fit`]。 +//! +//! 判据本身来自 `core::game::java::mapping`（静态表 + 版本 JSON 的 `javaVersion`）， +//! 本文件只是把它翻成页面的三态；**不复制**那张表。 + +/// 当前实例对 Java 的版本要求（app 层算好塞进来）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Requirement { + /// 实例名（「为什么选它」那句话里要指名道姓） + pub instance: String, + /// 实例绑的版本 id（`1.20.1`） + pub version: String, + /// 最低主版本 + pub minimum: u32, + /// 最高主版本（老版本才有；`None` = 不封顶） + pub maximum: Option, +} + +impl Requirement { + /// 某个大版本满不满足。 + #[must_use] + pub fn satisfied_by(&self, major: u32) -> bool { + major >= self.minimum && self.maximum.is_none_or(|max| major <= max) + } + + /// 某个大版本**怎么不满足**（满足时给 [`Fit::Ok`]）。 + /// + /// 两个方向的判据与 `mapping::check` 一致（下限来自版本清单 / 静态表，上限只对老版本存在）。 + #[must_use] + pub fn fit(&self, major: u32) -> Fit { + if major < self.minimum { + return Fit::TooOld { + required: self.minimum, + actual: major, + }; + } + match self.maximum { + Some(maximum) if major > maximum => Fit::TooNew { + maximum, + actual: major, + }, + _ => Fit::Ok, + } + } + + /// 要求的人读形态（`Java 21+` / `Java 8`）——**不含**"当前是什么"，那是 [`Fit`] 的活。 + #[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), + } + } +} + +/// 「这个大版本够不够用」的三态。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Fit { + /// 满足要求 + Ok, + /// 太低（当前实例要更老的之上的版本） + TooOld { + /// 需要的最低主版本 + required: u32, + /// 实际主版本 + actual: u32, + }, + /// 太高（老加载器吃不了新的 class 文件） + TooNew { + /// 允许的最高主版本 + maximum: u32, + /// 实际主版本 + actual: u32, + }, +} + +impl Fit { + /// 是不是「不满足」。 + #[must_use] + pub const fn is_mismatch(self) -> bool { + !matches!(self, Self::Ok) + } +} + +/// 生效内存来自哪一层。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum Layer { + /// 全局 `java.default_memory_mb` + Global, + /// 某个实例的 `launch.memoryMb` 覆盖了全局 + Instance { + /// 实例名 + instance: String, + /// 实例层的值 + mb: u32, + }, +} + +/// 上下文（app 层每次 hydrate 重算）。 +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct Context { + /// 当前实例的版本要求（没有实例 ⇒ `None`） + pub required: Option, + /// 当前生效内存来自哪一层 + pub layer: Option, + /// 当前生效内存（三级回落之后的数值） + pub effective_memory_mb: Option, +} + +#[cfg(test)] +mod tests { + use super::{Fit, Requirement}; + + fn legacy() -> Requirement { + Requirement { + instance: "老服".to_string(), + version: "1.12.2".to_string(), + minimum: 8, + maximum: Some(8), + } + } + + fn modern() -> Requirement { + Requirement { + instance: "生存服".to_string(), + version: "1.20.5".to_string(), + minimum: 21, + maximum: None, + } + } + + /// 两个方向各说各的：Java 21 对 1.12.2 是**太高**，不是「低于要求」。 + /// + /// M175 的 `satisfied()` 只给布尔值，文案于是必然写错一个方向（复审实测到的现象）。 + /// 变异证明：把 `fit` 里的 `maximum` 分支删掉（一律 `Fit::Ok`）⇒ 本用例红。 + #[test] + fn the_direction_of_the_mismatch_is_reported() { + assert_eq!( + legacy().fit(21), + Fit::TooNew { + maximum: 8, + actual: 21 + } + ); + assert_eq!( + modern().fit(17), + Fit::TooOld { + required: 21, + actual: 17 + } + ); + assert_eq!(modern().fit(21), Fit::Ok); + assert_eq!(modern().fit(25), Fit::Ok, "不封顶时更高的版本也满足"); + assert_eq!(legacy().fit(8), Fit::Ok); + assert!(legacy().fit(21).is_mismatch()); + assert!(!modern().fit(21).is_mismatch()); + } + + /// 要求的人读形态（给下载项 / 运行时行共用）。 + #[test] + fn the_requirement_reads_as_a_range() { + assert_eq!(legacy().describe(), "Java 8"); + assert_eq!(modern().describe(), "Java 21+"); + assert_eq!( + Requirement { + minimum: 8, + maximum: Some(16), + ..modern() + } + .describe(), + "Java 8–16", + "有上限时区间两端都要写出来（1.17 的 8–16 就是一个真实区间）" + ); + } +} diff --git a/crates/app-iced/src/pages/settings/java/download_view.rs b/crates/app-iced/src/pages/settings/java/download_view.rs new file mode 100644 index 0000000..f63f5d8 --- /dev/null +++ b/crates/app-iced/src/pages/settings/java/download_view.rs @@ -0,0 +1,387 @@ +//! 「下载一个 JDK」的视图（M197）：**版本选择列表 / 下载中 / 失败**三态。 +//! +//! 三态各自能说清什么，是这一屏的全部要求： +//! +//! | 态 | 必须出现的 | +//! |---|---| +//! | 选择列表 | 8 / 11 / 17 / 21 / 25 每一档 + 它由哪几家发行版承接 + 与当前实例要求的关系 | +//! | 下载中 | 大版本 + 阶段 + 百分比（分母未知就不给）+ 当前源 + 最近一次「哪个源失败、多久后重试」 | +//! | 失败 | 大版本 + 最后试到的源 + 「完整原因在日志里」+ 下一步（查网络 / 改顺序） | +//! +//! 「与当前实例要求的关系」是任务书第三条：**不许静默失败**。老版本 MC 要 8、新版本要 21/25， +//! 用户在列表里能直接看到「装这一档也起不来」（[`Fit`] 的两向措辞），不必等启动那一刻才发现。 +//! +//! 列表里的「已安装」判定来自**真扫盘的结论**（`state.runtimes`），不是另存一份安装记录。 + +mod result; + +use iced::widget::{column, container, row}; +use iced::{Alignment, Element, Length}; + +use unlucky_core::download::DownloadErrorKind; +use unlucky_core::game::java::catalog::{self, JdkChoice}; +use unlucky_design::color::Role; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; +use unlucky_i18n::{Catalog, Key}; + +use crate::app::components::selection::{chip, Chip}; +use crate::pages::frame::{divider, text_role_owned, BASE}; +use crate::pages::Message; +use crate::theme::Ui; + +use super::downloads::{Event, Job, Phase}; +use super::state::{Fit, State}; +use super::view::msg; +use super::Message as JavaMessage; + +/// 一整块（标题 + 口径 + 目录 + 结果）。 +pub(super) fn section<'a>(ui: &'a Ui, catalog: Catalog, state: &'a State) -> Element<'a, Message> { + let report = state.downloads.report(); + let mut block = column![].spacing(ui.space(Space::X2)).width(Length::Fill); + + block = block.push(text_role_owned( + ui, + TypeRole::BodyMedium, + true, + catalog.text(Key::SettingsJavaDownloadTitle).to_string(), + ui.color(Role::OnSurface), + )); + block = block.push(text_role_owned( + ui, + TypeRole::BodySmall, + false, + catalog.text(Key::SettingsJavaDownloadHint).to_string(), + ui.color(Role::OnSurfaceVariant), + )); + if let Some(refusal) = state.download_notice { + block = block.push(text_role_owned( + ui, + TypeRole::BodySmall, + false, + catalog.render( + Key::SettingsJavaDownloadRefused, + &[("reason", catalog.text(refusal.label()))], + ), + ui.color(Role::Error), + )); + } + if let Some(required) = &state.context.required { + block = block.push(text_role_owned( + ui, + TypeRole::BodySmall, + false, + catalog.render( + Key::SettingsJavaDownloadNeeded, + &[("requirement", required.describe().as_str())], + ), + ui.color(Role::OnSurface), + )); + } + + let recommended = super::downloads::recommend( + state.context.required.as_ref(), + &state.runtimes, + state.prefs.saved_auto_install, + ); + let busy = report.job.is_some(); + for choice in catalog::choices() { + block = block.push(choice_row( + ui, + catalog, + state, + *choice, + recommended == Some(choice.major), + busy, + )); + } + + if let Some(job) = &report.job { + block = block.push(divider(ui)); + block = block.push(running(ui, catalog, job)); + } + if let Some(success) = &report.success { + block = block.push(divider(ui)); + block = block.push(result::done(ui, catalog, success)); + } + if let Some(failure) = &report.failure { + block = block.push(divider(ui)); + block = block.push(result::failed(ui, catalog, failure, &report.tries)); + } + block.into() +} + +/// 目录里的一行：大版本 + 徽标 + 承接的发行版 + 与当前实例的关系 + 安装按钮。 +fn choice_row<'a>( + ui: &'a Ui, + catalog: Catalog, + state: &'a State, + choice: JdkChoice, + recommended: bool, + busy: bool, +) -> Element<'a, Message> { + let title = format!("Java {}", choice.major); + let mut badges = row![].spacing(ui.space(Space::X1)); + // M237：徽标是**禁用配色**（`Chip::badge` = 12% 容器 / 38% 内容），而这个板块整个住在 + // `frame::card` 里 ⇒ 底必须是卡底，否则徽标会把禁用色叠在画布色上。 + if choice.lts { + badges = badges.push(chip( + ui, + Chip::badge(catalog.text(Key::SettingsJavaDownloadLts)).base(BASE), + )); + } + if choice.baseline { + badges = badges.push(chip( + ui, + Chip::badge(catalog.text(Key::SettingsJavaDownloadBaseline)).base(BASE), + )); + } + if recommended { + badges = badges.push(chip( + ui, + Chip::badge(catalog.text(Key::SettingsJavaDownloadRecommended)).base(BASE), + )); + } + + let vendors = catalog::vendors_for( + choice.major, + &state.priority_vendors(), + state.effective.domestic, + ); + let vendors_line = if vendors.is_empty() { + catalog.text(Key::SettingsJavaDownloadNoVendor).to_string() + } else { + catalog.render( + Key::SettingsJavaDownloadVendors, + &[( + "vendors", + vendors + .iter() + .map(|vendor| vendor.display()) + .collect::>() + .join(" → ") + .as_str(), + )], + ) + }; + + let installed = state + .runtimes + .iter() + .find(|runtime| runtime.major == Some(choice.major)); + + let mut block = column![row![ + container( + column![ + text_role_owned( + ui, + TypeRole::BodyMedium, + recommended, + title, + ui.color(Role::OnSurface), + ), + badges, + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill), + ) + .width(Length::Fill), + install_button(ui, catalog, choice.major, installed.is_some(), busy), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill) + .align_y(Alignment::Center)] + .spacing(ui.space(Space::X1)) + .width(Length::Fill); + + block = block.push(text_role_owned( + ui, + TypeRole::BodySmall, + false, + vendors_line, + ui.color(Role::OnSurfaceVariant), + )); + if let Some(fit) = state.fit(Some(choice.major)) { + let (text, color) = fit_line(catalog, ui, fit); + block = block.push(text_role_owned(ui, TypeRole::BodySmall, false, text, color)); + } + if let Some(runtime) = installed { + block = block.push(text_role_owned( + ui, + TypeRole::BodySmall, + false, + catalog.render( + Key::SettingsJavaDownloadInstalled, + &[("path", runtime.display_home().as_str())], + ), + ui.color(Role::OnSurfaceVariant), + )); + } + block.into() +} + +/// 「装哪一档与当前实例合不合」那一行（两向措辞，来自 [`Fit`]）。 +fn fit_line(catalog: Catalog, ui: &Ui, fit: Fit) -> (String, iced::Color) { + match fit { + Fit::Ok => ( + catalog.text(Key::SettingsJavaDownloadFits).to_string(), + ui.color(Role::Primary), + ), + Fit::TooOld { required, .. } => ( + catalog.render( + Key::SettingsJavaDownloadTooLow, + &[("minimum", required.to_string().as_str())], + ), + ui.color(Role::Error), + ), + Fit::TooNew { maximum, .. } => ( + catalog.render( + Key::SettingsJavaDownloadTooHigh, + &[("maximum", maximum.to_string().as_str())], + ), + ui.color(Role::Error), + ), + } +} + +/// 安装按钮：已在跑的作业期间一律灰掉（同时只允许一个），已装过的写成「重装」。 +fn install_button<'a>( + ui: &'a Ui, + catalog: Catalog, + major: u32, + installed: bool, + busy: bool, +) -> Element<'a, Message> { + let label = catalog.text(if installed { + Key::SettingsJavaDownloadReinstall + } else { + Key::SettingsJavaDownloadAction + }); + if busy { + // 忙时那枚「下载」是**禁用配色**的徽标（不是可点 chip），同样叠在卡底上（M237）。 + return chip(ui, Chip::badge(label).base(BASE)); + } + chip( + ui, + Chip::filter(label, false, msg(JavaMessage::Download(major))).base(BASE), + ) +} + +/// 下载中：阶段 + 百分比 + 当前源 + 最近一次退避 / 换源。 +fn running<'a>(ui: &'a Ui, catalog: Catalog, job: &Job) -> Element<'a, Message> { + let header = catalog.render( + Key::SettingsJavaDownloadBusy, + &[("major", job.major.to_string().as_str())], + ); + let phase = match job.phase { + Phase::Preparing => catalog + .text(Key::SettingsJavaDownloadPhasePreparing) + .to_string(), + Phase::Downloading => match job.percent() { + Some(percent) => catalog.render( + Key::SettingsJavaDownloadPhaseDownloading, + &[ + ("percent", percent.to_string().as_str()), + ("done", result::mega(job.downloaded).as_str()), + ("total", result::mega(job.total.unwrap_or(0)).as_str()), + ], + ), + // 分母未知：只说已经下了多少，不给假的百分比。 + None => result::mega(job.downloaded), + }, + Phase::Verifying => catalog + .text(Key::SettingsJavaDownloadPhaseVerifying) + .to_string(), + Phase::Extracting => catalog + .text(Key::SettingsJavaDownloadPhaseExtracting) + .to_string(), + }; + let mut block = column![ + text_role_owned( + ui, + TypeRole::BodyMedium, + true, + header, + ui.color(Role::Primary), + ), + text_role_owned( + ui, + TypeRole::BodySmall, + false, + phase, + ui.color(Role::OnSurface), + ), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill); + if let Some(source) = &job.source { + block = block.push(text_role_owned( + ui, + TypeRole::BodySmall, + false, + catalog.render( + Key::SettingsJavaDownloadSource, + &[("source", source.as_str())], + ), + ui.color(Role::OnSurfaceVariant), + )); + } + if let Some(event) = &job.last { + let text = event_line(catalog, event); + block = block.push(text_role_owned( + ui, + TypeRole::BodySmall, + false, + text, + ui.color(Role::OnSurfaceVariant), + )); + } + block.into() +} + +/// 「哪个源失败 / 多久后重试」或「换源」那一条。 +fn event_line(catalog: Catalog, event: &Event) -> String { + match event { + Event::Retry { + source, + kind, + attempt, + retry_in_ms, + } => catalog.render( + Key::SettingsJavaDownloadRetry, + &[ + ("source", source.as_str()), + ("reason", source_reason(catalog, *kind).as_str()), + ("attempt", attempt.to_string().as_str()), + ( + "seconds", + format!( + "{:.1}", + f64::from(u32::try_from(*retry_in_ms).unwrap_or(u32::MAX)) / 1000.0 + ) + .as_str(), + ), + ], + ), + Event::Switched { from, to } => catalog.render( + Key::SettingsJavaDownloadSwitch, + &[("from", from.as_str()), ("to", to.as_str())], + ), + } +} + +/// `DownloadErrorKind` → 页面文案（core 的原句只进日志，见 `downloads.rs`）。 +pub(super) fn source_reason(catalog: Catalog, kind: DownloadErrorKind) -> String { + let key = match kind { + DownloadErrorKind::NotFound => Key::SettingsJavaSourceReasonNotFound, + DownloadErrorKind::ServerError => Key::SettingsJavaSourceReasonServer, + DownloadErrorKind::Timeout => Key::SettingsJavaSourceReasonTimeout, + DownloadErrorKind::Network => Key::SettingsJavaSourceReasonNetwork, + DownloadErrorKind::Integrity => Key::SettingsJavaSourceReasonIntegrity, + DownloadErrorKind::Io => Key::SettingsJavaSourceReasonIo, + DownloadErrorKind::InvalidRequest + | DownloadErrorKind::RangeUnsupported + | DownloadErrorKind::AllSourcesFailed => Key::SettingsJavaSourceReasonOther, + }; + catalog.text(key).to_string() +} diff --git a/crates/app-iced/src/pages/settings/java/download_view/result.rs b/crates/app-iced/src/pages/settings/java/download_view/result.rs new file mode 100644 index 0000000..e956989 --- /dev/null +++ b/crates/app-iced/src/pages/settings/java/download_view/result.rs @@ -0,0 +1,128 @@ +//! 「下载成功 / 下载失败」那两行 + 字节格式化（M197）。 +//! +//! 从 `download_view.rs` 拆出来守 400 行硬线：那个文件只剩「目录 / 下载中」两态， +//! 结果两态与单位换算在这里。 + +use iced::widget::column; +use iced::{Element, Length}; + +use unlucky_design::color::Role; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; +use unlucky_i18n::{Catalog, Key}; + +use crate::pages::frame::text_role_owned; +use crate::pages::Message; +use crate::theme::Ui; + +use super::super::downloads::{Failure, Success, Try}; + +/// 成功：装到哪 + 命中的源（或「复用已装，没走网络」）。 +pub(super) fn done<'a>(ui: &'a Ui, catalog: Catalog, success: &Success) -> Element<'a, Message> { + let text = if success.reused { + catalog.render( + Key::SettingsJavaDownloadDoneReused, + &[ + ("major", success.major.to_string().as_str()), + ("vendor", success.vendor), + ("root", success.root.as_str()), + ], + ) + } else { + catalog.render( + Key::SettingsJavaDownloadDone, + &[ + ("major", success.major.to_string().as_str()), + ("vendor", success.vendor), + ("root", success.root.as_str()), + ("source", success.source.as_deref().unwrap_or("?")), + ], + ) + }; + text_role_owned( + ui, + TypeRole::BodySmall, + false, + text, + ui.color(Role::OnSurface), + ) +} + +/// 失败：大版本 + 试过哪些源（各自的失败分类）+ 下一步（core 的原句只进日志）。 +pub(super) fn failed<'a>( + ui: &'a Ui, + catalog: Catalog, + failure: &Failure, + tries: &[Try], +) -> Element<'a, Message> { + let text = match (&failure.source, failure.kind) { + (Some(source), _) => catalog.render( + Key::SettingsJavaDownloadFailed, + &[ + ("major", failure.major.to_string().as_str()), + ("source", source.as_str()), + ], + ), + (None, _) => catalog.render( + Key::SettingsJavaDownloadFailedNoSource, + &[("major", failure.major.to_string().as_str())], + ), + }; + let mut block = column![text_role_owned( + ui, + TypeRole::BodySmall, + false, + text, + ui.color(Role::Error) + )] + .spacing(ui.space(Space::X1)) + .width(Length::Fill); + // 「试过哪些源、各自为什么失败」：任务书那条「失败要能说出命中哪个源与退避原因」在 + // **最终失败**那一刻的落点（过程中的实时退避在 `download_view::running` 那一块）。 + if !tries.is_empty() { + block = block.push(text_role_owned( + ui, + TypeRole::BodySmall, + false, + catalog + .text(Key::SettingsJavaDownloadTriedHeader) + .to_string(), + ui.color(Role::OnSurfaceVariant), + )); + for attempt in tries.iter().take(4) { + block = block.push(text_role_owned( + ui, + TypeRole::BodySmall, + false, + catalog.render( + Key::SettingsJavaDownloadTried, + &[ + ("source", attempt.source.as_str()), + ( + "reason", + super::source_reason(catalog, attempt.kind).as_str(), + ), + ], + ), + ui.color(Role::OnSurfaceVariant), + )); + } + } + block = block.push(text_role_owned( + ui, + TypeRole::BodySmall, + false, + catalog + .text(Key::SettingsJavaDownloadFailedHint) + .to_string(), + ui.color(Role::OnSurfaceVariant), + )); + block.into() +} + +/// 字节 → 「88.4 MB」（分母未知时也只说下了多少）。 +pub(super) fn mega(bytes: u64) -> String { + #[allow(clippy::cast_precision_loss)] + let mb = bytes as f64 / (1024.0 * 1024.0); + format!("{mb:.1} MB") +} diff --git a/crates/app-iced/src/pages/settings/java/downloads.rs b/crates/app-iced/src/pages/settings/java/downloads.rs new file mode 100644 index 0000000..0535e2f --- /dev/null +++ b/crates/app-iced/src/pages/settings/java/downloads.rs @@ -0,0 +1,389 @@ +//! 「下载一个 JDK」的作业与状态（M197）。 +//! +//! 用户原话：「自动下载 jdk17 作为基准版本，后续在设置中提供多版本可供用户下载。 +//! （国内用户走 github release 记得配置加速镜像）」——本文件负责**真下**：选好大版本之后 +//! 起一个后台线程跑 `core::game::java::install`（查版本 → 回退链 → 下载引擎 → 解压 → 探测）， +//! 界面按快照读进度。 +//! +//! ## 为什么又是「后台线程 + 快照」 +//! +//! 与 M175 的扫描同一条理由（`store.rs` 里记了完整推导）：本 crate 的执行器是 `thread-pool`， +//! 而一次 JDK 下载要的是**进度（百分比）+ 失败换源原因 + 不卡 UI**。快照的代价是一把短锁 + +//! 每拍一次比较；好处是窗口关掉之后不会往死掉的 channel 里写。 +//! +//! ## 进度与「失败退避原因」从哪来 +//! +//! 引擎的 [`ProgressEmitter`] 会把**每一次尝试**都吐出来： +//! +//! | 事件 | 界面拿它说什么 | +//! |---|---| +//! | `Started { total_bytes }` | 分母（未知就不显示百分比，不做假进度） | +//! | `Progress { downloaded }` | 百分比 | +//! | `SourceFailed { source, kind, attempt, retry_in_ms }` | 「清华 TUNA 失败（服务器报错）；2 秒后重试第 2 次」 | +//! | `SourceSwitched { from, to }` | 「换源：A → B」 | +//! | `Completed { source }` | 「命中的源」（**装完之后要能说出来**） | +//! | `Verifying` | 校验阶段 | +//! +//! `SourceFailed` 里的 `reason` 是 core 的中文句子，**只进 stderr 日志**；界面按结构化的 +//! `kind` 选 i18n 文案（M175 r2 P3-3 的同一条纪律：core 的句子不进双语界面）。 +//! +//! ## 为什么不复用 `download::shared::engine_for` +//! +//! `engine_for` 给的是 `Arc`，而 `with_progress` 要**拿走**引擎（`self`）。 +//! 要让共享引擎带「这一次作业的」进度观察者，得把引擎内部的 `progress` 改成可插拔的观察者 +//! 名单——那是引擎侧的范围（M193 的镜像/并发那一摊），本 mission 不碰。代价写在 +//! [`engine::engine_with`] 上：这一次作业有一条自己的连接池，但**盘上的**缓存与健康度仍然共用。 +//! +//! ## 同时只允许一个 +//! +//! [`Slot::start`] 的判据是「线程还活着」（`running`）。理由与扫描的取消位一致：两个作业抢同一个 +//! 归档缓存目录会互相搬走对方的中间文件（`PartFile` 的会话命名只隔进程，不隔线程）。 + +use std::path::PathBuf; +use std::sync::atomic::{AtomicBool, Ordering}; +use std::sync::{Arc, Mutex}; + +use unlucky_core::download::blocking::block_on; +use unlucky_core::download::{DownloadErrorKind, ProgressEmitter, ProgressEvent}; +use unlucky_core::game::java::{ + install, InstallRequest, InstalledJdk, JavaError, JavaErrorKind, JavaInstallRoot, JdkVendor, +}; + +/// 推荐判据（`java.auto_install` 的消费者）与引擎装配各自一个文件，见模块文档。 +mod engine; +mod recommend; +mod refusal; + +pub use engine::{gh_proxy_of_config, GhProxy}; +pub use recommend::recommend; +pub use refusal::Refusal; + +#[cfg(test)] +mod tests; + +/// 一次作业的阶段。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Phase { + /// 查版本（还没开始下字节） + Preparing, + /// 下归档 + Downloading, + /// 校验摘要 + Verifying, + /// 解压 + 探测（下载已经完成） + Extracting, +} + +/// 一条「退避 / 换源」记录（界面上那一行）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum Event { + /// 某个源失败（`retry_in_ms = 0` 表示不再重试、直接换源） + Retry { + /// 源标识（`tuna` / `github` / `huawei` …） + source: String, + /// 结构化失败分类（文案层按它选 i18n key） + kind: DownloadErrorKind, + /// 第几次尝试（从 1 起，给人看） + attempt: u32, + /// 下一次重试的等待（毫秒） + retry_in_ms: u64, + }, + /// 换源 + Switched { + /// 原源 + from: String, + /// 新源 + to: String, + }, +} + +/// 正在跑的作业。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Job { + /// 目标大版本 + pub major: u32, + /// 阶段 + pub phase: Phase, + /// 已下载字节 + pub downloaded: u64, + /// 总字节（`None` = 服务器没给长度，不显示百分比） + pub total: Option, + /// 当前 / 命中的源 + pub source: Option, + /// 最近一条换源 / 退避记录 + pub last: Option, +} + +impl Job { + fn new(major: u32) -> Self { + Self { + major, + phase: Phase::Preparing, + downloaded: 0, + total: None, + source: None, + last: None, + } + } + + /// 百分比（`None` = 分母未知）。 + #[must_use] + pub fn percent(&self) -> Option { + let total = self.total.filter(|total| *total > 0)?; + let percent = self.downloaded.saturating_mul(100) / total; + Some(u32::try_from(percent.min(100)).unwrap_or(100)) + } +} + +/// 一次失败（`kind` 是 core 的稳定分类，文案层自己翻）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Failure { + /// 目标大版本 + pub major: u32, + /// core 的错误分类 + pub kind: JavaErrorKind, + /// 最后试到的源（查版本阶段就失败时没有） + pub source: Option, +} + +/// 一次成功。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Success { + /// 目标大版本 + pub major: u32, + /// 实际装上的发行版（展示名） + pub vendor: &'static str, + /// 托管目录 + pub root: String, + /// `bin/java[.exe]` + pub binary: String, + /// 命中的下载源（`None` = 复用已装，没走网络） + pub source: Option, + /// 是否完全复用了已装的那一份 + pub reused: bool, +} + +/// 「这一次作业试过的一个源」（失败态逐条列出来：哪个源、为什么）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Try { + /// 源标识 + pub source: String, + /// 结构化失败分类 + pub kind: DownloadErrorKind, +} + +/// 界面读的那份快照。 +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct Report { + /// 正在跑的作业（`None` = 没在跑） + pub job: Option, + /// 这一次作业试过的源（按首次失败顺序，同一源只留一条） + pub tries: Vec, + /// 上一次失败 + pub failure: Option, + /// 上一次成功 + pub success: Option, +} + +impl Report { + /// 记一跳失败（同一源只留第一条：界面要的是「试过哪些」，不是重试次数）。 + fn record_try(&mut self, source: &str, kind: DownloadErrorKind) { + if self.tries.iter().any(|known| known.source == source) { + return; + } + self.tries.push(Try { + source: source.to_string(), + kind, + }); + } +} + +/// 一次作业的入参（app 层算好：装到哪、按什么顺序、缓存放哪）。 +#[derive(Debug, Clone)] +pub struct Request { + /// 目标大版本 + pub major: u32, + /// 下载缓存根（`/cache`，与其它下载共用） + pub cache_root: PathBuf, + /// 托管落点（`JavaInstallRoot::resolve` 的结果） + pub install_root: JavaInstallRoot, + /// 用户优先级（`java.vendorPriority`；空 = 地区默认序） + pub priority: Vec, + /// `download.gh_proxy`（`Builtin` = 跟随内置默认；`Off` = 关；`Prefix` = 覆盖前缀） + pub gh_proxy: GhProxy, +} + +/// 作业槽：快照 + 「线程还活着」。 +/// +/// 内部是 `Arc`：`State` 会被整体替换（hydrate / 截图种子），而作业线程要活得比某一次赋值更久。 +#[derive(Debug, Clone, Default)] +pub struct Slot { + inner: Arc, +} + +#[derive(Debug, Default)] +struct Inner { + report: Mutex, + running: AtomicBool, +} + +impl Slot { + /// 当前快照。 + #[must_use] + pub fn report(&self) -> Report { + self.inner + .report + .lock() + .map(|report| report.clone()) + .unwrap_or_default() + } + + /// 有没有作业在跑。 + #[must_use] + pub fn busy(&self) -> bool { + self.inner.running.load(Ordering::SeqCst) + } + + /// 发起一次安装（已在跑 ⇒ 什么都不做，返回 `false`）。 + pub fn start(&self, request: Request) -> bool { + if self.inner.running.swap(true, Ordering::SeqCst) { + return false; + } + if let Ok(mut report) = self.inner.report.lock() { + *report = Report { + job: Some(Job::new(request.major)), + tries: Vec::new(), + failure: None, + success: None, + }; + } + let slot = self.clone(); + std::thread::spawn(move || slot.run(request)); + true + } + + /// 线程体：挂进度发射器 → 跑 install → 把结论写回快照。 + fn run(self, request: Request) { + let (emitter, mut events) = ProgressEmitter::channel(); + let feed = self.clone(); + // 抽干事件的那条线：`blocking_recv` 在普通线程上不 panic（tokio 只禁异步上下文里调）。 + let drain = std::thread::spawn(move || { + while let Some(event) = events.blocking_recv() { + feed.apply(event); + } + }); + let engine = engine::engine_with(&request.cache_root, emitter, &request.gh_proxy); + let install_request = InstallRequest::new(request.major).with_priority(request.priority); + let result = block_on(install(&engine, &request.install_root, install_request)); + // 引擎丢掉 ⇒ 发射器丢掉 ⇒ 抽干线程读到 `None` 自然退出。 + drop(engine); + let _ = drain.join(); + self.finish(result, request.major); + self.inner.running.store(false, Ordering::SeqCst); + } + + /// 一条引擎事件 → 快照（纯函数式：界面只读结论）。 + fn apply(&self, event: ProgressEvent) { + let Ok(mut report) = self.inner.report.lock() else { + return; + }; + // 先记「这一跳试过哪个源、为什么失败」——失败态要在界面上逐条列出来。 + if let ProgressEvent::SourceFailed { source, kind, .. } = &event { + report.record_try(source, *kind); + } + let Some(job) = report.job.as_mut() else { + return; + }; + match event { + ProgressEvent::Started { total_bytes, .. } => { + job.phase = Phase::Downloading; + job.total = total_bytes; + } + ProgressEvent::Progress { + downloaded, + total_bytes, + .. + } => { + job.phase = Phase::Downloading; + job.downloaded = downloaded; + if total_bytes.is_some() { + job.total = total_bytes; + } + } + ProgressEvent::SourceFailed { + source, + kind, + reason, + attempt, + retry_in_ms, + .. + } => { + // core 的原句只进日志：界面要双语，不能直接吐中文句子。 + eprintln!("[java] 源 {source} 失败（{}）：{reason}", kind.as_str()); + job.source = Some(source.clone()); + job.last = Some(Event::Retry { + source, + kind, + attempt: attempt.saturating_add(1), + retry_in_ms, + }); + } + ProgressEvent::SourceSwitched { from, to, .. } => { + job.source = Some(to.clone()); + job.last = Some(Event::Switched { from, to }); + } + ProgressEvent::Verifying { .. } => job.phase = Phase::Verifying, + ProgressEvent::Completed { source, .. } => { + job.phase = Phase::Extracting; + job.source = Some(source); + } + ProgressEvent::Failed { kind, message, .. } => { + eprintln!("[java] 下载失败（{}）：{message}", kind.as_str()); + } + } + } + + /// install 的结论 → 快照。 + fn finish(&self, result: Result, major: u32) { + let Ok(mut report) = self.inner.report.lock() else { + return; + }; + let source = report.job.as_ref().and_then(|job| job.source.clone()); + report.job = None; + match result { + Ok(installed) => { + report.failure = None; + report.success = Some(Success { + major: installed.major, + vendor: installed.vendor.display(), + root: installed.root.display().to_string(), + binary: installed.binary().display().to_string(), + source: installed.downloaded.clone().or(source), + reused: installed.reused(), + }); + } + Err(error) => { + eprintln!( + "[java] Java {major} 安装失败（{}）：{}", + error.kind().as_str(), + error.message() + ); + report.success = None; + report.failure = Some(Failure { + major, + kind: error.kind(), + source, + }); + } + } + } + + /// 截图种子用：把快照钉成某一档（只给 `--screenshot` 走，见 `seed.rs`）。 + /// + /// 产品路径不调它：真进度只能来自 [`Slot::run`] 那条线程。 + pub fn seed_report(&self, report: Report) { + if let Ok(mut slot) = self.inner.report.lock() { + *slot = report; + } + } +} diff --git a/crates/app-iced/src/pages/settings/java/downloads/engine.rs b/crates/app-iced/src/pages/settings/java/downloads/engine.rs new file mode 100644 index 0000000..900a36b --- /dev/null +++ b/crates/app-iced/src/pages/settings/java/downloads/engine.rs @@ -0,0 +1,110 @@ +//! 带进度发射器的下载引擎（M197）：一次 JDK 安装一个实例 + `download.gh_proxy` 的真消费者。 +//! +//! 从 `downloads.rs` 拆出来（行数 + 口径独立：这里只说「为什么不用共享引擎」）。 +//! 装配口径与 `core::download::shared::build` 一致，只多挂一个 `ProgressEmitter`。 +//! +//! ## gh-proxy 的取值链（任务书那句「（默认值可改）」的落点） +//! +//! | `download.gh_proxy` | [`GhProxy`] | 效果 | +//! |---|---|---| +//! | 空（出厂） | [`GhProxy::Builtin`] | 跟随内置默认：`region.json` 判成镜像优先时用 `mirrors.json` 里的 `gh-proxy.com` | +//! | `off` / `none` / `direct` / `disable` | [`GhProxy::Off`] | `RegionProfile::with_gh_proxy(None)` —— 一个 gh-proxy 候选都不生成 | +//! | 其它非空值 | [`GhProxy::Prefix`] | 用这个前缀覆盖（仍然只在镜像优先/国内判定时启用） | +//! +//! **为什么只改 `RegionProfile`**：真正决定「要不要生成 gh-proxy 候选」的是 +//! `MirrorTable::gh_proxy_candidates`，它读的是 `region.gh_proxy` 与 `region.mode`；表里的 +//! `gh_proxies` 只是「已知可用前缀」的留档（**无生产读者**）。M193 已经把 `set_gh_proxy` / +//! `default_gh_proxy` 从表上删掉了，原因正是它们改的是那张没人读的表。所以本文件只动档案， +//! 并在 `downloads/tests.rs` 里用**候选链出现该前缀**来证明它真的生效。 +//! +//! 内置默认值本身没有动（`mirrors.json` 仍是 `https://gh-proxy.com/`）：空串这一档等于 +//! 「老文件没有这个键」的行为。 + +use std::path::Path; +use std::sync::Arc; + +use unlucky_core::download::cache::now_ms; +use unlucky_core::download::config::KEY_GH_PROXY; +use unlucky_core::download::region::{decide_from, load_cached}; +use unlucky_core::download::region_system::detect_signals; +use unlucky_core::download::{ + ContentCache, DownloadEngine, EngineConfig, HealthRegistry, MirrorTable, ProgressEmitter, +}; +use unlucky_core::setting::keys::launcher_schema; +use unlucky_core::setting::store::SettingStore; + +/// `download.gh_proxy` 的三种取值。 +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub enum GhProxy { + /// 跟随内置默认（`region.json` 的判定 + `mirrors.json` 的前缀） + #[default] + Builtin, + /// 明确关掉（`with_gh_proxy(None)`） + Off, + /// 用这个前缀覆盖 + Prefix(String), +} + +/// 设置原文 → 取值（纯函数：`off` 与 URL 的边界在这里定死，不散落在别处）。 +/// +/// `off` / `none` / `direct` / `disable` 都认（大小写不敏感、前后空白忽略）：用户拿哪个词表达 +/// 「关掉」都合理，专门要求某一个反而会造出「填了没生效」的坑。 +#[must_use] +pub fn gh_proxy_from(raw: &str) -> GhProxy { + let text = raw.trim(); + if text.is_empty() { + return GhProxy::Builtin; + } + let lowered = text.to_ascii_lowercase(); + if matches!( + lowered.as_str(), + "off" | "none" | "direct" | "disable" | "disabled" | "no" + ) { + return GhProxy::Off; + } + GhProxy::Prefix(text.to_string()) +} + +/// 从 `launcher.json` 读 `download.gh_proxy`（读不到 / 没有文件 = 跟随内置默认）。 +/// +/// 键名走 core 的 [`KEY_GH_PROXY`]，不写字面量：同一件事的第二个字符串就是下一次「改名只改一处」的种子 +/// （M207：重试次数、UA 之后又一处副本）。绑定关系由 core 的 +/// `setting::keys::proxy::the_gh_proxy_key_is_bound_to_the_schema_registration` 钉住。 +#[must_use] +pub fn gh_proxy_of_config(config: &Path) -> GhProxy { + let store = SettingStore::load(config, launcher_schema()); + gh_proxy_from(store.doc().effective_str(KEY_GH_PROXY).unwrap_or_default()) +} + +/// 带进度发射器的引擎（装配口径与 `download::shared::build` 一致，只多挂一个 emitter + gh-proxy 覆盖）。 +/// +/// 为什么不再走 `shared::engine_for`：那个登记处交出的是 `Arc`，而挂进度要 +/// 拿走引擎（`with_progress(self)`）。要让共享引擎带「按作业」的观察者，得改引擎内部的 +/// `progress` 字段为观察者名单——那是引擎侧（M193 的镜像/并发那摊）的范围。 +/// 代价：一次 JDK 安装有自己的连接池；**盘上的** `health.json` / `index.json` / `region.json` +/// 是同一个，所以换源经验仍然跨作业累积。 +pub(super) fn engine_with( + cache_root: &Path, + progress: ProgressEmitter, + gh_proxy: &GhProxy, +) -> DownloadEngine { + let now = now_ms(); + let profile = load_cached(&cache_root.join("region.json"), now).unwrap_or_else(|| { + let profile = decide_from(&detect_signals(), now); + let _ = std::fs::create_dir_all(cache_root); + profile + }); + let profile = match gh_proxy { + GhProxy::Builtin => profile, + GhProxy::Off => profile.with_gh_proxy(None), + GhProxy::Prefix(prefix) => profile.with_gh_proxy(Some(prefix)), + }; + DownloadEngine::new( + EngineConfig::default(), + Arc::new(MirrorTable::builtin()), + Arc::new(profile), + Arc::new(HealthRegistry::open_in(cache_root, now)), + Arc::new(ContentCache::open(cache_root)), + ) + .with_progress(progress) +} diff --git a/crates/app-iced/src/pages/settings/java/downloads/recommend.rs b/crates/app-iced/src/pages/settings/java/downloads/recommend.rs new file mode 100644 index 0000000..9085b84 --- /dev/null +++ b/crates/app-iced/src/pages/settings/java/downloads/recommend.rs @@ -0,0 +1,42 @@ +//! 「现在该推荐哪一档」（M197）：`java.auto_install` 的唯一消费者。 +//! +//! 从 `downloads.rs` 拆出来（那个文件加了作业槽与事件映射之后越过 400 行硬线）。 +//! 纯函数：只读「当前实例要求 + 已扫到的运行时 + 这个键」，不联网、不落盘。 + +use unlucky_core::game::java::catalog; + +use crate::pages::settings::java::context::Requirement; +use crate::pages::settings::java::row::RuntimeRow; + +/// 「现在该推荐哪一档」：`java.auto_install` 的真实消费者。 +/// +/// 语义（就是界面上那句 hint）：**开着**时，只有当「扫到的 JDK 里没有一个满足当前实例的要求」 +/// （没有实例时 = 一个 JDK 都没有）才推荐一档；推荐的是当前实例最低要求对齐到目录的那一档 +/// （[`catalog::default_major`]，没有实例时 = 基准 17）。**关掉**就一律不推荐，用户自己挑。 +/// +/// 为什么不直接自动开始下载：那是 180 MiB 起步、且用户可能只想手动指定 JAVA_HOME。 +/// 「替你选好一档 + 一句话说明」把决定权留在用户手上，同时把「该装哪个」这件知识给出去。 +#[must_use] +pub fn recommend( + required: Option<&Requirement>, + runtimes: &[RuntimeRow], + auto_install: bool, +) -> Option { + if !auto_install { + return None; + } + let satisfied = match required { + Some(required) => runtimes.iter().any(|runtime| { + runtime + .major + .is_some_and(|major| required.satisfied_by(major)) + }), + None => !runtimes.is_empty(), + }; + if satisfied { + return None; + } + Some(catalog::default_major( + required.map(|required| required.minimum), + )) +} diff --git a/crates/app-iced/src/pages/settings/java/downloads/refusal.rs b/crates/app-iced/src/pages/settings/java/downloads/refusal.rs new file mode 100644 index 0000000..a281c99 --- /dev/null +++ b/crates/app-iced/src/pages/settings/java/downloads/refusal.rs @@ -0,0 +1,34 @@ +//! 「下载按钮为什么没开始」的五档原因（M197）。 +//! +//! 从 `downloads.rs` 拆出来守 400 行硬线（与 `downloads/tests.rs` 同一种拆法）。 +//! 点了没反应是禁止的：每一种拒绝都要在下载区顶上写清是哪一档。 + +/// 「没开始」的四种原因（每一种都要在界面上说清，不许点了没反应）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Refusal { + /// 目录里没有这个大版本 + UnknownMajor, + /// 这一档在这台机器上没有发行版承接 + NoVendor, + /// 已经有一个作业在跑 + Busy, + /// 没有可写的设置文件 + NoStorage, + /// 有设置文件，但安装根解析不出来（standard 模式拿不到 %APPDATA% 之类的系统目录） + RootUnresolved, +} + +impl Refusal { + /// 文案 key（页面自己的拒绝原因，与 `state::Refusal` 同一套渲染路径）。 + #[must_use] + pub const fn label(self) -> unlucky_i18n::Key { + use unlucky_i18n::Key; + match self { + Self::UnknownMajor => Key::SettingsJavaReasonDownloadUnknownMajor, + Self::NoVendor => Key::SettingsJavaReasonDownloadNoVendor, + Self::Busy => Key::SettingsJavaReasonDownloadBusy, + Self::NoStorage => Key::SettingsJavaNoStorage, + Self::RootUnresolved => Key::SettingsJavaReasonRootUnresolved, + } + } +} diff --git a/crates/app-iced/src/pages/settings/java/downloads/tests.rs b/crates/app-iced/src/pages/settings/java/downloads/tests.rs new file mode 100644 index 0000000..f7b6a59 --- /dev/null +++ b/crates/app-iced/src/pages/settings/java/downloads/tests.rs @@ -0,0 +1,313 @@ +//! 「下载一个 JDK」的作业与状态（M197）：纯事件 → 快照的映射守卫。 +//! +//! 从 `downloads.rs` 拆出来守 400 行硬线（与 `tests/runtime.rs` 同一种拆法：断言跟着它守的 +//! 东西走，模块文件只留实现）。这些用例**不联网**：喂的是引擎会吐的那几种 `ProgressEvent`。 +use super::{Event, Failure, Job, Phase, Report, Slot}; +use unlucky_core::download::types::DownloadId; +use unlucky_core::download::{DownloadErrorKind, ProgressEvent}; +use unlucky_core::game::java::JavaErrorKind; + +/// 一条下载事件链 → 界面能看到「百分比 + 命中哪个源」。 +/// +/// 变异证明：把 `apply` 里 `ProgressEvent::Progress` 那一臂的 `job.downloaded = downloaded` +/// 删掉 ⇒ 本用例红（百分比恒为 0）。 +#[test] +fn progress_events_fill_the_percent_and_the_source() { + let slot = Slot::default(); + slot.seed_report(Report { + job: Some(Job::new(21)), + ..Report::default() + }); + let id = DownloadId::next(); + slot.apply(ProgressEvent::Started { + id, + kind: unlucky_core::download::ResourceKind::JavaRuntime, + url: "https://example.invalid/jdk.zip".to_string(), + dest: "jdk.zip".to_string(), + candidates: 2, + total_bytes: Some(200), + }); + slot.apply(ProgressEvent::Progress { + id, + downloaded: 50, + total_bytes: Some(200), + }); + let job = slot.report().job.expect("作业还在"); + assert_eq!(job.phase, Phase::Downloading); + assert_eq!(job.percent(), Some(25), "50/200 = 25%"); + slot.apply(ProgressEvent::Completed { + id, + bytes: 200, + from_cache: false, + source: "tuna".to_string(), + elapsed_ms: 10, + }); + let job = slot.report().job.expect("作业还在"); + assert_eq!(job.phase, Phase::Extracting, "下完就该进解压阶段"); + assert_eq!(job.source.as_deref(), Some("tuna"), "命中哪个源要说得出"); +} + +/// 分母未知时**不做假进度**（`percent()` 给 `None`）。 +#[test] +fn an_unknown_total_shows_no_percent() { + let slot = Slot::default(); + slot.seed_report(Report { + job: Some(Job::new(17)), + ..Report::default() + }); + slot.apply(ProgressEvent::Progress { + id: DownloadId::next(), + downloaded: 1024, + total_bytes: None, + }); + assert_eq!(slot.report().job.expect("作业").percent(), None); +} + +/// 退避与换源要留在快照里（界面那一行「A 失败；2 秒后重试第 2 次」/「换源」）。 +/// +/// 变异证明：把 `SourceFailed` 那一臂的 `job.last = Some(Event::Retry { .. })` 删掉 +/// ⇒ 本用例红。 +#[test] +fn retries_and_switches_are_kept_for_the_ui() { + let slot = Slot::default(); + slot.seed_report(Report { + job: Some(Job::new(8)), + ..Report::default() + }); + let id = DownloadId::next(); + slot.apply(ProgressEvent::SourceFailed { + id, + source: "tuna".to_string(), + kind: DownloadErrorKind::ServerError, + reason: "服务器 503".to_string(), + attempt: 1, + will_retry: true, + retry_in_ms: 2_000, + }); + assert_eq!( + slot.report().job.expect("作业").last, + Some(Event::Retry { + source: "tuna".to_string(), + kind: DownloadErrorKind::ServerError, + attempt: 2, + retry_in_ms: 2_000, + }) + ); + slot.apply(ProgressEvent::SourceSwitched { + id, + from: "tuna".to_string(), + to: "ustc".to_string(), + }); + let job = slot.report().job.expect("作业"); + assert_eq!(job.source.as_deref(), Some("ustc")); + assert_eq!( + job.last, + Some(Event::Switched { + from: "tuna".to_string(), + to: "ustc".to_string(), + }) + ); +} + +/// 「该推荐哪一档」：`java.auto_install` 的真实消费者（界面上那行「为当前实例推荐这一档」）。 +/// +/// 变异证明：把 `recommend` 开头 `if !auto_install { return None; }` 删掉 ⇒ 关掉那一档红； +/// 把 `satisfied` 判据写成恒 `false` ⇒ 「已满足就不推荐」那一档红。 +#[test] +fn auto_install_decides_whether_a_major_is_recommended() { + use super::recommend; + use crate::pages::settings::java::context::Requirement; + use crate::pages::settings::java::row::RuntimeRow; + + fn row(major: u32) -> RuntimeRow { + RuntimeRow { + binary: format!("C:/jdk-{major}/bin/java.exe"), + version: format!("openjdk version \"{major}.0.1\""), + major: Some(major), + vendor: Some("Temurin".to_string()), + source: "system", + } + } + + let required = Requirement { + instance: "生存服".to_string(), + version: "1.20.5".to_string(), + minimum: 21, + maximum: None, + }; + let none: &[RuntimeRow] = &[]; + assert_eq!(recommend(Some(&required), none, true), Some(21)); + assert_eq!(recommend(Some(&required), none, false), None); + let satisfied = [row(21)]; + assert_eq!(recommend(Some(&required), &satisfied, true), None); + let too_old = [row(17)]; + assert_eq!( + recommend(Some(&required), &too_old, true), + Some(21), + "手里只有 17、实例要 21 时照样推荐 21" + ); + assert_eq!( + recommend(None, none, true), + Some(17), + "没有实例时推荐基准 17" + ); + assert_eq!(recommend(None, &satisfied, true), None); +} + +/// 真下载一次（`--ignored`，需要网络）：装到临时目录并确认 `bin/java` 存在。 +/// +/// 这是「真入口」的端到端证据：`Slot::start` → `engine_with`（镜像表 / 地区 / 健康度）→ +/// `java::install`（查版本 → 回退链 → 下载 → 解压 → 探测）。默认不跑：它会下 ~180 MB。 +#[test] +#[ignore = "真下载（网络 + 数百 MB），用 cargo test -- --ignored 手动跑"] +fn the_real_download_installs_a_usable_jdk() { + use super::{Request, Slot}; + use unlucky_core::game::java::JavaInstallRoot; + + let dir = std::env::temp_dir().join(format!("ull-java-install-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&dir); + std::fs::create_dir_all(dir.join("cache")).expect("temp"); + let slot = Slot::default(); + assert!(slot.start(Request { + major: 21, + cache_root: dir.join("cache"), + install_root: JavaInstallRoot::custom(dir.join("jdks")), + priority: Vec::new(), + gh_proxy: super::GhProxy::Builtin, + })); + // 失败/panic 也要清理：这条用例会真下 ~180 MB，留在系统 temp 里是最贵的垃圾。 + struct Cleanup(std::path::PathBuf); + impl Drop for Cleanup { + fn drop(&mut self) { + let _ = std::fs::remove_dir_all(&self.0); + } + } + let _cleanup = Cleanup(dir.clone()); + + let deadline = std::time::Instant::now() + std::time::Duration::from_secs(900); + while slot.busy() && std::time::Instant::now() < deadline { + std::thread::sleep(std::time::Duration::from_millis(200)); + } + assert!(!slot.busy(), "作业应在 15 分钟内结束"); + let report = slot.report(); + if let Some(failure) = &report.failure { + panic!("安装失败：{failure:?}"); + } + let success = report.success.expect("应成功"); + assert!( + std::path::Path::new(&success.binary).is_file(), + "bin/java 应存在：{}", + success.binary + ); +} + +/// 失败要留档：分类 + 大版本 + 最后试到的源（界面靠这三样说清「为什么没装成」）。 +/// +/// 变异证明：把 `finish` 的 `Err` 分支里 `report.failure = Some(...)` 删掉 ⇒ 本用例红。 +#[test] +fn a_failure_is_kept_with_its_kind_and_source() { + let slot = Slot::default(); + slot.seed_report(Report { + job: Some(Job { + source: Some("tuna".to_string()), + ..Job::new(21) + }), + ..Report::default() + }); + slot.finish( + Err(unlucky_core::game::java::JavaError::new( + JavaErrorKind::Metadata, + "没有装成".to_string(), + )), + 21, + ); + let report = slot.report(); + assert!(report.success.is_none()); + assert!(report.job.is_none(), "失败之后不该还挂着作业"); + let failure: Failure = report.failure.expect("失败要留档"); + assert_eq!(failure.kind, JavaErrorKind::Metadata); + assert_eq!(failure.major, 21); + assert_eq!(failure.source.as_deref(), Some("tuna")); +} + +/// **占位符不许漏**：`Catalog::render` 缺参数时会把 `{name}` 留下 `(name)`，而那张图已经能看见 +/// （M197 出图时实测到 `试过 (tried) 家发行版`——模板里有一个调用点没给的占位符）。 +/// +/// 这条对**本页自己渲染的每一条下载文案**做同一件事：拿真实参数渲一遍，断言输出里没有 +/// 「`(` + 标识符 + `)`」这种残留。ASCII 括号是判据：本页这些模板里没有合法的 ASCII 括号短语 +/// （中文文案用全角「（）」），所以命中即漏参。 +/// +/// 变异证明：把 `SettingsJavaDownloadFailed` 的模板改回「`(tried {n} vendors…)`」那种带 +/// `{tried}` 的写法 ⇒ 本用例红（渲出 `(tried)`）。M197 就是这么发现它的。 +#[test] +fn every_download_template_renders_without_leftover_placeholders() { + use unlucky_i18n::{Key, Lang}; + + let catalog = Lang::En.catalog(); + /// 一条用例：标签 / key / 渲染参数。 + type Case<'a> = (&'a str, Key, &'a [(&'a str, &'a str)]); + + let cases: [Case<'_>; 6] = [ + ( + "failed", + Key::SettingsJavaDownloadFailed, + &[("major", "21"), ("source", "tuna")], + ), + ( + "failed-no-source", + Key::SettingsJavaDownloadFailedNoSource, + &[("major", "21")], + ), + ( + "done", + Key::SettingsJavaDownloadDone, + &[ + ("major", "21"), + ("vendor", "Eclipse Temurin"), + ("root", "D:/jdks/21"), + ("source", "tuna"), + ], + ), + ( + "done-reused", + Key::SettingsJavaDownloadDoneReused, + &[ + ("major", "21"), + ("vendor", "Eclipse Temurin"), + ("root", "D:/jdks/21"), + ], + ), + ("busy", Key::SettingsJavaDownloadBusy, &[("major", "21")]), + ( + "retry", + Key::SettingsJavaDownloadRetry, + &[ + ("source", "tuna"), + ("reason", "server error"), + ("attempt", "2"), + ("seconds", "2.0"), + ], + ), + ]; + for (tag, key, args) in cases { + let text = catalog.render(key, args); + let mut rest = text.as_str(); + while let Some(open) = rest.find('(') { + let after = &rest[open + 1..]; + let close = after.find(')'); + if let Some(close) = close { + let inner = &after[..close]; + assert!( + inner.is_empty() + || !inner.chars().all(|c| c.is_ascii_alphanumeric() || c == '_'), + "{tag} 渲染后还留着占位符 `({inner})`：{text}" + ); + } + rest = after; + } + } +} + +/// `download.gh_proxy` 的两条守卫（M197）：取值映射 + 真消费者。拆到子模块守 400 行硬线。 +#[path = "tests/gh_proxy.rs"] +mod gh_proxy; diff --git a/crates/app-iced/src/pages/settings/java/downloads/tests/gh_proxy.rs b/crates/app-iced/src/pages/settings/java/downloads/tests/gh_proxy.rs new file mode 100644 index 0000000..5684af7 --- /dev/null +++ b/crates/app-iced/src/pages/settings/java/downloads/tests/gh_proxy.rs @@ -0,0 +1,118 @@ +//! `download.gh_proxy` 的两条守卫（M197）：取值映射 + 「真的接上了」。 +//! +//! 从 `downloads/tests.rs` 拆出来守 400 行硬线（拆法与 `agents::tests` 一致：断言跟着它守的 +//! 东西走）。这里只说一件事：设置值必须**改变候选链**，而不只是被读出来。 + +// --------------------------------------------------------------- P2-3：`download.gh_proxy` 的取值与真消费者 + +/// 设置原文 → 三态：空 = 跟随内置默认，`off` 一族 = 关，其余 = 覆盖前缀。 +/// +/// 变异证明：删掉 `gh_proxy_from` 里那段 `matches!(lowered, "off" | …)` ⇒ 本用例红 +/// （`off` 会被当成一个前缀 `off`，拼出 `offhttps://…` 这种 URL）。 +#[test] +fn the_gh_proxy_setting_maps_to_three_states() { + use crate::pages::settings::java::downloads::engine::gh_proxy_from; + use crate::pages::settings::java::downloads::GhProxy; + + assert_eq!(gh_proxy_from(""), GhProxy::Builtin, "空 = 跟随内置默认"); + assert_eq!(gh_proxy_from(" "), GhProxy::Builtin); + for off in [ + "off", "OFF", " none ", "direct", "Disable", "disabled", "no", + ] { + assert_eq!(gh_proxy_from(off), GhProxy::Off, "{off} 应表示关掉"); + } + assert_eq!( + gh_proxy_from(" https://gh.example/ "), + GhProxy::Prefix("https://gh.example/".to_string()), + "前后空白要去掉，值原样保留" + ); +} + +/// **真消费者**：`download.gh_proxy` 落盘 → 引擎档案 → **候选链里真的出现该前缀**。 +/// +/// 三步都要成立才算「接了」：① 键读得出来；② 档案被覆盖；③ `expand()` 用它生成候选。 +/// 只断言 ① 会漏掉「读了但没用」（本 mission 修的就是这一类），只断言 ② 会漏掉「expand 不认 +/// 档案里的前缀」。 +/// +/// 变异证明：让 `engine_with` 忽略 `gh_proxy` 参数（`let profile = profile;`）⇒ ②③ 两条红； +/// 把 `gh_proxy_of_config` 写成恒 `Builtin` ⇒ ① 先红。 +#[test] +fn the_gh_proxy_setting_reaches_the_candidate_chain() { + use crate::pages::settings::java::downloads::engine::engine_with; + use crate::pages::settings::java::downloads::{gh_proxy_of_config, GhProxy}; + use unlucky_core::download::cache::now_ms; + use unlucky_core::download::region::{store_cached, RegionProfile}; + use unlucky_core::download::types::{DownloadRequest, ResourceKind}; + use unlucky_core::download::ProgressEmitter; + use unlucky_core::setting::keys::launcher_schema; + use unlucky_core::setting::store::SettingStore; + + let dir = std::env::temp_dir().join(format!("ull-gh-proxy-{}-{}", std::process::id(), line!())); + let _ = std::fs::remove_dir_all(&dir); + std::fs::create_dir_all(dir.join("cache")).expect("cache"); + std::fs::create_dir_all(dir.join("config")).expect("config"); + let config = dir.join("config").join("launcher.json"); + + // ① 键读得出来 + let mut store = SettingStore::load(&config, launcher_schema()); + store + .set( + "download.gh_proxy", + "https://gh.example/".to_string().into(), + ) + .expect("schema 认识 download.gh_proxy"); + store.save().expect("写盘"); + assert_eq!( + gh_proxy_of_config(&config), + GhProxy::Prefix("https://gh.example/".to_string()) + ); + + // region.json 钉成镜像优先：否则 gh-proxy 候选本来就不生成，测不出「设了有没有用」。 + let cache = dir.join("cache"); + store_cached( + &cache.join("region.json"), + &RegionProfile::mirror_first(now_ms()), + ) + .expect("写 region.json"); + + let engine = engine_with( + &cache, + ProgressEmitter::silent(), + &gh_proxy_of_config(&config), + ); + // ② 档案被覆盖 + assert_eq!( + engine.region().gh_proxy.as_deref(), + Some("https://gh.example/"), + "设置值必须覆盖档案里的前缀" + ); + + // ③ 候选链里真的出现这个前缀 + let request = DownloadRequest::new( + ResourceKind::Library, + "https://github.com/owner/repo/releases/download/v1/a.jar".to_string(), + dir.join("a.jar"), + ); + let plan = engine.plan(&request, 0); + assert!( + plan.iter() + .any(|candidate| candidate.url.starts_with("https://gh.example/")), + "gh-proxy 候选没出现在候选链里：{:?}", + plan.iter() + .map(|candidate| candidate.url.clone()) + .collect::>() + ); + + // 关掉那一档：一个代理候选都不生成（同一份 region.json，只换设置值）。 + let off = engine_with(&cache, ProgressEmitter::silent(), &GhProxy::Off); + assert_eq!(off.region().gh_proxy, None, "off 必须把前缀清掉"); + let plan = off.plan(&request, 0); + assert!( + !plan + .iter() + .any(|candidate| candidate.url.starts_with("https://gh.example/")), + "关掉之后不该再有 gh-proxy 候选" + ); + + let _ = std::fs::remove_dir_all(&dir); +} diff --git a/crates/app-iced/src/pages/settings/java/fields.rs b/crates/app-iced/src/pages/settings/java/fields.rs new file mode 100644 index 0000000..87676ed --- /dev/null +++ b/crates/app-iced/src/pages/settings/java/fields.rs @@ -0,0 +1,257 @@ +//! 「Java」分组的**编辑区**（M175）：手动路径 / 默认内存 / JVM 参数 / 保存与回执。 +//! +//! 从 `view.rs` 拆出来的（那个文件加了守卫之后贴到 438 行，越过 400 行硬线）：这里全是 +//! 「用户能改的东西」，`view.rs` 只剩「扫到了什么」与版面。两半共用 `view::msg` 这一个消息口， +//! 所以「一条控件对应哪条消息」不会各写一遍。 + +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 crate::app::components::buttons::{self, Button}; +use crate::app::components::inputs::{text_field, Field, FieldVariant}; +use crate::pages::frame::{text_role_owned, BASE}; +use crate::pages::Message; +use crate::theme::Ui; + +use super::state::{Layer, Notice, Refusal, State, MAX_MEMORY_MB, MIN_MEMORY_MB}; +use super::view::msg; +use super::Message as JavaMessage; + +/// 手动添加一行：输入框 + 「添加」按钮 + 原因。 +/// +/// M237：这一行住在 `frame::card` 里，输入框与按钮都把底传成 `frame::BASE`（禁用/状态层叠卡底）。 +pub(super) fn add_row<'a>(ui: &'a Ui, catalog: Catalog, state: &'a State) -> Element<'a, Message> { + let field = Field::new(&state.add_draft) + .variant(FieldVariant::Outlined) + .label(catalog.text(Key::SettingsJavaAdd)) + .placeholder(catalog.text(Key::SettingsJavaAddPlaceholder)) + .supporting(catalog.text(Key::SettingsJavaAddHint)) + .base(BASE); + let add = if state.add_draft.trim().is_empty() || !state.storage { + buttons::outlined( + ui, + Button::disabled(catalog.text(Key::SettingsJavaAddAction)).base(BASE), + ) + } else { + buttons::outlined( + ui, + Button::new( + catalog.text(Key::SettingsJavaAddAction), + msg(JavaMessage::Add), + ) + .base(BASE), + ) + }; + row![ + container(text_field(ui, field, |value| msg(JavaMessage::AddDraft( + value + )))) + .width(Length::Fill), + add, + ] + .spacing(ui.space(Space::X2)) + .width(Length::Fill) + .align_y(Alignment::Center) + .into() +} + +/// 默认内存：数字框 + 范围 + 「生效值来自哪一层」。 +pub(super) fn memory_field<'a>( + ui: &'a Ui, + catalog: Catalog, + state: &'a State, +) -> Element<'a, Message> { + let range = catalog.render( + Key::SettingsJavaMemoryHint, + &[ + ("min", MIN_MEMORY_MB.to_string().as_str()), + ("max", MAX_MEMORY_MB.to_string().as_str()), + ], + ); + let field = Field::new(&state.memory) + .variant(FieldVariant::Outlined) + .label(catalog.text(Key::SettingsJavaMemory)) + .base(BASE); + // 校验不过就把输入框本身标红（不只是下面那行字）：用户一眼看到「是这个框有问题」。 + let field = match state.validate() { + Err(Refusal::MemoryEmpty | Refusal::MemoryNotNumber | Refusal::MemoryRange) => { + field.error() + } + _ => field, + }; + let effective = match state.layer() { + Layer::Global => catalog.render( + Key::SettingsJavaLayerGlobal, + &[("mb", state.saved_memory.to_string().as_str())], + ), + Layer::Instance { instance, mb } => catalog.render( + Key::SettingsJavaLayerInstance, + &[ + ("mb", mb.to_string().as_str()), + ("instance", instance.as_str()), + ], + ), + }; + column![ + text_field(ui, field, |value| msg(JavaMessage::EditMemory(value))), + text_role_owned( + ui, + TypeRole::BodySmall, + false, + effective, + ui.color(Role::OnSurfaceVariant), + ), + text_role_owned( + ui, + TypeRole::BodySmall, + false, + range, + ui.color(Role::OnSurfaceVariant), + ), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill) + .into() +} + +/// JVM 额外参数：文本框 + 「会拼到每次启动」的说明。 +pub(super) fn jvm_field<'a>( + ui: &'a Ui, + catalog: Catalog, + state: &'a State, +) -> Element<'a, Message> { + let field = Field::new(&state.jvm) + .variant(FieldVariant::Outlined) + .label(catalog.text(Key::SettingsJavaJvm)) + .placeholder(catalog.text(Key::SettingsJavaJvmPlaceholder)) + .supporting(catalog.text(Key::SettingsJavaJvmHint)) + .base(BASE); + // 两种拒绝都长在这个框上：引号没配对、或者粘了超过 1024 字符的一整段（M199）。 + let field = if matches!( + state.validate(), + Err(Refusal::JvmQuotes | Refusal::JvmTooLong) + ) { + field.error() + } else { + field + }; + // 已保存值：空的时候说「还没有保存任何额外参数」，而不是让「已保存的值：」后面空着。 + let saved = if state.saved_jvm.trim().is_empty() { + catalog.text(Key::SettingsJavaJvmSavedNone).to_string() + } else { + catalog.render( + Key::SettingsJavaJvmSaved, + &[("value", state.saved_jvm.as_str())], + ) + }; + column![ + text_field(ui, field, |value| msg(JavaMessage::EditJvm(value))), + text_role_owned( + ui, + TypeRole::BodySmall, + false, + saved, + ui.color(Role::OnSurfaceVariant), + ), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill) + .into() +} + +pub(super) fn actions_row<'a>( + ui: &'a Ui, + catalog: Catalog, + state: &'a State, +) -> Element<'a, Message> { + let label = catalog.text(Key::SettingsJavaSave); + if state.can_save() { + buttons::filled(ui, Button::new(label, msg(JavaMessage::Save)).base(BASE)) + } else { + buttons::filled(ui, Button::disabled(label).base(BASE)) + } +} + +/// 按钮为什么灰着 / 下一步做什么——**永远说清**。 +pub(super) fn hint_line<'a>( + ui: &'a Ui, + catalog: Catalog, + state: &'a State, +) -> Element<'a, Message> { + let (text, error) = if !state.storage { + (catalog.text(Key::SettingsJavaNoStorage).to_string(), true) + } else if state.dirty { + (catalog.text(Key::SettingsJavaUnsaved).to_string(), false) + } else { + (String::new(), false) + }; + text_role_owned( + ui, + TypeRole::BodySmall, + false, + text, + ui.color(if error { + Role::Error + } else { + Role::OnSurfaceVariant + }), + ) +} + +pub(super) fn notice_line<'a>( + ui: &'a Ui, + catalog: Catalog, + notice: &Notice, +) -> Element<'a, Message> { + let (text, error) = match notice { + Notice::Saved => (catalog.text(Key::SettingsJavaSaved).to_string(), false), + Notice::Refused(reason) => ( + catalog.render( + Key::SettingsJavaRefused, + &[("reason", catalog.text(refusal_key(*reason)))], + ), + true, + ), + Notice::Unwritable(reason) => ( + catalog.render( + Key::SettingsJavaRefused, + &[("reason", catalog.text(reason.label()))], + ), + true, + ), + Notice::WriteFailed => ( + catalog.render( + Key::SettingsJavaRefused, + &[("reason", catalog.text(Key::SettingsJavaReasonWriteFailed))], + ), + true, + ), + Notice::NoStorage => (catalog.text(Key::SettingsJavaNoStorage).to_string(), true), + Notice::DefaultSet(path) => ( + catalog.render(Key::SettingsJavaDefaultSet, &[("path", path.as_str())]), + false, + ), + Notice::Added(path) => ( + catalog.render(Key::SettingsJavaAdded, &[("path", path.as_str())]), + false, + ), + Notice::PrefsSaved => (catalog.text(Key::SettingsJavaPrefsSaved).to_string(), false), + }; + text_role_owned( + ui, + TypeRole::BodySmall, + false, + text, + ui.color(if error { Role::Error } else { Role::OnSurface }), + ) +} + +/// 拒绝原因 → 文案 key（`Refusal::label` 已是这张表，这里只是给 `match` 一个名字）。 +pub(super) fn refusal_key(refusal: Refusal) -> Key { + refusal.label() +} diff --git a/crates/app-iced/src/pages/settings/java/prefs.rs b/crates/app-iced/src/pages/settings/java/prefs.rs new file mode 100644 index 0000000..1c3c68c --- /dev/null +++ b/crates/app-iced/src/pages/settings/java/prefs.rs @@ -0,0 +1,297 @@ +//! 三个设置键的可编辑状态（M197）：`java.installRoot` / `java.vendorPriority` / `java.auto_install`。 +//! +//! 用户原话（2026-11-08）：「自动下载 jdk17 作为基准版本，后续在设置中提供多版本可供用户下载。」 +//! M175 把 Java 页接上了真运行时，但明确没做这三个键；本文件只负责**草稿**与**生效值**两半。 +//! +//! ## 为什么又是「草稿 / 落盘真值」两层 +//! +//! 与 `state.rs` 的内存草稿同一条理由：输入框里的是**文本**（用户可能刚敲了 `D:\Ja`）， +//! 「现在生效什么」是**磁盘上的真值**。混成一个字段就会重演「显示的就是生效的」——而这三项里 +//! `installRoot` 与 `vendorPriority` 都是**可以留空**的键，留空的语义是「跟数据目录模式走 / +//! 跟地区默认序走」，只有拿落盘值去 resolve 一次才说得清到底落在哪、按什么顺序找。 +//! +//! ## 「从哪一层来」怎么表达 +//! +//! [`Effective`] 是 app 层算好的**只读结论**（`prefs_store::effective`）：有效的安装根 + 它是 +//! 来自 `java.installRoot` 还是 `core.data_mode`；有效的发行版顺序 + 它来自 `java.vendorPriority` +//! 还是地区默认序。渲染器只负责把这两个枚举翻成一句话，不再自己判断层级。 +//! +//! ## 优先级草稿为什么是「整条顺序」而不是「用户写的那几家」 +//! +//! `vendor::order` 的语义是**补集追加**（只写 oracle 就把它提前、其余按地区默认序补齐）。 +//! 于是「上移 / 下移」这种操作只有在**看得见的那条完整顺序**上才有意义：用户看到 4 行， +//! 拖动其中一行，落盘的就是他自己排的那条完整链。清空（[`Prefs::reset_priority`]）= 回到 +//! 「跟地区默认序走」，这也是这个键留空时唯一说得通的语义。 + +use unlucky_core::game::java::vendor::{self, JdkVendor}; + +use super::state::Refusal; + +/// `java.installRoot` 的最大长度：与 `core::setting::keys` 里那个键登记的上限一致（512）。 +pub const MAX_INSTALL_ROOT: usize = 512; + +/// `java.auto_install` 的出厂默认值（schema 默认 `true`）。 +pub const DEFAULT_AUTO_INSTALL: bool = true; + +/// 三键的草稿 + 落盘真值。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Prefs { + /// `java.installRoot` 草稿（空 = 跟数据目录模式走） + pub install_root: String, + /// 落盘的 `java.installRoot` + pub saved_install_root: String, + /// `java.auto_install` 草稿 + pub auto_install: bool, + /// 落盘的 `java.auto_install` + pub saved_auto_install: bool, + /// `java.vendorPriority` 草稿（稳定 id，顺序即优先级；空 = 地区默认序） + pub priority: Vec<&'static str>, + /// 落盘的 `java.vendorPriority` + pub saved_priority: Vec<&'static str>, +} + +impl Default for Prefs { + /// 出厂值 = schema 的默认值（**不是**零值：`auto_install` 出厂是 `true`）。 + fn default() -> Self { + Self { + install_root: String::new(), + saved_install_root: String::new(), + auto_install: DEFAULT_AUTO_INSTALL, + saved_auto_install: DEFAULT_AUTO_INSTALL, + priority: Vec::new(), + saved_priority: Vec::new(), + } + } +} + +/// 有效的安装根从哪一层来。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum RootLayer { + /// 设置键 `java.installRoot` + Setting, + /// 数据目录模式（`core.data_mode`）派生的落点 + DataMode, +} + +/// 有效的发行版顺序从哪一层来。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum OrderLayer { + /// 设置键 `java.vendorPriority` + Setting, + /// 地区默认序（国内 / 国外两套内置序） + Region, +} + +/// app 层每次 hydrate 重算的只读结论（渲染器只翻文案，不再判断层级）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Effective { + /// 有效的安装根（人读路径） + pub root: String, + /// 落点模式（`custom` / `standard` / `portable`） + pub root_mode: &'static str, + /// 安装根来自哪一层 + pub root_layer: RootLayer, + /// 解析不出标准目录（`standard` 模式拿不到 `%APPDATA%` / `HOME`） + pub root_unresolved: bool, + /// 有效的发行版顺序（展示名） + pub order: Vec<&'static str>, + /// 顺序来自哪一层 + pub order_layer: OrderLayer, + /// 这台机器被判成国内环境（地区默认序取的是国内那套） + pub domestic: bool, +} + +impl Default for Effective { + fn default() -> Self { + Self { + root: String::new(), + root_mode: "portable", + root_layer: RootLayer::DataMode, + root_unresolved: false, + order: Vec::new(), + order_layer: OrderLayer::Region, + domestic: true, + } + } +} + +/// 从 `launcher.json` 读回来的三键真值。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Snapshot { + /// `java.installRoot` + pub install_root: String, + /// `java.auto_install` + pub auto_install: bool, + /// `java.vendorPriority`（稳定 id） + pub priority: Vec, +} + +impl Prefs { + /// 用真值刷新（**脏草稿不覆盖**，与 `State::hydrate` 同一条纪律）。返回是否变了。 + pub fn hydrate(&mut self, snapshot: Snapshot) -> bool { + let priority: Vec<&'static str> = snapshot + .priority + .iter() + .filter_map(|text| JdkVendor::parse(text).map(JdkVendor::id)) + .collect(); + let changed = self.saved_install_root != snapshot.install_root + || self.saved_auto_install != snapshot.auto_install + || self.saved_priority != priority; + self.saved_install_root = snapshot.install_root.clone(); + self.saved_auto_install = snapshot.auto_install; + self.saved_priority = priority.clone(); + if !self.dirty() { + self.install_root = snapshot.install_root; + self.auto_install = snapshot.auto_install; + self.priority = priority; + } + changed + } + + /// 保存成功后用**读回的真值**收尾：草稿与落盘值两半都对它。 + /// + /// 为什么草稿也要改：这就是「改完回读验证已落盘」的界面形态——用户看到的就是磁盘上那份。 + /// 如果 schema 把值规整过（去空格、拒绝某个枚举值），界面上显示的是规整后的结果， + /// 而不是他刚敲的那串原样（假装没变过才是最坏的）。 + pub fn adopt(&mut self, snapshot: Snapshot) { + let priority: Vec<&'static str> = snapshot + .priority + .iter() + .filter_map(|text| JdkVendor::parse(text).map(JdkVendor::id)) + .collect(); + self.install_root = snapshot.install_root.clone(); + self.auto_install = snapshot.auto_install; + self.priority = priority.clone(); + self.saved_install_root = snapshot.install_root; + self.saved_auto_install = snapshot.auto_install; + self.saved_priority = priority; + } + + /// 这一段有没有未保存的改动。 + #[must_use] + pub fn dirty(&self) -> bool { + self.install_root.trim() != self.saved_install_root.trim() + || self.auto_install != self.saved_auto_install + || self.priority != self.saved_priority + } + + /// 保存前的本地校验（过不了就不写盘）。 + /// + /// # Errors + /// 路径超过 schema 登记的长度上限时返回 [`Refusal::InstallRootTooLong`]。 + pub fn validate(&self) -> Result<(), Refusal> { + if self.install_root.trim().chars().count() > MAX_INSTALL_ROOT { + return Err(Refusal::InstallRootTooLong); + } + Ok(()) + } + + /// 草稿的优先级链 → 稳定 id 列表（落盘用：空列表 = 跟地区默认序走）。 + #[must_use] + pub fn priority_ids(&self) -> Vec { + self.priority.iter().map(|id| (*id).to_string()).collect() + } + + /// 草稿的优先级链 → 有效顺序（`vendor::order` 的补集追加语义，与真正下载时同源）。 + #[must_use] + pub fn order(&self, domestic: bool) -> Vec { + let parsed = self + .priority + .iter() + .filter_map(|id| JdkVendor::parse(id)) + .collect::>(); + vendor::order(&parsed, domestic) + } + + /// 上移一行（`index` 是**有效顺序**里的下标）。 + /// + /// 第一次动就把草稿物化成整条顺序：用户拖的是他看见的那 4 行，落盘的就该是这 4 行的顺序。 + /// `domestic` 由调用方给（app 层已经算过一次地区判定，这里不重复探测）。 + pub fn move_up(&mut self, index: usize, domestic: bool) { + self.materialize(domestic); + if index > 0 && index < self.priority.len() { + self.priority.swap(index, index - 1); + } + } + + /// 下移一行。 + pub fn move_down(&mut self, index: usize, domestic: bool) { + self.materialize(domestic); + if index + 1 < self.priority.len() { + self.priority.swap(index, index + 1); + } + } + + /// 草稿物化：把「留空 = 地区默认序」展开成那条完整链（已物化时不动）。 + fn materialize(&mut self, domestic: bool) { + if self.priority.len() != JdkVendor::default_order(domestic).len() { + self.priority = self.order(domestic).iter().map(|id| id.id()).collect(); + } + } + + /// 恢复地区默认序（= 把这个键写回空，让地区那一层重新生效）。 + pub fn reset_priority(&mut self) { + self.priority.clear(); + } +} + +#[cfg(test)] +mod tests { + use super::Prefs; + use unlucky_core::game::java::vendor::{ids, JdkVendor}; + + /// 出厂值 = schema 默认（`auto_install` 为真、另两键留空）。 + /// + /// 变异证明：把 `Prefs::default` 里 `auto_install` 改成 `false` ⇒ 本用例红。 + #[test] + fn the_defaults_match_the_schema() { + let prefs = Prefs::default(); + assert!(prefs.auto_install); + assert!(prefs.install_root.is_empty()); + assert!(prefs.priority.is_empty()); + assert!(!prefs.dirty(), "出厂值不算脏"); + assert_eq!( + prefs.order(true), + vec![ + JdkVendor::Temurin, + JdkVendor::Oracle, + JdkVendor::Microsoft, + JdkVendor::Zulu + ], + "留空 = 国内默认序" + ); + } + + /// 上移 / 下移真的改顺序，而且第一条上移是空操作。 + /// + /// 变异证明：把 `move_up` 里的 `swap(index, index - 1)` 写成 `swap(index, index + 1)` + /// ⇒ 本用例红。 + #[test] + fn moving_a_vendor_rewrites_the_order() { + let mut prefs = Prefs::default(); + // 空白草稿上直接下移第一条：物化成整条链后再交换。 + prefs.move_down(0, true); + assert_eq!( + ids(&prefs.order(true)), + vec!["oracle", "temurin", "microsoft", "zulu"], + "下移第一条 = 与第二条交换" + ); + assert_eq!(prefs.priority.len(), 4, "物化之后是整条链"); + prefs.move_up(0, true); + assert_eq!(ids(&prefs.order(true))[0], "oracle", "第一条上移是空操作"); + prefs.move_up(1, true); + assert_eq!(ids(&prefs.order(true))[0], "temurin"); + assert!(prefs.dirty(), "动过就该脏"); + } + + /// 恢复地区默认序 = 草稿清空，且不再脏（与落盘的空值一致）。 + #[test] + fn resetting_goes_back_to_the_region_default() { + let mut prefs = Prefs::default(); + prefs.move_down(0, true); + assert!(prefs.dirty()); + prefs.reset_priority(); + assert!(!prefs.dirty()); + assert_eq!(ids(&prefs.order(true))[0], "temurin"); + } +} diff --git a/crates/app-iced/src/pages/settings/java/prefs_store.rs b/crates/app-iced/src/pages/settings/java/prefs_store.rs new file mode 100644 index 0000000..f33cf96 --- /dev/null +++ b/crates/app-iced/src/pages/settings/java/prefs_store.rs @@ -0,0 +1,246 @@ +//! 三个设置键的真读写（M197）：`java.installRoot` / `java.vendorPriority` / `java.auto_install`。 +//! +//! 与 `store.rs`（M175 的内存 / JVM / 默认 JDK）同一条通路：`core::setting::store::SettingStore` +//! —— 读一份 → 改几个键 → 存 → **再从磁盘读回来**。写盘只认 `Saved` 一档，其余一律当失败 +//! （`WriteError` 的三档与 `store.rs` 同一套类型，界面文案也同一套）。 +//! +//! ## 「生效值 + 从哪一层来」为什么在这里算 +//! +//! 两个键都可能**留空**，而留空的语义分别指向另外两层： +//! +//! | 键 | 留空 = | 生效值的第二层 | +//! |---|---|---| +//! | `java.installRoot` | 按 `core.data_mode` 派生落点 | `JavaInstallRoot::resolve`（portable / standard） | +//! | `java.vendorPriority` | 按地区默认序 | `vendor::order(&[], domestic)` | +//! +//! 所以「现在到底装到哪 / 按什么顺序找」只有把**落盘值**代进 core 的纯函数才说得清。 +//! 这两个纯函数本身就是真正下载时用的那一对（`install` 也走 `resolve` 与 `order`）， +//! 于是界面上的「生效」与真跑起来的行为不会各说一套。 +//! +//! ## 地区判定只做一次 +//! +//! `domestic` 从 `cache/region.json` 读（引擎建过一次就有）；读不到时按环境信号判一次并写回 +//! ——与 `shared::build` 的做法一致。它**不联网**（`region_system` 只跑 `tzutil` / `reg`）， +//! 且本函数只在首屏与配置文件变化时被调用，不进心跳。 + +use std::path::{Path, PathBuf}; + +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::game::java::vendor::{self, JdkVendor}; +use unlucky_core::game::java::{JavaInstallRoot, LocationMode}; +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::{SaveOutcome, SettingStore}; + +use super::prefs::{Effective, OrderLayer, Prefs, RootLayer, Snapshot}; +use super::store::{unwritable, WriteError}; + +/// 读三键真值。 +#[must_use] +pub fn load(config: &Path) -> Snapshot { + let store = SettingStore::load(config, launcher_schema()); + snapshot(store.doc()) +} + +/// 写三键，返回**落盘后读回来**的真值。 +/// +/// # Errors +/// 本地校验不过（[`WriteError::Refused`]）、文件只读 / 不可信（[`WriteError::Unwritable`]） +/// 或 schema 拒绝（[`WriteError::Schema`]）时返回原因。 +pub fn save(config: &Path, prefs: &Prefs) -> Result { + prefs.validate().map_err(WriteError::Refused)?; + let mut store = SettingStore::load(config, launcher_schema()); + let root = prefs.install_root.trim().to_string(); + let ids = prefs.priority_ids(); + // `java.vendorPriority` 是数组键，而 `SettingStore::set` 只收 `serde_json::Value`—— + // app-iced 的依赖表里没有 serde_json（本 mission 也改不了 manifest），所以不现造一个 + // `Value`：从文档里取**当前那个数组**（schema 默认就是空数组）清空再填，形状与 schema 一致。 + let mut array = store + .doc() + .effective("java.vendorPriority") + .cloned() + .unwrap_or_default(); + { + let Some(items) = array.as_array_mut() else { + return Err(WriteError::Schema( + "java.vendorPriority 当下不是数组（schema 的默认值是空数组）".to_string(), + )); + }; + items.clear(); + for id in &ids { + items.push(id.as_str().into()); + } + } + store + .set("java.installRoot", root.into()) + .and_then(|()| store.set("java.auto_install", prefs.auto_install.into())) + .and_then(|()| store.set("java.vendorPriority", array)) + .map_err(|error| WriteError::Schema(format!("{error}")))?; + match store.save() { + Ok(SaveOutcome::Saved(_)) => Ok(load(config)), + Ok(SaveOutcome::Skipped(reason)) => Err(WriteError::Unwritable(unwritable(reason))), + Err(error) => Err(WriteError::Schema(format!("{error}"))), + } +} + +/// 生效值 + 来源层（渲染器只翻文案）。 +#[must_use] +pub fn effective(config: &Path, prefs: &Prefs) -> Effective { + let store = SettingStore::load(config, launcher_schema()); + let doc = store.doc(); + let data_mode = doc + .effective_str("core.data_mode") + .and_then(DataMode::parse) + .unwrap_or_else(|| DataMode::default_for(Platform::current())); + let override_root = { + let text = prefs.saved_install_root.trim(); + (!text.is_empty()).then(|| PathBuf::from(text)) + }; + let layout = home_of(config).map(LauncherLayout::new); + let (root, root_mode, root_layer, root_unresolved) = match &layout { + Some(layout) => match JavaInstallRoot::resolve( + data_mode, + layout, + override_root.as_deref(), + Platform::current(), + &ProcessEnv, + ) { + Ok(resolved) => ( + resolved.root.display().to_string(), + resolved.mode.as_str(), + layer_of(resolved.mode), + false, + ), + Err(error) => { + eprintln!("[java] 解析安装根失败：{error}"); + ( + String::new(), + data_mode.as_str(), + if override_root.is_some() { + RootLayer::Setting + } else { + RootLayer::DataMode + }, + true, + ) + } + }, + None => (String::new(), data_mode.as_str(), RootLayer::DataMode, true), + }; + + let domestic = domestic_of(config); + let priority = prefs + .saved_priority + .iter() + .filter_map(|id| JdkVendor::parse(id)) + .collect::>(); + let order = vendor::order(&priority, domestic); + Effective { + root, + root_mode, + root_layer, + root_unresolved, + order: order.iter().map(|vendor| vendor.display()).collect(), + order_layer: if priority.is_empty() { + OrderLayer::Region + } else { + OrderLayer::Setting + }, + domestic, + } +} + +/// 现在的地区判定（`cache/region.json` 优先，没有就判一次并写回）。 +/// +/// 与 `core::download::shared::build` 同源：同一个 `region.json`、同一套信号。 +/// 读不到缓存目录（配置路径不像 `/config/launcher.json`）时按**国内**算—— +/// 那是 D23 出厂口径，也是唯一一个「不知道还更保守」的取值（镜像先试不会更差）。 +#[must_use] +pub fn domestic_of(config: &Path) -> bool { + let Some(home) = home_of(config) else { + return true; + }; + let cache = LauncherLayout::new(home).cache(); + let now = now_ms(); + let path = cache.join("region.json"); + if let Some(profile) = load_cached(&path, now) { + return profile.is_domestic(); + } + let profile = decide_from(&detect_signals(), now); + let _ = std::fs::create_dir_all(&cache); + let _ = store_cached(&path, &profile); + profile.is_domestic() +} + +/// 托管 JDK 该装到哪（下载作业用；与界面上的「生效」同一个函数）。 +#[must_use] +pub fn install_root(config: &Path, saved_install_root: &str) -> Option { + let store = SettingStore::load(config, launcher_schema()); + let data_mode = store + .doc() + .effective_str("core.data_mode") + .and_then(DataMode::parse) + .unwrap_or_else(|| DataMode::default_for(Platform::current())); + let home = home_of(config)?; + let layout = LauncherLayout::new(home); + let override_root = { + let text = saved_install_root.trim(); + (!text.is_empty()).then(|| PathBuf::from(text)) + }; + JavaInstallRoot::resolve( + data_mode, + &layout, + override_root.as_deref(), + Platform::current(), + &ProcessEnv, + ) + .ok() +} + +/// 下载引擎的缓存根（`/cache`）：让 JDK 归档与其它下载共用同一份缓存 / 健康度。 +#[must_use] +pub fn cache_root(config: &Path) -> Option { + home_of(config).map(|home| LauncherLayout::new(home).cache()) +} + +/// launcher home（`/config/launcher.json` 的上一级再上一级）。 +fn home_of(config: &Path) -> Option<&Path> { + config.parent().and_then(Path::parent) +} + +/// 落点模式 → 「从哪一层来」。 +fn layer_of(mode: LocationMode) -> RootLayer { + match mode { + LocationMode::Custom => RootLayer::Setting, + LocationMode::Standard | LocationMode::Portable => RootLayer::DataMode, + } +} + +/// 文档 → 快照。 +fn snapshot(doc: &unlucky_core::setting::document::SettingDocument) -> Snapshot { + Snapshot { + install_root: doc + .effective_str("java.installRoot") + .unwrap_or_default() + .trim() + .to_string(), + auto_install: doc + .effective_bool("java.auto_install") + .unwrap_or(super::prefs::DEFAULT_AUTO_INSTALL), + priority: doc + .effective("java.vendorPriority") + .and_then(|value| value.as_array()) + .map(|items| { + items + .iter() + .filter_map(|item| item.as_str()) + .map(str::to_string) + .collect() + }) + .unwrap_or_default(), + } +} diff --git a/crates/app-iced/src/pages/settings/java/prefs_view.rs b/crates/app-iced/src/pages/settings/java/prefs_view.rs new file mode 100644 index 0000000..ff889c5 --- /dev/null +++ b/crates/app-iced/src/pages/settings/java/prefs_view.rs @@ -0,0 +1,338 @@ +//! 三个设置键的**编辑区**（M197）：`java.installRoot` / `java.vendorPriority` / `java.auto_install`。 +//! +//! 每一段都是同一种形状：**能改的控件 + 现在生效什么 + 这个生效值从哪一层来**。第三件事是任务书 +//! 点名的（「两者都要能解释『生效值现在是什么、从哪一层来』」），所以三段的最后一行永远不是空的： +//! +//! | 段 | 控件 | 生效值从哪来 | +//! |---|---|---| +//! | 安装目录 | 文本框（可以留空） | `java.installRoot` 或 `core.data_mode` | +//! | 发行版顺序 | 4 行 + 上移 / 下移 + 恢复默认 | `java.vendorPriority` 或地区默认序 | +//! | 缺 JDK 时自动准备 | 开 / 关两片 | 设置本身（出厂开） | +//! +//! 文案一律走 [`Catalog`]（本组要 `Lang`，走 `settings/mod.rs` 的按下标分发）；渲染器自己不判断 +//! 层级，`RootLayer` / `OrderLayer` 是 app 层算好的结论。 + +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 crate::app::components::buttons::{self, Button}; +use crate::app::components::inputs::{text_field, Field, FieldVariant}; +use crate::app::components::selection::{chip, Chip}; +use crate::pages::frame::{divider, text_role_owned, BASE}; +use crate::pages::Message; +use crate::theme::Ui; + +use super::prefs::{Effective, OrderLayer, RootLayer}; +use super::state::State; +use super::view::msg; +use super::Message as JavaMessage; + +/// 三段 + 保存按钮（整块的标题由设置页的外壳给，这里不再画）。 +pub(super) fn section<'a>(ui: &'a Ui, catalog: Catalog, state: &'a State) -> Element<'a, Message> { + let mut block = column![].spacing(ui.space(Space::X2)).width(Length::Fill); + + block = block.push(install_root(ui, catalog, state)); + block = block.push(divider(ui)); + block = block.push(vendor_order(ui, catalog, state)); + block = block.push(divider(ui)); + block = block.push(auto_install(ui, catalog, state)); + block = block.push(actions(ui, catalog, state)); + block.into() +} + +/// `java.installRoot`：文本框 + 生效落点 + 来源层。 +fn install_root<'a>(ui: &'a Ui, catalog: Catalog, state: &'a State) -> Element<'a, Message> { + let prefs = &state.prefs; + let field = Field::new(&prefs.install_root) + .variant(FieldVariant::Outlined) + .label(catalog.text(Key::SettingsJavaInstallRoot)) + .placeholder(catalog.text(Key::SettingsJavaInstallRootPlaceholder)) + .supporting(catalog.text(Key::SettingsJavaInstallRootHint)) + .base(BASE); + let field = if prefs.validate().is_err() { + field.error() + } else { + field + }; + let effective = effective_line(ui, catalog, &state.effective); + column![ + text_field(ui, field, |value| msg(JavaMessage::EditInstallRoot(value))), + effective, + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill) + .into() +} + +/// 「生效：模式 · 路径」+「从哪一层来」（解析不出标准目录时说清下一步）。 +fn effective_line<'a>( + ui: &'a Ui, + catalog: Catalog, + effective: &'a Effective, +) -> Element<'a, Message> { + if effective.root_unresolved { + return text_role_owned( + ui, + TypeRole::BodySmall, + false, + catalog + .text(Key::SettingsJavaInstallRootUnresolved) + .to_string(), + ui.color(Role::Error), + ); + } + let text = catalog.render( + Key::SettingsJavaInstallRootEffective, + &[ + ("mode", effective.root_mode), + ("path", effective.root.as_str()), + ], + ); + let layer = match effective.root_layer { + RootLayer::Setting => catalog + .text(Key::SettingsJavaInstallRootLayerSetting) + .to_string(), + RootLayer::DataMode => catalog.render( + Key::SettingsJavaInstallRootLayerDataMode, + &[("mode", effective.root_mode)], + ), + }; + column![ + text_role_owned( + ui, + TypeRole::BodySmall, + false, + text, + ui.color(Role::OnSurface), + ), + text_role_owned( + ui, + TypeRole::BodySmall, + false, + layer, + ui.color(Role::OnSurfaceVariant), + ), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill) + .into() +} + +/// `java.vendorPriority`：4 行顺序 + 上移 / 下移 + 恢复地区默认序。 +fn vendor_order<'a>(ui: &'a Ui, catalog: Catalog, state: &'a State) -> Element<'a, Message> { + let prefs = &state.prefs; + let order = prefs.order(state.effective.domestic); + let mut list = column![text_role_owned( + ui, + TypeRole::BodyMedium, + true, + catalog.text(Key::SettingsJavaVendorPriority).to_string(), + ui.color(Role::OnSurface), + ),] + .spacing(ui.space(Space::X2)) + .width(Length::Fill); + + for (index, vendor) in order.iter().enumerate() { + list = list.push(vendor_row(ui, catalog, index, *vendor)); + } + + let joined = state.effective.order.join(" → "); + let layer = match state.effective.order_layer { + OrderLayer::Setting => catalog + .text(Key::SettingsJavaVendorOrderLayerSetting) + .to_string(), + OrderLayer::Region => catalog.render( + Key::SettingsJavaVendorOrderLayerRegion, + &[( + "region", + catalog + .text(if state.effective.domestic { + Key::SettingsJavaRegionDomestic + } else { + Key::SettingsJavaRegionGlobal + }) + .to_string() + .as_str(), + )], + ), + }; + list = list.push(text_role_owned( + ui, + TypeRole::BodySmall, + false, + catalog.render( + Key::SettingsJavaVendorOrderEffective, + &[("order", joined.as_str())], + ), + ui.color(Role::OnSurface), + )); + list = list.push(text_role_owned( + ui, + TypeRole::BodySmall, + false, + layer, + ui.color(Role::OnSurfaceVariant), + )); + // 「恢复地区默认序」只在真的排过顺序时才有意义（已经跟地区走时它是个空操作）。 + if !prefs.priority.is_empty() { + list = list.push(buttons::outlined( + ui, + Button::new( + catalog.text(Key::SettingsJavaVendorReset), + msg(JavaMessage::ResetPriority), + ) + .base(BASE), + )); + } + list.into() +} + +/// 一家发行版一行：名 + 它发哪些大版本 + 上移 / 下移。 +fn vendor_row<'a>( + ui: &'a Ui, + catalog: Catalog, + index: usize, + vendor: unlucky_core::game::java::JdkVendor, +) -> Element<'a, Message> { + let majors = vendor + .hint_majors() + .iter() + .map(u32::to_string) + .collect::>() + .join("/"); + let supporting = catalog.render( + Key::SettingsJavaVendorSupports, + &[("majors", majors.as_str())], + ); + // 第一条的「上移」与最后一条的「下移」都是空操作：照旧可点，点了不改顺序也不标脏 + // （比灰掉更省心——灰掉的 chip 在 424 宽的列里同样占位，用户还得去猜为什么灰）。 + let up = chip( + ui, + Chip::filter( + catalog.text(Key::SettingsJavaVendorUp), + false, + msg(JavaMessage::MoveVendor { index, up: true }), + ) + .base(BASE), + ); + let down = chip( + ui, + Chip::filter( + catalog.text(Key::SettingsJavaVendorDown), + false, + msg(JavaMessage::MoveVendor { index, up: false }), + ) + .base(BASE), + ); + row![ + container( + column![ + text_role_owned( + ui, + TypeRole::BodyMedium, + index == 0, + format!("{}. {}", index + 1, vendor.display()), + ui.color(Role::OnSurface), + ), + text_role_owned( + ui, + TypeRole::BodySmall, + false, + supporting, + ui.color(Role::OnSurfaceVariant), + ), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill), + ) + .width(Length::Fill), + up, + down, + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill) + .align_y(Alignment::Center) + .into() +} + +/// `java.auto_install`：开 / 关两片 + 「它到底做什么」那句。 +fn auto_install<'a>(ui: &'a Ui, catalog: Catalog, state: &'a State) -> Element<'a, Message> { + let on = state.prefs.auto_install; + let chips = row![ + chip( + ui, + Chip::filter( + catalog.text(Key::SettingsJavaAutoInstallOn), + on, + msg(JavaMessage::ToggleAutoInstall(true)), + ) + .base(BASE), + ), + chip( + ui, + Chip::filter( + catalog.text(Key::SettingsJavaAutoInstallOff), + !on, + msg(JavaMessage::ToggleAutoInstall(false)), + ) + .base(BASE), + ), + ] + .spacing(ui.space(Space::X1)); + column![ + text_role_owned( + ui, + TypeRole::BodyMedium, + true, + catalog.text(Key::SettingsJavaAutoInstall).to_string(), + ui.color(Role::OnSurface), + ), + chips, + text_role_owned( + ui, + TypeRole::BodySmall, + false, + catalog.text(Key::SettingsJavaAutoInstallHint).to_string(), + ui.color(Role::OnSurfaceVariant), + ), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill) + .into() +} + +/// 保存按钮 + 「有未保存改动」那行。 +fn actions<'a>(ui: &'a Ui, catalog: Catalog, state: &'a State) -> Element<'a, Message> { + let label = catalog.text(Key::SettingsJavaPrefsSave); + let save = if state.prefs.dirty() && state.storage { + buttons::filled( + ui, + Button::new(label, msg(JavaMessage::SavePrefs)).base(BASE), + ) + } else { + buttons::filled(ui, Button::disabled(label).base(BASE)) + }; + let hint = if state.prefs.dirty() { + catalog.text(Key::SettingsJavaPrefsUnsaved).to_string() + } else { + String::new() + }; + column![ + save, + text_role_owned( + ui, + TypeRole::BodySmall, + false, + hint, + ui.color(Role::OnSurfaceVariant), + ), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill) + .into() +} diff --git a/crates/app-iced/src/pages/settings/java/row.rs b/crates/app-iced/src/pages/settings/java/row.rs new file mode 100644 index 0000000..42f41eb --- /dev/null +++ b/crates/app-iced/src/pages/settings/java/row.rs @@ -0,0 +1,191 @@ +//! 「Java」分组的一行运行时（M175）：路径 / 版本 / 厂商 / 来源 + 上屏用的截断。 +//! +//! 从 `state.rs` 拆出来的（那个文件加了上下文与校验之后到 424 行，越过 400 行硬线）： +//! 这里只放「一行长什么样」，状态与校验仍在 `state.rs`。 + +use unlucky_i18n::Key; + +/// 一个扫到的 / 手动加的运行时（页面要的那几格）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct RuntimeRow { + /// `bin/java[.exe]` 的绝对路径（也是 `java.selected_path` 的取值）。 + pub binary: String, + /// `java -version` 的首行（探测失败时为空串）。 + pub version: String, + /// 主版本号（探测不出为 `None`）。 + pub major: Option, + /// 发行方（认不出为 `None`）。 + pub vendor: Option, + /// 来源 id（`managed` / `env` / `path` / `system` / `manual`）。 + pub source: &'static str, +} + +impl RuntimeRow { + /// 版本号：**能区分 `17.0.13` 与 `17.0.9`** 的那一位，而不是只给大版本（r1 复审 P2-4）。 + /// + /// 三层取法，逐层降级（不许因为解析不出来就只显示 `17`）： + /// 1. `-version` 首行引号里的版本号（`openjdk version "21.0.11" …` → `21.0.11`）； + /// 2. 无引号形态里的第一个版本样 token（`openjdk 25.0.3 2026-04-21` → `25.0.3`）； + /// 3. 整行原样（原始版本串比一个大版本号有用）； + /// 4. 连首行都没有（探测失败）→ 大版本；再没有 → `?`。 + #[must_use] + pub fn version_label(&self) -> String { + if let Some(quoted) = quoted_version(&self.version) { + return quoted; + } + if let Some(bare) = bare_version(&self.version) { + return bare; + } + let line = self.version.trim(); + if !line.is_empty() { + return line.to_string(); + } + self.major + .map_or_else(|| "?".to_string(), |major| major.to_string()) + } + + /// 版本一句话：`Java 21.0.11 · Microsoft`。 + #[must_use] + pub fn summary(&self) -> String { + let version = self.version_label(); + match &self.vendor { + Some(vendor) => format!("Java {version} · {vendor}"), + None => format!("Java {version}"), + } + } + + /// JDK 安装目录（`…/bin/java.exe` 的上一级再上一级）。 + /// + /// 上屏用它而不是整条可执行文件路径：424 宽的正文列放不下一条 `C:\Program Files\…\bin\java.exe`， + /// 而用户认的是 JDK 目录（也是他手动添加时会粘的那一段）。 + #[must_use] + pub fn home(&self) -> String { + let path = std::path::Path::new(self.binary.trim()); + let parent = path.parent(); + match parent.filter(|dir| { + dir.file_name() + .is_some_and(|name| name.eq_ignore_ascii_case("bin")) + }) { + Some(bin) => bin + .parent() + .map_or_else(|| self.binary.clone(), |home| home.display().to_string()), + None => parent.map_or_else(|| self.binary.clone(), |dir| dir.display().to_string()), + } + } + + /// 上屏用的目录：过长时保留**尾部**两段，前面用 `…` 收掉。 + /// + /// 为什么必须截：无空格的 Windows 路径在 iced 的文本排版里不可断行，一条 60 字符的路径会直接 + /// 盖住右边的「设为默认」chip（M175 出图时实测到了这个重叠）。保尾部而不是开头，因为磁盘名 + /// （`C:`）谁都知道，而 `…\Java\temurin\17.0.13` 才是能区分两条 JDK 的那一段。 + #[must_use] + pub fn display_home(&self) -> String { + const LIMIT: usize = 39; + let home = self.home(); + if home.chars().count() <= LIMIT { + return home; + } + let tail: String = home + .chars() + .rev() + .take(LIMIT - 1) + .collect::>() + .into_iter() + .rev() + .collect(); + // 从第一个分隔符之后开始（别让 `…` 后面接着半截目录名）。 + let tail = tail + .find(['\\', '/']) + .map_or(tail.clone(), |at| tail[at + 1..].to_string()); + format!("…{}{}", std::path::MAIN_SEPARATOR, tail) + } + + /// 来源文案 key。 + #[must_use] + pub fn source_key(&self) -> Key { + match self.source { + "managed" => Key::SettingsJavaSourceManaged, + "env" => Key::SettingsJavaSourceEnv, + "path" => Key::SettingsJavaSourcePath, + "manual" => Key::SettingsJavaSourceManual, + _ => Key::SettingsJavaSourceSystem, + } + } +} + +/// 引号里的版本号（`openjdk version "21.0.11" 2025-10-21 LTS` → `21.0.11`）。 +fn quoted_version(line: &str) -> Option { + let start = line.find('"')? + 1; + let rest = &line[start..]; + let end = rest.find('"')?; + let value = rest[..end].trim(); + (!value.is_empty()).then(|| value.to_string()) +} + +/// 无引号形态里的版本样 token（`openjdk 25.0.3 2026-04-21` → `25.0.3`）。 +fn bare_version(line: &str) -> Option { + line.split_whitespace().find_map(|token| { + let candidate = token.trim_matches([',', '(', ')', '"']); + let mut parts = candidate.split('.'); + let first = parts.next()?; + let looks_like_version = first.chars().all(|c| c.is_ascii_digit()) + && !first.is_empty() + && parts.next().is_some(); + looks_like_version.then(|| candidate.to_string()) + }) +} + +#[cfg(test)] +mod tests { + use super::RuntimeRow; + + fn row(version: &str, major: Option) -> RuntimeRow { + RuntimeRow { + binary: "C:/jdk/bin/java.exe".to_string(), + version: version.to_string(), + major, + vendor: Some("Microsoft".to_string()), + source: "system", + } + } + + /// 版本号必须能区分同一大版本的两份 JDK（`17.0.13` vs `17.0.9`），不许只给 `17`。 + /// + /// 变异证明：把 `version_label` 换回「只用 `major`」，这条立刻红。 + #[test] + fn the_version_label_keeps_the_minor_digits() { + assert_eq!( + row("openjdk version \"17.0.13\" 2024-10-15", Some(17)).version_label(), + "17.0.13" + ); + assert_eq!( + row("openjdk version \"17.0.9\" 2024-01-16", Some(17)).version_label(), + "17.0.9" + ); + assert_ne!( + row("openjdk version \"17.0.13\" 2024-10-15", Some(17)).summary(), + row("openjdk version \"17.0.9\" 2024-01-16", Some(17)).summary(), + "两份同大版本 JDK 的摘要必须不同" + ); + assert_eq!( + row("openjdk 25.0.3 2026-04-21", Some(25)).version_label(), + "25.0.3", + "无引号形态也要认" + ); + assert_eq!( + row("something unexpected 21", Some(21)).version_label(), + "something unexpected 21", + "解析不出来时给原始版本串，不给光秃秃的大版本" + ); + assert_eq!(row("", Some(21)).version_label(), "21"); + assert_eq!(row("", None).version_label(), "?"); + } + + #[test] + fn the_summary_carries_version_and_vendor() { + assert_eq!( + row("openjdk version \"21.0.11\" 2025-10-21 LTS", Some(21)).summary(), + "Java 21.0.11 · Microsoft" + ); + } +} diff --git a/crates/app-iced/src/pages/settings/java/scan.rs b/crates/app-iced/src/pages/settings/java/scan.rs new file mode 100644 index 0000000..095bbfd --- /dev/null +++ b/crates/app-iced/src/pages/settings/java/scan.rs @@ -0,0 +1,188 @@ +//! 「Java」分组的**扫描槽与生产作业**（M204 r1 从 `store.rs` 拆出：那个文件加了 +//! `ScanSlot::seed_report` 之后 408 行，越过 400 行硬线）。 +//! +//! 两件事： +//! +//! | 东西 | 为什么在这 | +//! |---|---| +//! | [`ScanSlot`] | 后台线程写、界面每拍读的快照 + 取消位 + 「线程还活着」。它是**每份 `State` 一个**的槽（不是进程级 static），理由见结构体文档 | +//! | [`run_staged`] / [`rows`] | 生产作业：真扫盘 + 逐个探测（超时与取消都在 `core::game::java::staged::scan` 里），并把 `JavaRuntime` 翻成页面行 | +//! +//! `store.rs` 用 `pub use` 把 [`Job`] / [`ScanReport`] / [`ScanSlot`] 再导出，所以 +//! `pages::settings::java::store::ScanSlot` 这类既有路径**一个都不用改**。 + +use std::path::PathBuf; +use std::sync::atomic::{AtomicBool, Ordering}; +use std::sync::Mutex; + +use unlucky_core::game::java::{staged, JavaRuntime}; + +use super::state::RuntimeRow; + +/// 扫描结果快照（后台线程写、界面读）。 +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct ScanReport { + /// 扫描线程**还活着**（取消之后到它真退出之前仍是 `true`——这一段界面上叫「正在取消…」） + pub running: bool, + /// 已探测 + pub done: usize, + /// 候选总数（`0` = 候选表还在收集，界面不显示 `0/0`） + pub total: usize, + /// 至少完整扫完过一次 + pub finished: bool, + /// 用户按过取消（线程还活着时是 `true`） + pub cancelled: bool, + /// 扫描结论（`finished` 且没被取消时有效） + pub runtimes: Vec, +} + +/// 一次扫描的作业（生产实现是 [`run_staged`]；测试注入可控的假作业）。 +pub type Job = + fn(&[staged::Candidate], &dyn Fn() -> bool, &mut dyn FnMut(usize, usize)) -> Vec; + +/// 一次扫描的**状态槽**：快照 + 取消位 + 「线程还活着」。 +/// +/// 为什么不是进程级 static（M175 r1 复审 P2-5 的附带项）：全局状态有两个坏处—— +/// ①候选收集要在 UI 线程上抢同一把锁；②单测之间互相污染（一个用例起的扫描会让另一个用例 +/// 看到「变了」）。挂在 `State` 上之后，每个 `App` / 每个用例都有一份自己的槽。 +/// +/// 内部是 `Arc`：`State` 会被整体替换（hydrate），而扫描线程要活得比某一次 `State` 赋值更久。 +#[derive(Debug, Clone, Default)] +pub struct ScanSlot { + inner: std::sync::Arc, +} + +#[derive(Debug, Default)] +struct ScanInner { + report: Mutex, + cancel: AtomicBool, +} + +impl ScanSlot { + /// 当前快照（界面每拍读一次；锁只在这几行里持有）。 + #[must_use] + pub fn report(&self) -> ScanReport { + self.inner + .report + .lock() + .map(|report| report.clone()) + .unwrap_or_default() + } + + /// 把快照**直接摆成**给定值（只给 `--screenshot` 的种子用，M204 r1）。 + /// + /// 为什么种子不能只写 `State.scanning`：`clock.advance` 每拍都调 + /// `hydrate_java_scan` → `State::apply_scan(&self.scan.report())`，而 `scanning` + /// 是从**槽里的快照**推出来的。只改 `State` 的话，第一拍就会被推回「没在扫」， + /// 出图拍到的是另一种状态。与 `downloads::Slot::seed_report` 同一个理由、同一种做法。 + /// + /// 与 [`ScanSlot::start`] 的区别：这里不起线程、不摸取消位，只摆一个静态快照—— + /// 出图要的是**可复现**的一帧，不是真的在扫。 + pub fn seed_report(&self, report: ScanReport) { + if let Ok(mut slot) = self.inner.report.lock() { + *slot = report; + } + } + + /// 取消正在跑的扫描：置取消位 + 标 `cancelled`，**不**动 `running`。 + /// + /// `running` 由扫描线程自己翻——它是「线程还活着」的唯一真相。取消若也翻它，`start()` 的 + /// 「已在扫」判据就失效，用户能在旧线程还卡着的时候起第二个（复审 P2-5 的第三个问题）。 + pub fn cancel(&self) { + self.inner.cancel.store(true, Ordering::SeqCst); + if let Ok(mut report) = self.inner.report.lock() { + if report.running { + report.cancelled = true; + } + } + } + + /// 发起一次扫描（已在扫 ⇒ 什么都不做，返回 `false`）。 + pub fn start(&self, roots: Vec, manual: Vec, system: bool) -> bool { + self.start_with(roots, manual, system, run_staged) + } + + /// 同 [`ScanSlot::start`]，但扫描作业可注入（测试用：一个可控的、会一直卡住的作业）。 + pub fn start_with( + &self, + roots: Vec, + manual: Vec, + system: bool, + job: Job, + ) -> bool { + { + let Ok(mut report) = self.inner.report.lock() else { + return false; + }; + if report.running { + return false; + } + // 「占位」与「线程起来了」在同一把锁里完成：两个调用不可能同时通过上面那道判据。 + *report = ScanReport { + running: true, + ..ScanReport::default() + }; + self.inner.cancel.store(false, Ordering::SeqCst); + } + + let slot = self.clone(); + std::thread::spawn(move || { + // 候选收集（注册表 / 常见目录）放在线程里：它是首屏那一拍最贵的一段， + // 放在 UI 线程上会拖慢开窗（复审 P2-5 的附带项）。 + let candidates = staged::candidates(&roots, &manual, system); + if let Ok(mut report) = slot.inner.report.lock() { + report.total = candidates.len(); + } + let cancelled = || slot.inner.cancel.load(Ordering::SeqCst); + let mut progress = |done: usize, _total: usize| { + if let Ok(mut report) = slot.inner.report.lock() { + report.done = done; + } + }; + let runtimes = job(&candidates, &cancelled, &mut progress); + if let Ok(mut report) = slot.inner.report.lock() { + report.running = false; + report.done = candidates.len(); + if !report.cancelled { + report.finished = true; + report.runtimes = runtimes; + } + } + }); + true + } +} + +/// 生产扫描作业：真扫盘 + 逐个探测（超时与取消都在 `staged::scan` 里）。 +fn run_staged( + candidates: &[staged::Candidate], + cancelled: &dyn Fn() -> bool, + progress: &mut dyn FnMut(usize, usize), +) -> Vec { + let found = staged::scan( + candidates, + |done, total| { + progress(done, total); + true + }, + cancelled, + ); + rows(&found, candidates) +} + +/// `JavaRuntime` → 页面行（来源从候选表里按路径回查：`JavaRuntime.origin` 分不出「手动」）。 +fn rows(found: &[JavaRuntime], candidates: &[staged::Candidate]) -> Vec { + found + .iter() + .map(|runtime| RuntimeRow { + binary: runtime.binary.display().to_string(), + version: runtime.version.clone().unwrap_or_default(), + major: runtime.major, + vendor: runtime.vendor.clone(), + source: candidates + .iter() + .find(|candidate| candidate.binary == runtime.binary) + .map_or("system", |candidate| candidate.source.id()), + }) + .collect() +} diff --git a/crates/app-iced/src/pages/settings/java/seed.rs b/crates/app-iced/src/pages/settings/java/seed.rs new file mode 100644 index 0000000..1730fab --- /dev/null +++ b/crates/app-iced/src/pages/settings/java/seed.rs @@ -0,0 +1,233 @@ +//! 「Java」分组的截图种子（M175，`ULL_JAVA_STATE`）：**只给 `--screenshot` 用**。 +//! +//! 三档对应任务书要的三张图：未安装 Java 的空态 / 检测到两个 JDK 并选中其一 / 内存与 JVM 参数 +//! 的编辑态。编辑态只让**内存**越界（`validate()` 一次只报第一个错，所以图上看到的是「内存超出 +//! 允许范围」+ 内存框标红；引号那条另有单测，不靠这张图证明）。 +//! +//! M197 加了三档，对应「下载一个 JDK」的三态（任务书要的三张图）：`download`（版本选择列表）/ +//! `downloading`（下载中：百分比 + 当前源 + 一次退避）/ `download-failed`（失败：最后试到的源）。 +//! 三档都把三个设置键摆成生产上真会出现的值（自定义落点 + 自己排的发行版顺序 + 自动准备开着）， +//! 于是一张图里能同时看到「版本目录」与「三个键」。 +//! +//! 与 `ULL_AI_STATE` / `ULL_UPDATE_STATE` / `ULL_FONT_STATUS` 同一族取证开关：只影响这一次进程， +//! 产品路径不设它。种子里的路径是**写死的示例路径**（真实机器上没有），所以它只在出图通道里出现； +//! 产品路径的真值一律来自 `core::game::java::staged` 的真扫盘。 +//! +//! M204 r1（视觉复审 p2-1）又补了三档：`scanning`（正在扫描… 3/7，「取消」可点）/ `unscanned` +//! （还没扫描过）/ `cancelling`（正在取消…，两颗按钮都灰）。起因是六张举证图里「取消」全程是 +//! 禁用态，「扫描中」一格都没拍，而 README 却写成「两态」——**证据覆盖不到结论**（M201 同一个坑）。 +//! 这三档都把快照写进 `ScanSlot`（`store::ScanSlot::seed_report`），理由见那个函数的文档。 + +use super::state::{Context, Layer, Notice, Refusal, Requirement, RuntimeRow, State}; + +/// 取证开关 `ULL_JAVA_STATE`（只给 `--screenshot` 用）。 +/// +/// 三档对应三张图：`empty`（未检测到）/ `two`（两个 JDK 并选中其一）/ `editing`（改了内存与 +/// JVM 参数、还没保存）。与 `ULL_AI_STATE` / `ULL_UPDATE_STATE` 同一族，只影响这一次进程。 +#[must_use] +pub fn build(raw: &str) -> Option { + let mut state = State { + storage: true, + scanned: true, + ..State::default() + }; + match raw.trim() { + "empty" => { + state.memory = "2048".to_string(); + state.saved_memory = 2048; + } + "two" => { + state.runtimes = vec![ + RuntimeRow { + binary: "C:/Program Files/Eclipse Adoptium/jdk-17.0.13/bin/java.exe" + .to_string(), + version: "openjdk version \"17.0.13\" 2024-10-15".to_string(), + major: Some(17), + vendor: Some("Temurin".to_string()), + source: "system", + }, + RuntimeRow { + binary: "C:/Program Files/Microsoft/jdk-21.0.4/bin/java.exe".to_string(), + version: "openjdk version \"21.0.4\" 2024-07-16 LTS".to_string(), + major: Some(21), + vendor: Some("Microsoft".to_string()), + source: "system", + }, + ]; + state.selected = state.runtimes[1].binary.clone(); + state.manual = vec!["D:/jdk/zulu-21".to_string()]; + state.memory = "4096".to_string(); + state.saved_memory = 4096; + state.jvm = "-XX:+UseG1GC".to_string(); + state.saved_jvm = "-XX:+UseG1GC".to_string(); + state.context = Context { + required: Some(Requirement { + instance: "生存服".to_string(), + version: "1.20.1".to_string(), + minimum: 17, + maximum: None, + }), + layer: Some(Layer::Global), + effective_memory_mb: Some(4096), + }; + } + "editing" => { + let mut seeded = build("two")?; + seeded.memory = "128".to_string(); + seeded.jvm = "-XX:+UseG1GC -Xss\"512k".to_string(); + seeded.dirty = true; + seeded.notice = Some(Notice::Refused(Refusal::MemoryRange)); + return Some(seeded); + } + // ── M204 r1（视觉复审 p2-1）：扫描的三格。复审指出六张图里「取消」全程是禁用态、 + // 「正在扫描… 3/7」一张没有，而 README 却写成了「两态」——这里补上能画出来的三格 + // （扫描中 / 还没扫描过 / 正在取消…；「扫描已取消…」那一句仍没有图，见 README §3）。 + // + // 三档都把快照**写进槽**（`ScanSlot::seed_report`）而不只是改 `State.scanning`： + // 心跳每拍用槽里的快照重算 `scanning`，只改 `State` 的话第一拍就被推回「没在扫」。 + "scanning" => { + let mut seeded = build("two")?; + // 扫描中：列表还没有结论（`scanned` 仍是 false），状态行画「正在扫描… 3/7」， + // 「立即扫描」灰掉、「取消」可点（`view.rs` 的 `scanning && !cancelled`）。 + seeded.scanned = false; + seeded.runtimes.clear(); + seeded.cancelled = false; + seeded.scanning = Some(super::state::Progress { done: 3, total: 7 }); + seeded.scan.seed_report(super::store::ScanReport { + running: true, + done: 3, + total: 7, + finished: false, + cancelled: false, + runtimes: Vec::new(), + }); + return Some(seeded); + } + "unscanned" => { + // 还没扫描过：状态行「还没扫描过」，列表处画「列表还是空的…」（`view.rs:110-113`）。 + let mut seeded = build("empty")?; + seeded.scanned = false; + seeded.scanning = None; + seeded.cancelled = false; + seeded.scan.seed_report(super::store::ScanReport::default()); + return Some(seeded); + } + "cancelling" => { + // 取消已按下、线程还没退出：状态行「正在取消…」、两颗按钮都灰（复审点名的另一格）。 + let mut seeded = build("scanning")?; + seeded.cancelled = true; + seeded.scan.seed_report(super::store::ScanReport { + running: true, + done: 3, + total: 7, + finished: false, + cancelled: true, + runtimes: Vec::new(), + }); + return Some(seeded); + } + // ── M197：「下载一个 JDK」的三态 + "download" => { + let mut seeded = build("two")?; + seeded.context = download_context(21); + seeded.prefs = seeded_prefs(); + seeded.effective = seeded_effective(); + return Some(seeded); + } + "downloading" => { + let seeded = build("download")?; + seeded.downloads.seed_report(super::downloads::Report { + job: Some(super::downloads::Job { + major: 21, + phase: super::downloads::Phase::Downloading, + downloaded: 96_468_992, + total: Some(210_763_776), + source: Some("tuna".to_string()), + last: Some(super::downloads::Event::Retry { + source: "tuna".to_string(), + kind: unlucky_core::download::DownloadErrorKind::ServerError, + attempt: 2, + retry_in_ms: 2_000, + }), + }), + tries: vec![super::downloads::Try { + source: "tuna".to_string(), + kind: unlucky_core::download::DownloadErrorKind::ServerError, + }], + failure: None, + success: None, + }); + return Some(seeded); + } + "download-failed" => { + let seeded = build("download")?; + seeded.downloads.seed_report(super::downloads::Report { + job: None, + // 出图要能看见「试过哪些源、各自为什么」：两条真实形态的失败。 + tries: vec![ + super::downloads::Try { + source: "tuna".to_string(), + kind: unlucky_core::download::DownloadErrorKind::NotFound, + }, + super::downloads::Try { + source: "github".to_string(), + kind: unlucky_core::download::DownloadErrorKind::Timeout, + }, + ], + success: None, + failure: Some(super::downloads::Failure { + major: 21, + kind: unlucky_core::game::java::JavaErrorKind::Network, + source: Some("github".to_string()), + }), + }); + return Some(seeded); + } + _ => return None, + } + Some(state) +} + +/// 出图用的「当前实例要求」（`1.20.5` 起要 21）。 +fn download_context(minimum: u32) -> Context { + Context { + required: Some(Requirement { + instance: "生存服".to_string(), + version: "1.20.5".to_string(), + minimum, + maximum: None, + }), + layer: Some(Layer::Global), + effective_memory_mb: Some(4096), + } +} + +/// 出图用的三键：自定义落点 + 自己排的顺序（第一行不是默认的那家）+ 自动准备开着。 +fn seeded_prefs() -> super::prefs::Prefs { + super::prefs::Prefs { + install_root: "D:/Java".to_string(), + saved_install_root: "D:/Java".to_string(), + auto_install: true, + saved_auto_install: true, + priority: vec!["microsoft", "temurin", "oracle", "zulu"], + saved_priority: vec!["microsoft", "temurin", "oracle", "zulu"], + } +} + +/// 出图用的生效值（与 [`seeded_prefs`] 一致：落点与顺序都来自设置）。 +fn seeded_effective() -> super::prefs::Effective { + super::prefs::Effective { + root: "D:/Java".to_string(), + root_mode: "custom", + root_layer: super::prefs::RootLayer::Setting, + root_unresolved: false, + order: vec![ + "Microsoft OpenJDK", + "Eclipse Temurin", + "Oracle OpenJDK", + "Azul Zulu", + ], + order_layer: super::prefs::OrderLayer::Setting, + domestic: true, + } +} diff --git a/crates/app-iced/src/pages/settings/java/state.rs b/crates/app-iced/src/pages/settings/java/state.rs new file mode 100644 index 0000000..0b7c85d --- /dev/null +++ b/crates/app-iced/src/pages/settings/java/state.rs @@ -0,0 +1,383 @@ +//! 「Java」分组的运行期状态（M175）：扫描结论 + 手动名单 + 两个可编辑项。 +//! +//! 状态住在 `pages::settings::Groups.java`（[`State`]），由 `App` 持有。三条边界： +//! +//! | 东西 | 住哪 | 为什么 | +//! |---|---|---| +//! | 扫描结论 / 进度 | 本结构（由后台线程的快照 1 拍一拍灌进来） | 用户切走再回来不该重扫 | +//! | 手动加的路径名单 | 本结构 + 一个纯文本文件（`store::manual_file`） | 它是「我加过哪些」的记忆，不是启动策略 | +//! | `java.selected_path` / `default_memory_mb` / `extra_args` | **`config/launcher.json`** | 真值只有一份，读回也读它 | +//! +//! ## 为什么内存草稿要记两层（`memory` 文本 + `saved_memory` 数值） +//! +//! 输入框里的是**文本**（用户可能刚敲了半截「819」），而「现在生效多少」是**落盘的真值**。 +//! 两者混成一个字段就会重演「显示的就是生效的」这种假象：改到一半的数字不是生效值。 +//! 于是草稿只影响「有未保存改动」与「保存按钮能不能点」，生效值一律来自 `saved_*`（落盘后读回的）。 +//! +//! ## 版本门槛从哪来 +//! +//! [`Context::required`] 由 **app 层**（`app/update/settings/java.rs`）算好塞进来：它要读实例快照 +//! （`requirement_for(mc_version)`），而页面渲染器只拿得到 [`super::States`]。 +//! 页面自己不去读盘、也不复制版本表。 + +pub use super::row::RuntimeRow; + +/// M197 起 `Requirement` / `Layer` / `Context` / `Fit` 住在 [`super::context`]（本文件加了三键状态 +/// 与下载槽之后越过 400 行硬线），三键的草稿与生效值住在 [`super::prefs`]——这里一并转出去， +/// 调用方仍然只认识 `pages::settings::java::{Context, Layer, Requirement}` 这一组名字。 +pub use super::context::{Context, Fit, Layer, Requirement}; + +use unlucky_i18n::Key; + +/// `java.default_memory_mb` 的下限（MB）。 +/// +/// **必须**等于 `core::setting::keys` 里那个键登记的下限（512）：UI 放行一个 schema 会拒的值， +/// 用户点保存只会得到一条「schema 拒绝」的错。一致性由 `tests::the_memory_bounds_mirror_the_schema` 守。 +pub const MIN_MEMORY_MB: u32 = 512; +/// `java.default_memory_mb` 的上限（MB）。 +pub const MAX_MEMORY_MB: u32 = 65536; +/// `java.default_memory_mb` 的出厂默认值（MB）：与 schema 的默认值同源， +/// 一致性由 `tests::the_memory_bounds_mirror_the_schema` 守。 +pub const DEFAULT_MEMORY_MB: u32 = 2048; +/// `java.extra_args` 的长度上限（字符）：**必须**等于 schema 登记的 `Text{max_len: 1024}`。 +/// +/// 为什么页面要自己再判一次（M199）：schema 那一道是在 `store.set` 里拒的，用户得到的是 +/// `Notice::WriteFailed`（「写不进去」）+ 一句带具体长度的中文只进 stderr——粘了一大段参数的 +/// 人不知道是长度问题。一致性由 `tests::the_jvm_length_mirrors_the_schema` 守。 +pub const MAX_JVM_ARGS: usize = 1024; + +/// 扫描进度（`None` = 没在扫）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct Progress { + /// 已探测的候选数 + pub done: usize, + /// 候选总数 + pub total: usize, +} + +/// 保存 / 操作的回执。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum Notice { + /// 已落盘并读回 + Saved, + /// 本地校验拒绝（没写盘） + Refused(Refusal), + /// 设置文件层面拒绝：只读 / 不可信 / 没有改动（i18n key，不拼字符串） + Unwritable(Unwritable), + /// 写盘失败（schema / 磁盘）：core 的 `Display` 是中文，不能直出给英文界面， + /// 所以这里只带一个页面自己的 key；原始句子进 stderr 日志。 + WriteFailed, + /// 没有可写文件（内存态运行） + NoStorage, + /// 默认 JDK 已写进 `java.selected_path` + DefaultSet(String), + /// 手动路径已加入名单 + Added(String), + /// 三个设置键已落盘并读回（M197） + PrefsSaved, +} + +/// 设置文件层面拒绝的三档（`SettingStore::save` 的 `Skipped` 三因）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Unwritable { + /// 没有任何脏键（我们以为改了、其实没有） + NotDirty, + /// 文件只读（被更新版本的启动器写过 / 被标记不可信） + ReadOnly, + /// 文件不可信（加载时就降级成只读） + Unreadable, +} + +impl Unwritable { + /// 文案 key。 + #[must_use] + pub const fn label(self) -> Key { + match self { + Self::NotDirty => Key::SettingsJavaSkipNotDirty, + Self::ReadOnly => Key::SettingsJavaSkipReadOnly, + Self::Unreadable => Key::SettingsJavaSkipUnreadable, + } + } +} + +/// 本地校验的拒绝原因。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Refusal { + /// 内存草稿为空 + MemoryEmpty, + /// 内存草稿不是整数 + MemoryNotNumber, + /// 内存越界 + MemoryRange, + /// JVM 参数里的引号没配成对 + JvmQuotes, + /// `java.extra_args` 超过 schema 登记的长度上限（1024） + JvmTooLong, + /// 手动路径为空 + AddEmpty, + /// 手动路径在盘上找不到 + AddMissing, + /// 有这个东西，但不是 java 可执行文件 + AddNotJava, + /// 跑不出 `-version` + AddNoVersion, + /// 路径太长（粘了一整段日志） + AddTooLong, + /// 名单文件写不进去（磁盘 / 权限） + AddWriteFailed, + /// 已经加过了 + AddDuplicate, + /// `java.installRoot` 超过 schema 登记的长度上限（512） + InstallRootTooLong, +} + +impl Refusal { + /// 文案 key。 + #[must_use] + pub const fn label(self) -> Key { + match self { + Self::MemoryEmpty => Key::SettingsJavaReasonMemoryEmpty, + Self::MemoryNotNumber => Key::SettingsJavaReasonMemoryNotNumber, + Self::MemoryRange => Key::SettingsJavaReasonMemoryRange, + Self::JvmQuotes => Key::SettingsJavaReasonJvmQuotes, + Self::JvmTooLong => Key::SettingsJavaReasonJvmTooLong, + Self::AddEmpty => Key::SettingsJavaReasonAddEmpty, + Self::AddMissing => Key::SettingsJavaReasonAddMissing, + Self::AddNotJava => Key::SettingsJavaReasonAddNotJava, + Self::AddNoVersion => Key::SettingsJavaReasonAddNoVersion, + Self::AddTooLong => Key::SettingsJavaReasonAddTooLong, + Self::AddWriteFailed => Key::SettingsJavaReasonAddWriteFailed, + Self::AddDuplicate => Key::SettingsJavaReasonAddDuplicate, + Self::InstallRootTooLong => Key::SettingsJavaReasonInstallRootTooLong, + } + } +} + +/// 「Java」分组的运行期状态。 +#[derive(Debug)] +pub struct State { + /// 扫到的运行时（顺序 = 大版本升序，探测不到主版本的排最后） + pub runtimes: Vec, + /// 至少完整扫过一次（区分「未检测到」与「还没扫」） + pub scanned: bool, + /// 扫描进度 + pub scanning: Option, + /// 上一次扫描被用户取消（界面上要说一句，否则「列表没变」会被当成没扫） + pub cancelled: bool, + /// 扫描状态槽（快照 + 取消位；线程与界面共享同一份） + pub scan: super::store::ScanSlot, + /// 用户手动加的路径（原样，持久化在 `manual_file`） + pub manual: Vec, + /// `java.selected_path` 的真值（空 = 没指定，启动时自动挑） + pub selected: String, + /// 内存草稿（MB 文本） + pub memory: String, + /// 落盘的内存真值（MB） + pub saved_memory: u32, + /// JVM 参数草稿 + pub jvm: String, + /// 落盘的 JVM 参数真值 + pub saved_jvm: String, + /// 手动路径输入框 + pub add_draft: String, + /// 有未保存的改动 + pub dirty: bool, + /// 这一次运行有没有可写的设置文件 + pub storage: bool, + /// 上一次操作的回执 + pub notice: Option, + /// 当前实例的上下文（版本门槛 / 生效内存层级） + pub context: Context, + /// 三个设置键的草稿 + 落盘真值（M197：`installRoot` / `vendorPriority` / `auto_install`） + pub prefs: super::prefs::Prefs, + /// 上述三键的**生效值 + 来源层**（app 层每次 hydrate 重算） + pub effective: super::prefs::Effective, + /// 「下载一个 JDK」的作业槽（后台线程写、界面读） + pub downloads: super::downloads::Slot, + /// 上一次「下载按钮被拒」的原因（点了没反应是禁止的） + pub download_notice: Option, + /// 已经处理过的那份下载快照（用来判「刚成功」——装完要重扫一次并把新 JDK 收进来） + pub download_seen: super::downloads::Report, +} + +impl Default for State { + fn default() -> Self { + Self { + runtimes: Vec::new(), + scanned: false, + scanning: None, + cancelled: false, + scan: super::store::ScanSlot::default(), + manual: Vec::new(), + selected: String::new(), + memory: String::new(), + saved_memory: DEFAULT_MEMORY_MB, + jvm: String::new(), + saved_jvm: String::new(), + add_draft: String::new(), + dirty: false, + storage: false, + notice: None, + context: Context::default(), + prefs: super::prefs::Prefs::default(), + effective: super::prefs::Effective::default(), + downloads: super::downloads::Slot::default(), + download_notice: None, + download_seen: super::downloads::Report::default(), + } + } +} + +/// 从 `launcher.json` 读回来的三键真值。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Snapshot { + /// `java.selected_path` + pub selected: String, + /// `java.default_memory_mb` + pub memory_mb: u32, + /// `java.extra_args` + pub jvm: String, +} + +impl State { + /// 用真值刷新（**脏草稿不覆盖**，否则外部一改文件就冲掉用户正在输入的内容）。 + /// + /// 返回是否改了「生效值」那一半（调用方据此决定要不要重建视图模型）。 + pub fn hydrate(&mut self, snapshot: Snapshot) -> bool { + self.storage = true; + let Snapshot { + selected, + memory_mb, + jvm, + } = snapshot; + let changed = + self.selected != selected || self.saved_memory != memory_mb || self.saved_jvm != jvm; + self.selected = selected; + self.saved_memory = memory_mb; + if !self.dirty { + self.memory = memory_mb.to_string(); + self.jvm = jvm.clone(); + } + self.saved_jvm = jvm; + changed + } + + /// 灌一次扫描结论（后台线程的快照）。返回是否变了。 + pub fn apply_scan(&mut self, report: &super::store::ScanReport) -> bool { + let scanning = report.running.then_some(Progress { + done: report.done, + total: report.total, + }); + let changed = self.scanning != scanning + || self.cancelled != report.cancelled + || (report.finished && !self.scanned) + || (report.finished && self.runtimes != report.runtimes); + self.scanning = scanning; + self.cancelled = report.cancelled; + if report.finished { + self.scanned = true; + self.runtimes = report.runtimes.clone(); + } + changed + } + + /// 某个大版本够不够当前实例用（`None` = 没有实例 / 那个版本探测不出版本号）。 + /// + /// 返回的是**带方向**的三态：老版本 MC 只能用 Java 8，「Java 21 太高」与「Java 8 太低」 + /// 在界面上是两句话（M197 的第三条任务不许静默失败）。 + #[must_use] + pub fn fit(&self, major: Option) -> Option { + let (Some(required), Some(major)) = (self.context.required.as_ref(), major) else { + return None; + }; + Some(required.fit(major)) + } + + /// 保存前的本地校验（过不了就不写盘）。 + /// + /// # Errors + /// 内存不是整数 / 越界，JVM 参数引号没配成对，或 JVM 参数超过 schema 登记的长度上限时 + /// 返回原因。 + pub fn validate(&self) -> Result { + let text = self.memory.trim(); + if text.is_empty() { + return Err(Refusal::MemoryEmpty); + } + let Ok(mb) = text.parse::() else { + return Err(Refusal::MemoryNotNumber); + }; + if !(MIN_MEMORY_MB..=MAX_MEMORY_MB).contains(&mb) { + return Err(Refusal::MemoryRange); + } + if unbalanced_quotes(&self.jvm) { + return Err(Refusal::JvmQuotes); + } + // 与 schema 同一个口径（`spec.rs` 的 `ValueKind::Text` 数 `chars()`，写盘前 `trim()`）。 + if self.jvm.trim().chars().count() > MAX_JVM_ARGS { + return Err(Refusal::JvmTooLong); + } + Ok(mb) + } + + /// 界面上「现在生效多少」的那句话用哪一层（没有上下文时按全局）。 + #[must_use] + pub fn layer(&self) -> Layer { + self.context.layer.clone().unwrap_or(Layer::Global) + } + + /// 生效的（落盘的）发行版优先级，给「这一档能由哪几家承接」用。 + /// + /// 用**落盘值**而不是草稿：列表边上那句「发行版：…」描述的是真跑起来会试的那条链； + /// 草稿只影响「保存之后」。 + #[must_use] + pub fn priority_vendors(&self) -> Vec { + self.prefs + .saved_priority + .iter() + .filter_map(|id| unlucky_core::game::java::JdkVendor::parse(id)) + .collect() + } + + /// 现在能不能点保存。 + #[must_use] + pub fn can_save(&self) -> bool { + self.storage && self.dirty + } + + /// 当前默认运行时那一行（`selected` 指向的）。 + #[must_use] + pub fn default_row(&self) -> Option<&RuntimeRow> { + self.runtimes + .iter() + .find(|row| same_path(&row.binary, &self.selected)) + } + + /// 取证开关 `ULL_JAVA_STATE`（只给 `--screenshot` 用；三档的实现在 `java/seed.rs`）。 + /// + /// 三档：`empty`（未检测到）/ `two`（两个 JDK 并选中其一）/ `editing`（改了内存与 JVM 参数、 + /// 还没保存）。与 `ULL_AI_STATE` / `ULL_UPDATE_STATE` 同一族，只影响这一次进程。 + #[must_use] + pub fn screenshot_seed(raw: &str) -> Option { + super::seed::build(raw) + } +} + +/// 两条路径是不是同一个（`/` 与 `\` 视为同一分隔符；Windows 折大小写）。 +#[must_use] +pub fn same_path(left: &str, right: &str) -> bool { + let key = |text: &str| { + let text = text.replace('\\', "/"); + if cfg!(windows) { + text.to_ascii_lowercase() + } else { + text + } + }; + !left.trim().is_empty() && key(left.trim()) == key(right.trim()) +} + +/// 引号（`"` 与 `'`）数量是不是奇数——奇数就意味着用户漏了一半。 +#[must_use] +pub fn unbalanced_quotes(text: &str) -> bool { + text.matches('"').count() % 2 == 1 || text.matches('\'').count() % 2 == 1 +} diff --git a/crates/app-iced/src/pages/settings/java/store.rs b/crates/app-iced/src/pages/settings/java/store.rs new file mode 100644 index 0000000..e8cae9c --- /dev/null +++ b/crates/app-iced/src/pages/settings/java/store.rs @@ -0,0 +1,243 @@ +//! 「Java」分组的真读写（M175）：设置三键 + 手动名单 + 后台扫描。 +//! +//! ## 写盘走 `SettingStore`，与 `ai/store.rs` 同一条通路 +//! +//! `java.selected_path` / `java.default_memory_mb` / `java.extra_args` 都是 +//! `config/launcher.json` 里的 schema 键（`core::setting::keys` 已登记，本 mission 不动 schema）。 +//! 于是这里只做「读一份 → 改几个键 → 存 → **再从磁盘读回来**」：`save()` 有 `Skipped` 一档 +//! （只读 / 文件被更新版本写过 / 没有脏键），把它当成功就会出现「界面说已保存、重启回旧值」。 +//! 失败一律走 [`WriteError`]：**要么是页面自己的拒绝原因（i18n key），要么是 core 给的原始句子**， +//! 不再把 Rust 枚举名（`"MemoryRange"`）当人话往上抛（M175 r1 复审 P2-2）。 +//! +//! ## 扫描为什么是「进程级快照 + 后台线程」，不是 `Task::perform` +//! +//! 与 `fonts::install` 同一条理由（那里记了完整推导）：本 crate 的执行器是 `thread-pool`， +//! 而扫描要的是**进度（3/7）+ 取消 + 不卡 UI**。快照方案的代价是一把短锁 + 1 拍一次比较， +//! 好处是窗口关掉之后不会往死掉的 channel 里写。界面的刷新节奏见 `app/update/clock.rs` +//! 与 `app/subscription.rs`（扫描期间按帧跑，扫描结束回到 1 Hz）。 +//! +//! ### 三条与「取消」有关的硬约束（M175 r1 复审 P2-5） +//! +//! 1. **每个候选都有超时**：卡住的 `java -version` 由 `core::game::java::manual` 的 +//! `run_with_timeout` kill 掉，扫描线程不会永远不结束； +//! 2. **取消打断的是「正在跑的那一个」**：取消位一路传进探测函数，不必等它自己结束； +//! 3. **同时只允许一个扫描线程**：[`ScanReport::running`] 的含义就是「线程还活着」， +//! 取消**不**翻这个位（只置 `cancelled`），于是取消到线程真退出之间点「立即扫描」 +//! 不会起第二个线程——界面上那一小段显示的是「正在取消…」。 +//! +//! ## 手动名单为什么是纯文本文件 +//! +//! 它记的是「我手动加过哪些路径」，不是启动策略（真正决定用哪个 Java 的是 `java.selected_path`）。 +//! 放进 `launcher.json` 要新登记一个 schema 键并推 minor（会让旧版本整份文件变只读）， +//! 代价远大于收益；而 `core::game::java::manual` 的读写是纯文本、一行一个，坏了顶多丢名单。 + +use std::path::{Path, PathBuf}; + +use unlucky_core::game::java::{discover, manual, JavaRuntime}; +use unlucky_core::platform::paths::{Platform, ProcessEnv}; +use unlucky_core::setting::keys::launcher_schema; +use unlucky_core::setting::store::{SaveOutcome, SettingStore}; + +use super::state::{Refusal, RuntimeRow, Snapshot, State, Unwritable}; + +// M204 r1：扫描槽与生产作业搬到了 [`super::scan`]（本文件加 `ScanSlot::seed_report` 之后 +// 408 行，越过 400 行硬线）。这里再导出，`store::ScanSlot` / `store::ScanReport` 这些既有路径 +// **一个都不用改**；`Job` 只被 `scan` 内部用，不外抛（外抛会让本文件多一条 unused 警告）。 +pub use super::scan::{ScanReport, ScanSlot}; + +/// 该不该**自动**发起一次扫描（首屏 / 配置文件刚被外部改过时）。 +/// +/// 四条都要成立：①不是截图通道（D30：同一份代码出同一张图，截图不许读本机装了什么）； +/// ②没有在扫；③**没被取消过**（一次取消 = 本进程不再自动扫：被取消的扫描 `finished` 仍是 +/// `false`，而 `launcher.json` 每改一次（存内存、改主题、改语言、存 AI 配置）心跳就会走一次 +/// `hydrate_java_settings`，不看这一条就会把用户的取消无声撤销）；④还没扫完过（一次就够—— +/// 用户手动点「立即扫描」走的是 `start`，不看这里）。 +/// +/// 单独抽出来是因为它是「用户实测的头一条抱怨」（设置页从来自动检测本机 Java）的开关： +/// 判据写在这里，`tests/cmdline.rs` 逐档断言，改坏立刻红。 +#[must_use] +pub fn auto_scan_due(report: &ScanReport, screenshot: bool) -> bool { + !screenshot && !report.running && !report.cancelled && !report.finished +} + +/// 托管安装根（`/data/java-managed` + `java.installRoot` + 标准落点）。 +/// +/// 从**我们正在写的那份 `launcher.json`** 的上一级推 launcher home：这比重新解析一次数据根模式 +/// 更可信（三模式解析已经在 `SettingsBridge::open` 里做过一遍了）。 +#[must_use] +pub fn managed_roots(config: &Path) -> Vec { + let Some(home) = config.parent().and_then(Path::parent) else { + return Vec::new(); + }; + let layout = unlucky_core::platform::layout::LauncherLayout::new(home); + let override_root = SettingStore::load(config, launcher_schema()) + .doc() + .effective_str("java.installRoot") + .map(str::trim) + .filter(|text| !text.is_empty()) + .map(PathBuf::from); + unlucky_core::game::java::location::scan_roots( + unlucky_core::platform::data_dir::DataMode::Portable, + &layout, + override_root.as_deref(), + Platform::current(), + &ProcessEnv, + ) +} + +/// 手动名单文件（与 `launcher.json` 同一个 `config/`）。 +#[must_use] +pub fn manual_file(config: &Path) -> PathBuf { + config.parent().map_or_else( + || PathBuf::from("java-extra-paths.txt"), + |dir| dir.join("java-extra-paths.txt"), + ) +} + +/// 读三键真值。 +#[must_use] +pub fn load(config: &Path) -> Snapshot { + snapshot(SettingStore::load(config, launcher_schema()).doc()) +} + +/// 写盘失败的三种来源（都是「没写进去」，但对用户要说的不是同一句话）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum WriteError { + /// 页面自己的校验拒绝（i18n key） + Refused(Refusal), + /// 设置文件层面拒绝：只读 / 不可信 / 没有改动（i18n key） + Unwritable(Unwritable), + /// schema / 磁盘给的原始句子（core 的文案，不属于本页） + Schema(String), +} + +/// 保存内存 + JVM 参数，返回**落盘后读回来**的真值。 +/// +/// # Errors +/// 本地校验不过（[`WriteError::Refused`]）、文件只读/不可信（[`WriteError::Unwritable`]） +/// 或 schema 拒绝（[`WriteError::Schema`]）时返回原因。 +pub fn save(config: &Path, state: &State) -> Result { + let mb = state.validate().map_err(WriteError::Refused)?; + let mut store = SettingStore::load(config, launcher_schema()); + store + .set("java.default_memory_mb", i64::from(mb).into()) + .and_then(|()| store.set("java.extra_args", state.jvm.trim().to_string().into())) + .map_err(|error| WriteError::Schema(format!("{error}")))?; + finish(store, config) +} + +/// 写 `java.selected_path`（选定默认 JDK），返回落盘后读回来的真值。 +/// +/// # Errors +/// 文件只读/不可信或 schema 拒绝时返回原因。 +pub fn set_selected(config: &Path, binary: &str) -> Result { + let mut store = SettingStore::load(config, launcher_schema()); + store + .set("java.selected_path", binary.to_string().into()) + .map_err(|error| WriteError::Schema(format!("{error}")))?; + finish(store, config) +} + +/// 落盘 + 判定 + 读回（`save` / `set_selected` 共用：只认 `Saved` 一档）。 +fn finish(mut store: SettingStore, config: &Path) -> Result { + match store.save() { + Ok(SaveOutcome::Saved(_)) => Ok(load(config)), + Ok(SaveOutcome::Skipped(reason)) => Err(WriteError::Unwritable(unwritable(reason))), + Err(error) => Err(WriteError::Schema(format!("{error}"))), + } +} + +/// `SkipReason` → 页面原因（**不**再用中文字符串：那是 r1 复审 P2-2 的第一条）。 +pub(super) fn unwritable(reason: unlucky_core::setting::store::SkipReason) -> Unwritable { + use unlucky_core::setting::store::SkipReason; + match reason { + SkipReason::NotDirty => Unwritable::NotDirty, + SkipReason::ReadOnly => Unwritable::ReadOnly, + SkipReason::Unreadable => Unwritable::Unreadable, + } +} + +/// 文档 → 快照。 +fn snapshot(doc: &unlucky_core::setting::document::SettingDocument) -> Snapshot { + Snapshot { + selected: doc + .effective_str("java.selected_path") + .unwrap_or_default() + .trim() + .to_string(), + memory_mb: doc + .effective_i64("java.default_memory_mb") + .and_then(|value| u32::try_from(value).ok()) + .unwrap_or(super::state::DEFAULT_MEMORY_MB), + jvm: doc + .effective_str("java.extra_args") + .unwrap_or_default() + .to_string(), + } +} + +/// 读手动名单。 +#[must_use] +pub fn load_manual(config: &Path) -> Vec { + manual::load_paths(&manual_file(config)) + .iter() + .map(|path| path.display().to_string()) + .collect() +} + +/// 手动加一个路径：严格校验（真跑 `java -version`）→ 进名单 → 落盘。 +/// +/// 拒绝时**什么都不写**（名单不变、设置不变）——这是「非法路径不污染设置」那条守卫的落点。 +/// +/// # Errors +/// 校验不过（见 [`Refusal`]）或名单写盘失败时返回原因。 +pub fn add_manual(config: &Path, input: &str) -> Result<(String, RuntimeRow), Refusal> { + add_manual_with(config, input, &manual::probe_manual) +} + +/// 同 [`add_manual`]，但探测函数可注入（测试用：不依赖本机装没装 JDK）。 +/// +/// # Errors +/// 探测被拒或名单写盘失败时返回原因。 +pub fn add_manual_with( + config: &Path, + input: &str, + probe: &dyn Fn(&str) -> Result, +) -> Result<(String, RuntimeRow), Refusal> { + let runtime = probe(input.trim()).map_err(failure_refusal)?; + let binary = runtime.binary.display().to_string(); + let mut paths = manual::load_paths(&manual_file(config)); + let key = discover::path_key(&runtime.binary); + if paths.iter().any(|known| discover::path_key(known) == key) { + return Err(Refusal::AddDuplicate); + } + paths.push(runtime.binary.clone()); + manual::save_paths(&manual_file(config), &paths).map_err(|_| Refusal::AddWriteFailed)?; + Ok(( + binary.clone(), + RuntimeRow { + binary, + version: runtime.version.clone().unwrap_or_default(), + major: runtime.major, + vendor: runtime.vendor.clone(), + source: "manual", + }, + )) +} + +/// `core` 的拒绝原因 → 页面原因。 +fn failure_refusal(failure: manual::ManualFailure) -> Refusal { + match failure { + manual::ManualFailure::Empty => Refusal::AddEmpty, + manual::ManualFailure::TooLong => Refusal::AddTooLong, + manual::ManualFailure::Missing => Refusal::AddMissing, + manual::ManualFailure::NotJava => Refusal::AddNotJava, + manual::ManualFailure::NoVersion => Refusal::AddNoVersion, + } +} + +/// 设置文件路径（数据根解析不出来时没有）。 +#[must_use] +pub fn config_of(bridge: &unlucky_presenter::settings_bridge::SettingsBridge) -> Option { + bridge.path().map(Path::to_path_buf) +} diff --git a/crates/app-iced/src/pages/settings/java/tests.rs b/crates/app-iced/src/pages/settings/java/tests.rs new file mode 100644 index 0000000..e9fe3d2 --- /dev/null +++ b/crates/app-iced/src/pages/settings/java/tests.rs @@ -0,0 +1,305 @@ +//! 「Java」分组的真数据源断言（M175）：扫描 / 手动路径 / 内存 / JVM 参数 / 真命令行。 +//! +//! 每一条都**能变红**（报告的「变异证明」逐条给了改哪一行会红）。四条守卫： +//! +//! | 守卫 | 断言 | 改回什么会红 | +//! |---|---|---| +//! | 列表来自真扫盘 | [`the_runtime_list_comes_from_the_disk`] | 把行换成写死的字符串 / 不读候选表 | +//! | 非法路径不污染设置 | [`an_invalid_manual_path_is_refused_and_writes_nothing`] | 删掉 `manual::probe_manual` 的校验 | +//! | 内存越界被拒 | [`the_memory_bounds_are_enforced_before_writing`] | 删掉范围判断 / 允许非数字 | +//! | 内存真进命令行 | [`the_saved_memory_reaches_the_real_command_line`] | 把 `-Xmx` 的来源改回常量 | +//! +//! 前三条不依赖本机装没装 JDK（假的 `bin/java` 空文件就够：它扫得到、但答不出版本）， +//! 第四条（`tests/cmdline.rs`）走 core 的**真组装链**（`launch::args_table::assemble`）—— +//! 不是读配置回显。落盘 / 读回 / 版本门槛 / 截图种子也在那个文件里（同一族「真值」断言）。 + +#[path = "tests/cmdline.rs"] +mod cmdline; + +use std::path::{Path, PathBuf}; + +use super::state::{Refusal, RuntimeRow, State, MAX_JVM_ARGS, MAX_MEMORY_MB, MIN_MEMORY_MB}; +use super::store; + +/// 每个用例一个临时数据根（`/config/launcher.json` 的形状与真实数据根一致）。 +pub(super) fn root(tag: &str) -> PathBuf { + let dir = std::env::temp_dir().join(format!( + "ull-java-page-{tag}-{}-{}", + std::process::id(), + std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .map(|d| d.as_nanos()) + .unwrap_or(0) + )); + let _ = std::fs::remove_dir_all(&dir); + std::fs::create_dir_all(dir.join("config")).expect("config"); + dir +} + +pub(super) fn config(dir: &Path) -> PathBuf { + dir.join("config").join("launcher.json") +} + +/// 造一个「看起来像 JDK」的目录：`bin/java` 是空文件（扫得到、但 `-version` 答不出）。 +pub(super) fn fake_jdk(dir: &Path, name: &str) -> PathBuf { + let jdk = dir.join(name); + std::fs::create_dir_all(jdk.join("bin")).expect("bin"); + std::fs::write(jdk.join("bin").join(java_bin()), b"").expect("写 java"); + jdk +} + +pub(super) fn java_bin() -> &'static str { + if cfg!(windows) { + "java.exe" + } else { + "java" + } +} + +// --------------------------------------------------------------- 守卫①：列表来自真扫盘 + +/// 扫描列表必须来自**盘上真有的目录**：造两个 → 两项；删一个 → 一项。 +/// +/// 变异证明：把 `store::start` 里的候选表换成一个写死的两行常量，删目录之后仍是两项 ⇒ 红。 +#[test] +fn the_runtime_list_comes_from_the_disk() { + let dir = root("scan"); + let one = fake_jdk(&dir, "jdk-a"); + let two = fake_jdk(&dir, "jdk-b"); + + let found = + unlucky_core::game::java::staged::scan_roots(&[], &[one.clone(), two.clone()], false); + assert_eq!(found.len(), 2, "两个假 JDK 目录必须扫出两项：{found:?}"); + + std::fs::remove_dir_all(&one).expect("删 jdk-a"); + let after = unlucky_core::game::java::staged::scan_roots(&[], &[one, two], false); + assert_eq!(after.len(), 1, "删掉一个之后必须少一项：{after:?}"); + + std::fs::remove_dir_all(&dir).ok(); +} + +/// 扫描结论灌进页面状态之后，**行数与路径**都来自那次扫描（不是常量）。 +#[test] +fn applying_a_scan_report_replaces_every_row() { + let mut state = State::default(); + let report = store::ScanReport { + running: false, + done: 2, + total: 2, + finished: true, + cancelled: false, + runtimes: vec![ + RuntimeRow { + binary: "C:/jdk-a/bin/java.exe".to_string(), + version: String::new(), + major: None, + vendor: None, + source: "manual", + }, + RuntimeRow { + binary: "C:/jdk-b/bin/java.exe".to_string(), + version: String::new(), + major: Some(21), + vendor: Some("Temurin".to_string()), + source: "system", + }, + ], + }; + assert!(state.apply_scan(&report), "第一次灌结论必须报告「变了」"); + assert_eq!(state.runtimes.len(), 2); + assert!(state.scanned, "扫完之后「未检测到」与「还没扫」必须能分开"); + assert_eq!(state.runtimes[1].summary(), "Java 21 · Temurin"); +} + +// --------------------------------------------------------------- 守卫②：非法路径不污染设置 + +/// 非法路径被拒、**设置与名单一个字节都不写**。 +/// +/// 变异证明：删掉 `store::add_manual` 里的 `manual::probe_manual`（改成只看 `is_dir()`）， +/// 「不存在的路径」就会被加进名单 ⇒ 红。 +#[test] +fn an_invalid_manual_path_is_refused_and_writes_nothing() { + let dir = root("manual"); + let file = config(&dir); + + assert_eq!( + store::add_manual(&file, "").err(), + Some(Refusal::AddEmpty), + "空输入要被拒" + ); + assert_eq!( + store::add_manual(&file, "Z:/definitely/not/here").err(), + Some(Refusal::AddMissing), + "不存在的路径要被拒" + ); + let empty = dir.join("empty-jdk"); + std::fs::create_dir_all(&empty).expect("空目录"); + assert_eq!( + store::add_manual(&file, &empty.display().to_string()).err(), + Some(Refusal::AddNotJava), + "目录里没有 bin/java 要被拒" + ); + let broken = fake_jdk(&dir, "broken-jdk"); + assert_eq!( + store::add_manual(&file, &broken.display().to_string()).err(), + Some(Refusal::AddNoVersion), + "跑不出 java -version 要被拒" + ); + + assert!( + store::load_manual(&file).is_empty(), + "被拒的路径不许进名单：{:?}", + store::load_manual(&file) + ); + let snapshot = store::load(&file); + assert!( + snapshot.selected.is_empty(), + "被拒的路径不许污染 java.selected_path：{snapshot:?}" + ); + std::fs::remove_dir_all(&dir).ok(); +} + +// --------------------------------------------------------------- 守卫③：内存越界被拒 + +/// 内存必须落在 schema 登记的区间里，非数字也要拒，而且**不写盘**。 +/// +/// 变异证明：删掉 `State::validate` 里的范围判断（只留 `parse`），128 与 999999 会落盘 ⇒ 红； +/// 把 `parse::` 换成 `unwrap_or(2048)`，`"abc"` 不再报错 ⇒ 红。 +#[test] +fn the_memory_bounds_are_enforced_before_writing() { + let mut state = State { + storage: true, + ..State::default() + }; + + state.memory = (MIN_MEMORY_MB - 1).to_string(); + assert_eq!( + state.validate().err(), + Some(Refusal::MemoryRange), + "低于下限" + ); + state.memory = (MAX_MEMORY_MB + 1).to_string(); + assert_eq!( + state.validate().err(), + Some(Refusal::MemoryRange), + "高于上限" + ); + state.memory = "abc".to_string(); + assert_eq!( + state.validate().err(), + Some(Refusal::MemoryNotNumber), + "非数字" + ); + state.memory = " ".to_string(); + assert_eq!(state.validate().err(), Some(Refusal::MemoryEmpty), "空"); + state.memory = "4096".to_string(); + assert!(state.validate().is_ok()); + state.jvm = "-XX:+UseG1GC".to_string(); + assert!(state.validate().is_ok()); + state.jvm = "-Xss\"512k".to_string(); + assert_eq!( + state.validate().err(), + Some(Refusal::JvmQuotes), + "引号没配对" + ); + + // 真的不写盘：一次越界保存之后，文件里还是出厂默认值。 + let dir = root("memory"); + let file = config(&dir); + let state = State { + storage: true, + memory: "128".to_string(), + ..State::default() + }; + assert!(store::save(&file, &state).is_err(), "越界必须写不进去"); + assert_eq!( + store::load(&file).memory_mb, + super::state::DEFAULT_MEMORY_MB, + "被拒的保存不许落盘" + ); + std::fs::remove_dir_all(&dir).ok(); +} + +/// 两个数字常量必须与 schema 登记的一致（否则 UI 放行的值会被 schema 拒）。 +/// +/// 变异证明：把 `MIN_MEMORY_MB` 改成 256（core 的 `launch_overrides` 那一档），这条立刻红。 +#[test] +fn the_memory_bounds_mirror_the_schema() { + use unlucky_core::setting::keys::launcher_schema; + use unlucky_core::setting::spec::ValueKind; + let schema = launcher_schema(); + let kind = schema + .spec("java.default_memory_mb") + .map(|spec| &spec.kind) + .expect("schema 里必须有 java.default_memory_mb"); + let ValueKind::Int { min, max } = kind else { + panic!("java.default_memory_mb 应该是 Int：{kind:?}"); + }; + assert_eq!(*min, i64::from(MIN_MEMORY_MB)); + assert_eq!(*max, i64::from(MAX_MEMORY_MB)); +} + +// --------------------------------------------------------------- 守卫⑤：JVM 参数超长被拒（M199） + +/// 粘了一整段参数（>1024 字符）时界面给的是**具体**原因，而不是撞 schema 之后的「写不进去」； +/// 而且一个字节都不写盘。 +/// +/// 变异证明：删掉 `State::validate` 里那条 `MAX_JVM_ARGS` 判据 ⇒ 长度打回 schema 那一档 +/// （`store::save` 返回 `WriteError::Schema`，用户只看到通用失败文案、具体原因只在 stderr）， +/// 本用例红。这也是 r3 复审 P3-4 的现场。 +#[test] +fn an_overlong_jvm_argument_line_is_refused_before_writing() { + let dir = root("jvm-long"); + let file = config(&dir); + + // 恰好等于上限：放行（判据是「超过」，不是「达到」）。 + let mut state = State { + storage: true, + memory: super::state::DEFAULT_MEMORY_MB.to_string(), + jvm: "x".repeat(MAX_JVM_ARGS), + ..State::default() + }; + assert!(state.validate().is_ok(), "恰好 {MAX_JVM_ARGS} 字符应当放行"); + + state.jvm = "x".repeat(MAX_JVM_ARGS + 1); + assert_eq!(state.validate().err(), Some(Refusal::JvmTooLong)); + assert_eq!( + Refusal::JvmTooLong.label(), + unlucky_i18n::Key::SettingsJavaReasonJvmTooLong, + "拒绝原因必须有自己的一句文案（不许退回通用的「写不进去」）" + ); + + let error = store::save(&file, &state).expect_err("超长参数应被本地校验拒掉"); + assert_eq!(error, store::WriteError::Refused(Refusal::JvmTooLong)); + assert!(!file.exists(), "被本地校验拒掉的保存不许碰磁盘"); + std::fs::remove_dir_all(&dir).ok(); +} + +/// `MAX_JVM_ARGS` 必须等于 schema 登记的 `java.extra_args` 上限：本地放行的值不许被 schema 拒 +/// （否则用户又只看到那句通用失败文案）。 +/// +/// 变异证明：把 `MAX_JVM_ARGS` 改成 2048 ⇒ 本用例红。 +#[test] +fn the_jvm_length_mirrors_the_schema() { + use unlucky_core::setting::keys::launcher_schema; + use unlucky_core::setting::spec::ValueKind; + let schema = launcher_schema(); + let kind = schema + .spec("java.extra_args") + .map(|spec| &spec.kind) + .expect("schema 里必须有 java.extra_args"); + let ValueKind::Text { max_len } = kind else { + panic!("java.extra_args 应该是 Text：{kind:?}"); + }; + assert_eq!(*max_len, MAX_JVM_ARGS); +} + +#[path = "tests/runtime.rs"] +mod runtime; + +#[path = "tests/prefs.rs"] +mod prefs; + +// M206：「当前默认」那颗标记的可读性（对比度 / 同族 / 禁用语义）断言。 +#[path = "tests/marker.rs"] +mod marker; diff --git a/crates/app-iced/src/pages/settings/java/tests/cmdline.rs b/crates/app-iced/src/pages/settings/java/tests/cmdline.rs new file mode 100644 index 0000000..da6225c --- /dev/null +++ b/crates/app-iced/src/pages/settings/java/tests/cmdline.rs @@ -0,0 +1,342 @@ +//! `tests.rs` 的后半：真命令行 / 落盘读回 / 版本门槛 / 截图种子。 +//! +//! 拆出来的理由：`tests.rs` 加上守卫之后 434 行，越过 400 行硬线；这一半是「真值走完整条生产链」 +//! 的一族（`launcher.json` → 组装链 / 重启后读回），与前半的「输入校验」不是一件事。 +//! 公共的临时目录与假 JDK 构造在父模块（`super::root` / `super::fake_jdk`）。 + +use std::path::Path; + +use super::super::state::{Fit, Layer, Notice, Requirement, RuntimeRow, State}; +use super::super::store; +use super::{config, fake_jdk, root}; + +// --------------------------------------------------------------- 守卫④：内存真进命令行 + +/// 写进 `java.default_memory_mb` 的值必须出现在**真组装出来的 JVM 参数**里。 +/// +/// 走的是生产代码那条链：`launcher.json` → `GlobalLaunchDefaults` → `launch_overrides::resolve` +/// → `launch::overrides::apply` → `launch::args_table::assemble`（`ull launch --dry-run` 用的是同一条）。 +/// 不是读配置回显：断言的是 `-Xmx<新值>m` 这个 argv 元素。 +/// +/// 变异证明：把 `store::save` 里写 `java.default_memory_mb` 的那一行删掉（或写死 2048）， +/// 这条立刻红（argv 里还是 `-Xmx2048m`）。 +#[test] +fn the_saved_memory_reaches_the_real_command_line() { + let dir = root("cmdline"); + let file = config(&dir); + let state = State { + storage: true, + memory: "6144".to_string(), + jvm: "-Dfile.encoding=UTF-8".to_string(), + ..State::default() + }; + assert!(state.validate().is_ok()); + let saved = store::save(&file, &state).expect("保存应成功"); + assert_eq!(saved.memory_mb, 6144, "落盘后读回的值"); + assert_eq!(saved.jvm, "-Dfile.encoding=UTF-8"); + + let args = real_argv(&file); + assert!( + args.iter().any(|arg| arg == "-Xmx6144m"), + "内存字段必须长成 -Xmx6144m：{args:?}" + ); + assert!( + args.iter().any(|arg| arg == "-Dfile.encoding=UTF-8"), + "java.extra_args 必须进命令行：{args:?}" + ); + assert!( + !args.iter().any(|arg| arg == "-Xmx2048m"), + "出厂默认值不许还在里面：{args:?}" + ); + std::fs::remove_dir_all(&dir).ok(); +} + +/// 用生产链组装一次命令行（`launch.json` 之外什么都不读）。 +fn real_argv(config: &Path) -> Vec { + use std::path::PathBuf; + + use unlucky_core::game::launch_overrides::{resolve, GlobalLaunchDefaults}; + use unlucky_core::launch::args_table::assemble; + use unlucky_core::launch::overrides; + use unlucky_core::launch::platform::{OsFamily, PlatformCtx}; + use unlucky_core::launch::request::{ + InstanceInfo, JavaSelection, LaunchDirs, ManifestArgs, MemoryOptions, + }; + use unlucky_core::launch::request::{ + LaunchRequest, LauncherInfo, Log4jOptions, OptimizationOptions, + }; + + let snapshot = store::load(config); + let resolved = resolve( + None, + &GlobalLaunchDefaults { + jvm_args: Some(snapshot.jvm.clone()), + memory_mb: Some(snapshot.memory_mb), + ..GlobalLaunchDefaults::default() + }, + ); + let mut request = LaunchRequest { + instance: InstanceInfo { + id: "inst-1".to_string(), + name: "1.20.1".to_string(), + version: unlucky_core::launch::game_version::GameVersion::parse("1.20.1"), + version_type: "release".to_string(), + }, + launcher: LauncherInfo { + name: "UnluckyLauncher".to_string(), + version: "0.2.3".to_string(), + }, + java: JavaSelection::new("C:/java/bin/java.exe", 21, 64), + memory: MemoryOptions { + min_mb: None, + max_mb: None, + }, + manifest: ManifestArgs { + main_class: Some("net.minecraft.client.main.Main".to_string()), + ..ManifestArgs::default() + }, + dirs: LaunchDirs { + game_dir: PathBuf::from("C:/mc"), + primary_jar: PathBuf::from("C:/mc/versions/x/x.jar"), + ..LaunchDirs::default() + }, + classpath: vec![PathBuf::from("C:/mc/libraries/a.jar")], + log4j: Log4jOptions { + enabled: false, + ..Log4jOptions::default() + }, + optimization: OptimizationOptions { + enabled: false, + physical_memory_mb: None, + }, + language: "zh-CN".to_string(), + ..LaunchRequest::default() + }; + overrides::apply(&mut request, &resolved); + assemble(&request, &PlatformCtx::new(OsFamily::Windows, "x86_64")) + .expect("组装应成功") + .args +} + +// --------------------------------------------------------------- 落盘 / 读回 / 门槛 + +/// 三键都能落盘、能在「重启后」读回来（新的 `State` + `hydrate` 就是重启的等价物）。 +#[test] +fn the_settings_survive_a_restart() { + let dir = root("restart"); + let file = config(&dir); + let state = State { + storage: true, + memory: "8192".to_string(), + jvm: "-XX:+UseG1GC".to_string(), + ..State::default() + }; + store::save(&file, &state).expect("保存"); + let selected = store::set_selected(&file, "C:/jdk-17/bin/java.exe").expect("选默认"); + + // 「重启」：全新的 State 从盘上灌一次。 + let mut reborn = State::default(); + assert!(reborn.hydrate(store::load(&file))); + assert_eq!(reborn.memory, "8192"); + assert_eq!(reborn.saved_memory, 8192); + assert_eq!(reborn.jvm, "-XX:+UseG1GC"); + assert_eq!(reborn.selected, "C:/jdk-17/bin/java.exe"); + assert_eq!(selected.selected, "C:/jdk-17/bin/java.exe"); + + // 手动名单也在（与设置同一个 config/ 目录下的纯文本）。 + let jdk = fake_jdk(&dir, "keep-me"); + std::fs::write(store::manual_file(&file), format!("{}\n", jdk.display())).expect("写名单"); + assert_eq!(store::load_manual(&file).len(), 1); + std::fs::remove_dir_all(&dir).ok(); +} + +/// 「为什么选它」那一行：版本门槛来自实例，选中的运行时够不够要能算出来。 +#[test] +fn the_requirement_explains_why_a_runtime_fits_or_not() { + let mut state = State { + scanned: true, + runtimes: vec![ + RuntimeRow { + binary: "C:/jdk-8/bin/java.exe".to_string(), + version: String::new(), + major: Some(8), + vendor: None, + source: "system", + }, + RuntimeRow { + binary: "C:/jdk-21/bin/java.exe".to_string(), + version: String::new(), + major: Some(21), + vendor: None, + source: "system", + }, + ], + selected: "C:/jdk-8/bin/java.exe".to_string(), + ..State::default() + }; + assert_eq!(state.fit(Some(8)), None, "没有要求时不下结论"); + + state.context.required = Some(Requirement { + instance: "生存服".to_string(), + version: "1.20.1".to_string(), + minimum: 17, + maximum: None, + }); + assert_eq!( + state.fit(Some(8)), + Some(Fit::TooOld { + required: 17, + actual: 8 + }), + "太低要说「需要 17」" + ); + assert_eq!(state.fit(Some(21)), Some(Fit::Ok)); + assert_eq!( + state.default_row().map(|row| row.binary.clone()), + Some("C:/jdk-8/bin/java.exe".to_string()), + "默认那一行按 selected 找出来" + ); + + state.context.layer = Some(Layer::Instance { + instance: "生存服".to_string(), + mb: 8192, + }); + assert!(matches!(state.layer(), Layer::Instance { mb: 8192, .. })); +} + +/// 截图种子：三档都得给得出来（`--screenshot` 的取证开关）。 +#[test] +fn the_screenshot_seeds_cover_the_three_states() { + let empty = State::screenshot_seed("empty").expect("empty 档"); + assert!(empty.runtimes.is_empty() && empty.scanned); + + let two = State::screenshot_seed("two").expect("two 档"); + assert_eq!(two.runtimes.len(), 2); + assert!(two.default_row().is_some(), "两个 JDK 里要选中其一"); + + let editing = State::screenshot_seed("editing").expect("editing 档"); + assert!(editing.dirty, "编辑态要有未保存改动"); + assert!(matches!(editing.notice, Some(Notice::Refused(_)))); + assert!(State::screenshot_seed("nonsense").is_none()); +} + +/// M204 r1：扫描的三档（扫描中 / 还没扫描过 / 正在取消）——视觉复审 p2-1 要的正是这三格。 +/// +/// 每档的判据都落在**界面真的会读的那两个字段**上：`State.scanning`（状态行画什么）与 +/// `State.scan.report().running`（心跳下一拍会不会把 `scanning` 推开）。 +/// +/// 变异证明：把 `"scanning"` 档里的 `scan.seed_report(...)` 换成不调 ⇒ `scanning` 在心跳第一拍 +/// 就被推回 `None`（`apply_scan` 用槽里的快照重算）⇒ 第二段红。这也正是这两档必须写槽、 +/// 不能只改 `State` 的理由。 +#[test] +fn the_scan_seeds_cover_the_running_states() { + let scanning = State::screenshot_seed("scanning").expect("scanning 档"); + assert_eq!( + scanning.scanning, + Some(super::super::state::Progress { done: 3, total: 7 }), + "状态行要画「正在扫描… 3/7」" + ); + assert!( + scanning.scan.report().running, + "槽里的快照也得是「在扫」，否则下一拍就把 scanning 推开" + ); + assert!(!scanning.scanned, "还没扫完过"); + assert!(!scanning.cancelled, "没按过取消 ⇒「取消」这颗按钮可点"); + assert!(scanning.runtimes.is_empty(), "扫描中列表还没有结论"); + + let cancelling = State::screenshot_seed("cancelling").expect("cancelling 档"); + assert!(cancelling.cancelled && cancelling.scan.report().running); + assert!( + cancelling.scanning.is_some(), + "线程还没退出 ⇒ 状态行仍是活动态（画的是「正在取消…」）" + ); + + let unscanned = State::screenshot_seed("unscanned").expect("unscanned 档"); + assert!(unscanned.scanning.is_none() && !unscanned.scanned); + assert!(!unscanned.scan.report().running, "这一档没有扫描在跑"); +} + +/// M197 的三档：版本选择列表 / 下载中 / 下载失败——出图靠它们，所以每档都要有**可断言的特征**。 +/// +/// 变异证明：把 `seed::build` 里 `"downloading"` 那一档的 `seed_report` 换成 `Report::default()` +/// ⇒ 第 2 段红（作业没了，图上就只剩目录）。 +#[test] +fn the_download_seeds_cover_the_three_states() { + use super::super::downloads::Phase; + + let list = State::screenshot_seed("download").expect("download 档"); + assert!( + list.prefs.saved_auto_install && !list.prefs.saved_priority.is_empty(), + "目录那一档要把三键摆成真值（自动准备开着 + 自己排过顺序）" + ); + assert!(list.downloads.report().job.is_none(), "选择列表不是下载中"); + + let running = State::screenshot_seed("downloading").expect("downloading 档"); + let job = running.downloads.report().job.expect("下载中要有作业"); + assert_eq!(job.phase, Phase::Downloading); + assert_eq!(job.percent(), Some(45), "96.4 MiB / 210.7 MiB ≈ 45%"); + assert_eq!(job.source.as_deref(), Some("tuna"), "要说得出当前源"); + assert!( + job.last.is_some(), + "退避那一行也要有（图上要看见「失败 / 重试」）" + ); + + let failed = State::screenshot_seed("download-failed").expect("download-failed 档"); + let report = failed.downloads.report(); + let failure = report.failure.expect("失败档要有失败"); + assert_eq!(failure.major, 21); + assert_eq!(failure.source.as_deref(), Some("github")); + assert_eq!( + report.tries.len(), + 2, + "失败态要列出「试过哪些源」：tuna + github" + ); +} + +/// 自动扫描的判据：首屏扫一次，扫过就不重扫，截图通道永不扫。 +/// +/// 变异证明：把 `auto_scan_due` 改成恒 `true`，第二、三档立刻红（每次心跳都发起扫描）； +/// 改成恒 `false`，第一档红（用户实测的头一条抱怨就是「设置页从来自动检测」）。 +#[test] +fn the_auto_scan_predicate_runs_once_and_never_in_screenshots() { + let fresh = store::ScanReport::default(); + assert!( + store::auto_scan_due(&fresh, false), + "首屏（没扫过、没在扫）应该自动扫一次" + ); + assert!( + !store::auto_scan_due(&fresh, true), + "截图通道不许读本机装了什么" + ); + + let running = store::ScanReport { + running: true, + ..store::ScanReport::default() + }; + assert!(!store::auto_scan_due(&running, false), "正在扫就不重入"); + + let finished = store::ScanReport { + finished: true, + ..store::ScanReport::default() + }; + assert!( + !store::auto_scan_due(&finished, false), + "扫过一次就不再自动扫（手动「立即扫描」仍可再扫）" + ); + + // 被取消过的扫描：`finished` 仍是 false（结论作废），但**不许**自动重来——否则 + // `launcher.json` 每变一次，心跳就会把用户刚做的取消无声撤销（r2 复审 P2-2）。 + let cancelled = store::ScanReport { + cancelled: true, + ..store::ScanReport::default() + }; + assert!( + !store::auto_scan_due(&cancelled, false), + "取消过一次之后，本进程不再自动扫描" + ); + // 手动「立即扫描」走的是 `ScanSlot::start`，不看这个判据 ⇒ 取消不是永久锁死。 + assert!( + store::auto_scan_due(&store::ScanReport::default(), false), + "全新进程（没扫过、没取消）仍然自动扫一次" + ); +} diff --git a/crates/app-iced/src/pages/settings/java/tests/marker.rs b/crates/app-iced/src/pages/settings/java/tests/marker.rs new file mode 100644 index 0000000..0902830 --- /dev/null +++ b/crates/app-iced/src/pages/settings/java/tests/marker.rs @@ -0,0 +1,219 @@ +//! 「当前默认」那颗标记的**可读性**断言（M206）。 +//! +//! 起因是 M204 的视觉复测量出来的两个数：Java 页用 `Chip::badge` 表示「哪个 JDK 是默认」， +//! 而 `badge` 走的是**禁用**配色（`OnSurface`@38% 叠 surface）⇒ 字/底只有 **1.84:1（浅）/ +//! 2.28:1（深）**，成了整页最不可读的一段；而同一张设置页里相邻的「下载」组表达「选中」用的是 +//! `SecondaryContainer` + `OnSecondaryContainer`（**7.21:1**）。同一个「选中」在两页是两种语汇。 +//! +//! 这里钉三件事（每条都写过「抓得住 / 抓不住」）： +//! +//! | 断言 | 抓得住 | 抓不住 | +//! |---|---|---| +//! | [`the_current_default_marker_clears_wcag_aa`] | 当前项标记的字/底对比度掉到 4.5:1 以下（例如 `view::action_chip` 改回 `Chip::badge`、或 `Chip::current` 的 `marker` 位丢了） | 字体粗细 / 字号是否够大（`LabelLarge` 是正文口径，本来就得 4.5）；真截图上的抗锯齿边缘 | +//! | [`the_current_default_marker_speaks_the_download_groups_language`] | 两页的「选中」被拆成两套配色（谁再另起一套立刻红） | 「两页在同一张图上看起来协调」这种整体观感（那要视觉 reviewer 判） | +//! | [`the_disabled_chip_still_looks_disabled`] | 有人为了让当前项好看，顺手把 `badge` / `.disabled()` 也接到选中配色上（「忙/不可用」于是看起来可点） | 禁用态够不够灰的美学判断——只钉到令牌：字 38%、容器 12% | +//! +//! **它们都不碰像素**：颜色是「角色 → 令牌 → 对比度」这条链上的值断言，真图另存 +//! `DevDocs/artifacts/m206/`（D30 §2.1 三件套）。 + +use iced::Color; + +use unlucky_design::color::{Color as TokenColor, Role, SchemeFlavor}; +use unlucky_design::palette::wcag::AA_TEXT; +use unlucky_design::typography::Platform; +use unlucky_i18n::Lang; + +use crate::app::components::interaction; +use crate::app::components::selection::paint::ChipPaint; +use crate::app::components::selection::Chip; +use crate::theme::{Families, Ui}; + +use super::super::seed; +use super::super::state::State; +use super::super::view::action_chip; + +const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", +}; + +const FLAVORS: [SchemeFlavor; 2] = [SchemeFlavor::Light, SchemeFlavor::Dark]; + +fn ui(flavor: SchemeFlavor) -> Ui { + Ui::with_platform(flavor, Platform::Windows, FAMILIES) +} + +/// iced 的 sRGB 分量 → 令牌色（[`crate::theme::to_iced`] 的逆；`to_iced` 是从 8 bit 来的， +/// 所以来回一趟无误差）。 +fn token(color: Color) -> TokenColor { + let q = |v: f32| (v.clamp(0.0, 1.0) * 255.0).round() as u8; + TokenColor::rgba(q(color.r), q(color.g), q(color.b), q(color.a)) +} + +/// 一颗 chip 的「字色 vs 底色」。容器为空（透明）时按 surface 算——chip 的透明态本来就压在 +/// 卡片底上，这条口径与 `wcag::check` 的 `(OnSurfaceVariant, Surface)` 一致。 +fn ink_ratio(paint: &ChipPaint, ui: &Ui) -> f32 { + let background = paint.frame.fill.unwrap_or_else(|| ui.color(Role::Surface)); + token(paint.label).contrast_ratio(token(background)) +} + +/// 截图种子里那两行 JDK（`ULL_JAVA_STATE=two` 用的同一份），其中**第二行是当前默认**。 +fn seeded() -> State { + seed::build("two").expect("种子 two 必须存在") +} + +// ------------------------------------------------- ① 对比度：当前项标记必须过 AA 正文 + +/// 「当前默认」那颗标记的字色与底色 ≥ **4.5:1**（WCAG 2.x AA 正文口径），浅深两档都要过。 +/// +/// 改前实测（M204，`Chip::badge` 的禁用配色）：**1.84:1 浅 / 2.28:1 深**；改后（本断言钉的）： +/// **7.21:1 浅 / 7.21:1 深**——与下载组的选中 chip 同一个数，因为就是同一套角色。 +/// +/// 变异证明（只改实现侧）：把 `view::action_chip` 的 `Chip::current` 换回 `Chip::badge`， +/// 这条立刻红（比值掉回 1.84 / 2.28）；把 `Chip::current` 里的 `marker: true` 改成 `false` +/// 也一样红（它会退回「无消息 ⇒ 禁用」那条路）。 +#[test] +fn the_current_default_marker_clears_wcag_aa() { + let catalog = Lang::ZhCn.catalog(); + let state = seeded(); + + for flavor in FLAVORS { + let ui = ui(flavor); + // 种子里选中的是第二行（`C:\Program Files\Microsoft\jdk-21.0.4`）。 + let marker_row = state + .runtimes + .iter() + .find(|runtime| super::super::state::same_path(&runtime.binary, &state.selected)) + .expect("种子里必须有一行是当前默认"); + let paint = action_chip(catalog, &state, marker_row).paint(&ui); + + // 先量数（这条是任务书点名要的那条）：谁把配色改回禁用灰，红在这里。 + let ratio = ink_ratio(&paint, &ui); + assert!( + ratio >= AA_TEXT, + "{flavor:?}：「当前默认」的字/底只有 {ratio:.2}:1，低于 AA 正文 {AA_TEXT}:1 —— \ + 这正是 M206 要修的那段（改前 1.84 浅 / 2.28 深）" + ); + + // 再钉角色名：比值恰好过线也可能是碰巧换了个色，这里把「用的是哪两个角色」写死。 + assert_eq!( + paint.frame.fill, + Some(ui.color(Role::SecondaryContainer)), + "{flavor:?}：当前项标记的容器必须是 SecondaryContainer（与下载组选中 chip 同族），\ + 不是禁用态的 12% 灰" + ); + assert_eq!( + paint.label, + ui.color(Role::OnSecondaryContainer), + "{flavor:?}：当前项标记的字色必须是 OnSecondaryContainer，不是 OnSurface@38%" + ); + } +} + +// ------------------------------------------------- ② 同族：两页表达「选中」只用一套颜色 + +/// Java 的「当前默认」与下载组的选中 chip **必须逐字段同色**。 +/// +/// 下载组那一侧（M201 已验收）是 `Chip::filter(option, selected=true, msg)`；这里照原样构造一颗 +/// ——**不是**照着角色名手抄一遍，所以谁把其中一页换套配色，这条就红。 +/// +/// 变异证明：把 `Chip::current` 的容器改成 `PrimaryContainer`（或任何另一个角色），红。 +#[test] +fn the_current_default_marker_speaks_the_download_groups_language() { + let catalog = Lang::ZhCn.catalog(); + let state = seeded(); + + for flavor in FLAVORS { + let ui = ui(flavor); + let marker_row = state + .runtimes + .iter() + .find(|runtime| super::super::state::same_path(&runtime.binary, &state.selected)) + .expect("种子里必须有一行是当前默认"); + let marker = action_chip(catalog, &state, marker_row).paint(&ui); + + // 下载组的分段单选：选中的那颗就是 `filter(.., true, ..)`。 + let download_selected = Chip::<()>::filter("8", true, ()); + assert_eq!( + marker, + download_selected.paint(&ui), + "{flavor:?}：两页的「选中」必须是同一套视觉语汇（M206）" + ); + + // 反面：另一行（非默认）是可点的「设为默认」——未选中 filter，且**不是**禁用灰。 + let other = state + .runtimes + .iter() + .find(|runtime| !super::super::state::same_path(&runtime.binary, &state.selected)) + .expect("种子里必须有一行不是默认"); + let actionable = action_chip(catalog, &state, other).paint(&ui); + assert_eq!( + actionable.label, + ui.color(Role::OnSurfaceVariant), + "{flavor:?}：「设为默认」是可点的未选中 filter（OnSurfaceVariant），不是禁用" + ); + assert_ne!( + actionable.frame.fill, marker.frame.fill, + "{flavor:?}：可点与当前项必须分得开（一个透明描边 / 一个填充）" + ); + } +} + +// ------------------------------------------------- ③ 反向：禁用态仍然要看起来禁用 + +/// 修当前项**不许**顺手把禁用语义改亮：`Chip::badge` / `.disabled()` 仍走 +/// 「字 `OnSurface`@38% + 容器 `OnSurface`@12%」，且与当前项标记**肉眼可分的两档**。 +/// +/// 变异证明：把 `Chip::paint` 里「没消息 = 禁用」那条改成走选中配色（或把 `badge` 改成 +/// `marker: true`），这条红——那会让「下载进行中，安装按钮灰掉」看起来像可点。 +#[test] +fn the_disabled_chip_still_looks_disabled() { + let ui_light = ui(SchemeFlavor::Light); + let ui_dark = ui(SchemeFlavor::Dark); + + for ui in [&ui_light, &ui_dark] { + let flavor = ui.flavor(); + // 下载组里「忙 ⇒ 灰掉」的那颗与 Java 的「默认」标记在语义上相反，必须画得不一样。 + let disabled = Chip::<()>::filter("安装", true, ()).disabled().paint(ui); + let marker = Chip::<()>::current("默认").paint(ui); + + let ink38 = + interaction::disabled_content_over_role(ui, Role::Surface, Role::OnSurface, false); + let container12 = interaction::disabled_colors(ui, Role::Surface).0; + + assert_eq!( + disabled.label, ink38, + "{flavor:?}：禁用字仍是 OnSurface@38%" + ); + assert_eq!( + disabled.frame.fill, + Some(container12), + "{flavor:?}：禁用容器仍是 OnSurface@12%（选中禁用的填充走 38%，见 selection::tests）" + ); + assert_ne!( + disabled.label, marker.label, + "{flavor:?}：禁用与当前项的文字色不许相同" + ); + assert_ne!( + disabled.frame.fill, marker.frame.fill, + "{flavor:?}：禁用与当前项的容器色不许相同" + ); + + // 禁用档**不**承诺 4.5:1（它是「用不了」的语汇，官方 α 就是 38%）：这条只记数值， + // 不当门槛——否则将来有人真去调亮禁用态时会被一条假门禁拦住。 + let ratio = ink_ratio(&disabled, ui); + assert!( + ratio < AA_TEXT, + "{flavor:?}：禁用档意外地过 AA 了（{ratio:.2}:1）——若是有意调亮，请同步改这条注释与 \ + `interaction::disabled` 的令牌口径，别让「禁用」和「当前项」两档混成一个" + ); + } + + // `Chip::badge` 仍是禁用档（它就是「没消息 ⇒ 禁用」那条路的产物）。 + let badge = Chip::<()>::badge("LTS").paint(&ui_light); + let disabled = Chip::<()>::filter("LTS", true, ()) + .disabled() + .paint(&ui_light); + assert_eq!(badge, disabled, "`Chip::badge` 与 `.disabled()` 必须同色"); +} diff --git a/crates/app-iced/src/pages/settings/java/tests/prefs.rs b/crates/app-iced/src/pages/settings/java/tests/prefs.rs new file mode 100644 index 0000000..e825376 --- /dev/null +++ b/crates/app-iced/src/pages/settings/java/tests/prefs.rs @@ -0,0 +1,140 @@ +//! 三个设置键的真读写（M197）：落盘 / 冷读回 / 生效值与来源层。 +//! +//! 每一条都能变红（报告的「变异证明」逐条给了改哪一行会红）： +//! +//! | 守卫 | 断言 | 改回什么会红 | +//! |---|---|---| +//! | 三键真落盘 | [`the_three_keys_are_written_and_read_back`] | 删掉 `prefs_store::save` 里任一 `store.set(...)` | +//! | 回读即真值 | 同上（`adopt` 之后草稿 = 磁盘值） | 让 `save` 返回草稿而不是 `load(config)` | +//! | 落点层级 | [`an_empty_install_root_follows_the_data_mode`] | 让 `effective` 忽略 `java.installRoot` | +//! | 顺序层级 | [`an_empty_priority_follows_the_region`] | 让 `order_layer` 恒为 `Region` | +//! | 超长路径不写盘 | [`an_overlong_install_root_is_refused_before_writing`] | 删掉 `Prefs::validate` 的长度判据 | + +use std::path::Path; + +use unlucky_core::setting::keys::launcher_schema; +use unlucky_core::setting::store::SettingStore; + +use super::super::prefs::{OrderLayer, Prefs, RootLayer, MAX_INSTALL_ROOT}; +use super::super::prefs_store; +use super::super::state::Refusal; +use super::super::store::WriteError; +use super::{config, root}; + +/// 把 `core.data_mode` 显式写成某一档（测试不依赖这台机器的出厂默认）。 +fn write_data_mode(file: &Path, mode: &str) { + let mut store = SettingStore::load(file, launcher_schema()); + store + .set("core.data_mode", mode.to_string().into()) + .expect("schema 认识 core.data_mode"); + store.save().expect("写盘"); +} + +/// 三键真写进 `launcher.json`，再从盘上冷读一次（= 重启后）仍一致。 +/// +/// 变异证明：删掉 `prefs_store::save` 里 `store.set("java.auto_install", …)` 那一行 ⇒ 本用例红 +/// （`snapshot.auto_install` 回到 schema 默认 `true`）；把 `Ok(load(config))` 改成 `Ok(*prefs)` +/// 之类「回显草稿」⇒ 前后空格那条断言红。 +#[test] +fn the_three_keys_are_written_and_read_back() { + let dir = root("prefs-save"); + let file = config(&dir); + + // 前后带空格：落盘值会被 trim，回读的草稿必须显示**磁盘上那份**。 + let mut prefs = Prefs { + install_root: " D:/JDKs ".to_string(), + auto_install: false, + priority: vec!["zulu", "temurin"], + ..Prefs::default() + }; + assert!(prefs.dirty(), "改过三键就该是脏的"); + + let snapshot = prefs_store::save(&file, &prefs).expect("三键应能落盘"); + assert_eq!(snapshot.install_root, "D:/JDKs", "落盘值已 trim"); + assert!(!snapshot.auto_install); + assert_eq!(snapshot.priority, vec!["zulu", "temurin"]); + + prefs.adopt(snapshot.clone()); + assert_eq!(prefs.install_root, "D:/JDKs", "回读后的草稿 = 磁盘值"); + assert!(!prefs.dirty(), "回读之后不再脏"); + + // 冷读（另一个 store 实例，模拟重启）。 + let again = prefs_store::load(&file); + assert_eq!(again, snapshot, "从盘上读回来的与写进去的一致"); +} + +/// `java.installRoot` 留空 ⇒ 生效落点来自 `core.data_mode`；填了 ⇒ 来自设置键。 +/// +/// 变异证明：把 `prefs_store::effective` 里 `override_root` 那段删掉（当作永远没设）⇒ 后半段红。 +#[test] +fn an_empty_install_root_follows_the_data_mode() { + let dir = root("prefs-root"); + let file = config(&dir); + write_data_mode(&file, "portable"); + + let prefs = Prefs::default(); + let effective = prefs_store::effective(&file, &prefs); + assert_eq!(effective.root_layer, RootLayer::DataMode); + assert_eq!(effective.root_mode, "portable"); + assert!( + effective.root.ends_with("java-managed"), + "portable 落点是数据根里的 java-managed：{}", + effective.root + ); + assert!( + effective.root.starts_with(&dir.display().to_string()), + "portable 落点必须在这个数据根里：{}", + effective.root + ); + + let custom = Prefs { + install_root: "D:/JDKs".to_string(), + saved_install_root: "D:/JDKs".to_string(), + ..Prefs::default() + }; + let effective = prefs_store::effective(&file, &custom); + assert_eq!(effective.root_layer, RootLayer::Setting); + assert_eq!(effective.root_mode, "custom"); + assert_eq!(effective.root, "D:/JDKs", "设了就按它来，不再拼数据根"); +} + +/// `java.vendorPriority` 留空 ⇒ 地区默认序；排过 ⇒ 顺序与来源层都变。 +/// +/// 变异证明：把 `order_layer` 的判据改成恒 `Region` ⇒ 后半段红。 +#[test] +fn an_empty_priority_follows_the_region() { + let dir = root("prefs-order"); + let file = config(&dir); + + let prefs = Prefs::default(); + let effective = prefs_store::effective(&file, &prefs); + assert_eq!(effective.order_layer, OrderLayer::Region); + assert_eq!(effective.order.len(), 4, "四家都要在链上"); + + let sorted = Prefs { + priority: vec!["zulu"], + saved_priority: vec!["zulu"], + ..Prefs::default() + }; + let effective = prefs_store::effective(&file, &sorted); + assert_eq!(effective.order_layer, OrderLayer::Setting); + assert_eq!(effective.order[0], "Azul Zulu", "排过的在第一"); + assert_eq!(effective.order.len(), 4, "补集追加，其余仍在链上"); +} + +/// 超长路径在**写盘前**被拒：文件都不该被创建。 +/// +/// 变异证明：删掉 `Prefs::validate` 的长度判据 ⇒ 本用例红（会走 schema 的路径长度上限， +/// 得到 `WriteError::Schema` 而不是 `Refused`，且断言 `!file.exists()` 仍成立但错误类型不符）。 +#[test] +fn an_overlong_install_root_is_refused_before_writing() { + let dir = root("prefs-long"); + let file = config(&dir); + let prefs = Prefs { + install_root: "x".repeat(MAX_INSTALL_ROOT + 1), + ..Prefs::default() + }; + let error = prefs_store::save(&file, &prefs).expect_err("超长路径应被拒"); + assert_eq!(error, WriteError::Refused(Refusal::InstallRootTooLong)); + assert!(!file.exists(), "被本地校验拒掉的保存不许碰磁盘"); +} diff --git a/crates/app-iced/src/pages/settings/java/tests/runtime.rs b/crates/app-iced/src/pages/settings/java/tests/runtime.rs new file mode 100644 index 0000000..c74294f --- /dev/null +++ b/crates/app-iced/src/pages/settings/java/tests/runtime.rs @@ -0,0 +1,318 @@ +//! `tests.rs` 的第三块（M175 r2）：手动名单的落盘 / 扫描槽的并发与取消 / 错误文案的 i18n。 +//! +//! 守卫①~④（列表来自真扫盘、非法路径被拒、内存越界、内存真进命令行）在 `tests.rs` 与 +//! `tests/cmdline.rs`；这一块是 r1 复审补的三条（P2-3 / P2-5 / P2-2）。 + +use super::super::state::{Refusal, RuntimeRow, State, Unwritable}; +use super::super::store; +use super::{config, fake_jdk, java_bin, root}; + +// --------------------------------------------------------------- 守卫⑤：手动名单真落盘（P2-3） + +/// 手动加一条合法路径 → **从盘上新读一份** → 名单里有它；「重启」之后仍在。 +/// +/// 为什么用注入的探测函数：`probe_manual` 要真跑 `java -version`，用例不能依赖本机装没装 JDK； +/// 但**落盘那一段走的是生产代码**（`manual::save_paths` + `manual::load_paths`），所以这条 +/// 是「持久化」的正面断言，而不是「内存里的 vec 有它」。 +/// +/// 变异证明：删掉 `store::add_manual_with` 里的 `manual::save_paths(...)` 那一行 ⇒ 这条红 +/// （`load_manual` 从盘上读回 0 条）；把去重那段删掉 ⇒ 末尾那条 `AddDuplicate` 断言红。 +#[test] +fn a_manual_path_is_written_to_disk_and_survives_a_restart() { + use unlucky_core::game::java::{JavaOrigin, JavaRuntime}; + + let dir = root("manual-ok"); + let file = config(&dir); + let jdk = fake_jdk(&dir, "manual-jdk"); + let binary = jdk.join("bin").join(java_bin()); + let runtime = JavaRuntime { + binary: binary.clone(), + origin: JavaOrigin::System, + version: Some("openjdk version \"21.0.4\" 2024-07-16 LTS".to_string()), + major: Some(21), + bits: 64, + vendor: Some("Temurin".to_string()), + }; + let probe = |_input: &str| Ok(runtime.clone()); + + // 刚加之前：盘上什么都没有。 + assert!(store::load_manual(&file).is_empty()); + + let (added, row) = store::add_manual_with(&file, &jdk.display().to_string(), &probe) + .expect("合法路径必须加得进去"); + assert_eq!(added, binary.display().to_string()); + assert_eq!(row.major, Some(21)); + + // **从盘上新读一份**（不是看内存里的 vec）。 + let listed = store::load_manual(&file); + assert_eq!(listed.len(), 1, "名单必须真的写到了盘上：{listed:?}"); + assert_eq!(listed[0], binary.display().to_string()); + assert!( + store::manual_file(&file).is_file(), + "名单文件必须真的存在：{:?}", + store::manual_file(&file) + ); + + // 「重启」：一个全新的 State 从盘上灌，名单还在。 + let reborn = State { + manual: store::load_manual(&file), + ..State::default() + }; + assert_eq!(reborn.manual.len(), 1); + + // 再加同一份 ⇒ 重复（去重也走盘上的名单）。 + assert_eq!( + store::add_manual_with(&file, &jdk.display().to_string(), &probe).err(), + Some(Refusal::AddDuplicate) + ); + std::fs::remove_dir_all(&dir).ok(); +} + +// --------------------------------------------------------------- 守卫⑥：扫描只许一个线程（P2-5） + +static JOB_LIVE: std::sync::atomic::AtomicUsize = std::sync::atomic::AtomicUsize::new(0); +static JOB_PEAK: std::sync::atomic::AtomicUsize = std::sync::atomic::AtomicUsize::new(0); +static JOB_RELEASE: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false); + +/// 一个「卡住」的扫描作业：直到被取消或 `JOB_RELEASE` 放开才返回。 +fn blocking_job( + _candidates: &[unlucky_core::game::java::staged::Candidate], + cancelled: &dyn Fn() -> bool, + _progress: &mut dyn FnMut(usize, usize), +) -> Vec { + use std::sync::atomic::Ordering; + let live = JOB_LIVE.fetch_add(1, Ordering::SeqCst) + 1; + JOB_PEAK.fetch_max(live, Ordering::SeqCst); + while !JOB_RELEASE.load(Ordering::SeqCst) && !cancelled() { + std::thread::sleep(std::time::Duration::from_millis(10)); + } + JOB_LIVE.fetch_sub(1, Ordering::SeqCst); + Vec::new() +} + +/// 扫描进行中点「立即扫描」不许起第二个线程；「取消」必须让线程**真的退出**（之后才允许再扫）。 +/// +/// 变异证明：把 `start_with` 开头那道 `if report.running { return false }` 删掉 ⇒ 第二次 +/// `start_with` 返回 `true`、`JOB_PEAK` 变成 2，这条红；把 `cancel()` 里置 `cancelled` 那两行 +/// 删掉 ⇒ 作业永远看不到取消、`report().running` 不退，超时断言红。 +#[test] +fn only_one_scan_thread_can_run_and_cancel_finishes_it() { + use std::sync::atomic::Ordering; + use std::time::{Duration, Instant}; + + JOB_RELEASE.store(false, Ordering::SeqCst); + JOB_PEAK.store(0, Ordering::SeqCst); + let slot = store::ScanSlot::default(); + + assert!( + slot.start_with(Vec::new(), Vec::new(), false, blocking_job), + "第一次扫描应该能起来" + ); + assert!( + !slot.start_with(Vec::new(), Vec::new(), false, blocking_job), + "扫描进行中不许起第二个线程" + ); + assert!(slot.report().running, "线程活着时 running 必须为真"); + + slot.cancel(); + assert!(slot.report().cancelled, "取消之后要标记 cancelled"); + let deadline = Instant::now() + Duration::from_secs(5); + while slot.report().running && Instant::now() < deadline { + std::thread::sleep(Duration::from_millis(10)); + } + assert!( + !slot.report().running, + "取消必须让扫描线程在预算内真的退出（不是只把界面翻成「已取消」）" + ); + assert!(!slot.report().finished, "被取消的扫描不许把结论当真"); + assert_eq!( + JOB_PEAK.load(Ordering::SeqCst), + 1, + "任何时刻只有一个扫描线程" + ); + + // 线程真退出之后允许重新扫（这就是「取消 ≠ 永久锁死」）。 + JOB_RELEASE.store(true, Ordering::SeqCst); + assert!( + slot.start_with(Vec::new(), Vec::new(), false, blocking_job), + "上一个线程退出之后应该能重新扫" + ); + let deadline = Instant::now() + Duration::from_secs(5); + while slot.report().running && Instant::now() < deadline { + std::thread::sleep(Duration::from_millis(10)); + } + assert!(slot.report().finished, "这次应该正常扫完"); + JOB_RELEASE.store(false, Ordering::SeqCst); +} + +// --------------------------------------------------------------- 守卫⑦：错误文案是 i18n 的（P2-2） + +/// 用户可见的失败原因**全部**来自 catalog：三档「写不进去」各有各的一句，手动路径的 +/// 「太长 / 写不进名单」也不再顶替「路径是空的 / 路径上没有东西」。 +/// +/// 抓得住：①三档文案串台（只读说成「没有改动」）；②新加的原因复用旧 key；③把中文硬编码回 +/// `store.rs`（源码扫描那一段）。 +/// 抓不住：译文翻得好不好（那是金表与人工的事）。 +/// +/// 变异证明：`Unwritable::ReadOnly` 的 key 改成 `SettingsJavaSkipNotDirty` ⇒ 这条红； +/// 把 `store.rs` 里加回一句硬编码中文 ⇒ 源码扫描那段红。 +#[test] +fn the_unwritable_reasons_have_distinct_text() { + use unlucky_i18n::{Key, Lang}; + + let en = Lang::En.catalog(); + let zh = Lang::ZhCn.catalog(); + let reasons = [ + Unwritable::NotDirty, + Unwritable::ReadOnly, + Unwritable::Unreadable, + ]; + + for reason in reasons { + assert_ne!( + en.text(reason.label()), + zh.text(reason.label()), + "{} 未翻译", + reason.label().name() + ); + } + for (index, left) in reasons.iter().enumerate() { + for right in reasons.iter().skip(index + 1) { + assert_ne!( + en.text(left.label()), + en.text(right.label()), + "「写不进去」的两档用了同一句文案：{} / {}", + left.label().name(), + right.label().name() + ); + } + } + + // 手动路径的两档新原因不许顶替旧原因（P2-2 的第三条与第四条）。 + assert_eq!( + Refusal::AddTooLong.label(), + Key::SettingsJavaReasonAddTooLong + ); + assert_eq!( + Refusal::AddWriteFailed.label(), + Key::SettingsJavaReasonAddWriteFailed + ); + assert_ne!(Refusal::AddTooLong.label(), Refusal::AddEmpty.label()); + assert_ne!(Refusal::AddWriteFailed.label(), Refusal::AddMissing.label()); + + // 源码扫描：`store.rs` 里不许再有「把 Rust 枚举名或中文字符串当人话」的写法。 + let source = include_str!("../store.rs"); + assert!( + !source.contains("format!(\"{refusal:?}\")"), + "不许把 Rust 枚举名（Refusal 的 Debug 串）当用户文案" + ); + for hardcoded in ["没有改动", "配置文件只读", "配置文件不可信"] { + // 只认**字符串字面量**（带引号）：文档注释里出现这几个词是正常的说明。 + let literal = format!("\"{hardcoded}\""); + assert!( + !source.contains(&literal), + "store.rs 里还有硬编码中文字符串：{literal}" + ); + } +} + +/// `core` 的每种拒绝原因都要落到**自己的**页面原因上（P2-2 的第三、四条）。 +/// +/// 抓得住：`ManualFailure::TooLong` 被写成 `Refusal::AddEmpty`（界面会对一条 600 字符的路径说 +/// 「路径是空的」）、名单写盘失败被写成 `Refusal::AddMissing`（磁盘写不进去却说「路径上没有东西」）。 +/// 抓不住：文案翻得好不好（那是金表与人工的事）。 +/// +/// 变异证明：`failure_refusal` 里 `TooLong => AddTooLong` 改成 `AddEmpty` ⇒ 本条红； +/// 写盘失败那行 `map_err(|_| AddWriteFailed)` 改成 `AddMissing` ⇒ 本条红。 +#[test] +fn every_manual_failure_maps_to_its_own_reason() { + use unlucky_core::game::java::manual::ManualFailure; + + let dir = root("manual-map"); + let file = config(&dir); + for (failure, expected) in [ + (ManualFailure::Empty, Refusal::AddEmpty), + (ManualFailure::TooLong, Refusal::AddTooLong), + (ManualFailure::Missing, Refusal::AddMissing), + (ManualFailure::NotJava, Refusal::AddNotJava), + (ManualFailure::NoVersion, Refusal::AddNoVersion), + ] { + let probe = move |_input: &str| Err(failure); + assert_eq!( + store::add_manual_with(&file, "whatever", &probe).err(), + Some(expected), + "{failure:?} 应该映射到 {expected:?}" + ); + } + // 一个都没写进去。 + assert!(store::load_manual(&file).is_empty()); + std::fs::remove_dir_all(&dir).ok(); +} + +/// 名单文件写不进去（父路径是个文件）时，报的是「写不进名单」而不是「路径上没有东西」。 +#[test] +fn a_failed_list_write_reports_the_write_not_the_path() { + use unlucky_core::game::java::{JavaOrigin, JavaRuntime}; + + let dir = root("manual-write-fail"); + // `/config` 做成**文件**：`manual_file` 的父目录建不出来 ⇒ save_paths 失败。 + // （`root()` 会先建好 `config/`，所以这里先删掉再放一个同名文件。） + let blocker = dir.join("config"); + std::fs::remove_dir_all(&blocker).expect("删掉空 config 目录"); + std::fs::write(&blocker, b"not a directory").expect("写占位文件"); + let file = blocker.join("launcher.json"); + let jdk = fake_jdk(&dir, "manual-jdk"); + let binary = jdk.join("bin").join(java_bin()); + let probe = |_input: &str| { + Ok(JavaRuntime { + binary: binary.clone(), + origin: JavaOrigin::System, + version: Some("openjdk version \"17.0.13\" 2024-10-15".to_string()), + major: Some(17), + bits: 64, + vendor: Some("Temurin".to_string()), + }) + }; + assert_eq!( + store::add_manual_with(&file, &jdk.display().to_string(), &probe).err(), + Some(Refusal::AddWriteFailed), + "磁盘写不进去要说「写不进名单」，不能说「路径不存在」" + ); + std::fs::remove_dir_all(&dir).ok(); +} + +// --------------------------------------------------------------- r2 P2-1：空态不许指向不存在的页 + +/// 空态给的那条「还有别的办法」必须是**真的存在**的入口。 +/// +/// 现场（r2 复审 P2-1）：原文写「或者去 Java 页装一个」，而 GUI 里根本没有 Java 页 +/// （`presenter::router::Route` 只有 Instances / Download / Content / Logs / Settings / +/// Accounts / Detail / Agent，`spawn_install` 在 `crates/app-iced/src` 里零消费者）。 +/// 于是「一个 JDK 都没装」的用户——正是这个 mission 要救的那位——被指到一个不存在的入口。 +/// +/// 抓得住：文案被改回「Java 页 / the Java page」，或把命令行入口那半句删掉。 +/// 抓不住：命令行的措辞好不好读（那是人工的事）。 +/// +/// 变异证明：把 `SettingsJavaEmptyBody` 改回「或者去 Java 页装一个」⇒ 本条红。 +#[test] +fn the_empty_state_points_at_a_real_entry() { + use unlucky_i18n::Lang; + + for lang in [Lang::En, Lang::ZhCn] { + let text = lang + .catalog() + .text(unlucky_i18n::Key::SettingsJavaEmptyBody); + assert!( + text.contains("ull java install"), + "{}：空态要给一条真能走的路（命令行）——{text}", + lang.tag() + ); + for dead in ["Java page", "Java 页"] { + assert!( + !text.contains(dead), + "{}：空态指向了不存在的入口「{dead}」——{text}", + lang.tag() + ); + } + } +} diff --git a/crates/app-iced/src/pages/settings/java/view.rs b/crates/app-iced/src/pages/settings/java/view.rs new file mode 100644 index 0000000..25b445f --- /dev/null +++ b/crates/app-iced/src/pages/settings/java/view.rs @@ -0,0 +1,307 @@ +//! 「Java」分组的一张卡片（M175）。 +//! +//! ## 版面（自上而下） +//! +//! | 行 | 内容 | 数值 / 证据 | +//! |---|---|---| +//! | 状态 | 未检测到 / N 个 JDK / 正在扫描 3/7 | 扫描按钮与取消按钮同步禁用 | +//! | 运行时列表 | 每个 JDK 一行：路径 + 版本 + 发行方 + 来源 | 「默认」标记 / 「设为默认」chip | +//! | 版本门槛 | 当前实例需要 Java ≥ N，哪一行不满足 | 来自 app 层算好的 [`Context`] | +//! | 手动添加 | 输入框 + 「添加」 | 校验不过时下面直接说原因 | +//! | 默认内存 | 数字框 + 范围提示 + 「现在生效多少来自哪一层」 | 落盘值（不是草稿） | +//! | JVM 参数 | 文本框 + 拼命令行提示 | 落盘的 `java.extra_args` | +//! | 动作 | 保存 | 灰掉时下面是原因 | +//! +//! 文案一律走 [`unlucky_i18n::Catalog`]：本组要 `Lang`，所以走 `settings/mod.rs` 的按下标分发 +//! （与 General / Update / Assistant 同一条路），`Group.body` 保持 `None`。 + +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::selection::{chip, Chip}; +use crate::pages::frame::{card, divider, text_role_owned, BASE}; +use crate::pages::Message; +use crate::theme::Ui; + +use super::fields::{actions_row, add_row, hint_line, jvm_field, memory_field, notice_line}; +use super::state::{Progress, RuntimeRow, State}; +use super::Message as JavaMessage; +use crate::pages::settings::{GroupMessage, States}; + +/// 一条本组消息 → 页面消息。 +pub(super) fn msg(message: JavaMessage) -> Message { + Message::Settings(GroupMessage::Java(message)) +} + +/// 一张卡片（`pages::settings::form` 按下标把 `Lang` 递进来）。 +pub(crate) fn body<'a>(ui: &'a Ui, states: States<'a>, lang: Lang) -> Element<'a, Message> { + body_of(ui, &states.groups.java, lang) +} + +fn body_of<'a>(ui: &'a Ui, state: &'a State, lang: Lang) -> Element<'a, Message> { + let catalog = lang.catalog(); + let mut stacked = column![].spacing(ui.space(Space::X2)).width(Length::Fill); + + stacked = stacked.push(status_row(ui, catalog, state)); + stacked = stacked.push(divider(ui)); + stacked = stacked.push(runtime_list(ui, catalog, state)); + stacked = stacked.push(divider(ui)); + stacked = stacked.push(add_row(ui, catalog, state)); + // M197：真下载一个 JDK（版本选择列表 / 下载中 / 失败三态都在这一块里）。 + stacked = stacked.push(divider(ui)); + stacked = stacked.push(super::download_view::section(ui, catalog, state)); + // M197：三个设置键（安装目录 / 发行版顺序 / 缺 JDK 时自动准备）。 + stacked = stacked.push(divider(ui)); + stacked = stacked.push(super::prefs_view::section(ui, catalog, state)); + stacked = stacked.push(divider(ui)); + stacked = stacked.push(memory_field(ui, catalog, state)); + stacked = stacked.push(jvm_field(ui, catalog, state)); + stacked = stacked.push(divider(ui)); + stacked = stacked.push(actions_row(ui, catalog, state)); + stacked = stacked.push(hint_line(ui, catalog, state)); + + if let Some(notice) = &state.notice { + stacked = stacked.push(notice_line(ui, catalog, notice)); + } + + card(ui, stacked) +} + +/// 状态行：未检测到 / N 个 JDK / 正在扫描 / 正在取消 + 两个按钮。 +/// +/// 「取消」的语义（r1 复审 P2-5）：按下之后到线程真退出之间，界面显示的是**正在取消…**， +/// 「立即扫描」保持禁用——否则用户能在旧线程还活着的时候起第二个。 +fn status_row<'a>(ui: &'a Ui, catalog: Catalog, state: &State) -> Element<'a, Message> { + let (text, scanning) = match (state.scanning, state.scanned) { + (Some(_), _) if state.cancelled => { + (catalog.text(Key::SettingsJavaCancelling).to_string(), true) + } + // 候选表还在收集（`total == 0`）：不显示 `0/0`，给一句「正在扫描…」。 + (Some(Progress { total: 0, .. }), _) => ( + catalog.text(Key::SettingsJavaScanningStart).to_string(), + true, + ), + (Some(Progress { done, total }), _) => ( + catalog.render( + Key::SettingsJavaScanning, + &[ + ("done", done.to_string().as_str()), + ("total", total.to_string().as_str()), + ], + ), + true, + ), + (None, true) if state.runtimes.is_empty() => { + (catalog.text(Key::SettingsJavaEmptyTitle).to_string(), false) + } + (None, true) => ( + catalog.render( + Key::SettingsJavaScanDone, + &[("count", state.runtimes.len().to_string().as_str())], + ), + false, + ), + (None, false) => ( + catalog.text(Key::SettingsJavaNeverScanned).to_string(), + false, + ), + }; + + let scan_label = catalog.text(Key::SettingsJavaScan); + // M237：这一整张卡片是 `frame::card` 画的（`Role::SurfaceContainerLow`），所以卡片里的 + // 控件把底传成 `frame::BASE`——禁用态的 10% / 12% 叠在卡底上，不是画布上。 + let scan = if scanning || !state.storage { + buttons::filled(ui, Button::disabled(scan_label).base(BASE)) + } else { + buttons::filled( + ui, + Button::new(scan_label, msg(JavaMessage::Scan)).base(BASE), + ) + }; + // 已经按过取消（线程还没退出）时，「取消」也灰掉：再按一次没有任何意义。 + let cancel = buttons::tonal( + ui, + if scanning && !state.cancelled { + Button::new( + catalog.text(Key::SettingsJavaCancel), + msg(JavaMessage::CancelScan), + ) + } else { + Button::disabled(catalog.text(Key::SettingsJavaCancel)) + } + .base(BASE), + ); + + // 「扫描已取消」那句只在线程**真退出之后**出现；退出之前状态行本身写着「正在取消…」。 + let cancelled = (state.cancelled && state.scanning.is_none()).then(|| { + text_role_owned( + ui, + TypeRole::BodySmall, + false, + catalog.text(Key::SettingsJavaCancelled).to_string(), + ui.color(Role::OnSurfaceVariant), + ) + }); + + let mut block = column![row![ + container(text_role_owned( + ui, + TypeRole::BodyMedium, + true, + text, + ui.color(if state.scanning.is_some() { + Role::Primary + } else { + Role::OnSurface + }), + )) + .width(Length::Fill), + scan, + cancel, + ] + .spacing(ui.space(Space::X2)) + .width(Length::Fill) + .align_y(Alignment::Center),] + .spacing(ui.space(Space::X1)) + .width(Length::Fill); + + if let Some(line) = cancelled { + block = block.push(line); + } + block.into() +} + +/// 运行时列表：每行一个 JDK，带「默认」标记与「设为默认」chip。 +fn runtime_list<'a>(ui: &'a Ui, catalog: Catalog, state: &'a State) -> Element<'a, Message> { + let mut list = column![].spacing(ui.space(Space::X2)).width(Length::Fill); + + if state.runtimes.is_empty() { + let body = if state.scanned { + catalog.text(Key::SettingsJavaEmptyBody) + } else { + catalog.text(Key::SettingsJavaNeverScannedBody) + }; + return text_role_owned( + ui, + TypeRole::BodySmall, + false, + body.to_string(), + ui.color(Role::OnSurfaceVariant), + ); + } + + for runtime in &state.runtimes { + list = list.push(runtime_row(ui, catalog, state, runtime)); + } + list.into() +} + +fn runtime_row<'a>( + ui: &'a Ui, + catalog: Catalog, + state: &'a State, + runtime: &'a RuntimeRow, +) -> Element<'a, Message> { + let is_default = super::state::same_path(&runtime.binary, &state.selected); + // M197：**带方向**的三态。M175 的布尔判定对「1.12.2 + Java 21」会说「低于要求：需要 Java 8 + // 及以上」——21 当然 ≥ 8，那句话自相矛盾；现在两个方向各说各的。 + let (verdict, verdict_color) = match state.fit(runtime.major) { + Some(super::state::Fit::Ok) => ( + catalog.text(Key::SettingsJavaFits).to_string(), + ui.color(Role::Primary), + ), + Some(super::state::Fit::TooOld { required, .. }) => ( + catalog.render( + Key::SettingsJavaTooOld, + &[("minimum", required.to_string().as_str())], + ), + ui.color(Role::Error), + ), + Some(super::state::Fit::TooNew { maximum, .. }) => ( + catalog.render( + Key::SettingsJavaTooNew, + &[("maximum", maximum.to_string().as_str())], + ), + ui.color(Role::Error), + ), + None => (String::new(), ui.color(Role::OnSurfaceVariant)), + }; + + let action = chip(ui, action_chip(catalog, state, runtime).base(BASE)); + + let mut block = column![row![ + container( + column![ + text_role_owned( + ui, + TypeRole::BodyMedium, + is_default, + runtime.display_home(), + ui.color(Role::OnSurface), + ), + text_role_owned( + ui, + TypeRole::BodySmall, + false, + format!( + "{} · {}", + runtime.summary(), + catalog.text(runtime.source_key()) + ), + ui.color(Role::OnSurfaceVariant), + ), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill), + ) + .width(Length::Fill), + action, + ] + .spacing(ui.space(Space::X2)) + .width(Length::Fill) + .align_y(Alignment::Center)] + .spacing(ui.space(Space::X1)) + .width(Length::Fill); + + if !verdict.is_empty() { + block = block.push(text_role_owned( + ui, + TypeRole::BodySmall, + false, + verdict, + verdict_color, + )); + } + block.into() +} + +/// 一行右侧的动作位（M206 把它抽成纯函数，好让断言直接对着它量对比度）： +/// +/// - **当前默认**那一行 → [`Chip::current`]：与下载组选中 chip **同一套颜色** +/// （`SecondaryContainer` + `OnSecondaryContainer`），但没有消息、不吃五态； +/// - 其余 → 可点的 [`Chip::filter`]`(…, false, …)`「设为默认」。 +/// +/// 为什么不用 `Chip::badge` 表示当前默认：`badge` 走的是**禁用**配色（`OnSurface`@38% 叠 surface， +/// M204 实测 **1.84:1 浅 / 2.28:1 深**）。把「暂不可用」的语汇贴在「哪个 JDK 是默认」这个 +/// **答案本身**上，就是 M206 要修的那件事。档位判据表见 `components::selection::chip` 的模块文档。 +pub(super) fn action_chip<'a>( + catalog: Catalog, + state: &State, + runtime: &'a RuntimeRow, +) -> Chip<'a, Message> { + if super::state::same_path(&runtime.binary, &state.selected) { + Chip::current(catalog.text(Key::SettingsJavaDefault)) + } else { + Chip::filter( + catalog.text(Key::SettingsJavaSetDefault), + false, + msg(JavaMessage::SelectRuntime(runtime.binary.clone())), + ) + } +} 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..f94b74b --- /dev/null +++ b/crates/app-iced/src/pages/settings/language_appearance.rs @@ -0,0 +1,41 @@ +//! 设置页 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/`（`appearance.rs` 只负责把 `body` 挂上去）。 + +/// 语言 + 外观线的状态（**只归本线**）。 +/// +/// 外观那份运行期状态是 `pages::appearance::State`（M93），走 `States::appearance` 那条既有通道， +/// 不在这里。本结构只装**分组自己的**档位：M229 起主题三档（Ink / Silver / 跟随系统）住这儿， +/// 由 `app` 在启动与切换时同步（唯一写者见 `app/state/theme.rs::set_theme_mode`）。 +/// +/// 初值 `Auto`：harness / 演示路径没有配置可读，跟随系统正是出厂值。 +#[derive(Debug, Default)] +pub struct State { + /// 当前主题档（Ink = `Dark` / Silver = `Light` / 跟随系统 = `Auto`）。 + pub theme: unlucky_presenter::prefs::ThemeMode, +} + +/// 语言 + 外观线的消息（**只归本线**）。 +/// +/// 首版是空枚举：这一条线还没有接真下拉 / 真控件之前，没有可点的东西。空枚举的好处是 +/// `app/update/settings/language_appearance.rs` 里的 `match message {}` 天然穷尽——加了变体 +/// 不接线就报 E0004，不会静默。 +#[derive(Debug, Clone)] +pub enum Message {} diff --git a/crates/app-iced/src/pages/settings/logs_row.rs b/crates/app-iced/src/pages/settings/logs_row.rs new file mode 100644 index 0000000..b543034 --- /dev/null +++ b/crates/app-iced/src/pages/settings/logs_row.rs @@ -0,0 +1,129 @@ +//! 设置页「General」组的**日志文件夹**一行（M188）。 +//! +//! 用户投诉原话：「我们的启动日志放在哪？…他找半天没找到崩溃日志」「只有一个安装日志」。 +//! 这一行是对那句投诉的直接回答，三件事缺一不可： +//! +//! 1. **路径永远显示**（不是只在打开成功时才显示）：`<数据根>/logs`，三模式解析出来的真值； +//! 2. **两个入口**：「打开文件夹」走平台打开器（`app::dialog::export::open_dir`，与崩溃弹窗同一个， +//! 不另写一套 `cfg`），「复制路径」把路径送进剪贴板——打开失败时用户至少能照着路径自己去找； +//! 3. **说清里面有什么**：`launcher.log`（滚动上限写进文案）与 `logs/game/` 的会话 jsonl， +//! 以及旧目录「仍能读、没搬动」——否则用户换了版本会以为旧日志丢了。 +//! +//! 为什么单独一个文件：`pages/settings/general.rs` 贴着 400 行硬线（语言行 + 字体行 + 三行只读）， +//! 这一行自带按钮与样式，塞回去必破线。 + +use iced::widget::{button, column, container, row as row_widget}; +use iced::{Alignment, Background, Border, Element, Length, Padding, Shadow, Theme as IcedTheme}; + +use unlucky_design::color::{Role, StateLayer}; +use unlucky_design::shape::ShapeScale; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; +use unlucky_i18n::catalog::{Catalog, Key}; + +use crate::pages::{frame, Action, Message}; +use crate::theme::Ui; + +/// 这一行（竖排：标签 / 路径 / 两个按钮 / 一句说明）。 +pub(super) fn folder_row<'a>(ui: &'a Ui, catalog: &Catalog) -> Element<'a, Message> { + let path = crate::app::logs_folder::logs_dir() + .map(|dir| dir.display().to_string()) + .unwrap_or_else(|| catalog.text(Key::SettingsLogsUnknown).to_string()); + + let hint = catalog.text(Key::SettingsLogsFolderHint); + let actions = row_widget![ + action_button( + ui, + catalog.text(Key::LogsOpenFolder), + Message::Action(Action::OpenLogs), + ), + action_button( + ui, + catalog.text(Key::SettingsLogsCopy), + Message::CopySummary(path.clone()), + ), + ] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Center); + + column![ + frame_text( + ui, + TypeRole::BodyMedium, + catalog.text(Key::SettingsLogsFolder), + ui.color(Role::OnSurface), + ), + container(frame_text_owned( + ui, + TypeRole::BodySmall, + path, + ui.color(Role::OnSurfaceVariant), + )) + .width(Length::Fill), + actions, + frame_text( + ui, + TypeRole::BodySmall, + hint, + ui.color(Role::OnSurfaceVariant), + ), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill) + .padding(Padding::from([ui.space(Space::X2), 0.0])) + .into() +} + +fn frame_text<'a>( + ui: &'a Ui, + role: TypeRole, + text: &'a str, + color: iced::Color, +) -> Element<'a, Message> { + frame::text_role(ui, role, false, text, color) +} + +fn frame_text_owned<'a>( + ui: &'a Ui, + role: TypeRole, + text: String, + color: iced::Color, +) -> Element<'a, Message> { + frame::text_role_owned(ui, role, false, text, color) +} + +/// 描边小按钮（与设置页其他「次级动作」同款：透明底、hover 出状态层、全圆角）。 +fn action_button<'a>(ui: &'a Ui, label: &'a str, message: Message) -> Element<'a, Message> { + let height = ui.metrics().control_height; + let content = ui.color(Role::OnSurface); + let outline = ui.color(Role::OutlineVariant); + button( + container(frame_text(ui, TypeRole::LabelLarge, label, content)).align_y(Alignment::Center), + ) + .height(height) + .padding(Padding::from([0.0, ui.space(Space::X3)])) + .style(move |_theme: &IcedTheme, status| { + let background = + matches!(status, button::Status::Hovered | button::Status::Pressed).then(|| { + // M237：这一行住在设置卡里（`frame::card`），hover 状态层叠卡底。 + Background::Color(ui.state_over( + StateLayer::Hover, + Role::OnSurface, + frame::BASE.role(), + )) + }); + button::Style { + background, + text_color: content, + border: Border { + color: outline, + width: 1.0, + radius: ui.radius(ShapeScale::Full, height), + }, + shadow: Shadow::default(), + snap: true, + } + }) + .on_press(message) + .into() +} 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::(), + "settings::java::Message", + ), + ( + std::any::type_name::(), + "settings::download::Message", + ), + ( + std::any::type_name::(), + "settings::language_appearance::Message", + ), + ( + std::any::type_name::(), + "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..ff25f01 --- /dev/null +++ b/crates/app-iced/src/pages/settings/mod.rs @@ -0,0 +1,399 @@ +//! 设置页：**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/`） | +//! | Java | [`java`] | java 线 | +//! | Downloads | [`download`] | download 线 | +//! | Updates | [`update`] | update 线（M159，按下标分发） | +//! | Assistant | [`ai_about`]（正文在 [`ai`]） | ai 线（M174，按下标分发：本组要 `Lang`） | +//! | 页头 / 侧列 / 滚动区 / 演示卡片 | [`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`。 +//! +//! **M159 的第五组（更新）是另一条形状**：它不持有组状态、也不走 `GroupMessage`，而是读 +//! `settings::view` 的 `update` 形参（presenter 快照），由 [`UPDATE_GROUP`] 按下标分发——与 M106 的 +//! 语言行同一取舍（那两样都不是「某一组的内部状态」）。所以加它只动了 ① `pages/settings/update.rs`、 +//! ② 本文件的 [`GROUPS`] / [`GROUP_LABELS`] / `render` 的形参、③ `pages/mod.rs` 与 `pages/model.rs` +//! （模型多一格 `update`），**没有**碰 `state::Groups` 与 `message::GroupMessage`。 +//! +//! ## 消息：一个投递口，四条线各写各的（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`] —— 加一整组时加一行（M174 的助手组就是这么来的：`GROUPS` 与 +//! [`GROUP_LABELS`] 各加一行、长度 +1，`tests/mod.rs` 的「左列顺序」随之更新）。 +//! 3. `tests/mod.rs` —— 「左列顺序」那条字面量断言会连带红，需要人确认（M174 就是把它加了一个 +//! `"Assistant"`）。加分组自己的测试文件时还要在 `tests/mod.rs` 顶部挂一行 `mod <名>;`； +//! M174 的用例走的是组内路径（`pages/settings/ai/tests.rs`），所以没有新增挂载行。 +//! 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` +//! 不用动 —— **推荐这个形状**。语言也已有真值源（`ui/lang.rs` 的 `App::lang` → `view::model(…)` +//! → `Model.lang`）：某组读「当前语言」走它或 `Groups` 里本线字段，别再另造一层状态。 +//! 5. **首帧取数 / 异步发起**（同上，r2 复审 P1 补）—— [`Body`] 是 +//! `fn(&Ui, States, Lang) -> Option`，返回不了 `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` 撑着 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; +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 logs_row; +mod message; +mod state; +pub(crate) mod update; + +#[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::update::Update; +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 要的正是这一点）。 +/// +/// `lang` 是 M179 加的：槽位此前拿不到语言，唯一挂了真控件的外观组只能写死英文；接进**唯一的那个 +/// 槽位**比再给 [`form`] 加一条按下标分发的 `else if` 更省行数（本文件贴着 400 行硬顶）。 +type Body = for<'a> fn(&'a Ui, States<'a>, Lang) -> Option>; + +/// 一个设置分组：名字、图标、演示行、（可选）把这一组正文画成真控件的渲染器。 +/// +/// 除 `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, +} + +/// 分组注册表：**顺序 = 左列自上而下**，也是 `crate::pages::appearance::APPEARANCE_GROUP` 的下标来源。 +/// +/// 每一项都指向它自己文件里的 `GROUP`（M99 之前是四份字面量挤在本文件里）。 +const GROUPS: [Group; 6] = [ + general::GROUP, + appearance::GROUP, + java::GROUP, + download::GROUP, + // M159：自更新只**追加**在末尾（插在中间会让 `APPEARANCE_GROUP` / `GENERAL_GROUP` 两个下标 + // 全部失效，`tests/mod.rs` 的「左列顺序」那条也会红）。 + update::GROUP, + // M174：助手（AI）配置。同样只追加（下标 = `ai_about::AI_GROUP`），正文走按下标分发。 + ai_about::GROUP, +]; + +/// 演示选中的分组（没有真实外观状态时——`pages_demo` harness——用它）。 +const SELECTED: usize = 0; + +/// General 分组在 [`GROUPS`] 里的下标（0）。它与 [`SELECTED`] 同值**是巧合，不是依赖**。 +/// +/// 为什么需要它：语言行要的是「当前档位 + 生效语言」（[`Language`]），而 `Group.body` 只带 +/// [`States`] 与**生效语言**（`Lang`，M179）——档位 `LangChoice` 装不进去（`States` 也装不下： +/// 加字段要动 `settings/state.rs` 与 4 处 struct literal，见本文件文档「仍然共享」第 4 条）。 +/// 所以这里做一次**按下标的分发**：代价是一行 `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; 6] = [ + unlucky_i18n::Key::SettingsGroupGeneral, + unlucky_i18n::Key::SettingsGroupAppearance, + unlucky_i18n::Key::SettingsGroupJava, + unlucky_i18n::Key::SettingsGroupDownloads, + // M159 + unlucky_i18n::Key::SettingsGroupUpdate, + // M174 + unlucky_i18n::Key::SettingsGroupAssistant, +]; + +/// 「更新」分组在 [`GROUPS`] 里的下标（真源在 `settings/update.rs`，这里只转发）。 +/// +/// 与 [`GENERAL_GROUP`] 同一种做法：这一组要画的是 **presenter 快照**（不在 [`States`] 里）， +/// 所以由 `view` 的 `update` 形参一路递到下标的 [`form`] 分发点，`GROUP.body` 保持 `None`。 +const UPDATE_GROUP: usize = update::UPDATE_GROUP; + +/// 「助手（AI）」分组在 [`GROUPS`] 里的下标（真源在 `settings/ai_about.rs`，这里只转发）。 +/// +/// 与 [`GENERAL_GROUP`] / [`UPDATE_GROUP`] 同一条做法：由 `view` 的 `language` 形参递到 [`form`] +/// 按本下标分发，`GROUP.body` 保持 `None`（本组**尚未**迁到 [`Body`] 槽位：槽位现在带 `Lang` 了， +/// 迁它要把 `ai::view::body` 的返回值改成 `Option`，是一次独立重构——M179 不做）。 +const AI_GROUP: usize = ai_about::AI_GROUP; + +/// 「Java」分组在 [`GROUPS`] 里的下标（真源在 `settings/java.rs`，这里只转发）。 +/// +/// M175 起这一组也按下标分发：它要 `Lang`（中英文案）并且要读后台扫描的快照 +/// （扫描线程不碰 `App`，结论由心跳灌进 `Groups.java`，页面只从 [`States`] 里取）。 +const JAVA_GROUP: usize = java::JAVA_GROUP; + +/// 整页。 +/// +/// `states` 是「画一帧时那份只读状态」：[`States::appearance`] 是 M93 接进来的外观运行期状态 +/// （`None` = harness / 演示路径，设置页仍画占位行），[`States::groups`] 是各组自己的状态。 +pub fn view<'a>( + ui: &'a Ui, + metrics: FrameMetrics, + states: States<'a>, + language: Language, + update: &'a Update, +) -> 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, update), + ), + ), + _ => frame::single_column(metrics, form(ui, None, states, language, update)), + }; + + frame::page(ui, metrics, frame::header(ui, language.effective), body) +} + +// --------------------------------------------------------------- 内容分发 + +/// 表单列（正文列宽 ≤424）。`only = Some(i)` 只渲染一组（supporting-pane），`None` 渲染全部（窄窗按组堆叠）。 +/// +/// **分发点（两条路，M106 起就并存）**：①`GROUP.body`——`Some(f)` 自己去 [`States`] 取数，并从形参拿 +/// **生效语言**（`None` 退回演示行）；②**按下标分发**——General（语言档位）/ Update（presenter 快照）/ +/// Assistant（`Lang` + 测试结论）/ Java（`Lang` + 扫描槽）在 [`section_columns`] 里各有 `else if`，它们 +/// 的 `GROUP.body` 仍是 `None`（理由见各自的 `<组>_GROUP` 常量）；分组名只作 `GROUPS` 元素的 id。 +/// +/// **尾部不许再挂东西（M196）**：循环之后原先无条件叠了一张「没有逐实例覆盖」的空态卡（来历见 +/// `frame.rs`），于是**每一组**下面都长出同一张卡。它**放错了地方**：真控件在**实例详情页**的「启动 +/// 参数」区（M157 `pages/instances/launch_args.rs` → `AppCommand::set_launch_args`），设置页拿不到那份 +/// 快照（[`view`] 没有 `Model`）；无人产出的只有 `Action::AddOverride`。删掉，守门见 `frame.rs` 末尾。 +fn form<'a>( + ui: &'a Ui, + only: Option, + states: States<'a>, + language: Language, + update: &'a Update, +) -> Element<'a, Message> { + let mut stack = column![].spacing(ui.space(Space::X6)).width(Length::Fill); + + for section in section_columns(ui, only, states, language, update) { + stack = stack.push(section); + } + + frame::scroll(ui, stack) +} + +/// 正文里**每组一件**的列（顺序 = [`GROUPS`]，只含被选中的那些；分发点见 [`form`] 的文档）。抽出来是 +/// 为了能被**行为断言**量到：`frame.rs` 的 `the_form_holds_exactly_one_column_per_group` 数它的列数。 +fn section_columns<'a>( + ui: &'a Ui, + only: Option, + states: States<'a>, + language: Language, + update: &'a Update, +) -> Vec> { + let catalog = language.effective.catalog(); + let mut columns = Vec::new(); + + 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, states, language) + } else if index == UPDATE_GROUP { + // M159：更新组读 presenter 快照（`view` 的 `update` 形参），与 General 同一条按下标分发。 + update::body(ui, update, language.effective) + } else if index == AI_GROUP { + // M174：助手组要 i18n 文案与「测试连接」结论，与 General / Update 同一条按下标分发。 + ai::view::body(ui, states, language.effective) + } else if index == JAVA_GROUP { + // M175：Java 组要 i18n 文案 + 扫描快照，同样按下标分发（`GROUP.body` 保持 `None`）。 + java::view::body(ui, states, language.effective) + } else { + group + .body + .and_then(|body| body(ui, states, language.effective)) + .unwrap_or_else(|| frame::demo_card(ui, group.rows)) + }; + + columns.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) + .into(), + ); + } + + columns +} 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..13eeb72 --- /dev/null +++ b/crates/app-iced/src/pages/settings/state.rs @@ -0,0 +1,97 @@ +//! 设置页的**状态漏斗**（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 unlucky_presenter::dto::SettingGroupView; + +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, +} + +/// 画一帧时**按值**递给各组渲染器的只读视图：组状态 + 外观运行期状态 + presenter 的设置快照 +/// （三个引用，`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, + /// **presenter 的设置组快照**（M201）：`CoreEvent::SettingsChanged` 的回流结果， + /// `pages::Model` 那份（`Model::settings`）。空切片 = 这一帧没有快照（harness / 首帧）， + /// 组自己的 `body` 据此退回演示行。 + /// + /// 为什么走这里而不是给 `settings::view` 加形参：`Group.body` 的槽位签名是 + /// `fn(&Ui, States, Lang) -> Option`，它**只看得到 `States`**——下载组要画真控件 + /// （`GROUP.body = Some(..)`，见 `settings/download.rs`）就必须从这里拿到快照。加形参那条路 + /// 与 `GROUP.body` 互斥，而且要把 `settings/mod.rs`（399 行）再撑出 10 行。 + pub settings: &'a [SettingGroupView], +} + +/// 演示 / 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 = 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..d628be1 --- /dev/null +++ b/crates/app-iced/src/pages/settings/tests/appearance_section.rs @@ -0,0 +1,172 @@ +//! 「Appearance」分组自己的断言（M100 **新增**：`settings/tests.rs` 那 7 条全是跨 section 的， +//! 一条 section 断言都没有；这 3 条是新增，不是搬移）。 +//! +//! **归 language+appearance 线**：这是设置页唯一接了真控件的一组，真控件实现全在 +//! `pages/appearance/section/`；本文件只守「注册表这一侧的接线」。 +//! 本组已经把 `body` 接上了；`tests/mod.rs` 那条「只有一组有真控件」的**聚合绊线已在 M101 r2 删除** +//! （被四条 per-group 断言完全蕴含——代价是「唯一性」从此没人守，那段说明写在 `tests/mod.rs` 同处）。 +//! +//! M179 `I18NSEAM` 加的第 4 条守的是**语言真的进到了渲染层**（此前这一组在中文界面上 0/27 条本地化）。 + +use super::super::appearance; +use super::super::{demo_groups, view, Language, States}; +use unlucky_design::color::SchemeFlavor; +use unlucky_design::icons::IconKind; +use unlucky_i18n::catalog::Key; +use unlucky_i18n::{Lang, LangChoice}; +use unlucky_presenter::prefs::{AppearanceBase, AppearancePrefs}; + +use crate::cli::Backend; +use crate::pages::appearance::{probe, State as AppearanceState}; +use crate::pages::layout::{frame_metrics, PaneKit}; +use crate::pages::Update; +use crate::theme::{Families, Ui}; + +/// 这一组的**演示行**（没有外观运行期状态时才画）。 +/// +/// 抓得住：四条线并行合并时把别人的行粘到本文件（四份 `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；具体渲染器由那一行源码 + 截图担保，函数指针相等性断言不了）" + ); +} + +// --------------------------------------------------------------- 语言（M179 I18NSEAM） + +/// **本组的语言绊线**：中文界面下，外观分组渲染出来的字里**必须含汉字**。 +/// +/// 走的是真路：`settings::view`（真语言分发）→ `Group.body(lang)` → `pages::appearance::section` +/// → `section::t(key, lang)`；取词口 `t` 把每条译文记进 `pages::appearance::probe`，测试断言这批字。 +/// +/// 为什么不在 `Element` 上遍历：iced 0.14 **没有**可遍历控件树的公开接口（`Widget::children()` +/// 返回的是状态 `Tree`；走 `operate` 要 `Tree` + 布局 + `Renderer`，单测里没有渲染器）。取证点 +/// 因此退到「字进树之前」的唯一取词口，代价是**看不见像素**——字体能不能画出汉字要截图判 +/// （M179 报告「没验的部分」列了这条）。 +/// +/// 抓得住：① `section::t` 退回写死 `Lang::En`（M179 之前正是这一行 ⇒ 中文界面上这一组 0/27 +/// 条本地化）；② `settings::view` 不把 `language.effective` 递给 `Group.body`（语言到不了渲染层）； +/// ③ 五个 key 的译文在金表里丢了中文。 +/// 抓不住：本组其余文案仍是英文**字面量**（没有 key，M172 口径的 27 条里占 22 条）——这条守的是 +/// 语言的**管子**，不是文案；补文案是下一条 mission（M179 报告逐行列了那些字面量）。 +#[test] +fn the_appearance_group_speaks_chinese_when_the_interface_does() { + let zh = appearance_texts(Lang::ZhCn); + assert!( + !zh.is_empty(), + "外观分组一条词表文案都没取到：渲染路径没走到 `section::t`（语言管子断了？）" + ); + assert!( + zh.iter() + .any(|(key, _)| *key == Key::SettingsAppearanceCorner), + "渲染路径没画到「窗口圆角」那一行：取词记录里没有它的 key，{zh:?}" + ); + + let han: Vec<&str> = zh + .iter() + .map(|(_, text)| *text) + .filter(|text| text.chars().any(is_han)) + .collect(); + assert!( + !han.is_empty(), + "中文界面下外观分组渲染出来的字全是非汉字（`section::t` 没跟随语言）：{zh:?}" + ); + + // 反向：英文界面下同一批字里不许出现汉字（否则「含汉字」可能来自写死的中文，而不是语言管子）。 + let en = appearance_texts(Lang::En); + assert!( + en.iter().all(|(_, text)| !text.chars().any(is_han)), + "英文界面下外观分组出现了汉字：{en:?}" + ); + let corner = |texts: &[(Key, &'static str)]| { + texts + .iter() + .find(|(key, _)| *key == Key::SettingsAppearanceCorner) + .map(|(_, text)| *text) + }; + assert_ne!( + corner(&zh), + corner(&en), + "同一个 key 在中英两种语言下取到了同一条译文：语言没生效" + ); +} + +/// 画一帧设置页（选中「外观」分组）并取走这一帧从词表取到的全部译文。 +fn appearance_texts(lang: Lang) -> Vec<(Key, &'static str)> { + const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", + }; + + let ui = Ui::new(SchemeFlavor::Light, FAMILIES); + let state = AppearanceState::new( + &AppearancePrefs::factory(), + &AppearanceBase::factory(), + Backend::Auto, + SchemeFlavor::Light, + ); + assert_eq!( + state.selected_group, + crate::pages::appearance::APPEARANCE_GROUP, + "工厂态默认选中「外观」分组（否则这一帧根本画不到本组）" + ); + // 前面几条用例不取词，这里先清一次，避免把别的渲染留下的记录算进来。 + probe::take(); + + let metrics = frame_metrics(PaneKit::Supporting, 1180.0); + let update = Update::default(); + let _tree = view( + &ui, + metrics, + States { + appearance: Some(&state), + groups: demo_groups(), + settings: &[], + }, + Language { + choice: LangChoice::System, + effective: lang, + }, + &update, + ); + + probe::take() +} + +/// 有没有汉字（判据与 `app/view/tests/launch.rs` 的 `is_cjk` 同一段码位）。 +fn is_han(ch: char) -> bool { + ('\u{4e00}'..='\u{9fff}').contains(&ch) +} 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..b60720f --- /dev/null +++ b/crates/app-iced/src/pages/settings/tests/download_section.rs @@ -0,0 +1,207 @@ +//! 「Downloads」分组自己的断言（M100 **新增**：`settings/tests.rs` 那 7 条全是跨 section 的， +//! 一条 section 断言都没有；这几条是新增，不是搬移）。 +//! +//! **归 download 线**。M201 之前这一组只有演示行；现在它接了真控件（`GROUP.body = Some(body)`）， +//! 数据来自 presenter 的设置快照（`States::settings` ← `pages::Model::settings`）。 +//! +//! 别把它和下载页（`pages/download*`）搞混：那是「装哪个版本」，这一组是「怎么下」的默认值。 +//! +//! ## 这一轮换了什么（M201） +//! +//! | 旧绊线 | 现在 | +//! |---|---| +//! | `body.is_none()`（「这一组还没接真控件」） | `body.is_some()`（「接了，别再退回去」） | +//! | 只有 `rows` 的语义行断言 | 保留 + 三条**控件形状**断言（按 `SettingControl` 分发） | +//! +//! 写回闭环（点了以后盘上真的变了）不在本文件：那是 `app/update/settings/download_tests.rs`， +//! 它要一个假后端 + `App`，页面层的测试拿不到。 + +use super::super::download; +use super::super::States; +use unlucky_design::icons::IconKind; +use unlucky_presenter::dto::{SettingControl, SettingGroupView, SettingRowView}; + +/// 一份照 presenter 的 `host::settings::download::group` 形状搭的快照（键与控件种类同序）。 +/// +/// 为什么自己搭而不是问 presenter 要：那个函数要 `HostEnv`（读盘）且不在 `host` 的公开面上； +/// 本文件守的是**页面按 `control` 字段分发**这件事，不是 presenter 的行文案。 +fn snapshot() -> Vec { + vec![SettingGroupView::new("download", "下载与镜像（D7）") + .with(SettingRowView::choice( + "download.concurrency", + "并发数", + "同时下载的文件数", + &["4", "8", "16"], + 1, + )) + .with(SettingRowView::choice( + "download.retry_limit", + "单源尝试次数", + "同一个源最多试几次", + &["0", "1", "3"], + 2, + )) + .with(SettingRowView::text( + "download.proxy_url", + "HTTP 代理", + "manual 模式生效", + "", + )) + .with(SettingRowView::action( + "download.action.detect_region", + "重新检测地区", + "清掉 24h 地区缓存", + "detect_region", + ))] +} + +/// 这一组的行集合（标签 + 值）——**没有快照时**画的语义行。 +/// +/// 抓得住：① 四条线并行合并时把别人的行粘到本文件（六份 `GROUP` 长得几乎一样，最容易整块贴错）； +/// ② 漏掉/多出一条行；③ 标签与值错位。 +/// 抓不住：值对不对（这几行本来就不是值，是语义），也抓不住有快照时画什么（下一条用例管）。 +#[test] +fn the_downloads_group_shows_concurrency_retries_and_the_gh_proxy_key() { + let rows: Vec<(&str, &str)> = download::GROUP.rows.to_vec(); + assert_eq!( + rows, + vec![ + ("并发数", "出厂 8 · 可调 1~64"), + ("单源尝试次数", "出厂 3 · 含首次 · 0/1 = 只试一次"), + ("GitHub 加速前缀", "留空 = 跟随内置默认"), + ("关掉它", "填 off = 关闭"), + ("换掉它", "填 URL 前缀 = 覆盖"), + ] + ); +} + +/// 左列图标（`IconKind::Download`）。与导航轨的「下载」同族，换掉就与 rail 语汇不一致。 +#[test] +fn the_downloads_group_keeps_its_icon() { + assert_eq!(download::GROUP.icon, IconKind::Download); +} + +/// **M201 翻了这条绊线**：这一组现在有真控件渲染器。 +/// +/// 旧绊线 `the_downloads_group_is_still_demo_rows`（`body.is_none()`）存在的意义是「防止演示值 +/// 回潮」。M201 之后演示值已经不是问题——有快照就画真控件，没快照才退回语义行——所以绊线翻面： +/// +/// 抓得住：① 谁把 `GROUP.body` 改回 `None`（真控件当场消失，页面又只剩静态语义行 —— +/// 那正是用户投诉的形态）；② 谁把渲染器挪走却忘了同步这里。 +/// 抓不住：渲染器**画得对不对**（`Element` 没有内省接口，形状断言在下一条），也抓不住 +/// 「有快照时真的走了 body」（`settings/mod.rs` 的 `and_then` 那一层；那一层断了会退回语义行， +/// 界面上看得出来，但没有断言）。 +#[test] +fn the_downloads_group_carries_a_real_control_body() { + assert!( + download::GROUP.body.is_some(), + "Downloads 必须挂着真控件渲染器：`body = None` 就是「设置页里改不了」的回归" + ); +} + +/// **控件形状**：快照里有几种 `SettingControl`，页面就画几种（choice / text / action）。 +/// +/// 抓得住：① 渲染器只认 choice（把 text / action 也画成chip 或干脆不画）——`controls_of` 是从 +/// 同一份行模型上读的，但**分发**发生在 `body` 里，改成 `match` 单臂会让别的行整段消失； +/// ② 谁把 `SettingControl::Text` 落到 `read_only_row` 上（那时输入框没了，用户改不了文本键）。 +/// 抓不住：画出来的像素（那是截图的事），也抓不住每种控件是否真的连了消息（那是 app 层的 +/// `download_tests.rs` 与真机截图）。 +#[test] +fn the_downloads_body_follows_the_control_kind() { + let groups = snapshot(); + assert_eq!( + download::controls_of(&groups), + vec![ + SettingControl::Choice, + SettingControl::Choice, + SettingControl::Text, + SettingControl::Action, + ], + "控件种类必须照快照的 `control` 字段画" + ); +} + +/// **没有快照就不许编值**：`controls_of` 空 ⇒ 页面退回 [`download::GROUP.rows`] 的语义行。 +/// +/// 抓得住：谁为了「让页面好看」在渲染器里塞一份写死的默认快照（那就是 M193 被投诉的演示值， +/// 只不过换了个藏身处）。 +/// 抓不住：「空快照时确实走了 `demo_card`」这一步（`settings/mod.rs` 的退回逻辑，它有自己的 +/// `frame.rs` 守门）。 +#[test] +fn an_empty_snapshot_lists_no_controls() { + assert!(download::controls_of(&[]).is_empty()); + + // 别的组在场、本组缺席，同样一条控件都不该画（不许拿别人的行凑数）。 + let other = vec![ + SettingGroupView::new("java", "Java（D13）").with(SettingRowView::toggle( + "java.auto_install", + "缺 Java 时自动下载", + "", + true, + )), + ]; + assert!(download::controls_of(&other).is_empty()); +} + +/// 语义行里的「三态 / 区间 / 出厂值」必须还在——它们是**没有快照时**唯一说得清的说明。 +/// +/// 这一条是 M193 留下的，M201 原样保留：即便有了真控件，兜底那一屏也不许出现假的当前值。 +/// +/// 抓得住：把 gh_proxy 那两行合并成一句（「留空 = 关闭」这种混法）、或者把区间 / 0-1 语义删掉。 +/// 抓不住：有快照时行文案对不对（那时文案来自 presenter，见 `host/settings/download_tests.rs`）。 +#[test] +fn the_downloads_rows_state_semantics_and_never_fake_a_current_value() { + let joined = download::GROUP + .rows + .iter() + .map(|(label, value)| format!("{label} {value}")) + .collect::>() + .join(" | "); + + for required in [ + // 三态里最容易被混的两档，必须都在（缺一个就是「设置项说假话」的种子）。 + "留空 = 跟随内置默认", + "填 off = 关闭", + "填 URL 前缀 = 覆盖", + // 硬上限必须在界面上说清（任务书的边界条款）。 + "1~64", + // P2-1：0 是旧版提供过的档位，界面必须说清它 = 只试一次（不是「不下载」）。 + "0/1 = 只试一次", + // 三个键各自是哪一行（标签本身也是契约：用户按它认设置）。 + "并发数", + "单源尝试次数", + "GitHub 加速前缀", + ] { + assert!( + joined.contains(required), + "行里缺少「{required}」：{joined}" + ); + } + + // 「当前值」形态的假数据：`8 threads` / `On` / `Automatic (region)` 都是当年被投诉的那类。 + for forbidden in ["threads", "Automatic (region)", "Verify checksums"] { + assert!( + !joined.contains(forbidden), + "又出现假的当前值「{forbidden}」：{joined}" + ); + } +} + +/// 本组是**有快照就不退回演示行**的那一类：`States` 里带了快照时，`body` 一定拿得到组。 +/// +/// 站位提醒：`States` 是 `pages::settings::States`（三条线共享的只读视图），本文件只验证 +/// 「本组能从它里面找到自己」——找不到就等于退回演示行。 +#[test] +fn the_group_finds_itself_in_the_states_snapshot() { + let groups = snapshot(); + let groups_state = super::super::demo_groups(); + let states = States { + appearance: None, + groups: groups_state, + settings: &groups, + }; + assert!( + states.settings.iter().any(|group| group.id == "download"), + "本组的 id 必须在快照里：`download`（presenter 的 `SettingGroupView::new(\"download\", ..)`）" + ); +} 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..ca38f34 --- /dev/null +++ b/crates/app-iced/src/pages/settings/tests/general_section.rs @@ -0,0 +1,246 @@ +//! 「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`——那个槽位现在带**生效语言**（`Lang`，M179）但仍是 +//! `States` + 语言，装不下「当前语言档位」（`LangChoice`）。所以 M101 r2 的 +//! 「本组接真控件只需改两个文件」这条口径，在语言行上**仍然是两个文件**。 + +use super::super::general; +use unlucky_design::icons::IconKind; +use unlucky_i18n::LangChoice; +use unlucky_i18n::{Key, Lang}; + +/// 这一组的**静态演示行**：语言（M106）与主题（M229）都已经换成真控件，所以只剩两行。 +/// +/// 抓得住：①四条线并行合并时把别人的行粘到本文件；②语言/主题被「顺手」加回静态表—— +/// 那等于把用户看到的假值又写回去（它们的值必须跟着语言/档位变，静态表做不到）。 +/// 抓不住：真控件画出来长什么样（那是截图验收的事，见 `DevDocs/artifacts/m229/`）。 +#[test] +fn the_general_group_keeps_only_the_two_rows_without_a_backend() { + let rows: Vec<(&str, &str)> = general::GROUP.rows.to_vec(); + assert_eq!( + rows, + vec![ + ("Startup page", "Instances"), + ("Close button", "Exit to tray") + ] + ); +} + +/// **M168（D28 后半）**：中文字体下载状态行的四种状态都得有话说，且两套目录都不许 `⟪missing⟫`。 +/// +/// 抓得住：①只画「下载成功」一种（失败的用户会以为程序坏了）；②失败态的文案写成「保持英文」 +/// （D28 的实际行为是**继续用系统字体**，界面语言不变）；③占位符没被替换（用户会看到 `{family}`）； +/// ④新 key 只进了英文表（中文界面上出现 `⟪missing⟫`）。 +/// 抓不住：真下载时的样子（那要联网）、字体有没有真的出字（截图 + 真机，见报告）。 +#[test] +fn the_font_status_row_speaks_in_four_states_and_two_languages() { + use crate::fonts::install::{CjkInstall, FetchClass}; + + let states = [ + CjkInstall::Downloading { bytes: 17_772_300 }, + CjkInstall::Ready { + family: "Noto Sans SC".to_owned(), + from_cache: true, + }, + CjkInstall::Failed { + class: FetchClass::Network, + message: "timeout".to_owned(), + }, + CjkInstall::System { + family: "Microsoft YaHei".to_owned(), + }, + CjkInstall::NotNeeded, + CjkInstall::Unprobeable, + CjkInstall::Unknown, + ]; + + for lang in Lang::ALL { + let catalog = lang.catalog(); + assert!( + catalog.get(Key::FontCjkStatusLabel).is_some(), + "{} 目录里缺中文字体那一行的标签", + lang.tag() + ); + for state in &states { + let (value, hint) = general::font_status(&catalog, state); + assert!(!value.is_empty(), "{state:?} 没话说"); + assert!(!value.contains('{'), "{state:?} 占位符没替换：{value}"); + assert!( + !value.contains(unlucky_i18n::catalog::MISSING), + "{state:?} 在 {} 目录里缺译：{value}", + lang.tag() + ); + if let Some(hint) = hint { + assert!(!hint.contains('{'), "{state:?} 的提示没替换：{hint}"); + } + } + } + + // 失败态必须说清三类原因之一（而不是一句「失败了」）。 + let zh = Lang::ZhCn.catalog(); + for (class, reason) in [ + (FetchClass::Network, "网络不通"), + (FetchClass::Integrity, "镜像内容校验不通过"), + (FetchClass::Disk, "写不进数据目录"), + ] { + let (value, _) = general::font_status( + &zh, + &CjkInstall::Failed { + class, + message: "x".to_owned(), + }, + ); + assert!(value.contains(reason), "失败原因没进文案：{value}"); + } + + // 下载中写的是**真实**字节数（17 772 300 B → 16.9 MiB），不是假百分比。 + let (value, _) = general::font_status(&zh, &CjkInstall::Downloading { bytes: 17_772_300 }); + assert!( + value.contains("16.9 MB"), + "17 772 300 B ≈ 16.9 MiB：{value}" + ); + assert!(!value.contains('%'), "没有真进度就不许写百分比：{value}"); +} + +/// 左列图标（`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` 那个槽位只拿到 `States` 与**生效语言**（`Lang`，M179）——装不下「当前语言档位」。 +/// 谁把语言行塞进 `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" + ); +} + +/// **M188：日志文件夹那一行**的文案必须与实现一致（用户投诉「找不到崩溃日志」的直接判据）。 +/// +/// 抓得住：①文案里的路径写错（写成 `data/logs`、`cache/game`）；②滚动上限与 +/// `core::launch::launcher_log::MAX_BYTES` 脱钩（文案说 1 MiB、实现改成 4 MiB）； +/// ③旧目录被静默改成「已迁移」（那会让用户以为旧日志没了）； +/// ④某条 key 只进了英文表（中文界面上是 `⟪missing⟫`）。 +/// 抓不住：界面画出来长什么样（截图验收管那一层）。 +#[test] +fn the_logs_row_names_the_real_paths_and_the_real_limit() { + use unlucky_core::launch::launcher_log; + use unlucky_core::platform::layout::{LauncherLayout, GAME_LOG_DIR, LOGS_DIR}; + + // 实现侧的真值：分区名与上限都只从 core 来。 + assert_eq!(LOGS_DIR, "logs"); + assert_eq!(GAME_LOG_DIR, "game"); + assert_eq!(launcher_log::MAX_BYTES, 1024 * 1024, "文案说 1 MiB"); + let layout = LauncherLayout::new(std::path::Path::new("/tmp/ull-home")); + assert_eq!( + layout.game_logs(), + std::path::Path::new("/tmp/ull-home/logs/game") + ); + + for lang in Lang::ALL { + let catalog = lang.catalog(); + let hint = catalog.text(Key::SettingsLogsFolderHint); + for needle in [ + "launcher.log", + "1 MiB", + &format!("{LOGS_DIR}/{GAME_LOG_DIR}/"), + "data/agent/sessions", + ] { + assert!( + hint.contains(needle), + "{} 缺 `{needle}`：{hint}", + lang.tag() + ); + } + assert!(!hint.contains('⟪'), "{} 目录里缺词：{hint}", lang.tag()); + assert!( + !catalog.text(Key::SettingsLogsFolder).contains('⟪'), + "{} 缺「日志文件夹」：{}", + lang.tag(), + catalog.text(Key::SettingsLogsFolder) + ); + assert!(!catalog.text(Key::SettingsLogsCopy).contains('⟪')); + assert!(!catalog.text(Key::SettingsLogsUnknown).contains('⟪')); + } +} 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..8e6d8c7 --- /dev/null +++ b/crates/app-iced/src/pages/settings/tests/java_section.rs @@ -0,0 +1,52 @@ +//! 「Java」分组自己的断言（M100 起归 java 线；M175 重写）。 +//! +//! M101 的三条里有两条在 M175 换掉了： +//! +//! | 旧断言 | M175 之后 | +//! |---|---| +//! | `the_java_group_shows_runtime_memory_and_jvm_arguments`（逐字钉住 `Temurin 21.0.4` / `4 GiB`） | 换成「演示行必须是空的」——那三行假数据正是用户实测投诉的源头 | +//! | `the_java_group_is_still_demo_rows`（断言 `body.is_none()`） | 保留（`body` 仍是 `None`：本组走按下标分发，见 `settings/java.rs` 的文件头） | +//! | `the_java_group_keeps_the_folder_icon_from_the_visual_review` | 不动 | +//! +//! 真数据源的断言在 `pages/settings/java/tests.rs`（扫描 / 校验 / 落盘 / 真命令行）， +//! 这里只守「左列那一格」——两处的分工与 M100 的 section 划分一致。 + +use super::super::java; +use unlucky_design::icons::IconKind; + +/// 这一组**不再有演示行**：三个假值（运行时 / 内存 / JVM 参数）已经换成真控件。 +/// +/// 抓得住：谁把演示行加回来（那会让 harness 路径又画出一份「看起来像真检测」的假数据）； +/// 也抓得住「接真控件却把 `rows` 留着」这种半吊子状态。 +/// 抓不住：真控件里画了什么（那是 `pages/settings/java/tests.rs` 的事）。 +#[test] +fn the_java_group_has_no_demo_rows_left() { + assert!( + java::GROUP.rows.is_empty(), + "Java 组不该再有演示行（真值来自扫描 / 手动路径 / launcher.json）：{:?}", + java::GROUP.rows + ); +} + +/// 左列图标必须是 `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); +} + +/// `body` 槽位仍是 `None`：本组靠 `settings/mod.rs` 的按下标分发（[`java::JAVA_GROUP`]）画正文。 +/// +/// 抓得住：谁把 `body: Some(..)` 挂上来（M179 之后槽位自带 `Lang`，所以「挂了 body 却没语言」 +/// 这种漂移不再可能——挂上来就必然拿到语言；这条守的是**分发形状**别变）。 +/// 抓不住：分发那一行本身有没有被删（`settings/mod.rs` 的 `form` 里有 `else if`；删了这组就空白）。 +#[test] +fn the_java_group_is_dispatched_by_index_not_by_body() { + assert!( + java::GROUP.body.is_none(), + "Java 组走按下标分发（要 Lang），body 必须保持 None" + ); +} diff --git a/crates/app-iced/src/pages/settings/tests/java_shot.rs b/crates/app-iced/src/pages/settings/tests/java_shot.rs new file mode 100644 index 0000000..ca61c24 --- /dev/null +++ b/crates/app-iced/src/pages/settings/tests/java_shot.rs @@ -0,0 +1,244 @@ +//! 「Java」卡片里的**禁用控件叠的是卡底**——页面级**像素**判据（M237）。 +//! +//! ## 为什么非要从页面量 +//! +//! `interaction::disabled::tests` 能证明「`Base` 传对了，合成就是对的」，`buttons::tests::base` +//! 能证明「`Button::base` 接到了样式闭包」——两条都**不**证明页面那天真的把 `frame::BASE` 传下去了 +//! （M229 的教训：参数在、语义在，8 个调用点全传死 `Role::Surface`）。只有页面自己的像素能证明 +//! 「这一屏里的禁用按钮是叠在卡底上画的」。 +//! +//! ## 量什么 +//! +//! `ULL_JAVA_STATE=scanning` 那一格里有一颗**禁用**的 Filled 按钮（「立即扫描」；「保存」同样是 +//! 禁用态，但在这张卡的下半段、1180×760 的一帧里落在折叠线以下，量不到）， +//! 它住在 `frame::card` 里（卡底 = `MaterialLayer::Card` = `SurfaceContainerLow`）。 +//! 禁用容器 = `OnSurface` @10% 叠在底上，于是「叠卡底」与「叠画布」是**两个不同的逐位值** +//! （实测的 8 位 RGB，十进制写在这里——色值十六进制字面量在源码里是禁的，见 +//! `tests/no_hardcoded_tokens.rs`）： +//! +//! | 板 | 叠画布（`Base::CANVAS`） | 叠卡底（`frame::BASE`） | 逐位差 | +//! |---|---|---|---| +//! | Silver（浅） | (226, 226, 227) | (221, 221, 222) | 5/255 | +//! | Ink（深） | (37, 43, 36) | (40, 45, 40) | 3/255 | +//! +//! 差得这么小正是**必须逐位匹配**的理由：肉眼（以及 `±10` 容差的扫描器）分不出这两档， +//! 而「叠错层」这件事本身是确定的。两个值都在测试里**现算** +//! （`interaction::disabled_button_colors`），不写死——换板 / 改令牌时判据跟着走； +//! 上表只是给人读的量测记录。 +//! +//! ## 跑法（1180×760 @1.0，`--software-renderer`） +//! +//! ```text +//! EXE=${CARGO_TARGET_DIR:-target}/debug/unlucky-launcher-iced +//! OUT=${CARGO_TARGET_DIR:-target}/m237 && mkdir -p "$OUT" +//! +//! ULL_START_ROUTE=settings ULL_SETTINGS_GROUP=2 ULL_JAVA_STATE=scanning \ +//! $EXE --software-renderer --scale-factor=1 \ +//! --screenshot "$OUT/java-light.png" --screenshot-theme=light +//! ULL_M237_JAVA_SHOT="$OUT/java-light.png" cargo test -p unlucky-app-iced java_shot +//! ``` +//! +//! `ULL_SETTINGS_GROUP=2` 是「Java」组（`settings::java::JAVA_GROUP`）；不给就画出 General 组， +//! 那张图上没有禁用填充按钮，判据会拿不到样本并**大声报出来**（不是静默通过）。 +//! +//! ## CI 上这条判据是**跳过**的（复审 P1-1） +//! +//! `.github/workflows/ci.yml` 的 test 作业在 ubuntu 与 windows 上都跑 +//! `cargo test --workspace --all-targets`，而**出图步骤只给 `options_shot` 备了四张图** +//! （`ULL_DL_*_SHOT`，Windows 一条）。本判据要的这张 Java 图**不在出图清单里** +//! （`grep -r ULL_M237 .github/` 零命中）⇒ 在 CI 上缺图是**预期**，实现里因此**跳过而不是失败** +//! （见 [`not_fed`]：初版写成「CI 就 panic」，`CI=true` 实测 exit 101，一合就红）。 +//! +//! 要让它真的进 CI 守门（跨 scope，塔另排）：① ci.yml 加一条 `if: runner.os == 'Windows'` 的 +//! 出图步骤（命令见上面的「跑法」）；② 把 `ULL_M237_JAVA_SHOT` 写进 `$GITHUB_ENV`； +//! ③ 把 `not_fed` 里那条 `eprintln!` 换成 `assert!(!(cfg!(windows) && in_ci()), …)` +//! ——与 `pages/download/tests/options_shot/feed.rs::not_fed`（`:104-124`）同一口径。 +//! +//! ## 抓得住 / 抓不住 +//! +//! - 抓得住：① 页面调用点漏了 `.base(..)`（回落到 `Base::CANVAS`）——卡区里会出现「叠画布」档、 +//! 「叠卡底」档消失；② `frame::BASE` 被改成别的角色（判据跟着 `BASE` 走，于是与像素对不上）； +//! ③ 出图通道换了组 / 换了主题（判据先用卡底色**认出**板，认不出就红）。 +//! - 抓不住：① 面板 α < 1 的 GPU 档（本判据读的是 tiny-skia 的图，α 恒 1）；② 卡外的控件 +//! （判据只看卡区）；③ 具体是哪一颗按钮变成了卡底（只数颜色总量，不定位控件）。 + +use unlucky_design::color::SchemeFlavor; +use unlucky_design::typography::Platform; + +use crate::app::components::interaction::{self, Base}; +use crate::pages::frame; +use crate::theme::{Families, Ui}; + +const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", +}; + +/// 出图路径（判据的输入）。 +const SHOT_ENV: &str = "ULL_M237_JAVA_SHOT"; +/// 卡区里「叠卡底」的禁用容器像素下限（两颗 40 高的药丸，扣掉字形与圆角后实测 ≈3100）。 +const MIN_HITS: usize = 1000; +/// 「正确档 : 错误档」的最小倍数（抗锯齿会在边缘撞上另一档的精确值，实测个位到十几像素）。 +const STRAY_RATIO: usize = 10; +/// 卡区的下限（一张 400+ 宽的卡，实测 ≈32 万像素）——低于它说明这一屏根本没有卡。 +const MIN_CARD_PX: usize = 50_000; + +fn ui(flavor: SchemeFlavor) -> Ui { + Ui::with_platform(flavor, Platform::Windows, FAMILIES) +} + +/// iced 颜色 → 8 位三元组（与 `to_iced` 同一条口径：`f32` 0..1 四舍五入回 0..255）。 +fn rgb(color: iced::Color) -> [u8; 3] { + let byte = |channel: f32| (channel * 255.0).round().clamp(0.0, 255.0) as u8; + [byte(color.r), byte(color.g), byte(color.b)] +} + +/// 一张 RGB 图（只留本判据要的两件事：尺寸 + 取点）。 +struct Shot { + width: usize, + height: usize, + pixels: Vec<[u8; 3]>, +} + +impl Shot { + fn load(path: &std::path::Path) -> Self { + let bytes = std::fs::read(path).expect("读截图"); + let image = image::load_from_memory(&bytes).expect("解 PNG").to_rgb8(); + let (width, height) = (image.width() as usize, image.height() as usize); + Self { + width, + height, + pixels: image.pixels().map(|pixel| pixel.0).collect(), + } + } + + fn at(&self, x: usize, y: usize) -> [u8; 3] { + self.pixels[y * self.width + x] + } + + /// 逐位相等的像素数（`±10` 容差在这里没用：两档底只差 5 个 RGB 单位）。 + fn count(&self, color: [u8; 3]) -> usize { + self.pixels.iter().filter(|pixel| **pixel == color).count() + } + + /// 某颜色像素的外接矩形 `(x0, y0, x1, y1)`（闭区间），一个都没有时 `None`。 + fn bbox(&self, color: [u8; 3]) -> Option<(usize, usize, usize, usize)> { + let mut found = None; + for y in 0..self.height { + for x in 0..self.width { + if self.at(x, y) == color { + let (x0, y0, x1, y1) = found.unwrap_or((x, y, x, y)); + found = Some((x0.min(x), y0.min(y), x1.max(x), y1.max(y))); + } + } + } + found + } + + /// 矩形内的逐位相等像素数。 + fn count_in(&self, color: [u8; 3], rect: (usize, usize, usize, usize)) -> usize { + let (x0, y0, x1, y1) = rect; + (y0..=y1.min(self.height - 1)) + .map(|y| { + (x0..=x1.min(self.width - 1)) + .filter(|x| self.at(*x, y) == color) + .count() + }) + .sum() + } +} + +/// 按**卡底色**认出这张图是哪块板（认不出 = 这一屏没有卡 / 主题对不上，直接红）。 +fn flavor_of(shot: &Shot) -> SchemeFlavor { + let mut candidates = Vec::new(); + for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] { + let card = rgb(ui(flavor).color(frame::BASE.role())); + let hits = shot.count(card); + if hits >= MIN_CARD_PX { + candidates.push((flavor, card, hits)); + } + } + assert_eq!( + candidates.len(), + 1, + "这一屏里「卡底」色的像素必须恰好落在一种板上，实测 {candidates:?}：\ + 检查出图命令是否带了 `--screenshot-theme` 与 `ULL_SETTINGS_GROUP=2`" + ); + candidates[0].0 +} + +/// 没喂图时的统一裁决：**一律响亮地跳过**，绝不 panic。 +/// +/// ## 为什么这里不能照 `options_shot/feed.rs` 那样「CI 就硬失败」（复审 P1-1） +/// +/// `options_shot` 那条硬失败（`feed.rs:104-124` 的 `!(cfg!(windows) && in_ci())`）成立的前提是 +/// `.github/workflows/ci.yml` 的 test 作业**真的**在 Windows 上出那四张图、并把 `ULL_DL_*_SHOT` +/// 写进 `$GITHUB_ENV`（`ci.yml:92-123`）。本判据的图**不在任何出图清单里** +/// （`grep -r ULL_M237 .github/` 零命中），而 `cargo test --workspace --all-targets` 在 ubuntu 与 +/// windows 两个 runner 上都跑 ⇒ 照抄那条口径会让**每个 PR 一亮红**：实测 +/// `CI=true cargo test -p unlucky-app-iced --lib java_shot` 会 panic（初版就是这么错的）。 +/// +/// ## 要在 CI 上真的守门（跨 scope，由塔另排） +/// +/// 1. `ci.yml` 加一条 `if: runner.os == 'Windows'` 的出图步骤（命令见本文件模块文档的「跑法」）； +/// 2. 把 `ULL_M237_JAVA_SHOT` 写进 `$GITHUB_ENV`（与 `ULL_DL_*_SHOT` 同一条路）； +/// 3. 那时把本函数末尾那条 `eprintln!` 换成 +/// `assert!(!(cfg!(windows) && in_ci()), "守门未喂图：{SHOT_ENV} 没设 …")` +/// —— 与 `options_shot/feed.rs::not_fed` 同一口径：**只有「会出图的平台 + CI」才硬失败**， +/// 别的平台缺图是预期。 +fn not_fed() { + let ci = std::env::var_os("CI").is_some_and(|value| !value.is_empty()); + eprintln!("[pages] 页面级像素判据未喂图：{SHOT_ENV} 没设，跳过（跑法见本文件模块文档）。"); + if ci { + eprintln!( + "[pages] 当前是 CI：本仓 CI 不出这张图（ci.yml 只给 options_shot 注入 ULL_DL_*_SHOT），\ + 所以这里跳过是**预期**，不是漏跑。让它守门的步骤见 not_fed 的文档。" + ); + } +} + +#[test] +fn the_java_card_composites_disabled_controls_over_its_own_base() { + let Some(path) = std::env::var_os(SHOT_ENV).filter(|value| !value.is_empty()) else { + not_fed(); + return; + }; + + let shot = Shot::load(std::path::Path::new(&path)); + let flavor = flavor_of(&shot); + let ui = ui(flavor); + + let over_card = rgb(interaction::disabled_button_colors(&ui, frame::BASE).0); + let over_canvas = rgb(interaction::disabled_button_colors(&ui, Base::CANVAS).0); + assert_ne!( + over_card, over_canvas, + "{flavor:?}: 叠卡底与叠画布的禁用容器算出来一样 —— 判据自己立不住" + ); + + // 卡区 = 卡底色像素的外接矩形（卡是这一屏最大的同色块） + let card_color = rgb(ui.color(frame::BASE.role())); + let rect = shot + .bbox(card_color) + .unwrap_or_else(|| panic!("{flavor:?}: 图里找不到卡底色 {card_color:?}")); + + let hits = shot.count_in(over_card, rect); + let stray = shot.count_in(over_canvas, rect); + + eprintln!( + "[pages] OK flavor={flavor:?} 卡区 {rect:?}：叠卡底 {over_card:?} {hits} px · \ + 叠画布 {over_canvas:?} {stray} px" + ); + + assert!( + hits >= MIN_HITS, + "{flavor:?}: 卡区里「叠 {:?}」的禁用容器只有 {hits} px（应 ≥{MIN_HITS}）—— \ + 卡片里的禁用控件没把 `frame::BASE` 传下去（还在按画布合成）", + frame::BASE.role() + ); + assert!( + hits > stray * STRAY_RATIO, + "{flavor:?}: 卡区里「叠卡底」{hits} px，而「叠画布」{stray} px（要求前者 ≥ 后者 ×{STRAY_RATIO}）—— \ + 卡区里仍有一部分禁用控件按 `Role::Surface` 合成" + ); +} 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..097d7ed --- /dev/null +++ b/crates/app-iced/src/pages/settings/tests/mod.rs @@ -0,0 +1,229 @@ +//! 设置页的**跨 section** 守门测试（M100：跨 section 的留在这里，section 自己的断言**新增**在 +//! `tests/
_section.rs`）。 +//! +//! ## 为什么这里只剩「跨 section」的断言 +//! +//! 设置页正文接下来由四条线并行接（java / download / language+appearance / ai+about）。每条线要能 +//! **只改自己的测试**就跑通，所以「某一组自己的行文案 / 图标 / body 现状」一律放在 +//! `tests/
_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; +mod java_shot; +mod scroll_fit; +mod update_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、又没有分发」 +/// 正是这条要抓的。 +/// +/// M175 起 Java 组的 `rows` 是**空**的：它那三行演示值（`Temurin 21.0.4` / `4 GiB` / +/// `Automatic`）正是用户实测投诉的假数据源，真控件接上之后演示行就删干净了。所以判据从 +/// 「必须有 rows」放宽成「必须有 rows **或** 有别的分发路径」——按下标分发的那几组 +/// （general / update / assistant / java）在 `settings/mod.rs` 的 `form` 里各有 `else if`， +/// 本断言只对「既没有 rows 又不在这张名单里」的组报错。 +#[test] +fn every_group_has_a_name_icon_and_rows() { + assert!(GROUPS.len() >= 3); + assert!(SELECTED < GROUPS.len()); + // 按下标分发（`settings/mod.rs` 的 `form`）：这些组的正文不在 `Group.rows` 里。 + const INDEX_DISPATCHED: [&str; 4] = ["General", "Updates", "Assistant", "Java"]; + for group in &GROUPS { + assert!(!group.name.is_empty()); + assert!(!group.icon.icon().path.is_empty(), "{} 缺图标", group.name); + assert!( + !group.rows.is_empty() || INDEX_DISPATCHED.contains(&group.name), + "{} 既没有设置行，也不在按下标分发的名单里", + 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", + "Updates", + // M174：助手（AI）配置只追加在末尾 + "Assistant", + ] + ); +} + +/// M101 r2：`settings/mod.rs` 里**不许出现任何一组的 `State` 类型**（r1 复审 P1 的判据钉在这里）。 +/// +/// 抓得住：谁把状态漏斗拆回去——让 `view` / `form` 直接收 `appearance::State` 或某一组的 `State` +/// （那正是四条线「加一个字段就要改本文件」的形状，本次复审要求修掉的就是它）。 +/// 抓不住：各组的**字段**（那些活在各组自己的文件里，本文件本来就不该知道，也就没有可断言的东西）。 +/// +/// **M106 的例外要读清楚**：General 已经接了真控件（语言行），但它**不走 `Group.body`**—— +/// 那个槽位的签名是 `fn(&Ui, States, Lang) -> Option`（`Lang` 是 M179 加的）， +/// `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(), + 6, + "四条填页线 + M159 的更新组 + M174 的助手组" + ); + assert!(SELECTED < GROUPS.len(), "演示下标仍在范围内"); +} diff --git a/crates/app-iced/src/pages/settings/tests/scroll_fit.rs b/crates/app-iced/src/pages/settings/tests/scroll_fit.rs new file mode 100644 index 0000000..2cf8ec9 --- /dev/null +++ b/crates/app-iced/src/pages/settings/tests/scroll_fit.rs @@ -0,0 +1,130 @@ +//! M173：设置页表单列的**滚动条槽**（滚动条并排，不压内容）。 +//! +//! 这里守的是整页级别的数值契约，不是「哪一组有哪些行」——所以它不属于任何 section 文件。 +//! +//! ## 怎么量 +//! +//! iced 的控件树支持在测试里真跑布局：`iced_core` 在 debug 构建下给 `()` 实现了全套 `Renderer` +//! trait（`iced_core-0.14.0/src/renderer/null.rs`），于是 `frame::scroll::<()>(…)` 返回的 +//! `Element<_, Message, Theme, ()>` 能被 `Widget::layout` 量出**真的**子节点尺寸。不需要开窗， +//! 也不需要 GPU——这是「数值断言，不是看图」的落点。 +//! +//! 节点树（`iced_core/src/layout.rs:201`：`padded` 恒为「自己 + 一个子节点」）： +//! +//! ```text +//! scrollable → [槽容器（Fill，右内边距 = 槽宽） → [内容]] +//! ``` +//! +//! ## 抓什么 / 抓不住什么 +//! +//! 抓得住：内容右侧真的留出了「轨宽 + 两侧 margin」的槽；长/短页面（出/不出滑块）内容宽度与左 +//! 边界**逐项相同**；把 `app::components::scroll` 的 padding 改回 0，本文件立刻红。 +//! 抓不住：滑块画在槽里的**像素**位置（那由 `pages/settings` 的出图与 iced 自己的 `Rail::new` +//! 公式担保，见 `src/components/scroll.rs` 文档里的源码行号）。 + +use iced::advanced::layout::Limits; +use iced::advanced::widget::Tree; +use iced::widget::{container, space}; +use iced::{Element, Length, Rectangle, Size, Theme}; +use unlucky_design::color::SchemeFlavor; +use unlucky_design::typography::Platform; + +use super::super::frame; +use super::super::frame::{SCROLLBAR_MARGIN, SCROLLBAR_WIDTH}; +use crate::pages::Message; +use crate::theme::{Families, Ui}; + +/// 设置页表单列宽：`frame_metrics` 的 `column`（= `measure_cap_px()`，1180 与 880 窗口下都是它）。 +const COLUMN: f32 = 424.0; +/// 视口高（1180×760 减去标题栏 / 页头 / 上下页边距之后的量级；只要求「长页 > 它」「短页 < 它」）。 +const VIEWPORT_HEIGHT: f32 = 600.0; +/// 长页面（正文远超视口 ⇒ 一定出滑块）。 +const LONG: f32 = 4000.0; +/// 短页面（正文装得下 ⇒ 一定不出滑块）。 +const SHORT: f32 = 120.0; + +const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", +}; + +fn ui() -> Ui { + Ui::with_platform(SchemeFlavor::Light, Platform::Windows, FAMILIES) +} + +/// 滚动条槽宽（dp）：轨道 + 两侧留白，与 iced 的 `total_scrollbar_width` 同口径。 +fn slot() -> f32 { + SCROLLBAR_WIDTH + 2.0 * SCROLLBAR_MARGIN +} + +/// 真跑一遍布局，返回 (槽容器, 内容) 两个矩形。 +fn laid_out(content_height: f32) -> (Rectangle, Rectangle) { + let ui = ui(); + + let filler: Element<'_, Message, Theme, ()> = container(space()) + .width(Length::Fill) + .height(Length::Fixed(content_height)) + .into(); + + // 走的是**产品那条** `frame::scroll`（泛型只为换成 `()` 渲染器，几何一字不改）。 + let mut element = frame::scroll::<()>(&ui, filler); + let mut tree = Tree::new(element.as_widget()); + + let node = element.as_widget_mut().layout( + &mut tree, + &(), + &Limits::new(Size::ZERO, Size::new(COLUMN, VIEWPORT_HEIGHT)), + ); + + let gutter = node.children()[0].bounds(); + let content = node.children()[0].children()[0].bounds(); + + (gutter, content) +} + +/// **本条 mission 的核心数值断言**：内容可用宽度 = 容器宽 − 滚动条占位。 +#[test] +fn the_form_column_reserves_a_rail_slot_beside_the_content() { + let (gutter, content) = laid_out(LONG); + + assert_eq!(slot(), 10.0, "6 轨宽 + 2×2 内缩 = 10dp 的槽"); + assert_eq!(gutter.width, COLUMN, "槽容器自身仍是满宽"); + assert_eq!( + content.width, + COLUMN - slot(), + "内容可用宽度必须是「容器宽 − 滚动条槽」，否则轨道就压在内容右缘上" + ); + assert_eq!(content.width, 414.0, "424 − 10 = 414"); +} + +/// 长页面（出滑块）与短页面（不出滑块）——内容宽度与左边界必须**逐项相同**。 +/// +/// 这是 M173 要求的「两张对照图 + 数值」里的数值那一半：只给一张出滑块的图说明不了「滑块出现时 +/// 内容会不会跳」，必须两态同框比。 +#[test] +fn the_content_does_not_jump_between_a_long_and_a_short_page() { + let (long_gutter, long) = laid_out(LONG); + let (short_gutter, short) = laid_out(SHORT); + + assert_eq!(long_gutter.x, short_gutter.x, "槽容器的左边界不许变"); + assert_eq!(long_gutter.width, short_gutter.width, "槽容器的宽度不许变"); + assert_eq!(long.x, short.x, "左边界不许横跳"); + assert_eq!(long.width, short.width, "宽度不许横跳"); + assert_eq!(short.x, 0.0, "槽只占右侧：左侧内边距为 0"); + assert_eq!( + short.x + short.width, + COLUMN - slot(), + "内容右缘 = 轨道的左缘（再往右 10dp 才是轨道自己）" + ); +} + +/// 反证：`content_width` 这条纯量与实际布局量出来的是同一个数（两处不许各算一套）。 +#[test] +fn the_layout_agrees_with_the_pure_quantity() { + let (_, content) = laid_out(LONG); + assert_eq!( + content.width, + crate::app::components::scroll::content_width(COLUMN, slot()) + ); +} diff --git a/crates/app-iced/src/pages/settings/tests/update_section.rs b/crates/app-iced/src/pages/settings/tests/update_section.rs new file mode 100644 index 0000000..ae21df8 --- /dev/null +++ b/crates/app-iced/src/pages/settings/tests/update_section.rs @@ -0,0 +1,207 @@ +//! 设置页「更新」分组（M159）的断言：注册表位置、四条状态各有各的句子。 +//! +//! 为什么只测「词表 + 判据」而不测控件：iced 的 `Element` 没有内省接口（`tests/mod.rs` 顶部那条 +//! 写过理由），上屏文本只能从**取词的那一个入口**取。这里守的是「四种结论的句子不是同一句」 +//! ——正是 mission 里「检查失败不等于已是最新」那条硬要求的最小可测形态。 + +use unlucky_i18n::{Catalog, Key, Lang}; + +use super::super::update::{GROUP as UPDATE_GROUP_META, UPDATE_GROUP}; +use super::super::{GROUPS, SELECTED}; +use crate::pages::update::UpdateStatus; +use crate::pages::{Screen, Update}; + +/// 更新组**下标固定为 4**：加组只追加不重排，插到它前面会让 `APPEARANCE_GROUP` / `GENERAL_GROUP` +/// 两个下标一起失效，也会把更新组自己的 `UPDATE_GROUP` 指到别人身上。 +/// +/// M174 之后它**不再是最后一组**（助手组追加在它后面）：这条断言因此从「len == 下标 + 1」 +/// 改成「下标 4 上就是更新组，且它是**倒数第二**组」——追加语义仍然成立，而「更新组被挤走」 +/// 照样会红。 +#[test] +fn the_update_group_sits_at_the_end_of_the_registry() { + assert_eq!(UPDATE_GROUP, 4, "更新组的下标不许变（加组只追加）"); + assert_eq!( + GROUPS.len(), + UPDATE_GROUP + 2, + "更新组之后只该有 M174 的助手组" + ); + assert_eq!(GROUPS[UPDATE_GROUP].name, UPDATE_GROUP_META.name); + assert_eq!(GROUPS[UPDATE_GROUP].name, "Updates"); + assert!(SELECTED < GROUPS.len()); +} + +/// 四种结论的句子**互不相同**，且「失败」那一句必须把原因带出来。 +/// +/// 抓得住：把「检查失败」写成「已是最新」（那是 mission 明令禁止的撒谎：断网时会说「你是最新」）。 +/// 抓不住：句子翻得顺不顺、颜色对不对（那是人读与截图的事）。 +#[test] +fn the_four_outcomes_read_differently() { + let catalog = Lang::ZhCn.catalog(); + let up_to_date = catalog.render(Key::SettingsUpdateUpToDate, &[("version", "0.2.2")]); + let available = catalog.render( + Key::SettingsUpdateAvailable, + &[("version", "0.2.3"), ("size", "21.0 MB")], + ); + let missing = catalog.render(Key::SettingsUpdateMissingArtifact, &[("version", "0.2.3")]); + let failed = catalog.render( + Key::SettingsUpdateFailed, + &[("reason", "取更新清单失败：连接被重置")], + ); + + let all = [&up_to_date, &available, &missing, &failed]; + for (index, left) in all.iter().enumerate() { + for right in all.iter().skip(index + 1) { + assert_ne!(left, right, "两条结论说的是同一句话：{left} / {right}"); + } + } + assert!( + failed.contains("连接被重置"), + "失败那一句必须带出原因，实际：{failed}" + ); + assert!( + !failed.contains("0.2.2"), + "失败那一句不该冒出当前版本号（读起来像「已是最新」）：{failed}" + ); +} + +/// 页面视图模型与 presenter 的判据同序：就位 > 进行中 > 失败（仅主动查） > 有新版本。 +/// +/// 两处各算一次（presenter 判据 + 页面视图），顺序必须一致，否则同一份状态在提示条与设置页上 +/// 会各说一套。这里只钉页面这一侧的顺序；presenter 那一侧在 `presenter` 的 `dto::update` 单测里。 +#[test] +fn the_banner_priority_is_ready_then_applying_then_failure_then_available() { + let mut update = Update { + current_version: "0.2.2".to_string(), + channel: "stable".to_string(), + auto_check: true, + status: UpdateStatus::Failed { + reason: "连不上".to_string(), + retryable: true, + }, + checked_at: String::new(), + applying: true, + ready: None, + skipped: None, + silent: false, + }; + assert!(matches!( + update.banner(), + Some(crate::pages::Banner::Applying) + )); + + update.applying = false; + assert!(matches!( + update.banner(), + Some(crate::pages::Banner::Failed { .. }) + )); + + update.status = UpdateStatus::Available { + version: "0.2.3".to_string(), + size: 1024, + notes: String::new(), + forced: false, + }; + assert!(matches!( + update.banner(), + Some(crate::pages::Banner::Available { .. }) + )); + + update.ready = Some("0.2.3".to_string()); + assert!(matches!( + update.banner(), + Some(crate::pages::Banner::Ready { .. }) + )); +} + +/// 演示模型里更新组能画（`pages_demo` 的 harness 路径）：`Model.update` 有默认值，不是 `None` 才画。 +#[test] +fn the_demo_model_carries_an_update_snapshot() { + let model = crate::pages::demo_model(Screen::Settings, 1180.0, 760.0); + assert_eq!(model.update, crate::pages::update::demo()); + assert!( + model.update.available().is_some(), + "演示快照要带一个可装的版本" + ); + // 其它页不掺演示更新状态（实例页/下载页的基线图不该多出一条提示条）。 + assert_eq!( + crate::pages::demo_model(Screen::Instances, 1180.0, 760.0).update, + Update::default() + ); + let catalog: Catalog = Lang::En.catalog(); + assert!(!catalog.text(Key::SettingsGroupUpdate).is_empty()); +} + +/// **忙碌时按钮禁用，且禁用态与状态行同源**（M161 收的债：以前点了没反应）。 +/// +/// 三条判据： +/// ① `Checking` / `applying` 时 `can_check()` 与 `can_apply()` 都是 false（按钮画成置灰）； +/// ② 这两态下设置页的状态行**必须**是「正在检查…」/「正在安装…」——否则用户看到一颗灰按钮 +/// 却没有任何解释； +/// ③ 结论回来（失败也算）之后恢回可点：超时/网络失败不许把按钮永久钉死。 +#[test] +fn the_buttons_are_disabled_exactly_while_something_is_running() { + use super::super::update::status_line; + + let catalog = Catalog::of(Lang::ZhCn); + let available = UpdateStatus::Available { + version: "0.2.3".to_string(), + size: 1024, + notes: String::new(), + forced: false, + }; + + // 静息：有候选 ⇒ 两颗按钮都能点。 + let idle = Update { + status: available.clone(), + ..Update::default() + }; + assert!(!idle.busy()); + assert!(idle.can_check(), "静息时「立即检查」可点"); + assert!(idle.can_apply(), "有候选且不忙 ⇒ 「下载并安装」可点"); + + // 正在查：两颗都置灰，状态行说「正在检查」。 + let checking = Update { + status: UpdateStatus::Checking, + ..idle.clone() + }; + assert!(checking.busy(), "Checking 就是忙碌"); + assert!(!checking.can_check(), "查的时候不许再点「立即检查」"); + assert!(!checking.can_apply(), "查的时候不许装（presenter 也拒）"); + assert_eq!( + status_line(catalog, &checking).0, + catalog.text(Key::SettingsUpdateChecking), + "灰按钮旁边必须有「正在检查…」这句话" + ); + + // 正在装：`applying` 也算忙碌（此时 status 可能仍是 Available）。 + let applying = Update { + applying: true, + ..idle.clone() + }; + assert!(applying.busy()); + assert!(!applying.can_apply(), "装的时候安装键置灰，不是消失"); + assert!(!applying.can_check(), "装的时候也不许再来一条检查"); + // 状态行在这一档也必须说「正在安装…」（复审 P2 附注：此前只有截图兜着）。 + assert_eq!( + super::super::update::status_text(catalog, &applying), + (catalog.text(Key::SettingsUpdateApplying).to_string(), false), + "applying 档的状态行必须是「正在安装…」且不是错误色" + ); + // 同一档的两句不许撞（「正在安装」≠「正在检查」）。 + assert_ne!( + catalog.text(Key::SettingsUpdateApplying), + catalog.text(Key::SettingsUpdateChecking) + ); + + // 结论回来（这里是最坏的结论：失败）⇒ 恢回可点。 + let failed = Update { + status: UpdateStatus::Failed { + reason: "连不上".to_string(), + retryable: true, + }, + ..Update::default() + }; + assert!(!failed.busy(), "失败 = 这一轮结束了"); + assert!(failed.can_check(), "失败之后必须能重试"); + assert!(!failed.can_apply(), "没有候选时安装键不可点"); +} diff --git a/crates/app-iced/src/pages/settings/update.rs b/crates/app-iced/src/pages/settings/update.rs new file mode 100644 index 0000000..98bdf78 --- /dev/null +++ b/crates/app-iced/src/pages/settings/update.rs @@ -0,0 +1,293 @@ +//! 设置页「更新」分组（M159）：当前版本 / 渠道 / 自动检查开关 / 立即检查 / 上次结果。 +//! +//! ## 为什么这一组不走 `Group.body` +//! +//! `Group.body` 的槽位拿的是 [`States`](super::States) 与**生效语言** `Lang`（M179 起），而更新状态 +//! 是 **presenter 快照**（`pages::Update`，不是某一组的字段、也不在 `States` 里），槽位装不下它。 +//! 与 M106 的语言行同一种情形：`settings/mod.rs` 按下标（[`UPDATE_GROUP`]）把 `settings::view` 的 +//! `update` 形参交给 [`body`]，`GROUP.body` 仍是 `None`。 +//! +//! 消息也**不**走 `GroupMessage`：更新动作是「跨页的一次性意图」（检查 / 下载安装 / 忽略 / +//! 重启），落点是 `app/update/update_action.rs`，`pages::Message::Update(UpdateAction)` 一支就够。 +//! 偏离已登记在本文件与 mission 报告里（与 M106 的 `Message::Language` 同一取舍：这两个都不是 +//! 「某一组的内部状态」，折进 `GroupMessage` 只会多一层没人用的转运）。 +//! +//! ## 四条状态行必须分开 +//! +//! 「已是最新」「有新版本」「没有本平台产物」「检查失败」是四种不同的结论（mission 硬要求： +//! 失败不许说成最新）。第四种一定要把原因摆出来（连不上 / 清单坏了 / 渠道不符）， +//! 否则用户只会看到一句「检查失败」而无从下手。 + +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, Lang}; +use unlucky_presenter::dto::human_bytes; + +use crate::app::components::buttons::{self, Button}; +use crate::app::components::selection::{chip, Chip}; + +use crate::pages::frame::text_role_owned; +use crate::pages::update::{Update, UpdateStatus}; +use crate::pages::Message; +use crate::pages::UpdateAction; +use crate::theme::Ui; + +use super::frame::{card, divider}; +use super::Group; + +/// 「更新」分组在 [`super::GROUPS`] 里的下标（**必须是最后一个**：加组只追加不重排）。 +pub(super) const UPDATE_GROUP: usize = 4; + +/// 更新分组（左列名固定英文：左列是导航，与导航轨同源，不进 catalog）。 +pub(super) const GROUP: Group = Group { + name: "Updates", + icon: IconKind::Download, + // 只给 harness / 窄窗「按组堆叠」路径用的演示行：产品路径走 [`body`]。 + rows: &[ + ("Current version", "0.2.2"), + ("Channel", "Stable"), + ("Check for updates on startup", "On"), + ], + body: None, +}; + +/// 渲染整组正文。 +pub(super) fn body<'a>(ui: &'a Ui, update: &'a Update, lang: Lang) -> Element<'a, Message> { + let catalog = lang.catalog(); + let mut stacked = column![].spacing(0.0).width(Length::Fill); + + stacked = stacked.push(info_row( + ui, + catalog.text(Key::SettingsUpdateCurrent), + update.current_version.clone(), + )); + stacked = stacked.push(divider(ui)); + stacked = stacked.push(info_row( + ui, + catalog.text(Key::SettingsUpdateChannel), + channel_label(catalog, &update.channel), + )); + stacked = stacked.push(divider(ui)); + stacked = stacked.push(auto_check_row(ui, catalog, update)); + stacked = stacked.push(divider(ui)); + stacked = stacked.push(status_block(ui, catalog, update)); + + card(ui, stacked) +} + +/// 渠道显示名：`stable` 走 key，其它渠道原样上屏（D50 现在只有 stable，但开 beta/alpha 时 +/// 页面不该跟着改——渠道是数据，不是写死的字面量）。 +fn channel_label(catalog: Catalog, channel: &str) -> String { + match channel { + "stable" => catalog.text(Key::SettingsUpdateChannelStable).to_string(), + other => other.to_string(), + } +} + +/// 「标签 + 值」一行（与 `frame::setting_row` 同一套排版，但值要在调用处现算）。 +fn info_row<'a>(ui: &'a Ui, label: &'a str, value: String) -> Element<'a, Message> { + let height = ui.metrics().control_height + Space::X2.dp(); + row![ + iced::widget::container(text_role_owned( + ui, + TypeRole::BodyMedium, + false, + label.to_string(), + ui.color(Role::OnSurface), + )) + .width(Length::Fill) + .align_y(Alignment::Center), + text_role_owned( + ui, + TypeRole::BodySmall, + false, + value, + ui.color(Role::OnSurfaceVariant), + ), + ] + .height(height) + .width(Length::Fill) + .align_y(Alignment::Center) + .into() +} + +/// 自动检查开关 + 「立即检查」按钮。 +/// +/// **忙碌时「立即检查」置灰**（M161）：此前它永远可点，而 presenter 的 `begin_check` 在 +/// inflight 时静默 `return None`——用户点了没反应，还以为启动器卡了。禁用态与状态行同源 +/// （同一个 [`Update::busy`]）：按钮灰着的时候，下面那句状态行一定是「正在检查…」/「正在安装…」。 +fn auto_check_row<'a>(ui: &'a Ui, catalog: Catalog, update: &Update) -> Element<'a, Message> { + let check_now = catalog.text(Key::SettingsUpdateCheckNow); + let check = if update.can_check() { + buttons::text( + ui, + Button::new(check_now, Message::Update(UpdateAction::CheckNow)), + ) + } else { + buttons::text(ui, Button::disabled(check_now)) + }; + row![ + chip( + ui, + Chip::filter( + catalog.text(Key::SettingsUpdateAutoCheck), + update.auto_check, + Message::Update(UpdateAction::SetAutoCheck(!update.auto_check)), + ), + ), + check, + ] + .spacing(ui.space(Space::X3)) + .width(Length::Fill) + .align_y(Alignment::Center) + .padding(iced::Padding::from([0.0_f32, 0.0])) + .into() +} + +/// 上次检查时间 + 结论 + （有候选时）下载按钮 + 说明摘要 + 一句校验提示。 +fn status_block<'a>(ui: &'a Ui, catalog: Catalog, update: &'a Update) -> Element<'a, Message> { + let mut block = column![].spacing(ui.space(Space::X2)).width(Length::Fill); + + let checked = if update.checked_at.trim().is_empty() { + catalog.text(Key::SettingsUpdateNever).to_string() + } else { + update.checked_at.clone() + }; + block = block.push(info_row( + ui, + catalog.text(Key::SettingsUpdateLastChecked), + checked, + )); + + // 下载/校验/替换期间先说这一句：设置页的按钮在这一刻也点不动（见下面 `applying` 分支）， + // 用户得知道「它正在干活」而不是「点了没反应」。 + let (text, error) = status_text(catalog, update); + let color = ui.color(if error { + Role::Error + } else { + Role::OnSurfaceVariant + }); + block = block.push(text_role_owned(ui, TypeRole::BodySmall, false, text, color)); + + if let Some((_version, _size, notes, forced)) = update.available() { + // 有候选就**永远画出**这一颗按钮：忙碌时置灰（`can_apply` = false），而不是整颗消失。 + // 消失会让人以为「装到一半的功能没了」；灰着 + 状态行那句「正在安装…」才说得清。 + let apply_label = catalog.text(Key::SettingsUpdateApply); + let apply = if update.can_apply() { + buttons::filled( + ui, + Button::new(apply_label, Message::Update(UpdateAction::Apply)), + ) + } else { + buttons::filled(ui, Button::disabled(apply_label)) + }; + let mut actions = row![apply] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Center); + if forced { + actions = actions.push(text_role_owned( + ui, + TypeRole::BodySmall, + false, + catalog.text(Key::SettingsUpdateForced).to_string(), + ui.color(Role::Error), + )); + } + block = block.push(actions); + if !notes.trim().is_empty() { + block = block.push(text_role_owned( + ui, + TypeRole::BodySmall, + false, + catalog.render(Key::SettingsUpdateNotes, &[("notes", notes.trim())]), + ui.color(Role::OnSurfaceVariant), + )); + } + } + + if let Some(version) = &update.ready { + block = block.push(text_role_owned( + ui, + TypeRole::BodySmall, + false, + catalog.render(Key::SettingsUpdateReady, &[("version", version)]), + ui.color(Role::OnSurface), + )); + block = block.push(buttons::tonal( + ui, + Button::new( + catalog.text(Key::UpdateBannerRestartNow), + Message::Update(UpdateAction::RestartNow), + ), + )); + } + + block = block.push(text_role_owned( + ui, + TypeRole::BodySmall, + false, + catalog.text(Key::SettingsUpdateHint).to_string(), + ui.color(Role::OnSurfaceVariant), + )); + + block.into() +} + +/// 状态行此刻那句话（**唯一**产地：`applying` 与四态都在这里分派）。 +/// +/// 拆成函数是为了可断言：`applying` 这一档此前只有截图兜着（复审 P2 附注）， +/// `Element` 没有内省接口，而上屏文本只能从**取词的那一个入口**取。 +pub(super) fn status_text(catalog: Catalog, update: &Update) -> (String, bool) { + if update.applying { + // 「正在下载/校验/替换」不是错误色（它只是在干活）。 + return (catalog.text(Key::SettingsUpdateApplying).to_string(), false); + } + status_line(catalog, update) +} + +/// 一条状态行（文案 + 是不是「错」那一类）。 +/// +/// 四种结论各写各的句子，**不共用**「已是最新」那句：失败/缺产物时那句就是撒谎。 +/// `pub(super)` 只为让 `settings/tests` 能断言「忙碌时状态行与按钮禁用态同源」。 +pub(super) fn status_line(catalog: Catalog, update: &Update) -> (String, bool) { + let (key, args, error) = match &update.status { + UpdateStatus::Idle => (Key::SettingsUpdateNever, Vec::new(), false), + UpdateStatus::Checking => (Key::SettingsUpdateChecking, Vec::new(), false), + UpdateStatus::UpToDate { latest } => { + let version = latest + .clone() + .unwrap_or_else(|| update.current_version.clone()); + ( + Key::SettingsUpdateUpToDate, + vec![("version", version)], + false, + ) + } + UpdateStatus::Available { version, size, .. } => ( + Key::SettingsUpdateAvailable, + vec![("version", version.clone()), ("size", human_bytes(*size))], + false, + ), + UpdateStatus::MissingArtifact { version } => ( + Key::SettingsUpdateMissingArtifact, + vec![("version", version.clone())], + true, + ), + UpdateStatus::Failed { reason, .. } => ( + Key::SettingsUpdateFailed, + vec![("reason", reason.clone())], + true, + ), + }; + + let args: Vec<(&str, &str)> = args + .iter() + .map(|(name, value)| (*name, value.as_str())) + .collect(); + (catalog.render(key, &args), error) +} diff --git a/crates/app-iced/src/pages/tests.rs b/crates/app-iced/src/pages/tests.rs new file mode 100644 index 0000000..a9f2a11 --- /dev/null +++ b/crates/app-iced/src/pages/tests.rs @@ -0,0 +1,389 @@ +//! 页面层的**数值判据**：M90 接真组件后，「M84 的版面约束一条没破」这件事在这里钉死。 +//! +//! 每条断言都注明了「抓得住什么 / 抓不住什么」——只测到纯函数，渲染真像素另见报告里的图与量测。 + +mod base_wiring; + +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(); + let form = demo_launch_form(); + for width in [1180.0, 900.0, 700.0] { + for screen in Screen::ALL { + let model = demo_model(screen, width, 760.0); + let _element: Element<'_, Message> = app(&ui, &model, &form); + } + } +} + +/// 空数据也要能构图（真实后端的「还没扫到实例」是常态，不能 panic）。 +#[test] +fn an_empty_snapshot_still_builds() { + let ui = ui(); + let form = demo_launch_form(); + for screen in Screen::ALL { + let model = Model::new(screen, 1180.0, 760.0, Some(screen.nav())); + let _element: Element<'_, Message> = app(&ui, &model, &form); + } +} + +/// 版面对照：同一页在 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, 760.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, 760.0); + assert!( + model.instances.rows.is_empty(), + "{} 不该带实例数据", + screen.slug() + ); + } +} diff --git a/crates/app-iced/src/pages/tests/base_wiring.rs b/crates/app-iced/src/pages/tests/base_wiring.rs new file mode 100644 index 0000000..0743b77 --- /dev/null +++ b/crates/app-iced/src/pages/tests/base_wiring.rs @@ -0,0 +1,132 @@ +//! 页面层**接线**守门：卡片里的控件有没有把 `frame::BASE` 传下去（M237）。 +//! +//! ## 为什么还要一条「数接线点」的判据 +//! +//! 像素判据（`pages/settings/tests/java_shot.rs`）只落在**一屏能拍到的**控件上。实例详情页的 +//! MODS / SAVES 两张卡在现有夹具下拍不到禁用控件：`ULL_MODS_FIXTURE` 把 `running` 写死成 +//! `false`（开关全是启用态），SAVES 的动作行在 1180×760 的折叠线以下。那几处接线于是**没有 +//! 任何渲染证据**能守——有人删掉一个 `.base(..)`，图和一整张像素判据都不会变。 +//! +//! 这里退一步，只数「每个文件里出现了几次接线调用」。它证明的是**接线还在**，不是「画对了」； +//! 真正的「叠的是哪一层底」由像素判据与 `interaction::disabled::tests` 两层负责。 +//! +//! 清单里有两种接线：**禁用态**（`Button::disabled` / `Switch::disabled` / `Chip::disabled`）与 +//! **hover / 选中状态层**（`Text`·`Outlined` 按钮、`ListItem` 行、手写 chip 的 `state_over`）。 +//! 像素判据只量到禁用态那一档（`pages/settings/tests/java_shot.rs` 的 Java 卡）， +//! 所以 `instances.rs`（列表行，复审 P2-1）这种**只有状态层**的接线只能靠这份计数守。 +//! +//! ## 抓得住 / 抓不住 +//! +//! - 抓得住：删掉 / 注释掉某个调用点的 `.base(..)`、或把整个文件的接线回退（数字掉一即红）。 +//! - 抓不住：① 传**错的**底（换成 `Base::CANVAS` 数字不变，只有像素判据能抓）； +//! ② 把接线搬进辅助函数（那是等价重构，改这里的数字并在提交信息里说明搬去了哪）； +//! ③ 新加的控件（新调用点没人接线时数字不会变——这条只守**已经签过的**那几处）。 +//! +//! ## 数字怎么来的 +//! +//! 每个文件里 `.base(` 的出现次数（`grep -o "\.base(" | wc -l`），三个手写样式的文件 +//! 数是 `BASE.role()`（它们不走组件的 `.base(..)`，而是把状态层直接叠在 `frame::BASE` 上）。 + +/// `(文件, 期望的接线次数)`：文件路径相对 `pages/`。 +const WIRED: [(&str, usize); 9] = [ + ("instances.rs", 1), + ("instances/mods.rs", 1), + ("instances/saves.rs", 2), + ("instances/launch_args.rs", 5), + ("logs/diagnostic.rs", 1), + ("settings/java/view.rs", 4), + ("settings/java/fields.rs", 7), + ("settings/java/prefs_view.rs", 8), + ("settings/java/download_view.rs", 5), +]; + +/// 手写样式（不走组件 `.base(..)`）的三处：状态层直接叠在 `frame::BASE.role()` 上。 +const ROLE_SITES: [(&str, usize); 3] = [ + ("settings/general.rs", 1), + ("settings/general/theme.rs", 1), + ("settings/logs_row.rs", 1), +]; + +/// 数**非注释行**里 `needle` 的出现次数。 +/// +/// 整行注释（`//` / `///` / `//!`）先剔掉：**把接线注释掉不算接线**，而「注释掉一行」恰恰是 +/// 最容易发生的回退。复审 r2 实测过：只按 `source.matches()` 数，注释掉 +/// `item.base(frame::BASE)` 之后本判据仍是绿的（注释里还留着 `.base(` 这四个字符）。 +fn count(haystack: &str, needle: &str) -> usize { + haystack + .lines() + .filter(|line| !line.trim_start().starts_with("//")) + .map(|line| line.matches(needle).count()) + .sum() +} + +#[test] +fn every_card_internal_control_site_still_passes_a_base() { + let sources: [(&str, &str); 12] = [ + ("instances.rs", include_str!("../instances.rs")), + ("instances/mods.rs", include_str!("../instances/mods.rs")), + ("instances/saves.rs", include_str!("../instances/saves.rs")), + ( + "instances/launch_args.rs", + include_str!("../instances/launch_args.rs"), + ), + ("logs/diagnostic.rs", include_str!("../logs/diagnostic.rs")), + ( + "settings/java/view.rs", + include_str!("../settings/java/view.rs"), + ), + ( + "settings/java/fields.rs", + include_str!("../settings/java/fields.rs"), + ), + ( + "settings/java/prefs_view.rs", + include_str!("../settings/java/prefs_view.rs"), + ), + ( + "settings/java/download_view.rs", + include_str!("../settings/java/download_view.rs"), + ), + ( + "settings/general.rs", + include_str!("../settings/general.rs"), + ), + ( + "settings/general/theme.rs", + include_str!("../settings/general/theme.rs"), + ), + ( + "settings/logs_row.rs", + include_str!("../settings/logs_row.rs"), + ), + ]; + + for (name, want) in WIRED { + let source = sources + .iter() + .find(|(file, _)| *file == name) + .map(|(_, source)| *source) + .unwrap_or_else(|| panic!("{name} 不在本判据的清单里（清单与文件对不上）")); + let got = count(source, ".base("); + assert_eq!( + got, want, + "{name}: `.base(..)` 出现 {got} 次，期望 {want} 次 —— 卡片内的控件必须把 \ + `frame::BASE` 传下去（`pages/frame/pieces.rs` 的 `BASE`）。\ + 如果你是把接线搬进了辅助函数（等价重构），把这里的数字跟着改并说明搬去了哪。" + ); + } + + for (name, want) in ROLE_SITES { + let source = sources + .iter() + .find(|(file, _)| *file == name) + .map(|(_, source)| *source) + .unwrap_or_else(|| panic!("{name} 不在本判据的清单里（清单与文件对不上）")); + let got = count(source, "BASE.role()"); + assert_eq!( + got, want, + "{name}: `BASE.role()` 出现 {got} 次，期望 {want} 次 —— 手写按钮的 hover / 禁用\ + 状态层必须叠在卡片底上（画布底会让它在卡里偏色，M237）" + ); + } +} diff --git a/crates/app-iced/src/pages/update.rs b/crates/app-iced/src/pages/update.rs new file mode 100644 index 0000000..92e02f6 --- /dev/null +++ b/crates/app-iced/src/pages/update.rs @@ -0,0 +1,368 @@ +//! 自更新（M159）的**页面视图模型**：只放「要画什么」。 +//! +//! 与 `presenter::dto::UpdateView` 的分工和本目录其它页一致（见 `pages/model.rs` 模块文档）： +//! DTO 是 IPC 契约（含 core 语义字段），这里是纯展示字段，于是页面可以用演示数据喂同一个渲染函数。 +//! 转换点只有一个：`app/view/update.rs`。 +//! +//! ## 为什么状态是「一个有载荷的枚举」 +//! +//! 「检查失败」与「已是最新」必须是两个变体（mission 硬要求）：把失败折叠成 +//! `UpToDate` 会让界面在断网时说「已是最新」，那是撒谎。`MissingArtifact`（有新版但没本平台产物） +//! 同理——它既不是「有新版本可装」，也不是「已是最新」。 + +/// 一次检查的结论（页面视图）。 +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub enum UpdateStatus { + /// 还没查过 + #[default] + Idle, + /// 正在查 + Checking, + /// 已是最新 + UpToDate { + /// 该渠道内的最高版本（`None` = 还没有任何发布） + latest: Option, + }, + /// 有可装的更新 + Available { + /// 新版本号 + version: String, + /// 包体字节数 + size: u64, + /// 更新说明（可能为空） + notes: String, + /// 是否强制 + forced: bool, + }, + /// 有更高版本，但没有本平台的产物 + MissingArtifact { + /// 那个版本 + version: String, + }, + /// 检查/应用失败（**不是**已是最新） + Failed { + /// 人话原因 + reason: String, + /// 换个时间再试是否可能变好 + retryable: bool, + }, +} + +/// 顶部提示条此刻的形态。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Banner<'a> { + /// 有新版本 + Available { + /// 新版本号 + version: &'a str, + /// 包体字节数 + size: u64, + /// 说明摘要 + notes: &'a str, + }, + /// 正在下载/校验 + Applying, + /// 已就位，等重启 + Ready { + /// 新版本号 + version: &'a str, + }, + /// 失败（只在用户主动查之后出现） + Failed { + /// 人话原因 + reason: &'a str, + /// 是否可重试 + retryable: bool, + }, +} + +/// 更新页 / 提示条的全部展示状态。 +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub struct Update { + /// 当前版本 + pub current_version: String, + /// 渠道（`stable`） + pub channel: String, + /// 启动时是否静默检查 + pub auto_check: bool, + /// 检查结论 + pub status: UpdateStatus, + /// 上次检查时间（空串 = 没查过） + pub checked_at: String, + /// 正在下载/校验/替换 + pub applying: bool, + /// 已就位的新版本号（`None` = 没有） + pub ready: Option, + /// 用户点了「忽略这个版本」时记下的**版本号**（`None` = 没忽略）。 + /// + /// 只压住**这一个**版本：0.2.3 被忽略后同一次运行里冒出 0.2.4 仍然提示 + /// （文案是「忽略这个版本」，不是「别再问我」）。 + pub skipped: Option, + /// 这一份结论来自静默检查（启动时/自动）：失败时**不**弹提示条 + pub silent: bool, +} + +mod busy; + +impl Update { + /// 有没有可装的候选（有的话设置页给「下载并安装」）。 + #[must_use] + pub fn available(&self) -> Option<(&str, u64, &str, bool)> { + match &self.status { + UpdateStatus::Available { + version, + size, + notes, + forced, + } => Some((version, *size, notes, *forced)), + _ => None, + } + } + + /// 提示条此刻要显示什么（`None` = 不显示）。 + /// + /// 优先级与 presenter 侧同一条（就位 > 进行中 > 失败（仅主动查） > 有新版本（未被忽略））， + /// 这里再算一次是因为页面层拿不到 DTO 的那份判据——两处判据的顺序必须一致， + /// `pages/tests.rs` 有对拍用例守着。 + #[must_use] + pub fn banner(&self) -> Option> { + if let Some(version) = &self.ready { + return Some(Banner::Ready { version }); + } + if self.applying { + return Some(Banner::Applying); + } + if let UpdateStatus::Failed { reason, retryable } = &self.status { + return (!self.silent).then_some(Banner::Failed { + reason, + retryable: *retryable, + }); + } + match &self.status { + UpdateStatus::Available { + version, + size, + notes, + .. + } if self.skipped.as_deref() != Some(version.as_str()) => Some(Banner::Available { + version, + size: *size, + notes, + }), + _ => None, + } + } +} + +/// 出图 / 单测用的演示快照（一个可装的新版本 + 一次成功的检查）。 +/// +/// **不是产品数据**：产品路径的更新状态只来自 presenter（`app/view/update.rs` 转换）。 +/// +/// 取证开关 `ULL_UPDATE_STATE`（M161，沿用 `ULL_CONTENT_*` 那套范式）：不设 = 缺省那一态； +/// `checking` / `applying` 用来出「按钮置灰 + 状态行说正在干活」的那两张图， +/// `failed` / `up_to_date` 用来出另外两条结论。 +#[must_use] +pub fn demo() -> Update { + let mut snapshot = demo_available(); + match std::env::var("ULL_UPDATE_STATE") + .unwrap_or_default() + .as_str() + { + "checking" => snapshot.status = UpdateStatus::Checking, + "applying" => snapshot.applying = true, + "failed" => { + snapshot.status = UpdateStatus::Failed { + reason: "Could not fetch the release manifest: connection reset".to_string(), + retryable: true, + } + } + "up_to_date" => { + snapshot.status = UpdateStatus::UpToDate { + latest: Some("0.2.2".to_string()), + } + } + _ => {} + } + snapshot +} + +/// 缺省那一态（可装的新版本）。 +fn demo_available() -> Update { + Update { + current_version: "0.2.2".to_string(), + channel: "stable".to_string(), + auto_check: true, + status: UpdateStatus::Available { + version: "0.2.3".to_string(), + size: 21_500_000, + notes: "修掉启动崩溃；实例页加载更快".to_string(), + forced: false, + }, + checked_at: "11-08 12:00".to_string(), + applying: false, + ready: None, + skipped: None, + silent: false, + } +} + +/// 「有新版本」那条提示条的正文：**体积与更新说明摘要都要给**（mission 明列的三件之二）。 +/// +/// 拆成函数是为了可断言（`Element` 没有内省接口）：条数与措辞由 `tests` 的两条用例钉住。 +#[must_use] +pub fn available_body(catalog: Catalog, size: u64, notes: &str) -> String { + let size = human_bytes(size); + let body = catalog.render(Key::UpdateBannerBodyAvailable, &[("size", &size)]); + if notes.trim().is_empty() { + body + } else { + format!("{body} · {}", notes.trim()) + } +} + +// --------------------------------------------------------------- 提示条 + +use iced::widget::{column, container, row}; +use iced::{Alignment, 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 unlucky_i18n::{Catalog, Key}; +use unlucky_presenter::dto::human_bytes; + +use crate::app::components::buttons::{self, Button}; +use crate::pages::frame::text_role_owned; +use crate::pages::message::UpdateAction; +use crate::pages::Message; +use crate::theme::Ui; + +/// 顶部提示条（每一页都在页头之上；`None` = 现在没有要说的）。 +/// +/// 形态三种：有新版本（可下载 / 可忽略）、正在下载、已就位（可立即重启）。**失败不在这里** +/// ——静默检查失败是常态，弹一条红条等于每次开机先骂网络一次；失败原因在设置页「更新」区看。 +pub fn banner<'a>( + ui: &'a Ui, + update: &'a Update, + catalog: Catalog, +) -> Option> { + let kind = update.banner()?; + + // 三种形态各自的底色：有新版 = 次级容器（可操作、非错误）；进行中 = 同色但只读； + // 就位 = 主容器（「已经好了，重启即生效」是正反馈）。 + let (title, body, actions, role): (String, String, Vec>, Role) = match kind + { + Banner::Available { + version, + size, + notes, + } => { + let mut actions = vec![ + buttons::filled( + ui, + Button::new( + catalog.text(Key::UpdateBannerInstall), + Message::Update(UpdateAction::Apply), + ), + ), + buttons::text( + ui, + Button::new( + catalog.text(Key::UpdateBannerDismiss), + Message::Update(UpdateAction::Dismiss), + ), + ), + ]; + let _ = &mut actions; + ( + catalog.render(Key::UpdateBannerTitleAvailable, &[("version", version)]), + available_body(catalog, size, notes), + actions, + Role::SecondaryContainer, + ) + } + Banner::Applying => ( + catalog.text(Key::UpdateBannerApplying).to_string(), + String::new(), + Vec::new(), + Role::SecondaryContainer, + ), + Banner::Ready { version } => ( + catalog.text(Key::UpdateBannerTitleReady).to_string(), + catalog.render(Key::UpdateBannerBodyReady, &[("version", version)]), + vec![buttons::filled( + ui, + Button::new( + catalog.text(Key::UpdateBannerRestartNow), + Message::Update(UpdateAction::RestartNow), + ), + )], + Role::PrimaryContainer, + ), + Banner::Failed { reason, .. } => ( + catalog.text(Key::UpdateBannerTitleFailed).to_string(), + reason.to_string(), + vec![buttons::text( + ui, + Button::new( + catalog.text(Key::UpdateBannerRetry), + Message::Update(UpdateAction::CheckNow), + ), + )], + Role::ErrorContainer, + ), + }; + + let on_container = match role { + Role::PrimaryContainer => Role::OnPrimaryContainer, + Role::ErrorContainer => Role::OnErrorContainer, + _ => Role::OnSecondaryContainer, + }; + + let mut text_column = column![text_role_owned( + ui, + TypeRole::LabelLarge, + true, + title, + ui.color(on_container), + )] + .spacing(ui.space(Space::X1)) + .width(Length::Fill); + if !body.is_empty() { + text_column = text_column.push(text_role_owned( + ui, + TypeRole::BodySmall, + false, + body, + ui.color(on_container), + )); + } + + let mut line = row![text_column] + .spacing(ui.space(Space::X3)) + .width(Length::Fill) + .align_y(Alignment::Center); + for action in actions { + line = line.push(action); + } + + let padding = Padding::from([ui.space(Space::X3), ui.space(Space::X4)]); + Some( + container(line) + .width(Length::Fill) + .padding(padding) + .style(move |_theme| container::Style { + background: Some(Background::Color(ui.color(role))), + border: Border { + radius: ui.radius(ShapeScale::Medium, 0.0), + ..Border::default() + }, + ..container::Style::default() + }) + .into(), + ) +} +#[cfg(test)] +#[path = "update/tests.rs"] +mod tests; diff --git a/crates/app-iced/src/pages/update/busy.rs b/crates/app-iced/src/pages/update/busy.rs new file mode 100644 index 0000000..2c43a40 --- /dev/null +++ b/crates/app-iced/src/pages/update/busy.rs @@ -0,0 +1,43 @@ +//! 「这一条更新动作此刻能不能点」（M161：把「按钮亮着、点了没反应」收掉）。 +//! +//! 判据只有一条：有没有检查/下载正在跑。三处必须同源—— +//! +//! | 处 | 读的是 | +//! |---|---| +//! | presenter `Runtime::inflight()` | `begin_check` / `begin_apply` 置位，`adopt` 清位 | +//! | 设置页两颗按钮 | [`Update::can_check`] / [`Update::can_apply`]（本文件） | +//! | 设置页状态行 | 「正在检查…」/「正在安装…」（同一份 `busy()` 判据） | +//! | app 的消息入口 | `App::update_busy`（`app/update/update_action.rs`）——最后一道闸 | +//! +//! 为什么拆分到本文件：`pages/update.rs` 贴着 400 行硬线（AGENTS §3-1）， +//! 而这一组判据是「独立的一块问题」（能不能点），独立成文件后更好找。 + +use super::{Update, UpdateStatus}; + +impl Update { + /// 有一条检查/下载正在跑。 + /// + /// 两个字段都要看：`status == Checking` 是「查版本」，`applying` 是「下载/校验/替换」。 + /// presenter 侧同一个判据是 `Runtime::inflight()`（`begin_check` / `begin_apply` 置位， + /// `adopt` 清位），页面这层是它的**只读投影**——按钮的禁用态必须与它同源， + /// 否则会出现「按钮亮着、点了没反应」。 + #[must_use] + pub fn busy(&self) -> bool { + self.applying || matches!(self.status, UpdateStatus::Checking) + } + + /// 「立即检查」此刻能点吗。 + /// + /// 忙碌时**禁用而不是消失**：入口消失会让人以为功能没了，禁用 + 状态行那句 + /// 「正在检查…」才说得清「它在干活，等一下」。 + #[must_use] + pub fn can_check(&self) -> bool { + !self.busy() + } + + /// 「下载并安装」此刻能点吗（要有候选，且不忙）。 + #[must_use] + pub fn can_apply(&self) -> bool { + self.available().is_some() && !self.busy() + } +} diff --git a/crates/app-iced/src/pages/update/tests.rs b/crates/app-iced/src/pages/update/tests.rs new file mode 100644 index 0000000..3f3b590 --- /dev/null +++ b/crates/app-iced/src/pages/update/tests.rs @@ -0,0 +1,56 @@ +//! 自更新视图模型的单测（从 `pages/update.rs` 拆出，那边贴着 400 行硬线）。 + +use super::*; + +use unlucky_i18n::Lang; + +/// 提示条的正文**同时**给体积与说明摘要（mission：提示条含版本号、体积、说明摘要）。 +#[test] +fn the_available_banner_carries_both_size_and_notes() { + for lang in [Lang::En, Lang::ZhCn] { + let body = available_body(lang.catalog(), 21_500_000, "修掉启动崩溃"); + assert!(body.contains("20.5 MB"), "{lang:?} 缺体积：{body}"); + assert!(body.contains("修掉启动崩溃"), "{lang:?} 缺说明：{body}"); + } + // 发布没写说明时只留体积，不留一个空尾巴。 + let bare = available_body(Lang::En.catalog(), 1024, " "); + assert!(bare.contains("1.0 KB"), "{bare}"); + assert!(!bare.contains('·'), "没有说明时不该留分隔符：{bare}"); +} + +/// 视图模型的提示条判据与 presenter 同序（就位 > 进行中 > 失败 > 新版本）。 +#[test] +fn the_banner_priority_matches_the_presenter() { + let mut update = Update { + status: UpdateStatus::Available { + version: "0.2.3".to_string(), + size: 1, + notes: String::new(), + forced: false, + }, + ..Update::default() + }; + assert!(matches!(update.banner(), Some(Banner::Available { .. }))); + + update.skipped = Some("0.2.3".to_string()); + assert!(update.banner().is_none(), "忽略之后不再打扰"); + + // 忽略的是**那一个版本**：同一次运行里冒出 0.2.4 仍然提示（与 presenter 同一语义）。 + update.status = UpdateStatus::Available { + version: "0.2.4".to_string(), + size: 1, + notes: String::new(), + forced: false, + }; + assert!( + matches!(update.banner(), Some(Banner::Available { version, .. }) if version == "0.2.4"), + "0.2.3 被忽略不该压住 0.2.4" + ); + + update.skipped = None; + update.applying = true; + assert!(matches!(update.banner(), Some(Banner::Applying))); + + update.ready = Some("0.2.3".to_string()); + assert!(matches!(update.banner(), Some(Banner::Ready { .. }))); +} diff --git a/crates/app-iced/src/platform/data.rs b/crates/app-iced/src/platform/data.rs new file mode 100644 index 0000000..695db41 --- /dev/null +++ b/crates/app-iced/src/platform/data.rs @@ -0,0 +1,111 @@ +//! 数据根派生：**字体缓存放哪** + **一条设置键读什么**（M168）。 +//! +//! ## 为什么需要它 +//! +//! 字体下载要把 17 MiB 落在数据根里（`/cache/fonts/`），而「数据根在哪」这件事 +//! 已经有一个真源：`unlucky_presenter::settings_bridge::SettingsBridge::open()`（三模式数据根 + +//! `core.*` 覆盖键 + 便携回落，见那边的 `resolve_config_path`）。本模块**不重写**那套解析， +//! 只做两件它没暴露的事： +//! +//! 1. 由配置文件路径 `/config/launcher.json` 反推 ``，再用 [`LauncherLayout::cache`] +//! 取缓存分区（分区名只从 core 的 `layout` 常量来，不手拼字符串）； +//! 2. 读一条**设置键**的生效值（`ui.font_cdn`）：`SettingsBridge` 只暴露了 `ui.language` 的读写， +//! 而 `ui.font_cdn` 是 M168 新增的键。 +//! +//! ## 诚实边界 +//! +//! - **抓得住**：路径推导的形状（`/config/x` → `/cache`）与「配置读不到时返回 `None` +//! 而不是猜一个目录」； +//! - **抓不住**：真机上 `SettingsBridge::open()` 解析出哪个根（那是 presenter + core 的用例）， +//! 以及 macOS `.app` 只读这类平台差异（没有真机）。 +//! +//! ## 后续收口（已登记 finding） +//! +//! 更干净的做法是让 presenter 暴露一个通用的 `SettingsBridge::load_text(key)`，本模块就只剩 +//! 「布局 + 一条键」。presenter 不在 M168 的 scope 里，所以这里先按上面的方式落地。 + +use std::path::PathBuf; + +use unlucky_core::platform::layout::LauncherLayout; +use unlucky_core::setting::document::SettingDocument; +use unlucky_core::setting::keys::launcher_schema; +use unlucky_core::setting::store::SettingStore; +use unlucky_presenter::settings_bridge::SettingsBridge; + +/// 中文字体下载地址的覆盖键（M168；空 = 用内置镜像）。 +pub const FONT_CDN_KEY: &str = "ui.font_cdn"; + +/// 本进程的数据根布局（`None` = 数据根解析不出来，例如 exe 目录都拿不到）。 +/// +/// 解析只发生一次：配方来自 `SettingsBridge::open()`（它内部走 `DataDirRequest` + `Resolver`）。 +pub fn layout() -> Option { + static LAYOUT: std::sync::OnceLock> = std::sync::OnceLock::new(); + LAYOUT + .get_or_init(|| { + let config = SettingsBridge::open().path()?.to_path_buf(); + // `/config/launcher.json` → `` + let home = config.parent()?.parent()?.to_path_buf(); + Some(LauncherLayout::new(home)) + }) + .clone() +} + +/// 字体缓存的根（`/fonts/` 的父目录；**不**等于字体目录本身）。 +/// +/// 用 `cache/` 而不是 `data/`：字体随时可删、删了会自动重下（D28 的「数据根」语义里， +/// 这就是「可重建」的那一类）。 +pub fn cache_root() -> Option { + layout().map(|layout| layout.cache()) +} + +/// 读一条设置键的**生效值**（schema 默认值也算；空串会被 `trim` 掉但仍是 `Some`）。 +/// +/// `None` = 配置读不到（数据根解析失败 / 文件损坏到 `SettingStore` 都装不起来）。 +pub fn setting_text(key: &str) -> Option { + let path = SettingsBridge::open().path()?.to_path_buf(); + let schema = launcher_schema(); + let store = SettingStore::load(&path, schema); + let document: &SettingDocument = store.doc(); + document.effective_str(key).map(str::to_owned) +} + +/// `ui.font_cdn` 的覆盖值（`None` = 没配 / 配了空串 ⇒ 用内置镜像）。 +pub fn font_cdn_override() -> Option { + let raw = setting_text(FONT_CDN_KEY)?; + let trimmed = raw.trim(); + (!trimmed.is_empty()).then(|| trimmed.to_owned()) +} + +#[cfg(test)] +mod tests { + use super::*; + + /// 键名与 core 的 schema 一致：写错一个字符，用户配了也不生效（而 UI 不会报错）。 + /// + /// 抓得住：本模块的常量与 `core::setting::keys` 里登记的键名对不上。 + /// 抓不住：真机上读到的值（那要数据根与配置文件）。 + #[test] + fn the_cdn_key_is_registered_in_the_launcher_schema() { + let schema = launcher_schema(); + assert!( + schema.spec(FONT_CDN_KEY).is_some(), + "{FONT_CDN_KEY} 没在 core 的 schema 里登记" + ); + } + + /// 布局推导的形状：`/config/launcher.json` → `/cache`。 + /// + /// 抓得住：有人把「上两级」写成「上一级」（缓存会落进 `config/` 里），或改用 `data/` 分区。 + /// 抓不住：真机上 `` 解析成什么（presenter 的 `resolve_config_path` 管那一层）。 + #[test] + fn the_cache_partition_is_the_sibling_of_config() { + let config = PathBuf::from("/tmp/ull-home/config/launcher.json"); + let home = config.parent().unwrap().parent().unwrap().to_path_buf(); + let layout = LauncherLayout::new(home); + assert_eq!(layout.cache(), PathBuf::from("/tmp/ull-home/cache")); + assert_eq!( + layout.cache().join("fonts"), + PathBuf::from("/tmp/ull-home/cache/fonts") + ); + } +} diff --git a/crates/app-iced/src/platform/host.rs b/crates/app-iced/src/platform/host.rs new file mode 100644 index 0000000..882149d --- /dev/null +++ b/crates/app-iced/src/platform/host.rs @@ -0,0 +1,104 @@ +//! 宿主平台族（M182）：窗口外框判据的**输入值**，而不是散落各处的 `#[cfg]`。 +//! +//! ## 为什么平台要是一个值 +//! +//! 圆角判据（[`super::win32::corner::plan_corner_for`]）必须能表达「Windows / macOS / Linux +//! 各自怎么办」三行。写成 `#[cfg(target_os = …)]` 的话，在 Windows 上编译时另外两行**根本不存在**， +//! 判据就永远只能在一台机器上验三分之一——而 M182 要的恰恰是那两行。 +//! +//! 把平台变成值以后：真值表可以在**本机**跑满三行，`cfg` 只留在真正需要 FFI 的地方 +//! （那边本来就有，且只影响「能不能调」，不影响「判据是什么」）。这与 AGENTS.md §7 +//! 「平台差异判断收敛到底层，不许在各模块里散写 `cfg`」是同一条纪律。 +//! +//! ## 取值来源 +//! +//! [`HostOs::current`] 读 `std::env::consts::OS`（编译期常量，运行期不会变）。 +//! 它**不**做任何环境探测：本仓库里「探测」是 [`super::win32::transparency`] 与 +//! `probe_windows_version` 的事，这里只回答「我编在哪个平台上」。 + +/// 宿主平台族（判据输入）。 +/// +/// 只分到判据真正会用到的粒度：Windows 要问 DWM、macOS 要交给窗口服务器、 +/// Linux 没有可问的对象、其余平台（FreeBSD / Android / wasm …）一律不承诺。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum HostOs { + /// Windows（10 / 11 / Server 同族）。 + Windows, + /// macOS。 + MacOs, + /// Linux（X11 与 Wayland 都是它：判据不看后端，看的是有没有可问的对象）。 + Linux, + /// 其余目标（FreeBSD / Android / wasm32 …）：不承诺圆角。 + Other, +} + +impl HostOs { + /// 当前编译目标所属的平台族。 + #[must_use] + pub fn current() -> Self { + Self::from_os_str(std::env::consts::OS) + } + + /// [`std::env::consts::OS`] 的字符串 → 平台族（纯函数，测试直接钉它）。 + /// + /// 只认 `"windows"` / `"macos"` / `"linux"` 三个字面量，其余（含未来新平台）落 [`Self::Other`]： + /// 猜错的代价是「多给它一个圆角承诺」，而不认识的平台本来就没有承诺可言。 + #[must_use] + pub fn from_os_str(os: &str) -> Self { + match os { + "windows" => Self::Windows, + "macos" => Self::MacOs, + "linux" => Self::Linux, + _ => Self::Other, + } + } + + /// 日志取值（`host=windows|macos|linux|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", + } + } +} + +#[cfg(test)] +mod tests { + use super::HostOs; + + /// **抓得住**：三个字面量任一个拼错（`"macos"` 写成 `"mac-os"` / `"darwin"`）—— + /// 那会让 macOS 静默掉进 `Other` 从而「不承诺圆角」，正是 M182 要修的那类静默。 + /// **抓不住**：`std::env::consts::OS` 在真机上到底是哪个值（那是编译器给的常量，本测试只钉映射）。 + #[test] + fn the_three_supported_families_are_recognized_verbatim() { + assert_eq!(HostOs::from_os_str("windows"), HostOs::Windows); + assert_eq!(HostOs::from_os_str("macos"), HostOs::MacOs); + assert_eq!(HostOs::from_os_str("linux"), HostOs::Linux); + assert_eq!(HostOs::Windows.as_str(), "windows"); + assert_eq!(HostOs::MacOs.as_str(), "macos"); + assert_eq!(HostOs::Linux.as_str(), "linux"); + } + + /// 不认识的目标一律 `Other`（不承诺），且**不许**退化成 Windows/macOS 的承诺。 + #[test] + fn anything_else_falls_to_other_instead_of_guessing() { + for os in ["freebsd", "netbsd", "android", "ios", "emscripten", ""] { + assert_eq!(HostOs::from_os_str(os), HostOs::Other, "{os}"); + } + assert_eq!(HostOs::Other.as_str(), "other"); + } + + /// `current()` 必须与编译目标的 `cfg` 一致——这是**本机唯一**能自查「值与 cfg 没跑偏」的地方。 + #[test] + fn current_matches_the_compilation_target() { + #[cfg(target_os = "windows")] + assert_eq!(HostOs::current(), HostOs::Windows); + #[cfg(target_os = "macos")] + assert_eq!(HostOs::current(), HostOs::MacOs); + #[cfg(target_os = "linux")] + assert_eq!(HostOs::current(), HostOs::Linux); + } +} diff --git a/crates/app-iced/src/platform/linux/mod.rs b/crates/app-iced/src/platform/linux/mod.rs new file mode 100644 index 0000000..e3f42d0 --- /dev/null +++ b/crates/app-iced/src/platform/linux/mod.rs @@ -0,0 +1,43 @@ +//! Linux（X11 / Wayland）的窗口圆角（M182）：**谁负责、我们为什么不画**。 +//! +//! 用户定的规则是「非 Windows 按窗口合成器的默认规则来」。在 Linux 上这句话要落到具体机制， +//! 否则很容易变成「把 Windows 那套 DWM 判据搬过来假装能用」——**不许**那样写（M182 任务书）。 +//! +//! ## 事实层：协议里没有「圆角」这个概念 +//! +//! | 层 | 有什么 | 依据级别 | +//! |---|---|---| +//! | `xdg-shell`（Wayland） | 只有 `wl_surface.set_opaque_region` / `set_input_region`（**矩形集合**）、`set_buffer_transform`、圆角半径之类一概没有 | A 级（协议规范） | +//! | X11 | 形状扩展（`XShape`）能按矩形并集切出非矩形窗口，但**只能切硬边**（无抗锯齿）；要透明圆角得配 ARGB visual + 合成器 | A 级（X 扩展规范） | +//! | 装饰归属 | 谁装饰谁负责：合成器画（SSD）由合成器圆，客户端画（CSD）由客户端圆。`zxdg_decoration_manager_v1` **很多合成器即使被请求也不画**（D35 已记） | A 级协议 + D35 实测/推断 | +//! +//! 我们是 **CSD**：`decorations: false`（`app/boot/diagnostics.rs`），自绘标题栏 + 自绘三键。 +//! 所以「圆角该由谁画」的答案是**我们**——而 D46 第 4 条明确要求不自绘裁切， +//! 于是唯一的诚实结果是**直角**，并把这句结论写进日志： +//! `source=compositor excluded_reason=client-side`（见 [`crate::platform::win32::corner`]）。 +//! +//! ## 为什么不自绘（不是「懒得做」） +//! +//! 1. 自绘圆角 = 把内容层裁成圆角。我们的内容层含**自绘三键 + 边缘缩放热区**，裁掉圆角就会 +//! 一起裁掉热区（这条在 M116 已被 tower 采纳）。 +//! 2. Wayland 上「表面画圆角 + ARGB 缓冲」在合成器侧确实能透出桌面，但需要整窗 `transparent` +//! ——那是 D36 的整窗 α 管线，且会与 Linux 上「没有 `_NET_WM_CM_S0` 合成器时透明变黑」的 +//! 既有结论打架。 +//! 3. X11 无合成器时透明不可用；只剩 `XShape` 硬边圆角——像素级毛边，比直角更难看。 +//! +//! ## 合成器差异（**推断级，本机无真机，未验**） +//! +//! - 浮动式合成器（KWin / Mutter）对自己的 SSD 窗做圆角，对 CSD 窗**通常不裁**（客户端的 surface +//! 原样合成）；但个别主题会给无边框窗额外加重绘制的阴影/边框——那种圆角是**合成器画的**， +//! 不是我们画的。判别口径：日志 `source=compositor`，而像素上的圆角随主题/合成器变化。 +//! - 平铺式（sway / niri / Hyprland / river）连边框都按自己的配置画，更不会替 CSD 窗裁圆角； +//! D35/D37 还记着「sway 默认下已经出现合成器 SSD + 我们自绘的双标题栏」这条现状缺陷。 +//! +//! 这些行为**没有任何一条**能用协议查询，也没有一条能由应用侧读取——所以判据里**不写** +//! 「Linux 会/不会圆角」，只写「决定权在合成器，而 CSD 窗它不裁」。 +//! +//! ## 本轮明确未验 +//! +//! - 真实合成器上的四角观感（无 Linux 真机；CI 的 Linux 冒烟只验「能起来 + 出图不是全黑」）； +//! - KWin / Mutter / Hyprland 是否会对我们的 CSD 窗做额外装饰； +//! - 高 DPI 下若将来改为自绘，半径是否需要缩放（本轮不涉及：半径不由我们定）。 diff --git a/crates/app-iced/src/platform/locale.rs b/crates/app-iced/src/platform/locale.rs new file mode 100644 index 0000000..0ec4188 --- /dev/null +++ b/crates/app-iced/src/platform/locale.rs @@ -0,0 +1,307 @@ +//! 系统语言的**真值源**（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 的纪律），所以这里照抄那条路。 +//! +//! 子进程**一律**经 `unlucky_core::platform::child::quiet` 起（M217）：GUI 父进程自己没控制台， +//! 裸构造会给 `reg.exe` 新建一块控制台窗口，用户看到的就是启动时闪一下黑框。 +//! +//! 为什么不 `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; +} + +/// 真实实现：`reg.exe` 子进程（非 Windows 上恒 `None`）。 +#[derive(Debug, Clone, Copy, Default)] +pub struct HostReg; + +impl RegIo for HostReg { + fn run(&self, program: &str, args: &[&str]) -> Option { + if !cfg!(windows) { + // 其它平台的「系统语言」真值源不是注册表；`resolve` 会继续往环境变量走。 + return None; + } + + // **必须**走 `quiet`（M217）：本 crate 的父进程是没有控制台的 GUI（PE Subsystem=2）， + // 裸 `Command::new("reg.exe")` 会让 Windows 给子进程新建一块控制台——用户看到的就是 + // 「启动时底下闪一个黑框」。这条路径每次 GUI 启动都跑，所以它闪得准时。 + let output = unlucky_core::platform::child::quiet(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 { + detect_with(&HostReg) + } + + fn label(&self) -> &'static str { + "registry" + } +} + +/// 用给定 IO 读一次系统语言（`LocaleName` 优先，退 `Locale` 的 LCID）。 +pub fn detect_with(io: &dyn RegIo) -> Option { + 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 { + 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 { + 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/macos/mod.rs b/crates/app-iced/src/platform/macos/mod.rs new file mode 100644 index 0000000..816878c --- /dev/null +++ b/crates/app-iced/src/platform/macos/mod.rs @@ -0,0 +1,93 @@ +//! macOS 的窗口外框（M182）：**本轮不实现**，这里只有结论、证据与后续配方。 +//! +//! 用户第三轮 Mac 真机验收的现象：四角是直角，日志 `[corner] … source=square os=unknown`。 +//! 「macOS 不支持圆角」是**错的**——macOS 的窗口四角本来就有系统圆角，只是我们交上去的窗口 +//! 不在会被裁的那一类里。三环链条如下，每一环都能在本机复核（读锁文件里的依赖源码即可）： +//! +//! ## 第 1 环：我们交的是什么窗 +//! +//! `crates/app-iced/src/app/boot/diagnostics.rs` 的 `window_settings()` 给的是 +//! `decorations: false`（M93 自绘三键）。那是**唯一产地**，`[window]` / `[caps]` 两行 +//! 验收日志也从它取字段。 +//! +//! ## 第 2 环：winit 把 `decorations: false` 翻成什么 +//! +//! winit 0.30.13 `src/platform_impl/macos/window_delegate.rs:540-552`： +//! +//! ```text +//! let mut masks = if (!attrs.decorations && screen.is_none()) || titlebar_hidden { +//! // Resizable without a titlebar or borders +//! NSWindowStyleMask::Borderless | NSWindowStyleMask::Resizable | NSWindowStyleMask::Miniaturizable +//! } else { +//! // default case, resizable window with titlebar and titlebar buttons +//! NSWindowStyleMask::Closable | Miniaturizable | Resizable | Titled +//! }; +//! ``` +//! +//! ⇒ `decorations: false` 拿到的是 **`Borderless`**，**没有 `Titled`**。 +//! +//! ## 第 3 环：窗口服务器只给 `Titled` 窗做圆角裁剪 +//! +//! 这是 AppKit 的标准窗口行为（A 级外部事实：标准窗口的圆角由窗口服务器连同阴影一起画， +//! 无边框窗口不参与）。本仓库**没有**任何一行代码能影响它：winit 的 macOS 后端里 +//! `cornerRadius` / `CornerRadius` 命中数为 **0**（`src/platform_impl/macos/` 内四命中全是 +//! 「屏幕/视图左上角」的注释），也就是说圆角从来没有一行业是我们调的。 +//! +//! 反向印证：用户第三轮实测（本机窗口就是 borderless）拍到四角直角，与第 3 环一致。 +//! +//! 判据一侧的落点：`plan_corner_for(MacOs, …)` 现在返回 +//! `source=compositor excluded_reason=borderless`（见 [`crate::platform::win32::corner`]）， +//! 而不是原先含糊的 `source=square os=unknown`。 +//! +//! ## 为什么**不**用 objc 给 `contentView.layer` 设 `cornerRadius`（M182 任务书原路线，已否） +//! +//! 1. **违反 D46 第 4 条**「macOS / X11 / Wayland 按合成器默认、**不主动自绘**」： +//! 把内容层裁成圆角就是自绘裁切，同一份决策日志里已经否决过这条（还附带 +//! 「会把标题栏三键与边缘缩放热区一起裁掉」的问题）。 +//! 2. **撞 `unsafe` 铁律**：根 `Cargo.toml` 的 `[workspace.lints.rust] unsafe_code = "deny"`， +//! 且 `guards.yml` 的 `unsafe-scope` 作业要求「带 `allow(unsafe_code)` 的文件集合**恰好等于** +//! `crates/app-iced/src/platform/win32/transparency.rs`」——新增一个 objc FFI 文件会让该作业 +//! 直接红，而那个工作流不在 M182 的改动范围内。 +//! 3. **拿不到 `NSWindow`**：`app/window_alpha.rs` 的 `probe_hwnd` 在非 Windows 恒返回 `None`， +//! 于是 `App::apply_window_corner` 走 `NoWindow` 分支——macOS 上那条下发链**从来没被调用过**。 +//! 要接线得改 `app/window_alpha.rs` + `app/update.rs`（M182 范围之外，且 M168/M178 正在改 +//! `app/**`）。 +//! 4. **本机编不了**：macOS 分支要靠 macOS 工具链，Windows 上连类型检查都跑不到。 +//! +//! ## 后续口径（**未实现**，需另立 mission + Mac 真机第 4 轮验收） +//! +//! 目标：把外框交还给窗口服务器当标准窗口，由它按自己的规则圆角（= 用户定的 +//! 「其他系统按照窗口合成器的默认规则来」）： +//! +//! ```text +//! decorations: true, +//! platform_specific: { title_hidden: true, titlebar_transparent: true, fullsize_content_view: true } +//! ``` +//! +//! - 三个字段 iced 0.14 已暴露（`iced_core-0.14.0/src/window/settings/macos.rs`）， +//! iced_winit 1:1 转发（`iced_winit-0.14.1/src/conversion.rs:125-137` 的 +//! `#[cfg(target_os = "macos")]` 块）； +//! `FullSizeContentView` 让内容铺满整窗（不留原生标题栏高度），窗口服务器把整窗 +//! ——**连同我们的背景图**——裁成圆角，不会出现「外框圆了、里面还是方块」。 +//! - **必须同时隐藏我们自绘的三键**（`crates/app-iced/src/shell/mod.rs`），否则屏幕上会同时存在 +//! 左上角原生三色灯与右上角自绘三键两套控件——那不是「跟随合成器」，是两套控件打架。 +//! - **已知阻塞点（真做之前必须先解掉）**：winit 有 `with_titlebar_buttons_hidden` +//! （`src/platform/macos.rs:290`，能一次藏掉全部三色灯），但 **iced 0.14 的 +//! `PlatformSpecific` 没有转发它**；而 `WindowExtMacOS` 也没有运行期隐藏按钮的接口 +//! （只有 `set_has_shadow` / `set_document_edited` 等）。三条出路：① 给 iced 上游提转发 +//! （最干净，但要等版本）；② 仅用 `closeable: false, minimizable: false` 藏掉关闭/最小化 +//! 两键——**缩放键藏不掉**，会留一个孤零零的绿灯；③ 拿到 `NSWindow` 后手动 `setHidden:` +//! （回到 objc + `unsafe`，见上面的第 2、3 条）。 +//! - **验收日志会一起变**：`renderer::acceptance::visual` 从 `decorations` 推 +//! `controls=self-drawn|native`，一旦改成 `true`，那行会写 `controls=native`，而我们当时 +//! 仍在自绘三键（除非同一次改动把三键撤掉）⇒ 那条改动必须**同一个 mission 内**一起做。 +//! - **验证路径**：本机（Windows）拿不到任何 macOS 像素；只能靠 +//! `ci.yml` 的 `runtime-smoke-macos` 作业（dispatch 触发、`continue-on-error`）看**编不编得过**， +//! 视觉效果必须等**第 4 轮 Mac 真机验收图**或用户手动确认。 +//! +//! ## 本轮明确未验 +//! +//! - macOS 圆的半径、平滑度、与系统其它窗口是否一致（无真机）； +//! - 高 DPI（Retina）下系统圆角的视觉半径（由系统决定，我们读不到，也不需要缩放——这一档 +//! 本来就「不归我们管」，见 [`crate::platform::win32::corner`] 的 `radius=system`）； +//! - 原生三色灯的最终观感与「是否保留自绘三键」的产品取舍。 diff --git a/crates/app-iced/src/platform/mod.rs b/crates/app-iced/src/platform/mod.rs new file mode 100644 index 0000000..abad10b --- /dev/null +++ b/crates/app-iced/src/platform/mod.rs @@ -0,0 +1,194 @@ +//! 平台相关的窗口能力（P4 / D36 / M116 / M168 / M182 / M196）：整窗透明度与窗口圆角的**判据**、 +//! 两处 `unsafe` 落点、系统语言真值源、以及数据根派生——每一件各归一处（判据不碰 FFI， +//! FFI 只住落点文件）。 +//! +//! - 本文件 = 整窗 α 的纯判据 [`effective_window_alpha`]：不读环境变量、不调 FFI、不碰窗口句柄， +//! 只回答「按这个渲染后端和用户要的 α，最终该给窗口什么值」； +//! - [`win32::corner`] = 圆角的纯判据 [`plan_corner`] / [`plan_corner_for`]（M116 / M182）： +//! 用户策略 × 宿主平台 × 渲染档 → 来源与原因码。两个判据都**不碰** FFI，因此都能被断言证明； +//! - [`win32::transparency`] = 整窗 α 的 FFI 落点（补 `WS_EX_LAYERED` + +//! `SetLayeredWindowAttributes`，以及 M116 的 `DwmSetWindowAttribute`）； +//! - [`win32::console`] = M196 的控制台附着落点（`AttachConsole`）：GUI 子系统进程的输出 +//! 为什么在 cmd 里会静默丢失，以及唯一的补救。两个落点的放行范围各自收在一个文件里， +//! `unsafe-scope` 门禁的期望集合就是这两个路径（集合相等，不是黑名单）； +//! - [`locale`] = 系统语言真值源（D28）：`reg.exe` 子进程读注册表，**零 `unsafe` / 零 FFI**。 +//! +//! 为什么判据要单独拎出来：D36 的降级规则（α 下限 0.08 / `≤0` 一律拒绝 / CPU 档也允许 +//! 窗口级 α）**可以**被断言证明；而 FFI 的**视觉**结果在本仓库的验证环境（RDP + 虚拟显示 +//! 适配器、无 Mac 真机）上没有参考价值。把可测的那一半独立出来，才有「有测试的判据 + +//! 没测试的观感」这条诚实的分界。 +//! +//! ## 平台分册（M182：非 Windows 不再是「未知」一格） +//! +//! | 模块 | 里面有什么 | 有没有 FFI | +//! |---|---|---| +//! | [`data`] | 数据根派生（字体缓存分区 + 一条设置键的生效值，M168） | 没有 | +//! | [`host`] | [`HostOs`]：平台族的**值**（判据的输入，不是散落的 `cfg`） | 没有 | +//! | [`macos`] | macOS 为什么是直角的三环证据 + 「迁移原生标题栏」的未实现配方 | 没有（本轮只有文档） | +//! | [`linux`] | X11 / Wayland 谁负责圆角、为什么我们不自绘 | 没有（本轮只有文档） | +//! | [`win32`] | Windows 的实现与探针（DWM / 分层 / 控制台附着） | **有**（两处落点：`transparency` + `console`） | +//! +//! 两个新平台模块**只有文档、没有代码**：M182 的裁决是不实现（macOS 要动手就得先迁移原生标题栏， +//! 那会引入两套窗口控件，必须连着撤掉自绘三键 + 真机验收一起做）。把结论写在这里而不是写进报告， +//! 是因为报告会随会话消失，而下一轮动这块的人一定先读代码。 + +use unlucky_presenter::prefs::WINDOW_ALPHA_MIN; + +use crate::Backend; + +pub mod data; +pub mod host; +pub mod linux; +pub mod locale; +pub mod macos; +pub mod win32; + +/// 窗口圆角的**判定**（M116 / M182）住在 `win32::corner`：判据是用户策略 × 宿主平台 × 渲染档。 +/// 非 Windows 的两档（macOS = 合成器不裁 borderless 窗、Linux = CSD 没人裁）在 +/// [`macos`] / [`linux`] 两个模块里逐条给了证据。 +pub use host::HostOs; +pub use win32::corner::{plan_corner, plan_corner_for, 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 { + static CACHED: std::sync::OnceLock> = + 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 { + 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/console.rs b/crates/app-iced/src/platform/win32/console.rs new file mode 100644 index 0000000..8a90ee7 --- /dev/null +++ b/crates/app-iced/src/platform/win32/console.rs @@ -0,0 +1,270 @@ +//! 控制台附着（M196）：GUI 子系统进程为什么「参数看得见、输出看不见」，以及唯一的补救。 +//! +//! ## 起因 +//! +//! `crates/app-iced/src/main.rs` 顶上的 `#![cfg_attr(windows, windows_subsystem = "windows")]` +//! 把产物 PE 头的 `Subsystem` 从 CUI(3) 改成 WINDOWS_GUI(2)——双击不再多一个控制台宿主窗口 +//! （群友 2026-11-08 实测「发布构建底下带一个控制台窗口」）。代价是：同一条命令行也仍然要能用。 +//! `unlucky-launcher-iced` 一个二进制两种用法（M82），CLI 子命令与 `--diff` / `--screenshot` +//! 的日志全靠 std 句柄，而 GUI 子系统进程**不继承**父进程的控制台。 +//! +//! ## 四情形实测（2026-11-08，本机 Windows；GUI 子系统探针与最终产物同属性） +//! +//! | 启动方式 | 启动瞬间 `GetStdHandle`(out/err) | 输出去哪了 | 要 attach 吗 | +//! |---|---|---|---| +//! | ① `> file` 重定向 | 磁盘句柄（`GetFileType`=1） | 文件 | 不要 | +//! | ② `\| pipe` 管道 | 管道句柄（=3） | 管道 | 不要 | +//! | ③ cmd 里直接跑 | **0 / 0**（`FILE_TYPE_UNKNOWN`） | **丢了** | **要** | +//! | ④ 双击 | 0 / 0 | 丢了（本来也没人看） | 要（但会失败，见下） | +//! +//! ③ 的补救实测：`AttachConsole(ATTACH_PARENT_PROCESS)` 返回 1 之后 `GetStdHandle` 立刻给出 +//! 控制台句柄（release 产物在 cmd 模型下实测 `out 0x0→0x1F0` / `err 0x0→0x1F4`），随后 +//! `WriteFile` 与 Rust 的 `eprintln!` 都真的落进了屏幕缓冲区（同一模型宿主读回的文本见 M196 +//! 报告）。具体数字随进程与控制台实例变化（调试构建里是 `0x208`/`0x20C`），**能跨实例复现的 +//! 是「从 0 变成非 0」这件事本身**。所以**不需要**再自己 `CreateFileW("CONOUT$")` + +//! `SetStdHandle`：那一层是多余的，而且它会覆盖用户自己重定向的句柄——①②两种情形会被打坏。 +//! +//! ④ 的边界：双击时祖先进程（explorer）没有控制台，`AttachConsole` 返回 0 +//! （`GetLastError` = 6 `ERROR_INVALID_HANDLE`），`GetConsoleWindow` 仍是 0、`CONOUT$` 也打不开。 +//! **`AttachConsole` 只会附到一个已经存在的控制台，永远不会新建窗口**——这正是它比 +//! `AllocConsole` 适合这里的原因（后者凭空多一个黑框，正是本次要修的那个 bug）。 +//! +//! ## 什么时候调、为什么无条件调 +//! +//! `main()` 的**第一件事**（早于 CLI 分发、早于 iced 初始化）：一条路径写 CLI 输出，另一条路径 +//! 在 `--diff` / `--screenshot` / 参数报错时写 stderr，两条都要句柄。判据只有一条—— +//! 「out 与 err 至少一个是不可用的就尝试 attach」，可用就绝不碰（那是 ①②）。 +//! +//! 无条件（而不是只在 CLI 分支）的取舍：今天发的产物是 CUI(3)，被控制台拉起时**本来就是** +//! 附着状态（收得到 Ctrl+C / 控制台关闭事件）；在同一条路径上保持附着语义，等于「除了双击不再 +//! 多黑框」之外**行为不变**。双击那条路 attach 必失败，不会多出任何窗口。 +//! +//! ## 非 Windows +//! +//! 同签名函数返回 [`ConsoleOutcome::NotWindows`]：调用点不需要 `#[cfg]`，而「这个平台没有 +//! Windows 控制台这回事」本身可以被断言。 + +// 本文件是 D36 那条「unsafe 落点」的第二个成员（详见 `transparency.rs` 顶部与 +// `.github/workflows/guards.yml` 的 `unsafe-scope`）：控制台附着只有 Win32 一条路， +// 没有安全替代。放行范围仅限本文件。 +#![allow(unsafe_code)] + +/// `GetStdHandle` 的两个 `(DWORD)-n` 参数（同一个值在 u32 与 i32 两种记法下都要能写）。 +#[cfg(target_os = "windows")] +const STD_OUTPUT_HANDLE: u32 = 0xFFFF_FFF5; // -11 +#[cfg(target_os = "windows")] +const STD_ERROR_HANDLE: u32 = 0xFFFF_FFF4; // -12 + +/// `AttachConsole` 的 `ATTACH_PARENT_PROCESS`（`(DWORD)-1`）。 +#[cfg(target_os = "windows")] +const ATTACH_PARENT_PROCESS: u32 = 0xFFFF_FFFF; + +/// `FALSE`/`TRUE` 之外唯一需要认的无效句柄：`(HANDLE)-1`。 +/// +/// **必须带下面那行 `cfg`**：唯一使用点 [`usable`] 只活在 Windows 分支里，而本模块在 +/// Linux/macOS 上也编译（`platform/mod.rs` 的 `pub mod win32;` 没有 cfg）。漏了它， +/// `ci.yml` 的 ubuntu clippy（`-- -D warnings`）会把它升级成 `dead_code` error——而本机只有 +/// windows-gnu 工具链，非 Windows 的 cfg 一次都编不到，本地抓不住（M196 r1 复审 P1）。 +/// 同目录 `transparency/dwm.rs` 用的是文件级 `#![cfg_attr(not(windows), allow(dead_code))]`； +/// 这里刻意**不用**那种写法：本文件的 Windows-only 面很小，每一项各自带 cfg 才能让编译器 +/// 继续在非 Windows 上替我们盯着「又漏了一个」。 +/// +/// 自证办法（本机只有 Windows triple、交叉编 iced 会卡在 x11/fontconfig 时）：把本文件的 +/// `target_os = "windows"` 全换成不存在的目标名，再 +/// `rustc --edition 2021 --crate-type lib -D warnings --crate-name console_probe <那份拷贝>` +/// ——漏了上面那行 cfg 时它是 exit 1 + `constant INVALID_HANDLE_VALUE is never used`， +/// 补齐后 exit 0 且零告警（**其他**任何非 Windows 死项也会一起报出来，所以这一个 probe 就是 +/// 「本文件在 Linux 上能不能过 -D warnings」的整份答案）。 +#[cfg(target_os = "windows")] +const INVALID_HANDLE_VALUE: isize = -1; + +#[cfg(target_os = "windows")] +#[link(name = "kernel32")] +extern "system" { + fn GetStdHandle(which: u32) -> isize; + fn GetFileType(handle: isize) -> u32; + fn AttachConsole(process_id: u32) -> i32; + fn GetLastError() -> u32; +} + +/// 一次附着的结论。带着前后两对句柄值走，报告里贴的就是运行时真读数，不是「应该没问题」。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum ConsoleOutcome { + /// 非 Windows：没有这回事。 + NotWindows, + /// `out` 与 `err` 都已经是可用句柄（①②）：**一个字节都没动**。 + AlreadyUsable { + /// `(stdout, stderr)` 的 `GetStdHandle` 读数。 + handles: (isize, isize), + }, + /// 附着成功：`after` 是附着后的读数（控制台句柄）。 + Attached { + /// 附着前 `(stdout, stderr)`。 + before: (isize, isize), + /// 附着后 `(stdout, stderr)`。 + after: (isize, isize), + }, + /// 没有可写的控制台（④ 双击，以及其他没有控制台的宿主）：附着失败**或**附着成功但 + /// 句柄仍不可用。服务 / 计划任务只是**近似**形态、未亲测，边界见 `packaging/README.md` §15。 + /// + /// 两种情况在调用点上是同一件事（都没有输出通道），所以合并成一个结论；`last_error` 与 + /// 两对句柄一起进诊断文本，读的人能自己分清是哪一种。**没有新建任何窗口**。 + NoConsole { + /// 附着前 `(stdout, stderr)`。 + before: (isize, isize), + /// 附着后 `(stdout, stderr)`。 + after: (isize, isize), + /// `AttachConsole` 之后的 `GetLastError`（双击时实测 6 = `ERROR_INVALID_HANDLE`）。 + last_error: u32, + }, +} + +impl ConsoleOutcome { + /// 单行可 grep 的验收诊断（`ULL_ACCEPTANCE=1` 时由 `main` 打到 stderr，前缀 `[console]`）。 + /// + /// 句柄按 `0x` 十六进制打印：`0x0` / `0xFFFFFFFFFFFFFFFF` 一眼就是「没有」， + /// 而「附着了但等于没附」这种半吊子状态（attach 成功、句柄仍是 0）也就藏不住。 + #[must_use] + pub fn describe(self) -> String { + match self { + Self::NotWindows => "非 Windows：无控制台可附着（不适用）".to_owned(), + Self::AlreadyUsable { handles } => format!( + "std 句柄本来就可用（out=0x{:X} err=0x{:X}），未 attach", + handles.0, handles.1 + ), + Self::Attached { before, after } => format!( + "已附着父进程控制台：out 0x{:X}→0x{:X}，err 0x{:X}→0x{:X}", + before.0, after.0, before.1, after.1 + ), + Self::NoConsole { + before, + after, + last_error, + } => format!( + "没有可用的控制台（attach 失败或句柄仍不可用，GetLastError={}）：out 0x{:X}→0x{:X}，err 0x{:X}→0x{:X}；未新建窗口", + last_error, before.0, after.0, before.1, after.1 + ), + } + } + + /// 是否真的（或本来就已经）有可用的输出通道。仅供诊断/日志判断，不影响控制流。 + #[must_use] + pub fn output_visible(self) -> bool { + match self { + Self::NotWindows | Self::NoConsole { .. } => false, + Self::AlreadyUsable { .. } | Self::Attached { .. } => true, + } + } +} + +/// 判据（纯函数）：两个句柄都可用就**不**碰，否则尝试 attach。 +/// +/// 单拎出来的理由与 `platform/mod.rs` 里那两条判据一样：这一半可以不碰 FFI 就被断言证明， +/// 而 FFI 的实际效果（窗口有没有多出来）在本仓库的验证环境里没有参考价值。 +#[must_use] +pub fn should_attach(stdout_usable: bool, stderr_usable: bool) -> bool { + !(stdout_usable && stderr_usable) +} + +/// 句柄是否指向一个能写的东西。 +/// +/// `GetFileType` 的返回值：1 磁盘 / 2 控制台 / 3 管道 / 4 remote，**0 = `FILE_TYPE_UNKNOWN`** +/// ——GUI 子系统进程从控制台启动时 `GetStdHandle` 给的就是 0（实测，见文件头表格 ③）。 +#[cfg(target_os = "windows")] +fn usable(handle: isize) -> bool { + handle != 0 && handle != INVALID_HANDLE_VALUE && { + // SAFETY: `GetFileType` 只按值收一个句柄、不持有指针、无所有权转移；无效句柄返回 0。 + (unsafe { GetFileType(handle) }) != 0 + } +} + +#[cfg(target_os = "windows")] +fn std_handles() -> (isize, isize) { + // SAFETY: `GetStdHandle` 只按值收一个索引常量，不持有指针、不改任何状态。 + (unsafe { GetStdHandle(STD_OUTPUT_HANDLE) }, unsafe { + GetStdHandle(STD_ERROR_HANDLE) + }) +} + +/// 让 GUI 子系统进程的输出接回父进程控制台（详见模块文档的四情形表）。 +/// +/// 幂等、不可失败（失败也是一种结论）：`out`/`err` 都可用时**一个字节都不动**， +/// 否则调一次 `AttachConsole(ATTACH_PARENT_PROCESS)` 再回读。 +#[must_use] +pub fn attach_parent_console() -> ConsoleOutcome { + #[cfg(not(target_os = "windows"))] + { + ConsoleOutcome::NotWindows + } + #[cfg(target_os = "windows")] + { + let before = std_handles(); + if !should_attach(usable(before.0), usable(before.1)) { + return ConsoleOutcome::AlreadyUsable { handles: before }; + } + // SAFETY: `AttachConsole` 只按值收一个 pid 常量（-1 = 父进程）；它不返回指针、 + // 不转移所有权，失败就是失败（父子关系不变、也没有窗口被创建）。 + let attached = (unsafe { AttachConsole(ATTACH_PARENT_PROCESS) }) != 0; + // 失败原因只进诊断文本（不改控制流）：返回值已经说明成败，这个码解释「为什么」。 + let last_error = unsafe { GetLastError() }; + let after = std_handles(); + if attached && usable(after.0) && usable(after.1) { + ConsoleOutcome::Attached { before, after } + } else { + // 附着成功但句柄仍不可用，与「父进程根本没有控制台」在调用点上是同一件事： + // 都没有可写的输出通道，所以合并成一个结论（`describe` 里照样带着读数）。 + ConsoleOutcome::NoConsole { + before, + after, + last_error, + } + } + } +} + +#[cfg(test)] +mod tests { + use super::{should_attach, ConsoleOutcome}; + + #[test] + fn truth_table_attach_only_when_a_stream_is_missing() { + // ①②：两个都在 → 绝不 attach（否则用户的重定向会被打坏）。 + assert!(!should_attach(true, true)); + // ③④：任意一个缺失 → 尝试 attach。三条都写出来，防止谁把它简化成 `!stdout_usable`。 + assert!(should_attach(false, true)); + assert!(should_attach(true, false)); + assert!(should_attach(false, false)); + } + + #[test] + fn describe_carries_the_runtime_readings() { + // 报告里贴的是这些行：句柄值必须真的出现在文本里，不然「已附着」就只是一句话。 + // 下面的 0xE4/0xE8 是**示例值**（真实读数随进程与控制台实例变化，见模块文档 ③）。 + let attached = ConsoleOutcome::Attached { + before: (0, 0), + after: (0xE4, 0xE8), + }; + let text = attached.describe(); + assert!(text.contains("0x0→0xE4"), "{text}"); + assert!(text.contains("0xE8"), "{text}"); + assert!(attached.output_visible()); + + let missing = ConsoleOutcome::NoConsole { + before: (0, 0), + after: (0, 0), + last_error: 6, + }; + assert!(missing.describe().contains("GetLastError=6")); + assert!(!missing.output_visible()); + } + + #[test] + fn already_usable_says_nothing_was_touched() { + let outcome = ConsoleOutcome::AlreadyUsable { + handles: (0x20C, 0x1F0), + }; + assert!(outcome.describe().contains("未 attach")); + assert!(outcome.output_visible()); + assert!(!ConsoleOutcome::NotWindows.output_visible()); + } +} 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..df08207 --- /dev/null +++ b/crates/app-iced/src/platform/win32/corner.rs @@ -0,0 +1,370 @@ +//! M116 / M182：窗口外框圆角的**判据**（纯函数，零 `unsafe`、零 FFI、零环境读取）。 +//! +//! ## 判据为什么单独拎出来 +//! +//! 「能不能圆」= 用户策略 × 宿主平台 × 渲染档，这几件事**可以被断言证明**；而合成器的**视觉** +//! 结果在本仓库的验证环境（RDP 断连、抓屏失效、无 Mac 真机）上没有参考价值。把可测的那一半独立 +//! 出来，才有「有测试的判据 + 没测试的观感」这条诚实的分界（与 [`super::super::effective_window_alpha`] +//! 同一套分法）。 +//! +//! 真正下发给窗口的动作在 [`super::transparency`]（`unsafe` 落点之一，另一个是 [`super::console`]）。 +//! +//! ## 平台矩阵（M182 修订：非 Windows 不再是「未知」一格） +//! +//! | 平台 | `source` | 谁画圆角 | 依据级别 | +//! |---|---|---|---| +//! | Win11 / Server 2025（build ≥ 22000） | `dwm` | DWM（我们只下发偏好） | 写入被接受 = **本机 API 实测**；「圆没圆」= **未验**（Server 2025 上实测无圆角，见下） | +//! | Win10 及更早（build < 22000） | `square` + `os-build` / `cpu-tier` | 没人 | 「该属性不存在」= **外部文档证据**；本机没有 Win10 | +//! | Windows 版本读不到 | `square` + `unknown-os` | 没人 | 探测失败，不猜 | +//! | macOS | `compositor` + `borderless` | 本该窗口服务器，但**它只裁 titled 窗**，我们是 borderless ⇒ 没人 | **源码级证据**（见 [`crate::platform::macos`]） | +//! | Linux X11 / Wayland | `compositor` + `client-side` | 本该合成器，但协议里没有圆角这回事，CSD 窗没人裁 | **规范级证据**（见 [`crate::platform::linux`]） | +//! | 其余（FreeBSD / Android / wasm…） | `square` + `unsupported` | 没人 | 不承诺 | +//! +//! ⚠️ **「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` 同族。 +//! +//! ④ **整窗 α 会关掉圆角**（tower 裁定 A / D47：整窗透明度优先于 DWM 圆角）：α < 1 时我们补 +//! `WS_EX_LAYERED`，此时系统会忽略圆角请求——请求照样发出（日志里 `pref=` 有值）， +//! 只是不生效；α 回到 1.0 就恢复。日志用 `suppressed_by=window_alpha` 记这一条**观测事实**。 +//! +//! 「圆角长什么样」归真机验收，证据目录见 `DevDocs/artifacts/m116/`。 + +use unlucky_presenter::prefs::{WindowCorner, WindowsVersion, WIN11_MIN_BUILD}; + +use crate::platform::host::HostOs; +use crate::Backend; + +/// 一次「圆角该从哪来」的判定结果（M116 / M182）。 +/// +/// 三档**互斥**，回答的是同一个问题：「这个窗口的四角由谁负责」。 +/// +/// | 来源 | 谁负责 | 我们做什么 | +/// |---|---|---| +/// | [`CornerSource::Dwm`] | Windows 的 DWM（半径不由我们定，也读不到） | 只下发 `DWMWA_WINDOW_CORNER_PREFERENCE` | +/// | [`CornerSource::Compositor`] | 平台的窗口合成器 / 窗口服务器**按它自己的规则**（M182 新增） | **什么都不做**：不下发偏好、不自绘裁切（D46） | +/// | [`CornerSource::Square`] | 没人 | Windows 上显式下发 `DWMWCP_DONOTROUND`，把「方」也变成可观测的选择 | +/// +/// **「合成器」这一档不等于「一定有圆角」**：它只说「圆角的决定权不在我们手里」。落到这一档 +/// 之后到底圆不圆，由 `excluded` 那一栏如实交代（macOS = `borderless`、Linux = `client-side`）。 +/// 把它写成「跟随合成器 ⇒ 圆角」正是 M182 要修的误读。 +/// +/// **没有 `Self`（自绘圆角）这一档**，这是刻意的（用户定案 2026-11-03 + tower 裁定，D46 第 4 条）： +/// 窗口是 `decorations=false` + 自绘标题栏 + 整窗 `LWA_ALPHA`，自绘圆角意味着把内容层裁成圆角， +/// 那会把标题栏三键与边缘缩放热区一起裁掉；系统也不暴露圆角半径（无 API 可读）， +/// 「固定 8/12/16」只是凭空维护一个数字。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum CornerSource { + /// DWM 系统圆角（Win11 / Server 2025 内核，build ≥ [`WIN11_MIN_BUILD`]）。 + Dwm, + /// 平台跟随合成器（M182）：圆角归属交给窗口合成器 / 窗口服务器，我们既不下发也不自绘。 + Compositor, + /// 直角（用户选择、系统不支持、或该平台不承诺）。 + Square, +} + +impl CornerSource { + /// 日志取值（`corner=… source=dwm|compositor|square`）。 + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::Dwm => "dwm", + Self::Compositor => "compositor", + Self::Square => "square", + } + } + + /// 是否要求 DWM 真去画圆角（唯一需要下发 FFI 的那一档）。 + #[must_use] + pub const fn is_dwm(self) -> bool { + matches!(self, Self::Dwm) + } + + /// 是否把圆角归属交给合成器（M182：只在非 Windows 上可能为真）。 + #[must_use] + pub const fn is_compositor(self) -> bool { + matches!(self, Self::Compositor) + } +} + +/// 为什么**没有**圆角（`None` = 就是 DWM 圆角）。日志里逐字打出来。 +/// +/// 为什么要这个枚举而不是一个 `bool`：用户报的现象是「别的窗口都有圆角，只有我们的没有」， +/// 于是「没圆角」至少有六种完全不同的原因，混成一个 `square` 以后没人能分辨 +/// 「没生效」与「生效了但看不见」（M116 任务书原话）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum CornerExclusion { + /// 用户在设置里选了「直角」。 + UserSquare, + /// 系统太老：Win10 及更早（build < [`WIN11_MIN_BUILD`]）——DWM 没有这个偏好属性。 + OsBuild, + /// Windows 版本探测不出来（注册表读不到 / 有东西在骗版本号）。**只在 Windows 上出现**。 + UnknownOs, + /// 非 DWM 平台上的软件渲染档：圆角只能靠自绘/`SetWindowRgn` 毛边路，D36 的 + /// 「CPU 档不碰合成技巧」优先，所以退回直角。 + CpuTier, + /// macOS（M182）：窗口是 `decorations=false` ⇒ winit 给 `NSWindowStyleMask::Borderless` + /// （**没有 `Titled`**）⇒ 窗口服务器不给这类窗口做圆角裁剪。不是「系统不支持圆角」， + /// 是「我们交上去的形状不在会被裁的那一类里」。证据见 [`crate::platform::macos`]。 + BorderlessFrame, + /// Linux（M182）：`xdg-shell` / X11 协议里都没有「圆角半径」这种东西，CSD 无边框窗 + /// 合成器不会替我们裁（谁装饰谁负责，而我们自己声明了 CSD）。D46 又排除自绘 ⇒ 直角。 + /// 证据与各合成器差异见 [`crate::platform::linux`]。 + ClientSideFrame, + /// 不认识的平台（FreeBSD / Android / wasm …）：不承诺。 + Unsupported, +} + +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", + Self::BorderlessFrame => "borderless", + Self::ClientSideFrame => "client-side", + Self::Unsupported => "unsupported", + } + } +} + +/// 判定结果：来源 + 排除原因 + 宿主平台 + Windows 版本（日志与测试共用）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct CornerPlan { + /// 圆角从哪来。 + pub source: CornerSource, + /// `None` = 走合成器/DWM；`Some(..)` = 这一档没有圆角，并说明为什么。 + pub excluded: Option, + /// 宿主平台族（M182：判据的输入，日志里也打出来）。 + pub host: HostOs, + /// 探测到的 Windows 版本（`None` = 非 Windows / 读不到）。 + pub os: Option, +} + +impl CornerPlan { + /// 日志行：`corner=policy=system host=macos source=compositor os=n/a excluded_reason=borderless radius=system`。 + /// + /// **`radius=system` 是刻意的**：系统不暴露圆角半径，我们也不自己定一个数字 + /// （用户定案取消了 8/12/16 档），所以这一栏永远只说「系统决定」。 + /// + /// **`host=` 是 M182 加的**：用户看到的那行 `source=square os=unknown` 之所以难判断， + /// 就是因为「未知」同时被 Windows 探测失败和「这台根本不是 Windows」共用。有了 `host=` + /// 与 `excluded_reason=borderless|client-side`，同一行就能自己解释完。 + /// + /// **非 Windows 的 `os=n/a`**：那一栏装的是 Windows 版本，在 macOS / Linux 上不是「没读到」， + /// 而是「跟本机无关」——写 `unknown` 会让人去找一个根本不存在的注册表项。 + #[must_use] + pub fn log_line(&self, policy: WindowCorner) -> String { + let os = match (self.host, self.os) { + (HostOs::Windows, Some(os)) => os.version_string(), + (HostOs::Windows, None) => "unknown".to_owned(), + _ => "n/a".to_owned(), + }; + format!( + "corner=policy={} host={} source={} os={os} excluded_reason={} radius=system", + policy.as_str(), + self.host.as_str(), + self.source.as_str(), + self.excluded.map_or("none", CornerExclusion::as_str), + ) + } +} + +/// 判定「这一次窗口该不该有系统圆角」（纯函数，不调 FFI、不读环境）。 +/// +/// 生产入口：平台取 [`HostOs::current`]（编译期常量），Windows 版本由调用方探测后传进来。 +/// 想验另外两行真值表时用 [`plan_corner_for`]——那是同一个判据，只是平台可以由测试喂。 +#[must_use] +pub fn plan_corner( + policy: WindowCorner, + os: Option, + backend: Backend, +) -> CornerPlan { + plan_corner_for(policy, HostOs::current(), os, backend) +} + +/// 真值表（`os` / `backend` 只对 Windows 行有意义）： +/// +/// | `policy` | `host` | `os.build` | backend | `source` | `excluded` | +/// |---|---|---|---|---|---| +/// | `Square` | 任意 | 任意 | 任意 | `Square` | `UserSquare` | +/// | `System` | Windows | `None` | 任意 | `Square` | `UnknownOs` | +/// | `System` | Windows | `< 22000` | GPU/Auto | `Square` | `OsBuild` | +/// | `System` | Windows | `< 22000` | CPU | `Square` | `CpuTier` | +/// | `System` | Windows | `>= 22000` | 任意 | `Dwm` | `None` | +/// | `System` | MacOs | 忽略 | 任意 | `Compositor` | `BorderlessFrame` | +/// | `System` | Linux | 忽略 | 任意 | `Compositor` | `ClientSideFrame` | +/// | `System` | Other | 忽略 | 任意 | `Square` | `Unsupported` | +/// +/// 为什么 CPU 档在 Win11 上**照样**用 DWM 圆角（**tower 2026-11-03 裁定，按此执行**）： +/// D36 的 CPU 档约束针对的是**我们自己的渲染路径**（面板 α / 玻璃 / 模糊要关、不许拿透明叠加 +/// 去换效果），而 DWM 圆角是**合成器侧**的效果，不增加我们的 GPU/CPU 绘制负担。所以 +/// 「CPU 档关掉 Win11 圆角」不是 D36 的要求，而是凭空造一个没人要的降级。 +/// +/// 反过来在非 DWM 平台上，圆角只剩「自绘裁切 / `SetWindowRgn` 毛边」这两条**我们自己的** +/// 合成技巧，那才是 D36 要拦的东西 ⇒ 那一格落 `cpu-tier` 而不是 `os-build` +/// （同一个直角，**原因不同**，日志里可分辨）。 +/// +/// macOS / Linux 两行**不看 `backend`**（M182）：我们根本不下发任何东西，也就没有「渲染档 +/// 要不要让步」这回事——CPU 档与 GPU 档在这两个平台上得到同一份判定，这是事实而不是遗漏。 +#[must_use] +pub fn plan_corner_for( + policy: WindowCorner, + host: HostOs, + os: Option, + backend: Backend, +) -> CornerPlan { + let square = |excluded| CornerPlan { + source: CornerSource::Square, + excluded: Some(excluded), + host, + os, + }; + + if policy == WindowCorner::Square { + return square(CornerExclusion::UserSquare); + } + match host { + // Windows：能不能圆是 DWM 的属性与版本问题，得问。 + HostOs::Windows => 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, + host, + os, + }, + }, + // macOS：圆角归窗口服务器，但我们交的是 borderless 窗（`decorations: false`）⇒ 它不裁。 + // 迁移成原生标题栏是另一件需要真机验收的事，配方见 `platform::macos`。 + HostOs::MacOs => CornerPlan { + source: CornerSource::Compositor, + excluded: Some(CornerExclusion::BorderlessFrame), + host, + os, + }, + // Linux：协议里没有圆角，CSD 窗由客户端装饰 ⇒ 没人替我们裁，自绘被 D46 排除。 + HostOs::Linux => CornerPlan { + source: CornerSource::Compositor, + excluded: Some(CornerExclusion::ClientSideFrame), + host, + os, + }, + HostOs::Other => square(CornerExclusion::Unsupported), + } +} + +/// 产品日志行的**唯一格式化落点**（纯函数：把四段文本拼成一个固定形状）。 +/// +/// ```text +/// [corner] corner=policy=system host=windows 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, + /// 下发时**有没有窗口句柄**：`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..1a8acbb --- /dev/null +++ b/crates/app-iced/src/platform/win32/corner/tests.rs @@ -0,0 +1,390 @@ +//! `win32::corner` 的单测（M116 从 `corner.rs` 搬出来：那个文件要守 400 行上限， +//! 而日志行的形状断言本身就有几十行）。 +//! +//! 判据与真实读数的出处：`DevDocs/artifacts/m116/probe-table.md`。 +//! +//! ## M182 的两条纪律（都来自复审 P1-1，别再退回原样） +//! +//! 1. **判据断言一律走 [`plan_corner_for`]，平台显式传值**。`plan_corner` 是**产品入口**， +//! 它读的是 `HostOs::current()`——同一个测试在 Windows 上绿、在 ubuntu 上就可能红。 +//! M182 首轮复审实测：本机（Windows）384+ 条全绿，而其中三条断言的是 Windows 的结果， +//! 合进 main 后 `ubuntu-latest` 的 `test` job 会当场红。 +//! 2. **`plan_corner` 只留一条用例**，且那条必须**与宿主无关**： +//! [`the_production_entry_forwards_to_the_pure_judgement`] 两边都用同一个 `HostOs::current()`， +//! 所以它在任何平台上都成立，只证「产品入口确实转发到纯函数」。 +//! +//! 「非 Windows」那一组断言住在 [`platforms`]（本文件守 400 行上限）。 + +use super::{format_line, plan_corner, plan_corner_for, CornerExclusion, CornerPlan, CornerSource}; +use crate::platform::host::HostOs; +use crate::Backend; +use unlucky_presenter::prefs::{WindowCorner, WindowsVersion, WIN11_MIN_BUILD}; + +mod platforms; + +/// 本机实测版本（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) +} + +/// 判据断言用的固定宿主：**永远是 Windows**，与本机实际跑在哪个系统上无关。 +/// +/// 为什么要有这个包装而不是直接写 `HostOs::Windows`：写一次名字就够了，以后想给 Linux / +/// macOS 也加 Windows 专属断言时，改这一处即可。 +fn on_windows(policy: WindowCorner, os: Option, backend: Backend) -> CornerPlan { + plan_corner_for(policy, HostOs::Windows, os, backend) +} + +/// **抓得住**：判定链的顺序与每一格的原因码（把 `policy`/`host`/`os`/`backend` 任一条判反都会红）。 +/// **抓不住**：DWM 到底有没有真画圆角（那要像素，见 `platform/win32` 的探针输出）。 +#[test] +fn truth_table_policy_host_os_backend() { + let cases = [ + // policy=Square：任何平台/系统/后端都直角，原因是用户选的。 + ( + WindowCorner::Square, + HostOs::Windows, + Some(win11()), + Backend::Gpu, + CornerSource::Square, + Some(CornerExclusion::UserSquare), + ), + ( + WindowCorner::Square, + HostOs::Linux, + None, + Backend::Cpu, + CornerSource::Square, + Some(CornerExclusion::UserSquare), + ), + // policy=System + Windows 上探测不出系统：不许猜「Win11」。 + ( + WindowCorner::System, + HostOs::Windows, + None, + Backend::Gpu, + CornerSource::Square, + Some(CornerExclusion::UnknownOs), + ), + // Win10：直角，GPU 档原因是版本、CPU 档原因是渲染档（同一个直角，原因不同）。 + ( + WindowCorner::System, + HostOs::Windows, + Some(win10()), + Backend::Gpu, + CornerSource::Square, + Some(CornerExclusion::OsBuild), + ), + ( + WindowCorner::System, + HostOs::Windows, + Some(win10()), + Backend::Auto, + CornerSource::Square, + Some(CornerExclusion::OsBuild), + ), + ( + WindowCorner::System, + HostOs::Windows, + Some(win10()), + Backend::Cpu, + CornerSource::Square, + Some(CornerExclusion::CpuTier), + ), + // Win11 / Server 2025：三个后端都用 DWM（D36 只管我们自己的合成技巧）。 + ( + WindowCorner::System, + HostOs::Windows, + Some(win11()), + Backend::Gpu, + CornerSource::Dwm, + None, + ), + ( + WindowCorner::System, + HostOs::Windows, + Some(win11()), + Backend::Cpu, + CornerSource::Dwm, + None, + ), + // macOS（M182）：圆角归窗口服务器，但我们交的是 borderless 窗 ⇒ 它不裁。 + ( + WindowCorner::System, + HostOs::MacOs, + None, + Backend::Gpu, + CornerSource::Compositor, + Some(CornerExclusion::BorderlessFrame), + ), + // Linux（M182）：CSD 窗没人裁，自绘被 D46 排除。 + ( + WindowCorner::System, + HostOs::Linux, + None, + Backend::Gpu, + CornerSource::Compositor, + Some(CornerExclusion::ClientSideFrame), + ), + // 不认识的平台：不承诺。 + ( + WindowCorner::System, + HostOs::Other, + None, + Backend::Gpu, + CornerSource::Square, + Some(CornerExclusion::Unsupported), + ), + ]; + + for (policy, host, os, backend, want_source, want_excluded) in cases { + let plan = plan_corner_for(policy, host, os, backend); + assert_eq!( + plan.source, want_source, + "policy={policy:?} host={host:?} os={os:?} backend={backend:?}" + ); + assert_eq!( + plan.excluded, want_excluded, + "policy={policy:?} host={host:?} os={os:?} backend={backend:?} 的原因码" + ); + assert_eq!( + plan.host, host, + "判定必须把输入的平台原样带回来（日志要用）" + ); + } +} + +/// 边界：`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!( + on_windows(WindowCorner::System, Some(at), Backend::Gpu).source, + CornerSource::Dwm + ); + let below = WindowsVersion::new(10, 0, WIN11_MIN_BUILD - 1); + assert_eq!( + on_windows(WindowCorner::System, Some(below), Backend::Gpu).source, + CornerSource::Square, + "build 21999 = Win10 22H2 家族末尾，不能算 Win11" + ); +} + +/// 日志行的形状：五个字段都在，且 `excluded_reason=none` 与 `reason=user` 不许混。 +/// +/// 为什么要钉这一条：这行是「后来的人分辨没生效 / 生效了看不见」的唯一依据（任务书原话）， +/// 少一栏就等于把这条线索丢掉。M182 新增的 `host=` 与「非 Windows 的 `os=n/a`」在这里钉死。 +#[test] +fn the_log_line_carries_every_field() { + let dwm = on_windows(WindowCorner::System, Some(win11()), Backend::Gpu) + .log_line(WindowCorner::System); + assert!(dwm.starts_with("corner=policy=system"), "{dwm}"); + assert!(dwm.contains("host=windows"), "{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 = on_windows(WindowCorner::Square, Some(win11()), Backend::Gpu) + .log_line(WindowCorner::Square); + assert!(square.contains("source=square"), "{square}"); + assert!(square.contains("excluded_reason=user"), "{square}"); + + // Windows 上「版本读不到」：`os=unknown` **配上** `host=windows` 才是完整的真话。 + let unknown = + on_windows(WindowCorner::System, None, Backend::Gpu).log_line(WindowCorner::System); + assert!(unknown.contains("host=windows"), "{unknown}"); + assert!(unknown.contains("os=unknown"), "{unknown}"); + assert!(unknown.contains("excluded_reason=unknown-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 = on_windows(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 host=windows 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", + &on_windows(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 host=windows 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 = + on_windows(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 = + on_windows(WindowCorner::System, Some(win10), Backend::Cpu).log_line(WindowCorner::System); + assert!(cpu.contains("excluded_reason=cpu-tier"), "{cpu}"); +} + +/// **产品入口只有一条用例**，且它**与宿主无关**（复审 P1-1 的要求）。 +/// +/// 断言的是「`plan_corner` 就是 `plan_corner_for(HostOs::current(), …)`」：两边喂同一个 +/// `HostOs::current()`，所以在 Windows / ubuntu / macOS 上恒成立——它证明的是**转发**， +/// 不是某个平台的结果。任何一个平台的结果都由 [`truth_table_policy_host_os_backend`] +/// 显式传 `HostOs` 钉住。 +/// +/// **抓得住**：`plan_corner` 里偷偷改成写死的 `HostOs::Windows`（那样 ubuntu 上这条会红）、 +/// 或者干脆不再转发（判据分叉）。 +#[test] +fn the_production_entry_forwards_to_the_pure_judgement() { + for policy in [WindowCorner::System, WindowCorner::Square] { + for os in [None, Some(win10()), Some(win11())] { + for backend in [Backend::Gpu, Backend::Cpu, Backend::Auto] { + let production = plan_corner(policy, os, backend); + assert_eq!( + production, + plan_corner_for(policy, HostOs::current(), os, backend), + "plan_corner 必须原样转发到纯函数（policy={policy:?} os={os:?} backend={backend:?}）" + ); + assert_eq!(production.host, HostOs::current()); + } + } + } +} + +/// 每个原因码都是一个**非空、无空格、互不重复**的稳定串（复审 P2-1：`unknown-os` 此前没有任何断言）。 +/// +/// 为什么值得一条表测试：这些串是产品日志里 `excluded_reason=` 的唯一取值，而它们只在 +/// **构建这样一张表**的时候才会被逐个过一遍——散在断言里时，`unknown-os` 这种「只在一台 +/// Windows 机器、且版本探测失败时才出现」的值最容易一直没有断言（复审就是这么抓到的）。 +/// +/// **抓得住**：两个原因码共用一个串（日志再也分不清原因）、串里混进空格（那一栏会被截断）、 +/// 或者某一条被改成空串。 +#[test] +fn every_exclusion_code_is_a_stable_non_empty_string() { + use std::collections::BTreeSet; + + let codes = [ + (CornerExclusion::UserSquare, "user"), + (CornerExclusion::OsBuild, "os-build"), + (CornerExclusion::UnknownOs, "unknown-os"), + (CornerExclusion::CpuTier, "cpu-tier"), + (CornerExclusion::BorderlessFrame, "borderless"), + (CornerExclusion::ClientSideFrame, "client-side"), + (CornerExclusion::Unsupported, "unsupported"), + ]; + + let mut seen = BTreeSet::new(); + for (reason, code) in codes { + assert_eq!(reason.as_str(), code, "{reason:?} 的日志取值"); + assert!( + !code.is_empty() && !code.contains(char::is_whitespace), + "原因码必须是单个词（日志按空格分栏）：{code:?}" + ); + assert!(seen.insert(code), "两个原因码共用了同一个串：{code}"); + } + assert_eq!(seen.len(), 7, "目前共七个原因码，少一个就是漏了断言"); +} + +/// **同一策略 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, CornerApplied}; + + let os = WindowsVersion::new(10, 0, 26_100); + let plan = on_windows(WindowCorner::System, Some(os), Backend::Gpu); + + // 模拟「滑条被拖动 20 次」：每次都是同一个策略、同一个系统、句柄一直在。 + let mut last: Option = 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 = on_windows(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 = 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/corner/tests/platforms.rs b/crates/app-iced/src/platform/win32/corner/tests/platforms.rs new file mode 100644 index 0000000..7c900c8 --- /dev/null +++ b/crates/app-iced/src/platform/win32/corner/tests/platforms.rs @@ -0,0 +1,188 @@ +//! 「非 Windows」那一组断言（M182）：`HostOs` 是判据的**参数**，所以本机（Windows）也能验。 +//! +//! 为什么单独成文件：`corner/tests.rs` 已经贴着 400 行上限（M182 加进来的三行平台断言 +//! 正好是压垮它的那部分）。 + +use super::{win10, win11}; +use crate::platform::host::HostOs; +use crate::platform::win32::corner::{plan_corner_for, CornerExclusion, CornerSource}; +use crate::Backend; +use unlucky_presenter::prefs::WindowCorner; + +const ALL_HOSTS: [HostOs; 4] = [HostOs::Windows, HostOs::MacOs, HostOs::Linux, HostOs::Other]; +const ALL_BACKENDS: [Backend; 3] = [Backend::Gpu, Backend::Cpu, Backend::Auto]; + +/// **M182 的核心断言**：`os = None` 不再等于「未知平台」。 +/// +/// 同一个 `(System, None, Gpu)` 三元组，在 Windows 上是「版本读不出来」（`unknown-os`）， +/// 在 macOS / Linux 上是「这一栏跟本机无关」（`borderless` / `client-side`）。把三行写成 +/// 同一格就是用户看到的那句 `source=square os=unknown`——它同时糊掉了「探测失败」与 +/// 「这台根本不是 Windows」两件事。 +/// +/// **抓得住**：谁把非 Windows 两行改回 `Square`/`UnknownOs`（或把 `host` 从判据里摘掉）。 +#[test] +fn a_missing_windows_version_does_not_mean_unknown_platform() { + let rows: Vec<_> = [HostOs::Windows, HostOs::MacOs, HostOs::Linux] + .into_iter() + .map(|host| { + let plan = plan_corner_for(WindowCorner::System, host, None, Backend::Gpu); + (host, plan.source, plan.excluded) + }) + .collect(); + + assert_eq!( + rows, + vec![ + ( + HostOs::Windows, + CornerSource::Square, + Some(CornerExclusion::UnknownOs) + ), + ( + HostOs::MacOs, + CornerSource::Compositor, + Some(CornerExclusion::BorderlessFrame) + ), + ( + HostOs::Linux, + CornerSource::Compositor, + Some(CornerExclusion::ClientSideFrame) + ), + ] + ); +} + +/// 非 Windows 的日志行必须自己解释完：有 `host=`、`os=n/a`（不是 `unknown`）、原因码说人话。 +/// +/// **抓得住**：把 `os=` 在非 Windows 上也写成 `unknown`——那会让人去找一个不存在的注册表项。 +#[test] +fn the_non_windows_log_line_explains_itself() { + let mac = plan_corner_for(WindowCorner::System, HostOs::MacOs, None, Backend::Gpu) + .log_line(WindowCorner::System); + assert!(mac.contains("host=macos"), "{mac}"); + assert!(mac.contains("os=n/a"), "{mac}"); + assert!(!mac.contains("os=unknown"), "{mac}"); + assert!(mac.contains("source=compositor"), "{mac}"); + assert!(mac.contains("excluded_reason=borderless"), "{mac}"); + + let linux = plan_corner_for(WindowCorner::System, HostOs::Linux, None, Backend::Cpu) + .log_line(WindowCorner::System); + assert!(linux.contains("host=linux"), "{linux}"); + assert!(linux.contains("os=n/a"), "{linux}"); + assert!(linux.contains("excluded_reason=client-side"), "{linux}"); + + // Windows 上 `os=unknown` 仍要保留它本来的意思：真的没探测到版本。 + let win = plan_corner_for(WindowCorner::System, HostOs::Windows, None, Backend::Gpu) + .log_line(WindowCorner::System); + assert!( + win.contains("host=windows") && win.contains("os=unknown"), + "{win}" + ); +} + +/// macOS / Linux 两行**不看渲染档**：我们什么都不下发，也就没有「CPU 档要不要让步」这回事。 +/// +/// **抓得住**：有人按 Windows 的形状给这两行加 `backend` 分支（那会变成凭空造的降级）。 +#[test] +fn the_non_windows_rows_ignore_the_backend() { + for host in [HostOs::MacOs, HostOs::Linux] { + let plans: Vec<_> = ALL_BACKENDS + .into_iter() + .map(|backend| plan_corner_for(WindowCorner::System, host, None, backend)) + .collect(); + for plan in &plans { + assert_eq!( + (plan.source, plan.excluded), + (plans[0].source, plans[0].excluded), + "{host:?}：三个渲染档必须得到同一份判定（实际 {plan:?}）" + ); + } + } +} + +/// macOS 与 Linux **不许共用同一个原因码**：两边的机制不同（缺 `Titled` 位 ≠ 协议里没有圆角）。 +/// +/// **抓得住**：复制粘贴把 Linux 行也标成 `borderless`（那会让以后看日志的人去研究 +/// `NSWindowStyleMask`，而 Linux 上根本没有这个东西）。 +#[test] +fn macos_and_linux_report_different_reasons() { + let mac = plan_corner_for(WindowCorner::System, HostOs::MacOs, None, Backend::Gpu); + let linux = plan_corner_for(WindowCorner::System, HostOs::Linux, None, Backend::Gpu); + assert_ne!(mac.excluded, linux.excluded); + assert_eq!(mac.excluded, Some(CornerExclusion::BorderlessFrame)); + assert_eq!(linux.excluded, Some(CornerExclusion::ClientSideFrame)); + // 两行都不是「我们要求 DWM 画」，而是「决定权在合成器」（`is_compositor` / `is_dwm` + // 这两个小判据的用处就在这里：以后加平台时先问一句「这一档算不算合成器档」）。 + assert!(mac.source.is_compositor() && linux.source.is_compositor()); + assert!(!mac.source.is_dwm() && !linux.source.is_dwm()); +} + +/// `Compositor` 这一档**不许**在 Windows 上出现；`Dwm` 也**不许**在非 Windows 上出现。 +/// +/// **抓得住**：「非 Windows 一律 compositor」写成「一律不 square」这类图省事的判定， +/// 或者反过来把 Windows 的 DWM 判据搬去 Linux 假装能用（M182 任务书点名禁止）。 +#[test] +fn each_source_stays_on_its_own_platforms() { + for os in [None, Some(win10()), Some(win11())] { + for backend in ALL_BACKENDS { + let win = plan_corner_for(WindowCorner::System, HostOs::Windows, os, backend); + assert_ne!( + win.source, + CornerSource::Compositor, + "Windows 上不许出现 compositor 档：{win:?}" + ); + } + } + for host in [HostOs::MacOs, HostOs::Linux, HostOs::Other] { + for backend in ALL_BACKENDS { + // 非 Windows 传一个「看起来像 Win11」的版本号进去：判据**不许**被它带偏。 + let plan = plan_corner_for(WindowCorner::System, host, Some(win11()), backend); + assert_ne!( + plan.source, + CornerSource::Dwm, + "{host:?} 上没有 DWM：{plan:?}" + ); + } + } +} + +/// `source` 与 `excluded` 不许互相撒谎：说「从合成器来」就必须说清为什么没来。 +/// +/// **抓得住**：把 macOS/Linux 写成 `source=compositor excluded_reason=none`——那行的字面意思是 +/// 「已经按合成器圆了」，而用户屏幕上仍是直角（正是 M182 要修的那种误读）。 +#[test] +fn the_source_never_claims_a_corner_that_the_exclusion_denies() { + for policy in [WindowCorner::System, WindowCorner::Square] { + for host in ALL_HOSTS { + for os in [None, Some(win10()), Some(win11())] { + for backend in ALL_BACKENDS { + let plan = plan_corner_for(policy, host, os, backend); + match plan.source { + // 真下发了 DWM 偏好时不该有原因码。 + CornerSource::Dwm => assert_eq!(plan.excluded, None, "{plan:?}"), + // 合成器档在当前实现里**永远**带原因码（没有任何平台真拿到系统圆角）。 + CornerSource::Compositor => assert!( + plan.excluded.is_some(), + "source=compositor 必须交代原因：{plan:?}" + ), + CornerSource::Square => assert!(plan.excluded.is_some(), "{plan:?}"), + } + } + } + } + } +} + +/// 用户选「直角」必须在**每一个**平台上都赢（包括将来真的迁移了标题栏的 macOS）。 +/// +/// **抓得住**：把 `policy == Square` 的短路写在 `match host` 之后或写进某个平台分支里。 +#[test] +fn the_user_square_choice_wins_on_every_platform() { + for host in ALL_HOSTS { + for backend in ALL_BACKENDS { + let plan = plan_corner_for(WindowCorner::Square, host, Some(win11()), backend); + assert_eq!(plan.source, CornerSource::Square, "{host:?} {backend:?}"); + assert_eq!(plan.excluded, Some(CornerExclusion::UserSquare)); + } + } +} 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..7fca34b --- /dev/null +++ b/crates/app-iced/src/platform/win32/mod.rs @@ -0,0 +1,19 @@ +//! Win32 专属的窗口能力。 +//! +//! | 子模块 | 是什么 | 有没有 `unsafe` | +//! |---|---|---| +//! | [`transparency`] | D36 定案的整窗 α 唯一实现落点（也是 M116 的 DWM 圆角落点） | **有**（落点之一） | +//! | [`corner`] | M116 的圆角**判据**：策略 × 系统版本 × 渲染档 → 来源与原因码 | 没有（纯函数） | +//! | [`console`] | M196：GUI 子系统进程的输出接回父进程控制台（`AttachConsole`） | **有**（落点之二） | +//! +//! 目录形态（而非 `win32.rs` 单文件）是为了让「每个平台一份实现」在路径上一眼可见： +//! 将来 macOS / Wayland 的对应能力各自成目录，互不干扰。 +//! +//! **非 Windows 平台也在编译**：`transparency` 里的公开函数有同签名的空实现， +//! `corner` 的判据在探测不到系统版本时给出「直角 + `unknown-os`」，`console` 返回 +//! [`console::ConsoleOutcome::NotWindows`]，所以调用点不需要 `#[cfg]`， +//! 行为（返回「本平台不支持」）可被测试断言。 + +pub mod console; +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..073ab94 --- /dev/null +++ b/crates/app-iced/src/platform/win32/transparency.rs @@ -0,0 +1,398 @@ +//! 整窗透明度（D36）：整窗 α 的**唯一**实现落点。 +//! +//! ## 为什么只有这里有 unsafe +//! +//! 窗口级 α 没有任何「安全」的 Rust API 可达：`SetLayeredWindowAttributes` 是 Win32 的 +//! 唯一路径（D36 逐路核实过 wgpu / iced / winit 都没有代理入口）。所以把窗口 FFI 面收在 +//! 这一处，其余一层（[`super::super::effective_window_alpha`]）保持纯函数。 +//! 守门在 `.github/workflows/guards.yml` 的 `unsafe-scope` job：全仓带这个 allow 的文件集合必须 +//! **恰好等于**期望集合（M196 起是两处：本文件与 `console.rs`，各自把 FFI 收在自己文件里）。 +//! +//! ## 只做 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 比对**文件集合**（M196 起是两个：本文件与 console.rs）。 +#![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-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::(), + u32::try_from(std::mem::size_of::()).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) { + let mut value: u32 = 0; + // SAFETY: out 指针指向本栈帧里的 `u32`，`size` 与之一致；失败时 DWM 不写。 + let hr = unsafe { + DwmGetWindowAttribute( + hwnd, + attribute, + (&raw mut value).cast::(), + u32::try_from(std::mem::size_of::()).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 { + 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 { + let mut rect = WinRect::default(); + // SAFETY: 同 `dwm_get_u32`，只是 out 类型换成 `RECT`。 + let hr = unsafe { + DwmGetWindowAttribute( + hwnd, + attribute, + (&raw mut rect).cast::(), + u32::try_from(std::mem::size_of::()).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 { + 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 = "STATIC\0".encode_utf16().collect(); + let title: Vec = "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) -> 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..718b129 --- /dev/null +++ b/crates/app-iced/src/platform/win32/transparency/dwm.rs @@ -0,0 +1,316 @@ +//! DWM 圆角（M116）：把 [`CornerPlan`](super::super::corner::CornerPlan) 落成一次属性下发。 +//! +//! ## 本文件零 `unsafe`、零 `extern` +//! +//! `DwmSetWindowAttribute` / `DwmGetWindowAttribute` 的声明与调用点在 [`super`] +//! （`unsafe` 落点之一；另一个是 `super::super::console`）；这里只做「哪一档 → 哪个属性值」的映射、`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` 或旧值）。 + +// M147：本模块七项（三个属性号 + 四个读函数）只在 Windows 上有使用者——唯一调用方 `probe::run_one` +// 的 Windows 版被门着，Linux + `-D warnings` 下就是 dead_code 错。用模块级 `cfg_attr` 而不是 +// 逐项 `cfg`：`cfg` 会把这些项连同本文件那几条与平台无关的单测一起门掉（逐项 `cfg_attr` 多 7 行，顶破红线）。 +#![cfg_attr(not(target_os = "windows"), allow(dead_code))] +/// `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, + /// 回读那一次的 `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 的启发式决定——那正是我们要么拿到、要么明确放弃的东西。 +/// +/// M182 的 `Compositor` 档（跟随合成器）在 Windows 上**不可达**（`plan_corner_for` 不产出它， +/// 单测钉着这一点）；真要出现，正确的落点是默认值 `0`（= 让系统自己决定）， +/// 而不是被当成「强制直角」——否则 `source=compositor` 那行日志会与下发值自相矛盾。 +#[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::Compositor => 0, + 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); + 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) { + #[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 { + #[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 { + #[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 { + #[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; + +/// **抓得住**：`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/dwm/tests.rs b/crates/app-iced/src/platform/win32/transparency/dwm/tests.rs new file mode 100644 index 0000000..1550d5a --- /dev/null +++ b/crates/app-iced/src/platform/win32/transparency/dwm/tests.rs @@ -0,0 +1,124 @@ +//! `transparency::dwm` 的单测（M182 从 `dwm.rs` 内联挪出来：那个文件贴着 400 行上限， +//! 而 M182 要往 `preference_for` 里加第三档映射）。 +//! +//! 挪动是**逐行照搬** + M182 的新断言，没有重写判据。 + +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::host::HostOs; +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); +} + +/// M182 的第三档：`Compositor`（跟随合成器）在 Windows 上**不会出现**（见 +/// `plan_corner_for` 的真值表），所以这里钉两件事——① match 必须写全、不许 panic； +/// ② 真要出现时它落到 `DWMWCP_DEFAULT`（`0` = 让 DWM 自己决定），而不是被偷偷当成直角。 +/// +/// **抓得住**：有人把这一臂写成 `DWMWCP_DONOTROUND`（那就成了「说跟随合成器、实际强制直角」， +/// 与 `source=compositor` 那行日志自相矛盾）。 +#[test] +fn the_compositor_tier_maps_to_letting_the_system_decide() { + assert_eq!( + preference_for(CornerSource::Compositor), + 0, + "Compositor 档必须落到 DWMWCP_DEFAULT(0)，不是 DONOTROUND" + ); + // 且它在 Windows 的判据里不可达（真值表不会产出它）。 + for os in [None, Some(WindowsVersion::new(10, 0, 26_100))] { + for backend in [ + crate::Backend::Gpu, + crate::Backend::Cpu, + crate::Backend::Auto, + ] { + let plan = crate::platform::win32::corner::plan_corner_for( + unlucky_presenter::prefs::WindowCorner::System, + HostOs::Windows, + os, + backend, + ); + assert_ne!(plan.source, CornerSource::Compositor, "{plan:?}"); + } + } +} + +/// 无效句柄：**不下发**、也不 panic。句柄 0 走 `NoWindow`（还没拿到窗口 ≠ 平台不支持）。 +#[test] +fn a_missing_window_is_reported_not_guessed() { + let plan = CornerPlan { + source: CornerSource::Dwm, + excluded: None, + host: HostOs::Windows, + 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")); +} 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..32d5104 --- /dev/null +++ b/crates/app-iced/src/platform/win32/transparency/exstyle.rs @@ -0,0 +1,110 @@ +//! 取证用的**扩展样式探针**（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` 门禁也照样绿（它只数「带放行 +//! 属性的文件」）——但「FFI 只住在少数几个落点文件里」这个性质就破了。 +//! 属性的作用是可审计性，不是给 CI 看的。 +//! +//! ## 判据来源 +//! +//! winit 0.30 在 Windows 把 `set_cursor_hittest(false)` 落成 +//! `WS_EX_TRANSPARENT | WS_EX_LAYERED`（`window_state.rs`）。所以读回这一位，就是 +//! 「取证窗口真的把命中测试关掉了」的 OS 侧证据——比「出图 hash 不变」有判别力得多 +//! （实测：同 argv 开/关穿透，hash 完全相同）。 + +// 唯一使用者是下面的 `click_through`（它自己按平台门禁），非 Windows 上这个导入没人用 +// ⇒ `unused_imports` 在 `-D warnings` 下升成错（M147）。 +#[cfg(target_os = "windows")] +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 { + 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 { + 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..05ce55d --- /dev/null +++ b/crates/app-iced/src/platform/win32/transparency/probe.rs @@ -0,0 +1,347 @@ +//! 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}; +// `CornerOutcome` 与平台无关（`ProbeRow` 的字段类型、非 Windows 的 `empty_row` 都用它）， +// 其余九个符号只服务于 Windows 的 `run_one` —— 分开写，否则非 Windows 上整条导入无人使用 +// （`unused_imports`，M147）。 +use super::dwm::CornerOutcome; +#[cfg(target_os = "windows")] +use super::dwm::{ + corner_preference_hr, extended_frame_bounds, set_preference, visible_border_thickness, + window_rect, window_style, 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, + /// 什么都没设时 DWM 侧的偏好值（`0` = `DWMWCP_DEFAULT`）。 + pub preference_default: Option, + /// 读上面那一格时的 `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, + /// 圆角状态下的可见边框厚度（像素）。 + pub border_round: Option, + /// 直角状态下的可见边框厚度（像素）。 + pub border_square: Option, + /// `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 { + let show = |value: Option| 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 { + 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..464c817 --- /dev/null +++ b/crates/app-iced/src/platform/win32/transparency/tests.rs @@ -0,0 +1,247 @@ +//! `transparency` 的测试（M116 从 `transparency.rs` 搬出来：那个文件要留行数给 DWM 的 FFI）。 +//! +//! **本文件零 `unsafe`、零 `extern`**：只调父模块的安全包装。别把 FFI 写进来—— +//! 带 `#![allow(unsafe_code)]` 的是 `transparency.rs`（以及 M196 的 `console.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::host::HostOs; + use crate::platform::win32::corner::plan_corner_for; + use unlucky_presenter::prefs::WindowCorner; + + // 平台**显式传 Windows**：这条探针本身就是 `#[cfg(target_os = "windows")]` 的真窗口实验， + // 用宿主绑定的 `plan_corner` 只会让「这台机器是 Windows」变成一个隐式前提（复审 P1-1 的 + // 同类问题：本机绿、别的宿主红）。判据与产品完全同一份，产物那一行逐字不变。 + let os = crate::platform::current_windows_version(); + let plan = plan_corner_for( + WindowCorner::System, + HostOs::Windows, + 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_for( + WindowCorner::Square, + HostOs::Windows, + 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>` 就这两件东西，和 +//! [`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, + /// 上一次写回 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 { + self.last_failure + } + + /// 抽干事件队列（UI 在心跳里调；返回的事件**只**经 `Message::Agent(Events)` 回流）。 + pub(crate) fn drain(&mut self) -> Vec { + 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>>`：**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` | 落盘/读回由 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, + accounts: Vec, + next_id: u32, + active: Option, +} + +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 { + 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>>; + +/// 失败原因槽（transport 侧写、UI 侧读后清）。 +pub(crate) type FailureSlot = Arc>>; + +/// 脚本（一轮输入会产生哪种剧情）。 +#[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::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, + 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) { + 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, 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, 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 { + 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..2755801 --- /dev/null +++ b/crates/app-iced/src/probe.rs @@ -0,0 +1,229 @@ +//! 渲染后端探测 + 自动降级（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, + /// 是否存在**真**硬件适配器（`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::>() + .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>, +) -> 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 { + "" + }; + + // M188 复审 P2-1：这三行是**一次性的启动取证**（后端请求 → 落定的 ICED_BACKEND → 取证指南）， + // 必须进 `<.ULL>/logs/launcher.log`：双击启动没有 stderr，否则「为什么用这个后端 / 为什么降级」 + // 在事故之后完全不可复原。 + crate::app::diag::diag!( + "[probe] {} :: request={} -> ICED_BACKEND={}{note}", + probe.describe(), + request.name(), + decision.primary.env_value() + ); + crate::app::diag::diag!("[probe] {}", decision.describe()); + if decision.primary == renderer::Kind::Wgpu { + crate::app::diag::diag!( + "[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::>(); + + 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::>(); + 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..660fd73 --- /dev/null +++ b/crates/app-iced/src/renderer/acceptance/locale.rs @@ -0,0 +1,296 @@ +//! `[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, 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 { + 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, + /// `ui.language` 的显式值（`None` = 文件里**没写过** = 跟随系统）。 + /// + /// 与 `App` 启动判定同一个读法（`SettingsBridge::load_ui_language`：只认显式值，不走 schema + /// 默认值），所以「没写过」在这里与 `ui::lang` 里是同一个意思。 + pub setting: Option, + /// (源自称的名字, 原始 locale)。 + pub platform: (&'static str, Option), + /// (源自称的名字, 原始 locale)。 + pub env: (&'static str, Option), + /// 只按**平台源 + 环境变量**算出来的「这台机器说什么语言」（**不看** `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, +} + +impl LocaleSource for Captured { + fn locale(&self) -> Option { + 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 { + #[cfg(target_os = "macos")] + { + // macOS 上 `quiet` 是原样返回（POSIX 不因 spawn 新开终端）；走它是为了不在整棵 + // `crates/` 的子进程守卫里为这条 macOS 专用路径开例外（M217）。 + let output = unlucky_core::platform::child::quiet("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 { + 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 = 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 { + 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 { + 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 { + 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, ®istry_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(®istry_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 { + 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 { + 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, 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, + final_kind: Option, + 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, + final_kind: Option, + 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, 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, 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, + 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, + 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 = 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::>() + .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, + 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, + 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, + /// 为什么这么判（进日志，验收就靠它）。 + 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, &'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..5b23e1d --- /dev/null +++ b/crates/app-iced/src/renderer/log_bridge.rs @@ -0,0 +1,153 @@ +//! 把 `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 { + parse_level(&std::env::var("ULL_GPU_LOG").unwrap_or_default()) +} + +/// 取值解释（纯函数，测试直接喂字符串，不碰进程环境）。 +fn parse_level(value: &str) -> Option { + 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', " "); + // M188 复审 P2-1：`[gpu] iced_wgpu: …Selected: AdapterInfo…` 是「GPU 真生效」的**唯一** + // 证据行，也是「为什么降级了」的第一现场，必须进 `<.ULL>/logs/launcher.log`。 + crate::app::diag::diag!("[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..46d9121 --- /dev/null +++ b/crates/app-iced/src/renderer/mod.rs @@ -0,0 +1,292 @@ +//! 渲染后端的**判据表**（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 { + 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 { + 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}`）， +/// 所以这里必须显式把内层错误打出来，否则又变回「只知道失败，不知道为什么」。 +/// +/// **M188 复审 P2-1**：这两行是**事故本体**，必须同时进 `<.ULL>/logs/launcher.log`—— +/// 双击启动的 GUI 进程没有 stderr，只打 `eprintln!` 等于「最该有日志的那条路径上没有日志」。 +pub fn report_failure(backend: Kind, error: &(impl std::fmt::Display + std::fmt::Debug)) { + crate::app::diag::diag!("[gpu] {} 初始化失败（具名）：{error}", backend.name()); + crate::app::diag::diag!("[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, "进程内只许跑一次；重试只能换进程"); + } + + /// **M188 复审 P2-1 的守门**：后端起不来那两行必须进 `<.ULL>/logs/launcher.log`，不只是 stderr。 + /// + /// 为什么这条最要紧：双击启动的 GUI 进程**没有 stderr 去向**，而「GPU / 渲染后端起不来」 + /// 正是最需要事后复盘的一类事故。只打 `eprintln!` 等于在这条路径上什么都没留下—— + /// 用户那句「崩了但只有一个安装日志」会在最该有日志的地方继续成立。 + /// + /// 抓得住：`report_failure` 退回纯 `eprintln!`（变异证明：改回去本条立刻红）。 + /// 抓不住：真机上 iced 起不来的样子（那要真 GPU/驱动，见报告「没验的部分」）。 + #[test] + fn a_backend_startup_failure_lands_in_the_launcher_log() { + use crate::app::diag::LOG_STATE_LOCK; + use unlucky_core::launch::launcher_log; + + // `launcher_log` 是进程级单例：与 `app/diag.rs` 的滚动闸、`app/dialog/tests.rs` 的启动事实 + // 用例串行（同一个 `LOG_STATE_LOCK`）。 + let _guard = LOG_STATE_LOCK + .lock() + .unwrap_or_else(|error| error.into_inner()); + let dir = std::env::temp_dir().join(format!("ull-m188-gpu-fail-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&dir); + std::fs::create_dir_all(&dir).expect("建夹具目录"); + launcher_log::set_dir(&dir); + + report_failure(Kind::Wgpu, &"no suitable adapter (host: test)".to_string()); + + let path = dir.join(launcher_log::FILE_NAME); + let text = std::fs::read_to_string(&path).expect("launcher.log"); + assert!( + text.contains("[gpu] wgpu 初始化失败（具名）：no suitable adapter"), + "具名原因没进日志：{text}" + ); + assert!( + text.contains("[gpu] 失败详情（具名）："), + "失败详情没进日志：{text}" + ); + // 取证：`cargo test … -- --nocapture` 时把真实落盘内容打出来（报告/复审可复核）。 + println!("launcher.log:\n{text}"); + std::fs::remove_dir_all(&dir).ok(); + } +} diff --git a/crates/app-iced/src/renderer/preflight.rs b/crates/app-iced/src/renderer/preflight.rs new file mode 100644 index 0000000..a7c2276 --- /dev/null +++ b/crates/app-iced/src/renderer/preflight.rs @@ -0,0 +1,248 @@ +//! 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> { + if !requested() { + return None; + } + + let started = std::time::Instant::now(); + let verdict = run(); + let took = started.elapsed().as_secs_f64() * 1000.0; + // M188：显式开关（`ULL_PREFLIGHT=1`）下的一次性行，按 `app::diag` 的判据可以进 + // `launcher.log`——用户开这个开关就是为了拿到「为什么起不来」的证据。 + match &verdict { + Ok(ok) => { + crate::app::diag::diag!("[gpu-preflight] {} took={took:.0}ms", ok.describe()); + } + Err(failure) => { + crate::app::diag::diag!("[gpu-preflight] {} took={took:.0}ms", failure.describe()); + } + } + Some(verdict) +} + +#[cfg(feature = "gpu")] +/// 真跑一遍 wgpu 初始化（不开窗、不建 surface）。 +/// +/// # Errors +/// 无适配器 / 设备请求被拒时返回 [`Failure`]，`detail` 是 wgpu 的原话。 +pub fn run() -> Result { + 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 { + 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(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.0.unpark(); + } + + fn wake_by_ref(self: &Arc) { + 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..6d1e47c --- /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，圆角取**规格卡 16**（`Large`；组件表 `OutlinedCard` 的官方值是 12）、`OutlineVariant` 1px、卡片层底 | `Ui::card_shape()` + `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>, + content: Element<'a, Message>, + right: Option>, + overlay: Option>, + forced: Option, + 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>, + work_area: Element<'a, Message>, + overlay: Option>, +) -> 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) -> 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, +) -> 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::( + 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, 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, + 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::>(); + + // 轨顶留白走 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, + 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::(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) -> Self { + Self { + signed_in: false, + initial: String::new(), + label: label.into(), + compact: false, + } + } + + /// 已登录态。 + pub fn signed_in(initial: impl Into, label: impl Into) -> 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, +) -> 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::( + 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, + /// 宽（px）。 + pub width: u32, + /// 高（px）。 + pub height: u32, +} + +impl Image { + /// 读 PNG（只支持 PNG：本 crate 的 `image` 只开了 png 编码/解码）。 + /// + /// # Errors + /// 读文件失败或解码失败时返回人话。 + pub fn load(path: &Path) -> Result { + 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 { + 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 { + 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 ` 的实现：读两张 PNG、对比、打日志。 +/// +/// # Errors +/// 任一图读不出来，或尺寸不同。 +pub fn diff_files(left: &Path, right: &Path) -> Result { + 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 { + 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 { + 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..3b0bcd0 --- /dev/null +++ b/crates/app-iced/src/theme.rs @@ -0,0 +1,386 @@ +//! # 令牌 → iced 类型（`Color` / `Font` / `Border` / `Radius` / `Theme`）。 +//! +//! 本模块是**唯一**允许把 `unlucky-design` 的值翻成 iced 类型的地方（M61 §0）：组件层只调 +//! [`Ui`]，绝不出现色值/字号/半径/间距字面量（`tests/no_hardcoded_tokens.rs` 扫 `src/**`）。 +//! +//! ## 两套来源：品牌色板（出厂）与取色方案（D38） +//! +//! M229 起 [`Ui::new`] 走 **品牌色板**（[`BrandBoard`]：Ink = 深色主方案 / Silver = 浅色主方案）， +//! `Scheme::baseline`（tone 派生）退回它本来的角色——D38 取色链的中性锚点。两条路径并列： +//! +//! - [`Ui::brand`]：出厂外观，色板自己决定深浅（[`BrandBoard::flavor`]）； +//! - [`Ui::with_accent`]：用户自定义强调色接管 primary/secondary/tertiary 三族（M250）， +//! 中性表面与 error 保持基线； +//! - [`Ui::from_scheme`]：背景图 / 壁纸取色成功时接管 49 个角色（取色失败回落色板）； +//! - [`Ui::baseline`]：老的 tone 派生口径，只给对照与测试用（产品路径不再默认走它）。 +//! +//! 「跟随系统」是**设置层的第三种态**，不是第三套板：系统浅色 → Silver、系统深色 → Ink +//! （[`BrandBoard::for_flavor`]）。色板始终只有两套。 +//! +//! ## 为什么不用 `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::{BrandBoard, Role, Scheme, SchemeFlavor, StateLayer}; +use unlucky_design::elevation::MaterialLayer; +use unlucky_design::inkcat::metrics::{self as inkcat, SpecBox}; +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, + /// 当前色板（Ink / Silver）。`from_scheme` 时取方案深浅对应的那块，`name()` 与图例用它。 + board: BrandBoard, + platform: Platform, + metrics: LayoutMetrics, + families: Families, + /// 面板层不透明度（D36 / M93）：**唯一的 α 来源**，由 [`Ui::layer`] 统一施加。 + panel_alpha: f32, +} + +impl Ui { + /// 按平台（由 `cfg!` 决定）与**品牌色板**求值：深浅决定色板（浅 → Silver / 深 → Ink）。 + /// + /// 这是产品出厂外观的唯一入口（M229）：`DesignTokens::brand(BrandBoard::for_flavor(flavor))`。 + 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::with_board(BrandBoard::for_flavor(flavor), platform, families) + } + + /// 按**指定色板**求值（色板自己决定深浅，见 [`BrandBoard::flavor`]）。 + pub fn brand(board: BrandBoard, families: Families) -> Self { + Self::with_board(board, Platform::current(), families) + } + + /// 指定色板 + 平台（截图与测试用）。 + pub fn with_board(board: BrandBoard, platform: Platform, families: Families) -> Self { + Self { + scheme: board.scheme(), + board, + platform, + metrics: LayoutMetrics::DESKTOP, + families, + panel_alpha: 1.0, + } + } + + /// tone 派生的 `Scheme::baseline` 口径（D38 取色链的中性锚点；产品路径不再默认走它）。 + /// + /// 留成公开入口是为了对照与测试：`Ui::new(flavor)` 与它在**颜色上不同**，那是 M229 的换肤。 + pub fn baseline(flavor: SchemeFlavor, families: Families) -> Self { + Self::from_scheme(Scheme::baseline(flavor), families) + } + + /// 当前深浅。 + pub fn flavor(&self) -> SchemeFlavor { + self.scheme.flavor() + } + + /// 当前色板（Ink / Silver）。 + pub fn board(&self) -> BrandBoard { + self.board + } + + /// 用**已解析的方案**构造求值器（D38：背景图 / 壁纸取色 → 49 个角色换掉色板）。 + /// + /// 色板字段取方案深浅对应的那块（`Light → Silver` / `Dark → Ink`）：取色方案只换颜色， + /// 不改变「这一屏是深色还是浅色」，所以 `name()` 仍然说实话。 + pub fn from_scheme(scheme: Scheme, families: Families) -> Self { + Self { + board: BrandBoard::for_flavor(scheme.flavor()), + scheme, + platform: Platform::current(), + metrics: LayoutMetrics::DESKTOP, + families, + panel_alpha: 1.0, + } + } + + /// 按**用户自定义强调色**求值（M250 ACCENTWIRE）：`DesignTokens::with_accent` 的 iced 侧入口。 + /// + /// 语义来自 design 的 [`Scheme::from_accent`]（既定产品口径，不是缺口）：只换 + /// primary / secondary / tertiary 三族，**中性表面与 error 保持基线**——「换强调色不该让整个 + /// 窗口底色变脏」。所以拿它跟 [`Ui::new`] 比，Primary 类角色会不同，Surface 系列**不会**。 + pub fn with_accent( + flavor: SchemeFlavor, + accent: unlucky_design::color::Color, + families: Families, + ) -> Self { + Self::from_scheme(accent_scheme(flavor, accent), families) + } + + /// 当前平台（决定字体族与字重降级）。 + 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)) + } + + /// 当前生效的 **49 角色方案**（品牌色板 / D38 取色方案，二选一的那一份）。 + /// + /// 凡是要**在令牌侧合成颜色**的地方（禁用态 38% 叠底、对话框遮罩 scrim、状态层叠色）都必须 + /// 从这里取，**不许**再 `Scheme::baseline(self.flavor())` 重算： + /// + /// - 重算出来的永远是 tone 派生的旧色（天蓝中性），品牌板上的禁用滑块轨道、填充框、遮罩会 + /// 各画各的（M229 复审 F1 实测：Ink 下三个蓝系像素值，应为绿系去饱和、遮罩为中性 + /// 绿黑；具体数值与出处见 `DevDocs/artifacts/m229/README.md` §6）。 + /// - 取色方案（D38）成功时也必须同源，否则「取色接管 49 个角色」这件事在禁用态上破一个洞。 + pub fn scheme(&self) -> &Scheme { + &self.scheme + } + + /// 材质层（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)) + } + + /// **规格卡口径的卡片方框**（`ELEVATED CARD` / `CARD`，`inkcat::metrics::CARD`）。 + /// + /// 与 `component_map` 的 `OutlinedCard = Medium(12)` 差 4：规格卡画的是 `rx=16`（Large）， + /// M228 的 `inkcat` 模块把这条差异登记为「换肤时取 `CARD`」，M229 就是那次换肤。表值不动 + /// （它还服务别的面），页面卡片统一从这里取。 + pub fn card_box(&self) -> SpecBox { + inkcat::CARD + } + + /// 卡片圆角档（= [`Self::card_box`] 的 `shape`，即 `ShapeScale::Large` = 16）。 + pub fn card_shape(&self) -> ShapeScale { + self.card_box().shape + } + + /// 固定档圆角。`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()` 的取值（稳定字符串，改名要先在协作文档登记）。 + /// + /// M229 起按**色板**取名（`ull-ink` / `ull-silver`）：换肤之后「深色」这个词不再等于 + /// 「M3 深色 tone 派生」，名字必须能区分「是哪块板」。D38 取色方案仍叫它所属深浅的那块 + /// （取色只换颜色，不换深浅）。 + pub fn name(&self) -> &'static str { + match self.board { + BrandBoard::Ink => "ull-ink", + BrandBoard::Silver => "ull-silver", + } + } +} + +/// 令牌色（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), + ) +} + +/// 强调色 → 49 角色方案：`DesignTokens::with_accent` 的**唯一**调用点（M250）。 +/// +/// 放在适配层而不是调用点，是因为「强调色只换三族、中性色保持基线」这条语义属于令牌层； +/// 页面侧只该拿到「一套方案」，不该各自决定换哪几个角色。 +pub fn accent_scheme(flavor: SchemeFlavor, accent: unlucky_design::color::Color) -> Scheme { + unlucky_design::DesignTokens::with_accent(flavor, accent).colors +} + +/// 这一屏的颜色从哪来（M250）。日志与出图都靠它说清「是谁生效」。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Colors { + /// 用户显式填的强调色（`appearance.accent_color`）。 + Accent, + /// D38 取色方案（背景图 / 壁纸取色成功，`State::derived_scheme`）。 + Scheme, + /// 出厂品牌色板（`DesignTokens::brand`）。 + Board, +} + +/// 强调色 / 取色方案 / 出厂板 **三选一**：全仓**唯一**的优先级定义点（M250）。 +/// +/// 产品路径（`App::rebuild_ui`）与出图 harness（`pages::harness`）都调它。为什么必须有这一个 +/// 函数：两头各抄一份两选一/三选一，迟早出现「出图上有强调色、产品里没有」或者反过来，而那种 +/// 偏差在图上看不出来（图是对的，产品是错的）。 +/// +/// 优先级：**显式强调色 > D38 取色方案 > 出厂板**。手填的色是直接意图，取色是从图片派生的。 +/// `flavor`（明暗 / 跟随系统）不在这里解析，由调用方按现有主题逻辑给。 +pub fn tokens( + flavor: SchemeFlavor, + accent: Option, + scheme: Option, + families: Families, +) -> (Ui, Colors) { + if let Some(accent) = accent { + (Ui::with_accent(flavor, accent, families), Colors::Accent) + } else if let Some(scheme) = scheme { + (Ui::from_scheme(scheme, families), Colors::Scheme) + } else { + (Ui::new(flavor, families), Colors::Board) + } +} + +/// 令牌字重 → 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; diff --git a/crates/app-iced/src/theme/tests.rs b/crates/app-iced/src/theme/tests.rs new file mode 100644 index 0000000..220f365 --- /dev/null +++ b/crates/app-iced/src/theme/tests.rs @@ -0,0 +1,209 @@ +//! `theme` 的单元测试（M229 从 `theme.rs` 纯搬移，守 400 行硬线：加双色板字段前该文件正好 400 行）。 +//! +//! 搬移只把 `mod tests { … }` 的包裹层换成了独立文件；**搬移之后内容有改动**（不是一行未改）： +//! 主题名从 `ull-m3-*` 改成 `ull-ink/ull-silver`、「默认构造逐字段等于 baseline」改成 +//! 「逐字段等于**品牌板**」，并新增了色板/卡片圆角/取色不改深浅等几条测试。 + +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-silver"); + assert_eq!(ui(SchemeFlavor::Dark).name(), "ull-ink"); + 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 时逐字段等于 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 board = ui(SchemeFlavor::Light); + assert_ne!( + tinted.color(Role::Primary), + board.color(Role::Primary), + "取色方案必须换掉 primary" + ); + // 深浅仍跟着方案走（方案自带 flavor），不会把 Light 变成 Dark；色板名也仍说实话。 + assert_eq!(tinted.flavor(), SchemeFlavor::Light); + assert_eq!(tinted.name(), board.name()); + + // 显式传 baseline 时逐块等于 baseline 口径（M229 之后产品默认不再是它，但这条通路必须诚实）。 + let explicit = Ui::from_scheme(Scheme::baseline(SchemeFlavor::Light), FAMILIES); + let baseline = Ui::baseline(SchemeFlavor::Light, FAMILIES); + for role in Role::ALL { + assert_eq!( + explicit.color(role), + baseline.color(role), + "{role:?}：显式传 baseline 时颜色必须与 baseline 口径一致" + ); + } +} + +/// M229：`Ui::new` 走**品牌色板**（Ink 深 / Silver 浅），不再走 tone 派生的 `baseline`。 +/// +/// 抓得住：换肤没接上（色值仍是 baseline）、深浅映射反了（Light 拿到 Ink）。 +/// 抓不住：色板好不好看、页面有没有绕过 `Ui::color` 自己写色值（后者由 `no_hardcoded_tokens` 扫）。 +#[test] +fn every_ui_is_built_from_a_brand_board() { + for (flavor, board) in [ + (SchemeFlavor::Light, BrandBoard::Silver), + (SchemeFlavor::Dark, BrandBoard::Ink), + ] { + let evaluator = ui(flavor); + assert_eq!(evaluator.board(), board, "{flavor:?} 该用 {:?}", board); + assert_eq!(evaluator.name(), board_name(board)); + for role in Role::ALL { + assert_eq!( + evaluator.color(role), + to_iced(board.get(role)), + "{flavor:?} 的 {role:?} 不是色板值" + ); + } + // 与 tone 派生的 baseline 确实不同（否则「换肤」这件事没发生）。 + let baseline = Ui::baseline(flavor, FAMILIES); + assert_ne!( + evaluator.color(Role::Primary), + baseline.color(Role::Primary), + "{flavor:?}：色板与 baseline 的 primary 撞了，换肤等于没接" + ); + assert_eq!(evaluator.flavor(), flavor); + } +} + +/// 显式选板时深浅跟着板走（`Ink = Dark` / `Silver = Light`），「跟随系统」不必另造一种板。 +#[test] +fn picking_a_board_sets_the_flavor_from_the_board() { + let ink = Ui::with_board(BrandBoard::Ink, Platform::Windows, FAMILIES); + let silver = Ui::with_board(BrandBoard::Silver, Platform::Windows, FAMILIES); + assert_eq!(ink.flavor(), SchemeFlavor::Dark); + assert_eq!(silver.flavor(), SchemeFlavor::Light); + assert_ne!(ink.theme().to_string(), silver.theme().to_string()); +} + +/// 卡片方框走规格卡（`rx=16`），不是组件表的 `Medium(12)`。 +#[test] +fn cards_take_the_spec_corner() { + let evaluator = ui(SchemeFlavor::Light); + assert_eq!(evaluator.card_shape(), ShapeScale::Large); + assert_eq!(evaluator.card_box().radius_px(), 16.0); + assert_eq!( + evaluator.outlined(evaluator.card_shape()).radius.top_left, + 16.0 + ); +} + +fn board_name(board: BrandBoard) -> &'static str { + match board { + BrandBoard::Ink => "ull-ink", + BrandBoard::Silver => "ull-silver", + } +} 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..db693a1 --- /dev/null +++ b/crates/app-iced/src/ui/lang.rs @@ -0,0 +1,287 @@ +//! 界面语言的**入口层**（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 { + if !screenshot { + return None; + } + std::env::var("ULL_SETTINGS_GROUP") + .ok() + .and_then(|raw| raw.trim().parse::().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(_) + ) { + // M168：这里**不再**说「通道还没做」——下载在这一拍之后就已经发起（同一份报告交给 + // `fonts::install::after_probe`），结果与状态在 `[font] cjk-download …` 那几行里， + // 也在设置页 General 组的状态行上。上一版这句 stderr 在下载发起后说「还是 PendingPin」， + // 等于当面否定刚做的事（复审 r1 P2-3）。 + eprintln!( + "[i18n] 缺中文字体：已按 D28 发起下载，进度与结果见 [font] cjk-download … 与设置页「中文字体」那一行；失败会降级用系统字体" + ); + } + } +} + +/// 档位选择的**纯判据**（单测直接打这张表）。 +/// +/// **产品路径与验收路径共用它**：`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) { + 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 { + 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::() == 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 { + 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) { + { + 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 { + 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, + passes: usize, +) -> SharedPixelBuffer { + 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 = 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::::new(source.width(), source.height()); + out.make_mut_slice().copy_from_slice(¤t); + out +} + +/// 双线性放大到目标尺寸。 +fn upscale( + source: &SharedPixelBuffer, + width: u32, + height: u32, +) -> SharedPixelBuffer { + 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::::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, + width: u32, + height: u32, +) -> SharedPixelBuffer { + let mut canvas = SharedPixelBuffer::::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, + target_width: u32, +) -> SharedPixelBuffer { + 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::::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 { + let mut buffer = SharedPixelBuffer::::new(width, height); + buffer.make_mut_slice().fill(pixel); + buffer + } + + #[test] + fn downscale_keeps_aspect_and_averages_area() { + let mut source = SharedPixelBuffer::::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::::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::::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) { + 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) { + { + 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) { + { + 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) { + { + 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) { + { + 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) { + { + 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) { + // 主题三态 + 外观四件在 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) { + { + 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::() { + this.state.borrow_mut().toasts.dismiss(id); + this.sync(); + } + }); + } +} + +fn close_current_dialog(weak: &Weak) { + 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) { + let Some(inner) = weak.upgrade() else { return }; + let page = inner.ui.global::>(); + + // ── 账户 ────────────────────────────────────────────────── + { + 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::>() + .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 { + 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 { + 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 { + 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 { + state.tiles().iter().map(tile).collect() +} + +/// 运行中实例（顶部迷你状态条）。 +pub fn running_tiles(state: &AppState) -> Vec { + 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 { + 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 { + 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 { + ModelRc::new(VecModel::from( + items + .iter() + .map(|item| SharedString::from(item.as_str())) + .collect::>(), + )) +} + +/// 账户行。 +pub fn accounts(state: &AppState) -> Vec { + 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 { + 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 { + 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 { + 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 { + 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::>(), + )), + }) + .collect() +} + +/// 横幅通知。 +pub fn notices(state: &AppState) -> Vec { + 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 { + 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 { + 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 { + 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 { + let query = state.download_query.trim().to_lowercase(); + let filtered: Vec = 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 = 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 { + 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::>(); + 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) -> Vec { + 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, 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 { + 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::::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::::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, + /// 打开新建实例向导 + pub wizard: bool, + /// 发起一次真实安装并停 `dwell_ms` 后取图（中间态） + pub install: Option, + /// 安装走哪个加载器（`--screenshot-loader forge`；缺省 = 原版） + pub loader: Option, + /// 发起一次真实启动并停 `dwell_ms` 后取图（中间态） + pub launch: Option, + /// 打开一个日志会话（日志页有数据态：日志行 + 诊断卡片） + pub session: Option, + /// 中间态停留毫秒（默认 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 { + 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 { + 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` 换成真实的 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, + timer: slint::Timer, +} + +pub(crate) struct Inner { + pub(crate) ui: MainWindow, + pub(crate) state: RefCell, + pub(crate) backend: RefCell>, + /// `config/launcher.json` 读写桥（app 不自己写盘：一律走 core::setting 的 schema API） + pub(crate) bridge: RefCell, + /// 当前背景图 / 模糊层（避免每次同步都重新解码） + pub(crate) background: RefCell, + /// 生成 `background` 时的输入（路径 / 填充模式 / 窗口粒度尺寸） + pub(crate) background_key: RefCell>, + /// 拍数（轮询节拍） + pub(crate) ticks: Cell, + /// 是否已经做过启动时的系统主题对齐 + pub(crate) system_theme_probed: Cell, +} + +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::>() + .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(items: Vec) -> ModelRc { + 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 message; + + property is-tool: message.role == ChatRole.tool; + property is-system: message.role == ChatRole.system; + property text-width: root.width - 2 * Metrics.gap-2; + property 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 collapsed: false; + /// true = 停在右侧栏形态；false = 已拆成独立全宽页 + in property docked: true; + in property yolo: false; + in property streaming: false; + in property endpoint-label: "llama.cpp · 本地"; + in-out property 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 text: ""; + in property tint: Theme.fg-secondary; + in property 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 card-radius: Metrics.radius-md; + /// 叠在模糊层上的半透明面板色（保证前景对比度） + in property tint: Theme.surface-solid; + + out property 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 kind: IconKind.instances; + in property tint: Theme.fg-secondary; + in property 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 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 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 icon: IconKind.instances; + in property label: ""; + in property active: false; + in property 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 active: RouteKind.instances; + in-out property collapsed: false; + in property account-name: "未登录"; + in property account-hue: #5C2D91; + in property 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 ratio: 0.0; + in property known: true; + in property 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 progress: 0; + in property 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 data; + in property 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 data; + in property 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 icon: IconKind.minimize; + /// 关闭键：hover 用 Metro 红底白字 + in property 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 title: "Unlucky Launcher"; + in property subtitle: ""; + in property 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 app-title: "Unlucky Launcher"; + in property route: RouteKind.instances; + + in property nav-collapsed: false; + in property account-name: "未登录"; + in property account-initial: "?"; + in property account-hue: #5C2D91; + + in-out property ai-collapsed: false; + in property <[UiChatMessage]> ai-messages; + in property ai-streaming: false; + in-out property yolo: false; + in property ai-endpoint-label: "llama.cpp · 本地"; + in-out property 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 diagnosis; + in property has-diagnosis: false; + in property selected-session: ""; + + in-out property tile-size: TileSize.medium; + in-out property instance-view: InstanceView.tiles; + in-out property instance-query: ""; + in-out property settings-section: SettingSection.general; + in-out property theme-mode: ThemeMode.auto; + // 系统主题（M41）：0 = 未知（回落 Slint 后端），1 = 浅色，2 = 深色 + in property system-theme: 0; + /// 后端是否认得系统主题（`false` 时 Rust 侧才需要轮询探测兜底） + out property system-theme-known: Theme.system-theme-known; + + // ── 外观（高级）P1 四件（09 §101-104，出厂全部关闭）────────────── + // 图片由 Rust 灌入（`in`）；其余是 in-out：设置页控件会写回，回调里再原样上抛给 Rust。 + in property background-image; + in property background-blur; + in-out property bg-image-enabled: false; + in-out property bg-image: ""; + in-out property bg-fill: BgFillKind.cover; + in-out property bg-dim: 0.35; + in-out property panel-alpha: 1.0; + in-out property glass: false; + in-out property accent-color: transparent; + /// 设置页「强调色（十六进制）」输入框的内容（Rust 写入规范化后的值） + in-out property accent-hex: ""; + /// 强调色输入是否非法（设置页亮 warn 行） + in-out property accent-invalid: false; + in-out property download-category: DownloadCategory.release; + in-out property download-installed-only: false; + in-out property download-query: ""; + + in property dialog; + in property dialog-open: false; + in property 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::()` 读写，语义与 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 active-account: ""; + in property device; + /// 离线添加表单的输入（不落盘，点「添加」才提交） + in-out property offline-name: ""; + + // ── Java（下载页 Java 分组 / 设置页 Java 分组）────────────── + in property <[UiJavaVendor]> java-vendors; + in property <[UiJavaStep]> java-chain; + in property <[UiJavaRuntime]> java-runtimes; + in property java-order: ""; + in property java-region: ""; + in property java-priority-source: ""; + in property java-message: ""; + in property java-busy: false; + in property java-target-major: 17; + + // ── 安装进度（下载页 + 向导共用）──────────────────────────── + in property install; + /// 下载页右侧视图：0 = 版本列表，1 = Java 运行时（截图通道也从这里切） + in-out property download-tab: 0; + + // ── 设置分组（settings_bridge 同源 launcher.json）────────── + in property <[UiSettingGroup]> setting-groups; + in-out property setting-tab: "download"; + + // ── 通知条 / 向导 ───────────────────────────────────────── + in property <[UiNotice]> notices; + in property 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 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 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 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 label: ""; + in property active: false; + in property sub: false; + in property 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 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 category: DownloadCategory.release; + in-out property installed-only: false; + in-out property query: ""; + /// 远古版子类树是否展开（默认展开，显式可达） + in-out property ancient-expanded: true; + /// 右侧视图：0 = 版本列表，1 = Java 运行时 + in-out property 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 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 view: InstanceView.tiles; + in-out property tile-size: TileSize.medium; + in-out property 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 data; + in property 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 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 diagnosis; + in property has-diagnosis: false; + in property live: false; + in-out property selected: ""; + in-out property 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 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 theme-mode: ThemeMode.auto; + in-out property bg-image-enabled: false; + in-out property bg-image: ""; + in-out property bg-fill: BgFillKind.cover; + in-out property bg-dim: 0.35; + in-out property panel-alpha: 1.0; + in-out property glass: false; + in-out property accent-color: ""; + in property 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 item; + /// 文本编辑的本地缓冲（编辑中不回写模型，失焦/回车才提交） + in-out property 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 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 label: ""; + in property section: SettingSection.general; + in property 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 section: SettingSection.general; + in-out property query: ""; + + // 外观（D17：主题三态 + 09 §101-104 高级特性四件） + in-out property theme-mode: ThemeMode.auto; + in-out property bg-image-enabled: false; + in-out property bg-image: ""; + in-out property bg-fill: BgFillKind.cover; + in-out property bg-dim: 0.35; + in-out property panel-alpha: 1.0; + in-out property glass: false; + in-out property accent-color: ""; + in property accent-invalid: false; + // 通用 + in-out property tile-size: TileSize.medium; + in-out property close-to-tray: true; + + // 数据 + in-out property data-mode: 0; + in property data-path: ""; + // 下载 + in-out property download-concurrency: 1; + in property region-label: "未知"; + // 账户 + in property account-label: "未登录"; + // AI + in-out property ai-endpoint: 0; + in-out property yolo: false; + in-out property mcp-enabled: false; + // 代理 + in-out property proxy: ""; + // 关于 + in property 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 app-title: "Unlucky Launcher"; + in property maximized: false; + + // ── 路由 ──────────────────────────────────────────────────── + in property route: RouteKind.instances; + + // ── 导航 / 账户 ────────────────────────────────────────────── + in property nav-collapsed: false; + in property account-name: "未登录"; + in property account-initial: "?"; + in property account-hue: #5C2D91; + + // ── AI 栏（双形态共享同一份会话）────────────────────────────── + in property ai-collapsed: false; + in property <[UiChatMessage]> ai-messages; + in property ai-streaming: false; + in property yolo: false; + in property ai-endpoint-label: "llama.cpp · 本地"; + in-out property 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 diagnosis; + in property has-diagnosis: false; + in property selected-session: ""; + + // ── 偏好（持久化键见 SubAgentsTalk/app-DTO通道约定.md）────────── + in-out property tile-size: TileSize.medium; + in-out property instance-view: InstanceView.tiles; + in-out property instance-query: ""; + in-out property settings-section: SettingSection.general; + /// D17 主题三态（auto 跟随系统；light/dark 钉死）。Rust 侧同时写 Theme 全局。 + in-out property theme-mode: ThemeMode.auto; + /// 外观（高级）四件的 in-out 通道：MainWindow ↔ SettingsPage（图片本身走 `Theme.bg-image`） + in-out property bg-image-enabled: false; + in-out property bg-image: ""; + in-out property bg-fill: BgFillKind.cover; + in-out property bg-dim: 0.35; + in-out property panel-alpha: 1.0; + in-out property glass: false; + /// 设置页编辑的十六进制串（`accent-color` 是解析后的颜色，只给 Theme 用） + in-out property accent-hex: ""; + /// 强调色输入是否非法（设置页亮 warn 行） + in-out property accent-invalid: false; + in-out property download-category: DownloadCategory.release; + in-out property download-installed-only: false; + /// 下载页版本号筛选词（输入由页面写回，state.download_query 参与过滤） + in-out property download-query: ""; + + // ── 对话框队列 / Toast ─────────────────────────────────────── + in property dialog; + in property dialog-open: false; + in property 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 gap-1: 4px; + out property gap-2: 8px; + out property gap-3: 12px; + out property gap-4: 16px; + out property gap-5: 24px; + out property gap-6: 32px; + + out property radius-sm: 2px; + out property radius-md: 4px; + out property radius-lg: 8px; + + // 主窗口骨架 + out property titlebar-height: 40px; + out property titlebar-button-width: 46px; + out property accent-line: 2px; + out property nav-expanded-width: 88px; + out property nav-collapsed-width: 48px; + out property ai-panel-width: 320px; + out property ai-rail-width: 44px; + out property page-header-height: 56px; + out property running-strip-height: 32px; + out property row-height: 44px; + out property control-height: 32px; + out property touch-target: 32px; + + // 磁贴三档（Q24-3：默认中磁贴 4 列，设置可调小 6 / 大 3） + in-out property tile-size: TileSize.medium; + out property tile-columns: + tile-size == TileSize.small ? 6 + : tile-size == TileSize.large ? 3 + : 4; + out property tile-height: + tile-size == TileSize.small ? 104px + : tile-size == TileSize.large ? 176px + : 136px; + out property tile-icon-size: + tile-size == TileSize.small ? 32px + : tile-size == TileSize.large ? 56px + : 44px; + // 小磁贴只留图标+名字+启动键，藏起徽标与最后游玩时间（空间不足） + out property 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 bg-canvas: #F3F3F3; + out property bg-surface: #FFFFFF; + out property bg-elevated: #FFFFFF; + out property bg-titlebar: #EDEDED; + out property bg-hover: #E9E9E9; + out property bg-pressed: #DEDEDE; + out property bg-input: #FFFFFF; + + out property fg-primary: #1A1A1A; + out property fg-secondary: #5F5F5F; + out property fg-disabled: #9A9A9A; + + out property stroke: #E1E1E1; + out property stroke-strong: #C8C8C8; + out property shadow: #00000026; + out property scrim: #00000099; + + out property accent-soft: #E5F1FB; + out property accent-hover: #106EBE; + out property accent-pressed: #005A9E; + + out property state-success: #107C10; + out property state-success-soft: #DFF6DD; + out property state-warn: #9D5D00; + out property state-warn-soft: #FFF4CE; + out property state-danger: #C42B1C; + out property state-danger-hover: #A82214; + out property state-danger-soft: #FDE7E9; + out property state-info-soft: #E7F1FA; +} + +// ── 暗色色板 ──────────────────────────────────────────────────── +export global DarkPalette { + out property bg-canvas: #1B1B1B; + out property bg-surface: #232323; + out property bg-elevated: #2B2B2B; + out property bg-titlebar: #161616; + out property bg-hover: #2F2F2F; + out property bg-pressed: #383838; + out property bg-input: #1E1E1E; + + out property fg-primary: #F2F2F2; + out property fg-secondary: #A6A6A6; + out property fg-disabled: #6B6B6B; + + out property stroke: #3A3A3A; + out property stroke-strong: #4A4A4A; + out property shadow: #000000CC; + out property scrim: #00000099; + + out property accent-soft: #0F2A3F; + out property accent-hover: #2B8FE0; + out property accent-pressed: #005A9E; + + out property state-success: #4CCB4C; + out property state-success-soft: #16321A; + out property state-warn: #FFD24C; + out property state-warn-soft: #3A2E0F; + out property state-danger: #FF6B6B; + out property state-danger-hover: #FF8A8A; + out property state-danger-soft: #3A1A1A; + out property state-info-soft: #10263A; +} + +// ── 解析器 ────────────────────────────────────────────────────── +export global Theme { + // ── 主题三态（D17 设置页「外观」分组，出厂 auto）────────────────── + // D17 主题三态（设置页「外观」分组，出厂 auto） + in-out property theme-mode: ThemeMode.auto; + // 系统主题来源（M41）：0 = 未知（此时回落到 Slint 后端 `Palette.color-scheme`）， + // 1 = 浅色 / 2 = 深色。由 Rust 的 `core::platform::theme_probe` 探测后灌入： + // 启动时给首帧对齐，之后按需轮询兜底（后端不支持系统主题时 auto 仍可用）。 + in-out property system-theme: 0; + // 后端是否认得系统主题（`unknown` 表示不支持/无 portal）。 + out property system-theme-known: Palette.color-scheme != ColorScheme.unknown; + // 是否深色：显式钉死（light/dark）优先；auto 时用探测值，探测未知才问后端。 + out property 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 panel-alpha: 1.0; + // 自定义窗口背景图（空 image = 纯色背景，出厂态）。 + in-out property bg-image; + // 背景图暗化层强度（0~0.95，越大前景越清晰）。Rust 侧夹到 schema 范围。 + in-out property bg-dim: 0.35; + // 玻璃拟态：预生成模糊层（Rust 侧降采样 + box blur），卡片内按 `absolute-position` + // 反向偏移对齐整窗，得到 Slint 版「毛玻璃」（无 backdrop-filter 的替代手法）。 + in-out property glass: false; + in-out property bg-blur; + // 玻璃层对齐用的窗口逻辑尺寸（AppShell 在 init/changed 里灌入）。 + in-out property window-width: 1180px; + in-out property window-height: 760px; + + // ── 强调色（accent 令牌全域生效；两套色板共享）────────────────── + // `accent-override` 的 alpha == 0 表示「未自定义」，走 D14 出厂 Metro 蓝。 + // （color 的 `.alpha` 字段是 0~255 整数，不是 0~1 浮点。） + in-out property accent-override: transparent; + out property accent-custom: accent-override.alpha > 1; + out property accent: accent-custom ? accent-override : #0078D4; + // 自定义时由覆盖色派生 hover/pressed/soft（未自定义仍走双色板常量，出场观感不变）。 + out property accent-hover: accent-custom + ? (dark ? accent.brighter(0.18) : accent.darker(0.12)) + : (dark ? DarkPalette.accent-hover : LightPalette.accent-hover); + out property accent-pressed: accent-custom + ? (dark ? accent.brighter(0.28) : accent.darker(0.24)) + : (dark ? DarkPalette.accent-pressed : LightPalette.accent-pressed); + out property accent-soft: accent-custom + ? accent.mix(surface-solid, 0.82) + : (dark ? DarkPalette.accent-soft : LightPalette.accent-soft); + out property accent-contrast: #FFFFFF; + // accent 上的前景色按相对亮度自动选黑/白（自定义亮黄、浅青时白字会糊）。 + // 注意：Slint 的 color 通道字段（`.red` 等）是 0~255 的**整数**。 + out property accent-luma: accent.red * 0.299 + accent.green * 0.587 + accent.blue * 0.114; + out property 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， + // 赋给 `` 属性会类型不符（Slint 无 Brush → color 隐式回退）。 + out property surface-solid: dark ? DarkPalette.bg-surface : LightPalette.bg-surface; + out property canvas-solid: dark ? DarkPalette.bg-canvas : LightPalette.bg-canvas; + out property surface-elevated-solid: dark ? DarkPalette.bg-elevated : LightPalette.bg-elevated; + out property titlebar-solid: dark ? DarkPalette.bg-titlebar : LightPalette.bg-titlebar; + out property hover-solid: dark ? DarkPalette.bg-hover : LightPalette.bg-hover; + out property pressed-solid: dark ? DarkPalette.bg-pressed : LightPalette.bg-pressed; + out property input-solid: dark ? DarkPalette.bg-input : LightPalette.bg-input; + + out property bg-canvas: rgba( + canvas-solid.red, canvas-solid.green, canvas-solid.blue, panel-alpha); + out property bg-surface: rgba( + surface-solid.red, surface-solid.green, surface-solid.blue, panel-alpha); + out property bg-elevated: rgba( + surface-elevated-solid.red, surface-elevated-solid.green, surface-elevated-solid.blue, panel-alpha); + out property bg-titlebar: rgba( + titlebar-solid.red, titlebar-solid.green, titlebar-solid.blue, panel-alpha); + out property bg-hover: rgba( + hover-solid.red, hover-solid.green, hover-solid.blue, panel-alpha); + out property bg-pressed: rgba( + pressed-solid.red, pressed-solid.green, pressed-solid.blue, panel-alpha); + out property bg-input: rgba( + input-solid.red, input-solid.green, input-solid.blue, panel-alpha); + + out property fg-primary: dark ? DarkPalette.fg-primary : LightPalette.fg-primary; + out property fg-secondary: dark ? DarkPalette.fg-secondary : LightPalette.fg-secondary; + out property fg-disabled: dark ? DarkPalette.fg-disabled : LightPalette.fg-disabled; + + out property stroke: dark ? DarkPalette.stroke : LightPalette.stroke; + out property stroke-strong: dark ? DarkPalette.stroke-strong : LightPalette.stroke-strong; + out property shadow: dark ? DarkPalette.shadow : LightPalette.shadow; + out property scrim: dark ? DarkPalette.scrim : LightPalette.scrim; + + out property state-success: dark ? DarkPalette.state-success : LightPalette.state-success; + out property state-success-soft: dark ? DarkPalette.state-success-soft : LightPalette.state-success-soft; + out property state-warn: dark ? DarkPalette.state-warn : LightPalette.state-warn; + out property state-warn-soft: dark ? DarkPalette.state-warn-soft : LightPalette.state-warn-soft; + out property state-danger: dark ? DarkPalette.state-danger : LightPalette.state-danger; + out property state-danger-hover: dark ? DarkPalette.state-danger-hover : LightPalette.state-danger-hover; + out property state-danger-soft: dark ? DarkPalette.state-danger-soft : LightPalette.state-danger-soft; + out property 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 font-family: "Selawik"; + in-out property font-family-mono: "Cascadia Mono"; + // 中文回退（思源黑体/微软雅黑由系统字体匹配，这里仅作显式声明） + in-out property font-family-cjk: "Microsoft YaHei UI"; + + // 排版层级（Metro typography ramp） + out property font-size-display: 24px; + out property font-size-title: 20px; + out property font-size-subtitle: 16px; + out property font-size-body: 14px; + out property font-size-caption: 12px; + out property line-height-body: 20px; + out property line-height-caption: 16px; + + // ── 动效（Metro 快速、克制）─────────────────────────────────── + out property motion-fast: 90ms; + out property motion-normal: 160ms; + out property motion-slow: 240ms; + // D17 动画强度倍率（P0 占位，P1 接设置页滑条与「减少动画」无障碍开关） + in-out property 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 kind: ButtonKind.standard; + in property text: ""; + in property icon: IconKind.plus; + /// 是否显示图标（纯文字按钮置 false） + in property show-icon: false; + in property enabled: true; + /// 图标按钮：不画文字，尺寸压到正方形 + in property icon-only: false; + /// 在布局中占据剩余宽度 + in property grow: false; + in property 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 current; + in property open: false; + /// 队列中剩余条数（>0 时卡片底部提示「还有 N 条待处理」，语义上是队列而非堆叠） + in property queued: 0; + in-out property 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 text: ""; + in property placeholder: ""; + in property text-color: Theme.fg-primary; + in property text-padding: 0px; + out property 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 text: ""; + in property 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 text: ""; + in property 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 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 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 checked: false; + in property 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 minimum: 0.0; + in property maximum: 1.0; + in-out property value: 1.0; + callback changed(float); + + out property 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 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 label: ""; + in property description: ""; + in property kind: ControlKind.none; + in property <[string]> options; + in property button-text: ""; + in-out property selected: 0; + in-out property checked: false; + in-out property value: ""; + // 滑条 + in property min-value: 0.0; + in property max-value: 1.0; + in-out property slider-value: 1.0; + // 色板 + in property <[color]> swatch-colors; + in property swatch-current: transparent; + // 危险/提示色描述（如「对比度偏低」） + in property 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 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 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 index: 0; + in property 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 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 label: ""; + in property hint: ""; + in property 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 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..d91ef7e --- /dev/null +++ b/crates/cli/Cargo.toml @@ -0,0 +1,46 @@ +[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.4" } +# agent：`redact`（输出脱敏）+ `ull agent serve`（M39 的 MCP server：注册表 → rmcp 双投影， +# core 侧五个端口在 src/commands/agent/ports/ 装配）。 +unlucky-agent = { path = "../agent", version = "0.2.4" } +# `ull agent serve` 要长驻跑 rmcp 的 stdio / Streamable HTTP 传输（tokio 运行时）。 +tokio.workspace = true +serde.workspace = true +serde_json.workspace = true + +[lints] +workspace = true + +[features] +# M169：转发 core 的测试通道（`--features update-test-source` 才编进来，默认关）。 +# `ull update check/apply` 的端到端验收要靠它指向本地目录源。 +update-test-source = ["unlucky-core/update-test-source"] + +# M190：把版本资源写进 PE（Windows「属性 → 详细信息」里的发布者/产品/版权/版本）。 +# 只在 windows 目标上真跑（`build.rs` 先看 CARGO_CFG_TARGET_OS，其它平台直接返回）， +# 共享口径在 `packaging/pe_version.rs`（两个 bin 各 include 一次，署名不会漂）。 +[build-dependencies] +winresource = "0.1" diff --git a/crates/cli/build.rs b/crates/cli/build.rs new file mode 100644 index 0000000..19c3b82 --- /dev/null +++ b/crates/cli/build.rs @@ -0,0 +1,10 @@ +//! `ull` 的 PE 版本资源（M190）。 +//! +//! 只做一件事：调共享口径 [`emit_pe_version_resource`]（定义在 `packaging/pe_version.rs`， +//! 两个 bin 共用同一份署名表）。非 windows 目标里那个函数会立刻返回，Linux/macOS 构建零影响。 + +include!("../../packaging/pe_version.rs"); + +fn main() { + emit_pe_version_resource("ull"); +} diff --git a/crates/cli/src/cli/help.rs b/crates/cli/src/cli/help.rs new file mode 100644 index 0000000..fa20128 --- /dev/null +++ b/crates/cli/src/cli/help.rs @@ -0,0 +1,287 @@ +//! 帮助文案（`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 列出实例与已安装版本 + instances launch-args [--jvm T] [--game T] [--memory MB] [--java P] + [--backend default|opengl|vulkan] [--clear] + 读/写实例级启动参数（不带选项 = 只读；--clear = 全部回跟随全局） + instances scan 列出 versions/ 里已铺好的版本（含别的启动器装的）：能不能登记 + 原因 + instances adopt [--name N] [--isolation shared|isolated|custom] [--game-dir DIR] + [--dry-run] 把已铺好的版本登记成实例（只读外部、不搬文件；缺省运行目录 + 落 ULL 数据区的独立目录；--dry-run 只检查不写盘） + install [--loader X] [--loader-version V] [--name N] [--dry-run] + 下载并安装版本本体（--loader fabric|quilt|neoforge|forge| + liteloader 时再叠一层加载器）→ 登记实例；--dry-run 只出计划 + launch [--dry-run] [--account ] [--java ] [--username ] + [--max-memory ] 启动实例；--dry-run 只打印组装后的命令行 + pack import [--target ] [--name N] [--overwrite] [--no-register] + 导入整合包（CF manifest.json / Modrinth .mrpack / + MultiMC·Prism 实例）→ 落内容 → 登记实例； + 缺文件降级为「部分成功」（退出码 3） + accounts list 列出账户（名称 / 轨道 / UUID，**不含凭据**） + accounts add offline 添加离线账户（HMCL 兼容 UUID） + accounts add msa 添加微软账户（设备码交互式登录） + accounts remove 删除账户（连同凭据） + sessions list [--limit N] 列出会话记录（倒序） + logs [--tail N] 打印会话事件流末尾 + diag [--tail N] 对会话跑规则引擎诊断 + config get [] [--show-secret] 读配置（生效值；无 key 时输出整份） + config set 写配置（走 setting schema 校验） + java list 列出可用 Java（含每个 JDK 的实际落点） + java install [--vendor X] 安装托管 JDK（缺省按地区回退链选发行版； + --vendor temurin|oracle|microsoft|zulu|termux 钉死一家） + 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 的配置样例 + update check 查一次更新（只读：不动任何文件；失败退出码 1） + update apply [--dest ] 下载 → SHA256 校验 → 替换（缺省替换本进程 exe） + 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\":…}} + 每行实例带 loader:{\"kind\":…,\"version\":…}，由 version_id 解析（core::game::loader 这条唯一入口）： + kind vanilla | fabric | quilt | forge | neoforge | optifine | liteloader； + 原版恒为 {\"kind\":\"vanilla\",\"version\":\"\"}（键恒存在、不为 null，脚本不必判空） + version id 里的加载器版本段；原版、以及 id 里没写版本的（1.12.2-LiteLoader）为空串 + 注意：kind 是「认得出」的口径，不是「装得了」的口径 —— optifine 只能由别的启动器装好后 + 继承进来，install --loader 不接受它；liteloader 自 M222 起**可以**装 + （install --loader liteloader）。kind=vanilla 只表示 id 里没有加载器痕迹（整包导入被 + 重命名的实例也会落成 vanilla），权威结论要读版本 JSON 的 libraries[]。 + +%prog% instances launch-args [--jvm T] [--game T] [--memory MB] [--java P] \ +[--backend default|opengl|vulkan] [--clear] + +读/写实例配置页「启动参数」区（M157）。不带取写选项时只读： + --jvm 实例级 JVM 参数（空白分隔、支持引号）；与全局 java.extra_args **叠加**， + 实例这层在最高优先级段（同名选项实例赢，`-Xmx` 也由它赢过内存字段） + --game 实例级游戏参数（追加在命令行最后，可覆盖前面一切游戏参数） + --memory 实例级最大堆（256~65536）；留空/不写 = 跟随全局 java.default_memory_mb + --java 实例级 Java 可执行文件；留空 = 跟随全局 java.selected_path 再退到自动挑 + --backend default（不下发）/ opengl / vulkan；只对 MC 26.2-snapshot-2+ 下发， + 老版本会被版本门槛拦下（启动时给诊断告警，不静默） + --clear 先把五项清空再应用其它选项（= 全部回「跟随全局」） + 每一项都是「实例 → 全局 → 默认」的独立回落，只填一项不会顶掉别的项。 + 值以 `--` 开头时（多数游戏参数都是）写成 `--game=--fullscreen`：单独一个 `--fullscreen` + 会被当成下一个选项（缺少取值），这是全项目 CLI 的既有解析口径。 + --json 输出 {\"data\":{\"launch\":{…实例层…},\"effective\":{…回落后的生效值…}, …}} + +%prog% instances scan + +列出当前游戏根 versions/ 里已经铺好的版本（可能是别的启动器装的），逐项给结论： + ✓ 可登记 / 已登记（附父链）；✗ 不可登记 + 每条原因（带稳定 code：manifest_missing / + manifest_invalid_json / missing_parent / circular_inheritance / outside_game_root …）。 +只读：不写文件、不改 mtime。versions/ 不存在 = 空结果；versions/ 读不了 = 报错（不当空列表）。 + --json 输出 {\"data\":{\"game_root\":…,\"versions_dir\":…,\"counts\":{…},\"candidates\":[…]}} + 每个 candidate 带 {\"version_id\",\"jar_present\",\"inherits\",\"registered\",\"adoptable\",\"problems\"}。 + +%prog% instances adopt [--name N] [--isolation shared|isolated|custom] + [--game-dir DIR] [--dry-run] + +把 versions// 登记成实例：只读外部、只写自己的配置——不搬文件、不补清单、不改任何 +外部文件的 mtime（versions/ libraries/ assets/ 一个字节都不写）。不读任何启动器的账户凭据。 + 运行目录（--gameDir）三档，缺省不沿用全局 isolated（那会把 mods/saves/config 造进 + 别人的 versions//，那是别的启动器的版本目录）： + 不给 --isolation → <数据根>/.ULL/data/instances/<实例目录名>（新建空目录，隔离档写 custom） + --isolation shared → 别人的游戏根（共用其 mods/saves/config；明确选择后才生效） + --isolation isolated → versions//（第一次启动会在这里新增玩家数据目录） + --isolation custom --game-dir DIR → 指定目录（DIR 必须是绝对路径；不新建、不改动其中内容） + 拒绝（退出码 1，原因逐条进 error.detail.problems）： + · 清单坏了 / 读不出来 / 缺 id / id 与目录名不一致 + · 缺父版本 / 父链成环（说清缺哪个、环是什么） + · 条目解析到游戏根之外（符号链接/目录联接/祖先链接）；versions 入口存在但读不出来（断链） + · 配置写面被链到 .ULL 之外（config/、config/instances/、profiles.json 的真实落点） + · 写盘面与游戏树重叠（.ULL / data / 缺省运行目录解析后落进别人的 .minecraft）⇒ 换不重叠的数据目录； + 整体迁移到游戏树之外仍允许 + · 展示名已被别的实例占用；这个版本已经同名登记过（重复执行 = 无副作用失败） + · 缺省运行目录已存在且非空（空目录可复用；不猜「合并进已有实例」） + · 缺省目录会撞上别的实例（slug 同名 / 大小写不敏感）⇒ 自动顺延 -2/-3… 并点出撞的是谁； + 撞满 32 个后缀才报错（不会让两个实例共用一个运行目录） +--dry-run：只检查并打印将要用的隔离档/运行目录，不写任何文件、不建目录。 + --json 输出 {\"data\":{\"dry_run\":…,\"instance\":{\"id\",\"name\",\"isolation\",\"run_dir\", + \"run_dir_source\",\"config_path\",\"created\"},\"notes\":[…]}}。 +", + ), + "pack" => Some( + "\ +%prog% pack import [--target ] [--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 会逐项列进报告，不静默丢） + +目标目录缺省 = 新实例目录 `<数据根>/.ULL/data/instances/<实例目录名>`（并登记实例，M216 起 + 不再落共享 .minecraft 根；目录名是包名/`--name` 经 ASCII 归一化后的结果，如 `Better-MC`）； + `--target` 可钉到别处（例如某个实例的运行目录）。 +两阶段落盘：先 overrides（三方合并：包内原值 / 磁盘现状 / 上次基线），再补远端文件。 + · 用户改过的文件不会被静默覆盖（默认保留，逐条进冲突清单）；`--overwrite` 才用包覆盖 + · 缺文件（断网 / CurseForge files[] 补不出来）可容忍，但结果降级为「部分成功」 + · 目录穿越 / 符号链接 / 清单损坏 / 摘要不符一律整包回滚，目标目录零残留 +`--no-register`：只落内容，不写 profiles.json。 +退出码：0 成功 / 3 部分成功 / 1 失败（2 内部错误）。 +--json：信封恒为 {\"ok\":true,\"data\":{…}}，分流看 data.status 与 data.error.code； + data.stages 列出实际走过的阶段。", + ), + "update" => Some( + "%prog% update check +%prog% update apply [--dest ] + +自更新（D50：GitHub Releases 固定清单地址，先只发 stable）。 + + check 查一次更新，只读：报告当前版本、渠道、有没有新版（版本号/体积/说明摘要）。 + 四种结论分开报，不折叠：up_to_date / available / missing_artifact（有新版但没本平台 + 产物，属发布侧漏项）/ 失败（退出码 1，code=update_check_failed）。 + apply 先复查一次（清单只有几 KB），有新版才下载 → 长度 + SHA256 双检 → 原子替换。 + 校验不符或替换被占用时**不会**留下暂存文件、也不会破坏现有 exe（自动回滚）。 + 缺省替换本进程的 exe：**下次启动生效**（正在跑的这一份仍是旧版本）。 + --dest 钉到别的路径（取证 / 自定义安装位置）。不写 = 本进程 exe。 + +环境变量 ULL_UPDATE_DIR= + ULL_UPDATE_TEST_SOURCE=1：改走本地目录源（`/stable.json` ++ 产物），用于内网手工分发与更新链路的整环取证。**两者都只在带 `update-test-source` feature +编出来的验收构建里生效**（`cargo build --features update-test-source`）；官方发布构建不含这条 +路径，设了环境变量也照旧走 GitHub。 +--json 输出 {\"data\":{\"status\":…,\"current\":…,\"version\":…}}，脚本按 status 分流。", + ), + "install" => Some( + "\ +%prog% install [--loader X] [--loader-version V] [--name N] [--dry-run] + +解析版本清单与继承链 → 组下载计划 → 落盘（versions/ assets/ libraries/）→ 登记实例 +（profiles.json + config/instances/.json）。已存在且校验通过的文件会跳过， +重复装同一版本不重复下载、不重复建实例。 +--dry-run：只输出计划（文件清单 + 总大小 + 每类资源的源选择），不下载、不登记。 +--loader：vanilla（缺省）/ fabric / quilt / neoforge / forge / liteloader。装加载器时先生成 +versions/<原版>-<加载器>-<版本>/<…>.json（inheritsFrom 父版本 + 主类 + loader 库）， +原版没装会先装原版，实例的 versionId 指向 loader 版本。 + optifine 认得出但**没接入安装管线**（要跑外部 Patcher 并原地改 zip），报 loader_unsupported； + 其余认不出的拼法报 loader_unknown —— 两者不是一回事。 + liteloader 的特殊之处：清单是从官方版本表**从零合成**的（mainClass = launchwrapper， + --tweakClass 追加在父链参数之后），不跑任何外部进程；不叠加载器时只占一个 loader 库。 + 位还可以写**已装的加载器版本 id**（`1.12.2-forge-14.23.5.2860 --loader liteloader`） + 表示「叠在它上面」：原版版本从盘上的继承链读出来，父版本没装会具名报错（不会猜一个原版版本号）。 + 只有 liteloader 接受这种叠法，别家给 usage 错误说清「只能叠在原版上」。 +--loader-version：加载器版本；缺省取官方默认（Fabric 系首个稳定版，maven 系最新， + LiteLoader 优先 release 分支、没有则最新快照）。 + 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 [--dry-run] [--account ] [--java ] [--username ] + [--max-memory ] + + 可以是实例 id、实例名，或直接是版本 id。 +--dry-run（D18）：只组装命令行并打印，不 spawn 进程、不写会话文件、不刷新令牌， +也不碰版本树（不解压 natives、不建 natives 目录，连缺的目录也不补）；启动器自身的 +运行日志（<数据根>/logs/launcher.log）照记，这一点与真实启动一致。 +账户：--account 指定账户（玩家名或条目 id）；不给时用唯一账户，一个都没有则回落 +离线占位（--username 或 Player），有多个账户会报错并列出候选。 +accessToken 一律脱敏（输出里出现的是 ）。", + ), + "accounts" => Some( + "\ +%prog% accounts list +%prog% accounts add offline +%prog% accounts add msa +%prog% accounts remove + +账户存在 <数据根>/.ULL/data/auth/：accounts.json（可公开元数据）与 credentials.dat（凭据） +**分文件**存放，先写凭据后写元数据、原子写、凭据文件 POSIX 侧 0600。 +凭据永不打印：list 只输出名称/轨道/UUID。 +add msa 走微软 device-code（用户码打在 stderr，去 https://www.microsoft.com/link 输码）。 +微软登录所需配置已内置在官方构建里，装完即可用；仍可用环境变量覆盖（优先于内置值）： + ULL_MSA_CLIENT_ID= %prog% accounts add msa 每次运行时给（优先于内置值） + ULL_MSA_CLIENT_ID= cargo build 自己从源码构建时注入，二进制自带 +两处都没有时（只有自建且不自带 id 才会这样）命令立刻报「微软登录未配置」（含怎么配），**不会去联网**。 +authlib-injector 账户的密码登录留给 GUI（密码进 argv 会泄露，CLI 不开这条通道）。", + ), + "sessions" => Some("%prog% sessions list [--limit N] 列出会话索引（按开始时间倒序，缺省 20 条）"), + "logs" => Some("%prog% logs [--tail N] 允许唯一前缀；输出会话 JSONL 末尾 N 条事件（缺省 200）"), + "diag" => Some( + "%prog% diag [--tail N] 把会话的退出信号与日志喂给规则引擎（内嵌规则集），输出结构化诊断", + ), + "config" => Some( + "\ +%prog% config get [] [--show-secret] +%prog% config set + +读写 <数据根>/.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 [--vendor X] 安装托管 JDK（D13/D23）：回退链查版本 → 下载 → 解压 → 验证 +%prog% java vendors 列出各发行版的镜像/支持版本/当前优先级顺序 + +落点（D23 三模式，随 core.data_mode 与设置键 java.installRoot 走）： + portable（默认） <数据根>/.ULL/data/java-managed/jdk--/ + standard Windows %APPDATA%\\Java\\<发行方>\\<版本>\\；macOS ~/Library/Application Support/Java/… + Linux $XDG_DATA_HOME/java/… + custom 设置 java.installRoot 后按 /<发行方>/<版本>/（覆盖前两者） + +发行版回退链（D23）：国内 temurin(TUNA) → oracle(华为云→南大) → microsoft(aka.ms) +→ zulu；国外 temurin → microsoft → oracle → zulu。设置 java.vendorPriority 可改顺序 +（只写几家也行，其余按默认序补齐）；--vendor 钉死一家、不自动降级。 +Termux 上缺省先用系统包（pkg install openjdk-，支持 17/21/25），失败再走归档链； +--vendor termux 只走系统包。每家失败的原因（版本不存在 / 镜像全 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 。 +`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..91b55dc --- /dev/null +++ b/crates/cli/src/cli/mod.rs @@ -0,0 +1,110 @@ +//! 命令行解析（手写，不引 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, InstanceLaunchArgs, Invocation, LaunchArgs, LogsArgs, + PackImportArgs, UpdateApplyArgs, UpdateCheckArgs, +}; +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::>()) + } + + #[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..652fd58 --- /dev/null +++ b/crates/cli/src/cli/model.rs @@ -0,0 +1,284 @@ +//! 命令模型（纯数据）：解析结果就是这里的一个 [`Invocation`]。 + +use std::path::PathBuf; + +use unlucky_core::game::AdoptTarget; + +/// 全局选项（所有命令共享）。 +#[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 `：覆盖数据根（等价 custom 模式的 `custom_root`）。 + pub data_dir: Option, +} + +/// 一条命令。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum Command { + /// 无子命令：版本摘要 + 帮助（用户原话「无子命令时 --version + --help」）。 + Welcome, + /// 只打印版本 + 系统摘要。 + Version, + /// 帮助（`Some(topic)` 给该子命令的帮助）。 + Help(Option), + /// `instances list`。 + InstancesList, + /// `instances scan`：列出当前游戏根里可登记 / 不可登记的外部版本（只读，M221）。 + InstancesScan, + /// `instances adopt [--name N] [--isolation ...] [--game-dir DIR] [--dry-run]`。 + InstancesAdopt(InstancesAdoptArgs), + /// `instances launch-args [--jvm …] [--game …] [--memory …] [--java …] [--backend …] [--clear]`。 + InstancesLaunchArgs(InstanceLaunchArgs), + /// `install [--loader X] [--name N]`。 + Install(InstallArgs), + /// `pack import [--target ] [--name N] [--overwrite] [--no-register]`。 + PackImport(PackImportArgs), + /// `launch [--dry-run]`。 + Launch(LaunchArgs), + /// `sessions list [--limit N]`。 + SessionsList { + /// 最多返回几条。 + limit: usize, + }, + /// `logs [--tail N]`。 + Logs(LogsArgs), + /// `diag `。 + Diag(DiagArgs), + /// `config get []`。 + ConfigGet(ConfigGetArgs), + /// `config set `。 + ConfigSet(ConfigSetArgs), + /// `java list`。 + JavaList, + /// `java install [--vendor X]`。 + JavaInstall { + /// 目标 JDK 主版本（8 / 17 / 21）。 + major: u32, + /// 钉死的发行版（缺省走 D23 的回退链）。 + vendor: Option, + }, + /// `java vendors`：列出各发行版的可用性 / 镜像 / 当前优先级。 + JavaVendors, + /// `accounts list`。 + AccountsList, + /// `accounts add []`。 + AccountsAdd(AccountsAddArgs), + /// `accounts remove `。 + AccountsRemove { + /// 账户名（或条目 id）。 + name: String, + }, + /// `agent serve`：对外 MCP server（长驻）。 + AgentServe(AgentServeArgs), + /// `update check`：查一次更新，不动任何文件。 + UpdateCheck(UpdateCheckArgs), + /// `update apply [--dest ]`：下载 → 校验 → 替换（默认替换本进程 exe）。 + UpdateApply(UpdateApplyArgs), + /// `agent config`：打印 Claude Code / Cursor 的客户端配置样例。 + AgentConfig { + /// 覆盖端点端口（默认取设置键 `agent.mcp.port`）。 + port: Option, + }, +} + +/// `update check` 的参数（现在没有选项，留一个结构体以免将来加选项时改签名）。 +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct UpdateCheckArgs {} + +/// `update apply` 的参数。 +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct UpdateApplyArgs { + /// 替换目标（缺省 = 本进程的 exe；取证/自定义安装位置时才给）。 + pub dest: Option, +} + +/// `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, + /// 覆盖监听地址（只接受回环地址，非回环会被 server 拒绝）。 + pub host: Option, + /// 本次运行放开写工具（仍需设置键 `agent.mcp.allow_write` 或本 flag 之一）。 + pub allow_write: bool, +} + +/// `accounts add` 的轨道。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum AccountsAddKind { + /// 离线（`add offline `）。 + 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, +} + +/// `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` / `liteloader`； + /// `optifine` 认得出但没接安装管线，报 `loader_unsupported`）。 + pub loader: Option, + /// 加载器版本（缺省取官方默认：Fabric 系首个稳定版，maven 系该原版下最新）。 + pub loader_version: Option, + /// 实例显示名（缺省用版本 id）。 + pub name: Option, + /// 只出安装计划（列清单 + 总大小 + 源选择），不下载、不登记。 + 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, + /// 目标实例目录（缺省 = 新实例目录 `<数据根>/.ULL/data/instances/<实例目录名>`，M216 前是 + /// 共享游戏目录 `game_home`）。 + pub target: Option, + /// 实例显示名（缺省 = 包名）。 + pub name: Option, + /// 冲突时用包内内容覆盖（缺省保留用户文件）。 + 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, + /// 离线账户名（缺省 `Player`）。 + pub username: Option, + /// 账户名（`accounts` 里的玩家名或条目 id）；缺省用唯一账户。 + pub account: Option, + /// 最大堆（MB）。 + pub max_memory: Option, +} + +/// `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, +} + +/// `instances adopt` 的参数（M221：把盘上已有的版本登记成实例，只读外部、只写自己的配置）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct InstancesAdoptArgs { + /// 要接入的版本 id（= `versions//`）。 + pub version_id: String, + /// 展示名（缺省 = 版本 id）。 + pub name: Option, + /// 运行目录选择：缺省 [`AdoptTarget::InstanceDir`]（ULL 数据区新目录）， + /// `shared` / `isolated` / `custom` 都必须显式给。 + pub target: AdoptTarget, + /// 只检查、不写任何文件（`--dry-run`）。 + pub dry_run: bool, +} + +/// `instances launch-args` 的参数（M157：实例级启动参数）。 +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct InstanceLaunchArgs { + /// 实例 id 或实例名。 + pub instance: String, + /// 实例级 JVM 参数（空白分隔，支持引号）。 + pub jvm_args: Option, + /// 实例级游戏参数。 + pub game_args: Option, + /// 实例级最大堆（MiB 文本；空串由 `--memory ""` 表达「跟随全局」）。 + pub memory_mb: Option, + /// 实例级 Java 可执行文件。 + pub java: Option, + /// 图形后端（`default` / `opengl` / `vulkan`）。 + pub backend: Option, + /// 先清空五项再应用给出的项（`--clear`；不带其它选项时等于「全部跟随全局」）。 + pub clear: bool, +} + +impl InstanceLaunchArgs { + /// 这次调用是不是纯读取（没有任何写入口）。 + #[must_use] + pub fn is_read_only(&self) -> bool { + !self.clear + && self.jvm_args.is_none() + && self.game_args.is_none() + && self.memory_mb.is_none() + && self.java.is_none() + && self.backend.is_none() + } +} + +/// `config get` 的参数。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ConfigGetArgs { + /// 点分键路径；`None` 表示整份生效配置。 + pub key: Option, + /// 敏感键也输出明文（默认脱敏）。 + 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..f210e28 --- /dev/null +++ b/crates/cli/src/cli/parse.rs @@ -0,0 +1,382 @@ +//! 手写解析器：全局选项 → 子命令 → 子命令内的选项。 + +use std::collections::BTreeMap; +use std::path::PathBuf; + +use unlucky_core::game::java::JdkVendor; + +use crate::error::CliError; + +mod accounts; +mod agent; +mod instances; +mod update; + +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 { + let mut globals = Globals::default(); + let mut rest: Vec = 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 { + 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" => 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), + "update" => update::parse_update(tail), + other => { + Err(CliError::usage(format!("未知命令 `{other}`")) + .with_hint("%prog% --help 查看命令列表")) + } + } +} + +fn parse_install(tail: &[String], globals: &Globals) -> Result { + let parsed = parse_flags(tail, &["loader", "loader-version", "name"], &["dry-run"])?; + let version = require_single_positional(&parsed, "install ")?; + 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 [--target ] [--name N] [--overwrite] [--no-register]`。 +fn parse_pack(tail: &[String]) -> Result { + let Some(sub) = tail.first().map(String::as_str) else { + return Err(CliError::usage("pack 需要子命令 import") + .with_hint("%prog% pack import [--target ]")); + }; + 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 ")?; + 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 { + let parsed = parse_flags( + tail, + &["java", "username", "account", "max-memory"], + &["dry-run"], + )?; + let instance = require_single_positional(&parsed, "launch ")?; + let max_memory = match parsed.value("max-memory") { + Some(raw) => Some( + raw.parse::() + .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 { + 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::() + .map_err(|_| CliError::usage(format!("--limit 需要整数，收到 `{raw}`")))?, + None => DEFAULT_SESSION_LIMIT, + }; + Ok(Command::SessionsList { limit }) +} + +fn parse_logs(tail: &[String]) -> Result { + let parsed = parse_flags(tail, &["tail"], &[])?; + let session_id = require_single_positional(&parsed, "logs ")?; + 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 { + let parsed = parse_flags(tail, &["tail"], &[])?; + let session_id = require_single_positional(&parsed, "diag ")?; + 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 { + let Some(sub) = tail.first().map(String::as_str) else { + return Err(CliError::usage("config 需要子命令 get|set") + .with_hint("%prog% config get / %prog% config set ")); + }; + 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 ", + )); + } + 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 { + 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 ")?; + let major = raw + .parse::() + .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 { + 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 { + match parsed.value(name) { + Some(raw) => raw + .parse::() + .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, + flags: BTreeMap>, +} + +impl ParsedArgs { + fn value(&self, name: &str) -> Option { + 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 { + 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 { + 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 ` +//! - `ull accounts add msa`（别名 `microsoft`） +//! - `ull accounts remove `（别名 `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 { + 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 ")?; + Ok(Command::AccountsRemove { name }) + } + other => Err(CliError::usage(format!( + "accounts 的子命令只有 list|add|remove，收到 `{other}`" + ))), + } +} + +fn parse_add(rest: &[String]) -> Result { + 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 ")?; + 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 `。 +/// +/// # Errors +/// 缺子命令、未知子命令、未知选项、端口不是 1~65535 时返回用法错误。 +pub fn parse_agent(tail: &[String]) -> Result { + 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 { + 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 { + 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, CliError> { + match parsed.value("port") { + Some(raw) => Ok(Some(raw.parse::().map_err(|_| { + CliError::usage(format!("--port 需要 1~65535，收到 `{raw}`")) + })?)), + None => Ok(None), + } +} diff --git a/crates/cli/src/cli/parse/instances.rs b/crates/cli/src/cli/parse/instances.rs new file mode 100644 index 0000000..b9a42d1 --- /dev/null +++ b/crates/cli/src/cli/parse/instances.rs @@ -0,0 +1,114 @@ +//! `instances` 的子命令解析（`list` / `launch-args` / `scan` / `adopt`）。 +//! +//! 从 `parse.rs` 拆出来只为守 400 行硬线（M157 的 `launch-args` 让那边到 415 行）； +//! 纯搬移，语义未变。M221 在这里加了 `scan` 与 `adopt` 两个只读/登记入口。 + +use std::path::PathBuf; + +use unlucky_core::game::AdoptTarget; + +use super::super::model::{InstanceLaunchArgs, InstancesAdoptArgs}; +use super::*; + +pub(super) fn parse_instances(tail: &[String]) -> Result { + let args = match tail.first().map(String::as_str) { + None | Some("list") => tail.get(1..).unwrap_or_default(), + Some("launch-args") => { + return parse_instances_launch_args(tail.get(1..).unwrap_or_default()) + } + Some("scan") => { + let parsed = parse_flags(tail.get(1..).unwrap_or_default(), &[], &[])?; + ensure_no_positionals(&parsed, "instances scan")?; + return Ok(Command::InstancesScan); + } + Some("adopt") => return parse_instances_adopt(tail.get(1..).unwrap_or_default()), + Some(other) => { + return Err(CliError::usage(format!( + "instances 的子命令只有 list / launch-args / scan / adopt，收到 `{other}`" + ))) + } + }; + let parsed = parse_flags(args, &[], &[])?; + ensure_no_positionals(&parsed, "instances list")?; + Ok(Command::InstancesList) +} + +/// `instances launch-args [--jvm …] [--game …] [--memory …] [--java …] [--backend …] [--clear]`。 +/// +/// 五个取值选项都接受空串（`--jvm ""`）= 该清空，与 `--clear` 的「先清后改」互补。 +fn parse_instances_launch_args(tail: &[String]) -> Result { + let parsed = parse_flags( + tail, + &["jvm", "game", "memory", "java", "backend"], + &["clear"], + )?; + let instance = require_single_positional(&parsed, "instances launch-args ")?; + Ok(Command::InstancesLaunchArgs(InstanceLaunchArgs { + instance, + jvm_args: parsed.value("jvm"), + game_args: parsed.value("game"), + memory_mb: parsed.value("memory"), + java: parsed.value("java"), + backend: parsed.value("backend"), + clear: parsed.has("clear"), + })) +} + +/// `instances adopt [--name N] [--isolation shared|isolated|custom] [--game-dir DIR] [--dry-run]`。 +/// +/// 运行目录的词表只在这里翻译一次（[`AdoptTarget::parse`] 是唯一判据）： +/// - 什么都不给 ⇒ [`AdoptTarget::InstanceDir`]（ULL 数据区新目录，**不沿用全局 `isolated`**）； +/// - `--isolation custom` 必须配 `--game-dir`； +/// - `--isolation shared|isolated` 不许再配 `--game-dir`（那两个档的运行目录是派生的）。 +fn parse_instances_adopt(tail: &[String]) -> Result { + let parsed = parse_flags(tail, &["name", "isolation", "game-dir"], &["dry-run"])?; + let version_id = require_single_positional(&parsed, "instances adopt ")?; + let isolation = parsed.value("isolation"); + let game_dir = match parsed.value("game-dir") { + Some(raw) => { + let dir = PathBuf::from(&raw); + // 用法错误在解析期就报（和 `--data-dir` 同一口径），别把「参数写错」拖成命令期失败。 + if !dir.is_absolute() { + return Err(CliError::usage(format!( + "--game-dir 需要绝对路径，收到 `{raw}`" + ))); + } + Some(dir) + } + None => None, + }; + let target = match isolation.as_deref() { + None => match game_dir { + // `--game-dir` 单独给 = 就是 custom（少写一个选项，不制造第二种说法）。 + Some(dir) => AdoptTarget::Custom(dir), + // 缺省**只能**来自 core 的 `AdoptTarget::default()`：这里再写一遍 `InstanceDir` + // 就等于有了第二处真相源，改缺省时会漏一处。 + None => AdoptTarget::default(), + }, + Some("custom") => { + let dir = game_dir.ok_or_else(|| { + CliError::usage("--isolation custom 需要配 --game-dir （绝对路径）") + })?; + AdoptTarget::Custom(dir) + } + Some(other) => { + if game_dir.is_some() { + return Err(CliError::usage( + "--game-dir 只配 --isolation custom（shared / isolated 的运行目录是派生的）", + )); + } + AdoptTarget::parse(other, None).ok_or_else(|| { + CliError::usage(format!( + "--isolation 只有 shared|isolated|custom，收到 `{other}`" + )) + .with_hint("不给 --isolation = 落 ULL 数据区的独立运行目录（推荐）") + })? + } + }; + Ok(Command::InstancesAdopt(InstancesAdoptArgs { + version_id, + name: parsed.value("name"), + target, + dry_run: parsed.has("dry-run"), + })) +} diff --git a/crates/cli/src/cli/parse/update.rs b/crates/cli/src/cli/parse/update.rs new file mode 100644 index 0000000..3542f6c --- /dev/null +++ b/crates/cli/src/cli/parse/update.rs @@ -0,0 +1,46 @@ +//! `ull update` 子命令的解析（从 `parse.rs` 拆出，避免解析器主文件顶到 400 行）。 +//! +//! 语法： +//! - `ull update check` +//! - `ull update apply [--dest ]` +//! +//! 两条命令都只是「造一个 `core::update::Job` → 调 `check` / `apply` → 排版输出」， +//! 判定（版本比较、渠道准入、清单校验）与替换（双检 + 原子改名）全在 core。 +//! `--dest` 钉替换目标，缺省是本进程的 exe（取证 / 自定义安装位置时才给）。 +//! +//! ## 为什么单独一个文件 +//! +//! `parse.rs` 在加进这两条之后是 406 行，撞仓库 400 行硬线（`guards.yml` 的 `file-size` +//! 作业按 `git ls-files '*.rs'` + `wc -l > 400` 判红）。拆法与 `parse/{accounts,agent, +//! instances}.rs` 一致：一个子命令族一个文件，主文件只留分发。 + +use std::path::PathBuf; + +use super::{ensure_no_extra, ensure_no_positionals, parse_flags}; +use crate::cli::model::{Command, UpdateApplyArgs, UpdateCheckArgs}; +use crate::error::CliError; + +/// 解析 `update ...`。 +pub(super) fn parse_update(tail: &[String]) -> Result { + let Some(sub) = tail.first().map(String::as_str) else { + return Err(CliError::usage("update 需要子命令 check|apply") + .with_hint("%prog% update check / %prog% update apply")); + }; + let rest = tail.get(1..).unwrap_or_default(); + match sub { + "check" => { + ensure_no_extra(rest, "update check")?; + Ok(Command::UpdateCheck(UpdateCheckArgs {})) + } + "apply" => { + let parsed = parse_flags(rest, &["dest"], &[])?; + ensure_no_positionals(&parsed, "update apply")?; + Ok(Command::UpdateApply(UpdateApplyArgs { + dest: parsed.value("dest").map(PathBuf::from), + })) + } + other => Err(CliError::usage(format!( + "update 的子命令只有 check|apply，收到 `{other}`" + ))), + } +} 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 ` / `add msa` / `remove `； +//! 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 { + 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 = 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 `。 +/// +/// # Errors +/// +/// 名字不合法、同名账户已存在、落盘失败。 +pub fn add(ctx: &Ctx, args: &AccountsAddArgs) -> Result { + 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 { + 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 { + // 失败日志落**本次命令的实际数据根**（`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 `。 +/// +/// # Errors +/// +/// 找不到该账户、落盘失败。 +pub fn remove(ctx: &Ctx, name: &str) -> Result { + 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..325ed41 --- /dev/null +++ b/crates/cli/src/commands/agent/mod.rs @@ -0,0 +1,136 @@ +//! `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 probe; +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 { + 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 { + 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) -> Result { + 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 { + 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) -> Self { + Self { root: root.into() } + } +} + +impl AccountPort for CoreAccounts { + fn list_accounts(&self) -> PortResult> { + 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..0558925 --- /dev/null +++ b/crates/cli/src/commands/agent/ports/diagnose.rs @@ -0,0 +1,296 @@ +//! 诊断端口：调用 M15 的规则引擎（**规则先跑，模型补位**，02 §3.2）。 +//! +//! 工具层只把「规则结论 + 相关片段」交给模型，不把裸日志倒进去——这是 token 预算 +//! 与结论质量的双重考虑，也是 analyse/02 §8.3 的分层思路。 +//! +//! ## M242：结论读**会话里落盘的那份**，不在脱敏文本上重跑 +//! +//! 会话 JSONL 是写前脱敏的，而脱敏拿不准形状时是**有损**的：`≥64` 的不透明串、带点的票据串 +//! 都会被换成占位符。M240 收窄了这条规则——**路径形状**的长串现在整条保留，所以 M239 实测的 +//! 那条 `org/spongepowered/…/FabricMixinTransformerProxy` 今天能活下来。但那是**白名单**： +//! 形状一变（或又登记了别的 secret）就回到「抹掉」那一侧，而抹掉之后的重跑不是「少一点细节」， +//! 是**换一条结论** —— `fabric.loader_0_12`（critical）降级成 `integrity.no_class_def_found` +//! （warning），把「Fabric Loader 版本不配套」说成「库没下全」。M241 起写会话时已经在 +//! **原始行**上算过一次结论并落成 `diagnosis` 事件，这里优先读它；没有该事件的老会话才回落到 +//! 重跑（与今天的读法完全一致）。 +//! +//! **隐私选择不变**：给模型的游戏日志仍是脱敏文本（`read_game_log` 与这里的 `evidence` +//! 片段都没动）。变的只是「结论从哪儿来」——盘上那份结论自己也是写入时过 `scrub_json` 的， +//! 所以既没把原文写进盘，也没把原文交给模型。 + +use std::collections::BTreeMap; + +use serde_json::Value; +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 unlucky_core::launch::session_index::SessionIndexEntry; + +use super::events::{tail_join, SessionSource}; + +#[cfg(test)] +#[path = "diagnose/tests.rs"] +mod tests; + +/// 送进规则引擎的默认尾巴行数（与 CLI `diag` 同值，避免两条路看到不同证据）。 +pub const DEFAULT_TAIL: usize = 2000; + +/// 会话级证据片段条数（与重跑路径同值：`stderr` 末尾 3 行）。 +const EVIDENCE_LINES: usize = 3; + +/// M15 规则引擎的端口实现。 +#[derive(Debug, Clone)] +pub struct CoreDiagnose { + source: SessionSource, + tail: usize, +} + +impl CoreDiagnose { + /// `root` = `<数据根>/.ULL/logs`（M188 起；旧名是 `data/agent/sessions`）。 + #[must_use] + pub fn new(root: impl Into) -> Self { + Self { + source: SessionSource::new(root), + tail: DEFAULT_TAIL, + } + } + + /// 再挂一个只读兼容的旧根（`data/agent/sessions`）：旧会话也能诊断。 + #[must_use] + pub fn with_legacy(mut self, legacy: impl Into) -> Self { + self.source = self.source.with_legacy(legacy); + self + } +} + +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::>(), + }) + .collect(), + } +} + +// ─────────────────── 落盘的结论（`diagnosis` 事件） ─────────────────── +// +// 下面三个是 `unlucky_core::diagnose::finding::{DiagnosisRecord, Candidate, +// MaterializedFixAction}` 的**只读镜像**：core 侧那些类型只 derive `Serialize`（写盘用）， +// agent 侧的类型也只 derive `Serialize`（回灌给模型用），所以「读回来」这一件事在这里落一次。 + +/// `diagnosis` 事件的 payload。 +#[derive(Debug, Default, serde::Deserialize)] +struct StoredRecord { + #[serde(default)] + source: Option, + #[serde(default)] + needs_more_info: bool, + #[serde(default)] + candidates: Vec, + #[serde(default)] + secondary: Vec, +} + +/// 一条落盘的候选结论。 +#[derive(Debug, Default, serde::Deserialize)] +struct StoredCandidate { + #[serde(default)] + id: String, + #[serde(default)] + severity: String, + #[serde(default)] + category: String, + #[serde(default)] + confidence: f32, + #[serde(default)] + message_key: String, + #[serde(default)] + message: String, + #[serde(default)] + detail: Option, + #[serde(default)] + evidence: Vec, + #[serde(default)] + fix_actions: Vec, +} + +/// 一条落盘的修复动作（`kind` 是 `snake_case` 的六维之一）。 +#[derive(Debug, Default, serde::Deserialize)] +struct StoredAction { + #[serde(default)] + kind: String, + #[serde(default)] + tool: String, + #[serde(default)] + args: BTreeMap, +} + +impl StoredRecord { + /// 事件流里最后一条**有主因**的 `diagnosis` 事件。 + /// + /// 正常只有一条（挂钩写的或收尾补的，二选一）；真有多条取**最后一条**：收尾补的证据最新鲜。 + /// 没有候选的 payload 与「没结论」等价（`conclude` 也不会写它）→ 返回 `None`，让调用方回落重跑。 + fn find(events: &[Value]) -> Option { + let payload = events + .iter() + .rev() + .find(|event| event.get("kind").and_then(Value::as_str) == Some("diagnosis"))? + .get("payload")?; + let record: Self = serde_json::from_value(payload.clone()).ok()?; + (!record.candidates.is_empty()).then_some(record) + } + + /// 落盘结论 → 给模型的 [`CrashDiagnosis`]。 + /// + /// `exit` 仍取自索引条目（launch 报的事实，与盘上那份结论的计算输入同源）， + /// `evidence` 仍是**脱敏**的 stderr 尾窗——隐私选择不变，只有结论换了来源。 + fn into_diagnosis(self, entry: &SessionIndexEntry, evidence: Vec) -> CrashDiagnosis { + CrashDiagnosis { + session_id: entry.session_id.clone(), + source: self.source.unwrap_or_else(|| "rules".to_string()), + needs_more_info: self.needs_more_info, + candidates: self + .candidates + .into_iter() + .map(StoredCandidate::into_candidate) + .collect(), + secondary: self + .secondary + .into_iter() + .map(StoredCandidate::into_candidate) + .collect(), + evidence, + exit: ExitSummary { + code: entry.exit_code, + exit_type: entry.exit_type.clone(), + silent_failure: entry.silent_failure, + }, + } + } +} + +impl StoredCandidate { + fn into_candidate(self) -> DiagnosisCandidate { + DiagnosisCandidate { + id: self.id, + severity: self.severity, + category: self.category, + confidence: self.confidence, + message_key: self.message_key, + message: self.message, + detail: self.detail.unwrap_or_default(), + evidence: self.evidence, + fix_actions: self + .fix_actions + .into_iter() + .filter_map(StoredAction::into_action) + .collect(), + } + } +} + +impl StoredAction { + /// 未知维度返回 `None`：宁可少一条建议，也不瞎猜成别的维度（六维口径在 core 一处）。 + fn into_action(self) -> Option { + let kind = match self.kind.as_str() { + "change_java" => FixActionKind::ChangeJava, + "adjust_memory" => FixActionKind::AdjustMemory, + "change_graphics" => FixActionKind::ChangeGraphics, + "remove_mod" => FixActionKind::RemoveMod, + "reinstall" => FixActionKind::Reinstall, + "seek_help" => FixActionKind::SeekHelp, + _ => return None, + }; + Some(FixAction { + kind, + tool: self.tool, + label: String::new(), + args: self.args, + }) + } +} + +impl DiagnosePort for CoreDiagnose { + fn diagnose(&self, session_id: &str) -> PortResult { + let entry = self.source.find(session_id)?; + let events = self.source.events(&entry)?; + let (stdout, stderr, error_lines) = SessionSource::split_text(&events); + + // 会话级证据片段：仍是**脱敏**文本（隐私选择不变）。 + let evidence: Vec = stderr.iter().rev().take(EVIDENCE_LINES).cloned().collect(); + + // 盘上有结论就用它——那是写会话时在原始行上算的，不是这份脱敏文本能重算出来的。 + if let Some(record) = StoredRecord::find(&events) { + return Ok(record.into_diagnosis(&entry, evidence)); + } + + // 老会话（M241 之前的 JSONL）：回落到在脱敏文本上重跑。 + 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, + exit: ExitSummary { + code: entry.exit_code, + exit_type: entry.exit_type.clone(), + silent_failure: entry.silent_failure, + }, + }) + } +} diff --git a/crates/cli/src/commands/agent/ports/diagnose/tests.rs b/crates/cli/src/commands/agent/ports/diagnose/tests.rs new file mode 100644 index 0000000..49853f5 --- /dev/null +++ b/crates/cli/src/commands/agent/ports/diagnose/tests.rs @@ -0,0 +1,187 @@ +//! M242：AI 侧 `diagnose_crash` 的结论来源（落盘那份优先，老会话回落重跑）。 +//! +//! 两条端到端用例都走**真链路**：真 `SessionWriter` 写盘 → 真工具注册（ +//! `unlucky_agent::tools::diagnose::register`）→ 真 handler。判据是「命中哪条规则」， +//! 因为脱敏有损：在脱敏文本上重跑会**换一条**规则（`fabric.loader_0_12` → +//! `integrity.no_class_def_found`）。 +//! +//! ## 夹具为什么把类路径登记成 secret +//! +//! M240 收窄了「`≥64` 不透明串」那条规则（路径形状的长串现在保留），所以 `SessionWriter` +//! 落盘时这条证据行今天**不会被抹**。要复现「读回脱敏文本就丢了证据」这个世界（M239 实测的 +//! 老落盘形状），夹具把类路径登记成 secret：写盘前它变成 ``，而结论是在 +//! **原始行**上算的 —— 与用户盘上真实存在的那类会话同样失真，足以分辨两条路。 +//! +//! 变异证明（改完已还原）： +//! - 删掉 `diagnose()` 里的 `StoredRecord::find(&events)` 分支（等于每次都重跑）⇒ +//! `ai_gets_the_stored_conclusion...` 红（`candidates[0].id` 变成 `integrity.no_class_def_found`）。 + +use std::path::Path; +use std::sync::Arc; + +use serde_json::{json, Value}; +use unlucky_agent::port::DiagnosePort; +use unlucky_agent::registry::{ToolCtx, ToolRegistry}; +use unlucky_agent::tools::diagnose::DIAGNOSE_CRASH; +use unlucky_core::launch::exit_analysis::{self, ExitSignals}; +use unlucky_core::launch::pump::{LogLine, Stream}; +use unlucky_core::launch::redact::Redactor; +use unlucky_core::launch::session::{EndReason, SessionMeta, SessionWriter}; +use unlucky_core::launch::session_index; + +use super::CoreDiagnose; + +/// `fabric.loader_0_12`（critical / priority 80）唯一的证据行（`rules.d/fabric.yaml`）里的类路径。 +const CLASS_PATH: &str = "org/spongepowered/asm/mixin/transformer/FabricMixinTransformerProxy"; +/// 真凭据（写盘前必须被抹掉的形状）。 +const TOKEN: &str = "SECRET-TOKEN-123456"; + +/// 那条完整的证据行。 +fn evidence_line() -> String { + format!("java.lang.NoClassDefFoundError: {CLASS_PATH}") +} + +/// 一个临时数据根（`` 当数据根，会话根就是 ``——端口只认会话根这一层）。 +fn temp_root(tag: &str) -> std::path::PathBuf { + let root = std::env::temp_dir().join(format!("ull-m242-{tag}-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&root); + root +} + +/// 与生产写入同形（M212/D2）：`log_path` 相对会话根，事件流落在 `<根>/game/.jsonl`。 +fn seed(root: &std::path::Path, stderr_line: &str) { + let sid = "20261029T124501-9f3c2a"; + let log_path = session_index::log_path_for(sid); + let index = session_index::index_path(root); + std::fs::create_dir_all(index.parent().expect("索引父目录")).expect("建目录"); + let entry = json!({ + "v": 1, + "session_id": sid, + "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": log_path.clone(), + "crash_found": true, + "diagnosis_top": null + }); + std::fs::write(index, 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( + session_index::event_file(root, &log_path), + format!("{event}\n"), + ) + .expect("写事件"); +} + +/// 一局真会话：`SessionWriter` 写盘（写前脱敏）→ `finish` 在原始行上补结论。 +fn write_real_session(sessions_root: &Path) -> String { + let session_id = "20261102T091500-m242ai"; + let mut writer = SessionWriter::create_with_id( + sessions_root, + session_id, + SessionMeta::new("inst-1", "1.20.1 Fabric", "1.20.1"), + // 类路径登记成 secret ⇒ 盘上那条证据行被抹掉（见模块文档：为什么要人为造这份失真）。 + Redactor::new().with_secret(TOKEN).with_secret(CLASS_PATH), + ) + .expect("建会话"); + writer.session_start().expect("session_start"); + let lines = vec![ + LogLine::new(Stream::Stderr, "Failed to start Fabric loader"), + LogLine::new(Stream::Stderr, evidence_line()), + LogLine::new(Stream::Stdout, format!("auth: token={TOKEN}")), + ]; + for line in &lines { + writer.line(line).expect("写行"); + } + let analysis = exit_analysis::analyze(&ExitSignals::new(1, 40_000, &lines)); + writer.exit(&analysis).expect("exit"); + writer.finish(EndReason::Exit).expect("finish"); + session_id.to_string() +} + +/// 走真工具入口调 `diagnose_crash`：注册表 + schema + handler 与 `ull agent serve` 同一份。 +fn call_diagnose_crash(sessions_root: &Path, session_id: &str) -> Value { + let mut registry = ToolRegistry::new(); + unlucky_agent::tools::diagnose::register( + &mut registry, + Arc::new(CoreDiagnose::new(sessions_root)), + ) + .expect("注册 diagnose_crash"); + let spec = registry.get(DIAGNOSE_CRASH).expect("工具已注册").clone(); + let ctx = ToolCtx { + agent_session_id: "m242".to_string(), + confirmed: false, + }; + let output = + (spec.handler)(&ctx, &json!({ "session_id": session_id })).expect("diagnose_crash 应成功"); + output.content +} + +#[test] +fn ai_gets_the_stored_conclusion_instead_of_a_rerun_on_redacted_text() { + let root = temp_root("ai-stored"); + let session_id = write_real_session(&root); + + let content = call_diagnose_crash(&root, &session_id); + assert_eq!(content["session_id"], session_id.as_str()); + assert_eq!( + content["candidates"][0]["id"], "fabric.loader_0_12", + "落盘的结论必须原样交给模型（重跑会降级成 integrity.no_class_def_found）：{content}" + ); + assert_eq!(content["needs_more_info"], false); + let confidence = content["top_confidence"].as_f64().expect("置信度是数字"); + assert!( + (confidence - 0.85).abs() < 1e-3, + "落盘结论的置信度应原样透传：{content}" + ); + + // 隐私选择不变：给模型的文本片段仍是脱敏的（类路径与凭据都不许出现）。 + let rendered = content.to_string(); + assert!( + !rendered.contains("FabricMixinTransformerProxy"), + "{rendered}" + ); + assert!(!rendered.contains(TOKEN), "{rendered}"); + + let _ = std::fs::remove_dir_all(&root); +} + +#[test] +fn runs_the_rule_engine_over_a_session() { + let root = temp_root("diagnose"); + 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)); + // 老会话（没有 `diagnosis` 事件）→ 回落重跑：规则集里应有完整性类结论命中这条 stderr。 + assert!(!report.candidates.is_empty(), "应至少命中一条规则"); + assert_eq!(report.candidates[0].id, "integrity.no_class_def_found"); + + let _ = std::fs::remove_dir_all(&root); +} + +#[test] +fn unknown_session_is_a_readable_error() { + let root = temp_root("diagnose-none"); + 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..dfd28e8 --- /dev/null +++ b/crates/cli/src/commands/agent/ports/events.rs @@ -0,0 +1,279 @@ +//! 会话数据的读取底座：索引（`index.jsonl`）+ 事件流（`.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; + +/// 一个数据根下的会话索引 + 事件流（可以再挂一个**只读兼容**的旧根，M188）。 +#[derive(Debug, Clone)] +pub struct SessionSource { + root: PathBuf, + legacy: Option, +} + +impl SessionSource { + /// `root` = `<数据根>/.ULL/logs`（M188 起；旧名是 `data/agent/sessions`）。 + #[must_use] + pub fn new(root: impl Into) -> Self { + Self { + root: root.into(), + legacy: None, + } + } + + /// 再挂一个只读兼容的旧根（`data/agent/sessions`）：旧的会话仍然列得出来、打得开。 + #[must_use] + pub fn with_legacy(mut self, legacy: impl Into) -> Self { + self.legacy = Some(legacy.into()); + self + } + + /// 读会话时要看的根，**新根在前**。 + fn roots(&self) -> Vec<&Path> { + let mut roots = vec![self.root.as_path()]; + if let Some(legacy) = &self.legacy { + if legacy.is_dir() { + roots.push(legacy.as_path()); + } + } + roots + } + + /// 索引文件路径（新根）。 + #[must_use] + pub fn index(&self) -> PathBuf { + session_index::index_path(&self.root) + } + + /// 全部会话（按 `started_at` 倒序，同 id 取最后一行；两个根合并，新根优先）。 + /// + /// # Errors + /// 索引读不了（权限/IO）时返回用户可读错误；不存在视为空列表。 + pub fn entries(&self) -> PortResult> { + let mut merged: Vec = Vec::new(); + for root in self.roots() { + let index = session_index::index_path(root); + let entries = session_index::read_all(&index) + .map_err(|error| format!("读会话索引 {} 失败：{error}", index.display()))?; + for entry in entries { + if merged + .iter() + .any(|item| item.session_id == entry.session_id) + { + continue; + } + merged.push(entry); + } + } + merged.sort_by(|a, b| b.started_at.cmp(&a.started_at)); + Ok(merged) + } + + /// 按完整 id 或唯一前缀找会话。 + /// + /// # Errors + /// 找不到 / 前缀歧义时返回用户可读错误。 + pub fn find(&self, key: &str) -> PortResult { + 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> { + 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::(line).ok()) + .collect()) + } + + /// 事件流文件路径（新根没有时回落到旧根）。 + /// + /// 解析只走 [`session_index::event_file`] 一处（M212/D2）：索引里的 `log_path` 已经是 + /// **相对会话根**的 `game/.jsonl`，这里再拼一层 `game/` 就会拼成 + /// `game/game/.jsonl` —— `ull agent` / MCP 的「读游戏日志」「诊断崩溃」两个工具 + /// 因此对每个真实会话都报「读会话事件流失败」，夹具写裸文件名时这个 bug 测不出来。 + #[must_use] + pub fn event_path(&self, entry: &SessionIndexEntry) -> PathBuf { + for root in self.roots() { + let path = session_index::event_file(root, &entry.log_path); + if path.is_file() { + return path; + } + } + // 两处都没有：返回**新根**的路径，调用方据此说出「该去哪找」。 + session_index::event_file(&self.root, &entry.log_path) + } + + /// 事件里的 stdout / stderr 文本（诊断与日志阅读共用）。 + /// + /// 返回 `(stdout 行, stderr 行, stderr 里 level=error 的条数)`。 + #[must_use] + pub fn split_text(events: &[Value]) -> (Vec, Vec, 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() +} + +#[cfg(test)] +mod tests { + use super::*; + use serde_json::json; + + const SID: &str = "20261029T124501-9f3c2a"; + + fn entry(log_path: &str) -> SessionIndexEntry { + serde_json::from_value(json!({ + "v": 1, + "session_id": SID, + "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": 1, + "log_path": log_path, + "crash_found": false, + "diagnosis_top": null + })) + .expect("索引条目") + } + + fn temp_root(tag: &str) -> PathBuf { + let root = + std::env::temp_dir().join(format!("ull-agent-events-{tag}-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&root); + std::fs::create_dir_all(root.join("game")).expect("建临时根"); + root + } + + /// 抓得住：新根解析出的路径**正好**是写入侧落盘的那一个（`<根>/game/.jsonl`）。 + /// 抓不住：旧根回落（下一条用例单独守）与事件内容解析（`ports::session` 的用例守）。 + #[test] + fn event_path_matches_what_the_writer_wrote() { + let root = temp_root("primary"); + let log_path = session_index::log_path_for(SID); + let written = session_index::event_file(&root, &log_path); + std::fs::write(&written, "{\"seq\":0}\n").expect("写事件流"); + + let source = SessionSource::new(root.clone()); + let resolved = source.event_path(&entry(&log_path)); + + assert_eq!(resolved, root.join("game").join(format!("{SID}.jsonl"))); + assert!( + resolved.is_file(), + "解析出的路径应真的是写入侧那份：{resolved:?}" + ); + + let _ = std::fs::remove_dir_all(&root); + } + + /// 文件暂时不在时，返回的「该去哪找」也必须是生产形状，不能多一层 `game/`。 + #[test] + fn missing_event_file_still_points_at_the_production_shape() { + let root = temp_root("missing"); + let log_path = session_index::log_path_for(SID); + + let source = SessionSource::new(root.clone()); + let resolved = source.event_path(&entry(&log_path)); + + assert_eq!(resolved, session_index::event_file(&root, &log_path)); + assert_eq!(resolved, root.join("game").join(format!("{SID}.jsonl"))); + + let _ = std::fs::remove_dir_all(&root); + } + + /// 旧根（`data/agent/sessions`，M188 前的生产落点）里的存量会话仍要读得回来。 + #[test] + fn legacy_root_fallback_uses_the_same_resolution() { + let primary = temp_root("legacy-primary"); + let legacy = temp_root("legacy-old"); + let log_path = session_index::log_path_for(SID); + let legacy_file = session_index::event_file(&legacy, &log_path); + std::fs::create_dir_all(legacy_file.parent().expect("父目录")).expect("建 game/"); + std::fs::write(&legacy_file, "{\"seq\":0}\n").expect("写旧根事件流"); + + let source = SessionSource::new(primary.clone()).with_legacy(legacy.clone()); + let resolved = source.event_path(&entry(&log_path)); + + assert_eq!(resolved, legacy_file); + assert!( + resolved.is_file(), + "旧根里的存量会话应读得回来：{resolved:?}" + ); + + let _ = std::fs::remove_dir_all(&primary); + let _ = std::fs::remove_dir_all(&legacy); + } +} 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 { + 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> { + let profiles = + read_profiles(&self.layout).map_err(|error| format!("读实例清单失败：{error}"))?; + let mut out: Vec = 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> { + 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 { + 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 = 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 { + 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::().ok()?, { + let padded = format!("{frac:0<3}"); + padded.get(..3)?.parse::().ok()? + }), + None => (seconds_text.parse::().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..719a845 --- /dev/null +++ b/crates/cli/src/commands/agent/ports/mod.rs @@ -0,0 +1,62 @@ +//! 端口装配：把 `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()).with_legacy(ctx.legacy_sessions_root()), + ), + diagnose: Arc::new( + CoreDiagnose::new(ctx.sessions_root()).with_legacy(ctx.legacy_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..3259475 --- /dev/null +++ b/crates/cli/src/commands/agent/ports/session.rs @@ -0,0 +1,213 @@ +//! 会话端口：索引 → `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/logs`（M188 起；`LauncherConfig` 在其下建 `game/`）。 + #[must_use] + pub fn new(root: impl Into) -> Self { + Self { + source: SessionSource::new(root), + } + } + + /// 再挂一个只读兼容的旧根（`<数据根>/.ULL/data/agent/sessions`，M188）。 + #[must_use] + pub fn with_legacy(mut self, legacy: impl Into) -> Self { + self.source = self.source.with_legacy(legacy); + self + } +} + +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> { + 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 { + let entry = self.source.find(session_id)?; + let raw = self.source.events(&entry)?; + let events: Vec = 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; + use unlucky_core::launch::session_index; + + /// 生产写入侧真会写出的形状（M212/D2）：`log_path` 相对**会话根**，事件流真落点 + /// `<根>/game/.jsonl`。夹具以前写裸文件名、把事件流也放在 `game/` 下， + /// 与生产只差一层 `game/` —— 正是这一层让「读取侧多 join 一层」永远测不出来。 + fn seed_session(root: &Path) { + let log_path = session_index::log_path_for("20261029T124501-9f3c2a"); + let index = session_index::index_path(root); + std::fs::create_dir_all(index.parent().expect("索引父目录")).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": log_path.clone(), + "crash_found": true, + "diagnosis_top": "integrity.forge_missing_library" + }); + std::fs::write(index, 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::(); + std::fs::write(session_index::event_file(root, &log_path), 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 = ""; + +/// 把 `core::setting` 包成 agent 的 [`SettingPort`]。 +#[derive(Debug, Clone)] +pub struct CoreSetting { + /// 解析后的数据根那份 `launcher.json`（非数据根键的落点）。 + path: PathBuf, + /// 便携目录那份 `launcher.json`（数据根键的落点）；与 `path` 重合或拿不到 + /// exe 目录时为 `None`。 + core_path: Option, +} + +impl CoreSetting { + /// 只指向数据根那份 `<数据根>/.ULL/config/launcher.json`（两份落点重合时够用）。 + #[must_use] + pub fn new(path: impl Into) -> Self { + Self::split(path, None) + } + + /// 数据根那份 + 便携目录那份（`Ctx::portable_launcher_config`，与数据根解析同源）。 + /// + /// 两份路径重合（便携模式）时只留一份，免得同一个文件被加载两次。 + #[must_use] + pub fn split(path: impl Into, core_path: Option) -> 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 { + 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 { + 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 { + 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 = 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/probe.rs b/crates/cli/src/commands/agent/probe.rs new file mode 100644 index 0000000..40c1bff --- /dev/null +++ b/crates/cli/src/commands/agent/probe.rs @@ -0,0 +1,361 @@ +//! 「测试连接」（M174）：拿 `config/launcher.json` 里的 AI 四项，走**现有 provider 实现** +//! （[`RigProvider`]）发一次最小请求，并把失败分成四类。 +//! +//! ## 分类从哪来（r1 复审 P2-5 之后） +//! +//! **不在本模块猜文本**：分类由 `unlucky_agent::brain::rig::map_error` 从 rig 0.45 的结构化 +//! 报告（`ErrorReport` 的 `kind` / `http_status` / `code`）翻译成 +//! [`ProviderFailure`]，本模块只做「枚举 → 界面结论」的映射： +//! +//! | [`ProviderFailure`] | 本模块产出 | +//! |---|---| +//! | `Auth`（401/403） | [`ProbeOutcome::Auth`] | +//! | `ModelNotFound`（404 / `model_not_found`） | [`ProbeOutcome::ModelNotFound`] | +//! | `Unreachable`（传输层：连接被拒 / DNS / TLS） | [`ProbeOutcome::Unreachable`] | +//! | `Timeout`（8 秒时限 / 传输层超时） | [`ProbeOutcome::Timeout`] | +//! | `NotConfigured`（没发请求） | [`ProbeOutcome::NotConfigured`] | +//! | `Other`（解析 / 5xx / 未知） | [`ProbeOutcome::Failed`] | +//! +//! ## 三条硬纪律 +//! +//! 1. **配置不完整时一个请求都不发**：[`ProbeOutcome::NotConfigured`] 在造 provider **之前**返回， +//! 连工厂都不会被调用（守卫②：假 provider 的构造计数必须是 0）。 +//! 2. **密钥永不外流**：`detail` 出本模块前先过 [`unlucky_agent::redact::redact_text`]，再把 +//! **本次的密钥原文**替换成 [`MASK`]——即使服务端把 key 回显在错误体里，界面上也看不到它。 +//! [`AiSettings`] 的 `Debug` 是手写的（掩码），[`ProbeOutcome`] 里没有密钥字段。 +//! 3. **每次现读文件**：[`probe_file`] 读的是「现在这一份」，所以设置页保存完再测，测的就是刚 +//! 存下的 `ai.base_url`（不是启动时缓存的旧值）。 +//! +//! 失败结论**一律带上被请求的 target**（r1 复审 P2-1）：只说「鉴权失败」而不说「对哪个端点、 +//! 哪个模型」，用户改完 key 也没法确认自己改的是不是那一份配置。 + +use std::path::Path; +use std::time::Duration; + +use unlucky_agent::brain::provider::{ + ProviderConfig, ProviderError, ProviderFailure, ProviderKind, +}; +use unlucky_agent::brain::rig::RigProvider; +use unlucky_agent::brain::{ChatMessage, ChatRequest, NoopObserver, ProviderFactory}; +use unlucky_agent::redact::{redact_text, MASK}; +use unlucky_core::setting::keys::launcher_schema; +use unlucky_core::setting::store::SettingStore; + +/// 一次「测试连接」的默认时限。 +/// +/// 8 秒：够一个跨洋 HTTPS 往返 + 服务端首 token；再长用户会以为按钮没反应。 +pub const DEFAULT_TIMEOUT: Duration = Duration::from_secs(8); + +/// 探测请求只发这一句：够触发一次真实补全，又不烧 token。 +const PING: &str = "ping"; + +/// 从设置文件读出来的 AI 四项（快照）。 +/// +/// `api_key` 在这里是**明文**（要用它发请求），所以 `Debug` 手写成掩码。 +#[derive(Clone, PartialEq, Eq)] +pub struct AiSettings { + /// `ai.enabled` + pub enabled: bool, + /// `ai.provider`（设置词表：`openai_compatible` / `anthropic` / `ollama` / `disabled`） + pub provider: String, + /// `ai.base_url`（空 = 用该形态的默认端点） + pub base_url: String, + /// `ai.model` + pub model: String, + /// `ai.api_key`（空/缺 = 没配置） + pub api_key: Option, +} + +impl std::fmt::Debug for AiSettings { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.debug_struct("AiSettings") + .field("enabled", &self.enabled) + .field("provider", &self.provider) + .field("base_url", &self.base_url) + .field("model", &self.model) + .field("api_key", &self.api_key.as_deref().map(|_| MASK)) + .finish() + } +} + +/// 缺哪一项配置（`NotConfigured` 的载荷：界面上要说清楚「差什么」）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Missing { + /// `ai.enabled=false` 或 `ai.provider=disabled` + Disabled, + /// `ai.provider` 是空/未知值 + Provider, + /// 该形态需要端点，但 `ai.base_url` 是空的 + BaseUrl, + /// `ai.model` 是空的 + Model, + /// 该形态（Anthropic）必须有密钥，但 `ai.api_key` 是空的 + ApiKey, +} + +impl Missing { + /// 稳定名（CLI 输出 / 日志 / 测试断言用；界面走 i18n）。 + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::Disabled => "disabled", + Self::Provider => "provider", + Self::BaseUrl => "base_url", + Self::Model => "model", + Self::ApiKey => "api_key", + } + } +} + +/// 被请求的那一份配置（端点 + 模型）：失败结论也要带它，用户才知道「改的是不是这一份」。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Target { + /// 实际请求的端点（`resolved_base_url`）。 + pub base_url: String, + /// 实际请求的模型名。 + pub model: String, +} + +/// 一次探测的结论（**不含密钥**；`detail` 已脱敏，可直接上屏/进日志）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum ProbeOutcome { + /// 配置不完整：**没有发出任何请求**（因此也没有 target）。 + NotConfigured { + /// 缺的是哪一项。 + missing: Missing, + }, + /// 通了（拿到一次真实补全的回复）。 + Passed { + /// 实际请求的目标。 + target: Target, + }, + /// 鉴权失败（401 / 403）。 + Auth { + /// 实际请求的目标。 + target: Target, + /// 脱敏后的原因。 + detail: String, + }, + /// 模型不存在（404 / `model_not_found`）。 + ModelNotFound { + /// 实际请求的目标。 + target: Target, + /// 脱敏后的原因。 + detail: String, + }, + /// 端点不可达（连接被拒 / DNS / TLS）。 + Unreachable { + /// 实际请求的目标。 + target: Target, + /// 脱敏后的原因。 + detail: String, + }, + /// 超时。 + Timeout { + /// 实际请求的目标。 + target: Target, + /// 脱敏后的原因（含时限）。 + detail: String, + }, + /// 其它（协议 / 解析 / 5xx）：不硬塞进上面四类。 + Failed { + /// 实际请求的目标。 + target: Target, + /// 脱敏后的原因。 + detail: String, + }, +} + +impl ProbeOutcome { + /// 是否「通」。 + #[must_use] + pub fn is_pass(&self) -> bool { + matches!(self, Self::Passed { .. }) + } + + /// 稳定名（`passed` / `auth` / `model_not_found` / `unreachable` / `timeout` / + /// `not_configured` / `failed`）。 + #[must_use] + pub const fn kind(&self) -> &'static str { + match self { + Self::NotConfigured { .. } => "not_configured", + Self::Passed { .. } => "passed", + Self::Auth { .. } => "auth", + Self::ModelNotFound { .. } => "model_not_found", + Self::Unreachable { .. } => "unreachable", + Self::Timeout { .. } => "timeout", + Self::Failed { .. } => "failed", + } + } + + /// 这条结论是关于哪个端点/模型的（`NotConfigured` 没有）。 + #[must_use] + pub fn target(&self) -> Option<&Target> { + match self { + Self::NotConfigured { .. } => None, + Self::Passed { target } + | Self::Auth { target, .. } + | Self::ModelNotFound { target, .. } + | Self::Unreachable { target, .. } + | Self::Timeout { target, .. } + | Self::Failed { target, .. } => Some(target), + } + } +} + +impl AiSettings { + /// 从设置文件读四项（文件缺失/坏掉时给「全默认」= 未配置，不报错）。 + #[must_use] + pub fn load(path: &Path) -> Self { + let store = SettingStore::load(path, launcher_schema()); + let doc = store.doc(); + let text = |key: &str| doc.effective_str(key).unwrap_or_default().to_string(); + let api_key = doc + .effective_str("ai.api_key") + .map(str::trim) + .filter(|value| !value.is_empty()) + .map(str::to_string); + Self { + enabled: doc.effective_bool("ai.enabled").unwrap_or(true), + provider: text("ai.provider"), + base_url: text("ai.base_url"), + model: text("ai.model"), + api_key, + } + } + + /// 四项 → [`ProviderConfig`]；缺项时给出**具体缺哪一项**（不发请求）。 + /// + /// # Errors + /// 禁用、端点/模型/密钥缺失或 `ai.provider` 不是已知取值时返回 [`Missing`]。 + pub fn to_config(&self) -> Result { + if !self.enabled { + return Err(Missing::Disabled); + } + let Some(kind) = ProviderKind::from_setting(&self.provider) else { + return Err(Missing::Provider); + }; + if kind == ProviderKind::Disabled { + return Err(Missing::Disabled); + } + let base_url = self.base_url.trim(); + if base_url.is_empty() && kind.default_base_url().is_empty() { + return Err(Missing::BaseUrl); + } + let model = self.model.trim(); + if model.is_empty() { + return Err(Missing::Model); + } + if kind.requires_api_key() && self.api_key.is_none() { + return Err(Missing::ApiKey); + } + let mut config = match kind { + ProviderKind::OpenAiCompatible => ProviderConfig::openai_compatible(base_url, model), + ProviderKind::Anthropic => ProviderConfig::anthropic(model), + ProviderKind::Ollama => ProviderConfig::ollama(model), + // 上面已经拦掉；留着是因为穷尽匹配比 `_ =>` 值钱（加形态时编译器会提醒）。 + ProviderKind::Disabled => return Err(Missing::Disabled), + }; + if !base_url.is_empty() { + config.base_url = base_url.to_string(); + } + if let Some(key) = self.api_key.as_deref() { + config = config.with_api_key(key); + } + Ok(config) + } + + /// 本次的密钥（脱敏用；空值给 `None`）。 + fn secret(&self) -> Option<&str> { + self.api_key.as_deref().filter(|key| !key.trim().is_empty()) + } +} + +/// 读设置文件并测一次连接（真 provider、真网络、带时限）。 +#[must_use] +pub fn probe_file(path: &Path, timeout: Duration) -> ProbeOutcome { + probe_with(&RigProvider::factory(), &AiSettings::load(path), timeout) +} + +/// 测一次连接（工厂可注入：单测用计数假件证明「未配置时一次都没发」）。 +/// +/// # Panics +/// +/// 在已有 tokio 运行时上下文里调用会 panic（`core::download::blocking::block_on` 的既有约定）； +/// 本函数的两个调用方（GUI 的 thread-pool 任务、CLI）都不在运行时里。 +#[must_use] +pub fn probe_with( + factory: &ProviderFactory, + settings: &AiSettings, + timeout: Duration, +) -> ProbeOutcome { + let config = match settings.to_config() { + Ok(config) => config, + Err(missing) => return ProbeOutcome::NotConfigured { missing }, + }; + let target = Target { + base_url: config.resolved_base_url().to_string(), + model: config.model.clone(), + }; + + let provider = match factory(&config) { + Ok(provider) => provider, + Err(error) => return outcome_from_error(&error, settings, target), + }; + + let request = ChatRequest { + model: target.model.clone(), + messages: vec![ChatMessage::user(PING)], + tools: Vec::new(), + temperature: Some(0.0), + max_tokens: Some(16), + }; + + unlucky_core::download::blocking::block_on(async move { + match tokio::time::timeout(timeout, provider.complete(&request, &NoopObserver)).await { + Ok(Ok(_reply)) => ProbeOutcome::Passed { target }, + Ok(Err(error)) => outcome_from_error(&error, settings, target), + Err(_) => ProbeOutcome::Timeout { + target, + detail: format!("{} s", timeout.as_secs_f32()), + }, + } + }) +} + +/// provider 错误 → 分类结论（`detail` 先脱敏再出门；分类来自 [`ProviderError::kind`]）。 +fn outcome_from_error( + error: &ProviderError, + settings: &AiSettings, + target: Target, +) -> ProbeOutcome { + let detail = scrub(&error.to_string(), settings.secret()); + match error.kind() { + ProviderFailure::Auth => ProbeOutcome::Auth { target, detail }, + ProviderFailure::ModelNotFound => ProbeOutcome::ModelNotFound { target, detail }, + ProviderFailure::Unreachable => ProbeOutcome::Unreachable { target, detail }, + ProviderFailure::Timeout => ProbeOutcome::Timeout { target, detail }, + // 工厂阶段就报「配置不完整」（`validate()` 拒绝）：仍然没发请求，但缺项已经在上游 + // `to_config()` 拦过，这里退到 `Provider` 这个具名缺项。 + ProviderFailure::NotConfigured => ProbeOutcome::NotConfigured { + missing: Missing::Provider, + }, + ProviderFailure::Other => ProbeOutcome::Failed { target, detail }, + } +} + +/// 文本脱敏：先走 agent 的通用脱敏（主目录 / Bearer），再把本次密钥原文换成 [`MASK`]。 +/// +/// 第二道是必须的：`redact_text` 认不出「某个服务端回显的自定义密钥」，只有本模块知道本次的 +/// 密钥原文。长度上限 400：错误体可能是整页 HTML，界面上放不下，日志里也没必要。 +pub fn scrub(text: &str, secret: Option<&str>) -> String { + let mut out = redact_text(text); + if let Some(secret) = secret.filter(|value| !value.trim().is_empty()) { + out = out.replace(secret, MASK); + } + out.chars().take(400).collect() +} + +#[cfg(test)] +#[path = "probe/tests.rs"] +mod tests; diff --git a/crates/cli/src/commands/agent/probe/tests.rs b/crates/cli/src/commands/agent/probe/tests.rs new file mode 100644 index 0000000..0c92430 --- /dev/null +++ b/crates/cli/src/commands/agent/probe/tests.rs @@ -0,0 +1,328 @@ +//! 「测试连接」的守卫（M174）。四类失败**各有一条真 TCP 假服务器**用例——不是拿字符串假装的。 +//! +//! | 用例 | 守什么 | 变异（改成什么会红） | +//! |---|---|---| +//! | `auth_failure_is_classified_as_auth` | 401 → 鉴权失败 | `map_error` 的 401 分支改成 `Other` | +//! | `missing_model_is_model_not_found` | 404 → 模型不存在 | 把 404 归进 auth | +//! | `closed_port_is_unreachable` | 连不上 → 端点不可达 | 把 `ErrorKind::Http` 归到 `Other` | +//! | `silent_server_times_out` | 不响应 → 超时，且在**本次预算**到点收手 | 去掉 `tokio::time::timeout`（那就得等假服务器睡满 5s） | +//! | `success_is_one_real_completion` | 200 + SSE → 通过 | 把 `Ok(Ok(_))` 当成失败 | +//! | `the_request_carries_the_configured_model` | **请求体里的 `model` 就是配置那个** | `probe_with` 里把 model 写死成别的名字 | +//! | 每条失败用例都断言 `target` | 失败结论带「对哪个端点/模型」 | `outcome_from_error` 丢掉 target（r1 复审 P2-1） | + +use std::io::{Read, Write}; +use std::net::{TcpListener, TcpStream}; +use std::sync::{Arc, Mutex}; +use std::time::Duration; + +use unlucky_agent::brain::rig::RigProvider; + +use super::{probe_with, AiSettings, ProbeOutcome}; + +/// 假服务器的行为。 +enum Behaviour { + /// 立刻回这一份（状态行 + Content-Type + body）。 + Reply(&'static str, &'static str, &'static str), + /// 收下请求但**永远不回**（超时用例）。 + Silent, +} + +/// 一条收到的请求：头 + 正文（P2-3：正文里才有 `model`）。 +#[derive(Clone)] +struct Hit { + head: String, + body: String, +} + +/// 一个只服务 127.0.0.1 的假 HTTP 服务器：记下每一份请求，按 `behaviour` 回。 +struct Server { + port: u16, + hits: Arc>>, +} + +impl Server { + fn start(behaviour: Behaviour) -> Self { + let listener = TcpListener::bind("127.0.0.1:0").expect("绑本地端口"); + let port = listener.local_addr().expect("本地地址").port(); + let hits = Arc::new(Mutex::new(Vec::new())); + let sink = Arc::clone(&hits); + std::thread::spawn(move || { + for stream in listener.incoming() { + let Ok(stream) = stream else { continue }; + handle(stream, &behaviour, &sink); + } + }); + Self { port, hits } + } + + fn base_url(&self) -> String { + format!("http://127.0.0.1:{}/v1", self.port) + } + + fn hits(&self) -> Vec { + self.hits.lock().expect("锁").clone() + } +} + +fn handle(mut stream: TcpStream, behaviour: &Behaviour, sink: &Arc>>) { + let mut buffer = [0_u8; 8192]; + let mut raw = Vec::new(); + // 先读头，再按 `Content-Length` 把正文读全（P2-3：只读头就断言不到 `model`）。 + let head_end = loop { + if let Some(at) = raw.windows(4).position(|w| w == b"\r\n\r\n") { + break at + 4; + } + match stream.read(&mut buffer) { + Ok(0) => break raw.len(), + Ok(n) => raw.extend_from_slice(&buffer[..n]), + Err(_) => return, + } + }; + let head = String::from_utf8_lossy(&raw[..head_end]).to_string(); + let length = head + .lines() + .find_map(|line| { + let (name, value) = line.split_once(':')?; + name.eq_ignore_ascii_case("content-length") + .then(|| value.trim().parse::().ok()) + .flatten() + }) + .unwrap_or(0); + while raw.len() < head_end + length { + match stream.read(&mut buffer) { + Ok(0) => break, + Ok(n) => raw.extend_from_slice(&buffer[..n]), + Err(_) => break, + } + } + let body = + String::from_utf8_lossy(&raw[head_end..raw.len().min(head_end + length)]).to_string(); + sink.lock().expect("锁").push(Hit { head, body }); + + match behaviour { + Behaviour::Silent => { + // 拖住这条连接（客户端会先超时）：比客户端时限长得多。 + std::thread::sleep(Duration::from_secs(5)); + } + Behaviour::Reply(status, content_type, body) => { + let response = format!( + "{status}\r\nContent-Type: {content_type}\r\nContent-Length: {len}\r\nConnection: close\r\n\r\n{body}", + len = body.len() + ); + let _ = stream.write_all(response.as_bytes()); + let _ = stream.flush(); + } + } +} + +fn settings(base_url: &str, model: &str) -> AiSettings { + AiSettings { + enabled: true, + provider: "openai_compatible".to_string(), + base_url: base_url.to_string(), + model: model.to_string(), + api_key: Some("sk-test-not-a-real-key".to_string()), + } +} + +const AUTH_BODY: &str = r#"{"error":{"message":"Incorrect API key provided","type":"invalid_request_error","code":"invalid_api_key"}}"#; +const MISSING_MODEL_BODY: &str = + r#"{"error":{"message":"model_not_found: no such model gpt-nope","code":"model_not_found"}}"#; + +/// 一份最小但合法的 OpenAI 流式回复（rig 走 `model.stream(..)`，要 SSE 不是整包 JSON）。 +const SSE_BODY: &str = concat!( + "data: {\"id\":\"chatcmpl-1\",\"object\":\"chat.completion.chunk\",\"created\":1700000000,\"model\":\"gpt-test\",\"choices\":[{\"index\":0,\"delta\":{\"role\":\"assistant\",\"content\":\"pong\"},\"finish_reason\":null}]}\n\n", + "data: {\"id\":\"chatcmpl-1\",\"object\":\"chat.completion.chunk\",\"created\":1700000000,\"model\":\"gpt-test\",\"choices\":[{\"index\":0,\"delta\":{},\"finish_reason\":\"stop\"}],\"usage\":{\"prompt_tokens\":3,\"completion_tokens\":1,\"total_tokens\":4}}\n\n", + "data: [DONE]\n\n" +); + +#[test] +fn auth_failure_is_classified_as_auth() { + let server = Server::start(Behaviour::Reply( + "HTTP/1.1 401 Unauthorized", + "application/json", + AUTH_BODY, + )); + let outcome = probe_with( + &RigProvider::factory(), + &settings(&server.base_url(), "gpt-test"), + Duration::from_secs(5), + ); + let ProbeOutcome::Auth { target, detail } = &outcome else { + panic!("401 必须归到鉴权失败，实际 {outcome:?}"); + }; + assert!(!detail.is_empty()); + // P2-1：失败结论必须说清「对哪个端点 / 哪个模型」。 + assert_eq!(target.base_url, server.base_url()); + assert_eq!(target.model, "gpt-test"); + // 请求确实发出去了（否则「鉴权失败」是凭空说的）。 + assert_eq!(server.hits().len(), 1, "鉴权失败之前必须真的连上过"); +} + +#[test] +fn missing_model_is_model_not_found() { + let server = Server::start(Behaviour::Reply( + "HTTP/1.1 404 Not Found", + "application/json", + MISSING_MODEL_BODY, + )); + let outcome = probe_with( + &RigProvider::factory(), + &settings(&server.base_url(), "gpt-nope"), + Duration::from_secs(5), + ); + assert_eq!( + outcome.kind(), + "model_not_found", + "404 必须归到模型不存在，实际 {outcome:?}" + ); + assert_eq!(outcome.target().map(|t| t.model.as_str()), Some("gpt-nope")); +} + +#[test] +fn closed_port_is_unreachable() { + // 绑一个端口再放掉：这个端口上没人监听 = 连接被拒。 + let port = { + let listener = TcpListener::bind("127.0.0.1:0").expect("绑端口"); + listener.local_addr().expect("地址").port() + }; + let base_url = format!("http://127.0.0.1:{port}/v1"); + let outcome = probe_with( + &RigProvider::factory(), + &settings(&base_url, "gpt-test"), + Duration::from_secs(5), + ); + assert_eq!( + outcome.kind(), + "unreachable", + "没人监听的端口必须归到端点不可达，实际 {outcome:?}" + ); + assert_eq!( + outcome.target().map(|t| t.base_url.as_str()), + Some(base_url.as_str()) + ); +} + +/// 超时用例的预算：跟产品默认时限（`DEFAULT_TIMEOUT` = 8s）同一个量级，取 1/20 只是为了让整个 +/// 测试套不必等 8 秒。判据只依赖「预算生效时远早于假服务器沉默的 5 秒」，不依赖这个绝对值。 +const TIMEOUT_BUDGET: Duration = Duration::from_millis(400); + +/// 允许的调度噪声：一次本地回环往返 + 建 tokio 运行时是毫秒级，1 秒是给繁忙机器的余量；它必须 +/// **远小于**「预算没生效」的代价（假服务器要睡 5s 才收手），否则两种情形区分不开。 +const TIMEOUT_SLACK: Duration = Duration::from_secs(1); + +/// 不回应 ⇒ 超时，且在**本次预算**到点时就收手（不是等对面 5 秒沉默、也不是等别处的默认时限）。 +/// +/// 三层判据各管一件事，别混： +/// +/// 1. **走了哪条分支**：`kind == "timeout"`。没被本模块预算截住的「不回应」落到的是传输层错误 +/// ——实测：摘掉 `tokio::time::timeout` ⇒ 假服务器睡满 5s 后关连接，结论是 `unreachable`， +/// 所以这一条先把「根本没走到超时分支」挡在外面。 +/// 2. **是本次预算那条分支**：`detail` 里的时限就是传进去的预算（Timeout 分支把 `timeout` 原样 +/// 写进 detail）。它证明「结论由这条预算分支产出」，**不**证明「计时器用的就是这个值」：分支 +/// 里把计时值换掉、detail 照抄参数，本条抓不住——那是下一条的活。 +/// 3. **墙钟**：`elapsed < 预算 + SLACK`，抓的正是上一条抓不住的形态（「分支对、但等的不是这个 +/// 预算」）。实测：把计时值硬编码成 3s ⇒ 本断言红（3.006s > 1.4s）。 +/// +/// 抓得住：「预算没生效 / 生效的不是这个预算」——那种情况要等假服务器睡满 5s 或等 3s 之类的 +/// 别处时限，远超 `预算 + SLACK`。 +/// 抓不住：预算到底是 400ms 还是 1.2s（都落在 SLACK 里），也不量定时器精度；机器再忙只吃掉 +/// SLACK 的余量，不吃预算本身。 +#[test] +fn silent_server_times_out() { + // 假服务器收下请求后睡 5s（`Behaviour::Silent`）：这就是「预算没生效」时本用例会等到的墙钟。 + let server = Server::start(Behaviour::Silent); + let started = std::time::Instant::now(); + let outcome = probe_with( + &RigProvider::factory(), + &settings(&server.base_url(), "gpt-test"), + TIMEOUT_BUDGET, + ); + let elapsed = started.elapsed(); + + assert_eq!( + outcome.kind(), + "timeout", + "不回应的端点必须归到超时，实际 {outcome:?}" + ); + let ProbeOutcome::Timeout { detail, .. } = &outcome else { + unreachable!("上一行已经断言 kind 是 timeout") + }; + assert!( + detail.contains(&TIMEOUT_BUDGET.as_secs_f32().to_string()), + "超时结论里的时限不是本次预算（{TIMEOUT_BUDGET:?}）：{detail}" + ); + assert_eq!( + server.hits().len(), + 1, + "超时之前必须真的把一次请求发给了假服务器（否则「超时」可能只是没连上）" + ); + assert!( + elapsed < TIMEOUT_BUDGET + TIMEOUT_SLACK, + "预算没生效或收手太晚：预算 {TIMEOUT_BUDGET:?}，实际 {elapsed:?}；假服务器会沉默 5s，\ + 超过 {:?} 就说明等的不是这个预算", + TIMEOUT_BUDGET + TIMEOUT_SLACK + ); +} + +#[test] +fn success_is_one_real_completion() { + let server = Server::start(Behaviour::Reply( + "HTTP/1.1 200 OK", + "text/event-stream", + SSE_BODY, + )); + let outcome = probe_with( + &RigProvider::factory(), + &settings(&server.base_url(), "gpt-test"), + Duration::from_secs(5), + ); + match &outcome { + ProbeOutcome::Passed { target } => { + assert_eq!(target.base_url, server.base_url()); + assert_eq!(target.model, "gpt-test"); + } + other => panic!("200 + 合法 SSE 必须算通过，实际 {other:?}"), + } +} + +/// **P2-3**：请求体里的 `model` 必须是用户配置的那个（不是写死的）。 +/// +/// 变异：把 `probe_with` 的 `model: target.model.clone()` 改成 `"gpt-4o".to_string()` ⇒ 本用例 +/// 断言 `\"model\":\"gpt-test\"` 失败。这是「配置里的模型真的上了线」唯一可信的证据：只看 +/// 状态码通过并不能证明服务端收到的是哪个模型。 +#[test] +fn the_request_carries_the_configured_model() { + let server = Server::start(Behaviour::Reply( + "HTTP/1.1 200 OK", + "text/event-stream", + SSE_BODY, + )); + let outcome = probe_with( + &RigProvider::factory(), + &settings(&server.base_url(), "gpt-test"), + Duration::from_secs(5), + ); + assert!(outcome.is_pass(), "前提：这一轮应当通过，实际 {outcome:?}"); + + let hits = server.hits(); + assert_eq!(hits.len(), 1, "应当恰好一次请求"); + let hit = &hits[0]; + assert!( + hit.head.starts_with("POST /v1/chat/completions"), + "请求行不对：{}", + hit.head.lines().next().unwrap_or("") + ); + assert!( + !hit.body.is_empty(), + "没有读到请求正文（夹具没按 Content-Length 读 body？）" + ); + assert!( + hit.body.contains("\"model\":\"gpt-test\""), + "请求正文里的 model 不是配置里的那个：{}", + hit.body + ); +} + +#[path = "tests_guards.rs"] +mod guards; diff --git a/crates/cli/src/commands/agent/probe/tests_guards.rs b/crates/cli/src/commands/agent/probe/tests_guards.rs new file mode 100644 index 0000000..5753c47 --- /dev/null +++ b/crates/cli/src/commands/agent/probe/tests_guards.rs @@ -0,0 +1,290 @@ +//! 「测试连接」的**不发请求**那一半守卫（M174）：未配置不建 provider / 改完设置打新地址 / +//! 密钥不外流 / 文件读取。与 `probe/tests.rs` 的分工：那边起真 TCP 假服务器验四类失败， +//! 这边只验「什么时候不发」「发到哪」「发出去的东西里有什么」。 + +use std::path::PathBuf; +use std::sync::atomic::{AtomicUsize, Ordering}; +use std::sync::Arc; +use std::time::Duration; + +use unlucky_agent::brain::provider::ProviderConfig; +use unlucky_agent::brain::{ + ChatProvider, ChatRequest, DeltaObserver, ProviderError, ProviderFuture, +}; +use unlucky_agent::redact::MASK; + +use super::{settings, Behaviour, Server, AUTH_BODY}; +use crate::commands::agent::probe::{probe_file, probe_with, AiSettings, Missing, ProbeOutcome}; + +#[test] +fn incomplete_config_never_builds_a_provider() { + struct Counter; + impl ChatProvider for Counter { + fn config(&self) -> &ProviderConfig { + unreachable!("不该被造出来") + } + fn complete<'a>( + &'a self, + _request: &'a ChatRequest, + _observer: &'a dyn DeltaObserver, + ) -> ProviderFuture<'a> { + unreachable!("不该被造出来") + } + } + + let builds = Arc::new(AtomicUsize::new(0)); + let counter = Arc::clone(&builds); + let factory: unlucky_agent::brain::ProviderFactory = + Arc::new(move |_config: &ProviderConfig| { + counter.fetch_add(1, Ordering::SeqCst); + Ok(Arc::new(Counter) as Arc) + }); + + // 四种「不完整」：禁用 / 缺端点 / 缺模型 / 缺密钥（Anthropic） + let mut cases = vec![ + ( + AiSettings { + enabled: false, + ..settings("http://127.0.0.1:1/v1", "m") + }, + Missing::Disabled, + ), + ( + AiSettings { + base_url: String::new(), + ..settings("", "m") + }, + Missing::BaseUrl, + ), + ( + AiSettings { + model: String::new(), + ..settings("http://127.0.0.1:1/v1", "") + }, + Missing::Model, + ), + ( + AiSettings { + provider: "anthropic".to_string(), + base_url: String::new(), + api_key: None, + ..settings("", "claude-sonnet-4") + }, + Missing::ApiKey, + ), + ( + AiSettings { + provider: "openai-compatible".to_string(), + ..settings("http://127.0.0.1:1/v1", "m") + }, + Missing::Provider, + ), + ]; + // `..::settings(..)` 里那些字段会被逐个覆盖，这里只要求「不全的配置都能被拦下」。 + for (case, expected) in cases.drain(..) { + let outcome = probe_with(&factory, &case, Duration::from_millis(50)); + assert_eq!( + outcome, + ProbeOutcome::NotConfigured { missing: expected }, + "配置不全时必须返回 NotConfigured（{expected:?}），实际 {outcome:?}" + ); + } + assert_eq!( + builds.load(Ordering::SeqCst), + 0, + "未配置时一个 provider 都不许造（更不许发请求）" + ); +} + +/// 守卫：设置页保存完再测，请求打到的是**文件里现在那个** `ai.base_url`。 +#[test] +fn saved_base_url_is_the_address_actually_dialed() { + let old = Server::start(Behaviour::Reply( + "HTTP/1.1 401 Unauthorized", + "application/json", + AUTH_BODY, + )); + let new = Server::start(Behaviour::Reply( + "HTTP/1.1 401 Unauthorized", + "application/json", + AUTH_BODY, + )); + let path = temp_config("base-url"); + write_config( + &path, + &format!( + r#"{{"ai":{{"enabled":true,"provider":"openai_compatible","base_url":"{}","model":"gpt-test","api_key":"sk-saved"}}}}"#, + old.base_url() + ), + ); + + let first = probe_file(&path, Duration::from_secs(5)); + assert!(!first.is_pass(), "假服务器回 401，不该算通过"); + assert_eq!(old.hits().len(), 1, "第一次必须打到旧地址"); + + // 用户在设置页改了 base_url（同一份 schema、同一个文件）之后再测一次。 + write_config( + &path, + &format!( + r#"{{"ai":{{"enabled":true,"provider":"openai_compatible","base_url":"{}","model":"gpt-test","api_key":"sk-saved"}}}}"#, + new.base_url() + ), + ); + let second = probe_file(&path, Duration::from_secs(5)); + assert!(!second.is_pass()); + assert_eq!( + new.hits().len(), + 1, + "改完 base_url 之后请求必须打到新地址（读的是文件里现在那一份）" + ); + assert_eq!(old.hits().len(), 1, "旧地址不该再被打一次"); + let hit = &new.hits()[0]; + assert!( + hit.head.starts_with("POST /v1/chat/completions"), + "OpenAI 兼容形态请求的是 /v1/chat/completions，实际请求行：{}", + hit.head.lines().next().unwrap_or("") + ); + assert!( + hit.body.contains("\"model\":\"gpt-test\""), + "请求正文里的 model 不是配置里的那个：{}", + hit.body + ); + // P2-1：改完 base_url 之后，失败结论里说的也必须是**新**地址。 + assert_eq!( + second.target().map(|target| target.base_url.as_str()), + Some(new.base_url().as_str()) + ); +} + +/// 守卫①：密钥不得出现在 `ProbeOutcome` 的任何字段里，也不得出现在 `AiSettings` 的 `Debug` 里。 +/// +/// 这里让假服务器把**密钥原文回显**在 401 错误体里（最坏情况）：`detail` 必须是掩码。 +#[test] +fn key_never_leaks_into_outcome_or_debug() { + const SECRET: &str = "sk-live-LEAK-MARKER-9f3a"; + // 服务端把 key 原样回显（有些网关会这么干）。 + let body = r#"{"error":{"message":"Incorrect API key provided: sk-live-LEAK-MARKER-9f3a","code":"invalid_api_key"}}"#; + let server = Server::start(Behaviour::Reply( + "HTTP/1.1 401 Unauthorized", + "application/json", + body, + )); + let settings = AiSettings { + api_key: Some(SECRET.to_string()), + ..settings(&server.base_url(), "gpt-test") + }; + + let outcome = probe_with( + &unlucky_agent::brain::rig::RigProvider::factory(), + &settings, + Duration::from_secs(5), + ); + let printed = format!("{outcome:?}"); + assert!( + !printed.contains(SECRET), + "ProbeOutcome 里出现了密钥明文：{printed}" + ); + assert!( + printed.contains(MASK), + "被掩码后应当看得见掩码标记：{printed}" + ); + + let debug = format!("{settings:?}"); + assert!( + !debug.contains(SECRET), + "AiSettings 的 Debug 漏了密钥：{debug}" + ); + assert!( + debug.contains(MASK), + "AiSettings 的 Debug 应当显示掩码：{debug}" + ); +} + +#[test] +fn settings_load_reads_the_five_keys() { + let path = temp_config("load"); + write_config( + &path, + r#"{"ai":{"enabled":false,"provider":"ollama","base_url":"http://127.0.0.1:11434","model":"llama3","api_key":"sk-x"}}"#, + ); + let settings = AiSettings::load(&path); + assert!(!settings.enabled); + assert_eq!(settings.provider, "ollama"); + assert_eq!(settings.base_url, "http://127.0.0.1:11434"); + assert_eq!(settings.model, "llama3"); + assert_eq!(settings.api_key.as_deref(), Some("sk-x")); + + // 空的 api_key（null / 空串）读成 `None`，不是 `Some("")`。 + let empty = temp_config("empty-key"); + write_config( + &empty, + r#"{"ai":{"provider":"ollama","model":"llama3","api_key":""}}"#, + ); + assert_eq!(AiSettings::load(&empty).api_key, None); + // 文件不存在也不 panic（`effective_*` 给 schema 默认值 = 未配置，不是坏值）。 + let missing = temp_config("missing"); + let settings = AiSettings::load(&missing); + assert_eq!( + settings.provider, "openai_compatible", + "缺文件时是 schema 默认值" + ); + assert!(settings.model.is_empty()); + assert_eq!(settings.api_key, None); + assert_eq!(settings.to_config(), Err(Missing::BaseUrl)); +} + +// ------------------------------------------------------------------ 夹具 + +fn temp_config(label: &str) -> PathBuf { + let dir = std::env::temp_dir().join(format!( + "ull-probe-{label}-{}-{}", + std::process::id(), + line!() + )); + std::fs::create_dir_all(dir.join("config")).expect("临时目录"); + dir.join("config/launcher.json") +} + +fn write_config(path: &PathBuf, body: &str) { + std::fs::write(path, body).expect("写配置文件"); +} + +/// 工厂阶段的错误也按**结构化分类**走（r1 复审 P2-5 之后：这里不再看文本）。 +/// +/// 两条一起钉住： +/// 1. 工厂给的是 `classified(Auth, …)` ⇒ 结论就是 `auth`（分类信息不丢）； +/// 2. 工厂给的是 `ProviderError::new("401 bad key")`（**纯文本、没有分类**）⇒ 结论是 `failed`， +/// **不是** `auth`。第二条是 P2-5 的绊线：谁把「按 `"401"` 子串猜类别」加回来，这条立刻红。 +#[test] +fn factory_error_carries_the_structured_classification() { + let classified: unlucky_agent::brain::ProviderFactory = Arc::new(|_config: &ProviderConfig| { + Err(ProviderError::classified( + unlucky_agent::brain::ProviderFailure::Auth, + "401 Unauthorized", + )) + }); + let outcome = probe_with( + &classified, + &settings("http://127.0.0.1:1/v1", "gpt-test"), + Duration::from_millis(50), + ); + assert_eq!( + outcome.kind(), + "auth", + "工厂阶段的结构化分类不许丢：{outcome:?}" + ); + + // 纯文本错误（无分类）**不许**被猜成鉴权失败。 + let text_only: unlucky_agent::brain::ProviderFactory = + Arc::new(|_config: &ProviderConfig| Err(ProviderError::new("401 bad key"))); + let outcome = probe_with( + &text_only, + &settings("http://127.0.0.1:1/v1", "gpt-test"), + Duration::from_millis(50), + ); + assert_eq!( + outcome.kind(), + "failed", + "没有结构化分类的错误必须落在「其它」，不许按文本猜成 auth（P2-5）：{outcome:?}" + ); +} 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`（落盘 `/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 { + 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(®istry) + }; + + 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(future: F) -> Result +where + F: std::future::Future> + 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, + 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..f5ea6b5 --- /dev/null +++ b/crates/cli/src/commands/config.rs @@ -0,0 +1,375 @@ +//! `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` +//! （`/.ULL/config/launcher.json`）。这正是 `Ctx::resolve` 决定数据根时读的 +//! 同一份文件（落点由 `Ctx::setting_path_for` 给出），所以 `config get core.data_mode` +//! 展示的就是真正生效的值，`config set` 也真的影响下一次解析； +//! - 其余键 → 解析后的数据根（`/.ULL/config/launcher.json`）。 +//! +//! 之前两条路各看一份文件：`--data-dir` / standard 模式下「改了 `core.data_mode` 没反应、 +//! `config get` 还报另一份文件里的值」（finding `…-improve-ull-config-get-set-launcher-json`）。 +//! +//! 实例级配置（`config/instances/.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 = ""; + +mod prefs_migration; + +use prefs_migration::migrate_update_prefs; + +/// `ull config get [] [--show-secret]`。 +/// +/// # Errors +/// +/// 未知键、配置不可读时返回用户错误。 +pub fn get(ctx: &Ctx, key: Option<&str>, show_secret: bool) -> Result { + 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 { + // 先跑一次遗留偏好迁移（幂等；没有旧文件时只是一次 stat）。必须在 `load` **之前**： + // 迁移写的正是这份 `launcher.json`，先读后迁会让这一条输出还是旧值。 + let migration = migrate_update_prefs(ctx); + 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 mut 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())); + if let Some(note) = migration { + human.push(note.human); + if let Some(object) = data.as_object_mut() { + object.insert("migration".to_string(), note.data); + } + } + 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 { + let migration = migrate_update_prefs(ctx); + 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 = 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)); + if let Some(note) = &migration { + human.push(note.human.clone()); + } + for problem in &problems { + human.push(format!("问题：{problem}")); + } + if masked { + human.push("（敏感值已掩码；加 --show-secret 显示明文）".to_string()); + } + let mut data = 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(), + }, + }); + if let Some(note) = migration { + if let Some(object) = data.as_object_mut() { + object.insert("migration".to_string(), note.data); + } + } + Ok(Report::new(data, human)) +} + +/// `ull config set `。 +/// +/// 敏感键的**旧值回显要掩码**（新值是用户刚敲进来的，照常回显）。 +/// +/// # Errors +/// +/// 键不在 schema、值不合法、文件只读/不可读、写盘失败时返回用户错误。 +pub fn set(ctx: &Ctx, key: &str, raw: &str) -> Result { + // 同一份遗留偏好先迁进来：否则用户「set 一个、get 另一个」会看到两份真相。 + let migration = migrate_update_prefs(ctx); + 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 mut 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()), + ]; + if let Some(note) = migration { + human.push(note.human); + if let Some(object) = data.as_object_mut() { + object.insert("migration".to_string(), note.data); + } + } + human.extend(source_note(ctx, key)); + Ok(Report::new(data, human)) + } + SaveOutcome::Skipped(SkipReason::NotDirty) => { + let mut human = vec![format!("{key} 已经是该值，未写盘")]; + if let Some(note) = &migration { + human.push(note.human.clone()); + } + Ok(Report::new( + json!({ "key": key, "new": value, "saved": null }), + human, + )) + } + 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 { + 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 { + 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::(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 = 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/prefs_migration.rs b/crates/cli/src/commands/config/prefs_migration.rs new file mode 100644 index 0000000..220d636 --- /dev/null +++ b/crates/cli/src/commands/config/prefs_migration.rs @@ -0,0 +1,70 @@ +//! M159 的遗留更新偏好 → 主配置（`update.auto_check`）的迁移（M161）。 +//! +//! 从 `commands/config.rs` 拆出：那边贴着 400 行硬线，而这块是**独立的一件事** +//! （遗留文件的桥接），与 get/set 的排版逻辑无关。 + +use serde_json::{json, Value}; +use unlucky_core::setting::update_prefs::{self, Migration}; + +use crate::context::Ctx; + +/// M159 的遗留更新偏好 → 主配置的迁移结果（只在**有话说**时返回）。 +pub(super) struct PrefsNote { + /// 人读一行（`config get/set` 的人类可读输出里追加） + pub(super) human: String, + /// 同一件事的机器可读形状（`--json` 信封里追加） + pub(super) data: Value, +} + +/// 把 `<数据根>/cache/update/prefs.json` 迁进 `launcher.json`（M161）。 +/// +/// 为什么 `config` 这个**读命令**也会写盘：那份遗留文件对 CLI 本来就不可见——用户在手头没 GUI +/// 的机器上 `config get update.auto_check`，旧实现永远回默认 `true`，而他的开关可能是关的。 +/// 迁移是**幂等**的（源指纹闸门 + 旧文件改名 `.migrated`），有收据，且在写不进去时什么都不动 +/// （见 [`unlucky_core::setting::update_prefs`]）。没有旧文件时这里只是一次 `stat`。 +pub(super) fn migrate_update_prefs(ctx: &Ctx) -> Option { + let layout = ctx.layout(); + let paths = update_prefs::Targets { + launcher: &ctx.launcher_config(), + legacy: &layout.cache().join("update").join("prefs.json"), + receipt: &layout.config().join(update_prefs::RECEIPT_FILE), + }; + let now = std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .map(|elapsed| u64::try_from(elapsed.as_millis()).unwrap_or(u64::MAX)) + .unwrap_or(0); + let migration = update_prefs::migrate(paths, now); + let (human, detail) = match &migration { + Migration::Nothing => return None, + Migration::Migrated { auto_check, .. } => ( + format!( + "已把旧更新偏好迁入主配置：update.auto_check = {auto_check}（收据 {}）", + paths.receipt.display() + ), + format!("update.auto_check = {auto_check} 已迁移"), + ), + Migration::NewValueWins { auto_check, .. } => ( + format!( + "旧更新偏好文件已退役（主配置里已有 update.auto_check = {auto_check}，新值胜出；收据 {}）", + paths.receipt.display() + ), + "旧文件已退役，主配置的值未改动".to_string(), + ), + Migration::Unreadable { path, reason } => ( + format!("旧更新偏好读不出来（{}）：{reason}", path.display()), + "旧文件坏，未迁移".to_string(), + ), + Migration::Refused { reason } => ( + format!("旧更新偏好未迁移：{reason}"), + "主配置不可写，未迁移".to_string(), + ), + }; + Some(PrefsNote { + human, + data: json!({ + "id": migration.as_str(), + "receipt": migration.receipt().map(|path| path.display().to_string()), + "detail": detail, + }), + }) +} diff --git a/crates/cli/src/commands/config/tests.rs b/crates/cli/src/commands/config/tests.rs new file mode 100644 index 0000000..5d51c02 --- /dev/null +++ b/crates/cli/src/commands/config/tests.rs @@ -0,0 +1,320 @@ +//! [`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），读路径默认掩码成 + // ``，所以要看生效值得像用户那样加 `--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 + ); +} + +/// M161：`ull config get update.auto_check` 读的是**主配置**，而且会把 M159 遗留的 +/// `cache/update/prefs.json` 先迁进来（迁移收据在 `migration` 里可查）。 +/// +/// 这条是 mission「`ull config get update.auto_check` 真能读到」的端到端证明： +/// 旧文件里 `false` → 迁移 → 主配置 → CLI 输出 `false`（**不是**默认的 `true`）。 +#[test] +fn the_update_switch_is_migrated_and_readable_from_the_cli() { + let temp = TempDir::new("update-prefs"); + let exe = temp.path().join("exe"); + let ctx = ctx_with(Globals::default(), &exe); + + // 旧域内文件（M159 的落点）：开关是关的。 + let legacy = ctx.layout().cache().join("update").join("prefs.json"); + write_json(&legacy, &json!({ "auto_check": false })); + + let report = get(&ctx, Some("update.auto_check"), false).expect("读 update.auto_check"); + assert_eq!( + report.data["value"], + json!(false), + "旧文件里的 false 必须读到（默认值是 true，读成默认就是丢值）" + ); + assert_eq!( + report.data["path"], + json!(ctx.launcher_config().display().to_string()), + "落点必须是主配置（schema API），不是更新域自己的文件" + ); + assert_eq!( + report.data["migration"]["id"], + json!("migrated"), + "迁移要走一遍并如实报出来：{report:?}" + ); + let receipt = report.data["migration"]["receipt"] + .as_str() + .expect("收据路径") + .to_string(); + assert!(Path::new(&receipt).is_file(), "收据可查：{receipt}"); + assert!(!legacy.exists(), "旧文件必须退役"); + assert!( + report + .human + .iter() + .any(|line| line.contains("已把旧更新偏好迁入主配置")), + "{:?}", + report.human + ); + + // 第二遍：什么都不做（幂等），值仍是 false。 + let again = get(&ctx, Some("update.auto_check"), false).expect("再读一遍"); + assert_eq!(again.data["value"], json!(false)); + assert!( + again.data.get("migration").is_none(), + "第二遍不该再报迁移：{again:?}" + ); + + // `channels` 里只有 stable 时，写 beta 要当面被拒（而不是静默写成「设了没生效」）。 + let error = set(&ctx, "update.channel", "beta").expect_err("beta 不在允许值里"); + assert!(error.to_string().contains("beta"), "{error}"); + + // 允许值写得进去，且读得回来。 + set(&ctx, "update.channel", "stable").expect("写 stable"); + let channel = get(&ctx, Some("update.channel"), false).expect("读 update.channel"); + assert_eq!(channel.data["value"], json!("stable")); +} 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 `：按玩家名 / 登录名 / 条目 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, + /// 需要展示给用户的说明（令牌过期、authlib 注入未落地等）。 + pub notes: Vec, +} + +/// 解析本次启动的身份。 +/// +/// # Errors +/// +/// 账户不存在/重名冲突/多账户未指定/凭据过期且刷新失败/凭据文件缺条目。 +pub fn resolve( + ctx: &Ctx, + account: Option<&str>, + username: Option<&str>, + dry_run: bool, +) -> Result { + let store = AccountStore::open(ctx.auth_data()); + let chosen: Option = 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 --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, +) -> Result { + 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, +) -> Result { + 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::>() + .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..25264eb --- /dev/null +++ b/crates/cli/src/commands/install/loader.rs @@ -0,0 +1,208 @@ +//! `ull install --loader [--loader-version ]`：加载器层的编排。 +//! +//! ```text +//! 目标解析： 位是原版版本 → 叠原版；是已装的加载器版本 id → 叠在它上面（仅 LiteLoader） +//! → LoaderSource::resolve（官方 meta：版本列表 → profile JSON / installer profile / LiteLoader 版本表） +//! → LoaderInstallPlan::build（纯计算：库清单 + loader 版本 JSON 落点） +//! → [--dry-run 到此为止，但多带一段 processors 计划] +//! → 原版已装？否 → vanilla::plan_and_install（先装原版） +//! → 需要 installer？→ 依赖库 → 选 Java → 串行跑 processors（M35） +//! → execute（loader 库并发下载 → 全量就绪才写 versions//.json） +//! → register（实例 versionId 指向 loader 版本） +//! ``` +//! +//! 「先装原版」是**硬前置**：loader 版本 JSON 只声明 `inheritsFrom`，jar 与资源都在原版那层， +//! 原版缺失时启动链必然断裂。已装则跳过（`is_version_installed` 判据 = 版本 JSON 在盘上）。 +//! +//! **父版本**：`` 位写成加载器版本 id（`1.12.2-forge-14.23.5.2860`）时，它就是父版本， +//! 原版版本从盘上的继承链读出来（`addon::loader::parent`）。只有 LiteLoader 接受这种叠法 +//! （它靠 `--tweakClass` 追加生效）；别家**具名拒绝**，不会默默改成叠原版。 +//! +//! processors 段的顺序也是硬约束：**先跑 processors，再写版本 JSON**。版本清单存在是 +//! "这版装完了"的判据，抢在 processors 前写会留下一个启动必崩却被报成已安装的实例。 + +use unlucky_core::addon::loader::{ + parent, 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 unlucky_core::game::loader::{InstanceLoader, LoaderKind as WideLoaderKind}; +use unlucky_core::game::GameLayout; + +use super::report_loader::ProcessorSection; +use super::{ + build_engine, ensure_name_free, failure_error, loader_processors, map_install_error, progress, + register_instance, 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 { + let requested = args.version.trim().to_string(); + if requested.is_empty() { + return Err(CliError::usage( + "install 需要版本 id：%prog% install --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 (version, parent) = resolve_target(ctx, &game, &requested, kind)?; + + let release = block_on(async { + let source = LoaderSource::new(&engine, &meta_cache); + source + .resolve_on( + kind, + &version, + args.loader_version.as_deref(), + parent.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(), + parent_installed: game.is_version_installed(&release.parent_version_id), + }) + .map_err(|error| map_loader_error(&error, ctx))?; + 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, None, &name, section, + )); + } + + let mut vanilla_report = None; + if plan.vanilla_install_needed { + let (_, report) = vanilla::plan_and_install( + ctx, + &engine, + &version, + false, + args.progress, + args.json_progress, + )?; + if let Some(report) = &report { + if !report.is_complete() { + return Err(failure_error(report, ctx)); + } + } + // **M216 r2 P2-2**：原版那段 report 不能在这里丢掉——它的 `warnings` / `manifest` + // （可能替换了共享 `.minecraft` 里 `versions/<原版>/<原版>.json`）必须进人读与 `--json`。 + vanilla_report = report; + } + + // 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 = progress::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), + vanilla_report.as_ref(), + Some(®istration), + &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) +} + +/// `` 位 → （原版版本, 父版本 id）。 +/// +/// 两种写法（`InstallArgs.version` 的文档口径允许版本 id）： +/// - 原版版本（`1.12.2`）→ 叠原版，父版本 = 原版； +/// - **已装的加载器版本 id**（`1.12.2-forge-14.23.5.2860`）→ 叠在它上面，原版版本从盘上的 +/// 继承链读出来。只有 LiteLoader 接受这种叠法；别家给具名错误，不静默改成叠原版。 +fn resolve_target( + ctx: &Ctx, + game: &GameLayout, + requested: &str, + kind: LoaderKind, +) -> Result<(String, Option), CliError> { + if InstanceLoader::parse(requested).kind == WideLoaderKind::Vanilla { + return Ok((requested.to_string(), None)); + } + if kind != LoaderKind::LiteLoader { + return Err(CliError::usage(format!( + "`{requested}` 是一个已装加载器版本 id：只有 LiteLoader 支持叠在别的加载器层上，{} 只能叠在原版上", + kind.label() + )) + .with_hint( + "换成原版版本号：`%prog% install 1.20.1 --loader forge`；或先 `%prog% instances list` 看已装版本", + )); + } + let mc_version = + parent::root_version_id(game, requested).map_err(|error| map_loader_error(&error, ctx))?; + Ok((mc_version, Some(requested.to_string()))) +} 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..f609a88 --- /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//.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, progress, 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, 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 = progress::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 { + 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::() + .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..6f08dc6 --- /dev/null +++ b/crates/cli/src/commands/install/mod.rs @@ -0,0 +1,145 @@ +//! `ull install [--loader ] [--loader-version ]`：装版本本体 / 装加载器层。 +//! +//! ```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） +//! --loader liteloader → 官方版本表 → 从零合成 launchwrapper 清单（不跑任何外部进程） +//! ``` +//! +//! CLI 只做四件事：建下载引擎、把计划/结果排版成人读与 `--json` 两种形态 +//! （[`report`] / [`report_loader`]）、把错误翻译成稳定错误码、往 stderr 打实时进度。 +//! 所有版本/继承/库/下载逻辑都在 core（CLI 不复制任何路径或镜像规则）。 + +mod loader; +mod loader_processors; +mod progress; +mod report; +mod report_loader; +mod vanilla; + +use std::sync::Arc; + +use unlucky_core::addon::loader::LoaderKind; +use unlucky_core::download::{DownloadEngine, DownloadErrorKind}; +use unlucky_core::game::install::{InstallError, InstallReport, Registration}; +use unlucky_core::game::LoaderKind as WideLoaderKind; + +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` 分发。 +/// +/// "认不出" 与 "认得但装不了" 是两件事，错误码也分开（`loader_unknown` / `loader_unsupported`）： +/// `optifine` 属于后者——core 的识别词表里有它（`ull help instances` 也这么写），只是安装管线 +/// 没接（要跑外部 `optifine.Patcher` + 原地改 zip）。两者混成一句"未知加载器"会让用户以为 +/// 是自己的版本 id 写错了。 +/// +/// # Errors +/// +/// 用法错误、加载器未知/认得但装不了、版本不存在、网络失败、校验不符、写盘失败、实例清单损坏。 +pub fn run(ctx: &Ctx, args: &InstallArgs) -> Result { + 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(match WideLoaderKind::parse(raw) { + Some(WideLoaderKind::OptiFine) => CliError::user( + "loader_unsupported", + "optifine 认得出但还没接入安装管线（要跑外部 Patcher 并原地改 zip）", + ) + .with_hint( + "先用官方安装器装好，再 `%prog% instances list` 确认它已在；或用 fabric / quilt / neoforge / forge / liteloader", + ), + _ => CliError::user("loader_unknown", format!("未知加载器 `{raw}`")).with_hint( + "--loader 取值：vanilla / fabric / quilt / neoforge / forge / liteloader（optifine 认得出但装不了）", + ), + }), + }, + } +} + +/// 登记实例（幂等）：`profiles.json` + `config/instances/.json`。 +/// +/// 原版安装与加载器安装共用：前者 `version_id` = 原版 id，后者 = loader 版本 id +/// （实例的 `versionId` 必须指向 loader 版本，否则启动会跑成原版）。 +pub(super) fn register_instance( + ctx: &Ctx, + name: &str, + version_id: &str, +) -> Result { + 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/`，装配参数来自设置（并发 / 重试 / gh-proxy， +/// 读数口径见 [`crate::download`]）——不再用裸 `EngineConfig::default()`（M203）。 +pub(crate) fn build_engine(ctx: &Ctx) -> Arc { + crate::download::engine(ctx) +} + +/// 同名但绑定别的版本 → 冲突；同名同版本视为重装（复用实例，允许）。 +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/progress.rs b/crates/cli/src/commands/install/progress.rs new file mode 100644 index 0000000..b73a2cf --- /dev/null +++ b/crates/cli/src/commands/install/progress.rs @@ -0,0 +1,303 @@ +//! stderr 实时进度（原版安装 / 加载器库 / processor 依赖库三段共用）。 +//! +//! **M210/D11 的教训**：进度行的数字必须是**已经发生的事实**（每个文件的 [`FileStatus`]）， +//! 不能拿「处理到第几个文件」冒充「下载了几个」。旧实现在回调里只累加一个 `done` 就打印 +//! `下载 {done}/{total}`，于是重装同版本（3961 个文件全部已就绪、一个字节都没下）时会连打 +//! `下载 32/3961 … 3961/3961`——进度条在跑，下载量是 0，用户在读一句假话。 +//! +//! 现在分三个计数（下载 / 跳过 / 失败），人读行的措辞随计数走：下载数为 0 时**不出现「下载」 +//! 二字**，改说「已就绪 N/M（跳过 N 个）」。 + +use std::sync::atomic::{AtomicUsize, Ordering}; +use std::sync::Arc; + +use unlucky_core::game::install::{FileOutcome, FileStatus, ProgressSink}; + +use crate::output::progress_line; + +/// 每处理多少个文件打一行进度（3000 个资源下约 90 行，够用又不刷屏）。 +const PROGRESS_EVERY: usize = 32; + +/// 进度里最多逐条打印几条失败（其余交给最终错误汇总）。 +const MAX_PROGRESS_FAILURES: usize = 5; + +/// 一次进度快照：每个字段都是**真实结局**的计数。 +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)] +pub(crate) struct Snapshot { + /// 已处理文件数（含跳过与失败）。 + pub done: usize, + /// 计划文件总数。 + pub total: usize, + /// 本次真的下载并落盘的文件数。 + pub downloaded: usize, + /// 已存在且校验通过、本次跳过的文件数。 + pub skipped: usize, + /// 失败文件数。 + pub failed: usize, +} + +impl Snapshot { + /// 人读进度行。 + /// + /// 下载数为 0 时**不提「下载」**：本次一个字节都没下，再写「下载 0/N」也只是换个说法的假进度。 + pub(crate) fn text(&self) -> String { + let failure = if self.failed > 0 { + format!(" / 失败 {}", self.failed) + } else { + String::new() + }; + if self.downloaded == 0 { + format!( + "已就绪 {}/{}（跳过 {} 个{failure}）", + self.done, self.total, self.skipped + ) + } else { + format!( + "下载 {} 个 / 跳过 {} 个（进度 {}/{}{failure}）", + self.downloaded, self.skipped, self.done, self.total + ) + } + } + + /// `--json` 模式的进度事件（字段名稳定，`done`/`total` 保持旧名以兼容脚本）。 + fn json(&self) -> serde_json::Value { + serde_json::json!({ + "event": "progress", + "done": self.done, + "total": self.total, + "downloaded": self.downloaded, + "skipped": self.skipped, + "failed": self.failed, + }) + } +} + +/// 计数：回调来自多个下载线程，全部原子累加。 +#[derive(Debug, Default)] +struct Tally { + done: AtomicUsize, + downloaded: AtomicUsize, + skipped: AtomicUsize, + failed: AtomicUsize, + failure_lines: AtomicUsize, +} + +impl Tally { + /// 记一个结局，返回记完之后的快照。 + fn observe(&self, outcome: &FileOutcome, total: usize) -> Snapshot { + let done = self.done.fetch_add(1, Ordering::Relaxed) + 1; + match outcome.status { + FileStatus::Downloaded => { + self.downloaded.fetch_add(1, Ordering::Relaxed); + } + FileStatus::Skipped => { + self.skipped.fetch_add(1, Ordering::Relaxed); + } + FileStatus::Failed => { + self.failed.fetch_add(1, Ordering::Relaxed); + } + } + Snapshot { + done, + total, + downloaded: self.downloaded.load(Ordering::Relaxed), + skipped: self.skipped.load(Ordering::Relaxed), + failed: self.failed.load(Ordering::Relaxed), + } + } +} + +/// 实时进度回调（只写 stderr，不污染 `--json` 的 stdout）。 +/// +/// 两种形态：人类模式打文本行；`--json` 模式打 **JSONL**（一行一条事件，`event` 字段分流）， +/// 这样脚本既能吃 stdout 的最终信封，也能实时跟进而不必解析文本。 +/// +/// 失败行只打前几条：整源不可达时会一口气失败上千个文件，全打出来既没用又淹没原因。 +pub fn progress_sink(enabled: bool, json: bool, total: usize) -> Option { + sink_with(enabled, json, total, Arc::new(progress_line)) +} + +/// 可注入输出端的构造器（测试据此抓行；生产只有一个调用者 [`progress_sink`]）。 +fn sink_with( + enabled: bool, + json: bool, + total: usize, + out: Arc, +) -> Option { + if !enabled { + return None; + } + let tally = Arc::new(Tally::default()); + Some(Arc::new(move |outcome: &FileOutcome| { + let snapshot = tally.observe(outcome, total); + if let Some(failure) = &outcome.failure { + let seen = tally.failure_lines.fetch_add(1, Ordering::Relaxed); + if seen < MAX_PROGRESS_FAILURES { + emit( + json, + serde_json::json!({ + "event": "file_failed", + "done": snapshot.done, + "total": total, + "name": outcome.name, + "role": outcome.role.as_str(), + "kind": failure.kind.as_str(), + "message": failure.message, + }), + &format!( + "失败 {}/{} {}：{}", + snapshot.done, total, outcome.name, failure.message + ), + &out, + ); + } else if seen == MAX_PROGRESS_FAILURES { + emit( + json, + serde_json::json!({ + "event": "progress_truncated", + "suppressed_after": MAX_PROGRESS_FAILURES, + }), + "（更多失败不再逐条打印，见最终错误汇总）", + &out, + ); + } + return; + } + if snapshot.done.is_multiple_of(PROGRESS_EVERY) || snapshot.done == total { + emit(json, snapshot.json(), &snapshot.text(), &out); + } + })) +} + +/// 一条进度：JSONL 模式打序列化后的一行，人类模式打短文本。 +fn emit( + json_mode: bool, + record: serde_json::Value, + text: &str, + out: &Arc, +) { + if json_mode { + let line = record.to_string(); + out(&line); + } else { + out(text); + } +} + +#[cfg(test)] +mod tests { + use std::sync::Mutex; + + use unlucky_core::download::DownloadErrorKind; + use unlucky_core::game::install::{FileFailure, FileRole}; + + use super::*; + + /// 测试用的输出端：一个可注入的 sink + 它收到的行。 + type Recorder = (Arc, Arc>>); + + /// 抓行的输出端。 + fn recorder() -> Recorder { + let lines = Arc::new(Mutex::new(Vec::new())); + let sink_lines = Arc::clone(&lines); + let out: Arc = + Arc::new(move |line: &str| sink_lines.lock().expect("锁").push(line.to_string())); + (out, lines) + } + + fn outcome(name: &str, status: FileStatus) -> FileOutcome { + FileOutcome { + role: FileRole::Asset, + name: name.to_string(), + dest: std::path::PathBuf::from(format!("assets/{name}")), + status, + bytes: 1234, + source: Some("cache".to_string()), + failure: None, + } + } + + /// **D11 用例**：全部已存在（重装同版本）⇒ 进度行里不出现「下载」，下载计数为 0。 + /// + /// 抓得住：把「处理序号」当下载量打印的旧实现（它会打出 `下载 32/96` 这类行）； + /// 以及任何「下载数 > 0 却说没下载」的表述。抓不住：行里出现的其它夸张词（措辞审查）， + /// 也不管单行是否真的落到 stderr（那是 [`crate::output::progress_line`] 的事）。 + #[test] + fn all_skipped_progress_never_claims_downloads() { + const TOTAL: usize = 96; // 3 的倍数，必然跨过 PROGRESS_EVERY + let (out, lines) = recorder(); + let sink = sink_with(true, false, TOTAL, out).expect("进度开关打开时必须有 sink"); + for index in 0..TOTAL { + sink(&outcome(&format!("asset-{index}"), FileStatus::Skipped)); + } + let lines = lines.lock().expect("锁").clone(); + assert!(!lines.is_empty(), "应当有进度行"); + for line in &lines { + assert!( + !line.contains("下载"), + "全部跳过时进度行不许提「下载」：{line}" + ); + } + let last = lines.last().expect("至少一行"); + assert!( + last.contains(&format!("已就绪 {TOTAL}/{TOTAL}")) + && last.contains(&format!("跳过 {TOTAL}")), + "全跳过应当说「已就绪 N/N（跳过 N 个）」：{last}" + ); + } + + /// 同一场景的 `--json` 形态：`downloaded` 必须是 0（脚本据此判断「其实没下」）。 + #[test] + fn all_skipped_json_progress_reports_zero_downloads() { + const TOTAL: usize = 32; + let (out, lines) = recorder(); + let sink = sink_with(true, true, TOTAL, out).expect("进度开关打开时必须有 sink"); + for index in 0..TOTAL { + sink(&outcome(&format!("lib-{index}"), FileStatus::Skipped)); + } + let records: Vec = lines + .lock() + .expect("锁") + .iter() + .map(|line| serde_json::from_str(line).expect("JSONL")) + .collect(); + let progress = records + .iter() + .find(|record| record["event"] == "progress") + .expect("应当有 progress 事件"); + assert_eq!(progress["downloaded"], 0); + assert_eq!(progress["skipped"], TOTAL); + assert_eq!(progress["done"], TOTAL); + assert_eq!(progress["total"], TOTAL); + } + + /// 真的有下载时，计数与措辞都跟着事实走（避免「一刀切不打印」这种假修复）。 + #[test] + fn mixed_outcomes_report_real_counts() { + let (out, lines) = recorder(); + let sink = sink_with(true, false, 4, out).expect("sink"); + sink(&outcome("client.jar", FileStatus::Downloaded)); + let failed = FileOutcome { + failure: Some(FileFailure { + kind: DownloadErrorKind::Network, + message: "连接被重置".to_string(), + }), + ..outcome("b", FileStatus::Failed) + }; + sink(&failed); + sink(&outcome("c", FileStatus::Skipped)); + sink(&outcome("d", FileStatus::Skipped)); + let lines = lines.lock().expect("锁").clone(); + // 失败有自己的行（`失败 2/4 b：…`），进度行不拿它冒充下载量。 + assert!( + lines.iter().any(|line| line.starts_with("失败 2/4 b")), + "{lines:?}" + ); + let last = lines.last().expect("至少一行"); + // done == total 时无条件打最后一行。 + assert!(last.contains("下载 1 个"), "{last}"); + assert!(last.contains("跳过 2 个"), "{last}"); + assert!(last.contains("失败 1"), "{last}"); + assert!(last.contains("进度 4/4"), "{last}"); + } +} diff --git a/crates/cli/src/commands/install/report.rs b/crates/cli/src/commands/install/report.rs new file mode 100644 index 0000000..a5b47bc --- /dev/null +++ b/crates/cli/src/commands/install/report.rs @@ -0,0 +1,265 @@ +//! 安装结果的两种呈现形态：人类可读行 + `--json` 载荷（stderr 实时进度见 [`super::progress`]）。 +//! +//! 拆出来是因为 `install` 的流程（规划 → 下载 → 登记）与排版彼此独立： +//! 前者要能读懂，后者要能被脚本断言。`--dry-run` 与真实安装共用同一份排版， +//! 差别只是多出逐文件清单与源选择。 + +use serde_json::json; +use unlucky_core::download::DownloadEngine; +use unlucky_core::game::install::{FileOutcome, InstallPlan, InstallReport, Registration}; + +use crate::context::Ctx; +use crate::output::Report; + +/// 排版一次安装结果。 +#[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::>(), + })), + "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 { + 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(" → ") + )); + } + // **M216 P2-2**：有 report 就报**运行期**告警——它开头就是 `plan.warnings` 的副本，加上执行期 + // 才知道的事（「已替换版本清单 … 旧的那份备份在 …」）。此前这里只遍历 `plan.warnings`， + // 于是「我们动了别人 `.minecraft` 里那份清单」这句话在 `ull install` 的人读输出里**从没出现过** + // （只有 `--json` 的 `result.warnings` 有）——「不静默破坏」就落不了地。 + // 没有 report（`--dry-run`）时退回计划期告警。 + let warnings = report.map_or(plan.warnings.as_slice(), |report| { + report.warnings.as_slice() + }); + for warning in warnings { + human.push(format!("告警: {warning}")); + } + if let Some(manifest) = report.and_then(|report| report.manifest.as_ref()) { + if let Some(backup) = manifest.backup() { + human.push(format!( + "版本清单已替换（旧的那份备份在 {}）", + backup.display() + )); + } + } + 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; + use super::*; + use unlucky_core::game::arguments::Environment; + use unlucky_core::game::install::{ManifestWrite, PlanInput}; + use unlucky_core::game::layout::GameLayout; + use unlucky_core::game::manifest::VersionJson; + + /// **M216 P2-2**：清单被替换这件事必须出现在**人读**行里（以前只进 `--json`， + /// 复审 r1 抓的就是「对玩家仍然静默」）。 + /// + /// 抓得住：`human_lines` 退回只遍历 `plan.warnings`（那时找不到「已替换版本清单」⇒ 红， + /// 正是修前状态）；`manifest` 的备份路径没渲出来。抓不住：真实终端排版与颜色、 + /// 以及 `ull install` 的整条命令链（本用例直接调排版函数，不落盘、不联网）。 + #[test] + fn a_replaced_manifest_is_said_out_loud_in_the_human_output() { + let root = std::env::temp_dir().join(format!("ull216-report-{}", std::process::id())); + let layout = GameLayout::new(&root); + let resolved = VersionJson::from_json_str( + r#"{"id":"1.20.1","mainClass":"net.minecraft.client.main.Main", + "downloads":{"client":{"sha1":"aa","size":1,"url":"https://example.invalid/c.jar"}}}"#, + ) + .expect("清单应可解析"); + let plan = InstallPlan::build(PlanInput { + layout: &layout, + version_id: "1.20.1", + resolved: &resolved, + asset_index: None, + environment: &Environment::host(), + }) + .expect("组计划应成功"); + + let backup = root.join("versions/1.20.1/1.20.1.json.ullbak-4242"); + let mut warnings = plan.warnings.clone(); + warnings.push("已替换版本清单 （旧的那份备份在 ）".to_string()); + let report = InstallReport { + files: Vec::new(), + version_json: Some(plan.version_json_path.clone()), + manifest: Some(ManifestWrite::Replaced { + backup: backup.clone(), + }), + warnings, + }; + + let text = human_lines(false, &plan, Some(&report), None, &[], "ignored", "1.20.1").join( + " +", + ); + assert!( + text.contains("已替换版本清单"), + "运行期告警没进人读输出：{text}" + ); + assert!( + text.contains(&backup.display().to_string()), + "备份路径没进人读输出：{text}" + ); + std::fs::remove_dir_all(&root).ok(); + } + + #[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..982d868 --- /dev/null +++ b/crates/cli/src/commands/install/report_loader.rs @@ -0,0 +1,399 @@ +//! 加载器安装的呈现形态（人类可读行 + `--json` 载荷）。 +//! +//! 与 [`super::report`] 的分工：那边是"原版安装"（客户端 jar + 资源 + 库），这边是 +//! "叠在原版上的 loader 层"（只有库）。共用同一套进度回调与字节格式化。 + +use serde_json::{json, Value}; +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>, + vanilla: Option<&InstallReport>, + registration: Option<&Registration>, + name: &str, + processors: Option>, +) -> 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); + } + if let Some(block) = vanilla_json(vanilla) { + data["vanilla"] = block; + } + + Report::new( + data, + human_lines( + dry_run, + plan, + report, + vanilla, + 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 +} + +/// `--json` 的 `vanilla` 段：先装原版那一步的告警 + 清单结局（`None` = 这次没先装原版）。 +/// +/// **M216 r2 P2-2**：原版 report 在 `is_complete()` 之后就被丢了 ⇒ 「替换了共享 `.minecraft` +/// 里的原版清单」在加载器安装的 JSON 里没有痕迹。 +fn vanilla_json(vanilla: Option<&InstallReport>) -> Option { + let report = vanilla?; + Some(json!({ + "warnings": report.warnings, + "version_json": report.version_json.as_ref().map(|path| path.display().to_string()), + "manifest": report.manifest.as_ref().map(|write| json!({ + "kind": write.as_str(), + "backup": write.backup().map(|path| path.display().to_string()), + })), + })) +} + +/// 人读行里「先装原版」那一段（**M216 r2 P2-2**，与 [`vanilla_json`] 同源）：以前 +/// `human_lines` 只遍历 `plan.warnings()`，原版那份 report 的告警与「清单被替换」都没说。 +fn vanilla_lines(vanilla: Option<&InstallReport>) -> Vec { + let Some(report) = vanilla else { + return Vec::new(); + }; + let mut lines: Vec = report + .warnings + .iter() + .map(|warning| format!("告警（原版）: {warning}")) + .collect(); + if let Some(backup) = report.manifest.as_ref().and_then(|write| write.backup()) { + lines.push(format!( + "原版版本清单已替换（旧的那份备份在 {}）", + backup.display() + )); + } + lines +} + +fn human_lines( + dry_run: bool, + plan: &LoaderInstallPlan, + report: Option<&InstallReport>, + vanilla: Option<&InstallReport>, + registration: Option<&Registration>, + samples: &[serde_json::Value], + name: &str, + processors: Option<&ProcessorSection<'_>>, +) -> Vec { + 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}")); + } + human.extend(vanilla_lines(vanilla)); + 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 { + 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 +} + +#[cfg(test)] +mod tests { + use super::*; + use std::path::PathBuf; + use unlucky_core::addon::loader::{ + LoaderInstallPlan, LoaderKind, LoaderPlanInput, LoaderRelease, LoaderSupport, + }; + use unlucky_core::game::arguments::Environment; + use unlucky_core::game::install::ManifestWrite; + use unlucky_core::game::layout::GameLayout; + use unlucky_core::game::manifest::VersionJson; + + /// 一份最小的 Fabric 加载器计划（零网络：只算路径，不落盘）。 + fn loader_plan(root: &std::path::Path) -> LoaderInstallPlan { + let layout = GameLayout::new(root); + let release = LoaderRelease { + kind: LoaderKind::Fabric, + mc_version: "1.20.1".to_string(), + parent_version_id: "1.20.1".to_string(), + loader_version: "0.15.11".to_string(), + version_id: "1.20.1-fabric-0.15.11".to_string(), + version_json: VersionJson::from_json_str( + r#"{"id":"1.20.1-fabric-0.15.11","mainClass":"net.fabricmc.loader.impl.launch.knot.KnotClient","inheritsFrom":"1.20.1","libraries":[]}"#, + ) + .expect("loader 清单应可解析"), + support: LoaderSupport::JsonRoute, + installer: None, + install_profile: None, + warnings: Vec::new(), + }; + LoaderInstallPlan::build(LoaderPlanInput { + layout: &layout, + release: &release, + environment: &Environment::host(), + parent_installed: true, + }) + .expect("计划应可组") + } + + /// **M216 r2 P2-2**：装加载器时「先装原版」那一步替换了共享 `.minecraft` 里的原版清单， + /// 这句话必须出现在**加载器安装**的人读输出里（此前只出现在纯原版安装的输出里）。 + /// + /// 抓得住：`human_lines` 只遍历 `plan.warnings()`（= r1 状态）；备份路径没渲出来； + /// `--json` 的 `vanilla` 段没了。抓不住：真实 `ull install --loader …` 整条链路（要网络）， + /// 以及「原版 report 是否真被 `loader.rs` 传进来」那步接线（见报告）。 + #[test] + fn a_replaced_vanilla_manifest_is_said_out_loud_in_the_loader_output() { + let root = std::env::temp_dir().join(format!("ull216-loader-{}", std::process::id())); + let plan = loader_plan(&root); + let backup = PathBuf::from("/g/.minecraft/versions/1.20.1/1.20.1.json.ullbak-99"); + let vanilla = InstallReport { + files: Vec::new(), + version_json: Some(PathBuf::from("/g/.minecraft/versions/1.20.1/1.20.1.json")), + manifest: Some(ManifestWrite::Replaced { + backup: backup.clone(), + }), + warnings: vec!["已替换版本清单 /g/.minecraft/versions/1.20.1/1.20.1.json".to_string()], + }; + let text = human_lines(false, &plan, None, Some(&vanilla), None, &[], "n", None).join("\n"); + assert!( + text.contains("已替换版本清单"), + "原版那段的告警没进人读输出：{text}" + ); + assert!( + text.contains(&backup.display().to_string()), + "原版清单的备份路径没进人读输出：{text}" + ); + // 没先装原版时不许凭空多说话。 + let plain = human_lines(false, &plan, None, None, None, &[], "n", None).join("\n"); + assert!(!plain.contains("原版版本清单已替换"), "{plain}"); + // `--json` 的 `vanilla` 段（结构化，脚本可读）。 + let block = vanilla_json(Some(&vanilla)).expect("应当有 vanilla 段"); + assert_eq!(block["manifest"]["kind"], Value::String("replaced".into())); + assert_eq!( + block["manifest"]["backup"].as_str(), + Some(backup.to_string_lossy().as_ref()) + ); + assert!(vanilla_json(None).is_none()); + std::fs::remove_dir_all(&root).ok(); + } +} diff --git a/crates/cli/src/commands/install/vanilla.rs b/crates/cli/src/commands/install/vanilla.rs new file mode 100644 index 0000000..65b6157 --- /dev/null +++ b/crates/cli/src/commands/install/vanilla.rs @@ -0,0 +1,160 @@ +//! `ull install `（无加载器）：M27 原版安装流程的宿主。 +//! +//! ```text +//! RemoteSource::resolve（版本清单缓存 → 版本 JSON → 继承链） +//! → RemoteSource::asset_index（资源索引，顺便拿字节给下面预取） +//! → InstallPlan::build（纯计算：文件清单 / 总大小 / 角色） +//! → [--dry-run 到此为止] +//! → execute（跳过已就绪 → 引擎并发下载 → 原子写版本 JSON） +//! → register（profiles.json + config/instances/.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, progress, 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 { + let version = args.version.trim().to_string(); + if version.is_empty() { + return Err(CliError::usage( + "install 需要版本 id：%prog% install ", + )); + } + 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), 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 { 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 = progress::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, +} diff --git a/crates/cli/src/commands/instance_launch.rs b/crates/cli/src/commands/instance_launch.rs new file mode 100644 index 0000000..22e5502 --- /dev/null +++ b/crates/cli/src/commands/instance_launch.rs @@ -0,0 +1,269 @@ +//! `instances launch-args `（M157）：实例级启动参数的读/写。 +//! +//! 五项的**含义与回落规则**都在 core（[`unlucky_core::game::launch_overrides`]），本命令只做 +//! 三件事：找实例、把命令行选项拼成 [`LaunchOverridesPatch`]、把生效值印出来。 +//! +//! ```text +//! ull instances launch-args 生存 # 读：实例层 + 生效值 + 后端门槛 +//! ull instances launch-args 生存 --jvm "-XX:+UseG1GC" --backend vulkan +//! ull instances launch-args 生存 --memory 8192 --game "--fullscreen" +//! ull instances launch-args 生存 --clear # 五项全部回「跟随全局」 +//! ``` +//! +//! 判定「版本够不够 Vulkan」用 core 的组合判据 +//! [`unlucky_core::launch::overrides::backend_allowed`]（继承解析后的库表 + 版本门槛）， +//! 与 GUI 灰化、拼装链的告警是同一个函数——CLI 不另写一条。 +//! +//! 全局层（`java.extra_args` / `java.default_memory_mb` / `java.selected_path`）在这里读一次 +//! 设置文档填 [`GlobalLaunchDefaults`]；presenter 的 host 侧有一份同形的读法（两个 crate 各自 +//! 依赖 core，没法共享那三行 IO），字段口径以 core 的回落表为准。 + +use serde_json::json; +use unlucky_core::game::install::instance::{ + read_instance_config, write_instance_config, InstanceConfig, +}; +use unlucky_core::game::launch_overrides::{ + resolve, GlobalLaunchDefaults, GraphicsBackend, LaunchOverridesPatch, ResolvedLaunch, +}; +use unlucky_core::game::{self, VersionJson}; +use unlucky_core::launch::game_args::GRAPHICS_BACKEND_MIN_VERSION; +use unlucky_core::launch::game_version::GameVersion; +use unlucky_core::launch::overrides::backend_allowed; +use unlucky_core::setting::keys::launcher_schema; +use unlucky_core::setting::store::SettingStore; + +use crate::cli::InstanceLaunchArgs; +use crate::context::Ctx; +use crate::error::CliError; +use crate::output::Report; + +use super::instances::read_profiles; + +/// `ull instances launch-args`。 +/// +/// # Errors +/// +/// 实例不存在、值非法（内存越界 / 未知后端）、实例文件读写失败时返回用户错误。 +pub fn run(ctx: &Ctx, args: &InstanceLaunchArgs) -> Result { + let profiles = read_profiles(ctx)?; + let profile = profiles + .profiles + .iter() + .find(|profile| profile.id.as_str() == args.instance || profile.name == args.instance) + .cloned() + .ok_or_else(|| { + CliError::user("not_found", format!("找不到实例 `{}`", args.instance)) + .with_hint("用 `%prog% instances list` 看已登记的实例") + })?; + let id = profile.id.as_str().to_string(); + let layout = ctx.layout(); + + let mut config = read_instance_config(&layout, &id) + .map_err(|error| CliError::user("instance_config", format!("读实例设置失败：{error}")))? + .unwrap_or_else(|| InstanceConfig::new(&id, &profile.version_id)); + + let mut updated = false; + if !args.is_read_only() { + config.launch = config + .launch + .patched(&patch_from(args)) + .map_err(CliError::usage)?; + write_instance_config(&layout, &config).map_err(|error| { + CliError::user("instance_config", format!("写实例设置失败：{error}")) + })?; + updated = true; + } + + let effective = resolve(Some(&config.launch), &global_defaults(ctx)); + let (allowed, mc_version) = backend_gate(ctx, &profile.version_id); + let layer = &config.launch; + + let data = json!({ + "instance_id": id, + "name": profile.name, + "version_id": profile.version_id, + "updated": updated, + "launch": { + "jvm_args": layer.jvm_args.clone().unwrap_or_default(), + "game_args": layer.game_args.clone().unwrap_or_default(), + "memory_mb": layer.memory_mb, + "java_path": layer.java_path.as_ref().map(|path| path.display().to_string()), + "graphics_backend": layer.graphics_backend.unwrap_or_default().as_str(), + }, + "effective": { + "jvm_args": effective.instance_jvm_args.clone().unwrap_or_default(), + "global_jvm_args": effective.global_jvm_args.clone().unwrap_or_default(), + "game_args": effective.game_args.clone().unwrap_or_default(), + "memory_mb": effective.memory_mb, + "java_path": effective.java_path.as_ref().map(|path| path.display().to_string()), + "graphics_backend": effective.graphics_backend.as_str(), + "graphics_backend_allowed": allowed, + "graphics_backend_min_version": GRAPHICS_BACKEND_MIN_VERSION, + "mc_version": mc_version, + }, + "graphics_backend_options": GraphicsBackend::IDS, + }); + + let mut human = vec![format!( + "{}（{} · {}）{}", + profile.name, + profile.version_id, + id, + if updated { " ← 已保存" } else { "" } + )]; + human.push(format!( + " JVM 参数（实例）: {}", + layer + .jvm_args + .clone() + .unwrap_or_else(|| "（跟随全局）".to_string()) + )); + human.push(format!( + " 游戏参数（实例）: {}", + layer + .game_args + .clone() + .unwrap_or_else(|| "（无）".to_string()) + )); + human.push(format!( + " 最大内存: {} MiB{}", + effective.memory_mb, + match layer.memory_mb { + Some(_) => "（实例覆盖）", + None => "（跟随全局 / 出厂默认）", + } + )); + human.push(format!( + " Java: {}", + effective + .java_path + .as_ref() + .map(|path| path.display().to_string()) + .unwrap_or_else(|| "（自动挑：托管 > JAVA_HOME > PATH）".to_string()) + )); + human.push(format!( + " 图形后端: {}{}", + effective.graphics_backend.as_str(), + if effective.graphics_backend.is_default() { + "（不下发 --graphicsBackend）".to_string() + } else if allowed { + format!("（{} 可下发）", mc_version) + } else { + format!("（版本 {mc_version} 不支持，不会下发；需 MC {GRAPHICS_BACKEND_MIN_VERSION}+）") + } + )); + + Ok(Report::new(data, human)) +} + +/// 命令行选项 → core 的文本补丁（`--clear` 先清五项，随后给出的项覆盖）。 +fn patch_from(args: &InstanceLaunchArgs) -> LaunchOverridesPatch { + let mut patch = if args.clear { + LaunchOverridesPatch::clear_all() + } else { + LaunchOverridesPatch::default() + }; + if let Some(value) = &args.jvm_args { + patch.jvm_args = Some(value.clone()); + } + if let Some(value) = &args.game_args { + patch.game_args = Some(value.clone()); + } + if let Some(value) = &args.memory_mb { + patch.memory_mb = Some(value.clone()); + } + if let Some(value) = &args.java { + patch.java_path = Some(value.clone()); + } + if let Some(value) = &args.backend { + patch.graphics_backend = Some(value.clone()); + } + patch +} + +/// 全局层（三个设置键）。 +pub(crate) fn global_defaults(ctx: &Ctx) -> GlobalLaunchDefaults { + let store = SettingStore::load(ctx.launcher_config(), launcher_schema()); + let text = |key: &str| -> Option { + store + .doc() + .effective_str(key) + .map(str::trim) + .filter(|value| !value.is_empty()) + .map(str::to_string) + }; + GlobalLaunchDefaults { + jvm_args: text("java.extra_args"), + game_args: None, + memory_mb: store + .effective("java.default_memory_mb") + .and_then(serde_json::Value::as_u64) + .and_then(|value| u32::try_from(value).ok()), + java_path: text("java.selected_path").map(std::path::PathBuf::from), + graphics_backend: None, + } +} + +/// 三级回落后的生效值（启动装配用；`instance_id` 为空 = 没有实例档案，只用全局层）。 +/// +/// 与 presenter 的 `host::launch_args::resolved` 同义：那边给 GUI 用，这边给 `ull launch` 用， +/// 规则都在 core 的 [`resolve`]，两处只剩「读哪几份文件」的差别。 +pub(crate) fn resolved(ctx: &Ctx, instance_id: &str) -> ResolvedLaunch { + let overrides = if instance_id.is_empty() { + None + } else { + read_instance_config(&ctx.layout(), instance_id) + .ok() + .flatten() + .map(|config| config.launch) + }; + resolve(overrides.as_ref(), &global_defaults(ctx)) +} + +/// 版本能不能用 `--graphicsBackend`，以及判定依据的游戏版本（继承链根）。 +fn backend_gate(ctx: &Ctx, version_id: &str) -> (bool, String) { + let game_layout = ctx.game(); + let Ok(text) = std::fs::read_to_string(game_layout.version_json(version_id)) else { + return (false, version_id.to_string()); + }; + let Ok(manifest) = VersionJson::from_json_str(&text) else { + return (false, version_id.to_string()); + }; + let mc_version = root_version_id(&game_layout, &manifest); + let source = |id: &str| -> Option { + std::fs::read_to_string(game_layout.version_json(id)) + .ok() + .and_then(|text| VersionJson::from_json_str(&text).ok()) + }; + let resolved = game::resolve(&source, &manifest).unwrap_or(manifest); + let allowed = backend_allowed(&GameVersion::parse(&mc_version), &resolved); + (allowed, mc_version) +} + +/// 继承链根（原版层）的 id——能力位与版本门限都以它为准（loader 层的 id 带加载器后缀）。 +/// +/// `pub(crate)`：`snapshot::prepare` 的装配（`SnapshotInput.game_version`）也要这一份口径， +/// 门槛判定（本模块的 `backend_gate`）与拼装必须用**同一个**根版本，否则会出现 +/// 「UI 说可用、命令行里没有这个参数」的静默偏差。 +pub(crate) fn root_version_id( + layout: &unlucky_core::game::GameLayout, + manifest: &VersionJson, +) -> String { + let mut current = manifest.id.clone().unwrap_or_default(); + let mut parent = manifest.inherits_from.clone().filter(|id| !id.is_empty()); + for _ in 0..16 { + let Some(next) = parent else { break }; + let Ok(text) = std::fs::read_to_string(layout.version_json(&next)) else { + return next; + }; + let Ok(json) = VersionJson::from_json_str(&text) else { + return next; + }; + current = json.id.clone().unwrap_or(next); + parent = json.inherits_from.clone().filter(|id| !id.is_empty()); + } + current +} + +#[cfg(test)] +mod tests; diff --git a/crates/cli/src/commands/instance_launch/tests.rs b/crates/cli/src/commands/instance_launch/tests.rs new file mode 100644 index 0000000..a166b34 --- /dev/null +++ b/crates/cli/src/commands/instance_launch/tests.rs @@ -0,0 +1,212 @@ +//! [`super`] 的单测：走真入口 [`crate::run`]，断言用户/脚本拿到的那份输出。 +//! +//! 口径与 `instances/tests.rs` 一致：临时 `--data-dir` + 真 `profiles.json`，只看 stdout 的 +//! JSON 信封（`--json`）与退出码。回落规则的真值表在 core 的 +//! `game::launch_overrides` / `launch::overrides` 测试里，这里只验 CLI 有没有如实搬运。 + +use std::path::{Path, PathBuf}; +use std::sync::atomic::{AtomicU64, Ordering}; +use std::time::{SystemTime, UNIX_EPOCH}; + +use serde_json::{json, Value}; +use unlucky_core::platform::layout::{LauncherLayout, LAUNCHER_HOME_DIR}; + +/// 一次性临时目录（`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-instance-launch-{tag}-{}-{seq}-{nanos}", + std::process::id() + )); + std::fs::create_dir_all(&path).expect("建临时目录"); + Self(path) + } + + fn path(&self) -> &Path { + &self.0 + } + + fn arg(&self) -> String { + self.0.display().to_string() + } +} + +impl Drop for TempDir { + fn drop(&mut self) { + let _ = std::fs::remove_dir_all(&self.0); + } +} + +/// 写 `.ULL/config/profiles.json` 并返回第一个实例的 id。 +fn write_profiles(data_root: &Path, name: &str, version_id: &str) -> String { + let dir = data_root.join(LAUNCHER_HOME_DIR).join("config"); + std::fs::create_dir_all(&dir).expect("建配置目录"); + let id = "11111111-2222-4333-8444-555555555555".to_string(); + let document = json!({ + "schema_version": 1, + "profiles": [{ "id": id, "name": name, "version_id": version_id }], + }); + std::fs::write( + dir.join("profiles.json"), + serde_json::to_vec_pretty(&document).expect("序列化 profiles.json"), + ) + .expect("写 profiles.json"); + id +} + +/// 写 `/.minecraft/versions//.json`（库表可带 vulkan）。 +fn write_version(data_root: &Path, id: &str, vulkan: bool) { + let path = data_root + .join(".minecraft") + .join("versions") + .join(id) + .join(format!("{id}.json")); + std::fs::create_dir_all(path.parent().expect("版本目录")).expect("版本目录"); + let libs = if vulkan { + r#"[{"name":"org.lwjgl:lwjgl-vulkan:3.4.3"}]"# + } else { + "[]" + }; + std::fs::write(&path, format!(r#"{{"id":"{id}","libraries":{libs}}}"#)).expect("写版本 JSON"); +} + +/// 跑一次 CLI，返回（退出码, stdout）。 +fn run_cli(args: &[&str]) -> (i32, String) { + let owned: Vec = args.iter().map(|arg| (*arg).to_string()).collect(); + let mut out: Vec = Vec::new(); + let mut err: Vec = Vec::new(); + let code = crate::run(&owned, &mut out, &mut err); + (code, String::from_utf8_lossy(&out).into_owned()) +} + +/// 跑 `instances launch-args … --json`，返回 `data` 载荷。 +fn launch_args(dir: &TempDir, rest: &[&str]) -> Value { + let root = dir.arg(); + let mut args = vec!["instances", "launch-args", "--json", "--data-dir", &root]; + args.extend_from_slice(rest); + let (code, stdout) = run_cli(&args); + assert_eq!(code, 0, "{stdout}"); + let value: Value = serde_json::from_str(&stdout).expect("输出不是 JSON"); + assert_eq!(value["ok"], true, "{stdout}"); + value["data"].clone() +} + +#[test] +fn read_reports_instance_layer_and_effective_values() { + let dir = TempDir::new("read"); + let id = write_profiles(dir.path(), "生存", "1.20.4"); + let data = launch_args(&dir, &[&id]); + assert_eq!(data["instance_id"], id.as_str()); + assert_eq!(data["updated"], false); + assert_eq!(data["launch"]["graphics_backend"], "default"); + // 没配内存 ⇒ 生效值是出厂默认 2048（三级回落的最后一级）。 + assert_eq!(data["effective"]["memory_mb"], 2048); + assert_eq!(data["effective"]["graphics_backend_allowed"], false); + assert_eq!( + data["graphics_backend_options"], + json!(["default", "opengl", "vulkan"]) + ); +} + +#[test] +fn write_from_flags_then_read_back() { + let dir = TempDir::new("write"); + let id = write_profiles(dir.path(), "生存", "26.2-snapshot-2"); + write_version(dir.path(), "26.2-snapshot-2", true); + + let data = launch_args( + &dir, + &[ + &id, + "--jvm=-XX:+UseG1GC", + // 值以 `--` 开头时必须用 `--key=value` 形式（`--game --fullscreen` 会被解析器 + // 当成「缺少取值」——那是全项目 CLI 的既有口径，见 help 里的提示）。 + "--game=--fullscreen", + "--memory", + "6144", + "--backend", + "vulkan", + ], + ); + assert_eq!(data["updated"], true); + assert_eq!(data["launch"]["jvm_args"], "-XX:+UseG1GC"); + assert_eq!(data["launch"]["memory_mb"], 6144); + assert_eq!(data["launch"]["graphics_backend"], "vulkan"); + // 26.2-snapshot-2 过了门槛（判定来自 core 的能力位 + 版本门限）。 + assert_eq!(data["effective"]["graphics_backend_allowed"], true); + + // 再读一次：落盘之后依然在（`--json` 是事实上的对外契约）。 + let again = launch_args(&dir, &[&id]); + assert_eq!(again["updated"], false); + assert_eq!(again["launch"]["jvm_args"], "-XX:+UseG1GC"); + assert_eq!(again["launch"]["game_args"], "--fullscreen"); +} + +#[test] +fn clear_restores_follow_the_global() { + let dir = TempDir::new("clear"); + let id = write_profiles(dir.path(), "生存", "1.20.4"); + launch_args(&dir, &[&id, "--memory", "4096", "--backend", "opengl"]); + let cleared = launch_args(&dir, &[&id, "--clear"]); + assert_eq!(cleared["launch"]["memory_mb"], Value::Null); + assert_eq!(cleared["launch"]["graphics_backend"], "default"); + assert_eq!(cleared["effective"]["memory_mb"], 2048); +} + +#[test] +fn invalid_values_fail_with_a_usage_error() { + let dir = TempDir::new("invalid"); + let id = write_profiles(dir.path(), "生存", "1.20.4"); + let root = dir.arg(); + for (flag, value) in [ + ("--backend", "vulkan2"), + ("--memory", "4g"), + ("--memory", "1"), + ] { + let (code, stdout) = run_cli(&[ + "instances", + "launch-args", + "--json", + "--data-dir", + &root, + &id, + flag, + value, + ]); + assert_ne!(code, 0, "{flag} {value} 应当失败：{stdout}"); + let value: Value = serde_json::from_str(&stdout).expect("输出不是 JSON"); + assert_eq!(value["error"]["code"], "usage", "{stdout}"); + } + // 失败的写入不许留下半截设置文件。 + let layout = LauncherLayout::new(dir.path().join(LAUNCHER_HOME_DIR)); + assert!( + unlucky_core::game::install::instance::read_instance_config(&layout, &id) + .expect("读") + .is_none(), + "非法补丁不该落盘" + ); +} + +#[test] +fn unknown_instance_is_a_user_error() { + let dir = TempDir::new("missing"); + let root = dir.arg(); + let (code, stdout) = run_cli(&[ + "instances", + "launch-args", + "--json", + "--data-dir", + &root, + "nope", + ]); + assert_ne!(code, 0); + let value: Value = serde_json::from_str(&stdout).expect("输出不是 JSON"); + assert_eq!(value["error"]["code"], "not_found", "{stdout}"); +} diff --git a/crates/cli/src/commands/instances.rs b/crates/cli/src/commands/instances.rs new file mode 100644 index 0000000..03020a3 --- /dev/null +++ b/crates/cli/src/commands/instances.rs @@ -0,0 +1,182 @@ +//! `instances list`：实例与已安装版本的总览。 +//! +//! 安装/登记在 [`super::install`]；这里只读（`profiles.json` + `versions/` 的存在性）。 +//! 读 `profiles.json` 的实现委托给 `core::game::install::instance`，避免 CLI 自带一份 +//! 解析逻辑（同一份文件两处解析迟早会漂移）。 +//! +//! # `--json` 里的 `loader` 字段（M124） +//! +//! 每一行实例带一个 `loader` 对象：`{"kind": <稳定 id>, "version": <版本段>}`。它是 +//! **`version_id` 的解析结果**，解析本身不在这里——[`unlucky_core::game::InstanceLoader::parse`] +//! 是全仓唯一的 id → 加载器入口（M122 收敛）。种类 → 稳定 id 的词表也不在本 crate 的代码里： +//! [`unlucky_core::game::LoaderKind::as_str`] 是生产代码里 id 的**源头表**（M126 收敛），这里 +//! 直接调它，**连翻译层都没有**——词表与 id 匹配一样，两处各算一遍就会漂（M120 的「刚装的 +//! Fabric 显示成原版」）。生产代码里唯一的逐字副本是 `cli::help` 里 `ull help instances` 的 +//! 词表行（会打印给用户），由本模块的 `help_vocabulary_tests::help_lists_every_stable_id` +//! 按 `ALL` 遍历守着。 +//! +//! ## 约定一：`loader` 恒存在，原版是 `{"kind":"vanilla","version":""}` +//! +//! 原版实例**不会**缺这个键，也**不会**是 `null`——脚本不必先判空，`kind` 恒是七个闭集值 +//! 之一（`vanilla` / `fabric` / `quilt` / `forge` / `neoforge` / `optifine` / `liteloader`）。 +//! 与 `version` 的关系：原版与「id 里没写加载器版本」的两家第三方（`1.12.2-LiteLoader`） +//! 拿到空串，不是缺失。 +//! +//! ## 约定二：`kind` 是**识别**口径，不是**安装**口径 +//! +//! 「认得出」是七个，「装得了」（`ull install --loader`）是六个——差的那一个是 `optifine`： +//! 它要跑外部 Patcher 并原地改 zip，报 `loader_unsupported`，只能由别的启动器（PCL / HMCL） +//! 装好后继承进来。`liteloader` 自 M222 起**可以**装 +//! （`install --loader liteloader`，取值表见 `ull help install`），所以 +//! `loader.kind == "liteloader"` 既可能是继承来的，也可能是 ull 自己装的。看到 +//! `loader.kind == "optifine"` 的意思是「这个实例的加载器是 OptiFine」， +//! **不是**「ull 能给你装 OptiFine」。 +//! +//! ## 约定三：`vanilla` 的含义是「id 里没有加载器痕迹」 +//! +//! [`unlucky_core::game::InstanceLoader::parse`] 只看版本 id 的字符串。把加载器信息只写进 +//! 版本 JSON、id 里一点痕迹都没有的实例（整包导入时被重命名成 `我的整合包` 那种）会**诚实地** +//! 返回 `vanilla`——这是「认不出」，不等于「一定没装加载器」。要权威结论得读 `libraries[]`， +//! 不在本命令的能力范围内。 +//! +//! ## 向后兼容 +//! +//! 这次只**加**一个键：`data.instances[]` 的其余七个键（`id` / `name` / `version_id` / +//! `version_present` / `game_dir` / `java_path` / `last_played_at`）一个没动，人类可读输出 +//! 逐字不变（`loader` 只进 JSON）。`--json` 是事实上的对外契约，字段说明同步在 +//! `ull help instances`（[`crate::cli::help::topic`]）。 + +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::{InstanceLoader, 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 { + let profiles = read_profiles(ctx)?; + let game = ctx.game(); + let installed = game.installed_versions().unwrap_or_default(); + + let mut rows: Vec = Vec::new(); + let mut body: Vec = 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, + "loader": loader_json(&profile.version_id), + })); + } + + 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 ` 登记第一个实例".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 { + 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 { + path.map(|path| path.display().to_string()) +} + +/// 版本 id → `loader` 对象（`{"kind": …, "version": …}`）。 +/// +/// 解析走 [`InstanceLoader::parse`]（全仓唯一入口）；种类 → 稳定 id 走 +/// [`unlucky_core::game::LoaderKind::as_str`]（词表的源头，M126）。这里既**不写 id +/// 匹配**，也**不写词表**：词表的源头只在 core（副本见模块文档）。原版同样给出对象 +/// （`kind = vanilla`、`version = ""`），不缺键、不为 `null`——见模块文档的「约定一」。 +fn loader_json(version_id: &str) -> Value { + let parsed = InstanceLoader::parse(version_id); + json!({ + "kind": parsed.kind.as_str(), + "version": parsed.version, + }) +} + +pub mod adopt; +mod adopt_shared; +pub mod scan; + +#[cfg(test)] +mod tests; + +/// `ull help instances` 的词表行是**对外文档契约**，不许成为第二个说假话的地方（r2）。 +/// +/// 单列在这里而不是塞进 `instances/tests.rs`：那几个断言钉的是本模块文档承诺的词表，与命令 +/// 行为无关（`tests.rs` 的职责是「跑真入口看输出」），而且这样 help 的契约与被承诺的那段 +/// 文档就在同一个文件里。 +#[cfg(test)] +mod help_vocabulary_tests { + use unlucky_core::game::LoaderKind; + + /// help 的词表必须覆盖**每一支**稳定 id（含原版与两家只继承、不安装的）。 + /// + /// 抓得住：help 的词表行被改字或删项（`neoforge` → `neo_forge`）；**新增一家加载器而忘了 + /// 更新 help**——下面按 [`LoaderKind::ALL`] 遍历而不是手抄七项，所以新分支漏写必红。 + /// 抓不住：措辞与排版（只做子串断言）；「kind 是识别口径不是安装口径」那段语义说明是否 + /// 仍然准确，只能靠人读。 + #[test] + fn help_lists_every_stable_id() { + let topic = crate::cli::help::topic("instances").expect("help instances 存在"); + for kind in LoaderKind::ALL { + assert!( + topic.contains(kind.as_str()), + "help instances 的词表行漏了 `{}`：\n{topic}", + kind.as_str() + ); + } + } +} diff --git a/crates/cli/src/commands/instances/adopt.rs b/crates/cli/src/commands/instances/adopt.rs new file mode 100644 index 0000000..c6fec71 --- /dev/null +++ b/crates/cli/src/commands/instances/adopt.rs @@ -0,0 +1,118 @@ +//! `ull instances adopt`：把盘上已有的版本登记成实例（M221）。 +//! +//! **只读外部、只写自己**：写盘面只有 `<数据根>/.ULL/config/` 下的两份配置（+ 选中缺省运行目录时 +//! 建那个空目录），`versions/` `libraries/` `assets/` 一个字节都不写。判据、落点与话术全在 +//! [`unlucky_core::game::adopt`]；本模块只做「参数 → core 调用 → 人读/JSON 两条输出」。 +//! +//! `--dry-run` 走 `adopt::plan`（零写盘），所以「先看一眼」不会改任何东西，也不会建目录。 + +use serde_json::{json, Value}; +use unlucky_core::game::adopt::{self, AdoptRequest}; +use unlucky_core::game::GameLayout; +use unlucky_core::launch::time::{format_rfc3339_millis, now}; +use unlucky_core::platform::layout::LauncherLayout; + +use crate::cli::model::InstancesAdoptArgs; +use crate::context::Ctx; +use crate::error::CliError; +use crate::output::Report; + +use super::adopt_shared::{candidate_json, map_error}; + +/// `ull instances adopt [--name N] [--isolation …] [--game-dir DIR] [--dry-run]`。 +/// +/// # Errors +/// +/// 版本不在盘上 / 候选不合格 / 名字冲突 / 运行目录不可用 / 读配置失败，全部由 +/// [`unlucky_core::game::adopt::AdoptError`] 映射成稳定错误码（`adopt_*`）。 +pub fn run(ctx: &Ctx, args: &InstancesAdoptArgs) -> Result { + let request = AdoptRequest { + version_id: args.version_id.clone(), + name: args.name.clone(), + target: args.target.clone(), + created_at: Some(format_rfc3339_millis(now())), + }; + let (game, launcher) = (ctx.game(), ctx.layout()); + if args.dry_run { + return dry_run(&game, &launcher, &request); + } + let outcome = adopt::adopt(&game, &launcher, &request).map_err(map_error)?; + // 人读行先拼（只借用），再把字段移进 JSON（两条出口的内容同源、顺序不影响事实）。 + let mut human = vec![format!( + "已登记实例 `{}`（id {}）→ 版本 {}", + outcome.name, outcome.instance_id, outcome.version_id + )]; + human.push(format!( + " 隔离档 {}（运行目录来源 {}），运行目录 {}", + outcome.isolation.as_str(), + outcome.target.as_str(), + outcome.run_dir.display() + )); + human.push(format!(" 实例设置 {}", outcome.config_path.display())); + if outcome.dir_created { + human.push(" 已新建该运行目录（空目录；玩家数据由游戏自己往里写）".to_string()); + } + human.push( + " 只写了本启动器的配置：versions/ libraries/ assets/ 一个字节都没动（不搬文件）" + .to_string(), + ); + human.extend(outcome.notes.iter().map(|note| format!(" 提示：{note}"))); + let version_id = outcome.version_id.clone(); + let data = json!({ + "dry_run": false, + "version_id": version_id, + "instance": json!({ + "id": outcome.instance_id, + "name": outcome.name, + "version_id": version_id, + "isolation": outcome.isolation.as_str(), + "run_dir": outcome.run_dir.display().to_string(), + "run_dir_source": outcome.target.as_str(), + "config_path": outcome.config_path.display().to_string(), + "created": outcome.created, + "dir_created": outcome.dir_created, + }), + "notes": outcome.notes, + }); + Ok(Report::new(data, human)) +} + +/// `--dry-run`：只算落点与判据，不写盘（连缺省运行目录都不建）。 +fn dry_run( + game: &GameLayout, + launcher: &LauncherLayout, + request: &AdoptRequest, +) -> Result { + let plan = adopt::plan(game, launcher, request).map_err(map_error)?; + let mut human = vec![format!( + "检查通过：版本 {} 可登记（--dry-run：没有写任何文件）", + plan.candidate.version_id + )]; + human.push(format!( + " 实例名 {}，隔离档 {}（运行目录来源 {}）", + plan.name, + plan.isolation.as_str(), + plan.target.as_str() + )); + human.push(format!(" 运行目录 {}", plan.run_dir.display())); + human.extend(plan.notes.iter().map(|note| format!(" 提示：{note}"))); + let version_id = plan.candidate.version_id.clone(); + let data = json!({ + "dry_run": true, + "version_id": version_id, + "candidate": candidate_json(&plan.candidate), + "instance": json!({ + "id": Value::Null, + "name": plan.name, + "version_id": version_id, + "isolation": plan.isolation.as_str(), + "run_dir": plan.run_dir.display().to_string(), + "run_dir_source": plan.target.as_str(), + "config_path": Value::Null, + "created": false, + "dir_created": false, + }), + "notes": plan.notes, + }); + Ok(Report::new(data, human)) +} diff --git a/crates/cli/src/commands/instances/adopt_shared.rs b/crates/cli/src/commands/instances/adopt_shared.rs new file mode 100644 index 0000000..8ff98f5 --- /dev/null +++ b/crates/cli/src/commands/instances/adopt_shared.rs @@ -0,0 +1,84 @@ +//! `instances scan` / `instances adopt` 共用的 JSON 与错误投影。 +//! +//! 两条命令输出同一种候选形状（`candidate` 对象），错误也走同一份映射——分两份写迟早漂。 + +use serde_json::{json, Value}; +use unlucky_core::game::adopt::{AdoptCandidate, AdoptError, AdoptProblem}; + +use crate::error::CliError; + +/// 候选 → `--json` 里的 `candidate` 对象。 +pub(super) fn candidate_json(candidate: &AdoptCandidate) -> Value { + json!({ + "version_id": candidate.version_id, + "version_dir": candidate.version_dir.display().to_string(), + "manifest_path": candidate.manifest_path.display().to_string(), + "jar_present": candidate.jar_present, + "manifest_id": candidate.manifest_id, + "inherits": candidate.inherits, + "registered": candidate.registered.iter().map(|item| json!({ + "id": item.id, + "name": item.name, + })).collect::>(), + "adoptable": candidate.adoptable(), + "problems": problems_json(&candidate.problems), + }) +} + +/// 问题清单 → 结构化数组（`code` 稳定、`message` 人读）。 +pub(super) fn problems_json(problems: &[AdoptProblem]) -> Value { + Value::Array( + problems + .iter() + .map(|problem| { + json!({ + "code": problem.code(), + "message": problem.to_string(), + }) + }) + .collect(), + ) +} + +/// `AdoptError` → CLI 错误：稳定 code + 逐条问题进 `detail`（脚本不必解析散文）。 +pub(super) fn map_error(error: AdoptError) -> CliError { + let code = error.code(); + let message = error.to_string(); + let cli = CliError::user(code, message); + let hint = match &error { + AdoptError::DuplicateName { .. } => { + Some("换个展示名：%prog% instances adopt --name <新名字>") + } + AdoptError::NotAdoptable { .. } => Some( + "这些版本要么清单坏了、要么缺父版本、要么越界：先在原来的启动器里把它修好，\ + 或 `%prog% install ` 让本启动器自己装一份", + ), + AdoptError::AlreadyRegistered { .. } => { + Some("用 `%prog% instances list` 看已有实例；要第二个实例请换 --name") + } + AdoptError::TargetNotEmpty { .. } => { + Some("换一个名字（缺省目录按名字派生），或用 --isolation custom --game-dir <空目录>") + } + AdoptError::UnknownVersion { .. } => Some("先看有哪些可用：%prog% instances scan"), + AdoptError::NoFreeRunDir { .. } => Some( + "换一个 --name（缺省目录按名字派生），或用 --isolation custom --game-dir <空目录>", + ), + AdoptError::WriteSurfaceInGameTree { .. } => Some( + "数据目录（.ULL / --data-dir）和游戏树重叠了：把它指到游戏树之外的目录再登记 （整体迁移到别处是允许的，默认登记不会把实例数据写进别人的 .minecraft）", + ), + AdoptError::ConfigSurfaceUnsafe { .. } => Some( + "数据根里的 config/ 或 config/instances/ 被链到别处了：先把它恢复成真实目录再登记 （整体迁移请把整个 .ULL 目录一起搬走，别只链其中一层）", + ), + AdoptError::VersionsDirUnreadable { .. } => Some( + "游戏根/versions 入口存在但读不出来：检查它是不是断链的符号链接/目录联接， 或把它指回真实目录后再扫", + ), + _ => None, + }; + let cli = match hint { + Some(hint) => cli.with_hint(hint), + None => cli, + }; + cli.with_detail(json!({ + "problems": problems_json(error.problems()), + })) +} diff --git a/crates/cli/src/commands/instances/scan.rs b/crates/cli/src/commands/instances/scan.rs new file mode 100644 index 0000000..dba0cf1 --- /dev/null +++ b/crates/cli/src/commands/instances/scan.rs @@ -0,0 +1,91 @@ +//! `ull instances scan`：列出当前游戏根 `versions/` 里**已经铺好**的版本，逐项说清能不能登记（M221）。 +//! +//! 只读：不写任何文件、不改任何 mtime。用途是「我盘上已经有别的启动器装好的版本，看看 ULL 认不认」， +//! 以及 `instances adopt` 的前置检查（同一套判据，见 [`unlucky_core::game::adopt::scan`]）。 + +use serde_json::json; +use unlucky_core::game::adopt; + +use crate::context::Ctx; +use crate::error::CliError; +use crate::output::Report; + +use super::adopt_shared::candidate_json; + +/// `ull instances scan`。 +/// +/// # Errors +/// +/// `versions/` 或 `profiles.json` 读不了时返回用户错误（**不降级成空列表**）。 +pub fn run(ctx: &Ctx) -> Result { + let scan = adopt::scan(&ctx.game(), &ctx.layout()).map_err(super::adopt_shared::map_error)?; + let ready = scan + .candidates + .iter() + .filter(|candidate| candidate.adoptable()) + .count(); + let registered = scan + .candidates + .iter() + .filter(|candidate| candidate.is_registered()) + .count(); + + let candidates: Vec = scan.candidates.iter().map(candidate_json).collect(); + let data = json!({ + "game_root": ctx.data.game_home.display().to_string(), + "versions_dir": scan.versions_dir.display().to_string(), + "counts": { + "total": scan.candidates.len(), + "adoptable": ready, + "registered": registered, + }, + "candidates": candidates, + }); + + let mut human = vec![format!( + "游戏根 {}：versions/ 里 {} 个版本，{} 个可登记", + scan.versions_dir.display(), + scan.candidates.len(), + ready + )]; + if scan.candidates.is_empty() { + human.push( + " （空）这个游戏根下还没有任何版本；`%prog% install ` 可以自己装一份" + .to_string(), + ); + } + for candidate in &scan.candidates { + if candidate.adoptable() { + let state = if candidate.is_registered() { + "已登记" + } else { + "可登记" + }; + human.push(format!( + " ✓ {} [{state}]{}", + candidate.version_id, + chain_suffix(candidate) + )); + } else { + human.push(format!(" ✗ {}", candidate.version_id)); + for problem in &candidate.problems { + human.push(format!(" 原因[{0}] {problem}", problem.code())); + } + } + } + if ready > 0 { + human.push( + "登记一个：%prog% instances adopt （缺省落 ULL 数据区的独立运行目录）" + .to_string(), + ); + } + Ok(Report::new(data, human)) +} + +/// 人读行尾的父链提示（`1.12.2-forge-…` 后面标出它继承的是谁）。 +fn chain_suffix(candidate: &unlucky_core::game::AdoptCandidate) -> String { + match candidate.inherits.len() { + 0 | 1 => String::new(), + _ => format!(" 继承 {}", candidate.inherits[1..].join(" -> ")), + } +} diff --git a/crates/cli/src/commands/instances/tests.rs b/crates/cli/src/commands/instances/tests.rs new file mode 100644 index 0000000..71d1c67 --- /dev/null +++ b/crates/cli/src/commands/instances/tests.rs @@ -0,0 +1,251 @@ +//! [`super`] 的单测：`instances list --json` 的 `loader` 字段 + 人类可读输出不变。 +//! +//! 走的是真入口 [`crate::run`]（`--data-dir` 钉在临时目录里），断言的是**用户/脚本拿到的那份 +//! 输出**，不是内部函数返回值——这样 JSON 信封（`ok` / `data` / `warnings`）与人类行都在射程内。 +//! 解析端本身（id → 加载器）的真值表在 `core::game::loader` 的测试里，这里只验「CLI 有没有把它 +//! 如实搬到输出面上」，不重复抄一份 id 真值。 + +use std::path::{Path, PathBuf}; +use std::sync::atomic::{AtomicU64, Ordering}; +use std::time::{SystemTime, UNIX_EPOCH}; + +use serde_json::Value; + +/// 一次性临时目录（`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-instances-test-{tag}-{}-{seq}-{nanos}", + std::process::id() + )); + std::fs::create_dir_all(&path).expect("建临时目录"); + Self(path) + } + + fn path(&self) -> &Path { + &self.0 + } + + fn arg(&self) -> String { + self.0.display().to_string() + } +} + +impl Drop for TempDir { + fn drop(&mut self) { + let _ = std::fs::remove_dir_all(&self.0); + } +} + +/// 写 `.ULL/config/profiles.json`（实例名 → 版本 id；id 用 UUID 形状，互不重复）。 +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 = 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"); +} + +/// 跑一次 CLI，返回（退出码, stdout, stderr）。 +fn run_cli(args: &[&str]) -> (i32, String, String) { + let owned: Vec = args.iter().map(|arg| (*arg).to_string()).collect(); + let mut out: Vec = Vec::new(); + let mut err: Vec = Vec::new(); + let code = crate::run(&owned, &mut out, &mut err); + ( + code, + String::from_utf8_lossy(&out).into_owned(), + String::from_utf8_lossy(&err).into_owned(), + ) +} + +/// 跑 `instances list --json` 并返回 `data.instances` 数组。 +fn list_instances(dir: &TempDir) -> Vec { + let (code, stdout, stderr) = + run_cli(&["instances", "list", "--json", "--data-dir", &dir.arg()]); + assert_eq!(code, 0, "stderr: {stderr}"); + let value: Value = serde_json::from_str(&stdout).expect("输出不是 JSON"); + assert_eq!(value["ok"], true, "{stdout}"); + value["data"]["instances"] + .as_array() + .expect("instances 数组") + .clone() +} + +/// 四家自家 id + 原版 + 两家第三方前缀：JSON 里的 `loader.kind` / `loader.version`。 +/// +/// 样本与 `core::game::loader` 的真值表**同源**（自家样本取自 `LoaderKind::version_id` 的 +/// `--` 口径，第三方样本取自 PCL 的真实 id 形状），但断言只钉在输出面上。 +/// +/// 抓得住：CLI 没调 `InstanceLoader::parse`（自己另算一遍或干脆不派生）；种类 → 稳定 id 的 +/// 词表被改（`neoforge` 写成 `neo_forge`）；版本段被截断/连标记一起搬；`optifine` / +/// `liteloader` 被漏成 `vanilla`（这两家的 id 是第三方前缀形状，没有 `--` 段， +/// 只按自家四种形状解析的实现在这两行会红）。 +/// 抓不住：解析规则本身退化（那是 core 的单测射程）；`version_id` 大小写/空格的边角； +/// 真实实例里 `libraries[]` 与 id 不一致的情形（本命令只看 id）。 +#[test] +fn json_rows_expose_loader_kind_and_version() { + let dir = TempDir::new("loader"); + let cases: [(&str, &str, &str); 7] = [ + ("Fabric 实例", "1.20.4-fabric-0.16.5", "fabric"), + ("Quilt 实例", "1.20.4-quilt-0.27.0", "quilt"), + ("Forge 实例", "1.20.1-forge-47.2.0", "forge"), + ("NeoForge 实例", "1.21.1-neoforge-21.1.80", "neoforge"), + ("原版实例", "1.20.1", "vanilla"), + ("OptiFine 实例", "1.13.2-OptiFine_HD_U_E6", "optifine"), + ("LiteLoader 实例", "1.12.2-LiteLoader", "liteloader"), + ]; + let expected_versions = ["0.16.5", "0.27.0", "47.2.0", "21.1.80", "", "HD_U_E6", ""]; + let profiles: Vec<(&str, &str)> = cases + .iter() + .map(|(name, version_id, _)| (*name, *version_id)) + .collect(); + write_profiles(dir.path(), &profiles); + + let rows = list_instances(&dir); + assert_eq!(rows.len(), cases.len(), "{rows:?}"); + for (index, (name, version_id, kind)) in cases.iter().enumerate() { + let row = &rows[index]; + assert_eq!(row["name"], *name, "{row}"); + assert_eq!(row["version_id"], *version_id, "{row}"); + assert_eq!( + row["loader"]["kind"], *kind, + "`{version_id}` 的 loader.kind 应是 `{kind}`：{row}" + ); + assert_eq!( + row["loader"]["version"], expected_versions[index], + "`{version_id}` 的 loader.version：{row}" + ); + } +} + +/// 反向锚：原版的 `loader` 是 `{"kind":"vanilla","version":""}`，**不缺键、不为 `null`**。 +/// +/// 这条钉住的是模块文档里的「约定一」：脚本可以无条件读 `row.loader.kind`。顺带把「原版 id +/// 不许被认成加载器」也验一遍——反面是 core 那边 `plain_version_ids_stay_vanilla` 的职责， +/// 这里验的是它有没有被 CLI 的翻译层改坏（例如把空版本当成「没解析出东西」而塞 `null`）。 +/// +/// 抓得住：有人把原版改回「省略 `loader` 键」或「给 `null`」（两种都会让 `row["loader"]["kind"]` +/// 变成 `null`）；`loader` 对象里被塞进多余的键（下面的键集合断言）。 +/// 抓不住：`vanilla` 与「id 里没痕迹的整合包」的区分——**用户视角两者本来就不可区分**， +/// 见模块文档「约定三」，只能靠读 `libraries[]`。 +#[test] +fn vanilla_rows_keep_a_loader_object_never_null() { + let dir = TempDir::new("vanilla"); + write_profiles( + dir.path(), + &[ + ("原版", "1.20.1"), + ("快照", "23w45a"), + ("预发布", "1.20.4-pre1"), + ], + ); + + let rows = list_instances(&dir); + assert_eq!(rows.len(), 3, "{rows:?}"); + for row in &rows { + let loader = row.get("loader").expect("原版也必须带 loader 键"); + assert!(!loader.is_null(), "loader 不许是 null：{row}"); + assert_eq!(loader["kind"], "vanilla", "{row}"); + assert_eq!(loader["version"], "", "{row}"); + let mut keys: Vec<&str> = loader + .as_object() + .expect("loader 是对象") + .keys() + .map(String::as_str) + .collect(); + keys.sort_unstable(); + assert_eq!(keys, ["kind", "version"], "loader 只有这两个键：{row}"); + } +} + +/// 向后兼容：人类可读输出逐字不变，`--json` 的旧字段一个没少。 +/// +/// 抓得住：把 `loader` 顺手塞进人类行（`instances list` 的人读格式被改）；旧七个 JSON 键 +/// 被删或改名（`last_played_at` 这类「看着没用」的最容易被顺手清掉）。 +/// 抓不住：人类行的**空白/顺序**之外的美化（例如多打一行汇总）——下面按整段逐行比对， +/// 所以大部分改动会红，但只在两行之间加空行这类不涉及内容的变化仍可能被容忍（本测试用的是 +/// 定长片段列表，多出来的行一定红；只有同位置改写才需要人看）。 +#[test] +fn human_output_and_old_json_fields_are_unchanged() { + let dir = TempDir::new("compat"); + write_profiles(dir.path(), &[("生存服", "1.13.2-OptiFine_HD_U_E6")]); + + let (code, stdout, stderr) = run_cli(&["instances", "list", "--data-dir", &dir.arg()]); + assert_eq!(code, 0, "stderr: {stderr}"); + let launcher_home = dir.path().join(".ULL"); + let expected = format!( + "实例 1 个（数据根 {}）\n \ + 生存服 [1.13.2-OptiFine_HD_U_E6] 载荷缺失 \ + 11111111-2222-4333-8444-000000000001\n\ + 已安装版本: （无）\n", + launcher_home.display() + ); + assert_eq!(stdout, expected, "人类可读输出应逐字不变"); + assert!( + !stdout.contains("loader") && !stdout.contains("OptiFine 版本"), + "人读输出里不该出现加载器派生列：{stdout}" + ); + + let rows = list_instances(&dir); + let row = &rows[0]; + for key in [ + "id", + "name", + "version_id", + "version_present", + "game_dir", + "java_path", + "last_played_at", + ] { + assert!(row.get(key).is_some(), "旧键 `{key}` 不许删：{row}"); + } + // 顺手钉住新键的值，避免「旧键都在、新键是空对象」这种假绿。 + assert_eq!(row["loader"]["kind"], "optifine", "{row}"); +} + +/// `--json` 是事实上的对外契约：字段约定必须能在 `ull help instances` 里读到。 +/// +/// 抓得住：`loader` 字段被加进输出、契约说明被从 help 里删掉（只留在源码注释里等于没写—— +/// 用户读不到）；「识别口径 ≠ 安装口径」这条警告被顺手删掉（`optifine` 装不了、`liteloader` +/// 自 M222 起能装，两件事都只在 help 里说，JSON 契约里看不出来）。 +/// 抓不住：措辞本身——下面只按键词（`loader` / `kind` / `version` / `vanilla` / `optifine` / +/// `install --loader`）检查，换个说法仍会绿；help 的排版正确性也不在射程内。 +#[test] +fn help_documents_the_loader_field_contract() { + let topic = crate::cli::help::topic("instances").expect("help instances"); + for needle in [ + "loader", + "kind", + "version", + "vanilla", + "optifine", + "install --loader", + ] { + assert!( + topic.contains(needle), + "help instances 缺 `{needle}`：\n{topic}" + ); + } +} diff --git a/crates/cli/src/commands/java.rs b/crates/cli/src/commands/java.rs new file mode 100644 index 0000000..0608313 --- /dev/null +++ b/crates/cli/src/commands/java.rs @@ -0,0 +1,346 @@ +//! 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::{DownloadEngine, 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 { + 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 { + 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 = 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::>(), + "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::>(), + }); + let mut human = vec![format!("Java {} 个", candidates.len())]; + if candidates.is_empty() { + human.push( + "（没找到可用 Java）用 `%prog% java install 21` 装一个，或设 JAVA_HOME / `%prog% launch --java `" + .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 [--vendor X]`：回退链查版本 → 下载 → 解压 → `java -version` 验证。 +/// +/// 幂等：同一个归档装过就直接复用（不联网、不解压）。下载走 `core::download` 引擎， +/// 国内环境按 D7 的地区策略优先院校/国内镜像。 +/// +/// # Errors +/// +/// 大版本不合法、平台无产物、所有发行版都失败（网络/校验/解压/跑不起来）时返回用户错误。 +pub fn install(ctx: &Ctx, major: u32, vendor: Option) -> Result { + 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, + pub(crate) priority: Vec, +} + +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 = 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::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 { + if runtime.origin != JavaOrigin::Managed { + return None; + } + runtime + .binary + .parent() + .and_then(Path::parent) + .map(|dir| dir.display().to_string()) +} + +/// 建下载引擎：装配参数来自设置（并发 / 重试 / gh-proxy，读数口径见 [`crate::download`]）， +/// 引擎本体与 `install` / `pack` 共用同一个（core 按缓存根共享）。 +pub(crate) fn build_engine(ctx: &Ctx) -> Arc { + crate::download::engine(ctx) +} + +/// 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 { + 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..558358a --- /dev/null +++ b/crates/cli/src/commands/java_launch.rs @@ -0,0 +1,252 @@ +//! 启动期的 Java 解析（`ull launch` 用）：实例覆盖 > 托管匹配 > 系统。 +//! +//! 从 `commands/java.rs` 拆出来（那边还要放 list/install/vendors，超 400 行硬上限）。 +//! 这里的职责是三条：①按 D13 的优先链挑一个 Java；②把选中的那个**钉成路径**交给装配 +//! （D4：校验过的就是启动用的，不许装配期再重选一遍）；③把结果整理成 `--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` 的**钉死路径**：D4 校验过的那个 java。 + /// + /// 五个来源一视同仁（M220 修的就是这条）：以前只有 `managed` 会钉住， + /// `JAVA_HOME` / `PATH` / 标准安装位置的命中会被 `snapshot::prepare` 的 + /// `selection()` 按环境**再挑一遍**——于是 D4 判过的那个不是真启动的那个。 + /// `None` 只可能是「一个候选都没探到」，此时只能让 `snapshot::prepare` 兜底。 + pub override_path: Option, + /// 实际选中的运行时。 + pub runtime: Option, + /// 目标版本对 Java 的要求。 + pub requirement: JavaRequirement, + /// 不符说明（`None` = 满足要求，或压根没探测到 Java）。 + /// + /// `--dry-run` 只把它当告警打出来；真启动时先过 [`unlucky_core::game::java::select::decide`]： + /// 不符且没人显式指定 Java 就直接拦下、不 spawn（D4）。 + pub mismatch: Option, +} + +impl LaunchJava { + /// `--json` 的 `java` 块（app 层 GUI 弹窗 P1 后直接吃这份数据）。 + /// + /// `launched` 是装配之后**真正要执行的** java 路径（`plan.request.java.binary`）。 + /// 它作为参数传进来而不是在这里自己算：读的人不该去猜「`binary` 是不是真跑的那个」， + /// 所以两个事实并排给出（`binary` = D4 校验过的，`launch_binary` = 装配落地的）。 + #[must_use] + pub fn to_json(&self, launched: &Path) -> Value { + let runtime = self.runtime.as_ref(); + json!({ + "binary": runtime.map(|runtime| runtime.binary.display().to_string()), + "launch_binary": launched.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 与真启动都输出）。 + /// + /// `launched` 是装配之后真正要执行的 java 路径，用来兜一条「钉路径失效」的自检。 + /// + /// 三类：①用户指定的 Java 探测不出来（路径写错了，静默退回默认版本会很难查）； + /// ②Java 与版本要求不符——`--dry-run` 到此为止只提示；真启动会先过 `select::decide`， + /// 只有「用户自己指定了 Java」时才会带着这条告警继续起（D4）； + /// ③装配落地的不是 D4 校验过的那个（钉路径没生效，M220 的回归闸）。 + #[must_use] + pub fn warnings(&self, launched: &Path) -> Vec { + 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()); + } + if let Some(unpinned) = self.pin_mismatch(launched) { + warnings.push(unpinned); + } + warnings + } + + /// 装配落地的 java 与 D4 校验过的那个是否一致（不一致要当场喊出来）。 + fn pin_mismatch(&self, launched: &Path) -> Option { + match (&self.runtime, self.override_path.as_deref()) { + (Some(_), Some(validated)) if validated == launched => None, + (Some(_), Some(validated)) => Some(format!( + "装配用的 Java（{}）与校验过的（{}）不一致：这次启动没有走 D4 判过的那个", + launched.display(), + validated.display() + )), + // 选出了一个 java 却没钉住路径 ⇒ 装配期会按环境再挑一遍，D4 判的就不是真跑的那个。 + (Some(runtime), None) => Some(format!( + "选中了 {}（{}）却没钉住路径，装配期按环境重选成了 {}：这一份没有经过 D4 校验", + runtime.binary.display(), + runtime.origin.as_str(), + launched.display() + )), + (None, _) => Some(format!( + "没探测到任何 Java，装配期按环境兜底用了 {}（这一份没有经过 D4 校验）", + launched.display() + )), + } + } + + /// 人读一行：Java 版本 + 来源 + **具体可执行文件** + 该版本的要求。 + /// + /// 路径必须写出来（M220）：五个来源都钉路径之后，「用的是哪个 java」不能再靠猜 + /// ——同机装两个 21 的时候，只有路径能把两个 Jar 头日志对上的问题说清。 + #[must_use] + pub fn summary(&self) -> String { + let (version, origin) = match &self.runtime { + Some(runtime) => ( + runtime + .major + .map_or_else(|| "未知".to_string(), |major| major.to_string()), + format!("{} · {}", runtime.origin.as_str(), runtime.binary.display()), + ), + None => ("未知".to_string(), "未探测到".to_string()), + }; + format!( + "Java {version}（{origin}）· 该版本要求 {}", + self.requirement.describe() + ) + } +} + +/// 解析启动用的 Java：实例覆盖 > 托管匹配 > 系统。 +/// +/// 候选收集有代价（托管扫盘、`java -version` 子进程），所以顺序是「先便宜的、不满足才扫盘」： +/// 托管 + `PATH`/`JAVA_HOME` 不满足要求时，才把标准安装位置（Program Files 系、 +/// 官方启动器的 `runtime/`、注册表）并进来重挑一次。 +#[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 Some(path) = explicit else { + // 托管区可能不止一个根（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 planned = plan_java(&candidates, &requirement); + if planned.mismatch.is_none() { + return planned; + } + candidates.extend(java::standard_candidates()); + return plan_java(&java::discover::dedupe(candidates), &requirement); + }; + // 用户自己指定了 Java：只探测这一个，不参与打分（D13：明确的选择不推翻）。 + plan_java(&[java::probe(path, JavaOrigin::Instance)], &requirement) +} + +/// 纯装配：从候选里挑一个，并把它**钉成路径**（候选可注入，测试不必真装 JDK）。 +#[must_use] +pub fn plan_java(candidates: &[JavaRuntime], requirement: &JavaRequirement) -> LaunchJava { + let resolution = java::resolve(candidates, requirement); + // D4：`override_path` 就是 D4 校验过的那个运行时——五种来源一个口径， + // 不分「托管要钉、环境变量可以放它再挑一次」。 + let override_path = resolution + .runtime + .as_ref() + .map(|runtime| runtime.binary.clone()); + LaunchJava { + override_path, + runtime: resolution.runtime, + requirement: requirement.clone(), + mismatch: resolution.mismatch, + } +} + +#[cfg(test)] +mod tests { + use std::path::PathBuf; + + use unlucky_core::game::java::RequirementSource; + + use super::{plan_java, JavaOrigin, JavaRequirement, JavaRuntime}; + + fn runtime(major: u32, origin: JavaOrigin) -> JavaRuntime { + JavaRuntime { + binary: PathBuf::from(format!("/jdks/{}/{major}/bin/java", origin.as_str())), + origin, + version: Some(format!("openjdk version \"{major}.0.1\"")), + major: Some(major), + bits: 64, + vendor: None, + } + } + + /// 五种来源都必须把选中项的路径钉住（M220 的核心不变量）。 + /// + /// 抓得住：退回「只有 `managed` 才钉路径」——那时 `JAVA_HOME` / `PATH` / `system` / + /// `instance` 四种来源的 `override_path` 会变成 `None`，装配期按环境再挑一遍， + /// D4 校验过的那个就不是真启动的那个了。 + #[test] + fn every_origin_pins_the_selected_binary() { + for origin in [ + JavaOrigin::Instance, + JavaOrigin::Managed, + JavaOrigin::JavaHome, + JavaOrigin::Path, + JavaOrigin::System, + ] { + let chosen = runtime(21, origin); + let planned = plan_java( + std::slice::from_ref(&chosen), + &JavaRequirement::new(17, None, RequirementSource::Table), + ); + assert_eq!(planned.runtime.as_ref(), Some(&chosen), "{origin:?}"); + assert_eq!( + planned.override_path, + Some(chosen.binary.clone()), + "{origin:?} 的命中必须钉成路径，不能留给装配期重选" + ); + } + } + + /// 钉的是**选中那个**，不是候选里第一个/来源排名最高的那个。 + /// + /// 抓得住：把 `override_path` 写成 `candidates.first()`，或者钉住一个与 + /// `runtime` 不同的运行时（D4 判 A 却启动 B）。 + #[test] + fn the_pinned_binary_is_the_one_that_satisfies_the_requirement() { + let legacy = runtime(8, JavaOrigin::JavaHome); + let modern = runtime(21, JavaOrigin::Managed); + let planned = plan_java( + &[modern, legacy.clone()], + &JavaRequirement::new(8, Some(8), RequirementSource::Table), + ); + assert_eq!(planned.runtime.map(|runtime| runtime.major), Some(Some(8))); + assert_eq!(planned.override_path, Some(legacy.binary)); + assert!(planned.mismatch.is_none()); + } + + /// 一个候选都没有时不编造路径（`None` = 让装配期按环境兜底），也不误报不符。 + #[test] + fn no_candidate_pins_nothing() { + let planned = plan_java( + &[], + &JavaRequirement::new(21, None, RequirementSource::Table), + ); + assert!(planned.runtime.is_none()); + assert_eq!(planned.override_path, None); + assert!(planned.mismatch.is_none()); + } +} diff --git a/crates/cli/src/commands/java_vendors.rs b/crates/cli/src/commands/java_vendors.rs new file mode 100644 index 0000000..82bbec9 --- /dev/null +++ b/crates/cli/src/commands/java_vendors.rs @@ -0,0 +1,149 @@ +//! `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::{termux, 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 { + let settings = JavaSettings::load(ctx); + let domestic = region_profile(ctx).is_domestic(); + let mut order = vendor::order(&settings.priority, domestic); + // Termux 上系统包是一条真实可用的发行版：不进默认回退序，但展示时要让人看见。 + if termux::available() && !order.contains(&JdkVendor::Termux) { + order.insert(0, JdkVendor::Termux); + } + let table = MirrorTable::builtin(); + let rows: Vec = 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 = 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(), + JdkVendor::Termux => termux::MIRRORS + .iter() + .map(|mirror| format!("{mirror}（系统包：pkg install openjdk-）")) + .collect(), + }; + json!({ + "rank": index + 1, + "vendor": item.id(), + "display": item.display(), + "majors": item.hint_majors(), + "supported": (8..=99u32).filter(|major| item.supports(*major)).collect::>(), + "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::>() + .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..157fd25 --- /dev/null +++ b/crates/cli/src/commands/launch.rs @@ -0,0 +1,298 @@ +//! `ull launch [--dry-run]`（D18：`--dry-run` 只打印组装后的命令行）。 +//! +//! D20 的隔离档位在**这里**落成 `--gameDir`：本命令按覆盖链 +//! （临时参数 > 实例 `isolation` > 全局 `instances.mode`）派生出运行目录， +//! 交给 [`snapshot::prepare`] 装进 `LaunchDirs.game_dir`（占位符 `${game_directory}` +//! 与子进程 CWD 都取这个值），并在启动时做一次切换检测（只探测、不迁移）。 + +use serde_json::json; +use unlucky_core::game::java::select; +use unlucky_core::game::ProfileList; +use unlucky_core::launch::{LaunchError, Launcher, LauncherConfig}; + +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}; + +// 隔离档位（D20）的派生与切换检测搬到独立模块：本文件贴着 400 行红线（M220）。 +// 用 `#[path]` 而不是在 `commands/mod.rs` 里登记，是为了这次改动只碰本文件 + 新文件。 +#[path = "launch_isolation.rs"] +mod launch_isolation; + +use launch_isolation::resolve_isolation; + +/// 执行 `launch`。 +/// +/// # Errors +/// +/// 实例/版本不存在、版本 JSON 不可用、命令行组装失败、进程起不来时返回用户错误。 +pub fn run(ctx: &Ctx, args: &LaunchArgs) -> Result { + 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, + ) + } + }; + + // D13 选 Java：命中就把路径钉死交给 `snapshot::prepare`（五个来源一个口径，M220）。 + // 顺序是有意的（M220 / nit3）：D4 的拦截排在身份解析**之前**——解析身份会联网刷新微软轨 + // 令牌（有副作用，还会顺手改写凭据），而 D4 判下来必被拦的启动根本用不到身份。 + // 这一步只看版本 id 与「谁指定了 Java」，不依赖身份解析的结果，所以拆得开。 + // + // 「谁指定了 Java」必须连实例设置/全局设置里的 `javaPath` 一起算：装配期 + // （`snapshot::prepare` 的 `effective.java_path`）用的就是那一份，D4 校验的却只认 + // `--java` / 档案 `javaPath` 的话，用户配过的 JDK 会被自动挑的结果顶掉。 + let configured_java = super::instance_launch::resolved(ctx, &input.instance_id).java_path; + let chosen_java = input.java.clone().or(configured_java); + unlucky_core::launch::launcher_log::set_dir(ctx.logs_dir()); + let explicit_java = chosen_java.is_some(); + let java = super::java::resolve_for_launch(ctx, &input.version_id, chosen_java.as_deref()); + if !args.dry_run { + if let Some(mismatch) = select::decide(java.mismatch, explicit_java).block() { + unlucky_core::launch::launcher_log::record("launch", &mismatch.message()); + // 提示里补上「挑中的是哪个 java」（M220）：不符时用户第一个问题就是「它到底用了我哪个 + // JDK」，以前只能自己猜；这条文案只加不减。 + return Err( + CliError::user("java_mismatch", mismatch.message()).with_hint(format!( + "{}；挑中的是 {}", + mismatch.advice(), + java.summary() + )), + ); + } + } + + // 实例存在性先确认、Java 先判，再解析身份：微软轨解析身份会联网刷新令牌（有副作用）， + // 不该在一个注定 not_found 或注定被 D4 拦下的启动上白跑一遍、更不该顺手改写凭据。 + let identity = identity::resolve( + ctx, + args.account.as_deref(), + args.username.as_deref(), + args.dry_run, + )?; + let input = PlanInput { + auth: Some(identity.placeholders.clone()), + // `override_path` 已经是 D4 校验过的那个 java，装配期只照用、不再挑。 + java: java.override_path.clone(), + ..input + }; + let isolation = resolve_isolation(ctx, profile, &input, args.dry_run)?; + let input = PlanInput { + // 派生结果就是 `--gameDir` 的取值（覆盖链已求值完）。 + game_dir: Some(isolation.game_dir.clone()), + ..input + }; + + // M188/M211：命令行这一路也把启动器日志写进 `/logs/launcher.log` + // （落点与格式的真相都在 core 的 `launcher_log`，GUI 写的是同一份）。 + unlucky_core::launch::launcher_log::record_start( + &input.instance_id, + &isolation.game_dir, + java.runtime + .as_ref() + .map(|runtime| (runtime.binary.as_path(), runtime.major.unwrap_or_default())), + input.max_memory, + ); + let plan = snapshot::prepare(ctx, &input)?; + let config = LauncherConfig::new(ctx.sessions_root()) + .with_launcher(super::meta::LAUNCHER_NAME, env!("CARGO_PKG_VERSION")) + .with_watchdog_env(); + // D6：两个看门狗时长的**生效值**落 launcher.log —— 卡死之后第一个要看的就是「等了多久才放弃」。 + let watchdog = config.watchdog_summary(); + unlucky_core::launch::launcher_log::record("launch", &watchdog); + let launcher = Launcher::new(config); + let mut human = Vec::new(); + human.push(watchdog); + 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(&plan.request.java.binary) { + 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(&plan.request.java.binary)); + // 人读行里 Java 告警已经在上面打过一次，这里只补 `dry_run` 自己新发现的。 + for warning in &dry.warnings { + lines.push(format!("告警: {warning}")); + } + human.extend(lines); + let natives = dry.natives.as_ref().map(|natives| natives.to_json()); + 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(&plan.request.java.binary), + "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))?; + unlucky_core::launch::launcher_log::record_end(&input.instance_id, &handle); + 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(&plan.request.java.binary), + "warnings": java.warnings(&plan.request.java.binary), + "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::>(), + "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)) +} + +fn map_launch_error(error: &LaunchError, ctx: &Ctx) -> CliError { + // D6：看门狗超时是一个**可区分的**结局（脚本要能单独处理），且自带现场与可调项， + // 不该被塞上「版本本体目录」这种无关提示。 + if let LaunchError::Watchdog { .. } = error { + return CliError::user("launch_timeout", error.to_string()); + } + 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 ` 登记一个".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/launch_isolation.rs b/crates/cli/src/commands/launch_isolation.rs new file mode 100644 index 0000000..da2ae52 --- /dev/null +++ b/crates/cli/src/commands/launch_isolation.rs @@ -0,0 +1,131 @@ +//! `ull launch` 的隔离档位派生（D20）：运行目录 + 切换检测。 +//! +//! 从 `commands/launch.rs` 原样搬出（那边贴着 400 行红线，M220 的 Java 钉路径改动要往里加行）。 +//! **搬动是纯挪**：函数体、注释、判定顺序一字未改，只补了本模块的 import 与 `pub(super)` +//! （`launch.rs` 里的 `#[path = "launch_isolation.rs"] mod launch_isolation;` 挂载）。 + +use std::path::PathBuf; + +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::launch::time::{format_rfc3339_millis, now}; +use unlucky_core::setting::keys::launcher_schema; +use unlucky_core::setting::store::SettingStore; + +use crate::context::Ctx; +use crate::error::CliError; + +use super::snapshot::PlanInput; + +/// 隔离派生的结果（运行目录 + 生效档位 + 提示）。 +pub(super) struct IsolationPlan { + /// 生效运行目录（喂 `--gameDir`）。 + pub(super) game_dir: PathBuf, + /// 生效档位。 + pub(super) isolation: Isolation, + /// 档位来自哪一层（`temporary` / `instance` / `global`）。 + pub(super) source: unlucky_core::game::IsolationSource, + /// 切换检测提示（两侧都有内容时；`None` = 不必提示）。 + pub(super) warning: Option, +} + +/// 按覆盖链派生运行目录，并在启动时做一次切换检测。 +/// +/// 覆盖链：临时参数（`ull launch` 暂无该 flag，留 `None`） > 实例 `isolation` > 全局 `instances.mode`。 +/// 切换检测只探测 `mods/saves/config` 的条目数并写进实例文件的 `lastModeChange`， +/// **不迁移任何数据**（D20 定案）；提示只展示一次（`warned` 落盘）。 +/// +/// 遗留实例（`profiles.json` 有档案、`config/instances/.json` 还没有——M27 之前的形态） +/// 会在**首次真启动**时补建基线文件：否则这批「最可能撞上存档消失」的用户永远拿不到提示。 +/// `--dry-run` 仍然一个字节都不写。 +pub(super) fn resolve_isolation( + ctx: &Ctx, + profile: Option<&unlucky_core::game::InstanceProfile>, + input: &PlanInput, + dry_run: bool, +) -> Result { + 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() +} 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..960f5f8 --- /dev/null +++ b/crates/cli/src/commands/mod.rs @@ -0,0 +1,241 @@ +//! 命令分发：命令模型 → 具体实现，并统一挂上环境提示。 + +pub mod accounts; +pub mod agent; +pub mod config; +pub mod identity; +pub mod install; +pub mod instance_launch; +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; +pub mod update; + +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 { + 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::InstancesLaunchArgs(args) => { + with_ctx(&invocation.globals, |ctx| instance_launch::run(ctx, args)) + } + Command::InstancesScan => with_ctx(&invocation.globals, instances::scan::run), + Command::InstancesAdopt(args) => { + with_ctx(&invocation.globals, |ctx| instances::adopt::run(ctx, args)) + } + 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::UpdateCheck(args) => { + with_ctx_outcome(&invocation.globals, |ctx| update::check(ctx, args)) + } + Command::UpdateApply(args) => { + with_ctx_outcome(&invocation.globals, |ctx| update::apply(ctx, args)) + } + 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 里给**能照抄的命令**（两条路： + // 运行期一次性的、构建期烘进二进制的），别只丢一个变量名让用户自己猜。 + // M149：官方发布构建已把 id 烘进二进制（真值走仓库 Secret，不进 git 文件），所以能走到这个 + // hint 的只可能是自建且没注入 id 的二进制——文案与 `cli/help.rs` 对齐：官方构建已内置。 + AuthError::Unsupported(_) => Some(format!( + "官方构建已内置微软登录所需的客户端 id，装完即可用；自建构建得自己给：\ +运行期 `{env}= %prog% accounts add msa`（优先于内置值）；\ +或构建时注入 `{env}= 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(globals: &Globals, action: F) -> Result +where + F: FnOnce(&Ctx) -> Result, +{ + 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(globals: &Globals, action: F) -> Result +where + F: FnOnce(&Ctx) -> Result, +{ + 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="), "{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..7bd9020 --- /dev/null +++ b/crates/cli/src/commands/pack.rs @@ -0,0 +1,400 @@ +//! `pack import `：整合包导入（M111）。 +//! +//! 逻辑**全在** `core::addon::import`：本文件只做参数落地、引擎接线、两种输出。坚持这一层很薄， +//! 是因为 M113 的导入页要复用的是 core 的 `import_pack` + `ImportReport`，不是这里的打印逻辑。 +//! +//! # 三态退出码（脚本契约） +//! +//! | `data.status` | 退出码 | 含义 | +//! |---------------|--------|------| +//! | `success` | `0` | 全部落地、无冲突 | +//! | `partial` | `3` | 有缺文件或有保留用户文件的冲突（实例可用但不完整） | +//! | `failed` | `1` | 致命失败，**已整包回滚** | +//! | `cancelled` | `130` | 用户取消（管线在检查点停手并回滚，**不是失败**） | +//! +//! `130`（= `128 + SIGINT`）是"被用户中断"的惯例码：CLI 这一轮没有取消入口（Ctrl-C 直接杀进程）， +//! 但 `ImportStatus::Cancelled` 是 core 的公开结果，脚本读 `--json` 时要能把它与 `failed` 分开。 +//! +//! `--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::DownloadEngine; +use unlucky_core::game::install::pack_dir; + +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 { + if !args.path.exists() { + return Err(CliError::user( + "not_found", + format!("整合包不存在：{}", args.path.display()), + ) + .with_hint("给 .zip / .mrpack 文件，或 MultiMC·Prism 的实例目录")); + } + let layout = ctx.layout(); + // **M216 ②**：缺省落点 = `/instances/<实例名>`（与 GUI 同源，判据在 core 的 + // `pack_dir::import_target`），不再是共享的 `.minecraft` 根。 + let (target, instance_name) = pack_dir::import_target( + &layout, + &args.path, + args.target.as_deref(), + args.name.as_deref(), + ) + .map_err(|reason| { + CliError::user("target_exists", reason).with_hint( + "加 --name 换个实例名，或显式给 --target（--overwrite 只管文件冲突，绕过不了这条预检）", + ) + })?; + + let stages: Arc>> = 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 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 { + // 登记名与目录名同源（GUI 也是这样：`instance_name` 缺省用包名）。 + request = request.with_registration(&layout, Some(&instance_name)); + } + + let report = block_on(import_pack(&request)); + // **§5**：缺省建出来的实例要绑到它的内容目录（判据/文案在 core，与 GUI 同一份），否则 + // 「导入成功」而那批 mods/config 永远不会被那条实例的启动用到。 + let auto = args.target.is_none() && !args.no_register; + let binding = pack_dir::bind_created_instance(&layout, &target, auto, &report); + let seen = stages.lock().map(|seen| seen.clone()).unwrap_or_default(); + Ok(outcome( + ctx, + &report, + &target, + &seen, + args, + binding.as_ref(), + )) +} + +/// 组装 `Outcome`（三态 → 退出码 + 两种输出）。 +fn outcome( + ctx: &Ctx, + report: &ImportReport, + target: &Path, + stages: &[&'static str], + args: &PackImportArgs, + binding: Option<&Result>, +) -> 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 = 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() { + "（缺省 = 新实例目录 <数据根>/instances/）" + } else { + "" + } + )); + if !stages.is_empty() { + human.push(format!("阶段：{}", stages.join(" → "))); + } + if let Some(binding) = binding { + // **M216 r2**：`--json` 里给**结构化成败**（r1 只印人读行，脚本看不到成败）。 + if let Some(object) = data.as_object_mut() { + object.insert("instance_bound".to_string(), json!(binding.is_ok())); + } + human.push(match binding { + Ok(note) | Err(note) => note.clone(), + }); + } + 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}")); + } + human.push(rollback_line(report)); + } + + Outcome::new(Report { data, human }).with_exit_code(report.status.exit_code()) +} + +/// 状态的人读名。**失败要按「动没动过目标目录」分叉**（见 [`rollback_line`]）。 +fn status_label(report: &ImportReport) -> &'static str { + match rollback_stage(report) { + Some(RollbackStage::NotStarted) => "失败（未写入：目标目录没被动过）", + Some(RollbackStage::RolledBack) => "失败（已回滚）", + Some(RollbackStage::Incomplete) => "失败（回滚不完整）", + None => match report.status { + ImportStatus::Success => "成功", + // 取消**不是失败**：不说"失败"，也不说"部分成功"（那会让人以为装了一半）。 + // 但回滚不完整时也不许说"与导入前一致"——与失败路径同一套诚实口径。 + ImportStatus::Cancelled => { + if report.rolled_back { + "已取消（目标目录与导入前一致）" + } else { + "已取消（回滚不完整，目标目录可能与导入前不同）" + } + } + _ => "部分成功", + }, + } +} + +/// 「这次失败到底动没动过目标目录」（三档）。 +/// +/// 与 `presenter` 的 `host::addon::pack::convert::failure_stage` **同义**——CLI 不依赖 presenter +/// 层（`unlucky-cli` 只依赖 core + agent），所以这套判据在这里各写一份。已登记 finding： +/// 更干净的做法是把三档挪进 `core::addon::import::ImportReport`（那儿有 `rollback` / +/// `rolled_back` 两个机器位），两处都改成读它。 +/// +/// 为什么要三档而不是一个 `rolled_back` 布尔：core 的 `rolled_back` 在「回滚完整完成」与 +/// **「从未写过目标目录」**两种情形下都是 `true`。只按它出词，预检失败会被说成「已整包回滚：目标 +/// 目录与导入前一致」——那句话在**一个字节都没写**时是假的（M161 复审的 P1 同族问题）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +enum RollbackStage { + /// 预检/装配阶段就失败：目标目录一个字节都没写 + NotStarted, + /// 写过，回滚**完整**完成 + RolledBack, + /// 写过，回滚有失败项（目标目录可能与导入前不同） + Incomplete, +} + +/// 三档判据（与 presenter 那份逐条对应）。 +fn rollback_stage(report: &ImportReport) -> Option { + if report.status != ImportStatus::Failed { + return None; + } + Some(match &report.rollback { + Some(outcome) if outcome.is_complete() => RollbackStage::RolledBack, + Some(_) => RollbackStage::Incomplete, + None if report.rolled_back => RollbackStage::NotStarted, + None => RollbackStage::Incomplete, + }) +} + +/// 失败收尾那一段人读文案（**三档三句**，不许共用）。 +fn rollback_line(report: &ImportReport) -> String { + match rollback_stage(report) { + Some(RollbackStage::NotStarted) => { + "预检未通过：目标目录一个字节都没写（不需要回滚）".to_string() + } + Some(RollbackStage::RolledBack) => "已整包回滚：目标目录与导入前一致".to_string(), + Some(RollbackStage::Incomplete) => match &report.rollback { + Some(rollback) => format!( + "回滚未完整：{} 项没回去（详见 --json 的 rollback.failed）", + rollback.failure_count() + ), + None => "回滚状态不明：目标目录可能与导入前不同（详见 --json）".to_string(), + }, + None => String::new(), + } +} + +fn count_action(report: &ImportReport, action: FileAction) -> usize { + report + .files + .iter() + .filter(|file| file.action == action) + .count() +} + +/// 与 `install` / `java` 共用同一套引擎装配（镜像 / 地区 / 健康度 / 内容缓存）， +/// 参数来自设置：读数口径见 [`crate::download`]。 +pub(crate) fn build_engine(ctx: &Ctx) -> Arc { + crate::download::engine(ctx) +} + +#[cfg(test)] +mod tests { + //! `pack import` 失败收尾的三档文案（M161 复审「不计入但该记」第一条：CLI 也曾把 + //! 预检失败说成「已整包回滚」）。 + //! + //! 抓得住：三档塌成两句（预检 → 已回滚）；`is_complete()` 被丢掉；`status != Failed` 也出话。 + + use std::path::PathBuf; + + use unlucky_core::addon::import::{ImportError, ImportReport, ImportStatus, RollbackOutcome}; + + use super::*; + + fn failed() -> ImportReport { + let mut report = ImportReport::empty(PathBuf::from("C:/tmp/.minecraft")); + report.fail(ImportError::integrity("sha1 mismatch")); + report + } + + /// 三档三句，**互不相同**（同族的谎就是这个 mission 要消灭的那类）。 + #[test] + fn the_three_rollback_stages_get_three_different_sentences() { + // ① 预检没过：一个字节都没写。 + let mut preflight = failed(); + preflight.rolled_back = true; + assert_eq!(rollback_stage(&preflight), Some(RollbackStage::NotStarted)); + let not_started = rollback_line(&preflight); + assert!(not_started.contains("没写"), "{not_started}"); + assert!( + !not_started.contains("回滚：目标目录"), + "预检失败不许说「已回滚」：{not_started}" + ); + assert_eq!(status_label(&preflight), "失败（未写入：目标目录没被动过）"); + + // ② 写过又完整回滚。 + let mut rolled_back = failed(); + rolled_back.rolled_back = true; + rolled_back.rollback = Some(RollbackOutcome { + attempted: 2, + failed: Vec::new(), + }); + assert_eq!( + rollback_stage(&rolled_back), + Some(RollbackStage::RolledBack) + ); + assert!(rollback_line(&rolled_back).contains("已整包回滚")); + assert_eq!(status_label(&rolled_back), "失败（已回滚）"); + + // ③ 回滚没做完。 + let mut incomplete = failed(); + incomplete.rolled_back = false; + incomplete.rollback = Some(RollbackOutcome { + attempted: 2, + failed: vec!["mods/a.jar".to_string()], + }); + assert_eq!(rollback_stage(&incomplete), Some(RollbackStage::Incomplete)); + assert!(rollback_line(&incomplete).contains("1 项没回去")); + assert_eq!(status_label(&incomplete), "失败（回滚不完整）"); + + // 三句必须互不相同（把任何两档并成一句，这里就红）。 + let lines = [ + rollback_line(&preflight), + rollback_line(&rolled_back), + rollback_line(&incomplete), + ]; + assert_eq!( + lines.iter().collect::>().len(), + 3, + "{lines:?}" + ); + } + + /// 不是致命失败 ⇒ 没有回滚那一段话（成功/部分成功不该出现「已回滚」）。 + #[test] + fn a_non_fatal_report_says_nothing_about_rollback() { + let mut report = ImportReport::empty(PathBuf::from("C:/tmp")); + report.status = ImportStatus::Partial; + assert_eq!(rollback_stage(&report), None); + assert_eq!(rollback_line(&report), ""); + assert_eq!(status_label(&report), "部分成功"); + } +} diff --git a/crates/cli/src/commands/sessions.rs b/crates/cli/src/commands/sessions.rs new file mode 100644 index 0000000..e33585c --- /dev/null +++ b/crates/cli/src/commands/sessions.rs @@ -0,0 +1,322 @@ +//! `sessions list` / `logs` / `diag`：读 M18 的会话索引与 JSONL 事件流。 +//! +//! 数据源形状见 `DevDocs/SubAgentsTalk/launch-接口约定.md` §2/§5： +//! - `/game/index.jsonl`：一会话一行摘要（同 id 取最后一行，倒序）； +//! - `/game/.jsonl`：事件流（`kind` + `payload`）。 +//! +//! **M188 起 `sessions_root` = `<.ULL>/logs`**（旧家 `<.ULL>/data/agent/sessions` 只读兼容： +//! 两个索引合并、事件流先新根后旧家），`launcher.log` 就在同一层的 `logs/` 里。 +//! +//! `diag` 的结论优先取会话里**落盘的那份**，老会话才把脱敏文本喂回 M15 的内嵌规则集 +//! （M242，为什么与代价见 `sessions/diagnosis.rs` 的模块文档）。 + +mod diagnosis; + +/// M242：`ull diag` 的结论来源（落盘那份优先）。拆文件守「单文件 ≤400 行」。 +#[cfg(test)] +#[path = "sessions/m242_tests.rs"] +mod m242_tests; + +use std::path::Path; + +use serde_json::{json, Value}; +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 { + let index = ctx.session_index(); + let entries = merged_entries(ctx)?; + let shown: Vec<&SessionIndexEntry> = entries.iter().take(limit).collect(); + + let rows: Vec = 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() + )]; + // M188：旧家的会话仍然列得出来，就得说清它们从哪来——否则用户会以为「新目录里怎么没有」。 + let legacy = ctx.legacy_session_index(); + if legacy.is_file() { + human.push(format!( + " 旧会话目录仍然只读兼容：{}（不搬不删）", + legacy.display() + )); + } + human.push(format!(" 启动器日志：{}", ctx.logs_dir().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 [--tail N]`：打印事件流末尾 N 条。 +/// +/// # Errors +/// +/// 会话不存在/前缀有歧义、事件流读不了时返回用户错误。 +pub fn logs(ctx: &Ctx, args: &LogsArgs) -> Result { + 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 = 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 [--tail N]`：给会话下诊断结论。 +/// +/// 结论来源**先是会话里落盘的 `diagnosis` 事件**（M242），没有它的老会话才在脱敏文本上重跑 +/// ——为什么、代价如何见 `sessions/diagnosis.rs` 的模块文档。`--tail` 只影响重跑那条路。 +/// +/// `exit` 仍取自索引（launch 报的事实），不是 M15 的结论：换来源只换结论。 +/// +/// # Errors +/// +/// 会话不存在、事件流读不了、结论序列化失败时返回错误。 +pub fn diag(ctx: &Ctx, args: &DiagArgs) -> Result { + let entry = find_entry(ctx, &args.session_id)?; + let path = event_path(ctx, &entry); + let events = read_events(&path)?; + let found = diagnosis::conclusion(&entry, &events, args.tail)?; + + // 脱敏一次、两条输出共用：`--json` 是机器消费路径，不该比人类路径拿到更多原文。 + let human: Vec = diagnosis::lines(&entry, &found) + .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, + }, + "conclusion_source": found.provenance.as_str(), + "diagnosis": found.record, + })); + Ok(Report::new(payload, human)) +} + +fn find_entry(ctx: &Ctx, key: &str) -> Result { + let index = ctx.session_index(); + let entries = merged_entries(ctx)?; + 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 { + // M188：新会话在 `logs/game/`，旧会话在 `data/agent/sessions/game/`（只读兼容）。 + // 先看新根，再回落旧家；两处都没有就把新根路径交出去（错误信息据此说「该去哪找」）。 + // M211/D2：`log_path` 已经**相对会话根**（`game/.jsonl`），解析交给 core 里唯一的 + // `session_index::event_file`——这里不许再自己拼 `game/`，否则又是一份第三真相。 + let primary = session_index::event_file(&ctx.sessions_root(), &entry.log_path); + if primary.is_file() { + return primary; + } + let legacy = session_index::event_file(&ctx.legacy_sessions_root(), &entry.log_path); + if legacy.is_file() { + return legacy; + } + primary +} + +/// 两个索引合并后的条目（新根 `logs/` 在前，旧家只读兼容在后；同 id 以新根为准）。 +fn merged_entries(ctx: &Ctx) -> Result, CliError> { + let mut indexes = vec![ctx.session_index()]; + let legacy = ctx.legacy_session_index(); + if legacy.is_file() { + indexes.push(legacy); + } + let mut merged: Vec = Vec::new(); + for index in indexes { + for entry in session_index::read_all(&index) + .map_err(|error| CliError::io("读会话索引", &index, &error))? + { + if merged + .iter() + .any(|item| item.session_id == entry.session_id) + { + continue; + } + merged.push(entry); + } + } + merged.sort_by(|left, right| right.started_at.cmp(&left.started_at)); + Ok(merged) +} + +fn read_events(path: &Path) -> Result, 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::(line).ok()) + .collect()) +} + +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}") +} + +/// M211/D5：`ull launch` 也必须写 `/logs/launcher.log`（与 GUI 同一份文件、同一行格式）。 +/// +/// 为什么这条用例在这个文件里：CLI 侧本 mission 只允许改 `commands/launch.rs` 与 +/// `commands/sessions.rs`，而 `launch.rs` 已到 389 行、再加用例会破「文件 ≤400 行」—— +/// 用例放在同一个 `/logs` 层级的读取方（本文件打印「启动器日志：」）旁边。 +/// +/// 变异证明：删掉 `commands/launch.rs` 里的 `record_start(...)` ⇒ 本条红（文件根本不存在）； +/// 把 `set_dir` 的入参换成别的目录 ⇒ 本条红。 +#[cfg(test)] +mod tests { + /// 一个最小实例档案（`profiles.json`）：只要能让 `launch` 走到「准备启动」这一段。 + const PROFILES: &str = r#"{"schema_version":1,"profiles":[{"id":"11111111-2222-4333-8444-000000000001","name":"生存服","version_id":"1.20.1"}]}"#; + + #[test] + fn a_launch_attempt_writes_the_launcher_log() { + let root = std::env::temp_dir().join(format!("ull-m211-cli-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&root); + std::fs::create_dir_all(root.join(".ULL/config")).expect("建配置目录"); + std::fs::write(root.join(".ULL/config/profiles.json"), PROFILES).expect("写 profiles"); + + let args: Vec = vec![ + "launch".to_string(), + "生存服".to_string(), + "--data-dir".to_string(), + root.display().to_string(), + ]; + let (mut out, mut err) = (Vec::new(), Vec::new()); + // 版本本体不存在 ⇒ 这条命令会失败，但「启动前」那一行必须已经落盘 + // （事故现场最需要的正是「它打算用什么起的」）。 + let _ = crate::run(&args, &mut out, &mut err); + + let log = std::fs::read_to_string(root.join(".ULL/logs/launcher.log")) + .expect("`ull launch` 必须在 /logs/launcher.log 里留下启动器日志"); + assert!( + log.contains("[launch] instance=11111111-2222-4333-8444-000000000001"), + "{log}" + ); + assert!( + log.contains("game_dir=") && log.contains("memory="), + "{log}" + ); + std::fs::remove_dir_all(&root).ok(); + } +} diff --git a/crates/cli/src/commands/sessions/diagnosis.rs b/crates/cli/src/commands/sessions/diagnosis.rs new file mode 100644 index 0000000..5738822 --- /dev/null +++ b/crates/cli/src/commands/sessions/diagnosis.rs @@ -0,0 +1,240 @@ +//! `ull diag` 的结论来源：**先读会话里落盘的那份**，老会话才重跑规则（M242）。 +//! +//! ## 为什么不能每次都在会话文本上重跑 +//! +//! 会话 JSONL 是**写前脱敏**的（`launch::redact`，落盘即脱敏），而脱敏拿不准形状时是**有损**的： +//! `≥64` 的不透明串、带点的票据串都会被换成占位符（`` / ``）。 +//! M240 收窄了这条规则——**路径形状**的长串现在整条保留，所以 M239 实测的那条 +//! `org/spongepowered/…/FabricMixinTransformerProxy` 今天能活下来。但那是**白名单**：形状一变 +//! （或又登记了别的 secret）就回到「抹掉」那一侧，而抹掉之后的重跑不是「少一点细节」，是 +//! **换一条结论** —— `fabric.loader_0_12`（critical）降级成 `integrity.no_class_def_found` +//! （warning：把「Fabric Loader 版本不配套」说成「库没下全」）。 +//! +//! M241 起写会话时已经在**原始行**上算过一次结论（`SessionWriter::finish` → +//! `diagnose::session::conclude`），落成 `diagnosis` 事件；那份结论自己还要再走一遍 +//! `Redactor::scrub_json`，所以盘上只有脱敏后的结论，没有原文。M242 换的就是**证据**， +//! 不是判据：规则集的 pattern 一个字符都没动。 +//! +//! ## 回落 +//! +//! 没有 `diagnosis` 事件的老会话仍走原来的重跑（行为与 M242 之前完全一致）：短字面量的规则 +//! （`memory.out_of_memory` 之类）在脱敏文本上照样命中；只有「靠长串证据」那类规则会降级 +//! —— 那是老数据本身的代价，输出里的「结论来源」一行会把它说清。 + +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::SessionIndexEntry; + +use crate::error::CliError; + +use super::exit_label; + +/// 结论从哪儿来（人类输出与 `--json` 都要说清，否则用户分不清「盘上的」与「刚算的」—— +/// 这两者在长串证据类规则上给出的结论**可能不同**）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Provenance { + /// 会话里落盘的 `diagnosis` 事件（M241 起，写会话时在原始行上算的）。 + Stored, + /// 老会话：在脱敏文本上重跑规则。 + Rerun, +} + +impl Provenance { + /// `--json` 里的值（`stored` / `rerun`）。 + pub const fn as_str(self) -> &'static str { + match self { + Self::Stored => "stored", + Self::Rerun => "rerun", + } + } + + /// 人类输出里的一行说明。 + pub const fn label(self) -> &'static str { + match self { + Self::Stored => "会话落盘的 diagnosis 事件（写会话时在原始行上算的，已脱敏后落盘）", + Self::Rerun => "在脱敏文本上重跑规则（老会话没有落盘结论，靠长串证据的规则可能降级）", + } + } +} + +/// 一次诊断：结论本体 + 出处。 +#[derive(Debug, Clone)] +pub struct Conclusion { + /// `diagnosis` 记录（`DiagnosisRecord` 的 JSON），两条来源同形。 + pub record: Value, + /// 从哪儿来。 + pub provenance: Provenance, + /// 重跑时评估了多少条规则（落盘那份不记这个数，所以是 `Option`）。 + pub rules_evaluated: Option, +} + +/// 取这个会话的诊断结论：优先落盘的那份，老会话才重跑。 +/// +/// # Errors +/// +/// 重跑路径上结论序列化失败时返回内部错误。 +pub fn conclusion( + entry: &SessionIndexEntry, + events: &[Value], + tail: usize, +) -> Result { + if let Some(record) = stored(events) { + return Ok(Conclusion { + record, + provenance: Provenance::Stored, + rules_evaluated: None, + }); + } + let (record, rules_evaluated) = rerun(entry, events, tail)?; + Ok(Conclusion { + record, + provenance: Provenance::Rerun, + rules_evaluated: Some(rules_evaluated), + }) +} + +/// 事件流里最后一条 `diagnosis` 事件的 payload。 +/// +/// 正常只有一条（挂钩写的或收尾补的，二选一）；真有多条取**最后一条**：收尾补的证据最新鲜。 +/// 没有主因（`candidates` 空）的 payload 与「没结论」等价——`conclude` 也不会写它——此时 +/// 回落到重跑，而不是拿一份空结论顶掉。 +fn stored(events: &[Value]) -> Option { + let payload = events + .iter() + .rev() + .find(|event| event.get("kind").and_then(Value::as_str) == Some("diagnosis"))? + .get("payload")?; + let has_primary = payload + .get("candidates") + .and_then(Value::as_array) + .is_some_and(|items| !items.is_empty()); + has_primary.then(|| payload.clone()) +} + +/// 老会话的回落：在脱敏文本上重跑规则，返回 `(结论记录, 评估条数)`。 +fn rerun( + entry: &SessionIndexEntry, + events: &[Value], + tail: usize, +) -> Result<(Value, usize), CliError> { + 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, tail); + let stderr_text = tail_join(&stderr_lines, 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()))?; + Ok((record, report.rules_evaluated)) +} + +/// 人类可读的几行（未脱敏——调用方统一过一次 `redact_text`）。 +pub fn lines(entry: &SessionIndexEntry, found: &Conclusion) -> Vec { + let mut human = vec![ + format!( + "会话 {} · {} · {} · {}", + entry.session_id, + entry.instance_name, + entry.game_version, + exit_label(entry) + ), + format!("结论来源: {}", found.provenance.label()), + ]; + match found.record.get("candidates").and_then(Value::as_array) { + Some(items) if !items.is_empty() => { + let primary = &items[0]; + if let Some(message) = text_at(primary, "message") { + human.push(format!("主因: {message}")); + } + if let Some(detail) = text_at(primary, "detail") { + human.push(format!("说明: {detail}")); + } + for evidence in evidence_of(primary, 3) { + human.push(format!("证据: {evidence}")); + } + } + _ => human.push("规则引擎没有得出确定结论（needs_more_info）".to_string()), + } + human.push(counts_line(&found.record, found.rules_evaluated)); + human +} + +/// `规则评估 N 条 · 结论 N 条 · 次生 N 条`（落盘那份没有「评估条数」，省掉第一段）。 +fn counts_line(record: &Value, rules_evaluated: Option) -> String { + let count = |key: &str| { + record + .get(key) + .and_then(Value::as_array) + .map_or(0, Vec::len) + }; + let mut line = String::new(); + if let Some(evaluated) = rules_evaluated { + line.push_str(&format!("规则评估 {evaluated} 条 · ")); + } + line.push_str(&format!( + "结论 {} 条 · 次生 {} 条", + count("candidates"), + count("secondary") + )); + line +} + +fn text_at<'a>(value: &'a Value, key: &str) -> Option<&'a str> { + value.get(key).and_then(Value::as_str) +} + +fn evidence_of(candidate: &Value, limit: usize) -> Vec { + candidate + .get("evidence") + .and_then(Value::as_array) + .into_iter() + .flatten() + .filter_map(Value::as_str) + .take(limit) + .map(str::to_string) + .collect() +} + +/// 取末尾 `tail` 行并拼成文本（与重跑路径的老行为逐字一致）。 +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 +} diff --git a/crates/cli/src/commands/sessions/m242_tests.rs b/crates/cli/src/commands/sessions/m242_tests.rs new file mode 100644 index 0000000..ea62bb2 --- /dev/null +++ b/crates/cli/src/commands/sessions/m242_tests.rs @@ -0,0 +1,221 @@ +//! M242：`ull diag ` 的结论来源。两条端到端用例：**真 `SessionWriter` 写盘 → 真 CLI 入口**。 +//! +//! 判据是「命中哪条规则」而不是「有没有结论」：脱敏有损，重跑出来的结论会**换一条**规则 +//! （`fabric.loader_0_12` → `integrity.no_class_def_found`）。 +//! +//! ## 夹具为什么把类路径登记成 secret +//! +//! M240 把「`≥64` 不透明串」这条收窄了：**路径形状**的长串（被 `/` 切开且每段都是词形名字） +//! 现在整条保留，所以 `SessionWriter` 落盘时这条证据行**今天不会被抹**。要复现「读回脱敏文本 +//! 就丢了证据」这个世界（M239 实测的那份老落盘形状，也是脱敏规则以后再收紧时的形状），夹具 +//! 把类路径登记成 secret 交给 `Redactor`：写盘前它被抹成 ``，而结论是 +//! 在**原始行**上算的 —— 与用户盘上真实存在的那类会话同样失真，足以分辨两条路。 +//! +//! 变异证明（改完已还原）： +//! - 把 [`super::diagnosis::conclusion`] 里的 `stored(...)` 分支删掉（等于每次都重跑）⇒ +//! `diag_reads_the_stored_conclusion...` 红（`candidates[0].id` 变成 `integrity.no_class_def_found`）。 + +use std::path::{Path, PathBuf}; + +use serde_json::{json, Value}; +use unlucky_core::launch::exit_analysis::{self, ExitSignals}; +use unlucky_core::launch::pump::{LogLine, Stream}; +use unlucky_core::launch::redact::Redactor; +use unlucky_core::launch::session::{EndReason, SessionMeta, SessionWriter}; +use unlucky_core::launch::session_index; + +use crate::cli::Globals; +use crate::context::Ctx; + +/// `fabric.loader_0_12`（critical / priority 80）唯一的证据行（`rules.d/fabric.yaml`）里的类路径。 +const CLASS_PATH: &str = "org/spongepowered/asm/mixin/transformer/FabricMixinTransformerProxy"; + +/// 那条完整的证据行。 +fn evidence_line() -> String { + format!("java.lang.NoClassDefFoundError: {CLASS_PATH}") +} + +/// 一个临时数据根（`Drop` 时清掉，与 `crates/cli/tests/support` 同口径）。 +struct TempRoot(PathBuf); + +impl TempRoot { + fn new(tag: &str) -> Self { + let path = std::env::temp_dir().join(format!("ull-m242-{tag}-{}", 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 TempRoot { + fn drop(&mut self) { + let _ = std::fs::remove_dir_all(&self.0); + } +} + +/// 与生产同一条解析（`--data-dir` → `Ctx`）：会话根不在测试里手拼，避免「夹具说另一种形状」。 +fn ctx_for(root: &Path) -> Ctx { + let globals = Globals { + data_dir: Some(root.to_path_buf()), + ..Globals::default() + }; + Ctx::resolve_in(&globals, None).expect("解析数据根") +} + +/// 跑一次真 CLI 命令（`crate::run` = 解析 + `Ctx` + 命令实现），返回 `--json` 载荷的 `data`。 +fn run_diag_json(root: &Path, session_id: &str) -> Value { + let args: Vec = vec![ + "diag".to_string(), + session_id.to_string(), + "--json".to_string(), + "--data-dir".to_string(), + root.display().to_string(), + ]; + let (mut out, mut err) = (Vec::new(), Vec::new()); + let code = crate::run(&args, &mut out, &mut err); + let stdout = String::from_utf8_lossy(&out).into_owned(); + let stderr = String::from_utf8_lossy(&err).into_owned(); + assert_eq!(code, 0, "`ull diag` 应成功：{stderr}\n{stdout}"); + let value: Value = serde_json::from_str(&stdout).unwrap_or_else(|error| { + panic!("`--json` 输出不是 JSON：{error}\n{stdout}"); + }); + value["data"].clone() +} + +/// 一局真会话：`SessionWriter` 写盘（写前脱敏）→ `finish` 在原始行上补结论 → 索引 + JSONL。 +fn write_real_session(root: &Path) -> String { + let session_id = "20261102T090000-m242abc"; + let mut writer = SessionWriter::create_with_id( + &ctx_for(root).sessions_root(), + session_id, + SessionMeta::new("inst-1", "1.20.1 Fabric", "1.20.1"), + // 登记成 secret ⇒ 盘上那条证据行的类路径被抹掉（见模块文档：为什么要人为造这份失真）。 + Redactor::new().with_secret(CLASS_PATH), + ) + .expect("建会话"); + writer.session_start().expect("session_start"); + let lines = vec![ + LogLine::new(Stream::Stderr, "Failed to start Fabric loader"), + LogLine::new(Stream::Stderr, evidence_line()), + LogLine::new(Stream::Stdout, "[main/INFO]: Loading Minecraft 1.20.1"), + ]; + for line in &lines { + writer.line(line).expect("写行"); + } + let analysis = exit_analysis::analyze(&ExitSignals::new(1, 40_000, &lines)); + writer.exit(&analysis).expect("exit"); + writer.finish(EndReason::Exit).expect("finish"); + session_id.to_string() +} + +/// 落盘的会话文件（诊断事件也在这份里）。 +fn event_file(root: &Path, session_id: &str) -> PathBuf { + session_index::event_file( + &ctx_for(root).sessions_root(), + &session_index::log_path_for(session_id), + ) +} + +/// 主判据：结论是**盘上那份**。只有读到 `diagnosis` 事件才能命中 `fabric.loader_0_12`—— +/// 在脱敏文本上重跑永远命中不了它（证据行已被抹成占位符）。 +#[test] +fn diag_reads_the_stored_conclusion_instead_of_rerunning_redacted_text() { + let temp = TempRoot::new("diag-stored"); + let root = temp.path(); + let session_id = write_real_session(root); + + let data = run_diag_json(root, &session_id); + assert_eq!(data["session_id"], session_id.as_str()); + assert_eq!( + data["conclusion_source"], "stored", + "有 diagnosis 事件时不得重跑：{data}" + ); + assert_eq!( + data["diagnosis"]["candidates"][0]["id"], "fabric.loader_0_12", + "落盘的结论必须原样读出（重跑会降级成 integrity.no_class_def_found）：{data}" + ); + assert_eq!(data["diagnosis"]["needs_more_info"], false); + + // 盘上那份**真的**丢了证据（不然这条用例证明不了「重跑会失真」），而修 bug ≠ 把原文写进盘。 + let disk = std::fs::read_to_string(event_file(root, &session_id)).expect("读会话文件"); + assert!( + disk.contains(""), + "夹具前提：盘上的证据行必须已被抹掉：{disk}" + ); + assert!(!disk.contains("FabricMixinTransformerProxy"), "{disk}"); + + // 人类路径也要说清结论从哪来（否则「盘上的」与「刚算的」分不开）。 + let args: Vec = vec![ + "diag".to_string(), + session_id.clone(), + "--data-dir".to_string(), + root.display().to_string(), + ]; + let (mut out, mut err) = (Vec::new(), Vec::new()); + assert_eq!(crate::run(&args, &mut out, &mut err), 0); + let human = String::from_utf8_lossy(&out); + assert!( + human.contains("结论来源: 会话落盘的 diagnosis 事件"), + "{human}" + ); + assert!(human.contains("主因: "), "{human}"); +} + +/// 老会话兼容：没有 `diagnosis` 事件（M241 之前写的 JSONL，且还在旧家）→ 回落重跑仍然可用。 +/// +/// 与上一条的差别只在**证据**：这里盘上只有脱敏文本，所以用的是短字面量规则 +/// `memory.out_of_memory`（脱敏抹不掉 `java.lang.OutOfMemoryError`）。长串证据那类规则 +/// 在老会话上只能降级，这是老数据本身的代价——`conclusion_source` 会标成 `rerun`。 +#[test] +fn legacy_session_without_a_stored_conclusion_falls_back_to_rerunning() { + let temp = TempRoot::new("diag-legacy"); + let root = temp.path(); + let session_id = "20261030T101500-legacy"; + let log_path = session_index::log_path_for(session_id); + // M188 之前的生产落点（`data/agent/sessions`，只读兼容）：老会话的「老」还多一层。 + let legacy_root = ctx_for(root).legacy_sessions_root(); + let index = session_index::index_path(&legacy_root); + std::fs::create_dir_all(index.parent().expect("索引父目录")).expect("建目录"); + let entry = json!({ + "v": 1, + "session_id": session_id, + "instance_id": "inst-1", + "instance_name": "1.20.1", + "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": 2, + "log_path": log_path, + "crash_found": false, + "diagnosis_top": null + }); + std::fs::write(&index, format!("{entry}\n")).expect("写索引"); + let file = session_index::event_file(&legacy_root, &log_path); + std::fs::write( + &file, + concat!( + "{\"v\":1,\"seq\":0,\"kind\":\"stderr\",\"payload\":{\"line\":\"java.lang.OutOfMemoryError: Java heap space\",\"level\":\"error\"}}\n", + "{\"v\":1,\"seq\":1,\"kind\":\"session_end\",\"payload\":{\"reason\":\"exit\"}}\n" + ), + ) + .expect("写老会话事件流"); + + let data = run_diag_json(root, session_id); + assert_eq!( + data["conclusion_source"], "rerun", + "没有 diagnosis 事件时必须回落重跑：{data}" + ); + assert_eq!( + data["diagnosis"]["candidates"][0]["id"], "memory.out_of_memory", + "回落路径仍要给出结论：{data}" + ); +} diff --git a/crates/cli/src/commands/snapshot.rs b/crates/cli/src/commands/snapshot.rs new file mode 100644 index 0000000..004a5bd --- /dev/null +++ b/crates/cli/src/commands/snapshot.rs @@ -0,0 +1,331 @@ +//! 实例 → [`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//`）。 + pub version_id: String, + /// 实例 id（写进会话索引；无档案时为空）。 + pub instance_id: String, + /// 实例显示名。 + pub instance_name: String, + /// 已派生的运行目录（D20 隔离覆盖链在 `super::launch` 求值完，这里只消费）。 + pub game_dir: Option, + /// Java 可执行文件覆盖。 + pub java: Option, + /// 离线账户名（无账户时生效；有账户时身份由 `auth` 决定）。 + pub username: Option, + /// 已解析好的账户占位（`None` = 退回 `username` 的离线占位）。 + pub auth: Option, + /// 最大堆 MB。 + pub max_memory: Option, +} + +/// 装配结果。 +#[derive(Debug, Clone)] +pub struct Plan { + /// 实际使用的版本 id。 + pub version_id: String, + /// 装配好的启动请求。 + pub request: LaunchRequest, + /// 非致命告警（缺主类/缺资源索引等）。 + pub warnings: Vec, +} + +/// 装配一个 [`LaunchRequest`]。 +/// +/// # Errors +/// +/// 版本 JSON 缺失/非法、继承链断裂（缺父版本/成环）时返回用户错误。 +pub fn prepare(ctx: &Ctx, input: &PlanInput) -> Result { + 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 { + 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 = Vec::new(); + for library in resolved.libraries.as_deref().unwrap_or_default() { + if !library.applies(&environment) { + continue; + } + // 1.19+ 的 natives 是独立库条目（name 带分类器），必须进 classpath； + // ≤1.18 的 `natives` 表条目归 natives::collect，不进 classpath。 + // Linux arm64：独立条目改写成 natives-linux-arm64（路径与展示名一起改）。 + let arm64 = library.linux_arm64_native_name(&environment); + if arm64.is_none() && library.native_classifier(&environment).is_some() { + continue; + } + let (coordinate, name) = match arm64 { + Some(rewritten) => { + let Ok(coordinate) = + unlucky_core::game::library::MavenCoordinate::parse(&rewritten) + else { + continue; + }; + (coordinate, rewritten) + } + None => { + let Ok(coordinate) = library.coordinate() else { + continue; + }; + (coordinate, library.name.clone()) + } + }; + let path = if library.is_local() { + game.version_library(&version_id, &coordinate) + } else { + game.library(&coordinate) + }; + libraries.push(LibraryInput::new(path, name)); + } + + // 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())); + + // 同 presenter：装配门限按**继承链的 MC 根版本**判（loader 实例的 version_id 带加载器后缀， + // 周快照的 6 字符形态判据在那儿失效，`--graphicsBackend` 会被静默跳过）。 + let root_version = super::instance_launch::root_version_id(&game, &manifest); + let snapshot = SnapshotInput { + version_id: &version_id, + version_name: Some(&input.instance_name), + version_type: None, + game_version: Some(root_version.as_str()), + 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, + }; + + // 实例级启动参数的三级回落（实例 → 全局 → 默认）。临时启动参数（`--max-memory` / + // `--java`）在 D20 的覆盖链里位于实例之上，所以这里先把它们叠上去再落位。 + let mut effective = super::instance_launch::resolved(ctx, &input.instance_id); + if let Some(mb) = input.max_memory { + effective.memory_mb = mb; + } + if let Some(path) = &input.java { + effective.java_path = Some(path.clone()); + } + + let options = AdapterOptions { + java: super::java::selection(effective.java_path.as_deref()), + memory: MemoryOptions { + min_mb: None, + max_mb: Some(effective.memory_mb), + }, + 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(); + // 实例级启动参数（三级回落后的生效值）最后落位：user.* / memory / graphics_backend。 + unlucky_core::launch::overrides::apply(&mut request, &effective); + + Ok(Plan { + version_id, + request, + warnings, + }) +} + +fn read_version_json(path: &std::path::Path) -> Result { + 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()) + } + } +} + +#[cfg(test)] +mod tests { + use std::path::{Path, PathBuf}; + use std::sync::atomic::{AtomicU64, Ordering}; + + use super::*; + + /// 一次性临时数据根（`--data-dir` 的等价物：custom 模式 → `/.ULL` + `/.minecraft`）。 + 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-cli-snapshot-{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); + } + } + + fn ctx_at(dir: &TempDir) -> Ctx { + let globals = crate::cli::Globals { + data_dir: Some(dir.path().to_path_buf()), + ..crate::cli::Globals::default() + }; + Ctx::resolve(&globals).expect("解析数据根") + } + + fn write_version(ctx: &Ctx, id: &str, json: &str) { + let path = ctx.game().version_json(id); + std::fs::create_dir_all(path.parent().expect("版本目录")).expect("版本目录"); + std::fs::write(&path, json).expect("写版本 JSON"); + } + + /// **周快照 + 加载器实例**（M157 r3 复审 P2-1）：`prepare` 交给装配的游戏版本是 + /// 继承链根的 `26w14a`，不是 `26w14a-fabric-0.16.5`。 + /// + /// 抓得住：`SnapshotInput.game_version` 回退成 `None`（装配用带后缀的 id 判门限， + /// `--graphicsBackend` 会被静默跳过，而 CLI 自己的门槛显示「可下发」）。 + /// 抓不住：完整 argv（`crates/core/src/launch/overrides/tests.rs` 的周快照用例）。 + #[test] + fn weekly_loader_instance_is_assembled_against_the_mc_root_version() { + let dir = TempDir::new("weekly"); + let ctx = ctx_at(&dir); + write_version( + &ctx, + "26w14a", + r#"{"id":"26w14a","mainClass":"net.minecraft.client.main.Main", + "libraries":[{"name":"org.lwjgl:lwjgl-vulkan:3.4.3"}]}"#, + ); + write_version( + &ctx, + "26w14a-fabric-0.16.5", + r#"{"id":"26w14a-fabric-0.16.5","inheritsFrom":"26w14a", + "mainClass":"net.fabricmc.loader.impl.launch.knot.KnotClient"}"#, + ); + + let plan = prepare( + &ctx, + &PlanInput { + version_id: "26w14a-fabric-0.16.5".to_string(), + instance_name: "周快照 Fabric".to_string(), + ..PlanInput::default() + }, + ) + .expect("装配应成功"); + + assert_eq!( + plan.request.instance.version.raw(), + "26w14a", + "装配的游戏版本必须是继承链的 MC 根版本（CLI 门槛与拼装必须同一口径）" + ); + assert!(plan.request.instance.version.is_weekly_snapshot()); + assert!(plan.request.manifest.has_vulkan_backend); + } +} diff --git a/crates/cli/src/commands/update.rs b/crates/cli/src/commands/update.rs new file mode 100644 index 0000000..cf96e0c --- /dev/null +++ b/crates/cli/src/commands/update.rs @@ -0,0 +1,286 @@ +//! `ull update check` / `ull update apply`（M159）：**复用 core 的同一内核**。 +//! +//! 两条命令都只做「解析参数 → 造一个 [`Job`] → 调 `check` / `apply` → 排版输出」， +//! 版本比较、渠道准入、清单校验、长度/SHA256 双检、原子替换全在 `core::update` +//! （GUI 走的是同一个 `Job`，见 `crates/presenter/src/host/update.rs`）。 +//! +//! 三条不许折叠的边界： +//! +//! | 情形 | 输出 | +//! |---|---| +//! | 已是最新 | `status=up_to_date`（退出码 0） | +//! | 有可装的更新 | `status=available`（退出码 0；`apply` 才动文件） | +//! | 检查失败 | **错误**（退出码 1，`code=update_check_failed`）——绝不说成「已是最新」 | +//! +//! 还有一条单独报的：`missing_artifact`（有更高版本但里面没有本平台的产物）。那是发布侧的漏项， +//! 同样不许说成「已是最新」。 +//! +//! `apply` 默认替换**本进程的 exe**（`Job::for_process`）；`--dest` 可以钉到别的路径（取证用）。 +//! +//! # 测试通道（M169） +//! +//! 想在没有稳定 Release 的情况下整环验一遍，得用**专门编出来的验收二进制**： +//! +//! ```text +//! cargo build --release --features update-test-source # 官方发布构建不带这个 feature +//! ULL_UPDATE_DIR= ULL_UPDATE_TEST_SOURCE=1 ./ull update check +//! ``` +//! +//! 三档全给才生效（feature 默认关 = 官方二进制里没有这条路径；带 feature 时还要两档环境变量， +//! 判据见 `core::update::job`）。这时 `--json` 的 `source` 是 `file:`、`test_source` 是 +//! `true`，人读输出另有一行点名。它不是第二个更新源：没有设置键、也没有命令行参数。 +//! +//! ⚠ **验收时必须给 `--dest`**：不给就是替换本进程的 exe。自动化用例里的「本进程」是测试二进制， +//! 去掉 `--dest` 会把它真改名换掉（`crates/cli/tests/update_e2e_test.rs` 的注释写了这件事）。 + +use std::path::PathBuf; +use std::sync::Arc; + +use serde_json::json; +use unlucky_core::download::DownloadEngine; +use unlucky_core::update::{default_source, Applied, CheckOutcome, Job, UpdateError, Version}; + +use crate::cli::{UpdateApplyArgs, UpdateCheckArgs}; +use crate::context::Ctx; +use crate::error::CliError; +use crate::output::{Outcome, Report}; + +/// D50：先只发 stable。 +const CHANNEL: unlucky_core::update::Channel = unlucky_core::update::Channel::Stable; + +/// 本进程版本（与 `ull --version` 同源）。 +fn current_version() -> Result { + let text = env!("CARGO_PKG_VERSION"); + Version::parse(text) + .map_err(|error| CliError::internal("bad_version", format!("编译期版本号不合法：{error}"))) +} + +/// 自更新的下载引擎：与 `install` / `java` / `pack` 同一条装配（参数来自 +/// [`crate::download`]，设置读数与落点在那边）。 +/// +/// 自更新只下**一个** artifact（`update::github` 的 `fetch_artifact` → 单次 `engine.download`）， +/// 所以并发的差别在这条路径上不可观测；真正随设置变的是**每源重试次数**与**gh-proxy 前缀**—— +/// 那正是「设置说真话」的两维。单独留这个接缝是为了让用例能逐命令打点（变异时只有它红）。 +pub(crate) fn engine(ctx: &Ctx) -> Arc { + super::install::build_engine(ctx) +} + +/// 造一个内核 job（源 = GitHub / `ULL_UPDATE_DIR`，暂存 = 数据根缓存，目标 = 本进程 exe）。 +fn job(ctx: &Ctx, dest: Option) -> Job { + let engine = engine(ctx); + let job = Job::for_process(default_source(engine), &ctx.layout().cache()); + match dest { + Some(dest) => job.with_dest(dest), + None => job, + } +} + +/// 失败 → CLI 错误（`code` 说「哪条命令的哪一类失败」，`detail.kind` 说**到底为什么**）。 +/// +/// `--json` 信封示例（复审 P3-3 之后的样子）： +/// +/// ```json +/// {"ok":false,"error":{"code":"update_apply_failed","kind":"user","message":"应用更新失败（digest_mismatch）：…", +/// "hint":"…","detail":{"kind":"digest_mismatch","retryable":true}}} +/// ``` +/// +/// 为什么要两层：`code` 是命令级的（脚本据此决定「要不要提示用户重跑」），`detail.kind` 是 +/// **底层原因**（`digest_mismatch` / `network` / `invalid_manifest` / `io` …，据此决定「重试有没有意义」）。 +/// 以前原因只写在人读 message 里，脚本不解析散文就分不出来。 +fn failure(code: &'static str, action: &str, error: &UpdateError) -> CliError { + // 签名类错误单独给一句：它们**不可重试**，而且绝不能靠「换个源/跳过校验」绕过——绕过一次 + // 就等于把信任根拆了（见 `core::update::signature` 的文件头）。 + let hint = if error.kind.is_signature() { + concat!( + "清单签名没通过，重试没有意义：signature_missing = 发布侧漏了签名；", + "signature_unknown_key / keyring_empty = 本构建的信任表里没有这把钥（升级启动器或等发布侧换钥）；", + "signature_invalid = 签名之后清单被改过。别绕过校验，等发布侧修" + ) + } else if error.is_retryable() { + "网络/占用类失败，过一会儿重试一次通常就好" + } else { + "这不是瞬时失败：清单或版本号本身有问题，等发布侧修" + }; + CliError::user( + code, + format!("{action}失败（{}）：{error}", error.kind.as_str()), + ) + .with_detail(json!({ + "kind": error.kind.as_str(), + "retryable": error.is_retryable(), + })) + .with_hint(hint) +} + +/// 这个源是不是测试通道（判据派生自**实际用了哪个源**，不是回读环境变量： +/// `DirSource` 的 id 是 `file:`，GitHub 源是 `github:/`）。 +fn is_test_source(source_id: &str) -> bool { + source_id.starts_with("file:") +} + +/// 测试通道的点名行（只在真走了本地目录源时出现）。文案里点明**这是验收构建**：官方发布二进制 +/// 没有这条路径（`update-test-source` 默认关），所以出现这一行就说明手上这份不是官方产物。 +fn test_channel_note(source: &str) -> String { + format!( + "测试通道生效：源 = {source}（本地目录，不是 GitHub Releases；本二进制带 \ + `update-test-source` feature 编出来，官方发布构建不含这条路径）" + ) +} + +/// `ull update check`：只查、不动任何文件。 +/// +/// # Errors +/// +/// 清单取不到 / 清单不合法 / 渠道不符 → 用户错误（退出码 1）。 +pub fn check(ctx: &Ctx, _args: &UpdateCheckArgs) -> Result { + let current = current_version()?; + let job = job(ctx, None); + let outcome = job + .check(¤t, CHANNEL) + .map_err(|error| failure("update_check_failed", "检查更新", &error))?; + Ok(Outcome::new(report_of(¤t, job.source_id(), &outcome))) +} + +/// `ull update apply`：复查 → 下载 → 双检 → 替换（失败自动清理/回滚）。 +/// +/// # Errors +/// +/// 复查、取包、校验、替换任一步失败 → 用户错误（退出码 1）。 +pub fn apply(ctx: &Ctx, args: &UpdateApplyArgs) -> Result { + let current = current_version()?; + let job = job(ctx, args.dest.clone()); + let dest = job.dest().display().to_string(); + match job + .apply(¤t, CHANNEL) + .map_err(|error| failure("update_apply_failed", "应用更新", &error))? + { + Applied::Installed { receipt, version } => { + let backup = receipt + .backup + .as_ref() + .map(|path| path.display().to_string()); + let source = job.source_id(); + let test_source = is_test_source(source); + let mut human = vec![ + format!("已下载并校验 v{version}（{} 字节）", receipt.bytes), + format!("已替换：{dest}"), + ]; + human.push(match &backup { + Some(backup) => format!("旧版本备份：{backup}"), + None => "原本没有旧文件（首次落盘）".to_string(), + }); + human.push("下次启动生效（正在运行的进程仍是旧版本）。".to_string()); + if test_source { + human.push(test_channel_note(source)); + } + Ok(Outcome::new(Report::new( + json!({ + "current": current.to_string(), + "channel": CHANNEL.as_str(), + "source": source, + "test_source": test_source, + "status": "installed", + "version": version, + "path": dest, + "bytes": receipt.bytes, + "backup": backup, + }), + human, + ))) + } + Applied::Nothing(outcome) => { + let report = report_of(¤t, job.source_id(), &outcome); + Ok(Outcome::new(Report::new( + json!({ "status": "nothing_to_apply", "check": report.data }), + { + let mut human = + vec!["复查之后没有可应用的更新（已经不是最新版本冲突）".to_string()]; + human.extend(report.human); + human + }, + ))) + } + } +} + +/// 把检查结论排成「人读几行 + `--json` 一份」。 +/// +/// `test_source` 逐条写进 JSON（不只在高亮时写）：脚本据此判断「这一份结论是不是本地夹具给的」， +/// 而判据来自 `source`（实际用了哪个源），所以不会出现「环境变量说关了、输出说开着」。 +fn report_of(current: &Version, source: &str, outcome: &CheckOutcome) -> Report { + let test_source = is_test_source(source); + let base = |status: &str| { + json!({ + "current": current.to_string(), + "channel": CHANNEL.as_str(), + "source": source, + "test_source": test_source, + "status": status, + }) + }; + let mut report = match outcome { + CheckOutcome::UpToDate { latest, .. } => { + let latest = latest.as_ref().map(ToString::to_string); + let mut data = base("up_to_date"); + data["latest"] = json!(latest); + Report::new( + data, + vec![match &latest { + Some(latest) => format!("已是最新：v{current}（渠道 {latest} 内最高）"), + None => format!("已是最新：v{current}（该渠道还没有任何发布）"), + }], + ) + } + CheckOutcome::Available(candidate) => { + let version = candidate.release.version.to_string(); + let forced = candidate.urgency == unlucky_core::update::Urgency::Forced; + let notes = candidate.release.notes.clone().unwrap_or_default(); + let mut human = vec![format!( + "发现新版本 v{version}（当前 v{current}，{} 字节{}）", + candidate.artifact.size, + if forced { "，强制更新" } else { "" } + )]; + if !notes.trim().is_empty() { + human.push(format!("说明：{}", notes.trim())); + } + human.push("用 `%prog% update apply` 下载并应用（下次启动生效）".to_string()); + Report::new( + json!({ + "current": current.to_string(), + "channel": CHANNEL.as_str(), + "source": source, + "test_source": test_source, + "status": "available", + "version": version, + "size": candidate.artifact.size, + "forced": forced, + "notes": notes, + "target": candidate.artifact.target.as_str(), + }), + human, + ) + } + CheckOutcome::MissingArtifact { release } => { + let version = release.version.to_string(); + Report::new( + json!({ + "current": current.to_string(), + "channel": CHANNEL.as_str(), + "source": source, + "test_source": test_source, + "status": "missing_artifact", + "version": version, + "target": unlucky_core::update::Target::current().as_str(), + }), + vec![format!( + "v{version} 已发布，但没有为本平台（{}）提供产物——这是发布侧漏项，不是「已是最新」", + unlucky_core::update::Target::current().as_str() + )], + ) + } + }; + if test_source { + report.human.push(test_channel_note(source)); + } + report +} diff --git a/crates/cli/src/context.rs b/crates/cli/src/context.rs new file mode 100644 index 0000000..3c46d49 --- /dev/null +++ b/crates/cli/src/context.rs @@ -0,0 +1,256 @@ +//! 数据根解析与目录视图。 +//! +//! 三模式（D6 / `04-data-and-config.md` §1）全部交给 `core::platform::data_dir`： +//! - `--data-dir ` → custom 模式（`/.ULL` + `/.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` 的路径（`/.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, + /// `--data-dir` 是否由命令行强制指定（此时数据根不看 `core.*` 键）。 + data_dir_forced: bool, +} + +impl Ctx { + /// 解析数据根。 + /// + /// # Errors + /// + /// `--data-dir` 非绝对路径、exe 目录拿不到、`redirect.json` 损坏等返回用户错误。 + pub fn resolve(globals: &Globals) -> Result { + 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) -> Result { + 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 { + 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` 也真的会影响 + /// 下次解析；其余键走解析后的数据根（`/.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() + } + + /// 会话根（M188 起 = `/logs`；launch 的事件流与索引都在这下面）。 + #[must_use] + pub fn sessions_root(&self) -> PathBuf { + self.layout().sessions_root() + } + + /// 会话日志的**旧家**（`/data/agent/sessions`）：只读兼容，M188 起不再往里写。 + #[must_use] + pub fn legacy_sessions_root(&self) -> PathBuf { + self.layout().agent_sessions() + } + + /// 启动器日志目录（`/logs`：`launcher.log` + `game/` 会话）。 + #[must_use] + pub fn logs_dir(&self) -> PathBuf { + self.layout().logs() + } + + /// 账户数据目录（`data/auth/`：`accounts.json` + `credentials.dat`）。 + #[must_use] + pub fn auth_data(&self) -> PathBuf { + self.layout().auth_data() + } + + /// 会话索引文件（`/game/index.jsonl`）。 + #[must_use] + pub fn session_index(&self) -> PathBuf { + unlucky_core::launch::session_index::index_path(&self.sessions_root()) + } + + /// 旧家的会话索引（`data/agent/sessions/game/index.jsonl`）：只读兼容。 + #[must_use] + pub fn legacy_session_index(&self) -> PathBuf { + unlucky_core::launch::session_index::index_path(&self.legacy_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 { + os::notes(&self.os) + } +} + +/// 便携目录的 `launcher.json` → 三模式请求。 +/// +/// 只读 `effective`（文件值 → 默认值），坏文件也永不 panic（`SettingStore` 的加载降级）。 +/// 路径由 [`portable_config_path`] 决定，`config get/set` 用的是同一个函数（同源）。 +fn request_from_portable_config(exe_dir: Option) -> 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/download.rs b/crates/cli/src/download.rs new file mode 100644 index 0000000..050395f --- /dev/null +++ b/crates/cli/src/download.rs @@ -0,0 +1,57 @@ +//! CLI 侧的下载引擎：把 CLI 自己的 `launcher.json` 接到 core 的下载调优上（M203）。 +//! +//! `install` / `java` / `pack` 三条命令此前各自 `DownloadEngine::new(EngineConfig::default(), …)`： +//! 用户在设置里配的 `download.concurrency` / `download.retry_limit` / `download.gh_proxy` 一概不生效。 +//! M193 把出厂并发从 64 改成 8 之后，它们还**静默**跟着降了——「设置项说假话」的同期病灶 +//! （`docs/download-settings.md` §3.1 记着这三条 ❌）。第四条路径 `update`（自更新）复用 `install` +//! 的装配，也随之吃设置；它只下一个 artifact，所以并发在那条路径上不可观测。 +//! +//! 现在四条一律经 [`engine`] 取引擎（进程内共享，见 `core::download::shared`）： +//! +//! ```text +//! <数据根>/config/launcher.json（与 `ull config set` 同一份） → setting store → DownloadTuning +//! （默认值/夹取/回落在 core） +//! → shared::engine_with_tuning(, tuning) → 引擎的 Semaphore / attempts_for() +//! ``` +//! +//! **回落是静默的**：`SettingStore::load` 永不失败（坏值只进 `problems()`）；类型不对 → `None`， +//! 越界 → `DownloadTuning::from_settings` 的区间过滤。两种情况都落成出厂值，**不报错、不中断安装**。 + +use std::sync::Arc; + +use unlucky_core::download::config::{ + DownloadTuning, KEY_CONCURRENCY, KEY_GH_PROXY, KEY_RETRY_LIMIT, +}; +use unlucky_core::download::{shared, DownloadEngine}; +use unlucky_core::setting::keys::launcher_schema; +use unlucky_core::setting::store::SettingStore; + +use crate::context::Ctx; + +/// 从 CLI 自己的 setting store 读下载调优（`launcher.json` 的三个 `download.*` 键）。 +/// +/// 读的是 `ctx.launcher_config()`——与 `ull config set download.concurrency` 的落点同一份文件 +/// （设置键的落点分流见 [`Ctx::setting_path_for`]）。gh-proxy 空串 = 跟随内置默认，**不是**关。 +#[must_use] +pub(crate) fn tuning(ctx: &Ctx) -> DownloadTuning { + let store = SettingStore::load(ctx.launcher_config(), launcher_schema()); + let doc = store.doc(); + let gh_proxy = doc + .effective_str(KEY_GH_PROXY) + .unwrap_or_default() + .to_string(); + DownloadTuning::from_settings( + doc.effective_i64(KEY_CONCURRENCY), + doc.effective_i64(KEY_RETRY_LIMIT), + Some(gh_proxy.as_str()), + ) +} + +/// 建该数据根的下载引擎：参数来自 [`tuning`]，引擎本体由 core 按缓存根共享。 +#[must_use] +pub(crate) fn engine(ctx: &Ctx) -> Arc { + shared::engine_with_tuning(ctx.layout().cache(), tuning(ctx)) +} + +#[cfg(test)] +mod tests; diff --git a/crates/cli/src/download/tests.rs b/crates/cli/src/download/tests.rs new file mode 100644 index 0000000..4fe04b5 --- /dev/null +++ b/crates/cli/src/download/tests.rs @@ -0,0 +1,266 @@ +//! [`super`] 的单测（M203）：`launcher.json` 的 `download.*` 真的进到四条命令拿到的引擎里 +//! （`install` / `java` / `pack` / `update`——`update` 复用 `install` 的装配，自更新只下一个 +//! artifact，所以并发在那条路径上不可观测，随设置变的是每源重试次数与 gh-proxy 前缀）。 +//! +//! 断言读的是**引擎的真实字段**——`config().max_concurrency` 与 `Semaphore` 的 +//! `available_permits()`（`concurrency_probe`）——不是「函数被调用过」：后者在回落写错、 +//! 或者命令又自建了一个裸引擎时照样绿。gh-proxy 那一条断言的是**候选链**（真行为），不是配置值。 + +use std::path::{Path, PathBuf}; +use std::sync::atomic::{AtomicU64, Ordering}; +use std::time::{SystemTime, UNIX_EPOCH}; + +use serde_json::{json, Value}; +use unlucky_core::download::config::{ + DownloadTuning, DEFAULT_MAX_ATTEMPTS_PER_SOURCE, DEFAULT_MAX_CONCURRENCY, KEY_CONCURRENCY, +}; +use unlucky_core::download::types::{DownloadRequest, ResourceKind}; +use unlucky_core::download::DownloadEngine; +use unlucky_core::setting::keys::launcher_schema; +use unlucky_core::setting::store::SettingStore; + +use crate::cli::Globals; +use crate::context::Ctx; + +/// 一次性临时目录（cli 没有 dev-dependency 的 tempfile；与 `commands/config/tests.rs` 同一手法）。 +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-cli-download-{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); + } +} + +/// 数据根钉在临时目录里：`launcher.json` 落在 `/.ULL/config/launcher.json`。 +fn ctx_at(dir: &TempDir) -> Ctx { + let globals = Globals { + data_dir: Some(dir.path().to_path_buf()), + ..Globals::default() + }; + Ctx::resolve(&globals).expect("解析数据根") +} + +/// 直接写 `launcher.json`——落点用 [`Ctx::setting_path_for`]（`ull config set` 用的那个表达式）， +/// **不是**实现读侧用的 `ctx.launcher_config()`。 +/// +/// 两个表达式今天指向同一份文件（`download.*` 不是数据根键 ⇒ 回落 `launcher_config()`），但写侧 +/// 走「用户改配置那条路」的 API，实现哪天改读别的文件时这条用例会红，而不是跟着一起漂移。 +fn write_launcher_config(ctx: &Ctx, document: Value) -> PathBuf { + let path = ctx.setting_path_for(KEY_CONCURRENCY); + std::fs::create_dir_all(path.parent().expect("配置目录")).expect("建配置目录"); + std::fs::write(&path, serde_json::to_vec(&document).expect("序列化")) + .expect("写 launcher.json"); + path +} + +/// 「引擎真的按这个并发跑」：配置字段 + 闸门许可数，两处都读真实值。 +fn assert_concurrency(engine: &DownloadEngine, expected: usize, case: &str) { + assert_eq!( + engine.config().max_concurrency, + expected, + "{case}：`EngineConfig` 里的并发" + ); + assert_eq!( + engine.concurrency_probe(), + expected, + "{case}：`Semaphore` 真实许可数" + ); +} + +/// **`install` 吃设置**：`download.concurrency` 改了就变；同一次进程里再改一次也立刻变（不是只读一次）。 +/// +/// 抓得住的变异：`commands::install::build_engine` 换回裸 `EngineConfig::default()` ⇒ 3 / 5 两处红。 +/// 抓不住的：真实下载时「只有 3 条连接在飞」的时序（离线验不了，见报告「没验的部分」）。 +#[test] +fn install_engine_takes_the_concurrency_from_the_setting_store() { + let dir = TempDir::new("install"); + let ctx = ctx_at(&dir); + // 没有 launcher.json = 没配过 ⇒ 出厂值（这也是「回落」的第一档）。 + assert_concurrency( + &crate::commands::install::build_engine(&ctx), + DEFAULT_MAX_CONCURRENCY, + "未配置", + ); + + write_launcher_config(&ctx, json!({ "download": { "concurrency": 3 } })); + assert_concurrency( + &crate::commands::install::build_engine(&ctx), + 3, + "concurrency=3", + ); + + write_launcher_config(&ctx, json!({ "download": { "concurrency": 5 } })); + assert_concurrency( + &crate::commands::install::build_engine(&ctx), + 5, + "concurrency=5", + ); +} + +/// **`java` 吃设置**：并发与每个源的尝试次数都进引擎。 +/// +/// 抓得住的变异：`commands::java::build_engine` 换回裸 `EngineConfig::default()` ⇒ 探针停在 8、次数停在 3，红。 +#[test] +fn java_engine_takes_the_concurrency_and_retry_from_the_setting_store() { + let dir = TempDir::new("java"); + let ctx = ctx_at(&dir); + write_launcher_config( + &ctx, + json!({ "download": { "concurrency": 3, "retry_limit": 4 } }), + ); + + let engine = crate::commands::java::build_engine(&ctx); + assert_concurrency(&engine, 3, "concurrency=3"); + assert_eq!( + engine.config().max_attempts_per_source, + 4, + "retry_limit=4 要真的落到引擎上（出厂是 3）" + ); +} + +/// **`pack` 吃设置**（四条命令各有一条独立断言：把任意一处改回裸引擎，只有那一条红）。 +/// +/// 抓得住的变异：`commands::pack::build_engine` 换回裸 `EngineConfig::default()` ⇒ 2 处红。 +#[test] +fn pack_engine_takes_the_concurrency_from_the_setting_store() { + let dir = TempDir::new("pack"); + let ctx = ctx_at(&dir); + write_launcher_config(&ctx, json!({ "download": { "concurrency": 2 } })); + assert_concurrency( + &crate::commands::pack::build_engine(&ctx), + 2, + "concurrency=2", + ); +} + +/// **`update` 吃设置**（第 4 条路径，`commands/update.rs::engine`）：自更新也只拿出厂值是不行的。 +/// +/// 这条路径上「并发」实际不可观测（自更新只下**一个** artifact，闸门开 1 还是 8 都只有一条连接）， +/// 但引擎参数是同一处装配出来的，用并发打点最省事；真正随设置变的是每源重试次数与 gh-proxy 前缀。 +/// 抓得住的变异：`commands::update::engine` 换回裸 `EngineConfig::default()` ⇒ 4 ≠ 8 处红，另五条绿。 +#[test] +fn update_engine_takes_the_concurrency_from_the_setting_store() { + let dir = TempDir::new("update"); + let ctx = ctx_at(&dir); + write_launcher_config(&ctx, json!({ "download": { "concurrency": 4 } })); + assert_concurrency(&crate::commands::update::engine(&ctx), 4, "concurrency=4"); +} + +/// **`gh_proxy` 的 CLI 侧闭环**：手写 `"off"` ⇒ 候选链里真的没有 gh-proxy（读的是 `plan()`，不是配置值）。 +/// +/// 两段式：先在镜像优先的地区档案下确认**出厂**（空串 = 跟随内置）确实生成 gh-proxy 候选，再把它 +/// 改成 `off` 确认候选消失——只断言后者的话，「本来就没有候选」会让用例白绿。 +/// 抓得住的变异：`download::tuning` 不读 `KEY_GH_PROXY`（传 `None`）⇒ 第二段仍有 gh-proxy 候选，红； +/// 把空串当成关（`gh_proxy_override("")` 返回 `Off`）⇒ 第一段没有候选，红（回落用例的 +/// `tuning == default` 同时红——两处都该红，实测如此）。 +/// 抓不住的：真实网络下这个前缀能不能通（离线只验候选链的**生成**）。 +#[test] +fn the_gh_proxy_setting_reaches_the_candidate_chain() { + use unlucky_core::download::cache::now_ms; + use unlucky_core::download::region::{store_cached, RegionProfile}; + + let dir = TempDir::new("ghproxy"); + let ctx = ctx_at(&dir); + // gh-proxy 只在「镜像优先」的地区档案下生成候选：先把该数据根的 region.json 钉住。 + let cache_root = ctx.layout().cache(); + store_cached( + &cache_root.join("region.json"), + &RegionProfile::mirror_first(now_ms()), + ) + .expect("地区档案"); + let url = "https://github.com/o/r/releases/download/v1/a.jar"; + let chain = |ctx: &Ctx| -> Vec { + let request = + DownloadRequest::new(ResourceKind::Other, url, ctx.layout().cache().join("a.jar")); + crate::download::engine(ctx) + .plan(&request, 0) + .into_iter() + .map(|candidate| candidate.url) + .collect() + }; + let has_gh_proxy = |chain: &[String]| chain.iter().any(|url| url.contains("gh-proxy")); + + // 出厂（未配置）：空串 = 跟随内置默认 ⇒ 有 gh-proxy 候选。 + assert!(has_gh_proxy(&chain(&ctx)), "出厂该套内置前缀"); + // 写 off：候选里不该再有 gh-proxy（其余候选仍在）。 + write_launcher_config(&ctx, json!({ "download": { "gh_proxy": "off" } })); + let off = chain(&ctx); + assert!(!has_gh_proxy(&off), "off 档还有 gh-proxy 候选：{off:?}"); + assert!(!off.is_empty(), "关掉加速不等于没有候选：{off:?}"); +} + +/// **反向断言**：键缺失 / 越界 / 负数 / 类型不对 ⇒ 回落出厂值，而且回落是**静默的**。 +/// +/// 「静默」在这里是结构性的：`crate::download::engine` 的返回类型没有错误通道，坏设置只进 +/// `SettingStore::problems()`，调用方（安装流程）连一个 `?` 都不用加——`ull install` 不会因为一条 +/// 写坏的设置而中断，只是按出厂值跑。 +/// +/// 抓得住的变异：删掉 `DownloadTuning::from_settings` 的区间过滤 ⇒ 9_999 那条把许可数变成 64，红； +/// 把 CLI 的读数改成 `expect`/报错 ⇒ 坏值文件这几档 panic 或编译不过，红。 +/// 抓不住的：`problems()` 的内容与措辞（那是 core 的 `setting` 模块，本用例只借它证明文件真的坏）。 +#[test] +fn missing_or_illegal_values_fall_back_to_the_factory_defaults_silently() { + let dir = TempDir::new("fallback"); + let ctx = ctx_at(&dir); + assert_eq!( + super::tuning(&ctx), + DownloadTuning::default(), + "没有 launcher.json 就该是出厂调优" + ); + + for (case, document) in [ + ( + "越界", + json!({ "download": { "concurrency": 9_999, "retry_limit": 99 } }), + ), + ( + "负数", + json!({ "download": { "concurrency": -4, "retry_limit": -1 } }), + ), + ( + "类型不对", + json!({ "download": { "concurrency": "八", "retry_limit": "很多" } }), + ), + ] { + let written = write_launcher_config(&ctx, document); + // 先证明这份文件**真的**是坏的（否则「回落」只是键不存在，用例就成了空断言）。 + let store = SettingStore::load(&written, launcher_schema()); + assert!( + !store.problems().is_empty(), + "{case}：这份文件该被判为有问题" + ); + + assert_eq!( + super::tuning(&ctx), + DownloadTuning::default(), + "{case}：坏值必须回落出厂调优" + ); + let engine = crate::commands::install::build_engine(&ctx); + assert_concurrency(&engine, DEFAULT_MAX_CONCURRENCY, case); + assert_eq!( + engine.config().max_attempts_per_source, + DEFAULT_MAX_ATTEMPTS_PER_SOURCE, + "{case}：尝试次数也回落出厂值" + ); + } +} diff --git a/crates/cli/src/error.rs b/crates/cli/src/error.rs new file mode 100644 index 0000000..cf96719 --- /dev/null +++ b/crates/cli/src/error.rs @@ -0,0 +1,198 @@ +//! 错误形状与退出码。 +//! +//! 约定（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, + /// `--json` 信封里 `error.detail` 的结构化载荷（可选）。 + /// + /// 为什么要有它：`code` 只分到「哪条命令的哪一类失败」（`update_apply_failed`）， + /// 而脚本真正要分流的是**底层原因**（`digest_mismatch` / `network` / `invalid_manifest`）。 + /// 那些原因以前只出现在人读 `message` 里（`应用更新失败（digest_mismatch）：…`）， + /// 脚本不解析散文就分不出来。`detail` 把它们挪进机器可读字段。 + /// + /// **装箱**：`serde_json::Value` 有 32 字节，直接塞进 `CliError` 会把它顶到 144 字节， + /// 于是所有 `Result<_, CliError>` 都触发 `clippy::result_large_err`（阈值 128）。 + /// `Option>` 只占 8 字节，错误对象保持轻量。 + detail: Option>, +} + +/// 把模板里的程序名占位符渲染掉（M82 r3）。 +/// +/// 渲染放在**构造时**，而不是打印时：错误有两条出口（人类可读 stderr、`--json` 信封）， +/// 只在打印处渲染会漏掉 JSON 那条（r2 就是这么漏的，`%prog%` 直接出现在了 JSON 里）。 +fn render(text: impl Into) -> String { + crate::cli::program::fill(&text.into()) +} + +impl CliError { + /// 用法错误（参数不对）。 + #[must_use] + pub fn usage(message: impl Into) -> Self { + Self { + kind: ErrorKind::User, + code: "usage", + message: render(message), + hint: None, + detail: None, + } + } + + /// 用户错误，带稳定 code。 + #[must_use] + pub fn user(code: &'static str, message: impl Into) -> Self { + Self { + kind: ErrorKind::User, + code, + message: render(message), + hint: None, + detail: None, + } + } + + /// 内部错误，带稳定 code。 + #[must_use] + pub fn internal(code: &'static str, message: impl Into) -> Self { + Self { + kind: ErrorKind::Internal, + code, + message: render(message), + hint: None, + detail: 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) -> Self { + self.hint = Some(render(hint)); + self + } + + /// 补一段**机器可读**的细节（`--json` 里落在 `error.detail`）。 + /// + /// 约定：`detail` 里只放脚本要分流的结构化字段（底层分类 id、可重试位、目标路径…）， + /// 人话仍在 `message` / `hint` 里——两条出口各管一件事，别把散文塞进 `detail`。 + #[must_use] + pub fn with_detail(mut self, detail: Value) -> Self { + self.detail = Some(Box::new(detail)); + self + } + + /// 机器可读细节（没有则为 `None`）。 + #[must_use] + pub fn detail(&self) -> Option<&Value> { + self.detail.as_deref() + } + + /// 错误大类。 + #[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()); + } + if let Some(detail) = &self.detail { + error["detail"] = (**detail).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..8b99da0 --- /dev/null +++ b/crates/cli/src/lib.rs @@ -0,0 +1,29 @@ +//! 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`]； +//! - [`download`]：CLI 侧的下载引擎（设置 store → core 调优，`install`/`java`/`pack` 共用）； +//! - [`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 download; +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 = 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 { + 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, +} + +impl Report { + /// 构造（人类可读行在这里就把程序名占位符渲染掉，见 [`crate::cli::program::PLACEHOLDER`]）。 + #[must_use] + pub fn new(data: Value, human: Vec) -> 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, + /// 命令自定义的退出码；`None` = 0（绝大多数命令）。 + /// + /// 只有"结果多态且脚本要分流"的命令才用得上：`ull pack import` 的三态是 + /// `0` 成功 / `3` 部分成功 / `1` 失败，光靠 0/1 分不出来。加这个字段而不是让命令 + /// 自己 `std::process::exit`，是为了让**输出照常刷新**（绕过 runner 的输出刷新会把 + /// "输出没刷完就退出"这种 bug 装进 CLI）。 + pub exit_code: Option, +} + +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) -> 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 = Vec::new(); + let mut err: Vec = 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 ...` 命令。 +fn cli(dir: &TempDir, tail: &[&str]) -> Vec { + 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 { + 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 = 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], ""); + // 真凭据位置：离线占位 token 是随机 32 hex，输出里必须只剩脱敏占位。 + let token_at = argv + .iter() + .position(|arg| arg == "--accessToken") + .expect("有 --accessToken"); + assert_eq!(argv[token_at + 1], ""); + assert!(out.contains("")); + // 命令行与展示行里不该有任何 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/adopt_test.rs b/crates/cli/tests/adopt_test.rs new file mode 100644 index 0000000..c281f94 --- /dev/null +++ b/crates/cli/tests/adopt_test.rs @@ -0,0 +1,332 @@ +//! M221 CLI 端到端：`ull instances scan` / `ull instances adopt` 的真实入口（解析 → 执行 → 两条输出）。 +//! +//! 用的都是**真磁盘**数据根（`support::TempDir`）+ 一份「别的启动器铺好的」`.minecraft`。 +//! 每条用例都断言外部文件哈希/mtime 不变（`fixture::assert_unchanged`）， +//! 因为「只登记不搬文件」是本 mission 的核心承诺。 + +#[path = "adopt_test/cli_surface.rs"] +mod cli_surface; +#[path = "adopt_test/collision_cases.rs"] +mod collision_cases; +#[path = "adopt_test/fixture.rs"] +mod fixture; +#[path = "support/mod.rs"] +mod support; + +use std::path::Path; + +use support::{parse_json, run_cli, TempDir}; + +use crate::fixture::{assert_unchanged, foreign_data_root, snapshot, snapshot_opt, Node}; + +/// 缺省登记：落 ULL 数据区的独立目录，隔离档 `custom`，**不沿用全局 `isolated`**。 +/// +/// 抓得住： +/// - 缺省沿用全局 `isolated`（运行目录会变成 `versions/1.20.1`，第二条断言会红）—— +/// 这是本 mission 点名的最容易漏的一条； +/// - 命令只登记不输出（`--json` 缺 `instance`）； +/// - 登记过程写了外部 `.minecraft`（哈希断言）。 +/// +/// 抓不住：GUI 是否也能触发同一条路（GUI 接线是后续 mission）。 +#[test] +fn adopt_without_isolation_uses_a_separate_run_dir_and_keeps_global_isolated_out_of_it() { + let dir = TempDir::new("adopt-default"); + let root = dir.path(); + foreign_data_root(root); + // 全局档显式写成 isolated（D20 的缺省）：登记**不许**继承它去踩别人的版本目录。 + set_global_isolated(&dir); + let minecraft = root.join(".minecraft"); + let before = snapshot(&minecraft); + + let (code, stdout, stderr) = run_cli(&[ + "instances", + "adopt", + "1.20.1", + "--json", + "--data-dir", + &dir.arg(), + ]); + assert_eq!(code, 0, "stdout={stdout}\nstderr={stderr}"); + let after = snapshot(&minecraft); + assert_unchanged(&before, &after, "adopt 之后"); + + let value = parse_json(&stdout); + let instance = &value["data"]["instance"]; + assert_eq!(instance["isolation"], "custom"); + assert_eq!(instance["run_dir_source"], "instance_dir"); + let run_dir = instance["run_dir"].as_str().expect("run_dir"); + assert!( + run_dir.contains("instances"), + "缺省运行目录应落 ULL 数据区：{run_dir}" + ); + assert!( + !Path::new(run_dir).starts_with(&minecraft), + "缺省运行目录不许落进别人的 .minecraft：{run_dir}" + ); + assert!( + !run_dir.ends_with("versions/1.20.1") && !run_dir.ends_with("versions\\1.20.1"), + "不许沿用全局 isolated 的 versions/：{run_dir}" + ); + assert_eq!(instance["created"], true); + + // 再走一次 `instances list`：档案真的进去了（不是只写了实例文件）。 + let (code, stdout, _) = run_cli(&["instances", "list", "--json", "--data-dir", &dir.arg()]); + assert_eq!(code, 0); + let listed = parse_json(&stdout); + assert_eq!(listed["data"]["instances"][0]["version_id"], "1.20.1"); + assert_eq!(listed["data"]["instances"][0]["version_present"], true); +} + +/// 登记之后 `launch --dry-run` 的 `--gameDir` 就是选定的运行目录（本 mission 的功能落点）。 +/// +/// 抓得住：登记把隔离档写错（`inherit`）⇒ 启动派生坚持全局 `isolated`，`game_dir` 变成 +/// `versions/1.20.1`（第二条断言会红）；`gameDir` 没进启动计划。 +/// 抓不住：真进程是否真的用这个 CWD（要真跑游戏，本 mission 不跑）。 +#[test] +fn the_launch_plan_points_game_dir_at_the_chosen_run_dir() { + let dir = TempDir::new("adopt-launch"); + let root = dir.path(); + foreign_data_root(root); + set_global_isolated(&dir); + + let (code, stdout, stderr) = run_cli(&[ + "instances", + "adopt", + "1.20.1", + "--json", + "--data-dir", + &dir.arg(), + ]); + assert_eq!(code, 0, "stdout={stdout}\nstderr={stderr}"); + let adopted = parse_json(&stdout); + let run_dir = adopted["data"]["instance"]["run_dir"] + .as_str() + .expect("run_dir") + .to_string(); + let instance_id = adopted["data"]["instance"]["id"] + .as_str() + .expect("instance id") + .to_string(); + + let dir_arg = dir.arg(); + let args = [ + "launch", + instance_id.as_str(), + "--dry-run", + "--json", + "--data-dir", + dir_arg.as_str(), + ]; + let (code, stdout, stderr) = run_cli(&args); + assert_eq!(code, 0, "stdout={stdout}\nstderr={stderr}"); + let plan = parse_json(&stdout); + assert_eq!(plan["data"]["game_dir"], run_dir.as_str()); + assert_eq!(plan["data"]["isolation"], "custom"); + assert_eq!(plan["data"]["isolation_source"], "instance"); + let command = plan["data"]["argv"] + .as_array() + .expect("启动计划里应有 argv"); + let game_dir_flag = command + .windows(2) + .find(|pair| pair[0].as_str() == Some("--gameDir")) + .map(|pair| pair[1].as_str().unwrap_or_default().to_string()) + .expect("命令行里应有 --gameDir"); + // `argv` 是**脱敏后**的（主目录 → ``，见 `core::launch::redact`），所以比尾段而不是全等； + // 全等的那条断言在 `data.game_dir` 上（那是未脱敏的权威值）。 + let tail = format!( + "instances/{}", + Path::new(&run_dir) + .file_name() + .expect("运行目录名") + .to_string_lossy() + ); + assert!( + game_dir_flag.ends_with(&tail) || game_dir_flag.ends_with(&tail.replace('/', "\\")), + "--gameDir 必须指向选定的运行目录：{game_dir_flag} 应以 {tail} 结尾" + ); +} + +/// `--isolation shared`：明确选共享 ⇒ 运行目录 = 别人的游戏根，**人读输出必须说出后果**。 +/// +/// 抓得住：shared 档没有告知（stdout 里没有「共用」）、shared 被写成 custom + 自己的目录、 +/// 登记往游戏根写文件（哈希断言）。 +/// 抓不住：用户是否真的看见这句（UI 验收另说）。 +#[test] +fn shared_isolation_states_the_consequence_in_human_output() { + let dir = TempDir::new("adopt-shared"); + let root = dir.path(); + foreign_data_root(root); + let minecraft = root.join(".minecraft"); + let before = snapshot(&minecraft); + + let (code, stdout, stderr) = run_cli(&[ + "instances", + "adopt", + "1.20.1", + "--isolation", + "shared", + "--data-dir", + &dir.arg(), + ]); + assert_eq!(code, 0, "stdout={stdout}\nstderr={stderr}"); + let after = snapshot(&minecraft); + assert_unchanged(&before, &after, "shared 登记之后"); + assert!( + stdout.contains("共用"), + "必须说出「共用别人的 .minecraft」：{stdout}" + ); + assert!(stdout.contains("一个字节都没动"), "{stdout}"); +} + +/// `--dry-run`：只检查不写盘（连配置目录都不建）。 +/// +/// 抓得住：`--dry-run` 真的写了档案或建了运行目录（快照会红）。 +/// 抓不住：`--dry-run` 有没有顺带读了不该读的东西。 +#[test] +fn dry_run_writes_nothing() { + let dir = TempDir::new("adopt-dry"); + let root = dir.path(); + foreign_data_root(root); + let before = snapshot(root); + // 判据强度自检（R5）：快照必须含**目录**节点，否则「凭空建个空目录」看不出来。 + assert!( + matches!(before.get(".minecraft"), Some(Node::Dir { .. })), + "快照缺少目录节点：{:?}", + before.get(".minecraft") + ); + assert!( + before.contains_key(".minecraft/versions"), + "快照缺少 versions 目录节点" + ); + + let (code, stdout, stderr) = run_cli(&[ + "instances", + "adopt", + "1.20.1", + "--dry-run", + "--data-dir", + &dir.arg(), + ]); + assert_eq!(code, 0, "stdout={stdout}\nstderr={stderr}"); + let after = snapshot(root); + assert_unchanged(&before, &after, "--dry-run 之后"); + // `--dry-run` 连 `.ULL` 这个**空目录**都不许建（存在性判据用 `snapshot_opt`）。 + assert!( + snapshot_opt(&root.join(".ULL")).is_none(), + "--dry-run 不该建配置目录" + ); + assert!(stdout.contains("检查通过"), "{stdout}"); + assert!(stdout.contains("没有写任何文件"), "{stdout}"); +} + +/// 坏的版本（缺父）⇒ 退出码 1，`--json` 里带**逐条**问题码。 +/// +/// 抓得住：不合格版本被登记成功（退出码变 0）、问题码被折叠成一句散文（`detail.problems` 缺项）。 +/// 抓不住：用户在原来的启动器里修好之后重试（自然覆盖）。 +#[test] +fn not_adoptable_version_exits_one_with_structured_problems() { + let dir = TempDir::new("adopt-refuse"); + let root = dir.path(); + foreign_data_root(root); + let before = snapshot(root); + + let (code, stdout, _) = run_cli(&[ + "instances", + "adopt", + "1.20.1-orphan", + "--json", + "--data-dir", + &dir.arg(), + ]); + assert_eq!(code, 1, "{stdout}"); + let value = parse_json(&stdout); + assert_eq!(value["ok"], false); + assert_eq!(value["error"]["code"], "adopt_not_adoptable"); + assert_eq!( + value["error"]["detail"]["problems"][0]["code"], + "missing_parent" + ); + let after = snapshot(root); + assert_unchanged(&before, &after, "失败之后"); +} + +/// 重复登记 ⇒ 退出码 1 + 无副作用（档案逐字节不变）。 +/// +/// 抓得住：重复登记当成功（退出码 0）或失败时改了档案。 +/// 抓不住：并发两次登记（没有锁；这不是并发入口）。 +#[test] +fn repeating_the_same_adopt_exits_one_without_side_effects() { + let dir = TempDir::new("adopt-repeat"); + let root = dir.path(); + foreign_data_root(root); + let (code, _, stderr) = run_cli(&["instances", "adopt", "1.20.1", "--data-dir", &dir.arg()]); + assert_eq!(code, 0, "{stderr}"); + let config = root.join(".ULL/config"); + let before = snapshot(&config); + + let (code, stdout, _) = run_cli(&[ + "instances", + "adopt", + "1.20.1", + "--json", + "--data-dir", + &dir.arg(), + ]); + assert_eq!(code, 1, "{stdout}"); + assert_eq!( + parse_json(&stdout)["error"]["code"], + "adopt_already_registered" + ); + let after = snapshot(&config); + assert_unchanged(&before, &after, "重复登记失败之后"); +} + +/// `instances scan`：只读列出候选，坏版本逐条给原因。 +/// +/// 抓得住：扫描变成空列表（那是本 mission 点名不许的行为）、坏版本被静默跳过、 +/// 扫描写了文件。 +/// 抓不住：真实 `.minecraft` 里那些平台特有的怪目录（夹具只覆盖已知形状）。 +#[test] +fn scan_lists_candidates_and_reasons_without_writing() { + let dir = TempDir::new("adopt-scan"); + let root = dir.path(); + foreign_data_root(root); + let before = snapshot(root); + + let (code, stdout, stderr) = + run_cli(&["instances", "scan", "--json", "--data-dir", &dir.arg()]); + assert_eq!(code, 0, "stdout={stdout}\nstderr={stderr}"); + let after = snapshot(root); + assert_unchanged(&before, &after, "scan 之后"); + + let value = parse_json(&stdout); + assert_eq!(value["data"]["counts"]["total"], 2); + assert_eq!(value["data"]["counts"]["adoptable"], 1); + let candidates = value["data"]["candidates"].as_array().expect("candidates"); + let ok = candidates + .iter() + .find(|item| item["version_id"] == "1.20.1") + .expect("有 1.20.1"); + assert_eq!(ok["adoptable"], true); + assert_eq!(ok["jar_present"], true); + let orphan = candidates + .iter() + .find(|item| item["version_id"] == "1.20.1-orphan") + .expect("有 1.20.1-orphan"); + assert_eq!(orphan["adoptable"], false); + assert_eq!(orphan["problems"][0]["code"], "missing_parent"); +} + +/// 把全局隔离档设成 `isolated`（走 schema 校验的正式入口，不手写 launcher.json）。 +fn set_global_isolated(dir: &TempDir) { + let dir_arg = dir.arg(); + let (code, _, stderr) = run_cli(&[ + "config", + "set", + "instances.mode", + "isolated", + "--data-dir", + dir_arg.as_str(), + ]); + assert_eq!(code, 0, "设置全局隔离档失败：{stderr}"); +} diff --git a/crates/cli/tests/adopt_test/cli_surface.rs b/crates/cli/tests/adopt_test/cli_surface.rs new file mode 100644 index 0000000..ddf3c02 --- /dev/null +++ b/crates/cli/tests/adopt_test/cli_surface.rs @@ -0,0 +1,156 @@ +//! 命令面：help 文案、用法错误、错误码——不碰数据或者只碰「拒绝」那条路。 +//! +//! 从 `tests/adopt_test.rs` 拆出来只为守 400 行硬线；搬动是纯搬，断言未变。 + +use crate::support::{parse_json, run_cli, TempDir}; + +use crate::fixture::foreign_data_root; + +/// 运行目录选项的用法错误：一律退出码 1 + `code=usage`（不是内部错误）。 +/// +/// 抓得住：`--isolation custom` 少 `--game-dir` 被默默当成缺省、`shared` 同时给 `--game-dir` +/// 被静默忽略、未知词被当缺省。 +/// 抓不住：提示文案的措辞（只断言 code 与关键字）。 +#[test] +fn isolation_option_misuse_is_a_usage_error() { + let dir = TempDir::new("adopt-usage"); + foreign_data_root(dir.path()); + let cases: Vec> = vec![ + vec!["--isolation", "custom"], + vec!["--isolation", "shared", "--game-dir", "C:/tmp/x"], + vec!["--isolation", "nope"], + vec!["--game-dir", "relative/dir"], + ]; + for extra in cases { + let mut args = vec!["instances", "adopt", "1.20.1", "--json", "--data-dir"]; + let dir_arg = dir.arg(); + args.push(&dir_arg); + args.extend(extra.iter().copied()); + let (code, stdout, stderr) = run_cli(&args); + assert_eq!(code, 1, "args={args:?}\nstdout={stdout}\nstderr={stderr}"); + let value = parse_json(&stdout); + assert_eq!( + value["error"]["code"], "usage", + "args={args:?} 应是用法错误：{stdout}" + ); + } +} + +/// 不存在的版本 ⇒ `adopt_version_not_found`（不联网、不偷偷装一个）。 +/// +/// 抓得住：不存在的 id 被登记成功。 +/// 抓不住：`versions/` 整个不存在时 `scan` 的空结果（core 侧用例覆盖）。 +#[test] +fn unknown_version_reports_not_found() { + let dir = TempDir::new("adopt-unknown"); + foreign_data_root(dir.path()); + let (code, stdout, _) = run_cli(&[ + "instances", + "adopt", + "9.9.9", + "--json", + "--data-dir", + &dir.arg(), + ]); + assert_eq!(code, 1, "{stdout}"); + assert_eq!( + parse_json(&stdout)["error"]["code"], + "adopt_version_not_found" + ); +} + +/// help 里必须有这两条命令（新命令不留「有实现没文档」的状态），且旧命令仍在。 +/// +/// 抓得住：help 漏列 `instances scan` / `instances adopt`（子串断言），或把旧的 +/// `instances launch-args` / `pack import` 弄丢。 +/// 抓不住：帮助文案与真实行为是否一致（那要靠上面的行为用例 + 人读）。 +#[test] +fn help_lists_the_new_subcommands_next_to_the_old_ones() { + let general = unlucky_cli::cli::help::general(); + for needle in [ + "instances scan", + "instances adopt", + "instances list", + "install ", + ] { + assert!(general.contains(needle), "总帮助缺 `{needle}`：\n{general}"); + } + let topic = unlucky_cli::cli::help::topic("instances").expect("help instances 存在"); + for needle in [ + "instances scan", + "instances adopt", + "缺省不沿用全局 isolated", + "一个字节都不写", + ] { + assert!(topic.contains(needle), "help instances 缺 `{needle}`"); + } + // 旧的 `per_version` 字面量只在 core 的 `Isolation::parse` 里被兼容，CLI 词表不接受它。 + let bogus = std::env::temp_dir().join("ull-adopt-help-nonexistent"); + let bogus = bogus.display().to_string(); + let args = [ + "instances", + "adopt", + "1.20.1", + "--isolation", + "per_version", + "--json", + "--data-dir", + bogus.as_str(), + ]; + let (code, stdout, _) = run_cli(&args); + assert_eq!(code, 1, "`per_version` 不是 CLI 词表：{stdout}"); +} + +/// **更高祖先断链**（r2 R2.3 的 CLI 面）：`--data-dir` 指到迁移联接下面的 nested 目录， +/// 联接目标被搬走后 `instances scan` 必须非零 + 结构化错误，不能 `ok:true / total:0`。 +/// +/// 抓得住：只判 `versions`/游戏根两层（更高层断链会漏，这里会看到 exit0 与 total 0）。 +/// +/// 抓不住：真正的权限不足（EACCES）那一支。 +#[cfg(windows)] +#[test] +fn a_dangling_ancestor_is_a_structured_scan_error() { + let dir = TempDir::new("scan-ancestor-dangling"); + let outer = TempDir::new("scan-ancestor-target"); + let real = outer.path(); + let game = real.join("nested").join(".minecraft"); + std::fs::create_dir_all(game.join("versions").join("1.20.1")).expect("建完整版本树"); + std::fs::write( + game.join("versions/1.20.1/1.20.1.json"), + br#"{"id":"1.20.1","type":"release","mainClass":"x","libraries":[]}"#, + ) + .expect("写清单"); + let link = dir.path().join("game-parent-link"); + let ok = std::process::Command::new("cmd") + .args(["/c", "mklink", "/J"]) + .arg(&link) + .arg(real) + .output() + .is_ok_and(|out| out.status.success()); + if !ok { + eprintln!("[link-guard] 建不出目录联接，跳过祖先断链 CLI 用例"); + return; + } + let data_arg = link.join("nested").display().to_string(); + + // 断开之前：能扫到 1 个候选。 + let (code, stdout, stderr) = run_cli(&["instances", "scan", "--json", "--data-dir", &data_arg]); + assert_eq!(code, 0, "stdout={stdout} stderr={stderr}"); + assert_eq!(parse_json(&stdout)["data"]["counts"]["total"], 1); + + // 断开：联接目标改名（入口还在，versions 与游戏根都 NotFound）。 + let moved = dir.path().join("moved-target"); + std::fs::rename(real, &moved).expect("移走联接目标"); + + let (code, stdout, stderr) = run_cli(&["instances", "scan", "--json", "--data-dir", &data_arg]); + assert_eq!( + code, 1, + "祖先断链必须非零退出：stdout={stdout} stderr={stderr}" + ); + let value = parse_json(&stdout); + assert_eq!(value["ok"], false, "{stdout}"); + assert_eq!( + value["error"]["code"], "adopt_versions_unreadable", + "{stdout}" + ); +} diff --git a/crates/cli/tests/adopt_test/collision_cases.rs b/crates/cli/tests/adopt_test/collision_cases.rs new file mode 100644 index 0000000..59616d6 --- /dev/null +++ b/crates/cli/tests/adopt_test/collision_cases.rs @@ -0,0 +1,195 @@ +//! 运行目录**碰撞**的 CLI 面：slug 同名 / 大小写不敏感不许让两个实例共用一个目录（复审 r1 的 R1）。 +//! +//! 从 `tests/adopt_test.rs` 拆出来只为守 400 行硬线；用例体未改。 + +use std::path::Path; + +use crate::support::{parse_json, run_cli, TempDir}; + +use crate::fixture::foreign_data_root; + +/// **slug 碰撞的两个展示名不能绑定同一个物理运行目录**（R1 的 CLI 面）。 +/// +/// 复审 r1 的实跑：`Better MC` 与 `Better-MC` 都成功、两个 UUID、却指向同一个目录， +/// 随后 `launch --dry-run` 的 `--gameDir` 也是同一个。这条把它钉住。 +/// +/// 抓得住： +/// - 登记侧不查已有实例占用的目录（两个 `run_dir` 相同，第一条断言红）； +/// - `launch` 的 `game_dir` 与登记的目录不一致（第三条断言红）。 +/// +/// 抓不住：`pack_dir` 的 slug 规则本身（既有行为，本 mission 不改）。 +#[test] +fn colliding_slug_names_get_separate_run_dirs() { + let dir = TempDir::new("adopt-slug"); + let root = dir.path(); + foreign_data_root(root); + let dir_arg = dir.arg(); + + let first = run_cli(&[ + "instances", + "adopt", + "1.20.1", + "--name", + "Better MC", + "--json", + "--data-dir", + dir_arg.as_str(), + ]); + assert_eq!( + first.0, 0, + "第一次登记应成功：stdout={} stderr={}", + first.1, first.2 + ); + let first = parse_json(&first.1); + let second = run_cli(&[ + "instances", + "adopt", + "1.20.1", + "--name", + "Better-MC", + "--json", + "--data-dir", + dir_arg.as_str(), + ]); + assert_eq!( + second.0, 0, + "第二次登记应成功：stdout={} stderr={}", + second.1, second.2 + ); + let second = parse_json(&second.1); + + let first_dir = first["data"]["instance"]["run_dir"] + .as_str() + .expect("run_dir A") + .to_string(); + let second_dir = second["data"]["instance"]["run_dir"] + .as_str() + .expect("run_dir B") + .to_string(); + assert_ne!(first_dir, second_dir, "两个实例不许共用运行目录"); + assert!( + Path::new(&first_dir).is_dir() && Path::new(&second_dir).is_dir(), + "两个运行目录都要真实存在" + ); + + // 真启动计划（dry-run）也要分开：两条实例各自的 game_dir 不同。 + for (value, expect) in [(&first, &first_dir), (&second, &second_dir)] { + let id = value["data"]["instance"]["id"] + .as_str() + .expect("instance id"); + let args = [ + "launch", + id, + "--dry-run", + "--json", + "--data-dir", + dir_arg.as_str(), + ]; + let (code, stdout, stderr) = run_cli(&args); + assert_eq!( + code, 0, + "stdout={stdout} +stderr={stderr}" + ); + assert_eq!( + parse_json(&stdout)["data"]["game_dir"] + .as_str() + .expect("game_dir"), + expect.as_str() + ); + } +} + +/// **Win32 尾点/尾空格**（r2 R2.1 的 CLI 面）：两次登记 + 两条 `launch --dry-run` 不许落到同一物理目录。 +/// +/// 抓得住：认领目录的尾点/尾空格不归一（第二次默认登记仍拿到 `Foo`，`run_dir` 相同断言红）。 +/// +/// 抓不住：`\?\` verbatim 写法（那本来就不折叠，是另一个目录）。 +#[cfg(windows)] +#[test] +fn win32_trailing_dot_or_space_claims_do_not_share_a_run_dir() { + for suffix in [".", " "] { + let dir = TempDir::new("adopt-win32-alias"); + let root = dir.path(); + foreign_data_root(root); + let dir_arg = dir.arg(); + let claimed = root + .join(".ULL/data/instances") + .join(format!("Foo{suffix}")); + let claimed_arg = claimed.display().to_string(); + + let first = run_cli(&[ + "instances", + "adopt", + "1.20.1", + "--name", + "First", + "--isolation", + "custom", + "--game-dir", + claimed_arg.as_str(), + "--json", + "--data-dir", + dir_arg.as_str(), + ]); + assert_eq!( + first.0, 0, + "custom 登记应成功：stdout={} stderr={}", + first.1, first.2 + ); + let first = parse_json(&first.1); + + let second = run_cli(&[ + "instances", + "adopt", + "1.20.1", + "--name", + "Foo", + "--json", + "--data-dir", + dir_arg.as_str(), + ]); + assert_eq!( + second.0, 0, + "默认登记应成功：stdout={} stderr={}", + second.1, second.2 + ); + let second = parse_json(&second.1); + + let first_dir = first["data"]["instance"]["run_dir"] + .as_str() + .expect("run_dir A") + .to_string(); + let second_dir = second["data"]["instance"]["run_dir"] + .as_str() + .expect("run_dir B") + .to_string(); + assert_ne!( + first_dir, second_dir, + "尾点/尾空格别名不许共用运行目录（suffix={suffix:?}）" + ); + + // 两条启动计划的 --gameDir 也必须分开（argv 已脱敏，比尾段）。 + for (value, expect) in [(&first, &first_dir), (&second, &second_dir)] { + let id = value["data"]["instance"]["id"] + .as_str() + .expect("instance id"); + let args = [ + "launch", + id, + "--dry-run", + "--json", + "--data-dir", + dir_arg.as_str(), + ]; + let (code, stdout, stderr) = run_cli(&args); + assert_eq!(code, 0, "stdout={stdout} stderr={stderr}"); + let plan = parse_json(&stdout); + assert_eq!( + plan["data"]["game_dir"].as_str().expect("game_dir"), + expect.as_str(), + "启动计划必须落在自己的运行目录（suffix={suffix:?}）" + ); + } + } +} diff --git a/crates/cli/tests/adopt_test/fixture.rs b/crates/cli/tests/adopt_test/fixture.rs new file mode 100644 index 0000000..3a3e70d --- /dev/null +++ b/crates/cli/tests/adopt_test/fixture.rs @@ -0,0 +1,81 @@ +//! CLI 侧夹具：一个「别的启动器铺好了 `.minecraft`」的数据根。 +//! +//! 快照工具**复用 core 测试那一份**（`crates/core/tests/adopt/snapshot.rs`，全节点：目录/文件/链接 +//! 各记形状与 mtime）。以前 CLI 自己抄了一份 walk，两份都漏了目录节点——复审 r1 的 R5 正是这个洞， +//! 所以这里直接 `#[path]` 引用同一份源码：判据只有一处，不会再漂。 + +#[path = "../../../core/tests/adopt/snapshot.rs"] +mod snapshot; + +pub use snapshot::{assert_unchanged, snapshot, snapshot_opt, Node}; + +use std::path::Path; + +/// 造一份「别的启动器已经铺好的」数据根（`/.minecraft` + `/.ULL`）： +/// +/// | 路径 | 用意 | +/// | --- | --- | +/// | `versions/1.20.1/` | 正常版本（清单 + jar），可登记、可 `launch --dry-run` | +/// | `versions/1.20.1-orphan/` | 缺父版本 ⇒ 不可登记 | +/// | `libraries/` `assets/` | 恒共享层（登记不该碰） | +/// | `mods/` `saves/` | 玩家数据（登记不该碰） | +/// | `launcher_profiles.json` | 别的启动器的元数据（连读都不该读，更不该写） | +pub fn foreign_data_root(root: &Path) { + let minecraft = root.join(".minecraft"); + let versions = minecraft.join("versions"); + write_version(&versions, "1.20.1", MANIFEST_OK, true); + write_version(&versions, "1.20.1-orphan", MANIFEST_ORPHAN, true); + write_file( + &minecraft.join("libraries/com/mojang/brigadier/1.0.18/brigadier-1.0.18.jar"), + b"library-bytes", + ); + write_file( + &minecraft.join("assets/indexes/5.json"), + b"{\"objects\":{}}", + ); + write_file(&minecraft.join("mods/jei.jar"), b"mod-bytes"); + write_file(&minecraft.join("saves/World/level.dat"), b"save-bytes"); + write_file( + &minecraft.join("launcher_profiles.json"), + br#"{"profiles":{"1.20.1":{"name":"1.20.1","lastVersionId":"1.20.1"}}}"#, + ); +} + +fn write_version(versions: &Path, id: &str, manifest: &str, jar: bool) { + let dir = versions.join(id); + std::fs::create_dir_all(&dir).expect("建版本目录"); + std::fs::write(dir.join(format!("{id}.json")), manifest.as_bytes()).expect("写清单"); + if jar { + std::fs::write(dir.join(format!("{id}.jar")), b"junk").expect("写 jar"); + } +} + +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("写文件"); +} + +const MANIFEST_OK: &str = r#"{ + "id": "1.20.1", + "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" } } +}"#; + +const MANIFEST_ORPHAN: &str = r#"{ + "id": "1.20.1-orphan", + "type": "release", + "inheritsFrom": "1.20.1-not-on-disk", + "mainClass": "net.minecraft.client.main.Main", + "libraries": [] +}"#; 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..7ae0e90 --- /dev/null +++ b/crates/cli/tests/agent_mcp_stdio_test.rs @@ -0,0 +1,257 @@ +//! 真机验收：起 `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}; + +#[path = "support/mod.rs"] +mod support; + +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>, +} + +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 = 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 = 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::(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); +} + +/// 抓得住：真实会话（索引 + 事件流按**生产形状**落盘）经 MCP 走 `read_game_log` / +/// `diagnose_crash` 时真读得到行，而不是「0 行 / 找不到事件流」。 +/// 抓不住：事件流内容本身对不对（`ports::session` / `ports::diagnose` 的用例守）， +/// 也抓不住 `ull agent` 之外的读取点（`ull logs` / GUI 由 M211 与 presenter 用例守）。 +#[test] +fn mcp_reads_a_real_session_log_and_diagnoses_it() { + let dir = data_dir("session-read"); + let sid = support::write_session(&dir); + let mut session = Session::start(&dir); + + session.rpc( + 1, + "initialize", + json!({ + "protocolVersion": "2025-03-26", + "capabilities": {}, + "clientInfo": { "name": "ull-test", "version": "0.1" } + }), + ); + session.send(&json!({ "jsonrpc": "2.0", "method": "notifications/initialized" })); + + let listed = session.rpc( + 2, + "tools/call", + json!({ "name": "list_game_sessions", "arguments": {} }), + ); + let text = listed["result"]["content"][0]["text"] + .as_str() + .unwrap_or_default(); + assert!(text.contains(&sid), "应列出该会话：{text}"); + + // 读日志：三行事件都在；只要 stderr 时正好那一行 OOM。 + let page = session.rpc( + 3, + "tools/call", + json!({ "name": "read_game_log", "arguments": { "session_id": sid, "kinds": ["stderr"] } }), + ); + assert_ne!(page["result"]["isError"], json!(true), "{page}"); + let text = page["result"]["content"][0]["text"] + .as_str() + .unwrap_or_default(); + assert!( + text.contains("\"total_events\":3"), + "应读到全部 3 行事件：{text}" + ); + assert!( + text.contains("OutOfMemoryError"), + "应读到 stderr 原文：{text}" + ); + + // 诊断：同一份 OOM 事件流要命中规则，而不是 needs_more_info。 + let report = session.rpc( + 4, + "tools/call", + json!({ "name": "diagnose_crash", "arguments": { "session_id": sid } }), + ); + assert_ne!(report["result"]["isError"], json!(true), "{report}"); + let text = report["result"]["content"][0]["text"] + .as_str() + .unwrap_or_default(); + assert!(text.contains("\"needs_more_info\":false"), "{text}"); + assert!( + !text.contains("\"candidates\":[]"), + "应命中至少一条规则：{text}" + ); + + 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"], ""); + assert_eq!( + value["data"]["config"]["download"]["proxy_url"], + "" + ); + 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(""), "{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"], ""); + 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"], ""); + 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(""), "{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![ + 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::>()); + 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/.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 --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 { + 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_pin_test.rs b/crates/cli/tests/java_pin_test.rs new file mode 100644 index 0000000..5f20053 --- /dev/null +++ b/crates/cli/tests/java_pin_test.rs @@ -0,0 +1,114 @@ +//! M220：`ull launch` 真正 spawn 的 Java 必须是 D4 校验过的那个。 +//! +//! 钉路径的**决策**是纯函数（`commands::java_launch::plan_java`，那边有五种来源的单测）； +//! 本文件补**端到端**：装配之后命令行里那个 java 也得是同一个。 +//! +//! 手法：把 `JAVA_HOME` 指到一个**没有 `bin/java` 的空目录**，让「装配期按环境兜底」 +//! 与「D4 选中的候选」必然不同——兜底会退回裸名字 `java[.exe]`（相对名，靠 `PATH` 找）， +//! 而 D4 选中的是探出来的绝对路径。不动 `JAVA_HOME` 的话兜底恰好也落在 `JAVA_HOME` +//! 那一个文件上，「只钉 Managed」的老实现也能蒙对，正是复审抓到的那个缺陷。 +//! +//! 用真子进程（`CARGO_BIN_EXE_ull` + `Command::env`）而不是 `support::run_cli`： +//! `JAVA_HOME` 要按进程注入，改本进程的环境会与同二进制里的其它用例抢。 + +#[path = "support/mod.rs"] +mod support; + +use std::path::Path; +use std::process::Command; + +use support::{parse_json, write_version, TempDir}; + +/// 一个可组装的版本 id：静态表要求 **Java 21+**。 +/// +/// 选 21+ 是有意的：「托管区里只有 17（距离 4）、环境/系统上有 21/25（距离 0）」， +/// 按 D4 的版本距离优先，选中的必然是托管的**外面**那个——正是复审抓到的 +/// 「只有 managed 会钉路径」缺陷所在的那条分支。要求 17 的话托管 17 会赢， +/// 老实现也能蒙对，用例就白跑了。 +const VERSION: &str = "1.21"; + +/// 跑一次 `ull --data-dir `，`JAVA_HOME` 注入成 `java_home`。 +/// +/// `json` 决定加不加全局 `--json`（加了就只有 JSON envelope，人读行被收起来）。 +fn cli_with_java_home( + dir: &TempDir, + java_home: &Path, + json: bool, + tail: &[&str], +) -> (i32, String, String) { + let mut args = vec!["--data-dir".to_string(), dir.arg()]; + if json { + args.push("--json".to_string()); + } + args.extend(tail.iter().map(|arg| arg.to_string())); + let output = Command::new(env!("CARGO_BIN_EXE_ull")) + .args(&args) + .env("JAVA_HOME", java_home) + .output() + .expect("应能起 ull"); + ( + output.status.code().unwrap_or(-1), + String::from_utf8_lossy(&output.stdout).into_owned(), + String::from_utf8_lossy(&output.stderr).into_owned(), + ) +} + +#[test] +fn the_command_line_runs_the_java_that_d4_validated() { + let dir = TempDir::new("java-pin"); + write_version(dir.path(), VERSION); + // 空 JAVA_HOME：`JAVA_HOME/bin/java` 不存在 → 环境兜底这条路走不通。 + let empty_home = dir.path().join("empty-java-home"); + std::fs::create_dir_all(&empty_home).expect("建空 JAVA_HOME"); + + let (code, stdout, stderr) = + cli_with_java_home(&dir, &empty_home, true, &["launch", VERSION, "--dry-run"]); + assert_eq!(code, 0, "stderr: {stderr}"); + let data = parse_json(&stdout)["data"].clone(); + let java = &data["java"]; + let source = java["source"].as_str().unwrap_or("none"); + assert!( + ["PATH", "system"].contains(&source), + "前置：`JAVA_HOME` 已置空，且这条版本要 Java 21+（托管区的 17 不满足），\ + 来源只该是 PATH 或标准安装位置：{data}" + ); + let binary = java["binary"] + .as_str() + .unwrap_or_else(|| panic!("本机一个 Java 都探不到，这条端到端验不到东西（判红）：{data}")); + assert!( + Path::new(binary).is_absolute(), + "前置：探到的 Java 必须是绝对路径（否则「钉住」与「裸名字」无从区分，判红）：{data}" + ); + + // ① 装配落地的就是校验过的那个（`--json` 里并排给的两个事实必须相等）。 + assert_eq!( + java["launch_binary"].as_str(), + Some(binary), + "装配落地的 java 必须是 D4 校验过的那个：{data}" + ); + // ② 命令行里真正要跑的也是它 —— 这一条才是「spawn 的是哪个」。 + // 注意 `program` 会过脱敏（主目录 → ``），所以按「绝对路径 + 文件名」判， + // 不按整串判；退回裸 `java[.exe]` 的老实现在这里必红。 + let program = data["program"].as_str().unwrap_or_default(); + assert!( + program.starts_with("") || Path::new(program).is_absolute(), + "命令行里的 java 必须是钉住的绝对路径（裸 `java` = 又退回装配期重选了）：{data}" + ); + assert_eq!( + Path::new(program).file_name(), + Path::new(binary).file_name(), + "命令行里的 java 与 D4 校验的不是同一个：{data}" + ); + // ③ 人读输出也要说清「实际用哪个、来源是什么」（终端里对着日志排查时只有一个依据）。 + let (code, stdout, stderr) = + cli_with_java_home(&dir, &empty_home, false, &["launch", VERSION, "--dry-run"]); + assert_eq!(code, 0, "stderr: {stderr}"); + assert!( + stdout.contains(&format!("{source} · ")), + "人读行要写出 Java 来源：{stdout}" + ); + assert!( + stdout.contains(binary), + "人读行要写出实际使用的 java 路径（{binary}）：{stdout}" + ); +} diff --git a/crates/cli/tests/java_test.rs b/crates/cli/tests/java_test.rs new file mode 100644 index 0000000..acac21b --- /dev/null +++ b/crates/cli/tests/java_test.rs @@ -0,0 +1,294 @@ +//! `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}" + ); + // M220：`binary` 是 D4 校验过的那个，`launch_binary` 是装配落地的那个——两者都得给出来。 + assert!( + java["launch_binary"].as_str().is_some(), + "`--json` 的 java 块要写明实际装配的 java 路径：{json}" + ); +} + +#[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}" + ); + } +} + +/// 写一份「清单自己声明要 Java `required`」的版本 JSON（其余字段与 `support::write_version` 同）。 +/// +/// 本机任何一个 Java 都不满足 `required = 99` ⇒ D4 必然要拦（`java_too_old`）， +/// 与「这台机器装了哪几个 JDK」无关、也不需要联网：用例的观察点是**拦截发生在哪一步**。 +fn write_version_requiring_java(root: &std::path::Path, required: u32) { + 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" }, + "javaVersion": { "majorVersion": required }, + "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!("{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"); +} + +/// M220 nit3：D4 的「Java 不符」拦截必须排在身份解析**之前**。 +/// +/// 身份解析有副作用（微软轨会联网刷新令牌、刷新成功还会回写凭据），一个注定要被拦下的 +/// 启动不该先跑那一遍。观察点：数据根里放两个离线账户 ⇒ 解析身份必然报 `account_ambiguous`， +/// 而这次启动注定被 D4 拦下 ⇒ 报出来的必须是 `java_mismatch`。 +/// 老实现（拦在身份之后）在这里会先撞上 `account_ambiguous`，用例必红。 +/// +/// 对照组：`--dry-run` 本来就只提示不拦（D4 只管真启动），所以同一条版本在 dry-run 下 +/// 会走到身份解析那一步——这一对断言把「拦截在哪一步」钉死。 +#[test] +fn the_java_mismatch_block_runs_before_identity_resolution() { + let dir = TempDir::new("java-block-order"); + write_version_requiring_java(dir.path(), 99); + for name in ["alpha", "beta"] { + let (code, _, stderr) = + run_cli(&["accounts", "add", "offline", name, "--data-dir", &dir.arg()]); + assert_eq!(code, 0, "建离线账户失败：{stderr}"); + } + + // 前置：这条版本的要求确实没人满足（否则「注定被拦」这个前提不成立，直接判红）。 + let (code, stdout, stderr) = run_cli(&[ + "--json", + "--data-dir", + &dir.arg(), + "launch", + VERSION, + "--dry-run", + "--account", + "alpha", + ]); + assert_eq!(code, 0, "stderr: {stderr}"); + let envelope = parse_json(&stdout); + assert_eq!( + envelope["data"]["java"]["mismatch"]["code"], "java_too_old", + "前置：本机探测到的 Java 必须都不满足 Java 99：{envelope}" + ); + + // 真启动（不指定账户）：两个账户 ⇒ 解析身份会报 account_ambiguous，但 D4 拦得更早。 + let (code, stdout, _stderr) = run_cli(&["--json", "--data-dir", &dir.arg(), "launch", VERSION]); + assert_eq!(code, 1); + let envelope = parse_json(&stdout); + assert_eq!( + envelope["error"]["code"], "java_mismatch", + "D4 拦截必须排在身份解析之前（否则注定被拦的启动也先刷了一遍令牌）：{envelope}" + ); + + // 对照：dry-run 不拦（D4 只管真启动）⇒ 它会走到身份解析，报的是账户歧义。 + let (code, stdout, _stderr) = run_cli(&[ + "--json", + "--data-dir", + &dir.arg(), + "launch", + VERSION, + "--dry-run", + ]); + assert_eq!(code, 1); + let envelope = parse_json(&stdout); + assert_eq!( + envelope["error"]["code"], "account_ambiguous", + "dry-run 不该被 D4 拦住（它只提示），应当走到身份解析：{envelope}" + ); +} diff --git a/crates/cli/tests/liteloader_test.rs b/crates/cli/tests/liteloader_test.rs new file mode 100644 index 0000000..2e8080d --- /dev/null +++ b/crates/cli/tests/liteloader_test.rs @@ -0,0 +1,140 @@ +//! `ull install --loader liteloader` 的**离线**可验面：词表分流、父版本缺失、help 文案。 +//! +//! 这里刻意不联网：LiteLoader 的版本表在 `dl.liteloader.com`，把「拉到表之后」的链路放在 +//! `crates/core/tests/liteloader/**`（真实响应夹具 + 合成 + 计划 + 落盘 + 启动参数）。 +//! 本文件守的是「进门那一步」：`optifine` 与随机拼法的错误码必须分开、父版本没装必须具名报错、 +//! 非 LiteLoader 不许叠在别的加载器层上。 + +#[path = "support/mod.rs"] +mod support; + +use support::{parse_json, run_cli, TempDir}; + +#[test] +fn optifine_is_recognized_but_not_supported() { + let dir = TempDir::new("liteloader-optifine"); + let (code, stdout, _) = run_cli(&[ + "install", + "1.20.1", + "--loader", + "optifine", + "--json", + "--data-dir", + &dir.arg(), + ]); + assert_eq!(code, 1); + let value = parse_json(&stdout); + assert_eq!( + value["error"]["code"], "loader_unsupported", + "optifine 是「认得但装不了」，不是未知加载器：{stdout}" + ); + assert!( + value["error"]["message"] + .as_str() + .unwrap_or_default() + .contains("optifine"), + "{stdout}" + ); +} + +/// `optifine` 之外，真正不认识的拼法仍是 `loader_unknown`（样本用**明显无效**的名字， +/// 不拿任何真实加载器名当「未知」前提）。 +#[test] +fn genuinely_unknown_loader_stays_unknown() { + let dir = TempDir::new("liteloader-unknown"); + let (code, stdout, _) = run_cli(&[ + "install", + "1.20.1", + "--loader", + "ull-invalid-loader-test", + "--json", + "--data-dir", + &dir.arg(), + ]); + assert_eq!(code, 1); + let value = parse_json(&stdout); + assert_eq!(value["error"]["code"], "loader_unknown", "{stdout}"); + let hint = value["error"]["hint"].as_str().unwrap_or_default(); + assert!(hint.contains("liteloader"), "提示要列全六家：{hint}"); +} + +/// 父版本（`1.12.2-forge-…`）没装时：具名报缺哪个父版本，且**不发网络请求**。 +#[test] +fn liteloader_on_a_missing_forge_parent_names_the_parent() { + let dir = TempDir::new("liteloader-missing-parent"); + let (code, stdout, _) = run_cli(&[ + "install", + "1.12.2-forge-14.23.5.2860", + "--loader", + "liteloader", + "--json", + "--data-dir", + &dir.arg(), + ]); + assert_eq!(code, 1); + let value = parse_json(&stdout); + assert_eq!(value["error"]["code"], "loader_not_found", "{stdout}"); + let message = value["error"]["message"].as_str().unwrap_or_default(); + assert!( + message.contains("1.12.2-forge-14.23.5.2860"), + "要点名缺哪个父版本：{message}" + ); +} + +/// 只有 LiteLoader 接受「叠在别的加载器层上」；别家在进门处就说清（不静默改成叠原版）。 +#[test] +fn only_liteloader_accepts_stacking_on_another_loader_layer() { + let dir = TempDir::new("liteloader-stack-guard"); + let (code, stdout, _) = run_cli(&[ + "install", + "1.12.2-forge-14.23.5.2860", + "--loader", + "fabric", + "--json", + "--data-dir", + &dir.arg(), + ]); + assert_eq!(code, 1); + let value = parse_json(&stdout); + assert_eq!(value["error"]["code"], "usage", "{stdout}"); + let message = value["error"]["message"].as_str().unwrap_or_default(); + assert!( + message.contains("LiteLoader") && message.contains("Fabric"), + "{message}" + ); +} + +#[test] +fn install_help_names_the_liteloader_route() { + let (code, stdout, _) = run_cli(&["help", "install"]); + assert_eq!(code, 0); + for needle in [ + "liteloader", + "optifine", + "launchwrapper", + "tweakClass", + "loader_unsupported", + "loader_unknown", + ] { + assert!( + stdout.contains(needle), + "`ull help install` 少了 `{needle}`：\n{stdout}" + ); + } +} + +#[test] +fn general_help_lists_liteloader_under_install() { + let (code, stdout, _) = run_cli(&["--help"]); + assert_eq!(code, 0); + let install_block = stdout + .lines() + .skip_while(|line| !line.trim_start().starts_with("install ")) + .take(3) + .collect::>() + .join("\n"); + assert!( + install_block.contains("liteloader"), + "总帮助的 install 段要提到 liteloader：\n{install_block}" + ); +} 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..ee8de44 --- /dev/null +++ b/crates/cli/tests/output_test.rs @@ -0,0 +1,297 @@ +//! `--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"); + // 样本必须是一个**任何词表里都没有**的拼法：`liteloader` 自 M222 起是受支持加载器， + // 拿它当「未知」会让这条用例变成真去拉 dl.liteloader.com 的联网测试。 + let (code, stdout, _) = run_cli(&[ + "install", + "1.20.1", + "--loader", + "ull-invalid-loader-test", + "--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::>() + .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..2fe6c00 --- /dev/null +++ b/crates/cli/tests/pack_test.rs @@ -0,0 +1,303 @@ +//! `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}"); +} + +/// **M216 P3-3 + §5**：不带 `--target` 时落点是**新实例目录**（不是共享 `.minecraft` 根）， +/// 而且登记出来的实例被绑到那个目录（`isolation=custom` + `gameDir`），否则导入内容永远不会 +/// 被启动用到。 +/// +/// 抓得住：CLI 自己兜底回 `ctx.game().root()`（第一条断言会变成 `.minecraft`）；不建实例目录而 +/// 直接铺共享根；不做绑定（`isolation` 仍是 `null`）；绑定写错目录。抓不住：真实启动那一条 +/// `derive_game_dir` 的派生（core 的 `isolation.rs` 用例钉，这里只断言设置文件的内容）。 +#[test] +fn the_default_target_is_a_new_instance_dir_and_the_instance_is_bound_to_it() { + let data = TempDir::new("pack-default-target"); + let source = multimc_instance(data.path()); + let (code, stdout, stderr) = run_cli(&[ + "pack", + "import", + &source.display().to_string(), + "--name", + "My Pack", + "--data-dir", + &data.arg(), + "--json", + ]); + assert_eq!(code, 0, "stdout={stdout} stderr={stderr}"); + + // **M216 r2**：绑定成败也进 `--json`（结构化，不必猜文案）。 + let value = parse_json(&stdout); + assert_eq!( + value["data"]["instance_bound"], + Value::Bool(true), + "缺省导入应当把实例绑到内容目录并报 true：{stdout}" + ); + + let instance_dir = data.path().join(".ULL/data/instances/My-Pack"); + assert!( + instance_dir.join("mods/a.jar").is_file(), + "缺省落点应当是 /instances/My-Pack：{stdout}" + ); + assert!( + !data.path().join(".minecraft/mods/a.jar").exists(), + "不许再往共享 .minecraft 根铺：{stdout}" + ); + + // 登记的实例被绑到这个目录（§5）。 + let profiles: Value = serde_json::from_str( + &std::fs::read_to_string(data.path().join(".ULL/config/profiles.json")) + .expect("profiles.json"), + ) + .expect("profiles.json 是 JSON"); + assert_eq!( + profiles["profiles"][0]["name"], + Value::String("My Pack".into()) + ); + let id = profiles["profiles"][0]["id"] + .as_str() + .expect("登记出来的实例有 id") + .to_string(); + let config: Value = serde_json::from_str( + &std::fs::read_to_string( + data.path() + .join(".ULL/config/instances") + .join(format!("{id}.json")), + ) + .expect("实例设置文件"), + ) + .expect("实例设置是 JSON"); + assert_eq!( + config["isolation"], + Value::String("custom".into()), + "isolation 应当是 custom：{config}" + ); + assert_eq!( + config["gameDir"].as_str().map(Path::new), + Some(instance_dir.as_path()), + "gameDir 应当指向导入目录：{config}" + ); +} + +/// **M216 P2-1 / r2**：`--help` 里的缺省落点必须是**真路径**。 +/// +/// 「数据根」在这份帮助自己的定义里是「含 `.ULL/` 与 `.minecraft/` 的父目录」（`--data-dir` 那行）， +/// 所以实例目录的真路径是 `<数据根>/.ULL/data/instances/<目录名>`。r1 写成了 +/// `<数据根>/instances/<实例名>` —— 少一层 `.ULL/data`，照读会去一个不存在的位置找包内容。 +/// +/// 抓得住：缺 `.ULL/data` 这一层（下面第二条断言就是抓它的——少写时该子串恰好出现）； +/// 文案退回「共享游戏目录」；目录名归一化这件事没提。抓不住：`model.rs` 的字段文档 +/// （编译期文档，测试读不到），以及真实 `--data-dir` 下的绝对路径拼接（那由上面那条端到端 +/// 用例按真目录断言）。 +#[test] +fn help_describes_the_new_default_target_with_the_real_path() { + let (code, stdout, _) = run_cli(&["help", "pack"]); + assert_eq!(code, 0); + assert!( + stdout.contains("<数据根>/.ULL/data/instances/<实例目录名>"), + "帮助里没写真路径 <数据根>/.ULL/data/instances/<实例目录名>：{stdout}" + ); + assert!( + !stdout.contains("<数据根>/instances/"), + "帮助里的落点少了 `.ULL/data` 这一层（r2 抓的就是这个错法）：{stdout}" + ); + assert!( + !stdout.contains("缺省 = 数据根的共享游戏目录"), + "帮助里还留着旧缺省落点：{stdout}" + ); +} diff --git a/crates/cli/tests/parse_test.rs b/crates/cli/tests/parse_test.rs new file mode 100644 index 0000000..aa2e602 --- /dev/null +++ b/crates/cli/tests/parse_test.rs @@ -0,0 +1,384 @@ +//! 子命令解析：手写解析器的语法契约。 + +#[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 = 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 update_subcommands() { + use unlucky_cli::cli::{UpdateApplyArgs, UpdateCheckArgs}; + + assert_eq!( + invoke(&["update", "check"]).command, + Command::UpdateCheck(UpdateCheckArgs {}) + ); + assert_eq!( + invoke(&["update", "apply"]).command, + Command::UpdateApply(UpdateApplyArgs { dest: None }) + ); + // `--dest` 两种写法都要认（钉替换目标 = 取证 / 自定义安装位置） + for args in [ + vec!["update", "apply", "--dest", "D:/tmp/ull.exe"], + vec!["update", "apply", "--dest=D:/tmp/ull.exe"], + ] { + assert_eq!( + invoke(&args).command, + Command::UpdateApply(UpdateApplyArgs { + dest: Some(std::path::PathBuf::from("D:/tmp/ull.exe")), + }) + ); + } +} + +/// `update` 的用法错误：没子命令 / 未知子命令 / 多余位置参数 / 未知选项——四条都是 `usage` +/// （退出码 1），不许静默退化成某个默认动作。 +#[test] +fn update_usage_errors() { + for args in [ + vec!["update"], + vec!["update", "install"], + vec!["update", "check", "extra"], + vec!["update", "apply", "extra"], + vec!["update", "apply", "--dest"], + vec!["update", "apply", "--nope"], + ] { + let owned: Vec = args.iter().map(|arg| arg.to_string()).collect(); + let error = parse(&owned).expect_err(&format!("{args:?} 应当报用法错误")); + assert_eq!(error.kind(), ErrorKind::User, "{args:?}"); + assert_eq!(error.code(), "usage", "{args:?}"); + } +} + +#[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 = 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 = 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", + "update", + ] { + 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..496b54f --- /dev/null +++ b/crates/cli/tests/support/mod.rs @@ -0,0 +1,278 @@ +//! 集成测试共用夹具：临时数据根、命令执行器、最小版本 JSON / 会话索引。 +//! +//! 每个测试目标都会整份编译本文件但只用其中一部分，因此这里放开 dead_code。 +#![allow(dead_code)] + +pub mod update_e2e; +pub mod update_e2e_sign; + +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 { + Self::in_root(&std::env::temp_dir(), tag).expect("创建临时目录") + } + + /// 建在**另一块卷**上（跨卷验收用）；本机只有一块可写卷时返回 `None`。 + pub fn on_other_volume(tag: &str) -> Option { + other_volume_root().and_then(|root| Self::in_root(&root, tag)) + } + + fn in_root(root: &Path, tag: &str) -> Option { + 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 = root.join(format!( + "ull-cli-test-{tag}-{}-{seq}-{nanos}", + std::process::id() + )); + std::fs::create_dir_all(&path).ok()?; + Some(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); + } +} + +/// 指定异卷根目录的环境变量（本机找不到第二块卷时，用它显式指一块）。 +pub const XDEV_ROOT_ENV: &str = "ULL_XDEV_TEST_ROOT"; + +/// 「我知道本机没有第二块卷」的显式豁免（值必须是 `1`）。 +/// +/// 与 `crates/core/src/update/tests/support.rs` 的同名常量是**同一条政策**（源头在 +/// `crates/core/src/update/tests/install_xdev_cases.rs::xdev_guard`，改一处要改两处）： +/// 探不到第二块卷又不豁免 ⇒ 这条 e2e 必须红，不许静静 `return`（M171 r2 P2-1）。 +pub const XDEV_WAIVE_ENV: &str = "ULL_XDEV_TEST_WAIVE"; + +/// 「本机/本作业必须有第二块卷」的显式声明（值必须是 `1`），优先于豁免。 +pub const XDEV_REQUIRE_ENV: &str = "ULL_XDEV_TEST_REQUIRE"; + +/// 跨卷 e2e 探不到第二块卷时的裁决：**显式豁免**才允许跳过（打印一行记录），否则 panic。 +/// +/// `what` 只用来在输出里点名是哪条用例，裁决规则与 core 侧完全一致（见 [`XDEV_WAIVE_ENV`]）。 +pub fn cross_volume_waived(what: &str) { + let required = std::env::var(XDEV_REQUIRE_ENV).ok(); + let waived = std::env::var(XDEV_WAIVE_ENV).ok(); + let required = required.as_deref().map(str::trim) == Some("1"); + let waived = waived.as_deref().map(str::trim) == Some("1"); + assert!( + waived && !required, + "[xdev-guard] {what}：本机没有第二块可写卷，也没有显式豁免——跨卷 e2e 空跑了，\ + 所以判红。三种合规做法任选其一：\ + ① ULL_XDEV_TEST_ROOT=<另一块卷上的可写目录>；② ULL_XDEV_TEST_WAIVE=1（值必须是 1）；\ + ③ 认为本机本该有第二块卷就用 ULL_XDEV_TEST_REQUIRE=1 声明。\ + 政策与理由见 crates/core/src/update/tests/install_xdev_cases.rs 的模块文档。" + ); + eprintln!( + "[xdev-guard] {what}：本机没有第二块可写卷，已显式豁免（{XDEV_WAIVE_ENV}=1），\ + 这条 e2e 跳过。" + ); +} + +/// 一块与会话临时目录**真的**不同卷的可写根目录（探出来的，不是按平台猜的）。 +/// +/// 候选：`ULL_XDEV_TEST_ROOT` → Windows 各盘符的 `Temp`（没有就盘根）/ Unix 的 `TMPDIR`、 +/// `/dev/shm`、`/tmp`、`/run/user/`。每个候选都要过「从 temp 目录 rename 进它必须报 +/// `CrossesDevices`」这一关，所以返回值**一定**是异卷——同一块卷上的候选会被跳过， +/// 否则跨卷用例会在同卷上跑，等于什么都没验。 +pub fn other_volume_root() -> Option { + let mut candidates = Vec::new(); + if let Some(root) = std::env::var_os(XDEV_ROOT_ENV) { + candidates.push(PathBuf::from(root)); + } + candidates.extend(volume_candidates()); + candidates + .into_iter() + .find(|candidate| is_other_volume(candidate)) +} + +fn volume_candidates() -> Vec { + #[cfg(windows)] + { + ('A'..='Z') + .map(|letter| PathBuf::from(format!("{letter}:/"))) + .filter(|root| root.is_dir()) + .map(|root| { + if root.join("Temp").is_dir() { + root.join("Temp") + } else { + root + } + }) + .collect() + } + #[cfg(not(windows))] + { + let mut candidates: Vec = ["TMPDIR", "TMP", "TEMP"] + .iter() + .filter_map(|key| std::env::var_os(key).map(PathBuf::from)) + .collect(); + for root in ["/dev/shm", "/tmp", "/var/tmp"] { + candidates.push(PathBuf::from(root)); + } + if let Some(uid) = std::env::var_os("UID") { + candidates.push(PathBuf::from("/run/user").join(uid)); + } + candidates + } +} + +fn is_other_volume(dir: &Path) -> bool { + if dir.as_os_str().is_empty() || std::fs::create_dir_all(dir).is_err() { + return false; + } + let probe = std::env::temp_dir().join(format!("ull-cli-probe-{}", std::process::id())); + if std::fs::write(&probe, b"probe").is_err() { + return false; + } + let landed = dir.join(format!("ull-cli-probe-{}", std::process::id())); + let cross = matches!( + std::fs::rename(&probe, &landed), + Err(ref error) if error.kind() == std::io::ErrorKind::CrossesDevices + ); + let _ = std::fs::remove_file(&probe); + let _ = std::fs::remove_file(&landed); + cross +} + +/// 跑一次 CLI，返回（退出码, stdout, stderr）。 +pub fn run_cli(args: &[&str]) -> (i32, String, String) { + let owned: Vec = args.iter().map(|arg| arg.to_string()).collect(); + let mut out: Vec = Vec::new(); + let mut err: Vec = 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 = 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。 +/// +/// **形状必须与生产写入一致**（M211/D2）：`log_path` 是**相对会话根**的 `game/.jsonl`， +/// 事件流真落点是 `<会话根>/game/.jsonl`。这里用的是旧家（`data/agent/sessions`）作会话根 +/// ——那是 M188 之前的生产落点，也是用户盘上存量会话的真实形状，读取侧必须还能读回它们。 +/// 夹具此前写的是不带 `game/` 的 `"{sid}.jsonl"`，于是「读取侧多 join 一层 `game/`」这个 bug +/// 在测试里永远看不见：夹具自己说了另一种形状。 +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": unlucky_core::launch::session_index::log_path_for(sid), + "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/cli/tests/support/update_e2e.rs b/crates/cli/tests/support/update_e2e.rs new file mode 100644 index 0000000..f46af21 --- /dev/null +++ b/crates/cli/tests/support/update_e2e.rs @@ -0,0 +1,348 @@ +//! 更新通道端到端验收的夹具（M169）：临时现场、真形状清单、测试通道的环境变量守卫。 +//! +//! 两个测试目标共用（`update_e2e_test` 正路 / 幂等，`update_e2e_tamper_test` 篡改）；每个目标只 +//! 用到其中一部分，所以与 `support/mod.rs` 一样放开 dead_code。 +//! +//! 整个夹具只在 `update-test-source` feature 下真的被用到：那两个测试目标自己 `#![cfg]` 掉， +//! 这里只是跟着编译（不跑）。判据（feature + 两档环境变量）在 `core::update::job`。 +//! +//! # 为什么这套「真形状」只在 Windows 上成立（r1 复审 P2-4） +//! +//! 产物名与形态按 **Windows** 的真实发布走：`unlucky-launcher__windows_x64.exe` + +//! `portable-exe`（口径见 `packaging/make_artifacts.py` 的头注释）。Linux/macOS 的真实产物是 +//! `.tar.gz` + `portable-zip`，会被 `ensure_self_replaceable` **直接拒**（不是可原地自替换的形态）。 +//! +//! * 在 Windows 上跑 = 验真实形状； +//! * 在别的平台上跑绿只能证明「一个世上不存在的 linux/macOS portable-exe 能装上」——**假绿**。 +//! +//! 所以 CI 里它是**一个独立的 Windows job**（`.github/workflows/ci.yml` 的 `update-e2e`， +//! `runs-on: windows-latest`），本文件也**不**为非 Windows 平台改断言：要真支持，得让产物名与 +//! `format` 一起按平台分叉，那是另一个 mission 的事（真实 Linux 自更新根本不支持，D50 只发裸 exe）。 +//! +//! ⚠ **验收必须给 `--dest`**：用例在**进程内**跑 `unlucky_cli::run`，`Job::for_process` 的 +//! 「本进程的 exe」就是测试二进制——`apply` 不带 `--dest` 会真的把它 `rename` 成新字节 +//! （Windows 允许改名正在运行的映像，见 `core::update::install` 的文档），整轮测试当场崩。 +//! `Fixture::run` 里有结构性断言兜这一条（r1 复审 P2-5），不是只靠这段注释。 +#![allow(dead_code)] + +use std::path::{Path, PathBuf}; + +use super::update_e2e_sign::write_signature; +use unlucky_core::update::{HashAlgo, OsFamily, Target, UPDATE_DIR_ENV, UPDATE_TEST_SOURCE_ENV}; + +/// 假装的「已安装版本」字节：与产物**必须不同**，否则「目标没被动过」这类断言会假绿。 +pub const INSTALLED: &[u8] = b"installed 0.2.3 build (pretend)"; + +/// 产物体量上限（1 MiB）。 +/// +/// 现场构建出来的 `ull.exe` 是 **~400 MB**（debug + 全套 reqwest/rmcp/axum）；拿整份当过测材， +/// 光 sha256 + 拷贝就要几十秒，验收会变成「谁都不想跑」。所以截取**前 1 MiB**：PE 头与头几节都在， +/// 「这是真 exe 的字节」这一点保留，代价是「装上去能不能启动」不再由它证明——那一跳本来就要人工 +/// （见报告「不验的部分」）。清单里的 `size` / `sha256` 按这份截短后的真实字节算，仍然自洽。 +const PAYLOAD_LIMIT: usize = 1024 * 1024; + +/// 清单里的更新说明（断言它会原样出现在 `check --json` 里）。 +const NOTES: &str = "修掉启动崩溃；实例页加载更快"; + +/// SHA-256 按真实字节算（与双检同一条实现：`core::download::verify::digest_bytes`）。 +pub fn sha256(bytes: &[u8]) -> String { + unlucky_core::download::verify::digest_bytes(HashAlgo::Sha256, bytes) +} + +/// 清单版本：**比编译期版本严格大一档次版本**。 +/// +/// 不能写死 `0.2.4`：workspace 版本一升，用例就变成「已是最新」的假红。次版本 +1 恒大于当前 +/// 版本，且仍在同一 major 内（不会意外触发 `min_supported` 那条判据）。 +pub fn next_version(current: &str) -> String { + let mut parts = current.split('.'); + let major = parts.next().unwrap_or("0"); + let minor: u64 = parts + .next() + .unwrap_or("0") + .parse() + .unwrap_or_else(|_| panic!("编译期版本号应是三段式：{current}")); + assert!(parts.next().is_some(), "编译期版本号应是三段式：{current}"); + format!("{major}.{}.0", minor + 1) +} + +/// 真实产物命名（D49）：`unlucky-launcher__windows_x64.exe`。 +/// +/// 拿 `Target::as_str()`（`win-x64`）直接拼会得到一个世上不存在的文件名，清单那一栏也就 +/// 与真实发布对不上——「真形状」的意义正在这里。 +fn asset_name(version: &str) -> String { + let target = Target::current(); + let os = match target.os { + OsFamily::Windows => "windows", + OsFamily::MacOs => "macos", + OsFamily::Linux => "linux", + }; + format!( + "unlucky-launcher_{version}_{os}_{}.exe", + target.arch.as_str() + ) +} + +/// 一份与 `packaging/tests/manifest.golden.json` **同字段**的清单。 +/// +/// 字段一个不多一个不少：core 的 `deny_unknown_fields` 会把多余字段当清单损坏拒掉，所以这条 +/// 同时也是「清单形状与真实生成器（`packaging/make_manifest.py`）对齐」的断言。 +fn manifest(version: &str, asset: &str, size: u64, sha256: &str) -> String { + format!( + r#"{{ + "channel": "stable", + "releases": [ + {{ + "version": "{version}", + "channel": "stable", + "released_at": "2026-01-02T03:04:05Z", + "notes": "{NOTES}", + "force": false, + "min_supported": "0.1.0", + "artifacts": [ + {{ + "target": "{}", + "format": "portable-exe", + "url": "{asset}", + "size": {size}, + "sha256": "{sha256}" + }} + ] + }} + ] +}}"#, + Target::current().as_str() + ) +} + +/// 进程环境是共享的（同一测试进程里各用例并行）：动环境变量的用例都拿这把锁串起来。 +pub fn channel_lock() -> std::sync::MutexGuard<'static, ()> { + static LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(()); + LOCK.lock().unwrap_or_else(|poisoned| poisoned.into_inner()) +} + +/// 两个测试通道变量的现场：构造时记住原值，`Drop` 还原（用例 panic 也还原）。 +pub struct Channel { + dir: Option, + ack: Option, +} + +impl Channel { + pub fn capture() -> Self { + Self { + dir: std::env::var_os(UPDATE_DIR_ENV), + ack: std::env::var_os(UPDATE_TEST_SOURCE_ENV), + } + } + + /// 测试通道开启：两档环境变量全给（二进制还得带 `update-test-source` feature；只给路径不会被 + /// 认，判据见 `core::update::job`）。 + pub fn enable(root: &Path) { + std::env::set_var(UPDATE_DIR_ENV, root); + std::env::set_var(UPDATE_TEST_SOURCE_ENV, "1"); + } +} + +impl Drop for Channel { + fn drop(&mut self) { + for (key, value) in [ + (UPDATE_DIR_ENV, self.dir.clone()), + (UPDATE_TEST_SOURCE_ENV, self.ack.clone()), + ] { + match value { + Some(value) => std::env::set_var(key, value), + None => std::env::remove_var(key), + } + } + } +} + +/// `--json` 信封 → 命令载荷。 +/// +/// 成功信封是 `{"ok":true,"data":{…},"warnings":[…]}`，失败信封是 `{"ok":false,"error":{…}}` +/// （没有 `data`）。所以「取载荷」= 有 `data` 取 `data`，否则原样返回——失败用例照样能看 +/// `error.code` / `error.detail.kind`。 +pub fn payload(json: &serde_json::Value) -> &serde_json::Value { + json.get("data").unwrap_or(json) +} + +/// 目录里的文件名（读不到就当空）。 +fn list_dir(dir: &Path) -> Vec { + match std::fs::read_dir(dir) { + Ok(entries) => entries + .filter_map(Result::ok) + .map(|entry| entry.file_name().to_string_lossy().into_owned()) + .collect(), + Err(_) => Vec::new(), + } +} + +/// 一次验收的全部现场： +/// +/// ```text +/// /-data/ --data-dir（自定义模式 ⇒ /.ULL 与 /.minecraft） +/// /-dist/ ULL_UPDATE_DIR（stable.json + 产物） +/// /-install/ --dest 所在目录（**临时副本**，不是本进程的 exe） +/// ``` +/// +/// 三个 `TempDir` 都要活到用例结束（`Fixture` 持有它们）。 +pub struct Fixture { + pub data: super::TempDir, + pub dist: super::TempDir, + install: super::TempDir, + /// 产物字节 = 现场构建出来的 `ull.exe` 的前 1 MiB（真 PE 头，理由见 [`PAYLOAD_LIMIT`]）。 + pub payload: Vec, + /// 清单里的版本号（= 编译期版本次版本 +1）。 + pub version: String, + /// 产物文件名（清单 `url` 与盘上文件同名）。 + pub asset: String, + /// 替换目标（安装目录里的副本）。 + pub dest: PathBuf, +} + +/// 现场构建出来的 `ull.exe` 的前 [`PAYLOAD_LIMIT`] 字节（读一次，整份不超过 1 MiB）。 +/// +/// 为什么不用占位字符串：这是**发布矩阵里那个单文件 exe** 的真字节，PE 头、节表、体积都对得上； +/// 为什么截短：整份 ~400 MB，测材太重（理由见 [`PAYLOAD_LIMIT`]）。 +fn payload_bytes() -> Vec { + let path = env!("CARGO_BIN_EXE_ull"); + let mut payload = std::fs::read(path).expect("读构建出来的 ull.exe"); + payload.truncate(PAYLOAD_LIMIT); + assert!( + payload.len() >= 64 * 1024, + "产物要像真的（至少 64 KiB），实际 {} 字节", + payload.len() + ); + if cfg!(windows) { + assert!( + payload.starts_with(b"MZ"), + "Windows 产物得是 PE 映像（前两个字节 MZ），否则「真形状」这句话就没意义" + ); + } + payload +} + +impl Fixture { + pub fn new(tag: &str) -> Self { + Self::with_install(tag, super::TempDir::new(&format!("{tag}-install"))) + } + + /// 安装目录在**另一块卷**上的现场（数据根与暂存仍在会话 temp）：M171 的真机跨卷形态。 + /// + /// 找不到第二块可写卷时返回 `None`（调用方跳过并说明原因）——这条用例在只有一块卷的 + /// 机器/CI 上**不生效**，跨卷逻辑本身由 `crates/core` 的注入用例守着。 + pub fn cross_volume(tag: &str) -> Option { + let install = super::TempDir::on_other_volume(&format!("{tag}-install"))?; + Some(Self::with_install(tag, install)) + } + + fn with_install(tag: &str, install: super::TempDir) -> Self { + let payload = payload_bytes(); + let version = next_version(env!("CARGO_PKG_VERSION")); + let dest = install.path().join("unlucky-launcher.exe"); + std::fs::write(&dest, INSTALLED).expect("写旧版本"); + Self { + data: super::TempDir::new(&format!("{tag}-data")), + dist: super::TempDir::new(&format!("{tag}-dist")), + install, + asset: asset_name(&version), + payload, + version, + dest, + } + } + + /// 发一版：清单 + 产物都按 `payload` 的真实长度与摘要。 + pub fn publish_good(&self) { + self.publish(&sha256(&self.payload), self.payload.len() as u64); + } + + /// 发一版，摘要/长度由调用方给（篡改用例用）。 + pub fn publish(&self, sha256: &str, size: u64) { + std::fs::write(self.dist.path().join(&self.asset), &self.payload).expect("写产物"); + let path = self.dist.path().join("stable.json"); + std::fs::write(&path, manifest(&self.version, &self.asset, size, sha256)).expect("写清单"); + // M190：清单与签名成对落盘。篡改用例给的是「错的 sha/size」，签的是**改过之后**那份清单 + // —— 那正是「清单本身可信、包体不对」的现场（摘要判据要独立于签名判据被证到）。 + write_signature(&path); + } + + /// 跑一条 `update` 子命令：`--data-dir` 指向临时数据根（与 GUI 一样由数据根派生暂存目录）。 + /// + /// **结构性保险（r1 复审 P2-5 / r2 复审 P2-3）**：`apply` 必须显式带 `--dest`，且**这一次调用实际 + /// 传下去的那个 `--dest` 值**不许是本进程的 exe。不带 `--dest` 就是 `Job::for_process` 的「本进程 + /// exe」——在这套用例里那是**测试二进制**，而 Windows 允许改名正在运行的映像，于是整轮测试会把它 + /// 换成一个假启动器（症状极难查）。 + /// + /// 比的是 **args 里那个 `--dest` 的值**（含 `--dest=` 形式），不是夹具字段：r2 复审指出 + /// 「比 `self.dest`」等于只守住了夹具自己那一份，手写 + /// `fx.run(&["apply", "--dest", "<测试二进制>", "--json"])` 照样能过。夹具字段那一份作为额外一道 + /// 保留（`Fixture::apply()` 走的就是它）。 + /// + /// 抓得住：漏 `--dest`、把 `--dest` 指到本进程 exe、夹具 dest 被改成 exe——都**当场 panic**。 + /// 抓不住：绕开 `Fixture` 直接调 `unlucky_cli::run`（那等于另写一套夹具，`--data-dir` 也没人拼了）。 + pub fn run(&self, args: &[&str]) -> (i32, String, String) { + let requested = args + .iter() + .position(|arg| *arg == "--dest") + .and_then(|index| args.get(index + 1).copied()) + .or_else(|| args.iter().find_map(|arg| arg.strip_prefix("--dest="))); + if args.first() == Some(&"apply") { + assert!( + requested.is_some(), + "apply 必须带 --dest：不带会替换本进程 exe（这套用例里就是测试二进制）。\ + 唯一的 apply 入口是 `Fixture::apply()`" + ); + } + if let Ok(exe) = std::env::current_exe().and_then(std::fs::canonicalize) { + let asked = requested.and_then(|path| std::fs::canonicalize(path).ok()); + let fixture = std::fs::canonicalize(&self.dest).ok(); + for dest in [asked, fixture].into_iter().flatten() { + assert_ne!( + dest, exe, + "替换目标不许是本进程的 exe（`--dest` 点的就是它）" + ); + } + } + let mut full = vec!["update"]; + full.extend_from_slice(args); + let data_dir = self.data.arg(); + full.push("--data-dir"); + full.push(data_dir.as_str()); + super::run_cli(&full) + } + + /// 跑 `apply --dest <副本> --json`（**永远**带 `--dest`，见文件头）。 + pub fn apply(&self) -> (i32, serde_json::Value) { + let dest = self.dest.display().to_string(); + let (code, out, _) = self.run(&["apply", "--dest", &dest, "--json"]); + (code, super::parse_json(&out)) + } + + /// 暂存目录（`<数据根>/.ULL/cache/update/staging`，与 `core::update::staging_dir` 同形）。 + pub fn staging(&self) -> PathBuf { + self.data + .path() + .join(".ULL") + .join("cache") + .join("update") + .join("staging") + } + + /// 暂存目录里还留着什么（`StagedPackage` 落地/被搬走之后应为空）。 + pub fn staging_leftovers(&self) -> Vec { + list_dir(&self.staging()) + } + + /// 安装目录里的备份（`.unlucky-launcher.exe.ullold-*`）。 + pub fn backups(&self) -> Vec { + list_dir(self.install.path()) + .into_iter() + .filter(|name| name.contains(".ullold-")) + .collect() + } + + /// 目标文件当前字节。 + pub fn installed_bytes(&self) -> Vec { + std::fs::read(&self.dest).expect("读目标") + } +} diff --git a/crates/cli/tests/support/update_e2e_sign.rs b/crates/cli/tests/support/update_e2e_sign.rs new file mode 100644 index 0000000..5b899fa --- /dev/null +++ b/crates/cli/tests/support/update_e2e_sign.rs @@ -0,0 +1,69 @@ +//! 更新 e2e 夹具的**签名**部分（M190）：用 `packaging/sign_manifest.py` 给清单签 `.sig`。 +//! +//! 为什么单独一个文件：`support/update_e2e.rs` 已经贴着全仓 400 行红线（M190 r1 复审 P1-3）， +//! 而签名这一摊只被 `Fixture::publish` 用到。搬出来是纯搬家，语义未改。 +//! +//! 为什么走**真脚本**而不是在测试里再写一份签名：这样这套端到端用例同时是「发布侧签名脚本 ⇒ +//! 真二进制验签」的跨实现证据（Python 签、Rust 验）。脚本零第三方依赖，CI runner 与开发机都自带 +//! python3/python；找不到 python 时这套用例**直接红**（不静默跳过——跳过等于这条链没有证据）。 + +use std::path::Path; + +/// 测试签名钥的种子（**公开**：只对 `update-test-source` 构建有意义，正式信任表里没有这把钥， +/// 见 `crates/core/src/update/trust.rs::TEST_ONLY`）。 +const TEST_KEY_SEED: &str = "ull-m190-test-key-seed-000000001"; +/// 测试钥的 `key_id`（与 `trust.rs::TEST_ONLY` 一致）。 +const TEST_KEY_ID: &str = "test-only-key"; + +/// 用 `packaging/sign_manifest.py` 给刚落盘的清单签一份 `.sig`（M190）。 +/// +/// 为什么走**真脚本**而不是在测试里再写一份签名：这样这套端到端用例同时是「发布侧签名脚本 ⇒ +/// 真二进制验签」的跨实现证据（Python 签、Rust 验）。脚本零第三方依赖，CI runner 与开发机都自带 +/// python3/python；找不到 python 时这套用例**直接红**（不静默跳过——跳过等于这条链没有证据）。 +pub fn write_signature(manifest_path: &Path) { + let script = Path::new(env!("CARGO_MANIFEST_DIR")).join("../../packaging/sign_manifest.py"); + assert!(script.is_file(), "找不到签名脚本：{}", script.display()); + let seed_hex: String = TEST_KEY_SEED + .as_bytes() + .iter() + .map(|byte| format!("{byte:02x}")) + .collect(); + let secret = format!(r#"{{"key_id":"{TEST_KEY_ID}","seed_hex":"{seed_hex}"}}"#); + let mut command = None; + for candidate in ["python3", "python"] { + if std::process::Command::new(candidate) + .arg("--version") + .output() + .is_ok_and(|output| output.status.success()) + { + command = Some(candidate); + break; + } + } + let python = command.unwrap_or_else(|| panic!("这套用例需要 python3/python 跑 {script:?}")); + let output = std::process::Command::new(python) + .arg(&script) + .arg("--sign") + .arg(manifest_path) + .env("ULL_MANIFEST_SIGNING_KEY", &secret) + .output() + .expect("跑签名脚本"); + assert!( + output.status.success(), + "签名脚本失败：stdout={} stderr={}", + String::from_utf8_lossy(&output.stdout), + String::from_utf8_lossy(&output.stderr) + ); + assert!( + manifest_path + .with_file_name(format!( + "{}.sig", + manifest_path + .file_name() + .map(|name| name.to_string_lossy().into_owned()) + .unwrap_or_default() + )) + .is_file(), + "签名脚本没产出 .sig" + ); +} diff --git a/crates/cli/tests/update_e2e_tamper_test.rs b/crates/cli/tests/update_e2e_tamper_test.rs new file mode 100644 index 0000000..2fb8091 --- /dev/null +++ b/crates/cli/tests/update_e2e_tamper_test.rs @@ -0,0 +1,107 @@ +//! 更新通道端到端验收（M169）的**拒绝侧**：篡改摘要、篡改包体、截断包体。 +//! +//! 正路与幂等在 `update_e2e_test.rs`（现场说明、抓得住/抓不住、不验的部分都在那边，别重复读）。 +//! 这里只钉一条底线：**校验不过就一个字节都不许落到目标上**，而且失败不会把现场搞脏到 +//! 「修好清单也装不上」。 +//! +//! ⚠ 这三例**抓不住回滚/备份**：摘要与长度失败都发生在 `install_staged` 之前，那一步走不到 +//! （r1 复审 ⑤ 的变异实测：去掉 dest 备份后这三例仍全绿）。回滚由 `update_e2e_test.rs` 的备份 +//! 断言与 `core::update::tests::install_cases` 守。 +//! +//! 一键跑（必须带 feature；tower 定案：验收落在 release profile 上）： +//! +//! ```text +//! cargo test --release -p unlucky-cli --features update-test-source --test update_e2e_tamper_test +//! ``` +//! +//! 不带 feature 时整个目标 `#![cfg]` 掉（0 个用例）——测试通道在那种构建里不存在。 + +#![cfg(feature = "update-test-source")] + +#[path = "support/mod.rs"] +mod support; + +use support::update_e2e::{channel_lock, sha256, Channel, Fixture, INSTALLED}; + +/// 清单的 `sha256` 与盘上字节不符 ⇒ 拒绝，且**现有安装一个字节都不动**。 +/// +/// 抓得住：校验和判据被绕过（写成恒真、先搬后校、只比长度）。抓不住：清单与包体一起被换 +/// （同时改 sha），那条路上没有可信根。 +#[test] +fn a_tampered_digest_is_refused_and_leaves_the_install_intact() { + let _serial = channel_lock(); + let _restore = Channel::capture(); + let fx = Fixture::new("e2e-digest"); + Channel::enable(fx.dist.path()); + // 长度对、摘要错：先过长度判据，才能测到摘要这一关。 + fx.publish(&sha256(b"another build entirely"), fx.payload.len() as u64); + + let (code, json) = fx.apply(); + assert_ne!(code, 0, "摘要不符必须拒绝（实际退出码 0）：{json}"); + assert_eq!(json["error"]["code"], "update_apply_failed", "{json}"); + assert_eq!(json["error"]["detail"]["kind"], "digest_mismatch", "{json}"); + + assert_eq!(fx.installed_bytes(), INSTALLED, "校验失败不许动目标文件"); + assert!( + fx.backups().is_empty(), + "还没走到替换就失败了，安装目录里不该出现 .ullold：{:?}", + fx.backups() + ); + assert!( + fx.staging().exists(), + "下载过才会建暂存目录（说明失败点在双检，不是根本没下）" + ); + assert!( + fx.staging_leftovers().is_empty(), + "校验失败的 .ullupd 必须被删掉：{:?}", + fx.staging_leftovers() + ); + + // 修好清单再装一次：失败没把现场搞脏，这条路还能走通。 + fx.publish_good(); + let (code, json) = fx.apply(); + assert_eq!(code, 0, "修好清单之后应能装上：{json}"); + let data = support::update_e2e::payload(&json); + assert_eq!(data["status"], "installed", "{json}"); + assert_eq!(fx.installed_bytes(), fx.payload); +} + +/// 产物被换（清单没动）⇒ 一样拒绝：篡改落在哪一侧都能抓到。 +#[test] +fn a_tampered_artifact_is_refused_too() { + let _serial = channel_lock(); + let _restore = Channel::capture(); + let fx = Fixture::new("e2e-artifact"); + Channel::enable(fx.dist.path()); + fx.publish_good(); + // 盘上换成同长度的另一份字节：只有摘要能抓（长度判据看不出区别）。 + let mut evil = fx.payload.clone(); + evil[0] ^= 0xff; + std::fs::write(fx.dist.path().join(&fx.asset), &evil).expect("篡改产物"); + + let (code, json) = fx.apply(); + assert_ne!(code, 0, "篡改的包必须拒绝：{json}"); + assert_eq!( + json["error"]["detail"]["kind"], "digest_mismatch", + "篡改产物应当报摘要不符：{json}" + ); + assert_eq!(fx.installed_bytes(), INSTALLED); + assert!(fx.staging_leftovers().is_empty()); +} + +/// 包体被截断（清单长度按完整包算）⇒ 长度判据先拒：不读摘要、不碰目标。 +#[test] +fn a_truncated_payload_is_refused_as_size_mismatch() { + let _serial = channel_lock(); + let _restore = Channel::capture(); + let fx = Fixture::new("e2e-truncated"); + Channel::enable(fx.dist.path()); + fx.publish_good(); + let full = fx.payload.clone(); + std::fs::write(fx.dist.path().join(&fx.asset), &full[..full.len() / 2]).expect("截断产物"); + + let (code, json) = fx.apply(); + assert_ne!(code, 0, "截断的包必须拒绝：{json}"); + assert_eq!(json["error"]["detail"]["kind"], "size_mismatch", "{json}"); + assert_eq!(fx.installed_bytes(), INSTALLED); +} diff --git a/crates/cli/tests/update_e2e_test.rs b/crates/cli/tests/update_e2e_test.rs new file mode 100644 index 0000000..ce342e2 --- /dev/null +++ b/crates/cli/tests/update_e2e_test.rs @@ -0,0 +1,259 @@ +//! 更新通道端到端验收（M169）：**临时数据根 + 本地更新源 + 真形状的清单与产物**， +//! 从 CLI 入口走完「发现新版本 → 下载 → 长度/SHA256 双检 → 就位」。 +//! +//! 一键跑（**必须带 feature**；tower 要求验收落在 release profile 上，debug 与 release 的 +//! `debug_assertions`、优化与 panic 行为都不同，用 debug 验收等于没验真实产物）： +//! +//! ```text +//! cargo test --release -p unlucky-cli --features update-test-source \ +//! --test update_e2e_test --test update_e2e_tamper_test +//! ``` +//! +//! （两个测试目标各跑一半：本文件是正路 + 幂等，`update_e2e_tamper_test` 是篡改/截断。） +//! +//! 不带 `--features update-test-source` 时整个目标 `#![cfg]` 掉（**0 个用例**，不是绿）：测试通道 +//! 在那种构建里根本不存在，「环境变量设满也走 GitHub」由 `crates/core` 的 +//! `the_test_channel_is_a_compile_time_opt_in` 在**不带 feature 的跑法**下守着。 +//! +//! 为什么需要 feature：`ULL_UPDATE_DIR` 曾经只在 `debug_assertions` 下生效，于是发布产物（release） +//! **没法**指向本地源，这条链在 release 上从来没有端到端证据。M169 把判据换成编译期 feature +//! （默认关 ⇒ 官方二进制里没有这条路径），验收构建显式打开它。 +//! +//! # 现场 +//! +//! 见 `tests/support/update_e2e.rs`：数据根 / 本地源 / 安装目录三份临时目录，产物是现场构建出来的 +//! `ull.exe` 的**前 1 MiB**（真 PE 头、真字节；整份 ~400 MB，测材太重在 `PAYLOAD_LIMIT` 的注释里 +//! 写了原因），清单与 `packaging/tests/manifest.golden.json` 同字段。**`--dest` 永远指向临时副本** +//! ——这个文件里没有一处会替换本进程的 exe。 +//! +//! # 抓得住什么 / 抓不住什么 +//! +//! | 本套断言 | 抓得住 | 抓不住 | +//! |---|---|---| +//! | 清单 → 选版本 → 下载 → 双检 → 就位整环跑通 | 任一环断了（字段拼错、渠道不符、没下、没校验、没搬）都会红 | 真 GitHub Release 的下载链路（本套一个字节不出网） | +//! | 清单 `sha256` 与盘上字节不符 ⇒ 拒绝 + 目标不动 | 「校验和判据被绕过/写成恒真」；篡改包体或篡改清单都能抓（见 `update_e2e_tamper_test`） | 「CDN 换了内容**而清单里的 sha 也一起换**」——这条路上没有可信根，只能靠 GitHub 侧 | +//! | 清单 `size` 与盘上长度不符 ⇒ 拒绝 | 截断/拼接（长度判据先跑，比摘要便宜） | 同上：清单自己撒谎时没有任何判据能发现 | +//! | 重复 `apply` 后目标字节稳定、暂存无残留、只留一份备份 | 「第二次把 dest 写坏 / 暂存留下垃圾 / 备份无限堆积」 | 「版本号真的前进了」——`current` 取的是**编译期**版本，不读 dest 里的 exe | +//! | 失败后目标仍是旧字节、无 `.ullold-*` | 「校验失败却已经动过目标」 | 跨卷失败路径：本文件只验了跨卷**成功**那一半（见下一行）；跨卷下的中途失败由 `install_io_cases` 注入验 | +//! | 跨卷 `apply`（数据根一卷、安装目录另一卷，M171） | 「rename 不能跨卷 ⇒ 更新必然失败」这条已发布版本上的真 bug；用例自己先证明前提（rename 报 `CrossesDevices`） | 只有一块可写卷的机器上**只有显式豁免才允许跳过**（`ULL_XDEV_TEST_WAIVE=1`，探不到又没豁免 ⇒ 红）；macOS 的跨卷行为一台没跑过 | +//! | 失败路径三例（`update_e2e_tamper_test`：篡改清单 sha / 篡改包体 / 截断） | 「校验判据被绕过」「失败却已动过目标」「失败留下 `.ullupd`」 | **回滚与备份**：摘要/长度失败发生在 `install_staged` **之前**，那一步根本走不到——回滚靠正路的备份断言 + `install_cases` 单测（r1 复审 ⑤ 的变异实测：去掉 dest 备份后失败路径三例仍全绿，只有正路/幂等变红） | +//! +//! # 不验的部分（如实划界） +//! +//! 1. **真实 GitHub Release 下载**：本套一个字节都不出网（源是本地目录）。`releases/latest` 的 +//! 真实响应、镜像/gh-proxy 回退、CDN 的 ETag/断点续传都属于真网络验收。 +//! 2. **GUI 的点击与重启替换**：设置页「下载并安装」、提示条、`RestartNow` 之后的进程重启不在 +//! 自动化里（替换自身 exe 需要真机，且要人工确认新版本能起来）。 +//! 3. **按版本号忽略**：`presenter::host::update_state` 的 `skipped` 是会话级行为，有单测 +//! （`update_session_tests.rs`），CLI 侧没有对应开关，所以这里不覆盖。 +//! 4. **`--dest` 之外的自替换**（替换本进程 exe）：`tests/support/update_e2e.rs` 的文件头写了为什么 +//! 这几条用例永远带 `--dest`，以及「去掉它会真的改名换掉测试二进制」这件事。 +//! 5. **macOS / Linux 上的跨卷**：跨卷用例只在**本机 Windows**（C: NVMe + D: 机械盘）上真跑过； +//! macOS 的卷（APFS 宗卷之间 `/Volumes` 挂载）与 Linux 的 tmpfs↔ext4 一次都没跑——两边的 +//! `EXDEV` 语义相同，但「同目录中转 + 改名」在同一台机器上有没有别的坑，本套没有证据。 + +#![cfg(feature = "update-test-source")] + +#[path = "support/mod.rs"] +mod support; + +use support::update_e2e::{channel_lock, Channel, Fixture, INSTALLED}; + +use unlucky_core::update::Target; + +/// 发现新版本 → 下载 → 双检 → 就位：整环从 CLI 入口跑一遍，并核对每一步的产物。 +#[test] +fn discovers_downloads_and_installs_from_the_local_channel() { + let _serial = channel_lock(); + let _restore = Channel::capture(); + let fx = Fixture::new("e2e-happy"); + Channel::enable(fx.dist.path()); + fx.publish_good(); + + // 1) 发现新版本：源是本地目录，脚本能看出这一份结论来自测试通道。 + let (code, out, err) = fx.run(&["check", "--json"]); + assert_eq!(code, 0, "check 应成功：{err}"); + let json = support::parse_json(&out); + let data = support::update_e2e::payload(&json); + assert_eq!(data["status"], "available", "{json}"); + assert_eq!(data["version"], fx.version.as_str()); + assert_eq!(data["current"], env!("CARGO_PKG_VERSION")); + assert_eq!( + data["size"].as_u64(), + Some(fx.payload.len() as u64), + "清单声明的字节数 = 产物真实字节数：{json}" + ); + assert_eq!(data["target"], Target::current().as_str()); + assert_eq!(data["notes"], "修掉启动崩溃；实例页加载更快"); + assert_eq!(data["forced"], false); + assert_eq!(data["test_source"], true, "测试通道必须在输出里点名"); + assert_eq!( + data["source"], + format!("file:{}", fx.dist.path().display()), + "源必须是本地目录（不是 GitHub）" + ); + + // 2) 人读输出也点名测试通道：人看的那份不能比 JSON 少说一句。 + let (code, human, _) = fx.run(&["check"]); + assert_eq!(code, 0); + assert!(human.contains("发现新版本"), "{human}"); + assert!( + human.contains("测试通道生效"), + "人读输出要点名「这一份结论来自本地夹具」：{human}" + ); + + // 3) 下载 → 长度/SHA256 双检 → 就位。 + let (code, json) = fx.apply(); + assert_eq!(code, 0, "apply 应成功：{json}"); + let data = support::update_e2e::payload(&json); + assert_eq!(data["status"], "installed", "{json}"); + assert_eq!(data["version"], fx.version.as_str()); + assert_eq!( + data["bytes"].as_u64(), + Some(fx.payload.len() as u64), + "{json}" + ); + assert_eq!(data["path"], fx.dest.display().to_string().as_str()); + assert_eq!(data["test_source"], true); + let backup = data["backup"] + .as_str() + .expect("旧版本应留备份（回滚用）") + .to_string(); + + // 4) 盘上事实：目标 = 产物字节，备份 = 旧字节，暂存无残留。 + assert_eq!( + fx.installed_bytes(), + fx.payload, + "就位的必须就是清单里那一份字节" + ); + assert_eq!( + std::fs::read(&backup).expect("读备份"), + INSTALLED, + "旧版本要在备份里，不能凭空消失" + ); + assert!( + fx.staging_leftovers().is_empty(), + "暂存目录里不许留 .ullupd：{:?}", + fx.staging_leftovers() + ); + + // 5) 装完再查：**仍然报有更新**——因为 current 取的是编译期版本，不读 dest 里的 exe。 + // 这不是 bug（真实场景里替换完就会重启），但脚本作者必须知道这一条。 + let (code, out, _) = fx.run(&["check", "--json"]); + assert_eq!(code, 0); + let json = support::parse_json(&out); + assert_eq!(support::update_e2e::payload(&json)["status"], "available"); +} + +/// 没有清单的本地渠道 = 「还没有任何发布」，不是错误、也不是「已是最新」以外的胡话。 +/// +/// 顺带把「源真的被换成本地目录」在没有产物的情况下也验一遍（全程离线）。 +#[test] +fn an_empty_local_channel_is_up_to_date_not_an_error() { + let _serial = channel_lock(); + let _restore = Channel::capture(); + let fx = Fixture::new("e2e-empty"); + Channel::enable(fx.dist.path()); + + let (code, out, err) = fx.run(&["check", "--json"]); + assert_eq!(code, 0, "缺清单不该是错误：{err}"); + let json = support::parse_json(&out); + let data = support::update_e2e::payload(&json); + assert_eq!(data["status"], "up_to_date", "{json}"); + assert_eq!(data["latest"], serde_json::Value::Null); + assert_eq!(data["test_source"], true); +} + +/// 重复 `apply` 的**终态**与一次相同：目标字节不变、暂存不留垃圾、备份只有一份。 +/// +/// 如实记两条：`apply` 每次都留一份备份（CLI 从不删，等下一次启动/人工清理），但**只留最近一份** +/// （`install::prune_stale_artifacts`，M171）；第二次之所以还会「装上」，是因为 `current` 是编译期 +/// 版本——重复执行不是空操作，只是结果幂等。 +#[test] +fn applying_twice_leaves_the_same_target_bytes() { + let _serial = channel_lock(); + let _restore = Channel::capture(); + let fx = Fixture::new("e2e-twice"); + Channel::enable(fx.dist.path()); + fx.publish_good(); + + for round in 1..=2 { + let (code, json) = fx.apply(); + assert_eq!(code, 0, "第 {round} 次 apply 应成功：{json}"); + assert_eq!(support::update_e2e::payload(&json)["status"], "installed"); + assert_eq!( + fx.installed_bytes(), + fx.payload, + "第 {round} 次 apply 之后目标字节必须仍是产物" + ); + assert!( + fx.staging_leftovers().is_empty(), + "第 {round} 次 apply 之后暂存目录还有 {:?}", + fx.staging_leftovers() + ); + } + assert_eq!( + fx.backups().len(), + 1, + "只留最近一份备份（每次 apply 建一份、成功即清更早的）：{:?}", + fx.backups() + ); +} + +/// 跨卷（M171）：数据根在一卷、安装目录在另一卷时，整环从 CLI 入口仍然跑通。 +/// +/// 这正是已发布版本上必然失败的那个场景（便携版放 U 盘、数据根在 D 盘而程序在 C 盘）： +/// `stage()` 把包落在 `<数据根>/cache/update/staging`，`install_staged()` 要把包搬进 exe 目录， +/// 而 `rename` 不能跨卷。修法是先落到**目标同目录**的中转名（同卷改名）再顶上去。 +/// +/// 用例先自己证明**前提成立**（从数据根到安装目录 rename 必须报 `CrossesDevices`），否则 +/// 「跨卷成功」这句话就是假的。本机只有一块可写卷时**只有显式豁免才允许跳过** +/// （`ULL_XDEV_TEST_WAIVE=1`，见 `support::cross_volume_waived`）：探不到又没豁免 ⇒ 红。 +/// 跨卷逻辑本身另由 `crates/core` 的 `install_xdev_cases`（真跨卷）与 `install_io_cases`（注入）守着。 +#[test] +fn installs_across_volumes_from_the_cli() { + let _serial = channel_lock(); + let _restore = Channel::capture(); + let Some(fx) = Fixture::cross_volume("e2e-xdev") else { + support::cross_volume_waived("cli-e2e"); + return; + }; + Channel::enable(fx.dist.path()); + fx.publish_good(); + + // 前提：数据根（暂存所在地）与安装目录**真的**不同卷。 + let install_dir = fx.dest.parent().expect("安装目录").to_path_buf(); + let probe = fx.data.path().join("volume-probe.bin"); + std::fs::write(&probe, b"probe").expect("写探针"); + let cross = std::fs::rename(&probe, install_dir.join("volume-probe.bin")) + .expect_err("跨卷 rename 必须失败"); + assert_eq!( + cross.kind(), + std::io::ErrorKind::CrossesDevices, + "前提不成立：数据根与安装目录同卷（{cross}）" + ); + + let (code, json) = fx.apply(); + assert_eq!(code, 0, "跨卷 apply 应成功：{json}"); + let data = support::update_e2e::payload(&json); + assert_eq!(data["status"], "installed", "{json}"); + assert_eq!(data["path"], fx.dest.display().to_string().as_str()); + assert_eq!( + fx.installed_bytes(), + fx.payload, + "装上去的必须是清单里那一份完整字节（不是半截）" + ); + assert!( + fx.staging_leftovers().is_empty(), + "暂存目录里不许留 .ullupd：{:?}", + fx.staging_leftovers() + ); + let backups = fx.backups(); + assert_eq!(backups.len(), 1, "旧版本要留一份备份：{backups:?}"); + let backup = install_dir.join(&backups[0]); + assert_eq!( + std::fs::read(&backup).expect("读备份"), + INSTALLED, + "旧字节必须完整留在备份里" + ); +} diff --git a/crates/core/Cargo.toml b/crates/core/Cargo.toml new file mode 100644 index 0000000..aef07b1 --- /dev/null +++ b/crates/core/Cargo.toml @@ -0,0 +1,90 @@ +[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 +# M190（core::update::ed25519）：清单签名验签（官方实现，见 workspace 依赖处的取舍说明）。 +ed25519-dalek.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 + +[features] +# M169：把「本地更新源」这条测试通道**编进二进制**。**默认关**——官方发布构建不带它， +# `core::update::job::default_source` 里那条分支根本不存在（编译期事实，不靠运行时判据）。 +# 验收用法见 `crates/cli/tests/update_e2e_test.rs` 的文件头；`packaging/check_test_source_off.py` +# 守门「发布流水线与打包脚本都不许打开它」。 +update-test-source = [] + +# M190：把**测试公钥**并进信任表（`trust::TEST_ONLY`）。它只加一把**公开**的钥，**不**开任何数据源 +# 开关（没有环境变量、没有 `DirSource`）。唯一使用者是 `crates/presenter` 的 `[dev-dependencies]`： +# presenter 的更新链路用例要构造「本构建认得」的签名清单，而它们编译 core 时既没有 `cfg(test)`， +# 也不该去打开 `update-test-source`（那条同时给出「本地目录当更新源」这条路）。 +# 守门：`packaging/check_test_key_off.py`（只许出现在这里与 presenter 的 dev-dependencies）。 +update-test-key = [] 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//.json` 的继承链 + 库坐标（[`snapshot`]），**不解析** +//! `--` 这类实例 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, + /// 摘要表（键名小写）。Modrinth 侧必须含 `sha1` 与 `sha512`——后者是 mrpack 的硬要求。 + pub hashes: BTreeMap, + /// 服务端记录的文件字节数（与本地实际字节数不一致时以本地为准，见 `pipeline`）。 + pub size: Option, + /// CurseForge `projectID`。 + pub project_id: Option, + /// CurseForge `fileID`。 + pub file_id: Option, +} + +impl RemoteHit { + /// 一次 Modrinth 命中：直链 + 摘要表（必须有 `sha512`，否则 mrpack 写不出来）。 + #[must_use] + pub fn modrinth( + downloads: Vec, + hashes: BTreeMap, + size: Option, + ) -> 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) -> 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; + + /// 按 CurseForge 指纹查项目/文件；查不到返回 `None`。 + /// + /// 调用方已按哨兵值（`811513880`）短路，实现不必重复判断。 + fn curseforge_by_fingerprint(&self, fingerprint: u32) -> Option; +} + +/// 离线：什么都证明不了 ⇒ 所有文件内联。 +/// +/// 这是**默认**行为，也是本仓库当前的唯一实现：没有 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 { + None + } + + fn curseforge_by_fingerprint(&self, _fingerprint: u32) -> Option { + 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) { + // 指纹要读两遍盘；读不出来就按"没有 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, +) -> (FileReason, Option) { + 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//.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, + version: Option, + version_id: Option<&'a str>, + content_roots: Option>, + 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) -> Self { + self.name = Some(name.into()); + self + } + + /// 包版本（写进 CF `version` / mrpack `versionId`）。 + #[must_use] + pub fn with_version(mut self, version: impl Into) -> 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) -> 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//.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 { + 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 = Vec::with_capacity(locals.len() + skipped.len()); + let mut overrides: Vec = Vec::new(); + let mut sources: BTreeMap = 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 { + 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(&self, serializer: S) -> Result { + 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(&self, serializer: S) -> Result { + 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, + /// CurseForge `projectID`（远程引用到 CF 时才有）。 + pub project_id: Option, + /// CurseForge `fileID`。 + pub file_id: Option, + /// 是否禁用态（`.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, + /// 游戏版本（来自实例快照）。 + pub minecraft: Option, + /// 加载器（`fabric-loader 0.15.11` 这种人读串，来自实例快照）。 + pub loaders: Vec, + /// 逐文件结果（按路径排序）。 + pub files: Vec, + /// 已知的表达不了的差异 / 值得用户知道的取舍。 + pub notes: Vec, +} + +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 { + self.files + .iter() + .filter(|file| file.class == FileClass::Inline) + } + + /// 不可导出的项（逐条给 `path` + `reason` 用）。 + pub fn skipped_files(&self) -> impl Iterator { + 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..f13f331 --- /dev/null +++ b/crates/core/src/addon/export/scan.rs @@ -0,0 +1,190 @@ +//! 实例目录扫描：把"磁盘上有什么"变成 [`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, Vec) { + let mut files: Vec = Vec::new(); + let mut skipped: Vec = 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 = 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::, _>>().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` 这种"禁用 + 旧残留"组合）。 +/// +/// M224 收敛：判据只有 [`crate::addon::mods::suffix`] 一处（启停也要用它，见 +/// `DevDocs/PlanDoc/08-mod-and-recommend.md` §3）。这里保留函数名与签名，行为逐字不变。 +#[must_use] +pub fn is_disabled_path(path: &str) -> bool { + crate::addon::mods::is_disabled_path(path) +} 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 的形状是社区约定，不是规范：`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:`、 +//! `org.quiltmc:quilt-loader:`、`net.minecraftforge:forge:`、 +//! `net.neoforged:neoforge:`（`fmlloader` 也认，它是 Forge 的拆分包）。 +//! +//! 这条口径由 tower 批准（M112）："解析 `--` 字符串是猜"。 +//! +//! # 版本号里的 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, + /// 加载器版本（已剥掉可能存在的 `-` 前缀）。 + pub version: String, +} + +/// 实例快照：游戏版本 + 加载器集合（顺序即 `libraries[]` 里出现的顺序）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct InstanceSnapshot { + /// 原版游戏版本（`1.20.1`）。 + pub game_version: String, + /// 加载器依赖（原版实例为空）。 + pub loaders: Vec, +} + +/// 读一个实例目录的快照。 +/// +/// `version_id` 给定时只读 `versions//.json`；`None` 时取 `versions/` 里**继承链的叶子** +/// （真实实例有"原版 + 加载器层"两个目录，叶子才是实例自己）。叶子多于一个时无法判断， +/// 宁可报错也不猜。 +pub fn read_instance_snapshot( + root: &Path, + version_id: Option<&str>, +) -> PackResult { + 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 = 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 { + let entries = std::fs::read_dir(versions_dir).map_err(|error| { + PackError::unsupported(format!( + "实例里没有可读的 {}：{error}", + versions_dir.display() + )) + .with_hint("导出需要实例的版本 JSON（versions//.json 给出游戏版本与加载器）") + })?; + let mut versions: Vec<(String, Option)> = 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/ 下没有 /.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 = 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> { + let mut layers: Vec = Vec::new(); + let mut visited: Vec = 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 { + 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, + } +} + +/// 剥掉版本号里又写了一遍的 `-` 前缀（`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..3231335 --- /dev/null +++ b/crates/core/src/addon/import.rs @@ -0,0 +1,271 @@ +//! 整合包**导入**（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`]：本模块**只消费，不重写**。 +//! +//! # 逐文件冲突决策（M160）：预检 → 用户点头 → 导入 +//! +//! | 步骤 | 入口 | 写盘吗 | +//! |------|------|--------| +//! | 预检：算出"哪几个文件会盖掉用户的" | [`scan_pack`] | **不写**（只读盘算摘要） | +//! | 用户点「全部保留 / 全部覆盖 / 逐项」 | [`ConflictDecisions`] | — | +//! | 导入 | [`import_pack`] | 写（按决策处置冲突） | +//! +//! 三条硬口径（改它们之前先看 [`scan`] 与 [`decision`] 的模块文档）： +//! +//! 1. 进冲突清单的**只有**"目标里已存在同名普通文件且内容（SHA-1）不同"的路径；内容相同、 +//! 目标不存在、以及用户删过的文件都不打扰用户； +//! 2. 决策按**路径**给，逐项优先于整批档，整批档缺省 = 保留； +//! 3. 缺省**绝不覆盖**：没收到决策的冲突一律保留用户那一侧（[`ConflictChoice::default`]）。 +//! +//! # 三条硬要求落在哪 +//! +//! | 要求 | 落点 | +//! |------|------| +//! | overrides 哈希**三方合并**（不静默覆盖用户改动） | [`merge`] 的判据 + [`baseline`] 的 base 侧 | +//! | 两阶段补全 + **失败分级**（仅"缺文件"可容忍） | [`pipeline`] 的顺序 + [`report::MissingFile`] 与 [`error::ImportError`] 的分工 | +//! | 路径穿越**双检** | 开包时 M110 [`crate::addon::pack::PackArchive::open`]，落地时 [`stage`] 的 `normalize_file` + `starts_with` 复核 | +//! +//! # 取消（M195）：每条停下路线都回滚，且**取消不是失败** +//! +//! 用户点「取消」之后管线真的停手：每个阶段边界与长循环内都有检查点，取消后目标目录与导入前 +//! 一致（先写临时目录、最后 `rename` / journal 合并），**不登记实例**。结果类型单列一档 +//! [`ImportStatus::Cancelled`]（`error` 为空、CLI 退出码 `130`、UI 不弹红），与 +//! [`ImportStatus::Failed`] 是两条路。逐段检查点表（含"哪几段没有检查点、为什么"）在 +//! [`cancel`] 模块文档里。 +//! +//! # 三种格式的语义（tower 定案，与 HMCL 相反的两条要记住） +//! +//! - **mrpack**：`overrides/` 与 `client-overrides/` 都解压，**后者胜**（Modrinth 官方客户端语义； +//! HMCL 恰好相反）；`server-overrides/` 客户端**不解压**；其余同名路径无官方优先级 ⇒ 按侧 +//! 优先级落地，不自创排序。**同一实例路径被本包多份声明命中时**（跨侧或同侧重复）， +//! 逐条算清楚：胜者按上面这条规则定，被遮蔽的那条不读字节、只留一条 +//! `pack.import.note.override_shadowed` 注记说明「谁赢了 / 两份内容是否逐字节相同」 +//! （见 [`plan::Shadowed`]）。一路径一行，不再出现"两条 Installed、前一条没落地"。 +//! - **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 cancel = ImportCancel::new(); // 交给「取消」按钮：cancel.cancel() +//! let request = ImportRequest::new(pack_path, instance_dir) +//! .with_fetcher(&fetcher) +//! .with_cancel(&cancel) +//! .with_registration(&launcher_layout, None); +//! let report = download::blocking::block_on(import_pack(&request)); +//! match report.status { /* Success / Partial / Failed / Cancelled */ } +//! ``` +//! +//! # 刻意不做的事（分工边界） +//! +//! - **不删除**整合包升级后不再包含的文件：磁盘上的 `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`] 的说明）。 +//! +//! 取消这一条另有三个欠账（M195 报告同样登记）：①超大整合包（几千文件 / 数 GB）在真实磁盘 +//! 上的**取消响应延迟**没测——最坏要等"当前这一条文件读完/下完 + 一次回滚"；②**单条下载在飞 +//! 不可中断**（[`fetch::PackFetcher`] 没有取消参数），只能等它返回；③macOS / Linux 未验。 + +pub mod baseline; +pub mod cancel; +pub(crate) mod complete; +pub mod decision; +pub mod error; +pub mod fetch; +pub mod merge; +pub mod phase; +pub mod pipeline; +pub mod plan; +pub(crate) mod prepare; +pub mod report; +pub mod scan; +pub mod stage; + +pub use baseline::{PackBaseline, BASELINE_FILE}; +pub use cancel::ImportCancel; +pub use decision::ConflictDecisions; +pub use error::{ImportError, ImportErrorKind}; +pub use fetch::{ + CurseFileMeta, DownloadEngineFetcher, FetchError, FetchErrorKind, FetchFuture, FetchRequest, + FetchedFile, ModrinthFileMeta, PackFetcher, +}; +pub use merge::{MergeAction, MergeDecision}; +pub use plan::{ImportPlan, PlanOverride, PlanRemote, Shadowed, SuffixVariant}; +pub use prepare::baseline_relative; +pub use report::{ + keys, ConflictChoice, ConflictFile, ConflictReason, FileAction, FileSource, ImportIssue, + ImportProgress, ImportProgressSink, ImportReport, ImportStage, ImportStatus, ImportedFile, + LoaderTarget, MissingFile, MissingReason, RegisteredInstance, RejectedComponent, +}; +pub use scan::{scan_pack, scan_pack_online, ImportConflict, ImportScan}; +pub use stage::{RollbackOutcome, Staging}; + +use std::path::Path; + +use crate::addon::pack::PackLimits; +use crate::platform::layout::LauncherLayout; + +/// 整次导入的**缺省**冲突档（逐项决策见 [`ConflictDecisions`]）。 +/// +/// 保留这个名字是因为 CLI 已经按它调用（`pack import --overwrite`）；语义上它就是 +/// [`ConflictDecisions::default_choice`] 的构造器： +/// +/// - [`ConflictPolicy::KeepUser`]（缺省）= 逐项决策的缺省档是"保留"； +/// - [`ConflictPolicy::Overwrite`] = 逐项决策的缺省档是"覆盖"。 +/// +/// **逐项决策优先于它**，所以"整批覆盖 + 某几条保留"是可表达的。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub enum ConflictPolicy { + /// 保留用户那一侧（不覆盖、不补回被删的文件），冲突逐条进报告。 + #[default] + KeepUser, + /// 用包内内容覆盖（用户明确要求"整合包说了算"）。 + Overwrite, +} + +impl ConflictPolicy { + /// 对应的逐项决策缺省档。 + #[must_use] + const fn choice(self) -> ConflictChoice { + match self { + Self::KeepUser => ConflictChoice::KeepUser, + Self::Overwrite => ConflictChoice::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 decisions: ConflictDecisions, + /// 取消令牌；缺省是永不取消的独立令牌（没挂令牌的调用方不必写 `Option`）。 + /// + /// 语义与检查点位置见 [`cancel`] 模块文档：取消后**不得**留下半包 / 覆盖已有实例，也不许 + /// 登记实例；判据是报告里的 [`report::ImportStatus::Cancelled`]（**不是**失败）。 + pub cancel: ImportCancel, + /// 包读取限额（条数 / 单条体积 / 解压总量）。 + pub limits: PackLimits, + /// 进度回调。 + pub progress: Option, +} + +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, + decisions: ConflictDecisions::default(), + cancel: ImportCancel::default(), + 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.decisions = std::mem::take(&mut self.decisions).with_default(policy.choice()); + self + } + + /// 整表逐文件决策（「全部保留 / 全部覆盖 / 逐项」三条入口的产物）。 + #[must_use] + pub fn with_decisions(mut self, decisions: ConflictDecisions) -> Self { + self.decisions = decisions; + self + } + + /// 挂一条逐项决策（链式，便于测试与命令行逐条给）。 + #[must_use] + pub fn with_decision(mut self, path: impl Into, choice: ConflictChoice) -> Self { + self.decisions.set(path, choice); + 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 + } + + /// 挂取消令牌（与调用方手里的那份**共享同一个开关**）。 + /// + /// 取消的结果是 [`ImportStatus`] 里的 `Cancelled`（不是失败）；停在哪一段、哪些段落没有 + /// 检查点，见 [`cancel`] 模块文档的逐段表。 + #[must_use] + pub fn with_cancel(mut self, token: &ImportCancel) -> Self { + self.cancel = token.clone(); + self + } +} + +/// 导入一个整合包。**永不返回 `Err`**：三态 + 取消 + 逐项原因都在 [`ImportReport`] 里。 +pub async fn import_pack(request: &ImportRequest<'_>) -> ImportReport { + pipeline::run(request).await +} + +#[cfg(test)] +mod cancel_tests; 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, +} + +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 { + 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, sha1: impl Into) { + self.files.insert(path.into(), sha1.into()); + } + + /// 序列化成落盘字节（pretty：这文件是给人排障看的）。 + /// + /// # Errors + /// + /// 序列化失败（纯理论，`BTreeMap` 不会失败）。 + pub fn to_bytes(&self) -> Result, String> { + serde_json::to_vec_pretty(self).map_err(|error| format!("基线序列化失败：{error}")) + } +} diff --git a/crates/core/src/addon/import/cancel.rs b/crates/core/src/addon/import/cancel.rs new file mode 100644 index 0000000..70b4559 --- /dev/null +++ b/crates/core/src/addon/import/cancel.rs @@ -0,0 +1,152 @@ +//! 导入的**取消令牌**（M195）：用户点「取消」之后，后台真的停手并回滚，而不是跑完再假装停了。 +//! +//! # 取消不是失败（这是本模块存在的唯一理由） +//! +//! | 现象 | 取消 | 失败 | +//! |------|------|------| +//! | 结果类型 | [`super::report::ImportStatus::Cancelled`] | [`super::report::ImportStatus::Failed`] | +//! | `ImportReport::error` | `None` | 必有 | +//! | CLI 退出码 | `130` | `1` | +//! | UI | 面板收回 / 「已取消」，**不弹红** | 红色结果块 | +//! +//! 管线内部因此有**两条**停止路线：[`Stopped`]。它故意不是 [`super::error::ImportError`] 的 +//! 第 N 个大类——把两者并成一个变体，调用方就再也分不清"用户改主意"与"这包装坏了"， +//! 而这两件事的收尾文案、退出码、重试语义全都不同。 +//! +//! # 取消到底停在哪一段（逐段点名，没有检查点的段落要说明为什么） +//! +//! | 段 | 代码 | 检查点 | 为什么是这个粒度 | +//! |----|------|--------|------------------| +//! | 读包 | `PackArchive::open` → `PackRegistry::read` → `ImportPlan::build` | 入口前、**解析后**各一次 | 一次 `open` 是**不可分割**的（zip 目录 + 四检 + 限额一次扫完），取消等它返回；解析完立刻有一次，所以"用户刚点取消时包已经读完"也不会白写盘 | +//! | 校验 / 补全 | `pipeline::load_baseline`、`complete::complete` | 补全循环**每条目**一次 | 补全是逐条网络请求（按 sha512 反查 sha1），条目之间是天然的取消点 | +//! | 解压 / 写入（暂存目录） | `phase::extract_overrides` | **每条**一次 | 只写临时目录，取消 = 临时目录整个删掉，目标目录一个字节都没动 | +//! | 远端下载（暂存目录） | `phase::fetch_remote` | **每条**一次 | 单条 `PackFetcher::fetch_file` **在飞不可中断**（fetcher 接口没有取消参数），取消在它返回后的下一次检查生效 | +//! | 落盘 | `Staging::commit` | 提交前一次；合并态**逐文件**一次 | 全新导入是一次 `rename`（单步原子，之后无可取消）；合并态是逐文件 `rename` + journal，中途取消**逆序回滚**（新文件删掉、旧备份改回原名） | +//! | 登记实例 | `game::install::register` | 落盘后、登记前一次 | 内容已进目标目录，取消必须**连内容一起回滚**，否则留下"有目录没档案"的半个实例 | +//! | 提交前清中间产物 | `Staging::purge_engine_artifacts` | 与"提交前"共用一次 | 它只是暂存目录里的一次本地遍历，与 `commit` 同一条边界 | +//! +//! **预检（[`super::scan`]）不接取消**：它只读盘、不写一个字节，取消了也不会留下任何东西； +//! 给它加令牌只是让"用户点完取消还得等预检跑完"这件事更难看。 +//! +//! # 与 M186 的下载取消不是一套（不许照搬） +//! +//! M186 的口径是"解析后查一次 + 下载循环每次迭代前查一次"，因为那边是**一批独立文件**的下载 +//! 队列，随时可以在文件之间停。导入是**单包解压 + 两阶段落盘**：真正的风险不是"少下几个文件"， +//! 而是"临时目录里的半包被提交进目标目录"。所以这里多了两处 M186 没有的检查点——**落盘逐文件** +//! 与**登记前**——它们对应两种只能靠回滚才能收场的状态（合并态已搬了一半 / 内容已落盘但档案 +//! 还没建）。照搬 M186 的两处检查会漏掉这两段，正是"取消后仍写盘"的原始 finding 形态。 +//! +//! # 目标的形态（取消后的机器位） +//! +//! 报告的收尾在 [`super::report::ImportReport::cancel`]（三档注记与 `rolled_back` 都在那里）： +//! +//! - 取消发生在**落盘之前** ⇒ 临时目录已删，`rolled_back = true`、`rollback` 为 `None`； +//! - 取消发生在**落盘之中/之后** ⇒ 回滚已做，`rollback` 里有结果，`rolled_back` 只在**完整** +//! 回滚时为 `true`（回滚本身失败时如实为 `false` 并逐项列出，与失败路径同一套口径）。 + +use std::sync::atomic::{AtomicBool, Ordering}; +use std::sync::Arc; + +use super::error::ImportError; + +/// 取消令牌：一个可跨线程共享的布尔开关。 +/// +/// [`Default`] 造出的是**永不取消**的独立令牌（没挂令牌的调用方零成本，不必到处写 `Option`）。 +/// 要用既有 `Arc`（presenter 的 `cancel_pack` 就是这么存的）时走 +/// [`ImportCancel::from_flag`]，两边共享同一个开关。 +#[derive(Debug, Clone, Default)] +pub struct ImportCancel { + flag: Arc, +} + +impl ImportCancel { + /// 一个新的、未取消的令牌。 + #[must_use] + pub fn new() -> Self { + Self::default() + } + + /// 接管一个既有开关（共享同一份状态：外面置位，这里立刻看得见）。 + #[must_use] + pub fn from_flag(flag: Arc) -> Self { + Self { flag } + } + + /// 底层开关（要交给别的线程持有时用）。 + #[must_use] + pub fn flag(&self) -> Arc { + Arc::clone(&self.flag) + } + + /// 置位（幂等）。 + pub fn cancel(&self) { + self.flag.store(true, Ordering::SeqCst); + } + + /// 是否已被取消。 + #[must_use] + pub fn is_cancelled(&self) -> bool { + self.flag.load(Ordering::SeqCst) + } + + /// 一个检查点：已取消 ⇒ [`Stopped::Cancelled`]（由 `?` 冒泡到编排层）。 + pub(crate) fn stopped(&self) -> Result<(), Stopped> { + if self.is_cancelled() { + Err(Stopped::Cancelled) + } else { + Ok(()) + } + } +} + +/// 管线内部的两条停止路线：**取消**与**失败**。 +/// +/// 分开的理由见模块文档："用户改主意"不是"这包装坏了"。`From` 让所有既有的 +/// `?`（IO / 穿越 / 摘要不符 / 限额）继续直接冒泡成 [`Stopped::Failed`]，不用把每个调用点 +/// 都改成手写映射。 +#[derive(Debug)] +pub(crate) enum Stopped { + /// 用户在检查点之前点了取消。 + Cancelled, + /// 一次必须回滚的失败。 + Failed(ImportError), +} + +impl From for Stopped { + fn from(error: ImportError) -> Self { + Self::Failed(error) + } +} + +impl From for Stopped { + fn from(error: crate::addon::pack::PackError) -> Self { + Self::Failed(error.into()) + } +} + +impl From for Stopped { + fn from(error: super::fetch::FetchError) -> Self { + Self::Failed(error.into()) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn a_token_is_shared_only_with_the_flags_it_was_built_from() { + let token = ImportCancel::new(); + assert!(!token.is_cancelled()); + token.cancel(); + assert!(token.is_cancelled(), "自己置位自己要看得见"); + + let foreign = ImportCancel::new(); + assert!(!foreign.is_cancelled(), "默认令牌之间不共享状态"); + + let flag = Arc::new(AtomicBool::new(false)); + let shared = ImportCancel::from_flag(Arc::clone(&flag)); + flag.store(true, Ordering::SeqCst); + assert!(shared.is_cancelled(), "外部置位要被看见"); + } +} diff --git a/crates/core/src/addon/import/cancel_tests.rs b/crates/core/src/addon/import/cancel_tests.rs new file mode 100644 index 0000000..ebc1375 --- /dev/null +++ b/crates/core/src/addon/import/cancel_tests.rs @@ -0,0 +1,400 @@ +//! 导入取消（M195）的守门用例：**取消不是失败**、**取消不留半包 / 不覆盖已有实例**、 +//! **取消后不登记实例**。 +//! +//! # 每条用例挡哪种回归（变异证明见 mission 报告） +//! +//! | 用例 | 删掉哪一处就红 | +//! |------|----------------| +//! | `a_cancel_before_the_first_write_touches_nothing` | 入口检查点 | +//! | `a_cancel_inside_the_extract_loop_leaves_no_half_unpacked_pack` | 解压循环检查点（判据 = 解压进度条数：有 = 1、删掉 = 3） | +//! | `a_cancel_in_the_middle_of_the_merge_restores_the_users_file` | 取消时的 `rollback_merge` | +//! | `a_cancel_right_before_registering_rolls_the_whole_instance_back` | 登记前的检查点 | +//! | `cancel_and_failure_are_two_different_result_types` | 把取消并进 `fail()` 那条路 | +//! +//! # 解压那条必须数事件，其余没有真守卫的检查点 +//! +//! 解压只写**暂存目录**，所以"status == Cancelled / 目标目录不存在 / `files` 为空 / 无残留暂存" +//! 在删掉循环检查点后**依然成立**（提交前检查点会替它停一次）——只有"解了几条"能区分两者。 +//! +//! 有变异证明的只有上表五处。**没有**：检查点②解析后 / ③补全后 / ④开暂存目录前 / ⑤提交前（删掉 +//! 任一处，别的检查点会接住同一次取消，`pipeline.rs` 的断言仍绿）、全新导入 `commit` 的取消分支、 +//! [`super::phase`] 远端下载逐条检查点、[`super::complete`] 补全循环的 `break`——补它们要两段式 +//! 夹具或更多计数探针，本轮没做。 +//! +//! 触发点全部走**进度回调**（置位 = 用户此刻点了取消，无 sleep、无竞态）；全部离线。 + +use std::io::Write; +use std::path::{Path, PathBuf}; +use std::sync::atomic::{AtomicUsize, Ordering}; +use std::sync::Arc; + +use super::cancel::ImportCancel; +use super::report::{ImportProgress, ImportProgressSink, ImportStage, ImportStatus}; +use super::{import_pack, ImportRequest}; +use crate::addon::temp::TempRoot; +use crate::download::blocking::block_on; + +/// 一份只含覆盖内容的 mrpack 清单（`files` 为空 ⇒ 全部内容来自 `overrides/`，无远端条目）。 +const INDEX: &str = r#"{ + "game": "minecraft", + "formatVersion": 1, + "versionId": "1.0.0", + "name": "Cancelable", + "files": [], + "dependencies": {"minecraft": "1.20.1", "fabric-loader": "0.15.11"} +} +"#; + +/// 手造 mrpack（`entries` 是 `overrides/` 下的实例内路径与字节）。 +fn mrpack(tag: &str, entries: &[(&str, &[u8])]) -> (TempRoot, PathBuf) { + let root = TempRoot::new(tag); + let source = root.join("src"); + write_file(&source.join("modrinth.index.json"), INDEX.as_bytes()); + for (path, bytes) in entries { + write_file(&source.join("overrides").join(path), bytes); + } + let pack = root.join("pack.mrpack"); + zip_dir(&source, &pack); + (root, pack) +} + +/// 三个文件的包。 +fn three_files(tag: &str) -> (TempRoot, PathBuf) { + mrpack( + tag, + &[ + ("mods/a.jar", b"pack a"), + ("mods/b.jar", b"pack b"), + ("mods/c.jar", b"pack c"), + ], + ) +} + +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("写文件"); +} + +fn zip_dir(source: &Path, target: &Path) { + let file = std::fs::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::, _>>() + .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"); +} + +/// 在**指定阶段的第一条进度事件**上置位取消（= 用户此刻点了取消）。 +fn cancel_on(token: &ImportCancel, stage: ImportStage) -> ImportProgressSink { + let token = token.clone(); + Arc::new(move |progress: &ImportProgress| { + if progress.stage == stage { + token.cancel(); + } + }) +} + +/// 数**解压阶段**的进度条数，并在第一条上置位取消（这是解压循环检查点唯一的可观测判据： +/// 有它 ⇒ 第一条之后立刻停 = 1；删掉 ⇒ 一路解完 = 文件条数）。 +fn cancel_on_first_extract_counting( + token: &ImportCancel, +) -> (ImportProgressSink, Arc) { + let token = token.clone(); + let count = Arc::new(AtomicUsize::new(0)); + let seen = Arc::clone(&count); + let sink: ImportProgressSink = Arc::new(move |progress: &ImportProgress| { + if progress.stage != ImportStage::Extract { + return; + } + if seen.fetch_add(1, Ordering::SeqCst) == 0 { + token.cancel(); + } + }); + (sink, count) +} + +/// 在**合并态第二条逐文件进度**上置位取消。合并是排序后逐文件搬：第 0 条是基线 +/// （`.ull/pack-baseline.json`，`.` 排最前），第 1 条才是 `mods/a.jar`——`done == 1` 正好是 +/// "用户那个被覆盖的文件已经搬进去、后面还有"的窗口，journal 回滚要接住的正是这一刻。 +fn cancel_on_second_merged_file(token: &ImportCancel) -> ImportProgressSink { + let token = token.clone(); + Arc::new(move |progress: &ImportProgress| { + if progress.stage == ImportStage::Commit && progress.done == 1 { + token.cancel(); + } + }) +} + +/// 目标目录里全部文件的实例内相对路径（排序后）：钉"取消后与导入前逐文件相同"。 +fn files_under(root: &Path) -> Vec { + let mut out = Vec::new(); + let mut pending = vec![root.to_path_buf()]; + while let Some(dir) = pending.pop() { + let Ok(entries) = std::fs::read_dir(&dir) else { + continue; + }; + for entry in entries.filter_map(Result::ok) { + let path = entry.path(); + if entry.file_type().map(|kind| kind.is_dir()).unwrap_or(false) { + pending.push(path); + continue; + } + let relative = path + .strip_prefix(root) + .map(|tail| tail.to_string_lossy().replace('\\', "/")) + .unwrap_or_default(); + out.push(relative); + } + } + out.sort(); + out +} + +/// 父目录里有没有遗留的暂存目录（`..ull-import--`）。 +fn stray_staging(parent: &Path) -> Vec { + std::fs::read_dir(parent) + .map(|entries| { + entries + .filter_map(Result::ok) + .map(|entry| entry.file_name().to_string_lossy().to_string()) + .filter(|name| name.contains(".ull-import-")) + .collect() + }) + .unwrap_or_default() +} + +#[test] +fn a_cancel_before_the_first_write_touches_nothing() { + // 入口检查点：包还没读，目标目录还没建。 + let (root, pack) = three_files("cancel-entry"); + let target = root.join("instance"); + let token = ImportCancel::new(); + token.cancel(); + + let report = block_on(import_pack( + &ImportRequest::new(&pack, &target).with_cancel(&token), + )); + + assert_eq!(report.status, ImportStatus::Cancelled); + assert!( + report.error.is_none(), + "取消不是失败：{}", + report.status.as_str() + ); + assert!(report.pack_name.is_none(), "停在入口 = 包都没读"); + assert!(report.files.is_empty()); + assert!(report.rolled_back, "一个字节都没写，目标目录与导入前一致"); + assert!(!target.exists(), "目标目录不许出现"); + assert!( + stray_staging(root.path()).is_empty(), + "{:?}", + stray_staging(root.path()) + ); +} + +#[test] +fn a_cancel_inside_the_extract_loop_leaves_no_half_unpacked_pack() { + // 解压循环里的检查点：第一条进度事件上取消 ⇒ 第一条写进临时目录，第二条之前停下， + // 临时目录整个删掉 ⇒ 目标目录**不出现半成品**，报告里也不许有"已落地 N 条"的假账。 + let (root, pack) = three_files("cancel-extract"); + let target = root.join("instance"); + let token = ImportCancel::new(); + let (sink, extract_events) = cancel_on_first_extract_counting(&token); + + let report = block_on(import_pack( + &ImportRequest::new(&pack, &target) + .with_cancel(&token) + .with_progress(sink), + )); + + assert_eq!(report.status, ImportStatus::Cancelled, "{:?}", report.error); + // **这一条才是解压循环检查点的判据**：有它 ⇒ 第一条之后立刻停（3 个文件的包里只报了 1 条 + // 解压进度）；删掉它 ⇒ 一路解完（3 条）。其余断言在删掉检查点后仍然成立，挡不住回归。 + assert_eq!( + extract_events.load(Ordering::SeqCst), + 1, + "取消必须在第一条解压之后立刻生效（包里有 3 个文件，解完再停 = 解压段没有检查点）" + ); + assert!(report.error.is_none(), "取消不许带错误"); + assert!(!target.exists(), "不许留下半包：{}", target.display()); + assert!( + report.files.is_empty(), + "取消前的处理记录一条都没落地，报告不许冒充已装：{:?}", + report.files + ); + assert_eq!(report.bytes_written, 0, "写入量要归零"); + assert!(report.registered.is_none()); + assert!(report.rolled_back); + assert!( + stray_staging(root.path()).is_empty(), + "{:?}", + stray_staging(root.path()) + ); +} + +#[test] +fn a_cancel_in_the_middle_of_the_merge_restores_the_users_file() { + // 合并态（目标目录已有内容）：提交是逐文件 rename + journal。取消落在两条搬动之间 ⇒ + // **逆序回滚**必须把用户被覆盖的文件改回来，且不留备份、不留暂存目录。 + let (root, pack) = three_files("cancel-merge"); + let target = root.join("instance"); + write_file(&target.join("mods/a.jar"), b"user a"); + write_file(&target.join("mods/user.jar"), b"user only"); + let token = ImportCancel::new(); + + let report = block_on(import_pack( + &ImportRequest::new(&pack, &target) + .with_cancel(&token) + // 覆盖档：让 a.jar 真的走"备份 + 覆盖"那条路，取消后必须恢复用户内容。 + .with_conflict_policy(super::ConflictPolicy::Overwrite) + .with_progress(cancel_on_second_merged_file(&token)), + )); + + assert_eq!(report.status, ImportStatus::Cancelled, "{:?}", report.error); + assert!(report.error.is_none()); + assert_eq!( + std::fs::read(target.join("mods/a.jar")).expect("用户文件要还在"), + b"user a", + "取消后必须恢复被覆盖的用户文件（回滚被删掉就会读到包内字节）" + ); + assert_eq!( + std::fs::read(target.join("mods/user.jar")).expect("用户文件要还在"), + b"user only" + ); + assert!(!target.join("mods/b.jar").exists(), "取消后不许有半包"); + assert!(!target.join("mods/c.jar").exists(), "取消后不许有半包"); + assert_eq!( + files_under(&target), + vec!["mods/a.jar".to_string(), "mods/user.jar".to_string()], + "目标目录必须与导入前**逐文件相同**（多出基线 / 少掉用户文件都是错）" + ); + assert!( + std::fs::read_dir(target.join("mods")) + .expect("读 mods") + .filter_map(Result::ok) + .all(|entry| !entry.file_name().to_string_lossy().contains(".ullbak-")), + "备份必须被清掉，不许在实例里留 .ullbak-*" + ); + assert!( + stray_staging(root.path()).is_empty(), + "{:?}", + stray_staging(root.path()) + ); + // 回滚做过，且完整 ⇒ 机器位与文案位都说"与导入前一致"。 + assert!(report.rolled_back, "{:?}", report.rollback); + assert_eq!( + report + .rollback + .as_ref() + .map(super::stage::RollbackOutcome::failure_count), + Some(0) + ); +} + +#[test] +fn a_cancel_right_before_registering_rolls_the_whole_instance_back() { + // 登记前的检查点（**取消后不得登记实例**）：取消在"内容已落盘、档案还没建"的窗口里落下 + // ⇒ 连内容一起回滚。删掉这条检查，实例就会被登记上（本用例立刻红）。 + let (root, pack) = three_files("cancel-register"); + let target = root.join("instance"); + let home = root.join("data"); + let layout = crate::platform::layout::LauncherLayout::new(&home); + let token = ImportCancel::new(); + + let report = block_on(import_pack( + &ImportRequest::new(&pack, &target) + .with_cancel(&token) + .with_registration(&layout, Some("cancelled pack")) + .with_progress(cancel_on(&token, ImportStage::Register)), + )); + + assert_eq!(report.status, ImportStatus::Cancelled, "{:?}", report.error); + assert!(report.error.is_none()); + assert!(report.registered.is_none(), "取消后不许登记实例"); + let profiles = crate::game::install::instance::read_profiles(&layout).expect("读档案"); + assert!( + profiles.profiles.is_empty(), + "profiles.json 里不许出现被取消的实例：{:?}", + profiles.profiles + ); + assert!(!target.exists(), "内容已提交也要连内容一起回滚"); + assert!(report.rolled_back); + assert!( + stray_staging(root.path()).is_empty(), + "{:?}", + stray_staging(root.path()) + ); +} + +#[test] +fn cancel_and_failure_are_two_different_result_types() { + // 条款③：取消与真失败必须产生**不同的结果类型**（状态变体、错误位、退出码、文案 key、 + // JSON 的 status 全不同）。把两条路合并成同一个错误，这里就红。 + let (root, pack) = three_files("cancel-vs-fail"); + let token = ImportCancel::new(); + token.cancel(); + let cancelled = block_on(import_pack( + &ImportRequest::new(&pack, &root.join("cancelled")).with_cancel(&token), + )); + + // 真失败：清单坏掉的包（开包成功、读清单失败）。 + let broken = root.join("broken.zip"); + { + let file = std::fs::File::create(&broken).expect("建 zip"); + let mut writer = zip::ZipWriter::new(file); + let options = zip::write::SimpleFileOptions::default() + .compression_method(zip::CompressionMethod::Stored); + writer.start_file("manifest.json", options).expect("写条目"); + writer.write_all(b"{\"manifestType\":").expect("写内容"); + writer.finish().expect("收尾"); + } + let failed = block_on(import_pack(&ImportRequest::new( + &broken, + &root.join("failed"), + ))); + + assert_eq!(cancelled.status, ImportStatus::Cancelled); + assert_eq!(failed.status, ImportStatus::Failed); + assert!(cancelled.error.is_none(), "取消不是错误"); + assert!(failed.error.is_some(), "失败必须带错误"); + assert_ne!( + cancelled.status.exit_code(), + failed.status.exit_code(), + "退出码必须能区分「用户取消」与「装坏了」" + ); + assert_eq!(cancelled.status.exit_code(), 130); + assert_eq!(failed.status.exit_code(), 1); + assert_ne!(cancelled.status.message_key(), failed.status.message_key()); + let cancelled_json = serde_json::to_value(&cancelled).expect("序列化"); + let failed_json = serde_json::to_value(&failed).expect("序列化"); + assert_eq!(cancelled_json["status"], serde_json::json!("cancelled")); + assert_eq!(failed_json["status"], serde_json::json!("failed")); + assert!( + cancelled_json["error"].is_null(), + "取消的 JSON 里不许有 error：{}", + cancelled_json["error"] + ); +} + +mod report_shaping; diff --git a/crates/core/src/addon/import/cancel_tests/report_shaping.rs b/crates/core/src/addon/import/cancel_tests/report_shaping.rs new file mode 100644 index 0000000..fb0845e --- /dev/null +++ b/crates/core/src/addon/import/cancel_tests/report_shaping.rs @@ -0,0 +1,111 @@ +//! 取消报告的**三档诚实口径**：`ImportReport::cancel` 的直接用例（不需要跑管线）。 +//! +//! 从 `cancel_tests.rs` 拆出来只为行数：那边装下五个端到端用例就够满了。 + +use crate::addon::import::report::{FileAction, FileSource, ImportReport, ImportedFile}; +use crate::addon::import::stage::RollbackOutcome; +use crate::addon::import::ImportStatus; + +fn base() -> ImportReport { + ImportReport::empty(std::path::PathBuf::from("instance")) +} + +fn notes(report: &ImportReport) -> Vec<&str> { + report + .warnings + .iter() + .map(|note| note.message.as_str()) + .collect() +} + +#[test] +fn a_cancel_before_writing_never_claims_the_target_was_touched() { + let mut report = base(); + report.cancel(RollbackOutcome::default()); + + assert_eq!(report.status, ImportStatus::Cancelled); + assert!(report.error.is_none(), "取消不许带错误"); + assert!(report.rolled_back); + assert!(report.rollback.is_none(), "没做过回滚就不该有回滚记录"); + let notes = notes(&report); + assert!( + notes.iter().any(|line| line.contains("未被写入")), + "{notes:?}" + ); + assert!( + !notes.iter().any(|line| line.contains("恢复为导入前")), + "{notes:?}" + ); +} + +#[test] +fn a_cancel_after_commit_says_it_rolled_back_exactly_once() { + let mut report = base(); + report.cancel(RollbackOutcome { + attempted: 2, + failed: Vec::new(), + }); + + assert_eq!(report.status, ImportStatus::Cancelled); + assert!(report.rolled_back); + assert_eq!( + report.rollback.as_ref().map(RollbackOutcome::failure_count), + Some(0) + ); + let notes = notes(&report); + assert!( + notes.iter().any(|line| line.contains("恢复为导入前")), + "{notes:?}" + ); + assert!( + !notes.iter().any(|line| line.contains("未被写入")), + "{notes:?}" + ); +} + +#[test] +fn an_incomplete_cancel_rollback_never_claims_consistency() { + let mut report = base(); + report.cancel(RollbackOutcome { + attempted: 3, + failed: vec!["删除 config/a.toml 失败：拒绝访问".to_string()], + }); + + assert_eq!(report.status, ImportStatus::Cancelled); + assert!(!report.rolled_back, "回滚不完整时不许宣称一致"); + let notes = notes(&report); + assert!( + notes + .iter() + .any(|line| line.contains("未能回滚") || line.contains("未完成")), + "{notes:?}" + ); + assert!( + !notes + .iter() + .any(|line| line.contains("恢复为导入前的样子") || line.contains("未被写入")), + "{notes:?}" + ); +} + +#[test] +fn cancelling_clears_the_per_file_ledger_it_never_landed() { + // 取消前的 `files` 是"处理过"而不是"落地过"：留着就是假账（UI 会照它画"已装 N 个"）。 + let mut report = base(); + report.bytes_written = 4096; + report.files.push(ImportedFile { + path: "mods/a.jar".to_string(), + source: FileSource::Overrides, + sha1: None, + bytes: 4096, + disabled: false, + action: FileAction::Installed, + note: None, + }); + + report.cancel(RollbackOutcome::default()); + + assert!(report.files.is_empty(), "取消后不许留下「已落地」的账"); + assert_eq!(report.bytes_written, 0); + assert_eq!(report.installed(), 0); +} diff --git a/crates/core/src/addon/import/complete.rs b/crates/core/src/addon/import/complete.rs new file mode 100644 index 0000000..bdb6f78 --- /dev/null +++ b/crates/core/src/addon/import/complete.rs @@ -0,0 +1,333 @@ +//! 远端条目补全（M162）：**有 `path` 但缺 `hashes.sha1` 的 mrpack 条目，按 sha512 反查 sha1**。 +//! +//! # 补什么、为什么补 +//! +//! M160 的预检用 SHA-1 判「会不会覆盖用户文件」；mrpack 规范里 `sha1` 是**可选**的，只有 +//! `sha512` 必填。于是「只有 path+downloads+hashes(sha512)」的条目在预检里判不了，只能记进 +//! `ImportScan::unknown_remote`。现在拿 sha512 去 Modrinth 反查：站点认得这个文件就把**它自己 +//! 记的 sha1** 填回来（同一个文件在同一站点上的官方摘要），补不出**保持缺**、照旧计数。 +//! +//! # 三条边界 +//! +//! 1. **只补 sha1 / 字节数 / 缺的直链**，绝不改写清单里已有的值（清单说多大就是多大）； +//! 2. **CurseForge 条目不走这里**：它们连路径都没有，补全要 `projectID/fileID` 端点（需要 key）， +//! 那条路仍是 `PackFetcher::curse_file` 的活； +//! 3. **只有「没联网」才立刻停**：第一条 [`FetchErrorKind::Offline`] 之后剩下的条目一律算 +//! 「补不出」，不拿 N 次超时惩罚用户；**404 / 5xx 不停**——真实 mrpack 的文件大多托管在 +//! CurseForge CDN，Modrinth 的 `version_file` 对它们必然 404，把「补不出」当「没联网」 +//! 会让「能补就补」只在第一条恰好托管在 Modrinth 时成立（r1 P1-1 后果 B）。 +//! +//! # 为什么要改 `plan.remote` 而不是 `manifest.files` +//! +//! 导入与预检都只读 `plan.remote`（`manifest` 保留原样作诊断），改一处即可两条路都生效， +//! 也不会让人误以为「清单被回写了」。 + +use super::fetch::FetchErrorKind; +use super::plan::ImportPlan; +use super::report::{keys, ImportIssue, ImportReport}; +use super::ImportRequest; + +/// 一次补全的结果。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub(crate) struct Completion { + /// 补出了 sha1 的条目数 + pub(crate) filled: usize, + /// 仍然补不出的条目数（缺 sha512 / 站点查不到 / 没接源） + pub(crate) unfilled: usize, + /// 是否因为「没联网」提前收工 + pub(crate) offline: bool, +} + +impl Completion { + /// 补全结果 → 报告注记（`None` = 既没补到、也没因断网停下，不必占一行）。 + /// + /// `lead` 是场景前缀（导入用空串、预检用「预检前」）：**文案只此一处**，两个入口不许 + /// 各写一句——r1 抓到的「404 却写因未联网提前停止」正是两处文案各自演进的后果。 + /// 现在 `offline` 只由真 `Offline` 置位，这句话只会在真断网时出现。 + pub(crate) fn note(&self, lead: &str) -> Option { + if self.filled == 0 && !self.offline { + return None; + } + let mut message = if self.filled == 0 { + // 一条也没补到（只可能是断网）：说「补全了 0 条」读起来像成功。 + format!( + "{lead}按 sha512 从 Modrinth 补全 sha1：一条也没补到（补不出 {} 条）", + self.unfilled + ) + } else { + format!( + "{lead}按 sha512 从 Modrinth 补全了 {} 条远端条目的 sha1（补不出 {} 条）", + self.filled, self.unfilled + ) + }; + if self.offline { + message.push_str(if self.filled == 0 { + "；补全因未联网提前停止" + } else { + "；补全因未联网提前停止，其余条目照旧按「缺省保留」处置" + }); + } + Some(ImportIssue::new(keys::NOTE_REMOTE_COMPLETED, message)) + } +} + +/// 补全 + 把注记写进报告（导入管线唯一的入口：一行调用，文案与计数都在本模块）。 +pub(crate) async fn complete_and_note( + request: &ImportRequest<'_>, + plan: &mut ImportPlan, + report: &mut ImportReport, +) { + let completion = complete(request, plan).await; + // 取消时这条注记会撒谎（剩下的条目**没试过**，不是"补不出"）：取消收尾的注记已经说清 + // 停在哪一步，这里不再补一句计数。 + if request.cancel.is_cancelled() { + return; + } + if let Some(note) = completion.note("") { + report.warnings.push(note); + } +} + +/// 跑一次补全（就地改 `plan.remote`）。 +pub(crate) async fn complete(request: &ImportRequest<'_>, plan: &mut ImportPlan) -> Completion { + let mut state = Completion::default(); + let Some(fetcher) = request.fetcher else { + state.unfilled = plan + .remote + .iter() + .filter(|entry| entry.path.is_some() && entry.file.sha1().is_none()) + .count(); + return state; + }; + for entry in plan.remote.iter_mut() { + // 取消检查点：补全是**逐条网络请求**，条目之间是天然的落点；已补的只改内存，不写盘。 + if request.cancel.is_cancelled() { + break; + } + if entry.file.sha1().is_some() { + continue; + } + // CF 条目（没有路径）不归这里：那是 `curse_file` 的活。 + if entry.path.is_none() { + continue; + } + let Some(sha512) = entry.file.sha512().map(str::to_string) else { + state.unfilled += 1; + continue; + }; + if state.offline { + state.unfilled += 1; + continue; + } + match fetcher.modrinth_file_by_sha512(&sha512).await { + Ok(meta) => { + // 站点给的 sha1 也要过形状检查：长度不对的「摘要」比没有更危险。 + match meta.sha1.filter(|hex| is_sha1(hex)) { + Some(sha1) => { + entry.file.hashes.insert("sha1".to_string(), sha1); + if entry.file.size.is_none() { + entry.file.size = meta.size; + } + if entry.file.downloads.iter().all(|url| url.trim().is_empty()) { + if let Some(url) = meta.url { + entry.file.downloads.push(url); + } + } + state.filled += 1; + } + None => state.unfilled += 1, + } + } + Err(error) => { + // 只有**真正的「没联网」**才提前收工：404（这条不在 Modrinth 上，或托管在 + // CF CDN）与 5xx 都只影响这一条，后面那些仍然可能补得出来。 + if error.kind() == FetchErrorKind::Offline { + state.offline = true; + } + state.unfilled += 1; + } + } + } + state +} + +/// 40 位十六进制。 +fn is_sha1(hex: &str) -> bool { + hex.len() == 40 && hex.bytes().all(|byte| byte.is_ascii_hexdigit()) +} + +#[cfg(test)] +mod tests { + //! 覆盖 **pack 用例走不到**的两条分支（r3 复审指出的缺口）： + //! `sha512` 缺失臂与「已有 downloads 不许追加第二个直链」。 + //! + //! mrpack 的读者要求 `hashes.sha512` 必填，所以「有 path 但没有 sha512」在真实文件里进不来 + //! ——它是**防御分支**。直接构造 `ImportPlan` 是唯一能让它变红的办法（不是放宽断言）。 + + use std::path::Path; + use std::sync::atomic::{AtomicU32, Ordering}; + + use super::{complete, Completion}; + use crate::addon::import::fetch::{ + FetchError, FetchFuture, FetchRequest, FetchedFile, ModrinthFileMeta, PackFetcher, + }; + use crate::addon::import::plan::{ImportPlan, PlanRemote}; + use crate::addon::import::report::FileSource; + use crate::addon::import::ImportRequest; + use crate::addon::pack::{PackFile, PackManifest}; + use crate::download::blocking::block_on; + + /// 只回答 `modrinth_file_by_sha512` 的假 fetcher（并记下被问了几次）。 + struct Lookup { + meta: Result, + asked: AtomicU32, + } + + impl PackFetcher for Lookup { + fn modrinth_file_by_sha512<'a>( + &'a self, + _sha512: &'a str, + ) -> FetchFuture<'a, Result> { + Box::pin(async move { + self.asked.fetch_add(1, Ordering::SeqCst); + match &self.meta { + Ok(meta) => Ok(meta.clone()), + Err(error) => Err(error.clone()), + } + }) + } + + fn fetch_file<'a>( + &'a self, + _request: FetchRequest<'a>, + ) -> FetchFuture<'a, Result> { + Box::pin(async move { Err(FetchError::unsupported("本用例不下载")) }) + } + } + + fn plan_with(file: PackFile) -> ImportPlan { + ImportPlan { + format: "modrinth".to_string(), + manifest: PackManifest::default(), + mc_version: "1.20.1".to_string(), + loader: None, + version_id: "1.20.1".to_string(), + rejected: Vec::new(), + notes: Vec::new(), + overrides: Vec::new(), + remote: vec![PlanRemote { + file, + path: Some("mods/no-sha1.jar".to_string()), + source: FileSource::Modrinth, + disabled: false, + }], + max_memory_mb: None, + } + } + + fn entry(sha512: Option<&str>, downloads: &[&str]) -> PackFile { + let mut file = PackFile::with_path("mods/no-sha1.jar"); + file.downloads = downloads.iter().map(|url| (*url).to_string()).collect(); + if let Some(sha512) = sha512 { + file.hashes.insert("sha512".to_string(), sha512.to_string()); + } + file + } + + fn meta(sha1: &str, url: &str) -> ModrinthFileMeta { + ModrinthFileMeta { + sha1: Some(sha1.to_string()), + size: Some(16), + url: Some(url.to_string()), + file_name: Some("no-sha1.jar".to_string()), + } + } + + #[test] + fn an_entry_without_sha512_is_counted_not_guessed() { + // 防御分支：有 path、有 downloads、**没有 sha512** ⇒ 无从反查，如实计数、不发请求。 + let lookup = Lookup { + meta: Ok(meta(&"a".repeat(40), "stub://from-source")), + asked: AtomicU32::new(0), + }; + let mut plan = plan_with(entry(None, &["stub://original"])); + let request = ImportRequest::new(Path::new("pack.mrpack"), Path::new("instance")) + .with_fetcher(&lookup); + let summary = block_on(complete(&request, &mut plan)); + assert_eq!(summary.filled, 0); + assert_eq!(summary.unfilled, 1, "缺 sha512 要计入「补不出」"); + assert_eq!( + lookup.asked.load(Ordering::SeqCst), + 0, + "没有摘要就不许发请求" + ); + assert_eq!(plan.remote[0].file.sha1(), None, "补不出就是补不出，不许猜"); + } + + #[test] + fn an_existing_download_list_is_never_extended() { + // 已有直链 ⇒ 站点给的直链**不许**再追加一条（列表必须逐字相同）。 + let lookup = Lookup { + meta: Ok(meta(&"a".repeat(40), "stub://from-source")), + asked: AtomicU32::new(0), + }; + let mut plan = plan_with(entry(Some(&"c".repeat(128)), &["stub://original"])); + let request = ImportRequest::new(Path::new("pack.mrpack"), Path::new("instance")) + .with_fetcher(&lookup); + let summary = block_on(complete(&request, &mut plan)); + assert_eq!(summary.filled, 1); + assert_eq!(plan.remote[0].file.sha1(), Some("a".repeat(40).as_str())); + assert_eq!( + plan.remote[0].file.downloads, + vec!["stub://original".to_string()], + "已有直链时不许追加第二个（长度与内容都要逐字相同）" + ); + assert_eq!(lookup.asked.load(Ordering::SeqCst), 1); + } + + #[test] + fn offline_with_nothing_filled_does_not_say_zero_items_were_filled() { + let note = Completion { + filled: 0, + unfilled: 3, + offline: true, + } + .note("预检前") + .expect("断网要留一条注记"); + assert!( + note.message.contains("一条也没补到"), + "断网且一条没补到时不许说「补全了 0 条」：{}", + note.message + ); + assert!( + !note.message.contains("补全了 0 条"), + "文案读起来像成功：{}", + note.message + ); + assert!( + !note.message.contains("缺省保留"), + "预检场景没有「缺省保留」这回事：{}", + note.message + ); + + // 真的补到过东西时，仍是原来那句（并带上「其余条目按缺省保留」）。 + let note = Completion { + filled: 2, + unfilled: 1, + offline: true, + } + .note("") + .expect("补到过就要留注记"); + assert!(note.message.contains("补全了 2 条")); + assert!(note.message.contains("缺省保留")); + + // 没补到、也没断网（例如所有摘要站点都不认得）⇒ 不占一行。 + assert!(Completion { + filled: 0, + unfilled: 2, + offline: false + } + .note("") + .is_none()); + } +} diff --git a/crates/core/src/addon/import/decision.rs b/crates/core/src/addon/import/decision.rs new file mode 100644 index 0000000..3dee659 --- /dev/null +++ b/crates/core/src/addon/import/decision.rs @@ -0,0 +1,182 @@ +//! 逐文件冲突决策：`path → Keep / Overwrite`，以及"没收到决策就等于保留"这条硬线。 +//! +//! # 三个入口，一个通道 +//! +//! | 用户在界面上点的 | 落到这里的形状 | +//! |---|---| +//! | 全部保留 | [`ConflictDecisions::keep_all`]（= [`ConflictDecisions::default`]） | +//! | 全部覆盖 | [`ConflictDecisions::overwrite_all`] | +//! | 逐项 | [`ConflictDecisions::with`] 一条一条挂上去，整批档仍是"保留" | +//! +//! 三者共用一个类型，是因为它们要回答的是同一个问题：「这个路径上的冲突该怎么处置」。 +//! 两条独立的落盘规则迟早会打架（一处按整批档、一处按逐项表），所以合并成一处。 +//! +//! # 缺省为什么必须保留 +//! +//! [`ConflictChoice::default`] 是 `KeepUser`：**表里没有这个路径**、或者调用方根本没设过决策时， +//! 结论是"用户那份文件留着"。这不是保守，是正确性——导入的输入是别人做的整合包，用户的 +//! 配置/存档/自己改过的 mod 不能因为"我们没问"就消失。要看"覆盖"只有一个来路：调用方 +//! **显式**说了覆盖（整批档或逐项决策）。 +//! +//! # 决策只作用于**冲突** +//! +//! 非冲突路径（磁盘上没有、或内容与包内一致）根本不看这张表：没有冲突就没有"保留/覆盖"这个 +//! 问题，`merge::decide` 的结论照旧。于是"表里没有这条"永远不会把一份该装的文件漏掉。 + +use std::collections::BTreeMap; + +use super::report::ConflictChoice; + +/// 一次导入的逐文件决策表。 +/// +/// 顺序稳定（`BTreeMap`），所以同一份决策序列化出来的形状是确定的——诊断与测试都能直接比。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ConflictDecisions { + /// 表里没点名的冲突按它处置。 + default: ConflictChoice, + /// 逐项决策（实例内相对路径 → 处置）。 + entries: BTreeMap, +} + +impl Default for ConflictDecisions { + fn default() -> Self { + Self { + // **不许改**：这是"没收到决策不覆盖"的落点。 + default: ConflictChoice::KeepUser, + entries: BTreeMap::new(), + } + } +} + +impl ConflictDecisions { + /// 全部保留（= 缺省）。 + #[must_use] + pub fn keep_all() -> Self { + Self::default() + } + + /// 全部覆盖（用户显式点了「整合包说了算」）。 + #[must_use] + pub fn overwrite_all() -> Self { + Self { + default: ConflictChoice::Overwrite, + entries: BTreeMap::new(), + } + } + + /// 改整批缺省档（逐项决策优先于它）。 + #[must_use] + pub fn with_default(mut self, choice: ConflictChoice) -> Self { + self.default = choice; + self + } + + /// 挂一条逐项决策（链式）。 + #[must_use] + pub fn with(mut self, path: impl Into, choice: ConflictChoice) -> Self { + self.set(path, choice); + self + } + + /// 挂一条逐项决策（就地）。 + pub fn set(&mut self, path: impl Into, choice: ConflictChoice) { + self.entries.insert(path.into(), choice); + } + + /// 整批缺省档。 + #[must_use] + pub const fn default_choice(&self) -> ConflictChoice { + self.default + } + + /// 这个路径的处置：逐项决策优先，其次整批档（**整批档缺省是保留**）。 + #[must_use] + pub fn choice_for(&self, path: &str) -> ConflictChoice { + self.entries.get(path).copied().unwrap_or(self.default) + } + + /// 这个路径有没有被逐项点名（诊断用：区分"用户选的"与"缺省档"）。 + #[must_use] + pub fn explicit(&self, path: &str) -> Option { + self.entries.get(path).copied() + } + + /// 逐项决策的条数（不含整批缺省档）。 + #[must_use] + pub fn len(&self) -> usize { + self.entries.len() + } + + /// 有没有逐项决策。 + #[must_use] + pub fn is_empty(&self) -> bool { + self.entries.is_empty() + } + + /// 逐项决策（按路径排序；进报告/日志用）。 + pub fn iter(&self) -> impl Iterator { + self.entries + .iter() + .map(|(path, choice)| (path.as_str(), *choice)) + } + + /// 逐项决策里"覆盖"的条数。 + #[must_use] + pub fn overwrite_count(&self) -> usize { + self.entries + .values() + .filter(|choice| **choice == ConflictChoice::Overwrite) + .count() + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn missing_decision_never_overwrites() { + // 这张表是"没收到决策就覆盖"的唯一防线：默认档与空表的答案都必须是保留。 + assert_eq!(ConflictChoice::default(), ConflictChoice::KeepUser); + let empty = ConflictDecisions::default(); + assert_eq!(empty.choice_for("config/a.toml"), ConflictChoice::KeepUser); + assert_eq!( + ConflictDecisions::keep_all().default_choice(), + ConflictChoice::KeepUser + ); + assert!(empty.is_empty()); + } + + #[test] + fn per_item_wins_over_the_batch_default() { + let decisions = + ConflictDecisions::overwrite_all().with("mods/pin.jar", ConflictChoice::KeepUser); + assert_eq!( + decisions.choice_for("mods/pin.jar"), + ConflictChoice::KeepUser + ); + assert_eq!( + decisions.choice_for("mods/other.jar"), + ConflictChoice::Overwrite + ); + assert_eq!( + decisions.explicit("mods/pin.jar"), + Some(ConflictChoice::KeepUser) + ); + assert_eq!(decisions.explicit("mods/other.jar"), None); + assert_eq!(decisions.len(), 1); + assert_eq!(decisions.overwrite_count(), 0); + } + + #[test] + fn set_is_idempotent_per_path() { + let mut decisions = ConflictDecisions::keep_all(); + decisions.set("a.toml", ConflictChoice::Overwrite); + decisions.set("a.toml", ConflictChoice::KeepUser); + assert_eq!(decisions.len(), 1); + assert_eq!(decisions.choice_for("a.toml"), ConflictChoice::KeepUser); + assert_eq!(decisions.overwrite_count(), 0); + let paths: Vec<&str> = decisions.iter().map(|(path, _)| path).collect(); + assert_eq!(paths, vec!["a.toml"]); + } +} diff --git a/crates/core/src/addon/import/error.rs b/crates/core/src/addon/import/error.rs new file mode 100644 index 0000000..8901b2e --- /dev/null +++ b/crates/core/src/addon/import/error.rs @@ -0,0 +1,205 @@ +//! 导入链路的**致命**失败分类（能容忍的缺文件不在这里，它们在 +//! [`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, +} + +impl ImportError { + /// 构造。 + #[must_use] + pub fn new(kind: ImportErrorKind, message: impl Into) -> Self { + Self { + kind, + message: message.into(), + hint: None, + } + } + + /// 内容与清单声明不符。 + #[must_use] + pub fn integrity(message: impl Into) -> Self { + Self::new(ImportErrorKind::Integrity, message) + } + + /// 远端补全/下载的致命失败。 + #[must_use] + pub fn fetch(message: impl Into) -> Self { + Self::new(ImportErrorKind::Fetch, message) + } + + /// 加载器信息不足。 + #[must_use] + pub fn loader(message: impl Into) -> Self { + Self::new(ImportErrorKind::Loader, message) + } + + /// 实例登记失败。 + #[must_use] + pub fn instance(message: impl Into) -> Self { + Self::new(ImportErrorKind::Instance, message) + } + + /// 补一句提示。 + #[must_use] + pub fn with_hint(mut self, hint: impl Into) -> 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 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 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::Offline + | FetchErrorKind::Unsupported => ImportErrorKind::Fetch, + }; + Self { + kind, + message: error.message().to_string(), + hint: None, + } + } +} + +impl serde::Serialize for ImportError { + fn serialize(&self, serializer: S) -> Result { + 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..14d1ca2 --- /dev/null +++ b/crates/core/src/addon/import/fetch.rs @@ -0,0 +1,324 @@ +//! 远端补全与下载的**注入点**：导入管线自己不碰网络，只认这个 trait。 +//! +//! # 为什么是 trait 而不是直接调 `DownloadEngine` +//! +//! 三条理由，每条都对应一个真实麻烦： +//! +//! 1. **测试不能联网**：三种格式的端到端用例必须离线跑（CI 没有网，也不该有）； +//! 2. **CurseForge 的 `files[]` 补全还没有客户端**：CF 官方清单只有 `projectID/fileID`， +//! 要 `x-api-key` 的 `api.curseforge.com/v1/mods//files/` 才能换出文件名与地址。 +//! 仓库里没有这个客户端（D10 §5 规划中），而 [`crate::download::DownloadRequest`] **没有 +//! 自定义 header 字段**——硬塞进去会把"补不出来"伪装成"网络失败"。所以默认实现诚实地 +//! 返回 [`FetchErrorKind::Unsupported`]（= 可容忍的"搞不到"，进报告的 `missing`）， +//! **绝不猜下载 URL**：猜出来的地址一旦 404，用户看到的是"导入失败"而不是"这条暂时补不了"； +//! 3. **依赖方向**：`addon` 属于更高层的领域逻辑，让它直接持有一个 `DownloadEngine` 会把 +//! 镜像/健康度/地区档案这些下载侧策略涌进导入链路。 +//! +//! # 生产实现只走 `core::download` +//! +//! [`DownloadEngineFetcher`] 是本 crate 里**唯一**的生产实现，做两件事： +//! +//! 1. **[`PackFetcher::fetch_file`]** —— 交给 [`crate::addon::online::download_verified`]： +//! sha1 由引擎流式校验、sha512 由 addon 侧落盘后复核（引擎的 `Integrity` 只认 Sha1/Sha256）， +//! 失败按 [`crate::addon::online::RETRY_ATTEMPTS`] 重试且不留半截文件； +//! 2. **[`PackFetcher::modrinth_file_by_sha512`]** —— M162 的补全路径：按 sha512 反查 +//! Modrinth 拿同一个文件的官方 sha1（站点不认得就如实报 `NotFound`，由调用方计数）。 +//! +//! 两条都经同一个引擎（`EngineTransport` / `DownloadRequest`），导入链路里**没有**第二个 +//! `reqwest::Client`，也没有第二个重试循环。 + +use std::future::Future; +use std::path::Path; +use std::pin::Pin; + +use crate::addon::online::complete::identity_of; +use crate::addon::online::download::download_verified; +use crate::addon::online::modrinth::HashAlgorithm; +use crate::addon::online::{ + EngineArtifactFetcher, EngineTransport, Modrinth, OnlineError, OnlineErrorKind, +}; +use crate::download::{DownloadEngine, DownloadError, DownloadErrorKind}; + +/// "搞不到"的成因（**分级判据只在这里**）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum FetchErrorKind { + /// 源上确实没有（404 / 文件被删）。 + NotFound, + /// 网络侧失败（超时、连不上、站点 5xx 退避后仍失败）。 + Network, + /// **没联网**：连不上任何候选源（与 `Network` 分开，是因为「补全」见到它要立刻停， + /// 而见到 404 / 5xx 不该停 —— 下一条可能补得出来）。 + Offline, + /// 本地 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::Offline => "fetch_offline", + 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::Offline | Self::Unsupported + ) + } +} + +/// 一次取数失败。 +#[derive(Debug, Clone)] +pub struct FetchError { + kind: FetchErrorKind, + message: String, +} + +impl FetchError { + /// 构造。 + #[must_use] + pub fn new(kind: FetchErrorKind, message: impl Into) -> Self { + Self { + kind, + message: message.into(), + } + } + + /// 这条路走不通。 + #[must_use] + pub fn unsupported(message: impl Into) -> Self { + Self::new(FetchErrorKind::Unsupported, message) + } + + /// 内容与声明不符。 + #[must_use] + pub fn integrity(message: impl Into) -> 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 for FetchError { + fn from(error: DownloadError) -> Self { + // 用**叶子成因**（`effective_kind`）：候选源循环结束时只有一条 `AllSourcesFailed`， + // 直接按它判定会把「这个文件不存在」也算成「网络失败」。 + let kind = match error.effective_kind() { + DownloadErrorKind::NotFound => FetchErrorKind::NotFound, + DownloadErrorKind::Integrity => FetchErrorKind::Integrity, + DownloadErrorKind::Io => FetchErrorKind::Io, + DownloadErrorKind::InvalidRequest => FetchErrorKind::Unsupported, + DownloadErrorKind::Timeout | DownloadErrorKind::Network => FetchErrorKind::Offline, + DownloadErrorKind::ServerError + | DownloadErrorKind::RangeUnsupported + | DownloadErrorKind::AllSourcesFailed => FetchErrorKind::Network, + }; + Self::new(kind, error.message) + } +} + +impl From for FetchError { + fn from(error: OnlineError) -> Self { + let kind = match error.kind() { + OnlineErrorKind::NotFound => FetchErrorKind::NotFound, + OnlineErrorKind::Integrity | OnlineErrorKind::Malformed => FetchErrorKind::Integrity, + OnlineErrorKind::Io => FetchErrorKind::Io, + OnlineErrorKind::Unsupported => FetchErrorKind::Unsupported, + // 「没联网」要能被「补全立刻停」认出来；站点 5xx 只是这一条补不出。 + OnlineErrorKind::NotConnected => FetchErrorKind::Offline, + OnlineErrorKind::Server => FetchErrorKind::Network, + }; + Self::new(kind, error.message().to_string()) + } +} + +/// trait 方法返回的装箱 future（core 不引 `async-trait`，手写 `Pin>` 即可）。 +pub type FetchFuture<'a, T> = Pin + 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, + /// 官方给的 SHA-1。 + pub sha1: Option, + /// 字节数。 + pub size: Option, + /// 项目类别（CF `classId`：6 = mods、12 = resource packs、6945 = shaders …）。 + pub class_id: Option, +} + +/// Modrinth 一个文件的元数据（`files[]` 补全的产物，按 sha512 反查得到）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ModrinthFileMeta { + /// 站点给的 SHA-1（**同一个文件**的官方摘要，不是本地推算） + pub sha1: Option, + /// 站点给的字节数 + pub size: Option, + /// 站点给的直链（清单里没有 downloads 时才用得上） + pub url: Option, + /// 站点给的文件名 + pub file_name: Option, +} + +/// 一次文件下载请求。 +#[derive(Debug, Clone, Copy)] +pub struct FetchRequest<'a> { + /// 逻辑下载地址（官方源）。 + pub url: &'a str, + /// 落盘路径（导入器给的**暂存**路径，不是最终实例路径）。 + pub dest: &'a Path, + /// 期望 SHA-1（清单声明的）。 + pub sha1: Option<&'a str>, + /// 期望 SHA-512（mrpack 的必填摘要；引擎不认这一档，由 `online::download` 落盘后复核）。 + pub sha512: Option<&'a str>, + /// 期望字节数。 + pub size: Option, +} + +/// 一次下载的产物。 +#[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> { + Box::pin(async move { + Err(FetchError::unsupported(format!( + "CurseForge files[] 补全需要 CF API 客户端（projectID={project_id} fileID={file_id}）；当前版本没有，本条记为缺文件" + ))) + }) + } + + /// 按 SHA-512 反查 Modrinth 上这个文件的元数据（**sha1 补全用**）。 + /// + /// 默认实现返回 [`FetchErrorKind::Unsupported`]：没有远程源（离线导入、测试的 `StubFetcher`） + /// 就补不出——这与 M160 的 `unknown_remote` 口径一致：补不出仍要如实计数，**不许猜**。 + fn modrinth_file_by_sha512<'a>( + &'a self, + sha512: &'a str, + ) -> FetchFuture<'a, Result> { + Box::pin(async move { + Err(FetchError::unsupported(format!( + "没有接 Modrinth 源，无法按 sha512 补全这一条（{sha512}）" + ))) + }) + } + + /// 把 `request.url` 下到 `request.dest`。 + fn fetch_file<'a>( + &'a self, + request: FetchRequest<'a>, + ) -> FetchFuture<'a, Result>; +} + +/// 生产实现：把请求交给 `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 modrinth_file_by_sha512<'a>( + &'a self, + sha512: &'a str, + ) -> FetchFuture<'a, Result> { + Box::pin(async move { + let transport = EngineTransport::new(self.engine); + let client = Modrinth::new(&transport); + let version = client + .version_by_hash(HashAlgorithm::Sha512, sha512) + .await + .map_err(FetchError::from)?; + let identity = identity_of(&version, sha512).ok_or_else(|| { + FetchError::new( + FetchErrorKind::NotFound, + format!("站点返回的版本里没有 sha512 与 {sha512} 相同的文件"), + ) + })?; + Ok(ModrinthFileMeta { + sha1: Some(identity.sha1), + size: identity.size, + url: identity.url, + file_name: version + .primary_file() + .map(|file| file.filename.clone()) + .filter(|name| !name.trim().is_empty()), + }) + }) + } + + fn fetch_file<'a>( + &'a self, + request: FetchRequest<'a>, + ) -> FetchFuture<'a, Result> { + Box::pin(async move { + // sha1 交给引擎流式校验、sha512 由 `download_verified` 落盘后复核； + // 失败重试与「不留半截文件」也在那一层（见 `online::download` 的模块文档）。 + let fetcher = EngineArtifactFetcher::new(self.engine); + let done = download_verified( + &fetcher, + request.url, + request.sha1, + request.sha512, + request.size, + request.dest, + ) + .await + .map_err(FetchError::from)?; + Ok(FetchedFile { bytes: done.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..27ec720 --- /dev/null +++ b/crates/core/src/addon/import/merge.rs @@ -0,0 +1,143 @@ +//! 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` | 用户改过：**不许**静默覆盖 | +//! +//! 两条"不许"就是任务里的硬要求（"不得直接盖掉用户改过的文件"）。判据只此一处：决策 +//! （逐项 [`super::decision::ConflictDecisions`]，或整批 [`super::ConflictPolicy`]）为 +//! `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, +} + +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), + // 磁盘上有、内容与包内**逐字节相同**（同一份 SHA-1）。 + // + // 这是"内容相同"的**唯一判据**：预检（`super::scan::judge`）刻意不再自己写一遍 + // `disk == pack` 的早退（复审 r1 P3-2），而是走这里的 `reason == None`。改这一行 + // 会同时影响"导入怎么处置"与"预检列不列这条"，所以两边的测试都会红。 + (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..c420307 --- /dev/null +++ b/crates/core/src/addon/import/phase.rs @@ -0,0 +1,364 @@ +//! 两个落盘阶段的实现：**覆盖内容解压** 与 **远端补全下载**（共用同一张三方合并表）。 +//! +//! 拆出来是为了让 `pipeline.rs` 只剩"顺序与收尾"：阶段实现里看得见"每个文件怎么判"， +//! 编排里看得见"什么时候回滚"。 + +use std::path::Path; + +use super::super::pack::{PackArchive, PackError}; +use super::baseline::PackBaseline; +use super::cancel::Stopped; +use super::error::ImportError; +use super::fetch::{FetchError, FetchRequest}; +use super::merge; +use super::plan::{curse_class_dir, ImportPlan, PlanRemote}; +use super::report::tell; +use super::report::{ImportReport, ImportStage, ImportedFile, MissingFile, MissingReason}; +use super::stage::Staging; +use super::ImportRequest; +use crate::download::verify::{self, digest_bytes}; +use crate::download::HashAlgo; + +mod settle; + +use settle::{conflict, settle}; + +/// 阶段一：覆盖条目落暂存 + 三方合并。 +/// +/// 被同包另一条声明遮蔽的条目（[`super::plan::PlanOverride::shadowed`]）**不读字节、不落地**： +/// 它的结论已经由 `plan::layer::resolve` 算成一条 `NOTE_OVERRIDE_SHADOWED` 注记 +/// （进 `report.warnings`），而这条路径的行由真正的胜者给出——一路径一行，不再出现 +/// "两条 Installed、前一条的哈希其实没落地"。 +/// +/// # 取消检查点 +/// +/// 解压阶段**每条一次**（循环开头）：只写临时目录，取消 = 临时目录整个删掉，目标目录一个 +/// 字节都没动。被 `?` 冒泡出去的 [`Stopped::Cancelled`] 与失败**不是同一条路**。 +pub(crate) async fn extract_overrides( + request: &ImportRequest<'_>, + archive: &PackArchive, + plan: &ImportPlan, + baseline: &PackBaseline, + staging: &Staging, + report: &mut ImportReport, + next: &mut PackBaseline, +) -> Result<(), Stopped> { + let live: Vec<&super::plan::PlanOverride> = plan + .overrides + .iter() + .filter(|entry| entry.shadowed.is_none()) + .collect(); + let total = live.len(); + let target = staging.target().to_path_buf(); + for (index, entry) in live.iter().enumerate() { + // 取消检查点（每条一次）：只写临时目录，停下就是"什么都没发生"。 + request.cancel.stopped()?; + 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()); + // 逐项决策优先，其次整批档（缺省是"保留"）：见 `decision::ConflictDecisions`。 + let picked = request.decisions.choice_for(&entry.path); + let (action, choice) = settle(decision, disk.is_some(), picked); + 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(()) +} + +/// 阶段二：远端条目补全 + 下载 + 同一张合并表。 +/// +/// # 取消检查点 +/// +/// 每条远端条目一次（循环开头）。**单条下载在飞不可中断**（[`super::fetch::PackFetcher`] 没有 +/// 取消参数），所以取消在最坏情况下要等"当前这一条下载返回"；返回后下一次检查立刻生效， +/// 已下到临时目录的字节随临时目录一起删掉。 +pub(crate) async fn fetch_remote( + request: &ImportRequest<'_>, + plan: &ImportPlan, + baseline: &PackBaseline, + staging: &Staging, + report: &mut ImportReport, + next: &mut PackBaseline, +) -> Result<(), Stopped> { + let total = plan.remote.len(); + let target = staging.target().to_path_buf(); + for (index, entry) in plan.remote.iter().enumerate() { + // 取消检查点（每条一次）：上一条下载返回之后立刻生效。 + request.cancel.stopped()?; + 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 picked = request.decisions.choice_for(&resolved.path); + let (action, choice) = settle(decision, disk.is_some(), picked); + 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(), + sha512: resolved.sha512.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 + )) + .into()); + } + } + let decision = merge::decide(&pack_sha1, baseline.sha1(&resolved.path), disk.as_deref()); + let picked = request.decisions.choice_for(&resolved.path); + let (action, choice) = settle(decision, disk.is_some(), picked); + 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, // 两档摘要各自可能缺（CF 只有 sha1、mrpack 可能只有 sha512） + sha512: Option, + size: Option, +} + +/// 把条目补全成"有路径、有地址"。 +/// `Ok(None)` = 这条补不出来（进 `missing`）；`Err` = 致命（本地 IO / 内容不符）。 +async fn resolve( + request: &ImportRequest<'_>, + entry: &PlanRemote, +) -> Result, 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), + sha512: entry.file.sha512().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, + // CF 官方只给 sha1，这一档没有可核的期望值。 + sha1: meta.sha1, + sha512: None, + size: meta.size, + })) +} + +/// 组装一条缺失记录（条目本身补不出来）。 +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, 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 { + 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) -> ImportError { + PackError::io(message).into() +} diff --git a/crates/core/src/addon/import/phase/settle.rs b/crates/core/src/addon/import/phase/settle.rs new file mode 100644 index 0000000..bdf4936 --- /dev/null +++ b/crates/core/src/addon/import/phase/settle.rs @@ -0,0 +1,61 @@ +//! 合并判定 + 决策 → 实际动作，以及冲突记录的组装。 +//! +//! 从 [`super`] 拆出来的唯一原因是行数上限（400 行），行为逐字未变：这两个函数是**纯函数**， +//! 不碰盘、不看时钟，所以搬动它们不影响任何判据。 + +use super::super::merge::{self, MergeAction}; +use super::super::report::{ConflictChoice, ConflictFile, ConflictReason, FileAction}; + +/// 合并判定 + 决策 → 实际动作。 +/// +/// `picked` 是这一次的处置（逐项决策或整批档，见 [`crate::addon::import::decision::ConflictDecisions`]）： +/// 它**只对冲突生效**——`Install` / `SkipIdentical` 不受它影响，所以"用户点错一条保留"不会漏装。 +pub(super) fn settle( + decision: merge::MergeDecision, + disk_exists: bool, + picked: ConflictChoice, +) -> (FileAction, ConflictChoice) { + let overwrite = picked == ConflictChoice::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), + } +} + +/// 组装一条冲突记录。 +pub(super) fn conflict( + path: String, + reason: ConflictReason, + choice: ConflictChoice, + pack_sha1: &str, + pack_size: u64, + base_sha1: Option, + disk_sha1: Option, +) -> ConflictFile { + ConflictFile { + path, + reason, + choice, + message_key: reason.message_key(), + pack_sha1: pack_sha1.to_string(), + pack_size, + base_sha1, + disk_sha1, + } +} diff --git a/crates/core/src/addon/import/pipeline.rs b/crates/core/src/addon/import/pipeline.rs new file mode 100644 index 0000000..607e016 --- /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` 里逐项列出——不许在"可能没回干净"时宣称一致。 +//! +//! # 可重试 +//! +//! 失败后目标目录与导入前一致（或明确告诉你哪几项没回去），重跑同一个包是安全的；成功后再跑 +//! 一遍会靠基线里的哈希走"跳过 / 已一致"路径，不会重复写盘。 +//! +//! # 取消（M195）：七个检查点 +//! +//! 编排层负责**阶段边界**的检查点（入口 → 解析后 → 补全后 → 开暂存目录前 → 提交前 → 登记前）， +//! 长循环里的**逐条**检查在各自实现里（解压/下载在 [`super::phase`]，合并落盘在 +//! [`super::stage`]）。逐段表（含"哪几段没有检查点、为什么"）见 [`super::cancel`]。 +//! 每次停下都按"回滚做过什么"收尾：没写盘 ⇒ 删暂存目录；写过 ⇒ 回滚结果如实进报告。 +//! **取消不走 [`failed`]**：它走 [`ImportReport::cancel`]，结果类型是 `Cancelled` +//! 而不是 `Failed`。 + +use super::baseline::PackBaseline; +use super::cancel::Stopped; +use super::error::ImportError; +use super::phase; +use super::plan::ImportPlan; +use super::prepare::{account_plan, probe_and_plan, write_baseline}; +use super::report::{keys, tell, ImportIssue, ImportReport, ImportStage, RegisteredInstance}; +use super::stage::{CommitStop, RollbackOutcome, Staging}; +use super::ImportRequest; + +/// 跑一次导入。**永不返回 `Err`**：成功 / 部分成功 / 失败 / 取消全在报告里。 +pub async fn run(request: &ImportRequest<'_>) -> ImportReport { + let mut report = ImportReport::empty(request.target.to_path_buf()); + // 检查点①：入口（用户可能在上一次点开面板之后、线程起来之前就取消了）。 + if request.cancel.is_cancelled() { + return cancelled(report, RollbackOutcome::default()); + } + tell(&request.progress, ImportStage::Probe, 0, 0, None); + let (archive, mut plan) = match probe_and_plan(request) { + Ok(pair) => pair, + Err(error) => return abandoned(report, error), + }; + account_plan(&mut report, &plan); + // 检查点②：解析后（包读完了，目标目录还一个字节都没写——停下最便宜）。 + if request.cancel.is_cancelled() { + return cancelled(report, RollbackOutcome::default()); + } + super::complete::complete_and_note(request, &mut plan, &mut report).await; + // 检查点③：补全后（补全是逐条网络请求，条目之间已经在 `complete` 里停过一次）。 + if request.cancel.is_cancelled() { + return cancelled(report, RollbackOutcome::default()); + } + + let baseline = { + let (baseline, warnings) = load_baseline(request.target, &plan); + report.warnings.extend(warnings); + baseline + }; + // 检查点④：开暂存目录前（此后磁盘上就有临时目录了）。 + if request.cancel.is_cancelled() { + return cancelled(report, RollbackOutcome::default()); + } + 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)?; + Ok::<(), Stopped>(()) + } + .await; + match staged { + Ok(()) => {} + // 停在暂存阶段：临时目录整个删掉，目标目录与导入前一致（一个字节都没写过）。 + Err(Stopped::Cancelled) => { + staging.abort(); + return cancelled(report, RollbackOutcome::default()); + } + Err(Stopped::Failed(error)) => { + staging.abort(); + return abandoned(report, error); + } + } + + // 检查点⑤：提交前（与"清中间产物"同一条边界）。 + if request.cancel.is_cancelled() { + staging.abort(); + return cancelled(report, RollbackOutcome::default()); + } + + // 引擎的续传残片（`.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); + // 检查点⑥：落盘（全新导入只在 rename 之前；合并态在 `apply_merge` 里逐文件）。 + let token = request.cancel.clone(); + let guard = match staging.commit(&token, &request.progress) { + Ok(guard) => guard, + Err(CommitStop::Cancelled(outcome)) => return cancelled(report, outcome), + Err(CommitStop::Failed(failure)) => { + return record_rollback(failed(report, failure.error), failure.rollback); + } + }; + + if let Some(layout) = request.register { + tell(&request.progress, ImportStage::Register, 0, 0, None); + // 检查点⑦：登记前。内容已经落进目标目录，所以取消要**连内容一起回滚**，否则留下 + // "有目录没档案"的半个实例——这正是"取消后不得登记实例"的判据。 + if request.cancel.is_cancelled() { + let outcome = guard.rollback(); + return cancelled(report, outcome); + } + 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 +} + +/// 取消收尾：把「用户取消」写进报告（**不是失败**），返回收好尾的报告。 +/// +/// 三档注记与 `rolled_back` 的判据在 [`ImportReport::cancel`]（那里也是失败路径的同形三档）。 +fn cancelled(mut report: ImportReport, outcome: RollbackOutcome) -> ImportReport { + report.cancel(outcome); + report +} + +/// 读三方合并的 base 侧：没有 / 读不出来 / **属于别的包** 三条路都不致命。 +/// +/// "属于别的包"要单独说一句：同一目录先后导入两个整合包时，若拿别人的基线当 base，用户改过 +/// 的文件会被判成"整合包升级"而**被静默覆盖**。所以身份不符时降级成"没有基线"并告警。 +/// +/// 返回的告警由调用方写进报告（预检也是同一批文案——两侧对"有没有基线"必须有同一个答案）。 +pub(super) fn load_baseline( + target: &std::path::Path, + plan: &ImportPlan, +) -> (PackBaseline, Vec) { + match PackBaseline::load(target) { + Ok(baseline) => { + if baseline.matches_pack(&plan.format, &plan.manifest.name) { + return (baseline, Vec::new()); + } + let warning = ImportIssue::new( + keys::NOTE_BASELINE_PACK_MISMATCH, + format!( + "基线属于另一个整合包（{} / {:?}），本次按「没有基线」处理：磁盘上同名文件一律算用户已有内容", + if baseline.format.is_empty() { + "?" + } else { + &baseline.format + }, + baseline.pack_name + ), + ); + (PackBaseline::default(), vec![warning]) + } + Err(reason) => { + let warning = ImportIssue::new( + keys::NOTE_BASELINE_UNREADABLE, + format!( + "基线读不出来，本次按「没有基线」处理（磁盘上同名文件一律算用户已有内容）：{reason}" + ), + ); + (PackBaseline::default(), vec![warning]) + } + } +} + +/// 把一次回滚的结果写进报告：**文案与机器位同源**，只有完整回滚才宣称"与导入前一致"。 +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 +} + +/// 失败收尾：**只落错误，不宣称目标目录状态**。 +/// +/// 口径由调用方补：从未写过目标目录 ⇒ [`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..f66e70a --- /dev/null +++ b/crates/core/src/addon/import/plan.rs @@ -0,0 +1,371 @@ +//! 清单 → **导入计划**：把三种格式的差异在进解压器之前全部拍平。 +//! +//! 计划是纯计算（只额外读一次 `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 条目顺序落盘"与"按路径 +//! 排序落盘"在无重复时等价。有重复（跨目录）时由侧优先级决定，不靠条目顺序。 +//! **同一实例路径被多份声明命中时逐条算清楚**（[`PlanOverride::shadowed`]）：胜者按上面 +//! 这条规则定，被遮蔽的那条不再读字节、只留一条 `NOTE_OVERRIDE_SHADOWED` 注记说明 +//! "谁赢了"和"两份内容是否逐字节相同"。这是"整包一个策略"到"逐文件事实"的那一步。 +//! 2. **`.disabled` 只认路径后缀**（官方 Modrinth 表达），`.old` **只识别与保留**（不清不删 +//! 不改名）。`env.client=optional` **不是**禁用（"可选"＝安装时可取消勾选）。判据在 +//! [`paths`]。 +//! 3. **MultiMC 的非加载器 component 逐项进报告**（`org.lwjgl3` / `net.fabricmc.intermediary` +//! / 社区自定义 uid）：静默丢它们等于"看起来装好了、其实少了补丁层"。 + +mod layer; +pub mod paths; + +pub use layer::Shadowed; +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, + PackSide, +}; +use super::error::ImportError; +use super::report::{keys, FileSource, ImportIssue, LoaderTarget, RejectedComponent}; + +/// 一条要落地的覆盖条目。 +#[derive(Debug, Clone)] +pub struct PlanOverride { + /// 包内目录前缀（读包时拼 `/`）。 + 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, + /// 被同包另一条声明遮蔽时的事实（`None` = 本条目就是这条路径的最终胜者）。 + pub shadowed: Option, +} + +/// 一条要补全/下载的远端条目。 +#[derive(Debug, Clone)] +pub struct PlanRemote { + /// 原清单条目（摘要表 / downloads / env / project/file id 都在里面）。 + pub file: PackFile, + /// 已知的实例内相对路径（mrpack 有；CF 需要补全才有）。 + pub path: Option, + /// 来源。 + 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, + /// 实例绑定版本 id。 + pub version_id: String, + /// 不支持的 component（逐项）。 + pub rejected: Vec, + /// 注记。 + pub notes: Vec, + /// 覆盖条目（已按侧优先级排好、已剔除 `server-overrides`）。 + pub overrides: Vec, + /// 远端条目。 + pub remote: Vec, + /// `instance.cfg` 里受开关门控的内存上限（MB）。 + pub max_memory_mb: Option, +} + +impl ImportPlan { + /// 组计划。 + /// + /// # Errors + /// + /// 清单缺游戏版本、加载器条目缺版本号、MultiMC 的 `formatVersion != 1` 等"清单自身非法" + /// 的情形返回 [`ImportError`]（调用方据此整包回滚）。"某条文件缺地址"**不是**错误。 + pub fn build( + pack: &PackArchive, + format_id: &str, + manifest: PackManifest, + ) -> Result { + let mut notes: Vec = Vec::new(); + let mut rejected: Vec = 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 = Vec::new(); + let mut skipped_server_files = 0_usize; + for group in layer::ordered(&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), + shadowed: None, + }); + } + } + layer::resolve(&mut overrides, &mut notes); + 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 = 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, + }) + } +} + +/// 选一个加载器并翻译成 [`LoaderTarget`]。 +fn select_loader( + manifest: &PackManifest, + mc_version: &str, + format_id: &str, + notes: &mut Vec, + rejected: &mut Vec, +) -> Result, 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::>() + .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, +) -> Result, 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::().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/layer.rs b/crates/core/src/addon/import/plan/layer.rs new file mode 100644 index 0000000..885570a --- /dev/null +++ b/crates/core/src/addon/import/plan/layer.rs @@ -0,0 +1,208 @@ +//! 覆盖目录的**叠层顺序**与**同路径遮蔽**：导入计划里"逐文件"那一半的判据（纯计算，无 IO）。 +//! +//! 拆成单独一个文件有两个原因：①`plan.rs` 要守 400 行；②这一层的两条规则（先按侧排、 +//! 再按路径结算胜负）是导入器里唯一"我们自己定的确定性规则"，值得放在一处被单独读完。 + +use std::collections::HashMap; + +use super::super::report::{keys, FileSource, ImportIssue}; +use super::PlanOverride; +use crate::addon::pack::{PackManifest, PackOverrides, PackSide}; + +/// 「这条覆盖条目被同一份包里的另一条声明遮蔽」。 +/// +/// 为什么不是新的 `FileAction` 变体：`FileAction` / `ConflictReason` / `ConflictChoice` 三个 +/// 枚举被 `crates/presenter/src/host/addon/pack/convert.rs` **穷尽 match**（那个 crate 不在 +/// `addon` 的作用域里）。所以"遮蔽"这件事走 [`ImportIssue`] 的 note 通道，与 +/// `server-overrides/ 被跳过` 完全同一条通道。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Shadowed { + /// 胜出那条的来源侧。 + pub winner: FileSource, + /// 胜出那条的包内目录名（人读用，例如 `client-overrides`）。 + pub winner_dir: String, + /// 两条声明的字节是否完全相同（`true` = 遮蔽不丢内容，只是重复了一份）。 + pub same_bytes: bool, +} + +/// 覆盖目录按侧排序：`Both`（`overrides/`）先、`Client`（`client-overrides/`）后 = 后者胜。 +pub(super) fn ordered(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 +} + +/// 同一实例路径被本包多份声明命中时：**叠层顺序里最后一条胜**，其余标记为遮蔽并逐条注记。 +/// +/// # 这是"逐文件"而不是"整包一个策略"的那一步 +/// +/// research/18 §3.3 的 A 级结论：mrpack 的 `overrides/` 与 `client-overrides/` 之间， +/// **规范层面只有极少数固定路径有优先级**，其余按 zip 条目顺序落盘；HMCL 连顺序都相反。 +/// 上一版导入器对此的处理是"按侧排序后逐条写"——结果是对的，但**报告是错的**：同一路径 +/// 会出现两条 `Installed`，其中前一条的哈希根本没落地，也没人说得清谁遮蔽了谁。 +/// +/// 现在把这层算清楚，逐条给出两个事实： +/// +/// 1. **赢了的是哪一侧**（叠层顺序 = [`ordered`] 的 `Both → Client`，同组内按路径排序， +/// 所以与 zip 条目顺序无关——那是我们自己定死的确定性规则，不是规范）； +/// 2. **两份内容是否逐字节相同**（相同 = 重复声明，遮蔽不丢内容；不同 = 真的换了一份）。 +/// +/// 判据只看模型里的 `sha1`：M110 扫包时是**现算**的真实内容哈希；手工构造的模型可能撒谎， +/// 但那最多让 `same_bytes` 这句注记不准，**谁落地不受影响**（胜者永远按叠层顺序定）。 +pub(super) fn resolve(overrides: &mut [PlanOverride], notes: &mut Vec) { + let mut last: HashMap = HashMap::new(); + for (index, entry) in overrides.iter().enumerate() { + last.insert(entry.path.clone(), index); + } + for index in 0..overrides.len() { + let path = overrides[index].path.clone(); + let Some(&winner_index) = last.get(&path) else { + continue; + }; + if winner_index == index { + continue; + } + let winner_dir = overrides[winner_index].dir.clone(); + let loser_dir = overrides[index].dir.clone(); + let same_bytes = overrides[winner_index].sha1 == overrides[index].sha1; + let conclusion = if same_bytes { + "两份内容逐字节相同，只落地一次" + } else { + "两份内容不同，以这一条为准" + }; + notes.push( + ImportIssue::new( + keys::NOTE_OVERRIDE_SHADOWED, + format!( + "{loser_dir}/{path} 与 {winner_dir}/{path} 声明同一实例路径：叠层顺序 \ + overrides/ 在前、client-overrides/ 在后（Modrinth 官方客户端语义），\ + {conclusion}" + ), + ) + .with_path(path), + ); + overrides[index].shadowed = Some(Shadowed { + winner: overrides[winner_index].source, + winner_dir, + same_bytes, + }); + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn entry(dir: &str, path: &str, source: FileSource, sha1: &str) -> PlanOverride { + PlanOverride { + dir: dir.to_string(), + path: path.to_string(), + source, + sha1: sha1.to_string(), + size: 1, + disabled: false, + note: None, + shadowed: None, + } + } + + #[test] + fn the_later_layer_wins_and_the_earlier_one_is_shadowed() { + // 叠层顺序：overrides/（Both）在前、client-overrides/（Client）在后 ⇒ 后者胜。 + let mut overrides = vec![ + entry( + "overrides", + "config/dup.toml", + FileSource::Overrides, + "aaaa", + ), + entry( + "client-overrides", + "config/dup.toml", + FileSource::ClientOverrides, + "bbbb", + ), + ]; + let mut notes = Vec::new(); + resolve(&mut overrides, &mut notes); + + let shadowed = overrides[0].shadowed.as_ref().expect("前一条要被标记"); + assert_eq!(shadowed.winner, FileSource::ClientOverrides); + assert_eq!(shadowed.winner_dir, "client-overrides"); + assert!(!shadowed.same_bytes, "同路径不同哈希"); + assert!(overrides[1].shadowed.is_none(), "胜者不标遮蔽"); + assert_eq!(notes.len(), 1); + assert_eq!(notes[0].message_key, keys::NOTE_OVERRIDE_SHADOWED); + assert_eq!(notes[0].path.as_deref(), Some("config/dup.toml")); + let message = ¬es[0].message; + for expected in [ + "overrides/config/dup.toml", + "client-overrides/config/dup.toml", + "内容不同", + ] { + assert!(message.contains(expected), "缺 {expected}：{message}"); + } + } + + #[test] + fn identical_bytes_are_reported_as_same_bytes() { + let mut overrides = vec![ + entry( + "overrides", + "config/same.toml", + FileSource::Overrides, + "aaaa", + ), + entry( + "client-overrides", + "config/same.toml", + FileSource::ClientOverrides, + "aaaa", + ), + ]; + let mut notes = Vec::new(); + resolve(&mut overrides, &mut notes); + + assert!(overrides[0].shadowed.as_ref().expect("标记").same_bytes); + assert!( + notes[0].message.contains("逐字节相同"), + "内容一致要说清楚，别让人以为丢了东西：{}", + notes[0].message + ); + } + + #[test] + fn different_paths_with_the_same_bytes_are_never_shadowed() { + // 同哈希不同路径 = 两份文件，不是重复声明。按哈希去重会**静默丢一个文件**。 + let mut overrides = vec![ + entry("overrides", "mods/a.jar", FileSource::Overrides, "aaaa"), + entry("overrides", "mods/b.jar", FileSource::Overrides, "aaaa"), + ]; + let mut notes = Vec::new(); + resolve(&mut overrides, &mut notes); + + assert!(overrides.iter().all(|entry| entry.shadowed.is_none())); + assert!(notes.is_empty()); + } + + #[test] + fn the_same_path_twice_inside_one_group_is_shadowed_too() { + // 同侧重复（模型被合并 / 手造时才会出现）：照样只落地一次，且注记两份来自同一目录。 + let mut overrides = vec![ + entry("overrides", "mods/x.jar", FileSource::Overrides, "aaaa"), + entry("overrides", "mods/x.jar", FileSource::Overrides, "bbbb"), + ]; + let mut notes = Vec::new(); + resolve(&mut overrides, &mut notes); + + assert_eq!( + overrides[0].shadowed.as_ref().expect("标记").winner, + FileSource::Overrides + ); + assert_eq!(notes.len(), 1); + } +} 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..7e7e7e2 --- /dev/null +++ b/crates/core/src/addon/import/plan/paths.rs @@ -0,0 +1,132 @@ +//! 路径与版本号的小判据（纯函数）：`.disabled` / `.old` 后缀变体与注记、CF 类别目录、MC 版本前缀。 +//! +//! 拆出来是因为它们是**格式事实**而非管线逻辑：`.disabled` 只按路径后缀（tower 定案，不用 +//! `env.client=optional`）、`.old` 只识别与保留（不清不删）、CF 的 `classId` 认不出就不猜。 + +use super::super::report::{keys, ImportIssue}; + +/// 路径后缀变体（`.disabled` / `.old` 的四种组合）。 +/// +/// M224 收敛：类型本体只有 [`crate::addon::mods::suffix`] 一处，这里原样再导出，于是 +/// `paths::SuffixVariant` 与启停用的是**同一个类型**（零行为变化，调用点不用改）。 +pub use crate::addon::mods::SuffixVariant; + +/// 识别四种路径后缀变体。 +/// +/// 委派到唯一判据（见模块文档）；保留函数名与签名。 +#[must_use] +pub fn suffix_variant(path: &str) -> SuffixVariant { + crate::addon::mods::suffix_variant(path) +} + +/// 后缀注记（`.disabled` / `.old`）：进报告，告诉用户"这个名字我们是认得的"。 +#[must_use] +pub fn suffix_note(variant: SuffixVariant, path: &str) -> Option { + 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` 的坑）。 +/// +/// 只在"版本段以 `-` 开头"时剥——这是 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/prepare.rs b/crates/core/src/addon/import/prepare.rs new file mode 100644 index 0000000..fba827b --- /dev/null +++ b/crates/core/src/addon/import/prepare.rs @@ -0,0 +1,65 @@ +//! 导入管线的**准备段**：读包 → 组计划 → 抄进报告 → 写基线（一个字节都还没进目标目录）。 +//! +//! 从 [`super::pipeline`] 拆出来的是"碰盘之前"的那一段，行为逐字未变：编排文件（`pipeline.rs`） +//! 要装下取消的七个检查点与回滚收尾，把这一段移到同级模块是为了让它仍在一屏之内。 +//! +//! 这里的函数**都不查取消令牌**：整段落在"解析后一次检查"之前/之后的两侧，而 `open` 是 +//! 不可分割的（zip 目录 + 四检 + 限额一次扫完）——见 [`super::cancel`] 的逐段表。 + +use super::baseline::PackBaseline; +use super::error::ImportError; +use super::plan::ImportPlan; +use super::report::ImportReport; +use super::stage::Staging; +use super::ImportRequest; +use crate::addon::pack::{PackArchive, PackError, PackRegistry}; + +/// 开包 + 探测 + 组计划（任何失败都是 `Failed`）。 +/// +/// 预检（[`super::scan`]）走的是**同一段代码**：两边对"这包是什么、要装什么"必须完全一致， +/// 否则"预检说没冲突、导入说有冲突"这种事就会发生。 +pub(super) 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)) +} + +/// 把计划里的静态信息抄进报告。 +pub(super) 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()); +} + +/// 基线作为**最后一个暂存文件**写进去：它跟同一个事务一起提交 / 回滚。 +pub(super) 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('\\', "/") +} diff --git a/crates/core/src/addon/import/report.rs b/crates/core/src/addon/import/report.rs new file mode 100644 index 0000000..2d94141 --- /dev/null +++ b/crates/core/src/addon/import/report.rs @@ -0,0 +1,337 @@ +//! 导入结果：**三态 + 逐项原因**，给 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; + +/// 导入结果（三态 + 一档"用户取消"）。 +/// +/// 取消**单列一档、不是第四种失败**（M195）：它有自己的变体、自己的文案 key、自己的退出码， +/// 且 `ImportReport::error` 恒为 `None`。把两者并成一个错误变体，UI 就会把"用户自己点的" +/// 画成红的，脚本也会把"我改主意了"当成"装坏了"。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)] +#[serde(rename_all = "snake_case")] +pub enum ImportStatus { + /// 全部落地、无冲突。 + Success, + /// 有缺文件或有冲突（内容不完整，但实例可用）。 + Partial, + /// 致命失败，已整包回滚。 + Failed, + /// 用户主动取消：管线在检查点停下，目标目录与导入前一致（`error` 为 `None`）。 + Cancelled, +} + +impl ImportStatus { + /// 稳定字符串 id。 + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::Success => "success", + Self::Partial => "partial", + Self::Failed => "failed", + Self::Cancelled => "cancelled", + } + } + + /// 文案 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, + Self::Cancelled => keys::STATUS_CANCELLED, + } + } + + /// CLI 退出码：`0` / `3` / `1` / `130`（`2` 留给内部错误，`1` 与用法错误同码但 JSON 里可区分）。 + /// + /// `130` 是「被用户中断」的惯例码（`128 + SIGINT`）：**与失败不同码**，脚本不会把 + /// 「用户改主意」记成「装坏了」，也不会误判成成功。 + #[must_use] + pub const fn exit_code(self) -> i32 { + match self { + Self::Success => 0, + Self::Partial => 3, + Self::Failed => 1, + Self::Cancelled => 130, + } + } +} + +/// 导入阶段（进度回调按这个分组）。 +#[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, +} + +/// 进度回调。 +pub type ImportProgressSink = std::sync::Arc; + +/// 发一条进度事件（`sink` 为 `None` 时什么都不做）。 +/// +/// 放在这里是因为它是 [`ImportProgress`] 的唯一出口：编排、阶段实现、提交事务都走它， +/// 谁都不许自己拼一条进度事件。 +pub(crate) fn tell( + sink: &Option, + stage: ImportStage, + done: usize, + total: usize, + current: Option, +) { + if let Some(sink) = sink { + sink(&ImportProgress { + stage, + done, + total, + current, + }); + } +} + +/// 一次导入的完整结果。 +#[derive(Debug, Clone, Serialize)] +pub struct ImportReport { + /// 三态。 + pub status: ImportStatus, + /// 命中的格式 id（`curseforge` / `modrinth` / `multimc`）。 + pub format: Option, + /// 包名。 + pub pack_name: Option, + /// 包版本。 + pub pack_version: Option, + /// 游戏版本。 + pub game_version: Option, + /// 加载器安装计划输入（没有加载器时 `None` = 纯原版）。 + pub loader: Option, + /// 实例绑定的版本 id。 + pub version_id: Option, + /// 目标实例目录。 + pub target: PathBuf, + /// 落地的文件（含 `SkippedIdentical`）。 + pub files: Vec, + /// 冲突清单。 + pub conflicts: Vec, + /// 缺文件清单（容忍）。 + pub missing: Vec, + /// MultiMC 不支持的 component（逐项）。 + pub rejected_components: Vec, + /// 注记。 + pub warnings: Vec, + /// 致命错误（`status == Failed` 时必有）。 + pub error: Option, + /// 登记的实例。 + pub registered: Option, + /// 回滚结果（只有真的执行过回滚才有）。[`ImportReport::rolled_back`] 只在它**完整**时为真。 + pub rollback: Option, + /// `instance.cfg` 里受开关门控的内存上限（MB；仅 MultiMC / Prism 有）。 + pub max_memory_mb: Option, + /// 本次写入的字节数。 + 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; + } + + /// 取消收尾：状态落到 [`ImportStatus::Cancelled`]，并说准**目标目录现在的样子**。 + /// + /// 与 [`ImportReport::fail`] 是**两条路**（M195 的守门条款③）：取消不是失败，`error` 保持 + /// `None`，UI 不弹红、CLI 退出码 `130`。把两者并成一个错误变体，这一条就守不住。 + /// + /// `outcome` 是取消之前已经做过的回滚动作（落盘之前取消 ⇒ `attempted == 0`，即"没写过"）。 + /// 三档文案与失败路径**同形**：没写过 / 回滚干净 / 回滚没做完——回滚不完整时同样不许宣称 + /// "与导入前一致"。 + pub fn cancel(&mut self, outcome: RollbackOutcome) { + // 取消前"处理过"的条目一条都没进目标目录（暂存目录已删 / 已回滚）：留着它们会让 + // `installed()` / `bytes_written` 谎报"装了多少"，所以清空并把这笔账写进注记。 + let handled = self.files.len(); + self.files.clear(); + self.conflicts.clear(); + self.missing.clear(); + self.bytes_written = 0; + self.error = None; + self.status = ImportStatus::Cancelled; + + if outcome.attempted == 0 { + // 落盘之前就停了：目标目录一个字节都没动。 + self.rolled_back = true; + self.warnings.push(ImportIssue::new( + keys::NOTE_CANCELLED, + format!( + "已取消：目标目录未被写入（{}）；已处理的 {handled} 条文件未落地", + self.target.display() + ), + )); + return; + } + + if outcome.is_complete() { + self.rolled_back = true; + self.warnings.push(ImportIssue::new( + keys::NOTE_CANCELLED, + format!( + "已取消：已回滚 {} 项，目标目录恢复为导入前的样子（{}）", + outcome.attempted, + self.target.display() + ), + )); + } else { + // 回滚本身失败：与失败路径同一口径——不许在"可能没回干净"时宣称一致。 + self.rolled_back = false; + self.warnings.push(ImportIssue::new( + keys::NOTE_ROLLBACK_INCOMPLETE, + format!( + "取消时回滚有 {} 项未完成（目标目录可能与导入前不同）：{}", + outcome.failure_count(), + outcome.failed.join("；") + ), + )); + self.warnings.push(ImportIssue::new( + keys::NOTE_CANCELLED, + format!("已取消：已处理 {handled} 条文件、回滚未完整（详见 rollback.failed）"), + )); + } + self.rollback = Some(outcome); + } +} 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..80b5dff --- /dev/null +++ b/crates/core/src/addon/import/report/items.rs @@ -0,0 +1,272 @@ +//! 报告里的**条目类型**：一条文件、一条冲突、一条缺失、一个 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`] / [`super::super::ConflictDecisions`] 决定）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)] +#[serde(rename_all = "snake_case")] +pub enum ConflictChoice { + /// 保留用户侧（不写盘）。 + KeepUser, + /// 用包内内容覆盖（用户选了"覆盖"）。 + Overwrite, +} + +impl Default for ConflictChoice { + /// **缺省是保留**：没有决策时绝不覆盖用户已有文件（M160 的硬线，见 `import::decision`）。 + fn default() -> Self { + Self::KeepUser + } +} + +/// 一条冲突（"无法判定时给可选择的冲突清单"就是这张表）。 +#[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, + /// 磁盘现状的 SHA-1（文件不存在时 `None`）。 + pub disk_sha1: Option, +} + +/// 一个"搞不到"的文件（**容忍**，但必须逐条列出）。 +#[derive(Debug, Clone, Serialize)] +pub struct MissingFile { + /// 实例内相对路径（mrpack 有；CF 补全失败时没有）。 + pub path: Option, + /// 人读标识（CF 条目是 `projectID:fileID`，其余是路径）。 + pub display: String, + /// CF `projectID`。 + pub project_id: Option, + /// CF `fileID`。 + pub file_id: Option, + /// 为什么搞不到。 + 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, + /// 文案 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(&self, serializer: S) -> Result { + 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, + /// 字节数。 + pub bytes: u64, + /// 是否禁用态（路径后缀表达，不附加语义）。 + pub disabled: bool, + /// 处理方式。 + pub action: FileAction, + /// 可选注记（`.disabled` / `optional` 之类）。 + pub note: Option, +} + +/// 一条人读注记（带稳定 key）。 +#[derive(Debug, Clone, Serialize)] +pub struct ImportIssue { + /// 文案 key。 + pub message_key: &'static str, + /// 人读细节。 + pub message: String, + /// 相关实例内路径。 + pub path: Option, +} + +impl ImportIssue { + /// 构造。 + #[must_use] + pub fn new(message_key: &'static str, message: impl Into) -> Self { + Self { + message_key, + message: message.into(), + path: None, + } + } + + /// 挂一条路径。 + #[must_use] + pub fn with_path(mut self, path: impl Into) -> 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..0848773 --- /dev/null +++ b/crates/core/src/addon/import/report/keys.rs @@ -0,0 +1,120 @@ +//! 文案 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"; +/// 状态：**用户取消**（不是失败，`error` 为空）。 +pub const STATUS_CANCELLED: &str = "pack.import.status.cancelled"; + +/// 注记：`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"; +/// 注记：用户取消，管线在检查点停下（说明停在哪一步、已处理的条目未落地）。 +pub const NOTE_CANCELLED: &str = "pack.import.note.cancelled"; +/// 注记：同包另一条声明遮蔽了这个路径（说清谁赢、两份内容是否相同）。 +pub const NOTE_OVERRIDE_SHADOWED: &str = "pack.import.note.override_shadowed"; +/// 注记：这些远端条目预检判不了（补全前没有路径 / 有路径但缺 sha1 声明），无法预判冲突。 +pub const NOTE_REMOTE_PATH_UNKNOWN: &str = "pack.import.note.remote_path_unknown"; +/// 注记：这些远端条目按 sha512 从 Modrinth 补全了 sha1（补不出的另有计数）。 +pub const NOTE_REMOTE_COMPLETED: &str = "pack.import.note.remote_completed"; + +/// 缺失：调用方没给 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, + STATUS_CANCELLED, + 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, + NOTE_CANCELLED, + NOTE_OVERRIDE_SHADOWED, + NOTE_REMOTE_PATH_UNKNOWN, + NOTE_REMOTE_COMPLETED, + 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/scan.rs b/crates/core/src/addon/import/scan.rs new file mode 100644 index 0000000..de6a04e --- /dev/null +++ b/crates/core/src/addon/import/scan.rs @@ -0,0 +1,337 @@ +//! 导入**预检**（M160）：只读地算出「冲突清单」——**只列真正需要用户点头的文件**。 +//! +//! # 什么进清单，什么不进（口径只此一处） +//! +//! 一个路径进清单**当且仅当**：目标实例里同名路径是一个普通文件，且它的内容与包内**不同**。 +//! 等值判据是 **SHA-1**（包内那条来自 M110 读包时现算的摘要，磁盘那条现算）；体积只作展示， +//! 不参与判定——同一份内容不可能有两个哈希，而"体积相同"并不说明内容相同。 +//! +//! 不进清单的四种情形，每一种都有理由： +//! +//! | 情形 | 为什么不必打扰用户 | +//! |------|--------------------| +//! | 目标里没有这个文件 | 全新文件，装就是了 | +//! | 内容与包内一致 | 已经是最新，写盘是浪费 | +//! | 用户删过（基线有、磁盘没有） | 删是用户的决定，**不偷偷装回来**（`merge::decide` 的 `UserDeleted`） | +//! | 包内被同包另一条声明遮蔽（`shadowed`） | 它不落地，用户看不到它，问了也无从选 | +//! +//! # 叠层优先级不在这层重判 +//! +//! `client-overrides/` 胜 `overrides/`、`server-overrides/` 客户端不解压——这些**已由** +//! [`super::plan::ImportPlan::build`] 与 `plan::layer::resolve` 算定（一路径一行，胜者才在 +//! `overrides` 表里且 `shadowed.is_none()`）。本模块只按胜者取 `source`，从不自己再排一次。 +//! +//! # 远端条目的两种命运 +//! +//! mrpack 的 `files[]` 自带 `path` + `hashes.sha1`，所以能在这里判；判的是"**声明的**摘要 vs +//! 磁盘"，与导入时"下载下来再校验"是同一份期望值。CurseForge 的 `files[]` 只有 +//! `projectID/fileID`，补全前**没有路径**，无从判起 ⇒ 不猜、不进清单，只把条数记进 +//! [`ImportScan::unknown_remote`]（界面据此说"还有 N 条补全后才能知道会不会撞车"）。计数与 +//! 文案同一口径：**判不了**的两种来路（补全前没有路径 / 有路径但缺 `hashes.sha1`）都算。 +//! +//! # 便宜在哪、贵在哪 +//! +//! 预检不读包内字节（摘要来自 M110 的读包结果），但要给每条冲突填"目标现有体积与哈希"， +//! 所以**磁盘上那些同名文件要真读一遍**。于是 `scan` + `import` 会把它们读两次——这是本轮 +//! 的已知代价（要省就得让导入直接吃预检的判定结果，那是另一件事，报告里登记）。 + +use std::collections::BTreeMap; +use std::path::{Path, PathBuf}; + +use super::baseline::PackBaseline; +use super::decision::ConflictDecisions; +use super::error::ImportError; +use super::merge; +use super::pipeline::load_baseline; +use super::plan::ImportPlan; +use super::prepare::probe_and_plan; +use super::report::{keys, ConflictReason, FileSource, ImportIssue, LoaderTarget}; +use super::ImportRequest; +use crate::download::verify; +use crate::download::HashAlgo; + +/// 一条**要用户点头**的冲突（目标里已有同名文件且内容不同）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ImportConflict { + /// 实例内相对路径。 + pub path: String, + /// 来源（包内 `overrides/` / `client-overrides/` / mrpack 或 CF 的 `files[]`）。 + pub source: FileSource, + /// 成因（`PreExisting` = 没有基线可判；`UserModified` = 基线里记过、用户改过）。 + pub reason: ConflictReason, + /// 包内那条是不是禁用态（`.disabled` 后缀原样保留）。 + pub disabled: bool, + /// 包内声明的 SHA-1。 + pub pack_sha1: String, + /// 包内声明的字节数。 + pub pack_size: u64, + /// 目标现有文件的 SHA-1。 + pub disk_sha1: String, + /// 目标现有文件的字节数。 + pub disk_size: u64, + /// 上次导入写下的 SHA-1（没有基线时 `None`）。 + pub base_sha1: Option, +} + +impl ImportConflict { + /// 覆盖它会丢掉多少字节（界面上"覆盖会丢掉 12.4 MB"就是它）。 + #[must_use] + pub const fn lost_bytes(&self) -> u64 { + self.disk_size + } +} + +/// 一次预检的结果。 +/// +/// `error` 为 `Some` 时其余字段是"没算出来"：探测/开包/组计划失败与导入管线同一条口径 +/// （同一个 [`PackError`] → [`ImportError`] 的映射），不去新造一套。 +#[derive(Debug, Clone)] +pub struct ImportScan { + /// 目标实例目录。 + pub target: PathBuf, + /// 命中的格式 id。 + pub format: Option, + /// 包名。 + pub pack_name: Option, + /// 包版本。 + pub pack_version: Option, + /// 游戏版本。 + pub game_version: Option, + /// 加载器计划输入（`None` = 纯原版）。 + pub loader: Option, + /// 冲突清单（按路径排序）。 + pub conflicts: Vec, + /// 预检阶段**判不了**的远端条目数。 + /// + /// 判不了有两种来路，计数把两者都算上（口径与注记文案一致，复审 r1 P3-4）： + /// ①CurseForge `files[]` 补全前**没有路径**（常态）；②极少数 mrpack 条目**有路径但缺 + /// `hashes.sha1`**，没有声明摘要就没法与磁盘现状比对。 + pub unknown_remote: usize, + /// 注记（`.disabled` / 可选条目 / 基线口径 / 被遮蔽的条目……与导入报告同源）。 + pub notes: Vec, + /// 开包或组计划失败（`Failed` 口径，目标目录一个字节都没动）。 + pub error: Option, +} + +impl ImportScan { + fn empty(target: PathBuf) -> Self { + Self { + target, + format: None, + pack_name: None, + pack_version: None, + game_version: None, + loader: None, + conflicts: Vec::new(), + unknown_remote: 0, + notes: Vec::new(), + error: None, + } + } + + /// 预检成功了吗（`false` = 看 [`Self::error`]）。 + #[must_use] + pub const fn is_ok(&self) -> bool { + self.error.is_none() + } + + /// 有没有需要用户点头的项（`false` = 可以直接导入，不必打扰用户）。 + #[must_use] + pub fn needs_decision(&self) -> bool { + !self.conflicts.is_empty() + } + + /// 「全部保留」的决策（= 缺省档，不覆盖任何用户文件）。 + #[must_use] + pub fn keep_all(&self) -> ConflictDecisions { + ConflictDecisions::keep_all() + } + + /// 「全部覆盖」的决策（用户显式要求"整合包说了算"）。 + #[must_use] + pub fn overwrite_all(&self) -> ConflictDecisions { + ConflictDecisions::overwrite_all() + } + + /// 覆盖会丢掉的字节总量（界面上的计数摘要）。 + #[must_use] + pub fn lost_bytes(&self) -> u64 { + self.conflicts + .iter() + .map(ImportConflict::lost_bytes) + .fold(0, u64::saturating_add) + } + + /// 包内那些条目声明了多大（= 覆盖后会占用的字节数）。 + #[must_use] + pub fn incoming_bytes(&self) -> u64 { + self.conflicts + .iter() + .map(|conflict| conflict.pack_size) + .fold(0, u64::saturating_add) + } +} + +/// 跑一次预检：**只读**（不建目录、不写暂存、不改基线、**不联网**）。 +#[must_use] +pub fn scan_pack(request: &ImportRequest<'_>) -> ImportScan { + let mut scan = ImportScan::empty(request.target.to_path_buf()); + let plan = match probe_and_plan(request) { + Ok((_, plan)) => plan, + Err(error) => { + scan.error = Some(error); + return scan; + } + }; + fill(request, &plan, &mut scan); + scan +} + +/// 跑一次预检，**先补全再判**（M162）：缺 `hashes.sha1` 的 mrpack 条目按 `sha512` 反查 Modrinth。 +/// +/// 补出来的条目与清单里本来就带 `sha1` 的条目走**同一个** [`judge`]（判据一行没改）； +/// 补不出的仍进 [`ImportScan::unknown_remote`] 并留同一条注记——计数口径不变，只是「能判的变多了」。 +/// +/// 没有挂 fetcher（离线导入）时等价于 [`scan_pack`]：不发任何请求，计数照旧。 +#[must_use] +pub async fn scan_pack_online(request: &ImportRequest<'_>) -> ImportScan { + let mut scan = ImportScan::empty(request.target.to_path_buf()); + let mut plan = match probe_and_plan(request) { + Ok((_, plan)) => plan, + Err(error) => { + scan.error = Some(error); + return scan; + } + }; + let completion = super::complete::complete(request, &mut plan).await; + fill(request, &plan, &mut scan); + if let Some(note) = completion.note("预检前") { + scan.notes.push(note); + } + scan +} + +/// 预检的主体：把「已组好的计划」判成冲突清单（两个入口共用，判据只此一处）。 +fn fill(request: &ImportRequest<'_>, plan: &ImportPlan, scan: &mut ImportScan) { + let (baseline, warnings) = load_baseline(request.target, plan); + scan.notes = warnings; + scan.format = Some(plan.format.clone()); + scan.pack_name = Some(plan.manifest.name.clone()); + scan.pack_version = plan.manifest.version.clone(); + scan.game_version = Some(plan.mc_version.clone()); + scan.loader = plan.loader.clone(); + + // 一路径一行：同一路径被覆盖条目与远端条目同时声明时，只留一条（决策是按路径给的）。 + let mut seen: BTreeMap = BTreeMap::new(); + for entry in plan + .overrides + .iter() + .filter(|entry| entry.shadowed.is_none()) + { + let Some(conflict) = judge( + &entry.path, + entry.source, + &entry.sha1, + entry.size, + entry.disabled, + &baseline, + request.target, + ) else { + continue; + }; + seen.insert(entry.path.clone(), ()); + scan.conflicts.push(conflict); + } + for entry in &plan.remote { + let (Some(path), Some(declared)) = (entry.path.as_deref(), entry.file.sha1()) else { + // 两种来路都算「判不了」：没有路径（CF 待补全）或没有声明摘要（缺 `hashes.sha1`）。 + scan.unknown_remote += 1; + continue; + }; + if seen.contains_key(path) { + continue; + } + let Some(conflict) = judge( + path, + entry.source, + declared, + entry.file.size.unwrap_or(0), + entry.disabled, + &baseline, + request.target, + ) else { + continue; + }; + seen.insert(path.to_string(), ()); + scan.conflicts.push(conflict); + } + if scan.unknown_remote > 0 { + scan.notes.push(ImportIssue::new( + keys::NOTE_REMOTE_PATH_UNKNOWN, + format!( + "有 {} 条远端条目预检判不了：CurseForge files[] 补全前没有路径，个别条目有路径但没有 sha1 声明；这些条目会不会撞上已有文件只能等补全/下载后才知道，导入时仍按「缺省保留」处置", + scan.unknown_remote + ), + )); + } + scan.conflicts + .sort_by(|left, right| left.path.cmp(&right.path)); +} + +/// 判一个路径：`Some` = 要用户点头的冲突。 +/// +/// # 「内容相同」的判据**只此一处**：[`merge::decide`] +/// +/// 这里**故意不再写** `if disk.sha1 == pack_sha1 { return None }`（复审 r1 P3-2 抓到的重复判据）： +/// 那种早退与 `merge::decide` 的 `SkipIdentical` 分支是同一件事的两次实现，改一处漏一处的后果 +/// 就是"预检说没冲突、导入却判 SkipIdentical"或者反过来。 +/// +/// 现在只有一条链路：`decide` 给出 `MergeDecision`，**没有 `reason` 就不是冲突** +/// （`SkipIdentical` 与 `Install` 都是 `reason == None`），`?` 把它一步交代掉。 +/// 于是"内容相同 ⇒ 不进清单"这条结论的源头是 `merge.rs` 的那张表——与导入用的是同一张。 +fn judge( + path: &str, + source: FileSource, + pack_sha1: &str, + pack_size: u64, + disabled: bool, + baseline: &PackBaseline, + target: &Path, +) -> Option { + let disk = disk_state(&target.join(path))?; + // 包内那条的摘要来自 M110 读包（`override_files` 边读边算），与导入时现算的是同一份字节。 + let base_sha1 = baseline.sha1(path).map(str::to_string); + // 唯一判据：`reason` 为 `None` 就是"不是冲突"（内容相同 → `SkipIdentical`； + // 磁盘上没有 → `Install`，而那一条 `disk_state` 已经先返回 `None` 了）。 + let decision = merge::decide(pack_sha1, base_sha1.as_deref(), Some(&disk.sha1)); + let reason = decision.reason?; + Some(ImportConflict { + path: path.to_string(), + source, + reason, + disabled, + pack_sha1: pack_sha1.to_string(), + pack_size, + disk_sha1: disk.sha1, + disk_size: disk.size, + base_sha1, + }) +} + +/// 磁盘现状：`None` = 那里没有普通文件（不存在或是目录）。 +struct DiskState { + size: u64, + sha1: String, +} + +fn disk_state(path: &Path) -> Option { + let metadata = std::fs::metadata(path).ok()?; + if !metadata.is_file() { + return None; + } + let sha1 = verify::digest_file(path, HashAlgo::Sha1).ok()?; + Some(DiskState { + size: metadata.len(), + sha1, + }) +} diff --git a/crates/core/src/addon/import/stage.rs b/crates/core/src/addon/import/stage.rs new file mode 100644 index 0000000..a5899a5 --- /dev/null +++ b/crates/core/src/addon/import/stage.rs @@ -0,0 +1,387 @@ +//! 落地事务：**临时目录 + rename**，合并态用 journal 回滚（回滚细节在 [`commit`]）。 +//! +//! # 两种起点，两条事务路径 +//! +//! | 起点 | 做法 | 失败后的样子 | +//! |------|------|--------------| +//! | 目标目录不存在 / 是空目录（全新导入） | 在**同卷兄弟目录**里把整个实例建好，最后一次 `rename` 到位 | 目标目录**从未出现**（rename 是原子的） | +//! | 目标目录已有内容（升级 / 重导） | 逐文件 `rename` 进目标；被替换的旧文件先改名成 `.ullbak-` 当备份 | journal 逆序回滚：新文件删掉、旧备份改回原名 | +//! +//! 为什么全新导入不逐文件搬：逐文件搬意味着"搬到一半失败"会留下一个**看起来存在**的 +//! 半个实例，而 `rename` 一个目录是单步原子操作——失败就只有"没有"这一种结果。 +//! +//! # 取消落在这层怎么办（M195） +//! +//! | 起点 | 取消点 | 收场 | +//! |------|--------|------| +//! | 全新导入 | **只在 `rename` 之前** | 删暂存目录，目标目录从未出现 | +//! | 合并态 | 每条搬动之前 | journal **逆序**撤回（新文件删掉、旧备份改回原名） | +//! +//! 合并态逐文件报进度（`ImportStage::Commit`）：既是界面该有的动静，也是取消能落下的地方。 +//! +//! # 两道路径检查都在这层再走一遍 +//! +//! 第一道是 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, CommitStop, 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::cancel::{ImportCancel, Stopped}; +use super::error::ImportError; +use super::report::tell; +use super::report::{ImportProgressSink, ImportStage}; +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 { + 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 { + 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 { + 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`** 的守卫（析构即回滚）。 + /// + /// `cancel` 是取消令牌，`progress` 是进度回调（合并态**逐文件**报一条：几千文件的合并本来 + /// 就该看得见动静，而"取消"也正需要文件之间的落点）。 + /// + /// # Errors + /// + /// - [`CommitStop::Cancelled`]：取消落在提交前 / 合并中途。**回滚已经在这条路径上做过**， + /// 结果一并返回（调用方把它写进报告的 `rollback` 机器位）； + /// - [`CommitStop::Failed`]：`rename` 失败、合并态逐文件搬动失败。回滚同样已经做过，其结果 + /// 随错误返回（[`CommitFailure::rollback`]）：调用方不许假设"失败 = 已回滚干净"。 + /// + /// 全新导入只有一次 `rename`：那是单步原子操作，**取消点只在它之前**——之后不存在"半个 + /// 实例"这种中间态，也就没有"取消"这一说。 + pub fn commit( + self, + cancel: &ImportCancel, + progress: &Option, + ) -> Result { + match self.mode { + Mode::Fresh => { + if cancel.is_cancelled() { + // 还没 rename：目标目录一个字节都没动，删掉暂存目录就是零残留。 + self.abort_inner(); + return Err(CommitStop::Cancelled(RollbackOutcome::default())); + } + match std::fs::rename(&self.temp, &self.target) { + Ok(()) => Ok(CommitGuard::fresh(self.target.clone(), self.temp.clone())), + Err(error) => { + self.abort_inner(); + Err(CommitStop::Failed(CommitFailure::io( + format!( + "把 {} 改名成 {} 失败：{error}", + self.temp.display(), + self.target.display() + ), + RollbackOutcome::default(), + ))) + } + } + } + Mode::Merge => { + let mut applied: Vec = Vec::new(); + match self.apply_merge(&mut applied, cancel, progress) { + Ok(()) => Ok(CommitGuard::merge( + self.target.clone(), + self.temp.clone(), + applied, + )), + Err(Stopped::Cancelled) => { + let rollback = rollback_merge(&mut applied); + self.abort_inner(); + Err(CommitStop::Cancelled(rollback)) + } + Err(Stopped::Failed(error)) => { + let rollback = rollback_merge(&mut applied); + self.abort_inner(); + Err(CommitStop::Failed(CommitFailure::new(error, rollback))) + } + } + } + } + } + + /// 删掉暂存目录里的**下载引擎中间产物**（续传 part 与 meta），返回删掉的个数。 + /// + /// 为什么必须在提交前删：引擎在下载失败时**故意**保留 `.ullpart--` + /// 与 `.ullmeta.json` 供下次续传（`core::download::atomic` 的设计）。这些文件躺在 + /// 暂存目录里，提交阶段会跟内容一起搬进实例——实例里冒出 `.ullpart-…` 既不是整合包内容， + /// 又会被下次导入的基线/冲突判定当成"用户文件"，从此谁也说不清。 + /// + /// 冲突口径：整合包里真有一个叫 `x.ullpart` 的文件几乎不可能；真出现时以"不入实例"为准。 + /// + /// # Errors + /// + /// 遍历或删除失败返回 `pack_io`。 + pub fn purge_engine_artifacts(&self) -> Result { + let mut files: Vec = 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) + } + + /// 合并态：把临时目录里的文件逐个搬进目标目录（每个都带备份）。 + /// + /// **逐文件取消点**：每条搬动之前查一次令牌，已取消 ⇒ `Err(Stopped::Cancelled)`，调用方 + /// 按 journal 逆序回滚（新文件删掉、旧备份改回原名）。 + fn apply_merge( + &self, + applied: &mut Vec, + cancel: &ImportCancel, + progress: &Option, + ) -> Result<(), Stopped> { + let mut staged: Vec = Vec::new(); + collect_files(&self.temp, &mut staged)?; + staged.sort(); + let total = staged.len(); + for (index, source) in staged.into_iter().enumerate() { + cancel.stopped()?; + let relative = source + .strip_prefix(&self.temp) + .map_err(|_| io_error(format!("暂存路径不在临时目录里：{}", source.display())))?; + let relative_text = relative.to_string_lossy().replace('\\', "/"); + tell( + progress, + ImportStage::Commit, + index, + total, + Some(relative_text.clone()), + ); + // 搬动前再规整一次（第三道，防"临时目录里被塞了奇怪的名字"）。 + 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) -> 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) -> 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..690cd53 --- /dev/null +++ b/crates/core/src/addon/import/stage/commit.rs @@ -0,0 +1,302 @@ +//! 提交守卫、回滚与**回滚本身失败的记账**：`Drop` 即回滚，除非显式 `finish`。 +//! +//! 靠调用方在每个错误分支手动清理，早晚会漏一条——所以把"回滚"绑在析构上：任何提前 +//! `return`、`?` 冒泡、panic 展开都不会留下半个实例。 +//! +//! 回滚分两种： +//! +//! - **全新导入**：目标目录整个是本事务建的 ⇒ 删干净就是零残留； +//! - **合并态**：按 journal **逆序**撤回——新文件删掉、被替换的旧文件从 `.ullbak-` 改回原名。 +//! +//! # 回滚也可能失败（复审 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, +} + +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, + /// 新文件是否已经搬到位。 + pub(super) moved: bool, +} + +/// 提交守卫：**析构即回滚**，除非显式 [`CommitGuard::finish`]。 +#[derive(Debug)] +pub struct CommitGuard { + inner: Option, +} + +#[derive(Debug)] +struct Inner { + target: PathBuf, + temp: PathBuf, + /// 本次是否**新建**了目标目录（全新导入）。 + created_target: bool, + applied: Vec, + 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) -> 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 +} + +/// 备份路径：`.ullbak-`。 +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) +} + +/// 提交阶段的两条停止路线（M195）：**取消不是失败**，所以不共用 [`CommitFailure`]。 +/// +/// 两条路都**已经把回滚做过**（全新导入是 `abort`，合并态是 journal 逆序撤回）： +/// 调用方拿到它们只管写报告，不必再自己清一遍。 +#[derive(Debug)] +pub enum CommitStop { + /// 用户取消（回滚结果一并交回，可能不完整）。 + Cancelled(RollbackOutcome), + /// 真失败（回滚结果连同错误一起交回）。 + Failed(CommitFailure), +} + +/// 一次**失败的回滚**（提交阶段失败时连同错误一起交回调用方）。 +/// +/// `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, 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, 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..7772e68 --- /dev/null +++ b/crates/core/src/addon/loader/fabric.rs @@ -0,0 +1,259 @@ +//! 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//.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 根地址（按加载器；非 fabric 系给空串，调用方已按 [`LoaderKind::is_fabric_family`] 分流）。 +#[must_use] +pub fn meta_base(kind: LoaderKind) -> &'static str { + match kind { + LoaderKind::Fabric => FABRIC_META, + LoaderKind::Quilt => QUILT_META, + // Forge / NeoForge 走 maven，LiteLoader 走官方版本表——都不能回落到 fabric meta。 + LoaderKind::NeoForge | LoaderKind::Forge | LoaderKind::LiteLoader => "", + } +} + +/// 该原版版本可用的加载器版本列表地址。 +#[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, +} + +/// 解析版本列表（最新的排在前，与官方顺序一致——**不重排**）。 +/// +/// # Errors +/// +/// JSON 非法、或列表形状完全不符（顶层不是数组 / 一条都认不出）时返回 metadata 错误。 +pub fn parse_loader_list(kind: LoaderKind, json: &str) -> Result, LoaderError> { + let rows: Vec = serde_json::from_str(json).map_err(|error| { + LoaderError::metadata(format!("{} 版本列表解析失败：{error}", kind.label())) + })?; + let entries: Vec = 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 归一化成 `--` 的 loader 版本 JSON。 +/// +/// # Errors +/// +/// profile 不是合法版本 JSON、缺主类时返回 metadata 错误。 +pub fn build_release( + kind: LoaderKind, + mc_version: &str, + loader_version: &str, + profile_json: &str, +) -> Result { + 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(), + parent_version_id: 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"的实例。 +/// +/// 只有 fabric 系会走到这里（调用方 [`build_release`] 的入口已按 +/// [`LoaderKind::is_fabric_family`] 分流）；这里仍然**穷尽 match**，因为过去那对 `_ =>` +/// 会在新加一支加载器时把它静默当成 `fabric-loader` 补进库表。 +fn ensure_loader_library( + kind: LoaderKind, + loader_version: &str, + libraries: &mut Vec, + warnings: &mut Vec, +) { + let (group, artifact, maven_base) = match kind { + LoaderKind::Fabric => ( + "net.fabricmc", + "fabric-loader", + "https://maven.fabricmc.net/", + ), + LoaderKind::Quilt => ( + "org.quiltmc", + "quilt-loader", + "https://maven.quiltmc.org/repository/release/", + ), + LoaderKind::NeoForge | LoaderKind::Forge | LoaderKind::LiteLoader => return, + }; + let present = libraries.iter().any(|library| { + library + .coordinate() + .is_ok_and(|coordinate| coordinate.group == group && coordinate.artifact == artifact) + }); + if present { + return; + } + 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..76b7ea1 --- /dev/null +++ b/crates/core/src/addon/loader/forge.rs @@ -0,0 +1,281 @@ +//! 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, +} + +/// installer 里的 `install_profile.json`（只解析我们需要的键，其余忽略）。 +#[derive(Debug, Clone, Default, Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct InstallProfile { + /// 协议代号（`1` = processor 时代）。 + #[serde(default)] + pub spec: Option, + /// 组件名（`forge` / `NeoForge`）。 + #[serde(default)] + pub profile: Option, + /// installer 自己的版本串（`1.20.1-forge-47.2.0`）。 + #[serde(default)] + pub version: Option, + /// 目标原版版本。 + #[serde(default)] + pub minecraft: Option, + /// 内嵌版本 JSON 在 installer 里的路径（通常是 `/version.json`）。 + #[serde(default, rename = "json")] + pub version_json_path: Option, + /// universal jar 的 maven 坐标（`net.minecraftforge:forge:…`，spec 0 才有）。 + #[serde(default)] + pub path: Option, + /// processor 列表。 + #[serde(default)] + pub processors: Vec, + /// processor 的变量表（`{MAPPINGS}` / `{MC_SLIM}` 之类占位的数据源）。 + #[serde(default)] + pub data: BTreeMap, + /// processor / universal jar 依赖（**不是**启动 classpath，别合并）。 + #[serde(default)] + pub libraries: Vec, + /// 老协议：内嵌 jar 解包信息。 + #[serde(default)] + pub install: Option, + /// 老协议：内联的版本 JSON 片段。 + #[serde(default, rename = "versionInfo")] + pub version_info: Option, +} + +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 { + 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 ` 的原版版本配套")); + } + } + 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(), + parent_version_id: 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-.jar`（无 classifier），但官方 maven 只托管 +/// `forge--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/liteloader.rs b/crates/core/src/addon/loader/liteloader.rs new file mode 100644 index 0000000..b29b6fc --- /dev/null +++ b/crates/core/src/addon/loader/liteloader.rs @@ -0,0 +1,229 @@ +//! LiteLoader：官方 `versions.json` → **从零合成**一份 launchwrapper 版本 JSON。 +//! +//! 依据（A 级：官方数据 + 官方构建脚本，不查二手转述）： +//! - 数据源 `https://dl.liteloader.com/versions/versions.json`（2026-11 实测 200 / 49 KB， +//! 16 个原版版本）； +//! - HMCL 的同类实现只做一件事（`HMCLCore/.../liteloader/LiteLoaderInstallTask.java`）： +//! `mainClass = launchwrapper` + `--tweakClass ` + 「记录自带库 + 本体 jar」， +//! **不跑任何外部进程**；本模块按同样的协议独立实现，没有抄它的代码。 +//! +//! # 四条与上游形状有关的硬事实（都实测过，别按直觉改） +//! +//! 1. **分支键是 md5，不是版本号**：`artefacts."com.mumfrey:liteloader"` 下的键是 md5， +//! 真正的版本号在记录的 `version` 字段（`1.7.10_04`）。按 `version` 去重（同一版本会挂 +//! 两个 md5 键），`latest` 分支要跳过。 +//! 2. **目录名是原版版本，不是 loader 版本**：release 直链形如 +//! `/com/mumfrey/liteloader/1.7.10/liteloader-1.7.10_04.jar`（`1.7.10` 是原版）。 +//! 3. **1.12.2 这类版本只有 `snapshots` 分支**（上游 16 个版本里 8 个如此，含最常用的 1.12.2）。 +//! 记录的 `file`（`liteloader-1.12.2-SNAPSHOT.jar`）**下不动**，仓库里只有带时间戳的 +//! `liteloader-1.12.2---release.jar`；要拼出直链必须再读一次 +//! `maven-metadata.xml`（`` + ``）。见 [`snapshot_artifact_url`]。 +//! 4. **分支级 `libraries` 不是要装的库**：那是 ForgeGradle 开发环境用的（1.12.2 的 +//! `snapshots.libraries` 里挂着 `org.spongepowered:mixin`）。要进游戏 classpath 的是 +//! **记录级** `libraries`（`launchwrapper` + `asm-all`），与 HMCL 的取法一致。 +//! +//! # 库基址为什么按 group 分流 +//! +//! 记录里的库大多不写 `url`，上游默认（Mojang 库仓）**实测 404**：`org.ow2.asm:asm-all:5.2` +//! 在 `libraries.minecraft.net` 上不存在（5.0.3 存在），而 `net.minecraft:launchwrapper:*` +//! 只在 Mojang 库仓有（Central / Forge maven 都 404）。所以 `net.minecraft` 走 Mojang 默认基址、 +//! 其余走 Maven Central（实测 206）。这条分流有单测钉住，别把两侧弄反。 + +use std::collections::BTreeMap; + +use super::plan::{LoaderRelease, LoaderSupport}; +use super::{LoaderError, LoaderKind}; +use crate::game::arguments::{Argument, Arguments}; +use crate::game::library::{Library, LibraryDownloads}; +use crate::game::manifest::{DownloadInfo, VersionJson}; +use crate::game::version::ReleaseType; + +/// 官方版本表。 +pub const VERSION_LIST_URL: &str = "https://dl.liteloader.com/versions/versions.json"; + +/// 本体 jar 与 release 分支的仓库根：**直连官方**——`bmclapi-liteloader` 改写规则已 +/// `enabled: false`（镜像侧实测 404，关闭依据见 `download/mirrors.json`）。库走 [`CENTRAL_REPO`]。 +pub const DEFAULT_REPO: &str = "https://dl.liteloader.com/versions/"; + +/// 非 Mojang 库的基址：Mojang 库仓里没有 `asm-all:5.2`（实测 404），Central 有（实测 206）。 +pub const CENTRAL_REPO: &str = "https://repo1.maven.org/maven2/"; + +/// 快照分支的仓库根——**固定这一个**，不跟着 `repo.url` 走。 +/// +/// 上游每个原版版本的 `repo.url` 有两种形态（`…/versions/` 与 `…/repo/`），而**快照只发布在 +/// snapshots 仓**：1.10.2 的 `repo.url` 是 `http://dl.liteloader.com/repo/`，按它拼 +/// `…/repo/com/mumfrey/liteloader/1.10.2-SNAPSHOT/maven-metadata.xml` 实测会 302 到 +/// `…/repositories/liteloader/…` 再 404；而 +/// `https://repo.mumfrey.com/content/repositories/snapshots/com/mumfrey/liteloader/1.10.2-SNAPSHOT/maven-metadata.xml` +/// 是 200。HMCL 的构建脚本同样把这个快照仓**写死**（`UpdateLiteLoaderVersionList.SNAPSHOT_FILE`， +/// 注释还引了它自己的 issue #3147）。1.12.2 的 `repo.url` 恰好就是这条路径，所以只测 1.12.2 +/// 看不出这个问题——单测专门钉了 1.10.2。 +pub const SNAPSHOT_REPO: &str = "https://repo.mumfrey.com/content/repositories/snapshots/"; + +/// launchwrapper 主类（LiteLoader 靠它做 tweak 注入）。 +pub const LAUNCHWRAPPER_MAIN: &str = "net.minecraft.launchwrapper.Launch"; + +/// 记录没带 launchwrapper 时的兜底版本（1.12.2 的记录带的是 1.12）。 +const LAUNCHWRAPPER_FALLBACK: &str = "1.12"; + +/// 本体库坐标的 group / artifact。 +const LOADER_GROUP: &str = "com.mumfrey"; +/// 本体库坐标的 artifact 名。 +const LOADER_ARTIFACT: &str = "liteloader"; + +mod versions; + +pub use versions::{parse_versions, snapshot_artifact_url}; + +/// 一条可安装的 LiteLoader 版本（已归一化，不含 `latest` 别名分支）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct LiteLoaderEntry { + /// 版本号（`1.7.10_04` / `1.12.2-SNAPSHOT`） + pub version: String, + /// 记录所属的原版版本（拼目录与文件名用） + pub mc_version: String, + /// 是否快照分支（只有快照时要再读 maven-metadata 才拼得出直链） + pub snapshot: bool, + /// tweak 类（`com.mumfrey.liteloader.launch.LiteLoaderTweaker`） + pub tweak_class: String, + /// 记录级库（**不含**本体 jar，本体由 [`build_release`] 补） + pub libraries: Vec, + /// release 分支的直链（快照分支为 `None`） + pub url: Option, + /// 快照分支的 maven 目录（`…/com/mumfrey/liteloader/1.12.2-SNAPSHOT/`） + pub snapshot_dir: Option, +} + +/// 默认版本：优先非快照（稳定），没有则取最新的那条。 +#[must_use] +pub fn default_entry(entries: &[LiteLoaderEntry]) -> Option<&LiteLoaderEntry> { + entries + .iter() + .find(|entry| !entry.snapshot) + .or_else(|| entries.first()) +} + +/// 按版本号找一条（大小写不敏感）。 +#[must_use] +pub fn find_entry<'a>( + entries: &'a [LiteLoaderEntry], + version: &str, +) -> Option<&'a LiteLoaderEntry> { + entries + .iter() + .find(|entry| entry.version.eq_ignore_ascii_case(version.trim())) +} + +/// 合成 loader 版本 JSON（**纯函数**：直链由调用方给，快照的直链要先去查 maven-metadata）。 +/// +/// 拼出来的清单只有四件事：主类 = launchwrapper、`--tweakClass` 进 `arguments.game`、 +/// 库 = 记录库 + 本体 jar、`inheritsFrom` = 父版本（缺省原版）。 +/// +/// **`arguments.game` 而不是 `minecraftArguments`**：继承合并里 `minecraftArguments` 是 +/// **子覆盖父**（[`crate::game::inherit::merge`]），写它会把父链（Forge 1.12.2 的 +/// `--tweakClass FMLTweaker`）整串顶掉，Forge 当场不加载；`arguments.game` 才是父在前、子在后 +/// **追加**，且启动时排在 legacy 参数之后（[`crate::launch::game_args`] 第 24/25 项）。 +/// +/// # Errors +/// +/// 记录缺 `tweakClass`、或没有本体直链时返回 metadata 错误（没有它这份清单装上也起不来）。 +pub fn build_release( + mc_version: &str, + parent_version_id: &str, + entry: &LiteLoaderEntry, + artifact_url: &str, +) -> Result { + if entry.tweak_class.trim().is_empty() { + return Err(LoaderError::metadata(format!( + "LiteLoader {} 的记录没有 tweakClass：这份清单装上也起不来", + entry.version + )) + .with_hint("换一个 LiteLoader 版本，或核对 dl.liteloader.com 的版本表")); + } + if artifact_url.trim().is_empty() { + return Err(LoaderError::metadata(format!( + "LiteLoader {} 没有可下载的本体 jar 地址", + entry.version + ))); + } + + let version_id = LoaderKind::LiteLoader.version_id(mc_version, &entry.version); + let mut libraries = entry.libraries.clone(); + libraries.push(loader_library(entry, artifact_url)); + + let mut warnings = Vec::new(); + if parent_version_id != mc_version { + warnings.push(format!( + "LiteLoader {} 叠在 {parent_version_id} 上（父链不是原版 {mc_version}）：tweakClass 追加在父链参数之后，父链自己的 tweakClass 不动", + entry.version + )); + } + if !libraries + .iter() + .any(|library| library.name.starts_with("net.minecraft:launchwrapper:")) + { + libraries.push(Library { + name: format!("net.minecraft:launchwrapper:{LAUNCHWRAPPER_FALLBACK}"), + ..Library::default() + }); + warnings.push( + "LiteLoader 的记录没带 launchwrapper：已补 1.12（Launch 主类就靠它）".to_string(), + ); + } + + let version_json = VersionJson { + id: Some(version_id.clone()), + name: Some(format!("{mc_version} · LiteLoader {}", entry.version)), + inherits_from: Some(parent_version_id.to_string()), + // 客户端 jar 恒在原版那层（父链与 loader 层都不带 jar）。 + jar: Some(mc_version.to_string()), + main_class: Some(LAUNCHWRAPPER_MAIN.to_string()), + minecraft_arguments: None, + arguments: Some(Arguments { + game: vec![ + Argument::Plain("--tweakClass".to_string()), + Argument::Plain(entry.tweak_class.clone()), + ], + jvm: Vec::new(), + }), + version_type: Some(if entry.snapshot { + ReleaseType::Snapshot + } else { + ReleaseType::Release + }), + libraries: Some(libraries), + ..VersionJson::default() + }; + + Ok(LoaderRelease { + kind: LoaderKind::LiteLoader, + mc_version: mc_version.to_string(), + parent_version_id: parent_version_id.to_string(), + loader_version: entry.version.clone(), + version_id, + version_json, + support: LoaderSupport::JsonRoute, + installer: None, + install_profile: None, + warnings, + }) +} + +/// 本体 jar 的那一条库：直链绝对地址（快照的路径与 maven 坐标不一致，不能靠坐标推导）。 +fn loader_library(entry: &LiteLoaderEntry, artifact_url: &str) -> Library { + Library { + name: format!("{LOADER_GROUP}:{LOADER_ARTIFACT}:{}", entry.version), + url: Some(DEFAULT_REPO.to_string()), + downloads: Some(LibraryDownloads { + artifact: Some(DownloadInfo { + id: None, + sha1: None, + size: None, + url: Some(artifact_url.to_string()), + path: None, + }), + classifiers: BTreeMap::new(), + }), + ..Library::default() + } +} diff --git a/crates/core/src/addon/loader/liteloader/versions.rs b/crates/core/src/addon/loader/liteloader/versions.rs new file mode 100644 index 0000000..11811eb --- /dev/null +++ b/crates/core/src/addon/loader/liteloader/versions.rs @@ -0,0 +1,219 @@ +//! 官方版本表（`dl.liteloader.com/versions/versions.json`）的解析：原版版本 → 条目列表。 +//! +//! 上游形状的四条硬事实写在父模块的文档里（[`super`]）；这里只放解析与 URL 拼装。 +//! 单独一个文件的理由是行数：父模块要装「解析」与「合成清单」两件事，一起写会破 400 行硬线。 + +use std::collections::{BTreeMap, BTreeSet}; + +use serde::Deserialize; + +use super::{LiteLoaderEntry, LoaderError, CENTRAL_REPO, DEFAULT_REPO, SNAPSHOT_REPO}; +use crate::game::library::Library; + +#[derive(Debug, Deserialize)] +struct Root { + #[serde(default)] + versions: BTreeMap, +} + +#[derive(Debug, Deserialize)] +struct GameVersions { + #[serde(default)] + repo: Option, + #[serde(default)] + artefacts: Option, + #[serde(default)] + snapshots: Option, +} + +#[derive(Debug, Deserialize)] +struct Repo { + #[serde(default)] + url: String, +} + +#[derive(Debug, Deserialize)] +struct Branch { + #[serde(rename = "com.mumfrey:liteloader", default)] + liteloader: BTreeMap, +} + +#[derive(Debug, Deserialize)] +struct Record { + #[serde(default, rename = "tweakClass")] + tweak_class: String, + #[serde(default)] + libraries: Vec, + #[serde(default)] + file: String, + #[serde(default)] + version: String, + #[serde(default)] + stream: String, +} + +/// 解析官方版本表：原版版本 → 该原版下的 LiteLoader 版本（**新在前**）。 +/// +/// # Errors +/// +/// 顶层不是 `{"versions": {…}}`、或一个版本都认不出时返回 metadata 错误。 +pub fn parse_versions(json: &str) -> Result>, LoaderError> { + let root: Root = serde_json::from_str(json) + .map_err(|error| LoaderError::metadata(format!("LiteLoader 版本表解析失败：{error}")))?; + let mut out: BTreeMap> = BTreeMap::new(); + for (mc_version, game) in &root.versions { + let repo = game + .repo + .as_ref() + .map(|repo| https_repo(&repo.url)) + .filter(|url| !url.is_empty()) + .unwrap_or_else(|| DEFAULT_REPO.to_string()); + let mut entries: Vec = Vec::new(); + let mut seen: BTreeSet = BTreeSet::new(); + if let Some(branch) = &game.artefacts { + collect(branch, mc_version, &repo, false, &mut entries, &mut seen); + } + if let Some(branch) = &game.snapshots { + collect(branch, mc_version, &repo, true, &mut entries, &mut seen); + } + if entries.is_empty() { + continue; + } + entries.sort_by(|left, right| cmp_versions(&right.version, &left.version)); + out.insert(mc_version.clone(), entries); + } + if out.is_empty() { + return Err(LoaderError::not_found( + "LiteLoader 版本表里没有任何可用版本（数据源形状变了？）", + )); + } + Ok(out) +} + +/// 收一个分支的记录（`latest` 别名与重复版本跳过）。 +fn collect( + branch: &Branch, + mc_version: &str, + repo: &str, + snapshot_branch: bool, + out: &mut Vec, + seen: &mut BTreeSet, +) { + for (key, record) in &branch.liteloader { + if key.eq_ignore_ascii_case("latest") || record.version.is_empty() { + continue; + } + if !seen.insert(record.version.clone()) { + continue; + } + // 记录自己标 SNAPSHOT 的也走快照路线（release 分支里出现过混编）。 + let snapshot = snapshot_branch || record.stream.eq_ignore_ascii_case("SNAPSHOT"); + let dir = format!("{repo}com/mumfrey/liteloader/{mc_version}/"); + let (url, snapshot_dir) = if snapshot { + // 快照仓是**固定**的（见 `SNAPSHOT_REPO` 的注释），不跟 `repo.url` 走。 + let snap_dir = format!("{SNAPSHOT_REPO}com/mumfrey/liteloader/{mc_version}-SNAPSHOT/"); + (None, Some(snap_dir)) + } else { + ( + (!record.file.is_empty()).then(|| format!("{dir}{}", record.file)), + None, + ) + }; + out.push(LiteLoaderEntry { + version: record.version.clone(), + mc_version: mc_version.to_string(), + snapshot, + tweak_class: record.tweak_class.clone(), + libraries: record.libraries.iter().map(rebased).collect(), + url, + snapshot_dir, + }); + } +} + +/// `http://…` → `https://…`（上游表里混着 http；HMCL 同样改写）。 +fn https_repo(url: &str) -> String { + if let Some(rest) = url.strip_prefix("http://") { + return format!("https://{rest}"); + } + url.to_string() +} + +/// 记录级库：保留上游字段（`http` → `https`），只给「没写 url」的库补基址（见模块文档的 group 分流）。 +fn rebased(library: &Library) -> Library { + let mut out = library.clone(); + match out + .url + .as_deref() + .map(str::trim) + .filter(|url| !url.is_empty()) + { + Some(url) => out.url = Some(https_repo(url)), + None => { + let group = out.name.split(':').next().unwrap_or_default(); + if group != "net.minecraft" { + out.url = Some(CENTRAL_REPO.to_string()); + } + } + } + out +} + +/// 版本号比较：按 `.`/`-`/`_` 切段，纯数字段按数值比，其余按字面量比。 +fn cmp_versions(left: &str, right: &str) -> std::cmp::Ordering { + let lhs: Vec<&str> = left.split(['.', '-', '_']).collect(); + let rhs: Vec<&str> = right.split(['.', '-', '_']).collect(); + for (a, b) in lhs.iter().zip(rhs.iter()) { + let order = match (a.parse::(), b.parse::()) { + (Ok(a), Ok(b)) => a.cmp(&b), + _ => a.cmp(b), + }; + if order != std::cmp::Ordering::Equal { + return order; + } + } + lhs.len().cmp(&rhs.len()) +} + +/// 从 `maven-metadata.xml` 拼出快照产物的直链（`liteloader----release.jar`）。 +/// +/// # Errors +/// +/// 缺 ``/`` 时返回 metadata 错误（宁可报错，也不猜一个 404 直链）。 +pub fn snapshot_artifact_url( + entry: &LiteLoaderEntry, + metadata_xml: &str, +) -> Result { + let dir = entry.snapshot_dir.as_deref().ok_or_else(|| { + LoaderError::metadata(format!( + "LiteLoader {} 不是快照版本，没有 maven 目录", + entry.version + )) + })?; + let timestamp = tag_value(metadata_xml, "timestamp").ok_or_else(|| { + LoaderError::metadata(format!( + "{} 的 maven-metadata.xml 里没有 ：拿不到快照直链", + entry.version + )) + })?; + let build = tag_value(metadata_xml, "buildNumber").ok_or_else(|| { + LoaderError::metadata(format!( + "{} 的 maven-metadata.xml 里没有 ", + entry.version + )) + })?; + Ok(format!( + "{dir}liteloader-{}-{timestamp}-{build}-release.jar", + entry.mc_version + )) +} + +/// 取 `…` 里的文本（maven 元数据只有一层，不引 XML 库，与 [`super::maven`] 同口径）。 +fn tag_value(xml: &str, tag: &str) -> Option { + let open = format!("<{tag}>"); + let close = format!(""); + let start = xml.find(&open)? + open.len(); + let end = xml[start..].find(&close)? + start; + let value = xml[start..end].trim(); + (!value.is_empty()).then(|| value.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..c940e9a --- /dev/null +++ b/crates/core/src/addon/loader/maven.rs @@ -0,0 +1,199 @@ +//! Maven 坐标与版本表（Forge / NeoForge）：版本列表地址、版本选择、installer 地址。 +//! +//! 与 [`super::forge`] 的分工：这里只管"maven 上有什么版本、jar 在哪"， +//! 那边只管"installer 里的 profile 怎么变成版本 JSON"。 +//! +//! 镜像：两家 maven 都在 D7 镜像表里有 BMCLAPI 规则（`bmclapi-neoforge` / +//! `bmclapi-forge-maven-net`），所以这里一律**写官方地址**，重写交给 `core::download` +//! 的镜像展开（与 M27 的"不拼镜像 URL"纪律一致）。 +//! +//! # 非 maven 族一律「没有答案」，不再回落 Forge +//! +//! 这里每个函数过去都用 `_ =>` 把「不是 NeoForge」的全当 Forge。加了第三个数据源 +//! （LiteLoader：官方版本表 + 从零合成，不是 maven）之后，那个通配会**静默拼出 Forge 的 +//! URL**：请求 404 或被当成 Forge 装成一个"像模像样"的错实例。现在： +//! +//! - 地址类函数返回 `Option`，非 maven 族给 `None`； +//! - 版本判定类函数对非 maven 族给「不匹配 / 放行原样」，语义上本就如此。 +//! +//! 真正的入口分流在 [`super::meta::LoaderSource`]（按 +//! [`LoaderKind::is_fabric_family`] / [`LoaderKind::is_maven_family`] 三路派发）。 + +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 根地址（非 maven 族给空串；调用方已按 [`LoaderKind::is_maven_family`] 分流）。 +#[must_use] +pub fn base(kind: LoaderKind) -> &'static str { + match kind { + LoaderKind::NeoForge => NEOFORGE_MAVEN, + LoaderKind::Forge => FORGE_MAVEN, + // fabric 系与 LiteLoader 都不是 maven 族——绝不能回落到 Forge 的仓库。 + LoaderKind::Fabric | LoaderKind::Quilt | LoaderKind::LiteLoader => "", + } +} + +/// maven 路径段（`group/artifact`）与该原版版本的匹配规则。 +fn layout(kind: LoaderKind, mc_version: &str) -> Option<(&'static str, &'static str)> { + match kind { + LoaderKind::NeoForge if mc_version == NEOFORGE_FORGE_LAYOUT_MC => { + Some((NEOFORGE_MAVEN, "net/neoforged/forge")) + } + LoaderKind::NeoForge => Some((NEOFORGE_MAVEN, "net/neoforged/neoforge")), + LoaderKind::Forge => Some((FORGE_MAVEN, "net/minecraftforge/forge")), + LoaderKind::Fabric | LoaderKind::Quilt | LoaderKind::LiteLoader => None, + } +} + +/// 该原版版本对应的 `maven-metadata.xml` 地址；非 maven 族给 `None`。 +#[must_use] +pub fn metadata_url(kind: LoaderKind, mc_version: &str) -> Option { + let (root, path) = layout(kind, mc_version)?; + Some(format!("{root}/{path}/maven-metadata.xml")) +} + +/// installer jar 地址；非 maven 族给 `None`。 +#[must_use] +pub fn installer_url(kind: LoaderKind, mc_version: &str, maven_version: &str) -> Option { + let (root, path) = layout(kind, mc_version)?; + let file = match kind { + LoaderKind::NeoForge if mc_version != NEOFORGE_FORGE_LAYOUT_MC => { + format!("neoforge-{maven_version}-installer.jar") + } + LoaderKind::NeoForge | LoaderKind::Forge => { + format!("forge-{maven_version}-installer.jar") + } + LoaderKind::Fabric | LoaderKind::Quilt | LoaderKind::LiteLoader => return None, + }; + Some(format!("{root}/{path}/{maven_version}/{file}")) +} + +/// 扫 maven-metadata.xml 里的 `` 值。 +/// +/// 故意不引 XML 库：maven 元数据是**极简且稳定**的格式（只有一层 `` 列表）， +/// 为它拉一个 XML 解析器不划算。解析不出就返回空表，由上层报"没有可用版本"。 +#[must_use] +pub fn parse_metadata_versions(xml: &str) -> Vec { + const OPEN: &str = ""; + const CLOSE: &str = ""; + 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 { + let core = version.split(['-', '+']).next().unwrap_or(version); + let segments: Vec = core + .split('.') + .map(str::parse::) + .collect::>() + .ok()?; + let (major, minor) = (*segments.first()?, *segments.get(1)?); + match major { + 0 => None, + 26.. => Some(format!("{major}.{minor}")), + _ => Some(format!("1.{major}.{minor}")), + } +} + +/// maven 版本是否属于该原版版本（非 maven 族恒 `false`：它们的版本号不是 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), + LoaderKind::Forge => version.starts_with(&format!("{mc_version}-")), + LoaderKind::Fabric | LoaderKind::Quilt | LoaderKind::LiteLoader => false, + } +} + +/// 从 maven 版本表里挑出属于该原版版本的加载器版本（**升序**，末尾最好）。 +#[must_use] +pub fn select_versions(kind: LoaderKind, mc_version: &str, versions: &[String]) -> Vec { + let mut picked: Vec = 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 版本，原样返回； +/// 非 maven 族（fabric 系 / LiteLoader）的版本号原样返回——它们的版本号本就自带原版口径。 +#[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::Forge => true, + LoaderKind::NeoForge => mc_version == NEOFORGE_FORGE_LAYOUT_MC, + LoaderKind::Fabric | LoaderKind::Quilt | LoaderKind::LiteLoader => false, + }; + if needs_prefix && !raw.starts_with(&format!("{mc_version}-")) { + format!("{mc_version}-{raw}") + } else { + raw.to_string() + } +} + +/// 用户视角的加载器版本号（带原版前缀的 maven 版本要去掉前缀）。 +/// +/// 谁带前缀是**按加载器 + 布局**定的：Forge 恒带；NeoForge 只有「1.20.1 走 forge 布局」 +/// 那一段带（`1.20.1-47.1.106` → `47.1.106`），其余 NeoForge 版本本身就是完整 maven 版本； +/// fabric 系与 LiteLoader 的版本号本来就是用户视角的。 +#[must_use] +pub fn display_loader_version(kind: LoaderKind, mc_version: &str, maven_version: &str) -> String { + let strip = match kind { + LoaderKind::Forge => true, + LoaderKind::NeoForge => mc_version == NEOFORGE_FORGE_LAYOUT_MC, + LoaderKind::Fabric | LoaderKind::Quilt | LoaderKind::LiteLoader => false, + }; + if strip { + maven_version + .strip_prefix(&format!("{mc_version}-")) + .unwrap_or(maven_version) + .to_string() + } else { + maven_version.to_string() + } +} + +/// 版本号 → 可比较的数字键（非数字段按 0，保证不 panic）。 +fn numeric_key(version: &str) -> Vec { + version + .split(['-', '.', '+']) + .map(|segment| segment.parse::().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..b91e9d4 --- /dev/null +++ b/crates/core/src/addon/loader/meta.rs @@ -0,0 +1,368 @@ +//! 加载器元数据的网络层：版本列表 + 官方 profile/installer → [`LoaderRelease`]。 +//! +//! 分工与 M27 的 [`crate::game::install::RemoteSource`] 一样：**只发请求、只解析**， +//! 不写游戏目录（installer jar 落 `.ULL/cache/meta/` 作离线复用），镜像/退避/health 全在 +//! `core::download` 的引擎里（我们一律递**官方地址**，重写由镜像表负责）。 +//! +//! 三个数据源的取数路径完全不同（**三路显式派发**，不许再有「不是 fabric 就是 maven」）： +//! +//! ```text +//! Fabric / Quilt : meta API → profile/json（官方直出可用版本 JSON） +//! NeoForge/Forge : maven-metadata.xml → installer jar → 读 install_profile.json + version.json +//! LiteLoader : dl.liteloader.com/versions.json →（快照再读 maven-metadata.xml）→ 从零合成 +//! ``` + +use std::fs::File; +use std::path::{Path, PathBuf}; + +use zip::ZipArchive; + +use super::fabric; +use super::forge::{self, InstallProfile}; +use super::liteloader; +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"; + +/// LiteLoader 官方版本表的缓存文件名（整表 49 KB，一次取全量再本地筛）。 +const LITELOADER_LIST_TAG: &str = "liteloader-versions.json"; + +/// 远端加载器元数据来源。 +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, 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()); + } + if kind == LoaderKind::LiteLoader { + let table = self.liteloader_table().await?; + let entries = table.get(mc_version.trim()).ok_or_else(|| { + LoaderError::not_found(format!( + "LiteLoader 没有适配原版 {mc_version} 的版本（官方版本表 {} 条原版版本）", + table.len() + )) + })?; + return Ok(entries.iter().map(|entry| entry.version.clone()).collect()); + } + let url = maven::metadata_url(kind, mc_version).ok_or_else(|| non_maven(kind))?; + 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 系取该原版版本下最新的一版，LiteLoader 取首个 release / 否则最新）。 + /// + /// 等价于 [`Self::resolve_on`]，父版本 = 原版本身。 + /// + /// # Errors + /// + /// 网络失败、版本不存在、installer 缺 profile、协议不受支持时返回 [`LoaderError`]。 + pub async fn resolve( + &self, + kind: LoaderKind, + mc_version: &str, + loader_version: Option<&str>, + ) -> Result { + self.resolve_on(kind, mc_version, loader_version, None) + .await + } + + /// 解析一个加载器版本，并**指定父版本**（`parent` 为 `None` 时等于 `mc_version`）。 + /// + /// 目前只有 LiteLoader 接受「父版本不是原版」：它靠 `--tweakClass` 追加生效，叠在 + /// Forge 1.12.2 上是官方主推组合。其它加载器声明自己的主类/启动目标，叠在别人的 loader + /// 层上没有装配路径，因此**具名拒绝**，而不是默默装成「叠在原版上」。 + /// + /// # Errors + /// + /// 同上；另外「非 LiteLoader 却指定了非原版父版本」返回 `unsupported`。 + pub async fn resolve_on( + &self, + kind: LoaderKind, + mc_version: &str, + loader_version: Option<&str>, + parent: Option<&str>, + ) -> Result { + let requested = loader_version + .map(str::trim) + .filter(|value| !value.is_empty()); + let parent_version_id = parent + .map(str::trim) + .filter(|value| !value.is_empty()) + .unwrap_or(mc_version); + if parent_version_id != mc_version && kind != LoaderKind::LiteLoader { + return Err(LoaderError::unsupported(format!( + "{} 没有「叠在 {parent_version_id} 上」的装配路线：它自己声明主类与启动目标，只能叠在原版 {mc_version} 上", + kind.label() + )) + .with_hint("先装原版，再在其上安装这一家加载器")); + } + 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); + } + if kind == LoaderKind::LiteLoader { + return self + .resolve_liteloader(mc_version, requested, parent_version_id) + .await; + } + + 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) + .ok_or_else(|| non_maven(kind))?; + 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); + release.parent_version_id = parent_version_id.to_string(); + Ok(release) + } + + /// LiteLoader：整表 → 选条 →（快照再查 maven-metadata）→ 合成清单。 + async fn resolve_liteloader( + &self, + mc_version: &str, + requested: Option<&str>, + parent_version_id: &str, + ) -> Result { + let table = self.liteloader_table().await?; + let entries = table.get(mc_version.trim()).ok_or_else(|| { + LoaderError::not_found(format!( + "LiteLoader 没有适配原版 {mc_version} 的版本（官方版本表 {} 条原版版本）", + table.len() + )) + })?; + let entry = match requested { + Some(raw) => liteloader::find_entry(entries, raw).ok_or_else(|| { + LoaderError::not_found(format!( + "LiteLoader {} 没有版本 `{raw}`（该原版下有：{}）", + mc_version, + entries + .iter() + .map(|entry| entry.version.as_str()) + .collect::>() + .join(" / ") + )) + })?, + None => liteloader::default_entry(entries).ok_or_else(|| { + LoaderError::not_found(format!("LiteLoader 没有适配原版 {mc_version} 的版本")) + })?, + }; + // 直链：release 分支记录里就有；快照分支必须再读一次 maven-metadata.xml。 + let artifact_url = match (&entry.url, &entry.snapshot_dir) { + (Some(url), _) => url.clone(), + (None, Some(dir)) => { + let metadata = self.fetch_text(&format!("{dir}maven-metadata.xml")).await?; + liteloader::snapshot_artifact_url(entry, &metadata)? + } + (None, None) => { + return Err(LoaderError::metadata(format!( + "LiteLoader {} 的记录既没有直链也没有快照目录", + entry.version + ))) + } + }; + liteloader::build_release(mc_version, parent_version_id, entry, &artifact_url) + } + + /// 取 LiteLoader 整张官方版本表（按原版版本分组）。 + async fn liteloader_table( + &self, + ) -> Result>, LoaderError> + { + let body = self + .fetch_text_named(liteloader::VERSION_LIST_URL, LITELOADER_LIST_TAG) + .await?; + liteloader::parse_versions(&body) + } + + /// 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 { + 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 { + self.fetch_text_named(url, "loader-meta.bin").await + } + + /// 同上，缓存文件名按调用方给（LiteLoader 整表单独一档，别把小响应和 49 KB 的表混存）。 + async fn fetch_text_named(&self, url: &str, tag: &str) -> Result { + let dest = self.meta_cache.join(tag); + 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}"))) + } +} + +/// 非 maven 族被送进 maven 分支时的统一报错（入口已分流，走到这里说明调用链有 bug）。 +fn non_maven(kind: LoaderKind) -> LoaderError { + LoaderError::unsupported(format!( + "{} 不是 maven 族加载器，没有 maven 元数据/installer 地址", + kind.label() + )) +} + +/// 读 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), 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, name: &str) -> Result, 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..53346e7 --- /dev/null +++ b/crates/core/src/addon/loader/mod.rs @@ -0,0 +1,297 @@ +//! 加载器安装（Fabric / Quilt / NeoForge / Forge / LiteLoader）：官方元数据 → 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`] | LiteLoader | 官方版本表 → **从零合成**清单（见 [`liteloader`]） | +//! | [`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。 +//! +//! OptiFine 仍**认得出但装不了**（[`LoaderKind::from_core`] 返回 `None`）：它要跑外部 +//! `optifine.Patcher` 并原地改 zip，不在本期（见 `DevDocs/artifacts/m218/SURVEY-p1.md` §3）。 + +pub mod fabric; +pub mod forge; +pub mod liteloader; +pub mod maven; +pub mod meta; +pub mod parent; +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 的原版路径。 +/// OptiFine 也**不在**这里：它要跑外部 `optifine.Patcher` + 原地改 zip，本启动器仍只识别不安装。 +#[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, + /// LiteLoader（`dl.liteloader.com`，官方版本表 + 从零合成 launchwrapper 清单，无 installer）。 + LiteLoader, +} + +impl LoaderKind { + /// 解析命令行 / 整合包清单里的加载器名（大小写不敏感）。 + /// + /// 七个 id 的匹配**委派**给 [`crate::game::LoaderKind::parse`]（词表的源头，M126）， + /// 本方法只多收一个**输入别名** `neo-forge`：那是 Modrinth 的拼法（mrpack + /// `dependencies` 的键、CF 包里也有这种写法），**只进不出**——[`Self::as_str`] 绝不产出 + /// 它。识别得出但本启动器装不了的（原版 / OptiFine）返回 `None`。 + #[must_use] + pub fn parse(raw: &str) -> Option { + let wanted = raw.trim(); + if wanted.eq_ignore_ascii_case("neo-forge") { + return Some(Self::NeoForge); + } + Self::from_core(crate::game::LoaderKind::parse(wanted)?) + } + + /// core 的宽种类 → 本模块能装的五家（`None` = 识别得出但本启动器装不了）。 + /// + /// 穷尽 match：core 加一支就编不过，逼作者决定「它能不能装」。 + const fn from_core(kind: crate::game::LoaderKind) -> Option { + match kind { + crate::game::LoaderKind::Fabric => Some(Self::Fabric), + crate::game::LoaderKind::Quilt => Some(Self::Quilt), + crate::game::LoaderKind::NeoForge => Some(Self::NeoForge), + crate::game::LoaderKind::Forge => Some(Self::Forge), + crate::game::LoaderKind::LiteLoader => Some(Self::LiteLoader), + crate::game::LoaderKind::Vanilla | crate::game::LoaderKind::OptiFine => None, + } + } + + /// 稳定字符串 id（进版本 id、JSON 输出与日志）。 + /// + /// 词表**不在本模块**：[`crate::game::LoaderKind::as_str`] 是「种类 → 对外稳定 id」的源头 + /// （M126）。这里只做**结构映射**（一个 id 字面量都没有）——安装侧拼出来的 + /// `--` 必须能被 [`crate::game::InstanceLoader::parse`] 认回来，委派让 + /// 「两边各写一份、改一边忘了另一边」这件事物理上做不到。 + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::Fabric => crate::game::LoaderKind::Fabric.as_str(), + Self::Quilt => crate::game::LoaderKind::Quilt.as_str(), + Self::NeoForge => crate::game::LoaderKind::NeoForge.as_str(), + Self::Forge => crate::game::LoaderKind::Forge.as_str(), + Self::LiteLoader => crate::game::LoaderKind::LiteLoader.as_str(), + } + } + + /// 人读名称。 + #[must_use] + pub const fn label(self) -> &'static str { + match self { + Self::Fabric => "Fabric", + Self::Quilt => "Quilt", + Self::NeoForge => "NeoForge", + Self::Forge => "Forge", + Self::LiteLoader => "LiteLoader", + } + } + + /// 是否属于 Fabric 系（纯 meta、profile JSON 直接可用）。 + #[must_use] + pub const fn is_fabric_family(self) -> bool { + matches!(self, Self::Fabric | Self::Quilt) + } + + /// 是否走 maven 族（installer jar + install profile）。 + /// + /// 第三个数据源（LiteLoader）既不是 fabric 系也不是 maven 族，所以这条路**必须显式问**， + /// 不能再用「不是 fabric 就是 maven」的二分——那会把 LiteLoader 静默送进 Forge 的 URL 拼装。 + #[must_use] + pub const fn is_maven_family(self) -> bool { + matches!(self, Self::NeoForge | Self::Forge) + } + + /// 全部加载器（CLI 的 `--loader` 枚举提示用）。 + #[must_use] + pub const fn all() -> &'static [Self] { + &[ + Self::Fabric, + Self::Quilt, + Self::NeoForge, + Self::Forge, + Self::LiteLoader, + ] + } + + /// loader 版本 id 的词根：`--`（`versions//` 与实例 `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, +} + +impl LoaderError { + /// 构造。 + #[must_use] + pub fn new(kind: LoaderErrorKind, message: impl Into) -> Self { + Self { + kind, + message: message.into(), + hint: None, + } + } + + /// 走不通我们的路线（需要外调 java installer / 老协议）。 + #[must_use] + pub fn unsupported(message: impl Into) -> Self { + Self::new(LoaderErrorKind::Unsupported, message) + } + + /// 元数据里查不到。 + #[must_use] + pub fn not_found(message: impl Into) -> Self { + Self::new(LoaderErrorKind::NotFound, message) + } + + /// 元数据坏了/形状不符。 + #[must_use] + pub fn metadata(message: impl Into) -> Self { + Self::new(LoaderErrorKind::Metadata, message) + } + + /// 本地 IO。 + #[must_use] + pub fn io(message: impl Into) -> Self { + Self::new(LoaderErrorKind::Io, message) + } + + /// 补一句提示。 + #[must_use] + pub fn with_hint(mut self, hint: impl Into) -> 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 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/parent.rs b/crates/core/src/addon/loader/parent.rs new file mode 100644 index 0000000..982950e --- /dev/null +++ b/crates/core/src/addon/loader/parent.rs @@ -0,0 +1,64 @@ +//! 父版本链：把「叠在哪一层上」翻译成原版版本 id（LiteLoader 叠在 Forge 上时要用）。 +//! +//! 加载器层只声明 `inheritsFrom`，客户端 jar、资源索引都在**根**那一层（原版）。所以当用户 +//! 指定的父版本不是原版（`1.12.2-forge-14.23.5.2860`）时，我们既要记住父版本 id（写进 +//! 合成清单的 `inheritsFrom`），又要知道根的原版 id（拼 loader 版本 id、定位 jar）。 +//! +//! 判据只有一条：**读盘**。父版本在盘上就必须读得出它的 `inheritsFrom`；读不出来说明父版本 +//! 压根没装好，这时报错比猜一个原版版本号强（猜错会装出 `inheritsFrom` 指向不存在版本、 +//! 启动必崩的实例）。沿链走最多 [`MAX_DEPTH`] 跳，成环即报错（与 +//! [`crate::game::inherit::resolve`] 同口径）。 + +use crate::game::layout::GameLayout; +use crate::game::manifest::VersionJson; + +use super::LoaderError; + +/// 继承链深度上限（现实里 loader + patch 不超过 5 层）。 +pub const MAX_DEPTH: usize = 32; + +/// 从盘上的版本 JSON 沿 `inheritsFrom` 走到根，返回根版本 id（原版）。 +/// +/// # Errors +/// +/// 版本 JSON 不存在 → `not_found`（父版本还没装）；读不出来 / 成环 → `metadata`。 +pub fn root_version_id(layout: &GameLayout, version_id: &str) -> Result { + let mut chain = vec![version_id.to_string()]; + let mut current = version_id.to_string(); + for _ in 0..MAX_DEPTH { + let manifest = read_manifest(layout, ¤t)?; + match manifest.inherits_from.as_deref().map(str::trim) { + Some(parent) if !parent.is_empty() => { + if chain.iter().any(|id| id == parent) { + chain.push(parent.to_string()); + return Err(LoaderError::metadata(format!( + "父版本链成环：{}", + chain.join(" → ") + ))); + } + chain.push(parent.to_string()); + current = parent.to_string(); + } + _ => return Ok(current), + } + } + Err(LoaderError::metadata(format!( + "父版本链超过 {MAX_DEPTH} 层，拒绝继续解析：{}", + chain.join(" → ") + ))) +} + +/// 读一份版本 JSON；文件不存在时给出「先装父版本」的可执行提示。 +fn read_manifest(layout: &GameLayout, version_id: &str) -> Result { + let path = layout.version_json(version_id); + let text = std::fs::read_to_string(&path).map_err(|error| { + LoaderError::not_found(format!( + "父版本 {version_id} 还没装好（读不到 {}：{error}）", + path.display() + )) + .with_hint("先用同一个父版本装一次它自己的加载器（例如 `install <原版> --loader forge`），再在它上面叠") + })?; + VersionJson::from_json_str(&text).map_err(|error| { + LoaderError::metadata(format!("父版本 {version_id} 的清单解析失败：{error}")) + }) +} diff --git a/crates/core/src/addon/loader/plan.rs b/crates/core/src/addon/loader/plan.rs new file mode 100644 index 0000000..06ecabe --- /dev/null +++ b/crates/core/src/addon/loader/plan.rs @@ -0,0 +1,293 @@ +//! 加载器安装计划：一份 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::{LoaderError, 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, + /// 目标原版版本（客户端 jar 与资源都在这一层）。 + pub mc_version: String, + /// **父版本 id**：合成清单的 `inheritsFrom`。默认等于 [`Self::mc_version`]（叠在原版上）， + /// 叠在别的加载器层上时是那一层的版本 id（`1.12.2-forge-14.23.5.2860`）。 + pub parent_version_id: String, + /// 加载器自身版本号（`0.15.11` / `47.2.0` / `21.1.80` / `1.12.2-SNAPSHOT`）。 + pub loader_version: String, + /// 生成的 loader 版本 id（`1.20.1-fabric-0.15.11`，即 `versions//` 的目录名）。 + pub version_id: String, + /// loader 版本 JSON（`inheritsFrom` 指向父版本）。 + pub version_json: VersionJson, + /// 可走哪条路线。 + pub support: LoaderSupport, + /// installer jar 的磁盘路径（M35 执行器的输入；Fabric 系与 LiteLoader 为 `None`）。 + pub installer: Option, + /// installer 里读出来的 install profile（执行器要 `processors` / `data` / `libraries`）。 + pub install_profile: Option, + /// 解析期告警（不致命：例如 profile 缺 loader 库时我们补了一条）。 + pub warnings: Vec, +} + +impl LoaderRelease { + /// 是否可真正安装。 + #[must_use] + pub const fn is_installable(&self) -> bool { + self.support.is_installable() + } + + /// 父版本是不是原版本身（`false` = 叠在别的加载器层上）。 + #[must_use] + pub fn parent_is_vanilla(&self) -> bool { + self.parent_version_id == self.mc_version + } + + /// 是否要外调 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, + "parent_version_id": self.parent_version_id, + "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, + /// **父版本**（[`LoaderRelease::parent_version_id`]）的清单是否已在盘上。 + /// + /// 父版本是原版时缺了能自动补装（[`LoaderInstallPlan::vanilla_install_needed`]）； + /// 父版本是别的加载器层（Forge）时缺了**直接报错**——我们不能替用户决定装哪一版 Forge。 + pub parent_installed: bool, +} + +/// 加载器安装计划：M27 的 [`InstallPlan`] + 加载器自己的上下文。 +/// +/// 执行期直接 `execute(&engine, &plan.install, …)`：那份计划里的 `version_json` 就是 +/// 带 `inheritsFrom` 的 loader 层，`execute` 会在**全部库就绪后**原子写到 +/// `versions//.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「宁可给出可修复的骨架，也不静默假装成功」一致。 + /// + /// # Errors + /// + /// 父版本不是原版、而它又没装在盘上时返回 [`LoaderError::not_found`]（具名说清是哪个 + /// 父版本缺了）。**不能默默回落成叠原版**：那会装出一份和用户意图不同的实例。 + pub fn build(input: LoaderPlanInput<'_>) -> Result { + let release = input.release; + // 同一个 loader 版本 id 不能同时表示两条父链（`<原版>-liteloader-` 与 + // 「叠在 Forge 上」撞同一个目录）：盘上那份的 `inheritsFrom` 与本次请求不符就具名报错， + // 而不是把旧清单覆盖掉——旧实例会静默换父链，启动行为跟着变。 + if let Some(existing) = existing_parent(input.layout, &release.version_id) { + if existing != release.parent_version_id { + return Err(LoaderError::unsupported(format!( + "{} 已装在盘上，父版本是 {existing}，与本次请求的 {} 不同", + release.version_id, release.parent_version_id + )) + .with_hint(format!( + "loader 版本 id 由「原版版本 + 加载器 + 加载器版本」决定，叠在别的层上会撞同一个目录：先删掉 versions/{}（旧实例也会失去这一层），或换一个加载器版本", + release.version_id + ))); + } + } + if !input.parent_installed && !release.parent_is_vanilla() { + return Err(LoaderError::not_found(format!( + "父版本 {} 还没装好：{} {} 要叠在它上面", + release.parent_version_id, + release.kind.label(), + release.loader_version + )) + .with_hint(format!( + "先把父版本装上（同一个原版版本先装一次它自己的加载器），再重跑；本次不会替你猜一个 {} 的版本", + release.parent_version_id + ))); + } + 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.parent_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, + }; + + Ok(Self { + release: release.clone(), + install, + vanilla_install_needed: !input.parent_installed && release.parent_is_vanilla(), + }) + } + + /// 计划里的待下载文件。 + #[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 + } +} + +/// 盘上那份 `versions//.json` 的 `inheritsFrom`（不存在 / 读不出 / 没写 → `None`）。 +/// +/// 只用来挡「同一版本 id 撞两条父链」，不参与其它判定：读失败不该让安装失败， +/// 所以错误一律吞成 `None`（真正的父子链校验由 [`crate::game::inherit::resolve`] 与 +/// [`LoaderPlanInput::parent_installed`] 负责）。 +fn existing_parent(layout: &GameLayout, version_id: &str) -> Option { + let text = std::fs::read_to_string(layout.version_json(version_id)).ok()?; + let manifest = VersionJson::from_json_str(&text).ok()?; + manifest + .inherits_from + .map(|parent| parent.trim().to_string()) + .filter(|parent| !parent.is_empty()) +} 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..d9ca5a0 --- /dev/null +++ b/crates/core/src/addon/loader/processors/download.rs @@ -0,0 +1,84 @@ +//! 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, +) -> InstallReport { + let outcomes: Vec = 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, + manifest: 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, + stderr_tail: Option, +} + +impl ProcessorError { + /// 构造。 + #[must_use] + pub fn new(kind: ProcessorErrorKind, message: impl Into) -> Self { + Self { + kind, + message: message.into(), + hint: None, + stderr_tail: None, + } + } + + /// 规划期失败（install profile 形状/变量问题）。 + #[must_use] + pub fn plan(message: impl Into) -> Self { + Self::new(ProcessorErrorKind::Plan, message) + } + + /// 找不到可用的 Java。 + #[must_use] + pub fn java_missing(message: impl Into) -> Self { + Self::new(ProcessorErrorKind::Java, message) + } + + /// processor 依赖不在盘上。 + #[must_use] + pub fn library_missing(message: impl Into) -> Self { + Self::new(ProcessorErrorKind::Library, message) + } + + /// processor 产物没落盘。 + #[must_use] + pub fn output_missing(message: impl Into) -> Self { + Self::new(ProcessorErrorKind::Output, message) + } + + /// 本地 IO 失败。 + #[must_use] + pub fn io(message: impl Into) -> 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) -> 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..62ea5b3 --- /dev/null +++ b/crates/core/src/addon/loader/processors/exec.rs @@ -0,0 +1,363 @@ +//! 逐个外调 java 执行 processor：`java -cp <依赖…>: <主类> <参数…>`。 +//! +//! 依据 `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::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; +use crate::platform::child::quiet; + +/// 一步的结局。 +#[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, + /// stderr 尾巴（已脱敏，可能为空）。 + pub stderr_tail: Option, +} + +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, + /// 不致命的告警（摘要不符、没有 outputs 的步骤等）。 + pub warnings: Vec, +} + +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::>(), + "warnings": self.warnings, + }) + } +} + +/// 每步完成的回调（CLI 往 stderr 打实时进度用）。 +pub type StepSink = Arc; + +/// 按 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 { + 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, +) -> Result { + let redactor = host_redactor(); + let mut warnings = Vec::new(); + let mut outcomes = Vec::with_capacity(plan.steps.len()); + let satisfied: Vec = 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, +) -> Result { + 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 = quiet(&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 ` 装一个托管 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 = 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) -> Result<(), ProcessorError> { + let missing: Vec = 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) -> 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 { + 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 { + 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, +} + +/// 一个待执行的 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, + /// `-cp` 的依赖 jar（不含 `jar` 自己）。 + pub classpath: Vec, + /// 已展开的参数。 + pub args: Vec, + /// 产物与期望摘要。 + pub outputs: Vec, +} + +impl ProcessorStep { + /// 一步的 `-cp` 全串（依赖在前、可执行 jar 在后，与 HMCL 一致）。 + /// + /// # Errors + /// + /// 路径里含分隔符时返回 IO 错误（Windows 的 `;` 不可能出现在合法路径里， + /// 真出现说明路径是拼错的）。 + pub fn classpath_join(&self) -> Result { + 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, + /// processor 依赖库（走 M27 引擎下载）。 + pub libraries: Vec, + /// 跑 installer 需要的 Java 要求。 + pub java_requirement: JavaRequirement, + /// 规划期告警（不致命）。 + pub warnings: Vec, +} + +impl ProcessorPlan { + /// 组计划。 + /// + /// # Errors + /// + /// `data` 表变量缺定义、构件坐标不合法、processor 缺 `jar` 字段时返回规划错误。 + pub fn build(input: ProcessorPlanInput<'_>) -> Result { + 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::>(), + "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::>(), + "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::>(), + }) +} + +/// 展开一步的 `outputs` 表（路径 + 期望摘要）。 +fn step_outputs( + variables: &Variables, + processor: &Processor, + coordinate: &str, + scratch: &Path, + warnings: &mut Vec, +) -> Result, 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 { + 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) -> (Vec, usize) { + let total = files.len(); + let mut seen: Vec = Vec::with_capacity(total); + let mut kept: Vec = 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 `")) + } + }; + 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, + /// 可执行 jar 的 maven 坐标。 + #[serde(default)] + pub jar: Option, + /// 主类覆盖（官方 profile 不写，留给少数 fork）。 + #[serde(default, rename = "mainClass")] + pub main_class: Option, + /// 依赖 jar 的 maven 坐标（**不含** `jar` 自己）。 + #[serde(default)] + pub classpath: Vec, + /// 命令行参数（可含 `{VAR}` / `[坐标]` / `'字面量'` 三种占位）。 + #[serde(default)] + pub args: Vec, + /// 产物表：路径占位 → 期望 SHA-1（既有产物可用于幂等跳过）。 + #[serde(default)] + pub outputs: BTreeMap, +} + +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, + /// server 侧的值（本期不跑 server 安装，只解析不动作）。 + #[serde(default)] + pub server: Option, +} + +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(""), "{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 { + 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, + 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\<名>` → ``）。 + +use std::path::PathBuf; + +use crate::launch::redact::Redactor; + +/// 尾巴保留的行数（够看异常栈头）。 +const TAIL_LINES: usize = 12; +/// 尾巴保留的字符上限。 +const TAIL_CHARS: usize = 1200; + +/// 宿主脱敏器：把用户主目录换成 ``。 +/// +/// 复用 [`crate::launch::redact::Redactor`]（与 M15/M31 落地的同一套规则：token、 +/// ``、长不透明串、带点 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 { + (!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//.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, + /// 游戏目录布局（`libraries/` 与 `versions/` 的路径规则）。 + pub layout: &'a GameLayout, + /// 目标原版版本（`net.minecraft:client:` 这类坐标回落用）。 + 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, + embedded: Vec, + /// 参数里 `[坐标]` 的解析上下文（官方 profile 会在 `args` 里直接写坐标，不只写在 `data` 里）。 + artifacts: Option, +} + +/// `[坐标]` 的解析上下文。 +#[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 { + 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 { + 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 { + 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 { + 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, + closing: char, + pattern: &str, +) -> Result { + 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:`（无 classifier）对应的是 +/// `versions//.jar`。官方 installer 会把 client jar 塞进本地 maven 布局， +/// 我们不复制（磁盘上原版 jar 只有一份），因此按目标版本回落。 +fn artifact_path( + libraries: &Path, + vanilla_jar: &Path, + descriptor: &str, +) -> Result { + 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/liteloader.rs b/crates/core/src/addon/loader/tests/liteloader.rs new file mode 100644 index 0000000..f42a8f6 --- /dev/null +++ b/crates/core/src/addon/loader/tests/liteloader.rs @@ -0,0 +1,338 @@ +//! LiteLoader 数据源与合成：官方版本表（**真实响应的裁剪版**）→ 版本条目 → 合成清单。 +//! +//! 夹具 `LITELOADER_VERSIONS` 是 2026-11 从 `https://dl.liteloader.com/versions/versions.json` +//! 真取的一份响应（200 / 49129 字节 / 16 个原版版本）里挑三个原版版本原样留下： +//! `1.7.10`（只有 release 分支）、`1.10.2`（release + snapshots，且 `repo.url` 是 `…/repo/` +//! 形态——专门用来钉「快照仓固定」这条）、`1.12.2`（只有 snapshots 分支）。删掉的是另外 13 个原版版本与 +//! 每个版本下的多余分支；**字段名与结构一个没改**（键仍是 md5、`latest` 别名也留着，用来 +//! 钉「跳过别名 + 按 version 去重」）。`LITELOADER_METADATA` 是同一次探测里取的 +//! `repo.mumfrey.com/…/liteloader/1.12.2-SNAPSHOT/maven-metadata.xml`（200 / 358 字节）。 + +use crate::addon::loader::liteloader::{ + build_release, default_entry, find_entry, parse_versions, snapshot_artifact_url, CENTRAL_REPO, +}; +use crate::addon::loader::{LoaderErrorKind, LoaderKind}; +use crate::game::loader::{InstanceLoader, LoaderKind as Wide}; +use crate::game::version::ReleaseType; + +/// 真实响应的裁剪版（见文件头）。 +const LITELOADER_VERSIONS: &str = r#"{ + "meta": { + "description": "LiteLoader is a lightweight mod bootstrap designed to provide basic loader functionality for mods which don't need to modify game mechanics.", + "authors": "Mumfrey", + "url": "http://dl.liteloader.com", + "updated": "2017-11-29T16:31:41+00:00", + "updatedTime": 1511973101 + }, + "versions": { + "1.7.10": { + "repo": {"stream": "RELEASE", "type": "ivy", "url": "http://dl.liteloader.com/versions/", "classifier": "mcpnames"}, + "artefacts": {"com.mumfrey:liteloader": { + "63ada46e033d0cb6782bada09ad5ca4e": { + "tweakClass": "com.mumfrey.liteloader.launch.LiteLoaderTweaker", + "libraries": [{"name": "net.minecraft:launchwrapper:1.11"}, {"name": "org.ow2.asm:asm-all:5.0.3"}], + "srcJar": "liteloader-1.7.10_04-mcpnames-sources.jar", + "mcpJar": "liteloader-1.7.10_04-mcpnames.jar", + "stream": "RELEASE", + "file": "liteloader-1.7.10_04.jar", + "version": "1.7.10_04", + "md5": "63ada46e033d0cb6782bada09ad5ca4e", + "timestamp": "1414368553" + }, + "db7235aefd407ac1fde09a7baba50839": { + "tweakClass": "com.mumfrey.liteloader.launch.LiteLoaderTweaker", + "libraries": [ + {"name": "net.minecraft:launchwrapper:1.9"}, + {"name": "org.ow2.asm:asm-all:5.0.3", "url": "http://repo.maven.apache.org/maven2/"} + ], + "stream": "RELEASE", + "file": "liteloader-1.7.10_00.jar", + "version": "1.7.10_00", + "md5": "db7235aefd407ac1fde09a7baba50839", + "timestamp": "1404330030" + } + }} + }, + "1.10.2": { + "repo": {"stream": "RELEASE", "type": "m2", "url": "http://dl.liteloader.com/repo/", "classifier": ""}, + "artefacts": {"com.mumfrey:liteloader": { + "8a7c21f32d77ee08b393dd3921ced8eb": { + "tweakClass": "com.mumfrey.liteloader.launch.LiteLoaderTweaker", + "libraries": [{"name": "net.minecraft:launchwrapper:1.12"}, {"name": "org.ow2.asm:asm-all:5.0.3"}], + "stream": "RELEASE", + "file": "liteloader-1.10.2.jar", + "version": "1.10.2", + "md5": "8a7c21f32d77ee08b393dd3921ced8eb", + "timestamp": "1479473570" + } + }}, + "snapshots": { + "libraries": [ + {"name": "net.minecraft:launchwrapper:1.12"}, + {"name": "org.spongepowered:mixin:0.5.17-SNAPSHOT", "url": "https://repo.spongepowered.org/maven/"} + ], + "com.mumfrey:liteloader": { + "1cdd72f7232e45551f16cc8ffd27ccf3": { + "tweakClass": "com.mumfrey.liteloader.launch.LiteLoaderTweaker", + "libraries": [{"name": "net.minecraft:launchwrapper:1.12"}, {"name": "org.ow2.asm:asm-all:5.0.3"}], + "stream": "SNAPSHOT", + "file": "liteloader-1.10.2-SNAPSHOT.jar", + "version": "1.10.2-SNAPSHOT", + "build": "1.10.2-SNAPSHOT-rE85C8AE-b11-11", + "md5": "1cdd72f7232e45551f16cc8ffd27ccf3", + "timestamp": "1485987183", + "lastSuccessfulBuild": 11 + } + } + } + }, + "1.12.2": { + "repo": {"stream": "SNAPSHOT", "type": "m2", "url": "http://repo.mumfrey.com/content/repositories/snapshots/", "classifier": ""}, + "snapshots": { + "libraries": [ + {"name": "net.minecraft:launchwrapper:1.12"}, + {"name": "org.spongepowered:mixin:0.7.4-SNAPSHOT", "url": "https://repo.spongepowered.org/maven/"} + ], + "com.mumfrey:liteloader": { + "1420785ecbfed5aff4a586c5c9dd97eb": { + "tweakClass": "com.mumfrey.liteloader.launch.LiteLoaderTweaker", + "libraries": [{"name": "net.minecraft:launchwrapper:1.12"}, {"name": "org.ow2.asm:asm-all:5.2"}], + "stream": "SNAPSHOT", + "file": "liteloader-1.12.2-SNAPSHOT.jar", + "version": "1.12.2-SNAPSHOT", + "build": "1.12.2-SNAPSHOT-r4CC2BB0-b4-4", + "md5": "1420785ecbfed5aff4a586c5c9dd97eb", + "timestamp": "1511880271", + "lastSuccessfulBuild": 4 + }, + "latest": { + "tweakClass": "com.mumfrey.liteloader.launch.LiteLoaderTweaker", + "libraries": [{"name": "net.minecraft:launchwrapper:1.12"}, {"name": "org.ow2.asm:asm-all:5.2"}], + "stream": "SNAPSHOT", + "file": "liteloader-1.12.2-SNAPSHOT.jar", + "version": "1.12.2-SNAPSHOT", + "md5": "1420785ecbfed5aff4a586c5c9dd97eb", + "timestamp": "1511880271", + "lastSuccessfulBuild": 4 + } + } + } + } + } +}"#; + +/// 同一次探测取的 maven-metadata（真实 358 字节响应的原样）。 +const LITELOADER_METADATA: &str = r#" + + com.mumfrey + liteloader + 1.12.2-SNAPSHOT + + + 20171128.144431 + 4 + + 20171128144431 + +"#; + +#[test] +fn parses_the_real_version_table() { + let table = parse_versions(LITELOADER_VERSIONS).expect("真实响应必须能解析"); + assert_eq!(table.len(), 3, "只留了三个原版版本"); + + // release 分支：按 version 去重、新的排前面。 + let releases = &table["1.7.10"]; + assert_eq!( + releases + .iter() + .map(|e| e.version.as_str()) + .collect::>(), + ["1.7.10_04", "1.7.10_00"] + ); + // 目录名是**原版**版本（1.7.10），不是 loader 版本（1.7.10_04）。 + assert_eq!( + releases[0].url.as_deref(), + Some("https://dl.liteloader.com/versions/com/mumfrey/liteloader/1.7.10/liteloader-1.7.10_04.jar") + ); + assert!(!releases[0].snapshot); + + // 记录级库：没 url 的非 Mojang 库补 Central，Mojang 的库保持默认基址。 + let names: Vec<&str> = releases[0] + .libraries + .iter() + .map(|library| library.name.as_str()) + .collect(); + assert_eq!( + names, + [ + "net.minecraft:launchwrapper:1.11", + "org.ow2.asm:asm-all:5.0.3" + ] + ); + assert_eq!( + releases[0].libraries[0].url, None, + "Mojang 库仓才有 launchwrapper" + ); + assert_eq!(releases[0].libraries[1].url.as_deref(), Some(CENTRAL_REPO)); + + // 记录自己写了 url 的，保留但 http → https。 + assert_eq!( + releases[1].libraries[1].url.as_deref(), + Some("https://repo.maven.apache.org/maven2/") + ); + + // snapshot 分支：`latest` 别名跳过，直链留给 maven-metadata 现拼。 + let snapshots = &table["1.12.2"]; + assert_eq!(snapshots.len(), 1, "latest 别名不算一个版本"); + assert!(snapshots[0].snapshot); + assert!(snapshots[0].url.is_none()); + assert_eq!( + snapshots[0].snapshot_dir.as_deref(), + Some("https://repo.mumfrey.com/content/repositories/snapshots/com/mumfrey/liteloader/1.12.2-SNAPSHOT/") + ); + // 分支级 libraries 里那条 mixin 不该混进记录（那是 ForgeGradle 开发环境用的）。 + assert!(!snapshots[0] + .libraries + .iter() + .any(|library| library.name.contains("mixin"))); +} + +#[test] +fn snapshot_url_comes_from_maven_metadata() { + let table = parse_versions(LITELOADER_VERSIONS).expect("解析"); + let entry = &table["1.12.2"][0]; + assert_eq!( + snapshot_artifact_url(entry, LITELOADER_METADATA).expect("应拼得出直链"), + "https://repo.mumfrey.com/content/repositories/snapshots/com/mumfrey/liteloader/1.12.2-SNAPSHOT/liteloader-1.12.2-20171128.144431-4-release.jar" + ); + + // 缺 ：报错，不猜一个指向 404 的直链。 + let broken = LITELOADER_METADATA.replace("4", ""); + let error = snapshot_artifact_url(entry, &broken).expect_err("缺字段必须报错"); + assert_eq!(error.kind(), LoaderErrorKind::Metadata); +} + +#[test] +fn build_release_synthesizes_launchwrapper_manifest() { + let table = parse_versions(LITELOADER_VERSIONS).expect("解析"); + let entry = find_entry(&table["1.12.2"], "1.12.2-snapshot").expect("版本号大小写不敏感"); + let url = snapshot_artifact_url(entry, LITELOADER_METADATA).expect("直链"); + let release = build_release("1.12.2", "1.12.2", entry, &url).expect("合成"); + + assert_eq!(release.version_id, "1.12.2-liteloader-1.12.2-SNAPSHOT"); + let json = &release.version_json; + assert_eq!( + json.main_class.as_deref(), + Some("net.minecraft.launchwrapper.Launch") + ); + // 父子链靠 arguments.game 追加，不写 minecraftArguments（写了会顶掉 Forge 的 tweakClass）。 + assert!(json.minecraft_arguments.is_none()); + let game: Vec = json + .arguments + .as_ref() + .expect("arguments 必须有") + .expand(&Default::default()) + .game; + assert_eq!( + game, + [ + "--tweakClass", + "com.mumfrey.liteloader.launch.LiteLoaderTweaker" + ] + ); + assert_eq!(json.inherits_from.as_deref(), Some("1.12.2")); + assert_eq!(json.jar.as_deref(), Some("1.12.2"), "jar 恒在原版那层"); + assert_eq!(json.version_type, Some(ReleaseType::Snapshot)); + + // 本体 jar 那一条：绝对直链 + maven 坐标（快照路径与坐标不一致，所以必须给 url）。 + let loader = json + .libraries + .as_ref() + .expect("libraries") + .iter() + .find(|library| library.name == "com.mumfrey:liteloader:1.12.2-SNAPSHOT") + .expect("缺本体库"); + assert_eq!( + loader + .downloads + .as_ref() + .and_then(|downloads| downloads.artifact.as_ref()) + .and_then(|artifact| artifact.url.as_deref()), + Some(url.as_str()) + ); + assert!(!release.requires_installer(), "LiteLoader 不跑任何外部进程"); + assert!(release.warnings.is_empty(), "{:?}", release.warnings); +} + +#[test] +fn synthesized_version_id_parses_back_to_liteloader() { + for (mc, loader_version) in [("1.12.2", "1.12.2-SNAPSHOT"), ("1.7.10", "1.7.10_04")] { + let id = LoaderKind::LiteLoader.version_id(mc, loader_version); + let parsed = InstanceLoader::parse(&id); + assert_eq!(parsed.kind, Wide::LiteLoader, "`{id}` 认错了家"); + assert_eq!(parsed.version, loader_version, "`{id}` 的版本段"); + } +} + +#[test] +fn missing_tweak_class_is_a_metadata_error() { + let table = parse_versions(LITELOADER_VERSIONS).expect("解析"); + let mut entry = table["1.7.10"][0].clone(); + entry.tweak_class = " ".to_string(); + let error = build_release("1.7.10", "1.7.10", &entry, "https://example.invalid/x.jar") + .expect_err("缺 tweakClass 必须报错"); + assert_eq!(error.kind(), LoaderErrorKind::Metadata); +} + +#[test] +fn default_entry_prefers_release_builds() { + let table = parse_versions(LITELOADER_VERSIONS).expect("解析"); + // 1.7.10 只有 release：取最新那条。 + assert_eq!( + default_entry(&table["1.7.10"]).map(|entry| entry.version.as_str()), + Some("1.7.10_04") + ); + // 1.12.2 只有快照：没有 release 可选时退回最新。 + assert_eq!( + default_entry(&table["1.12.2"]).map(|entry| entry.version.as_str()), + Some("1.12.2-SNAPSHOT") + ); +} + +#[test] +fn unknown_version_does_not_fall_back() { + let table = parse_versions(LITELOADER_VERSIONS).expect("解析"); + assert!(find_entry(&table["1.7.10"], "1.7.10_99").is_none()); + // 形状不符的表（顶层不是 versions）也要报 metadata，而不是当空表。 + let error = parse_versions(r#"{"versions": []}"#).expect_err("形状不符必须报错"); + assert_eq!(error.kind(), LoaderErrorKind::Metadata); +} + +/// 快照仓**固定**在 `repo.mumfrey.com/content/repositories/snapshots/`，不跟 `repo.url` 走。 +/// +/// 抓得住：1.10.2 的 `repo.url` 是 `…/repo/`，照它拼快照路径会 302 到 +/// `…/repositories/liteloader/…` 再 404（实测）。1.12.2 的 `repo.url` 恰好就是快照仓， +/// 所以只测 1.12.2 会漏掉这个 bug。 +#[test] +fn snapshot_repo_is_fixed_not_taken_from_repo_url() { + let table = parse_versions(LITELOADER_VERSIONS).expect("解析"); + let entries = &table["1.10.2"]; + let snapshot = entries + .iter() + .find(|entry| entry.snapshot) + .expect("1.10.2 应有快照条目"); + assert_eq!( + snapshot.snapshot_dir.as_deref(), + Some("https://repo.mumfrey.com/content/repositories/snapshots/com/mumfrey/liteloader/1.10.2-SNAPSHOT/") + ); + // release 条目仍走该版本自己的 `repo.url`（上游 `/repo/` 会 302 到真地址，引擎跟重定向）。 + let release = entries + .iter() + .find(|entry| !entry.snapshot) + .expect("1.10.2 应有 release 条目"); + assert_eq!( + release.url.as_deref(), + Some("https://dl.liteloader.com/repo/com/mumfrey/liteloader/1.10.2/liteloader-1.10.2.jar") + ); +} 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..17bfa9a --- /dev/null +++ b/crates/core/src/addon/loader/tests/maven.rs @@ -0,0 +1,137 @@ +//! 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（真实结构，只留 `` 列表）。 +const METADATA: &str = r#" + + net.neoforged + neoforge + + 26.1.2.125 + + 20.4.237 + 21.1.9 + 21.1.80 + 26.1.2.125 + 0.0.1-snapshot-1 + + +"#; + +#[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") + .expect("maven 族应有地址") + .ends_with("net/neoforged/forge/maven-metadata.xml")); + assert!(metadata_url(LoaderKind::NeoForge, "1.21.1") + .expect("maven 族应有地址") + .ends_with("net/neoforged/neoforge/maven-metadata.xml")); + assert!(metadata_url(LoaderKind::Forge, "1.20.1") + .expect("maven 族应有地址") + .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").expect("maven 族应有地址"), + "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").expect("maven 族应有地址"), + "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").expect("maven 族应有地址"), + "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..6beddab --- /dev/null +++ b/crates/core/src/addon/loader/tests/mod.rs @@ -0,0 +1,58 @@ +//! `addon::loader` 的单元测试：离线夹具对拍 + 镜像选择 + unsupported 判定。 +//! +//! 刻意**不打真实网络**：JSON 归一化、版本表挑选、镜像候选、计划形状全是纯计算。 +//! 夹具是官方响应的**裁剪版**（保留形状与关键字段，去掉几百行库与 base64 图标）。 + +mod fabric; +mod forge; +mod liteloader; +mod maven; +mod plan; +mod vocabulary; + +/// 裁剪过的 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..94b3ef3 --- /dev/null +++ b/crates/core/src/addon/loader/tests/plan.rs @@ -0,0 +1,198 @@ +//! 计划形状 / 继承链两级解析 / 镜像选择。 + +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(), + parent_installed: false, + }) + .expect("计划应可组"); + + 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::>() + ); + 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(), + parent_installed: false, + }) + .expect("计划应可组"); + 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(), + parent_installed: true, + }) + .expect("计划应可组"); + 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(), + parent_installed: true, + }) + .expect("计划应可组"); + 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(), + parent_installed: true, + }) + .expect("计划应可组"); + 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 = 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").expect("maven 族应有地址"); + 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").expect("maven 族应有地址"); + 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/loader/tests/vocabulary.rs b/crates/core/src/addon/loader/tests/vocabulary.rs new file mode 100644 index 0000000..e115bd1 --- /dev/null +++ b/crates/core/src/addon/loader/tests/vocabulary.rs @@ -0,0 +1,85 @@ +//! 安装侧词表与 `crate::game` 词表的对接：委派有没有接错、别名有没有漏进产出。 +//! +//! 词表本体（七个对外 id）在 `crate::game::loader`，这里只验**安装侧这一半**： +//! [`LoaderKind::as_str`] 委派给 core，[`LoaderKind::parse`] 委派 core 的解析并只多收一个 +//! Modrinth 输入别名。为什么放在安装侧的测试目录：这一半的存在理由是「装出来的版本 id 得 +//! 能被认回来」，那正好是生成端与解析端的接缝。 + +use crate::addon::loader::LoaderKind; +use crate::game::{InstanceLoader, LoaderKind as Wide}; + +/// `as_str` 是 core 词表的委派：五家装得上的一一对应，且绝不产出别名。 +/// +/// 抓得住：委派接错支（`Fabric` 映到 `Quilt`）；有人把 `as_str` 改回手写字面量并写错； +/// 有人让 `as_str` 产出 `neo-forge`（别名只进不出）；生成端 `--` 与解析端 +/// 脱节（装出来的 id 认不回同一家）。 +/// 抓不住：core 词表的字面值（那是 `game::loader` 的往返测试与 presenter 契约测试的职责）。 +#[test] +fn install_side_ids_are_delegated_to_the_core_vocabulary() { + let cases = [ + (LoaderKind::Fabric, Wide::Fabric), + (LoaderKind::Quilt, Wide::Quilt), + (LoaderKind::NeoForge, Wide::NeoForge), + (LoaderKind::Forge, Wide::Forge), + (LoaderKind::LiteLoader, Wide::LiteLoader), + ]; + for (install, wide) in cases { + assert_eq!( + install.as_str(), + wide.as_str(), + "{install:?} 的 id 没走 core 词表" + ); + assert_ne!(install.as_str(), "neo-forge", "别名只进不出"); + assert_eq!(LoaderKind::parse(install.as_str()), Some(install), "反查"); + + let id = install.version_id("1.20.4", "0.16.5"); + let parsed = InstanceLoader::parse(&id); + assert_eq!(parsed.kind.as_str(), install.as_str(), "`{id}` 认错了家"); + assert_eq!(parsed.version, "0.16.5", "`{id}` 的版本段"); + } +} + +/// 别名策略：`neo-forge` 只作为**输入**被接受（Modrinth 的拼法），产出永远是 `neoforge`。 +/// +/// 抓得住：别名被搬进词表（`as_str` 开始产出 `neo-forge`）；别名只认小写；安装侧顺手接受了 +/// 本启动器装不了的几家（原版 / OptiFine）。 +/// 抓不住：`neo-forge` 之外 Modrinth 以后可能再发明的拼法——没有样本可写。 +#[test] +fn modrinth_alias_is_input_only() { + for raw in ["neo-forge", "NEO-FORGE", " neo-forge "] { + assert_eq!( + LoaderKind::parse(raw), + Some(LoaderKind::NeoForge), + "`{raw}`" + ); + } + assert_eq!( + LoaderKind::NeoForge.as_str(), + "neoforge", + "产出不许带连字符" + ); + for raw in ["vanilla", "optifine", "", "rift"] { + assert_eq!(LoaderKind::parse(raw), None, "`{raw}` 不该被安装侧接受"); + } +} + +/// [`LoaderKind::all`] 是安装侧唯一还手写的清单（CF id 前缀匹配、CLI `--loader` 提示用）， +/// 它与 [`LoaderKind::from_core`] 认可的集合必须一致——不重抄字面量，直接对映射本身。 +/// +/// 抓得住：往 core 加一家**能装**的加载器，`from_core` 补了却忘了 `all()`（CLI 提示会漏一家、 +/// CF id 不认识它的前缀）；反过来 `all()` 里多一家而 `from_core` 说装不了。 +/// 抓不住：`all()` 的顺序（那是 CLI 提示的展示序，没有对外契约意义）。 +#[test] +fn installable_list_matches_the_from_core_mapping() { + let mut derived: Vec = Wide::ALL + .into_iter() + .filter_map(LoaderKind::from_core) + .collect(); + derived.sort_unstable(); + let mut listed = LoaderKind::all().to_vec(); + listed.sort_unstable(); + assert_eq!( + listed, derived, + "`LoaderKind::all()` 必须正好是 `from_core` 认可的那几家" + ); +} diff --git a/crates/core/src/addon/mod.rs b/crates/core/src/addon/mod.rs new file mode 100644 index 0000000..b5789e9 --- /dev/null +++ b/crates/core/src/addon/mod.rs @@ -0,0 +1,72 @@ +//! 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 **只导入不导出**（有意省略）。 +//! +//! - [`online`]（P2 · M162）：**在线内容源**——先只做匿名可用的 Modrinth（`/v2/search` / +//! `/v2/project` / `/v2/project/{id}/version` / `/v2/version_file/{hash}`）。网络出口只有 +//! `Transport` 一个 trait（生产实现走 `core::download` 的引擎）；下载走引擎并**复核 +//! sha1 + sha512**；远端条目补全按 sha512 反查 sha1，补不出照旧如实计数。 +//! CurseForge 需要 `x-api-key`，本轮不碰（见模块文档的「留的缝」）。 +//! +//! - [`mods`]（P2 · M224）：**本地 Mod 列表与启停**——`.disabled` / `.old` 后缀的唯一判据 +//! （导出扫描与导入计划两侧委派到这里）、`<实例运行目录>/mods/` 的单根列表、启停 = 在 +//! `mods/` 里改名（五条守卫、幂等、不覆盖）。 +//! +//! 规划中：CurseForge 客户端（§5）。 + +pub mod export; +pub mod import; +pub mod loader; +pub mod mods; +pub mod online; +pub mod pack; + +pub use export::{ + export_instance, ExportFile, ExportReport, ExportRequest, FileClass, FileReason, RemoteCatalog, + RemoteHit, +}; +pub use import::{ + import_pack, scan_pack, scan_pack_online, ConflictChoice, ConflictDecisions, ConflictFile, + ConflictPolicy, ImportConflict, ImportError, ImportErrorKind, ImportProgress, + ImportProgressSink, ImportReport, ImportRequest, ImportScan, ImportStage, ImportStatus, + ImportedFile, MissingFile, PackBaseline, PackFetcher, RejectedComponent, +}; +pub use loader::{ + LoaderError, LoaderErrorKind, LoaderInstallPlan, LoaderKind, LoaderPlanInput, LoaderRelease, + LoaderSource, LoaderSupport, +}; +pub use mods::{ + ModEntry, ModError, ModScan, ModSkip, ModToggle, SkipReason, SuffixVariant as ModSuffixVariant, + MODS_DIR, +}; +pub use online::{ + download_verified, ArtifactFetcher, ContentType, Downloaded, EngineArtifactFetcher, + EngineTransport, Modrinth, OnlineError, OnlineErrorKind, ProjectDetail, ProjectHit, SearchPage, + SearchQuery, SortIndex, Transport, Version, VersionFile, VersionQuery, MODRINTH_API, +}; +pub use pack::{ + EnvSupport, PackArchive, PackError, PackErrorKind, PackFile, PackFormat, PackLimits, + PackLoader, PackManifest, PackOverrides, PackRegistry, PackResult, PackSide, +}; + +#[cfg(test)] +pub(crate) mod temp; +#[cfg(test)] +mod tests; diff --git a/crates/core/src/addon/mods/error.rs b/crates/core/src/addon/mods/error.rs new file mode 100644 index 0000000..9fdaf62 --- /dev/null +++ b/crates/core/src/addon/mods/error.rs @@ -0,0 +1,92 @@ +//! 本地 Mod 读写的失败形状（CLI/UI 据此给具名原因，不折叠成一句「失败」）。 + +use std::fmt; +use std::path::PathBuf; + +/// 一次列目录 / 启停失败。 +#[derive(Debug)] +pub enum ModError { + /// 文件名不是**裸文件名**（含分隔符 / `..` / 盘符 / NUL）。 + /// + /// 判据直接复用整合包侧的七条路径规则（[`crate::addon::pack::path::normalize_file`]）， + /// 再要求结果里没有 `/`：启停只接受 `mods/` 下**直接**的一个文件， + /// 不收相对路径——那等于让 UI 决定落到哪个子目录。 + UnsafeName { + /// 调用方给的名字。 + file: String, + /// 人读原因。 + detail: String, + }, + /// `mods` 目录本身不可用：是符号链接 / 不是目录 / 读不了。 + /// + /// 符号链接**不跟随**：`/mods` 指到别处时，改名会落到实例目录之外。 + ModsDirUnusable { + /// 那个目录。 + dir: PathBuf, + /// 人读原因。 + detail: String, + }, + /// 要启停的文件不在 `mods/` 里。 + NotFound { + /// 文件名。 + file: String, + /// 找过的目录。 + dir: PathBuf, + }, + /// 目标存在但不是普通文件（目录 / 符号链接 / 设备）。 + NotARegularFile { + /// 文件名。 + file: String, + /// 人读原因。 + detail: String, + }, + /// 目标名字已被占用（**不覆盖**：那可能是另一个 mod）。 + Collision { + /// 原名字。 + file: String, + /// 想要的（已存在的）目标名。 + target: String, + /// 目录。 + dir: PathBuf, + }, + /// 改名本身失败（占用 / 权限 / 磁盘异常）。 + Rename { + /// 原名字。 + file: String, + /// 目标名。 + target: String, + /// 底层原因。 + detail: String, + }, +} + +impl fmt::Display for ModError { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + Self::UnsafeName { file, detail } => { + write!(f, "文件名不可用于启停（{file:?}）：{detail}") + } + Self::ModsDirUnusable { dir, detail } => { + write!(f, "mods 目录不可用（{}）：{detail}", dir.display()) + } + Self::NotFound { file, dir } => { + write!(f, "mods 目录里没有 {file}（{}）", dir.display()) + } + Self::NotARegularFile { file, detail } => { + write!(f, "{file} 不是普通文件：{detail}") + } + Self::Collision { file, target, dir } => write!( + f, + "{file} 改不成 {target}：同名文件已存在（{}）——不覆盖，请先处理那个文件", + dir.join(target).display() + ), + Self::Rename { + file, + target, + detail, + } => write!(f, "{file} → {target} 改名失败：{detail}"), + } + } +} + +impl std::error::Error for ModError {} diff --git a/crates/core/src/addon/mods/list.rs b/crates/core/src/addon/mods/list.rs new file mode 100644 index 0000000..9840d52 --- /dev/null +++ b/crates/core/src/addon/mods/list.rs @@ -0,0 +1,204 @@ +//! 列一个实例 `mods/` 目录（**只读**、只看这一个目录）。 +//! +//! # 单根语义（D20） +//! +//! 入口是**已经派生好的运行目录**（`game::isolation::derive_game_dir` 的结果），本模块只往下 +//! 取一层 `mods/`：不自己去猜游戏根、不做「隔离侧 + 共享侧合并」。派生是启动与列表**同一个** +//! 答案的唯一来源，第二处派生就是第二套真相。 +//! +//! # 收哪些条目 +//! +//! 与导出扫描同一条纪律：`mods/` 下**不按扩展名过滤**（`.jar` / `.jar.disabled` / `.zip` / +//! 认不出的后缀一律列出）。丢掉"我不认识的东西"正是用户点名不许的——启停开关对认不出的 +//! 文件同样有意义（禁用它 = 让游戏别加载它）。 +//! +//! 不收的东西只有三类，且都**逐条登记原因**（不是静默跳过）： +//! 符号链接（不跟随）、非普通文件（目录 / 设备）、名字过不了路径规则（[`crate::addon::pack::path`]）。 + +use std::path::{Path, PathBuf}; + +use super::error::ModError; +use super::suffix::{display_name, suffix_variant, SuffixVariant}; + +/// `mods` 目录名（游戏与社区一致的口径）。 +pub const MODS_DIR: &str = "mods"; + +/// 某个运行目录下的 `mods/`（不建、不检查——纯路径拼接）。 +#[must_use] +pub fn mods_dir(run_dir: &Path) -> PathBuf { + run_dir.join(MODS_DIR) +} + +/// 列表里的一条。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ModEntry { + /// 磁盘上的文件名（含 `.disabled` / `.old` 后缀，原样）。 + pub file: String, + /// 展示名（去掉两个后缀，不做 `-版本号` 猜解）。 + pub name: String, + /// 是否启用（`.disabled` 缺席即启用）。 + pub enabled: bool, + /// 字节数。 + pub bytes: u64, + /// 后缀变体（UI 用它区分"旧残留"）。 + pub variant: SuffixVariant, +} + +/// 没能进列表的一条。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ModSkip { + /// 文件名（读不到时给能拿到的原样串）。 + pub file: String, + /// 为什么没列。 + pub reason: SkipReason, +} + +/// 没列出来的原因。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum SkipReason { + /// 符号链接（不跟随：跟随会把实例外的东西算成实例内容）。 + SymbolicLink, + /// 不是普通文件（目录 / 设备 / 管道）。 + NotAFile, + /// 名字过不了路径规则（含 `\`、`:`、`..` 之类）。 + UnsafeName, + /// 元数据读不出来。 + Unreadable, +} + +/// 一次列目录的结果。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ModScan { + /// 被列的那个 `mods/` 目录。 + pub dir: PathBuf, + /// 目录存不存在（`false` = 这个实例还没装过 mod，不是错误）。 + pub exists: bool, + /// 列表（按展示名排序，大小写不敏感）。 + pub entries: Vec, + /// 跳过的条目与原因。 + pub skipped: Vec, +} + +impl ModScan { + /// 启用中的条数。 + #[must_use] + pub fn enabled_count(&self) -> usize { + self.entries.iter().filter(|entry| entry.enabled).count() + } + + /// 禁用中的条数。 + #[must_use] + pub fn disabled_count(&self) -> usize { + self.entries.len() - self.enabled_count() + } +} + +/// 列一个运行目录下的 `mods/`。 +/// +/// 目录不存在 → `exists = false` 的空结果（空实例不是错误）。 +/// +/// # Errors +/// +/// `mods` 存在但不可用（符号链接 / 不是目录 / 读不了）时给 [`ModError::ModsDirUnusable`]。 +pub fn scan(run_dir: &Path) -> Result { + let dir = mods_dir(run_dir); + let meta = match std::fs::symlink_metadata(&dir) { + Ok(meta) => meta, + Err(error) if error.kind() == std::io::ErrorKind::NotFound => { + return Ok(ModScan { + dir, + exists: false, + entries: Vec::new(), + skipped: Vec::new(), + }); + } + Err(error) => { + return Err(ModError::ModsDirUnusable { + dir, + detail: error.to_string(), + }); + } + }; + if meta.file_type().is_symlink() { + return Err(ModError::ModsDirUnusable { + dir, + detail: "是符号链接（不跟随：改名会落到实例目录之外）".to_string(), + }); + } + if !meta.is_dir() { + return Err(ModError::ModsDirUnusable { + dir, + detail: "不是目录".to_string(), + }); + } + + let read = std::fs::read_dir(&dir).map_err(|error| ModError::ModsDirUnusable { + dir: dir.clone(), + detail: error.to_string(), + })?; + let mut children: Vec<_> = + read.collect::, _>>() + .map_err(|error| ModError::ModsDirUnusable { + dir: dir.clone(), + detail: error.to_string(), + })?; + children.sort_by_key(std::fs::DirEntry::file_name); + + let mut entries = Vec::new(); + let mut skipped = Vec::new(); + for child in children { + let raw = child.file_name().to_string_lossy().to_string(); + let Ok(file_type) = child.file_type() else { + skipped.push(ModSkip { + file: raw, + reason: SkipReason::Unreadable, + }); + continue; + }; + if file_type.is_symlink() { + skipped.push(ModSkip { + file: raw, + reason: SkipReason::SymbolicLink, + }); + continue; + } + if !file_type.is_file() { + skipped.push(ModSkip { + file: raw, + reason: SkipReason::NotAFile, + }); + continue; + } + if crate::addon::pack::path::normalize_file(&raw).is_err() || raw.contains('/') { + skipped.push(ModSkip { + file: raw, + reason: SkipReason::UnsafeName, + }); + continue; + } + let bytes = child.metadata().map(|meta| meta.len()).unwrap_or(0); + entries.push(ModEntry { + name: display_name(&raw).to_string(), + enabled: !suffix_variant(&raw).is_disabled(), + variant: suffix_variant(&raw), + file: raw, + bytes, + }); + } + + // 展示名排序（大小写不敏感；同名时按磁盘名字典序兜底，保证两帧之间不抖）。 + entries.sort_by(|left, right| { + left.name + .to_lowercase() + .cmp(&right.name.to_lowercase()) + .then_with(|| left.file.cmp(&right.file)) + }); + skipped.sort_by(|left, right| left.file.cmp(&right.file)); + + Ok(ModScan { + dir, + exists: true, + entries, + skipped, + }) +} diff --git a/crates/core/src/addon/mods/mod.rs b/crates/core/src/addon/mods/mod.rs new file mode 100644 index 0000000..9fc67b1 --- /dev/null +++ b/crates/core/src/addon/mods/mod.rs @@ -0,0 +1,60 @@ +//! 本地 Mod 的**列表**与**启停**（M224 · MODTOGGLE）。 +//! +//! 设计定稿：`DevDocs/PlanDoc/08-mod-and-recommend.md` §3（三条结论原样落地）。 +//! +//! # 三层里的第一层 +//! +//! §3 的结论是「Mod 启停 = 新建三层（core 读写目录 + presenter DTO + 实例详情页），不是给 +//! 内容页接一个开关」，并特别点名**不要**给内容页加第五个 `ContentKind`（会打断 4 处穷尽 match）。 +//! 本模块就是那第一层，另外两层见 `crates/presenter/src/dto/mods.rs` 与 +//! `crates/app-iced/src/pages/instances/mods.rs`。 +//! +//! # 唯一 `.disabled` 判据 +//! +//! 收敛前仓里有两份逐字同构的后缀判据（`addon::export::scan::is_disabled_path` 与 +//! `addon::import::plan::paths::suffix_variant`）。M218 的要求是「做这块时第一步先收敛成一份， +//! 别让第三份出生」，所以判据只有 [`suffix`] 一处，导出/导入两侧改为**委派**（签名与行为不变， +//! 收敛 diff 为零行为变化）。启停要改写文件名，比"判一下"多两件事——保住原始大小写、保住 +//! `.old` 的位置——这两件也只能和判据同源，否则会出现「判禁用用一套、改名字用另一套」。 +//! +//! # 单根语义（D20） +//! +//! 入口一律是**派生好的运行目录**（[`crate::game::isolation::derive_game_dir`] 的结果）， +//! 本模块只碰 `/mods/`： +//! +//! - 不自己去猜游戏根，也不做「隔离侧 `versions//mods` + 共享侧 `.minecraft/mods` 合并」 +//! 这种双根视图——派生是启动与列表**同一个**答案的唯一来源； +//! - 只往下取一层：`mods/` 下的子目录不递归（游戏也不递归）； +//! - `mods/` 本身是符号链接时**拒绝**（不跟随），否则改名会落到实例目录之外。 +//! +//! # 模块 +//! +//! | 文件 | 职责 | +//! |---|---| +//! | [`suffix`] | `.disabled` / `.old` 的唯一判据与改名目标名（含四态枚举） | +//! | [`list`] | 列 `/mods/`（只读、逐条登记跳过原因） | +//! | [`toggle`] | 启停 = 在 `mods/` 里改名（五条守卫、幂等、不覆盖） | +//! +//! # 已知边界 +//! +//! - **不判断游戏是否在跑**：进程正持有这些 jar（Windows 上 rename 会失败），失败按 +//! [`error::ModError::Rename`] 如实报出来。要不要在上层挡「运行中不许改」是宿主层的策略 +//! （presenter 侧已挡，见 `host::mods`）。 +//! - **不解析 jar**：列表给的是文件名，`-版本号` 猜解仍归 `diagnose::environment::ModRecord`， +//! 这里不复制第二份启发式。 + +mod error; +mod list; +mod suffix; +mod toggle; + +pub use error::ModError; +pub use list::{mods_dir, scan, ModEntry, ModScan, ModSkip, SkipReason, MODS_DIR}; +pub use suffix::{ + disabled_name, display_name, enabled_name, is_disabled_path, renamed_for, suffix_variant, + SuffixVariant, DISABLED_SUFFIX, OLD_SUFFIX, +}; +pub use toggle::{ensure_dir, set_enabled, ModToggle}; + +#[cfg(test)] +mod tests; diff --git a/crates/core/src/addon/mods/suffix.rs b/crates/core/src/addon/mods/suffix.rs new file mode 100644 index 0000000..b24052f --- /dev/null +++ b/crates/core/src/addon/mods/suffix.rs @@ -0,0 +1,263 @@ +//! `.disabled` / `.old` 后缀的**唯一判据**（M224 · MODTOGGLE）。 +//! +//! # 为什么这里是一份而不是三份 +//! +//! 收敛前仓里有两份同构实现，各自 lowercase → 剥 `.old` → `ends_with(".disabled")`： +//! +//! | 位置 | 形状 | 用途 | +//! |---|---|---| +//! | `addon::export::scan::is_disabled_path` | 只给 bool | 导出扫描判禁用位 | +//! | `addon::import::plan::paths::suffix_variant` | 四态枚举 | 导入计划打注记 | +//! +//! 两份逐字同构，而 M218 的结论是「做启停时第一步先收敛成一份，别让第三份出生」 +//! （`DevDocs/PlanDoc/08-mod-and-recommend.md` §3）。启停要**改写**文件名，比"判一下"多两件事： +//! ①必须保住原始大小写（`X.JAR.DISABLED` 禁用后不能变全小写）；②必须保住 `.old` 的位置 +//! （`.disabled` 只能出现在 `.old` **之前**，否则 [`suffix_variant`] 认不出来）。 +//! +//! 所以本模块是唯一出口：判据（[`suffix_variant`] / [`is_disabled_path`]）与改写目标名 +//! （[`renamed_for`]）用**同一套剥离逻辑**，不会出现「判禁用用一套、改名字用另一套」。 +//! 导出与导入两侧改为委派到本模块（函数名与签名保持不变）。 +//! +//! # 认哪些形状（写死四种） +//! +//! | 磁盘上的名字 | 变体 | 禁用 | `.old` | +//! |---|---|---|---| +//! | `x.jar` | [`SuffixVariant::Plain`] | ❌ | ❌ | +//! | `x.jar.disabled` | [`SuffixVariant::Disabled`] | ✅ | ❌ | +//! | `x.jar.old` | [`SuffixVariant::Old`] | ❌ | ✅ | +//! | `x.jar.disabled.old` | [`SuffixVariant::DisabledOld`] | ✅ | ✅ | +//! +//! 大小写不敏感（Windows 上 `X.JAR.DISABLED` 与 `x.jar.disabled` 是同一个文件）；`.old` 只 +//! 识别与保留（不清除、不改名——它是 HMCL 生态的旧版本残留，删掉等于替用户做决定）。 + +/// 禁用位的路径后缀（官方 Modrinth 导出的表达，也是唯一跨启动器保真的那条）。 +pub const DISABLED_SUFFIX: &str = ".disabled"; + +/// 旧版本残留的路径后缀（只识别与保留）。 +pub const OLD_SUFFIX: &str = ".old"; + +/// 路径后缀变体（`.disabled` / `.old` 的四种组合）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +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_SUFFIX).unwrap_or(&lowered); + let old = stripped.len() != lowered.len(); + let disabled = stripped.ends_with(DISABLED_SUFFIX); + match (disabled, old) { + (false, false) => SuffixVariant::Plain, + (true, false) => SuffixVariant::Disabled, + (false, true) => SuffixVariant::Old, + (true, true) => SuffixVariant::DisabledOld, + } +} + +/// 路径后缀是否带 `.disabled`（允许 `x.jar.disabled.old` 这种"禁用 + 旧残留"组合）。 +#[must_use] +pub fn is_disabled_path(path: &str) -> bool { + suffix_variant(path).is_disabled() +} + +/// `enabled = true` 时该改成什么名字（`None` = 已经是启用态，不用动）。 +/// +/// `x.jar.disabled` → `x.jar`；`x.jar.disabled.old` → `x.jar.old`（`.old` 原位保留）。 +/// 原始大小写按**逐字符比较**剥掉后缀，所以 `X.JAR.DISABLED` → `X.JAR`，不会被整串小写化。 +#[must_use] +pub fn enabled_name(name: &str) -> Option { + let trimmed = name.trim_end(); + // **先剥 `.old` 再剥 `.disabled`**：反过来会漏 `x.jar.disabled.old`（结尾是 `.old`， + // 直接找结尾的 `.disabled` 找不到 ⇒ 明明禁用着却说"已是启用态"）。这一条由 + // `toggling_round_trips_every_variant` / `enabling_only_strips_the_disabled_suffix` 钉住。 + let (body, old) = match strip_ascii_ci(trimmed, OLD_SUFFIX) { + Some(base) => (base, Some(&trimmed[base.len()..])), + None => (trimmed, None), + }; + let stripped = strip_ascii_ci(body, DISABLED_SUFFIX)?; + // 剥完只剩空串或只剩 `.old` 都不是文件名（`.disabled` / `.old.disabled` 这种畸形）。 + if stripped.is_empty() || stripped.eq_ignore_ascii_case(OLD_SUFFIX) { + return None; + } + Some(match old { + Some(old) => format!("{stripped}{old}"), + None => stripped.to_string(), + }) +} + +/// `enabled = false` 时该改成什么名字（`None` = 已经是禁用态，不用动）。 +/// +/// `x.jar` → `x.jar.disabled`；`x.jar.old` → `x.jar.disabled.old`——`.disabled` **插在** `.old` +/// 之前，否则 [`suffix_variant`] 读回来是 `Old`（"有旧残留但没禁用"），禁用位就丢了。 +#[must_use] +pub fn disabled_name(name: &str) -> Option { + let trimmed = name.trim_end(); + if trimmed.is_empty() { + return None; + } + if suffix_variant(trimmed).is_disabled() { + return None; + } + // 只认原串里那个 `.old`（大小写可能不同），按字节位置插进去，保住其余部分原样。 + if let Some(base) = strip_ascii_ci(trimmed, OLD_SUFFIX) { + if base.is_empty() { + return None; + } + return Some(format!("{base}{DISABLED_SUFFIX}{OLD_SUFFIX}")); + } + Some(format!("{trimmed}{DISABLED_SUFFIX}")) +} + +/// 启停后应当落成的文件名（`None` = 已经是这个状态，无需 rename）。 +#[must_use] +pub fn renamed_for(name: &str, enabled: bool) -> Option { + if enabled { + enabled_name(name) + } else { + disabled_name(name) + } +} + +/// 展示名（去掉 `.disabled` / `.old` 两个后缀，其余原样）。 +/// +/// **不**做 `-版本号` 的猜解：那是 `diagnose::environment::ModRecord` 的活，这里再猜一次就是 +/// 第二份启发式。列表要的是"这个文件叫什么"，不是"它可能是哪个 mod"。 +#[must_use] +pub fn display_name(name: &str) -> &str { + let trimmed = name.trim_end(); + // 与 [`enabled_name`] 同一个顺序：先 `.old`、再 `.disabled`（`x.jar.disabled.old` 两个都要剥）。 + let without_old = strip_ascii_ci(trimmed, OLD_SUFFIX).unwrap_or(trimmed); + strip_ascii_ci(without_old, DISABLED_SUFFIX).unwrap_or(without_old) +} + +/// 去掉**结尾**的 ASCII 后缀（大小写不敏感），保住前半段原始大小写。 +fn strip_ascii_ci<'a>(text: &'a str, suffix: &str) -> Option<&'a str> { + let cut = text.len().checked_sub(suffix.len())?; + if !text.is_char_boundary(cut) { + return None; + } + text.get(cut..) + .filter(|tail| tail.eq_ignore_ascii_case(suffix)) + .map(|_| &text[..cut]) +} + +#[cfg(test)] +mod tests { + use super::*; + + /// 四种形状都认得，且禁用位只看 `.disabled`（`.old` 单独出现不是禁用）。 + #[test] + fn recognises_four_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!(is_disabled_path("mods/x.jar.disabled")); + assert!(is_disabled_path("mods/x.jar.disabled.old")); + assert!(!is_disabled_path("mods/x.jar.old")); + assert!(!is_disabled_path("mods/x.jar")); + } + + /// 大小写不敏感（Windows 上 `X.JAR.DISABLED` 就是禁用），尾随空白不算名字的一部分。 + #[test] + fn suffix_matching_ignores_ascii_case() { + assert_eq!(suffix_variant("X.JAR.DISABLED"), SuffixVariant::Disabled); + assert_eq!(suffix_variant("X.Disabled.Old"), SuffixVariant::DisabledOld); + assert_eq!(suffix_variant("x.jar.disabled \n"), SuffixVariant::Disabled); + // 不是子串匹配：`.disabled` 必须真在结尾。 + assert_eq!(suffix_variant("x.disabled.jar"), SuffixVariant::Plain); + assert_eq!(suffix_variant("x.jar.notdisabled"), SuffixVariant::Plain); + } + + /// 启用 = 剥 `.disabled`，`.old` 原位保留，**原始大小写不动**。 + #[test] + fn enabling_only_strips_the_disabled_suffix() { + assert_eq!(enabled_name("x.jar.disabled").as_deref(), Some("x.jar")); + assert_eq!( + enabled_name("x.jar.disabled.old").as_deref(), + Some("x.jar.old") + ); + assert_eq!(enabled_name("X.JAR.DISABLED").as_deref(), Some("X.JAR")); + // 已经是启用态 / 只剩畸形后缀 ⇒ None（不猜、不改）。 + assert_eq!(enabled_name("x.jar"), None); + assert_eq!(enabled_name(".disabled"), None); + assert_eq!(enabled_name(".old.disabled"), None); + } + + /// 禁用 = 把 `.disabled` **插在** `.old` 之前（插在后面判据读不回来）。 + #[test] + fn disabling_inserts_before_the_old_suffix() { + assert_eq!(disabled_name("x.jar").as_deref(), Some("x.jar.disabled")); + assert_eq!( + disabled_name("x.jar.old").as_deref(), + Some("x.jar.disabled.old") + ); + assert_eq!( + disabled_name("X.JAR.OLD").as_deref(), + Some("X.JAR.disabled.old") + ); + assert_eq!(disabled_name("x.jar.disabled"), None); + assert_eq!(disabled_name("x.jar.disabled.old"), None); + assert_eq!(disabled_name(""), None); + assert_eq!(disabled_name(".old"), None); + } + + /// 两个方向互为逆（同一条剥离逻辑的自证）：往返回来名字一模一样。 + #[test] + fn toggling_round_trips_every_variant() { + for plain in ["x.jar", "X.JAR", "风.jar", "a.b.c"] { + let off = renamed_for(plain, false).expect("禁用目标名"); + assert_eq!(suffix_variant(&off), SuffixVariant::Disabled); + assert_eq!(renamed_for(&off, true).as_deref(), Some(plain)); + } + // `.old` 变体往返也不掉 `.old`。 + let off = renamed_for("x.jar.old", false).expect("禁用目标名"); + assert_eq!(off, "x.jar.disabled.old"); + assert_eq!(renamed_for(&off, true).as_deref(), Some("x.jar.old")); + // 已经在目标状态 ⇒ None（幂等，不产生多余 rename）。 + assert_eq!(renamed_for("x.jar", true), None); + assert_eq!(renamed_for("x.jar.disabled", false), None); + } + + /// 展示名剥两个后缀，但**不**猜 `-版本号`。 + #[test] + fn display_name_strips_suffixes_only() { + assert_eq!( + display_name("sodium-0.5.8.jar.disabled"), + "sodium-0.5.8.jar" + ); + assert_eq!(display_name("x.jar.disabled.old"), "x.jar"); + assert_eq!(display_name("jei.jar"), "jei.jar"); + assert_eq!(display_name("X.JAR.DISABLED"), "X.JAR"); + } +} diff --git a/crates/core/src/addon/mods/tests.rs b/crates/core/src/addon/mods/tests.rs new file mode 100644 index 0000000..41c186f --- /dev/null +++ b/crates/core/src/addon/mods/tests.rs @@ -0,0 +1,254 @@ +//! 列表与启停的用例：**真的建盘上文件**再读回来（不 mock 文件系统）。 +//! +//! 每条用例都写在「抓得住什么 / 抓不住什么」的口径里：抓得住的是判据与守卫本身， +//! 抓不住的是 Windows 与 Linux 上 rename 的细节差异（那条靠真实运行，见 handoff）。 + +use std::path::Path; + +use super::suffix::SuffixVariant; +use super::*; +use crate::addon::temp::TempRoot; + +/// 建一个运行目录 + `mods/`，并把给定文件写进去。 +fn fixture(tag: &str, files: &[(&str, &[u8])]) -> TempRoot { + let root = TempRoot::under(tag, "run"); + let mods = mods_dir(&root); + std::fs::create_dir_all(&mods).expect("建 mods"); + for (name, body) in files { + std::fs::write(mods.join(name), body).expect("写 mod 文件"); + } + root +} + +/// 列目录：四种后缀变体都认、禁用位只看 `.disabled`、目录不进列表。 +#[test] +fn scan_lists_every_variant_and_skips_directories() { + let root = fixture( + "mods-scan", + &[ + ("sodium.jar", b"a"), + ("jei.jar.disabled", b"bb"), + ("opt.jar.old", b"ccc"), + ("aether.jar.disabled.old", b"dddd"), + ("notes.txt", b"whatever"), + ], + ); + std::fs::create_dir(root.join("mods/sub")).expect("建子目录"); + + let scan = scan(&root).expect("列目录"); + assert!(scan.exists); + assert_eq!(scan.dir, root.join("mods")); + + let files: Vec<&str> = scan + .entries + .iter() + .map(|entry| entry.file.as_str()) + .collect(); + assert_eq!( + files, + [ + "aether.jar.disabled.old", + "jei.jar.disabled", + "notes.txt", + "opt.jar.old", + "sodium.jar" + ] + ); + + let entry = |file: &str| { + scan.entries + .iter() + .find(|entry| entry.file == file) + .unwrap_or_else(|| panic!("{file} 不在列表里")) + }; + assert!(entry("sodium.jar").enabled); + assert!(!entry("jei.jar.disabled").enabled); + assert!(entry("opt.jar.old").enabled, "`.old` 单独出现不是禁用"); + assert!(!entry("aether.jar.disabled.old").enabled); + // 展示名剥两个后缀（不做 -版本号 猜解）。 + assert_eq!(entry("aether.jar.disabled.old").name, "aether.jar"); + assert_eq!(entry("sodium.jar").variant, SuffixVariant::Plain); + assert_eq!(entry("jei.jar.disabled").bytes, 2); + + assert_eq!(scan.skipped.len(), 1); + assert_eq!(scan.skipped[0].file, "sub"); + assert_eq!(scan.skipped[0].reason, SkipReason::NotAFile); + assert_eq!(scan.enabled_count(), 3); + assert_eq!(scan.disabled_count(), 2); +} + +/// 空实例（没有 `mods/`）不是错误：`exists = false` 的空结果。 +#[test] +fn scan_treats_a_missing_mods_dir_as_empty() { + let root = TempRoot::under("mods-empty", "run"); + let scan = scan(&root).expect("列目录"); + assert!(!scan.exists); + assert!(scan.entries.is_empty()); + assert!(scan.skipped.is_empty()); +} + +/// `mods` 是符号链接就拒（不跟随）。Windows 上建目录链接要特权，建不出来就跳过这一条。 +#[test] +fn scan_refuses_a_symlinked_mods_dir() { + let root = TempRoot::under("mods-link", "run"); + let outside = root.join("elsewhere"); + std::fs::create_dir_all(&outside).expect("建外部目录"); + std::fs::write(outside.join("x.jar"), b"x").expect("写外部文件"); + + let linked = link_dir(&outside, &mods_dir(&root)); + if !linked { + eprintln!("[skip] 本机建不出目录符号链接（Windows 需要开发者模式/特权）"); + return; + } + + let error = scan(&root).expect_err("必须拒绝符号链接"); + assert!(matches!(error, ModError::ModsDirUnusable { .. }), "{error}"); + // 启停同样拒（同一条守卫，不另记一遍）。 + let error = set_enabled(&root, "x.jar", false).expect_err("必须拒绝符号链接"); + assert!(matches!(error, ModError::ModsDirUnusable { .. }), "{error}"); +} + +/// 启停往返：改名真的发生、读回来状态对、重复点幂等。 +#[test] +fn toggling_renames_on_disk_and_is_idempotent() { + let root = fixture("mods-toggle", &[("sodium.jar", b"jar")]); + + let off = set_enabled(&root, "sodium.jar", false).expect("禁用"); + assert!(off.renamed); + assert_eq!(off.to, "sodium.jar.disabled"); + assert!(!off.enabled); + assert!(root.join("mods/sodium.jar.disabled").is_file()); + assert!(!root.join("mods/sodium.jar").exists()); + + // 再禁一次：不是错误，也不改名。 + let again = set_enabled(&root, "sodium.jar.disabled", false).expect("幂等"); + assert!(!again.renamed); + assert_eq!(again.from, again.to); + assert!(!again.enabled); + + // 启用回来：名字与字节都回到原样。 + let on = set_enabled(&root, "sodium.jar.disabled", true).expect("启用"); + assert!(on.renamed); + assert_eq!(on.to, "sodium.jar"); + assert!(on.enabled); + assert_eq!( + std::fs::read(root.join("mods/sodium.jar")).expect("读回"), + b"jar" + ); + + let scan = scan(&root).expect("列目录"); + assert_eq!(scan.entries.len(), 1); + assert!(scan.entries[0].enabled); +} + +/// `.disabled` 只能插在 `.old` **之前**，否则读回来丢禁用位（往返用例抓的就是这个）。 +#[test] +fn toggling_keeps_the_old_suffix_in_place() { + let root = fixture("mods-old", &[("jei.jar.old", b"old")]); + + let off = set_enabled(&root, "jei.jar.old", false).expect("禁用"); + assert_eq!(off.to, "jei.jar.disabled.old"); + let listed = scan(&root).expect("列目录"); + assert_eq!(listed.entries[0].variant, SuffixVariant::DisabledOld); + assert!(!listed.entries[0].enabled, "禁用位被 `.old` 吃掉了"); + + let on = set_enabled(&root, "jei.jar.disabled.old", true).expect("启用"); + assert_eq!(on.to, "jei.jar.old"); + assert_eq!( + scan(&root).expect("列目录").entries[0].variant, + SuffixVariant::Old + ); +} + +/// 目标名已被占用 ⇒ 报冲突，**不覆盖**那个文件。 +#[test] +fn toggling_refuses_to_overwrite_an_existing_file() { + let root = fixture( + "mods-collision", + &[("x.jar", b"one"), ("x.jar.disabled", b"two")], + ); + + let error = set_enabled(&root, "x.jar", false).expect_err("必须报冲突"); + assert!(matches!(error, ModError::Collision { .. }), "{error}"); + // 两个文件都还在、内容没被踩。 + assert_eq!( + std::fs::read(root.join("mods/x.jar")).expect("读 a"), + b"one" + ); + assert_eq!( + std::fs::read(root.join("mods/x.jar.disabled")).expect("读 b"), + b"two" + ); +} + +/// 路径类名字一律拒：启停只接受 `mods/` 下的裸文件名。 +#[test] +fn toggling_rejects_anything_that_is_not_a_bare_file_name() { + let root = fixture("mods-names", &[("x.jar", b"x")]); + for bad in [ + "", + "../x.jar", + "mods/x.jar", + "sub/x.jar", + r"mods\x.jar", + "C:/x.jar", + ".hidden/../x.jar", + ] { + let error = set_enabled(&root, bad, false) + .err() + .unwrap_or_else(|| panic!("{bad:?} 必须被拒")); + assert!( + matches!( + error, + ModError::UnsafeName { .. } | ModError::NotFound { .. } + ), + "{bad:?} → {error}" + ); + } + // 越界改名一次都没发生。 + assert!(root.join("mods/x.jar").is_file()); +} + +/// 不存在的文件、目录、符号链接都不是"可启停的 mod"。 +#[test] +fn toggling_refuses_missing_and_non_file_targets() { + let root = fixture("mods-targets", &[("x.jar", b"x")]); + std::fs::create_dir(root.join("mods/adir")).expect("建目录"); + + let missing = set_enabled(&root, "nope.jar", false).expect_err("不存在的必须报"); + assert!(matches!(missing, ModError::NotFound { .. }), "{missing}"); + + let dir = set_enabled(&root, "adir", false).expect_err("目录必须报"); + assert!(matches!(dir, ModError::NotARegularFile { .. }), "{dir}"); + assert!(root.join("mods/adir").is_dir(), "目录被改名了"); +} + +/// 没有 `mods/` 时启停报「目录不可用」（不替用户建目录——建目录是装 mod 的事）。 +#[test] +fn toggling_requires_an_existing_mods_dir() { + let root = TempRoot::under("mods-nodir", "run"); + let error = set_enabled(&root, "x.jar", false).expect_err("没有 mods 目录"); + assert!(matches!(error, ModError::ModsDirUnusable { .. }), "{error}"); + assert!(!root.join("mods").exists(), "启停不该顺手建目录"); + + // `ensure_dir` 才是建目录那条路（装 mod 用）。 + ensure_dir(&root).expect("建 mods"); + assert!(root.join("mods").is_dir()); +} + +/// 建目录链接：Windows 上可能没特权，返回是否建成（用例据此决定跳不跳）。 +fn link_dir(target: &Path, link: &Path) -> bool { + #[cfg(unix)] + { + std::os::unix::fs::symlink(target, link).is_ok() + } + #[cfg(windows)] + { + std::os::windows::fs::symlink_dir(target, link).is_ok() + } + #[cfg(not(any(unix, windows)))] + { + let _ = (target, link); + false + } +} diff --git a/crates/core/src/addon/mods/toggle.rs b/crates/core/src/addon/mods/toggle.rs new file mode 100644 index 0000000..9e44241 --- /dev/null +++ b/crates/core/src/addon/mods/toggle.rs @@ -0,0 +1,166 @@ +//! 启停一个 mod：**在 `mods/` 里改名**（`.disabled` 后缀就是禁用位）。 +//! +//! # 为什么是改名而不是写配置文件 +//! +//! 游戏本身不读任何"禁用列表"——它只加载 `mods/*.jar`。`.disabled` 后缀让文件**不再匹配** +//! 加载器的 glob，于是"禁用"是**文件系统状态**：换启动器、换机器、手动 `git checkout` 之后 +//! 依然成立。这也是 Modrinth 官方导出表达禁用位的唯一方式（见 +//! [`crate::addon::pack::manifest::PackFile::disabled`]）。 +//! +//! # 五条守卫（都不猜、都不覆盖） +//! +//! | 守卫 | 理由 | +//! |---|---| +//! | 只收**裸文件名**（过七条路径规则且不含 `/`） | 启停不接受相对路径，否则 UI 能指挥落点 | +//! | `mods/` 是符号链接就拒 | 改名会落到实例目录之外 | +//! | 目标必须是**普通文件**（非目录 / 非链接） | 改一个目录或链接不是"启停一个 mod" | +//! | 目标名已存在就拒（[`ModError::Collision`]） | 覆盖掉的是**另一个 mod**，用户没同意 | +//! | rename 不做跨盘兜底（不 copy+delete） | copy 半截失败会留下两个文件，语义比报错更差 | +//! +//! # 幂等 +//! +//! 「已经启用还要启用」不是错误：返回 `renamed = false` 的成功结果（UI 的开关重复点不会 +//! 变成红字）。这一条由 [`super::suffix::renamed_for`] 的 `None` 表达。 + +use std::path::{Path, PathBuf}; + +use super::error::ModError; +use super::list::mods_dir; +use super::suffix::{is_disabled_path, renamed_for}; + +/// 一次启停的结果（`from == to` 且 `renamed == false` ⇒ 本来就是那个状态）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ModToggle { + /// 原文件名的磁盘名（含后缀）。 + pub from: String, + /// 改名后的磁盘名（没改名时与 `from` 相同）。 + pub to: String, + /// 这一步之后的启用状态。 + pub enabled: bool, + /// 是否真的在磁盘上改了名。 + pub renamed: bool, +} + +/// 把 `mods/` 下的某个文件切到 `enabled` 状态（改名）。 +/// +/// # Errors +/// +/// 见模块文档的五条守卫：[`ModError::UnsafeName`] / [`ModError::ModsDirUnusable`] / +/// [`ModError::NotFound`] / [`ModError::NotARegularFile`] / [`ModError::Collision`] / +/// [`ModError::Rename`]。 +pub fn set_enabled(run_dir: &Path, file: &str, enabled: bool) -> Result { + let name = bare_name(file)?; + let dir = mods_dir(run_dir); + usable_dir(&dir)?; + + let from_path = dir.join(&name); + let meta = std::fs::symlink_metadata(&from_path).map_err(|error| { + if error.kind() == std::io::ErrorKind::NotFound { + ModError::NotFound { + file: name.clone(), + dir: dir.clone(), + } + } else { + ModError::NotARegularFile { + file: name.clone(), + detail: error.to_string(), + } + } + })?; + if meta.file_type().is_symlink() || !meta.is_file() { + return Err(ModError::NotARegularFile { + file: name.clone(), + detail: "不是普通文件（符号链接 / 目录 / 设备都不动）".to_string(), + }); + } + + let Some(target) = renamed_for(&name, enabled) else { + // 已经是目标状态：幂等返回，不产生多余 rename（Windows 上同大小写改名还可能失败）。 + return Ok(ModToggle { + enabled: !is_disabled_path(&name), + from: name.clone(), + to: name, + renamed: false, + }); + }; + + let to_path = dir.join(&target); + if std::fs::symlink_metadata(&to_path).is_ok() { + return Err(ModError::Collision { + file: name, + target, + dir, + }); + } + + std::fs::rename(&from_path, &to_path).map_err(|error| ModError::Rename { + file: name.clone(), + target: target.clone(), + detail: error.to_string(), + })?; + + Ok(ModToggle { + from: name, + to: target, + enabled, + renamed: true, + }) +} + +/// 文件名必须是**裸文件名**：先过整合包侧的七条路径规则，再要求没有 `/`。 +fn bare_name(file: &str) -> Result { + let trimmed = file.trim(); + let normalized = crate::addon::pack::path::normalize_file(trimmed).map_err(|error| { + ModError::UnsafeName { + file: file.to_string(), + detail: error.to_string(), + } + })?; + if normalized.contains('/') || normalized != trimmed { + return Err(ModError::UnsafeName { + file: file.to_string(), + detail: "只接受 mods/ 下的裸文件名（不含路径分隔符、不做归一）".to_string(), + }); + } + Ok(normalized) +} + +/// `mods/` 必须存在、是目录、且**不是符号链接**。 +fn usable_dir(dir: &Path) -> Result<(), ModError> { + let meta = std::fs::symlink_metadata(dir).map_err(|error| ModError::ModsDirUnusable { + dir: dir.to_path_buf(), + detail: if error.kind() == std::io::ErrorKind::NotFound { + "不存在（这个实例还没有 mods 目录）".to_string() + } else { + error.to_string() + }, + })?; + if meta.file_type().is_symlink() { + return Err(ModError::ModsDirUnusable { + dir: dir.to_path_buf(), + detail: "是符号链接（不跟随：改名会落到实例目录之外）".to_string(), + }); + } + if !meta.is_dir() { + return Err(ModError::ModsDirUnusable { + dir: dir.to_path_buf(), + detail: "不是目录".to_string(), + }); + } + Ok(()) +} + +/// 建 `mods/` 目录（**只在装 mod 时用**；列目录/启停不建）。 +/// +/// # Errors +/// +/// 建不出来 / 建出来是符号链接以外的怪形状时给 [`ModError::ModsDirUnusable`]。 +pub fn ensure_dir(run_dir: &Path) -> Result { + let dir = mods_dir(run_dir); + std::fs::create_dir_all(&dir).map_err(|error| ModError::ModsDirUnusable { + dir: dir.clone(), + detail: error.to_string(), + })?; + usable_dir(&dir)?; + Ok(dir) +} diff --git a/crates/core/src/addon/online/complete.rs b/crates/core/src/addon/online/complete.rs new file mode 100644 index 0000000..98d64ae --- /dev/null +++ b/crates/core/src/addon/online/complete.rs @@ -0,0 +1,119 @@ +//! 按摘要认文件：[`identity_of`] 判断「站点返回的这个版本里，哪个文件才是我们要的那个」。 +//! +//! # 为什么只留这一件 +//! +//! 生产上的补全循环只有**一处**：`crate::addon::import::complete`（它走 `PackFetcher`， +//! 因此能区分「站点不认得这个摘要（404）」与「没联网（Offline）」，这决定了要不要提前收工）。 +//! 这里曾经还有一份 `complete_files` 循环，r2 复审指出「看着像生产代码其实没人调、两套循环 +//! 迟早漂移」⇒ 已删除。本文件只留**判定**，两个调用点共用： +//! +//! | 调用方 | 用它做什么 | +//! |--------|------------| +//! | `addon::import::fetch`（生产补全） | 按 sha512 反查回来的版本 → 取出那份文件的官方 sha1/大小/直链 | +//! | `online::complete` 的用例 | 钉住「对不上就不许用」 | +//! +//! # 一致性比「有值」重要 +//! +//! 站点返回的版本里可能有多个文件（`primary` 之外还有 `sources.jar`）。只在 +//! **`hashes.sha512` 与请求值逐字相同**的那条上取 `sha1`；一个都对不上就返回 `None` +//! ——宁可让上游记「补不出」，也不把别的东西的摘要装进来。 + +use super::model::Version; + +/// 从版本里找出**摘要对得上**的那个文件，取出它的 sha1/大小/地址。 +/// +/// `None` = 这个版本里没有任何文件的 sha512 与请求值相同（站点数据不一致 / 版本被换过）， +/// 或者对上的那条没有 sha1 可用。 +#[must_use] +pub fn identity_of(version: &Version, sha512: &str) -> Option { + let file = version.files.iter().find(|file| { + file.sha512() + .is_some_and(|hex| hex.eq_ignore_ascii_case(sha512)) + })?; + let sha1 = file.sha1().map(str::to_string)?; + Some(Identity { + sha1, + size: (file.size > 0).then_some(file.size), + url: (!file.url.trim().is_empty()).then(|| file.url.clone()), + }) +} + +/// 补全出来的一份身份。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Identity { + /// 站点给的 SHA-1 + pub sha1: String, + /// 站点给的字节数（`0` = 没给） + pub size: Option, + /// 站点给的直链（`None` = 也没给） + pub url: Option, +} + +#[cfg(test)] +mod tests { + use super::identity_of; + use crate::addon::online::model::{Version, VersionFile}; + + fn version(files: Vec) -> Version { + Version { + id: "v1".to_string(), + project_id: "p1".to_string(), + files, + ..Version::default() + } + } + + fn file(sha1: Option<&str>, sha512: &str, primary: bool) -> VersionFile { + let mut file = VersionFile { + url: "https://cdn.modrinth.com/data/p1/v1/a.jar".to_string(), + filename: "a.jar".to_string(), + size: 2048, + primary, + ..VersionFile::default() + }; + file.hashes.insert("sha512".to_string(), sha512.to_string()); + if let Some(sha1) = sha1 { + file.hashes.insert("sha1".to_string(), sha1.to_string()); + } + file + } + + #[test] + fn the_matching_file_wins_even_when_it_is_not_the_primary() { + let wanted = "a".repeat(128); + let other = "b".repeat(128); + let version = version(vec![ + file(Some(&"1".repeat(40)), &other, true), + file(Some(&"2".repeat(40)), &wanted, false), + ]); + let identity = identity_of(&version, &wanted).expect("摘要对得上，必须给出身份"); + assert_eq!(identity.sha1, "2".repeat(40)); + assert_eq!(identity.size, Some(2048)); + assert!(identity.url.is_some()); + } + + #[test] + fn a_version_without_that_hash_yields_nothing() { + let version = version(vec![file(Some(&"1".repeat(40)), &"b".repeat(128), true)]); + assert_eq!(identity_of(&version, &"c".repeat(128)), None); + } + + #[test] + fn a_matching_file_without_a_sha1_is_not_usable() { + // 站点只给了 sha512：这时没有可填的 sha1，宁可「补不出」也不许拿 sha512 冒充。 + let wanted = "a".repeat(128); + let version = version(vec![file(None, &wanted, true)]); + assert_eq!(identity_of(&version, &wanted), None); + } + + #[test] + fn hex_case_does_not_matter() { + let wanted = "AbCd".repeat(32); + let version = version(vec![file( + Some(&"1".repeat(40)), + &wanted.to_ascii_lowercase(), + true, + )]); + assert!(identity_of(&version, &wanted).is_some()); + } +} diff --git a/crates/core/src/addon/online/dependency.rs b/crates/core/src/addon/online/dependency.rs new file mode 100644 index 0000000..440742f --- /dev/null +++ b/crates/core/src/addon/online/dependency.rs @@ -0,0 +1,330 @@ +//! 依赖图谱的**形状**：一次解析要什么（[`ResolveRequest`]）、出什么（[`DependencyPlan`]）。 +//! +//! 算法在 [`super::resolve`]；本文件只放类型与不变量，于是「两档失败从类型上可分辨」这件事 +//! 不必读算法也能核对。 +//! +//! # 三份名单，一份都不许丢 +//! +//! | 名单 | 含义 | 上层该做什么 | +//! |------|------|--------------| +//! | [`DependencyPlan::nodes`] | 要下的（BFS 顺序、父子关系齐全） | 逐个下载 | +//! | [`DependencyPlan::skipped`] | 目标目录里已经有同名文件 | 提示「已存在，跳过」 | +//! | [`DependencyPlan::failures`] | 装不了的，**每条自带 [`FailureKind`]** | 两档分开说；进可重试名单 | +//! +//! `truncated` 是第四样东西：撞到 [`DEFAULT_MAX_DEPTH`] 而没展开的项目。它既不是成功也不是 +//! 失败（站点没拒绝，我们主动停），但**必须**露出来——静默截断会让用户看着「装好了」而缺前置。 +//! +//! # 两档为什么不能合成一句 +//! +//! 「所选版本/加载器没有匹配项」与「网络异常 / 项目不存在」要用户做的事完全不同： +//! 前者换版本或换加载器，后者检查网络再试。字符串错误只能靠 `contains("网络")` 猜， +//! 一改文案就失效；[`FailureKind`] 把判据放在类型上，叶子成因（404 / 连不上 / 5xx） +//! 另存在 [`DependencyFailure::cause`] 上，允许上层再细分而不用重新判。 + +use super::model::{VersionFile, VersionQuery}; + +/// 默认最大深度（根 = 0）。六层足够覆盖真实套娃（前置的前置的前置……）， +/// 同时给环与异常链一个硬边界——撞上就记 [`DependencyPlan::truncated`]，**不静默截断**。 +pub const DEFAULT_MAX_DEPTH: u8 = 6; + +/// 目标目录里已存在的文件（调用方扫描后给；core 不读盘）。 +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub struct PresentFile { + /// 文件名（可以带路径，比对时会砍掉） + pub name: String, +} + +impl PresentFile { + /// 记一个已存在的文件名。 + #[must_use] + pub fn new(name: impl Into) -> Self { + Self { name: name.into() } + } + + /// 归一化后的比对键（见 [`present_key`]）。 + #[must_use] + pub fn key(&self) -> String { + present_key(&self.name) + } +} + +/// 文件名 → 比对键：只留文件名、小写、去掉 `.disabled` 后缀。 +/// +/// 为什么带 `.disabled`：本仓用**路径后缀**表示禁用（`mods/x.jar.disabled`，见 +/// `core::addon::export`），禁用中的 jar 也是「装过」，再下一份会和它并存。 +#[must_use] +pub fn present_key(name: &str) -> String { + let base = name + .rsplit(['/', '\\']) + .next() + .unwrap_or(name) + .trim() + .to_ascii_lowercase(); + base.strip_suffix(".disabled").unwrap_or(&base).to_string() +} + +/// 一次解析请求。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ResolveRequest { + /// 起点（项目 id 或 slug）；同层处理时按项目键字典序，与这里给的顺序无关 + pub roots: Vec, + /// 目标游戏版本（选版本用；`None` = 不限） + pub game_version: Option, + /// 目标加载器（选版本用；`None` = 不限） + pub loader: Option, + /// 最大深度（根 = 0，见 [`DEFAULT_MAX_DEPTH`]） + pub max_depth: u8, + /// 目标目录里已存在的文件（盘上去重的依据；空 = 目录是空的） + pub present: Vec, +} + +impl Default for ResolveRequest { + fn default() -> Self { + Self { + roots: Vec::new(), + game_version: None, + loader: None, + max_depth: DEFAULT_MAX_DEPTH, + present: Vec::new(), + } + } +} + +impl ResolveRequest { + /// 单根请求（内容库「装进实例」的入口形状）。 + #[must_use] + pub fn single(project: impl Into) -> Self { + Self { + roots: vec![project.into()], + ..Self::default() + } + } + + /// 这个项目的版本请求（过滤条件相同，只换项目）。 + #[must_use] + pub fn version_query(&self, project: &str) -> VersionQuery { + VersionQuery { + project: project.to_string(), + game_version: self.game_version.clone(), + loader: self.loader.clone(), + } + } +} + +/// 计划里的一条「要装什么」。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct PlannedNode { + /// 规范项目 id（站点回的 `project_id`；空则用请求时的键） + pub project: String, + /// 当初请求它用的键（slug 或 id）——重试要用同一个 + pub requested_as: String, + /// 版本 id + pub version_id: String, + /// 版本名 + pub version_name: String, + /// 版本号 + pub version_number: String, + /// 要下载的那个文件（`primary` 优先，见 `Version::primary_file`） + pub file: VersionFile, + /// 距根的层数（根 = 0） + pub depth: u8, + /// 谁要求装它（规范项目 id，排序去重；根为空 = 用户自己点的） + pub required_by: Vec, +} + +impl PlannedNode { + /// 是用户点的那个项目吗（根 = 层数 0）。 + /// + /// 判据是 `depth` 而不是 `required_by.is_empty()`：环里根也会被别人「要求」 + /// （A ⇄ B 时 A 的 `required_by` 里有 B），但它在计划里仍是起点。 + #[must_use] + pub fn is_root(&self) -> bool { + self.depth == 0 + } +} + +/// 为什么跳过。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum SkipReason { + /// 目标目录里已经有同名文件（含 `.disabled`） + AlreadyPresent, +} + +impl SkipReason { + /// 稳定字符串 id（日志 / DTO 用，**不要改名**）。 + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::AlreadyPresent => "already_present", + } + } +} + +/// 一条被跳过的（本来要下载的）项目。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct SkippedNode { + /// 规范项目 id + pub project: String, + /// 请求它用的键 + pub requested_as: String, + /// 计划里的文件名（在目录里找到了同名的那个） + pub file_name: String, + /// 距根的层数 + pub depth: u8, + /// 谁要求装它 + pub required_by: Vec, + /// 跳过原因 + pub reason: SkipReason, +} + +/// 失败的两档（**类型上就分开，不许拼成一句「下载失败」**）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum FailureKind { + /// 站点有这个项目，但所选游戏版本 / 加载器下没有可装的条目 + /// （版本列表为空，或选中的版本没有可下载的主文件）。 + /// + /// 用户该做的动作是**换版本或换加载器**；原样重试得到的还是这一档。 + Incompatible, + /// 取不到：没联网 / 项目不存在 / 站点出错 / 响应坏。 + /// + /// 用户该做的动作是**检查网络后再试**；具体叶子成因保留在 + /// [`DependencyFailure::cause`] 上（`NotFound` 与 `NotConnected` 不能混为一谈）。 + Unreachable, +} + +impl FailureKind { + /// 稳定字符串 id（日志 / 命令行输出用，**不要改名**）。 + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::Incompatible => "incompatible", + Self::Unreachable => "unreachable", + } + } +} + +/// 一条解析失败（进「可重试名单」的就是它们）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct DependencyFailure { + /// 请求它用的键（重试也用它） + pub requested_as: String, + /// 当初因为谁而被要求（规范项目 id；根为空） + pub required_by: Vec, + /// 距根的层数 + pub depth: u8, + /// 哪一档 + pub kind: FailureKind, + /// 叶子成因（只有 [`FailureKind::Unreachable`] 有） + pub cause: Option, + /// 人读说明（站点/引擎原话 + 上下文，不是界面文案） + pub message: String, +} + +/// 声明了 `required`、但**只给了 `version_id`**（没有 `project_id`）的依赖。 +/// +/// BFS 需要项目 id 才能取版本（`/v2/project/{id}/version`），所以这条既装不了、也不该被 +/// 假装没看见：留在计划里，上层才能说「有 N 条前置没法解析」而不是默默少装一个。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct UnresolvedRequired { + /// 声明它的项目（规范 id） + pub parent: String, + /// 站点给的版本 id（`None` = 连版本 id 都没有，只有文件名） + pub version_id: Option, + /// 站点给的文件名 + pub file_name: Option, +} + +/// 一次 BFS 的完整结果（成功、跳过、失败三份名单，都**不丢**）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct DependencyPlan { + /// 这次用的请求（重试要沿用同样的过滤条件与同一份 `present`） + pub request: ResolveRequest, + /// 要装的（BFS 顺序：层号小的在前，同层按项目键字典序） + pub nodes: Vec, + /// 目录里已经有了、不用再下的 + pub skipped: Vec, + /// 装不了的（两档混在同一个列表里，但每条自带 [`FailureKind`]） + pub failures: Vec, + /// 撞到 `max_depth` 而没展开的项目键（排序去重） + pub truncated: Vec, + /// 有 `required` 但没有项目 id、解析不了的前置（排序去重） + pub unresolved_required: Vec, +} + +impl DependencyPlan { + /// 空计划（`resolve` 从这里开始填）。 + #[must_use] + pub fn new(request: &ResolveRequest) -> Self { + Self { + request: request.clone(), + nodes: Vec::new(), + skipped: Vec::new(), + failures: Vec::new(), + truncated: Vec::new(), + unresolved_required: Vec::new(), + } + } + + /// 一条失败都没有吗（空循环也算干净）。 + #[must_use] + pub fn is_clean(&self) -> bool { + self.failures.is_empty() + } + + /// 某一档的失败（两档分开看时用）。 + pub fn failures_of(&self, kind: FailureKind) -> impl Iterator { + self.failures.iter().filter(move |item| item.kind == kind) + } + + /// 记一条失败——**按 `requested_as` 去重**，父边合并。 + /// + /// 为什么要有这道去重：同一个项目可能被两条路径要求（A→GONE、B→C→GONE）。若不去重， + /// 「可只重试这 N 个」会写出 `GONE、GONE`，用户按名单重试等于发两次一样的请求。 + /// 解析阶段与下载阶段的失败都走这里，于是名单里一个项目只出现一次。 + pub fn record_failure(&mut self, failure: DependencyFailure) { + if let Some(existing) = self + .failures + .iter_mut() + .find(|item| item.requested_as == failure.requested_as) + { + existing.required_by.extend(failure.required_by); + existing.required_by.sort(); + existing.required_by.dedup(); + // 深度取更浅的那条：越靠近根越该先修 + existing.depth = existing.depth.min(failure.depth); + return; + } + self.failures.push(failure); + } + + /// 「可重试名单」：失败项原样重启一次解析的请求。 + /// + /// 只含失败项 ⇒ 用户只重试这一部分，**不重下**已经装好的文件（`present` 沿用）。 + /// 两档都在名单里，但每条自带 [`FailureKind`]：不兼容那一档重试前得换版本/加载器， + /// 换完再调它才有意义。**这不是「后台自动重试」**——本模块只给请求，什么时候发由上层决定。 + /// + /// 调用方如果刚跑完一轮下载，重试前应**重新扫一遍目录**再填 `present`：这一轮新落盘的 + /// 文件不在旧的 `present` 里，不重扫就会把它们当「还没有」再下一份。 + #[must_use] + pub fn retry_request(&self) -> ResolveRequest { + let mut roots: Vec = Vec::new(); + for failure in &self.failures { + if !roots.contains(&failure.requested_as) { + roots.push(failure.requested_as.clone()); + } + } + ResolveRequest { + roots, + ..self.request.clone() + } + } + + /// 这个项目为什么在计划里（规范 id → 要求装它的项目）。`None` = 不在计划里。 + #[must_use] + pub fn required_by(&self, project: &str) -> Option<&[String]> { + self.nodes + .iter() + .find(|node| node.project == project) + .map(|node| node.required_by.as_slice()) + } +} diff --git a/crates/core/src/addon/online/download.rs b/crates/core/src/addon/online/download.rs new file mode 100644 index 0000000..9213a4c --- /dev/null +++ b/crates/core/src/addon/online/download.rs @@ -0,0 +1,334 @@ +//! 「取到下载地址」之后的最后一步：**下载 → 复核 sha1/sha512 → 才算数**。 +//! +//! # 三条硬要求（任务书原文） +//! +//! 1. **走既有分块下载引擎与镜像策略**：生产实现 [`EngineArtifactFetcher`] 只把请求翻译成 +//! [`DownloadRequest`]（`ResourceKind::ModFile` ⇒ 引擎按大文件分块下载，镜像展开、地区模式、 +//! 健康度、退避全在引擎里；Modrinth 的 CDN 不在 `mirrors.json` 的规则里，所以只有国内环境 +//! 真的命中规则时才会换源，不会瞎改写）； +//! 2. **校验 sha1/sha512 后再写入**：引擎只认 sha1（`Integrity` 只有 Sha1/Sha256 两档）， +//! 所以 sha1 交给引擎流式校验、sha512 由本模块**落盘后复核**；任何一项不符都删掉目标文件 +//! （`download` 模块的 `HashAlgo` 没有 Sha512 是事实，改它超出 M162 的 scope，已登记 finding）； +//! 3. **失败可重试且不留半截文件**：每次尝试前先删目标文件，尝试次数 [`RETRY_ATTEMPTS`]； +//! 半截文件本身由引擎的 `PartFile` 守卫（`.ullpart--` + 原子改名）兜住， +//! 本模块不另造临时目录范式。 +//! +//! # 为什么摘要复核不信任 fetcher +//! +//! [`ArtifactFetcher`] 是注入点（测试喂假字节）。如果「校验」放在某个具体实现里，测试注入的 +//! 实现就成了「不校验也能过」的后门——而生产实现与测试实现走的是同一段 [`download_verified`]。 +//! 所以复核在**外层**：读一遍落盘文件，同时算 sha1 与 sha512，与声明逐字比对。 + +use std::io::Read; +use std::path::{Path, PathBuf}; + +use sha1::Digest as _; +use sha2::Sha512; + +use crate::download::config::DEFAULT_MAX_ATTEMPTS_PER_SOURCE; +use crate::download::{DownloadEngine, DownloadRequest, Integrity, ResourceKind}; + +use super::modrinth::HashAlgorithm; +use super::transport::{OnlineError, OnlineErrorKind, OnlineFuture}; + +/// 本模块外层「整条下载」的预算（含首次）：最多取几遍文件。 +/// +/// # 它**不是**引擎的每源尝试次数，所以不引用 `download::config` 的常量（M205 判定） +/// +/// 数值恰好都是 3，但数的不是同一件事。三条判据，任一条都足够说明「合并成一处」会把语义拍平： +/// +/// 1. **层级不同，而且是相乘**：引擎那层在 [`ArtifactFetcher`] 里面，按**源**数（镜像展开后每个候选 +/// 各有一份预算，见 `DownloadEngine::attempts_for`；源在冷却期时还会缩成 1 次恢复探测）。本模块这 +/// 层只数「取一遍 + 复核一遍」，每数一次都要重新走一遍引擎 —— 最坏情况下的真实请求数 ≈ +/// [`RETRY_ATTEMPTS`] × 引擎每源预算，合并成一个数等于把最坏请求数变成平方级。 +/// 2. **管的失败类型不同**：sha512 不符与字节数不符只有本模块知道（引擎只认 sha1，`Integrity` 没有 +/// Sha512 档），这类失败引擎**不会**重试，必须由这一层重取 —— 这一层的预算里有一档是引擎看不见的。 +/// 3. **改它的性质不同**：`download.retry_limit` 是用户可见的设置（0~10、进 JSON schema，也就是说引擎 +/// 那个默认值会因为**用户的**配置而变）；这里的 3 是内容库元数据请求的产品口径，没有设置键，也不该 +/// 被某个设置项的出厂默认牵着走。 +/// +/// **边界**：真实请求数 = [`RETRY_ATTEMPTS`]（外层）× 引擎每源预算（`download.retry_limit`，出厂 +/// [`DEFAULT_MAX_ATTEMPTS_PER_SOURCE`]）。**出厂档**是 3 × 3 = 9；用户把 `retry_limit` 调到 N 时是 +/// 3 × N（schema 上限 `MAX_ATTEMPTS_PER_SOURCE` = 10 ⇒ 30）——**9 只是出厂档的数，不是事实上限**， +/// 这正是本仓反复吃亏的「把出厂值说成上限」。下面两条注解级断言（编译期求值）钉的也只是**出厂档**： +/// 出厂默认想改，就得先读到这段判据，而不是被一次「统一常量」的顺带改动悄悄翻倍。 +pub const RETRY_ATTEMPTS: u32 = 3; + +/// 外层预算被改了吗（改之前先读 [`RETRY_ATTEMPTS`] 的 doc：它不是引擎的每源次数）。 +const _: () = assert!( + RETRY_ATTEMPTS == 3, + "外层下载预算（出厂档 3）变了：它不是 download::config 的每源尝试次数，改它要单独一个决定" +); + +/// **出厂档**最坏请求数（外层 3 × 引擎每源出厂 3）——两个「3」不共享来源，乘积才是事实。 +/// 用户把 `download.retry_limit` 调大后真实最坏是 3 × N，与本断言无关（那头是运行时配置，编译期钉不了）。 +const _: () = assert!( + RETRY_ATTEMPTS as u64 * DEFAULT_MAX_ATTEMPTS_PER_SOURCE as u64 == 9, + "出厂档最坏真实请求数变了（外层 3 × 引擎每源出厂 3 = 9；用户把 retry_limit 调到 N 时是 3 × N）：先读 doc" +); + +/// 一次下载请求（只含「引擎需要什么」，不含任何站点字段）。 +#[derive(Debug, Clone, Copy)] +pub struct FetchArgs<'a> { + /// 逻辑下载地址（官方源；镜像展开在引擎里） + pub url: &'a str, + /// 落盘路径（父目录由调用方保证，或由本模块建） + pub dest: &'a Path, + /// 期望 SHA-1（形状不对当「没给」，见 [`well_formed`]） + pub sha1: Option<&'a str>, + /// 期望字节数 + pub size: Option, +} + +/// 「把 URL 下到 dest」的注入点（测试喂假字节）。 +pub trait ArtifactFetcher: Send + Sync { + /// 下到 `dest`，返回落盘字节数。 + fn fetch<'a>(&'a self, args: FetchArgs<'a>) -> OnlineFuture<'a, Result>; +} + +/// 生产实现：交给 `core::download` 的引擎。 +#[derive(Debug, Clone, Copy)] +pub struct EngineArtifactFetcher<'a> { + engine: &'a DownloadEngine, +} + +impl<'a> EngineArtifactFetcher<'a> { + /// 绑定引擎。 + #[must_use] + pub const fn new(engine: &'a DownloadEngine) -> Self { + Self { engine } + } +} + +impl ArtifactFetcher for EngineArtifactFetcher<'_> { + fn fetch<'a>(&'a self, args: FetchArgs<'a>) -> OnlineFuture<'a, Result> { + Box::pin(async move { + let mut request = + DownloadRequest::new(ResourceKind::ModFile, args.url, args.dest.to_path_buf()); + if let Some(sha1) = args.sha1.filter(|hex| HashAlgorithm::Sha1.accepts(hex)) { + request.integrity = Some(Integrity::sha1(sha1)); + } + request.expected_size = args.size; + let outcome = self.engine.download(request).await?; + Ok(outcome.bytes) + }) + } +} + +/// 一个文件的摘要（读一遍盘同时算两个）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Digest { + /// SHA-1（小写十六进制） + pub sha1: String, + /// SHA-512（小写十六进制） + pub sha512: String, + /// 字节数 + pub bytes: u64, +} + +/// 一次成功下载的产物。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Downloaded { + /// 落盘路径 + pub path: PathBuf, + /// 字节数 + pub bytes: u64, + /// 落盘内容的摘要（**实测**，不是声明） + pub digest: Digest, +} + +/// 下载并复核（sha1 **与** sha512，给了哪个就校验哪个）。 +/// +/// # Errors +/// +/// - 声明的摘要是 `Some` 但形状不对 ⇒ [`OnlineErrorKind::Unsupported`]，**不发请求**； +/// - 没有下载地址 ⇒ `Unsupported`； +/// - 重试用尽仍是网络/站点/摘要问题 ⇒ 最后一次的错误（且目标文件已被删掉）； +/// - 本地 IO ⇒ `Io`。 +pub async fn download_verified( + fetcher: &dyn ArtifactFetcher, + url: &str, + sha1: Option<&str>, + sha512: Option<&str>, + size: Option, + dest: &Path, +) -> Result { + if url.trim().is_empty() { + return Err(OnlineError::unsupported("没有可用下载地址")); + } + // 两档摘要**各自**过形状检查：坏掉的那一档丢掉，用另一档校验（mrpack 的权威摘要是 + // sha512，CLI/整合包都可能给出一个人写坏的 sha1——为此整条不装是过分惩罚）。 + // 但如果**声明过**摘要却一档都用不上，就必须失败：那是「没有任何校验」的伪装。 + let declared = sha1.is_some() || sha512.is_some(); + let sha1 = usable_hash(sha1, HashAlgorithm::Sha1); + let sha512 = usable_hash(sha512, HashAlgorithm::Sha512); + if declared && sha1.is_none() && sha512.is_none() { + return Err(OnlineError::unsupported( + "声明的 sha1/sha512 都不是合法摘要，无法校验（拒绝在「没有校验」的情况下落盘）", + )); + } + if let Some(parent) = dest.parent() { + std::fs::create_dir_all(parent).map_err(|error| { + OnlineError::new( + OnlineErrorKind::Io, + format!("建目录 {} 失败：{error}", parent.display()), + ) + })?; + } + + let mut last: Option = None; + for attempt in 0..RETRY_ATTEMPTS { + // 每次尝试前清掉目标：上一轮的半截/坏内容不许参与本轮判定。 + remove_quiet(dest); + let fetched = fetcher + .fetch(FetchArgs { + url, + dest, + sha1, + size, + }) + .await; + let bytes = match fetched { + Ok(bytes) => bytes, + Err(error) if retryable(error.kind()) && attempt + 1 < RETRY_ATTEMPTS => { + last = Some(error); + continue; + } + Err(error) => { + remove_quiet(dest); + return Err(error); + } + }; + if let Some(expected) = size { + if expected != bytes { + last = Some(OnlineError::integrity(format!( + "字节数与声明不符：声明 {expected}，实际 {bytes}" + ))); + remove_quiet(dest); + continue; + } + } + let digest = match digest_file(dest) { + Ok(digest) => digest, + Err(error) => { + // 与其它失败路径一致：读不出来就不许把文件留在盘上。 + remove_quiet(dest); + return Err(error); + } + }; + if let Some(expected) = sha1 { + if !equals_hex(expected, &digest.sha1) { + last = Some(OnlineError::integrity(format!( + "SHA-1 与声明不符（声明 {expected}，实际 {}）", + digest.sha1 + ))); + remove_quiet(dest); + continue; + } + } + if let Some(expected) = sha512 { + if !equals_hex(expected, &digest.sha512) { + last = Some(OnlineError::integrity(format!( + "SHA-512 与声明不符（声明 {expected}，实际 {}）", + digest.sha512 + ))); + remove_quiet(dest); + continue; + } + } + return Ok(Downloaded { + path: dest.to_path_buf(), + bytes, + digest, + }); + } + remove_quiet(dest); + Err(last.unwrap_or_else(|| { + OnlineError::new( + OnlineErrorKind::NotConnected, + "下载重试用尽（没有拿到任何字节）", + ) + })) +} + +/// 读一个文件同时算 sha1 与 sha512。 +/// +/// # Errors +/// 读盘失败返回 [`OnlineErrorKind::Io`]。 +pub fn digest_file(path: &Path) -> Result { + let mut file = std::fs::File::open(path).map_err(|error| { + OnlineError::new( + OnlineErrorKind::Io, + format!("读 {} 失败：{error}", path.display()), + ) + })?; + let mut sha1 = sha1::Sha1::new(); + let mut sha512 = Sha512::new(); + let mut buffer = [0u8; 64 * 1024]; + let mut bytes = 0u64; + loop { + let read = file.read(&mut buffer).map_err(|error| { + OnlineError::new( + OnlineErrorKind::Io, + format!("读 {} 失败：{error}", path.display()), + ) + })?; + if read == 0 { + break; + } + bytes += read as u64; + sha1.update(&buffer[..read]); + sha512.update(&buffer[..read]); + } + Ok(Digest { + sha1: to_hex(&sha1.finalize()), + sha512: to_hex(&sha512.finalize()), + bytes, + }) +} + +/// 摘要形状合法吗（长度 + 十六进制）。 +/// +/// 这一档摘要能用吗：形状合法就原样返回（不复制、不归一，大小写不敏感比较交给 +/// [`equals_hex`]），形状不合法就当「没给」。 +/// +/// 为什么丢掉而不是报错：`sha1` 与 `sha512` 是同一个文件的两档校验，**任一**都能证明内容； +/// 一档写坏不该让整条装不上（r1 顺手项）。两档都不可用时由 `download_verified` 统一拒绝。 +fn usable_hash(raw: Option<&str>, algorithm: HashAlgorithm) -> Option<&str> { + raw.map(str::trim) + .filter(|hex| !hex.is_empty()) + .filter(|hex| algorithm.accepts(hex)) +} + +/// 十六进制比较（大小写不敏感：声明侧可能大写）。 +fn equals_hex(expected: &str, actual: &str) -> bool { + expected.len() == actual.len() && expected.eq_ignore_ascii_case(actual) +} + +/// 这个错误值得再试一次吗（网络/站点/内容不符；**404 与自身不自洽一律不重试**）。 +fn retryable(kind: OnlineErrorKind) -> bool { + matches!( + kind, + OnlineErrorKind::NotConnected | OnlineErrorKind::Server | OnlineErrorKind::Integrity + ) +} + +fn remove_quiet(path: &Path) { + if let Err(error) = std::fs::remove_file(path) { + if error.kind() != std::io::ErrorKind::NotFound { + eprintln!("[online] 删 {} 失败：{error}", path.display()); + } + } +} + +/// 小写十六进制（不引 `hex` 依赖；与 `download::verify::to_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 +} diff --git a/crates/core/src/addon/online/mod.rs b/crates/core/src/addon/online/mod.rs new file mode 100644 index 0000000..2fa4203 --- /dev/null +++ b/crates/core/src/addon/online/mod.rs @@ -0,0 +1,89 @@ +//! 在线内容源（M162）：**只做匿名可用的那半**——Modrinth v2。 +//! +//! # 为什么形状是 Modrinth 的，而不是「内容源通用抽象」 +//! +//! CurseForge 的检索/文件端点要 `x-api-key`（D10 §5 的客户端还没写），而它的 JSON 方言与 +//! Modrinth 几乎没有一处同名（`project_id` vs `id`、`description` vs `summary`、 +//! `downloads` vs `downloadCount`、版本列表还要再套一层 `latestFilesIndexes`）。为了让两者 +//! 共用而发明一套谁都不像的抽象，代价是两边都得翻译两次、错一处两边都错。 +//! +//! 所以本模块**按 Modrinth 的真实形状建模**（`/v2/search` 的 facets、`/v2/project/{id}`、 +//! `/v2/project/{id}/version`、`/v2/version_file/{hash}`），把「平台差异」留到将来真要加第二个 +//! 源时再抽。留的缝只有两处： +//! +//! | 缝 | 在哪 | 换源时要动什么 | +//! |----|------|----------------| +//! | [`Transport`] | 唯一的 HTTP 出口（trait） | 换/加一个实现；测试注入录制 JSON | +//! | [`Modrinth::new`] | `Modrinth<'a, T: Transport + ?Sized>` | 传 `&dyn Transport` 就能换站点客户端，一行业务代码不改 | +//! +//! # 网络层（零新依赖） +//! +//! `Cargo.lock` 里已有的 `reqwest` 0.12 + `tokio` + `serde_json` 就是全部。生产实现 +//! [`EngineTransport`] 走 `DownloadEngine::download_bytes`，于是**信号量限流、源健康度、 +//! 指数退避、错误分类**全由 `core::download` 提供，本模块不写第二个重试循环，也不持有第二个 +//! `reqwest::Client`（与 `addon::import::fetch` 同一条纪律）。那个引擎是宿主侧的进程级共享实例 +//! （M165：`download::shared::engine_for`），所以元数据请求与文件下载共用同一条连接池与限流。 +//! +//! 没有 POST：Modrinth 的批量接口（`POST /v2/version_files`）需要 POST 请求体，而引擎的 +//! `DownloadRequest` 没有请求体字段。补全路径因此按**单摘要 GET** 逐条查（循环在 +//! `crate::addon::import::complete`，本模块只用 [`identity_of`] 认文件）， +//! mrpack 里缺 `sha1` 的条目本来就是少数，不值得为它引入第二条 HTTP 路径。 +//! +//! # 离线不是「空结果」 +//! +//! 无网时上层必须能说清「未联网」而不是「没有匹配的内容」，所以错误是枚举不是字符串： +//! 引擎把叶子成因（404 / 5xx / 网络）放在 `DownloadError::leaf` 上，[`OnlineError`] 按它映射 +//! 成 `NotFound` / `Server` / `NotConnected`（见 `transport::From` 的映射表）， +//! presenter 再翻成 DTO 的 `ContentFailureKind::{Offline,NotFound,Server}`。 +//! 没有叶子时保守归到 `NotConnected`——宁可说「检查网络」，也不声称「没有匹配的内容」。 +//! +//! # 模块 +//! +//! | 文件 | 职责 | +//! |------|------| +//! | [`model`] | Modrinth 的响应形状 + 检索请求（facets / 排序 / 分页） | +//! | [`transport`] | HTTP 出口 trait + 生产实现（走下载引擎）+ 错误分类 | +//! | [`modrinth`] | 端点拼装与响应解析（纯逻辑，测试直接喂录制 JSON） | +//! | [`download`] | 取下载地址之后那一步：引擎下载 + **sha1/sha512 复核** + 重试 + 不留半截文件 | +//! | [`complete`] | 按摘要认文件（[`identity_of`]）：站点返回的版本里哪条才是我们要的那个 | +//! | [`dependency`] | 依赖图谱的形状（请求 / 计划 / **两档失败**） | +//! | [`resolve`] | BFS 解析（只跟 `required`）：去重、按项目缓存、深度上限、确定性顺序 | +//! +//! # 一次「装一个模组」到底发几个请求 +//! +//! M186 之前的实测口径（也是现在仍然成立的基座）：`GET /v2/project/{id}/version` 一次 +//! （带 `game_versions` / `loaders` 两个数组参数）＋ 文件下载一次 = **2 个请求**， +//! 其中**没有任何**依赖解析——`dependencies` 字段根本没进模型，所以「装了模组但进游戏崩」 +//! 这条路只能靠用户自己发现缺前置。 +//! +//! M186 之后：根项目同样是 2 个请求（版本 + 下载），每个 `required` 前置再各加 1 次版本 +//! 请求 + 1 次下载。与参考实现相比省掉了「每个前置再查一次 `/v2/project/{id}` 换 slug」， +//! 因为依赖里给的就是项目 id，而 `/project/{id}/version` 认 id。 + +pub mod complete; +pub mod dependency; +pub mod download; +pub mod model; +pub mod modrinth; +pub mod resolve; +pub mod transport; + +pub use complete::identity_of; +pub use dependency::{ + present_key, DependencyFailure, DependencyPlan, FailureKind, PlannedNode, PresentFile, + ResolveRequest, SkipReason, SkippedNode, UnresolvedRequired, DEFAULT_MAX_DEPTH, +}; +pub use download::{ + digest_file, download_verified, ArtifactFetcher, Digest, Downloaded, EngineArtifactFetcher, + FetchArgs, RETRY_ATTEMPTS, +}; +pub use model::{ + ContentType, Dependency, DependencyType, FileHashes, ProjectDetail, ProjectHit, SearchPage, + SearchQuery, SortIndex, Version, VersionFile, VersionQuery, VersionType, +}; +pub use modrinth::{HashAlgorithm, Modrinth, MODRINTH_API}; +pub use resolve::resolve; +pub use transport::{EngineTransport, OnlineError, OnlineErrorKind, OnlineFuture, Transport}; + +#[cfg(test)] +mod tests; diff --git a/crates/core/src/addon/online/model/mod.rs b/crates/core/src/addon/online/model/mod.rs new file mode 100644 index 0000000..67af82b --- /dev/null +++ b/crates/core/src/addon/online/model/mod.rs @@ -0,0 +1,37 @@ +//! Modrinth v2 的响应形状与检索请求（**按站点原文建模，不翻译成「通用内容模型」**）。 +//! +//! 每个公开类型都对着一个真实端点： +//! +//! | 类型 | 端点 | +//! |------|------| +//! | [`SearchQuery`] → [`SearchPage`] | `GET /v2/search` | +//! | [`ProjectDetail`] | `GET /v2/project/{id or slug}` | +//! | [`VersionQuery`] → [`Vec`] | `GET /v2/project/{id}/version` | +//! | [`Version`] | `GET /v2/version_file/{hash}?algorithm=sha1\|sha512` | +//! +//! # 解析纪律 +//! +//! 站点会加字段、也会给 `""` 表示「没有」——所以： +//! +//! - 一律 `#[serde(default)]`，**没给就是空的**，缺字段不炸整页； +//! - 只把**形状**当硬要求（`hits` 必须是数组、project 必须是对象），形状不对就是 +//! [`super::OnlineErrorKind::Malformed`]，不静默给空页冒充「没结果」； +//! - 未知字段不保留（这里不是导入导出的无损通道，是只读检索）。 +//! +//! # 为什么拆成三个文件 +//! +//! 一个 600+ 行的 `model.rs` 已经越过本仓的 400 行硬线，而且三种东西混在一起时最容易看漏 +//! 「站点字段名与 DTO 字段名不是一回事」：请求形状（[`query`]）、响应形状（[`types`]）、 +//! 以及把前者读成后者的解析（[`parse`]）。拆开后 `parse` 里每一处 `#[serde(rename)]`/ +//! `alias` 都能单独读。 + +mod parse; +mod query; +mod types; + +pub use parse::{known_loaders, parse_project, parse_search, parse_version, parse_versions}; +pub use query::{ContentType, SearchQuery, SortIndex, KNOWN_LOADERS}; +pub use types::{ + Dependency, DependencyType, FileHashes, ProjectDetail, ProjectHit, SearchPage, Version, + VersionFile, VersionQuery, VersionType, +}; diff --git a/crates/core/src/addon/online/model/parse.rs b/crates/core/src/addon/online/model/parse.rs new file mode 100644 index 0000000..0e4722e --- /dev/null +++ b/crates/core/src/addon/online/model/parse.rs @@ -0,0 +1,289 @@ +//! 站点的原始 JSON → 上面那些类型（**唯一**读字段名的地方）。 +//! +//! 每个 `#[serde(default)]` 都在说「这个字段站点可能不给」；`alias` 只在有历史原因时用 +//! （例如检索命中的日期字段曾按 `updated` 读，站点实际叫 `date_modified`）。 + +use std::collections::BTreeMap; + +use serde::Deserialize; + +use super::query::KNOWN_LOADERS; +use super::types::{ + Dependency, DependencyType, ProjectDetail, ProjectHit, SearchPage, Version, VersionFile, + VersionType, +}; +use crate::addon::online::transport::{OnlineError, OnlineErrorKind}; + +// --------------------------------------------------------------- 解析 + +#[derive(Debug, Default, Deserialize)] +struct RawSearch { + #[serde(default)] + hits: Vec, + #[serde(default)] + total_hits: u64, + #[serde(default)] + offset: u32, + #[serde(default)] + limit: u32, +} + +#[derive(Debug, Default, Deserialize)] +struct RawHit { + #[serde(default)] + project_id: String, + #[serde(default)] + slug: String, + #[serde(default)] + title: String, + #[serde(default)] + description: String, + #[serde(default)] + author: String, + #[serde(default)] + downloads: u64, + #[serde(default)] + follows: u64, + // 站点的字段名是 `date_modified`（旧实现的 `updated` 永远取不到值，别再加回去当主名）。 + #[serde(default, alias = "updated")] + date_modified: String, + #[serde(default)] + versions: Vec, + #[serde(default)] + categories: Vec, + #[serde(default)] + project_type: String, + #[serde(default)] + icon_url: Option, +} + +#[derive(Debug, Default, Deserialize)] +struct RawProject { + #[serde(default)] + id: String, + #[serde(default)] + slug: String, + #[serde(default)] + title: String, + #[serde(default)] + description: String, + #[serde(default)] + body: String, + #[serde(default)] + project_type: String, + #[serde(default)] + downloads: u64, + #[serde(default)] + followers: u64, + #[serde(default)] + updated: String, + #[serde(default)] + published: String, + #[serde(default)] + game_versions: Vec, + #[serde(default)] + loaders: Vec, + #[serde(default)] + categories: Vec, + #[serde(default)] + icon_url: Option, + #[serde(default)] + source_url: Option, + #[serde(default)] + issues_url: Option, +} + +#[derive(Debug, Default, Deserialize)] +struct RawVersion { + #[serde(default)] + id: String, + #[serde(default)] + project_id: String, + #[serde(default)] + name: String, + #[serde(default)] + version_number: String, + #[serde(default)] + version_type: String, + #[serde(default)] + loaders: Vec, + #[serde(default)] + game_versions: Vec, + #[serde(default)] + date_published: String, + #[serde(default)] + downloads: u64, + #[serde(default)] + files: Vec, + #[serde(default)] + dependencies: Vec, +} + +#[derive(Debug, Default, Deserialize)] +struct RawDependency { + #[serde(default)] + project_id: Option, + #[serde(default)] + version_id: Option, + #[serde(default)] + file_name: Option, + // 站点给的是 `required` / `optional` / `incompatible` / `embedded`。 + // 必须是 `Option`：`#[serde(default)]` 只兜「字段缺失」，兜不住 `null` + // （`"dependency_type": null` 用 `String` 会整份响应报 Malformed，于是整个项目都取不到版本）。 + #[serde(default)] + dependency_type: Option, +} + +#[derive(Debug, Default, Deserialize)] +struct RawFile { + #[serde(default)] + hashes: BTreeMap, + #[serde(default)] + url: String, + #[serde(default)] + filename: String, + #[serde(default)] + size: u64, + #[serde(default)] + primary: bool, +} + +/// 解析 `/v2/search`。 +/// +/// # Errors +/// JSON 不合法、或没有 `hits` 数组时返回 [`OnlineErrorKind::Malformed`]。 +pub fn parse_search(body: &str, offset: u32, limit: u32) -> Result { + let raw: RawSearch = parse_json(body, "search")?; + Ok(SearchPage { + hits: raw.hits.into_iter().map(hit_of).collect(), + total_hits: raw.total_hits, + // 站点会回显 offset/limit；缺省用请求里的（分页游标不能靠回显才成立） + offset: raw.offset.max(offset), + limit: if raw.limit == 0 { limit } else { raw.limit }, + }) +} + +/// 解析 `/v2/project/{id}`。 +/// +/// # Errors +/// JSON 不合法时返回 [`OnlineErrorKind::Malformed`]。 +pub fn parse_project(body: &str) -> Result { + let raw: RawProject = parse_json(body, "project")?; + Ok(ProjectDetail { + id: raw.id, + slug: raw.slug, + title: raw.title, + description: raw.description, + body: raw.body, + project_type: raw.project_type, + downloads: raw.downloads, + follows: raw.followers, + updated: raw.updated, + published: raw.published, + game_versions: raw.game_versions, + loaders: raw.loaders, + categories: raw.categories, + icon_url: non_empty(raw.icon_url), + source_url: non_empty(raw.source_url), + issues_url: non_empty(raw.issues_url), + }) +} + +/// 解析 `/v2/project/{id}/version`（一个数组）。 +/// +/// # Errors +/// JSON 不合法或不是数组时返回 [`OnlineErrorKind::Malformed`]。 +pub fn parse_versions(body: &str) -> Result, OnlineError> { + let raw: Vec = + serde_json::from_str(body).map_err(|error| malformed("versions", error))?; + Ok(raw.into_iter().map(version_of).collect()) +} + +/// 解析 `/v2/version_file/{hash}`（单个版本对象）。 +/// +/// # Errors +/// JSON 不合法时返回 [`OnlineErrorKind::Malformed`]。 +pub fn parse_version(body: &str) -> Result { + let raw: RawVersion = parse_json(body, "version_file")?; + Ok(version_of(raw)) +} + +fn parse_json Deserialize<'de>>(body: &str, what: &str) -> Result { + serde_json::from_str(body).map_err(|error| malformed(what, error)) +} + +fn malformed(what: &str, error: serde_json::Error) -> OnlineError { + OnlineError::new( + OnlineErrorKind::Malformed, + format!("Modrinth {what} 响应不是期望形状：{error}"), + ) +} + +fn hit_of(raw: RawHit) -> ProjectHit { + ProjectHit { + project_id: raw.project_id, + slug: raw.slug, + title: raw.title, + description: raw.description, + author: raw.author, + downloads: raw.downloads, + follows: raw.follows, + updated: raw.date_modified, + loaders: known_loaders(&raw.categories), + game_versions: raw.versions, + project_type: raw.project_type, + icon_url: non_empty(raw.icon_url), + } +} + +fn version_of(raw: RawVersion) -> Version { + Version { + id: raw.id, + project_id: raw.project_id, + name: raw.name, + version_number: raw.version_number, + version_type: VersionType::parse(&raw.version_type), + loaders: raw.loaders, + game_versions: raw.game_versions, + date_published: raw.date_published, + downloads: raw.downloads, + files: raw + .files + .into_iter() + .map(|file| VersionFile { + hashes: file.hashes, + url: file.url, + filename: file.filename, + size: file.size, + primary: file.primary, + }) + .collect(), + dependencies: raw + .dependencies + .into_iter() + .map(|dependency| Dependency { + project_id: non_empty(dependency.project_id), + version_id: non_empty(dependency.version_id), + file_name: non_empty(dependency.file_name), + dependency_type: DependencyType::parse( + dependency.dependency_type.as_deref().unwrap_or_default(), + ), + }) + .collect(), + } +} + +/// 只留已知加载器（`categories` 里混着分类标签）。 +#[must_use] +pub fn known_loaders(categories: &[String]) -> Vec { + categories + .iter() + .filter(|tag| KNOWN_LOADERS.contains(&tag.as_str())) + .cloned() + .collect() +} + +/// 空串当「没有」（站点用 `""` 表示没图 / 没链接）。 +fn non_empty(value: Option) -> Option { + value.filter(|item| !item.trim().is_empty()) +} diff --git a/crates/core/src/addon/online/model/query.rs b/crates/core/src/addon/online/model/query.rs new file mode 100644 index 0000000..1e2b57f --- /dev/null +++ b/crates/core/src/addon/online/model/query.rs @@ -0,0 +1,165 @@ +//! 检索请求的形状（facet / 排序 / 分页）——站点要什么就写什么，不预先「通用化」。 +//! +//! 两个容易踩的点： +//! +//! 1. `facets` 是**二维数组的 JSON 文本**（外层「与」、内层「或」），要再整体百分号编码； +//! 2. `categories` 里混着分类标签（`optimization`），只有 [`KNOWN_LOADERS`] 那几个才是加载器。 + +/// Modrinth 的 `project_type` 取值（检索 facet 与项目详情的同名字段）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +pub enum ContentType { + /// 整合包 + Modpack, + /// Mod + Mod, + /// 资源包 + Resourcepack, + /// 光影 + Shader, + /// 服务端插件 + Plugin, + /// 数据包 + Datapack, +} + +impl ContentType { + /// 站点原文（`project_type` facet 的值）。 + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::Modpack => "modpack", + Self::Mod => "mod", + Self::Resourcepack => "resourcepack", + Self::Shader => "shader", + Self::Plugin => "plugin", + Self::Datapack => "datapack", + } + } + + /// 从站点原文解析；认不出返回 `None`（调用方决定当「未知」还是报错）。 + #[must_use] + pub fn parse(raw: &str) -> Option { + Some(match raw { + "modpack" => Self::Modpack, + "mod" => Self::Mod, + "resourcepack" => Self::Resourcepack, + "shader" => Self::Shader, + "plugin" => Self::Plugin, + "datapack" => Self::Datapack, + _ => return None, + }) + } +} + +/// `/v2/search` 的 `index` 参数。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub enum SortIndex { + /// 相关度（站点默认） + #[default] + Relevance, + /// 下载量 + Downloads, + /// 关注数 + Follows, + /// 最新发布 + Newest, + /// 最近更新 + Updated, +} + +impl SortIndex { + /// 站点原文。 + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::Relevance => "relevance", + Self::Downloads => "downloads", + Self::Follows => "follows", + Self::Newest => "newest", + Self::Updated => "updated", + } + } +} + +/// 站点认的加载器 facet 值（`categories` 里混着 `optimization` 这种**分类标签**， +/// 直接整份当加载器会画出假加载器）。 +/// +/// 后两项是**光影**的加载器（Modrinth 把 shader 的 `iris` / `optifine` 也放在 `categories` +/// 里）：不登记它们，光影检索结果的 `loaders` 就会恒为空，页面既画不出「支持 Iris」， +/// 也用不上「只看 Iris」这种判断。 +pub const KNOWN_LOADERS: [&str; 8] = [ + "fabric", + "forge", + "neoforge", + "quilt", + "liteloader", + "rift", + "iris", + "optifine", +]; + +/// 一次检索请求（分页游标也在里面：换页就是换一份 query）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct SearchQuery { + /// 关键词（空 = 不带 `query` 参数，即「按排序浏览」） + pub text: String, + /// 内容类型过滤 + pub project_type: Option, + /// 游戏版本过滤（精确值，如 `1.20.1`） + pub game_version: Option, + /// 加载器过滤（站点 facet 值，如 `fabric`） + pub loader: Option, + /// 排序 + pub index: SortIndex, + /// 每页条数（站点上限 100，构造时钳住） + pub limit: u32, + /// 偏移 + pub offset: u32, +} + +impl Default for SearchQuery { + fn default() -> Self { + Self { + text: String::new(), + project_type: None, + game_version: None, + loader: None, + index: SortIndex::Relevance, + limit: 20, + offset: 0, + } + } +} + +impl SearchQuery { + /// 站点上限（超过会被站点拒，钳住更省一次往返）。 + pub const MAX_LIMIT: u32 = 100; + + /// 钳过界的分页参数。 + #[must_use] + pub fn normalized(&self) -> Self { + let mut query = self.clone(); + query.text = query.text.trim().to_string(); + query.limit = query.limit.clamp(1, Self::MAX_LIMIT); + query + } + + /// `facets` 参数（站点要的是**二维数组的 JSON**，每一项是一组「或」）。 + /// + /// 形状：`[["project_type:mod"],["versions:1.20.1"],["categories:fabric"]]`——不同组之间是 + /// 「与」，同组内是「或」。这里每组只有一项。 + #[must_use] + pub fn facets(&self) -> String { + let mut groups: Vec> = Vec::new(); + if let Some(kind) = self.project_type { + groups.push(vec![format!("project_type:{}", kind.as_str())]); + } + if let Some(version) = self.game_version.as_deref().filter(|v| !v.is_empty()) { + groups.push(vec![format!("versions:{version}")]); + } + if let Some(loader) = self.loader.as_deref().filter(|v| !v.is_empty()) { + groups.push(vec![format!("categories:{loader}")]); + } + serde_json::to_string(&groups).unwrap_or_else(|_| "[]".to_string()) + } +} diff --git a/crates/core/src/addon/online/model/types.rs b/crates/core/src/addon/online/model/types.rs new file mode 100644 index 0000000..3c2b57a --- /dev/null +++ b/crates/core/src/addon/online/model/types.rs @@ -0,0 +1,333 @@ +//! 响应形状（`/v2/search`、`/v2/project`、`/v2/project/{id}/version`、`/v2/version_file`）。 + +use std::collections::BTreeMap; + +/// 一页检索结果。 +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub struct SearchPage { + /// 命中项（顺序 = 站点顺序） + pub hits: Vec, + /// 站点给的总数（**估算值**：站点文档不保证精确） + pub total_hits: u64, + /// 请求的偏移 + pub offset: u32, + /// 请求的每页条数 + pub limit: u32, +} + +impl SearchPage { + /// 还有下一页吗。 + /// + /// 判据是「本页装满了」，不是 `offset + len < total`：`total_hits` 是估算值， + /// 用「装满」最多多请求一次空页，不会出现「明明还有却翻不到」。 + #[must_use] + pub fn has_more(&self) -> bool { + self.limit > 0 && self.hits.len() as u32 >= self.limit + } +} + +/// 一条检索命中（`/v2/search` 的 `hits[]`）。 +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub struct ProjectHit { + /// 项目 id（base62） + pub project_id: String, + /// 人读 slug + pub slug: String, + /// 标题 + pub title: String, + /// 简介 + pub description: String, + /// 作者（站点给的是团队名；没有时为空） + pub author: String, + /// 下载量 + pub downloads: u64, + /// 关注数 + pub follows: u64, + /// 最近更新（站点原文 ISO-8601） + pub updated: String, + /// 支持的加载器（已按 [`KNOWN_LOADERS`] 过滤） + pub loaders: Vec, + /// 支持的游戏版本 + pub game_versions: Vec, + /// 项目类型原文 + pub project_type: String, + /// 图标 URL（`None` = 没有） + pub icon_url: Option, +} + +impl ProjectHit { + /// 支持某个加载器吗（空列表 = 站点没给，按「未知」处理 ⇒ 不拦）。 + #[must_use] + pub fn supports_loader(&self, loader: &str) -> bool { + self.loaders.is_empty() || self.loaders.iter().any(|item| item == loader) + } + + /// 支持某个游戏版本吗（空列表 = 未知 ⇒ 不拦）。 + #[must_use] + pub fn supports_version(&self, version: &str) -> bool { + self.game_versions.is_empty() || self.game_versions.iter().any(|item| item == version) + } +} + +/// 项目详情（`/v2/project/{id or slug}`）。 +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub struct ProjectDetail { + /// 项目 id + pub id: String, + /// slug + pub slug: String, + /// 标题 + pub title: String, + /// 简介 + pub description: String, + /// 长文（markdown 原文；站点可能给 `""`） + pub body: String, + /// 项目类型原文 + pub project_type: String, + /// 下载量 + pub downloads: u64, + /// 关注数 + pub follows: u64, + /// 最近更新 + pub updated: String, + /// 首次发布 + pub published: String, + /// 游戏版本 + pub game_versions: Vec, + /// 加载器 + pub loaders: Vec, + /// 分类标签 + pub categories: Vec, + /// 图标 + pub icon_url: Option, + /// 项目主页 + pub source_url: Option, + /// 问题追踪 + pub issues_url: Option, +} + +/// 版本类型。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub enum VersionType { + /// 正式版 + #[default] + Release, + /// 测试版 + Beta, + /// 早期预览 + Alpha, +} + +impl VersionType { + /// 站点原文。 + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::Release => "release", + Self::Beta => "beta", + Self::Alpha => "alpha", + } + } + + /// 从站点原文解析；认不出按正式版（**不**拿它做安装判据）。 + #[must_use] + pub fn parse(raw: &str) -> Self { + match raw { + "beta" => Self::Beta, + "alpha" => Self::Alpha, + _ => Self::Release, + } + } +} + +/// 前置依赖的类型（`/version` 的 `dependencies[].dependency_type`）。 +/// +/// # 为什么要留 `Unknown` 而不是「认不出就当可选」 +/// +/// 站点以后加新取值时，**只有 `Required` 才该触发递归**。认不出的值落进 `Unknown`， +/// 于是「站点改名」的下场是「少装一个前置」（可观察、可补），而不是「把所有建议项都当必备项 +/// 递归拉一遍」（一次装模组变成几十个请求，还装了一堆不兼容的东西）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)] +pub enum DependencyType { + /// 必须装（BFS **只跟这一档**） + Required, + /// 可选（装不装都能跑） + #[default] + Optional, + /// 明确不兼容（**不要**和它一起装） + Incompatible, + /// 已内嵌在被依赖的文件里（不用另外装） + Embedded, + /// 站点给了个我们不认识的取值 + Unknown, +} + +impl DependencyType { + /// 站点原文。 + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::Required => "required", + Self::Optional => "optional", + Self::Incompatible => "incompatible", + Self::Embedded => "embedded", + Self::Unknown => "unknown", + } + } + + /// 从站点原文解析；认不出（含空串）返回 [`Self::Unknown`]。 + #[must_use] + pub fn parse(raw: &str) -> Self { + match raw.trim() { + "required" => Self::Required, + "optional" => Self::Optional, + "incompatible" => Self::Incompatible, + "embedded" => Self::Embedded, + _ => Self::Unknown, + } + } +} + +/// 版本声明的一条前置（`dependencies[]`）。 +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub struct Dependency { + /// 依赖的**项目** id（BFS 的地址；有了它就不用像参考实现那样再查一次 slug） + pub project_id: Option, + /// 依赖的版本 id（站点基本只对 `embedded` 给） + pub version_id: Option, + /// 站点给的文件名（只对 `embedded` / `incompatible` 有意义） + pub file_name: Option, + /// 依赖类型 + pub dependency_type: DependencyType, +} + +/// 一个版本（`/v2/project/{id}/version[]` 与 `/v2/version_file/{hash}` 同一形状）。 +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub struct Version { + /// 版本 id + pub id: String, + /// 所属项目 id + pub project_id: String, + /// 版本名 + pub name: String, + /// 版本号（`1.2.3+fabric`） + pub version_number: String, + /// 版本类型 + pub version_type: VersionType, + /// 支持的加载器 + pub loaders: Vec, + /// 支持的游戏版本 + pub game_versions: Vec, + /// 发布日期 + pub date_published: String, + /// 该版本总下载量 + pub downloads: u64, + /// 文件列表 + pub files: Vec, + /// 前置声明（站点原文顺序；空 = 站点没说 / 没有） + pub dependencies: Vec, +} + +impl Version { + /// 拿这个文件：优先 `primary: true`（Modrinth 官方口径），否则第一个。 + /// + /// 不能无脑取第一个：很多项目同时发 `sources.jar` / `-dev.jar`，取第一个会装错东西。 + #[must_use] + pub fn primary_file(&self) -> Option<&VersionFile> { + self.files + .iter() + .find(|file| file.primary) + .or_else(|| self.files.first()) + } + + /// 要跟下去的**前置项目 id**：只取 `required`，去掉空值，**排序去重**。 + /// + /// 排序在这里做（不是让调用方排）：BFS 的展开顺序必须是数据本身决定的， + /// 否则站点把 `dependencies` 换个顺序、或者用 `HashMap` 收一遍，测试就会随机红。 + #[must_use] + pub fn required_project_ids(&self) -> Vec<&str> { + let mut ids: Vec<&str> = self + .dependencies + .iter() + .filter(|dependency| dependency.dependency_type == DependencyType::Required) + .filter_map(|dependency| dependency.project_id.as_deref()) + .map(str::trim) + .filter(|id| !id.is_empty()) + .collect(); + ids.sort_unstable(); + ids.dedup(); + ids + } + + /// 声明了 `required`、却**没有项目 id** 的前置（站点只给了版本 id / 文件名）。 + /// + /// 这些条目 BFS 跟不下去（取版本要项目 id），但也不能当成「没有这条依赖」—— + /// 上层据此说「有 N 条前置没法解析」，见 `DependencyPlan::unresolved_required`。 + #[must_use] + pub fn unresolved_required(&self) -> Vec<&Dependency> { + self.dependencies + .iter() + .filter(|dependency| dependency.dependency_type == DependencyType::Required) + .filter(|dependency| { + dependency + .project_id + .as_deref() + .map(str::trim) + .map(str::is_empty) + .unwrap_or(true) + }) + .collect() + } +} + +/// 版本里的一个文件。 +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub struct VersionFile { + /// 摘要表（键名小写：`sha1` / `sha512` / `md5`；站点给几个就有几个） + pub hashes: BTreeMap, + /// 下载地址 + pub url: String, + /// 文件名 + pub filename: String, + /// 字节数 + pub size: u64, + /// 是否主文件 + pub primary: bool, +} + +impl VersionFile { + /// 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) + } +} + +/// 摘要表（给需要「按算法取」的调用方用；与 [`VersionFile::hashes`] 同源）。 +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub struct FileHashes(pub BTreeMap); + +impl FileHashes { + /// 按算法取。 + #[must_use] + pub fn get(&self, algorithm: &str) -> Option<&str> { + self.0.get(algorithm).map(String::as_str) + } +} + +/// 版本列表请求（`/v2/project/{id}/version` 的过滤条件）。 +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub struct VersionQuery { + /// 项目 id 或 slug + pub project: String, + /// 游戏版本过滤（单个精确值） + pub game_version: Option, + /// 加载器过滤（站点 facet 值） + pub loader: Option, +} diff --git a/crates/core/src/addon/online/modrinth.rs b/crates/core/src/addon/online/modrinth.rs new file mode 100644 index 0000000..9183cd7 --- /dev/null +++ b/crates/core/src/addon/online/modrinth.rs @@ -0,0 +1,231 @@ +//! Modrinth v2 的四个端点（**只有一个站点，所以不做「源分派」那一层**）。 +//! +//! | 方法 | 端点 | 拿什么 | +//! |------|------|--------| +//! | [`Modrinth::search`] | `GET /v2/search` | 一页命中项（分页游标在 [`SearchQuery`] 里） | +//! | [`Modrinth::project`] | `GET /v2/project/{id or slug}` | 项目详情（含长文与链接） | +//! | [`Modrinth::versions`] | `GET /v2/project/{id}/version` | 版本列表（可按版本/加载器过滤） | +//! | [`Modrinth::version_by_hash`] | `GET /v2/version_file/{hash}` | 某个文件的所属版本（**补全路径用的那条**） | +//! +//! # 端点拼装与解析都分离出来 +//! +//! `*_url` 是纯函数（单测直接比字符串），`search/project/...` 只做「取文本 → 解析」。 +//! 于是录制 JSON 的离线夹具不需要任何 HTTP 桩就能覆盖全部分支。 +//! +//! # 为什么按摘要查是 GET +//! +//! Modrinth 的批量接口是 `POST /v2/version_files`（请求体是一个 JSON 对象）。引擎的 +//! `DownloadRequest` 没有请求体字段，为它单开一条直发 `client()` 的路径就得自己写退避与限流 +//! （presenter 里为 CF 的 header 已经付过这笔账）。补全路径一次只看一两个摘要，逐条 GET 更划算。 +//! +//! # 百分号编码 +//! +//! 只为 query 串写一个最小实现（`A-Za-z0-9-._~` 不编码），**不引第三方 crate**： +//! `facets` 与 `game_versions` 都是 JSON 文本，方括号引号逗号全要编码，否则站点会当成 +//! 空过滤条件静默忽略——那会让「筛选条说 Fabric、结果里有 Forge」这种谎话成立。 + +use super::model::{ + parse_project, parse_search, parse_version, parse_versions, ProjectDetail, SearchPage, + SearchQuery, Version, VersionQuery, +}; +use super::transport::{OnlineError, Transport}; + +/// Modrinth API 的根（匿名可用，无需 key）。 +pub const MODRINTH_API: &str = "https://api.modrinth.com/v2"; + +/// 按哪个摘要查文件。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub enum HashAlgorithm { + /// SHA-1（mrpack 的 `files[].hashes.sha1`） + #[default] + Sha1, + /// SHA-512（mrpack 的必填摘要） + Sha512, +} + +impl HashAlgorithm { + /// 站点 `algorithm` 参数值。 + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::Sha1 => "sha1", + Self::Sha512 => "sha512", + } + } + + /// 十六进制长度（格式自检用；长度不对就别发请求）。 + #[must_use] + pub const fn hex_len(self) -> usize { + match self { + Self::Sha1 => 40, + Self::Sha512 => 128, + } + } + + /// 摘要是否**形状**合法（小写归一 + 十六进制 + 长度）。 + #[must_use] + pub fn accepts(self, hex: &str) -> bool { + hex.len() == self.hex_len() && hex.bytes().all(|byte| byte.is_ascii_hexdigit()) + } +} + +/// Modrinth 客户端（只持有 [`Transport`]，不持有客户端/连接池）。 +#[derive(Debug, Clone, Copy)] +pub struct Modrinth<'a, T: Transport + ?Sized> { + transport: &'a T, +} + +impl<'a, T: Transport + ?Sized> Modrinth<'a, T> { + /// 绑定传输层。 + #[must_use] + pub const fn new(transport: &'a T) -> Self { + Self { transport } + } + + /// 检索的 URL（纯函数，单测直接钉）。 + #[must_use] + pub fn search_url(&self, query: &SearchQuery) -> String { + let query = query.normalized(); + let mut url = format!( + "{MODRINTH_API}/search?limit={}&offset={}&index={}", + query.limit, + query.offset, + query.index.as_str() + ); + let facets = query.facets(); + if facets != "[]" { + url.push_str(&format!("&facets={}", encode(&facets))); + } + if !query.text.is_empty() { + url.push_str(&format!("&query={}", encode(&query.text))); + } + url + } + + /// 项目详情的 URL。 + #[must_use] + pub fn project_url(&self, id_or_slug: &str) -> String { + format!("{MODRINTH_API}/project/{}", encode(id_or_slug)) + } + + /// 版本列表的 URL。 + #[must_use] + pub fn versions_url(&self, query: &VersionQuery) -> String { + let mut url = format!("{MODRINTH_API}/project/{}/version", encode(&query.project)); + let mut first = true; + if let Some(version) = query + .game_version + .as_deref() + .filter(|item| !item.is_empty()) + { + url.push_str(&format!( + "{}game_versions={}", + separator(&mut first), + encode(&format!("[\"{version}\"]")) + )); + } + if let Some(loader) = query.loader.as_deref().filter(|item| !item.is_empty()) { + url.push_str(&format!( + "{}loaders={}", + separator(&mut first), + encode(&format!("[\"{loader}\"]")) + )); + } + url + } + + /// 按文件摘要查所属版本的 URL。 + #[must_use] + pub fn version_file_url(&self, algorithm: HashAlgorithm, hex: &str) -> String { + format!( + "{MODRINTH_API}/version_file/{}?algorithm={}", + encode(&hex.to_ascii_lowercase()), + algorithm.as_str() + ) + } + + /// 检索一页。 + /// + /// # Errors + /// 传输层失败（见 [`OnlineErrorKind`]）或响应形状不符。 + pub async fn search(&self, query: &SearchQuery) -> Result { + let normalized = query.normalized(); + let url = self.search_url(&normalized); + let body = self.transport.get_text(&url).await?; + let mut page = parse_search(&body, normalized.offset, normalized.limit)?; + // 站点没回显时用请求值补齐，分页游标才不会因为缺字段而卡死。 + if page.limit == 0 { + page.limit = normalized.limit; + } + Ok(page) + } + + /// 项目详情。 + /// + /// # Errors + /// 传输层失败或响应形状不符。 + pub async fn project(&self, id_or_slug: &str) -> Result { + let url = self.project_url(id_or_slug); + let body = self.transport.get_text(&url).await?; + parse_project(&body) + } + + /// 版本列表（站点的顺序 = 最新在前）。 + /// + /// # Errors + /// 传输层失败或响应形状不符。 + pub async fn versions(&self, query: &VersionQuery) -> Result, OnlineError> { + let url = self.versions_url(query); + let body = self.transport.get_text(&url).await?; + parse_versions(&body) + } + + /// 按文件摘要查所属版本。 + /// + /// # Errors + /// 摘要形状不对时**不发请求**（[`OnlineErrorKind::Unsupported`]）；站点 404 是 + /// [`OnlineErrorKind::NotFound`]（= 这个摘要不在 Modrinth 上，补全要如实记「补不出」）。 + pub async fn version_by_hash( + &self, + algorithm: HashAlgorithm, + hex: &str, + ) -> Result { + let hex = hex.trim(); + if !algorithm.accepts(hex) { + return Err(OnlineError::unsupported(format!( + "摘要不是合法的 {}：长度 {}，要求 {}", + algorithm.as_str(), + hex.len(), + algorithm.hex_len() + ))); + } + let url = self.version_file_url(algorithm, hex); + let body = self.transport.get_text(&url).await?; + parse_version(&body) + } +} + +/// 第一个参数用 `?`，后续用 `&`。 +fn separator(first: &mut bool) -> &'static str { + if *first { + *first = false; + "?" + } else { + "&" + } +} + +/// 最小百分号编码（query 串用；`A-Za-z0-9-._~` 原样，其余按字节编码）。 +#[must_use] +pub 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/core/src/addon/online/resolve.rs b/crates/core/src/addon/online/resolve.rs new file mode 100644 index 0000000..16966c7 --- /dev/null +++ b/crates/core/src/addon/online/resolve.rs @@ -0,0 +1,303 @@ +//! BFS 依赖解析（**只跟 `required`**）。形状在 [`super::dependency`]，这里只有算法。 +//! +//! # 与参考实现（Python 版 Modrinth 下载器）的四处差别 +//! +//! | 参考实现 | 这里 | 为什么 | +//! |---|---|---| +//! | 每个前置再 `GET /v2/project/{id}` 换 slug | **不查**，直接拿 `dependencies[].project_id` 当地址 | 依赖里给的就是项目 id，`/project/{id}/version` 认它；一次安装省掉每个前置一个请求 | +//! | 失败名单是字符串，靠括号里的中文区分「不兼容」与「网络异常」 | [`FailureKind`] 枚举 | 「哪一档」要能从类型上判，不能靠 `contains("网络")` | +//! | 一个 dict 兼做缓存与去重 | 键 = **规范项目 id**，别名单设一张表 | 同一项目可能一次以 slug、一次以 id 出现；只按请求串去重会把它装两遍 | +//! | 队列按 `dependencies` 原文顺序展开 | 每层按项目键**字典序**处理 | 顺序必须是数据决定的，否则测试靠 HashMap 运气 | +//! +//! # 失败是**数据**，不是 `Err` +//! +//! [`resolve`] 永远返回一个 [`DependencyPlan`]：某个前置取不到版本时，它进 `failures`， +//! 解析继续做别的分支。若中途 `return Err`，用户看到的是「装这个模组失败」，而真正该看到的 +//! 是「主文件装上了，缺 fabric-api（不兼容 1.20.1/fabric）」＋一份可单独重试的名单。 +//! +//! # 两张去重网 +//! +//! 1. **图内**：同一项目只解一次版本（`nodes` 里每个项目最多一条），多条依赖路径折进 +//! [`PlannedNode::required_by`]； +//! 2. **盘上**：目标目录里已经有同名文件（`.disabled` 也算）就进 `skipped`、**不再下载**。 +//! 这是「已装过的同一项目跳过并提示」里我们真能判的那一半；另一半（同项目**另一个版本** +//! 已装）需要实例侧的已装清单，本模块判不出来（见报告）。 +//! +//! 盘上判定只比文件名（`present` 由调用方扫目录得到，core 不读盘）：内容级去重需要先算一份 +//! sha1，为了「跳过」把整个 `mods/` 哈希一遍不划算；同名文件就是同一份 jar 的最常见形态 +//! （我们落盘用站点给的文件名，不重命名）。 + +use std::collections::{BTreeMap, BTreeSet}; + +use super::dependency::{ + present_key, DependencyFailure, DependencyPlan, FailureKind, PlannedNode, PresentFile, + ResolveRequest, SkipReason, SkippedNode, UnresolvedRequired, +}; +use super::model::Version; +use super::modrinth::Modrinth; +use super::transport::{OnlineErrorKind, Transport}; + +/// 一层里还没处理的一项。 +struct Wave { + key: String, + depth: u8, + parents: Vec, +} + +/// BFS 解析。**不返回 `Err`**：失败进 [`DependencyPlan::failures`]（见模块文档）。 +pub async fn resolve( + client: &Modrinth<'_, T>, + request: &ResolveRequest, +) -> DependencyPlan { + let mut plan = DependencyPlan::new(request); + let present: BTreeSet = request.present.iter().map(PresentFile::key).collect(); + // 请求键 → 规范 id（同一项目可能一次给 slug、一次给 id） + let mut alias: BTreeMap = BTreeMap::new(); + let mut resolved: BTreeSet = BTreeSet::new(); + + let mut layer: Vec = Vec::new(); + for root in &request.roots { + let key = root.trim(); + if !key.is_empty() { + wave_in(&mut layer, key, 0, None); + } + } + + while !layer.is_empty() { + // 同层按项目键字典序：顺序由数据决定，不靠插入顺序或 HashMap 的运气。 + layer.sort_by(|left, right| left.key.cmp(&right.key)); + let mut next: Vec = Vec::new(); + for mut item in layer.drain(..) { + normalize(&mut item.parents); + // ① 已经解过（含「A 依赖 B、B 又依赖 A」的环）⇒ 只把父边折进已有节点 + if let Some(canonical) = alias.get(&item.key).cloned() { + fold_parents(&mut plan, &canonical, &item.parents); + continue; + } + let version = match client.versions(&request.version_query(&item.key)).await { + Ok(versions) => match versions.into_iter().next() { + Some(version) => version, + None => { + let message = filter_message(request); + fail( + &mut plan, + &mut alias, + item, + FailureKind::Incompatible, + None, + message, + ); + continue; + } + }, + Err(error) => { + let message = format!( + "取版本失败（{}）：{}", + error.kind().as_str(), + error.message() + ); + fail( + &mut plan, + &mut alias, + item, + FailureKind::Unreachable, + Some(error.kind()), + message, + ); + continue; + } + }; + let Some(file) = version + .primary_file() + .filter(|file| !file.url.trim().is_empty()) + .cloned() + else { + let message = format!( + "{} 的版本 {} 里没有可下载的主文件", + item.key, + version_label(&version) + ); + fail( + &mut plan, + &mut alias, + item, + FailureKind::Incompatible, + None, + message, + ); + continue; + }; + + let canonical = canonical_of(&item.key, &version); + alias.insert(item.key.clone(), canonical.clone()); + alias + .entry(canonical.clone()) + .or_insert_with(|| canonical.clone()); + // ② 同一项目走了两条路（slug 与 id 各一次）⇒ 折边，不重复装 + if !resolved.insert(canonical.clone()) { + fold_parents(&mut plan, &canonical, &item.parents); + continue; + } + + let file_name = file.filename.clone(); + if present.contains(&present_key(&file_name)) { + plan.skipped.push(SkippedNode { + project: canonical.clone(), + requested_as: item.key.clone(), + file_name, + depth: item.depth, + required_by: item.parents.clone(), + reason: SkipReason::AlreadyPresent, + }); + } else { + plan.nodes.push(PlannedNode { + project: canonical.clone(), + requested_as: item.key.clone(), + version_id: version.id.clone(), + version_name: version.name.clone(), + version_number: version.version_number.clone(), + file, + depth: item.depth, + required_by: item.parents.clone(), + }); + } + + // 子项：只跟 required（排序去重由 `required_project_ids` 保证） + for dependency in version.required_project_ids() { + if item.depth >= request.max_depth { + plan.truncated.push(dependency.to_string()); + } else { + wave_in(&mut next, dependency, item.depth + 1, Some(&canonical)); + } + } + // 只有版本 id、没有项目 id 的 required：没有地址可取，记下来不假装没看见 + for dependency in version.unresolved_required() { + plan.unresolved_required.push(UnresolvedRequired { + parent: canonical.clone(), + version_id: dependency.version_id.clone(), + file_name: dependency.file_name.clone(), + }); + } + } + plan.truncated.sort(); + plan.truncated.dedup(); + layer = next; + } + + plan.unresolved_required.sort_by(|left, right| { + (&left.parent, &left.version_id).cmp(&(&right.parent, &right.version_id)) + }); + plan.unresolved_required.dedup(); + plan +} + +/// 记一条失败，并把这个请求键标成「已处理」。 +/// +/// 标键这一步是**失败侧的去重网**：成功路径靠 `alias` 短路，失败路径以前直接 `continue`， +/// 于是同一个项目被两条路径要求时会各取一次版本、各记一条失败，重试名单里出现两次。 +/// 标记之后，后续同键请求在①处短路，走现成的 [`fold_parents`] 把父边折进那条失败。 +/// +/// # 这道去重按**请求键**，不是规范 id（已知边界，别当成全覆盖） +/// +/// 规范 id（`project_id`）要拿到响应才知道；失败时没有响应，能用的只有请求键。所以同一个 +/// 失败项目如果**先以 slug、后以 project_id** 被两个不同的父项目要求，仍会被取两次、名单里 +/// 出现两个名字。真实载荷里 `dependencies[].project_id` 与用户点的 slug 混用的情况没有证据， +/// 且这一档本来就是「取不到」，重复一条的代价是名单多一行、不是多装一个东西——故本轮不消掉， +/// 只把边界写在这里（复审 r2 nit③）。 +fn fail( + plan: &mut DependencyPlan, + alias: &mut BTreeMap, + item: Wave, + kind: FailureKind, + cause: Option, + message: String, +) { + plan.record_failure(DependencyFailure { + requested_as: item.key.clone(), + required_by: item.parents, + depth: item.depth, + kind, + cause, + message, + }); + alias.insert(item.key.clone(), item.key); +} + +/// 把一项放进这一层的待处理表（同一个键已经排队 ⇒ 只追加父项目）。 +fn wave_in(layer: &mut Vec, key: &str, depth: u8, parent: Option<&str>) { + if let Some(existing) = layer.iter_mut().find(|item| item.key == key) { + if let Some(parent) = parent { + existing.parents.push(parent.to_string()); + } + return; + } + layer.push(Wave { + key: key.to_string(), + depth, + parents: parent + .map(|parent| vec![parent.to_string()]) + .unwrap_or_default(), + }); +} + +/// 往已经建好的节点上折一条父边（节点可能在被跳过的那一档，也可能只出现在失败名单里）。 +fn fold_parents(plan: &mut DependencyPlan, project: &str, parents: &[String]) { + if parents.is_empty() { + return; + } + let node = plan + .nodes + .iter_mut() + .find(|node| node.project == project) + .map(|node| &mut node.required_by); + let node = node.or_else(|| { + plan.skipped + .iter_mut() + .find(|node| node.project == project) + .map(|node| &mut node.required_by) + }); + if let Some(required_by) = node { + required_by.extend(parents.iter().cloned()); + normalize(required_by); + return; + } + if let Some(failure) = plan + .failures + .iter_mut() + .find(|failure| failure.requested_as == project) + { + failure.required_by.extend(parents.iter().cloned()); + normalize(&mut failure.required_by); + } +} + +fn normalize(list: &mut Vec) { + list.sort(); + list.dedup(); +} + +/// 规范身份：站点回的 `project_id` 才是身份；没给就退回请求键。 +fn canonical_of(key: &str, version: &Version) -> String { + let project_id = version.project_id.trim(); + if project_id.is_empty() { + key.to_string() + } else { + project_id.to_string() + } +} + +/// 「哪里没有匹配项」这句话（第一档的固定说法，带出用的是什么过滤条件）。 +fn filter_message(request: &ResolveRequest) -> String { + let game_version = request.game_version.as_deref().unwrap_or("不限"); + let loader = request.loader.as_deref().unwrap_or("不限"); + format!("没有匹配所选游戏版本/加载器（{game_version} / {loader}）的版本") +} + +fn version_label(version: &Version) -> String { + let number = version.version_number.trim(); + if number.is_empty() { + version.id.clone() + } else { + number.to_string() + } +} diff --git a/crates/core/src/addon/online/tests/api.rs b/crates/core/src/addon/online/tests/api.rs new file mode 100644 index 0000000..38ea9d5 --- /dev/null +++ b/crates/core/src/addon/online/tests/api.rs @@ -0,0 +1,205 @@ +//! 端点拼装 + 响应解析 + 离线分类（纯离线）。 + +use crate::addon::online::modrinth::{encode, HashAlgorithm, MODRINTH_API}; +use crate::addon::online::{ + ContentType, Modrinth, OnlineErrorKind, SearchQuery, SortIndex, VersionQuery, +}; +use crate::download::blocking::block_on; + +use super::fixtures; +use super::support::FixtureTransport; + +fn query(text: &str) -> SearchQuery { + SearchQuery { + text: text.to_string(), + project_type: Some(ContentType::Mod), + game_version: Some("1.20.1".to_string()), + loader: Some("fabric".to_string()), + index: SortIndex::Downloads, + limit: 2, + offset: 0, + } +} + +#[test] +fn search_url_carries_facets_and_query_in_the_sites_own_shape() { + let transport = FixtureTransport::new(); + let client = Modrinth::new(&transport); + let url = client.search_url(&query("sodium edge")); + assert!(url.starts_with(&format!( + "{MODRINTH_API}/search?limit=2&offset=0&index=downloads" + ))); + // 站点要的是二维数组的 JSON，再整体百分号编码 + let facets = encode(&query("").facets()); + assert!(url.contains(&format!("&facets={facets}")), "url={url}"); + assert!(facets.contains("%5B%5B%22project_type%3Amod%22%5D")); + assert!(url.ends_with("&query=sodium%20edge")); +} + +#[test] +fn empty_text_omits_the_query_parameter() { + let transport = FixtureTransport::new(); + let client = Modrinth::new(&transport); + let url = client.search_url(&SearchQuery::default()); + assert!(!url.contains("&query="), "空关键词不该带 query：{url}"); + assert!( + !url.contains("&facets="), + "没有过滤条件不该带 facets：{url}" + ); +} + +#[test] +fn search_parses_hits_and_filters_fake_loaders() { + let transport = + FixtureTransport::new().with(&format!("{MODRINTH_API}/search"), fixtures::SEARCH); + let client = Modrinth::new(&transport); + let page = block_on(client.search(&query("sodium"))).expect("解析应当成功"); + assert_eq!(page.total_hits, 1234); + assert_eq!(page.hits.len(), 2); + let sodium = &page.hits[0]; + assert_eq!(sodium.project_id, "AANobbMI"); + assert_eq!(sodium.title, "Sodium"); + // `optimization` 不是加载器：只留 fabric / quilt + assert_eq!( + sodium.loaders, + vec!["fabric".to_string(), "quilt".to_string()] + ); + assert!(sodium.supports_version("1.20.1")); + assert!(!sodium.supports_version("1.19.2")); + // 日期读的是 `date_modified`（旧实现读 `updated`，永远是空串） + assert_eq!(sodium.updated, "2026-02-03T10:11:12Z"); + // 空 icon_url 当「没有」 + assert_eq!(page.hits[1].icon_url, None); + // limit=2 且回了 2 条 ⇒ 本页装满 ⇒ 还有下一页（判据不是 total_hits） + assert!(page.has_more()); +} + +#[test] +fn has_more_is_decided_by_a_full_page() { + let mut page = crate::addon::online::SearchPage { + limit: 2, + hits: vec![Default::default(), Default::default()], + ..Default::default() + }; + assert!(page.has_more()); + page.hits.pop(); + assert!(!page.has_more()); +} + +#[test] +fn project_detail_parses_body_links_and_loader_list() { + let transport = + FixtureTransport::new().with(&format!("{MODRINTH_API}/project/sodium"), fixtures::PROJECT); + let client = Modrinth::new(&transport); + let project = block_on(client.project("sodium")).expect("解析应当成功"); + assert_eq!(project.id, "AANobbMI"); + assert_eq!(project.follows, 9912); + assert!(project.body.contains("modern rendering engine")); + assert_eq!( + project.loaders, + vec!["fabric".to_string(), "quilt".to_string()] + ); + assert_eq!( + project.source_url.as_deref(), + Some("https://github.com/CaffeineMC/sodium") + ); +} + +#[test] +fn version_list_prefers_the_primary_file() { + let transport = FixtureTransport::new().with( + &format!("{MODRINTH_API}/project/sodium/version"), + fixtures::VERSIONS, + ); + let client = Modrinth::new(&transport); + let versions = block_on(client.versions(&VersionQuery { + project: "sodium".to_string(), + game_version: Some("1.21.1".to_string()), + loader: Some("fabric".to_string()), + })) + .expect("解析应当成功"); + assert_eq!(versions.len(), 1); + let file = versions[0].primary_file().expect("必须有文件"); + // 取第一个会拿到 sources.jar：必须是 primary 的那个 + assert_eq!(file.filename, "sodium-fabric-0.6.0.jar"); + assert_eq!(file.size, 2048); + // 版本列表请求带了两个数组参数（不是被静默丢掉的空过滤） + let seen = transport.seen(); + assert!( + seen[0].contains("game_versions=%5B%221.21.1%22%5D"), + "{}", + seen[0] + ); + assert!( + seen[0].contains("loaders=%5B%22fabric%22%5D"), + "{}", + seen[0] + ); +} + +#[test] +fn a_hash_shape_mismatch_never_hits_the_network() { + let transport = FixtureTransport::new(); + let client = Modrinth::new(&transport); + let error = block_on(client.version_by_hash(HashAlgorithm::Sha512, "not-a-hash")) + .expect_err("形状不对必须报错"); + assert_eq!(error.kind(), OnlineErrorKind::Unsupported); + assert!( + transport.seen().is_empty(), + "不该发请求：{:?}", + transport.seen() + ); +} + +#[test] +fn offline_is_reported_as_not_connected_not_as_an_empty_page() { + let transport = FixtureTransport::new().offline(&format!("{MODRINTH_API}/search")); + let client = Modrinth::new(&transport); + let error = block_on(client.search(&query("sodium"))).expect_err("没网必须报错"); + assert_eq!(error.kind(), OnlineErrorKind::NotConnected); + assert!(error.is_offline()); +} + +#[test] +fn a_broken_payload_is_malformed_not_empty() { + let transport = + FixtureTransport::new().with(&format!("{MODRINTH_API}/search"), "{\"hits\": 3}"); + let client = Modrinth::new(&transport); + let error = block_on(client.search(&query("sodium"))).expect_err("形状不对必须报错"); + assert_eq!(error.kind(), OnlineErrorKind::Malformed); +} + +// ------------------------------------------------ 按摘要反查（补全路径的那两个端点行为） + +#[test] +fn version_file_lookup_parses_the_recorded_payload() { + let transport = FixtureTransport::new().with( + &format!("{MODRINTH_API}/version_file/"), + fixtures::VERSION_FILE_A, + ); + let client = Modrinth::new(&transport); + let version = block_on(client.version_by_hash(HashAlgorithm::Sha512, fixtures::LOOKUP_SHA512)) + .expect("录制响应应当解析成功"); + assert_eq!(version.id, "ver-a"); + assert_eq!(version.game_versions, vec!["1.20.1".to_string()]); + + // 身份判定只认「sha512 逐字相同」的那条：同版本里的 sources.jar 不许被当成它 + let identity = crate::addon::online::complete::identity_of(&version, fixtures::LOOKUP_SHA512) + .expect("摘要对得上就该给出身份"); + assert_eq!(identity.sha1, fixtures::LOOKUP_SHA1); + assert_eq!(identity.size, Some(4096)); + let other = crate::addon::online::complete::identity_of(&version, fixtures::OTHER_SHA512) + .expect("另一个文件也认得出来"); + assert_ne!(other.sha1, fixtures::LOOKUP_SHA1, "两档摘要不许串"); +} + +#[test] +fn a_hash_the_source_does_not_know_is_not_found_and_not_offline() { + // 真实 mrpack 大多托管在 CurseForge CDN：Modrinth 对这个 sha512 必然 404。 + let transport = FixtureTransport::new().missing(&format!("{MODRINTH_API}/version_file/")); + let client = Modrinth::new(&transport); + let error = block_on(client.version_by_hash(HashAlgorithm::Sha512, &"a1".repeat(64))) + .expect_err("站点不认得就该报错"); + assert_eq!(error.kind(), OnlineErrorKind::NotFound); + assert!(!error.is_offline(), "404 不是「没联网」"); +} diff --git a/crates/core/src/addon/online/tests/classify.rs b/crates/core/src/addon/online/tests/classify.rs new file mode 100644 index 0000000..657f60c --- /dev/null +++ b/crates/core/src/addon/online/tests/classify.rs @@ -0,0 +1,89 @@ +//! 引擎错误 → 在线内容源错误分类（r1 P1-1 的守卫）。 +//! +//! 这一族的价值全在「经过真的 `From`」：直接给 `OnlineError` 造一个 +//! `NotFound` 什么也证明不了——本轮修的是**引擎把叶子成因折叠掉**之后上层的映射， +//! 所以输入必须是引擎真会产出的那种错误（`AllSourcesFailed` + `leaf`）。 + +use crate::addon::online::{OnlineError, OnlineErrorKind}; +use crate::download::{DownloadError, DownloadErrorKind}; + +#[test] +fn an_all_sources_failed_with_a_404_leaf_is_not_found() { + // 引擎在「所有候选源都回 404」时的真实形状（`download::bytes` 的收尾）。 + let error = DownloadError::new( + DownloadErrorKind::AllSourcesFailed, + "所有候选源都取不到文本资源：https://api.modrinth.com/v2/version_file/...", + ) + .with_suppressed(vec!["official: HTTP 404".to_string()]) + .with_leaf(DownloadErrorKind::NotFound); + let online: OnlineError = error.into(); + assert_eq!( + online.kind(), + OnlineErrorKind::NotFound, + "项目不存在 / id 拼错必须报 NotFound，不能画成「未联网」" + ); + assert!(!online.is_offline()); +} + +#[test] +fn an_all_sources_failed_without_a_leaf_stays_conservatively_offline() { + let online: OnlineError = + DownloadError::new(DownloadErrorKind::AllSourcesFailed, "全部候选源都失败").into(); + assert_eq!(online.kind(), OnlineErrorKind::NotConnected); + assert!(online.is_offline()); +} + +#[test] +fn leaf_kinds_map_one_to_one() { + let cases = [ + (DownloadErrorKind::NotFound, OnlineErrorKind::NotFound), + (DownloadErrorKind::ServerError, OnlineErrorKind::Server), + (DownloadErrorKind::Timeout, OnlineErrorKind::NotConnected), + (DownloadErrorKind::Network, OnlineErrorKind::NotConnected), + (DownloadErrorKind::Integrity, OnlineErrorKind::Integrity), + (DownloadErrorKind::Io, OnlineErrorKind::Io), + ( + DownloadErrorKind::InvalidRequest, + OnlineErrorKind::Unsupported, + ), + ( + DownloadErrorKind::RangeUnsupported, + OnlineErrorKind::Malformed, + ), + ]; + for (leaf, expected) in cases { + let error = + DownloadError::new(DownloadErrorKind::AllSourcesFailed, "全部失败").with_leaf(leaf); + let online: OnlineError = error.into(); + assert_eq!(online.kind(), expected, "叶子 {} 映射错了", leaf.as_str()); + } +} + +#[test] +fn a_single_source_failure_uses_its_own_kind() { + // 单源直失败（没有 AllSourcesFailed 这一层）：不该看 leaf，本来就没有。 + let online: OnlineError = DownloadError::new(DownloadErrorKind::NotFound, "HTTP 404").into(); + assert_eq!(online.kind(), OnlineErrorKind::NotFound); +} + +#[test] +fn a_404_leaf_is_not_treated_as_offline_by_the_importer_too() { + // 导入侧（补全）用的是另一套分类：这里只钉「404 与没联网不同类」。 + use crate::addon::import::FetchErrorKind; + let not_found: crate::addon::import::FetchError = + DownloadError::new(DownloadErrorKind::AllSourcesFailed, "全部失败") + .with_leaf(DownloadErrorKind::NotFound) + .into(); + assert_eq!(not_found.kind(), FetchErrorKind::NotFound); + assert!(not_found.kind().is_tolerable()); + + let offline: crate::addon::import::FetchError = + DownloadError::new(DownloadErrorKind::AllSourcesFailed, "全部失败") + .with_leaf(DownloadErrorKind::Network) + .into(); + assert_eq!(offline.kind(), FetchErrorKind::Offline); + assert!( + offline.kind().is_tolerable(), + "没联网仍然是「这条文件搞不到」，实例照装" + ); +} diff --git a/crates/core/src/addon/online/tests/dependency.rs b/crates/core/src/addon/online/tests/dependency.rs new file mode 100644 index 0000000..1a75948 --- /dev/null +++ b/crates/core/src/addon/online/tests/dependency.rs @@ -0,0 +1,306 @@ +//! 依赖解析的离线用例（录制 JSON 夹具，**不打真实网络**）。 +//! +//! 三条守门对应任务书的三条： +//! 1. [`two_nested_levels_are_pulled_in_a_predictable_order`] —— 嵌套两层能拉全，顺序确定； +//! 2. [`a_dependency_cycle_terminates_and_each_project_appears_once`] —— 环不无限递归； +//! 3. [`an_incompatible_dependency_lands_in_the_retry_list`] —— 不兼容进重试名单，不静默丢。 +//! +//! 每条都配过一次「把实现改坏就该红」的变异（过程写在 M186 报告里），所以断言不是装饰。 + +use crate::addon::online::dependency::{ + present_key, DependencyPlan, FailureKind, PresentFile, ResolveRequest, SkipReason, +}; +use crate::addon::online::model::parse_versions; +use crate::addon::online::{resolve, Modrinth, OnlineErrorKind, MODRINTH_API}; +use crate::download::blocking::block_on; + +use super::fixtures_deps as deps; +use super::support::FixtureTransport; + +const SODIUM_VERSIONS: &str = "https://api.modrinth.com/v2/project/sodium/version"; +const FABRIC_API_VERSIONS: &str = "https://api.modrinth.com/v2/project/P7dR8mSH/version"; +const YACL_VERSIONS: &str = "https://api.modrinth.com/v2/project/1eAoo2KR/version"; + +fn request(root: &str) -> ResolveRequest { + ResolveRequest { + roots: vec![root.to_string()], + game_version: Some("1.20.1".to_string()), + loader: Some("fabric".to_string()), + ..ResolveRequest::default() + } +} + +/// 三层链的传输层（sodium → fabric-api → yacl）。 +fn chain_transport() -> FixtureTransport { + FixtureTransport::new() + .with(SODIUM_VERSIONS, deps::SODIUM_WITH_DEPENDENCIES) + .with(FABRIC_API_VERSIONS, deps::FABRIC_API_WITH_DEPENDENCIES) + .with(YACL_VERSIONS, deps::YACL) +} + +fn resolve_with(transport: &FixtureTransport, request: &ResolveRequest) -> DependencyPlan { + let client = Modrinth::new(transport); + block_on(resolve(&client, request)) +} + +// ---------------------------------------------------------------- ① 嵌套两层 + +#[test] +fn two_nested_levels_are_pulled_in_a_predictable_order() { + let transport = chain_transport(); + let plan = resolve_with(&transport, &request("sodium")); + + assert!(plan.is_clean(), "不该有失败：{:?}", plan.failures); + // 顺序 = BFS 层序，同层按项目键字典序：根 → fabric-api → yacl + let order: Vec<(&str, u8)> = plan + .nodes + .iter() + .map(|node| (node.project.as_str(), node.depth)) + .collect(); + assert_eq!( + order, + vec![("AANobbMI", 0), ("P7dR8mSH", 1), ("1eAoo2KR", 2)] + ); + + // 「为什么装」：父子关系逐条对得上 + assert!(plan.required_by("AANobbMI").expect("根在计划里").is_empty()); + assert_eq!( + plan.required_by("P7dR8mSH").expect("fabric-api 在计划里"), + ["AANobbMI".to_string()].as_slice() + ); + assert_eq!( + plan.required_by("1eAoo2KR").expect("yacl 在计划里"), + ["P7dR8mSH".to_string()].as_slice() + ); + + // 只跟 required：optional / incompatible / embedded 三个 id 一次请求都没发 + let seen = transport.seen(); + assert_eq!(seen.len(), 3, "只该有 3 次版本请求：{seen:?}"); + for quiet in ["OCS3z7f6", "AAAABBBB", "embedded-lib"] { + assert!( + !seen.iter().any(|url| url.contains(quiet)), + "{quiet} 不该被跟：{seen:?}" + ); + } + + // 主文件取 primary（第一个是 sources.jar） + assert_eq!(plan.nodes[0].file.filename, "sodium-fabric-0.6.0.jar"); + assert_eq!(plan.nodes[1].file.filename, "fabric-api-0.92.2+1.20.1.jar"); +} + +#[test] +fn only_required_dependencies_are_followed() { + // 模型层：四值都解析得出来，`required_project_ids` 只吐 required 那一条。 + let versions = parse_versions(deps::SODIUM_WITH_DEPENDENCIES).expect("夹具该解析成功"); + let version = &versions[0]; + assert_eq!(version.dependencies.len(), 4); + let kinds: Vec<&str> = version + .dependencies + .iter() + .map(|dependency| dependency.dependency_type.as_str()) + .collect(); + assert_eq!(kinds, ["required", "optional", "incompatible", "embedded"]); + assert_eq!(version.required_project_ids(), ["P7dR8mSH"]); + // embedded 那条只有 file_name、没有 project_id，不该冒出一个空 id + assert!(version.dependencies[3].project_id.is_none()); +} + +#[test] +fn the_depth_limit_is_reported_instead_of_silently_cutting_the_chain() { + let transport = chain_transport(); + let mut request = request("sodium"); + request.max_depth = 1; + let plan = resolve_with(&transport, &request); + + assert_eq!(plan.nodes.len(), 2, "根 + 第一层"); + assert_eq!(plan.truncated, ["1eAoo2KR"], "截断必须写在计划里"); +} + +// ---------------------------------------------------------------- ② 环 + +#[test] +fn a_dependency_cycle_terminates_and_each_project_appears_once() { + let transport = FixtureTransport::new() + .with( + "https://api.modrinth.com/v2/project/cycle-a/version", + deps::CYCLE_A, + ) + .with( + "https://api.modrinth.com/v2/project/cycBid01/version", + deps::CYCLE_B, + ); + let plan = resolve_with(&transport, &request("cycle-a")); + + let projects: Vec<&str> = plan + .nodes + .iter() + .map(|node| node.project.as_str()) + .collect(); + assert_eq!(projects, ["cycAid01", "cycBid01"], "每个项目只出现一次"); + assert_eq!(transport.seen().len(), 2, "环不许把请求数放大"); + // B 是被 A 要来的；A 又被 B 要（环）——这条边折回已有节点，不新建节点 + assert_eq!( + plan.required_by("cycBid01").expect("B 在计划里"), + ["cycAid01".to_string()].as_slice() + ); + assert_eq!( + plan.required_by("cycAid01").expect("A 在计划里"), + ["cycBid01".to_string()].as_slice() + ); + assert!(plan.nodes[0].is_root(), "根判据是 depth，不是 required_by"); + assert!(!plan.nodes[1].is_root()); +} + +// ---------------------------------------------------------------- ③ 两档失败 + +#[test] +fn an_incompatible_dependency_lands_in_the_retry_list() { + // fabric-api 在 1.20.1/fabric 下没有条目（站点回空数组） + let transport = FixtureTransport::new() + .with(SODIUM_VERSIONS, deps::SODIUM_WITH_DEPENDENCIES) + .with(FABRIC_API_VERSIONS, "[]"); + let plan = resolve_with(&transport, &request("sodium")); + + // 根还在计划里（失败不连坐），缺的那条单独立案 + assert_eq!(plan.nodes.len(), 1); + assert_eq!(plan.failures.len(), 1, "不许静默丢：{:?}", plan.failures); + let failure = &plan.failures[0]; + assert_eq!(failure.kind, FailureKind::Incompatible); + assert_eq!(failure.requested_as, "P7dR8mSH"); + assert_eq!(failure.depth, 1); + assert_eq!(failure.required_by, ["AANobbMI".to_string()]); + assert!(failure.cause.is_none(), "这一档不是网络成因"); + assert!(failure.message.contains("1.20.1"), "文案要带过滤条件"); + assert!(plan.failures_of(FailureKind::Unreachable).next().is_none()); + + // 可重试名单只含失败项，过滤条件沿用 + let retry = plan.retry_request(); + assert_eq!(retry.roots, ["P7dR8mSH"]); + assert_eq!(retry.game_version.as_deref(), Some("1.20.1")); + assert_eq!(retry.loader.as_deref(), Some("fabric")); +} + +#[test] +fn a_missing_project_is_unreachable_and_keeps_its_leaf_cause() { + let transport = FixtureTransport::new() + .with(SODIUM_VERSIONS, deps::SODIUM_WITH_DEPENDENCIES) + .missing(FABRIC_API_VERSIONS); + let plan = resolve_with(&transport, &request("sodium")); + + let failure = &plan.failures[0]; + assert_eq!(failure.kind, FailureKind::Unreachable); + assert_eq!(failure.cause, Some(OnlineErrorKind::NotFound)); + // 两档从类型上就分得开：同一个计划里两种成因不会挤进一条 + assert_eq!(plan.failures_of(FailureKind::Incompatible).count(), 0); +} + +#[test] +fn a_version_without_a_usable_file_is_incompatible_not_a_network_error() { + let transport = FixtureTransport::new() + .with(SODIUM_VERSIONS, deps::SODIUM_WITH_DEPENDENCIES) + .with( + FABRIC_API_VERSIONS, + r#"[{"id": "ver-empty", "project_id": "P7dR8mSH", + "version_number": "0.0", "files": []}]"#, + ); + let plan = resolve_with(&transport, &request("sodium")); + assert_eq!(plan.failures[0].kind, FailureKind::Incompatible); + assert!(plan.failures[0].message.contains("没有可下载的主文件")); +} + +// ---------------------------------------------------------------- 两道去重 + +#[test] +fn one_project_required_by_two_parents_is_planned_once_with_both_parents() { + let transport = FixtureTransport::new() + .with( + "https://api.modrinth.com/v2/project/fanin-root/version", + deps::FANIN_ROOT, + ) + .with( + "https://api.modrinth.com/v2/project/BRANCHAA/version", + deps::FANIN_A, + ) + .with( + "https://api.modrinth.com/v2/project/BRANCHBB/version", + deps::FANIN_B, + ) + .with( + "https://api.modrinth.com/v2/project/SHARED01/version", + deps::SHARED_LIB, + ); + let plan = resolve_with(&transport, &request("fanin-root")); + + let projects: Vec<&str> = plan + .nodes + .iter() + .map(|node| node.project.as_str()) + .collect(); + assert_eq!( + projects, + ["ROOT0001", "BRANCHAA", "BRANCHBB", "SHARED01"], + "同层按项目键字典序，公共前置只出现一次" + ); + assert_eq!( + plan.required_by("SHARED01").expect("公共前置在计划里"), + ["BRANCHAA".to_string(), "BRANCHBB".to_string()].as_slice(), + "两条依赖路径都要留下" + ); + let shared_requests = transport + .seen() + .iter() + .filter(|url| url.contains("SHARED01")) + .count(); + assert_eq!(shared_requests, 1, "一个项目只解一次版本"); +} + +#[test] +fn a_file_that_already_exists_is_skipped_but_its_dependencies_are_still_walked() { + let mut request = request("sodium"); + // 禁用中的 jar 也算「装过」（本仓用 `.disabled` 后缀表示禁用） + request.present = vec![PresentFile::new("fabric-api-0.92.2+1.20.1.jar.disabled")]; + let transport = chain_transport(); + let plan = resolve_with(&transport, &request); + + assert_eq!(plan.skipped.len(), 1); + let skipped = &plan.skipped[0]; + assert_eq!(skipped.project, "P7dR8mSH"); + assert_eq!(skipped.reason, SkipReason::AlreadyPresent); + assert_eq!(skipped.file_name, "fabric-api-0.92.2+1.20.1.jar"); + // 跳过的是**下载**，不是图：fabric-api 的前置照样解析出来 + let projects: Vec<&str> = plan + .nodes + .iter() + .map(|node| node.project.as_str()) + .collect(); + assert_eq!(projects, ["AANobbMI", "1eAoo2KR"]); +} + +#[test] +fn present_keys_normalize_paths_case_and_the_disabled_suffix() { + assert_eq!(present_key("mods/Sodium-0.6.0.jar"), "sodium-0.6.0.jar"); + assert_eq!(present_key("a\\b\\x.jar.disabled"), "x.jar"); + assert_eq!(present_key(" y.jar "), "y.jar"); + assert_eq!(present_key(""), ""); +} + +// ---------------------------------------------------------------- 光影过滤器 + +#[test] +fn shader_loaders_are_recognised_in_search_hits() { + let transport = + FixtureTransport::new().with(&format!("{MODRINTH_API}/search"), deps::SEARCH_SHADER); + let client = Modrinth::new(&transport); + let page = block_on(client.search(&crate::addon::online::SearchQuery { + text: String::new(), + project_type: Some(crate::addon::online::ContentType::Shader), + limit: 1, + ..crate::addon::online::SearchQuery::default() + })) + .expect("解析应当成功"); + assert_eq!( + page.hits[0].loaders, + vec!["iris".to_string(), "optifine".to_string()], + "光影的加载器不该被当成分类标签丢掉" + ); +} diff --git a/crates/core/src/addon/online/tests/download.rs b/crates/core/src/addon/online/tests/download.rs new file mode 100644 index 0000000..788afbd --- /dev/null +++ b/crates/core/src/addon/online/tests/download.rs @@ -0,0 +1,187 @@ +//! 下载复核：sha1/sha512 对不对、失败重试几次、会不会留下半截文件。 + +use crate::addon::online::download::{download_verified, RETRY_ATTEMPTS}; +use crate::addon::online::OnlineErrorKind; +use crate::addon::temp::TempRoot; +use crate::download::blocking::block_on; + +use super::support::{hashes_of, FakeArtifact}; + +const BYTES: &[u8] = b"PK\x03\x04 fake mod jar bytes for offline fixtures"; + +fn spec() -> (String, String) { + hashes_of(BYTES) +} + +#[test] +fn a_matching_download_is_written_and_reported() { + let root = TempRoot::new("online-ok"); + let dest = root.join("sodium.jar"); + let fetcher = FakeArtifact::new(BYTES); + let (sha1, sha512) = spec(); + let done = block_on(download_verified( + &fetcher, + "https://cdn.modrinth.com/data/AANobbMI/sodium.jar", + Some(&sha1), + Some(&sha512), + Some(BYTES.len() as u64), + &dest, + )) + .expect("摘要对得上就该成功"); + assert_eq!(done.bytes, BYTES.len() as u64); + assert_eq!(done.digest.sha512, sha512); + assert_eq!(std::fs::read(&dest).expect("文件应当落盘"), BYTES); + assert_eq!(fetcher.attempts(), 1); +} + +#[test] +fn a_sha512_mismatch_deletes_the_file_and_retries_then_fails() { + let root = TempRoot::new("online-bad-sha512"); + let dest = root.join("sodium.jar"); + let fetcher = FakeArtifact::new(BYTES); + let (sha1, _) = spec(); + let wrong = "0".repeat(128); + let error = block_on(download_verified( + &fetcher, + "https://cdn.modrinth.com/data/AANobbMI/sodium.jar", + Some(&sha1), + Some(&wrong), + None, + &dest, + )) + .expect_err("摘要不符必须失败"); + assert_eq!(error.kind(), OnlineErrorKind::Integrity); + assert_eq!(fetcher.attempts(), RETRY_ATTEMPTS, "摘要不符要重试到上限"); + assert!(!dest.exists(), "不符的内容不许留在盘上"); +} + +#[test] +fn a_sha1_mismatch_is_caught_even_when_the_fetcher_skips_verification() { + let root = TempRoot::new("online-bad-sha1"); + let dest = root.join("sodium.jar"); + let fetcher = FakeArtifact::new(BYTES); + let (_, sha512) = spec(); + let wrong = "1".repeat(40); + let error = block_on(download_verified( + &fetcher, + "https://cdn.modrinth.com/data/AANobbMI/sodium.jar", + Some(&wrong), + Some(&sha512), + None, + &dest, + )) + .expect_err("sha1 不符必须失败"); + assert_eq!(error.kind(), OnlineErrorKind::Integrity); + assert!(error.message().contains("SHA-1"), "{}", error.message()); + assert!(!dest.exists()); +} + +#[test] +fn a_transient_network_failure_is_retried_and_succeeds() { + let root = TempRoot::new("online-retry"); + let dest = root.join("sodium.jar"); + let fetcher = FakeArtifact::new(BYTES).failing(2); + let (sha1, sha512) = spec(); + let done = block_on(download_verified( + &fetcher, + "https://cdn.modrinth.com/data/AANobbMI/sodium.jar", + Some(&sha1), + Some(&sha512), + Some(BYTES.len() as u64), + &dest, + )) + .expect("第三次该成功"); + assert_eq!(done.bytes, BYTES.len() as u64); + assert_eq!(fetcher.attempts(), 3); + assert!(dest.exists()); +} + +#[test] +fn exhausting_the_retries_leaves_no_half_file() { + let root = TempRoot::new("online-exhausted"); + let dest = root.join("sodium.jar"); + let fetcher = FakeArtifact::new(BYTES).failing(RETRY_ATTEMPTS + 5); + let (sha1, sha512) = spec(); + let error = block_on(download_verified( + &fetcher, + "https://cdn.modrinth.com/data/AANobbMI/sodium.jar", + Some(&sha1), + Some(&sha512), + None, + &dest, + )) + .expect_err("一直断网必须失败"); + assert_eq!(error.kind(), OnlineErrorKind::NotConnected); + assert_eq!(fetcher.attempts(), RETRY_ATTEMPTS); + assert!(!dest.exists(), "失败后不许留文件"); +} + +#[test] +fn a_truncated_body_is_rejected_by_the_declared_size() { + let root = TempRoot::new("online-truncated"); + let dest = root.join("sodium.jar"); + let fetcher = FakeArtifact::new(BYTES).truncated(); + // 声明的是全量大小，实际只写了一半 ⇒ 按字节数就该拒 + let (sha1, sha512) = spec(); + let error = block_on(download_verified( + &fetcher, + "https://cdn.modrinth.com/data/AANobbMI/sodium.jar", + Some(&sha1), + Some(&sha512), + Some(BYTES.len() as u64), + &dest, + )) + .expect_err("半截文件必须失败"); + assert_eq!(error.kind(), OnlineErrorKind::Integrity); + assert!(!dest.exists()); +} + +#[test] +fn a_malformed_declared_hash_never_touches_the_disk_or_the_network() { + let root = TempRoot::new("online-bad-decl"); + let dest = root.join("sodium.jar"); + let fetcher = FakeArtifact::new(BYTES); + let error = block_on(download_verified( + &fetcher, + "https://cdn.modrinth.com/data/AANobbMI/sodium.jar", + None, + Some("abc"), + None, + &dest, + )) + .expect_err("摘要形状不对必须失败"); + assert_eq!(error.kind(), OnlineErrorKind::Unsupported); + assert_eq!(fetcher.attempts(), 0); + assert!(!dest.exists()); +} + +#[test] +fn a_malformed_sha1_is_dropped_and_the_sha512_still_guards_the_file() { + // r1 顺手项：sha1 形状写坏不该让整条装不上——sha512 才是 mrpack 的权威摘要。 + let root = TempRoot::new("online-bad-sha1-good-sha512"); + let dest = root.join("sodium.jar"); + let fetcher = FakeArtifact::new(BYTES); + let (_, sha512) = spec(); + let done = block_on(download_verified( + &fetcher, + "https://cdn.modrinth.com/data/AANobbMI/sodium.jar", + Some("not-a-sha1-at-all"), + Some(&sha512), + Some(BYTES.len() as u64), + &dest, + )) + .expect("sha512 合法就该能校验并装下"); + assert_eq!(done.digest.sha512, sha512); + assert!(dest.exists()); +} + +#[test] +fn an_empty_url_is_unsupported() { + let root = TempRoot::new("online-no-url"); + let dest = root.join("sodium.jar"); + let fetcher = FakeArtifact::new(BYTES); + let error = block_on(download_verified(&fetcher, " ", None, None, None, &dest)) + .expect_err("没有地址必须失败"); + assert_eq!(error.kind(), OnlineErrorKind::Unsupported); + assert_eq!(fetcher.attempts(), 0); +} diff --git a/crates/core/src/addon/online/tests/fixtures.rs b/crates/core/src/addon/online/tests/fixtures.rs new file mode 100644 index 0000000..129a45d --- /dev/null +++ b/crates/core/src/addon/online/tests/fixtures.rs @@ -0,0 +1,143 @@ +//! 录制下来的 Modrinth v2 响应（**形状按站点原文，字段抄真**；数值是示意，不是某天的真值）。 +//! +//! 三条刻意的细节： +//! - 检索命中的日期字段是 `date_modified`（不是 `updated`）——旧实现读错了字段； +//! - `categories` 里混着 `optimization` 这种分类标签，只有 `fabric` 是真加载器； +//! - 版本里的文件有 `primary: false` 的 `sources.jar`，取第一个会装错。 + +/// `/v2/search?query=sodium`（两页里的第一页）。 +pub(super) const SEARCH: &str = r#"{ + "hits": [ + { + "project_id": "AANobbMI", + "project_type": "mod", + "slug": "sodium", + "author": "jellysquid3", + "title": "Sodium", + "description": "Modern rendering engine and client-side optimization mod", + "categories": ["fabric", "optimization", "quilt"], + "display_categories": ["optimization"], + "versions": ["1.20.1", "1.21.1"], + "downloads": 42123456, + "follows": 9912, + "icon_url": "https://cdn.modrinth.com/data/AANobbMI/icon.png", + "date_created": "2020-12-01T00:00:00Z", + "date_modified": "2026-02-03T10:11:12Z", + "latest_version": "mc1.21.1-0.6.0", + "license": "LGPL-3.0-only", + "client_side": "required", + "server_side": "unsupported", + "gallery": [] + }, + { + "project_id": "P7dR8mSH", + "project_type": "mod", + "slug": "fabric-api", + "author": "modmuss50", + "title": "Fabric API", + "description": "Lightweight and modular API providing common hooks and intercompatibility measures", + "categories": ["fabric", "library"], + "versions": ["1.20.1", "1.21.1"], + "downloads": 99000000, + "follows": 12000, + "icon_url": "", + "date_modified": "2026-01-30T08:00:00Z" + } + ], + "offset": 0, + "limit": 2, + "total_hits": 1234 +}"#; + +/// `/v2/project/sodium`。 +pub(super) const PROJECT: &str = r###"{ + "id": "AANobbMI", + "slug": "sodium", + "project_type": "mod", + "team": "team-id", + "title": "Sodium", + "description": "Modern rendering engine and client-side optimization mod", + "body": "## Sodium\n\nA modern rendering engine for Minecraft which greatly improves performance.", + "published": "2020-12-01T00:00:00Z", + "updated": "2026-02-03T10:11:12Z", + "downloads": 42123456, + "followers": 9912, + "categories": ["fabric", "optimization"], + "game_versions": ["1.20.1", "1.21.1"], + "loaders": ["fabric", "quilt"], + "versions": ["ver-1", "ver-2"], + "icon_url": "https://cdn.modrinth.com/data/AANobbMI/icon.png", + "source_url": "https://github.com/CaffeineMC/sodium", + "issues_url": "https://github.com/CaffeineMC/sodium/issues" +}"###; + +/// `/v2/project/sodium/version`（站点顺序 = 最新在前）。 +pub(super) const VERSIONS: &str = r#"[ + { + "id": "ver-2", + "project_id": "AANobbMI", + "name": "Sodium 0.6.0 for 1.21.1", + "version_number": "mc1.21.1-0.6.0", + "version_type": "release", + "loaders": ["fabric"], + "game_versions": ["1.21.1"], + "date_published": "2026-02-01T12:00:00Z", + "downloads": 4321, + "files": [ + { + "hashes": {"sha1": "1111111111111111111111111111111111111111", "sha512": "aa"}, + "url": "https://cdn.modrinth.com/data/AANobbMI/versions/ver-2/sodium-sources.jar", + "filename": "sodium-sources.jar", + "size": 1000, + "primary": false + }, + { + "hashes": {"sha1": "2222222222222222222222222222222222222222", "sha512": "bb"}, + "url": "https://cdn.modrinth.com/data/AANobbMI/versions/ver-2/sodium-fabric-0.6.0.jar", + "filename": "sodium-fabric-0.6.0.jar", + "size": 2048, + "primary": true + } + ] + } +]"#; + +/// `GET /v2/version_file/{sha512}?algorithm=sha512` 的响应（一个版本对象）。 +/// +/// 里面有两个文件：只有 `hashes.sha512` 与请求值相同的那条能取 sha1（另一个是 `sources.jar`）。 +pub(super) const VERSION_FILE_A: &str = r#"{ + "id": "ver-a", + "project_id": "AANobbMI", + "name": "Sodium 0.5.11 for 1.20.1", + "version_number": "mc1.20.1-0.5.11", + "version_type": "release", + "loaders": ["fabric"], + "game_versions": ["1.20.1"], + "date_published": "2025-06-01T00:00:00Z", + "downloads": 9999, + "files": [ + { + "hashes": {"sha1": "3333333333333333333333333333333333333333", "sha512": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1"}, + "url": "https://cdn.modrinth.com/data/AANobbMI/versions/ver-a/sodium-fabric-0.5.11.jar", + "filename": "sodium-fabric-0.5.11.jar", + "size": 4096, + "primary": true + }, + { + "hashes": {"sha1": "4444444444444444444444444444444444444444", "sha512": "b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2"}, + "url": "https://cdn.modrinth.com/data/AANobbMI/versions/ver-a/sodium-sources.jar", + "filename": "sodium-sources.jar", + "size": 512, + "primary": false + } + ] +}"#; + +/// 补全时请求的那个 sha512（128 位十六进制；形状不对客户端根本不发请求）。 +pub(super) const LOOKUP_SHA512: &str = "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1"; + +/// 同一版本里另一个文件的 sha512（`sources.jar`，不该被拿来当身份）。 +pub(super) const OTHER_SHA512: &str = "b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2"; + +/// 补全应该拿到的 sha1（`VERSION_FILE_A` 主文件那条）。 +pub(super) const LOOKUP_SHA1: &str = "3333333333333333333333333333333333333333"; diff --git a/crates/core/src/addon/online/tests/fixtures_deps.rs b/crates/core/src/addon/online/tests/fixtures_deps.rs new file mode 100644 index 0000000..4680eac --- /dev/null +++ b/crates/core/src/addon/online/tests/fixtures_deps.rs @@ -0,0 +1,277 @@ +//! 依赖解析用的录制响应（形状按站点原文；数值是示意，不是某天的真值）。 +//! +//! 从 `fixtures.rs` 分出来的原因很实在：那里已经在钉「字段名与 `primary`」这类解析细节， +//! 再往里塞四五个带 `dependencies` 的版本对象就会贴到 400 行硬线。 +//! +//! 三条刻意的布置： +//! - 根项目（`sodium`）的版本里**同时有四类依赖**：只有 `required` 该被跟； +//! - 每个版本都有 `primary: false` 的 `sources.jar`，取第一个就会装错； +//! - 环（`cycle-a` ⇄ `cycle-b`）与扇入（两个分支都要 `shared-lib`）各有一组独立夹具。 + +/// 根项目 `sodium` 的版本：一条 required + 一条 optional + 一条 incompatible + 一条 embedded。 +pub(super) const SODIUM_WITH_DEPENDENCIES: &str = r#"[ + { + "id": "ver-sodium", + "project_id": "AANobbMI", + "name": "Sodium 0.6.0 for 1.20.1", + "version_number": "mc1.20.1-0.6.0", + "version_type": "release", + "loaders": ["fabric"], + "game_versions": ["1.20.1"], + "date_published": "2026-02-01T12:00:00Z", + "downloads": 4321, + "files": [ + { + "hashes": {"sha1": "1111111111111111111111111111111111111111", "sha512": "aa"}, + "url": "https://cdn.modrinth.com/data/AANobbMI/versions/ver-sodium/sodium-sources.jar", + "filename": "sodium-sources.jar", + "size": 1000, + "primary": false + }, + { + "hashes": {"sha1": "2222222222222222222222222222222222222222", "sha512": "bb"}, + "url": "https://cdn.modrinth.com/data/AANobbMI/versions/ver-sodium/sodium-fabric-0.6.0.jar", + "filename": "sodium-fabric-0.6.0.jar", + "size": 2048, + "primary": true + } + ], + "dependencies": [ + {"version_id": null, "project_id": "P7dR8mSH", "file_name": null, "dependency_type": "required"}, + {"version_id": null, "project_id": "OCS3z7f6", "file_name": null, "dependency_type": "optional"}, + {"version_id": null, "project_id": "AAAABBBB", "file_name": null, "dependency_type": "incompatible"}, + {"version_id": "ver-embedded", "project_id": null, "file_name": "embedded-lib.jar", "dependency_type": "embedded"} + ] + } +]"#; + +/// `fabric-api`（`P7dR8mSH`）：它自己又要求 `yacl`（`1eAoo2KR`）⇒ 第二层嵌套。 +pub(super) const FABRIC_API_WITH_DEPENDENCIES: &str = r#"[ + { + "id": "ver-fabric-api", + "project_id": "P7dR8mSH", + "name": "Fabric API 0.92.2 for 1.20.1", + "version_number": "0.92.2+1.20.1", + "version_type": "release", + "loaders": ["fabric"], + "game_versions": ["1.20.1"], + "date_published": "2025-12-01T00:00:00Z", + "downloads": 9999, + "files": [ + { + "hashes": {"sha1": "3333333333333333333333333333333333333333", "sha512": "cc"}, + "url": "https://cdn.modrinth.com/data/P7dR8mSH/versions/ver-fabric-api/fabric-api-0.92.2-sources.jar", + "filename": "fabric-api-0.92.2-sources.jar", + "size": 512, + "primary": false + }, + { + "hashes": {"sha1": "4444444444444444444444444444444444444444", "sha512": "dd"}, + "url": "https://cdn.modrinth.com/data/P7dR8mSH/versions/ver-fabric-api/fabric-api-0.92.2+1.20.1.jar", + "filename": "fabric-api-0.92.2+1.20.1.jar", + "size": 4096, + "primary": true + } + ], + "dependencies": [ + {"version_id": null, "project_id": "1eAoo2KR", "file_name": null, "dependency_type": "required"} + ] + } +]"#; + +/// `yacl`（`1eAoo2KR`）：链的末端，没有依赖。 +pub(super) const YACL: &str = r#"[ + { + "id": "ver-yacl", + "project_id": "1eAoo2KR", + "name": "YetAnotherConfigLib 3.3.2", + "version_number": "3.3.2+1.20.1", + "version_type": "release", + "loaders": ["fabric"], + "game_versions": ["1.20.1"], + "date_published": "2025-11-01T00:00:00Z", + "downloads": 1234, + "files": [ + { + "hashes": {"sha1": "5555555555555555555555555555555555555555", "sha512": "ee"}, + "url": "https://cdn.modrinth.com/data/1eAoo2KR/versions/ver-yacl/yacl-3.3.2.jar", + "filename": "yacl-3.3.2+1.20.1.jar", + "size": 8192, + "primary": true + } + ], + "dependencies": [] + } +]"#; + +/// 扇入的根：两个 required 分支。 +pub(super) const FANIN_ROOT: &str = r#"[ + { + "id": "ver-root", + "project_id": "ROOT0001", + "name": "Fan-in Root 1.0", + "version_number": "1.0", + "version_type": "release", + "loaders": ["fabric"], + "game_versions": ["1.20.1"], + "files": [ + { + "hashes": {"sha1": "6666666666666666666666666666666666666666", "sha512": "ff"}, + "url": "https://cdn.modrinth.com/data/ROOT0001/versions/ver-root/fanin-root-1.0.jar", + "filename": "fanin-root-1.0.jar", + "size": 1024, + "primary": true + } + ], + "dependencies": [ + {"project_id": "BRANCHAA", "dependency_type": "required"}, + {"project_id": "BRANCHBB", "dependency_type": "required"} + ] + } +]"#; + +/// 分支 A：也要 `shared-lib`。 +pub(super) const FANIN_A: &str = r#"[ + { + "id": "ver-branch-a", + "project_id": "BRANCHAA", + "name": "Branch A 2.0", + "version_number": "2.0", + "version_type": "release", + "loaders": ["fabric"], + "game_versions": ["1.20.1"], + "files": [ + { + "hashes": {"sha1": "7777777777777777777777777777777777777777", "sha512": "ab"}, + "url": "https://cdn.modrinth.com/data/BRANCHAA/versions/ver-branch-a/branch-a-2.0.jar", + "filename": "branch-a-2.0.jar", + "size": 1024, + "primary": true + } + ], + "dependencies": [ + {"project_id": "SHARED01", "dependency_type": "required"} + ] + } +]"#; + +/// 分支 B：也要 `shared-lib`（同一项目两条路径 ⇒ 只装一次）。 +pub(super) const FANIN_B: &str = r#"[ + { + "id": "ver-branch-b", + "project_id": "BRANCHBB", + "name": "Branch B 3.0", + "version_number": "3.0", + "version_type": "release", + "loaders": ["fabric"], + "game_versions": ["1.20.1"], + "files": [ + { + "hashes": {"sha1": "8888888888888888888888888888888888888888", "sha512": "ac"}, + "url": "https://cdn.modrinth.com/data/BRANCHBB/versions/ver-branch-b/branch-b-3.0.jar", + "filename": "branch-b-3.0.jar", + "size": 1024, + "primary": true + } + ], + "dependencies": [ + {"project_id": "SHARED01", "dependency_type": "required"} + ] + } +]"#; + +/// 扇入的公共前置。 +pub(super) const SHARED_LIB: &str = r#"[ + { + "id": "ver-shared", + "project_id": "SHARED01", + "name": "Shared Lib 1.5", + "version_number": "1.5", + "version_type": "release", + "loaders": ["fabric"], + "game_versions": ["1.20.1"], + "files": [ + { + "hashes": {"sha1": "9999999999999999999999999999999999999999", "sha512": "ad"}, + "url": "https://cdn.modrinth.com/data/SHARED01/versions/ver-shared/shared-lib-1.5.jar", + "filename": "shared-lib-1.5.jar", + "size": 2048, + "primary": true + } + ], + "dependencies": [] + } +]"#; + +/// 环的一端：`cycle-a` 要求 `cycle-b`。 +pub(super) const CYCLE_A: &str = r#"[ + { + "id": "ver-cycle-a", + "project_id": "cycAid01", + "name": "Cycle A 1.0", + "version_number": "1.0", + "version_type": "release", + "loaders": ["fabric"], + "game_versions": ["1.20.1"], + "files": [ + { + "hashes": {"sha1": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "sha512": "a1"}, + "url": "https://cdn.modrinth.com/data/cycAid01/versions/ver-cycle-a/cycle-a-1.0.jar", + "filename": "cycle-a-1.0.jar", + "size": 1024, + "primary": true + } + ], + "dependencies": [ + {"project_id": "cycBid01", "dependency_type": "required"} + ] + } +]"#; + +/// 环的另一端：`cycle-b` 又要求 `cycle-a`（不设防就是无限递归）。 +pub(super) const CYCLE_B: &str = r#"[ + { + "id": "ver-cycle-b", + "project_id": "cycBid01", + "name": "Cycle B 1.0", + "version_number": "1.0", + "version_type": "release", + "loaders": ["fabric"], + "game_versions": ["1.20.1"], + "files": [ + { + "hashes": {"sha1": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "sha512": "b1"}, + "url": "https://cdn.modrinth.com/data/cycBid01/versions/ver-cycle-b/cycle-b-1.0.jar", + "filename": "cycle-b-1.0.jar", + "size": 1024, + "primary": true + } + ], + "dependencies": [ + {"project_id": "cycAid01", "dependency_type": "required"} + ] + } +]"#; + +/// 光影检索的一页：`categories` 里是 `iris` / `optifine`（光影的加载器）。 +pub(super) const SEARCH_SHADER: &str = r#"{ + "hits": [ + { + "project_id": "shader01", + "project_type": "shader", + "slug": "complementary-reimagined", + "author": "EminGT", + "title": "Complementary Reimagined", + "description": "A shader pack", + "categories": ["iris", "optifine", "shaders"], + "versions": ["1.20.1"], + "downloads": 1234567, + "follows": 4242, + "icon_url": "", + "date_modified": "2026-01-02T03:04:05Z" + } + ], + "offset": 0, + "limit": 1, + "total_hits": 1 +}"#; diff --git a/crates/core/src/addon/online/tests/mod.rs b/crates/core/src/addon/online/tests/mod.rs new file mode 100644 index 0000000..31f60da --- /dev/null +++ b/crates/core/src/addon/online/tests/mod.rs @@ -0,0 +1,17 @@ +//! 在线内容源的离线用例（**不打真实网络**）。 +//! +//! 全部素材是录制好的 Modrinth v2 响应（`fixtures.rs`）+ 假字节（`support::FakeArtifact`）： +//! 覆盖检索、项目详情、版本列表、按摘要反查、下载复核、补全路径与离线分类。 +//! +//! 口径提醒：这些用例证明的是**解析与判定**，不证明「真实站点今天回什么」——后者写在 +//! M162 报告的「没验的部分」里。 + +mod api; +mod classify; +mod dependency; +mod download; +mod fixtures; +mod fixtures_deps; +mod order; +mod regressions; +mod support; diff --git a/crates/core/src/addon/online/tests/order.rs b/crates/core/src/addon/online/tests/order.rs new file mode 100644 index 0000000..35917a8 --- /dev/null +++ b/crates/core/src/addon/online/tests/order.rs @@ -0,0 +1,137 @@ +//! 顺序确定性（r1 P2-4）：同层 ≥2 个前置、夹具数组故意逆序、多根乱序，结果必须一样。 +//! +//! # 这条用例守的是什么 +//! +//! `resolve` 在每层处理前把队列按**项目键字典序**排一遍。把那一行删掉，原来那 11 条用例 +//! （以及 core 的全部用例）**仍然全绿**——因为三跳链每层只有一个前置、扇入用例里两个同层 +//! 节点的先后恰好等于夹具数组顺序。也就是说「顺序由数据决定」这条性质当时没有守门。 +//! +//! # 归因（实测过，别写成「都靠这两条守门」） +//! +//! 删掉 `resolve` 里那行 `layer.sort_by` ⇒ +//! [`prerequisites_from_two_roots_are_ordered_by_project_key`] 与 +//! [`multiple_roots_are_processed_in_key_order_whatever_the_argument_order`] 红， +//! [`same_root_prerequisites_follow_key_order_not_payload_order`] 仍绿——因为那两个前置 +//! 是**同一个根**入队的，顺序已经被 `Version::required_project_ids()` 内部的排序排过了。 +//! 反过来，只删 `required_project_ids()` 的排序时三条都绿：`layer.sort_by` 会把结果重排一遍。 +//! +//! 也就是说：跨层顺序由 `layer.sort_by` 兜底（这两条用例钉它），同一个根内的顺序**两层保护** +//! 冗余存在；`required_project_ids()` 自己的「排序去重」契约由 `tests/regressions.rs` 的 +//! `required_project_ids_are_sorted_and_deduplicated_on_their_own` 单独钉（那条只删排序就会红）。 + +use crate::addon::online::dependency::{DependencyPlan, ResolveRequest}; +use crate::addon::online::{resolve, Modrinth}; +use crate::download::blocking::block_on; + +use super::support::{version_json, FixtureTransport}; + +const API: &str = "https://api.modrinth.com/v2/project"; + +fn request(roots: &[&str]) -> ResolveRequest { + ResolveRequest { + roots: roots.iter().map(|root| (*root).to_string()).collect(), + game_version: Some("1.20.1".to_string()), + loader: Some("fabric".to_string()), + ..ResolveRequest::default() + } +} + +fn plan_of(transport: &FixtureTransport, roots: &[&str]) -> DependencyPlan { + let client = Modrinth::new(transport); + block_on(resolve(&client, &request(roots))) +} + +fn projects(plan: &DependencyPlan) -> Vec<&str> { + plan.nodes + .iter() + .map(|node| node.project.as_str()) + .collect() +} + +#[test] +fn same_root_prerequisites_follow_key_order_not_payload_order() { + // 夹具里 ZEBRA01 在前、ALPHA01 在后（站点原文顺序反过来是常态）。 + // 这一条守的是 `Version::required_project_ids()` 里的排序：靠「入队顺序」展开的话， + // 站点换个数组顺序，安装顺序就跟着变。 + let transport = FixtureTransport::new() + .with( + &format!("{API}/order-root/version"), + &version_json( + "order-root", + "order-root.jar", + &[("ZEBRA01", "required"), ("ALPHA01", "required")], + ), + ) + .with( + &format!("{API}/ALPHA01/version"), + &version_json("ALPHA01", "alpha.jar", &[]), + ) + .with( + &format!("{API}/ZEBRA01/version"), + &version_json("ZEBRA01", "zebra.jar", &[]), + ); + + let plan = plan_of(&transport, &["order-root"]); + assert!(plan.is_clean(), "{:?}", plan.failures); + assert_eq!( + projects(&plan), + ["order-root", "ALPHA01", "ZEBRA01"], + "同层按项目键字典序，与 `dependencies` 数组顺序无关" + ); +} + +/// 两个根各带一个前置 ⇒ 它们在**同一层**相遇，且项目键的顺序与根的先后相反。 +/// +/// 这一条守的是 `resolve` 里每层的 `sort_by`：不排的话，层内顺序就是「谁先被入队」—— +/// 也就是参数顺序与站点响应顺序的混合，删掉那行 `sort_by` 这条会红 +/// （实测：`left: ["zebra-branch","alpha-branch"]` 之类的参数序）。 +#[test] +fn prerequisites_from_two_roots_are_ordered_by_project_key() { + let transport = FixtureTransport::new() + .with( + &format!("{API}/branch-a/version"), + &version_json("branch-a", "branch-a.jar", &[("ZEBRA01", "required")]), + ) + .with( + &format!("{API}/branch-b/version"), + &version_json("branch-b", "branch-b.jar", &[("ALPHA01", "required")]), + ) + .with( + &format!("{API}/ALPHA01/version"), + &version_json("ALPHA01", "alpha.jar", &[]), + ) + .with( + &format!("{API}/ZEBRA01/version"), + &version_json("ZEBRA01", "zebra.jar", &[]), + ); + + let plan = plan_of(&transport, &["branch-a", "branch-b"]); + assert!(plan.is_clean(), "{:?}", plan.failures); + assert_eq!( + projects(&plan), + ["branch-a", "branch-b", "ALPHA01", "ZEBRA01"], + "第二层两个前置按项目键排，不按「谁先入队」" + ); +} + +#[test] +fn multiple_roots_are_processed_in_key_order_whatever_the_argument_order() { + let transport = FixtureTransport::new() + .with( + &format!("{API}/zebra-root/version"), + &version_json("zebra-root", "zebra-root.jar", &[]), + ) + .with( + &format!("{API}/alpha-root/version"), + &version_json("alpha-root", "alpha-root.jar", &[]), + ); + + let forward = plan_of(&transport, &["zebra-root", "alpha-root"]); + let backward = plan_of(&transport, &["alpha-root", "zebra-root"]); + assert_eq!( + projects(&forward), + ["alpha-root", "zebra-root"], + "参数逆序也要按项目键处理" + ); + assert_eq!(projects(&backward), projects(&forward), "两次结果必须一样"); +} diff --git a/crates/core/src/addon/online/tests/regressions.rs b/crates/core/src/addon/online/tests/regressions.rs new file mode 100644 index 0000000..605c2fc --- /dev/null +++ b/crates/core/src/addon/online/tests/regressions.rs @@ -0,0 +1,232 @@ +//! M186 复审（r1）补的用例：失败去重、null 载荷、版本级去重。 +//! +//! 三条都对应一轮真实缺陷或真实缺口，而不是「补覆盖率」： +//! 1. [`the_same_failing_project_is_recorded_once_however_many_paths_ask_for_it`] — P2-1： +//! 失败分支以前直接 `continue`，同一项目被两条路径要求时取两次版本、记两条失败、 +//! 重试名单里写两遍同一个名字； +//! 2. [`a_null_dependency_type_does_not_poison_the_whole_version_list`] — P2-2： +//! `"dependency_type": null` 曾让整份 `/version` 报 Malformed，于是整个项目都装不上； +//! 3. [`another_version_of_the_same_mod_in_the_directory_still_downloads`] — nit③： +//! 归一化一旦改松，同 mod 的另一个版本会被误判成「已装」而跳过。 + +use crate::addon::online::dependency::{present_key, DependencyPlan, ResolveRequest}; +use crate::addon::online::model::parse_versions; +use crate::addon::online::{resolve, DependencyType, Modrinth, PresentFile, UnresolvedRequired}; +use crate::download::blocking::block_on; + +use super::fixtures_deps as deps; +use super::support::{version_json, FixtureTransport}; + +const API: &str = "https://api.modrinth.com/v2/project"; +const SODIUM_VERSIONS: &str = "https://api.modrinth.com/v2/project/sodium/version"; +const FABRIC_API_VERSIONS: &str = "https://api.modrinth.com/v2/project/P7dR8mSH/version"; +const YACL_VERSIONS: &str = "https://api.modrinth.com/v2/project/1eAoo2KR/version"; + +fn request(root: &str) -> ResolveRequest { + ResolveRequest { + roots: vec![root.to_string()], + game_version: Some("1.20.1".to_string()), + loader: Some("fabric".to_string()), + ..ResolveRequest::default() + } +} + +fn resolve_with(transport: &FixtureTransport, request: &ResolveRequest) -> DependencyPlan { + let client = Modrinth::new(transport); + block_on(resolve(&client, request)) +} + +fn chain_transport() -> FixtureTransport { + FixtureTransport::new() + .with(SODIUM_VERSIONS, deps::SODIUM_WITH_DEPENDENCIES) + .with(FABRIC_API_VERSIONS, deps::FABRIC_API_WITH_DEPENDENCIES) + .with(YACL_VERSIONS, deps::YACL) +} + +/// 同一个项目被两条路径要求、且它 404：**只请求一次、只记一条失败**，父边合起来。 +/// +/// r1 P2-1 的探针：`ROOT0001 → {BRANCH01, MIDDLE01}`、`BRANCH01 → GONE0001`(404)、 +/// `MIDDLE01 → LATE0001 → GONE0001`。修之前 GONE0001 被请求 2 次、失败 2 条、 +/// 重试名单是 `["GONE0001","GONE0001"]`（用户会看到「可只重试这 2 个：GONE0001、GONE0001」）。 +#[test] +fn the_same_failing_project_is_recorded_once_however_many_paths_ask_for_it() { + let transport = FixtureTransport::new() + .with( + &format!("{API}/root/version"), + &version_json( + "ROOT0001", + "root.jar", + &[("BRANCH01", "required"), ("MIDDLE01", "required")], + ), + ) + .with( + &format!("{API}/BRANCH01/version"), + &version_json("BRANCH01", "branch.jar", &[("GONE0001", "required")]), + ) + .with( + &format!("{API}/MIDDLE01/version"), + &version_json("MIDDLE01", "middle.jar", &[("LATE0001", "required")]), + ) + .with( + &format!("{API}/LATE0001/version"), + &version_json("LATE0001", "late.jar", &[("GONE0001", "required")]), + ) + .missing(&format!("{API}/GONE0001/version")); + + let plan = resolve_with(&transport, &request("root")); + + let gone_requests = transport + .seen() + .iter() + .filter(|url| url.contains("GONE0001")) + .count(); + assert_eq!( + gone_requests, + 1, + "同一个失败项目不许取两次：{:?}", + transport.seen() + ); + assert_eq!(plan.failures.len(), 1, "{:?}", plan.failures); + assert_eq!(plan.failures[0].requested_as, "GONE0001"); + assert_eq!( + plan.failures[0].required_by, + ["BRANCH01".to_string(), "LATE0001".to_string()], + "两条路径的父边都要留下" + ); + assert_eq!(plan.retry_request().roots, ["GONE0001"], "名单不许重复"); +} + +/// `"dependency_type": null` 不许把整份版本响应打成 Malformed（r1 P2-2 的回归）。 +/// +/// 以前 `RawDependency.dependency_type` 是 `String`：`#[serde(default)]` 只兜「字段缺失」， +/// 兜不住 null ⇒ 整份 `/version` 解析失败 ⇒ 根项目记 `Malformed`、`nodes` 为空 ⇒ 一个都装不上。 +#[test] +fn a_null_dependency_type_does_not_poison_the_whole_version_list() { + let body = r#"[{"id": "ver-null", "project_id": "NULLTYPE", "version_number": "1.0", + "files": [{"url": "https://cdn.modrinth.com/data/NULLTYPE/1.0/null-type.jar", + "filename": "null-type.jar", "size": 16, "primary": true}], + "dependencies": [{"project_id": "X1", "dependency_type": null}]}]"#; + + // 解析层：null 与缺失一样落 `Unknown` + let versions = parse_versions(body).expect("null 不该让整份响应失败"); + assert_eq!( + versions[0].dependencies[0].dependency_type, + DependencyType::Unknown + ); + assert_eq!(versions[0].required_project_ids(), Vec::<&str>::new()); + + // 解析流程：根照样装得上，X1 一次请求都不发 + let transport = FixtureTransport::new().with(&format!("{API}/null-type/version"), body); + let plan = resolve_with(&transport, &request("null-type")); + assert!(plan.is_clean(), "{:?}", plan.failures); + assert_eq!(plan.nodes.len(), 1, "根项目要还在计划里"); + assert_eq!(transport.seen().len(), 1, "未知类型不许递归"); +} + +/// 目录里是**同 mod 的另一个版本** ⇒ 文件名不同，仍然要下载（r1 nit③ 的负向用例）。 +/// +/// 归一化如果改松（例如「砍到第一个 `-` 前 + 砍扩展名」），`sodium-fabric-0.5.11.jar` 与 +/// `sodium-fabric-0.6.0.jar` 会被判成同一个文件，该装的被跳过。 +#[test] +fn another_version_of_the_same_mod_in_the_directory_still_downloads() { + let mut request = request("sodium"); + request.present = vec![PresentFile::new("sodium-fabric-0.5.11.jar")]; + let transport = chain_transport(); + let plan = resolve_with(&transport, &request); + + assert!(plan.skipped.is_empty(), "{:?}", plan.skipped); + assert_eq!(plan.nodes[0].file.filename, "sodium-fabric-0.6.0.jar"); + assert_ne!( + present_key("sodium-fabric-0.5.11.jar"), + present_key("sodium-fabric-0.6.0.jar"), + "不同版本的文件名归一化后不许相等" + ); +} + +/// 未知/大小写不同的取值一律 `Unknown`，**绝不**猜成 required（这条设计不许被 r1 的修法改坏）。 +#[test] +fn unknown_dependency_types_never_trigger_recursion() { + for raw in [ + "required_by_default", + "Required ", + "Recommended", + "", + "REQUIRED", + "req", + ] { + assert_eq!( + DependencyType::parse(raw), + DependencyType::Unknown, + "{raw:?} 不该被当成 required" + ); + } + assert_eq!(DependencyType::parse("required"), DependencyType::Required); +} + +/// `required_project_ids()` 的「排序 + 去重」契约单独钉住。 +/// +/// 为什么要单独钉：resolver 里 `layer.sort_by` 会把它重排一遍、`wave_in` 也会按同键合并， +/// 于是**这条契约在端到端用例里被兜住了**（删掉这里的 `sort_unstable` 三条顺序用例仍绿）。 +/// 但 `dedup()` 只去相邻重复，不排序就留下 `["ZEBRA01","ALPHA01","ZEBRA01"]`—— +/// 公开 API 说好了「排序去重」，就得有自己的一条。 +#[test] +fn required_project_ids_are_sorted_and_deduplicated_on_their_own() { + let body = version_json( + "dup-root", + "dup-root.jar", + &[ + ("ZEBRA01", "required"), + ("ALPHA01", "required"), + ("ZEBRA01", "required"), + ], + ); + let versions = parse_versions(&body).expect("夹具该解析成功"); + assert_eq!( + versions[0].required_project_ids(), + ["ALPHA01", "ZEBRA01"], + "既要去重（非相邻）也要排序" + ); +} + +/// 只有 `version_id` 的必备前置：**core 自己**要把它们收进 `unresolved_required`（r2 nit①）。 +/// +/// presenter 那条用例是直接赋值 `plan.unresolved_required`，绕过了 core；这里从夹具走一遍解析， +/// 顺带钉住「别为了收集把正常的 required 也吞掉」——同一版本里带 `project_id` 的那条仍要被跟。 +#[test] +fn a_required_dependency_with_only_a_version_id_is_collected_by_the_resolver() { + let body = r#"[{"id": "ver-mixed", "project_id": "MIXED001", "version_number": "1.0", + "files": [{"url": "https://cdn.modrinth.com/data/MIXED001/1.0/mixed.jar", + "filename": "mixed.jar", "size": 16, "primary": true}], + "dependencies": [ + {"version_id": "vid-only", "dependency_type": "required"}, + {"project_id": "FOLLOW01", "dependency_type": "required"} + ]}]"#; + let transport = FixtureTransport::new() + .with(&format!("{API}/mixed/version"), body) + .with( + &format!("{API}/FOLLOW01/version"), + &version_json("FOLLOW01", "follow.jar", &[]), + ); + + let plan = resolve_with(&transport, &request("mixed")); + + assert_eq!( + plan.unresolved_required, + [UnresolvedRequired { + parent: "MIXED001".to_string(), + version_id: Some("vid-only".to_string()), + file_name: None, + }], + "只给版本 id 的 required 必须被记下来" + ); + let projects: Vec<&str> = plan + .nodes + .iter() + .map(|node| node.project.as_str()) + .collect(); + assert_eq!( + projects, + ["MIXED001", "FOLLOW01"], + "同一版本里带 project_id 的 required 仍要被跟" + ); +} diff --git a/crates/core/src/addon/online/tests/support.rs b/crates/core/src/addon/online/tests/support.rs new file mode 100644 index 0000000..f3a70fc --- /dev/null +++ b/crates/core/src/addon/online/tests/support.rs @@ -0,0 +1,189 @@ +//! 测试替身：录制响应传输层 + 假字节下载器。 +//! +//! 两个替身都**只做注入点该做的事**：不校验、不重试、不判断——那些必须在被测代码里， +//! 否则测试就只是「验证桩自己」。 + +use std::collections::BTreeMap; +use std::io::Write; +use std::path::Path; +use std::sync::Mutex; + +use sha1::Digest as _; + +use crate::addon::online::download::{ArtifactFetcher, FetchArgs}; +use crate::addon::online::{OnlineError, OnlineErrorKind, OnlineFuture, Transport}; + +/// 按 URL 前缀路由的传输层（把录制 JSON 喂给客户端）。 +pub(super) struct FixtureTransport { + routes: BTreeMap>, + seen: Mutex>, +} + +impl FixtureTransport { + /// 建一个空的路由表。 + pub(super) fn new() -> Self { + Self { + routes: BTreeMap::new(), + seen: Mutex::new(Vec::new()), + } + } + + /// 挂一条路由（`prefix` 是 URL 前缀）。 + pub(super) fn with(mut self, prefix: &str, body: &str) -> Self { + self.routes.insert(prefix.to_string(), Ok(body.to_string())); + self + } + + /// 挂一条「没联网」的路由。 + pub(super) fn offline(mut self, prefix: &str) -> Self { + self.routes.insert( + prefix.to_string(), + Err(OnlineError::offline("连不上 api.modrinth.com")), + ); + self + } + + /// 挂一条「站点说没有」的路由。 + pub(super) fn missing(mut self, prefix: &str) -> Self { + self.routes.insert( + prefix.to_string(), + Err(OnlineError::new(OnlineErrorKind::NotFound, "HTTP 404")), + ); + self + } + + /// 实际请求过的 URL（按顺序）。 + pub(super) fn seen(&self) -> Vec { + self.seen.lock().expect("锁没中毒").clone() + } +} + +impl Transport for FixtureTransport { + fn get_text<'a>(&'a self, url: &'a str) -> OnlineFuture<'a, Result> { + Box::pin(async move { + self.seen.lock().expect("锁没中毒").push(url.to_string()); + // 最长前缀优先：`/v2/project/sodium` 与 `/v2/project/sodium/version` 不能互相抢。 + let best = self + .routes + .iter() + .filter(|(prefix, _)| url.starts_with(prefix.as_str())) + .max_by_key(|(prefix, _)| prefix.len()) + .map(|(_, result)| result); + match best { + Some(Ok(body)) => Ok(body.clone()), + Some(Err(error)) => Err(error.clone()), + None => Err(OnlineError::new( + OnlineErrorKind::NotFound, + format!("测试没为 {url} 挂路由"), + )), + } + }) + } +} + +/// 假字节下载器：把给定字节写到 `dest`，可以安排前几次失败。 +pub(super) struct FakeArtifact { + bytes: Vec, + /// 还欠几次「没联网」失败（每尝试一次减一） + failures: Mutex, + /// 实际尝试次数 + attempts: Mutex, + /// 故意只写一半（模拟半截文件） + truncate: bool, +} + +impl FakeArtifact { + /// 正常一份字节。 + pub(super) fn new(bytes: &[u8]) -> Self { + Self { + bytes: bytes.to_vec(), + failures: Mutex::new(0), + attempts: Mutex::new(0), + truncate: false, + } + } + + /// 前 `count` 次尝试没联网。 + pub(super) fn failing(mut self, count: u32) -> Self { + *self.failures.get_mut().expect("锁没中毒") = count; + self + } + + /// 只写一半字节（半截文件场景）。 + pub(super) fn truncated(mut self) -> Self { + self.truncate = true; + self + } + + /// 尝试次数。 + pub(super) fn attempts(&self) -> u32 { + *self.attempts.lock().expect("锁没中毒") + } +} + +impl ArtifactFetcher for FakeArtifact { + fn fetch<'a>(&'a self, args: FetchArgs<'a>) -> OnlineFuture<'a, Result> { + Box::pin(async move { + *self.attempts.lock().expect("锁没中毒") += 1; + let mut failures = self.failures.lock().expect("锁没中毒"); + if *failures > 0 { + *failures -= 1; + return Err(OnlineError::offline("假装的断网")); + } + drop(failures); + write_bytes(args.dest, &self.bytes, self.truncate)?; + Ok(if self.truncate { + self.bytes.len() as u64 / 2 + } else { + self.bytes.len() as u64 + }) + }) + } +} + +fn write_bytes(dest: &Path, bytes: &[u8], truncated: bool) -> Result<(), OnlineError> { + let mut file = std::fs::File::create(dest).map_err(|error| { + OnlineError::new( + OnlineErrorKind::Io, + format!("建 {} 失败：{error}", dest.display()), + ) + })?; + let half = bytes.len() / 2; + let slice = if truncated { &bytes[..half] } else { bytes }; + file.write_all(slice).map_err(|error| { + OnlineError::new( + OnlineErrorKind::Io, + format!("写 {} 失败：{error}", dest.display()), + ) + }) +} + +/// 一段字节的 `(sha1, sha512)`（小写十六进制）。 +pub(super) fn hashes_of(bytes: &[u8]) -> (String, String) { + let sha1 = sha1::Sha1::digest(bytes); + let sha512 = sha2::Sha512::digest(bytes); + ( + crate::addon::online::download::to_hex(&sha1), + crate::addon::online::download::to_hex(&sha512), + ) +} + +/// 拼一份 `/v2/project/{id}/version` 响应：一个版本、一个主文件、按给定顺序声明依赖。 +/// +/// `deps` 的每一项是 `(project_id, dependency_type)`，**顺序照抄站点原文**——顺序无关性由 +/// `resolve` 保证（`tests/order.rs` 用它做「夹具逆序也得到同一顺序」的守门）。 +pub(super) fn version_json(project: &str, file: &str, deps: &[(&str, &str)]) -> String { + let dependencies: Vec = deps + .iter() + .map(|(id, kind)| format!(r#"{{"project_id":"{id}","dependency_type":"{kind}"}}"#)) + .collect(); + format!( + r#"[{{"id":"ver-{project}","project_id":"{project}","name":"{project}", + "version_number":"1.0","version_type":"release","loaders":["fabric"], + "game_versions":["1.20.1"], + "files":[{{"hashes":{{}},"url":"https://cdn.modrinth.com/data/{project}/1.0/{file}", + "filename":"{file}","size":16,"primary":true}}], + "dependencies":[{}]}}]"#, + dependencies.join(",") + ) +} diff --git a/crates/core/src/addon/online/transport.rs b/crates/core/src/addon/online/transport.rs new file mode 100644 index 0000000..932b973 --- /dev/null +++ b/crates/core/src/addon/online/transport.rs @@ -0,0 +1,227 @@ +//! 唯一的 HTTP 出口 + 错误分类。 +//! +//! # 为什么是 trait +//! +//! 三条理由，每条都对应一个真实麻烦： +//! +//! 1. **测试不能联网**：本模块的解析/端点/补全全部要用录制 JSON 跑（CI 没有网，也不该有）； +//! 2. **换源不改业务**：将来加第二个内容源时，只要它也能 GET 出 JSON，就能复用这套 +//! `Transport`（现在的实现按「一个 URL → 一段文本」抽象，不假设站点）； +//! 3. **错误必须可分辨**：「没联网」和「站点说没有这个项目」是两件事（前者该提示检查网络， +//! 后者该提示换关键词），字符串错误串会让上层只能靠 `contains` 猜。 +//! +//! # 生产实现只有一条路：`core::download` 的引擎 +//! +//! [`EngineTransport`] 调 [`DownloadEngine::download_bytes`]，于是信号量限流、源健康度、 +//! 指数退避、错误分类全在引擎里。本模块**不**新建 `reqwest::Client`、**不**写重试循环 +//! （与 `addon::import::fetch` 的纪律同源）。镜像策略同理：`mirrors.json` 里没有 +//! `api.modrinth.com` 的前缀规则 ⇒ 元数据请求永远是直连，只有真正的文件下载才会被镜像 +//! 规则命中（国内 gh-proxy 那条也只看 GitHub host）。 +//! +//! 引擎本身由宿主提供**且是进程级共享的**（M165：`download::shared::engine_for`，一个数据根 +//! 一个）：`EngineTransport` 只借一个 `&DownloadEngine`，不负责建也不负责销毁。于是 +//! 「检索 → 详情 → 装文件」这一串请求复用同一条连接池、同一个限流闸门、同一份镜像健康度—— +//! 这正是本模块当初拒绝自己造 client 的同一个理由，只是从「模块内不重复造」扩到了「跨请求不重复造」。 + +use std::future::Future; +use std::pin::Pin; + +use crate::download::{ + DownloadEngine, DownloadError, DownloadErrorKind, DownloadRequest, ResourceKind, +}; + +/// trait 方法返回的装箱 future（core 不引 `async-trait`，手写与 `import::fetch` 同一个范式）。 +pub type OnlineFuture<'a, T> = Pin + Send + 'a>>; + +/// 「拿不到」的成因（**分级判据只在这里**）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum OnlineErrorKind { + /// 没联网 / 连不上 / 所有候选源都失败 —— 上层要明确说「未联网」。 + NotConnected, + /// 站点说没有（404 / 项目被删）。 + NotFound, + /// 站点出错（5xx / 429 退避后仍失败）。 + Server, + /// 响应不是期望形状（JSON 坏 / 字段类型不对）。 + Malformed, + /// 本地 IO（写缓存失败等）。 + Io, + /// 内容与声明的摘要不符（下载到的字节坏了 / 镜像给的其实是别的东西）。 + Integrity, + /// 这条路走不通（URL 非法、摘要格式不对、没有可用下载地址）。 + Unsupported, +} + +impl OnlineErrorKind { + /// 稳定字符串 id（日志 / DTO 用，**不要改名**）。 + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::NotConnected => "online_not_connected", + Self::NotFound => "online_not_found", + Self::Server => "online_server", + Self::Malformed => "online_malformed", + Self::Io => "online_io", + Self::Integrity => "online_integrity", + Self::Unsupported => "online_unsupported", + } + } + + /// 是不是「网络这条路没通」（决定上层画「未联网」还是「查无此项」）。 + #[must_use] + pub const fn is_offline(self) -> bool { + matches!(self, Self::NotConnected) + } +} + +/// 一次取数失败。 +#[derive(Debug, Clone)] +pub struct OnlineError { + kind: OnlineErrorKind, + message: String, +} + +impl OnlineError { + /// 构造。 + #[must_use] + pub fn new(kind: OnlineErrorKind, message: impl Into) -> Self { + Self { + kind, + message: message.into(), + } + } + + /// 没联网。 + #[must_use] + pub fn offline(message: impl Into) -> Self { + Self::new(OnlineErrorKind::NotConnected, message) + } + + /// 形状不对 / 自身不自洽。 + #[must_use] + pub fn malformed(message: impl Into) -> Self { + Self::new(OnlineErrorKind::Malformed, message) + } + + /// 内容与声明不符。 + #[must_use] + pub fn integrity(message: impl Into) -> Self { + Self::new(OnlineErrorKind::Integrity, message) + } + + /// 这条路走不通。 + #[must_use] + pub fn unsupported(message: impl Into) -> Self { + Self::new(OnlineErrorKind::Unsupported, message) + } + + /// 大类。 + #[must_use] + pub const fn kind(&self) -> OnlineErrorKind { + self.kind + } + + /// 人读说明。 + #[must_use] + pub fn message(&self) -> &str { + &self.message + } + + /// 没联网吗（上层据此决定降级文案）。 + #[must_use] + pub const fn is_offline(&self) -> bool { + self.kind.is_offline() + } +} + +impl std::fmt::Display for OnlineError { + fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + write!(formatter, "{}：{}", self.kind.as_str(), self.message) + } +} + +impl std::error::Error for OnlineError {} + +/// `DownloadEngine` 的错误 → 本模块的错误分类。 +/// +/// # 为什么读 `effective_kind()` 而不是 `kind` +/// +/// 引擎的候选源循环结束时只留下一条 [`DownloadErrorKind::AllSourcesFailed`]，404 / 429 / 5xx / +/// 超时这些**叶子**成因会被折叠掉（`crates/core/src/download/bytes.rs` 的收尾）。 +/// 如果直接按 `kind` 判定，`NotFound` / `Server` / `Integrity` 三档在本模块的生产路径上 +/// **永远不可达**：项目被删、id 拼错、被限速都会画成「未联网」（r1 P1-1 后果 A）。 +/// +/// 引擎现在会把汇总出来的叶子 kind 挂在 `DownloadError::leaf` 上，这里按叶子映射； +/// 没有叶子（单源直失败 / 手工构造）就按自身 kind。**不从 `suppressed` 文本里猜状态码。** +/// +/// # 分类口径 +/// +/// | 引擎侧 | 本模块 | 上层该怎么说 | +/// |--------|--------|--------------| +/// | `NotFound`（404/410/403，全源都是） | [`OnlineErrorKind::NotFound`] | 「查无此项 / 换个关键词」 | +/// | `ServerError`（5xx / 429） | [`OnlineErrorKind::Server`] | 「站点那边出错了」 | +/// | `Network` / `Timeout` | [`OnlineErrorKind::NotConnected`] | 「未联网，检查网络」 | +/// | `AllSourcesFailed`（没有叶子） | [`OnlineErrorKind::NotConnected`] | 同上（保守） | +/// | `Integrity` | [`OnlineErrorKind::Integrity`] | 「内容不对」 | +impl From for OnlineError { + fn from(error: DownloadError) -> Self { + let kind = match error.effective_kind() { + DownloadErrorKind::NotFound => OnlineErrorKind::NotFound, + DownloadErrorKind::ServerError => OnlineErrorKind::Server, + DownloadErrorKind::Timeout | DownloadErrorKind::Network => { + OnlineErrorKind::NotConnected + } + DownloadErrorKind::Io => OnlineErrorKind::Io, + DownloadErrorKind::Integrity => OnlineErrorKind::Integrity, + DownloadErrorKind::RangeUnsupported => OnlineErrorKind::Malformed, + DownloadErrorKind::InvalidRequest => OnlineErrorKind::Unsupported, + // 没有叶子 ⇒ 分不清「没网」与「站点挂了」，按可重试的「没联网」保守处理： + // 上层至少会提示「检查网络后重试」，而不是宣称「没有匹配的内容」。 + DownloadErrorKind::AllSourcesFailed => OnlineErrorKind::NotConnected, + }; + Self::new(kind, error.message) + } +} + +/// 一个 URL → 一段文本（JSON 原文）。 +/// +/// 实现方只负责「取回来」：状态码分类、退避、限流都在实现里（生产实现在引擎里）。 +pub trait Transport: Send + Sync { + /// GET 一段文本。 + fn get_text<'a>(&'a self, url: &'a str) -> OnlineFuture<'a, Result>; +} + +/// 生产实现：把 GET 交给 `core::download` 的引擎（内存下载路径）。 +#[derive(Debug, Clone, Copy)] +pub struct EngineTransport<'a> { + engine: &'a DownloadEngine, +} + +impl<'a> EngineTransport<'a> { + /// 绑定引擎。 + #[must_use] + pub const fn new(engine: &'a DownloadEngine) -> Self { + Self { engine } + } +} + +impl Transport for EngineTransport<'_> { + fn get_text<'a>(&'a self, url: &'a str) -> OnlineFuture<'a, Result> { + Box::pin(async move { + // `download_bytes` 不落盘（`dest` 只是请求形状的一部分），所以这里给一个中性路径； + // 内容寻址缓存按 URL 规划，不看它。 + let request = DownloadRequest::new( + ResourceKind::Other, + url, + std::env::temp_dir().join("ull-online-metadata.json"), + ); + let bytes = self + .engine + .download_bytes(request) + .await + .map_err(OnlineError::from)?; + String::from_utf8(bytes) + .map_err(|error| OnlineError::malformed(format!("{url} 的响应不是 UTF-8：{error}"))) + }) + } +} diff --git a/crates/core/src/addon/pack.rs b/crates/core/src/addon/pack.rs new file mode 100644 index 0000000..8cbc2aa --- /dev/null +++ b/crates/core/src/addon/pack.rs @@ -0,0 +1,74 @@ +//! 整合包的**格式无关模型**与**格式扩展点**（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, PACK_MAX_ENTRIES, PACK_MAX_ENTRY_BYTES, + PACK_MAX_UNCOMPRESSED_BYTES, PACK_ZIP64_BYTES_THR, +}; +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..6d4b518 --- /dev/null +++ b/crates/core/src/addon/pack/archive.rs @@ -0,0 +1,299 @@ +//! 打包输入的安全读取层：[`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, PACK_MAX_ENTRIES, PACK_MAX_ENTRY_BYTES, + PACK_MAX_UNCOMPRESSED_BYTES, PACK_ZIP64_BYTES_THR, +}; + +use limits::read_capped; + +/// 输入来源。 +pub(super) enum Source { + /// 目录（MultiMC 实例、已解开的包）。 + Dir, + /// zip（`.zip` / `.mrpack`）。`RefCell` 让只读方法能取 `&mut ZipArchive`（解压需要）。 + Zip(RefCell>), +} + +/// 一个已校验的整合包输入（目录或 zip）。 +pub struct PackArchive { + root: PathBuf, + source: Source, + entries: Vec, + index: HashMap, + 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) -> PackResult { + Self::open(path, PackLimits::default()) + } + + /// 打开一个目录或 zip，按给定限额校验。 + /// + /// 校验是**全量**的：打开成功就说明整包的条目名都过了两道穿越检查、没有符号链接、 + /// 条数与体积都在限额内。后续读取不再需要重复判断来源是否恶意。 + pub fn open(path: impl AsRef, limits: PackLimits) -> PackResult { + 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>> { + 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> { + 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> { + 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> { + self.sha1_with(name, None) + } + + /// 算 SHA-1 并从 `budget` 里扣减实际读出的字节（批量读取用）。 + fn sha1_with(&self, name: &str, budget: Option<&ReadBudget>) -> PackResult> { + 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> { + 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> { + 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..acbbec5 --- /dev/null +++ b/crates/core/src/addon/pack/archive/limits.rs @@ -0,0 +1,196 @@ +//! 读取限额：条目数 / 解压总体积 / 单条目，以及两处封顶实现。 +//! +//! # 只此一份口径（导入读取 **与** 导出写入共用） +//! +//! [`PACK_MAX_ENTRIES`] / [`PACK_MAX_UNCOMPRESSED_BYTES`] / [`PACK_MAX_ENTRY_BYTES`] 是**唯一** +//! 的体积口径：读侧 [`PackLimits::default`] 从这里取，写侧 `pack::format::write` 的预检也从 +//! 这里取（以前写侧直接拿 `zip::ZIP64_BYTES_THR`，于是"导得出来、导不回去"——导出允许 ~4 GiB， +//! 导入只允许 512 MiB）。现在的关系是硬约束： +//! +//! ```text +//! PACK_MAX_ENTRY_BYTES ≤ PACK_MAX_UNCOMPRESSED_BYTES < PACK_ZIP64_BYTES_THR ≤ u32::MAX +//! ``` +//! +//! 所以「我们能写出的包一定能被自己读回来」，而 ZIP64 阈值退化成一条**不会再被触碰的** +//! 物理上限（`tests/limits.rs` 钉住这条不等式，也钉住两侧用的是同一批常数）。 +//! +//! 为什么不让写侧跟着 ZIP64 放宽：读侧把单条目整条读进内存（[`read_capped`]），64 MiB 是**内存** +//! 护栏；放宽它等于用一个看不见的内存峰值换一个几乎用不到的大包能力。 +//! +//! # 两阶段限额（打开 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 PACK_MAX_ENTRIES: usize = 20_000; +/// 解压/打包总体积上限（512 MiB；`.mrpack` 的 `overrides` 通常几十 MiB）。 +pub const PACK_MAX_UNCOMPRESSED_BYTES: u64 = 512 * 1024 * 1024; +/// 单条目上限（64 MiB；同时是读侧的**内存**护栏与写侧的单文件护栏）。 +pub const PACK_MAX_ENTRY_BYTES: u64 = 64 * 1024 * 1024; +/// ZIP64 的物理阈值（`zip` crate 的口径，≈4 GiB）。 +/// +/// 生产路径**不再**用它当判据：PACK_MAX_UNCOMPRESSED_BYTES 远低于它（0.5 GiB ≪ 4 GiB）， +/// 所以 `tests/limits.rs` 只需钉住"统一上限 < 本阈值"，ZIP64 就永远不会被需要。 +pub const PACK_ZIP64_BYTES_THR: u64 = zip::ZIP64_BYTES_THR; + +/// 默认条目数上限（= [`PACK_MAX_ENTRIES`]，保留旧名以免破坏既有调用点）。 +pub const DEFAULT_MAX_ENTRIES: usize = PACK_MAX_ENTRIES; +/// 默认解压总体积上限（= [`PACK_MAX_UNCOMPRESSED_BYTES`]）。 +pub const DEFAULT_MAX_UNCOMPRESSED_BYTES: u64 = PACK_MAX_UNCOMPRESSED_BYTES; +/// 默认单条目上限（= [`PACK_MAX_ENTRY_BYTES`]）。 +pub const DEFAULT_MAX_ENTRY_BYTES: u64 = PACK_MAX_ENTRY_BYTES; + +/// 包读取限额。 +#[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, +} + +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> { + 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 { + 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::, _>>() + .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 { + 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, + limits: PackLimits, + ) -> PackResult { + 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, + #[serde(rename = "manifestVersion", default)] + manifest_version: Option, + #[serde(default)] + name: Option, + #[serde(default)] + version: Option, + #[serde(default)] + author: Option, + #[serde(default)] + overrides: Option, + #[serde(default)] + minecraft: Option, + #[serde(default)] + files: Vec, + #[serde(flatten)] + extra: Map, +} + +/// `minecraft` 对象。 +#[derive(Debug, Default, Deserialize)] +struct RawMinecraft { + #[serde(default)] + version: Option, + #[serde(rename = "modLoaders", default)] + mod_loaders: Vec, + #[serde(flatten)] + extra: Map, +} + +/// `minecraft.modLoaders[]` 的一条。 +#[derive(Debug, Default, Deserialize)] +struct RawLoader { + #[serde(default)] + id: Option, + #[serde(default)] + primary: bool, + #[serde(flatten)] + extra: Map, +} + +/// `files[]` 的一条。 +#[derive(Debug, Default, Deserialize)] +struct RawFile { + #[serde(rename = "projectID", default)] + project_id: Option, + #[serde(rename = "fileID", default)] + file_id: Option, + #[serde(default = "default_required")] + required: bool, + #[serde(flatten)] + extra: Map, +} + +/// 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> { + // 文件不存在 ≠ 包坏了：没有 `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 { + 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 { + 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 = bytes.iter().copied().filter(|byte| keeps(*byte)).collect(); + murmur2(&filtered) +} + +/// 对一个**文件**算指纹：两遍流式读（先数过滤后长度，再喂哈希）。 +/// +/// MurmurHash2 的初始态要事先知道总长度，所以必须两遍；这里不把文件读进内存（mod jar 可以 +/// 有几百 MB，整包导出要对每个文件算一次）。 +pub fn fingerprint_file(path: &Path) -> io::Result { + 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 { + (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, +} + +impl PackError { + /// 构造。 + #[must_use] + pub fn new(kind: PackErrorKind, message: impl Into) -> Self { + Self { + kind, + message: message.into(), + hint: None, + } + } + + /// 没格式认领 / 模型表达不了该格式。 + #[must_use] + pub fn unsupported(message: impl Into) -> Self { + Self::new(PackErrorKind::Unsupported, message) + } + + /// 清单形状不对 / 必填字段缺失。 + #[must_use] + pub fn metadata(message: impl Into) -> Self { + Self::new(PackErrorKind::Metadata, message) + } + + /// 路径穿越。 + #[must_use] + pub fn traversal(message: impl Into) -> Self { + Self::new(PackErrorKind::Traversal, message) + } + + /// 符号链接条目。 + #[must_use] + pub fn symlink(message: impl Into) -> Self { + Self::new(PackErrorKind::Symlink, message) + } + + /// 超过限额。 + #[must_use] + pub fn limits(message: impl Into) -> Self { + Self::new(PackErrorKind::Limits, message) + } + + /// 本地 IO。 + #[must_use] + pub fn io(message: impl Into) -> Self { + Self::new(PackErrorKind::Io, message) + } + + /// 补一句提示。 + #[must_use] + pub fn with_hint(mut self, hint: impl Into) -> 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 for PackError { + fn from(error: std::io::Error) -> Self { + Self::io(error.to_string()) + } +} + +impl From 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 for PackError { + fn from(error: serde_json::Error) -> Self { + Self::metadata(format!("JSON 解析失败：{error}")) + } +} + +/// `pack` 模块内的结果别名。 +pub type PackResult = Result; diff --git a/crates/core/src/addon/pack/format.rs b/crates/core/src/addon/pack/format.rs new file mode 100644 index 0000000..534c4d8 --- /dev/null +++ b/crates/core/src/addon/pack/format.rs @@ -0,0 +1,355 @@ +//! 格式扩展点：[`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::path::Path; + +use super::archive::PackArchive; +use super::curseforge; +use super::error::{PackError, PackResult}; +use super::manifest::PackManifest; +use super::modrinth; +use super::multimc; + +mod payload; +mod write; + +/// 测试用的限额记录钩子（`probe.rs`，**只在 `cfg(test)` 里编译**）：把"生产 `write()` +/// 到底传了哪份限额"变成可观测的，见该模块文档。 +#[cfg(test)] +pub(in crate::addon::pack) mod probe; + +/// 导出时的覆盖内容来源在 [`payload`] 子模块里（`payload.rs`，与本文件拆开是为了守 400 行）： +/// [`PackPayload::metadata_only`] 只写清单、[`PackPayload::from_root`] 按 +/// `//` 取文件、[`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>; + + /// 读成中间模型。 + fn read(&self, pack: &PackArchive) -> PackResult; + + /// 把模型渲染成清单 JSON（未知字段在这里回写）。 + fn render(&self, manifest: &PackManifest) -> PackResult; + + /// 这份模型的**覆盖目录集合**能不能被本格式表达（默认 `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` 出清单；④**先按声明尺寸预检 ZIP64 阈值**，再写进**临时文件**并 `rename` 到 + /// `target`（失败不留半个包）。第④步的细节见 `format::write` 模块文档。 + /// + /// # 只保证同格式往返（写给 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<()> { + // 生产口径只有一处来源：导入读取用的也是这三个数（见 `archive::limits`）。 + write_with_limits( + self, + manifest, + payload, + target, + write::WriteLimits::production(), + ) + } +} + +/// [`PackFormat::write`] 的实体：限额由调用方给。 +/// +/// # 为什么把 limits 做成参数 +/// +/// 预检的判据是「**声明尺寸** ≥ 上限」，与夹具真实大小无关。生产路径只传 +/// [`write::WriteLimits::production`]；测试传几百字节的小值，走的是**同一条** +/// `write::preflight` 分支——这样"闸在碰内容之前"不必再造 GiB 级夹具来证明。 +/// （旧版测试用 `set_len` 造"稀疏"大文件，实测在 NTFS 上**不是稀疏的**：可用空间真的 +/// 掉了那么多，见 `tests/zip64.rs` 的模块文档。） +pub(in crate::addon::pack) fn write_with_limits( + format: &F, + manifest: &PackManifest, + payload: PackPayload<'_>, + target: &Path, + limits: write::WriteLimits, +) -> PackResult<()> { + // 测试构建里记一笔"这次传的是哪份限额"：夹具缩小之后，只有它能把 + // 「生产 `write()` 传的就是 `WriteLimits::production()`」这件事变成可观测的（见 `probe`）。 + #[cfg(test)] + probe::record(limits); + + let Some(entry) = format.metadata_entry() else { + return Err(PackError::unsupported(format!( + "格式 {}（{}）只支持读取，不支持导出", + format.id(), + format.label() + )) + .with_hint("导出请选 Modrinth（.mrpack）或 CurseForge 格式")); + }; + // 先判"能不能表达"，再碰磁盘：跨格式导出宁可报错，也不产出空包。 + format.check_overrides(manifest)?; + // 模型可能来自外部构造：搬内容前把每条路径重查一遍。 + manifest.check_paths()?; + let json = format.render(manifest)?; + // 临时文件 + rename：中途失败时目标路径上不会留下"看起来能用"的半个 zip（r1 p3-1）。 + let temp = write::temporary_path(target); + match write::container(format.id(), entry, &json, manifest, payload, &temp, limits) { + 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) + } + } +} + +/// 测试要能自己给 limits：把 `write` 子模块里的类型借出来（生产代码不走这条）。 +#[cfg(test)] +pub(in crate::addon::pack) use write::WriteLimits; + +/// 一次探测的结果。 +#[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 { + let mut matched: Vec<(&'static dyn PackFormat, &'static str)> = Vec::new(); + // 命中优先于"某个格式的清单坏了"：包里躺着一份别人的坏 manifest.json 不该毁掉它。 + let mut failures: Vec = 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` 就是 `/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>, +} + +impl<'a> PackPayload<'a> { + /// 只写清单，不搬覆盖内容。 + #[must_use] + pub const fn metadata_only() -> Self { + Self { + root: None, + sources: None, + } + } + + /// 覆盖内容从 `root` 取（`//`，同格式往返用）。 + #[must_use] + pub const fn from_root(root: &'a Path) -> Self { + Self { + root: Some(root), + sources: None, + } + } + + /// 覆盖内容按**包内条目名**查表（`overrides/mods/x.jar` → 实例里的绝对/相对路径）。 + /// + /// `root` 仍然要给：映射没覆盖到的条目退回 `//`， + /// 这样"大部分文件原位、少数文件改名"的混合场景不必手写全表。 + #[must_use] + pub const fn with_sources(root: &'a Path, sources: &'a BTreeMap) -> 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/format/probe.rs b/crates/core/src/addon/pack/format/probe.rs new file mode 100644 index 0000000..3c08e22 --- /dev/null +++ b/crates/core/src/addon/pack/format/probe.rs @@ -0,0 +1,45 @@ +//! **只在测试构建里存在**的限额记录钩子（p2-1，复审 r1）。 +//! +//! # 为什么需要它 +//! +//! M166 把夹具从 GiB 缩到 KiB 之后，「生产路径 + 真超限内容」那种顺带守住生产限额的证法没了。 +//! 于是「[`super::PackFormat::write`] 到底把哪份限额交给 [`super::write_with_limits`]」 +//! **没有任何测试能观测**：把它换成 `WriteLimits::new(u64::MAX, u64::MAX, …)` 会全绿 +//! （复审 r1 实测 606 passed）。`the_production_limits_are_the_shared_constants` 只钉了 +//! `production()` 的**返回值**，没钉 `write()` 的**调用点**。 +//! +//! 所以这里加一条捕获缝：`write_with_limits` 进门时记一笔，测试走**生产**的 +//! `CURSEFORGE.write(…)` 之后断言记到的就是 [`super::write::WriteLimits::production`]。 +//! +//! # 三条纪律 +//! +//! 1. **只在 `cfg(test)` 里编译**：发布构建里这个模块不存在，`write_with_limits` 的签名也没动； +//! 2. 记录是**线程局部**的：`cargo test` 每个用例一个线程，并行跑也不会串味； +//! 3. 这是**测试设施**，不是给生产留的"放宽限额"开关——生产路径只有 +//! [`super::write::WriteLimits::production`] 一个来源。 + +use std::cell::Cell; + +use super::write::WriteLimits; + +thread_local! { + /// 本线程最近一次 [`super::write_with_limits`] 收到的限额。 + /// + /// `#[allow]` 贴在**这个 `static`** 上（M170）：clippy 1.99 的 + /// `missing_const_for_thread_local` 在初始化**已经是** `const { … }` 的写法上仍然报误报 + /// （最小复现 `static A: Cell> = const { Cell::new(None) };` 一样红）， + /// 所以要压掉。放在这里是最窄的作用域；反过来，外挂在 `thread_local!` **本身**上的 + /// `#[allow]` 才是无效的（被宏展开吞掉，报成 unused attribute）。 + #[allow(clippy::missing_const_for_thread_local)] + static LAST_LIMITS: Cell> = const { Cell::new(None) }; +} + +/// 记一笔（由 [`super::write_with_limits`] 进门时调用）。 +pub(super) fn record(limits: WriteLimits) { + LAST_LIMITS.with(|slot| slot.set(Some(limits))); +} + +/// 本线程最近一次记到的限额（`None` = 还没走过 `write_with_limits`）。 +pub(in crate::addon::pack) fn last_limits() -> Option { + LAST_LIMITS.with(Cell::get) +} diff --git a/crates/core/src/addon/pack/format/write.rs b/crates/core/src/addon/pack/format/write.rs new file mode 100644 index 0000000..68e73cb --- /dev/null +++ b/crates/core/src/addon/pack/format/write.rs @@ -0,0 +1,289 @@ +//! 把模型写成 zip：**声明尺寸预检 → 写清单 → 逐条搬覆盖内容**（`format.rs` 只留 trait 与注册表）。 +//! +//! # 为什么预检必须在读第一个字节之前 +//! +//! 一条写死的边界（research/18-p2 §8.6，A 级 `export_mrpack.rs:305-311`）：**不写 ZIP64 包**。 +//! Modrinth 官方导出撞到阈值直接报错，HMCL 那边 `(int)` 截断只打 warning 是反面教材。 +//! +//! 早先的实现是「读一个文件 → 累加 → 比较」：真要导出一个 4 GiB 覆盖文件的实例， +//! `std::fs::read` 先把它整份读进内存，闸门**永远够不着**——用户看到的是内存打爆或 IO 错， +//! 而不是"包太大，把这个文件移出实例"。所以现在先跑一遍 `metadata().len()` 累加 +//! （`preflight`），超阈值在任何内容被读进内存**之前**就报 `pack_limits`。 +//! +//! 写循环里那份增量检查保留，当第二道：预检与写入之间文件可能变大（实例目录不是快照）。 +//! **第二道自己从清单长度起算**，绝不拿预检的返回值当基数——两者合起来会重复累计， +//! 于是真实总量只要过半阈值（~2.15 GiB）就被误拒，而且拒在内容已经读出来之后（P2-1）。 +//! +//! # 内容按块搬运，不整份读进内存 +//! +//! 覆盖文件用 1 MiB 缓冲流式写进 zip（`COPY_CHUNK`）。这不是优化癖：`std::fs::read` 会把 +//! 一份 2.5 GiB 的 mod 整份摊在内存里，恰恰破坏"闸在内容进内存之前"这条性质——即使判据 +//! 后来修对了，误拒也发生在把几个 GiB 读进内存之后。流式之后第二道闸看的是**已写字节数**， +//! 与内存占用无关。 +//! +//! # 阈值与声明口径（**与导入读取同一份常量**） +//! +//! 判据是**未压缩声明的总量**（清单 JSON + 每个覆盖文件的字节数）**与单条目体积**，两个数 +//! 都来自 `pack::archive::limits`（[`WriteLimits::production`]）：以前写侧直接拿 +//! `zip::ZIP64_BYTES_THR`（≈4 GiB），导入读取只允许 512 MiB ⇒「导得出来、导不回去」。现在 +//! 只此一份口径，关系是 +//! `PACK_MAX_ENTRY_BYTES ≤ PACK_MAX_UNCOMPRESSED_BYTES < PACK_ZIP64_BYTES_THR`， +//! 所以 ZIP64 阈值永远不会被触碰（`pack/tests/limits.rs` 钉住这条不等式）。 +//! zip 条目头与中央目录的几十字节开销不计——这个常数本身就是近似边界，官方实现同样按这个 +//! 粗粒度判。 + +use std::fs::File; +use std::io::{Read, Write}; +use std::path::{Path, PathBuf}; + +use super::super::error::{PackError, PackResult}; +use super::super::manifest::PackManifest; +use super::super::path::{normalize_dir, normalize_file}; +use super::payload::PackPayload; + +/// 搬覆盖内容时的缓冲大小（流式，不把文件整份读进内存）。 +const COPY_CHUNK: usize = 1024 * 1024; + +/// 与目标同目录的临时文件路径（同卷 `rename` 才能原子替换）。 +pub(super) 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 的那一段（失败了由调用方删临时文件）。 +pub(super) fn container( + format_id: &str, + entry: &'static str, + json: &str, + manifest: &PackManifest, + payload: PackPayload<'_>, + temp: &Path, + limits: WriteLimits, +) -> PackResult<()> { + // 先判总量再碰磁盘：超限时临时文件都不建，更不会读进一份几百 MiB 的内容。 + // **返回值只属于预检**：写循环有自己的计数器（`Written`），拿它当基数会把全量声明尺寸 + // 再累加一遍 ⇒ 过拒窗口（P2-1）。 + let _ = preflight(json.len() as u64, manifest, payload, limits)?; + + 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}")))?; + + // 第二道闸的计数器：**从清单长度重新起算**，与预检的结果无关（见 `Written`）。 + let mut written = Written::new(json.len() as u64, limits.total); + let mut buffer = vec![0_u8; COPY_CHUNK]; + 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 = source_for(payload, &dir, &path)?; + let mut source_file = File::open(&source).map_err(|error| { + PackError::io(format!("读覆盖文件 {} 失败：{error}", source.display())) + })?; + writer + .start_file(name.clone(), options) + .map_err(|error| PackError::io(format!("写 {name} 失败：{error}")))?; + loop { + let read = source_file.read(&mut buffer).map_err(|error| { + PackError::io(format!("读覆盖文件 {} 失败：{error}", source.display())) + })?; + if read == 0 { + break; + } + writer + .write_all(&buffer[..read]) + .map_err(|error| PackError::io(format!("写 {name} 失败：{error}")))?; + written.spend(read as u64)?; + } + } + } + writer + .finish() + .map_err(|error| PackError::io(format!("收尾 zip 失败：{error}（格式 {format_id}）")))?; + Ok(()) +} + +/// 写盘前的**声明尺寸预检**：只量 `metadata().len()`，不读内容。 +/// +/// 返回值是"清单 + 全部覆盖文件的声明总量"，**只给测试与诊断看**。写循环有自己的计数器 +/// （从清单长度起算）——曾经把它直接当累加基数，结果每个文件的字节被算两遍，真实总量过半 +/// 阈值就被误拒（P2-1，已有端到端用例钉住这个窗口）。 +/// +/// 判据顺序是**先总量、后单条**：总量超限时给出的那句"包太大"更贴用户的实际处境 +/// （"把这个文件移出实例"只对单条超限才有意义）。 +fn preflight( + json_len: u64, + manifest: &PackManifest, + payload: PackPayload<'_>, + limits: WriteLimits, +) -> PackResult { + // **条目数闸**（读侧同一条：`PACK_MAX_ENTRIES`）。放在读盘之前：超 2 万条时连一次 + // `metadata()` 都不必做，也顺手证明"闸在碰内容之前"。清单条目自己也占一条。 + let declared_entries = 1 + manifest + .overrides + .iter() + .map(|group| group.files.len()) + .fold(0_usize, usize::saturating_add); + guard_entries(declared_entries, limits.entries)?; + + let mut total = json_len; + let mut entries: Vec<(String, u64)> = Vec::new(); + 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 source = source_for(payload, &dir, &path)?; + // 缺文件 / 读不到元数据在这里就报（与"读内容失败"同一个 `pack_io` 口径： + // 目标路径上不会留下半个包，临时文件由调用方删）。 + let length = std::fs::metadata(&source) + .map_err(|error| { + PackError::io(format!("读覆盖文件 {} 失败：{error}", source.display())) + })? + .len(); + total += length; + entries.push((format!("{dir}/{path}"), length)); + } + } + guard_with(total, limits.total)?; + for (name, length) in entries { + guard_entry(&name, length, limits.entry)?; + } + Ok(total) +} + +/// 写侧的限额口径（**默认值直接取读侧那三个常量**，见 `archive::limits` 的模块文档）。 +/// +/// 可见性是 `pub(in crate::addon::pack)`——不是 `pub(super)`：`tests/zip64.rs` 与 +/// `tests/limits.rs`（`pack::tests` 下）要能用**几百字节的小 limits** 走同一条预检分支， +/// 详见 [`super::write_with_limits`]。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(in crate::addon::pack) struct WriteLimits { + /// 未压缩总量上限。 + pub(in crate::addon::pack) total: u64, + /// 单条目上限。 + pub(in crate::addon::pack) entry: u64, + /// 条目数上限（**与读侧同一个数**：清单条目 + 每个覆盖文件）。 + pub(in crate::addon::pack) entries: usize, +} + +impl WriteLimits { + /// 生产口径：与 [`PackLimits::default`](crate::addon::pack::PackLimits) 同一个数。 + pub(in crate::addon::pack) const fn production() -> Self { + Self { + total: super::super::archive::limits::PACK_MAX_UNCOMPRESSED_BYTES, + entry: super::super::archive::limits::PACK_MAX_ENTRY_BYTES, + entries: super::super::archive::limits::PACK_MAX_ENTRIES, + } + } + + /// 显式给值（测试用：把边界缩小到可测尺寸）。 + #[cfg(test)] + pub(in crate::addon::pack) const fn new(total: u64, entry: u64, entries: usize) -> Self { + Self { + total, + entry, + entries, + } + } +} + +/// 条目数闸：与读侧的 `PACK_MAX_ENTRIES` **同一份口径**。 +/// +/// 读侧在 `archive::open` 里对"中央目录条数"判 `>= limit` 就拒；写侧产出的是"清单 + N 个覆盖 +/// 文件"，比读侧少掉目录条目，所以这里按同一侧的口径判（`count > limit` 拒，`== limit` 许可， +/// 与读侧能读回的最大值一致）。没有这道闸时，一个内容目录超过 2 万条的实例**导得出来、 +/// 自己的导入器拒读**——正是"M152 遗留的限额不衔接"那条。 +fn guard_entries(count: usize, entries_limit: usize) -> PackResult<()> { + if count > entries_limit { + return Err(PackError::limits(format!( + "包内条目数 {count} 超过统一上限 {entries_limit}（导入读取用的也是这个数）" + )) + .with_hint("把内容目录里多余的文件移出实例后再导出；单文件与总量上限也是同一份口径")); + } + Ok(()) +} + +/// 单条目闸：与读侧的 `PACK_MAX_ENTRY_BYTES` **同一份口径**。 +/// +/// 没有这道闸时，"导出 100 MiB 的覆盖文件 → 自己的导入器拒读"是能真实发生的（读侧把一条 +/// 内容整块读进内存，所以有单条上限）。写侧照着读侧的上限拒，才不会产出自己读不回来的包。 +fn guard_entry(name: &str, length: u64, entry_limit: u64) -> PackResult<()> { + if length > entry_limit { + return Err(PackError::limits(format!( + "覆盖条目 {name} 有 {length} 字节，超过单条目统一上限 {entry_limit}（导入读取用的也是这个数）" + )) + .with_hint("把该文件移出实例（或换一个不需要内联它的内容目录）后再导出")); + } + Ok(()) +} + +/// 单条覆盖文件的来源：来源表优先（跨格式导出用），否则按 `//` 拼。 +fn source_for(payload: PackPayload<'_>, dir: &str, path: &str) -> PackResult { + let name = format!("{dir}/{path}"); + if let Some(source) = payload.source_for(&name) { + return Ok(source.to_path_buf()); + } + let Some(root) = payload.root() else { + return Err(PackError::unsupported(format!( + "导出需要覆盖内容（{name}），但既没有来源映射也没有 payload 根目录" + ))); + }; + Ok(root.join(dir).join(path)) +} + +/// 写循环的第二道闸（**已写出**的未压缩字节数）。 +/// +/// 起点是**清单 JSON 的长度**，与 `preflight` 的返回值无关：两者混用会把每个文件的字节算 +/// 两遍，真实总量过半阈值（~2.15 GiB）就被误拒（P2-1）。类型上也没法混用——`Written` +/// 由 `u64` 构造，而预检的返回值是"全量声明尺寸"，只有显式取值才拿得到。 +struct Written { + total: u64, + limit: u64, +} + +impl Written { + const fn new(json_len: u64, limit: u64) -> Self { + Self { + total: json_len, + limit, + } + } + + /// 记一笔实际写出的字节，并在**每一块之后**过闸（大文件因此能在中途被拦下）。 + fn spend(&mut self, bytes: u64) -> PackResult<()> { + self.total = self.total.saturating_add(bytes); + guard_with(self.total, self.limit) + } +} + +/// 总量闸（`pack_limits`）：`total` **达到**上限就拒（`>=` 不是 `>`，撞上就不写）。 +/// +/// 生产路径的 `limit` 来自 [`WriteLimits::production`]（= 读侧 `PACK_MAX_UNCOMPRESSED_BYTES`）； +/// 把它做成参数是为了能用几十字节的小数值钉住"边界在 `>=` 上"和"写循环不许重复累计"这两件事。 +fn guard_with(total: u64, limit: u64) -> PackResult<()> { + if total >= limit { + return Err(PackError::limits(format!( + "包体未压缩总量超过统一上限 {limit} 字节（ZIP64 阈值 {} 远在其上，所以永远不需要写 ZIP64）", + super::super::archive::limits::PACK_ZIP64_BYTES_THR + )) + .with_hint("把超大的覆盖文件移出实例后再导出；导入读取用的是同一个上限")); + } + Ok(()) +} + +#[cfg(test)] +mod tests; diff --git a/crates/core/src/addon/pack/format/write/tests.rs b/crates/core/src/addon/pack/format/write/tests.rs new file mode 100644 index 0000000..2ef4b19 --- /dev/null +++ b/crates/core/src/addon/pack/format/write/tests.rs @@ -0,0 +1,206 @@ +//! `format/write.rs` 的单测：**从 `write.rs` 拆出来守 400 行硬线**。 +//! +//! 拆分口径与仓库其它拆分一致：**纯搬移**，断言与注释一行不改（只在外面加一层 `mod tests;`）。 +//! 这些用例钉的是「闸在碰内容之前」「边界在 `>=` 上」「写循环不许重复累计」三件事。 + +use super::*; +use crate::addon::pack::manifest::{OverrideFile, PackOverrides, PackSide}; +use crate::addon::temp::TempRoot; + +#[test] +fn the_threshold_is_reached_not_exceeded() { + // `>=` 而不是 `>`：恰好等于阈值就已经需要 ZIP64 了。 + assert!(guard_with(99, 100).is_ok()); + let error = guard_with(100, 100).expect_err("等于阈值必须拒"); + assert_eq!( + error.kind(), + super::super::super::error::PackErrorKind::Limits + ); + assert!(error.message().contains("100"), "{error}"); + assert!(guard_with(101, 100).is_err()); +} + +#[test] +fn the_second_gate_counts_from_the_manifest_length_not_the_preflight_total() { + // P2-1 的窗口：真实总量在 [上限一半, 上限) 之间的包**不许**被拒。这一条不真写 + // 几百 MiB（那要几十秒 deflate 与一大片内存/页面文件），而是直接把窗口里的字节数 + // 喂给第二道闸的计数器——它的起点是清单长度，所以只有"把预检的全量 total 当基数" + // 那种写法才会在这里红（红法是 `spend` 返回 Limits）。 + let limit = WriteLimits::production().total; + let inside = limit / 2 + limit / 4; + let mut written = Written::new(28, limit); + written.spend(inside).expect("没到统一上限，第二道闸不许拒"); + assert!(inside > limit / 2, "样本要落在过拒窗口里"); + + // 对照：撞上上限必须拒，且正好在上限处（不是超一点点才拒）。 + let mut written = Written::new(28, limit); + let error = written.spend(limit).expect_err("撞上限必须拒"); + assert_eq!( + error.kind(), + super::super::super::error::PackErrorKind::Limits + ); +} + +#[test] +fn the_container_does_not_double_count_the_preflight_total() { + // 容器层的窗口回归钉（P2-1），**用几十字节的 limit 把窗口缩小到可测尺寸**： + // `json` 30 字节 + 覆盖文件 40 字节 = 声明总量 70。 + // - 正确实现：第二道闸从 30 起算，写到 70 也不到 100 ⇒ 导出成功； + // - P2-1 的写法（把预检返回的全量 70 当基数）：写循环再累加 40 ⇒ 110 ≥ 100 ⇒ 误拒。 + // 真造 2.5 GB 才能暴露同一个 bug，本机资源纪律下不跑：GiB 级的**数值判定**由 + // `the_gib_scale_boundaries_decide_without_any_fixture` 用纯算术钉住。测试全部用 + // `TempRoot`（drop 即删、panic 也删）：旧版自己拼 `%TEMP%` 路径、只在**正常收尾**时删， + // 断言一红就留下 `ull-double-count-*`（M160 r2 的泄漏口径）。 + let root = TempRoot::new("double-count"); + std::fs::create_dir_all(root.join("overrides/mods")).expect("建目录"); + std::fs::write(root.join("overrides/mods/a.bin"), [0_u8; 40]).expect("写覆盖文件"); + // 清单很短，limit 取"声明总量 + 20 字节"的余量：正确实现只写到 70，重复累计会写到 110。 + let json = "{\"name\":\"0123456789012345\"}"; + let declared = json.len() as u64 + 40; + let limit = declared + 20; + let mut manifest = PackManifest::new("double count"); + manifest.overrides.push(PackOverrides { + dir: "overrides".to_string(), + side: PackSide::Both, + files: vec![OverrideFile { + path: "mods/a.bin".to_string(), + sha1: String::new(), + size: 40, + }], + }); + let target = root.join("out.zip"); + + container( + "curseforge", + "manifest.json", + json, + &manifest, + PackPayload::from_root(&root), + &target, + WriteLimits::new(limit, 1024, 16), + ) + .expect("声明总量没到 limit：写循环不许把预检的 total 重复累计"); + + // 对照：limit 降到声明总量本身 ⇒ 预检就该拒，且临时文件都没建。 + let refused = root.join("refused.zip"); + let error = container( + "curseforge", + "manifest.json", + json, + &manifest, + PackPayload::from_root(&root), + &refused, + WriteLimits::new(declared, 1024, 16), + ) + .expect_err("声明总量达到 limit 必须拒"); + assert_eq!( + error.kind(), + super::super::super::error::PackErrorKind::Limits + ); + assert!(!refused.exists(), "预检失败时目标路径不许出现"); +} + +#[test] +fn the_preflight_measures_declared_sizes_not_content() { + // 预检必须只量 `metadata().len()`。夹具刻意**只有几 KiB**（M166）：把"没读内容"钉住的是 + // **结构**而不是字节数——`container` 的顺序是 预检 → `File::create(temp)` → 打开源文件读， + // 所以"临时文件根本没被创建"等价于"一个字节的内容都没被打开过"。 + // 旧版这里造一个 3 GiB 的"稀疏"文件，实测在 NTFS 上真占 3 GiB（见 `zip64.rs` 模块文档）。 + const LIMIT: u64 = 8 * 1024; + const HUGE: u64 = 6 * 1024; + let root = TempRoot::new("preflight"); + std::fs::create_dir_all(root.join("overrides/mods")).expect("建目录"); + std::fs::write(root.join("overrides/mods/small.jar"), b"0123456789").expect("写小文件"); + std::fs::write( + root.join("overrides/mods/huge.jar"), + vec![0_u8; HUGE as usize], + ) + .expect("写大一点的覆盖文件"); + + let mut manifest = PackManifest::new("preflight"); + manifest.overrides.push(PackOverrides { + dir: "overrides".to_string(), + side: PackSide::Both, + files: vec![ + OverrideFile { + path: "mods/small.jar".to_string(), + sha1: String::new(), + size: 10, + }, + OverrideFile { + path: "mods/huge.jar".to_string(), + sha1: String::new(), + size: 0, + }, + ], + }); + + let total = preflight( + 7, + &manifest, + PackPayload::from_root(&root), + // 总量闸放到 8 KiB：声明总量 7 + 10 + 6144 仍在它之下，预检不许误伤。 + WriteLimits::new(LIMIT, LIMIT, 16), + ) + .expect("声明总量仍在闸下，预检不许误伤"); + assert_eq!(total, 7 + 10 + HUGE, "清单 + 每个覆盖文件的声明尺寸"); +} + +#[test] +fn the_production_limits_are_the_shared_constants() { + // 写侧口径的**接线**证明：生产路径拿到的就是读侧那三个常量，不是另抄一份。 + // 这条是纯算术。旧版是靠"造 64 MiB 文件、看报错文案里出现的数字"来证的—— + // 那既要真占 64 MiB，也只覆盖到文案碰巧提到的字段。 + let production = WriteLimits::production(); + assert_eq!( + production.total, + crate::addon::pack::archive::limits::PACK_MAX_UNCOMPRESSED_BYTES + ); + assert_eq!( + production.entry, + crate::addon::pack::archive::limits::PACK_MAX_ENTRY_BYTES + ); + assert_eq!( + production.entries, + crate::addon::pack::archive::limits::PACK_MAX_ENTRIES + ); +} + +#[test] +fn the_gib_scale_boundaries_decide_without_any_fixture() { + // M166：**>2 GiB 与 >4 GiB 两条边界**在这里钉，不需要落盘——两道闸吃的都是 `u64`。 + // 以前它们只有"造 4 GiB / 2.5 GB 夹具"这一条证法，而那在本机 NTFS 上是真占 4 GiB。 + use crate::addon::pack::archive::limits::{PACK_MAX_UNCOMPRESSED_BYTES, PACK_ZIP64_BYTES_THR}; + const GIB: u64 = 1024 * 1024 * 1024; + + // ① >4 GiB 那条：撞上 ZIP64 阈值就拒，差一字节就放行（`>=` 不是 `>`）。 + let zip64 = PACK_ZIP64_BYTES_THR; + assert_eq!(zip64, u32::MAX as u64, "ZIP64 阈值就是 u32::MAX ≈ 4 GiB"); + assert!(guard_with(zip64 - 1, zip64).is_ok(), "差一字节必须放行"); + let error = guard_with(zip64, zip64).expect_err("撞上 ZIP64 阈值必须拒"); + assert!(error.message().contains("ZIP64"), "{error}"); + + // ② >2 GiB 那条：M152 时代那个 2.5 GB 的样本，现在按**统一上限**（512 MiB）拒。 + let old_sample: u64 = 2_500_000_000; + assert!(old_sample > 2 * GIB, "样本必须真的在 2 GiB 之上"); + assert!( + old_sample < zip64, + "样本又必须在 ZIP64 阈值之下：拒绝理由是统一上限" + ); + let error = + guard_with(old_sample, PACK_MAX_UNCOMPRESSED_BYTES).expect_err("统一上限必须拒 2.5 GB"); + assert!( + error + .message() + .contains(&PACK_MAX_UNCOMPRESSED_BYTES.to_string()), + "文案要给出统一上限那个数：{error}" + ); + + // ③ 第二道闸（`Written`）在同一批数值上也不许误拒，越界才拒。 + let mut written = Written::new(0, zip64); + written + .spend(old_sample) + .expect("2.5 GB < ZIP64 阈值，第二道闸不许拒"); + written.spend(GIB).expect("3.5 GB 仍在上限之下"); + assert!(written.spend(GIB).is_err(), "越过 4 GiB 必须拒"); +} 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 { + 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, + /// 加载器版本。 + pub version: Option, + /// 是否主加载器（CF `primary`；其它格式取"第一条能认出来的"）。 + pub primary: bool, + /// 该加载器条目的未知字段。 + pub extra: Map, +} + +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 { + 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-`，其它版本写 `neoforge-`。 + /// 原因是 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 { + 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, Option) { + 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 { + 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, + /// 作者（CF `author`；mrpack 没有这一项）。 + pub author: Option, + /// 简介（mrpack `summary`；CF 没有这一项）。 + pub summary: Option, + /// 清单 schema 版本（CF `manifestVersion` / mrpack `formatVersion` / MultiMC `formatVersion`）。 + pub format_version: Option, + /// 平台标识（mrpack `game`，恒为 `minecraft`；CF 隐式，`None`）。 + pub game: Option, + /// 游戏版本（`1.20.1`）。 + pub minecraft: Option, + /// 加载器依赖集合。 + pub loaders: Vec, + /// 远端文件条目（不含覆盖目录里的文件）。 + pub files: Vec, + /// 覆盖目录清单。 + pub overrides: Vec, + /// 清单顶层的未知字段（原样保存、导出时回写）。 + pub extra: Map, + /// CF `minecraft` 对象里的未知字段（mrpack/MultiMC 没有这一层）。 + pub minecraft_extra: Map, +} + +impl PackManifest { + /// 建一个只有包名的空清单。 + #[must_use] + pub fn new(name: impl Into) -> 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 { + 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 { + 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, usize)> { + struct Slot { + sides: Vec, + 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, 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, + /// CF `projectID`。 + pub project_id: Option, + /// CF `fileID`。 + pub file_id: Option, + /// 摘要表（键名小写：`sha1` / `sha512` / `sha256` / `md5`）。mrpack 要求有 `sha512`。 + pub hashes: BTreeMap, + /// 下载候选（mrpack `downloads`，多源；CF 官方清单没有，要靠 CDN 规则或 API 拼）。 + pub downloads: Vec, + /// 文件字节数（mrpack `fileSize`）。 + pub size: Option, + /// 是否"以禁用态安装"（`.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, + /// `env` 对象里的未知字段。 + pub env_extra: Map, +} + +impl PackFile { + /// 只带路径的条目（mrpack 侧最简形态）。 + #[must_use] + pub fn with_path(path: impl Into) -> 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::` / `modrinth::`， + /// 两者都没有时退回路径。 + #[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, +} + +impl PackOverrides { + /// 建一个空目录清单。 + #[must_use] + pub fn new(dir: impl Into, 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, extra: &Map) { + 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, + #[serde(rename = "formatVersion", default)] + format_version: Option, + #[serde(rename = "versionId", default)] + version_id: Option, + #[serde(default)] + name: Option, + #[serde(default)] + summary: Option, + #[serde(default)] + files: Vec, + #[serde(default)] + dependencies: BTreeMap, + #[serde(flatten)] + extra: Map, +} + +/// `files[]` 的一条。 +#[derive(Debug, Default, Deserialize)] +struct RawFile { + #[serde(default)] + path: Option, + #[serde(default)] + hashes: BTreeMap, + #[serde(default)] + env: Option, + #[serde(default)] + downloads: Vec, + #[serde(rename = "fileSize", default)] + file_size: Option, + #[serde(flatten)] + extra: Map, +} + +/// `files[].env`。 +#[derive(Debug, Default, Deserialize)] +struct RawEnv { + #[serde(default)] + client: Option, + #[serde(default)] + server: Option, + #[serde(flatten)] + extra: Map, +} + +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> { + 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 = 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 { + 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 = 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 { + 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) -> 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::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, + #[serde(default)] + components: Vec, + #[serde(flatten)] + extra: Map, +} + +/// `components[]` 的一条。 +#[derive(Debug, Default, Deserialize)] +struct RawComponent { + #[serde(default)] + uid: Option, + #[serde(default)] + version: Option, + #[serde(flatten)] + extra: Map, +} + +impl PackFormat for MultiMc { + fn id(&self) -> &'static str { + ID + } + + fn label(&self) -> &'static str { + "MultiMC / Prism" + } + + fn detect(&self, pack: &PackArchive) -> PackResult> { + 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 { + 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 = 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 { + Err(PackError::unsupported( + "MultiMC 格式只支持导入：写回需要重组组件图与 patches/libraries，不在模型职责内", + ) + .with_hint("导出请选 Modrinth（.mrpack）或 CurseForge 格式")) + } +} + +/// 从 `instance.cfg` 的 `name=` 行取实例名（MultiMC 的 ini 很宽松，只认这一行）。 +fn instance_name(pack: &PackArchive) -> Option { + 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 { + 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 { + 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 { + 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..11be5eb --- /dev/null +++ b/crates/core/src/addon/pack/tests/detect.rs @@ -0,0 +1,232 @@ +//! 探测优先级：顺序写死在注册表里，用例把"谁赢"和"为什么赢"都钉住。 +//! +//! 判据分三层，缺一层都可能被"看起来对"糊过去： +//! 1. 内置顺序本身（[`PackRegistry::ids`]）； +//! 2. 同一份包命中多格式时选谁（含 `also_matched` 记录的其它命中）； +//! 3. **换一下注册顺序，赢家跟着换**——这才证明优先级来自注册表，而不是代码里散落的 if。 + +use super::{fixtures, write_zip, TempRoot}; +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) -> TempRoot { + // 返回的是**守卫**（Deref 到 `hybrid.zip`）：包文件活到调用点用完为止。 + let target = TempRoot::at(tag, "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 hybrid = hybrid_pack("detect-hybrid"); + let pack = PackArchive::open_default(&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 root = TempRoot::new("detect-plain"); + let target = root.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 root = TempRoot::new("detect-order"); + let target = root.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 root = TempRoot::new("detect-unknown"); + let target = root.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 root = TempRoot::new("detect-mmc-empty"); + let target = root.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 root = TempRoot::new("corrupt-manifest"); + let target = root.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 root = TempRoot::new("corrupt-foreign"); + let target = root.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 root = TempRoot::new("no-manifest"); + let target = root.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..3b94e89 --- /dev/null +++ b/crates/core/src/addon/pack/tests/export.rs @@ -0,0 +1,158 @@ +//! 导出面的安全闸（r1 p2-1 / p3-1）：**跨格式导出必须被拒，失败不留半个包**。 +//! +//! 这一组不测"映射是否做对"（那是 M112），只测"表达不了的时候会不会静默产出空包"。 + +use super::{fixtures, TempRoot}; +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 root = TempRoot::new("export-cf-two"); + let target = root.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 = TempRoot::new("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 = 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 root = TempRoot::new("export-mr-same-side"); + let target = root.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..be3ccc0 --- /dev/null +++ b/crates/core/src/addon/pack/tests/export_harness.rs @@ -0,0 +1,122 @@ +//! 导出测试的共用夹具（M112）：实例目录、`versions/` 版本层、假的远端目录。 +//! +//! 这里的东西**只给测试用**：本仓库没有 Modrinth/CF 客户端（要网络与 key），所以远端查表一律 +//! 由 [`StubCatalog`] 注入；实例目录手造成"M111 导入产物"的形状（内容目录 + 版本 JSON）。 + +use std::cell::RefCell; +use std::collections::BTreeMap; +use std::path::Path; + +use super::{write_file, TempRoot}; +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 { + DEFAULT_CONTENT_ROOTS.map(str::to_string).to_vec() +} + +/// 写一份 `/.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) -> TempRoot { + // 返回守卫本身（`Deref` 到 `/game`）：实例目录活到调用点用完为止，drop 即删。 + let root = TempRoot::under(tag, "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) -> TempRoot { + let root = TempRoot::under(tag, "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, + curse: BTreeMap, + curse_calls: RefCell>, +} + +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 { + self.curse_calls.borrow().clone() + } +} + +impl RemoteCatalog for StubCatalog { + fn modrinth_by_sha1(&self, sha1: &str) -> Option { + self.modrinth.get(sha1).cloned() + } + + fn curseforge_by_fingerprint(&self, value: u32) -> Option { + 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..6d3966c --- /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::{write_file, TempRoot}; +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 { + 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 = TempRoot::new("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..f02a1c5 --- /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//.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; + +use super::export_harness::{ + defaults, modrinth_hit, write_layer, StubCatalog, FORGE_LAYER, VANILLA_LAYER, +}; +use super::{fixtures, write_file, TempRoot}; +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; + +/// 把夹具里的覆盖内容铺成一个实例目录（`/`），并写一份版本 JSON。 +fn instance_from(fixture_dir: &Path, manifest: &PackManifest, tag: &str) -> TempRoot { + let game = TempRoot::under(tag, "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 { + let mut paths: Vec = 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 = TempRoot::new("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..78dcf9d --- /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::{write_file, write_zip, TempRoot}; +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> { + 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 { + 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 { + 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) -> TempRoot { + let dir = TempRoot::under(tag, "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 = TempRoot::new("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..a4fa451 --- /dev/null +++ b/crates/core/src/addon/pack/tests/fixtures.rs @@ -0,0 +1,201 @@ +//! 本地夹具：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::{write_file, zip_dir, TempRoot}; + +/// 一个既有源目录（可当导出 payload）又有打好的 zip 的夹具。 +/// +/// `_root` 是临时根的**守卫**：夹具活多久，目录就活多久；夹具 drop（含测试 panic 展开）时 +/// 整个临时根被删。没有它，这些手造包会一直堆在 `%TEMP%` 里（M160 r2：实测堆到 110 GB）。 +pub(crate) struct Fixture { + /// 源目录（zip 的内容来源，也是 `PackPayload::from_root` 的根）。 + pub dir: PathBuf, + /// 打好的包。 + pub zip: PathBuf, + /// 临时根守卫（只为了在夹具存活期间保住 `dir` / `zip`）。 + _root: TempRoot, +} + +/// 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 = TempRoot::new(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, + _root: root, + } +} + +/// Modrinth 夹具（`modrinth.index.json` + 三个覆盖目录，含一个半截 jar）。 +pub(crate) fn modrinth(tag: &str) -> Fixture { + let root = TempRoot::new(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, + _root: root, + } +} + +/// MultiMC 夹具：**目录形式**（真实形态就是实例目录，不是 zip），含一个零字节 jar。 +/// +/// 返回 `TempRoot`（`Deref` 指向 `/instance`）：调用点照旧当路径用， +/// 而临时根由返回值持有——用到哪、活到哪、drop 就删。 +pub(crate) fn multimc(tag: &str) -> TempRoot { + let root = TempRoot::under(tag, "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/limits.rs b/crates/core/src/addon/pack/tests/limits.rs new file mode 100644 index 0000000..ee5d7ae --- /dev/null +++ b/crates/core/src/addon/pack/tests/limits.rs @@ -0,0 +1,320 @@ +//! 限额口径的统一（M160）：**导入读取与导出写入只此一份常数**，且不等式关系钉死在这里。 +//! +//! # 为什么需要这个文件 +//! +//! M152 之前两侧各写各的：读侧 `PackLimits` 是 20 000 条 / 512 MiB / 64 MiB，写侧直接拿 +//! `zip::ZIP64_BYTES_THR`（≈4 GiB）与 u32。结果是一个**能导出、导不回来**的包是合法的。 +//! 现在写侧改读同一份常量（`WriteLimits::production`），本文件就是那条口径的证据： +//! +//! 1. 三个常量之间的关系（`entry ≤ total < ZIP64 ≤ u32`）； +//! 2. 读侧 `PackLimits::default()` 就是这三个数； +//! 3. 写侧在**单条边界**上拒（`>` 而不是 `≥`：恰好 64 MiB 合法）； +//! 4. 写侧在**总量**上拒，且拒绝发生在读内容之前（临时目录里什么都不留）。 +//! +//! # 夹具是 KiB 级，判据仍是生产口径（M166） +//! +//! 第 3、4 条以前靠"造 64 MiB 的**稀疏**文件"验，以为稀疏不占磁盘。**实测不成立**：本机 +//! NTFS 上 `set_len` 真占（`SetLength(1 GiB)` ⇒ C 盘可用空间掉 1024 MiB，见 +//! `tests/zip64.rs` 的模块文档），那三条用例合计真占 ~700 MiB。 +//! +//! 现在判据的**数值**用纯算术钉（`format/write/tests.rs` 的 +//! `the_production_limits_are_the_shared_constants` 证明生产路径拿的就是这三个常量）， +//! **分支**用 `format::write_with_limits` 把 limits 缩到 KiB 级来验——两条合起来等价于 +//! 原来的"造 64 MiB 看文案"，但一条用例都 `#[ignore]`、一条断言都没删。 + +use super::{write_file, TempRoot}; +use crate::addon::pack::archive::limits::{ + PACK_MAX_ENTRIES, PACK_MAX_ENTRY_BYTES, PACK_MAX_UNCOMPRESSED_BYTES, PACK_ZIP64_BYTES_THR, +}; +use crate::addon::pack::curseforge::CURSEFORGE; +use crate::addon::pack::error::PackErrorKind; +use crate::addon::pack::format::{write_with_limits, PackFormat, PackPayload, WriteLimits}; +use crate::addon::pack::manifest::{OverrideFile, PackManifest, PackOverrides, PackSide}; +use crate::addon::pack::PackLimits; + +/// 小 limits 用的单条目上限（生产口径是 64 MiB，这里缩到 2 KiB）。 +const ENTRY: u64 = 2 * 1024; + +/// 一个覆盖文件的声明（内容由调用方提供）。 +fn override_file(path: &str) -> OverrideFile { + OverrideFile { + path: path.to_string(), + sha1: "0".repeat(40), + size: 0, + } +} + +fn manifest_of(files: Vec) -> PackManifest { + 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 { + dir: "overrides".to_string(), + side: PackSide::Both, + files, + }); + manifest +} + +/// 造一个真有 `length` 字节内容的覆盖文件（**不稀疏**，见模块文档）。 +fn content_file(path: &std::path::Path, length: u64) { + write_file( + path, + &vec![0_u8; usize::try_from(length).expect("夹具尺寸")], + ); +} + +#[test] +fn the_write_side_refuses_a_pack_over_the_unified_entry_count() { + // 写侧以前只有总量与单条两道闸：内容目录超过 2 万条的实例**导得出来、自己拒读** + // （读侧 `archive::open` 的「条目数超过上限」）。这条钉住第三道闸，以及它挡在**读盘之前**。 + let root = TempRoot::new("limits-entries"); + write_file(&root.join("overrides/mods/a.jar"), b"x"); + let target = root.join("out.zip"); + + // ① 对照：条目数远低于上限时不许误伤。 + CURSEFORGE + .write( + &manifest_of(vec![override_file("mods/a.jar")]), + PackPayload::from_root(&root), + &target, + ) + .expect("单个覆盖条目必须写得出来"); + let _ = std::fs::remove_file(&target); + + // ② 声明 20001 条（上限 20000 + 1）：只有**第一条**的文件真的存在，其余 2 万条谁都不在盘上。 + // 报出来的必须是 `pack_limits` 而不是 `pack_io` —— 那就是"条目数闸在读第一个文件之前"的证据 + // （真去 `metadata()` 的话，第二个文件就已经报 `pack_io` 了）。 + // 这条**不需要**小 limits：清单条目本身不占磁盘，2 万条只是一个 JSON 数组。 + let mut files = vec![override_file("mods/a.jar")]; + for index in 1..=PACK_MAX_ENTRIES { + files.push(override_file(&format!("mods/{index:05}.jar"))); + } + assert_eq!(files.len(), PACK_MAX_ENTRIES + 1, "上限 + 1 条"); + let error = CURSEFORGE + .write(&manifest_of(files), PackPayload::from_root(&root), &target) + .expect_err("超过条目数上限必须拒"); + assert_eq!(error.kind(), PackErrorKind::Limits, "{error}"); + assert!( + error.message().contains(&PACK_MAX_ENTRIES.to_string()), + "文案要给出统一上限那个数（读侧用的是同一个）：{error}" + ); + assert!( + error.hint().is_some_and(|hint| hint.contains("移出实例")), + "要给可执行的下一步：{error:?}" + ); + assert!(!target.exists(), "预检失败时目标路径不许出现"); +} + +#[test] +fn the_entry_count_gate_is_the_same_number_as_the_read_side() { + // 「三个常量同源」的写侧那一半：生产口径的条目数上限必须**就是**读侧那个常量。 + // 改坏它会先在 `pick` 这层红，而不是等某个用户导出 2 万条内容的实例才发现。 + let production = crate::addon::pack::archive::limits::PACK_MAX_ENTRIES; + let read_side = PackLimits::default().max_entries; + assert_eq!(production, read_side, "写侧与读侧必须是同一个数"); + assert_eq!(read_side, 20_000, "上限本身也钉住（改数值要显式改这里）"); +} + +#[test] +fn the_three_limits_form_one_chain_and_the_read_side_uses_them() { + // ① 关系：单条 ≤ 总量 < ZIP64 ≤ u32。前一半保证"能写出来的包读得回来"， + // 后一半保证我们永远不需要写 ZIP64，也永远撞不到 mrpack 的 fileSize(u32) 上限。 + // 这三条是**编译期**断言（`const` 块，而且写在 `#[test] fn` 体内 ⇒ **只在测试构建里存在**）： + // 改坏常量会在 `cargo test` / `cargo clippy --all-targets` 的编译期就红（E0080）， + // 不用等跑到测试函数；但**裸 `cargo check -p unlucky-core`** 是 lib 非测试构建， + // 看不见这些断言（复审 r1 实测：E0080 只在 `--no-run`/`--all-targets` 下出现）。 + const _: () = assert!( + PACK_MAX_ENTRY_BYTES <= PACK_MAX_UNCOMPRESSED_BYTES, + "单条上限必须 ≤ 总量上限（否则单条规则永远够不着）" + ); + const _: () = assert!( + PACK_MAX_UNCOMPRESSED_BYTES < PACK_ZIP64_BYTES_THR, + "总量上限必须严格低于 ZIP64 阈值" + ); + const _: () = assert!( + PACK_ZIP64_BYTES_THR <= u32::MAX as u64, + "ZIP64 阈值也不该越过 u32（mrpack fileSize 的口径）" + ); + + // ② 读侧默认限额就是这三个数（不是"看起来一样"的另一份拷贝）。 + let limits = PackLimits::default(); + assert_eq!(limits.max_entries, PACK_MAX_ENTRIES); + assert_eq!(limits.max_uncompressed_bytes, PACK_MAX_UNCOMPRESSED_BYTES); + assert_eq!(limits.max_entry_bytes, PACK_MAX_ENTRY_BYTES); +} + +#[test] +fn the_write_side_refuses_a_single_entry_over_the_unified_entry_limit() { + // 单条目那道闸。生产口径下"恰好 +1 字节超 64 MiB"要真占 64 MiB，所以这里把 limits + // 缩到 KiB 级、触发**同一条** `guard_entry` 分支；生产数值由 + // `format/write/tests.rs::the_production_limits_are_the_shared_constants` 钉住。 + let root = TempRoot::new("limits-entry"); + let limits = WriteLimits::new(ENTRY * 4, ENTRY, 16); + // 恰好 +1 字节超**单条**上限；声明总量（清单 + 2049）仍在总量上限 ENTRY*4 之下， + // 所以只有 `guard_entry` 能拒——两档判据没串味。 + content_file(&root.join("overrides/mods/too-big.jar"), ENTRY + 1); + assert!( + ENTRY + 1 < limits.total, + "样本的声明总量必须仍在总量上限之下" + ); + let target = root.join("out.zip"); + + let error = write_with_limits( + &CURSEFORGE, + &manifest_of(vec![override_file("mods/too-big.jar")]), + PackPayload::from_root(&root), + &target, + limits, + ) + .expect_err("超过单条统一上限必须拒"); + + assert_eq!(error.kind(), PackErrorKind::Limits, "{error}"); + assert!( + error.message().contains(&ENTRY.to_string()), + "文案要给出在用的那个单条上限：{error}" + ); + assert!( + error.hint().is_some_and(|hint| hint.contains("移出实例")), + "要给可执行的下一步：{error:?}" + ); + assert!(!target.exists(), "预检失败时目标路径不许出现"); + // 预检在建临时文件之前就失败 ⇒ 目录里只有源目录，没有 `out.zip.*.part`。 + let leftovers: Vec = std::fs::read_dir(&root) + .expect("列目录") + .filter_map(Result::ok) + .map(|entry| entry.file_name().to_string_lossy().to_string()) + .filter(|name| name != "overrides") + .collect(); + assert!(leftovers.is_empty(), "不许留临时文件：{leftovers:?}"); +} + +#[test] +fn the_entry_boundary_is_exactly_the_limit() { + // 边界口径是 `>`：恰好等于上限合法（与读侧的 `size > max_entry_bytes` 同一侧）。 + let root = TempRoot::new("limits-boundary"); + let limits = WriteLimits::new(ENTRY * 4, ENTRY, 16); + content_file(&root.join("overrides/mods/exact.jar"), ENTRY); + let target = root.join("out.zip"); + + write_with_limits( + &CURSEFORGE, + &manifest_of(vec![override_file("mods/exact.jar")]), + PackPayload::from_root(&root), + &target, + limits, + ) + .expect("恰好等于上限必须写得出来（否则两侧的边界就错开了）"); + let written = crate::addon::pack::PackArchive::open( + &target, + // 读回来时单条上限就是"恰好等于它"，证明写出来的东西读侧认。 + PackLimits { + max_entry_bytes: ENTRY, + ..PackLimits::default() + }, + ) + .expect("刚写出来的包必须能被自己的读取层打开"); + assert!(written.has_entry("overrides/mods/exact.jar")); +} + +#[test] +fn the_write_side_refuses_a_total_over_the_unified_total_limit() { + // 每条都在单条上限之内（2 KiB），但只要 3 条就超总量（6 KiB + 清单 ≥ 6 KiB）—— + // 这条与"单条规则"是两件事：判据是**累计**。以前是 9 × 64 MiB = 576 MiB 真占用。 + let root = TempRoot::new("limits-total"); + let limits = WriteLimits::new(ENTRY * 3, ENTRY, 16); + let mut files = Vec::new(); + for index in 0..3 { + let relative = format!("mods/part-{index}.jar"); + content_file(&root.join("overrides").join(&relative), ENTRY); + files.push(override_file(&relative)); + } + let total = ENTRY * 3; + assert!( + ENTRY <= limits.entry, + "每条都必须在单条上限之内（判据是累计，不是单条）" + ); + assert!(total >= limits.total, "三条加起来必须真的超总量"); + let target = root.join("out.zip"); + + let error = write_with_limits( + &CURSEFORGE, + &manifest_of(files), + PackPayload::from_root(&root), + &target, + limits, + ) + .expect_err("累计超总量必须拒"); + + assert_eq!(error.kind(), PackErrorKind::Limits, "{error}"); + assert!( + error.message().contains(&total.to_string()), + "文案要给出在用的总量上限：{error}" + ); + assert!(!target.exists()); +} + +#[test] +fn the_production_write_path_hands_the_shared_constants_to_the_preflight() { + // p2-1（复审 r1）：夹具缩到 KiB 之后，"生产路径 + 真超限内容"那种顺带守住生产限额的 + // 证法没了，于是「`PackFormat::write` 到底把哪份限额交给 `write_with_limits`」 + // 没有任何测试能观测——把它换成 `WriteLimits::new(u64::MAX, u64::MAX, …)` 会全绿。 + // `the_production_limits_are_the_shared_constants` 只钉了 `production()` 的**返回值**， + // 这条钉的是**调用点**（走生产的 `CURSEFORGE.write`，靠 `format::probe` 记录）。 + let root = TempRoot::new("limits-binding"); + write_file(&root.join("overrides/mods/jei.jar"), b"PK\x03\x04 jei"); + let target = root.join("out.zip"); + + CURSEFORGE + .write( + &manifest_of(vec![override_file("mods/jei.jar")]), + PackPayload::from_root(&root), + &target, + ) + .expect("正常尺寸必须写得出来"); + + let recorded = crate::addon::pack::format::probe::last_limits() + .expect("生产 write() 必须经过 write_with_limits"); + let production = WriteLimits::production(); + assert_eq!(recorded.total, production.total, "总量限额：生产路径传错了"); + assert_eq!( + recorded.entry, production.entry, + "单条目限额：生产路径传错了" + ); + assert_eq!( + recorded.entries, production.entries, + "条目数限额：生产路径传错了" + ); + // 再把生产值本身钉在统一常量上：两条合起来才等于"生产路径用的是读侧那三个数"。 + assert_eq!(recorded.total, PACK_MAX_UNCOMPRESSED_BYTES); + assert_eq!(recorded.entry, PACK_MAX_ENTRY_BYTES); + assert_eq!(recorded.entries, PACK_MAX_ENTRIES); +} + +#[test] +fn a_real_pack_written_under_the_limit_reopens_under_the_read_limits() { + // 端到端的那句话："我们能写出的包一定能被自己读回来"。用一份正常尺寸的覆盖内容跑一遍。 + let root = TempRoot::new("limits-parity"); + write_file(&root.join("overrides/mods/jei.jar"), b"PK\x03\x04 jei"); + write_file( + &root.join("overrides/config/known.toml"), + b"shared = true\n", + ); + let target = root.join("out.mrpack"); + + crate::addon::pack::modrinth::MODRINTH + .write( + &manifest_of(vec![ + override_file("mods/jei.jar"), + override_file("config/known.toml"), + ]), + PackPayload::from_root(&root), + &target, + ) + .expect("正常尺寸必须写得出来"); + + let pack = crate::addon::pack::PackArchive::open_default(&target) + .expect("默认限额（= 统一口径）必须读得回来"); + assert!(pack.has_entry("overrides/mods/jei.jar")); + assert!(pack.has_entry("overrides/config/known.toml")); +} 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..8de9bb5 --- /dev/null +++ b/crates/core/src/addon/pack/tests/mod.rs @@ -0,0 +1,170 @@ +//! `addon::pack` 的单元测试：夹具读回、未知字段往返、探测优先级、扩展点、恶意样本。 +//! +//! **全部离线**：没有网络调用，也没有真实整合包样本（见 `fixtures` 的来源声明）。 +//! +//! # 临时目录必须**测试自己收尾**（M160 r2） +//! +//! 每个用例的临时根是 [`TempRoot`]：`Drop` 里 `remove_dir_all`，所以**正常结束与 panic 展开 +//! 都会删**（Rust 展开会跑析构）。这条不是洁癖：`zip64` 那族用例历史上要造 4 GiB 的"稀疏" +//! 文件验阈值（**实测在 NTFS 上真占 4 GiB**，见 `tests/zip64.rs` 的模块文档），残留会把 +//! `%TEMP%` 堆到撑爆整台机器（实测 1651 个目录 / 110 GB，把 CI 与别的 agent 的构建一起咬死）。 +//! M166 之后夹具缩到 KiB 级，但"测试自己收尾"这条不变——泄漏一次就是几十 GB 的量级。 +//! +//! 写法的来源是仓库既有的那一份（`crate::update::tests::support::TempDir`）：同样的 `new` / +//! `join` / `Drop` 三件套，只把前缀换成 `ull-pack-`，不引 `tempfile`、不新增第四种范式。 +//! 不信"系统会自动清 `%TEMP%`"——那要靠时间或外部工具，测试必须自证干净。 + +mod detect; +mod export; +mod export_harness; +mod export_pipeline; +mod export_roundtrip; +mod extend; +mod fixtures; +mod limits; +mod model; +mod roundtrip; +mod safety; +mod unknown_fields; +mod zip64; + +use std::fs::File; +use std::io::Write; +use std::path::{Path, PathBuf}; + +pub(crate) use crate::addon::temp::TempRoot; + +/// 写一个夹具文件（自动建父目录）。 +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::, _>>() + .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"); +} + +#[test] +fn the_temp_root_is_gone_once_dropped() { + // 自证①：正常路径。用完（drop）之后连目录都不该存在。 + let path = { + let root = TempRoot::new("self-proof"); + write_file(&root.join("overrides/mods/a.jar"), b"x"); + assert!(root.path().is_dir(), "活在的时候必须是真目录"); + root.path().to_path_buf() + }; + assert!( + !path.exists(), + "drop 之后临时根必须被删掉：{}", + path.display() + ); +} + +#[test] +fn a_panicking_test_still_removes_its_temp_root() { + // 自证②：panic 展开路径。断言"panic 也删"——这正是大夹具残留的那条路： + // 断言红了不代表可以留下 110 GB。 + let path = std::sync::Arc::new(std::sync::Mutex::new(PathBuf::new())); + let slot = std::sync::Arc::clone(&path); + let outcome = std::panic::catch_unwind(move || { + let root = TempRoot::new("self-proof-panic"); + write_file(&root.join("overrides/mods/a.jar"), b"x"); + *slot.lock().expect("锁") = root.path().to_path_buf(); + panic!("故意失败：展开时守卫要照删不误"); + }); + assert!(outcome.is_err(), "这个用例必须真的走 panic 分支"); + let path = path.lock().expect("锁").clone(); + assert!( + !path.exists(), + "panic 之后临时根必须被删掉：{}", + path.display() + ); +} + +#[test] +fn a_sub_directory_root_takes_its_parent_with_it() { + // 自证③：`under` 造的子树删的是**根**，不给 `%TEMP%` 留一堆空壳父目录。 + let (sub, parent) = { + let root = TempRoot::under("self-proof-under", "instance"); + write_file(&root.join("mmc-pack.json"), b"{}"); + ( + root.path().to_path_buf(), + root.path().parent().map(Path::to_path_buf), + ) + }; + assert!(!sub.exists(), "子树要删"); + assert!( + parent.is_some_and(|parent| !parent.exists()), + "父目录也不许留空壳" + ); +} 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..fb00102 --- /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::TempRoot::new("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::TempRoot::new("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..157c915 --- /dev/null +++ b/crates/core/src/addon/pack/tests/safety.rs @@ -0,0 +1,321 @@ +//! 恶意样本：每条安全判据都配一条"会失败的包"，而不是靠注释保证。 +//! +//! 覆盖：路径穿越四类形状（`..` / 绝对路径 / 反斜杠 / 盘符）、符号链接条目、条目数上限、 +//! 解压总体积上限、单条目上限、规整后重名、篡改载荷（CRC 不符）、以及**清单字段里的**穿越 +//! （mrpack `files[].path`、CF `overrides`）。 + +use std::path::Path; + +use super::{write_zip, write_zip_with_symlink, TempRoot}; +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) -> TempRoot { + let target = TempRoot::at(tag, "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 root = TempRoot::new("symlink"); + let target = root.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 root = TempRoot::new("limit-count"); + let target = root.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 root = TempRoot::new("limit-volume"); + let target = root.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 root = TempRoot::new("limit-entry"); + let target = root.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 root = TempRoot::new("dup-name"); + let target = root.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 root = TempRoot::new("tampered"); + let target = root.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 root = TempRoot::new("mr-trav"); + let target = root.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 root = TempRoot::new("cf-trav"); + let target = root.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 root = TempRoot::new("missing"); + let target = root.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 = TempRoot::under("dir-symlink", "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..364faa2 --- /dev/null +++ b/crates/core/src/addon/pack/tests/unknown_fields.rs @@ -0,0 +1,166 @@ +//! 「未知字段不丢」的三处条目级 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::TempRoot::new("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::TempRoot::new("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::TempRoot::new("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")); +} + +#[test] +fn mrpack_file_unknown_keys_survive_read_write_reread() { + // 第四个假边（M152 补）：`files[]` 这一层。上面三条覆盖了 `env` / CF `files[]` / + // CF `modLoaders[]`，而 mrpack 的文件级未知键一直没人钉——它恰恰是"社区给某条文件加 + // 一个私有字段"最常出现的位置（例如镜像站塞的 `mirror` / 作者写的 `optionalReason`）。 + let root = super::TempRoot::new("mr-file-extra"); + let dir = root.join("src"); + super::write_file( + &dir.join("modrinth.index.json"), + br#"{"game":"minecraft","formatVersion":1,"versionId":"1.0","name":"file extra keys", + "files":[{"path":"mods/a.jar", + "hashes":{"sha1":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "sha512":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", + "md5":"d41d8cd98f00b204e9800998ecf8427e"}, + "downloads":["https://cdn.modrinth.com/data/abc/versions/x/a.jar"], + "fileSize":42, + "mirror":"https://mirror.example.invalid/a.jar", + "optionalReason":{"why":"kept for the community"}}], + "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].extra["mirror"], + json!("https://mirror.example.invalid/a.jar") + ); + assert_eq!( + manifest.files[0].extra["optionalReason"], + json!({"why": "kept for the community"}) + ); + // 未知**哈希算法**也不丢：`hashes` 是整张表，不是两个字段。 + assert_eq!( + manifest.files[0].hashes.get("md5").map(String::as_str), + Some("d41d8cd98f00b204e9800998ecf8427e") + ); + + 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, "files[] 里的未知键必须原样回写"); + assert_eq!( + reread.files[0].extra["optionalReason"], + json!({"why": "kept for the community"}) + ); +} diff --git a/crates/core/src/addon/pack/tests/zip64.rs b/crates/core/src/addon/pack/tests/zip64.rs new file mode 100644 index 0000000..af8dff8 --- /dev/null +++ b/crates/core/src/addon/pack/tests/zip64.rs @@ -0,0 +1,345 @@ +//! 导出侧的体积闸：**拒写**过大包（research/18-p2 §8.6 / 表 B #17 的导出侧那条）。 +//! +//! # 现在的判据是「与导入读取同一份常量」（M160） +//! +//! 以前判据是 `zip::ZIP64_BYTES_THR`（≈4 GiB），而导入读取只允许 512 MiB —— 于是存在 +//! 「导得出来、导不回去」的包。M160 把写侧上限换成读侧那份常量（`pack::archive::limits`）， +//! 本文件仍钉**同一件事**：闸门在碰内容之前就把包拒了。只是拒绝的理由从"要写 ZIP64" +//! 变成"超过统一上限，所以永远不会写出 ZIP64"。 +//! +//! # 夹具只有几 KiB（M166） +//! +//! 判据是**声明尺寸**（`metadata().len()`），所以判据本身跟夹具真实大小无关。旧版本靠 +//! `File::set_len` 造 4 GiB「稀疏文件」，以为"只改 EOF、不占磁盘"——**实测是错的**： +//! +//! ```text +//! PS> $fs=[IO.File]::Create("$env:TEMP\probe.bin"); $fs.SetLength(1GB); $fs.Close() +//! logical=1024.0MiB freeDelta=1024.0MiB # 可用空间真的掉了 1 GiB +//! ``` +//! +//! 本机是 NTFS（Windows 11）。ext4 / APFS 上 `truncate`（= `set_len`）通常确实不分配块， +//! **但那是平台差异，不是可以依赖的性质**；而在 NTFS 上这两条用例的声明尺寸合计 +//! `u32::MAX + 1`（≈4 GiB）+ `3 × 1.5 GiB`（4.5 GiB）= **8.5 GiB 真占用**。 +//! +//! 现在改走 [`format::write_with_limits`]：limits 缩到 KiB 级，几百字节的**真**文件就触发 +//! 同一条预检分支（`write::preflight` → `guard_with` / `guard_entry`），一条用例都不 `#[ignore]`、 +//! 一条断言都没删。**GiB 级的数值判定**（>2 GiB 与 >4 GiB）搬到了 `format/write/tests.rs`： +//! 那两道闸吃的是 `u64`，本来就不需要落盘。 +//! +//! # 「声明长度」必须自己造出来（M170） +//! +//! M166 的 `the_gate_runs_before_any_content_is_opened` 把源做成目录、量 `metadata().len()`， +//! 量到 0 就 `return`。而**本机 NTFS 上空目录的长度就是 0**（实测：空目录 0；条目塞进去之后 +//! 才变成 4–16 KiB 量级，见 [`DIR_LENGTH_FILLERS`] 的注释；ext4 空目录直接报 4096）——所以 +//! 那条"行为证明"在 Windows 上一条断言都没执行，只有 CI 的 ubuntu 那侧真跑。现在改成：先把 +//! 目录填到长度**大于清单 JSON 自身**，拿**这个长度减一字节**当总量上限，并且前提不满足时 +//! `assert!` 而不是 `return`——要么真判过东西，要么在这台机器上红。 + +use std::io::Read; +use std::path::Path; + +use super::write_file; +use super::TempRoot; +use crate::addon::pack::curseforge::CURSEFORGE; +use crate::addon::pack::error::PackErrorKind; +use crate::addon::pack::format::{write_with_limits, PackFormat, PackPayload, WriteLimits}; +use crate::addon::pack::manifest::{OverrideFile, PackManifest, PackOverrides, PackSide}; + +/// 小 limits：生产口径是 512 MiB 总量 / 64 MiB 单条 / 2 万条，这里缩到 KiB 级。 +/// +/// 判据只吃"声明尺寸 ≥ 上限"这个**关系**，所以缩小的只是夹具，不是分支。 +const SMALL_TOTAL: u64 = 8 * 1024; +const SMALL_ENTRY: u64 = 2 * 1024; +const SMALL_ENTRIES: usize = 16; + +/// 把目录填充到「`metadata().len()` 大到能当判据」用几个条目。 +/// +/// **这个数字不是阈值，是区间里挑的一个稳的点**：NTFS 的目录长度是索引分配的字节数，按 4 KiB +/// 一档往上加，**跟条目名的长度和条目数都有关**——本机实测（`std::fs::metadata`，同一台机器、 +/// 同一个 `%TEMP%`）： +/// +/// | 条目名 | 空 | 3 条 | 7 条 | 20 条 | 32 条 | 39 条 | 40 条 | +/// | --- | --- | --- | --- | --- | --- | --- | --- | +/// | `f0`…`f39`（短名） | 0 | 0 | 4096 | 4096 | 4096 | 4096 | 4096 | +/// | `filler-NN`（本用例的形状） | 0 | 4096 | 4096 | 8192 | **8192** | 12288 | 16384 | +/// +/// 所以"第几个条目起非零"没有平台无关的答案，别在注释里钉死一个漂亮的数字：这里只钉 +/// **32 个 `filler-NN` 条目**这个形状（本机 8192），其余文件系统（ext4 空目录 4096、tmpfs +/// 680 量级）由下面那条 `limit > 清单 JSON 长度` 的 `assert!` 现场把关——不满足就用例红。 +const DIR_LENGTH_FILLERS: usize = 32; + +/// 上面那三个数组成的限额（`WriteLimits::new` 是 `#[cfg(test)]` 的测试入口）。 +fn small_limits() -> WriteLimits { + WriteLimits::new(SMALL_TOTAL, SMALL_ENTRY, SMALL_ENTRIES) +} + +/// 一个覆盖文件的声明（内容由调用方提供）。 +fn override_file(path: &str) -> OverrideFile { + OverrideFile { + path: path.to_string(), + sha1: "0".repeat(40), + size: 0, + } +} + +fn manifest_of(files: Vec) -> PackManifest { + 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 { + dir: "overrides".to_string(), + side: PackSide::Both, + files, + }); + manifest +} + +/// 造一个真有 `length` 字节内容的覆盖文件（**不稀疏**，见模块文档）。 +fn content_file(path: &Path, length: u64) { + write_file( + path, + &vec![0_u8; usize::try_from(length).expect("夹具尺寸")], + ); +} + +/// 临时目录里除 `keep` 之外的文件名（断言"没留下 .part"用）。 +fn leftovers(root: &Path, keep: &[&str]) -> Vec { + let mut names: Vec = std::fs::read_dir(root) + .expect("列目录") + .filter_map(Result::ok) + .map(|entry| entry.file_name().to_string_lossy().to_string()) + .filter(|name| !keep.contains(&name.as_str())) + .collect(); + names.sort(); + names +} + +#[test] +fn one_file_over_the_threshold_is_refused_before_a_single_byte_is_read() { + let root = TempRoot::new("zip64-single"); + // 单条就等于总量上限：预检在 `guard_with` 上拒，**不许读内容**。 + // （旧版这里是 `ZIP64_BYTES_THR + 1` 的 4 GiB 夹具，见模块文档。） + content_file(&root.join("overrides/mods/huge.jar"), SMALL_TOTAL); + let manifest = manifest_of(vec![override_file("mods/huge.jar")]); + let target = root.join("out.zip"); + + let error = write_with_limits( + &CURSEFORGE, + &manifest, + PackPayload::from_root(&root), + &target, + small_limits(), + ) + .expect_err("超统一上限必须拒写"); + + assert_eq!(error.kind(), PackErrorKind::Limits, "{error}"); + // 文案要点名「我们永远不会写 ZIP64」这件事，而不是拿 ZIP64 阈值当判据。 + assert!(error.message().contains("ZIP64"), "{error}"); + // 报出来的必须是**在用的**那个上限（生产路径上它就是 PACK_MAX_UNCOMPRESSED_BYTES， + // 接线由 `format/write/tests.rs` 的 `the_production_limits_are_the_shared_constants` 钉）。 + assert!( + error.message().contains(&SMALL_TOTAL.to_string()), + "要报出在用的总量上限：{error}" + ); + assert!( + error.hint().is_some_and(|hint| hint.contains("移出实例")), + "要给「把大文件移出实例」这种可执行的提示：{error:?}" + ); + assert!(!target.exists(), "失败后目标路径不许存在"); + // 临时文件也不许留。**但这条不是"一个字节都没读"的证明**（M170 更正）：失败分支自己会 + // `remove_file(&temp)`，所以它在任何失败路径上都成立，等于"确实返回了 Err"的同义反复。 + // 上面的 `kind()` 也**不区分闸的位置**：这条用例的源是**可读的** 8 KiB 真文件，闸被挪到 + // `File::open` 之后时，写循环的第二道闸 `Written::spend`（`write.rs` 每块之后 + // `guard_with`）照样返回 `Limits`——所以本用例在"闸挪位置"的变异下仍然绿（复审 r1 实测， + // 我自己的变异 A 表里"其余 4 条仍绿"就是同一件事）。**顺序只由 + // `the_gate_runs_before_any_content_is_opened` 用"读不出来的源"证明**（含常驻反证）。 + assert_eq!(leftovers(&root, &["overrides"]), Vec::::new()); +} + +#[test] +fn the_threshold_is_cumulative_not_per_file() { + // 四条各自都**没有**越过单条目上限，加起来越过了总量上限：判据是**整包未压缩总量**。 + let root = TempRoot::new("zip64-cumulative"); + let each = SMALL_ENTRY; + assert!(each * 4 >= SMALL_TOTAL, "四条加起来必须真的越过总量上限"); + let mut files = Vec::new(); + for index in 0..4 { + let relative = format!("mods/part-{index}.jar"); + content_file(&root.join("overrides").join(&relative), each); + files.push(override_file(&relative)); + } + + let target = root.join("out.zip"); + let error = write_with_limits( + &CURSEFORGE, + &manifest_of(files), + PackPayload::from_root(&root), + &target, + small_limits(), + ) + .expect_err("累计超上限同样必须拒写"); + + assert_eq!(error.kind(), PackErrorKind::Limits, "{error}"); + assert!(error.message().contains("ZIP64"), "{error}"); + assert!(!target.exists()); + assert_eq!(leftovers(&root, &["overrides"]), Vec::::new()); +} + +#[test] +fn a_single_entry_over_the_entry_limit_is_refused_before_a_single_byte_is_read() { + // **单条目**那道闸（`guard_entry`）：总量还远在上限之下，只有一条越界。 + // 这条顶替了旧版 `#[ignore]` 的「2.5 GB 单文件落在 ZIP64 过拒窗口」端到端用例—— + // M160 之后那个窗口按设计不再存在，留下的是"单条越界就拒、且拒在读内容之前"。 + // 2.5 GB 那个**数值**的判定搬到 `format/write/tests.rs`（那里不需要落盘）。 + let root = TempRoot::new("zip64-entry"); + content_file(&root.join("overrides/mods/big.jar"), SMALL_ENTRY + 1); + let manifest = manifest_of(vec![override_file("mods/big.jar")]); + let target = root.join("out.zip"); + + let error = write_with_limits( + &CURSEFORGE, + &manifest, + PackPayload::from_root(&root), + &target, + small_limits(), + ) + .expect_err("超过单条目上限必须拒"); + + assert_eq!(error.kind(), PackErrorKind::Limits, "{error}"); + assert!( + error.message().contains(&SMALL_ENTRY.to_string()), + "要报出在用的单条目上限：{error}" + ); + assert!(!target.exists(), "预检失败时目标路径不许出现"); + assert_eq!(leftovers(&root, &["overrides"]), Vec::::new()); +} + +#[test] +fn the_gate_runs_before_any_content_is_opened() { + // **行为**证明（复审 r1 的观察 2）：源做成**目录**——`metadata()` 拿得到长度，把它当内容 + // 读却读不出来（Windows NTFS：`File::open` 直接"拒绝访问"；Linux：`open` 成功但 `read` + // 报 EISDIR）。于是闸若被挪到"读内容"那一段，这里拿到的会是 `pack_io` 而不是 + // `pack_limits`——比只看"临时文件没被创建"硬，因为后者在任何失败路径上都成立。 + // + // 但"硬"的前提是**真有声明长度可判**：见下面的两块 `assert!`（M170）。 + let root = TempRoot::new("zip64-before-read"); + let directory = root.join("overrides/mods/not-a-file"); + std::fs::create_dir_all(&directory).expect("建目录"); + // 长度得**自己造**：NTFS 上空目录报 0（本机实测：空 0；塞条目之后按 4 KiB 一档 + // 往上跳，`filler-NN` 形状 3 条 → 4096、32 条 → 8192，详见 `DIR_LENGTH_FILLERS`）， + // 直接量空目录会得到 0 —— r2 版本就是在这里 `return` 的，于是 Windows 上一条断言都没跑。 + for index in 0..DIR_LENGTH_FILLERS { + write_file(&directory.join(format!("filler-{index:02}")), b"x"); + } + let declared = std::fs::metadata(&directory) + .expect("stat 目录（这一步必须成功，否则区分不了两道闸）") + .len(); + let manifest = manifest_of(vec![override_file("mods/not-a-file")]); + let json_len = CURSEFORGE + .render(&manifest) + .expect("渲染清单（只是为了量它多长）") + .len() as u64; + // 上限 = 声明长度减一字节（`guard_with` 是 `>=`，声明尺寸自己就越线）。用 + // `saturating_sub` 而不是 `-`：目录长度报 0 时要走到下一条 `assert!` 的清楚信息， + // 而不是一个整数下溢的 panic。 + let limit = declared.saturating_sub(1); + // 前提①（r1 复审建议的收紧）：上限必须**大于清单 JSON 自身长度**。`total` 是 + // `清单 + 声明尺寸`，若上限比清单还小，清单自己就能把 `total` 顶过线——用例照样绿， + // 却悄悄失去对「总量闸漏算了覆盖条目的声明尺寸」那类洞的判别力（复审的变异 E）。 + // 本用例这份 CurseForge 清单渲染出来实测 **220 字节**（复审用另一份清单量到约 165，差别 + // 来自清单字段）；ext4（4095）、tmpfs（679）、本机 NTFS（8191）都远在它之上。对 32 个 + // 条目报不到 220 字节的文件系统会让这条用例红——那是对的，它在那里证明不了声明尺寸承重 + // （把 `DIR_LENGTH_FILLERS` 临时改成 0 就能看到这句 assert 的话：`声明长度 0 − 1 = 0`）。 + assert!( + limit > json_len, + "前提：总量上限（目录声明长度 {declared} − 1 = {limit}）必须大于清单 JSON 自身长度\ + （{json_len}），否则拒写可能只是清单越线，声明尺寸没被证明承重（**不许静默 return**）" + ); + + // 前提②：这条源**确实**读不出来，否则 `pack_limits` / `pack_io` 区分不了闸的位置。 + // 走的就是写循环那一对调用（`File::open` → `read`），不满足照样 `assert!` 而不是跳过。 + let consumed = std::fs::File::open(&directory).and_then(|mut file| { + let mut byte = [0_u8; 1]; + file.read(&mut byte).map(|_| ()) + }); + assert!( + consumed.is_err(), + "前提：目录源必须读不出来，否则拿到 pack_limits 也说明不了闸在内容之前：{consumed:?}" + ); + + // 单条目上限给 `u64::MAX`：不让 `guard_entry` 当替身——如果总量闸漏算了覆盖条目的声明 + // 尺寸，这里就不会拿到 `pack_limits`，而是一路走到读内容上拿到 `pack_io`（用例变红）。 + let target = root.join("out.zip"); + + let error = write_with_limits( + &CURSEFORGE, + &manifest, + PackPayload::from_root(&root), + &target, + WriteLimits::new(limit, u64::MAX, SMALL_ENTRIES), + ) + .expect_err("声明尺寸超限必须拒"); + + assert_eq!( + error.kind(), + PackErrorKind::Limits, + "闸必须在打开内容**之前**：拿到 pack_io 说明它被挪到读之后了：{error}" + ); + assert!( + error.message().contains("总量") && error.message().contains(&limit.to_string()), + "拒写理由必须是**总量闸**、且报出在用的上限（{limit}）：{error}" + ); + assert!( + !error.message().contains("读覆盖文件"), + "文案是「读覆盖文件失败」的口径 ⇒ 闸已经在碰内容了：{error}" + ); + + // # 反证：同一个夹具，闸一放行就必定死在"读内容"上 + // + // 这一步是"上面那个 `kind` 断言不是同义反复"的证据：把限额放到远大于声明尺寸，同一个 + // 目录源会在 `File::open` / `read` 上炸成 `pack_io`。于是上面拿到 `pack_limits` 只有 + // 一种解释——闸在碰内容**之前**就拒了。（而 `!target.exists()` 与"目录里没 `.part`" + // 这两条：失败分支会 `remove_file(temp)`、只有成功分支才 `rename`，所以它们在任何失败 + // 路径上都成立，属于**结构侧检**、不是判据。r2 曾把后者当成"一个字节都没读"的证明， + // 那才是同义反复。） + let error = write_with_limits( + &CURSEFORGE, + &manifest_of(vec![override_file("mods/not-a-file")]), + PackPayload::from_root(&root), + &root.join("out-loose.zip"), + WriteLimits::new(u64::MAX, u64::MAX, SMALL_ENTRIES), + ) + .expect_err("目录源读不出来：闸放行就只能死在读内容上"); + assert_eq!( + error.kind(), + PackErrorKind::Io, + "反证不成立：闸放行后没有死在读内容上，那上面那个 kind 断言就区分不了闸的位置：{error}" + ); + assert!(error.message().contains("读覆盖文件"), "{error}"); + + // 结构侧检（**不是判据**）：两次调用到这里都没留下 `out.zip` / `out-loose.zip` / `.part`。 + // 这两条在任何失败路径上都成立（失败分支自己 `remove_file(temp)`，只有成功分支才 + // `rename`），所以它们只值"确实返回了 Err"的同义反复——上面那条反证把真正有牙的判据 + // （`kind()` + 文案）与它们区分开。 + assert!(!target.exists(), "预检失败时目标路径不许出现"); + assert_eq!(leftovers(&root, &["overrides"]), Vec::::new()); +} + +#[test] +fn an_export_under_the_threshold_still_writes_a_normal_pack() { + // 对照：不超阈值时预检不许误伤（否则这条护栏就变成"导出全挂"）。 + // 走**生产口径**（`CURSEFORGE.write` → `WriteLimits::production()`）：小 limits 那几条 + // 证明的是分支，这条证明的是生产接线不会把正常包拒掉。 + let root = TempRoot::new("zip64-under"); + let content = b"a normal sized override file"; + write_file(&root.join("overrides/mods/jei.jar"), content); + let manifest = manifest_of(vec![override_file("mods/jei.jar")]); + let target = root.join("out.zip"); + + CURSEFORGE + .write(&manifest, PackPayload::from_root(&root), &target) + .expect("正常尺寸必须写得出来"); + assert!(target.exists()); + let written = crate::addon::pack::PackArchive::open_default(&target).expect("打开导出的包"); + assert!(written.has_entry("overrides/mods/jei.jar")); +} diff --git a/crates/core/src/addon/temp.rs b/crates/core/src/addon/temp.rs new file mode 100644 index 0000000..544b900 --- /dev/null +++ b/crates/core/src/addon/temp.rs @@ -0,0 +1,108 @@ +//! 测试用的**一次性临时根**（`Drop` 即删；panic 展开时同样删）。 +//! +//! # 为什么它必须在 `addon` 里而不是某个测试目录里 +//! +//! `addon::pack` 与 `addon::tests` 两族用例都建临时目录，而 `pack/tests/fixtures.rs` 被**两边 +//! 同时**通过 `#[path]` 编译（同一份手造包只维护一处）。守卫因此要放在两边的公共祖先上，否则 +//! `fixtures.rs` 里的 `super::TempRoot` 在其中一侧解析不到。 +//! +//! # 为什么不能靠"系统会清 `%TEMP%`" +//! +//! 那种清理要等时间或外部工具，而 `zip64` 那族用例历史上每个要造 4 GiB 的"稀疏"文件验阈值 +//! （**实测在 NTFS 上 `set_len` 真占空间**，见 `pack/tests/zip64.rs` 的模块文档）： +//! M160 r2 实测 `%TEMP%/ull-pack-*` 堆到 **1651 个目录 / 110 GB**，把整台机器（含别的 agent +//! 的构建）一起顶死。所以测试自己负责收尾，并且有自证用例 +//! （`pack/tests/mod.rs` 的 `the_temp_root_is_gone_once_dropped` / +//! `a_panicking_test_still_removes_its_temp_root`）。 +//! +//! # 形状来自仓库既有写法 +//! +//! 与 [`crate::update::tests::support::TempDir`] 同一套 `new` / `join` / `Drop` 三件套 +//! （不引 `tempfile`、不新增范式），只多了两件事：`Deref` 让调用点能直接当 +//! `&Path` 用；[`TempRoot::under`] 让"子树落点、删父目录"这件事不留下空壳。 + +use std::ops::Deref; +use std::path::{Path, PathBuf}; +use std::sync::atomic::{AtomicU64, Ordering}; + +/// 一次性临时根目录（**`Drop` 即删**）。 +pub(crate) struct TempRoot { + /// 真正要删的根（[`Self::under`] 造的子树也删它，不留空壳父目录）。 + root: PathBuf, + /// 本夹具的落点（通常等于 `root`；`under` 时是 `root/`）。 + path: PathBuf, +} + +impl TempRoot { + /// 建一个新的临时根（同名残留先清掉：`COUNTER` 在同一进程内唯一，跨进程靠 pid）。 + pub(crate) fn new(tag: &str) -> Self { + static COUNTER: AtomicU64 = AtomicU64::new(0); + let unique = COUNTER.fetch_add(1, Ordering::Relaxed); + let root = + std::env::temp_dir().join(format!("ull-pack-{}-{tag}-{unique}", std::process::id())); + let _ = std::fs::remove_dir_all(&root); + std::fs::create_dir_all(&root).expect("建临时根"); + Self { + path: root.clone(), + root, + } + } + + /// 在临时根下开一个子目录当落点（`Drop` 删的是**根**，父目录不会剩空壳）。 + pub(crate) fn under(tag: &str, sub: &str) -> Self { + let base = Self::new(tag); + let path = base.path.join(sub); + std::fs::create_dir_all(&path).expect("建临时子目录"); + Self { + root: base.root.clone(), + path, + } + } + + /// 建一个临时根，并让落点直接是根内的某个文件（`Drop` 删的仍是**根**）。 + /// + /// 给"夹具函数要返回一个包路径、而包路径必须活到测试用完"的场景用：返回值 `Deref` 到那个 + /// 文件，根由它持有。`root.parent()` 拿得到根目录。 + pub(crate) fn at(tag: &str, file: &str) -> Self { + let mut base = Self::new(tag); + base.path = base.path.join(file); + base + } + + /// 本夹具的落点。 + pub(crate) fn path(&self) -> &Path { + &self.path + } + + /// 落点下的一条路径（`&str` 与 `Path` 都收，免得把调用点写成两套）。 + pub(crate) fn join(&self, name: impl AsRef) -> PathBuf { + self.path.join(name) + } +} + +impl Deref for TempRoot { + type Target = Path; + + fn deref(&self) -> &Path { + &self.path + } +} + +impl AsRef for TempRoot { + /// 让 `&TempRoot` 能直接喂给 `impl AsRef` 形态的 API（`fs::read_dir` / `remove_dir_all` + /// / `PackArchive::open_default` …）。`Deref` 只解决"要 `&Path`"的场景，两者都要。 + fn as_ref(&self) -> &Path { + &self.path + } +} + +impl Drop for TempRoot { + fn drop(&mut self) { + // 尽力删：删不掉留一行日志，别在析构里 panic（二次 panic 会 abort）。 + if let Err(error) = std::fs::remove_dir_all(&self.root) { + if error.kind() != std::io::ErrorKind::NotFound { + eprintln!("[temp] 删 {} 失败：{error}", self.root.display()); + } + } + } +} diff --git a/crates/core/src/addon/tests/decisions_support.rs b/crates/core/src/addon/tests/decisions_support.rs new file mode 100644 index 0000000..249a1de --- /dev/null +++ b/crates/core/src/addon/tests/decisions_support.rs @@ -0,0 +1,69 @@ +//! `import_decisions` 的夹具与断言小工具：**从 `import_decisions.rs` 拆出来守 400 行硬线**。 +//! +//! 拆分口径与仓库其它拆分一致：**纯搬移**，内容一行不改。这些夹具本身也是"口径"的一部分—— +//! 叠层（`client-overrides/` 胜 `overrides/`）、目标里已存在的用户内容、以及"内容与包内一致" +//! 的那一份，都是冲突判定的边界样本。 + +use super::support::{sha1, StubFetcher}; +use super::{write_file, zip_dir, TempRoot}; +use crate::addon::import::ImportScan; + +/// 夹具里 `client-overrides/` 胜出的那份内容（`overrides/` 里同名文件是不同的内容）。 +pub(super) const KNOWN_CLIENT: &[u8] = b"shared = client\n"; +/// 夹具里被遮蔽的那份（`overrides/` 侧）。 +pub(super) const KNOWN_OVERRIDES: &[u8] = b"shared = overrides\n"; +/// 与目标内容**一致**的那个文件。 +pub(super) const SAME: &[u8] = b"same = 1\n"; +/// 只有 overrides 声明、目标里还有一个不同内容的同名文件。 +pub(super) const LAYER: &[u8] = b"layer from overrides\n"; +/// 目标里用户自己的内容（会被覆盖 / 被保留的那一侧）。 +pub(super) const USER_KNOWN: &[u8] = b"shared = mine\n"; +/// 目标里用户自己的 layer 内容。 +pub(super) const USER_LAYER: &[u8] = b"my layer\n"; + +/// 一份带 **overrides 叠层** 的 mrpack（`client-overrides/` 与 `overrides/` 同名不同内容）+ 一条远端条目。 +pub(super) fn layered_pack(tag: &str) -> (TempRoot, StubFetcher) { + // 返回值 `Deref` 到 `pack.mrpack`，根由它持有（`src/` 在 `root.parent()` 下）。 + let root = TempRoot::at(tag, "pack.mrpack"); + let dir = root.parent().expect("临时根").join("src"); + let remote = b"remote jar bytes"; + let index = format!( + r#"{{"game":"minecraft","formatVersion":1,"versionId":"1.0.0","name":"M160 夹具", + "files":[{{"path":"mods/remote.jar", + "hashes":{{"sha1":"{}","sha512":"{}"}}, + "downloads":["stub://mods/remote.jar"],"fileSize":{}}}], + "dependencies":{{"minecraft":"1.20.1"}}}}"#, + sha1(remote), + "0".repeat(128), + remote.len() + ); + write_file(&dir.join("modrinth.index.json"), index.as_bytes()); + // 叠层：同一路径两份声明，client-overrides 胜（Modrinth 官方语义）。 + write_file(&dir.join("overrides/config/known.toml"), KNOWN_OVERRIDES); + write_file( + &dir.join("client-overrides/config/known.toml"), + KNOWN_CLIENT, + ); + // 内容与目标一致的那个（不在叠层里，来源 = overrides）。 + write_file(&dir.join("overrides/config/same.toml"), SAME); + write_file(&dir.join("overrides/mods/layer.jar"), LAYER); + zip_dir(&dir, &root); + let fetcher = StubFetcher::new().with_file("stub://mods/remote.jar", remote); + (root, fetcher) +} + +/// 预置一个"用户已有文件"的实例目录。 +pub(super) fn seeded(tag: &str) -> TempRoot { + let target = TempRoot::under(tag, "instance"); + write_file(&target.join("config/known.toml"), USER_KNOWN); + write_file(&target.join("config/same.toml"), SAME); + write_file(&target.join("mods/layer.jar"), USER_LAYER); + target +} + +pub(super) fn paths(scan: &ImportScan) -> Vec<&str> { + scan.conflicts + .iter() + .map(|conflict| conflict.path.as_str()) + .collect() +} 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..470427f --- /dev/null +++ b/crates/core/src/addon/tests/import_curseforge.rs @@ -0,0 +1,137 @@ +//! 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, TempRoot}; + +/// 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 root = TempRoot::new("cf-e2e-out"); + let target = root.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 root = TempRoot::new("cf-offline-out"); + let target = root.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 root = TempRoot::new("cf-nourl-out"); + let target = root.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_decisions.rs b/crates/core/src/addon/tests/import_decisions.rs new file mode 100644 index 0000000..4b913ae --- /dev/null +++ b/crates/core/src/addon/tests/import_decisions.rs @@ -0,0 +1,354 @@ +//! 逐文件冲突决策（M160）：预检列清单 → 用户点头 → 导入按决策处置。 +//! +//! # 一张表看完全部用例 +//! +//! | 用例 | 钉住的口径 | +//! |------|------------| +//! | [`scan_lists_only_files_that_exist_and_differ`] | 进清单的条件：**已存在且内容不同**；来源记胜者侧 | +//! | [`scan_is_silent_about_identical_and_missing_files`] | 内容相同 / 目标不存在 ⇒ 一行都不列 | +//! | [`scan_does_not_ask_about_files_the_user_deleted`] | 用户删过的不算"已存在且内容不同" | +//! | [`no_decision_means_keep_and_nothing_is_overwritten`] | **缺省保留**（报告的 choice 与磁盘内容双证） | +//! | [`per_item_overwrite_touches_only_the_named_path`] | 逐项决策：只动点名那条，最终文件集逐字节断言 | +//! | [`overwrite_all_is_the_batch_channel_from_the_same_table`] | 整批档来自同一张表（`ImportScan::overwrite_all`） | +//! | [`a_kept_file_is_still_a_conflict_next_time`] | 基线记的是**包内**哈希，所以保留过一次的文件不会被静默覆盖 | +//! | [`curseforge_entries_without_a_path_are_counted_not_guessed`] | 补全前没有路径 ⇒ 不猜，只计数 | +//! +//! 全部离线：远端走 [`support::StubFetcher`]，没有一条网络请求。 + +use super::decisions_support::{ + layered_pack, paths, seeded, KNOWN_CLIENT, SAME, USER_KNOWN, USER_LAYER, +}; +use super::support::{mrpack_stub, sha1}; +use super::{read_text, write_file, zip_dir, TempRoot}; +use crate::addon::import::{ + import_pack, scan_pack, ConflictChoice, ConflictDecisions, ConflictReason, FileAction, + FileSource, ImportRequest, ImportStatus, +}; +use crate::download::blocking::block_on; + +#[test] +fn scan_lists_only_files_that_exist_and_differ() { + let (pack, _) = layered_pack("dec-scan"); + let target = seeded("dec-scan"); + let scan = scan_pack(&ImportRequest::new(&pack, &target)); + + assert!(scan.is_ok(), "预检不许失败：{:?}", scan.error); + assert_eq!( + paths(&scan), + vec!["config/known.toml", "mods/layer.jar"], + "只列「已存在且内容不同」的两条（same.toml 与 remote.jar 不该出现）" + ); + let known = &scan.conflicts[0]; + assert_eq!( + known.source, + FileSource::ClientOverrides, + "叠层的胜者是 client-overrides 侧，来源要记它" + ); + assert_eq!(known.reason, ConflictReason::PreExisting); + assert_eq!(known.pack_sha1, sha1(KNOWN_CLIENT)); + assert_eq!(known.pack_size, KNOWN_CLIENT.len() as u64); + assert_eq!(known.disk_sha1, sha1(USER_KNOWN)); + assert_eq!( + known.disk_size, + USER_KNOWN.len() as u64, + "要给出目标现有体积" + ); + assert_eq!(known.base_sha1, None, "首次导入没有基线"); + assert_eq!( + scan.lost_bytes(), + (USER_KNOWN.len() + USER_LAYER.len()) as u64 + ); + assert!( + scan.needs_decision(), + "有冲突就必须让用户点头，不能自己决定" + ); +} + +#[test] +fn scan_is_silent_about_identical_and_missing_files() { + let (pack, _) = layered_pack("dec-same"); + let root = TempRoot::new("dec-same"); + let target = root.join("instance"); + // 只放一个**内容与包内一致**的文件：一行都不该列出来。 + write_file(&target.join("config/same.toml"), SAME); + let scan = scan_pack(&ImportRequest::new(&pack, &target)); + + assert!(scan.is_ok(), "{:?}", scan.error); + assert!( + paths(&scan).is_empty(), + "内容一致不算冲突：{:?}", + paths(&scan) + ); + assert!(!scan.needs_decision(), "没有冲突就不该打扰用户"); + assert_eq!(scan.unknown_remote, 0, "mrpack 条目自带路径，判得了"); +} + +#[test] +fn scan_does_not_ask_about_files_the_user_deleted() { + let (pack, fetcher) = layered_pack("dec-deleted"); + let target = seeded("dec-deleted"); + // 先完整导入一次（有基线了），再删掉其中两个文件。 + let first = block_on(import_pack( + &ImportRequest::new(&pack, &target) + .with_fetcher(&fetcher) + .with_decisions(ConflictDecisions::overwrite_all()), + )); + assert_eq!(first.status, ImportStatus::Success, "{:?}", first.error); + std::fs::remove_file(target.join("config/known.toml")).expect("删文件"); + std::fs::remove_file(target.join("mods/remote.jar")).expect("删文件"); + + let scan = scan_pack(&ImportRequest::new(&pack, &target)); + assert!( + paths(&scan).is_empty(), + "用户删过的文件不是「已存在且内容不同」，不该问：{:?}", + paths(&scan) + ); + + // 导入同样不把它们装回来（原有的 `UserDeleted` 判据仍然生效）。 + let second = block_on(import_pack( + &ImportRequest::new(&pack, &target).with_fetcher(&fetcher), + )); + assert_eq!(second.status, ImportStatus::Partial); + assert!(!target.join("config/known.toml").exists(), "不许偷偷装回来"); + assert!( + second.conflicts.iter().any(|conflict| { + conflict.path == "config/known.toml" && conflict.reason == ConflictReason::UserDeleted + }), + "但仍要按事记账：{:?}", + second.conflicts + ); +} + +#[test] +fn no_decision_means_keep_and_nothing_is_overwritten() { + let (pack, fetcher) = layered_pack("dec-keep"); + let target = seeded("dec-keep"); + let report = block_on(import_pack( + &ImportRequest::new(&pack, &target).with_fetcher(&fetcher), + )); + + // 磁盘内容逐字节没变（**这是"缺省不覆盖"的直接证据**）。 + assert_eq!( + read_text(&target.join("config/known.toml")), + "shared = mine\n" + ); + assert_eq!(read_text(&target.join("mods/layer.jar")), "my layer\n"); + // 报告里这两条都记成 KeptUser + KeepUser。 + for path in ["config/known.toml", "mods/layer.jar"] { + let conflict = report + .conflicts + .iter() + .find(|conflict| conflict.path == path) + .unwrap_or_else(|| panic!("{path} 要进冲突清单：{:?}", report.conflicts)); + assert_eq!( + conflict.choice, + crate::addon::import::ConflictChoice::KeepUser + ); + let file = report + .files + .iter() + .find(|file| file.path == path) + .expect("逐文件结果里也要有它"); + assert_eq!(file.action, FileAction::KeptUser); + } + // 不冲突的那些照常落地（「保留」不会把整次导入变成什么都不做）。 + assert_eq!( + read_text(&target.join("mods/remote.jar")), + "remote jar bytes" + ); +} + +#[test] +fn per_item_overwrite_touches_only_the_named_path() { + let (pack, fetcher) = layered_pack("dec-item"); + let target = seeded("dec-item"); + let scan = scan_pack(&ImportRequest::new(&pack, &target)); + assert_eq!(paths(&scan), vec!["config/known.toml", "mods/layer.jar"]); + + // 只对 `config/known.toml` 说"覆盖"，另一条不给决策。 + let decisions = + ConflictDecisions::keep_all().with("config/known.toml", ConflictChoice::Overwrite); + let report = block_on(import_pack( + &ImportRequest::new(&pack, &target) + .with_fetcher(&fetcher) + .with_decisions(decisions), + )); + + // 最终文件集：点名那条被覆盖，没点名那条原样保留。 + assert_eq!( + read_text(&target.join("config/known.toml")), + "shared = client\n" + ); + assert_eq!(read_text(&target.join("mods/layer.jar")), "my layer\n"); + assert_eq!(read_text(&target.join("config/same.toml")), "same = 1\n"); + assert_eq!( + read_text(&target.join("mods/remote.jar")), + "remote jar bytes" + ); + // 有一条冲突按「保留」处置 ⇒ `Partial`（**不是** `Success`：实例可用，但内容与包不全一致）。 + assert_eq!(report.status, ImportStatus::Partial, "{:?}", report.error); + let mut chosen: Vec<(&str, ConflictChoice)> = report + .conflicts + .iter() + .map(|conflict| (conflict.path.as_str(), conflict.choice)) + .collect(); + // 报告里的顺序是落盘顺序（overrides 组在前、client-overrides 在后），比较前按路径排序。 + chosen.sort_by(|left, right| left.0.cmp(right.0)); + assert_eq!( + chosen, + vec![ + ("config/known.toml", ConflictChoice::Overwrite), + ("mods/layer.jar", ConflictChoice::KeepUser), + ] + ); +} + +#[test] +fn overwrite_all_is_the_batch_channel_from_the_same_table() { + let (pack, fetcher) = layered_pack("dec-all"); + let target = seeded("dec-all"); + let scan = scan_pack(&ImportRequest::new(&pack, &target)); + let report = block_on(import_pack( + &ImportRequest::new(&pack, &target) + .with_fetcher(&fetcher) + .with_decisions(scan.overwrite_all()), + )); + + assert_eq!( + read_text(&target.join("config/known.toml")), + "shared = client\n" + ); + assert_eq!( + read_text(&target.join("mods/layer.jar")), + "layer from overrides\n" + ); + assert_eq!(report.status, ImportStatus::Success, "{:?}", report.error); + assert!(report + .conflicts + .iter() + .all(|conflict| conflict.choice == ConflictChoice::Overwrite)); +} + +#[test] +fn a_kept_file_is_still_a_conflict_next_time() { + // 基线里必须记**包内**的哈希：若记的是磁盘哈希，下一次导入会判成"用户没动过 ⇒ 整合包升级" + // 而静默覆盖——那正是本轮要禁的行为。 + let (pack, fetcher) = layered_pack("dec-baseline"); + let target = seeded("dec-baseline"); + for _ in 0..2 { + let report = block_on(import_pack( + &ImportRequest::new(&pack, &target).with_fetcher(&fetcher), + )); + let conflict = report + .conflicts + .iter() + .find(|conflict| conflict.path == "config/known.toml") + .expect("第二次也必须报冲突"); + assert_eq!(conflict.choice, ConflictChoice::KeepUser); + assert_eq!( + read_text(&target.join("config/known.toml")), + "shared = mine\n" + ); + } + // 第二次的成因变成"用户改过"（有基线了），而不是"没有基线"。 + let scan = scan_pack(&ImportRequest::new(&pack, &target)); + let known = &scan.conflicts[0]; + assert_eq!(known.reason, ConflictReason::UserModified); + assert_eq!( + known.base_sha1.as_deref(), + Some(sha1(KNOWN_CLIENT).as_str()) + ); +} + +#[test] +fn curseforge_entries_without_a_path_are_counted_not_guessed() { + // CF 的 `files[]` 只有 projectID/fileID：补全前没有路径 ⇒ 预检判不了，只记条数。 + let fixture = super::fixtures::curseforge("dec-cf"); + let root = TempRoot::new("dec-cf"); + let target = root.join("instance"); + let scan = scan_pack(&ImportRequest::new(&fixture.zip, &target)); + + assert!(scan.is_ok(), "{:?}", scan.error); + assert_eq!(scan.unknown_remote, 2, "两条 CF 远端条目都判不了"); + assert!( + scan.notes + .iter() + .any(|note| note.message_key == crate::addon::import::keys::NOTE_REMOTE_PATH_UNKNOWN), + "要如实说「还有 N 条判不了」：{:?}", + scan.notes + ); + // overrides 里的三条（example.jar / known.toml / broken.toml）在空目标上不冲突。 + assert!(paths(&scan).is_empty(), "{:?}", paths(&scan)); +} + +#[test] +fn a_remote_entry_with_a_path_but_no_sha1_is_counted_as_unjudgeable() { + // 复审 r1 P3-4：`unknown_remote` 的**计数口径**与注记文案要同一件事。 + // 这一条只放 `hashes` 里的 sha512、**不写 sha1**：有路径但没有声明摘要 ⇒ 预检没法比对磁盘， + // 也就不该假装它"没冲突"，而是要计入 unknown_remote 并如实注记。 + let root = TempRoot::new("dec-no-sha1"); + let dir = root.join("src"); + let index = format!( + r#"{{"game":"minecraft","formatVersion":1,"versionId":"1.0.0","name":"缺 sha1", + "files":[{{"path":"mods/no-sha1.jar", + "hashes":{{"sha512":"{}"}}, + "downloads":["stub://mods/no-sha1.jar"],"fileSize":16}}], + "dependencies":{{"minecraft":"1.20.1"}}}}"#, + "0".repeat(128) + ); + write_file(&dir.join("modrinth.index.json"), index.as_bytes()); + let pack = root.join("pack.mrpack"); + zip_dir(&dir, &pack); + let target = root.join("instance"); + + let scan = scan_pack(&ImportRequest::new(&pack, &target)); + assert!(scan.is_ok(), "{:?}", scan.error); + assert_eq!(scan.unknown_remote, 1, "有路径但缺 sha1 ⇒ 判不了，要计数"); + let note = scan + .notes + .iter() + .find(|note| note.message_key == crate::addon::import::keys::NOTE_REMOTE_PATH_UNKNOWN) + .expect("要如实注记"); + assert!( + note.message.contains("sha1"), + "文案要把「缺 sha1 声明」这条来路说清楚（计数口径与文案一致）：{}", + note.message + ); +} + +#[test] +fn a_broken_pack_reports_the_error_instead_of_panicking() { + let root = TempRoot::new("dec-broken"); + let bad = root.join("bad.zip"); + write_file(&bad, b"not a zip at all"); + let scan = scan_pack(&ImportRequest::new(&bad, &root.join("instance"))); + assert!(!scan.is_ok(), "坏包必须给 error"); + assert!(scan.conflicts.is_empty()); + assert!(!scan.needs_decision(), "判不了就没有可决策的项"); +} + +#[test] +fn the_scan_does_not_touch_the_target_directory() { + // 预检是只读的：连目标目录都不该建出来。 + let (pack, _) = layered_pack("dec-readonly"); + let root = TempRoot::new("dec-readonly"); + let target = root.join("instance"); + let scan = scan_pack(&ImportRequest::new(&pack, &target)); + assert!(scan.is_ok(), "{:?}", scan.error); + assert!(!target.exists(), "预检不许创建目标目录"); +} + +#[test] +fn mrpack_stub_keeps_its_remote_entries_out_of_the_conflict_list() { + // 对照夹具（M111 的 mrpack_stub）：远端条目自带真实摘要，目标里没有 ⇒ 一条冲突都没有。 + let (fixture, fetcher) = mrpack_stub("dec-stub"); + let root = TempRoot::new("dec-stub"); + let target = root.join("instance"); + let scan = scan_pack(&ImportRequest::new(&fixture.zip, &target)); + assert!(scan.is_ok(), "{:?}", scan.error); + assert!(scan.conflicts.is_empty(), "{:?}", paths(&scan)); + let report = block_on(import_pack( + &ImportRequest::new(&fixture.zip, &target).with_fetcher(&fetcher), + )); + assert_eq!(report.status, ImportStatus::Success, "{:?}", report.error); +} 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..cbe73fb --- /dev/null +++ b/crates/core/src/addon/tests/import_failures.rs @@ -0,0 +1,256 @@ +//! **必须先失败**的样本：四条恶意/坏包 + 两条"证明双检真的在导入链上跑"的用例。 +//! +//! # 复审要的那张表 +//! +//! | 样本 | 期望结果 | 断言在哪 | +//! |------|----------|----------| +//! | 路径穿越条目（`../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, write_file, write_zip, write_zip_with_symlink, TempRoot, +}; + +/// 一份形状合法的最小 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}"); + } + } +} + +/// 恶意样本包 + 目标目录。返回的 `TempRoot` **`Deref` 到那个 zip**，同时持有临时根： +/// 用它喂 `ImportRequest::new(&pack, ..)` 之后包文件还在（不带守卫的话函数一返回包就被删了， +/// 导入会以 `pack_io` 失败——那是"测错了东西还看不出来"的典型）。 +fn failing(tag: &str, entries: &[(&str, &[u8])]) -> (TempRoot, std::path::PathBuf) { + let pack = TempRoot::at(tag, "evil.zip"); + write_zip(&pack, entries); + let target = pack.parent().expect("临时根").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 = TempRoot::new("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 = TempRoot::new("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() { + // 让合并态的**提交阶段**在中途失败：目标文件要被替换时必须先备份成 + // `.ullbak-`，而那个位置已被一个**非空目录**占住 ⇒ `rename(dest → backup)` + // 必然失败（文件改不成非空目录，Windows / Unix 一致）。 + // 这覆盖 journal 回滚 + `Drop` 兜底：前半截已经搬进去的文件（基线排最前）必须被撤回。 + let root = TempRoot::new("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_layering.rs b/crates/core/src/addon/tests/import_layering.rs new file mode 100644 index 0000000..f7833fc --- /dev/null +++ b/crates/core/src/addon/tests/import_layering.rs @@ -0,0 +1,211 @@ +//! 逐文件冲突策略的**边界样本**（research/18 §3.3 / §6 表 B #1–#2 的那几条）。 +//! +//! 三条样本各自钉一个事实，缺一条就会复现不同的 bug： +//! +//! | 样本 | 必须成立的事实 | 写错的后果 | +//! |------|----------------|-----------| +//! | 同路径不同哈希 | 叠层顺序里**最后一条**胜；被遮蔽的那条不落地、只留一条具名注记 | 报告里两条 `Installed`，前一条的哈希根本没落地 | +//! | 同哈希不同路径 | **两个文件都落地**（按路径判重，不许按哈希判重） | 静默丢一个文件（内容一样不等于同一个文件） | +//! | overrides 叠层顺序 | `overrides/` 先、`client-overrides/` 后（= 后者胜，Modrinth 官方语义） | 与 HMCL 的相反语义混进来，同一包在不同启动器装出不同内容 | +//! +//! 判据的纯函数版本（`plan::layer::resolve`）在那边有单元测试；这里是**接在管线上的行为**： +//! 真打 zip、真导入、真读回磁盘内容与报告字段。 + +use std::sync::{Arc, Mutex}; + +use crate::addon::import::{ + import_pack, keys, ConflictReason, FileAction, ImportProgress, ImportRequest, ImportStage, + ImportStatus, +}; +use crate::download::blocking::block_on; + +use super::support::sha1; +use super::{read_text, write_file, zip_dir, TempRoot}; + +/// 打一个只有 `files: []` 的 mrpack（覆盖内容全在 overrides 系列目录里）。 +fn index_json(name: &str) -> String { + format!( + r#"{{"game": "minecraft", "formatVersion": 1, "versionId": "1.0.0", + "name": "{name}", "files": [], "dependencies": {{"minecraft": "1.20.1"}}}}"# + ) +} + +/// 报告里所有 `NOTE_OVERRIDE_SHADOWED` 注记的消息。 +fn shadow_notes(report: &crate::addon::import::ImportReport) -> Vec<&str> { + report + .warnings + .iter() + .filter(|note| note.message_key == keys::NOTE_OVERRIDE_SHADOWED) + .map(|note| note.message.as_str()) + .collect() +} + +#[test] +fn same_path_with_different_bytes_lands_the_later_side_only() { + let root = TempRoot::new("layer-same-path"); + let dir = root.join("src"); + write_file( + &dir.join("modrinth.index.json"), + index_json("dup conflict").as_bytes(), + ); + 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", + ); + let pack = root.join("pack.mrpack"); + zip_dir(&dir, &pack); + let target = root.join("instance"); + + // Extract 阶段的总条数就是"要落地的条目数"：两点声明 ⇒ 只算 1 条（被遮蔽的不读字节）。 + let totals: Arc>> = Arc::new(Mutex::new(Vec::new())); + let sink = { + let totals = Arc::clone(&totals); + Arc::new(move |progress: &ImportProgress| { + if progress.stage == ImportStage::Extract { + totals.lock().expect("锁").push(progress.total); + } + }) + }; + let report = block_on(import_pack( + &ImportRequest::new(&pack, &target).with_progress(sink), + )); + + assert_eq!(report.status, ImportStatus::Success, "{:?}", report.error); + // Modrinth 官方语义：client-overrides/ 后写 = 胜。 + assert_eq!(read_text(&target.join("config/dup.toml")), "from-client\n"); + // 一路径一行，且那一行的哈希必须是**真落地**的那份内容。 + let rows: Vec<_> = report + .files + .iter() + .filter(|file| file.path == "config/dup.toml") + .collect(); + assert_eq!(rows.len(), 1, "同一路径只许一行：{:?}", report.files); + assert_eq!( + rows[0].sha1.as_deref(), + Some(sha1(b"from-client\n").as_str()) + ); + assert_eq!(rows[0].action, FileAction::Installed); + // 遮蔽要留下具名注记：谁赢了、两份内容不同。 + let notes = shadow_notes(&report); + assert_eq!(notes.len(), 1, "{:?}", report.warnings); + assert!(notes[0].contains("内容不同"), "{}", notes[0]); + assert!(notes[0].contains("client-overrides"), "{}", notes[0]); + assert!( + report.conflicts.is_empty(), + "包内重复声明不是用户冲突：{:?}", + report.conflicts + ); + // 被遮蔽的条目不再进 Extract 的总数（1 条真落地）。 + assert_eq!(totals.lock().expect("锁").last().copied(), Some(1)); +} + +#[test] +fn the_same_bytes_at_two_paths_are_two_files() { + let root = TempRoot::new("layer-same-bytes"); + let dir = root.join("src"); + write_file( + &dir.join("modrinth.index.json"), + index_json("same bytes").as_bytes(), + ); + let content = b"identical payload\n"; + write_file(&dir.join("overrides/mods/a.jar"), content); + write_file(&dir.join("overrides/mods/b.jar"), content); + 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); + for path in ["mods/a.jar", "mods/b.jar"] { + assert_eq!( + read_text(&target.join(path)), + "identical payload\n", + "{path}" + ); + } + let rows: Vec<_> = report + .files + .iter() + .filter(|file| file.path.ends_with(".jar")) + .collect(); + assert_eq!(rows.len(), 2, "同哈希不同路径不许折叠：{:?}", report.files); + assert!(rows + .iter() + .all(|row| row.sha1.as_deref() == Some(sha1(content).as_str()))); + assert!( + shadow_notes(&report).is_empty(), + "不同路径不是重复声明：{:?}", + report.warnings + ); +} + +#[test] +fn identical_bytes_on_both_sides_shadow_without_claiming_a_conflict() { + let root = TempRoot::new("layer-same-content"); + let dir = root.join("src"); + write_file( + &dir.join("modrinth.index.json"), + index_json("dup identical").as_bytes(), + ); + let content = b"shared = true\n"; + write_file(&dir.join("overrides/config/shared.toml"), content); + write_file(&dir.join("client-overrides/config/shared.toml"), content); + 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/shared.toml")), + "shared = true\n" + ); + let notes = shadow_notes(&report); + assert_eq!(notes.len(), 1, "{:?}", report.warnings); + assert!( + notes[0].contains("逐字节相同"), + "内容一致必须说清楚，别让人以为丢了东西：{}", + notes[0] + ); +} + +#[test] +fn the_baseline_remembers_the_winning_bytes() { + // 叠层顺序的**后果**：基线要记胜者那份。记错的话，下一次升级会把"用户没动过"判成 + // "用户改过"（或反过来静默覆盖用户改动）。 + let root = TempRoot::new("layer-baseline"); + let dir = root.join("src"); + write_file( + &dir.join("modrinth.index.json"), + index_json("baseline dup").as_bytes(), + ); + 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", + ); + let pack = root.join("pack.mrpack"); + zip_dir(&dir, &pack); + let target = root.join("instance"); + let first = block_on(import_pack(&ImportRequest::new(&pack, &target))); + assert_eq!(first.status, ImportStatus::Success, "{:?}", first.error); + + // 同一份包再导一次：磁盘内容 == 胜者内容 == 基线 ⇒ 既不该报冲突，也不该重写盘。 + let second = block_on(import_pack(&ImportRequest::new(&pack, &target))); + assert_eq!(second.status, ImportStatus::Success, "{:?}", second.error); + assert!( + second.conflicts.is_empty(), + "基线记的必须是胜者那份，否则这里会冒出一条假的 user_modified：{:?}", + second.conflicts + ); + assert_eq!(read_text(&target.join("config/dup.toml")), "from-client\n"); + // 反向确认：冲突清单里不该出现这条路径的**任何**成因。 + assert!(!second + .conflicts + .iter() + .any(|conflict| conflict.path == "config/dup.toml" + && conflict.reason != ConflictReason::PreExisting)); +} 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..7ca69f3 --- /dev/null +++ b/crates/core/src/addon/tests/import_merge.rs @@ -0,0 +1,298 @@ +//! 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, write_file, zip_dir, TempRoot}; + +use crate::addon::import::{PackBaseline, BASELINE_FILE}; + +#[test] +fn user_modified_file_is_kept_and_reported() { + let (fixture, fetcher) = mrpack_stub("merge-modified"); + let root = TempRoot::new("merge-modified-out"); + let target = root.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 root = TempRoot::new("merge-deleted-out"); + let target = root.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 root = TempRoot::new("merge-upgrade-out"); + let target = root.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 root = TempRoot::new("merge-existing-out"); + let target = root.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 root = TempRoot::new("merge-overwrite-out"); + let target = root.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 = TempRoot::new("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 = TempRoot::under("baseline-path", "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.to_path_buf()) + .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 = TempRoot::new("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..be93253 --- /dev/null +++ b/crates/core/src/addon/tests/import_modrinth.rs @@ -0,0 +1,181 @@ +//! 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, TempRoot}; + +#[test] +fn imports_mrpack_end_to_end() { + let (fixture, fetcher) = mrpack_stub("mr-e2e"); + let root = TempRoot::new("mr-e2e-out"); + let target = root.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() { + // 引擎在下载失败时故意留下 `.ullpart--` 与 `.ullmeta.json` + // 供下次续传；它们躺在暂存目录里，提交前必须剔掉，否则会变成实例里的"内容"。 + let (fixture, fetcher) = mrpack_stub("mr-artifacts"); + let fetcher = fetcher.with_engine_artifacts(); + let root = TempRoot::new("mr-artifacts-out"); + let target = root.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 root = TempRoot::new("mr-disabled-out"); + let target = root.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..6d9789c --- /dev/null +++ b/crates/core/src/addon/tests/import_multimc.rs @@ -0,0 +1,215 @@ +//! 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, write_file, TempRoot}; + +#[test] +fn imports_multimc_instance_end_to_end() { + let source = fixtures::multimc("mmc-e2e"); + let root = TempRoot::new("mmc-e2e-out"); + let target = root.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 root = TempRoot::new("mmc-components-out"); + let target = root.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 = TempRoot::new("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 root = TempRoot::new("mmc-mem-out"); + let target = root.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 root = TempRoot::new("mmc-mem-gated-out"); + let gated_target = root.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/.json。 + let root = TempRoot::new("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 = TempRoot::new("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 root = TempRoot::new("mmc-v2-out"); + let target = root.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_online.rs b/crates/core/src/addon/tests/import_online.rs new file mode 100644 index 0000000..8b03811 --- /dev/null +++ b/crates/core/src/addon/tests/import_online.rs @@ -0,0 +1,311 @@ +//! 远端条目补全（M162）：**有 path 但没有 `hashes.sha1` 的 mrpack 条目，补得出就判，补不出照旧计数**。 +//! +//! 三条纪律： +//! +//! 1. 补全靠 `PackFetcher::modrinth_file_by_sha512`（默认 `Unsupported` ⇒ 离线导入补不出）； +//! 2. 补出来的条目与自带 `sha1` 的条目走**同一个** `judge`（M160 的判据一行没改）； +//! 3. 补出的 `sha1` 会真的用在下载校验上——所以「站点给错摘要」必须是 `Failed`（内容不符）， +//! 不能被当成「暂时搞不到」混过去。 +//! +//! 全部离线：`StubFetcher` 里挂一条 sha512 → 元数据，没有一个真实请求。 + +use super::support::{sha1, StubFetcher}; +use super::{read_text, write_file, zip_dir, TempRoot}; +use crate::addon::import::{ + import_pack, scan_pack, scan_pack_online, ImportRequest, ImportStatus, ModrinthFileMeta, +}; +use crate::download::blocking::block_on; + +const PATH: &str = "mods/no-sha1.jar"; +const DISK_BYTES: &[u8] = b"what the user already has"; +const PACK_BYTES: &[u8] = b"what the content source serves"; +const DOWNLOAD: &str = "stub://mods/no-sha1.jar"; +const SHA512: &str = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\ +0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"; + +/// 一个只有 `hashes.sha512` 的 mrpack（sha1 缺失 = 预检判不了）。 +fn mrpack_without_sha1(tag: &str) -> (TempRoot, std::path::PathBuf) { + let root = TempRoot::new(tag); + let dir = root.join("src"); + let index = format!( + r#"{{"game":"minecraft","formatVersion":1,"versionId":"1.0.0","name":"缺 sha1 的包", + "files":[{{"path":"{PATH}", + "hashes":{{"sha512":"{SHA512}"}}, + "downloads":["{DOWNLOAD}"],"fileSize":{size}}}], + "dependencies":{{"minecraft":"1.20.1"}}}}"#, + size = PACK_BYTES.len() + ); + write_file(&dir.join("modrinth.index.json"), index.as_bytes()); + let pack = root.join("pack.mrpack"); + zip_dir(&dir, &pack); + (root, pack) +} + +/// 站点给出这个文件的 sha1/字节数（`sha1` 由调用方决定对不对）。 +fn meta(pack_sha1: &str) -> ModrinthFileMeta { + ModrinthFileMeta { + sha1: Some(pack_sha1.to_string()), + size: Some(PACK_BYTES.len() as u64), + url: Some(DOWNLOAD.to_string()), + file_name: Some("no-sha1.jar".to_string()), + } +} + +#[test] +fn offline_scan_keeps_the_unknown_remote_count() { + // 对照：没有 fetcher（离线）时口径与 M160 完全一致。 + let (root, pack) = mrpack_without_sha1("online-scan-offline"); + let target = root.join("instance"); + write_file(&target.join(PATH), DISK_BYTES); + let scan = scan_pack(&ImportRequest::new(&pack, &target)); + assert!(scan.is_ok(), "{:?}", scan.error); + assert_eq!(scan.unknown_remote, 1, "缺 sha1 就是判不了，如实计数"); + assert!(scan.conflicts.is_empty()); +} + +#[test] +fn an_online_scan_completes_the_sha1_and_judges_the_conflict() { + let (root, pack) = mrpack_without_sha1("online-scan-filled"); + let target = root.join("instance"); + write_file(&target.join(PATH), DISK_BYTES); + let fetcher = StubFetcher::new().with_modrinth(SHA512, meta(&sha1(PACK_BYTES))); + let scan = block_on(scan_pack_online( + &ImportRequest::new(&pack, &target).with_fetcher(&fetcher), + )); + assert!(scan.is_ok(), "{:?}", scan.error); + assert_eq!(scan.unknown_remote, 0, "补出来了就不再是「判不了」"); + let paths: Vec<&str> = scan.conflicts.iter().map(|c| c.path.as_str()).collect(); + assert_eq!(paths, vec![PATH], "补出来的摘要要真的用上：{:?}", paths); + assert_eq!(scan.conflicts[0].pack_sha1, sha1(PACK_BYTES)); + assert!(scan + .notes + .iter() + .any(|note| note.message.contains("补全了 1 条远端条目的 sha1"))); +} + +#[test] +fn a_scan_whose_source_does_not_know_the_hash_still_counts_it() { + let (root, pack) = mrpack_without_sha1("online-scan-unknown"); + let target = root.join("instance"); + write_file(&target.join(PATH), DISK_BYTES); + // 站点不认得这个 sha512（stub 里没挂）⇒ 补不出，口径回到 M160 + let fetcher = StubFetcher::new(); + let scan = block_on(scan_pack_online( + &ImportRequest::new(&pack, &target).with_fetcher(&fetcher), + )); + assert_eq!(scan.unknown_remote, 1); + assert!(scan.conflicts.is_empty()); +} + +#[test] +fn a_completed_sha1_is_actually_used_for_the_download_check() { + let (root, pack) = mrpack_without_sha1("online-import-ok"); + let target = root.join("instance"); + let fetcher = StubFetcher::new() + .with_modrinth(SHA512, meta(&sha1(PACK_BYTES))) + .with_file(DOWNLOAD, PACK_BYTES); + let report = block_on(import_pack( + &ImportRequest::new(&pack, &target).with_fetcher(&fetcher), + )); + assert_eq!(report.status, ImportStatus::Success, "{:?}", report.error); + assert_eq!( + read_text(&target.join(PATH)), + String::from_utf8_lossy(PACK_BYTES) + ); + assert!(report.missing.is_empty(), "{:?}", report.missing); + assert!( + report + .warnings + .iter() + .any(|note| note.message.contains("补全了 1 条远端条目的 sha1")), + "报告要说清补全过：{:?}", + report.warnings + ); +} + +#[test] +fn a_wrong_completed_sha1_fails_the_import_instead_of_installing() { + // 站点给了错的 sha1 ⇒ 下载校验必须拦住（这是"内容坏了"，不是"暂时搞不到"）。 + let (root, pack) = mrpack_without_sha1("online-import-bad"); + let target = root.join("instance"); + let fetcher = StubFetcher::new() + .with_modrinth(SHA512, meta(&"f".repeat(40))) + .with_file(DOWNLOAD, PACK_BYTES); + let report = block_on(import_pack( + &ImportRequest::new(&pack, &target).with_fetcher(&fetcher), + )); + assert_eq!(report.status, ImportStatus::Failed, "{:?}", report.status); + assert_eq!( + report.error.as_ref().map(|error| error.code()), + Some("import_integrity"), + "{:?}", + report.error + ); + assert!(!target.join(PATH).exists(), "失败的导入不许留文件"); +} + +// ---------------------------------------------------------------- r1 P1-1 后果 B 的守卫 + +const CF_SHA512: &str = "c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1\ +c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1c1"; + +/// 两条远端条目：第一条**站点不认得**（等价于托管在 CurseForge CDN），第二条认得。 +/// +/// 真实 mrpack 大多是这个形状——所以「第一条补不出就掐掉整轮」是 r1 抓到的后果 B。 +fn pack_with_one_unknown_sha512(tag: &str) -> (TempRoot, std::path::PathBuf) { + let root = TempRoot::new(tag); + let dir = root.join("src"); + let index = format!( + r#"{{"game":"minecraft","formatVersion":1,"versionId":"1.0.0","name":"混托管", + "files":[ + {{"path":"mods/hosted-on-cf.jar","hashes":{{"sha512":"{CF_SHA512}"}}, + "downloads":["stub://mods/hosted-on-cf.jar"],"fileSize":10}}, + {{"path":"{PATH}","hashes":{{"sha512":"{SHA512}"}}, + "downloads":["{DOWNLOAD}"],"fileSize":{size}}} + ], + "dependencies":{{"minecraft":"1.20.1"}}}}"#, + size = PACK_BYTES.len() + ); + write_file(&dir.join("modrinth.index.json"), index.as_bytes()); + let pack = root.join("pack.mrpack"); + zip_dir(&dir, &pack); + (root, pack) +} + +#[test] +fn a_404_on_one_entry_does_not_stop_the_completion_round() { + // 第一次查（CF 那一条）站点回 404 ⇒ **不许**停：第二条仍然要补出来并参与判定。 + let (root, pack) = pack_with_one_unknown_sha512("online-mixed-hosting"); + let target = root.join("instance"); + write_file(&target.join(PATH), DISK_BYTES); + write_file(&target.join("mods/hosted-on-cf.jar"), b"user's own copy"); + + let fetcher = StubFetcher::new().with_modrinth(SHA512, meta(&sha1(PACK_BYTES))); + let scan = block_on(scan_pack_online( + &ImportRequest::new(&pack, &target).with_fetcher(&fetcher), + )); + assert!(scan.is_ok(), "{:?}", scan.error); + let paths: Vec<&str> = scan.conflicts.iter().map(|c| c.path.as_str()).collect(); + assert_eq!( + paths, + vec![PATH], + "第二条（托管在 Modrinth 的那条）必须补出来并判出冲突：{:?}", + paths + ); + assert_eq!(scan.unknown_remote, 1, "补不出的那一条仍如实计数"); + assert!( + !scan + .notes + .iter() + .any(|note| note.message.contains("未联网")), + "404 不是「没联网」，注记不许这么说：{:?}", + scan.notes.iter().map(|n| &n.message).collect::>() + ); +} + +#[test] +fn only_a_real_offline_stops_the_completion_round() { + let (root, pack) = pack_with_one_unknown_sha512("online-mixed-offline"); + let target = root.join("instance"); + write_file(&target.join(PATH), DISK_BYTES); + write_file(&target.join("mods/hosted-on-cf.jar"), b"user's own copy"); + + let fetcher = StubFetcher::new() + .with_modrinth(SHA512, meta(&sha1(PACK_BYTES))) + .offline_modrinth(); + let scan = block_on(scan_pack_online( + &ImportRequest::new(&pack, &target).with_fetcher(&fetcher), + )); + assert!(scan.is_ok(), "{:?}", scan.error); + assert_eq!(scan.unknown_remote, 2, "没联网 ⇒ 两条都判不了"); + assert!(scan.conflicts.is_empty()); + // 断网且一条也没补到：注记不许说「补全了 0 条」（读起来像成功），也不许带「缺省保留」 + // ——那句是导入场景的尾缀，预检里没有这回事（r3 登记项）。 + let note = scan + .notes + .iter() + .find(|note| note.message.contains("sha512")) + .expect("断网要留一条补全注记"); + assert!(note.message.contains("一条也没补到"), "{}", note.message); + assert!(!note.message.contains("补全了 0 条"), "{}", note.message); + assert!(!note.message.contains("缺省保留"), "{}", note.message); +} + +/// 清单自带 `sha1` 时补全不许插手（也不许改写清单里的摘要）。 +fn pack_with_sha1_and_sha512(tag: &str) -> (TempRoot, std::path::PathBuf) { + let root = TempRoot::new(tag); + let dir = root.join("src"); + let index = format!( + r#"{{"game":"minecraft","formatVersion":1,"versionId":"1.0.0","name":"两档摘要都有", + "files":[{{"path":"{PATH}", + "hashes":{{"sha1":"{sha1}","sha512":"{SHA512}"}}, + "downloads":["{DOWNLOAD}"],"fileSize":{size}}}], + "dependencies":{{"minecraft":"1.20.1"}}}}"#, + sha1 = sha1(PACK_BYTES), + size = PACK_BYTES.len() + ); + write_file(&dir.join("modrinth.index.json"), index.as_bytes()); + let pack = root.join("pack.mrpack"); + zip_dir(&dir, &pack); + (root, pack) +} + +#[test] +fn an_entry_that_already_has_a_sha1_is_left_alone() { + let (root, pack) = pack_with_sha1_and_sha512("online-keeps-sha1"); + let target = root.join("instance"); + write_file(&target.join(PATH), DISK_BYTES); + // 站点那边挂一个**不一样**的 sha1：真去反查并写回的话，这条就会被改写。 + let fetcher = StubFetcher::new().with_modrinth(SHA512, meta(&"e".repeat(40))); + let scan = block_on(scan_pack_online( + &ImportRequest::new(&pack, &target).with_fetcher(&fetcher), + )); + assert!(scan.is_ok(), "{:?}", scan.error); + let conflict = scan.conflicts.first().expect("磁盘内容不同 ⇒ 要判出冲突"); + assert_eq!( + conflict.pack_sha1, + sha1(PACK_BYTES), + "清单里的 sha1 不许被改写" + ); + assert!( + !scan + .notes + .iter() + .any(|note| note.message.contains("补全了")), + "没有条目需要补 ⇒ 不该写「补全了 N 条」的注记" + ); +} + +/// 清单没写 `downloads`：补全给的直链要能真的用上（否则这条只会进 missing）。 +fn pack_without_downloads(tag: &str) -> (TempRoot, std::path::PathBuf) { + let root = TempRoot::new(tag); + let dir = root.join("src"); + let index = format!( + r#"{{"game":"minecraft","formatVersion":1,"versionId":"1.0.0","name":"没有直链", + "files":[{{"path":"{PATH}","hashes":{{"sha512":"{SHA512}"}}, + "downloads":[],"fileSize":{size}}}], + "dependencies":{{"minecraft":"1.20.1"}}}}"#, + size = PACK_BYTES.len() + ); + write_file(&dir.join("modrinth.index.json"), index.as_bytes()); + let pack = root.join("pack.mrpack"); + zip_dir(&dir, &pack); + (root, pack) +} + +#[test] +fn a_completed_entry_can_supply_the_missing_download_url() { + let (root, pack) = pack_without_downloads("online-url-from-source"); + let target = root.join("instance"); + let fetcher = StubFetcher::new() + .with_modrinth(SHA512, meta(&sha1(PACK_BYTES))) + .with_file(DOWNLOAD, PACK_BYTES); + let report = block_on(import_pack( + &ImportRequest::new(&pack, &target).with_fetcher(&fetcher), + )); + assert_eq!(report.status, ImportStatus::Success, "{:?}", report.error); + assert_eq!( + read_text(&target.join(PATH)), + String::from_utf8_lossy(PACK_BYTES) + ); +} 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..bea2a23 --- /dev/null +++ b/crates/core/src/addon/tests/import_report.rs @@ -0,0 +1,167 @@ +//! 报告的**契约**测试：三态退出码、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::TempRoot; + +#[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 = TempRoot::new("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 root = TempRoot::new("report-ok-out"); + let target = root.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"), + // M160：预检（冲突清单）与逐文件决策的引用也要算进这张表， + // 否则 `NOTE_REMOTE_PATH_UNKNOWN` 会被判成"死常量"。 + include_str!("../import/scan.rs"), + // M162：补全注记的文案搬到了 `complete.rs`（原来在 pipeline/scan 各写一份）， + // 不把它算进这张表的话 `NOTE_REMOTE_COMPLETED` 会被判成死常量。 + include_str!("../import/complete.rs"), + include_str!("../import/decision.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..edc983e --- /dev/null +++ b/crates/core/src/addon/tests/mod.rs @@ -0,0 +1,176 @@ +//! `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` 在这里是刻意为之：改成两份副本才是真的错。 +mod decisions_support; +#[allow(clippy::duplicate_mod)] +#[path = "../pack/tests/fixtures.rs"] +mod fixtures; +mod import_curseforge; +mod import_decisions; +mod import_failures; +mod import_layering; +mod import_merge; +mod import_modrinth; +mod import_multimc; +mod import_online; +mod import_report; +mod roundtrip_three; +mod support; + +use std::fs::File; +use std::io::Write; +use std::path::{Path, PathBuf}; + +/// 一次性临时根（`Drop` 即删，panic 也删）。实现与 `pack::tests` 共用一份： +/// [`crate::addon::temp::TempRoot`]（两族用例都会建临时目录，守卫只此一处）。 +pub(crate) use crate::addon::temp::TempRoot; + +/// 写一个文件（自动建父目录）。 +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::, _>>() + .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 { + fn walk(base: &Path, dir: &Path, out: &mut Vec) { + 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/roundtrip_three.rs b/crates/core/src/addon/tests/roundtrip_three.rs new file mode 100644 index 0000000..ea3a78d --- /dev/null +++ b/crates/core/src/addon/tests/roundtrip_three.rs @@ -0,0 +1,257 @@ +//! `import → export → import` 三轮一致性（M160）。 +//! +//! # 这条用例补的是哪笔账 +//! +//! M111/M112 的往返各自只有半条链：导入侧测"包 → 实例"，导出侧测"实例 → 包"（`export_roundtrip` +//! 里明确登记了"M111 合并后要补一条 `import_pack → export → import_pack`"）。本文件就是那条， +//! 而且是**三轮**：包① → 实例 A → 包② → 实例 B → 包③ → 实例 C，三个实例的内容逐字节相等。 +//! +//! 夹具带 **overrides 叠层**（`client-overrides/` 与 `overrides/` 同名不同内容），并且第二轮 +//! 的实例**预置了一个与包冲突的文件**：用户选了「覆盖」，于是三轮之后仍然一致——这条同时证明 +//! "决策真的生效"与"决策之后的一致性仍然成立"。 +//! +//! # 为什么比的是"内容目录里的文件"而不是整棵树 +//! +//! 实例里还有两样东西**不属于整合包内容**：`versions//.json`（导出要读它，但导出器 +//! 不会把它打进包）与 `.ull/pack-baseline.json`（本仓库的三方合并基线）。两者都按设计不进包， +//! 所以比较口径是 `mods/` `config/` 等 8 个内容目录。 +//! +//! # 没验的部分 +//! +//! 真实社区包（CurseForge / Modrinth 在线下载）不在本轮：远端条目一律走 `StubFetcher`， +//! 导出一律走离线目录（`OfflineCatalog` ⇒ 全部内联）。这条欠账在完成报告里同样登记。 + +use std::collections::BTreeMap; +use std::path::Path; + +use super::support::{sha1, StubFetcher}; +use super::{write_file, zip_dir, TempRoot}; +use crate::addon::export::{export_instance, ExportRequest}; +use crate::addon::import::{ + import_pack, ConflictChoice, ConflictDecisions, ImportRequest, ImportStatus, +}; +use crate::addon::pack::format::PackFormat; +use crate::addon::pack::modrinth::MODRINTH; +use crate::addon::pack::PackArchive; +use crate::download::blocking::block_on; + +/// 内容目录白名单（与 `export::scan::DEFAULT_CONTENT_ROOTS` 同一条口径）。 +const CONTENT_ROOTS: [&str; 4] = ["mods", "config", "resourcepacks", "scripts"]; + +/// 夹具里 `client-overrides/` 胜出的那份内容。 +const KNOWN_CLIENT: &[u8] = b"shared = client\n"; +/// 夹具里 `overrides/` 侧（被遮蔽）。 +const KNOWN_OVERRIDES: &[u8] = b"shared = overrides\n"; +/// 仅 overrides 声明的文件。 +const LAYER: &[u8] = b"layer from overrides\n"; +/// 远端条目的内容（走 stub 下载）。 +const REMOTE: &[u8] = b"remote jar bytes"; +/// 第二轮实例里用户自己那份（与包冲突）。 +const USER_KNOWN: &[u8] = b"shared = mine\n"; + +/// 带叠层 + 一条远端条目的 mrpack。 +fn layered_pack(tag: &str) -> (TempRoot, StubFetcher) { + let root = TempRoot::at(tag, "pack.mrpack"); + let dir = root.parent().expect("临时根").join("src"); + let index = format!( + r#"{{"game":"minecraft","formatVersion":1,"versionId":"1.0.0","name":"M160 三轮夹具", + "files":[{{"path":"mods/remote.jar", + "hashes":{{"sha1":"{}","sha512":"{}"}}, + "downloads":["stub://mods/remote.jar"],"fileSize":{}}}], + "dependencies":{{"minecraft":"1.20.1"}}}}"#, + sha1(REMOTE), + "0".repeat(128), + REMOTE.len() + ); + write_file(&dir.join("modrinth.index.json"), index.as_bytes()); + write_file(&dir.join("overrides/config/known.toml"), KNOWN_OVERRIDES); + write_file( + &dir.join("client-overrides/config/known.toml"), + KNOWN_CLIENT, + ); + write_file(&dir.join("overrides/mods/layer.jar"), LAYER); + write_file(&dir.join("overrides/scripts/start.js"), b"// script\n"); + zip_dir(&dir, &root); + let fetcher = StubFetcher::new().with_file("stub://mods/remote.jar", REMOTE); + (root, fetcher) +} + +/// 内容目录里的文件（`/` 分隔、排序）→ 字节。 +fn content_files(root: &Path) -> BTreeMap> { + let mut out = BTreeMap::new(); + for dir in CONTENT_ROOTS { + let base = root.join(dir); + if !base.is_dir() { + continue; + } + let mut pending = vec![base]; + while let Some(current) = pending.pop() { + for entry in std::fs::read_dir(¤t).expect("读内容目录").flatten() { + let path = entry.path(); + if path.is_dir() { + pending.push(path); + continue; + } + let relative = path + .strip_prefix(root) + .expect("在实例内") + .to_string_lossy() + .replace('\\', "/"); + out.insert(relative, std::fs::read(&path).expect("读内容文件")); + } + } + } + out +} + +/// 给实例补一份版本 JSON（导出要读它拿游戏版本；导入**不装**游戏，所以得手工放）。 +fn write_version(root: &Path, id: &str, game: &str) { + write_file( + &root.join("versions").join(id).join(format!("{id}.json")), + format!(r#"{{"id":"{game}"}}"#).as_bytes(), + ); +} + +/// 实例 → 包（走产品路径的导出器，离线目录 ⇒ 全部内联）。 +fn export(root: &Path, target: &Path) { + let request = ExportRequest::new(root, target, &MODRINTH).with_version_id("1.20.1"); + let report = export_instance(&request).expect("导出"); + assert!( + report.is_complete(), + "夹具里每个文件都该能内联进包：{:?}", + report.summary() + ); + assert!(target.exists(), "导出产物不存在"); +} + +/// 导出的包里覆盖条目的 `路径 → sha1`（三轮之间要比这一份）。 +fn pack_overrides(pack: &Path) -> BTreeMap { + let archive = PackArchive::open_default(pack).expect("打开导出的包"); + let (format, manifest) = crate::addon::pack::PackRegistry::builtin() + .read(&archive) + .expect("读清单"); + assert_eq!(format.id(), MODRINTH.id(), "导出目标是 mrpack"); + manifest + .override_files() + .map(|(_, file)| (file.path.clone(), file.sha1.clone())) + .collect() +} + +#[test] +fn import_export_import_three_rounds_keep_the_same_file_set() { + let (pack1, fetcher) = layered_pack("rt3"); + let base = TempRoot::new("rt3"); + let (dir_a, dir_b, dir_c) = (base.join("a"), base.join("b"), base.join("c")); + + // —— 第 1 轮：包① → 实例 A（干净目标）—— + let first = block_on(import_pack( + &ImportRequest::new(&pack1, &dir_a).with_fetcher(&fetcher), + )); + assert_eq!(first.status, ImportStatus::Success, "{:?}", first.error); + assert_eq!( + content_files(&dir_a).keys().cloned().collect::>(), + vec![ + "config/known.toml", + "mods/layer.jar", + "mods/remote.jar", + "scripts/start.js" + ], + "叠层的胜者是 client-overrides（不是 overrides）；实际树：{:?}", + super::list_tree(&dir_a) + ); + write_version(&dir_a, "1.20.1", "1.20.1"); + let pack2 = base.join("round2.mrpack"); + export(&dir_a, &pack2); + + // —— 第 2 轮：包② → 实例 B（**预置冲突**，用户选「覆盖」）—— + write_file(&dir_b.join("config/known.toml"), USER_KNOWN); + let report = block_on(import_pack( + &ImportRequest::new(&pack2, &dir_b) + .with_fetcher(&fetcher) + .with_decisions( + ConflictDecisions::keep_all().with("config/known.toml", ConflictChoice::Overwrite), + ), + )); + assert_eq!(report.status, ImportStatus::Success, "{:?}", report.error); + let conflict = report + .conflicts + .iter() + .find(|conflict| conflict.path == "config/known.toml") + .expect("第二轮必须报出那个冲突"); + assert_eq!(conflict.choice, ConflictChoice::Overwrite); + write_version(&dir_b, "1.20.1", "1.20.1"); + let pack3 = base.join("round3.mrpack"); + export(&dir_b, &pack3); + + // —— 第 3 轮：包③ → 实例 C（干净目标）—— + let third = block_on(import_pack( + &ImportRequest::new(&pack3, &dir_c).with_fetcher(&fetcher), + )); + assert_eq!(third.status, ImportStatus::Success, "{:?}", third.error); + + // 三个实例的内容逐字节相等。 + let a = content_files(&dir_a); + let b = content_files(&dir_b); + let c = content_files(&dir_c); + assert_eq!(a, b, "第 1 轮与第 2 轮的文件集必须一致"); + assert_eq!(a, c, "第 1 轮与第 3 轮的文件集必须一致"); + assert_eq!( + a.get("config/known.toml").map(Vec::as_slice), + Some(KNOWN_CLIENT), + "覆盖之后留下的是包内内容" + ); + + // 包②与包③的覆盖条目（路径 + 哈希）也必须一致。 + assert_eq!( + pack_overrides(&pack2), + pack_overrides(&pack3), + "两轮导出的覆盖条目必须一样" + ); + // 导出的是"内联"形态（离线目录没有远端命中），所以覆盖条目就是那四条内容文件。 + assert_eq!( + pack_overrides(&pack2).keys().cloned().collect::>(), + vec![ + "config/known.toml", + "mods/layer.jar", + "mods/remote.jar", + "scripts/start.js" + ] + ); +} + +#[test] +fn keeping_the_user_file_is_what_makes_the_rounds_diverge() { + // 对照：同一个冲突若选「保留」，第二轮结果**按设计**与第一轮不同——这正是"决策真的进了管线" + // 的反向证据（否则 `per_item` 那条就只是走了个过场）。 + let (pack1, fetcher) = layered_pack("rt3-keep"); + let base = TempRoot::new("rt3-keep"); + let (dir_a, dir_b) = (base.join("a"), base.join("b")); + block_on(import_pack( + &ImportRequest::new(&pack1, &dir_a).with_fetcher(&fetcher), + )); + write_version(&dir_a, "1.20.1", "1.20.1"); + let pack2 = base.join("round2.mrpack"); + export(&dir_a, &pack2); + + write_file(&dir_b.join("config/known.toml"), USER_KNOWN); + let report = block_on(import_pack( + &ImportRequest::new(&pack2, &dir_b).with_fetcher(&fetcher), + )); + // 保留了一条冲突 ⇒ `Partial`（实例可用，但与包内容不全一致）。 + assert_eq!(report.status, ImportStatus::Partial, "{:?}", report.error); + assert_eq!( + std::fs::read(dir_b.join("config/known.toml")).expect("读"), + USER_KNOWN, + "缺省决策下用户那份必须原样留着" + ); + let a = content_files(&dir_a); + let b = content_files(&dir_b); + assert_ne!(a, b, "选了保留就该与第一轮不同（这条证明决策真的生效）"); + let mut differing: Vec<&str> = Vec::new(); + for (path, bytes) in &a { + if b.get(path) != Some(bytes) { + differing.push(path.as_str()); + } + } + assert_eq!(differing, vec!["config/known.toml"], "只有那一处不同"); +} diff --git a/crates/core/src/addon/tests/support.rs b/crates/core/src/addon/tests/support.rs new file mode 100644 index 0000000..7b6cc61 --- /dev/null +++ b/crates/core/src/addon/tests/support.rs @@ -0,0 +1,248 @@ +//! 测试替身：内存里的远端（零网络）+ 把 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, ModrinthFileMeta, 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>, + curse: BTreeMap<(i64, i64), CurseFileMeta>, + /// M162：按 sha512 查到的 Modrinth 文件元数据（模拟「站点认得这个文件」）。 + modrinth: BTreeMap, + /// M162：补全时假装「没联网」（与「站点不认得这个摘要」区分开）。 + modrinth_offline: bool, + /// 被请求过的 URL（断言"没白下载"用）。 + calls: Mutex>, + /// 是否像真引擎那样在目标旁边留下续传残片（`.ullpart-*` / `.ullmeta.json`）。 + artifacts: bool, +} + +impl StubFetcher { + /// 空表。 + pub(crate) fn new() -> Self { + Self { + files: BTreeMap::new(), + curse: BTreeMap::new(), + modrinth: BTreeMap::new(), + modrinth_offline: false, + 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 + } + + /// 挂一条「按 sha512 反查」的结果（M162 的补全路径）。 + pub(crate) fn with_modrinth(mut self, sha512: &str, meta: ModrinthFileMeta) -> Self { + self.modrinth.insert(sha512.to_string(), meta); + self + } + + /// 让补全路径假装「没联网」（`FetchErrorKind::Offline`）。 + pub(crate) fn offline_modrinth(mut self) -> Self { + self.modrinth_offline = true; + self + } + + /// 像真引擎那样在每次"下载"后留下续传残片与 meta（用来钉"中间产物不许进实例"）。 + pub(crate) fn with_engine_artifacts(mut self) -> Self { + self.artifacts = true; + self + } + + /// 被请求过的 URL 列表。 + pub(crate) fn calls(&self) -> Vec { + 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> { + 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 modrinth_file_by_sha512<'a>( + &'a self, + sha512: &'a str, + ) -> FetchFuture<'a, Result> { + Box::pin(async move { + if self.modrinth_offline { + return Err(super::super::import::FetchError::new( + super::super::import::FetchErrorKind::Offline, + "连不上 api.modrinth.com", + )); + } + self.modrinth.get(sha512).cloned().ok_or_else(|| { + super::super::import::FetchError::new( + super::super::import::FetchErrorKind::NotFound, + format!("stub 里没有 sha512={sha512}"), + ) + }) + }) + } + + fn fetch_file<'a>( + &'a self, + request: FetchRequest<'a>, + ) -> FetchFuture<'a, Result> { + 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 { + 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 { + 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, + /// authlib 认证服务器 API 根（其余轨为 `None`；凭据之外唯一需要持久化的服务器信息）。 + #[serde(default, skip_serializing_if = "Option::is_none")] + pub server_url: Option, + /// 创建时刻（Unix 毫秒；仅用于排序/展示）。 + pub created_at_ms: u64, +} + +impl AccountMeta { + /// 构造一条元数据（`profile_name` 可后补）。 + #[must_use] + pub fn new( + kind: AccountKind, + profile_id: impl Into, + profile_name: impl Into, + 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 { + 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（服务发现约定）。 +//! +//! 三条照抄要点： +//! - 端点 = `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 { + 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 { + 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, +} + +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 { + 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 { + 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 { + 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 { + 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 { + 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 { + 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 { + 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, + /// 是否允许非邮箱登录名（决定输入框校验）。 + #[serde(default)] + pub non_email_login: bool, + /// `skinDomains`（纹理白名单，注入参数会用；本期只保存）。 + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub skin_domains: Vec, +} + +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, + /// 正文形状。 + pub kind: BodyKind, + /// 服务端文案（已脱敏、已截断）。 + pub server_message: Option, + /// 正文摘要（已脱敏，≤[`DIGEST_CHARS`] 字符）。 + pub digest: String, +} + +impl ResponseDetail { + /// 细分机读码（**只增不改**）：JSON 拒绝沿用 M31 的 `_`； + /// 非 JSON 用新增后缀 `_non_json`；空体用 `_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 { + let body = reply.body.as_ref()?; + let mut parts: Vec = 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"), "")), + BodyKind::Html + ); + // 没给 Content-Type 时靠正文形状兜底。 + assert_eq!( + classify(&text_reply(403, None, "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"), "blocked"), + "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 拒绝沿用 `_`， + /// 拦截页（HTML/纯文本）是新增的 `_non_json`，空体是 `_empty_body`。 + /// + /// 载荷装箱：`ResponseDetail` 有 7 个字段（含 4 个字符串），不装箱会把整个枚举撑到 + /// 128 字节以上，`Result` 的每个 Ok 也跟着变胖（clippy `result_large_err`）。 + Response(Box), + /// 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 拒绝返回 `` 里带的错误码，链上非 2xx 返回 + /// `_` / `_non_json` / `_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, detail: impl Into) -> Self { + Self::Network { + url: url.into(), + detail: detail.into(), + } + } + + /// 落盘错误的构造。 + #[must_use] + pub fn store(path: impl fmt::Display, detail: impl Into) -> 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 = Result; + +#[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, + /// `Content-Type` 原样（诊断文案与分流判断用；缺失为 `None`）。 + pub content_type: Option, + /// 非 JSON 正文的前 [`RAW_PREVIEW_BYTES`] 字节（有损 UTF-8；JSON 解析成功时为 `None`）。 + pub raw: Option, +} + +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 { + 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 { + 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 { + 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 { + 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 { + 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::(&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) -> 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, + /// 粗分流码（[`AuthError::code`]）。 + pub code: String, + /// 细分码（[`AuthError::detail_code`]）。 + pub detail_code: String, + /// HTTP 状态码（链上拒绝才有）。 + pub status: Option, + /// `Content-Type`（链上拒绝才有）。 + pub content_type: Option, + /// 正文形状（链上拒绝才有）。 + pub body_kind: Option, + /// 服务端文案（已脱敏）。 + pub server_message: Option, + /// 正文摘要（已脱敏，≤200 字符）。 + pub digest: Option, + /// 是否可重试（[`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/` 分区下（`/auth.jsonl`）。 + #[must_use] + pub fn in_logs_dir(logs: impl Into) -> Self { + Self { + path: logs.into().join(AUTH_LOG_FILE), + } + } + + /// 直接指定文件路径。 + #[must_use] + pub fn at(path: impl Into) -> Self { + Self { path: path.into() } + } + + /// 便携模式默认位置（exe 同目录 `.ULL/logs/auth.jsonl`，跟随 `redirect.json`）。 + /// + /// 拿不到 exe 目录（极少数嵌入场景）时返回 `None`——没有可写的日志根就不写。 + #[must_use] + pub fn portable_default() -> Option { + 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: "blocked".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..51ed053 --- /dev/null +++ b/crates/core/src/auth/microsoft/authcode.rs @@ -0,0 +1,348 @@ +//! 授权码流（`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::preflight::{self, RedirectRegistration}; +use super::session::MicrosoftSession; +use super::{BrowserFallback, BrowserFallbackReason}; + +/// 授权码 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, + /// CSRF 用的 `state`（`None` = 每次随机生成）。 + pub state: Option, +} + +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 { + 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( + client: &Client, + endpoints: &MicrosoftEndpoints, + client_id: &str, + policy: AuthCodePolicy, + present: F, +) -> AuthResult +where + F: FnOnce(&AuthCodePrompt), +{ + login_counting(client, endpoints, client_id, policy, None, present).await +} + +/// 同 [`login`]，但把**绑定现场**的监听口次数记进 `counter`（M178 的取证计数）。 +pub(crate) async fn login_counting( + client: &Client, + endpoints: &MicrosoftEndpoints, + client_id: &str, + policy: AuthCodePolicy, + counter: Option<&std::sync::atomic::AtomicUsize>, + present: F, +) -> AuthResult +where + F: FnOnce(&AuthCodePrompt), +{ + let state = policy.state.clone().unwrap_or_else(nonce); + let server = + CallbackServer::bind_counting(policy.port, policy.bind_attempts, state.clone(), counter) + .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 +} + +/// 一次「浏览器优先」尝试的结果（M178）。 +pub(crate) enum AuthCodeAttempt { + /// 授权码流走通（凭据已换到，整链完成）。 + LoggedIn(MicrosoftSession), + /// **没去试**：预检说这个回环 URI 没登记（或问不出来）。监听端口一次都没开。 + Skipped(BrowserFallback), +} + +/// 带预检的授权码登录：注册里有这个回环 URI 才真去绑端口、弹浏览器。 +/// +/// 顺序是刻意的——**预检在绑定之前**：没登记的机器上连监听口都不开（`counter` 是绑定现场的 +/// 真计数，见 [`CallbackServer::bind_counting`]），也就不会出现「浏览器里一张 AAD 错误页 + +/// 启动器干等 5 分钟」的那套现象（M178 用户实测的那个 bug）。 +pub(crate) async fn login_checked( + client: &Client, + endpoints: &MicrosoftEndpoints, + client_id: &str, + policy: AuthCodePolicy, + counter: &std::sync::atomic::AtomicUsize, + present: F, +) -> AuthResult +where + F: FnOnce(&AuthCodePrompt), +{ + let probe = RedirectUri::new(preflight::PROBE_PORT); + match preflight::check(client, endpoints, client_id, &probe).await { + RedirectRegistration::Registered => {} + RedirectRegistration::NotRegistered { detail } => { + return Ok(AuthCodeAttempt::Skipped(BrowserFallback::new( + BrowserFallbackReason::RedirectNotRegistered, + detail, + ))) + } + RedirectRegistration::Unknown { detail } => { + return Ok(AuthCodeAttempt::Skipped(BrowserFallback::new( + BrowserFallbackReason::PreflightUnavailable, + detail, + ))) + } + } + let session = + login_counting(client, endpoints, client_id, policy, Some(counter), present).await?; + Ok(AuthCodeAttempt::LoggedIn(session)) +} + +/// 每次登录一个 `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..400a6a3 --- /dev/null +++ b/crates/core/src/auth/microsoft/callback.rs @@ -0,0 +1,364 @@ +//! 授权码流的本地回调服务器（`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 = "\ +登录完成\ +

登录完成

可以关闭此窗口，回到启动器继续。

"; +const DENIED_PAGE: &str = "\ +登录未完成\ +

登录未完成

授权没有完成，可以回到启动器重试。

"; +const BAD_REQUEST_PAGE: &str = "\ +回调无效\ +

回调无效

这个链接不属于本次登录。

"; +const NOT_FOUND_PAGE: &str = "\ +Not Found

Not Found

"; + +/// 本地回调服务器（一个实例只服务一次登录）。 +#[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, + attempts: u8, + state: impl Into, + ) -> AuthResult { + Self::bind_counting(port, attempts, state, None).await + } + + /// 同 [`Self::bind`]，但把**每一次真正调用 `TcpListener::bind`** 记进 `counter`（M178）。 + /// + /// 为什么不把计数写在外层：`LoginOutcome::listeners_opened` 是「这次登录有没有偷开监听口」 + /// 的唯一证据，它必须是**绑定现场**的数，不能是「进没进授权码分支」的代理指标 + /// （复审 r1 P2-1 的变异 D 实测：代理指标对「真的多绑了一次」不敏感）。 + /// 计数发生在 `TcpListener::bind` 调用之前：要数的是「去开了没」，不是「开成功了没」。 + pub(crate) async fn bind_counting( + port: Option, + attempts: u8, + state: impl Into, + counter: Option<&std::sync::atomic::AtomicUsize>, + ) -> AuthResult { + let wanted = port.unwrap_or(0); + let attempts = attempts.max(1); + let mut last = String::new(); + for attempt in 0..attempts { + if let Some(counter) = counter { + counter.fetch_add(1, std::sync::atomic::Ordering::Relaxed); + } + 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 { + 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> { + 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 { + 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 { + 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=;`**（分号分隔，`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=;...` 的 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 { + 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 { + 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 { + 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 { + 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 { + 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 { + 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 { + 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) -> 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..67a1d32 --- /dev/null +++ b/crates/core/src/auth/microsoft/client_id.rs @@ -0,0 +1,120 @@ +//! Azure 公共客户端 id 的**配置状态**：从哪来、配没配、启动日志那一行长什么样。 +//! +//! ## 为什么单独一块（M117） +//! +//! 这是**公共客户端 id**（非机密，随二进制一起分发），可以来自两处：运行期环境变量 [`CLIENT_ID_ENV`]， +//! 或构建期 `option_env!` 注入（[`CLIENT_ID_BUILD`]）——官方发布构建在构建时烘入它（M149）， +//! 所以官方产物开箱即用；环境变量仍优先，可覆盖。**两处都没有**时登录是「没配置」， +//! 不是「没实现」——这两件事在用户眼里完全不同，文案与日志都必须分清： +//! +//! | 现象 | 该说什么 | +//! |---|---| +//! | 两处都没配 | [`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= cargo build`）。 +/// +/// 官方发布构建就是这么烘的（`.github/workflows/release-build.yml` 给构建步设了同名环境变量，M149； +/// 值来自仓库 Secret，不进 git 文件），所以官方产物走到这里恒为 `Some`；从源码自建时才可能为空。 +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= cargo build`；或启动前设置同名环境变量 `ULL_MSA_CLIENT_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, +} + +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 { + 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)] +#[path = "client_id/tests.rs"] +mod tests; diff --git a/crates/core/src/auth/microsoft/client_id/tests.rs b/crates/core/src/auth/microsoft/client_id/tests.rs new file mode 100644 index 0000000..c9ccad6 --- /dev/null +++ b/crates/core/src/auth/microsoft/client_id/tests.rs @@ -0,0 +1,358 @@ +//! `client_id` 的判据（从 `client_id.rs` 拆出来守 400 行硬线）。 +//! +//! 两块：①「缺 id」文案与日志行的措辞纪律（M117）；②**M178 守卫**——client id 只能构建期注入， +//! 微软轨源码里不许出现 UUID 形状的字面量（复审 r1 P2-3 加严：`concat!` / 跨行 / `format!` +//! 三种拼法都要抓得住，且不许误杀 `session.rs` 里那个 profile UUID）。 + +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, +} + +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。 + assert!(MISSING_CLIENT_ID_MESSAGE.contains("")); +} + +#[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 时唯一合法（`ULL_MSA_CLIENT_ID` 也设进 `cargo test` 的环境就会走到这里； + // 官方发布构建即烘了 id，但门禁里的 `cargo test` 不带该变量，故常态走上面那条。 + // 注意：把该变量导出到跑测试的 shell 会让 presenter 的 M132 入口锚**故意红** + // （它要求「两处都没有 id」的构建，见 crates/presenter/src/host/accounts/tests.rs）。 + 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()); + } +} + +/// **M178 守卫**：client id 只能构建期/运行期注入，**微软轨源码里不许出现任何真实 id**。 +/// +/// 抓得住：为了让登录「开箱可用」而把一个真 client id 写进源码（或写进本模块的默认值）。 +/// 抓不住：`.github/workflows` 里 Secret 的接线（那不在本 crate 的范围内，靠发布链自己的 +/// `packaging/check_release_semantics.py` 与 Actions 日志看）。 +#[test] +fn no_client_id_is_hardcoded_in_the_microsoft_sources() { + // 判据一：本模块的 id 只能来自 `option_env!`（构建期注入）。 + let manifest = env!("CARGO_MANIFEST_DIR"); + let source = std::fs::read_to_string(format!("{manifest}/src/auth/microsoft/client_id.rs")) + .expect("读 client_id.rs"); + assert!( + source.contains("option_env!(\"ULL_MSA_CLIENT_ID\")"), + "client id 的构建期注入点不见了" + ); + // 判据二：`auth/microsoft/` 下的任何源码都不许出现 UUID 形状的字面量 + // （Azure 客户端 id 就是 UUID）。扫**全部文件**，所以把 id 挪到别的模块同样会红。 + // 范围只到 `auth/microsoft/`：`auth/offline.rs` 里那个带连字符的 UUID 是离线名字的 + // 测试向量，与 client id 无关。 + let mut offenders = Vec::new(); + let mut stack = vec![format!("{manifest}/src/auth/microsoft")]; + while let Some(dir) = stack.pop() { + let Ok(entries) = std::fs::read_dir(&dir) else { + continue; + }; + for entry in entries.flatten() { + let path = entry.path(); + if path.is_dir() { + stack.push(path.display().to_string()); + continue; + } + if path.extension().is_some_and(|ext| ext == "rs") { + let text = std::fs::read_to_string(&path).unwrap_or_default(); + if contains_uuid_literal(&text) { + offenders.push(path.display().to_string()); + } + } + } + } + assert!( + offenders.is_empty(), + "这些源文件里出现了 UUID 形状的字面量（client id 只能构建期注入）：{offenders:?}" + ); +} + +/// 源码里有没有「Azure 客户端 id 形状」的字面量（复审 r1 P2-3 加严）。 +/// +/// 两条判据，覆盖复审点名的三种拼法： +/// 1. **带连字符**（`8-4-4-4-12`）：把全部字面量首尾相接后扫，于是 +/// `concat!("83fd9b2f-", "da89-…")`、跨行相邻两段、单段完整 UUID 都能抓到； +/// 2. **无连字符的 32 位十六进制、且由 ≥2 个**连续**的「纯十六进制字面量**拼起来 +/// （`format!("{}-{}-{}-{}", "83fd9b2f", "da89", …)` 这类逐段拼法）。 +/// +/// 为什么判据 2 要求 ≥2 段：`session.rs` 的测试数据里有 profile UUID +/// （`"0f8fad5bd9cb469fa16570867728950e"`）——单个字面量的 32 位 hex 是**档案 id**， +/// 不是 client id；只有「拼出来的」才可疑。也不能把字面量无分隔地全部相接去数 hex 段： +/// 那样下一个字面量的开头若恰好是 hex 字符（如 `"Bearer"` 的 `Bea`）会把上一段续长造成误杀。 +fn contains_uuid_literal(text: &str) -> bool { + let literals = string_literals(text); + let joined: String = literals.iter().map(String::as_str).collect(); + if has_dashed_uuid(&joined) { + return true; + } + // 判据 2：连续的「纯 hex 字面量」累计长度 ≥32 且至少两段。 + let mut run_len = 0; + let mut run_parts = 0; + for literal in &literals { + let pure_hex = !literal.is_empty() && literal.bytes().all(|b| b.is_ascii_hexdigit()); + if pure_hex { + run_len += literal.len(); + run_parts += 1; + if run_len >= 32 && run_parts >= 2 { + return true; + } + } else { + run_len = 0; + run_parts = 0; + } + } + false +} + +/// 收集源码里的字符串字面量内容（跳过注释；`\` 转义按「跳一个字符」处理）。 +/// +/// 为什么跳注释：本模块的文档里就写着 `concat!("83fd9b2f-", "da89-…")` 这类**说明性**例子， +/// 不跳的话自检样本会被自己的文档抓成 offender（实测踩过）。注释里出现 id 不构成「代码里 +/// 硬编码 id」，判据只管可执行的字面量。 +/// +/// 近似处（够用即可）：字符字面量 `'a'` 不当字符串；`r#"…"#` 按普通字面量近似（前缀 `r` +/// 不在引号内，不影响内容提取）。 +fn string_literals(source: &str) -> Vec { + let bytes = source.as_bytes(); + let mut out = Vec::new(); + let mut index = 0; + while index < bytes.len() { + match bytes[index] { + // 行注释：跳到行尾 + b'/' if bytes.get(index + 1) == Some(&b'/') => { + while index < bytes.len() && bytes[index] != b'\n' { + index += 1; + } + } + // 块注释：跳到 `*/` + b'/' if bytes.get(index + 1) == Some(&b'*') => { + index += 2; + while index + 1 < bytes.len() && !(bytes[index] == b'*' && bytes[index + 1] == b'/') + { + index += 1; + } + index = (index + 2).min(bytes.len()); + } + b'"' => { + index += 1; + let start = index; + let mut escaped = false; + while index < bytes.len() { + let byte = bytes[index]; + if escaped { + escaped = false; + index += 1; + continue; + } + match byte { + b'\\' => { + escaped = true; + index += 1; + } + b'"' => break, + _ => index += 1, + } + } + let end = index.min(bytes.len()); + out.push(String::from_utf8_lossy(&bytes[start..end]).into_owned()); + index += 1; + } + _ => index += 1, + } + } + out +} + +/// 拼接后的串里有没有 `8-4-4-4-12` 的十六进制段（间距 5-5-5-13）。 +fn has_dashed_uuid(text: &str) -> bool { + fn hex(value: &[u8]) -> bool { + !value.is_empty() && value.iter().all(u8::is_ascii_hexdigit) + } + let bytes = text.as_bytes(); + let dashes: Vec = bytes + .iter() + .enumerate() + .filter(|(_, byte)| **byte == b'-') + .map(|(index, _)| index) + .collect(); + dashes.windows(4).any(|window| { + let (first, last) = (window[0], window[3]); + let gaps = [ + window[1] - first, + window[2] - window[1], + window[3] - window[2], + ]; + if gaps != [5, 5, 5] || last + 13 > bytes.len() || first < 8 { + return false; + } + hex(&bytes[first - 8..first]) + && hex(&bytes[first + 1..window[1]]) + && hex(&bytes[window[1] + 1..window[2]]) + && hex(&bytes[window[2] + 1..last]) + && hex(&bytes[last + 1..last + 13]) + }) +} + +/// 判据自检：三种拼法都要抓得住，且不能把普通代码当 client id。 +/// +/// 没有这条，扫描可能因为判据本身坏掉而永远为真（假绿）。 +/// 样本**运行时拼、且源码里不出现十六进制字面量**（用 `char` 数组拼）：否则这条自检的 +/// 样本本身会被扫描抓成 offender——自指陷阱（实测踩过一次）。 +#[test] +fn the_uuid_literal_detector_bites_three_shapes() { + let part = |chars: &[char]| chars.iter().collect::(); + let head = part(&['8', '3', 'f', 'd', '9', 'b', '2', 'f']); + let p2 = part(&['d', 'a', '8', '9']); + let p3 = part(&['4', '1', 'f', '7']); + let p4 = part(&['b', '4', '1', 'b']); + let tail = part(&['1', '3', '7', '4', '2', 'a', '7', '3', '8', '4', '1', 'c']); + let uuid = format!("{head}-{p2}-{p3}-{p4}-{tail}"); + + // ① 单个完整字面量（基线）。 + let plain = format!("let id = \"{uuid}\";"); + assert!(contains_uuid_literal(&plain), "{plain}"); + // ② `concat!` 拼出来（复审点名的形态之一）。 + let concatenated = format!("const ID: &str = concat!(\"{head}-\", \"{p2}-{p3}-{p4}-{tail}\");"); + assert!(contains_uuid_literal(&concatenated), "{concatenated}"); + // ③ 跨行两段字面量。 + let split_lines = + format!("let id = concat!(\n \"{head}-{p2}-\",\n \"{p3}-{p4}-{tail}\"\n);"); + assert!(contains_uuid_literal(&split_lines), "{split_lines}"); + // ④ `format!` 逐段拼（无连字符落点，靠「连续纯 hex 字面量累计 ≥32 且 ≥2 段」抓）。 + let formatted = format!( + "let id = format!(\"{{}}-{{}}-{{}}-{{}}-{{}}\", \"{head}\", \"{p2}\", \"{p3}\", \"{p4}\", \"{tail}\");" + ); + assert!(contains_uuid_literal(&formatted), "{formatted}"); + + // 反例：这些都不许误杀。 + assert!(!contains_uuid_literal("// 0000-test-client")); + assert!(!contains_uuid_literal("a-b-c-d")); + assert!(!contains_uuid_literal( + "let uri = \"http://localhost/auth?client_id=not-a-uuid\";" + )); + // 单个字面量的 32 位 hex = 既有测试数据（`session.rs` 的 profile UUID），不算 client id。 + let profile = format!("let profile_id = \"{head}{p2}{p3}{p4}{tail}\";"); + assert!(!contains_uuid_literal(&profile), "{profile}"); + // 段长不对的连字符串不算（`8-4-4-4-12` 之外一律放行）。 + assert!(!contains_uuid_literal( + "let x = \"abcdefgh-1234-5678-9012-12345678901\";" + )); +} 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=;"`）。 + 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 { + 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 { + 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 { + 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 { + 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) -> Reply { + Reply { + status, + body, + content_type: Some("application/json".to_string()), + raw: None, + } + } +} diff --git a/crates/core/src/auth/microsoft/login.rs b/crates/core/src/auth/microsoft/login.rs new file mode 100644 index 0000000..ad50f47 --- /dev/null +++ b/crates/core/src/auth/microsoft/login.rs @@ -0,0 +1,195 @@ +//! 「浏览器优先、失败自动回退设备码」（M178）——GUI 那条可选加速路的编排。 +//! +//! ## 为什么这条流必须自己会退 +//! +//! 授权码（浏览器）流把用户送回 `http://localhost:{port}/auth`。随机端口只有在「回环 URI +//! 的端口不参与匹配」成立时才可能被接受——微软官方文档 +//! （[*Redirect URI (reply URL) best practices and limitations*](https://learn.microsoft.com/en-us/entra/identity-platform/reply-url)， +//! *Localhost exceptions*）原文： +//! +//! > "Due to ephemeral port ranges often required by native applications, the port component +//! > (for example, :5001 or :443) is ignored for the purposes of matching a localhost redirect URI." +//! +//! 也就是说**注册一次 `http://localhost/auth` 就能接住任意端口**；但本项目这个注册当初是为 +//! device-code 建的，重定向 URI 一项都没登记（`DevDocs/ops/azure-msa-app.md`）。没登记时 +//! 授权端点当场回 `invalid_request ... 'redirect_uri' is not valid`，**而且不会**再跳回本地 +//! 回调——用户只看到一张 AAD 原始错误页，启动器干等到超时。这正是 2026-11-08 官方产物上 +//! 「微软登录整体不可用」的根因。 +//! +//! 于是这里的分工是：设备码当默认（不依赖任何注册项），浏览器流只在**用户显式要求**时试， +//! 而且试之前先预检（[`super::preflight`]）：没登记就一个监听口都不开。 +//! +//! 回退说明有两层：结构化码 [`BrowserFallbackReason`]（宿主据它出 i18n，**能说清怎么修**） +//! 与原始诊断 [`BrowserFallback::detail`]（只进日志，不上屏）。 + +use std::sync::atomic::{AtomicUsize, Ordering}; + +use crate::auth::error::{AuthError, AuthResult}; + +use super::authcode::{self, AuthCodeAttempt, AuthCodePrompt}; +use super::chain; +use super::flow::{self, DeviceCodePrompt}; +use super::now_ms; +use super::preflight; +use super::session::MicrosoftSession; +use super::MicrosoftAuth; + +/// 「浏览器优先但没走成」的原因（**上屏只看码**，`detail` 只进日志）。 +/// +/// 三个码对应三种不同的下一步： +/// - [`BrowserFallbackReason::RedirectNotRegistered`]：应用注册里没登记回环重定向 URI。 +/// 修法是**具体可执行的**（把 `http://localhost/auth` 加进「重定向 URI」，端口不参与匹配）。 +/// - [`BrowserFallbackReason::PreflightUnavailable`]：没法确认（网络/超时），只能先用设备码。 +/// - [`BrowserFallbackReason::AttemptFailed`]：试过了但失败（超时、换 token 被拒…）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum BrowserFallbackReason { + /// 授权端点当场拒绝了这个回环 `redirect_uri`（`invalid_request` / `AADSTS50011`） + RedirectNotRegistered, + /// 预检本身没问出结论（网络/超时/非预期应答） + PreflightUnavailable, + /// 预检通过、但授权码流仍然没走通 + AttemptFailed, +} + +impl BrowserFallbackReason { + /// 稳定的 ascii 码（日志 / 页面「Code: …」/ 测试断言都用它）。 + #[must_use] + pub const fn code(self) -> &'static str { + match self { + Self::RedirectNotRegistered => "redirect_not_registered", + Self::PreflightUnavailable => "preflight_unavailable", + Self::AttemptFailed => "attempt_failed", + } + } +} + +/// 回退到设备码时的说明：原因码 + 原始诊断（诊断只进日志，不上屏）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct BrowserFallback { + /// 原因码 + pub reason: BrowserFallbackReason, + /// 原始诊断（**只进日志**；截断到 240 字符） + pub detail: String, +} + +impl BrowserFallback { + /// 构造（诊断串截断：只进日志，别把整张错误页灌进去）。 + #[must_use] + pub fn new(reason: BrowserFallbackReason, detail: impl Into) -> Self { + let detail = detail.into(); + let detail = match detail.char_indices().nth(240) { + Some((index, _)) => format!("{}…", &detail[..index]), + None => detail, + }; + Self { reason, detail } + } +} + +/// 一次「浏览器优先」登录的完整结果（M178）。 +/// +/// `listeners_opened` 是**这次登录**真的去开本地监听口的次数（0 或 1，`bind_counting` 在 +/// `TcpListener::bind` 现场 +1）。它存在的唯一理由是守卫能直接数：「没登记回环」「走设备码」 +/// 这两条路上必须是 0。用进程级全局计数器做不到这一点（并行跑的测试会互相搅动），所以计数 +/// 是 per-login 的 `AtomicUsize`，但**增长点在绑定现场**，不在「进没进某个分支」。 +#[derive(Debug, Clone)] +pub struct LoginOutcome { + /// 拿到的会话（两条流任意一条走通） + pub session: MicrosoftSession, + /// 回退说明（`None` = 没走浏览器 / 浏览器走通了） + pub browser: Option, + /// 这次登录一共开了几个本地监听口（设备码路恒 0） + pub listeners_opened: usize, +} + +impl LoginOutcome { + /// 浏览器（授权码）流是不是被跳过了。 + #[must_use] + pub fn browser_was_skipped(&self) -> bool { + self.browser.is_some() + } +} + +impl MicrosoftAuth { + /// 浏览器优先、失败自动回退设备码（M178：GUI 的「用浏览器登录」入口）。 + /// + /// 顺序与判据： + /// 1. 先预检回环注册（[`authcode::login_checked`]）。没登记 / 问不出来 → **不绑端口**、 + /// 不弹浏览器，带一条结构化说明直接进设备码； + /// 2. 预检通过 → 真走授权码流（绑端口 + 弹浏览器）； + /// 3. 授权码流失败（超时 / 换 token 被拒 / 端口绑不上）→ 同样回退设备码， + /// 说明码是 [`BrowserFallbackReason::AttemptFailed`]（拒绝原因若属于「重定向 URI 没登记」 + /// 则归一成 [`BrowserFallbackReason::RedirectNotRegistered`]，好让用户看到怎么修）； + /// 4. **用户自己取消不算失败**（[`AuthError::Canceled`] 原样上抛）：那是明确意图， + /// 不能偷偷换一条流继续问用户要码。 + /// + /// `present_device` 额外收到回退说明（`None` = 根本没走浏览器），宿主据此在设备码面板上 + /// 画一句「为什么改用设备码 + 怎么修」。 + /// + /// # Errors + /// + /// 用户取消、设备码流本身的失败（网络/超时/被拒/无拥有权/无档案），见 [`AuthError`]。 + pub async fn browser_then_device_login( + &self, + present_browser: FB, + mut present_device: FD, + ) -> AuthResult + where + FB: FnOnce(&AuthCodePrompt), + FD: FnMut(&DeviceCodePrompt, Option<&BrowserFallback>), + { + let mut fallback: Option = None; + // 绑定现场的**真计数**（`CallbackServer::bind_counting` 每次调 `TcpListener::bind` 前 +1）： + // 不是「进没进授权码分支」的代理指标——那正是复审 r1 P2-1 变异 D 打穿的地方。 + let listeners = AtomicUsize::new(0); + if self.browser_first { + match authcode::login_checked( + &self.client, + &self.endpoints, + &self.client_id, + self.authcode.clone(), + &listeners, + present_browser, + ) + .await + { + Ok(AuthCodeAttempt::LoggedIn(session)) => { + return Ok(LoginOutcome { + session, + browser: None, + listeners_opened: listeners.load(Ordering::Relaxed), + }) + } + // 跳过：**没绑端口**（预检在绑定之前），计数仍是 0。 + Ok(AuthCodeAttempt::Skipped(note)) => fallback = Some(note), + Err(AuthError::Canceled) => return Err(AuthError::Canceled), + Err(error) => { + self.record_failure("authcode_login", &error); + let reason = if preflight::error_means_unregistered(&error) { + BrowserFallbackReason::RedirectNotRegistered + } else { + BrowserFallbackReason::AttemptFailed + }; + fallback = Some(BrowserFallback::new(reason, error.to_string())); + } + } + } + let grant = + flow::request_device_code(&self.client, &self.endpoints, &self.client_id).await?; + present_device(&grant.prompt, fallback.as_ref()); + let tokens = flow::poll_device_token( + &self.client, + &self.endpoints, + &self.client_id, + &grant, + self.poll, + ) + .await?; + let session = + chain::complete_chain(&self.client, &self.endpoints, tokens, now_ms()).await?; + Ok(LoginOutcome { + session, + browser: fallback, + listeners_opened: listeners.load(Ordering::Relaxed), + }) + } +} diff --git a/crates/core/src/auth/microsoft/mod.rs b/crates/core/src/auth/microsoft/mod.rs new file mode 100644 index 0000000..a3e8753 --- /dev/null +++ b/crates/core/src/auth/microsoft/mod.rs @@ -0,0 +1,400 @@ +//! 微软轨：device-code 与授权码（浏览器）两条登录流 + 会话/刷新语义 +//! （`PlanDoc/07-accounts.md` §1、`analyse/04` §4–§5、`research/08` §3）。 +//! +//! - [`client_id`]：Azure 公共客户端 id 的**配置状态**（来源 / 配没配 / 启动日志那一行，零网络）； +//! - [`session`]：`MicrosoftSession`（凭据载荷）与**刷新判定**（纯函数，可脱离网络单测）； +//! - [`endpoints`] + [`flow`]：端点表与 device-code 发起 / 轮询 / refresh（OAuth 层）； +//! - [`authcode`] + [`callback`] + [`preflight`] + [`login`]：授权码流（授权 URL + 本地回调 + +//! 回环注册预检 + 回退设备码的编排）； +//! - [`chain`]：XBL → XSTS → login_with_xbox → entitlements → profile（Xbox/MC 层）。 +//! +//! 两条流只差「怎么拿到 MS access_token」：拿到之后都进同一个 [`chain::complete_chain`]， +//! 落盘/刷新也共用 [`MicrosoftSession`]，所以 GUI 账户页的两颗按钮不会长出两套凭据语义。 +//! # 默认走哪条（M178） +//! +//! **设备码是默认**，授权码是可选加速路：授权码流要求应用注册里登记回环重定向 URI +//! （`http://localhost/auth`，端口由微软忽略），而本项目的注册当初只为 device-code 而建。 +//! 没登记时授权端点当场拒掉且**不**把浏览器送回本地回调，用户只看到 +//! `invalid_request ... 'redirect_uri' is not valid` 那张 AAD 原始错误页。所以： +//! +//! | 入口 | 走什么 | +//! |---|---| +//! | [`MicrosoftAuth::device_code_login`] | 设备码，**一个监听口都不开** | +//! | [`MicrosoftAuth::browser_then_device_login`] | 先预检回环注册：没登记就直接设备码；登记了走授权码，失败回退设备码 | +//! | [`MicrosoftAuth::authcode_login`] | 强制授权码（测试/排障用，不做预检） | +//! +//! # client id 从哪来 +//! +//! 两条流都必须带一个**已在 Azure 注册的公共客户端 id**（租户必须是 `consumers`）。 +//! 授权码流额外要求注册里登记过回环重定向 URI（`http://localhost/auth`，端口不参与匹配； +//! 见 [`login`] 引的微软官方原文）。id 与 HMCL 同款模型：二进制里不硬编码， +//! 改由 `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 login; +pub mod preflight; + +pub mod session; + +pub use authcode::{AuthCodePolicy, AuthCodePrompt, RedirectUri}; +pub use callback::CallbackServer; +// 回环重定向 URI 的注册预检（M178）：`RedirectRegistration` 是宿主排障时唯一要看的结论。 +pub use preflight::{RedirectRegistration, PROBE_PORT}; +// 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 login::{BrowserFallback, BrowserFallbackReason, LoginOutcome}; +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, + browser_first: bool, + journal: Option, +} + +impl MicrosoftAuth { + /// 按显式 client id 构造（HTTP 基座复用 `core::download` 的客户端构造）。 + /// + /// # Errors + /// + /// HTTP 客户端建不起来时返回 [`AuthError::Network`]。 + pub fn new(client_id: impl Into) -> AuthResult { + 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(), + browser_first: false, + 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 { + 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) -> 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 + } + + /// 「浏览器优先」（M178）：授权码流只是**可选加速路**，默认不走。 + /// + /// 只有宿主确认用户显式要求时才置位（GUI 的「用浏览器登录」按钮）。置位后仍然先做 + /// 回环注册预检（[`preflight`]）：没登记就**不绑端口、不弹浏览器**，直接设备码。 + #[must_use] + pub fn with_browser_first(mut self, enabled: bool) -> Self { + self.browser_first = enabled; + self + } + + /// 是否允许尝试浏览器（授权码）流。 + #[must_use] + pub fn browser_first(&self) -> bool { + self.browser_first + } + + /// 当前端点表。 + #[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(&self, mut present: F) -> AuthResult + 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 { + 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(&self, present: F) -> AuthResult + 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 { + 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 { + 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 { + 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)> { + 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")); + // 默认**不是**浏览器优先（M178：设备码才是默认路）。 + assert!(!auth.browser_first()); + } + + #[test] + fn now_ms_is_sane() { + // 2020-01-01 之后、2100 之前（防止本地时钟/单位抄错）。 + let now = now_ms(); + assert!(now > 1_577_836_800_000 && now < 4_102_444_800_000); + } +} diff --git a/crates/core/src/auth/microsoft/preflight.rs b/crates/core/src/auth/microsoft/preflight.rs new file mode 100644 index 0000000..f2ef0c6 --- /dev/null +++ b/crates/core/src/auth/microsoft/preflight.rs @@ -0,0 +1,340 @@ +//! 授权码流的「回环重定向 URI 注册预检」（M178）。 +//! +//! ## 为什么需要预检 +//! +//! 授权码流把浏览器送回 `http://localhost:{port}/auth`。**随机端口**只有在「回环 URI 的 +//! 端口不参与匹配」这件事成立时才可能被接受——微软官方文档写得很清楚 +//! （[*Redirect URI (reply URL) best practices and limitations*](https://learn.microsoft.com/en-us/entra/identity-platform/reply-url)， +//! 小节 *Localhost exceptions*）： +//! +//! > "Due to ephemeral port ranges often required by native applications, the port component +//! > (for example, :5001 or :443) is ignored for the purposes of matching a localhost redirect URI. +//! > As a result, all of these URIs are considered equivalent: `http://localhost/MyApp`, +//! > `http://localhost:1234/MyApp`, `http://localhost:5000/MyApp`, `http://localhost:8080/MyApp`" +//! +//! 换句话说：**注册一次 `http://localhost/auth` 就能接住任意端口**；但**一次都没注册**时， +//! 任何端口的回环 URI 都会被授权端点当场拒掉（`invalid_request: ... 'redirect_uri' is not valid`）， +//! 而且**不会**再跳回本地回调——用户只在浏览器里看到一张 AAD 错误页，启动器只能干等超时。 +//! 本项目的 Azure 应用注册当初是为 device-code 建的，重定向 URI 一项都没登记 +//! （`DevDocs/ops/azure-msa-app.md`），所以这条流在官方产物上必然失败。 +//! +//! ## 预检做什么、不做什么 +//! +//! 做：拿**即将使用的那个** `redirect_uri`（只有端口可以是任意的，所以用固定探测端口拼形状） +//! 去授权端点发一次**不带凭据的 GET**，看它是否当场报 `invalid_request` / `AADSTS50011`。 +//! 不注册 → 不绑本地端口、不弹浏览器，直接回退设备码。这样「没登记回调地址」的机器上 +//! 监听口一次都不开（守卫断言 `LoginOutcome::listeners_opened == 0`，那个数是 +//! [`super::callback::CallbackServer::bind_counting`] 在 `TcpListener::bind` 现场加的）。 +//! +//! 不做：预检失败**不等于**登录被拒——它只决定「要不要试浏览器」。 +//! `Unknown`（网络问题/整体超时）同样按「别试」处理：设备码流不依赖任何注册项，永远更稳。 +//! 整次预检有 [`PREFLIGHT_TIMEOUT`] 的上限：服务器接了连接却不出响应时，不能让「浏览器登录」 +//! 按钮把界面卡在 Requesting（取消按钮只收面板、停不掉已经跑起来的线程）。 + +use reqwest::Client; + +use crate::auth::error::AuthError; + +use super::authcode::{authorization_url, RedirectUri}; +use super::endpoints::MicrosoftEndpoints; + +/// 预检用的回环端口。 +/// +/// **不是要绑它**：端口对回环匹配不参与（见模块文档引的那段官方原文），所以随便一个 +/// 「看起来像临时端口」的值就能代表真实绑定后的那个。固定值让日志与测试可复现。 +pub const PROBE_PORT: u16 = 53_691; + +/// 预检请求里的 `state`（不参与任何校验，只为拼出形状完整的授权 URL）。 +const PROBE_STATE: &str = "ull-redirect-probe"; + +/// 整次预检的时间上限（复审 r1 P2-2）。 +/// +/// 为什么必须有：下载引擎那个 HTTP 客户端只设了 `connect_timeout`（10s），**没有**整体超时 +/// ——`read_timeout` 从未应用到 reqwest 客户端。授权端点接了连接却不出响应（或 header 后停住）时， +/// 这一次「用浏览器登录」会把界面卡在 Requesting，而取消按钮只收面板、停不掉已经跑起来的线程。 +/// 超时按 [`RedirectRegistration::Unknown`] 处理：回退设备码，原因码「没确认」。 +pub const PREFLIGHT_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(10); + +/// 授权端点对 `redirect_uri` 的态度。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum RedirectRegistration { + /// 注册里有这个回环 URI（端口随意）→ 可以真的走授权码流。 + Registered, + /// 明确没登记（`invalid_request` / `AADSTS50011`）→ 别试，直接设备码。 + NotRegistered { + /// 诊断原文（只进日志） + detail: String, + }, + /// 问不出来（网络/超时/非预期应答）→ 同样不试，但原因是「没确认」而不是「没配」。 + Unknown { + /// 诊断原文（只进日志） + detail: String, + }, +} + +impl RedirectRegistration { + /// 是否值得继续走授权码流。 + #[must_use] + pub fn is_registered(&self) -> bool { + matches!(self, Self::Registered) + } +} + +/// 预检：注册里有没有这个回环重定向 URI。 +/// +/// 判据（顺序即优先级）： +/// 1. 应答里出现 `invalid_request` / `AADSTS50011` / `redirect_uri is not valid` 一类字样 → 没登记； +/// 2. 非 2xx/3xx → 按「没登记」处理（AAD 对不合法的 redirect_uri 直接渲染错误页，状态码 400）； +/// 3. 其余 2xx/3xx 且没有拒绝字样 → 认为已登记（那就是登录页本身）； +/// 4. 连不上 → `Unknown`。 +/// +/// 阅读提示：这条判据**宁可错杀**——错过一次浏览器登录只是慢一步，误放行会让用户撞上 +/// AAD 的原始错误页，而那正是本 mission 要消灭的现象。 +pub(super) async fn check( + client: &Client, + endpoints: &MicrosoftEndpoints, + client_id: &str, + redirect_uri: &RedirectUri, +) -> RedirectRegistration { + check_with_deadline( + client, + endpoints, + client_id, + redirect_uri, + PREFLIGHT_TIMEOUT, + ) + .await +} + +/// [`check`] 的可注入 deadline 版本（单测用短 deadline，不必等 10 秒）。 +pub(super) async fn check_with_deadline( + client: &Client, + endpoints: &MicrosoftEndpoints, + client_id: &str, + redirect_uri: &RedirectUri, + deadline: std::time::Duration, +) -> RedirectRegistration { + match tokio::time::timeout(deadline, probe(client, endpoints, client_id, redirect_uri)).await { + Ok(verdict) => verdict, + Err(_) => RedirectRegistration::Unknown { + detail: format!( + "预检 {} 毫秒内没有结论，按「没确认」处理", + deadline.as_millis() + ), + }, + } +} + +/// 真正的预检请求（不含超时；由 [`check_with_deadline`] 套 deadline）。 +async fn probe( + client: &Client, + endpoints: &MicrosoftEndpoints, + client_id: &str, + redirect_uri: &RedirectUri, +) -> RedirectRegistration { + let url = authorization_url(endpoints, client_id, redirect_uri, PROBE_STATE); + let response = client.get(&url).send().await; + let response = match response { + Ok(response) => response, + Err(error) => { + return RedirectRegistration::Unknown { + detail: format!("预检请求失败：{error}"), + } + } + }; + let status = response.status().as_u16(); + // 登录页可能带上几十上百 KB 的脚本；拒绝页只有一小段。读整页是为了抓正文里的错误码， + // reqwest 的 `text()` 会把正文一次读尽（授权页不含任何凭据，不需要脱敏）。 + let body = response.text().await.unwrap_or_default(); + if rejects_redirect_uri(&body) { + return RedirectRegistration::NotRegistered { + detail: format!("HTTP {status}：{}", snippet(&body)), + }; + } + if !(200..400).contains(&status) { + return RedirectRegistration::NotRegistered { + detail: format!("HTTP {status}：{}", snippet(&body)), + }; + } + RedirectRegistration::Registered +} + +/// 这个错误是不是「重定向 URI 没登记」那一类（`AuthError` 侧重判，回调/换 token 用）。 +/// +/// 与 [`rejects_redirect_uri`] 同源：一个看页面正文，一个看结构化错误。两者都覆盖 +/// `invalid_request` 与 `AADSTS50011`，因为同一件事在两条流上的形状不一样。 +#[must_use] +pub(super) fn error_means_unregistered(error: &AuthError) -> bool { + match error { + AuthError::Denied { code, description } => { + is_redirect_code(code) || redirects_rejected(description) + } + AuthError::Response(detail) => { + redirects_rejected(detail.server_message.as_deref().unwrap_or_default()) + || redirects_rejected(detail.digest.as_str()) + } + _ => false, + } +} + +fn is_redirect_code(code: &str) -> bool { + matches!( + code, + "invalid_request" + | "invalid_redirect_uri" + | "redirect_uri_mismatch" + | "unauthorized_client" + ) +} + +fn redirects_rejected(text: &str) -> bool { + let lowered = text.to_lowercase(); + lowered.contains("aadsts50011") + || lowered.contains("invalid_request") + || lowered.contains("redirect_uri is not valid") + || lowered.contains("redirect_uri+is+not+valid") + || lowered.contains("reply url specified in the request does not match") + || (lowered.contains("redirect") && lowered.contains("not valid")) +} + +/// 页面正文里有没有「重定向 URI 不合法」的拒绝标记。 +fn rejects_redirect_uri(body: &str) -> bool { + let lowered = body.to_lowercase(); + lowered.contains("aadsts50011") + || lowered.contains("invalid_request") + || lowered.contains("redirect_uri is not valid") + || lowered.contains("redirect_uri+is+not+valid") + || (lowered.contains("redirect") && lowered.contains("not valid")) +} + +/// 正文摘要（单行、截断）：只进日志，不上屏。 +fn snippet(body: &str) -> String { + let one_line: String = body + .chars() + .map(|c| if c.is_control() { ' ' } else { c }) + .collect(); + let collapsed = one_line.split_whitespace().collect::>().join(" "); + match collapsed.char_indices().nth(200) { + Some((index, _)) => format!("{}…", &collapsed[..index]), + None => collapsed, + } +} + +#[cfg(test)] +mod tests { + use super::{ + check_with_deadline, error_means_unregistered, rejects_redirect_uri, snippet, + RedirectRegistration, + }; + use crate::auth::body::ResponseDetail; + use crate::auth::error::AuthError; + use crate::auth::microsoft::{MicrosoftEndpoints, RedirectUri}; + + /// 用户 2026-11-08 实测的那张错误页（原文截取）必须被判成「没登记」。 + #[test] + fn the_reported_aad_page_is_recognized_as_unregistered() { + let page = "error=invalid_request&error_description=The+provided+value+for+the+input+\ +parameter+%27redirect_uri%27+is+not+valid.+The+expected+value+is+a+URI+which+matches+a+\ +redirect+URI+registered+for+this+client+application."; + assert!(rejects_redirect_uri(page)); + // 登录页本身（有脚本、有表单）不能被误判成拒绝。 + assert!(!rejects_redirect_uri( + "Sign in to your account..." + )); + } + + #[test] + fn aadsts50011_is_also_a_registration_problem() { + assert!(rejects_redirect_uri( + "AADSTS50011: The redirect URI 'http://localhost:61492/auth' specified in the request does not match" + )); + } + + /// 两条流上的同一件事：授权页拒绝（`Denied`）与 token 端点拒绝（`Response`）都要认。 + #[test] + fn structured_errors_of_both_shapes_are_recognized() { + assert!(error_means_unregistered(&AuthError::Denied { + code: "invalid_request".to_string(), + description: "bad redirect".to_string(), + })); + assert!(error_means_unregistered(&AuthError::Response(Box::new( + ResponseDetail { + step: "token".to_string(), + what: "换 token".to_string(), + status: 400, + content_type: None, + kind: crate::auth::BodyKind::Json, + server_message: Some("AADSTS50011: reply url mismatch".to_string()), + digest: "digest".to_string(), + } + )))); + // 不相干的失败不是注册问题（别把网络/白名单也归到这条）。 + assert!(!error_means_unregistered(&AuthError::Canceled)); + } + + #[test] + fn registration_state_is_answered_by_one_predicate() { + assert!(RedirectRegistration::Registered.is_registered()); + assert!(!RedirectRegistration::NotRegistered { + detail: String::new() + } + .is_registered()); + assert!(!RedirectRegistration::Unknown { + detail: String::new() + } + .is_registered()); + } + + /// **复审 r1 P2-2**：服务器接了连接却永不出响应时，预检必须靠**整体 deadline** 收场 + /// （不是 connect_timeout：连接早就建好了），结论是「没确认」⇒ 上层回退设备码。 + /// + /// 抓得住：把 `tokio::time::timeout` 去掉（那条路会一直挂着，本用例在 deadline 后 + /// 断言超时不出来，必然失败）。 + /// 抓不住：真机上网关的其它卡法（这里只有一个「不回字」的假服务器）。 + #[tokio::test] + async fn a_silent_authorize_server_hits_the_overall_deadline() { + // 假授权端点：accept 之后一个字节都不写（connect 成功、读永远等不到）。 + let silent = tokio::net::TcpListener::bind(("127.0.0.1", 0)) + .await + .expect("假服务器起不来"); + let port = silent.local_addr().expect("地址").port(); + tokio::spawn(async move { + let mut held = Vec::new(); + loop { + let Ok((stream, _)) = silent.accept().await else { + break; + }; + held.push(stream); + } + }); + + let client = + crate::download::http::build_client(&crate::download::config::EngineConfig::default()) + .expect("HTTP 客户端"); + let mut endpoints = MicrosoftEndpoints::all_on("http://127.0.0.1:1"); + endpoints.authorize = format!("http://127.0.0.1:{port}/authorize"); + let verdict = check_with_deadline( + &client, + &endpoints, + "test-client-id", + &RedirectUri::new(53_691), + std::time::Duration::from_millis(200), + ) + .await; + match verdict { + RedirectRegistration::Unknown { detail } => { + assert!(detail.contains("200"), "文案要带 deadline：{detail}"); + } + other => panic!("静默服务器必须走 Unknown，实际 {other:?}"), + } + } + + #[test] + fn snippet_is_single_line_and_capped() { + let long = format!("a\nb\t{}", "x".repeat(400)); + let text = snippet(&long); + assert!(!text.contains('\n'), "{text}"); + assert!(text.ends_with('…'), "{text}"); + assert_eq!(text.chars().count(), 201); + } +} 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, +} + +/// 过期判定的结论。 +#[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, + profile_name: impl Into, + access_token: Secret, + refresh_token: Secret, + expires_in_secs: u64, + now_ms: u64, + user_id: Option, + ) -> 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 { + 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` 恒为 ``，取明文只能 `.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 { + 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 { + 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 { + 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 @@ +//! 凭据值包装：**打印出来永远是 ``**。 +//! +//! 依据 `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 = ""; + +/// 一个凭据值（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) -> 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 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) -> 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 = 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) -> 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, + credentials: BTreeMap, + warnings: Vec, +} + +impl AccountStore { + /// 打开（不存在就是空库；坏记录进 warnings）。 + #[must_use] + pub fn open(root: impl Into) -> 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 = 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 { + 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, +) -> 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 { + 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) -> Vec { + let mut accounts = Vec::new(); + let Some(text) = read_to_string(path, warnings) else { + return accounts; + }; + let Ok(value) = serde_json::from_str::(&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, +) -> BTreeMap { + let mut credentials = BTreeMap::new(); + let Some(text) = read_to_string(path, warnings) else { + return credentials; + }; + let Ok(value) = serde_json::from_str::(&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::(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) -> Option { + 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, +} + +impl CollectionContext { + /// 以工作目录构造。 + #[must_use] + pub fn new(run_dir: impl Into) -> 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, + /// 人类可读原因。 + 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, +} + +impl CollectedSources { + /// 空。 + #[must_use] + pub fn new() -> Self { + Self::default() + } + + /// 记一个源文件。 + pub fn push(&mut self, path: impl Into) { + 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, +} + +/// 采集到的全部信号。 +#[derive(Debug, Clone, Default)] +pub struct SignalBundle { + /// 退出信号。 + pub exit: Option, + /// 日志环形缓冲（launch 逐行喂；`latest.log` 兜底也进这里）。 + pub log: LogBuffer, + /// 崩溃报告全文。 + pub crash_report: Option, + /// hs_err 解析结果。 + pub hs_err: Option, + /// 环境快照。 + pub environment: Option, + /// mod 清单。 + pub mods: Vec, + /// 本次采到的源文件。 + pub sources: Vec, +} + +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; +} + +/// 按顺序跑一批采集器，单源失败只记录不中断。 +pub fn collect_all( + collectors: &[&dyn SignalCollector], + ctx: &CollectionContext, +) -> (SignalBundle, Vec) { + 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) -> Self { + Self { + origin, + text: text.into(), + } + } +} + +/// 引擎输入：退出信号 + 若干待匹配文本 +（可选）解析好的 hs_err。 +#[derive(Debug, Clone, Default)] +pub struct DiagnosisInput { + /// 退出信号。 + pub exit: Option, + /// 待匹配文本（按 `SignalOrigin::evidence_rank` 优先取证据）。 + pub haystacks: Vec, + /// 解析好的 `hs_err_pid*.log`（产生内置结论，其摘要也已进 `haystacks`）。 + pub hs_err: Option, +} + +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) { + 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, +} + +impl Diagnoser { + /// 用一组已编译的规则构造。 + #[must_use] + pub fn new(rules: Vec) -> 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::>(); + 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, + offset: usize, +} + +fn scan(rule: &CompiledRule, haystack: &Haystack) -> Option { + 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 { + 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 { + 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 { + 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: ®ex::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) -> (Vec, Vec) { + let suppressers = findings + .iter() + .map(|finding| { + ( + finding.rule_id.clone(), + finding.priority, + finding.suppress.clone(), + ) + }) + .collect::>(); + 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::(); + 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, version: impl Into) -> 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, + /// 版本。 + pub version: Option, + /// jar 文件名（诊断包里给人看）。 + pub file: Option, + /// 是否启用（`.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, + /// 实例 id。 + pub instance_id: Option, + /// 游戏版本。 + pub game_version: Option, + /// 操作系统名（`Windows 10.0.19045`）。 + pub os_name: Option, + /// 架构（`x86_64` / `aarch64`）。 + pub os_arch: Option, + /// 物理内存（MB）。 + pub physical_memory_mb: Option, + /// Java 可执行文件。 + pub java_path: Option, + /// Java 大版本。 + pub java_major: Option, + /// Java 位数（32 / 64）。 + pub java_bits: Option, + /// `-Xmx`（MB）。 + pub xmx_mb: Option, + /// `-Xms`（MB）。 + pub xms_mb: Option, + /// 工作目录（跑游戏的 cwd）。 + pub run_dir: Option, + /// 已装组件版本。 + pub components: Vec, + /// 已装 mod。 + pub mods: Vec, +} + +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) -> Self { + Self { + origin, + line, + text: text.into(), + } + } + + /// 诊断输出里的字符串形式：`": "`。 + #[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, + /// 证据。 + pub evidence: Vec, + /// 六维修复动作。 + pub fix_actions: Vec, + /// 规则捕获组（供动作模板替换）。 + pub groups: BTreeMap, + /// 本结论会抑制哪些规则 id。 + pub suppress: Vec, + /// 被哪条结论抑制（`Some` 即次生结论）。 + pub suppressed_by: Option, +} + +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 { + 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, + /// 证据字符串。 + pub evidence: Vec, + /// 六维修复动作（M16/UI 一键修复入口）。 + pub fix_actions: Vec, +} + +/// 退出信号摘要（诊断输出用）。 +#[derive(Debug, Clone, Serialize)] +pub struct ExitRecord { + /// 退出码。 + #[serde(skip_serializing_if = "Option::is_none")] + pub code: Option, + /// 退出类型（与 launch 约定同值）。 + pub exit_type: &'static str, + /// 疑似静默失败。 + pub silent_failure: bool, + /// 存活毫秒数。 + #[serde(skip_serializing_if = "Option::is_none")] + pub uptime_ms: Option, +} + +/// 交给 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, + /// 被抑制的次生结论。 + pub secondary: Vec, + /// 本次判定用的退出信号摘要。 + #[serde(skip_serializing_if = "Option::is_none")] + pub exit: Option, +} + +/// 一次诊断的完整结果。 +#[derive(Debug, Clone, Default)] +pub struct DiagnosisReport { + /// 结论（已排序，主因在前）。 + pub findings: Vec, + /// 被抑制的次生结论。 + pub secondary: Vec, + /// 本次判定用的退出信号。 + pub exit: Option, + /// 评估了多少条规则（可观测性）。 + pub rules_evaluated: usize, + /// 解析出的 hs_err（若有）。 + pub hs_err: Option, +} + +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 { + let mut out: Vec = 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, +} + +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) -> 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::().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::>(); + 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, groups: &BTreeMap) -> Option { + value.as_ref().map(|text| substitute(text, groups)) +} + +fn put_str(args: &mut BTreeMap, key: &str, value: &str) { + args.insert(key.to_owned(), value.to_owned()); +} + +fn put_opt_str(args: &mut BTreeMap, key: &str, value: Option) { + if let Some(value) = value { + args.insert(key.to_owned(), value); + } +} + +fn put_opt(args: &mut BTreeMap, key: &str, value: Option) { + if let Some(value) = value { + args.insert(key.to_owned(), value.to_string()); + } +} + +fn put_bool(args: &mut BTreeMap, 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 { + 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, + /// 允许的最高大版本（老 Forge 只能用 Java 8 时给 `8`）。 + #[serde(default)] + pub max_major: Option, + /// 从该命名捕获组取 `class file version N`，按 `N - 44` 换算成 Java 大版本。 + #[serde(default)] + pub class_file_version_group: Option, + /// JVM 实现偏好。 + #[serde(default)] + pub vendor: JavaVendor, + /// 给用户看的补充说明。 + #[serde(default)] + pub note: Option, +} + +/// 调内存的参数。 +#[derive(Debug, Clone, PartialEq, Eq, Default, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct AdjustMemory { + /// 建议的 `-Xmx`（MB）；规则不确定时留空，由 UI 按物理内存算。 + #[serde(default)] + pub suggested_xmx_mb: Option, + /// `-Xmx` 的下限（MB）。 + #[serde(default)] + pub min_xmx_mb: Option, + /// 需要 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, +} + +/// 改图形设置的参数。 +#[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, + /// 补充说明。 + #[serde(default)] + pub note: Option, +} + +/// 删/禁/换 mod 的参数。 +#[derive(Debug, Clone, PartialEq, Eq, Default, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct RemoveMod { + /// modid 列表，允许 `{group}` 模板（由规则命名捕获组代入）。 + #[serde(default)] + pub mod_ids: Vec, + /// 处理方式。 + #[serde(default)] + pub action: ModAction, + /// 补充说明。 + #[serde(default)] + pub note: Option, +} + +/// 重装/修组件的参数。 +#[derive(Debug, Clone, PartialEq, Eq, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct Reinstall { + /// 要修的组件。 + pub component: ComponentKind, + /// 出问题的路径提示（来自规则捕获组或原文）。 + #[serde(default)] + pub path_hint: Option, + /// 补充说明。 + #[serde(default)] + pub note: Option, +} + +/// 求助/上报的参数。 +#[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, + /// 补充说明。 + #[serde(default)] + pub note: Option, +} 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::>(); + + 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::().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::().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) -> io::Result { + 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 { + 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 { + 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 { + 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 { + 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, Option) { + let numbers = part + .split(|ch: char| !ch.is_ascii_digit()) + .filter(|token| !token.is_empty()) + .filter_map(|token| token.parse::().ok()) + .collect::>(); + (numbers.first().copied(), numbers.get(1).copied()) +} + +/// 取从 `start` 开始、到第一个空行为止的连续行（VM Arguments / java_command 段）。 +fn collect_unindented(lines: &[&str], start: usize, limit: usize) -> Vec { + 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 { + 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 { + 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::>() + .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, + /// 模块内偏移（`0x9b3c4d`）。 + pub offset: Option, +} + +/// 内存段摘要（`Memory: 4k page, physical …, swap …`）。 +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub struct MemorySummary { + /// 页大小（`4k`）。 + pub page_size: Option, + /// 物理内存 kB。 + pub physical_kb: Option, + /// 物理可用 kB。 + pub physical_free_kb: Option, + /// 交换区 kB。 + pub swap_kb: Option, + /// 交换区可用 kB。 + pub swap_free_kb: Option, + /// 原始行。 + pub raw: String, +} + +impl MemorySummary { + /// 一行人类可读摘要（GB 保留一位小数）。 + #[must_use] + pub fn summary(&self) -> String { + let gb = |kb: Option| { + 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, + /// 标题行（`#[derive(Default)]` 之外的语义见 `parse`）。 + pub header: Option, + /// 崩溃类别。 + pub kind: HsErrKind, + /// 异常名（`EXCEPTION_ACCESS_VIOLATION (0xc0000005)`）。 + pub exception: Option, + /// `siginfo:` 行（Unix 侧带 si_signo / si_addr）。 + pub siginfo: Option, + /// 信号名（`SIGSEGV (0xb)`）。 + pub signal: Option, + /// 出错时的指令指针。 + pub pc: Option, + /// 进程 pid。 + pub pid: Option, + /// 线程 tid（保留原始十六进制/十进制串）。 + pub tid: Option, + /// 失败帧。 + pub failed_frame: Option, + /// 当前线程（`JavaThread "Render thread" [_thread_in_native, id=…]`）。 + pub current_thread: Option, + /// JRE 版本行内容。 + pub jre_version: Option, + /// JVM 实现行内容。 + pub java_vm: Option, + /// 操作系统行内容。 + pub os: Option, + /// `java_command` 行。 + pub command_line: Option, + /// `VM Arguments:` 段的参数行。 + pub vm_arguments: Vec, + /// 内存段摘要。 + pub memory: Option, + /// `Heap:` 段的前几行（原样，含 total/used）。 + pub heap: Vec, + /// 标题块原文（逐行保留 `#` 前缀，规则可以直接在上面匹配）。 + pub header_lines: Vec, +} + +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, +} + +/// 编译好的规则集（字段私有，只能经 loader 构造，保证「id 唯一 + 正则可编译」）。 +#[derive(Debug, Clone, Default)] +pub struct RuleSet { + rules: Vec, +} + +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> { + let mut errors = Vec::new(); + let mut rules: Vec = Vec::new(); + let mut seen: HashSet = HashSet::new(); + for (file, text) in sources { + let parsed = match serde_yaml_ng::from_str::(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, + }, +} + +/// 规则库加载器（持有当前生效的规则集 + 目录指纹）。 +#[derive(Debug, Clone)] +pub struct RuleLoader { + dir: Option, + set: RuleSet, + fingerprint: u64, + last_errors: Vec, +} + +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) -> 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) { + 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) { + 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::>() + }) + .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..bba9a17 --- /dev/null +++ b/crates/core/src/diagnose/mod.rs @@ -0,0 +1,19 @@ +//! 崩溃诊断：五类信号采集（含 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、session 下的 +// session_tests）由各自的父文件用 #[path] 声明。这里**不要**重复声明，否则同一文件会被编译成 +// 两份不同类型。 +pub mod collectors; +pub mod engine; +pub mod hs_err; +pub mod loader; +pub mod rules; +pub mod session; 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: (?(.*)[\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: (?.*) conflicts with (?.*)' + 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: (?.*) requires (?.*)' + 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: (?.*) requires \{minecraft @ (?.*)\}' + 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: (?.*) requires (?.*)\)' + 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]+(?[^\[]+)\[' + 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:(?(.*)[\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:(?(.*)(?:\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 (?.*) at (?.*)' + 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: (?.*?),' + 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 (?.*)|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: (?.*?)' + 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: (?.*)' + 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 (?.*?)' + 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: (?.*)' + 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: (?.*)' + 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 (?\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\.\(java\.util\.jar\.Manifest\)''|sun\.security\.util\.ManifestEntryVerifier\.\(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\.\(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\.\(int\[\], int, net\.minecraft\.core\.Direction, net\.minecraft\.client\.renderer\.texture\.TextureAtlasSprite, boolean, boolean\)'|TRANSFORMER/net\.optifine/net\.optifine\.reflect\.Reflector\.\(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 (?.*?) \((?.*)\)' + 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 '(?.*)'! + 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 (?.*?) of type (.*?) for modid (?.*)' + 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 (?.*) 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)*(?.*(?:\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.(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.(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.(Reflector.java:455) + TRANSFORMER/net.optifine/net.optifine.reflect.Reflector.(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: (?.*)[\\w\\W\\n\\r]*?Entity's Exact 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: (?.*)[\w\W\n\r]*?Block 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/.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, +} + +impl Cause { + /// 代入捕获组后的（结论, 细化说明）。 + #[must_use] + pub fn render(&self, groups: &BTreeMap) -> (String, Option) { + ( + 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` 语法，命名组用 `(?…)`）。 + 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, + /// 结论文案。 + pub cause: Cause, + /// 六维修复动作。 + #[serde(default)] + pub fix_action: Vec, + /// 回归样本路径（相对 `rules.d/`）。 + #[serde(default)] + pub sample: Option, + /// 出处（HMCL 枚举名 / issue 链接）。 + #[serde(default)] + pub source: Option, +} + +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 { + 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 { + 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/session.rs b/crates/core/src/diagnose/session.rs new file mode 100644 index 0000000..0927c09 --- /dev/null +++ b/crates/core/src/diagnose/session.rs @@ -0,0 +1,85 @@ +//! 会话收尾的规则结论：**在原始行还热着的时候**算一次（M241）。 +//! +//! ## 为什么不能等读回 JSONL 再算 +//! +//! 会话事件流是「写前先脱敏」的（[`crate::launch::redact`]，`落盘即脱敏`），而脱敏的两条 +//! 形状规则是**有损**的：`≥64` 无点号不透明串、带点 token。于是「读回 JSONL → 喂规则引擎」 +//! 这条路看到的不是游戏说的话，而是**被抹过的**游戏说的话。M239 实测：`fabric.loader_0_12` +//! （critical / priority 80）的唯一证据行 +//! `java.lang.NoClassDefFoundError: org/spongepowered/…/FabricMixinTransformerProxy` +//! 里的类路径 66 字符、无点号，正好撞上 `≥64` 那条规则 → 变成 `` → +//! 规则在会话路上**永不命中**。 +//! +//! ## 分工（`DevDocs/SubAgentsTalk/launch-接口约定.md` §3） +//! +//! 「launch 报事实、M15 下结论」没有变：launch 把**原始事实**（退出码、存活时长、原始 +//! stdout/stderr 尾窗）交过来，结论在 `diagnose` 里算，产出的就是 `diagnosis` 事件的 +//! payload（[`DiagnosisReport::to_record`]）。落盘仍然只留**已脱敏**的结论：写会话的 +//! `SessionWriter::diagnosis` 会再走一遍 `Redactor::scrub_json`。 +//! +//! 换句话说：**原始文本只活在内存里**，盘上永远只有脱敏文本——不是「再存一份原文」。 + +use serde_json::Value; + +use crate::diagnose::collectors::{ExitSignal, SignalOrigin}; +use crate::diagnose::engine::{Diagnoser, DiagnosisInput}; +use crate::diagnose::loader::RuleLoader; + +/// 会话收尾时交给规则引擎的**原始**事实（未脱敏，只在本进程内存里）。 +#[derive(Debug, Clone, Copy)] +pub struct RawFacts<'a> { + /// 退出码（`None` = 没有退出判定）。 + pub exit_code: Option, + /// 进程存活毫秒数。 + pub duration_ms: u64, + /// 全量错误行数（不受尾窗影响）。 + pub error_lines: u32, + /// 原始 stdout 尾窗（按时间顺序）。 + pub stdout: &'a [String], + /// 原始 stderr 尾窗（按时间顺序）。 + pub stderr: &'a [String], +} + +impl RawFacts<'_> { + /// 有没有任何可匹配的文本。 + fn has_text(&self) -> bool { + !self.stdout.is_empty() || !self.stderr.is_empty() + } +} + +/// 跑一遍规则引擎，返回 `diagnosis` 事件的 payload；没有结论时返回 `None`。 +/// +/// 返回 `None` 的两种情况都**不写事件**：没有任何文本可匹配（无从判断），或规则引擎没认出 +/// 已知问题（此时读回 JSONL 的那条兜底路径看到的是同一份证据，重跑也是空手）。 +#[must_use] +pub fn conclude(facts: &RawFacts<'_>) -> Option { + if !facts.has_text() { + return None; + } + let stderr_text = facts.stderr.join("\n"); + let exit = ExitSignal::classify( + facts.exit_code, + Some(facts.duration_ms), + facts.error_lines, + &stderr_text, + ); + let mut input = DiagnosisInput::new().with_exit(exit); + if !facts.stdout.is_empty() { + input.push_text(SignalOrigin::Stdout, facts.stdout.join("\n")); + } + if !facts.stderr.is_empty() { + input.push_text(SignalOrigin::Stderr, facts.stderr.join("\n")); + } + let report = Diagnoser::new(rules()).analyze(&input); + report.primary()?; + serde_json::to_value(report.to_record()).ok() +} + +/// 内嵌规则集编译一次的那份规则（每次重新取；`RuleLoader` 自带缓存语义）。 +fn rules() -> Vec { + RuleLoader::embedded().rule_set().rules().to_vec() +} + +#[cfg(test)] +#[path = "session_tests.rs"] +mod tests; diff --git a/crates/core/src/diagnose/session_tests.rs b/crates/core/src/diagnose/session_tests.rs new file mode 100644 index 0000000..540eff1 --- /dev/null +++ b/crates/core/src/diagnose/session_tests.rs @@ -0,0 +1,98 @@ +//! `diagnose::session` 的单测（拆文件守 400 行上限）。 + +use super::*; +use crate::launch::redact::Redactor; + +/// `fabric.loader_0_12`（critical / priority 80）在 `rules.d/fabric.yaml` 里的唯一证据行。 +const EVIDENCE: &str = "java.lang.NoClassDefFoundError: \ + org/spongepowered/asm/mixin/transformer/FabricMixinTransformerProxy"; + +fn facts<'a>(stdout: &'a [String], stderr: &'a [String]) -> RawFacts<'a> { + RawFacts { + exit_code: Some(1), + duration_ms: 4_200, + error_lines: 2, + stdout, + stderr, + } +} + +fn record_id(record: &Value) -> Option<&str> { + record + .get("candidates") + .and_then(Value::as_array) + .and_then(|items| items.first()) + .and_then(|item| item.get("id")) + .and_then(Value::as_str) +} + +/// **判据 ①**：原始证据行能命中 `fabric.loader_0_12`；M240 收窄脱敏之后，同一行在脱敏文本里**也**能命中。 +/// +/// 这半边在 M240 之前是「命不中」（那是 M239 报的 bug）。M240 把词形长路径从「不透明串」里放了出来， +/// 于是这条证据不再被抹——**证据能留在盘上正是 M240 的目的**，所以这里改成断言「两边都能命中」。 +/// 原始窗口（`RawWindow`）对「证据本身含凭据、被迫抹掉」的行依然必需，但那种行需要一条 +/// 真的依赖凭据字面量的规则才能演示，本仓当前没有这样的规则。 +#[test] +fn raw_evidence_hits_the_fabric_rule_and_m240_keeps_it_visible_after_scrubbing() { + let raw = [EVIDENCE.to_string()]; + let empty: [String; 0] = []; + + let record = conclude(&facts(&empty, &raw)).expect("原始证据应当有结论"); + assert_eq!(record_id(&record), Some("fabric.loader_0_12"), "{record}"); + assert_eq!(record["source"], serde_json::json!("rules")); + assert_eq!(record["needs_more_info"], serde_json::json!(false)); + + let scrubbed = [Redactor::new().scrub(EVIDENCE).into_owned()]; + assert!( + !scrubbed[0].contains(""), + "夹具前提（M240 之后）：词形长路径不再被抹成不透明串：{}", + scrubbed[0] + ); + assert!( + scrubbed[0].contains("FabricMixinTransformerProxy"), + "夹具前提：类名应原样留在脱敏文本里：{}", + scrubbed[0] + ); + let after = conclude(&facts(&empty, &scrubbed)); + assert_eq!( + after.as_ref().and_then(record_id), + Some("fabric.loader_0_12"), + "M240 之后脱敏文本也能命中；若这条变红，说明长类名又被抹了——那时请改用 raw 窗口的用例重新说明它为什么必要" + ); +} + +/// 没有文本就没有结论（不写空事件）。 +#[test] +fn no_text_means_no_conclusion() { + let empty: [String; 0] = []; + assert!(conclude(&facts(&empty, &empty)).is_none()); +} + +/// 认不出来的日志也不写事件（让读回 JSONL 的兜底路径去跑，避免两条路给出不同结论）。 +#[test] +fn unrecognized_output_means_no_conclusion() { + let stdout = ["[12:00:00] [main/INFO]: Setting user".to_string()]; + let empty: [String; 0] = []; + assert!(conclude(&facts(&stdout, &empty)).is_none()); +} + +/// 结论里带的是**已渲染**的文案与物化动作，展示侧不必再自己拼。 +#[test] +fn the_record_carries_rendered_text_and_actions() { + let raw = ["Fabric loader failed".to_string(), EVIDENCE.to_string()]; + let empty: [String; 0] = []; + let record = conclude(&facts(&empty, &raw)).expect("应有结论"); + let candidate = &record["candidates"][0]; + assert!(!candidate["message"].as_str().unwrap_or_default().is_empty()); + assert_eq!( + candidate["fix_actions"][0]["kind"], + serde_json::json!("reinstall") + ); + assert!( + candidate["evidence"][0] + .as_str() + .unwrap_or_default() + .contains("NoClassDefFoundError"), + "{candidate}" + ); +} 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) -> 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, + /// 已从环形区淘汰、但因为是关键行而留下来的行（按时间顺序）。 + kept: VecDeque, + 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, + { + for line in lines { + self.push(origin, line); + } + } + + /// 按时间顺序返回全部保留行（关键行历史在前，最近 N 行在后）。 + pub fn lines(&self) -> impl Iterator { + 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, + /// 退出类型。 + pub exit_type: ExitType, + /// 进程存活毫秒数。 + pub uptime_ms: Option, + /// stderr/错误行条数。 + pub error_lines: u32, + /// 退出码 0 但疑似静默失败（存活 <30s 或 stderr 有错误特征）。 + pub silent_failure: bool, + /// Windows 状态码原始串（`0xc0000005`）。 + pub windows_status: Option, + /// 命中的崩溃关键字。 + pub crash_keywords: Vec, +} + +impl ExitSignal { + /// 从原始退出事实推断类型（离线诊断 / 导入日志用；launch 侧有权威版本）。 + #[must_use] + pub fn classify( + code: Option, + uptime_ms: Option, + 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 { + 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 { + // 只有 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 { + 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 { + 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, +} + +impl CrashReportCollector { + /// 默认扫 `/crash-reports`。 + #[must_use] + pub fn new() -> Self { + Self::default() + } + + /// 指定目录。 + #[must_use] + pub fn with_dir(dir: impl Into) -> 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 { + 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, +} + +impl HsErrCollector { + /// 默认扫 ``（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) -> 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 { + let dirs = if self.dirs.is_empty() { + vec![ctx.run_dir.clone()] + } else { + self.dirs.clone() + }; + let mut newest: Option = 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(¤t), 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, + max_lines: usize, +} + +impl Default for LatestLogCollector { + fn default() -> Self { + Self::new() + } +} + +impl LatestLogCollector { + /// 默认读 `/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) -> 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 { + 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::>(); + 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, + matches: impl Fn(&str) -> bool, +) -> Option { + 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 { + fs::metadata(path).ok()?.modified().ok() +} + +fn read_lossy(kind: SignalKind, path: &Path) -> Result { + 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 { + 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 { + 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 { + 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/` 逐个打点： +//! +//! | 镜像 | 结果 | +//! | --- | --- | +//! | 清华 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`：留着当「将来恢复」的登记， +//! 但不让它们每次安装都白跑一趟（健康度虽然会冷却，首轮仍要付代价）。 +//! **判可用性别只看状态码**：真仓库目录页含 `
`，门户兜底页没有——状态码 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 {
+        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 {
+    let filename = url.rsplit('/').next()?;
+    if filename.is_empty()
+        || (!filename.contains("OpenJDK") && !filename.contains("jdk") && !filename.contains("jre"))
+    {
+        return None;
+    }
+    let mut major: Option = 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`。
+//!
+//! # 中间文件的身份
+//!
+//! 中间文件名是 `.ullpart--`：`session` 是进程号，`seq` 是进程内
+//! 自增序号（一个 `PartFile` 一个）。旧版命名只由目标路径决定（`.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};
+
+/// 下载中间文件后缀（中间文件家族的前缀：`.ullpart` 或 `.ullpart--`）。
+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> {
+    static LIVE: OnceLock>> = 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 {
+    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::().ok()?;
+    pieces.next()?.parse::().ok()?;
+    if pieces.next().is_some() {
+        return None;
+    }
+    Some(Owner::Session(session))
+}
+
+/// 本次会话的中间文件路径：`.ullpart--`。
+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,
+    /// 本目标的全部中间文件副本（含被收养者）。
+    leftovers: Vec<(PathBuf, Owner, Duration)>,
+    /// 无主且超龄的孤儿。
+    orphans: Vec,
+}
+
+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 = 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 {
+        ensure_parent(&self.path)?;
+        OpenOptions::new()
+            .create(true)
+            .append(true)
+            .open(&self.path)
+    }
+
+    /// 以截断方式打开（从头下载）。
+    pub fn open_truncate(&self) -> io::Result {
+        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);
+    }
+}
+
+/// 原子写小文件：`.tmp--` → `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..4f83992
--- /dev/null
+++ b/crates/core/src/download/blocking.rs
@@ -0,0 +1,111 @@
+//! 同步桥：让**非 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 { /* 规划 + 下载 */ });
+//! ```
+//!
+//! # 一句话约定（M165 起）
+//!
+//! **整个进程只有一个运行时**，所有 [`block_on`] 都跑在它上面。理由两条，都是实测口径：
+//!
+//! 1. **连接池绑在运行时上**。`reqwest` 的连接池条目由驱动连接的运行时任务持有：运行时一销毁，
+//!    池里的空闲连接就全成了尸体。M165 之前每次 `block_on` 现建一个临时运行时，于是下载引擎
+//!    的连接池**跨请求根本留不住**（每次重新 TCP + TLS）；引擎复用（[`super::shared`]）与
+//!    运行时常驻必须成对出现，只做一半会退化成「复用一个装着死连接的池」。
+//! 2. **建运行时就是起线程**。每个请求建一次 = 每次多起两个线程，再各自销毁。
+//!
+//! 调用形状不变：把**一整段**流程包在一次 `block_on` 里仍然是对的（同一个 future 里少切几次
+//! 上下文，也少几次许可申请/释放）；只是这几次调用现在落在同一个运行时上，不再互相孤立。
+//!
+//! # 仍然不能嵌套
+//!
+//! 在已有异步上下文里调 [`block_on`] 会 panic（tokio 的硬规则）。这条与 M165 之前一致。
+
+use std::future::Future;
+use std::sync::OnceLock;
+
+/// 共享运行时的 worker 数。
+///
+/// 下载流程里有真实的同步 I/O（`PartFile` 落盘、`write_atomic` 写索引/健康度），它们跑在
+/// worker 线程上；M165 之前每个请求自带 2 个 worker，现在这些请求共用同一池，所以按机器并行度
+/// 给一点余量（下限 2 保证单核机器也够驱动，上限 8 免得为一个启动器起一船线程）。
+fn workers() -> usize {
+    std::thread::available_parallelism()
+        .map_or(2, std::num::NonZeroUsize::get)
+        .clamp(2, 8)
+}
+
+/// 进程内唯一的阻塞桥运行时（第一次 [`block_on`] 时创建，之后一直活着）。
+///
+/// 故意不实现关闭：它的生命周期就是进程的生命周期。静态量不会被 drop，因此进程退出时
+/// 也不会去等它「优雅停机」（那正是短命运行时被销毁时的开销）。
+fn bridge() -> &'static tokio::runtime::Runtime {
+    static BRIDGE: OnceLock = OnceLock::new();
+    BRIDGE.get_or_init(|| {
+        tokio::runtime::Builder::new_multi_thread()
+            .worker_threads(workers())
+            .thread_name("ull-blocking")
+            .enable_all()
+            .build()
+            .expect("创建 tokio 运行时失败（内存/线程资源不足）")
+    })
+}
+
+/// 在进程共享的多线程运行时上跑完 `future`（阻塞当前线程）。
+///
+/// 多个线程可以同时调用：它们在同一个运行时上各自阻塞自己的线程，任务在同一个 worker 池里跑，
+/// 于是连接池、限流、健康度这些「跟运行时/引擎绑在一起」的东西真的能跨调用复用。
+///
+/// # Panics
+///
+/// 运行时建不起来（系统资源耗尽）时 panic：此时进程已无法继续，早点暴露比静默降级好。
+/// 在已有 tokio 运行时上下文里调用同样会 panic（tokio 不允许嵌套 `block_on`）。
+pub fn block_on(future: F) -> F::Output {
+    bridge().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));
+    }
+
+    /// 共享运行时能被多个线程同时驱动（宿主侧就是多线程并行发请求）。
+    #[test]
+    fn shared_runtime_serves_concurrent_callers() {
+        let threads: Vec<_> = (0..4)
+            .map(|index| {
+                std::thread::spawn(move || {
+                    block_on(async move {
+                        tokio::time::sleep(std::time::Duration::from_millis(5)).await;
+                        index
+                    })
+                })
+            })
+            .collect();
+        let mut seen: Vec = threads
+            .into_iter()
+            .map(|handle| handle.join().expect("线程不该 panic"))
+            .collect();
+        seen.sort_unstable();
+        assert_eq!(seen, vec![0, 1, 2, 3]);
+    }
+}
diff --git a/crates/core/src/download/bytes.rs b/crates/core/src/download/bytes.rs
new file mode 100644
index 0000000..f405402
--- /dev/null
+++ b/crates/core/src/download/bytes.rs
@@ -0,0 +1,145 @@
+//! 内存下载：版本清单 / 版本 JSON / 资源索引这类「小文本」资源。
+//!
+//! 与文件下载共用候选源、退避与健康度逻辑，但不续传、不分块——它们要么很小，
+//! 要么强时效（`ETag` 语义比续传更合适）。
+
+use std::time::Instant;
+
+use super::cache::now_ms;
+use super::engine::{millis, DownloadEngine};
+use super::error::{leaf_of, 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, 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 = Vec::new();
+        // 逐源的叶子分类（出去时汇总成一条，见 `DownloadError::leaf`）。
+        let mut kinds: Vec = 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(),
+                            kind: err.kind,
+                            reason: err.message.clone(),
+                            attempt,
+                            will_retry: retry,
+                            retry_in_ms: if retry { millis(delay) } else { 0 },
+                        });
+                        if !retry {
+                            kinds.push(err.kind);
+                            suppressed.push(format!("{}: {}", candidate.source, err.message));
+                            break;
+                        }
+                        tokio::time::sleep(delay).await;
+                    }
+                }
+            }
+        }
+
+        self.flush_health();
+        // 叶子成因要跟着出去：上层（在线内容源的 `Transport`）靠它区分「这个 URL 不存在」
+        // 与「没联网」，只留 `AllSourcesFailed` 的话那套分类在生产路径上永远不可达。
+        Err(DownloadError::new(
+            DownloadErrorKind::AllSourcesFailed,
+            format!("所有候选源都取不到文本资源：{}", req.url),
+        )
+        .with_suppressed(suppressed)
+        .with_leaf(leaf_of(kinds)))
+    }
+
+    async fn fetch_bytes(
+        &self,
+        req: &DownloadRequest,
+        candidate: &Candidate,
+    ) -> Result, 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：`/sha1//`（两级分片，
+//! 避开 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,
+}
+
+impl Default for CacheIndex {
+    fn default() -> Self {
+        Self {
+            version: INDEX_VERSION,
+            entries: BTreeMap::new(),
+        }
+    }
+}
+
+/// 内容寻址缓存。
+#[derive(Debug)]
+pub struct ContentCache {
+    root: PathBuf,
+    index: Mutex,
+}
+
+impl ContentCache {
+    /// 打开（或初始化）缓存根目录；索引损坏时从空表重建（缓存随时可丢，不阻断启动）。
+    #[must_use]
+    pub fn open(root: impl Into) -> 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::(&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 {
+        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 {
+        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 {
+        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) -> 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 {
+    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,
+}
+
+/// 解析 `Content-Range`（畸形一律 `None`，调用方退化处理）。
+#[must_use]
+pub fn parse_content_range(value: &str) -> Option {
+    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 {
+    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..20929a1
--- /dev/null
+++ b/crates/core/src/download/config.rs
@@ -0,0 +1,400 @@
+//! 引擎配置：设置层（core::setting）直接映射到这里。
+//!
+//! # 出厂默认值与设置 schema 的唯一来源（M193）
+//!
+//! 四个常量是**唯一**写死数字的地方：schema 的默认值/范围、`EngineConfig::default()`、
+//! `Semaphore` 容量全从它们取。此前 schema 写 8、引擎写 64 ⇒ 调并发完全无效（引擎侧零消费者）。
+//! 收成常量后「改一处另一个不变」会直接变红（守卫见 `shared.rs` 与本文件的用例）。
+
+use std::collections::HashMap;
+use std::path::{Path, PathBuf};
+use std::sync::{Mutex, OnceLock};
+use std::time::Duration;
+
+use super::backoff::BackoffPolicy;
+use super::chunked::ChunkedConfig;
+use super::region::RegionProfile;
+use super::types::ResumePolicy;
+
+/// 全局并发许可数的出厂默认（`download.concurrency` 的 schema 默认值同源）。
+pub const DEFAULT_MAX_CONCURRENCY: usize = 8;
+
+/// 全局并发许可的**硬上限**（`download.concurrency` 的 schema 上界同源）。schema 在写入口就拒绝
+/// 越界值，这里再夹一次是纵深防御（手改文件、老 schema 允许的大数）——9999 会把机器拖死。
+pub const MAX_CONCURRENCY: usize = 64;
+
+/// 每个源尝试次数的出厂默认（`download.retry_limit` 的 schema 默认值同源）。
+pub const DEFAULT_MAX_ATTEMPTS_PER_SOURCE: u32 = 3;
+
+/// 每个源尝试次数的硬上限（`download.retry_limit` 的 schema 上界同源）。
+pub const MAX_ATTEMPTS_PER_SOURCE: u32 = 10;
+
+/// 三个设置键名（层间契约）：登记在 `setting::keys`，读取在宿主。只写在这里，两侧都引用常量。
+pub const KEY_CONCURRENCY: &str = "download.concurrency";
+/// 见 [`KEY_CONCURRENCY`]。
+pub const KEY_RETRY_LIMIT: &str = "download.retry_limit";
+/// gh-proxy 前缀覆盖键（三态语义见 [`gh_proxy_override`]）。**已登记**：`setting::keys::proxy` 的
+/// `specs()` 里有它（文本 / 出厂空串），presenter 与 CLI 的宿主都按这个常量读，读不到 ⇒
+/// [`GhProxyOverride::Builtin`]。**绑定在哪（别当死键删）**：常量与 schema 登记的对应关系由
+/// `setting::keys::proxy` 的 `the_gh_proxy_key_is_bound_to_the_schema_registration`（M205）钉住：写错就红；
+/// 它抓不住两侧同时改名（公开改名）。行为退化由 `empty_gh_proxy_means_follow_builtin_not_off` 与 `shared` 的候选链拦。
+pub const KEY_GH_PROXY: &str = "download.gh_proxy";
+
+/// 引擎配置。
+#[derive(Debug, Clone)]
+pub struct EngineConfig {
+    /// 全局并发许可数（tokio `Semaphore`），默认 [`DEFAULT_MAX_CONCURRENCY`]。
+    pub max_concurrency: usize,
+    /// 每个源的尝试次数上限，默认 [`DEFAULT_MAX_ATTEMPTS_PER_SOURCE`]。
+    pub max_attempts_per_source: u32,
+    /// 连接超时，默认 10s。
+    pub connect_timeout: Duration,
+    /// 单次读超时（读空闲判定，不是整体超时），默认 30s。
+    pub read_timeout: Duration,
+    /// User-Agent（唯一定义在 `http::USER_AGENT`；两条 HTTP 路径发的都是这一份，别在这里另拼）。
+    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: DEFAULT_MAX_CONCURRENCY,
+            max_attempts_per_source: DEFAULT_MAX_ATTEMPTS_PER_SOURCE,
+            connect_timeout: Duration::from_secs(10),
+            read_timeout: Duration::from_secs(30),
+            user_agent: super::http::USER_AGENT.to_string(),
+            progress_throttle: Duration::from_millis(250),
+            backoff: BackoffPolicy::default(),
+            chunked: ChunkedConfig::default(),
+            resume: ResumePolicy::Conservative,
+        }
+    }
+}
+
+/// `download.gh_proxy` 的三种取值（三态语义见 [`gh_proxy_override`]）。
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub enum GhProxyOverride {
+    /// 空串：**没有覆盖**，跟随内置默认（地区判定 + 镜像表里的前缀）。
+    #[default]
+    Builtin,
+    /// 明确关掉：一个 gh-proxy 候选都不生成（`RegionProfile::with_gh_proxy(None)`）。
+    Off,
+    /// 用这个前缀覆盖（仍然只在镜像优先 / 国内判定时启用）。
+    Prefix(String),
+}
+
+/// 设置原文 → gh-proxy 三态（纯函数：`off` 与 URL 的边界在这里定死，不散落到宿主）。
+///
+/// **空串不等于关**：「我不想用加速」和「我还没决定」是两件事。空串 = 跟随内置默认，
+/// 要关必须写 `off`（`none` / `direct` / `disable` / `disabled` / `no` 这些口语词一并认，
+/// 大小写不敏感、前后空白忽略——用户拿哪个词表达「关掉」都合理，专门要求某一个会造出
+/// 「填了没生效」的坑）。
+#[must_use]
+pub fn gh_proxy_override(raw: &str) -> GhProxyOverride {
+    let text = raw.trim();
+    if text.is_empty() {
+        return GhProxyOverride::Builtin;
+    }
+    let lowered = text.to_ascii_lowercase();
+    if matches!(
+        lowered.as_str(),
+        "off" | "none" | "direct" | "disable" | "disabled" | "no"
+    ) {
+        return GhProxyOverride::Off;
+    }
+    GhProxyOverride::Prefix(text.to_string())
+}
+
+/// 设置侧灌进来的下载调优（M193）：并发 / 每个源的尝试次数 / gh-proxy 覆盖。
+///
+/// 这是「`launcher.json` 的三个键」到「引擎装配参数」之间**唯一**的翻译层：键名由宿主读（core
+/// 不认识设置键名），默认值、合法区间、回落策略都在这里——否则「UI 说 8、引擎跑 64」会从缝里长回来。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct DownloadTuning {
+    /// 全局并发许可数（已夹在 `1..=MAX_CONCURRENCY`）。
+    pub max_concurrency: usize,
+    /// 每个源的尝试次数上限（已夹在 `1..=MAX_ATTEMPTS_PER_SOURCE`）。
+    pub max_attempts_per_source: u32,
+    /// gh-proxy 覆盖。
+    pub gh_proxy: GhProxyOverride,
+}
+
+impl Default for DownloadTuning {
+    fn default() -> Self {
+        Self {
+            max_concurrency: DEFAULT_MAX_CONCURRENCY,
+            max_attempts_per_source: DEFAULT_MAX_ATTEMPTS_PER_SOURCE,
+            gh_proxy: GhProxyOverride::Builtin,
+        }
+    }
+}
+
+impl DownloadTuning {
+    /// 设置原文 → 调优（**未填 / 越界 / 非法值一律回落出厂默认**，绝不报错阻断下载）。
+    ///
+    /// 口径与 schema 的 `(min, max)` 同源但独立实现（用户可能手改文件绕过 `store.set`）：键不存在
+    /// → 出厂默认；落在区间内 → 原值；负数 / 超上限 → 出厂默认（**不夹到边界**：那是「想 9999 给
+    /// 64」，界面仍会说谎）。`retry_limit` 的 `0` 在区间内，落成「只试一次」（见实现里的注释）。
+    #[must_use]
+    pub fn from_settings(
+        concurrency: Option,
+        attempts: Option,
+        gh_proxy: Option<&str>,
+    ) -> Self {
+        let default = Self::default();
+        Self {
+            max_concurrency: concurrency
+                .and_then(|raw| usize::try_from(raw).ok())
+                .filter(|raw| (1..=MAX_CONCURRENCY).contains(raw))
+                .unwrap_or(default.max_concurrency),
+            // `0` 是**合法值**（P2-1 复审：旧配置里真的有 0，且旧 GUI 把它当档位）：语义是
+            // 「只试一次 = 不重试」，所以 0 与 1 都落成 1；负数 / 超上限才回落出厂默认。
+            max_attempts_per_source: attempts
+                .and_then(|raw| u32::try_from(raw).ok())
+                .filter(|raw| *raw <= MAX_ATTEMPTS_PER_SOURCE)
+                .map_or(default.max_attempts_per_source, |raw| raw.max(1)),
+            gh_proxy: gh_proxy.map_or(GhProxyOverride::Builtin, gh_proxy_override),
+        }
+    }
+
+    /// 把调优盖到 `EngineConfig` 上（其余字段保持传入值）。
+    #[must_use]
+    pub fn apply_to(&self, mut cfg: EngineConfig) -> EngineConfig {
+        cfg.max_concurrency = self.max_concurrency;
+        cfg.max_attempts_per_source = self.max_attempts_per_source;
+        cfg
+    }
+
+    /// 把 gh-proxy 覆盖盖到档案上（`Builtin` 原样返回 = 跟随地区判定与镜像表）。
+    #[must_use]
+    pub fn apply_gh_proxy(&self, profile: RegionProfile) -> RegionProfile {
+        match &self.gh_proxy {
+            GhProxyOverride::Builtin => profile,
+            GhProxyOverride::Off => profile.with_gh_proxy(None),
+            GhProxyOverride::Prefix(prefix) => profile.with_gh_proxy(Some(prefix)),
+        }
+    }
+}
+
+/// 每个缓存根一份「宿主想要什么」（[`wanted`] 用）。按数据根而不是进程级：登记处本就是「一个数据根
+/// 一个引擎」；进程级那份在多数据根时会互相踩（A 根改 2、B 根冲回 8）。
+fn wanted_slot() -> &'static Mutex> {
+    static WANTED: OnceLock>> = OnceLock::new();
+    WANTED.get_or_init(|| Mutex::new(HashMap::new()))
+}
+
+/// 该数据根当前想要的调优（没灌过 = 出厂默认）。
+#[must_use]
+pub fn wanted(cache_root: &Path) -> DownloadTuning {
+    wanted_slot()
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner())
+        .get(cache_root)
+        .cloned()
+        .unwrap_or_default()
+}
+
+/// 记下该数据根想要的调优，返回**是否真的变了**（没变时调用方不该重建引擎）。
+pub fn publish(cache_root: &Path, next: DownloadTuning) -> bool {
+    let mut wanted = wanted_slot()
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner());
+    // 归一化比较：「没灌过」与「灌了出厂默认」是同一件事，不能因为 `None != Some(default)`
+    // 就把每次取引擎都当成「参数变了」（那会每次重建引擎、把连接池与健康度记忆全丢掉）。
+    let current = wanted.get(cache_root).cloned().unwrap_or_default();
+    if current == next {
+        return false;
+    }
+    if next == DownloadTuning::default() {
+        // 默认值不占格子（也顺手回收测试造的临时根）。
+        wanted.remove(cache_root);
+    } else {
+        wanted.insert(cache_root.to_path_buf(), next);
+    }
+    true
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::setting::keys::{launcher_schema, launcher_version};
+
+    /// **守门③**：schema 的默认值 / 区间 / 键名与 `EngineConfig::default()` / 调优默认值取同一组常量。
+    /// 变异证明（只改实现侧）：`EngineConfig::default()` 的并发写回 64、schema 默认值写成 16、
+    /// `MAX_CONCURRENCY` 改了而 schema 仍写 64 ⇒ 各自红。
+    #[test]
+    fn the_schema_contract_is_single_sourced() {
+        let schema = launcher_schema();
+        assert_eq!(schema.version(), launcher_version());
+        let cfg = EngineConfig::default();
+        let tune = DownloadTuning::default();
+
+        // 并发 1~64（0 张许可没意义）；尝试次数 **0**~10（P2-1：0 = 只试一次，旧配置里真有）。
+        let contract: [(&str, i64, i64, usize); 2] = [
+            (
+                KEY_CONCURRENCY,
+                i64::try_from(DEFAULT_MAX_CONCURRENCY).expect("装得下"),
+                1,
+                MAX_CONCURRENCY,
+            ),
+            (
+                KEY_RETRY_LIMIT,
+                i64::from(DEFAULT_MAX_ATTEMPTS_PER_SOURCE),
+                0,
+                usize::try_from(MAX_ATTEMPTS_PER_SOURCE).expect("装得下"),
+            ),
+        ];
+        for (key, default, min, max) in contract {
+            let spec = schema.spec(key).expect("键已登记");
+            assert_eq!(spec.default, serde_json::json!(default), "{key}");
+            assert_eq!(
+                spec.kind,
+                crate::setting::spec::ValueKind::Int {
+                    min,
+                    max: i64::try_from(max).expect("装得下"),
+                },
+                "{key}"
+            );
+        }
+        assert_eq!(cfg.max_concurrency, DEFAULT_MAX_CONCURRENCY);
+        assert_eq!(tune.max_concurrency, DEFAULT_MAX_CONCURRENCY);
+        assert_eq!(cfg.max_attempts_per_source, DEFAULT_MAX_ATTEMPTS_PER_SOURCE);
+        assert_eq!(
+            tune.max_attempts_per_source,
+            DEFAULT_MAX_ATTEMPTS_PER_SOURCE
+        );
+    }
+
+    /// `SettingSpec.doc` 是 `&'static str`（`concat!` 插不进常量），描述里的数字只能手写——这条钉住它，
+    /// 改常量不改文案就红（`catalog.rs` 会把这些 doc 当 JSON schema 的 description 发出去）。
+    #[test]
+    fn the_key_docs_quote_the_real_limits() {
+        let schema = launcher_schema();
+        let doc = |key: &str| schema.spec(key).expect("键已登记").doc;
+        assert!(doc(KEY_CONCURRENCY).contains(&format!("1~{MAX_CONCURRENCY}")));
+        assert!(doc(KEY_CONCURRENCY).contains(&format!("出厂 {DEFAULT_MAX_CONCURRENCY}")));
+        assert!(doc(KEY_RETRY_LIMIT).contains(&format!("出厂 {DEFAULT_MAX_ATTEMPTS_PER_SOURCE}")));
+    }
+
+    /// 未填 / 越界回落默认（不阻断下载）；**`retry_limit: 0` 是合法值**，语义 = 只试一次。
+    ///
+    /// 变异证明：把并发的区间过滤删掉 ⇒ `0` / `9999` 两条红；把尝试次数的 `.max(1)` 删掉 ⇒
+    /// `0 → 1` 那条红（引擎会拿到 0 次尝试）；把 `0` 判成越界 ⇒ 同样红。
+    #[test]
+    fn missing_or_illegal_values_fall_back_to_the_defaults() {
+        assert_eq!(
+            DownloadTuning::from_settings(None, None, None),
+            DownloadTuning::default()
+        );
+
+        let just_over = i64::try_from(MAX_CONCURRENCY).expect("上限装得下") + 1;
+        for bad in [0_i64, -1, 9_999, just_over] {
+            let tune = DownloadTuning::from_settings(Some(bad), None, None);
+            assert_eq!(tune.max_concurrency, DEFAULT_MAX_CONCURRENCY, "{bad}");
+        }
+        // 0 与 1 都 = 只试一次：旧配置里的 0 不许回落成出厂 3（那正是「界面 0、引擎 3」）。
+        for zero_or_one in [0_i64, 1] {
+            let tune = DownloadTuning::from_settings(None, Some(zero_or_one), None);
+            assert_eq!(tune.max_attempts_per_source, 1, "{zero_or_one}");
+        }
+        for bad in [-1_i64, 9_999] {
+            let tune = DownloadTuning::from_settings(None, Some(bad), None);
+            assert_eq!(
+                tune.max_attempts_per_source,
+                DEFAULT_MAX_ATTEMPTS_PER_SOURCE
+            );
+        }
+
+        let tune = DownloadTuning::from_settings(Some(2), Some(2), None);
+        assert_eq!(tune.max_concurrency, 2);
+        assert_eq!(tune.max_attempts_per_source, 2);
+    }
+
+    /// 三态：**空串 ≠ 关**（这条是「设置项说假话」的高发点，M197 的键语义同源）。
+    #[test]
+    fn empty_gh_proxy_means_follow_builtin_not_off() {
+        assert_eq!(gh_proxy_override(""), GhProxyOverride::Builtin);
+        assert_eq!(gh_proxy_override("   "), GhProxyOverride::Builtin);
+        for off in [
+            "off", "OFF", " none ", "direct", "disable", "disabled", "no",
+        ] {
+            assert_eq!(gh_proxy_override(off), GhProxyOverride::Off, "{off}");
+        }
+        assert_eq!(
+            gh_proxy_override(" https://gh.example/ "),
+            GhProxyOverride::Prefix("https://gh.example/".to_string())
+        );
+        // 未填（键不存在）也是 Builtin，不是 Off。
+        assert_eq!(
+            DownloadTuning::from_settings(None, None, None).gh_proxy,
+            GhProxyOverride::Builtin
+        );
+    }
+
+    /// `apply_gh_proxy` 的三档真的改到档案上、并且**改到候选链上**（`expand()` 读的就是档案里那个
+    /// 前缀；自定义前缀那一档的链断言在 `shared.rs`）。变异证明：`Off` 分支改成原样返回 ⇒ `off` 红。
+    #[test]
+    fn gh_proxy_override_reaches_the_profile_and_the_chain() {
+        use crate::download::mirrors::{MirrorTable, SOURCE_GH_PROXY};
+        use crate::download::types::ResourceKind;
+
+        let url = "https://github.com/o/r/releases/download/v1/a.jar";
+        let table = MirrorTable::builtin();
+        let sources = |profile: &RegionProfile| -> Vec {
+            table
+                .expand(url, ResourceKind::Other, profile)
+                .into_iter()
+                .map(|candidate| candidate.source)
+                .collect()
+        };
+
+        let mirror_first = RegionProfile::mirror_first(0);
+        let kept = DownloadTuning::default().apply_gh_proxy(mirror_first.clone());
+        assert_eq!(kept.gh_proxy, mirror_first.gh_proxy, "Builtin 不该动档案");
+        assert!(
+            sources(&kept).contains(&SOURCE_GH_PROXY.to_string()),
+            "出厂套前缀"
+        );
+
+        let off = DownloadTuning::from_settings(None, None, Some("off"))
+            .apply_gh_proxy(mirror_first.clone());
+        assert!(
+            !sources(&off).contains(&SOURCE_GH_PROXY.to_string()),
+            "关了就没候选"
+        );
+
+        let prefix = DownloadTuning::from_settings(None, None, Some("https://gh.example/"))
+            .apply_gh_proxy(mirror_first);
+        assert_eq!(prefix.gh_proxy.as_deref(), Some("https://gh.example/"));
+        assert!(prefix.gh_proxy_enabled(), "前缀生效");
+    }
+
+    /// 每个数据根的调优互不串味（一个根改成 2 不该改另一个根的引擎）。
+    /// 变异证明：把 `wanted`/`publish` 的键改回单一进程级槽位 ⇒ 第二个根读到 2，红。
+    #[test]
+    fn tuning_is_per_cache_root_and_no_change_is_reported_as_such() {
+        let a = PathBuf::from("/tmp/ull-tuning-a");
+        let b = PathBuf::from("/tmp/ull-tuning-b");
+        assert_eq!(wanted(&a), DownloadTuning::default());
+
+        let changed = DownloadTuning::from_settings(Some(2), None, None);
+        assert!(publish(&a, changed.clone()), "真变了要报变更");
+        assert_eq!(wanted(&a), changed);
+        assert!(!publish(&a, changed.clone()), "同值不该报变更");
+        assert_eq!(wanted(&b), DownloadTuning::default(), "别的根不受影响");
+
+        assert!(
+            publish(&a, DownloadTuning::default()),
+            "恢复默认也是一次变更"
+        );
+        assert_eq!(wanted(&a), DownloadTuning::default());
+    }
+}
diff --git a/crates/core/src/download/engine.rs b/crates/core/src/download/engine.rs
new file mode 100644
index 0000000..e782e78
--- /dev/null
+++ b/crates/core/src/download/engine.rs
@@ -0,0 +1,400 @@
+//! 下载引擎：编排层。
+//!
+//! 一次 `download()` 的固定剧情：
+//!
+//! ```text
+//! 校验请求 → 内容寻址缓存直取（零网络）
+//!          → 候选规划（镜像表展开 + 健康度排序）
+//!          → Semaphore 限流          ← 容量来自设置（M193，见 config.rs）
+//!          → 候选源外循环（换源），每源内循环（指数退避 + 抖动）
+//!              → 续传判定（保守）→ 单连接 / 多连接分块 → 流式校验 → 原子落盘
+//!          → 失败则保留中间文件供下次续传
+//! ```
+//!
+//! 中间文件是本会话命名的（`.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, MAX_CONCURRENCY};
+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,
+    pub(crate) cache: Arc,
+    pub(crate) jitter: std::sync::Mutex,
+    mirrors: Arc,
+    region: Arc,
+    sem: Arc,
+}
+
+impl DownloadEngine {
+    /// 构造引擎（用 `with_progress` 挂事件流）。
+    #[must_use]
+    pub fn new(
+        cfg: EngineConfig,
+        mirrors: Arc,
+        region: Arc,
+        health: Arc,
+        cache: Arc,
+    ) -> Self {
+        let http = http::build_client(&cfg).unwrap_or_else(|_| reqwest::Client::new());
+        // 硬上限夹取（M193）：手改的 launcher.json / CLI 自拼的 cfg 都可能写着 9999，在唯一构造点再夹一次。
+        let permits = cfg.max_concurrency.clamp(1, MAX_CONCURRENCY);
+        let sem = Arc::new(Semaphore::new(permits));
+        let seed = now_ms() ^ (u64::from(u32::try_from(permits).unwrap_or(u32::MAX)) << 32);
+        // 纯记账（M165）：卡在构造这个点上，才统计得到绕过登记处的调用点（守卫靠 `constructions`）。
+        super::shared::record_build(cache.root());
+        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
+    }
+
+    /// **真实并发闸门**此刻的许可数（探针，M193）：读 [`Self::acquire`] 会去抢的那张
+    /// `Semaphore`，**不是** `config().max_concurrency`。有下载在飞时偏小，空闲等于容量。
+    #[must_use]
+    pub fn concurrency_probe(&self) -> usize {
+        self.sem.available_permits()
+    }
+
+    /// HTTP 客户端（同一条连接池与超时配置）：给「一锤子查询」用（如 Adoptium 版本查询），
+    /// 没必要为了一个 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 {
+        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 {
+        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 = Vec::new();
+        let mut previous: Option = 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(),
+                            kind: err.kind,
+                            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 {
+        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 {
+        Arc::clone(&self.sem).acquire_owned().await.map_err(|_| {
+            DownloadError::new(DownloadErrorKind::Io, "并发闸门已关闭（引擎正在销毁）")
+        })
+    }
+
+    /// 该源此刻给几次尝试：冷却中 / 刚出冷却未洗白 → 1 次（那就是恢复探测，别让死源每次到期
+    /// 都吃满预算）；正常 → 设置里的 `download.retry_limit`（= `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 {
+    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..3152de9
--- /dev/null
+++ b/crates/core/src/download/error.rs
@@ -0,0 +1,250 @@
+//! 下载错误：三态分类（同源重试 / 立刻换源 / 整体失败）+ 失败摘要。
+//!
+//! 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,
+    /// 人类可读描述。
+    pub message: String,
+    /// 已经尝试的次数（含本次）。
+    pub attempts: usize,
+    /// 其它候选源的失败摘要，便于诊断「到底哪一层挂了」。
+    pub suppressed: Vec,
+    /// **叶子成因**：整体失败（[`DownloadErrorKind::AllSourcesFailed`]）之前，各候选源到底
+    /// 是怎么挂的。
+    ///
+    /// 为什么需要它：候选源循环结束后只剩一条 `AllSourcesFailed`，上层（在线内容源、
+    /// 导入补全、自更新）拿到它就无法区分「这个项目不存在（404）」与「没联网」——
+    /// 前者要提示换关键词，后者要提示检查网络。`suppressed` 里虽然有文字，但从错误串里
+    /// 反解状态码是靠文案猜，改一句提示就失效。
+    ///
+    /// 汇总规则（[`leaf_of`]）：全 404 ⇒ `NotFound`；出现 `Network`/`Timeout` ⇒ `Network`；
+    /// 全 5xx ⇒ `ServerError`；混合按「网络错 > 5xx > 404」取最可诊断的那个。
+    /// `None` = 没有汇总过（单源直接失败，或调用方自己构造的错误）。
+    pub leaf: Option,
+}
+
+impl DownloadError {
+    /// 构造错误。
+    #[must_use]
+    pub fn new(kind: DownloadErrorKind, message: impl Into) -> Self {
+        Self {
+            kind,
+            source: None,
+            message: message.into(),
+            attempts: 0,
+            suppressed: Vec::new(),
+            leaf: None,
+        }
+    }
+
+    /// 标注出错的源。
+    #[must_use]
+    pub fn with_source(mut self, source: impl Into) -> 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) -> Self {
+        self.suppressed = suppressed;
+        self
+    }
+
+    /// 标注整体失败之前的叶子成因。
+    #[must_use]
+    pub const fn with_leaf(mut self, leaf: DownloadErrorKind) -> Self {
+        self.leaf = Some(leaf);
+        self
+    }
+
+    /// 最可诊断的成因：有叶子就用叶子，否则用自身的 kind。
+    ///
+    /// 上层（`addon::online::transport` / `addon::import::fetch`）靠这一处判定，不各自
+    /// 再写一遍「AllSourcesFailed 到底算哪一类」。
+    #[must_use]
+    pub fn effective_kind(&self) -> DownloadErrorKind {
+        if self.kind == DownloadErrorKind::AllSourcesFailed {
+            return self.leaf.unwrap_or(self.kind);
+        }
+        self.kind
+    }
+}
+
+/// 从各候选源的失败里汇总出**最可诊断**的叶子成因。
+///
+/// 规则（与 `online::transport` 的映射表配套，判据只此一处）：
+///
+/// | 各源的情况 | 叶子 |
+/// |------------|------|
+/// | 全部 404/410/403（`NotFound`） | `NotFound` |
+/// | 出现 `Network` / `Timeout` | `Network` |
+/// | 全部 5xx（`ServerError`） | `ServerError` |
+/// | 其它（`Integrity` / `Io` / `InvalidRequest`） | 该条自己的 kind（后出现的赢） |
+/// | 混合了 404 与 5xx | `ServerError`（比「不存在」更可诊断） |
+///
+/// `kinds` 为空时返回 `AllSourcesFailed`（调用方据此保留原 kind）。
+#[must_use]
+pub fn leaf_of(kinds: impl IntoIterator) -> DownloadErrorKind {
+    let mut leaf = DownloadErrorKind::AllSourcesFailed;
+    let mut rank = 0u8;
+    for kind in kinds {
+        let (candidate, weight) = match kind {
+            DownloadErrorKind::Network | DownloadErrorKind::Timeout => {
+                (DownloadErrorKind::Network, 4)
+            }
+            DownloadErrorKind::ServerError => (DownloadErrorKind::ServerError, 3),
+            DownloadErrorKind::Integrity => (DownloadErrorKind::Integrity, 3),
+            DownloadErrorKind::Io => (DownloadErrorKind::Io, 3),
+            DownloadErrorKind::InvalidRequest => (DownloadErrorKind::InvalidRequest, 3),
+            DownloadErrorKind::NotFound => (DownloadErrorKind::NotFound, 1),
+            DownloadErrorKind::RangeUnsupported | DownloadErrorKind::AllSourcesFailed => (kind, 2),
+        };
+        if weight >= rank {
+            rank = weight;
+            leaf = candidate;
+        }
+    }
+    leaf
+}
+
+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 {}
+
+#[cfg(test)]
+mod tests {
+    use super::{leaf_of, DownloadError, DownloadErrorKind};
+
+    /// 四档叶子成因（tower 定案的门禁）：全 404 / 有网络错 / 全 5xx / 混合。
+    #[test]
+    fn leaf_keeps_the_most_diagnosable_cause() {
+        use DownloadErrorKind::{Network, NotFound, ServerError, Timeout};
+        assert_eq!(leaf_of([NotFound, NotFound]), NotFound, "全 404 ⇒ NotFound");
+        assert_eq!(
+            leaf_of([Network, NotFound]),
+            Network,
+            "有网络错 ⇒ Network（哪怕另一源是 404）"
+        );
+        assert_eq!(
+            leaf_of([ServerError, ServerError]),
+            ServerError,
+            "全 5xx ⇒ ServerError"
+        );
+        assert_eq!(
+            leaf_of([NotFound, ServerError]),
+            ServerError,
+            "混合 404 与 5xx ⇒ 取更可诊断的那个"
+        );
+        assert_eq!(leaf_of([Timeout, NotFound]), Network, "超时归到 Network");
+        assert_eq!(
+            leaf_of([]),
+            DownloadErrorKind::AllSourcesFailed,
+            "一条都没有 ⇒ 保留原 kind"
+        );
+    }
+
+    /// 整体失败时上层靠 `effective_kind()` 判定；单源失败时就是它自己的 kind。
+    #[test]
+    fn effective_kind_prefers_the_leaf_only_for_all_sources_failed() {
+        let leaf = DownloadError::new(DownloadErrorKind::AllSourcesFailed, "全部失败")
+            .with_leaf(DownloadErrorKind::NotFound);
+        assert_eq!(leaf.effective_kind(), DownloadErrorKind::NotFound);
+        assert_eq!(
+            leaf.kind,
+            DownloadErrorKind::AllSourcesFailed,
+            "kind 本身不改"
+        );
+
+        let bare = DownloadError::new(DownloadErrorKind::AllSourcesFailed, "全部失败");
+        assert_eq!(
+            bare.effective_kind(),
+            DownloadErrorKind::AllSourcesFailed,
+            "没有叶子 ⇒ 原样返回（上层再决定当哪一类）"
+        );
+
+        let single = DownloadError::new(DownloadErrorKind::NotFound, "404");
+        assert_eq!(single.effective_kind(), DownloadErrorKind::NotFound);
+    }
+}
diff --git a/crates/core/src/download/font.rs b/crates/core/src/download/font.rs
new file mode 100644
index 0000000..1d3f731
--- /dev/null
+++ b/crates/core/src/download/font.rs
@@ -0,0 +1,352 @@
+//! OFL 中文字体的取回（D28 后半）：**缓存命中 → 共享引擎下载 → 复验 → 原子落盘**。
+//!
+//! ## 一段话
+//!
+//! `unlucky_i18n::font` 只做判据与「该下载什么」（URL 候选 + sha256 + 字节数），真正把字节弄到
+//! 盘上的活在这里：
+//!
+//! ```text
+//! <数据根>/fonts/cjk-noto-sans-sc-.ttf
+//!        已有且哈希 + 魔数都对 ⇒ 直接返回（零网络）
+//!        否则 ⇒ 共享引擎的 download_bytes（进内存）
+//!             ⇒ 自己再算一遍 sha256、再看一眼是不是 sfnt、再看大小上限
+//!             ⇒ 全过才 write_atomic 落盘 ⇒ 返回字节
+//! ```
+//!
+//! ## 为什么用「内存下载」而不是「边下边写文件」
+//!
+//! 一张 17 MiB 的字体本来就要整份进内存（注册进字体系统要 `Vec`），而**先复验再落盘**让
+//! 「哈希不符」这条判据简单到不可能出错：盘上要么没有这个文件，要么它是校验过的。文件下载路径
+//! （`DownloadEngine::download`）会先写 `.ullpart-*` 再换名，中间态与「拒绝落盘」混在一起，
+//! 对这一份内容寻址的小资源没有收益。
+//!
+//! ## 三条判据（都有守卫，见 `tests.rs`）
+//!
+//! 1. **缓存命中不联网**：命中就 `from_cache`，一条 HTTP 都不发（同进程第二次、二次启动都一样）；
+//!    哈希不符的旧文件会被删掉重下（自愈），不冒充命中、也不永远挡路。
+//! 2. **sha256 不符拒绝落盘**：复验在任何写盘动作**之前**；不符 ⇒ 正式路径上什么都没有。
+//! 3. **大小上限**：[`MAX_FONT_BYTES`]。pin 声称超过上限的直接拒（不发请求）；实得字节超上限的
+//!    也拒。挡的是「CDN 被换成一个大文件」这类事故，不是省流量。
+//!
+//! ## 失败分类为什么是三类
+//!
+//! 上层（设置页那一行）只需决定「说什么话」：网络类可重试、校验类是内容不对、磁盘类得腾空间。
+//! 再多分类对用户没有区别。
+//!
+//! ## 与 M165 共享引擎的关系
+//!
+//! **不另写 HTTP 通路**：请求一律走 [`super::shared::engine_for`] 那个进程级引擎（连接池 / 限流 /
+//! 健康度 / 候选源都复用）。本模块只额外提供「字体这个资源特有的三件事」：内容寻址的缓存文件名、
+//! 复验、大小上限。
+
+use std::path::Path;
+use std::time::{Duration, Instant};
+
+use super::atomic::write_atomic;
+use super::blocking::block_on;
+use super::error::DownloadErrorKind;
+use super::shared;
+use super::types::{DownloadRequest, HashAlgo, ResourceKind};
+use super::verify;
+
+/// 一套字体允许的最大字节数（32 MiB）。
+///
+/// 实测参考：Noto Sans SC 可变字体（wght 100–900，整个简体字符集）16.95 MiB；再大的「字体」基本
+/// 可以判断不是给 UI 用的字体。上限的用处不是省流量，是**挡住被换掉的 CDN 把几十上百 MB 的东西
+/// 写进数据根**。
+pub const MAX_FONT_BYTES: u64 = 32 * 1024 * 1024;
+
+/// **非最后一个候选**的单次尝试时限（不是连接超时，也不是空闲超时）。
+///
+/// 为什么必须有：引擎的 `read_timeout` 是 30 s **空闲**超时，一条每秒只挤几 KB、但一直在动的
+/// 连接永远不会被判失败。复审实测过这条路径（同一台机器、同一份文件）：
+///
+/// | 路径 | 结果 |
+/// |---|---|
+/// | Fastly 的 IPv6 边缘 | 60 s 只到 4.0 MB（≈67 KB/s，17.7 MB 要 ≈4 分钟） |
+/// | 同一域名的 IPv4 边缘 | 1.2 s 下完（≈15 MB/s） |
+///
+/// 60 s 是「明显不对劲就换源」的位置：健康线路（实测 1.1~16.6 s）根本用不到它。
+///
+/// ## 为什么**最后一个**候选不吃这个时限（复审 r2 P2-3 / r3 P2-3）
+///
+/// 每个候选都从 0 字节重下（不做续传），所以「单次上限」直接就是一条**吞吐门槛**：
+/// `17 772 300 B / 预算`。历史两版都踩在这里：90 s ⇒ 门槛 197 KB/s；120 s + 总 360 s ⇒
+/// 第一个候选吃掉 120 s 后最后一个只剩 240 s ⇒ 门槛 **72.3 KiB/s**，而 r1 实测那条 IPv6 是
+/// 67~77 KiB/s——**67 KiB/s 需要 259 s > 240 s，仍然必失败**（复审 r3 就是这么把上一版的
+/// 「49 KB/s」拆穿的：那个数是「第一个候选瞬间失败」的情形，不是这条改动要救的场景）。
+///
+/// 现在的规则（见 [`fetch_blocking_with_limits`]）：前 n-1 个候选各拿
+/// `min(ATTEMPT_DEADLINE, 剩余)`，**最后一个候选拿整个剩余总预算**。
+///
+/// ## 三个数的完整算术（2 个候选的常见情形）
+///
+/// | 情形 | 最后一个候选拿到的预算 | 门槛 = 17 772 300 B / 预算 |
+/// |---|---|---|
+/// | 第一个候选瞬间失败 | 420 s | **42.3 KiB/s** |
+/// | 第一个候选爬满 60 s 被切 | 360 s | **49.4 KiB/s** |
+///
+/// 两者都低于 r1 实测最慢的 67 KiB/s（需要 259 s），于是「慢而当当能下完」的线路仍有**一次**
+/// 老老实实下完的机会。**超时归入网络档**（用户视角是「太慢」，不是「内容不对」）。
+pub const ATTEMPT_DEADLINE: Duration = Duration::from_secs(60);
+
+/// 整条取回（所有候选加起来）的总时限，也是**最后一个候选**能拿到的预算上限。
+///
+/// 取值依据见 [`ATTEMPT_DEADLINE`] 的算术表：420 s 让「第一个候选爬满 60 s」这种最差情形
+/// 仍给最后一个候选 360 s（49.4 KiB/s 门槛）。
+///
+/// 代价：最坏情形下用户要在设置页看着「正在获取中文字体…（16.9 MB）」等 7 分钟。这是刻意的
+/// 取舍——**慢而最终成功**远好过**快而必然失败**（后者要用户自己再来一次，结果一样）。
+pub const TOTAL_DEADLINE: Duration = Duration::from_secs(420);
+
+/// 字体取回的失败分类（三层，见模块文档「失败分类为什么是三类」）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum FontFetchError {
+    /// 网络层：连不上 / 超时 / 非 2xx / 所有候选源都失败。
+    Network(String),
+    /// 内容层：sha256 不符 / 不是字体文件 / 超出大小上限。
+    Integrity(String),
+    /// 本地磁盘层：建目录、写文件、换名失败。
+    Disk(String),
+}
+
+impl FontFetchError {
+    /// 稳定类别名（`network` / `integrity` / `disk`；日志与 i18n 金表按它选词，**不要改名**）。
+    #[must_use]
+    pub const fn class(&self) -> &'static str {
+        match self {
+            Self::Network(_) => "network",
+            Self::Integrity(_) => "integrity",
+            Self::Disk(_) => "disk",
+        }
+    }
+
+    /// 人类可读描述（进日志的一句）。
+    #[must_use]
+    pub fn message(&self) -> &str {
+        match self {
+            Self::Network(message) | Self::Integrity(message) | Self::Disk(message) => message,
+        }
+    }
+}
+
+impl std::fmt::Display for FontFetchError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "[{}] {}", self.class(), self.message())
+    }
+}
+
+impl std::error::Error for FontFetchError {}
+
+impl From for FontFetchError {
+    fn from(error: super::error::DownloadError) -> Self {
+        // 用叶子成因：`download_bytes` 的整体失败会带上它（全 404 → NotFound，出现网络错 → Network，
+        // 校验不符 → Integrity）。少了叶子这一层，哈希不符会被读成「没联网」。
+        let message = error.to_string();
+        match error.effective_kind() {
+            DownloadErrorKind::Io => Self::Disk(message),
+            DownloadErrorKind::Integrity | DownloadErrorKind::InvalidRequest => {
+                Self::Integrity(message)
+            }
+            _ => Self::Network(message),
+        }
+    }
+}
+
+/// 一次取回的产物。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct FontFetch {
+    /// 字体字节（交给调用方注册进字体系统）。
+    pub bytes: Vec,
+    /// 是否零网络命中缓存。
+    pub from_cache: bool,
+    /// 成功的源标识（`cache` / 引擎给的候选源名）。
+    pub source: String,
+    /// 耗时。
+    pub elapsed: Duration,
+}
+
+/// 取一套字体（**阻塞**：内部走进程共享运行时）。
+///
+/// 顺序：pin 自洽检查 → 缓存复验 → 逐个 URL 走共享引擎 → 复验 + 魔数 + 上限 → 原子落盘。
+///
+/// # Errors
+/// 见 [`FontFetchError`]。失败**不是**致命错误：调用方应当降级回系统字体 / 英文界面。
+pub fn fetch_blocking(cache_root: &Path, spec: &FontSpec) -> Result {
+    fetch_blocking_with_limits(cache_root, spec, ATTEMPT_DEADLINE, TOTAL_DEADLINE)
+}
+
+/// 同 [`fetch_blocking`]，但两个时限由调用方给（单测用它把 60 s / 420 s 压成几百毫秒）。
+///
+/// 为什么把时限做成参数而不是读环境变量：这是**行为**判据，不是诊断开关——测试要能证明
+/// 「一条只爬不死的连接会在时限处被打断并换源」，而 90 s 的用例没人会跑。
+///
+/// # Errors
+/// 同 [`fetch_blocking`]；超时归 [`FontFetchError::Network`]（文案里带「超时」二字）。
+pub fn fetch_blocking_with_limits(
+    cache_root: &Path,
+    spec: &FontSpec,
+    attempt_deadline: Duration,
+    total_deadline: Duration,
+) -> Result {
+    let started = Instant::now();
+    spec.check()?;
+
+    let final_path = cache_path(cache_root, spec);
+    if let Some(bytes) = read_verified(&final_path, spec)? {
+        return Ok(FontFetch {
+            bytes,
+            from_cache: true,
+            source: "cache".to_owned(),
+            elapsed: started.elapsed(),
+        });
+    }
+
+    let engine = shared::engine_for(cache_root);
+    let mut network_error: Option = None;
+    let mut integrity_error: Option = None;
+
+    for (index, url) in spec.urls.iter().enumerate() {
+        // 总时限先看一眼：已经用完了就不必再开一条注定超时的连接。
+        let remaining = total_deadline.saturating_sub(started.elapsed());
+        if remaining.is_zero() {
+            network_error = Some(FontFetchError::Network(format!(
+                "取字体超过总时限 {} s（已试 {index} / {} 个候选；这是「太慢」，不是校验失败）",
+                total_deadline.as_secs(),
+                spec.urls.len()
+            )));
+            break;
+        }
+        // 前 n-1 个候选：`min(单次上限, 剩余)`；**最后一个候选**拿整个剩余总预算。
+        // 为什么对最后一个放宽：每个候选都从 0 字节重下，「单次上限」就是一条吞吐门槛，
+        // 卡死最后一个等于把「慢但能下完」判成永久失败（复审 r2 P2-3 的算术，见 ATTEMPT_DEADLINE）。
+        let is_last = index + 1 == spec.urls.len();
+        let budget = if is_last {
+            remaining
+        } else {
+            attempt_deadline.min(remaining)
+        };
+        let request = DownloadRequest::new(ResourceKind::Other, url.clone(), &final_path)
+            .with_sha256(&spec.sha256)
+            .with_size(spec.bytes);
+
+        let attempt = block_on(async {
+            // `tokio::time::timeout` 必须在**运行时上下文里**构造（它一创建就要注册计时器；
+            // 在外面构造会 panic「there is no reactor running」）。所以整段包进 async 块。
+            tokio::time::timeout(budget, engine.download_bytes(request)).await
+        });
+        let outcome = match attempt {
+            Ok(outcome) => outcome,
+            Err(_elapsed) => {
+                network_error = Some(FontFetchError::Network(format!(
+                    "下载字体超时（单次上限 {} ms，总上限 {} ms）：{url}",
+                    budget.as_millis(),
+                    total_deadline.as_millis()
+                )));
+                continue;
+            }
+        };
+
+        match outcome {
+            Ok(bytes) => {
+                if bytes.len() as u64 > MAX_FONT_BYTES {
+                    integrity_error = Some(FontFetchError::Integrity(format!(
+                        "字体超过大小上限：{} > {MAX_FONT_BYTES}",
+                        bytes.len()
+                    )));
+                    continue;
+                }
+                // 引擎的流式校验与这一道是**两处独立**的判据：这里同时看哈希与魔数，且都在写盘之前。
+                let actual = verify::digest_bytes(HashAlgo::Sha256, &bytes);
+                if !verify::matches(&spec.sha256, &actual) {
+                    integrity_error = Some(FontFetchError::Integrity(format!(
+                        "字体 sha256 不符：期望 {} 实得 {actual}（{url}）",
+                        spec.sha256
+                    )));
+                    continue;
+                }
+                if !looks_like_sfnt(&bytes) {
+                    integrity_error = Some(FontFetchError::Integrity(format!(
+                        "取回的不是字体文件（sfnt 魔数不符）：{url}"
+                    )));
+                    continue;
+                }
+                write_atomic(&final_path, &bytes).map_err(|error| {
+                    FontFetchError::Disk(format!(
+                        "字体落盘失败（{}）：{error}",
+                        final_path.display()
+                    ))
+                })?;
+                return Ok(FontFetch {
+                    bytes,
+                    from_cache: false,
+                    source: url.clone(),
+                    elapsed: started.elapsed(),
+                });
+            }
+            Err(error) => {
+                let mapped = FontFetchError::from(error);
+                match mapped {
+                    FontFetchError::Integrity(_) => integrity_error = Some(mapped),
+                    _ => network_error = Some(mapped),
+                }
+            }
+        }
+    }
+
+    // 报错时优先报「内容不对」：那说明源给了不该给的东西，比「连不上」更需要人看一眼。
+    Err(integrity_error
+        .or(network_error)
+        .unwrap_or_else(|| FontFetchError::Network("字体 pin 没有可用 URL".to_owned())))
+}
+
+/// 读缓存并复验（`Ok(None)` = 不存在或校验不过，**且坏文件已被删掉**）。
+fn read_verified(path: &Path, spec: &FontSpec) -> Result>, FontFetchError> {
+    let bytes = match std::fs::read(path) {
+        Ok(bytes) => bytes,
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(None),
+        Err(error) => {
+            return Err(FontFetchError::Disk(format!(
+                "读字体缓存失败（{}）：{error}",
+                path.display()
+            )))
+        }
+    };
+
+    let actual = verify::digest_bytes(HashAlgo::Sha256, &bytes);
+    if !verify::matches(&spec.sha256, &actual) || !looks_like_sfnt(&bytes) {
+        // 坏缓存自愈：删掉，交给下载路径重来（不把坏文件当命中，也不让它一直挡路）。
+        let _ = std::fs::remove_file(path);
+        return Ok(None);
+    }
+    Ok(Some(bytes))
+}
+
+/// 是不是一个 sfnt 字体文件（TTF / OTF / TTC）。
+///
+/// 只认魔数 + 表目录读得出来：够挡住「CDN 回了一个 HTML 错误页」这类事故，**不**做字形覆盖校验
+/// （那要 `ttf-parser`，core 的依赖纪律不允许为一个判据引它）。
+#[must_use]
+pub fn looks_like_sfnt(bytes: &[u8]) -> bool {
+    if bytes.len() < 12 {
+        return false;
+    }
+    let tag = &bytes[..4];
+    if tag == b"ttcf" {
+        // 字体集合：只要长度说得过去就收（成员表的细节不值得在这里解析）。
+        return bytes.len() >= 16;
+    }
+    if !matches!(tag, b"\x00\x01\x00\x00" | b"OTTO" | b"true") {
+        return false;
+    }
+    let tables = u16::from_be_bytes([bytes[4], bytes[5]]);
+    tables > 0 && bytes.len() >= 12 + usize::from(tables) * 16
+}
+
+mod spec;
+
+pub use spec::{cache_path, FontSpec};
+
+#[cfg(test)]
+#[path = "font/tests.rs"]
+mod tests;
diff --git a/crates/core/src/download/font/spec.rs b/crates/core/src/download/font/spec.rs
new file mode 100644
index 0000000..8c3cba1
--- /dev/null
+++ b/crates/core/src/download/font/spec.rs
@@ -0,0 +1,106 @@
+//! 「下什么、放哪」：字体 pin 的**值**表示（[`FontSpec`]）与缓存落点（[`cache_path`]）。
+//!
+//! 从 `font.rs` 拆出只为守 400 行硬线（M168 复审 r1 加了整体时限与 URL 口径之后越线）。
+//! 判据（哪些 URL 可用）、复验、落盘编排都在 [`super`] 那边；这里只有数据结构与路径规则。
+
+use std::path::{Path, PathBuf};
+
+use super::{FontFetchError, MAX_FONT_BYTES};
+
+/// 一套字体的「在哪拿、拿到什么」：URL 候选（首选 + 备用镜像）+ 期望 sha256 + 期望字节数。
+///
+/// 与 `unlucky_i18n::font::Source::Pinned` 是同一份事实的两种表示：i18n 那份是**常量**（零依赖
+/// crate 里写死），本结构是**值**（可被设置改写、可在测试里注入假 URL）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct FontSpec {
+    /// URL 候选，按顺序尝试（首选 CDN 挂了才试备用镜像）。
+    pub urls: Vec,
+    /// 期望 sha256（小写十六进制、64 位）。
+    pub sha256: String,
+    /// 期望字节数（进度预算 + 大小上限的判据）。
+    pub bytes: u64,
+}
+
+impl FontSpec {
+    /// 构造并做基本自洽检查（URL 非空 / 哈希形态 / 大小上限）。
+    ///
+    /// # Errors
+    /// pin 本身不合法时返回 [`FontFetchError::Integrity`]（**不发请求**）。
+    pub fn new(
+        urls: impl IntoIterator>,
+        sha256: impl Into,
+        bytes: u64,
+    ) -> Result {
+        let spec = Self {
+            urls: urls.into_iter().map(Into::into).collect(),
+            sha256: sha256.into().trim().to_ascii_lowercase(),
+            bytes,
+        };
+        spec.check()?;
+        Ok(spec)
+    }
+
+    /// pin 是否自洽（`super::fetch_blocking*` 与构造器都调它，故 `pub(super)`）。
+    pub(super) fn check(&self) -> Result<(), FontFetchError> {
+        if self.urls.is_empty() {
+            return Err(FontFetchError::Integrity("字体 pin 没有 URL".to_owned()));
+        }
+        if let Some(bad) = self.urls.iter().find(|url| !is_acceptable_url(url)) {
+            return Err(FontFetchError::Integrity(format!(
+                "字体 pin 只接受 https（http 仅限回环地址，给单测用）：{bad}"
+            )));
+        }
+        if self.sha256.len() != 64 || !self.sha256.bytes().all(|b| b.is_ascii_hexdigit()) {
+            return Err(FontFetchError::Integrity(format!(
+                "字体 pin 的 sha256 不是 64 位十六进制：{}",
+                self.sha256
+            )));
+        }
+        if self.bytes == 0 || self.bytes > MAX_FONT_BYTES {
+            return Err(FontFetchError::Integrity(format!(
+                "字体 pin 的字节数 {} 不在 (0, {MAX_FONT_BYTES}] 内",
+                self.bytes
+            )));
+        }
+        Ok(())
+    }
+
+    /// 缓存文件名的哈希段（前 16 位：够区分，又不至于让路径长得没法看）。
+    #[must_use]
+    fn cache_key(&self) -> &str {
+        let end = self.sha256.len().min(16);
+        &self.sha256[..end]
+    }
+}
+
+/// URL 是否可用：**https 一律可以；http 只给回环地址**（单测的回环 HTTP 服务要用）。
+///
+/// 为什么这条要写进校验而不是只写进注释：字体是从网络下来、直接注册进渲染器的东西。明文 http
+/// 在 sha256 钉死的前提下不会导致「内容被换」，但会把「从哪拿」暴露给路上的任何人（可被替换成
+/// 任意大文件来耗流量/磁盘，虽然会被大小上限与哈希挡住）。契约写成「非回环必须 https」，
+/// 注释与实现就是一个口径。
+fn is_acceptable_url(url: &str) -> bool {
+    if url.starts_with("https://") {
+        return true;
+    }
+    let Some(rest) = url.strip_prefix("http://") else {
+        return false;
+    };
+    let host_port = rest.split('/').next().unwrap_or_default();
+    let host = host_port
+        .rsplit_once(':')
+        .filter(|(_, port)| port.chars().all(|c| c.is_ascii_digit()))
+        .map_or(host_port, |(host, _)| host);
+    let host = host.trim_start_matches('[').trim_end_matches(']');
+    matches!(host, "127.0.0.1" | "localhost" | "::1") || host.starts_with("127.")
+}
+
+/// 缓存文件落点：`<数据根>/fonts/cjk-noto-sans-sc-.ttf`。
+///
+/// 文件名带哈希段是刻意的：pin 一改（换字体 / 换子集），新文件自然换名，旧文件不会冒充命中。
+#[must_use]
+pub fn cache_path(cache_root: &Path, spec: &FontSpec) -> PathBuf {
+    cache_root
+        .join("fonts")
+        .join(format!("cjk-noto-sans-sc-{}.ttf", spec.cache_key()))
+}
diff --git a/crates/core/src/download/font/tests.rs b/crates/core/src/download/font/tests.rs
new file mode 100644
index 0000000..06d3123
--- /dev/null
+++ b/crates/core/src/download/font/tests.rs
@@ -0,0 +1,319 @@
+//! `download::font` 的守卫（三条都能变红，变异证明见 M168 报告）。
+//!
+//! ## 离线纪律
+//!
+//! 服务端是 `127.0.0.1` 上的回环监听器，把**内存里的假字体字节**当响应体发出去：不碰任何
+//! 外网站点，跑 `cargo test` 不需要网络。真 CDN 的字节有没有变、17 MiB 要下多久，这些**不在**
+//! 本文件的能力范围内（报告里写明）。
+
+use std::path::Path;
+use std::sync::atomic::Ordering;
+use std::time::Duration;
+
+use super::*;
+
+#[path = "tests/support.rs"]
+mod support;
+
+use support::{dead_url, fake_font, root, serve, serve_trickle, sha256, spec_for};
+
+/// 守卫 ③：**缓存命中不联网**。
+///
+/// 抓得住：把 `fetch_blocking` 开头的缓存分支删掉——URL 指向的死人端口会被真的去连，本用例红。
+/// 抓不住：真机上 17 MiB 文件读盘有多快。
+#[test]
+fn cache_hit_never_touches_the_network() {
+    let dir = root("cache");
+    let body = fake_font(b"cached payload");
+    let spec = spec_for(vec![dead_url()], &body);
+    let path = cache_path(&dir, &spec);
+    std::fs::create_dir_all(path.parent().unwrap()).expect("建字体目录");
+    std::fs::write(&path, &body).expect("预置缓存");
+
+    let fetched = fetch_blocking(&dir, &spec).expect("缓存命中应成功");
+    assert!(fetched.from_cache, "必须报「来自缓存」");
+    assert_eq!(fetched.bytes, body);
+    assert_eq!(fetched.source, "cache");
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+/// 守卫 ②：**sha256 不符时拒绝落盘**（正式路径上什么都不许留下）。
+///
+/// **两层校验是互备的**（复审 r3 顺手项①：上一版这里写「只拆一层也会红」是假的，复审变异实测
+/// 单独拆掉引擎的 `with_sha256` 或单独短路本模块复验，本用例都**仍然绿**——另一层会接住）。
+/// 本用例真正抓的是**两层同时被拆**：那时坏字节会被当成字体返回、`cache_path` 也会落盘，断言在
+/// `expect_err` 处红（r1 的变异证明就是这么打的）。
+///
+/// 抓不住：单层的实现细节（比如 `verify::matches` 的大小写处理）——那要各自的单元用例。
+#[test]
+fn sha256_mismatch_is_refused_and_nothing_lands() {
+    let dir = root("mismatch");
+    let served = fake_font(b"what the cdn claims");
+    let expected = fake_font(b"what the pin expects");
+    let (url, _served) = serve(served.clone(), 4);
+    let spec = FontSpec::new(vec![url], sha256(&expected), served.len() as u64).expect("pin");
+
+    let error = fetch_blocking(&dir, &spec).expect_err("哈希不符必须失败");
+    assert_eq!(error.class(), "integrity", "{error}");
+    let path = cache_path(&dir, &spec);
+    assert!(
+        !path.exists(),
+        "校验不过的字体不许出现在 {}",
+        path.display()
+    );
+    // 字体目录里什么都不该留下：复验在写盘之前，所以连中间态都不存在。
+    let leftovers = std::fs::read_dir(path.parent().unwrap())
+        .map_or(0, |entries| entries.filter_map(Result::ok).count());
+    assert_eq!(leftovers, 0, "校验不过时字体目录必须干净");
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+/// 守卫 ③ 的另一半：**下过一次就再也不下**（同进程第二次调用零请求）。
+///
+/// 抓得住：缓存写失败（换名没做）/ 缓存文件名不带哈希（pin 换了还命中旧文件）/ 每次调用都
+/// 重新下载——第一条与第三条都会让 `served == 2`，本用例红。
+#[test]
+fn the_second_call_is_served_from_the_cache() {
+    let dir = root("second");
+    let body = fake_font(b"payload of the second call");
+    // 服务端最多伺候 4 条请求：若第二次调用又联网，计数会变成 2。
+    let (url, served) = serve(body.clone(), 4);
+    let spec = spec_for(vec![url], &body);
+
+    let first = fetch_blocking(&dir, &spec).expect("第一次应成功");
+    assert!(
+        !first.from_cache,
+        "第一次必须是真下载（否则这条用例什么也没证明"
+    );
+    assert_eq!(first.bytes, body);
+
+    let second = fetch_blocking(&dir, &spec).expect("第二次应命中缓存");
+    assert!(second.from_cache, "第二次不许再联网");
+    assert_eq!(
+        served.load(Ordering::SeqCst),
+        1,
+        "整个过程只该有一条 HTTP 请求"
+    );
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+/// 坏缓存**自愈**：哈希不符的旧文件要被删掉重下，而不是被当成命中，也不是永远挡路。
+#[test]
+fn a_corrupt_cache_file_is_healed_by_a_fresh_download() {
+    let dir = root("heal");
+    let body = fake_font(b"fresh bytes");
+    let spec = spec_for(vec![dead_url()], &body);
+    let path = cache_path(&dir, &spec);
+    std::fs::create_dir_all(path.parent().unwrap()).expect("建字体目录");
+    std::fs::write(&path, fake_font(b"rotten bytes")).expect("预置坏缓存");
+
+    // 坏缓存 + 死人 URL ⇒ 只能报网络错（若把坏文件当命中会返回 Ok，本用例红）。
+    let error = fetch_blocking(&dir, &spec).expect_err("坏缓存不该被当成命中");
+    assert_eq!(error.class(), "network", "{error}");
+    assert!(!path.exists(), "坏缓存必须被删掉");
+
+    // 换成真服务端：同一次进程里重来一次就能落地（自愈）。
+    let (url, _served) = serve(body.clone(), 4);
+    let spec = spec_for(vec![url], &body);
+    let fetched = fetch_blocking(&dir, &spec).expect("自愈后应成功");
+    assert!(!fetched.from_cache);
+    assert!(path.exists());
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+/// CDN 回了一个 HTML 错误页（哈希还对不上/对得上都一样）：不许当字体落盘。
+///
+/// 抓得住：`looks_like_sfnt` 这道闸被删掉——哈希正确时它会让一堆 HTML 进字体系统。
+/// 抓不住：真字体里子集不全这类内容问题（那要 cmap 检查）。
+#[test]
+fn an_html_error_page_is_not_a_font() {
+    let dir = root("html");
+    let body = b"403 Forbidden".to_vec();
+    let (url, _served) = serve(body.clone(), 4);
+    let spec = spec_for(vec![url], &body);
+
+    let error = fetch_blocking(&dir, &spec).expect_err("HTML 不是字体");
+    assert_eq!(error.class(), "integrity", "{error}");
+    assert!(!cache_path(&dir, &spec).exists());
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+/// 守卫（M168 复审 r2 P2-1/P2-3）：**单次尝试的时限会打断爬行连接并转下一个候选**。
+///
+/// 这个场景现在是真的：第一个候选是 `serve_trickle()`（发真实 CRLF 响应头，之后每 100 ms 一个
+/// 字节），第二个候选是正常服务端。
+///
+/// 抓得住：①`serve_trickle` 的响应头写错（上一版就是这个病：真实换行字节 + 4 字节窗口 ⇒ 恒 false
+/// ⇒ 一个字节都不发）——那样第一个候选会在**读不到响应头**时按网络错失败，用例里
+/// `trickle_served` 的「服务端真的发过头」这条断言会红；②`budget` 不是 `min(单次, 剩余)` 而是
+/// 直接用总预算 ⇒ 本用例会等到总预算（5 s）才换源，`elapsed < 3 s` 红；③时限被归成校验失败。
+/// 抓不住：默认值（120 s / 360 s）在真弱网下够不够（那要真 CDN，见报告「未验」）。
+#[test]
+fn a_trickling_candidate_is_cut_by_the_attempt_deadline() {
+    let dir = root("deadline-attempt");
+    let good = fake_font(b"served by the second candidate");
+    let (good_url, _served) = serve(good.clone(), 4);
+    let (trickle_url, proof) = serve_trickle();
+    let spec = FontSpec::new(
+        vec![trickle_url, good_url],
+        sha256(&good),
+        good.len() as u64,
+    )
+    .expect("pin");
+
+    let started = std::time::Instant::now();
+    let fetched = fetch_blocking_with_limits(
+        &dir,
+        &spec,
+        Duration::from_millis(300),
+        Duration::from_secs(5),
+    )
+    .expect("第二个候选应当成功");
+    assert_eq!(fetched.bytes, good);
+    assert!(
+        started.elapsed() < Duration::from_secs(3),
+        "单次上限该在 300 ms 处切断第一个候选，实际 {:?}",
+        started.elapsed()
+    );
+    assert!(cache_path(&dir, &spec).exists());
+    // **这条是「夹具没坏」的判据**（复审 r2 P2-1）：第一个候选必须真的发过响应头、真的挤过字节。
+    // 少了这两条，一个「什么都不发的服务端」也能让本用例绿——那证明的是「连接挂着被掐断」，
+    // 而不是我们想证明的「活着但在爬」。
+    assert!(
+        proof.header.load(Ordering::SeqCst),
+        "爬行服务端必须真的发出响应头"
+    );
+    assert!(
+        proof.dripped.load(Ordering::SeqCst) >= 1,
+        "爬行服务端必须真的挤出过字节（否则引擎的空闲超时那条路径根本没被造出来）"
+    );
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+/// 守卫（M168 复审 r3 P2-3）：**最后一个候选拿整个剩余预算**（`is_last` 那一支）。
+///
+/// 形状是刻意挑的：**单候选** + `attempt = 300 ms` / `total = 5 s`。
+/// * 有 `is_last`：最后一个（也是唯一一个）候选拿到剩下的 ~5 s ⇒ 只在**总时限**处被打断，
+///   耗时 ≈5 s；
+/// * 没有 `is_last`（一律 `attempt.min(remaining)`）：300 ms 就切，耗时 ≈0.3 s。
+///
+/// 两种实现的解不同，于是这条用例能分辨它们——上一版给的是 `attempt=30 s > total=400 ms`，
+/// 两种实现同解，天生测不出差别（复审 r3 就是据此说 `is_last` 没人守）。
+///
+/// 抓得住：删掉 `is_last` 那一支（或把预算写成 `attempt_deadline.min(remaining)` 一视同仁）⇒
+/// `elapsed >= 3 s` 当场红；也抓得住服务端其实不发字节（`proof` 的两个断言）。
+/// 抓不住：真弱网下 60 s / 420 s 够不够（要真 CDN，见报告「未验」）。
+#[test]
+fn the_last_candidate_gets_the_whole_remaining_budget() {
+    let dir = root("deadline-last");
+    let body = fake_font(b"not what the server sends");
+    let (trickle_url, proof) = serve_trickle();
+    let spec = FontSpec::new(vec![trickle_url], sha256(&body), body.len() as u64).expect("pin");
+
+    let started = std::time::Instant::now();
+    let error = fetch_blocking_with_limits(
+        &dir,
+        &spec,
+        Duration::from_millis(300),
+        Duration::from_secs(5),
+    )
+    .expect_err("爬行连接最终必须被总时限打断");
+    let elapsed = started.elapsed();
+
+    assert_eq!(error.class(), "network", "超时属于网络档：{error}");
+    assert!(
+        error.message().contains("超时"),
+        "文案要说得清是超时：{error}"
+    );
+    assert!(
+        elapsed >= Duration::from_secs(3),
+        "最后一个候选该拿整个剩余预算（≈5 s），而不是在 300 ms 处就被切：{elapsed:?}"
+    );
+    assert!(
+        elapsed < Duration::from_secs(9),
+        "不该超过总时限太多：{elapsed:?}"
+    );
+    assert!(!cache_path(&dir, &spec).exists(), "超时不许落盘");
+    assert!(
+        proof.dripped.load(Ordering::SeqCst) >= 1,
+        "这条用例必须掐在「有字节在动」的连接上，而不是一个不响的端口"
+    );
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+/// pin 的 URL 口径：**https 一律可以，http 只给回环**（M168 复审次要项）。
+///
+/// 抓得住：把 `http://` 一律放行（注释说「必须 https」、实现说「随便」的老毛病），
+/// 也抓得住收紧过头（连回环的单测服务都不让用 ⇒ 一批用例会红）。
+#[test]
+fn the_pin_only_accepts_https_or_loopback_http() {
+    let hash = "a".repeat(64);
+    assert!(FontSpec::new(vec!["https://mirror.example/a.ttf"], &hash, 1).is_ok());
+    assert!(FontSpec::new(vec!["http://127.0.0.1:8080/a.ttf"], &hash, 1).is_ok());
+    assert!(FontSpec::new(vec!["http://localhost:9/a.ttf"], &hash, 1).is_ok());
+    assert!(
+        FontSpec::new(vec!["http://127.0.0.2:9/a.ttf"], &hash, 1).is_ok(),
+        "127.0.0.0/8 整个都是回环"
+    );
+    assert!(
+        FontSpec::new(vec!["http://example.com/a.ttf"], &hash, 1).is_err(),
+        "非回环的明文 http 不许过"
+    );
+    assert!(FontSpec::new(vec!["ftp://example.com/a.ttf"], &hash, 1).is_err());
+}
+
+/// pin 自身不合法时**一个请求都不发**（免得为一个坏 pin 白跑一趟网络）。
+#[test]
+fn an_invalid_pin_never_reaches_the_network() {
+    let dir = root("pin");
+    let served = fake_font(b"x");
+    let (url, counter) = serve(served.clone(), 4);
+
+    // 哈希形态不对
+    assert!(FontSpec::new(vec![url.clone()], "not-a-hash", 10).is_err());
+    // 非 http(s)
+    assert!(FontSpec::new(vec!["file:///etc/passwd"], sha256(&served), 10).is_err());
+    // 没有 URL
+    assert!(FontSpec::new(Vec::::new(), sha256(&served), 10).is_err());
+    // 超过大小上限
+    assert!(FontSpec::new(vec![url], sha256(&served), MAX_FONT_BYTES + 1).is_err());
+    // 零字节
+    assert!(FontSpec::new(vec!["https://example.invalid/f.ttf"], sha256(&served), 0).is_err());
+
+    assert_eq!(counter.load(Ordering::SeqCst), 0, "坏 pin 不许发请求");
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+/// `looks_like_sfnt`：只认魔数 + 表目录，不猜内容。
+#[test]
+fn sfnt_sniffing_accepts_fonts_and_rejects_junk() {
+    assert!(looks_like_sfnt(&fake_font(b"x")));
+    // OTF（CFF 轮廓）：魔数 OTTO + 一张表
+    let mut otf = b"OTTO".to_vec();
+    otf.extend_from_slice(&1u16.to_be_bytes());
+    otf.extend_from_slice(&[0u8; 6]);
+    otf.extend_from_slice(&[0u8; 16]);
+    assert!(looks_like_sfnt(&otf));
+    // TTC（字体集合）：长度够就收
+    assert!(looks_like_sfnt(
+        b"ttcf\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00"
+    ));
+    assert!(!looks_like_sfnt(b""));
+    assert!(!looks_like_sfnt(b"\x00\x01\x00\x00\x00\x00")); // 表数 0
+    assert!(!looks_like_sfnt(b"\x00\x01\x00\x00\x00\x02")); // 长度不够装两张表
+    assert!(!looks_like_sfnt(&[]));
+}
+
+/// 缓存文件名带 pin 的哈希段：换 pin（换字体/换子集）⇒ 换文件名 ⇒ 不会命中旧内容。
+#[test]
+fn the_cache_name_changes_with_the_pin() {
+    let dir: &Path = std::path::Path::new("/tmp/ull-font-name");
+    let a = FontSpec::new(vec!["https://x.invalid/a.ttf"], "a".repeat(64), 1).expect("pin a");
+    let b = FontSpec::new(vec!["https://x.invalid/a.ttf"], "b".repeat(64), 1).expect("pin b");
+    assert_ne!(cache_path(dir, &a), cache_path(dir, &b));
+    assert_eq!(
+        cache_path(dir, &a),
+        dir.join("fonts")
+            .join(format!("cjk-noto-sans-sc-{}.ttf", "a".repeat(16)))
+    );
+}
diff --git a/crates/core/src/download/font/tests/support.rs b/crates/core/src/download/font/tests/support.rs
new file mode 100644
index 0000000..89f4eed
--- /dev/null
+++ b/crates/core/src/download/font/tests/support.rs
@@ -0,0 +1,177 @@
+//! `download::font` 的测试夹具（回环 HTTP 服务端 / 假字体字节 / 临时数据根）。
+//!
+//! 从 `tests.rs` 拆出只为守 400 行硬线（复审 r2 加了两条时限用例之后越线）。这里只有夹具，
+//! 断言全在 `tests.rs`——两个回环服务端（`serve` 正常、`serve_trickle` 只爬）是「缓存/校验/时限」
+//! 三组守卫的地基，改坏它们等于把守卫变成空转（复审 r2 P2-1 就是这么发现上一版的
+//! CRLF 字面量写坏了的）。
+
+use std::io::{Read as _, Write as _};
+use std::net::TcpListener;
+use std::path::PathBuf;
+use std::sync::atomic::{AtomicUsize, Ordering};
+use std::sync::Arc;
+use std::time::Duration;
+
+use super::super::super::verify;
+use super::super::{FontSpec, HashAlgo};
+
+/// 每个用例一个独立数据根（共享引擎的登记处是进程级的，键撞了会互相干扰）。
+pub(super) fn root(tag: &str) -> PathBuf {
+    static SEQ: AtomicUsize = AtomicUsize::new(0);
+    let seq = SEQ.fetch_add(1, Ordering::SeqCst);
+    let dir = std::env::temp_dir().join(format!("ull-font-{tag}-{}-{seq}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    std::fs::create_dir_all(&dir).expect("建数据根");
+    dir
+}
+
+/// 一段「像字体」的字节：sfnt 头 + 一张表记录 + 载荷。
+///
+/// 为什么造它而不是塞随机字节：`looks_like_sfnt` 是落盘前的一道闸，测试若拿 HTML 当正常内容，
+/// 「下载成功」这条路径就永远走不到。
+pub(super) fn fake_font(payload: &[u8]) -> Vec {
+    let mut bytes = Vec::new();
+    bytes.extend_from_slice(b"\x00\x01\x00\x00"); // sfnt 版本
+    bytes.extend_from_slice(&1u16.to_be_bytes()); // numTables
+    bytes.extend_from_slice(&[0u8; 6]); // searchRange / entrySelector / rangeShift
+    bytes.extend_from_slice(b"TEST"); // 表名
+    bytes.extend_from_slice(&0u32.to_be_bytes()); // checksum
+    bytes.extend_from_slice(&28u32.to_be_bytes()); // offset
+    bytes.extend_from_slice(&(payload.len() as u32).to_be_bytes());
+    bytes.extend_from_slice(payload);
+    bytes
+}
+
+pub(super) fn sha256(bytes: &[u8]) -> String {
+    verify::digest_bytes(HashAlgo::Sha256, bytes)
+}
+
+/// 回环 HTTP 服务：不管请求什么，都回同一份字节；记下处理了几条请求。
+///
+/// 只讲 HTTP/1.1 keep-alive，够用来判「第二次调用有没有再发请求」。
+pub(super) fn serve(body: Vec, expected_requests: usize) -> (String, Arc) {
+    let listener = TcpListener::bind("127.0.0.1:0").expect("绑定回环端口");
+    let addr = listener.local_addr().expect("取端口");
+    let served = Arc::new(AtomicUsize::new(0));
+    let counter = Arc::clone(&served);
+
+    std::thread::spawn(move || {
+        let mut requests = 0usize;
+        while requests < expected_requests {
+            let Ok((mut socket, _)) = listener.accept() else {
+                break;
+            };
+            let _ = socket.set_read_timeout(Some(Duration::from_secs(10)));
+            let mut seen = Vec::new();
+            loop {
+                let mut chunk = [0u8; 1024];
+                match socket.read(&mut chunk) {
+                    Ok(0) | Err(_) => break,
+                    Ok(read) => seen.extend_from_slice(&chunk[..read]),
+                }
+                if !seen.windows(4).any(|window| window == b"\r\n\r\n") {
+                    continue;
+                }
+                requests += 1;
+                counter.store(requests, Ordering::SeqCst);
+                let head = format!(
+                    "HTTP/1.1 200 OK\r\nContent-Type: font/ttf\r\nContent-Length: {}\r\n\r\n",
+                    body.len()
+                );
+                if socket.write_all(head.as_bytes()).is_err() || socket.write_all(&body).is_err() {
+                    break;
+                }
+                seen.clear();
+                if requests >= expected_requests {
+                    return;
+                }
+            }
+        }
+    });
+
+    (format!("http://{addr}/cjk.ttf"), served)
+}
+
+/// 一个**不会**有人监听的地址：证明「没联网」比证明「联网成功」更有力。
+pub(super) fn dead_url() -> String {
+    let listener = TcpListener::bind("127.0.0.1:0").expect("占一个端口");
+    let addr = listener.local_addr().expect("取端口");
+    drop(listener);
+    format!("http://{addr}/cjk.ttf")
+}
+
+/// 爬行服务端的取证计数器：`header` = 真的发过响应头，`dripped` = 真的挤出过几个字节。
+///
+/// 为什么把这两个数字**带出去**：这类 `serve_*` 夹具坏掉时，用例会静默变成另一种场景
+/// （复审 r2 P2-1 就是：请求头永远读不完 ⇒ 一个字节不发 ⇒ 用例证明的是「连接挂着」，而不是
+/// 「活着但在爬」）。用例拿到这两个数就能断言「服务端确实在说话」。
+pub(super) struct TrickleProof {
+    /// 响应头是否真的写出去了。
+    pub header: Arc,
+    /// 写出去了几个正文字节。
+    pub dripped: Arc,
+}
+
+/// 由 URL 候选 + 期望字节算 pin（哈希取这批字节的 sha256）。
+pub(super) fn spec_for(urls: Vec, bytes: &[u8]) -> FontSpec {
+    FontSpec::new(urls, sha256(bytes), bytes.len() as u64).expect("pin 应自洽")
+}
+
+/// 爬行服务端：回完头之后每 100 ms 只挤 1 字节，**永远不结束**。
+///
+/// 这就是复审 r1 P2-2 实测到的那条路径（Fastly 的 IPv6 边缘 ≈67 KB/s）：引擎的 `read_timeout`
+/// 是 30 s **空闲**超时，而字节一直在动 ⇒ 引擎自己永远不会判它失败。只有我们这一层的整体时限
+/// 能打断它——这条服务端存在的唯一目的就是造出「活着但爬」的连接。
+///
+/// 注意这里的 `\r\n` 必须是**转义写法**：上一版这个函数里写成了真实换行字节（`b"\n\n"`，2 字节）
+/// 却拿 4 字节窗口去比，`PartialEq` 先比长度 ⇒ 恒 false ⇒ 请求头永远读不完、一个字节都不发，
+/// 用例证明的其实是另一件事（复审 r2 P2-1）。`serve()` 那边的写法是对的，别动它。
+pub(super) fn serve_trickle() -> (String, TrickleProof) {
+    let header_sent = Arc::new(std::sync::atomic::AtomicBool::new(false));
+    let dripped = Arc::new(AtomicUsize::new(0));
+    let (header_flag, drip_flag) = (Arc::clone(&header_sent), Arc::clone(&dripped));
+    let listener = TcpListener::bind("127.0.0.1:0").expect("绑定回环端口");
+    let addr = listener.local_addr().expect("取端口");
+    std::thread::spawn(move || {
+        let Ok((mut socket, _)) = listener.accept() else {
+            return;
+        };
+        let _ = socket.set_read_timeout(Some(Duration::from_secs(5)));
+        // 先把请求头读干净（不读完就写响应，某些栈会 RST）。
+        let mut seen = Vec::new();
+        loop {
+            let mut chunk = [0u8; 1024];
+            match socket.read(&mut chunk) {
+                Ok(0) | Err(_) => return,
+                Ok(read) => seen.extend_from_slice(&chunk[..read]),
+            }
+            if seen.windows(4).any(|window| window == b"\r\n\r\n") {
+                break;
+            }
+        }
+        // 声明一个够大的长度，然后开始「爬」：每 100 ms 一个字节。
+        if socket
+            .write_all(
+                b"HTTP/1.1 200 OK\r\nContent-Type: font/ttf\r\nContent-Length: 1000000\r\n\r\n",
+            )
+            .is_err()
+        {
+            return;
+        }
+        header_flag.store(true, Ordering::SeqCst);
+        for _ in 0..600 {
+            if socket.write_all(&[0u8]).is_err() {
+                return;
+            }
+            drip_flag.fetch_add(1, Ordering::SeqCst);
+            std::thread::sleep(Duration::from_millis(100));
+        }
+    });
+    (
+        format!("http://{addr}/cjk.ttf"),
+        TrickleProof {
+            header: header_sent,
+            dripped,
+        },
+    )
+}
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, 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,
+    /// 最后更新时间（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,
+    entries: Mutex>,
+    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, 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/` 根目录打开（**生产接线用这一条**）：文件固定在 `/health.json`，
+    /// 保留期用默认值。
+    #[must_use]
+    pub fn open_in(cache_root: impl AsRef, 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> {
+        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 {
+        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,
+}
+
+/// 读盘：不存在/损坏/超龄都只丢掉对应记录，绝不阻断启动。
+pub(crate) fn load(path: &Path, max_age_ms: u64, now_ms: u64) -> HashMap {
+    let mut entries = HashMap::new();
+    let Ok(bytes) = std::fs::read(path) else {
+        return entries;
+    };
+    match serde_json::from_slice::(&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) -> 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..9db7b1e
--- /dev/null
+++ b/crates/core/src/download/http.rs
@@ -0,0 +1,228 @@
+//! 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;
+
+/// 站点可见的 `User-Agent`：`<产品名>/<版本> (+<仓库 URL>)`。**全仓唯一一份**（M207）。
+///
+/// 三段各自有理由：
+/// * `Unlucky-Launcher` —— 连字符写法（与仓库名一致）。此前引擎那一份是 `UnluckyLauncher`，于是同一个
+///   产品对 Modrinth 与 CurseForge 报两个名字；
+/// * 版本取 `CARGO_PKG_VERSION` —— 写死的话只会一年一年落后（M205 之前写死成 `0.1`，那时版本已是 0.2.3）；
+/// * `(+https://github.com/AskaEth/Unlucky-Launcher)` —— Modrinth 的 UA 政策要求带联系方式，否则限流。
+///   联系方式用**仓库 URL**、不用邮箱：这个字符串会出现在公开流量里。
+///
+/// 消费者两处，都是引用、不是副本：`EngineConfig::default().user_agent`（[`super::config`] 取它），
+/// 与 [`build_client`] 的 `.user_agent(…)`（reqwest 客户端的默认 UA）。于是引擎的每一条请求——包括
+/// presenter 里 `engine.client()` 直发的那条——发的都是这一份。
+pub const USER_AGENT: &str = concat!(
+    "Unlucky-Launcher/",
+    env!("CARGO_PKG_VERSION"),
+    " (+https://github.com/AskaEth/Unlucky-Launcher)"
+);
+
+/// 构造共享的 `reqwest::Client`（连接池、超时、重定向策略一次定好）。
+pub fn build_client(cfg: &EngineConfig) -> Result {
+    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 {
+    header_str(headers, CONTENT_LENGTH).and_then(|value| value.trim().parse().ok())
+}
+
+/// `ETag`（续传的强校验器）。
+#[must_use]
+pub fn etag(headers: &HeaderMap) -> Option {
+    header_str(headers, ETAG).map(str::to_string)
+}
+
+/// `Last-Modified`（弱校验器，ETag 缺失时的兜底）。
+#[must_use]
+pub fn last_modified(headers: &HeaderMap) -> Option {
+    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,
+    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, USER_AGENT};
+
+    fn headers(content_type: Option<&str>, length: Option) -> 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);
+    }
+
+    /// UA 的三段都得对：产品名连字符写法、版本 == `CARGO_PKG_VERSION`、联系方式是仓库 URL 且不是邮箱。
+    ///
+    /// 为什么不是「编译过就行」：`concat!` 只保证拼得起来——版本写回字面量、`(+…)` 那一段被顺手删掉、
+    /// 产品名改回无连字符写法，都照样编得过。而这条 UA 会真的发到 Modrinth（M207 之前发的不是它）。
+    ///
+    /// 抓得住：版本写死（`0.1` / `0.2` / 与 `CARGO_PKG_VERSION` 不等的任何值）⇒ 红；产品名回到
+    /// `UnluckyLauncher`（无连字符）⇒ 红；联系方式段被删、被改或换成邮箱 ⇒ 红。
+    /// 抓不住：真实 Modrinth / CurseForge 收到这条 UA 之后怎么限流（单测不出网），也抓不住
+    /// 「仓库 URL 那个仓库还在不在」——这里钉的是字符串形状，不是站点的接受度。
+    #[test]
+    fn the_user_agent_carries_the_package_version_and_the_repo_url() {
+        let ua = USER_AGENT;
+        let rest = ua
+            .strip_prefix("Unlucky-Launcher/")
+            .expect("产品名是连字符写法（与仓库名一致）");
+        let (version, contact) = rest.split_once(' ').expect("版本之后是联系方式段");
+        assert_eq!(version, env!("CARGO_PKG_VERSION"), "UA: {ua}");
+        assert_eq!(
+            contact, "(+https://github.com/AskaEth/Unlucky-Launcher)",
+            "联系方式那一段是 Modrinth 的 UA 政策要求，不许顺手删：{ua}"
+        );
+        assert!(
+            !ua.contains('@'),
+            "联系方式用仓库 URL、不用邮箱（公开流量里不放个人联系方式）：{ua}"
+        );
+    }
+}
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,
+    /// 国内镜像（实测为空数组：三家云都没有 MS OpenJDK）。
+    #[serde(default)]
+    pub domestic_mirrors: Vec,
+    /// 实测吞吐（展示用）。
+    #[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 {
+        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..49a0434
--- /dev/null
+++ b/crates/core/src/download/mirrors.json
@@ -0,0 +1,181 @@
+{
+  "version": 3,
+  "notes": [
+    "M225（规则修订，version 仍为 3）：① bmclapi-liteloader 关闭——2026-11-10 实测镜像侧全 404，LiteLoader 走官方直连；② 新增 bmclapi-maven-central，把 repo1.maven.org 的库接到 bmclapi 的 /maven（实测逐字节一致）；③ 快照仓 repo.mumfrey.com 无任何镜像，登记为「不加速」。**不升 version 的原因**：v4 会把 `download/jdk_sources.rs::builtin_table_is_v3_with_all_four_source_families` 与 `tests/game/java_vendor_chain.rs`（`mirror_table_v3_registers_all_four_source_families`）里的 `version == 3` pin 弄红，升版得同时改那两处——本轮只修规则，version 的世代标记留给一次专门的升版。",
+    "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。",
+    "LiteLoader 的 bmclapi 改写已关闭（bmclapi-liteloader.enabled=false，规则保留作形状留档）：2026-11-10 实探 curl -sS -L -o /dev/null -w '%{http_code} %{size_download}' —— 官方 https://dl.liteloader.com/versions/versions.json 200 / 49129 B、.../com/mumfrey/liteloader/1.7.10/liteloader-1.7.10_04.jar 200 / 533903 B；镜像侧（`apply()` 的真实产物：`from` 吃掉 `/versions` 后剩下 `/versions.json`）https://bmclapi2.bangbang93.com/maven/versions.json 404 / 9 B、/maven/com/mumfrey/liteloader/1.7.10/liteloader-1.7.10_04.jar 404 / 9 B、/maven/com/mumfrey/liteloader/{maven-metadata.xml,1.12.2-SNAPSHOT/maven-metadata.xml} 也是 404 / 9 B。（任务描述里的 `/maven/versions/versions.json` 也实测 404，但那条双段路径不是这条规则拼出来的，别照样抄。）引擎遇 404 会前进到官方（NotFound 不重试），所以留着这条只会让镜像优先用户每个文件白丢一次请求；官方不可达时更是直接失败。",
+    "bmclapi-maven-central 的依据：bmclapi 的 /maven 是真的 maven 代理（不止 libraries.minecraft.net）。2026-11-10 实测 —— 官方 repo1.maven.org 与镜像 200 且字节数一致、sha1 逐一相同：org/ow2/asm/asm-all/5.2 (247787 B)、com/google/code/gson/gson/2.10.1 (283367 B)、org/apache/logging/log4j/log4j-core/2.17.1 (1790452 B)，另有 asm 9.3 / asm-util 9.3 / jna 5.13.0 / annotations 24.0.1 字节数一致；不存在的坐标两侧都是 404（镜像回 9 B 纯文本，无「200 + HTML」假阳性）。注意两点：① 镜像还是上游的超集（org/spongepowered/mixin/0.8.5 在 Central 是 404、镜像 200 / 1089277 B），命中超集不影响校验（清单自带 sha1）；② 镜像对 Range 请求回 200 全量而非 206，所以这条规则只对不走分块的资源有实际意义（库文件是 Library，本来就 not prefers_chunked）。",
+    "快照仓不加速（不登记规则）：LiteLoader 的快照分支固定在 https://repo.mumfrey.com/content/repositories/snapshots/（M222 的 SNAPSHOT_REPO）。2026-11-10 实测官方 .../com/mumfrey/liteloader/1.12.2-SNAPSHOT/maven-metadata.xml 200 / 358 B，而候选镜像 bmclapi /maven 404 / 9 B、maven.aliyun.com/repository/central 404 / 689 B、repo.huaweicloud.com/repository/maven 404 / 394 B —— 没有任何镜像有 com/mumfrey，所以这条还是直连，别按「同族都该有镜像」的直觉加规则。",
+    "repo.maven.apache.org（Central 的官方别名）实测 200 / 247787 B，镜像同路径也 200 / 247787 B，但本仓库没有任何生产代码用这个 host（发行版库基址用的是 repo1.maven.org），所以不登记第二条规则——要用时再加，别为「可能有人用」提前铺。"
+  ],
+  "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 列表，带 
；归档旁有 .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",
+      "inject": "/maven"
+    },
+    {
+      "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-maven-central",
+      "from": "https://repo1.maven.org/maven2",
+      "to": "https://bmclapi2.bangbang93.com/maven"
+    },
+    {
+      "id": "bmclapi-liteloader",
+      "from": "https://dl.liteloader.com/versions",
+      "to": "https://bmclapi2.bangbang93.com/maven",
+      "enabled": false
+    },
+    {
+      "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..31fca8d
--- /dev/null
+++ b/crates/core/src/download/mirrors.rs
@@ -0,0 +1,356 @@
+//! 镜像清单与 URL 前缀重写。
+//!
+//! 内置清单 `mirrors.json` 随源码嵌入（`include_str!`），发行后可由设置层追加自定义规则。
+//! 重写语义承 analyse/03 §5.2 的「前缀替换而非全量重写」——保留子路径，因此 `/libraries`、
+//! `/maven`、`/fabric-meta` 这类子路径天然兼容；`inject` 用于补上路径形状不同的场景
+//! （资源对象：官方 `/`，BMCLAPI `/assets//`）。
+//!
+//! 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,
+    /// 是否启用（设置层可关）。
+    #[serde(default = "default_true")]
+    pub enabled: bool,
+}
+
+impl PrefixRule {
+    /// 构造一条最简规则。
+    #[must_use]
+    pub fn new(id: impl Into, from: impl Into, to: impl Into) -> 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) -> 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 {
+        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,
+    /// 前缀重写规则（前面的优先）。
+    #[serde(default)]
+    pub rules: Vec,
+    /// Adoptium 院校镜像。
+    #[serde(default)]
+    pub adoptium: Vec,
+    /// Oracle OpenJDK 镜像（v3 新增）。
+    #[serde(default)]
+    pub oracle_openjdk: Vec,
+    /// Microsoft OpenJDK 分发模板（v3 新增）。
+    #[serde(default)]
+    pub microsoft_openjdk: Option,
+    /// Zulu 元数据（v3 新增）。
+    #[serde(default)]
+    pub zulu: Option,
+    /// gh-proxy 类前缀（**目前无生产读者**：生效前缀的唯一真相源是 `RegionProfile.gh_proxy`；
+    /// 这一列只作为 `mirrors.json` 的解析留档，别再按它做「改这里能生效」的接口）。
+    #[serde(default)]
+    pub gh_proxies: Vec,
+}
+
+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 {
+        serde_json::from_str(json)
+    }
+
+    /// 序列化成 JSON（诊断页/用户自定义文件回写用）。
+    pub fn to_json_pretty(&self) -> Result {
+        serde_json::to_string_pretty(self)
+    }
+
+    /// 追加用户自定义规则（插到最前，优先于内置规则）。
+    pub fn add_custom_rule(&mut self, rule: PrefixRule) {
+        self.rules.insert(0, rule);
+    }
+
+    /// 找到第一条命中的前缀规则。
+    #[must_use]
+    pub fn prefix_rule_for(&self, url: &str, kind: ResourceKind) -> Option<&PrefixRule> {
+        self.rules.iter().find(|rule| rule.matches(url, kind))
+    }
+
+    /// GitHub host 且允许时套 gh-proxy 前缀。
+    ///
+    /// **生效前缀的唯一真相源是 `region.gh_proxy`**（设置层/地区判定写入，`None` = 用户关闭）。
+    /// 表格里的 `gh_proxies` 只是「已知可用前缀」的留档（无生产读者），**改它不会生效**——M193
+    /// 删掉了原先那个 `MirrorTable::set_gh_proxy`，正是因为它改了这张表而 `expand()` 读的是档案，
+    /// 属于「看起来能改、其实没人读」的入口。
+    #[must_use]
+    pub fn gh_proxy_candidates(&self, url: &str, region: &RegionProfile) -> Vec {
+        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 {
+        let official = Candidate::new(direct_source_id(url), url);
+        let mut mirrors: Vec = 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, 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..fbccf5e
--- /dev/null
+++ b/crates/core/src/download/mod.rs
@@ -0,0 +1,99 @@
+//! 下载引擎：多源健康度、指数退避、分层下载（大文件分块）、边下边算、原子落盘。
+//!
+//! 设计定稿：`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     错误分类
+//! shared        进程级共享：一个数据根一个引擎（跨请求复用连接池/限流/健康度）
+//! ```
+//!
+//! 宿主侧**不要**每次请求现建引擎：`download::shared::engine_for()` 拿到的是进程内
+//! 共享的那个，连接池、信号量限流、健康度记忆因此跨请求累积（M165）。
+//!
+//! 落盘守卫（[`PartFile`]）中间文件名是 `.ullpart--`：`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 font;
+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 shared;
+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::font::{
+    cache_path, fetch_blocking, FontFetch, FontFetchError, FontSpec, MAX_FONT_BYTES,
+};
+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..e63b722
--- /dev/null
+++ b/crates/core/src/download/progress.rs
@@ -0,0 +1,202 @@
+//! 进度事件与发射器。
+//!
+//! 事件是「字节级 + 文件级」双层的载体（设计文档 §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,
+    },
+    /// 字节级进度（节流后）。
+    Progress {
+        /// 关联 id。
+        id: DownloadId,
+        /// 已下载字节。
+        downloaded: u64,
+        /// 总字节数（未知为 `None`）。
+        total_bytes: Option,
+    },
+    /// 某个源失败（单次尝试）。
+    SourceFailed {
+        /// 关联 id。
+        id: DownloadId,
+        /// 源标识。
+        source: String,
+        /// 失败分类（**结构化**：文案层按这个类型选 i18n key，`reason` 只进日志）。
+        ///
+        /// M197 补的：在这之前只有 `reason`（core 的中文句子），GUI 要么放弃双语、
+        /// 要么放弃「命中哪个源 / 为什么退避」这一条用户可见信息。
+        kind: DownloadErrorKind,
+        /// 失败原因（短描述）。
+        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>,
+}
+
+impl ProgressEmitter {
+    /// 静默发射器（测试、后台静默下载用）。
+    #[must_use]
+    pub const fn silent() -> Self {
+        Self { tx: None }
+    }
+
+    /// 建一对（发射器, 接收端）；接收端由 app 层转成 IPC DTO。
+    #[must_use]
+    pub fn channel() -> (Self, UnboundedReceiver) {
+        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,
+}
+
+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,
+    /// 是否做过网络探测（设置里可关）。
+    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,
+    /// 系统语言列表（BCP-47 或 POSIX locale，取首个非空即可）。
+    pub languages: Vec,
+    /// google 可达性（`None` = 未探测/探测被关）。
+    pub google_reachable: Option,
+    /// baidu 可达性（诊断信息，暂不参与判定）。
+    pub baidu_reachable: Option,
+}
+
+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, Option) {
+    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 {
+    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..e01c8fe
--- /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 crate::platform::child::quiet;
+
+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 {
+    let output = quiet("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 {
+    let output = quiet("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 {
+    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,
+    /// 响应 `Last-Modified`。
+    pub last_modified: Option,
+    /// 响应告知的总长度。
+    pub total: Option,
+    /// 摘要算法。
+    pub algo: HashAlgo,
+    /// 期望摘要。
+    pub hash: String,
+    /// 保存时间（unix 毫秒）。
+    pub saved_at_ms: u64,
+}
+
+impl ResumeMeta {
+    /// 从磁盘读（不存在/损坏 → `None`）。
+    #[must_use]
+    pub fn load(path: &Path) -> Option {
+        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,
+    /// 弱校验器。
+    pub last_modified: Option,
+}
+
+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,
+) -> 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) -> 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/shared.rs b/crates/core/src/download/shared.rs
new file mode 100644
index 0000000..c1ead3a
--- /dev/null
+++ b/crates/core/src/download/shared.rs
@@ -0,0 +1,398 @@
+//! 进程级共享引擎：**一个数据根一个 `DownloadEngine`**，跨请求复用。
+//!
+//! # 为什么要有这一层（M165）
+//!
+//! 在此之前，宿主侧每处理一次「请求」（一次检索 / 一次详情 / 一次装文件 / 一次拉清单）都会
+//! 现建一个引擎（`DownloadEngine::new`）。建的时候什么都会重新来一遍，于是下面这些**跨请求
+//! 本该积累的状态每次都清零**：
+//!
+//! | 引擎里的东西 | 每建一次就丢什么 |
+//! |--------------|------------------|
+//! | `reqwest::Client`（`http::build_client`） | 整条连接池：每个请求重新 TCP + TLS 握手 |
+//! | `Semaphore`（`max_concurrency`） | 限流变成「每请求 64」，N 个并发请求 = 64×N 条在飞 |
+//! | `HealthRegistry`（`open_in`） | 从盘上重读 `health.json`；`last_save_ms` 被重置成「现在」⇒ 收尾那次 `flush()` 落在 5s 节流窗口里直接返回，**这个短命引擎记下的失败数一并丢掉**（只有「进/出冷却」会立刻落盘） |
+//! | `ContentCache`（`open`） | 从盘上重读并解析整份 `index.json`；`persist()` 用**本请求这一份内存索引**覆写全文件 ⇒ 两个并发请求各自覆写，后写的把先写的登记条目冲掉 |
+//! | `MirrorTable::builtin()` | 重新解析一遍内置 `mirrors.json` |
+//! | 地区档案 + `Jitter` | 重读 `region.json`；抖动序列重新播种 |
+//!
+//! 失败分类、镜像回退、`Retry-After` 语义一概不动——复用只改「谁来建、建几次」，不改
+//! [`DownloadEngine`] 内部的任何判定。
+//!
+//! # 边界（谁持有 / 活多久 / 并发多少）
+//!
+//! * **谁持有**：本模块的进程级登记处（`OnceLock>`），键是**数据根的缓存目录**
+//!   （`/cache`）。同一数据根的多次请求拿到同一个 `Arc`；
+//!   不同数据根各有一份，缓存/健康度不会串味（有测试钉住这一条）。
+//! * **活多久**：跟随进程。登记处**不做淘汰**——淘汰会让后续请求建出第二个引擎，同一个根上
+//!   同时存在两条连接池，等于把要修的问题换个地方复现。要让地区判定等「一次性派生值」重算，
+//!   用 [`forget`] 显式失效（设置页「重新检测地区」就这么做）。
+//! * **`forget` 到什么范围**：只让登记处不再持有那一份。**已经拿到 `Arc` 的人继续用旧的**：
+//!   短命请求自然结束（它们的窗口只有一次下载），但**长命持有者必须自己重建**——presenter 的
+//!   自更新子系统（`host::update::Factory`）从 `CoreHost::build` 起就把引擎存在字段里，
+//!   只 forget 的话它会一直用旧实例（含旧地区档案）直到进程结束。所以「重新检测地区」那条
+//!   设置动作除了 [`forget`] 还调 `CoreHost::refresh_update_factory()` 把新引擎接过去
+//!   （M165 复审 P2-1：这是本模块文档原先说漏的一半）。
+//! * **并发多少**（M193）：容量来自设置 `download.concurrency`（出厂 8、硬上限 64，见 [`set_tuning`]），
+//!   而且是**进程级**上限——多请求并发时分摊这批许可，不是「每请求 8」。
+//! * **镜像切换 / 失效**：一律走引擎原有的候选规划 + 健康度冷却，本模块不参与判定；唯一可见的
+//!   差别是健康度记忆现在真的跨请求累积（这本就是它存在的理由）。
+//!
+//! # 与 [`super::blocking::block_on`] 的绑定关系
+//!
+//! `reqwest` 的连接池绑在**驱动连接的运行时**上：引擎复用了而每次 `block_on` 都新起一个运行时，
+//! 池里的空闲连接就属于已销毁的运行时，复用会退化成「拿到的都是死连接」。所以引擎复用必须配
+//! 运行时常驻（`blocking` 那一头一并改成进程内唯一运行时）。两者是同一件事的两半。
+
+use std::collections::HashMap;
+use std::path::{Path, PathBuf};
+use std::sync::{Arc, Mutex, OnceLock};
+
+use super::cache::{now_ms, ContentCache};
+use super::config::{publish, wanted, DownloadTuning, EngineConfig};
+use super::engine::DownloadEngine;
+use super::health::HealthRegistry;
+use super::mirrors::MirrorTable;
+use super::region::{decide_from, load_cached, store_cached};
+use super::region_system::detect_signals;
+
+mod tuned;
+pub use tuned::engine_with_tuning;
+
+/// 登记处：缓存根 → 引擎。
+fn registry() -> &'static Mutex>> {
+    static ENGINES: OnceLock>>> = OnceLock::new();
+    ENGINES.get_or_init(|| Mutex::new(HashMap::new()))
+}
+
+/// 「这个根建过几次引擎」的账本（守卫/诊断用，**不**随 [`forget`] 清零）。
+///
+/// 与 [`registry`] **分两把锁**：记账发生在 `DownloadEngine::new` 里（见 [`record_build`]），
+/// 而 [`engine_for`] 是**持着**登记处那把锁去调构造的——合成一把锁就是自己等自己。
+fn ledger() -> &'static Mutex> {
+    static BUILDS: OnceLock>> = OnceLock::new();
+    BUILDS.get_or_init(|| Mutex::new(HashMap::new()))
+}
+
+/// 缓存根的键：去掉尾部分隔符（`D:/x/cache` 与 `D:/x/cache/` 视作同一根）。
+fn key_of(cache_root: &Path) -> PathBuf {
+    let text = cache_root.to_string_lossy();
+    let trimmed = text.trim_end_matches(['/', '\\']);
+    if trimmed.is_empty() {
+        cache_root.to_path_buf()
+    } else {
+        PathBuf::from(trimmed)
+    }
+}
+
+/// 取该数据根上的共享引擎（第一次调用时构造，之后一律复用）。
+///
+/// 构造过程只做本地 I/O（读 `region.json` / `health.json` / `index.json`，解析内置
+/// `mirrors.json`），**不联网**；因此持锁构造不会把网络等待带进临界区。
+#[must_use]
+pub fn engine_for(cache_root: impl AsRef) -> Arc {
+    let key = key_of(cache_root.as_ref());
+    let mut engines = registry()
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner());
+    if let Some(engine) = engines.get(&key) {
+        return Arc::clone(engine);
+    }
+    let engine = Arc::new(build(&key));
+    engines.insert(key, Arc::clone(&engine));
+    engine
+}
+
+/// 让该数据根的共享引擎失效（下次 [`engine_for`] 重新构造）。
+///
+/// **只让登记处不再持有那一份**：已经拿到 `Arc` 的人继续用旧的。短命请求自然结束；长命持有者
+/// （presenter 的自更新 `Factory`）必须自己重建——「重新检测地区」那条设置动作就补调了
+/// `CoreHost::refresh_update_factory()`。返回是否真淘汰了一份。
+pub fn forget(cache_root: impl AsRef) -> bool {
+    registry()
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner())
+        .remove(&key_of(cache_root.as_ref()))
+        .is_some()
+}
+
+/// 记一笔「这个缓存根上又造了一个引擎」。
+///
+/// **唯一调用点是 [`DownloadEngine::new`]**（不是 [`engine_for`]）：记账卡在构造这个卡口上，
+/// [`constructions`] 才是「进程里真实构造过几次」，与谁造的无关（M165 复审备注 2）。
+pub(crate) fn record_build(cache_root: &Path) {
+    *ledger()
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner())
+        .entry(key_of(cache_root))
+        .or_default() += 1;
+}
+
+/// 该数据根在本进程里**实际构造过几次引擎**（不论谁构造的）：复用成立时停在 `1`（`forget`
+/// 之后每重建一次 +1）。只断言「结果一样」测不出复用——引擎建几次都能下同一个文件。
+#[must_use]
+pub fn constructions(cache_root: impl AsRef) -> usize {
+    ledger()
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner())
+        .get(&key_of(cache_root.as_ref()))
+        .copied()
+        .unwrap_or(0)
+}
+
+/// 真实构造（**presenter 侧**唯一一处 `DownloadEngine::new` 的宿主装配；CLI 走 [`engine_with_tuning`]）。
+/// 装配参数从该数据根的 [`wanted`] 取，不用裸 `EngineConfig::default()`（M193）：并发 → `Semaphore`
+/// 容量、尝试次数 → `attempts_for()` 上限、gh_proxy → 地区档案（`expand()` 只认档案里那个前缀）。
+fn build(cache_root: &Path) -> DownloadEngine {
+    let now = now_ms();
+    let tune = wanted(cache_root);
+    let region_path = cache_root.join("region.json");
+    let region = load_cached(®ion_path, now).unwrap_or_else(|| {
+        let profile = decide_from(&detect_signals(), now);
+        let _ = store_cached(®ion_path, &profile);
+        profile
+    });
+    DownloadEngine::new(
+        tune.apply_to(EngineConfig::default()),
+        Arc::new(MirrorTable::builtin()),
+        Arc::new(tune.apply_gh_proxy(region)),
+        Arc::new(HealthRegistry::open_in(cache_root, now)),
+        Arc::new(ContentCache::open(cache_root)),
+    )
+}
+
+/// 换该数据根的下载调优（宿主取引擎前 / 设置变更时调用），返回**是否真的变了**。变了就清掉该根的
+/// 登记项，下次 [`engine_for`] 按新参数重建——否则「改了设置要重启才生效」。已拿到 `Arc` 的长命
+/// 持有者继续用旧的（与 [`forget`] 同一条边界）；自更新 `Factory` 由 dispatch 侧换引擎。
+/// **锁序**：`publish` 的锁先释放再拿登记处的锁，[`build`] 反之——两段不嵌套。
+pub fn set_tuning(cache_root: impl AsRef, next: DownloadTuning) -> bool {
+    let key = key_of(cache_root.as_ref());
+    if !publish(&key, next) {
+        return false;
+    }
+    let _ = registry()
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner())
+        .remove(&key);
+    true
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// 每个用例一个独立数据根（登记处与调优都是进程级、按根存，键撞了会互相干扰）。
+    fn root(tag: &str) -> PathBuf {
+        static SEQ: std::sync::atomic::AtomicUsize = std::sync::atomic::AtomicUsize::new(0);
+        let seq = SEQ.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
+        let dir =
+            std::env::temp_dir().join(format!("ull-shared-{tag}-{}-{seq}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        std::fs::create_dir_all(&dir).expect("建缓存根");
+        dir
+    }
+
+    /// 守卫：同一个根上「多次请求」只构造一个引擎（**断言构造次数，不是只看结果**）。
+    ///
+    /// 抓得住的变异：把 [`engine_for`] 里的 `engines.get` 命中分支删掉（每次现建），
+    /// 本用例立刻红在 `constructions == 1` 与 `Arc::ptr_eq` 两处。
+    #[test]
+    fn one_engine_per_cache_root() {
+        let dir = root("one");
+        let first = engine_for(&dir);
+        let second = engine_for(&dir);
+        assert_eq!(constructions(&dir), 1, "同一根只该构造一次引擎");
+        assert!(Arc::ptr_eq(&first, &second), "两次请求必须是同一个引擎");
+        // 尾部分隔符不该被当成另一个根。
+        let with_sep = PathBuf::from(format!("{}/", dir.display()));
+        assert!(
+            Arc::ptr_eq(&first, &engine_for(&with_sep)),
+            "尾部分隔符不该造成第二个引擎"
+        );
+        assert_eq!(constructions(&dir), 1);
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    /// 两个数据根**不共享**引擎：缓存 / 健康度串味比多建一个引擎严重得多。
+    #[test]
+    fn different_cache_roots_do_not_share() {
+        let a = root("a");
+        let b = root("b");
+        let engine_a = engine_for(&a);
+        let engine_b = engine_for(&b);
+        assert!(!Arc::ptr_eq(&engine_a, &engine_b));
+        assert_eq!(constructions(&a), 1);
+        assert_eq!(constructions(&b), 1);
+        assert_eq!(engine_a.cache().root(), a.as_path());
+        assert_eq!(engine_b.cache().root(), b.as_path());
+        std::fs::remove_dir_all(&a).ok();
+        std::fs::remove_dir_all(&b).ok();
+    }
+
+    /// 失效后重建（设置页「重新检测地区」依赖这条语义）。
+    #[test]
+    fn forget_rebuilds_once() {
+        let dir = root("forget");
+        let before = engine_for(&dir);
+        assert!(forget(&dir), "已存在的引擎应被淘汰");
+        assert!(!forget(&dir), "淘汰后不该再有可淘汰的");
+        let after = engine_for(&dir);
+        assert!(!Arc::ptr_eq(&before, &after));
+        assert_eq!(constructions(&dir), 2, "失效一次 = 多构造一次");
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    /// 离线回环 HTTP 服务：记下「接受了几条连接 / 处理了几条请求」。
+    ///
+    /// 只回固定 JSON、只讲 HTTP/1.1 keep-alive，够用来判「两次下载有没有复用同一条连接」。
+    fn loopback_server(
+        expected_requests: usize,
+    ) -> (String, std::sync::mpsc::Receiver<(usize, usize)>) {
+        use std::io::{Read as _, Write as _};
+        use std::net::TcpListener;
+
+        let listener = TcpListener::bind("127.0.0.1:0").expect("绑定回环端口");
+        let addr = listener.local_addr().expect("取端口");
+        let (tx, rx) = std::sync::mpsc::channel();
+        std::thread::spawn(move || {
+            let mut conns = 0usize;
+            let mut requests = 0usize;
+            while requests < expected_requests {
+                let Ok((mut socket, _)) = listener.accept() else {
+                    break;
+                };
+                conns += 1;
+                let _ = socket.set_read_timeout(Some(std::time::Duration::from_secs(5)));
+                let mut seen = Vec::new();
+                loop {
+                    let mut chunk = [0u8; 1024];
+                    match socket.read(&mut chunk) {
+                        Ok(0) | Err(_) => break,
+                        Ok(read) => seen.extend_from_slice(&chunk[..read]),
+                    }
+                    if !seen.windows(4).any(|window| window == b"\r\n\r\n") {
+                        continue;
+                    }
+                    requests += 1;
+                    let body = br#"{"ok":true}"#;
+                    let head = format!(
+                        "HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\n\r\n",
+                        body.len()
+                    );
+                    if socket.write_all(head.as_bytes()).is_err() || socket.write_all(body).is_err()
+                    {
+                        break;
+                    }
+                    seen.clear();
+                    if requests >= expected_requests {
+                        let _ = tx.send((conns, requests));
+                        return;
+                    }
+                }
+            }
+            let _ = tx.send((conns, requests));
+        });
+        (format!("http://{addr}/meta.json"), rx)
+    }
+
+    /// **复用真的落到连接上**：同一个引擎跨两次 `block_on` 取同一个 host，只应该拨号一次。
+    ///
+    /// 这条钉住的是「引擎复用」与「运行时常驻」必须成对出现的那半个承诺：只复用引擎、
+    /// 每次 `block_on` 新起运行时的话，连接池里的空闲连接属于已销毁的运行时，
+    /// 第二次请求会重新 TCP 握手——`conns` 就是 2 而不是 1。
+    ///
+    /// 离线可跑：服务端是 127.0.0.1 的回环监听器，不碰任何外网站点。
+    #[test]
+    fn pooled_connection_survives_across_block_on_calls() {
+        use super::super::blocking::block_on;
+        use super::super::types::{DownloadRequest, ResourceKind};
+
+        let dir = root("pool");
+        let (url, counts) = loopback_server(2);
+        let engine = engine_for(&dir);
+        for seq in 0..2 {
+            let request = DownloadRequest::new(
+                ResourceKind::Other,
+                url.clone(),
+                dir.join(format!("meta-{seq}.json")),
+            );
+            let bytes = block_on(engine.download_bytes(request)).expect("回环请求应成功");
+            assert_eq!(bytes, br#"{"ok":true}"#.to_vec());
+        }
+        let (conns, requests) = counts
+            .recv_timeout(std::time::Duration::from_secs(10))
+            .expect("服务端应报告计数");
+        assert_eq!(requests, 2, "两次下载 = 两条请求");
+        assert_eq!(conns, 1, "两次下载应复用同一条连接");
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    /// **守门①②**：设置说 2 ⇒ 引擎**真实的并发闸门**就是 2（探针读 `Semaphore` 而非配置）；gh-proxy
+    /// 三档也真的改变 `plan()` 的候选链；`retry_limit = 0` 落成「只试一次」。
+    ///
+    /// 变异证明（只改实现侧）：① `build` 换回裸 `EngineConfig::default()` ⇒ 探针 8 红；②
+    /// `apply_gh_proxy(region)` 换回 `region` ⇒ `off` 档仍有候选，红；③ 删 `set_tuning` 的
+    /// `remove` ⇒ 换参数后交回旧引擎，红。gh-proxy 的端到端（schema 键 → 调优）等 M197 登记该键。
+    #[test]
+    fn the_setting_and_the_gh_proxy_override_reach_the_engine() {
+        use super::super::types::{DownloadRequest, ResourceKind};
+        use super::super::{config, RegionProfile};
+
+        let dir = root("tune");
+        // 镜像优先的档案：gh-proxy 只在这个模式下才生成候选。
+        store_cached(
+            &dir.join("region.json"),
+            &RegionProfile::mirror_first(now_ms()),
+        )
+        .expect("地区档案");
+        let req = DownloadRequest::new(
+            ResourceKind::Other,
+            "https://github.com/o/r/releases/download/v1/a.jar",
+            dir.join("a.jar"),
+        );
+        let chain = |dir: &Path| -> Vec {
+            engine_for(dir)
+                .plan(&req, 0)
+                .into_iter()
+                .map(|c| c.url)
+                .collect()
+        };
+        let set = |c: Option, a: Option, g: &str| {
+            set_tuning(&dir, DownloadTuning::from_settings(c, a, Some(g)))
+        };
+
+        set(Some(2), Some(1), "off");
+        let engine = engine_for(&dir);
+        assert_eq!(engine.concurrency_probe(), 2, "闸门必须真是 2 张许可");
+        let off = chain(&dir);
+        assert!(!off.iter().any(|u| u.contains("gh-proxy")), "{off:?}");
+
+        set(Some(5), None, "https://gh.example/");
+        let rebuilt = engine_for(&dir);
+        assert!(!Arc::ptr_eq(&engine, &rebuilt), "参数变了必须换引擎");
+        assert_eq!(rebuilt.concurrency_probe(), 5, "新闸门吃新值");
+        let over = chain(&dir);
+        assert!(
+            over.iter().any(|u| u.starts_with("https://gh.example/")),
+            "{over:?}"
+        );
+
+        // P2-1：`retry_limit = 0`（旧配置里真有）不许回落出厂 3。硬上限：塞 9999 也只开 64。
+        set(Some(8), Some(0), "");
+        let zero = engine_for(&dir);
+        assert_eq!(zero.config().max_attempts_per_source, 1);
+        assert_eq!(
+            zero.attempts_for("official", ResourceKind::Other, now_ms()),
+            1
+        );
+        let wild = DownloadTuning {
+            max_concurrency: 9_999,
+            ..Default::default()
+        };
+        set_tuning(&dir, wild);
+        assert_eq!(
+            engine_for(&dir).concurrency_probe(),
+            config::MAX_CONCURRENCY
+        );
+        std::fs::remove_dir_all(&dir).ok();
+    }
+}
diff --git a/crates/core/src/download/shared/tuned.rs b/crates/core/src/download/shared/tuned.rs
new file mode 100644
index 0000000..6acfe1a
--- /dev/null
+++ b/crates/core/src/download/shared/tuned.rs
@@ -0,0 +1,85 @@
+//! 带调优取引擎：把「灌设置」与「取引擎」绑成一次调用（M203）。
+//!
+//! [`super::set_tuning`] 与 [`super::engine_for`] 是两处显式同步点，宿主少调前一步就会**静默**
+//! 拿到出厂参数的引擎——CLI 的 `install` / `java` / `pack` 此前各自 `DownloadEngine::new(
+//! EngineConfig::default(), …)`，用户在设置里配的并发 / 重试 / gh-proxy 一概不生效。
+//! 把它们绑成一次调用，漏调就成了类型错误而不是「跑起来但用出厂值」。
+//!
+//! 现有 [`super::engine_for`] 的签名与行为**不动**（presenter 走 `set_tuning` + `engine_for`
+//! 两步，语义相同，见 `presenter::host::settings::download::apply_tuning`）。
+
+use std::path::Path;
+use std::sync::Arc;
+
+use super::super::config::DownloadTuning;
+use super::super::engine::DownloadEngine;
+use super::{engine_for, set_tuning};
+
+/// 先灌该数据根的调优，再取它的共享引擎（调优没变时复用的是同一个引擎）。
+///
+/// 幂等：值没变时 `set_tuning` 一行不动，所以「每次取引擎前都调」不会白扔连接池。
+#[must_use]
+pub fn engine_with_tuning(
+    cache_root: impl AsRef,
+    tune: DownloadTuning,
+) -> Arc {
+    let root = cache_root.as_ref();
+    let _ = set_tuning(root, tune);
+    engine_for(root)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::download::config::{DEFAULT_MAX_ATTEMPTS_PER_SOURCE, DEFAULT_MAX_CONCURRENCY};
+    use std::path::PathBuf;
+
+    fn root(tag: &str) -> PathBuf {
+        let dir = std::env::temp_dir().join(format!(
+            "ull-shared-tuned-{tag}-{}-{:?}",
+            std::process::id(),
+            std::thread::current().id()
+        ));
+        let _ = std::fs::remove_dir_all(&dir);
+        std::fs::create_dir_all(&dir).expect("建缓存根");
+        dir
+    }
+
+    /// **调优与取引擎必须是一步**：调 `engine_with_tuning` 就该拿到吃这套参数的引擎。
+    ///
+    /// 抓得住的变异：把 `engine_with_tuning` 里的 `set_tuning(...)` 删掉（只留 `engine_for`）⇒
+    /// 探针停在出厂 8，红。抓不住的：设置键 → 调优那一段（在 CLI 侧，`cli/src/download/tests.rs`）。
+    #[test]
+    fn the_tuning_reaches_the_engine_it_returns() {
+        let dir = root("reach");
+        let engine =
+            engine_with_tuning(&dir, DownloadTuning::from_settings(Some(3), Some(2), None));
+        assert_eq!(engine.config().max_concurrency, 3);
+        assert_eq!(engine.concurrency_probe(), 3, "闸门真开了 3 张许可");
+        assert_eq!(engine.config().max_attempts_per_source, 2);
+
+        // 出厂调优与「没灌过」等价：不该因为这次调用就把引擎参数写坏。
+        let plain = engine_with_tuning(&dir, DownloadTuning::default());
+        assert_eq!(plain.config().max_concurrency, DEFAULT_MAX_CONCURRENCY);
+        assert_eq!(
+            plain.config().max_attempts_per_source,
+            DEFAULT_MAX_ATTEMPTS_PER_SOURCE
+        );
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    /// 调优变了就要换引擎（`set_tuning` 的那半个承诺在这里也成立）。
+    ///
+    /// 抓得住的变异：`engine_with_tuning` 只 `engine_for` 不看调优的变更 ⇒ 交回旧引擎（`ptr_eq` 红）。
+    #[test]
+    fn a_changed_tuning_yields_a_rebuilt_engine() {
+        let dir = root("rebuild");
+        let first = engine_with_tuning(&dir, DownloadTuning::from_settings(Some(2), None, None));
+        let same = engine_with_tuning(&dir, DownloadTuning::from_settings(Some(2), None, None));
+        assert!(Arc::ptr_eq(&first, &same), "同值不该重建");
+        let next = engine_with_tuning(&dir, DownloadTuning::from_settings(Some(5), None, None));
+        assert!(!Arc::ptr_eq(&first, &next), "改了并发必须重建");
+        assert_eq!(next.concurrency_probe(), 5);
+        std::fs::remove_dir_all(&dir).ok();
+    }
+}
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,
+}
+
+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 {
+        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 {
+        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,
+    ) -> Result {
+        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 = 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,
+        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//`），海量小文件。
+    Asset,
+    /// 库文件（MB 级）。
+    Library,
+    /// 客户端 jar（MB~几十 MB）。
+    ClientJar,
+    /// 版本清单 / 版本 JSON（强时效，短 TTL）。
+    VersionManifest,
+    /// 资源索引 `assets/indexes/.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) -> Self {
+        Self {
+            algo: HashAlgo::Sha1,
+            hex: hex.into().trim().to_ascii_lowercase(),
+        }
+    }
+
+    /// 构造 SHA-256 校验值。
+    #[must_use]
+    pub fn sha256(hex: impl Into) -> 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,
+    /// 期望大小（进度预算 + 分块规划）。
+    pub expected_size: Option,
+    /// 续传策略。
+    pub resume: ResumePolicy,
+}
+
+impl DownloadRequest {
+    /// 构造请求（默认保守续传、无校验）。
+    #[must_use]
+    pub fn new(kind: ResourceKind, url: impl Into, dest: impl Into) -> 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) -> Self {
+        self.integrity = Some(Integrity::sha1(hex));
+        self
+    }
+
+    /// 设置 SHA-256 校验。
+    #[must_use]
+    pub fn with_sha256(mut self, hex: impl Into) -> 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, url: impl Into) -> 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 {
+    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 {
+    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/adopt.rs b/crates/core/src/game/adopt.rs
new file mode 100644
index 0000000..a91b375
--- /dev/null
+++ b/crates/core/src/game/adopt.rs
@@ -0,0 +1,59 @@
+//! 登记「已经铺在盘上的版本」（从其他启动器的 `.minecraft` 只读接入，M221）。
+//!
+//! 依据：`DevDocs/artifacts/m218/SURVEY-p4.md`（④ 从其他启动器导入数据）与
+//! `DevDocs/00-债务台账.md` §21 的第 ④ 条；模型口径仍按 D20（实例隔离只改**运行目录**，
+//! `versions/` `assets/` `libraries/` 恒共享，见 [`crate::game::isolation::SHARED_LAYERS`]）。
+//!
+//! # 一句话纪律
+//!
+//! **登记只读外部、只写自己**：本模块从不往游戏根写一个字节（不搬文件、不补清单、不改 mtime），
+//! 唯一的写盘是 `profiles.json` + `config/instances/.json`（+ 缺省运行目录的准备，若选了它）。
+//! 因此「导入前后对 `versions/` `libraries/` 做全量哈希必须完全不变」是可以用测试钉死的事实。
+//!
+//! # 为什么要有它（现状的洞）
+//!
+//! [`GameLayout::installed_versions`] 早就会扫 `versions/`，但**没有任何代码把扫到的东西变成实例**。
+//! 于是「别人的 `.minecraft` 已经装好了 1.20.1」这件事在 ULL 里看不见，用户只能重装一遍
+//! （下载全部资源）。这个模块把那批版本变成实例档案，内容一个字节不搬。
+//!
+//! # 缺省隔离档**不能**沿用全局 `isolated`（本模块最要紧的一条）
+//!
+//! 全局 `instances.mode` 缺省是 `isolated`，而 `isolated` 的运行目录正是 `versions//`
+//! （[`crate::game::isolation::derive_game_dir`]）。若登记沿用这条缺省，第一次启动就会在
+//! **别人的版本目录**里长出 `mods/` `saves/` `config/` `logs/` —— 不覆盖任何文件，但与
+//! 「多启动器共存」的意图相反。所以 [`AdoptTarget`] 的缺省值是
+//! [`AdoptTarget::InstanceDir`]（落 ULL 数据区 `/instances/<实例目录名>`），
+//! 想共用/写进对方目录必须**显式**选，并且 [`target_notes`] 会把后果说清楚。
+//!
+//! # 分层
+//!
+//! - `candidate`：候选与逐项**结构化失败**（坏 JSON / 缺父 / 环 / 不可读 / 越界 / 符号链接）；
+//! - `error`：整次调用失败（[`AdoptError`]，带稳定错误码）；
+//! - `inspect`：只读扫描与逐项检查（[`scan`] / [`inspect`]）；
+//! - `paths`：路径判据（版本 id 能不能当路径、符号链接有没有跑出游戏根）；
+//! - `fspaths`：路径语义（真实化 / Win32 尾点尾空格归一）与写盘面判据（配置在 `.ULL` 内、
+//!   默认写盘面不得与受保护游戏树重叠）；
+//! - `run_dir`：运行目录派生（含**碰撞消歧**）与「缺省目录必须落在数据区」；
+//! - `plan`：把候选 + 用户选择算成一次登记的落点（[`plan`]），真正落盘是 [`adopt`]。
+//!
+//! # 不做什么
+//!
+//! - **不读账户凭据**：`launcher_profiles.json` / `launcher_accounts.json` / HMCL 的
+//!   `accounts.json` 一个都不碰（`AGENTS.md` §6 同族纪律）；
+//! - **不做多根**（D20 未改）：扫的永远是**当前**游戏根（`core.game_home`），
+//!   「同时管多个 `.minecraft`」是另一个更贵的模型改动，见 SURVEY-p4 §4.2；
+//! - **不下载、不校验完整性**：版本 JSON 里 `libraries[].downloads.artifact.url` 指向 maven
+//!   中心是正常形态，登记不因此拒绝，但也不假装校验过（人读输出里如实写成「未校验」）。
+
+pub mod candidate;
+mod error;
+mod fspaths;
+mod inspect;
+mod paths;
+mod plan;
+mod run_dir;
+
+pub use candidate::{AdoptCandidate, AdoptProblem, AdoptTarget, RegisteredInstance};
+pub use error::AdoptError;
+pub use inspect::{inspect, scan, AdoptScan};
+pub use plan::{adopt, plan, target_notes, AdoptOutcome, AdoptPlan, AdoptRequest};
diff --git a/crates/core/src/game/adopt/candidate.rs b/crates/core/src/game/adopt/candidate.rs
new file mode 100644
index 0000000..0cf5a8a
--- /dev/null
+++ b/crates/core/src/game/adopt/candidate.rs
@@ -0,0 +1,276 @@
+//! 登记的**数据形状**：候选、结构化失败、运行目录选择。
+//!
+//! 三种形状刻意分开：
+//! - [`AdoptCandidate`]：盘上的一个 `versions//` 是不是能登记的版本（含逐项问题）；
+//! - [`AdoptProblem`]：一条**结构化**的不合格原因（有稳定 `code`，人读 `message`）；
+//! - [`AdoptTarget`]：登记后运行目录从哪来（隔离档由它决定）；
+//! - 整次调用的失败形状在 [`super::error::AdoptError`]。
+//!
+//! 为什么不把问题塞进 [`crate::game::GameError`]：`core::game` 的错误是「解析/路径/IO」这一层，
+//! 而这里是「这个版本对我们而言能不能登记」的业务判据（缺父、越界、同名冲突…）。
+//! 混进 `GameError` 会让所有现存 `match` 多出一批只在本模块有意义的变体。
+
+use std::fmt;
+use std::path::PathBuf;
+
+use super::super::install::instance::Isolation;
+
+/// 候选版本的**结构化**不合格原因（每一条都带稳定机读 `code`）。
+///
+/// 判据来源：`DevDocs/artifacts/m218/SURVEY-p4.md` §3 的 copy/引用/拒绝表。任一 `Err` 都意味着
+/// 「登记了也启动不了」或「越界/踩别人的目录」，因此登记前一律拒绝，并把原因原样说给用户。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum AdoptProblem {
+    /// `versions//` 存在但没有同名清单（只剩 natives / 上个启动器的残留）。
+    ManifestMissing {
+        /// 版本 id（目录名）。
+        version_id: String,
+        /// 期望的清单路径 `versions//.json`。
+        path: PathBuf,
+    },
+    /// 版本 id 本身不能当路径用（空 / 含分隔符 / 盘符 / NUL / 结尾点号空格）。
+    VersionIdInvalid {
+        /// 原始 id。
+        version_id: String,
+        /// 人读原因。
+        reason: &'static str,
+    },
+    /// 清单文件读不出来（权限 / 被占用 / 不是 UTF-8）。
+    ManifestUnreadable {
+        /// 清单路径。
+        path: PathBuf,
+        /// 底层错误文本（含 Win32 错误码或 serde 行列号）。
+        message: String,
+    },
+    /// 清单不是合法 JSON（**带行号列号**，别只说「坏了」）。
+    ManifestInvalidJson {
+        /// 清单路径。
+        path: PathBuf,
+        /// serde_json 的错误文本（含 `line L column C`）。
+        message: String,
+    },
+    /// 清单里没有 `id`。
+    ManifestMissingId {
+        /// 清单路径。
+        path: PathBuf,
+    },
+    /// 清单里的 `id` 与目录名不一致（启动时按清单 id 找 jar，必然找不到）。
+    ManifestIdMismatch {
+        /// 清单路径。
+        path: PathBuf,
+        /// 清单里的 id。
+        manifest_id: String,
+        /// 目录名。
+        directory_id: String,
+    },
+    /// 目录遍历/元数据读不出来（权限、坏链接）。
+    DirectoryUnreadable {
+        /// 出问题的路径。
+        path: PathBuf,
+        /// 底层错误文本。
+        message: String,
+    },
+    /// 已有条目解析到游戏根之外（符号链接 / 目录联接 / 祖先链接；不跟随）。
+    OutsideGameRoot {
+        /// 链接本身。
+        path: PathBuf,
+        /// 解析出来的真实目标。
+        target: PathBuf,
+        /// 比较基准（真实化后的游戏根）。
+        root: PathBuf,
+    },
+    /// 是符号链接但解析不出来（断链 / 权限）。
+    SymlinkUnresolvable {
+        /// 链接本身。
+        path: PathBuf,
+        /// 底层错误文本。
+        message: String,
+    },
+    /// `inheritsFrom` 指向的父版本在盘上找不到。
+    MissingParent {
+        /// 缺失的父版本 id。
+        parent: String,
+        /// 谁在要它。
+        required_by: String,
+    },
+    /// `inheritsFrom` 成环。
+    CircularInheritance {
+        /// 从根到环的 id 链（首尾同一个 id）。
+        chain: Vec,
+    },
+    /// 继承链在 `core::game::resolve` 那里失败（走查通过、权威解析不通过的兜底）。
+    InheritanceInvalid {
+        /// `GameError` 的人读文本。
+        detail: String,
+    },
+}
+
+impl AdoptProblem {
+    /// 稳定机读码（`--json` 的 `problems[].code`）。
+    #[must_use]
+    pub const fn code(&self) -> &'static str {
+        match self {
+            Self::ManifestMissing { .. } => "manifest_missing",
+            Self::VersionIdInvalid { .. } => "version_id_invalid",
+            Self::ManifestUnreadable { .. } => "manifest_unreadable",
+            Self::ManifestInvalidJson { .. } => "manifest_invalid_json",
+            Self::ManifestMissingId { .. } => "manifest_missing_id",
+            Self::ManifestIdMismatch { .. } => "manifest_id_mismatch",
+            Self::DirectoryUnreadable { .. } => "directory_unreadable",
+            Self::OutsideGameRoot { .. } => "outside_game_root",
+            Self::SymlinkUnresolvable { .. } => "symlink_unresolvable",
+            Self::MissingParent { .. } => "missing_parent",
+            Self::CircularInheritance { .. } => "circular_inheritance",
+            Self::InheritanceInvalid { .. } => "inheritance_invalid",
+        }
+    }
+}
+
+impl fmt::Display for AdoptProblem {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::ManifestMissing { version_id, path } => write!(
+                f,
+                "版本 {version_id} 没有清单文件（期望 {}）",
+                path.display()
+            ),
+            Self::VersionIdInvalid { version_id, reason } => {
+                write!(f, "版本 id 不能当路径用（{reason}）：{version_id:?}")
+            }
+            Self::ManifestUnreadable { path, message } => {
+                write!(f, "清单读不出来 {}：{message}", path.display())
+            }
+            Self::ManifestInvalidJson { path, message } => {
+                write!(f, "清单不是合法 JSON {}：{message}", path.display())
+            }
+            Self::ManifestMissingId { path } => {
+                write!(f, "清单缺少 id 字段：{}", path.display())
+            }
+            Self::ManifestIdMismatch {
+                path,
+                manifest_id,
+                directory_id,
+            } => write!(
+                f,
+                "清单 id（{manifest_id}）与目录名（{directory_id}）不一致：{}——启动时会按清单 id 找 jar，必然找不到",
+                path.display()
+            ),
+            Self::DirectoryUnreadable { path, message } => {
+                write!(f, "目录读不出来 {}：{message}", path.display())
+            }
+            Self::OutsideGameRoot { path, target, root } => write!(
+                f,
+                "条目解析到游戏根之外，不跟随：{} -> {}（游戏根 {}）",
+                path.display(),
+                target.display(),
+                root.display()
+            ),
+            Self::SymlinkUnresolvable { path, message } => {
+                write!(f, "符号链接解析失败 {}：{message}", path.display())
+            }
+            Self::MissingParent { parent, required_by } => {
+                write!(f, "版本 {required_by} 继承的父版本 {parent} 不在盘上")
+            }
+            Self::CircularInheritance { chain } => {
+                write!(f, "版本继承成环：{}", chain.join(" -> "))
+            }
+            Self::InheritanceInvalid { detail } => write!(f, "继承链解析失败：{detail}"),
+        }
+    }
+}
+
+/// 已经绑定某个版本 id 的实例档案（只带展示需要的最小信息，不泄露内部结构）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RegisteredInstance {
+    /// 实例 id。
+    pub id: String,
+    /// 实例展示名。
+    pub name: String,
+}
+
+/// 盘上的一个候选版本（扫出来的一个 `versions//`）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AdoptCandidate {
+    /// 版本 id（= 目录名，登记后写进 `profiles.json` 的 `version_id`）。
+    pub version_id: String,
+    /// 版本目录 `versions//`。
+    pub version_dir: PathBuf,
+    /// 清单路径 `versions//.json`。
+    pub manifest_path: PathBuf,
+    /// 客户端 jar `versions//.jar` 是否存在（只报事实，不校验内容）。
+    pub jar_present: bool,
+    /// 清单里声明的 id（读不出来时为 `None`）。
+    pub manifest_id: Option,
+    /// `inheritsFrom` 链（自身在前、最祖先在后；读不出来时是已走通的那一段）。
+    pub inherits: Vec,
+    /// 已有实例绑定这个版本（空 = 还没登记过）。
+    pub registered: Vec,
+    /// 问题清单（空 = 可登记）。
+    pub problems: Vec,
+}
+
+impl AdoptCandidate {
+    /// 是否可登记（没有任何问题）。
+    #[must_use]
+    pub fn adoptable(&self) -> bool {
+        self.problems.is_empty()
+    }
+
+    /// 已登记过（至少有一个实例绑定这个版本 id）。
+    #[must_use]
+    pub fn is_registered(&self) -> bool {
+        !self.registered.is_empty()
+    }
+}
+
+/// 登记后实例的**运行目录**从哪来（隔离档由它决定，见 [`AdoptTarget::isolation`]）。
+///
+/// 缺省是 [`Self::InstanceDir`]——**不是** `isolated`：理由见模块文档。
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub enum AdoptTarget {
+    /// 缺省：ULL 数据区里新建独立运行目录 `/instances/<实例目录名>`（写 `custom` 档）。
+    #[default]
+    InstanceDir,
+    /// 共用当前游戏根（别人的 `.minecraft`）——必须显式选，且必须告知后果。
+    Shared,
+    /// 版本目录 `versions//`（`isolated` 档）——会在别人的版本目录里长玩家数据。
+    VersionDir,
+    /// 用户指定的目录（`custom` 档，必须绝对路径）。
+    Custom(PathBuf),
+}
+
+impl AdoptTarget {
+    /// 稳定机读 id（`--json` 的 `run_dir_source`）。
+    #[must_use]
+    pub const fn as_str(&self) -> &'static str {
+        match self {
+            Self::InstanceDir => "instance_dir",
+            Self::Shared => "shared",
+            Self::VersionDir => "version_dir",
+            Self::Custom(_) => "custom",
+        }
+    }
+
+    /// 生效隔离档。
+    #[must_use]
+    pub const fn isolation(&self) -> Isolation {
+        match self {
+            Self::InstanceDir | Self::Custom(_) => Isolation::Custom,
+            Self::Shared => Isolation::Shared,
+            Self::VersionDir => Isolation::Isolated,
+        }
+    }
+
+    /// 命令行/配置里的词表（`shared` / `isolated` / `custom`，与 [`Isolation`] 同一套字面量）。
+    ///
+    /// `instance_dir` 有意**不接受**输入：它是缺省值，不是一个用户可以手写选中的档位。
+    #[must_use]
+    pub fn parse(raw: &str, game_dir: Option) -> Option {
+        match raw.trim() {
+            "shared" => Some(Self::Shared),
+            "isolated" | "per_version" => Some(Self::VersionDir),
+            "custom" => game_dir.map(Self::Custom),
+            _ => None,
+        }
+    }
+}
diff --git a/crates/core/src/game/adopt/error.rs b/crates/core/src/game/adopt/error.rs
new file mode 100644
index 0000000..79c3102
--- /dev/null
+++ b/crates/core/src/game/adopt/error.rs
@@ -0,0 +1,194 @@
+//! 一次登记的失败形状（CLI 据此给稳定错误码 + 结构化 details）。
+//!
+//! 与 [`AdoptProblem`] 的分工：`AdoptProblem` 是「这个版本为什么不能登记」（可以多条、逐条列出），
+//! [`AdoptError`] 是「这次调用为什么没成功」（一条，喂给 `--json` 的 `error.code`）。
+//! 候选不合格是后者的一个变体，但问题清单原样带出来——不许把原因折叠成一句「导入失败」。
+
+use std::fmt;
+use std::path::PathBuf;
+
+use super::candidate::AdoptProblem;
+use crate::game::error::GameError;
+
+/// 一次登记失败（CLI 据此给稳定错误码 + 结构化 details）。
+#[derive(Debug)]
+pub enum AdoptError {
+    /// `core::game` 的解析/路径/IO 失败。
+    Game(GameError),
+    /// 版本 id 在盘上不存在（没有 `versions//`）。
+    UnknownVersion {
+        /// 请求的版本 id。
+        version_id: String,
+        /// 期望的目录。
+        version_dir: PathBuf,
+    },
+    /// 候选不合格（`problems` 就是全部原因，一条都不吞）。
+    NotAdoptable {
+        /// 版本 id。
+        version_id: String,
+        /// 全部原因。
+        problems: Vec,
+    },
+    /// 展示名已被别的实例占用（**显式报错**，不静默复用一条别的版本）。
+    DuplicateName {
+        /// 冲突的展示名。
+        name: String,
+        /// 占用它的实例 id。
+        instance_id: String,
+    },
+    /// 这个版本已经以同名实例登记过了（重复执行 = 无副作用失败）。
+    AlreadyRegistered {
+        /// 版本 id。
+        version_id: String,
+        /// 已存在的实例名。
+        name: String,
+        /// 已存在的实例 id。
+        instance_id: String,
+    },
+    /// 缺省运行目录已存在且非空（不猜「合并进已有实例」，也不覆盖）。
+    TargetNotEmpty {
+        /// 那个目录。
+        path: PathBuf,
+    },
+    /// 运行目录选择本身不成立（`custom` 缺目录 / 相对路径）。
+    TargetInvalid {
+        /// 人读原因。
+        detail: String,
+    },
+    /// 缺省运行目录的后缀全被占用（`-2` … `-33` 都撞上了）——不无限顺延，直接报错。
+    NoFreeRunDir {
+        /// 派生用的基准目录。
+        base: PathBuf,
+    },
+    /// 配置写面（`config/`、`config/instances/`、`profiles.json`）的真实落点不可信：
+    /// 跑出 `<.ULL>` 或落进游戏根（符号链接 / 目录联接）。
+    ConfigSurfaceUnsafe {
+        /// 出问题的目标路径（`config/`、`config/instances/` 或 `profiles.json`）。
+        path: PathBuf,
+        /// 人读原因（含解析后的真实位置）。
+        detail: String,
+    },
+    /// 默认写盘面（`.ULL`/`data`/配置/缺省运行目录）解析后落在**受保护游戏树**之内（r2 R2.2）。
+    ///
+    /// 与 [`Self::ConfigSurfaceUnsafe`] 的分工：那条管「配置跑出 `.ULL`」，这条管「写盘面与游戏树重叠」。
+    WriteSurfaceInGameTree {
+        /// 出问题的写盘面（`.ULL`、`data/`、配置目录、缺省运行目录…）。
+        path: PathBuf,
+        /// 人读原因（含解析后的真实位置与「请换不重叠的数据目录」的指引）。
+        detail: String,
+    },
+    /// `versions` 入口存在但读不出来（断链的符号链接/目录联接、目标被移走、祖先断链）。
+    ///
+    /// 与「`versions` 真不存在」严格区分：后者才是空结果，前者必须具名报错。
+    VersionsDirUnreadable {
+        /// 出问题的路径（`versions/` 或游戏根）。
+        path: PathBuf,
+        /// 人读原因。
+        detail: String,
+    },
+}
+
+impl AdoptError {
+    /// 稳定机读码（`--json` 的 `error.code`）。
+    #[must_use]
+    pub const fn code(&self) -> &'static str {
+        match self {
+            Self::Game(_) => "adopt_io",
+            Self::UnknownVersion { .. } => "adopt_version_not_found",
+            Self::NotAdoptable { .. } => "adopt_not_adoptable",
+            Self::DuplicateName { .. } => "adopt_duplicate_name",
+            Self::AlreadyRegistered { .. } => "adopt_already_registered",
+            Self::TargetNotEmpty { .. } => "adopt_target_not_empty",
+            Self::TargetInvalid { .. } => "adopt_target_invalid",
+            Self::NoFreeRunDir { .. } => "adopt_no_free_run_dir",
+            Self::ConfigSurfaceUnsafe { .. } => "adopt_config_surface_unsafe",
+            Self::WriteSurfaceInGameTree { .. } => "adopt_write_surface_in_game_tree",
+            Self::VersionsDirUnreadable { .. } => "adopt_versions_unreadable",
+        }
+    }
+
+    /// 候选不合格时的问题清单（其它错误为空）。
+    #[must_use]
+    pub fn problems(&self) -> &[AdoptProblem] {
+        match self {
+            Self::NotAdoptable { problems, .. } => problems,
+            _ => &[],
+        }
+    }
+}
+
+impl fmt::Display for AdoptError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Game(error) => write!(f, "{error}"),
+            Self::UnknownVersion {
+                version_id,
+                version_dir,
+            } => write!(
+                f,
+                "版本 {version_id} 不在盘上（没有 {}）",
+                version_dir.display()
+            ),
+            Self::NotAdoptable {
+                version_id,
+                problems,
+            } => {
+                write!(f, "版本 {version_id} 不能登记：")?;
+                for (index, problem) in problems.iter().enumerate() {
+                    if index > 0 {
+                        f.write_str("；")?;
+                    }
+                    write!(f, "{problem}")?;
+                }
+                Ok(())
+            }
+            Self::DuplicateName { name, instance_id } => write!(
+                f,
+                "已有同名实例 `{name}`（id {instance_id}）：导入时请用 --name 换一个展示名"
+            ),
+            Self::AlreadyRegistered {
+                version_id,
+                name,
+                instance_id,
+            } => write!(
+                f,
+                "版本 {version_id} 已经登记过（实例 `{name}`，id {instance_id}）：没有改动任何文件"
+            ),
+            Self::TargetNotEmpty { path } => {
+                write!(f, "运行目录已存在且非空，不覆盖：{}", path.display())
+            }
+            Self::TargetInvalid { detail } => write!(f, "运行目录选择不成立：{detail}"),
+            Self::NoFreeRunDir { base } => write!(
+                f,
+                "为这个实例派生独立运行目录失败：{} 及其 -2…-33 后缀都被别的实例占着",
+                base.display()
+            ),
+            Self::ConfigSurfaceUnsafe { path, detail } => {
+                write!(f, "配置写面不可信：{} {detail}", path.display())
+            }
+            Self::WriteSurfaceInGameTree { path, detail } => {
+                write!(f, "写盘面与游戏树重叠：{} {detail}", path.display())
+            }
+            Self::VersionsDirUnreadable { path, detail } => write!(
+                f,
+                "versions 入口存在但读不出来 {}：{detail}",
+                path.display()
+            ),
+        }
+    }
+}
+
+impl std::error::Error for AdoptError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            Self::Game(error) => Some(error),
+            _ => None,
+        }
+    }
+}
+
+impl From for AdoptError {
+    fn from(error: GameError) -> Self {
+        Self::Game(error)
+    }
+}
diff --git a/crates/core/src/game/adopt/fspaths.rs b/crates/core/src/game/adopt/fspaths.rs
new file mode 100644
index 0000000..7cc6651
--- /dev/null
+++ b/crates/core/src/game/adopt/fspaths.rs
@@ -0,0 +1,195 @@
+//! 路径语义与**写盘面**判据：真实化、Win32 别名归一、配置写面、与受保护游戏树的重叠。
+//!
+//! # 为什么单独一层
+//!
+//! 「这个路径到底是哪个物理位置」在 Windows 上不是字符串比较：普通路径的**尾点/尾空格会被 Win32
+//! 折叠**（`Foo.` 与 `Foo ` 都落到 `Foo`），而 verbatim 路径（`\\?\…`）**不**折叠。`canonicalize`
+//! 只能回答「已存在的东西在哪」，尚不存在的尾段（`custom` 档认领的目录、派生出来还没建的缺省目录）
+//! 必须自己按平台语义归一，否则「两个实例共用同一个物理目录」会从这个缝里漏过去（复审 r2 的 R2.1）。
+//!
+//! 另一件事是**写盘面**：登记承诺「只写 ULL 自己的配置、外部游戏树零写入」。判据分两条：
+//! 1. 配置落点必须在 `<.ULL>` 内（[`ensure_config_write_surface`]）；
+//! 2. 全部默认写盘面（`.ULL` 自身、`config/`、`config/instances/`、`profiles.json`、`data/`
+//!    以及缺省运行目录）**不得与受保护游戏树重叠**（[`ensure_surfaces_clear_of_game_tree`]）。
+//!    用户把整个 `.ULL`/`data` 迁到游戏树外是合法迁移，照样通过；重叠则具名拒绝——
+//!    不能写完之后再补一句 warning（复审 r2 的 R2.2）。
+//!
+//! # 已知边界
+//!
+//! 判据都是「检查那一刻」的快照（TOCTOU 看不到）；Win32 的 8.3 短名别名不在归一范围内
+//! （未就绪的短名无法可靠推导），非 junction 的重解析点也未逐个识别。
+
+use std::ffi::OsString;
+use std::path::{Path, PathBuf};
+
+use super::super::layout::GameLayout;
+use super::error::AdoptError;
+use crate::platform::layout::LauncherLayout;
+
+/// **最近**的已存在祖先/自身解析出的真实路径 + 尚不存在的尾段（`None` = 整条链都不存在）。
+///
+/// 用于**位置判据**（越界比较、写面重叠）：这里不做别名折叠——问的是「物理上在哪」。
+pub(super) fn existing_real(path: &Path) -> Option {
+    resolve(path, false)
+}
+
+/// **比较键**用的路径：已存在部分真实化，尚不存在的尾段按平台语义归一（Windows 折叠尾点/尾空格，
+/// verbatim 路径除外）。两个不同写法指向同一个物理目录时，键必须相等。
+pub(super) fn comparison_real(path: &Path) -> Option {
+    resolve(path, true)
+}
+
+fn resolve(path: &Path, fold_tail: bool) -> Option {
+    let verbatim = is_verbatim(path);
+    let mut probe = path.to_path_buf();
+    let mut tail: Vec = Vec::new();
+    loop {
+        if std::fs::symlink_metadata(&probe).is_ok() {
+            let real = probe.canonicalize().ok()?;
+            let mut full = real;
+            for part in tail.iter().rev() {
+                if fold_tail {
+                    full.push(platform_component(part, verbatim));
+                } else {
+                    full.push(part);
+                }
+            }
+            return Some(full);
+        }
+        let name = probe.file_name().map(OsString::from)?;
+        tail.push(name);
+        if !probe.pop() {
+            return None;
+        }
+    }
+}
+
+/// 整条路径是不是 verbatim 形式（`\\?\…` / `\\.\…`）：那种写法**不**折叠尾点/尾空格。
+fn is_verbatim(path: &Path) -> bool {
+    #[cfg(windows)]
+    {
+        let text = path.to_string_lossy();
+        text.starts_with(r"\\?\") || text.starts_with(r"\\.\")
+    }
+    #[cfg(not(windows))]
+    {
+        let _ = path;
+        false
+    }
+}
+
+/// 尚不存在的一段名字按**平台语义**归一。
+///
+/// Windows（非 verbatim）：去掉尾部的 `.` 与空格——Win32 建目录/解析路径时就这么做，所以
+/// `Foo.`、`Foo `、`Foo` 是同一个物理目录。全是点/空格的名字保持原样（那种名字本身建不出来，
+/// 折叠成空串只会制造新的歧义）。其它平台原样返回（`Foo.` 与 `Foo` 是不同目录）。
+fn platform_component(name: &std::ffi::OsStr, verbatim: bool) -> OsString {
+    #[cfg(windows)]
+    {
+        if !verbatim {
+            let text = name.to_string_lossy();
+            let trimmed = text.trim_end_matches(['.', ' ']);
+            if !trimmed.is_empty() && trimmed.len() != text.len() {
+                return OsString::from(trimmed.to_string());
+            }
+        }
+    }
+    let _ = verbatim;
+    name.to_os_string()
+}
+
+/// 路径 → 比较键（`/` 分隔 + 大小写归一；大小写只在大小写不敏感的平台折叠）。
+pub(super) fn normalize_key(path: &Path) -> String {
+    let text = path.to_string_lossy().replace('\\', "/");
+    if cfg!(any(windows, target_os = "macos")) {
+        text.to_lowercase()
+    } else {
+        text
+    }
+}
+
+/// 配置写面（`config/`、`config/instances/`、`profiles.json`）必须在 `<.ULL>` 之内。
+///
+/// 只管「在不在自己家里」；「有没有落进受保护游戏树」由
+/// [`ensure_surfaces_clear_of_game_tree`] 统一负责（两条判据各有单一职责，不再互相豁免）。
+///
+/// # Errors
+///
+/// 落点跑出 `<.ULL>`：`ConfigSurfaceUnsafe`。
+pub(super) fn ensure_config_write_surface(launcher: &LauncherLayout) -> Result<(), AdoptError> {
+    let Some(home_real) = existing_real(launcher.home()) else {
+        // `<.ULL>` 都还不存在 ⇒ 还不可能有链接可言。
+        return Ok(());
+    };
+    let targets = [
+        launcher.config(),
+        launcher.config().join("instances"),
+        launcher.profiles_config(),
+    ];
+    for target in targets {
+        let Some(real) = existing_real(&target) else {
+            continue;
+        };
+        if !real.starts_with(&home_real) {
+            return Err(AdoptError::ConfigSurfaceUnsafe {
+                path: target,
+                detail: format!(
+                    "解析到 {}，落在启动器目录 {} 之外（有指向外部的符号链接/目录联接）",
+                    real.display(),
+                    home_real.display()
+                ),
+            });
+        }
+    }
+    Ok(())
+}
+
+/// 默认写盘面**不得**与受保护游戏树重叠（`.ULL`/`data`/配置/缺省运行目录解析后都不许落进游戏根）。
+///
+/// 为什么要它：用户可能预先在数据根里放过目录联接（不是 adopt 建的）。这时「默认独立目录」写着写着
+/// 就写进了别人的 `.minecraft`，输出却还说「与别人的 .minecraft 隔离」——那是**假承诺**。
+/// 判据在**写入之前**给出具名拒绝，并让用户把数据目录挪到游戏树之外；整体迁移到游戏树**之外**照旧允许。
+///
+/// `run_dir` 只在缺省档（`InstanceDir`）传：`shared` / `version_dir` / `custom` 是用户显式选择的
+/// 运行目录，允许与游戏树重叠（那是选择的语义，不是偷偷写的）。
+///
+/// # Errors
+///
+/// 任一面解析后落进游戏根：`WriteSurfaceInGameTree`。
+pub(super) fn ensure_surfaces_clear_of_game_tree(
+    game: &GameLayout,
+    launcher: &LauncherLayout,
+    run_dir: Option<&Path>,
+) -> Result<(), AdoptError> {
+    let Some(game_real) = existing_real(game.root()) else {
+        // 游戏根还不存在 ⇒ 没有「受保护游戏树」可重叠。
+        return Ok(());
+    };
+    let mut surfaces = vec![
+        launcher.home().to_path_buf(),
+        launcher.config(),
+        launcher.config().join("instances"),
+        launcher.profiles_config(),
+        launcher.data(),
+    ];
+    if let Some(run_dir) = run_dir {
+        surfaces.push(run_dir.to_path_buf());
+    }
+    for surface in surfaces {
+        let Some(real) = existing_real(&surface) else {
+            continue;
+        };
+        if real.starts_with(&game_real) {
+            return Err(AdoptError::WriteSurfaceInGameTree {
+                path: surface,
+                detail: format!(
+                    "解析到 {}，落在受保护游戏树 {} 之内：默认登记不会把实例数据写进别人的 .minecraft；\
+                     请把 .ULL（或 --data-dir）指到游戏树之外的目录再登记（整体迁移本身是合法的）",
+                    real.display(),
+                    game_real.display()
+                ),
+            });
+        }
+    }
+    Ok(())
+}
diff --git a/crates/core/src/game/adopt/inspect.rs b/crates/core/src/game/adopt/inspect.rs
new file mode 100644
index 0000000..4b470d8
--- /dev/null
+++ b/crates/core/src/game/adopt/inspect.rs
@@ -0,0 +1,400 @@
+//! 只读扫描与逐项检查：`versions/` 下哪些版本能登记、不能登记的原因是什么。
+//!
+//! # 三条不许偷懒的判据
+//!
+//! 1. **坏东西不能当空列表**：`versions/` 读不了是错误（[`AdoptError::Game`]），一个版本的清单坏了是
+//!    一条 [`AdoptProblem`]；两条都不会变成「这里什么都没有」。
+//! 2. **继承链要走到头**：缺父、成环、父清单坏了、父的清单 id 与目录名不一致，逐条报清楚是哪个文件。
+//! 3. **不跟随越界符号链接**：`versions/` 或清单是符号链接时，解析出的真实路径必须仍在游戏根内
+//!    （与导出侧「符号链接不跟随」同一政策）。
+//!
+//! 全程**只读**：不建目录、不写文件、不改 mtime。
+
+use std::path::{Path, PathBuf};
+
+use super::super::error::GameError;
+use super::super::inherit;
+use super::super::install::instance::read_profiles;
+use super::super::layout::GameLayout;
+use super::super::manifest::VersionJson;
+use super::super::profiles::ProfileList;
+use super::candidate::{AdoptCandidate, AdoptProblem, RegisteredInstance};
+use super::error::AdoptError;
+use super::paths::{ensure_inside, root_of, validate_version_id};
+use crate::platform::layout::LauncherLayout;
+
+/// 一次扫描的结果（`versions/` 里的全部条目，逐项带问题）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AdoptScan {
+    /// 被扫的目录（`<游戏根>/versions`）。
+    pub versions_dir: PathBuf,
+    /// 候选版本（按版本 id 字典序）。
+    pub candidates: Vec,
+}
+
+/// 扫当前游戏根的 `versions/`，逐个检查。
+///
+/// `versions/` **真的不存在** ⇒ 空结果（新装的数据根，没有可登记的东西，不是错误）；
+/// `versions/` 入口**存在但读不出来**（断链的符号链接/目录联接、目标被移走、祖先断链）⇒
+/// [`AdoptError::VersionsDirUnreadable`]，绝不降级成空列表；其它读目录失败 ⇒ [`AdoptError::Game`]。
+///
+/// # Errors
+///
+/// 读目录 / 读 `profiles.json` 失败；条目元数据读不出来（权限）时也直接失败——那属于
+/// 「环境坏了」而不是「这个版本不能登记」。
+pub fn scan(game: &GameLayout, launcher: &LauncherLayout) -> Result {
+    let profiles = read_profiles(launcher)?;
+    let versions_dir = game.versions_dir();
+    let root = root_of(game);
+    let entries = match std::fs::read_dir(&versions_dir) {
+        Ok(entries) => entries,
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+            // **入口还在但读不出来**不是「新数据根」：Windows 上断链的目录联接也只会给 NotFound，
+            // 必须自己用不跟随链接的元数据分辨（复审 r1 的实测：lstat 成功而命令报「空」）。
+            //
+            // r2 R2.3：断链可能发生在**更高的祖先**上（例如 `--data-dir` 指向迁移联接下面的 nested
+            // 目录，联接目标被搬走后 `versions` 与游戏根本身都 NotFound）。所以沿祖先找**最近的
+            // 已存在入口**：它 lstat 得到但 `canonicalize` 不出来 ⇒ 具名报错；一路到盘根都不存在
+            // ⇒ 才是「真正的新数据根」，空结果是诚实的。
+            if let Some(entry) = nearest_existing_entry(&versions_dir) {
+                if entry.canonicalize().is_err() {
+                    return Err(AdoptError::VersionsDirUnreadable {
+                        path: entry,
+                        detail: "最近的已存在入口解析失败（断链的符号链接/目录联接，或目标被移走）"
+                            .to_owned(),
+                    });
+                }
+            }
+
+            return Ok(AdoptScan {
+                versions_dir,
+                candidates: Vec::new(),
+            });
+        }
+        Err(error) => return Err(GameError::io(&versions_dir, error).into()),
+    };
+    let mut candidates: Vec = Vec::new();
+    for entry in entries {
+        let entry = entry.map_err(|error| GameError::io(&versions_dir, error))?;
+        let path = entry.path();
+        let Some(version_id) = path.file_name().and_then(|name| name.to_str()) else {
+            // 非 UTF-8 目录名不能当版本 id（进不了 profiles.json），如实记一条问题而不是丢掉。
+            candidates.push(unreadable_id_candidate(&path, &versions_dir));
+            continue;
+        };
+        match std::fs::metadata(&path) {
+            Ok(meta) if meta.is_dir() => {}
+            Ok(_) => continue, // `versions/` 里的普通文件不是版本目录
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+                // 断链符号链接：元数据跟不过去，但链接本身在。
+                if std::fs::symlink_metadata(&path).is_ok() {
+                    candidates.push(broken_link_candidate(version_id, &path));
+                }
+                continue;
+            }
+            Err(error) => return Err(GameError::io(&path, error).into()),
+        }
+        candidates.push(check(game, &root, version_id, &profiles));
+    }
+    candidates.sort_by(|a, b| a.version_id.cmp(&b.version_id));
+    Ok(AdoptScan {
+        versions_dir,
+        candidates,
+    })
+}
+
+/// 检查单个版本。
+///
+/// 与 [`scan`] 用同一套判据，但**先**校验 id 能不能当路径用（非法 id 连存在性都不该去探，
+/// 否则 `versions/../../外面的/1.20.1` 这种形状会先撞上「目录真的存在」再报出别的结论）。
+/// 候选不合格一律 [`AdoptError::NotAdoptable`] 且把问题清单原样带出，只有环境级失败才 `Err`。
+///
+/// # Errors
+///
+/// - [`AdoptError::NotAdoptable`]：id 非法，或候选有问题（坏清单 / 缺父 / 环 / 越界…）；
+/// - [`AdoptError::UnknownVersion`]：id 合法但 `versions//` 不存在；
+/// - [`AdoptError::Game`]：读 `profiles.json` 失败。
+pub fn inspect(
+    game: &GameLayout,
+    launcher: &LauncherLayout,
+    version_id: &str,
+) -> Result {
+    if let Err(problem) = validate_version_id(version_id) {
+        return Err(AdoptError::NotAdoptable {
+            version_id: version_id.to_owned(),
+            problems: vec![problem],
+        });
+    }
+    if !game.version_dir(version_id).is_dir() {
+        let version_dir = game.version_dir(version_id);
+        // 条目存在但不是可读目录（断链链接/联接、或同名的是个文件）⇒ 具名报错，别混成「没装」。
+        if std::fs::symlink_metadata(&version_dir).is_ok() {
+            return Err(AdoptError::NotAdoptable {
+                version_id: version_id.to_owned(),
+                problems: vec![AdoptProblem::DirectoryUnreadable {
+                    path: version_dir,
+                    message: "条目存在但不是可读目录（断链 / 联接目标被移走 / 同名的是文件）"
+                        .to_owned(),
+                }],
+            });
+        }
+        return Err(AdoptError::UnknownVersion {
+            version_id: version_id.to_owned(),
+            version_dir,
+        });
+    }
+    let profiles = read_profiles(launcher)?;
+    let candidate = check(game, &root_of(game), version_id, &profiles);
+    if candidate.adoptable() {
+        Ok(candidate)
+    } else {
+        Err(AdoptError::NotAdoptable {
+            version_id: candidate.version_id.clone(),
+            problems: candidate.problems.clone(),
+        })
+    }
+}
+
+/// 逐项检查一个版本目录。
+fn check(
+    game: &GameLayout,
+    root: &Path,
+    version_id: &str,
+    profiles: &ProfileList,
+) -> AdoptCandidate {
+    let version_dir = game.version_dir(version_id);
+    let manifest_path = game.version_json(version_id);
+    let registered = registered_for(profiles, version_id);
+    let mut candidate = AdoptCandidate {
+        version_id: version_id.to_owned(),
+        version_dir: version_dir.clone(),
+        manifest_path: manifest_path.clone(),
+        jar_present: false,
+        manifest_id: None,
+        inherits: Vec::new(),
+        registered,
+        problems: Vec::new(),
+    };
+
+    // ① id 能不能当路径用：不能的话后面的 join 全不可信，直接结束。
+    if let Err(problem) = validate_version_id(version_id) {
+        candidate.problems.push(problem);
+        return candidate;
+    }
+    // ② 版本目录解析到根外（符号链接 / 目录联接 / 祖先链接）⇒ 立刻停手：
+    //    **一个字节都不去读**那个目录（读它就等于读别人的启动器数据）。
+    if let Some(problem) = ensure_inside(&version_dir, root) {
+        candidate.problems.push(problem);
+        return candidate;
+    }
+    // ③ 清单必须在（`installed_versions` 的判据同源）。
+    if !manifest_path.is_file() {
+        candidate.problems.push(AdoptProblem::ManifestMissing {
+            version_id: version_id.to_owned(),
+            path: manifest_path,
+        });
+        return candidate;
+    }
+    if let Some(problem) = ensure_inside(&manifest_path, root) {
+        candidate.problems.push(problem);
+        return candidate;
+    }
+    candidate.jar_present = game.version_jar(version_id).is_file();
+
+    // ④ 清单读得出来、id 对得上。
+    let manifest = match read_manifest(&manifest_path) {
+        Ok(manifest) => manifest,
+        Err(problem) => {
+            candidate.problems.push(problem);
+            return candidate;
+        }
+    };
+    let manifest_id = manifest.id.clone();
+    candidate.manifest_id = manifest_id.clone();
+    match manifest_id.as_deref() {
+        None => {
+            candidate.problems.push(AdoptProblem::ManifestMissingId {
+                path: manifest_path.clone(),
+            });
+            return candidate;
+        }
+        Some(id) if id != version_id => {
+            candidate.problems.push(AdoptProblem::ManifestIdMismatch {
+                path: manifest_path.clone(),
+                manifest_id: id.to_owned(),
+                directory_id: version_id.to_owned(),
+            });
+        }
+        Some(_) => {}
+    }
+
+    // ⑤ 继承链走到底（缺父 / 环 / 父清单坏 / 父 id 不匹配都在这条路上报）。
+    match walk_chain(game, root, &manifest_path, manifest) {
+        Ok(chain) => {
+            candidate.inherits = chain;
+            // 走查通过后再让 `resolve` 做一次权威判定：两处判据不许漂。
+            if let Some(problem) = resolve_verdict(game, &candidate.manifest_path) {
+                candidate.problems.push(problem);
+            }
+        }
+        Err(problem) => candidate.problems.push(problem),
+    }
+    candidate
+}
+
+/// 走 `inheritsFrom` 链，返回 [自身, 父, 祖父, …]；任一层不合格就返回那条问题。
+fn walk_chain(
+    game: &GameLayout,
+    root: &Path,
+    manifest_path: &Path,
+    manifest: VersionJson,
+) -> Result, AdoptProblem> {
+    let Some(self_id) = manifest.id.clone() else {
+        return Err(AdoptProblem::ManifestMissingId {
+            path: manifest_path.to_path_buf(),
+        });
+    };
+    let mut chain = vec![self_id];
+    let mut current = manifest;
+    while let Some(parent) = current.inherits_from.clone() {
+        if chain.iter().any(|id| id == &parent) {
+            let mut loop_chain = chain.clone();
+            loop_chain.push(parent);
+            return Err(AdoptProblem::CircularInheritance { chain: loop_chain });
+        }
+        validate_version_id(&parent)?;
+        let required_by = chain.last().cloned().unwrap_or_default();
+        let parent_dir = game.version_dir(&parent);
+        let parent_path = game.version_json(&parent);
+        // 父版本同样先过边界（越界就不读），再判存在。
+        if let Some(problem) = ensure_inside(&parent_dir, root) {
+            return Err(problem);
+        }
+        if !parent_path.is_file() {
+            return Err(AdoptProblem::MissingParent {
+                parent,
+                required_by,
+            });
+        }
+        if let Some(problem) = ensure_inside(&parent_path, root) {
+            return Err(problem);
+        }
+        let parent_manifest = read_manifest(&parent_path)?;
+        match parent_manifest.id.as_deref() {
+            None => return Err(AdoptProblem::ManifestMissingId { path: parent_path }),
+            Some(id) if id != parent => {
+                return Err(AdoptProblem::ManifestIdMismatch {
+                    path: parent_path,
+                    manifest_id: id.to_owned(),
+                    directory_id: parent,
+                })
+            }
+            Some(_) => {}
+        }
+        chain.push(parent);
+        current = parent_manifest;
+    }
+    Ok(chain)
+}
+
+/// 用 `core::game::resolve` 判一次继承链（权威结论；失败就如实报，不猜）。
+fn resolve_verdict(game: &GameLayout, manifest_path: &Path) -> Option {
+    let manifest = read_manifest(manifest_path).ok()?;
+    let source = |id: &str| -> Option {
+        let bytes = std::fs::read(game.version_json(id)).ok()?;
+        VersionJson::from_json_slice(&bytes).ok()
+    };
+    match inherit::resolve(&source, &manifest) {
+        Ok(_) => None,
+        Err(error) => Some(AdoptProblem::InheritanceInvalid {
+            detail: error.to_string(),
+        }),
+    }
+}
+
+/// 读一份清单（错误带路径与 serde 的行列号）。
+fn read_manifest(path: &Path) -> Result {
+    let bytes = std::fs::read(path).map_err(|error| AdoptProblem::ManifestUnreadable {
+        path: path.to_path_buf(),
+        message: error.to_string(),
+    })?;
+    VersionJson::from_json_slice(&bytes).map_err(|error| match error {
+        GameError::Json { source, .. } => AdoptProblem::ManifestInvalidJson {
+            path: path.to_path_buf(),
+            message: source.to_string(),
+        },
+        other => AdoptProblem::ManifestInvalidJson {
+            path: path.to_path_buf(),
+            message: other.to_string(),
+        },
+    })
+}
+
+/// 绑定这个版本 id 的全部实例档案。
+fn registered_for(profiles: &ProfileList, version_id: &str) -> Vec {
+    profiles
+        .profiles
+        .iter()
+        .filter(|profile| profile.version_id == version_id)
+        .map(|profile| RegisteredInstance {
+            id: profile.id.as_str().to_owned(),
+            name: profile.name.clone(),
+        })
+        .collect()
+}
+
+/// 非 UTF-8 目录名：当成一条不可登记的候选（丢掉它就等于「静默少一行」）。
+fn unreadable_id_candidate(path: &Path, versions_dir: &Path) -> AdoptCandidate {
+    let shown = path
+        .strip_prefix(versions_dir)
+        .unwrap_or(path)
+        .to_string_lossy()
+        .into_owned();
+    AdoptCandidate {
+        version_id: shown,
+        version_dir: path.to_path_buf(),
+        manifest_path: path.to_path_buf(),
+        jar_present: false,
+        manifest_id: None,
+        inherits: Vec::new(),
+        registered: Vec::new(),
+        problems: vec![AdoptProblem::DirectoryUnreadable {
+            path: path.to_path_buf(),
+            message: "目录名不是合法 UTF-8，不能作为版本 id".to_owned(),
+        }],
+    }
+}
+
+/// 断链符号链接：`versions/` 里有这个条目，但指不到任何东西。
+fn broken_link_candidate(version_id: &str, path: &Path) -> AdoptCandidate {
+    AdoptCandidate {
+        version_id: version_id.to_owned(),
+        version_dir: path.to_path_buf(),
+        manifest_path: path.to_path_buf(),
+        jar_present: false,
+        manifest_id: None,
+        inherits: Vec::new(),
+        registered: Vec::new(),
+        problems: vec![AdoptProblem::SymlinkUnresolvable {
+            path: path.to_path_buf(),
+            message: "符号链接的目标不存在（断链）".to_owned(),
+        }],
+    }
+}
+
+/// 沿祖先找**最近的已存在入口**（自身优先；一路到盘根都没有 ⇒ `None`）。
+///
+/// 用途：`read_dir` 的 `NotFound` 不代表「这个数据根是空的」——断链可能发生在更高的祖先上
+/// （迁移联接的目标被搬走时，`versions` 和游戏根都 NotFound，但入口还在）。判据是**存在性**
+/// （`symlink_metadata`，不跟随），能不能解析由调用方另行判定。
+fn nearest_existing_entry(path: &Path) -> Option {
+    let mut probe = path.to_path_buf();
+    loop {
+        if std::fs::symlink_metadata(&probe).is_ok() {
+            return Some(probe);
+        }
+        if !probe.pop() {
+            return None;
+        }
+    }
+}
diff --git a/crates/core/src/game/adopt/paths.rs b/crates/core/src/game/adopt/paths.rs
new file mode 100644
index 0000000..2258033
--- /dev/null
+++ b/crates/core/src/game/adopt/paths.rs
@@ -0,0 +1,84 @@
+//! 路径判据：版本 id 能不能当路径用、已有条目是不是跑出了游戏根（符号链接 / 目录联接 / 祖先链接）。
+//!
+//! 两条判据都与「登记只读」直接相关：id 不可信 ⇒ `versions//` 可能落到别人的目录上；
+//! 越界 ⇒ 我们以为在游戏根里的东西其实在外面（读它就等于读别的启动器的数据）。
+//! 判据写成纯函数，好在这一层单独变异。
+
+use std::path::{Path, PathBuf};
+
+use super::super::layout::GameLayout;
+use super::candidate::AdoptProblem;
+
+/// 游戏根的「真实」形式（符号链接越界判据的比较基准）。
+///
+/// 拿不到（根还不存在 / 无权限）时退回原始路径：那种情况下不会有已存在的符号链接能通过元数据检查，
+/// 越界判据仍能给出「不在根内」的结论，而不是静默放行。
+pub(super) fn root_of(game: &GameLayout) -> PathBuf {
+    game.root()
+        .canonicalize()
+        .unwrap_or_else(|_| game.root().to_path_buf())
+}
+
+/// 边界判据：**已存在**的路径，其真实（解析符号链接/目录联接之后）位置必须在游戏根内。
+///
+/// 为什么不是 `is_symlink` 一刀切：
+/// - `is_symlink` 看不到 Windows 的**目录联接（junction）**和大部分重解析点——而 junction 不需要
+///   管理员权限就能建，正是「把别人的版本目录挂进来」最容易的形态；
+/// - 祖先链接同样要算：`versions/` 本身是 junction 时，每个 `versions/` 都解析到根外，
+///   单看 `` 这一层还是普通目录。
+///
+/// 所以这里一律 `canonicalize` 后与**真实游戏根**做前缀比较：根内的链接照旧放行（合法的省盘做法），
+/// 根外的一律给出 [`AdoptProblem::OutsideGameRoot`]。路径不存在 ⇒ `None`（存在性由调用方的
+/// 「清单缺失」判据负责，别把「还没装」说成「越界」）。
+///
+/// **已知边界**：判据是「检查那一刻」的快照，检查与读取之间若有人把目录换成链接（TOCTOU），
+/// 本函数看不到——本模块不是并发/对抗入口，不做跨进程锁。
+pub(super) fn ensure_inside(path: &Path, root: &Path) -> Option {
+    if std::fs::symlink_metadata(path).is_err() {
+        return None;
+    }
+    match path.canonicalize() {
+        Ok(target) if target.starts_with(root) => None,
+        Ok(target) => Some(AdoptProblem::OutsideGameRoot {
+            path: path.to_path_buf(),
+            target,
+            root: root.to_path_buf(),
+        }),
+        Err(error) => Some(AdoptProblem::SymlinkUnresolvable {
+            path: path.to_path_buf(),
+            message: error.to_string(),
+        }),
+    }
+}
+
+/// 版本 id 的路径安全判据（空 / 分隔符 / 盘符 / NUL / 结尾点号空格都拒绝）。
+///
+/// 结尾的点号与空格必须拒绝：Win32 会在建目录时把它们**静默剥掉**，于是
+/// `versions/1.20.1.` 与 `versions/1.20.1` 会落到同一个目录上——两个「不同 id」指向一份文件。
+pub(super) fn validate_version_id(version_id: &str) -> Result<(), AdoptProblem> {
+    let invalid = |reason: &'static str| {
+        Err(AdoptProblem::VersionIdInvalid {
+            version_id: version_id.to_owned(),
+            reason,
+        })
+    };
+    if version_id.trim().is_empty() {
+        return invalid("为空");
+    }
+    if version_id.contains('/') || version_id.contains('\\') {
+        return invalid("含路径分隔符");
+    }
+    if version_id.contains(':') {
+        return invalid("含冒号（盘符 / NTFS 数据流）");
+    }
+    if version_id.contains('\0') || version_id.chars().any(|ch| ch.is_control()) {
+        return invalid("含控制字符");
+    }
+    if version_id == "." || version_id == ".." {
+        return invalid("是相对路径标记");
+    }
+    if version_id.ends_with('.') || version_id.ends_with(' ') {
+        return invalid("以点号或空格结尾（Win32 会剥掉，落到别的目录上）");
+    }
+    Ok(())
+}
diff --git a/crates/core/src/game/adopt/plan.rs b/crates/core/src/game/adopt/plan.rs
new file mode 100644
index 0000000..cf3ffa2
--- /dev/null
+++ b/crates/core/src/game/adopt/plan.rs
@@ -0,0 +1,287 @@
+//! 落点计算与真正的登记：`plan`（纯算 + 零写盘）与 `adopt`（plan + 只写自己的两份配置）。
+//!
+//! # 写盘面（全部在 ULL 数据根下，游戏根一个字节都不动）
+//!
+//! 1. `config/instances/.json`（实例设置：隔离档 + 运行目录）；
+//! 2. `config/profiles.json`（档案列表）；
+//! 3. 选了缺省运行目录时，`/instances/<实例目录名>` 这个空目录（已存在且非空 ⇒ 拒绝；
+//!    路径上的已有祖先若解析到**数据根之外**（符号链接/目录联接）⇒ 拒绝，不沿它写盘；
+//!    已被**别的实例**占着 ⇒ 顺延 `-2`/`-3` 后缀，绝不让两个实例共用同一个运行目录）。
+//!
+//! 写配置**之前**还要核一遍真实写面（`config/`、`config/instances/`、`profiles.json` 必须落在
+//! `<.ULL>` 内、且默认写盘面不得与游戏树重叠），判据见 [`fspaths`]。
+//!
+//! `versions/` `libraries/` `assets/` **一个字节都不写**：登记只填 `version_id`，内容靠 D20 的
+//! 「恒共享层」被启动/下载链路复用（[`crate::game::isolation::SHARED_LAYERS`]）。
+
+use std::path::{Path, PathBuf};
+
+use super::super::install::instance::{read_profiles, register_with, InstanceSettings, Isolation};
+use super::super::layout::GameLayout;
+use super::super::profiles::ProfileList;
+use super::candidate::{AdoptCandidate, AdoptTarget};
+use super::error::AdoptError;
+use super::fspaths;
+use super::inspect::inspect;
+use super::run_dir;
+use crate::platform::layout::LauncherLayout;
+
+/// 一次登记请求（CLI / presenter 的输入形状）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AdoptRequest {
+    /// 要接进来的版本 id（= `versions//`）。
+    pub version_id: String,
+    /// 展示名；缺省 = 版本 id。
+    pub name: Option,
+    /// 运行目录选择（缺省 [`AdoptTarget::InstanceDir`]，**不是** `isolated`）。
+    pub target: AdoptTarget,
+    /// 档案的创建时间（RFC-3339；core 不碰时钟格式，由调用方给）。
+    pub created_at: Option,
+}
+
+impl AdoptRequest {
+    /// 最小请求（缺省名 + 缺省运行目录）。
+    #[must_use]
+    pub fn new(version_id: impl Into) -> Self {
+        Self {
+            version_id: version_id.into(),
+            name: None,
+            target: AdoptTarget::default(),
+            created_at: None,
+        }
+    }
+}
+
+/// 一次登记的**计划**（不写任何东西；`--dry-run` / GUI 预检就吃这个）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AdoptPlan {
+    /// 检查过的候选（含问题清单，正常时为空）。
+    pub candidate: AdoptCandidate,
+    /// 将写进档案的展示名。
+    pub name: String,
+    /// 运行目录选择。
+    pub target: AdoptTarget,
+    /// 生效隔离档。
+    pub isolation: Isolation,
+    /// 生效运行目录（= `--gameDir`）。
+    pub run_dir: PathBuf,
+    /// 人读提示（共享/版本目录的后果、已有同版本实例…）。
+    pub notes: Vec,
+}
+
+/// 一次登记的结果。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AdoptOutcome {
+    /// 实例 id（稳定 UUID）。
+    pub instance_id: String,
+    /// 展示名。
+    pub name: String,
+    /// 绑定的版本 id。
+    pub version_id: String,
+    /// 实例设置文件路径。
+    pub config_path: PathBuf,
+    /// 生效隔离档。
+    pub isolation: Isolation,
+    /// 运行目录选择。
+    pub target: AdoptTarget,
+    /// 生效运行目录。
+    pub run_dir: PathBuf,
+    /// 是否新建了档案（`false` 只可能是复用同名同版本档案，本命令会先拒绝那种情况）。
+    pub created: bool,
+    /// 是否新建了缺省运行目录（`false` = 目录已存在但为空、直接复用）。
+    pub dir_created: bool,
+    /// 人读提示（与 [`AdoptPlan::notes`] 同一份）。
+    pub notes: Vec,
+}
+
+/// 计算一次登记：检查候选 + 解析名字 + 查重名 + 算运行目录。**零写盘**。
+///
+/// # Errors
+///
+/// - [`AdoptError::UnknownVersion`]：版本不在盘上；
+/// - [`AdoptError::NotAdoptable`]：候选有问题（清单坏/缺父/环/越界…，原因逐条给出；由
+///   [`inspect`] 判出来）；
+/// - [`AdoptError::DuplicateName`] / [`AdoptError::AlreadyRegistered`]：名字冲突 / 重复登记；
+/// - [`AdoptError::TargetNotEmpty`] / [`AdoptError::TargetInvalid`]：运行目录不可用；
+/// - [`AdoptError::Game`]：`profiles.json` 读不了。
+pub fn plan(
+    game: &GameLayout,
+    launcher: &LauncherLayout,
+    request: &AdoptRequest,
+) -> Result {
+    // 写盘面两道判据都放在 `inspect` 之前（dry-run 也要报，别让预检说「可以」）：
+    // ① 默认写盘面不得与**受保护游戏树**重叠（r2 R2.2；整体迁移到游戏树外照旧允许）；
+    // ② 配置落点必须在 `<.ULL>` 内（r1 R2）。
+    // 放前面是有意的——检查候选的读盘也会穿过 `config/`（`profiles.json`），写面不可信时先停手。
+    fspaths::ensure_surfaces_clear_of_game_tree(game, launcher, None)?;
+    fspaths::ensure_config_write_surface(launcher)?;
+    // `inspect` 只在候选**可登记**时返回 `Ok`，不合格一律是 `NotAdoptable`（问题清单已带出）。
+    let candidate = inspect(game, launcher, &request.version_id)?;
+    let name = resolve_name(request.name.as_deref(), &candidate.version_id);
+    let profiles = read_profiles(launcher)?;
+    let mut notes = Vec::new();
+    // 重名与重复登记：**显式报错**，不静默复用（复用会把用户「导入这个」的意图改成「改一个别的实例」）。
+    if let Some(existing) = profiles
+        .profiles
+        .iter()
+        .find(|profile| profile.name == name)
+    {
+        if existing.version_id == candidate.version_id {
+            return Err(AdoptError::AlreadyRegistered {
+                version_id: candidate.version_id.clone(),
+                name,
+                instance_id: existing.id.as_str().to_owned(),
+            });
+        }
+        return Err(AdoptError::DuplicateName {
+            name,
+            instance_id: existing.id.as_str().to_owned(),
+        });
+    }
+    for profile in &candidate.registered {
+        notes.push(format!(
+            "这个版本已经有实例了：`{}`（id {}）——再登记会得到第二个实例，两个实例共用同一份版本文件",
+            profile.name, profile.id
+        ));
+    }
+
+    let (run_dir, bump_notes) = run_dir_of(
+        game,
+        launcher,
+        &candidate.version_id,
+        &name,
+        &request.target,
+        &profiles,
+    )?;
+    notes.extend(bump_notes);
+    // 缺省运行目录也要落在游戏树之外（`shared`/`version_dir`/`custom` 是显式选择，不复检）。
+    if request.target == AdoptTarget::InstanceDir {
+        fspaths::ensure_surfaces_clear_of_game_tree(game, launcher, Some(&run_dir))?;
+    }
+    notes.extend(target_notes(&request.target, &run_dir));
+
+    Ok(AdoptPlan {
+        candidate,
+        name,
+        target: request.target.clone(),
+        isolation: request.target.isolation(),
+        run_dir,
+        notes,
+    })
+}
+
+/// 按计划登记：先准备缺省运行目录（若选了它），再写实例设置与档案。
+///
+/// # Errors
+///
+/// 同 [`plan`]，外加建目录/写配置失败（[`AdoptError::Game`]）。
+pub fn adopt(
+    game: &GameLayout,
+    launcher: &LauncherLayout,
+    request: &AdoptRequest,
+) -> Result {
+    let plan = plan(game, launcher, request)?;
+    // `plan` 已核过；写盘前再核一次（中间可能有别人动过树），失败就一个字节都不写。
+    fspaths::ensure_surfaces_clear_of_game_tree(game, launcher, None)?;
+    if plan.target == AdoptTarget::InstanceDir {
+        fspaths::ensure_surfaces_clear_of_game_tree(game, launcher, Some(&plan.run_dir))?;
+    }
+    fspaths::ensure_config_write_surface(launcher)?;
+    let mut dir_created = false;
+    // 目录先建：建不出来就一个配置都不写（失败的残留是一个空目录，可复用）。
+    if plan.target == AdoptTarget::InstanceDir && !plan.run_dir.is_dir() {
+        run_dir::ensure_inside_data(launcher, &plan.run_dir)?;
+        std::fs::create_dir_all(&plan.run_dir)
+            .map_err(|error| AdoptError::Game(crate::game::GameError::io(&plan.run_dir, error)))?;
+        dir_created = true;
+        // 建完再核一次：`create_dir_all` 会沿已存在的目录联接走，越过边界就不算成功。
+        run_dir::ensure_inside_data(launcher, &plan.run_dir)?;
+    }
+    let settings = InstanceSettings {
+        isolation: Some(plan.isolation),
+        game_dir: match &plan.target {
+            // `custom` 档必须有运行目录：缺省目录与用户目录都要落进 `gameDir`。
+            AdoptTarget::InstanceDir | AdoptTarget::Custom(_) => Some(plan.run_dir.clone()),
+            AdoptTarget::Shared | AdoptTarget::VersionDir => None,
+        },
+    };
+    let registration = register_with(
+        launcher,
+        &plan.name,
+        &plan.candidate.version_id,
+        request.created_at.as_deref(),
+        &settings,
+    )?;
+    Ok(AdoptOutcome {
+        instance_id: registration.profile.id.as_str().to_owned(),
+        name: registration.profile.name.clone(),
+        version_id: registration.profile.version_id.clone(),
+        config_path: registration.config_path,
+        isolation: plan.isolation,
+        target: plan.target,
+        run_dir: plan.run_dir,
+        created: registration.created,
+        dir_created,
+        notes: plan.notes,
+    })
+}
+
+/// 运行目录的派生（缺省落点复用整合包导入的 `/instances/<实例目录名>`）。
+///
+/// 缺省档**必须**查「已有实例占着哪个真实目录」（R1）：slug 与大小写不敏感都会让两个不同展示名
+/// 落到同一个物理目录上；撞上就顺延后缀（见 [`run_dir::derive_instance_dir`]），而不是让两个
+/// 实例悄悄共用一个运行目录。返回（目录，顺延提示）。
+fn run_dir_of(
+    game: &GameLayout,
+    launcher: &LauncherLayout,
+    version_id: &str,
+    name: &str,
+    target: &AdoptTarget,
+    profiles: &ProfileList,
+) -> Result<(PathBuf, Vec), AdoptError> {
+    match target {
+        AdoptTarget::InstanceDir => {
+            let claims = run_dir::claims(launcher, profiles)?;
+            run_dir::derive_instance_dir(launcher, name, &claims)
+        }
+        AdoptTarget::Shared => Ok((game.root().to_path_buf(), Vec::new())),
+        AdoptTarget::VersionDir => Ok((game.version_dir(version_id), Vec::new())),
+        AdoptTarget::Custom(dir) => Ok((run_dir::resolve_custom_dir(dir)?, Vec::new())),
+    }
+}
+
+/// 运行目录选择的后果说明（人读；CLI 与 GUI 共用同一份话术）。
+///
+/// `shared` / `version_dir` 必须**明确告知**：它们会把玩家数据写进别人的 `.minecraft`
+/// （D20 的 `isolated` 档运行目录就是 `versions//`）。
+#[must_use]
+pub fn target_notes(target: &AdoptTarget, run_dir: &Path) -> Vec {
+    match target {
+        AdoptTarget::InstanceDir => vec![format!(
+            "运行目录 = {}（ULL 数据区新建，与别人的 .minecraft 隔离；versions/libraries/assets 仍按 D20 恒共享，不复制）",
+            run_dir.display()
+        )],
+        AdoptTarget::Shared => vec![format!(
+            "运行目录 = 游戏根 {}（共享档）：mods/saves/config 会落在别人的 .minecraft 里，与其它启动器共用；\
+             要隔离请用缺省（ULL 数据区新目录）或 --isolation custom --game-dir ",
+            run_dir.display()
+        )],
+        AdoptTarget::VersionDir => vec![format!(
+            "运行目录 = 版本目录 {}（版本隔离档）：第一次启动会在这里新增 mods/saves/config/logs，\
+             而这个目录是别的启动器的版本目录（不覆盖已有文件）；要隔离请用缺省或 --isolation custom",
+            run_dir.display()
+        )],
+        AdoptTarget::Custom(_) => vec![format!(
+            "运行目录 = {}（用户指定；不新建、不改动其中已有内容）",
+            run_dir.display()
+        )],
+    }
+}
+
+/// 展示名：去空格，空串退回版本 id（与 `pack import` 的「名字不给就用包名」同一口径）。
+fn resolve_name(name: Option<&str>, version_id: &str) -> String {
+    name.map(str::trim)
+        .filter(|name| !name.is_empty())
+        .map(str::to_string)
+        .unwrap_or_else(|| version_id.to_owned())
+}
diff --git a/crates/core/src/game/adopt/run_dir.rs b/crates/core/src/game/adopt/run_dir.rs
new file mode 100644
index 0000000..c12e559
--- /dev/null
+++ b/crates/core/src/game/adopt/run_dir.rs
@@ -0,0 +1,219 @@
+//! 运行目录与**写盘边界**：缺省目录派生（含碰撞消歧）+ 数据区/配置写面的真实路径判据。
+//!
+//! # 两条铁律（都来自复审 r1 的实测缺陷）
+//!
+//! 1. **两个实例不许悄悄共用同一个运行目录**（R1）：展示名不重复不代表派生目录不重复
+//!    （`Better MC` 与 `Better-MC` 经 slug 同名；Windows 上 `Foo` 与 `foo` 是同一个目录）。
+//!    所以「目录是空的」**不足以**判可复用——还要看**已有实例已经占着哪个真实目录**；
+//!    撞上了就顺延到 `-2`、`-3`…（原因写进 notes），而不是让两个实例共用一个。
+//! 2. **只写 ULL 自己的配置**：配置写面与「默认写盘面不得与受保护游戏树重叠」两条判据在
+//!    [`super::fspaths`]（`ensure_config_write_surface` / `ensure_surfaces_clear_of_game_tree`），
+//!    本模块只负责**运行目录派生**与「缺省目录必须落在数据区」这一条。
+//!
+//! # 判据的基准（为什么不拿 `/instances` 或 `<.ULL>/config` 当基准）
+//!
+//! 被保护的**边界自己是链接**时，拿它当基准等于把越界当正常。所以基准一律是**解析后的父级**：
+//! 数据写面看 ``（本模块只负责这一条）；配置写面（`<.ULL>` 内、并额外排除游戏根）已移交
+//! [`super::fspaths`] 的 `ensure_config_write_surface` / `ensure_surfaces_clear_of_game_tree`，
+//! 不在本模块的判据里。用户把整棵树迁到别的盘（`<.ULL>` 或 `` 本身是联接/符号链接）
+//! 仍然允许——判据是落点，不是路径长得像不像。
+//!
+//! # 已知边界
+//!
+//! 判据是「检查那一刻」的快照：检查与 `create_dir_all`/写盘之间被人换掉组件（TOCTOU）看不到。
+//! 本命令不是并发/对抗入口，不做跨进程锁。
+
+use std::path::{Path, PathBuf};
+
+use super::super::install::instance::read_instance_config;
+use super::super::install::pack_dir;
+use super::super::profiles::ProfileList;
+use super::error::AdoptError;
+use super::fspaths;
+use crate::platform::layout::LauncherLayout;
+
+/// 派生目录撞车时最多顺延多少个后缀（`-2` … `-33`）。撞满即报错，不无限找。
+const MAX_SUFFIX: u32 = 32;
+
+/// 一个「已有实例已经占着的运行目录」。
+///
+/// 只收 `gameDir`（现役设置文件里的，或 M27 前档案的遗留 `game_dir`）：`shared` / `isolated`
+/// 档的运行目录是**派生**的（游戏根 / `versions/`），与缺省落点 `/instances/<名>`
+/// 不可能相等，收进来只会制造噪音。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(super) struct RunDirClaim {
+    /// 占着这个目录的实例 id。
+    pub(super) instance_id: String,
+    /// 实例展示名（写进提示给人看）。
+    pub(super) name: String,
+    /// 声明/绑定的运行目录（原样，未真实化）。
+    pub(super) dir: PathBuf,
+    /// 比较用的键（真实化路径 + 大小写归一，见 [`dir_key`]）。
+    pub(super) key: String,
+}
+
+/// 收集现有实例占着的运行目录（读 `config/instances/.json`；读不了就是错误，不猜）。
+///
+/// # Errors
+///
+/// 实例设置文件读不出来 / JSON 坏：`AdoptError::Game`。
+pub(super) fn claims(
+    launcher: &LauncherLayout,
+    profiles: &ProfileList,
+) -> Result, AdoptError> {
+    let mut out = Vec::new();
+    for profile in &profiles.profiles {
+        let config = read_instance_config(launcher, profile.id.as_str())?;
+        let dir = config
+            .and_then(|config| config.game_dir)
+            .or_else(|| profile.game_dir.clone());
+        let Some(dir) = dir.filter(|dir| !dir.as_os_str().is_empty()) else {
+            continue;
+        };
+        out.push(RunDirClaim {
+            instance_id: profile.id.as_str().to_owned(),
+            name: profile.name.clone(),
+            key: dir_key(&dir),
+            dir,
+        });
+    }
+    Ok(out)
+}
+
+/// 缺省运行目录：`/instances/<实例目录名>`，撞车/占用时顺延后缀。
+///
+/// 判据顺序（三条都要过）：
+/// 1. 路径上的已有祖先解析后必须仍在数据根内（[`ensure_inside_data`]）；
+/// 2. **不能**是已有实例占着的目录（按真实路径比较，[`dir_key`]）——撞上就顺延；
+/// 3. 目录必须不存在或为空（非空且无人认领 = 用户数据，拒绝而不是换目录）。
+///
+/// 返回派生目录 + 人读提示（顺延过就有一条，没顺延就是空）。
+///
+/// # Errors
+///
+/// 数据区越界（`TargetInvalid`）、非空目录（`TargetNotEmpty`）、后缀撞满（`NoFreeRunDir`）、
+/// 读实例设置失败（`Game`）。
+pub(super) fn derive_instance_dir(
+    launcher: &LauncherLayout,
+    name: &str,
+    claims: &[RunDirClaim],
+) -> Result<(PathBuf, Vec), AdoptError> {
+    let base = pack_dir::instance_dir(launcher, name);
+    let mut bumped: Vec = Vec::new();
+    let mut attempt = base.clone();
+    let mut suffix = 1;
+    loop {
+        ensure_inside_data(launcher, &attempt)?;
+        let key = dir_key(&attempt);
+        match claims.iter().find(|claim| claim.key == key) {
+            Some(claim) => {
+                bumped.push(claim.clone());
+                suffix += 1;
+                if suffix > MAX_SUFFIX {
+                    return Err(AdoptError::NoFreeRunDir { base });
+                }
+                attempt = with_suffix(&base, suffix);
+            }
+            None if directory_occupied(&attempt) => {
+                // 非空且没有实例认领 ⇒ 用户自己的数据：不覆盖，也不偷偷换个目录把它晾在一边。
+                return Err(AdoptError::TargetNotEmpty { path: attempt });
+            }
+            None => {
+                let mut notes = Vec::new();
+                if let Some(claim) = bumped.first() {
+                    notes.push(format!(
+                        "派生目录 {} 与已有实例 `{}`（id {}）的运行目录 {} 是同一个物理目录，\
+                         已改用 {} —— 两个实例不会共用同一个运行目录",
+                        base.display(),
+                        claim.name,
+                        claim.instance_id,
+                        claim.dir.display(),
+                        attempt.display()
+                    ));
+                }
+                return Ok((attempt, notes));
+            }
+        }
+    }
+}
+
+/// `-2` / `-3` …（只动最后一段）。
+fn with_suffix(base: &Path, suffix: u32) -> PathBuf {
+    let name = base
+        .file_name()
+        .map(|name| name.to_string_lossy().into_owned())
+        .unwrap_or_default();
+    base.with_file_name(format!("{name}-{suffix}"))
+}
+
+/// 缺省运行目录必须**真的**落在启动器数据根之下。
+///
+/// 边界是 ``（`/.ULL/data`）而不是 `/instances`：后者本身可能就是链接，
+/// 拿它当基准等于把「越界」当成「正常」。
+///
+/// # Errors
+///
+/// 解析后跑出数据根（`TargetInvalid`）。
+pub(super) fn ensure_inside_data(launcher: &LauncherLayout, dir: &Path) -> Result<(), AdoptError> {
+    let Some(data_real) = fspaths::existing_real(&launcher.data()) else {
+        // 连数据根都还不存在 ⇒ 不可能已经有指向外面的链接。
+        return Ok(());
+    };
+    if let Some(dir_real) = fspaths::existing_real(dir) {
+        if !dir_real.starts_with(&data_real) {
+            return Err(AdoptError::TargetInvalid {
+                detail: format!(
+                    "运行目录 {} 解析到 {}，落在数据根 {} 之外：数据区里有指向外部的符号链接/目录联接，拒绝沿它写盘",
+                    dir.display(),
+                    dir_real.display(),
+                    data_real.display()
+                ),
+            });
+        }
+    }
+    Ok(())
+}
+
+/// `custom` 运行目录的用法判据（绝对路径 / 非空）。
+///
+/// # Errors
+///
+/// 相对路径或空路径：`TargetInvalid`。
+pub(super) fn resolve_custom_dir(dir: &Path) -> Result {
+    if dir.as_os_str().is_empty() {
+        return Err(AdoptError::TargetInvalid {
+            detail: "运行目录为空".to_owned(),
+        });
+    }
+    if !dir.is_absolute() {
+        return Err(AdoptError::TargetInvalid {
+            detail: format!("--game-dir 需要绝对路径，收到 `{}`", dir.display()),
+        });
+    }
+    Ok(dir.to_path_buf())
+}
+
+/// 目录是否「有人在用」（存在且非空）。空目录是上次失败的残留，可复用。
+pub(super) fn directory_occupied(path: &Path) -> bool {
+    std::fs::read_dir(path).is_ok_and(|mut entries| entries.next().is_some())
+}
+
+/// **比较用**的真实路径键：真实化 + 平台别名归一（Win32 尾点/尾空格，见 [`fspaths`]）+ 大小写归一。
+///
+/// 大小写归一只在大小写不敏感的平台做（Windows / 默认 macOS）：`Foo` 与 `foo` 是同一个目录，
+/// 不归一会让「两个实例共用目录」这一条在 Windows 上漏掉（复审 r1 的实测之一）。
+/// **Windows 上还要折叠尾点/尾空格**（`Foo.` / `Foo ` 都是 `Foo`）——否则「尚不存在的认领目录」
+/// 会从这条缝里绕过碰撞判定（复审 r2 的 R2.1）。verbatim 路径（`\?\…`）不折叠，交给平台语义。
+///
+/// **策略是保守的**：macOS 也可能是大小写敏感的 APFS 卷，那时 `Foo` 与 `foo` 本来是**不同**目录，
+/// 归一后会判成碰撞 ⇒ 顺延 `-2`。代价是目录名可能多一个后缀，换来的是「绝不共用」这条不变量
+/// 在任何卷上都成立（判错的方向只能是「多一次顺延」，不能是「共用一个目录」）。
+///
+/// **目标可能还不存在**：这里不要求路径存在（[`fspaths::comparison_real`] 会拼回尚不存在的尾段），
+/// 因为「实例已经认领了、但目录还没被创建」（`custom` 档就是这种）同样必须参与比较。
+fn dir_key(path: &Path) -> String {
+    match fspaths::comparison_real(path) {
+        Some(real) => fspaths::normalize_key(&real),
+        None => fspaths::normalize_key(path),
+    }
+}
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,
+    /// 特性开关限制（`has_custom_resolution`、`is_demo_user`…）。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub features: Option>,
+}
+
+/// 规则的 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,
+    /// OS 版本模式。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub version: Option,
+    /// 架构模式（`x86`、`x86_64`、`arm64`）。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub arch: Option,
+}
+
+/// 求值时的运行环境（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,
+}
+
+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, 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 {
+        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,
+    /// 命中后的参数值（单个或多个）。
+    pub value: ArgumentValue,
+}
+
+/// 参数值：单个字符串或多个字符串。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(untagged)]
+pub enum ArgumentValue {
+    /// 单个参数。
+    One(String),
+    /// 多个参数。
+    Many(Vec),
+}
+
+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) {
+        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,
+    /// JVM 参数（`-Xmx` 之类之外的那部分）。
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub jvm: Vec,
+}
+
+impl Arguments {
+    /// 合并两层参数：**父在前、子在后**（analyse/03 §4.4）。
+    pub fn merge(parent: Option<&Arguments>, child: Option<&Arguments>) -> Option {
+        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,
+    /// 展开后的 JVM 参数。
+    pub jvm: Vec,
+}
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) -> 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,
+    },
+    /// 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, source: serde_json::Error) -> Self {
+        Self::Json {
+            context: context.into(),
+            source,
+        }
+    }
+
+    /// 包装 IO 错误并带上路径。
+    pub fn io(path: impl Into, 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..fe5ee3f
--- /dev/null
+++ b/crates/core/src/game/inherit.rs
@@ -0,0 +1,208 @@
+//! `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;
+}
+
+impl VersionSource for BTreeMap {
+    fn load(&self, id: &str) -> Option {
+        self.get(id).cloned()
+    }
+}
+
+impl VersionSource for F
+where
+    F: Fn(&str) -> Option,
+{
+    fn load(&self, id: &str) -> Option {
+        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(
+    source: &S,
+    manifest: &VersionJson,
+) -> Result {
+    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 = 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 维持。
+///
+/// # 两种 args 表达的语义**不一样**（M222 核实，别混）
+///
+/// - `arguments.game` / `arguments.jvm`：父在前、子在后**追加**（[`Arguments::merge`]）；
+/// - `minecraftArguments`（pre-1.13 的单串）：**子覆盖父**，子不写才继承。
+///
+/// 所以「叠一层加载器」只能往 `arguments.game` 里加参数；往 `minecraftArguments` 里写会把父链
+/// （例如 Forge 1.12.2 的 `--tweakClass FMLTweaker`）整串顶掉。回归：
+/// `crates/core/tests/liteloader/install.rs` 的 `merge_laws_liteloader_depends_on` 与
+/// `stacks_on_forge_and_keeps_the_forge_tweak_class`。
+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/.json`）的模型与逐对象展开。
+//!
+//! 依据：`DevDocs/analyse/03-version-download.md` §6.5（索引下载）、§6.6（逐对象下载）。
+//!
+//! 对象是**内容寻址**的：路径 `assets/objects//`、URL
+//! `https://resources.download.minecraft.net//`，校验值就是哈希本身。
+//! 因此索引里不需要 `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/`。
+    #[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/`、
+/// `resources/`），不影响下载，这里保真存下但不消费。
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct AssetIndex {
+    /// 对象表：键是资源名（`minecraft/sounds/...ogg`），值是内容描述。
+    #[serde(default)]
+    pub objects: BTreeMap,
+    /// 旧版：是否要在启动期铺到 `assets/virtual//`。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub r#virtual: Option,
+    /// 旧版：是否要映射到存档目录旁的 `resources/`。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub map_to_resources: Option,
+}
+
+impl AssetIndex {
+    /// 解析索引 JSON。
+    ///
+    /// # Errors
+    ///
+    /// JSON 非法（例如镜像返回了 HTML 错误页）时返回 [`GameError::Json`]。
+    pub fn from_json_slice(bytes: &[u8]) -> Result {
+        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, 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..8a3c16f
--- /dev/null
+++ b/crates/core/src/game/install/execute.rs
@@ -0,0 +1,399 @@
+//! 落盘执行：跳过判定 → 并发下载（引擎负责镜像/退避/续传/校验）→ 原子写版本 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, PathBuf};
+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::report::ManifestWrite;
+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//.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,
+) -> Result {
+    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,
+    cancel: Option<&AtomicBool>,
+) -> Result {
+    if is_cancelled(cancel) {
+        return Err(cancelled_error());
+    }
+    let mut outcomes: Vec = 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 = 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 mut warnings = plan.warnings.clone();
+    let manifest = if complete {
+        let written = write_version_json(&plan.version_json_path, plan)?;
+        // **M216 ③**：替换了别人的清单要大声说一句（`report.warnings` 会进 CLI 的 `--json`，
+        // GUI 侧另有结构化的 `manifest` 字段可读）。内容相同（重装）不在此列。
+        if let Some(backup) = written.backup() {
+            warnings.push(format!(
+                "已替换版本清单 {}（旧的那份备份在 {}）：这个 .minecraft 是共享的，别的启动器可能也用它",
+                plan.version_json_path.display(),
+                backup.display()
+            ));
+        }
+        Some(written)
+    } else {
+        None
+    };
+
+    Ok(InstallReport {
+        files: outcomes,
+        version_json: complete.then(|| plan.version_json_path.clone()),
+        manifest,
+        warnings,
+    })
+}
+
+/// 标志是否已置位（`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 {
+    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),
+        },
+    }
+}
+
+/// 写解析后的版本清单（原子写），并如实交代「原来那份怎么办」（**M216 ③**）。
+///
+/// 三条判据：
+/// - 目标不存在 → [`ManifestWrite::Fresh`]，正常写；
+/// - 存在且内容**逐字节相同** → [`ManifestWrite::Identical`]，**一个字节都不写**（重装同版本
+///   是正常操作：既不是冲突，也不该改别人的 mtime）；
+/// - 存在且内容不同（含「存在但读不出来」——读不了 ≠ 相同）→ 旧的那份先 **copy** 到
+///   `.ullbak-`，再原子写 ⇒ [`ManifestWrite::Replaced`]。
+///
+/// 备份用 `copy` 而不是 `rename`：整合包导入的合并态用 rename 是因为它紧接着覆盖同一路径、
+/// 失败还会回滚；这里若 rename 之后原子写失败（目标正被别的启动器占着），盘上会**一份清单
+/// 都不剩**。copy 之下最坏是「原件完好 + 多一份备份」。
+fn write_version_json(
+    path: &Path,
+    plan: &InstallPlan,
+) -> Result {
+    let text = plan.version_json.to_json_string().map_err(|error| {
+        super::InstallError::new(super::InstallErrorKind::Metadata, error.to_string())
+    })?;
+    let bytes = text.as_bytes();
+    if std::fs::read(path).ok().as_deref() == Some(bytes) {
+        return Ok(ManifestWrite::Identical);
+    }
+    let Some(backup) = path.is_file().then(|| backup_manifest(path)) else {
+        write_atomic(path, bytes).map_err(io_error)?;
+        return Ok(ManifestWrite::Fresh);
+    };
+    std::fs::copy(path, &backup).map_err(io_error)?;
+    write_atomic(path, bytes).map_err(io_error)?;
+    Ok(ManifestWrite::Replaced { backup })
+}
+
+/// IO 失败 → 安装错误（`std::io::Error` 与 `PlatformError` 都吃，取 `Display` 原文）。
+fn io_error(error: impl std::fmt::Display) -> super::InstallError {
+    super::InstallError::new(super::InstallErrorKind::Io, error.to_string())
+}
+
+/// `.ullbak-`（与整合包导入同一命名习惯，见 `addon/import/stage/commit.rs`）。
+///
+/// 同一进程里再替换一次时补 `-`：否则第二份备份会盖掉第一份，而第一份很可能才是别人
+/// 启动器铺的那份原文。
+fn backup_manifest(path: &Path) -> PathBuf {
+    let mut name = path
+        .file_name()
+        .map_or_else(|| "version.json".into(), std::ffi::OsStr::to_os_string);
+    name.push(format!(".ullbak-{}", std::process::id()));
+    let mut candidate = path.with_file_name(&name);
+    let mut seq = 1_u32;
+    while candidate.exists() {
+        let mut next = name.clone();
+        next.push(format!("-{seq}"));
+        candidate = path.with_file_name(next);
+        seq += 1;
+    }
+    candidate
+}
+
+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..472f9c0
--- /dev/null
+++ b/crates/core/src/game/install/instance.rs
@@ -0,0 +1,299 @@
+//! 实例登记：`config/profiles.json` + `config/instances/.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/.json` = **每实例设置**，稀疏：只写用户显式改过的键。
+//!
+//! §5 的关键结论：`isolation` 默认 `inherit` 且**不落盘**——这样改全局模式对存量实例立即生效，
+//! 直接避开 PCL2"默认值被固化成实例值"的缺陷。因此 [`InstanceConfig::new`] 的
+//! `isolation` 是 `None`（序列化时整个键消失）；档位的**派生与切换检测**在
+//! [`crate::game::isolation`]（M30 落地），本模块只管结构与落盘。
+//!
+//! # 幂等
+//!
+//! 同一版本重复 `install`：按 `version_id` + 展示名复用已有档案，返回 `created = false`，
+//! 不产生第二个实例、不改已有实例的 id（id 一旦写进档案就是稳定的）。登记本身（含
+//! [`InstanceSettings`] 与 `register_with`）在同目录的 `register` 子模块里。
+
+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::launch_overrides::LaunchOverrides;
+use super::super::profiles::ProfileList;
+use crate::platform::atomic::write_atomic;
+use crate::platform::layout::LauncherLayout;
+
+mod register;
+
+pub use register::{register, register_with, InstanceSettings, Registration};
+
+/// 每实例设置文件的 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//`、
+/// `shared` → 游戏根 `.minecraft/`、`custom` → 用户指定的 `gameDir`。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum Isolation {
+    /// 独立游戏目录（派生 `versions//`）。
+    #[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 {
+        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/.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//`）。
+    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 = custom` 时有值）。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub game_dir: Option,
+    /// 该实例覆盖了哪些设置键。
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub overrides: Vec,
+    /// 实例级启动参数覆盖（M157）：JVM/游戏参数、内存、Java、图形后端五项，逐项回落。
+    ///
+    /// 空段（全 `None`/空白）**不落盘**——与 `isolation` 同一套稀疏语义，清空输入框即「跟随全局」。
+    /// 回落规则与生效值见 [`crate::game::launch_overrides`]。
+    #[serde(default, skip_serializing_if = "LaunchOverrides::is_empty")]
+    pub launch: LaunchOverrides,
+    /// 上次隔离档位切换的记录（`lastModeChange`；没切过就不落盘）。
+    ///
+    /// 由 [`crate::game::isolation::observe_mode`] 维护，只记事实（含双侧探测），**不迁移数据**。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub last_mode_change: Option,
+    /// 未识别字段原样保留（向前兼容）。
+    #[serde(flatten)]
+    pub extra: BTreeMap,
+}
+
+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, D::Error>
+where
+    D: serde::Deserializer<'de>,
+{
+    match Option::::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, version_id: impl Into) -> Self {
+        Self {
+            schema_version: INSTANCE_CONFIG_VERSION,
+            id: id.into(),
+            version_id: version_id.into(),
+            isolation: None,
+            game_dir: None,
+            overrides: Vec::new(),
+            launch: LaunchOverrides::default(),
+            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 {
+        self.last_mode_change.as_mut()?.take_warning()
+    }
+
+    /// 解析。
+    ///
+    /// # Errors
+    ///
+    /// JSON 非法时返回 [`GameError::Json`]。
+    pub fn from_json_str(json: &str) -> Result {
+        serde_json::from_str(json).map_err(|e| GameError::json("instance_config", e))
+    }
+
+    /// 序列化（格式化，便于用户手改与 diff）。
+    ///
+    /// # Errors
+    ///
+    /// 序列化失败时返回 [`GameError::Json`]。
+    pub fn to_json_string(&self) -> Result {
+        serde_json::to_string_pretty(self).map_err(|e| GameError::json("instance_config", e))
+    }
+}
+
+/// 读实例清单（文件缺失 = 空列表，不算错误）。
+///
+/// # Errors
+///
+/// 读盘失败、非 UTF-8 或 JSON 非法。
+pub fn read_profiles(layout: &LauncherLayout) -> Result {
+    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 {
+    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, 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/.json`（实例 id 白名单校验在布局层，挡掉 `../` 穿越）。
+///
+/// # Errors
+///
+/// 实例 id 不合法时返回 [`GameError::Io`]（`PlatformError` 没有对应变体）。
+fn instance_config_path(layout: &LauncherLayout, id: &str) -> Result {
+    layout
+        .instance_config(id)
+        .map_err(|error| GameError::io(layout.config(), std::io::Error::other(error)))
+}
diff --git a/crates/core/src/game/install/instance/register.rs b/crates/core/src/game/install/instance/register.rs
new file mode 100644
index 0000000..8ed89e7
--- /dev/null
+++ b/crates/core/src/game/install/instance/register.rs
@@ -0,0 +1,150 @@
+//! 实例登记：把「用户点了一下导入/安装」变成 `profiles.json` + `config/instances/.json`。
+//!
+//! 从 `install/instance.rs` 搬出来只为守 400 行硬线（M221 的 `register_with` 让那边到 430 行）；
+//! 搬动是纯挪，唯一新增的是 [`InstanceSettings`] 与 [`register_with`]（登记时一并定隔离档/运行目录）。
+//!
+//! # 幂等
+//!
+//! 同一 `version_id` + 同一展示名重复登记：复用已有档案（`created = false`），不产生第二个实例、
+//! 不改已有实例的 id（id 一旦写进档案就是稳定的）。
+//!
+//! # 写盘顺序（M221）
+//!
+//! **先写实例设置、后写档案**。中断时留下的是「没有档案的孤立设置文件」——不可见、下次登记同一 id
+//! 会覆盖；反过来（先档案后设置）会留下一个按全局档启动的实例，而全局缺省是 `isolated`，
+//! 那会把 `mods/saves/config` 造进 `versions//`（登记别人的版本时那正是别人的目录）。
+
+use std::path::PathBuf;
+
+use crate::game::error::GameError;
+use crate::game::profiles::InstanceProfile;
+use crate::platform::layout::LauncherLayout;
+
+use super::{
+    instance_config_path, read_profiles, write_instance_config, write_profiles, InstanceConfig,
+    Isolation,
+};
+
+/// 一次登记的结果。
+#[derive(Debug, Clone)]
+pub struct Registration {
+    /// 档案（新建或复用）。
+    pub profile: InstanceProfile,
+    /// 每实例设置文件路径。
+    pub config_path: PathBuf,
+    /// 是否新建（`false` = 已有同版本同名的实例，直接复用）。
+    pub created: bool,
+}
+
+/// 登记时一并落进 `config/instances/.json` 的初始设置。
+///
+/// 为什么要有它：登记与「运行目录怎么定」原本是两件事，于是调用方只能先 `register` 再补写设置
+/// ——中间那段时间实例是 `inherit`（跟随全局 `isolated`）。把选择前移到登记这一步，就没有那个窗口。
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct InstanceSettings {
+    /// 隔离档；`None` = 跟随全局（不落盘）。
+    pub isolation: Option,
+    /// 自定义运行目录（仅 `custom` 档需要）。
+    pub game_dir: Option,
+}
+
+impl InstanceSettings {
+    /// 跟随全局（= 未引入 [`InstanceSettings`] 前的历史行为，不落任何设置键）。
+    #[must_use]
+    pub fn inherit() -> Self {
+        Self::default()
+    }
+
+    /// 是否什么都没选。
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.isolation.is_none() && self.game_dir.is_none()
+    }
+}
+
+/// 登记一个实例（幂等，跟随全局隔离档）。
+///
+/// # Errors
+///
+/// 读/写 `profiles.json`、实例 id 不合法、原子写失败。
+pub fn register(
+    layout: &LauncherLayout,
+    name: &str,
+    version_id: &str,
+    created_at: Option<&str>,
+) -> Result {
+    register_with(
+        layout,
+        name,
+        version_id,
+        created_at,
+        &InstanceSettings::inherit(),
+    )
+}
+
+/// 同 [`register`]，但把隔离档与运行目录**一并**写进新建实例的设置文件。
+///
+/// 复用已有档案（同版本 + 同名）时 `settings` 只在「设置文件缺失、需要补建」时生效——
+/// 已有设置文件绝不改写（那是用户的显式选择，登记不该覆盖它）。
+///
+/// # Errors
+///
+/// 同 [`register`]。
+pub fn register_with(
+    layout: &LauncherLayout,
+    name: &str,
+    version_id: &str,
+    created_at: Option<&str>,
+    settings: &InstanceSettings,
+) -> Result {
+    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() {
+            let mut config = InstanceConfig::new(profile.id.as_str(), version_id);
+            apply_settings(&mut config, settings);
+            write_instance_config(layout, &config)?;
+        }
+        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();
+    let mut config = InstanceConfig::new(id, version_id);
+    apply_settings(&mut config, settings);
+    let config_path = write_instance_config(layout, &config)?;
+
+    profiles.upsert(profile.clone());
+    if let Err(error) = write_profiles(layout, &profiles) {
+        // 档案没落盘 ⇒ 撤掉刚写的设置文件，不留半登记状态。
+        let _ = std::fs::remove_file(&config_path);
+        return Err(error);
+    }
+    Ok(Registration {
+        profile,
+        config_path,
+        created: true,
+    })
+}
+
+/// 把登记时的初始设置贴到实例设置上（只动这两个键，其余保持稀疏缺省）。
+fn apply_settings(config: &mut InstanceConfig, settings: &InstanceSettings) {
+    if let Some(isolation) = settings.isolation {
+        config.isolation = Some(isolation);
+    }
+    if settings.game_dir.is_some() {
+        config.game_dir = settings.game_dir.clone();
+    }
+}
diff --git a/crates/core/src/game/install/libraries.rs b/crates/core/src/game/install/libraries.rs
new file mode 100644
index 0000000..ea92fce
--- /dev/null
+++ b/crates/core/src/game/install/libraries.rs
@@ -0,0 +1,364 @@
+//! 依赖库展开：主构件 + 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//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;
+
+use arm64_natives::{arm64_native_url, linux_arm64_native_entry, LINUX_ARM64_CLASSIFIER};
+
+mod arm64_natives;
+
+/// 没写 `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, Vec) {
+    let mut files = Vec::new();
+    let mut warnings = Vec::new();
+
+    for library in libraries {
+        if !library.applies(environment) {
+            continue;
+        }
+        // 现代清单把 natives 作为独立库条目（`org.lwjgl:lwjgl:3.3.2:natives-linux`），
+        // 不是 `natives` 表。Linux arm64 上改写坐标并兜底到 Maven 镜像。
+        if let Some(rewritten) = linux_arm64_native_entry(library, environment) {
+            files.push(PlanFile {
+                role: FileRole::Native,
+                name: rewritten.name,
+                url: rewritten.url,
+                sha1: None,
+                size: None,
+                dest: layout.libraries_dir().join(&rewritten.relative),
+                resource: ResourceKind::Library,
+            });
+            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 Ok(native_relative) = library.native_relative_path(&classifier) else {
+            warnings.push(format!("{} 的 natives 路径推导失败，已跳过", library.name));
+            continue;
+        };
+        let dest = layout.libraries_dir().join(&native_relative);
+        // Linux arm64：Mojang 清单没有 arm64 分类器，兜底到 Maven 镜像（见常量注释）。
+        let arm64_fallback = classifier == LINUX_ARM64_CLASSIFIER;
+        let (url, sha1, size) = match library.native_artifact(&classifier) {
+            Some(artifact) if artifact.has_url() => (
+                artifact.url.clone().unwrap_or_default(),
+                artifact.sha1.clone(),
+                artifact.size,
+            ),
+            _ if arm64_fallback => (arm64_native_url(&native_relative), None, None),
+            Some(_) => {
+                warnings.push(format!(
+                    "{} 的 natives 构件 {classifier} 没有下载地址，已跳过",
+                    library.name
+                ));
+                continue;
+            }
+            None => {
+                warnings.push(format!(
+                    "{} 的 natives 分类器 {classifier} 没有下载信息，已跳过",
+                    library.name
+                ));
+                continue;
+            }
+        };
+        files.push(PlanFile {
+            role: FileRole::Native,
+            name: format!("{}:{classifier}", library.name),
+            url,
+            sha1,
+            size,
+            dest,
+            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"));
+    }
+
+    #[test]
+    fn linux_arm64_lwjgl3_natives_fall_back_to_maven_mirror() {
+        // Mojang 的清单只有 `natives-linux`（x86_64）且没有 arm64 分类器下载信息；
+        // Linux arm64 要改写成 `natives-linux-arm64` 并兜底到 Maven 镜像。
+        let library = library_with_artifact(
+            r#"{"name":"org.lwjgl:lwjgl:3.3.2","natives":{"linux":"natives-linux"}}"#,
+        );
+        let env = Environment {
+            os: "linux".to_string(),
+            os_version: String::new(),
+            arch: "arm64".to_string(),
+            ..environment()
+        };
+        let layout = GameLayout::new("/g/.minecraft");
+        let (files, warnings) = plan(&layout, "1.20.4", &[library], &env);
+        assert!(warnings.is_empty(), "不该有告警：{warnings:?}");
+        assert_eq!(files.len(), 1);
+        assert_eq!(files[0].name, "org.lwjgl:lwjgl:3.3.2:natives-linux-arm64");
+        assert_eq!(
+            files[0].url,
+            "https://maven.aliyun.com/repository/public/org/lwjgl/lwjgl/3.3.2/lwjgl-3.3.2-natives-linux-arm64.jar"
+        );
+        assert!(
+            files[0].sha1.is_none(),
+            "镜像兜底没有 sha1，只能靠大小/存在性"
+        );
+    }
+
+    #[test]
+    fn modern_lwjgl_native_entry_is_rewritten_to_arm64_maven() {
+        // 1.20.x 的清单把 natives 作为独立条目，分类器写在 name 里。
+        let library = library_with_artifact(
+            r#"{"name":"org.lwjgl:lwjgl:3.3.2:natives-linux",
+                "rules":[{"action":"allow","os":{"name":"linux"}}],
+                "downloads":{"artifact":{"path":"org/lwjgl/lwjgl/3.3.2/lwjgl-3.3.2-natives-linux.jar","url":"https://libraries.minecraft.net/x.jar","sha1":"aa"}}}"#,
+        );
+        let env = Environment {
+            os: "linux".to_string(),
+            os_version: String::new(),
+            arch: "arm64".to_string(),
+            ..environment()
+        };
+        let layout = GameLayout::new("/g/.minecraft");
+        let (files, warnings) = plan(&layout, "1.20.4", &[library], &env);
+        assert!(warnings.is_empty(), "不该有告警：{warnings:?}");
+        assert_eq!(files.len(), 1);
+        assert_eq!(files[0].role.as_str(), "native");
+        assert_eq!(files[0].name, "org.lwjgl:lwjgl:3.3.2:natives-linux-arm64");
+        assert_eq!(
+            files[0].url,
+            "https://maven.aliyun.com/repository/public/org/lwjgl/lwjgl/3.3.2/lwjgl-3.3.2-natives-linux-arm64.jar"
+        );
+        assert!(files[0]
+            .dest
+            .ends_with("libraries/org/lwjgl/lwjgl/3.3.2/lwjgl-3.3.2-natives-linux-arm64.jar"));
+    }
+
+    #[test]
+    fn linux_x86_64_keeps_the_manifest_classifier() {
+        let library = library_with_artifact(
+            r#"{"name":"org.lwjgl:lwjgl:3.3.2","natives":{"linux":"natives-linux"}}"#,
+        );
+        let env = Environment {
+            os: "linux".to_string(),
+            os_version: String::new(),
+            arch: "x86_64".to_string(),
+            ..environment()
+        };
+        let layout = GameLayout::new("/g/.minecraft");
+        let (files, warnings) = plan(&layout, "1.20.4", &[library], &env);
+        assert!(files.is_empty(), "x86_64 没有清单下载信息，不该凭空拼 URL");
+        assert!(
+            warnings.iter().any(|w| w.contains("natives-linux")),
+            "{warnings:?}"
+        );
+    }
+}
diff --git a/crates/core/src/game/install/libraries/arm64_natives.rs b/crates/core/src/game/install/libraries/arm64_natives.rs
new file mode 100644
index 0000000..fc0c7f9
--- /dev/null
+++ b/crates/core/src/game/install/libraries/arm64_natives.rs
@@ -0,0 +1,72 @@
+//! Linux arm64 的 natives 改写与下载兜底。
+//!
+//! 两件事实拼出来的特例：
+//! 1. Mojang 清单里 LWJGL3 的 natives 只写 `natives-linux`（x86_64 的 `.so`）；
+//!    直接用它，在 aarch64 JVM 里加载必失败。
+//! 2. 同一个 Maven 坐标确实有 `natives-linux-arm64` 分类器，但 `libraries.minecraft.net`
+//!    对它一律 404（实测 3.3.2 的 lwjgl/glfw/opengl/stb/tinyfd/openal），Maven Central 与
+//!    阿里云镜像有。
+//!
+//! 所以 Linux arm64 上：分类器改写（`Library::native_classifier` /
+//! `Library::linux_arm64_native_name`）+ 地址兜底到镜像。**只在 linux + arm64 生效**，
+//! x86_64 / Windows / macOS 的地址一个字节不变。用例仍在 `libraries.rs` 的 tests 里
+//! （它们从 `plan()` 的出口断言，不直接调这里的私有步骤）。
+//!
+//! 从 `libraries.rs` 拆出来是为了守住 400 行红线（`guards.yml` 的 `file-size`）。
+
+use std::path::{Path, PathBuf};
+
+use crate::game::arguments::Environment;
+use crate::game::library::Library;
+
+/// Linux arm64 的 natives 兜底仓库：Mojang 的 `libraries.minecraft.net` 对
+/// `natives-linux-arm64` 一律 404（实测 3.3.2 的 lwjgl/glfw/opengl/stb/tinyfd/openal），
+/// 同一坐标在 Maven Central / 阿里云镜像有。
+pub const LINUX_ARM64_NATIVES_BASE: &str = "https://maven.aliyun.com/repository/public/";
+
+/// Linux arm64 的 natives 分类器（见 `Library::native_classifier`）。
+pub const LINUX_ARM64_CLASSIFIER: &str = "natives-linux-arm64";
+
+/// 现代清单里 LWJGL3 natives 条目的改写结果。
+pub(super) struct Arm64Native {
+    pub(super) name: String,
+    pub(super) relative: PathBuf,
+    pub(super) url: String,
+}
+
+/// Linux arm64：把 `org.lwjgl:::natives-linux` 改写成 arm64。
+pub(super) fn linux_arm64_native_entry(
+    library: &Library,
+    env: &Environment,
+) -> Option {
+    let name = library.linux_arm64_native_name(env)?;
+    let base = name.strip_suffix(":natives-linux-arm64")?;
+    let mut parts = base.split(':');
+    let group = parts.next()?;
+    let artifact = parts.next()?;
+    let version = parts.next()?;
+    if parts.next().is_some() {
+        return None;
+    }
+    let relative = PathBuf::from(format!(
+        "{}/{artifact}/{version}/{artifact}-{version}-natives-linux-arm64.jar",
+        group.replace('.', "/")
+    ));
+    let url = format!(
+        "{LINUX_ARM64_NATIVES_BASE}{}",
+        relative.to_string_lossy().replace('\\', "/")
+    );
+    Some(Arm64Native {
+        name,
+        relative,
+        url,
+    })
+}
+
+/// arm64 natives 的兜底 URL（按相对路径拼镜像基址）。
+pub(super) fn arm64_native_url(relative: &Path) -> String {
+    format!(
+        "{LINUX_ARM64_NATIVES_BASE}{}",
+        relative.to_string_lossy().replace('\\', "/")
+    )
+}
diff --git a/crates/core/src/game/install/mod.rs b/crates/core/src/game/install/mod.rs
new file mode 100644
index 0000000..b045e5a
--- /dev/null
+++ b/crates/core/src/game/install/mod.rs
@@ -0,0 +1,196 @@
+//! 安装层：版本链 → 下载计划 → 分区落盘 → 实例登记（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/.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 pack_dir;
+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, ManifestWrite, 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,
+}
+
+impl InstallError {
+    /// 构造。
+    #[must_use]
+    pub fn new(kind: InstallErrorKind, message: impl Into) -> 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 ` 前先确认版本 id（如 26.3 / 1.21.4）；快照版本 id 形如 24w14a")
+    }
+
+    /// 补一句提示。
+    #[must_use]
+    pub fn with_hint(mut self, hint: impl Into) -> 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 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 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 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/pack_dir.rs b/crates/core/src/game/install/pack_dir.rs
new file mode 100644
index 0000000..1d1aa42
--- /dev/null
+++ b/crates/core/src/game/install/pack_dir.rs
@@ -0,0 +1,316 @@
+//! 整合包导入的**落点派生**（M216 ②）：`/instances/<实例目录名>` + 名字归一化。
+//!
+//! 为什么在 core：`ull pack import` 与 GUI 导入页必须落到**同一个**目录、用**同一份**名字
+//! 归一化。M215 survey 的债②就是两边不同源——CLI 缺省指向共享 `.minecraft` 根
+//! （`cli/commands/pack.rs`），GUI 指向 `/instances/`
+//! （`presenter/host/addon/pack/import.rs::target_of`）。归一化留在 presenter 就只有 GUI 能看，
+//! CLI 复制一份就是第三处真相源；放这里，两侧各一行委托。
+//!
+//! 归 GUI 侧独有的部分**不在**这里：选中的实例 → 其运行目录（要读隔离档与实例设置，
+//! `pack.rs::instance_root`），那是「用已有实例」而不是「建新实例目录」。
+
+use std::path::{Path, PathBuf};
+
+use super::instance::{self, InstanceConfig, Isolation};
+use crate::game::error::GameError;
+use crate::platform::layout::LauncherLayout;
+
+/// 包文件名 → 实例候选名（`Better MC.mrpack` → `Better MC`）。
+///
+/// 取不到 `file_stem`（路径以 `..` 结尾之类）时给 `imported-pack`：宁可名字难看，
+/// 也不要一个空目录名。
+#[must_use]
+pub 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 化 + 必要时补一段内容哈希。
+///
+/// 判据：名字里**只含** ASCII 字母数字、空格、`-`、`_` 时保持原样（空格折成 `-`，
+/// `Better MC` → `Better-MC`）；**一旦折过别的字符**（中文、`.`、括号……）就补 `-`，
+/// 用原名的哈希保住区分度——否则「我的整合包」「另一个整合包」都会得到 `pack`，
+/// 第二个中文名导入直接撞「目录已存在」。
+#[must_use]
+pub fn instance_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))
+    }
+}
+
+/// 新实例的内容目录：`/instances/<实例目录名>`（**只算路径，不建目录**）。
+///
+/// 调用方自己决定要不要建（CLI 的预检与 GUI 的 `prepare_target` 都要先看路径）。
+#[must_use]
+pub fn instance_dir(layout: &LauncherLayout, name: &str) -> PathBuf {
+    layout
+        .data()
+        .join("instances")
+        .join(instance_dir_name(name))
+}
+
+/// 导入一次的**落点与登记名**：显式目标优先，否则 `/instances/<实例目录名>`。
+///
+/// 名字 = `name`（去空格，空串不算）或包文件名；**目录名与登记名用同一个值**（GUI 同）。
+/// `Err` = 缺省目录已存在且非空的人读原因：空目录（上次失败的残留）可以复用，否则一次
+/// 失败之后永远重试不了；非空也不猜「你想合并进已有实例」，让用户显式给目标。
+///
+/// GUI 导入页（`import.rs::target_of`）是同一判据的另一份实现，外加一条「用已有实例」分支
+/// （要读隔离档与实例设置）——那条分支只有 GUI 有，所以落点判定留了这道公共函数给 CLI。
+///
+/// # Errors
+///
+/// 缺省目录非空时返回原因字符串。
+pub fn import_target(
+    layout: &LauncherLayout,
+    pack: &Path,
+    target: Option<&Path>,
+    name: Option<&str>,
+) -> Result<(PathBuf, String), String> {
+    let name = name
+        .map(str::trim)
+        .filter(|name| !name.is_empty())
+        .map(str::to_string)
+        .unwrap_or_else(|| pack_stem(pack));
+    let Some(target) = target else {
+        let dir = instance_dir(layout, &name);
+        let occupied = std::fs::read_dir(&dir).is_ok_and(|mut entries| entries.next().is_some());
+        if occupied {
+            return Err(format!("目标实例目录已存在且非空：{}", dir.display()));
+        }
+        return Ok((dir, name));
+    };
+    Ok((target.to_path_buf(), name))
+}
+
+/// 把「导入建出来的实例」绑到它的内容目录（`isolation=custom` + `game_dir`）。
+///
+/// # 为什么必须绑
+///
+/// 运行目录不是「导入目录」，而是从 `config/instances/.json` 的 `isolation` 派生的
+/// （[`derive_game_dir`](crate::game::isolation::derive_game_dir)）：缺省档
+/// `instances.mode=isolated` 给成 `/versions/`，`shared` 给成游戏根。
+/// 导入目标 `/instances/<名>` **不在这条链上** ⇒ 不绑的话「导入成功」而那批
+/// mods/config 永远不会被那条实例的启动用到（M113 起 GUI 就有这个洞）。
+///
+/// # 绑成什么、不绑成什么
+///
+/// - 运行目录 = `dir`：`saves/` `mods/` `logs/` `config/` 落在这里（与别的启动器隔离）；
+/// - **`versions/` `libraries/` `assets/` 仍按 D20 恒共享**在游戏根 —— 不是「完全隔离」，
+///   版本本体只装一份，别人 `.minecraft` 里已下好的库也照旧复用。
+///
+/// # 回滚
+///
+/// 把 `config/instances/.json` 的 `isolation` 删掉（或写成 `"inherit"`）即回到「跟随全局
+/// 档」；`gameDir` 随之失效。也可以整份删掉这一份实例设置文件（`register` 会重新补最小那份）。
+/// **不会**搬动任何已落盘的内容。
+///
+/// # Errors
+///
+/// 读/写实例设置失败（JSON 坏、id 不合法、原子写失败）。
+pub fn bind_instance_dir(
+    layout: &LauncherLayout,
+    instance_id: &str,
+    version_id: &str,
+    dir: &Path,
+) -> Result<(), GameError> {
+    let mut config = instance::read_instance_config(layout, instance_id)?
+        .unwrap_or_else(|| InstanceConfig::new(instance_id, version_id));
+    config.isolation = Some(Isolation::Custom);
+    config.game_dir = Some(dir.to_path_buf());
+    instance::write_instance_config(layout, &config)?;
+    Ok(())
+}
+
+/// 导入收尾：把「我们新建出来的实例」绑到它的内容目录，返回一句给人读的结论。
+///
+/// 返回 `None` = 不需要绑；`Some(Ok(说明))` = 已绑；`Some(Err(说明))` = 绑失败（档案在、内容在，
+/// 只是运行目录没指过来——调用方**别**把它当整次导入失败，但要让人看见）。
+///
+/// 判据（CLI 与 GUI 共用一份，别自己再写一遍）：
+/// - `auto_bound == false` ⇒ 不绑（用户显式给了目标目录 / `--no-register`：那目录可能是别人的
+///   运行目录，也可能被用户自己指过）；
+/// - 没登记、或**复用了已有档案**（`registered.created == false`）⇒ 不绑；
+/// - 其余 ⇒ [`bind_instance_dir`]。
+///
+/// 参数直接吃 `addon::import::ImportReport`：`addon` 早就在调 `game::install::register`，
+/// 两者同属 core 内部；再投影一层 `struct` 只会让两侧各多写六行构造。
+#[must_use]
+pub fn bind_created_instance(
+    layout: &LauncherLayout,
+    target: &Path,
+    auto_bound: bool,
+    report: &crate::addon::import::ImportReport,
+) -> Option> {
+    if !auto_bound {
+        return None;
+    }
+    let registered = report.registered.as_ref().filter(|item| item.created)?;
+    Some(
+        match bind_instance_dir(layout, ®istered.id, ®istered.version_id, target) {
+            Ok(()) => Ok(format!(
+                "运行目录已指向 {}（实例 {}）",
+                target.display(),
+                registered.name
+            )),
+            // 内容与档案都已就位，只是目录没指过来 ⇒ 不把整次导入判失败，但必须说出来。
+            Err(error) => Err(format!(
+                "实例已登记但没能绑到导入目录（{error}）：启动前请把该实例的运行目录指到 {}",
+                target.display()
+            )),
+        },
+    )
+}
+
+/// 目录/文件名用的 slug（只留 ASCII 字母数字与 `-` / `_`，其余折成 `-`）。
+#[must_use]
+pub 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
+    }
+}
+
+/// 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)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// 抓得住：目录名归一化的四条既有判据（ASCII 保真、空格折 `-`、中文补哈希、点号补哈希），
+    /// 以及 `/instances/<名>` 这个落点本身。
+    /// 抓不住：GUI 是否真的改调这个函数（那条由 presenter 侧的既有用例继续钉着）。
+    #[test]
+    fn the_instance_dir_is_derived_the_same_way_the_gui_used_to() {
+        assert_eq!(
+            pack_stem(Path::new("C:/packs/Better MC.mrpack")),
+            "Better MC"
+        );
+        assert_eq!(pack_stem(Path::new("packs/unnamed")), "unnamed");
+        assert_eq!(instance_dir_name("Better MC"), "Better-MC");
+        assert_eq!(instance_dir_name("Better-MC"), "Better-MC");
+        assert_eq!(instance_dir_name("pack"), "pack");
+        // 折过字符 ⇒ 补哈希保住区分度（两个中文名不许塌成同一个目录）。
+        let a = instance_dir_name("我的整合包");
+        let b = instance_dir_name("另一个整合包");
+        assert_ne!(a, b);
+        assert!(
+            a.starts_with("pack-") && a.len() == "pack-".len() + 8,
+            "{a}"
+        );
+        assert!(instance_dir_name("Survival 1.20.1").starts_with("Survival-1-20-1-"));
+        // 落点：`/instances/<目录名>`，不是共享的 `.minecraft` 根。
+        let layout = LauncherLayout::new(PathBuf::from("/data/.ULL"));
+        assert_eq!(
+            instance_dir(&layout, "Better MC"),
+            PathBuf::from("/data/.ULL/data/instances/Better-MC")
+        );
+    }
+
+    /// **M216 ②**：缺省落点与 GUI 同源（`/instances/<名>`），**不是共享的 `.minecraft` 根**；
+    /// 显式目标照给、空目录可复用、非空才报错。
+    ///
+    /// 抓得住：缺省改回 `game_home` 根（第一条断言会变成 `…/ .minecraft`）、目录名不归一化、
+    /// 非空目录不复检、登记名与目录名分叉。抓不住：CLI/GUI 是否真调用本函数（编译期无约束，
+    /// 靠两侧各自的调用点用例），以及真实 `Ctx::layout()` / `HostEnv` 的取值。
+    #[test]
+    fn the_default_target_is_an_instance_dir_not_the_shared_minecraft_root() {
+        let root = std::env::temp_dir().join(format!("ull-m216-pack-{}", std::process::id()));
+        let layout = LauncherLayout::new(root.join(".ULL"));
+        let pack = Path::new("C:/packs/Better MC.mrpack");
+        let target =
+            |target: Option<&Path>, name: Option<&str>| import_target(&layout, pack, target, name);
+
+        let (dir, name) = target(None, None).expect("缺省可用");
+        assert_eq!(dir, root.join(".ULL/data/instances/Better-MC"));
+        assert!(
+            !dir.starts_with(root.join(".minecraft")),
+            "不许落到共享游戏根"
+        );
+        assert_eq!(name, "Better MC", "登记名与目录名同源");
+
+        std::fs::create_dir_all(&dir).expect("建目录");
+        assert_eq!(
+            target(None, None).expect("空目录可复用").0,
+            dir,
+            "空目录可复用"
+        );
+        std::fs::write(dir.join("mmc-pack.json"), b"{}").expect("写文件");
+        let reason = target(None, None).expect_err("非空要报错");
+        assert!(reason.contains("已存在且非空"), "{reason}");
+
+        let explicit = root.join("my-target");
+        let (dir, name) = target(Some(&explicit), Some("x")).expect("显式目标照给");
+        assert_eq!((dir, name.as_str()), (explicit, "x"));
+        std::fs::remove_dir_all(&root).ok();
+    }
+
+    /// **§5 正向**：导入建出来的实例必须绑到内容目录，否则「导入成功」而内容永远不会被启动用到。
+    ///
+    /// 抓得住：`bind_instance_dir` 没写 `isolation=custom` / `game_dir` 落空 / 写错了实例（读回来
+    /// 仍是 `None`）。抓不住：`derive_game_dir` 真的把运行目录算成那个目录——那条由
+    /// `isolation.rs` 的既有用例钉住，这里不重算（tower 要求不动 `derive_game_dir`）。
+    #[test]
+    fn binding_an_imported_instance_points_it_at_the_import_dir() {
+        let root = std::env::temp_dir().join(format!("ull216-bind-{}", std::process::id()));
+        let layout = LauncherLayout::new(root.join(".ULL"));
+        let registration =
+            crate::game::install::instance::register(&layout, "pack", "1.20.1", None)
+                .expect("登记");
+        let id = registration.profile.id.as_str().to_string();
+        let dir = instance_dir(&layout, "pack");
+
+        bind_instance_dir(&layout, &id, "1.20.1", &dir).expect("绑定");
+        let config = crate::game::install::instance::read_instance_config(&layout, &id)
+            .expect("读设置")
+            .expect("有设置文件");
+        assert_eq!(config.isolation, Some(Isolation::Custom));
+        assert_eq!(config.game_dir.as_deref(), Some(dir.as_path()));
+        std::fs::remove_dir_all(&root).ok();
+    }
+
+    /// **§5 反向**：没走绑定那条路的实例不许自己冒出 `custom`（否则上一条抓不住东西）。
+    #[test]
+    fn a_freshly_registered_instance_still_inherits_the_global_mode() {
+        let root = std::env::temp_dir().join(format!("ull216-unbound-{}", std::process::id()));
+        let layout = LauncherLayout::new(root.join(".ULL"));
+        let registration =
+            crate::game::install::instance::register(&layout, "plain", "1.20.1", None)
+                .expect("登记");
+        let config = crate::game::install::instance::read_instance_config(
+            &layout,
+            registration.profile.id.as_str(),
+        )
+        .expect("读设置")
+        .expect("有设置文件");
+        assert_eq!(config.isolation, None, "缺省必须跟随全局档");
+        assert_eq!(config.game_dir, None);
+        std::fs::remove_dir_all(&root).ok();
+    }
+}
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//.jar`。
+    ClientJar,
+    /// 共享库 `libraries/...`。
+    Library,
+    /// natives 分类器构件（也进 `libraries/`，启动期解压）。
+    Native,
+    /// 资源索引 `assets/indexes/.json`。
+    AssetIndex,
+    /// 资源对象 `assets/objects//`。
+    Asset,
+    /// 日志配置 `assets/log_configs/`。
+    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,
+    /// 期望字节数。
+    pub size: Option,
+    /// 最终落盘路径。
+    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,
+}
+
+/// 一次安装的完整计划。
+#[derive(Debug, Clone)]
+pub struct InstallPlan {
+    /// 目标版本 id（`versions//`）。
+    pub version_id: String,
+    /// 实际提供 jar 的版本 id（继承链上可能是父版本）。
+    pub jar_id: String,
+    /// 游戏根目录（恒共享层的根）。
+    pub game_root: PathBuf,
+    /// 版本清单落盘路径 `versions//.json`。
+    pub version_json_path: PathBuf,
+    /// 待下载文件（按 dest 去重、按角色排序）。
+    pub files: Vec,
+    /// 已解析的扁平清单（落盘时写进 `versions//.json`）。
+    pub version_json: VersionJson,
+    /// 规划期已取到内容的文件（见 [`Prefetched`]）。
+    pub prefetched: Vec,
+    /// 人读告警（缺哪类资源一律如实告知，不静默降级）。
+    pub warnings: Vec,
+}
+
+/// [`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 {
+        let layout = input.layout;
+        let version_id = input.version_id;
+        let resolved = input.resolved;
+        let mut files: Vec = Vec::new();
+        let mut warnings: Vec = 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) {
+        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 {
+        let mut out: BTreeMap = 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) -> Vec {
+    let mut by_dest: BTreeMap = 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 = 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 = 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 {
+        self.files.iter().map(PlanFile::to_json).collect()
+    }
+
+    /// 每个角色取第一个文件，[`DownloadEngine::plan`] 给出候选源顺序（"源选择"）。
+    ///
+    /// 只取每类的**首个**文件做样本：3000 个资源对象的候选源是一样的，
+    /// 逐文件列源选择既没用也没法读。
+    #[must_use]
+    pub fn source_samples(&self, engine: &DownloadEngine, now_ms: u64) -> Vec {
+        let mut seen: BTreeSet = BTreeSet::new();
+        let mut samples = Vec::new();
+        for file in &self.files {
+            if !seen.insert(file.role) {
+                continue;
+            }
+            let candidates: Vec = 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..4431f6c
--- /dev/null
+++ b/crates/core/src/game/install/report.rs
@@ -0,0 +1,197 @@
+//! 安装报告与进度回调的形状（M105 从 `execute.rs` 搬出，守 400 行硬线）。
+//!
+//! 纯数据 + 纯方法：`execute.rs`（执行）与 CLI（汇总打印）都读它，谁也不改它。
+//! 搬移是**逐字**的，只有 `use` 断了回来（原来靠 `execute.rs` 的 import 活着）。
+
+use std::path::{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,
+    /// 失败详情。
+    pub failure: Option,
+}
+
+impl FileOutcome {
+    /// 是否失败。
+    #[must_use]
+    pub fn failed(&self) -> bool {
+        self.status == FileStatus::Failed
+    }
+}
+
+/// 进度回调：每完成一个文件调用一次（可跨线程，由执行器持有 `Arc`）。
+///
+/// CLI 用它往 stderr 打实时进度；GUI 侧直接消费 `ProgressEvent` 事件流即可，不必用这个。
+pub type ProgressSink = Arc;
+
+/// 版本清单（`versions//.json`）这一处落盘的结局（**M216 ③**）。
+///
+/// 这一份清单是「版本已安装」的判据，也是**别人的 `.minecraft` 里同一个文件**：装在同一个
+/// 上级目录下的另一个启动器（官方 / PCL / HMCL）铺的就是它。M215 survey 判为债③：老实现
+/// `write_atomic` 无条件 rename 覆盖，不检测、不备份、不提示。现在三种结局都如实记下来。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ManifestWrite {
+    /// 目标原本没有清单：正常新建。
+    Fresh,
+    /// 目标已有**完全相同**的内容：**一个字节都没写**（别人的 mtime / ACL 保持原样）。
+    ///
+    /// 重装同版本走这一档：正常操作，不该被当成冲突，也不该留一堆备份。
+    Identical,
+    /// 目标已有**不同**的内容：旧清单先复制到 `backup`，再写新的。
+    Replaced {
+        /// 旧清单的备份路径（`.ullbak-`，与整合包导入同一命名习惯）。
+        backup: PathBuf,
+    },
+}
+
+impl ManifestWrite {
+    /// 稳定字符串 id（日志 / `--json` 用）。
+    #[must_use]
+    pub const fn as_str(&self) -> &'static str {
+        match self {
+            Self::Fresh => "fresh",
+            Self::Identical => "identical",
+            Self::Replaced { .. } => "replaced",
+        }
+    }
+
+    /// 备份路径（只有 [`Self::Replaced`] 有）。
+    #[must_use]
+    pub fn backup(&self) -> Option<&Path> {
+        match self {
+            Self::Replaced { backup } => Some(backup),
+            Self::Fresh | Self::Identical => None,
+        }
+    }
+}
+
+/// 一次安装的执行结果。
+#[derive(Debug, Clone)]
+pub struct InstallReport {
+    /// 逐文件结果（顺序不保证，按角色/大小汇总即可）。
+    pub files: Vec,
+    /// 版本清单落盘路径；`None` = 有文件失败，故意没写（见 `execute` 的说明）。
+    pub version_json: Option,
+    /// 版本清单这一处怎么落的盘；`None` = 本次根本没写清单（有失败 / 不写清单的那条路径）。
+    pub manifest: Option,
+    /// 计划阶段带来的告警（缺件降级说明）+ 运行期告警（清单被替换等）。
+    pub warnings: Vec,
+}
+
+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 {
+        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) -> 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 {
+        let (manifest, _) = self.manifest(false).await?;
+        let root = self.load_one(version_id, &manifest).await?;
+
+        let mut table: BTreeMap = BTreeMap::new();
+        table.insert(version_id.to_string(), root.clone());
+        let mut visited: BTreeSet = 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/.json`，不重复下载。
+    ///
+    /// # Errors
+    ///
+    /// 索引没有下载地址、网络失败、sha1 不符或 JSON 非法。
+    pub async fn asset_index(
+        &self,
+        reference: &AssetIndexRef,
+    ) -> Result<(AssetIndex, Vec), 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 {
+        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//.json` 兜底。
+    async fn load_one(
+        &self,
+        id: &str,
+        manifest: &VersionList,
+    ) -> Result {
+        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 {
+        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, 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//.json`）；不存在返回 `Ok(None)`。
+    fn read_local(&self, id: &str) -> Result, 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 {
+    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..28474c1
--- /dev/null
+++ b/crates/core/src/game/install/tests/execute.rs
@@ -0,0 +1,398 @@
+//! 落盘执行：跳过判定（三级）、幂等重装、预取元数据落盘、失败分类聚合。
+//!
+//! 全部用例都**已把文件放好**或**只做纯函数判定**，因此不发网络请求。
+
+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) {
+    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 {
+        manifest: None,
+        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(®istration.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/.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/manifest_write.rs b/crates/core/src/game/install/tests/manifest_write.rs
new file mode 100644
index 0000000..194f698
--- /dev/null
+++ b/crates/core/src/game/install/tests/manifest_write.rs
@@ -0,0 +1,189 @@
+//! M216 ③：装同一版本时**不再静默覆盖** `versions//.json`。
+//!
+//! 三条判据各一条用例（都走真的 `execute`，所以报告字段是端到端验过的，不是只测私有函数）：
+//!
+//! | 盘上状态 | 期望 |
+//! |---|---|
+//! | 没有清单 | `ManifestWrite::Fresh`，无备份、无告警 |
+//! | 有、且内容**逐字节相同** | `Identical`，不写、不备份、不告警（重装同版本是正常操作）|
+//! | 有、且内容**不同** | `Replaced{backup}`，旧的那份进 `.ullbak-`，告警里点名 |
+//!
+//! 全部零网络：客户端 jar 事先按 sha1 放好，跳过判定第一级直接命中。
+
+use std::path::{Path, PathBuf};
+use std::sync::Arc;
+
+use crate::download::verify;
+use crate::download::{
+    ContentCache, DownloadEngine, EngineConfig, HashAlgo, HealthRegistry, MirrorTable,
+    RegionProfile,
+};
+use crate::game::arguments::Environment;
+use crate::game::install::execute::execute;
+use crate::game::install::plan::{InstallPlan, PlanInput};
+use crate::game::install::{InstallReport, ManifestWrite};
+use crate::game::layout::GameLayout;
+use crate::game::manifest::VersionJson;
+
+fn temp_root(tag: &str) -> PathBuf {
+    std::env::temp_dir().join(format!("ull-m216-manifest-{}-{tag}", 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"))),
+    )
+}
+
+/// 客户端 jar 已在盘上的一份计划（于是整次安装零下载，只有清单这一步会写盘）。
+fn plan_with_existing_jar(root: &Path) -> InstallPlan {
+    let payload = b"already installed client jar".to_vec();
+    let layout = GameLayout::new(root);
+    let sha1 = verify::digest_bytes(HashAlgo::Sha1, &payload);
+    std::fs::create_dir_all(root.join("versions/1.20.1")).expect("建版本目录");
+    std::fs::write(layout.version_jar("1.20.1"), &payload).expect("放客户端 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"}}}}}}"#,
+        payload.len()
+    ))
+    .expect("清单应可解析");
+    InstallPlan::build(PlanInput {
+        layout: &layout,
+        version_id: "1.20.1",
+        resolved: &resolved,
+        asset_index: None,
+        environment: &Environment::host(),
+    })
+    .expect("组计划应成功")
+}
+
+/// 版本目录下的备份文件（`.ullbak-[-n]`）。
+fn backups(plan: &InstallPlan) -> Vec {
+    let Some(dir) = plan.version_json_path.parent() else {
+        return Vec::new();
+    };
+    std::fs::read_dir(dir)
+        .map(|entries| {
+            entries
+                .filter_map(Result::ok)
+                .map(|entry| entry.path())
+                .filter(|path| path.to_string_lossy().contains(".ullbak-"))
+                .collect()
+        })
+        .unwrap_or_default()
+}
+
+fn says_replaced(report: &InstallReport) -> bool {
+    report
+        .warnings
+        .iter()
+        .any(|line| line.contains("已替换版本清单"))
+}
+
+/// **不存在 ⇒ 正常写**（不能因为加了检测就把「第一次装」也变成需要备份的路径）。
+///
+/// 抓得住：Fresh 被误标成 Replaced/Identical（那会让报告对第一次安装说谎）、凭空多出备份、
+/// 以及「检测逻辑把没有清单的路径判成失败」。抓不住：写完之后别的启动器能不能读（实机才验）。
+#[tokio::test]
+async fn a_version_without_a_manifest_gets_one_written() {
+    let root = temp_root("fresh");
+    let plan = plan_with_existing_jar(&root);
+    let report = execute(&engine(&root), &plan, 4, None)
+        .await
+        .expect("执行应成功");
+
+    assert_eq!(report.manifest, Some(ManifestWrite::Fresh));
+    assert!(plan.version_json_path.is_file(), "清单该落盘");
+    assert!(backups(&plan).is_empty(), "没覆盖就没什么可备份");
+    assert!(!says_replaced(&report), "第一次装不该说「替换了」");
+    std::fs::remove_dir_all(&root).ok();
+}
+
+/// **存在且相同 ⇒ 不写、不备份、不提示**（重装同版本是正常操作，不是冲突）。
+///
+/// 抓得住：内容相同也走备份/告警（`backups` 非空或 `says_replaced` 为真就红）、清单内容被改。
+/// 抓不住：是不是真的没调 `write_atomic`——内容本来就一样，盘上看不出来；这一条靠
+/// `Identical` 早退那段代码 review 兜住（Windows 上另加一半证据：只读属性下 rename 会失败，
+/// 所以「只读 + 仍然成功」在 Windows 上等于没写）。
+#[tokio::test]
+async fn reinstalling_the_same_version_leaves_the_manifest_alone() {
+    let root = temp_root("identical");
+    let plan = plan_with_existing_jar(&root);
+    execute(&engine(&root), &plan, 4, None)
+        .await
+        .expect("第一次执行应成功");
+    let before = std::fs::read(&plan.version_json_path).expect("读清单");
+
+    // Windows 上把这枚文件设成只读：写它的唯一途径是 rename 盖过去，那会失败。
+    // （只读这条证据只在 Windows 上成立；Unix 下目录权限才管 rename，所以那里它不证明什么。）
+    let original = std::fs::metadata(&plan.version_json_path)
+        .expect("读元数据")
+        .permissions();
+    let mut readonly = original.clone();
+    readonly.set_readonly(true);
+    std::fs::set_permissions(&plan.version_json_path, readonly).expect("设只读");
+
+    let again = execute(&engine(&root), &plan, 4, None).await;
+    // 复原**原来的**权限（不是 `set_readonly(false)`：那会把 Unix 的位改成 world-writable）。
+    std::fs::set_permissions(&plan.version_json_path, original).expect("恢复权限");
+
+    let report = again.expect("内容相同 ⇒ 不该尝试写盘（只读也不该失败）");
+    assert_eq!(report.manifest, Some(ManifestWrite::Identical));
+    assert_eq!(
+        std::fs::read(&plan.version_json_path).expect("读清单"),
+        before,
+        "内容相同 ⇒ 清单一个字节都不该变"
+    );
+    assert!(backups(&plan).is_empty(), "内容相同不该备份");
+    assert!(!says_replaced(&report), "内容相同不该提示替换");
+    std::fs::remove_dir_all(&root).ok();
+}
+
+/// **存在且不同 ⇒ 备份 + 报告里可见**（这是「不静默破坏别人」的核心一条）。
+///
+/// 抓得住：去掉备份只覆盖（`backup` 为空、`.ullbak-*` 不存在 ⇒ 红）、旧内容丢失（备份内容
+/// 不等于别人的原文 ⇒ 红）、报告不说（`ManifestWrite::Replaced` 与告警都缺 ⇒ 红）。
+/// 抓不住：真实另一个启动器**正开着**这枚文件时的失败落点（Windows 共享冲突），那要实机。
+#[tokio::test]
+async fn a_different_manifest_is_backed_up_before_being_replaced() {
+    let root = temp_root("replaced");
+    let plan = plan_with_existing_jar(&root);
+    // 「别人铺的那份」：同路径、不同内容（这里用另一份 id/mainClass 模拟）。
+    let foreign = br#"{"id":"1.20.1","mainClass":"org.pcl.Launcher","note":"not ours"}"#.to_vec();
+    std::fs::write(&plan.version_json_path, &foreign).expect("放别人的清单");
+
+    let report = execute(&engine(&root), &plan, 4, None)
+        .await
+        .expect("执行应成功");
+    let Some(ManifestWrite::Replaced { backup }) = report.manifest.clone() else {
+        panic!("应当报 Replaced，实际 {:?}", report.manifest);
+    };
+
+    assert_eq!(
+        std::fs::read(&backup).expect("读备份"),
+        foreign,
+        "备份=别人原文"
+    );
+    assert_eq!(
+        backups(&plan),
+        vec![backup.clone()],
+        "备份只有一份、在版本目录里"
+    );
+    assert_ne!(
+        std::fs::read(&plan.version_json_path).expect("读清单"),
+        foreign,
+        "目标应当是刚解析出来的那份"
+    );
+    let written = std::fs::read_to_string(&plan.version_json_path).expect("读清单");
+    assert!(
+        VersionJson::from_json_str(&written).is_ok_and(|json| json.id.as_deref() == Some("1.20.1")),
+        "{written}"
+    );
+    assert!(says_replaced(&report), "报告里必须点名「替换了已有清单」");
+    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..4b80e9f
--- /dev/null
+++ b/crates/core/src/game/install/tests/mod.rs
@@ -0,0 +1,9 @@
+//! `game::install` 的单元测试：计划正确性 / 跳过与幂等 / 实例登记。
+//!
+//! 刻意**不打真实网络**：计划是纯计算，跳过判定只看盘，实例登记只看文件系统。
+//! 需要"引擎"的用例只要求它"不联网也能跑"（全部文件已就位 → 全跳过）。
+
+mod execute;
+mod instance;
+mod manifest_write;
+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//`（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 {
+        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 {
+    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//`，共享侧 = `.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 {
+        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 {
+    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//`）与共享侧（游戏根）。
+///
+/// # 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 {
+    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--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 {
+    let assets: Vec = 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 {
+    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,
+    #[serde(default)]
+    size: u64,
+}
+
+/// 响应里的 `binary` 子对象。
+#[derive(Debug, Deserialize)]
+struct ApiBinary {
+    #[serde(default)]
+    os: Option,
+    #[serde(default)]
+    architecture: Option,
+    #[serde(default)]
+    image_type: Option,
+    #[serde(default)]
+    package: Option,
+}
+
+/// 响应里的 `version` 子对象。
+#[derive(Debug, Deserialize)]
+struct ApiVersion {
+    #[serde(default)]
+    major: Option,
+    #[serde(default)]
+    semver: Option,
+}
+
+/// 响应列表里的一条。
+#[derive(Debug, Deserialize)]
+struct ApiAsset {
+    #[serde(default)]
+    release_name: String,
+    #[serde(default)]
+    version: Option,
+    #[serde(default)]
+    binary: Option,
+}
+
+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 {
+        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 {
+    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("502", 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/catalog.rs b/crates/core/src/game/java/catalog.rs
new file mode 100644
index 0000000..bd76bc3
--- /dev/null
+++ b/crates/core/src/game/java/catalog.rs
@@ -0,0 +1,171 @@
+//! 可下载 JDK 大版本目录（M197）：设置页「下载一个 JDK」的来源表。
+//!
+//! 用户原话（2026-11-08）：「我们内置了那么多镜像源 甚至用户不能手动选择指定版本下载。」
+//! 这一层只回答两个问题：**可选的有哪些大版本**、**每个大版本由哪几家发行版承接**。
+//! 它不联网、不落盘、不认识 UI——真正查版本与下载仍在 [`super::install`] / [`super::source`]。
+//!
+//! ## 为什么目录要写在这里而不是 UI 里
+//!
+//! 「哪几家能装 8」是 [`JdkVendor::supports`] 的知识（Oracle 从 9 起、MS 只发 11/17/21/25），
+//! 写进 UI 就是第二份真相：两边一旦不一致，界面会给出一个「点了必然失败」的按钮。
+//! 所以本模块只做「目录 × 发行版能力」的组合，UI 拿到的就是回退链里真实会试的那几家。
+//!
+//! ## 基准版本
+//!
+//! [`BASELINE_MAJOR`]（17）是 D13 定的基准：缺 Java 时先装它。它同时也是目录的一员，
+//! 但不是唯一一员——`26.1` 起 MC 要 25，`1.12.2` 只能吃 8，所以要能挑。
+
+use super::vendor::{self, JdkVendor};
+
+/// D13 的基准 JDK 大版本（没有上下文时「装哪个」的默认答案）。
+pub const BASELINE_MAJOR: u32 = 17;
+
+/// 一个可选的大版本。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct JdkChoice {
+    /// 大版本号（`17`）。
+    pub major: u32,
+    /// 是不是 LTS（展示用徽标；不参与任何判定）。
+    pub lts: bool,
+    /// 是不是 D13 基准版本。
+    pub baseline: bool,
+}
+
+/// 目录（升序）：8 / 11 / 17 / 21 / 25。
+///
+/// 8 不是「顺便带上」的：1.12.2 及更早只能吃 Java 8（LaunchWrapper），而 25 是 `26.1` 起
+/// 的下限（见 `mapping`）。少任何一端，用户在最老的实例上就只能手动去装 JDK。
+pub const CHOICES: [JdkChoice; 5] = [
+    JdkChoice {
+        major: 8,
+        lts: false,
+        baseline: false,
+    },
+    JdkChoice {
+        major: 11,
+        lts: true,
+        baseline: false,
+    },
+    JdkChoice {
+        major: 17,
+        lts: true,
+        baseline: true,
+    },
+    JdkChoice {
+        major: 21,
+        lts: true,
+        baseline: false,
+    },
+    JdkChoice {
+        major: 25,
+        lts: true,
+        baseline: false,
+    },
+];
+
+/// 全部可选大版本（升序）。
+#[must_use]
+pub const fn choices() -> &'static [JdkChoice] {
+    &CHOICES
+}
+
+/// 目录里有没有这个大版本（`Some` = 这一档可选）。
+#[must_use]
+pub fn find(major: u32) -> Option {
+    CHOICES.into_iter().find(|choice| choice.major == major)
+}
+
+/// 某个大版本能由哪几家发行版承接（顺序 = 回退链顺序）。
+///
+/// 与 [`super::install::install`] 的过滤同源——`vendor::order` 给出这条链，`supports` 去掉
+/// 发不出这个大版本的那几家。于是 GUI 上「能选哪几家」与「真会试哪几家」不会各说一套。
+#[must_use]
+pub fn vendors_for(major: u32, priority: &[JdkVendor], domestic: bool) -> Vec {
+    vendor::order(priority, domestic)
+        .into_iter()
+        .filter(|vendor| vendor.supports(major))
+        .collect()
+}
+
+/// 「该装哪个大版本」：把当前实例的最低要求对齐到目录里的一档，没有上下文时给基准版本。
+///
+/// 对齐方向是**向上取整**（1.17 要 16 → 目录里的 17），因为装低一档一定跑不起来；
+/// 要求超过目录上限（例如 26.1 的 25 已在目录里；将来 28 就超出）时给基准版本，
+/// 由页面把「这个版本装什么都不对」说清楚——而不是悄悄装个用不上的。
+#[must_use]
+pub fn default_major(required: Option) -> u32 {
+    let Some(required) = required else {
+        return BASELINE_MAJOR;
+    };
+    CHOICES
+        .iter()
+        .map(|choice| choice.major)
+        .find(|major| *major >= required)
+        .unwrap_or(BASELINE_MAJOR)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{choices, default_major, find, vendors_for, BASELINE_MAJOR};
+    use crate::game::java::vendor::{ids, JdkVendor};
+
+    /// 目录必须覆盖用户点名的三档（8 / 17 / 21），并钉住基准版本。
+    ///
+    /// 变异证明：从 `CHOICES` 里删掉 8 那一项 ⇒ 本用例红（`find(8)` 为 `None`）。
+    #[test]
+    fn the_catalog_covers_eight_seventeen_and_twenty_one() {
+        for major in [8, 17, 21] {
+            assert!(find(major).is_some(), "目录里必须有 Java {major}");
+        }
+        assert_eq!(BASELINE_MAJOR, 17, "D13 的基准版本是 17");
+        assert!(find(BASELINE_MAJOR).expect("基准版本在目录里").baseline);
+        assert_eq!(
+            choices().len(),
+            5,
+            "目录是 8/11/17/21/25 五档，改动要同步本断言与 UI 文案"
+        );
+        assert!(
+            choices()
+                .windows(2)
+                .all(|pair| pair[0].major < pair[1].major),
+            "目录必须升序（UI 直接按这个顺序画）"
+        );
+    }
+
+    /// 「8 只能由 Temurin / Zulu 承接」：Oracle 从 9 起、MS 已停发 8。
+    ///
+    /// 变异证明：把 `vendors_for` 里的 `supports` 过滤删掉 ⇒ 本用例红（8 会列出 oracle/microsoft）。
+    #[test]
+    fn java_eight_is_only_served_by_the_vendors_that_still_ship_it() {
+        assert_eq!(ids(&vendors_for(8, &[], true)), vec!["temurin", "zulu"]);
+        assert_eq!(
+            ids(&vendors_for(21, &[], true)),
+            vec!["temurin", "oracle", "microsoft", "zulu"],
+            "21 四家都在（国内默认序）"
+        );
+        assert!(
+            !vendors_for(8, &[], true).contains(&JdkVendor::Microsoft),
+            "微软已停发 8"
+        );
+    }
+
+    /// 用户优先级要真的排在最前面（与 `install` 的链同源）。
+    #[test]
+    fn the_user_priority_leads_the_vendor_list() {
+        let priority = vec![JdkVendor::Zulu];
+        assert_eq!(ids(&vendors_for(17, &priority, true))[0], "zulu");
+        assert_eq!(ids(&vendors_for(17, &priority, true)).len(), 4);
+    }
+
+    /// 「该装哪个」对齐到目录里的一档：向上取整，没有上下文给基准，超出目录给基准。
+    #[test]
+    fn the_default_major_rounds_up_into_the_catalog() {
+        assert_eq!(default_major(None), 17);
+        assert_eq!(default_major(Some(8)), 8, "1.12.2 → 8");
+        assert_eq!(default_major(Some(16)), 17, "1.17 要 16 → 目录里的 17");
+        assert_eq!(default_major(Some(17)), 17);
+        assert_eq!(default_major(Some(21)), 21, "1.20.5+ → 21");
+        assert_eq!(default_major(Some(25)), 25, "26.1 → 25");
+        assert_eq!(default_major(Some(99)), 17, "超出目录时退回基准");
+    }
+}
diff --git a/crates/core/src/game/java/discover.rs b/crates/core/src/game/java/discover.rs
new file mode 100644
index 0000000..47ee23e
--- /dev/null
+++ b/crates/core/src/game/java/discover.rs
@@ -0,0 +1,383 @@
+//! 标准安装位置扫描 + 全部发现源的合并去重（`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/*` |
+//! | Termux | `$PREFIX/lib/jvm/*`（`java-17-openjdk` 这类；`$PREFIX` 由 [`crate::platform::termux`] 识别） |
+//! | 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 crate::platform::child::quiet;
+use crate::platform::paths::{EnvSource, ProcessEnv};
+use crate::platform::termux;
+
+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 {
+    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 {
+    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 {
+    scan_java_binaries()
+        .into_iter()
+        .map(|binary| probe::probe(&binary, JavaOrigin::System))
+        .collect()
+}
+
+/// 扫描标准安装位置，返回 `bin/java[.exe]` 路径表（稳定排序，未探测）。
+#[must_use]
+pub fn scan_java_binaries() -> Vec {
+    let mut found: Vec = 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 {
+    standard_roots_in(&ProcessEnv)
+}
+
+/// 同 [`standard_roots`]，但环境变量可注入（测试 / 便携化封装用）。
+#[must_use]
+pub fn standard_roots_in(env: &dyn EnvSource) -> Vec {
+    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)));
+        }
+        // Termux 的 JDK 落在 `$PREFIX/lib/jvm`（如 `java-17-openjdk`），不在 `/usr` 下。
+        if let Some(root) = termux::jvm_root(env) {
+            roots.extend(child_dirs(&root));
+        }
+    }
+    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 {
+    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 {
+    if !cfg!(windows) {
+        return Vec::new();
+    }
+    let mut homes = Vec::new();
+    for view in ["64", "32"] {
+        let Ok(output) = quiet("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 {
+    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) -> Vec {
+    let mut seen: Vec = 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};
+    // 这两个只有 Termux 扫描的两个测试用，而那两个测试是 `cfg(unix)`——导入必须同样 gate，
+    // 否则 Windows 上不编译测试、导入就成了未使用（`-D warnings` 直接判错）。
+    #[cfg(unix)]
+    use super::standard_roots_in;
+    #[cfg(unix)]
+    use crate::platform::paths::MapEnv;
+
+    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()));
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn termux_jvm_root_is_scanned() {
+        let base = std::env::temp_dir().join(format!("ull-termux-jvm-{}", std::process::id()));
+        let jdk = base.join("lib").join("jvm").join("java-17-openjdk");
+        std::fs::create_dir_all(jdk.join("bin")).unwrap();
+        std::fs::write(jdk.join("bin").join("java"), b"").unwrap();
+
+        let env = MapEnv::new()
+            .with("TERMUX_VERSION", "0.118.3")
+            .with("PREFIX", base.to_str().unwrap());
+        let roots = standard_roots_in(&env);
+        assert!(
+            roots.contains(&jdk),
+            "Termux 的 $PREFIX/lib/jvm 必须进扫描表：{roots:?}"
+        );
+
+        std::fs::remove_dir_all(&base).ok();
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn non_termux_env_does_not_scan_prefix() {
+        let base = std::env::temp_dir().join(format!("ull-not-termux-{}", std::process::id()));
+        let jdk = base.join("lib").join("jvm").join("java-17-openjdk");
+        std::fs::create_dir_all(&jdk).unwrap();
+
+        let env = MapEnv::new().with("PREFIX", base.to_str().unwrap());
+        let roots = standard_roots_in(&env);
+        assert!(
+            !roots.contains(&jdk),
+            "非 Termux 不该扫 $PREFIX/lib/jvm：{roots:?}"
+        );
+
+        std::fs::remove_dir_all(&base).ok();
+    }
+}
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,
+}
+
+impl JavaError {
+    /// 构造。
+    #[must_use]
+    pub fn new(kind: JavaErrorKind, message: impl Into) -> Self {
+        Self {
+            kind,
+            message: message.into(),
+            hint: None,
+        }
+    }
+
+    /// 补一句「下一步怎么办」。
+    #[must_use]
+    pub fn with_hint(mut self, hint: impl Into) -> 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 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 {
+    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 {
+    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 {
+    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 {
+    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 {
+    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..6377579
--- /dev/null
+++ b/crates/core/src/game/java/install.rs
@@ -0,0 +1,333 @@
+//! 托管 JDK 安装编排：发行版回退链 → 下载引擎 → 解压 → `java -version` 验证。
+//!
+//! ```text
+//! [Termux] termux_install::attempt            系统包（.deb）——与下面这条链不共用任何一步
+//! 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 取不到、下载校验失败，
+//! 都记一条降级原因然后换下一家；只有全部失败才整体报错，错误里带上每一跳的原因。
+//!
+//! **平台参数（`AdoptiumTarget::host()`）失败不提前退出**：Termux/Android 这类没有归档产物的
+//! 宿主上，早退只会在错误里留一句「不支持该平台」，看不出是哪几家、各卡在哪；现在它降级成
+//! 每家一条原因，与其它失败同形。
+//!
+//! 这一步**不拼任何镜像 URL**（Oracle 的哈希段不可推导，见 `oracle` 模块）：Temurin 的
+//! GitHub 直链交给 `MirrorTable::expand` 展开成院校镜像，Oracle/MS/Zulu 的链接由各自模块
+//! 从目录页/模板/API 拿到最终形态，引擎只负责「把这个 URL 下下来并校验」。
+//!
+//! 这一步**不拼任何镜像 URL**（Oracle 的哈希段不可推导，见 `oracle` 模块）：Temurin 的
+//! GitHub 直链交给 `MirrorTable::expand` 展开成院校镜像，Oracle/MS/Zulu 的链接由各自模块
+//! 从目录页/模板/API 拿到最终形态，引擎只负责「把这个 URL 下下来并校验」。
+
+use std::path::{Path, PathBuf};
+
+use super::error::{JavaError, JavaErrorKind};
+use super::extract;
+use super::location::{JavaInstallRoot, LocationMode};
+use super::probe::{self, 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};
+
+use one::install_one;
+
+mod one;
+mod termux_install;
+
+/// 归档缓存目录名（在安装根下；托管目录扫描跳过它）。
+pub use super::location::CACHE_DIR;
+
+/// 一次安装请求。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct InstallRequest {
+    /// 目标大版本。
+    pub major: u32,
+    /// 钉死某一家发行版（`--vendor`）；`None` = 按回退链自己选。
+    pub vendor: Option,
+    /// 用户优先级（`java.vendorPriority`，空 = 按地区默认序）。
+    pub priority: Vec,
+}
+
+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) -> Self {
+        self.priority = priority;
+        self
+    }
+
+    /// 实际尝试顺序（`--vendor` 钉死时链里只放它）。
+    #[must_use]
+    pub fn order(&self, domestic: bool) -> Vec {
+        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 {
+    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,
+    /// 本次下载字节数（复用已装时为 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--`）。
+#[must_use]
+pub fn managed_root_dir(managed_root: &Path, major: u32, vendor: &str) -> PathBuf {
+    managed_root.join(probe::managed_dir_name(major, vendor))
+}
+
+/// 归档缓存路径（`/.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 {
+    let domestic = engine.region().is_domestic();
+    let priority = request.order(domestic);
+    let mut reasons: Vec = Vec::new();
+    // 清掉上次中断留下的 .staging-* 与空壳（只碰我们自己的形状，见 location 模块）。
+    let _ = super::location::cleanup_orphans(&location.root);
+
+    // Termux 那一条路（系统包）单独成模块：它与归档链不共用任何一步，见 `termux_install`。
+    // 它把 chain 还回来（没走成时），归档链接着往上记。
+    let mut chain = match termux_install::attempt(
+        request.vendor,
+        request.major,
+        location,
+        ChainLog::new(),
+        &mut reasons,
+    )
+    .await?
+    {
+        termux_install::Outcome::Done(installed) => return Ok(*installed),
+        termux_install::Outcome::Skipped(chain) => chain,
+    };
+
+    // 归档发行版需要 Adoptium 的平台参数；Termux/Android 上这里会 Unsupported，
+    // 不提前 `?` 退出——让每一家都记一条降级原因，错误里能看见全貌。
+    let target = AdoptiumTarget::host();
+
+    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 target = match &target {
+            Ok(target) => *target,
+            Err(error) => {
+                let message = error.message().to_string();
+                chain.failed(vendor, message.clone());
+                reasons.push(format!("{}：{message}", 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"))
+}
+
+/// 只做规划不落盘：返回将要安装的版本、目标目录与「是否已经装好」。
+///
+/// # 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 = 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::>()
+        .join("/")
+}
diff --git a/crates/core/src/game/java/install/one.rs b/crates/core/src/game/java/install/one.rs
new file mode 100644
index 0000000..e213e22
--- /dev/null
+++ b/crates/core/src/game/java/install/one.rs
@@ -0,0 +1,100 @@
+//! 回退链里的「一家」怎么装：下载 → 解压 → 探测，外加幂等复用。
+//!
+//! 从 `install.rs` 拆出来是为了守住 400 行红线（`guards.yml` 的 `file-size`）：
+//! `install.rs` 只保留「按优先级链挑一家 / 记降级原因」的编排，这里放单家的机械步骤。
+
+use std::path::PathBuf;
+
+use super::super::error::{io_error, JavaError, JavaErrorKind};
+use super::super::extract;
+use super::super::location::JavaInstallRoot;
+use super::super::probe::{self, JavaOrigin, JavaRuntime};
+use super::super::release::JdkRelease;
+use super::{archive_path, archive_request};
+use crate::download::DownloadEngine;
+
+/// 某一家的中间结果（把七元组元组换成具名结构，读起来才不费劲）。
+pub(super) struct Prepared {
+    pub(super) root: PathBuf,
+    pub(super) archive: PathBuf,
+    pub(super) runtime: JavaRuntime,
+    pub(super) downloaded: Option,
+    pub(super) bytes: u64,
+    pub(super) files: usize,
+    pub(super) extracted: bool,
+}
+
+/// 装某一家的那一份（下载 → 解压 → 探测）。
+pub(super) async fn install_one(
+    engine: &DownloadEngine,
+    location: &JavaInstallRoot,
+    release: &JdkRelease,
+) -> Result {
+    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(),
+    })
+}
+
+fn note(message: &str) {
+    if cfg!(debug_assertions) {
+        eprintln!("[ull::game::java] {message}");
+    } else {
+        let _ = message;
+    }
+}
diff --git a/crates/core/src/game/java/install/termux_install.rs b/crates/core/src/game/java/install/termux_install.rs
new file mode 100644
index 0000000..62d8ef6
--- /dev/null
+++ b/crates/core/src/game/java/install/termux_install.rs
@@ -0,0 +1,105 @@
+//! `install` 的 Termux 分支：JDK 由系统包管理器装进 `$PREFIX`，不是可下载的归档。
+//!
+//! 单独成模块有两个理由：`.deb` 这条路与归档链**没有共用步骤**（不查版本元数据、不下载、
+//! 不解压、不校验 sha256），留在 `install()` 里只能是一段嵌在中间的 if；而 `install.rs`
+//! 贴着 400 行红线（拆分前 456 行，见 `guards.yml` 的 `file-size`）。
+
+use super::super::error::{JavaError, JavaErrorKind};
+use super::super::extract;
+use super::super::location::JavaInstallRoot;
+use super::super::probe::{self, JavaOrigin};
+use super::super::release::{JdkArchive, JdkRelease};
+use super::super::source::ChainLog;
+use super::super::vendor::JdkVendor;
+use super::InstalledJdk;
+
+/// Termux 分支的结果。
+pub(super) enum Outcome {
+    /// 系统包装成了，`install` 直接返回它（装箱只为让枚举别撑到 392 字节，
+    /// 这条路一次安装才走一次）。
+    Done(Box),
+    /// 不该走这条分支，或者走了但失败（原因已进 `chain` 与 `reasons`）——把 chain 还给调用方，
+    /// 由它继续跑归档回退链。
+    Skipped(ChainLog),
+}
+
+/// 尝试走 Termux 系统包。
+///
+/// 语义（D23「`--vendor` 钉死一家、不自动降级」）：
+/// - `pinned = Some(Termux)`：只走这条，失败直接冒泡；
+/// - `pinned = None`：Termux 上先试系统包，失败记一条降级原因后继续归档链；
+/// - 其它平台：`Ok(Skipped(chain))`，一个字节都不动。
+///
+/// # Errors
+///
+/// 只有「钉死 termux」且失败时才返回错误；其余失败一律降级成 `reasons` 里的一行。
+pub(super) async fn attempt(
+    pinned: Option,
+    major: u32,
+    location: &JavaInstallRoot,
+    chain: ChainLog,
+    reasons: &mut Vec,
+) -> Result {
+    let wanted = match pinned {
+        Some(JdkVendor::Termux) => true,
+        Some(_) => false,
+        None => super::super::termux::available(),
+    };
+    if !wanted {
+        return Ok(Outcome::Skipped(chain));
+    }
+    if !super::super::termux::available() {
+        return Err(
+            JavaError::new(JavaErrorKind::Unsupported, "termux 源只在 Termux 里可用")
+                .with_hint("普通 Linux/Windows 用 --vendor temurin|oracle|microsoft|zulu"),
+        );
+    }
+    let mut chain = chain;
+    match super::super::termux::install(major).await {
+        Ok((home, reused)) => {
+            let mut runtime = probe::probe(&extract::java_binary(&home), JavaOrigin::Managed);
+            runtime.vendor = Some(JdkVendor::Termux.id().to_string());
+            let version = runtime.version.clone().unwrap_or_else(|| major.to_string());
+            let release = JdkRelease {
+                vendor: JdkVendor::Termux,
+                major,
+                version,
+                semver: None,
+                release_name: format!("Termux openjdk-{major}"),
+                archive: JdkArchive {
+                    name: format!("openjdk-{major}.deb"),
+                    url: String::new(),
+                    sha256: String::new(),
+                    size: 0,
+                },
+            };
+            chain.hit(JdkVendor::Termux, format!("命中 {}", release.summary()));
+            Ok(Outcome::Done(Box::new(InstalledJdk {
+                major: release.major,
+                vendor: JdkVendor::Termux,
+                release,
+                root: home,
+                mode: location.mode,
+                archive: std::path::PathBuf::new(),
+                runtime,
+                downloaded: if reused {
+                    None
+                } else {
+                    Some("termux".to_string())
+                },
+                bytes: 0,
+                files: 0,
+                extracted: false,
+                chain,
+            })))
+        }
+        Err(error) => {
+            if pinned == Some(JdkVendor::Termux) {
+                return Err(error);
+            }
+            chain.failed(JdkVendor::Termux, error.message().to_string());
+            reasons.push(format!("termux：{}", error.message()));
+            Ok(Outcome::Skipped(chain))
+        }
+    }
+}
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--/` | v1 既有布局，M33/M35 的托管根解析语义不变 |
+//! | Standard | Windows `%APPDATA%\Java\\\`；macOS `~/Library/Application Support/Java//`；Linux `$XDG_DATA_HOME/java//`（回落 `~/.local/share/java/…`） | 用户原话「安装到 %APPDATA%\Java\发行方\Java版本\」 |
+//! | Custom | 设置键 `java.installRoot` 指定的目录，同样按 `/` 分层 | 覆盖前两种模式 |
+//!
+//! 三条纪律：
+//!
+//! 1. **不猜平台目录**：`%APPDATA%` / `XDG_DATA_HOME` / `HOME` 全走 `platform::paths::EnvSource`，
+//!    测试能注入假环境确定性地覆盖各 OS 落点；
+//! 2. **Portable 布局永不改**：`.ULL/data/java-managed/jdk--` 是 M33 定下的，
+//!    改成 `/` 会让既有托管 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 {
+        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 {
+        standard_java_root(platform, env).map(|root| Self {
+            mode: LocationMode::Standard,
+            root,
+        })
+    }
+
+    /// Custom：`java.installRoot` 指定的目录（相对路径按数据根解析）。
+    #[must_use]
+    pub fn custom(root: impl Into) -> 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 {
+        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 用 `/`（D23 用户原话的 `<发行方>\\`），
+    /// Portable 保持 v1 的 `jdk--`（改形状会让既有托管 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())),
+        }
+    }
+
+    /// 归档缓存目录（`/.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 {
+    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 {
+    env.var("HOME").map(PathBuf::from).or_else(|| home_dir(env))
+}
+
+/// `%APPDATA%`，回落 `%USERPROFILE%\AppData\Roaming`。
+fn roaming_app_data(env: &dyn EnvSource) -> Option {
+    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 {
+    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,
+    /// 保留下来的条目数（都是我们没资格动的）。
+    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 布局：`/` 里的空目录也要收。
+        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/manual.rs b/crates/core/src/game/java/manual.rs
new file mode 100644
index 0000000..ba100ba
--- /dev/null
+++ b/crates/core/src/game/java/manual.rs
@@ -0,0 +1,324 @@
+//! 用户手动指定的 JDK 路径（M175）：校验、厂商识别、名单持久化。
+//!
+//! 场景：MSI 装的 JDK 落在 `%ProgramFiles%` 之外的盘符上、或者用户自己解压的一份 JDK ——
+//! [`super::discover`] 的标准位置扫描看不见它们，用户只能在设置页里**手动指一个路径**。
+//!
+//! # 三条口径
+//!
+//! 1. **收目录也收可执行文件**：两样都是用户会粘的东西，统一折成 `bin/java[.exe]`；
+//! 2. **校验就是真跑一次 `java -version`**：目录存在、里面有 `bin/java` 都不算数——
+//!    一份放错的 `java`（空文件、别的平台的可执行文件）必须在这里被拒，而不是等启动时崩；
+//! 3. **这份名单是 UI 的持久化，不是启动策略**：真正「用哪个 Java 启动」仍由
+//!    `java.selected_path`（core 的 schema 键）决定，名单只是「我手动加过哪些」的记忆。
+//!
+//! 名单落一个纯文本文件（一行一个路径）：它是 UI 侧的登记表，不参与 schema 校验，
+//! 也不该借道 `launcher.json`（那条路要新键 ⇒ 动 schema 版本与迁移，代价远大于收益）。
+
+use std::path::{Path, PathBuf};
+
+use super::extract::java_binary_name;
+use super::probe::{self, JavaOrigin, JavaRuntime};
+
+/// 用户可粘路径的长度上限（防手滑粘进来一整段日志）。
+pub const MAX_PATH_CHARS: usize = 512;
+
+/// 手动路径被拒的原因（稳定 id 给 UI 选文案；不做本地化）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ManualFailure {
+    /// 空串 / 全空白
+    Empty,
+    /// 超过 [`MAX_PATH_CHARS`]
+    TooLong,
+    /// 盘上没这个文件或目录
+    Missing,
+    /// 有这个东西，但里面没有 `bin/java[.exe]`（或给的不是一个 java 可执行文件）
+    NotJava,
+    /// 有 `java`，但 `java -version` 跑不起来 / 读不出版本号
+    NoVersion,
+}
+
+impl ManualFailure {
+    /// 稳定 id（UI 文案 key 的后缀，见 `pages/settings/java`）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Empty => "empty",
+            Self::TooLong => "too-long",
+            Self::Missing => "missing",
+            Self::NotJava => "not-java",
+            Self::NoVersion => "no-version",
+        }
+    }
+}
+
+/// 用户给的路径 → `java` 可执行文件（不探测，只看文件系统）。
+///
+/// # Errors
+/// 空 / 太长 / 不存在 / 不是 java 可执行文件时返回原因。
+pub fn resolve_binary(input: &str) -> Result {
+    let text = input.trim();
+    if text.is_empty() {
+        return Err(ManualFailure::Empty);
+    }
+    if text.chars().count() > MAX_PATH_CHARS {
+        return Err(ManualFailure::TooLong);
+    }
+    let path = Path::new(text);
+    if path.is_file() {
+        return looks_like_java(path)
+            .then(|| path.to_path_buf())
+            .ok_or(ManualFailure::NotJava);
+    }
+    if path.is_dir() {
+        let binary = path.join("bin").join(java_binary_name());
+        return binary
+            .is_file()
+            .then_some(binary)
+            .ok_or(ManualFailure::NotJava);
+    }
+    Err(ManualFailure::Missing)
+}
+
+/// 文件名是不是 `java` / `javaw`（Windows 带 `.exe`；POSIX 不区分大小写属于宽容）。
+fn looks_like_java(path: &Path) -> bool {
+    path.file_stem()
+        .and_then(|stem| stem.to_str())
+        .is_some_and(|stem| stem.eq_ignore_ascii_case("java") || stem.eq_ignore_ascii_case("javaw"))
+}
+
+/// 跑一次 `java -version`，同时把**原始输出**交回来（厂商要从整段输出里认，不能只看首行）。
+///
+/// 为什么需要原始输出：`-version` 的第一行只有 `openjdk version "21.0.11"`，发行方印在**第二行**
+/// （`OpenJDK Runtime Environment Microsoft-11230047` / `… Temurin-21.0.4+7`）。只拿首行去认厂商，
+/// Microsoft / Temurin 的 JDK 会一律显示成 `OpenJDK`——M175 出图时实测到了这个错。
+#[must_use]
+pub fn probe_with_output(binary: &Path, origin: JavaOrigin) -> (JavaRuntime, String) {
+    probe_with_timeout(binary, origin, super::proc::PROBE_TIMEOUT, &|| false)
+}
+
+/// 同 [`probe_with_output`]，但带**超时与取消**（扫描线程用这一条）。
+#[must_use]
+pub fn probe_with_timeout(
+    binary: &Path,
+    origin: JavaOrigin,
+    timeout: std::time::Duration,
+    cancelled: &dyn Fn() -> bool,
+) -> (JavaRuntime, String) {
+    let mut runtime = JavaRuntime::unknown(binary.to_path_buf(), origin);
+    let mut command = crate::platform::child::quiet(binary);
+    command.arg("-version");
+    let Some(output) = super::proc::run_with_timeout(command, timeout, cancelled) else {
+        return (runtime, String::new());
+    };
+    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)) = probe::parse_version_output(&text) {
+        runtime.major = Some(major);
+        runtime.version = Some(line);
+        runtime.bits = probe::bits_of(&text);
+    }
+    runtime.vendor = vendor_of(&text);
+    (runtime, text)
+}
+
+/// 严格探测：必须真跑得起来 `-version`。
+///
+/// 与 [`probe::probe`] 的差别只有一个：后者「探测不出也返回一个 runtime」，这里探测不出就是**拒绝**。
+/// 手动添加这条路上，一个答不出话的 `java` 就是无效输入，不能进名单。
+///
+/// # Errors
+/// 校验不过（[`resolve_binary`]）或 `-version` 读不出版本号时返回原因。
+pub fn probe_manual(input: &str) -> Result {
+    let binary = resolve_binary(input)?;
+    let (runtime, _output) = probe_with_output(&binary, JavaOrigin::System);
+    if runtime.major.is_none() {
+        return Err(ManualFailure::NoVersion);
+    }
+    Ok(runtime)
+}
+
+/// `java -version` 输出里的发行方（认不出返回 `None`，不猜）。
+///
+/// 为什么从输出里认而不是从安装目录名认：用户手动指的路径跟目录命名毫无关系，
+/// 而 `java -version` 的首行/次行本来就把发行方印出来了
+/// （`OpenJDK Runtime Environment Temurin-21.0.4+7`、`Java(TM) SE Runtime Environment`）。
+#[must_use]
+pub fn vendor_of(text: &str) -> Option {
+    let lowered = text.to_ascii_lowercase();
+    // 顺序即判据：「Temurin 构建的 OpenJDK」也能匹配到 openjdk，所以具体品牌必须排在前面。
+    const MARKERS: &[(&str, &str)] = &[
+        ("temurin", "Temurin"),
+        ("adoptium", "Temurin"),
+        ("microsoft", "Microsoft"),
+        ("zulu", "Zulu"),
+        ("azul", "Zulu"),
+        ("corretto", "Corretto"),
+        ("semeru", "Semeru"),
+        ("graalvm", "GraalVM"),
+        ("sapmachine", "SapMachine"),
+        ("oracle", "Oracle"),
+        // 老 Oracle / HotSpot 的 `-version` 不提 "Oracle"（Java 8 就是 `Java(TM) SE Runtime
+        // Environment` + `Java HotSpot(TM) 64-Bit Server VM`），这两条是那一代的唯一指纹。
+        ("se runtime", "Oracle"),
+        ("hotspot", "Oracle"),
+        ("openjdk", "OpenJDK"),
+    ];
+    MARKERS
+        .iter()
+        .find(|(needle, _)| lowered.contains(needle))
+        .map(|(_, display)| (*display).to_string())
+}
+
+/// 读名单（文件不存在 / 读不动 ⇒ 空名单，不报错）。
+///
+/// 去掉空行、去重（按 [`probe::discover::path_key`](super::discover::path_key) 的同一套键），
+/// 顺序保持文件里的顺序（用户添加的先后）。
+#[must_use]
+pub fn load_paths(file: &Path) -> Vec {
+    let Ok(text) = std::fs::read_to_string(file) else {
+        return Vec::new();
+    };
+    let mut paths: Vec = Vec::new();
+    for line in text.lines() {
+        let line = line.trim();
+        if line.is_empty() {
+            continue;
+        }
+        let path = PathBuf::from(line);
+        if !paths
+            .iter()
+            .any(|known| super::discover::path_key(known) == super::discover::path_key(&path))
+        {
+            paths.push(path);
+        }
+    }
+    paths
+}
+
+/// 写名单（一行一个，末尾换行；父目录不存在就建）。
+///
+/// # Errors
+/// 目录建不出来或写盘失败时返回 IO 错误。
+pub fn save_paths(file: &Path, paths: &[PathBuf]) -> std::io::Result<()> {
+    if let Some(parent) = file.parent() {
+        std::fs::create_dir_all(parent)?;
+    }
+    let mut text = String::new();
+    for path in paths {
+        text.push_str(&path.display().to_string());
+        text.push('\n');
+    }
+    std::fs::write(file, text)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn temp(tag: &str) -> PathBuf {
+        let dir = std::env::temp_dir().join(format!(
+            "ull-java-manual-{tag}-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .map(|d| d.subsec_nanos())
+                .unwrap_or(0)
+        ));
+        let _ = std::fs::remove_dir_all(&dir);
+        std::fs::create_dir_all(&dir).expect("临时目录");
+        dir
+    }
+
+    #[test]
+    fn recognises_vendors_from_real_version_lines() {
+        assert_eq!(
+            vendor_of("OpenJDK Runtime Environment Temurin-21.0.4+7 (build 21.0.4+7-LTS)"),
+            Some("Temurin".to_string())
+        );
+        assert_eq!(
+            vendor_of("OpenJDK 64-Bit Server VM Microsoft-8321 (build 17.0.13+11)"),
+            Some("Microsoft".to_string())
+        );
+        assert_eq!(
+            vendor_of("openjdk version \"17.0.9\" 2023-10-17\nOpenJDK Runtime Environment Zulu17.46+19-CA"),
+            Some("Zulu".to_string())
+        );
+        assert_eq!(
+            vendor_of(
+                "java version \"1.8.0_402\"\nJava(TM) SE Runtime Environment (build 1.8.0_402-b06)"
+            ),
+            Some("Oracle".to_string())
+        );
+        assert_eq!(vendor_of("nothing useful here"), None);
+    }
+
+    #[test]
+    fn accepts_a_directory_and_a_binary_but_rejects_anything_else() {
+        let dir = temp("resolve");
+        let jdk = dir.join("jdk-21");
+        std::fs::create_dir_all(jdk.join("bin")).expect("bin");
+        let binary = jdk.join("bin").join(java_binary_name());
+        std::fs::write(&binary, b"").expect("写 java");
+
+        assert_eq!(
+            resolve_binary(&jdk.display().to_string()),
+            Ok(binary.clone())
+        );
+        assert_eq!(resolve_binary(&binary.display().to_string()), Ok(binary));
+        assert_eq!(resolve_binary("   "), Err(ManualFailure::Empty));
+        assert_eq!(
+            resolve_binary(&dir.join("nope").display().to_string()),
+            Err(ManualFailure::Missing)
+        );
+        let empty = dir.join("empty");
+        std::fs::create_dir_all(&empty).expect("empty");
+        assert_eq!(
+            resolve_binary(&empty.display().to_string()),
+            Err(ManualFailure::NotJava)
+        );
+        // 目录里有一个**不叫 java 的**可执行文件：也不算。
+        let text = dir.join("notes.txt");
+        std::fs::write(&text, b"hi").expect("写文本");
+        assert_eq!(
+            resolve_binary(&text.display().to_string()),
+            Err(ManualFailure::NotJava)
+        );
+        let long = "a".repeat(MAX_PATH_CHARS + 1);
+        assert_eq!(resolve_binary(&long), Err(ManualFailure::TooLong));
+
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    #[test]
+    fn a_binary_that_cannot_answer_version_is_refused() {
+        let dir = temp("noversion");
+        let jdk = dir.join("jdk");
+        std::fs::create_dir_all(jdk.join("bin")).expect("bin");
+        // 空文件：解析不出版本号 ⇒ 拒绝（这条正是「文件存在 ≠ 能用」的判据）。
+        std::fs::write(jdk.join("bin").join(java_binary_name()), b"").expect("写 java");
+        assert_eq!(
+            probe_manual(&jdk.display().to_string()).err(),
+            Some(ManualFailure::NoVersion)
+        );
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    #[test]
+    fn the_list_round_trips_and_dedupes() {
+        let dir = temp("list");
+        let file = dir.join("config").join("java-extra-paths.txt");
+        let paths = vec![
+            PathBuf::from("C:/jdk/17"),
+            PathBuf::from("C:/jdk/21"),
+            PathBuf::from("C:\\jdk\\17"),
+        ];
+        save_paths(&file, &paths).expect("写名单");
+        // 第三条是第一条的另一种写法：读回来只留一条（与扫描去重同一套键）。
+        assert_eq!(load_paths(&file).len(), 2);
+        assert_eq!(load_paths(&file)[0], PathBuf::from("C:/jdk/17"));
+
+        let missing = dir.join("nope.txt");
+        assert!(load_paths(&missing).is_empty(), "缺文件是空名单，不是错误");
+        std::fs::remove_dir_all(&dir).ok();
+    }
+}
diff --git a/crates/core/src/game/java/mapping.rs b/crates/core/src/game/java/mapping.rs
new file mode 100644
index 0000000..bd8b404
--- /dev/null
+++ b/crates/core/src/game/java/mapping.rs
@@ -0,0 +1,282 @@
+//! MC 版本 ↔ Java 版本映射（平移 HMCL 约束体系）；不符判定与文案见
+//! [`crate::game::java::mismatch`]（其中的 `check` / `JavaMismatch` 仍从本模块转出，
+//! 调用方的 `mapping::check` 写法不变）。
+//!
+//! 依据 `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};
+
+pub use super::mismatch::{check, JavaMismatch};
+
+/// 要求来源（`--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,
+    /// 来源。
+    pub source: RequirementSource,
+}
+
+impl JavaRequirement {
+    /// 构造。
+    #[must_use]
+    pub const fn new(minimum: u32, maximum: Option, source: RequirementSource) -> Self {
+        Self {
+            minimum,
+            maximum,
+            source,
+        }
+    }
+
+    /// 静态表来源的构造。
+    #[must_use]
+    pub const fn table(minimum: u32, maximum: Option) -> 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),
+        }
+    }
+}
+
+/// 静态表：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 {
+    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 {
+        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 {
+    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::() {
+            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::{recommended_major, requirement_for, JavaRequirement};
+
+    #[test]
+    fn table_covers_the_hmcl_boundaries() {
+        let cases: &[(&str, u32, Option)] = &[
+            ("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 describe_spells_out_the_interval() {
+        assert_eq!(requirement_for("1.12.2").describe(), "Java 8");
+        assert_eq!(requirement_for("1.20.5").describe(), "Java 21+");
+        assert_eq!(JavaRequirement::table(8, Some(16)).describe(), "Java 8–16");
+    }
+}
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   # "  "
+//! ```
+//!
+//! 三条硬事实（都影响实现）：
+//!
+//! 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,
+}
+
+impl MsVersion {
+    /// 原样的版本串。
+    #[must_use]
+    pub fn text(&self) -> String {
+        self.segments
+            .iter()
+            .map(u32::to_string)
+            .collect::>()
+            .join(".")
+    }
+}
+
+/// 解析 MS 的版本串；段数必须 3..=5（MS 的语义：`major.update.patch[.build[.rev]]`）。
+#[must_use]
+pub fn parse_version(text: &str) -> Option {
+    let mut segments = Vec::new();
+    for segment in text.trim().split('.') {
+        segments.push(segment.parse::().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 {
+    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 {
+    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::>()
+        .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![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/mismatch.rs b/crates/core/src/game/java/mismatch.rs
new file mode 100644
index 0000000..a2168d8
--- /dev/null
+++ b/crates/core/src/game/java/mismatch.rs
@@ -0,0 +1,167 @@
+//! Java 与目标版本**不符**的判定与文案（从 `mapping` 拆出：那边只管版本表与清单推导）。
+//!
+//! 两种形态（D13 引入，D4 起参与启动决策）：
+//!
+//! - [`JavaMismatch::TooOld`]：新版本配了太老的 Java（1.20.5+ 需要 21，手里只有 17）；
+//! - [`JavaMismatch::TooNew`]：老版本配了新 Java（1.12.2 只能用 8，托管里只有 21/25）。
+//!
+//! 这里只产出数据与人读文案；**拦不拦**由调用方决定（CLI 见
+//! [`crate::game::java::select::decide`]：不符且用户没显式指定 Java 就拦住）。
+
+use super::mapping::JavaRequirement;
+
+/// 不符的两种形态。
+#[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 文件）"
+            ),
+        }
+    }
+
+    /// 一句**可操作**的建议（D4：拦下来之后必须告诉用户怎么继续）。
+    ///
+    /// 两个出口：装一个对版本的 JDK，或用 `--java` 明确指定要试的那个（显式指定不再被拦）。
+    #[must_use]
+    pub fn advice(self) -> String {
+        let wanted = match self {
+            Self::TooOld { required, .. } => required,
+            Self::TooNew { maximum, .. } => maximum,
+        };
+        format!(
+            "装一个 Java {wanted}（`java install {wanted}`），或用 `--java <路径>` 指定要试的那个"
+        )
+    }
+
+    /// 实际主版本号。
+    #[must_use]
+    pub const fn actual(self) -> u32 {
+        match self {
+            Self::TooOld { actual, .. } | Self::TooNew { actual, .. } => actual,
+        }
+    }
+}
+
+/// 判需求与实际是否相符（`None` = 相符）。
+#[must_use]
+pub fn check(actual: u32, required: &JavaRequirement) -> Option {
+    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
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{check, JavaMismatch};
+    use crate::game::java::mapping::JavaRequirement;
+
+    #[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
+            })
+        );
+    }
+
+    #[test]
+    fn messages_name_both_sides_and_codes_are_stable() {
+        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"
+        );
+        assert_eq!(
+            JavaMismatch::TooNew {
+                maximum: 8,
+                actual: 21
+            }
+            .actual(),
+            21
+        );
+    }
+
+    #[test]
+    fn advice_names_the_major_and_the_escape_hatch() {
+        let advice = JavaMismatch::TooNew {
+            maximum: 8,
+            actual: 17,
+        }
+        .advice();
+        assert!(advice.contains("Java 8"), "{advice}");
+        assert!(advice.contains("java install 8"), "{advice}");
+        assert!(advice.contains("--java"), "{advice}");
+        assert!(JavaMismatch::TooOld {
+            required: 21,
+            actual: 17
+        }
+        .advice()
+        .contains("java install 21"));
+    }
+}
diff --git a/crates/core/src/game/java/mod.rs b/crates/core/src/game/java/mod.rs
new file mode 100644
index 0000000..2e8c105
--- /dev/null
+++ b/crates/core/src/game/java/mod.rs
@@ -0,0 +1,102 @@
+//! 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 优先
+//! mismatch  不符判定（太老 / 太新）+ 说明与可操作建议
+//! ```
+//!
+//! # 三条边界
+//!
+//! 1. **不碰网络细节**：包下载一律交 `core::download` 的引擎，本模块不写重试循环
+//!    （`MirrorTable::expand` 负责 Temurin 的镜像展开；Oracle 的目录解析在 `oracle`）；
+//! 2. **不弹窗**：不符检查只产出数据（[`JavaMismatch`]）与取舍结论（[`LaunchVerdict`]），
+//!    提示与拦截都交给调用方（D4：不符且用户没显式指定 Java 时 `ull launch` 直接报错，
+//!    显式 `--java` 则只告警）；
+//! 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\\\     （mac/Linux 见 location 模块）
+//! ```
+
+pub mod api;
+pub mod catalog;
+pub mod discover;
+pub mod error;
+pub mod extract;
+pub mod install;
+pub mod location;
+pub mod manual;
+pub mod mapping;
+pub mod microsoft;
+pub mod mismatch;
+pub mod net;
+pub mod oracle;
+pub mod probe;
+pub mod proc;
+pub mod release;
+pub mod select;
+pub mod source;
+pub mod staged;
+pub mod target;
+pub mod termux;
+pub mod vendor;
+pub mod zulu;
+
+pub use self::api::{
+    latest_url, parse_latest, JdkArchive, JdkRelease, ADOPTIUM_API_BASE, JDK_VENDOR,
+};
+pub use self::catalog::{
+    choices as jdk_choices, default_major, vendors_for, JdkChoice, BASELINE_MAJOR,
+};
+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::{decide, distance, pick, resolve, JavaResolution, LaunchVerdict};
+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 {
+    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 {
+    let mut out: Vec = 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> {
+    let mut parts = Vec::new();
+    for segment in version.split('.') {
+        parts.push(segment.parse::().ok()?);
+    }
+    (!parts.is_empty()).then_some(parts)
+}
+
+/// 目录页里属于 `major` 的版本串，按版本**降序**（最新在前）。
+#[must_use]
+pub fn versions_for(html: &str, major: u32) -> Vec {
+    let mut found: Vec<(Vec, 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 {
+    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 {
+    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 = 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 {
+    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 抓取，`
` 列表）。
+    const INDEX: &str = r#"
Name         Last modified     Size
+10/          22-Aug-2021 15:18 -
+17.0.2/      22-Aug-2021 15:19 -
+21/          22-Aug-2021 15:19 -
+21.0.1/      22-Aug-2021 15:19 -
+21.0.2/      06-Jan-2024 15:26 -
+27.0.1.0.3/ 06-Jan-2026 15:26 -
+../
+
"#;
+
+    /// 华为云 `/openjdk/21.0.2/` 的真实文件列表片段。
+    const LISTING: &str = r#"
../
+openjdk-21.0.2_linux-x64_bin.tar.gz 194.18 MB
+openjdk-21.0.2_windows-x64_bin.zip 192 MB
+
"#;
+
+    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(
+            "mirrors 门户",
+            &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..2d3430b
--- /dev/null
+++ b/crates/core/src/game/java/probe.rs
@@ -0,0 +1,370 @@
+//! Java 运行时探测：跑一次 `java -version`、扫托管目录、列系统候选。
+//!
+//! 探测动作只有两种：读托管目录（`.ULL/data/java-managed/jdk--/`）
+//! 与跑 `java -version`（输出在 stderr，主版本号从引号里的版本号解析，
+//! `1.8.0_402` 这种老形态换算成 8）。
+//!
+//! 「选哪个 Java 启动」不在这里，而在 [`super::select`]——那边是**纯函数**，
+//! 候选运行时由调用方注入，测试因此不需要真的装三个 JDK。
+
+use std::path::{Path, PathBuf};
+
+use super::extract::{java_binary_name, read_stamp};
+use super::vendor::JdkVendor;
+use crate::platform::child::quiet;
+
+/// 缺省 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,
+    /// 主版本号（`1.8.0_402` → 8）。
+    pub major: Option,
+    /// 位数（32 / 64；探测不到时按宿主）。
+    pub bits: u32,
+    /// 托管目录里的供应商（`temurin`）；其它来源为 `None`。
+    pub vendor: Option,
+}
+
+impl JavaRuntime {
+    /// 探测不出来时给个「版本未知」的占位。
+    #[must_use]
+    pub fn unknown(binary: impl Into, 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) = quiet(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
+/// /jdk--/bin/java      Portable（v1 布局，M33 定下，永不改）
+/// ///bin/java        Standard / Custom（D23 的 <发行方>/<版本>）
+/// ```
+///
+/// 只认带戳记的目录：托管区是我们自己写的地方，但没有戳记的子目录可能是用户塞进来的
+/// 别的东西，不去猜它。`major` 一律以 `java -version` 为准（戳记只用于幂等判定）。
+#[must_use]
+pub fn discover_managed(managed_root: &Path) -> Vec {
+    let mut found: Vec = 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 名取自父目录名。
+        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 {
+    let mut found: Vec = 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 {
+    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 {
+    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 {
+    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 {
+    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 {
+    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 {
+    let mut parts = version.split(['.', '_', '-']);
+    let first = parts.next()?.parse::().ok()?;
+    if first == 1 {
+        parts.next()?.parse::().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/proc.rs b/crates/core/src/game/java/proc.rs
new file mode 100644
index 0000000..e43e828
--- /dev/null
+++ b/crates/core/src/game/java/proc.rs
@@ -0,0 +1,279 @@
+//! 子进程的**带超时 / 可打断**执行（M175 r1 复审 P2-5）。
+//!
+//! `Command::output()` 是「等到底」：一份放在挂死网络盘上的 `java` 会让调用它的扫描线程永远不
+//! 返回，界面上「取消」也就永远兑现不了。这里只做一件事——**要么拿到输出，要么把它杀掉**。
+
+use std::time::Duration;
+
+/// 单个候选的探测预算（`java -version` 正常几十毫秒；8 秒还没答话就是卡住了）。
+pub const PROBE_TIMEOUT: Duration = Duration::from_secs(8);
+
+/// 轮询间隔（`try_wait` 的粒度）：够细，取消能在一帧内生效；够粗，不烧 CPU。
+const POLL_INTERVAL: Duration = Duration::from_millis(20);
+
+/// 杀掉并**回收**子进程：`kill()` 只是投递终止请求，`wait()` 才是回收。
+///
+/// 为什么两件必须一起做（M199 / r3 复审 P3-5）：只 `kill()` 不 `wait()`，Unix 上留下**僵尸**
+/// （进程表项与 pid 都不释放），Windows 上句柄活到 `Child` 被 drop 为止、终止也只是异步的。
+/// 抽成函数的理由：它是这条不变量的唯一落点，三个分支（超时 / 取消 / 出错）都走这里。
+fn terminate(child: &mut std::process::Child) {
+    let _ = child.kill();
+    let _ = child.wait();
+}
+
+/// 跑一个命令并等它结束，**带超时与可打断**：`cancelled()` 为真或超时就把子进程 kill 掉。
+///
+/// 返回 `None` = 没起来 / 超时 / 被取消（三者对调用方是同一件事：这次探测没有结论）。
+///
+/// 为什么不用 `Command::output()`：它是「等到底」，一个卡住的子进程会把整个扫描线程钉死，
+/// 而取消位只能在两次探测之间被看到——取消就永远兑现不了。
+#[must_use]
+pub fn run_with_timeout(
+    mut command: std::process::Command,
+    timeout: Duration,
+    cancelled: &dyn Fn() -> bool,
+) -> Option {
+    use std::process::Stdio;
+
+    command
+        .stdin(Stdio::null())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped());
+    let mut child = command.spawn().ok()?;
+    let started = std::time::Instant::now();
+    loop {
+        match child.try_wait() {
+            Ok(Some(_)) => break,
+            Ok(None) => {
+                if cancelled() || started.elapsed() > timeout {
+                    terminate(&mut child);
+                    return None;
+                }
+                std::thread::sleep(POLL_INTERVAL);
+            }
+            Err(_) => {
+                terminate(&mut child);
+                return None;
+            }
+        }
+    }
+    child.wait_with_output().ok()
+}
+
+#[cfg(test)]
+mod tests {
+    use std::time::Duration;
+
+    use super::run_with_timeout;
+
+    #[test]
+    fn a_hung_probe_is_killed_after_the_timeout() {
+        // 一个「永远不返回」的子进程：不杀掉它，扫描线程就永远不结束（复审 P2-5）。
+        let started = std::time::Instant::now();
+        let output = run_with_timeout(
+            sleeping_command(30),
+            std::time::Duration::from_millis(400),
+            &|| false,
+        );
+        assert!(output.is_none(), "超时必须判成「没有结论」");
+        let elapsed = started.elapsed();
+        assert!(
+            elapsed < std::time::Duration::from_secs(5),
+            "超时之后必须 kill 掉子进程并返回，实际等了 {elapsed:?}"
+        );
+    }
+
+    #[test]
+    fn a_cancel_interrupts_the_probe_that_is_already_running() {
+        // 取消不能只在「两次探测之间」被看到：卡住的那一个也要能打断。
+        let flag = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
+        let tripper = flag.clone();
+        std::thread::spawn(move || {
+            std::thread::sleep(std::time::Duration::from_millis(150));
+            tripper.store(true, std::sync::atomic::Ordering::SeqCst);
+        });
+        let started = std::time::Instant::now();
+        let output = run_with_timeout(
+            sleeping_command(30),
+            std::time::Duration::from_secs(30),
+            &|| flag.load(std::sync::atomic::Ordering::SeqCst),
+        );
+        assert!(output.is_none(), "被取消的探测没有结论");
+        assert!(
+            started.elapsed() < std::time::Duration::from_secs(10),
+            "取消必须打断正在跑的那个探测，而不是等它自己结束"
+        );
+    }
+
+    /// 超时之后子进程必须**真的死了**：让它延时写一个标记文件，断言那个文件从未出现。
+    ///
+    /// 为什么要有这一条（r2 复审 P3-1）：上面两条只断言「返回得快」，把 kill 那几行删掉它们照样绿
+    /// ——而没杀掉的子进程会继续跑（写它自己的文件、占句柄）。
+    ///
+    /// 为什么还要一条「子进程真的起过」（M199 / r3 复审 P3-5）：`command.spawn().ok()?` 在命令
+    /// 起不来时也返回 `None`，于是机器上没有 powershell 时本用例**空跑也照样绿**。现在先用同一条
+    /// 命令（不延时）真跑一次，再要求超时那一跑也留下启动标记（里面有子进程自己的 pid）——起不来的
+    /// 机器从此是红，不是静默通过。
+    ///
+    /// 时间账（免得慢机器上假红/假绿）：超时 3s、子进程尾部延时 4s、事后等待 4s。若 kill 没生效，
+    /// 子进程在「起进程耗时 + 4s」写出存活标记，而这次检查在 3s + 4s = 7s；只要它起得来（上一步已
+    /// 证明 3s 内起得来，否则启动标记也写不出来）就一定在检查之前写出来 ⇒ 红。反过来，若 kill 生效，
+    /// 它在 3s 就被杀掉，4s 的尾巴根本走不到 ⇒ 绿。
+    ///
+    /// 变异证明：删掉 `terminate()` 里的 `child.kill()` ⇒ 子进程活到 4 秒、把存活标记写出来 ⇒ 红。
+    #[test]
+    fn a_timed_out_child_is_really_killed() {
+        const TIMEOUT: Duration = Duration::from_secs(3);
+        const TAIL: u32 = 4;
+        const WAIT: Duration = Duration::from_secs(4);
+
+        let dir = temp_dir("kill");
+        let started = dir.join("started.txt");
+        let survived = dir.join("survived.txt");
+
+        // ① 子进程真的起得来吗（起不来的话下面全是空跑：`spawn().ok()?` 也给 `None`）。
+        let preflight = marker_command(&started, &survived, 0)
+            .output()
+            .expect("子进程必须真的起得来：本机缺 powershell / sh 时本用例不许静默通过");
+        assert!(
+            preflight.status.success(),
+            "标记命令自己失败了（stderr：{}）",
+            String::from_utf8_lossy(&preflight.stderr)
+        );
+        assert!(
+            started.exists() && survived.exists(),
+            "标记命令没写出标记：它没真的跑过，后面的结论不成立"
+        );
+        std::fs::remove_file(&started).ok();
+        std::fs::remove_file(&survived).ok();
+
+        // ② 超时那一跑：被杀掉，且被杀之前它确实已经起来了。
+        let output = run_with_timeout(marker_command(&started, &survived, TAIL), TIMEOUT, &|| {
+            false
+        });
+        assert!(output.is_none(), "超时没有结论");
+        assert!(
+            started.exists(),
+            "子进程没写出启动标记：这一跑是空跑（{TIMEOUT:?} 内没起来），用例不成立"
+        );
+        std::thread::sleep(WAIT);
+        assert!(
+            !survived.exists(),
+            "子进程在超时后仍然活着并执行了尾巴（存活标记出现了）：kill 没生效"
+        );
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    /// 被 kill 之后必须**回收**（`wait()`）：只 `kill()` 不 `wait()` 会留下僵尸。
+    ///
+    /// 为什么只能在 Linux / Android 上守（M199）：僵尸是 Unix 的概念——进程被杀掉而父进程没
+    /// `wait()` 时，它在进程表里留着、`/proc/` 仍然存在（状态 `Z`），pid 也不释放；`wait()`
+    /// 之后进程表项立刻消失。Windows 没有这个可观测状态（终止 + 句柄释放之后没有残留），所以那条
+    /// 平台上「少写一行 `wait()`」只能靠代码评审——**这是本用例覆盖不到的一半**，报告里要说清。
+    ///
+    /// 变异证明：只删 `terminate()` 里的 `child.wait()`（留着 `kill()`）⇒ pid 成僵尸 ⇒ 红；
+    /// 把 `terminate()` 整个换成空函数（两条都删）⇒ 子进程还活着 ⇒ 红。
+    #[cfg(any(target_os = "linux", target_os = "android"))]
+    #[test]
+    fn a_killed_child_is_reaped_not_left_a_zombie() {
+        let dir = temp_dir("reap");
+        let started = dir.join("started.txt");
+        let survived = dir.join("survived.txt");
+        let output = run_with_timeout(
+            marker_command(&started, &survived, 30),
+            Duration::from_secs(2),
+            &|| false,
+        );
+        assert!(output.is_none(), "超时没有结论");
+        let pid: u32 = std::fs::read_to_string(&started)
+            .expect("子进程没写出 pid：这一跑是空跑")
+            .trim()
+            .parse()
+            .expect("启动标记里应当是子进程的 pid");
+        // `wait()` 是同步回收：它返回时 `/proc/` 就该没了，不用等。
+        match process_state(pid) {
+            None => {}
+            Some('Z') => panic!("kill 之后没有 wait 回收：pid {pid} 成了僵尸（进程表项还在）"),
+            Some(state) => panic!("pid {pid} 还在（状态 {state}）：它没被杀掉，或没被回收"),
+        }
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    /// `/proc/` 里的进程状态字符（`None` = 进程表里已经没有这一项）。
+    #[cfg(any(target_os = "linux", target_os = "android"))]
+    fn process_state(pid: u32) -> Option {
+        let stat = std::fs::read_to_string(format!("/proc/{pid}/stat")).ok()?;
+        // `pid (comm) S …`：comm 里可能有空格和括号，只认**最后一个** `)` 之后的第一个字符。
+        let rest = &stat[stat.rfind(')')? + 1..];
+        rest.chars().find(|c| !c.is_whitespace())
+    }
+
+    /// 每个用例一个临时目录（pid + 纳秒：并行用例不会撞在一起）。
+    fn temp_dir(tag: &str) -> std::path::PathBuf {
+        let dir = std::env::temp_dir().join(format!(
+            "ull-proc-{tag}-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .map(|d| d.subsec_nanos())
+                .unwrap_or(0)
+        ));
+        std::fs::create_dir_all(&dir).expect("临时目录");
+        dir
+    }
+
+    /// 「先写启动标记（子进程 pid）、延时 `seconds` 秒之后再写存活标记」的命令（两平台语义相同）。
+    ///
+    /// 启动标记里的 pid 同时证明两件事：**spawn 真的成功、进程真的跑起来了**（M199：`spawn().ok()?`
+    /// 起不来时也是 `None`，本用例因此会空跑），以及「这个 pid 后来被回收了吗」。
+    ///
+    /// 两个标记的路径**走环境变量**：`cmd /C "…"` 会被 Rust 与 cmd 各加一层引号、把重定向目标截断
+    /// （实测命令立刻失败 ⇒ 假红）；`sh` 用 `"$VAR"`、PowerShell 用 `$env:` 取，命令行上一个引号
+    /// 都不出现，路径里有空格也不会被拆开。
+    fn marker_command(
+        started: &std::path::Path,
+        survived: &std::path::Path,
+        seconds: u32,
+    ) -> std::process::Command {
+        let mut command = if cfg!(windows) {
+            let mut command = crate::platform::child::quiet("powershell");
+            command.args([
+                "-NoProfile",
+                "-Command",
+                &format!(
+                    "Set-Content -Path $env:ULL_PROC_STARTED -Value $PID; \
+                     Start-Sleep -Seconds {seconds}; \
+                     Set-Content -Path $env:ULL_PROC_SURVIVED -Value alive"
+                ),
+            ]);
+            command
+        } else {
+            let mut command = crate::platform::child::quiet("sh");
+            command.args([
+                "-c",
+                &format!(
+                    "echo $$ > \"$ULL_PROC_STARTED\"; sleep {seconds}; \
+                     echo alive > \"$ULL_PROC_SURVIVED\""
+                ),
+            ]);
+            command
+        };
+        command
+            .env("ULL_PROC_STARTED", started)
+            .env("ULL_PROC_SURVIVED", survived);
+        command
+    }
+
+    /// 一个必然超时的命令（两个平台都有，且在「等很久」这件事上行为一致）。
+    fn sleeping_command(seconds: u32) -> std::process::Command {
+        if cfg!(windows) {
+            let mut command = crate::platform::child::quiet("cmd");
+            command.args(["/C", &format!("ping -n {seconds} 127.0.0.1 > NUL")]);
+            command
+        } else {
+            let mut command = crate::platform::child::quiet("sleep");
+            command.arg(seconds.to_string());
+            command
+        }
+    }
+}
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,
+    /// 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 {
+    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 {
+    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：`  `，并且带大写与 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("404"), 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..a9d5bb8
--- /dev/null
+++ b/crates/core/src/game/java/select.rs
@@ -0,0 +1,292 @@
+//! 「启动选哪个 Java」的**纯**优先链（D13）。
+//!
+//! 优先级：实例覆盖（`--java` / 档案 `javaPath`）> 托管目录里**满足要求**的 JDK >
+//! `JAVA_HOME` > `PATH`。实例覆盖由调用方单独判（用户明确指定了就不参与打分），
+//! 这里只处理「一堆已探测的候选 + 一个要求」的挑选。
+//!
+//! 挑选规则（比「机械按来源排序」更贴近用户预期）：
+//!
+//! 1. **满足要求的候选优先**——1.12.2 只能用 Java 8，托管的 21 再新也不能选；
+//! 2. 全都不满足时按**版本距离**（[`distance`]）取最接近的那个，同距离再按来源：
+//!    托管 > `JAVA_HOME` > `PATH`（D13：托管目录是启动器的地盘，用户 PATH 上的 java
+//!    可能是另一个 JDK 的残留）。距离优先而非来源优先是 D4：托管里只有 25、`JAVA_HOME`
+//!    是 21 时，1.12.2 该被推上更接近的 21，而不是机械地选「来源排名更高」的托管 25；
+//! 3. 挑完还要决定**要不要拦**（[`decide`]）：不符且用户没显式指定 Java 就不启动。
+//!
+//! 抽成纯函数是为了可测：测试注入「托管 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,
+    /// 目标版本对 Java 的要求。
+    pub required: JavaRequirement,
+    /// 不符说明（`None` = 满足要求，或压根没探测到 Java）。
+    pub mismatch: Option,
+}
+
+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()
+    }
+}
+
+/// 候选主版本号与要求区间的**距离**（`0` = 满足要求）。
+///
+/// D4：主版本号是离散档位，用户装的 `17` 与 `25` 对「只能用 8」的 1.12.2 都是错的，
+/// 但 `17` 只差 9 档、`25` 差 17 档——真机上「离得近」的那个起得来的概率明显更高
+/// （老版本对新 class 文件的容忍度随版本差递减）。
+#[must_use]
+pub fn distance(major: u32, required: &JavaRequirement) -> u32 {
+    if major < required.minimum {
+        return required.minimum - major;
+    }
+    match required.maximum {
+        Some(maximum) if major > maximum => major - maximum,
+        _ => 0,
+    }
+}
+
+/// 从候选里挑一个：先按「离要求多远」，同距离再按来源优先序。
+///
+/// 探不到主版本号的候选排最后（不知道就不能算“近”）。
+#[must_use]
+pub fn pick<'a>(
+    candidates: &'a [JavaRuntime],
+    required: &JavaRequirement,
+) -> Option<&'a JavaRuntime> {
+    candidates.iter().min_by_key(|runtime| {
+        let distance = runtime
+            .major
+            .map_or(u32::MAX, |major| distance(major, required));
+        // 先排「距离远」，再排来源优先序（托管 > JAVA_HOME > PATH）。
+        (distance, runtime.origin.rank())
+    })
+}
+
+/// 启动前的取舍（D4）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum LaunchVerdict {
+    /// 照常启动（满足要求，或用户显式指定了 Java——那是他的明确选择）。
+    Proceed,
+    /// 拦下：不满足要求且没人明确指定，起不来是必然的，那句警告没有信息量。
+    Block(JavaMismatch),
+}
+
+impl LaunchVerdict {
+    /// 需要拦下时返回不符说明。
+    #[must_use]
+    pub fn block(self) -> Option {
+        match self {
+            Self::Proceed => None,
+            Self::Block(mismatch) => Some(mismatch),
+        }
+    }
+}
+
+/// 不满足要求时是「只告警」还是「拦住」（D4 的取舍，理由见 [`LaunchVerdict`]）。
+///
+/// 判据只有两条：不符的方向不重要（两个方向都必然起不来），**是不是用户自己选的**才重要。
+#[must_use]
+pub fn decide(mismatch: Option, explicitly_chosen: bool) -> LaunchVerdict {
+    match mismatch {
+        Some(mismatch) if !explicitly_chosen => LaunchVerdict::Block(mismatch),
+        _ => LaunchVerdict::Proceed,
+    }
+}
+
+/// 挑 + 判不符。
+#[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::{decide, distance, resolve, LaunchVerdict};
+    use crate::game::java::mapping::{JavaMismatch, 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 unsatisfiable_candidates_are_ranked_by_distance_not_by_origin() {
+        // 1.12.2（min=max=8）：托管的 25 与 JAVA_HOME 的 17 都不满足要求。
+        // 按来源排会选托管 25（rank 1 < 2），按版本距离应选 17（距离 9 vs 17）。
+        let required = JavaRequirement::new(8, Some(8), RequirementSource::Table);
+        let candidates = [
+            runtime(25, JavaOrigin::Managed),
+            runtime(17, JavaOrigin::JavaHome),
+        ];
+        assert_eq!(
+            resolve(&candidates, &required).major(),
+            17,
+            "全不满足时应按版本距离选 17，而不是按来源选托管的 25"
+        );
+    }
+
+    #[test]
+    fn too_old_candidates_are_ranked_by_distance() {
+        // 需要 21+：托管 8 与 JAVA_HOME 17 都太老（距离 13 vs 4）。
+        let candidates = [
+            runtime(8, JavaOrigin::Managed),
+            runtime(17, JavaOrigin::JavaHome),
+        ];
+        assert_eq!(
+            resolve(&candidates, &at_least(21)).major(),
+            17,
+            "都太老时应选最接近的那个，而不是托管目录里最老的那个"
+        );
+    }
+
+    #[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");
+    }
+
+    #[test]
+    fn distance_is_zero_inside_the_interval_and_positive_outside() {
+        let legacy = JavaRequirement::new(8, Some(8), RequirementSource::Table);
+        assert_eq!(distance(8, &legacy), 0);
+        assert_eq!(distance(17, &legacy), 9);
+        assert_eq!(distance(25, &legacy), 17);
+        let modern = at_least(21);
+        assert_eq!(distance(21, &modern), 0);
+        assert_eq!(distance(25, &modern), 0);
+        assert_eq!(distance(17, &modern), 4);
+        // 区间 8–16（假想）：16 与 9 都满足，只有 17 超出一档。
+        let band = JavaRequirement::new(8, Some(16), RequirementSource::Table);
+        assert_eq!(distance(16, &band), 0);
+        assert_eq!(distance(17, &band), 1);
+    }
+
+    #[test]
+    fn unknown_majors_rank_last() {
+        let mut unknown = runtime(17, JavaOrigin::Managed);
+        unknown.major = None;
+        let candidates = [unknown, runtime(25, JavaOrigin::JavaHome)];
+        let picked = resolve(&candidates, &at_least(21));
+        assert_eq!(
+            picked.runtime.map(|runtime| runtime.major),
+            Some(Some(25)),
+            "探不到主版本号的候选不能因为来源排名高就胜出"
+        );
+    }
+
+    #[test]
+    fn mismatch_blocks_only_when_nobody_chose_that_java() {
+        let mismatch = JavaMismatch::TooNew {
+            maximum: 8,
+            actual: 17,
+        };
+        assert_eq!(
+            decide(Some(mismatch), false),
+            LaunchVerdict::Block(mismatch)
+        );
+        assert_eq!(decide(Some(mismatch), true), LaunchVerdict::Proceed);
+        assert_eq!(decide(None, false), LaunchVerdict::Proceed);
+        assert_eq!(LaunchVerdict::Proceed.block(), None);
+        assert_eq!(LaunchVerdict::Block(mismatch).block(), Some(mismatch));
+        // 太老同样拦：装错方向不会改变「起不来」这个结局。
+        let too_old = JavaMismatch::TooOld {
+            required: 21,
+            actual: 17,
+        };
+        assert_eq!(decide(Some(too_old), false).block(), Some(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..a463a84
--- /dev/null
+++ b/crates/core/src/game/java/source.rs
@@ -0,0 +1,204 @@
+//! 版本查询的发行版分派 + 回退链记录（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 {
+    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
+        }
+        JdkVendor::Termux => Err(JavaError::new(
+            super::error::JavaErrorKind::Unsupported,
+            "Termux 的 JDK 由系统包管理器安装，不走归档下载链",
+        )
+        .with_hint("在 Termux 里用 `ull java install `（默认走 termux 源）")),
+    }
+}
+
+/// 一跳的结果。
+#[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,
+}
+
+impl ChainLog {
+    /// 空记录。
+    #[must_use]
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// 记一次「跳过」（该家不支持这个大版本，根本没查网络）。
+    pub fn skip(&mut self, vendor: JdkVendor, detail: impl Into) {
+        self.attempts.push(VendorAttempt {
+            vendor,
+            ok: false,
+            detail: detail.into(),
+        });
+    }
+
+    /// 记一次失败（查到了但拿不到、或下载/校验失败）。
+    pub fn failed(&mut self, vendor: JdkVendor, detail: impl Into) {
+        self.attempts.push(VendorAttempt {
+            vendor,
+            ok: false,
+            detail: detail.into(),
+        });
+    }
+
+    /// 记一次命中。
+    pub fn hit(&mut self, vendor: JdkVendor, detail: impl Into) {
+        self.attempts.push(VendorAttempt {
+            vendor,
+            ok: true,
+            detail: detail.into(),
+        });
+    }
+
+    /// 是否已经命中（命中后不再往下试）。
+    #[must_use]
+    pub fn hit_vendor(&self) -> Option {
+        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 {
+        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::>(),
+        })
+    }
+}
+
+#[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/staged.rs b/crates/core/src/game/java/staged.rs
new file mode 100644
index 0000000..c4e7f86
--- /dev/null
+++ b/crates/core/src/game/java/staged.rs
@@ -0,0 +1,347 @@
+//! 带进度与取消的 Java 扫描（M175）：**先收集候选、再逐个探测**。
+//!
+//! 为什么不能直接调 [`super::discover::candidates_in_roots`]：那条路把「收集」与「探测」揉在一起，
+//! 一个 JDK 跑一次 `java -version`（几十到几百毫秒），一台装了七八个 JDK 的机器上整段要几秒。
+//! 设置页要的是**能显示 3/7、能中途取消、且不卡住 UI**——于是这里把两段拆开：
+//!
+//! ```text
+//! candidates(roots, manual, system)   纯文件系统，快、无子进程
+//!   → scan(&candidates, on_progress, cancelled)  逐个探测；任一回调说停就停
+//! ```
+//!
+//! 判据与 [`super::discover`] 一致（同一套去重键、同一套标准位置），差别只有「可观测」这一层——
+//! 所以 `ull java list` 与设置页看到的是同一批 JDK。
+
+use std::path::PathBuf;
+
+use super::discover::{self, path_key};
+use super::extract::{java_binary_name, read_stamp};
+use super::probe::{self, JavaOrigin, JavaRuntime};
+use super::vendor::JdkVendor;
+
+/// 候选来源（比 [`JavaOrigin`] 多一个「用户手动加的」，UI 也按它分组）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Source {
+    /// 托管目录（`ull java install` 装的）
+    Managed,
+    /// `JAVA_HOME`
+    JavaHome,
+    /// `PATH` 上的 `java`
+    Path,
+    /// 标准安装位置（Program Files 系 / 官方启动器 runtime / 注册表 / `/usr/lib/jvm`）
+    System,
+    /// 用户在设置页手动指的路径
+    Manual,
+}
+
+impl Source {
+    /// 稳定 id（DTO / UI 文案选档用）。
+    #[must_use]
+    pub const fn id(self) -> &'static str {
+        match self {
+            Self::Managed => "managed",
+            Self::JavaHome => "env",
+            Self::Path => "path",
+            Self::System => "system",
+            Self::Manual => "manual",
+        }
+    }
+
+    /// 展示优先级（小者先；与 [`JavaOrigin::rank`] 同序，手动路径排在系统安装之前——
+    /// 用户亲手指的是明确的意图）。
+    #[must_use]
+    pub const fn rank(self) -> u8 {
+        match self {
+            Self::Managed => 1,
+            Self::JavaHome => 2,
+            Self::Path => 3,
+            Self::Manual => 4,
+            Self::System => 5,
+        }
+    }
+
+    /// 探测时用的 [`JavaOrigin`]（`JavaOrigin` 没有「手动」这一档，用 `System` 承接下来即可：
+    /// 展示走本枚举的 [`Source::id`]，不看 `JavaRuntime.origin`）。
+    #[must_use]
+    pub const fn origin(self) -> JavaOrigin {
+        match self {
+            Self::Managed => JavaOrigin::Managed,
+            Self::JavaHome => JavaOrigin::JavaHome,
+            Self::Path => JavaOrigin::Path,
+            Self::System | Self::Manual => JavaOrigin::System,
+        }
+    }
+}
+
+/// 一个待探测的候选。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Candidate {
+    /// `bin/java[.exe]` 的绝对路径
+    pub binary: PathBuf,
+    /// 来源
+    pub source: Source,
+}
+
+/// 收集候选（**不探测**，所以很快；目录不存在一律跳过）。
+///
+/// `system = false` 用于测试与「只看托管区」的场景：它跳过 `JAVA_HOME`/`PATH`/标准位置，
+/// 于是同一份输入在任何机器上得到同一份候选表（不依赖本机装了什么）。
+#[must_use]
+pub fn candidates(managed_roots: &[PathBuf], manual: &[PathBuf], system: bool) -> Vec {
+    let mut out: Vec = Vec::new();
+    for root in managed_roots {
+        out.extend(managed_in(root));
+    }
+    // 手动路径：目录 → `bin/java`；文件原样（用户在输入框里粘过两种形态，都认）。
+    for path in manual {
+        let binary = if path.is_dir() {
+            path.join("bin").join(java_binary_name())
+        } else {
+            path.clone()
+        };
+        if binary.is_file() {
+            out.push(Candidate {
+                binary,
+                source: Source::Manual,
+            });
+        }
+    }
+    if system {
+        out.extend(env_candidates());
+        out.extend(
+            discover::scan_java_binaries()
+                .into_iter()
+                .map(|binary| Candidate {
+                    binary,
+                    source: Source::System,
+                }),
+        );
+    }
+    dedupe(out)
+}
+
+/// 托管安装根里的候选（两种布局都认，**必须有戳记**——没戳记的目录可能是用户塞的别的东西）。
+fn managed_in(root: &std::path::Path) -> Vec {
+    let mut found = Vec::new();
+    let Ok(entries) = std::fs::read_dir(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(binary) = stamped_binary(&path) {
+            found.push(Candidate {
+                binary,
+                source: Source::Managed,
+            });
+            continue;
+        }
+        // 两层布局 `/`：厂商名取自父目录名。
+        if JdkVendor::parse(&name).is_some() {
+            let Ok(children) = std::fs::read_dir(&path) else {
+                continue;
+            };
+            for child in children.flatten() {
+                if let Some(binary) = stamped_binary(&child.path()) {
+                    found.push(Candidate {
+                        binary,
+                        source: Source::Managed,
+                    });
+                }
+            }
+        }
+    }
+    found
+}
+
+/// 带戳记、且 `bin/java[.exe]` 在盘上的托管目录。
+fn stamped_binary(dir: &std::path::Path) -> Option {
+    if !dir.is_dir() || read_stamp(dir).is_none() {
+        return None;
+    }
+    let binary = dir.join("bin").join(java_binary_name());
+    binary.is_file().then_some(binary)
+}
+
+/// `JAVA_HOME` 与 `PATH`（与 [`discover::candidates_in_roots`] 同一口径）。
+fn env_candidates() -> Vec {
+    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(Candidate {
+                binary,
+                source: Source::JavaHome,
+            });
+        }
+    }
+    if let Some(binary) = probe::resolve_on_path(java_binary_name()) {
+        found.push(Candidate {
+            binary,
+            source: Source::Path,
+        });
+    }
+    found
+}
+
+/// 按路径去重，保留**先出现**的（调用方按优先级排好序）。
+fn dedupe(candidates: Vec) -> Vec {
+    let mut seen: Vec = Vec::with_capacity(candidates.len());
+    let mut kept = Vec::with_capacity(candidates.len());
+    for candidate in candidates {
+        let key = path_key(&candidate.binary);
+        if seen.contains(&key) {
+            continue;
+        }
+        seen.push(key);
+        kept.push(candidate);
+    }
+    kept
+}
+
+/// 逐个探测。`on_progress(done, total)` 返回 `false` ⇒ 立刻停（取消），已探测的照样返回。
+///
+/// `cancelled()` 在一次探测**进行中**也会被查询：卡住的候选会被 [`super::proc::PROBE_TIMEOUT`]
+/// 或取消打断，而不是把扫描线程钉死在一个 `-version` 上（见 [`super::proc::run_with_timeout`]）。
+///
+/// 返回的列表按**大版本升序、同版本按路径**排序，探测不出主版本的排在最后
+/// （与 [`super::probe::discover_managed`] 的排序口径一致，用户看到的第一行不该是「版本未知」）。
+#[must_use]
+pub fn scan(
+    candidates: &[Candidate],
+    mut on_progress: F,
+    cancelled: &dyn Fn() -> bool,
+) -> Vec
+where
+    F: FnMut(usize, usize) -> bool,
+{
+    let total = candidates.len();
+    let mut found: Vec = Vec::with_capacity(total);
+    for (index, candidate) in candidates.iter().enumerate() {
+        if cancelled() || !on_progress(index, total) {
+            break;
+        }
+        // 发行方要从**整段** `-version` 输出里认（首行只有 `openjdk version "…"`，品牌在第二行）。
+        // 超时与取消都交给这一层：卡住的子进程会被 kill，取消不必等它自己结束。
+        let (runtime, _output) = super::manual::probe_with_timeout(
+            &candidate.binary,
+            candidate.source.origin(),
+            super::proc::PROBE_TIMEOUT,
+            cancelled,
+        );
+        found.push(runtime);
+    }
+    found.sort_by(|left, right| {
+        left.major
+            .unwrap_or(u32::MAX)
+            .cmp(&right.major.unwrap_or(u32::MAX))
+            .then_with(|| left.binary.cmp(&right.binary))
+    });
+    found
+}
+
+/// 候选 + 扫描一步到位（不与 UI 打交道的调用方用；设置页走两段式）。
+#[must_use]
+pub fn scan_roots(managed_roots: &[PathBuf], manual: &[PathBuf], system: bool) -> Vec {
+    let list = candidates(managed_roots, manual, system);
+    scan(&list, |_, _| true, &|| false)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn temp(tag: &str) -> PathBuf {
+        let dir = std::env::temp_dir().join(format!(
+            "ull-java-staged-{tag}-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .map(|d| d.as_nanos())
+                .unwrap_or(0)
+        ));
+        let _ = std::fs::remove_dir_all(&dir);
+        std::fs::create_dir_all(&dir).expect("临时目录");
+        dir
+    }
+
+    /// 造一个「看起来像 JDK」的目录（`bin/java` 是空文件 ⇒ 探测出「版本未知」，
+    /// 但它确实被扫到了——这正是「列表来自真实扫描」要的证据）。
+    fn fake_jdk(root: &std::path::Path, name: &str) -> PathBuf {
+        let dir = root.join(name);
+        std::fs::create_dir_all(dir.join("bin")).expect("bin");
+        std::fs::write(dir.join("bin").join(java_binary_name()), b"").expect("写 java");
+        dir
+    }
+
+    #[test]
+    fn the_list_comes_from_the_disk_not_from_a_constant() {
+        let root = temp("list");
+        let one = fake_jdk(&root, "jdk-a");
+        let two = fake_jdk(&root, "jdk-b");
+
+        let found = scan_roots(&[], &[one.clone(), two.clone()], false);
+        assert_eq!(found.len(), 2, "两个假 JDK 目录必须扫出两项：{found:?}");
+        assert!(found
+            .iter()
+            .any(|runtime| runtime.binary == one.join("bin").join(java_binary_name())));
+
+        // 删掉一个：列表必须少一项（证明它读的是盘，不是写死的字符串）。
+        std::fs::remove_dir_all(&one).expect("删 jdk-a");
+        let after = scan_roots(&[], &[one, two], false);
+        assert_eq!(after.len(), 1, "删掉一个 JDK 之后列表必须少一项：{after:?}");
+
+        std::fs::remove_dir_all(&root).ok();
+    }
+
+    #[test]
+    fn a_managed_directory_without_a_stamp_is_not_claimed() {
+        let root = temp("stamp");
+        // 长得像托管目录，但没有戳记 ⇒ 不是我们装的，不去猜。
+        fake_jdk(&root, "jdk-21-temurin");
+        let found = scan_roots(std::slice::from_ref(&root), &[], false);
+        assert!(found.is_empty(), "无戳记目录不该被认领：{found:?}");
+        std::fs::remove_dir_all(&root).ok();
+    }
+
+    #[test]
+    fn progress_reports_every_candidate_and_cancel_stops_early() {
+        let root = temp("progress");
+        let paths: Vec = (0..3)
+            .map(|n| fake_jdk(&root, &format!("jdk-{n}")))
+            .collect();
+        let list = candidates(&[], &paths, false);
+        assert_eq!(list.len(), 3);
+
+        let mut seen = Vec::new();
+        let all = scan(
+            &list,
+            |done, total| {
+                seen.push((done, total));
+                true
+            },
+            &|| false,
+        );
+        assert_eq!(seen, vec![(0, 3), (1, 3), (2, 3)], "每个候选都要报一次进度");
+        assert_eq!(all.len(), 3);
+
+        let stopped = scan(&list, |done, _| done < 1, &|| false);
+        assert_eq!(stopped.len(), 1, "取消之后只留已探测的那一项");
+
+        std::fs::remove_dir_all(&root).ok();
+    }
+
+    #[test]
+    fn candidates_dedupe_the_same_jdk_written_two_ways() {
+        let root = temp("dedupe");
+        let jdk = fake_jdk(&root, "jdk-x");
+        let binary = jdk.join("bin").join(java_binary_name());
+        // 同一份 JDK 用「目录」和「可执行文件」两种写法各登记一次。
+        let list = candidates(&[], &[jdk, binary], false);
+        assert_eq!(list.len(), 1, "同一路径只列一次：{list:?}");
+        std::fs::remove_dir_all(&root).ok();
+    }
+}
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 {
+        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 ` 挑已有 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 ` 挑已有 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/termux.rs b/crates/core/src/game/java/termux.rs
new file mode 100644
index 0000000..03c1661
--- /dev/null
+++ b/crates/core/src/game/java/termux.rs
@@ -0,0 +1,257 @@
+//! Termux 系统 JDK（`openjdk-` 包）的安装与定位。
+//!
+//! Termux 的 openjdk 是 `.deb`（bionic），由 apt/dpkg 装进 `$PREFIX`，与 Temurin 的
+//! zip/tar.gz 归档不是同一形态，所以**不走** `source::fetch` 的归档链。这里委托包管理器：
+//!
+//! 1. 用内置镜像生成一份**隔离**的 sources.list；
+//! 2. `apt-get update && install` 的 lists/cache 都指向临时目录，不污染用户的 apt 状态；
+//! 3. 装完在 `$PREFIX/lib/jvm` 下找 `java--openjdk`，用 `bin/java` 是否存在做判据。
+//!
+//! 镜像顺序是实测可用的国内源；全部失败才报错，错误里带每一跳的原因。
+
+use std::path::{Path, PathBuf};
+
+use crate::platform::child::quiet;
+use crate::platform::paths::ProcessEnv;
+use crate::platform::termux as host;
+
+use super::error::{JavaError, JavaErrorKind};
+
+/// 内置镜像（termux-main 仓库根）。顺序即尝试顺序。
+pub const MIRRORS: &[&str] = &[
+    "https://mirrors.sau.edu.cn/termux/apt/termux-main",
+    "https://mirrors.tuna.tsinghua.edu.cn/termux/apt/termux-main",
+    "https://mirrors.ustc.edu.cn/termux/apt/termux-main",
+    "https://packages.termux.dev/apt/termux-main",
+];
+
+/// 当前宿主是不是 Termux。
+#[must_use]
+pub fn available() -> bool {
+    host::is_termux(&ProcessEnv)
+}
+
+/// 大版本 → Termux 包名（主源只有 17 / 21 / 25）。
+#[must_use]
+pub fn package_for(major: u32) -> Option {
+    matches!(major, 17 | 21 | 25).then(|| format!("openjdk-{major}"))
+}
+
+/// `$PREFIX/lib/jvm` 下与 `major` 对应的 JDK 根（`bin/java` 必须存在）。
+#[must_use]
+pub fn installed_home(prefix: &Path, major: u32) -> Option {
+    let root = prefix.join("lib").join("jvm");
+    let entries = std::fs::read_dir(root).ok()?;
+    let dashed = format!("java-{major}-openjdk");
+    let plain = format!("openjdk-{major}");
+    let mut found: Vec = entries
+        .flatten()
+        .map(|entry| entry.path())
+        .filter(|path| path.is_dir() && path.join("bin").join("java").is_file())
+        .filter(|path| {
+            path.file_name()
+                .and_then(|name| name.to_str())
+                .is_some_and(|name| name == dashed || name == plain)
+        })
+        .collect();
+    found.sort();
+    found.into_iter().next()
+}
+
+/// 一条 `deb` 行（测试与安装共用同一份拼法）。
+#[must_use]
+pub fn sources_line(mirror: &str) -> String {
+    format!("deb {} stable main\n", mirror.trim_end_matches('/'))
+}
+
+/// 装一个 Termux JDK，返回它的根目录。
+///
+/// # Errors
+///
+/// 当前不在 Termux、主源没有该大版本、所有镜像都失败、装完仍找不到 `bin/java` 时返回错误。
+///
+/// 返回 `(JDK 根, 是否复用了已装)`：包管理器刚装完与「本来就有」对调用方是两种结果
+/// （一个要报安装，一个要报「未走网络」）。
+pub async fn install(major: u32) -> Result<(PathBuf, bool), JavaError> {
+    let Some(package) = package_for(major) else {
+        return Err(JavaError::new(
+            JavaErrorKind::Unsupported,
+            format!("Termux 主源没有 Java {major}（只有 17 / 21 / 25）"),
+        )
+        .with_hint("`pkg search openjdk` 看可用包；其它大版本请用归档发行版"));
+    };
+    let Some(prefix) = host::prefix(&ProcessEnv) else {
+        return Err(
+            JavaError::new(JavaErrorKind::Unsupported, "termux 源只在 Termux 里可用")
+                .with_hint("普通 Linux/Windows 用 Temurin / Oracle / MS / Zulu"),
+        );
+    };
+
+    // 幂等：已经装了同一大版本就不碰网络。
+    if let Some(home) = installed_home(&prefix, major) {
+        return Ok((home, true));
+    }
+
+    let workspace = workspace_dir(&prefix, major);
+    std::fs::create_dir_all(&workspace).map_err(|error| {
+        JavaError::new(
+            JavaErrorKind::Io,
+            format!(
+                "建 Termux 安装临时目录失败（{}）：{error}",
+                workspace.display()
+            ),
+        )
+    })?;
+
+    let package_for_task = package.clone();
+    tokio::task::spawn_blocking(move || run_install(&prefix, &workspace, &package_for_task, major))
+        .await
+        .map_err(|error| {
+            JavaError::new(
+                JavaErrorKind::Io,
+                format!("Termux 安装任务没能完成：{error}"),
+            )
+        })?
+        .map(|home| (home, false))
+}
+
+/// 逐镜像尝试 `apt-get`（阻塞，跑在 `spawn_blocking` 里）。
+fn run_install(
+    prefix: &Path,
+    workspace: &Path,
+    package: &str,
+    major: u32,
+) -> Result {
+    let mut failures: Vec = Vec::new();
+    for mirror in MIRRORS {
+        match apt_install(prefix, workspace, mirror, package) {
+            Ok(()) => {
+                if let Some(home) = installed_home(prefix, major) {
+                    // 装完把隔离的 lists/cache/archives 清掉（几十到上百 MB，别留在 $PREFIX/tmp）。
+                    let _ = std::fs::remove_dir_all(workspace);
+                    return Ok(home);
+                }
+                failures.push(format!("{mirror}：装完找不到 bin/java"));
+            }
+            Err(error) => failures.push(format!("{mirror}：{error}")),
+        }
+    }
+    Err(JavaError::new(
+        JavaErrorKind::Network,
+        format!(
+            "Termux 包安装失败（试过 {} 个镜像）：{}",
+            MIRRORS.len(),
+            failures.join("；")
+        ),
+    )
+    .with_hint("确认 apt 可用、磁盘空间足够，或手动 `pkg install openjdk-`"))
+}
+
+/// 对单个镜像跑 `apt-get update` + `install`（lists/cache 隔离在 workspace 内）。
+fn apt_install(prefix: &Path, workspace: &Path, mirror: &str, package: &str) -> Result<(), String> {
+    let sources = workspace.join("sources.list");
+    std::fs::write(&sources, sources_line(mirror))
+        .map_err(|error| format!("写 sources.list 失败：{error}"))?;
+
+    let lists = workspace.join("lists");
+    let cache = workspace.join("cache");
+    let archives = workspace.join("archives");
+    for dir in [&lists, &cache, &archives] {
+        std::fs::create_dir_all(dir).map_err(|error| format!("建临时目录失败：{error}"))?;
+    }
+
+    let options = [
+        format!("Dir::Etc::sourcelist={}", sources.display()),
+        "Dir::Etc::sourceparts=-".to_string(),
+        format!("Dir::State::lists={}", lists.display()),
+        format!("Dir::Cache={}", cache.display()),
+        format!("Dir::Cache::archives={}", archives.display()),
+        "Acquire::ForceIPv4=true".to_string(),
+        "Acquire::Retries=2".to_string(),
+        "Acquire::http::Timeout=30".to_string(),
+        "Acquire::https::Timeout=30".to_string(),
+    ];
+
+    run_apt(prefix, &options, &["update"])?;
+    run_apt(
+        prefix,
+        &options,
+        &["install", "-y", "--no-install-suggests", package],
+    )
+}
+
+/// 执行一次 `apt-get`（`-o` 选项在前，子命令在后）。
+fn run_apt(prefix: &Path, options: &[String], args: &[&str]) -> Result<(), String> {
+    let apt = prefix.join("bin").join("apt-get");
+    let mut command = quiet(&apt);
+    command.env("DEBIAN_FRONTEND", "noninteractive");
+    for option in options {
+        command.arg("-o").arg(option);
+    }
+    command.args(args);
+    let output = command
+        .output()
+        .map_err(|error| format!("执行 {} 失败：{error}", apt.display()))?;
+    if output.status.success() {
+        return Ok(());
+    }
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    let last = stderr
+        .lines()
+        .rev()
+        .find(|line| !line.trim().is_empty())
+        .unwrap_or("（无 stderr 输出）");
+    Err(format!(
+        "apt-get {} 退出 {}：{last}",
+        args.first().copied().unwrap_or("?"),
+        output.status.code().unwrap_or(-1)
+    ))
+}
+
+/// 临时工作区（按大版本区分，避免两次安装互相踩 lists）。
+fn workspace_dir(prefix: &Path, major: u32) -> PathBuf {
+    prefix
+        .join("tmp")
+        .join("ull-java-termux")
+        .join(format!("jdk-{major}"))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{installed_home, package_for, sources_line, MIRRORS};
+
+    #[test]
+    fn only_the_majors_that_termux_ships_are_installable() {
+        assert_eq!(package_for(17).as_deref(), Some("openjdk-17"));
+        assert_eq!(package_for(21).as_deref(), Some("openjdk-21"));
+        assert_eq!(package_for(25).as_deref(), Some("openjdk-25"));
+        assert_eq!(package_for(8), None);
+        assert_eq!(package_for(11), None);
+    }
+
+    #[test]
+    fn sources_line_has_one_deb_and_keeps_the_mirror_root() {
+        let line = sources_line("https://mirrors.tuna.tsinghua.edu.cn/termux/apt/termux-main/");
+        assert_eq!(
+            line,
+            "deb https://mirrors.tuna.tsinghua.edu.cn/termux/apt/termux-main stable main\n"
+        );
+        assert!(MIRRORS.iter().all(|mirror| mirror.starts_with("https://")));
+    }
+
+    #[test]
+    fn installed_home_requires_bin_java_and_matching_major() {
+        let base = std::env::temp_dir().join(format!("ull-termux-home-{}", std::process::id()));
+        let good = base.join("lib").join("jvm").join("java-21-openjdk");
+        let empty = base.join("lib").join("jvm").join("java-17-openjdk");
+        std::fs::create_dir_all(good.join("bin")).unwrap();
+        std::fs::write(good.join("bin").join("java"), b"").unwrap();
+        std::fs::create_dir_all(&empty).unwrap();
+
+        assert_eq!(installed_home(&base, 21), Some(good));
+        assert_eq!(installed_home(&base, 17), None, "没有 bin/java 的目录不算");
+        assert_eq!(installed_home(&base, 25), None);
+
+        std::fs::remove_dir_all(&base).ok();
+    }
+}
diff --git a/crates/core/src/game/java/vendor.rs b/crates/core/src/game/java/vendor.rs
new file mode 100644
index 0000000..31c9a4f
--- /dev/null
+++ b/crates/core/src/game/java/vendor.rs
@@ -0,0 +1,235 @@
+//! 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` 的允许值（顺序即默认序的覆盖来源）。
+///
+/// `termux` 只在 Termux 宿主上可用（系统包管理器安装），默认序里不出现；
+/// 显式写进优先级或 `--vendor termux` 才走它。
+pub const VENDOR_IDS: &[&str] = &["temurin", "oracle", "microsoft", "zulu", "termux"];
+
+/// 一家 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,
+    /// Termux 的系统 openjdk（`pkg install openjdk-`；只在 Termux 里可用）。
+    Termux,
+}
+
+impl JdkVendor {
+    /// 全部发行版（枚举顺序，不是优先级顺序）。
+    pub const ALL: [Self; 5] = [
+        Self::Temurin,
+        Self::Oracle,
+        Self::Microsoft,
+        Self::Zulu,
+        Self::Termux,
+    ];
+
+    /// 稳定 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",
+            Self::Termux => "termux",
+        }
+    }
+
+    /// 展示名（人读输出 + `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",
+            Self::Termux => "Termux OpenJDK",
+        }
+    }
+
+    /// 解析 `--vendor` / 设置值（容忍常见别名，大小写不敏感）。
+    #[must_use]
+    pub fn parse(text: &str) -> Option {
+        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),
+            "termux" | "termux-openjdk" | "pkg" => Some(Self::Termux),
+            _ => 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),
+            Self::Termux => matches!(major, 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],
+            Self::Termux => &[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 {
+    let mut out: Vec = 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 {
+    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,
+    /// 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::>()
+            .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 {
+    let packages: Vec = 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 {
+    #[derive(Deserialize)]
+    struct Detail {
+        #[serde(default)]
+        sha256_hash: Option,
+    }
+    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 {
+    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("502").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/launch_overrides.rs b/crates/core/src/game/launch_overrides.rs
new file mode 100644
index 0000000..d6708ae
--- /dev/null
+++ b/crates/core/src/game/launch_overrides.rs
@@ -0,0 +1,360 @@
+//! 实例级启动参数覆盖（五项）+ **三级回落**（实例 → 全局 → 默认）。
+//!
+//! 依据：M157 的定案（叠加/冲突规则见该 mission 的 notes；用户 2026-11-07 拍板实例配置页
+//! 支持启动参数，含 MC 26.2+ 的 `--graphicsBackend vulkan`）。
+//!
+//! # 为什么是「五项全 Option」
+//!
+//! 每个字段独立回落：只填了内存的实例不能把全局 JVM 参数一起顶掉。`None`（或空白字符串）
+//! = 这一项跟随下一层，与 D20 的 `isolation` 同一套稀疏语义（[`super::install::instance`]）。
+//!
+//! # 键名为什么叫 `launch` 而不是 `overrides`
+//!
+//! `overrides` 已经被 D20 占用（`["maxMemory", "javaType", "runningDirectory"]` 这份
+//! 「该实例覆盖了哪些全局键」的清单），抢占会让存量实例文件的语义漂移。五项**取值**段落
+//! 落在 `launch` 对象里，互不干扰。
+//!
+//! # 三级回落逐项（**不是整段覆盖**）
+//!
+//! | 字段 | 实例层 | 全局层 | 出厂默认 |
+//! |---|---|---|---|
+//! | `jvmArgs` | `launch.jvmArgs` | `java.extra_args` | 空 |
+//! | `gameArgs` | `launch.gameArgs` | （无全局键，留 `None`） | 空 |
+//! | `memoryMb` | `launch.memoryMb` | `java.default_memory_mb` | [`DEFAULT_MAX_MEMORY_MB`] |
+//! | `javaPath` | `launch.javaPath` | `java.selected_path` | 自动挑（托管 > JAVA_HOME > PATH） |
+//! | `graphicsBackend` | `launch.graphicsBackend` | （无全局键，留 `None`） | `default` |
+//!
+//! `jvmArgs` 是**追加**而不是替换：全局是基线（进组装表第 7 项 `user.jvm`），实例是精调
+//! （进第 4 项 `user.override_jvm`），两者都下发，同名选项 JVM 取后出现者 ⇒ 实例赢。
+//! 落位实现在 [`crate::launch::overrides`]，本文件只给**生效值**（纯计算、零 IO）。
+//!
+//! # 越界的内存值不算「覆盖」
+//!
+//! 手改文件能绕过 schema 校验，所以 `memoryMb` 在这个模块里也过一遍范围：
+//! 越界 ⇒ 当作没填（落到下一层），而不是拿 `-Xmx0m` 去把 JVM 启动弄崩。判据与
+//! `setting::instance_keys` 登记的区间同源（[`MIN_MAX_MEMORY_MB`] / [`MAX_MAX_MEMORY_MB`]）。
+
+use std::path::PathBuf;
+
+use serde::{Deserialize, Serialize};
+
+/// 出厂默认最大堆（MiB）：与 `setting::keys` 的 `java.default_memory_mb` 默认值一致。
+pub const DEFAULT_MAX_MEMORY_MB: u32 = 2048;
+/// `memoryMb` 允许的下限（MiB）。
+pub const MIN_MAX_MEMORY_MB: u32 = 256;
+/// `memoryMb` 允许的上限（MiB）。
+pub const MAX_MAX_MEMORY_MB: u32 = 65536;
+
+/// 图形后端三态（任务书：默认 / OpenGL / Vulkan）。
+///
+/// `Default` **不是**「交给 JVM 决定」的另一个参数，而是「不下发 `--graphicsBackend`」——
+/// 26.2 以前根本没有这个参数，下发即 `UnrecognizedOptionException`。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum GraphicsBackend {
+    /// 不下发（游戏按自己的默认后端启动）。
+    #[default]
+    Default,
+    /// `--graphicsBackend opengl`。
+    Opengl,
+    /// `--graphicsBackend vulkan`。
+    Vulkan,
+}
+
+impl GraphicsBackend {
+    /// 全部三态（顺序即 UI 下拉的展示顺序）。
+    pub const ALL: [Self; 3] = [Self::Default, Self::Opengl, Self::Vulkan];
+    /// 中文档位说明里的稳定 id 之一。
+    pub const IDS: [&'static str; 3] = ["default", "opengl", "vulkan"];
+
+    /// 稳定 id（`default` / `opengl` / `vulkan`；GUI 与 `--json` 同词表）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Default => "default",
+            Self::Opengl => "opengl",
+            Self::Vulkan => "vulkan",
+        }
+    }
+
+    /// 从稳定 id 解析；未知值返回 `None`（**调用方必须报错**，不许静默退化成 `default`）。
+    #[must_use]
+    pub fn parse(raw: &str) -> Option {
+        let wanted = raw.trim();
+        Self::ALL
+            .into_iter()
+            .find(|backend| backend.as_str().eq_ignore_ascii_case(wanted))
+    }
+
+    /// `--graphicsBackend` 的取值；`Default` = 不下发（`None`）。
+    #[must_use]
+    pub const fn flag_value(self) -> Option<&'static str> {
+        match self {
+            Self::Default => None,
+            Self::Opengl => Some("opengl"),
+            Self::Vulkan => Some("vulkan"),
+        }
+    }
+
+    /// 是否需要下发参数（`default` 不需要）。
+    #[must_use]
+    pub const fn is_default(self) -> bool {
+        matches!(self, Self::Default)
+    }
+}
+
+/// 实例级启动参数覆盖（`config/instances/.json` 的 `launch` 段）。
+///
+/// 稀疏：只写用户显式改过的项，键不存在即「跟随下一层」。
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", default)]
+pub struct LaunchOverrides {
+    /// 实例级 JVM 参数（空白分隔的文本，支持引号）；空 = 只用全局 `java.extra_args`。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub jvm_args: Option,
+    /// 实例级游戏参数（同上）；空 = 不追加。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub game_args: Option,
+    /// 最大堆（MiB）；空或越界 = 跟随全局 `java.default_memory_mb`。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub memory_mb: Option,
+    /// 实例级 Java 可执行文件；空 = 跟随全局 `java.selected_path` 再退到自动挑。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub java_path: Option,
+    /// 图形后端；空 = `default`（不下发 `--graphicsBackend`）。
+    ///
+    /// 反序列化对未知值**报错**（`unknown variant`），不静默落成 `default`。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub graphics_backend: Option,
+}
+
+impl LaunchOverrides {
+    /// 整段是否为空（序列化时用来决定 `launch` 键出不出现）。
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.normalized() == Self::default()
+    }
+
+    /// 归一：空白字符串与空路径当作没填（用户清空输入框 = 回到跟随）。
+    #[must_use]
+    pub fn normalized(&self) -> Self {
+        Self {
+            jvm_args: non_blank(self.jvm_args.as_deref()).map(str::to_string),
+            game_args: non_blank(self.game_args.as_deref()).map(str::to_string),
+            memory_mb: self.memory_mb.filter(|value| valid_memory(*value)),
+            java_path: self
+                .java_path
+                .as_ref()
+                .map(|path| path.display().to_string())
+                .filter(|text| !text.trim().is_empty())
+                .map(PathBuf::from),
+            graphics_backend: self.graphics_backend,
+        }
+    }
+
+    /// 生效的最大堆（已过范围校验；`None` = 这一层没给）。
+    #[must_use]
+    pub fn effective_memory_mb(&self) -> Option {
+        self.memory_mb.filter(|value| valid_memory(*value))
+    }
+}
+
+/// 全局层（`config/launcher.json` 里与启动参数相关的键）。
+///
+/// 读配置归调用方（CLI / presenter 的 host），本结构只承载**值**——`game` 不 import
+/// `setting`，回落规则才能纯函数化、可纯单测。
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct GlobalLaunchDefaults {
+    /// `java.extra_args`（基线 JVM 参数）。
+    pub jvm_args: Option,
+    /// 全局游戏参数（本轮没有对应设置键，留 `None` 占位，回落链照样逐项成立）。
+    pub game_args: Option,
+    /// `java.default_memory_mb`。
+    pub memory_mb: Option,
+    /// `java.selected_path`。
+    pub java_path: Option,
+    /// 全局图形后端（本轮没有对应设置键）。
+    pub graphics_backend: Option,
+}
+
+impl GlobalLaunchDefaults {
+    /// 只带 `java.extra_args` 的最小构造（测试/CLI 常用）。
+    #[must_use]
+    pub fn with_jvm_args(text: impl Into) -> Self {
+        Self {
+            jvm_args: Some(text.into()),
+            ..Self::default()
+        }
+    }
+}
+
+/// 三级回落之后的**生效值**（拼装链的输入，见 [`crate::launch::overrides::apply`]）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ResolvedLaunch {
+    /// 全局层 JVM 参数（组装表第 7 项，`None` = 没有）。
+    pub global_jvm_args: Option,
+    /// 实例层 JVM 参数（组装表第 4 项，最高优先级，`None` = 没有）。
+    pub instance_jvm_args: Option,
+    /// 游戏参数（第 32 项，最后追加）。
+    pub game_args: Option,
+    /// 生效最大堆（三级回落 + 范围校验 + 出厂默认，**恒有值**）。
+    pub memory_mb: u32,
+    /// 生效 Java 可执行文件；`None` = 调用方走自动挑。
+    pub java_path: Option,
+    /// 生效图形后端（`Default` = 不下发）。
+    pub graphics_backend: GraphicsBackend,
+}
+
+impl ResolvedLaunch {
+    /// 是否与「全默认」等价（测试与日志用）。
+    #[must_use]
+    pub fn is_defaults(&self) -> bool {
+        self.global_jvm_args.is_none()
+            && self.instance_jvm_args.is_none()
+            && self.game_args.is_none()
+            && self.memory_mb == DEFAULT_MAX_MEMORY_MB
+            && self.java_path.is_none()
+            && self.graphics_backend.is_default()
+    }
+}
+
+/// 三级回落：`instance` 为 `None`/空项一律落到 `global`，再落到出厂默认。
+#[must_use]
+pub fn resolve(
+    instance: Option<&LaunchOverrides>,
+    global: &GlobalLaunchDefaults,
+) -> ResolvedLaunch {
+    let instance = instance
+        .map(LaunchOverrides::normalized)
+        .unwrap_or_default();
+    let global = GlobalLaunchDefaults {
+        jvm_args: non_blank(global.jvm_args.as_deref()).map(str::to_string),
+        game_args: non_blank(global.game_args.as_deref()).map(str::to_string),
+        memory_mb: global.memory_mb.filter(|value| valid_memory(*value)),
+        java_path: global.java_path.clone(),
+        graphics_backend: global.graphics_backend,
+    };
+
+    ResolvedLaunch {
+        global_jvm_args: global.jvm_args,
+        instance_jvm_args: instance.jvm_args,
+        // gameArgs 是**替换**语义：实例给了就用实例的（全局层本轮恒空）。
+        game_args: instance.game_args.or(global.game_args),
+        memory_mb: instance
+            .memory_mb
+            .or(global.memory_mb)
+            .unwrap_or(DEFAULT_MAX_MEMORY_MB),
+        java_path: instance.java_path.or(global.java_path),
+        graphics_backend: instance
+            .graphics_backend
+            .or(global.graphics_backend)
+            .unwrap_or_default(),
+    }
+}
+
+/// 内存范围判据（与 `setting::instance_keys` 登记的区间同源）。
+#[must_use]
+pub fn valid_memory(mb: u32) -> bool {
+    (MIN_MAX_MEMORY_MB..=MAX_MAX_MEMORY_MB).contains(&mb)
+}
+
+/// 五项**文本**补丁（GUI 表单与 CLI 共用）：`None` = 这一项不改；`Some("")` = 清空回「跟随」。
+///
+/// 校验只在这里做一次（内存整数/范围、图形后端词表），两个调用端都拿同一条错误文案——
+/// 否则「GUI 说合法、CLI 说非法」这类两套真相迟早出现。
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct LaunchOverridesPatch {
+    /// 实例层 JVM 参数原文。
+    pub jvm_args: Option,
+    /// 实例层游戏参数原文。
+    pub game_args: Option,
+    /// 实例层最大堆（文本形态，见 [`MIN_MAX_MEMORY_MB`] / [`MAX_MAX_MEMORY_MB`]）。
+    pub memory_mb: Option,
+    /// 实例层 Java 可执行文件。
+    pub java_path: Option,
+    /// 实例层图形后端（`default` / `opengl` / `vulkan`）。
+    pub graphics_backend: Option,
+}
+
+impl LaunchOverridesPatch {
+    /// 只改图形后端（下拉切换的最小补丁）。
+    #[must_use]
+    pub fn backend(id: &str) -> Self {
+        Self {
+            graphics_backend: Some(id.to_string()),
+            ..Self::default()
+        }
+    }
+
+    /// 清空全部五项（`--clear` 的语义；随后可按需再给几项）。
+    #[must_use]
+    pub fn clear_all() -> Self {
+        Self {
+            jvm_args: Some(String::new()),
+            game_args: Some(String::new()),
+            memory_mb: Some(String::new()),
+            java_path: Some(String::new()),
+            graphics_backend: Some("default".to_string()),
+        }
+    }
+}
+
+impl LaunchOverrides {
+    /// 应用文本补丁：`None` 不动、空串清空；非法值**报错**（不静默丢弃）。
+    ///
+    /// # Errors
+    ///
+    /// 内存不是整数、越界，或图形后端不在 [`GraphicsBackend::IDS`] 里时返回用户可读文案。
+    pub fn patched(&self, patch: &LaunchOverridesPatch) -> Result {
+        let mut next = self.normalized();
+        if let Some(text) = &patch.jvm_args {
+            next.jvm_args = non_blank(Some(text)).map(str::to_string);
+        }
+        if let Some(text) = &patch.game_args {
+            next.game_args = non_blank(Some(text)).map(str::to_string);
+        }
+        if let Some(text) = &patch.memory_mb {
+            next.memory_mb = parse_memory(text)?;
+        }
+        if let Some(text) = &patch.java_path {
+            next.java_path = non_blank(Some(text)).map(PathBuf::from);
+        }
+        if let Some(text) = &patch.graphics_backend {
+            next.graphics_backend = match GraphicsBackend::parse(text) {
+                // `default` 是「不下发」而不是要落盘的覆盖值：清成 None（稀疏语义）。
+                Some(GraphicsBackend::Default) => None,
+                Some(backend) => Some(backend),
+                None => {
+                    return Err(format!(
+                        "无法识别的图形后端 `{text}`（只接受 {}）",
+                        GraphicsBackend::IDS.join(" / ")
+                    ))
+                }
+            };
+        }
+        Ok(next)
+    }
+}
+
+/// 内存文本 → `Option`（空 = 清空；非整数/越界 = 错）。
+fn parse_memory(text: &str) -> Result, String> {
+    let Some(text) = non_blank(Some(text)) else {
+        return Ok(None);
+    };
+    let value: u32 = text
+        .parse()
+        .map_err(|_| format!("内存需要是整数（MiB），收到 `{text}`"))?;
+    if !valid_memory(value) {
+        return Err(format!(
+            "内存超出范围（{MIN_MAX_MEMORY_MB}~{MAX_MAX_MEMORY_MB} MiB），收到 {value}"
+        ));
+    }
+    Ok(Some(value))
+}
+
+fn non_blank(text: Option<&str>) -> Option<&str> {
+    text.map(str::trim).filter(|value| !value.is_empty())
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/core/src/game/launch_overrides/tests.rs b/crates/core/src/game/launch_overrides/tests.rs
new file mode 100644
index 0000000..8268376
--- /dev/null
+++ b/crates/core/src/game/launch_overrides/tests.rs
@@ -0,0 +1,295 @@
+use super::*;
+
+fn instance_with(field: &str) -> LaunchOverrides {
+    match field {
+        "jvm" => LaunchOverrides {
+            jvm_args: Some("-XX:+UseG1GC".to_string()),
+            ..LaunchOverrides::default()
+        },
+        "game" => LaunchOverrides {
+            game_args: Some("--fullscreen".to_string()),
+            ..LaunchOverrides::default()
+        },
+        "memory" => LaunchOverrides {
+            memory_mb: Some(6144),
+            ..LaunchOverrides::default()
+        },
+        "java" => LaunchOverrides {
+            java_path: Some(PathBuf::from("D:/jdk21/bin/java.exe")),
+            ..LaunchOverrides::default()
+        },
+        "backend" => LaunchOverrides {
+            graphics_backend: Some(GraphicsBackend::Vulkan),
+            ..LaunchOverrides::default()
+        },
+        other => panic!("未知字段 {other}"),
+    }
+}
+
+fn global_with(field: &str) -> GlobalLaunchDefaults {
+    match field {
+        "jvm" => GlobalLaunchDefaults {
+            jvm_args: Some("-Xss4m".to_string()),
+            ..GlobalLaunchDefaults::default()
+        },
+        "game" => GlobalLaunchDefaults {
+            game_args: Some("--foo".to_string()),
+            ..GlobalLaunchDefaults::default()
+        },
+        "memory" => GlobalLaunchDefaults {
+            memory_mb: Some(3072),
+            ..GlobalLaunchDefaults::default()
+        },
+        "java" => GlobalLaunchDefaults {
+            java_path: Some(PathBuf::from("C:/jdk17/bin/java.exe")),
+            ..GlobalLaunchDefaults::default()
+        },
+        "backend" => GlobalLaunchDefaults {
+            graphics_backend: Some(GraphicsBackend::Opengl),
+            ..GlobalLaunchDefaults::default()
+        },
+        other => panic!("未知字段 {other}"),
+    }
+}
+
+/// **三级回落逐项**：五项各自走「实例 → 全局 → 默认」，一项不得连坐另一项。
+#[test]
+fn every_field_falls_back_on_its_own() {
+    for field in ["jvm", "game", "memory", "java", "backend"] {
+        // ① 实例有值 → 实例赢（jvm 例外：两层叠加，见下一条测试）。
+        let from_instance = resolve(
+            Some(&instance_with(field)),
+            &GlobalLaunchDefaults::default(),
+        );
+        let from_global = resolve(None, &global_with(field));
+        let neither = resolve(None, &GlobalLaunchDefaults::default());
+
+        match field {
+            "jvm" => {
+                assert_eq!(
+                    from_instance.instance_jvm_args.as_deref(),
+                    Some("-XX:+UseG1GC")
+                );
+                assert_eq!(from_global.global_jvm_args.as_deref(), Some("-Xss4m"));
+                assert!(neither.global_jvm_args.is_none());
+                assert!(neither.instance_jvm_args.is_none());
+            }
+            "game" => {
+                assert_eq!(from_instance.game_args.as_deref(), Some("--fullscreen"));
+                assert_eq!(from_global.game_args.as_deref(), Some("--foo"));
+                assert!(neither.game_args.is_none());
+            }
+            "memory" => {
+                assert_eq!(from_instance.memory_mb, 6144);
+                assert_eq!(from_global.memory_mb, 3072);
+                assert_eq!(neither.memory_mb, DEFAULT_MAX_MEMORY_MB);
+            }
+            "java" => {
+                assert_eq!(
+                    from_instance.java_path.as_deref(),
+                    Some(std::path::Path::new("D:/jdk21/bin/java.exe"))
+                );
+                assert_eq!(
+                    from_global.java_path.as_deref(),
+                    Some(std::path::Path::new("C:/jdk17/bin/java.exe"))
+                );
+                assert!(neither.java_path.is_none());
+            }
+            "backend" => {
+                assert_eq!(from_instance.graphics_backend, GraphicsBackend::Vulkan);
+                assert_eq!(from_global.graphics_backend, GraphicsBackend::Opengl);
+                assert_eq!(neither.graphics_backend, GraphicsBackend::Default);
+            }
+            _ => unreachable!(),
+        }
+    }
+}
+
+/// 只填了一项时，其余各项**不受牵连**（稀疏语义的真判据）。
+#[test]
+fn one_field_does_not_reset_the_others() {
+    let instance = LaunchOverrides {
+        memory_mb: Some(8192),
+        ..LaunchOverrides::default()
+    };
+    let global = GlobalLaunchDefaults {
+        jvm_args: Some("-XX:+UseZGC".to_string()),
+        game_args: Some("--width 1280".to_string()),
+        memory_mb: Some(2048),
+        java_path: Some(PathBuf::from("C:/java.exe")),
+        graphics_backend: Some(GraphicsBackend::Opengl),
+    };
+    let resolved = resolve(Some(&instance), &global);
+    assert_eq!(resolved.memory_mb, 8192, "实例内存赢");
+    assert_eq!(
+        resolved.global_jvm_args.as_deref(),
+        Some("-XX:+UseZGC"),
+        "全局 JVM 参数照旧下发（追加语义）"
+    );
+    assert_eq!(resolved.game_args.as_deref(), Some("--width 1280"));
+    assert_eq!(
+        resolved.java_path.as_deref(),
+        Some(std::path::Path::new("C:/java.exe"))
+    );
+    assert_eq!(
+        resolved.graphics_backend,
+        GraphicsBackend::Opengl,
+        "实例没给后端 → 落到全局层"
+    );
+}
+
+/// 空白字符串 = 没填：用户清空输入框必须回到跟随全局，而不是下发一个空参数。
+#[test]
+fn blank_text_falls_back_to_the_next_layer() {
+    let instance = LaunchOverrides {
+        jvm_args: Some("   ".to_string()),
+        game_args: Some(String::new()),
+        java_path: Some(PathBuf::from("  ")),
+        ..LaunchOverrides::default()
+    };
+    assert!(instance.is_empty(), "全空白视为空段");
+    let resolved = resolve(
+        Some(&instance),
+        &GlobalLaunchDefaults::with_jvm_args("-Xmx1g"),
+    );
+    assert_eq!(resolved.global_jvm_args.as_deref(), Some("-Xmx1g"));
+    assert!(resolved.instance_jvm_args.is_none());
+    assert!(resolved.game_args.is_none());
+    assert!(resolved.java_path.is_none());
+}
+
+/// 越界的内存值不算覆盖（手改文件绕得过 schema，绕不过这里）。
+#[test]
+fn out_of_range_memory_falls_back() {
+    for bad in [0, 1, MIN_MAX_MEMORY_MB - 1, MAX_MAX_MEMORY_MB + 1] {
+        let instance = LaunchOverrides {
+            memory_mb: Some(bad),
+            ..LaunchOverrides::default()
+        };
+        let resolved = resolve(Some(&instance), &GlobalLaunchDefaults::default());
+        assert_eq!(
+            resolved.memory_mb, DEFAULT_MAX_MEMORY_MB,
+            "{bad} MiB 不该生效"
+        );
+    }
+    let ok = resolve(
+        Some(&instance_with("memory")),
+        &GlobalLaunchDefaults::default(),
+    );
+    assert_eq!(ok.memory_mb, 6144);
+}
+
+/// 无效 `graphicsBackend` 值**拒绝**（不是静默落成 default）。
+#[test]
+fn unknown_graphics_backend_is_rejected() {
+    let error = serde_json::from_str::(r#"{"graphicsBackend":"vulkan2"}"#)
+        .expect_err("未知取值必须报错");
+    assert!(
+        error.to_string().contains("unknown variant"),
+        "错误文案要指出是变体不明：{error}"
+    );
+    // 大小写与空白容错只发生在 `parse` 这条显式路径上。
+    assert_eq!(
+        GraphicsBackend::parse(" VULKAN "),
+        Some(GraphicsBackend::Vulkan)
+    );
+    assert_eq!(GraphicsBackend::parse("metal"), None);
+    assert_eq!(GraphicsBackend::parse(""), None);
+}
+
+/// 三态词表与 `--graphicsBackend` 取值：`default` 不下发。
+#[test]
+fn backend_flag_values_skip_default() {
+    assert_eq!(GraphicsBackend::Default.flag_value(), None);
+    assert_eq!(GraphicsBackend::Opengl.flag_value(), Some("opengl"));
+    assert_eq!(GraphicsBackend::Vulkan.flag_value(), Some("vulkan"));
+    for (backend, id) in GraphicsBackend::ALL.into_iter().zip(GraphicsBackend::IDS) {
+        assert_eq!(backend.as_str(), id);
+        assert_eq!(GraphicsBackend::parse(id), Some(backend));
+    }
+}
+
+/// 落盘形状：空段不写键；有值才出现（稀疏），且能原样读回来。
+#[test]
+fn empty_section_is_not_serialized() {
+    let empty = serde_json::to_string(&LaunchOverrides::default()).expect("序列化");
+    assert_eq!(empty, "{}");
+    let filled = LaunchOverrides {
+        memory_mb: Some(4096),
+        graphics_backend: Some(GraphicsBackend::Vulkan),
+        ..LaunchOverrides::default()
+    };
+    let json = serde_json::to_string(&filled).expect("序列化");
+    assert_eq!(json, r#"{"memoryMb":4096,"graphicsBackend":"vulkan"}"#);
+    let back: LaunchOverrides = serde_json::from_str(&json).expect("反序列化");
+    assert_eq!(back, filled);
+}
+
+/// **补丁语义**：`None` 不动、`Some("")` 清空、非法值报错（GUI 与 CLI 共用这一条实现）。
+#[test]
+fn patch_touches_only_the_fields_it_is_given() {
+    let current = LaunchOverrides {
+        jvm_args: Some("-Xss4m".to_string()),
+        game_args: Some("--fullscreen".to_string()),
+        memory_mb: Some(4096),
+        java_path: Some(PathBuf::from("C:/jdk21/bin/java.exe")),
+        graphics_backend: Some(GraphicsBackend::Opengl),
+    };
+    // 只给内存：其余四项原样保留。
+    let patched = current
+        .patched(&LaunchOverridesPatch {
+            memory_mb: Some("8192".to_string()),
+            ..LaunchOverridesPatch::default()
+        })
+        .expect("合法补丁");
+    assert_eq!(patched.memory_mb, Some(8192));
+    assert_eq!(patched.jvm_args.as_deref(), Some("-Xss4m"));
+    assert_eq!(patched.graphics_backend, Some(GraphicsBackend::Opengl));
+
+    // 空串清空；空白也算清空。
+    let cleared = current
+        .patched(&LaunchOverridesPatch {
+            jvm_args: Some("  ".to_string()),
+            game_args: Some(String::new()),
+            ..LaunchOverridesPatch::default()
+        })
+        .expect("清空");
+    assert!(cleared.jvm_args.is_none());
+    assert!(cleared.game_args.is_none());
+    assert_eq!(cleared.memory_mb, Some(4096), "没给的项不许被连带清掉");
+
+    // `clear_all` 把五项一起清掉（`default` 后端同样落成「没有覆盖」）。
+    let cleared = current
+        .patched(&LaunchOverridesPatch::clear_all())
+        .expect("全清");
+    assert!(cleared.is_empty(), "{cleared:?}");
+}
+
+/// 非法补丁值必须报错：内存非整数/越界、后端词表外。
+#[test]
+fn patch_rejects_invalid_values() {
+    let current = LaunchOverrides::default();
+    for bad in ["4g", "0", "1", "999999"] {
+        let patch = LaunchOverridesPatch {
+            memory_mb: Some(bad.to_string()),
+            ..LaunchOverridesPatch::default()
+        };
+        assert!(current.patched(&patch).is_err(), "`{bad}` 不该通过内存校验");
+    }
+    for bad in ["vulkan2", "metal", "gl"] {
+        let error = current
+            .patched(&LaunchOverridesPatch::backend(bad))
+            .expect_err("未知后端要报错");
+        assert!(error.contains(bad), "{error}");
+        assert!(error.contains("vulkan"), "错误文案要给出可选值：{error}");
+    }
+    // 大小写容错走 `parse`（显式路径），落盘仍是小写稳定 id。
+    let patched = current
+        .patched(&LaunchOverridesPatch::backend(" VULKAN "))
+        .expect("大小写容错");
+    assert_eq!(patched.graphics_backend, Some(GraphicsBackend::Vulkan));
+    assert_eq!(
+        serde_json::to_string(&patched).expect("序列化"),
+        r#"{"graphicsBackend":"vulkan"}"#
+    );
+}
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//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) -> 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//`。
+    pub fn version_dir(&self, id: &str) -> PathBuf {
+        self.versions_dir().join(id)
+    }
+
+    /// 实例清单 `versions//.json`。
+    pub fn version_json(&self, id: &str) -> PathBuf {
+        self.version_dir(id).join(format!("{id}.json"))
+    }
+
+    /// 实例 jar `versions//.jar`。
+    pub fn version_jar(&self, id: &str) -> PathBuf {
+        self.version_dir(id).join(format!("{id}.jar"))
+    }
+
+    /// natives 解压目录 `versions//natives/`（ULL 约定，HMCL 用 `natives/`）。
+    pub fn natives_dir(&self, id: &str) -> PathBuf {
+        self.version_dir(id).join("natives")
+    }
+
+    /// 实例私有状态目录 `versions//.ull/`（上次会话日志索引、安装收据等）。
+    pub fn version_state_dir(&self, id: &str) -> PathBuf {
+        self.version_dir(id).join(".ull")
+    }
+
+    /// 实例私有库目录 `versions//libraries/`（HMCL `hint=local` 的落点）。
+    pub fn version_libraries_dir(&self, id: &str) -> PathBuf {
+        self.version_dir(id).join("libraries")
+    }
+
+    /// 启动器全局私有目录 `/.ull/`。
+    pub fn ull_root(&self) -> PathBuf {
+        self.root.join(".ull")
+    }
+
+    /// 资源索引 `assets/indexes/.json`。
+    pub fn asset_index(&self, assets_id: &str) -> PathBuf {
+        self.indexes_dir().join(format!("{assets_id}.json"))
+    }
+
+    /// 资源对象 `assets/objects//`。
+    ///
+    /// # Errors
+    ///
+    /// 哈希短于两个字符时返回 [`GameError::InvalidAssetHash`]。
+    pub fn asset_object(&self, hash: &str) -> Result {
+        let shard = hash.get(0..2).ok_or_else(|| GameError::InvalidAssetHash {
+            hash: hash.to_owned(),
+        })?;
+        Ok(self.objects_dir().join(shard).join(hash))
+    }
+
+    /// 公共库 `libraries//-[-].`。
+    pub fn library(&self, coordinate: &MavenCoordinate) -> PathBuf {
+        self.libraries_dir().join(coordinate.relative_path())
+    }
+
+    /// 实例私有库 `versions//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/`。
+    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//.json` 的目录），按字典序排列。
+    ///
+    /// # Errors
+    ///
+    /// 读 `versions/` 失败时返回 [`GameError::Io`]；目录不存在视为空列表。
+    pub fn installed_versions(&self) -> Result, 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..b6e128d
--- /dev/null
+++ b/crates/core/src/game/library.rs
@@ -0,0 +1,244 @@
+//! 依赖库模型：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,
+    /// natives 选择表：`{ "windows": "natives-windows-${arch}" }`。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub natives: Option>,
+    /// 生效规则（空 = 生效）。
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub rules: Vec,
+    /// natives 解压规则。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub extract: Option,
+    /// Maven 仓库基地址覆盖。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub url: Option,
+    /// HMCL 私有：`local` 表示库放在实例私有的 `versions//libraries/` 下。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub hint: Option,
+    /// 未识别字段原样保留。
+    #[serde(flatten)]
+    pub extra: BTreeMap,
+}
+
+/// 一条依赖库的下载表。
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct LibraryDownloads {
+    /// 主构件。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub artifact: Option,
+    /// 分类器构件（natives 走这里）。
+    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
+    pub classifiers: BTreeMap,
+}
+
+/// 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,
+}
+
+/// 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,
+    /// 扩展名，缺省 `jar`。
+    pub extension: String,
+}
+
+impl MavenCoordinate {
+    /// 解析坐标字符串。
+    pub fn parse(raw: &str) -> Result {
+        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('.', "/")
+    }
+
+    /// 文件名：`-[-].`。
+    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/` 的路径：
+    /// `///-[-].`。
+    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) -> Self {
+        Self {
+            classifier: Some(classifier.into()),
+            ..self.clone()
+        }
+    }
+}
+
+impl Library {
+    /// 解析本库的 Maven 坐标。
+    pub fn coordinate(&self) -> Result {
+        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`）。
+    ///
+    /// **Linux arm64 特例**：Mojang 的 LWJGL3 条目只写 `natives-linux`（x86_64），
+    /// 但同一个 Maven 坐标有 `natives-linux-arm64`。原样用 `natives-linux` 会下到 x86_64
+    /// 的 `.so`，在 aarch64 JVM 里加载失败；这里改成 arm64 分类器（下载地址的兜底见
+    /// `install::libraries`）。
+    pub fn native_classifier(&self, env: &Environment) -> Option {
+        let raw = self.natives.as_ref()?.get(&env.os)?;
+        let arch = if matches!(env.arch.as_str(), "x86_64" | "arm64") {
+            "64"
+        } else {
+            ""
+        };
+        let classifier = raw.replace("${arch}", arch);
+        if env.os == "linux"
+            && env.arch == "arm64"
+            && classifier == "natives-linux"
+            && self.is_lwjgl3()
+        {
+            return Some("natives-linux-arm64".to_owned());
+        }
+        Some(classifier)
+    }
+
+    /// 是否是 LWJGL 3（`org.lwjgl:`；LWJGL 2 的 group 是 `org.lwjgl.lwjgl`）。
+    fn is_lwjgl3(&self) -> bool {
+        self.name.starts_with("org.lwjgl:")
+    }
+
+    /// 现代清单（1.19+）把 natives 作为独立库条目：Linux arm64 上把
+    /// `org.lwjgl:::natives-linux` 改写成 `...:natives-linux-arm64`。
+    ///
+    /// 返回 None 表示不适用（非 Linux/arm64、非 LWJGL3、或不是 natives 条目）。
+    #[must_use]
+    pub fn linux_arm64_native_name(&self, env: &Environment) -> Option {
+        if env.os != "linux" || env.arch != "arm64" || !self.is_lwjgl3() {
+            return None;
+        }
+        let base = self.name.strip_suffix(":natives-linux")?;
+        Some(format!("{base}:natives-linux-arm64"))
+    }
+
+    /// 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 {
+        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 {
+        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/loader.rs b/crates/core/src/game/loader.rs
new file mode 100644
index 0000000..fd3be03
--- /dev/null
+++ b/crates/core/src/game/loader.rs
@@ -0,0 +1,399 @@
+//! 版本 id → 加载器：**全仓唯一**的 id 解析入口（M122），外加「种类 → 对外稳定 id」的命名词表
+//! **源头**（M126，见 [`LoaderKind::as_str`]；副本只有一处，见下）。
+//!
+//! # 为什么要这一个模块
+//!
+//! 「这个实例装的什么加载器」在 UI 上是一句话，代码里却有两个来源：版本 JSON 的 `libraries[]`
+//! （权威但要多读一次盘）与**版本 id 的字符串**（磁贴/列表最省事的那条）。只要有人按 id 猜就
+//! 必须只有**一处**在猜——两处各算一遍迟早一边先漂，用户看到的就是「我刚装的 Fabric 显示成
+//! 原版」（M120 复审的老 bug：解析端只认 `fabric-loader-…`，认不出自家生成的
+//! `1.20.4-fabric-0.16.5`）。所以 presenter 的实例页、CLI 的实例总览、以后任何「按 id 认加载
+//! 器」的地方一律调 [`InstanceLoader::parse`]，**不许**再写一份标记匹配。生成端
+//! （[`crate::addon::loader::LoaderKind::version_id`] 拼 `--`）与解析端的一致
+//! 性由 [`tests::own_version_ids_parse_back_to_their_loader`] 钉住（**从生成端取 id**，不手抄）；
+//! OptiFine 本启动器不能装（见 `presenter::host::install`），只能继承进来；LiteLoader 自 M222 起有安装路线。
+//!
+//! # 命名词表只有一张表（M126）
+//!
+//! 契约（0.2.0 已发布形状，**不许改名**）：`vanilla` / `fabric` / `quilt` / `forge` /
+//! `neoforge` / `optifine` / `liteloader`。**生产代码里这份词表有两处，都要改**：① 下面那次
+//! `loader_kind_vocab!` 展开——枚举、`ALL`、`as_str`、`has_marker` 全从同一张表长出来，所以
+//! 「加了一支却漏进清单」物理上做不到（理由见宏的注释）；② 会打印给用户看的
+//! `crates/cli/src/cli/help.rs` 里 `ull help instances` 的词表行——**逐字副本**、没有委派，
+//! 由 CLI 的 `help_lists_every_stable_id`（按 `ALL` 遍历）守着。安装侧与 presenter 的 `as_str` /
+//! `parse` 都是**委派**，CLI 的 `loader.kind` 直接调；唯一不进词表的字面量是安装侧收的输入别名
+//! `neo-forge`（Modrinth 拼法，只进不出）。
+//!
+//! 加一家加载器要动：① `loader_kind_vocab!` 表里加一行（id + 认不认标记）→ 枚举 / `ALL` /
+//! `as_str` / `has_marker` / 解析顺序一起长出来，漏不了；② presenter 的 `to_core`·`from_core`
+//! **编不过**（逼你决定 DTO 怎么显示它），能装的话安装侧 `as_str`·`from_core` 也各差一支；
+//! ③ 契约测试**会红**：presenter 的 `loader_kind_ids_are_the_released_contract` 拿 core 的 `ALL`
+//! 与独立手写的七个 id 做**集合比较**，CLI 的 `help_lists_every_stable_id` 按 `ALL` 遍历 help
+//! 词表，`json_rows_*` 钉真二进制输出面（0.2.0 已发出去过，所以这步是确认而不是可选）。
+//!
+//! ⚠️ 分工要看准：**编译器只拦「漏 match」**，新种类在消费方用 `=> Vanilla` 糊过去编得过。
+//! ③ 那条集合断言拦的是**对外词表**；**显示路径另有守卫**（M134 起）：`presenter/src/host/game.rs::dto_kind`
+//! 不再是自己一张手写 match，而是拿 core 的稳定 id 反查 DTO 词表——想在那一支糊 `=> Vanilla` 已经
+//! 没有 match 可写，加一家加载器会在 `dto::LoaderKind::from_core` 先编不过；糊错由 presenter 的
+//! `loader_kind_ids_are_the_released_contract`、以及按 `ALL` 遍历不手抄清单的
+//! `every_core_loader_kind_reaches_the_tile_as_itself` 钉住。**改名**同理：往返测试绿，只有 ③ 会红。
+//!
+//! # 解析规则（按整段前缀匹配，大小写不敏感，**最靠左的标记胜**）
+//!
+//! 1. 把 id 按 `-` 切段，从左往右找第一段，它的**前缀**是某个加载器标记
+//!    （`neoforge` / `fabric` / `quilt` / `forge` / `optifine` / `liteloader`）；紧跟的 `loader`
+//!    段（`fabric-loader-…`）或同段里的 `_loader` 尾巴算标记的一部分，不是版本段；
+//! 2. 该段里标记之后剩下的部分，加上它右边的所有段，按 `-` 拼回版本段
+//!    （`_` 之类的原样保留，所以 `1.13.2-OptiFine_HD_U_E6` 的版本是 `HD_U_E6`）；
+//! 3. 例外：版本段 **≥2 段**且末段像 MC 版本（`1.20.1` 这种纯数字点号）时砍掉末段——老 HMCL 的
+//!    `fabric-loader--` 写法；`0.16.5`（只剩一段）与 `0.20.0-beta.9` 不受影响；
+//! 4. 一个标记都没找到 ⇒ 原版（版本段空串）。只把加载器写进版本 JSON、id 里没痕迹的实例
+//!    （整包导入时被重命名成 `我的整合包` 那种）会**诚实**返回「原版」——那不等于没装加载器。
+
+/// 一张表生成整份词表：枚举、[`LoaderKind::ALL`]、`as_str`、`has_marker` 一起长出来。
+///
+/// 为什么非要用宏：Rust 没有「枚举有哪几支」的编译期反射，手写枚举 + 手写清单时「加了一支却
+/// 忘了进清单」既不报错也不会被测试抓住（测试同样从清单出发），新加载器被**静默**当成「认不
+/// 出」；让两者从同一张表展开，这件事在物理上不可能发生。表里的顺序就是标记的匹配优先级；
+/// 带 `marker` 的条目参与 id 识别，不带的（原版）不参与。
+macro_rules! loader_kind_vocab {
+    (
+        $(#[$meta:meta])*
+        $vis:vis enum $name:ident {
+            $(
+                $(#[$variant_doc:meta])*
+                $variant:ident => $id:literal $(, $marker:ident)?;
+            )+
+        }
+    ) => {
+        $(#[$meta])*
+        #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+        $vis enum $name {
+            $(
+                $(#[$variant_doc])*
+                $variant,
+            )+
+        }
+
+        impl $name {
+            /// 全部种类，**顺序即标记的匹配优先级**；原版没有标记（由 `has_marker` 跳过）。
+            pub const ALL: [Self; loader_kind_vocab!(@count $($variant)+)] =
+                [$(Self::$variant,)+];
+
+            /// 对外稳定 id（`--json` 的 `loader.kind`、GUI 词表、`--loader` 的取值）。
+            ///
+            /// 这是**生产代码里 id 的源头表**（0.2.0 已发布契约）：别处要么委派到这里，要么是逐字
+            /// 副本（`ull help instances` 的词表行，由 CLI 的 `help_lists_every_stable_id` 守着）。
+            /// 穷尽 match：加一支就编不过。
+            #[must_use]
+            pub const fn as_str(self) -> &'static str {
+                match self {
+                    $(Self::$variant => $id,)+
+                }
+            }
+
+            /// 这一支会不会从版本 id 的标记里认出来（原版不会）。穷尽 match：加一支必须表态。
+            #[must_use]
+            pub const fn has_marker(self) -> bool {
+                match self {
+                    $(Self::$variant => loader_kind_vocab!(@marker $($marker)?),)+
+                }
+            }
+        }
+    };
+    (@marker marker) => { true };
+    (@marker) => { false };
+    (@count) => { 0 };
+    (@count $head:ident $($tail:ident)*) => { 1 + loader_kind_vocab!(@count $($tail)*) };
+}
+
+loader_kind_vocab! {
+    /// 实例面向的加载器种类（比 [`crate::addon::loader::LoaderKind`] 宽）。
+    ///
+    /// 那个类型只描述**本启动器能装**的四家（装不了就没有下载路线）；本类型面向**识别与展示**，
+    /// 多出「原版」这一支，以及两家只能继承进来的第三方加载器。
+    pub enum LoaderKind {
+        /// 原版（id 里没有任何加载器标记）
+        Vanilla => "vanilla";
+        /// NeoForge（必须排在 `Forge` 前：两者都是段前缀匹配，顺序写死能防以后宽成「包含」）
+        NeoForge => "neoforge", marker;
+        /// Fabric
+        Fabric => "fabric", marker;
+        /// Quilt
+        Quilt => "quilt", marker;
+        /// Forge
+        Forge => "forge", marker;
+        /// OptiFine（第三方，本启动器不装，只继承）
+        OptiFine => "optifine", marker;
+        /// LiteLoader（自 M222 起可装：官方版本表 + 从零合成 launchwrapper 清单）
+        LiteLoader => "liteloader", marker;
+    }
+}
+
+impl LoaderKind {
+    /// 稳定 id → 种类（[`Self::as_str`] 的反查；整串全等、大小写不敏感、不认前缀与别名）。
+    ///
+    /// 别和 [`InstanceLoader::parse`] 搞混：那个认的是**版本 id**（切段、认前缀、给版本段）。
+    /// 别名 `neo-forge` 只有安装侧收，见 [`crate::addon::loader::LoaderKind::parse`]。
+    #[must_use]
+    pub fn parse(raw: &str) -> Option {
+        let wanted = raw.trim();
+        Self::ALL
+            .into_iter()
+            .find(|kind| kind.as_str().eq_ignore_ascii_case(wanted))
+    }
+}
+
+/// 一个版本 id 解析出来的加载器：种类 + 版本段（原版为空串）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct InstanceLoader {
+    /// 加载器种类
+    pub kind: LoaderKind,
+    /// 加载器版本段（id 里标记之后的那一截）；原版或 id 里没写版本时为空串
+    pub version: String,
+}
+
+impl InstanceLoader {
+    /// 从版本 id 解析加载器（纯字符串计算，不读盘）。
+    ///
+    /// 规则见模块文档；认不出标记时返回 [`LoaderKind::Vanilla`] + 空版本段。
+    #[must_use]
+    pub fn parse(version_id: &str) -> Self {
+        let segments: Vec<&str> = version_id.trim().split('-').collect();
+        for (index, segment) in segments.iter().enumerate() {
+            let Some((kind, rest)) = marker_of(segment) else {
+                continue;
+            };
+            // `fabric-loader-0.16.5-1.20.1` 按 `-` 切完是 `["fabric", "loader", …]`，
+            // `loader` 自己占一段；版本段要从它后面算，否则会读出 `loader-0.16.5`。
+            let mut next = index + 1;
+            while segments
+                .get(next)
+                .is_some_and(|segment| segment.eq_ignore_ascii_case("loader"))
+            {
+                next += 1;
+            }
+            let mut parts: Vec<&str> = Vec::new();
+            if !rest.is_empty() {
+                parts.push(rest);
+            }
+            parts.extend(segments.iter().skip(next).copied());
+            let version = join_version(&parts);
+            return Self { kind, version };
+        }
+        Self {
+            kind: LoaderKind::Vanilla,
+            version: String::new(),
+        }
+    }
+}
+
+/// 这一段的**前缀**是哪个加载器标记；命中时连它后面剩下的部分一起给出。
+///
+/// 标记串 = [`LoaderKind::as_str`]，顺序 = [`LoaderKind::ALL`]（即优先级），认不认标记由
+/// [`LoaderKind::has_marker`] 表决：**解析表没有独立字面量，也没有独立清单**。
+fn marker_of(segment: &str) -> Option<(LoaderKind, &str)> {
+    for kind in LoaderKind::ALL.into_iter().filter(|kind| kind.has_marker()) {
+        if let Some(rest) = strip_prefix_ascii_ci(segment, kind.as_str()) {
+            return Some((kind, strip_loader_suffix(rest)));
+        }
+    }
+    None
+}
+
+/// 去掉标记后面可选的 `loader` 后缀（版本段从 `0.16.5` 起算，不是 `loader-0.16.5`）。
+fn strip_loader_suffix(rest: &str) -> &str {
+    let trimmed = trim_separators(rest);
+    match strip_prefix_ascii_ci(trimmed, "loader") {
+        Some(after) => trim_separators(after),
+        None => trimmed,
+    }
+}
+
+/// 掐头去尾的 `-` / `_`（`OptiFine_HD_U_E6` 的标记后面紧跟的是 `_`）。
+fn trim_separators(text: &str) -> &str {
+    text.trim_matches(['-', '_'])
+}
+
+/// 大小写不敏感的 `strip_prefix`（用的是 ASCII 折叠，版本 id 里不会出现非 ASCII 标记）。
+fn strip_prefix_ascii_ci<'a>(text: &'a str, prefix: &str) -> Option<&'a str> {
+    let head = text.get(..prefix.len())?;
+    if head.eq_ignore_ascii_case(prefix) {
+        text.get(prefix.len()..)
+    } else {
+        None
+    }
+}
+
+/// 把标记右边剩下的段拼成版本段，并按「老 HMCL 的 `-` 尾巴」规则砍掉 MC 版本。
+fn join_version(parts: &[&str]) -> String {
+    let mut kept = parts.to_vec();
+    if kept.len() >= 2 && kept.last().is_some_and(|last| looks_like_mc_version(last)) {
+        kept.pop();
+    }
+    kept.join("-")
+}
+
+/// 这一段长得像不像 MC 版本（`1.20.1` 这种全数字 + 点号）；只用于「砍 HMCL 尾巴」（要求前面
+/// 还有内容，所以 `0.16.5` 与 `0.20.0-beta.9` 都不受影响）。
+fn looks_like_mc_version(text: &str) -> bool {
+    text.contains('.')
+        && text
+            .split('.')
+            .all(|part| !part.is_empty() && part.bytes().all(|byte| byte.is_ascii_digit()))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// 自家 id 的真值表：**从生成端取 id**，不手抄。
+    ///
+    /// 抓得住：生成端换了 id 形状而解析端没跟、解析端退回只认老 HMCL 口径（M122 的 bug）。
+    /// 抓不住：加载器版本自己带 `-` 的**其他**情形（`0.16.5-beta.1` / `0.20.0-beta.9` 两个
+    /// 样本专为它写；Forge/NeoForge 的真实版本号不带 `-`，出现了只能靠人补样本）。
+    #[test]
+    fn own_version_ids_parse_back_to_their_loader() {
+        use crate::addon::loader::LoaderKind as InstallKind;
+
+        let cases: [(InstallKind, LoaderKind, &str, &str); 6] = [
+            (InstallKind::Fabric, LoaderKind::Fabric, "1.20.4", "0.16.5"),
+            (
+                InstallKind::Fabric,
+                LoaderKind::Fabric,
+                "1.20.4",
+                "0.16.5-beta.1",
+            ),
+            (InstallKind::Quilt, LoaderKind::Quilt, "1.20.4", "0.27.0"),
+            (
+                InstallKind::Quilt,
+                LoaderKind::Quilt,
+                "1.20.1",
+                "0.20.0-beta.9",
+            ),
+            (InstallKind::Forge, LoaderKind::Forge, "1.20.1", "47.2.0"),
+            (
+                InstallKind::NeoForge,
+                LoaderKind::NeoForge,
+                "1.21.1",
+                "21.1.80",
+            ),
+        ];
+        for (install, kind, mc, loader_version) in cases {
+            let id = install.version_id(mc, loader_version);
+            let parsed = InstanceLoader::parse(&id);
+            assert_eq!(parsed.kind, kind, "id `{id}` 认成了 {:?}", parsed.kind);
+            assert_eq!(parsed.version, loader_version, "id `{id}` 的版本段");
+        }
+    }
+
+    /// 第三方前缀（OptiFine / LiteLoader）：它们**不是** `--` 口径。
+    ///
+    /// 样本来源：PCL 的 `Modules/Minecraft/ModDownload.vb:441`（`-OptiFine_…`）与
+    /// `Pages/PageDownload/ModDownloadLib.vb:793`（`-LiteLoader`，**没有版本段**）；`_pre1`
+    /// 尾巴来自 OptiFine 自己的 preview 命名。
+    /// 抓得住：标记被当成「必须带 `-`」或「必须小写」（旧口径 `split_once("optifine")`）。
+    /// 抓不住：OptiFine 的 maven 坐标形式（`optifine:OptiFine:1.12.2_HD_U_C7`），未做特判。
+    #[test]
+    fn third_party_prefixes_are_recognized() {
+        let cases = [
+            ("1.13.2-OptiFine_HD_U_E6", LoaderKind::OptiFine, "HD_U_E6"),
+            ("1.20.1-OptiFine_HD_U_I6", LoaderKind::OptiFine, "HD_U_I6"),
+            (
+                "1.20.1-OptiFine_HD_U_I6_pre1",
+                LoaderKind::OptiFine,
+                "HD_U_I6_pre1",
+            ),
+            ("1.20.1-OptiFine", LoaderKind::OptiFine, ""),
+            ("1.12.2-LiteLoader", LoaderKind::LiteLoader, ""),
+        ];
+        for (id, kind, version) in cases {
+            let parsed = InstanceLoader::parse(id);
+            assert_eq!(parsed.kind, kind, "id `{id}` 认成了 {:?}", parsed.kind);
+            assert_eq!(parsed.version, version, "id `{id}` 的版本段");
+        }
+    }
+
+    /// 老 HMCL / CF 口径（`fabric-loader--`、`forge-`）：存量实例还会按它们
+    /// 出现，行为不许退化。
+    ///
+    /// 抓得住：砍 MC 尾巴的规则被删（版本段变成 `0.16.5-1.20.1`）、`loader` 后缀被当成版本段。
+    /// 抓不住：`forge-47.2.0-1.20.1` 是**手工声明**的口径，不是查到的真实格式（本仓库的老
+    /// HMCL 分支已改成「清单 + patch」）。
+    #[test]
+    fn foreign_loader_style_ids_still_parse() {
+        let cases = [
+            ("fabric-loader-0.16.5-1.20.1", LoaderKind::Fabric, "0.16.5"),
+            ("quilt-loader-0.24.0-1.20.1", LoaderKind::Quilt, "0.24.0"),
+            (
+                "quilt-loader-0.24.0-beta.9-1.20.1",
+                LoaderKind::Quilt,
+                "0.24.0-beta.9",
+            ),
+            ("forge-47.2.0", LoaderKind::Forge, "47.2.0"),
+            ("forge-47.2.0-1.20.1", LoaderKind::Forge, "47.2.0"),
+        ];
+        for (id, kind, version) in cases {
+            let parsed = InstanceLoader::parse(id);
+            assert_eq!(parsed.kind, kind, "id `{id}` 认成了 {:?}", parsed.kind);
+            assert_eq!(parsed.version, version, "id `{id}` 的版本段");
+        }
+    }
+
+    /// 反向锚：普通版本 id（原版、快照、预发布）**不许**被认成加载器。
+    ///
+    /// 抓得住：解析端退化成「有 id 就当加载器」、匹配放宽成「包含子串」。
+    /// 抓不住：**含加载器名字样的原版 id**（真出现 `1.20.4-forge` 这种原版 id 会被认成
+    /// Forge——本模块按标记优先）。
+    #[test]
+    fn plain_version_ids_stay_vanilla() {
+        for id in [
+            "1.20.4",
+            "1.20",
+            "1.7.10",
+            "23w45a",
+            "1.20.4-rc1",
+            "1.20.1-pre1",
+            "",
+            "   ",
+        ] {
+            let parsed = InstanceLoader::parse(id);
+            assert_eq!(parsed.kind, LoaderKind::Vanilla, "id `{id}`");
+            assert!(parsed.version.is_empty(), "id `{id}` 的版本段应为空");
+        }
+    }
+
+    /// 标记按**整段前缀**匹配，不是「包含」：段里出现加载器名字样但不在段首的，不算。
+    ///
+    /// 抓得住：匹配规则从「段前缀」放宽成「段内包含」（`myforge-pack` 会被认成 Forge）。
+    /// 抓不住：段首就是标记的误伤（`forgepack-1.0` 会认成 Forge）——这条有意不拦，因为
+    /// 段首命中正是 OptiFine 的 `OptiFine_HD_U_E6` 与 CF 的 `forge-47.2.0` 依赖的形状。
+    #[test]
+    fn markers_only_match_at_segment_start() {
+        for id in ["1.20.1-myforge-pack", "1.20.1-somequiltish"] {
+            let parsed = InstanceLoader::parse(id);
+            assert_eq!(parsed.kind, LoaderKind::Vanilla, "id `{id}`");
+        }
+    }
+
+    /// 往返锚：**每个对外 id 喂回解析都要认成它自己**，标记顺序也得留优先级。
+    ///
+    /// 抓得住：标记匹配退化（段前缀变整段全等、`loader` 后缀/MC 尾巴规则被改坏）、标记串与词表
+    /// 脱节、`neoforge` 被排到 `forge` 后面。抓不住：**改名**——词表与解析同源、改名自洽，本条
+    /// 是绿的；抓改名是 presenter 的 `loader_kind_ids_are_the_released_contract`。
+    #[test]
+    fn every_stable_id_parses_back_to_its_kind() {
+        for kind in LoaderKind::ALL {
+            let id = kind.as_str();
+            assert_eq!(LoaderKind::parse(id), Some(kind), "反查 `{id}`");
+            let parsed = InstanceLoader::parse(&format!("1.20.4-{id}-0.16.5"));
+            assert_eq!(parsed.kind, kind, "`{id}` 认成了 {:?}", parsed.kind);
+            let expected = if kind.has_marker() { "0.16.5" } else { "" };
+            assert_eq!(parsed.version, expected, "`{id}` 的版本段");
+        }
+        let order: Vec = LoaderKind::ALL.into_iter().collect();
+        let neoforge = order.iter().position(|kind| *kind == LoaderKind::NeoForge);
+        let forge = order.iter().position(|kind| *kind == LoaderKind::Forge);
+        assert!(neoforge < forge, "`neoforge` 要在 `forge` 前：{order:?}");
+    }
+}
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//.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,
+    /// SHA-1 校验值。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub sha1: Option,
+    /// 字节数。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub size: Option,
+    /// 下载地址（老版本的版本 JSON 可能完全没有）。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub url: Option,
+    /// 库文件相对 `libraries/` 的路径（Mojang 在 artifact 里给出）。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub path: Option,
+}
+
+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);
+
+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,
+    /// 配置文件本体。
+    #[serde(default)]
+    pub file: DownloadInfo,
+    /// `log4j2-xml` 之类。
+    #[serde(rename = "type", default, skip_serializing_if = "Option::is_none")]
+    pub kind: Option,
+}
+
+/// 版本 JSON 的 `logging` 对象（键通常是 `client`）。
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(transparent)]
+pub struct Logging(pub BTreeMap);
+
+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,
+    /// 主版本号，例如 `17`。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub major_version: Option,
+}
+
+/// `assetIndex`：资源索引的引用。
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AssetIndexRef {
+    /// 索引 id（`1.20`、`legacy`…），对应 `assets/indexes/.json`。
+    #[serde(default)]
+    pub id: String,
+    /// 索引文件 SHA-1。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub sha1: Option,
+    /// 索引文件字节数。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub size: Option,
+    /// 全部对象的总字节数（`totalSize`，进度估算用）。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub total_size: Option,
+    /// 索引下载地址。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub url: Option,
+}
+
+/// 一份版本 JSON（磁盘上的 `.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,
+    /// 展示名（部分整合包写入）。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub name: Option,
+    /// 继承的父版本 id。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub inherits_from: Option,
+    /// 启动用的 jar 所在版本 id；`None` 表示用本实例的 jar。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub jar: Option,
+    /// 主类。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub main_class: Option,
+    /// 旧版单串游戏参数（pre-1.13），与 `arguments` 并存。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub minecraft_arguments: Option,
+    /// 新版结构化参数。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub arguments: Option,
+    /// 资源版本名（`1.20`、`legacy`…）；缺失按 `legacy` 处理（analyse/03 §4.6）。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub assets: Option,
+    /// 资源索引引用。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub asset_index: Option,
+    /// 兼容级别。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub compliance_level: Option,
+    /// 需要的 Java 版本。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub java_version: Option,
+    /// 依赖库列表。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub libraries: Option>,
+    /// 下载信息。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub downloads: Option,
+    /// 日志配置。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub logging: Option,
+    /// 版本分类。
+    #[serde(rename = "type", skip_serializing_if = "Option::is_none")]
+    pub version_type: Option,
+    /// 最后修改时间。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub time: Option,
+    /// 发布时间。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub release_time: Option,
+    /// 启动器最低版本要求。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub minimum_launcher_version: Option,
+    /// 是否为根清单（HMCL 私有字段）。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub root: Option,
+    /// 是否在 UI 中隐藏（HMCL 私有字段）。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub hidden: Option,
+    /// 补丁层，按 `priority` 升序合并（HMCL 私有字段）。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub patches: Option>,
+    /// 补丁优先级；`None` 视作最小值（最先合并，analyse/03 §4.1）。
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub priority: Option,
+    /// 未识别的字段，原样保留（`rawJson` 保真）。
+    #[serde(flatten)]
+    pub extra: BTreeMap,
+}
+
+impl VersionJson {
+    /// 解析一份版本 JSON。
+    pub fn from_json_str(json: &str) -> Result {
+        serde_json::from_str(json).map_err(|e| GameError::json("version_json", e))
+    }
+
+    /// 从字节解析（直接吃 HTTP 响应体）。
+    pub fn from_json_slice(bytes: &[u8]) -> Result {
+        serde_json::from_slice(bytes).map_err(|e| GameError::json("version_json", e))
+    }
+
+    /// 序列化回 JSON。
+    pub fn to_json_string(&self) -> Result {
+        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..5f0dce1
--- /dev/null
+++ b/crates/core/src/game/mod.rs
@@ -0,0 +1,91 @@
+//! 版本与实例仓库：不可变快照 + 单写者草稿、版本 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`]；
+//! - 版本 id → 加载器：[`loader`]（[`InstanceLoader::parse`]，全仓唯一解析入口）；
+//! - 能力位：[`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。
+//!
+//! 已铺在盘上的版本接入（M221，[`adopt`]）：扫描/检查 `versions/` 里**别人装的**版本 → 只登记
+//! （`profiles.json` + 实例设置），不搬文件、不写游戏根。缺省运行目录落 ULL 数据区，
+//! 共用/写进对方的 `.minecraft` 必须显式选择（见 [`adopt::AdoptTarget`]）。
+//!
+//! 存档与截图（M235，[`saves`]）：**只读**列 `/saves`（世界目录）与
+//! `/screenshots`（图片），不建目录、不写盘；「打开文件夹」走
+//! [`crate::platform::opener::open_dir`]（平台差异不在这里）。缩略图墙与导入不在这一版（塔裁决 U3）。
+//!
+//! 模块分工按"数据形状 / 纯计算 / 状态"切开，任何模块都不碰网络与 UI：
+//! 下载归 `core::download`、进程归 `core::launch`、配置落盘归 `core::setting`。
+
+pub mod adopt;
+pub mod arguments;
+pub mod capability;
+pub mod error;
+pub mod inherit;
+pub mod install;
+pub mod isolation;
+pub mod java;
+pub mod launch_overrides;
+pub mod layout;
+pub mod library;
+pub mod loader;
+pub mod manifest;
+pub mod profiles;
+pub mod saves;
+pub mod snapshot;
+pub mod unlisted;
+pub mod version;
+
+pub use adopt::{
+    AdoptCandidate, AdoptError, AdoptOutcome, AdoptPlan, AdoptProblem, AdoptRequest, AdoptScan,
+    AdoptTarget, RegisteredInstance,
+};
+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 launch_overrides::{
+    resolve as resolve_launch_overrides, valid_memory, GlobalLaunchDefaults, GraphicsBackend,
+    LaunchOverrides, LaunchOverridesPatch, ResolvedLaunch, DEFAULT_MAX_MEMORY_MB,
+    MAX_MAX_MEMORY_MB, MIN_MAX_MEMORY_MB,
+};
+pub use layout::GameLayout;
+pub use library::{Library, MavenCoordinate};
+pub use loader::{InstanceLoader, LoaderKind};
+pub use manifest::{AssetIndexRef, DownloadInfo, Downloads, JavaVersion, Logging, VersionJson};
+pub use profiles::{InstanceProfile, ProfileId, ProfileList, PROFILE_SCHEMA_VERSION};
+pub use saves::{
+    Area, SavesError, SavesScan, SavesSkip, ScreenshotEntry, SkipKind, WorldEntry,
+    IMAGE_EXTENSIONS, SAVES_DIR, SCREENSHOTS_DIR, WORLD_ICON,
+};
+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) -> 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 {
+        Ok(Self(s.to_owned()))
+    }
+}
+
+impl From 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//`）。
+    #[serde(default)]
+    pub version_id: String,
+    /// 独立游戏目录；`None` 表示使用全局 `.minecraft`。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub game_dir: Option,
+    /// 工作目录覆盖（HMCL 的"版本隔离"）。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub running_dir: Option,
+    /// Java 路径覆盖。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub java_path: Option,
+    /// 创建时间（RFC-3339 字符串，由调用方填写）。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub created_at: Option,
+    /// 最近启动时间。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub last_played_at: Option,
+    /// 未识别字段原样保留（向前兼容）。
+    #[serde(flatten)]
+    pub extra: BTreeMap,
+}
+
+impl InstanceProfile {
+    /// 建一个最小档案（新实例默认值）。
+    pub fn new(name: impl Into, version_id: impl Into) -> 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,
+}
+
+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 {
+        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 {
+        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 {
+        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 {
+        serde_json::to_string_pretty(self).map_err(|e| super::error::GameError::json("profiles", e))
+    }
+}
diff --git a/crates/core/src/game/saves/error.rs b/crates/core/src/game/saves/error.rs
new file mode 100644
index 0000000..17a4ae0
--- /dev/null
+++ b/crates/core/src/game/saves/error.rs
@@ -0,0 +1,38 @@
+//! 「目录存在但不可用」的失败形状（带 OS 原文）。
+//!
+//! 只有**一层**：`/saves` 或 `/screenshots` 本身不可用。项目级的问题
+//! （某个世界目录读不出元数据、某个文件不是图片）不是错误，逐条进 `skipped`——列表宁可短，
+//! 也不能因为一个坏文件整份读不出来。
+//!
+//! 为什么不折叠成 `io::Error`：调用方要分得清「这个实例没有存档目录」与「有但读不了」，
+//! 前者是空列表加一句说明，后者是带重试按钮的红字。`dir` 字段是这两者的唯一区分依据。
+
+use std::fmt;
+use std::path::PathBuf;
+
+/// 一次列举失败。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SavesError {
+    /// 出问题的那个目录（`/saves` 或 `/screenshots`）。
+    pub dir: PathBuf,
+    /// 人读原因（OS 原文或"是符号链接"这类判据）。
+    pub detail: String,
+}
+
+impl SavesError {
+    /// 建一条（内部用；`dir` 一律是**被列的那个目录**，不是它的父目录）。
+    pub(super) fn unusable(dir: &std::path::Path, detail: impl Into) -> Self {
+        Self {
+            dir: dir.to_path_buf(),
+            detail: detail.into(),
+        }
+    }
+}
+
+impl fmt::Display for SavesError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "目录不可用（{}）：{}", self.dir.display(), self.detail)
+    }
+}
+
+impl std::error::Error for SavesError {}
diff --git a/crates/core/src/game/saves/list.rs b/crates/core/src/game/saves/list.rs
new file mode 100644
index 0000000..0e0a020
--- /dev/null
+++ b/crates/core/src/game/saves/list.rs
@@ -0,0 +1,296 @@
+//! 列一个运行目录下的 `saves/`（世界）与 `screenshots/`（图片），**纯只读**。
+//!
+//! 只碰三种系统调用：`symlink_metadata`（判目录形态）、`read_dir`（取子项）、`metadata`
+//! （取大小/时间）。没有 `create_dir`、没有 `write`、没有 `rename`、没有 `remove`——`saves/`
+//! 不存在时也**不替玩家建**（建出来的空目录会让「这实例还没玩过」这件事再也看不出来）。
+//!
+//! 回看「调用前后版本树不变」的判据见 `tests::scan_does_not_touch_the_disk`：
+//! 它在调用前后各拍一次 `(相对路径, 是否目录, 字节数, mtime)` 的指纹并逐条比对。
+
+use std::path::{Path, PathBuf};
+use std::time::UNIX_EPOCH;
+
+use super::error::SavesError;
+
+/// `saves` 目录名（游戏与社区一致的口径）。
+pub const SAVES_DIR: &str = "saves";
+
+/// `screenshots` 目录名（原版游戏把 F2 截图放这里）。
+pub const SCREENSHOTS_DIR: &str = "screenshots";
+
+/// 世界图标文件名（**只判存在**，不解码：U3 不做缩略图墙）。
+pub const WORLD_ICON: &str = "icon.png";
+
+/// 认作截图的扩展名（大小写不敏感）。
+///
+/// 原版游戏只写 `.png`；其余几个是玩家手动塞进去/其它 mod 的常见形态。**不收** `.gif` /
+/// 视频——它们是"别的东西"，与"我们忘了列"要区分开（见 [`SkipKind::NotAnImage`]）。
+pub const IMAGE_EXTENSIONS: &[&str] = &["png", "jpg", "jpeg", "webp"];
+
+/// 某个运行目录下的 `saves/`（纯路径拼接，不建、不检查）。
+#[must_use]
+pub fn saves_dir(run_dir: &Path) -> PathBuf {
+    run_dir.join(SAVES_DIR)
+}
+
+/// 某个运行目录下的 `screenshots/`（纯路径拼接，不建、不检查）。
+#[must_use]
+pub fn screenshots_dir(run_dir: &Path) -> PathBuf {
+    run_dir.join(SCREENSHOTS_DIR)
+}
+
+/// `saves/` 下的一个世界目录。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct WorldEntry {
+    /// 磁盘上的目录名（原样）。**这一版它就是展示名**：`LevelName` 在 `level.dat` 里，
+    /// 解析 NBT 不在 U3 范围内（做缩略图墙时一起做）。
+    pub dir: String,
+    /// 有没有 `icon.png`（只判存在，不读内容）。
+    pub icon: bool,
+    /// 目录 mtime（毫秒 since UNIX_EPOCH；取不到为 `None`）。
+    pub modified_ms: Option,
+}
+
+/// `screenshots/` 下的一张图。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ScreenshotEntry {
+    /// 磁盘文件名（原样，含扩展名）。
+    pub file: String,
+    /// 字节数（UI 自己格式化，不在这里拼 `1.2 MiB`）。
+    pub bytes: u64,
+    /// 文件 mtime（毫秒 since UNIX_EPOCH；取不到为 `None`）。
+    pub modified_ms: Option,
+}
+
+/// 被跳过的条目来自哪个目录。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Area {
+    /// `/saves/`
+    Saves,
+    /// `/screenshots/`
+    Screenshots,
+}
+
+/// 没收进列表的原因。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SkipKind {
+    /// 符号链接（不跟随：跟随会把实例外的东西算成存档）。
+    SymbolicLink,
+    /// `saves/` 下的非目录（散落文件），或 `screenshots/` 下的目录。
+    NotADirectoryExpected,
+    /// `screenshots/` 下的非普通文件（设备 / 管道 / 目录）。
+    NotAFile,
+    /// 名字过不了路径规则（含 `\`、`:`、`..` 之类；判据复用整合包侧那一份）。
+    UnsafeName,
+    /// 元数据读不出来。
+    Unreadable,
+    /// `screenshots/` 下的普通文件，但扩展名不是 [`IMAGE_EXTENSIONS`]。
+    NotAnImage,
+}
+
+/// 一个没能进列表的条目。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SavesSkip {
+    /// 来自哪个目录。
+    pub area: Area,
+    /// 磁盘名字（原样；读不出来时给能拿到的那个串）。
+    pub file: String,
+    /// 为什么没收。
+    pub reason: SkipKind,
+}
+
+/// 一次列举的结果（两个目录一次读回，UI 只收这一份快照）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SavesScan {
+    /// 被列的 `saves/` 目录。
+    pub dir: PathBuf,
+    /// `saves/` 存不存在（`false` = 这实例还没存过档，不是错误）。
+    pub exists: bool,
+    /// 世界列表（按名字排序，大小写不敏感）。
+    pub worlds: Vec,
+    /// 被列的 `screenshots/` 目录。
+    pub screenshots_dir: PathBuf,
+    /// `screenshots/` 存不存在。
+    pub screenshots_exists: bool,
+    /// 截图列表（**新的在前**：文件名就是时间戳，倒序即时间倒序）。
+    pub screenshots: Vec,
+    /// 跳过的条目与原因（两个目录并在一份里，靠 [`SavesSkip::area`] 区分）。
+    pub skipped: Vec,
+}
+
+impl SavesScan {
+    /// `saves/` 与 `screenshots/` 一个都不存在（新实例的常态）。
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.worlds.is_empty() && self.screenshots.is_empty()
+    }
+}
+
+/// 列一个运行目录下的 `saves/` 与 `screenshots/`。
+///
+/// 目录不存在 → `exists = false` 的空结果（新实例不是错误），**且不建那个目录**。
+///
+/// # Errors
+///
+/// 目录存在但不可用（符号链接 / 不是目录 / 读不了）时给 [`SavesError`]。
+pub fn scan(run_dir: &Path) -> Result {
+    let dir = saves_dir(run_dir);
+    let (exists, children) = read_children(&dir)?;
+    let mut worlds = Vec::new();
+    let mut skipped = Vec::new();
+    for child in children {
+        let raw = child.file_name().to_string_lossy().to_string();
+        let Ok(file_type) = child.file_type() else {
+            skipped.push(skip(Area::Saves, raw, SkipKind::Unreadable));
+            continue;
+        };
+        if file_type.is_symlink() {
+            skipped.push(skip(Area::Saves, raw, SkipKind::SymbolicLink));
+            continue;
+        }
+        if !file_type.is_dir() {
+            skipped.push(skip(Area::Saves, raw, SkipKind::NotADirectoryExpected));
+            continue;
+        }
+        if !plain_name(&raw) {
+            skipped.push(skip(Area::Saves, raw, SkipKind::UnsafeName));
+            continue;
+        }
+        let icon = is_regular_file(&dir.join(&raw).join(WORLD_ICON));
+        let modified_ms = child.metadata().ok().and_then(|meta| modified_ms(&meta));
+        worlds.push(WorldEntry {
+            dir: raw,
+            icon,
+            modified_ms,
+        });
+    }
+    // 名字排序（大小写不敏感；同名时按磁盘名字典序兜底，保证两帧之间不抖）。
+    worlds.sort_by(|left, right| {
+        left.dir
+            .to_lowercase()
+            .cmp(&right.dir.to_lowercase())
+            .then_with(|| left.dir.cmp(&right.dir))
+    });
+
+    let shots_dir = screenshots_dir(run_dir);
+    let (shots_exists, shots) = read_children(&shots_dir)?;
+    let mut screenshots = Vec::new();
+    for child in shots {
+        let raw = child.file_name().to_string_lossy().to_string();
+        let Ok(file_type) = child.file_type() else {
+            skipped.push(skip(Area::Screenshots, raw, SkipKind::Unreadable));
+            continue;
+        };
+        if file_type.is_symlink() {
+            skipped.push(skip(Area::Screenshots, raw, SkipKind::SymbolicLink));
+            continue;
+        }
+        if !file_type.is_file() {
+            skipped.push(skip(Area::Screenshots, raw, SkipKind::NotAFile));
+            continue;
+        }
+        if !plain_name(&raw) {
+            skipped.push(skip(Area::Screenshots, raw, SkipKind::UnsafeName));
+            continue;
+        }
+        if !is_image(&raw) {
+            skipped.push(skip(Area::Screenshots, raw, SkipKind::NotAnImage));
+            continue;
+        }
+        let meta = child.metadata().ok();
+        screenshots.push(ScreenshotEntry {
+            bytes: meta.as_ref().map_or(0, std::fs::Metadata::len),
+            modified_ms: meta.as_ref().and_then(modified_ms),
+            file: raw,
+        });
+    }
+    // 新的在前：截图文件名就是 `2024-01-02_12.00.00.png`，字典序倒排就是时间倒排。
+    screenshots.sort_by(|left, right| right.file.cmp(&left.file));
+    skipped.sort_by(|left, right| {
+        area_key(left.area)
+            .cmp(&area_key(right.area))
+            .then_with(|| left.file.cmp(&right.file))
+    });
+
+    Ok(SavesScan {
+        dir,
+        exists,
+        worlds,
+        screenshots_dir: shots_dir,
+        screenshots_exists: shots_exists,
+        screenshots,
+        skipped,
+    })
+}
+
+/// 列一个目录的子项（**不存在 ⇒ `(false, 空)`**；不可用 ⇒ 具名错误；符号链接不跟随）。
+fn read_children(dir: &Path) -> Result<(bool, Vec), SavesError> {
+    let meta = match std::fs::symlink_metadata(dir) {
+        Ok(meta) => meta,
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+            return Ok((false, Vec::new()));
+        }
+        Err(error) => return Err(SavesError::unusable(dir, error.to_string())),
+    };
+    if meta.file_type().is_symlink() {
+        return Err(SavesError::unusable(
+            dir,
+            "是符号链接（不跟随：会把实例目录之外的内容算成存档）",
+        ));
+    }
+    if !meta.is_dir() {
+        return Err(SavesError::unusable(dir, "不是目录"));
+    }
+    let read =
+        std::fs::read_dir(dir).map_err(|error| SavesError::unusable(dir, error.to_string()))?;
+    let mut children: Vec<_> = read
+        .collect::, _>>()
+        .map_err(|error| SavesError::unusable(dir, error.to_string()))?;
+    children.sort_by_key(std::fs::DirEntry::file_name);
+    Ok((true, children))
+}
+
+fn skip(area: Area, file: String, reason: SkipKind) -> SavesSkip {
+    SavesSkip { area, file, reason }
+}
+
+/// 名字是不是**裸名字**（判据复用整合包侧那一份，不在这里写第二份规则）。
+///
+/// `read_dir` 给的已经是单段名字，所以只需判它过不过得了路径规则：`\`、`:`、`..` 这类会被
+/// 拒——它们既可能在展示里被误读成路径分隔，也可能在将来接"删除/重命名"时落到别处。
+fn plain_name(raw: &str) -> bool {
+    crate::addon::pack::path::normalize_file(raw).is_ok()
+}
+
+/// 扩展名是不是认得的图片（大小写不敏感）。
+fn is_image(raw: &str) -> bool {
+    Path::new(raw)
+        .extension()
+        .and_then(|ext| ext.to_str())
+        .map(|ext| {
+            let ext = ext.to_ascii_lowercase();
+            IMAGE_EXTENSIONS.iter().any(|known| *known == ext)
+        })
+        .unwrap_or(false)
+}
+
+/// 是不是**普通文件**（不跟随符号链接：`icon.png` 指到别处不算这个世界的图标）。
+fn is_regular_file(path: &Path) -> bool {
+    std::fs::symlink_metadata(path)
+        .map(|meta| meta.file_type().is_file())
+        .unwrap_or(false)
+}
+
+/// mtime → 毫秒（早于 1970 或取不到 ⇒ `None`，不报错）。
+fn modified_ms(meta: &std::fs::Metadata) -> Option {
+    let since = meta.modified().ok()?.duration_since(UNIX_EPOCH).ok()?;
+    u64::try_from(since.as_millis()).ok()
+}
+
+/// 跳过条目的排序键（先 `saves/` 再 `screenshots/`）。
+fn area_key(area: Area) -> u8 {
+    match area {
+        Area::Saves => 0,
+        Area::Screenshots => 1,
+    }
+}
diff --git a/crates/core/src/game/saves/mod.rs b/crates/core/src/game/saves/mod.rs
new file mode 100644
index 0000000..ce258b9
--- /dev/null
+++ b/crates/core/src/game/saves/mod.rs
@@ -0,0 +1,78 @@
+//! 存档 / 截图的列举与「打开文件夹」（M235 · STOREMVP）+ 三个写操作（M247 · SAVESOPS）。
+//!
+//! # 读的那一半（M235）
+//!
+//! 用户原话是「存档截图 / 导入」，M230 审计确认三层全缺（core 没有读路径，`saves/` 只在
+//! `isolation.rs` 的切换探测里被计数；presenter 没有 DTO；i18n 没有键；没有页面）。
+//! U3 把 M235 的边界钉成：**只读列表 + 打开文件夹，不做缩略图墙**。理由有两条：
+//!
+//! 1. 缩略图要引图片解码依赖，而 `AGENTS.md` §2 只允许 `palette-extract` 之外不引 image 类依赖；
+//! 2. 截图/导入的产物形态还没定型，先不进产品。
+//!
+//! 所以 [`list`] **只读**：只调 `read_dir` / `metadata` / `symlink_metadata`，不建目录、不写文件、
+//! 不改名字、不读文件内容（`icon.png` 只判存在——那是将来缩略图墙的输入，不是这一版的解码对象）。
+//!
+//! # 写的那一半（M247）
+//!
+//! 用户接着拍板：「存档按照主流的方式来」——主流第三方启动器（HMCL / PCL2）的存档区都有
+//! **重命名世界 / 删除世界（二次确认）/ 备份导出**。这三个落在 [`write`]：
+//!
+//! | 操作 | 入口 | 边界 |
+//! |---|---|---|
+//! | 重命名 | [`write::rename_world`] | 只动 `saves/` → `saves/`；撞名拒 |
+//! | 删除 | [`write::delete_world`] | 先过边界校验，再递归删；不跟随符号链接 |
+//! | 备份 | [`write::backup_world`] | 流式 zip 到调用方给的目录，时戳命名，不覆盖 |
+//!
+//! **写操作一律自己重新校验 `run_dir` 与目标路径**（不靠调用方传对）——判据在
+//! [`write`] 的模块文档里一条条列着。
+//!
+//! # 单根语义（D20）
+//!
+//! 入口是**已经派生好的运行目录**（[`crate::game::isolation::derive_game_dir`] 的结果），
+//! 本模块只往下取两层：`/saves/` 与 `/screenshots/`。
+//! 不自己去猜游戏根，也不做「隔离侧 + 共享侧合并」——派生是启动、mod 列表、存档列表**同一个**
+//! 答案的唯一来源。与 [`crate::addon::mods`] 同一条纪律。
+//!
+//! # 目录不存在不是错误
+//!
+//! 新实例两个目录都不存在，这**不是**异常（`exists = false` + 空列表）。只有「存在但不可用」
+//! （符号链接 / 不是目录 / 读不了）才是 [`SavesError`]；**并且照样不建目录**。
+//! 写操作那边不同：目标不存在就是 [`write::SavesWriteKind::NotFound`]（写不下去，得说清楚）。
+//!
+//! # 收纳口径
+//!
+//! | 位置 | 收什么 | 不收什么（逐条登记原因，不静默丢） |
+//! |---|---|---|
+//! | `saves/` | 子目录 = 一个世界 | 符号链接（不跟随）、非目录（散落文件）、名字过不了路径规则、元数据读不出 |
+//! | `screenshots/` | 扩展名是 [`IMAGE_EXTENSIONS`] 的普通文件 | 同上 + 不是图片的文件（`NotAnImage`） |
+//!
+//! 「不静默丢」是 M224 定下的口径：列表要能和磁盘对得上账，用户看到「跳过 3 项」时得知道
+//! 那 3 项不是我们忘了。
+//!
+//! # 模块
+//!
+//! | 文件 | 职责 |
+//! |---|---|
+//! | [`error`] | 「目录存在但不可用」的失败形状（带 OS 原文） |
+//! | [`list`] | 列 `/saves` 与 `/screenshots`（纯只读） |
+//! | [`write`] | 重命名 / 删除 / 备份导出（三个写操作 + 边界校验） |
+//!
+//! 「打开文件夹」不在本模块：平台差异收敛在 [`crate::platform::opener::open_dir`]
+//! （`AGENTS.md` §6），本模块一个 `cfg` 都不写。
+
+mod error;
+mod list;
+mod write;
+
+pub use error::SavesError;
+pub use list::{
+    saves_dir, scan, screenshots_dir, Area, SavesScan, SavesSkip, ScreenshotEntry, SkipKind,
+    WorldEntry, IMAGE_EXTENSIONS, SAVES_DIR, SCREENSHOTS_DIR, WORLD_ICON,
+};
+pub use write::{
+    backup_world, delete_world, rename_world, Backup, SavesWriteError, SavesWriteKind, BACKUP_EXT,
+    MAX_BACKUP_ENTRIES, MAX_BACKUP_TOTAL_BYTES,
+};
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/core/src/game/saves/tests.rs b/crates/core/src/game/saves/tests.rs
new file mode 100644
index 0000000..fd3fb63
--- /dev/null
+++ b/crates/core/src/game/saves/tests.rs
@@ -0,0 +1,260 @@
+//! 只读判据的用例：**真的建盘上目录**再读回来（不 mock 文件系统）。
+//!
+//! 每条用例都写在「抓得住什么 / 抓不住什么」的口径里（M224 的写法）：
+//!
+//! | 用例 | 抓得住 | 抓不住 |
+//! |---|---|---|
+//! | [`scan_lists_worlds_and_screenshots_read_only`] | 收纳口径、排序、`icon.png` 只判存在、**调用前后盘上指纹不变** | 大世界的耗时（不测性能） |
+//! | [`missing_dirs_are_empty_and_not_created`] | 「不存在 ⇒ 空列表」且**不建目录** | 权限不足导致的 `NotFound`（本机跑不出来） |
+//! | [`unusable_dirs_are_errors`] | 目录被占成文件 ⇒ 具名错误 | Windows 上建符号链接要开发者模式，见下一条 |
+//! | [`symlinks_are_refused`] | 符号链接不被跟随（目录级与条目级） | 非 unix 平台（`cfg(unix)`；Windows 建链接要提权） |
+
+use std::path::Path;
+
+use super::*;
+use crate::addon::temp::TempRoot;
+
+/// 建一个运行目录（`/run`）。
+///
+/// `create_dir_all` 这一句不是冗余：`addon::temp::TempRoot::under` 返回时它内部的 `base`
+/// 已经析构、把那棵树删掉了（M235 已作为 finding 上报，`addon/` 不在本 mission 的改动范围）。
+/// 修好之后这一句会退化成 no-op。
+fn run_dir(tag: &str) -> TempRoot {
+    let root = TempRoot::under(tag, "run");
+    std::fs::create_dir_all(&root).expect("建运行目录");
+    root
+}
+
+/// 盘上指纹：`(相对路径, 是否目录, 字节数, mtime)` 逐条排序后的列表。
+///
+/// 这就是「调用前后版本树快照不变」的判据本体——只要列举路径里多了一次 `create_dir`、
+/// 一次 `write`、一次 `remove`，或者顺手动了 mtime，这个列表就会不同。
+fn fingerprint(root: &Path) -> Vec {
+    let mut out = Vec::new();
+    let mut stack = vec![root.to_path_buf()];
+    while let Some(dir) = stack.pop() {
+        let Ok(read) = std::fs::read_dir(&dir) else {
+            continue;
+        };
+        let mut entries: Vec<_> = read.flatten().collect();
+        entries.sort_by_key(std::fs::DirEntry::file_name);
+        for entry in entries {
+            let path = entry.path();
+            let Ok(meta) = std::fs::symlink_metadata(&path) else {
+                continue;
+            };
+            let rel = path
+                .strip_prefix(root)
+                .unwrap_or(&path)
+                .display()
+                .to_string();
+            let mtime = meta
+                .modified()
+                .ok()
+                .and_then(|time| time.duration_since(std::time::UNIX_EPOCH).ok())
+                .map_or(0, |since| since.as_millis());
+            out.push(format!(
+                "{rel}|dir={}|len={}|mtime={mtime}",
+                meta.is_dir(),
+                meta.len()
+            ));
+            if meta.is_dir() {
+                stack.push(path);
+            }
+        }
+    }
+    out.sort();
+    out
+}
+
+/// 收纳口径 + 排序 + `icon.png` + **只读**（M235 的核心判据）。
+#[test]
+fn scan_lists_worlds_and_screenshots_read_only() {
+    let root = run_dir("m235-scan");
+    let saves = saves_dir(&root);
+    std::fs::create_dir_all(saves.join("World A")).expect("建世界 A");
+    std::fs::write(saves.join("World A/level.dat"), b"nbt").expect("写 level.dat");
+    std::fs::write(saves.join("World A/icon.png"), b"png").expect("写 icon");
+    std::fs::create_dir_all(saves.join("world b")).expect("建世界 B");
+    // `saves/` 下的散落文件：不是世界，登记原因。
+    std::fs::write(saves.join("readme.txt"), b"hi").expect("写散落文件");
+
+    let shots = screenshots_dir(&root);
+    std::fs::create_dir_all(&shots).expect("建截图目录");
+    std::fs::write(shots.join("2024-05-01_10.00.00.png"), b"aa").expect("写截图 1");
+    std::fs::write(shots.join("2024-06-02_11.00.00.PNG"), b"bbb").expect("写截图 2");
+    std::fs::write(shots.join("notes.txt"), b"x").expect("写非图片");
+
+    let before = fingerprint(&root);
+    let scan = scan(&root).expect("列存档");
+    let after = fingerprint(&root);
+    assert_eq!(before, after, "列举改动了磁盘：{before:?} → {after:?}");
+
+    assert!(scan.exists);
+    assert!(scan.screenshots_exists);
+    assert_eq!(scan.dir, save_path(&root));
+    assert_eq!(scan.screenshots_dir, shot_path(&root));
+
+    // 世界：名字排序大小写不敏感；`icon.png` 只判存在。
+    let worlds: Vec<(&str, bool)> = scan
+        .worlds
+        .iter()
+        .map(|world| (world.dir.as_str(), world.icon))
+        .collect();
+    assert_eq!(worlds, [("World A", true), ("world b", false)]);
+    assert!(
+        scan.worlds.iter().all(|world| world.modified_ms.is_some()),
+        "世界的 mtime 应当取得到：{:?}",
+        scan.worlds
+    );
+
+    // 截图：新的在前（文件名倒序），扩展名大小写不敏感，非图片登记原因。
+    let shots_listed: Vec<&str> = scan
+        .screenshots
+        .iter()
+        .map(|shot| shot.file.as_str())
+        .collect();
+    assert_eq!(
+        shots_listed,
+        ["2024-06-02_11.00.00.PNG", "2024-05-01_10.00.00.png"]
+    );
+    assert_eq!(scan.screenshots[0].bytes, 3, "字节数来自 metadata");
+    assert_eq!(scan.screenshots[1].bytes, 2);
+
+    let skipped: Vec<(Area, &str, SkipKind)> = scan
+        .skipped
+        .iter()
+        .map(|skip| (skip.area, skip.file.as_str(), skip.reason))
+        .collect();
+    assert_eq!(
+        skipped,
+        [
+            (Area::Saves, "readme.txt", SkipKind::NotADirectoryExpected),
+            (Area::Screenshots, "notes.txt", SkipKind::NotAnImage),
+        ],
+        "跳过必须逐条登记原因（不静默丢）"
+    );
+}
+
+/// 「目录不存在 ⇒ 空列表」**且不替玩家建目录**。
+#[test]
+fn missing_dirs_are_empty_and_not_created() {
+    let root = run_dir("m235-missing");
+    let before = fingerprint(&root);
+
+    let scan = scan(&root).expect("两个目录都不存在不是错误");
+    assert!(!scan.exists);
+    assert!(!scan.screenshots_exists);
+    assert!(scan.worlds.is_empty());
+    assert!(scan.screenshots.is_empty());
+    assert!(scan.skipped.is_empty());
+    assert!(scan.is_empty());
+
+    assert_eq!(fingerprint(&root), before, "列举顺手建了目录");
+    assert!(!saves_dir(&root).exists(), "`saves/` 被建出来了");
+    assert!(
+        !screenshots_dir(&root).exists(),
+        "`screenshots/` 被建出来了"
+    );
+    // 路径本身照样是"拼得出来的"（UI 的「打开文件夹」需要它）。
+    assert_eq!(scan.dir, saves_dir(&root));
+    assert_eq!(scan.screenshots_dir, screenshots_dir(&root));
+}
+
+/// 「存在但不是目录」⇒ 具名错误（不折叠成空列表：那不是"没存档"，是"读不了"）。
+#[test]
+fn unusable_dirs_are_errors() {
+    let root = run_dir("m235-unusable");
+    std::fs::write(saves_dir(&root), b"not a dir").expect("用文件占住 saves 这个名字");
+
+    let error = scan(&root).expect_err("saves 是个文件，居然列成功了");
+    assert_eq!(error.dir, saves_dir(&root));
+    assert!(error.detail.contains("不是目录"), "原因：{}", error.detail);
+
+    // `screenshots/` 那一侧单独判（saves 正常、shot 被占）。
+    let other = run_dir("m235-unusable-shots");
+    std::fs::create_dir_all(saves_dir(&other)).expect("建 saves");
+    std::fs::write(screenshots_dir(&other), b"x").expect("用文件占住 screenshots");
+    let error = scan(&other).expect_err("screenshots 是个文件，居然列成功了");
+    assert_eq!(error.dir, screenshots_dir(&other));
+}
+
+/// 符号链接不跟随（目录级 = 错误；条目级 = 跳过并登记原因）。
+#[cfg(unix)]
+#[test]
+fn symlinks_are_refused() {
+    use std::os::unix::fs::symlink;
+
+    // 目录级：`saves/` 指到别处 ⇒ 拒（列下去会把实例外的东西算成存档）。
+    let root = run_dir("m235-symlink-dir");
+    let elsewhere = root.join("elsewhere");
+    std::fs::create_dir_all(elsewhere.join("Outside")).expect("建实例外目录");
+    symlink(&elsewhere, saves_dir(&root)).expect("建符号链接");
+    let error = scan(&root).expect_err("符号链接的 saves 居然列成功了");
+    assert!(error.detail.contains("符号链接"), "原因：{}", error.detail);
+
+    // 条目级：世界目录 / 截图文件各一个链接 ⇒ 跳过，不跟随。
+    let root = run_dir("m235-symlink-entry");
+    let saves = saves_dir(&root);
+    std::fs::create_dir_all(&saves).expect("建 saves");
+    std::fs::create_dir_all(elsewhere.join("Real")).expect("建真实世界");
+    symlink(elsewhere.join("Real"), saves.join("Linked")).expect("建世界链接");
+    let shots = screenshots_dir(&root);
+    std::fs::create_dir_all(&shots).expect("建 screenshots");
+    std::fs::write(elsewhere.join("shot.png"), b"png").expect("写真实截图");
+    symlink(elsewhere.join("shot.png"), shots.join("linked.png")).expect("建截图链接");
+
+    let scan = scan(&root).expect("列存档");
+    assert!(scan.worlds.is_empty(), "跟随了世界符号链接");
+    assert!(scan.screenshots.is_empty(), "跟随了截图符号链接");
+    let reasons: Vec<(Area, SkipKind)> = scan
+        .skipped
+        .iter()
+        .map(|skip| (skip.area, skip.reason))
+        .collect();
+    assert_eq!(
+        reasons,
+        [
+            (Area::Saves, SkipKind::SymbolicLink),
+            (Area::Screenshots, SkipKind::SymbolicLink),
+        ]
+    );
+}
+
+/// 名字过不了路径规则的条目：跳过并登记（不静默丢）。
+///
+/// `:` 在 unix 上是合法文件名字符，在 Windows 上建不出来——所以这条只在 unix 跑得起来。
+#[cfg(unix)]
+#[test]
+fn unsafe_names_are_skipped() {
+    let root = run_dir("m235-unsafe");
+    let scenes = saves_dir(&root);
+    std::fs::create_dir_all(&scenes).expect("建 saves");
+    std::fs::create_dir_all(scenes.join("bad:name")).expect("建带冒号的世界");
+    std::fs::create_dir_all(scenes.join("good")).expect("建正常世界");
+
+    let scan = scan(&root).expect("列存档");
+    let worlds: Vec<&str> = scan.worlds.iter().map(|world| world.dir.as_str()).collect();
+    assert_eq!(worlds, ["good"]);
+    assert_eq!(scan.skipped.len(), 1);
+    assert_eq!(scan.skipped[0].file, "bad:name");
+    assert_eq!(scan.skipped[0].reason, SkipKind::UnsafeName);
+}
+
+/// 路径拼接口径：两个目录都挂在**运行目录**下面（不是游戏根、不是 `.minecraft`）。
+#[test]
+fn paths_hang_off_the_run_dir() {
+    let run = Path::new("D:/ULL/.ULL/data/instances/better-mc");
+    assert_eq!(saves_dir(run).file_name().unwrap(), SAVES_DIR);
+    assert_eq!(screenshots_dir(run).file_name().unwrap(), SCREENSHOTS_DIR);
+    assert!(saves_dir(run).starts_with(run));
+    assert!(screenshots_dir(run).starts_with(run));
+}
+
+fn save_path(root: &Path) -> std::path::PathBuf {
+    root.join(SAVES_DIR)
+}
+
+fn shot_path(root: &Path) -> std::path::PathBuf {
+    root.join(SCREENSHOTS_DIR)
+}
diff --git a/crates/core/src/game/saves/write.rs b/crates/core/src/game/saves/write.rs
new file mode 100644
index 0000000..a03ce26
--- /dev/null
+++ b/crates/core/src/game/saves/write.rs
@@ -0,0 +1,159 @@
+//! 存档的**三个写操作**（M247 · SAVESOPS）：重命名世界、删除世界、备份导出（zip）。
+//!
+//! # 这一版做到哪
+//!
+//! 用户原话是「存档按照主流的方式来」——HMCL / PCL2 的存档区都有**重命名 / 删除（二次确认）/
+//! 备份导出**。M235 只做了只读列表，本模块补写的那一半。
+//!
+//! | 操作 | 入口 | 落盘形态 |
+//! |---|---|---|
+//! | 重命名世界 | [`rename_world`] | `saves/` → `saves/`（一次 `rename`，不搬字节） |
+//! | 删除世界 | [`delete_world`] | 递归删 `saves/`（**不跟随符号链接**） |
+//! | 备份导出 | [`backup_world`] | `/<世界名>-YYYYMMDD-HHMMSS.zip`（流式 zip） |
+//!
+//! # 边界校验是**每次自己重做**的，不靠调用方传对
+//!
+//! 三个入口的第一件事都是 [`boundary::guard`]：它重新解析 ``、重新确认
+//! `/saves` 是**直属子目录且不是链接**、重新确认目标那条世界目录是**真的目录而不是链接**。
+//! 调用方（presenter host）拿到的是「实例 id + 世界名」这种可被 UI 传坏的东西，所以
+//! **r1 复审那种「信任上游」在这里一律不成立**：
+//!
+//! ```text
+//! 名字   → 必须是单段裸名字（`crate::addon::pack::path::normalize_file` 后原样相等）
+//! saves/ → 必须是  的真实直属子目录（解析后比父级，不拿字符串前缀当判据）
+//! 世界   → 必须是 saves/ 下的真目录（symlink_metadata：符号链接、非目录一律拒）
+//! ```
+//!
+//! 三条各自对应 [`SavesWriteKind`] 里的一个具名类别，测试逐条钉住（见 `write/tests.rs`）。
+//!
+//! # 为什么写操作不走 `saves::scan` 的结果
+//!
+//! 扫描结果是**上一拍**的事实。用户在文件管理器里换了名字、别的程序删了一个目录，扫描里都还是
+//! 旧值。所以写路径上不「先查快照再下手」，而是把边界与目标重新查一遍——快照只用来画界面。
+//!
+//! # 不跟随符号链接（`AGENTS.md` 的写盘纪律）
+//!
+//! | 位置 | 判据 | 为什么 |
+//! |---|---|---|
+//! | `saves/` 本身是链接 | 拒绝（[`SavesWriteKind::SymbolicLink`]） | 跟下去就写到实例目录之外了 |
+//! | 世界目录是链接 | 拒绝 | 同上；删除更危险（会把链接指向的整棵树删掉） |
+//! | 世界**内部**的链接 | 删除：只删链接本身；备份：跳过并计数 | 两种都不跟随，但都不静默丢（`skipped` 会计数） |
+//!
+//! # 失败形状
+//!
+//! [`SavesWriteError`] = **具名类别 + 出事的那个路径 + OS 原文**。不拼人读句子（M161 纪律：
+//! 文案由 app 层按 i18n key 现求）。UI 上每一种都有话可说——见 [`SavesWriteKind`] 每一个变体的文档。
+//!
+//! # 模块
+//!
+//! | 文件 | 职责 |
+//! |---|---|
+//! | [`boundary`] | 名字规则 + `/saves/` 的三道校验 + 重命名 |
+//! | [`remove`] | 递归删除（不跟随链接，层级有上限） |
+//! | [`backup`] | 流式 zip（限额预检 → 写临时文件 → 原子改名） |
+
+use std::fmt;
+use std::path::PathBuf;
+
+mod backup;
+mod boundary;
+mod remove;
+
+#[cfg(test)]
+mod tests;
+
+pub use backup::{backup_world, Backup, BACKUP_EXT, MAX_BACKUP_ENTRIES, MAX_BACKUP_TOTAL_BYTES};
+pub use boundary::rename_world;
+pub use remove::delete_world;
+
+/// 写操作失败的类别（**结构**；文案由 app 层按 i18n key 现求）。
+///
+/// 每个变体在 UI 上都有一句对应的话，没有一种是「静默失败」：
+///
+/// | 类别 | 用户看到什么 |
+/// |---|---|
+/// | [`Boundary`](Self::Boundary) | 这个路径落在 `saves/` 之外（或层级深得不像一个世界） |
+/// | [`UnsafeName`](Self::UnsafeName) | 名字里有不能用的字符（`/` `\` `:` `..` …） |
+/// | [`SymbolicLink`](Self::SymbolicLink) | 这个位置是符号链接，不跟随 |
+/// | [`NotFound`](Self::NotFound) | 那个世界（或 `saves/` 目录）已经不在了 |
+/// | [`NotADirectory`](Self::NotADirectory) | 那个名字底下不是目录 |
+/// | [`Conflict`](Self::Conflict) | 同名世界已存在 / 备份文件名撞满 |
+/// | [`TooLarge`](Self::TooLarge) | 备份超过体积或条目上限（附上限数值） |
+/// | [`Io`](Self::Io) | 其它系统错误（权限 / 被占用），OS 原文进括号 |
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum SavesWriteKind {
+    /// 目标越出 `/saves`（名字可穿越、或解析后落在外面、或层级异常深）。
+    Boundary,
+    /// 名字过不了路径规则（空串、`.`、`..`、含 `/` `\` `:` NUL，或规整后与原串不等）。
+    UnsafeName,
+    /// 目标（`saves/` 那一层或世界那一条）是符号链接：不跟随。
+    SymbolicLink,
+    /// 目标不在了（`run_dir` / `saves/` / 世界目录三者之一）。
+    NotFound,
+    /// 目标存在但不是目录。
+    NotADirectory,
+    /// 目标已存在（重命名撞名、备份文件名撞满）。
+    Conflict,
+    /// 备份超过体积 / 条目上限。
+    TooLarge,
+    /// 其它 IO 失败（权限、被别的进程占用……OS 原文进 `detail`）。
+    Io,
+}
+
+/// 一次写操作失败。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SavesWriteError {
+    /// 出事的那个路径（能确定时给最内层的那一条）。
+    pub path: PathBuf,
+    /// 失败类别。
+    pub kind: SavesWriteKind,
+    /// 人读原因（OS 原文或判据本身），**只进括号**，不进主句。
+    pub detail: String,
+}
+
+impl SavesWriteError {
+    pub(super) fn new(
+        path: &std::path::Path,
+        kind: SavesWriteKind,
+        detail: impl Into,
+    ) -> Self {
+        Self {
+            path: path.to_path_buf(),
+            kind,
+            detail: detail.into(),
+        }
+    }
+
+    /// 一个 IO 错误：类别 [`SavesWriteKind::Io`]，`detail` 是 OS 原文。
+    pub(super) fn io(path: &std::path::Path, error: &std::io::Error) -> Self {
+        Self::new(path, SavesWriteKind::Io, error.to_string())
+    }
+}
+
+impl fmt::Display for SavesWriteError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(
+            f,
+            "{}（{}）：{}",
+            self.path.display(),
+            kind_label(self.kind),
+            self.detail
+        )
+    }
+}
+
+impl std::error::Error for SavesWriteError {}
+
+/// 类别的中文短名（**日志与测试诊断用**，不是界面文案：界面按 i18n key 现求）。
+fn kind_label(kind: SavesWriteKind) -> &'static str {
+    match kind {
+        SavesWriteKind::Boundary => "路径越界",
+        SavesWriteKind::UnsafeName => "名字不可用",
+        SavesWriteKind::SymbolicLink => "是符号链接",
+        SavesWriteKind::NotFound => "已不在",
+        SavesWriteKind::NotADirectory => "不是目录",
+        SavesWriteKind::Conflict => "同名冲突",
+        SavesWriteKind::TooLarge => "超出上限",
+        SavesWriteKind::Io => "系统错误",
+    }
+}
diff --git a/crates/core/src/game/saves/write/backup.rs b/crates/core/src/game/saves/write/backup.rs
new file mode 100644
index 0000000..a65da1a
--- /dev/null
+++ b/crates/core/src/game/saves/write/backup.rs
@@ -0,0 +1,365 @@
+//! 世界目录 → zip 备份（流式、限额预检、原子落点）。
+//!
+//! # 落点与命名
+//!
+//! `/<世界名>-YYYYMMDD-HHMMSS.zip`（UTC 时间戳）。落点名撞上已有文件就顺延
+//! `-2` … `-99`，撞满报 [`SavesWriteKind::Conflict`]——**绝不覆盖**上一次备份。
+//!
+//! `dest_dir` 由调用方给（presenter host 的默认值是启动器自己的 `exports/saves/`，见
+//! `core::launch::crash_bundle::default_target_dir` 的同一先例）。本模块不猜「用户想要哪个目录」，
+//! 也不在 `saves/` 里偷偷建备份目录：`saves/` 下多一个 `backups/` 会在列表里长成一个世界。
+//!
+//! # 为什么先预检再写第一个字节
+//!
+//! 一条写死的边界（与 `addon::pack::format::write` 的 `preflight` 同一条纪律）：**超限要在
+//! 内容进内存之前就拒**。这里的预检只走 `metadata().len()`：顶层递归一遍算条目数与未压缩总量，
+//! 超限时连临时文件都不建。之后写循环里还有第二道（**已写出**的字节数），因为预检与写入之间
+//! 文件可能变大（实例目录不是快照）。
+//!
+//! 上限本身是 [`MAX_BACKUP_TOTAL_BYTES`]（3 GiB）与 [`MAX_BACKUP_ENTRIES`]（20 万条）：
+//! 前者压在 zip 的 32 位尺寸阈值（4 GiB）之下，所以**永远不会写 ZIP64**——一个能被自己与
+//! 常见第三方工具读回来的包，比一个「理论上更大」的包有用。
+//!
+//! # 为什么写临时文件再改名
+//!
+//! 半截的备份文件比没有备份更坏：用户会以为它是一份完整的备份。所以写到 `<名字>.part`，
+//! 收尾成功才 `rename` 到最终名字；任何一步失败都把临时文件删掉（同 `addon::pack` 的
+//! `temporary_path` 口径）。
+//!
+//! # 符号链接
+//!
+//! **不跟随**：世界内部遇到链接只**跳过并计数**（[`Backup::skipped`]），不打包链接指向的内容。
+//! 跳过不是静默的——`skipped` 会进 UI 的那句话（「跳过了 2 个符号链接」），与 M235「不静默丢」同一条纪律。
+
+use std::fs::File;
+use std::io::{Read, Write};
+use std::path::{Path, PathBuf};
+use std::time::SystemTime;
+
+use super::boundary::guard;
+use super::{SavesWriteError, SavesWriteKind};
+
+/// 备份文件的扩展名。
+pub const BACKUP_EXT: &str = "zip";
+
+/// 未压缩总量上限（3 GiB：压在 zip 的 32 位尺寸阈值之下，见模块文档）。
+pub const MAX_BACKUP_TOTAL_BYTES: u64 = 3 * 1024 * 1024 * 1024;
+
+/// 条目数上限（20 万条；一个巨型世界的 `region/` 通常是几千条）。
+pub const MAX_BACKUP_ENTRIES: usize = 200_000;
+
+/// 搬内容时的缓冲（流式，不把文件整份读进内存）。
+const COPY_CHUNK: usize = 1024 * 1024;
+
+/// 撞名时最多顺延多少个后缀（`-2` … `-99`）。
+const MAX_SUFFIX: u32 = 99;
+
+/// 一次成功的备份。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Backup {
+    /// 落点（最终名字，不是临时文件）。
+    pub path: PathBuf,
+    /// 写出来的 zip 字节数。
+    pub bytes: u64,
+    /// 源目录的**未压缩**字节数（预检算出来的）。
+    pub sourced: u64,
+    /// 进了包的条目数（含目录条目）。
+    pub entries: usize,
+    /// 被跳过的符号链接数（不跟随；这个数要能报到界面上）。
+    pub skipped: usize,
+}
+
+/// 写操作的限额（生产口径见 [`Limits::production`]；测试可以用极小的值钉住边界）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(super) struct Limits {
+    /// 未压缩总量上限。
+    pub(super) total: u64,
+    /// 条目数上限。
+    pub(super) entries: usize,
+}
+
+impl Limits {
+    pub(super) const fn production() -> Self {
+        Self {
+            total: MAX_BACKUP_TOTAL_BYTES,
+            entries: MAX_BACKUP_ENTRIES,
+        }
+    }
+
+    #[cfg(test)]
+    pub(super) const fn new(total: u64, entries: usize) -> Self {
+        Self { total, entries }
+    }
+}
+
+/// 备份一个世界目录到 `dest_dir`，返回落点与统计。
+///
+/// 第一句永远是 [`guard`]：源必须是 `/saves` 下的真目录。
+///
+/// # Errors
+///
+/// | 情况 | 类别 |
+/// |---|---|
+/// | 源越界 / 是链接 / 不在 / 不是目录 | `Boundary` / `SymbolicLink` / `NotFound` / `NotADirectory` |
+/// | 超过 [`MAX_BACKUP_TOTAL_BYTES`] 或 [`MAX_BACKUP_ENTRIES`] | [`SavesWriteKind::TooLarge`] |
+/// | 撞名顺延到 `-99` 还被占 | [`SavesWriteKind::Conflict`] |
+/// | 建目录 / 读文件 / 写 zip / 改名失败 | [`SavesWriteKind::Io`]（`path` 指出卡在哪一条） |
+pub fn backup_world(
+    run_dir: &Path,
+    name: &str,
+    dest_dir: &Path,
+) -> Result {
+    backup_world_at(
+        run_dir,
+        name,
+        dest_dir,
+        SystemTime::now(),
+        Limits::production(),
+    )
+}
+
+/// 带显式时钟与限额的那一份（测试用它钉「时戳命名」与「限额拦在内容进内存之前」）。
+pub(super) fn backup_world_at(
+    run_dir: &Path,
+    name: &str,
+    dest_dir: &Path,
+    at: SystemTime,
+    limits: Limits,
+) -> Result {
+    let target = guard(run_dir, name)?;
+    // 落点目录必须是**绝对且非空**的：相对路径会落到进程当前目录（测试里真的发生过——
+    // 一次 `dest = ""` 把 zip 写进了 crate 根），这属于「写到用户没想到的地方」，直接拒。
+    if dest_dir.as_os_str().is_empty() || !dest_dir.is_absolute() {
+        return Err(SavesWriteError::new(
+            dest_dir,
+            SavesWriteKind::Boundary,
+            format!(
+                "落点目录需要绝对路径，收到 `{}`（相对路径会落到进程当前目录）",
+                dest_dir.display()
+            ),
+        ));
+    }
+    // 预检：只走 metadata，不读内容；超限时下面的临时文件连建都不建。
+    let plan = plan(&target.world, limits)?;
+    std::fs::create_dir_all(dest_dir).map_err(|error| SavesWriteError::io(dest_dir, &error))?;
+    let path = unique_target(dest_dir, name, at)?;
+    let temp = temporary_path(&path);
+    // 上一轮被打断留下的临时文件：先清掉（同名字段是 `.part`，扫不到就继续）。
+    let _ = std::fs::remove_file(&temp);
+
+    match write_zip(&plan, &temp, limits) {
+        Ok(()) => {}
+        Err(error) => {
+            let _ = std::fs::remove_file(&temp);
+            return Err(error);
+        }
+    }
+    if let Err(error) = std::fs::rename(&temp, &path) {
+        let _ = std::fs::remove_file(&temp);
+        return Err(SavesWriteError::io(&path, &error));
+    }
+    let bytes = std::fs::metadata(&path).map(|meta| meta.len()).unwrap_or(0);
+    Ok(Backup {
+        path,
+        bytes,
+        sourced: plan.total,
+        entries: plan.dirs.len() + plan.files.len(),
+        skipped: plan.skipped,
+    })
+}
+
+/// 预检结果：要打进包的那一份清单（`saves/` 之外一个字节都没碰）。
+struct Plan {
+    /// 目录条目（zip 内名字，带结尾 `/`）。
+    dirs: Vec,
+    /// 文件条目（zip 内名字 + 磁盘路径 + 字节数）。
+    files: Vec<(String, PathBuf, u64)>,
+    /// 未压缩总量。
+    total: u64,
+    /// 跳过的符号链接数。
+    skipped: usize,
+}
+
+/// 走一遍世界目录，算条目数与总量（**只读**，不读内容）。
+fn plan(world: &Path, limits: Limits) -> Result {
+    let mut out = Plan {
+        dirs: Vec::new(),
+        files: Vec::new(),
+        total: 0,
+        skipped: 0,
+    };
+    // (磁盘目录, zip 内前缀)：显式栈，避免深目录上的递归栈。
+    let mut stack: Vec<(PathBuf, String)> = vec![(world.to_path_buf(), String::new())];
+    while let Some((dir, prefix)) = stack.pop() {
+        let read = std::fs::read_dir(&dir).map_err(|error| SavesWriteError::io(&dir, &error))?;
+        // 同一个目录里的顺序不影响包内容，但排序能让同名世界两次备份的条目序一致（可比对）。
+        let mut children: Vec<_> = read
+            .collect::, _>>()
+            .map_err(|error| SavesWriteError::io(&dir, &error))?;
+        children.sort_by_key(std::fs::DirEntry::file_name);
+        for child in children {
+            let raw = child.file_name().to_string_lossy().to_string();
+            let path = child.path();
+            let name = if prefix.is_empty() {
+                raw.clone()
+            } else {
+                format!("{prefix}/{raw}")
+            };
+            let meta = match std::fs::symlink_metadata(&path) {
+                Ok(meta) => meta,
+                // 预检与写入之间被删掉：当成"不在这一包里"，不让整份备份失败。
+                Err(error) if error.kind() == std::io::ErrorKind::NotFound => continue,
+                Err(error) => return Err(SavesWriteError::io(&path, &error)),
+            };
+            if meta.file_type().is_symlink() {
+                out.skipped += 1;
+                continue;
+            }
+            if meta.is_dir() {
+                out.dirs.push(format!("{name}/"));
+                guard_entries(&path, out.dirs.len() + out.files.len(), limits)?;
+                stack.push((path, name));
+                continue;
+            }
+            let length = meta.len();
+            out.total = out.total.saturating_add(length);
+            out.files.push((name, path, length));
+            guard_total(world, out.total, limits)?;
+            guard_entries(world, out.dirs.len() + out.files.len(), limits)?;
+        }
+    }
+    Ok(out)
+}
+
+fn guard_total(path: &Path, total: u64, limits: Limits) -> Result<(), SavesWriteError> {
+    if total >= limits.total {
+        return Err(SavesWriteError::new(
+            path,
+            SavesWriteKind::TooLarge,
+            format!(
+                "世界未压缩总量超过上限 {} 字节（写出的包不写 ZIP64，所以上限压在 4 GiB 之下）",
+                limits.total
+            ),
+        ));
+    }
+    Ok(())
+}
+
+fn guard_entries(path: &Path, count: usize, limits: Limits) -> Result<(), SavesWriteError> {
+    if count > limits.entries {
+        return Err(SavesWriteError::new(
+            path,
+            SavesWriteKind::TooLarge,
+            format!("条目数 {count} 超过上限 {}", limits.entries),
+        ));
+    }
+    Ok(())
+}
+
+/// 真正的 zip 写入（`temp` 由调用方负责在失败时删掉）。
+fn write_zip(plan: &Plan, temp: &Path, limits: Limits) -> Result<(), SavesWriteError> {
+    let file = File::create(temp).map_err(|error| SavesWriteError::io(temp, &error))?;
+    let mut writer = zip::ZipWriter::new(file);
+    let options = zip::write::SimpleFileOptions::default()
+        .compression_method(zip::CompressionMethod::Deflated)
+        .unix_permissions(0o644);
+
+    for dir in &plan.dirs {
+        writer
+            .add_directory(dir.as_str(), options)
+            .map_err(|error| SavesWriteError::new(temp, SavesWriteKind::Io, error.to_string()))?;
+    }
+    // 第二道闸：**已写出**的未压缩字节数从 0 起算，与预检结果无关（不重复累计）。
+    let mut written = Written::default();
+    let mut buffer = vec![0_u8; COPY_CHUNK];
+    for (name, source, _) in &plan.files {
+        let mut handle = File::open(source).map_err(|error| SavesWriteError::io(source, &error))?;
+        writer
+            .start_file(name.as_str(), options)
+            .map_err(|error| SavesWriteError::new(source, SavesWriteKind::Io, error.to_string()))?;
+        loop {
+            let read = handle
+                .read(&mut buffer)
+                .map_err(|error| SavesWriteError::io(source, &error))?;
+            if read == 0 {
+                break;
+            }
+            writer.write_all(&buffer[..read]).map_err(|error| {
+                SavesWriteError::new(temp, SavesWriteKind::Io, error.to_string())
+            })?;
+            written.spend(temp, read as u64, limits)?;
+        }
+    }
+    writer
+        .finish()
+        .map_err(|error| SavesWriteError::new(temp, SavesWriteKind::Io, error.to_string()))?;
+    Ok(())
+}
+
+/// 写循环的第二道闸（**已写出**的未压缩字节数）。
+///
+/// 起点是 0，**与预检的结果无关**：拿预检的返回值当基数会把全量声明尺寸再累加一遍
+/// （`addon::pack::format::write::Written` 上记着同一条 P2-1 教训）。
+#[derive(Default)]
+struct Written {
+    total: u64,
+}
+
+impl Written {
+    /// 记一笔实际写出的字节，每一块之后过闸（大文件能在中途被拦下）。
+    fn spend(&mut self, path: &Path, bytes: u64, limits: Limits) -> Result<(), SavesWriteError> {
+        self.total = self.total.saturating_add(bytes);
+        guard_total(path, self.total, limits)
+    }
+}
+
+/// 落点名：`<世界名>-<时戳>.zip`，撞名顺延（见模块文档）。
+fn unique_target(dest_dir: &Path, world: &str, at: SystemTime) -> Result {
+    let stem = format!("{world}-{}", stamp(at));
+    for suffix in 1..=MAX_SUFFIX {
+        let name = if suffix == 1 {
+            format!("{stem}.{BACKUP_EXT}")
+        } else {
+            format!("{stem}-{suffix}.{BACKUP_EXT}")
+        };
+        let candidate = dest_dir.join(name);
+        match std::fs::symlink_metadata(&candidate) {
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(candidate),
+            Ok(_) => {}
+            Err(error) => return Err(SavesWriteError::io(&candidate, &error)),
+        }
+    }
+    Err(SavesWriteError::new(
+        dest_dir,
+        SavesWriteKind::Conflict,
+        format!("`{stem}` 的同名备份已经有 {MAX_SUFFIX} 份，换个落点目录再试"),
+    ))
+}
+
+/// 与目标同目录的临时文件名（同卷 `rename` 才能原子替换）。
+fn temporary_path(target: &Path) -> PathBuf {
+    let mut name = target.file_name().map_or_else(
+        || std::ffi::OsString::from("backup"),
+        std::ffi::OsStr::to_os_string,
+    );
+    name.push(".part");
+    target.with_file_name(name)
+}
+
+/// `SystemTime` → `YYYYMMDD-HHMMSS`（**UTC**，与 `core::launch::time` 同一个时间口径）。
+///
+/// 从 RFC3339 的固定位置切片，不解析、不重排（与页面 `stamp_utc` 同一条做法）。
+#[must_use]
+pub fn stamp(at: SystemTime) -> String {
+    let text = crate::launch::time::format_rfc3339_millis(at);
+    let part = |range: std::ops::Range| text.get(range).unwrap_or_default();
+    format!(
+        "{}{}{}-{}{}{}",
+        part(0..4),
+        part(5..7),
+        part(8..10),
+        part(11..13),
+        part(14..16),
+        part(17..19)
+    )
+}
diff --git a/crates/core/src/game/saves/write/boundary.rs b/crates/core/src/game/saves/write/boundary.rs
new file mode 100644
index 0000000..974d414
--- /dev/null
+++ b/crates/core/src/game/saves/write/boundary.rs
@@ -0,0 +1,196 @@
+//! 写操作的**边界校验**与重命名。
+//!
+//! # 三道校验，每次重做
+//!
+//! [`guard`] 是三个写操作共同的第一句：
+//!
+//! | 第几道 | 查什么 | 失败类别 |
+//! |---|---|---|
+//! | 1 | 名字是单段裸名字（`normalize_file` 之后与原串**原样相等**） | [`SavesWriteKind::UnsafeName`] |
+//! | 2 | `/saves` 是**运行目录的直属子目录**、不是链接、是目录 | `SymbolicLink` / `NotADirectory` / `Boundary` |
+//! | 3 | `saves/` 是真目录（`symlink_metadata`：链接与非目录一律拒） | `SymbolicLink` / `NotADirectory` / `Boundary` |
+//!
+//! ## 为什么第 2 道比的是「父级」而不是字符串前缀
+//!
+//! `Path::starts_with` 是**逐段**比较，看起来够用；但它对「`saves/` 被换成一个指向实例外的
+//! 目录联接」这种情况答不了——解析之后父级已经不是运行目录了。所以两道都比**解析后的父级**：
+//! `saves` 的父级必须**就是**运行目录本身，世界目录的父级必须**就是** `saves`。这样
+//! 「把 `saves` 换成链接」「把世界目录换成链接」两类越界都在同一条判据上被挡住，
+//! 不依赖字符串长什么样。
+//!
+//! ## 为什么第 1 道要「原样相等」而不是「规整后能用」
+//!
+//! `normalize_file` 会**丢弃** `.` 段与空段（`a//b` → `a/b`）。对 zip 条目名那是好意，对
+//! 磁盘上的目录名却是**改名**：用户输入 `a//b`，我们悄悄去动 `a/b`。所以这里要求规整结果与输入
+//! 一字不差——超出的部分（`..`、`/`、`\`、`:`、NUL、绝对路径）由 `normalize_file` 一律拒掉。
+//!
+//! # 重命名的失败顺序
+//!
+//! 先校验**源**（必须是一个真世界），再校验**目标名字**，最后才碰磁盘。目标位置上
+//! **存在任何东西**（目录、文件、坏链接——`symlink_metadata` 都看得见）都算冲突：
+//! 「覆盖别人」这件事不在本 mission 的语义里。
+
+use std::ffi::OsStr;
+use std::path::{Path, PathBuf};
+
+use super::{SavesWriteError, SavesWriteKind};
+use crate::game::saves::{saves_dir, SAVES_DIR};
+
+/// 一次写操作**已校验**的目标。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(super) struct Target {
+    /// `/saves`（**解析后的真实路径**：后续拼名字都拿它当父级）。
+    pub(super) saves: PathBuf,
+    /// `/saves/`（**解析后的真实目录**）。
+    ///
+    /// 它就是这一拍要动的那棵树。解析过 ⇒ 后面 `rename` / 递归删 / 打包都不必再猜路径形态。
+    pub(super) world: PathBuf,
+}
+
+/// 名字 → 单段裸名字（不过规则就给具名错误）。
+///
+/// `anchor` 只用于错误里的路径：给「用户以为自己在动的那一条」。
+pub(super) fn check_name(anchor: &Path, name: &str) -> Result<(), SavesWriteError> {
+    if name.is_empty() {
+        return Err(SavesWriteError::new(
+            anchor,
+            SavesWriteKind::UnsafeName,
+            "名字为空",
+        ));
+    }
+    // 判据复用整合包侧那一份（不在存档这边写第二套规则），再补一条「规整后必须原样相等且只有一段」。
+    // `normalize_file("a/b")` 会把 `a/b` 原样返回（那是包内路径，本来就允许多段），可磁盘上的
+    // **目录名**多一段就落到别处去了——所以这里还要判「只有一段」。
+    match crate::addon::pack::path::normalize_file(name) {
+        Ok(normalized) if normalized == name && !normalized.contains('/') => Ok(()),
+        Ok(_) => Err(SavesWriteError::new(
+            anchor,
+            SavesWriteKind::UnsafeName,
+            format!("名字 `{name}` 不是单段（`/` `\\` `:` `.` 段都不许出现）"),
+        )),
+        Err(error) => Err(SavesWriteError::new(
+            anchor,
+            SavesWriteKind::UnsafeName,
+            format!("名字 `{name}` 过不了路径规则：{error}"),
+        )),
+    }
+}
+
+/// `` + 世界名 → 已校验的目标（见模块文档的三道）。
+pub(super) fn guard(run_dir: &Path, name: &str) -> Result {
+    check_name(run_dir, name)?;
+
+    let run_real = real_dir(run_dir)?;
+    let saves = saves_dir(run_dir);
+    let saves_real = real_dir(&saves)?;
+    // 第 2 道：`saves` 必须是**运行目录的直属子目录**（解析后比父级，不比字符串前缀）。
+    if saves_real.parent() != Some(run_real.as_path())
+        || saves_real.file_name() != Some(OsStr::new(SAVES_DIR))
+    {
+        return Err(SavesWriteError::new(
+            &saves,
+            SavesWriteKind::Boundary,
+            format!(
+                "{} 解析到 {}，不是 {} 的直属 {SAVES_DIR} 目录：拒绝沿它写盘",
+                saves.display(),
+                saves_real.display(),
+                run_real.display()
+            ),
+        ));
+    }
+
+    let world = saves_real.join(name);
+    let world_real = real_dir(&world)?;
+    // 第 3 道：世界目录必须**直接**挂在 `saves/` 下面（解析后比父级）。
+    if world_real.parent() != Some(saves_real.as_path()) {
+        return Err(SavesWriteError::new(
+            &world,
+            SavesWriteKind::Boundary,
+            format!(
+                "{} 解析到 {}，不在 {} 之下：拒绝沿它写盘",
+                world.display(),
+                world_real.display(),
+                saves_real.display()
+            ),
+        ));
+    }
+
+    Ok(Target {
+        saves: saves_real,
+        world: world_real,
+    })
+}
+
+/// 路径 → **解析后的真实目录**（不存在 / 是链接 / 不是目录各给具名类别）。
+///
+/// `symlink_metadata` 先判形态，`canonicalize` 再解析：只解析不看形态的话，`canonicalize`
+/// 会把链接一路跟到底，越界就变成了「正常」。
+fn real_dir(path: &Path) -> Result {
+    let meta = match std::fs::symlink_metadata(path) {
+        Ok(meta) => meta,
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+            return Err(SavesWriteError::new(
+                path,
+                SavesWriteKind::NotFound,
+                "目录不存在",
+            ));
+        }
+        Err(error) => return Err(SavesWriteError::io(path, &error)),
+    };
+    if meta.file_type().is_symlink() {
+        return Err(SavesWriteError::new(
+            path,
+            SavesWriteKind::SymbolicLink,
+            "是符号链接（不跟随：跟下去就动到实例目录之外的东西了）",
+        ));
+    }
+    if !meta.is_dir() {
+        return Err(SavesWriteError::new(
+            path,
+            SavesWriteKind::NotADirectory,
+            "不是目录",
+        ));
+    }
+    std::fs::canonicalize(path).map_err(|error| SavesWriteError::io(path, &error))
+}
+
+/// 重命名一个世界目录：`saves/` → `saves/`。
+///
+/// 返回**新的世界目录**（解析后的路径）。判据顺序见模块文档：源、目标名字、目标位置，最后才动盘。
+///
+/// # Errors
+///
+/// | 情况 | 类别 |
+/// |---|---|
+/// | 源不是 `saves/` 里的真目录（越界 / 链接 / 不在 / 不是目录） | `Boundary` / `SymbolicLink` / `NotFound` / `NotADirectory` |
+/// | 新名字过不了名字规则 | [`SavesWriteKind::UnsafeName`] |
+/// | 新名字与原名字相同，或目标位置已存在任何东西 | [`SavesWriteKind::Conflict`] |
+/// | `rename` 本身失败（权限 / 被占用） | [`SavesWriteKind::Io`] |
+pub fn rename_world(run_dir: &Path, from: &str, to: &str) -> Result {
+    let target = guard(run_dir, from)?;
+    // 目标名字先在**已校验的 saves 目录**上查规则（锚点用 saves，比 run_dir 更贴用户看到的那一条）。
+    check_name(&target.saves, to)?;
+    let dest = target.saves.join(to);
+    if to == from {
+        return Err(SavesWriteError::new(
+            &dest,
+            SavesWriteKind::Conflict,
+            "新名字与原名字相同",
+        ));
+    }
+    match std::fs::symlink_metadata(&dest) {
+        // 目标位置上有东西（目录 / 文件 / 坏链接）就拒：本操作不覆盖别人。
+        Ok(_) => {
+            return Err(SavesWriteError::new(
+                &dest,
+                SavesWriteKind::Conflict,
+                "目标位置已存在（先给它换个名字，或换一个名字给这个世界）",
+            ));
+        }
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
+        Err(error) => return Err(SavesWriteError::io(&dest, &error)),
+    }
+    std::fs::rename(&target.world, &dest)
+        .map_err(|error| SavesWriteError::io(&target.world, &error))?;
+    Ok(dest)
+}
diff --git a/crates/core/src/game/saves/write/remove.rs b/crates/core/src/game/saves/write/remove.rs
new file mode 100644
index 0000000..dd39273
--- /dev/null
+++ b/crates/core/src/game/saves/write/remove.rs
@@ -0,0 +1,90 @@
+//! 递归删除一个世界目录（**不跟随符号链接**，层级有上限）。
+//!
+//! # 为什么不直接 `std::fs::remove_dir_all`
+//!
+//! 两个理由，都不是洁癖：
+//!
+//! 1. **要能说清「删了什么」**。`remove_dir_all` 是一次黑盒调用，失败时只给「最后一个错误」；
+//!    这里逐条走，出错时能指认是哪一条路径（[`SavesWriteError::path`] 就是它）。
+//! 2. **要有一条自己写死的不跟随判据**。标准库文档保证 `remove_dir_all` 不跟随符号链接，
+//!    但它是「实现保证」而不是「本模块的判据」——本模块把这件事写进自己的循环里：
+//!    `symlink_metadata` 判形态，链接只删链接本身（[`remove_link`]），绝不递归进去。
+//!    unix 下 `remove_file` 对「指向目录的链接」也有效（unlink 删的是链接），
+//!    Windows 下目录链接要 `remove_dir`——两个都试一次，这就是 `remove_link` 的全部内容。
+//!
+//! # 层级上限
+//!
+//! 超过 [`MAX_DEPTH`] 层就报 [`SavesWriteKind::Boundary`]：真实的存档是
+//! `world/{region,DIM-1/region,...}` 这种三到四层，六十层只可能是「这不是一个世界目录」。
+//! 没有这道闸时，一次误传的路径会在删除上耗掉用户不想要的长时间（而删除是不可逆的）。
+//!
+//! # 边界
+//!
+//! 判据是「检查那一刻」的快照：检查与 `read_dir` 之间被人换掉组件（TOCTOU）看不到。
+//! 本命令不是并发/对抗入口，不做跨进程锁（与 `game::adopt::run_dir` 同一条已知边界）。
+
+use std::path::{Path, PathBuf};
+
+use super::boundary::guard;
+use super::{SavesWriteError, SavesWriteKind};
+
+/// 递归删除的最大层级（见模块文档）。
+pub const MAX_DEPTH: usize = 64;
+
+/// 删除一个世界目录（递归），返回被删掉的那个目录（**解析后的真实路径**）。
+///
+/// 第一句永远是 [`guard`]：源必须是 `/saves` 下的真目录。越界、符号链接、
+/// 不存在的目标各自给具名类别，**一个字节都不删**。
+///
+/// # Errors
+///
+/// | 情况 | 类别 |
+/// |---|---|
+/// | 源越界 / 是链接 / 不在 / 不是目录 | `Boundary` / `SymbolicLink` / `NotFound` / `NotADirectory` |
+/// | 目录层级超过 [`MAX_DEPTH`] | [`SavesWriteKind::Boundary`] |
+/// | 删某一条失败（权限 / 被占用） | [`SavesWriteKind::Io`]（`path` 指出卡在哪一条） |
+pub fn delete_world(run_dir: &Path, name: &str) -> Result {
+    let target = guard(run_dir, name)?;
+    remove_tree(&target.world, 0)?;
+    Ok(target.world)
+}
+
+/// 删掉 `dir` 这一棵（`depth` 从 0 起算）。
+fn remove_tree(dir: &Path, depth: usize) -> Result<(), SavesWriteError> {
+    if depth > MAX_DEPTH {
+        return Err(SavesWriteError::new(
+            dir,
+            SavesWriteKind::Boundary,
+            format!("目录层级超过 {MAX_DEPTH} 层，不像一个世界目录：拒绝继续往下删"),
+        ));
+    }
+    let read = std::fs::read_dir(dir).map_err(|error| SavesWriteError::io(dir, &error))?;
+    for entry in read {
+        let entry = entry.map_err(|error| SavesWriteError::io(dir, &error))?;
+        let path = entry.path();
+        let meta = match std::fs::symlink_metadata(&path) {
+            Ok(meta) => meta,
+            // 刚被判据挡住又在两步之间消失：目标已经没了，继续删剩下的。
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => continue,
+            Err(error) => return Err(SavesWriteError::io(&path, &error)),
+        };
+        let file_type = meta.file_type();
+        if file_type.is_symlink() {
+            // **只删链接本身**：链接指向的东西不在本操作的范围里。
+            remove_link(&path)?;
+        } else if file_type.is_dir() {
+            remove_tree(&path, depth + 1)?;
+        } else {
+            std::fs::remove_file(&path).map_err(|error| SavesWriteError::io(&path, &error))?;
+        }
+    }
+    std::fs::remove_dir(dir).map_err(|error| SavesWriteError::io(dir, &error))
+}
+
+/// 删一条符号链接自身（unix 用 `remove_file`，Windows 的目录链接要用 `remove_dir`）。
+fn remove_link(path: &Path) -> Result<(), SavesWriteError> {
+    match std::fs::remove_file(path) {
+        Ok(()) => Ok(()),
+        Err(first) => std::fs::remove_dir(path).map_err(|_| SavesWriteError::io(path, &first)),
+    }
+}
diff --git a/crates/core/src/game/saves/write/tests.rs b/crates/core/src/game/saves/write/tests.rs
new file mode 100644
index 0000000..0bc3c31
--- /dev/null
+++ b/crates/core/src/game/saves/write/tests.rs
@@ -0,0 +1,371 @@
+//! 写操作的判据：**真的在盘上建目录再动它**（不 mock 文件系统）。
+//!
+//! # 每个用例抓得住什么
+//!
+//! | 用例 | 抓得住 |
+//! |---|---|
+//! | [`rename_moves_only_the_named_world`] | 改名真的搬了目录、世界内容原样、别的世界不动 |
+//! | [`rename_refuses_conflicts_and_bad_names`] | 撞名 / 同名 / 非法字符 / 分隔符 / 穿越全部拒，且**盘上一个字节没变** |
+//! | [`traversal_is_refused_before_touching_the_disk`] | `saves/../..` 这类名字被挡在名字规则上，`saves/` 之外的东西不受影响 |
+//! | [`saves_must_be_a_plain_child_of_the_run_dir`] | `saves/` 被占成文件 ⇒ 具名错误；被换成链接 ⇒ 拒（`cfg(unix)`） |
+//! | [`symlinks_are_never_followed`] | 世界目录是链接 ⇒ 三个操作都拒、链接指向的那棵树**一根毫毛没少**（`cfg(unix)`） |
+//! | [`nested_symlinks_are_removed_or_skipped`] | 世界**内部**的链接：删除只删链接、备份跳过并计数（`cfg(unix)`） |
+//! | [`delete_removes_one_world_and_bumps_the_parent_mtime`] | 只删指名的那一个；`saves/` 的 mtime 变了、别的世界的 mtime 没变 |
+//! | [`backup_writes_a_timestamped_zip`] | 时戳命名、条目与内容能读回来、目录条目也在 |
+//! | [`backup_never_overwrites_an_earlier_export`] | 同一时刻两份备份 ⇒ `-2` 后缀，前一份内容不变 |
+//! | [`backup_limits_are_checked_before_any_byte_is_written`] | 超限 ⇒ `TooLarge` 且落点目录**一个文件都没有** |
+//! | [`missing_targets_are_named`] | 不存在的世界 / 不是目录 / 没有 `saves/` 各给具名类别 |
+//!
+//! # 变异自证（M247 的门禁要求）
+//!
+//! 把 `boundary::guard` 里那三道的**第二、三道**（`saves` 与世界的父级判据 + `real_dir` 的
+//! 链接判据）删掉之后，[`symlinks_are_never_followed`] 与
+//! [`saves_must_be_a_plain_child_of_the_run_dir`] 必红——报告里附的是实测输出，不是推测。
+//! 只删第一道（名字规则）则 [`traversal_is_refused_before_touching_the_disk`] 与
+//! [`rename_refuses_conflicts_and_bad_names`] 必红。
+
+use std::path::{Path, PathBuf};
+use std::time::{Duration, SystemTime};
+
+use super::*;
+use crate::addon::temp::TempRoot;
+use crate::game::saves::{saves_dir, SAVES_DIR};
+
+mod backup;
+
+/// 一个只跑一帧的临时运行目录（`TempRoot::under` 返回时父级已被删，所以要自己建）。
+fn run_dir(tag: &str) -> TempRoot {
+    let root = TempRoot::under(tag, "run");
+    std::fs::create_dir_all(&root).expect("建运行目录");
+    root
+}
+
+/// 在 `saves/` 下造一个世界（两个文件 + 两层目录）。
+fn world(root: &Path, name: &str) -> PathBuf {
+    let dir = saves_dir(root).join(name);
+    std::fs::create_dir_all(dir.join("region")).expect("建世界子目录");
+    std::fs::write(dir.join("level.dat"), b"nbt").expect("写 level.dat");
+    std::fs::write(dir.join("region/r.0.0.mca"), b"chunk").expect("写 region");
+    dir
+}
+
+/// `(相对路径, 是否目录, 字节数, mtime 毫秒)` 的排序列表——「盘上没变」的判据本体。
+fn fingerprint(root: &Path) -> Vec {
+    let mut out = Vec::new();
+    let mut stack = vec![root.to_path_buf()];
+    while let Some(dir) = stack.pop() {
+        let Ok(read) = std::fs::read_dir(&dir) else {
+            continue;
+        };
+        for entry in read.flatten() {
+            let path = entry.path();
+            let Ok(meta) = std::fs::symlink_metadata(&path) else {
+                continue;
+            };
+            let rel = path
+                .strip_prefix(root)
+                .unwrap_or(&path)
+                .display()
+                .to_string();
+            out.push(format!(
+                "{rel}|dir={}|len={}|mtime={}",
+                meta.is_dir(),
+                meta.len(),
+                meta.modified()
+                    .ok()
+                    .and_then(|time| time.duration_since(SystemTime::UNIX_EPOCH).ok())
+                    .map_or(0, |since| since.as_millis())
+            ));
+            if meta.is_dir() {
+                stack.push(path);
+            }
+        }
+    }
+    out.sort();
+    out
+}
+
+/// 改名真的搬了目录、世界内容原样、别的世界不动。
+#[test]
+fn rename_moves_only_the_named_world() {
+    let root = run_dir("m247-rename");
+    world(&root, "Alpha");
+    world(&root, "Beta");
+    let beta_before = fingerprint(&saves_dir(&root).join("Beta"));
+
+    let moved = rename_world(&root, "Alpha", "Alpha Renamed").expect("改名");
+    assert!(moved.ends_with("Alpha Renamed"));
+    assert!(!saves_dir(&root).join("Alpha").exists(), "旧目录还在");
+    let new = saves_dir(&root).join("Alpha Renamed");
+    assert_eq!(
+        std::fs::read(new.join("level.dat")).expect("读 level.dat"),
+        b"nbt",
+        "改名把内容搬丢了"
+    );
+    assert!(new.join("region/r.0.0.mca").exists(), "子目录没跟过来");
+    assert_eq!(
+        fingerprint(&saves_dir(&root).join("Beta")),
+        beta_before,
+        "改名动了别的世界"
+    );
+}
+
+/// 撞名 / 同名 / 非法字符 / 分隔符 / 穿越全部拒，且**盘上一个字节没变**。
+#[test]
+fn rename_refuses_conflicts_and_bad_names() {
+    let root = run_dir("m247-rename-bad");
+    world(&root, "Alpha");
+    world(&root, "Beta");
+    let before = fingerprint(&root);
+
+    let cases: &[(&str, &str, SavesWriteKind)] = &[
+        ("Alpha", "Beta", SavesWriteKind::Conflict),
+        ("Alpha", "Alpha", SavesWriteKind::Conflict),
+        ("Alpha", "../escape", SavesWriteKind::UnsafeName),
+        ("Alpha", "a/b", SavesWriteKind::UnsafeName),
+        ("Alpha", "a\\b", SavesWriteKind::UnsafeName),
+        ("Alpha", "C:evil", SavesWriteKind::UnsafeName),
+        ("Alpha", "..", SavesWriteKind::UnsafeName),
+        ("Alpha", ".", SavesWriteKind::UnsafeName),
+        ("Alpha", "", SavesWriteKind::UnsafeName),
+        // 源自己也不许穿越
+        ("../Alpha", "Other", SavesWriteKind::UnsafeName),
+        ("saves/../Alpha", "Other", SavesWriteKind::UnsafeName),
+        ("", "Other", SavesWriteKind::UnsafeName),
+    ];
+    for (from, to, kind) in cases {
+        let error =
+            rename_world(&root, from, to).expect_err(&format!("{from} → {to:?} 居然成功了"));
+        assert_eq!(error.kind, *kind, "{from} → {to:?}：{}", error.detail);
+    }
+    assert_eq!(fingerprint(&root), before, "被拒的改名动了磁盘");
+}
+
+/// `saves/../..` 这类名字被挡在名字规则上，`saves/` 之外的东西不受影响。
+#[test]
+fn traversal_is_refused_before_touching_the_disk() {
+    let root = run_dir("m247-traversal");
+    world(&root, "Alpha");
+    // `saves/` 之外的哨兵：任何一次越界删除都会把它带走。
+    std::fs::write(root.join("sentinel.txt"), b"keep me").expect("写哨兵");
+    let outside = root.parent().expect("临时目录一定有父级");
+    let before = fingerprint(&root);
+
+    for name in [
+        "../..",
+        "..",
+        "../../sentinel.txt",
+        "saves/../..",
+        "/etc",
+        "C:/Windows",
+        ".",
+        "",
+    ] {
+        let error = delete_world(&root, name).expect_err(&format!("删 {name:?} 居然成功了"));
+        assert_eq!(
+            error.kind,
+            SavesWriteKind::UnsafeName,
+            "{name:?}：{}",
+            error.detail
+        );
+        let error = backup_world(&root, name, &root.join("exports"))
+            .expect_err(&format!("备份 {name:?} 居然成功了"));
+        assert_eq!(error.kind, SavesWriteKind::UnsafeName);
+    }
+    assert_eq!(fingerprint(&root), before, "越界尝试动了磁盘");
+    assert!(root.join("sentinel.txt").exists(), "哨兵被删了");
+    assert!(!outside.join("exports").exists(), "备份在实例外建了目录");
+}
+
+/// `saves/` 必须是运行目录下的**真目录**：被占成文件 ⇒ 具名错误；被换成链接 ⇒ 拒。
+#[test]
+fn saves_must_be_a_plain_child_of_the_run_dir() {
+    // 被占成文件
+    let root = run_dir("m247-saves-file");
+    std::fs::write(saves_dir(&root), b"not a dir").expect("用文件占住 saves");
+    let error = delete_world(&root, "Alpha").expect_err("saves 是文件，居然删成功了");
+    assert_eq!(error.kind, SavesWriteKind::NotADirectory);
+
+    // 没有 saves/
+    let empty = run_dir("m247-no-saves");
+    let error = delete_world(&empty, "Alpha").expect_err("没有 saves/，居然删成功了");
+    assert_eq!(error.kind, SavesWriteKind::NotFound);
+
+    // 被换成符号链接（指到实例之外）
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::symlink;
+        let linked = run_dir("m247-saves-link");
+        let elsewhere = linked.parent().expect("父级").join("elsewhere-saves");
+        std::fs::create_dir_all(elsewhere.join("Alpha")).expect("建实例外世界");
+        std::fs::write(elsewhere.join("Alpha/level.dat"), b"nbt").expect("写实例外 level.dat");
+        symlink(&elsewhere, saves_dir(&linked)).expect("建 saves 链接");
+        let error = delete_world(&linked, "Alpha").expect_err("saves 是链接，居然删成功了");
+        assert_eq!(error.kind, SavesWriteKind::SymbolicLink, "{}", error.detail);
+        assert!(
+            elsewhere.join("Alpha/level.dat").exists(),
+            "顺着 saves 链接把实例外的世界删了"
+        );
+    }
+}
+
+/// 世界目录是链接 ⇒ 三个操作都拒、链接指向的那棵树一根毫毛没少（`cfg(unix)`）。
+#[cfg(unix)]
+#[test]
+fn symlinks_are_never_followed() {
+    use std::os::unix::fs::symlink;
+
+    let root = run_dir("m247-symlink-world");
+    std::fs::create_dir_all(saves_dir(&root)).expect("建 saves");
+    let elsewhere = root.parent().expect("父级").join("shared-world");
+    std::fs::create_dir_all(elsewhere.join("region")).expect("建实例外世界");
+    std::fs::write(elsewhere.join("level.dat"), b"nbt").expect("写 level.dat");
+    symlink(&elsewhere, saves_dir(&root).join("Linked")).expect("建世界链接");
+
+    let before = fingerprint(&elsewhere);
+    for error in [
+        rename_world(&root, "Linked", "Copied").expect_err("链接世界居然改名成功了"),
+        delete_world(&root, "Linked").expect_err("链接世界居然删成功了"),
+        backup_world(&root, "Linked", &root.join("exports")).expect_err("链接世界居然备份成功了"),
+    ] {
+        assert_eq!(error.kind, SavesWriteKind::SymbolicLink, "{}", error.detail);
+    }
+    assert_eq!(fingerprint(&elsewhere), before, "跟着链接动了实例外的目录");
+}
+
+/// Windows 上「不跟随链接」的可执行证据：**目录联接（junction）不需要管理员权限**，
+/// 所以这条判据在 Windows 上真的跑得起来（`symlink_dir` 要提权 / 开发者模式，跑不了）。
+///
+/// 判据是「拒 + 实例外那棵树一根毫毛没少」；具体的具名类别两档都算过：
+/// 联接被 `symlink_metadata` 认成链接 ⇒ `SymbolicLink`（**M247 实测就是这一档**）；
+/// 只被解析成目录 ⇒「`saves` 的直属子目录」那道父级判据把它拦成 `Boundary`。
+#[cfg(windows)]
+#[test]
+fn junctions_are_never_followed() {
+    let root = run_dir("m247-junction-world");
+    std::fs::create_dir_all(saves_dir(&root)).expect("建 saves");
+    let elsewhere = root.parent().expect("父级").join("shared-junction");
+    std::fs::create_dir_all(elsewhere.join("region")).expect("建实例外世界");
+    std::fs::write(elsewhere.join("level.dat"), b"nbt").expect("写 level.dat");
+    let link = saves_dir(&root).join("Linked");
+    // `quiet` 不是洁癖：Windows 上裸 `Command::new` 会给每个子进程开一块控制台，
+    // GUI 父进程下就是桌面上「黑框闪一下」（`tests/child_quiet_guard.rs` 盯着这一条）。
+    let status = crate::platform::child::quiet("cmd")
+        .args(["/C", "mklink", "/J"])
+        .arg(&link)
+        .arg(&elsewhere)
+        .output()
+        .expect("拉起 mklink");
+    assert!(
+        status.status.success(),
+        "mklink /J 失败：{}",
+        String::from_utf8_lossy(&status.stderr)
+    );
+
+    let before = fingerprint(&elsewhere);
+    let error = delete_world(&root, "Linked").expect_err("联接世界居然删成功了");
+    assert!(
+        matches!(
+            error.kind,
+            SavesWriteKind::SymbolicLink | SavesWriteKind::Boundary
+        ),
+        "联接被当成普通目录放过了：{:?} / {}",
+        error.kind,
+        error.detail
+    );
+    let error = backup_world(&root, "Linked", &root.join("exports")).expect_err("居然备份了联接");
+    assert!(matches!(
+        error.kind,
+        SavesWriteKind::SymbolicLink | SavesWriteKind::Boundary
+    ));
+    assert_eq!(fingerprint(&elsewhere), before, "跟着联接动了实例外的目录");
+    // 收尾：先摘掉联接，别让临时根的清理去碰它（`TempRoot` 的 Drop 在下面自己删）。
+    let _ = std::fs::remove_dir(&link);
+}
+
+/// 世界**内部**的链接：删除只删链接、备份跳过并计数（`cfg(unix)`）。
+#[cfg(unix)]
+#[test]
+fn nested_symlinks_are_removed_or_skipped() {
+    use std::os::unix::fs::symlink;
+
+    let root = run_dir("m247-nested-link");
+    let dir = world(&root, "Alpha");
+    let target = root.join("outside.bin");
+    std::fs::write(&target, b"outside").expect("写实例外文件");
+    symlink(&target, dir.join("region/link.bin")).expect("建世界内链接");
+
+    let exports = root.join("exports");
+    let backup = backup_world(&root, "Alpha", &exports).expect("备份");
+    assert_eq!(backup.skipped, 1, "世界内的链接要跳过并计数");
+
+    delete_world(&root, "Alpha").expect("删世界");
+    assert!(!dir.exists(), "世界目录还在");
+    assert!(target.exists(), "删世界时把链接指向的实例外文件也删了");
+}
+
+/// 只删指名的那一个；`saves/` 的 mtime 变了、别的世界的 mtime 没变。
+#[test]
+fn delete_removes_one_world_and_bumps_the_parent_mtime() {
+    let root = run_dir("m247-delete");
+    world(&root, "Alpha");
+    world(&root, "Beta");
+    let saves = saves_dir(&root);
+    let parent_before = mtime(&saves);
+    let beta_before = mtime(&saves.join("Beta"));
+    let beta_tree = fingerprint(&saves.join("Beta"));
+    // mtime 的粒度可能是一秒（FAT / 一些网络盘），睡一下再删，判据才有分辨力。
+    std::thread::sleep(Duration::from_millis(20));
+
+    delete_world(&root, "Alpha").expect("删世界");
+    assert!(!saves.join("Alpha").exists(), "世界目录还在");
+    assert_eq!(
+        fingerprint(&saves.join("Beta")),
+        beta_tree,
+        "删除动了别的世界"
+    );
+    assert_eq!(
+        mtime(&saves.join("Beta")),
+        beta_before,
+        "别的世界的 mtime 变了"
+    );
+    assert!(
+        mtime(&saves) >= parent_before,
+        "saves/ 的 mtime 应该跟着变（{} → {}）",
+        parent_before,
+        mtime(&saves)
+    );
+}
+
+/// 不存在的世界 / 不是目录 / 没有 `saves/` 各给具名类别。
+#[test]
+fn missing_targets_are_named() {
+    let root = run_dir("m247-missing");
+    world(&root, "Alpha");
+    std::fs::write(saves_dir(&root).join("loose.txt"), b"x").expect("写散落文件");
+
+    let error = delete_world(&root, "Nope").expect_err("不存在的世界居然删成功了");
+    assert_eq!(error.kind, SavesWriteKind::NotFound);
+    let error = delete_world(&root, "loose.txt").expect_err("文件居然被当成世界删了");
+    assert_eq!(error.kind, SavesWriteKind::NotADirectory);
+    let error = backup_world(&root, "Nope", &root.join("exports2")).expect_err("居然备份成功");
+    assert_eq!(error.kind, SavesWriteKind::NotFound);
+    assert!(
+        saves_dir(&root).join("loose.txt").exists(),
+        "散落文件被动了"
+    );
+    assert_eq!(
+        saves_dir(&root).file_name().unwrap().to_string_lossy(),
+        SAVES_DIR,
+        "路径拼接口径"
+    );
+}
+
+/// mtime（毫秒；取不到给 0）。
+fn mtime(path: &Path) -> u128 {
+    std::fs::metadata(path)
+        .and_then(|meta| meta.modified())
+        .ok()
+        .and_then(|time| time.duration_since(SystemTime::UNIX_EPOCH).ok())
+        .map_or(0, |since| since.as_millis())
+}
diff --git a/crates/core/src/game/saves/write/tests/backup.rs b/crates/core/src/game/saves/write/tests/backup.rs
new file mode 100644
index 0000000..44706e5
--- /dev/null
+++ b/crates/core/src/game/saves/write/tests/backup.rs
@@ -0,0 +1,154 @@
+//! 备份（zip 导出）那几条判据——从 `write/tests.rs` 拆出：那边加完 11 条用例之后越过 400 行硬线
+//! （拆法与仓库其它 `-p1/-p2` / `tail*` 一致：**纯搬移，判据一条不改**）。
+//!
+//! | 用例 | 抓得住 |
+//! |---|---|
+//! | [`backup_writes_a_timestamped_zip`] | 时戳命名、条目与内容能读回来、空目录条目也在 |
+//! | [`backup_never_overwrites_an_earlier_export`] | 同一时刻两份备份 ⇒ `-2` 后缀，前一份不变 |
+//! | [`backup_limits_are_checked_before_any_byte_is_written`] | 超限 ⇒ `TooLarge` 且落点目录一个文件都没有 |
+//! | [`backup_refuses_a_relative_or_empty_dest`] | 空 / 相对的落点 ⇒ `Boundary`（相对路径会落到进程当前目录） |
+
+use std::io::Read;
+use std::path::PathBuf;
+use std::time::{Duration, SystemTime};
+
+use super::super::backup::{backup_world_at, stamp, Limits};
+use super::super::*;
+use super::{fingerprint, run_dir, world};
+
+/// 2024-05-01 10:00:00 UTC（写死的时刻：时戳命名要能逐字断言）。
+fn fixed_at() -> SystemTime {
+    SystemTime::UNIX_EPOCH + Duration::from_millis(1_714_557_600_000)
+}
+
+/// 时戳命名、条目与内容能读回来、目录条目也在。
+#[test]
+fn backup_writes_a_timestamped_zip() {
+    let root = run_dir("m247-backup");
+    let dir = world(&root, "Alpha");
+    std::fs::create_dir_all(dir.join("empty-dir")).expect("建空目录");
+    let exports = root.join("exports");
+
+    let backup =
+        backup_world_at(&root, "Alpha", &exports, fixed_at(), Limits::production()).expect("备份");
+    assert_eq!(
+        backup.path.file_name().unwrap().to_string_lossy(),
+        "Alpha-20240501-100000.zip",
+        "落点名要带 UTC 时戳"
+    );
+    assert_eq!(backup.skipped, 0);
+    assert!(backup.bytes > 0);
+    assert_eq!(backup.sourced, 8, "level.dat + region 共 8 字节");
+    assert_eq!(
+        backup.entries, 4,
+        "region/ 与 empty-dir/ 两个目录条目 + 两个文件条目"
+    );
+
+    let file = std::fs::File::open(&backup.path).expect("开备份");
+    let mut archive = zip::ZipArchive::new(file).expect("读 zip");
+    let names: Vec = (0..archive.len())
+        .map(|index| {
+            archive
+                .by_index(index)
+                .expect("读条目")
+                .name()
+                .expect("条目名")
+                .to_string()
+        })
+        .collect();
+    assert!(names.contains(&"level.dat".to_string()), "条目：{names:?}");
+    assert!(
+        names.contains(&"region/r.0.0.mca".to_string()),
+        "条目：{names:?}"
+    );
+    assert!(
+        names.contains(&"empty-dir/".to_string()),
+        "空目录丢了：{names:?}"
+    );
+
+    let mut body = Vec::new();
+    archive
+        .by_name("level.dat")
+        .expect("取 level.dat")
+        .read_to_end(&mut body)
+        .expect("读 level.dat");
+    assert_eq!(body, b"nbt", "包里的内容与盘上不一致");
+
+    // 时戳换算本身（同一张固定时刻表）。
+    assert_eq!(stamp(fixed_at()), "20240501-100000");
+}
+
+/// 同一时刻两份备份 ⇒ `-2` 后缀，前一份内容不变。
+#[test]
+fn backup_never_overwrites_an_earlier_export() {
+    let root = run_dir("m247-backup-twice");
+    world(&root, "Alpha");
+    let exports = root.join("exports");
+    let first = backup_world_at(&root, "Alpha", &exports, fixed_at(), Limits::production())
+        .expect("第一次");
+    let body = std::fs::read(&first.path).expect("读第一份");
+    let second = backup_world_at(&root, "Alpha", &exports, fixed_at(), Limits::production())
+        .expect("第二次");
+
+    assert_ne!(first.path, second.path, "第二份覆盖了第一份");
+    assert_eq!(
+        second.path.file_name().unwrap().to_string_lossy(),
+        "Alpha-20240501-100000-2.zip"
+    );
+    assert_eq!(
+        std::fs::read(&first.path).expect("读第一份"),
+        body,
+        "第一份被改了"
+    );
+}
+
+/// 超限 ⇒ `TooLarge` 且落点目录**一个文件都没有**（闸在第一个字节之前）。
+#[test]
+fn backup_limits_are_checked_before_any_byte_is_written() {
+    let root = run_dir("m247-backup-limit");
+    world(&root, "Alpha");
+    let exports = root.join("exports");
+
+    // 总量闸：世界有 8 字节，上限给 4。
+    let error = backup_world_at(&root, "Alpha", &exports, fixed_at(), Limits::new(4, 100))
+        .expect_err("超限居然备份成功了");
+    assert_eq!(error.kind, SavesWriteKind::TooLarge, "{}", error.detail);
+    assert!(!exports.exists(), "超限时连落点目录都不该建");
+
+    // 条目闸：4 个条目 + 上限给 2。
+    let error = backup_world_at(
+        &root,
+        "Alpha",
+        &exports,
+        fixed_at(),
+        Limits::new(1 << 30, 2),
+    )
+    .expect_err("条目超限居然备份成功了");
+    assert_eq!(error.kind, SavesWriteKind::TooLarge);
+    assert!(
+        !exports.exists()
+            || std::fs::read_dir(&exports)
+                .expect("读落点")
+                .next()
+                .is_none(),
+        "超限时写出了文件"
+    );
+}
+
+/// 落点目录必须是绝对路径：相对路径会落到进程当前目录（一次实测里 `dest = ""` 把 zip
+/// 写进了 crate 根），所以「空 / 相对」直接拒。
+#[test]
+fn backup_refuses_a_relative_or_empty_dest() {
+    let root = run_dir("m247-backup-dest");
+    world(&root, "Alpha");
+    let before = fingerprint(&root);
+    for dest in [
+        PathBuf::new(),
+        PathBuf::from("exports"),
+        PathBuf::from("./exports"),
+    ] {
+        let error = backup_world(&root, "Alpha", &dest).expect_err("相对落点居然备份成功了");
+        assert_eq!(error.kind, SavesWriteKind::Boundary, "{}", error.detail);
+    }
+    assert_eq!(fingerprint(&root), before, "被拒的备份动了磁盘");
+}
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 {
+    data: Arc,
+}
+
+impl Snapshot {
+    /// 用给定内容构造快照。
+    pub fn new(data: T) -> Self {
+        Self {
+            data: Arc::new(data),
+        }
+    }
+
+    /// 读内容。
+    pub fn get(&self) -> &T {
+        &self.data
+    }
+
+    /// 共享同一份内容的强引用。
+    pub fn shared(&self) -> Arc {
+        Arc::clone(&self.data)
+    }
+}
+
+impl Clone for Snapshot {
+    fn clone(&self) -> Self {
+        Self {
+            data: Arc::clone(&self.data),
+        }
+    }
+}
+
+impl fmt::Debug for Snapshot {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_tuple("Snapshot").field(&self.data).finish()
+    }
+}
+
+impl PartialEq for Snapshot {
+    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 {
+        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 {
+    current: RwLock>,
+    writing: AtomicBool,
+}
+
+impl Store {
+    /// 以初始内容建立仓库。
+    pub fn new(initial: T) -> Self {
+        Self {
+            current: RwLock::new(Arc::new(initial)),
+            writing: AtomicBool::new(false),
+        }
+    }
+
+    /// 取当前快照（读路径：一次共享锁 + `Arc` 克隆，锁内不做别的）。
+    pub fn snapshot(&self) -> Snapshot {
+        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, 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, 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,
+    token: WriteToken<'a>,
+    working: T,
+}
+
+impl Draft<'_, T> {
+    /// 读草稿内容。
+    pub fn view(&self) -> &T {
+        &self.working
+    }
+
+    /// 改草稿内容。
+    pub fn edit(&mut self) -> &mut T {
+        &mut self.working
+    }
+
+    /// 发布：把草稿内容换成仓库当前快照，并释放写权。
+    pub fn commit(self) -> Snapshot {
+        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 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 = 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(&self, serializer: S) -> Result {
+        serializer.serialize_str(self.as_json_str())
+    }
+}
+
+impl<'de> Deserialize<'de> for ReleaseType {
+    fn deserialize>(deserializer: D) -> Result {
+        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,
+    /// 最新快照 id。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub snapshot: Option,
+}
+
+/// 版本清单里的一条记录。
+///
+/// `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,
+    /// 该版本的发布时刻（ISO-8601 字符串，排序键）。
+    #[serde(
+        rename = "releaseTime",
+        default,
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub release_time: Option,
+    /// 版本 JSON 的 SHA-1（v2 才有）。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub sha1: Option,
+    /// 版本 JSON 的字节数（v2 才有）。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub size: Option,
+}
+
+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,
+    /// 条目列表。
+    #[serde(default)]
+    pub versions: Vec,
+}
+
+impl VersionList {
+    /// 解析清单 JSON。
+    pub fn from_json_str(json: &str) -> Result {
+        serde_json::from_str(json).map_err(|e| GameError::json("version_manifest", e))
+    }
+
+    /// 序列化回 JSON（便于缓存落盘/测试对拍）。
+    pub fn to_json_string(&self) -> Result {
+        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) -> 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, name: impl Into) -> Self {
+        Self {
+            path: path.into(),
+            name: name.into(),
+        }
+    }
+}
+
+/// 版本快照里 launch 需要的部分（全部是纯数据，不依赖 game 类型）。
+#[derive(Debug, Clone)]
+pub struct SnapshotInput<'a> {
+    /// 版本 id（`versions//`）。
+    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,
+    /// 全屏。
+    pub fullscreen: bool,
+    /// 一键进入。
+    pub quick_play: Option,
+    /// SOCKS 代理。
+    pub proxy: Option,
+    /// 图形后端。
+    pub graphics_backend: Option,
+    /// log4j 配置文件（launch 侧注入）。
+    pub log4j_config: Option,
+    /// `-Dfile.encoding` 指定值。
+    pub encoding: Option,
+    /// 界面语言。
+    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,
+    /// 实际进 classpath 的条目数（库 + 主 jar）。
+    pub classpath_entries: usize,
+    /// 缺失库清单。
+    pub missing: Vec,
+}
+
+/// 把快照 + 选项装配成 [`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 {
+    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,
+    /// 完整 classpath（库 + 主 jar 末位）。
+    pub classpath: Vec,
+    /// 日志解码编码（决定 pump 用什么解码子进程输出）。
+    pub encoding: String,
+    /// 内存设置（与 `-Xmx`/`-Xms` 一致）。
+    pub memory: MemoryOptions,
+    /// 环境变量（实例标识/渲染/加载器/用户自定义）。
+    pub env: Vec<(String, String)>,
+    /// 组装告警。
+    pub warnings: Vec,
+    /// 主类。
+    pub main_class: String,
+}
+
+impl AssembledCommand {
+    /// 完整 argv（`program` 在第一个）。
+    pub fn argv(&self) -> Vec {
+        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 {
+    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 = 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 {
+    let mut classpath: Vec = 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,
+    /// `x86` / `x86_64` / `arm64`。
+    pub arch: Option,
+    /// 系统版本模式（Mojang 用正则，这里只做前缀/子串匹配）。
+    pub version: Option,
+}
+
+/// 单条规则。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Rule {
+    /// 命中后的动作。
+    pub action: RuleAction,
+    /// 系统条件。
+    pub os: Option,
+    /// 特性条件（逐项相等才算命中）。
+    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) -> 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, expected: bool) -> Self {
+        self.features.push((name.into(), expected));
+        self
+    }
+
+    /// 求值：`Some(true)` 命中且允许，`Some(false)` 命中且禁止，`None` 不适用（规则无效）。
+    pub fn evaluate(&self, ctx: &RuleContext<'_>) -> Option {
+        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,
+    /// 取值（每个元素是一个独立命令行 token）。
+    pub values: Vec,
+}
+
+impl ArgumentEntry {
+    /// 无条件参数项。
+    pub fn plain(values: impl IntoIterator>) -> Self {
+        Self {
+            rules: Vec::new(),
+            values: values.into_iter().map(Into::into).collect(),
+        }
+    }
+
+    /// 带规则参数项。
+    pub fn ruled(rules: Vec, values: impl IntoIterator>) -> 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,
+    external: Vec,
+    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) {
+        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,
+    ) {
+        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 {
+        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 {
+        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 {
+        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 {
+        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 {
+        self.args
+    }
+
+    /// 人读形式（含空格的参数加双引号），用于日志与快照测试。
+    pub fn display_args(&self) -> String {
+        self.args
+            .iter()
+            .map(|arg| quote_for_display(arg))
+            .collect::>()
+            .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 {
+    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 {
+    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 {
+    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_bundle.rs b/crates/core/src/launch/crash_bundle.rs
new file mode 100644
index 0000000..6eb9a68
--- /dev/null
+++ b/crates/core/src/launch/crash_bundle.rs
@@ -0,0 +1,364 @@
+//! 诊断包（M187）：把一次启动失败的现场打成一个 zip 交给用户。
+//!
+//! ## 为什么不只是「打开日志文件夹」
+//!
+//! 用户实测（2026-11-08）：「MC 启动失败『游戏崩溃 退出码 1』，找半天没找到崩溃日志」。
+//! 现场散在四处——启动器日志（`.ULL/logs/`）、会话事件流 JSONL（`data/agent/sessions/game/`）、
+//! 游戏自己写的 `crash-reports/` 与 `logs/latest.log`、还有环境（系统 / Java / 命令行）。
+//! 让用户自己去四个目录里拼，等于没修。打成一个包 + 一行清单，才是「能发给别人看」的东西。
+//!
+//! ## 三条纪律
+//!
+//! 1. **落盘即脱敏**（`launch::redact` 的唯一一份规则）：主目录 → ``，token → 占位符，
+//!    长不透明串（base64/hex）与带点 token（JWT 形状）同样替换；调用方另外把**会话 id**
+//!    之类也要抹掉的串塞进 [`BundleSpec::secrets`]。
+//! 2. **缺什么要写出来**：`crash-reports/` 不存在不是错误——那是「游戏没来得及写」的**证据**，
+//!    清单里必须有一行说清楚，不许静默漏掉。见 [`BundleSpec::missing`]。
+//! 3. **有上限**：单个文件最多收 [`MAX_ENTRY_BYTES`]，包内总字节最多 [`MAX_TOTAL_BYTES`]。
+//!    超了就在清单里记一行「已截断」。数百 MB 的 `latest.log` 不该把导出卡成十秒。
+//!
+//! 不做的事：不判断崩溃原因（那是诊断引擎 `diagnose` 的活），不改任何图片之外的二进制，
+//! 不联网。打包只读盘。
+
+use std::fs::File;
+use std::io::Write;
+use std::path::{Path, PathBuf};
+
+use super::redact::Redactor;
+
+/// 单个文件最多收多少字节（超出按**头 + 尾**截断，清单里记「已截断」）。
+///
+/// 为什么不是「只收头部」：崩溃证据在**尾部**——会话 JSONL 的最后几行是 `exit` 事件与
+/// stderr，`latest.log` 的栈也在尾。只留头部的包等于「证据是残的，而用户不知道」。
+pub const MAX_ENTRY_BYTES: u64 = 4 * 1024 * 1024;
+/// 截断时头部保留的字节（另一半点给尾部）。
+pub const HEAD_BYTES: u64 = MAX_ENTRY_BYTES / 2;
+/// 整个包最多收多少字节（超出后剩余文件只记清单、不收内容）。
+pub const MAX_TOTAL_BYTES: u64 = 48 * 1024 * 1024;
+
+/// 一个要进包的文件。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BundleEntry {
+    /// 包内分组（`launcher` / `session` / `game` / `instance`），决定包内目录。
+    pub group: &'static str,
+    /// 源文件绝对路径。
+    pub path: PathBuf,
+    /// 包内固定文件名（`None` = 用源文件名）。
+    ///
+    /// 为什么要能钉死：会话 JSONL 的源文件名就是**会话 id**（`.jsonl`），
+    /// 拿它当条目名要么泄漏 id、要么让「清单里的名字」与「包里的名字」对不上。钉成
+    /// `session.jsonl` 两个问题一起消失（见 [`BundleSpec::entry_names`]）。
+    pub name: Option,
+}
+
+impl BundleEntry {
+    /// 建一条（包内名 = 源文件名）。
+    pub fn new(group: &'static str, path: impl Into) -> Self {
+        Self {
+            group,
+            path: path.into(),
+            name: None,
+        }
+    }
+
+    /// 建一条并**钉死包内文件名**（会话 JSONL、`latest.log` 这类有唯一身份的用它）。
+    pub fn named(group: &'static str, path: impl Into, name: &str) -> Self {
+        Self {
+            group,
+            path: path.into(),
+            name: Some(name.to_string()),
+        }
+    }
+}
+
+/// 一次导出的输入（全部是事实，不含任何结论）。
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct BundleSpec {
+    /// 实例名。
+    pub instance: String,
+    /// 版本 id。
+    pub version: String,
+    /// 会话 id（**同时会被脱敏**）。
+    pub session: String,
+    /// 退出码（`None` = 进程没起来）。
+    pub exit_code: Option,
+    /// 退出判定 slug（`application_error` / `jvm_error` / `normal` …）。
+    pub exit_type: String,
+    /// 存活毫秒数。
+    pub uptime_ms: u64,
+    /// 脱敏后的命令行（**调用方**已经过 [`Redactor::scrub_all`]）。
+    pub command: String,
+    /// Java 一行说明（路径 + 主版本）。
+    pub java: String,
+    /// 系统一行说明（`OsInfo::summary_line`）。
+    pub system: String,
+    /// 额外说明（例如「本次没有生成 crash-report」）。
+    pub notes: Vec,
+    /// 明确不存在的现场（清单里写成「没有：…」）。
+    pub missing: Vec,
+    /// 要收的文件。
+    pub entries: Vec,
+    /// 除了主目录之外还要抹掉的串（会话 id 等）。
+    pub secrets: Vec,
+    /// 用户主目录（`None` = 不抹）。
+    pub home: Option,
+}
+
+impl BundleSpec {
+    /// 清单文本（`manifest.txt`；导出前会再过一遍脱敏）。
+    ///
+    /// 这是「自算条目名」的包装（测试与单独看清单用）；真正落盘时用的是
+    /// [`Self::header`] + 收集循环里长出来的行，保证与包内条目一字不差。
+    #[must_use]
+    pub fn manifest(&self) -> String {
+        let rows: Vec = self
+            .entry_names()
+            .iter()
+            .zip(&self.entries)
+            .map(|(name, entry)| format!("- {name}  <- {}", entry.path.display()))
+            .collect();
+        // 对外出口一律脱敏（r2 复审 P3-6）：不给「谁调谁泄漏」的口子。
+        self.redactor().scrub(&self.header(&rows)).into_owned()
+    }
+
+    /// 清单的**事实段 + files 段**（files 段由调用方给，行内已是最终条目名）。
+    fn header(&self, rows: &[String]) -> String {
+        let mut text = String::new();
+        text.push_str("Unlucky Launcher — launch failure bundle\n");
+        text.push_str("=======================================\n");
+        text.push_str(&format!("instance: {}\n", self.instance));
+        text.push_str(&format!("version: {}\n", self.version));
+        text.push_str(&format!("session: {}\n", self.session));
+        text.push_str(&format!(
+            "exit_code: {}\n",
+            self.exit_code
+                .map(|code| code.to_string())
+                .unwrap_or_else(|| "(none)".to_string())
+        ));
+        text.push_str(&format!("exit_type: {}\n", self.exit_type));
+        text.push_str(&format!("uptime: {:.1}s\n", self.uptime_ms as f64 / 1000.0));
+        text.push_str(&format!("os: {}\n", self.system));
+        text.push_str(&format!("java: {}\n", self.java));
+        text.push_str(&format!("command: {}\n", self.command));
+
+        if !self.notes.is_empty() {
+            text.push_str("\nnotes\n-----\n");
+            for note in &self.notes {
+                text.push_str(&format!("- {note}\n"));
+            }
+        }
+        if !self.missing.is_empty() {
+            text.push_str("\nmissing (不存在)\n----------------\n");
+            for item in &self.missing {
+                text.push_str(&format!("- {item}\n"));
+            }
+        }
+
+        text.push_str("\nfiles\n-----\n");
+        // 清单里的名字**必须**与包里的条目一一对应（r1 复审 P2-2 就是这里对不上）：
+        // 两边都走同一份解析（`rows` 由调用方给出，行内已是最终条目名）：
+        // 清单与 zip 不许各算一遍 —— 各算一遍就是 r1 复审 P2-2。
+        for row in rows {
+            text.push_str(row);
+            text.push('\n');
+        }
+        text
+    }
+
+    /// 包内条目名（与 `entries` 一一对应；**名字也过脱敏**）。
+    ///
+    /// 名字与内容分开治：内容走 `redactor` 的整套规则，名字走同一份 redactor 的 token 规则。
+    /// **两边都以返回值为准**——清单与 zip 都读这一份，不许各算一遍（各算一遍就是 P2-2）。
+    #[must_use]
+    pub fn entry_names(&self) -> Vec {
+        let redactor = self.redactor();
+        self.entries
+            .iter()
+            .map(|entry| {
+                let raw = entry.name.clone().unwrap_or_else(|| file_name(&entry.path));
+                let safe = redactor.scrub(&raw).into_owned();
+                format!("{}/{}", entry.group, safe)
+            })
+            .collect()
+    }
+
+    fn redactor(&self) -> Redactor {
+        let mut redactor = Redactor::new();
+        if let Some(home) = &self.home {
+            redactor = redactor.with_home(home);
+        }
+        for secret in &self.secrets {
+            redactor = redactor.with_secret(secret.clone());
+        }
+        redactor
+    }
+}
+
+/// 一次导出的结果。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Bundle {
+    /// 落盘路径。
+    pub path: PathBuf,
+    /// 字节数（**落盘后**的真实大小）。
+    pub bytes: u64,
+    /// 收进包的文件数（不含清单）。
+    pub files: usize,
+    /// 被截断 / 因总量上限没收内容的文件数。
+    pub truncated: usize,
+}
+
+impl Bundle {
+    /// 一行说明（Toast 与日志共用）。
+    pub fn describe(&self) -> String {
+        format!(
+            "{} ({} bytes, {} files, {} truncated)",
+            self.path.display(),
+            self.bytes,
+            self.files,
+            self.truncated
+        )
+    }
+}
+
+/// 把 `spec` 打成一个 zip 写到 `target`（父目录不存在会建）。
+///
+/// # Errors
+/// 目录建不出来、zip 写失败、清单写失败时返回人话（导出失败要能一眼看出哪一步断）。
+pub fn write_bundle(spec: &BundleSpec, target: &Path) -> Result {
+    let redactor = spec.redactor();
+
+    if let Some(parent) = target.parent() {
+        if !parent.as_os_str().is_empty() {
+            std::fs::create_dir_all(parent)
+                .map_err(|error| format!("建目录 {} 失败：{error}", parent.display()))?;
+        }
+    }
+    let file = File::create(target)
+        .map_err(|error| format!("建诊断包 {} 失败：{error}", target.display()))?;
+    let mut zip = zip::ZipWriter::new(file);
+    let options =
+        zip::write::SimpleFileOptions::default().compression_method(zip::CompressionMethod::Stored);
+
+    // 名字与清单**先在同一个循环里长出来**：`files` 段只列真进了包的条目，
+    // 谁被跳过、谁被截断都在 `collected` 段写明（r1 复审 P2-2 的修法）。
+    let names = spec.entry_names();
+    let mut listed: Vec = Vec::new();
+    let mut collected: Vec = Vec::new();
+    let mut total: u64 = 0;
+    let mut files = 0usize;
+    let mut truncated = 0usize;
+    let mut used: Vec = Vec::new();
+
+    for (index, entry) in spec.entries.iter().enumerate() {
+        let name = unique_name(&mut used, &names[index]);
+        let Ok(bytes) = std::fs::read(&entry.path) else {
+            collected.push(format!("- {name}: 读不出来（已跳过）"));
+            continue;
+        };
+        let original_len = bytes.len();
+        // **唯一的通路**：解码 → 脱敏 → 按字符边界截断（见 `clip.rs` 的模块文档）。
+        // 没有「二进制原样」分支，所以也不存在「截坏一个字就整份跳过脱敏」的旁路
+        // （r2 复审 P2-1）。`lossy` 保证任何字节序列都能进脱敏器。
+        let text = String::from_utf8_lossy(&bytes).into_owned();
+        let scrubbed = redactor.scrub(&text).into_owned();
+        let budget = MAX_TOTAL_BYTES.saturating_sub(total).min(MAX_ENTRY_BYTES);
+        let mut kept = scrubbed;
+        if kept.len() as u64 > budget {
+            let Some(clipped) = clip_text(&kept, budget) else {
+                collected.push(format!("- {name}: 超出总量上限，未收内容"));
+                truncated += 1;
+                continue;
+            };
+            kept = clipped;
+            collected.push(format!(
+                "- {name}: 已截断（收 {} B，原 {original_len} B）",
+                kept.len()
+            ));
+            truncated += 1;
+        }
+        let body = kept.into_bytes();
+        total += body.len() as u64;
+        files += 1;
+        listed.push(format!("- {name}  <- {}", entry.path.display()));
+        write_entry(&mut zip, &name, &body, options)?;
+    }
+
+    let mut manifest = spec.header(&listed);
+    if !collected.is_empty() {
+        manifest.push_str("\ncollected\n---------\n");
+        for line in collected {
+            manifest.push_str(&line);
+            manifest.push('\n');
+        }
+    }
+    write_entry(
+        &mut zip,
+        "manifest.txt",
+        redactor.scrub(&manifest).as_bytes(),
+        options,
+    )?;
+    zip.finish()
+        .map_err(|error| format!("收尾诊断包失败：{error}"))?;
+
+    let bytes = std::fs::metadata(target)
+        .map(|meta| meta.len())
+        .unwrap_or(0);
+    Ok(Bundle {
+        path: target.to_path_buf(),
+        bytes,
+        files,
+        truncated,
+    })
+}
+
+fn write_entry(
+    zip: &mut zip::ZipWriter,
+    name: &str,
+    body: &[u8],
+    options: zip::write::SimpleFileOptions,
+) -> Result<(), String> {
+    zip.start_file(name, options)
+        .map_err(|error| format!("写入 {name} 失败：{error}"))?;
+    zip.write_all(body)
+        .map_err(|error| format!("写入 {name} 失败：{error}"))
+}
+
+fn file_name(path: &Path) -> String {
+    path.file_name()
+        .map(|name| name.to_string_lossy().into_owned())
+        .unwrap_or_else(|| "file".to_string())
+}
+
+/// 包内重名时在**目录名后**加序号（`game/latest.log` 与 `game/2-latest.log` 不会互相覆盖）。
+fn unique_name(used: &mut Vec, name: &str) -> String {
+    let base = name.to_string();
+    if !used.contains(&base) {
+        used.push(base.clone());
+        return base;
+    }
+    let (group, file) = base.split_once('/').unwrap_or(("", base.as_str()));
+    for index in 2.. {
+        let candidate = format!("{group}/{index}-{file}");
+        if !used.contains(&candidate) {
+            used.push(candidate.clone());
+            return candidate;
+        }
+    }
+    unreachable!("序号一定找得到空位")
+}
+
+/// 默认落点：启动器日志分区下的 `exports/`。
+///
+/// 为什么不弹文件选择框：本仓没有 `rfd` 这类原生对话框依赖（Cargo.toml 不在本 mission scope），
+/// 也不该为一次导出引一棵新依赖树。导出后界面把**完整路径**与字节数都给出来，另有
+/// 「打开文件夹」按钮直达——用户不用猜。
+pub fn default_target_dir(logs_dir: &Path) -> PathBuf {
+    logs_dir.join("exports")
+}
+
+mod clip;
+
+use clip::clip_text;
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/core/src/launch/crash_bundle/clip.rs b/crates/core/src/launch/crash_bundle/clip.rs
new file mode 100644
index 0000000..e69731b
--- /dev/null
+++ b/crates/core/src/launch/crash_bundle/clip.rs
@@ -0,0 +1,138 @@
+//! 超限文件的**文本流**截断（头 + 尾），切点落在字符/行边界上。
+//!
+//! ## 为什么截断必须发生在「文本流」里，而不是字节上
+//!
+//! 上一版在**字节**上切两刀（头 2 MiB / 尾 2 MiB），切完才试 `String::from_utf8`
+//! 决定要不要脱敏。中文与 emoji 是 3~4 字节，只要切点落在字中间，`from_utf8` 就失败，
+//! 于是**整份文件退回「原样字节」分支、一条脱敏规则都没跑**（r2 复审 P2-1 抓到的隐私旁路：
+//! 长会话的 `latest.log` 与会话 JSONL 正好是最容易超大、也最该脱敏的两个文件；
+//! 中文 Windows 用户名让家目录串本身就是 CJK，切在它附近必然命中）。
+//!
+//! 现在这条通路只有一种形态：**解码 → 脱敏 → 按字符边界截断**。没有「二进制原样」这条分支，
+//! 也就没有旁路。
+//!
+//! ## 为什么先脱敏再截断（而不是先截断再脱敏）
+//!
+//! 顺序反过来会在切点留下**半截 secret**：被切开的前缀不再匹配任何规则，于是以原文形态留在
+//! 包里。先脱敏就没有这个问题——整串已经变成占位符，截断只能切占位符。
+//!
+//! 代价：要先把整份文本过一遍脱敏器。导出是低频人工动作、上限 4 MiB，代价可以忽略。
+
+/// 在**字符边界**上截断，保留头部与尾部，中间插一行说明。
+///
+/// 返回 `None` 表示不需要截（预算足够或预算为 0）。
+/// 返回值里的 `String` 已按预算裁好；调用方负责把 `truncated` 记进清单。
+pub(super) fn clip_text(text: &str, budget: u64) -> Option {
+    let budget = usize::try_from(budget).unwrap_or(usize::MAX);
+    if budget == 0 || text.len() <= budget {
+        return None;
+    }
+
+    let head_budget = usize::try_from(super::HEAD_BYTES)
+        .unwrap_or(usize::MAX)
+        .min(budget / 2);
+    let tail_budget = budget - head_budget;
+
+    let head_end = snap_back(text, head_budget);
+    let tail_start = snap_forward(text, text.len() - tail_budget);
+    if tail_start <= head_end {
+        return None;
+    }
+
+    let dropped = tail_start - head_end;
+    Some(format!(
+        "{}\n\n{}",
+        &text[..head_end],
+        &text[tail_start..]
+    ))
+}
+
+/// 从 `index` 向左找最近的**行首**，找不到就在字符边界上回退。
+///
+/// 行边界只为可读性：切在一条日志行中间，读的人会以为那份日志本身是坏的。
+fn snap_back(text: &str, index: usize) -> usize {
+    let index = floor_char(text, index);
+    let window = floor_char(text, index.saturating_sub(200));
+    match text[window..index].rfind('\n') {
+        Some(newline) => window + newline + 1,
+        None => index,
+    }
+}
+
+/// 从 `index` 向右找最近的**行首**，找不到就在字符边界上前进。
+fn snap_forward(text: &str, index: usize) -> usize {
+    let index = ceil_char(text, index);
+    let window = ceil_char(text, (index + 200).min(text.len()));
+    match text[index..window].find('\n') {
+        Some(newline) => index + newline + 1,
+        None => index,
+    }
+}
+
+/// 向左回退到最近的字符边界（`str::floor_char_boundary` 仍是 nightly）。
+fn floor_char(text: &str, index: usize) -> usize {
+    let mut at = index.min(text.len());
+    while at > 0 && !text.is_char_boundary(at) {
+        at -= 1;
+    }
+    at
+}
+
+/// 向右前进到最近的字符边界。
+fn ceil_char(text: &str, index: usize) -> usize {
+    let mut at = index.min(text.len());
+    while at < text.len() && !text.is_char_boundary(at) {
+        at += 1;
+    }
+    at
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{clip_text, snap_back, snap_forward};
+    use crate::launch::crash_bundle::MAX_ENTRY_BYTES;
+
+    /// 切点必须落在字符边界上（否则下游 `str` 切片会直接 panic）。
+    #[test]
+    fn cuts_land_on_char_boundaries() {
+        // 每个 CJK 字 3 字节：把边界刻意放在字的中间
+        let text = "中".repeat(2000);
+        let clipped = clip_text(&text, 3 * 500 + 1).expect("应当截断");
+        assert!(clipped.contains(" {}）",
+            clipped.len(),
+            MAX_ENTRY_BYTES
+        );
+    }
+
+    #[test]
+    fn small_files_are_not_touched() {
+        assert!(clip_text("short", 1024).is_none());
+        assert!(clip_text("short", 0).is_none());
+    }
+
+    #[test]
+    fn snapping_prefers_line_bounds() {
+        let text = "aaaa\nbbbb\ncccc";
+        assert_eq!(snap_back(text, 7), 5, "应回退到「bbbb」行首");
+        assert_eq!(snap_forward(text, 5), 10, "应前进到「cccc」行首");
+    }
+}
diff --git a/crates/core/src/launch/crash_bundle/tests.rs b/crates/core/src/launch/crash_bundle/tests.rs
new file mode 100644
index 0000000..e4f0062
--- /dev/null
+++ b/crates/core/src/launch/crash_bundle/tests.rs
@@ -0,0 +1,387 @@
+//! 诊断包的断言：清单齐全、脱敏生效、缺件写明白、超大文件截断。
+//!
+//! 为什么这些值得单开文件：守卫的三条（内容有清单 / 脱敏生效 / 没 crash-report 也能导出）
+//! 都要**真读回 zip** 才作数——只断言 `write_bundle` 返回 `Ok` 抓不住任何一种坏法。
+
+use std::io::Read;
+use std::path::{Path, PathBuf};
+
+use super::{
+    default_target_dir, write_bundle, BundleEntry, BundleSpec, HEAD_BYTES, MAX_ENTRY_BYTES,
+};
+
+fn temp_dir(tag: &str) -> PathBuf {
+    let root = std::env::temp_dir().join(format!("ull-m187-{}-{tag}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&root);
+    std::fs::create_dir_all(&root).expect("建夹具目录");
+    root
+}
+
+fn write(path: &Path, text: &str) {
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent).expect("建父目录");
+    }
+    std::fs::write(path, text).expect("写夹具");
+}
+
+/// 打开 zip 读某个条目的全文（不存在返回 `None`）。
+fn entry_text(path: &Path, name: &str) -> Option {
+    let file = std::fs::File::open(path).expect("打开 zip");
+    let mut archive = zip::ZipArchive::new(file).expect("读 zip");
+    let mut entry = archive.by_name(name).ok()?;
+    let mut text = String::new();
+    entry.read_to_string(&mut text).expect("读条目");
+    Some(text)
+}
+
+fn names(path: &Path) -> Vec {
+    let file = std::fs::File::open(path).expect("打开 zip");
+    let mut archive = zip::ZipArchive::new(file).expect("读 zip");
+    (0..archive.len())
+        .filter_map(|index| {
+            let item = archive.by_index(index).ok()?;
+            item.name().ok().map(|name| name.to_string())
+        })
+        .collect()
+}
+
+/// 接近真实日志的填充物。
+///
+/// 为什么不用 `"x".repeat(n)`：连续 4 MiB 的同字符会被脱敏器的「长不透明串」规则
+/// （长度 ≥64 的 base64/hex 形状）整段替换成占位符，长度就不再超限 —— 那样测的是脱敏，
+/// 不是截断。
+fn filler(bytes: usize) -> String {
+    let line = "2026-11-08T15:30:12.441Z [Render thread/INFO]: loading chunk with some words
+";
+    let mut text = String::with_capacity(bytes + line.len());
+    while text.len() < bytes {
+        text.push_str(line);
+    }
+    text
+}
+
+fn spec(root: &Path, secrets: Vec) -> BundleSpec {
+    BundleSpec {
+        instance: "1.20.4 · Fabric".into(),
+        version: "1.20.4-fabric".into(),
+        session: "0f8fad5b-d9cb-469f-a165-70867728950e".into(),
+        exit_code: Some(1),
+        exit_type: "application_error".into(),
+        uptime_ms: 12_345,
+        command: "javac -Xmx4096m -Djava.library.path=".into(),
+        java: "C:/Java/bin/javaw.exe (major 21)".into(),
+        system: "os=windows version=10.0 arch=x86_64".into(),
+        notes: vec!["本次没有生成 crash-report".into()],
+        missing: vec!["crash-reports/ 不存在".into()],
+        entries: vec![
+            BundleEntry::new("launcher", root.join("launcher.log")),
+            BundleEntry::new("session", root.join("game").join("s1.jsonl")),
+        ],
+        secrets,
+        home: Some(root.join("home")),
+    }
+}
+
+#[test]
+fn bundle_has_a_manifest_and_the_collected_files() {
+    let root = temp_dir("manifest");
+    write(&root.join("launcher.log"), "[launch] spawn argv=...\n");
+    write(&root.join("game").join("s1.jsonl"), "{\"kind\":\"exit\"}\n");
+
+    let target = default_target_dir(&root).join("m187.zip");
+    let bundle = write_bundle(&spec(&root, Vec::new()), &target).expect("导出");
+
+    assert!(bundle.bytes > 0, "落盘字节数不该是 0");
+    assert_eq!(bundle.files, 2, "两个现场文件都该进包");
+    assert_eq!(bundle.truncated, 0);
+
+    let listed = names(&target);
+    assert!(listed.contains(&"manifest.txt".to_string()), "{listed:?}");
+    assert!(
+        listed.contains(&"launcher/launcher.log".to_string()),
+        "{listed:?}"
+    );
+    assert!(
+        listed.contains(&"session/s1.jsonl".to_string()),
+        "{listed:?}"
+    );
+
+    let manifest = entry_text(&target, "manifest.txt").expect("清单");
+    // 清单要能把「发给别人看」需要的三件事说清：哪一场、什么退出、文件在哪。
+    assert!(manifest.contains("instance: 1.20.4 · Fabric"), "{manifest}");
+    assert!(manifest.contains("exit_code: 1"), "{manifest}");
+    assert!(
+        manifest.contains("exit_type: application_error"),
+        "{manifest}"
+    );
+    assert!(manifest.contains("launcher/launcher.log  <-"), "{manifest}");
+}
+
+/// 守卫②：**脱敏真的生效**（主目录 / token / 会话 id 三条各自替换）。
+#[test]
+fn secrets_home_and_session_ids_are_scrubbed_in_every_entry() {
+    let root = temp_dir("scrub");
+    let home = root.join("home");
+    let token = "eyJhbGciOiJIUzI1NiJ9.eyJ4IjoxMjN9.c2lnbmF0dXJlLXZhbHVl";
+    let session = "0f8fad5b-d9cb-469f-a165-70867728950e";
+    let dirty = format!(
+        "argv=--accessToken {token}\npath={}\nsession={session}\n",
+        home.join("AppData").display()
+    );
+    write(&root.join("launcher.log"), &dirty);
+    write(&root.join("game").join("s1.jsonl"), &dirty);
+
+    let target = default_target_dir(&root).join("m187.zip");
+    let mut spec = spec(&root, vec![session.to_string()]);
+    spec.command = format!("java -accessToken {token}");
+    let bundle = write_bundle(&spec, &target).expect("导出");
+    assert_eq!(bundle.files, 2);
+
+    for name in ["manifest.txt", "launcher/launcher.log", "session/s1.jsonl"] {
+        let text = entry_text(&target, name).unwrap_or_else(|| panic!("缺条目 {name}"));
+        assert!(!text.contains(token), "{name} 漏了 token：{text}");
+        assert!(!text.contains(session), "{name} 漏了会话 id：{text}");
+    }
+    let log = entry_text(&target, "launcher/launcher.log").expect("日志");
+    assert!(log.contains(""), "主目录没被替换：{log}");
+    assert!(
+        !log.contains(&home.display().to_string()),
+        "家目录原文还在：{log}"
+    );
+}
+
+/// 守卫③：**没有 crash-report 也能导出**，而且「没有」这件事写进清单（不许静默漏掉）。
+#[test]
+fn missing_crash_report_is_stated_in_the_manifest() {
+    let root = temp_dir("missing");
+    write(
+        &root.join("game").join("s1.jsonl"),
+        "{\"kind\":\"stderr\"}\n",
+    );
+
+    let target = default_target_dir(&root).join("m187.zip");
+    let bundle = write_bundle(&spec(&root, Vec::new()), &target).expect("导出");
+    assert_eq!(bundle.files, 1, "只有会话 JSONL 时也要出包");
+
+    let manifest = entry_text(&target, "manifest.txt").expect("清单");
+    assert!(manifest.contains("missing"), "{manifest}");
+    assert!(manifest.contains("crash-reports/ 不存在"), "{manifest}");
+    assert!(manifest.contains("本次没有生成 crash-report"), "{manifest}");
+    // 清单里也要能看见那个「不存在的文件名」，否则用户以为我们忘收了。
+    assert!(manifest.contains("session/s1.jsonl"), "{manifest}");
+}
+
+/// 有上限：单个超限文件只收头部，并在清单里记一行「已截断」。
+#[test]
+fn oversized_entries_are_truncated_and_recorded() {
+    let root = temp_dir("truncate");
+    let big = root.join("game").join("latest.log");
+    let body = filler(usize::try_from(MAX_ENTRY_BYTES).expect("常数") + 32);
+    write(&big, &body);
+
+    let target = default_target_dir(&root).join("m187.zip");
+    let mut spec = spec(&root, Vec::new());
+    spec.entries = vec![BundleEntry::new("game", &big)];
+    let bundle = write_bundle(&spec, &target).expect("导出");
+
+    assert_eq!(bundle.truncated, 1, "超限文件必须计入截断数");
+    let manifest = entry_text(&target, "manifest.txt").expect("清单");
+    assert!(manifest.contains("已截断"), "{manifest}");
+    assert!(
+        bundle.bytes < MAX_ENTRY_BYTES + 8 * 1024,
+        "包不该把整个超限文件塞进去（{} 字节）",
+        bundle.bytes
+    );
+}
+
+#[test]
+fn missing_source_files_are_skipped_not_fatal() {
+    let root = temp_dir("gone");
+    let mut spec = spec(&root, Vec::new());
+    spec.entries = vec![BundleEntry::new("game", root.join("nope/absent.log"))];
+
+    let target = default_target_dir(&root).join("m187.zip");
+    let bundle = write_bundle(&spec, &target).expect("缺文件也要出包");
+    assert_eq!(bundle.files, 0);
+    let manifest = entry_text(&target, "manifest.txt").expect("清单");
+    assert!(manifest.contains("读不出来"), "{manifest}");
+}
+
+/// P2-2：**包内条目名与清单里的名字必须一字不差**，且名字也要过脱敏。
+///
+/// 抓得住：r1 复审抓到的原 bug —— 条目名用原始文件名（会话 id 原样泄漏），而 manifest 过了
+/// redactor（写 ``）⇒ 清单指向的条目在包里不存在。
+#[test]
+fn entry_names_are_scrubbed_and_match_the_manifest_exactly() {
+    let root = temp_dir("names");
+    let session = "0f8fad5b-d9cb-469f-a165-70867728950e";
+    write(
+        &root.join("game").join(format!("{session}.jsonl")),
+        "{}
+",
+    );
+    write(
+        &root.join("launcher.log"),
+        "boot
+",
+    );
+
+    // 第三条**不钉名**：它的源文件名里带会话 id，靠 `entry_names` 的脱敏兜住。
+    write(
+        &root.join("game").join(format!("hs-{session}.log")),
+        "x
+",
+    );
+    let mut spec = spec(&root, vec![session.to_string()]);
+    spec.entries = vec![
+        BundleEntry::new("launcher", root.join("launcher.log")),
+        // 源文件名就是会话 id：钉成 session.jsonl（调用方 app-iced 的做法）
+        BundleEntry::named(
+            "session",
+            root.join("game").join(format!("{session}.jsonl")),
+            "session.jsonl",
+        ),
+        BundleEntry::new("game", root.join("game").join(format!("hs-{session}.log"))),
+    ];
+    let target = default_target_dir(&root).join("names.zip");
+    write_bundle(&spec, &target).expect("导出");
+
+    let listed = names(&target);
+    assert!(
+        listed.iter().any(|name| name == "session/session.jsonl"),
+        "钉死的条目名没生效：{listed:?}"
+    );
+    assert!(
+        !listed.iter().any(|name| name.contains(session)),
+        "条目名里还有原始会话 id：{listed:?}"
+    );
+
+    // 清单的 files 段必须与真实条目一一对应（顺序也一致）。
+    let manifest = entry_text(&target, "manifest.txt").expect("清单");
+    let manifest_names: Vec = manifest
+        .lines()
+        .filter(|line| line.starts_with("- ") && line.contains("  <- "))
+        .map(|line| {
+            line.trim_start_matches("- ")
+                .split("  <- ")
+                .next()
+                .unwrap_or_default()
+                .to_string()
+        })
+        .collect();
+    let zip_names: Vec = listed
+        .iter()
+        .filter(|name| name.as_str() != "manifest.txt")
+        .cloned()
+        .collect();
+    assert_eq!(manifest_names, zip_names, "清单与包内条目对不上");
+}
+
+/// P2-3：截断必须**保留尾部**——崩溃证据（`exit` 事件 / 栈尾）在尾部。
+///
+/// 抓得住：只留头部的截断（r1 复审 P2-3 的原实现）会让包里没有 `exit` 行。
+#[test]
+fn truncation_keeps_the_tail_where_the_crash_evidence_lives() {
+    let root = temp_dir("tail");
+    let session = root.join("game").join("session.jsonl");
+    let head_marker = "HEAD-MARKER-first-line";
+    let tail_marker = "{\"kind\":\"exit\",\"payload\":{\"code\":1}}";
+    let body = format!(
+        "{head_marker}
+{}{tail_marker}
+",
+        filler(usize::try_from(MAX_ENTRY_BYTES).expect("常数") + 64)
+    );
+    write(&session, &body);
+
+    let mut spec = spec(&root, Vec::new());
+    spec.entries = vec![BundleEntry::named("session", &session, "session.jsonl")];
+    let target = default_target_dir(&root).join("tail.zip");
+    let bundle = write_bundle(&spec, &target).expect("导出");
+
+    assert_eq!(bundle.truncated, 1, "超限文件必须计入截断数");
+    let kept = entry_text(&target, "session/session.jsonl").expect("条目");
+    assert!(kept.contains(head_marker), "头部标记丢了");
+    assert!(
+        kept.contains(tail_marker),
+        "尾部标记丢了 —— 包里将没有 exit 事件（证据是残的）"
+    );
+    assert!(
+        kept.contains(""), "没有  占位符");
+    // ③ 尾部证据仍在（截断仍保尾）
+    assert!(kept.contains("\"kind\":\"exit\""), "尾部 exit 事件丢了");
+}
diff --git a/crates/core/src/launch/crash_report.rs b/crates/core/src/launch/crash_report.rs
new file mode 100644
index 0000000..2b978ac
--- /dev/null
+++ b/crates/core/src/launch/crash_report.rs
@@ -0,0 +1,394 @@
+//! 一次失败启动的**现场**（M187）：路径 + 捕获输出 + 退出事实，供失败弹窗与诊断包共用。
+//!
+//! ## 为什么是「事实」而不是「结论」
+//!
+//! 弹窗要说三件事——**是哪一场失败**（装配阶段 / 起进程后崩溃）、**退出码**、**证据在哪**。
+//! 这三件都是启动器已经知道的事实，不含任何推断。崩溃原因的智能诊断是另一条线（诊断引擎
+//! `diagnose` / AI），本模块只把事实摆齐，让用户能一键把证据带走。
+//!
+//! ## 两种失败形态必须分开（用户投诉的原点）
+//!
+//! | 形态 | 判据 | 弹窗该说什么 |
+//! |---|---|---|
+//! | 游戏自己写了崩溃报告 | [`CrashReport::has_game_crash_report`] 为真 | 「游戏写出了崩溃报告」，贴 Description/栈片段 |
+//! | 游戏**没来得及写** | 没有 crash-report，但有捕获输出 | 「这次没有生成崩溃报告，下面是捕获的最后若干行」 |
+//! | 什么输出都没抓到 | 两者皆无 | 「游戏还没来得及写日志」+ 最可能原因分类（缺 Java / 内存 / 参数 / 库） |
+//!
+//! 第二、三种**不许**显示成「找不到日志」——日志在启动器这里，只是游戏没写它自己那份。
+//! 进程级槽位只存**已脱敏**的文本（[`CrashReport::collect`] 的出口就是脱敏边界）。
+
+use std::path::PathBuf;
+use std::sync::{Mutex, OnceLock};
+
+use super::crash_scan::{self, CrashArtifact, CrashSource};
+use super::launch_session::SessionHandle;
+use super::redact::Redactor;
+
+/// 弹窗里贴「捕获输出」的行数上限（够看清 JVM 报错，又不把弹窗撑破）。
+pub const TAIL_LINES: usize = 30;
+/// 现场文件的扫描条数上限。
+pub const MAX_ARTIFACTS: usize = 8;
+/// 弹窗里贴崩溃报告摘要的字符上限。
+pub const MAX_EXCERPT_CHARS: usize = 1200;
+
+/// 一个现场文件（来源 + 路径 + 人读摘要）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ArtifactFact {
+    /// 来源 slug（`crash_report` / `hs_err` / `latest_log`）。
+    pub source: String,
+    /// 文件路径。
+    pub path: PathBuf,
+    /// 摘要（崩溃报告的 Description + 栈片段；`latest.log` 与 `hs_err` 不给）。
+    pub excerpt: Option,
+}
+
+/// 一次失败启动的现场。
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub struct CrashReport {
+    /// 实例 id。
+    pub instance: String,
+    /// 实例名。
+    pub name: String,
+    /// 绑定的版本 id。
+    pub version: String,
+    /// 会话 id（空 = 进程根本没起来）。
+    pub session: String,
+    /// 会话事件流 JSONL（**游戏侧证据的真正落点**）。
+    pub session_log: Option,
+    /// 该实例绑定的版本 JSON（诊断包要带上它，别人才能复现装配）。
+    pub version_json: Option,
+    /// 启动器自己的日志目录（`.ULL/logs`）。
+    pub launcher_logs: Option,
+    /// 实例运行目录（`crash-reports/` 与 `logs/` 的父目录）。
+    pub run_dir: Option,
+    /// 崩溃现场文件（按修改时间倒序）。
+    pub artifacts: Vec,
+    /// 退出码（`None` = 进程没起来 / 平台没给）。
+    pub exit_code: Option,
+    /// 退出判定 slug（`application_error` / `jvm_error` / `normal` …；进程没起来时是 `spawn`）。
+    pub exit_type: String,
+    /// 存活毫秒数。
+    pub uptime_ms: u64,
+    /// 脱敏后的命令行一行。
+    pub command: String,
+    /// Java 一行说明（二进制 + 主版本）。
+    pub java: String,
+    /// 系统一行说明。
+    pub system: String,
+    /// 装配阶段失败的 slug（`version_manifest` / `spawn` …）；`None` = 进程起来过。
+    pub stage: Option,
+    /// 装配阶段的原始错误文本（不翻译，可能含路径）。
+    pub stage_detail: Option,
+    /// 启动器捕获的最后若干行（已脱敏、已截断到 [`TAIL_LINES`]）。
+    pub stderr_tail: Vec,
+}
+
+/// 证据形态（界面按它选 i18n key，**不许**再自己判断）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Evidence {
+    /// 游戏自己写了 `crash-reports/crash-*.txt`。
+    GameCrashReport,
+    /// 游戏没写崩溃报告，但启动器抓到了输出。
+    CapturedOutput,
+    /// 连输出都没抓到（JVM 都没起来 / 立刻失败）。
+    Nothing,
+}
+
+impl Evidence {
+    /// 稳定 slug（测试与日志用；不是文案）。
+    #[must_use]
+    pub const fn slug(self) -> &'static str {
+        match self {
+            Self::GameCrashReport => "game_crash_report",
+            Self::CapturedOutput => "captured_output",
+            Self::Nothing => "nothing",
+        }
+    }
+}
+
+impl CrashReport {
+    /// 游戏侧证据的形态（界面按它选文案，**不许**再自己判断）。
+    #[must_use]
+    pub fn evidence(&self) -> Evidence {
+        if self.has_game_crash_report() {
+            Evidence::GameCrashReport
+        } else if self.stderr_tail.is_empty() {
+            Evidence::Nothing
+        } else {
+            Evidence::CapturedOutput
+        }
+    }
+
+    /// 是否找到游戏自己写的崩溃报告。
+    #[must_use]
+    pub fn has_game_crash_report(&self) -> bool {
+        self.artifacts
+            .iter()
+            .any(|a| a.source == CrashSource::CrashReport.as_str())
+    }
+
+    /// 进程是否起来过（决定标题写「启动失败」还是「游戏崩溃」）。
+    #[must_use]
+    pub fn started(&self) -> bool {
+        self.stage.is_none()
+    }
+
+    /// 该实例运行目录下的 `crash-reports/`。
+    #[must_use]
+    pub fn crash_reports_dir(&self) -> Option {
+        self.run_dir.as_ref().map(|dir| dir.join("crash-reports"))
+    }
+
+    /// 该实例的 `logs/latest.log`。
+    #[must_use]
+    pub fn latest_log_path(&self) -> Option {
+        self.run_dir
+            .as_ref()
+            .map(|dir| dir.join("logs").join("latest.log"))
+    }
+
+    /// 供「复制路径」用的（标签, 路径）列表（提示词在前、目录在后）。
+    #[must_use]
+    pub fn path_lines(&self) -> Vec<(String, PathBuf)> {
+        let mut lines = Vec::new();
+        if let Some(log) = &self.session_log {
+            lines.push(("session".to_string(), log.clone()));
+        }
+        if let Some(dir) = &self.launcher_logs {
+            lines.push(("launcher_logs".to_string(), dir.clone()));
+        }
+        if let Some(path) = self.latest_log_path() {
+            lines.push(("latest_log".to_string(), path));
+        }
+        if let Some(dir) = self.crash_reports_dir() {
+            lines.push(("crash_reports".to_string(), dir));
+        }
+        if let Some(dir) = &self.run_dir {
+            lines.push(("run_dir".to_string(), dir.clone()));
+        }
+        lines
+    }
+
+    /// 收集一次**已经起来过**的启动的现场。
+    ///
+    /// `session` 由调用方在 `finish()` 之后给出；`lines` 是该会话的事件流行（**调用方读**，
+    /// 因为读 JSONL 属于 host 的活）。只有最后 [`TAIL_LINES`] 行进弹窗。
+    #[must_use]
+    pub fn collect(session: &SessionHandle, ctx: &ReportContext, lines: &[String]) -> Self {
+        let run_dir = ctx.run_dir.clone();
+        let artifacts = crash_scan::scan(&run_dir, ctx.started_at, MAX_ARTIFACTS)
+            .into_iter()
+            .map(|artifact| fact(&artifact, &ctx.redactor()))
+            .collect();
+
+        let raw: Vec = lines.iter().rev().take(TAIL_LINES).rev().cloned().collect();
+
+        Self {
+            instance: ctx.instance.clone(),
+            name: ctx.name.clone(),
+            version: ctx.version.clone(),
+            session: session.session_id.clone(),
+            session_log: Some(session.log_path.clone()),
+            version_json: ctx.version_json.clone(),
+            launcher_logs: Some(ctx.launcher_logs.clone()),
+            run_dir: Some(run_dir),
+            artifacts,
+            exit_code: Some(session.exit.code),
+            exit_type: session.exit.exit_type.as_str().to_string(),
+            uptime_ms: session.uptime_ms,
+            command: ctx
+                .redactor()
+                .scrub(session.redacted_display().as_str())
+                .into_owned(),
+            java: ctx.java.clone(),
+            system: ctx.system.clone(),
+            stage: None,
+            stage_detail: None,
+            stderr_tail: scrub_tail(&raw, &ctx.redactor()),
+        }
+    }
+
+    /// 收集一次**进程没起来**的现场（装配 / 起进程阶段失败）。
+    ///
+    /// 这种失败最常见的形态就是「找不到 crash-report」——游戏根本没被执行到，所以
+    /// [`Evidence`] 落到 [`Evidence::Nothing`]，界面必须说「游戏还没来得及写日志」。
+    #[must_use]
+    pub fn before_start(ctx: &ReportContext, stage: &str, detail: &str, exit_type: &str) -> Self {
+        let redactor = ctx.redactor();
+        Self {
+            instance: ctx.instance.clone(),
+            name: ctx.name.clone(),
+            version: ctx.version.clone(),
+            session: String::new(),
+            session_log: None,
+            version_json: ctx.version_json.clone(),
+            launcher_logs: Some(ctx.launcher_logs.clone()),
+            run_dir: Some(ctx.run_dir.clone()),
+            artifacts: Vec::new(),
+            exit_code: None,
+            exit_type: exit_type.to_string(),
+            uptime_ms: 0,
+            command: String::new(),
+            java: ctx.java.clone(),
+            system: ctx.system.clone(),
+            stage: Some(stage.to_string()),
+            stage_detail: Some(redactor.scrub(detail).into_owned()),
+            stderr_tail: Vec::new(),
+        }
+    }
+
+    /// 诊断包清单里要写明的「没有的东西」（**不许静默省略**）。
+    #[must_use]
+    pub fn missing_lines(&self) -> Vec {
+        let mut missing = Vec::new();
+        if !self.has_game_crash_report() {
+            missing.push("crash-reports/crash-*.txt: 本次没有（游戏没来得及写）".to_string());
+        }
+        if let Some(path) = self.latest_log_path() {
+            if !path.is_file() {
+                missing.push(format!("logs/latest.log: 不存在（{}）", path.display()));
+            }
+        }
+        if self.session_log.is_none() {
+            missing.push("会话 JSONL: 不存在（进程没起来）".to_string());
+        }
+        missing
+    }
+
+    /// 备注（清单里「这次发生了什么」那一段）。
+    #[must_use]
+    pub fn note_lines(&self) -> Vec {
+        let mut notes = match self.evidence() {
+            Evidence::GameCrashReport => vec!["游戏写出了崩溃报告（crash-reports/）".to_string()],
+            Evidence::CapturedOutput => {
+                vec!["本次没有生成崩溃报告；证据是启动器捕获的输出".to_string()]
+            }
+            Evidence::Nothing => vec![
+                "本次没有崩溃报告，也没捕获到输出（最可能：缺 Java / 内存不足 / 参数错误 / 库缺失）"
+                    .to_string(),
+            ],
+        };
+        if let Some(stage) = &self.stage {
+            notes.push(format!("进程没有起来，失败在：{stage}"));
+        }
+        notes
+    }
+}
+
+/// [`CrashReport::collect`] / [`CrashReport::before_start`] 的输入（全是启动侧已有的东西）。
+///
+/// 字段是**拥有的**：构造一次、在四个失败出口上反复用（借用版会让每个出口都要重算一遍
+/// 主目录与脱敏器，而这条路径低频、克隆代价可以忽略）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ReportContext {
+    /// 实例 id。
+    pub instance: String,
+    /// 实例名。
+    pub name: String,
+    /// 版本 id。
+    pub version: String,
+    /// 实例运行目录。
+    pub run_dir: PathBuf,
+    /// 启动器日志目录（`.ULL/logs`）。
+    pub launcher_logs: PathBuf,
+    /// 本次会话的开始时刻（现场文件的时间闸）。
+    pub started_at: std::time::SystemTime,
+    /// 该实例绑定的版本 JSON。
+    pub version_json: Option,
+    /// Java 一行说明。
+    pub java: String,
+    /// 系统一行说明。
+    pub system: String,
+    /// 要额外抹掉的串（会话 id、access token 等）。
+    pub secrets: Vec,
+}
+
+impl ReportContext {
+    /// 建一份（`java` 可以后补：装配阶段还没选 Java）。
+    #[must_use]
+    pub fn new(
+        instance: impl Into,
+        name: impl Into,
+        version: impl Into,
+        run_dir: impl Into,
+        launcher_logs: impl Into,
+        started_at: std::time::SystemTime,
+        system: impl Into,
+    ) -> Self {
+        Self {
+            instance: instance.into(),
+            name: name.into(),
+            version: version.into(),
+            run_dir: run_dir.into(),
+            launcher_logs: launcher_logs.into(),
+            started_at,
+            version_json: None,
+            java: String::new(),
+            system: system.into(),
+            secrets: Vec::new(),
+        }
+    }
+
+    fn redactor(&self) -> Redactor {
+        let mut redactor = Redactor::new();
+        for key in ["USERPROFILE", "HOME"] {
+            if let Ok(home) = std::env::var(key) {
+                if !home.trim().is_empty() {
+                    redactor = redactor.with_home_str(home);
+                }
+            }
+        }
+        for secret in &self.secrets {
+            redactor = redactor.with_secret(secret.clone());
+        }
+        redactor
+    }
+}
+
+fn scrub_tail(lines: &[String], redactor: &Redactor) -> Vec {
+    lines
+        .iter()
+        .map(|line| redactor.scrub(line).into_owned())
+        .collect()
+}
+
+fn fact(artifact: &CrashArtifact, redactor: &Redactor) -> ArtifactFact {
+    let excerpt = artifact.excerpt.as_ref().map(|text| {
+        let scrubbed = redactor.scrub(text);
+        let trimmed: String = scrubbed.chars().take(MAX_EXCERPT_CHARS).collect();
+        trimmed
+    });
+    ArtifactFact {
+        source: artifact.source.as_str().to_string(),
+        path: artifact.path.clone(),
+        excerpt,
+    }
+}
+
+fn slot() -> &'static Mutex> {
+    static SLOT: OnceLock>> = OnceLock::new();
+    SLOT.get_or_init(|| Mutex::new(None))
+}
+
+/// 登记一次失败启动的现场（启动线程收尾时调用）。
+pub fn publish(report: CrashReport) {
+    if let Ok(mut guard) = slot().lock() {
+        *guard = Some(report);
+    }
+}
+
+/// 读最近一次失败启动的现场。
+#[must_use]
+pub fn failing_launch() -> Option {
+    slot().lock().ok().and_then(|guard| guard.clone())
+}
+
+/// 清空槽位（测试用）。
+pub fn clear() {
+    if let Ok(mut guard) = slot().lock() {
+        *guard = None;
+    }
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/core/src/launch/crash_report/tests.rs b/crates/core/src/launch/crash_report/tests.rs
new file mode 100644
index 0000000..1f61fa6
--- /dev/null
+++ b/crates/core/src/launch/crash_report/tests.rs
@@ -0,0 +1,125 @@
+//! 现场事实的断言：三态证据分类、脱敏、缺件写明、槽位读写。
+
+use std::path::PathBuf;
+
+use super::{clear, failing_launch, publish, ArtifactFact, CrashReport, Evidence, ReportContext};
+
+fn report(artifacts: Vec, tail: Vec) -> CrashReport {
+    CrashReport {
+        instance: "survival".into(),
+        name: "生存".into(),
+        version: "1.20.4".into(),
+        session: "0f8fad5b".into(),
+        session_log: Some(PathBuf::from("/sessions/game/0f8fad5b.jsonl")),
+        version_json: None,
+        launcher_logs: Some(PathBuf::from("/.ULL/logs")),
+        run_dir: Some(PathBuf::from("/instances/survival")),
+        artifacts,
+        exit_code: Some(1),
+        exit_type: "application_error".into(),
+        uptime_ms: 12_000,
+        command: "javaw -Xmx4096m".into(),
+        java: "javaw.exe (21)".into(),
+        system: "os=windows".into(),
+        stage: None,
+        stage_detail: None,
+        stderr_tail: tail,
+    }
+}
+
+#[test]
+fn evidence_tells_the_three_shapes_apart() {
+    let with_report = report(
+        vec![ArtifactFact {
+            source: "crash_report".into(),
+            path: PathBuf::from("/instances/survival/crash-reports/crash-1.txt"),
+            excerpt: Some("Description: Ticking entity".into()),
+        }],
+        vec!["Exception in thread main".into()],
+    );
+    assert_eq!(with_report.evidence(), Evidence::GameCrashReport);
+    assert_eq!(with_report.evidence().slug(), "game_crash_report");
+
+    let stderr_only = report(Vec::new(), vec!["Error: could not find java.dll".into()]);
+    assert_eq!(
+        stderr_only.evidence(),
+        Evidence::CapturedOutput,
+        "没有 crash-report 但有捕获输出 ⇒ 不许说「找不到日志」"
+    );
+
+    let nothing = report(Vec::new(), Vec::new());
+    assert_eq!(nothing.evidence(), Evidence::Nothing);
+
+    // 三种 slug 必须互不相同（界面按它选 key，撞了就会显示错的一句）。
+    let slugs = [
+        with_report.evidence().slug(),
+        stderr_only.evidence().slug(),
+        nothing.evidence().slug(),
+    ];
+    let mut unique = slugs.to_vec();
+    unique.sort_unstable();
+    unique.dedup();
+    assert_eq!(unique.len(), 3, "{slugs:?}");
+}
+
+#[test]
+fn missing_crash_report_is_listed_not_silently_dropped() {
+    let report = report(Vec::new(), vec!["line".into()]);
+    let missing = report.missing_lines().join("\n");
+    assert!(missing.contains("crash-reports"), "{missing}");
+    assert!(missing.contains("游戏没来得及写"), "{missing}");
+    assert!(
+        !missing.contains("会话 JSONL"),
+        "会话在，不该说没会话：{missing}"
+    );
+}
+
+#[test]
+fn notes_name_the_fallback_reason_classification() {
+    let report = report(Vec::new(), Vec::new());
+    let notes = report.note_lines().join("\n");
+    assert!(notes.contains("缺 Java"), "{notes}");
+    assert!(notes.contains("内存不足"), "{notes}");
+}
+
+#[test]
+fn before_start_marks_the_launch_as_never_started_and_scrubs_the_detail() {
+    let home = std::env::var("USERPROFILE")
+        .or_else(|_| std::env::var("HOME"))
+        .unwrap_or_default();
+    if home.is_empty() {
+        return;
+    }
+    let ctx = ReportContext::new(
+        "survival",
+        "生存",
+        "1.20.4",
+        std::path::Path::new("/instances/survival"),
+        std::path::Path::new("/.ULL/logs"),
+        std::time::SystemTime::now(),
+        "os=windows",
+    );
+    let report = CrashReport::before_start(
+        &ctx,
+        "spawn",
+        &format!("{home}/java/bin/javaw.exe 不存在"),
+        "spawn",
+    );
+    assert!(!report.started(), "进程没起来");
+    assert_eq!(report.evidence(), Evidence::Nothing);
+    let detail = report.stage_detail.expect("阶段原文");
+    assert!(detail.contains(""), "{detail}");
+    assert!(!detail.contains(&home), "主目录原文漏了：{detail}");
+}
+
+#[test]
+fn slot_keeps_the_last_failure_only() {
+    clear();
+    assert!(failing_launch().is_none());
+    publish(report(Vec::new(), vec!["first".into()]));
+    publish(report(Vec::new(), vec!["second".into()]));
+    let last = failing_launch().expect("最近一次");
+    assert_eq!(last.stderr_tail, vec!["second".to_string()]);
+    clear();
+    assert!(failing_launch().is_none());
+}
diff --git a/crates/core/src/launch/crash_scan.rs b/crates/core/src/launch/crash_scan.rs
new file mode 100644
index 0000000..aff3fd6
--- /dev/null
+++ b/crates/core/src/launch/crash_scan.rs
@@ -0,0 +1,295 @@
+//! 崩溃现场扫描：`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};
+
+use crate::launch::exit_analysis::ExitAnalysis;
+
+/// 崩溃现场文件来源。
+#[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",
+        }
+    }
+
+    /// 这个来源本身能否**作为崩溃的证据**（M211/D3）。
+    ///
+    /// `crash-reports/*.txt` 与 `hs_err_pid*.log` 只有崩溃时才会出现；`logs/latest.log` 是
+    /// **每局都写**的普通日志，它的存在什么也证明不了——把「文件在」当崩溃判据，等于给每一局
+    /// 都盖上「游戏崩溃」的章（M208 实机：连 `code 0 / error_lines 0` 的干净退出也被标成崩溃）。
+    pub fn is_authoritative(self) -> bool {
+        !matches!(self, Self::LatestLog)
+    }
+}
+
+/// 一个现场文件。
+#[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,
+}
+
+/// 默认摘录上限（字符）。
+pub const MAX_EXCERPT_CHARS: usize = 2000;
+
+/// 扫描一次运行目录，返回按修改时间倒序的现场文件（最多 `limit` 个）。
+///
+/// `since` 之前的文件视为上一局遗留，忽略；给 `since` 留 1 秒容差以吸收文件系统时间精度。
+///
+/// **`logs/latest.log` 只在已经找到权威现场文件时才被带上**（M211/D3）：它是「崩溃报告/
+/// hs_err 都缺、只能看全文」时的补充证据，每局都会写，不能当崩溃判据。
+pub fn scan(run_dir: &Path, since: SystemTime, limit: usize) -> Vec {
+    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 found.is_empty() {
+        return Vec::new();
+    }
+    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()
+}
+
+/// 这一局是否**有真实崩溃证据**（M211/D3：索引里的 `crash_found` 只认这个结论）。
+///
+/// 判据只有两类，都要么是崩溃专属产物、要么是「异常退出 + 日志里真有错误行」：
+/// 1. 现场文件里有权威来源（`crash-reports/*.txt` / `hs_err_pid*.log`）；
+/// 2. 非 0 退出码且错误级日志行数 > 0。
+///
+/// 干净退出（`code 0`、`error_lines 0`）落不进任何一条 ⇒ `false`。`logs/latest.log` 存在与否
+/// 不参与判定（每次启动都会写它）。
+pub fn has_crash_evidence(artifacts: &[CrashArtifact], exit: &ExitAnalysis) -> bool {
+    if artifacts.iter().any(|item| item.source.is_authoritative()) {
+        return true;
+    }
+    exit.code != 0 && exit.error_lines > 0
+}
+
+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 {
+    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 {
+    std::fs::metadata(path).ok()?.modified().ok()
+}
+
+/// 读文件开头 `max_chars` 个字符（读不到就 `None`，不因权限/编码问题中断收尾）。
+pub fn read_excerpt(path: &Path, max_chars: usize) -> Option {
+    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)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{has_crash_evidence, scan, CrashSource};
+    use crate::launch::exit_analysis::{self, ExitAnalysis, ExitSignals};
+    use crate::launch::pump::LogLine;
+    use crate::launch::pump::Stream;
+    use std::path::{Path, PathBuf};
+    use std::time::SystemTime;
+
+    fn temp_dir(tag: &str) -> PathBuf {
+        let root = std::env::temp_dir().join(format!("ull-m211-scan-{}-{tag}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&root);
+        std::fs::create_dir_all(&root).expect("建夹具目录");
+        root
+    }
+
+    /// 每局都会写的普通日志：干净退出时它**也在**，所以「它在」什么也证明不了。
+    fn write_latest_log(run_dir: &Path) {
+        let logs = run_dir.join("logs");
+        std::fs::create_dir_all(&logs).expect("建 logs");
+        std::fs::write(logs.join("latest.log"), "[10:15:00] [main/INFO]: hello\n")
+            .expect("写 latest.log");
+    }
+
+    fn analyze(code: i32, errors: usize) -> ExitAnalysis {
+        let lines: Vec = (0..errors)
+            .map(|index| {
+                LogLine::new(
+                    Stream::Stderr,
+                    format!("java.lang.RuntimeException: boom {index}"),
+                )
+            })
+            .collect();
+        exit_analysis::analyze(&ExitSignals::new(code, 60_000, &lines))
+    }
+
+    /// D3 主用例（**改实现之前是红的**）：干净退出 + 只写了 `logs/latest.log` ⇒ 没有现场文件。
+    ///
+    /// 变异证明：把 `scan` 里 `if found.is_empty() { return Vec::new() }` 删掉（即恢复「
+    /// latest.log 无条件当现场文件」）⇒ 本条拿到 1 个 `latest_log`，红。
+    #[test]
+    fn a_clean_run_produces_no_crash_artifact() {
+        let run_dir = temp_dir("clean");
+        write_latest_log(&run_dir);
+
+        let artifacts = scan(&run_dir, SystemTime::now(), 8);
+        assert!(
+            artifacts.is_empty(),
+            "只有 latest.log 时不该报现场文件：{artifacts:?}"
+        );
+        std::fs::remove_dir_all(&run_dir).ok();
+    }
+
+    /// 真有崩溃现场时，`latest.log` 才作为补充证据跟着走（它的诊断价值要保住）。
+    ///
+    /// 变异证明：把 `scan` 里的 `latest_log(...)` 整段删掉 ⇒ 本条只剩 hs_err 一个，红。
+    #[test]
+    fn latest_log_rides_along_only_when_a_crash_scene_exists() {
+        let run_dir = temp_dir("ride");
+        write_latest_log(&run_dir);
+        std::fs::write(run_dir.join("hs_err_pid4242.log"), "SIGSEGV\n").expect("写 hs_err");
+
+        let artifacts = scan(&run_dir, SystemTime::now(), 8);
+        let sources: Vec = artifacts.iter().map(|item| item.source).collect();
+        assert!(
+            sources.contains(&CrashSource::HsErr),
+            "hs_err 必须被认出来：{sources:?}"
+        );
+        assert!(
+            sources.contains(&CrashSource::LatestLog),
+            "有权威现场时 latest.log 仍要作为补充带上：{sources:?}"
+        );
+        std::fs::remove_dir_all(&run_dir).ok();
+    }
+
+    /// 崩溃结论的三条判据：权威现场 / 非 0 退出 + 错误行 / 其余一律不算。
+    ///
+    /// 变异证明：把 `has_crash_evidence` 最后一行改成 `true`（或改成只看
+    /// `!artifacts.is_empty()`）⇒ 干净退出那条断言红。
+    #[test]
+    fn crash_evidence_needs_something_that_only_happens_on_a_crash() {
+        let hs_err = super::CrashArtifact {
+            source: CrashSource::HsErr,
+            path: PathBuf::from("hs_err_pid1.log"),
+            excerpt: None,
+        };
+        let latest = super::CrashArtifact {
+            source: CrashSource::LatestLog,
+            path: PathBuf::from("logs/latest.log"),
+            excerpt: None,
+        };
+        let clean = analyze(0, 0);
+        let crashed = analyze(1, 2);
+
+        assert!(
+            !has_crash_evidence(std::slice::from_ref(&latest), &clean),
+            "只有 latest.log + 干净退出 ⇒ 不是崩溃"
+        );
+        assert!(!has_crash_evidence(&[], &clean), "干净退出 ⇒ 不是崩溃");
+        assert!(
+            !has_crash_evidence(&[], &analyze(1, 0)),
+            "非 0 退出但没有错误行 ⇒ 证据不足，不算崩溃"
+        );
+        assert!(has_crash_evidence(&[hs_err], &clean), "hs_err 就是崩溃证据");
+        assert!(
+            has_crash_evidence(&[], &crashed),
+            "非 0 退出 + 错误行 ⇒ 崩溃"
+        );
+    }
+}
diff --git a/crates/core/src/launch/defaults.rs b/crates/core/src/launch/defaults.rs
new file mode 100644
index 0000000..b60f4cd
--- /dev/null
+++ b/crates/core/src/launch/defaults.rs
@@ -0,0 +1,250 @@
+//! 默认参数表：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 {
+    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 {
+    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 {
+    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,
+    user_specified_gc: bool,
+) -> Vec {
+    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 {
+    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 {
+    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 {
+    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 {
+    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");
+    }
+    // Termux + glibc 构建：termux-x11 下 glibc Mesa 的 zink 卡 DRI3，softpipe 是当前
+    // 可用路径。放在软件渲染块之后、用户自定义之前（用户显式设置仍可覆盖）。
+    if cfg!(target_os = "linux")
+        && crate::platform::termux::is_termux(&crate::platform::paths::ProcessEnv)
+    {
+        apply_termux_gl_defaults(&mut env);
+    }
+    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()));
+    }
+}
+
+/// Termux（glibc 构建）上的默认 GL 环境：softpipe。
+///
+/// glibc Mesa 26 的 zink 在 termux-x11 下报 `DRI3 not available`，softpipe 是当前
+/// 可用的软件路径；硬件路径等 DRI3 问题解决后再切。
+fn apply_termux_gl_defaults(env: &mut Vec<(String, String)>) {
+    set_env(env, "MESA_LOADER_DRIVER_OVERRIDE", "swrast");
+    set_env(env, "LIBGL_ALWAYS_SOFTWARE", "1");
+}
+
+#[cfg(test)]
+mod tests {
+    use super::apply_termux_gl_defaults;
+
+    #[test]
+    fn termux_gl_defaults_force_softpipe() {
+        let mut env = Vec::new();
+        apply_termux_gl_defaults(&mut env);
+        assert!(env.contains(&(
+            "MESA_LOADER_DRIVER_OVERRIDE".to_string(),
+            "swrast".to_string()
+        )));
+        assert!(env.contains(&("LIBGL_ALWAYS_SOFTWARE".to_string(), "1".to_string())));
+    }
+
+    #[test]
+    fn termux_gl_defaults_overwrite_earlier_llvmpipe_choice() {
+        let mut env = vec![(
+            "MESA_LOADER_DRIVER_OVERRIDE".to_string(),
+            "llvmpipe".to_string(),
+        )];
+        apply_termux_gl_defaults(&mut env);
+        assert_eq!(
+            env.iter()
+                .find(|(key, _)| key == "MESA_LOADER_DRIVER_OVERRIDE")
+                .map(|(_, value)| value.as_str()),
+            Some("swrast")
+        );
+    }
+}
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;
+}
+
+/// 空挂钩：不诊断（占位 / 用户关闭 AI）。
+#[derive(Debug, Default, Clone, Copy)]
+pub struct NoopDiagnosis;
+
+impl DiagnosisHook for NoopDiagnosis {
+    fn analyze(&self, _request: &DiagnosisRequest) -> Option {
+        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,
+    /// 崩溃现场文件（crash-report / hs_err / latest.log）。
+    pub artifacts: Vec,
+    /// 脱敏后的完整 argv。
+    pub argv: Vec,
+    /// 最大堆（MiB）。
+    pub memory_mb: Option,
+    /// Java 主版本。
+    pub java_major: u32,
+    /// Java 可执行文件。
+    pub java_binary: PathBuf,
+    /// 运行目录。
+    pub game_dir: PathBuf,
+}
+
+impl DiagnosisRequest {
+    /// 错误级日志行（M15 规则匹配的主输入）。
+    pub fn error_lines(&self) -> Vec {
+        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..25b37c3
--- /dev/null
+++ b/crates/core/src/launch/error.rs
@@ -0,0 +1,201 @@
+//! 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 = std::result::Result;
+
+/// 缺失的组件（库 / 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,
+}
+
+impl MissingComponent {
+    /// 只按名字构造（路径未知）。
+    pub fn named(name: impl Into) -> Self {
+        Self {
+            name: name.into(),
+            path: None,
+        }
+    }
+
+    /// 带期望路径构造。
+    pub fn at_path(name: impl Into, path: impl Into) -> 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),
+    /// 清单参数畸形（例如空参数项）。
+    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,
+    },
+    /// 看门狗到点**停止等待**（D6）：进程仍在运行，我们只是不再等它了。
+    Watchdog {
+        /// 目标进程号（没有被结束）。
+        pid: u32,
+        /// 判据 id：`startup_timeout` / `shutdown_timeout`。
+        reason: &'static str,
+        /// 已经等了多久（毫秒）。
+        waited_ms: u64,
+        /// 判据上限（毫秒）。
+        limit_ms: u64,
+        /// 会话事件流（现场）。
+        log_path: PathBuf,
+    },
+}
+
+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}")
+            }
+            Self::Watchdog {
+                pid,
+                reason,
+                waited_ms,
+                limit_ms,
+                log_path,
+            } => {
+                let what = if *reason == "shutdown_timeout" {
+                    "游戏已开始关闭但一直没退出"
+                } else {
+                    "启动后一直没有任何日志、也没出现游戏窗口"
+                };
+                write!(
+                    f,
+                    "{what}：等了 {:.0}s（上限 {:.0}s）就停止等待了。进程 {pid} 仍在运行、没有被结束\
+                     （可能只是加载得慢，也可能真卡住了）；事件流见 {}。放宽上限：设环境变量 \
+                     ULL_LAUNCH_STARTUP_TIMEOUT_SECS / ULL_LAUNCH_SHUTDOWN_GRACE_SECS（秒，0 = 不限）",
+                    *waited_ms as f64 / 1000.0,
+                    *limit_ms as f64 / 1000.0,
+                    log_path.display()
+                )
+            }
+        }
+    }
+}
+
+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,
+            Self::Watchdog { .. } => None,
+        }
+    }
+}
+
+impl From 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..6a21c22
--- /dev/null
+++ b/crates/core/src/launch/exit_analysis.rs
@@ -0,0 +1,311 @@
+//! 退出分析：退出码语义 + `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;
+
+/// 「被外部结束」在 Windows 上的退出码。
+///
+/// 任务管理器「结束任务」与 `taskkill /F` 都走 `TerminateProcess(h, 1)`，进程侧只能看到 1；
+/// 真正的应用崩溃在 Windows 上给的是 NTSTATUS 异常码（`0xC0000005` 等），不会落在 1。
+pub const WINDOWS_TERMINATED_CODE: i32 = 1;
+
+/// 退出分析的输入。
+#[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,
+    /// 命中的 JVM 失败关键字。
+    pub jvm_keywords: Vec,
+    /// 静默失败标记（仅 `Normal` 时可能非空）。
+    pub silent_failure: Option,
+    /// Windows NTSTATUS 解释（例 `0xC0000005 ACCESS_VIOLATION`）。
+    pub windows_status: Option,
+    /// 是否**疑似被外部结束**（任务管理器 / 强杀），而不是应用自己崩了（D10）。
+    ///
+    /// 判据见 [`looks_externally_terminated`]：Windows 上退出码 1 且零错误输出。
+    /// 与「我们杀的」区分开：那条路有 [`crate::launch::kill_registry`] 作据，是**确知**的。
+    pub terminated_externally: bool,
+    /// 是否应该进入诊断流水线（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.terminated_externally {
+            text.push_str("，零错误输出：疑似被外部结束（任务管理器 / 强杀）");
+        }
+        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 looks_externally_terminated(signals, error_lines, &crash_keywords, &jvm_keywords) {
+        // D10：任务管理器 / `taskkill /F` 给的就是「1 + 零错误输出」，不是应用错误。
+        ExitType::Killed
+    } 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),
+        terminated_externally: exit_type == ExitType::Killed
+            && !signals.killed
+            && !signals.interrupted,
+        needs_diagnosis: exit_type.is_abnormal()
+            || silent_failure.is_some()
+            || !crash_keywords.is_empty(),
+    }
+}
+
+/// 外部结束的判据（D10）。
+///
+/// 三条同时成立才算：
+///
+/// 1. **不是我们杀的**（`signals.killed`）——那条路有 [`crate::launch::kill_registry`] 作据；
+/// 2. Windows 上退出码 [`WINDOWS_TERMINATED_CODE`]（`TerminateProcess(h, 1)` 的痕迹）；
+/// 3. **零错误输出**：没有错误行、没有崩溃关键字、没有 JVM 失败关键字。
+///
+/// 「1 + 一句话的报错都没有」不属于应用崩溃：应用崩在 Windows 上给 NTSTATUS 异常码，
+/// JVM 起不来会打 `Could not create the Java Virtual Machine.`，`System.exit(1)` 之前
+/// 一般也有日志。剩下最可能的解释就是「被外面按了结束」——挂死之后任务管理器强杀正是这种形态。
+#[must_use]
+pub fn looks_externally_terminated(
+    signals: &ExitSignals<'_>,
+    error_lines: usize,
+    crash_keywords: &[String],
+    jvm_keywords: &[String],
+) -> bool {
+    !signals.killed
+        && !signals.interrupted
+        && !signals.is_posix
+        && signals.code == WINDOWS_TERMINATED_CODE
+        && error_lines == 0
+        && crash_keywords.is_empty()
+        && jvm_keywords.is_empty()
+}
+
+/// Windows NTSTATUS → 解释。
+pub fn windows_status_name(code: i32) -> Option {
+    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 {
+    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 {
+    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,
+) {
+    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)> {
+    let trimmed = address.trim();
+    if trimmed.is_empty() {
+        return None;
+    }
+    match trimmed.rsplit_once(':') {
+        Some((host, port)) if !host.is_empty() => match port.parse::() {
+            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 {
+    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,
+    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::().ok())
+            .collect::>();
+        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 {
+        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::().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) {
+    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/kill_registry.rs b/crates/core/src/launch/kill_registry.rs
new file mode 100644
index 0000000..e391393
--- /dev/null
+++ b/crates/core/src/launch/kill_registry.rs
@@ -0,0 +1,108 @@
+//! 「这个 pid 是我们主动结束的」的进程内登记簿（D10）。
+//!
+//! M208 实机：挂死的 1.12.2 被强杀后记成「退出码 1（application_error）」，而那一局
+//! `error_lines 0`。问题不在判定表，在**信息丢失**：谁发的结束请求只有调用方知道，
+//! 进程自己只会回一个 1。
+//!
+//! 所以把「我们杀过它」变成一条有据可查的事实：
+//!
+//! - 发送侧（[`crate::launch::tree_kill`]）在发信号前登记 pid，**所有**结束路径都经过那里
+//!   （`RunningProcess::stop` / GUI 的 `host::launch::stop` / 看门狗兜底），不需要每个调用点
+//!   自己记得标记；
+//! - 判定侧（[`crate::launch::launch_session`]）在收尾时取走登记，据此判
+//!   [`ExitType::Killed`](crate::launch::exit_analysis::ExitType::Killed) 而不是应用错误。
+//!
+//! 两条纪律：
+//!
+//! 1. [`take`] 是**取走**语义（判完就忘）：pid 会被复用，留着旧登记会把别的进程误判成
+//!    「我们杀的」；
+//! 2. 登记表有上限（[`MAX_TRACKED`]），登记了却没人消费（进程自己先退了）的条目按 FIFO 淘汰，
+//!    不随运行时长无限增长。
+
+use std::collections::VecDeque;
+use std::sync::{Mutex, OnceLock};
+
+/// 最多同时记住多少个 pid。
+pub const MAX_TRACKED: usize = 64;
+
+fn registry() -> &'static Mutex> {
+    static REGISTRY: OnceLock>> = OnceLock::new();
+    REGISTRY.get_or_init(|| Mutex::new(VecDeque::new()))
+}
+
+/// 登记「我们正在结束 `pid`」（重复登记不叠加）。
+pub fn note(pid: u32) {
+    if pid == 0 {
+        return;
+    }
+    let Ok(mut guard) = registry().lock() else {
+        return;
+    };
+    if guard.contains(&pid) {
+        return;
+    }
+    while guard.len() >= MAX_TRACKED {
+        guard.pop_front();
+    }
+    guard.push_back(pid);
+}
+
+/// 取走登记，返回此前是否登记过。
+pub fn take(pid: u32) -> bool {
+    let Ok(mut guard) = registry().lock() else {
+        return false;
+    };
+    match guard.iter().position(|tracked| *tracked == pid) {
+        Some(index) => {
+            guard.remove(index);
+            true
+        }
+        None => false,
+    }
+}
+
+/// 撤销登记（结束动作没送达、进程其实还在时用，避免下一次误判）。
+pub fn forget(pid: u32) {
+    let Ok(mut guard) = registry().lock() else {
+        return;
+    };
+    if let Some(index) = guard.iter().position(|tracked| *tracked == pid) {
+        guard.remove(index);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{forget, note, take, MAX_TRACKED};
+
+    #[test]
+    fn noted_pid_is_taken_exactly_once() {
+        note(4242);
+        assert!(take(4242), "登记过的 pid 应判成我们杀的");
+        assert!(!take(4242), "取走语义：判完就忘，避免 pid 复用误伤");
+    }
+
+    #[test]
+    fn forgetting_a_pid_clears_the_note() {
+        note(4243);
+        forget(4243);
+        assert!(!take(4243));
+    }
+
+    #[test]
+    fn pid_zero_is_never_tracked() {
+        // 0 在 POSIX 上是「当前进程组」，绝不能出现在登记表里。
+        note(0);
+        assert!(!take(0));
+    }
+
+    #[test]
+    fn registry_is_bounded_and_drops_the_oldest() {
+        let base = 900_000;
+        for offset in 0..u32::try_from(MAX_TRACKED).unwrap() + 5 {
+            note(base + offset);
+        }
+        assert!(!take(base), "最早的一条应被 FIFO 淘汰");
+        assert!(take(base + 5), "上限之后的条目仍在表里");
+    }
+}
diff --git a/crates/core/src/launch/launch_session.rs b/crates/core/src/launch/launch_session.rs
new file mode 100644
index 0000000..1bb5623
--- /dev/null
+++ b/crates/core/src/launch/launch_session.rs
@@ -0,0 +1,343 @@
+//! 运行中的启动会话与收尾流水线。
+//!
+//! 一次启动的生命周期（`DevDocs/PlanDoc/06-launch-and-diagnostics.md` §1 的第 7~10 阶段）：
+//! `spawn` → 用户可能 [`LaunchSession::stop`] → [`LaunchSession::finish`]
+//! （**有界**等进程 → 等日志泵（有预算）→ 退出分析 → 扫崩溃现场 → 诊断挂钩 → 写事件 + 索引）。
+//!
+//! 「有界」是 D6：等进程那一步会按 [`crate::launch::startup_watch`] 的判据停下（窗口从未出现 /
+//! 已出现关闭标记），到点**不杀进程**，只结束本次会话并报 [`crate::launch::error::LaunchError::Watchdog`]。
+//!
+//! 结果是 [`SessionHandle`]（拆到 `session_handle`：那边是纯数据 + 展示）。
+
+use std::path::{Path, PathBuf};
+use std::sync::Arc;
+use std::time::SystemTime;
+
+use crate::launch::args_table::AssembledCommand;
+use crate::launch::crash_scan::{self, CrashArtifact};
+use crate::launch::diagnosis_hook::{DiagnosisHook, DiagnosisRequest};
+use crate::launch::error::{LaunchError, Result};
+use crate::launch::exit_analysis::{self, ExitAnalysis, ExitSignals};
+use crate::launch::kill_registry;
+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::startup_watch::{StartupWatch, WatchVerdict};
+
+pub use crate::launch::session_handle::SessionHandle;
+
+/// 一次运行中的启动会话。
+pub struct LaunchSession {
+    config: LauncherConfig,
+    hook: Arc,
+    redactor: Redactor,
+    request: LaunchRequest,
+    session_id: String,
+    log_path: PathBuf,
+    command: AssembledCommand,
+    pid: u32,
+    process: RunningProcess,
+    sink: Arc,
+    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()
+    }
+}
+
+/// 有界等待的结果（D6）。
+enum WaitOutcome {
+    /// 进程已退出。
+    Exited(std::process::ExitStatus),
+    /// 看门狗判出「活着但没动静」：不杀进程，只是不再等。
+    GaveUp(WatchVerdict),
+}
+
+impl LaunchSession {
+    /// 构造一次会话。
+    #[allow(clippy::too_many_arguments)]
+    pub(crate) fn new(
+        config: LauncherConfig,
+        hook: Arc,
+        redactor: Redactor,
+        request: LaunchRequest,
+        session_id: String,
+        log_path: PathBuf,
+        command: AssembledCommand,
+        pid: u32,
+        process: RunningProcess,
+        sink: Arc,
+    ) -> 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 {
+        self.sink.clone() as Arc
+    }
+
+    /// 已运行毫秒数。
+    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()
+    }
+
+    /// 收尾：**有界地**等进程 → 等日志泵 → 退出分析 → 现场扫描 → 诊断 → 事件 + 索引。
+    ///
+    /// 「有界」是 D6：到点（[`Self::wait_bounded`] 的判据）只**停止等待**，绝不杀进程——
+    /// 用户的加载进度不该被启动器清掉。走那条路时先写 `session_end`（`still_running`）
+    /// 与一行 `launcher.log`，再返回 [`LaunchError::Watchdog`]。
+    pub fn finish(mut self) -> Result {
+        let status = match self.wait_bounded()? {
+            WaitOutcome::Exited(status) => status,
+            WaitOutcome::GaveUp(verdict) => return self.abandon(verdict),
+        };
+        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);
+        // D10：判定「是不是我们杀的」有两个来源——本会话自己的 `stop()`，以及发送侧
+        // （`tree_kill`）留下的登记。GUI 从别的线程 kill 的那条路只经过后者。
+        let killed = self.killed || kill_registry::take(self.pid);
+        signals.killed = 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;
+        // M211/D3：崩溃结论只认真实证据（权威现场文件 / 非 0 退出 + 错误行），不再由
+        // 「有没有 latest.log」推出——那是每局都有的文件。
+        let crash_evidence = crash_scan::has_crash_evidence(&artifacts, &exit);
+        let end_reason = if 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());
+                }
+            }
+            writer.mark_crash(crash_evidence);
+            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::new(
+            self.session_id,
+            self.log_path,
+            self.command,
+            redacted_argv,
+            exit,
+            diagnostics,
+            index,
+            artifacts,
+            uptime_ms,
+            pump_stalled,
+            event_write_errors,
+        ))
+    }
+
+    /// 有界等待：要么进程退出，要么看门狗判出「活着但没动静」（D6）。
+    ///
+    /// 判据在 [`StartupWatch`]（纯逻辑，`startup_watch` 的测试钉住）；这里只把三个信号喂进去：
+    /// 进程是否已退出、窗口是否**出现过**、日志里是否出现了关闭标记。
+    fn wait_bounded(&mut self) -> Result {
+        let limits = self.config.process;
+        let mut watch = StartupWatch::new(limits.startup_timeout, limits.shutdown_grace);
+        let started = self.process.started_at();
+        loop {
+            if let Some(status) = self.process.try_wait()? {
+                return Ok(WaitOutcome::Exited(status));
+            }
+            if self.sink.window_detected() {
+                watch.mark_window();
+            }
+            if let Some(at) = self.sink.last_line_at() {
+                watch.mark_activity(at.saturating_duration_since(started));
+            }
+            if let Some(at) = self.sink.shutdown_seen_at() {
+                watch.mark_shutdown(at.saturating_duration_since(started));
+            }
+            let verdict = watch.verdict(started.elapsed());
+            if !verdict.is_wait() {
+                return Ok(WaitOutcome::GaveUp(verdict));
+            }
+            std::thread::sleep(process::POLL_INTERVAL);
+        }
+    }
+
+    /// 放弃等待：**不杀进程**，把现场写清楚，返回结构化错误。
+    ///
+    /// 三条落点：① `launcher.log` 一行（含判据、上限、pid）；② 会话事件流写
+    /// `session_end`（`still_running`）并追加索引，历史里看得见这一局；③ 错误本身带
+    /// 会话路径与可调的环境变量。
+    fn abandon(self, verdict: WatchVerdict) -> Result {
+        let pid = self.pid;
+        let spent_ms = verdict.waited_ms();
+        crate::launch::launcher_log::record(
+            "launch",
+            &format!(
+                "instance={} session={} 看门狗：{} ⇒ 停止等待（pid {pid} 仍在运行，未结束）",
+                self.request.instance.id,
+                self.session_id,
+                verdict.describe()
+            ),
+        );
+        let _ = self
+            .sink
+            .with_writer(|writer| writer.finish(EndReason::StillRunning));
+        Err(LaunchError::Watchdog {
+            pid,
+            reason: verdict.code(),
+            waited_ms: spent_ms,
+            limit_ms: verdict.limit_ms(),
+            log_path: self.log_path,
+        })
+    }
+
+    fn collect_artifacts(&self) -> Vec {
+        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,
+    ) -> 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()
+        }
+    }
+}
diff --git a/crates/core/src/launch/launcher.rs b/crates/core/src/launch/launcher.rs
new file mode 100644
index 0000000..170f4c2
--- /dev/null
+++ b/crates/core/src/launch/launcher.rs
@@ -0,0 +1,344 @@
+//! 顶层启动管线：组装 → 会话 → 进程 → 退出分析 → 诊断 → 索引。
+//!
+//! 对应 `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::{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, NativesError, NativesPlan, 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 {
+    /// 会话文件根目录（`/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,
+    /// 结束后是否扫描崩溃现场文件。
+    pub scan_crash_reports: bool,
+    /// 现场文件最多收几个。
+    pub max_crash_artifacts: usize,
+}
+
+impl LauncherConfig {
+    /// 以会话根目录构造（其余取默认）。
+    pub fn new(sessions_root: impl Into) -> 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, version: impl Into) -> Self {
+        self.launcher_name = name.into();
+        self.launcher_version = version.into();
+        self
+    }
+
+    /// 让两个看门狗时长按环境变量覆盖（D6 的「可配」出口，宿主显式要求时生效）。
+    #[must_use]
+    pub fn with_watchdog_env(mut self) -> Self {
+        self.process = self.process.with_env_overrides();
+        self
+    }
+
+    /// 一行「看门狗生效值」（D6：卡死之后第一个要看的就是「等了多久才放弃」）。
+    #[must_use]
+    pub fn watchdog_summary(&self) -> String {
+        let startup = self.process.startup_timeout.as_secs();
+        let grace = self.process.shutdown_grace.as_secs();
+        format!(
+            "看门狗：连续 {startup}s 没日志也没窗口就停止等待；出现关闭标记后 {grace}s 仍未退出也停止等待\
+             （0 = 不限；停止等待不结束进程，可用 {} / {} 调整）",
+            crate::launch::process::STARTUP_TIMEOUT_ENV,
+            crate::launch::process::SHUTDOWN_GRACE_ENV,
+        )
+    }
+}
+
+/// `--dry-run` 的输出（D18）：完整命令行，但**不 spawn、不写会话文件、不碰磁盘**。
+///
+/// 「不碰磁盘」是本层（core 启动管线）的承诺：环境准备（第 6 段）在 dry-run 下走
+/// [`crate::launch::natives::preview`]，只算「会解出几个原生库 / natives 目录是不是
+/// 已经就绪」，**不建目录、不写文件、不删文件**——对版本树（尤其是别人铺的
+/// `versions//`）是纯读的。调用方自己的运行日志（CLI 的 `<数据根>/logs/launcher.log`）
+/// 不在此列。
+#[derive(Debug, Clone)]
+pub struct DryRun {
+    /// 实际要执行的程序。
+    pub program: PathBuf,
+    /// 参数（已脱敏：accessToken 一定是 ``）。
+    pub argv: Vec,
+    /// 人读单行（可直接 `println!`，含空格的参数带引号）。
+    pub display: String,
+    /// 组装告警。
+    pub warnings: Vec,
+    /// classpath 条目数。
+    pub classpath_entries: usize,
+    /// 日志解码编码。
+    pub encoding: String,
+    /// natives 预览结果（没有 natives 目录、即请求未配置时为 `None`）。
+    ///
+    /// `planned == true`：`files` 是「真启动会写下」的数量，盘上零改动。
+    pub natives: Option,
+}
+
+impl DryRun {
+    /// 一行命令行（D18 打印用）。
+    pub fn line(&self) -> &str {
+        &self.display
+    }
+}
+
+/// 启动器。
+#[derive(Clone)]
+pub struct Launcher {
+    config: LauncherConfig,
+    hook: Arc,
+}
+
+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", &"")
+            .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) -> Self {
+        self.hook = hook;
+        self
+    }
+
+    /// 配置。
+    pub fn config(&self) -> &LauncherConfig {
+        &self.config
+    }
+
+    /// 只组装命令行（纯计算，可单测/可透传）。
+    pub fn plan(&self, request: &LaunchRequest) -> Result {
+        assemble(request, &self.config.platform)
+    }
+
+    /// 环境准备（管线第 6 段）：natives 解压（**落盘**，真启动专用）。
+    ///
+    /// 目标目录取 `request.dirs.natives_dir`（与 `${natives_directory}` 同一真相源）；
+    /// 目录为空视为调用方不需要，返回 `Ok(None)`。
+    fn prepare_environment(&self, request: &LaunchRequest) -> Result> {
+        self.environment(request, natives::extract)
+    }
+
+    /// 环境准备的第 6 段预览版：只算「会解出什么」，**零落盘**（`--dry-run` 专用）。
+    fn preview_environment(&self, request: &LaunchRequest) -> Result> {
+        self.environment(request, natives::preview)
+    }
+
+    /// 两个入口共用的外壳：空 `natives_dir` = 调用方不需要，失败统一折成组装错误。
+    ///
+    /// `run` 是 [`natives::extract`]（落盘）或 [`natives::preview`]（零落盘）；
+    /// 返回值类型要写全 `std::result::Result`——本模块的 `Result` 别名固定带 `LaunchError`。
+    fn environment(
+        &self,
+        request: &LaunchRequest,
+        run: fn(&Path, &NativesPlan) -> std::result::Result,
+    ) -> Result> {
+        if request.dirs.natives_dir.as_os_str().is_empty() {
+            return Ok(None);
+        }
+        run(&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 ` 打印一行命令行后退出；
+    /// natives 走 [`natives::preview`]（不建目录、不写文件），所以对版本树是纯读的；
+    /// accessToken 已脱敏（绝不把凭据打到终端/日志里）。
+    pub fn dry_run(&self, request: &LaunchRequest) -> Result {
+        let natives = self.preview_environment(request)?;
+        let command = self.plan(request)?;
+        let redactor = self.redactor(request);
+        let warnings = command
+            .warnings
+            .iter()
+            .map(ToString::to_string)
+            .collect::>();
+        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 {
+        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 主入口）。
+    ///
+    /// 「阻塞」有界（D6）：看门狗判出「活着但没动静」时返回 [`crate::launch::error::LaunchError::Watchdog`]，
+    /// 进程**不会**被结束。
+    pub fn launch(&self, request: &LaunchRequest) -> Result {
+        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/launcher_log.rs b/crates/core/src/launch/launcher_log.rs
new file mode 100644
index 0000000..0a02dab
--- /dev/null
+++ b/crates/core/src/launch/launcher_log.rs
@@ -0,0 +1,312 @@
+//! 启动器**自己的**运行日志（M187）：`<.ULL>/logs/launcher.log`。
+//!
+//! ## 为什么要有这个文件
+//!
+//! 用户实测（2026-11-08）：「游戏崩溃后只有一个安装日志，没有崩溃日志」。核查结论是：
+//! `logs/` 分区里此前只有 `install.log`（安装流水）与 auth journal——**启动器自己没有运行期
+//! 日志**。双击启动的 GUI 进程没有 stderr 去向，所有 `eprintln!` 诊断当场蒸发，于是
+//! 「启动器视角发生了什么」在事故之后无法复原。
+//!
+//! 本模块只做一件事：把一行行 `[scope] message` 追加到一个文件里，**落盘即脱敏**。
+//!
+//! ## 三条约束（都是有意的）
+//!
+//! 1. **best-effort**：写不进去就静默放过。日志失败不该让启动器崩、也不该弹提示。
+//! 2. **不阻塞**：不建后台线程、不做异步队列。调用点都是「一次启动 / 一次导出」这种低频事件，
+//!    每次一行 `write_all` 的代价可以忽略；引入通道反而多一处要收尾的生命周期。
+//! 3. **有上限**：超过 [`MAX_BYTES`] 就滚成 `launcher.1.log`（只保留一份历史）。日志文件
+//!    无限长会让「导出诊断包」变成搬砖。
+//!
+//! ## 目录从哪来
+//!
+//! 目录**不是**本模块自己解析的：`.ULL` 的落点由 `platform::data_dir` 的三模式决定（导出的
+//! exe 目录 / 标准目录 / 自定义根），解析它需要读配置——那是宿主（presenter / app）已经做过
+//! 的事。所以这里是「**先到者登记**」：知道真相的调用方用 [`set_dir`] 登记，
+//! 登记之前 [`record`] 的行进内存缓冲（最多 [`MAX_BUFFERED`] 行），登记时一次刷出去。
+//! 这样启动早期（字体 / GPU / 路由）那几行也不会丢。
+
+use std::io::Write;
+use std::path::{Path, PathBuf};
+use std::sync::{Mutex, OnceLock};
+
+use super::launch_session::SessionHandle;
+use super::redact::Redactor;
+
+/// 日志文件名。
+pub const FILE_NAME: &str = "launcher.log";
+/// 单个文件上限（超过就滚成 `launcher.1.log`，只留一份历史）。
+pub const MAX_BYTES: u64 = 1024 * 1024;
+/// 登记目录之前最多缓冲多少行。
+pub const MAX_BUFFERED: usize = 200;
+
+#[derive(Debug, Default)]
+struct State {
+    dir: Option,
+    buffer: Vec,
+}
+
+fn state() -> &'static Mutex {
+    static STATE: OnceLock> = OnceLock::new();
+    STATE.get_or_init(|| Mutex::new(State::default()))
+}
+
+/// 登记日志目录（`<.ULL>/logs`）。重复登记时以**最后一次**为准（数据根可能被 `redirect.json` 改）。
+pub fn set_dir(logs_dir: impl Into) {
+    let dir = logs_dir.into();
+    let mut guard = match state().lock() {
+        Ok(guard) => guard,
+        Err(_) => return,
+    };
+    if guard.dir.as_ref() == Some(&dir) {
+        return;
+    }
+    guard.dir = Some(dir);
+    let buffered = std::mem::take(&mut guard.buffer);
+    let Some(directory) = guard.dir.clone() else {
+        return;
+    };
+    drop(guard);
+    for line in buffered {
+        append(&directory, &line);
+    }
+}
+
+/// 当前日志文件路径（`None` = 还没登记目录）。
+pub fn path() -> Option {
+    let guard = state().lock().ok()?;
+    guard.dir.as_ref().map(|dir| dir.join(FILE_NAME))
+}
+
+/// 记一行（`[scope] message`）。scope 是稳定短的英文标签（`boot` / `launch` / `dialog`）。
+///
+/// 时间戳走 `launch::time::now()`（与事件流同一份时钟口径），所以日志行与 JSONL 能对上。
+pub fn record(scope: &str, message: &str) {
+    let line = format!(
+        "{} [{scope}] {message}",
+        super::time::format_rfc3339_millis(super::time::now())
+    );
+    let dir = {
+        let mut guard = match state().lock() {
+            Ok(guard) => guard,
+            Err(_) => return,
+        };
+        match guard.dir.clone() {
+            Some(dir) => dir,
+            None => {
+                if guard.buffer.len() < MAX_BUFFERED {
+                    guard.buffer.push(line);
+                }
+                return;
+            }
+        }
+    };
+    append(&dir, &line);
+}
+
+/// 一次启动的「启动前」一行：`instance=… game_dir=… java=… memory=…MB`（M211/D5）。
+///
+/// GUI（`presenter::host::launch`）与 CLI（`ull launch`）写的是**同一份** `launcher.log`，
+/// 所以字段名/顺序只在这里定义一次——两边各写一句 `format!` 就等于迟早漂成两种形状。
+fn start_line(
+    instance_id: &str,
+    game_dir: &Path,
+    java: Option<(&Path, u32)>,
+    memory_mb: Option,
+) -> String {
+    let java = java.map_or_else(
+        || "未找到".to_string(),
+        |(binary, major)| java_label(binary, major),
+    );
+    format!(
+        "instance={instance_id} game_dir={} java={java} memory={}MB",
+        game_dir.display(),
+        memory_mb.unwrap_or(0)
+    )
+}
+
+/// `java=` 字段的形状：`<二进制> (major <主版本>)`。
+pub fn java_label(binary: &Path, major: u32) -> String {
+    format!("{} (major {major})", binary.display())
+}
+
+/// 一次启动的「收尾」一行：`instance=… session=… exit=… type=… uptime=…ms outcome=… artifacts=…`。
+///
+/// `outcome` 与 GUI 的 `LogOutcome` 同词（`Ok` / `Crashed` / `SilentFail`），见
+/// [`SessionHandle::outcome_label`]。
+#[allow(clippy::too_many_arguments)]
+fn end_line(
+    instance_id: &str,
+    session_id: &str,
+    exit_code: i32,
+    exit_type: &str,
+    uptime_ms: u64,
+    outcome: &str,
+    artifacts: usize,
+) -> String {
+    format!(
+        "instance={instance_id} session={session_id} exit={exit_code} type={exit_type} \
+         uptime={uptime_ms}ms outcome={outcome} artifacts={artifacts}"
+    )
+}
+
+/// 记「启动前」一行（`instance` / `game_dir` / `java` / `memory`）。
+///
+/// 装配失败也要留下这一行：事故之后「到底打算用什么起的」是第一个要看的。
+pub fn record_start(
+    instance_id: &str,
+    game_dir: &Path,
+    java: Option<(&Path, u32)>,
+    memory_mb: Option,
+) {
+    record(
+        "launch",
+        &start_line(instance_id, game_dir, java, memory_mb),
+    );
+}
+
+/// 记「收尾」一行（`session` / `exit` / `type` / `uptime` / `outcome` / `artifacts`）。
+pub fn record_end(instance_id: &str, handle: &SessionHandle) {
+    record(
+        "launch",
+        &end_line(
+            instance_id,
+            &handle.session_id,
+            handle.exit.code,
+            handle.exit.exit_type.as_str(),
+            handle.uptime_ms,
+            handle.outcome_label(),
+            handle.artifacts.len(),
+        ),
+    );
+}
+
+/// 脱敏器：主目录换成 ``（同一份规则见 [`super::redact`]）。
+fn redactor() -> Redactor {
+    let mut redactor = Redactor::new();
+    for key in ["USERPROFILE", "HOME"] {
+        if let Ok(home) = std::env::var(key) {
+            if !home.trim().is_empty() {
+                redactor = redactor.with_home_str(home);
+            }
+        }
+    }
+    redactor
+}
+
+fn append(dir: &Path, line: &str) {
+    let path = dir.join(FILE_NAME);
+    if let Some(parent) = path.parent() {
+        let _ = std::fs::create_dir_all(parent);
+    }
+    // 滚动：只在超过上限时做一次 rename，平时的路径只有「打开 → 追加 → 关」。
+    if std::fs::metadata(&path).is_ok_and(|meta| meta.len() > MAX_BYTES) {
+        let _ = std::fs::rename(&path, dir.join("launcher.1.log"));
+    }
+    let scrubbed = redactor().scrub(line).into_owned();
+    if let Ok(mut file) = std::fs::OpenOptions::new()
+        .create(true)
+        .append(true)
+        .open(&path)
+    {
+        let _ = file.write_all(scrubbed.as_bytes());
+        let _ = file.write_all(b"\n");
+    }
+}
+
+#[cfg(test)]
+fn state_reset() {
+    if let Ok(mut guard) = state().lock() {
+        guard.dir = None;
+        guard.buffer.clear();
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::MAX_BUFFERED;
+    use std::path::PathBuf;
+
+    /// 测试之间共享全局状态，必须串行（`cargo test` 默认多线程）。
+    static LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
+
+    fn temp_dir(tag: &str) -> PathBuf {
+        let root = std::env::temp_dir().join(format!("ull-m187-log-{}-{tag}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&root);
+        std::fs::create_dir_all(&root).expect("建夹具目录");
+        root
+    }
+
+    #[test]
+    fn buffered_lines_are_flushed_once_the_dir_is_known() {
+        let _guard = LOCK.lock().unwrap_or_else(|error| error.into_inner());
+        super::state_reset();
+        let dir = temp_dir("flush");
+
+        super::record("boot", "before the dir was known");
+        assert!(super::path().is_none(), "没登记目录时不该报出路径");
+        super::set_dir(&dir);
+        super::record("launch", "after");
+
+        let text = std::fs::read_to_string(dir.join(super::FILE_NAME)).expect("读日志");
+        assert!(text.contains("before the dir was known"), "{text}");
+        assert!(text.contains("[launch] after"), "{text}");
+    }
+
+    #[test]
+    fn home_paths_are_scrubbed_on_write() {
+        let _guard = LOCK.lock().unwrap_or_else(|error| error.into_inner());
+        super::state_reset();
+        let dir = temp_dir("scrub");
+        super::set_dir(&dir);
+        let home = std::env::var("USERPROFILE").or_else(|_| std::env::var("HOME"));
+        let Ok(home) = home else {
+            return;
+        };
+        super::record("launch", &format!("argv --nativesDir {home}/natives"));
+        let text = std::fs::read_to_string(dir.join(super::FILE_NAME)).expect("读日志");
+        assert!(text.contains(""), "{text}");
+        assert!(!text.contains(home.as_str()), "家目录原文还在：{text}");
+    }
+
+    #[test]
+    fn buffer_is_bounded_before_the_dir_is_known() {
+        let _guard = LOCK.lock().unwrap_or_else(|error| error.into_inner());
+        super::state_reset();
+        for index in 0..(MAX_BUFFERED + 50) {
+            super::record("boot", &format!("line {index}"));
+        }
+        let dir = temp_dir("bounded");
+        super::set_dir(&dir);
+        let text = std::fs::read_to_string(dir.join(super::FILE_NAME)).expect("读日志");
+        let lines = text.lines().count();
+        assert!(lines <= MAX_BUFFERED, "缓冲没有上限：{lines} 行");
+        assert!(lines > 0);
+    }
+
+    /// M211/D5：GUI 与 `ull launch` 写**同一份** `launcher.log`，所以形状只能有一套。
+    ///
+    /// 变异证明：把 `start_line`/`end_line` 里的键名或顺序改掉（例如 `memory` → `mem`）⇒
+    /// 本条的字符串相等断言红——这正是「两条路各自 `format!`」时会发生的事。
+    #[test]
+    fn launch_lines_have_one_shape_for_both_entries() {
+        use std::path::Path;
+        assert_eq!(
+            super::start_line(
+                "inst",
+                Path::new("C:/mc"),
+                Some((Path::new("C:/jdk/bin/java.exe"), 17)),
+                Some(4096),
+            ),
+            "instance=inst game_dir=C:/mc java=C:/jdk/bin/java.exe (major 17) memory=4096MB"
+        );
+        assert_eq!(
+            super::start_line("inst", Path::new("C:/mc"), None, None),
+            "instance=inst game_dir=C:/mc java=未找到 memory=0MB"
+        );
+        assert_eq!(
+            super::end_line("inst", "sid", 1, "application_error", 1234, "Crashed", 2),
+            "instance=inst session=sid exit=1 type=application_error \
+             uptime=1234ms outcome=Crashed artifacts=2"
+        );
+    }
+}
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]: ...` 里取级别。
+///
+/// 逐段扫描方括号内容，取第一段形如 `<线程名>/` 的级别，最多看 3 段。
+fn log4j_level(line: &str) -> Option {
+    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 {
+    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 {
+    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..fc609c9
--- /dev/null
+++ b/crates/core/src/launch/mod.rs
@@ -0,0 +1,93 @@
+//! 启动管线：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`]）。
+//!
+//! # 两条实机修正（M208 台账）
+//!
+//! - **D6 有界等待**：进程也可能「活着但没动静」。判据在 [`startup_watch`]
+//!   （未见过窗口 / 已出现关闭标记），到点只**停止等待**并返回
+//!   [`LaunchError::Watchdog`]——绝不杀进程，用户的加载进度不该被启动器清掉；
+//! - **D10 结束归属**：谁结束的进程只有调用方知道，所以 [`tree_kill`] 送达即登记
+//!   （[`kill_registry`]），退出分析据此判「被终止」而不是「应用错误」；外部强杀
+//!   （任务管理器）走[`exit_analysis::looks_externally_terminated`] 的 Windows 判据。
+//!
+//! 零 UI 依赖：本模块只产出结构化事件与纯数据，不 import 任何 UI 类型。
+
+pub mod adapter;
+pub mod args_table;
+pub mod argument;
+pub mod command_builder;
+pub mod crash_bundle;
+pub mod crash_report;
+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 kill_registry;
+pub mod launch_session;
+pub mod launcher;
+pub mod launcher_log;
+pub mod log_level;
+pub mod natives;
+pub mod overrides;
+pub mod placeholders;
+pub mod platform;
+pub mod process;
+pub mod pump;
+pub mod redact;
+pub mod request;
+pub mod session;
+pub mod session_handle;
+pub mod session_index;
+pub mod session_meta;
+pub mod session_payload;
+pub mod session_sink;
+pub mod sink;
+pub mod startup_watch;
+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_report::{ArtifactFact, CrashReport, Evidence, ReportContext};
+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};
+pub use startup_watch::{StartupWatch, WatchVerdict};
diff --git a/crates/core/src/launch/natives/jar.rs b/crates/core/src/launch/natives/jar.rs
new file mode 100644
index 0000000..734e230
--- /dev/null
+++ b/crates/core/src/launch/natives/jar.rs
@@ -0,0 +1,288 @@
+//! 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,
+}
+
+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,
+    source: io::Error,
+) -> NativesError {
+    NativesError::Io {
+        op,
+        path: path.into(),
+        source,
+    }
+}
+
+/// 打开一个 natives jar（打不开 / 不是合法 zip 都以 [`NativesError`] 带路径报出）。
+fn open_archive(native: &NativeJar) -> Result, NativesError> {
+    let file = File::open(&native.path)
+        .map_err(|source| io_error("open_native_jar", &native.path, source))?;
+    ZipArchive::new(file).map_err(|err| NativesError::Zip {
+        path: native.path.clone(),
+        reason: err.to_string(),
+    })
+}
+
+/// 该落盘的条目（zip 索引 + 相对路径）：排除前缀 → 原生库白名单 → zip-slip 防护。
+///
+/// 只读遍历，不解压：`extract_jar` 拿它算落点，`count_jar` 拿它清点数量，
+/// 两边共用同一套筛选口径（预览与真解压不会给出不同的数字）。
+fn extractable_entries(
+    archive: &mut ZipArchive,
+    native: &NativeJar,
+    report: &mut NativesReport,
+) -> Result, NativesError> {
+    let excludes: Vec<&str> = DEFAULT_EXCLUDES
+        .iter()
+        .copied()
+        .chain(native.exclude.iter().map(String::as_str))
+        .collect();
+    let mut entries = Vec::new();
+    for index in 0..archive.len() {
+        let 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;
+        }
+        entries.push((index, relative));
+    }
+    Ok(entries)
+}
+
+/// 解压单个 jar：`extractable_entries` 选条目，再逐个落到 `dir` 下。
+pub(crate) fn extract_jar(
+    native: &NativeJar,
+    dir: &Path,
+    report: &mut NativesReport,
+) -> Result<(), NativesError> {
+    let mut archive = open_archive(native)?;
+    for (index, relative) in extractable_entries(&mut archive, native, report)? {
+        let mut entry = archive.by_index(index).map_err(|err| NativesError::Zip {
+            path: native.path.clone(),
+            reason: err.to_string(),
+        })?;
+        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(())
+}
+
+/// 只读清点单个 jar：只算「真解压会写下几个原生库」，一个字节都不落盘。
+///
+/// 与 [`extract_jar`] 的差别只有「写」这一步；jar 打不开照样报错，所以预览不会把
+/// 真启动会遇到的坏包藏起来。
+pub(crate) fn count_jar(
+    native: &NativeJar,
+    report: &mut NativesReport,
+) -> Result<(), NativesError> {
+    let mut archive = open_archive(native)?;
+    let entries = extractable_entries(&mut archive, native, report)?;
+    report.files += entries.len();
+    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 {
+    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 {
+    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..df653f8
--- /dev/null
+++ b/crates/core/src/launch/natives/mod.rs
@@ -0,0 +1,354 @@
+//! natives 解压：把版本链里的 natives 分类器构件解到 `versions//natives/`。
+//!
+//! 这是 10 阶段管线里**第 6 段「环境准备」**的落盘部分（`PlanDoc/06` §1），发生顺序在
+//! 命令行组装之前（HMCL 也在组装期做：`DefaultLauncher.decompressNatives`，
+//! `analyse/03` §6.4-(7)）。
+//!
+//! # 两条路径
+//!
+//! - [`extract`]：真启动走这条，把原生库落到 `java.library.path`；
+//! - [`preview`]：`--dry-run` 走这条，**零落盘**（不建目录、不写文件、不删文件），
+//!   只回答「真启动会解出几个文件 / 目录是不是已经就绪」。断言口径与 [`extract`]
+//!   共用（同一套条目筛选、同一份戳记），所以预览能当「装完能不能起」的依据，
+//!   又不会在别人的版本树里留下 `natives/` 目录或改掉父目录 mtime。
+//!
+//! # 三个时代（`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;
+/// 报告与错误类型（`mod.rs` 只留计划与两个入口）。
+pub(crate) mod report;
+
+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//.../--natives-.jar`）。
+    pub path: PathBuf,
+    /// 坐标 + 分类器（`org.lwjgl:lwjgl:3.2.2:natives-windows`，报错与事件里用）。
+    pub name: String,
+    /// 清单 `extract.exclude` 的排除前缀（`["META-INF/"]`）。
+    pub exclude: Vec,
+}
+
+impl NativeJar {
+    /// 构造（无排除规则）。
+    pub fn new(path: impl Into, name: impl Into) -> Self {
+        Self {
+            path: path.into(),
+            name: name.into(),
+            exclude: Vec::new(),
+        }
+    }
+
+    /// 带清单排除规则构造。
+    pub fn with_exclude(
+        path: impl Into,
+        name: impl Into,
+        exclude: Vec,
+    ) -> 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,
+    /// 时代（只影响报告字段；解压路径三时代统一）。
+    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) -> 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()
+    }
+}
+
+/// 解压结果 / 预览结果与失败原因单独成文件（`mod.rs` 只留计划与两个入口）。
+pub use report::{NativesError, NativesReport};
+
+/// 从版本链库表收集 natives 分类器构件（adapter / app / CLI 共用这一段，别各写一份）。
+///
+/// 口径与安装层 `game::install::libraries::plan` **除 `hint=local` 落点外**逐条对齐：
+/// 1. 先按环境过滤（`Library::applies`）；
+/// 2. `natives` 表命中当前 OS 才取分类器（1.19+ 没有 `natives` 表 → 返回空表）；
+/// 3. 落点优先用清单 `downloads.classifiers..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 {
+    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
+}
+
+/// 目录状态的三种结论：两个入口共用一条判定链，别各写一份。
+enum DirStatus {
+    /// 无需解压：1.19+ 没有 natives 分类器 jar，只要目录在。
+    NoJars,
+    /// 戳记与当前 jar 集一致：目录已就绪，上次解出 `usize` 个原生库。
+    Ready(usize),
+    /// 需要（重新）解压。
+    Stale,
+}
+
+/// 判定链 + 本次源 jar 指纹（真解压拿它写戳记，预览丢弃）。
+///
+/// `extract` 与 `preview` **只在这里**决定「要不要解压」：改判定只改这一处，
+/// 两边不会漂。
+fn inspect(dir: &Path, plan: &NativesPlan) -> (DirStatus, Vec) {
+    let stamps = jar_stamps(&plan.jars);
+    if plan.jars.is_empty() {
+        return (DirStatus::NoJars, stamps);
+    }
+    let ready = read_stamp(dir)
+        .filter(|stamp| stamp.matches(&stamps))
+        .map(|stamp| stamp.files());
+    match ready {
+        Some(files) => (DirStatus::Ready(files), stamps),
+        None => (DirStatus::Stale, stamps),
+    }
+}
+
+/// 解压一个计划（幂等：目录与源 jar 都没变时零写盘）。
+///
+/// `--dry-run` 不走这里，走 [`preview`]：那里一个字节都不写。
+///
+/// # Errors
+///
+/// 目录为空、建目录 / 写文件失败、jar 不是合法 zip 时返回 [`NativesError`]。
+pub fn extract(dir: &Path, plan: &NativesPlan) -> Result {
+    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,
+        planned: false,
+        dir_exists: 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))?;
+    report.dir_exists = true;
+    let (status, stamps) = inspect(dir, plan);
+    match status {
+        DirStatus::NoJars => {
+            report.up_to_date = true;
+            return Ok(report);
+        }
+        DirStatus::Ready(files) => {
+            report.up_to_date = true;
+            report.skipped = files;
+            return Ok(report);
+        }
+        DirStatus::Stale => {}
+    }
+
+    // 源变了：先清旧原生库（避免两代 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)
+}
+
+/// 预览一个计划：算出「真启动会怎么解压」，**不建目录、不写文件、不删文件**。
+///
+/// `--dry-run` 的唯一环境准备入口。与 [`extract`] 共用判定链（[`inspect`]）与条目
+/// 筛选口径：无 jar（1.19+）= 无需解压；戳记与当前 jar 集一致 = 已就绪；否则读 jar
+/// 清点「将写下几个原生库」。区别只有「不落盘」：没有 `create_dir_all`、没有
+/// `clear_natives`、没有 `write_stamp`，因此版本树的目录结构与父目录 mtime 都不动。
+///
+/// jar 打不开 / 不是合法 zip 照样报错（与真启动同一条失败路径），预览不会藏坏包。
+///
+/// # Errors
+///
+/// 目录为空、jar 打不开或不是合法 zip 时返回 [`NativesError`]。
+pub fn preview(dir: &Path, plan: &NativesPlan) -> Result {
+    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,
+        planned: true,
+        dir_exists: dir.is_dir(),
+    };
+    let (status, _stamps) = inspect(dir, plan);
+    match status {
+        DirStatus::NoJars => {
+            report.up_to_date = true;
+            return Ok(report);
+        }
+        DirStatus::Ready(files) => {
+            report.up_to_date = true;
+            report.skipped = files;
+            return Ok(report);
+        }
+        DirStatus::Stale => {}
+    }
+
+    for native in &plan.jars {
+        jar::count_jar(native, &mut report)?;
+    }
+    Ok(report)
+}
diff --git a/crates/core/src/launch/natives/report.rs b/crates/core/src/launch/natives/report.rs
new file mode 100644
index 0000000..42a53fc
--- /dev/null
+++ b/crates/core/src/launch/natives/report.rs
@@ -0,0 +1,160 @@
+//! natives 的报告与错误：真解压与预览共用的 [`NativesReport`] / [`NativesError`]。
+//!
+//! 单独成文件是为了让 `mod.rs` 只留「计划 + 两个入口（`extract` / `preview`）」，
+//! 本仓的红线是单文件 ≤400 行。
+
+use std::path::PathBuf;
+
+use super::NativesEra;
+
+/// 解压结果 / 预览结果（进 `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,
+    /// 报告是否来自只读预览（[`super::preview`]）。true = 盘上零改动，`files` 只是预计值。
+    pub planned: bool,
+    /// 报告生成时目标目录是否已在盘上。
+    ///
+    /// 预览时这是**盘上真值**（用于区分「目录已就绪」与「真启动才会建出来」）；
+    /// 真解压路径在 `create_dir_all` 之后恒为 true。
+    pub dir_exists: bool,
+}
+
+impl NativesReport {
+    /// 人读一行（CLI / 日志用）。
+    pub fn summary(&self) -> String {
+        if self.planned {
+            return self.planned_summary();
+        }
+        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()
+        )
+    }
+
+    /// 预览版人读一行：句句带「将 / 未落盘」，别让用户把预览当成已经解好了。
+    fn planned_summary(&self) -> String {
+        if self.jars == 0 {
+            return if self.dir_exists {
+                format!(
+                    "natives 目录已就绪（该版本无需解压，LWJGL 运行期自取）→ {}",
+                    self.dir.display()
+                )
+            } else {
+                format!(
+                    "natives 目录尚不存在，真启动会建出来（--dry-run 未落盘）→ {}",
+                    self.dir.display()
+                )
+            };
+        }
+        if self.up_to_date {
+            return format!(
+                "natives 已就绪（{} 个原生库，{} 个 jar 未变；--dry-run 未落盘）",
+                self.skipped, self.jars
+            );
+        }
+        format!(
+            "将解压 {} 个原生库（{} 个 jar，忽略 {} 个条目）→ {}（--dry-run 未落盘）",
+            self.files,
+            self.jars,
+            self.ignored,
+            self.dir.display()
+        )
+    }
+
+    /// `--json` 的 `natives` 块（`ull launch --dry-run` 用；字段名是接口的一部分）。
+    #[must_use]
+    pub fn to_json(&self) -> serde_json::Value {
+        serde_json::json!({
+            "dir": self.dir.display().to_string(),
+            "files": self.files,
+            "skipped": self.skipped,
+            "ignored": self.ignored,
+            "jars": self.jars,
+            "custom": self.custom,
+            "up_to_date": self.up_to_date,
+            "era": self.era.as_str(),
+            "planned": self.planned,
+            "dir_exists": self.dir_exists,
+        })
+    }
+}
+
+/// 解压失败原因。
+#[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 {}
diff --git a/crates/core/src/launch/overrides.rs b/crates/core/src/launch/overrides.rs
new file mode 100644
index 0000000..d6b7f4d
--- /dev/null
+++ b/crates/core/src/launch/overrides.rs
@@ -0,0 +1,74 @@
+//! 实例级启动参数的**落位**：`ResolvedLaunch` → [`LaunchRequest`]。
+//!
+//! 三级回落本身在 [`crate::game::launch_overrides`]（纯计算）；本模块只回答「落到哪一段」，
+//! 规则与理由见 M157 的定案（叠加/冲突），这里给出可执行的对照表：
+//!
+//! | 生效值 | 落点 | 组装表 | 为什么在这儿 |
+//! |---|---|---|---|
+//! | 全局 `java.extra_args` | `user.jvm` | 第 7 项 | 基线：按“默认值”处理，可被清单参数抑制 |
+//! | 实例 `launch.jvmArgs` | `user.override_jvm` | 第 4 项 | 精调：最高优先级，`-Xmx`/编码/代理默认值全被它抑制 |
+//! | 实例 `launch.gameArgs` | `user.game` | 第 32 项 | 最后追加，可覆盖前面一切游戏参数 |
+//! | `memoryMb`（已回落） | `memory.max_mb` | 第 5 项 | `-Xmx` 只从这里长出来 |
+//! | `graphicsBackend` | `graphics_backend` | 第 31 项 | 仍过 `graphics_backend_allowed` 门槛，不放行给诊断告警 |
+//! | `javaPath` | **不进来** | — | Java 选择在调用方（`JavaSelection`），见标量注释 |
+//!
+//! # 两条必须一起读的结论
+//!
+//! 1. **追加，不替换**：全局与实例的 JVM 参数都下发。实例段在前、全局段在后，同名选项由 JVM
+//!    取后出现者——但注意组装表第 4 项在 `-Xmx` **之前**：实例文本里的 `-Xmx` 会抑制内存字段
+//!    产出的 `-Xmx`（这是「文本比字段更精确」的表达，不是 bug）；
+//! 2. **全局文本里的 `-Xmx` 不生效**：第 7 项晚于第 5 项，`-Xmx` 已被内存字段占住
+//!    （`add_default` 语义）。要改堆请用内存字段或实例 JVM 文本——写进注释与测试，别当特例。
+//!
+//! `javaPath` 不进 `LaunchRequest`：那份结构只收选好的 [`crate::launch::request::JavaSelection`]，
+//! 调用方用 `resolved.java_path` 决定「显式路径优先 / 自动挑」。
+
+use std::path::Path;
+
+use crate::game::launch_overrides::ResolvedLaunch;
+use crate::launch::command_builder::tokenize;
+use crate::launch::request::{LaunchRequest, MemoryOptions};
+
+/// 把三级回落后的生效值写进请求（覆盖 `user.*` / `memory` / `graphics_backend` 三处）。
+///
+/// 调用方在 [`crate::launch::adapter::build_request`] 之后调用一次即可；它**接管**这三处，
+/// 所以别在此之前再往 `user` 里塞东西（目前 CLI 与 GUI 都没有别的来源，契约就是这一段）。
+pub fn apply(request: &mut LaunchRequest, resolved: &ResolvedLaunch) {
+    request.user.jvm = tokens(resolved.global_jvm_args.as_deref());
+    request.user.override_jvm = tokens(resolved.instance_jvm_args.as_deref());
+    request.user.game = tokens(resolved.game_args.as_deref());
+    request.memory = MemoryOptions {
+        min_mb: request.memory.min_mb,
+        max_mb: Some(resolved.memory_mb),
+    };
+    request.graphics_backend = resolved.graphics_backend.flag_value().map(str::to_string);
+}
+
+/// 实例/全局给的显式 Java 路径（`None` = 调用方走自动挑）。
+#[must_use]
+pub fn java_binary(resolved: &ResolvedLaunch) -> Option<&Path> {
+    resolved.java_path.as_deref()
+}
+
+/// 版本能不能下发 `--graphicsBackend`：**解析过继承链的**版本 JSON + 游戏版本号。
+///
+/// `resolved_json` 必须是继承解析之后的那份（26.2 的 `lwjgl-vulkan` 在父层，
+/// 只看 loader 层会漏）。判据本身仍是 [`graphics_backend_allowed`] 一处实现——
+/// UI 与拼装链共用它，别在调用方再抄一遍能力位判断。
+#[must_use]
+pub fn backend_allowed(
+    version: &crate::launch::game_version::GameVersion,
+    resolved_json: &crate::game::VersionJson,
+) -> bool {
+    crate::launch::game_args::graphics_backend_allowed(
+        version,
+        crate::game::VersionCapabilities::from_json(resolved_json).has_vulkan_backend,
+    )
+}
+
+fn tokens(text: Option<&str>) -> Vec {
+    text.map(tokenize).unwrap_or_default()
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/core/src/launch/overrides/tests.rs b/crates/core/src/launch/overrides/tests.rs
new file mode 100644
index 0000000..7dc1f58
--- /dev/null
+++ b/crates/core/src/launch/overrides/tests.rs
@@ -0,0 +1,356 @@
+use std::path::PathBuf;
+
+use super::*;
+use crate::game::launch_overrides::{
+    resolve, GlobalLaunchDefaults, GraphicsBackend, LaunchOverrides,
+};
+use crate::launch::adapter::{build_request, AdapterOptions, LibraryInput, SnapshotInput};
+use crate::launch::args_table::{assemble, AssemblyWarning};
+use crate::launch::game_version::GameVersion;
+use crate::launch::platform::{OsFamily, PlatformCtx};
+use crate::launch::request::{
+    AuthPlaceholders, InstanceInfo, JavaSelection, LaunchDirs, LauncherInfo, Log4jOptions,
+    ManifestArgs, OptimizationOptions,
+};
+
+fn request(version: &str) -> LaunchRequest {
+    LaunchRequest {
+        instance: InstanceInfo {
+            id: "inst-1".to_string(),
+            name: version.to_string(),
+            version: GameVersion::parse(version),
+            version_type: "release".to_string(),
+        },
+        launcher: LauncherInfo {
+            name: "UnluckyLauncher".to_string(),
+            version: "0.2.2".to_string(),
+        },
+        java: JavaSelection::new("C:/java/bin/java.exe", 21, 64),
+        memory: MemoryOptions {
+            min_mb: None,
+            max_mb: None,
+        },
+        manifest: ManifestArgs {
+            main_class: Some("net.minecraft.client.main.Main".to_string()),
+            ..ManifestArgs::default()
+        },
+        dirs: LaunchDirs {
+            game_dir: PathBuf::from("C:/mc"),
+            primary_jar: PathBuf::from("C:/mc/versions/x/x.jar"),
+            ..LaunchDirs::default()
+        },
+        classpath: vec![PathBuf::from("C:/mc/libraries/a.jar")],
+        auth: AuthPlaceholders::default(),
+        log4j: Log4jOptions {
+            enabled: false,
+            ..Log4jOptions::default()
+        },
+        optimization: OptimizationOptions {
+            enabled: false,
+            physical_memory_mb: None,
+        },
+        language: "zh-CN".to_string(),
+        ..LaunchRequest::default()
+    }
+}
+
+fn ctx() -> PlatformCtx {
+    PlatformCtx::new(OsFamily::Windows, "x86_64")
+}
+
+fn argvs(req: &LaunchRequest) -> Vec {
+    assemble(req, &ctx()).expect("组装应成功").args
+}
+
+fn position(args: &[String], needle: &str) -> Option {
+    args.iter().position(|arg| arg == needle)
+}
+
+/// **叠加规则**：实例段在 `-Xmx` 之前、全局段在之后；两段都下发（不替换）。
+#[test]
+fn instance_and_global_jvm_args_stack_in_order() {
+    let instance = LaunchOverrides {
+        jvm_args: Some("-XX:+UseG1GC".to_string()),
+        ..LaunchOverrides::default()
+    };
+    let global = GlobalLaunchDefaults {
+        jvm_args: Some("-Xss4m".to_string()),
+        ..GlobalLaunchDefaults::default()
+    };
+    let resolved = resolve(Some(&instance), &global);
+    let mut req = request("1.20.4");
+    apply(&mut req, &resolved);
+    let args = argvs(&req);
+
+    let instance_at = position(&args, "-XX:+UseG1GC").expect("实例参数要下发");
+    let memory_at = position(&args, "-Xmx2048m").expect("内存字段要产 -Xmx");
+    let global_at = position(&args, "-Xss4m").expect("全局参数要下发");
+    assert!(
+        instance_at < memory_at,
+        "实例段（override_jvm）必须在 -Xmx 之前：{args:?}"
+    );
+    assert!(
+        global_at > memory_at,
+        "全局段（user.jvm）在 -Xmx 之后（基线不抢内存字段）：{args:?}"
+    );
+}
+
+/// **-Xmx 冲突**：实例文本写 `-Xmx` ⇒ 内存字段不再产出（文本赢）；全局文本写 `-Xmx` ⇒ 被内存字段抑制。
+#[test]
+fn xmx_conflict_follows_the_assembly_order() {
+    let instance = LaunchOverrides {
+        jvm_args: Some("-Xmx3g".to_string()),
+        ..LaunchOverrides::default()
+    };
+    let resolved = resolve(Some(&instance), &GlobalLaunchDefaults::default());
+    let mut req = request("1.20.4");
+    apply(&mut req, &resolved);
+    let args = argvs(&req);
+    assert!(
+        args.iter().any(|arg| arg == "-Xmx3g"),
+        "实例文本的 -Xmx 必须生效：{args:?}"
+    );
+    assert!(
+        !args.iter().any(|arg| arg == "-Xmx2048m"),
+        "内存字段的 -Xmx 必须被抑制：{args:?}"
+    );
+
+    let resolved = resolve(None, &GlobalLaunchDefaults::with_jvm_args("-Xmx3g"));
+    let mut req = request("1.20.4");
+    apply(&mut req, &resolved);
+    let args = argvs(&req);
+    assert!(
+        args.iter().any(|arg| arg == "-Xmx2048m"),
+        "全局文本的 -Xmx 不生效（第 7 项晚于第 5 项）：{args:?}"
+    );
+    assert!(!args.iter().any(|arg| arg == "-Xmx3g"), "{args:?}");
+}
+
+/// 内存三级回落落进 `-Xmx`：实例 → 全局 → 默认。
+#[test]
+fn memory_falls_back_into_xmx() {
+    let global = GlobalLaunchDefaults {
+        memory_mb: Some(6144),
+        ..GlobalLaunchDefaults::default()
+    };
+    let instance = LaunchOverrides {
+        memory_mb: Some(8192),
+        ..LaunchOverrides::default()
+    };
+    for (overrides, expected) in [(Some(instance), "-Xmx8192m"), (None, "-Xmx6144m")] {
+        let resolved = resolve(overrides.as_ref(), &global);
+        let mut req = request("1.20.4");
+        apply(&mut req, &resolved);
+        assert!(
+            argvs(&req).iter().any(|arg| arg == expected),
+            "期望 {expected}"
+        );
+    }
+    let resolved = resolve(None, &GlobalLaunchDefaults::default());
+    let mut req = request("1.20.4");
+    apply(&mut req, &resolved);
+    assert!(argvs(&req).iter().any(|arg| arg == "-Xmx2048m"));
+}
+
+/// 游戏参数最后追加（可覆盖前面一切游戏参数）。
+#[test]
+fn game_args_land_at_the_tail() {
+    let instance = LaunchOverrides {
+        game_args: Some("--fullscreen --width 1920".to_string()),
+        ..LaunchOverrides::default()
+    };
+    let resolved = resolve(Some(&instance), &GlobalLaunchDefaults::default());
+    let mut req = request("1.20.4");
+    apply(&mut req, &resolved);
+    let args = argvs(&req);
+    let tail = &args[args.len() - 3..];
+    assert_eq!(tail, ["--fullscreen", "--width", "1920"], "{args:?}");
+}
+
+/// **版本门槛**：26.2-snapshot-2+ 才下发；老版本不下发但必须给诊断告警（不静默）。
+#[test]
+fn graphics_backend_is_version_gated_with_a_warning() {
+    let instance = LaunchOverrides {
+        graphics_backend: Some(GraphicsBackend::Vulkan),
+        ..LaunchOverrides::default()
+    };
+    let resolved = resolve(Some(&instance), &GlobalLaunchDefaults::default());
+
+    let mut supported = request("26.2-snapshot-2");
+    apply(&mut supported, &resolved);
+    let command = assemble(&supported, &ctx()).expect("组装");
+    let at = position(&command.args, "--graphicsBackend").expect("支持版本要下发");
+    assert_eq!(command.args[at + 1], "vulkan");
+    assert!(
+        !command
+            .warnings
+            .iter()
+            .any(|warning| matches!(warning, AssemblyWarning::GraphicsBackendSkipped { .. })),
+        "支持版本不该有跳过告警：{:?}",
+        command.warnings
+    );
+
+    let mut old = request("1.20.4");
+    apply(&mut old, &resolved);
+    let command = assemble(&old, &ctx()).expect("组装");
+    assert!(
+        !command.args.iter().any(|arg| arg == "--graphicsBackend"),
+        "老版本不许下发：{:?}",
+        command.args
+    );
+    assert!(
+        command
+            .warnings
+            .iter()
+            .any(|warning| matches!(warning, AssemblyWarning::GraphicsBackendSkipped { .. })),
+        "跳过必须留诊断：{:?}",
+        command.warnings
+    );
+}
+
+/// `default` = 不下发、不告警（三态里的「跟随游戏默认」）。
+#[test]
+fn default_backend_emits_nothing() {
+    for instance in [None, Some(LaunchOverrides::default())] {
+        let resolved = resolve(instance.as_ref(), &GlobalLaunchDefaults::default());
+        let mut req = request("26.2");
+        apply(&mut req, &resolved);
+        let command = assemble(&req, &ctx()).expect("组装");
+        assert!(!command.args.iter().any(|arg| arg == "--graphicsBackend"));
+        assert!(command.warnings.is_empty(), "{:?}", command.warnings);
+    }
+}
+
+/// 启动器自带的 `--fullscreen`（第 29 项）与实例游戏参数共存：实例在最后，可覆盖。
+#[test]
+fn instance_game_args_win_over_launcher_defaults() {
+    let instance = LaunchOverrides {
+        game_args: Some("--fullscreen".to_string()),
+        ..LaunchOverrides::default()
+    };
+    let resolved = resolve(Some(&instance), &GlobalLaunchDefaults::default());
+    let mut req = request("1.20.4");
+    req.fullscreen = true;
+    apply(&mut req, &resolved);
+    let args = argvs(&req);
+    assert_eq!(
+        args.iter()
+            .filter(|arg| arg.as_str() == "--fullscreen")
+            .count(),
+        2,
+        "两处都给 --fullscreen，由 MC 取后者（实例段在最后）：{args:?}"
+    );
+    assert_eq!(args.last().map(String::as_str), Some("--fullscreen"));
+    assert!(
+        position(&args, "net.minecraft.client.main.Main").unwrap() < args.len() - 1,
+        "实例游戏参数必须在主类之后"
+    );
+}
+
+/// Java 路径不进请求、只作为调用方的选择依据。
+#[test]
+fn java_path_is_a_scalar_for_the_caller() {
+    let instance = LaunchOverrides {
+        java_path: Some(PathBuf::from("D:/jdk21/bin/java.exe")),
+        ..LaunchOverrides::default()
+    };
+    let resolved = resolve(Some(&instance), &GlobalLaunchDefaults::default());
+    assert_eq!(
+        java_binary(&resolved),
+        Some(Path::new("D:/jdk21/bin/java.exe"))
+    );
+    let mut req = request("1.20.4");
+    let before = req.java.binary.clone();
+    apply(&mut req, &resolved);
+    assert_eq!(req.java.binary, before, "apply 不改 Java 选择");
+}
+
+/// `backend_allowed`：继承解析后的库表 + 版本门限，两条判据的**唯一组合入口**。
+///
+/// 它是 UI 灰化与拼装链共用的那一格：调用方只负责把「继承解析后的版本 JSON」和
+/// 「游戏版本号」递进来，不许自己拼 `has_vulkan_backend && is_at_least(..)`。
+#[test]
+fn backend_allowed_combines_capability_and_threshold() {
+    use crate::game::VersionJson;
+
+    let with_vulkan = VersionJson::from_json_str(
+        r#"{"id":"x","libraries":[{"name":"org.lwjgl:lwjgl-vulkan:3.4.3"}]}"#,
+    )
+    .expect("解析");
+    let without = VersionJson::from_json_str(r#"{"id":"x"}"#).expect("解析");
+
+    // 可解析版本：精确门限说了算（库表只作周快照兜底）。
+    assert!(backend_allowed(
+        &GameVersion::parse("26.2-snapshot-2"),
+        &without
+    ));
+    assert!(!backend_allowed(
+        &GameVersion::parse("26.2-snapshot-1"),
+        &with_vulkan
+    ));
+    assert!(!backend_allowed(
+        &GameVersion::parse("1.20.4"),
+        &with_vulkan
+    ));
+    // 周快照：看库表。
+    assert!(backend_allowed(&GameVersion::parse("26w14a"), &with_vulkan));
+    assert!(!backend_allowed(&GameVersion::parse("26w14a"), &without));
+}
+
+/// **周快照 + 加载器**（M157 r3 复审 P2-1）：装配门限必须按**继承链的 MC 根版本**判。
+///
+/// 造一个 Fabric 实例（id `26w14a-fabric-0.16.5`，继承周快照 `26w14a`），库表里有
+/// `org.lwjgl:lwjgl-vulkan`：`game_version = Some("26w14a")` ⇒ 命令行带 `--graphicsBackend vulkan`；
+/// 退回到「拿带加载器后缀的 version_id 当游戏版本」⇒ `GameVersion::is_weekly_snapshot`
+/// 的 6 字符形态认不出来，参数被跳过（**负向锚点**：这正是复审复现出来的静默丢失）。
+///
+/// 抓得住：adapter 的 `game_version` 传错（调用方又回退成 `None`）——周快照 loader 实例
+/// 「UI 说可用、命令行里没有」。
+/// 抓不住：两个调用点自己有没有传（那由 presenter `host::launch::tests` 与
+/// CLI `snapshot::tests` 各自的根版本断言守）。
+#[test]
+fn modded_weekly_snapshot_needs_the_root_version_for_the_gate() {
+    let version_id = "26w14a-fabric-0.16.5";
+    let libraries = [LibraryInput::new(
+        "C:/mc/libraries/org/lwjgl/lwjgl-vulkan/3.4.3/lwjgl-vulkan-3.4.3.jar",
+        "org.lwjgl:lwjgl-vulkan:3.4.3",
+    )];
+
+    for (game_version, expected) in [(Some("26w14a"), true), (None, false)] {
+        let snapshot = SnapshotInput {
+            game_version,
+            libraries: &libraries,
+            primary_jar: PathBuf::from("C:/mc/versions/x/x.jar"),
+            ..SnapshotInput::minimal(version_id, "net.minecraft.client.main.Main")
+        };
+        let options = AdapterOptions {
+            // `assemble` 要求 Java 可执行文件非空（`EmptyJavaPath`）；adapter 默认是空路径，
+            // 所以这里显式给一个（原来这条用例从没被执行过，r4 把它提到模块层才暴露出来）。
+            java: JavaSelection::new("C:/java/bin/java.exe", 21, 64),
+            check_classpath: false,
+            language: "zh-CN".to_string(),
+            ..AdapterOptions::default()
+        };
+        let mut out = build_request(&snapshot, options).request;
+        let resolved = resolve(
+            Some(&LaunchOverrides {
+                graphics_backend: Some(GraphicsBackend::Vulkan),
+                ..LaunchOverrides::default()
+            }),
+            &GlobalLaunchDefaults::default(),
+        );
+        apply(&mut out, &resolved);
+        let command = assemble(&out, &ctx()).expect("组装应成功");
+        let sent = command.args.iter().any(|arg| arg == "--graphicsBackend");
+        assert_eq!(
+            sent, expected,
+            "game_version={game_version:?} 时是否下发不对：{:?}",
+            command.args
+        );
+        let skipped = command
+            .warnings
+            .iter()
+            .any(|warning| matches!(warning, AssemblyWarning::GraphicsBackendSkipped { .. }));
+        assert_eq!(skipped, !expected, "跳过与否必须与下发相反（不静默）");
+    }
+}
diff --git a/crates/core/src/launch/placeholders.rs b/crates/core/src/launch/placeholders.rs
new file mode 100644
index 0000000..481ef24
--- /dev/null
+++ b/crates/core/src/launch/placeholders.rs
@@ -0,0 +1,339 @@
+//! 参数占位符字典与替换。
+//!
+//! 占位符清单平移自 `analyse/02` §4.8（`DefaultLauncher.getConfigurations()`）：
+//! 版本清单里的 `arguments.*` 用 `${...}` 引用运行时值，启动器负责在组装时替换。
+//! 替换语义与 HMCL 一致：**单遍、不递归**。
+//!
+//! ## 未登记占位符：原样保留，但不再静默（M244）
+//!
+//! 未登记键（第三方清单里自造的 `${xxx}`）**仍然原样写进 argv**——第三方清单的兼容性优先，
+//! 悄悄改写别人给的命令行比留着 `${xxx}` 危险得多。但「静默」是另一回事：argv、
+//! `--dry-run` 与会话 JSONL 里只有一个 `${xxx}`，没有任何解释。所以渲染时会把这些键收集起来：
+//!
+//! - [`PlaceholderMap::render`] 每个键每次启动只往 `launcher.log` 记一行
+//!   （[`crate::launch::launcher_log`] 是 `crates/core` 里唯一 GUI 与 CLI 都写、且事故之后
+//!   还能翻的落点，见该模块文档）；
+//! - [`PlaceholderMap::render_tracked`] / [`PlaceholderMap::unknown_keys`] 把同一份清单
+//!   **结构化**交出来，给后续接 `AssemblyWarning` / `--dry-run` 留好接口。
+//!
+//! 键的匹配是**精确字节相等**：`${Version_Name}`、`${ version_name }` 与 `${version_name}`
+//! 是三个不同的键（替换本身就不认它们，合并只会掩盖「这个串没被替换」这个事实）。日志行里
+//! 会提示大小写/空白近似的那一个，方便定位笔误。
+
+use std::collections::BTreeMap;
+use std::path::Path;
+use std::sync::{Mutex, MutexGuard};
+
+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, PartialEq, Eq)]
+pub struct RenderOutcome {
+    /// 替换后的参数串（未登记键原样保留）。
+    pub text: String,
+    /// 本次渲染遇到的未登记键（不含 `${}`）；按首次出现顺序去重。
+    pub unknown_keys: Vec,
+}
+
+impl RenderOutcome {
+    /// 记一个未登记键（已记过的不重复记）。
+    fn note_unknown(&mut self, key: &str) {
+        if self.unknown_keys.iter().any(|known| known == key) {
+            return;
+        }
+        self.unknown_keys.push(key.to_string());
+    }
+}
+
+/// 占位符表。
+///
+/// 除了键值对，还记着「渲染时见过哪些未登记键」（去重保序，[`Self::unknown_keys`] 交出）。
+/// 这份记录是**附加物**：它不参与替换，也不改变替换结果。
+#[derive(Debug, Default)]
+pub struct PlaceholderMap {
+    entries: BTreeMap,
+    reported: Mutex>,
+}
+
+impl Clone for PlaceholderMap {
+    fn clone(&self) -> Self {
+        Self {
+            entries: self.entries.clone(),
+            reported: Mutex::new(self.reported_keys()),
+        }
+    }
+}
+
+impl PlaceholderMap {
+    /// 空表。
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// 插入一个占位符（键不含 `${}`）。
+    pub fn insert(&mut self, key: &str, value: impl Into) {
+        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()
+    }
+
+    /// 到目前为止渲染时遇到的未登记键（去重、保序）。
+    ///
+    /// 这是给「结构化交出口」用的：接 `AssemblyWarning` / `--dry-run` 时读这份清单即可，
+    /// 不必再解析 `launcher.log`。
+    pub fn unknown_keys(&self) -> Vec {
+        self.reported_keys()
+    }
+
+    /// 单遍替换 `${key}`；未登记键原样保留，并记一行 `launcher.log`（每个键只记一次）。
+    ///
+    /// 需要同一份结果的**结构化**形式（未登记键清单）时用 [`Self::render_tracked`]。
+    pub fn render(&self, template: &str) -> String {
+        let outcome = self.render_tracked(template);
+        self.report(&outcome.unknown_keys);
+        outcome.text
+    }
+
+    /// 单遍替换 `${key}`，并把本次遇到的未登记键一并交出（本方法**不**写日志）。
+    pub fn render_tracked(&self, template: &str) -> RenderOutcome {
+        let mut outcome = RenderOutcome {
+            text: String::new(),
+            unknown_keys: Vec::new(),
+        };
+        if !template.contains("${") {
+            outcome.text.push_str(template);
+            return outcome;
+        }
+        outcome.text.reserve(template.len() + 16);
+        let mut rest = template;
+        while let Some(start) = rest.find("${") {
+            outcome.text.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) => outcome.text.push_str(value),
+                        None => {
+                            outcome.text.push_str("${");
+                            outcome.text.push_str(key);
+                            outcome.text.push('}');
+                            outcome.note_unknown(key);
+                        }
+                    }
+                    rest = &after[end + 1..];
+                }
+                None => {
+                    outcome.text.push_str(&rest[start..]);
+                    rest = "";
+                }
+            }
+        }
+        outcome.text.push_str(rest);
+        outcome
+    }
+
+    /// 登记本次遇到的未登记键，只把**新**见到的那些写进日志。
+    fn report(&self, unknown: &[String]) {
+        self.report_with(unknown, emit);
+    }
+
+    /// [`Self::report`] 的可注入版本：`sink` 拿到的是「本次**新**见到的键」（去重、保序）。
+    ///
+    /// 留这道缝只为一件事：让「哪些键真的交给了日志」有自动化证据（用例用假 sink 断言），
+    /// 而不是只能靠读代码——进程级的 `launcher_log` 在 lib 测试里动不得（见 [`emit`] 的注释）。
+    fn report_with(&self, unknown: &[String], mut sink: impl FnMut(&str)) {
+        let fresh = {
+            let mut seen = self.seen();
+            collect_fresh(&mut seen, unknown)
+        };
+        for key in &fresh {
+            sink(key);
+        }
+    }
+
+    fn seen(&self) -> MutexGuard<'_, Vec> {
+        self.reported
+            .lock()
+            .unwrap_or_else(|poison| poison.into_inner())
+    }
+
+    fn reported_keys(&self) -> Vec {
+        self.seen().clone()
+    }
+
+    /// 由启动请求构造完整占位符表。
+    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
+    }
+}
+
+/// 把 `keys` 登记进 `seen`，返回本次**新**见到的那些（保序；两边都按字节相等去重）。
+fn collect_fresh(seen: &mut Vec, keys: &[String]) -> Vec {
+    let mut fresh = Vec::new();
+    for key in keys {
+        if seen.iter().any(|known| known == key) {
+            continue;
+        }
+        seen.push(key.clone());
+        fresh.push(key.clone());
+    }
+    fresh
+}
+
+/// 未登记键的 `launcher.log` 行（scope 与时间戳由 `launcher_log` 加）。
+///
+/// 键名先做换行消毒：`launcher.log` 是**行导向**的，第三方清单完全可以在 JSON 里塞
+/// `${evil\n2026-… [launch] 伪造行}`，把一个键变成两行假日志。这里换成一个空格。
+fn unknown_log_line(key: &str) -> String {
+    let key = key.replace(['\r', '\n'], " ");
+    match near_miss(&key) {
+        Some(known) => format!(
+            "占位符 ${{{key}}} 未登记：已按原样保留；疑似 ${{{known}}} 的笔误\
+             （替换是精确匹配，大小写/空白都算不同的键）"
+        ),
+        None => format!("占位符 ${{{key}}} 未登记：已按原样保留（第三方版本清单常带自有占位符）"),
+    }
+}
+
+/// 大小写/首尾空白不同、但确实登记了的那个键（只用于日志提示，不参与替换与去重）。
+///
+/// 候选集用 [`PLACEHOLDER_KEYS`] 而不是 `self.entries`：`from_request` 登记的就是这 26 个
+/// （`crates/core/tests/launch/cmdline_snapshot.rs` 的 `placeholder_table_is_complete` 守这条），
+/// 而本函数是纯函数，拿不到表。
+fn near_miss(key: &str) -> Option<&'static str> {
+    let trimmed = key.trim();
+    if trimmed.is_empty() {
+        return None;
+    }
+    PLACEHOLDER_KEYS
+        .iter()
+        .copied()
+        .find(|known| known.eq_ignore_ascii_case(trimmed))
+}
+
+/// 把一行「未登记占位符」写进 `launcher.log`。
+///
+/// 测试构建里是空实现：`launcher_log` 是**进程级单例**（目录 + 200 行缓冲），lib 的几百条
+/// 用例在同一个进程里并行跑，本模块记的几行会落进 `launcher_log` 自己
+/// `buffer_is_bounded_before_the_dir_is_known` 的窗口里（实测：`缓冲没有上限：205 行`）。
+/// 让每个用例都去抢那个单例，等于把 flake 转嫁给别人。三段各有自动化证据：行文本
+/// [`unknown_log_line`]、「哪些键算新」[`collect_fresh`]、「新键怎么交给 sink」
+/// [`PlaceholderMap::report_with`]（用例用假 sink 断言）；只剩最后一句
+/// `launcher_log::record` 由 `M244` 的一次性探针（`--test-threads=1`，跑完即删）手工验过。
+#[cfg(not(test))]
+fn emit(key: &str) {
+    crate::launch::launcher_log::record("launch", &unknown_log_line(key));
+}
+
+/// 见上面非测试版本（测试里刻意不碰进程级日志单例）。
+#[cfg(test)]
+fn emit(_key: &str) {}
+
+/// 按平台分隔符拼接 classpath。
+pub fn join_classpath(paths: &[std::path::PathBuf], separator: char) -> String {
+    paths
+        .iter()
+        .map(|path| path.display().to_string())
+        .collect::>()
+        .join(&separator.to_string())
+}
+
+fn path_str(path: &Path) -> String {
+    path.display().to_string()
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/core/src/launch/placeholders/tests.rs b/crates/core/src/launch/placeholders/tests.rs
new file mode 100644
index 0000000..7d34bd7
--- /dev/null
+++ b/crates/core/src/launch/placeholders/tests.rs
@@ -0,0 +1,185 @@
+//! 未登记占位符的可观测性（M244 PLACEHOLDERWARN）。
+//!
+//! 判据四条：① 已登记键仍正常替换；② 未登记键原样保留且被收集到；③ 同一 key 只报一次；
+//! ④ 大小写/空白变体按「不同的键」处理，但日志行给出笔误提示。
+//!
+//! 日志落盘那一环（`launcher_log::record`）刻意不在单元测试里断言：它是**进程全局**单例
+//! （`launcher_log` 自己的用例要排他地改目录），在并行跑的 lib 测试里抢它是给别人制造
+//! flake——实测过一次：本模块的几行把 `launcher_log` 的 `缓冲没有上限：205 行` 顶红了。
+//! 所以 [`emit`](super::emit) 在测试构建里是空实现，落盘那一环用一次性探针
+//! （`--test-threads=1`，跑完即删）手工验过。这里断言的是它的上游——行文本
+//! （[`unknown_log_line`]）、「哪些键算新」（[`collect_fresh`]）、「新键怎么交给 sink」
+//! （[`PlaceholderMap::report_with`]，用假 sink）——三段合起来就是「记什么、记几次」。
+
+use super::{collect_fresh, near_miss, unknown_log_line, PlaceholderMap};
+use crate::launch::command_builder::CommandBuilder;
+
+fn strings(items: &[&str]) -> Vec {
+    items.iter().map(|item| (*item).to_string()).collect()
+}
+
+fn map_with_version() -> PlaceholderMap {
+    let mut map = PlaceholderMap::new();
+    map.insert("version_name", "1.20.1");
+    map.insert("natives_directory", "C:/mc/natives");
+    map
+}
+
+/// ① 正例：已登记键照旧替换（嵌入串里也一样）。
+#[test]
+fn registered_keys_are_still_substituted() {
+    let map = map_with_version();
+    let outcome = map.render_tracked("--version ${version_name} -Dnatives=${natives_directory}");
+    assert_eq!(outcome.text, "--version 1.20.1 -Dnatives=C:/mc/natives");
+    assert!(outcome.unknown_keys.is_empty(), "{outcome:?}");
+    assert_eq!(map.render("a${version_name}b"), "a1.20.1b");
+}
+
+/// ② 未登记键原样保留，并且**被收集到**（这条是新增断言：改回空实现就红）。
+#[test]
+fn unknown_keys_are_kept_verbatim_and_collected() {
+    let map = map_with_version();
+    let outcome = map.render_tracked("--feature ${third_party_flag} ${version_name}");
+    assert_eq!(
+        outcome.text, "--feature ${third_party_flag} 1.20.1",
+        "未登记键必须原样保留"
+    );
+    assert_eq!(outcome.unknown_keys, strings(&["third_party_flag"]));
+    // 走 `render` 的那条路也会把它记进表里。
+    assert_eq!(map.render("${third_party_flag}"), "${third_party_flag}");
+    assert_eq!(map.unknown_keys(), strings(&["third_party_flag"]));
+}
+
+/// ② 的 argv 侧：组装出来的参数串里 `${}` 一个字节都不变（第三方清单兼容性优先）。
+#[test]
+fn command_builder_keeps_unknown_placeholders_in_argv() {
+    let mut builder = CommandBuilder::with_placeholders(map_with_version());
+    builder.add("--version");
+    builder.add("${version_name}");
+    builder.add("${third_party_flag}");
+    assert_eq!(
+        builder.args(),
+        &strings(&["--version", "1.20.1", "${third_party_flag}"])
+    );
+    assert_eq!(
+        builder.placeholders().unknown_keys(),
+        strings(&["third_party_flag"])
+    );
+}
+
+/// ③ 同一 key 只报一次：一次渲染内去重、跨渲染也只在「新见到」时才写日志。
+#[test]
+fn the_same_key_is_reported_once() {
+    let map = PlaceholderMap::new();
+    let outcome = map.render_tracked("${b}${a}${b}${a}");
+    assert_eq!(outcome.text, "${b}${a}${b}${a}");
+    assert_eq!(outcome.unknown_keys, strings(&["b", "a"]), "保序 + 去重");
+
+    // 表级累计：连着渲染两次，清单里还是这两个。
+    let map = PlaceholderMap::new();
+    assert_eq!(map.render("${b}${a}"), "${b}${a}");
+    assert_eq!(map.render("${a}${b}${c}"), "${a}${b}${c}");
+    assert_eq!(map.unknown_keys(), strings(&["b", "a", "c"]));
+
+    // 写日志的那一步：`report` 只把新键交给 `emit`（测试构建里它不碰全局日志）。
+    let mut seen = Vec::new();
+    assert_eq!(
+        collect_fresh(&mut seen, &strings(&["a", "a"])),
+        strings(&["a"])
+    );
+    assert!(collect_fresh(&mut seen, &strings(&["a"])).is_empty());
+    assert_eq!(
+        collect_fresh(&mut seen, &strings(&["b", "a"])),
+        strings(&["b"])
+    );
+}
+
+/// ④ 大小写/空白变体算**不同的键**（替换是精确匹配，合并会掩盖「这个串没被替换」），
+/// 但日志行把近似的那一个点出来，方便定位笔误。
+#[test]
+fn case_and_whitespace_variants_are_distinct_keys_with_a_hint() {
+    let map = map_with_version();
+    let outcome = map.render_tracked("${version_name}|${Version_Name}|${version_name }");
+    assert_eq!(
+        outcome.text, "1.20.1|${Version_Name}|${version_name }",
+        "变体没被替换 ⇒ 必须原样保留（不能悄悄合并成已登记键）"
+    );
+    assert_eq!(
+        outcome.unknown_keys,
+        strings(&["Version_Name", "version_name "]),
+        "变体是各自独立的键"
+    );
+    assert_eq!(near_miss("Version_Name"), Some("version_name"));
+    assert_eq!(near_miss(" version_name "), Some("version_name"));
+    assert_eq!(near_miss("third_party_flag"), None);
+
+    let hinted = unknown_log_line("Version_Name");
+    assert!(hinted.contains("${Version_Name}"), "{hinted}");
+    assert!(hinted.contains("${version_name}"), "{hinted}");
+    let plain = unknown_log_line("third_party_flag");
+    assert!(plain.contains("${third_party_flag}"), "{plain}");
+    assert!(!plain.contains("笔误"), "{plain}");
+}
+
+/// 替换语义没被顺手改掉的边角：不闭合的 `${` 原样留、单遍不递归。
+#[test]
+fn rendering_semantics_are_unchanged() {
+    let mut map = PlaceholderMap::new();
+    map.insert("a", "${b}");
+    map.insert("b", "boom");
+    assert_eq!(map.render("${a}"), "${b}", "单遍、不递归");
+    assert_eq!(map.render("tail ${"), "tail ${");
+    assert_eq!(map.render("no placeholders"), "no placeholders");
+    assert_eq!(
+        PlaceholderMap::new().render_tracked("${}").unknown_keys,
+        strings(&[""]),
+        "空键也是未登记键（原样保留）"
+    );
+}
+
+/// ③ 的「真的交给了日志」这一层：`report_with` 只把**本次新**见到的键递给你的 sink。
+///
+/// 变异证明：把 `report_with` 里的 `for key in &fresh` 换成 `for key in unknown`（每次渲染都
+/// 重复写日志）⇒ 本条红（`left: ["a", "a", …]`）——「一个键只报一次、不刷屏」被守住的地方
+/// 就在这里，而不是在 `collect_fresh` 的用例里。
+#[test]
+fn report_emits_only_fresh_keys() {
+    let map = PlaceholderMap::new();
+    let mut delivered: Vec = Vec::new();
+    map.report_with(&strings(&["a", "a"]), |key| delivered.push(key.to_string()));
+    assert_eq!(delivered, strings(&["a"]), "一次渲染内的重复只交一次");
+    map.report_with(&strings(&["a", "b"]), |key| delivered.push(key.to_string()));
+    assert_eq!(
+        delivered,
+        strings(&["a", "b"]),
+        "跨渲染只有新键才交，且保序"
+    );
+    assert_eq!(
+        map.unknown_keys(),
+        strings(&["a", "b"]),
+        "表级清单与 sink 同一份"
+    );
+
+    // 顺序口径与 `collect_fresh` 一致（同一份规则的两处实现不能漂）。
+    let mut fresh_seen = Vec::new();
+    assert_eq!(
+        collect_fresh(&mut fresh_seen, &strings(&["a", "a"])),
+        strings(&["a"])
+    );
+    assert_eq!(
+        collect_fresh(&mut fresh_seen, &strings(&["a", "b"])),
+        strings(&["b"])
+    );
+}
+
+/// 日志是**行导向**的：恶意/畸形清单可以在 JSON 里塞换行，一个键不能变成两行假日志。
+#[test]
+fn log_lines_never_break_into_two_lines() {
+    let line = unknown_log_line("evil\n2026-01-01T00:00:00Z [launch] 伪造行\r");
+    assert_eq!(line.lines().count(), 1, "{line}");
+    assert!(!line.contains('\n') && !line.contains('\r'), "{line}");
+    assert!(
+        line.contains("evil 2026-01-01T00:00:00Z [launch] 伪造行"),
+        "{line}"
+    );
+}
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,
+    /// 系统版本串（`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) -> 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 {
+    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..29f3f1e
--- /dev/null
+++ b/crates/core/src/launch/process.rs
@@ -0,0 +1,317 @@
+//! 进程管理：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);
+/// 轮询进程状态的间隔（有界等待也用这个）。
+pub const POLL_INTERVAL: Duration = Duration::from_millis(20);
+
+/// 默认启动预算：spawn 后**连续这么久既没有日志输出、也没见到游戏窗口**就停止等待（D6）。
+///
+/// 判据是「静默」不是「等了多久」：还在打日志说明它还在加载（大整合包首次启动三分钟以上
+/// 是常态，那期间日志一直在刷），所以这里按「一声不响」计量，宁松不紧。
+pub const DEFAULT_STARTUP_TIMEOUT: Duration = Duration::from_secs(300);
+/// 默认关闭宽限：日志里出现关闭标记后这么久还没退出，就认为卡在关闭（D6）。
+pub const DEFAULT_SHUTDOWN_GRACE: Duration = Duration::from_secs(60);
+/// 覆盖启动预算的环境变量（单位秒，`0` = 不限）。
+pub const STARTUP_TIMEOUT_ENV: &str = "ULL_LAUNCH_STARTUP_TIMEOUT_SECS";
+/// 覆盖关闭宽限的环境变量（单位秒，`0` = 不限）。
+pub const SHUTDOWN_GRACE_ENV: &str = "ULL_LAUNCH_SHUTDOWN_GRACE_SECS";
+
+/// 进程管理配置。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct ProcessConfig {
+    /// 日志泵等待预算。
+    pub watchdog: WatchdogConfig,
+    /// 停止时温和关闭的宽限期。
+    pub graceful_stop: Duration,
+    /// 环形缓冲配置。
+    pub buffer: RingBufferConfig,
+    /// 未见游戏窗口的**静默**预算（D6；`0` = 不判）。
+    ///
+    /// 判据是「连续这么久没有任何日志输出、也没见到窗口」——还在打日志就不算卡死，
+    /// 大整合包慢慢加载不会被判进来。
+    pub startup_timeout: Duration,
+    /// 出现关闭标记后仍不退出的宽限（D6；`0` = 不判）。
+    pub shutdown_grace: Duration,
+}
+
+impl Default for ProcessConfig {
+    fn default() -> Self {
+        Self {
+            watchdog: WatchdogConfig::default(),
+            graceful_stop: Duration::from_secs(3),
+            buffer: RingBufferConfig::default(),
+            startup_timeout: DEFAULT_STARTUP_TIMEOUT,
+            shutdown_grace: DEFAULT_SHUTDOWN_GRACE,
+        }
+    }
+}
+
+impl ProcessConfig {
+    /// 按环境变量覆盖两个看门狗时长（D6 的「可配」出口；不设就等于默认值）。
+    ///
+    /// 放在这里而不是 `default()`：默认值必须是纯的（测试与嵌入方都吃它），
+    /// 环境变量只在宿主明确要求时生效（CLI 的 `LauncherConfig::with_watchdog_env`）。
+    #[must_use]
+    pub fn with_env_overrides(mut self) -> Self {
+        if let Some(value) = env_seconds(STARTUP_TIMEOUT_ENV) {
+            self.startup_timeout = value;
+        }
+        if let Some(value) = env_seconds(SHUTDOWN_GRACE_ENV) {
+            self.shutdown_grace = value;
+        }
+        self
+    }
+}
+
+/// 读一个「秒数」环境变量（空值/非数字/溢出都当没设）。
+fn env_seconds(name: &str) -> Option {
+    parse_seconds(&std::env::var(name).ok()?)
+}
+
+/// 解析秒数（`"120"` → 120s，`"0"` → 0s = 关闭该判据；其余一律 `None`）。
+fn parse_seconds(raw: &str) -> Option {
+    let trimmed = raw.trim();
+    if trimmed.is_empty() {
+        return None;
+    }
+    trimmed.parse::().ok().map(Duration::from_secs)
+}
+
+/// 已启动的游戏进程。
+#[derive(Debug)]
+pub struct RunningProcess {
+    child: Child,
+    pump: PumpGroup,
+    buffer: Arc>,
+    started_at: Instant,
+    pid: u32,
+    config: ProcessConfig,
+}
+
+impl RunningProcess {
+    /// 启动进程并接管两条输出流。
+    pub fn spawn(
+        command: &AssembledCommand,
+        working_dir: Option<&Path>,
+        sink: Arc,
+        config: ProcessConfig,
+    ) -> Result {
+        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 -- -` 才能覆盖整棵子树。`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> {
+        self.buffer.clone()
+    }
+
+    /// 当前可读日志快照。
+    pub fn lines(&self) -> Vec {
+        match self.buffer.lock() {
+            Ok(guard) => guard.lines().cloned().collect(),
+            Err(_) => Vec::new(),
+        }
+    }
+
+    /// 等待进程退出（不等待日志泵）。
+    pub fn wait(&mut self) -> Result {
+        self.child.wait().map_err(|source| LaunchError::Io {
+            op: "wait_child",
+            path: PathBuf::from(self.pid.to_string()),
+            source,
+        })
+    }
+
+    /// 非阻塞取退出状态（`None` = 还在跑）。有界等待（D6）靠它轮询。
+    pub fn try_wait(&mut self) -> Result> {
+        self.child.try_wait().map_err(|source| LaunchError::Io {
+            op: "try_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
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{parse_seconds, ProcessConfig, DEFAULT_SHUTDOWN_GRACE, DEFAULT_STARTUP_TIMEOUT};
+    use std::time::Duration;
+
+    #[test]
+    fn defaults_are_real_values_not_disabled() {
+        let config = ProcessConfig::default();
+        assert_eq!(config.startup_timeout, DEFAULT_STARTUP_TIMEOUT);
+        assert_eq!(config.shutdown_grace, DEFAULT_SHUTDOWN_GRACE);
+        assert!(!config.startup_timeout.is_zero(), "默认值不能等于关掉");
+        assert!(!config.shutdown_grace.is_zero());
+    }
+
+    #[test]
+    fn seconds_parser_accepts_plain_numbers_and_zero() {
+        assert_eq!(parse_seconds("120"), Some(Duration::from_secs(120)));
+        assert_eq!(parse_seconds(" 45 "), Some(Duration::from_secs(45)));
+        assert_eq!(parse_seconds("0"), Some(Duration::ZERO));
+        assert_eq!(parse_seconds(""), None);
+        assert_eq!(parse_seconds("abc"), None);
+        assert_eq!(parse_seconds("-5"), None);
+    }
+}
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) -> 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,
+    retained: Vec,
+    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 {
+        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,
+}
+
+/// 一次等待 PumpGroup 的结果。
+#[derive(Debug, Clone, Default)]
+pub struct PumpCompletion {
+    /// 已结束的流。
+    pub finished: Vec,
+    /// 超时仍未结束的流。
+    pub stalled: Vec,
+}
+
+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>,
+    receiver: Receiver,
+    streams: Vec,
+    completed: Vec,
+}
+
+impl PumpGroup {
+    /// 为子进程的输出流派生泵线程。
+    ///
+    /// `buffer` 与 `sink` 同时被两个泵线程共享：缓冲区用于“最后 N 行”，
+    /// sink 用于事件流落盘。
+    pub fn spawn(
+        stdout: Option,
+        stderr: Option,
+        buffer: Arc>,
+        sink: Arc,
+    ) -> 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;
+
+fn spawn_one(
+    reader: BoxedReader,
+    stream: Stream,
+    buffer: Arc>,
+    sink: Arc,
+    sender: Sender,
+) -> 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..565caba
--- /dev/null
+++ b/crates/core/src/launch/redact.rs
@@ -0,0 +1,309 @@
+//! 日志与事件流的脱敏（写入前执行，落盘即脱敏）。
+//!
+//! 规则见 `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 错误摘要 …）共用，避免各自补一套后漂移。
+//!
+//! 形状判据本身在 [`shape`]，本模块只做「扫描 + 搬运」：把文本切成连续段，
+//! 逐段问一次判据，命中就换成占位符。
+//!
+//! # 判据只砍「真凭据不可能有的形状」（M240）
+//!
+//! 两条形状规则都是纯启发式，M239 实测它们会误杀三类正常文本（品牌串、CDN 主机名、长路径），
+//! 而这三类被抹掉的面正是用户要复制/要读的面（`--dry-run` 的 argv、诊断规则的输入）。
+//! 修法不是抬阈值，而是给每条规则加**必要条件**（详见 [`shape`] 的表）：
+//!
+//! - `=` 不算 token 字符（赋值边界）：`-D=<品牌>` 不再被当成三段式 token；
+//! - 带点 token 必须含大写字母、且首段不是主机名（JWT 头的 base64url 第三个字符恒为
+//!   `I/J/K/L`，且 base64url 不含 `/`）；
+//! - ≥64 的不透明串若是「路径形状」（被 `/` 切开且每段都是词形名字）就整条保留，
+//!   但**段本身**仍够长的照抹（`/…/objects/<64 位 hex>` 里只有那段消失）。
+//!
+//! **口径（别读成"抹除能力没有下降"）**：登记过明文值的那条替换路径没动，JWT / sha256 /
+//! base64 的正例全部仍被抹；但有三类形状是「旧行为抹、新行为留」——`=` 边界、填充不计段长、
+//! 全小写点分串。三条都在 [`shape`] 的「旧行为抹、新行为留」一节里逐条写明理由，
+//! 前两条是本次要修的误杀，第三条是代价。
+//!
+//! # 句读不是 token 本体（M243 BEARERDOT）
+//!
+//! `Bearer eyJ….eyJ….c2ln….`（行尾一个英文句点）在 M240 之后仍整串原样落盘：句点自己属于
+//! dotted 字符集，被算进 run 后 `split('.')` 多切出一个空段，「每段 ≥8」当场不成立。修法同样
+//! 不是抬阈值——判定前把**末尾**句读切出去（[`shape::split_trailing_punct`]），搬运方
+//! （[`push_dotted`]）再把句读原位写回，所以占位符只吃 token 本体，句子标点一个不丢。
+//! 只削末尾：中间的句点仍是 token 的一部分（JWT 的三段就是靠它切的）；`(`、`)`、`,`、`;`
+//! 本来就在字符集外，一并列进规则是为了「句读不参与判定」这件事只有一个出处。
+
+use std::borrow::Cow;
+use std::path::Path;
+
+use serde_json::Value;
+
+mod shape;
+
+use self::shape::{
+    is_dns_host, is_dotted_token, is_dotted_token_char, is_opaque_char, is_path_run,
+    split_trailing_punct, MAX_OPAQUE_RUN,
+};
+
+/// access token / session token 的替换标记。
+pub const TOKEN_PLACEHOLDER: &str = "";
+/// 用户主目录的替换标记。
+pub const HOME_PLACEHOLDER: &str = "";
+/// 形似 token 的长不透明串的替换标记。
+pub const OPAQUE_PLACEHOLDER: &str = "";
+
+/// 脱敏器：持有需要抹掉的敏感值（token、主目录）。
+#[derive(Debug, Clone, Default)]
+pub struct Redactor {
+    secrets: Vec,
+    homes: Vec,
+}
+
+impl Redactor {
+    /// 空脱敏器（不做任何替换）。
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// 登记一个敏感值（access token、userhash、xuid 等）。
+    ///
+    /// 太短的值（< 6 字节）会被忽略：替换一个 3 字符串会把正常日志搅乱。
+    pub fn with_secret(mut self, secret: impl Into) -> Self {
+        let secret = secret.into();
+        if secret.trim().len() >= 6 && !self.secrets.contains(&secret) {
+            self.secrets.push(secret);
+        }
+        self
+    }
+
+    /// 登记一个需要抹掉的主目录（替换成 ``）。
+    pub fn with_home(mut self, home: impl AsRef) -> 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) -> 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(¤t) {
+            current = Cow::Owned(mask_dotted_tokens(¤t));
+        }
+        if has_opaque_run(¤t) {
+            current = Cow::Owned(mask_opaque(¤t));
+        }
+        current
+    }
+
+    /// 对整条命令行脱敏（`cmd_built.argv` 必然含 accessToken，必须走这里）。
+    pub fn scrub_all(&self, values: &[String]) -> Vec {
+        values
+            .iter()
+            .map(|value| self.scrub(value).into_owned())
+            .collect()
+    }
+
+    /// 递归脱敏一个 JSON 值。
+    ///
+    /// **只改字符串**：数值/布尔/null 与字段名原样保留——满足「launch 只做脱敏、不改写字段」
+    /// 的契约（`DevDocs/SubAgentsTalk/launch-接口约定.md` §9.3）。诊断结论里的证据行常带
+    /// 崩溃报告/`hs_err` 的绝对路径，正是要过 `` 规则的地方。
+    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 start: Option = None;
+    for (idx, ch) in text.char_indices() {
+        if is_opaque_char(ch) {
+            start.get_or_insert(idx);
+            continue;
+        }
+        if let Some(from) = start.take() {
+            if run_needs_masking(&text[from..idx]) {
+                return true;
+            }
+        }
+    }
+    start.is_some_and(|from| run_needs_masking(&text[from..]))
+}
+
+/// 这一段不透明连续串要不要动手：够长，且（不是路径 或 路径里某一段自己就够长）。
+fn run_needs_masking(run: &str) -> bool {
+    run.len() >= MAX_OPAQUE_RUN
+        && (!is_path_run(run) || run.split('/').any(|chunk| chunk.len() >= MAX_OPAQUE_RUN))
+}
+
+/// 把长度 ≥64 的不透明串替换成 [`OPAQUE_PLACEHOLDER`]（路径形状的串见 [`push_path_masked`]）。
+pub fn mask_opaque(text: &str) -> String {
+    let mut out = String::with_capacity(text.len());
+    let mut run_start: Option = 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_needs_masking(run) {
+        out.push_str(run);
+    } else if is_path_run(run) {
+        push_path_masked(out, run);
+    } else {
+        out.push_str(OPAQUE_PLACEHOLDER);
+    }
+}
+
+/// 路径整条保留，但**段本身**够长的照抹。
+///
+/// 路径判据放行的是"目录/包名段"，不许顺手放行一整段凭据：`/srv/mc/assets/objects/<64 位 hex>`
+/// 里的目录留下，那个 64 字符的段照样变成占位符（它与无点号密钥在形状上不可区分）。
+fn push_path_masked(out: &mut String, run: &str) {
+    for (idx, chunk) in run.split('/').enumerate() {
+        if idx > 0 {
+            out.push('/');
+        }
+        if chunk.len() >= MAX_OPAQUE_RUN {
+            out.push_str(OPAQUE_PLACEHOLDER);
+        } else {
+            out.push_str(chunk);
+        }
+    }
+}
+
+/// 文本里是否含「带点 token」。
+pub fn has_dotted_token(text: &str) -> bool {
+    let mut start: Option = 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 run_has_dotted_token(&text[from..idx]) {
+                return true;
+            }
+        }
+    }
+    start.is_some_and(|from| run_has_dotted_token(&text[from..]))
+}
+
+/// 一段里有没有该抹的部分：URL 形状只判**路径那一半**，主机名放行。
+fn run_has_dotted_token(run: &str) -> bool {
+    match split_authority(run) {
+        Some((_, rest)) => run_has_dotted_token(rest),
+        None => is_dotted_token(split_trailing_punct(run).0),
+    }
+}
+
+/// 把「带点 token」整串替换成 [`TOKEN_PLACEHOLDER`]（段外文本原样保留）。
+pub fn mask_dotted_tokens(text: &str) -> String {
+    let mut out = String::with_capacity(text.len());
+    let mut start: Option = 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) {
+    // URL 形状先切：主机名原样留下，路径那半继续判——JWT 摆在 URL 路径里也照抹。
+    if let Some((prefix, rest)) = split_authority(run) {
+        out.push_str(prefix);
+        out.push('/');
+        push_dotted(out, rest);
+        return;
+    }
+    // 句读不参与判定，但要原位保留：`Bearer .` 的句点不许被占位符吃掉。
+    let (body, punct) = split_trailing_punct(run);
+    if is_dotted_token(body) {
+        out.push_str(TOKEN_PLACEHOLDER);
+    } else {
+        out.push_str(body);
+    }
+    out.push_str(punct);
+}
+
+/// 把 URL 形状的 run 切成（主机名前缀, 路径那半）。路径那半不含分隔用的那个 `/`。
+///
+/// 前缀里含 scheme 之后的 `//`（`:` 会切断 run，所以 `https:` 不在 run 里）。
+/// 判据只看主机名部分是不是 DNS 形状，路径原样交回去继续判。
+fn split_authority(run: &str) -> Option<(&str, &str)> {
+    let slashes = run.len() - run.trim_start_matches('/').len();
+    let (authority, _) = run[slashes..].split_once('/')?;
+    if !is_dns_host(authority) {
+        return None;
+    }
+    let cut = slashes + authority.len();
+    Some((&run[..cut], &run[cut + 1..]))
+}
+
+#[cfg(test)]
+#[path = "redact/tests.rs"]
+mod tests;
diff --git a/crates/core/src/launch/redact/shape.rs b/crates/core/src/launch/redact/shape.rs
new file mode 100644
index 0000000..9aa4dd1
--- /dev/null
+++ b/crates/core/src/launch/redact/shape.rs
@@ -0,0 +1,201 @@
+//! 两条形状判据（`dotted` / `opaque`）的判定与阈值；[`super`] 的扫描器只负责搬运字符。
+//!
+//! 判据集中在这里一份，是因为它们是**同一件事的两面**：`dotted` 先跑、`opaque` 后跑，
+//! 两者的字符集相互补充（`.` 只属于前者，`/` 属于两者），任何一边改了字符集，另一边的
+//! 覆盖面就跟着变。
+//!
+//! # 四条"别抹"的判据（M239 的 D8 误杀）
+//!
+//! 修法是给每条规则加**必要条件**，不是抬阈值（40 / 3×8 / 64 一个字没动）：
+//!
+//! | 误杀形状 | 出口判据 | 为什么这一串不可能是真凭据 |
+//! |---|---|---|
+//! | `-D=<品牌>`（`minecraft.launcher.brand=UnluckyLauncher`） | `=` 不属于 dotted 字符集（赋值边界） | JWT 的 `.` 分段里 `=` 只可能是末尾填充，拆出去不损伤覆盖 |
+//! | CDN/镜像主机名（`resources.download.minecraft.net/ab/cdef`） | 首段是 DNS 主机名 → 只判路径那半 | JWT 是 base64url，**不含 `/`**，所以"主机名 + 路径"形状不可能是 JWT |
+//! | 目录段/类名（`/srv/…/mods/x.jar`、`org/spongepowered/…`） | 段名是"词形"（[`is_path_run`]） | 随机 base64 的一段里不可能每个连续字母块都恰好是全小写/全大写/CamelCase |
+//! | 全小写点分串（`sophisticatedbackpacks.upgrades.reference`） | ①主机名形状的走首段 DNS 豁免 ②**不是**主机名的靠"必须含大写字母"（[`jwt_shaped`]） | JWT 头是 JSON 对象，其 base64url 前三个字符恒为 `ey` + `I/J/K/L`，所以真 JWT 必含大写 |
+//!
+//! 四条里前两条是**位置/字符集**判据，后两条是**形状**判据；都写成必要条件：判据不成立时
+//! 仍然照抹，只有"这一串根本不可能是凭据"时才放行。
+//!
+//! 第五处边界（M243 BEARERDOT，同样不是抬阈值）：**末尾句读不参与判定**
+//! （[`split_trailing_punct`]）。判定前把 `.` `,` `;` `)` 切出去，搬运方原位写回——
+//! 行尾句点原先会多切出一个空段，把真 token 整串放行。只有 `.` 会进入 dotted 字符集，
+//! 其余三个本来就在外面；列全是为了「句读不参与判定」只有一处出处。
+//!
+//! 关于"必须含大写"的实际覆盖面（复审 P2-2 的怀疑成立一半）：**DNS 形状**的全小写点分串
+//! 早在首段 DNS 豁免那一条就被救下了，跟大写判据无关；大写判据唯一扛住的是**不是 DNS 形状**
+//! 的全小写点分串（标签带 `_`、标签超 63 字符、`/` 前只有一段主机名）。它保留下来，因为那类
+//! 形状同样不可能是 JWT，而且删掉它就会把误杀请回来——`the_uppercase_requirement_is_load_bearing`
+//! 就是钉这一点的用例（删掉判据 → 该测试红）。
+//!
+//! # 旧行为抹、新行为留的形状（三类，全部有测试钉住）
+//!
+//! 口径说明：**不是"抹除能力整体没有下降"**——收窄的就是下面三类，前两条是本次要修的误杀，
+//! 第三条是代价。都没有放宽长度/段数阈值，也没有动"登记过的明文值"那条替换路径。
+//!
+//! 1. **`=` 边界**：`-Dminecraft.launcher.brand=UnluckyLauncher` —— 旧行为把 `键=值` 粘成
+//!    一段，键里的点号凑够段数/总长；现在两半各自不达标。（这就是要修的品牌串误杀。）
+//!    同一处边界的**代价**：`-DaccessToken=abcdefgh.ijklmnop.qrstuvwx`（整段 40 字符、
+//!    三段各 ≥8，旧规则抹）现在 `=` 切段后值只剩 26 < 40 → 原样留下。也就是说
+//!    **紧跟 `=`、自己又不够 40 的带点值**不再被形状规则兜住，只剩"登记明文值"那条路径，
+//!    这是换品牌串保留付出的代价。
+//! 2. **填充不算段长**：`eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.c2lnbm==` ——
+//!    旧行为把 `==` 算进末段（8 ≥ 8），现在 `=` 在段外、末段实际 6 < 8，整串留下。
+//!    真 JWT 的签名段是 43+ 字符（HS256）/ 342（RS256），6–7 字符的末段只可能是被裁剪或
+//!    自造的票据；末段 ≥8 时（`…c2lnbmFy==`）仍照抹，缝合线由测试钉住。
+//! 3. **全小写点分串**：`sophisticatedbackpacks.upgrades.reference`（41 字符 / 三段各 ≥8）
+//!    —— 旧行为抹，现在放行（DNS 形状的走主机名豁免，非 DNS 形状的走"必须含大写"）。
+//!    这是**刻意的**：真 JWT 必含大写（见上表末行），而全小写点分串正是点分类路径的常见形状。
+
+/// 判定“像 token”的最短连续长度。
+pub(super) const MAX_OPAQUE_RUN: usize = 64;
+/// 「带点 token」（JWT 三段式）判定的最短总长。
+pub(super) const DOTTED_TOKEN_MIN_TOTAL: usize = 40;
+/// 「带点 token」每一段的最短长度（挡住 `Service.Unavailable.today` 这类正常文案）。
+pub(super) const DOTTED_TOKEN_MIN_SEGMENT: usize = 8;
+
+/// 不透明串的字符集（base64 / hex / 路径分隔符）。`.` 不在内，`: \ @` 也不在内。
+pub(super) fn is_opaque_char(ch: char) -> bool {
+    ch.is_ascii_alphanumeric() || matches!(ch, '+' | '/' | '=' | '_' | '-')
+}
+
+/// 「带点 token」的字符集：不透明串的字符加 `.`、减 `=`。
+///
+/// `=` 是**赋值边界**而不是 token 本体。把它留在字符集里，`-D=<值>` 就会被粘成一个
+/// run：键里的点号（`minecraft.launcher.brand`）会把值一起拖进段数统计，M239 实测的品牌串
+/// 误杀就是从这儿来的。
+///
+/// 这条边界的代价**有范围**，别读成"不损伤覆盖面"：`=` 切段之后，**紧跟 `=`、自己又不够
+/// 40 字符**的带点值不再被形状规则兜住——`-DaccessToken=abcdefgh.ijklmnop.qrstuvwx`（整段
+/// 40 字符、三段各 ≥8，旧规则抹）现在切出 26 < 40 而原样留下。这是换品牌串保留的代价，
+/// 记在模块文档「旧行为抹、新行为留」第 1 条的末句；真 token 仍由 [`super::Redactor::with_secret`]
+/// 那条明文值替换路径扛住。
+pub(super) fn is_dotted_token_char(ch: char) -> bool {
+    ch != '=' && (is_opaque_char(ch) || ch == '.')
+}
+
+/// 单段连写（无空白）的串是否像 JWT。
+pub(super) fn is_dotted_token(run: &str) -> bool {
+    jwt_shaped(run) && !is_url_authority(run)
+}
+
+/// 把 run 末尾的句读切出去：返回（判据只看的前半, 原样搬回的后半）。
+///
+/// 句读（`.` `,` `;` `)`）不属于 token 本体。`.` 是**唯一会进入** dotted 字符集的句读
+/// （见 [`is_dotted_token_char`]），所以行尾一个句点就会把 run 多切出一个空段：
+/// 「每段 ≥8」当场不成立，整串原样落盘——BEARERDOT（M243）。`(` `,` `;` 早被字符集
+/// 切在 run 外，这里一并列出，是把「句读不参与判定」写成一条规则：字符集将来若放宽，
+/// 判据不用再改一遍。
+///
+/// 只削**末尾**：中间的句点仍是 token 本体（JWT 的三段就是靠它切的）。
+/// 削短只会让形状判据更容易成立，方向在安全那一侧；搬运方负责把切出去的后半原位写回。
+pub(super) fn split_trailing_punct(run: &str) -> (&str, &str) {
+    let body = run.trim_end_matches(['.', ',', ';', ')']);
+    run.split_at(body.len())
+}
+
+/// 「带点 token」的形状：段数 ≥3、每段 ≥8 字节、总长 ≥40（老规则，一个字都没放宽），
+/// 外加两条必要条件——首段不是主机名、**含大写字母**。
+///
+/// "必须含大写"依据的是 JWT 的构造而不是概率：头的明文是 JSON 对象，以 `{"` 开头。
+/// 三个字节 `7B 22 xx` 的 base64url 前三个字符 = `e`、`y`、`I`/`J`/`K`/`L`
+/// （第三组 6 位 = `b1` 低 4 位 `0010` ++ `b2` 高 2 位 → 索引 8..11，全是大写）。
+/// 也就是说**第三个字符**必为大写，任何真 JWT 都躲不过这条。
+///
+/// 代价写在这里而不是藏起来：全小写点分串（`sophisticatedbackpacks.upgrades.reference`，
+/// 以及非 DNS 形状的 `sophisticated_backpacks.upgrades.reference`，旧行为都会抹）因此被放行，
+/// 见模块文档「旧行为抹、新行为留」第 3 条。
+fn jwt_shaped(run: &str) -> bool {
+    run.len() >= DOTTED_TOKEN_MIN_TOTAL
+        && run.split('.').count() >= 3
+        && run
+            .split('.')
+            .all(|segment| segment.len() >= DOTTED_TOKEN_MIN_SEGMENT)
+        && run.chars().any(|ch| ch.is_ascii_uppercase())
+}
+
+/// run 的第一段（到第一个 `/` 为止）是不是主机名：是的话这就是一条 URL，不是 token。
+///
+/// 扫描器（`super::push_dotted`）先按这条把主机名切走、只判路径那半；这里的判据留一份，
+/// 是为了让「一段串是不是 token」单独成立（`has_dotted_token` 与单测直接用它）。
+pub(super) fn is_url_authority(run: &str) -> bool {
+    is_dns_host(run.split('/').next().unwrap_or(run))
+}
+
+/// 整串是不是一个 DNS 主机名（至少两段标签，标签只含小写字母/数字/连字符）。
+///
+/// JWT 是 base64url，**不含 `/`**；主机名的标签也不会大写（URL 里从没这么写过）。
+pub(super) fn is_dns_host(name: &str) -> bool {
+    let labels: Vec<&str> = name.split('.').collect();
+    labels.len() >= 2 && labels.iter().all(|label| is_dns_label(label))
+}
+
+/// 单个 DNS 标签：小写字母/数字/连字符，首尾不是连字符（日志里的主机名不会写大写）。
+fn is_dns_label(label: &str) -> bool {
+    !label.is_empty()
+        && label.len() <= 63
+        && label
+            .chars()
+            .all(|ch| ch.is_ascii_lowercase() || ch.is_ascii_digit() || ch == '-')
+        && !label.starts_with('-')
+        && !label.ends_with('-')
+}
+
+/// 长不透明串是不是一段路径/命名空间（目录、文件名、Java 包名）。
+///
+/// 两条：① 至少被 `/` 切开一次；② 每一段都是"名字"（[`is_name_chunk`]）。
+/// 判据里没有任何熵估计，"词形 vs 随机"就靠第 ② 条：随机 base64 的一段里每个连续字母块
+/// 都恰好是全小写/全大写/CamelCase 的概率可以忽略——所以一条 base64 密钥不会被当成路径。
+/// 方向也是安全的：判定失败的串照旧被抹，只是路径不再整条消失。
+pub(super) fn is_path_run(run: &str) -> bool {
+    run.split('/').count() >= 2 && run.split('/').all(is_name_chunk)
+}
+
+/// 路径/包名的一段：只许字母数字与 `- _ .`，且每个连续字母块都是"词"（[`is_word`]）。
+fn is_name_chunk(chunk: &str) -> bool {
+    chunk
+        .chars()
+        .all(|ch| ch.is_ascii_alphanumeric() || matches!(ch, '-' | '_' | '.'))
+        && chunk
+            .split(|ch: char| !ch.is_ascii_alphabetic())
+            .all(is_word)
+}
+
+/// 连续字母块是否像词：全小写 / 全大写（缩写）/ CamelCase（`OpenGL`、`AllTheMods`、`FabricMixin…`）。
+fn is_word(word: &str) -> bool {
+    let mut has_lower = false;
+    let mut has_upper = false;
+    for ch in word.chars() {
+        if ch.is_ascii_lowercase() {
+            has_lower = true;
+        } else if ch.is_ascii_uppercase() {
+            has_upper = true;
+        } else {
+            return false;
+        }
+    }
+    if !has_lower || !has_upper {
+        return true;
+    }
+    let chars: Vec = word.chars().collect();
+    let mut idx = 0usize;
+    while idx < chars.len() {
+        if !chars[idx].is_ascii_uppercase() {
+            return false;
+        }
+        let mut end = idx + 1;
+        while end < chars.len() && chars[end].is_ascii_uppercase() {
+            end += 1;
+        }
+        let lowered = end < chars.len() && chars[end].is_ascii_lowercase();
+        if lowered && end - idx != 1 {
+            return false; // `ABCDef`：缩写后面接小写，不是词
+        }
+        idx = end;
+        while idx < chars.len() && chars[idx].is_ascii_lowercase() {
+            idx += 1;
+        }
+    }
+    true
+}
diff --git a/crates/core/src/launch/redact/tests.rs b/crates/core/src/launch/redact/tests.rs
new file mode 100644
index 0000000..b0d4cea
--- /dev/null
+++ b/crates/core/src/launch/redact/tests.rs
@@ -0,0 +1,364 @@
+//! `launch::redact` 的判据测试：抹得掉真凭据，抹不着正常文本。
+//!
+//! 三组：**正例**（必须抹，占位符形状固定）、**误杀**（M239 实测的形状，必须逐字原样）、
+//! **边界**（新判据最容易被拼出来的形状，以及 `has_*` / `mask_*` 两个入口的一致性）。
+//! 语料组拿 M239 的回归语料（68 文件 / 243 行）当钉死的输入，要求一行都不许改。
+//!
+//! BEARERDOT（token 后面跟句读，M243）单独一页：`tests/bearerdot.rs`。
+
+use std::path::{Path, PathBuf};
+
+use super::*;
+
+// `tests.rs` 是以 `#[path]` 挂进来的文件模块，子模块按**它所在目录**（`redact/`）解析，
+// 所以这里写全相对路径，文件仍归在 `tests/` 目录下。
+#[path = "tests/bearerdot.rs"]
+mod bearerdot;
+
+/// 真实形状的 JWT（`header.payload.signature`，三段各 ≥8）。
+const JWT: &str = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.c2lnbmF0dXJlLXZhbHVlLXRoYXQtaXMtbG9uZy1lbm91Z2g";
+/// 微软 MSA/XSTS 形状的 header（`{"typ":"JWT","alg":"none"}`）。
+const MSA: &str = "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJ4dWlkIjoiMjUzNTQyOTk4OTg4OTg5OCJ9.c2lnbmF0dXJlLXZhbHVlLXRoYXQtaXMtbG9uZw";
+/// 64 位 sha256（hex）。
+const SHA256: &str = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
+
+fn scrub(text: &str) -> String {
+    Redactor::new().scrub(text).into_owned()
+}
+
+// ───────────────────────── 正例：真凭据仍被抹 ─────────────────────────
+
+#[test]
+fn jwts_are_masked_in_every_log_shape() {
+    let cases = [
+        (JWT.to_string(), TOKEN_PLACEHOLDER.to_string()),
+        (MSA.to_string(), TOKEN_PLACEHOLDER.to_string()),
+        (
+            format!("authorization: Bearer {JWT}, retry=1"),
+            format!("authorization: Bearer {TOKEN_PLACEHOLDER}, retry=1"),
+        ),
+        // `键=` 粘在 token 前面：键留下、token 照抹（`=` 是赋值边界，不是 token 本体）
+        (
+            format!("-DaccessToken={JWT}"),
+            format!("-DaccessToken={TOKEN_PLACEHOLDER}"),
+        ),
+        (
+            format!("--accessToken {MSA} --uuid 0123"),
+            format!("--accessToken {TOKEN_PLACEHOLDER} --uuid 0123"),
+        ),
+        // 藏在 URL 路径里也照抹（只有主机名被放行）
+        (
+            format!("https://resources.download.minecraft.net/{JWT}"),
+            format!("https://resources.download.minecraft.net/{TOKEN_PLACEHOLDER}"),
+        ),
+        // 标准 base64 的三段式（带大写）：不是 URL 形状，照抹
+        (
+            "QWxsLmJhc2U2NA.QWJjZGVmZ2hpamtsbW5vcA.ZGVmaWdoaWprbG1ub3BxcnN0dXZ3eHl6".to_string(),
+            TOKEN_PLACEHOLDER.to_string(),
+        ),
+    ];
+    for (input, expected) in cases {
+        assert_eq!(scrub(&input), expected, "输入：{input}");
+    }
+}
+
+#[test]
+fn opaque_secrets_are_masked_in_every_log_shape() {
+    let cases = [
+        (format!("sha256={SHA256}"), OPAQUE_PLACEHOLDER.to_string()),
+        (SHA256.to_string(), OPAQUE_PLACEHOLDER.to_string()),
+        ("A".repeat(64), OPAQUE_PLACEHOLDER.to_string()),
+        (
+            "dGhpcyBpcyBhIHZlcnkgbG9uZyBzZWNyZXQga2V5IHRoYXQgaXMgYmFzZTY0IGVuY29kZWQ=".to_string(),
+            OPAQUE_PLACEHOLDER.to_string(),
+        ),
+        // 带 `/` 与 `+` 的普通 base64：随机大小写，不是路径形状
+        (
+            "aB3xK9mQ2pL5vN8r/W1tY4uI7oP0sD6fGhJ2kL5zX8cV1bN4mQ7wE3rT6yU9iO2pA5sD8fG1hJ"
+                .to_string(),
+            OPAQUE_PLACEHOLDER.to_string(),
+        ),
+    ];
+    for (input, expected) in cases {
+        assert_eq!(scrub(&input), expected, "输入：{input}");
+    }
+}
+
+#[test]
+fn registered_secrets_and_home_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_eq!(
+        scrubbed, "/game.log: token=",
+        "登记过的明文值走替换路径，与形状启发式无关"
+    );
+    assert!(Redactor::new().is_empty(), "空脱敏器不该登记任何规则");
+}
+
+// ───────────────────────── 误杀：必须逐字原样 ─────────────────────────
+
+/// M239 的 ①②③：品牌串 / 属性串（`=` 是赋值边界）。
+#[test]
+fn brand_and_property_strings_survive() {
+    for text in [
+        "-Dminecraft.launcher.brand=UnluckyLauncher",
+        "-Dminecraft.launcher.brand=minecraft",
+        "-Dminecraft.launcher.version=0.2.3",
+        "-Dsome.prop=com.example.UnluckyLauncher.ClientMain",
+        "com.mojang.authlib.GameProfile",
+        "net.minecraft.launchwrapper.Launch.launch(Launch.java:135)",
+        "1.20.1-forge-47.2.0-beta.20250115.123456",
+        "Service.Unavailable.today",
+        "xbl.xsts.entitlements.profile",
+    ] {
+        assert_eq!(scrub(text), text, "误杀：{text}");
+    }
+}
+
+/// 老规则的负例（M240 重构时被丢掉过，复审 P2-3 要求找回）：分段太短 / 总长不够 / 段数不够。
+#[test]
+fn dotted_token_rule_does_not_eat_normal_text() {
+    for text in [
+        "Service.Unavailable.today",
+        "1.2.0",
+        "xbl.xsts.entitlements.profile",
+        "eyJhbGciOiJIUzI1NiJ9.short.abc",
+    ] {
+        assert!(!has_dotted_token(text), "{text}");
+        assert_eq!(scrub(text), text, "{text}");
+    }
+}
+
+/// 整条 HMCL 形状的 argv（`--dry-run` 的面）：一处都不许动。
+#[test]
+fn hmcl_shaped_argv_survives_verbatim() {
+    let argv = "javaw.exe -Dminecraft.launcher.brand=UnluckyLauncher -Dminecraft.launcher.version=0.2.3 \
+                -cp /home/alice/.minecraft/libraries/net/minecraftforge/forge/1.20.1-47.2.0/forge-1.20.1-47.2.0-universal.jar \
+                net.minecraft.launchwrapper.Launch";
+    assert_eq!(scrub(argv), argv);
+}
+
+/// M239 的 U1–U6：CDN / 镜像主机名（判据 = 首段是 DNS 主机名 → 只判路径那半）。
+#[test]
+fn cdn_and_mirror_urls_survive() {
+    for text in [
+        "https://resources.download.minecraft.net/ab/cdef",
+        "https://bmclapi2.bangbang93.com/assets/ab/abcdef0123456789abcdef",
+        "http://textures.minecraft.net/texture/8f4a1b2c3d4e5f60718293a4b5c6d7e8",
+        "https://libraries.minecraft.net/net/minecraft/launchwrapper/1.12/launchwrapper-1.12.jar",
+        "https://api.minecraftservices.com/entitlements/mcstore",
+        "https://maven.minecraftforge.net/net/minecraftforge/forge/1.20.1-47.2.0/forge.jar",
+        // 40 字符的纯主机名形状：DNS 形 → 靠首段主机名豁免（不是靠大写判据，
+        // 大写判据只管非 DNS 形状，归属见 `lowercase_dotted_names_are_spared` 的 doc）
+        "resources.download.minecraft.example-cdn",
+        // 短域名 + 长路径（内容全是词形名字）
+        "https://short.host/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        "mirror.example.com/downloads/0123456789abcdef0123456789abcdef0123456789abcdef",
+    ] {
+        assert_eq!(scrub(text), text, "URL/主机名被抹：{text}");
+    }
+}
+
+/// M239 的 O1–O3 / ⑥'：长路径、Java 包名路径（段名是词形，不是随机串）。
+#[test]
+fn long_paths_and_class_paths_survive() {
+    for text in [
+        "Java Path: /home/alice/.minecraft/runtime/java-runtime-delta/linux/java-runtime-delta/bin/java",
+        "java.lang.NoClassDefFoundError: org/spongepowered/asm/mixin/transformer/FabricMixinTransformerProxy",
+        "/srv/games/minecraft/instances/AllTheMods10/mods/sophisticatedbackpacks-universal.jar",
+        "/var/folders/xy/0123456789abcdef0123456789abcdef/T/unlucky/launch",
+        "net/minecraftforge/fml/loading/FMLEnvironment",
+    ] {
+        assert_eq!(scrub(text), text, "路径被抹：{text}");
+    }
+}
+
+/// 语料组：M239 的回归语料，形状规则**一行都不许改**。
+///
+/// **只守一个方向**：它证明"该保留的保留了"，**不能**拿来背书"正例仍被抹"——正例那一方向
+/// 由 `jwts_are_masked_in_every_log_shape` / `opaque_secrets_are_masked_in_every_log_shape` 显式断言。
+#[test]
+fn sample_corpus_is_untouched() {
+    let files = corpus_files();
+    let mut lines = 0usize;
+    let mut changed = Vec::new();
+    for file in &files {
+        let text = std::fs::read_to_string(file).unwrap_or_default();
+        for (idx, line) in text.lines().enumerate() {
+            lines += 1;
+            let out = scrub(line);
+            if out != line {
+                changed.push(format!("{}:{} → {out}", file.display(), idx + 1));
+            }
+        }
+    }
+    assert_eq!(files.len(), 68, "语料文件数变了（M239 口径 68）");
+    assert_eq!(lines, 243, "语料行数变了（M239 口径 243）");
+    assert!(changed.is_empty(), "形状规则改了语料行：{changed:#?}");
+}
+
+// ───────────────────────── 边界 ─────────────────────────
+
+/// 判据的缝合线：路径里**段本身**够长时照抹，段不长就整条留下。
+#[test]
+fn a_long_path_component_is_still_masked() {
+    // 63 字符的段：与无点号密钥的判定长度差一个字符，留下
+    let short = format!("https://short.host/{}", "a".repeat(63));
+    assert_eq!(scrub(&short), short);
+    // 64 字符的段：形状上与 `sha256=` 不可区分，抹掉
+    let long = format!("https://short.host/{}", "a".repeat(64));
+    assert_eq!(
+        scrub(&long),
+        format!("https://short.host/{OPAQUE_PLACEHOLDER}")
+    );
+    // 路径里夹一段 64 位 hex：只有那一段消失
+    assert_eq!(
+        scrub(&format!("/srv/mc/assets/objects/{SHA256}")),
+        format!("/srv/mc/assets/objects/{OPAQUE_PLACEHOLDER}")
+    );
+}
+
+/// 边界：**没有** `/` 的长文件名与无点号密钥同形，只能照抹（已知残留，见报告）。
+#[test]
+fn a_bare_long_filename_is_still_masked() {
+    assert_eq!(
+        scrub("sophisticatedbackpacks-universal-fabric-loader-compatible-build-final.jar"),
+        format!("{OPAQUE_PLACEHOLDER}.jar")
+    );
+}
+
+/// 边界：路径里有一段**不是**词形的随机串 → 整条按凭据处理（安全方向）。
+#[test]
+fn a_path_with_a_random_looking_component_is_masked() {
+    let secret = "srv/games/aB3xK9mQ2pL5vN8rW1tY4uI7oP0sD6fGhJ2kL5zX8cV1bN4mQ7wE3rT6yU9";
+    assert_eq!(scrub(secret), OPAQUE_PLACEHOLDER);
+}
+
+/// 边界：URL 主机名放行**不**等于整个 run 放行——JWT 摆在路径里照样抹；
+/// 而主机名后面的长路径如果本身是词形，整条留下（`--dry-run` 要能复制）。
+#[test]
+fn url_host_is_exempt_but_the_path_half_is_still_judged() {
+    assert_eq!(
+        scrub(&format!("https://cdn.example.com/{JWT}")),
+        format!("https://cdn.example.com/{TOKEN_PLACEHOLDER}")
+    );
+    let url = "https://resources.download.minecraft.net/assets/objects/4b9d8b9d4e6f4c9a8b7d6e5f";
+    assert_eq!(scrub(url), url);
+}
+
+/// 「旧行为抹、新行为留」的三类形状（复审 P2-1：口径写准，别留"抹除能力没有下降"的绝对承诺）。
+///
+/// 三条都用 **M240 之前的真实代码**（`git show 74be510:crates/core/src/launch/redact.rs` 直接
+/// 用 rustc 编成探针）实测过：旧行为输出 ``，现在逐字原样。前两条是本次要修的
+/// 误杀本身，第三条是全小写点分串的代价（理由见 `shape` 模块文档的「旧行为抹、新行为留」）。
+#[test]
+fn known_narrowings_old_masked_new_keeps() {
+    // ① `=` 边界：键把值带过线（旧行为把 `键=值` 粘成一段凑够段数）
+    let brand = "-Dminecraft.launcher.brand=UnluckyLauncher";
+    assert_eq!(scrub(brand), brand, "旧行为：");
+    // ② 填充不算段长：末段实际 6 字符（旧行为把 `c2lnbm==` 算成 8 ≥ 8 → 抹）
+    let padded = "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.c2lnbm==";
+    assert_eq!(scrub(padded), padded, "旧行为：");
+    // ② 的另一侧：末段 8 字符仍照抹（占位符在前、填充留在外面）
+    assert_eq!(
+        scrub("eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.c2lnbmFy=="),
+        format!("{TOKEN_PLACEHOLDER}==")
+    );
+    // ③ 全小写点分串：DNS 形的靠主机名豁免、非 DNS 形的靠"必须含大写"（旧行为都会抹）
+    let lowercase = "sophisticatedbackpacks.upgrades.reference";
+    assert_eq!(scrub(lowercase), lowercase, "旧行为：");
+}
+
+/// "必须含大写"这条判据**自己**在扛的用例（复审 P2-2 的 (b)）。
+///
+/// 先划清它的实际覆盖面（复审的怀疑是对的）：**DNS 形状**的全小写点分串（`a.b.c` 全小写）
+/// 已经被 [`is_dns_host`] 那条主机名豁免救下了，跟大写判据无关。大写判据唯一扛住的是
+/// **不是 DNS 形状**的全小写点分串——例如标签里带 `_`（Java 标识符常见写法）、标签超 63 字符、
+/// 或 `/` 之前只有一段主机名。下面就是这一类。
+///
+/// 删掉 `jwt_shaped` 里那条大写判据，**这条测试与 `lowercase_dotted_names_are_spared` 会红，
+/// 其余 15 条仍绿**（M240 复审实测：删判据 → 15 passed / 2 failed）。
+#[test]
+fn the_uppercase_requirement_is_load_bearing() {
+    for text in [
+        "sophisticated_backpacks.upgrades.reference", // 41 字符，段长 23/8/9，标签带 `_`
+        "spongepowered_mixins.injections.callback",   // 40 字符，段长 20/10/8，标签带 `_`
+    ] {
+        assert_eq!(
+            scrub(text),
+            text,
+            "全小写、非 DNS 形状的点分串被抹（大写判据失效？）：{text}"
+        );
+    }
+}
+
+/// 全小写点分串整体都不该被抹（两类出口各管一半，测试分开写以免把功劳记错）：
+/// DNS 形的靠主机名豁免，非 DNS 形的靠"必须含大写"。
+#[test]
+fn lowercase_dotted_names_are_spared() {
+    for text in [
+        "sophisticatedbackpacks.upgrades.reference", // DNS 形状 → 主机名豁免
+        "libraries.minecraftservices.entitlements",  // DNS 形状 → 主机名豁免
+        "sophisticated_backpacks.upgrades.reference", // 非 DNS → 大写判据
+    ] {
+        assert_eq!(scrub(text), text, "全小写点分串被抹：{text}");
+    }
+}
+
+/// 两个入口必须一致：`scrub` 用 `has_*` 当闸门，闸门关着就永远不会调 `mask_*`。
+#[test]
+fn the_has_gate_agrees_with_the_maskers() {
+    let cases = [
+        JWT,
+        MSA,
+        "-Dminecraft.launcher.brand=UnluckyLauncher",
+        "https://resources.download.minecraft.net/ab/cdef",
+        "https://short.host/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        "Java Path: /home/alice/.minecraft/runtime/java-runtime-delta/bin/java",
+        "java.lang.NoClassDefFoundError: org/spongepowered/asm/mixin/transformer/FabricMixinTransformerProxy",
+        SHA256,
+        "1.2.0",
+        "",
+    ];
+    for case in cases {
+        assert_eq!(
+            has_dotted_token(case),
+            mask_dotted_tokens(case) != case,
+            "has_dotted_token 与 mask_dotted_tokens 不一致：{case}"
+        );
+        assert_eq!(
+            has_opaque_run(case),
+            mask_opaque(case) != case,
+            "has_opaque_run 与 mask_opaque 不一致：{case}"
+        );
+    }
+}
+
+/// 语料 = `rules.d/samples/**/*.log` + app 壳的两份示例日志（M239 的 68 文件口径）。
+fn corpus_files() -> Vec {
+    let root = Path::new(env!("CARGO_MANIFEST_DIR"));
+    let mut files = Vec::new();
+    let mut stack = vec![root.join("src/diagnose/rules.d/samples")];
+    while let Some(dir) = stack.pop() {
+        let Ok(entries) = std::fs::read_dir(&dir) else {
+            continue;
+        };
+        for entry in entries.flatten() {
+            let path = entry.path();
+            if path.is_dir() {
+                stack.push(path);
+            } else if path.extension().is_some_and(|ext| ext == "log") {
+                files.push(path);
+            }
+        }
+    }
+    for name in ["sample_crash.log", "sample_live.log"] {
+        files.push(root.join("../app-iced/src/pages/logs").join(name));
+    }
+    files.sort();
+    files
+}
diff --git a/crates/core/src/launch/redact/tests/bearerdot.rs b/crates/core/src/launch/redact/tests/bearerdot.rs
new file mode 100644
index 0000000..80f565e
--- /dev/null
+++ b/crates/core/src/launch/redact/tests/bearerdot.rs
@@ -0,0 +1,96 @@
+//! BEARERDOT（M243）：token 后面跟句读时也要抹，句读原位保留。
+//!
+//! # 漏抹的形状
+//!
+//! `Bearer eyJ….eyJ….c2ln….`（行尾一个英文句点）：句点自己属于 dotted 字符集
+//! （[`is_dotted_token_char`]），扫描器把它算进 run，`split('.')` 多切出一个空段，
+//! 「每段 ≥8」当场不成立，整串原样落盘。M240 实测 `old == new == 原文`，
+//! 影响面是 core 的全部落盘/展示面（会话 JSONL、`--dry-run`、诊断规则输入）。
+//!
+//! # 修法
+//!
+//! 不是抬阈值，是**判定前把句读切出去**（[`split_trailing_punct`]）：判据只看 token 本体，
+//! 句读由搬运方（`push_dotted`）原位写回。方向是对安全的那一侧：削短只会让形状判据
+//! 更容易成立，不会把真 token 放过去。`(`、`)`、`,`、`;` 早就在字符集外，一并钉住，
+//! 免得下次改字符集时又把这四个位置漏掉。
+//!
+//! # 另一半：句读不是「见到句点就抹」的入口
+//!
+//! 削句读之后必须证明句点分隔的普通文本没被顺手拖进来（`Service.Unavailable.today.`），
+//! 这一侧由 [`sentences_ending_in_punctuation_still_survive`] 钉住；否则修法等于用
+//! 「行尾有没有句点」当抹除判据，那是把 M239/M240 修掉的误杀换了个形状请回来。
+
+use super::*;
+
+/// 真凭据 + 句读：token 照抹，句读原位保留（不是被占位符吃掉，也不是被当噪声丢掉）。
+#[test]
+fn trailing_sentence_punctuation_does_not_hide_a_token() {
+    let cases = [
+        // form ①：行尾句点
+        (
+            format!("Bearer {JWT}."),
+            format!("Bearer {TOKEN_PLACEHOLDER}."),
+        ),
+        // form ②：句点后还有正文（`"…c2ln…. then"`）
+        (
+            format!("the token was {JWT}. then"),
+            format!("the token was {TOKEN_PLACEHOLDER}. then"),
+        ),
+        // form ③：逗号
+        (format!("{JWT},"), format!("{TOKEN_PLACEHOLDER},")),
+        // form ④：括号（左右都在字符集外，钉住说明它们从来不是判据的一部分）
+        (format!("({JWT})"), format!("({TOKEN_PLACEHOLDER})")),
+        // MSA/XSTS 票据被抄进日志时正是这个位置：键 + 分号
+        (
+            format!("xsts: {MSA};"),
+            format!("xsts: {TOKEN_PLACEHOLDER};"),
+        ),
+        // URL 路径里的 token + 行尾句点（主机名豁免只管主机名那半）
+        (
+            format!("https://cdn.example.com/{JWT}."),
+            format!("https://cdn.example.com/{TOKEN_PLACEHOLDER}."),
+        ),
+    ];
+    for (input, expected) in cases {
+        assert_eq!(scrub(&input), expected, "输入：{input}");
+    }
+}
+
+/// 句点分隔的普通文本：削句读不许把「行尾有句点」变成新的抹除入口。
+///
+/// 每一条都是 `brand_and_property_strings_survive` / `long_paths_and_class_paths_survive`
+/// 里已经钉过的形状，末尾加一个句点——断言 `scrub` 逐字原样，且闸门 `has_dotted_token` 不开。
+#[test]
+fn sentences_ending_in_punctuation_still_survive() {
+    for text in [
+        "Service.Unavailable.today.",
+        "the error came back. Service.Unavailable.today.",
+        "sophisticatedbackpacks.upgrades.reference.",
+        "xbl.xsts.entitlements.profile.",
+        "Java Path: /home/alice/.minecraft/runtime/java-runtime-delta/bin/java.",
+    ] {
+        assert!(!has_dotted_token(text), "闸门开了：{text}");
+        assert_eq!(scrub(text), text, "误杀：{text}");
+    }
+}
+
+/// 两个入口在带句读的输入上仍要一致：`has_*` 开着闸门，`mask_*` 就必须真的改。
+///
+/// `scrub` 用 `has_dotted_token` 当闸门，闸门与搬运方对句读的看法一旦分叉（一边削、一边不削），
+/// `scrub` 会静默走「闸门关着 → 什么都不抹」这条路，测试却全绿。
+#[test]
+fn the_has_gate_agrees_on_trailing_punctuation() {
+    for case in [
+        format!("Bearer {JWT}."),
+        format!("{JWT},"),
+        format!("({JWT})"),
+        format!("the token was {MSA}. then"),
+        "Service.Unavailable.today.".to_string(),
+    ] {
+        assert_eq!(
+            has_dotted_token(&case),
+            mask_dotted_tokens(&case) != case,
+            "has_dotted_token 与 mask_dotted_tokens 不一致：{case}"
+        );
+    }
+}
diff --git a/crates/core/src/launch/request.rs b/crates/core/src/launch/request.rs
new file mode 100644
index 0000000..dcc1c6a
--- /dev/null
+++ b/crates/core/src/launch/request.rs
@@ -0,0 +1,359 @@
+//! 启动请求：命令行组装的输入模型（纯数据，无 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, 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,
+    /// 最大堆 `-Xmx`。
+    pub max_mb: Option,
+}
+
+/// 版本清单里的参数（`arguments.jvm` / `arguments.game` / 旧版 `minecraftArguments`）。
+#[derive(Debug, Clone, Default)]
+pub struct ManifestArgs {
+    /// 主类。
+    pub main_class: Option,
+    /// 现代清单的 JVM 参数（带 rules）。
+    pub jvm: Vec,
+    /// 现代清单的游戏参数（带 rules）。
+    pub game: Vec,
+    /// 旧版清单的整串游戏参数（1.12 及更早）。
+    pub legacy_arguments: Option,
+    /// 版本库表里带 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,
+    /// 普通 JVM 参数（整体按“默认值”处理）。
+    pub jvm: Vec,
+    /// 追加在最后、可覆盖前面一切的 game 参数。
+    pub game: Vec,
+    /// 额外环境变量（用户自定义，最后覆盖）。
+    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 {
+        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,
+    /// 密码。
+    pub password: Option,
+}
+
+/// 模组加载器种类（决定 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,
+    /// 调试日志变体。
+    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,
+    /// macOS 上的 Vulkan ICD JSON。
+    pub vulkan_icd: Option,
+}
+
+/// JVM 自动优化选项。
+#[derive(Debug, Clone)]
+pub struct OptimizationOptions {
+    /// 是否注入自动优化参数（用户可关）。
+    pub enabled: bool,
+    /// 物理内存 MiB（决定 CodeCache 一组参数的开关）。
+    pub physical_memory_mb: Option,
+}
+
+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` 为分类器构件清单）。
+    ///
+    /// 解压发生在**组装期**（`spawn`/`launch` 的「环境准备」段）；`dry_run` 只**预览**同一段
+    /// 的结果（不建目录、不写文件），见 [`crate::launch::natives`] 与
+    /// `SubAgentsTalk/launch-natives-解压与时代分界.md`。
+    pub natives: NativesPlan,
+    /// 账户。
+    pub auth: AuthPlaceholders,
+    /// 用户参数。
+    pub user: UserArgs,
+    /// 特性开关。
+    pub features: FeatureSet,
+    /// 分辨率（`None` 表示不指定）。
+    pub resolution: Option,
+    /// 一键进入。
+    pub quick_play: Option,
+    /// SOCKS 代理。
+    pub proxy: Option,
+    /// 图形后端（`default` / `opengl` / `vulkan`）。
+    ///
+    /// 下发门限见 [`graphics_backend_allowed`](crate::launch::game_args::graphics_backend_allowed)：
+    /// 可解析版本 ≥ `26.2-snapshot-2`，周快照另按版本库表的能力位判。
+    pub graphics_backend: Option,
+    /// 全屏。
+    pub fullscreen: bool,
+    /// 进程优先级（POSIX `nice -n`，Windows 忽略）。
+    pub nice: Option,
+    /// 命令包装器（`optirun`、`prime-run` 等）。
+    pub wrapper: Vec,
+    /// `-javaagent:` 列表。
+    pub java_agents: Vec,
+    /// 登录源提供的 JVM 参数（authlib-injector）。
+    pub auth_jvm_args: Vec,
+    /// 登录源提供的游戏参数。
+    pub auth_game_args: Vec,
+    /// 模组加载器。
+    pub mod_loader: ModLoaderKind,
+    /// Log4j 注入。
+    pub log4j: Log4jOptions,
+    /// 渲染器开关。
+    pub renderer: RendererOptions,
+    /// JVM 自动优化。
+    pub optimization: OptimizationOptions,
+    /// `-Dfile.encoding` 指定值（`COMPAT` 表示跟随系统）。
+    pub encoding: Option,
+    /// 界面语言（`${language}`）。
+    pub language: String,
+    /// 已过滤为“确实存在”的 classpath（主 jar 由组装器追加到末位）。
+    pub classpath: Vec,
+    /// 组件就绪检查发现的缺失项（非空则组装直接失败）。
+    pub missing_components: Vec,
+    /// 额外注入的 JVM 参数（品牌/特性钩子，`appendJvmArgs` 的替代者）。
+    pub extra_jvm: Vec,
+}
diff --git a/crates/core/src/launch/session.rs b/crates/core/src/launch/session.rs
new file mode 100644
index 0000000..5084117
--- /dev/null
+++ b/crates/core/src/launch/session.rs
@@ -0,0 +1,384 @@
+//! JSONL 会话事件流：`/game/.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 产出、由本模块落盘；
+//! 3. **规则结论在脱敏前算**（M241）：盘上只有脱敏文本，而脱敏的有损规则会把证据行也抹掉
+//!    （`fabric.loader_0_12` 的类路径就被 `≥64` 那条吃掉）。所以原始行在内存里留一个有界尾窗
+//!    （`session/raw_window.rs`），收尾时交给 [`crate::diagnose::session::conclude`] 算一次，
+//!    落盘的仍然只有**结论**——它自己还要再走一遍 `scrub_json`。
+
+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::diagnose::session::{self as diagnosis, RawFacts};
+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;
+
+#[path = "session/event_kind.rs"]
+mod event_kind;
+#[path = "session/raw_window.rs"]
+mod raw_window;
+
+pub use event_kind::EventKind;
+
+/// 会话结束原因。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum EndReason {
+    /// 进程自然退出。
+    Exit,
+    /// 被主动结束。
+    Killed,
+    /// 启动前失败（组装/组件检查）。
+    AssemblyFailed,
+    /// 进程派生失败。
+    SpawnFailed,
+    /// 看门狗到点停止等待，进程仍在运行（D6：不杀进程，只结束本次会话）。
+    StillRunning,
+}
+
+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",
+            Self::StillRunning => "still_running",
+        }
+    }
+}
+
+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,
+    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,
+    exit_type: Option,
+    silent_failure: bool,
+    diagnosis_top: Option,
+    /// 是否值得跑诊断（与 `ExitAnalysis::needs_diagnosis` 同值）。
+    needs_diagnosis: bool,
+    /// 原始行尾窗（诊断用；**不落盘**，见模块文档第 3 条）。
+    raw: raw_window::RawWindow,
+    finished: bool,
+}
+
+impl SessionWriter {
+    /// 新建会话（id 由时间 + pid 生成）。
+    pub fn create(sessions_root: &Path, meta: SessionMeta, redactor: Redactor) -> Result {
+        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 {
+        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,
+            needs_diagnosis: false,
+            raw: raw_window::RawWindow::default(),
+            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` 行事件。
+    ///
+    /// 原始文本先进内存尾窗（诊断用），落盘的是脱敏后的那份（[`Redactor`]）。
+    pub fn line(&mut self, line: &LogLine) -> Result<()> {
+        let kind = match line.stream {
+            Stream::Stdout => EventKind::Stdout,
+            Stream::Stderr => EventKind::Stderr,
+        };
+        self.raw.push(line);
+        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();
+        self.needs_diagnosis = analysis.needs_diagnosis;
+        let payload = payload::exit(analysis);
+        self.record(EventKind::Exit, payload)
+    }
+
+    /// `crash_found`：以 `path` 为权威字段（M15 自己读盘）。
+    ///
+    /// 这条只是「找到了这个现场文件」的**事实**记录，不参与索引里的崩溃结论——结论由
+    /// [`Self::mark_crash`] 按 `crash_scan::has_crash_evidence` 的判定写入（M211/D3）。
+    pub fn crash_found(&mut self, source: &str, path: &Path, excerpt: Option<&str>) -> Result<()> {
+        let payload = payload::crash_found(source, path, excerpt, &self.redactor);
+        self.record(EventKind::CrashFound, payload)
+    }
+
+    /// 写入索引前的崩溃结论（`crash_scan::has_crash_evidence` 的结果）。
+    ///
+    /// 索引里的 `crash_found` 不再等于「有现场文件」：`logs/latest.log` 每局都写，把它当判据
+    /// 会让每一次干净退出都被标成「游戏崩溃」（M208 实机 D3）。
+    pub fn mark_crash(&mut self, found: bool) {
+        self.crash_found = found;
+    }
+
+    /// `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)
+    }
+
+    /// 用**原始行**补一次规则结论（写失败不打断收尾：launch 另有 `event_write_errors` 收集）。
+    ///
+    /// 门槛与 launch 的挂钩一致（`ExitAnalysis::needs_diagnosis`）：干净退出不跑引擎，也不写空事件。
+    fn conclude_from_raw(&mut self, duration_ms: u64) {
+        if !self.needs_diagnosis || self.diagnosis_top.is_some() {
+            return;
+        }
+        let (stdout, stderr) = self.raw.facts();
+        let facts = RawFacts {
+            exit_code: self.exit_code,
+            duration_ms,
+            error_lines: self.raw.error_lines(),
+            stdout: &stdout,
+            stderr: &stderr,
+        };
+        if let Some(record) = diagnosis::conclude(&facts) {
+            let _ = self.diagnosis(record);
+        }
+    }
+
+    /// `session_end` + 追加索引，返回索引条目。
+    ///
+    /// 收尾前先补一次**原始行**上的规则结论（模块文档第 3 条）：挂上真实 `DiagnosisHook` 时
+    /// 它已经写过结论（`diagnosis_top` 非空），这里不重复；没挂（今天的 `NoopDiagnosis`）就由
+    /// 这里补位，免得读回 JSONL 时只剩脱敏文本可看。
+    pub fn finish(&mut self, reason: EndReason) -> Result {
+        let duration_ms = self.clock.elapsed_ms();
+        self.conclude_from_raw(duration_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: session_index::log_path_for(&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)
+    }
+}
+
+#[cfg(test)]
+#[path = "session_path_tests.rs"]
+mod path_tests;
diff --git a/crates/core/src/launch/session/event_kind.rs b/crates/core/src/launch/session/event_kind.rs
new file mode 100644
index 0000000..21df693
--- /dev/null
+++ b/crates/core/src/launch/session/event_kind.rs
@@ -0,0 +1,58 @@
+//! 会话事件类型（从 `session.rs` 纯搬移，守单文件 400 行上限）。
+//!
+//! 对外路径不变：`unlucky_core::launch::session::EventKind`。
+
+/// 事件类型。
+#[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",
+        }
+    }
+}
diff --git a/crates/core/src/launch/session/raw_window.rs b/crates/core/src/launch/session/raw_window.rs
new file mode 100644
index 0000000..cb60a2e
--- /dev/null
+++ b/crates/core/src/launch/session/raw_window.rs
@@ -0,0 +1,59 @@
+//! 原始行尾窗（M241）：诊断要在**脱敏前**的文本上跑，落盘仍然只有脱敏文本。
+//!
+//! 会话事件流是写前脱敏的，脱敏的两条形状规则有损（见 [`crate::diagnose::session`] 的模块
+//! 文档）。所以边界是：原始行**只在本进程内存里活到会话收尾**，收尾时算一次规则结论
+//! （`diagnose::session::conclude`），写进 JSONL 的是结论本体，仍然过 `Redactor::scrub_json`。
+//!
+//! 容量按展示侧 `DEFAULT_TAIL` 同量级取：规则引擎看的是最近的日志，不是开局那几行；
+//! 错误行数另外全量统计（`exit0 静默失败` 那类判据要的是总数，不是尾窗里的数）。
+
+use std::collections::VecDeque;
+
+use crate::launch::pump::LogLine;
+
+/// 保留多少行原始文本（尾窗）。
+pub const CAPACITY: usize = 2000;
+
+/// 原始行尾窗 + 全量错误行计数。
+#[derive(Debug, Default)]
+pub struct RawWindow {
+    lines: VecDeque<(bool, String)>,
+    errors: u32,
+}
+
+impl RawWindow {
+    /// 记一行**原始**（未脱敏）文本。
+    pub fn push(&mut self, line: &LogLine) {
+        if line.level().is_error() {
+            self.errors = self.errors.saturating_add(1);
+        }
+        if self.lines.len() >= CAPACITY {
+            self.lines.pop_front();
+        }
+        self.lines
+            .push_back((line.stream.is_stderr(), line.text.clone()));
+    }
+
+    /// 全量错误行数。
+    pub fn error_lines(&self) -> u32 {
+        self.errors
+    }
+
+    /// 尾窗按流拆开：`(stdout, stderr)`，各自按时间顺序。
+    pub fn facts(&self) -> (Vec, Vec) {
+        let mut stdout = Vec::new();
+        let mut stderr = Vec::new();
+        for (is_stderr, text) in &self.lines {
+            if *is_stderr {
+                stderr.push(text.clone());
+            } else {
+                stdout.push(text.clone());
+            }
+        }
+        (stdout, stderr)
+    }
+}
+
+#[cfg(test)]
+#[path = "raw_window_tests.rs"]
+mod tests;
diff --git a/crates/core/src/launch/session/raw_window_tests.rs b/crates/core/src/launch/session/raw_window_tests.rs
new file mode 100644
index 0000000..206ce11
--- /dev/null
+++ b/crates/core/src/launch/session/raw_window_tests.rs
@@ -0,0 +1,46 @@
+//! `raw_window` 的单测。
+
+use super::*;
+use crate::launch::pump::Stream;
+
+fn line(stream: Stream, text: &str) -> LogLine {
+    LogLine::new(stream, text)
+}
+
+#[test]
+fn keeps_the_tail_and_counts_every_error_line() {
+    let mut window = RawWindow::default();
+    window.push(&line(
+        Stream::Stderr,
+        "java.lang.IllegalStateException: boom",
+    ));
+    window.push(&line(Stream::Stdout, "[main/INFO]: Setting user"));
+    assert_eq!(window.error_lines(), 1);
+    let (stdout, stderr) = window.facts();
+    assert_eq!(stdout, vec!["[main/INFO]: Setting user".to_string()]);
+    assert_eq!(
+        stderr,
+        vec!["java.lang.IllegalStateException: boom".to_string()]
+    );
+}
+
+/// 尾窗有界：`CAPACITY` 之前的行被丢掉，但**错误行数照旧全量**。
+#[test]
+fn the_window_is_bounded_while_error_count_is_not() {
+    let mut window = RawWindow::default();
+    for index in 0..(CAPACITY + 10) {
+        window.push(&line(Stream::Stdout, &format!("line {index}")));
+    }
+    let (stdout, _) = window.facts();
+    assert_eq!(stdout.len(), CAPACITY);
+    assert_eq!(stdout.first().map(String::as_str), Some("line 10"));
+    assert_eq!(window.error_lines(), 0);
+
+    for _ in 0..3 {
+        window.push(&line(
+            Stream::Stderr,
+            "java.lang.OutOfMemoryError: Java heap space",
+        ));
+    }
+    assert_eq!(window.error_lines(), 3);
+}
diff --git a/crates/core/src/launch/session_handle.rs b/crates/core/src/launch/session_handle.rs
new file mode 100644
index 0000000..04b32c5
--- /dev/null
+++ b/crates/core/src/launch/session_handle.rs
@@ -0,0 +1,130 @@
+//! 一次启动的结果（[`SessionHandle`]）。
+//!
+//! 从 `launch_session` 拆出：那边是「跑一局 + 收尾」的流水线，这里是**纯数据 + 展示**。
+//! 拆开的直接原因是行数——`launch_session` 加上 D6 的有界等待后越过了 400 行红线。
+
+use std::path::PathBuf;
+
+use serde_json::Value;
+
+use crate::launch::args_table::AssembledCommand;
+use crate::launch::crash_scan::CrashArtifact;
+use crate::launch::exit_analysis::ExitAnalysis;
+use crate::launch::session_index::SessionIndexEntry;
+
+/// 一次启动的结果。
+#[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_argv: Vec,
+    /// 退出判定。
+    pub exit: ExitAnalysis,
+    /// 诊断结论（M15 产出，已写入事件流）。
+    pub diagnostics: Option,
+    /// 索引条目（写入 `index.jsonl` 的那一行）。
+    pub index: Option,
+    /// 崩溃现场文件。
+    pub artifacts: Vec,
+    /// 游戏存活毫秒数。
+    pub uptime_ms: u64,
+    /// 日志泵是否超时（watchdog 触发 = 有子进程没关 stdout）。
+    pub pump_stalled: bool,
+    /// 会话写入错误（磁盘问题；不影响进程结果）。
+    pub event_write_errors: Vec,
+}
+
+impl SessionHandle {
+    /// 构造（`redacted_argv` 只在这里赋值，外部拿不到明文 argv 的那条路）。
+    #[allow(clippy::too_many_arguments)]
+    pub(crate) fn new(
+        session_id: String,
+        log_path: PathBuf,
+        command: AssembledCommand,
+        redacted_argv: Vec,
+        exit: ExitAnalysis,
+        diagnostics: Option,
+        index: Option,
+        artifacts: Vec,
+        uptime_ms: u64,
+        pump_stalled: bool,
+        event_write_errors: Vec,
+    ) -> Self {
+        Self {
+            session_id,
+            log_path,
+            command,
+            redacted_argv,
+            exit,
+            diagnostics,
+            index,
+            artifacts,
+            uptime_ms,
+            pump_stalled,
+            event_write_errors,
+        }
+    }
+
+    /// 脱敏后的完整 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::>()
+            .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
+    }
+
+    /// 结局标签，与 GUI 的 `LogOutcome` 同词（`Ok` / `Crashed` / `SilentFail`）。
+    ///
+    /// `launcher.log` 里两条路（GUI / `ull launch`）都写这一套词，见
+    /// [`crate::launch::launcher_log::launch_end_line`]。
+    pub fn outcome_label(&self) -> &'static str {
+        if self.exit.silent_failure.is_some() {
+            "SilentFail"
+        } else if self.succeeded() {
+            "Ok"
+        } else {
+            "Crashed"
+        }
+    }
+
+    /// 一句话摘要。
+    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/session_index.rs b/crates/core/src/launch/session_index.rs
new file mode 100644
index 0000000..c9548ca
--- /dev/null
+++ b/crates/core/src/launch/session_index.rs
@@ -0,0 +1,145 @@
+//! 会话记录索引：`list_game_sessions` 的数据源。
+//!
+//! 文件：`/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};
+
+use crate::platform::layout::GAME_LOG_DIR;
+
+/// 索引条目的 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,
+    /// 退出判定字符串。
+    pub exit_type: Option,
+    /// 是否静默失败。
+    pub silent_failure: bool,
+    /// 是否检测到游戏窗口。
+    pub window_detected: bool,
+    /// 事件条数。
+    pub event_count: u64,
+    /// 事件流相对**会话根**的路径（生产形状 `game/.jsonl`）。
+    ///
+    /// 契约里「相对谁」只有这一句，见 [`event_file`]。M211 之前这里写成「相对 `game/`」，
+    /// 而写入侧一直按「相对会话根」写 —— 两个说法各自成立，两处读取点于是都多 join 了一层
+    /// `game/`，`ull logs` / `ull diag` 对每个真实会话都报「找不到事件流」。
+    pub log_path: String,
+    /// 是否抓到崩溃报告/hs_err。
+    pub crash_found: bool,
+    /// 诊断首因（M15 写入的第一个候选 id）。
+    pub diagnosis_top: Option,
+}
+
+/// 索引文件路径（`/game/index.jsonl`）。
+pub fn index_path(sessions_root: &Path) -> PathBuf {
+    sessions_root.join("game").join("index.jsonl")
+}
+
+/// 写入侧用的 `log_path`：**相对会话根**（``）的形状，`game/.jsonl`。
+///
+/// 写入侧（[`crate::launch::session::SessionWriter`]）与读取侧（[`event_file`]）都只认这一个
+/// 函数产出的形状，所以「存什么」与「怎么找回来」不可能再各说一套（M211/D2）。
+pub fn log_path_for(session_id: &str) -> String {
+    format!("{GAME_LOG_DIR}/{session_id}.jsonl")
+}
+
+/// `log_path` → 事件流文件（相对**会话根**解析，M211/D2）。
+///
+/// 这是全仓唯一的解析点：CLI 的 `ull logs` / `ull diag` 与 presenter 的日志页都走这里，
+/// 谁也不再自己往前拼一层 `game/`。
+///
+/// 存量数据不需要迁移：索引里的 `log_path` 从第一版起就是 `game/.jsonl`，正是本函数的
+/// 输入形状（`/game/.jsonl`），只是之前的读取侧又拼了一次 `game/` 才找不到。
+pub fn event_file(sessions_root: &Path, log_path: &str) -> PathBuf {
+    sessions_root.join(log_path)
+}
+
+/// 追加一行摘要。
+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> {
+    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 = 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::(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> {
+    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,
+        instance_name: impl Into,
+        game_version: impl Into,
+    ) -> 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, version: impl Into) -> 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_path_tests.rs b/crates/core/src/launch/session_path_tests.rs
new file mode 100644
index 0000000..32fd9ae
--- /dev/null
+++ b/crates/core/src/launch/session_path_tests.rs
@@ -0,0 +1,142 @@
+//! M211：写入侧与读取侧对**同一个相对路径**的往返用例（D2 / D3）。
+//!
+//! 这个文件存在的理由：原来的夹具（CLI `tests/support`、presenter `logs_tests`）各自
+//! **手写**索引条目，于是「写入侧存 `game/.jsonl`、读取侧又多 join 一层 `game/`」这个
+//! bug 在测试里永远看不见——夹具自己说了第三种形状。这里跑**真的** [`SessionWriter`]，
+//! 断言它写出的形状与 `session_index::event_file` 解析出的路径是同一个文件。
+//!
+//! 变异证明（把实现改回旧形状 ⇒ 本文件红）：
+//! - `session.rs` 的 `log_path` 改回 `format!("game/{}.jsonl", …)` 之类的手写形状 ⇒
+//!   `the_written_log_path_is_the_one_the_readers_resolve` 的第①③条断言红；
+//! - `session_index::event_file` 里补回 `.join(GAME_LOG_DIR)` ⇒ 同一条用例的第③条红。
+
+use std::path::{Path, PathBuf};
+use std::time::SystemTime;
+
+use crate::launch::crash_scan;
+use crate::launch::exit_analysis::{self, ExitSignals};
+use crate::launch::redact::Redactor;
+use crate::launch::session::{EndReason, SessionMeta, SessionWriter};
+use crate::launch::session_index;
+
+fn temp_dir(tag: &str) -> PathBuf {
+    let root = std::env::temp_dir().join(format!("ull-m211-path-{}-{tag}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&root);
+    std::fs::create_dir_all(&root).expect("建夹具目录");
+    root
+}
+
+fn writer(sessions_root: &Path, session_id: &str) -> SessionWriter {
+    SessionWriter::create_with_id(
+        sessions_root,
+        session_id,
+        SessionMeta::new("inst-1", "实例", "1.20.1"),
+        Redactor::new(),
+    )
+    .expect("建会话写入器")
+}
+
+/// D2 主用例：写入侧存的形状 = 实际落点 = 读取侧解析出的路径（三者同一个文件）。
+#[test]
+fn the_written_log_path_is_the_one_the_readers_resolve() {
+    let root = temp_dir("roundtrip");
+    let mut sink = writer(&root, "s-round");
+    sink.session_start().expect("写 session_start");
+    let entry = sink.finish(EndReason::Exit).expect("收尾");
+
+    // ① 写入侧存进索引的形状：**相对会话根**，带一层 `game/`。
+    assert_eq!(
+        entry.log_path, "game/s-round.jsonl",
+        "写入侧的 log_path 形状漂了（读取侧按这个形状回找）"
+    );
+    // ② 事件流真的落在会话根下的 `game/`。
+    let written = root.join("game").join("s-round.jsonl");
+    assert!(
+        written.is_file(),
+        "事件流不在 {}：{}",
+        written.display(),
+        std::fs::read_dir(root.join("game"))
+            .map(|items| items.filter_map(Result::ok).count())
+            .unwrap_or(0)
+    );
+    // ③ 读取侧（CLI 的 `ull logs`/`ull diag` 与 presenter 的日志页共用）解析到**同一个文件**。
+    assert_eq!(
+        session_index::event_file(&root, &entry.log_path),
+        written,
+        "读取侧解析出的路径与写入侧的真落点不一致（双写 `game/`？）"
+    );
+    // ④ 真读一遍：读取侧拿到的路径里确实有事件。
+    let text = std::fs::read_to_string(session_index::event_file(&root, &entry.log_path))
+        .expect("读事件流");
+    assert!(text.contains("\"session_start\""), "{text}");
+    std::fs::remove_dir_all(&root).ok();
+}
+
+/// D3 主用例：干净退出（`code 0` / `error_lines 0`）⇒ 索引里 `crash_found` 必须是 `false`。
+///
+/// 夹具刻意按生产写：干净的一局也会写 `logs/latest.log`，所以「有 latest.log」不构成证据。
+#[test]
+fn a_clean_exit_is_not_indexed_as_a_crash() {
+    let root = temp_dir("clean-index");
+    let run_dir = temp_dir("clean-run");
+    std::fs::create_dir_all(run_dir.join("logs")).expect("建 logs");
+    std::fs::write(
+        run_dir.join("logs/latest.log"),
+        "[10:15:00] [main/INFO]: hi\n",
+    )
+    .expect("写 latest.log");
+
+    let exit = exit_analysis::analyze(&ExitSignals::new(0, 60_000, &[]));
+    assert_eq!(exit.code, 0);
+    assert_eq!(exit.error_lines, 0, "夹具必须是干净退出");
+
+    let artifacts = crash_scan::scan(&run_dir, SystemTime::now(), 8);
+    let mut sink = writer(&root, "s-clean");
+    sink.exit(&exit).expect("写 exit");
+    for artifact in &artifacts {
+        sink.crash_found(
+            artifact.source.as_str(),
+            &artifact.path,
+            artifact.excerpt.as_deref(),
+        )
+        .expect("写 crash_found");
+    }
+    sink.mark_crash(crash_scan::has_crash_evidence(&artifacts, &exit));
+    let entry = sink.finish(EndReason::Exit).expect("收尾");
+
+    assert!(
+        !entry.crash_found,
+        "干净退出（code 0 / error_lines 0）被标成了崩溃：artifacts={artifacts:?}"
+    );
+    std::fs::remove_dir_all(&root).ok();
+    std::fs::remove_dir_all(&run_dir).ok();
+}
+
+/// 对照用例：真有 `hs_err_pid*.log` 时仍然要标成崩溃（别把 D3 修成「永远 false」）。
+#[test]
+fn a_real_crash_scene_is_still_indexed_as_a_crash() {
+    let root = temp_dir("crash-index");
+    let run_dir = temp_dir("crash-run");
+    std::fs::create_dir_all(run_dir.join("logs")).expect("建 logs");
+    std::fs::write(run_dir.join("logs/latest.log"), "log\n").expect("写 latest.log");
+    std::fs::write(run_dir.join("hs_err_pid77.log"), "SIGSEGV\n").expect("写 hs_err");
+
+    let exit = exit_analysis::analyze(&ExitSignals::new(0, 60_000, &[]));
+    let artifacts = crash_scan::scan(&run_dir, SystemTime::now(), 8);
+    let mut sink = writer(&root, "s-crash");
+    sink.exit(&exit).expect("写 exit");
+    for artifact in &artifacts {
+        sink.crash_found(
+            artifact.source.as_str(),
+            &artifact.path,
+            artifact.excerpt.as_deref(),
+        )
+        .expect("写 crash_found");
+    }
+    sink.mark_crash(crash_scan::has_crash_evidence(&artifacts, &exit));
+    let entry = sink.finish(EndReason::Exit).expect("收尾");
+
+    assert!(entry.crash_found, "hs_err 在却没有标成崩溃：{artifacts:?}");
+    std::fs::remove_dir_all(&root).ok();
+    std::fs::remove_dir_all(&run_dir).ok();
+}
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::::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::>(),
+    })
+}
+
+/// `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::>(),
+        ),
+    };
+    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..f570fc5
--- /dev/null
+++ b/crates/core/src/launch/session_sink.rs
@@ -0,0 +1,89 @@
+//! 把会话事件流接到日志泵上：逐行落盘 + 自动窗口出现检测。
+//!
+//! 放在单独文件是为了让 [`crate::launch::session`] 保持“只写事件、只管索引”的单一职责，
+//! 也避免单文件超过 400 行的硬约束。
+
+use std::sync::Mutex;
+use std::time::Instant;
+
+use crate::launch::pump::{LineSink, LogLine};
+use crate::launch::session::SessionWriter;
+use crate::launch::window_detect::{shutdown_marker, WindowDetector};
+
+/// 会话日志 sink。
+#[derive(Debug)]
+pub struct SessionSink {
+    writer: Mutex,
+    detector: Mutex,
+    shutdown_at: Mutex>,
+    last_line_at: Mutex>,
+}
+
+impl SessionSink {
+    /// 以进程启动时刻为窗口检测起点。
+    pub fn new(writer: SessionWriter) -> Self {
+        Self::with_start(writer, Instant::now())
+    }
+
+    /// 指定窗口检测计时起点（进程 spawn 时刻）。
+    pub fn with_start(writer: SessionWriter, started_at: Instant) -> Self {
+        Self {
+            writer: Mutex::new(writer),
+            detector: Mutex::new(WindowDetector::with_start(started_at)),
+            shutdown_at: Mutex::new(None),
+            last_line_at: Mutex::new(None),
+        }
+    }
+
+    /// 借用写入器（退出分析、结束会话等需要可变访问的场合）。
+    pub fn with_writer(&self, action: impl FnOnce(&mut SessionWriter) -> R) -> Option {
+        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,
+        }
+    }
+
+    /// 第一次见到关闭标记（游戏自己说要退出）的时刻（D6）。
+    pub fn shutdown_seen_at(&self) -> Option {
+        self.shutdown_at.lock().ok().and_then(|guard| *guard)
+    }
+
+    /// 最后一行的时刻（D6：还在打日志就说明还在加载，不算卡死）。
+    pub fn last_line_at(&self) -> Option {
+        self.last_line_at.lock().ok().and_then(|guard| *guard)
+    }
+}
+
+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,
+        };
+        if let Ok(mut guard) = self.last_line_at.lock() {
+            *guard = Some(Instant::now());
+        }
+        if shutdown_marker(&line.text).is_some() {
+            if let Ok(mut guard) = self.shutdown_at.lock() {
+                guard.get_or_insert_with(Instant::now);
+            }
+        }
+        let Ok(mut writer) = self.writer.lock() else {
+            return;
+        };
+        // 会话已经收尾（看门狗放弃等待后进程还在打日志）：不再往事件流里追加，
+        // 否则 `session_end` 之后会出现孤儿行。
+        if writer.is_finished() {
+            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>,
+}
+
+impl CompositeSink {
+    /// 空组合。
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// 追加一个 sink（builder 风格）。
+    pub fn with(mut self, sink: Arc) -> Self {
+        self.sinks.push(sink);
+        self
+    }
+
+    /// 追加一个 sink。
+    pub fn push(&mut self, sink: Arc) {
+        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 {
+    action: F,
+}
+
+impl FnSink {
+    /// 用闭包构造。
+    pub fn new(action: F) -> Self {
+        Self { action }
+    }
+}
+
+impl FnSink {
+    /// 转成 `Arc`（可直接塞进 [`CompositeSink`] / `RunningProcess`）。
+    pub fn shared(self) -> Arc {
+        Arc::new(self)
+    }
+}
+
+impl std::fmt::Debug for FnSink {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str("FnSink")
+    }
+}
+
+impl LineSink for FnSink {
+    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/startup_watch.rs b/crates/core/src/launch/startup_watch.rs
new file mode 100644
index 0000000..1ff5539
--- /dev/null
+++ b/crates/core/src/launch/startup_watch.rs
@@ -0,0 +1,297 @@
+//! 启动看门狗：把「还在慢慢加载」与「活着但没动静」分开（D6）。
+//!
+//! M208 实机：1.12.2 关窗后 `java.exe` 仍存活、CPU 继续涨，`ull launch` 阻塞 >2 分钟，
+//! 用户视角就是启动器卡死。`watchdog.rs` 只管**日志泵**的预算，进程本身是无限等的。
+//!
+//! 这里只做判据（纯逻辑，不碰时钟也不碰进程），两条互不干扰：
+//!
+//! 1. **窗口从未出现**：进程起来后 `startup_limit` 内**既没见到游戏窗口、也没有任何新日志**，
+//!    ⇒ `startup_timeout`。窗口一旦出现过，这条**永久失效**——大整合包首次启动慢是正常现象。
+//!    只按「多久没窗口」判会把慢加载判死，所以判据是**静默**：还在打日志就说明它还在干活。
+//! 2. **已经在关闭**：日志里出现关闭标记（`Stopping!` 等）后 `shutdown_limit` 仍不退出
+//!    ⇒ `shutdown_timeout`。这条只在游戏自己说要退出之后才生效，正是 D6 那个「关窗后挂死」。
+//!
+//! 两个上限都有默认值、都可配（[`crate::launch::process::ProcessConfig`]），也可以关掉（`0`）。
+//! 判出超时**不等于**要杀进程：调用方只停止等待，见
+//! [`crate::launch::launch_session::LaunchSession::finish`]。
+
+use std::time::Duration;
+
+/// 「还要不要继续等」。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum WatchVerdict {
+    /// 继续等。
+    Wait,
+    /// 窗口从未出现、且连续这么久没有任何日志输出。
+    StartupTimeout {
+        /// 已经静默了多久（从最后一行日志算）。
+        waited: Duration,
+        /// 配置的静默预算。
+        limit: Duration,
+    },
+    /// 已出现关闭标记，且超出宽限仍未退出。
+    ShutdownTimeout {
+        /// 从关闭标记到现在等了多久。
+        waited: Duration,
+        /// 配置的宽限。
+        limit: Duration,
+    },
+}
+
+impl WatchVerdict {
+    /// 是否应当继续等。
+    #[must_use]
+    pub fn is_wait(self) -> bool {
+        self == Self::Wait
+    }
+
+    /// 稳定字符串 id（`launcher.log` / `--json` / 错误码用）。
+    #[must_use]
+    pub fn code(self) -> &'static str {
+        match self {
+            Self::Wait => "wait",
+            Self::StartupTimeout { .. } => "startup_timeout",
+            Self::ShutdownTimeout { .. } => "shutdown_timeout",
+        }
+    }
+
+    /// 判据上限（毫秒；`Wait` 为 0）。
+    #[must_use]
+    pub fn limit_ms(self) -> u64 {
+        let limit = match self {
+            Self::Wait => Duration::ZERO,
+            Self::StartupTimeout { limit, .. } | Self::ShutdownTimeout { limit, .. } => limit,
+        };
+        millis(limit)
+    }
+
+    /// 已经等了多久（毫秒；`Wait` 为 0）。
+    #[must_use]
+    pub fn waited_ms(self) -> u64 {
+        match self {
+            Self::Wait => 0,
+            Self::StartupTimeout { waited, .. } | Self::ShutdownTimeout { waited, .. } => {
+                millis(waited)
+            }
+        }
+    }
+
+    /// 人读一行。
+    #[must_use]
+    pub fn describe(self) -> String {
+        match self {
+            Self::Wait => "继续等待".to_string(),
+            Self::StartupTimeout { waited, limit } => format!(
+                "启动 {:.1}s 没有任何日志输出、也没见到游戏窗口（静默预算 {:.1}s）",
+                seconds(waited),
+                seconds(limit)
+            ),
+            Self::ShutdownTimeout { waited, limit } => format!(
+                "已开始关闭但 {:.1}s 仍未退出（宽限 {:.1}s）",
+                seconds(waited),
+                seconds(limit)
+            ),
+        }
+    }
+}
+
+fn seconds(value: Duration) -> f64 {
+    value.as_secs_f64()
+}
+
+fn millis(value: Duration) -> u64 {
+    u64::try_from(value.as_millis()).unwrap_or(u64::MAX)
+}
+
+/// 看门狗状态：见过的信号 + 两个上限。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct StartupWatch {
+    startup_limit: Duration,
+    shutdown_limit: Duration,
+    window_seen: bool,
+    last_activity: Duration,
+    shutdown_at: Option,
+}
+
+impl StartupWatch {
+    /// 用两个上限构造（`Duration::ZERO` = 该条不判）。
+    #[must_use]
+    pub fn new(startup_limit: Duration, shutdown_limit: Duration) -> Self {
+        Self {
+            startup_limit,
+            shutdown_limit,
+            window_seen: false,
+            last_activity: Duration::ZERO,
+            shutdown_at: None,
+        }
+    }
+
+    /// 见到游戏窗口（之后启动预算永久失效）。
+    pub fn mark_window(&mut self) {
+        self.window_seen = true;
+    }
+
+    /// 见到一行日志（进程在干活，静默计时重新开始）。
+    pub fn mark_activity(&mut self, at: Duration) {
+        if at > self.last_activity {
+            self.last_activity = at;
+        }
+    }
+
+    /// 见到关闭标记（只记第一次出现的时刻，相对进程启动）。
+    pub fn mark_shutdown(&mut self, at: Duration) {
+        if self.shutdown_at.is_none() {
+            self.shutdown_at = Some(at);
+        }
+    }
+
+    /// 是否见过窗口。
+    #[must_use]
+    pub fn is_window_seen(&self) -> bool {
+        self.window_seen
+    }
+
+    /// 关闭标记出现的时刻（相对进程启动）。
+    #[must_use]
+    pub fn shutdown_at(&self) -> Option {
+        self.shutdown_at
+    }
+
+    /// 按「进程起来多久」判一次。
+    #[must_use]
+    pub fn verdict(&self, elapsed: Duration) -> WatchVerdict {
+        // 关闭优先：游戏自己说要退了，这时候的「没窗口」不再是信息。
+        if let Some(at) = self.shutdown_at {
+            let waited = elapsed.saturating_sub(at);
+            if !self.shutdown_limit.is_zero() && waited > self.shutdown_limit {
+                return WatchVerdict::ShutdownTimeout {
+                    waited,
+                    limit: self.shutdown_limit,
+                };
+            }
+            return WatchVerdict::Wait;
+        }
+        if !self.window_seen && !self.startup_limit.is_zero() {
+            // 判据是**静默**而不是「等了多久」：还在打日志就说明它还在加载。
+            let quiet = elapsed.saturating_sub(self.last_activity);
+            if quiet > self.startup_limit {
+                return WatchVerdict::StartupTimeout {
+                    waited: quiet,
+                    limit: self.startup_limit,
+                };
+            }
+        }
+        WatchVerdict::Wait
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{StartupWatch, WatchVerdict};
+    use std::time::Duration;
+
+    fn secs(value: u64) -> Duration {
+        Duration::from_secs(value)
+    }
+
+    fn watch() -> StartupWatch {
+        StartupWatch::new(secs(180), secs(60))
+    }
+
+    #[test]
+    fn waits_inside_the_startup_budget() {
+        let watch = watch();
+        assert_eq!(watch.verdict(secs(179)), WatchVerdict::Wait);
+        assert!(matches!(
+            watch.verdict(secs(181)),
+            WatchVerdict::StartupTimeout { .. }
+        ));
+    }
+
+    #[test]
+    fn waiting_stays_alive_while_log_lines_keep_coming() {
+        // 慢加载：一直没有窗口，但每 20s 都有一行日志 → 静默永远不越限。
+        let mut watch = watch();
+        for second in 1..=30u64 {
+            watch.mark_activity(secs(second * 20));
+            assert_eq!(
+                watch.verdict(secs(second * 20 + 1)),
+                WatchVerdict::Wait,
+                "第 {second} 分钟还在打日志，不该判卡死"
+            );
+        }
+        // 之后真的静默了 → 按静默时长报，而不是按总时长。
+        assert_eq!(
+            watch.verdict(secs(600 + 181)),
+            WatchVerdict::StartupTimeout {
+                waited: secs(181),
+                limit: secs(180)
+            }
+        );
+    }
+
+    #[test]
+    fn a_seen_window_disables_the_startup_budget_for_good() {
+        // 大整合包慢慢加载：窗口出现过就不再判「卡在启动」，等到天荒地老也只是 Wait。
+        let mut watch = watch();
+        watch.mark_window();
+        assert_eq!(watch.verdict(secs(1800)), WatchVerdict::Wait);
+    }
+
+    #[test]
+    fn shutdown_grace_only_applies_after_the_marker() {
+        let mut watch = watch();
+        watch.mark_shutdown(secs(300));
+        assert_eq!(watch.verdict(secs(330)), WatchVerdict::Wait);
+        assert_eq!(
+            watch.verdict(secs(361)),
+            WatchVerdict::ShutdownTimeout {
+                waited: secs(61),
+                limit: secs(60)
+            }
+        );
+    }
+
+    #[test]
+    fn shutdown_marker_wins_over_the_startup_budget() {
+        // 没窗口但已经打了「正在关闭」：按关闭判，不按启动判（哪怕总时长已越过启动预算）。
+        let mut watch = watch();
+        watch.mark_shutdown(secs(175));
+        assert_eq!(watch.verdict(secs(200)), WatchVerdict::Wait);
+        // 宽限一到就改口：从关闭标记算起超过 60s 才是「卡在关闭」。
+        assert!(matches!(
+            watch.verdict(secs(236)),
+            WatchVerdict::ShutdownTimeout { .. }
+        ));
+    }
+
+    #[test]
+    fn zero_limits_disable_the_checks() {
+        let mut watch = StartupWatch::new(Duration::ZERO, Duration::ZERO);
+        assert_eq!(watch.verdict(secs(10_000)), WatchVerdict::Wait);
+        watch.mark_shutdown(secs(1));
+        assert_eq!(watch.verdict(secs(10_000)), WatchVerdict::Wait);
+    }
+
+    #[test]
+    fn codes_and_descriptions_are_stable_and_name_both_numbers() {
+        let verdict = WatchVerdict::StartupTimeout {
+            waited: secs(300),
+            limit: secs(180),
+        };
+        assert_eq!(verdict.code(), "startup_timeout");
+        let text = verdict.describe();
+        assert!(text.contains("300.0s"), "{text}");
+        assert!(text.contains("180.0s"), "{text}");
+        assert_eq!(
+            WatchVerdict::ShutdownTimeout {
+                waited: secs(90),
+                limit: secs(60)
+            }
+            .code(),
+            "shutdown_timeout"
+        );
+        assert!(WatchVerdict::Wait.is_wait());
+        assert!(!verdict.is_wait());
+    }
+}
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..4aee9b0
--- /dev/null
+++ b/crates/core/src/launch/tree_kill.rs
@@ -0,0 +1,210 @@
+//! 进程树回收：`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 -- -` 一次覆盖整棵子树 → 宽限 → `kill -KILL -- -`，再补一发单 pid。
+//!
+//! 两个平台都先尝试“温和”，宽限期后再“强制”。
+//!
+//! # 两条来自 CI 的硬约束
+//!
+//! 1. **组杀必须先验组**（[`group_kill_target`]）：目标进程必须是它自己进程组的**组长**，
+//!    且该组不能是我们所在的组。否则一次 `kill -- -` 会把测试进程（CI 容器里全体进程
+//!    常常共用 pgid 1）一起带走——M48 之前 `test (ubuntu-latest)` 就是这么被 SIGTERM 打断的。
+//!    验不过就只发单 pid。
+//! 2. **`--` 不能省**：procps-ng 的 `kill` 会把裸 `-` 当成又一个信号选项吞掉，**退出码 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` 轮询），本模块只提供发送动作。
+//!
+//! # 送达即登记（D10）
+//!
+//! 每次信号**真的送达**都记进 [`crate::launch::kill_registry`]，退出分析据此把结局判成
+//! 「被终止」而不是「应用错误」。登记放在这一层，是因为所有结束路径都经过这里
+//! （`RunningProcess::stop` / GUI 的 `host::launch::stop` / 看门狗兜底），调用点不必各记一遍。
+
+use std::io;
+
+use crate::platform::child::quiet;
+
+/// 温和关闭（Windows 无 `/F`；POSIX `SIGTERM`）。
+pub fn terminate(pid: u32) -> io::Result<()> {
+    check_pid(pid)?;
+    signal_and_note(pid, false)
+}
+
+/// 强制关闭（Windows `/F`；POSIX `SIGKILL`），并尽量覆盖整棵进程树。
+pub fn force_kill(pid: u32) -> io::Result<()> {
+    check_pid(pid)?;
+    signal_and_note(pid, true)
+}
+
+/// 发信号，**送达后**登记「这个 pid 是我们结束的」（D10）。
+///
+/// 只在送达时登记：`taskkill` 对已退出的进程返回非 0、POSIX 的 `kill` 会报「没有送达」，
+/// 那两种情况说明它自己先走了——不能把自然退出洗成「被结束」。
+fn signal_and_note(pid: u32, force: bool) -> io::Result<()> {
+    let result = imp::signal(pid, force);
+    if result.is_ok() {
+        crate::launch::kill_registry::note(pid);
+    }
+    result
+}
+
+/// 三段式：温和 → 宽限 → 强制。返回**强制阶段**的结果（温和阶段失败不致命）。
+///
+/// 注意：返回值不代表“进程已经死了”（见模块注释）。需要准确判定请用
+/// [`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`）——否则 `-` 指的不是“它的”子树；
+/// 2. 必须能读到我们自己所在的进程组；
+/// 3. 目标组不能就是我们所在的组——否则信号会打到自己人身上。
+#[cfg(unix)]
+pub fn group_kill_target(pid: u32) -> Option {
+    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 {
+    // `/proc//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 {
+    let output = quiet("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::*;
+
+    pub(super) fn signal(pid: u32, force: bool) -> io::Result<()> {
+        // `CREATE_NO_WINDOW` 由 `platform::child::quiet` 统一带（否则 kill 子进程会闪一个黑框）。
+        let mut command = quiet("taskkill");
+        command.arg("/PID").arg(pid.to_string()).arg("/T");
+        if force {
+            command.arg("/F");
+        }
+        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  `，返回是否送达。
+    ///
+    /// `kill` 不存在时给**明确**错误而不是静默失败：否则调用方只会看到“进程仍在运行”，
+    /// 排查方向会被带偏（M48 之前的红灯就是这么来的）。
+    fn run_kill(flag: &str, args: &[&str]) -> io::Result {
+        match quiet("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,
+        /// 等待了多久。
+        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..fa6ce2d
--- /dev/null
+++ b/crates/core/src/launch/window_detect.rs
@@ -0,0 +1,152 @@
+//! “游戏窗口是否出现”的检测（日志启发式）。
+//!
+//! 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"),
+];
+
+/// 关闭标记的模式表（小写子串 → 名称）。
+///
+/// 游戏**自己说要退出**时会打这几行；之后进程还不退，就是卡在关闭（D6 的实机形态：
+/// 1.12.2 关窗后 `java.exe` 仍在跑）。表要保守——宁少判，不要把正常日志当关闭信号。
+pub const SHUTDOWN_MARKERS: &[(&str, &str)] = &[
+    ("stopping!", "stopping"),
+    ("stopping render thread", "render_thread"),
+    ("stopping worker threads", "worker_threads"),
+];
+
+/// 命中关闭标记时返回启发式名称。
+#[must_use]
+pub fn shutdown_marker(line: &str) -> Option<&'static str> {
+    let lower = line.to_ascii_lowercase();
+    SHUTDOWN_MARKERS
+        .iter()
+        .find(|(needle, _)| lower.contains(needle))
+        .map(|(_, name)| *name)
+}
+
+/// 窗口检测器。
+#[derive(Debug, Clone)]
+pub struct WindowDetector {
+    started_at: Instant,
+    detection: Option,
+}
+
+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 {
+        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()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{shutdown_marker, WindowDetector};
+
+    #[test]
+    fn window_heuristics_are_case_insensitive_and_reported_once() {
+        let mut detector = WindowDetector::new();
+        assert!(detector
+            .observe("[12:00:00] [main/INFO]: nothing here")
+            .is_none());
+        let detection = detector
+            .observe("[12:00:01] [main/INFO]: LWJGL Version: 3.3.1")
+            .expect("应命中窗口启发式");
+        assert_eq!(detection.heuristic, "lwjgl_version");
+        assert!(detector.is_detected());
+        assert!(
+            detector.observe("LWJGL Version again").is_none(),
+            "只报一次"
+        );
+    }
+
+    #[test]
+    fn shutdown_markers_cover_both_log_generations() {
+        // 1.12.2：`[Client thread/INFO] [minecraft/Minecraft]: Stopping!`
+        assert_eq!(
+            shutdown_marker("[Client thread/INFO]: Stopping!"),
+            Some("stopping")
+        );
+        // 1.20+：渲染线程与工作线程各自打印。
+        assert_eq!(
+            shutdown_marker("[Render thread/INFO]: Stopping render thread"),
+            Some("render_thread")
+        );
+        assert_eq!(
+            shutdown_marker("[Worker-Main-1/INFO]: Stopping worker threads"),
+            Some("worker_threads")
+        );
+        // 普通日志不能被当成关闭信号。
+        assert_eq!(
+            shutdown_marker("[main/INFO]: Started serving on 25565"),
+            None
+        );
+        assert_eq!(shutdown_marker("Stopping server is not our business"), None);
+    }
+}
diff --git a/crates/core/src/lib.rs b/crates/core/src/lib.rs
new file mode 100644
index 0000000..626b99d
--- /dev/null
+++ b/crates/core/src/lib.rs
@@ -0,0 +1,25 @@
+//! 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;
+pub mod update;
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>> {
+    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-`）。
+#[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/child.rs b/crates/core/src/platform/child.rs
new file mode 100644
index 0000000..852f9cd
--- /dev/null
+++ b/crates/core/src/platform/child.rs
@@ -0,0 +1,65 @@
+//! 子进程构造器：本 crate 里**唯一**允许直接 `std::process::Command::new` 的地方（M213）。
+//!
+//! ## 为什么需要它（这不是风格问题，是窗口问题）
+//!
+//! Windows 上「某个子进程要不要一块控制台」由**创建者的可执行文件类型**决定：一个**自己没有
+//! 控制台**的进程（GUI 程序的 PE Subsystem = 2；本仓库的 `unlucky-launcher.exe` 就是，M196 已改）
+//! 去 spawn 一个**控制台程序**（`java.exe` / `reg.exe` / `tzutil.exe` / `cmd.exe` /
+//! `powershell.exe` …）时，Windows 会为这个子进程**新建一块控制台**——桌面上看到的就是
+//! 「黑框闪一下」。所以探 N 个 JDK 就闪 N 次 `java -version`，用户的原话是「疯狂闪」。
+//!
+//! 抑制手段只有一个：创建时带 `CREATE_NO_WINDOW`（`0x0800_0000`）。
+//! **`Stdio::null()` 不管这件事**——它只把子进程的 stdout/stderr 指到空设备，控制台窗口照样会被
+//! 创建。所以到处补 `.stdout(Stdio::null())` 是无效修法。
+//!
+//! ## 谁**不许**走这里
+//!
+//! **游戏进程**（[`crate::launch::process::RunningProcess::spawn`]）保留自己的
+//! `CREATE_NEW_PROCESS_GROUP`（`0x0000_0200`），以便 `taskkill /T` 递归回收整棵进程树。
+//!
+//! 这两个 flag 在 **Win32 层是可以任意组合的**：[Process Creation Flags][flags] 原文
+//! 「They can be specified in any combination, except as noted」，而两条各自 not 掉的只有
+//! `CREATE_NEW_CONSOLE` / `DETACHED_PROCESS`，与这一组无关。真正的坑在 **Rust std 这一层**：
+//! `CommandExt::creation_flags` 是 **setter 不是累加器**——「先 `quiet()` 再
+//! `.creation_flags(CREATE_NEW_PROCESS_GROUP)`」会把 `CREATE_NO_WINDOW` **静默覆盖掉**。
+//!
+//! 而「游戏要不要带自己的控制台窗口」是**产品决定**（玩家要看游戏自己那段输出），不是顺手
+//! 抑制的事——所以这里不复用 `quiet`，显式只设 group flag，M213 一个字没动它。
+//!
+//! 那边是唯一另一处合法的直接构造点，两处都由 `crates/core/tests/child_quiet.rs` 的守卫钉住。
+//!
+//! [flags]: https://learn.microsoft.com/windows/win32/procthread/process-creation-flags
+
+use std::ffi::OsStr;
+use std::process::Command;
+
+/// `CREATE_NO_WINDOW`：子进程不获得控制台窗口。
+///
+/// 见 。
+/// 别和 `CREATE_NEW_CONSOLE`（`0x0000_0010`，意思正好相反）或
+/// `DETACHED_PROCESS`（`0x0000_0008`，子进程不继承父控制台、也不新建；标准句柄由
+/// `STARTUPINFO` 给，给了照样可用）搞混。
+#[cfg(windows)]
+const CREATE_NO_WINDOW: u32 = 0x0800_0000;
+
+/// 起一个**不该在桌面上留下窗口**的子进程。
+///
+/// - Windows：`.creation_flags(CREATE_NO_WINDOW)`；
+/// - 其它平台：原样返回，一个字不改（POSIX 没有「spawn 就新开一个终端」这回事，子进程的
+///   窗口从来不由我们造）。
+///
+/// 返回值就是普通 [`std::process::Command`]，调用方照旧 `.arg(..)` / `.env(..)` /
+/// `.output()` / `.status()`，或者整个交给 `game::java::proc::run_with_timeout` 去带超时跑。
+/// 本 crate 是 `#![forbid(unsafe_code)]`，而 `CommandExt::creation_flags` 是 std 的安全 API，
+/// 所以这里不需要任何 `unsafe`。
+#[must_use]
+pub fn quiet>(program: S) -> Command {
+    #[allow(unused_mut)]
+    let mut command = Command::new(program);
+    #[cfg(windows)]
+    {
+        use std::os::windows::process::CommandExt;
+        command.creation_flags(CREATE_NO_WINDOW);
+    }
+    command
+}
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 {
+        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,
+    /// 高级：显式覆盖启动器数据目录（`.ULL` 的等价物）。
+    pub launcher_home: Option,
+    /// 高级：游戏目录与数据目录分离指定（整合包用户：游戏在 D 盘，配置在用户目录）。
+    pub game_home: Option,
+}
+
+/// 解析结果：实际生效的两个 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,
+}
+
+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,
+    env: &'env dyn EnvSource,
+}
+
+impl Resolver<'static> {
+    /// 用真实进程环境构造。
+    #[must_use]
+    pub fn new(platform: Platform, exe_dir: Option) -> Self {
+        Self {
+            platform,
+            exe_dir,
+            env: &ProcessEnv,
+        }
+    }
+}
+
+impl<'env> Resolver<'env> {
+    /// 注入环境来源（测试 / 便携化封装）。
+    #[must_use]
+    pub fn with_env(
+        platform: Platform,
+        exe_dir: Option,
+        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 {
+        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,
+        })
+    }
+
+    /// 解析并跟随 `/redirect.json`（便携盘被搬走后旧目录不再自己长出新实例）。
+    ///
+    /// # Errors
+    /// 解析失败、指针损坏、跳转成环/超限时返回错误。
+    pub fn resolve_effective(
+        &self,
+        request: &DataDirRequest,
+        max_hops: usize,
+    ) -> PlatformResult {
+        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 {
+        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,
+}
+
+/// 迁移结果。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct DirMigrationOutcome {
+    /// 已搬的分区（按搬动顺序）。
+    pub moved: Vec,
+    /// 写入目标的收据。
+    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 {
+    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 {
+    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 = Result;
+
+/// 数据目录解析、文件系统原语、目录迁移可能出的问题。
+#[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>(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 {
+    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..bb05618
--- /dev/null
+++ b/crates/core/src/platform/layout.rs
@@ -0,0 +1,243 @@
+//! `.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";
+/// `logs/` 下的游戏会话目录名（事件流与 `index.jsonl`；M188）。
+pub const GAME_LOG_DIR: &str = "game";
+
+/// 全局设置文件名。
+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) -> 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/`。
+    #[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/.json`。
+    ///
+    /// # Errors
+    /// 实例 id 只允许 `[A-Za-z0-9_-]`（正常是稳定 UUID），否则返回
+    /// [`super::error::PlatformError::InvalidInstanceId`]，挡掉 `../` 穿越。
+    pub fn instance_config(&self, id: &str) -> PlatformResult {
+        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/
`——内容寻址缓存的两级分片（避开 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")
+    }
+
+    /// 会话根（M188 起 = `logs/`）。
+    ///
+    /// `launch::LauncherConfig` 在会话根下自己建 `game/`，所以「会话根」与「事件流目录」差一层：
+    /// 根是这里，真落点是 [`Self::game_logs`]。
+    #[must_use]
+    pub fn sessions_root(&self) -> PathBuf {
+        self.logs()
+    }
+
+    /// `logs/game/`——游戏会话事件流（`.jsonl`）与 `index.jsonl` 的真落点（M188）。
+    #[must_use]
+    pub fn game_logs(&self) -> PathBuf {
+        self.logs().join(GAME_LOG_DIR)
+    }
+
+    /// `data/agent/sessions/`——会话日志的**旧家**（M188 起只读兼容）。
+    ///
+    /// 目录名里的 `agent` 是历史遗留：它从来只装游戏会话，与 AI 无关。M188 把新会话挪到
+    /// `logs/game/`，这里**不搬不删**（用户的数据不该被偷偷移动），只是继续被读出来。
+    #[must_use]
+    pub fn agent_sessions(&self) -> PathBuf {
+        self.data().join("agent").join("sessions")
+    }
+
+    /// `/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..fe5c335
--- /dev/null
+++ b/crates/core/src/platform/linux_caps.rs
@@ -0,0 +1,224 @@
+//! 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,
+    /// 内核 release 原始串（`6.8.0-45-generic`），喂 `rules.os.version`。
+    pub kernel: Option,
+    /// 内核 `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) -> 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 {
+    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 {
+    let output = super::child::quiet(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..cb64bb4
--- /dev/null
+++ b/crates/core/src/platform/macos_version.rs
@@ -0,0 +1,99 @@
+//! 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 {
+    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 {
+    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::);
+    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 {
+    let output = super::child::quiet(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..c2ec8bd
--- /dev/null
+++ b/crates/core/src/platform/mod.rs
@@ -0,0 +1,54 @@
+//! 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。
+//! - [`child`]：子进程的唯一构造器 [`child::quiet`]（M213）。Windows 上给子进程带
+//!   `CREATE_NO_WINDOW`，否则 GUI 父进程 spawn 控制台程序会给子进程新建控制台——桌面上
+//!   就是「黑框闪一下」。**别在别处直接构造 `Command`**，`tests/child_quiet.rs` 守门。
+//! - [`opener`]：交出去的两件事——[`opener::open_url`]（授权码流）与 [`opener::open_dir`]
+//!   （实例详情页的「打开文件夹」，M235）。平台分支只在这里出现一次，业务模块一律调它。
+//!
+//! 尚未落地（后续 mission）：文件锁、进程工具、真实 GL/Vulkan 能力探测（钩子见
+//! [`linux_caps::probe_gl`] 与 [`vk_probe::probe_vk`]，FFI 受限，实际探测归 app 层渲染后端选择）。
+
+pub mod atomic;
+pub mod child;
+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 opener;
+pub mod os_info;
+pub mod paths;
+pub mod receipt;
+pub mod redirect;
+pub mod termux;
+pub mod theme_probe;
+pub mod vk_probe;
+pub mod wallpaper;
+pub mod windows_version;
diff --git a/crates/core/src/platform/opener.rs b/crates/core/src/platform/opener.rs
new file mode 100644
index 0000000..d7f491c
--- /dev/null
+++ b/crates/core/src/platform/opener.rs
@@ -0,0 +1,220 @@
+//! 用**系统默认程序**打开一个 URL 或一个目录（M235）。
+//!
+//! # 为什么收敛到 `core::platform`
+//!
+//! `DevDocs/AGENTS.md` §6：平台差异判断收敛到 `core::platform`，不在各模块里散写
+//! `cfg(target_os)` 补丁。本文件里的两种"交出去"：
+//!
+//! | 目标 | 程序 | 谁在用 |
+//! |---|---|---|
+//! | 目录 | Windows `explorer` / macOS `open` / 其它 `xdg-open` | 实例详情页「打开文件夹」（`game::saves`，M235） |
+//! | URL（`http`/`https`） | Windows `rundll32 url.dll,FileProtocolHandler` / macOS `open` / 其它 `xdg-open` | 微软授权码流（**当前仍走** `presenter::host::opener`，见下） |
+//!
+//! `open_url` 放在这里是为了给 URL 通道一个归宿：它现在还在 `presenter::host::opener`，因为
+//! 把那份实现搬过来会同时改到 `crates/core/tests/child_quiet_guard.rs` 的角色登记（M217 把
+//! 那个文件钉在"裸构造 1 处"，不在 M235 的改动范围），所以本 mission **只搬目录这一支**，
+//! 迁移 URL 那支留给后续（见 M235 的 handoff）。
+//!
+//! `app-iced/src/app/dialog/export.rs` 是第三处目录打开器（崩溃对话框的「打开日志文件夹」，
+//! M217 特意留裸）；它与这里的 `open_dir` 是同一件事，迁移同样留给后续。
+//!
+//! # 子进程纪律（M213 / M217）
+//!
+//! 所有启动都经 [`child::quiet`]：Windows 上带 `CREATE_NO_WINDOW`，否则 GUI 父进程 spawn
+//! 控制台程序会给子进程新建控制台（桌面上是"黑框闪一下"）。本文件是本 crate 里**唯一**出现
+//! `explorer` / `xdg-open` / `open` 这三个字面量的地方，[`tests::the_launcher_literals_live_here_only`]
+//! 扫源码钉住这一条（防"有人又在某个业务模块里塞一个平台分支"）。
+//!
+//! # 不等待、不判退出码
+//!
+//! 打开浏览器/文件管理器是**把意图交出去**：用户可能在那边停留很久，`explorer.exe` 即便成功
+//! 也常返回非 0 退出码。所以这里只 `spawn` 不 `wait`，`Ok(())` 的含义是「拉起来了」。
+
+use std::path::Path;
+
+use super::child::quiet;
+
+/// 拉起系统默认浏览器打开 `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) = url_launcher(url);
+    launch(program, args)
+}
+
+/// 用系统文件管理器打开一个**已存在的目录**。
+///
+/// 先确认它真是一个目录：拿一个不存在的路径去问 `explorer` 会得到一个"我的电脑"窗口或一句
+/// OS 报错，两种都不是用户想要的答案——所以在这里就说清楚。
+///
+/// # Errors
+///
+/// 路径不存在 / 不是目录 / 进程拉不起来时返回用户可读文案（含 OS 原文）。
+pub fn open_dir(dir: &Path) -> Result<(), String> {
+    let meta = std::fs::metadata(dir)
+        .map_err(|error| format!("找不到目录（{}）：{error}", dir.display()))?;
+    if !meta.is_dir() {
+        return Err(format!("不是目录（{}）", dir.display()));
+    }
+    let (program, args) = dir_launcher(dir);
+    launch(program, args)
+}
+
+/// 真去拉进程（两个入口共用）。
+fn launch(program: &'static str, args: Vec) -> Result<(), String> {
+    quiet(program)
+        .args(args)
+        .spawn()
+        .map(|_child| ())
+        .map_err(|error| format!("拉起失败（{program}）：{error}"))
+}
+
+/// 打开 URL 的程序与参数。
+#[cfg(target_os = "windows")]
+fn url_launcher(url: &str) -> (&'static str, Vec) {
+    // `rundll32` 不用 shell，URL 里的 `&` 不会被当成命令分隔符（`cmd /C start` 会）。
+    (
+        "rundll32",
+        vec!["url.dll,FileProtocolHandler".into(), url.into()],
+    )
+}
+
+#[cfg(target_os = "macos")]
+fn url_launcher(url: &str) -> (&'static str, Vec) {
+    ("open", vec![url.into()])
+}
+
+#[cfg(not(any(target_os = "windows", target_os = "macos")))]
+fn url_launcher(url: &str) -> (&'static str, Vec) {
+    ("xdg-open", vec![url.into()])
+}
+
+/// 打开目录的程序与参数。
+#[cfg(target_os = "windows")]
+fn dir_launcher(dir: &Path) -> (&'static str, Vec) {
+    // `explorer` 吃的是**一个**路径参数；别拼引号（它不是 shell，引号会变成名字的一部分）。
+    ("explorer", vec![dir.as_os_str().to_os_string()])
+}
+
+#[cfg(target_os = "macos")]
+fn dir_launcher(dir: &Path) -> (&'static str, Vec) {
+    ("open", vec![dir.as_os_str().to_os_string()])
+}
+
+#[cfg(not(any(target_os = "windows", target_os = "macos")))]
+fn dir_launcher(dir: &Path) -> (&'static str, Vec) {
+    ("xdg-open", vec![dir.as_os_str().to_os_string()])
+}
+
+#[cfg(test)]
+mod tests {
+    use std::path::PathBuf;
+
+    use super::{dir_launcher, open_dir, open_url, url_launcher};
+
+    /// URL 通道只收 http/https（不在单测里真去拉浏览器，只验命令形态）。
+    #[test]
+    fn rejects_non_http_urls() {
+        assert!(open_url("javascript:alert(1)").is_err());
+        assert!(open_url("").is_err());
+        let (program, args) = url_launcher("http://localhost:1234/auth?code=a&state=b");
+        assert!(!program.is_empty());
+        assert!(args
+            .iter()
+            .any(|arg| arg.to_string_lossy().contains("http://localhost:1234/auth")));
+    }
+
+    #[cfg(target_os = "windows")]
+    #[test]
+    fn windows_opens_urls_through_the_file_protocol_handler() {
+        let (program, args) = url_launcher("https://example.invalid/");
+        assert_eq!(program, "rundll32");
+        assert_eq!(args[0], "url.dll,FileProtocolHandler");
+        assert_eq!(args[1], "https://example.invalid/");
+    }
+
+    /// 目录通道：不存在的路径直接拒（**不 spawn**，否则会弹出"我的电脑"或一句 OS 报错）。
+    #[test]
+    fn missing_dirs_are_rejected_before_spawning() {
+        let gone = PathBuf::from("ull-no-such-dir-m235/definitely-missing");
+        let error = open_dir(&gone).expect_err("不存在的目录居然打开了？");
+        assert!(error.contains("找不到目录"), "错误文案：{error}");
+
+        // 存在但不是目录（用一个文件）也要拒。
+        let file = std::env::temp_dir().join(format!("ull-opener-m235-{}", std::process::id()));
+        std::fs::write(&file, b"x").expect("写临时文件");
+        let error = open_dir(&file).expect_err("文件居然被当目录打开了？");
+        let _ = std::fs::remove_file(&file);
+        assert!(error.contains("不是目录"), "错误文案：{error}");
+    }
+
+    /// 目录通道的命令形态（各平台一支，只验"程序名 + 一个路径参数"，不 spawn）。
+    #[test]
+    fn dir_launcher_passes_the_path_as_a_single_argument() {
+        let (program, args) = dir_launcher(&PathBuf::from("D:/ULL/.ULL/data/instances/x/saves"));
+        assert!(!program.is_empty());
+        assert_eq!(args.len(), 1, "路径必须是**一个**参数：{args:?}");
+        assert_eq!(
+            args[0].to_string_lossy().replace('\\', "/"),
+            "D:/ULL/.ULL/data/instances/x/saves"
+        );
+        if cfg!(target_os = "windows") {
+            assert_eq!(program, "explorer");
+        } else if cfg!(target_os = "macos") {
+            assert_eq!(program, "open");
+        } else {
+            assert_eq!(program, "xdg-open");
+        }
+    }
+
+    /// **防退化判据**（`AGENTS.md` §6）：`explorer` / `xdg-open` 这两个字面量只许出现在本文件。
+    ///
+    /// 抓得住：有人在 `game::saves` 或别的业务模块里再写一份平台分支（tower 在 M235 明确要求
+    /// 把这条写成可执行判据，而不是只写在提交信息里）。
+    /// 抓不住：经由变量间接拼出的程序名、以及本 crate 之外的 crate（presenter/app 侧另有
+    /// `tests/child_quiet_guard.rs` 管"是否经 `quiet` 起进程"，不管"在哪儿起"）。
+    #[test]
+    fn the_launcher_literals_live_here_only() {
+        let root = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("src");
+        let mut hits = Vec::new();
+        let mut stack = vec![root.clone()];
+        while let Some(dir) = stack.pop() {
+            let Ok(read) = std::fs::read_dir(&dir) else {
+                continue;
+            };
+            for entry in read.flatten() {
+                let path = entry.path();
+                if path.is_dir() {
+                    stack.push(path);
+                    continue;
+                }
+                if path.extension().and_then(|ext| ext.to_str()) != Some("rs") {
+                    continue;
+                }
+                if path == root.join("platform").join("opener.rs") {
+                    continue;
+                }
+                let Ok(text) = std::fs::read_to_string(&path) else {
+                    continue;
+                };
+                for (index, line) in text.lines().enumerate() {
+                    // 注释里提到这两个名字（文档、handoff）不算退化。
+                    let code = line.split("//").next().unwrap_or("");
+                    if code.contains("\"explorer\"") || code.contains("\"xdg-open\"") {
+                        hits.push(format!("{}:{}", path.display(), index + 1));
+                    }
+                }
+            }
+        }
+        assert!(
+            hits.is_empty(),
+            "平台 opener 必须只在 platform/opener.rs 里：{}",
+            hits.join(", ")
+        );
+    }
+}
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,
+    /// 展示名（`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) -> 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,
+    product: Option,
+    version_string: Option,
+    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 = 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;
+}
+
+/// 真实进程环境。
+#[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 {
+        std::env::var(name)
+            .ok()
+            .filter(|value| !value.trim().is_empty())
+    }
+}
+
+/// 固定环境（测试 / 便携化封装用）。
+#[derive(Debug, Clone, Default)]
+pub struct MapEnv {
+    vars: BTreeMap,
+}
+
+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 {
+        self.vars.get(name).cloned()
+    }
+}
+
+/// 用户主目录。
+#[must_use]
+pub fn home_dir(env: &dyn EnvSource) -> Option {
+    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 {
+    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 {
+    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 {
+    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 {
+    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 {
+    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,
+        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> {
+    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> {
+    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,
+}
+
+/// `/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> {
+    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 {
+    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 {
+    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> {
+    let mut current = dir.to_path_buf();
+    let mut visited: BTreeSet = BTreeSet::new();
+    visited.insert(current.clone());
+    let mut hops = 0usize;
+
+    loop {
+        let Some(pointer) = read(¤t)? 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/termux.rs b/crates/core/src/platform/termux.rs
new file mode 100644
index 0000000..71095ce
--- /dev/null
+++ b/crates/core/src/platform/termux.rs
@@ -0,0 +1,82 @@
+//! Termux（Android 上的用户空间）宿主识别。
+//!
+//! Termux 的软件前缀不在 `/usr`，而是 `$PREFIX`（典型值
+//! `/data/data/com.termux/files/usr`）；JDK 由 `pkg install openjdk-17` 落到
+//! `$PREFIX/lib/jvm/java-17-openjdk`。这里只做**识别与路径推导**，不碰包管理，
+//! 也不把 `$PREFIX` 当成编译期常量写死。
+
+use std::path::PathBuf;
+
+use super::paths::EnvSource;
+
+/// Termux 的默认前缀（`PREFIX` 缺失时的兜底）。
+pub const DEFAULT_PREFIX: &str = "/data/data/com.termux/files/usr";
+
+/// 当前环境是否运行在 Termux 里。
+///
+/// 判据取 Termux 自己导出的两个变量：`TERMUX_VERSION`（版本）或 `PREFIX`
+/// 指向默认前缀。两者都没有时按普通 Linux 处理——不猜。
+#[must_use]
+pub fn is_termux(env: &dyn EnvSource) -> bool {
+    env.var("TERMUX_VERSION").is_some()
+        || env
+            .var("PREFIX")
+            .is_some_and(|prefix| prefix.trim_end_matches('/') == DEFAULT_PREFIX)
+}
+
+/// Termux 的软件前缀（仅当识别为 Termux 时）。
+#[must_use]
+pub fn prefix(env: &dyn EnvSource) -> Option {
+    if !is_termux(env) {
+        return None;
+    }
+    Some(
+        env.var("PREFIX")
+            .map_or_else(|| PathBuf::from(DEFAULT_PREFIX), PathBuf::from),
+    )
+}
+
+/// Termux 的 JDK 安装根（`$PREFIX/lib/jvm`）。
+#[must_use]
+pub fn jvm_root(env: &dyn EnvSource) -> Option {
+    prefix(env).map(|prefix| prefix.join("lib").join("jvm"))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{is_termux, jvm_root, prefix, DEFAULT_PREFIX};
+    use crate::platform::paths::MapEnv;
+
+    #[test]
+    fn plain_linux_is_not_termux() {
+        let env = MapEnv::new().with("HOME", "/home/u");
+        assert!(!is_termux(&env));
+        assert_eq!(prefix(&env), None);
+        assert_eq!(jvm_root(&env), None);
+    }
+
+    #[test]
+    fn default_prefix_is_recognised() {
+        let env = MapEnv::new().with("PREFIX", DEFAULT_PREFIX);
+        assert!(is_termux(&env));
+        assert_eq!(
+            jvm_root(&env).unwrap(),
+            std::path::PathBuf::from(DEFAULT_PREFIX).join("lib/jvm")
+        );
+    }
+
+    #[test]
+    fn version_variable_alone_is_enough() {
+        let env = MapEnv::new()
+            .with("TERMUX_VERSION", "0.118.3")
+            .with("PREFIX", "/data/data/com.termux/files/usr");
+        assert!(is_termux(&env));
+    }
+
+    #[test]
+    fn other_prefix_is_not_termux() {
+        // `PREFIX` 被搬到别的目录不在识别范围内——只有版本变量或默认前缀算数。
+        let env = MapEnv::new().with("PREFIX", "/opt/termux");
+        assert!(!is_termux(&env));
+    }
+}
diff --git a/crates/core/src/platform/theme_probe.rs b/crates/core/src/platform/theme_probe.rs
new file mode 100644
index 0000000..5a8b62a
--- /dev/null
+++ b/crates/core/src/platform/theme_probe.rs
@@ -0,0 +1,181 @@
+//! 系统主题（浅色/深色）探测：给主题三态的 `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 {
+        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 {
+    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 {
+    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 {
+    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 {
+    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 {
+    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 {
+    let output = super::child::quiet(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..10581ea
--- /dev/null
+++ b/crates/core/src/platform/vk_probe.rs
@@ -0,0 +1,304 @@
+//! 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 {
+    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) -> Option {
+    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 {
+    let output = super::child::quiet(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,
+    notes: Vec,
+}
+
+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 {
+        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 {
+        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,
+    notes: Vec,
+    seen: Vec,
+}
+
+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..70f9d47
--- /dev/null
+++ b/crates/core/src/platform/wallpaper/io.rs
@@ -0,0 +1,295 @@
+//! 壁纸探测要用的外部 IO：文件读取、文件头、目录列表、子进程，以及宿主根目录。
+//!
+//! 生产实现是 [`HostIo`]，测试实现是 `fake::FakeIo`（固定夹具，不碰真机壁纸）。
+//! 这一层的存在只为把「外部世界」变成注入参数，不含任何平台判断。
+
+use std::path::{Path, PathBuf};
+
+use crate::platform::child::quiet;
+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;
+
+    /// 读文件头最多 `limit` 字节（图片魔数嗅探用；不存在或读不了返回 `None`）。
+    fn read_head(&self, path: &Path, limit: usize) -> Option>;
+
+    /// 列出目录里的**文件**（非递归、不排序；目录不存在返回空列表）。排序由调用方做。
+    fn list_dir(&self, dir: &Path) -> Vec;
+
+    /// 跑一个外部命令取 stdout（命令缺失 / 非零退出 / 空输出都返回 `None`）。
+    fn run(&self, program: &str, args: &[&str]) -> Option;
+}
+
+/// 真实宿主 IO。
+#[derive(Debug, Clone, Copy, Default)]
+pub struct HostIo;
+
+impl ProbeIo for HostIo {
+    fn read_text(&self, path: &Path) -> Option {
+        let bytes = std::fs::read(path).ok()?;
+        Some(String::from_utf8_lossy(&bytes).into_owned())
+    }
+
+    fn read_head(&self, path: &Path, limit: usize) -> Option> {
+        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 {
+        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 {
+        let output = quiet(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,
+}
+
+impl HostRoots {
+    /// 从环境变量表推出根目录；连主目录都没有时返回 `None`（调用方记一条原因）。
+    ///
+    /// 顺序固定（`HOME` 优先于 `USERPROFILE`），**不按编译目标分支**：否则在 Windows 上
+    /// 跑 Linux 夹具时会被 `USERPROFILE` 抢走主目录，夹具就不再确定。
+    #[must_use]
+    pub fn from_env(env: &dyn EnvSource) -> Option {
+        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,
+        images: Vec,
+        dirs: BTreeMap>,
+        commands: BTreeMap,
+    }
+
+    impl FakeIo {
+        /// 空世界（一切探测都会失败）。
+        pub(crate) fn new() -> Self {
+            Self::default()
+        }
+
+        /// 登记一个文本文件（配置文件、`.theme`、plist、xml……）。
+        pub(crate) fn with_file(mut self, path: impl AsRef, 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) -> Self {
+            self.images.push(path.as_ref().to_path_buf());
+            self
+        }
+
+        /// 登记目录内容（按文件名给，路径拼在 `dir` 上）。
+        pub(crate) fn with_dir(mut self, dir: impl AsRef, 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 {
+            self.texts.get(path).cloned()
+        }
+
+        fn read_head(&self, path: &Path, limit: usize) -> Option> {
+            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 {
+            self.dirs.get(dir).cloned().unwrap_or_default()
+        }
+
+        fn run(&self, program: &str, args: &[&str]) -> Option {
+            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  bg `）；
+//! 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 {
+    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 {
+    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 {
+    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 {
+    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 {
+    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 {
+    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 {
+    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 {
+    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),
+                        "\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),
+                "\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(
+                "\n\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（`file:///…`）也可能是二进制 plist 的 lossy 文本
+/// （可读 ASCII 串之间夹着不可打印字节）。因此先按「可打印 ASCII 连续段」切，再在每段里认：
+///
+/// - 任意位置的 `file://` 开头；
+/// - 「段首 / 分隔符之后 / `~` 之后」的 `/` 开头（路径中间的 `/` 不算新起点，避免同一路径
+///   被切成好几段）。
+#[must_use]
+pub(super) fn scan_string_paths(text: &str) -> Vec {
+    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 {
+    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 {
+    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),
+        // 闭合标签 `` 里的那个斜杠不是路径。
+        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 序列化里的终止字符（`` 的尖括号、引号、实体）切掉。
+fn push_candidate(found: &mut Vec, 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!("\n\n{body}\n\n")
+    }
+
+    #[test]
+    fn store_index_hit_decodes_file_url() {
+        let io = FakeIo::new()
+            .with_file(
+                STORE_PATH,
+                &xml_plist("file:///Users/me/Pictures/my%20wall.heic"),
+            )
+            .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(
+                    "\n\
+                     file:///System/Library/Desktop Pictures/a.heic\n\
+                     /Users/me/Library/Application Support/com.apple.wallpaper/Store/b.heic\n\
+                     ",
+                ),
+            )
+            .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 = 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(
+            "Content\n/Users/me/a.png",
+        ));
+        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("~/Library/Desktop Pictures/a.heic");
+        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，外加头部出现 ` 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" Option {
+    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") {
+    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 = 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 {
+    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";
+    // 反斜杠原样：本常量经 `%LOCALAPPDATA%` 展开后要与 `CUSTOM_THEME`（反斜杠原文）拼出**同一个
+    // `PathBuf` 键**。写成 `C:/…` 会得到 `C:/Users/u/AppData/Local\Microsoft\…` 这种混合串——
+    // Windows 的 `Path` 把 `/` 与 `\` 都当分隔符，Linux 只认 `/`，于是同一份夹具在 Linux 上永远
+    // 查不到那个文件（M147 实测：CI 的 test(ubuntu) 就红在这条上）。
+    const LOCAL_APP_DATA: &str = r"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 {
+    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 {
+    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..3588ec3
--- /dev/null
+++ b/crates/core/src/platform/windows_version.rs
@@ -0,0 +1,214 @@
+//! 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 {
+    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 {
+    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 {
+    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 {
+    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 ` 的输出。
+///
+/// 形如 `    CurrentBuildNumber    REG_SZ    19045`；DWORD 值以 `0x..` 输出。
+pub fn parse_reg_query(text: &str) -> Option {
+    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 {
+    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 = digits
+        .split('.')
+        .take(3)
+        .map(str::parse)
+        .collect::>()
+        .ok()?;
+    match parts.as_slice() {
+        [major, minor, build] => Some(WindowsVersion::new(*major, *minor, *build)),
+        _ => None,
+    }
+}
+
+fn parse_number(value: &str) -> Option {
+    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 {
+    let output = super::child::quiet(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 {
+    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| 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 {
+    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 {
+    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..8db2dde
--- /dev/null
+++ b/crates/core/src/setting/catalog.rs
@@ -0,0 +1,206 @@
+//! 一份配置文件的键目录：[`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,
+}
+
+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
+    }
+
+    /// 一次登记一批键（M161：某个域的键表拆到自己的文件后，主表只留一行）。
+    ///
+    /// 重复键的断言与 [`Self::with`] 同源（`with` 负责），所以批量登记不会绕过那条守门。
+    #[must_use]
+    pub fn with_all(mut self, specs: impl IntoIterator) -> Self {
+        for spec in specs {
+            self = self.with(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 {
+        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,
+    /// 已废弃键的原始值：只供诊断/UI 提示，**永远不落盘**。
+    legacy: Map,
+    /// 废弃键（点分）清单。
+    legacy_keys: BTreeSet,
+    dirty: BTreeSet,
+    unknown: Map,
+    unknown_keys: BTreeSet,
+    preserve_schema: Option,
+}
+
+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) {
+        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 {
+        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 {
+        self.effective(key).and_then(Value::as_bool)
+    }
+
+    /// 生效整数。
+    #[must_use]
+    pub fn effective_i64(&self, key: &str) -> Option {
+        self.effective(key).and_then(Value::as_i64)
+    }
+
+    /// 生效浮点。
+    #[must_use]
+    pub fn effective_f64(&self, key: &str) -> Option {
+        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 {
+        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 {
+        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) {
+        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 {
+        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 = Result;
+
+/// 配置读写与迁移可能出的问题。
+#[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 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..54c563b
--- /dev/null
+++ b/crates/core/src/setting/instance_keys.rs
@@ -0,0 +1,251 @@
+//! `config/profiles.json` 与 `config/instances/.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": "",
+//!   "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/`」的语法糖，
+//!    派生实现归 `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"];
+/// `launch.graphicsBackend` 的允许值（`default` = 不下发 `--graphicsBackend`）。
+///
+/// 与 `crate::game::launch_overrides::GraphicsBackend::IDS` 必须是同一份集合——setting 层
+/// 不依赖 game 层（分层纪律），一致性由本文件的 `graphics_backends_match_the_game_layer` 固定。
+pub const GRAPHICS_BACKENDS: &[&str] = &["default", "opengl", "vulkan"];
+
+/// profiles.json 当前 schema 版本。
+#[must_use]
+pub fn profiles_version() -> SchemaVersion {
+    SchemaVersion::new(1, 0, 0)
+}
+
+/// instances/.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/.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/）",
+        ))
+        .with(SettingSpec::enumeration(
+            "isolation",
+            "inherit",
+            ISOLATION_OVERRIDES,
+            AiPolicy::sensitive(),
+            "实例隔离档位：inherit（跟随全局 instances.mode，不落盘）/ isolated（运行目录派生 versions/）/ shared（共用 .minecraft 根）/ custom（用 gameDir）",
+        ))
+        .with(SettingSpec::path(
+            "gameDir",
+            AiPolicy::sensitive(),
+            "自定义运行目录（仅 isolation=custom 生效）",
+        ))
+        .with(SettingSpec::enum_list(
+            "overrides",
+            OVERRIDE_KEYS,
+            AiPolicy::locked(),
+            "该实例覆盖了全局哪些设置键（enum 白名单，拼错即校验失败）",
+        ))
+        // M157：实例级启动参数（`launch` 段，五项全可选、逐项回落到全局）。
+        // 作者是 `game::install::instance::InstanceConfig`（serde 形状与这些路径逐键对应），
+        // 回落规则与生效值在 `game::launch_overrides`，拼装消费在 `launch::overrides`。
+        .with(SettingSpec::text(
+            "launch.jvmArgs",
+            "",
+            1024,
+            AiPolicy::sensitive(),
+            "实例级 JVM 参数（空白分隔、支持引号）；留空 = 只用全局 java.extra_args（两者叠加，实例优先）",
+        ))
+        .with(SettingSpec::text(
+            "launch.gameArgs",
+            "",
+            1024,
+            AiPolicy::audited(),
+            "实例级游戏参数（追加在命令行末段，可覆盖前面一切游戏参数）；留空 = 不追加",
+        ))
+        .with(SettingSpec::int(
+            "launch.memoryMb",
+            0,
+            (0, 65536),
+            AiPolicy::sensitive(),
+            "实例级最大堆（MiB）；0/缺键 = 跟随全局 java.default_memory_mb（有效区间 256~65536）",
+        ))
+        .with(SettingSpec::path(
+            "launch.javaPath",
+            AiPolicy::sensitive(),
+            "实例级 Java 可执行文件；留空 = 跟随全局 java.selected_path 再退到自动挑（托管 > JAVA_HOME > PATH）",
+        ))
+        .with(SettingSpec::enumeration(
+            "launch.graphicsBackend",
+            "default",
+            GRAPHICS_BACKENDS,
+            AiPolicy::audited(),
+            "图形后端：default（不下发）/ opengl / vulkan。只对 MC 26.2-snapshot-2+ 下发，老版本会被门槛拦下并给出诊断告警",
+        ))
+        .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/）的内容条目数（只探测，不迁移）",
+        ))
+        .with(SettingSpec::int(
+            "lastModeChange.probe.sharedSide",
+            0,
+            (0, 1_000_000_000),
+            AiPolicy::locked(),
+            "切换时共享侧（.minecraft 根）的内容条目数（只探测，不迁移）",
+        ))
+        .with(SettingSpec::bool(
+            "lastModeChange.warned",
+            false,
+            AiPolicy::locked(),
+            "该次切换的提示是否已展示过（保证切换后首次启动只提示一次）",
+        ))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// M157：图形后端词表**只有一份真相源**（`game::launch_overrides::GraphicsBackend`），
+    /// setting 层是它的白名单视图——两边脱节就是「写得进、读不出」或「UI 三态少一档」。
+    #[test]
+    fn graphics_backends_match_the_game_layer() {
+        use crate::game::launch_overrides::GraphicsBackend;
+        let mut setting: Vec<&str> = GRAPHICS_BACKENDS.to_vec();
+        let mut game: Vec<&str> = GraphicsBackend::IDS.to_vec();
+        setting.sort_unstable();
+        game.sort_unstable();
+        assert_eq!(setting, game, "setting 白名单与 game 层词表脱节了");
+        for id in GRAPHICS_BACKENDS {
+            assert!(
+                GraphicsBackend::parse(id).is_some(),
+                "`{id}` 在 game 层解析不出来"
+            );
+        }
+    }
+
+    /// 五项键真的进了实例 schema 白名单（且 `default` 之外的后端值被拒）。
+    #[test]
+    fn launch_section_keys_are_registered() {
+        let schema = instance_schema();
+        assert!(schema
+            .validate("launch.jvmArgs", &serde_json::json!("-XX:+UseG1GC"))
+            .is_ok());
+        assert!(schema
+            .validate("launch.gameArgs", &serde_json::json!("--fullscreen"))
+            .is_ok());
+        assert!(schema
+            .validate("launch.memoryMb", &serde_json::json!(4096))
+            .is_ok());
+        assert!(schema
+            .validate(
+                "launch.javaPath",
+                &serde_json::json!("D:/jdk21/bin/java.exe")
+            )
+            .is_ok());
+        assert!(schema
+            .validate("launch.graphicsBackend", &serde_json::json!("vulkan"))
+            .is_ok());
+        // 非法后端值：白名单外必须报错（手改文件绕不过校验）。
+        assert!(schema
+            .validate("launch.graphicsBackend", &serde_json::json!("vulkan2"))
+            .is_err());
+        // 越界内存：schema 层也拦。
+        assert!(schema
+            .validate("launch.memoryMb", &serde_json::json!(1_000_000))
+            .is_err());
+    }
+}
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, 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, 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, extra: &Map) {
+    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,
+    schema: &SettingSchema,
+    problems: &mut Vec,
+) -> Map {
+    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) -> BTreeSet {
+    fn walk(prefix: &str, node: &Map, out: &mut BTreeSet) {
+        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..7cba6a7
--- /dev/null
+++ b/crates/core/src/setting/keys.rs
@@ -0,0 +1,396 @@
+//! `config/launcher.json` 的键表（全局设置）。键名与默认值对齐 `04-data-and-config.md` §2-§3；
+//! 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：四家发行版，顺序即优先级）。与 `game::java::vendor::VENDOR_IDS`
+/// 必须同一份集合（setting 层不依赖 game 层），一致性由 `tests/setting/java_install_keys.rs` 守。
+pub const JDK_VENDORS: &[&str] = &["temurin", "oracle", "microsoft", "zulu", "termux"];
+
+/// 拆到各自文件的键域：中文字体 CDN（M168）/ 自更新（M161）/ 代理与 gh-proxy（M197）。
+/// 主表各留一行登记。
+pub mod font;
+pub mod proxy;
+pub mod update;
+
+/// 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 的外观下层三键（`window_opacity` / `titlebar_mode` / `palette_source`，M91）：
+/// 仍然只推 minor、不加迁移步骤——三者的出厂值正是「老文件没有这些键」时的等价物。
+/// `1.5.0` 登记 M116 的窗口圆角策略（`appearance.window_corner`，出厂 `system`）：纯增量。
+/// `1.6.0` 登记 M161 的「自更新」两键（见 [`update`]）：纯增量但带一步数据迁移
+/// （此前住在 `cache/update/prefs.json`，迁移见 [`super::update_prefs`]）。
+/// `1.7.0` 登记 M168 的中文字体下载地址覆盖键（`ui.font_cdn`，见 [`font`]）：纯增量、无迁移。
+/// `1.8.0` 登记 M197 的 gh-proxy 前缀覆盖键（`download.gh_proxy`）：同样纯增量——出厂值是空串，
+/// 语义正是「老文件没有这个键」时的行为（跟随内置镜像表的默认前缀）。
+///
+/// **旧读新（方向相反，措辞必须精确）**：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 而不是偷偷塞进旧版本的
+/// 原因：回退到旧版本会出现「设置改不动」，而原因只在 `$schema` 那一行里，不看版本号无从排查。
+#[must_use]
+pub fn launcher_version() -> SchemaVersion {
+    SchemaVersion::new(1, 8, 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",
+            crate::download::config::DEFAULT_MAX_CONCURRENCY as i64,
+            (1, crate::download::config::MAX_CONCURRENCY as i64),
+            AiPolicy::silent(),
+            "同时下载的文件数（1~64，出厂 8）。这是引擎真实持有的并发许可，不是展示值；越界或手改坏值按出厂值生效",
+        ))
+        .with(SettingSpec::int(
+            "download.retry_limit",
+            crate::download::config::DEFAULT_MAX_ATTEMPTS_PER_SOURCE as i64,
+            (0, crate::download::config::MAX_ATTEMPTS_PER_SOURCE as i64),
+            AiPolicy::silent(),
+            "单个下载源的最多尝试次数（含首次；出厂 3）。0 与 1 都等于「只试一次、不重试」——0 是旧版 GUI 提供过的档位，保留合法但不代表「不下载」。换源不受此限",
+        ))
+        .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（镜像优先）",
+        ))
+        // M197：代理与 gh-proxy 三键（`download.proxy_mode` / `proxy_url` / `gh_proxy`）搬到
+        // [`proxy`]——主表这一段的注释也一起搬过去，见那个模块的表格。
+        .with_all(proxy::specs())
+        .with(SettingSpec::path(
+            "java.selected_path",
+            AiPolicy::sensitive(),
+            "用户选定的 Java 可执行文件路径",
+        ))
+        .with(SettingSpec::bool(
+            "java.auto_install",
+            true,
+            AiPolicy::audited(),
+            // M197：这句会进 AI 工具的 JSON Schema `description`（`catalog.rs` 直接塞 `spec.doc`），
+            // 所以必须写**实现真做的事**：缺 Java 时在 Java 页标出推荐版本并可一键安装，
+            // 不会自己开始下载（是否下载由用户点「安装」决定）。
+            "缺 Java 时在 Java 页标出推荐版本并可一键安装；不会自动下载",
+        ))
+        // D23：托管 JDK 的落点三模式。语义在 `game::java::location`：
+        // 未设置（空串）→ 按 `core.data_mode` 派生（Portable 数据根 / Standard 系统目录）；
+        // 设置了 → 覆盖前两者，按 `/` 分层。
+        .with(SettingSpec::text(
+            "java.installRoot",
+            JAVA_INSTALL_ROOT_UNSET,
+            512,
+            AiPolicy::sensitive(),
+            "托管 JDK 的自定义安装根（留空 = 按数据目录模式：portable 进数据根、standard 进 %APPDATA%\\Java）；设置后覆盖两者，JDK 落在 /<发行方>/<版本>/",
+        ))
+        // 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（空 = 出厂品牌板；非空时只换 primary/secondary/tertiary 三族，中性表面与 error 保持基线；非法值不写盘，设置页给错行）",
+        ))
+        // 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(),
+            "启动器日志级别",
+        ))
+        .with_all(update::specs())
+        .with(font::cdn_spec())
+}
diff --git a/crates/core/src/setting/keys/font.rs b/crates/core/src/setting/keys/font.rs
new file mode 100644
index 0000000..6f3897c
--- /dev/null
+++ b/crates/core/src/setting/keys/font.rs
@@ -0,0 +1,59 @@
+//! 中文字体下载地址的覆盖键（M168：D28 后半「下载开源中文字体」）。
+//!
+//! 从 `keys.rs` 拆出（那边贴着 400 行硬线）：主表只留一行 `.with(font::cdn_spec())`。
+//!
+//! ## 为什么需要这个键
+//!
+//! 内置 pin（`unlucky_i18n::font::NOTO_SANS_SC`）把 URL 钉到了 jsDelivr 的一个 git commit 上
+//! ——那是**一个**出口。用户所在网络如果连不上它（或想走自建镜像 / 代理），要有办法换，否则
+//! 「自动下载中文字体」在某些网络上等于不存在。
+//!
+//! ## 为什么只换 URL，不换哈希
+//!
+//! 字体是**注册进渲染器的可执行内容**，不是一张图。这个键只允许改「从哪拿」，`sha256` 与字节数
+//! 仍取内置那一份：镜像给了别的内容 ⇒ 校验当场拒 ⇒ 降级回系统字体，并在设置页那一行说「镜像
+//! 内容校验不通过」。**宁可不下载，也不把没校验过的东西注册成字体。**
+//!
+//! 想让用户能换「整套字体」（换族、换子集）就得连哈希一起进配置——那是另一件事：现在的 pin 是
+//! 代码里的常量，改它要发版。理由是此刻只有一套官方子集，多条可写路径只会多一个「校验值和字体
+//! 对不上」的支持面。
+
+use crate::setting::spec::{AiPolicy, SettingSpec};
+
+/// `ui.font_cdn` 的登记项（走 [`SettingSpec::text`]：空串 = 用内置镜像）。
+#[must_use]
+pub fn cdn_spec() -> SettingSpec {
+    SettingSpec::text(
+        "ui.font_cdn",
+        "",
+        512,
+        AiPolicy::audited(),
+        "中文字体下载地址（空 = 内置国内可达镜像；填整条 https URL，内容必须与内置 sha256 一致）",
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    /// 默认值是空串（= 用内置镜像），且不是 `Path` 类型——空串对 `Path` 会被 schema 拒。
+    ///
+    /// 抓得住：有人把键改成 `SettingSpec::path(...)`（空串过不了校验 ⇒ 出厂配置自己就非法）。
+    #[test]
+    fn the_cdn_key_defaults_to_the_builtin_mirror() {
+        let spec = cdn_spec();
+        assert_eq!(spec.key, "ui.font_cdn");
+        assert_eq!(spec.default, json!(""));
+        assert!(
+            spec.kind.check(&json!("")).is_ok(),
+            "空串（= 内置镜像）必须过校验"
+        );
+        assert!(
+            spec.kind
+                .check(&json!("https://mirror.example/NotoSansSC.ttf"))
+                .is_ok(),
+            "一条 https URL 必须过校验"
+        );
+    }
+}
diff --git a/crates/core/src/setting/keys/proxy.rs b/crates/core/src/setting/keys/proxy.rs
new file mode 100644
index 0000000..c6b4924
--- /dev/null
+++ b/crates/core/src/setting/keys/proxy.rs
@@ -0,0 +1,96 @@
+//! 代理与 gh-proxy 三键（M197 从 `keys.rs` 拆出：那边正好贴着 400 行硬线）。
+//!
+//! 三个键是一件事的两层：前两个是 **HTTP 代理**（整条请求走代理），第三个是 **gh-proxy 前缀**
+//! （只把 GitHub 上的 URL 改写成 ``，其余流量直连）。放在一起是因为用户问的往往是
+//! 「我下不动 GitHub 怎么办」，答案要么在这三个里面、要么在镜像表里。
+//!
+//! | 键 | 语义 | 谁消费 |
+//! |---|---|---|
+//! | `download.proxy_mode` | `none` / `system` / `manual` | 引擎的 HTTP 客户端（`http::build_client`） |
+//! | `download.proxy_url` | manual 模式的代理地址 | 同上 |
+//! | `download.gh_proxy` | 空 = 跟随内置默认；`off` = 关；其它 = 覆盖前缀 | `app-iced` 的 JDK 下载作业（M197），其它下载走同一份 `region.json` |
+//!
+//! `download.gh_proxy` 的语义细节在 `core::download::region`：**空串不等于关**——空串是「没有
+//! 覆盖」，仍按地区判定与内置镜像表走（国内判成镜像优先时用 `gh-proxy.com`）。要关必须写 `off`，
+//! 因为「我不想用加速」和「我还没决定」是两件事。
+
+use crate::setting::spec::{AiPolicy, SettingSpec};
+
+use super::PROXY_MODES;
+
+/// 三个键的完整登记项（主表一行 `.with_all(proxy::specs())`）。
+#[must_use]
+pub fn specs() -> Vec {
+    vec![
+        SettingSpec::enumeration(
+            "download.proxy_mode",
+            "none",
+            PROXY_MODES,
+            AiPolicy::sensitive(),
+            "代理模式：none / system / manual",
+        ),
+        SettingSpec::text(
+            "download.proxy_url",
+            "",
+            512,
+            AiPolicy::sensitive(),
+            "manual 代理地址（如 http://127.0.0.1:7890）",
+        ),
+        // M197：gh-proxy 前缀的用户覆盖（任务书那句「（默认值可改）」的落点）。
+        SettingSpec::text(
+            "download.gh_proxy",
+            "",
+            256,
+            AiPolicy::sensitive(),
+            "GitHub 下载的加速前缀（gh-proxy）。留空 = 跟随内置默认（镜像表里的 gh-proxy.com，仅镜像优先/国内判定时启用）；填 off 关闭；填一个 URL 前缀则覆盖它",
+        ),
+    ]
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// 三个键都在、且**空串 ≠ 关**这条语义写在描述里（M197 复审要求它与行为一致）。
+    ///
+    /// 变异证明：把 `gh_proxy` 的描述改成「留空 = 关闭」⇒ 本用例红（实现里空串是「跟随内置默认」，
+    /// `downloads::engine::gh_proxy_from("")` 返回 `Builtin` 而不是 `Off`）。
+    #[test]
+    fn the_gh_proxy_description_says_empty_is_not_off() {
+        let specs = specs();
+        let ids: Vec<&str> = specs.iter().map(|spec| spec.key).collect();
+        assert_eq!(
+            ids,
+            vec![
+                "download.proxy_mode",
+                "download.proxy_url",
+                "download.gh_proxy"
+            ]
+        );
+        let gh = specs
+            .iter()
+            .find(|spec| spec.key == "download.gh_proxy")
+            .expect("gh_proxy 已登记");
+        assert!(gh.doc.contains("留空 = 跟随内置默认"), "{}", gh.doc);
+        assert!(gh.doc.contains("填 off 关闭"), "{}", gh.doc);
+    }
+
+    /// **`KEY_GH_PROXY` 与 schema 登记的绑定**（M205）：`download/config.rs` 那个常量是宿主读数用的
+    /// 唯一键名，本文件 `specs()` 里是 schema 的登记——两侧各写一个字符串，此前没有任何断言把它们
+    /// 绑在一起，常量被改名/写错时全绿，行为只在宿主侧静默退化成 `Builtin`（用户填的 `off` 被忽略）。
+    ///
+    /// 抓得住：常量值写错（如 `download.ghproxy`）⇒ 找不到登记项，第一句红；登记的 `max_len` 从 256
+    /// 改掉、或默认值从空串改成别的 ⇒ 各自红（类型/默认值是宿主的读侧契约）。
+    /// 抓不住：两侧**同时**改名（那是一次公开改名，本用例判断不了它对不对，只能保证两侧一致）。
+    #[test]
+    fn the_gh_proxy_key_is_bound_to_the_schema_registration() {
+        use crate::download::config::KEY_GH_PROXY;
+        use crate::setting::spec::ValueKind;
+
+        let Some(gh) = specs().into_iter().find(|spec| spec.key == KEY_GH_PROXY) else {
+            panic!("下载键常量 {KEY_GH_PROXY:?} 在 schema 里没有登记项（常量值与 specs() 的键名不一致）");
+        };
+        assert_eq!(gh.kind, ValueKind::Text { max_len: 256 }, "{}", gh.key);
+        assert_eq!(gh.default, serde_json::json!(""), "{}", gh.key);
+    }
+}
diff --git a/crates/core/src/setting/keys/update.rs b/crates/core/src/setting/keys/update.rs
new file mode 100644
index 0000000..92be9dd
--- /dev/null
+++ b/crates/core/src/setting/keys/update.rs
@@ -0,0 +1,39 @@
+//! 自更新两键（M161：从更新域自己的 `cache/update/prefs.json` 迁进主配置）。
+//!
+//! 从 `keys.rs` 拆出（那边贴着 400 行硬线）：这两个键连同它们的允许值与理由一起搬，
+//! 主表只留一行 `.with(update::register(..))`。
+//!
+//! 为什么必须进 schema：`ull config get update.auto_check` 读的是**这一份**文件；域内文件对
+//! CLI 不可见（用户在 GUI 里关掉自动检查，CLI 永远报默认值 `true`）。存量迁移（幂等 + 收据）
+//! 在 [`crate::setting::update_prefs`]。
+
+use crate::setting::spec::{AiPolicy, SettingSpec};
+
+/// `update.channel` 允许值。
+///
+/// D50：先只发 stable。**加值必须与宿主层同步**——`presenter::host::update::Runtime` 现在真的
+/// 读这个键（`UpdateView::channel` 与检查用的渠道同源），但 core 的 `Job::check/apply` 仍按
+/// 传入的渠道准入，所以只有清单里真有那个渠道的发布时才该加值。现在写死一个值：用户
+/// `config set update.channel beta` 会被 schema **当面拒绝**，而不是写进文件后被静默忽略
+/// （那是更坏的谎）。
+pub const UPDATE_CHANNELS: &[&str] = &["stable"];
+
+/// 两个自更新键的完整登记项（主表一行 `.with_all(specs())`）。
+#[must_use]
+pub fn specs() -> Vec {
+    vec![
+        SettingSpec::bool(
+            "update.auto_check",
+            true,
+            AiPolicy::audited(),
+            "启动时静默检查更新（关掉之后启动一次网络都不发；发现新版本才弹提示条）",
+        ),
+        SettingSpec::enumeration(
+            "update.channel",
+            "stable",
+            UPDATE_CHANNELS,
+            AiPolicy::audited(),
+            "更新渠道（D50 先只发 stable；清单里没有的渠道不许写进文件）",
+        ),
+    ]
+}
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) -> 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>,
+}
+
+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) -> 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 {
+        self.steps.last().map(|step| step.to())
+    }
+
+    /// 从 `from` 起要执行的步骤（含 `from` 那一步）。
+    ///
+    /// # Errors
+    /// 链里没有以 `from` 开头的步骤（版本不认识）时返回 [`SettingError::ChainBroken`]。
+    pub fn plan_from(&self, from: SchemaVersion) -> SettingResult> {
+        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,
+    ) -> SettingResult {
+        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 {
+        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 {
+        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..9806b60
--- /dev/null
+++ b/crates/core/src/setting/mod.rs
@@ -0,0 +1,39 @@
+//! 配置与数据目录：三模式数据根（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/.json` 的键表；
+//! - [`appearance`]：D17「外观（高级）」键簇的取值快照与校验（主题三态 / 背景图 / 面板透明度 /
+//!   玻璃拟态 / 强调色）；
+//! - [`document`]：内存文档（点分键、脏字段、未知字段保留、默认值不落盘）；
+//! - [`store`]：单文件加载降级 + 原子保存 + 坏文件备份；
+//! - [`save`] / [`save_worker`]：200ms 去抖攒批与后台保存线程；
+//! - [`migrate`]：`schemaVersion N → N+1` 迁移链 + 收据闸门。
+//! - [`update_prefs`]：自更新偏好（旧 `cache/update/prefs.json`）→ `launcher.json` 的一次性迁移
+//!   （M161：幂等、源指纹闸门、旧文件退役、收据可查）。
+
+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;
+pub mod update_prefs;
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,
+    queued_at: Instant,
+}
+
+/// 按 key 去重的去抖队列：同一 key 的新内容覆盖旧内容，但**保留首次入队时间**
+/// （窗口从第一次改动开始算，避免连续改动把写盘无限推迟）。
+#[derive(Debug, Clone)]
+pub struct DebounceQueue {
+    debounce: Duration,
+    pending: BTreeMap,
+}
+
+impl DebounceQueue {
+    /// 新建一个去抖队列。
+    #[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>, 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 {
+        self.pending
+            .values()
+            .map(|pending| pending.queued_at + self.debounce)
+            .min()
+    }
+
+    /// 取出所有已过窗口的任务（按键排序，保证写盘顺序稳定）。
+    pub fn drain_due(&mut self, now: Instant) -> Vec<(K, Vec)> {
+        let due: Vec = 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)> {
+        let all: Vec = self.pending.keys().cloned().collect();
+        self.take(all)
+    }
+
+    fn take(&mut self, keys: Vec) -> Vec<(K, Vec)> {
+        keys.into_iter()
+            .filter_map(|key| {
+                self.pending
+                    .remove(&key)
+                    .map(|pending| (key, pending.payload))
+            })
+            .collect()
+    }
+}
+
+impl Default for DebounceQueue {
+    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 {
+    queue: DebounceQueue,
+    sink: S,
+}
+
+impl CoalescingWriter {
+    /// 组合去抖队列与 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, payload: impl Into>, 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 {
+        self.queue.next_due()
+    }
+
+    /// 写掉已过窗口的任务，返回写了几个文件。
+    ///
+    /// # Errors
+    /// sink 落盘失败时返回 [`super::error::SettingError`]。
+    pub fn flush_due(&mut self, now: Instant) -> SettingResult {
+        let jobs = self.queue.drain_due(now);
+        self.run(jobs)
+    }
+
+    /// 写掉全部任务（关停兜底），返回写了几个文件。
+    ///
+    /// # Errors
+    /// sink 落盘失败时返回 [`super::error::SettingError`]。
+    pub fn flush_all(&mut self) -> SettingResult {
+        let jobs = self.queue.drain_all();
+        self.run(jobs)
+    }
+
+    fn run(&mut self, jobs: Vec<(PathBuf, Vec)>) -> SettingResult {
+        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 = "";
+
+enum Command {
+    Queue { path: PathBuf, payload: Vec },
+    Flush(Sender>),
+    Shutdown(Sender>),
+}
+
+/// 后台保存线程句柄。
+#[derive(Debug)]
+pub struct SaveWorker {
+    tx: Option>,
+    handle: Option>,
+}
+
+impl SaveWorker {
+    /// 用默认 200ms 去抖窗口起线程。
+    ///
+    /// # Errors
+    /// 线程创建失败时返回 [`SettingError::Io`]。
+    pub fn spawn_default() -> SettingResult {
+        Self::spawn(DEFAULT_DEBOUNCE)
+    }
+
+    /// 用指定去抖窗口起线程。
+    ///
+    /// # Errors
+    /// 线程创建失败时返回 [`SettingError::Io`]。
+    pub fn spawn(debounce: Duration) -> SettingResult {
+        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,
+        payload: impl Into>,
+    ) -> 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, debounce: Duration) {
+    let mut writer = CoalescingWriter::new(AtomicSink, debounce);
+    let mut last_error: Option = 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, result: SettingResult) -> 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 {
+        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/.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::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 {
+        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,
+}
+
+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,
+    backup_on_next_save: bool,
+}
+
+impl SettingStore {
+    /// 加载（或首建）一个配置文件；永不失败，状态从 [`Self::access`] 读。
+    #[must_use]
+    pub fn load(path: impl Into, 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 {
+        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 {
+        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> {
+        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::(&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> {
+        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/src/setting/update_prefs.rs b/crates/core/src/setting/update_prefs.rs
new file mode 100644
index 0000000..2da1750
--- /dev/null
+++ b/crates/core/src/setting/update_prefs.rs
@@ -0,0 +1,303 @@
+//! 自更新偏好 `<数据根>/cache/update/prefs.json` → `<数据根>/config/launcher.json` 的迁移（M161）。
+//!
+//! # 为什么要有这一步
+//!
+//! M159 把「启动时静默检查」临时落在更新域自己的文件里（当时 `crates/core/src/setting/**`
+//! 不在那条 mission 的 scope）。后果是**同一个开关有两个真相源**：GUI 读写 `prefs.json`，
+//! 而 `ull config get update.auto_check` 读 `launcher.json`——用户在 GUI 里关掉自动检查，
+//! CLI 永远回答默认值 `true`。M161 把两个键（[`KEY_AUTO_CHECK`] / [`KEY_CHANNEL`]）登记进
+//! schema，本模块负责把**存量值**搬过去。
+//!
+//! # 四条硬约束（每条都有对应用例，见 `tests/setting/update_keys.rs`）
+//!
+//! 1. **幂等**：跑两次的第二遍什么都不做。判据不是「文件还在不在」（改名可能失败），而是
+//!    [`crate::platform::receipt`] 里的源指纹——同一份源文件内容只迁一次；
+//! 2. **不丢值**：旧文件里 `auto_check: false` 必须迁成 `false`。默认值是 `true`，所以
+//!    「用默认值兜底」会把用户的关闭状态**静默打开**——这是本条里最贵的一种错；
+//! 3. **新值胜出**：主配置里**已经有**这个键时绝不覆盖（用户可能在前一版 GUI 之后手改过
+//!    `launcher.json`，或者刚从 CLI 设过）。旧文件照样退役，但不写字；
+//! 4. **旧文件迁完不能再被读**：改名为 `prefs.json.migrated`（不删——留着是取证材料，
+//!    但不再有任何读路径，`Prefs::load` 已经从宿主层删掉）。
+//!
+//! 写不进去（只读/不可读的 `launcher.json`）时**不退役旧文件**：宁可下一次再试，
+//! 也不能让用户的值在两边都不存在。
+
+use std::path::{Path, PathBuf};
+
+use serde::Deserialize;
+use serde_json::json;
+
+use crate::platform::receipt::{self, MigrationReceipt};
+use crate::setting::document::SettingDocument;
+use crate::setting::keys::launcher_schema;
+use crate::setting::store::SettingStore;
+
+/// 主配置里的「启动时静默检查」键。
+pub const KEY_AUTO_CHECK: &str = "update.auto_check";
+/// 主配置里的「更新渠道」键。
+pub const KEY_CHANNEL: &str = "update.channel";
+/// 旧域内文件里的同义键（`serde` 的字段名，别改）。
+pub const LEGACY_AUTO_CHECK: &str = "auto_check";
+/// `update.auto_check` 的出厂值（与 `keys::launcher_schema` 里那份**必须一致**，契约用例守着）。
+pub const DEFAULT_AUTO_CHECK: bool = true;
+/// `update.channel` 的出厂值。
+pub const DEFAULT_CHANNEL: &str = "stable";
+/// 收据文件名（落在 `<数据根>/config/` 下；与数据目录迁移的 `migration-receipt.json` 分开）。
+pub const RECEIPT_FILE: &str = "update-prefs-migration.json";
+/// 旧文件退役后的后缀（`prefs.json` → `prefs.json.migrated`）。
+pub const RETIRED_SUFFIX: &str = "migrated";
+
+/// 迁移需要知道的三个路径（都由调用方按数据根算：core 不猜布局）。
+#[derive(Debug, Clone, Copy)]
+pub struct Targets<'a> {
+    /// `<数据根>/config/launcher.json`
+    pub launcher: &'a Path,
+    /// `<数据根>/cache/update/prefs.json`（旧域内文件）
+    pub legacy: &'a Path,
+    /// 收据落点（`<数据根>/config/update-prefs-migration.json`）
+    pub receipt: &'a Path,
+}
+
+/// 迁移结局（**每一种都要能被调用方如实转述**，不许折叠成 bool）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Migration {
+    /// 没有旧文件（绝大多数用户），或已经迁过（源指纹相同）。
+    Nothing,
+    /// 迁进去了：值来自旧文件。
+    Migrated {
+        /// 迁过去的取值
+        auto_check: bool,
+        /// 收据路径
+        receipt: PathBuf,
+        /// 退役后的旧文件路径
+        retired: PathBuf,
+    },
+    /// 主配置里已经有这个键 ⇒ 新值胜出，一个字都没写；旧文件照样退役。
+    NewValueWins {
+        /// 主配置里那个生效值
+        auto_check: bool,
+        /// 收据路径
+        receipt: PathBuf,
+        /// 退役后的旧文件路径
+        retired: PathBuf,
+    },
+    /// 旧文件读不出来（坏 JSON / 读失败）：**什么都不动**，旧文件原样留着等下一次。
+    Unreadable {
+        /// 旧文件路径
+        path: PathBuf,
+        /// 原因（人读）
+        reason: String,
+    },
+    /// 主配置写不进去：不退役旧文件（用户的值不能两边都没有）。
+    Refused {
+        /// 原因（人读）
+        reason: String,
+    },
+}
+
+impl Migration {
+    /// 有没有真的改动主配置或旧文件。
+    #[must_use]
+    pub const fn touched(&self) -> bool {
+        matches!(self, Self::Migrated { .. } | Self::NewValueWins { .. })
+    }
+
+    /// 收据路径（没写收据时为 `None`）。
+    #[must_use]
+    pub fn receipt(&self) -> Option<&Path> {
+        match self {
+            Self::Migrated { receipt, .. } | Self::NewValueWins { receipt, .. } => Some(receipt),
+            _ => None,
+        }
+    }
+
+    /// 稳定 id（日志 / CLI 输出 / 测试用；**不要改名**）。
+    #[must_use]
+    pub const fn as_str(&self) -> &'static str {
+        match self {
+            Self::Nothing => "nothing",
+            Self::Migrated { .. } => "migrated",
+            Self::NewValueWins { .. } => "new_value_wins",
+            Self::Unreadable { .. } => "unreadable",
+            Self::Refused { .. } => "refused",
+        }
+    }
+}
+
+/// 旧域内文件的结构（只有一个字段，但**保留 `serde(default)`**：
+/// 少了字段的旧文件按出厂值处理，而不是整个解析失败）。
+#[derive(Debug, Clone, Copy, Deserialize)]
+struct LegacyPrefs {
+    #[serde(default = "default_auto_check")]
+    auto_check: bool,
+}
+
+const fn default_auto_check() -> bool {
+    DEFAULT_AUTO_CHECK
+}
+
+/// 执行一次迁移（幂等）。
+///
+/// `now_ms` = 毫秒 since UNIX_EPOCH（注入便于断言收据内容）。
+#[must_use]
+pub fn migrate(targets: Targets<'_>, now_ms: u64) -> Migration {
+    let Ok(bytes) = std::fs::read(targets.legacy) else {
+        // 文件不在（或读不动=一样当没有）：绝大多数用户走这一支。
+        return Migration::Nothing;
+    };
+    let fingerprint = receipt::fingerprint_bytes(&bytes);
+
+    // ① 收据闸门：同一份源文件内容只迁一次。
+    if matches!(
+        receipt::read(targets.receipt),
+        Ok(Some(existing)) if existing.source_fingerprint == fingerprint
+    ) {
+        retire(targets.legacy);
+        return Migration::Nothing;
+    }
+
+    // ② 旧文件必须能解析：坏文件不猜（猜错就等于替用户关掉/打开自动检查）。
+    let legacy: LegacyPrefs = match serde_json::from_slice(&bytes) {
+        Ok(value) => value,
+        Err(error) => {
+            return Migration::Unreadable {
+                path: targets.legacy.to_path_buf(),
+                reason: error.to_string(),
+            }
+        }
+    };
+
+    let mut store = SettingStore::load(targets.launcher, launcher_schema());
+    if !store.access().can_save() {
+        return Migration::Refused {
+            reason: format!(
+                "主配置不可写（{}）：{}",
+                targets.launcher.display(),
+                store.access().as_str()
+            ),
+        };
+    }
+
+    // ③ 新值胜出：主配置里**显式**有这个键就不覆盖（`effective` 会兜默认值，用 `get`）。
+    let explicit = store
+        .doc()
+        .get(KEY_AUTO_CHECK)
+        .and_then(serde_json::Value::as_bool);
+
+    let outcome = if let Some(current) = explicit {
+        Migration::NewValueWins {
+            auto_check: current,
+            receipt: targets.receipt.to_path_buf(),
+            retired: retired_path(targets.legacy),
+        }
+    } else {
+        // ④ 只在**非出厂值**时写盘：出厂值（`true`）不落盘是 `document` 的既定语义
+        //    （「默认值不落盘」），写进去只是给文件添一行噪音。`false` 必须写。
+        if legacy.auto_check != DEFAULT_AUTO_CHECK {
+            if let Err(error) = store.set(KEY_AUTO_CHECK, json!(legacy.auto_check)) {
+                return Migration::Refused {
+                    reason: format!("写 {KEY_AUTO_CHECK} 被拒：{error}"),
+                };
+            }
+            match store.save() {
+                Ok(saved) if saved.wrote() || !store.is_dirty() => {}
+                Ok(saved) => {
+                    return Migration::Refused {
+                        reason: format!("主配置没落盘（{}）", format_save(&saved)),
+                    }
+                }
+                Err(error) => {
+                    return Migration::Refused {
+                        reason: format!("写主配置失败：{error}"),
+                    }
+                }
+            }
+        }
+        Migration::Migrated {
+            auto_check: legacy.auto_check,
+            receipt: targets.receipt.to_path_buf(),
+            retired: retired_path(targets.legacy),
+        }
+    };
+
+    // ⑤ 收据（写不成也不回滚主配置：值已经在主配置里生效了，收据丢了下一次会重跑一遍，
+    //    而重跑是幂等的——正如「新值胜出」那一支不会覆盖）。
+    let record = MigrationReceipt::legacy_config(
+        targets.legacy.to_path_buf(),
+        targets.launcher.to_path_buf(),
+        fingerprint,
+        now_ms,
+    );
+    let _ = receipt::write(targets.receipt, &record);
+
+    // ⑥ 旧文件退役（改名失败就留着：主配置已经是真相源，`prefs.json` 不再有读路径）。
+    retire(targets.legacy);
+    outcome
+}
+
+/// 退役后的路径（`prefs.json` → `prefs.json.migrated`）。
+#[must_use]
+pub fn retired_path(legacy: &Path) -> PathBuf {
+    let name = legacy
+        .file_name()
+        .map(|name| name.to_string_lossy().to_string())
+        .unwrap_or_else(|| "prefs.json".to_string());
+    legacy.with_file_name(format!("{name}.{RETIRED_SUFFIX}"))
+}
+
+/// 把旧文件改名成 `.migrated`（不存在 / 改不动都算成功：它不是真相源了）。
+fn retire(legacy: &Path) {
+    if legacy.exists() {
+        let _ = std::fs::rename(legacy, retired_path(legacy));
+    }
+}
+
+fn format_save(outcome: &crate::setting::store::SaveOutcome) -> String {
+    match outcome {
+        crate::setting::store::SaveOutcome::Saved(path) => format!("已写 {}", path.display()),
+        crate::setting::store::SaveOutcome::Skipped(reason) => reason.as_str().to_string(),
+    }
+}
+
+/// 「启动时静默检查」的生效值（**唯一**取值点：宿主层与 CLI 都从这里读）。
+#[must_use]
+pub fn auto_check(doc: &SettingDocument) -> bool {
+    doc.effective_bool(KEY_AUTO_CHECK)
+        .unwrap_or(DEFAULT_AUTO_CHECK)
+}
+
+/// 「更新渠道」的生效值（同上；空串/坏值都回出厂渠道）。
+#[must_use]
+pub fn channel(doc: &SettingDocument) -> &str {
+    doc.effective_str(KEY_CHANNEL)
+        .filter(|text| !text.trim().is_empty())
+        .unwrap_or(DEFAULT_CHANNEL)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn retired_name_keeps_the_original_stem() {
+        assert_eq!(
+            retired_path(Path::new("/data/cache/update/prefs.json")),
+            Path::new("/data/cache/update/prefs.json.migrated")
+        );
+    }
+
+    #[test]
+    fn defaults_agree_with_the_schema() {
+        // 契约：本文件里的常量与 `keys::launcher_schema()` 的默认值必须一致
+        // （两份字面量漂移 = 「迁过去的值」和「不迁时的值」不同）。
+        let schema = launcher_schema();
+        assert_eq!(
+            schema.spec(KEY_AUTO_CHECK).expect("键已登记").default,
+            json!(DEFAULT_AUTO_CHECK)
+        );
+        assert_eq!(
+            schema.spec(KEY_CHANNEL).expect("键已登记").default,
+            json!(DEFAULT_CHANNEL)
+        );
+    }
+}
diff --git a/crates/core/src/update/channel.rs b/crates/core/src/update/channel.rs
new file mode 100644
index 0000000..56c9142
--- /dev/null
+++ b/crates/core/src/update/channel.rs
@@ -0,0 +1,113 @@
+//! 更新渠道（通道）与准入规则。
+//!
+//! 四个渠道是一条**稳定度阶梯**，`Ord` 的派生顺序就是阶梯顺序
+//! （`Stable < Beta < Alpha < Nightly`），所以「本渠道收不收那份发布」只要一次比较：
+//! `manifest_channel <= requested_channel`。nightly 收全部，stable 只收 stable。
+//!
+//! 除了清单自报的渠道，还要看版本号里的预发布阶段（[`Stage`]）：清单可以撒谎
+//! （`channel: "stable"` 但版本是 `1.0.0-alpha.2`），阶段这条判据不信清单只信版本号本身。
+//! 两道判据**同时**成立才准入，见 [`Channel::admits`] 与 [`Channel::admits_stage`]。
+//!
+//! 准入阶梯（与渠道顺序同一套口径，别在别处另立一张表）：
+//!
+//! | 渠道 | 收正式版 | 收 rc | 收 beta | 收 alpha | 收认不出的预发布 |
+//! | ---- | -------- | ----- | ------- | -------- | ---------------- |
+//! | stable  | ✓ |   |   |   |   |
+//! | beta    | ✓ | ✓ |   |   |   |
+//! | alpha   | ✓ | ✓ | ✓ |   |   |
+//! | nightly | ✓ | ✓ | ✓ | ✓ | ✓ |
+
+use std::fmt;
+use std::str::FromStr;
+
+use super::error::{UpdateError, UpdateErrorKind};
+use super::version::Stage;
+
+/// 更新渠道。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub enum Channel {
+    /// 稳定版（默认渠道）。
+    Stable,
+    /// 公测版。
+    Beta,
+    /// 内测版。
+    Alpha,
+    /// 每日构建（收所有预发布，包括认不出的标识）。
+    Nightly,
+}
+
+impl Channel {
+    /// 全部渠道，从最稳到最激进。
+    pub const ALL: [Self; 4] = [Self::Stable, Self::Beta, Self::Alpha, Self::Nightly];
+
+    /// 清单文件名与日志用的稳定字符串 id（**不要改名**：清单里的 `channel` 字段就是它）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Stable => "stable",
+            Self::Beta => "beta",
+            Self::Alpha => "alpha",
+            Self::Nightly => "nightly",
+        }
+    }
+
+    /// 解析渠道名（大小写与首尾空白不敏感）。
+    ///
+    /// # Errors
+    ///
+    /// 认不出的名字返回 [`UpdateErrorKind::InvalidManifest`]（清单里的 `channel` 写错了）。
+    pub fn parse(text: &str) -> Result {
+        let name = text.trim().to_ascii_lowercase();
+        Self::ALL
+            .into_iter()
+            .find(|channel| channel.as_str() == name)
+            .ok_or_else(|| {
+                let allowed = Self::ALL
+                    .iter()
+                    .map(|channel| channel.as_str())
+                    .collect::>()
+                    .join(" / ");
+                UpdateError::new(
+                    UpdateErrorKind::InvalidManifest,
+                    format!("未知更新渠道 `{text}`（只认 {allowed}）"),
+                )
+            })
+    }
+
+    /// 本渠道是否接受「发布自报 `release` 渠道」的那份版本。
+    ///
+    /// 判定就是阶梯比较（`Ord` 的派生顺序即阶梯），不在别处另立一张表。
+    #[must_use]
+    pub fn admits(self, release: Self) -> bool {
+        release <= self
+    }
+
+    /// 本渠道是否接受该预发布阶段（正式版对所有渠道都成立）。
+    #[must_use]
+    pub const fn admits_stage(self, stage: Stage) -> bool {
+        matches!(
+            (self, stage),
+            (Self::Stable, Stage::Stable)
+                | (Self::Beta, Stage::Stable | Stage::ReleaseCandidate)
+                | (
+                    Self::Alpha,
+                    Stage::Stable | Stage::ReleaseCandidate | Stage::Beta
+                )
+                | (Self::Nightly, _)
+        )
+    }
+}
+
+impl fmt::Display for Channel {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
+impl FromStr for Channel {
+    type Err = UpdateError;
+
+    fn from_str(text: &str) -> Result {
+        Self::parse(text)
+    }
+}
diff --git a/crates/core/src/update/checker.rs b/crates/core/src/update/checker.rs
new file mode 100644
index 0000000..a3186de
--- /dev/null
+++ b/crates/core/src/update/checker.rs
@@ -0,0 +1,204 @@
+//! 检查更新：把「清单 + 当前版本 + 渠道 + 目标平台」收敛成一个结论。
+//!
+//! 判定顺序（每一步都是纯函数，可单测）：
+//!
+//! 1. 取清单（源没有该渠道清单 = 还没发过版 = 已是最新）；
+//! 2. 清单自报渠道与请求渠道不符 → [`UpdateErrorKind::ChannelMismatch`]（拿错文件是源的问题，
+//!    不能悄悄当成「没有更新」）；
+//! 3. 准入过滤：[`Channel::admits`]（清单渠道阶梯）+ [`Channel::admits_stage`]（版本号里的
+//!    预发布阶段）**同时**成立。清单可以撒谎，版本号不会；
+//! 4. 只留版本号**严格大于**当前版本的候选（降级不做，nightly 想回退请手工下载）；
+//! 5. 按版本号从高到低找**第一个有本平台产物**的候选：命中就是 [`CheckOutcome::Available`]，
+//!    一个都没有则 [`CheckOutcome::MissingArtifact`]（有新版但没给你的平台发包，这是发布侧的
+//!    漏项，不能对用户说「已是最新」）；
+//! 6. 候选为空 → [`CheckOutcome::UpToDate`]。
+//!
+//! 强制更新（[`Urgency::Forced`]）有两个来源：发布自带的 `force`，或当前版本低于该发布的
+//! `min_supported`（发布侧收回老版本支持）。两者都不看渠道——强制就是强制。
+
+use std::path::Path;
+
+use super::channel::Channel;
+use super::error::{UpdateError, UpdateErrorKind};
+use super::manifest::{Artifact, Release, ReleaseManifest};
+use super::source::UpdateSource;
+use super::target::Target;
+use super::verify::{stage, StagedPackage};
+use super::version::Version;
+
+/// 这次更新急不急。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Urgency {
+    /// 可选：用户想升再升。
+    Optional,
+    /// 强制：`force` 或当前版本低于发布侧的最低支持版本。
+    Forced,
+}
+
+impl Urgency {
+    /// 稳定字符串 id（事件流用）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Optional => "optional",
+            Self::Forced => "forced",
+        }
+    }
+}
+
+/// 一个可安装的候选：哪个发布、哪个产物、急不急。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct UpdateCandidate {
+    /// 发布信息（版本、说明、产物列表）。
+    pub release: Release,
+    /// 本平台要装的那个产物。
+    pub artifact: Artifact,
+    /// 急不急。
+    pub urgency: Urgency,
+}
+
+/// 检查更新的结论。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum CheckOutcome {
+    /// 已是最新。
+    UpToDate {
+        /// 当前版本。
+        current: Version,
+        /// 该渠道内准入的最高版本（清单里没有可用发布时为 `None`）。
+        latest: Option,
+    },
+    /// 有可装的更新。
+    Available(Box),
+    /// 有更高的版本，但里面没有本平台的产物。
+    MissingArtifact {
+        /// 那个更高版本（没有本平台产物的那份发布）。
+        release: Box,
+    },
+}
+
+impl CheckOutcome {
+    /// 是否有可装的更新。
+    #[must_use]
+    pub const fn is_available(&self) -> bool {
+        matches!(self, Self::Available(_))
+    }
+
+    /// 可安装候选（没有则为 `None`）。
+    #[must_use]
+    pub fn candidate(&self) -> Option<&UpdateCandidate> {
+        match self {
+            Self::Available(candidate) => Some(candidate),
+            _ => None,
+        }
+    }
+}
+
+/// 检查更新的入口：绑定一个源与一个目标平台，之后每次检查只传「当前版本 + 渠道」。
+#[derive(Debug, Clone)]
+pub struct UpdateChecker {
+    source: S,
+    target: Target,
+}
+
+impl UpdateChecker {
+    /// 用显式目标平台构造（跨平台代查、测试都靠它）。
+    #[must_use]
+    pub fn new(source: S, target: Target) -> Self {
+        Self { source, target }
+    }
+
+    /// 用当前编译目标构造。
+    #[must_use]
+    pub fn for_current_target(source: S) -> Self {
+        Self::new(source, Target::current())
+    }
+
+    /// 绑定的源。
+    #[must_use]
+    pub const fn source(&self) -> &S {
+        &self.source
+    }
+
+    /// 绑定的目标平台。
+    #[must_use]
+    pub const fn target(&self) -> Target {
+        self.target
+    }
+
+    /// 查一次更新。
+    ///
+    /// # Errors
+    ///
+    /// 清单取不到、清单不合法、渠道不符都返回 [`UpdateError`]。
+    /// 「没有更新」不是错误，走 [`CheckOutcome::UpToDate`]。
+    pub fn check(&self, current: &Version, channel: Channel) -> Result {
+        let Some(manifest) = super::source::verified_manifest(&self.source, channel)? else {
+            return Ok(CheckOutcome::UpToDate {
+                current: current.clone(),
+                latest: None,
+            });
+        };
+        if manifest.channel != channel {
+            return Err(UpdateError::new(
+                UpdateErrorKind::ChannelMismatch,
+                format!("请求的是 {channel} 渠道，清单自报 {}", manifest.channel),
+            ));
+        }
+        let admitted = admitted(&manifest, channel).collect::>();
+        let latest = admitted.iter().map(|release| release.version.clone()).max();
+        let mut candidates = admitted
+            .into_iter()
+            .filter(|release| release.version > *current)
+            .collect::>();
+        candidates.sort_by(|left, right| right.version.cmp(&left.version));
+
+        for release in &candidates {
+            if let Some(artifact) = release.artifact_for(self.target) {
+                return Ok(CheckOutcome::Available(Box::new(UpdateCandidate {
+                    urgency: urgency_of(release, current),
+                    release: (*release).clone(),
+                    artifact: artifact.clone(),
+                })));
+            }
+        }
+        match candidates.first() {
+            Some(release) => Ok(CheckOutcome::MissingArtifact {
+                release: Box::new((*release).clone()),
+            }),
+            None => Ok(CheckOutcome::UpToDate {
+                current: current.clone(),
+                latest,
+            }),
+        }
+    }
+
+    /// 把候选的包体取下来、落暂存、校验。成功返回的 [`StagedPackage`] 可直接交给
+    /// [`super::install::install_staged`]。
+    ///
+    /// # Errors
+    ///
+    /// 取包失败透传；长度或摘要不符分别返回 `SizeMismatch` / `DigestMismatch`，
+    /// 且暂存文件会被删掉（见 [`stage`]）。
+    pub fn prepare(
+        &self,
+        candidate: &UpdateCandidate,
+        staging_dir: &Path,
+    ) -> Result {
+        stage(&self.source, &candidate.artifact, staging_dir)
+    }
+}
+
+/// 该渠道准入的全部发布（不看版本高低）。
+fn admitted(manifest: &ReleaseManifest, channel: Channel) -> impl Iterator {
+    manifest.releases.iter().filter(move |release| {
+        channel.admits(release.channel) && channel.admits_stage(release.version.stage())
+    })
+}
+
+fn urgency_of(release: &Release, current: &Version) -> Urgency {
+    if release.force || release.below_min_supported(current) {
+        Urgency::Forced
+    } else {
+        Urgency::Optional
+    }
+}
diff --git a/crates/core/src/update/ed25519.rs b/crates/core/src/update/ed25519.rs
new file mode 100644
index 0000000..9863ce0
--- /dev/null
+++ b/crates/core/src/update/ed25519.rs
@@ -0,0 +1,52 @@
+//! Ed25519 **严格验签**（`ed25519-dalek::verify_strict`），只验不签、只用公开数据。
+//!
+//! # 为什么是官方实现，而不是本仓自写
+//!
+//! M190 第一版为了「scope 里不含 `crates/core/Cargo.toml`」把曲线算术写在了仓里
+//! （5x51 素域 + 扩展坐标 + 平方-乘）。r1 复审的裁定是**不允许**：这是**信任锚**，
+//! 非规范编码、小阶点这类微妙错误的后果是「验签通过但本不该通过」，自写的向量覆盖再全也证明不了
+//! 「严格性判据选对了」。当时的时机也最好：正式信任表（`trust::PRODUCTION`）还是空表，换实现
+//! **零兼容负担**。于是这里只剩一层薄封装。
+//!
+//! # 判据分工（**实测口径**，`ed25519-dalek 2.2.0`；别照抄「常识」）
+//!
+//! | 步骤 | 它实际做什么 | 它**不**做什么 |
+//! |---|---|---|
+//! | `VerifyingKey::from_bytes` | 解压成曲线上的合法点；解不出来才 `Err` | **不**校验编码规范性：`y >= p` 这种第二种写法照样 `Ok`（此时 `is_weak() == true`）。M190 r2 复审实测并纠正了先前「要求规范编码」的说法 |
+//! | `VerifyingKey::verify`（**非 strict**，本仓不用） | 验方程 `[S]B = R + [k]A`，并检查 `S` 是**规范标量**（`S >= L` 会拒） | **不**检查小阶点：小阶公钥 / 小阶 `R` 下「自洽的伪造四元组」能验过 |
+//! | `VerifyingKey::verify_strict`（**本仓用的这个**） | 上面全部 + 拒**小阶公钥**与**小阶 `R`** | —— |
+//!
+//! 换成大白话：在这批拒绝类用例里，strict 与**非** strict 唯一的分歧是**小阶点**（不是可锻性——
+//! `verify` 自己就查 `S` 规范性）。所以守卫里真正承重的是
+//! `tests/ed25519_cases.rs::small_order_public_key_is_rejected` 与
+//! `small_order_r_is_rejected_only_by_strict` 这两条；`malleable_s_plus_l_is_rejected` 等其余几条在
+//! 非 strict 下**照样绿**，它们钉的是「判据没被删成恒真」，不要误当成 strict 的守卫。
+//!
+//! # 签名侧不在二进制里
+//!
+//! 本仓没有任何私钥代码：清单由 `packaging/sign_manifest.py`（纯 Python 参考实现，零第三方依赖）
+//! 在发布侧签。测试里的签名夹具走 dalek 的 `SigningKey`，只在 `cfg(test)` 里编译。
+
+use ed25519_dalek::{Signature, VerifyingKey};
+
+/// 公钥字节数。
+pub(crate) const PUBLIC_KEY_LEN: usize = 32;
+/// 签名字节数。
+pub(crate) const SIGNATURE_LEN: usize = 64;
+
+/// 验一条 Ed25519 签名（**严格**语义，见模块文档）。
+///
+/// `message` 是任意长原文——这里恒为清单文件的**原始字节**（见 [`super::signature`]）。
+#[must_use]
+pub(crate) fn verify(
+    public_key: &[u8; PUBLIC_KEY_LEN],
+    message: &[u8],
+    signature: &[u8; SIGNATURE_LEN],
+) -> bool {
+    let Ok(key) = VerifyingKey::from_bytes(public_key) else {
+        // 不是曲线上的合法点：直接拒。注意 `from_bytes` **不**管编码规范性（见模块文档的表）。
+        return false;
+    };
+    key.verify_strict(message, &Signature::from_bytes(signature))
+        .is_ok()
+}
diff --git a/crates/core/src/update/error.rs b/crates/core/src/update/error.rs
new file mode 100644
index 0000000..5826669
--- /dev/null
+++ b/crates/core/src/update/error.rs
@@ -0,0 +1,173 @@
+//! 自更新错误：一份分类 + 一句人话 + 出错路径。
+//!
+//! 分类只服务三件事：给日志/事件一个稳定 id、判「要不要换源」、判「用户的包有没有被动过」。
+//! core 不引 `thiserror`，手写 `Display`/`Error`（与 `download::error` 同一取舍）。
+
+use std::fmt;
+use std::io;
+use std::path::{Path, PathBuf};
+
+use super::version::VersionError;
+
+/// 自更新失败分类。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum UpdateErrorKind {
+    /// 版本号解析失败（清单里写了不是 semver 的东西）。
+    InvalidVersion,
+    /// 清单结构不合法：缺字段、摘要格式错、同一清单里重复版本、`size` 为 0。
+    InvalidManifest,
+    /// 清单声明的渠道与请求的渠道不符（拿 stable 清单当 beta 用）。
+    ChannelMismatch,
+    /// 更新源没有这份数据：渠道清单文件、产物文件不存在。
+    SourceMissing,
+    /// 更新源协议不支持（例如本地目录源里出现了 `http://` 地址）。
+    UnsupportedSource,
+    /// 远端源取字节失败：连不上、超时、5xx、所有候选源（含镜像）全挂。
+    ///
+    /// 与 [`Self::Io`] 分开是因为处置不同：网络失败值得隔一会儿重试/换镜像，
+    /// 本地 IO 失败（盘满、没权限）重试多少次都一样。
+    Network,
+    /// 本地 IO 失败：读源、写暂存、替换落盘。
+    Io,
+    /// 摘要不符：拿到的字节与清单声明的不是同一份。
+    DigestMismatch,
+    /// 长度不符：典型成因是下载被截断，也可能清单写错。
+    SizeMismatch,
+    /// 清单没有配套签名文件（`<清单名>.sig` 不在源里）。
+    ///
+    /// 与 [`Self::SignatureInvalid`] 分开：这条是**发布侧漏了签名**，不是清单被改；
+    /// 处置也不同（等发布侧补，或回滚发布），所以必须是两个分类。
+    SignatureMissing,
+    /// 签名文件本身坏了：不是 JSON、字段名拼错、`format` 不认识、`signatures` 是空的。
+    SignatureMalformed,
+    /// 本构建没有钉任何清单签名公钥（正式信任表为空）。
+    ///
+    /// 这是「构建形态」的问题，不是清单的问题：空表一律拒装，绝不「没钥就放行」。
+    KeyringEmpty,
+    /// 清单的签名者不在钉住的信任表里（`key_id` 一个都没命中）。
+    SignatureUnknownKey,
+    /// 签名对不上清单字节（清单被改过，或签名是给另一份清单的）。
+    SignatureInvalid,
+}
+
+impl UpdateErrorKind {
+    /// 稳定字符串 id（日志、事件流、诊断规则输入用；**不要改名**）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::InvalidVersion => "invalid_version",
+            Self::InvalidManifest => "invalid_manifest",
+            Self::ChannelMismatch => "channel_mismatch",
+            Self::SourceMissing => "source_missing",
+            Self::UnsupportedSource => "unsupported_source",
+            Self::Network => "network",
+            Self::Io => "io",
+            Self::DigestMismatch => "digest_mismatch",
+            Self::SizeMismatch => "size_mismatch",
+            Self::SignatureMissing => "signature_missing",
+            Self::SignatureMalformed => "signature_malformed",
+            Self::KeyringEmpty => "keyring_empty",
+            Self::SignatureUnknownKey => "signature_unknown_key",
+            Self::SignatureInvalid => "signature_invalid",
+        }
+    }
+
+    /// 换个源 / 重下一次是否可能变好（调用方据此决定重试，别在这里写死重试次数）。
+    ///
+    /// 清单本身不合法、协议不支持、渠道不符这几类换多少源都一样，所以只有字节层
+    /// （摘要/长度）、网络（可能是瞬时抖动）与 IO（可能是瞬时占用）算可重试。
+    ///
+    /// 签名五兄弟**一律不可重试**：签名不对不是抖动，重试一千次还是不对。把它们标成可重试
+    /// 会让壳层反复弹「网络问题，稍后重试」，掩盖真正的原因（发布侧漏签 / 钥没钉 / 清单被改）。
+    #[must_use]
+    pub const fn is_retryable(self) -> bool {
+        matches!(
+            self,
+            Self::DigestMismatch | Self::SizeMismatch | Self::Network | Self::Io
+        )
+    }
+
+    /// 是否属于「清单签名」这一组（壳层据此换文案：这不是网络问题，别让用户重试）。
+    #[must_use]
+    pub const fn is_signature(self) -> bool {
+        matches!(
+            self,
+            Self::SignatureMissing
+                | Self::SignatureMalformed
+                | Self::KeyringEmpty
+                | Self::SignatureUnknownKey
+                | Self::SignatureInvalid
+        )
+    }
+}
+
+/// 自更新错误。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct UpdateError {
+    /// 分类。
+    pub kind: UpdateErrorKind,
+    /// 人类可读描述（进日志；用户可见文案由上层按 kind 组织，别直接贴这里）。
+    pub message: String,
+    /// 出错的文件或目录（能定位到就带上）。
+    pub path: Option,
+}
+
+impl UpdateError {
+    /// 构造错误。
+    #[must_use]
+    pub fn new(kind: UpdateErrorKind, message: impl Into) -> Self {
+        Self {
+            kind,
+            message: message.into(),
+            path: None,
+        }
+    }
+
+    /// 清单不合法。
+    #[must_use]
+    pub fn invalid_manifest(message: impl Into) -> Self {
+        Self::new(UpdateErrorKind::InvalidManifest, message)
+    }
+
+    /// 标注出错路径。
+    #[must_use]
+    pub fn with_path(mut self, path: impl Into) -> Self {
+        self.path = Some(path.into());
+        self
+    }
+
+    /// 分类是否可重试。
+    #[must_use]
+    pub const fn is_retryable(&self) -> bool {
+        self.kind.is_retryable()
+    }
+
+    /// 把底层 IO 错误包成「某个路径上的 IO 失败」。
+    #[must_use]
+    pub fn io_at(path: &Path, source: &io::Error) -> Self {
+        Self::new(UpdateErrorKind::Io, source.to_string()).with_path(path)
+    }
+}
+
+impl fmt::Display for UpdateError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match &self.path {
+            Some(path) => write!(
+                f,
+                "[{}] {}（{}）",
+                self.kind.as_str(),
+                self.message,
+                path.display()
+            ),
+            None => write!(f, "[{}] {}", self.kind.as_str(), self.message),
+        }
+    }
+}
+
+impl std::error::Error for UpdateError {}
+
+impl From for UpdateError {
+    fn from(error: VersionError) -> Self {
+        Self::new(UpdateErrorKind::InvalidVersion, error.to_string())
+    }
+}
diff --git a/crates/core/src/update/github.rs b/crates/core/src/update/github.rs
new file mode 100644
index 0000000..ac0d059
--- /dev/null
+++ b/crates/core/src/update/github.rs
@@ -0,0 +1,341 @@
+//! GitHub Releases 更新源（D50 定案：GitHub Releases 是唯一更新源）。
+//!
+//! # 地址形状（固定，不可配置）
+//!
+//! ```text
+//! 清单   ///releases/latest/download/manifest.json
+//! 产物   ///releases/latest/download/<清单里的产物文件名>
+//! ```
+//!
+//! `releases/latest/download/` 是 GitHub 原生的「最新发布」地址：不用知道 tag、
+//! 不用调 API（API 有速率限制、也要 token），发布侧只要把 `manifest.json` 和各平台产物
+//! 挂在最新 release 上，客户端就能取到。清单里的 `url` 因此照 D49 的产物命名规则写成
+//! **文件名**（如 `unlucky-launcher_0.6.0_windows_x64.exe`），由本源拼成上面的地址；
+//! 清单若已经写了完整 `http(s)` 地址（例如临时挂到别处复测），原样使用。
+//!
+//! # 可配置面只有三个
+//!
+//! * `owner` / `repo`（默认 [`DEFAULT_OWNER`] / [`DEFAULT_REPO`]）；
+//! * `base`（默认 [`DEFAULT_BASE`]；**只为测试存在**——把它指向本地假 HTTP 服务，
+//!   单测就不必联网）。
+//!
+//! # 网络全走 `core::download`
+//!
+//! * **产物**（几十 MB 的包体）：整段交给 [`DownloadEngine::download`]——镜像展开
+//!   （国内 gh-proxy 前缀）、地区判定、健康度排序、失败退避、断点续传、原子落盘全部复用，
+//!   本源不再造一套网络栈，也不自己拼镜像地址；
+//! * **清单**（几 KB 的 JSON）：用引擎的候选规划 [`GitHubReleaseSource::candidates`] +
+//!   共享客户端 [`DownloadEngine::client`] 逐候选取文本，与 `core::game::java` 的
+//!   「一锤子 GET」同一手法。包体才需要退避/续传/分块，为几 KB 建一条下载流水线不划算。
+//!
+//! 两种路径都吃到同一条镜像策略：`mirrors.json` 的前缀规则 + 地区档案里生效的
+//! `gh_proxy` 前缀（[`crate::download::mirrors::MirrorTable::gh_proxy_candidates`]），
+//! 国内环境下 `https://github.com/...` 会被改写成 `https://gh-proxy.com/https://github.com/...`。
+//!
+//! # 渠道
+//!
+//! `releases/latest` 只有一个，所以本源**只服务 stable**。beta/alpha/nightly 的清单枚举
+//! 保留但不发布（D50「先只发 stable」），因此非 stable 渠道一律 `Ok(None)` = 没有更新——
+//! 这不是错误，别让「还没开通道」变成用户机器上的红字。
+//!
+//! # 校验
+//!
+//! 本源只管「把字节放到 dest」：长度与摘要由 [`super::verify`] 统一双检（与 [`super::DirSource`]
+//! 一致）。所以包体请求只带 `expected_size`（给进度预算与门户页假阳性兜底），不带摘要——
+//! 摘要判据只有一处，别在这里再写一套。
+//!
+//! # 运行时
+//!
+//! [`UpdateSource`] 是同步签名，本源在方法内部用 [`crate::download::block_on`] 桥接异步引擎
+//! （CLI 与 presenter 都是这么用的）。因此**不要在已有的 tokio 运行时里直接调本源的
+//! `fetch_*`**：tokio 不允许嵌套 `block_on`，会 panic。更新流程请放在独立线程上跑。
+
+use std::path::{Path, PathBuf};
+use std::sync::Arc;
+
+use crate::download::cache::now_ms;
+use crate::download::{
+    Candidate, DownloadEngine, DownloadError, DownloadErrorKind, DownloadRequest, ResourceKind,
+};
+
+use super::channel::Channel;
+use super::error::{UpdateError, UpdateErrorKind};
+use super::manifest::Artifact;
+use super::source::{ManifestDocuments, UpdateSource};
+
+/// 默认仓库 owner。
+pub const DEFAULT_OWNER: &str = "AskaEth";
+/// 默认仓库名。
+pub const DEFAULT_REPO: &str = "Unlucky-Launcher";
+/// GitHub 站点根地址（`base` 的默认值）。
+pub const DEFAULT_BASE: &str = "https://github.com";
+/// 清单文件名（挂在最新 release 的产物里，地址由 D50 定死）。
+pub const MANIFEST_ASSET: &str = "manifest.json";
+/// 清单签名的资产名（M190：与清单并列挂在同一个 release 上）。
+pub const MANIFEST_SIGNATURE_ASSET: &str = "manifest.json.sig";
+
+/// GitHub Releases 更新源。
+#[derive(Debug, Clone)]
+pub struct GitHubReleaseSource {
+    engine: Arc,
+    owner: String,
+    repo: String,
+    base: String,
+    id: String,
+}
+
+impl GitHubReleaseSource {
+    /// 用默认仓库（[`DEFAULT_OWNER`] / [`DEFAULT_REPO`]）与 GitHub 站点根地址构造。
+    #[must_use]
+    pub fn new(engine: Arc) -> Self {
+        Self::with_repo(engine, DEFAULT_OWNER, DEFAULT_REPO)
+    }
+
+    /// 指定仓库构造（fork / 自建镜像仓、测试用）。
+    #[must_use]
+    pub fn with_repo(
+        engine: Arc,
+        owner: impl Into,
+        repo: impl Into,
+    ) -> Self {
+        let owner = owner.into();
+        let repo = repo.into();
+        let id = format!("github:{owner}/{repo}");
+        Self {
+            engine,
+            owner,
+            repo,
+            base: DEFAULT_BASE.to_string(),
+            id,
+        }
+    }
+
+    /// 换 `base`（站点根地址，末尾斜杠会去掉）。
+    ///
+    /// 生产不用这个口子；单测把它指向本地假服务（`http://127.0.0.1:`）以保持离线。
+    #[must_use]
+    pub fn with_base(mut self, base: impl Into) -> Self {
+        self.base = base.into().trim_end_matches('/').to_string();
+        self
+    }
+
+    /// 仓库 owner。
+    #[must_use]
+    pub fn owner(&self) -> &str {
+        &self.owner
+    }
+
+    /// 仓库名。
+    #[must_use]
+    pub fn repo(&self) -> &str {
+        &self.repo
+    }
+
+    /// 站点根地址。
+    #[must_use]
+    pub fn base(&self) -> &str {
+        &self.base
+    }
+
+    /// 引擎（调用方要挂进度事件时用）。
+    #[must_use]
+    pub fn engine(&self) -> &Arc {
+        &self.engine
+    }
+
+    /// 某渠道的清单地址；非 stable 渠道没有清单（返回 `None`）。
+    #[must_use]
+    pub fn manifest_url(&self, channel: Channel) -> Option {
+        (channel == Channel::Stable).then(|| format!("{}/{MANIFEST_ASSET}", self.download_base()))
+    }
+
+    /// 把清单里的 `url` 解析成真实下载地址。
+    ///
+    /// 已经是 `http(s)://` 的地址原样使用（清单可以临时指向别处）；其余一律当成
+    /// 「最新 release 里的产物文件名」，拼到本源的下载根路径下。
+    ///
+    /// # Errors
+    ///
+    /// `url` 为空是 [`UpdateErrorKind::InvalidManifest`]（清单坏，不是源的问题）；
+    /// 非 http(s) 的其它协议是 [`UpdateErrorKind::UnsupportedSource`]。
+    pub fn artifact_url(&self, artifact: &Artifact) -> Result {
+        let raw = artifact.url.trim();
+        if raw.is_empty() {
+            return Err(UpdateError::invalid_manifest("产物的 url 为空"));
+        }
+        if raw.starts_with("http://") || raw.starts_with("https://") {
+            return Ok(raw.to_string());
+        }
+        if raw.contains("://") {
+            return Err(UpdateError::new(
+                UpdateErrorKind::UnsupportedSource,
+                format!("GitHub 源只认 http(s) 地址或 release 内的产物文件名：`{raw}`"),
+            ));
+        }
+        // `./name` 与 `/name` 都当成「release 里的文件名」，别把整串拼出个双斜杠路径。
+        let name = raw.trim_start_matches(['.', '/']);
+        Ok(format!("{}/{name}", self.download_base()))
+    }
+
+    /// 某地址在引擎眼里的候选源序列（镜像展开 + 健康度排序，**不发请求**）。
+    ///
+    /// 生产调用走引擎自己的规划；这里是给「镜像策略是否生效」这类断言用的观察窗。
+    #[must_use]
+    pub fn candidates(&self, url: &str) -> Vec {
+        // `dest` 只是 `DownloadRequest` 的必填字段，`plan` 不看它。
+        let request = DownloadRequest::new(ResourceKind::GitHubRelease, url, PathBuf::new());
+        self.engine.plan(&request, now_ms())
+    }
+
+    /// 最新的 release 产物根路径（`///releases/latest/download`）。
+    fn download_base(&self) -> String {
+        format!(
+            "{}/{}/{}/releases/latest/download",
+            self.base, self.owner, self.repo
+        )
+    }
+
+    /// 逐候选取一段文本：`Ok(None)` = 所有候选都说「这份文件不存在」。
+    fn fetch_text(&self, url: &str) -> Result, UpdateError> {
+        let candidates = self.candidates(url);
+        if candidates.is_empty() {
+            return Err(UpdateError::new(
+                UpdateErrorKind::Network,
+                format!("没有可用候选源：{url}"),
+            ));
+        }
+        let mut failure: Option = None;
+        let mut all_missing = true;
+        for candidate in candidates {
+            match self.get_candidate_text(&candidate.url) {
+                Ok(Some(text)) => return Ok(Some(text)),
+                // 某个候选 404 不代表没有：镜像可能比官方慢半拍，继续问下一个。
+                Ok(None) => {}
+                Err(error) => {
+                    all_missing = false;
+                    failure = Some(error);
+                }
+            }
+        }
+        if all_missing {
+            Ok(None)
+        } else {
+            Err(failure.unwrap_or_else(|| {
+                UpdateError::new(UpdateErrorKind::Network, format!("取 {url} 失败"))
+            }))
+        }
+    }
+
+    /// 单个候选地址取文本；`Ok(None)` = 404/410（该候选没有这份文件）。
+    fn get_candidate_text(&self, url: &str) -> Result, UpdateError> {
+        let client = self.engine.client();
+        crate::download::block_on(async {
+            let response = client.get(url).send().await.map_err(|error| {
+                UpdateError::new(
+                    UpdateErrorKind::Network,
+                    format!("取更新清单失败：{error}（{url}）"),
+                )
+            })?;
+            let status = response.status();
+            if status == reqwest::StatusCode::NOT_FOUND || status == reqwest::StatusCode::GONE {
+                return Ok(None);
+            }
+            if !status.is_success() {
+                return Err(UpdateError::new(
+                    UpdateErrorKind::Network,
+                    format!("更新清单返回 HTTP {status}（{url}）"),
+                ));
+            }
+            let text = response.text().await.map_err(|error| {
+                UpdateError::new(
+                    UpdateErrorKind::Network,
+                    format!("读更新清单响应失败：{error}（{url}）"),
+                )
+            })?;
+            if text.trim().is_empty() {
+                return Err(UpdateError::invalid_manifest(format!(
+                    "清单响应为空（{url}），发布脚本可能漏传了 {MANIFEST_ASSET}"
+                )));
+            }
+            Ok(Some(text))
+        })
+    }
+}
+
+impl UpdateSource for GitHubReleaseSource {
+    fn source_id(&self) -> &str {
+        &self.id
+    }
+
+    fn fetch_manifest_documents(
+        &self,
+        channel: Channel,
+    ) -> Result, UpdateError> {
+        let Some(url) = self.manifest_url(channel) else {
+            return Ok(None);
+        };
+        let Some(manifest) = self.fetch_text(&url)? else {
+            return Ok(None);
+        };
+        // 签名文件的 404 与清单的 404 处理不同：清单没有 = 该渠道没发过版（不是错误）；
+        // 签名没有 = 发布侧漏了签名（上层判 SignatureMissing 并拒装）。
+        let signature_url = format!("{}/{MANIFEST_SIGNATURE_ASSET}", self.download_base());
+        let signatures = self.fetch_text(&signature_url)?;
+        Ok(Some(ManifestDocuments {
+            manifest,
+            signatures,
+        }))
+    }
+
+    fn fetch_artifact(&self, artifact: &Artifact, dest: &Path) -> Result {
+        let url = self.artifact_url(artifact)?;
+        if let Some(parent) = dest.parent() {
+            if !parent.as_os_str().is_empty() {
+                std::fs::create_dir_all(parent)
+                    .map_err(|error| UpdateError::io_at(parent, &error))?;
+            }
+        }
+        // 摘要不在这里传：`update::verify` 统一做长度/摘要双检（trait 契约，别各写一套）。
+        let request = DownloadRequest::new(ResourceKind::GitHubRelease, url.clone(), dest)
+            .with_size(artifact.size);
+        let outcome = crate::download::block_on(self.engine.download(request))
+            .map_err(|error| download_error(&error, &url))?;
+        Ok(outcome.bytes)
+    }
+}
+
+/// 把下载引擎的错误翻译成自更新的错误分类（两套分类各有各的职责，别混用）。
+fn download_error(error: &DownloadError, url: &str) -> UpdateError {
+    let kind = match error.kind {
+        DownloadErrorKind::NotFound => UpdateErrorKind::SourceMissing,
+        DownloadErrorKind::Integrity => UpdateErrorKind::DigestMismatch,
+        DownloadErrorKind::Io => UpdateErrorKind::Io,
+        DownloadErrorKind::InvalidRequest => UpdateErrorKind::UnsupportedSource,
+        DownloadErrorKind::AllSourcesFailed if all_candidates_missing(error) => {
+            UpdateErrorKind::SourceMissing
+        }
+        DownloadErrorKind::ServerError
+        | DownloadErrorKind::Timeout
+        | DownloadErrorKind::Network
+        | DownloadErrorKind::RangeUnsupported
+        | DownloadErrorKind::AllSourcesFailed => UpdateErrorKind::Network,
+    };
+    let mut message = format!("{}（{url}）", error.message);
+    if !error.suppressed.is_empty() {
+        message.push_str(&format!("；各源：{}", error.suppressed.join("；")));
+    }
+    UpdateError::new(kind, message)
+}
+
+/// 所有候选是不是都回「这份文件不存在」。
+///
+/// 引擎把逐源失败压成一条 [`DownloadErrorKind::AllSourcesFailed`]，原始的 404/410 分类只剩在
+/// 失败摘要文本里（`download::http::classify_status` 的文案：`HTTP 404`）。不还原这一层，
+/// 「发布清单里挂了个没上传的产物」会被报成「网络失败 + 可重试」，重试多少次都一样。
+fn all_candidates_missing(error: &DownloadError) -> bool {
+    !error.suppressed.is_empty()
+        && error
+            .suppressed
+            .iter()
+            .all(|line| line.contains("HTTP 404") || line.contains("HTTP 410"))
+}
diff --git a/crates/core/src/update/install.rs b/crates/core/src/update/install.rs
new file mode 100644
index 0000000..f8c492e
--- /dev/null
+++ b/crates/core/src/update/install.rs
@@ -0,0 +1,367 @@
+//! 原子替换：先把新包落到**目标同目录**的中转名，再把旧文件改名挪开、中转名顶上；
+//! 任一步失败都能回滚，**目标路径上永远不会出现半截文件**。
+//!
+//! # 为什么不用「直接覆盖」
+//!
+//! Windows 上**正在运行的 exe** 不能被覆盖、也不能被删除（映像被占用，改字节这条路根本
+//! 不存在）；`std::fs::rename` 走 `MoveFileExW(MOVEFILE_REPLACE_EXISTING)`，目标只要被任何
+//! 「不共享删除」的句柄占着就报共享冲突（`os error 32`）。剩下唯一可用的动作是**改名**：
+//! 把旧文件挪到同目录的备份名，让新文件顶替原来的路径。而改名本身也可能被拒绝（杀软扫描
+//! 句柄、编辑器打开、另一个进程正在写），所以失败必须能回到旧版本——这正是本模块存在的理由。
+//!
+//! # 为什么先落中转名（M171 跨卷修复）
+//!
+//! 暂存包在 `<数据根>/cache/update/staging`，目标 exe 在安装目录：**两者可能不在同一卷**
+//! （便携版放 U 盘、数据根在 D 盘而程序在 C 盘、部分 macOS 配置）。`rename` 不能跨卷
+//! （Unix `EXDEV` / Windows `ERROR_NOT_SAME_DEVICE`，`std` 不会偷偷降级成复制），
+//! 于是「暂存包 → 目标」那一步必然失败——M169 复审判定这是已发布版本上的真实 bug。
+//!
+//! 修法不是「把 rename 换成 copy」（那会让目标路径上出现半截文件），而是把**原子替换的前提**
+//! 变成不依赖跨卷：
+//!
+//! ```text
+//! 0. 新包 → <目标同目录>/.<文件名>.ullnew--    同卷改名；跨卷时复制到这儿并核对字节数
+//! 1. dest 存在 → rename(dest → <同目录 .ullold-…>)      旧版本先安全落地
+//! 2. rename(中转名 → dest)                              新版本就位（同卷，原子）
+//! 3a. 成功 → 返回 InstallReceipt（备份留着，等新版真的能起来再删）
+//! 3b. 失败 → rename(备份 → dest) 回滚，并把「回滚是否成功」如实报给调用方
+//! ```
+//!
+//! 关键性质：**第 2 步之后目标路径要么是旧字节要么是新字节**，不可能是一半。跨卷那条路多出来的
+//! 复制只发生在第 0 步，落的是中转名：复制到一半失败 → 删中转名、目标一个字节都没动
+//! （多数情况下备份都还没建）。同一卷上走的是改名不是复制，**没有一个字节被多搬一次**。
+//!
+//! Unix 上也照这个顺序跑（Unix 本可直接 `rename` 覆盖，但两套语义分叉之后，回滚路径只有 Windows
+//! 被真正跑过，最容易坏的那一半就没人测了）。
+//!
+//! # 旧版本备份留几份
+//!
+//! 替换成功的那一刻会把**同目录里更早的** `.<同名文件>.ullold-*` 删掉，只留本次这一份
+//! （见 `prune_stale_artifacts`）：旧实现在每次 apply 都留一份、而全仓**没有任何调用方**调
+//! [`InstallReceipt::remove_backup`]，等于每更新一次就在安装目录里堆一个 20+ MB 的 exe。
+//! 「留多份」唯一能多给的东西是「回退到更早的版本」，而回滚只用最近一份，所以按份数上界收敛成 1。
+//!
+//! **一条刻意的例外**：本次安装前 `dest` 就不存在时（`keep = None`）一个 `.ullold-*` 都不删，
+//! 只清残留的 `.ullnew-*`。理由见 `prune_stale_artifacts`：那个时刻的旧备份可能是崩溃现场里
+//! **唯一幸存的旧 exe**（上一次装在「dest → 备份」之后、「中转名 → dest」之前被杀），
+//! 删掉它等于抹掉用户手工恢复的最后一份材料。
+//!
+//! # 本模块**不**负责的事
+//!
+//! * **不判断现在能不能替换**：占用/杀软/权限都在 [`ReplacePolicy`] 的重试里撞，撞不动就回滚。
+//!   **正在运行的 exe 照样能换**——这一点 M159 在 Windows 真机验过（`ull update apply` 在自己
+//!   运行中完成了 `rename(dest→备份)` + `rename(暂存→dest)`，替换后的 exe 仍能启动）：
+//!   Windows 加载器打开映像时带 `FILE_SHARE_DELETE`，所以**可以改名**，只是**不能覆盖/删除**
+//!   （改字节这条路根本不存在）。这也是本模块「先改名、再搬入」而不是「直接覆盖」的原因。
+//!   别照早先那版文档去设计「退出自身 → 由另一个进程搬运」的双进程方案（HMCL 的 `--apply-to`）：
+//!   那条路在 Windows 上不是必需的。（Unix 上 `rename` 本就可以覆盖，两步写法是为了两边同一条
+//!   回滚路径，见上。）
+//! * **不装安装器形态**（msi/dmg/deb/rpm）：那些该交给系统包管理器，
+//!   [`crate::update::PackageFormat::needs_installer`] 是给上层的判据。
+//! * **不重启、不删备份**（最新一份何时删由上层决定：新版启动成功后
+//!   [`InstallReceipt::remove_backup`]）。
+//!
+//! # 单测覆盖到哪
+//!
+//! 占用场景是**真的造出来**的：测试里用 `share_mode(FILE_SHARE_READ)` 打开目标文件
+//! （**不带** `FILE_SHARE_DELETE`，与 Windows 加载器打开正在运行的映像时一致），
+//! 让 `rename` 撞共享冲突，于是在 Windows 上能看到「重试 → 仍失败 → 旧版本完好」。
+//! 那条用例是 `#[cfg(windows)]`：Unix 允许改名打开中的文件，本来就该成功。
+//!
+//! 跨卷场景是**真的跨卷**（`install_xdev_cases` 拿一次真实 rename 探出第二块卷），真盘上没法
+//! 确定性复现的「跨卷被拒」「复制/改名到一半失败」则由 `install_io_cases` 的注入器打出来。
+//! 它都不是「运行中的 exe」——那需要真的跑一个子进程并替换它，属真机验收，不在单测范围。
+//! 另外注意：`std::fs::File::open` **默认共享删除**，用它造的「占用」不生效，
+//! 写这类用例时必须显式指定 `share_mode`。
+
+use std::fmt;
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+
+use super::error::UpdateError;
+use super::replace_io::{is_cross_device, rename_with_retry, RealFs, ReplaceFs};
+use super::verify::StagedPackage;
+
+pub use super::replace_io::ReplacePolicy;
+
+/// 同进程内备份 / 中转文件名去重序号。
+static SEQ: AtomicU64 = AtomicU64::new(0);
+
+/// 旧版本备份的名字标签（`.<文件名>.ullold--`）。
+const OLD_TAG: &str = "ullold";
+
+/// 新版本中转名的名字标签（`.<文件名>.ullnew--`）。
+const NEW_TAG: &str = "ullnew";
+
+/// 替换成功后的收据。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct InstallReceipt {
+    /// 新版本所在的路径。
+    pub dest: PathBuf,
+    /// 旧版本被挪到哪（原本没有文件时为 `None`）。
+    pub backup: Option,
+    /// 新版本字节数。
+    pub bytes: u64,
+}
+
+impl InstallReceipt {
+    /// 删掉旧版本备份（新版启动成功之后调用）。
+    ///
+    /// # Errors
+    ///
+    /// 删不掉（还占着、没权限）返回带路径的 [`UpdateError`]——这时**别**当成更新失败，
+    /// 只是留了个垃圾文件，下次启动还能再删。
+    pub fn remove_backup(&self) -> Result<(), UpdateError> {
+        let Some(backup) = &self.backup else {
+            return Ok(());
+        };
+        fs::remove_file(backup).map_err(|error| UpdateError::io_at(backup, &error))
+    }
+
+    /// 手动回滚：把备份搬回 `dest`（新版起不来时用）。成功后 `backup` 字段清空。
+    ///
+    /// # Errors
+    ///
+    /// 没有备份时是空操作 `Ok(())`；搬不动返回 [`UpdateError`]（此时 `backup` 保持不变，
+    /// 旧版本还在原位置，可以再试）。
+    pub fn rollback(&mut self, policy: ReplacePolicy) -> Result<(), UpdateError> {
+        let Some(backup) = self.backup.as_ref() else {
+            return Ok(());
+        };
+        rename_with_retry(&RealFs, backup, &self.dest, policy)
+            .map_err(|error| UpdateError::io_at(&self.dest, &error))?;
+        self.backup = None;
+        Ok(())
+    }
+}
+
+/// 替换失败：原始错误 + 回滚结果。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct InstallFailure {
+    /// 原始失败。
+    pub error: UpdateError,
+    /// 旧版本是否已回到原路径（`true` = 目标没被破坏；本来没有旧文件时也算 `true`）。
+    pub rolled_back: bool,
+    /// 回滚失败时旧版本留在哪（`None` = 已回到原位或压根没有旧文件）。
+    pub backup_left: Option,
+}
+
+impl InstallFailure {
+    /// 目标是否可能处于「既不是旧版也不是新版」的坏状态（需要人工介入）。
+    #[must_use]
+    pub const fn needs_manual_repair(&self) -> bool {
+        !self.rolled_back
+    }
+}
+
+impl fmt::Display for InstallFailure {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}", self.error)?;
+        if self.rolled_back {
+            f.write_str("（已回滚，旧版本仍在原位）")
+        } else {
+            let where_ = self.backup_left.as_ref().map_or_else(String::new, |path| {
+                format!("，旧文件留在 {}", path.display())
+            });
+            write!(f, "（回滚失败，需要人工处理{where_}）")
+        }
+    }
+}
+
+impl std::error::Error for InstallFailure {}
+
+/// 把校验过的暂存包装到 `dest`；失败则回滚，旧版本保持可用。
+///
+/// # Errors
+///
+/// 目录建不出来、目标被占用、改名/跨卷复制失败都返回 [`InstallFailure`]，
+/// 其中的 `rolled_back` 如实反映旧版本有没有回到原位。
+pub fn install_staged(
+    staged: &StagedPackage,
+    dest: &Path,
+    policy: ReplacePolicy,
+) -> Result {
+    install_with(&RealFs, staged, dest, policy)
+}
+
+/// [`install_staged`] 的注入版：文件动作用调用方给的 [`ReplaceFs`]。
+///
+/// 判据与顺序与本函数完全相同——测试只能改「系统调用成不成功」，改不了「失败时目标是否完好」。
+pub(crate) fn install_with(
+    fs: &dyn ReplaceFs,
+    staged: &StagedPackage,
+    dest: &Path,
+    policy: ReplacePolicy,
+) -> Result {
+    if let Some(parent) = dest
+        .parent()
+        .filter(|parent| !parent.as_os_str().is_empty())
+    {
+        fs::create_dir_all(parent)
+            .map_err(|error| failed(UpdateError::io_at(parent, &error), true, None))?;
+    }
+
+    // 第 0 步：新包 → 目标同目录的中转名。**先做这一步**：它在目标没被碰过的情况下把
+    // 「搬不动」暴露出来（跨卷、临时目录写不进），失败时连备份都不用建。
+    let new = new_path(dest);
+    if let Err(error) = materialize(fs, staged, &new, policy) {
+        let _ = fs.remove(&new);
+        return Err(failed(UpdateError::io_at(dest, &error), true, None));
+    }
+
+    // 第 1 步：dest → 同目录备份。
+    let mut backup = None;
+    if fs::symlink_metadata(dest).is_ok() {
+        let path = backup_path(dest);
+        if let Err(error) = rename_with_retry(fs, dest, &path, policy) {
+            let _ = fs.remove(&new);
+            return Err(failed(UpdateError::io_at(dest, &error), true, None));
+        }
+        backup = Some(path);
+    }
+
+    // 第 2 步：中转名 → dest（同卷，原子）。
+    match rename_with_retry(fs, &new, dest, policy) {
+        Ok(()) => {
+            prune_stale_artifacts(backup.as_deref(), dest);
+            Ok(InstallReceipt {
+                dest: dest.to_path_buf(),
+                backup,
+                bytes: staged.size(),
+            })
+        }
+        Err(error) => {
+            let _ = fs.remove(&new);
+            let error = UpdateError::io_at(dest, &error);
+            let Some(backup_path) = backup else {
+                // 目标原本不存在：没有旧版本要恢复，目标也没被写坏，
+                // 所以按「旧版本仍在原位」上报（新安装失败 ≠ 现有安装被破坏）。
+                return Err(failed(error, true, None));
+            };
+            match rename_with_retry(fs, &backup_path, dest, policy) {
+                Ok(()) => Err(failed(error, true, None)),
+                Err(_) => Err(failed(error, false, Some(backup_path))),
+            }
+        }
+    }
+}
+
+/// 第 0 步：把暂存包落成 `new`（目标同目录）。同卷改名一步到位；跨卷才复制，并核对字节数。
+fn materialize(
+    fs: &dyn ReplaceFs,
+    staged: &StagedPackage,
+    new: &Path,
+    policy: ReplacePolicy,
+) -> std::io::Result<()> {
+    match rename_with_retry(fs, staged.path(), new, policy) {
+        Ok(()) => Ok(()),
+        // 跨卷不重试：换多少次都不会变成同卷。复制是**唯一**的降级方向，而且只能往
+        // 目标同目录的中转名里复制——绝不许直接往 dest 上复制。
+        Err(error) if is_cross_device(&error) => copy_across_volumes(fs, staged, new),
+        Err(error) => Err(error),
+    }
+}
+
+/// 跨卷降级：复制到中转名，并核对写出的字节数（少了就是半截，直接判失败）。
+///
+/// 复制**不重试**：它不是占用问题，重来一次只会再搬几十 MB。失败后留下的半截文件由
+/// `install_with` 删掉（`fs::copy` 自己不会收拾）。
+fn copy_across_volumes(
+    fs: &dyn ReplaceFs,
+    staged: &StagedPackage,
+    new: &Path,
+) -> std::io::Result<()> {
+    let copied = fs.copy(staged.path(), new)?;
+    if copied != staged.size() {
+        return Err(std::io::Error::other(format!(
+            "跨卷复制只写出 {copied} 字节，暂存包是 {} 字节（拒绝把它顶到目标上）",
+            staged.size()
+        )));
+    }
+    Ok(())
+}
+
+fn failed(error: UpdateError, rolled_back: bool, backup_left: Option) -> InstallFailure {
+    InstallFailure {
+        error,
+        rolled_back,
+        backup_left,
+    }
+}
+
+fn tagged_path(dest: &Path, tag: &str) -> PathBuf {
+    let seq = SEQ.fetch_add(1, Ordering::Relaxed);
+    let name = dest.file_name().map_or_else(
+        || String::from("ull"),
+        |name| name.to_string_lossy().into_owned(),
+    );
+    let tagged = format!(".{name}.{tag}-{}-{seq}", std::process::id());
+    match dest.parent() {
+        Some(parent) => parent.join(tagged),
+        None => PathBuf::from(tagged),
+    }
+}
+
+/// 旧版本的备份路径：`/.<文件名>.ullold--`。
+///
+/// 点号开头在 Unix 上是隐藏文件，也和 `download` 的 `.ullpart-*` 中间文件一个家族；
+/// 必须同目录，因为 `rename` **不能跨卷**（Unix 返回 `EXDEV`，Windows 返回
+/// `ERROR_NOT_SAME_DEVICE`——`std` 的 `fs::rename` 不带 `MOVEFILE_COPY_ALLOWED`，
+/// 不会偷偷降级成复制）。
+#[must_use]
+pub fn backup_path(dest: &Path) -> PathBuf {
+    tagged_path(dest, OLD_TAG)
+}
+
+/// 新版本的中转名：`/.<文件名>.ullnew--`。
+///
+/// **必须与 dest 同目录**：这是「不经复制就把新字节原子地放到目标位置上」的全部前提。
+fn new_path(dest: &Path) -> PathBuf {
+    tagged_path(dest, NEW_TAG)
+}
+
+/// 清同目录里的替换残留：只留最近一份旧版本备份，顺带扫掉更早失败遗留的中转名。
+///
+/// * `keep = Some(本次新建的备份)`：删掉同目录里**同名目标**更早的 `.<名>.ullold-*`，只留这一份；
+/// * `keep = None`（本次安装前 `dest` 本来不存在）：**一个 `.ullold-*` 都不动**，只清 `.ullnew-*`。
+///
+/// `keep = None` 这条例外是 M171 r2 P3-2 的结论：`.<名>.ullold-*` 在那个时刻极可能是**用户旧版本
+/// 唯一幸存的副本**——上一次安装在「dest → 备份」之后、「中转名 → dest」之前被杀（掉电、被结束
+/// 进程），于是 dest 空着、旧字节全在备份里。把它当垃圾删掉，用户就彻底失去手工恢复的材料；
+/// 而修前（没有清理）根本不会删。宁可留一份几十 MB 的垃圾：等 dest 重新存在（下一次成功替换
+/// ⇒ `keep = Some`），这些旧备份会自然收敛成一份。
+///
+/// `.ullnew-*` 则任何时候都是垃圾：本次那份在被调用前已经改名成 dest 了，还留着的只可能是
+/// 更早某次失败遗留的中转文件（本次失败路径自己会删，删不掉才会留到这里）。
+///
+/// 删失败不当错误（只是垃圾文件，下次 apply 再清）；只在替换成功之后调用，所以正在用的
+/// 那一份（`keep`）不会被动。
+///
+/// 前提是「同一个 exe 只有一个更新者在动」。两个进程同时替换同一路径本来就不成立：
+/// 后一个回滚会把前一个刚装上的新版本换成旧字节。这条不因为保留多份而变好，反倒因为
+/// 每份都是几十 MB 的 exe 而变坏。
+fn prune_stale_artifacts(keep: Option<&Path>, dest: &Path) {
+    let (Some(dir), Some(name)) = (dest.parent(), dest.file_name()) else {
+        return;
+    };
+    let Ok(entries) = fs::read_dir(dir) else {
+        return;
+    };
+    let name = name.to_string_lossy();
+    let old_prefix = format!(".{name}.{OLD_TAG}-");
+    let new_prefix = format!(".{name}.{NEW_TAG}-");
+    for entry in entries.flatten() {
+        let path = entry.path();
+        if Some(path.as_path()) == keep {
+            continue;
+        }
+        let stale = path.file_name().is_some_and(|other| {
+            let other = other.to_string_lossy();
+            other.starts_with(&new_prefix) || (keep.is_some() && other.starts_with(&old_prefix))
+        });
+        if stale {
+            let _ = fs::remove_file(&path);
+        }
+    }
+}
diff --git a/crates/core/src/update/job.rs b/crates/core/src/update/job.rs
new file mode 100644
index 0000000..2a0f750
--- /dev/null
+++ b/crates/core/src/update/job.rs
@@ -0,0 +1,329 @@
+//! 「检查 → 取包 → 长度/SHA256 双检 → 原子替换」的一条龙：**GUI 与 CLI 的唯一入口**。
+//!
+//! # 为什么要有本模块
+//!
+//! mission 的硬要求是「GUI 与 CLI 行为一致，不许两套逻辑」。两个壳子各自拼一遍「选源 + 定目标 +
+//! 暂存 + 校验 + 替换」，迟早会漂：一处忘了摘要校验，一处把暂存放在数据根之外，一处把「没有更新」
+//! 当成错误。所以这些决定收成一个 [`Job`]：
+//!
+//! ```text
+//! Job { source, target, staging, dest }
+//!      ├─ check(current, channel)  → CheckOutcome   （版本比较/渠道准入都在 checker）
+//!      └─ apply(current, channel)  → Applied        （复查 → 取包 → 双检 → 替换）
+//! ```
+//!
+//! # 应用为什么先复查一次
+//!
+//! 用户点「安装」离上次检查可能已过几分钟，期间发布侧可能换了包。清单只有几 KB，复查一次换来
+//! 两个好处：装的一定是**此刻**最新的那一份；`apply` 自带「现在到底有没有得装」的答案，
+//! 不必让调用方信任内存里的旧候选。
+//!
+//! # 失败时的文件去哪
+//!
+//! 校验失败：暂存文件由 [`stage`] 就地删掉（[`super::verify::StagedPackage`] 的 `Drop` 再兜一层），
+//! **不留在原地**。替换失败：由 [`install_staged`] 回滚，旧版本仍在原路径上。两件事都不需要调用方记得做。
+//!
+//! # 换源
+//!
+//! 生产源是 D50 定死的 GitHub Releases（[`default_source`]）；**测试通道**（带 `update-test-source`
+//! feature 编出来的二进制 + [`UPDATE_DIR_ENV`] + [`UPDATE_TEST_SOURCE_ENV`] 三档全给）时改走
+//! [`super::source::DirSource`]——那是取证/内网手工分发的口子，**不是**第二个更新源。判据、隔离
+//! 手段与残余风险见 [`test_source_root`]。
+
+use std::path::{Path, PathBuf};
+use std::sync::Arc;
+
+use crate::download::DownloadEngine;
+
+use super::channel::Channel;
+use super::checker::{CheckOutcome, UpdateChecker};
+use super::error::UpdateError;
+use super::github::GitHubReleaseSource;
+use super::install::{install_staged, InstallReceipt, ReplacePolicy};
+use super::manifest::Artifact;
+#[cfg(feature = "update-test-source")]
+use super::source::DirSource;
+use super::source::UpdateSource;
+use super::target::{PackageFormat, Target};
+use super::verify::stage;
+use super::version::Version;
+
+/// 测试通道的源根（取证 / 内网手工分发）：指向一个 `DirSource` 根目录（`/stable.json`）。
+///
+/// 只在**带 `update-test-source` feature** 编出来的二进制里生效，且**单独设它没有用**：还要
+/// [`UPDATE_TEST_SOURCE_ENV`]（判据见 `test_source_root`）。默认构建里这两个变量纯粹是死字符串。
+pub const UPDATE_DIR_ENV: &str = "ULL_UPDATE_DIR";
+
+/// 测试通道的显式承认开关：值必须是 `1`，[`UPDATE_DIR_ENV`] 才会被认（同样只在 feature 构建里）。
+///
+/// 两个变量分开是为了「路径」与「我知道我在用测试源」这两件事各自留痕：只漏出一个路径
+/// （继承的环境、别的脚本 export 过）不足以把启动器的更新源改走本地目录。
+pub const UPDATE_TEST_SOURCE_ENV: &str = "ULL_UPDATE_TEST_SOURCE";
+
+/// [`UPDATE_TEST_SOURCE_ENV`] 唯一认的值（`true` / `yes` / `on` 一律不算：手误不该开闸）。
+#[cfg(feature = "update-test-source")]
+const TEST_SOURCE_ACK: &str = "1";
+
+/// 一次应用的结局。
+#[derive(Debug)]
+pub enum Applied {
+    /// 替换成功（新版本已经就位，等重启）。
+    Installed {
+        /// 收据（目标路径 + 旧版本备份 + 字节数）。
+        receipt: InstallReceipt,
+        /// 装上的版本号。
+        version: String,
+    },
+    /// 复查时已经没有可装的更新（例如这期间别人替你升过）。
+    Nothing(CheckOutcome),
+}
+
+/// 一次检查/应用的全部输入。
+///
+/// 不含任何 UI 状态：谁在查、查完怎么展示是壳层的事。字段都可读，日志/诊断要什么有什么。
+pub struct Job {
+    source: Box,
+    target: Target,
+    staging: PathBuf,
+    dest: PathBuf,
+}
+
+impl std::fmt::Debug for Job {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("Job")
+            .field("source", &self.source.source_id())
+            .field("target", &self.target.as_str())
+            .field("staging", &self.staging)
+            .field("dest", &self.dest)
+            .finish()
+    }
+}
+
+impl Job {
+    /// 显式装配（测试用：源、目标平台、暂存、替换目标全都自己给）。
+    #[must_use]
+    pub fn new(
+        source: Box,
+        target: Target,
+        staging: impl Into,
+        dest: impl Into,
+    ) -> Self {
+        Self {
+            source,
+            target,
+            staging: staging.into(),
+            dest: dest.into(),
+        }
+    }
+
+    /// 本进程的默认装配：目标平台 = 编译目标，替换目标 = 本进程 exe，
+    /// 暂存 = `/update/staging`。
+    #[must_use]
+    pub fn for_process(source: Box, cache_root: &Path) -> Self {
+        Self::new(
+            source,
+            Target::current(),
+            staging_dir(cache_root),
+            process_dest(),
+        )
+    }
+
+    /// 换替换目标（`ull update apply --dest `、单测都走它）。
+    #[must_use]
+    pub fn with_dest(mut self, dest: impl Into) -> Self {
+        self.dest = dest.into();
+        self
+    }
+
+    /// 源 id（日志/事件里的 `source` 字段）。
+    #[must_use]
+    pub fn source_id(&self) -> &str {
+        self.source.source_id()
+    }
+
+    /// 绑定的目标平台。
+    #[must_use]
+    pub const fn target(&self) -> Target {
+        self.target
+    }
+
+    /// 暂存目录。
+    #[must_use]
+    pub fn staging(&self) -> &Path {
+        &self.staging
+    }
+
+    /// 替换目标（本进程 exe）。
+    #[must_use]
+    pub fn dest(&self) -> &Path {
+        &self.dest
+    }
+
+    /// 查一次更新。
+    ///
+    /// # Errors
+    ///
+    /// 清单取不到 / 清单不合法 / 渠道不符都返回 [`UpdateError`]；「没有更新」不是错误，
+    /// 走 [`CheckOutcome::UpToDate`]。
+    pub fn check(&self, current: &Version, channel: Channel) -> Result {
+        UpdateChecker::new(SourceRef(&*self.source), self.target).check(current, channel)
+    }
+
+    /// 下载 → 双检 → 原子替换。
+    ///
+    /// # Errors
+    ///
+    /// 复查失败、取包失败、长度/摘要不符、替换失败都返回 [`UpdateError`]；
+    /// 「复查之后没有可装的更新」不是错误，走 [`Applied::Nothing`]。
+    pub fn apply(&self, current: &Version, channel: Channel) -> Result {
+        let outcome = self.check(current, channel)?;
+        let Some(candidate) = outcome.candidate() else {
+            return Ok(Applied::Nothing(outcome));
+        };
+        // P3-6：清单只有 `target` 参与挑选（`Release::artifact_for` 只比平台），所以清单可以给
+        // win-x64 挂一个 msi；以前这里会把它直接 rename 成本进程的 exe（D50 明说「不做 MSI」）。
+        // 先按包形态挡一次，**挡在取包之前**：既不浪费下载，也不会在目标路径上留下任何东西。
+        ensure_self_replaceable(&candidate.artifact)?;
+        let staged = stage(&*self.source, &candidate.artifact, &self.staging)?;
+        let version = candidate.release.version.to_string();
+        match install_staged(&staged, &self.dest, ReplacePolicy::default()) {
+            Ok(receipt) => Ok(Applied::Installed { receipt, version }),
+            Err(failure) => Err(failure.error),
+        }
+    }
+}
+
+/// 这个包形态能不能**原地**变成启动器本体。
+///
+/// 只有「便携单文件 exe」（[`PackageFormat::PortableExe`]）可以：
+///
+/// | 形态 | 为什么不行 |
+/// |---|---|
+/// | `msi` / `dmg` / `deb` / `rpm` | D50 明说「不做 MSI」——那是系统包管理器的活（`needs_installer()`） |
+/// | `portable-zip` | 是压缩包，不是启动器本体：rename 到 exe 路径只会得到一个跑不起来的文件 |
+/// | `appimage` | Linux 的可执行镜像，Windows/macOS 上没有意义；且本模块只做「同目录改名换 exe」 |
+pub(super) fn self_replaceable(format: PackageFormat) -> bool {
+    matches!(format, PackageFormat::PortableExe)
+}
+
+/// 包形态不合规就拒绝（错误分类是 `InvalidManifest`：清单挂错了东西，换源/重试都没用）。
+fn ensure_self_replaceable(artifact: &Artifact) -> Result<(), UpdateError> {
+    if self_replaceable(artifact.format) {
+        return Ok(());
+    }
+    Err(UpdateError::invalid_manifest(format!(
+        "发布里的 {} 产物是 {} 形态，不能原地替换启动器：本启动器只做便携单文件 exe 的自替换\
+         （安装器形态请用系统包管理器；压缩包请解压后再用）",
+        artifact.target.as_str(),
+        artifact.format.as_str()
+    )))
+}
+
+/// `&dyn UpdateSource` 也能当源用（[`UpdateChecker`] 是泛型的，这里省掉一次装箱）。
+struct SourceRef<'a>(&'a dyn UpdateSource);
+
+impl UpdateSource for SourceRef<'_> {
+    fn source_id(&self) -> &str {
+        self.0.source_id()
+    }
+
+    fn fetch_manifest_documents(
+        &self,
+        channel: Channel,
+    ) -> Result, UpdateError> {
+        self.0.fetch_manifest_documents(channel)
+    }
+
+    fn fetch_artifact(
+        &self,
+        artifact: &super::manifest::Artifact,
+        dest: &Path,
+    ) -> Result {
+        self.0.fetch_artifact(artifact, dest)
+    }
+}
+
+/// 本进程要替换的目标（拿不到 `current_exe` 时留一个占位名，让错误信息里至少有个名字）。
+#[must_use]
+pub fn process_dest() -> PathBuf {
+    std::env::current_exe().unwrap_or_else(|_| PathBuf::from("unlucky-launcher"))
+}
+
+/// 暂存目录（`/update/staging`）。
+#[must_use]
+pub fn staging_dir(cache_root: &Path) -> PathBuf {
+    cache_root.join("update").join("staging")
+}
+
+/// 生产源：GitHub Releases（D50）；**带 `update-test-source` feature 的构建**里，测试通道开启时
+/// （`test_source_root`）走本地目录源。
+#[must_use]
+pub fn default_source(engine: Arc) -> Box {
+    // 测试通道（M169）：整段只在带 feature 的构建里存在。默认关 ⇒ 官方发布产物里
+    // `test_source_root` 根本编不出来，`DirSource` 也进不了这条入口（编译期事实，不看运行时）。
+    #[cfg(feature = "update-test-source")]
+    if let Some(root) = test_source_root() {
+        return Box::new(DirSource::new(root));
+    }
+    Box::new(GitHubReleaseSource::new(engine))
+}
+
+/// 测试通道的判据：**feature 编进来 + 两档环境变量给全**，才返回本地源根。
+///
+/// # 为什么判据从「只看构建画像」改成「feature + 两档显式承认」
+///
+/// M159 的判据是 `cfg!(debug_assertions)`：`--release` 里整段被常量折叠掉，于是**发布产物没法
+/// 指向本地更新源**，而发布产物正是 release，`ull update apply` 又会替换本进程 exe——这条链在
+/// release 上从来没有端到端证据（M167 的结论）。要补这一环，判据必须与「是不是 debug」脱钩。
+///
+/// M169 的三档（tower 定案 B，理由不是省事而是攻击面）：
+///
+/// | 档 | 怎么给 | 作用 |
+/// |---|---|---|
+/// | 编译期 | `--features update-test-source` | 这段代码**才存在**；官方发布构建不带它 |
+/// | 路径 | `ULL_UPDATE_DIR=` | 本地源根（`/stable.json` + 产物） |
+/// | 承认 | `ULL_UPDATE_TEST_SOURCE=1` | 「我知道这是测试通道」；值必须是 `1`，`true`/`yes` 不算 |
+///
+/// 只给路径（或只设环境变量）什么都不会发生：**默认构建里这段函数根本不存在**。
+///
+/// # 隔离手段（逐条；别只信「有闸门」）
+///
+/// 1. **编译期不存在**：默认 features 关，官方发布二进制里没有这条路径——这是 README 里
+///    「release builds do not contain that path at all」这句承诺的落点。
+/// 2. **不是默认**：feature 打开之后，还要两个环境变量同时给；判据是纯函数
+///    （`test_source_root_from`），每种半开都有单测。
+/// 3. **不是用户面开关**：没有设置键、没有命令行参数、不落盘；每次 [`default_source`] 重读环境
+///    变量，同一个进程里改了就立刻生效/失效（不留缓存）。
+/// 4. **输出里点名**：`ull update check --json` 的信封里 `data.source` 是 `file:`、
+///    `data.test_source` 是 `true`（判据派生自**实际用了哪个源**，不是回读环境变量），人读输出另有
+///    一行「测试通道生效」。
+/// 5. **发布流程不碰它**：`packaging/check_test_source_off.py` 扫 `.github/workflows/**`、
+///    `packaging/*.py|*.sh` 与各 `Cargo.toml` 的 `default`，任何一处打开它就红（CI 的
+///    release-guard job 跑它）。
+///
+/// # 这条闸门**不是**权限边界
+///
+/// 谁能在 Windows 上给 GUI 设进程环境变量，谁就已经能以该用户身份运行任意程序。真正要守的是
+/// 「**官方二进制里不存在第二条更新源**」——第 1 条（编译期）才是这件事的判据，第 2-5 条是纵深。
+#[cfg(feature = "update-test-source")]
+pub(super) fn test_source_root() -> Option {
+    let dir = std::env::var(UPDATE_DIR_ENV).ok();
+    let ack = std::env::var(UPDATE_TEST_SOURCE_ENV).ok();
+    test_source_root_from(dir.as_deref(), ack.as_deref())
+}
+
+/// [`test_source_root`] 的纯判据（不碰进程环境：单测直接喂两档，并行跑也不会互相干扰）。
+///
+/// 空路径按「没给」处理（`ULL_UPDATE_DIR=` 这种写法很常见，不该被当成「当前目录」）；
+/// 承认档两侧空白忽略、大小写不忽略（`1` 就是 `1`）。
+#[cfg(feature = "update-test-source")]
+pub(super) fn test_source_root_from(dir: Option<&str>, ack: Option<&str>) -> Option {
+    if ack.map(str::trim) != Some(TEST_SOURCE_ACK) {
+        return None;
+    }
+    let root = dir?.trim();
+    if root.is_empty() {
+        return None;
+    }
+    Some(PathBuf::from(root))
+}
diff --git a/crates/core/src/update/manifest.rs b/crates/core/src/update/manifest.rs
new file mode 100644
index 0000000..59e2937
--- /dev/null
+++ b/crates/core/src/update/manifest.rs
@@ -0,0 +1,263 @@
+//! 发布清单模型：一个渠道一份 JSON，列出该渠道已知的所有发布与各平台的产物。
+//!
+//! 字段形状取自 `DevDocs/analyse/07-settings-packaging-update-p2.md` §6.2 的扩展清单，
+//! 但**只留与更新源无关的部分**：清单里没有任何 CDN 常量，`url` 是字符串，怎么解析由
+//! [`crate::update::UpdateSource`] 的实现决定。
+//!
+//! ```json
+//! {
+//!   "channel": "stable",
+//!   "releases": [
+//!     {
+//!       "version": "0.3.0",
+//!       "channel": "stable",
+//!       "released_at": "2026-01-02T03:04:05Z",
+//!       "notes": "修掉启动崩溃",
+//!       "force": false,
+//!       "min_supported": "0.2.0",
+//!       "artifacts": [
+//!         {"target": "win-x64", "format": "portable-zip", "url": "ull-0.3.0-win-x64.zip",
+//!          "size": 22100000, "sha256": "…"}
+//!       ]
+//!     }
+//!   ]
+//! }
+//! ```
+//!
+//! 读的方向刻意严格（`deny_unknown_fields` + 逐字段校验）：清单是我们自己发的东西，
+//! 拼错的字段名宁可在 CI 上炸掉，也别在用户机器上变成「查不到更新」。
+//!
+//! # 校验规则（`from_json` 会一次性查完）
+//!
+//! * `version` / `min_supported` 必须是合法 semver；
+//! * 同一份清单里 `version` 不许重复（重复意味着「升到哪个」没有确定答案）；
+//! * `size` 必须 > 0（0 字节的包只可能是发布脚本写漏了）；
+//! * 每个产物必须带 `sha256` 或 `sha1`，且长度/字符集合法（两者都带时以 `sha256` 为准）；
+//! * `url` 不许为空。
+//!
+//! `released_at` / `notes` 只做展示，不解析成时间类型（core 不引时间库，排序只看版本号）。
+
+use serde::Deserialize;
+
+use crate::download::Integrity;
+
+use super::channel::Channel;
+use super::error::{UpdateError, UpdateErrorKind};
+use super::target::{PackageFormat, Target};
+use super::version::Version;
+
+/// 一个渠道的发布清单。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ReleaseManifest {
+    /// 这份清单属于哪个渠道。
+    pub channel: Channel,
+    /// 已发布的版本（顺序无所谓：选版本的是 checker，不是清单的书写顺序）。
+    pub releases: Vec,
+}
+
+impl ReleaseManifest {
+    /// 解析清单 JSON 并做完整校验。
+    ///
+    /// # Errors
+    ///
+    /// JSON 语法错、字段名拼错、版本号/摘要/长度不合法都返回 [`UpdateError`]，
+    /// 分类是 [`UpdateErrorKind::InvalidManifest`] 或 [`UpdateErrorKind::InvalidVersion`]。
+    pub fn from_json(text: &str) -> Result {
+        let raw: RawManifest = serde_json::from_str(text).map_err(|error| {
+            UpdateError::invalid_manifest(format!("清单 JSON 解析失败：{error}"))
+        })?;
+        let channel = Channel::parse(&raw.channel)?;
+        let mut releases = Vec::with_capacity(raw.releases.len());
+        for raw_release in raw.releases {
+            let release = Release::from_raw(channel, raw_release)?;
+            if releases
+                .iter()
+                .any(|existing: &Release| existing.version == release.version)
+            {
+                return Err(UpdateError::invalid_manifest(format!(
+                    "清单 {} 里版本 {} 出现多次",
+                    channel, release.version
+                )));
+            }
+            releases.push(release);
+        }
+        Ok(Self { channel, releases })
+    }
+
+    /// 清单里该目标平台的最高可用版本（不看渠道准入，纯查表；选择逻辑在 checker）。
+    #[must_use]
+    pub fn newest_artifact_for(&self, target: Target) -> Option<(&Release, &Artifact)> {
+        self.releases
+            .iter()
+            .filter_map(|release| {
+                release
+                    .artifact_for(target)
+                    .map(|artifact| (release, artifact))
+            })
+            .max_by(|left, right| left.0.version.cmp(&right.0.version))
+    }
+}
+
+/// 一次发布。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Release {
+    /// 版本号。
+    pub version: Version,
+    /// 这次发布自报的渠道（可以比清单渠道更稳，例如 beta 清单里放一个 stable 补丁版）。
+    pub channel: Channel,
+    /// 发布时间（RFC3339 字符串，仅展示）。
+    pub released_at: Option,
+    /// 更新说明（纯文本，仅展示）。
+    pub notes: Option,
+    /// 是否强制更新（不看版本号也得升）。
+    pub force: bool,
+    /// 客户端最低支持版本：当前版本低于它就必须升（发布侧收回老版本的支持）。
+    pub min_supported: Option,
+    /// 各平台的产物。清单里的顺序 = 同一目标多形态时的优先级。
+    pub artifacts: Vec,
+}
+
+impl Release {
+    /// 该目标平台的首选产物（清单顺序即优先级；一个都没有就返回 `None`）。
+    #[must_use]
+    pub fn artifact_for(&self, target: Target) -> Option<&Artifact> {
+        self.artifacts
+            .iter()
+            .find(|artifact| artifact.target == target)
+    }
+
+    /// 当前版本是否低于本发布要求的最低支持版本。
+    #[must_use]
+    pub fn below_min_supported(&self, current: &Version) -> bool {
+        self.min_supported
+            .as_ref()
+            .is_some_and(|minimum| current < minimum)
+    }
+
+    fn from_raw(manifest_channel: Channel, raw: RawRelease) -> Result {
+        let version = Version::parse(&raw.version)?;
+        let channel = match &raw.channel {
+            Some(text) => Channel::parse(text)?,
+            None => manifest_channel,
+        };
+        let min_supported = raw
+            .min_supported
+            .as_deref()
+            .map(Version::parse)
+            .transpose()?;
+        let mut artifacts = Vec::with_capacity(raw.artifacts.len());
+        for raw_artifact in raw.artifacts {
+            artifacts.push(Artifact::from_raw(&version, raw_artifact)?);
+        }
+        Ok(Self {
+            version,
+            channel,
+            released_at: raw.released_at,
+            notes: raw.notes,
+            force: raw.force,
+            min_supported,
+            artifacts,
+        })
+    }
+}
+
+/// 一份可下载的产物。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Artifact {
+    /// 目标平台。
+    pub target: Target,
+    /// 包形态。
+    pub format: PackageFormat,
+    /// 更新源内部的地址（怎么解释由源实现决定：相对路径 / `file://` / `https://`）。
+    pub url: String,
+    /// 字节数（下载后必须**恰好**这么多，短了就是截断）。
+    pub size: u64,
+    /// 期望摘要（已归一化为小写十六进制）。
+    pub integrity: Integrity,
+}
+
+impl Artifact {
+    fn from_raw(version: &Version, raw: RawArtifact) -> Result {
+        let target = Target::parse(&raw.target).ok_or_else(|| {
+            UpdateError::invalid_manifest(format!(
+                "版本 {version} 的产物 target `{}` 无法识别（形如 win-x64 / mac-arm64 / linux-x64）",
+                raw.target
+            ))
+        })?;
+        let format = PackageFormat::parse(&raw.format).ok_or_else(|| {
+            UpdateError::invalid_manifest(format!(
+                "版本 {version} 的产物 format `{}` 无法识别",
+                raw.format
+            ))
+        })?;
+        if raw.url.trim().is_empty() {
+            return Err(UpdateError::invalid_manifest(format!(
+                "版本 {version}（{target}）的产物 url 为空"
+            )));
+        }
+        if raw.size == 0 {
+            return Err(UpdateError::invalid_manifest(format!(
+                "版本 {version}（{target}）的产物 size 为 0"
+            )));
+        }
+        let integrity = match (raw.sha256, raw.sha1) {
+            (Some(hex), _) => Integrity::sha256(hex),
+            (None, Some(hex)) => Integrity::sha1(hex),
+            (None, None) => {
+                return Err(UpdateError::invalid_manifest(format!(
+                    "版本 {version}（{target}）的产物既没有 sha256 也没有 sha1"
+                )));
+            }
+        };
+        if !integrity.is_well_formed() {
+            return Err(UpdateError::new(
+                UpdateErrorKind::InvalidManifest,
+                format!(
+                    "版本 {version}（{target}）的 {} 摘要格式不合法（应为 {} 位十六进制）",
+                    integrity.algo.as_str(),
+                    integrity.algo.hex_len()
+                ),
+            ));
+        }
+        Ok(Self {
+            target,
+            format,
+            url: raw.url,
+            size: raw.size,
+            integrity,
+        })
+    }
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct RawManifest {
+    channel: String,
+    #[serde(default)]
+    releases: Vec,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct RawRelease {
+    version: String,
+    channel: Option,
+    released_at: Option,
+    notes: Option,
+    #[serde(default)]
+    force: bool,
+    min_supported: Option,
+    #[serde(default)]
+    artifacts: Vec,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct RawArtifact {
+    target: String,
+    format: String,
+    url: String,
+    size: u64,
+    sha256: Option,
+    sha1: Option,
+}
diff --git a/crates/core/src/update/mod.rs b/crates/core/src/update/mod.rs
new file mode 100644
index 0000000..18117c2
--- /dev/null
+++ b/crates/core/src/update/mod.rs
@@ -0,0 +1,104 @@
+//! 自更新内核：版本比较、发布清单、渠道准入、下载校验、原子替换。
+//!
+//! 更新源已定（D50）：**GitHub Releases 是唯一更新源**，真实实现在
+//! [`GitHubReleaseSource`]（清单固定地址 + 产物走 `core::download` 引擎）。
+//! 这一层仍然保持源无关：核心只认 [`UpdateSource`] 三个方法，接哪家由上层注入
+//! （本地目录源 [`DirSource`] 留作对拍基准、内网手工分发与**测试通道**）。
+//!
+//! 测试通道不是第二个更新源：`update-test-source` feature（默认关）+ `ULL_UPDATE_DIR` +
+//! `ULL_UPDATE_TEST_SOURCE=1` 三档全给才会把 [`default_source`] 换成本地目录（判据、隔离手段与
+//! 为什么用编译期 feature 见 `job::test_source_root` 的文档）。
+//!
+//! 设计输入：`DevDocs/analyse/07-settings-packaging-update-p2.md` §4（HMCL 自更新）与 §6.2
+//! （多平台清单扩展）。我们抄骨架、补两处 HMCL 明确放弃的东西：**回滚**与**按平台分发**。
+//!
+//! # 一条完整的更新链
+//!
+//! ```text
+//! UpdateChecker::check(current, channel)   清单 + 版本 + 渠道 + 目标平台 → 结论
+//!         │  Available(candidate)
+//!         ├─ UpdateChecker::prepare(candidate, staging)   取包 → 长度/摘要双检
+//!         │        │  StagedPackage（校验通过，失败已自动清理）
+//!         │        └─ install::install_staged(...)        改名旧版 → 搬入新版（失败回滚）
+//!         └─ UpToDate / MissingArtifact
+//! ```
+//!
+//! # 分层
+//!
+//! ```text
+//! version   语义化版本解析与排序（alpha/beta/rc、build metadata）  channel  渠道阶梯与准入
+//! manifest  清单模型 + JSON 校验            target   目标平台与包形态
+//! source    UpdateSource trait + 本地目录源  github   GitHub Releases 源（D50）
+//! verify    暂存 + 长度/摘要校验             checker   选择哪一份发布、急不急
+//! signature 清单签名信封 + 验签             trust     钉进二进制的公钥表（keyring）
+//! ed25519   Ed25519 严格验签（ed25519-dalek::verify_strict 的薄封装）
+//! install   原子替换 + 回滚                  replace_io 改名/复制/重试与跨卷判据（注入点）
+//! error     分类与文案                      job       检查/应用的一条龙（GUI 与 CLI 共用同一入口）
+//! ```
+//!
+//! # 跨卷（M171）
+//!
+//! 暂存目录在数据根下、目标 exe 在安装目录，两者可能不在同一卷（便携版放 U 盘、数据根在 D 盘而
+//! 程序在 C 盘）。`rename` 不能跨卷，所以 [`install_staged`] 先把新包落成**目标同目录**的
+//! `.ullnew-*` 中转名（同卷改名；跨卷才复制到这儿并核对字节数），再由一次同卷改名顶到目标位置。
+//! 目标路径上任何时刻都不是半截文件，同一卷路径也**不会多搬一个字节**。
+//!
+//! # 刻意不做的事
+//!
+//! * **不碰 UI**：本模块只产出可序列化的判定结果与错误分类，弹窗/进度/文案排版在壳层。
+//!   入口在 `crates/presenter`/`crates/app-iced` 接，`crates/core` 保持零 UI 依赖。
+//! * **不自己替换正在运行的 exe**：那需要「退出自身 → 另一个进程搬运」（HMCL 的
+//!   `--apply-to`），属启动器外壳的编排；本模块只保证搬运本身原子且可回滚。
+//! * **不装安装器形态**（msi/dmg/deb/rpm）：交给系统包管理器。
+//! * **不做差分/增量**：清单里没有 patch 字段，宁可每次全量，也别先上一套没验过的差分协议。
+//!
+//! # 信任根（M190）
+//!
+//! ```text
+//! 源只取字节 ──> signature::verify_manifest（清单**原始字节** + `manifest.json.sig`）
+//!                │  判据：钉死的公钥（trust::keyring，编译期常量）验 Ed25519
+//!                ├─ 过了 ──> manifest::from_json ──> checker/apply
+//!                └─ 不过 ──> 五类签名错误（不可重试），**什么都不会被安装**
+//! ```
+//!
+//! 一句话：**先验签、再解析**。清单的 sha256 只保证「包体和清单对上」，清单本身可不可信由签名回答——
+//! 两条判据互不替代（`tests/signature_cases.rs` 分别证明）。
+
+pub mod channel;
+pub mod checker;
+mod ed25519;
+pub mod error;
+pub mod github;
+pub mod install;
+pub mod job;
+pub mod manifest;
+mod replace_io;
+mod signature;
+pub mod source;
+pub mod target;
+mod trust;
+pub mod verify;
+pub mod version;
+
+pub use crate::download::{HashAlgo, Integrity};
+pub use crate::platform::os_info::OsFamily;
+
+pub use self::channel::Channel;
+pub use self::checker::{CheckOutcome, UpdateCandidate, UpdateChecker, Urgency};
+pub use self::error::{UpdateError, UpdateErrorKind};
+pub use self::github::GitHubReleaseSource;
+pub use self::install::{
+    backup_path, install_staged, InstallFailure, InstallReceipt, ReplacePolicy,
+};
+pub use self::job::{
+    default_source, process_dest, staging_dir, Applied, Job, UPDATE_DIR_ENV, UPDATE_TEST_SOURCE_ENV,
+};
+pub use self::manifest::{Artifact, Release, ReleaseManifest};
+pub use self::signature::VerifiedSignature;
+pub use self::source::{verified_manifest, DirSource, ManifestDocuments, UpdateSource};
+pub use self::target::{Arch, PackageFormat, Target};
+pub use self::verify::{stage, verify_file, StagedPackage};
+pub use self::version::{Stage, Version, VersionError};
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/core/src/update/replace_io.rs b/crates/core/src/update/replace_io.rs
new file mode 100644
index 0000000..52d09da
--- /dev/null
+++ b/crates/core/src/update/replace_io.rs
@@ -0,0 +1,129 @@
+//! 替换过程真正碰盘的三个动作（改名 / 复制 / 删除）+ 重试与跨卷判据。
+//!
+//! # 为什么抽成 trait
+//!
+//! 只为一件事：**故障注入**。两条最关键的坏路径在真盘上没法确定性复现——
+//!
+//! * 「跨卷 rename 被拒」（`EXDEV` / `ERROR_NOT_SAME_DEVICE`）：得先有第二块卷；
+//! * 「复制/改名到一半失败」：得让盘真的满，或者让杀软恰好在那 100ms 里咬住文件。
+//!
+//! 真实现 [`RealFs`] 就是 `std::fs` 的三个函数（薄到没有分支）；测试用注入器把上面两种
+//! 失败变成 `install_with` 上的确定性输入。抽的只有「动作」，**判据与顺序仍在 `install` 里**，
+//! 所以注入器能改的只是「系统调用成不成功」，改不了「失败时目标是否仍是旧版本」这条规矩。
+//!
+//! # 跨卷为什么不能退化成「直接覆盖」
+//!
+//! Windows 上正在运行的 exe 不能覆盖、只能改名；`rename` **不能跨卷**（`std` 不带
+//! `MOVEFILE_COPY_ALLOWED`，也不会偷偷降级成复制）。所以唯一既原子又能跨卷的姿势是：
+//! 先把字节搬到**目标同目录**的临时名（同卷内改名 = 原子），再由一次同卷改名把临时名换成目标名。
+//! 目标路径上的新字节永远来自一次原子命名，任何时刻都不存在「拷了一半的目标文件」。
+
+use std::fs;
+use std::io;
+use std::path::Path;
+use std::time::Duration;
+
+/// 替换策略：改名失败时重试几次、每次间隔多久。
+///
+/// 默认 5 次 × 80ms：足够扛过杀软扫描/索引器短暂占用，又不至于让用户在「更新」按钮上
+/// 干等半分钟。真正长期的占用（另一个启动器实例在跑）重试多少次都没用，直接报错更诚实。
+///
+/// 跨卷（`CrossesDevices`）**不重试**：换多少次都不会变成同卷，那是复制降级该接的信号
+/// （见 `install::materialize`）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct ReplacePolicy {
+    /// 总尝试次数（含首次），`0` 按 `1` 处理。
+    pub attempts: u32,
+    /// 两次尝试之间的等待。
+    pub delay: Duration,
+}
+
+impl Default for ReplacePolicy {
+    fn default() -> Self {
+        Self {
+            attempts: 5,
+            delay: Duration::from_millis(80),
+        }
+    }
+}
+
+impl ReplacePolicy {
+    /// 构造。
+    #[must_use]
+    pub const fn new(attempts: u32, delay: Duration) -> Self {
+        Self { attempts, delay }
+    }
+}
+
+/// 替换用到的三个文件动作（真实现 = `std::fs`）。
+pub(crate) trait ReplaceFs {
+    /// 同卷改名。
+    fn rename(&self, from: &Path, to: &Path) -> io::Result<()>;
+    /// 复制（跨卷降级用）；返回实际写出的字节数。
+    fn copy(&self, from: &Path, to: &Path) -> io::Result;
+    /// 删文件（清理中转名）。
+    fn remove(&self, path: &Path) -> io::Result<()>;
+}
+
+/// 真实现。
+pub(crate) struct RealFs;
+
+impl ReplaceFs for RealFs {
+    fn rename(&self, from: &Path, to: &Path) -> io::Result<()> {
+        fs::rename(from, to)
+    }
+
+    fn copy(&self, from: &Path, to: &Path) -> io::Result {
+        fs::copy(from, to)
+    }
+
+    fn remove(&self, path: &Path) -> io::Result<()> {
+        fs::remove_file(path)
+    }
+}
+
+/// 改名，失败时按策略重试（**只有占用类错误**值得重试）。
+pub(crate) fn rename_with_retry(
+    fs: &dyn ReplaceFs,
+    from: &Path,
+    to: &Path,
+    policy: ReplacePolicy,
+) -> io::Result<()> {
+    let attempts = policy.attempts.max(1);
+    let mut last = None;
+    for attempt in 0..attempts {
+        match fs.rename(from, to) {
+            Ok(()) => return Ok(()),
+            Err(error) => {
+                let retryable = is_transient(&error) && attempt + 1 < attempts;
+                if !retryable {
+                    return Err(error);
+                }
+                std::thread::sleep(policy.delay);
+                last = Some(error);
+            }
+        }
+    }
+    Err(last.unwrap_or_else(|| io::Error::other("rename 未执行")))
+}
+
+/// 是否属于「等一会儿可能就好了」的失败。
+///
+/// Windows 的共享冲突（`os error 32`）落在 `ErrorKind::Other` 里（`std` 没有专门的 kind），
+/// 所以这里必须把 `Other` 也算上；`PermissionDenied` 覆盖 `ACCESS_DENIED`（杀软持有的句柄）。
+/// `CrossesDevices` **不在**这里：它不是占用，是「这块地搬不过去」，重试零收益。
+pub(crate) fn is_transient(error: &io::Error) -> bool {
+    matches!(
+        error.kind(),
+        io::ErrorKind::PermissionDenied
+            | io::ErrorKind::Other
+            | io::ErrorKind::Interrupted
+            | io::ErrorKind::WouldBlock
+    )
+}
+
+/// 是否「源与目标不同卷」：Unix `EXDEV` / Windows `ERROR_NOT_SAME_DEVICE`，`std` 都映射到
+/// [`io::ErrorKind::CrossesDevices`]。
+pub(crate) fn is_cross_device(error: &io::Error) -> bool {
+    error.kind() == io::ErrorKind::CrossesDevices
+}
diff --git a/crates/core/src/update/signature.rs b/crates/core/src/update/signature.rs
new file mode 100644
index 0000000..eb7cafe
--- /dev/null
+++ b/crates/core/src/update/signature.rs
@@ -0,0 +1,256 @@
+//! 清单签名信封：`manifest.json.sig` 的解析与验签。
+//!
+//! # 为什么是**分离**的签名文件，而不是清单里的一个 `signatures` 字段
+//!
+//! 签名只能覆盖「签的时候那份字节」。把签名塞进清单本身，验签就得先把那个字段从 JSON 里摘出来
+//! 再规范化（空白、键序、数字写法全都得钉死），任何一处规范化差异都会让「同一份内容」有两种字节，
+//! 于是「改字节不改语义」的老把戏就回来了。分离文件把这件事变简单：**签名覆盖清单文件的原始字节**，
+//! 一个 bit 都不能变。顺序也就固定了：先验签，再解析。
+//!
+//! ```json
+//! {"format": 1,
+//!  "signatures": [
+//!    {"alg": "ed25519", "key_id": "ull-release-2026a", "sig": "<128 位十六进制>",
+//!     "manifest_sha256": "<64 位十六进制>"}
+//!  ]}
+//! ```
+//!
+//! `manifest_sha256` 是冗余但**有意**的：它让「清单变了而签名没跟着换」这种最常见的发布事故
+//! 给出**具体**原因（签名声明的是哪一份、手上是哪一份），而不是一句「验签失败」。它不参与判据
+//! ——判据永远是 Ed25519 的那条方程。
+//!
+//! # 多签名
+//!
+//! 数组里可以有任意多条，**任意一条**由钉死的钥验过就放行。这给了「新旧钥并存」的窗口期：
+//! 轮换期一份清单同时带旧钥与新钥签名，装着旧二进制的用户与装着新二进制的用户都过得去。
+//!
+//! # 判据顺序（每条都能单独变红）
+//!
+//! 1. 信封存在且能解析（`format` 必须是 1）；
+//! 2. 本构建钉了至少一把公钥（[`super::trust::keyring`] 非空）——空表一律拒，绝不「没钥就放行」；
+//! 3. 至少一条签名的 `key_id` 命中钉住的表，且它的 `alg` 是 `ed25519`；
+//! 4. 那条签名对**清单原始字节**验过；
+//! 5. 若签名带 `manifest_sha256`，与清单字节的 SHA-256 相符（只为给出可读原因，不替代第 4 条）。
+
+use serde::Deserialize;
+use sha2::{Digest, Sha256};
+
+use super::ed25519::{verify, PUBLIC_KEY_LEN, SIGNATURE_LEN};
+use super::error::{UpdateError, UpdateErrorKind};
+use super::trust;
+
+/// 信封格式版本（改字段形状要抬它，老客户端会以「格式不支持」明确拒绝，而不是静默不认签名）。
+pub(crate) const ENVELOPE_FORMAT: u32 = 1;
+
+/// 验收通过的签名摘要（进日志/CLI 输出：谁签的、用哪把钥验过的）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct VerifiedSignature {
+    /// 验过的 `key_id`。
+    pub key_id: String,
+    /// 算法标识（当前只有 `ed25519`）。
+    pub alg: String,
+}
+
+/// 清单的签名信封。
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct Envelope {
+    format: u32,
+    signatures: Vec,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct EnvelopeSignature {
+    alg: String,
+    key_id: String,
+    sig: String,
+    manifest_sha256: Option,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct RawEnvelope {
+    format: u32,
+    #[serde(default)]
+    signatures: Vec,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct RawEnvelopeSignature {
+    alg: String,
+    key_id: String,
+    sig: String,
+    manifest_sha256: Option,
+}
+
+/// 验一份清单的签名。
+///
+/// # Errors
+///
+/// * [`UpdateErrorKind::SignatureMissing`]：源里没有配套的签名文件；
+/// * [`UpdateErrorKind::SignatureMalformed`]：信封不是合法 JSON / 字段名拼错 / `format` 不认识；
+/// * [`UpdateErrorKind::KeyringEmpty`]：本构建一把公钥都没钉（正式表还没录钥）；
+/// * [`UpdateErrorKind::SignatureUnknownKey`]：所有签名的 `key_id` 都不在钉住的表里；
+/// * [`UpdateErrorKind::SignatureInvalid`]：命中了钥但对清单字节验不过（清单被改过、签名不是给这份的）。
+pub(crate) fn verify_manifest(
+    manifest_bytes: &[u8],
+    envelope_text: Option<&str>,
+) -> Result {
+    let Some(text) = envelope_text else {
+        return Err(UpdateError::new(
+            UpdateErrorKind::SignatureMissing,
+            "清单没有配套签名（清单旁边缺 `<清单名>.sig`）：本启动器只安装「清单签名对得上」的更新，\
+             没有签名一律拒装——这不是你的问题，是发布侧漏了签名",
+        ));
+    };
+    let envelope = parse_envelope(text)?;
+    let keys = trust::keyring();
+    if keys.is_empty() {
+        return Err(UpdateError::new(
+            UpdateErrorKind::KeyringEmpty,
+            "本构建没有钉任何清单签名公钥（正式表为空），因此任何清单都无法验签：\
+             请勿绕过，这是「还没录钥」的构建，不是清单有问题",
+        ));
+    }
+    let actual_sha256 = hex_sha256(manifest_bytes);
+    let mut unknown = Vec::new();
+    let mut attempted = Vec::new();
+    for signature in &envelope.signatures {
+        if signature.alg != "ed25519" {
+            unknown.push(format!("{}({})", signature.key_id, signature.alg));
+            continue;
+        }
+        let Some(pinned) = keys.iter().find(|key| key.key_id == signature.key_id) else {
+            unknown.push(format!("{}（未钉住）", signature.key_id));
+            continue;
+        };
+        let Some(public_key) = trust::decode_hex(pinned.public_key_hex) else {
+            return Err(UpdateError::invalid_manifest(format!(
+                "钉住的公钥 `{}` 不是合法十六进制（这是构建缺陷，不是清单的问题）",
+                pinned.key_id
+            )));
+        };
+        if public_key.len() != PUBLIC_KEY_LEN {
+            return Err(UpdateError::invalid_manifest(format!(
+                "钉住的公钥 `{}` 长 {} 字节，Ed25519 公钥必须是 {PUBLIC_KEY_LEN} 字节（构建缺陷）",
+                pinned.key_id,
+                public_key.len()
+            )));
+        }
+        let mut key_bytes = [0_u8; PUBLIC_KEY_LEN];
+        key_bytes.copy_from_slice(&public_key);
+        let Some(signature_bytes) = trust::decode_hex(&signature.sig) else {
+            attempted.push(format!("{}（`sig` 不是十六进制）", signature.key_id));
+            continue;
+        };
+        if signature_bytes.len() != SIGNATURE_LEN {
+            attempted.push(format!(
+                "{}（`sig` 长 {} 字节，应为 {SIGNATURE_LEN}）",
+                signature.key_id,
+                signature_bytes.len()
+            ));
+            continue;
+        }
+        let mut sig_bytes = [0_u8; SIGNATURE_LEN];
+        sig_bytes.copy_from_slice(&signature_bytes);
+        if !verify(&key_bytes, manifest_bytes, &sig_bytes) {
+            attempted.push(signature.key_id.clone());
+            continue;
+        }
+        // 第 5 条：只为「把话说清楚」，不替代上面那条方程。
+        if let Some(declared) = &signature.manifest_sha256 {
+            if declared.to_ascii_lowercase() != actual_sha256 {
+                return Err(UpdateError::new(
+                    UpdateErrorKind::SignatureInvalid,
+                    format!(
+                        "清单签名声明的是另一份清单（签名里的 sha256 = {}，手上这份 = {}）：\
+                         签名对上了、内容不是它签的那份",
+                        short(declared),
+                        short(&actual_sha256)
+                    ),
+                ));
+            }
+        }
+        return Ok(VerifiedSignature {
+            key_id: signature.key_id.clone(),
+            alg: signature.alg.clone(),
+        });
+    }
+    if attempted.is_empty() {
+        return Err(UpdateError::new(
+            UpdateErrorKind::SignatureUnknownKey,
+            format!(
+                "清单由本构建不认识的钥签名（{}）：本构建钉住的 key_id = [{}]。\
+                 要么清单是别人签的，要么发布侧用了还没进信任表的新钥",
+                unknown.join("、"),
+                keys.iter()
+                    .map(|key| key.key_id)
+                    .collect::>()
+                    .join(", ")
+            ),
+        ));
+    }
+    Err(UpdateError::new(
+        UpdateErrorKind::SignatureInvalid,
+        format!(
+            "清单签名验不过（key_id = {}，清单 sha256 = {}）：这份清单不是那把钥签的，\
+             或签名之后清单被改过。绝不安装",
+            attempted.join("、"),
+            short(&actual_sha256)
+        ),
+    ))
+}
+
+/// 解析信封（`deny_unknown_fields`：字段名拼错宁可在 CI/发布侧当场炸，也别在用户机器上变成「验签失败」）。
+fn parse_envelope(text: &str) -> Result {
+    let raw: RawEnvelope = serde_json::from_str(text).map_err(|error| {
+        UpdateError::new(
+            UpdateErrorKind::SignatureMalformed,
+            format!("清单签名文件不是合法 JSON（{error}）"),
+        )
+    })?;
+    if raw.format != ENVELOPE_FORMAT {
+        return Err(UpdateError::new(
+            UpdateErrorKind::SignatureMalformed,
+            format!(
+                "清单签名格式 {} 不认识（本构建只认 {ENVELOPE_FORMAT}）：请升级启动器",
+                raw.format
+            ),
+        ));
+    }
+    if raw.signatures.is_empty() {
+        return Err(UpdateError::new(
+            UpdateErrorKind::SignatureMalformed,
+            "清单签名文件里 `signatures` 是空的：签了个空",
+        ));
+    }
+    Ok(Envelope {
+        format: raw.format,
+        signatures: raw
+            .signatures
+            .into_iter()
+            .map(|item| EnvelopeSignature {
+                alg: item.alg,
+                key_id: item.key_id,
+                sig: item.sig,
+                manifest_sha256: item.manifest_sha256,
+            })
+            .collect(),
+    })
+}
+
+/// 清单字节的 SHA-256（小写十六进制）。
+pub(crate) fn hex_sha256(bytes: &[u8]) -> String {
+    let digest = Sha256::digest(bytes);
+    let mut out = String::with_capacity(64);
+    for byte in digest {
+        out.push_str(&format!("{byte:02x}"));
+    }
+    out
+}
+
+/// 日志/文案里只露前 8 位。
+fn short(hex: &str) -> String {
+    let trimmed: String = hex.trim().chars().take(8).collect();
+    format!("{trimmed}…")
+}
diff --git a/crates/core/src/update/source.rs b/crates/core/src/update/source.rs
new file mode 100644
index 0000000..eea1610
--- /dev/null
+++ b/crates/core/src/update/source.rs
@@ -0,0 +1,265 @@
+//! 更新源抽象：清单从哪来、包体从哪来，全部收在一个 trait 后面。
+//!
+//! 这一层刻意不写死任何 URL、任何厂商名：core 只认 [`UpdateSource`] 三个方法，接哪家由上层
+//! 注入。真实源已定（D50）：[`super::GitHubReleaseSource`]，它在 `github.rs`，网络与镜像策略
+//! 全交给 `crate::download`。
+//!
+//! 内置的另一个实现是 [`DirSource`]（本地目录 / `file://`），用途是测试、内网手工分发，
+//! 以及给远端实现当对拍基准。
+//!
+//! # 本地源的目录约定
+//!
+//! ```text
+//! /stable.json     渠道清单（文件名 = 渠道名 + .json）
+//! /stable.json.sig 清单签名信封（M190；缺了它清单一律拒装，见 `signature`）
+//! /beta.json
+//! /<产物文件>       清单里 url 写相对路径时，相对 root
+//! ```
+//!
+//! 清单里的 `url` 支持两种写法：`file://` 绝对地址，或相对 `` 的路径。
+//! 出现 `http://` / `https://` 一律 [`UpdateErrorKind::UnsupportedSource`]——那是别的
+//! 实现的活，本地源不该假装能取远端字节。
+
+use std::fs;
+use std::path::{Path, PathBuf};
+
+use super::channel::Channel;
+use super::error::{UpdateError, UpdateErrorKind};
+use super::manifest::{Artifact, ReleaseManifest};
+
+/// 源交出来的「清单两份原文」：清单本身 + 配套签名信封（M190）。
+///
+/// 刻意是**原文**而不是解析后的结构：签名只能覆盖字节，先解析再验签就等于给「解析器认了、
+/// 签名没认」的东西开了门。判据顺序因此固定为「先验签、再解析」，两者都在
+/// [`verified_manifest`] 里，源实现自己不做任何验签。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ManifestDocuments {
+    /// 清单原文（`manifest.json` / `.json` 的字节，按 UTF-8 解释）。
+    pub manifest: String,
+    /// 签名信封原文（`<清单名>.sig`）；`None` = 源里没有这份文件（会被判 [`UpdateErrorKind::SignatureMissing`]）。
+    pub signatures: Option,
+}
+
+/// 更新源：清单与包体的来源。
+///
+/// 实现必须是 `Send + Sync`（下载与替换可能在不同线程上跑），且**不持有运行时**：
+/// 同步签名是为了让 CLI 与 GUI 都能直接调用，异步实现自己在方法里桥接。
+pub trait UpdateSource: Send + Sync {
+    /// 源标识（日志/事件里的 `source` 字段，如 `file:D:\dist`；健康度也按它归并）。
+    fn source_id(&self) -> &str;
+
+    /// 取某渠道清单的两份原文；`Ok(None)` = 该渠道还没发布过（不是错误）。
+    ///
+    /// # Errors
+    ///
+    /// 读不到文件、响应为空、网络失败都返回 [`UpdateError`]。**这里不验签、不解析**
+    /// （见 [`ManifestDocuments`]）——管线的下一站是 [`verified_manifest`]。
+    fn fetch_manifest_documents(
+        &self,
+        channel: Channel,
+    ) -> Result, UpdateError>;
+
+    /// 把产物取到 `dest`，返回写入的字节数。
+    ///
+    /// 实现只管「把字节放到 dest」；长度与摘要校验由 [`crate::update::verify`] 统一做，
+    /// 别在实现里各写一套。
+    ///
+    /// # Errors
+    ///
+    /// 源里没有这个文件、读失败、写 `dest` 失败都返回 [`UpdateError`]。
+    fn fetch_artifact(&self, artifact: &Artifact, dest: &Path) -> Result;
+}
+
+/// 取清单 → 验签 → 解析 → 渠道校验（**唯一**入口，GUI 与 CLI 共用）。
+///
+/// 它是个**自由函数**而不是 trait 的默认方法：trait 方法可被任何实现方覆写，那样「信任根的收口点」
+/// 就只剩纪律（M190 r1 复审 P2-2）。删掉那条默认实现之后，调用方手里只有源交出来的**原文**
+/// （[`ManifestDocuments`]），想绕过验签就必须自己重写一遍解析 + 渠道判据 —— 不再是「一行覆写」。
+///
+/// # Errors
+///
+/// 源里没有该渠道清单 ⇒ `Ok(None)`；签名/解析/渠道任一不过 ⇒ [`UpdateError`]。
+/// 签名相关的分类见 [`UpdateErrorKind::is_signature`]，它们**不可重试**。
+pub fn verified_manifest(
+    source: &S,
+    channel: Channel,
+) -> Result, UpdateError> {
+    let Some(documents) = source.fetch_manifest_documents(channel)? else {
+        return Ok(None);
+    };
+    // ① 先验签：拿到的是不是「我们发的那份字节」，在这里一次说清。
+    let source_label = source.source_id().to_string();
+    super::signature::verify_manifest(
+        documents.manifest.as_bytes(),
+        documents.signatures.as_deref(),
+    )
+    .map_err(|mut error| {
+        error.message = format!("{}（来源 {source_label}）", error.message);
+        error
+    })?;
+    // ② 再解析：到了这一步，字节已经是发布侧签过的那份，解析失败只可能是签名者也写错了。
+    let manifest = ReleaseManifest::from_json(&documents.manifest).map_err(|mut error| {
+        error.message = format!("{}（来源 {source_label}）", error.message);
+        error
+    })?;
+    // ③ 渠道：清单自报的渠道与请求的对不上是源的问题，不能悄悄当成「没有更新」。
+    if manifest.channel != channel {
+        return Err(UpdateError::new(
+            UpdateErrorKind::ChannelMismatch,
+            format!(
+                "请求的是 {channel} 渠道，清单（源 {}）自报 {}",
+                source.source_id(),
+                manifest.channel
+            ),
+        ));
+    }
+    Ok(Some(manifest))
+}
+
+/// `Box` 也是 `UpdateSource`。
+///
+/// 为什么需要：壳层要**运行期**才决定用哪个源（生产走 GitHub、测试/内网走本地目录），而
+/// [`super::UpdateChecker`] 与 [`super::verify::stage`] 都是按 trait 泛型化的。没有这条转发，
+/// 调用方只能给每种源写一份检查/下载流程——那正是 mission 禁止的「两套逻辑」。
+impl UpdateSource for Box {
+    fn source_id(&self) -> &str {
+        (**self).source_id()
+    }
+
+    fn fetch_manifest_documents(
+        &self,
+        channel: Channel,
+    ) -> Result, UpdateError> {
+        (**self).fetch_manifest_documents(channel)
+    }
+
+    fn fetch_artifact(&self, artifact: &Artifact, dest: &Path) -> Result {
+        (**self).fetch_artifact(artifact, dest)
+    }
+}
+
+/// 本地目录源（也接受 `file://` 根地址）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct DirSource {
+    root: PathBuf,
+    id: String,
+}
+
+impl DirSource {
+    /// 用本地目录构造。
+    #[must_use]
+    pub fn new(root: impl Into) -> Self {
+        let root = root.into();
+        let id = format!("file:{}", root.display());
+        Self { root, id }
+    }
+
+    /// 用 `file://` 地址构造（`file:///D:/dist`、`file:///srv/ull`）。
+    ///
+    /// # Errors
+    ///
+    /// 不是 `file://` 开头的地址返回 [`UpdateErrorKind::UnsupportedSource`]。
+    pub fn from_url(url: &str) -> Result {
+        let rest = url
+            .strip_prefix("file://")
+            .ok_or_else(|| unsupported_source(url))?;
+        Ok(Self::new(file_url_to_path(rest)))
+    }
+
+    /// 根目录。
+    #[must_use]
+    pub fn root(&self) -> &Path {
+        &self.root
+    }
+
+    /// 某渠道的清单文件路径。
+    #[must_use]
+    pub fn manifest_path(&self, channel: Channel) -> PathBuf {
+        self.root.join(format!("{}.json", channel.as_str()))
+    }
+
+    /// 某渠道清单的签名文件路径（`stable.json` → `stable.json.sig`）。
+    #[must_use]
+    pub fn signature_path(&self, channel: Channel) -> PathBuf {
+        self.root.join(format!("{}.json.sig", channel.as_str()))
+    }
+
+    /// 把清单里的 `url` 解析成源侧本地路径。
+    fn resolve(&self, url: &str) -> Result {
+        if let Some(rest) = url.strip_prefix("file://") {
+            return Ok(file_url_to_path(rest));
+        }
+        if url.contains("://") {
+            return Err(unsupported_source(url));
+        }
+        Ok(self.root.join(url))
+    }
+}
+
+fn unsupported_source(url: &str) -> UpdateError {
+    let hint = if url.starts_with("http://") || url.starts_with("https://") {
+        "本地目录源不取远端字节，请换用实现远端源的 UpdateSource"
+    } else {
+        "只支持本地相对路径与 file:// 地址"
+    };
+    UpdateError::new(
+        UpdateErrorKind::UnsupportedSource,
+        format!("更新源不支持地址 `{url}`：{hint}"),
+    )
+}
+
+fn file_url_to_path(rest: &str) -> PathBuf {
+    if cfg!(windows) {
+        // file:///D:/dist → 去掉盘符前的斜杠；Windows 上没有「以 / 开头的当前盘路径」这种写法。
+        PathBuf::from(rest.trim_start_matches('/'))
+    } else {
+        PathBuf::from(rest)
+    }
+}
+
+impl UpdateSource for DirSource {
+    fn source_id(&self) -> &str {
+        &self.id
+    }
+
+    fn fetch_manifest_documents(
+        &self,
+        channel: Channel,
+    ) -> Result, UpdateError> {
+        let path = self.manifest_path(channel);
+        let manifest = match fs::read_to_string(&path) {
+            Ok(text) => text,
+            Err(source) if source.kind() == std::io::ErrorKind::NotFound => return Ok(None),
+            Err(source) => return Err(UpdateError::io_at(&path, &source)),
+        };
+        // 签名文件缺失**不是**「没有清单」：清单在、签名不在 ⇒ 上层判 SignatureMissing 并拒装。
+        let signature_path = self.signature_path(channel);
+        let signatures = match fs::read_to_string(&signature_path) {
+            Ok(text) => Some(text),
+            Err(source) if source.kind() == std::io::ErrorKind::NotFound => None,
+            Err(source) => return Err(UpdateError::io_at(&signature_path, &source)),
+        };
+        Ok(Some(ManifestDocuments {
+            manifest,
+            signatures,
+        }))
+    }
+
+    fn fetch_artifact(&self, artifact: &Artifact, dest: &Path) -> Result {
+        let from = self.resolve(&artifact.url)?;
+        if let Some(parent) = dest.parent() {
+            if !parent.as_os_str().is_empty() {
+                fs::create_dir_all(parent).map_err(|error| UpdateError::io_at(parent, &error))?;
+            }
+        }
+        match fs::copy(&from, dest) {
+            Ok(bytes) => Ok(bytes),
+            Err(source) if source.kind() == std::io::ErrorKind::NotFound => Err(UpdateError::new(
+                UpdateErrorKind::SourceMissing,
+                format!("源里没有产物 `{}`", artifact.url),
+            )
+            .with_path(&from)),
+            Err(source) => Err(UpdateError::io_at(&from, &source)),
+        }
+    }
+}
diff --git a/crates/core/src/update/target.rs b/crates/core/src/update/target.rs
new file mode 100644
index 0000000..292d31e
--- /dev/null
+++ b/crates/core/src/update/target.rs
@@ -0,0 +1,196 @@
+//! 产物目标平台与包格式：清单里 `target` / `format` 两个字段的取值。
+//!
+//! 系统家族直接复用 [`OsFamily`]（`core::platform` 的口径），这里不另立一套
+//! Windows/macOS/Linux 枚举——否则同一件事会有两个真相源。
+//!
+//! `target` 的清单写法是 `系统-架构`，例如 `win-x64` / `mac-arm64` / `linux-arm64`。
+//! 解析容忍常见别名（`windows` / `macos` / `osx`、`x86_64` / `amd64`、`aarch64`），
+//! 因为清单是人（或 CI 脚本）拼出来的，别让 `win-amd64` 这种写法静默变成「没有可用产物」。
+
+use std::fmt;
+
+use crate::platform::os_info::OsFamily;
+
+/// 产物架构。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub enum Arch {
+    /// x86_64 / amd64。
+    X64,
+    /// aarch64 / arm64。
+    Arm64,
+    /// i686 / x86 32 位。
+    X86,
+    /// 编译目标认不出的架构（对照组永远匹配不上，于是走「本平台没有产物」那条路）。
+    Unknown,
+}
+
+impl Arch {
+    /// 清单写法。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::X64 => "x64",
+            Self::Arm64 => "arm64",
+            Self::X86 => "x86",
+            Self::Unknown => "unknown",
+        }
+    }
+
+    /// 当前编译目标的架构。
+    #[must_use]
+    pub const fn current() -> Self {
+        if cfg!(target_arch = "x86_64") {
+            Self::X64
+        } else if cfg!(target_arch = "aarch64") {
+            Self::Arm64
+        } else if cfg!(target_arch = "x86") {
+            Self::X86
+        } else {
+            Self::Unknown
+        }
+    }
+
+    /// 解析清单写法（容忍 `x86_64` / `amd64` / `aarch64` / `i686` 等别名）。
+    #[must_use]
+    pub fn parse(text: &str) -> Option {
+        match text.trim().to_ascii_lowercase().as_str() {
+            "x64" | "x86_64" | "x86-64" | "amd64" => Some(Self::X64),
+            "arm64" | "aarch64" | "arm64e" => Some(Self::Arm64),
+            "x86" | "i686" | "i386" | "x86_32" => Some(Self::X86),
+            _ => None,
+        }
+    }
+}
+
+/// 产物目标平台（系统 + 架构）。
+///
+/// 没派生 `Hash`/`Ord`：`OsFamily` 尚未派生这两个 trait（`core::platform` 不在本 mission
+/// 的改动范围内），需要当 Map 键时再回头补，别在这里另造一套系统枚举绕过去。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Target {
+    /// 系统家族。
+    pub os: OsFamily,
+    /// 架构。
+    pub arch: Arch,
+}
+
+impl Target {
+    /// 构造。
+    #[must_use]
+    pub const fn new(os: OsFamily, arch: Arch) -> Self {
+        Self { os, arch }
+    }
+
+    /// 当前编译目标。
+    #[must_use]
+    pub fn current() -> Self {
+        Self::new(OsFamily::current(), Arch::current())
+    }
+
+    /// 解析清单写法（`系统-架构`）。
+    #[must_use]
+    pub fn parse(text: &str) -> Option {
+        let (os, arch) = text.trim().split_once('-')?;
+        Some(Self::new(parse_os(os)?, Arch::parse(arch)?))
+    }
+
+    /// 清单写法。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match (self.os, self.arch) {
+            (OsFamily::Windows, Arch::X64) => "win-x64",
+            (OsFamily::Windows, Arch::Arm64) => "win-arm64",
+            (OsFamily::Windows, Arch::X86) => "win-x86",
+            (OsFamily::Windows, Arch::Unknown) => "win-unknown",
+            (OsFamily::MacOs, Arch::X64) => "mac-x64",
+            (OsFamily::MacOs, Arch::Arm64) => "mac-arm64",
+            (OsFamily::MacOs, Arch::X86) => "mac-x86",
+            (OsFamily::MacOs, Arch::Unknown) => "mac-unknown",
+            (OsFamily::Linux, Arch::X64) => "linux-x64",
+            (OsFamily::Linux, Arch::Arm64) => "linux-arm64",
+            (OsFamily::Linux, Arch::X86) => "linux-x86",
+            (OsFamily::Linux, Arch::Unknown) => "linux-unknown",
+        }
+    }
+}
+
+fn parse_os(text: &str) -> Option {
+    match text.trim().to_ascii_lowercase().as_str() {
+        "win" | "windows" => Some(OsFamily::Windows),
+        "mac" | "macos" | "osx" | "darwin" => Some(OsFamily::MacOs),
+        "linux" => Some(OsFamily::Linux),
+        _ => None,
+    }
+}
+
+impl fmt::Display for Target {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
+/// 安装包形态。
+///
+/// 只区分「安装器装出来的」与「解压即用的」两大类，具体怎么装由打包层决定：
+/// 安装器装的实例（msi/dmg/deb/rpm）本模块**不主张**原地覆盖（见 `install` 模块文档），
+/// 便携形态（portable-zip / appimage / portable-exe）才走自替换。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub enum PackageFormat {
+    /// Windows 安装器。
+    Msi,
+    /// macOS 磁盘映像。
+    Dmg,
+    /// Linux AppImage。
+    AppImage,
+    /// Debian 包。
+    Deb,
+    /// RPM 包。
+    Rpm,
+    /// 便携 zip（解压即用）。
+    PortableZip,
+    /// 便携单文件 exe。
+    PortableExe,
+}
+
+impl PackageFormat {
+    /// 清单写法。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Msi => "msi",
+            Self::Dmg => "dmg",
+            Self::AppImage => "appimage",
+            Self::Deb => "deb",
+            Self::Rpm => "rpm",
+            Self::PortableZip => "portable-zip",
+            Self::PortableExe => "portable-exe",
+        }
+    }
+
+    /// 解析清单写法。
+    #[must_use]
+    pub fn parse(text: &str) -> Option {
+        match text.trim().to_ascii_lowercase().as_str() {
+            "msi" => Some(Self::Msi),
+            "dmg" => Some(Self::Dmg),
+            "appimage" => Some(Self::AppImage),
+            "deb" => Some(Self::Deb),
+            "rpm" => Some(Self::Rpm),
+            "portable-zip" | "zip" => Some(Self::PortableZip),
+            "portable-exe" | "exe" => Some(Self::PortableExe),
+            _ => None,
+        }
+    }
+
+    /// 是否需要安装器代劳（这些形态不该被本模块原地覆盖）。
+    #[must_use]
+    pub const fn needs_installer(self) -> bool {
+        matches!(self, Self::Msi | Self::Dmg | Self::Deb | Self::Rpm)
+    }
+}
+
+impl fmt::Display for PackageFormat {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
diff --git a/crates/core/src/update/tests/channel_cases.rs b/crates/core/src/update/tests/channel_cases.rs
new file mode 100644
index 0000000..d4f7e02
--- /dev/null
+++ b/crates/core/src/update/tests/channel_cases.rs
@@ -0,0 +1,57 @@
+//! 渠道阶梯与准入：清单渠道比大小，预发布阶段按表收。
+
+use crate::update::{Channel, Stage};
+
+#[test]
+fn parses_names_loosely() {
+    assert_eq!(Channel::parse("stable").expect("stable"), Channel::Stable);
+    assert_eq!(Channel::parse(" STABLE ").expect("大写"), Channel::Stable);
+    assert_eq!(Channel::parse("Beta").expect("beta"), Channel::Beta);
+    assert_eq!(
+        Channel::parse("nightly").expect("nightly"),
+        Channel::Nightly
+    );
+    let error = Channel::parse("canary").expect_err("canary 不认");
+    assert!(error.to_string().contains("canary"));
+    assert_eq!(
+        Channel::ALL.map(Channel::as_str),
+        ["stable", "beta", "alpha", "nightly"]
+    );
+}
+
+#[test]
+fn ladder_admits_only_more_stable_releases() {
+    assert!(Channel::Stable.admits(Channel::Stable));
+    assert!(!Channel::Stable.admits(Channel::Beta));
+    assert!(Channel::Beta.admits(Channel::Stable));
+    assert!(Channel::Beta.admits(Channel::Beta));
+    assert!(!Channel::Beta.admits(Channel::Alpha));
+    assert!(!Channel::Alpha.admits(Channel::Nightly));
+    assert!(Channel::Alpha.admits(Channel::Beta));
+    assert!(Channel::Nightly.admits(Channel::Alpha));
+    assert!(Channel::Nightly.admits(Channel::Stable));
+}
+
+#[test]
+fn prerelease_stages_are_gated_by_channel() {
+    // 正式版对所有渠道都成立
+    for channel in Channel::ALL {
+        assert!(channel.admits_stage(Stage::Stable), "{channel}");
+    }
+    assert!(!Channel::Stable.admits_stage(Stage::ReleaseCandidate));
+    assert!(Channel::Beta.admits_stage(Stage::ReleaseCandidate));
+    assert!(!Channel::Beta.admits_stage(Stage::Beta));
+    assert!(Channel::Alpha.admits_stage(Stage::Beta));
+    assert!(!Channel::Alpha.admits_stage(Stage::Alpha));
+    assert!(!Channel::Alpha.admits_stage(Stage::Unknown));
+    assert!(Channel::Nightly.admits_stage(Stage::Alpha));
+    assert!(Channel::Nightly.admits_stage(Stage::Unknown));
+}
+
+#[test]
+fn display_and_from_str_agree() {
+    for channel in Channel::ALL {
+        assert_eq!(channel.as_str().parse::().expect("回读"), channel);
+        assert_eq!(channel.to_string(), channel.as_str());
+    }
+}
diff --git a/crates/core/src/update/tests/checker_cases.rs b/crates/core/src/update/tests/checker_cases.rs
new file mode 100644
index 0000000..a2e676e
--- /dev/null
+++ b/crates/core/src/update/tests/checker_cases.rs
@@ -0,0 +1,245 @@
+//! 检查更新：渠道准入、版本高低、目标平台漏发、强制更新。
+
+use crate::platform::os_info::OsFamily;
+use crate::update::{
+    Channel, CheckOutcome, DirSource, Target, UpdateChecker, UpdateErrorKind, UpdateSource,
+    Urgency, Version,
+};
+
+use super::support::{artifact, manifest, release, TempDir};
+
+const PAYLOAD: &[u8] = b"checker payload";
+
+fn target() -> Target {
+    Target::new(OsFamily::Windows, crate::update::Arch::X64)
+}
+
+/// 新建一个只放了这一份清单的本地源；返回的 `TempDir` 要活到用例结束。
+fn source_with(json: &str, channel: Channel) -> (TempDir, DirSource) {
+    let dir = TempDir::new("checker");
+    dir.write_signed(&format!("{}.json", channel.as_str()), json);
+    let source = DirSource::new(dir.path());
+    (dir, source)
+}
+
+fn check_outcome(json: &str, current: &str, channel: Channel) -> CheckOutcome {
+    let (_dir, source) = source_with(json, channel);
+    let version = Version::parse(current).expect("当前版本应可解析");
+    UpdateChecker::new(source, target())
+        .check(&version, channel)
+        .expect("检查不该失败")
+}
+
+fn stable_release(version: &str) -> String {
+    manifest(
+        "stable",
+        &[release(
+            version,
+            "",
+            &[artifact("win-x64", "portable-zip", "a.zip", PAYLOAD)],
+        )],
+    )
+}
+
+#[test]
+fn offers_the_numeric_newer_version() {
+    // 0.9 → 0.10 的字典序陷阱在 checker 这一层也要挡住
+    let outcome = check_outcome(&stable_release("0.10.0"), "0.9.0", Channel::Stable);
+    let candidate = outcome.candidate().expect("应有更新");
+    assert_eq!(candidate.release.version.to_string(), "0.10.0");
+    assert_eq!(
+        candidate.artifact.format,
+        crate::update::PackageFormat::PortableZip
+    );
+    assert_eq!(candidate.urgency, Urgency::Optional);
+}
+
+#[test]
+fn same_or_older_release_is_up_to_date() {
+    let outcome = check_outcome(&stable_release("0.2.1"), "0.2.1", Channel::Stable);
+    match outcome {
+        CheckOutcome::UpToDate { latest, .. } => {
+            assert_eq!(latest.map(|v| v.to_string()).as_deref(), Some("0.2.1"));
+        }
+        other => panic!("同等版本应已是最新，实际 {other:?}"),
+    }
+    let outcome = check_outcome(&stable_release("0.2.0"), "0.3.0", Channel::Stable);
+    assert!(!outcome.is_available(), "不该提示降级");
+}
+
+#[test]
+fn missing_manifest_means_up_to_date() {
+    let tmp = TempDir::new("checker-empty");
+    let source = DirSource::new(tmp.path());
+    let current = Version::parse("0.2.1").expect("版本");
+    let outcome = UpdateChecker::new(source, target())
+        .check(¤t, Channel::Stable)
+        .expect("没清单不是错误");
+    match outcome {
+        CheckOutcome::UpToDate { latest, .. } => assert_eq!(latest, None),
+        other => panic!("应为已是最新，实际 {other:?}"),
+    }
+}
+
+#[test]
+fn prerelease_is_gated_by_channel_stage() {
+    let json = manifest(
+        "beta",
+        &[release(
+            "1.0.0-rc.1",
+            "",
+            &[artifact("win-x64", "portable-zip", "a.zip", PAYLOAD)],
+        )],
+    );
+    // beta 渠道收 rc
+    let outcome = check_outcome(&json, "0.9.0", Channel::Beta);
+    assert_eq!(
+        outcome.candidate().map(|c| c.release.version.to_string()),
+        Some("1.0.0-rc.1".to_string())
+    );
+    // alpha 发布在 beta 渠道里不收（阶段阶梯）
+    let alpha_json = manifest(
+        "beta",
+        &[release(
+            "1.1.0-alpha.1",
+            "",
+            &[artifact("win-x64", "portable-zip", "a.zip", PAYLOAD)],
+        )],
+    );
+    let outcome = check_outcome(&alpha_json, "0.9.0", Channel::Beta);
+    assert!(!outcome.is_available(), "beta 渠道不该收 alpha 预发布");
+}
+
+#[test]
+fn stable_channel_never_takes_a_prerelease_even_if_the_manifest_claims_stable() {
+    let json = manifest(
+        "stable",
+        &[release(
+            "1.0.0-beta.2",
+            "",
+            &[artifact("win-x64", "portable-zip", "a.zip", PAYLOAD)],
+        )],
+    );
+    let outcome = check_outcome(&json, "0.9.0", Channel::Stable);
+    assert!(
+        !outcome.is_available(),
+        "清单可以写错，版本号不会：正式版渠道不许收预发布"
+    );
+}
+
+#[test]
+fn forced_update_comes_from_force_or_min_supported() {
+    let json = manifest(
+        "stable",
+        &[release(
+            "0.3.0",
+            r#","force":true"#,
+            &[artifact("win-x64", "portable-zip", "a.zip", PAYLOAD)],
+        )],
+    );
+    assert_eq!(
+        check_outcome(&json, "0.2.0", Channel::Stable)
+            .candidate()
+            .map(|candidate| candidate.urgency),
+        Some(Urgency::Forced)
+    );
+
+    let json = manifest(
+        "stable",
+        &[release(
+            "0.3.0",
+            r#","min_supported":"0.2.5""#,
+            &[artifact("win-x64", "portable-zip", "a.zip", PAYLOAD)],
+        )],
+    );
+    assert_eq!(
+        check_outcome(&json, "0.2.0", Channel::Stable)
+            .candidate()
+            .map(|candidate| candidate.urgency),
+        Some(Urgency::Forced),
+        "低于最低支持版本 = 强制"
+    );
+    assert_eq!(
+        check_outcome(&json, "0.2.5", Channel::Stable)
+            .candidate()
+            .map(|candidate| candidate.urgency),
+        Some(Urgency::Optional),
+        "刚好等于最低支持版本不算强制"
+    );
+}
+
+#[test]
+fn missing_target_artifact_is_reported_not_hidden() {
+    let json = manifest(
+        "stable",
+        &[release(
+            "0.3.0",
+            "",
+            &[artifact("linux-x64", "appimage", "a.AppImage", PAYLOAD)],
+        )],
+    );
+    let outcome = check_outcome(&json, "0.2.0", Channel::Stable);
+    match outcome {
+        CheckOutcome::MissingArtifact { release } => {
+            assert_eq!(release.version.to_string(), "0.3.0");
+        }
+        other => panic!("应为「有新版但没本平台产物」，实际 {other:?}"),
+    }
+}
+
+#[test]
+fn falls_back_to_the_newest_release_that_does_have_the_target() {
+    let json = manifest(
+        "stable",
+        &[
+            release(
+                "0.3.0",
+                "",
+                &[artifact("win-x64", "portable-zip", "a.zip", PAYLOAD)],
+            ),
+            release(
+                "0.4.0",
+                "",
+                &[artifact("linux-x64", "appimage", "b.AppImage", PAYLOAD)],
+            ),
+        ],
+    );
+    let outcome = check_outcome(&json, "0.2.0", Channel::Stable);
+    assert_eq!(
+        outcome.candidate().map(|c| c.release.version.to_string()),
+        Some("0.3.0".to_string()),
+        "0.4.0 没 win-x64 产物，应退回到 0.3.0"
+    );
+}
+
+#[test]
+fn channel_mismatch_in_the_source_is_an_error() {
+    let tmp = TempDir::new("checker-mismatch");
+    tmp.write_signed("stable.json", &manifest("beta", &[]));
+    let source = crate::update::DirSource::new(tmp.path());
+    let current = crate::update::Version::parse("0.2.1").expect("版本");
+    let error = UpdateChecker::new(source, target())
+        .check(¤t, Channel::Stable)
+        .expect_err("清单渠道不符应报错");
+    assert_eq!(error.kind, UpdateErrorKind::ChannelMismatch);
+}
+
+#[test]
+fn prepare_stages_the_selected_artifact() {
+    let tmp = TempDir::new("checker-prepare");
+    tmp.write("a.zip", PAYLOAD);
+    tmp.write_signed("stable.json", &stable_release("0.3.0"));
+    let source = crate::update::DirSource::new(tmp.path());
+    let checker = UpdateChecker::new(source, target());
+    let current = crate::update::Version::parse("0.2.0").expect("版本");
+    let outcome = checker
+        .check(¤t, Channel::Stable)
+        .expect("检查不该失败");
+    let candidate = outcome.candidate().expect("应有更新");
+    let staged = checker
+        .prepare(candidate, &tmp.join("staging"))
+        .expect("取包应成功");
+    assert_eq!(staged.size(), PAYLOAD.len() as u64);
+    assert_eq!(checker.target(), target());
+    assert!(checker.source().source_id().starts_with("file:"));
+}
diff --git a/crates/core/src/update/tests/ed25519_cases.rs b/crates/core/src/update/tests/ed25519_cases.rs
new file mode 100644
index 0000000..f76d956
--- /dev/null
+++ b/crates/core/src/update/tests/ed25519_cases.rs
@@ -0,0 +1,286 @@
+//! Ed25519 验签判据：**钉住 `ed25519-dalek::verify_strict` 的行为**（RFC 8032 §7.1 向量 + 六条拒绝类）。
+//!
+//! M190 r1 复审把自写曲线算术整体换成了官方实现（理由见 `crate::update::ed25519` 的模块文档）。
+//! 这批用例的定位因此从「测自己的实现」变成「**钉 dalek 的严格语义**」：
+//!
+//! | 用例 | 它挡住什么 | 把 `verify_strict` 换成 `verify` 后会怎样（r2 实测） |
+//! |---|---|---|
+//! | `small_order_public_key_is_rejected` | 小阶公钥下「自洽的伪造」（谁都能凑） | **红** —— 这是**唯一**承重的守卫 |
+//! | `small_order_r_is_rejected_only_by_strict` | 小阶 `R`（R = 单位元）的同一族伪造 | **红**（其余几条不会） |
+//! | `rfc8032_vectors_verify` | 实现换成任何一个错的版本（向量来自 RFC 附录） | 仍绿（`verify` 也验方程） |
+//! | `malleable_s_plus_l_is_rejected` | `S >= L` 的可锻变体 | **仍绿**：`verify` 自己就查 `S` 规范性，别把它当 strict 的守卫 |
+//! | `non_canonical_r_encoding_is_rejected` | 非规范编码的点（`y >= p` 的第二种写法） | 仍绿（dalek 靠自己的下游判据拒，见该用例注释） |
+//! | `empty_signature_is_rejected` / `message_bit_flip` / `signature_bit_flip` | 判据本身失效（恒真） | 仍绿 |
+//! | `signing_key_round_trips` | 测试夹具（dalek `SigningKey`）与验签侧同一套语义 | 仍绿 |
+//!
+//! 口径来源：M190 r2 复审在 `ed25519-dalek 2.2.0` 上逐条实测（并把先前的四处错误说法打回）。
+//! **结论**：strict 与**非** strict 在这批输入上唯一的分歧是**小阶点**——所以想确认「strict 还开着」，
+//! 看前两条；其余几条只在「判据被删成恒真」时才会红。
+
+use ed25519_dalek::{Signature, Verifier, VerifyingKey};
+
+use crate::update::ed25519::{verify, PUBLIC_KEY_LEN, SIGNATURE_LEN};
+
+use super::support_sign::{hex_of, public_key_hex, sign_bytes};
+
+/// 十六进制转字节（长度不对/字符非法当场 panic：这些向量是写死的常量）。
+fn unhex(text: &str) -> Vec {
+    let cleaned: String = text.chars().filter(|c| !c.is_whitespace()).collect();
+    assert!(
+        cleaned.len().is_multiple_of(2),
+        "十六进制串长度必须是偶数：{text}"
+    );
+    let bytes = cleaned.as_bytes();
+    let mut out = Vec::with_capacity(bytes.len() / 2);
+    let (pairs, _) = bytes.as_chunks::<2>();
+    for pair in pairs {
+        let hi = (pair[0] as char).to_digit(16).expect("十六进制字符");
+        let lo = (pair[1] as char).to_digit(16).expect("十六进制字符");
+        out.push(u8::try_from(hi * 16 + lo).expect("字节"));
+    }
+    out
+}
+
+fn array32(bytes: &[u8]) -> [u8; 32] {
+    let mut out = [0_u8; 32];
+    out.copy_from_slice(bytes);
+    out
+}
+
+fn array64(bytes: &[u8]) -> [u8; 64] {
+    let mut out = [0_u8; 64];
+    out.copy_from_slice(bytes);
+    out
+}
+
+/// L（群阶）的小端字节，用于构造「S + L」这种可锻变体。
+const L_BYTES: [u8; 32] = [
+    0xed, 0xd3, 0xf5, 0x5c, 0x1a, 0x63, 0x12, 0x58, 0xd6, 0x9c, 0xf7, 0xa2, 0xde, 0xf9, 0xde, 0x14,
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x10,
+];
+
+/// RFC 8032 §7.1 的四条向量：(public, message, signature)。
+fn rfc_vectors() -> Vec<(&'static str, &'static str, &'static str)> {
+    vec![
+        (
+            "d75a980182b10ab7d54bfed3c964073a0ee172f3daa62325af021a68f707511a",
+            "",
+            "e5564300c360ac729086e2cc806e828a84877f1eb8e5d974d873e065224901555fb8821590a33bacc61e39701cf9b46bd25bf5f0595bbe24655141438e7a100b",
+        ),
+        (
+            "3d4017c3e843895a92b70aa74d1b7ebc9c982ccf2ec4968cc0cd55f12af4660c",
+            "72",
+            "92a009a9f0d4cab8720e820b5f642540a2b27b5416503f8fb3762223ebdb69da085ac1e43e15996e458f3613d0f11d8c387b2eaeb4302aeeb00d291612bb0c00",
+        ),
+        (
+            "fc51cd8e6218a1a38da47ed00230f0580816ed13ba3303ac5deb911548908025",
+            "af82",
+            "6291d657deec24024827e69c3abe01a30ce548a284743a445e3680d7db5ac3ac18ff9b538d16f290ae67f760984dc6594a7c15e9716ed28dc027beceea1ec40a",
+        ),
+        (
+            "ec172b93ad5e563bf4932c70e1245034c35467ef2efd4d64ebf819683467e2bf",
+            "ddaf35a193617abacc417349ae20413112e6fa4e89a97ea20a9eeee64b55d39a2192992a274fc1a836ba3c23a3feebbd454d4423643ce80e2a9ac94fa54ca49f",
+            "dc2a4459e7369633a52b1bf277839a00201009a3efbf3ecb69bea2186c26b58909351fc9ac90b3ecfdfbc7c66431e0303dca179c138ac17ad9bef1177331a704",
+        ),
+    ]
+}
+
+#[test]
+fn rfc8032_vectors_verify() {
+    for (index, (public, message, signature)) in rfc_vectors().into_iter().enumerate() {
+        assert!(
+            verify(
+                &array32(&unhex(public)),
+                &unhex(message),
+                &array64(&unhex(signature))
+            ),
+            "RFC 8032 第 {} 条向量必须通过",
+            index + 1
+        );
+    }
+}
+
+#[test]
+fn message_bit_flip_is_rejected() {
+    let (public, message, signature) = rfc_vectors()[1];
+    let mut message = unhex(message);
+    message[0] ^= 0x01;
+    assert!(
+        !verify(
+            &array32(&unhex(public)),
+            &message,
+            &array64(&unhex(signature))
+        ),
+        "改一个消息字节必须被拒"
+    );
+}
+
+#[test]
+fn signature_bit_flip_is_rejected() {
+    let (public, message, signature) = rfc_vectors()[2];
+    let mut r_flipped = array64(&unhex(signature));
+    r_flipped[31] ^= 0x01;
+    assert!(
+        !verify(&array32(&unhex(public)), &unhex(message), &r_flipped),
+        "改 R 必须被拒"
+    );
+    let mut s_flipped = array64(&unhex(signature));
+    s_flipped[63] ^= 0x04;
+    assert!(
+        !verify(&array32(&unhex(public)), &unhex(message), &s_flipped),
+        "改 S 必须被拒"
+    );
+}
+
+#[test]
+fn malleable_s_plus_l_is_rejected() {
+    // 可锻性：把 S 换成 S + L，曲线方程照样成立（S 与 S+L 模 L 同余）。RFC 8032 的最低要求允许它。
+    // ⚠ 这条**不是** strict 的守卫：dalek 的非 strict `verify` 自己就检查 `S` 规范性，换掉 strict 它
+    // 仍绿（r2 实测）。它挡的是「判据被删成恒真」。strict 的守卫见 `small_order_*` 两条。
+    let (public, message, signature) = rfc_vectors()[0];
+    let mut signature = array64(&unhex(signature));
+    let mut carry = 0_u16;
+    for index in 0..32 {
+        let sum = u16::from(signature[32 + index]) + u16::from(L_BYTES[index]) + carry;
+        signature[32 + index] = (sum & 0xFF) as u8;
+        carry = sum >> 8;
+    }
+    assert_eq!(
+        carry, 0,
+        "S + L 不该溢出 256 位（否则这条用例本身没造出来）"
+    );
+    assert!(
+        !verify(&array32(&unhex(public)), &unhex(message), &signature),
+        "S >= L 必须被拒（可锻变体）"
+    );
+}
+
+#[test]
+fn small_order_public_key_is_rejected() {
+    // 阶为 1 的点（y = 1, x = 0）与零字节公钥：用它们做公钥，`verify`（非 strict）会接受一批伪造。
+    let message = b"manifest bytes";
+    let identity_key = {
+        let mut key = [0_u8; PUBLIC_KEY_LEN];
+        key[0] = 1;
+        key
+    };
+    let mut signature = [0_u8; SIGNATURE_LEN];
+    signature[0] = 1; // R = 单位元
+    assert!(
+        !verify(&identity_key, message, &signature),
+        "小阶公钥必须被拒"
+    );
+    assert!(
+        !verify(&[0_u8; PUBLIC_KEY_LEN], message, &signature),
+        "零公钥必须被拒"
+    );
+}
+
+#[test]
+fn non_canonical_r_encoding_is_rejected() {
+    // R = p（= 2^255-19）的字节：它与 y = 0 同值但编码不同（非规范）。
+    // dalek 的实际行为（r2 实测，与先前的说法不同）：
+    //   * `CompressedEdwardsY::decompress` **不**校验编码规范性 —— 这串字节解出来是**阶为 4**的点；
+    //   * 于是它被 `verify_strict` 的**小阶**判据拒，而不是被「编码非规范」拒；
+    //   * 公钥侧同理：`VerifyingKey::from_bytes` 对非规范编码返回 **Ok**（`is_weak() == true`），
+    //     所以要拒它只能靠下游判据 —— 下面把 dalek 的这个真实行为**断言下来**，将来 dalek 升级
+    //     改了口径会红（否则这条断言对任何实现都绿，等于没测）。
+    let (public, message, _) = rfc_vectors()[0];
+    let p_bytes: [u8; 32] = [
+        0xed, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
+        0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
+        0xff, 0x7f,
+    ];
+    let mut signature = [0_u8; SIGNATURE_LEN];
+    signature[..32].copy_from_slice(&p_bytes);
+    assert!(
+        !verify(&array32(&unhex(public)), &unhex(message), &signature),
+        "非规范 R 编码必须被拒（dalek 的理由是小阶点）"
+    );
+
+    // dalek 的真实行为：非规范编码的公钥**能**通过 `from_bytes`，并被标成 weak。
+    let weak = VerifyingKey::from_bytes(&p_bytes).expect("dalek 2.2 不校验编码规范性，应返回 Ok");
+    assert!(
+        weak.is_weak(),
+        "这个非规范编码解出的是小阶点，dalek 应标记 is_weak"
+    );
+    // 我们的 `verify` 对同一串公钥仍然拒（下游方程/小阶判据兜住）。
+    assert!(
+        !verify(
+            &p_bytes,
+            &unhex(message),
+            &array64(&unhex(rfc_vectors()[0].2))
+        ),
+        "非规范/小阶公钥不得验过"
+    );
+}
+
+#[test]
+fn small_order_r_is_rejected_only_by_strict() {
+    // **第二条只由 strict 承重的判据**（r2 复审建议补的）：小阶 `R`。
+    // 构造：R = 单位元（阶 1），S = k·a mod L，其中 k = SHA-512(R‖A‖M) mod L、a 是测试钥的标量。
+    // 这样方程 `[S]B = R + [k]A` 自洽 ⇒ **非 strict 的 `verify` 会通过**；`verify_strict` 因
+    // 「R 是小阶点」拒。下面两边都断言，所以将来谁把 strict 换成非 strict，这条会红。
+    let public = array32(&unhex(
+        "f3ea49a34ebda73d6500c9416f425e0358baf094b957baf3ea7daa6df63e876b",
+    ));
+    let message = b"manifest bytes";
+    let forged = array64(&unhex(concat!(
+        "0100000000000000000000000000000000000000000000000000000000000000",
+        "698a94a4c82aa13c1a4da6248799849f2254ef333b5f5d69dcbd71b6320e5e0e"
+    )));
+
+    // 非 strict 侧：dalek 的 `verify` 会接受这条伪造（这就是 strict 存在的理由）。
+    let key = VerifyingKey::from_bytes(&public).expect("合法公钥");
+    assert!(
+        key.verify(message, &Signature::from_bytes(&forged)).is_ok(),
+        "非 strict 的 verify 应当接受这条伪造（构造前提；若 dalek 改了行为，这条先红）"
+    );
+    // strict 侧：我们导出的 `verify` 必须拒。
+    assert!(
+        !verify(&public, message, &forged),
+        "小阶 R 的伪造必须被 verify_strict 拒"
+    );
+}
+
+#[test]
+fn empty_signature_is_rejected() {
+    let (public, message, _) = rfc_vectors()[0];
+    assert!(!verify(
+        &array32(&unhex(public)),
+        &unhex(message),
+        &[0_u8; 64]
+    ));
+}
+
+#[test]
+fn signing_key_round_trips() {
+    // 测试夹具（dalek `SigningKey`）与验签侧同一套语义：RFC 的 secret 反推出的公钥要对得上，
+    // 签出来的能验过，改一个字节就验不过。
+    let seed = array32(&unhex(
+        "9d61b19deffd5a60ba844af492ec2cc44449c5697b326919703bac031cae7f60",
+    ));
+    assert_eq!(
+        public_key_hex(&seed),
+        rfc_vectors()[0].0,
+        "种子展开必须与 RFC 一致"
+    );
+    assert_eq!(
+        hex_of(&sign_bytes(&seed, b"")),
+        rfc_vectors()[0].2,
+        "空消息的签名必须逐字节等于 RFC 向量（测试夹具与向量同一套语义）"
+    );
+    let signature = sign_bytes(&seed, b"unlucky");
+    assert!(verify(
+        &array32(&unhex(rfc_vectors()[0].0)),
+        b"unlucky",
+        &signature
+    ));
+    let mut tampered = signature;
+    tampered[0] ^= 0x80;
+    assert!(!verify(
+        &array32(&unhex(rfc_vectors()[0].0)),
+        b"unlucky",
+        &tampered
+    ));
+}
diff --git a/crates/core/src/update/tests/github_cases.rs b/crates/core/src/update/tests/github_cases.rs
new file mode 100644
index 0000000..97ba278
--- /dev/null
+++ b/crates/core/src/update/tests/github_cases.rs
@@ -0,0 +1,382 @@
+//! GitHub Releases 源：固定清单地址、产物 URL 解析、渠道只有 stable、与 `DirSource` 对拍。
+//!
+//! 全程离线：假 HTTP 服务起在 `127.0.0.1` 上，`base` 指向它——没有一个用例访问 github.com
+//! 或 gh-proxy（那部分只能真联网验收，见 mission 报告的「没验的部分」）。
+
+use std::fs;
+use std::sync::Arc;
+
+use crate::download::mirrors::SOURCE_GH_PROXY;
+use crate::download::{DownloadEngine, RegionProfile, SOURCE_OFFICIAL};
+use crate::update::github::{DEFAULT_BASE, DEFAULT_OWNER, DEFAULT_REPO, MANIFEST_ASSET};
+use crate::update::{
+    verified_manifest, Channel, DirSource, GitHubReleaseSource, ReleaseManifest, Target,
+    UpdateChecker, UpdateError, UpdateErrorKind, UpdateSource, Version,
+};
+
+use super::support::{artifact, engine_for, manifest, release, FakeHttp, FakeResponse, TempDir};
+use super::support_sign::signature_envelope;
+
+const PAYLOAD: &[u8] = b"github release payload";
+
+/// 假服务上清单所在路径（与本源拼出来的地址逐字符对齐）。
+fn manifest_path() -> String {
+    format!("/{DEFAULT_OWNER}/{DEFAULT_REPO}/releases/latest/download/{MANIFEST_ASSET}")
+}
+
+/// 假服务上签名所在路径（M190：与清单并列）。
+fn signature_path() -> String {
+    format!("{}.sig", manifest_path())
+}
+
+/// 「清单 + 签名」两条路由：签名用测试钥现签，与 `DirSource` 夹具同一把钥。
+fn signed_routes(manifest_json: &str) -> Vec<(String, FakeResponse)> {
+    vec![
+        (manifest_path(), FakeResponse::json(manifest_json)),
+        (
+            signature_path(),
+            FakeResponse::json(&signature_envelope(manifest_json)),
+        ),
+    ]
+}
+
+/// 按 D49 命名规则的产物文件名。
+fn asset_name() -> &'static str {
+    "unlucky-launcher_0.6.0_windows_x64.exe"
+}
+
+/// 假服务上产物所在路径。
+fn asset_path() -> String {
+    format!(
+        "/{DEFAULT_OWNER}/{DEFAULT_REPO}/releases/latest/download/{}",
+        asset_name()
+    )
+}
+
+/// 一份可用的 stable 清单（产物 url 就是 D49 文件名）。
+fn stable_manifest_json() -> String {
+    manifest(
+        "stable",
+        &[release(
+            "0.6.0",
+            r#","notes":"修掉启动崩溃""#,
+            &[artifact("win-x64", "portable-exe", asset_name(), PAYLOAD)],
+        )],
+    )
+}
+
+/// 解析上面那份清单（多数字段级断言都用它）。
+fn parsed_stable() -> ReleaseManifest {
+    ReleaseManifest::from_json(&stable_manifest_json()).expect("清单应可解析")
+}
+
+fn target() -> Target {
+    Target::parse("win-x64").expect("目标平台写法合法")
+}
+
+fn source_with(engine: Arc, base: &str) -> GitHubReleaseSource {
+    GitHubReleaseSource::new(engine).with_base(base)
+}
+
+/// 本地假服务 + 指向它的源（直连模式：不套 gh-proxy，请求落在 127.0.0.1 上）。
+fn local_source(tmp: &TempDir, server: &FakeHttp) -> GitHubReleaseSource {
+    source_with(engine_for(tmp, RegionProfile::direct(0)), &server.base())
+}
+
+#[test]
+fn manifest_url_is_the_fixed_latest_download_path() {
+    let tmp = TempDir::new("gh-url");
+    let source = GitHubReleaseSource::new(engine_for(&tmp, RegionProfile::direct(0)));
+    assert_eq!(source.owner(), DEFAULT_OWNER);
+    assert_eq!(source.repo(), DEFAULT_REPO);
+    assert_eq!(source.base(), DEFAULT_BASE);
+    let expected = format!(
+        "{DEFAULT_BASE}/{DEFAULT_OWNER}/{DEFAULT_REPO}/releases/latest/download/{MANIFEST_ASSET}"
+    );
+    assert_eq!(
+        source.manifest_url(Channel::Stable).as_deref(),
+        Some(expected.as_str()),
+        "D50 定死的固定地址，一个字符都不许飘"
+    );
+    assert_eq!(
+        source.source_id(),
+        format!("github:{DEFAULT_OWNER}/{DEFAULT_REPO}")
+    );
+
+    // fork / 自建镜像仓：owner/repo 可换，路径形状不变。
+    let fork = GitHubReleaseSource::with_repo(
+        engine_for(&tmp, RegionProfile::direct(0)),
+        "someone",
+        "ull-fork",
+    )
+    .with_base("http://127.0.0.1:1/");
+    assert_eq!(
+        fork.manifest_url(Channel::Stable).as_deref(),
+        Some("http://127.0.0.1:1/someone/ull-fork/releases/latest/download/manifest.json"),
+        "base 末尾斜杠要去掉，别拼出双斜杠"
+    );
+    assert_eq!(fork.source_id(), "github:someone/ull-fork");
+}
+
+#[test]
+fn channels_other_than_stable_publish_nothing() {
+    let tmp = TempDir::new("gh-channels");
+    let server = FakeHttp::start(signed_routes(&stable_manifest_json()));
+    let source = local_source(&tmp, &server);
+
+    for channel in [Channel::Beta, Channel::Alpha, Channel::Nightly] {
+        assert!(
+            source.manifest_url(channel).is_none(),
+            "{channel} 不该有清单地址"
+        );
+        let manifest = verified_manifest(&source, channel).expect("没开通道不是错误");
+        assert!(
+            manifest.is_none(),
+            "{channel} 应返回 Ok(None)（不发布即无更新）"
+        );
+    }
+    assert!(
+        server.hits().is_empty(),
+        "非 stable 渠道一次请求都不该发（实际：{:?}）",
+        server.hits()
+    );
+}
+
+#[test]
+fn artifact_url_appends_the_release_download_path() {
+    let tmp = TempDir::new("gh-artifact-url");
+    let source = GitHubReleaseSource::new(engine_for(&tmp, RegionProfile::direct(0)));
+    let artifact = &parsed_stable().releases[0].artifacts[0];
+
+    let url = source.artifact_url(artifact).expect("应能拼出地址");
+    assert_eq!(
+        url,
+        format!(
+            "{DEFAULT_BASE}/{DEFAULT_OWNER}/{DEFAULT_REPO}/releases/latest/download/{}",
+            asset_name()
+        )
+    );
+
+    // `./name` / `/name` 与裸文件名等价（清单是人手写的）。
+    for written in [format!("./{}", asset_name()), format!("/{}", asset_name())] {
+        let mut tweaked = artifact.clone();
+        tweaked.url = written;
+        assert_eq!(source.artifact_url(&tweaked).expect("应可解析"), url);
+    }
+
+    // 已经写了完整地址 → 原样使用（清单可以临时指向别处）。
+    let mut absolute = artifact.clone();
+    absolute.url = "https://example.invalid/dist/ull.exe".to_string();
+    assert_eq!(
+        source.artifact_url(&absolute).expect("绝对地址原样"),
+        "https://example.invalid/dist/ull.exe"
+    );
+
+    // 其它协议不认（那是别的源的活）。
+    let mut unsupported = artifact.clone();
+    unsupported.url = "ftp://example.invalid/ull.exe".to_string();
+    assert_eq!(
+        source
+            .artifact_url(&unsupported)
+            .expect_err("ftp 不是本源能取的")
+            .kind,
+        UpdateErrorKind::UnsupportedSource
+    );
+}
+
+#[test]
+fn fetches_and_parses_the_manifest_from_the_base() {
+    let tmp = TempDir::new("gh-manifest-ok");
+    let server = FakeHttp::start(signed_routes(&stable_manifest_json()));
+    let source = local_source(&tmp, &server);
+
+    let manifest = verified_manifest(&source, Channel::Stable)
+        .expect("应取到清单")
+        .expect("清单存在");
+    assert_eq!(manifest.channel, Channel::Stable);
+    assert_eq!(manifest.releases.len(), 1);
+    assert_eq!(manifest.releases[0].version.to_string(), "0.6.0");
+    assert_eq!(
+        server.hits(),
+        vec![manifest_path(), signature_path()],
+        "先取清单、再取它旁边的签名，两个请求都发过"
+    );
+}
+
+#[test]
+fn missing_manifest_in_the_release_is_not_an_error() {
+    // 最新 release 没挂 manifest.json → 404 → 当成「还没发布」，不是红字。
+    let tmp = TempDir::new("gh-manifest-404");
+    let server = FakeHttp::start(Vec::new());
+    let source = local_source(&tmp, &server);
+
+    let outcome = verified_manifest(&source, Channel::Stable).expect("404 不是错误");
+    assert!(outcome.is_none(), "取不到清单 = 还没发过版");
+    assert_eq!(
+        server.hits(),
+        vec![manifest_path()],
+        "确实问过一次，不是压根没发请求"
+    );
+}
+
+#[test]
+fn broken_json_is_reported_as_invalid_manifest() {
+    let tmp = TempDir::new("gh-manifest-broken");
+    // 签名是对的（签的就是这串坏字节）——只有「签名对、内容坏」才走得到解析这一步。
+    let server = FakeHttp::start(signed_routes("{ not json"));
+    let source = local_source(&tmp, &server);
+
+    let error = verified_manifest(&source, Channel::Stable).expect_err("坏 JSON 必须报错");
+    assert_eq!(error.kind, UpdateErrorKind::InvalidManifest);
+    assert!(
+        error.message.contains("github:"),
+        "错误里要带出来源标识，日志才定位得到（实际：{}）",
+        error.message
+    );
+    assert!(!error.is_retryable(), "清单坏重试多少次都一样");
+}
+
+#[test]
+fn illegal_manifest_fields_are_reported() {
+    let tmp = TempDir::new("gh-manifest-illegal");
+    // size 为 0（发布脚本写漏）——字段层面的非法，走同一条 InvalidManifest 分类。
+    let json = r#"{"channel":"stable","releases":[{"version":"0.6.0","artifacts":[{"target":"win-x64","format":"portable-exe","url":"ull.exe","size":0,"sha256":"0000000000000000000000000000000000000000000000000000000000000000"}]}]}"#;
+    let server = FakeHttp::start(signed_routes(json));
+    let source = local_source(&tmp, &server);
+
+    let error = verified_manifest(&source, Channel::Stable).expect_err("size 为 0 必须报错");
+    assert_eq!(error.kind, UpdateErrorKind::InvalidManifest);
+}
+
+#[test]
+fn manifest_self_reporting_another_channel_is_a_mismatch() {
+    let tmp = TempDir::new("gh-manifest-mismatch");
+    let server = FakeHttp::start(signed_routes(&manifest("beta", &[])));
+    let source = local_source(&tmp, &server);
+
+    let error = verified_manifest(&source, Channel::Stable).expect_err("渠道不符必须报错");
+    assert_eq!(error.kind, UpdateErrorKind::ChannelMismatch);
+}
+
+#[test]
+fn server_errors_are_network_errors() {
+    let tmp = TempDir::new("gh-manifest-500");
+    let server = FakeHttp::start(vec![(manifest_path(), FakeResponse::status(500))]);
+    let source = local_source(&tmp, &server);
+
+    let error = verified_manifest(&source, Channel::Stable).expect_err("5xx 必须报错");
+    assert_eq!(error.kind, UpdateErrorKind::Network);
+    assert!(error.is_retryable(), "网络抖动值得隔一会儿再试");
+}
+
+#[test]
+fn downloads_the_artifact_through_the_engine() {
+    let tmp = TempDir::new("gh-artifact-download");
+    let server = FakeHttp::start(vec![(asset_path(), FakeResponse::bin(PAYLOAD))]);
+    let source = local_source(&tmp, &server);
+    let dest = tmp.join("staging/package.exe");
+
+    let written = source
+        .fetch_artifact(&parsed_stable().releases[0].artifacts[0], &dest)
+        .expect("应下载成功");
+    assert_eq!(written, PAYLOAD.len() as u64);
+    assert_eq!(fs::read(&dest).expect("目标文件应存在"), PAYLOAD);
+    assert_eq!(
+        server.hits(),
+        vec![asset_path()],
+        "包体走引擎，请求地址就是解析出来的那条"
+    );
+}
+
+#[test]
+fn missing_artifact_is_reported_as_source_missing() {
+    let tmp = TempDir::new("gh-artifact-404");
+    let server = FakeHttp::start(Vec::new());
+    let source = local_source(&tmp, &server);
+
+    let error: UpdateError = source
+        .fetch_artifact(
+            &parsed_stable().releases[0].artifacts[0],
+            &tmp.join("staging/package.exe"),
+        )
+        .expect_err("产物不存在必须报错");
+    assert_eq!(error.kind, UpdateErrorKind::SourceMissing);
+    assert!(!error.is_retryable(), "产物没上传，重试多少次都一样");
+}
+
+#[test]
+fn mirror_first_region_puts_the_gh_proxy_in_front() {
+    // 镜像策略不新造：国内（镜像优先）环境下 gh-proxy 前缀由引擎的镜像表 + 地区档案决定。
+    let tmp = TempDir::new("gh-mirror");
+    let source = GitHubReleaseSource::new(engine_for(&tmp, RegionProfile::mirror_first(0)));
+    let artifact_url = source
+        .artifact_url(&parsed_stable().releases[0].artifacts[0])
+        .expect("应能拼出地址");
+
+    let planned = source.candidates(&artifact_url);
+    assert!(
+        planned.len() >= 2,
+        "镜像优先至少要有镜像与官方两条候选（实际 {planned:?}）"
+    );
+    assert_eq!(planned[0].source, SOURCE_GH_PROXY);
+    assert_eq!(
+        planned[0].url,
+        format!("https://gh-proxy.com/{artifact_url}")
+    );
+    assert!(
+        planned
+            .iter()
+            .any(|candidate| candidate.source == SOURCE_OFFICIAL && candidate.url == artifact_url),
+        "官方地址仍要留作兜底（实际 {planned:?}）"
+    );
+
+    // 直连模式不套前缀：只剩官方一条。
+    let direct = GitHubReleaseSource::new(engine_for(&tmp, RegionProfile::direct(0)));
+    let planned_direct = direct.candidates(&artifact_url);
+    assert_eq!(planned_direct.len(), 1);
+    assert_eq!(planned_direct[0].source, SOURCE_OFFICIAL);
+
+    // 清单地址同样吃到 gh-proxy（国内拿不到 releases/latest/download 的正是清单这一刻）。
+    let manifest_url = source.manifest_url(Channel::Stable).expect("stable 有清单");
+    let planned_manifest = source.candidates(&manifest_url);
+    assert_eq!(planned_manifest[0].source, SOURCE_GH_PROXY);
+    assert_eq!(
+        planned_manifest[0].url,
+        format!("https://gh-proxy.com/{manifest_url}")
+    );
+}
+
+#[test]
+fn agrees_with_dir_source_on_the_same_manifest() {
+    // 对拍：同一份清单、同一个当前版本、同一个目标平台，两个源的判定必须一模一样。
+    let tmp = TempDir::new("gh-dir-parity");
+    let json = stable_manifest_json();
+
+    // 本地目录源：清单与产物都在临时目录里（产物 url 是相对文件名）。
+    tmp.write_signed(&format!("{}.json", Channel::Stable.as_str()), &json);
+    tmp.write(asset_name(), PAYLOAD);
+    let dir = DirSource::new(tmp.path());
+
+    // GitHub 源：同一份 JSON 由假服务提供，产物 url 解析成 release 产物地址。
+    let mut routes = signed_routes(&json);
+    routes.push((asset_path(), FakeResponse::bin(PAYLOAD)));
+    let server = FakeHttp::start(routes);
+    let github = local_source(&tmp, &server);
+
+    let current = Version::parse("0.5.0").expect("版本号合法");
+    let from_dir = UpdateChecker::new(dir, target())
+        .check(¤t, Channel::Stable)
+        .expect("本地源应能判定");
+    let from_github = UpdateChecker::new(github, target())
+        .check(¤t, Channel::Stable)
+        .expect("GitHub 源应能判定");
+
+    assert!(
+        from_dir.is_available(),
+        "基准用例应当有可用更新（实际 {from_dir:?}）"
+    );
+    assert_eq!(
+        from_github, from_dir,
+        "同一份清单，两个源选出的版本/产物/紧急度必须一致"
+    );
+}
diff --git a/crates/core/src/update/tests/install_cases.rs b/crates/core/src/update/tests/install_cases.rs
new file mode 100644
index 0000000..7094028
--- /dev/null
+++ b/crates/core/src/update/tests/install_cases.rs
@@ -0,0 +1,259 @@
+//! 替换与回滚：成功后备份还在、失败后旧版本仍在原位、目标目录写不进去要报错。
+//!
+//! Windows 的「文件被占用」用例是**真造出来**的：用 `share_mode(FILE_SHARE_READ)` 打开目标
+//! 文件（不带 `FILE_SHARE_DELETE`，与 Windows 加载器打开运行中映像的口径一致），让 `rename`
+//! 撞共享冲突。它不是「运行中的 exe」（那需要真跑一个子进程，属真机验收），这一点在报告里写明。
+
+use std::fs;
+use std::path::PathBuf;
+
+use crate::update::manifest::ReleaseManifest;
+use crate::update::{
+    install_staged, stage, DirSource, InstallFailure, ReplacePolicy, StagedPackage,
+};
+
+use super::support::{artifact, manifest, names_in, release, TempDir};
+
+const UPDATE: &[u8] = b"new build bytes";
+const OLD: &[u8] = b"old build bytes";
+
+fn policy() -> ReplacePolicy {
+    ReplacePolicy::new(2, std::time::Duration::from_millis(1))
+}
+
+/// 发布一个包体、跑完取包+校验，拿到可直接安装的 `StagedPackage`。
+fn staged(tmp: &TempDir) -> StagedPackage {
+    tmp.write("ull-test.zip", UPDATE);
+    let json = manifest(
+        "stable",
+        &[release(
+            "0.3.0",
+            "",
+            &[artifact("win-x64", "portable-zip", "ull-test.zip", UPDATE)],
+        )],
+    );
+    let parsed = ReleaseManifest::from_json(&json).expect("清单应可解析");
+    stage(
+        &DirSource::new(tmp.path()),
+        &parsed.releases[0].artifacts[0],
+        &tmp.join("staging"),
+    )
+    .expect("取包与校验应通过")
+}
+
+#[test]
+fn installs_over_an_existing_file_and_keeps_the_backup() {
+    let tmp = TempDir::new("install-ok");
+    let dest = tmp.write("app/ull.exe", OLD);
+    let staged = staged(&tmp);
+    let receipt = install_staged(&staged, &dest, policy()).expect("替换应成功");
+
+    assert_eq!(fs::read(&dest).expect("目标应存在"), UPDATE);
+    assert_eq!(receipt.bytes, UPDATE.len() as u64);
+    assert_eq!(receipt.dest, dest);
+    let backup = receipt.backup.clone().expect("旧版本应被留在备份路径");
+    assert_eq!(fs::read(&backup).expect("备份应存在"), OLD);
+    assert_eq!(
+        backup.parent(),
+        dest.parent(),
+        "备份必须与目标同目录，跨卷 rename 会失去原子性"
+    );
+
+    receipt.remove_backup().expect("删备份");
+    assert!(!backup.exists(), "备份应被删掉");
+    assert_eq!(names_in(dest.parent().expect("父目录")), ["ull.exe"]);
+}
+
+#[test]
+fn installing_into_a_fresh_path_has_no_backup() {
+    let tmp = TempDir::new("install-fresh");
+    let staged = staged(&tmp);
+    let dest = tmp.join("dist/ull.exe");
+    let receipt = install_staged(&staged, &dest, policy()).expect("新装应成功");
+    assert_eq!(receipt.backup, None);
+    assert_eq!(fs::read(&dest).expect("目标应存在"), UPDATE);
+}
+
+#[test]
+fn failed_move_rolls_the_old_version_back() {
+    let tmp = TempDir::new("install-rollback");
+    let dest = tmp.write("app/ull.exe", OLD);
+    let staged = staged(&tmp);
+    // 让第二步（暂存包 → 目标）注定失败：把暂存文件删掉，等价于"搬到一半源没了"。
+    fs::remove_file(staged.path()).expect("删掉暂存文件");
+
+    let failure: InstallFailure =
+        install_staged(&staged, &dest, policy()).expect_err("搬不进去必须失败");
+    assert!(failure.rolled_back, "旧版本应回到原位：{failure}");
+    assert!(!failure.needs_manual_repair());
+    assert_eq!(failure.backup_left, None);
+    assert_eq!(fs::read(&dest).expect("旧版本应仍在"), OLD);
+    assert_eq!(
+        names_in(dest.parent().expect("父目录")),
+        ["ull.exe"],
+        "回滚后不该留下备份文件"
+    );
+}
+
+#[test]
+fn manual_rollback_restores_the_previous_build() {
+    let tmp = TempDir::new("install-manual-rollback");
+    let dest = tmp.write("app/ull.exe", OLD);
+    let staged = staged(&tmp);
+    let mut receipt = install_staged(&staged, &dest, policy()).expect("替换应成功");
+    assert_eq!(fs::read(&dest).expect("新版本"), UPDATE);
+    let backup = receipt.backup.clone().expect("旧版本备份");
+
+    receipt.rollback(policy()).expect("回滚应成功");
+    assert_eq!(fs::read(&dest).expect("旧版本应回来"), OLD);
+    assert!(!backup.exists(), "回滚会把备份搬回去，不留副本");
+    assert_eq!(receipt.backup, None, "回滚成功后不该再指着不存在的备份");
+    assert!(receipt.remove_backup().is_ok(), "没有备份时删备份是空操作");
+}
+
+#[test]
+fn unwritable_target_directory_fails_without_touching_anything() {
+    let tmp = TempDir::new("install-unwritable");
+    let staged = staged(&tmp);
+    // 父路径是个普通文件：建目录必然失败，等价于"目标目录不可写"
+    // （比 chmod 555 更可移植：CI 里常以 root 跑，chmod 对 root 无效）。
+    let blocked = tmp.write("blocked", b"not a directory");
+    let dest = blocked.join("app/ull.exe");
+
+    let failure = install_staged(&staged, &dest, policy()).expect_err("写不进目标目录必须失败");
+    assert!(failure.rolled_back, "没写任何东西，旧状态未变：{failure}");
+    assert_eq!(
+        fs::read(&blocked).expect("占位文件应原样"),
+        b"not a directory"
+    );
+    assert!(!dest.exists());
+}
+
+#[cfg(windows)]
+#[test]
+fn windows_locked_target_fails_and_leaves_the_old_file_intact() {
+    use std::fs::OpenOptions;
+    use std::os::windows::fs::OpenOptionsExt;
+
+    /// `FILE_SHARE_READ`：只允许别人读，不允许改名/删除。
+    const FILE_SHARE_READ: u32 = 0x1;
+
+    let tmp = TempDir::new("install-locked");
+    let dest = tmp.write("app/ull.exe", OLD);
+    let staged = staged(&tmp);
+    // 刻意**不**共享删除：`std::fs::File::open` 默认带 FILE_SHARE_DELETE（改名会被放行），
+    // 而 Windows 加载器打开正在运行的映像时不带它——这才是我们要复现的占用形态。
+    let held = OpenOptions::new()
+        .read(true)
+        .share_mode(FILE_SHARE_READ)
+        .open(&dest)
+        .expect("打开目标文件");
+    let failure = install_staged(&staged, &dest, policy()).expect_err("占用中的文件改不了名");
+    assert!(failure.rolled_back, "旧版本必须完好：{failure}");
+    assert_eq!(fs::read(&dest).expect("旧版本应仍在"), OLD);
+    drop(held);
+    assert_eq!(
+        names_in(dest.parent().expect("父目录")),
+        ["ull.exe"],
+        "失败的尝试不该留下备份或暂存垃圾"
+    );
+}
+
+#[test]
+fn backup_path_stays_in_the_same_directory() {
+    let dest = PathBuf::from("some/dir/ull.exe");
+    let backup = crate::update::backup_path(&dest);
+    assert_eq!(backup.parent(), dest.parent());
+    let name = backup
+        .file_name()
+        .expect("备份名")
+        .to_string_lossy()
+        .into_owned();
+    assert!(name.starts_with(".ull.exe.ullold-"), "实际：{name}");
+    assert_ne!(
+        backup,
+        crate::update::backup_path(&dest),
+        "同一进程两次调用不能撞名"
+    );
+}
+
+/// 备份只留最近一份：连装两次不会在安装目录里堆两个几十 MB 的旧 exe。
+///
+/// 旧行为是「每次 apply 留一个、永不删」（全仓没有任何调用方调 `remove_backup`），这条用例把
+/// 上界钉在「一次安装一份」上。它抓得住「prune 被删掉/被改坏」；抓不住**并发**：两个进程同时
+/// 替换同一路径本来就不成立（后者的回滚会把前者的新版本换回旧字节），这一点写在 `install` 的
+/// 文档里，不是这里能验的。
+#[test]
+fn only_the_latest_backup_is_kept() {
+    let tmp = TempDir::new("install-retention");
+    let dest = tmp.write("app/ull.exe", OLD);
+    // 上一次也没人删的备份（名字形态与 `backup_path` 一致，只是 pid/seq 不同）。
+    tmp.write("app/.ull.exe.ullold-1-1", b"older old bytes");
+    tmp.write("app/.ull.exe.ullold-1-2", b"even older bytes");
+    // 别的程序的备份：不是我们的名字，一个都不许动。
+    tmp.write("app/.other.exe.ullold-1-1", b"someone else's backup");
+    // 上一次失败遗留的中转文件：垃圾，要在这次成功之后清掉。
+    tmp.write(
+        "app/.ull.exe.ullnew-1-1",
+        b"half a build from a dead attempt",
+    );
+
+    let staged = staged(&tmp);
+    let receipt = install_staged(&staged, &dest, policy()).expect("替换应成功");
+    let backup = receipt.backup.clone().expect("本次备份");
+
+    assert_eq!(fs::read(&backup).expect("本次备份"), OLD);
+    assert_eq!(
+        names_in(dest.parent().expect("父目录")),
+        [
+            ".other.exe.ullold-1-1".to_owned(),
+            backup
+                .file_name()
+                .expect("备份名")
+                .to_string_lossy()
+                .into_owned(),
+            "ull.exe".to_owned(),
+        ],
+        "只该留本次备份，且不许碰别的程序的备份"
+    );
+}
+
+/// 崩溃现场：上一次装到「dest → 备份」之后被杀，`dest` 空着、旧字节只剩备份那一份。
+///
+/// 这种情况下本次安装的 `keep = None`（dest 原本不存在 ⇒ 不建新备份），清理**必须放过**
+/// `.ullold-*`——它是用户旧版本唯一幸存的副本，删了就没法手工恢复了。`.ullnew-*` 仍是垃圾，
+/// 该清。变异实测：把 `prune_stale_artifacts` 里 `keep.is_some() &&` 这一半去掉 ⇒ 本条红。
+#[test]
+fn a_crashed_install_keeps_the_only_surviving_old_copy() {
+    let tmp = TempDir::new("install-crash-scene");
+    let app = tmp.join("app");
+    fs::create_dir_all(&app).expect("建安装目录");
+    // 崩现场：没有 ulls.exe，旧字节只在备份里。
+    let survivor = tmp.write("app/.ull.exe.ullold-1-1", OLD);
+    let transit = tmp.write(
+        "app/.ull.exe.ullnew-1-1",
+        b"half a build from a dead attempt",
+    );
+
+    let staged = staged(&tmp);
+    let dest = app.join("ull.exe");
+    let receipt = install_staged(&staged, &dest, policy()).expect("新装应成功");
+
+    assert_eq!(receipt.backup, None, "dest 原本不存在 ⇒ 本次不建备份");
+    assert_eq!(fs::read(&dest).expect("目标"), UPDATE);
+    assert!(
+        survivor.exists(),
+        "崩溃现场唯一幸存的旧 exe 不许被删（用户靠它手工恢复）：{:?}",
+        names_in(&app)
+    );
+    assert_eq!(
+        fs::read(&survivor).expect("幸存副本"),
+        OLD,
+        "旧字节要原样留着"
+    );
+    assert!(
+        !transit.exists(),
+        "残留的中转名仍是垃圾，该清：{:?}",
+        names_in(&app)
+    );
+}
diff --git a/crates/core/src/update/tests/install_io_cases.rs b/crates/core/src/update/tests/install_io_cases.rs
new file mode 100644
index 0000000..3f19524
--- /dev/null
+++ b/crates/core/src/update/tests/install_io_cases.rs
@@ -0,0 +1,271 @@
+//! 替换的坏路径：跨卷降级、复制到一半失败、截断复制、最后一步改名失败、同卷不多搬一个字节。
+//!
+//! # 为什么要注入而不是造真盘
+//!
+//! 「跨卷」在 `install_xdev_cases` 里是**真跨卷**（真盘、真 `EXDEV`），但那需要机器上有第二块卷；
+//! 「复制写到一半失败」在真盘上根本没法确定性复现（要么让盘满，要么让杀软恰好在那一刻咬住）。
+//! 这两条恰好是本次修复最关键的路径，所以这里用 [`ReplaceFs`] 的注入器把系统调用变成输入：
+//!
+//! * 注入器能改的只有「rename/copy 这一次成不成功」；
+//! * 注入器**改不了**判据与顺序——`install_with` 与生产路径是同一份代码，只有 `&dyn` 后面那个
+//!   实现不同。
+//!
+//! 抓得住：跨卷时是否真的降级到「复制到目标同目录的中转名」；复制半途失败后目标是否仍是旧字节、
+//! 中转名是否被清掉；截断的复制是否被字节数判据拒掉；同卷是否一个字节都没多搬。
+//! 抓不住：真实文件系统的掉电/写缓存语义（`fsync` 从未被调用过），以及「复制期间目标盘被拔掉」
+//! 这类整卷消失的场景。
+
+use std::cell::Cell;
+use std::fs;
+use std::io;
+use std::path::Path;
+
+use crate::update::manifest::ReleaseManifest;
+use crate::update::replace_io::ReplaceFs;
+use crate::update::{install::install_with, stage, DirSource, ReplacePolicy, StagedPackage};
+
+use super::support::{artifact, manifest, names_in, release, TempDir};
+
+const UPDATE: &[u8] = b"new build bytes that must land whole";
+const OLD: &[u8] = b"old build bytes";
+
+fn policy() -> ReplacePolicy {
+    ReplacePolicy::new(1, std::time::Duration::from_millis(1))
+}
+
+fn staged(tmp: &TempDir) -> StagedPackage {
+    tmp.write("ull-test.zip", UPDATE);
+    let json = manifest(
+        "stable",
+        &[release(
+            "0.3.0",
+            "",
+            &[artifact("win-x64", "portable-exe", "ull-test.zip", UPDATE)],
+        )],
+    );
+    let parsed = ReleaseManifest::from_json(&json).expect("清单应可解析");
+    stage(
+        &DirSource::new(tmp.path()),
+        &parsed.releases[0].artifacts[0],
+        &tmp.join("staging"),
+    )
+    .expect("取包与校验应通过")
+}
+
+/// 复制这一步的表现。
+#[derive(Clone, Copy)]
+enum CopyMode {
+    /// 老实复制。
+    Normal,
+    /// 只写 `n` 字节就报错（真盘上「拷到一半失败」留下的半截文件）。
+    PartialThenError(usize),
+    /// 只写 `n` 字节但**声称**成功（模拟「长度判据必须抓住」的那一类坏复制）。
+    TruncateThenOk(usize),
+    /// 一律拒绝（用来证明同卷路径上没有复制）。
+    Forbidden,
+}
+
+/// 注入器：默认全权交给 `std::fs`，按开关制造跨卷与失败。
+struct FakeFs {
+    /// 「暂存包 → 中转名」这一步假装跨卷。
+    staged_rename_crosses: bool,
+    /// 中转名 → dest 这一步失败。
+    fail_final_rename: bool,
+    copy_mode: CopyMode,
+    copies: Cell,
+    renames: Cell,
+}
+
+impl FakeFs {
+    fn new() -> Self {
+        Self {
+            staged_rename_crosses: false,
+            fail_final_rename: false,
+            copy_mode: CopyMode::Normal,
+            copies: Cell::new(0),
+            renames: Cell::new(0),
+        }
+    }
+
+    fn across_volumes() -> Self {
+        Self {
+            staged_rename_crosses: true,
+            ..Self::new()
+        }
+    }
+
+    fn copies(&self) -> usize {
+        self.copies.get()
+    }
+
+    fn renames(&self) -> usize {
+        self.renames.get()
+    }
+}
+
+fn is_transit(path: &Path) -> bool {
+    path.file_name()
+        .is_some_and(|name| name.to_string_lossy().contains(".ullnew-"))
+}
+
+impl ReplaceFs for FakeFs {
+    fn rename(&self, from: &Path, to: &Path) -> io::Result<()> {
+        self.renames.set(self.renames.get() + 1);
+        if self.staged_rename_crosses && is_transit(to) {
+            return Err(io::Error::from(io::ErrorKind::CrossesDevices));
+        }
+        if self.fail_final_rename && is_transit(from) {
+            return Err(io::Error::other("模拟：中转名改名到目标失败"));
+        }
+        fs::rename(from, to)
+    }
+
+    fn copy(&self, from: &Path, to: &Path) -> io::Result {
+        self.copies.set(self.copies.get() + 1);
+        let bytes = fs::read(from)?;
+        match self.copy_mode {
+            CopyMode::Normal => fs::copy(from, to),
+            CopyMode::PartialThenError(wrote) => {
+                fs::write(to, &bytes[..wrote.min(bytes.len())])?;
+                Err(io::Error::other("模拟：复制到一半失败"))
+            }
+            CopyMode::TruncateThenOk(wrote) => {
+                let wrote = wrote.min(bytes.len());
+                fs::write(to, &bytes[..wrote])?;
+                Ok(wrote as u64)
+            }
+            CopyMode::Forbidden => Err(io::Error::other("这里不许复制")),
+        }
+    }
+
+    fn remove(&self, path: &Path) -> io::Result<()> {
+        fs::remove_file(path)
+    }
+}
+
+/// 目标目录里只该有 `ull.exe`（+ 可能的一份备份），中转名一律不许留。
+fn assert_no_transit(dir: &Path) {
+    let names = names_in(dir);
+    assert!(
+        names.iter().all(|name| !name.contains(".ullnew-")),
+        "中转名必须被清理：{names:?}"
+    );
+}
+
+/// ① 跨卷：降级为「复制到目标同目录的中转名」，装上去的必须是完整字节。
+#[test]
+fn cross_volume_falls_back_to_a_copy_beside_the_target() {
+    let fake = FakeFs::across_volumes();
+    let tmp = TempDir::new("io-xdev-ok");
+    let dest = tmp.write("app/ull.exe", OLD);
+    let staged = staged(&tmp);
+    let receipt = install_with(&fake, &staged, &dest, policy()).expect("跨卷必须成功");
+
+    assert_eq!(fs::read(&dest).expect("目标应存在"), UPDATE);
+    assert_eq!(receipt.bytes, UPDATE.len() as u64);
+    assert_eq!(
+        fake.copies(),
+        1,
+        "跨卷只该复制一次（降级路径唯一允许的复制）"
+    );
+    let backup = receipt.backup.clone().expect("旧版本应有备份");
+    assert_eq!(fs::read(&backup).expect("备份"), OLD);
+    assert_no_transit(dest.parent().expect("父目录"));
+}
+
+/// ② 复制写到一半失败：目标仍是旧字节、不留中转名、也不该动过备份。
+#[test]
+fn a_copy_that_dies_halfway_leaves_the_old_bytes_and_no_garbage() {
+    let fake = FakeFs {
+        copy_mode: CopyMode::PartialThenError(UPDATE.len() / 2),
+        ..FakeFs::across_volumes()
+    };
+    let tmp = TempDir::new("io-xdev-partial");
+    let dest = tmp.write("app/ull.exe", OLD);
+    let staged = staged(&tmp);
+    let failure = install_with(&fake, &staged, &dest, policy()).expect_err("半截复制必须失败");
+
+    assert!(
+        failure.rolled_back,
+        "目标没被碰过，旧版本仍在原位：{failure}"
+    );
+    assert_eq!(
+        fs::read(&dest).expect("旧版本"),
+        OLD,
+        "目标必须是完整的旧字节"
+    );
+    assert_no_transit(dest.parent().expect("父目录"));
+    assert!(
+        names_in(dest.parent().expect("父目录")) == ["ull.exe"],
+        "连备份都不该建（失败发生在动目标之前）：{:?}",
+        names_in(dest.parent().expect("父目录"))
+    );
+}
+
+/// ②′ 复制「声称成功」但字节数不符：长度判据必须拒掉，目标不动。
+#[test]
+fn a_short_copy_is_rejected_by_the_byte_count() {
+    let fake = FakeFs {
+        copy_mode: CopyMode::TruncateThenOk(UPDATE.len() - 1),
+        ..FakeFs::across_volumes()
+    };
+    let tmp = TempDir::new("io-xdev-short");
+    let dest = tmp.write("app/ull.exe", OLD);
+    let staged = staged(&tmp);
+    let failure = install_with(&fake, &staged, &dest, policy()).expect_err("短了必须拒");
+
+    assert!(failure.rolled_back, "{failure}");
+    assert_eq!(fs::read(&dest).expect("旧版本"), OLD);
+    assert!(
+        failure.error.message.contains("跨卷复制只写出"),
+        "失败原因要说清是字节数不符：{failure}"
+    );
+    assert_no_transit(dest.parent().expect("父目录"));
+}
+
+/// ②″ 最后一步改名失败：回滚到旧字节，中转名与备份都不留。
+#[test]
+fn a_failed_final_rename_rolls_back_and_cleans_up() {
+    let fake = FakeFs {
+        fail_final_rename: true,
+        ..FakeFs::across_volumes()
+    };
+    let tmp = TempDir::new("io-final-rename");
+    let dest = tmp.write("app/ull.exe", OLD);
+    let staged = staged(&tmp);
+    let failure = install_with(&fake, &staged, &dest, policy()).expect_err("改名失败必须报错");
+
+    assert!(failure.rolled_back, "旧版本应回到原位：{failure}");
+    assert_eq!(failure.backup_left, None);
+    assert_eq!(fs::read(&dest).expect("旧版本"), OLD);
+    assert_eq!(
+        names_in(dest.parent().expect("父目录")),
+        ["ull.exe"],
+        "中转名与备份都必须被清掉"
+    );
+}
+
+/// ③ 同卷：一个字节都不许复制（行为与修前一致）。
+///
+/// 注入器的 `copy` 一律报错——只要实现走了复制，这条就会红。
+#[test]
+fn the_same_volume_path_never_copies() {
+    let fake = FakeFs {
+        copy_mode: CopyMode::Forbidden,
+        ..FakeFs::new()
+    };
+    let tmp = TempDir::new("io-same-volume");
+    let dest = tmp.write("app/ull.exe", OLD);
+    let staged = staged(&tmp);
+    let receipt = install_with(&fake, &staged, &dest, policy()).expect("同卷替换必须成功");
+
+    assert_eq!(fs::read(&dest).expect("目标"), UPDATE);
+    assert_eq!(fake.copies(), 0, "同卷走改名，不许有复制");
+    assert_eq!(
+        fake.renames(),
+        3,
+        "同卷三步：暂存→中转名、目标→备份、中转名→目标（比修前多一次同卷改名、不多一个字节）"
+    );
+    assert_eq!(receipt.bytes, UPDATE.len() as u64);
+    assert_no_transit(dest.parent().expect("父目录"));
+}
diff --git a/crates/core/src/update/tests/install_xdev_cases.rs b/crates/core/src/update/tests/install_xdev_cases.rs
new file mode 100644
index 0000000..dcb0391
--- /dev/null
+++ b/crates/core/src/update/tests/install_xdev_cases.rs
@@ -0,0 +1,274 @@
+//! 跨卷替换：暂存包在 A 卷、目标 exe 在 B 卷时，替换必须成功且**不留半截文件**，
+//! 并且「凑不出跨卷现场」这件事**必须是响的**。
+//!
+//! # 这条用例为什么必须存在
+//!
+//! `stage()` 把包落在 `<数据根>/cache/update/staging`，`install_staged()` 把包搬进 exe 所在目录。
+//! 两者不在同一卷时（便携版放 U 盘、数据根设到 D 盘而程序在 C 盘、部分 macOS 配置），
+//! `fs::rename` 直接返回 `EXDEV`/`ERROR_NOT_SAME_DEVICE`（`CrossesDevices`）——M169 复审
+//! 在已发布版本上判定「更新必然失败」。修法是**先把包落到目标同目录的临时名，再同卷改名**：
+//! 目标路径上的新字节永远来自一次原子命名，不存在「拷到一半」的中间态。
+//!
+//! # 跨卷是探出来的，探不到**不许静默变绿**（M171 r2 P2-1）
+//!
+//! [`XdevRoot::probe`] 用一次真实 `rename` 验证候选目录**真的**在另一块卷上。问题是「探不到」
+//! 以前写成 `eprintln! + return`：libtest 默认捕获 stdout/stderr，于是这台机器只有一块卷时
+//! 用例显示 `... ok`，跨卷守卫**空跑了却看不出来**（复审 M3 变异实测）。本仓已确立的口径是
+//! 「跳过这件事必须是响的」（同 `crates/app-iced/.../options_shot/feed.rs::not_fed`），
+//! 所以裁决被收进 [`xdev_guard`]，三档：
+//!
+//! | 探到第二块卷 | `ULL_XDEV_TEST_WAIVE=1` | 结果 |
+//! |---|---|---|
+//! | 是 | 无所谓 | **绿**，真跨卷用例真跑（豁免只在探测失败时被咨询） |
+//! | 否 | 给了 | **绿**，并打印「已显式豁免」——这是**记录在案的**降级，不是意外 |
+//! | 否 | 没给 | **红**：本机/本作业的跨卷守卫没有生效 |
+//!
+//! 另有 `ULL_XDEV_TEST_REQUIRE=1`（声明「本机必须有第二块卷」）：与豁免同时给时以它为准
+//! （声明了必须有、实际没有 ⇒ 红），一句话里不许自相矛盾。`ULL_XDEV_TEST_ROOT` 可以直接
+//! 指定一块异卷目录（Windows 举例：`ULL_XDEV_TEST_ROOT=D:/Temp`）。
+//!
+//! # 谁该给哪个 env
+//!
+//! * **本仓开发机**（`C:` NVMe + `D:` 机械盘，见 [`volume_candidates`]）：什么都不用给，探得到。
+//! * **CI `test (ubuntu-latest)`**：`/tmp` 与会话临时目录同卷，但 `/dev/shm` 是另一块 tmpfs ⇒
+//!   通常直接探得到（本机 docker 里实测 `/tmp` 设备号 119、`/dev/shm` 158）。探不到就会红。
+//! * **CI `test (windows-latest)` / `update-e2e (windows-latest)`**：runner 是只有一块系统卷、
+//!   还是额外挂了一块临时盘（`D:`），**本仓没有核实手段**（没有 runner 权限，文档也没写死盘符）。
+//!   所以策略**不赌它**：探到就跑真跨卷；探不到就必须在作业里显式写
+//!   `ULL_XDEV_TEST_WAIVE: "1"`——这一行属 `.github/workflows/ci.yml`（不在 M171 的改动范围）。
+//!
+//! 只有注入用例（`install_io_cases`）永远在跑：它把「跨卷被拒」「复制到一半失败」直接喂给
+//! `install_with`，不依赖盘的分区布局。
+//!
+//! # 探不到时怎么办（三选一）
+//!
+//! 1. 给一块异卷目录：`ULL_XDEV_TEST_ROOT=<另一块卷上的可写目录>`；
+//! 2. 明确豁免：`ULL_XDEV_TEST_WAIVE=1`；
+//! 3. 认为自己本该有第二块卷 ⇒ `ULL_XDEV_TEST_REQUIRE=1`，让它在配置坏掉时就地红。
+
+use std::fs;
+
+use crate::update::manifest::ReleaseManifest;
+use crate::update::{install_staged, stage, DirSource, ReplacePolicy, StagedPackage};
+
+use super::support::{
+    artifact, manifest, names_in, release, TempDir, XdevRoot, XDEV_REQUIRE_ENV, XDEV_WAIVE_ENV,
+};
+
+const UPDATE: &[u8] = b"new build bytes, cross volume";
+const OLD: &[u8] = b"old build bytes";
+
+fn policy() -> ReplacePolicy {
+    ReplacePolicy::new(2, std::time::Duration::from_millis(1))
+}
+
+/// 跨卷守卫的裁决结果。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum XdevGuard {
+    /// 探到了第二块卷：真跨卷用例会真跑。
+    Live,
+    /// 没有第二块卷，但调用方**显式**豁免了。
+    Waived,
+}
+
+/// 裁决（纯函数：只吃「探到了吗」与两档环境变量，不读进程环境 ⇒ 并行跑不会互相干扰）。
+///
+/// 规则见模块文档的表。`require` 优先于 `waiver`：声明「必须有」又同时说「可以没有」是自相矛盾，
+/// 这时按更严的那条办——否则一句手误就把守卫关掉了。
+fn xdev_guard(
+    found: bool,
+    waiver: Option<&str>,
+    require: Option<&str>,
+) -> Result {
+    if found {
+        return Ok(XdevGuard::Live);
+    }
+    // 只认 `1`（`true`/`yes`/空串一律不算：手误不该开闸），两侧空白忽略。
+    let required = require.map(str::trim) == Some("1");
+    let waived = waiver.map(str::trim) == Some("1");
+    if waived && !required {
+        return Ok(XdevGuard::Waived);
+    }
+    Err(xdev_failure(required, waived))
+}
+
+/// 探不到第二块卷、又不许豁免时的失败正文（把「有哪三条出路」写全，别让人去猜）。
+fn xdev_failure(required: bool, waived: bool) -> String {
+    let lead = match (required, waived) {
+        (true, true) => concat!(
+            "同时给了 ULL_XDEV_TEST_REQUIRE=1 与 ULL_XDEV_TEST_WAIVE=1：自相矛盾。",
+            "以 REQUIRE 为准（声明了必须有，就没有豁免）。"
+        ),
+        (true, _) => {
+            "给了 ULL_XDEV_TEST_REQUIRE=1（声明本机必须有第二块卷），但这台机器上探不到——那是配置坏了，不是可以跳过。"
+        }
+        (false, _) => {
+            "没有第二块可写卷，也没有显式豁免：跨卷守卫在这台机器上是空跑。"
+        }
+    };
+    format!(
+        "[xdev-guard] {lead}\n\
+         这条守卫守的是已发布版本上的真 bug（数据根与程序不同卷 ⇒ 更新必然失败），\
+         空跑的守卫等于没有，所以默认判红。三种合规做法任选其一：\n\
+         1. 给它一块异卷目录：ULL_XDEV_TEST_ROOT=<另一块卷上的可写目录>（本机举例：D:/Temp）；\n\
+         2. 明确豁免：ULL_XDEV_TEST_WAIVE=1（值必须是 `1`）；\n\
+         3. 认为本机本该有第二块卷 ⇒ 用 ULL_XDEV_TEST_REQUIRE=1 声明，坏掉时就地红。\n\
+         CI：ubuntu runner 的 /dev/shm 与 /tmp 是不同设备（通常直接满足第 1 条）；\
+         windows runner 只有一块卷时，作业里要显式给第 2 条（.github/workflows/ci.yml 的 \
+         test 作业与 update-e2e 作业）。"
+    )
+}
+
+/// 要一块异卷现场来做真跨卷用例：`Some` = 探到了；`None` = **显式豁免**（已打印记录）。
+///
+/// 探不到又没豁免就 panic——这是给逐条用例用的入口，保证没有哪一条能靠 `return` 静静跳过。
+fn cross_volume_scene(tag: &str) -> Option {
+    let root = XdevRoot::probe(tag);
+    let verdict = xdev_guard(
+        root.is_some(),
+        std::env::var(XDEV_WAIVE_ENV).ok().as_deref(),
+        std::env::var(XDEV_REQUIRE_ENV).ok().as_deref(),
+    );
+    match verdict {
+        Ok(XdevGuard::Live) => root,
+        Ok(XdevGuard::Waived) => {
+            eprintln!(
+                "[xdev-guard] {XDEV_WAIVE_ENV}=1：本机没有第二块可写卷，真跨卷用例（{tag}）\
+                 按显式豁免跳过——跨卷逻辑此刻只有 install_io_cases 的注入用例在守。"
+            );
+            None
+        }
+        Err(message) => panic!("{message}"),
+    }
+}
+
+/// **常跑的裁决用例**：跨卷守卫要么在真跑，要么有记录在案的豁免，要么红。
+///
+/// 它自己不需要第二块卷也能跑，所以永远被执行；`--nocapture` 下能看到走的是哪一档。
+#[test]
+fn the_cross_volume_guard_is_live_or_explicitly_waived() {
+    let root = XdevRoot::probe("verdict");
+    let waiver = std::env::var(XDEV_WAIVE_ENV).ok();
+    let require = std::env::var(XDEV_REQUIRE_ENV).ok();
+    match xdev_guard(root.is_some(), waiver.as_deref(), require.as_deref()) {
+        Ok(XdevGuard::Live) => {
+            let at = root.as_ref().map(|root| root.path().display().to_string());
+            eprintln!(
+                "[xdev-guard] 探到第二块可写卷（{}）：真跨卷用例会真跑。",
+                at.unwrap_or_default()
+            );
+        }
+        Ok(XdevGuard::Waived) => {
+            eprintln!(
+                "[xdev-guard] 本机没有第二块可写卷，但已显式豁免（{XDEV_WAIVE_ENV}=1）：\
+                 真跨卷用例跳过，跨卷逻辑由 install_io_cases 的注入用例守着。"
+            );
+        }
+        Err(message) => panic!("{message}"),
+    }
+}
+
+/// 裁决表的每一格都得钉住——尤其「既没探到也没豁免 ⇒ 红」这一格（P2-1 的回归点）。
+#[test]
+fn the_verdict_table_has_exactly_three_ways() {
+    // 探到了：永远是 Live（豁免给了也不影响，真跨卷用例照跑）。
+    for (waiver, require) in [(None, None), (Some("1"), None), (None, Some("1"))] {
+        assert_eq!(
+            xdev_guard(true, waiver, require),
+            Ok(XdevGuard::Live),
+            "探到了就该真跑：{waiver:?}/{require:?}"
+        );
+    }
+    // 探不到 + 显式豁免 ⇒ Waived（记录在案的降级）。
+    assert_eq!(xdev_guard(false, Some("1"), None), Ok(XdevGuard::Waived));
+    assert_eq!(
+        xdev_guard(false, Some(" 1 "), None),
+        Ok(XdevGuard::Waived),
+        "两侧空白应忽略"
+    );
+    // 探不到 + 没豁免 ⇒ 红（这条就是 P2-1 要的那个「响」）。
+    let error = xdev_guard(false, None, None).expect_err("没豁免就必须红");
+    assert!(error.contains("空跑"), "失败正文要说清是空跑：{error}");
+    // 只认 `1`。
+    for bogus in [Some("true"), Some("yes"), Some(""), Some("0")] {
+        assert!(
+            xdev_guard(false, bogus, None).is_err(),
+            "只有 `1` 算豁免，{bogus:?} 不算"
+        );
+    }
+    // 声明「必须有」⇒ 探不到就红，且 REQUIRE 压过 WAIVE（不许自相矛盾地放行）。
+    let error = xdev_guard(false, None, Some("1")).expect_err("声明了必须有就必须红");
+    assert!(error.contains("REQUIRE"), "{error}");
+    let error = xdev_guard(false, Some("1"), Some("1")).expect_err("矛盾时按更严的办");
+    assert!(error.contains("自相矛盾"), "{error}");
+}
+
+/// 在 `tmp`（会话临时目录 = A 卷）里造一份已校验的暂存包。
+fn staged_on_a_volume(tmp: &TempDir) -> StagedPackage {
+    tmp.write("ull-test.zip", UPDATE);
+    let json = manifest(
+        "stable",
+        &[release(
+            "0.3.0",
+            "",
+            &[artifact("win-x64", "portable-exe", "ull-test.zip", UPDATE)],
+        )],
+    );
+    let parsed = ReleaseManifest::from_json(&json).expect("清单应可解析");
+    stage(
+        &DirSource::new(tmp.path()),
+        &parsed.releases[0].artifacts[0],
+        &tmp.join("staging"),
+    )
+    .expect("取包与校验应通过")
+}
+
+/// ① 跨卷安装必须成功，且目标字节 = 包体字节（不是半截、不是旧字节）。
+#[test]
+fn installs_across_volumes_and_lands_the_exact_bytes() {
+    let Some(xdev) = cross_volume_scene("install") else {
+        return;
+    };
+    let tmp = TempDir::new("xdev-install");
+    let staged = staged_on_a_volume(&tmp);
+    let app = xdev.dir("app");
+    let dest = app.join("ull.exe");
+    fs::write(&dest, OLD).expect("写旧版本");
+
+    // 前提断言：暂存与目标**真的**不在同一卷（否则这条用例只是在同卷上重跑一遍）。
+    let cross =
+        fs::rename(staged.path(), app.join("probe-move")).expect_err("跨卷 rename 必须失败");
+    assert_eq!(
+        cross.kind(),
+        std::io::ErrorKind::CrossesDevices,
+        "前提不成立：暂存与目标同卷（{cross}）"
+    );
+
+    let receipt = install_staged(&staged, &dest, policy()).expect("跨卷替换必须成功");
+
+    assert_eq!(
+        fs::read(&dest).expect("目标应存在"),
+        UPDATE,
+        "目标必须就是包体字节"
+    );
+    assert_eq!(receipt.bytes, UPDATE.len() as u64);
+    assert_eq!(receipt.dest, dest);
+    let backup = receipt.backup.clone().expect("旧版本应留备份");
+    assert_eq!(backup.parent(), dest.parent(), "备份必须与目标同目录");
+    assert_eq!(
+        fs::read(&backup).expect("备份应存在"),
+        OLD,
+        "旧字节要完整留在备份里"
+    );
+    let names = names_in(&app);
+    assert_eq!(
+        names.len(),
+        2,
+        "目标目录里只该有目标与一份备份（跨卷中转的临时名必须被改掉、不许残留）：{names:?}"
+    );
+    assert_eq!(names[1], "ull.exe", "排序后目标在后：{names:?}");
+    assert!(
+        names[0].starts_with(".ull.exe.ullold-"),
+        "另一个必须是备份：{names:?}"
+    );
+}
diff --git a/crates/core/src/update/tests/job_cases.rs b/crates/core/src/update/tests/job_cases.rs
new file mode 100644
index 0000000..68dc5ac
--- /dev/null
+++ b/crates/core/src/update/tests/job_cases.rs
@@ -0,0 +1,276 @@
+//! `Job`（检查/应用的一条龙）的用例：包形态闸门、一条成功的自替换、测试通道的两档判据。
+//!
+//! 为什么这层要单独测：`Release::artifact_for` 只比 `target`、不看 `format`，所以「清单给
+//! win-x64 挂了一个 msi/zip」是完全可能的输入（复审 P3-6）。以前 `apply` 会把它直接 rename
+//! 成本进程的 exe——D50 明说「不做 MSI」，而 zip 当 exe 更是跑不起来。闸门在本模块，
+//! 用例就在这里钉住（presenter / CLI 的测试覆盖不到「形态」这一维）。
+
+use crate::platform::os_info::OsFamily;
+use crate::update::job::self_replaceable;
+use crate::update::{
+    Applied, Channel, DirSource, Job, PackageFormat, Target, UpdateErrorKind, Version,
+};
+
+use super::support::{artifact, manifest, release, TempDir};
+
+const PAYLOAD: &[u8] = b"job payload";
+
+fn target() -> Target {
+    Target::new(OsFamily::Windows, crate::update::Arch::X64)
+}
+
+/// 造一个本地源 + 一个替换目标；返回的 `TempDir` 要活到用例结束。
+fn fixture(format: &str, version: &str) -> (TempDir, Job) {
+    let dir = TempDir::new("job");
+    dir.write_signed(
+        "stable.json",
+        &manifest(
+            "stable",
+            &[release(
+                version,
+                "",
+                &[artifact("win-x64", format, "asset.bin", PAYLOAD)],
+            )],
+        ),
+    );
+    dir.write("asset.bin", PAYLOAD);
+    let dest = dir.join("bin/unlucky-launcher.exe");
+    if let Some(parent) = dest.parent() {
+        std::fs::create_dir_all(parent).expect("建目标目录");
+    }
+    std::fs::write(&dest, b"old-bytes").expect("旧版本");
+    let staging = dir.join("staging");
+    let job = Job::new(
+        Box::new(DirSource::new(dir.path())),
+        target(),
+        staging,
+        dest,
+    );
+    (dir, job)
+}
+
+/// 只有便携单文件 exe 能原地变成启动器本体。
+///
+/// 抓得住：把闸门写成 `!needs_installer()`（那样 `portable-zip` 会漏过去，zip 会被 rename 成
+/// exe，得到一个跑不起来的启动器）。
+#[test]
+fn only_portable_exe_is_self_replaceable() {
+    assert!(self_replaceable(PackageFormat::PortableExe));
+    for format in [
+        PackageFormat::Msi,
+        PackageFormat::Dmg,
+        PackageFormat::Deb,
+        PackageFormat::Rpm,
+        PackageFormat::AppImage,
+        PackageFormat::PortableZip,
+    ] {
+        assert!(
+            !self_replaceable(format),
+            "{} 不该被当成可原地自替换的形态",
+            format.as_str()
+        );
+    }
+}
+
+/// 安装器形态被拒绝，且**目标文件一个字节都没动、暂存目录没建**（闸门在取包之前）。
+#[test]
+fn an_installer_artifact_is_refused_before_any_download() {
+    for format in ["msi", "portable-zip"] {
+        let (dir, job) = fixture(format, "9.9.9");
+        let error = job
+            .apply(&Version::parse("0.2.2").expect("版本"), Channel::Stable)
+            .expect_err("不该装上");
+        assert_eq!(
+            error.kind,
+            UpdateErrorKind::InvalidManifest,
+            "{format}：清单挂错形态属发布侧问题（换源/重试都没用），实际 {error:?}"
+        );
+        assert_eq!(
+            std::fs::read(job.dest()).expect("读目标"),
+            b"old-bytes",
+            "{format}：拒绝之后目标文件不许被动过"
+        );
+        assert!(
+            !job.staging().exists(),
+            "{format}：闸门在取包之前，暂存目录都不该被建出来"
+        );
+        drop(dir);
+    }
+}
+
+/// 便携 exe 形态走完整条路：新字节就位、旧字节进备份。
+#[test]
+fn a_portable_exe_runs_the_whole_chain() {
+    let (_dir, job) = fixture("portable-exe", "9.9.9");
+    let applied = job
+        .apply(&Version::parse("0.2.2").expect("版本"), Channel::Stable)
+        .expect("应当装上");
+    let Applied::Installed { receipt, version } = applied else {
+        panic!("应当装上");
+    };
+    assert_eq!(version, "9.9.9");
+    assert_eq!(std::fs::read(job.dest()).expect("读目标"), PAYLOAD);
+    let backup = receipt.backup.expect("旧版本应留备份");
+    assert_eq!(std::fs::read(backup).expect("读备份"), b"old-bytes");
+}
+
+/// 发布里挂的是「没有可装更新」时 `apply` 返回 `Nothing`，不碰任何文件。
+#[test]
+fn nothing_to_apply_does_not_touch_the_target() {
+    let dir = TempDir::new("job-none");
+    dir.write_signed(
+        "stable.json",
+        &manifest(
+            "stable",
+            &[release(
+                "0.2.2",
+                "",
+                &[artifact("win-x64", "portable-exe", "asset.bin", PAYLOAD)],
+            )],
+        ),
+    );
+    let dest = dir.join("bin/unlucky-launcher.exe");
+    std::fs::create_dir_all(dest.parent().expect("父目录")).expect("建目录");
+    std::fs::write(&dest, b"old-bytes").expect("旧版本");
+    let job = Job::new(
+        Box::new(DirSource::new(dir.path())) as Box,
+        target(),
+        dir.join("staging"),
+        &dest,
+    );
+    let applied = job
+        .apply(&Version::parse("0.2.2").expect("版本"), Channel::Stable)
+        .expect("不是错误");
+    assert!(matches!(applied, Applied::Nothing(_)));
+    assert_eq!(std::fs::read(&dest).expect("读目标"), b"old-bytes");
+}
+
+/// 测试通道的判据是**编译期开 + 两档全给**：`--features update-test-source`、`ULL_UPDATE_DIR`、
+/// `ULL_UPDATE_TEST_SOURCE=1`。
+///
+/// 旧判据是 `cfg!(debug_assertions)`（debug 认、release 整段折叠掉），M169 换掉它是因为发布
+/// 产物正是 release——拿 release 验不了这条链，整条更新通道就没有端到端证据。换判据必须补隔离：
+/// 编译期 feature 保证**官方二进制里不存在这条路**，两档环境变量保证「开了 feature 的验收构建」
+/// 也不会被继承来的单个环境变量悄悄改源。这条用例守后者（纯判据，不碰进程环境）。
+#[cfg(feature = "update-test-source")]
+#[test]
+fn the_test_channel_needs_both_switches() {
+    use std::path::PathBuf;
+
+    use crate::update::job::test_source_root_from;
+
+    assert_eq!(
+        test_source_root_from(Some("/d/dist"), Some("1")),
+        Some(PathBuf::from("/d/dist")),
+        "两档全给才开"
+    );
+    assert_eq!(
+        test_source_root_from(Some("  /d/dist \n"), Some(" 1 ")),
+        Some(PathBuf::from("/d/dist")),
+        "路径与承认值两侧空白忽略"
+    );
+
+    assert_eq!(
+        test_source_root_from(Some("/d/dist"), None),
+        None,
+        "只给路径不许改源（旧的单变量口子）"
+    );
+    assert_eq!(
+        test_source_root_from(None, Some("1")),
+        None,
+        "只给承认档但没有路径"
+    );
+    for ack in ["true", "yes", "on", "0", "", "  "] {
+        assert_eq!(
+            test_source_root_from(Some("/d/dist"), Some(ack)),
+            None,
+            "承认值 `{ack}` 不算（手误不该开闸）"
+        );
+    }
+    assert_eq!(
+        test_source_root_from(Some("   "), Some("1")),
+        None,
+        "空路径按没给处理（`ULL_UPDATE_DIR=` 不该被读成当前目录）"
+    );
+}
+
+/// 环境变量 → [`default_source`] 的接线，**两种构建各断各的**：
+///
+/// * 带 `update-test-source`（验收构建）：两档全给才换成 `file:` 源；半开仍走 GitHub；去掉承认档
+///   立刻回到 GitHub（判据不缓存）。
+/// * 不带 feature（**官方发布构建**）：环境变量设满了也照样走 GitHub——这条分支根本不存在。
+///
+/// 后者是本 mission 的关键断言：README 承诺「release 构建里不存在这条路径」，判据是编译期的，
+/// 所以只能在「不带 feature 的测试跑」时验证。
+///
+/// 用例动的是**进程环境变量**（全局状态），所以先用一把进程内锁串起来、退出时还原原值——
+/// `update` 的单测在同一个测试进程里并行跑。
+#[test]
+fn the_test_channel_is_a_compile_time_opt_in() {
+    use crate::download::RegionProfile;
+    use crate::update::job::{UPDATE_DIR_ENV, UPDATE_TEST_SOURCE_ENV};
+    use crate::update::{default_source, github};
+
+    static ENV_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
+    let _serial = ENV_LOCK
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner());
+
+    /// 记住两个变量的原值，`Drop` 时还原（用例 panic 也还原）。
+    struct Restore(Option, Option);
+    impl Drop for Restore {
+        fn drop(&mut self) {
+            for (key, value) in [
+                (UPDATE_DIR_ENV, self.0.clone()),
+                (UPDATE_TEST_SOURCE_ENV, self.1.clone()),
+            ] {
+                match value {
+                    Some(value) => std::env::set_var(key, value),
+                    None => std::env::remove_var(key),
+                }
+            }
+        }
+    }
+
+    let tmp = TempDir::new("job-env");
+    let _restore = Restore(
+        std::env::var_os(UPDATE_DIR_ENV),
+        std::env::var_os(UPDATE_TEST_SOURCE_ENV),
+    );
+    let github_id = format!("github:{}/{}", github::DEFAULT_OWNER, github::DEFAULT_REPO);
+    let engine = || super::support::engine_for(&tmp, RegionProfile::direct(0));
+    let root = tmp.join("dist");
+
+    // 两档都给满（不带 feature 的构建里这是最强的「攻击面」输入）。
+    std::env::set_var(UPDATE_DIR_ENV, &root);
+    std::env::set_var(UPDATE_TEST_SOURCE_ENV, "1");
+
+    #[cfg(not(feature = "update-test-source"))]
+    {
+        assert_eq!(
+            default_source(engine()).source_id(),
+            github_id,
+            "不带 `update-test-source` 的构建（= 官方发布）里，环境变量设满了也不许改源：{root:?}"
+        );
+    }
+
+    #[cfg(feature = "update-test-source")]
+    {
+        use crate::update::job::test_source_root;
+
+        assert_eq!(
+            default_source(engine()).source_id(),
+            format!("file:{}", root.display()),
+            "带 feature：两档全给才换成本地目录源"
+        );
+        assert_eq!(test_source_root(), Some(root.clone()));
+
+        std::env::remove_var(UPDATE_TEST_SOURCE_ENV);
+        assert_eq!(
+            default_source(engine()).source_id(),
+            github_id,
+            "半开（只给路径）必须回到 GitHub——旧的单变量口子不再生效"
+        );
+        assert_eq!(test_source_root(), None);
+    }
+}
diff --git a/crates/core/src/update/tests/manifest_cases.rs b/crates/core/src/update/tests/manifest_cases.rs
new file mode 100644
index 0000000..5e6a6b0
--- /dev/null
+++ b/crates/core/src/update/tests/manifest_cases.rs
@@ -0,0 +1,258 @@
+//! 清单解析与校验：字段拼错、重复版本、零长度、摘要格式、产物优先级。
+
+use crate::download::HashAlgo;
+use crate::platform::os_info::OsFamily;
+use crate::update::manifest::ReleaseManifest;
+use crate::update::{Arch, Channel, PackageFormat, Target, UpdateErrorKind};
+
+use super::support::{artifact, manifest, release, sha256};
+
+const PAYLOAD: &[u8] = b"fake portable zip payload";
+
+#[test]
+fn parses_a_full_manifest() {
+    let json = manifest(
+        "stable",
+        &[release(
+            "0.3.0",
+            r#","released_at":"2026-01-02T03:04:05Z","notes":"修掉启动崩溃","min_supported":"0.2.0""#,
+            &[
+                artifact("win-x64", "portable-zip", "ull-0.3.0-win-x64.zip", PAYLOAD),
+                artifact(
+                    "linux-x64",
+                    "appimage",
+                    "ull-0.3.0-linux-x64.AppImage",
+                    PAYLOAD,
+                ),
+            ],
+        )],
+    );
+    let parsed = ReleaseManifest::from_json(&json).expect("清单应可解析");
+    assert_eq!(parsed.channel, Channel::Stable);
+    assert_eq!(parsed.releases.len(), 1);
+    let first = &parsed.releases[0];
+    assert_eq!(first.version.to_string(), "0.3.0");
+    assert_eq!(first.channel, Channel::Stable, "渠道字段缺省时继承清单渠道");
+    assert_eq!(first.notes.as_deref(), Some("修掉启动崩溃"));
+    assert_eq!(
+        first.min_supported.as_ref().map(ToString::to_string),
+        Some("0.2.0".to_string())
+    );
+    assert!(!first.force);
+    assert_eq!(first.artifacts.len(), 2);
+    let windows = &first.artifacts[0];
+    assert_eq!(windows.target, Target::new(OsFamily::Windows, Arch::X64));
+    assert_eq!(windows.format, PackageFormat::PortableZip);
+    assert_eq!(windows.integrity.algo, HashAlgo::Sha256);
+    assert_eq!(windows.integrity.hex, sha256(PAYLOAD));
+    assert_eq!(windows.size, PAYLOAD.len() as u64);
+}
+
+#[test]
+fn release_can_override_the_manifest_channel() {
+    let json = manifest("beta", &[release("0.3.0", r#","channel":"stable""#, &[])]);
+    let parsed = ReleaseManifest::from_json(&json).expect("清单应可解析");
+    assert_eq!(parsed.releases[0].channel, Channel::Stable);
+}
+
+#[test]
+fn rejects_duplicate_versions() {
+    let json = manifest(
+        "stable",
+        &[
+            release("0.3.0", "", &[]),
+            release("0.3.0", r#","notes":"重复""#, &[]),
+        ],
+    );
+    let error = ReleaseManifest::from_json(&json).expect_err("重复版本应失败");
+    assert_eq!(error.kind, UpdateErrorKind::InvalidManifest);
+    assert!(error.to_string().contains("0.3.0"));
+}
+
+#[test]
+fn rejects_zero_size_artifact() {
+    let json = manifest(
+        "stable",
+        &[release(
+            "0.3.0",
+            "",
+            &[format!(
+                r#"{{"target":"win-x64","format":"msi","url":"a.msi","size":0,"sha256":"{}"}}"#,
+                sha256(b"")
+            )],
+        )],
+    );
+    let error = ReleaseManifest::from_json(&json).expect_err("size=0 应失败");
+    assert_eq!(error.kind, UpdateErrorKind::InvalidManifest);
+    assert!(error.to_string().contains("size"));
+}
+
+#[test]
+fn rejects_unknown_fields() {
+    let json = r#"{"channel":"stable","relases":[]}"#;
+    let error = ReleaseManifest::from_json(json).expect_err("拼错的字段名应失败");
+    assert_eq!(error.kind, UpdateErrorKind::InvalidManifest);
+}
+
+#[test]
+fn rejects_artifact_without_digest() {
+    let json = manifest(
+        "stable",
+        &[release(
+            "0.3.0",
+            "",
+            &[r#"{"target":"win-x64","format":"msi","url":"a.msi","size":12}"#.to_string()],
+        )],
+    );
+    let error = ReleaseManifest::from_json(&json).expect_err("缺摘要应失败");
+    assert!(error.to_string().contains("sha256"));
+}
+
+#[test]
+fn rejects_malformed_digest() {
+    let json = manifest(
+        "stable",
+        &[release(
+            "0.3.0",
+            "",
+            &[
+                r#"{"target":"win-x64","format":"msi","url":"a.msi","size":12,"sha256":"abc"}"#
+                    .to_string(),
+            ],
+        )],
+    );
+    let error = ReleaseManifest::from_json(&json).expect_err("摘要长度不对应失败");
+    assert_eq!(error.kind, UpdateErrorKind::InvalidManifest);
+}
+
+#[test]
+fn accepts_sha1_only_and_normalises_case() {
+    // 64 位 hex 挂 sha1 名头是错长度的，先确认它真的被挡下
+    let wrong_length = manifest(
+        "stable",
+        &[release(
+            "0.3.0",
+            "",
+            &[format!(
+                r#"{{"target":"win-x64","format":"msi","url":"a.msi","size":12,"sha1":"{}"}}"#,
+                sha256(PAYLOAD)
+            )],
+        )],
+    );
+    assert!(ReleaseManifest::from_json(&wrong_length).is_err());
+
+    let json = manifest(
+        "stable",
+        &[release(
+            "0.3.0",
+            "",
+            &[format!(
+                r#"{{"target":"win-x64","format":"msi","url":"a.msi","size":12,"sha1":"{}"}}"#,
+                "A".repeat(40)
+            )],
+        )],
+    );
+    let parsed = ReleaseManifest::from_json(&json).expect("只有 sha1 也应可解析");
+    let integrity = &parsed.releases[0].artifacts[0].integrity;
+    assert_eq!(integrity.algo, HashAlgo::Sha1);
+    assert_eq!(integrity.hex, "a".repeat(40), "摘要统一归一化为小写");
+}
+
+#[test]
+fn sha256_wins_when_both_digests_are_present() {
+    let json = manifest(
+        "stable",
+        &[release(
+            "0.3.0",
+            "",
+            &[format!(
+                r#"{{"target":"win-x64","format":"msi","url":"a.msi","size":12,"sha1":"{}","sha256":"{}"}}"#,
+                "a".repeat(40),
+                sha256(PAYLOAD)
+            )],
+        )],
+    );
+    let parsed = ReleaseManifest::from_json(&json).expect("两个摘要都在时应可解析");
+    assert_eq!(
+        parsed.releases[0].artifacts[0].integrity.algo,
+        HashAlgo::Sha256
+    );
+}
+
+#[test]
+fn rejects_unknown_target_and_format() {
+    let bad_target = manifest(
+        "stable",
+        &[release(
+            "0.3.0",
+            "",
+            &[artifact("solaris-x64", "msi", "a.msi", PAYLOAD)],
+        )],
+    );
+    let error = ReleaseManifest::from_json(&bad_target).expect_err("未知平台应失败");
+    assert!(error.to_string().contains("solaris-x64"));
+
+    let bad_format = manifest(
+        "stable",
+        &[release(
+            "0.3.0",
+            "",
+            &[artifact("win-x64", "tar.gz", "a.tgz", PAYLOAD)],
+        )],
+    );
+    let error = ReleaseManifest::from_json(&bad_format).expect_err("未知格式应失败");
+    assert!(error.to_string().contains("tar.gz"));
+}
+
+#[test]
+fn artifact_order_is_the_priority() {
+    let json = manifest(
+        "stable",
+        &[release(
+            "0.3.0",
+            "",
+            &[
+                artifact("win-x64", "portable-zip", "a.zip", PAYLOAD),
+                artifact("win-x64", "msi", "a.msi", PAYLOAD),
+            ],
+        )],
+    );
+    let parsed = ReleaseManifest::from_json(&json).expect("清单应可解析");
+    let target = Target::new(OsFamily::Windows, Arch::X64);
+    let artifact = parsed.releases[0]
+        .artifact_for(target)
+        .expect("应有 win-x64 产物");
+    assert_eq!(artifact.format, PackageFormat::PortableZip, "先写先选");
+}
+
+#[test]
+fn newest_artifact_for_skips_releases_without_the_target() {
+    let json = manifest(
+        "stable",
+        &[
+            release(
+                "0.3.0",
+                "",
+                &[artifact("win-x64", "portable-zip", "a.zip", PAYLOAD)],
+            ),
+            release(
+                "0.4.0",
+                "",
+                &[artifact("linux-x64", "appimage", "b.AppImage", PAYLOAD)],
+            ),
+        ],
+    );
+    let parsed = ReleaseManifest::from_json(&json).expect("清单应可解析");
+    let (release, _) = parsed
+        .newest_artifact_for(Target::new(OsFamily::Windows, Arch::X64))
+        .expect("win-x64 只有 0.3.0 有货");
+    assert_eq!(release.version.to_string(), "0.3.0");
+}
+
+#[test]
+fn empty_release_list_is_valid() {
+    let parsed = ReleaseManifest::from_json(r#"{"channel":"nightly","releases":[]}"#)
+        .expect("空清单是合法状态（还没发过版）");
+    assert_eq!(parsed.channel, Channel::Nightly);
+    assert!(parsed.releases.is_empty());
+}
diff --git a/crates/core/src/update/tests/mod.rs b/crates/core/src/update/tests/mod.rs
new file mode 100644
index 0000000..5ec5af5
--- /dev/null
+++ b/crates/core/src/update/tests/mod.rs
@@ -0,0 +1,36 @@
+//! `update` 的单元测试。
+//!
+//! 覆盖面（与 mission 的验收条目一一对应）：
+//!
+//! * 版本比较边界：`0.9` vs `0.10`、预发布 vs 正式、alpha/beta/rc、构建元数据不排序；
+//! * 清单校验：重复版本、零长度、缺摘要/摘要格式错、未知平台与格式；
+//! * 渠道准入：阶梯比较 + 预发布阶段表；
+//! * 校验失败：摘要不符、包体截断（短了/多了）、失败后暂存文件不残留；
+//! * 替换与回滚：成功后备份仍在、搬一半失败回滚、目标目录不可写、Windows 占用、
+//!   跨卷（暂存在 A 卷、目标在 B 卷）安装成功且字节完整、中途失败不留半截文件、
+//!   同卷不多搬一个字节、旧备份只留最近一份（崩溃现场的唯一旧副本例外）、
+//!   跨卷守卫「探不到第二块卷」时不许静默变绿（裁决用例见 `install_xdev_cases`）；
+//! * 一条龙（`job`）：只有便携单文件 exe 能原地自替换（msi/zip 在取包之前就被拒）、
+//!   「没有可装更新」不碰目标、测试通道是**编译期 opt-in**（官方发布构建里那段根本编不进来，
+//!   带 feature 时还要 `ULL_UPDATE_DIR` + `ULL_UPDATE_TEST_SOURCE=1` 两档全给）；
+//! * 更新源：缺清单不是错误、渠道不符报错、远端地址拒绝；
+//! * GitHub 源：固定清单地址、产物 URL 解析、非 stable 无更新、与 `DirSource` 对拍。
+//!
+//! 全程离线：所有字节都在临时目录或 127.0.0.1 的假 HTTP 服务上造，没有一个用例发公网请求。
+
+mod channel_cases;
+mod checker_cases;
+mod ed25519_cases;
+mod github_cases;
+mod install_cases;
+mod install_io_cases;
+mod install_xdev_cases;
+mod job_cases;
+mod manifest_cases;
+mod signature_cases;
+mod source_cases;
+mod support;
+mod support_sign;
+mod target_cases;
+mod verify_cases;
+mod version_cases;
diff --git a/crates/core/src/update/tests/signature_cases.rs b/crates/core/src/update/tests/signature_cases.rs
new file mode 100644
index 0000000..9716926
--- /dev/null
+++ b/crates/core/src/update/tests/signature_cases.rs
@@ -0,0 +1,294 @@
+//! 清单签名：**先验签再解析**（M190）。
+//!
+//! 这一组用例是 mission 守卫里「更新侧」的那几条，每条都能单独变红：
+//!
+//! | 用例 | 红掉意味着什么 |
+//! |---|---|
+//! | `tampered_field_is_rejected` | 改清单里任意一个字段仍能装 → 签名判据被绕过 |
+//! | `tampered_signature_only_is_rejected` | 只改签名文件、内容不动仍能装 → 「只改签名不换内容」没被拒 |
+//! | `missing_signature_is_rejected` | 没有 `.sig` 也照装 → 发布侧漏签名即可绕过整套信任根 |
+//! | `unknown_key_is_rejected` | 别人用自己的钥签的清单被认 → 信任锚不是钉死的那把 |
+//! | `key_id_spoofing_does_not_help` | 按 `key_id` 名字信任而不是按公钥字节验 → 伪个名字就能签 |
+//! | `unsigned_install_never_touches_the_target` | 验签失败却已经动过目标 exe → 判据跑在安装之后（顺序错） |
+//! | `no_runtime_keyring_override` | 环境变量/旁边的 keyring 文件能换信任锚 → 钉在二进制里的公钥白钉 |
+//!
+//! 还有一条「两条判据互不替代」：`sha256_mismatch_is_reported_separately` 证明签名过了、包体摘要
+//! 不符时仍是 `DigestMismatch`——签名管「清单是不是我们发的」，sha256 管「包体和清单对不对得上」。
+
+use std::fs;
+
+use crate::update::{
+    trust, verified_manifest, Channel, DirSource, Job, OsFamily, Target, UpdateChecker,
+    UpdateErrorKind, Version,
+};
+
+use super::support::{artifact, manifest, release, TempDir};
+use super::support_sign::{
+    public_key_hex, sign_bytes, signature_entry, signature_entry_from_bytes, signature_envelope,
+    signature_envelope_of, signature_envelope_with, TEST_KEY_ID, TEST_SIGNING_SEED,
+};
+
+const PAYLOAD: &[u8] = b"signed release payload";
+
+/// 另一把「攻击者的钥」：种子换一个词，公钥就完全不同。
+const ATTACKER_SEED: &[u8; 32] = b"ull-m190-attacker-seed-000000001";
+
+fn target() -> Target {
+    Target::new(OsFamily::Windows, crate::update::Arch::X64)
+}
+
+fn stable_json(version: &str) -> String {
+    manifest(
+        "stable",
+        &[release(
+            version,
+            "",
+            &[artifact("win-x64", "portable-exe", "asset.bin", PAYLOAD)],
+        )],
+    )
+}
+
+fn current() -> Version {
+    Version::parse("0.2.0").expect("版本号合法")
+}
+
+#[test]
+fn pinned_test_key_matches_the_test_seed() {
+    // 信任表里那把测试钥必须就是测试种子推出来的那把。漂了的话「钉住的公钥」与「签名的钥」不是同一个，
+    // 下面所有正路用例会一起变红——先在这里单独钉死。
+    let derived = public_key_hex(TEST_SIGNING_SEED);
+    let pinned = trust::keyring()
+        .iter()
+        .find(|key| key.key_id == TEST_KEY_ID)
+        .expect("测试构建的信任表里必须有测试钥");
+    assert_eq!(
+        pinned.public_key_hex, derived,
+        "钉住的测试公钥与测试种子不匹配"
+    );
+}
+
+#[test]
+fn signed_manifest_is_accepted_and_picks_the_candidate() {
+    let dir = TempDir::new("sig-ok");
+    dir.write_signed("stable.json", &stable_json("0.3.0"));
+    let outcome = UpdateChecker::new(DirSource::new(dir.path()), target())
+        .check(¤t(), Channel::Stable)
+        .expect("签名对得上就不该报错");
+    assert_eq!(
+        outcome.candidate().map(|c| c.release.version.to_string()),
+        Some("0.3.0".to_string())
+    );
+}
+
+#[test]
+fn tampered_field_is_rejected() {
+    // 守卫①：清单里改一个字段（版本号多一个数字），签名不跟着换 ⇒ 必须拒。
+    let original = stable_json("0.3.0");
+    let tampered = stable_json("0.3.1");
+    assert_ne!(original, tampered, "两次生成的清单必须真的不同");
+
+    let dir = TempDir::new("sig-tamper-field");
+    dir.write("stable.json", tampered.as_bytes());
+    // 签名还是**原始**那份的签名。
+    dir.write("stable.json.sig", signature_envelope(&original).as_bytes());
+    let error = verified_manifest(&DirSource::new(dir.path()), Channel::Stable)
+        .expect_err("改过字段的清单必须验不过");
+    assert_eq!(error.kind, UpdateErrorKind::SignatureInvalid);
+    assert!(
+        error.message.contains("sha256"),
+        "要说清「签名声明的是哪一份、手上是哪一份」（实际：{}）",
+        error.message
+    );
+}
+
+#[test]
+fn tampered_signature_only_is_rejected() {
+    // 守卫①的另一半：清单字节一个不动，只把签名的最后一个字节改掉。
+    let json = stable_json("0.3.0");
+    let mut signature = sign_bytes(TEST_SIGNING_SEED, json.as_bytes());
+    let good = signature_envelope(&json);
+    signature[63] ^= 0x04;
+    let broken =
+        signature_envelope_of(&[signature_entry_from_bytes(TEST_KEY_ID, &signature, &json)]);
+    assert_ne!(good, broken, "两份信封必须真的不同");
+
+    let dir = TempDir::new("sig-tamper-sig");
+    dir.write("stable.json", json.as_bytes());
+    dir.write("stable.json.sig", broken.as_bytes());
+    let error = verified_manifest(&DirSource::new(dir.path()), Channel::Stable)
+        .expect_err("只改签名也必须被拒");
+    assert_eq!(error.kind, UpdateErrorKind::SignatureInvalid);
+}
+
+#[test]
+fn missing_signature_is_rejected() {
+    let dir = TempDir::new("sig-missing");
+    dir.write("stable.json", stable_json("0.3.0").as_bytes());
+    let error = verified_manifest(&DirSource::new(dir.path()), Channel::Stable)
+        .expect_err("没有签名文件必须拒");
+    assert_eq!(error.kind, UpdateErrorKind::SignatureMissing);
+    assert!(!error.is_retryable(), "漏签名不是抖动，重试没有意义");
+    assert!(error.kind.is_signature(), "壳层据此换文案");
+}
+
+#[test]
+fn empty_signature_array_is_malformed() {
+    let dir = TempDir::new("sig-empty-array");
+    dir.write("stable.json", stable_json("0.3.0").as_bytes());
+    dir.write("stable.json.sig", br#"{"format":1,"signatures":[]}"#);
+    let error = verified_manifest(&DirSource::new(dir.path()), Channel::Stable)
+        .expect_err("空签名数组必须拒");
+    assert_eq!(error.kind, UpdateErrorKind::SignatureMalformed);
+}
+
+#[test]
+fn unknown_field_in_envelope_is_malformed() {
+    // `deny_unknown_fields`：发布侧拼错字段名要在 CI/发布侧当场炸，而不是变成用户机器上的「验签失败」。
+    let json = stable_json("0.3.0");
+    let dir = TempDir::new("sig-unknown-field");
+    dir.write("stable.json", json.as_bytes());
+    dir.write(
+        "stable.json.sig",
+        br#"{"format":1,"signatures":[],"comment":"hi"}"#,
+    );
+    let error = verified_manifest(&DirSource::new(dir.path()), Channel::Stable)
+        .expect_err("未知字段必须拒");
+    assert_eq!(error.kind, UpdateErrorKind::SignatureMalformed);
+}
+
+#[test]
+fn unknown_key_is_rejected() {
+    // 攻击者用自己那把钥签了一份**完全合法**的清单：字节没问题，只是钥不在钉住的表里。
+    let json = stable_json("9.9.9");
+    let dir = TempDir::new("sig-unknown-key");
+    dir.write("stable.json", json.as_bytes());
+    dir.write(
+        "stable.json.sig",
+        signature_envelope_with(ATTACKER_SEED, "attacker-key", &json).as_bytes(),
+    );
+    let error = verified_manifest(&DirSource::new(dir.path()), Channel::Stable)
+        .expect_err("不认识的钥必须拒");
+    assert_eq!(error.kind, UpdateErrorKind::SignatureUnknownKey);
+    assert!(
+        error.message.contains("attacker-key"),
+        "要说出是谁签的（实际：{}）",
+        error.message
+    );
+}
+
+#[test]
+fn key_id_spoofing_does_not_help() {
+    // 攻击者把自己那把钥的 key_id 伪造成钉住的那个：查表命中，但**公钥字节**对不上 ⇒ 仍拒。
+    // 这条就是「公钥钉在二进制里，不是按名字信任」的直接证据。
+    let json = stable_json("9.9.9");
+    let dir = TempDir::new("sig-key-id-spoof");
+    dir.write("stable.json", json.as_bytes());
+    dir.write(
+        "stable.json.sig",
+        signature_envelope_with(ATTACKER_SEED, TEST_KEY_ID, &json).as_bytes(),
+    );
+    let error = verified_manifest(&DirSource::new(dir.path()), Channel::Stable)
+        .expect_err("key_id 撞名不能替代公钥");
+    assert_eq!(error.kind, UpdateErrorKind::SignatureInvalid);
+}
+
+#[test]
+fn multi_signature_accepts_any_pinned_key() {
+    // 轮换窗口：一份清单同时带「钉住的旧钥」与「本构建不认识的新钥」的签名，只要有一条能过就放行。
+    let json = stable_json("0.3.0");
+    let dir = TempDir::new("sig-multi");
+    dir.write("stable.json", json.as_bytes());
+    let merged = signature_envelope_of(&[
+        signature_entry(ATTACKER_SEED, "someone-else", &json),
+        signature_entry(TEST_SIGNING_SEED, TEST_KEY_ID, &json),
+    ]);
+    dir.write("stable.json.sig", merged.as_bytes());
+    let manifest =
+        verified_manifest(&DirSource::new(dir.path()), Channel::Stable).expect("有一条能过就放行");
+    assert!(manifest.is_some());
+}
+
+#[test]
+fn unsigned_install_never_touches_the_target() {
+    // 顺序证据：验签在**取包之前**，因此目标 exe 与暂存目录一个字节都没动过。
+    let dir = TempDir::new("sig-apply-order");
+    dir.write("stable.json", stable_json("0.3.0").as_bytes());
+    dir.write("asset.bin", PAYLOAD);
+    let dest = dir.join("bin/unlucky-launcher.exe");
+    fs::create_dir_all(dest.parent().expect("父目录")).expect("建目录");
+    fs::write(&dest, b"old-bytes").expect("写旧 exe");
+
+    let job = Job::new(
+        Box::new(DirSource::new(dir.path())),
+        target(),
+        dir.join("staging"),
+        dest.clone(),
+    );
+    let error = job
+        .apply(¤t(), Channel::Stable)
+        .expect_err("没有签名不许 apply");
+    assert_eq!(error.kind, UpdateErrorKind::SignatureMissing);
+    assert_eq!(
+        fs::read(&dest).expect("目标仍在"),
+        b"old-bytes",
+        "目标 exe 不许被动过"
+    );
+    let staging_empty = match fs::read_dir(dir.join("staging")) {
+        Ok(mut entries) => entries.next().is_none(),
+        Err(_) => true,
+    };
+    assert!(staging_empty, "暂存目录不该留下任何东西（验签在取包之前）");
+}
+
+#[test]
+fn sha256_mismatch_is_reported_separately() {
+    // 两条判据互不替代：签名对（内容就是发布侧签的那份），但包体摘要对不上 ⇒ DigestMismatch。
+    let dir = TempDir::new("sig-vs-digest");
+    dir.write_signed("stable.json", &stable_json("0.3.0"));
+    // 等长但不同内容：先过长度判据，才走得到摘要判据（顺序在 verify.rs 里是有意的）。
+    dir.write("asset.bin", &[b'X'; PAYLOAD.len()]);
+    let job = Job::new(
+        Box::new(DirSource::new(dir.path())),
+        target(),
+        dir.join("staging"),
+        dir.join("bin/unlucky-launcher.exe"),
+    );
+    let error = job
+        .apply(¤t(), Channel::Stable)
+        .expect_err("摘要不符必须拒");
+    assert_eq!(error.kind, UpdateErrorKind::DigestMismatch);
+    assert!(!error.kind.is_signature(), "这是摘要判据，不是签名判据");
+}
+
+#[test]
+fn no_runtime_keyring_override() {
+    // 守卫②：信任锚是编译期常量。运行期旁边放一份「信任表」、或设环境变量，都不该有任何作用
+    // （现在压根没有这种口子；将来谁加了，这条会红）。
+    let json = stable_json("9.9.9");
+    let dir = TempDir::new("sig-no-override");
+    dir.write("stable.json", json.as_bytes());
+    dir.write(
+        "stable.json.sig",
+        signature_envelope_with(ATTACKER_SEED, "attacker-key", &json).as_bytes(),
+    );
+    let attacker_public = public_key_hex(ATTACKER_SEED);
+    dir.write(
+        "keyring.json",
+        format!(r#"{{"keys":[{{"key_id":"attacker-key","public_key_hex":"{attacker_public}"}}]}}"#)
+            .as_bytes(),
+    );
+    dir.write("attacker.pub", attacker_public.as_bytes());
+    let keyring_path = dir.join("keyring.json");
+    std::env::set_var("ULL_UPDATE_KEYRING", &keyring_path);
+    std::env::set_var("ULL_UPDATE_KEYRING_FILE", &keyring_path);
+    let outcome = verified_manifest(&DirSource::new(dir.path()), Channel::Stable);
+    std::env::remove_var("ULL_UPDATE_KEYRING");
+    std::env::remove_var("ULL_UPDATE_KEYRING_FILE");
+    let error = outcome.expect_err("旁边的信任表文件不许生效");
+    assert_eq!(
+        error.kind,
+        UpdateErrorKind::SignatureUnknownKey,
+        "改不了信任锚：攻击者的钥仍在表外（实际：{}）",
+        error.message
+    );
+}
diff --git a/crates/core/src/update/tests/source_cases.rs b/crates/core/src/update/tests/source_cases.rs
new file mode 100644
index 0000000..bacdd97
--- /dev/null
+++ b/crates/core/src/update/tests/source_cases.rs
@@ -0,0 +1,178 @@
+//! 本地目录源：清单缺失不是错误、渠道对不上要报错、远端地址一律拒绝。
+
+use std::fs;
+
+use crate::update::manifest::ReleaseManifest;
+use crate::update::{verified_manifest, Channel, DirSource, UpdateErrorKind, UpdateSource};
+
+use super::support::{artifact, manifest, release, TempDir};
+
+const PAYLOAD: &[u8] = b"source payload";
+
+fn publish(tmp: &TempDir, channel: Channel, json: &str) {
+    tmp.write_signed(&format!("{}.json", channel.as_str()), json);
+}
+
+#[test]
+fn missing_channel_manifest_is_not_an_error() {
+    let tmp = TempDir::new("source-missing");
+    let source = DirSource::new(tmp.path());
+    let manifest = verified_manifest(&source, Channel::Stable).expect("缺清单不该报错");
+    assert!(manifest.is_none(), "还没发过版 = Ok(None)");
+}
+
+#[test]
+fn reads_and_validates_the_channel_manifest() {
+    let tmp = TempDir::new("source-ok");
+    let json = manifest(
+        "stable",
+        &[release(
+            "0.3.0",
+            "",
+            &[artifact("win-x64", "portable-zip", "ull-test.zip", PAYLOAD)],
+        )],
+    );
+    publish(&tmp, Channel::Stable, &json);
+    let source = DirSource::new(tmp.path());
+    let parsed = verified_manifest(&source, Channel::Stable)
+        .expect("应取到清单")
+        .expect("清单存在");
+    assert_eq!(parsed.channel, Channel::Stable);
+    assert_eq!(parsed.releases.len(), 1);
+    assert!(source.source_id().starts_with("file:"));
+    assert_eq!(source.root(), tmp.path());
+    assert_eq!(source.manifest_path(Channel::Beta), tmp.join("beta.json"));
+}
+
+#[test]
+fn channel_mismatch_is_an_error() {
+    let tmp = TempDir::new("source-mismatch");
+    // 清单自称 beta，却躺在 stable.json 里
+    publish(&tmp, Channel::Stable, &manifest("beta", &[]));
+    let error = verified_manifest(&DirSource::new(tmp.path()), Channel::Stable)
+        .expect_err("渠道不符必须报错");
+    assert_eq!(error.kind, UpdateErrorKind::ChannelMismatch);
+}
+
+#[test]
+fn broken_manifest_json_is_reported_with_path() {
+    let tmp = TempDir::new("source-broken");
+    publish(&tmp, Channel::Stable, "{ not json");
+    let error = verified_manifest(&DirSource::new(tmp.path()), Channel::Stable)
+        .expect_err("坏 JSON 必须报错");
+    assert_eq!(error.kind, UpdateErrorKind::InvalidManifest);
+    assert!(
+        error.message.contains("来源 file:"),
+        "错误里要带出来源（本地源的 id 就是根目录），日志才定位得到（实际：{}）",
+        error.message
+    );
+}
+
+#[test]
+fn copies_artifact_from_a_relative_url() {
+    let tmp = TempDir::new("source-copy");
+    let file = tmp.write("dist/ull-test.zip", PAYLOAD);
+    let json = manifest(
+        "stable",
+        &[release(
+            "0.3.0",
+            "",
+            &[artifact(
+                "win-x64",
+                "portable-zip",
+                "dist/ull-test.zip",
+                PAYLOAD,
+            )],
+        )],
+    );
+    let parsed = ReleaseManifest::from_json(&json).expect("清单应可解析");
+    let dest = tmp.join("staging/copy.zip");
+    let written = DirSource::new(tmp.path())
+        .fetch_artifact(&parsed.releases[0].artifacts[0], &dest)
+        .expect("应复制成功");
+    assert_eq!(written, PAYLOAD.len() as u64);
+    assert_eq!(fs::read(&dest).expect("目标应存在"), PAYLOAD);
+    assert!(file.exists());
+    assert!(dest.parent().is_some_and(|parent| parent.exists()));
+}
+
+#[test]
+fn accepts_file_url_for_the_artifact() {
+    let tmp = TempDir::new("source-file-url");
+    let file = tmp.write("dist/ull-test.zip", PAYLOAD);
+    let url = format!("file://{}", file.display().to_string().replace('\\', "/"));
+    let json = manifest(
+        "stable",
+        &[release(
+            "0.3.0",
+            "",
+            &[artifact("win-x64", "portable-zip", &url, PAYLOAD)],
+        )],
+    );
+    let parsed = ReleaseManifest::from_json(&json).expect("清单应可解析");
+    let dest = tmp.join("staging/copy.zip");
+    DirSource::new(tmp.join("a-different-root"))
+        .fetch_artifact(&parsed.releases[0].artifacts[0], &dest)
+        .expect("file:// 地址应可复制");
+    assert_eq!(fs::read(&dest).expect("目标应存在"), PAYLOAD);
+}
+
+#[test]
+fn rejects_remote_urls() {
+    let tmp = TempDir::new("source-remote");
+    let json = manifest(
+        "stable",
+        &[release(
+            "0.3.0",
+            "",
+            &[artifact(
+                "win-x64",
+                "portable-zip",
+                "https://example.invalid/ull-test.zip",
+                PAYLOAD,
+            )],
+        )],
+    );
+    let parsed = ReleaseManifest::from_json(&json).expect("清单应可解析");
+    let error = DirSource::new(tmp.path())
+        .fetch_artifact(&parsed.releases[0].artifacts[0], &tmp.join("copy.zip"))
+        .expect_err("本地源不该假装能取远端字节");
+    assert_eq!(error.kind, UpdateErrorKind::UnsupportedSource);
+}
+
+#[test]
+fn missing_artifact_file_is_source_missing() {
+    let tmp = TempDir::new("source-no-file");
+    let json = manifest(
+        "stable",
+        &[release(
+            "0.3.0",
+            "",
+            &[artifact(
+                "win-x64",
+                "portable-zip",
+                "not-there.zip",
+                PAYLOAD,
+            )],
+        )],
+    );
+    let parsed = ReleaseManifest::from_json(&json).expect("清单应可解析");
+    let error = DirSource::new(tmp.path())
+        .fetch_artifact(&parsed.releases[0].artifacts[0], &tmp.join("copy.zip"))
+        .expect_err("产物不存在应报错");
+    assert_eq!(error.kind, UpdateErrorKind::SourceMissing);
+}
+
+#[test]
+fn builds_a_source_from_a_file_url() {
+    let tmp = TempDir::new("source-from-url");
+    let url = format!(
+        "file://{}",
+        tmp.path().display().to_string().replace('\\', "/")
+    );
+    let source = DirSource::from_url(&url).expect("file:// 应被接受");
+    assert_eq!(source.root(), tmp.path(), "根目录应与给定目录一致");
+
+    let error = DirSource::from_url("https://example.invalid/dist").expect_err("https 不是本地源");
+    assert_eq!(error.kind, UpdateErrorKind::UnsupportedSource);
+}
diff --git a/crates/core/src/update/tests/support.rs b/crates/core/src/update/tests/support.rs
new file mode 100644
index 0000000..c725912
--- /dev/null
+++ b/crates/core/src/update/tests/support.rs
@@ -0,0 +1,392 @@
+//! `update` 测试的公共夹具：临时目录、真实摘要、清单 JSON 片段。
+//!
+//! 清单片段里的摘要**按真实字节算**，不用占位值——「校验和不符」那条用例正是要证明
+//! 判据真的在跑，占位值会让它对所有输入都成立。
+
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+
+use crate::download::verify::digest_bytes;
+use crate::download::{
+    ContentCache, DownloadEngine, EngineConfig, HashAlgo, HealthRegistry, MirrorTable,
+    RegionProfile,
+};
+
+/// 一次性临时目录（`Drop` 时尽力删除；删不掉也留在系统 temp 下不碍事）。
+pub(crate) struct TempDir {
+    path: PathBuf,
+}
+
+impl TempDir {
+    pub(crate) fn new(tag: &str) -> Self {
+        static COUNTER: AtomicU64 = AtomicU64::new(0);
+        let unique = COUNTER.fetch_add(1, Ordering::Relaxed);
+        let path =
+            std::env::temp_dir().join(format!("ull-update-{}-{tag}-{unique}", std::process::id()));
+        let _ = fs::remove_dir_all(&path);
+        fs::create_dir_all(&path).expect("建临时目录");
+        Self { path }
+    }
+
+    pub(crate) fn path(&self) -> &Path {
+        &self.path
+    }
+
+    pub(crate) fn join(&self, name: &str) -> PathBuf {
+        self.path.join(name)
+    }
+
+    /// 写一个文件（父目录自动建），返回路径。
+    pub(crate) fn write(&self, name: &str, bytes: &[u8]) -> PathBuf {
+        let path = self.join(name);
+        if let Some(parent) = path.parent() {
+            fs::create_dir_all(parent).expect("建父目录");
+        }
+        fs::write(&path, bytes).expect("写文件");
+        path
+    }
+}
+
+impl Drop for TempDir {
+    fn drop(&mut self) {
+        let _ = fs::remove_dir_all(&self.path);
+    }
+}
+
+/// 目录里的文件名（读不到就当空；排序过，断言可写死）。
+pub(crate) fn names_in(dir: &Path) -> Vec {
+    match fs::read_dir(dir) {
+        Ok(entries) => {
+            let mut names = entries
+                .filter_map(Result::ok)
+                .map(|entry| entry.file_name().to_string_lossy().into_owned())
+                .collect::>();
+            names.sort();
+            names
+        }
+        Err(_) => Vec::new(),
+    }
+}
+
+/// 指定异卷根目录的环境变量（跨卷夹具找不到别的卷时，用它显式指一块）。
+pub(crate) const XDEV_ROOT_ENV: &str = "ULL_XDEV_TEST_ROOT";
+
+/// 「我知道本机没有第二块卷」的**显式豁免**：值必须是 `1`（`true`/`yes` 不算，手误不该放行）。
+///
+/// 没有它、又探不到第二块卷 ⇒ 跨卷守卫**当场红**（见 `install_xdev_cases::xdev_guard`）。
+/// 它不会让真跨卷用例变假绿：探到了第二块卷照样真跑（豁免只在探测失败时被咨询）。
+pub(crate) const XDEV_WAIVE_ENV: &str = "ULL_XDEV_TEST_WAIVE";
+
+/// 「本机/本作业**必须**有第二块卷」的显式声明：值必须是 `1`（与豁免同给时以它为准，不许自相矛盾）。
+pub(crate) const XDEV_REQUIRE_ENV: &str = "ULL_XDEV_TEST_REQUIRE";
+
+/// 一块**与会话临时目录不同卷**的可写目录：跨卷替换用例的现场。
+///
+/// 「不同卷」不是按平台猜的，是**探测**出来的：往候选目录 rename 一个探针文件，只有真的报
+/// `CrossesDevices`（Unix `EXDEV` / Windows `ERROR_NOT_SAME_DEVICE`）才认这块地——否则
+/// 用例会在同一卷上跑，等于什么都没验。
+///
+/// 候选顺序：`ULL_XDEV_TEST_ROOT` → 各盘符（Windows：`<盘>:\Temp`，没有就盘根）/
+/// `TMPDIR`、`/dev/shm`、`/run/user/`、`/tmp`（Unix）。
+///
+/// 探不到时**怎么处置不是这里决定的**：本函数只回答「有没有」，跳过/失败由
+/// `install_xdev_cases::xdev_guard` 裁决（跳过必须是响的）。
+pub(crate) struct XdevRoot {
+    path: PathBuf,
+}
+
+impl XdevRoot {
+    /// 探一块异卷目录；探不到返回 `None`（是否允许跳过由 `xdev_guard` 定）。
+    pub(crate) fn probe(tag: &str) -> Option {
+        let mut candidates = Vec::new();
+        if let Some(root) = std::env::var_os(XDEV_ROOT_ENV) {
+            candidates.push(PathBuf::from(root));
+        }
+        candidates.extend(volume_candidates());
+        candidates.into_iter().find_map(|candidate| {
+            let path = candidate.join(format!("ull-xdev-{}-{tag}", std::process::id()));
+            if !is_other_volume(&candidate) || fs::create_dir_all(&path).is_err() {
+                return None;
+            }
+            Some(Self { path })
+        })
+    }
+
+    /// 现场根目录。
+    pub(crate) fn path(&self) -> &Path {
+        &self.path
+    }
+
+    /// 现场根目录下的子目录（自动建）。
+    pub(crate) fn dir(&self, name: &str) -> PathBuf {
+        let path = self.path.join(name);
+        fs::create_dir_all(&path).expect("建异卷子目录");
+        path
+    }
+}
+
+impl Drop for XdevRoot {
+    fn drop(&mut self) {
+        let _ = fs::remove_dir_all(&self.path);
+    }
+}
+
+/// 可能的异卷候选根（只是候选，能不能用由 [`is_other_volume`] 定）。
+fn volume_candidates() -> Vec {
+    #[cfg(windows)]
+    {
+        ('A'..='Z')
+            .map(|letter| format!("{letter}:/"))
+            .map(PathBuf::from)
+            .filter(|root| root.join("Temp").is_dir() || root.is_dir())
+            .map(|root| {
+                if root.join("Temp").is_dir() {
+                    root.join("Temp")
+                } else {
+                    root
+                }
+            })
+            .collect()
+    }
+    #[cfg(not(windows))]
+    {
+        let mut candidates = Vec::new();
+        for key in ["TMPDIR", "TMP", "TEMP"] {
+            if let Some(value) = std::env::var_os(key) {
+                candidates.push(PathBuf::from(value));
+            }
+        }
+        for root in ["/dev/shm", "/tmp", "/var/tmp"] {
+            candidates.push(PathBuf::from(root));
+        }
+        if let Some(uid) = std::env::var_os("UID") {
+            candidates.push(PathBuf::from("/run/user").join(uid));
+        }
+        candidates
+    }
+}
+
+/// 这块目录与 [`std::env::temp_dir`] 是否**真的**不同卷（拿一次真实的 rename 试出来）。
+fn is_other_volume(dir: &Path) -> bool {
+    if dir.as_os_str().is_empty() || fs::create_dir_all(dir).is_err() {
+        return false;
+    }
+    let probe = std::env::temp_dir().join(format!("ull-xdev-probe-{}", std::process::id()));
+    if fs::write(&probe, b"probe").is_err() {
+        return false;
+    }
+    let landed = dir.join(format!("ull-xdev-probe-{}", std::process::id()));
+    let cross = matches!(fs::rename(&probe, &landed), Err(ref error) if error.kind() == std::io::ErrorKind::CrossesDevices);
+    let _ = fs::remove_file(&probe);
+    let _ = fs::remove_file(&landed);
+    cross
+}
+
+/// 小写十六进制 SHA-256。
+pub(crate) fn sha256(bytes: &[u8]) -> String {
+    digest_bytes(HashAlgo::Sha256, bytes)
+}
+
+/// 清单里的一个产物对象（`sha256` 与 `size` 都按 `payload` 真实值算）。
+pub(crate) fn artifact(target: &str, format: &str, url: &str, payload: &[u8]) -> String {
+    format!(
+        r#"{{"target":"{target}","format":"{format}","url":"{url}","size":{},"sha256":"{}"}}"#,
+        payload.len(),
+        sha256(payload)
+    )
+}
+
+/// 清单里的一个发布对象；`extra` 追加其它字段（如 `,"force":true`），注意前导逗号。
+pub(crate) fn release(version: &str, extra: &str, artifacts: &[String]) -> String {
+    format!(
+        r#"{{"version":"{version}"{extra},"artifacts":[{}]}}"#,
+        artifacts.join(",")
+    )
+}
+
+/// 一份渠道清单。
+pub(crate) fn manifest(channel: &str, releases: &[String]) -> String {
+    format!(
+        r#"{{"channel":"{channel}","releases":[{}]}}"#,
+        releases.join(",")
+    )
+}
+
+/// 造一台测试用下载引擎：镜像表用内置清单，健康度只在内存里，缓存落临时目录。
+///
+/// `region` 决定「官方优先」还是「镜像优先」——gh-proxy 前缀只在该是后一种时生效。
+pub(crate) fn engine_for(tmp: &TempDir, region: RegionProfile) -> std::sync::Arc {
+    std::sync::Arc::new(DownloadEngine::new(
+        EngineConfig {
+            // 失败用例不必等三次退避。
+            max_attempts_per_source: 1,
+            ..EngineConfig::default()
+        },
+        std::sync::Arc::new(MirrorTable::builtin()),
+        std::sync::Arc::new(region),
+        std::sync::Arc::new(HealthRegistry::in_memory()),
+        std::sync::Arc::new(ContentCache::open(tmp.join("cache"))),
+    ))
+}
+
+/// 假服务的一条路由应答。
+#[derive(Debug, Clone)]
+pub(crate) struct FakeResponse {
+    pub(crate) status: u16,
+    pub(crate) content_type: &'static str,
+    pub(crate) body: Vec,
+}
+
+impl FakeResponse {
+    /// 200 + JSON 体。
+    pub(crate) fn json(body: &str) -> Self {
+        Self {
+            status: 200,
+            content_type: "application/json",
+            body: body.as_bytes().to_vec(),
+        }
+    }
+
+    /// 200 + 二进制体（模拟 release 里的产物）。
+    pub(crate) fn bin(body: &[u8]) -> Self {
+        Self {
+            status: 200,
+            content_type: "application/octet-stream",
+            body: body.to_vec(),
+        }
+    }
+
+    /// 固定状态码 + 空体（404 / 500 用）。
+    pub(crate) fn status(status: u16) -> Self {
+        Self {
+            status,
+            content_type: "text/plain",
+            body: Vec::new(),
+        }
+    }
+}
+
+/// 进程内极简 HTTP/1.1 假服务：按**完整请求路径**查表应答，未命中的路径一律 404。
+///
+/// 用它而不是 httpmock：项目里下载测试就是这么干的（零额外依赖），而且能把
+/// 「请求真的发到了哪个 URL」记下来给断言用。
+pub(crate) struct FakeHttp {
+    addr: std::net::SocketAddr,
+    hits: std::sync::Arc>>,
+    stop: std::sync::Arc,
+    handle: Option>,
+}
+
+impl FakeHttp {
+    /// 起服务（`routes` 是「路径 → 应答」表）。
+    pub(crate) fn start(routes: Vec<(String, FakeResponse)>) -> Self {
+        let listener = std::net::TcpListener::bind(("127.0.0.1", 0)).expect("绑定本地端口");
+        let addr = listener.local_addr().expect("取本地地址");
+        let hits = std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));
+        let stop = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
+
+        let worker_hits = std::sync::Arc::clone(&hits);
+        let worker_stop = std::sync::Arc::clone(&stop);
+        let handle = std::thread::spawn(move || {
+            for stream in listener.incoming() {
+                if worker_stop.load(std::sync::atomic::Ordering::SeqCst) {
+                    break;
+                }
+                let Ok(mut stream) = stream else { break };
+                let Some(path) = read_request_path(&mut stream) else {
+                    continue;
+                };
+                worker_hits
+                    .lock()
+                    .unwrap_or_else(|poisoned| poisoned.into_inner())
+                    .push(path.clone());
+                let response = routes.iter().find(|(route, _)| route == &path).map_or_else(
+                    || FakeResponse::status(404),
+                    |(_, response)| response.clone(),
+                );
+                let _ = write_response(&mut stream, &response);
+            }
+        });
+
+        Self {
+            addr,
+            hits,
+            stop,
+            handle: Some(handle),
+        }
+    }
+
+    /// 站点根地址（可直接喂给 `GitHubReleaseSource::with_base`）。
+    pub(crate) fn base(&self) -> String {
+        format!("http://{}", self.addr)
+    }
+
+    /// 已经收到的请求路径（按到达顺序）。
+    pub(crate) fn hits(&self) -> Vec {
+        self.hits
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner())
+            .clone()
+    }
+}
+
+impl Drop for FakeHttp {
+    fn drop(&mut self) {
+        self.stop.store(true, std::sync::atomic::Ordering::SeqCst);
+        // 自己连一下唤醒阻塞中的 accept，否则 join 会一直等。
+        let _ = std::net::TcpStream::connect(self.addr);
+        if let Some(handle) = self.handle.take() {
+            let _ = handle.join();
+        }
+    }
+}
+
+/// 读一个请求的路径（只读头部，够用）。
+fn read_request_path(stream: &mut std::net::TcpStream) -> Option {
+    use std::io::Read;
+    let mut buffer = Vec::new();
+    let mut chunk = [0_u8; 1024];
+    loop {
+        let read = stream.read(&mut chunk).ok()?;
+        if read == 0 {
+            break;
+        }
+        buffer.extend_from_slice(&chunk[..read]);
+        if buffer.windows(4).any(|window| window == b"\r\n\r\n") {
+            break;
+        }
+    }
+    let head = String::from_utf8_lossy(&buffer).to_string();
+    head.lines()
+        .next()?
+        .split_whitespace()
+        .nth(1)
+        .map(str::to_string)
+}
+
+fn write_response(
+    stream: &mut std::net::TcpStream,
+    response: &FakeResponse,
+) -> std::io::Result<()> {
+    use std::io::Write;
+    let head = format!(
+        "HTTP/1.1 {} {}\r\nContent-Type: {}\r\nContent-Length: {}\r\nConnection: close\r\n\r\n",
+        response.status,
+        reason(response.status),
+        response.content_type,
+        response.body.len()
+    );
+    stream.write_all(head.as_bytes())?;
+    stream.write_all(&response.body)?;
+    stream.flush()
+}
+
+fn reason(status: u16) -> &'static str {
+    match status {
+        200 => "OK",
+        404 => "Not Found",
+        500 => "Internal Server Error",
+        _ => "Status",
+    }
+}
diff --git a/crates/core/src/update/tests/support_sign.rs b/crates/core/src/update/tests/support_sign.rs
new file mode 100644
index 0000000..d98a8b5
--- /dev/null
+++ b/crates/core/src/update/tests/support_sign.rs
@@ -0,0 +1,94 @@
+//! 清单签名的**测试夹具**：用测试钥签出 `manifest.json.sig` 的信封（M190）。
+//!
+//! 为什么单独一个文件：`support.rs` 是 update 测试的通用夹具（临时目录、假 HTTP、清单片段），
+//! 已经贴着 400 行红线；签名这一摊只被 `signature_cases` / `github_cases` 用到，搬出来两清。
+//!
+//! 签名走 `ed25519-dalek` 的 `SigningKey`（与仓里验签用的 `verify_strict` 同一棵树），而**不是**
+//! 自写实现——M190 r1 复审把自写曲线算术整体删掉了，这里也不留第二条算法。测试钥的种子是公开的
+//! （见下），它只对 `cfg(test)` / `update-test-source` / `update-test-key` 三档构建有意义。
+
+use super::support::TempDir;
+
+/// 测试签名钥的 32 字节种子。
+///
+/// **它是公开的，故意不保密**：它只对 `cfg(test)` / `update-test-source` / `update-test-key` 三档
+/// 构建有意义（`trust::TEST_ONLY` 才认这把钥），正式构建的信任表里没有它，所以拿它签不出任何正式
+/// 版本能装的清单。正式私钥只能来自仓库 Secret（见 `packaging/docs/signing.md`）。
+pub(crate) const TEST_SIGNING_SEED: &[u8; 32] = b"ull-m190-test-key-seed-000000001";
+
+/// 测试钥的 `key_id`（与 `trust::TEST_ONLY` 里那条一致）。
+pub(crate) const TEST_KEY_ID: &str = "test-only-key";
+
+/// 字节转小写十六进制。
+pub(crate) fn hex_of(bytes: &[u8]) -> String {
+    bytes.iter().map(|byte| format!("{byte:02x}")).collect()
+}
+
+/// 用测试钥签一份清单，返回 `manifest.json.sig` 的信封原文。
+pub(crate) fn signature_envelope(manifest_text: &str) -> String {
+    signature_envelope_with(TEST_SIGNING_SEED, TEST_KEY_ID, manifest_text)
+}
+
+/// 用指定种子/`key_id` 签一份清单（负向用例要造「不认识的钥」「改过内容的签名」）。
+pub(crate) fn signature_envelope_with(
+    seed: &[u8; 32],
+    key_id: &str,
+    manifest_text: &str,
+) -> String {
+    signature_envelope_of(&[signature_entry(seed, key_id, manifest_text)])
+}
+
+/// 多签名信封（轮换窗口的夹具：一份清单同时带几把钥的签名）。
+pub(crate) fn signature_envelope_of(entries: &[String]) -> String {
+    format!(r#"{{"format":1,"signatures":[{}]}}"#, entries.join(","))
+}
+
+/// 一条签名条目（可以被 [`signature_envelope_of`] 拼起来，也可以单独改坏再拼）。
+pub(crate) fn signature_entry(seed: &[u8; 32], key_id: &str, manifest_text: &str) -> String {
+    signature_entry_from_bytes(
+        key_id,
+        &sign_bytes(seed, manifest_text.as_bytes()),
+        manifest_text,
+    )
+}
+
+/// 用**现成的签名字节**拼一条条目（「只改签名字节」的用例靠它）。
+pub(crate) fn signature_entry_from_bytes(
+    key_id: &str,
+    signature: &[u8; 64],
+    manifest_text: &str,
+) -> String {
+    let sha = crate::update::signature::hex_sha256(manifest_text.as_bytes());
+    format!(
+        r#"{{"alg":"ed25519","key_id":"{key_id}","sig":"{}","manifest_sha256":"{sha}"}}"#,
+        hex_of(signature)
+    )
+}
+
+/// 用 32 字节种子签一段字节（dalek 的 `SigningKey`；测试专用，正式构建里没有签名代码）。
+pub(crate) fn sign_bytes(seed: &[u8; 32], message: &[u8]) -> [u8; 64] {
+    use ed25519_dalek::{Signer, SigningKey};
+    let key = SigningKey::from_bytes(seed);
+    key.sign(message).to_bytes()
+}
+
+/// 种子对应的公钥（用来让「钉住的公钥」与「签名的钥」对得上——漂了就当场红）。
+pub(crate) fn public_key_hex(seed: &[u8; 32]) -> String {
+    use ed25519_dalek::SigningKey;
+    hex_of(SigningKey::from_bytes(seed).verifying_key().as_bytes())
+}
+
+impl TempDir {
+    /// 写一份清单**连它的签名**（`` + `.sig`），返回清单路径。
+    ///
+    /// M190 起「有清单没签名」是被拒的一档，所以夹具一律成对落盘：只写清单的用例都是为了
+    /// 证明「缺签名会被拒」，它们自己显式 `write` 清单即可。
+    pub(crate) fn write_signed(&self, name: &str, manifest_text: &str) -> std::path::PathBuf {
+        let path = self.write(name, manifest_text.as_bytes());
+        self.write(
+            &format!("{name}.sig"),
+            signature_envelope(manifest_text).as_bytes(),
+        );
+        path
+    }
+}
diff --git a/crates/core/src/update/tests/target_cases.rs b/crates/core/src/update/tests/target_cases.rs
new file mode 100644
index 0000000..a178e10
--- /dev/null
+++ b/crates/core/src/update/tests/target_cases.rs
@@ -0,0 +1,91 @@
+//! 目标平台与包形态的清单写法解析。
+
+use crate::platform::os_info::OsFamily;
+use crate::update::{Arch, PackageFormat, Target};
+
+#[test]
+fn parses_canonical_targets() {
+    assert_eq!(
+        Target::parse("win-x64"),
+        Some(Target::new(OsFamily::Windows, Arch::X64))
+    );
+    assert_eq!(
+        Target::parse("mac-arm64"),
+        Some(Target::new(OsFamily::MacOs, Arch::Arm64))
+    );
+    assert_eq!(
+        Target::parse("linux-x64"),
+        Some(Target::new(OsFamily::Linux, Arch::X64))
+    );
+    assert_eq!(
+        Target::parse("linux-arm64"),
+        Some(Target::new(OsFamily::Linux, Arch::Arm64))
+    );
+}
+
+#[test]
+fn tolerates_common_aliases() {
+    assert_eq!(
+        Target::parse("windows-amd64"),
+        Some(Target::new(OsFamily::Windows, Arch::X64))
+    );
+    assert_eq!(
+        Target::parse("osx-aarch64"),
+        Some(Target::new(OsFamily::MacOs, Arch::Arm64))
+    );
+    assert_eq!(
+        Target::parse("darwin-universal"),
+        None,
+        "认不出的架构必须返回 None，不能瞎猜"
+    );
+    assert_eq!(Target::parse("win"), None, "少了架构段");
+    assert_eq!(Target::parse("solaris-x64"), None);
+    assert_eq!(Target::parse(""), None);
+}
+
+#[test]
+fn current_target_renders_and_round_trips() {
+    let current = Target::current();
+    assert_eq!(Target::parse(current.as_str()), Some(current));
+    assert_eq!(current.to_string(), current.as_str());
+    assert_ne!(current.arch, Arch::Unknown, "编译目标架构应能识别");
+}
+
+#[test]
+fn parses_package_formats() {
+    assert_eq!(PackageFormat::parse("msi"), Some(PackageFormat::Msi));
+    assert_eq!(PackageFormat::parse("DMG"), Some(PackageFormat::Dmg));
+    assert_eq!(
+        PackageFormat::parse("appimage"),
+        Some(PackageFormat::AppImage)
+    );
+    assert_eq!(
+        PackageFormat::parse("portable-zip"),
+        Some(PackageFormat::PortableZip)
+    );
+    assert_eq!(
+        PackageFormat::parse("zip"),
+        Some(PackageFormat::PortableZip)
+    );
+    assert_eq!(PackageFormat::parse("tar.gz"), None);
+    assert_eq!(PackageFormat::Msi.to_string(), "msi");
+}
+
+#[test]
+fn installer_formats_are_flagged() {
+    for format in [
+        PackageFormat::Msi,
+        PackageFormat::Dmg,
+        PackageFormat::Deb,
+        PackageFormat::Rpm,
+    ] {
+        assert!(format.needs_installer(), "{format}");
+    }
+    for format in [
+        PackageFormat::PortableZip,
+        PackageFormat::PortableExe,
+        PackageFormat::AppImage,
+    ] {
+        assert!(!format.needs_installer(), "{format}");
+    }
+}
diff --git a/crates/core/src/update/tests/verify_cases.rs b/crates/core/src/update/tests/verify_cases.rs
new file mode 100644
index 0000000..4236787
--- /dev/null
+++ b/crates/core/src/update/tests/verify_cases.rs
@@ -0,0 +1,138 @@
+//! 校验层：摘要不符、包体截断都必须被挡下，且暂存文件不许留下。
+
+use std::fs;
+use std::path::Path;
+
+use crate::update::manifest::ReleaseManifest;
+use crate::update::{stage, DirSource, UpdateErrorKind};
+
+use super::support::{artifact, manifest, release, sha256, TempDir};
+
+/// 暂存目录里的文件名（断言「失败后没留垃圾」用）。
+fn staging_files(dir: &Path) -> Vec {
+    match fs::read_dir(dir) {
+        Ok(entries) => entries
+            .filter_map(|entry| entry.ok())
+            .map(|entry| entry.file_name().to_string_lossy().into_owned())
+            .collect(),
+        Err(_) => Vec::new(),
+    }
+}
+
+fn artifact_of(json: &str) -> crate::update::Artifact {
+    ReleaseManifest::from_json(json)
+        .expect("清单应可解析")
+        .releases[0]
+        .artifacts[0]
+        .clone()
+}
+
+#[test]
+fn digest_mismatch_is_rejected_and_staged_file_removed() {
+    let tmp = TempDir::new("verify-digest");
+    let source = DirSource::new(tmp.path());
+    // 清单声明的摘要按 A 算，实际发的是 B：长度一样，只有摘要能抓住。
+    let declared = b"payload-aaaa";
+    let delivered = b"payload-bbbb";
+    assert_eq!(declared.len(), delivered.len());
+    tmp.write("ull-test.zip", delivered);
+    let json = manifest(
+        "stable",
+        &[release(
+            "0.3.0",
+            "",
+            &[artifact(
+                "win-x64",
+                "portable-zip",
+                "ull-test.zip",
+                declared,
+            )],
+        )],
+    );
+    let artifact = artifact_of(&json);
+    assert_eq!(artifact.integrity.hex, sha256(declared));
+
+    let staging = tmp.join("staging");
+    let error = stage(&source, &artifact, &staging).expect_err("摘要不符必须拒绝");
+    assert_eq!(error.kind, UpdateErrorKind::DigestMismatch);
+    assert!(
+        error
+            .path
+            .as_ref()
+            .is_some_and(|path| path.starts_with(&staging)),
+        "错误应指向暂存文件：{error}"
+    );
+    assert!(
+        staging_files(&staging).is_empty(),
+        "校验失败的暂存文件必须被删掉，实际：{:?}",
+        staging_files(&staging)
+    );
+}
+
+#[test]
+fn truncated_payload_is_rejected_as_size_mismatch() {
+    let tmp = TempDir::new("verify-truncated");
+    let source = DirSource::new(tmp.path());
+    let full = b"a full portable zip payload";
+    // 发布侧发一半就断了：长度先抓到，不用读摘要就能拒绝。
+    tmp.write("ull-test.zip", &full[..8]);
+    let json = manifest(
+        "stable",
+        &[release(
+            "0.3.0",
+            "",
+            &[artifact("win-x64", "portable-zip", "ull-test.zip", full)],
+        )],
+    );
+    let staging = tmp.join("staging");
+    let error = stage(&source, &artifact_of(&json), &staging).expect_err("截断的包必须拒绝");
+    assert_eq!(error.kind, UpdateErrorKind::SizeMismatch);
+    assert!(error.to_string().contains("截断"));
+    assert!(staging_files(&staging).is_empty());
+}
+
+#[test]
+fn oversized_payload_is_rejected_too() {
+    let tmp = TempDir::new("verify-oversized");
+    let source = DirSource::new(tmp.path());
+    tmp.write("ull-test.zip", b"payload and then some");
+    let json = manifest(
+        "stable",
+        &[release(
+            "0.3.0",
+            "",
+            &[artifact(
+                "win-x64",
+                "portable-zip",
+                "ull-test.zip",
+                b"payload",
+            )],
+        )],
+    );
+    let error = stage(&source, &artifact_of(&json), &tmp.join("staging"))
+        .expect_err("多出来的字节同样不许装");
+    assert_eq!(error.kind, UpdateErrorKind::SizeMismatch);
+}
+
+#[test]
+fn matching_payload_is_staged_and_cleaned_on_drop() {
+    let tmp = TempDir::new("verify-ok");
+    let source = DirSource::new(tmp.path());
+    let payload = b"a real payload, short but real";
+    tmp.write("ull-test.zip", payload);
+    let json = manifest(
+        "stable",
+        &[release(
+            "0.3.0",
+            "",
+            &[artifact("win-x64", "portable-zip", "ull-test.zip", payload)],
+        )],
+    );
+    let staged = stage(&source, &artifact_of(&json), &tmp.join("staging")).expect("校验应通过");
+    assert_eq!(staged.size(), payload.len() as u64);
+    assert_eq!(fs::read(staged.path()).expect("暂存文件应存在"), payload);
+    assert_eq!(staged.integrity().hex, sha256(payload));
+    let path = staged.path().to_path_buf();
+    drop(staged);
+    assert!(!path.exists(), "StagedPackage 落地后应自行清理");
+}
diff --git a/crates/core/src/update/tests/version_cases.rs b/crates/core/src/update/tests/version_cases.rs
new file mode 100644
index 0000000..4234931
--- /dev/null
+++ b/crates/core/src/update/tests/version_cases.rs
@@ -0,0 +1,135 @@
+//! 版本比较的边界用例：数值比而非字典序、预发布 vs 正式、构建元数据不参与排序。
+
+use std::cmp::Ordering;
+
+use crate::update::{Stage, Version};
+
+fn version(text: &str) -> Version {
+    Version::parse(text).expect("测试里的版本号应可解析")
+}
+
+#[test]
+fn minor_numbers_compare_numerically() {
+    // 字典序会把 "0.9.0" 判成比 "0.10.0" 新，这正是这条用例要钉死的行为。
+    assert!(version("0.10.0") > version("0.9.0"));
+    assert!(version("0.10.1") < version("0.11.0"));
+    assert!(version("1.0.0") > version("0.999.999"));
+    assert!(version("2.0.0") > version("1.99.99"));
+}
+
+#[test]
+fn prerelease_sorts_below_the_release() {
+    assert!(version("1.0.0-rc.1") < version("1.0.0"));
+    assert!(version("1.0.0-alpha") < version("1.0.0"));
+    // 预发布阶段之间：alpha < beta < rc（ASCII 序，不是特例表）
+    assert!(version("1.0.0-alpha") < version("1.0.0-beta"));
+    assert!(version("1.0.0-beta.2") < version("1.0.0-rc.1"));
+    // 主次修订号优先于预发布标识
+    assert!(version("1.0.1-alpha.1") > version("1.0.0"));
+}
+
+#[test]
+fn prerelease_identifiers_follow_semver_rules() {
+    assert!(version("1.0.0-alpha.1") < version("1.0.0-alpha.2"));
+    assert!(version("1.0.0-alpha.2") < version("1.0.0-alpha.10"));
+    assert!(version("1.0.0-alpha") < version("1.0.0-alpha.1"));
+    // 纯数字段小于任何非数字段
+    assert!(version("1.0.0-1") < version("1.0.0-alpha"));
+    // 非数字段按 ASCII 比
+    assert!(version("1.0.0-alpha-1") < version("1.0.0-alpha-x"));
+}
+
+#[test]
+fn build_metadata_is_ignored_by_ordering_and_equality() {
+    let with = version("1.2.3+build.7");
+    let without = version("1.2.3");
+    assert_eq!(with.cmp(&without), Ordering::Equal);
+    assert_eq!(with, without);
+    assert!(version("1.2.4+zzz") > version("1.2.3+aaa"));
+    assert_eq!(with.to_string(), "1.2.3+build.7");
+    assert_eq!(with.build_metadata(), Some("build.7"));
+    assert_eq!(without.build_metadata(), None);
+}
+
+#[test]
+fn stages_are_recognised_from_the_first_identifier() {
+    assert_eq!(version("1.0.0").stage(), Stage::Stable);
+    assert_eq!(version("1.0.0-alpha.3").stage(), Stage::Alpha);
+    assert_eq!(version("1.0.0-a.2").stage(), Stage::Alpha);
+    assert_eq!(version("1.0.0-beta.1").stage(), Stage::Beta);
+    assert_eq!(version("1.0.0-rc.4").stage(), Stage::ReleaseCandidate);
+    assert_eq!(version("1.0.0-preview.2").stage(), Stage::ReleaseCandidate);
+    assert_eq!(version("1.0.0-spike-1").stage(), Stage::Unknown);
+    assert_eq!(version("1.0.0-7").stage(), Stage::Unknown);
+}
+
+#[test]
+fn round_trips_through_display() {
+    for text in [
+        "0.2.1",
+        "1.0.0-alpha.1",
+        "3.17.0+build-9",
+        "10.0.12-rc.2+ci.9",
+    ] {
+        let parsed = version(text);
+        let rendered = parsed.to_string();
+        assert_eq!(version(&rendered), parsed, "{text} 回读不一致");
+    }
+}
+
+#[test]
+fn accepts_v_prefix_and_reports_prerelease() {
+    assert_eq!(version("v1.4.2"), version("1.4.2"));
+    assert_eq!(version("V1.4.2"), version("1.4.2"));
+    assert!(!version("1.4.2").is_prerelease());
+    assert!(version("1.4.2-rc.1").is_prerelease());
+    assert_eq!(version("1.4.2-rc.1").prerelease().as_deref(), Some("rc.1"));
+    assert_eq!(version("1.4.2").prerelease(), None);
+    assert_eq!(
+        (
+            version("1.4.2").major(),
+            version("1.4.2").minor(),
+            version("1.4.2").patch()
+        ),
+        (1, 4, 2)
+    );
+}
+
+#[test]
+fn rejects_non_semver_input() {
+    for text in [
+        "",
+        "1",
+        "1.2",
+        "1.2.3.4",
+        "01.2.3",
+        "1.02.3",
+        "1.2.03",
+        "1.2.3-",
+        "1.2.3-alpha..1",
+        "1.2.3+",
+        "1.2.3-é",
+        "1.-2.3",
+        "1.2.x",
+        "1.2.3-01",
+    ] {
+        assert!(
+            Version::parse(text).is_err(),
+            "`{text}` 不该被当成合法版本号"
+        );
+    }
+}
+
+#[test]
+fn version_error_carries_input_and_reason() {
+    let error = Version::parse("1.2.x").expect_err("应失败");
+    assert_eq!(error.input(), "1.2.x");
+    assert!(!error.reason().is_empty());
+    assert!(error.to_string().contains("1.2.x"));
+}
+
+#[test]
+fn new_builds_a_plain_release() {
+    assert_eq!(Version::new(0, 2, 1), version("0.2.1"));
+    assert!(!Version::new(0, 2, 1).is_prerelease());
+}
diff --git a/crates/core/src/update/trust.rs b/crates/core/src/update/trust.rs
new file mode 100644
index 0000000..94f26f7
--- /dev/null
+++ b/crates/core/src/update/trust.rs
@@ -0,0 +1,151 @@
+//! 钉进二进制的清单签名信任锚（keyring）：**多把**公钥，`key_id` 只是查表用的标签。
+//!
+//! # 为什么是一张编译期常量表
+//!
+//! 自更新的信任根必须不可被「用户机器上的一枚文件」替换：清单与签名都能被能改 Release 的人一起
+//! 换掉，唯一挡得住的是「客户端**编进二进制**的那几把公钥」。所以这张表是 `const`：
+//!
+//! * 改仓库里的本文件只会改变**下一次构建**的行为，不会改变任何**已发布二进制**的验签结果；
+//! * 没有环境变量、没有设置键、没有「旁边的 keyring.json」这类运行期覆盖口子
+//!   （`tests/signature_cases.rs::no_runtime_keyring_override` 守这条）。
+//!
+//! # 为什么是「一组」而不是「一把」
+//!
+//! 换签名方（例如日后接 SignPath 的托管签名，或旧钥泄露后轮换）时，用户机器上装着的是**旧**二进制，
+//! 它只认旧钥。做成数组才有两条路同时成立：新签出的清单可以同时带新旧两把钥的签名（旧二进制认旧的、
+//! 新二进制认新的），以及新二进制可以一把一把地收紧。步骤见 `packaging/docs/signing.md`。
+//!
+//! # 唯一的加钥匙纪律：**旧钥签新钥**
+//!
+//! 往本表里加一把公钥，必须同时有「旧钥对新钥的背书」——即那次发布的清单同时带旧钥签名（见上），
+//! 以及 changelog 里点名新钥的 `key_id` 与指纹。**不允许**在没有旧钥签名的情况下替换这张表：
+//! 那等于让「能改仓库的人」变成「能改信任根的人」。
+//!
+//! # 正式构建的表当前是**空的**（fail-closed）
+//!
+//! 私钥只能来自仓库 Secret，本轮没有（也不该由代码仓库产生）私钥，所以正式表里一个条目都没有：
+//! 任何正式构建拿到清单都会以 [`super::error::UpdateErrorKind::SignatureMissing`] 之类的分类拒绝更新，
+//! 而 `packaging/sign_manifest.py --check-pinned-keyring` 会让发布流水线在「Secret 没配 / 公钥没钉」
+//! 时**当场红**（宁可不出 Release，也不出未签名的 Release）。
+//!
+//! 录一把真钥的两步（细节见 `packaging/docs/signing.md`）：
+//!
+//! ```text
+//! python packaging/sign_manifest.py --generate-key --out-key release.key   # ① 生成，私钥写进 Secret
+//! # ② 把打印出来的 `PinnedKey { … }` 一行贴到下面 PINNED-KEYS 标记之间
+//! ```
+//!
+//! 测试/验收构建另有一把**只在** `cfg(test)` / `update-test-source` / `update-test-key` 三档里存在的
+//! 测试钥（三档的口径见下面 `keyring()`）：它的私钥种子就写在测试夹具里、公开可见，因此它可以签出
+//! 「本仓库自己认得」的清单，但对任何正式构建毫无意义（正式表里没有它，`keyring()` 也不会把它并进
+//! 信任表，而且那条目根本不进编译 —— 三档都不开的产物里连它的字节都没有，读数见 `keyring()`）。
+//! 后两档（那两个 feature）各由 `packaging/check_test_source_off.py` /
+//! `check_test_key_off.py` 守着 ——正式发布流水线与打包脚本都不许打开它们。
+//! （`cfg(test)` 那档不需要守门：发布构建里根本没有 `test` cfg。）
+
+use std::sync::OnceLock;
+
+/// 一把钉死的公钥。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) struct PinnedKey {
+    /// 标签（清单签名里的 `key_id` 靠它查表；**改名就是换钥**）。
+    pub(crate) key_id: &'static str,
+    /// Ed25519 公钥的 64 位十六进制小写形态（32 字节）。
+    pub(crate) public_key_hex: &'static str,
+}
+
+/// 正式构建的信任锚（发布二进制里就是这一份）。
+///
+/// ── 加钥匙只改下面 `PINNED-KEYS` 标记之间的内容，别改标记本身 ──
+/// （`packaging/sign_manifest.py --check-pinned-keyring` 按标记解析这一段，标记变了它就找不到表）。
+pub(crate) const PRODUCTION: &[PinnedKey] = &[
+    // >>> PINNED-KEYS >>>
+    PinnedKey { key_id: "ull-release", public_key_hex: "1c3687ecd656a29fda87a7afb56e07d2b9e223b62cf3a6f1a901fb499a97b122" },
+    // <<< PINNED-KEYS <<<
+];
+
+/// 测试钥：**只**在 `cfg(test)` / `update-test-source` / `update-test-key` 三档构建里存在（正式表里没有它；
+/// 三档的口径见下面 `keyring()`）。
+///
+/// 公钥由 `tests/support.rs` 里那串公开可见的 32 字节种子推出来（种子 = `ull-m190-test-key-seed-000000001`），
+/// 两者一旦漂开，`tests/signature_cases.rs::pinned_test_key_matches_the_test_seed` 会当场红。
+///
+/// ⚠ 这个 `#[cfg]` 是**编译期剔除**，不是 `cfg!()` 那种「运行期值为假的分支」：不在这三档里时，
+/// 下面这条条目根本不进编译（只剩再下面那条同名空表），所以那串十六进制与它的 `key_id`
+/// 在产物里连字节都没有 —— 读数是实测的，见 `keyring()` 文档末尾那段。
+#[cfg(any(test, feature = "update-test-source", feature = "update-test-key"))]
+pub(crate) const TEST_ONLY: &[PinnedKey] = &[PinnedKey {
+    key_id: "test-only-key",
+    public_key_hex: "f3ea49a34ebda73d6500c9416f425e0358baf094b957baf3ea7daa6df63e876b",
+}];
+
+/// 三档之外的 `TEST_ONLY`：空表。
+///
+/// 它存在的唯一目的，是让 [`keyring()`] 里那段「把测试钥并进来」的代码在**两档里写法一致**
+/// （`keys` 的 `mut` 在两档里都有用处，不至于为 `unused_mut` 单独开 lint 口子）。空表本身就是
+/// 「这段字节不在产物里」的全部内容 —— 真条目在上一档里。
+#[cfg(not(any(test, feature = "update-test-source", feature = "update-test-key")))]
+pub(crate) const TEST_ONLY: &[PinnedKey] = &[];
+
+/// 本构建实际的信任锚（正式表 + 仅测试构建才有的那把测试钥）。
+///
+/// 三档「仅测试」的口径，逐档说明为什么需要它：
+///
+/// | 档 | 谁在用 | 为什么不能只靠 `cfg(test)` |
+/// |---|---|---|
+/// | `cfg(test)` | core 自己的单测 | 够用 |
+/// | `update-test-source` | CLI 的端到端验收（`--features update-test-source`） | 那是**另一个 target**，`cfg(test)` 不生效 |
+/// | `update-test-key` | `crates/presenter` 的 `[dev-dependencies]` | presenter 的更新链路用例编译 core 时既无 `cfg(test)`，也不该打开 `update-test-source`（那条会同时给出「本地目录当更新源」这条路）。这一档**只**加一把公开的测试公钥，不开任何数据源开关 |
+///
+/// 三档都不开的构建里，这把测试钥**既不被并进信任表，也不会被编进产物**（官方构建三个 feature 都不开，
+/// 且 `check_test_source_off.py` / `check_test_key_off.py` 守着）。
+///
+/// 这是**编译期**结论，不是运行期判据：门是 `#[cfg]`（三档之外 `TEST_ONLY` 只剩上面那条空表，
+/// 真条目根本不进编译），而不是 `cfg!()` 那种「运行期值为假的分支」—— 后者会把那段字节照编进产物。
+///
+/// 实测读数（本机 Windows + Git Bash，`grep -ac` 数的是命中行数，`grep` 退出码 1 = 零命中；
+/// `$HEX` = 上文 `TEST_ONLY` 里的 `public_key_hex`，`$KID` = 那条的 `key_id`）：
+///
+/// ```text
+/// $ CARGO_TARGET_DIR=... cargo build -p unlucky-core --lib                      # exit 0
+/// $ grep -ac "$HEX" .../debug/libunlucky_core.rlib                              # 0
+/// $ grep -ac "$KID" .../debug/libunlucky_core.rlib                              # 0
+/// $ CARGO_TARGET_DIR=... cargo build -p unlucky-core --lib --release            # exit 0
+/// $ grep -ac "$HEX" .../release/libunlucky_core.rlib                            # 0
+/// $ grep -ac "$KID" .../release/libunlucky_core.rlib                            # 0
+/// $ CARGO_TARGET_DIR=...-key cargo build -p unlucky-core --lib --features update-test-key   # exit 0
+/// $ grep -ac "$HEX" ...-key/debug/libunlucky_core.rlib                          # 2
+/// $ grep -ac "$KID" ...-key/debug/libunlucky_core.rlib                          # 2
+/// ```
+///
+/// （最后两行是对照臂：真打开那一档时这两串**都在**，所以前六行的 0 不是「grep 坏了」。）
+///
+/// ⚠ 这份读数只到 **rlib 为止**：core 的 `--lib` 产物里没有那两串字节。**未验**的是最终链接出来的
+/// exe 在 `lto = "fat"` + `strip = "symbols"` 之后是否还有那段字节 —— 那是链接期与 strip 的事，
+/// 本条的判据（编译期剔除）管不到，别把上面六行读成「exe 里也不可能有」。另：无论有没有那段字节，
+/// 验签都 fail-closed（信任表里没有这把钥）。
+pub(crate) fn keyring() -> &'static [PinnedKey] {
+    static ALL: OnceLock> = OnceLock::new();
+    ALL.get_or_init(|| {
+        let mut keys = PRODUCTION.to_vec();
+        // 三档之外 `TEST_ONLY` 是上面那条空表，这一段等于什么都没并；三档之内才是真条目。
+        keys.extend_from_slice(TEST_ONLY);
+        keys
+    })
+}
+
+/// 十六进制解码（只收小写/大写十六进制，长度必须是偶数）。
+pub(crate) fn decode_hex(text: &str) -> Option> {
+    if !text.len().is_multiple_of(2) {
+        return None;
+    }
+    let bytes = text.as_bytes();
+    let mut out = Vec::with_capacity(bytes.len() / 2);
+    let (pairs, _) = bytes.as_chunks::<2>();
+    for pair in pairs {
+        let hi = (pair[0] as char).to_digit(16)?;
+        let lo = (pair[1] as char).to_digit(16)?;
+        out.push(u8::try_from(hi * 16 + lo).ok()?);
+    }
+    Some(out)
+}
diff --git a/crates/core/src/update/verify.rs b/crates/core/src/update/verify.rs
new file mode 100644
index 0000000..df3bc29
--- /dev/null
+++ b/crates/core/src/update/verify.rs
@@ -0,0 +1,134 @@
+//! 下载产物的校验：长度（截断）+ 摘要（内容），不符即拒绝安装。
+//!
+//! 承 `download` 的规矩「先校验后落盘」：包体先落在暂存目录的中间文件里，长度与摘要都对上
+//! 才算 [`StagedPackage`]；对不上就**立刻删掉**，绝不让它有机会顶到目标路径上。
+//!
+//! 两道判据的顺序是有意的：先比长度（能抓住截断，且不需要读全文件），再比摘要（能抓住
+//! 「长度对但内容错」）。顺序反过来会让「被截断的包」白白多读一遍盘。
+//!
+//! 长度判据用「**恰好等于**」而不是「不小于」：清单里的 `size` 是我们自己发的字节数，
+//! 多了同样是错的（比如拼接了两个包），多一个字节也不许装。
+
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+
+use crate::download::verify::{digest_file, matches};
+use crate::download::Integrity;
+
+use super::error::{UpdateError, UpdateErrorKind};
+use super::manifest::Artifact;
+use super::source::UpdateSource;
+
+/// 暂存文件的进程内序号（同一进程多次更新不撞名）。
+static SEQ: AtomicU64 = AtomicU64::new(0);
+
+/// 校验通过的暂存包。
+///
+/// `Drop` 时删掉暂存文件（装好之后 `rename` 已经把它搬走，删除是无操作）；
+/// 因此「校验失败要清理」这件事不需要调用方记得做。
+#[derive(Debug)]
+pub struct StagedPackage {
+    path: PathBuf,
+    size: u64,
+    integrity: Integrity,
+}
+
+impl StagedPackage {
+    /// 暂存文件路径。
+    #[must_use]
+    pub fn path(&self) -> &Path {
+        &self.path
+    }
+
+    /// 实际字节数（已与清单核对过，等于清单声明的 `size`）。
+    #[must_use]
+    pub const fn size(&self) -> u64 {
+        self.size
+    }
+
+    /// 校验用的摘要。
+    #[must_use]
+    pub fn integrity(&self) -> &Integrity {
+        &self.integrity
+    }
+}
+
+impl Drop for StagedPackage {
+    fn drop(&mut self) {
+        let _ = fs::remove_file(&self.path);
+    }
+}
+
+/// 从源取包体 → 落暂存 → 长度与摘要双检。
+///
+/// # Errors
+///
+/// 取包失败透传 [`UpdateError`]；长度不符是 [`UpdateErrorKind::SizeMismatch`]，
+/// 摘要不符是 [`UpdateErrorKind::DigestMismatch`]。失败时暂存文件已被删掉。
+pub fn stage(
+    source: &dyn UpdateSource,
+    artifact: &Artifact,
+    staging_dir: &Path,
+) -> Result {
+    fs::create_dir_all(staging_dir).map_err(|error| UpdateError::io_at(staging_dir, &error))?;
+    let path = staging_dir.join(format!(
+        "{}-{}.ullupd",
+        std::process::id(),
+        SEQ.fetch_add(1, Ordering::Relaxed)
+    ));
+    let outcome = source
+        .fetch_artifact(artifact, &path)
+        .and_then(|_| verify_file(&path, &artifact.integrity, artifact.size));
+    match outcome {
+        Ok(size) => Ok(StagedPackage {
+            path,
+            size,
+            integrity: artifact.integrity.clone(),
+        }),
+        Err(error) => {
+            let _ = fs::remove_file(&path);
+            Err(error)
+        }
+    }
+}
+
+/// 校验一个已经落盘的文件：长度必须**恰好**等于 `expected_size`，摘要必须相等。
+///
+/// # Errors
+///
+/// 读不到文件/读失败是 [`UpdateErrorKind::Io`]；长度不符是 `SizeMismatch`；
+/// 摘要不符是 `DigestMismatch`。
+pub fn verify_file(
+    path: &Path,
+    integrity: &Integrity,
+    expected_size: u64,
+) -> Result {
+    let metadata = fs::metadata(path).map_err(|error| UpdateError::io_at(path, &error))?;
+    let actual = metadata.len();
+    if actual != expected_size {
+        return Err(UpdateError::new(
+            UpdateErrorKind::SizeMismatch,
+            format!(
+                "包体 {actual} 字节，清单声明 {expected_size} 字节（差 {} 字节；短了通常是下载被截断）",
+                expected_size.abs_diff(actual)
+            ),
+        )
+        .with_path(path));
+    }
+    let digest =
+        digest_file(path, integrity.algo).map_err(|error| UpdateError::io_at(path, &error))?;
+    if !matches(&integrity.hex, &digest) {
+        return Err(UpdateError::new(
+            UpdateErrorKind::DigestMismatch,
+            format!(
+                "{} 摘要不符：清单 {} / 实际 {}（拒绝安装）",
+                integrity.algo.as_str(),
+                integrity.short_prefix(),
+                &digest[..digest.len().min(8)]
+            ),
+        )
+        .with_path(path));
+    }
+    Ok(actual)
+}
diff --git a/crates/core/src/update/version.rs b/crates/core/src/update/version.rs
new file mode 100644
index 0000000..d83addb
--- /dev/null
+++ b/crates/core/src/update/version.rs
@@ -0,0 +1,363 @@
+//! 语义化版本：解析、比较、预发布阶段识别。
+//!
+//! 排序规则严格按 semver 2.0 §11：
+//!
+//! 1. 主 / 次 / 修订号按**数值**比（不是字符串比，所以 `0.9.0 < 0.10.0`）；
+//! 2. 带预发布标识的版本**小于**同号正式版（`1.0.0-rc.1 < 1.0.0`）；
+//! 3. 预发布标识逐段比：纯数字段按数值比、其余按 ASCII 字典序比；纯数字段**小于**任何
+//!    非数字段；前缀相同时段数少的更小（`1.0.0-alpha < 1.0.0-alpha.1`）；
+//! 4. 构建元数据（`+` 之后）**既不参与比较也不参与相等判定**。
+//!
+//! `alpha < beta < rc` 不是特例：ASCII 里 `a < b < r`，规则 3 自然得出
+//! `1.0.0-alpha.1 < 1.0.0-beta.1 < 1.0.0-rc.1 < 1.0.0`。**别**在这里加「阶段权重表」，
+//! 一旦加了，`1.0.0-preview` 与 `1.0.0-rc` 的相对顺序就和 semver 生态不一致了。
+//!
+//! 拒绝的写法（宁可解析失败，也别让「看起来像版本」的字符串混进清单）：段数不是三段、
+//! 前导零（`01.2.3`）、空标识段（`1.0.0-`、`1.0.0-alpha..1`）、非 ASCII 标识字符、
+//! 留空的构建元数据。唯一放宽的是可选前缀 `v`（`v1.4.2`），因为 git tag 普遍这么写。
+
+use std::cmp::Ordering;
+use std::fmt;
+
+/// 版本号解析失败。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct VersionError {
+    input: String,
+    reason: String,
+}
+
+impl VersionError {
+    /// 原始输入（已 trim，但保留 `v` 前缀这种细节）。
+    #[must_use]
+    pub fn input(&self) -> &str {
+        &self.input
+    }
+
+    /// 具体原因。
+    #[must_use]
+    pub fn reason(&self) -> &str {
+        &self.reason
+    }
+}
+
+impl fmt::Display for VersionError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "版本号 `{}` 不合法：{}", self.input, self.reason)
+    }
+}
+
+impl std::error::Error for VersionError {}
+
+fn invalid(input: &str, reason: impl Into) -> VersionError {
+    VersionError {
+        input: input.trim().to_string(),
+        reason: reason.into(),
+    }
+}
+
+/// 预发布标识的一段。
+///
+/// 刻意不对外暴露：外部能构造出 `Alpha("01")` 这种违反 semver 不变量的值，
+/// 排序与相等就自相矛盾了。读方向只给 [`Version::prerelease`] 的字符串形式。
+#[derive(Debug, Clone, PartialEq, Eq)]
+enum Identifier {
+    Numeric(u64),
+    Alpha(String),
+}
+
+impl fmt::Display for Identifier {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Numeric(value) => write!(f, "{value}"),
+            Self::Alpha(text) => f.write_str(text),
+        }
+    }
+}
+
+impl Ord for Identifier {
+    fn cmp(&self, other: &Self) -> Ordering {
+        match (self, other) {
+            (Self::Numeric(left), Self::Numeric(right)) => left.cmp(right),
+            (Self::Numeric(_), Self::Alpha(_)) => Ordering::Less,
+            (Self::Alpha(_), Self::Numeric(_)) => Ordering::Greater,
+            (Self::Alpha(left), Self::Alpha(right)) => left.cmp(right),
+        }
+    }
+}
+
+impl PartialOrd for Identifier {
+    fn partial_cmp(&self, other: &Self) -> Option {
+        Some(self.cmp(other))
+    }
+}
+
+/// 预发布阶段（渠道准入判定用，见 [`crate::update::Channel::admits_stage`]）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum Stage {
+    /// 正式版（没有预发布标识）。
+    Stable,
+    /// `rc` / `pre` / `preview`。
+    ReleaseCandidate,
+    /// `beta` / `b`。
+    Beta,
+    /// `alpha` / `a`。
+    Alpha,
+    /// 认不出的预发布标识（只有 `nightly` 渠道收）。
+    Unknown,
+}
+
+impl Stage {
+    /// 稳定字符串 id。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Stable => "stable",
+            Self::ReleaseCandidate => "rc",
+            Self::Beta => "beta",
+            Self::Alpha => "alpha",
+            Self::Unknown => "unknown",
+        }
+    }
+}
+
+/// 版本号。
+///
+/// 字段私有：构造只走 [`Version::parse`] 与 [`Version::new`]，不变量（前导零、空标识段）
+/// 因此只需要守一处。
+#[derive(Debug, Clone)]
+pub struct Version {
+    major: u64,
+    minor: u64,
+    patch: u64,
+    pre: Vec,
+    build: Option,
+}
+
+impl Version {
+    /// 正式版（`major.minor.patch`，无预发布、无构建元数据）。
+    #[must_use]
+    pub const fn new(major: u64, minor: u64, patch: u64) -> Self {
+        Self {
+            major,
+            minor,
+            patch,
+            pre: Vec::new(),
+            build: None,
+        }
+    }
+
+    /// 解析 `MAJOR.MINOR.PATCH[-PRE][+BUILD]`（可选前缀 `v`）。
+    ///
+    /// # Errors
+    ///
+    /// 任何不符合 semver 的写法都返回 [`VersionError`]，错误里带原始输入与原因。
+    pub fn parse(text: &str) -> Result {
+        let trimmed = text.trim();
+        let body = trimmed
+            .strip_prefix('v')
+            .or_else(|| trimmed.strip_prefix('V'))
+            .unwrap_or(trimmed);
+
+        let (body, build) = match body.split_once('+') {
+            Some((head, build)) => (head, Some(build)),
+            None => (body, None),
+        };
+        if let Some(build) = build {
+            if build.split('.').any(|segment| !is_identifier(segment)) {
+                return Err(invalid(text, "构建元数据含非法字符或空段"));
+            }
+        }
+
+        let (core, pre) = match body.split_once('-') {
+            Some((head, pre)) => (head, Some(pre)),
+            None => (body, None),
+        };
+
+        let mut numbers = core.split('.');
+        let major = segment_number(text, numbers.next(), "主版本号")?;
+        let minor = segment_number(text, numbers.next(), "次版本号")?;
+        let patch = segment_number(text, numbers.next(), "修订号")?;
+        if numbers.next().is_some() {
+            return Err(invalid(text, "只接受三段数字（主.次.修订）"));
+        }
+
+        let pre = match pre {
+            Some(pre) => parse_prerelease(text, pre)?,
+            None => Vec::new(),
+        };
+
+        Ok(Self {
+            major,
+            minor,
+            patch,
+            pre,
+            build: build.map(str::to_string),
+        })
+    }
+
+    /// 主版本号。
+    #[must_use]
+    pub const fn major(&self) -> u64 {
+        self.major
+    }
+
+    /// 次版本号。
+    #[must_use]
+    pub const fn minor(&self) -> u64 {
+        self.minor
+    }
+
+    /// 修订号。
+    #[must_use]
+    pub const fn patch(&self) -> u64 {
+        self.patch
+    }
+
+    /// 预发布标识的原始写法（`None` = 正式版）。
+    #[must_use]
+    pub fn prerelease(&self) -> Option {
+        if self.pre.is_empty() {
+            return None;
+        }
+        Some(
+            self.pre
+                .iter()
+                .map(ToString::to_string)
+                .collect::>()
+                .join("."),
+        )
+    }
+
+    /// 构建元数据（`+` 之后，不参与比较）。
+    #[must_use]
+    pub fn build_metadata(&self) -> Option<&str> {
+        self.build.as_deref()
+    }
+
+    /// 是否预发布。
+    #[must_use]
+    pub fn is_prerelease(&self) -> bool {
+        !self.pre.is_empty()
+    }
+
+    /// 预发布阶段（正式版为 [`Stage::Stable`]）。
+    #[must_use]
+    pub fn stage(&self) -> Stage {
+        match self.pre.first() {
+            None => Stage::Stable,
+            Some(Identifier::Numeric(_)) => Stage::Unknown,
+            Some(Identifier::Alpha(name)) => match name.as_str() {
+                "alpha" | "a" => Stage::Alpha,
+                "beta" | "b" => Stage::Beta,
+                "rc" | "pre" | "preview" => Stage::ReleaseCandidate,
+                _ => Stage::Unknown,
+            },
+        }
+    }
+}
+
+fn segment_number(whole: &str, segment: Option<&str>, label: &str) -> Result {
+    let Some(segment) = segment else {
+        return Err(invalid(whole, "段数不足：需要 `主.次.修订` 三段"));
+    };
+    if segment.is_empty() {
+        return Err(invalid(whole, format!("{label}为空")));
+    }
+    if !segment.bytes().all(|byte| byte.is_ascii_digit()) {
+        return Err(invalid(whole, format!("{label}含非数字字符")));
+    }
+    if segment.len() > 1 && segment.starts_with('0') {
+        return Err(invalid(whole, format!("{label}不得有前导零")));
+    }
+    segment
+        .parse::()
+        .map_err(|_| invalid(whole, format!("{label}超出 u64 范围")))
+}
+
+fn is_identifier(segment: &str) -> bool {
+    !segment.is_empty()
+        && segment
+            .bytes()
+            .all(|byte| byte.is_ascii_alphanumeric() || byte == b'-')
+}
+
+fn parse_prerelease(whole: &str, pre: &str) -> Result, VersionError> {
+    let mut out = Vec::new();
+    for segment in pre.split('.') {
+        if !is_identifier(segment) {
+            return Err(invalid(whole, "预发布标识含非法字符或空段"));
+        }
+        if segment.bytes().all(|byte| byte.is_ascii_digit()) {
+            if segment.len() > 1 && segment.starts_with('0') {
+                return Err(invalid(whole, "预发布数字段不得有前导零"));
+            }
+            let value = segment
+                .parse::()
+                .map_err(|_| invalid(whole, "预发布数字段超出 u64 范围"))?;
+            out.push(Identifier::Numeric(value));
+        } else {
+            out.push(Identifier::Alpha(segment.to_string()));
+        }
+    }
+    Ok(out)
+}
+
+fn compare_prerelease(left: &[Identifier], right: &[Identifier]) -> Ordering {
+    match (left.is_empty(), right.is_empty()) {
+        (true, true) => Ordering::Equal,
+        (true, false) => Ordering::Greater,
+        (false, true) => Ordering::Less,
+        (false, false) => left.cmp(right),
+    }
+}
+
+impl Ord for Version {
+    fn cmp(&self, other: &Self) -> Ordering {
+        self.major
+            .cmp(&other.major)
+            .then_with(|| self.minor.cmp(&other.minor))
+            .then_with(|| self.patch.cmp(&other.patch))
+            .then_with(|| compare_prerelease(&self.pre, &other.pre))
+    }
+}
+
+impl PartialOrd for Version {
+    fn partial_cmp(&self, other: &Self) -> Option {
+        Some(self.cmp(other))
+    }
+}
+
+impl PartialEq for Version {
+    fn eq(&self, other: &Self) -> bool {
+        self.cmp(other) == Ordering::Equal
+    }
+}
+
+impl Eq for Version {}
+
+impl fmt::Display for Version {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}.{}.{}", self.major, self.minor, self.patch)?;
+        if !self.pre.is_empty() {
+            f.write_str("-")?;
+            for (index, identifier) in self.pre.iter().enumerate() {
+                if index > 0 {
+                    f.write_str(".")?;
+                }
+                write!(f, "{identifier}")?;
+            }
+        }
+        if let Some(build) = &self.build {
+            write!(f, "+{build}")?;
+        }
+        Ok(())
+    }
+}
+
+impl std::str::FromStr for Version {
+    type Err = VersionError;
+
+    fn from_str(text: &str) -> Result {
+        Self::parse(text)
+    }
+}
diff --git a/crates/core/tests/adopt/collision_cases.rs b/crates/core/tests/adopt/collision_cases.rs
new file mode 100644
index 0000000..4b42304
--- /dev/null
+++ b/crates/core/tests/adopt/collision_cases.rs
@@ -0,0 +1,221 @@
+//! 运行目录**碰撞**：slug 同名 / 大小写不敏感 / 「空目录已被实例占着」/ 「认领目录还不存在」。
+//!
+//! 复审 r1 的 R1：旧实现只比展示名，第二次登记看到「目录是空的」就复用了 ⇒ 两个从未选择
+//! shared/custom 的实例共用一个运行目录（`mods`/`saves` 互相污染）。
+//! 判据必须是「有没有实例占着这个**真实**目录」，而不是「目录空不空」。
+
+use unlucky_core::game::adopt::{self, AdoptTarget};
+use unlucky_core::game::install::instance::read_instance_config;
+use unlucky_core::game::install::pack_dir;
+
+use crate::fixture::{foreign_minecraft, request, TempRoot};
+
+/// **slug 碰撞**：`Better MC` 与 `Better-MC` 派生到同一个目录名 —— 两个实例必须落在不同目录。
+///
+/// 复审 r1 的 R1：旧实现只比展示名，第二次登记看到「目录是空的」就复用了，于是两个从未选择
+/// shared/custom 的实例共用一个运行目录（`mods`/`saves` 互相污染）。
+///
+/// 抓得住：
+/// - 判据只看目录空不空、不看已有实例占没占（两条 `run_dir` 不同的断言会红）；
+/// - 顺延目录没建出来 / 提示里没点出撞的是谁。
+///
+/// 抓不住：`pack_dir::instance_dir_name` 本身把两个名字折成同一个目录（那是既有行为，
+/// 本 mission 不改它，只保证**登记侧**不共用）。
+#[test]
+fn slug_colliding_names_do_not_share_a_run_dir() {
+    let root = TempRoot::new("slug-collide");
+    foreign_minecraft(&root.game_root());
+
+    let mut first = request("1.20.1", AdoptTarget::InstanceDir);
+    first.name = Some("Better MC".to_string());
+    let a = adopt::adopt(&root.game(), &root.launcher(), &first).expect("第一次登记");
+    let mut second = request("1.20.1", AdoptTarget::InstanceDir);
+    second.name = Some("Better-MC".to_string());
+    let b = adopt::adopt(&root.game(), &root.launcher(), &second).expect("第二次登记");
+
+    assert_ne!(a.run_dir, b.run_dir, "两个实例不许共用同一个运行目录");
+    assert!(
+        a.run_dir.is_dir() && b.run_dir.is_dir(),
+        "两个目录都要真实存在"
+    );
+    let bumped = b
+        .run_dir
+        .file_name()
+        .map(|name| name.to_string_lossy().into_owned());
+    assert!(
+        bumped.as_deref().is_some_and(|name| name.ends_with("-2")),
+        "撞车后应顺延成 -2：{:?}",
+        b.run_dir
+    );
+    assert!(
+        b.notes.iter().any(|note| note.contains("同一个物理目录")),
+        "必须把「撞了谁」说出来：{:?}",
+        b.notes
+    );
+
+    // 两份实例设置各自指向自己的目录（不是都指第一个）。
+    let config_a = read_instance_config(&root.launcher(), &a.instance_id)
+        .expect("读设置")
+        .expect("有设置文件");
+    let config_b = read_instance_config(&root.launcher(), &b.instance_id)
+        .expect("读设置")
+        .expect("有设置文件");
+    assert_eq!(config_a.game_dir.as_deref(), Some(a.run_dir.as_path()));
+    assert_eq!(config_b.game_dir.as_deref(), Some(b.run_dir.as_path()));
+}
+
+/// **大小写碰撞**（Windows/macOS）：`Foo` 与 `foo` 是同一个物理目录 ⇒ 同样必须顺延。
+///
+/// 抓得住：`dir_key` 不做大小写归一（Windows 上第二次登记会复用同一个目录）。
+/// 抓不住：Linux（大小写敏感，两条目录本来就不同——那里这条不适用，见 `cfg`）。
+#[cfg(windows)]
+#[test]
+fn names_differing_only_in_case_do_not_share_a_run_dir() {
+    let root = TempRoot::new("case-collide");
+    foreign_minecraft(&root.game_root());
+
+    let mut first = request("1.20.1", AdoptTarget::InstanceDir);
+    first.name = Some("Foo".to_string());
+    let a = adopt::adopt(&root.game(), &root.launcher(), &first).expect("第一次登记");
+    let mut second = request("1.20.1", AdoptTarget::InstanceDir);
+    second.name = Some("foo".to_string());
+    let b = adopt::adopt(&root.game(), &root.launcher(), &second).expect("第二次登记");
+
+    assert_ne!(a.run_dir, b.run_dir, "大小写不同不是「不同目录」的理由");
+    let a_real = a.run_dir.canonicalize().expect("真实路径 A");
+    let b_real = b.run_dir.canonicalize().expect("真实路径 B");
+    assert_ne!(a_real, b_real, "两个运行目录的真实路径必须不同");
+}
+
+/// 空目录**已被别的实例占着** ⇒ 也不能当「失败残留」复用，要顺延。
+///
+/// 这是 R1 的另一半：判据必须是「有没有实例占着」，而不是「目录空不空」。
+///
+/// 抓得住：只按 `directory_occupied` 判（第一次登记建出的空目录会被第二次白白复用）。
+/// 抓不住：目录非空且无人认领的情形（那条保持 `TargetNotEmpty`，见下一条用例）。
+#[test]
+fn an_empty_dir_owned_by_another_instance_is_not_reused() {
+    let root = TempRoot::new("owned-empty");
+    foreign_minecraft(&root.game_root());
+    let mut first = request("1.20.1", AdoptTarget::InstanceDir);
+    first.name = Some("Better MC".to_string());
+    let a = adopt::adopt(&root.game(), &root.launcher(), &first).expect("第一次登记");
+    // 目录此刻是空的（新建、还没启动过游戏）——旧判据会认为「可复用」。
+    let entries_before = std::fs::read_dir(&a.run_dir).expect("读目录").count();
+    assert_eq!(entries_before, 0, "夹具前提：这个目录此刻是空的");
+
+    let mut second = request("1.20.1", AdoptTarget::InstanceDir);
+    second.name = Some("Better-MC".to_string());
+    let b = adopt::adopt(&root.game(), &root.launcher(), &second).expect("第二次登记");
+    assert_ne!(b.run_dir, a.run_dir);
+}
+
+/// **认领的目录还不存在**时也必须能比对出碰撞。
+///
+/// 场景：第一个实例用 `--isolation custom --game-dir <某路径>` 登记（custom 档**不创建**目录），
+/// 那条路径恰好等于第二个实例缺省派生出来的目录名。第二个实例看到的目录「不存在、非空判据为假」，
+/// 但它已经被第一个实例认领了。
+///
+/// 抓得住：`claims`/`dir_key` 只在「路径存在」时才比较（那样第二条 `run_dir` 相同的断言会红）；
+/// 抓不住：跨卷/大小写之外的别名（例如 8.3 短名），本判据不覆盖。
+#[test]
+fn a_claim_on_a_not_yet_existing_dir_still_collides() {
+    let root = TempRoot::new("claim-missing");
+    foreign_minecraft(&root.game_root());
+    let default_dir = pack_dir::instance_dir(&root.launcher(), "Better MC");
+    assert!(!default_dir.exists(), "夹具前提：这个目录还不存在");
+
+    let mut first = request("1.20.1", AdoptTarget::Custom(default_dir.clone()));
+    first.name = Some("Better MC".to_string());
+    let a = adopt::adopt(&root.game(), &root.launcher(), &first).expect("custom 登记成功");
+    assert_eq!(a.run_dir, default_dir);
+    assert!(!default_dir.exists(), "custom 目标不该被创建");
+
+    let mut second = request("1.20.1", AdoptTarget::InstanceDir);
+    second.name = Some("Better-MC".to_string());
+    let b = adopt::adopt(&root.game(), &root.launcher(), &second).expect("第二次登记成功");
+
+    assert_ne!(b.run_dir, default_dir, "认领侧不存在也要能比对出碰撞");
+    assert!(
+        b.notes.iter().any(|note| note.contains("同一个物理目录")),
+        "碰撞要写进 notes：{:?}",
+        b.notes
+    );
+}
+
+/// **Win32 尾点/尾空格别名**：`custom` 认领 `Foo.`（目录还没建）与缺省派生 `Foo` 是**同一个物理目录**。
+///
+/// 复审 r2 的 R2.1：普通路径的尾点/尾空格会被 Win32 折叠，旧实现把尚不存在的尾段原样拼进比较键，
+/// 于是第二次默认登记仍拿到 `Foo`（两次都 exit0、两个 UUID、同一物理目录）。
+///
+/// 抓得住：`dir_key` 只做分隔符/大小写归一（`Foo.` 与 `Foo` 键不等，第二条断言红）。
+///
+/// 抓不住：verbatim 路径（`\\?\…`）——那种写法**不**折叠，是另一个物理目录，见下一条用例。
+#[cfg(windows)]
+#[test]
+fn a_trailing_dot_claim_still_collides_with_the_derived_dir() {
+    for suffix in [".", " "] {
+        let root = TempRoot::new("win32-alias");
+        foreign_minecraft(&root.game_root());
+        let claimed = pack_dir::instance_dir(&root.launcher(), &format!("Foo{suffix}"))
+            .with_file_name(format!("Foo{suffix}"));
+        assert!(!claimed.exists(), "夹具前提：认领目录还不存在");
+
+        let mut first = request("1.20.1", AdoptTarget::Custom(claimed.clone()));
+        first.name = Some("First".to_string());
+        let a = adopt::adopt(&root.game(), &root.launcher(), &first).expect("custom 登记成功");
+
+        let mut second = request("1.20.1", AdoptTarget::InstanceDir);
+        second.name = Some("Foo".to_string());
+        let b = adopt::adopt(&root.game(), &root.launcher(), &second)
+            .expect("第二次默认登记应成功（顺延到 -2，而不是复用同一目录）");
+
+        assert_ne!(
+            b.run_dir, a.run_dir,
+            "尾点/尾空格别名不许让两个实例共用一个运行目录（suffix={suffix:?}）"
+        );
+        assert!(
+            b.run_dir
+                .file_name()
+                .map(|name| name.to_string_lossy().ends_with("-2"))
+                .unwrap_or(false),
+            "应顺延成 -2：{}",
+            b.run_dir.display()
+        );
+        assert!(
+            !a.run_dir.exists(),
+            "custom 认领的目录不该被创建：{}",
+            a.run_dir.display()
+        );
+    }
+}
+
+/// 正向：**verbatim** 路径（`\\?\…`）不折叠 —— 它是另一个物理目录，必须允许并存。
+///
+/// 抓得住：归一化时盲目 trim（verbatim 的 `Foo.` 会被折叠成 `Foo`，这条第二次登记会顺延，
+/// `-2` 断言红）。
+///
+/// 抓不住：别的重解析点形态；也不验 8.3 短名。
+#[cfg(windows)]
+#[test]
+fn a_verbatim_trailing_dot_path_is_not_folded() {
+    let root = TempRoot::new("verbatim");
+    foreign_minecraft(&root.game_root());
+    let base = pack_dir::instance_dir(&root.launcher(), "Bar");
+    let verbatim =
+        std::path::PathBuf::from(format!(r"\\?\{}", base.with_file_name("Bar.").display()));
+    let mut first = request("1.20.1", AdoptTarget::Custom(verbatim.clone()));
+    first.name = Some("First".to_string());
+    adopt::adopt(&root.game(), &root.launcher(), &first).expect("verbatim custom 登记成功");
+
+    let mut second = request("1.20.1", AdoptTarget::InstanceDir);
+    second.name = Some("Bar".to_string());
+    let b = adopt::adopt(&root.game(), &root.launcher(), &second).expect("默认登记成功");
+    assert_eq!(
+        b.run_dir
+            .file_name()
+            .map(|n| n.to_string_lossy().into_owned()),
+        Some("Bar".to_string()),
+        "verbatim 的 Bar. 与普通 Bar 是两个目录，不该顺延"
+    );
+}
diff --git a/crates/core/tests/adopt/fixture.rs b/crates/core/tests/adopt/fixture.rs
new file mode 100644
index 0000000..9a28d63
--- /dev/null
+++ b/crates/core/tests/adopt/fixture.rs
@@ -0,0 +1,349 @@
+//! 真实磁盘夹具：一份「别的启动器铺好的」`.minecraft` + 全量快照工具。
+//!
+//! # 为什么必须是真盘
+//!
+//! 本 mission 的核心判据是**「登记前后外部文件一个字节都不变」**。内存里的假目录证明不了这件事
+//! ——mtime、目录项、符号链接都只有真文件系统才存在。所以每个用例都在 `std::env::temp_dir()`
+//! 下建一棵真目录树，`Drop` 时整棵删掉。
+//!
+//! # 夹具里放了什么（逐项都有用意）
+//!
+//! | 路径 | 用意 |
+//! | --- | --- |
+//! | `versions/1.20.1/` | 正常版本（清单 + jar） |
+//! | `versions/1.20.1-fabric-0.15.0/` | 正常版本，`inheritsFrom` 指向 1.20.1（父链闭合） |
+//! | `versions/1.20.1-broken/` | 清单不是合法 JSON |
+//! | `versions/1.20.1-orphan/` | `inheritsFrom` 指向不存在的父 |
+//! | `versions/cycle-a/` `versions/cycle-b/` | 互相继承（成环） |
+//! | `versions/1.20.1-nomanifest/` | 只有目录、没有同名清单 |
+//! | `libraries/` `assets/` | 恒共享层（登记不该碰） |
+//! | `mods/` `saves/` `config/` | 玩家数据（登记不该碰） |
+//! | `launcher_profiles.json` | 别的启动器的元数据（连读都不该读，更不该写） |
+//!
+//! 快照工具在 `snapshot.rs`（**全节点**：目录/文件/链接各记形状与 mtime，读盘失败即失败），
+//! 本模块只做 `pub use`，测试统一从 `crate::fixture::{snapshot, assert_unchanged, …}` 取。
+
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use unlucky_core::game::adopt::{AdoptRequest, AdoptTarget};
+use unlucky_core::game::GameLayout;
+
+pub use super::snapshot::{assert_unchanged, snapshot, snapshot_opt, Node};
+use unlucky_core::platform::layout::LauncherLayout;
+
+/// 唯一临时目录守卫（`drop` 时递归删除）。
+pub struct TempRoot {
+    path: PathBuf,
+}
+
+impl TempRoot {
+    /// 建一个唯一临时根。
+    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-adopt-{tag}-{}-{nanos}-{seq}",
+            std::process::id()
+        ));
+        std::fs::create_dir_all(&path).expect("临时根应可创建");
+        Self { path }
+    }
+
+    /// 临时根路径。
+    pub fn path(&self) -> &Path {
+        &self.path
+    }
+
+    /// `.minecraft`（游戏根）。
+    pub fn game_root(&self) -> PathBuf {
+        self.path.join(".minecraft")
+    }
+
+    /// 游戏布局。
+    pub fn game(&self) -> GameLayout {
+        GameLayout::new(self.game_root())
+    }
+
+    /// 启动器数据布局（`/.ULL`）。
+    pub fn launcher(&self) -> LauncherLayout {
+        LauncherLayout::new(self.path.join(".ULL"))
+    }
+}
+
+impl Drop for TempRoot {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_dir_all(&self.path);
+    }
+}
+
+/// 造一份「别的启动器已经铺好的」`.minecraft`（见模块文档的表）。
+pub fn foreign_minecraft(root: &Path) {
+    let versions = root.join("versions");
+    // 正常版本：清单 + jar。
+    version_with(&versions, "1.20.1", MANIFEST_VANILLA, true);
+    // 正常版本：带父链（fabric 形态：只有清单、没有自己的 jar）。
+    version_with(&versions, "1.20.1-fabric-0.15.0", MANIFEST_FABRIC, false);
+    // 清单坏掉。
+    let broken = versions.join("1.20.1-broken");
+    std::fs::create_dir_all(&broken).expect("建坏清单目录");
+    std::fs::write(broken.join("1.20.1-broken.json"), b"{ this is not json").expect("写坏清单");
+    // 缺父版本。
+    version_with(&versions, "1.20.1-orphan", MANIFEST_ORPHAN, true);
+    // 成环。
+    version_with(&versions, "cycle-a", MANIFEST_CYCLE_A, true);
+    version_with(&versions, "cycle-b", MANIFEST_CYCLE_B, true);
+    // 只有目录、没有清单。
+    std::fs::create_dir_all(versions.join("1.20.1-nomanifest")).expect("建无清单目录");
+
+    // 恒共享层：库与资源（登记一个字节都不该动）。
+    write_file(
+        &root.join("libraries/com/mojang/brigadier/1.0.18/brigadier-1.0.18.jar"),
+        b"library-bytes",
+    );
+    write_file(&root.join("assets/indexes/5.json"), b"{\"objects\":{}}");
+    write_file(
+        &root.join("assets/objects/ab/abcdef0123456789abcdef0123456789abcdef01"),
+        b"asset-bytes",
+    );
+    // 玩家数据。
+    write_file(&root.join("mods/jei.jar"), b"mod-bytes");
+    write_file(&root.join("saves/World/level.dat"), b"save-bytes");
+    write_file(&root.join("config/example.toml"), b"config = 1\n");
+    // 别的启动器的元数据（登记不该读、更不该写）。
+    write_file(
+        &root.join("launcher_profiles.json"),
+        br#"{"profiles":{"1.20.1":{"name":"1.20.1","lastVersionId":"1.20.1"}}}"#,
+    );
+}
+
+fn version_with(versions: &Path, id: &str, manifest: &str, jar: bool) {
+    let dir = versions.join(id);
+    std::fs::create_dir_all(&dir).expect("建版本目录");
+    std::fs::write(dir.join(format!("{id}.json")), manifest.as_bytes()).expect("写清单");
+    if jar {
+        std::fs::write(dir.join(format!("{id}.jar")), b"jar-bytes").expect("写 jar");
+    }
+}
+
+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("写文件");
+}
+
+/// 原版形态的最小清单（`downloads.client` 有值、无继承）。
+const MANIFEST_VANILLA: &str = r#"{
+  "id": "1.20.1",
+  "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": 9, "url": "http://example.invalid/client.jar" } }
+}"#;
+
+/// Fabric 形态：`inheritsFrom` 指 1.20.1（父链闭合）。
+const MANIFEST_FABRIC: &str = r#"{
+  "id": "1.20.1-fabric-0.15.0",
+  "type": "release",
+  "inheritsFrom": "1.20.1",
+  "mainClass": "net.fabricmc.loader.impl.launch.knot.KnotClient",
+  "libraries": []
+}"#;
+
+/// 缺父版本（父 id 在盘上不存在）。
+const MANIFEST_ORPHAN: &str = r#"{
+  "id": "1.20.1-orphan",
+  "type": "release",
+  "inheritsFrom": "1.20.1-not-on-disk",
+  "mainClass": "net.minecraft.client.main.Main",
+  "libraries": []
+}"#;
+
+/// 环的一侧。
+const MANIFEST_CYCLE_A: &str = r#"{
+  "id": "cycle-a",
+  "type": "release",
+  "inheritsFrom": "cycle-b",
+  "mainClass": "net.minecraft.client.main.Main",
+  "libraries": []
+}"#;
+
+/// 环的另一侧。
+const MANIFEST_CYCLE_B: &str = r#"{
+  "id": "cycle-b",
+  "type": "release",
+  "inheritsFrom": "cycle-a",
+  "mainClass": "net.minecraft.client.main.Main",
+  "libraries": []
+}"#;
+
+/// 一次登记请求（测试用：固定 `created_at`，名字缺省 = 版本 id）。
+pub fn request(version_id: &str, target: AdoptTarget) -> AdoptRequest {
+    AdoptRequest {
+        version_id: version_id.to_string(),
+        name: None,
+        target,
+        created_at: Some("2026-11-09T00:00:00.000Z".to_string()),
+    }
+}
+
+/// 建目录符号链接（`true` = 建成）。Windows 上未开开发者模式/非管理员时可能失败。
+pub fn try_symlink_dir(target: &Path, link: &Path) -> bool {
+    #[cfg(unix)]
+    let created = std::os::unix::fs::symlink(target, link).is_ok();
+    #[cfg(windows)]
+    let created = std::os::windows::fs::symlink_dir(target, link).is_ok();
+    created
+}
+
+/// 用 `mklink /J` 建目录联接（junction 不需要管理员权限；建不出来返回 `false`）。
+///
+/// 只在 Windows 上有意义：junction 不是 `is_symlink`，是把别人版本目录挂进 `versions/` 最常见的
+/// 形态，所以越界判据必须能看见它——这条夹具就是用来证明这点的。
+#[cfg(windows)]
+pub fn try_junction(target: &Path, link: &Path) -> bool {
+    // `cmd /c mklink /J  `：三个参数分开传，别拼成一整条（拼成一串会被 cmd 当语法错），
+    // 路径也必须**逐段 join**（`cmd` 把正斜杠当开关）。
+    let output = std::process::Command::new("cmd")
+        .args(["/c", "mklink", "/J"])
+        .arg(link)
+        .arg(target)
+        .output();
+    match output {
+        Ok(output) if output.status.success() && link.is_dir() => true,
+        Ok(output) => {
+            eprintln!(
+                "[junction] mklink /J {} {} 失败（{:?}）：{}{}",
+                link.display(),
+                target.display(),
+                output.status.code(),
+                String::from_utf8_lossy(&output.stdout),
+                String::from_utf8_lossy(&output.stderr)
+            );
+            false
+        }
+        Err(error) => {
+            eprintln!("[junction] 调不起 cmd：{error}");
+            false
+        }
+    }
+}
+
+/// 建目录链接：Windows 先试符号链接、再试联接；其它平台只有符号链接。
+pub fn try_link_dir(target: &Path, link: &Path) -> bool {
+    if try_symlink_dir(target, link) {
+        return true;
+    }
+    #[cfg(windows)]
+    {
+        try_junction(target, link)
+    }
+    #[cfg(not(windows))]
+    {
+        false
+    }
+}
+
+/// 链接夹具建不出来时怎么走（**真值表**，复审 r1 的 R4 抓的就是这张表被写反）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum LinkGate {
+    /// 建成了：照常跑断言。
+    Run,
+    /// 没建成且**没要求强制**：打印一行记录后跳过（不静默）。
+    Skip,
+    /// 没建成且 `ULL_ADOPT_TEST_SYMLINK_REQUIRE=1`：**必红**，不许空跑。
+    Fail,
+}
+
+/// 纯判据：`(建成了吗, 是否强制)` → 怎么走。
+#[must_use]
+pub fn link_gate(created: bool, required: bool) -> LinkGate {
+    match (created, required) {
+        (true, _) => LinkGate::Run,
+        (false, true) => LinkGate::Fail,
+        (false, false) => LinkGate::Skip,
+    }
+}
+
+/// `ULL_ADOPT_TEST_SYMLINK_REQUIRE=1` 时链接夹具**不许**空跑。
+#[must_use]
+pub fn links_required() -> bool {
+    std::env::var("ULL_ADOPT_TEST_SYMLINK_REQUIRE")
+        .as_deref()
+        .map(str::trim)
+        == Ok("1")
+}
+
+/// 链接夹具的守卫：返回 `true` = 继续跑断言；`false` = 已显式跳过（调用方 `return`）。
+///
+/// `required` 由环境变量决定（[`links_required`]）；判据本身是 [`link_gate`]。
+pub fn link_guard(created: bool, what: &str) -> bool {
+    link_guard_with(created, links_required(), what)
+}
+
+/// 同 [`link_guard`]，但 `required` 显式传入（测试要能**执行**强制分支，而不靠改进程环境）。
+///
+/// # Panics
+///
+/// `required` 且没建成链接/联接：**红**（这是复审 r1 的 R4：旧写法把方向写反了，
+/// 强制模式下建不出来反而直接「成功」返回）。
+pub fn link_guard_with(created: bool, required: bool, what: &str) -> bool {
+    match link_gate(created, required) {
+        LinkGate::Run => true,
+        LinkGate::Skip => {
+            eprintln!(
+                "[link-guard] {what}：本机建不出符号链接/目录联接，已显式跳过这条用例；                 设 ULL_ADOPT_TEST_SYMLINK_REQUIRE=1 可让它必跑（建不出来即红）"
+            );
+            false
+        }
+        LinkGate::Fail => panic!(
+            "[link-guard] {what}：ULL_ADOPT_TEST_SYMLINK_REQUIRE=1，但本机建不出符号链接/目录联接             ——这条用例不许空跑，判红"
+        ),
+    }
+}
+
+/// 真值表的回归：**强制模式建不出来必须致命**（R4 的反转就是这张表写错）。
+///
+/// 抓得住：把 `(false, true)` 判成 `Skip`（旧实现的写法）、或把 `(false, false)` 判成 `Fail`。
+/// 抓不住：真实建链接是否成功（那由各链接用例自己走 [`link_guard`]）。
+#[test]
+fn link_gate_truth_table() {
+    assert_eq!(link_gate(true, false), LinkGate::Run);
+    assert_eq!(link_gate(true, true), LinkGate::Run);
+    assert_eq!(link_gate(false, false), LinkGate::Skip);
+    assert_eq!(
+        link_gate(false, true),
+        LinkGate::Fail,
+        "强制模式下建不出链接必须红"
+    );
+}
+
+/// **执行**守卫的三个分支（不只测纯判据）：Run 继续、Skip 返回 false、Fail panic。
+///
+/// 抓得住：把 `Fail` 分支写成 `return false`（`catch_unwind` 捕不到 panic，最后一条断言红）；
+/// 把 `Skip` 写成 panic（第一条 `catch_unwind` 不再 ok）。
+/// 抓不住：真实建链接是否成功（各链接用例自己走 [`link_guard`]）；也不依赖进程级环境变量，
+/// 因此可与并行用例共存。
+#[test]
+fn link_guard_executes_all_three_branches() {
+    assert!(link_guard_with(true, false, "已建成"));
+    assert!(
+        std::panic::catch_unwind(|| link_guard_with(false, false, "非强制模式 · 建不出")).is_ok(),
+        "非强制模式不许 panic"
+    );
+    assert!(!link_guard_with(false, false, "非强制模式 · 建不出"));
+    let forced = std::panic::catch_unwind(|| link_guard_with(false, true, "强制模式 · 建不出"));
+    assert!(forced.is_err(), "强制模式下建不出来必须 panic（R4）");
+}
diff --git a/crates/core/tests/adopt/fixture_cases.rs b/crates/core/tests/adopt/fixture_cases.rs
new file mode 100644
index 0000000..b915af1
--- /dev/null
+++ b/crates/core/tests/adopt/fixture_cases.rs
@@ -0,0 +1,141 @@
+//! 快照工具自身的回归：它必须抓得住「凭空多出一个空目录」（复审 r1 的 R5）。
+//!
+//! 早先的快照只记文件：`scan` 或 `--dry-run` 若在外部树里建了一个空目录（例如
+//! `/versions//mods`），快照完全不变，于是「零写入」这条承诺可以是假绿。
+//! 这里用**同一份** `snapshot.rs` 证明：目录节点、链接节点都进快照，读盘失败不吞。
+
+use std::path::Path;
+
+use crate::fixture::{
+    link_guard, snapshot, snapshot_opt, try_link_dir, try_symlink_dir, Node, TempRoot,
+};
+
+/// 目录 / 文件 / 链接三类节点都记，且链接**不跟随**（目标内容不会挂到链接路径下）。
+///
+/// 抓得住：
+/// - 目录节点缺失（`dir` 断言红）；
+/// - 跟随链接（`link/inside.txt` 会同时出现在链接路径下，`is_none` 断言红）；
+/// - 链接被当成普通目录（`Node::Link` 断言红）。
+///
+/// 抓不住：链接目标本身的内容变化（不跟随就看不见——这正是本工具要的语义）。
+#[test]
+fn snapshot_records_dirs_files_and_links_without_following() {
+    let root = TempRoot::new("snap-shapes");
+    let real = root.path().join("real");
+    std::fs::create_dir_all(&real).expect("建真实目录");
+    std::fs::write(real.join("inside.txt"), b"x").expect("写文件");
+    let link = root.path().join("link");
+    if !link_guard(try_symlink_dir(&real, &link), "快照链接夹具") {
+        // 链接建不出来时仍要验目录/文件两类（guard 已显式记录跳过原因）。
+        let snap = snapshot(root.path());
+        assert!(matches!(snap.get("real"), Some(Node::Dir { .. })));
+        assert!(matches!(
+            snap.get("real/inside.txt"),
+            Some(Node::File { .. })
+        ));
+        return;
+    }
+
+    let snap = snapshot(root.path());
+    assert!(
+        matches!(snap.get("."), Some(Node::Dir { .. })),
+        "根自身也要记"
+    );
+    assert!(matches!(snap.get("real"), Some(Node::Dir { .. })));
+    assert!(matches!(
+        snap.get("real/inside.txt"),
+        Some(Node::File { .. })
+    ));
+    assert!(
+        matches!(snap.get("link"), Some(Node::Link { .. })),
+        "链接要记成 Link：{:?}",
+        snap.get("link")
+    );
+    assert!(
+        !snap.contains_key("link/inside.txt"),
+        "不许跟随链接（否则根外/别处内容会被算进这棵树）"
+    );
+}
+
+/// **新增一个空目录**必须让快照变化（R5 的核心判据）。
+///
+/// 抓得住：只记文件的旧快照（`before == after` 会让第一条断言红）。
+/// 抓不住：目录 mtime 的精度（这条只比路径集合与节点形状；mtime 由 `assert_unchanged` 另外守）。
+#[test]
+fn snapshot_catches_a_new_empty_directory() {
+    let root = TempRoot::new("snap-newdir");
+    let game = root.game_root().join("versions").join("1.20.1");
+    std::fs::create_dir_all(&game).expect("建版本目录");
+    let before = snapshot(&root.game_root());
+
+    // 「登记过程凭空建了一个空目录」——正是旧快照看不见的那种改动。
+    let planted = game.join("mods");
+    std::fs::create_dir_all(&planted).expect("建空目录");
+    let after = snapshot(&root.game_root());
+
+    assert_ne!(before, after, "新增空目录必须改变快照");
+    assert!(
+        !before.contains_key("versions/1.20.1/mods"),
+        "改动前不该有这个节点"
+    );
+    assert!(
+        matches!(after.get("versions/1.20.1/mods"), Some(Node::Dir { .. })),
+        "新增的空目录要作为目录节点出现：{:?}",
+        after.get("versions/1.20.1/mods")
+    );
+
+    // 反向：删掉之后路径集合回到原样（目录 mtime 会变，所以只比键集合）。
+    std::fs::remove_dir(&planted).expect("删空目录");
+    let again = snapshot(&root.game_root());
+    assert_eq!(
+        before.keys().collect::>(),
+        again.keys().collect::>(),
+        "删掉空目录后路径集合应回到原样"
+    );
+}
+
+/// 目录的 mtime 变化也要能看见（条目增删会改父目录 mtime）。
+///
+/// 抓得住：目录节点只记路径不记 mtime（那样 `Node::Dir{mtime_ns}` 相同，第二条断言红）。
+/// 抓不住：某些文件系统对 mtime 的粗粒度（本机 NTFS 是 100ns 级；真粗到同一 tick 时这条会软过）。
+#[test]
+fn snapshot_notices_a_directory_mtime_change() {
+    let root = TempRoot::new("snap-dirmtime");
+    let dir = root.path().join("watched");
+    std::fs::create_dir_all(&dir).expect("建目录");
+    let before = snapshot(root.path());
+    std::fs::write(dir.join("new.txt"), b"x").expect("写文件");
+    let after = snapshot(root.path());
+    let before_node = before.get("watched").expect("有该目录节点");
+    let after_node = after.get("watched").expect("有该目录节点");
+    assert_ne!(
+        before_node, after_node,
+        "目录里加了文件，目录节点（含 mtime）必须变"
+    );
+}
+
+/// 目标根本不存在 ⇒ `snapshot_opt` 给 `None`（与「空树」区分开）。
+///
+/// 抓得住：把「不存在」当成空快照（那样「dry-run 建了 .ULL」就看不出来）。
+/// 抓不住：存在但权限不足（那一支直接 panic，见模块文档）。
+#[test]
+fn a_missing_target_is_none_not_an_empty_snapshot() {
+    let root = TempRoot::new("snap-missing");
+    let absent: &Path = &root.path().join("nope");
+    assert!(snapshot_opt(absent).is_none());
+    std::fs::create_dir_all(absent).expect("建空目录");
+    assert!(snapshot_opt(absent).is_some(), "空目录也算存在");
+}
+
+/// 链接建不出来时 `try_link_dir` 会退回联接（Windows）；这条只验它不 panic。
+#[test]
+fn link_fixtures_are_total() {
+    let root = TempRoot::new("snap-link-total");
+    let target = root.path().join("target");
+    std::fs::create_dir_all(&target).expect("建目标");
+    let link = root.path().join("link");
+    let created = try_link_dir(&target, &link);
+    if created {
+        assert!(link.is_dir());
+    }
+}
diff --git a/crates/core/tests/adopt/main.rs b/crates/core/tests/adopt/main.rs
new file mode 100644
index 0000000..15ea73a
--- /dev/null
+++ b/crates/core/tests/adopt/main.rs
@@ -0,0 +1,24 @@
+//! M221 core 侧集成测试入口：从**别人的** `.minecraft` 只读登记版本（adopt）。
+//!
+//! 分工：
+//! - `fixture`：临时真实磁盘目录 + 一份「别的启动器铺好的」`.minecraft`；
+//! - `snapshot`：**全节点**快照（目录/文件/链接 + mtime），core 与 CLI 测试共用这一份；
+//! - `scan_cases`：`scan` / `inspect` 的判据（正常 / 坏 JSON / 缺父 / 成环 / 缺清单 / 越界符号链接）；
+//! - `plan_cases`：还没登记时的**只读**判据与拒绝理由（dry-run 零写盘 / 缺父 / 不存在 / 非法目标）；
+//! - `collision_cases`：缺省运行目录**不许被两个实例共用**（slug / 大小写 / 已被占 / 认领但未创建）；
+//! - `register_cases`：`adopt` 的落点与写盘面（缺省独立目录 / shared / isolated / custom /
+//!   重名 / 重复 / 非空目录 / 数据区联接 / **slug 与大小写碰撞不许共用运行目录** / 外部树全节点不变）；
+//! - `surface_cases`：配置写面被链接走出去必须拒绝（R2）、`versions` 入口断链必须报错（R3）；
+//! - `fixture_cases`：快照工具自身的回归（它得抓得住「凭空多一个空目录」，R5）。
+//!
+//! 这些用例**不启动真实 Minecraft**：验的是「登记这一步做了什么、没做什么」，启动链路由
+//! `tests/game/*` 与 CLI 的 `launch --dry-run` 各自覆盖。
+
+mod collision_cases;
+mod fixture;
+mod fixture_cases;
+mod plan_cases;
+mod register_cases;
+mod scan_cases;
+mod snapshot;
+mod surface_cases;
diff --git a/crates/core/tests/adopt/plan_cases.rs b/crates/core/tests/adopt/plan_cases.rs
new file mode 100644
index 0000000..6261664
--- /dev/null
+++ b/crates/core/tests/adopt/plan_cases.rs
@@ -0,0 +1,118 @@
+//! `plan` / `inspect` 的**只读**判据与拒绝理由：零写盘、缺父/不存在/非法目标的报错形状。
+//!
+//! 与 `register_cases` 的分工：那边验「登记写出了什么」，这边验「还没登记时算出了什么、拒绝得对不对」。
+
+use std::path::PathBuf;
+
+use unlucky_core::game::adopt::{self, AdoptError, AdoptTarget};
+use unlucky_core::game::install::instance::Isolation;
+
+use crate::fixture::{
+    assert_unchanged, foreign_minecraft, request, snapshot, snapshot_opt, TempRoot,
+};
+
+/// 缺省档位本身就是「数据区独立目录」，而且**不是** `isolated`（判据的单一真相源）。
+///
+/// 抓得住：把 `#[default]` 挪到 `VersionDir`/`Shared`（第一条断言红），或让缺省档映射到
+/// `Isolated`（第二条断言红）——后者正是「导入别人的版本后第一次启动就在他的 `versions//`
+/// 里长 mods/saves」的那个坑。
+/// 抓不住：CLI 是否真的用 `AdoptTarget::default()`（那条由 cli/adopt_test 的行为断言钉着）。
+#[test]
+fn the_default_target_is_an_own_dir_not_the_global_isolated_mode() {
+    let target = AdoptTarget::default();
+    assert_eq!(target, AdoptTarget::InstanceDir);
+    assert_eq!(target.as_str(), "instance_dir");
+    assert_eq!(target.isolation(), Isolation::Custom);
+    assert_ne!(target.isolation(), Isolation::Isolated);
+}
+
+/// `--isolation custom --game-dir <相对路径>` ⇒ 明确报错（不猜、不悄悄改成绝对路径）。
+///
+/// 抓得住：相对路径被默默接受（`TargetInvalid` 变成成功）。
+/// 抓不住：Windows 上 `C:foo` 这种「带盘符但非绝对」的形状，只看 `is_absolute`。
+#[test]
+fn custom_target_requires_an_absolute_directory() {
+    let root = TempRoot::new("custom-rel");
+    foreign_minecraft(&root.game_root());
+    let error = adopt::adopt(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::Custom(PathBuf::from("relative/dir"))),
+    )
+    .expect_err("相对路径应被拒");
+    assert_eq!(error.code(), "adopt_target_invalid");
+    assert!(error.to_string().contains("绝对路径"), "{error}");
+}
+
+/// `--dry-run` 的 core 形态（`plan`）：一个文件都不写、目录也不建。
+///
+/// 抓得住：`plan` 顺手建了运行目录或写了档案（两种断言都会红）。
+/// 抓不住：CLI 的 `--dry-run` 是否真的只调 `plan`（那条在 cli 侧用例里）。
+#[test]
+fn plan_writes_nothing_at_all() {
+    let root = TempRoot::new("plan");
+    foreign_minecraft(&root.game_root());
+    let before = snapshot(root.path());
+
+    let plan = adopt::plan(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::InstanceDir),
+    )
+    .expect("计划应成功");
+    let after = snapshot(root.path());
+    assert_unchanged(&before, &after, "plan 之后（含 .ULL）");
+
+    assert!(plan.candidate.adoptable());
+    assert!(!plan.run_dir.exists(), "plan 不该建目录");
+    // `.ULL` 连**空目录**都不许出现（存在性用 `snapshot_opt`，与「空树」区分开）。
+    assert!(
+        snapshot_opt(&root.path().join(".ULL")).is_none(),
+        "plan 不该建配置目录（连空的也不行）"
+    );
+}
+
+/// 不可登记的版本（缺父）⇒ 一条都不登记，问题清单原样带出。
+///
+/// 抓得住：缺父的版本被登记（启动必失败却显示「导入成功」）、问题被折叠成一句空话。
+/// 抓不住：用户在原来的启动器里修好之后重试（那条由重试路径自然覆盖）。
+#[test]
+fn not_adoptable_versions_are_refused_with_their_reasons() {
+    let root = TempRoot::new("refuse");
+    foreign_minecraft(&root.game_root());
+    let error = adopt::adopt(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1-orphan", AdoptTarget::InstanceDir),
+    )
+    .expect_err("缺父版本应被拒");
+    assert_eq!(error.code(), "adopt_not_adoptable");
+    let codes: Vec<&str> = error
+        .problems()
+        .iter()
+        .map(|problem| problem.code())
+        .collect();
+    assert_eq!(codes, vec!["missing_parent"]);
+    assert!(
+        !root.path().join(".ULL/config/profiles.json").exists(),
+        "拒绝时不许留档案"
+    );
+}
+
+/// 不存在的版本 ⇒ `adopt_version_not_found`（不是「帮你在网上下一个」）。
+///
+/// 抓得住：不存在的 id 被当成可登记（档案指向空版本）。
+/// 抓不住：`versions/` 整个不存在的情形（上一条扫描用例覆盖）。
+#[test]
+fn an_unknown_version_is_reported_as_not_found() {
+    let root = TempRoot::new("unknown");
+    foreign_minecraft(&root.game_root());
+    let error = adopt::adopt(
+        &root.game(),
+        &root.launcher(),
+        &request("9.9.9", AdoptTarget::InstanceDir),
+    )
+    .expect_err("不存在的版本应报错");
+    assert!(matches!(error, AdoptError::UnknownVersion { .. }));
+    assert_eq!(error.code(), "adopt_version_not_found");
+}
diff --git a/crates/core/tests/adopt/register_cases.rs b/crates/core/tests/adopt/register_cases.rs
new file mode 100644
index 0000000..4d74e95
--- /dev/null
+++ b/crates/core/tests/adopt/register_cases.rs
@@ -0,0 +1,298 @@
+//! `plan` / `adopt` 的落点与写盘面：登记只写自己的配置，外部 `.minecraft` 一个字节都不动。
+//!
+//! 每条用例都带「抓得住 / 抓不住」，并且**外部快照断言**是每条的核心：`versions/`
+//! `libraries/` `assets/` `mods/` `saves/` `config/` `launcher_profiles.json` 的路径集合、
+//! 字节数、内容哈希、mtime 全都不许变（`fixture::assert_unchanged`）。
+
+use unlucky_core::game::adopt::{self, AdoptTarget};
+use unlucky_core::game::install::instance::{read_instance_config, read_profiles, Isolation};
+use unlucky_core::game::isolation::{derive_game_dir, IsolationMode};
+
+use crate::fixture::{assert_unchanged, foreign_minecraft, request, snapshot, TempRoot};
+
+/// 缺省（不给 `--isolation`）：运行目录落 ULL 数据区的独立目录，隔离档写 `custom`。
+///
+/// 抓得住：缺省沿用全局 `isolated`（那样 `run_dir` 会变成 `versions/1.20.1`）、
+/// `gameDir` 没落盘、外部文件被写（哈希/mtime 断言）、profiles 没登记。
+/// 抓不住：真实启动是否真的把 `--gameDir` 用上（core 侧只验派生结果，CLI 侧用 `launch --dry-run` 验）。
+#[test]
+fn default_target_lands_in_the_launcher_data_area() {
+    let root = TempRoot::new("default");
+    foreign_minecraft(&root.game_root());
+    let before = snapshot(&root.game_root());
+
+    let outcome = adopt::adopt(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::InstanceDir),
+    )
+    .expect("登记应成功");
+    let after = snapshot(&root.game_root());
+    assert_unchanged(&before, &after, "缺省登记之后");
+
+    assert_eq!(outcome.isolation, Isolation::Custom);
+    assert!(outcome.created);
+    assert!(outcome.dir_created, "缺省目录应被新建");
+    let instances_dir = root.path().join(".ULL/data/instances");
+    assert!(
+        outcome.run_dir.starts_with(&instances_dir),
+        "运行目录必须在 ULL 数据区：{}",
+        outcome.run_dir.display()
+    );
+    assert!(outcome.run_dir.is_dir());
+    assert!(
+        !outcome.run_dir.starts_with(root.game_root()),
+        "缺省运行目录不许落在别人的 .minecraft 里"
+    );
+
+    // 落盘的三样东西：profiles.json、实例设置、新建的空运行目录。
+    let profiles = read_profiles(&root.launcher()).expect("读档案");
+    assert_eq!(profiles.profiles.len(), 1);
+    assert_eq!(profiles.profiles[0].name, "1.20.1");
+    assert_eq!(profiles.profiles[0].version_id, "1.20.1");
+    let config = read_instance_config(&root.launcher(), &outcome.instance_id)
+        .expect("读设置")
+        .expect("设置文件存在");
+    assert_eq!(config.isolation, Some(Isolation::Custom));
+    assert_eq!(config.game_dir.as_deref(), Some(outcome.run_dir.as_path()));
+
+    // 启动时 `--gameDir` 真的会取这个目录（D20 覆盖链的权威求值）。
+    let derivation = derive_game_dir(
+        &root.game(),
+        "1.20.1",
+        IsolationMode::Isolated,
+        Some(&config),
+        None,
+    )
+    .expect("派生运行目录");
+    assert_eq!(derivation.game_dir, outcome.run_dir);
+    assert_eq!(derivation.isolation, Isolation::Custom);
+}
+
+/// `--isolation shared`：运行目录 = 别人的游戏根，且**人读提示必须说出后果**。
+///
+/// 抓得住：shared 档被当成 custom 写 `game_dir`、提示里没提「共用/别人的 .minecraft」、
+/// 登记过程往游戏根写了东西（哈希断言）。
+/// 抓不住：用户是否真的读到了这句提示（那属于 UI 验收）。
+#[test]
+fn shared_target_points_at_the_game_root_and_says_what_it_means() {
+    let root = TempRoot::new("shared");
+    foreign_minecraft(&root.game_root());
+    let before = snapshot(&root.game_root());
+
+    let outcome = adopt::adopt(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::Shared),
+    )
+    .expect("登记应成功");
+    let after = snapshot(&root.game_root());
+    assert_unchanged(&before, &after, "shared 登记之后");
+
+    assert_eq!(outcome.isolation, Isolation::Shared);
+    assert_eq!(outcome.run_dir, root.game_root());
+    assert!(
+        outcome.notes.iter().any(|note| note.contains("共用")),
+        "必须告知「共用别人的 .minecraft」：{:?}",
+        outcome.notes
+    );
+    let config = read_instance_config(&root.launcher(), &outcome.instance_id)
+        .expect("读设置")
+        .expect("设置文件存在");
+    assert_eq!(config.isolation, Some(Isolation::Shared));
+    assert_eq!(config.game_dir, None, "shared 档不该固化成 custom");
+}
+
+/// `--isolation isolated`：运行目录 = `versions/`，**登记这一刻仍不往那里写任何东西**。
+///
+/// 抓得住：`VersionDir` 被漏做（`isolation` 不是 `Isolated`）、提示里没提「会新增玩家数据」、
+/// 登记当场就在版本目录里建了 `mods/`（下面的目录内容断言会红）。
+/// 抓不住：首次启动之后游戏自己往里写（那是启动链路的事，本 mission 不跑真游戏）。
+#[test]
+fn version_dir_target_is_explicit_and_writes_nothing_yet() {
+    let root = TempRoot::new("isolated");
+    foreign_minecraft(&root.game_root());
+    let before = snapshot(&root.game_root());
+
+    let outcome = adopt::adopt(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::VersionDir),
+    )
+    .expect("登记应成功");
+    let after = snapshot(&root.game_root());
+    assert_unchanged(&before, &after, "isolated 登记之后");
+
+    assert_eq!(outcome.isolation, Isolation::Isolated);
+    assert_eq!(outcome.run_dir, root.game_root().join("versions/1.20.1"));
+    assert!(
+        outcome.notes.iter().any(|note| note.contains("新增")),
+        "必须告知「第一次启动会在这里新增玩家数据」：{:?}",
+        outcome.notes
+    );
+    assert!(!outcome.dir_created, "版本目录已存在，不该新建");
+    let mut entries: Vec = std::fs::read_dir(&outcome.run_dir)
+        .expect("读版本目录")
+        .filter_map(|entry| Some(entry.ok()?.file_name().to_string_lossy().into_owned()))
+        .collect();
+    entries.sort();
+    assert_eq!(
+        entries,
+        vec!["1.20.1.jar".to_string(), "1.20.1.json".to_string()],
+        "版本目录里不该多出任何东西"
+    );
+}
+
+/// 展示名已被别的实例占用 ⇒ 显式报错，不改任何档案（不静默复用别的版本）。
+///
+/// 抓得住：`register` 的幂等复用路径被当成「导入成功」（那样第二个版本会指向第一个实例的档案）。
+/// 抓不住：CLI 的 hint 文案（那条在 cli 侧用例里）。
+#[test]
+fn a_taken_name_is_an_explicit_error() {
+    let root = TempRoot::new("dupname");
+    foreign_minecraft(&root.game_root());
+    adopt::adopt(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::InstanceDir),
+    )
+    .expect("第一个登记成功");
+    let profiles_before =
+        std::fs::read(root.path().join(".ULL/config/profiles.json")).expect("读档案");
+
+    let mut second = request("1.20.1-fabric-0.15.0", AdoptTarget::InstanceDir);
+    second.name = Some("1.20.1".to_string());
+    let error = adopt::adopt(&root.game(), &root.launcher(), &second).expect_err("重名应被拒");
+    assert_eq!(error.code(), "adopt_duplicate_name");
+    let profiles_after =
+        std::fs::read(root.path().join(".ULL/config/profiles.json")).expect("读档案");
+    assert_eq!(profiles_before, profiles_after, "失败不许改档案");
+}
+
+/// 同一个版本重复登记 ⇒ 无副作用失败（`adopt_already_registered`），档案逐字节不变。
+///
+/// 抓得住：重复登记变成「静默成功」（第二条断言会红），或失败时仍改写了档案。
+/// 抓不住：并发两次 adopt 的竞态（没有锁；本命令不是并发入口，如实记在这里）。
+#[test]
+fn repeating_the_same_adopt_fails_without_side_effects() {
+    let root = TempRoot::new("repeat");
+    foreign_minecraft(&root.game_root());
+    adopt::adopt(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::InstanceDir),
+    )
+    .expect("第一次登记成功");
+    let config_dir = root.path().join(".ULL/config");
+    let before = snapshot(&config_dir);
+
+    let error = adopt::adopt(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::InstanceDir),
+    )
+    .expect_err("重复登记应报错");
+    assert_eq!(error.code(), "adopt_already_registered");
+    let after = snapshot(&config_dir);
+    assert_unchanged(&before, &after, "重复登记失败之后");
+}
+
+/// 缺省运行目录已存在且非空 ⇒ 拒绝（不猜「合并进已有实例」，不覆盖用户内容）。
+///
+/// 抓得住：非空目录被复用（内容被游戏写进去只是时间问题）、拒绝时仍写了档案。
+/// 抓不住：空目录复用那条正向路径（见下一条用例）。
+#[test]
+fn a_non_empty_default_run_dir_is_refused() {
+    let root = TempRoot::new("occupied");
+    foreign_minecraft(&root.game_root());
+    let plan = adopt::plan(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::InstanceDir),
+    )
+    .expect("先算一次落点");
+    std::fs::create_dir_all(&plan.run_dir).expect("建目录");
+    std::fs::write(plan.run_dir.join("someone-elses-file.txt"), b"keep me").expect("写文件");
+
+    let error = adopt::adopt(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::InstanceDir),
+    )
+    .expect_err("非空目录应被拒");
+    assert_eq!(error.code(), "adopt_target_not_empty");
+    assert_eq!(
+        std::fs::read(plan.run_dir.join("someone-elses-file.txt")).expect("读文件"),
+        b"keep me"
+    );
+    assert!(
+        !root.path().join(".ULL/config/profiles.json").exists(),
+        "拒绝时不许留档案"
+    );
+}
+
+/// 缺省运行目录存在但**为空** ⇒ 复用（上次失败的残留不该让用户永远重试不了）。
+///
+/// 抓得住：空目录也被拒（那就把「先建目录再登记」这条路堵死了）。
+/// 抓不住：目录里的隐藏文件（`read_dir` 能看见，但平台差异在这里没覆盖）。
+#[test]
+fn an_empty_default_run_dir_is_reused() {
+    let root = TempRoot::new("empty-dir");
+    foreign_minecraft(&root.game_root());
+    let plan = adopt::plan(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::InstanceDir),
+    )
+    .expect("先算一次落点");
+    std::fs::create_dir_all(&plan.run_dir).expect("建空目录");
+
+    let outcome = adopt::adopt(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::InstanceDir),
+    )
+    .expect("空目录可复用");
+    assert!(!outcome.dir_created, "已存在的空目录不算新建");
+    assert_eq!(outcome.run_dir, plan.run_dir);
+}
+
+/// 数据区里预先放了指向外部的目录联接 ⇒ 缺省运行目录拒绝沿它写盘。
+///
+/// 抓得住：`create_dir_all` 直接沿联接在数据根之外建目录（外部会多出条目，最后一条断言红），
+/// 或错误码不是 `adopt_target_invalid`。
+/// 抓不住：数据根**自己**是链接的情形——那是用户的数据目录迁移手法，允许（判据是落点仍在
+/// 解析后的数据根内）；也抓不住检查与建目录之间的 TOCTOU。
+#[cfg(windows)]
+#[test]
+fn a_junction_inside_the_data_area_does_not_get_written_through() {
+    let root = TempRoot::new("datajunction");
+    foreign_minecraft(&root.game_root());
+    let outside = root.path().join("outside-instances");
+    std::fs::create_dir_all(&outside).expect("建外部目录");
+    // 逐段 join：`mklink` 把正斜杠当开关，拼成一串带 `/` 的路径会被判「无效参数」。
+    let data_instances = root.path().join(".ULL").join("data").join("instances");
+    std::fs::create_dir_all(data_instances.parent().expect("父目录")).expect("建 data 目录");
+    if !crate::fixture::link_guard(
+        crate::fixture::try_junction(&outside, &data_instances),
+        "数据区目录联接",
+    ) {
+        return;
+    }
+
+    let error = adopt::adopt(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::InstanceDir),
+    )
+    .expect_err("数据区里的联接必须被拒");
+    assert_eq!(error.code(), "adopt_target_invalid", "{error}");
+    let entries: Vec = std::fs::read_dir(&outside)
+        .expect("读外部目录")
+        .filter_map(|entry| Some(entry.ok()?.file_name().to_string_lossy().into_owned()))
+        .collect();
+    assert!(
+        entries.is_empty(),
+        "不许沿联接在数据根之外建目录：{entries:?}"
+    );
+}
diff --git a/crates/core/tests/adopt/scan_cases.rs b/crates/core/tests/adopt/scan_cases.rs
new file mode 100644
index 0000000..a8d8e96
--- /dev/null
+++ b/crates/core/tests/adopt/scan_cases.rs
@@ -0,0 +1,347 @@
+//! `scan` / `inspect` 的判据：正常版本能不能过、坏东西是不是**逐条**说清楚。
+//!
+//! 每条断言下面都标了「抓得住 / 抓不住」：抓得住的是变异实现会变红的具体结论，
+//! 抓不住的是只能靠人读的东西（措辞、是否还有别的静默吞掉路径）。
+
+use unlucky_core::game::adopt::{self, AdoptCandidate};
+
+use crate::fixture::{assert_unchanged, foreign_minecraft, snapshot, TempRoot};
+
+/// 扫一次并按 id 取候选（`inspect` 对不合格候选返回 `Err`，扫描则逐项列出，断言更好写）。
+fn candidate_of(root: &TempRoot, version_id: &str) -> AdoptCandidate {
+    let scan = adopt::scan(&root.game(), &root.launcher()).expect("扫描应成功");
+    scan.candidates
+        .into_iter()
+        .find(|candidate| candidate.version_id == version_id)
+        .unwrap_or_else(|| panic!("扫描里没有 {version_id}"))
+}
+
+/// 正常 / 缺清单 / 坏 JSON / 缺父 / 成环：一次扫描把每个候选的结论都说出来。
+///
+/// 抓得住：`scan` 把坏东西当空列表（`candidates` 少项就红）、漏掉父链（`inherits` 长度变）、
+/// 缺父被当成可登记（`adoptable` 变真）、成环没被检出（`cycle-*` 会变可登记）。
+/// 抓不住：问题文案的措辞，以及 `versions/` 之外的地方有没有被读写（由下面的哈希断言覆盖）。
+#[test]
+fn scan_reports_every_version_with_its_reason() {
+    let root = TempRoot::new("scan");
+    foreign_minecraft(&root.game_root());
+    let before = snapshot(root.path());
+
+    let scan = adopt::scan(&root.game(), &root.launcher()).expect("扫描应成功");
+    let after = snapshot(root.path());
+    assert_unchanged(&before, &after, "scan 之后");
+
+    let ids: Vec<&str> = scan
+        .candidates
+        .iter()
+        .map(|candidate| candidate.version_id.as_str())
+        .collect();
+    assert_eq!(
+        ids,
+        vec![
+            "1.20.1",
+            "1.20.1-broken",
+            "1.20.1-fabric-0.15.0",
+            "1.20.1-nomanifest",
+            "1.20.1-orphan",
+            "cycle-a",
+            "cycle-b",
+        ],
+        "扫描必须列出每一个目录（含不可登记的），不能少一行"
+    );
+
+    let by_id = |id: &str| {
+        scan.candidates
+            .iter()
+            .find(|candidate| candidate.version_id == id)
+            .unwrap_or_else(|| panic!("缺候选 {id}"))
+    };
+
+    let vanilla = by_id("1.20.1");
+    assert!(
+        vanilla.adoptable(),
+        "正常版本应可登记：{:?}",
+        vanilla.problems
+    );
+    assert!(vanilla.jar_present);
+    assert_eq!(vanilla.inherits, vec!["1.20.1"]);
+    assert!(!vanilla.is_registered());
+
+    let fabric = by_id("1.20.1-fabric-0.15.0");
+    assert!(fabric.adoptable(), "{:?}", fabric.problems);
+    assert!(!fabric.jar_present, "fabric 版本自己没有 jar");
+    assert_eq!(
+        fabric.inherits,
+        vec!["1.20.1-fabric-0.15.0", "1.20.1"],
+        "父链必须走到底"
+    );
+
+    let codes = |id: &str| -> Vec<&'static str> {
+        by_id(id)
+            .problems
+            .iter()
+            .map(|problem| problem.code())
+            .collect()
+    };
+    assert_eq!(codes("1.20.1-broken"), vec!["manifest_invalid_json"]);
+    assert_eq!(codes("1.20.1-nomanifest"), vec!["manifest_missing"]);
+    assert_eq!(codes("1.20.1-orphan"), vec!["missing_parent"]);
+    assert_eq!(codes("cycle-a"), vec!["circular_inheritance"]);
+    assert_eq!(codes("cycle-b"), vec!["circular_inheritance"]);
+    for id in ["1.20.1-broken", "1.20.1-orphan", "cycle-a"] {
+        assert!(!by_id(id).adoptable(), "{id} 不该被判成可登记");
+    }
+}
+
+/// 缺父要说清**缺哪个**、成环要说清**环长什么样**（不是一句「继承有问题」）。
+///
+/// 抓得住：`MissingParent` 丢了 `parent` 字段、环链只剩最后一个 id（两个都会被下面的 contains 抓到）。
+/// 抓不住：错误码是否被 CLI 原样透出（那条在 cli/tests/adopt_test 里）。
+#[test]
+fn missing_parent_and_cycle_name_what_is_wrong() {
+    let root = TempRoot::new("chain");
+    foreign_minecraft(&root.game_root());
+    let scan = adopt::scan(&root.game(), &root.launcher()).expect("扫描应成功");
+    let problems = |id: &str| {
+        scan.candidates
+            .iter()
+            .find(|candidate| candidate.version_id == id)
+            .expect("有候选")
+            .problems
+            .clone()
+    };
+
+    let orphan = problems("1.20.1-orphan");
+    let message = orphan.first().expect("一条问题").to_string();
+    assert!(message.contains("1.20.1-not-on-disk"), "{message}");
+    assert!(message.contains("1.20.1-orphan"), "{message}");
+
+    let cycle = problems("cycle-a");
+    let message = cycle.first().expect("一条问题").to_string();
+    assert!(message.contains("cycle-a"), "{message}");
+    assert!(message.contains("cycle-b"), "{message}");
+}
+
+/// 坏 JSON 要带**行列号**（用户才知道去改哪一行）。
+///
+/// 抓得住：把 serde 的错误文本换成一句「解析失败」（`line` 就没了）。
+/// 抓不住：具体行列号对不对（不同 serde_json 版本的措辞会变，只断言关键字）。
+#[test]
+fn broken_json_message_carries_a_line_number() {
+    let root = TempRoot::new("badjson");
+    foreign_minecraft(&root.game_root());
+    let candidate = candidate_of(&root, "1.20.1-broken");
+    let message = candidate.problems.first().expect("一条问题").to_string();
+    assert!(message.contains("line"), "{message}");
+    assert!(message.contains("1.20.1-broken"), "{message}");
+}
+
+/// 清单 `id` 与目录名不一致 ⇒ 拒绝（启动时会按清单 id 找 jar，必然找不到）。
+///
+/// 抓得住：去掉 `ManifestIdMismatch` 这条判据后，这个版本会变成「可登记」。
+/// 抓不住：真实启动是否真的失败（那需要真跑游戏，本 mission 不做）。
+#[test]
+fn manifest_id_must_match_the_directory_name() {
+    let root = TempRoot::new("idmismatch");
+    foreign_minecraft(&root.game_root());
+    let dir = root.game_root().join("versions/1.20.1-copy");
+    std::fs::create_dir_all(&dir).expect("建目录");
+    std::fs::write(
+        dir.join("1.20.1-copy.json"),
+        br#"{"id":"1.20.1","type":"release","mainClass":"x","libraries":[]}"#,
+    )
+    .expect("写清单");
+    std::fs::write(dir.join("1.20.1-copy.jar"), b"jar").expect("写 jar");
+
+    let candidate = candidate_of(&root, "1.20.1-copy");
+    let codes: Vec<&str> = candidate
+        .problems
+        .iter()
+        .map(|problem| problem.code())
+        .collect();
+    assert_eq!(codes, vec!["manifest_id_mismatch"]);
+}
+
+/// 版本 id 不能当路径用（`../` / 盘符 / 结尾点号）⇒ 一条结构化问题，不去碰盘。
+///
+/// 抓得住：删掉 id 校验后 `inspect("../escape")` 会去读游戏根之外的路径（下面断言问题码）。
+/// 抓不住：Windows 大小写不敏感之类的平台细节（与判据无关）。
+#[test]
+fn version_ids_that_cannot_be_paths_are_rejected() {
+    let root = TempRoot::new("badid");
+    foreign_minecraft(&root.game_root());
+    let escape = root.path().join("outside");
+    std::fs::create_dir_all(escape.join("1.20.1")).expect("建外部同名目录");
+    std::fs::write(
+        escape.join("1.20.1/1.20.1.json"),
+        br#"{"id":"1.20.1","type":"release","mainClass":"x","libraries":[]}"#,
+    )
+    .expect("写外部清单");
+
+    // `versions/../../outside/1.20.1` 这种形状：目录真的存在（能解析出去），但 id 里含分隔符。
+    let error = adopt::inspect(&root.game(), &root.launcher(), "../../outside/1.20.1")
+        .expect_err("非法 id 应报错，而不是去读游戏根之外的目录");
+    assert_eq!(error.code(), "adopt_not_adoptable");
+    let codes: Vec<&str> = error
+        .problems()
+        .iter()
+        .map(|problem| problem.code())
+        .collect();
+    assert_eq!(codes, vec!["version_id_invalid"], "{error}");
+
+    for bad in ["1.20.1.", "1.20.1 ", "C:", "a/b"] {
+        let error =
+            adopt::inspect(&root.game(), &root.launcher(), bad).expect_err("非法 id 应报错");
+        assert!(
+            error
+                .problems()
+                .iter()
+                .any(|problem| problem.code() == "version_id_invalid"),
+            "{bad:?} 应被当成非法 id：{error}"
+        );
+    }
+}
+
+/// 版本目录是指向游戏根**之外**的符号链接 ⇒ 拒绝不跟随（也不读它）。
+///
+/// 抓得住：`ensure_inside` 不比较解析后的真实路径（那样 `1.20.1-link` 会变成「可登记」）。
+/// 抓不住 / 已知局限：
+/// - 本机不允许建符号链接（Windows 未开开发者模式、或非管理员）时这条会打印 `[link-guard]`
+///   并**跳过**——显式记录而不是静静通过；设 `ULL_ADOPT_TEST_SYMLINK_REQUIRE=1` 则建不出来**必红**；
+/// - 目录联接（junction）由下面单独那条用例覆盖（不需要管理员权限，是更常见的形态）。
+#[test]
+fn a_symlinked_version_pointing_outside_the_game_root_is_rejected() {
+    let root = TempRoot::new("symlink");
+    foreign_minecraft(&root.game_root());
+    let outside = root.path().join("other-launcher");
+    std::fs::create_dir_all(outside.join("1.20.1")).expect("建外部版本目录");
+    std::fs::write(
+        outside.join("1.20.1/1.20.1.json"),
+        br#"{"id":"1.20.1","type":"release","mainClass":"x","libraries":[]}"#,
+    )
+    .expect("写外部清单");
+    let link = root.game_root().join("versions/1.20.1-link");
+    // 建不出来时：非强制模式打印一行并跳过；`ULL_ADOPT_TEST_SYMLINK_REQUIRE=1` 必红（R4）。
+    if !crate::fixture::link_guard(
+        crate::fixture::try_symlink_dir(&outside.join("1.20.1"), &link),
+        "根外符号链接",
+    ) {
+        return;
+    }
+
+    let candidate = candidate_of(&root, "1.20.1-link");
+    let codes: Vec<&str> = candidate
+        .problems
+        .iter()
+        .map(|problem| problem.code())
+        .collect();
+    assert!(
+        codes.contains(&"outside_game_root"),
+        "越界链接必须被点名：{codes:?}"
+    );
+    assert!(!candidate.adoptable(), "越界链接的版本不许登记");
+}
+
+/// 游戏根内的符号链接（指向同一棵树里的真实版本目录）**不**拒绝：那是合法的省盘做法。
+///
+/// 抓得住：`check_symlink` 一刀切拒绝所有符号链接（这条会红）。
+/// 抓不住：本机建不出链接时同上跳过（打印 `[link-guard]`，强制模式下必红）。
+#[test]
+fn a_symlink_inside_the_game_root_is_allowed() {
+    let root = TempRoot::new("symlink-in");
+    foreign_minecraft(&root.game_root());
+    // 真实版本目录放在根内的 `hidden/` 下（清单 id 与目录名一致），再在 `versions/` 里挂一条链接。
+    let real = root.game_root().join("hidden/1.20.1-thin");
+    std::fs::create_dir_all(&real).expect("建真实版本目录");
+    std::fs::write(
+        real.join("1.20.1-thin.json"),
+        br#"{"id":"1.20.1-thin","type":"release","mainClass":"x","libraries":[]}"#,
+    )
+    .expect("写清单");
+    let link = root.game_root().join("versions/1.20.1-thin");
+    if !crate::fixture::link_guard(
+        crate::fixture::try_symlink_dir(&real, &link),
+        "根内符号链接",
+    ) {
+        return;
+    }
+    let candidate = candidate_of(&root, "1.20.1-thin");
+    assert!(
+        candidate.adoptable(),
+        "根内链接不该被拒：{:?}",
+        candidate.problems
+    );
+}
+
+/// `versions/` 不存在 = 空结果（新数据根不是错误），但**不存在的游戏根不会被建出来**。
+///
+/// 抓得住：`scan` 顺手 `create_dir_all(versions)`（下面的断言会红），或把「不存在」当错误。
+/// 抓不住：读目录失败（ENOTDIR/EACCES）那条分支——真造一个不可读目录在 Windows 上不可靠，
+/// 那一条由代码审读把关。
+#[test]
+fn a_missing_versions_dir_is_empty_not_an_error() {
+    let root = TempRoot::new("noversions");
+    let scan = adopt::scan(&root.game(), &root.launcher()).expect("应成功");
+    assert!(scan.candidates.is_empty());
+    assert!(
+        !root.game_root().exists(),
+        "扫描不该顺手建游戏根目录：{}",
+        root.game_root().display()
+    );
+}
+
+/// Windows 目录联接（junction）指向根外 ⇒ **同样**拒绝，而且不去读那个目录。
+///
+/// 为什么要单列：junction 不是 `is_symlink`，只看链接类型的实现会放行它——而 junction
+/// **不需要管理员权限**就能建，是把别人版本目录挂进 `versions/` 最常见的形态。
+///
+/// 抓得住：
+/// - 判据退回 `is_symlink`（除 Windows junction 外全都看不到，此时候选会变成「可登记」，第一条断言红）；
+/// - 判据排到**解析清单之后**：根外那份清单是合法 JSON 且 id 与目录名一致，一旦走到解析，
+///   `manifest_id` 就会被填上（第二条断言红）——所以它至少能证明「没解析过根外清单」；
+/// - 建不出链接时走 `fixture::link_guard`：非强制模式打印 `[link-guard]` 并跳过，
+///   强制模式（`ULL_ADOPT_TEST_SYMLINK_REQUIRE=1`）**必红**（真值表见 `fixture::link_gate_truth_table`）。
+///
+/// 抓不住（证据边界，别把它读大）：**只 stat/只 open 不解析**的读取这里看不出来
+/// （`manifest_id` 为 `None` 只说明没解析过，不说明没碰过文件）；「边界检查排在
+/// `read_manifest` 之前」这条由 `inspect.rs::check` 的代码顺序保证，靠人读。
+/// 也抓不住检查与读取之间的 TOCTOU（本模块不是并发/对抗入口）。
+#[cfg(windows)]
+#[test]
+fn a_junction_pointing_outside_is_rejected_without_reading_it() {
+    let root = TempRoot::new("junction");
+    foreign_minecraft(&root.game_root());
+    // 逐段 join：`cmd` / `mklink` 会把正斜杠当开关，拼成一串带 `/` 的路径会被判「无效参数」。
+    let outside = root.path().join("other-launcher").join("1.20.1-junction");
+    std::fs::create_dir_all(&outside).expect("建外部版本目录");
+    std::fs::write(
+        outside.join("1.20.1-junction.json"),
+        br#"{"id":"1.20.1-junction","type":"release","mainClass":"x","libraries":[]}"#,
+    )
+    .expect("写外部清单");
+    let link = root.game_root().join("versions").join("1.20.1-junction");
+    if !crate::fixture::link_guard(
+        crate::fixture::try_junction(&outside, &link),
+        "根外目录联接",
+    ) {
+        return;
+    }
+
+    let candidate = candidate_of(&root, "1.20.1-junction");
+    let codes: Vec<&str> = candidate
+        .problems
+        .iter()
+        .map(|problem| problem.code())
+        .collect();
+    assert!(
+        codes.contains(&"outside_game_root"),
+        "联接越界必须被点名：{codes:?} / {:?}",
+        candidate.problems
+    );
+    assert!(!candidate.adoptable(), "越界联接的版本不许登记");
+    assert!(
+        candidate.manifest_id.is_none() && candidate.inherits.is_empty(),
+        "拒绝之后不许再读根外那份清单：{:?}",
+        candidate.manifest_id
+    );
+}
diff --git a/crates/core/tests/adopt/snapshot.rs b/crates/core/tests/adopt/snapshot.rs
new file mode 100644
index 0000000..92afb5e
--- /dev/null
+++ b/crates/core/tests/adopt/snapshot.rs
@@ -0,0 +1,180 @@
+//! 目录树**全节点**快照：目录 / 文件 / 链接各记自己的类型与适用 mtime。
+//!
+//! # 为什么不是「只记文件」
+//!
+//! 复审 r1 的 R5：早先版本遇到目录只递归、不记录，于是「登记过程凭空建了一个空目录」
+//! （例如错误地在 `/versions//mods` 里 `create_dir_all`）在快照上**完全看不出来**。
+//! 「只读外部」这条承诺必须能抓住新增/删除的**目录节点**，所以这里：
+//!
+//! - 根自身、每个目录、每个文件、每个链接都进快照（相对路径 → [`Node`]）；
+//! - 目录记 mtime（条目增删会改它），文件记字节数 + mtime + 内容哈希；
+//! - **链接不跟随**：只记目标路径（跟随会把根外的内容算进「外部树」，让越界写入看起来像「没变化」）；
+//!   Windows 的目录联接（junction）不是 `is_symlink`，这里额外用重解析点属性识别它；
+//! - 任何读盘失败都**直接失败**（`panic`），不吞成「这项没变」——吞错就是假绿。
+//!
+//! # 为什么 CLI 测试也用这一份
+//!
+//! 以前 core 与 CLI 各写一份 walk，两份都漏了目录节点（同一处缺口两遍）。现在 CLI 的
+//! `adopt_test/fixture.rs` 用 `#[path = "../../../core/tests/adopt/snapshot.rs"]` 复用本文件：
+//! **判据只有一份**，不会再次漂移。
+
+use std::collections::hash_map::DefaultHasher;
+use std::collections::BTreeMap;
+use std::hash::{Hash, Hasher};
+use std::path::{Path, PathBuf};
+use std::time::UNIX_EPOCH;
+
+/// 快照里的一个节点。
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
+pub enum Node {
+    /// 目录（只记 mtime：条目增删会改它）。
+    Dir {
+        /// mtime（纳秒；取不到记 0）。
+        mtime_ns: u128,
+    },
+    /// 文件（字节数 + mtime + 内容哈希）。
+    File {
+        /// 字节数。
+        len: u64,
+        /// mtime（纳秒）。
+        mtime_ns: u128,
+        /// 内容哈希（稳定即可，不要密码学强度）。
+        hash: u64,
+    },
+    /// 符号链接 / Windows 目录联接：只记目标，**不跟随**。
+    Link {
+        /// 链接目标（原样，可能是相对路径；读不出来时记 ``）。
+        target: PathBuf,
+    },
+}
+
+/// 一次快照：相对路径（根自身是 `.`）→ 节点。
+pub type Snapshot = BTreeMap;
+
+/// 拍一次全节点快照（目标不存在 = 空快照，见 [`snapshot_opt`] 的区分）。
+///
+/// # Panics
+///
+/// 任何目录/元数据/文件读不出来都 panic：读不出来不能当成「没变化」。
+pub fn snapshot(root: &Path) -> Snapshot {
+    snapshot_opt(root).unwrap_or_default()
+}
+
+/// 同 [`snapshot`]，但目标**不存在**时返回 `None`（用于区分「空树」与「根本没有」）。
+///
+/// # Panics
+///
+/// 同上（存在但读不出来即 panic）。
+pub fn snapshot_opt(root: &Path) -> Option {
+    match std::fs::symlink_metadata(root) {
+        Ok(_) => {}
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return None,
+        Err(error) => panic!("快照根读不出来 {}：{error}", root.display()),
+    }
+    let mut out = Snapshot::new();
+    out.insert(".".to_string(), node_of(root));
+    walk(root, root, &mut out);
+    Some(out)
+}
+
+fn walk(root: &Path, dir: &Path, out: &mut Snapshot) {
+    let entries = std::fs::read_dir(dir)
+        .unwrap_or_else(|error| panic!("目录应可读 {}：{error}", dir.display()));
+    for entry in entries {
+        let entry = entry.unwrap_or_else(|error| panic!("目录项应可读 {}：{error}", dir.display()));
+        let path = entry.path();
+        let relative = path
+            .strip_prefix(root)
+            .unwrap_or(&path)
+            .to_string_lossy()
+            .replace('\\', "/");
+        let node = node_of(&path);
+        let is_dir = matches!(node, Node::Dir { .. });
+        out.insert(relative, node);
+        if is_dir {
+            walk(root, &path, out);
+        }
+    }
+}
+
+/// 单个节点的形状（链接/联接**不跟随**）。
+fn node_of(path: &Path) -> Node {
+    let meta = std::fs::symlink_metadata(path)
+        .unwrap_or_else(|error| panic!("元数据应可读 {}：{error}", path.display()));
+    if link_like(&meta) {
+        let target =
+            std::fs::read_link(path).unwrap_or_else(|_| PathBuf::from(""));
+        return Node::Link { target };
+    }
+    let mtime_ns = meta
+        .modified()
+        .ok()
+        .and_then(|time| time.duration_since(UNIX_EPOCH).ok())
+        .map_or(0, |duration| duration.as_nanos());
+    if meta.file_type().is_dir() {
+        return Node::Dir { mtime_ns };
+    }
+    let bytes = std::fs::read(path)
+        .unwrap_or_else(|error| panic!("文件应可读 {}：{error}", path.display()));
+    Node::File {
+        len: bytes.len() as u64,
+        mtime_ns,
+        hash: hash(&bytes),
+    }
+}
+
+/// 符号链接（所有平台）或 Windows 重解析点（junction / mount point）。
+///
+/// `FileType::is_symlink` 对 junction 返回 `false`，所以 Windows 上另看
+/// `FILE_ATTRIBUTE_REPARSE_POINT`：不识别它就会把 junction 当普通目录**递归进去**，
+/// 等于跟随链接读根外内容。
+fn link_like(meta: &std::fs::Metadata) -> bool {
+    if meta.file_type().is_symlink() {
+        return true;
+    }
+    #[cfg(windows)]
+    {
+        use std::os::windows::fs::MetadataExt;
+        const FILE_ATTRIBUTE_REPARSE_POINT: u32 = 0x0400;
+        meta.file_attributes() & FILE_ATTRIBUTE_REPARSE_POINT != 0
+    }
+    #[cfg(not(windows))]
+    {
+        false
+    }
+}
+
+/// 内容哈希（只要稳定、不需要密码学强度）。
+fn hash(bytes: &[u8]) -> u64 {
+    let mut hasher = DefaultHasher::new();
+    bytes.hash(&mut hasher);
+    hasher.finish()
+}
+
+/// 断言两次快照**完全一致**：路径集合（含目录/链接）与每个节点的形状都不许变。
+///
+/// 抓得住：
+/// - 新增/删除**空目录**（目录节点进快照）、目录条目变化（目录 mtime 变）；
+/// - 文件被改写（哈希变、mtime 变）或被删（路径集合变）；
+/// - 链接目标被改（`Link.target` 变）。
+///
+/// 抓不住：只读打开（无可观测痕迹）、文件内容相同且 mtime 未被改写的「伪写」、
+/// 以及检查期间的 TOCTOU。
+///
+/// # Panics
+///
+/// 快照不一致即 panic（消息里点名第一个不同的路径）。
+pub fn assert_unchanged(before: &Snapshot, after: &Snapshot, what: &str) {
+    assert_eq!(
+        before.keys().collect::>(),
+        after.keys().collect::>(),
+        "{what}：路径集合（含目录/链接节点）变了"
+    );
+    for (path, node) in before {
+        assert_eq!(
+            node,
+            after.get(path).expect("同一路径"),
+            "{what}：节点被改动 -> {path}"
+        );
+    }
+}
diff --git a/crates/core/tests/adopt/surface_cases.rs b/crates/core/tests/adopt/surface_cases.rs
new file mode 100644
index 0000000..0e14eac
--- /dev/null
+++ b/crates/core/tests/adopt/surface_cases.rs
@@ -0,0 +1,320 @@
+//! 写盘面与入口可用性：**配置目录被链出去**必须拒绝（R2）、**versions 入口断链**必须具名报错（R3）。
+//!
+//! 两类都属于「本 mission 承诺的东西被链接绕过」：前者是「只写自己的配置」被
+//! `config/instances` 的目录联接打穿（会替别人的启动器在 `.minecraft/config` 里造 UUID 文件），
+//! 后者是「坏东西不能当空列表」被 `read_dir` 的 NotFound 打穿（断链 junction 与「真没有」同态）。
+//!
+//! 两条都用**真链接夹具**；建不出链接时走 `fixture::link_guard`（强制模式下必红，见 R4）。
+
+use unlucky_core::game::adopt::{self, AdoptTarget};
+
+use crate::fixture::{
+    assert_unchanged, foreign_minecraft, link_guard, request, snapshot, try_link_dir, TempRoot,
+};
+
+/// `config/instances` 被目录联接指到游戏根的 `config/`：adopt 必须先拒绝，且游戏根零写入。
+///
+/// 抓得住：
+/// - 只核运行目录、不核配置写面（那样这次登记会 exit0，并在 `.minecraft/config/.json`
+///   多出一个文件——`before/after` 全节点快照与「外部 config 目录为空」两条都会红）；
+/// - `plan`（dry-run）也放行（第四条断言红：预检说「可以」，真写才失败）；
+/// - 拒绝时先写了目录/配置（快照与目录列举都会红）。
+///
+/// 抓不住：检查与写入之间的 TOCTOU（本模块不是并发/对抗入口）。
+#[cfg(windows)]
+#[test]
+fn a_junction_on_the_instances_dir_must_not_write_into_the_game_root() {
+    use crate::fixture::try_junction;
+
+    let root = TempRoot::new("cfg-instances-junction");
+    foreign_minecraft(&root.game_root());
+    let game_config = root.game_root().join("config");
+    std::fs::create_dir_all(&game_config).expect("建别人的 config 目录");
+    let instances_dir = root.path().join(".ULL").join("config").join("instances");
+    std::fs::create_dir_all(instances_dir.parent().expect("config 目录")).expect("建 .ULL/config");
+    if !link_guard(
+        try_junction(&game_config, &instances_dir),
+        "config/instances 目录联接",
+    ) {
+        return;
+    }
+    let before = snapshot(&root.game_root());
+    // 别人的 `config/` 里本来就有文件（`example.toml` 是玩家配置）：判据是**没有新增条目**。
+    let config_before = listing(&game_config);
+
+    let plan_error = adopt::plan(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::InstanceDir),
+    )
+    .expect_err("配置写面被链走时，dry-run 也必须报错");
+    assert_eq!(plan_error.code(), "adopt_write_surface_in_game_tree");
+
+    let error = adopt::adopt(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::InstanceDir),
+    )
+    .expect_err("配置写面被链走时必须拒绝登记");
+    assert_eq!(error.code(), "adopt_write_surface_in_game_tree");
+
+    let after = snapshot(&root.game_root());
+    assert_unchanged(&before, &after, "拒绝之后（游戏根零写入）");
+    assert_eq!(
+        config_before,
+        listing(&game_config),
+        "绝不许在别人的 .minecraft/config 里新增文件（尤其 UUID 配置）"
+    );
+    assert!(
+        !listing(&game_config)
+            .iter()
+            .any(|name| name.ends_with(".json") && name.len() == 41),
+        "不该出现 UUID 形状的 json：{:?}",
+        listing(&game_config)
+    );
+}
+
+/// `config/` 整层被链到游戏根：同样拒绝（判定粒度到**每一个**写盘目标，不只看 `instances`）。
+///
+/// 抓得住：只检查 `config/instances` 而不检查 `config/` 与 `profiles.json`（那样这条会 exit0）。
+/// 抓不住：跨卷/跨盘的整体迁移（`<.ULL>` 自己是联接）——那是允许的，见 `run_dir` 模块文档。
+#[test]
+fn a_linked_config_dir_must_not_write_into_the_game_root() {
+    let root = TempRoot::new("cfg-dir-link");
+    foreign_minecraft(&root.game_root());
+    let game_config = root.game_root().join("config");
+    std::fs::create_dir_all(&game_config).expect("建别人的 config 目录");
+    let ull = root.path().join(".ULL");
+    std::fs::create_dir_all(&ull).expect("建 .ULL");
+    let config_dir = ull.join("config");
+    if !link_guard(try_link_dir(&game_config, &config_dir), "config 目录链接") {
+        return;
+    }
+    let before = snapshot(&root.game_root());
+
+    let error = adopt::adopt(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::InstanceDir),
+    )
+    .expect_err("config/ 被链走时必须拒绝登记");
+    assert_eq!(error.code(), "adopt_write_surface_in_game_tree");
+
+    let after = snapshot(&root.game_root());
+    assert_unchanged(&before, &after, "拒绝之后（游戏根零写入）");
+}
+
+/// `versions/` 入口**存在但断链**（目标被移走）⇒ 具名报错，而不是「这个数据根还没有版本」。
+///
+/// 抓得住：`read_dir` 的 `NotFound` 一律当空列表（旧实现；Windows 断链 junction 正是这个形状）
+/// ——第一条断言会红成「成功空列表」。
+/// 抓不住：`versions/` 是普通文件的情形（走 `GameError::io`，错误码不同，靠人读）。
+#[test]
+fn a_dangling_versions_entry_is_an_error_not_an_empty_scan() {
+    let root = TempRoot::new("dangling-versions");
+    std::fs::create_dir_all(root.game_root()).expect("建游戏根");
+    let moved = root.path().join("moved-versions");
+    std::fs::create_dir_all(moved.join("1.20.1")).expect("建将被移走的 versions");
+    let versions = root.game_root().join("versions");
+    if !link_guard(try_link_dir(&moved, &versions), "versions 入口链接") {
+        return;
+    }
+    // 目标被移走 ⇒ 入口成为断链；lstat 仍然看得见它。
+    std::fs::remove_dir_all(&moved).expect("移走目标");
+    assert!(
+        std::fs::symlink_metadata(&versions).is_ok(),
+        "夹具有问题：断链入口应当仍能被 lstat 看到"
+    );
+
+    let error = adopt::scan(&root.game(), &root.launcher())
+        .expect_err("断链的 versions 入口必须报错，不能当空列表");
+    assert_eq!(error.code(), "adopt_versions_unreadable", "{error}");
+}
+
+/// `versions` 真不存在 ⇒ 仍然是空结果（别把「新数据根」误报成故障）。
+///
+/// 抓得住：为了修 R3 把所有 NotFound 都当错误（这条会红）。
+/// 抓不住：真正不可读（EACCES）那一支——Windows 上造不可读目录不可靠。
+#[test]
+fn a_truly_missing_versions_dir_stays_empty() {
+    let root = TempRoot::new("no-versions");
+    std::fs::create_dir_all(root.game_root()).expect("建空游戏根");
+    let scan = adopt::scan(&root.game(), &root.launcher()).expect("真不存在 ⇒ 空结果");
+    assert!(scan.candidates.is_empty());
+}
+
+/// 目录里直接子项的名字（排序后，用于「有没有新增」的判据）。
+fn listing(dir: &std::path::Path) -> Vec {
+    let mut names: Vec = std::fs::read_dir(dir)
+        .expect("读目录")
+        .filter_map(|entry| Some(entry.ok()?.file_name().to_string_lossy().into_owned()))
+        .collect();
+    names.sort();
+    names
+}
+
+/// `.ULL/data` 被预先联接到**游戏树**上 ⇒ 默认登记必须拒绝（r2 R2.2），而不是写完再说「隔离」。
+///
+/// 复审 r2 的实跑：`data -> .minecraft` 时 dry-run 与 adopt 都 exit0，外部多出
+/// `instances/` 且游戏根 mtime 变化，输出仍称「与别人的 .minecraft 隔离」。
+///
+/// 抓得住：写面重叠不核（那样这次登记会成功，游戏树快照与「外部零新增」断言都会红）；
+/// 只核配置不核 data（`data` 面上的缺省运行目录仍会落进游戏树）。
+///
+/// 抓不住：检查与写入之间的 TOCTOU；也不把「后续游戏自己写盘」算作本判据的证据。
+#[cfg(windows)]
+#[test]
+fn data_linked_into_the_game_tree_is_refused_before_any_write() {
+    use crate::fixture::try_junction;
+
+    let root = TempRoot::new("data-to-game");
+    foreign_minecraft(&root.game_root());
+    let data = root.path().join(".ULL").join("data");
+    std::fs::create_dir_all(data.parent().expect(".ULL")).expect("建 .ULL");
+    if !link_guard(try_junction(&root.game_root(), &data), "data -> 游戏树联接") {
+        return;
+    }
+    let before = snapshot(&root.game_root());
+
+    let plan_error = adopt::plan(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::InstanceDir),
+    )
+    .expect_err("dry-run 也必须拒绝与游戏树重叠的写盘面");
+    assert_eq!(plan_error.code(), "adopt_write_surface_in_game_tree");
+
+    let error = adopt::adopt(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::InstanceDir),
+    )
+    .expect_err("默认登记必须拒绝与游戏树重叠的 data 写面");
+    assert_eq!(error.code(), "adopt_write_surface_in_game_tree");
+
+    assert_unchanged(
+        &before,
+        &snapshot(&root.game_root()),
+        "拒绝之后（游戏树零写入）",
+    );
+    assert!(
+        !root.game_root().join("instances").exists(),
+        "绝不许在别人的 .minecraft 里建 instances 目录"
+    );
+}
+
+/// `.ULL` 整棵树被预先联接到游戏树 ⇒ 同样拒绝（配置 + data 一起落进游戏树）。
+///
+/// 抓得住：只核 `data` 或只核 `config/instances`（那样 `profiles.json` 与 `data/` 仍会写穿）。
+///
+/// 抓不住：`<.ULL>` 自己是链接但指向**游戏树之外**的情形——那是合法迁移，见下一条正向对照。
+#[cfg(windows)]
+#[test]
+fn home_linked_into_the_game_tree_is_refused_before_any_write() {
+    use crate::fixture::try_junction;
+
+    let root = TempRoot::new("home-to-game");
+    foreign_minecraft(&root.game_root());
+    let home = root.path().join(".ULL");
+    if !link_guard(try_junction(&root.game_root(), &home), ".ULL -> 游戏树联接") {
+        return;
+    }
+    let before = snapshot(&root.game_root());
+
+    let error = adopt::adopt(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::InstanceDir),
+    )
+    .expect_err("默认登记必须拒绝与游戏树重叠的 .ULL 写面");
+    assert_eq!(error.code(), "adopt_write_surface_in_game_tree");
+
+    assert_unchanged(
+        &before,
+        &snapshot(&root.game_root()),
+        "拒绝之后（游戏树零写入）",
+    );
+}
+
+/// **正向对照**：把 `data` 整体迁到游戏树**之外**仍然允许（迁移是合法的，重叠才拒）。
+///
+/// 抓得住：把「与游戏树重叠」写成「任何链接都拒」（这条正向用例会红）。
+/// 抓不住：迁移后的数据目录内容（只断言登记成功且游戏树不变）。
+#[test]
+fn data_migrated_outside_the_game_tree_still_registers() {
+    let root = TempRoot::new("data-outside");
+    foreign_minecraft(&root.game_root());
+    let external = root.path().join("external-data");
+    std::fs::create_dir_all(&external).expect("建外部数据目录");
+    let data = root.path().join(".ULL").join("data");
+    std::fs::create_dir_all(data.parent().expect(".ULL")).expect("建 .ULL");
+    if !link_guard(try_link_dir(&external, &data), "data -> 游戏树之外的联接") {
+        return;
+    }
+    let before = snapshot(&root.game_root());
+
+    let outcome = adopt::adopt(
+        &root.game(),
+        &root.launcher(),
+        &request("1.20.1", AdoptTarget::InstanceDir),
+    )
+    .expect("迁到游戏树之外的 data 应允许");
+    // 对外返回的是**逻辑**路径（`<.ULL>/data/instances/`），真实位置才是迁移后的目录。
+    let real = outcome.run_dir.canonicalize().expect("运行目录真实路径");
+    let external_real = external.canonicalize().expect("外部数据目录真实路径");
+    assert!(
+        real.starts_with(&external_real),
+        "运行目录的真实位置应落在迁移后的数据目录里：{}",
+        real.display()
+    );
+    assert_unchanged(
+        &before,
+        &snapshot(&root.game_root()),
+        "登记之后（游戏树零写入）",
+    );
+}
+
+/// **更高祖先断链**（r2 R2.3）：完整版本树挂在迁移联接下面，联接目标被搬走后 scan 不许报空。
+///
+/// 复审 r2 的对照：`--data-dir link/nested` 断开前 total=1；把 `link` 的目标改名后，
+/// `versions` 与游戏根本身都 NotFound，旧实现返回 `ok:true / total:0`。
+///
+/// 抓得住：只在 `versions` 与游戏根两层 lstat（更高层断链会漏，第二条断言红）；
+/// 或反过来把「真正的新数据根」也判成错误（断开**之前**那条 total==1 的断言与
+/// `a_truly_missing_versions_dir_stays_empty` 会红）。
+#[test]
+fn a_dangling_ancestor_above_the_game_root_is_not_an_empty_scan() {
+    let root = TempRoot::new("ancestor-dangling");
+    let real = root.path().join("target");
+    let game = real.join("nested").join(".minecraft");
+    std::fs::create_dir_all(game.join("versions").join("1.20.1")).expect("建完整版本树");
+    std::fs::write(
+        game.join("versions/1.20.1/1.20.1.json"),
+        br#"{"id":"1.20.1","type":"release","mainClass":"x","libraries":[]}"#,
+    )
+    .expect("写清单");
+    let link = root.path().join("game-parent-link");
+    if !link_guard(try_link_dir(&real, &link), "游戏根上层联接") {
+        return;
+    }
+    let data_root = root.path().join("data");
+    std::fs::create_dir_all(&data_root).expect("建数据根");
+    let minecraft = link.join("nested").join(".minecraft");
+    let game_layout = unlucky_core::game::GameLayout::new(&minecraft);
+    let launcher = unlucky_core::platform::layout::LauncherLayout::new(data_root.join(".ULL"));
+
+    // 断开之前：完整版本树看得见。
+    let scan = adopt::scan(&game_layout, &launcher).expect("联接完好的树应可扫");
+    assert_eq!(scan.candidates.len(), 1, "完整版本树应扫到 1 个候选");
+
+    // 断开：把联接目标改名，入口还在但解析不出来（versions 与游戏根本身都 NotFound）。
+    std::fs::rename(&real, root.path().join("moved-target")).expect("移走联接目标");
+    assert!(
+        std::fs::symlink_metadata(&link).is_ok(),
+        "夹具有问题：断链入口应仍能被 lstat 看到"
+    );
+
+    let error =
+        adopt::scan(&game_layout, &launcher).expect_err("祖先断链必须具名报错，不能当空结果");
+    assert_eq!(error.code(), "adopt_versions_unreadable", "{error}");
+}
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..de76825
--- /dev/null
+++ b/crates/core/tests/auth/main.rs
@@ -0,0 +1,23 @@
+//! `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 二义；
+//! - `microsoft_msalogin`：回环重定向 URI 没登记时的回退（M178：默认设备码、不白开监听口）；
+//! - `authlib_api`：Yggdrasil 四动作的报文级对接。
+
+mod support;
+
+mod auth_failure_journal;
+mod authlib_api;
+mod microsoft_authcode;
+mod microsoft_diagnostics;
+mod microsoft_flow;
+mod microsoft_msalogin;
+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 = 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)> {
+    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 = 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_msalogin.rs b/crates/core/tests/auth/microsoft_msalogin.rs
new file mode 100644
index 0000000..141da54
--- /dev/null
+++ b/crates/core/tests/auth/microsoft_msalogin.rs
@@ -0,0 +1,274 @@
+//! M178 守卫：微软登录在**官方产物**（应用注册里没有任何重定向 URI）上的行为。
+//!
+//! 用户 2026-11-08 实测的现象：GUI 直接走授权码流 → 授权端点回
+//! `invalid_request ... 'redirect_uri' is not valid` → 浏览器里一张 AAD 原始错误页，
+//! 启动器干等超时 ⇒ 官方产物上「微软登录」整体不可用。
+//!
+//! 本文件钉四件事（都是能给答案「能不能变红」的）：
+//!
+//! | 守卫 | 用例 | 抓到什么 |
+//! |---|---|---|
+//! | ① 回退且提示可读 | [`unregistered_redirect_falls_back_to_the_device_code`] | 回退没发生 / 原因码丢了（页面就只能画原文） |
+//! | ② 不白开监听口 | 同上 + [`device_code_default_never_opens_a_listening_port`] | 预检被挪到绑定之后（`listeners_opened` 会变 1） |
+//! | ③ 注册过就仍能走浏览器 | [`registered_loopback_still_runs_the_auth_code_flow`] | 把加速路彻底焊死（一刀切回退） |
+//! | ④ 取消不被偷偷换流 | [`user_cancel_on_the_browser_page_does_not_fall_back`] | 取消被当成失败的后退理由 |
+//!
+//! 另：**真微软登录没有在这里验**（要真人拿自己账号点一次），这里只证错误处理与回退路径。
+
+use std::sync::{Arc, Mutex};
+use std::time::Duration;
+
+use unlucky_core::auth::microsoft::{
+    AuthCodePolicy, BrowserFallbackReason, MicrosoftAuth, MicrosoftEndpoints,
+};
+use unlucky_core::auth::AuthError;
+
+use crate::support::{full_routes, AuthMock, MockReply};
+
+const CLIENT_ID: &str = "test-client-id";
+/// 授权端点对**没登记**的回环 redirect_uri 的应答（2026-11-08 实测那张页面的形状）。
+const INVALID_REDIRECT_PAGE: &str =
+    "error=invalid_request&error_description=The+provided+value+for+the+input+\
+parameter+%27redirect_uri%27+is+not+valid.+The+expected+value+is+a+URI+which+matches+a+\
++redirect+URI+registered+for+this+client+application.";
+/// 授权端点对**已登记**回环 URI 的正常应答（登录页，无拒绝字样）。
+const SIGN_IN_PAGE: &str = "Sign in to your account\
+
";
+
+/// 设备码面板里看到的 `(用户码, 回退原因码)`（跨闭包共享）。
+type Seen = Arc)>>>;
+
+fn policy(state: &str) -> AuthCodePolicy {
+    AuthCodePolicy {
+        callback_timeout: Duration::from_millis(2_000),
+        bind_attempts: 1,
+        port: None,
+        state: Some(state.to_string()),
+    }
+}
+
+/// 路由表 + 定向的 `/authorize` 应答（预检打的就是这个 path）。
+fn routes_with_authorize(reply: MockReply) -> Vec<(&'static str, Vec)> {
+    let mut routes = full_routes();
+    routes.push(("/authorize", vec![reply]));
+    routes
+}
+
+fn auth(base: &str, browser_first: bool) -> MicrosoftAuth {
+    MicrosoftAuth::new(CLIENT_ID)
+        .expect("构造")
+        .with_endpoints(MicrosoftEndpoints::all_on(base))
+        .with_poll_policy(crate::support::microsoft::fast_poll())
+        .with_authcode_policy(policy("state-abc"))
+        .with_browser_first(browser_first)
+}
+
+/// 守卫 ① + ②：没登记回环 → 回退设备码、原因码是「没登记」、**监听口一次都不开**。
+#[tokio::test]
+async fn unregistered_redirect_falls_back_to_the_device_code() {
+    let mock = AuthMock::start(routes_with_authorize(MockReply::text(
+        400,
+        INVALID_REDIRECT_PAGE,
+    )))
+    .await;
+
+    let seen: Seen = Arc::new(Mutex::new(None));
+    let seen_for_device = Arc::clone(&seen);
+    let outcome = auth(&mock.base(), true)
+        .browser_then_device_login(
+            |_prompt| panic!("没登记回环时**不许**弹浏览器（用户只会看到 AAD 错误页）"),
+            move |prompt, fallback| {
+                *seen_for_device.lock().unwrap() =
+                    Some((prompt.user_code.clone(), fallback.map(|note| note.reason)));
+            },
+        )
+        .await
+        .expect("必须回退到设备码并成功");
+
+    // ① 回退确实发生，且宿主拿到的是**结构化原因码**（页面据此出可读文案，而不是画原文）
+    let (user_code, reason) = seen.lock().unwrap().clone().expect("设备码必须被展示");
+    assert_eq!(user_code, "ABCD-1234");
+    assert_eq!(reason, Some(BrowserFallbackReason::RedirectNotRegistered));
+    assert_eq!(
+        reason.map(BrowserFallbackReason::code),
+        Some("redirect_not_registered")
+    );
+    assert_eq!(outcome.session.profile_name, "Steve");
+    let note = outcome.browser.expect("必须带回退说明");
+    assert_eq!(note.reason, BrowserFallbackReason::RedirectNotRegistered);
+    // 原文只进日志：说明里的 detail 有内容，但页面只拿码（i18n 在 app-iced 侧）。
+    assert!(!note.detail.is_empty());
+
+    // ② 预检在绑定之前：这次登录一个监听口都没开（用户机上不会出现「占了端口却没人回调」）
+    assert_eq!(
+        outcome.listeners_opened, 0,
+        "没登记回环时不许绑本地端口（预检必须在绑定之前）"
+    );
+    // ③ **报文级证据**：预检真的发出去了（授权端点收到 1 次 GET），而不是被跳过。
+    //    这条也是复审 P1-1 的回执：只要生产路径把 `browser_first` 置位，这条 GET 就会发生。
+    assert_eq!(
+        mock.bodies_on("/authorize").len(),
+        1,
+        "浏览器优先路必须真的发一次回环注册预检"
+    );
+    mock.stop();
+}
+
+/// 守卫 ②（默认路那一半）：设备码是默认，浏览器流根本没被启用 ⇒ 监听计数不涨。
+#[tokio::test]
+async fn device_code_default_never_opens_a_listening_port() {
+    let mock = AuthMock::start(full_routes()).await;
+    let device_seen = Arc::new(Mutex::new(None));
+    let device_flag = Arc::clone(&device_seen);
+
+    let outcome = auth(&mock.base(), false)
+        .browser_then_device_login(
+            |_| panic!("默认路不许碰浏览器回调"),
+            move |prompt, fallback| {
+                *device_flag.lock().unwrap() = Some(prompt.user_code.clone());
+                assert!(fallback.is_none(), "没走浏览器就不该有回退说明");
+            },
+        )
+        .await
+        .expect("设备码登录成功");
+
+    assert_eq!(
+        device_seen.lock().unwrap().clone().as_deref(),
+        Some("ABCD-1234")
+    );
+    assert!(outcome.browser.is_none());
+    assert_eq!(
+        outcome.session.profile_id,
+        crate::support::microsoft::PROFILE_ID
+    );
+    assert_eq!(outcome.listeners_opened, 0, "设备码流不许开任何本地监听口");
+    // 授权端点一次都没被请求（那正是会返回 invalid_request 的那一跳）
+    assert!(mock.bodies_on("/authorize").is_empty());
+    mock.stop();
+}
+
+/// 守卫 ③：回环**真的登记了**的时候，加速路必须还能走（否则就是把功能一刀切焊死）。
+#[tokio::test]
+async fn registered_loopback_still_runs_the_auth_code_flow() {
+    let mock = AuthMock::start(routes_with_authorize(MockReply::html(200, SIGN_IN_PAGE))).await;
+
+    let outcome = auth(&mock.base(), true)
+        .browser_then_device_login(
+            |prompt| {
+                let redirect = prompt.redirect_uri.clone();
+                tokio::spawn(async move {
+                    tokio::time::sleep(Duration::from_millis(20)).await;
+                    let url = format!("{redirect}?code=the-auth-code&state=state-abc");
+                    let response = reqwest::get(&url).await.expect("浏览器回调");
+                    assert_eq!(response.status(), 200);
+                });
+            },
+            |_prompt, _note| panic!("登记了回环就不该回退设备码"),
+        )
+        .await
+        .expect("授权码流应当走通");
+
+    assert_eq!(outcome.session.profile_name, "Steve");
+    assert!(outcome.browser.is_none(), "走通了就不该有回退说明");
+    assert_eq!(
+        outcome.listeners_opened, 1,
+        "登记了回环就应当真的绑端口（否则加速路名存实亡）"
+    );
+    // 换 token 用的是**授权码** grant（不是设备码那条）。
+    let token_bodies = mock.bodies_on("/token");
+    assert_eq!(token_bodies.len(), 1, "{token_bodies:?}");
+    assert!(token_bodies[0].contains("grant_type=authorization_code"));
+    mock.stop();
+}
+
+/// 守卫 ④：用户自己取消**不算**失败——不许偷偷换一条流继续要码。
+#[tokio::test]
+async fn user_cancel_on_the_browser_page_does_not_fall_back() {
+    let mock = AuthMock::start(routes_with_authorize(MockReply::html(200, SIGN_IN_PAGE))).await;
+    let error = auth(&mock.base(), true)
+        .browser_then_device_login(
+            |prompt| {
+                let redirect = prompt.redirect_uri.clone();
+                tokio::spawn(async move {
+                    tokio::time::sleep(Duration::from_millis(20)).await;
+                    let url = format!("{redirect}?error=access_denied&state=state-abc");
+                    let _ = reqwest::get(&url).await;
+                });
+            },
+            |_prompt, _note| panic!("用户取消后不许自动换流"),
+        )
+        .await
+        .expect_err("取消应当是最终结果");
+    assert_eq!(error, AuthError::Canceled);
+    assert!(
+        mock.bodies_on("/devicecode").is_empty(),
+        "取消之后不该再去要设备码"
+    );
+    mock.stop();
+}
+
+/// 预检问不出结论（连不上）也要回退，且原因码是「没确认」而不是「没登记」。
+#[tokio::test]
+async fn an_unreachable_precheck_falls_back_with_the_unverified_reason() {
+    // 只有授权端点指到一个必然关闭的端口：预检必然失败，而设备码那条链照常打 mock。
+    let mock = AuthMock::start(full_routes()).await;
+    let mut endpoints = MicrosoftEndpoints::all_on(&mock.base());
+    endpoints.authorize = "http://127.0.0.1:1/authorize".to_string();
+    let reason = Arc::new(Mutex::new(None));
+    let reason_flag = Arc::clone(&reason);
+    let outcome = MicrosoftAuth::new(CLIENT_ID)
+        .expect("构造")
+        .with_endpoints(endpoints)
+        .with_poll_policy(crate::support::microsoft::fast_poll())
+        .with_authcode_policy(policy("state-abc"))
+        .with_browser_first(true)
+        .browser_then_device_login(
+            |_prompt| panic!("预检失败时不许弹浏览器"),
+            move |_prompt, fallback| {
+                *reason_flag.lock().unwrap() = fallback.map(|note| note.reason);
+            },
+        )
+        .await
+        .expect("预检失败不该拦住设备码");
+    assert_eq!(
+        *reason.lock().unwrap(),
+        Some(BrowserFallbackReason::PreflightUnavailable)
+    );
+    assert_eq!(
+        outcome.browser.map(|note| note.reason),
+        Some(BrowserFallbackReason::PreflightUnavailable)
+    );
+    assert_eq!(outcome.session.profile_name, "Steve");
+    assert_eq!(outcome.listeners_opened, 0, "预检失败时不该绑端口");
+    mock.stop();
+}
+
+/// 与上两例配对：`/authorize` 回 200 但正文是 AADSTS50011 的拒绝页，也不许当「已登记」。
+#[tokio::test]
+async fn aadsts50011_page_is_not_treated_as_registered() {
+    let mock = AuthMock::start(routes_with_authorize(MockReply::text(
+        200,
+        "AADSTS50011: The redirect URI specified in the request does not match the redirect URIs configured",
+    )))
+    .await;
+    let note = Arc::new(Mutex::new(None));
+    let note_flag = Arc::clone(¬e);
+    let outcome = auth(&mock.base(), true)
+        .browser_then_device_login(
+            |_| panic!("AADSTS50011 的页面不许当已登记"),
+            move |_prompt, fallback| {
+                *note_flag.lock().unwrap() = fallback.map(|note| note.reason);
+            },
+        )
+        .await
+        .expect("回退设备码后应当成功");
+    assert_eq!(
+        *note.lock().unwrap(),
+        Some(BrowserFallbackReason::RedirectNotRegistered)
+    );
+    assert_eq!(
+        outcome.browser.map(|note| note.reason),
+        Some(BrowserFallbackReason::RedirectNotRegistered)
+    );
+    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)> {
+    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 {
+    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 = "Service unavailableblocked by gateway";
+
+/// 小间隔轮询策略（设备码轮询在测试里要秒级跑完）。
+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)> {
+    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)> {
+    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=;`
+//! 的拼接、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>>,
+    handle: tokio::task::JoinHandle<()>,
+}
+
+impl AuthMock {
+    /// 启动服务器。`routes` 是 `(path, 该 path 依次使用的应答队列)`。
+    pub async fn start(routes: Vec<(&str, Vec)>) -> Self {
+        let listener = TcpListener::bind("127.0.0.1:0").await.expect("绑定端口");
+        let addr = listener.local_addr().expect("取地址");
+        let requests: Arc>> = Arc::new(Mutex::new(Vec::new()));
+        let queues: Arc>>> = 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 {
+        self.requests
+            .lock()
+            .unwrap_or_else(|error| error.into_inner())
+            .clone()
+    }
+
+    /// 找某 path 的请求体列表。
+    pub fn bodies_on(&self, path: &str) -> Vec {
+        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>>,
+    queues: Arc>>>,
+) -> 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::().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 {
+    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/child_quiet.rs b/crates/core/tests/child_quiet.rs
new file mode 100644
index 0000000..da98240
--- /dev/null
+++ b/crates/core/tests/child_quiet.rs
@@ -0,0 +1,85 @@
+//! M213：`platform::child::quiet` 的**行为**测试（它仍是一个普通 `Command`）。
+//!
+//! 抑制窗口最容易顺手搞坏的是「`.output()` 的管道、退出码、env、错误语义」，
+//! 所以这一组用真程序把这四件事各钉一条。
+//!
+//! 源码扫描型守卫（所有 spawn 是否都经 `quiet`）在 `child_quiet_guard.rs`，
+//! 与这里分开是为了让两边都留在 400 行以内，不靠压缩论证换行数。
+
+use std::process::Command;
+
+#[test]
+fn quiet_is_a_plain_command_that_still_captures_output() {
+    // 抑制窗口不能顺手把输出吞了：`.output()` 的管道与退出码必须照旧可用。
+    let output = shell(&["echo hi"]).output().expect("spawn 失败");
+    assert!(output.status.success(), "退出码：{}", output.status);
+    assert_eq!(String::from_utf8_lossy(&output.stdout).trim(), "hi");
+}
+
+#[test]
+fn quiet_keeps_stderr_and_nonzero_exit_code() {
+    let output = shell(&["echo oops 1>&2", "exit 3"])
+        .output()
+        .expect("spawn 失败");
+    assert_eq!(output.status.code(), Some(3), "退出码没透传");
+    assert!(
+        String::from_utf8_lossy(&output.stderr).contains("oops"),
+        "stderr 没被捕获：{:?}",
+        String::from_utf8_lossy(&output.stderr),
+    );
+}
+
+#[test]
+fn quiet_keeps_env_and_args() {
+    // 走 argv 与 env 两条通道，证明 `quiet` 没把 Command 包装成别的东西。
+    let script = if cfg!(windows) {
+        "echo %ULL_QUIET_PROBE%"
+    } else {
+        "echo $ULL_QUIET_PROBE"
+    };
+    let output = shell(&[script])
+        .env("ULL_QUIET_PROBE", "m213")
+        .output()
+        .expect("spawn 失败");
+    assert!(output.status.success(), "退出码：{}", output.status);
+    assert_eq!(
+        String::from_utf8_lossy(&output.stdout).trim(),
+        "m213",
+        "参数/环境变量在构造器里丢了",
+    );
+}
+
+#[test]
+fn quiet_does_not_swallow_spawn_errors() {
+    // 找不到程序时仍然是 Err：构造器不加任何「失败即静默」的逻辑。
+    let error = unlucky_core::platform::child::quiet("ull-no-such-program-m213")
+        .output()
+        .expect_err("不存在的程序居然 spawn 成功了？");
+    assert_eq!(error.kind(), std::io::ErrorKind::NotFound);
+}
+
+/// 构造器的返回值必须能直接当 `std::process::Command` 用（下游 `run_with_timeout` 就是这么接的）。
+#[test]
+fn quiet_returns_a_std_command() {
+    fn takes_command(_: Command) {}
+    takes_command(unlucky_core::platform::child::quiet("ull-type-check-only"));
+}
+
+/// 走构造器起一个 shell，拼上本平台的「跑一段脚本」参数。
+fn shell(scripts: &[&str]) -> Command {
+    let (program, flag) = if cfg!(windows) {
+        ("cmd", "/C")
+    } else {
+        ("sh", "-c")
+    };
+    let mut command = unlucky_core::platform::child::quiet(program);
+    command.arg(flag);
+    // Windows 的 `cmd /C` 只吃一条命令行；POSIX 的 `sh -c` 同理，所以用 `&` / `;` 串起来。
+    let joined = if cfg!(windows) {
+        scripts.join(" & ")
+    } else {
+        scripts.join("; ")
+    };
+    command.arg(joined);
+    command
+}
diff --git a/crates/core/tests/child_quiet_guard.rs b/crates/core/tests/child_quiet_guard.rs
new file mode 100644
index 0000000..3f994be
--- /dev/null
+++ b/crates/core/tests/child_quiet_guard.rs
@@ -0,0 +1,400 @@
+//! M217 守卫：**整棵 `crates/` 树**里所有子进程都必须经 `platform::child::quiet` 起。
+//!
+//! M213 建它时射程只有 `crates/core/src`；用户随后报「CI 构建版启动时底下闪一个控制台」，
+//! 定位到 `app-iced/src/platform/locale.rs` 的 `reg.exe`——射程之外的漏网。M217 把根抬到
+//! `crates/`，角色路径也重写成相对 `crates/`。
+//!
+//! ## 判据（按角色，不按次数）
+//!
+//! 每一处直接构造的**文件**必须命中 [`ALLOWED_ROLES`] 里的某条角色，否则就是绕开了构造器；红的
+//! 信息是「某文件某行不属于任何角色」而不是「总数对不上 N」，所以它咬得住「随手再 spawn 一个
+//! 命令」。文件角色还钉**精确处数**；目录角色（`core/tests/` 这类）只要求至少一处，因为测试
+//! 夹具的数量是活的，钉死会变成假红。
+//!
+//! ## 抓不住什么（别当完备保证）
+//!
+//! - **别名**：只认 `Command as <别名>` 与 `type <别名> = …Command`；两跳别名、从别的模块
+//!   `pub use` 进来的别名看不见。`Command` 没有 `From`，非 `::new` 的构造暂不存在。
+//! - **注释与空白**：只剥整行 `//` 与**行首** `/*`；行尾注释里写 `Command::new`、行中开始的
+//!   跨行块注释之后那几行会**误报**（方向「宁可红」，与 P1-1 的假绿相反）。判据是字面子串，
+//!   `Command :: new(..)` 看不见（`rustfmt` 会规范回去）。
+//! - **射程**：根是 `crates/`；`packaging/*.py`、`.github/workflows/*` 里的 shell 不在内（父进程
+//!   是控制台，GUI 下不闪窗），`crates/app`（Slint 退役树，非 workspace 成员）**在**内。
+//! - **行为**：只证明「代码里没有绕开构造器」，不证明「桌面上真的没闪窗口」——本机无前台桌面，
+//!   做不到目视验证（见 M217 报告）。
+//!
+//! ## 变异验证（全部实测过并已还原，只改实现侧）
+//!
+//! M213（射程还是 `crates/core/src`）：①`download/region_system.rs` 塞裸 `tzutil` ⇒ 红并点名该
+//! 行；②同一处改写成别名 `Spawn::new(..)` ⇒ 同样红；③删 `platform/child.rs` 的
+//! `creation_flags(CREATE_NO_WINDOW)` ⇒ [`the_constructor_actually_passes_create_no_window`] 红；
+//! ④`game/java/discover.rs` 的 `quiet("reg")` 改回裸构造 ⇒ 必须红（见 P1-1）。
+//!
+//! M217（落在**此前不在射程内**的 crate 上）：⑤`presenter/src/host/env.rs` 塞裸
+//! `Command::new("tzutil")` ⇒ 红并点名 `crates/presenter/src/host/env.rs:<行>`；⑥
+//! `app-iced/src/platform/locale.rs` 的 `quiet(program)` 改回裸构造 ⇒ 红（用户报的那处
+//! `reg.exe`）；⑦`export.rs` 三个 opener 留裸 + 清单写明理由 ⇒ **不**红。
+//!
+//! ## P1-1：守卫自己被变异验了两遍才对的
+//!
+//! ③第一次**没红**：断言搜整份源码，而 `quiet` 的文档注释里就写着
+//! `.creation_flags(CREATE_NO_WINDOW)`——注释喂饱了断言，改成先剥注释（[`code_lines`]）再判。
+//! ④（复审判的变异 D）**又没红**：那版 `code_lines` 对每行找 `/*`，而注释与字符串里到处是
+//! glob（`/usr/lib/jvm/*`、`"mods/*.jar"`），这些 `/*` 没有配对的 `*/` ⇒ `in_block` 一旦为真就
+//! 不再变假，**该文件从那一行到 EOF 全被吞掉**（`crates/core/src` 里 8/371 个中招，一个正是
+//! `game/java/discover.rs`）。现在只在**行首**认 `/*`，并由
+//! [`the_scan_reaches_the_end_of_every_file`] 逐文件核对最后一行代码必须被扫到。
+
+use std::fs;
+use std::path::{Path, PathBuf};
+
+/// 允许直接构造子进程的一条**角色**。
+struct Role {
+    /// 相对 `crates/` 的路径。以 `/` 结尾 = 该目录下全部文件（目录角色）。
+    path: &'static str,
+    /// 期望的裸构造处数：`Some(n)` 精确核对；目录角色 `None` = 只要求至少一处。
+    sites: Option,
+    /// 为什么这一处不能走 `quiet`。文件角色写这一处，目录角色写这一整类。
+    why: &'static str,
+}
+
+impl Role {
+    /// 目录角色覆盖该目录下全部文件；文件角色按整条路径精确比。
+    fn covers(&self, rel: &str) -> bool {
+        (self.path.ends_with('/') && rel.starts_with(self.path)) || rel == self.path
+    }
+}
+
+/// 这张表是**角色**清单，不是「白名单文件」清单：新增一行必须写清「为什么不能走 `quiet`」。
+const ALLOWED_ROLES: &[Role] = &[
+    Role {
+        path: "core/src/platform/child.rs",
+        sites: Some(1),
+        why: "构造器自身：`child::quiet` 内部就是这一处 `Command::new`",
+    },
+    Role {
+        path: "core/src/launch/process.rs",
+        sites: Some(1),
+        why: "游戏进程：要 CREATE_NEW_PROCESS_GROUP 撑 taskkill /T 回收进程树；\
+              游戏要不要带自己的控制台窗口是产品决定，不是顺手抑制（M213 明确不动）",
+    },
+    Role {
+        path: "app-iced/src/app/dialog/export.rs",
+        sites: Some(3),
+        why: "目录打开器三兄弟（explorer / open / xdg-open，各平台一个）：用户点「打开文件夹」\
+              要的就是那个文件管理器窗口，窗口就是产品。这三者自己都是 GUI 侧程序，由无控制台的\
+              GUI 父进程 spawn 时本来就不分控制台；改错的代价是用户点按钮没反应（M217 要求留裸）",
+    },
+    Role {
+        path: "presenter/src/host/opener.rs",
+        sites: Some(1),
+        why: "浏览器打开器（rundll32 / open / xdg-open）：与上一行同一角色——打开一个可见的东西\
+              是这次 spawn 的**目的**。M217 不改它（不在本 mission 的改动范围），只登记成角色，\
+              免得守卫把正确的实现判成漏网",
+    },
+    Role {
+        path: "core/tests/",
+        sites: None,
+        why: "测试夹具：父进程是控制台（`cargo test`），子进程继承同一块控制台，不会新建窗口；\
+              而且夹具要起 shell / tasklist / kill 之类的真程序做行为验证",
+    },
+    Role {
+        path: "cli/tests/",
+        sites: None,
+        why: "测试夹具（同上；这里还要起真二进制验 CLI 的退出码与 update 签名）",
+    },
+];
+
+#[test]
+fn no_spawn_site_bypasses_the_quiet_constructor() {
+    let root = crates_root();
+    let files = rust_files(&root);
+    // 兜底一：扫不到任何文件 ⇒ 根路径错了。兜底二：根扫到「非空但不是 crates/」也红——拿角色
+    // 文件当锚点。
+    assert!(
+        !files.is_empty(),
+        "没扫到任何 .rs：`crates/` 路径不对（{}）",
+        root.display()
+    );
+    for anchor in ["core/src/platform/child.rs", "core/src/launch/process.rs"] {
+        assert!(
+            files.iter().any(|rel| rel == anchor),
+            "扫描根不是 `crates/`：里面找不到 `{anchor}`（实际根：{}）",
+            root.display()
+        );
+    }
+
+    // 一次扫面：`(相对 crates/ 的路径, 行号, 该行代码)`。
+    let mut sites: Vec<(String, usize, String)> = Vec::new();
+    for rel in &files {
+        let text = read_source(&root, rel);
+        let aliases = command_aliases(&text);
+        for (number, line) in code_lines(&text) {
+            if is_spawn_site(line, &aliases) {
+                sites.push((rel.clone(), number, line.trim().to_string()));
+            }
+        }
+    }
+    let illegal: Vec = sites
+        .iter()
+        .filter(|(rel, ..)| !ALLOWED_ROLES.iter().any(|role| role.covers(rel)))
+        .map(|(rel, number, line)| format!("  crates/{rel}:{number}  {line}"))
+        .collect();
+    assert!(
+        illegal.is_empty(),
+        "发现绕开 `platform::child::quiet` 的子进程构造（{} 处）：\n{}\n\
+         在 Windows 上这会为每个子进程新建一块控制台（GUI 父进程下就是桌面上「黑框闪一下」）。\
+         改走 `unlucky_core::platform::child::quiet(program)`；若这一处确实不该抑制窗口，\
+         把它的**角色**加进 ALLOWED_ROLES 并写清理由。",
+        illegal.len(),
+        illegal.join("\n"),
+    );
+
+    // 角色核对：允许的角色必须真的存在、处数对得上，否则这张表会悄悄变成摆设。
+    for role in ALLOWED_ROLES {
+        let hits: Vec = sites
+            .iter()
+            .filter(|(rel, ..)| role.covers(rel))
+            .map(|(.., number, _)| *number)
+            .collect();
+        match role.sites {
+            Some(expected) => assert_eq!(
+                hits.len(),
+                expected,
+                "角色 `crates/{}`（{}）应当恰好 {expected} 处直接构造，实测行号 {hits:?}",
+                role.path,
+                role.why,
+            ),
+            None => assert!(
+                !hits.is_empty(),
+                "目录角色 `crates/{}`（{}）一处都没命中——这条清单条目该删了",
+                role.path,
+                role.why,
+            ),
+        }
+    }
+}
+
+#[test]
+fn the_constructor_actually_passes_create_no_window() {
+    let text = read_source(&crates_root(), "core/src/platform/child.rs");
+    // **只看代码行**：`quiet` 的文档注释里就写着 `.creation_flags(CREATE_NO_WINDOW)`，
+    // 对着整份源码搜会被那句注释喂饱——删掉真正的设置行也照样绿（实测踩过）。
+    let code: Vec<&str> = code_lines(&text)
+        .into_iter()
+        .map(|(_, line)| line)
+        .collect();
+    // 只去空白，避免格式调整造成假红（下划线是标识符的一部分，不能去）。
+    let no_space = code.concat().split_whitespace().collect::();
+    assert!(
+        no_space.contains("creation_flags(CREATE_NO_WINDOW)"),
+        "`platform::child::quiet` 不再设置 creation_flags —— 抑制窗口的那一行被删了？\n\
+         注意 `.stdout(Stdio::null())` 不能替代它：那只改句柄，控制台窗口照样会被创建。",
+    );
+    // 常量值单独比：数字里的下划线是排版自由，去掉再比。
+    let definition = code
+        .iter()
+        .find(|line| line.trim_start().starts_with("const CREATE_NO_WINDOW"))
+        .expect("找不到 `CREATE_NO_WINDOW` 的常量定义");
+    let (_, value) = definition.split_once('=').expect("常量定义里没有 `=`");
+    let digits = value.replace('_', "");
+    let literal = digits.split_whitespace().collect::();
+    assert_eq!(
+        literal.trim_end_matches(';'),
+        "0x08000000",
+        "`CREATE_NO_WINDOW` 的取值不对（`{definition}`）。必须是 0x0800_0000，\
+         不是 CREATE_NEW_CONSOLE（0x0000_0010，意思正好相反）。",
+    );
+}
+
+#[test]
+fn code_lines_is_not_fooled_by_glob_slashes_in_strings_or_docs() {
+    // M213 复审 P1-1 的最小复现：**字符串**里的 `/*` 不许把后一行吞掉。
+    let in_string = code_lines("let a = \"mods/*.jar\";\nlet b = 1;\n");
+    assert!(
+        in_string
+            .iter()
+            .any(|(number, line)| *number == 2 && line.contains("let b")),
+        "字符串里的 `/*` 吞掉了后一行：{in_string:?}",
+    );
+
+    // 同一份故障在**文档注释的 glob** 上的形态（`crates/core/src` 里 8 个文件都是这一种）。
+    let in_doc_glob = code_lines("//! | Linux | `/usr/lib/jvm/*` |\nfn real_code() {}\n");
+    assert_eq!(
+        in_doc_glob.len(),
+        1,
+        "注释里的 glob 吞掉了代码：{in_doc_glob:?}"
+    );
+    assert!(in_doc_glob[0].1.contains("fn real_code"));
+
+    // 真的块注释还是要被剥掉（别把上面两条修成「块注释一律不认」）。
+    let block = code_lines("/* a\n b\n*/\nfn after() {}\n");
+    assert_eq!(block.len(), 1, "块注释没被剥：{block:?}");
+    assert!(block[0].1.contains("fn after"), "剥错了行：{block:?}");
+
+    // 同一行闭合的块注释，收尾后的残段是代码。
+    let inline_close = code_lines("/* c */ fn inline() {}\n");
+    assert_eq!(
+        inline_close.len(),
+        1,
+        "同行闭合的块注释丢了残段：{inline_close:?}"
+    );
+    assert!(inline_close[0].1.contains("fn inline"));
+}
+
+#[test]
+fn the_scan_reaches_the_end_of_every_file() {
+    // 「整份文件被吞掉」这类故障自己红：逐文件核对**最后一行代码的行号**必须出现在扫面结果里。
+    // 这条比「数总行数」尖锐——文件普遍以 `}` 结尾，光比内容会被别处的 `}` 蒙混过去。
+    // 只有 `//!` 的结论页（`app-iced/src/platform/linux/mod.rs` 这类）没有代码行，跳过是对的。
+    let root = crates_root();
+    let files = rust_files(&root);
+    assert!(!files.is_empty(), "没扫到任何 .rs：{}", root.display());
+
+    let (mut visible_total, mut line_total) = (0usize, 0usize);
+    let mut starved: Vec = Vec::new();
+    for rel in &files {
+        let text = read_source(&root, rel);
+        let visible = code_lines(&text);
+        visible_total += visible.len();
+        line_total += text.lines().count();
+        let mut last_code = None;
+        for (index, line) in text.lines().enumerate() {
+            if looks_like_code(line) {
+                last_code = Some((index + 1, line));
+            }
+        }
+        let Some((number, line)) = last_code else {
+            continue;
+        };
+        if !visible.iter().any(|(seen, _)| *seen == number) {
+            starved.push(format!(
+                "crates/{rel}：最后一行代码 `{}`（第 {number} 行）没被扫到 ⇒ 被吞到 EOF",
+                line.trim()
+            ));
+        }
+    }
+    assert!(starved.is_empty(), "扫面没走到底：\n{}", starved.join("\n"));
+    // 兜底：可见行占比实测 81%（1219 个 .rs），门槛取 60% 留足余量。它只抓「大面积吞行」。
+    assert!(
+        visible_total * 10 >= line_total * 6,
+        "可见行只有 {visible_total}/{line_total}（<60%），扫面异常缩水",
+    );
+}
+
+/// 「这一行看起来是代码」：非空，且不是以 `/`（`//`、`/*`）或 `*`（`*/`、续行）开头。
+fn looks_like_code(line: &str) -> bool {
+    let trimmed = line.trim();
+    !trimmed.is_empty() && !trimmed.starts_with(['/', '*'])
+}
+
+/// `crates/`（`CARGO_MANIFEST_DIR` 的上一级）。守卫的射程就是它，不多不少。
+fn crates_root() -> PathBuf {
+    let manifest = Path::new(env!("CARGO_MANIFEST_DIR"));
+    let crates = manifest.parent().expect("`crates/core` 没有上一级");
+    crates.to_path_buf()
+}
+
+fn read_source(root: &Path, rel: &str) -> String {
+    fs::read_to_string(root.join(rel))
+        .unwrap_or_else(|error| panic!("读不到 crates/{rel}：{error}"))
+}
+
+fn rust_files(root: &Path) -> Vec {
+    fn walk(root: &Path, dir: &Path, out: &mut Vec) {
+        let entries =
+            fs::read_dir(dir).unwrap_or_else(|error| panic!("读不到 {}：{error}", dir.display()));
+        for entry in entries.flatten() {
+            let path = entry.path();
+            if path.is_dir() {
+                walk(root, &path, out);
+            } else if path.extension().is_some_and(|ext| ext == "rs") {
+                let rel = path.strip_prefix(root).expect("strip_prefix 失败");
+                out.push(rel.to_string_lossy().replace('\\', "/"));
+            }
+        }
+    }
+
+    let mut files = Vec::new();
+    walk(root, root, &mut files);
+    files.sort();
+    files
+}
+
+/// 去掉注释后的可见行（行号保留，报错能指到原文件）。
+///
+/// **`/*` 只在行首才算块注释开头**（M213 复审 P1-1）：本仓库的文档注释与字符串里到处是 glob
+/// （`/usr/lib/jvm/*`、`"mods/*.jar"`），行中认 `/*` 会让 `in_block` 一去不回，把该文件从那
+/// 里到 EOF 全吞掉。代价是行中开始的跨行块注释之后那几行会被当成代码（方向：误报）。
+fn code_lines(text: &str) -> Vec<(usize, &str)> {
+    let mut visible: Vec<(usize, &str)> = Vec::new();
+    let mut in_block = false;
+    for (index, raw) in text.lines().enumerate() {
+        let number = index + 1;
+        let trimmed = raw.trim_start();
+        if in_block {
+            // 块内只认 `*/`：它后面剩的残段可能是代码（`*/ let x = 1;`）。
+            if let Some(end) = trimmed.find("*/") {
+                in_block = false;
+                push_tail(&mut visible, number, &trimmed[end + 2..]);
+            }
+            continue;
+        }
+        if trimmed.starts_with("//") {
+            continue;
+        }
+        if trimmed.starts_with("/*") {
+            match trimmed.find("*/") {
+                Some(end) => push_tail(&mut visible, number, &trimmed[end + 2..]),
+                None => in_block = true,
+            }
+            continue;
+        }
+        visible.push((number, raw));
+    }
+    visible
+}
+
+/// 块注释收尾后的残段：不是空、也不是新的一条整行注释，才算可见代码。
+fn push_tail<'a>(visible: &mut Vec<(usize, &'a str)>, number: usize, tail: &'a str) {
+    let tail = tail.trim_start();
+    if !tail.is_empty() && !tail.starts_with("//") {
+        visible.push((number, tail));
+    }
+}
+
+/// 本文件里由 `std::process::Command` 导出的别名（`use ... Command as X;` / `type X = …Command;`）。
+fn command_aliases(text: &str) -> Vec {
+    let mut aliases = Vec::new();
+    for (_, line) in code_lines(text) {
+        // `use std::process::Command as Spawn;` / `use std::process::{Command as Spawn};`
+        if let Some(at) = line.find("Command as ") {
+            let ident: String = line[at + "Command as ".len()..]
+                .chars()
+                .take_while(|c| c.is_alphanumeric() || *c == '_')
+                .collect();
+            if !ident.is_empty() {
+                aliases.push(ident);
+            }
+            continue;
+        }
+        // `type Cmd = std::process::Command;` —— 别名在 `=` 的**左边**。
+        let trimmed = line.trim_start();
+        if trimmed.starts_with("type ") && line.ends_with("Command;") {
+            if let Some(ident) = trimmed
+                .split_whitespace()
+                .find(|word| *word != "type" && !word.contains('='))
+            {
+                aliases.push(ident.to_string());
+            }
+        }
+    }
+    aliases
+}
+
+fn is_spawn_site(line: &str, aliases: &[String]) -> bool {
+    line.contains("Command::new(")
+        || aliases
+            .iter()
+            .any(|alias| line.contains(&format!("{alias}::new(")))
+}
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::>();
+    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.(Reflector.java:455)",
+        "\tTRANSFORMER/net.optifine/net.optifine.reflect.Reflector.(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::>()
+    );
+}
+
+#[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::>();
+    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) {
+    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::>();
+    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::(), 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 = (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 = (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 = (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 = (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/not_found.rs b/crates/core/tests/download/engine_mock/not_found.rs
new file mode 100644
index 0000000..13cc50c
--- /dev/null
+++ b/crates/core/tests/download/engine_mock/not_found.rs
@@ -0,0 +1,67 @@
+//! `SourceFailed.kind` 的另一半（M197 复审 P2-2）：**404 是「该源没有这个文件」**，不是「源坏了」。
+//!
+//! 两档在引擎里的后果不同：`NotFound` 走 `record_missing`（不冷却源），`ServerError` 走
+//! `record_failure`。院校镜像只留最新补丁，请求旧补丁必然 404——判成「源坏了」会把唯一可用镜像
+//! 冷却掉（M33/M34 实测）。
+//!
+//! 变异证明：把 `engine.rs` / `bytes.rs` 的 `kind: err.kind` 改成常量 `Network` ⇒ 本条与
+//! `reports_progress_events_and_errors_when_all_sources_fail` 一起红。
+//!
+//! 拆成子模块：`engine_mock_test.rs` 加了这条之后 407 行，越过 400 行硬线（`guards.yml` 的
+//! `file-size`），于是把整条用例搬出来。
+
+use std::sync::Arc;
+
+use unlucky_core::download::cache::ContentCache;
+use unlucky_core::download::engine::DownloadEngine;
+use unlucky_core::download::error::DownloadErrorKind;
+use unlucky_core::download::health::HealthRegistry;
+use unlucky_core::download::mirrors::MirrorTable;
+use unlucky_core::download::progress::{ProgressEmitter, ProgressEvent};
+use unlucky_core::download::types::{DownloadRequest, ResourceKind};
+
+use super::support::{temp_dir, MockResponse, MockServer};
+use super::{direct_region, fast_config};
+
+#[tokio::test]
+async fn a_404_is_classified_as_not_found() {
+    let server = MockServer::start(vec![
+        MockResponse::status(404),
+        MockResponse::status(404),
+        MockResponse::status(404),
+        MockResponse::status(404),
+    ])
+    .await;
+    let url = server.url("/gone.jar");
+    let dir = temp_dir("engine-404");
+    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()),
+        Arc::new(ContentCache::open(dir.join("cache"))),
+    )
+    .with_progress(emitter);
+    engine
+        .download(DownloadRequest::new(
+            ResourceKind::Library,
+            url.as_str(),
+            dir.join("gone.jar"),
+        ))
+        .await
+        .expect_err("只有 404 的源必须失败");
+
+    let mut seen: Vec = Vec::new();
+    while let Ok(event) = events.try_recv() {
+        if let ProgressEvent::SourceFailed { kind, .. } = event {
+            seen.push(kind);
+        }
+    }
+    assert!(!seen.is_empty(), "至少要有一条 SourceFailed");
+    assert!(
+        seen.iter().all(|kind| *kind == DownloadErrorKind::NotFound),
+        "404 必须分类成 NotFound，实际：{seen:?}"
+    );
+    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..30604c4
--- /dev/null
+++ b/crates/core/tests/download/engine_mock_test.rs
@@ -0,0 +1,364 @@
+//! 引擎端到端（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, kind, ..
+            } => {
+                failed_source = true;
+                assert!(!will_retry, "单次尝试用尽后不应再声明重试");
+                // M197：`kind` 是诊断字段，必须来自**真实**的失败分类（HTTP 500 → ServerError）。
+                // 变异证明：把 `engine.rs` 的 `kind: err.kind` 写成常量
+                // `DownloadErrorKind::Network` ⇒ 本断言红。
+                assert_eq!(
+                    kind,
+                    DownloadErrorKind::ServerError,
+                    "HTTP 500 必须被分类成 ServerError（诊断字段不许是常量）"
+                );
+            }
+            _ => {}
+        }
+    }
+    assert!(started && failed_source, "进度事件缺失");
+    server.stop();
+}
+
+/// 「404 不是源坏了」的守卫（M197 P2-2 的第二档）：拆到子模块守 400 行硬线。
+#[path = "engine_mock/not_found.rs"]
+mod not_found;
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(®istry),
+        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..2cbcce0
--- /dev/null
+++ b/crates/core/tests/download/mirrors_test.rs
@@ -0,0 +1,397 @@
+//! 镜像清单与前缀重写的单测（纯字符串，无网络）。
+
+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");
+    // 子路径逐字保留（`/maven` 是镜像侧的固定前缀，不属于子路径）。M210/D1：这条断言此前写成
+    // 「换成 `https://bmclapi2.bangbang93.com` 就完事」，把**丢 inject 的 bug 钉成了期望**——实测
+    // 无 `/maven` 是 70/70 个库 404 + 9 B，带 `/maven` 回 200 且 sha1 与官方逐字节一致。
+    let expected = LIBRARIES_URL.replace(
+        "https://libraries.minecraft.net",
+        "https://bmclapi2.bangbang93.com/maven",
+    );
+    assert_eq!(candidate.url, expected);
+}
+
+/// **守卫（M210/D1）**：每一条「给 libraries 用」的镜像规则，镜像前缀都必须带 `/maven`。官方库域名与
+/// 各 loader 的 maven 在 BMCLAPI 上都挂在 `/maven` 下，而 `apply()` 是纯前缀替换——`to` 里少了这一段
+/// 就会把 `com/google/guava/...` 直接拼到镜像根上。抓得住：删掉/改错任一条库镜像规则的 `inject`；
+/// 抓不住：`/maven` **写歪**（如 `/maven2`）只能靠行为用例 [`library_urls_expand_to_the_maven_subpath_on_bmclapi`]；
+/// `/assets`、`/fabric-meta` 这类结构本就不同的镜像表，以及 `from` 不像 maven 仓库的新库镜像，都不在列。
+#[test]
+fn every_library_mirror_rule_carries_the_maven_segment() {
+    let table = MirrorTable::builtin();
+    // 判据：「给 libraries 用」= `from` 指向 maven 仓库（host/路径里带 maven，或就是 Mojang 库域名）。
+    // 新增一条库镜像规则时这条自动纳入，不必改测试。
+    fn serves_maven(from: &str) -> bool {
+        host_of(from).unwrap_or_default().contains("maven")
+            || from.contains("maven")
+            || host_of(from) == Some("libraries.minecraft.net")
+    }
+    // 判据覆盖的规则 id（内置表里就是这 6 条；`bmclapi-liteloader` 的 `from` 不像 maven 仓库，且已因 M225 关闭，不在列）。
+    const EXPECTED: [&str; 6] = [
+        "bmclapi-libraries",
+        "bmclapi-forge-maven",
+        "bmclapi-forge-maven-net",
+        "bmclapi-neoforge",
+        "bmclapi-fabric-maven",
+        "bmclapi-maven-central",
+    ];
+    let mut checked: Vec<&str> = Vec::new();
+    for rule in table.rules.iter().filter(|rule| serves_maven(&rule.from)) {
+        let prefix = format!("{}{}", rule.to, rule.inject);
+        assert!(
+            prefix.ends_with("/maven"),
+            "规则 {} 的镜像前缀 `{prefix}` 少了 `/maven`：官方 `{}` 在镜像上挂在 `/maven/` 下，\
+             丢了它整张表 404（M210/D1）",
+            rule.id,
+            rule.from
+        );
+        checked.push(rule.id.as_str());
+    }
+    // 判据失效（规则被改名/改形/删掉）时这里红：期望的规则一条都不能漏。
+    for expected in EXPECTED {
+        assert!(
+            checked.contains(&expected),
+            "库镜像规则 {expected} 没被形态判据覆盖到（被改名/改形/删掉了？）：{checked:?}"
+        );
+    }
+    // 多出来的（新增 maven 规则）也得登记进 EXPECTED，否则说明它绕过了这道判据的意图审查。
+    assert_eq!(
+        checked.len(),
+        EXPECTED.len(),
+        "库镜像规则数与预期不符（新增/删除了规则？）：{checked:?}"
+    );
+}
+
+/// **行为守卫（M210/D1）**：真实库 URL 展开后必须落在镜像的 `/maven/<子路径>` 上。与上一条互为
+/// 补充：那条看规则形态，这条看用户实际会请求到的 URL。抓得住：`inject` 丢失、`to` 里手写 `/maven`
+/// 被删、或 `from`/`to` 被改成拼不出 `/maven` 的形态；抓不住：只覆盖这 5 个官方 maven 根（各处未必
+/// 都写全），镜像侧真实可达性要网络（留给 e2e）。
+#[test]
+fn library_urls_expand_to_the_maven_subpath_on_bmclapi() {
+    let table = MirrorTable::builtin();
+    let region = RegionProfile::mirror_first(0);
+    let cases = [
+        (
+            LIBRARIES_URL,
+            "https://bmclapi2.bangbang93.com/maven/com/google/guava/guava/32.0.0/guava-32.0.0.jar",
+        ),
+        (
+            "https://maven.fabricmc.net/net/fabricmc/fabric-loader/0.15.11/fabric-loader-0.15.11.jar",
+            "https://bmclapi2.bangbang93.com/maven/net/fabricmc/fabric-loader/0.15.11/fabric-loader-0.15.11.jar",
+        ),
+        (
+            "https://maven.minecraftforge.net/net/minecraftforge/forge/1.20.1-47.2.0/forge-1.20.1-47.2.0-installer.jar",
+            "https://bmclapi2.bangbang93.com/maven/net/minecraftforge/forge/1.20.1-47.2.0/forge-1.20.1-47.2.0-installer.jar",
+        ),
+        (
+            "https://maven.neoforged.net/releases/net/neoforged/neoforge/21.1.80/neoforge-21.1.80-installer.jar",
+            "https://bmclapi2.bangbang93.com/maven/net/neoforged/neoforge/21.1.80/neoforge-21.1.80-installer.jar",
+        ),
+        // M225：LiteLoader 的库来自 Central（`net.minecraft:launchwrapper` 才是 Mojang 库仓）。
+        (
+            "https://repo1.maven.org/maven2/org/ow2/asm/asm-all/5.2/asm-all-5.2.jar",
+            "https://bmclapi2.bangbang93.com/maven/org/ow2/asm/asm-all/5.2/asm-all-5.2.jar",
+        ),
+    ];
+    for (official, expected) in cases {
+        let candidates = table.expand(official, ResourceKind::Library, ®ion);
+        let mirror = candidates
+            .iter()
+            .find(|candidate| candidate.source == "bmclapi")
+            .unwrap_or_else(|| panic!("{official} 没有 bmclapi 候选：{candidates:?}"));
+        assert_eq!(
+            mirror.url, expected,
+            "库镜像 URL 形状不对（官方 {official}）"
+        );
+    }
+}
+
+/// **守卫（M225）**：LiteLoader 不套 bmclapi 改写——镜像侧 `versions.json` 与 artifact 实测 404 / 9 B，
+/// 官方 200（curl 记录见 `mirrors.json` 的 notes）。抓得住：`bmclapi-liteloader.enabled` 被翻回 true、
+/// 或有人给快照仓补来源不明的镜像规则；抓不住：镜像侧哪天真的补上了（那时改期望与 notes，别删测试）。
+#[test]
+fn liteloader_urls_stay_official_only() {
+    let (table, region) = (MirrorTable::builtin(), RegionProfile::mirror_first(0));
+    for url in [
+        "https://dl.liteloader.com/versions/versions.json",
+        "https://dl.liteloader.com/versions/com/mumfrey/liteloader/1.7.10/liteloader-1.7.10_04.jar",
+        "https://repo.mumfrey.com/content/repositories/snapshots/com/mumfrey/liteloader/1.12.2-SNAPSHOT/maven-metadata.xml",
+    ] {
+        let got = table.expand(url, ResourceKind::Library, ®ion);
+        assert_eq!(got.len(), 1, "{url} 不该有镜像候选：{got:?}");
+    }
+}
+
+#[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, ®ion);
+    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, ®ion);
+    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}"));
+
+    // 「默认前缀」的唯一真相源是**地区档案**（M193：`MirrorTable::set_gh_proxy` / `default_gh_proxy`
+    // 已删除——它们改/读的是表里的前缀目录，而 `expand()` 读档案，属于「看起来能改、其实没人读」）。
+    assert_eq!(
+        RegionProfile::mirror_first(0).gh_proxy.as_deref(),
+        Some(unlucky_core::download::region::DEFAULT_GH_PROXY)
+    );
+}
+
+#[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, ®ion);
+    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,
+        ®ion,
+    );
+    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,
+        ®ion,
+    );
+    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> = 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) -> 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 {
+    let Ok(entries) = std::fs::read_dir(dir) else {
+        return Vec::new();
+    };
+    let mut names: Vec = 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,
+    /// 是否声明 `Accept-Ranges: bytes` 并在收到 `Range` 时真的切段。
+    pub range_support: bool,
+    /// `ETag`（续传测试用）。
+    pub etag: Option,
+    /// 返回 206 时故意把 `Content-Range` 写成从 0 开始（模拟段错位的坏服务器）。
+    pub lie_content_range: bool,
+}
+
+impl MockResponse {
+    /// 200 + 完整内容（支持 Range）。
+    pub fn ok(body: impl Into>) -> 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,
+    handle: tokio::task::JoinHandle<()>,
+}
+
+impl MockServer {
+    /// 启动服务器（脚本是「每次请求一个响应」的队列）。
+    pub async fn start(script: Vec) -> 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=-`（`end` 可缺省 = 到文件末尾）。
+fn parse_range_header(value: &str) -> Option<(u64, Option)> {
+    let (start, end) = value.split_once('-')?;
+    let start = start.trim().parse::().ok()?;
+    let end = end.trim();
+    let end = if end.is_empty() {
+        None
+    } else {
+        Some(end.parse::().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 {
+    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/` 并写一个文件进去（模拟玩家内容：`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 {
+    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 = 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 = 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 用 /（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..db97db5
--- /dev/null
+++ b/crates/core/tests/game/java_vendor_chain.rs
@@ -0,0 +1,186 @@
+//! 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 {
+    parse_priority(
+        &items
+            .iter()
+            .map(|item| (*item).to_string())
+            .collect::>(),
+    )
+}
+
+#[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!["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!["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：`  `（大写 + 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", "termux"]
+    );
+    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 = (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 {
+    vec![
+        "-Djava.library.path=${natives_directory}".to_string(),
+        "-cp".to_string(),
+        "${classpath}".to_string(),
+    ]
+}
+
+fn game_tokens() -> Vec {
+    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 {
+    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..7a4805a
--- /dev/null
+++ b/crates/core/tests/launch/exit_cases.rs
@@ -0,0 +1,204 @@
+//! 退出分析测试：退出码语义 + `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_terminated_code_with_no_output_is_not_an_application_error() {
+    // D10：1.12.2 挂死后被任务管理器 / `taskkill /F` 结束 —— 退出码 1，零错误输出。
+    let analysis = analyze(1, 60_000, &[], false);
+    assert_eq!(analysis.exit_type, ExitType::Killed);
+    assert!(analysis.terminated_externally);
+    assert!(
+        analysis.summary().contains("疑似被外部结束"),
+        "{}",
+        analysis.summary()
+    );
+    // 同样的退出码带错误输出 → 仍是应用错误（不能把所有 1 都洗成「被结束」）。
+    let lines = vec![line(
+        Stream::Stderr,
+        "Exception in thread \"main\" java.lang.NullPointerException",
+    )];
+    let analysis = analyze(1, 60_000, &lines, false);
+    assert_eq!(analysis.exit_type, ExitType::ApplicationError);
+    assert!(!analysis.terminated_externally);
+    // POSIX 上 1 不是信号痕迹：不套这条判据（137/143 才是）。
+    let analysis = analyze(1, 60_000, &[], true);
+    assert_eq!(analysis.exit_type, ExitType::ApplicationError);
+    assert!(!analysis.terminated_externally);
+}
+
+#[test]
+fn a_deliberate_kill_is_reported_as_killed_not_suspected() {
+    // 「我们杀的」有登记作据，不该被说成「疑似」。
+    let mut signals = exit_analysis::ExitSignals::new(1, 60_000, &[]);
+    signals.killed = true;
+    let analysis = exit_analysis::analyze(&signals);
+    assert_eq!(analysis.exit_type, ExitType::Killed);
+    assert!(!analysis.terminated_externally);
+}
+
+#[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..41c6999
--- /dev/null
+++ b/crates/core/tests/launch/main.rs
@@ -0,0 +1,18 @@
+//! 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 natives_dry_run_cases;
+mod pipeline_cases;
+mod prelude;
+mod process_smoke;
+mod pump_buffer;
+mod session_events;
+mod sink_cases;
+mod tree_kill_cases;
+mod watchdog_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 = 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 = 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..4677c10
--- /dev/null
+++ b/crates/core/tests/launch/natives_cases.rs
@@ -0,0 +1,221 @@
+//! natives 解压（`launch::natives`）的用例：解析正确性 / 排除项 / 幂等 / 时代参数 / 事件流。
+//!
+//! 假 jar 用 `zip` 的 Stored 模式现造（不依赖真下载），真机验收另有人工步骤。
+
+use std::path::Path;
+
+use unlucky_core::launch::natives::{self, NativeJar, NativesEra, NativesPlan, STAMP_FILE};
+
+use crate::prelude::*;
+
+fn plan(jars: Vec) -> 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"));
+}
+
+/// 缺 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 = 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/natives_dry_run_cases.rs b/crates/core/tests/launch/natives_dry_run_cases.rs
new file mode 100644
index 0000000..beb32de
--- /dev/null
+++ b/crates/core/tests/launch/natives_dry_run_cases.rs
@@ -0,0 +1,245 @@
+//! `--dry-run` 的零落盘契约（M231 / DRYRUNPURE）：预览只读版本树，不建目录、不改 mtime。
+//!
+//! 判据是「版本树的节点类型 + mtime 快照逐字相等」而不是「natives 目录不存在」：
+//! 后者抓不住 `create_dir_all` 之后立刻删掉的情形（父目录 mtime 已经变了），
+//! 也抓不住「目录本来就在、但被重写/清空」的情形。
+
+use std::path::{Path, PathBuf};
+
+use unlucky_core::launch::natives::{self, NativeJar, NativesPlan};
+
+use crate::prelude::*;
+
+/// 版本树的「节点类型 + mtime（纳秒）+ 相对路径」快照，用来逐字比较 dry-run 前后。
+///
+/// 抓得住：新增/删除任何节点（含 `natives/` 目录本身）、任何已有节点被重写或 mtime 被
+/// 更新；根节点（= 父目录 `versions//`）也在快照里，所以「建目录」会同时体现在
+/// 节点集合与父目录 mtime 上。
+/// 抓不住：①内容变了但 mtime 被回填成原值（本仓没有这种写法）；②**建了立刻删**这类
+/// 瞬时写入只留父目录 mtime 一条线索，而 NTFS 会把该更新合并掉 —— 本仓实测：全量并行跑
+/// 测试时这条偶发看不见（单跑又看得见），所以瞬时建删只剩「`natives` 目录不存在」兜底。
+///
+/// 时间戳口径：NTFS / ext4 的 mtime 精度是 100ns 级，快照取纳秒整数比较，同一秒内的
+/// 两次操作（写文件 → 再写一次）分辨得出来，不需要 `sleep` 把操作推到不同秒。
+/// 判据自检见 `tree_snapshot_sees_new_nodes_and_mtime_changes`（防假绿）。
+fn tree_snapshot(root: &Path) -> Vec {
+    fn line(meta: &std::fs::Metadata, relative: &str) -> String {
+        let nanos = meta
+            .modified()
+            .expect("mtime")
+            .duration_since(std::time::UNIX_EPOCH)
+            .expect("epoch 之后")
+            .as_nanos();
+        let kind = if meta.is_dir() { "d" } else { "f" };
+        format!("{kind} {nanos} {relative}")
+    }
+    fn walk(dir: &Path, prefix: &str, out: &mut Vec) {
+        let mut entries: Vec = std::fs::read_dir(dir)
+            .expect("读目录")
+            .flatten()
+            .map(|entry| entry.path())
+            .collect();
+        entries.sort();
+        for path in entries {
+            let meta = std::fs::symlink_metadata(&path).expect("元数据");
+            let name = path
+                .file_name()
+                .expect("文件名")
+                .to_string_lossy()
+                .to_string();
+            let relative = format!("{prefix}{name}");
+            out.push(line(&meta, &relative));
+            if meta.is_dir() {
+                walk(&path, &format!("{relative}/"), out);
+            }
+        }
+    }
+    let mut out = vec![line(
+        &std::fs::symlink_metadata(root).expect("根元数据"),
+        "",
+    )];
+    walk(root, "", &mut out);
+    out
+}
+
+/// `--dry-run` 零落盘（有 jar）：只报「将解压几个」，版本树里一个节点都不新增、mtime 不动。
+#[test]
+fn dry_run_previews_natives_without_touching_disk() {
+    let root = temp_dir("natives-dry-run-pure");
+    let jar = root.join("libraries/lwjgl-natives-windows.jar");
+    make_jar(&jar, &lwjgl_jar_entries());
+    let version_dir = root.join("versions/1.16.5");
+    std::fs::create_dir_all(&version_dir).expect("建版本目录");
+    std::fs::write(version_dir.join("1.16.5.json"), b"{}").expect("放清单占位");
+    let natives_dir = version_dir.join("natives");
+    let before = tree_snapshot(&version_dir);
+
+    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-pure-sessions");
+    let launcher = Launcher::new(LauncherConfig::new(&sessions));
+
+    let dry = launcher.dry_run(&request).expect("dry-run 应成功");
+    assert_eq!(
+        before,
+        tree_snapshot(&version_dir),
+        "dry-run 不许在版本树里加节点 / 改 mtime"
+    );
+    let report = dry.natives.expect("应有 natives 预览");
+    assert!(report.planned, "预览报告要自报家门：{report:?}");
+    assert!(!report.dir_exists, "natives 目录原本不在盘上：{report:?}");
+    assert_eq!(report.files, 2, "要算出「将写下」的数量：{report:?}");
+    assert_eq!(report.ignored, 4, "忽略口径要与真解压一致：{report:?}");
+    assert!(!report.up_to_date, "{report:?}");
+    assert!(
+        report.summary().contains("未落盘"),
+        "人读行得说清没写盘：{}",
+        report.summary()
+    );
+
+    assert!(!natives_dir.exists(), "natives 目录不该被建出来");
+}
+
+/// `--dry-run` 零落盘（无 jar，1.19+ 常态）：不建 natives 目录，人读行说清「尚不存在」。
+#[test]
+fn dry_run_with_no_natives_jar_creates_no_directory() {
+    let root = temp_dir("natives-dry-run-nojar");
+    let version_dir = root.join("versions/1.20.1");
+    std::fs::create_dir_all(&version_dir).expect("建版本目录");
+    let natives_dir = version_dir.join("natives");
+    let before = tree_snapshot(&version_dir);
+
+    let (mut request, _) = legacy_forge_request();
+    request.dirs.natives_dir = natives_dir.clone();
+    request.natives = NativesPlan::default();
+    request.manifest.legacy_arguments = Some("--username ${auth_player_name}".to_string());
+    let sessions = temp_sessions_root("natives-dry-run-nojar-sessions");
+    let launcher = Launcher::new(LauncherConfig::new(&sessions));
+
+    let dry = launcher.dry_run(&request).expect("dry-run 应成功");
+    assert_eq!(before, tree_snapshot(&version_dir), "无 jar 也不许建目录");
+    let report = dry.natives.expect("应有 natives 预览");
+    assert_eq!(report.jars, 0, "{report:?}");
+    assert_eq!(report.files, 0, "{report:?}");
+    assert!(!report.dir_exists, "盘上没有这个目录：{report:?}");
+    assert!(report.up_to_date, "无 jar = 无需解压：{report:?}");
+    assert!(
+        report.summary().contains("尚不存在"),
+        "{}",
+        report.summary()
+    );
+
+    assert!(!natives_dir.exists(), "natives 目录不该被建出来");
+}
+
+/// `--dry-run` 零落盘（空 jar：只有 `META-INF/` 与噪音）：数得出 0 个原生库，仍不建目录。
+#[test]
+fn dry_run_with_empty_native_jar_creates_no_directory() {
+    let root = temp_dir("natives-dry-run-emptyjar");
+    let jar = root.join("natives-windows.jar");
+    make_jar(
+        &jar,
+        &[
+            ("META-INF/MANIFEST.MF", b"manifest".as_slice()),
+            ("README.txt", b"noise".as_slice()),
+        ],
+    );
+    let version_dir = root.join("versions/1.16.5");
+    std::fs::create_dir_all(&version_dir).expect("建版本目录");
+    let natives_dir = version_dir.join("natives");
+    let before = tree_snapshot(&version_dir);
+
+    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-emptyjar-sessions");
+    let launcher = Launcher::new(LauncherConfig::new(&sessions));
+
+    let dry = launcher.dry_run(&request).expect("dry-run 应成功");
+    assert_eq!(before, tree_snapshot(&version_dir), "空 jar 也不许建目录");
+    let report = dry.natives.expect("应有 natives 预览");
+    assert_eq!(report.files, 0, "空 jar 解不出原生库：{report:?}");
+    assert_eq!(report.ignored, 2, "两条噪音都要数进忽略：{report:?}");
+    assert!(!report.up_to_date, "{report:?}");
+    assert!(!report.dir_exists, "{report:?}");
+
+    assert!(!natives_dir.exists(), "natives 目录不该被建出来");
+}
+
+/// 目录已经真解压过：预览读戳记报「已就绪」，同样零写盘（幂等路径也不许碰盘）。
+#[test]
+fn dry_run_after_real_extract_reports_ready_without_writing() {
+    let root = temp_dir("natives-dry-run-ready");
+    let jar = root.join("natives-windows.jar");
+    make_jar(&jar, &[("lwjgl.dll", b"DLL".as_slice())]);
+    let version_dir = root.join("versions/1.16.5");
+    let natives_dir = version_dir.join("natives");
+    std::fs::create_dir_all(&version_dir).expect("建版本目录");
+    natives::extract(
+        &natives_dir,
+        &NativesPlan::new(vec![NativeJar::new(&jar, "lwjgl")]),
+    )
+    .expect("先真解压一次");
+    let before = tree_snapshot(&version_dir);
+
+    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-ready-sessions");
+    let launcher = Launcher::new(LauncherConfig::new(&sessions));
+
+    let dry = launcher.dry_run(&request).expect("dry-run 应成功");
+    assert_eq!(
+        before,
+        tree_snapshot(&version_dir),
+        "预览不该重写已有的原生库或戳记"
+    );
+    let report = dry.natives.expect("应有 natives 预览");
+    assert!(report.planned, "{report:?}");
+    assert!(report.dir_exists, "{report:?}");
+    assert!(report.up_to_date, "戳记命中应报已就绪：{report:?}");
+    assert_eq!(report.files, 0, "预览不该再数一遍：{report:?}");
+    assert_eq!(report.skipped, 1, "{report:?}");
+}
+
+/// 判据自检（防假绿）：快照必须看得见「新增节点」与「已有节点的 mtime 变化」，
+/// 否则上面几条「快照逐字相等」等于没断言。
+///
+/// 这里**不**用「建了立刻删」来探父目录 mtime：NTFS 会把瞬时建删对父目录 mtime 的影响
+/// 合并掉（本仓实测：全量并行跑时偶发看不见、单跑看得见），拿它当门禁就是引入 flaky。
+/// 改成两种确定性变化：新节点（结构维度）+ 同内容重写（时间维度，只有文件 mtime 变，
+/// 不依赖父目录时间戳的合并行为）。
+#[test]
+fn tree_snapshot_sees_new_nodes_and_mtime_changes() {
+    let root = temp_dir("natives-snapshot-probe");
+    let version_dir = root.join("versions/1.16.5");
+    std::fs::create_dir_all(&version_dir).expect("建版本目录");
+    std::fs::write(version_dir.join("1.16.5.json"), b"{}").expect("放清单占位");
+    let baseline = tree_snapshot(&version_dir);
+
+    // 1) 结构维度：多一个目录节点（正是 `create_dir_all(natives)` 留下的痕迹）。
+    std::fs::create_dir(version_dir.join("natives")).expect("建目录");
+    let with_dir = tree_snapshot(&version_dir);
+    assert!(
+        with_dir.len() > baseline.len(),
+        "快照必须看得见新目录：{baseline:?} vs {with_dir:?}"
+    );
+    assert_ne!(baseline, with_dir);
+
+    // 2) 时间维度：同一份内容重写一遍，节点集合不变、文件 mtime 必须变。
+    std::fs::write(version_dir.join("1.16.5.json"), b"{}").expect("重写清单占位");
+    let rewritten = tree_snapshot(&version_dir);
+    assert_eq!(
+        with_dir.len(),
+        rewritten.len(),
+        "节点集合没变，差异只该在 mtime 上"
+    );
+    assert_ne!(
+        with_dir, rewritten,
+        "快照必须看得见已有文件的 mtime 变化，否则零落盘断言是假绿"
+    );
+}
diff --git a/crates/core/tests/launch/pipeline_cases.rs b/crates/core/tests/launch/pipeline_cases.rs
new file mode 100644
index 0000000..23665f3
--- /dev/null
+++ b/crates/core/tests/launch/pipeline_cases.rs
@@ -0,0 +1,376 @@
+//! 顶层启动管线测试：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>,
+}
+
+impl DiagnosisHook for RecordingHook {
+    fn analyze(&self, request: &DiagnosisRequest) -> Option {
+        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>) -> 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(dir: &std::path::Path) -> String {
+    #[cfg(windows)]
+    let (file, body) = (
+        dir.join("linger.bat"),
+        "@echo off\r\nping -n 30 127.0.0.1 >nul\r\n",
+    );
+    #[cfg(not(windows))]
+    let (file, body) = (dir.join("linger.sh"), "#!/bin/sh\nsleep 30\n");
+    std::fs::write(&file, body).expect("写长跑脚本");
+    file.display().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(""),
+        "命令行必须脱敏：{}",
+        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("")));
+    assert!(!handle
+        .redacted_argv()
+        .iter()
+        .any(|arg| arg.contains("SECRET-TOKEN-123456")));
+    assert!(handle.redacted_display().contains(""));
+    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), &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 a_kill_from_another_thread_is_recorded_as_killed() {
+    // D10：GUI 的 `host::launch::stop(pid)` 是从别的线程直接 `kill_tree`，不经过
+    // `LaunchSession::stop()`。这条路以前会记成 `application_error`（Windows 退出码 1）。
+    let sessions = temp_sessions_root("external-kill");
+    let run_dir = temp_dir("external-kill-run");
+    let launcher = launcher(&sessions, None);
+    let (request, _) = shell_request(&long_running_script(&run_dir), &run_dir);
+
+    let session = launcher.spawn(&request).expect("spawn 应成功");
+    let pid = session.pid();
+    // `kill_tree` 的返回值不代表「进程还在」：温和阶段可能已经关掉了它（taskkill 报 128）。
+    let _ = unlucky_core::launch::tree_kill::kill_tree(pid, Duration::from_millis(200));
+    let handle = session.finish().expect("收尾应成功");
+
+    assert_eq!(
+        handle.exit.exit_type,
+        ExitType::Killed,
+        "我们杀的要判成 killed：{}",
+        handle.exit.summary()
+    );
+    assert!(
+        !handle.exit.terminated_externally,
+        "有登记作据就不该只是「疑似」：{}",
+        handle.exit.summary()
+    );
+}
+
+#[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 = 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 = 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..fa0fa57
--- /dev/null
+++ b/crates/core/tests/launch/prelude.rs
@@ -0,0 +1,183 @@
+//! 测试共用设施。
+//!
+//! **crate 名只在本文件出现**（tower 定案 `unlucky_core`；若 M11 改包名，只改这里）。
+
+use std::fs::File;
+use std::io::Write;
+use std::path::{Path, PathBuf};
+
+use zip::write::SimpleFileOptions;
+use zip::{CompressionMethod, ZipWriter};
+
+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 {
+    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()
+}
+
+/// 造一个假 jar（`zip` Stored 模式，不依赖真下载）：`entries` 是（条目名, 内容）。
+///
+/// natives 用例共用（真解压与 `--dry-run` 预览两边都要现造 jar）。
+pub 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 的条目集（2 个原生库 + 4 条该被排除的噪音）。
+pub 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()),
+    ]
+}
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 = 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//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 = 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 = 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 = 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(""));
+    assert!(raw.contains(""), "同一个值内也允许混合脱敏");
+
+    // 字段名/数值/布尔原样保留（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 = 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::::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 -- -` 没有可用的组；
+//! - 组杀前必须验组（[`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//stat` 里 `)` 之后的字段（state ppid pgrp ...）。
+    fn stat_tail(pid: u32) -> Option> {
+        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 {
+        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 不是合法目标");
+
+        // 同组的子进程：它不是组长，`-` 指向的不是“它的”组。
+        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,
+            "非组长子进程不能走组杀（`-` 会打到别人的组）"
+        );
+
+        // 独立组的子进程：合法的组杀目标。
+        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 {
+            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/launch/watchdog_cases.rs b/crates/core/tests/launch/watchdog_cases.rs
new file mode 100644
index 0000000..e056a52
--- /dev/null
+++ b/crates/core/tests/launch/watchdog_cases.rs
@@ -0,0 +1,328 @@
+//! D6 看门狗：有界等待（真进程，不是 mock）。
+//!
+//! 四条用例各自钉一个判据：
+//!
+//! 1. 没窗口也没退出 → 立刻停止等待并报错，**进程还活着**（不杀）；
+//! 2. 窗口出现过 → 慢慢加载不会被判死，正常退出照常给结果；
+//! 3. 出现关闭标记后仍不退出 → 判「卡在关闭」（实机 D6 的形态）；
+//! 4. 短命的正常退出 → 不会被超时误判成错误。
+//!
+//! 子进程一律是**脚本文件**（`.bat` / `.sh`），不把 `&` / 重定向塞进 `cmd /C` 的单个参数：
+//! 那样 cmd 的引号剥离规则会让脚本变成另一条命令（第一版就是这么翻车的）。
+
+use std::path::{Path, PathBuf};
+use std::time::{Duration, Instant};
+
+use crate::prelude::*;
+
+use unlucky_core::launch::tree_kill;
+use unlucky_core::launch::watchdog::WatchdogConfig;
+
+fn launcher(sessions_root: &Path, startup: Duration, grace: Duration) -> 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),
+        // 泵的预算压到 200ms：放弃等待之后不该再为「等日志落盘」多等默认的 10 秒。
+        watchdog: WatchdogConfig {
+            pump_timeout: Duration::from_millis(200),
+        },
+        startup_timeout: startup,
+        shutdown_grace: grace,
+        ..ProcessConfig::default()
+    };
+    Launcher::new(config)
+}
+
+/// 写一个伪装成 java 的脚本，返回它的路径。
+fn script(dir: &Path, name: &str, lines: &[&str]) -> PathBuf {
+    #[cfg(windows)]
+    let (file, shebang) = (dir.join(format!("{name}.bat")), "@echo off");
+    #[cfg(not(windows))]
+    let (file, shebang) = (dir.join(format!("{name}.sh")), "#!/bin/sh");
+    let body = format!("{shebang}\n{}\n", lines.join("\n"));
+    std::fs::write(&file, body).expect("写测试脚本");
+    file
+}
+
+/// 用脚本文件当 java（命令行组装、事件流、退出判定都是真的，只有 JVM 是假的）。
+fn request(script_path: &Path, run_dir: &Path) -> LaunchRequest {
+    let (mut request, _) = legacy_forge_request();
+    #[cfg(windows)]
+    {
+        request.wrapper = vec![
+            "cmd".to_string(),
+            "/C".to_string(),
+            script_path.display().to_string(),
+        ];
+    }
+    #[cfg(not(windows))]
+    {
+        request.wrapper = vec!["/bin/sh".to_string(), script_path.display().to_string()];
+    }
+    request.java = JavaSelection::new("fake-java", 17, 64);
+    request.manifest.legacy_arguments = None;
+    request.dirs.game_dir = run_dir.to_path_buf();
+    request.dirs.natives_dir = run_dir.join("natives");
+    request.user.jvm = Vec::new();
+    request.user.game = Vec::new();
+    request
+}
+
+/// 进程是否还活着（看门狗「不杀进程」的判据）。
+fn is_alive(pid: u32) -> bool {
+    #[cfg(windows)]
+    {
+        let output = std::process::Command::new("tasklist")
+            .args(["/FI", &format!("PID eq {pid}"), "/NH"])
+            .output()
+            .expect("tasklist 应可执行");
+        String::from_utf8_lossy(&output.stdout).contains(&pid.to_string())
+    }
+    #[cfg(not(windows))]
+    {
+        std::process::Command::new("kill")
+            .args(["-0", &pid.to_string()])
+            .status()
+            .map(|status| status.success())
+            .unwrap_or(false)
+    }
+}
+
+/// 一条「活着但什么也不干」的脚本（约 3 秒）。
+fn linger_lines() -> Vec<&'static str> {
+    #[cfg(windows)]
+    {
+        vec!["ping -n 4 127.0.0.1 >nul"]
+    }
+    #[cfg(not(windows))]
+    {
+        vec!["sleep 3"]
+    }
+}
+
+/// 先打一行窗口标记，再活 1 秒左右。
+fn window_then_exit_lines() -> Vec<&'static str> {
+    #[cfg(windows)]
+    {
+        vec!["echo LWJGL Version: 3.3.1", "ping -n 2 127.0.0.1 >nul"]
+    }
+    #[cfg(not(windows))]
+    {
+        vec!["echo 'LWJGL Version: 3.3.1'", "sleep 1"]
+    }
+}
+
+/// 每秒打一行、总共约 4 秒的脚本（**有**日志、**没有**窗口标记）。
+#[cfg(windows)]
+fn chatty_lines() -> Vec<&'static str> {
+    // `ping` 每秒打一行；不重定向就是为了让它真的输出。
+    vec!["ping -n 5 127.0.0.1"]
+}
+
+/// 同上（POSIX）。
+#[cfg(not(windows))]
+fn chatty_lines() -> Vec<&'static str> {
+    vec!["i=0; while [ $i -lt 5 ]; do echo \"tick $i\"; sleep 1; i=$((i+1)); done"]
+}
+
+#[test]
+fn a_chatty_slow_load_is_not_mistaken_for_a_hang() {
+    // 一直没有窗口，但每秒都有一行日志：静默预算 1.5s，总时长 4s+ ⇒ 不能被判死。
+    let sessions = temp_sessions_root("watchdog-chatty");
+    let run_dir = temp_dir("watchdog-chatty-run");
+    let path = script(&run_dir, "chatty", &chatty_lines());
+    let launcher = launcher(
+        &sessions,
+        Duration::from_millis(1500),
+        Duration::from_secs(60),
+    );
+    let session = launcher
+        .spawn(&request(&path, &run_dir))
+        .expect("spawn 应成功");
+    let started = Instant::now();
+    let handle = session.finish().expect("还在打日志就不算卡死");
+    assert!(
+        started.elapsed() > Duration::from_millis(1500),
+        "这条用例要真的越过静默预算，否则什么都没验到：{:?}",
+        started.elapsed()
+    );
+    assert_eq!(handle.exit.code, 0);
+    assert_eq!(handle.exit.exit_type, ExitType::Normal);
+    assert!(
+        !handle
+            .index
+            .as_ref()
+            .is_some_and(|entry| entry.window_detected),
+        "这条脚本不该命中窗口启发式"
+    );
+}
+
+/// 先打关闭标记，再挂住不走（约 9 秒）。
+fn shutdown_then_hang_lines() -> Vec<&'static str> {
+    #[cfg(windows)]
+    {
+        vec![
+            "echo [Client thread/INFO]: Stopping!",
+            "ping -n 10 127.0.0.1 >nul",
+        ]
+    }
+    #[cfg(not(windows))]
+    {
+        vec!["echo '[Client thread/INFO]: Stopping!'", "sleep 9"]
+    }
+}
+
+#[test]
+fn startup_timeout_stops_waiting_and_never_kills_the_process() {
+    let sessions = temp_sessions_root("watchdog-startup");
+    let run_dir = temp_dir("watchdog-startup-run");
+    let path = script(&run_dir, "linger", &linger_lines());
+    let launcher = launcher(
+        &sessions,
+        Duration::from_millis(300),
+        Duration::from_secs(60),
+    );
+    let session = launcher
+        .spawn(&request(&path, &run_dir))
+        .expect("spawn 应成功");
+    let pid = session.pid();
+    let log_path = session.log_path().to_path_buf();
+    let started = Instant::now();
+    let error = session
+        .finish()
+        .expect_err("没窗口也没退出：必须停止等待并报错，不能无限等");
+    let spent = started.elapsed();
+    assert!(
+        spent < Duration::from_secs(5),
+        "超时后应立即返回：{spent:?}"
+    );
+    match &error {
+        LaunchError::Watchdog {
+            pid: reported,
+            reason,
+            limit_ms,
+            ..
+        } => {
+            assert_eq!(*reported, pid);
+            assert_eq!(*reason, "startup_timeout");
+            assert_eq!(*limit_ms, 300, "上限要如实回报（可配 + 可见）");
+        }
+        other => panic!("应报看门狗超时，实际 {other:?}"),
+    }
+    let text = error.to_string();
+    assert!(text.contains("没有被结束"), "{text}");
+    // M220 nit1：这句话直接打到终端，残留的 `**` 标记在终端里只会原样显示成星号。
+    assert!(
+        !text.contains("**"),
+        "人读错误串里不该有 Markdown 标记：{text}"
+    );
+    assert!(text.contains("ULL_LAUNCH_STARTUP_TIMEOUT_SECS"), "{text}");
+
+    // 会话照样收尾（历史里看得见这一局），原因是 still_running 而不是 exit。
+    let events = read_events(&log_path);
+    let last = events.last().expect("至少写了 session_start");
+    assert_eq!(last["kind"], "session_end");
+    assert_eq!(last["payload"]["reason"], "still_running");
+
+    // 关键断言：进程还活着 —— 看门狗只停止等待，绝不结束进程。
+    assert!(is_alive(pid), "看门狗不该结束进程（pid {pid} 已经不在了）");
+    let _ = tree_kill::force_kill(pid);
+}
+
+#[test]
+fn a_seen_window_keeps_the_wait_alive_for_slow_loads() {
+    // 启动预算是 300ms，但窗口标记在几十毫秒内就到了：慢加载不是卡死。
+    let sessions = temp_sessions_root("watchdog-window");
+    let run_dir = temp_dir("watchdog-window-run");
+    let path = script(&run_dir, "windowed", &window_then_exit_lines());
+    let launcher = launcher(
+        &sessions,
+        Duration::from_millis(300),
+        Duration::from_secs(60),
+    );
+    let session = launcher
+        .spawn(&request(&path, &run_dir))
+        .expect("spawn 应成功");
+    let started = Instant::now();
+    let handle = session
+        .finish()
+        .expect("窗口出现过之后就该一直等到它自己退出");
+    assert!(
+        started.elapsed() > Duration::from_millis(300),
+        "这条用例要真的越过启动预算，否则什么都没验到"
+    );
+    assert_eq!(
+        handle.exit.exit_type,
+        ExitType::Normal,
+        "{}",
+        handle.summary()
+    );
+    assert_eq!(handle.exit.code, 0);
+    assert!(
+        handle
+            .index
+            .as_ref()
+            .is_some_and(|entry| entry.window_detected),
+        "窗口检测要落进索引（GUI/诊断都看这一位）"
+    );
+}
+
+#[test]
+fn a_shutdown_marker_followed_by_hang_is_reported_as_stuck_on_close() {
+    // 实机 D6：关窗后 java.exe 仍存活。游戏自己打了「Stopping!」，之后就再没动静。
+    let sessions = temp_sessions_root("watchdog-shutdown");
+    let run_dir = temp_dir("watchdog-shutdown-run");
+    let path = script(&run_dir, "hanging", &shutdown_then_hang_lines());
+    let launcher = launcher(
+        &sessions,
+        Duration::from_secs(60),
+        Duration::from_millis(400),
+    );
+    let session = launcher
+        .spawn(&request(&path, &run_dir))
+        .expect("spawn 应成功");
+    let pid = session.pid();
+    let started = Instant::now();
+    let error = session
+        .finish()
+        .expect_err("关闭标记之后挂住：必须停止等待并报错");
+    assert!(
+        started.elapsed() < Duration::from_secs(6),
+        "宽限一到就要返回：{:?}",
+        started.elapsed()
+    );
+    match &error {
+        LaunchError::Watchdog { reason, .. } => assert_eq!(*reason, "shutdown_timeout"),
+        other => panic!("应报卡在关闭，实际 {other:?}"),
+    }
+    assert!(error.to_string().contains("已开始关闭"), "{error}");
+    let _ = tree_kill::force_kill(pid);
+}
+
+#[test]
+fn a_quick_clean_exit_is_never_punished_by_the_watchdog() {
+    let sessions = temp_sessions_root("watchdog-quick");
+    let run_dir = temp_dir("watchdog-quick-run");
+    let path = script(&run_dir, "quick", &["echo hello"]);
+    let launcher = launcher(&sessions, Duration::from_secs(3), Duration::from_secs(3));
+    let session = launcher
+        .spawn(&request(&path, &run_dir))
+        .expect("spawn 应成功");
+    let handle = session.finish().expect("正常退出不该报错");
+    assert_eq!(handle.exit.code, 0);
+    assert_eq!(handle.exit.exit_type, ExitType::Normal);
+    assert!(!handle.exit.terminated_externally);
+}
+
+/// M220 nit1：`launcher.log` 与会话输出里的这句「看门狗生效值」是给人看的，
+/// 残留的 `**` 标记在终端里只会原样显示成星号（旧文案就是「停止等待**不结束进程**」）。
+#[test]
+fn the_watchdog_summary_is_plain_text() {
+    let summary = LauncherConfig::new(std::env::temp_dir()).watchdog_summary();
+    assert!(summary.contains("不结束进程"), "{summary}");
+    assert!(
+        !summary.contains("**"),
+        "人读串里不该有 Markdown 标记：{summary}"
+    );
+}
diff --git a/crates/core/tests/liteloader/fixtures/liteloader-versions.json b/crates/core/tests/liteloader/fixtures/liteloader-versions.json
new file mode 100644
index 0000000..e1c458f
--- /dev/null
+++ b/crates/core/tests/liteloader/fixtures/liteloader-versions.json
@@ -0,0 +1,98 @@
+{
+  "meta": {
+    "description": "LiteLoader is a lightweight mod bootstrap designed to provide basic loader functionality for mods which don't need to modify game mechanics.",
+    "authors": "Mumfrey",
+    "url": "http://dl.liteloader.com",
+    "updated": "2017-11-29T16:31:41+00:00",
+    "updatedTime": 1511973101
+  },
+  "versions": {
+    "1.7.10": {
+      "repo": {
+        "stream": "RELEASE",
+        "type": "ivy",
+        "url": "http://dl.liteloader.com/versions/",
+        "classifier": "mcpnames"
+      },
+      "artefacts": {
+        "com.mumfrey:liteloader": {
+          "63ada46e033d0cb6782bada09ad5ca4e": {
+            "tweakClass": "com.mumfrey.liteloader.launch.LiteLoaderTweaker",
+            "libraries": [
+              { "name": "net.minecraft:launchwrapper:1.11" },
+              { "name": "org.ow2.asm:asm-all:5.0.3" }
+            ],
+            "srcJar": "liteloader-1.7.10_04-mcpnames-sources.jar",
+            "mcpJar": "liteloader-1.7.10_04-mcpnames.jar",
+            "stream": "RELEASE",
+            "file": "liteloader-1.7.10_04.jar",
+            "version": "1.7.10_04",
+            "md5": "63ada46e033d0cb6782bada09ad5ca4e",
+            "timestamp": "1414368553"
+          },
+          "db7235aefd407ac1fde09a7baba50839": {
+            "tweakClass": "com.mumfrey.liteloader.launch.LiteLoaderTweaker",
+            "libraries": [
+              { "name": "net.minecraft:launchwrapper:1.9" },
+              {
+                "name": "org.ow2.asm:asm-all:5.0.3",
+                "url": "http://repo.maven.apache.org/maven2/"
+              }
+            ],
+            "stream": "RELEASE",
+            "file": "liteloader-1.7.10_00.jar",
+            "version": "1.7.10_00",
+            "md5": "db7235aefd407ac1fde09a7baba50839",
+            "timestamp": "1404330030"
+          }
+        }
+      }
+    },
+    "1.12.2": {
+      "repo": {
+        "stream": "SNAPSHOT",
+        "type": "m2",
+        "url": "http://repo.mumfrey.com/content/repositories/snapshots/",
+        "classifier": ""
+      },
+      "snapshots": {
+        "libraries": [
+          { "name": "net.minecraft:launchwrapper:1.12" },
+          {
+            "name": "org.spongepowered:mixin:0.7.4-SNAPSHOT",
+            "url": "https://repo.spongepowered.org/maven/"
+          }
+        ],
+        "com.mumfrey:liteloader": {
+          "1420785ecbfed5aff4a586c5c9dd97eb": {
+            "tweakClass": "com.mumfrey.liteloader.launch.LiteLoaderTweaker",
+            "libraries": [
+              { "name": "net.minecraft:launchwrapper:1.12" },
+              { "name": "org.ow2.asm:asm-all:5.2" }
+            ],
+            "stream": "SNAPSHOT",
+            "file": "liteloader-1.12.2-SNAPSHOT.jar",
+            "version": "1.12.2-SNAPSHOT",
+            "build": "1.12.2-SNAPSHOT-r4CC2BB0-b4-4",
+            "md5": "1420785ecbfed5aff4a586c5c9dd97eb",
+            "timestamp": "1511880271",
+            "lastSuccessfulBuild": 4
+          },
+          "latest": {
+            "tweakClass": "com.mumfrey.liteloader.launch.LiteLoaderTweaker",
+            "libraries": [
+              { "name": "net.minecraft:launchwrapper:1.12" },
+              { "name": "org.ow2.asm:asm-all:5.2" }
+            ],
+            "stream": "SNAPSHOT",
+            "file": "liteloader-1.12.2-SNAPSHOT.jar",
+            "version": "1.12.2-SNAPSHOT",
+            "md5": "1420785ecbfed5aff4a586c5c9dd97eb",
+            "timestamp": "1511880271",
+            "lastSuccessfulBuild": 4
+          }
+        }
+      }
+    }
+  }
+}
diff --git a/crates/core/tests/liteloader/guards.rs b/crates/core/tests/liteloader/guards.rs
new file mode 100644
index 0000000..f303a3f
--- /dev/null
+++ b/crates/core/tests/liteloader/guards.rs
@@ -0,0 +1,200 @@
+//! 边界与失败面：父版本缺失、组合不支持、数据源形状坏、取消。
+//!
+//! 网络层的失败映射（`DownloadError` → `loader_network`）由 `core::download` 的引擎测试
+//! 与既有加载器测试覆盖，这里**不联网**：外部源的真实可用性在 mission 报告里单独列
+//! （含探测结果），不混进单元测试冒充。
+
+use std::sync::atomic::AtomicBool;
+
+use unlucky_core::addon::loader::liteloader::parse_versions;
+use unlucky_core::addon::loader::{
+    LoaderErrorKind, LoaderInstallPlan, LoaderKind, LoaderPlanInput, LoaderSource,
+};
+use unlucky_core::download::blocking::block_on;
+use unlucky_core::game::arguments::Environment;
+use unlucky_core::game::install::{execute_with_cancel, InstallErrorKind};
+use unlucky_core::game::layout::GameLayout;
+
+use crate::support::{engine, liteloader_release, prefill, put_version, TempDir, VANILLA_1122};
+
+/// 父版本不是原版、又没装在盘上 → **具名报错**，绝不默默改成叠原版。
+#[test]
+fn missing_loader_parent_is_a_named_error() {
+    let temp = TempDir::new("missing-parent");
+    let layout = GameLayout::new(temp.path());
+    put_version(&layout, "1.12.2", VANILLA_1122);
+    let release = liteloader_release("1.12.2-forge-14.23.5.2860");
+
+    let error = LoaderInstallPlan::build(LoaderPlanInput {
+        layout: &layout,
+        release: &release,
+        environment: &Environment::host(),
+        parent_installed: false,
+    })
+    .expect_err("父版本缺失必须报错");
+    assert_eq!(error.kind(), LoaderErrorKind::NotFound);
+    assert!(
+        error.message().contains("1.12.2-forge-14.23.5.2860"),
+        "错误里要点名缺的是哪个父版本：{}",
+        error.message()
+    );
+    assert!(error.hint().is_some(), "要给出下一步怎么办");
+}
+
+/// 父版本链：读盘定位原版版本 id（合成 loader id / 定位 jar 都用它）。
+#[test]
+fn parent_chain_walks_to_the_vanilla_root() {
+    let temp = TempDir::new("parent-chain");
+    let layout = GameLayout::new(temp.path());
+    put_version(&layout, "1.12.2", VANILLA_1122);
+    put_version(
+        &layout,
+        "1.12.2-forge-14.23.5.2860",
+        crate::support::FORGE_1122,
+    );
+
+    assert_eq!(
+        unlucky_core::addon::loader::parent::root_version_id(&layout, "1.12.2-forge-14.23.5.2860")
+            .expect("两层链应走得到根"),
+        "1.12.2"
+    );
+    assert_eq!(
+        unlucky_core::addon::loader::parent::root_version_id(&layout, "1.12.2").expect("根是自己"),
+        "1.12.2"
+    );
+
+    // 没装的父版本 → not_found（而不是猜一个原版版本号）。
+    let error = unlucky_core::addon::loader::parent::root_version_id(&layout, "9.9.9-forge-1.0.0")
+        .expect_err("缺父版本必须报错");
+    assert_eq!(error.kind(), LoaderErrorKind::NotFound);
+}
+
+/// 只有 LiteLoader 接受「父版本不是原版」；别家**具名拒绝**，不去发请求。
+#[test]
+fn only_liteloader_accepts_a_non_vanilla_parent() {
+    let temp = TempDir::new("combo-guard");
+    let engine = engine(temp.path());
+    let source = LoaderSource::new(&engine, temp.path());
+    let error = block_on(async {
+        source
+            .resolve_on(
+                LoaderKind::Forge,
+                "1.12.2",
+                Some("14.23.5.2860"),
+                Some("1.12.2-liteloader-1.12.2-SNAPSHOT"),
+            )
+            .await
+    })
+    .expect_err("Forge 叠在 LiteLoader 上必须被拒");
+    assert_eq!(error.kind(), LoaderErrorKind::Unsupported);
+    assert!(
+        error
+            .message()
+            .contains("1.12.2-liteloader-1.12.2-SNAPSHOT"),
+        "要说清是哪个组合：{}",
+        error.message()
+    );
+}
+
+/// 版本表形状坏 / 空表：各自给具名大类，不当成「没有版本」糊过去。
+#[test]
+fn broken_version_table_is_reported_distinctly() {
+    let shape = parse_versions(r#"{"versions": []}"#).expect_err("形状不符");
+    assert_eq!(shape.kind(), LoaderErrorKind::Metadata);
+    let empty = parse_versions(r#"{"meta": {}, "versions": {}}"#).expect_err("空表");
+    assert_eq!(empty.kind(), LoaderErrorKind::NotFound);
+
+    // 版本段缺失（记录没有 version）：只剩 latest 别名 → 仍当空表处理。
+    let only_latest = r#"{"versions": {"1.7.10": {"artefacts": {"com.mumfrey:liteloader":
+        {"latest": {"tweakClass": "x", "version": "", "file": "liteloader.jar"}}}}}}"#;
+    let error = parse_versions(only_latest).expect_err("只有 http 别名时没有可用版本");
+    assert_eq!(error.kind(), LoaderErrorKind::NotFound);
+}
+
+/// 取消：执行段看标志就返回 `Cancelled`，**版本 JSON 不落盘**（不留半成品）。
+#[test]
+fn cancel_leaves_no_manifest() {
+    let temp = TempDir::new("cancel");
+    let layout = GameLayout::new(temp.path());
+    put_version(&layout, "1.12.2", VANILLA_1122);
+    let release = liteloader_release("1.12.2");
+    let plan = LoaderInstallPlan::build(LoaderPlanInput {
+        layout: &layout,
+        release: &release,
+        environment: &Environment::host(),
+        parent_installed: true,
+    })
+    .expect("计划应可组");
+
+    let engine = engine(temp.path());
+    prefill(&plan.install);
+    let cancel = AtomicBool::new(true);
+    let error = block_on(execute_with_cancel(
+        &engine,
+        &plan.install,
+        4,
+        None,
+        Some(&cancel),
+    ))
+    .expect_err("取消必须返回错误");
+    assert_eq!(error.kind(), InstallErrorKind::Cancelled);
+    assert!(
+        !layout.version_json(&release.version_id).exists(),
+        "取消之后不许留下版本清单"
+    );
+}
+
+/// 同一个 loader 版本 id 被两条父链请求：**具名报错**，且盘上那份清单一个字节都不动。
+///
+/// 为什么必须有这道门：`<原版>-liteloader-` 对「叠原版」与「叠 Forge」是同一个目录名，
+/// 直接覆盖会让已经登记、指向这个版本 id 的旧实例**静默换父链**（启动行为跟着变）。
+#[test]
+fn parent_collision_is_refused_instead_of_overwriting() {
+    let temp = TempDir::new("parent-collision");
+    let layout = GameLayout::new(temp.path());
+    put_version(&layout, "1.12.2", VANILLA_1122);
+    put_version(
+        &layout,
+        "1.12.2-forge-14.23.5.2860",
+        crate::support::FORGE_1122,
+    );
+
+    let vanilla_release = liteloader_release("1.12.2");
+    let existing = serde_json::json!({
+        "id": vanilla_release.version_id,
+        "inheritsFrom": "1.12.2",
+        "mainClass": "net.minecraft.launchwrapper.Launch",
+        "arguments": {"game": ["--tweakClass", "com.mumfrey.liteloader.launch.LiteLoaderTweaker"]},
+        "libraries": []
+    });
+    put_version(
+        &layout,
+        &vanilla_release.version_id,
+        &serde_json::to_string_pretty(&existing).expect("序列化"),
+    );
+    let before = std::fs::read_to_string(layout.version_json(&vanilla_release.version_id))
+        .expect("读旧清单");
+
+    let forge_release = liteloader_release("1.12.2-forge-14.23.5.2860");
+    assert_eq!(
+        forge_release.version_id, vanilla_release.version_id,
+        "两条父链撞同一个 id"
+    );
+    let error = LoaderInstallPlan::build(LoaderPlanInput {
+        layout: &layout,
+        release: &forge_release,
+        environment: &Environment::host(),
+        parent_installed: true,
+    })
+    .expect_err("撞父链必须报错");
+    assert_eq!(error.kind(), LoaderErrorKind::Unsupported);
+    assert!(
+        error.message().contains("1.12.2-forge-14.23.5.2860") && error.message().contains("1.12.2"),
+        "要说清两条父链各是什么：{}",
+        error.message()
+    );
+
+    let after = std::fs::read_to_string(layout.version_json(&vanilla_release.version_id))
+        .expect("读旧清单");
+    assert_eq!(before, after, "报错之后盘上那份清单不许被改动");
+}
diff --git a/crates/core/tests/liteloader/install.rs b/crates/core/tests/liteloader/install.rs
new file mode 100644
index 0000000..2179a9c
--- /dev/null
+++ b/crates/core/tests/liteloader/install.rs
@@ -0,0 +1,297 @@
+//! 解析 → 计划 → 落盘 → 继承解析 → 启动参数顺序（两条父链：原版 / Forge）。
+
+use unlucky_core::addon::loader::{LoaderInstallPlan, LoaderPlanInput};
+use unlucky_core::download::blocking::block_on;
+use unlucky_core::game::arguments::Environment;
+use unlucky_core::game::inherit::resolve;
+use unlucky_core::game::install::execute;
+use unlucky_core::game::layout::GameLayout;
+use unlucky_core::launch::command_builder::tokenize;
+
+use crate::support::{
+    engine, liteloader_release, prefill, put_version, read_version, TempDir, FORGE_1122,
+    VANILLA_1122,
+};
+
+/// 原版父链：装完能落盘，清单指向原版，`arguments.game` 带 tweakClass。
+#[test]
+fn installs_over_vanilla_and_writes_the_manifest() {
+    let temp = TempDir::new("vanilla");
+    let layout = GameLayout::new(temp.path());
+    put_version(&layout, "1.12.2", VANILLA_1122);
+
+    let release = liteloader_release("1.12.2");
+    assert_eq!(release.version_id, "1.12.2-liteloader-1.12.2-SNAPSHOT");
+    let plan = LoaderInstallPlan::build(LoaderPlanInput {
+        layout: &layout,
+        release: &release,
+        environment: &Environment::host(),
+        parent_installed: true,
+    })
+    .expect("父版本已装，计划应可组");
+    assert!(!plan.vanilla_install_needed);
+    assert!(plan.install.client_jar().is_none(), "jar 归原版层");
+
+    // 三个库：launchwrapper（Mojang 库仓）+ asm-all（Central）+ 本体 jar（官方直链）。
+    let names: Vec<&str> = plan.files().iter().map(|file| file.name.as_str()).collect();
+    assert_eq!(names.len(), 3, "{names:?}");
+    let loader_jar = plan
+        .files()
+        .iter()
+        .find(|file| file.name == "com.mumfrey:liteloader:1.12.2-SNAPSHOT")
+        .expect("缺本体 jar");
+    assert!(
+        loader_jar
+            .url
+            .ends_with("/1.12.2-SNAPSHOT/liteloader-1.12.2-20171128.144431-4-release.jar"),
+        "本体直链：{}",
+        loader_jar.url
+    );
+    let asm = plan
+        .files()
+        .iter()
+        .find(|file| file.name.contains("asm-all"))
+        .expect("缺 asm-all");
+    assert!(
+        asm.url.starts_with("https://repo1.maven.org/maven2/"),
+        "asm-all 只能从 Central 取：{}",
+        asm.url
+    );
+
+    // 全部落点先铺好占位文件（库无 sha1/size → 存在即信），执行段只写版本 JSON。
+    let engine = engine(temp.path());
+    let prefilled = prefill(&plan.install);
+    assert_eq!(prefilled, 3);
+    let report = block_on(execute(&engine, &plan.install, 4, None)).expect("执行应成功");
+    assert!(report.is_complete(), "{:?}", report.failures(3));
+
+    let written = read_version(&layout, &release.version_id);
+    assert_eq!(written.inherits_from.as_deref(), Some("1.12.2"));
+    assert_eq!(
+        written.main_class.as_deref(),
+        Some("net.minecraft.launchwrapper.Launch")
+    );
+    assert!(
+        written.minecraft_arguments.is_none(),
+        "loader 层不许写 minecraftArguments：那会顶掉父链"
+    );
+}
+
+/// Forge 父链：**父链的 FMLTweaker 必须还在**，LiteLoader 的 tweakClass 追加在它后面。
+///
+/// 这条是 M218 SURVEY-p1 的「准入条件」：靠 `--tweakClass` 生效，就要求继承时
+/// `arguments.game` 是追加、`minecraftArguments` 不被子层覆盖。启动参数顺序照
+/// `core::launch::game_args` 的第 24 项（legacy 子串）→ 第 25 项（`arguments.game`）复现，
+/// 真实 argv 由 `tests/launch/cmdline_snapshot.rs` 钉住。
+#[test]
+fn stacks_on_forge_and_keeps_the_forge_tweak_class() {
+    let temp = TempDir::new("forge");
+    let layout = GameLayout::new(temp.path());
+    put_version(&layout, "1.12.2", VANILLA_1122);
+    put_version(&layout, "1.12.2-forge-14.23.5.2860", FORGE_1122);
+
+    let release = liteloader_release("1.12.2-forge-14.23.5.2860");
+    assert!(!release.parent_is_vanilla());
+    let plan = LoaderInstallPlan::build(LoaderPlanInput {
+        layout: &layout,
+        release: &release,
+        environment: &Environment::host(),
+        parent_installed: true,
+    })
+    .expect("父版本已装，计划应可组");
+    assert_eq!(plan.install.jar_id, "1.12.2", "jar 仍取原版那层");
+
+    let engine = engine(temp.path());
+    prefill(&plan.install);
+    let report = block_on(execute(&engine, &plan.install, 4, None)).expect("执行应成功");
+    assert!(report.is_complete(), "{:?}", report.failures(3));
+
+    let installed = read_version(&layout, &release.version_id);
+    let mut source = std::collections::BTreeMap::new();
+    source.insert("1.12.2".to_string(), read_version(&layout, "1.12.2"));
+    source.insert(
+        "1.12.2-forge-14.23.5.2860".to_string(),
+        read_version(&layout, "1.12.2-forge-14.23.5.2860"),
+    );
+    source.insert(release.version_id.clone(), installed);
+    let resolved = resolve(&source, &source[&release.version_id]).expect("三层继承应可解析");
+
+    // ① 父链的 legacy 参数整串还在（子层没写 minecraftArguments）。
+    let legacy = resolved
+        .minecraft_arguments
+        .as_deref()
+        .expect("Forge 的 minecraftArguments 不许被子层顶掉");
+    assert!(
+        legacy.contains("net.minecraftforge.fml.common.launcher.FMLTweaker"),
+        "Forge 的 tweakClass 丢了：{legacy}"
+    );
+
+    // ② 启动顺序：legacy（第 24 项）在前，arguments.game（第 25 项）在后。
+    let mut game: Vec = tokenize(legacy);
+    game.extend(
+        resolved
+            .arguments
+            .as_ref()
+            .expect("arguments 应保留")
+            .expand(&Environment::host())
+            .game,
+    );
+    let forge_at = game
+        .iter()
+        .position(|token| token.contains("FMLTweaker"))
+        .expect("Forge tweakClass 不在游戏参数里");
+    let liteloader_at = game
+        .iter()
+        .position(|token| token == "com.mumfrey.liteloader.launch.LiteLoaderTweaker")
+        .expect("LiteLoader tweakClass 不在游戏参数里");
+    assert!(
+        forge_at < liteloader_at,
+        "launchwrapper 按出现顺序应用 tweak：Forge 必须在前，实际 {game:?}"
+    );
+    assert_eq!(game[liteloader_at - 1], "--tweakClass");
+
+    // ③ 主类与库顺序：Forge 的库在前（classpath 先到先得），LiteLoader 的在后。
+    assert_eq!(
+        resolved.main_class.as_deref(),
+        Some("net.minecraft.launchwrapper.Launch")
+    );
+    let libraries: Vec<&str> = resolved
+        .libraries
+        .as_deref()
+        .expect("libraries")
+        .iter()
+        .map(|library| library.name.as_str())
+        .collect();
+    let forge_lib = libraries
+        .iter()
+        .position(|name| name.starts_with("net.minecraftforge:forge:"))
+        .expect("缺 Forge 本体库");
+    let liteloader_lib = libraries
+        .iter()
+        .position(|name| name.starts_with("com.mumfrey:liteloader:"))
+        .expect("缺 LiteLoader 本体库");
+    assert!(forge_lib < liteloader_lib, "{libraries:?}");
+}
+
+/// **新式 args 的父链**：父版本用 `arguments.game`（没有 `minecraftArguments`）。
+///
+/// 现实里 LiteLoader 只到 1.12.2，碰不到这种父版本；但「追加语义」是这套路线的准入条件，
+/// 两种父版本形状都得钉住——否则哪天上游把老版本清单改成新式，我们会静默丢参数。
+/// 这里用一份**手工夹具**（`--launchTarget forgeclient` 是 Forge 1.13+ 的真实形态）说明：
+/// 父层参数在前、LiteLoader 的 tweakClass 在后，中间不互相覆盖。
+#[test]
+fn new_style_parent_args_are_appended_not_replaced() {
+    const MODERN_PARENT: &str = r#"{
+      "id": "1.12.2-modern-1.0",
+      "inheritsFrom": "1.12.2",
+      "mainClass": "net.minecraft.launchwrapper.Launch",
+      "arguments": {"game": ["--launchTarget", "forgeclient"], "jvm": ["-Dmodern=1"]},
+      "libraries": [{"name": "example:modern:1.0", "url": "https://example.invalid/"}]
+    }"#;
+
+    let temp = TempDir::new("modern-args");
+    let layout = GameLayout::new(temp.path());
+    put_version(&layout, "1.12.2", VANILLA_1122);
+    put_version(&layout, "1.12.2-modern-1.0", MODERN_PARENT);
+
+    let release = liteloader_release("1.12.2-modern-1.0");
+    let plan = LoaderInstallPlan::build(LoaderPlanInput {
+        layout: &layout,
+        release: &release,
+        environment: &Environment::host(),
+        parent_installed: true,
+    })
+    .expect("计划应可组");
+    let engine = engine(temp.path());
+    prefill(&plan.install);
+    let report = block_on(execute(&engine, &plan.install, 4, None)).expect("执行应成功");
+    assert!(report.is_complete(), "{:?}", report.failures(3));
+
+    let mut source = std::collections::BTreeMap::new();
+    source.insert("1.12.2".to_string(), read_version(&layout, "1.12.2"));
+    source.insert(
+        "1.12.2-modern-1.0".to_string(),
+        read_version(&layout, "1.12.2-modern-1.0"),
+    );
+    source.insert(
+        release.version_id.clone(),
+        read_version(&layout, &release.version_id),
+    );
+    let resolved = resolve(&source, &source[&release.version_id]).expect("三层继承应可解析");
+
+    // 子层没写 legacy 串：继承结果里的 `minecraftArguments` 只能是祖父层（原版）那一份，
+    // 里面绝不能出现 LiteLoader 的 tweakClass（写了就说明我们用了覆盖语义）。
+    let legacy = resolved
+        .minecraft_arguments
+        .as_deref()
+        .expect("原版那份 legacy 串应沿链继承下来");
+    assert!(
+        !legacy.contains("LiteLoaderTweaker"),
+        "loader 层不许往 minecraftArguments 里写：{legacy}"
+    );
+    let game = resolved
+        .arguments
+        .as_ref()
+        .expect("arguments")
+        .expand(&Environment::host())
+        .game;
+    let assert_order = |needle: &str| {
+        game.iter()
+            .position(|token| token == needle)
+            .unwrap_or_else(|| panic!("缺 `{needle}`：{game:?}"))
+    };
+    assert!(
+        assert_order("forgeclient")
+            < assert_order("com.mumfrey.liteloader.launch.LiteLoaderTweaker"),
+        "父层参数必须在前：{game:?}"
+    );
+}
+
+/// LiteLoader 生效所依赖的**两条继承合并律**（M222 第一步核实，直接钉在合并函数上）。
+///
+/// 1. `arguments.game`：父在前、子在后**追加**（所以 tweakClass 能叠在父链参数之后）；
+/// 2. `minecraftArguments`：**子覆盖父**（所以 loader 层绝不能写它，否则父链的 tweakClass
+///    整串消失）。
+///
+/// 抓得住：有人把 `minecraftArguments` 改成追加（HMCL/原版语义不是这样），或把
+/// `arguments.game` 改成整体替换（LiteLoader/其它叠层加载器当场失效）。
+/// 抓不住：真实启动 argv 的顺序（那是 `launch::game_args` 的第 24/25 项，
+/// 由 `tests/launch/cmdline_snapshot.rs` 钉住；本 mission 没有改那一层）。
+#[test]
+fn merge_laws_liteloader_depends_on() {
+    use unlucky_core::game::inherit::merge;
+    use unlucky_core::game::manifest::VersionJson;
+
+    let parse = |json: &str| VersionJson::from_json_str(json).expect("夹具应可解析");
+
+    let parent = parse(
+        r#"{"id":"p","minecraftArguments":"--tweakClass FMLTweaker","arguments":{"game":["--parent"]}}"#,
+    );
+    let child = parse(r#"{"id":"c","arguments":{"game":["--child"]}}"#);
+    let merged = merge(&child, &parent);
+    assert_eq!(
+        merged.minecraft_arguments.as_deref(),
+        Some("--tweakClass FMLTweaker"),
+        "子没写就继承父（这条是「叠在 Forge 上」的前提）"
+    );
+    let game: Vec = merged
+        .arguments
+        .as_ref()
+        .expect("arguments")
+        .expand(&Environment::host())
+        .game;
+    assert_eq!(
+        game,
+        ["--parent", "--child"],
+        "arguments.game 是父在前、子在后追加"
+    );
+
+    // 子写了 minecraftArguments：整串替换（不是追加）。
+    let loud_child = parse(r#"{"id":"c2","minecraftArguments":"--tweakClass LiteLoaderTweaker"}"#);
+    let merged = merge(&loud_child, &parent);
+    assert_eq!(
+        merged.minecraft_arguments.as_deref(),
+        Some("--tweakClass LiteLoaderTweaker"),
+        "子覆盖父：这正是 loader 层不许写 minecraftArguments 的原因"
+    );
+}
diff --git a/crates/core/tests/liteloader/main.rs b/crates/core/tests/liteloader/main.rs
new file mode 100644
index 0000000..d8f1feb
--- /dev/null
+++ b/crates/core/tests/liteloader/main.rs
@@ -0,0 +1,20 @@
+//! LiteLoader 安装链路的集成测试（`tests/liteloader*` 这个 test target 的入口）。
+//!
+//! 判据链：**真实元数据夹具 → 解析 → 合成清单 → 计划 → 落盘 → 继承解析 → 启动参数顺序**。
+//! 全程不联网：LiteLoader 的库没有 sha1/size，`execute` 的跳过判据是「存在即信」，
+//! 所以先把每个待下文件按计划里的落点写一份占位字节，执行期就只做「跳过 + 写版本 JSON」。
+//!
+//! 夹具来源（可追溯）：
+//! - `fixtures/liteloader-versions.json` = 2026-11 从 `https://dl.liteloader.com/versions/versions.json`
+//!   真取的响应（200 / 49129 字节 / 16 个原版版本）裁剪到两个原版版本，**字段名与嵌套结构原样**；
+//! - `metadata.xml` = 同一次探测里 `repo.mumfrey.com/…/liteloader/1.12.2-SNAPSHOT/maven-metadata.xml`
+//!   的原样响应（200 / 358 字节）；
+//! - 原版 / Forge 1.12.2 的版本 JSON 是按官方清单形状写的最小夹具（Forge 那侧的
+//!   `minecraftArguments` 与 `crates/core/src/addon/loader/tests/forge.rs` 的实测夹具一致）。
+//!
+//! 未覆盖（如实留档）：真实下载（走 `core::download` 引擎的镜像/退避，已有 M13 的单测覆盖）、
+//! 真实 MC 启动、`dl.liteloader.com` / `repo.mumfrey.com` 的持续可用性。
+
+mod guards;
+mod install;
+mod support;
diff --git a/crates/core/tests/liteloader/support.rs b/crates/core/tests/liteloader/support.rs
new file mode 100644
index 0000000..954cd4a
--- /dev/null
+++ b/crates/core/tests/liteloader/support.rs
@@ -0,0 +1,157 @@
+//! 集成测试公用件：临时游戏目录、离线下载引擎、元数据夹具、父版本清单夹具。
+
+#![allow(dead_code)]
+
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicUsize, Ordering};
+use std::sync::Arc;
+use std::time::Duration;
+
+use unlucky_core::addon::loader::liteloader::{self, LiteLoaderEntry};
+use unlucky_core::addon::loader::LoaderRelease;
+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::game::layout::GameLayout;
+use unlucky_core::game::manifest::VersionJson;
+
+/// 真实响应的裁剪版（见 `tests/liteloader.rs` 文件头的来源说明）。
+pub const VERSION_TABLE: &str = include_str!("fixtures/liteloader-versions.json");
+
+/// 1.12.2-SNAPSHOT 的 maven-metadata（真实响应原样）。
+pub const METADATA_XML: &str = r#"
+
+  com.mumfrey
+  liteloader
+  1.12.2-SNAPSHOT
+  
+    
+      20171128.144431
+      4
+    
+    20171128144431
+  
+"#;
+
+/// 原版 1.12.2（老式 `minecraftArguments`，与官方清单同形）。
+pub const VANILLA_1122: &str = r#"{
+  "id": "1.12.2",
+  "type": "release",
+  "mainClass": "net.minecraft.client.main.Main",
+  "assets": "1.12",
+  "assetIndex": {"id": "1.12"},
+  "minecraftArguments": "--username ${auth_player_name} --version ${version_name}",
+  "libraries": [
+    {"name": "com.mojang:patchy:1.1", "url": "https://libraries.minecraft.net/"}
+  ]
+}"#;
+
+/// Forge 1.12.2-14.23.5.2860（spec-0 的 version.json：主类 launchwrapper + FMLTweaker）。
+pub const FORGE_1122: &str = r#"{
+  "id": "1.12.2-forge-14.23.5.2860",
+  "inheritsFrom": "1.12.2",
+  "mainClass": "net.minecraft.launchwrapper.Launch",
+  "minecraftArguments": "--tweakClass net.minecraftforge.fml.common.launcher.FMLTweaker",
+  "libraries": [
+    {"name": "net.minecraftforge:forge:1.12.2-14.23.5.2860", "url": "https://maven.minecraftforge.net/"}
+  ]
+}"#;
+
+/// 唯一临时目录守卫（`drop` 时递归删除）。
+pub struct TempDir {
+    path: PathBuf,
+}
+
+impl TempDir {
+    pub fn new(tag: &str) -> Self {
+        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 path = std::env::temp_dir().join(format!(
+            "ull-liteloader-{tag}-{}-{stamp}-{unique}",
+            std::process::id()
+        ));
+        let _ = std::fs::remove_dir_all(&path);
+        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 engine(cache_root: &Path) -> DownloadEngine {
+    let config = EngineConfig {
+        max_attempts_per_source: 1,
+        backoff: BackoffPolicy {
+            base_ms: 1,
+            max_ms: 2,
+            jitter_ratio: 0.0,
+            max_attempts: 1,
+        },
+        connect_timeout: Duration::from_secs(3),
+        read_timeout: Duration::from_secs(3),
+        chunked: ChunkedConfig::disabled(),
+        ..EngineConfig::default()
+    };
+    DownloadEngine::new(
+        config,
+        Arc::new(MirrorTable::builtin()),
+        Arc::new(RegionProfile::direct(0)),
+        Arc::new(HealthRegistry::in_memory()),
+        Arc::new(ContentCache::open(cache_root.join("cache"))),
+    )
+}
+
+/// 解析夹具表里某个原版版本的条目。
+pub fn entries(mc_version: &str) -> Vec {
+    let table = liteloader::parse_versions(VERSION_TABLE).expect("夹具版本表应可解析");
+    table.get(mc_version).cloned().unwrap_or_default()
+}
+
+/// 取 1.12.2 的 SNAPSHOT 条目并合成 release（父版本由调用方给）。
+pub fn liteloader_release(parent_version_id: &str) -> LoaderRelease {
+    let entries = entries("1.12.2");
+    let entry = liteloader::default_entry(&entries).expect("1.12.2 应有一条版本");
+    let url = liteloader::snapshot_artifact_url(entry, METADATA_XML).expect("快照直链");
+    liteloader::build_release("1.12.2", parent_version_id, entry, &url).expect("合成清单")
+}
+
+/// 把一份版本 JSON 写进 `versions//.json`（模拟「父版本已装好」）。
+pub fn put_version(layout: &GameLayout, id: &str, json: &str) {
+    let path = layout.version_json(id);
+    std::fs::create_dir_all(path.parent().expect("版本目录")).expect("建版本目录");
+    std::fs::write(&path, json).expect("写版本 JSON");
+}
+
+/// 读盘上的版本 JSON。
+pub fn read_version(layout: &GameLayout, id: &str) -> VersionJson {
+    let path = layout.version_json(id);
+    let text = std::fs::read_to_string(&path)
+        .unwrap_or_else(|error| panic!("读不到 {}：{error}", path.display()));
+    VersionJson::from_json_str(&text).expect("版本 JSON 应可解析")
+}
+
+/// 按计划把每个待下文件写成占位字节（`execute` 的跳过判据 = 无 sha1 且存在即信）。
+pub fn prefill(plan: &unlucky_core::game::install::InstallPlan) -> usize {
+    for file in &plan.files {
+        std::fs::create_dir_all(file.dest.parent().expect("文件父目录")).expect("建库目录");
+        std::fs::write(&file.dest, b"placeholder").expect("写占位文件");
+    }
+    plan.files.len()
+}
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 = 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) -> 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, ctx: &PlatformCtx) -> Vec {
+    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::>();
+    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..fc59988
--- /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,
+        8,
+        "1.8.0 登记 M197 的 download.gh_proxy（1.7.0 是 M168 的 ui.font_cdn）"
+    );
+    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 {
+    let mut names: Vec = 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)>;
+
+#[derive(Clone, Default)]
+struct RecordingSink {
+    written: Arc>,
+}
+
+impl RecordingSink {
+    fn entries(&self) -> Vec<(PathBuf, Vec)> {
+        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::::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::::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 = 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) {
+    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..d628dab
--- /dev/null
+++ b/crates/core/tests/setting/isolation_keys.rs
@@ -0,0 +1,252 @@
+//! 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.8.0 登记 M197 的 `download.gh_proxy`（1.7.0 = M168 的 `ui.font_cdn`，1.6.0 登记 M161 的
+    // 自更新两键，1.5.0 = M116 窗口圆角，1.4.0 = M91 外观下层三键，1.3.0 = D17「外观（高级）」，
+    // 1.2.0 = D23 的 JDK 落点/优先级键）。
+    assert_eq!(launcher_version(), SchemaVersion::new(1, 8, 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 = Vec::new();
+    let mut invalid: Vec = 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..2cc7d4a
--- /dev/null
+++ b/crates/core/tests/setting/java_install_keys.rs
@@ -0,0 +1,150 @@
+//! 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() {
+    // 1.8.0 = M197 的 gh-proxy 覆盖键（`download.gh_proxy`；此前 1.7.0 是 M168 的 `ui.font_cdn`，
+    // 1.6.0 是 M161 的自更新两键，1.5.0 是 M116 窗口圆角）。每加一批键推一次 minor 是**纪律**，
+    // 不是巧合：老版本读新文件会判 `ReadOnlyPreserveSchema`，所以版本号本身就是「新键存在」的对外声明。
+    assert_eq!(launcher_version(), SchemaVersion::new(1, 8, 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);
+}
+
+/// `java.auto_install` 的 schema 描述必须与实现一致：**不会**自动下载。
+///
+/// 这句会进 AI 工具的 JSON Schema `description`（`setting/catalog.rs` 把 `spec.doc` 原样塞进去），
+/// 所以它不是注释而是**对外文案**：写「缺 Java 时自动下载」等于让启动器自己的助手对用户说
+/// 一件实现刻意不做的事（M197 复审 r1 的 P1）。
+///
+/// 变异证明：把描述改回「缺 Java 时自动下载（D13 基准 JDK17）」⇒ 本用例红（三句断言都会红）。
+#[test]
+fn the_auto_install_description_says_it_never_downloads_by_itself() {
+    let schema = launcher_schema();
+    let doc = schema
+        .spec("java.auto_install")
+        .expect("java.auto_install 必须登记")
+        .doc;
+    assert!(
+        doc.contains("不会自动下载"),
+        "描述必须写明「不会自动下载」（AI 会照这句话告诉用户）：{doc}"
+    );
+    assert!(
+        !doc.contains("缺 Java 时自动下载"),
+        "描述不许再写「缺 Java 时自动下载」：{doc}"
+    );
+    assert!(
+        !doc.contains("D13"),
+        "描述里不许出现内部决策编号（用户与助手都不知道 D13 是什么）：{doc}"
+    );
+}
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..75eedb4
--- /dev/null
+++ b/crates/core/tests/setting/main.rs
@@ -0,0 +1,22 @@
+//! M12（core::setting + platform）集成测试入口。
+//!
+//! cargo 把 `tests//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;
+mod update_keys;
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) -> 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) -> 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) -> 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/core/tests/setting/update_keys.rs b/crates/core/tests/setting/update_keys.rs
new file mode 100644
index 0000000..02f98c8
--- /dev/null
+++ b/crates/core/tests/setting/update_keys.rs
@@ -0,0 +1,354 @@
+//! M161：`update.auto_check` / `update.channel` 的 schema 契约 + 旧 `cache/update/prefs.json` 的迁移。
+//!
+//! 迁移的四条硬约束在这里逐条钉住（幂等 / 不丢 `false` / 新值胜出 / 旧文件退役），
+//! 另外还有一条 schema 层面的：`update.channel` 现在只允许 `stable`——清单里没有的渠道
+//! 写进文件等于「设了但没生效」，宁可让 `config set` 当面拒绝。
+
+use serde_json::json;
+use unlucky_core::setting::document::{RenderMode, SettingDocument};
+use unlucky_core::setting::keys::update::UPDATE_CHANNELS;
+use unlucky_core::setting::keys::{launcher_schema, launcher_version};
+use unlucky_core::setting::schema::{SchemaId, SchemaRef, SchemaVersion};
+use unlucky_core::setting::spec::{Sensitivity, ValueKind};
+use unlucky_core::setting::store::SettingStore;
+use unlucky_core::setting::update_prefs::{
+    self, Migration, Targets, DEFAULT_AUTO_CHECK, DEFAULT_CHANNEL, KEY_AUTO_CHECK, KEY_CHANNEL,
+    RECEIPT_FILE,
+};
+
+use super::common::TempDir;
+
+/// 三个路径（`/config/launcher.json` + `/cache/update/prefs.json` + 收据）。
+fn targets(_temp: &TempDir) -> (String, String, String) {
+    (
+        "config/launcher.json".to_string(),
+        "cache/update/prefs.json".to_string(),
+        format!("config/{RECEIPT_FILE}"),
+    )
+}
+
+fn run(temp: &TempDir) -> Migration {
+    let (launcher, legacy, receipt) = targets(temp);
+    update_prefs::migrate(
+        Targets {
+            launcher: &temp.child(&launcher),
+            legacy: &temp.child(&legacy),
+            receipt: &temp.child(&receipt),
+        },
+        1_700_000_000_000,
+    )
+}
+
+/// 读主配置里的显式值（`None` = 文件里没这个键）。
+fn explicit(temp: &TempDir, key: &str) -> Option {
+    let store = SettingStore::load(temp.child("config/launcher.json"), launcher_schema());
+    store.doc().get(key).cloned()
+}
+
+#[test]
+fn the_two_keys_are_registered_with_the_expected_shape() {
+    let schema = launcher_schema();
+    let auto = schema
+        .spec(KEY_AUTO_CHECK)
+        .expect("update.auto_check 必须登记");
+    assert_eq!(auto.default, json!(DEFAULT_AUTO_CHECK), "出厂是开");
+    assert_eq!(auto.kind, ValueKind::Bool);
+    assert_eq!(
+        auto.ai.sensitivity,
+        Sensitivity::Medium,
+        "改它会让启动器自己下载并替换 exe，AI 改过要留审计痕迹"
+    );
+
+    let channel = schema.spec(KEY_CHANNEL).expect("update.channel 必须登记");
+    assert_eq!(channel.default, json!(DEFAULT_CHANNEL));
+    assert_eq!(channel.kind, ValueKind::Enum(UPDATE_CHANNELS));
+    assert!(schema.validate(KEY_CHANNEL, &json!("stable")).is_ok());
+    // 清单里还没有的渠道：**当面拒绝**（写进文件等于「设了但没生效」）。
+    assert!(schema.validate(KEY_CHANNEL, &json!("beta")).is_err());
+    assert!(schema.validate(KEY_CHANNEL, &json!("nightly")).is_err());
+    assert!(schema.validate(KEY_AUTO_CHECK, &json!(1)).is_err());
+}
+
+#[test]
+fn the_keys_render_in_the_nested_shape() {
+    let (mut document, problems) = SettingDocument::load(&launcher_schema(), &json!({}));
+    assert!(problems.is_empty(), "{problems:?}");
+    // 默认值不落盘：空文档渲染出来不该有 update 段。
+    assert!(
+        document.render(RenderMode::Full).get("update").is_none(),
+        "出厂值不该写进文件"
+    );
+
+    document.set(KEY_AUTO_CHECK, json!(false)).expect("写");
+    document.set(KEY_CHANNEL, json!("stable")).expect("写");
+    let rendered = document.render(RenderMode::Full);
+    assert_eq!(
+        rendered["update"],
+        json!({ "auto_check": false, "channel": "stable" }),
+        "点分键在文件里是嵌套对象（与既有键同一形状）"
+    );
+    // 读回来也要是同一个值（IPC/CLI 都读这一份）。
+    let (reloaded, problems) = SettingDocument::load(&launcher_schema(), &rendered);
+    assert!(problems.is_empty(), "{problems:?}");
+    assert!(
+        !update_prefs::auto_check(&reloaded),
+        "读回来的生效值必须是文件里的 false"
+    );
+    assert_eq!(update_prefs::channel(&reloaded), "stable");
+}
+
+#[test]
+fn a_false_switch_is_migrated_and_the_old_file_is_retired() {
+    let temp = TempDir::new("m161-migrate-false");
+    temp.write("cache/update/prefs.json", r#"{"auto_check": false}"#);
+
+    let outcome = run(&temp);
+    let Migration::Migrated {
+        auto_check,
+        retired,
+        receipt,
+    } = outcome.clone()
+    else {
+        panic!("应当迁入，实际 {outcome:?}");
+    };
+    assert!(!auto_check, "旧文件里的 false 不许被默认值盖掉");
+
+    // 主配置里是显式的 false（不是「缺键取默认」）。
+    assert_eq!(explicit(&temp, KEY_AUTO_CHECK), Some(json!(false)));
+    // 旧文件不能再被读到。
+    assert!(!temp.exists("cache/update/prefs.json"), "旧文件必须退役");
+    assert!(temp.exists("cache/update/prefs.json.migrated"), "留着取证");
+    assert_eq!(retired, temp.child("cache/update/prefs.json.migrated"));
+    // 收据可查：落盘、类型/指纹/端点齐全。
+    assert!(receipt.exists(), "收据要落盘：{}", receipt.display());
+    let text = temp.read(&format!("config/{RECEIPT_FILE}"));
+    assert!(text.contains("\"legacy_config\""), "{text}");
+    assert!(text.contains("prefs.json"), "{text}");
+    assert!(text.contains("launcher.json"), "{text}");
+    assert!(text.contains("\"applied_at_ms\": 1700000000000"), "{text}");
+}
+
+#[test]
+fn running_twice_is_idempotent() {
+    let temp = TempDir::new("m161-migrate-twice");
+    temp.write("cache/update/prefs.json", r#"{"auto_check": false}"#);
+
+    assert!(run(&temp).touched(), "第一遍要真的动手");
+    let after_first = temp.read("config/launcher.json");
+    let receipt_first = temp.read(&format!("config/{RECEIPT_FILE}"));
+
+    // 第二遍：旧文件已经改名 ⇒ 什么都没得做。
+    let second = run(&temp);
+    assert_eq!(second, Migration::Nothing, "第二遍必须是空操作");
+    assert_eq!(temp.read("config/launcher.json"), after_first, "文件不许变");
+    assert_eq!(
+        temp.read(&format!("config/{RECEIPT_FILE}")),
+        receipt_first,
+        "收据也不该被重写（源指纹相同 = 跳过）"
+    );
+}
+
+#[test]
+fn a_missing_legacy_file_is_a_silent_noop() {
+    let temp = TempDir::new("m161-migrate-absent");
+    assert_eq!(run(&temp), Migration::Nothing);
+    // 连主配置都不该建（没有值要写，就不该白建一个文件）。
+    assert!(!temp.exists("config/launcher.json"), "不该凭空建配置");
+    assert!(
+        !temp.exists(&format!("config/{RECEIPT_FILE}")),
+        "不该写收据"
+    );
+}
+
+#[test]
+fn an_explicit_new_value_wins_over_the_legacy_file() {
+    let temp = TempDir::new("m161-migrate-new-wins");
+    temp.write(
+        "config/launcher.json",
+        &json!({
+            "$schema": schema_url(),
+            "schemaVersion": 1,
+            "update": { "auto_check": true }
+        })
+        .to_string(),
+    );
+    temp.write("cache/update/prefs.json", r#"{"auto_check": false}"#);
+
+    let outcome = run(&temp);
+    assert_eq!(
+        outcome.as_str(),
+        "new_value_wins",
+        "主配置里有显式值时不许覆盖：{outcome:?}"
+    );
+    assert_eq!(
+        explicit(&temp, KEY_AUTO_CHECK),
+        Some(json!(true)),
+        "新值胜出"
+    );
+    // 旧文件照样退役（它已经不是真相源），收据也写了。
+    assert!(!temp.exists("cache/update/prefs.json"));
+    assert!(temp.exists(&format!("config/{RECEIPT_FILE}")));
+}
+
+#[test]
+fn the_default_true_is_not_written_but_the_file_still_retires() {
+    let temp = TempDir::new("m161-migrate-default");
+    temp.write("cache/update/prefs.json", r#"{"auto_check": true}"#);
+
+    let outcome = run(&temp);
+    assert_eq!(outcome.as_str(), "migrated");
+    // 「默认值不落盘」：写进去只是噪音，生效值本来就是 true。
+    assert_eq!(explicit(&temp, KEY_AUTO_CHECK), None, "出厂值不落盘");
+    assert!(!temp.exists("cache/update/prefs.json"), "旧文件仍要退役");
+    let store = SettingStore::load(temp.child("config/launcher.json"), launcher_schema());
+    assert!(update_prefs::auto_check(store.doc()));
+}
+
+#[test]
+fn a_corrupt_legacy_file_touches_nothing() {
+    let temp = TempDir::new("m161-migrate-corrupt");
+    temp.write("cache/update/prefs.json", "{ not json");
+    let outcome = run(&temp);
+    assert_eq!(outcome.as_str(), "unreadable", "{outcome:?}");
+    // 坏文件保持原样：下一次还能再试（我们既不猜值也不删证据）。
+    assert!(temp.exists("cache/update/prefs.json"));
+    assert!(!temp.exists(&format!("config/{RECEIPT_FILE}")));
+}
+
+#[test]
+fn an_empty_legacy_file_still_means_the_default() {
+    // `serde(default)`：老文件里没有 auto_check 字段（或整份是 `{}`）⇒ 按出厂值处理，
+    // 而不是把整份文件判成坏文件。
+    let temp = TempDir::new("m161-migrate-empty");
+    temp.write("cache/update/prefs.json", "{}");
+    let outcome = run(&temp);
+    assert_eq!(outcome.as_str(), "migrated");
+    let store = SettingStore::load(temp.child("config/launcher.json"), launcher_schema());
+    assert!(update_prefs::auto_check(store.doc()), "缺字段取出厂值 true");
+}
+
+/// **源指纹闸门**：旧文件还在原地（改名失败 / 用户从备份捞回来）但内容没变 ⇒ 一次都不再迁。
+///
+/// 复审 P2-3：把 `update_prefs.rs` 里那道闸门整段删掉，113 条 setting 用例全绿——因为
+/// `running_twice_is_idempotent` 的第二遍之所以空操作，是第一遍已经把文件改名成 `.migrated`，
+/// **根本没走到闸门**。这条用例是唯一真正撞它的：先按旧文件字节写好收据，再让 `prefs.json`
+/// 原地留着调 `migrate`。
+///
+/// 抓得住：①闸门被删（会走「新值胜出」那一支并**重写收据**，`applied_at_ms` 变）；②指纹比对
+/// 写成「有收据就跳过」而不是「指纹相同才跳过」（下面第二条反证）；③闸门放行时忘了退役旧文件。
+#[test]
+fn the_receipt_gate_skips_a_replayed_source_byte_for_byte() {
+    let temp = TempDir::new("m161-gate-replay");
+    let legacy = temp.write("cache/update/prefs.json", r#"{"auto_check": false}"#);
+    let receipt_path = temp.child(&format!("config/{RECEIPT_FILE}"));
+
+    // 先按真实字节写一张收据（模拟「上一轮迁过、但旧文件又回到了原地」）。
+    let bytes = std::fs::read(&legacy).expect("读旧文件");
+    let receipt = unlucky_core::platform::receipt::MigrationReceipt::legacy_config(
+        legacy.clone(),
+        temp.child("config/launcher.json"),
+        unlucky_core::platform::receipt::fingerprint_bytes(&bytes),
+        1_600_000_000_000,
+    );
+    unlucky_core::platform::receipt::write(&receipt_path, &receipt).expect("写收据");
+    let receipt_before = temp.read(&format!("config/{RECEIPT_FILE}"));
+
+    let outcome = run(&temp);
+    assert_eq!(
+        outcome.as_str(),
+        "nothing",
+        "源指纹相同 ⇒ 必须走闸门（Nothing），实际 {outcome:?}"
+    );
+    // 关键断言：**收据没被重写**（重写 = 走了迁移分支，闸门失效）。
+    assert_eq!(
+        temp.read(&format!("config/{RECEIPT_FILE}")),
+        receipt_before,
+        "收据被重写了 ⇒ 闸门没拦住重放"
+    );
+    // 主配置一个字都没写（闸门那一支只退役旧文件）。
+    assert!(!temp.exists("config/launcher.json"), "闸门放行时不该建配置");
+    // 旧文件仍然退役（它是真相源之外的东西，留着只会下次再撞一次）。
+    assert!(!temp.exists("cache/update/prefs.json"));
+
+    // 反证：源文件**变了**（false → true）⇒ 指纹不同 ⇒ 允许重放，收据被更新。
+    temp.write("cache/update/prefs.json", r#"{"auto_check": true}"#);
+    let outcome = run(&temp);
+    assert_eq!(
+        outcome.as_str(),
+        "migrated",
+        "源内容变了就该重放，实际 {outcome:?}"
+    );
+    assert_ne!(
+        temp.read(&format!("config/{RECEIPT_FILE}")),
+        receipt_before,
+        "重放要写新收据（指纹变了）"
+    );
+}
+
+/// **`Refused`：主配置不可写时不动旧文件**（唯一有用户数据风险的分支）。
+///
+/// 造法：主配置的 `$schema` 写成**比当前更高的 minor**（`launcher_version().minor + 1`）⇒
+/// `SchemaCompat` 判 `ReadOnlyPreserveSchema` ⇒ `FileAccess::ReadOnly` ⇒ `can_save()` false。
+///
+/// **这里刻意不写死数字**（M168 复审 p1-1）：上一版把「更高」写成了字面量 `1.7.0`，于是
+/// `launcher_version()` 一推到 1.7.0 这个夹具就变成「同版本」——文件可写 ⇒ 迁移真的执行 ⇒
+/// 旧文件被退役，`Refused` 分支再也走不到，而**断言还在，绿着**：一条守护用户数据的用例
+/// 就这样静默失效了。相对推导（current + 1）不会过期，版本往后推多少次它都还是「更高一档」。
+/// 抓得住：把「写不进去」当成「迁完了」（旧文件被改名，用户的值两边都没有了）。
+#[test]
+fn a_read_only_launcher_config_never_retires_the_legacy_file() {
+    // 比当前更高一档的 minor：`SchemaRef::url()` 是 `$schema` 的唯一产地，不手拼字符串。
+    let newer = SchemaRef {
+        id: SchemaId::LAUNCHER,
+        version: SchemaVersion::new(
+            launcher_version().major,
+            launcher_version().minor + 1,
+            launcher_version().patch,
+        ),
+    };
+    let newer_schema = newer.url();
+
+    let temp = TempDir::new("m161-refused");
+    temp.write(
+        "config/launcher.json",
+        &json!({
+            "$schema": newer_schema,
+            "schemaVersion": 1
+        })
+        .to_string(),
+    );
+    temp.write("cache/update/prefs.json", r#"{"auto_check": false}"#);
+
+    let outcome = run(&temp);
+    let Migration::Refused { reason } = &outcome else {
+        panic!("只读主配置必须走 Refused，实际 {outcome:?}");
+    };
+    // 拒绝的理由必须是「先看能不能写」这一条（而不是写到一半才发现 `set` 被拒）：
+    // 抓得住把 `can_save()` 守卫删掉这种变异——那条路径的 reason 是「写 update.auto_check 被拒」。
+    assert!(
+        reason.contains("不可写"),
+        "应当在动手前就判定主配置不可写，实际理由：{reason}"
+    );
+    // 旧文件原样留着（下一次还能再试）。
+    assert!(
+        temp.exists("cache/update/prefs.json"),
+        "写不进去时**不许**退役旧文件——用户的值不能两边都没有"
+    );
+    assert!(
+        !temp.exists("cache/update/prefs.json.migrated"),
+        "不许留下「已迁移」的痕迹"
+    );
+    // 不写收据（没迁成就不该有收据）。
+    assert!(!temp.exists(&format!("config/{RECEIPT_FILE}")));
+    // 主配置一个字都没改（还是那份「更高 minor」的 `$schema`）。
+    let text = temp.read("config/launcher.json");
+    assert!(text.contains(&newer_schema), "主配置被改了：{text}");
+    assert!(!text.contains("auto_check"), "只读文件不许被写：{text}");
+}
+
+/// 真 `$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()
+}
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/boards/ink.rs b/crates/design/src/color/boards/ink.rs
new file mode 100644
index 0000000..a6d1109
--- /dev/null
+++ b/crates/design/src/color/boards/ink.rs
@@ -0,0 +1,117 @@
+//! **Ink Cat 深色板**（规格卡 `DevDocs/artifacts/components-ink.svg` 的深色方案）。
+//!
+//! 49 行按 [`Role`] 声明序排列（下标 = `Role as usize`），由 `boards` 模块的
+//! `anchors_pin_the_spec` 测试用 [`ANCHORS`] 逐条对账——**行错位会当场红**。
+//!
+//! 取值分两类，来源都在行注释里：
+//! - `[spec]`：规格卡上直接写出的色值（[`ANCHORS`] 里同一份，测试逐条比对 hex）；
+//! - `[derive]`：规格卡没给的角色，按「同色相 + M3 的 tone 关系」从邻居推导后固化。
+//!
+//! 推导口径（`[derive]` 行）：容器/文字的 tone 差沿用 M3 ColorSpec2021 的成对关系
+//! （`on-*` 与承载色差 ≥50 tone 才稳过 AA），色相取承载色的 CAM16 色相，彩度只压不抬。
+//! 换算过程是 `Hct::from_components(hue, chroma, tone)`，结果已固化成字面量，不在运行期重算——
+//! 这样色板是**可逐值审阅的数据**，而不是「跑一遍才知道」的产物。
+
+use crate::color::{Color, Role};
+
+/// 规格卡直接给出的色值（`[spec]` 行），用于逐条对账与文档生成。
+///
+/// 顺序即规格卡上出现的顺序（BUTTONS → FAB → TEXT FIELDS → SWITCH/CHIPS → CARD/DIALOG/SNACKBAR
+/// → COLOR ROLES / INK）。**这张表是色板的出处**：表里的值改了，测试 `anchors_pin_the_spec`
+/// 会指着要改的行。
+pub const ANCHORS: [(Role, &str); 22] = [
+    (Role::Primary, "#E8FFEF"),
+    (Role::OnPrimary, "#256B4B"),
+    (Role::PrimaryContainer, "#B3FBD2"),
+    (Role::OnPrimaryContainer, "#1B6243"),
+    (Role::Secondary, "#B4CCBC"),
+    (Role::SecondaryContainer, "#364B3F"),
+    (Role::OnSecondaryContainer, "#D0E8D7"),
+    (Role::Tertiary, "#FFB77D"),
+    (Role::TertiaryContainer, "#FFA453"),
+    (Role::Surface, "#0F150F"),
+    (Role::SurfaceContainer, "#151B15"),
+    (Role::SurfaceContainerHigh, "#1D231D"),
+    (Role::SurfaceContainerHighest, "#262B25"),
+    (Role::OnSurface, "#E4EAE0"),
+    (Role::OnSurfaceVariant, "#B6C5B4"),
+    (Role::Outline, "#7B8A7B"),
+    (Role::OutlineVariant, "#3C4A3D"),
+    (Role::Error, "#FF716C"),
+    (Role::OnError, "#490006"),
+    (Role::InverseSurface, "#E4EAE0"),
+    (Role::InverseOnSurface, "#282E27"),
+    (Role::InversePrimary, "#256B4B"),
+];
+
+/// Ink 板 49 个角色（下标 = `Role as usize`）。
+pub const COLORS: [Color; 49] = [
+    Color::rgb(0xE8, 0xFF, 0xEF), // 01 primary            [spec] 按钮/文字按钮标签、进度、选中
+    Color::rgb(0x25, 0x6B, 0x4B), // 02 on-primary         [spec]
+    Color::rgb(0xB3, 0xFB, 0xD2), // 03 primary-container  [spec] FAB 底、头像底
+    Color::rgb(0x1B, 0x62, 0x43), // 04 on-primary-container [spec] FAB 图标
+    Color::rgb(0xB4, 0xCC, 0xBC), // 05 secondary          [spec]
+    Color::rgb(0x37, 0x4B, 0x3E), // 06 on-secondary       [derive] secondary @ tone 30
+    Color::rgb(0x36, 0x4B, 0x3F), // 07 secondary-container [spec] tonal 按钮底、选中 chip
+    Color::rgb(0xD0, 0xE8, 0xD7), // 08 on-secondary-container [spec] tonal 按钮标签
+    Color::rgb(0xFF, 0xB7, 0x7D), // 09 tertiary           [spec] 暖橙装饰
+    Color::rgb(0x55, 0x2B, 0x00), // 10 on-tertiary        [derive] tertiary @ tone 22
+    Color::rgb(0xFF, 0xA4, 0x53), // 11 tertiary-container  [spec]
+    Color::rgb(0x4C, 0x27, 0x00), // 12 on-tertiary-container [derive] container @ tone 20
+    Color::rgb(0xFF, 0x71, 0x6C), // 13 error              [spec] 错误文字、badge 底
+    Color::rgb(0x49, 0x00, 0x06), // 14 on-error           [spec] badge 数字
+    Color::rgb(0x93, 0x00, 0x0A), // 15 error-container    [derive] error @ tone 30（= M3 深色 error-container）
+    Color::rgb(0xFF, 0xDA, 0xD6), // 16 on-error-container [derive] error @ tone 90
+    Color::rgb(0x0F, 0x15, 0x0F), // 17 surface            [spec] 窗口底
+    Color::rgb(0xE4, 0xEA, 0xE0), // 18 on-surface         [spec] 正文/标题
+    Color::rgb(0x3C, 0x4A, 0x3D), // 19 surface-variant    [spec]（= outline-variant，M3 深色同 tone）
+    Color::rgb(0xB6, 0xC5, 0xB4), // 20 on-surface-variant [spec] 次要文字、字段标签
+    Color::rgb(0x0F, 0x15, 0x0F), // 21 background         [spec]（= surface）
+    Color::rgb(0xE4, 0xEA, 0xE0), // 22 on-background      [spec]（= on-surface）
+    Color::rgb(0x0C, 0x13, 0x0C), // 23 surface-dim        [derive] surface −1 tone 档
+    Color::rgb(0x35, 0x3C, 0x34), // 24 surface-bright     [derive] surface @ tone 24
+    Color::rgb(0x08, 0x0D, 0x08), // 25 surface-container-lowest [derive] tone 3
+    Color::rgb(0x13, 0x18, 0x13), // 26 surface-container-low [derive] tone 8
+    Color::rgb(0x15, 0x1B, 0x15), // 27 surface-container  [spec] 卡片/列表行底
+    Color::rgb(0x1D, 0x23, 0x1D), // 28 surface-container-high [spec] 对话框底
+    Color::rgb(0x26, 0x2B, 0x25), // 29 surface-container-highest [spec] 输入框底
+    Color::rgb(0x7B, 0x8A, 0x7B), // 30 outline            [spec] 字段描边、switch 关态
+    Color::rgb(0x3C, 0x4A, 0x3D), // 31 outline-variant    [spec] 分隔线、chip 描边
+    Color::rgb(0xE4, 0xEA, 0xE0), // 32 inverse-surface    [spec] snackbar 底
+    Color::rgb(0x28, 0x2E, 0x27), // 33 inverse-on-surface [spec] snackbar 文字
+    Color::rgb(0x25, 0x6B, 0x4B), // 34 inverse-primary    [spec] snackbar 动作文字
+    Color::rgb(0x00, 0x00, 0x00), // 35 shadow             M3 定值：纯黑 + 令牌 alpha
+    Color::rgb(0x00, 0x00, 0x00), // 36 scrim              M3 定值：纯黑 + 令牌 alpha
+    Color::rgb(0xE8, 0xFF, 0xEF), // 37 surface-tint       = primary（M3 旧 tint 口径）
+    Color::rgb(0xB3, 0xFB, 0xD2), // 38 primary-fixed      [derive] tone 93（= container）
+    Color::rgb(0x9D, 0xE4, 0xBC), // 39 primary-fixed-dim  [derive] tone 85
+    Color::rgb(0x00, 0x26, 0x14), // 40 on-primary-fixed   [derive] tone 12
+    Color::rgb(0x00, 0x4D, 0x2E), // 41 on-primary-fixed-variant [derive] tone 28
+    Color::rgb(0xD0, 0xE8, 0xD7), // 42 secondary-fixed    [derive] tone 90
+    Color::rgb(0xB4, 0xCC, 0xBC), // 43 secondary-fixed-dim [derive] tone 80
+    Color::rgb(0x0D, 0x1F, 0x14), // 44 on-secondary-fixed [derive] tone 10
+    Color::rgb(0x33, 0x47, 0x39), // 45 on-secondary-fixed-variant [derive] tone 28
+    Color::rgb(0xFC, 0xD9, 0xBE), // 46 tertiary-fixed     [derive] tone 89
+    Color::rgb(0xFF, 0xB7, 0x7D), // 47 tertiary-fixed-dim [derive] tone 80（= tertiary）
+    Color::rgb(0x2A, 0x17, 0x00), // 48 on-tertiary-fixed  [derive] tone 10
+    Color::rgb(0x56, 0x3D, 0x27), // 49 on-tertiary-fixed-variant [derive] tone 28
+];
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn anchors_pin_the_spec() {
+        for (role, hex) in ANCHORS {
+            let expected = Color::from_hex(hex).expect("规格卡色值");
+            assert_eq!(
+                COLORS[role as usize],
+                expected,
+                "{} 的色值与规格卡（{hex}）不符：表里是 {}",
+                role.name(),
+                COLORS[role as usize].to_hex()
+            );
+        }
+    }
+}
diff --git a/crates/design/src/color/boards/mod.rs b/crates/design/src/color/boards/mod.rs
new file mode 100644
index 0000000..748a1da
--- /dev/null
+++ b/crates/design/src/color/boards/mod.rs
@@ -0,0 +1,201 @@
+//! # 双主题色板（Ink 深 / Silver 浅）
+//!
+//! 产品视觉的两套固定色板，来源是**用户自制的规格卡** `DevDocs/artifacts/components-ink.svg`
+//! （Ink Cat / M3 Expressive，1480×2260，色值/圆角/尺寸/字号全在源码里）。本模块只做一件事：
+//! **把规格卡的色值固化成 49 个 M3 角色 × 2 套**，让 iced 侧拿到的仍是
+//! [`Scheme`](crate::color::Scheme)——角色名、取色入口、对比度门禁一个都不用换。
+//!
+//! ## 两层配色来源，互不顶替
+//!
+//! | 来源 | 入口 | 什么时候用 |
+//! |---|---|---|
+//! | **品牌色板**（本模块） | [`BrandBoard`] → [`Scheme::from_board`](crate::color::Scheme::from_board) | 出厂外观：Ink = 深色主方案、Silver = 浅色主方案 |
+//! | **tone 派生**（既有） | [`Scheme::baseline`](crate::color::Scheme::baseline) / [`Scheme::from_accent`](crate::color::Scheme::from_accent) | D38 取色链（背景图 / 壁纸取色、用户自选强调色） |
+//!
+//! **为什么保留 `baseline` 而不是把它换成色板**（「保留旧令牌名兼容层」这一选，理由）：
+//!
+//! 1. `Scheme::baseline` 是 D38 取色链的**中性锚点**：`from_accent` 的全部语义就是「表面色与
+//!    baseline 一致、只换强调族」。把 baseline 改成固定板，取色链要么改语义、要么在板色上再叠
+//!    一层 tone 派生，两者都会让「换强调色不该让窗口底色变脏」这条产品口径失效。
+//! 2. 改 `baseline` 的色值等于**同时改 app-iced 的观感**（`theme::Ui::new` 直接吃 baseline），
+//!    而换肤（含截图验收）归 M229；令牌层先把两套板备好，再让壳层一次性切过去，比「两处各改一半」
+//!    可控。
+//! 3. 兼容层是**零成本**的：`Role` 名字与 49 个下标一个没动，新增的是并列入口而不是替换入口。
+//!
+//! ## 「跟随系统」是第三种设置态，不是第三套色板
+//!
+//! 外观设置有三态：浅色 / 深色 / 跟随系统。前两态直接选板，第三态按系统外观落到
+//! [`BrandBoard::for_flavor`]。色板本身只有两套，**不要**再加一个 `System` 变体——那会让
+//! 「两套板」变成「三套板」，而系统外观随时会变，色板却应该是静态的。
+//!
+//! ## 色值来源分两类（`[spec]` / `[derive]`）
+//!
+//! - **`[spec]`**：规格卡直写。每块的 [`BrandBoard::anchors`] 表就是这份清单，测试逐条比对 hex，
+//!   所以「规格卡改了但代码没改」会红。
+//! - **`[derive]`**：规格卡没给的角色（`on-secondary`、`surface-container-low`、`*-fixed*` 等），
+//!   按「同色相 + M3 的 tone 关系」从邻居推导后**固化成字面量**。推导规则写在
+//!   `boards/ink.rs` / `boards/silver.rs` 的模块文档与行注释里，运行期不重算——色板是数据，
+//!   不是每次启动现算的函数。
+//!
+//! ## 对比度纪律（两套板同一道门，数字见 `palette::visibility` 的实测表）
+//!
+//! - 26 组文字/图标对两套板全部 ≥4.5:1（`tests/ink_cat_boards.rs`）；
+//! - **状态容器**（primary / secondary / tertiary / error 的 `*-container`）对 `surface` ≥
+//!   [`crate::palette::visibility::STATE_CONTAINER_MIN`]（1.20:1）——这是债务台账
+//!   「SecondaryContainer 对 Surface 仅 1.06」的令牌层裁决：旧 baseline 的选中行底实测
+//!   **1.057:1**（m223 视觉复审），Ink 板抬到 **1.97:1**、Silver 板 **1.23:1**；
+//! - **层级容器**（`surface-container-*`）不参与那条数字门禁，只要求 L\\* 沿阶梯单调、相邻步长
+//!   ≥ [`crate::palette::visibility::LAYER_STEP_MIN_LSTAR`]。M3 的容器层天生贴在一起
+//!   （Silver 的状态容器压在容器层上实测最低 **1.02**、Ink 最低 1.54，见 `palette::visibility`
+//!   的实测表），所以裁决第 3 条是**构成要求**：选中态必须「容器底 + 文字对比 + 形状/图标/描边」
+//!   三件套，不许只靠底色差。
+
+mod ink;
+mod silver;
+
+use super::{Color, Role, Scheme, SchemeFlavor};
+
+/// 产品色板（两套，与深浅模式一一对应）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum BrandBoard {
+    /// **Ink Cat**：深色主方案（规格卡 `COLOR ROLES / INK`）。窗口底 `#0F150F`，主色淡绿。
+    Ink,
+    /// **Silver Cat**：浅色主方案（规格卡 `SILVER CAT / LIGHT SCHEME`）。窗口底 `#F9F9FA`，主色钢蓝。
+    Silver,
+}
+
+impl BrandBoard {
+    /// 全部色板（由深到浅）。
+    pub const ALL: [BrandBoard; 2] = [BrandBoard::Ink, BrandBoard::Silver];
+
+    /// 稳定字符串名（`ink` / `silver`），写配置与日志用。
+    pub const fn name(self) -> &'static str {
+        match self {
+            BrandBoard::Ink => "ink",
+            BrandBoard::Silver => "silver",
+        }
+    }
+
+    /// 该板对应的深浅模式（Ink = 深、Silver = 浅）。
+    pub const fn flavor(self) -> SchemeFlavor {
+        match self {
+            BrandBoard::Ink => SchemeFlavor::Dark,
+            BrandBoard::Silver => SchemeFlavor::Light,
+        }
+    }
+
+    /// 按深浅模式选板——这就是「跟随系统」的落点。
+    pub const fn for_flavor(flavor: SchemeFlavor) -> Self {
+        match flavor {
+            SchemeFlavor::Dark => BrandBoard::Ink,
+            SchemeFlavor::Light => BrandBoard::Silver,
+        }
+    }
+
+    /// 49 个角色的色值表（下标 = `Role as usize`）。
+    pub const fn colors(self) -> [Color; 49] {
+        match self {
+            BrandBoard::Ink => ink::COLORS,
+            BrandBoard::Silver => silver::COLORS,
+        }
+    }
+
+    /// 直接取角色色值。
+    pub const fn get(self, role: Role) -> Color {
+        self.colors()[role as usize]
+    }
+
+    /// 规格卡直写的色值清单（`[spec]` 行），出处对账与文档生成用。
+    pub const fn anchors(self) -> &'static [(Role, &'static str)] {
+        match self {
+            BrandBoard::Ink => &ink::ANCHORS,
+            BrandBoard::Silver => &silver::ANCHORS,
+        }
+    }
+
+    /// 这套色板对应的完整语义方案。
+    pub fn scheme(self) -> Scheme {
+        Scheme::from_board(self)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::collections::BTreeSet;
+
+    #[test]
+    fn boards_map_to_flavors_both_ways() {
+        for board in BrandBoard::ALL {
+            assert_eq!(BrandBoard::for_flavor(board.flavor()), board);
+        }
+        assert_eq!(
+            BrandBoard::for_flavor(SchemeFlavor::Light),
+            BrandBoard::Silver
+        );
+        assert_eq!(BrandBoard::for_flavor(SchemeFlavor::Dark), BrandBoard::Ink);
+    }
+
+    #[test]
+    fn names_are_unique_and_ascii() {
+        let mut seen = BTreeSet::new();
+        for board in BrandBoard::ALL {
+            let name = board.name();
+            assert!(seen.insert(name), "色板名重复：{name}");
+            assert!(name.chars().all(|c| c.is_ascii_lowercase()));
+        }
+    }
+
+    #[test]
+    fn every_role_is_opaque_on_both_boards() {
+        for board in BrandBoard::ALL {
+            for role in Role::ALL {
+                assert!(
+                    board.get(role).is_opaque(),
+                    "{} 的 {} 不是不透明色",
+                    board.name(),
+                    role.name()
+                );
+            }
+        }
+    }
+
+    #[test]
+    fn anchors_are_a_subset_of_the_board() {
+        for board in BrandBoard::ALL {
+            for (role, hex) in board.anchors() {
+                assert_eq!(
+                    board.get(*role),
+                    Color::from_hex(hex).expect("规格卡色值"),
+                    "{} 的 {} 与规格卡 {hex} 不符",
+                    board.name(),
+                    role.name()
+                );
+            }
+        }
+    }
+
+    #[test]
+    fn scheme_flavor_follows_the_board() {
+        for board in BrandBoard::ALL {
+            assert_eq!(board.scheme().flavor(), board.flavor());
+        }
+        // 深板确实深、浅板确实浅（不是两个同义词）。
+        let ink = BrandBoard::Ink.get(Role::Surface).relative_luminance();
+        let silver = BrandBoard::Silver.get(Role::Surface).relative_luminance();
+        assert!(ink < 0.02, "Ink 的窗口底太亮：{ink}");
+        assert!(silver > 0.9, "Silver 的窗口底太暗：{silver}");
+    }
+
+    #[test]
+    fn the_two_boards_are_actually_different() {
+        let ink = BrandBoard::Ink.colors();
+        let silver = BrandBoard::Silver.colors();
+        let same = Role::ALL
+            .iter()
+            .filter(|role| ink[**role as usize] == silver[**role as usize])
+            .count();
+        // 只有 shadow / scrim（纯黑，M3 定值）该跨板同值——其余都得变。
+        assert_eq!(same, 2, "跨板同值的角色数应从 2（shadow/scrim）开始算");
+    }
+}
diff --git a/crates/design/src/color/boards/silver.rs b/crates/design/src/color/boards/silver.rs
new file mode 100644
index 0000000..045b66f
--- /dev/null
+++ b/crates/design/src/color/boards/silver.rs
@@ -0,0 +1,105 @@
+//! **Silver Cat 浅色板**（规格卡 `SILVER CAT / LIGHT SCHEME` 一节 + 同页浅色字段/按钮）。
+//!
+//! 与 [`super::ink`] 同一套口径：49 行按 [`Role`] 声明序排列，`[spec]` = 规格卡直写值
+//! （与 [`ANCHORS`] 同源，测试逐条比对 hex），`[derive]` = 按同色相 + M3 tone 关系推导后固化。
+
+use crate::color::{Color, Role};
+
+/// 规格卡直接给出的浅色色值，逐条对账用。
+///
+/// 出处分三处：SILVER CAT / LIGHT SCHEME 的色板行、同页 Filled/Tonal/Outlined 按钮与两个字段
+/// （`on-primary` 取自 Filled 的文字 `#f6f9ff`、`on-secondary-container` 取自 Tonal 的文字
+/// `#0d1d2a`、`outline-variant` 取自色板方块的描边 `#bec8cd`）。
+///
+/// ⚠️ 字段底 `#dcddde` 落在 **`surface-container-highest`**（不是 high）：它与 Ink 的字段底
+/// `#262b25` 是同一层角色（`component_map` 的 `TextField` 口径 = 最高容器层）。浅色板的
+/// `surface-container-high` 因此是**推导值** `#e4e4e5`（tone 90），只为让阶梯在 94.1 → 88.1
+/// 之间保持单调、步长 ≥1.0 L\\*；若把 `#dcddde` 定在 high，Silver 的字段底会比 Ink 低一层，
+/// 单一角色接法（只读 Highest）会读到 4.38:1 的 `Error` 标签（掉 AA）。
+pub const ANCHORS: [(Role, &str); 13] = [
+    (Role::Primary, "#006499"),
+    (Role::OnPrimary, "#F6F9FF"),
+    (Role::PrimaryContainer, "#87C7FF"),
+    (Role::SecondaryContainer, "#D4E4F6"),
+    (Role::OnSecondaryContainer, "#0D1D2A"),
+    (Role::Surface, "#F9F9FA"),
+    (Role::SurfaceContainer, "#EEEEEF"),
+    (Role::SurfaceContainerHighest, "#DCDDDE"),
+    (Role::OnSurface, "#1A1C1D"),
+    (Role::OnSurfaceVariant, "#434D51"),
+    (Role::Outline, "#6F797D"),
+    (Role::OutlineVariant, "#BEC8CD"),
+    (Role::Error, "#AC3434"),
+];
+
+/// Silver 板 49 个角色（下标 = `Role as usize`）。
+pub const COLORS: [Color; 49] = [
+    Color::rgb(0x00, 0x64, 0x99), // 01 primary            [spec] 实心按钮底、文字按钮标签
+    Color::rgb(0xF6, 0xF9, 0xFF), // 02 on-primary         [spec] Filled 按钮文字
+    Color::rgb(0x87, 0xC7, 0xFF), // 03 primary-container  [spec]
+    Color::rgb(0x00, 0x34, 0x4E), // 04 on-primary-container [derive] container @ tone 20
+    Color::rgb(0x4A, 0x60, 0x76), // 05 secondary          [derive] tone 40，蓝灰
+    Color::rgb(0xF6, 0xF9, 0xFF), // 06 on-secondary       [derive] tone 98
+    Color::rgb(0xD4, 0xE4, 0xF6), // 07 secondary-container [spec] Tonal 按钮底、选中 chip
+    Color::rgb(0x0D, 0x1D, 0x2A), // 08 on-secondary-container [spec] Tonal 按钮文字
+    Color::rgb(0x7C, 0x52, 0x25), // 09 tertiary           [derive] tone 40，暖棕（与主色互补）
+    Color::rgb(0xFF, 0xFF, 0xFF), // 10 on-tertiary        [derive] tone 100
+    Color::rgb(0xFF, 0xDC, 0xC1), // 11 tertiary-container [derive] tone 90
+    Color::rgb(0x2B, 0x17, 0x00), // 12 on-tertiary-container [derive] tone 10
+    Color::rgb(0xAC, 0x34, 0x34), // 13 error              [spec] 错误文字
+    Color::rgb(0xFF, 0xFF, 0xFF), // 14 on-error           [derive] tone 100
+    Color::rgb(0xFF, 0xDA, 0xD6), // 15 error-container    [derive] error @ tone 90
+    Color::rgb(0x41, 0x00, 0x02), // 16 on-error-container [derive] error @ tone 10
+    Color::rgb(0xF9, 0xF9, 0xFA), // 17 surface            [spec] 窗口底
+    Color::rgb(0x1A, 0x1C, 0x1D), // 18 on-surface         [spec] 正文/标题
+    Color::rgb(0xD9, 0xDE, 0xE2), // 19 surface-variant    [derive] neutral-variant tone 88
+    Color::rgb(0x43, 0x4D, 0x51), // 20 on-surface-variant [spec] 次要文字、字段标签
+    Color::rgb(0xF9, 0xF9, 0xFA), // 21 background         [spec]（= surface）
+    Color::rgb(0x1A, 0x1C, 0x1D), // 22 on-background      [spec]（= on-surface）
+    Color::rgb(0xD8, 0xDA, 0xDA), // 23 surface-dim        [derive] tone 87
+    Color::rgb(0xF9, 0xF9, 0xFA), // 24 surface-bright     [derive]（= surface，M3 浅色同 tone 98）
+    Color::rgb(0xFF, 0xFF, 0xFF), // 25 surface-container-lowest [derive] tone 100
+    Color::rgb(0xF3, 0xF3, 0xF4), // 26 surface-container-low [derive] tone 96
+    Color::rgb(0xEE, 0xEE, 0xEF), // 27 surface-container  [spec] 卡片/列表行底
+    Color::rgb(0xE4, 0xE4, 0xE5), // 28 surface-container-high [derive] tone 90（比 highest 高 2.5 L*，阶梯步长 3.5）
+    Color::rgb(0xDC, 0xDD, 0xDE), // 29 surface-container-highest [spec] 输入框底（与 Ink 的 #262B25 同位：字段底就是最高容器层）
+    Color::rgb(0x6F, 0x79, 0x7D), // 30 outline            [spec] 字段描边
+    Color::rgb(0xBE, 0xC8, 0xCD), // 31 outline-variant    [spec] 分隔线、chip 描边
+    Color::rgb(0x2F, 0x31, 0x33), // 32 inverse-surface    [derive] tone 20
+    Color::rgb(0xF0, 0xF0, 0xF1), // 33 inverse-on-surface [derive] tone 95
+    Color::rgb(0x87, 0xC7, 0xFF), // 34 inverse-primary    [derive]（= primary-container）
+    Color::rgb(0x00, 0x00, 0x00), // 35 shadow             M3 定值：纯黑 + 令牌 alpha
+    Color::rgb(0x00, 0x00, 0x00), // 36 scrim              M3 定值：纯黑 + 令牌 alpha
+    Color::rgb(0x00, 0x64, 0x99), // 37 surface-tint       = primary（M3 旧 tint 口径）
+    Color::rgb(0x87, 0xC7, 0xFF), // 38 primary-fixed      [derive] tone 78（= container）
+    Color::rgb(0x5F, 0xAE, 0xE6), // 39 primary-fixed-dim  [derive] tone 68
+    Color::rgb(0x00, 0x1E, 0x2E), // 40 on-primary-fixed   [derive] tone 10
+    Color::rgb(0x00, 0x3A, 0x57), // 41 on-primary-fixed-variant [derive] tone 23
+    Color::rgb(0xD4, 0xE4, 0xF6), // 42 secondary-fixed    [derive] tone 90
+    Color::rgb(0xB8, 0xC8, 0xDA), // 43 secondary-fixed-dim [derive] tone 80
+    Color::rgb(0x0D, 0x1D, 0x2A), // 44 on-secondary-fixed [derive] tone 10
+    Color::rgb(0x33, 0x48, 0x5A), // 45 on-secondary-fixed-variant [derive] tone 30
+    Color::rgb(0xFF, 0xDC, 0xC1), // 46 tertiary-fixed     [derive] tone 90
+    Color::rgb(0xF0, 0xBD, 0x8E), // 47 tertiary-fixed-dim [derive] tone 80
+    Color::rgb(0x2B, 0x17, 0x00), // 48 on-tertiary-fixed  [derive] tone 10
+    Color::rgb(0x5E, 0x3F, 0x1A), // 49 on-tertiary-fixed-variant [derive] tone 29
+];
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn anchors_pin_the_spec() {
+        for (role, hex) in ANCHORS {
+            let expected = Color::from_hex(hex).expect("规格卡色值");
+            assert_eq!(
+                COLORS[role as usize],
+                expected,
+                "{} 的色值与规格卡（{hex}）不符：表里是 {}",
+                role.name(),
+                COLORS[role as usize].to_hex()
+            );
+        }
+    }
+}
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 {
+    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..6109cf1
--- /dev/null
+++ b/crates/design/src/color/mod.rs
@@ -0,0 +1,341 @@
+//! # 色彩令牌（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：浅冷天蓝）——含**两处**有意偏离（同一处偏离的两半）
+//!
+//! > **口径更新（M228）**：出厂外观的入口是 `DesignTokens::brand`（Ink / Silver 两套固化色板，
+//! > 见 [`crate::color::boards`]）。本节描述的「浅冷天蓝」**仍是 D38 取色链的中性锚点**
+//! > （`Scheme::baseline` / `from_accent` 的表面色基准），不再是「产品出厂看起来长什么样」。
+//!
+//! 产品默认不走官方紫，而是「浅冷天蓝」。默认值收在两个常量里，**换默认只改这两行**
+//! （用户 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 boards;
+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 boards::BrandBoard;
+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 {
+        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..799c00b
--- /dev/null
+++ b/crates/design/src/color/palettes.rs
@@ -0,0 +1,399 @@
+//! 六条 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 / M228 口径更新）
+//!
+//! | 入口 | 种子 | 中性彩度 | 用途 |
+//! |---|---|---|---|
+//! | [`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`] | **D38 取色链的中性锚点**（`from_accent` 的表面色基准）。M228 起**出厂外观**的入口是 `DesignTokens::brand`（Ink / Silver 固化板），不是这里 |
+//!
+//! 换默认色只改 [`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 的默认基线同值）；**不是**产品色——
+/// 产品外观见 `DesignTokens::brand`，取色链锚点见 [`DEFAULT_SEED`]。
+pub const BASELINE_SEED: Color = Color::rgb(0x67, 0x50, 0xA4);
+
+/// 取色链的锚点种子色 —— M70 候选④「天蓝」，**用户 2026-11-01 拍板采用**；M228 起产品出厂
+/// 外观走 `DesignTokens::brand`（Ink / Silver 固化板），本常量只影响 D38 取色链。
+///
+/// `#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 {
+    /// **D38 取色链的中性锚点**：种子 [`DEFAULT_SEED`] + 中性彩度 [`DEFAULT_NEUTRAL_CHROMA`]。
+    ///
+    /// 用途只剩一条：给「莫奈关闭时的机内色卡」与 [`super::Scheme::from_accent`] 提供中性表面色
+    /// 基准。**M228 起产品出厂外观走 `DesignTokens::brand`**（[`super::boards::BrandBoard`] 的
+    /// Ink / Silver 板），改这两个常量**不再改变用户看到的默认外观**，只影响取色链。
+    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();
+        // 中性色相取**种子色相的实测值**而不是 `NEUTRAL_HUE_DEG` 字面量：两者只差 `atan2()` 的末位
+        // （见下一条测试），逐位比会在 glibc 与 UCRT 之间翻脸；取实测值两侧同源，断言仍是逐位相等。
+        let per_seed = Palettes::from_seed_with_neutral_chroma(DEFAULT_SEED, 12.0);
+        let seed_hue = per_seed.neutral.hue_deg();
+        let same = Palettes::accent_on_fixed_neutral(DEFAULT_SEED, seed_hue, 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..8768855
--- /dev/null
+++ b/crates/design/src/color/scheme.rs
@@ -0,0 +1,360 @@
+//! 一套完整的 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::boards::BrandBoard;
+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 {
+    /// **D38 取色链的中性锚点**（种子 [`super::palettes::DEFAULT_SEED`] + 中性彩度
+    /// [`super::palettes::DEFAULT_NEUTRAL_CHROMA`]，见 [`Palettes::baseline`]）。
+    ///
+    /// M228 起**产品出厂外观**走 [`Scheme::from_board`]（Ink / Silver 固化色板）；本入口保留给
+    /// 取色链与 [`Scheme::from_accent`] 的表面色基准，两者并列而不是互相替换（理由见
+    /// [`super::boards`] 的模块文档）。
+    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 }
+    }
+
+    /// **品牌色板**（Ink 深 / Silver 浅）→ 完整方案：`unlucky_design::color::BrandBoard`。
+    ///
+    /// 与 [`Scheme::baseline`] 的区别不是算法而是**来源**：baseline 由种子 + tone 表推导（D38
+    /// 取色链），本入口直接吃用户规格卡固化的 49 个色值（`color::boards`）。深浅模式由板自己
+    /// 决定（`BrandBoard::flavor`），所以不需要再传 [`SchemeFlavor`]——穿错了会得到「深板浅色」
+    /// 这种自相矛盾的方案。
+    pub fn from_board(board: BrandBoard) -> Self {
+        Self {
+            flavor: board.flavor(),
+            colors: board.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 + '_ {
+        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 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.` 里**真的调了**
+///   `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 里出现」，**不是「字段不存在」**）。
+///
+/// 我们的实现在 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 字节码 ``）。
+///
+/// **不适用于按钮容器**：按钮是 [`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` 的 ``）：
+    /// `*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 = 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,
+    /// 描边 / 环线宽度（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 {
+    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,
+    /// 高程级别（决定 surface container 角色与是否画阴影）。
+    pub elevation: Elevation,
+    /// 主要文字角色。**无文字的组件（如 `Divider`）这里是占位值**，消费方不得据此排版。
+    pub text: TypeRole,
+    /// 辅助文字角色。
+    pub support: Option,
+    /// 状态过渡缓动。
+    ///
+    /// 该字段不是 `Option`，所以**没有动效语义的组件（如 `Divider`）这里是占位值**——
+    /// 读之前先确认组件本身有状态过渡，无过渡的组件不得据此排动效。
+    pub motion: Easing,
+    /// 状态过渡时长。
+    pub duration: DurationToken,
+    /// 按下/选中时的形状形变。
+    pub morph: Option,
+}
+
+/// 需要固定档位的组件清单（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 {
+        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` 的各组件 `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,
+    motion: Easing,
+    duration: DurationToken,
+    morph: Option,
+) -> 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,
+    motion: Easing,
+    duration: DurationToken,
+    morph: Option,
+) -> 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 = 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.` 里 `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::() {
+                    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 = 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. 的 `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/inkcat/metrics.rs b/crates/design/src/inkcat/metrics.rs
new file mode 100644
index 0000000..9e20aa1
--- /dev/null
+++ b/crates/design/src/inkcat/metrics.rs
@@ -0,0 +1,255 @@
+//! 控件方框几何（规格卡的 `CARD / DIALOG / SNACKBAR / LIST`、`TEXT FIELDS`、`SWITCH / CHECKBOX /
+//! RADIO / CHIPS`、`PROGRESS` 五节）。
+//!
+//! 口径与 [`crate::component_map::ComponentMetrics`] 一致：`width`/`height` 为 `0.0` 表示
+//! **由内容决定**（自适应宽），不是「尺寸为零」。差别只在**来源**——这里是规格卡的值，
+//! `component_map` 是官方组件令牌的值，两者不一致处已在 [`super`] 的登记表里逐条写明。
+//!
+//! 圆角一律引用 [`ShapeScale`]，不写裸数字；`SpecBox::radius_px()` 用**高度**折算
+//! （药丸按高的一半、非药丸按刻度值且不超过半高），所以同一个结构既能表达 60 高药丸行（30），
+//! 也能表达 150 高圆角卡（16）。
+
+use crate::shape::ShapeScale;
+
+/// 一个控件方框（宽 / 高 / 圆角档）。`0.0` = 由内容决定。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct SpecBox {
+    /// 可见外框宽（px；`0.0` = 自适应）。
+    pub width: f32,
+    /// 可见外框高（px）。
+    pub height: f32,
+    /// 圆角档（[`ShapeScale`] 的刻度值）。
+    pub shape: ShapeScale,
+}
+
+impl SpecBox {
+    /// 实际圆角（px）：按高度折算，且不超过高的一半。
+    pub fn radius_px(&self) -> f32 {
+        self.shape.radius_px(self.height)
+    }
+
+    /// 是否是药丸/整圆（圆角 = 半高）。
+    pub fn is_pill(&self) -> bool {
+        (self.radius_px() - self.height / 2.0).abs() < f32::EPSILON && self.height > 0.0
+    }
+}
+
+/// 卡片：300×150、圆角 **16**（规格卡 `ELEVATED CARD` 的 `rx=16`）。
+///
+/// 与官方 `FilledCardTokens` 的 `CornerMedium(12)` 差 4 —— 规格卡口径取 16（Large）。
+pub const CARD: SpecBox = SpecBox {
+    width: 300.0,
+    height: 150.0,
+    shape: ShapeScale::Large,
+};
+
+/// 对话框：380×190、圆角 **28**（与官方 `DialogTokens.CornerExtraLarge` 一致）。
+pub const DIALOG: SpecBox = SpecBox {
+    width: 380.0,
+    height: 190.0,
+    shape: ShapeScale::ExtraLarge,
+};
+
+/// Snackbar：340×52、圆角 **16**（官方是 `ExtraSmall(4)`，规格卡取 16 —— 登记差异）。
+pub const SNACKBAR: SpecBox = SpecBox {
+    width: 340.0,
+    height: 52.0,
+    shape: ShapeScale::Large,
+};
+
+/// 列表行：300×**60**、圆角 **30**（= 药丸；官方 `CornerNone`，本项目 `Small(8)`，规格卡药丸 —— 登记差异）。
+pub const LIST_ROW: SpecBox = SpecBox {
+    width: 300.0,
+    height: 60.0,
+    shape: ShapeScale::Full,
+};
+
+/// Chip（assist / filter）：高 **32**、圆角 **8**、宽度自适应（标签 13px、左右内距 16）。
+///
+/// 选中态的**形状不变**（规格卡 `Selected` 只是换填充），所以这里不给形变数据。
+pub const CHIP: SpecBox = SpecBox {
+    width: 0.0,
+    height: 32.0,
+    shape: ShapeScale::Small,
+};
+
+/// Chip 左右内距（px）。规格卡 chip 自适应宽；16 与 M3 `AssistChipTokens` 的 `HorizontalPadding`
+/// 同值，且实测标签订了这个量级。
+pub const CHIP_PAD_X: f32 = 16.0;
+
+/// 徽标（数字圆点）：20 Ø、整圆。
+pub const BADGE: SpecBox = SpecBox {
+    width: 20.0,
+    height: 20.0,
+    shape: ShapeScale::Full,
+};
+
+/// 列表行头像：40 Ø、整圆。
+pub const AVATAR: SpecBox = SpecBox {
+    width: 40.0,
+    height: 40.0,
+    shape: ShapeScale::Full,
+};
+
+/// 加载指示：56 Ø，圆形态（`rx=28`）与方形态（`rx=12` = [`ShapeScale::Medium`]）两种。
+pub const LOADING: SpecBox = SpecBox {
+    width: 56.0,
+    height: 56.0,
+    shape: ShapeScale::Full,
+};
+
+/// 加载指示的方形态圆角档（规格卡 `rx=12`）。
+pub const LOADING_SQUIRCLE: ShapeScale = ShapeScale::Medium;
+
+// ---- 文本字段（TEXT FIELDS / FILLED - OUTLINED - ERROR + ROUNDED 变体）----
+
+/// 字段高度（px；filled / outlined / error / 搜索框都是 56）。
+pub const FIELD_HEIGHT: f32 = 56.0;
+/// 默认圆角档：**4**（规格卡标题就写着 `CORNER 4`；与官方 `CornerExtraSmall` 一致）。
+pub const FIELD_SHAPE: ShapeScale = ShapeScale::ExtraSmall;
+/// 药丸变体圆角档：**28**（规格卡 `ROUNDED  (CORNER 28, BRAND VARIANT)`）。
+pub const FIELD_SHAPE_ROUNDED: ShapeScale = ShapeScale::ExtraLarge;
+/// 默认字段的内容内距（px）：标签 `x=80` − 字段 `x=64` = **16**。
+pub const FIELD_INSET: f32 = 16.0;
+/// 药丸字段的内容内距（px）：**32**。
+///
+/// 规格卡专门写了一行提醒：`label inset 32 inside pills (not 16), otherwise it reads as clipped`——
+/// 药丸两端是半圆，沿用 16 会让标签贴到弧上。
+pub const FIELD_PILL_INSET: f32 = 32.0;
+/// 字段悬浮标签字号（px）与输入值字号（px）。
+pub const FIELD_LABEL_PX: f32 = 12.0;
+/// 字段输入值字号（px）。
+pub const FIELD_VALUE_PX: f32 = 16.0;
+/// 错误提示行字号（px）。
+pub const FIELD_ERROR_PX: f32 = 12.0;
+
+/// 搜索框：560 宽是页级骨架量（这里只给高度与形状），圆角 **28** = 药丸，图标内距 **32**。
+pub const SEARCH_SHAPE: ShapeScale = ShapeScale::Full;
+/// 搜索框图标中心距左边（px）：`cx=1048` − 框 `x=1016` = **32**。
+pub const SEARCH_INSET: f32 = 32.0;
+
+// ---- 开关 / 复选框 / 单选框 ----
+
+/// 开关：轨道 52×32 药丸，拇指 **24 Ø**、内缩 **4**（关态拇指 16 Ø + 描边 2）。
+pub const SWITCH_TRACK: SpecBox = SpecBox {
+    width: 52.0,
+    height: 32.0,
+    shape: ShapeScale::Full,
+};
+/// 开关拇指直径（px）。
+pub const SWITCH_THUMB: f32 = 24.0;
+/// 拇指相对轨道的内缩（px）：规格卡轨道 `y=1060..1092`、拇指 `y=1064..1088`，上下各 **4**；
+/// 右端 `116−112` 同为 4。
+///
+/// 位移行程（拇指可从左滑到右的距离）= 轨道宽 52 − 拇指 24 − 2×内缩 4 = **20**（规格卡没写行程，
+/// 这是由前三项推出来的唯一值；写死 20 就是第四份副本）。
+pub const SWITCH_THUMB_INSET: f32 = 4.0;
+/// 关态拇指直径（px）：规格卡 `16×16 rx8`。
+pub const SWITCH_THUMB_OFF: f32 = 16.0;
+
+/// 复选框：**18×18**、圆角 **4**、描边 **2**（规格卡 `rect 18×18 rx4` + 勾线 `stroke-width=2`）。
+///
+/// 与官方 20×20 / 2dp 差 2px 与 2dp —— 4 是 `ShapeScale` 的刻度值，所以走容器层不违反 D32。
+pub const CHECKBOX: SpecBox = SpecBox {
+    width: 18.0,
+    height: 18.0,
+    shape: ShapeScale::ExtraSmall,
+};
+/// 复选框描边/勾线宽度（px）。
+pub const CHECKBOX_STROKE: f32 = 2.0;
+
+/// 单选框：**18 Ø**、环线 **2**、内点 **10 Ø**（规格卡 `r=9` 环 + `r=5` 实心）。
+pub const RADIO: SpecBox = SpecBox {
+    width: 18.0,
+    height: 18.0,
+    shape: ShapeScale::Full,
+};
+/// 单选框环线宽度（px）。
+pub const RADIO_RING: f32 = 2.0;
+/// 单选框内点直径（px）。
+pub const RADIO_DOT: f32 = 10.0;
+/// 勾选控件与标签的间距（px；规格卡 `18` 框 → 标签 `x=398`，实测 8）。
+pub const CHOICE_GAP: f32 = 8.0;
+
+// ---- 进度 ----
+
+/// 线性进度条厚度（px）：`rect height=4`。
+pub const PROGRESS_THICKNESS: f32 = 4.0;
+/// 波形进度的描边宽度（px）：`stroke-width=6`、`stroke-linecap=round`。
+pub const PROGRESS_WAVY_STROKE: f32 = 6.0;
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::spacing::GRID;
+
+    #[test]
+    fn spec_boxes_hit_the_spec_corners() {
+        // 规格卡逐个比对（rx 一栏就是 `radius_px()`）。
+        assert_eq!(CARD.radius_px(), 16.0, "卡片 rx=16");
+        assert_eq!(DIALOG.radius_px(), 28.0, "对话框 rx=28");
+        assert_eq!(SNACKBAR.radius_px(), 16.0, "snackbar rx=16");
+        assert_eq!(LIST_ROW.radius_px(), 30.0, "列表行 rx=30（药丸）");
+        assert_eq!(CHIP.radius_px(), 8.0, "chip rx=8");
+        assert_eq!(BADGE.radius_px(), 10.0, "徽标是圆点");
+        assert_eq!(AVATAR.radius_px(), 20.0, "头像是圆");
+        assert_eq!(LOADING.radius_px(), 28.0, "加载圆形态");
+        assert_eq!(LOADING_SQUIRCLE.dp(), 12.0, "加载方形态 rx=12");
+        assert_eq!(CHECKBOX.radius_px(), 4.0, "复选框 rx=4");
+        assert_eq!(SWITCH_TRACK.radius_px(), 16.0, "开关轨道 rx=16");
+    }
+
+    #[test]
+    fn pills_are_only_the_ones_the_spec_draws_as_pills() {
+        assert!(LIST_ROW.is_pill());
+        assert!(BADGE.is_pill());
+        assert!(AVATAR.is_pill());
+        assert!(LOADING.is_pill());
+        assert!(RADIO.is_pill());
+        assert!(SWITCH_TRACK.is_pill());
+        assert!(!CARD.is_pill());
+        assert!(!DIALOG.is_pill());
+        assert!(!SNACKBAR.is_pill());
+        assert!(!CHECKBOX.is_pill());
+    }
+
+    #[test]
+    fn field_variants_keep_the_inset_rule() {
+        assert_eq!(FIELD_SHAPE.dp(), 4.0);
+        assert_eq!(FIELD_SHAPE_ROUNDED.dp(), 28.0);
+        // 药丸内距必须是默认内距的两倍——规格卡那行提醒就是这条。
+        assert_eq!(FIELD_PILL_INSET, FIELD_INSET * 2.0);
+    }
+
+    #[test]
+    fn heights_are_on_the_grid() {
+        for (name, value) in [
+            ("snackbar", SNACKBAR.height),
+            ("list-row", LIST_ROW.height),
+            ("chip", CHIP.height),
+            ("badge", BADGE.height),
+            ("avatar", AVATAR.height),
+            ("loading", LOADING.height),
+            ("field", FIELD_HEIGHT),
+            ("switch", SWITCH_TRACK.height),
+            ("switch-thumb", SWITCH_THUMB),
+            ("progress", PROGRESS_THICKNESS),
+            ("choice-gap", CHOICE_GAP),
+            ("search-inset", SEARCH_INSET),
+        ] {
+            assert_eq!(value % GRID, 0.0, "{name} = {value} 不在 4px 栅格上");
+        }
+        // 微控件 18：规格卡实测值（M3 官方 `CheckboxTokens.ContainerWidth/Height` 也是 18），
+        // 它与 2dp/4dp 圆角一样属「微控件刻度」，不受 4px 栅格约束。
+        assert_eq!((CHECKBOX.width, CHECKBOX.height), (18.0, 18.0));
+        assert_eq!((RADIO.width, RADIO.height), (18.0, 18.0));
+        // 卡 / 对话框的 300×150 与 380×190 是规格卡画布上的**示意**尺寸（实际高由内容决定），
+        // 所以只钉数值、不参与栅格门禁。
+        assert_eq!((CARD.width, CARD.height), (300.0, 150.0));
+        assert_eq!((DIALOG.width, DIALOG.height), (380.0, 190.0));
+        // 例外：描边类不受栅格约束（它们是一像素/线宽量，不是布局尺寸），单独钉住。
+        assert_eq!(CHECKBOX_STROKE, 2.0);
+        assert_eq!(RADIO_RING, 2.0);
+        assert_eq!(PROGRESS_WAVY_STROKE, 6.0, "波形进度描边 stroke-width=6");
+    }
+}
diff --git a/crates/design/src/inkcat/mod.rs b/crates/design/src/inkcat/mod.rs
new file mode 100644
index 0000000..6534b33
--- /dev/null
+++ b/crates/design/src/inkcat/mod.rs
@@ -0,0 +1,48 @@
+//! # Ink Cat 规格卡 → 令牌（形状 / 尺寸档 / 字号校核）
+//!
+//! 来源是用户自制的规格卡 `DevDocs/artifacts/components-ink.svg`（Ink Cat / M3 Expressive，
+//! 1480×2260）。色板在 [`crate::color::boards`]，**本模块只装几何与排版**：
+//!
+//! | 子模块 | 内容 |
+//! |---|---|
+//! | [`size`] | 按钮 XS~XL 五档（[`size::ControlSize`]）+ FAB 四态（[`size::FabSize`]） |
+//! | [`metrics`] | 控件方框几何：卡片 / 对话框 / snackbar / 列表行 / chip / 徽标 / 字段 / 复选框 / 单选框 / 开关 / 进度 / 加载 |
+//! | [`type_scale`] | 规格卡出现的每个字号 → 最近官方档的**校核结论**（命中 / 落在两档之间 / 低于 UI 下限） |
+//!
+//! ## 与 [`crate::component_map`] 的关系：并列来源，不是替代
+//!
+//! `component_map` 的口径是**官方 M3 组件令牌**（`androidx.compose.material3.tokens`，A 级）；
+//! 规格卡是**用户自己的视觉决议**（也是 A 级，但是产品口径）。两者在若干处不一致，
+//! 本模块把差异**逐条登记**而不是偷偷改 `component_map`：
+//!
+//! | 项 | 规格卡 | `component_map`（官方） | 处置 |
+//! |---|---|---|---|
+//! | 卡片圆角 | **16**（`rx=16`） | `FilledCard/OutlinedCard = Medium(12)` | 登记：换肤时取 [`metrics::CARD`]（Large 16）。表值不动——app-iced 的 `pages/frame/tests.rs` 按 12 pin 住，改表等于连带改观感，归 M229 |
+//! | Snackbar | 高 **52** / 圆角 **16** | `ExtraSmall(4)` | 登记同上（[`metrics::SNACKBAR`]） |
+//! | 列表行 | 高 **60** / 药丸 **30** | `Small(8)` | 登记同上（[`metrics::LIST_ROW`]） |
+//! | 输入框 | 圆角 **4**（默认）/ **28**（药丸变体） | `ExtraSmall(4)` | 一致 + 新增药丸变体（[`metrics::FIELD_SHAPE_ROUNDED`]） |
+//! | Chip | 高 **32** / 圆角 **8** | `Small(8)`、无高度 | 一致 + 补高度（[`metrics::CHIP`]） |
+//! | Checkbox | **18×18** / 圆角 **4** / 描边 2 | 20×20 / 圆角 2（微半径） | 差异登记（[`metrics::CHECKBOX`]）。4 是 `ShapeScale` 刻度值，42 号位不冲突 |
+//! | Radio | **18 Ø** / 环 2 / 内点 10 | 20 Ø / 环 2 / 内点 10 | 差异登记（[`metrics::RADIO`]） |
+//! | 按钮档 | **XS~XL = 32/40/56/96/136** | 无档位（`LayoutMetrics::control_height = 40`） | 新增 [`size::ControlSize`] |
+//! | FAB | 四态 40/56/80/160×56，圆角 12/16/20/16 | 无 | 新增 [`size::FabSize`] |
+//! | 对话框 | 380×190 / 圆角 **28** | `ExtraLarge(28)` | 一致（[`metrics::DIALOG`]） |
+//!
+//! **为什么不动 `component_map` 的表值**：那张表已经被 iced 壳层消费并 pin 住（卡片 12、
+//! 搜索条 Full 等），改值等于在令牌层做了一次没人截图验收的换肤。本模块先给出规格卡口径的
+//! 数据，M229 换肤时一次切换 + 出图验收，避免「一半旧一半新」。
+//!
+//! ## 数值口径
+//!
+//! - 所有尺寸单位都是**逻辑 px**（100% DPI 下 1px = 1dp），与 `ShapeScale::dp()` 同一刻度；
+//! - `0.0` 一律表示「由内容决定」（与 [`crate::component_map::ComponentMetrics`] 同约定），
+//!   不是「尺寸为零」；
+//! - 规格卡没写、但实现需要的值（按钮水平内距）标 `[估]` 并注明推导规则。
+
+pub mod metrics;
+pub mod size;
+pub mod type_scale;
+
+pub use metrics::SpecBox;
+pub use size::{ControlSize, FabSize};
+pub use type_scale::{SpecFit, SpecText, UI_TEXT_FLOOR_PX};
diff --git a/crates/design/src/inkcat/size.rs b/crates/design/src/inkcat/size.rs
new file mode 100644
index 0000000..552eee7
--- /dev/null
+++ b/crates/design/src/inkcat/size.rs
@@ -0,0 +1,323 @@
+//! 控件**尺寸档**：按钮 XS~XL 五档 + FAB 四态（规格卡 `BUTTONS / XS - XL` 与
+//! `FAB / SMALL - DEFAULT - MEDIUM - EXTENDED`）。
+//!
+//! 为什么要有这一层：`LayoutMetrics::control_height`（40）只够表达「标准控件多高」，
+//! 而规格卡把按钮做成了**五档梯子**（32/40/56/96/136），FAB 又自成一套四态。这些是「档位」，
+//! 不是骨架尺寸（不随窗口变），也不是单个控件的内部微几何（`ComponentMetrics` 管的是画进
+//! 方框里的那几个像素）。所以单独一层，一个枚举一个档，消费方按语义取。
+//!
+//! ## 取值与实测（规格卡 `rx` 全部等于半高 ⇒ 真药丸）
+//!
+//! | 档 | 高 | 圆角 | 字号 | 规格卡依据 |
+//! |---|---|---|---|---|
+//! | XS | 32 | 16 | 14 | `40.24×32 rx16`，标签 `font-size=14` |
+//! | S | 40 | 20 | 14 | `40.12×40 rx20` |
+//! | M | 56 | 28 | 16 | `57.28×56 rx28`（五档行同一档） |
+//! | L | 96 | 48 | 24 | `109.92×96 rx48` |
+//! | XL | 136 | 68 | 32 | `165.12×136 rx68` |
+//!
+//! 圆角一律走 [`ShapeScale::Full`]（`radius_px(高)` = 半高），**不写裸数字**：规格卡的 rx
+//! 恰好都是半高，`Full` 与之一致，还顺带保证「换档不会漏改圆角」。
+//!
+//! 字号是规格卡 measured 值；字重 500（Expressive 的按钮文字就是 Medium）。
+//! **规格卡没给水平内距**（按钮是自适应宽），[`ControlSize::pad_x`] 是按「半高向下取 4 栅格、
+//! 封顶 48」推的 `[估]` 值——药丸两端要留出半圆安全区，这条规则比逐档拍数字更经得起改档。
+
+use crate::shape::ShapeScale;
+use crate::typography::{TypeRole, TypeStyle, Weight};
+
+/// 按钮尺寸档（规格卡 `XS - XL`）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum ControlSize {
+    /// 32 高：行内小按钮、徽标式操作。
+    Xs,
+    /// 40 高：默认密集按钮（= `LayoutMetrics::control_height`）。
+    S,
+    /// 56 高：主操作按钮（规格卡 `BUTTONS / 5 LEVELS` 那一行就是这一档）。
+    M,
+    /// 96 高：页面级主行动（空态、引导页）。
+    L,
+    /// 136 高：展示型入口（规格卡给的最大档，慎用）。
+    Xl,
+}
+
+impl ControlSize {
+    /// 由小到大全部档位。
+    pub const ALL: [ControlSize; 5] = [
+        ControlSize::Xs,
+        ControlSize::S,
+        ControlSize::M,
+        ControlSize::L,
+        ControlSize::Xl,
+    ];
+
+    /// 稳定字符串名（`xs` … `xl`）。
+    pub const fn name(self) -> &'static str {
+        match self {
+            ControlSize::Xs => "xs",
+            ControlSize::S => "s",
+            ControlSize::M => "m",
+            ControlSize::L => "l",
+            ControlSize::Xl => "xl",
+        }
+    }
+
+    /// 可见高度（px）。
+    pub const fn height_px(self) -> f32 {
+        match self {
+            ControlSize::Xs => 32.0,
+            ControlSize::S => 40.0,
+            ControlSize::M => 56.0,
+            ControlSize::L => 96.0,
+            ControlSize::Xl => 136.0,
+        }
+    }
+
+    /// 圆角档：全部药丸（规格卡每档的 rx 都等于半高）。
+    pub const fn shape(self) -> ShapeScale {
+        ShapeScale::Full
+    }
+
+    /// 实际圆角（= 半高，规格卡 rx 实测值 16/20/28/48/68）。
+    pub fn radius_px(self) -> f32 {
+        self.shape().radius_px(self.height_px())
+    }
+
+    /// 标签字号（规格卡 measured：14/14/16/24/32）。
+    pub const fn label_px(self) -> f32 {
+        match self {
+            ControlSize::Xs | ControlSize::S => 14.0,
+            ControlSize::M => 16.0,
+            ControlSize::L => 24.0,
+            ControlSize::Xl => 32.0,
+        }
+    }
+
+    /// 标签该用的官方字级（`[spec]` 字号对应的最近档；同一字号多档时取 `Role::ALL` 序里靠前的那个）。
+    pub const fn type_role(self) -> TypeRole {
+        match self {
+            ControlSize::Xs | ControlSize::S => TypeRole::LabelLarge,
+            ControlSize::M => TypeRole::BodyLarge,
+            ControlSize::L => TypeRole::HeadlineSmall,
+            ControlSize::Xl => TypeRole::HeadlineLarge,
+        }
+    }
+
+    /// 标签样式：字号/行高跟字级、**字重固定 500**（规格卡按钮文字都是 `font-weight=500`，
+    /// 而官方 body/headline 是 400 —— 这是按钮语义，不是排版漂移）。
+    pub fn label(self) -> TypeStyle {
+        TypeStyle {
+            weight: Weight::Medium,
+            ..self.type_role().style()
+        }
+    }
+
+    /// 水平内距（px）。`[估]`：规格卡是自适应宽、没写内距。
+    ///
+    /// 规则 = 半高向下取 4 栅格，封顶 48（再宽只会白吃宽度，观感不再变）。
+    pub const fn pad_x(self) -> f32 {
+        match self {
+            ControlSize::Xs => 16.0,
+            ControlSize::S => 20.0,
+            ControlSize::M => 28.0,
+            ControlSize::L => 48.0,
+            ControlSize::Xl => 48.0,
+        }
+    }
+
+    /// 该档是否达到无障碍命中下限（M3：可点目标 ≥48dp）。XS/S 需要外扩命中区。
+    pub const fn meets_touch_target(self) -> bool {
+        self.height_px() >= 48.0
+    }
+}
+
+/// FAB 四态（规格卡 `FAB / SMALL - DEFAULT - MEDIUM - EXTENDED`）。
+///
+/// 规格卡的圆角是 12/16/20/16 —— **不是**半高（40 的半高是 20，规格卡是 12），所以这里
+/// 逐个写档位（[`ShapeScale::Medium`] / [`ShapeScale::Large`] / [`ShapeScale::LargeIncreased`]），
+/// 不用 `Full`。扩展态（Extended）是「药丸 + 图标 + 标签」，几何见 [`FabSize::Extended`] 的各访问器。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum FabSize {
+    /// 40×40，圆角 12，图标 20。
+    Small,
+    /// 56×56，圆角 16，图标 26（= M3 默认 FAB 尺寸）。
+    Default,
+    /// 80×80，圆角 20，图标 34。
+    Medium,
+    /// 160×56（最小宽，随标签撑开），圆角 16，图标 24，标签 15。
+    Extended,
+}
+
+impl FabSize {
+    /// 全部四态。
+    pub const ALL: [FabSize; 4] = [
+        FabSize::Small,
+        FabSize::Default,
+        FabSize::Medium,
+        FabSize::Extended,
+    ];
+
+    /// 稳定字符串名（`small` / `default` / `medium` / `extended`）。
+    pub const fn name(self) -> &'static str {
+        match self {
+            FabSize::Small => "small",
+            FabSize::Default => "default",
+            FabSize::Medium => "medium",
+            FabSize::Extended => "extended",
+        }
+    }
+
+    /// 宽度（px；Extended 是**最小**宽，实际由标签撑开）。
+    pub const fn width_px(self) -> f32 {
+        match self {
+            FabSize::Small => 40.0,
+            FabSize::Default => 56.0,
+            FabSize::Medium => 80.0,
+            FabSize::Extended => 160.0,
+        }
+    }
+
+    /// 高度（px）。
+    pub const fn height_px(self) -> f32 {
+        match self {
+            FabSize::Small => 40.0,
+            FabSize::Default => 56.0,
+            FabSize::Medium => 80.0,
+            FabSize::Extended => 56.0,
+        }
+    }
+
+    /// 圆角档（规格卡 rx：12 / 16 / 20 / 16）。
+    pub const fn shape(self) -> ShapeScale {
+        match self {
+            FabSize::Small => ShapeScale::Medium,
+            FabSize::Default | FabSize::Extended => ShapeScale::Large,
+            FabSize::Medium => ShapeScale::LargeIncreased,
+        }
+    }
+
+    /// 实际圆角（px）。
+    pub fn radius_px(self) -> f32 {
+        self.shape().radius_px(self.height_px())
+    }
+
+    /// 图标（`+` 字形）字号（规格卡 measured：20/26/34/24）。
+    pub const fn icon_px(self) -> f32 {
+        match self {
+            FabSize::Small => 20.0,
+            FabSize::Default => 26.0,
+            FabSize::Medium => 34.0,
+            FabSize::Extended => 24.0,
+        }
+    }
+
+    /// 标签字号（px；只有 Extended 有标签）。
+    pub const fn label_px(self) -> f32 {
+        match self {
+            FabSize::Extended => 15.0,
+            _ => 0.0,
+        }
+    }
+
+    /// 起始内距（px；只有 Extended 有）：**28**，规格卡画的就这个数。
+    ///
+    /// 推导（可逐位核）：框 `x=292` 起、宽 160；`+` 是 `font-size=24`、`text-anchor=middle`、
+    /// 中心 `x=332` ⇒ 图标盒 = 320..344 ⇒ 内距 = 320 − 292 = **28**；标签 `x=352` 起，
+    /// 于是图标盒右沿 344 到标签 352 = [`FabSize::gap_px`] 的 8。
+    ///
+    /// ⚠️ 与官方口径的偏离已登记：M3 ExtendedFAB 的起始内距是 **16**（图标盒 292+16=308）。
+    /// 规格卡画得更宽松，本表按**规格卡**取值（A 级依据 = 图中坐标，不是猜的）；M229 若要用
+    /// M3 的 16，得同时把图标中心从 332 挪回 316 —— 那是一处视觉改动，要出截图，别悄悄改数。
+    pub const fn pad_start_px(self) -> f32 {
+        match self {
+            FabSize::Extended => 28.0,
+            _ => 0.0,
+        }
+    }
+
+    /// 图标与标签的间距（px；Extended 实测 8）。
+    pub const fn gap_px(self) -> f32 {
+        match self {
+            FabSize::Extended => 8.0,
+            _ => 0.0,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::spacing::GRID;
+
+    #[test]
+    fn button_ladder_is_pill_and_monotone() {
+        for pair in ControlSize::ALL.windows(2) {
+            assert!(
+                pair[0].height_px() < pair[1].height_px(),
+                "{:?} 应矮于 {:?}",
+                pair[0],
+                pair[1]
+            );
+            assert!(pair[0].label_px() <= pair[1].label_px());
+            assert!(pair[0].pad_x() <= pair[1].pad_x());
+        }
+        for size in ControlSize::ALL {
+            // 规格卡实测：rx = 半高（16/20/28/48/68）。
+            assert_eq!(size.radius_px(), size.height_px() / 2.0, "{size:?}");
+            assert_eq!(size.shape(), ShapeScale::Full);
+            assert_eq!(size.height_px() % GRID, 0.0, "{size:?} 不在 4px 栅格上");
+            assert_eq!(size.pad_x() % GRID, 0.0, "{size:?} 的内距不在 4px 栅格上");
+            // 标签字号与所取字级一致（字重才是被覆盖的那一项）。
+            assert_eq!(size.label().size_px, size.type_role().style().size_px);
+            assert_eq!(size.label().weight, Weight::Medium);
+        }
+        // 命中下限：只有 L / XL 自身就够 48。
+        assert!(!ControlSize::Xs.meets_touch_target());
+        assert!(!ControlSize::S.meets_touch_target());
+        assert!(ControlSize::M.meets_touch_target());
+    }
+
+    #[test]
+    fn fab_corners_are_the_spec_values() {
+        // 规格卡 rx：40→12、56→16、80→20、扩展 56→16（都不是半高，所以不许用 Full）。
+        for (size, radius) in [
+            (FabSize::Small, 12.0),
+            (FabSize::Default, 16.0),
+            (FabSize::Medium, 20.0),
+            (FabSize::Extended, 16.0),
+        ] {
+            assert_eq!(size.radius_px(), radius, "{size:?}");
+            assert_ne!(size.shape(), ShapeScale::Full, "{size:?} 不是药丸");
+        }
+        // 方态三档是正方形；扩展态是药丸。
+        for size in [FabSize::Small, FabSize::Default, FabSize::Medium] {
+            assert_eq!(size.width_px(), size.height_px(), "{size:?} 该是正方形");
+            assert_eq!(size.label_px(), 0.0);
+            assert_eq!(size.pad_start_px(), 0.0);
+        }
+        assert_eq!(FabSize::Extended.width_px(), 160.0);
+        assert_eq!(FabSize::Extended.height_px(), 56.0);
+        assert_eq!(FabSize::Extended.label_px(), 15.0);
+        // 内距 28 = 规格卡图中「框 292 → 图标盒 320」的实测距离（不是 M3 的 16）。
+        assert_eq!(FabSize::Extended.pad_start_px(), 28.0);
+        // 图标中心落点必须自洽：292 + 28 + 24/2 = 332，与规格卡 `x=332` 对得上。
+        assert_eq!(FabSize::Extended.pad_start_px() + 24.0 / 2.0 + 292.0, 332.0);
+        assert_eq!(FabSize::Extended.gap_px(), 8.0);
+        // 图标字号随档递增（扩展态回到 24，因为它跟标签同一行）。
+        assert!(FabSize::Small.icon_px() < FabSize::Default.icon_px());
+        assert!(FabSize::Default.icon_px() < FabSize::Medium.icon_px());
+        assert_eq!(FabSize::Extended.icon_px(), 24.0);
+    }
+
+    #[test]
+    fn names_are_unique() {
+        let mut seen = std::collections::BTreeSet::new();
+        for size in ControlSize::ALL {
+            assert!(seen.insert(size.name()));
+        }
+        let mut seen = std::collections::BTreeSet::new();
+        for size in FabSize::ALL {
+            assert!(seen.insert(size.name()));
+        }
+    }
+}
diff --git a/crates/design/src/inkcat/type_scale.rs b/crates/design/src/inkcat/type_scale.rs
new file mode 100644
index 0000000..bf53ac7
--- /dev/null
+++ b/crates/design/src/inkcat/type_scale.rs
@@ -0,0 +1,288 @@
+//! 规格卡字号 → 官方 type scale 的**校核**（不是又一张字号表）。
+//!
+//! 规格卡上每一处**文字**都写了 `font-size`，去重共 11 档：
+//! 40 / 32 / 24 / 16 / 15 / 14 / 13 / 12 / 11 / 10 / 9。
+//! 其中一部分**命中** M3 的 15 档（14 / 16 / 24 / 32 / 12 / 11），一部分**落在两档之间**
+//! （13 / 15 / 40），还有一部分**低于本项目允许的 UI 下限**（10 / 9）。
+//!
+//! 规格卡上另有 20 / 26 / 34 三个字号，但它们是 **FAB 的图形符号（`+` 字形）**，不是文字——
+//! 归 [`crate::inkcat::size::FabSize::icon_px`] 管，本模块不收录（`SpecText` 里没有 20 这一档）。
+//!
+//! 本模块的职责就是把「规格卡字级」翻译成这三类结论，让换肤时不用逐个拿卷尺量：
+//!
+//! | 结论 | 含义 | 处置 |
+//! |---|---|---|
+//! | [`SpecFit::Exact`] | 恰好是官方某档 | 直接用该 [`TypeRole`] |
+//! | [`SpecFit::Between`] | 落在相邻两档之间 | 取**较大**那档（可读性优先），并在报告里登记 1px 级偏离 |
+//! | [`SpecFit::BelowFloor`] | 低于 [`UI_TEXT_FLOOR_PX`]（11） | **不进 UI**：只允许出现在规格卡/图注/设计稿里 |
+//!
+//! ## 为什么下限是 11
+//!
+//! [`TypeRole::LabelSmall`] 是官方最小档（11/16），且 crate 文档已经写明「中文 11px 可读性差，
+//! 谨慎使用」。规格卡的 10（小节标题 `BUTTONS / 5 LEVELS`）与 9（色板角色名）是**设计稿标注**，
+//! 不是界面文字——搬进 UI 就是拿中文在图上看蚂蚁。所以下限写成常量，由
+//! [`SpecText::in_ui`] 与测试把它钉死。
+//!
+//! ## 同字号多档怎么办
+//!
+//! M3 有若干同字号档（14 有 title-small / body-medium / label-large；16 有 title-medium /
+//! body-large；12 有 body-small / label-medium）。[`nearest_role`] 在距离相同时按
+//! [`TypeRole::ALL`] 的声明序取第一个（title → body → label），这是**稳定的**、与文档一致的选择；
+//! 需要别的语义（例如「这是按钮文字」）就显式指定 [`TypeRole`]，不要指望 `nearest_role` 猜。
+
+use crate::typography::{TypeRole, Weight};
+
+/// 允许进 UI 的最小字号（px）。低于它的规格卡字号只能是设计稿标注。
+pub const UI_TEXT_FLOOR_PX: f32 = 11.0;
+
+/// 规格卡上出现的文字用途（每个用途一个 `font-size`，值取自规格卡）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum SpecText {
+    /// 卡片大标题：40 / 500 / 0（`Ink Cat / M3 Expressive` 那行）。
+    PageTitle,
+    /// 副标题：15 / 400 / 0.3。
+    Subtitle,
+    /// 小节标注（全大写 + 字距）：10 / 600 / 1.2。
+    SectionCaps,
+    /// 大按钮标签：32 / 500 / 0（XL 档）。
+    DisplayLabel,
+    /// 对话框标题：24 / 400 / 0。
+    DialogTitle,
+    /// 标准控件标签：16 / 500 / 0（M 档按钮、卡片标题）。
+    ControlLabel,
+    /// 小控件标签：14 / 500 / 0（XS/S 档按钮、对话框动作、snackbar）。
+    ControlLabelSmall,
+    /// 正文：13 / 400 / 0（卡片支持文字、chip 标签、列表副文案）。
+    Body,
+    /// 辅助文字：12 / 400 / 0（字段标签、图标按钮说明）。
+    Caption,
+    /// 徽标数字：11 / 600 / 0。
+    Badge,
+    /// 色板角色名（设计稿标注）：9 / 400 / 0。
+    SwatchCaption,
+}
+
+impl SpecText {
+    /// 规格卡里出现的全部用途。
+    pub const ALL: [SpecText; 11] = [
+        SpecText::PageTitle,
+        SpecText::Subtitle,
+        SpecText::SectionCaps,
+        SpecText::DisplayLabel,
+        SpecText::DialogTitle,
+        SpecText::ControlLabel,
+        SpecText::ControlLabelSmall,
+        SpecText::Body,
+        SpecText::Caption,
+        SpecText::Badge,
+        SpecText::SwatchCaption,
+    ];
+
+    /// 字号（px，规格卡 `font-size`）。
+    pub const fn px(self) -> f32 {
+        match self {
+            SpecText::PageTitle => 40.0,
+            SpecText::Subtitle => 15.0,
+            SpecText::SectionCaps => 10.0,
+            SpecText::DisplayLabel => 32.0,
+            SpecText::DialogTitle => 24.0,
+            SpecText::ControlLabel => 16.0,
+            SpecText::ControlLabelSmall => 14.0,
+            SpecText::Body => 13.0,
+            SpecText::Caption => 12.0,
+            SpecText::Badge => 11.0,
+            SpecText::SwatchCaption => 9.0,
+        }
+    }
+
+    /// 字重（规格卡 `font-weight`）。
+    pub const fn weight(self) -> Weight {
+        match self {
+            SpecText::SectionCaps | SpecText::Badge => Weight::SemiBold,
+            SpecText::PageTitle
+            | SpecText::DisplayLabel
+            | SpecText::ControlLabel
+            | SpecText::ControlLabelSmall => Weight::Medium,
+            _ => Weight::Regular,
+        }
+    }
+
+    /// 字距（px，规格卡 `letter-spacing`）。
+    pub const fn tracking_px(self) -> f32 {
+        match self {
+            SpecText::SectionCaps => 1.2,
+            SpecText::Subtitle => 0.3,
+            _ => 0.0,
+        }
+    }
+
+    /// 校核结论（命中 / 落在两档之间 / 低于下限）。
+    pub fn fit(self) -> SpecFit {
+        fit_of(self.px())
+    }
+
+    /// 能否进 UI（≥ [`UI_TEXT_FLOOR_PX`]）。
+    pub const fn in_ui(self) -> bool {
+        self.px() >= UI_TEXT_FLOOR_PX
+    }
+}
+
+/// 一个字号与官方 type scale 的关系。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SpecFit {
+    /// 恰好等于官方某档（同字号多档时取 `TypeRole::ALL` 序里第一个）。
+    Exact(TypeRole),
+    /// 落在相邻两档之间（小档, 大档）。
+    Between(TypeRole, TypeRole),
+    /// 低于 [`UI_TEXT_FLOOR_PX`]：只能是设计稿标注。
+    BelowFloor,
+}
+
+impl SpecFit {
+    /// 建议采用的档位（`BelowFloor` 返回 `None`：不该进 UI）。
+    ///
+    /// `Between` 取**较大**那档——宁可偏大 1px，也不要偏小到中文糊成一团。
+    pub fn recommended(self) -> Option {
+        match self {
+            SpecFit::Exact(role) => Some(role),
+            SpecFit::Between(_, larger) => Some(larger),
+            SpecFit::BelowFloor => None,
+        }
+    }
+}
+
+/// `px` 的最近官方档（距离相同取**较大**那档；同字号多档取 `TypeRole::ALL` 序里第一个）。
+pub fn nearest_role(px: f32) -> TypeRole {
+    let mut best = TypeRole::BodyMedium;
+    let mut best_key = (f32::INFINITY, f32::NEG_INFINITY);
+    for role in TypeRole::ALL {
+        let size = role.style().size_px;
+        // 排序键：(距离, −字号)；严格优于当前才换，所以同键时保留 `ALL` 序靠前的那个。
+        let key = ((size - px).abs(), -size);
+        if key.0 < best_key.0 || (key.0 == best_key.0 && key.1 < best_key.1) {
+            best = role;
+            best_key = key;
+        }
+    }
+    best
+}
+
+/// `px` 与官方 type scale 的关系。
+pub fn fit_of(px: f32) -> SpecFit {
+    if px < UI_TEXT_FLOOR_PX {
+        return SpecFit::BelowFloor;
+    }
+    let mut exact = None;
+    let mut lower: Option<(f32, TypeRole)> = None;
+    let mut upper: Option<(f32, TypeRole)> = None;
+    for role in TypeRole::ALL {
+        let size = role.style().size_px;
+        if (size - px).abs() < f32::EPSILON {
+            // 同字号多档（14/16/12）：保留 `ALL` 序里第一个（title → body → label）。
+            exact = exact.or(Some(role));
+        } else if size < px {
+            if lower.is_none_or(|(best, _)| size > best) {
+                lower = Some((size, role));
+            }
+        } else if upper.is_none_or(|(best, _)| size < best) {
+            upper = Some((size, role));
+        }
+    }
+    match (exact, lower, upper) {
+        (Some(role), _, _) => SpecFit::Exact(role),
+        (None, Some((_, lower)), Some((_, upper))) => SpecFit::Between(lower, upper),
+        // 超出官方区间（px > 57）：取最近档，不硬造一个不存在的「之间」。
+        _ => SpecFit::Exact(nearest_role(px)),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn spec_sizes_classify_as_documented() {
+        // 命中：14 / 16 / 24 / 32 / 12 / 11
+        assert_eq!(
+            SpecText::ControlLabelSmall.fit(),
+            SpecFit::Exact(TypeRole::TitleSmall)
+        );
+        assert_eq!(
+            SpecText::ControlLabel.fit(),
+            SpecFit::Exact(TypeRole::TitleMedium)
+        );
+        assert_eq!(
+            SpecText::DialogTitle.fit(),
+            SpecFit::Exact(TypeRole::HeadlineSmall)
+        );
+        assert_eq!(
+            SpecText::DisplayLabel.fit(),
+            SpecFit::Exact(TypeRole::HeadlineLarge)
+        );
+        assert_eq!(SpecText::Caption.fit(), SpecFit::Exact(TypeRole::BodySmall));
+        assert_eq!(SpecText::Badge.fit(), SpecFit::Exact(TypeRole::LabelSmall));
+        // 落在两档之间：13（12/14）、15（14/16）、40（36/45）
+        assert_eq!(
+            SpecText::Body.fit(),
+            SpecFit::Between(TypeRole::BodySmall, TypeRole::TitleSmall)
+        );
+        assert_eq!(
+            SpecText::Subtitle.fit(),
+            SpecFit::Between(TypeRole::TitleSmall, TypeRole::TitleMedium)
+        );
+        assert_eq!(
+            SpecText::PageTitle.fit(),
+            SpecFit::Between(TypeRole::DisplaySmall, TypeRole::DisplayMedium)
+        );
+        // 低于下限：10 / 9
+        assert_eq!(SpecText::SectionCaps.fit(), SpecFit::BelowFloor);
+        assert_eq!(SpecText::SwatchCaption.fit(), SpecFit::BelowFloor);
+    }
+
+    #[test]
+    fn only_the_two_annotation_sizes_are_out_of_ui() {
+        let out: Vec<&str> = SpecText::ALL
+            .iter()
+            .filter(|text| !text.in_ui())
+            .map(|text| match text {
+                SpecText::SectionCaps => "section-caps",
+                SpecText::SwatchCaption => "swatch-caption",
+                _ => "不该出现在这里",
+            })
+            .collect();
+        assert_eq!(out, vec!["section-caps", "swatch-caption"]);
+        // 下限就是 LabelSmall 的字号（官方最小档），不是随手拍的数。
+        assert_eq!(UI_TEXT_FLOOR_PX, TypeRole::LabelSmall.style().size_px);
+    }
+
+    #[test]
+    fn recommended_rounds_up_not_down() {
+        assert_eq!(SpecFit::BelowFloor.recommended(), None);
+        // 13 → 取 14，不取 12。
+        assert_eq!(fit_of(13.0).recommended(), Some(TypeRole::TitleSmall));
+        // 15 → 取 16。
+        assert_eq!(fit_of(15.0).recommended(), Some(TypeRole::TitleMedium));
+        // 40 → 取 45，不取 36。
+        assert_eq!(fit_of(40.0).recommended(), Some(TypeRole::DisplayMedium));
+    }
+
+    #[test]
+    fn nearest_role_is_stable_for_equal_distances() {
+        // 15 与 14 / 16 等距 → 取较大档 16。
+        assert_eq!(nearest_role(15.0), TypeRole::TitleMedium);
+        // 官方最小/最大档之外也不越界。
+        assert_eq!(nearest_role(4.0), TypeRole::LabelSmall);
+        assert_eq!(nearest_role(80.0), TypeRole::DisplayLarge);
+    }
+
+    #[test]
+    fn spec_weights_and_tracking_are_pinned() {
+        assert_eq!(SpecText::SectionCaps.weight(), Weight::SemiBold);
+        assert_eq!(SpecText::Badge.weight(), Weight::SemiBold);
+        assert_eq!(SpecText::ControlLabel.weight(), Weight::Medium);
+        assert_eq!(SpecText::Body.weight(), Weight::Regular);
+        assert!((SpecText::SectionCaps.tracking_px() - 1.2).abs() < 1.0e-6);
+        assert!((SpecText::Subtitle.tracking_px() - 0.3).abs() < 1.0e-6);
+        assert_eq!(SpecText::ControlLabel.tracking_px(), 0.0);
+    }
+}
diff --git a/crates/design/src/lib.rs b/crates/design/src/lib.rs
new file mode 100644
index 0000000..d573ebf
--- /dev/null
+++ b/crates/design/src/lib.rs
@@ -0,0 +1,170 @@
+//! # 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 实现逐通道对齐——口径见模块文档）
+//! - [`color::boards`]：**双主题色板**（Ink 深 / Silver 浅，用户规格卡 `components-ink.svg` 的固化值）
+//!   + [`BrandBoard`] 选择器；与 tone 派生的 `Scheme::baseline` 并列（理由见该模块文档）
+//! - [`inkcat`]：规格卡的**形状 / 尺寸档 / 字号校核**——按钮 XS~XL、FAB 四态、控件方框几何、
+//!   规格卡字号 → 官方 type scale 的命中/落档/低于下限结论
+//! - [`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 inkcat;
+pub mod motion;
+pub mod palette;
+pub mod shape;
+pub mod spacing;
+pub mod typography;
+
+pub use color::{BrandBoard, 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::brand(board)`，换强调色 =
+/// `DesignTokens::with_accent(flavor, accent)`），不要在适配层里缓存散装色值——
+/// 那样热切会有一半画对一半画错。
+#[derive(Debug, Clone, Copy)]
+pub struct DesignTokens {
+    /// 当前深浅模式。
+    pub flavor: SchemeFlavor,
+    /// 当前模式的 M3 语义色角色全表。
+    pub colors: Scheme,
+    /// 动效时长的全局缩放（`1.0` = 标准；用户关掉动画时适配层传 `0.0`）。
+    pub motion_scale: MotionScale,
+}
+
+impl DesignTokens {
+    /// **tone 派生**的一套令牌：种子 `#3C8DBC`（M70 ④ 天蓝，用户 2026-11-01 拍板）
+    /// + 中性彩度 12，即 `color::palettes::DEFAULT_SEED` / `DEFAULT_NEUTRAL_CHROMA`。
+    ///
+    /// 定位（M228 起）：这是 **D38 取色链的锚点**——「莫奈关闭时机内色卡的底色」与
+    /// `with_accent` 的中性基准。**产品出厂外观请走 [`DesignTokens::brand`]**（Ink / Silver
+    /// 两套固化色板）；两条路径并列而不是互相替换，理由见 `color::boards` 的模块文档。
+    ///
+    /// 想要**官方 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,
+        }
+    }
+
+    /// **品牌色板**（Ink 深 / Silver 浅）的令牌：出厂外观的唯一入口。
+    ///
+    /// `flavor` 由色板自己决定（`BrandBoard::flavor`），所以「跟随系统」只需
+    /// `DesignTokens::brand(BrandBoard::for_flavor(system_flavor))`——第三种设置态在设置层解析，
+    /// 令牌层只认两套板。
+    pub fn brand(board: BrandBoard) -> Self {
+        Self {
+            flavor: board.flavor(),
+            colors: board.scheme(),
+            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::ALL.into_iter().find(|card| card.key() == key)
+    }
+}
+
+impl From 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 = 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..353bed5
--- /dev/null
+++ b/crates/design/src/palette/mod.rs
@@ -0,0 +1,67 @@
+//! # 配色来源（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 轴修正，并记录「改了什么」。
+//! - [`visibility`]：容器层可视性裁决（状态容器对 `surface` 的 1.20:1 门禁 + 容器阶梯单调），
+//!   即债务台账「SecondaryContainer 对 Surface 仅 1.06」的令牌层结论。
+//! - [`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 visibility;
+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 visibility::{
+    check_surface_hierarchy, LayerStep, SurfaceHierarchy, LAYER_ROLES, LAYER_STEP_MIN_LSTAR,
+    STATE_CONTAINERS, STATE_CONTAINER_MIN,
+};
+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 {
+    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 {
+    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 {
+    let mut by_population: Vec = (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 = 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> = 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 = 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>,
+    wallpaper: Option>,
+    preset: Option,
+    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,
+        seed: Seed,
+        adjustments: Vec,
+    },
+}
+
+fn try_level(input: Option>, 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 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,
+    /// 深浅模式。
+    pub flavor: SchemeFlavor,
+    /// 对比度收敛改了哪些角色（空 = 没动）。
+    pub adjustments: Vec,
+    /// 三级各自的处置结果（`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 {
+    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 {
+    let total: u64 = clusters.iter().map(|c| u64::from(c.population)).sum();
+    if total == 0 {
+        return Vec::new();
+    }
+
+    let hcts: Vec = 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 = 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::>(),
+            second.iter().map(|r| r.cluster.color).collect::>()
+        );
+    }
+
+    #[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 {
+    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`（`None` = 这张图没有可用的颜色信息）。
+///
+/// 需要知道「为什么没有」就用 [`analyze_rgba`]。
+pub fn seed_from_rgba(pixels: &[u8], width: u32, height: u32) -> Option {
+    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 {
+    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 {
+    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 {
+    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/visibility.rs b/crates/design/src/palette/visibility.rs
new file mode 100644
index 0000000..d0ebfe3
--- /dev/null
+++ b/crates/design/src/palette/visibility.rs
@@ -0,0 +1,219 @@
+//! # 容器层可视性裁决（债务台账「SecondaryContainer 对 Surface 仅 1.06」的令牌层结论）
+//!
+//! ## 问题
+//!
+//! m223 视觉复审实测：选中行底（`SecondaryContainer`）与它压着的卡片只差 **1.057:1**，
+//! 大色块 + 色相偏移肉眼可辨，但**数不出层级**。逐个页面补色修不完（每个用选中底色的页面都要
+//! 自己调一次，而且下一套色板又得来一遍），所以裁决必须落在令牌层。
+//!
+//! ## 裁决（三条，按顺序适用）
+//!
+//! 1. **文字对比**：所有 `on-*` 对承载色 ≥ 4.5:1 —— 既有 [`super::wcag`] 那道门，不重复定义。
+//! 2. **状态容器对窗口底 ≥ [`STATE_CONTAINER_MIN`] = 1.20:1**：表达「状态」的容器
+//!    （[`STATE_CONTAINERS`]：primary / secondary / tertiary / error 的 `*-container`）压在
+//!    `surface` 上时必须数得出来。这是唯一一条**数字门禁**，[`SurfaceHierarchy::state_failures`]
+//!    守它。
+//! 3. **容器层之间的亮度差不设门禁，改为「组合指示」要求**：M3 的容器层天生贴在一起
+//!    （官方口径浅色 `secondary-container` 对 `surface-container-high` 只有 1.06:1，
+//!    本项目 Ink 板最低也只有 1.54:1 —— 这是配色结构的必然，不是哪套板的失误）。所以
+//!    **禁止**把「容器底色差异」当作唯一的选中 / 层级指示：选中态必须是
+//!    「容器底（过第 2 条）+ 文字对比（第 1 条）+ 形状 / 图标 / 描边指示」三件套。
+//!    另一半同理：`surface-container-*` 只表达「几乎看不见的抬升」，
+//!    拿它当选中态用连第 2 条都过不了。
+//!
+//! 第 3 条为什么不是「把阈值降到 1.02 就完事」：那样等于承认「选中态可以看不见」，
+//! 而用户抱怨的正是这个。把不可测的那一半转成**构成要求**，才是能落地的那一半。
+//!
+//! ## 实测（`tests/ink_cat_visibility.rs` 守住第 2 条与阶梯）
+//!
+//! | 板 | 最弱状态容器 / `surface` | 状态容器 / 容器层（4×5 全矩阵，最低 ~ 最高） | 阶梯 L\\* 步长 |
+//! |---|---|---|---|
+//! | Ink | **1.97**（secondary-container） | 1.54 ~ **16.47** | +1.4 ~ +4.4 |
+//! | Silver | **1.23**（tertiary/error-container） | **1.02** ~ 1.80 | −1.7 ~ −4.1 |
+//! | 旧 baseline（债务现场） | 1.23 | **1.057**（对卡片，m223 实测） | — |
+//!
+//! 第三列就是第 3 条的由来：它过不了任何有意义的门禁（Silver 最差的一组是
+//! `tertiary-container` 压 `surface-container-high`，1.016 —— 两者几乎同亮度），
+//! 所以不设门禁、只设组合要求。
+//!
+//! ## 阶梯本身还是要查（[`SurfaceHierarchy::layer_violations`]）
+//!
+//! `surface-container-lowest` → `highest` 必须**单调**且相邻步长 ≥ [`LAYER_STEP_MIN_LSTAR`]
+//! （1.0 个 L\\* 单位）。方向由深浅模式决定：深色板递增（越靠上越亮）、浅色板递减。
+//! 这条抓的是「两档写成同一个色」「顺序填反」这类事故——不抓「差距够不够好看」。
+
+use crate::color::{Role, Scheme, SchemeFlavor};
+
+/// 状态容器对 `surface` 的最低对比度（唯一的**数字**门禁）。
+pub const STATE_CONTAINER_MIN: f32 = 1.20;
+
+/// 层级阶梯相邻两档的最小 L\\* 步长（低于这个数就分不出「哪层更高」）。
+pub const LAYER_STEP_MIN_LSTAR: f32 = 1.0;
+
+/// 表达**状态**的容器角色（必须过 [`STATE_CONTAINER_MIN`]）。
+pub const STATE_CONTAINERS: [Role; 4] = [
+    Role::PrimaryContainer,
+    Role::SecondaryContainer,
+    Role::TertiaryContainer,
+    Role::ErrorContainer,
+];
+
+/// 表达**层级**的容器角色（由低到高；只查阶梯单调与步长）。
+pub const LAYER_ROLES: [Role; 5] = [
+    Role::SurfaceContainerLowest,
+    Role::SurfaceContainerLow,
+    Role::SurfaceContainer,
+    Role::SurfaceContainerHigh,
+    Role::SurfaceContainerHighest,
+];
+
+/// 阶梯上的一步：相对**前一档**的 L\\* 变化量（带符号；深色板应为正、浅色板为负）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct LayerStep {
+    /// 这一档是谁。
+    pub role: Role,
+    /// 相对前一档的 L\\* 差。
+    pub delta_lstar: f32,
+}
+
+/// 一套方案的容器层可视性体检结果（纯数据，不改方案）。
+#[derive(Debug, Clone, PartialEq)]
+pub struct SurfaceHierarchy {
+    /// 方案自己的深浅模式（决定阶梯方向）。
+    pub flavor: SchemeFlavor,
+    /// `surface` 的 L\\*（报告与对账用）。
+    pub surface_lstar: f32,
+    /// 每个状态容器对 `surface` 的实测对比度（顺序同 [`STATE_CONTAINERS`]）。
+    pub state: [(Role, f32); 4],
+    /// 层级阶梯的实测 L\\*（顺序同 [`LAYER_ROLES`]）。
+    pub layers: [(Role, f32); 5],
+}
+
+impl SurfaceHierarchy {
+    /// 状态容器里最低的一档（观察「刚好卡线」用）。
+    pub fn worst_state(&self) -> (Role, f32) {
+        self.state.iter().copied().fold(
+            self.state[0],
+            |acc, item| if item.1 < acc.1 { item } else { acc },
+        )
+    }
+
+    /// 未达 [`STATE_CONTAINER_MIN`] 的状态容器。
+    pub fn state_failures(&self) -> Vec<(Role, f32)> {
+        self.state
+            .iter()
+            .copied()
+            .filter(|(_, ratio)| *ratio < STATE_CONTAINER_MIN)
+            .collect()
+    }
+
+    /// 阶梯的每一步（4 步：lowest→low→container→high→highest）。
+    pub fn layer_steps(&self) -> [LayerStep; 4] {
+        let mut out = [LayerStep {
+            role: LAYER_ROLES[1],
+            delta_lstar: 0.0,
+        }; 4];
+        for i in 1..self.layers.len() {
+            out[i - 1] = LayerStep {
+                role: self.layers[i].0,
+                delta_lstar: self.layers[i].1 - self.layers[i - 1].1,
+            };
+        }
+        out
+    }
+
+    /// 方向反了或步长不足的阶梯步（深色板要递增、浅色板要递减）。
+    pub fn layer_violations(&self) -> Vec {
+        let sign = if self.flavor == SchemeFlavor::Dark {
+            1.0
+        } else {
+            -1.0
+        };
+        self.layer_steps()
+            .into_iter()
+            .filter(|step| step.delta_lstar * sign < LAYER_STEP_MIN_LSTAR)
+            .collect()
+    }
+
+    /// 第 2 条与阶梯都过。
+    pub fn is_clean(&self) -> bool {
+        self.state_failures().is_empty() && self.layer_violations().is_empty()
+    }
+}
+
+/// 跑一遍容器层体检（纯函数）。
+pub fn check_surface_hierarchy(scheme: &Scheme) -> SurfaceHierarchy {
+    let surface = scheme.get(Role::Surface);
+    SurfaceHierarchy {
+        flavor: scheme.flavor(),
+        surface_lstar: surface.lstar(),
+        state: std::array::from_fn(|i| {
+            let role = STATE_CONTAINERS[i];
+            (role, scheme.contrast(role, Role::Surface))
+        }),
+        layers: std::array::from_fn(|i| {
+            let role = LAYER_ROLES[i];
+            (role, scheme.get(role).lstar())
+        }),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::color::{Color, Scheme};
+
+    #[test]
+    fn dark_ladder_must_climb_and_light_ladder_must_fall() {
+        // 造假：深色板把 highest 设成纯黑 → 阶梯反向，必须被抓住。
+        let base = Scheme::baseline(SchemeFlavor::Dark);
+        let mut colors = [Color::BLACK; 49];
+        for (role, color) in base.iter() {
+            colors[role as usize] = color;
+        }
+        colors[Role::SurfaceContainerHighest as usize] = Color::BLACK;
+        let broken = Scheme::from_colors(SchemeFlavor::Dark, colors);
+        let report = check_surface_hierarchy(&broken);
+        assert!(
+            report
+                .layer_violations()
+                .iter()
+                .any(|step| step.role == Role::SurfaceContainerHighest),
+            "{:?}",
+            report.layer_steps()
+        );
+        assert!(!report.is_clean());
+    }
+
+    #[test]
+    fn state_container_below_the_floor_is_reported() {
+        // 造假：secondary-container 直接等于 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::SecondaryContainer as usize] = base.get(Role::Surface);
+        let broken = Scheme::from_colors(SchemeFlavor::Light, colors);
+        let report = check_surface_hierarchy(&broken);
+        assert_eq!(
+            report.state_failures(),
+            vec![(Role::SecondaryContainer, 1.0)]
+        );
+    }
+
+    #[test]
+    fn the_official_baseline_shows_why_the_debt_exists() {
+        // 官方口径（tone 表）浅色板：状态容器对 surface 只有 ~1.23，对容器层只有 ~1.05。
+        // 前半条过不了 1.20 的是「白银下界」，后半条根本不可门禁化——这就是裁决第 3 条。
+        let report = check_surface_hierarchy(&Scheme::official_baseline(SchemeFlavor::Light));
+        let (role, ratio) = report.worst_state();
+        // 官方浅色的四个 container 都是 tone 90、surface 是 tone 98 ⇒ 四个值几乎相同，
+        // 所以只断言量级（1.23 上下），不断言「哪一族最弱」。
+        assert!(
+            (1.15..1.30).contains(&ratio),
+            "官方 baseline 的 {} 对 surface = {ratio:.3}，与文档的 1.23 不符",
+            role.name()
+        );
+    }
+}
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,
+    /// 全表里最低的对比度（用来观察「刚好卡线」的方案）。
+    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) {
+    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 {
+    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..238ecbf
--- /dev/null
+++ b/crates/design/src/shape.rs
@@ -0,0 +1,319 @@
+//! 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 / M182）
+//!
+//! `ShapeScale` 管的是**我们画的东西**：卡片、按钮、浮层、面板。窗口的最外层圆角由平台决定，
+//! 系统**不暴露**那个半径值，我们也不自己定一个数字（用户定案：不做 8/12/16 档；D46 也不许
+//! 自绘裁切）。三档平台的机制各不相同（M182 已逐条取证）：
+//!
+//! - Win11 / Server 2025：下发给 DWM；（Win10 及更早没有这个属性）
+//! - macOS：窗口服务器只给 **titled** 窗裁圆角，我们是 `decorations: false` 的 borderless 窗
+//!   ⇒ 不裁（`platform::macos` 里有三环证据与后续口径）；
+//! - X11 / Wayland：协议里没有圆角这回事，CSD 窗由客户端装饰 ⇒ 没人裁（`platform::linux`）。
+//!
+//! 所以窗口圆角没有令牌：判据在 `unlucky-app-iced` 的 `platform::plan_corner` /
+//! `platform::plan_corner_for`，Windows 的落点在 `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`，>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 {
+        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 的
+//! `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 四元组取 `{Size,LineHeight,Tracking,Weight}`，Expressive 强调档取
+//! `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 = 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::>()
+    };
+    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 = 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 = 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 = 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 {
+    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/ink_cat_boards.rs b/crates/design/tests/ink_cat_boards.rs
new file mode 100644
index 0000000..d1c77ae
--- /dev/null
+++ b/crates/design/tests/ink_cat_boards.rs
@@ -0,0 +1,285 @@
+//! Ink Cat 双主题的**消费方视角**门禁（M228）：色板完整性、双主题切换、对比度。
+//!
+//! 只用公开 API（`unlucky_design::...`），所以它同时是「iced 适配层能拿到什么」的样本：
+//! 换肤时只需要 `BrandBoard` → `Scheme` → `Role`，一个色值字面量都不用抄。
+//! 几何与字级校核在 `ink_cat_geometry.rs`，容器层可视性在 `ink_cat_visibility.rs`
+//! （拆开是单文件 ≤400 行的硬约束）。
+
+use unlucky_design::color::BrandBoard::{Ink, Silver};
+use unlucky_design::color::{BrandBoard, Color, Role, SchemeFlavor};
+use unlucky_design::palette::wcag::{check, AA_TEXT};
+use unlucky_design::DesignTokens;
+
+// ---------------------------------------------------------------- 色板完整性
+
+#[test]
+fn every_board_covers_all_49_roles_and_reports_its_flavor() {
+    for board in BrandBoard::ALL {
+        let scheme = board.scheme();
+        assert_eq!(scheme.flavor(), board.flavor());
+        assert_eq!(scheme.iter().count(), Role::ALL.len());
+        for role in Role::ALL {
+            let color = scheme.get(role);
+            assert!(
+                color.is_opaque(),
+                "{} 的 {} 不是不透明色",
+                board.name(),
+                role.name()
+            );
+            assert_eq!(color, board.get(role), "两个入口必须同源");
+        }
+    }
+}
+
+#[test]
+fn spec_anchors_survive_the_public_api() {
+    // 规格卡上写死的色值（两套板各自的一批），一份都不许漂。
+    let cases: [(BrandBoard, Role, &str); 12] = [
+        (BrandBoard::Ink, Role::Primary, "#E8FFEF"),
+        (BrandBoard::Ink, Role::OnPrimary, "#256B4B"),
+        (BrandBoard::Ink, Role::Surface, "#0F150F"),
+        (BrandBoard::Ink, Role::SurfaceContainerHighest, "#262B25"),
+        (BrandBoard::Ink, Role::Error, "#FF716C"),
+        (BrandBoard::Ink, Role::Outline, "#7B8A7B"),
+        (BrandBoard::Silver, Role::Primary, "#006499"),
+        (BrandBoard::Silver, Role::PrimaryContainer, "#87C7FF"),
+        (BrandBoard::Silver, Role::Surface, "#F9F9FA"),
+        (BrandBoard::Silver, Role::SecondaryContainer, "#D4E4F6"),
+        (BrandBoard::Silver, Role::OnSurface, "#1A1C1D"),
+        (BrandBoard::Silver, Role::Error, "#AC3434"),
+    ];
+    for (board, role, hex) in cases {
+        assert_eq!(
+            board.scheme().get(role),
+            Color::from_hex(hex).expect("规格卡色值"),
+            "{} / {} 与规格卡的 {hex} 不符",
+            board.name(),
+            role.name()
+        );
+    }
+}
+
+// ---------------------------------------------------------------- 双主题切换
+
+#[test]
+fn follow_system_resolves_to_the_right_board() {
+    // 「跟随系统」是设置层的第三种态，令牌层只提供映射。
+    assert_eq!(
+        BrandBoard::for_flavor(SchemeFlavor::Dark),
+        BrandBoard::Ink,
+        "系统深色 → Ink"
+    );
+    assert_eq!(
+        BrandBoard::for_flavor(SchemeFlavor::Light),
+        BrandBoard::Silver,
+        "系统浅色 → Silver"
+    );
+    for board in BrandBoard::ALL {
+        assert_eq!(
+            BrandBoard::for_flavor(board.flavor()),
+            board,
+            "映射必须可逆"
+        );
+    }
+}
+
+#[test]
+fn switching_boards_swaps_all_the_surface_roles() {
+    let ink = BrandBoard::Ink.scheme();
+    let silver = BrandBoard::Silver.scheme();
+    // 窗口底 / 正文 / 字段底 / 分层容器：切板后全都得换。
+    for role in [
+        Role::Surface,
+        Role::OnSurface,
+        Role::SurfaceContainerLow,
+        Role::SurfaceContainerHighest,
+        Role::Primary,
+        Role::SecondaryContainer,
+        Role::Error,
+        Role::InverseSurface,
+    ] {
+        assert_ne!(
+            ink.get(role),
+            silver.get(role),
+            "{} 在两套板之间没变——换肤会露出旧颜色",
+            role.name()
+        );
+    }
+    // 深浅判定：Ink 是真的深、Silver 是真的浅。
+    assert!(ink.get(Role::Surface).relative_luminance() < 0.02);
+    assert!(silver.get(Role::Surface).relative_luminance() > 0.90);
+}
+
+#[test]
+fn design_tokens_brand_entry_is_the_product_default() {
+    let ink = DesignTokens::brand(BrandBoard::Ink);
+    assert_eq!(ink.flavor, SchemeFlavor::Dark);
+    assert_eq!(ink.color(Role::Surface), BrandBoard::Ink.get(Role::Surface));
+    // 品牌板与「取色链」两条路径互不干扰：baseline 仍是 tone 派生（D38 的锚点）。
+    let baseline = DesignTokens::baseline(SchemeFlavor::Dark);
+    assert_eq!(baseline.flavor, SchemeFlavor::Dark);
+    assert_ne!(
+        baseline.color(Role::Surface),
+        ink.color(Role::Surface),
+        "baseline 若已变成品牌板，D38 取色链的表面色锚点就没了"
+    );
+}
+
+// ---------------------------------------------------------------- 对比度
+
+#[test]
+fn both_boards_pass_the_full_wcag_table() {
+    for board in BrandBoard::ALL {
+        let report = check(&board.scheme());
+        assert!(
+            report.is_clean(),
+            "{} 有 {} 项未达 AA：{:?}",
+            board.name(),
+            report.failures.len(),
+            report.failures
+        );
+        assert!(
+            report.worst >= AA_TEXT,
+            "{} 最紧的一对只有 {:.2}",
+            board.name(),
+            report.worst
+        );
+    }
+}
+
+/// 规格卡里真实出现的「文字压在什么色上」组合（25 组，含 `on-*-container` 全族）。
+///
+/// 只列规格卡上画出来的用法——不列「有可能这么用」的组合，否则就是在替页面线编需求。
+const SPEC_TEXT_ON_SURFACE: [(BrandBoard, Role, Role, &str); 25] = [
+    (Ink, Role::OnPrimary, Role::Primary, "Filled 按钮"),
+    (
+        Ink,
+        Role::OnSecondaryContainer,
+        Role::SecondaryContainer,
+        "Tonal 按钮",
+    ),
+    (Ink, Role::OnSurface, Role::Surface, "Outlined/Text 按钮"),
+    (Ink, Role::Primary, Role::Surface, "Text 按钮标签"),
+    (
+        Ink,
+        Role::Primary,
+        Role::SurfaceContainerLowest,
+        "Elevated 标签",
+    ),
+    (
+        Ink,
+        Role::OnPrimaryContainer,
+        Role::PrimaryContainer,
+        "FAB 图标",
+    ),
+    (
+        Ink,
+        Role::OnSurfaceVariant,
+        Role::SurfaceContainerHighest,
+        "字段标签",
+    ),
+    (
+        Ink,
+        Role::OnSurface,
+        Role::SurfaceContainerHighest,
+        "字段内容",
+    ),
+    (
+        Ink,
+        Role::Error,
+        Role::SurfaceContainerHighest,
+        "错误字段标签",
+    ),
+    (Ink, Role::Error, Role::Surface, "错误提示"),
+    (Ink, Role::OnError, Role::Error, "徽标数字"),
+    (
+        Ink,
+        Role::OnSurfaceVariant,
+        Role::Surface,
+        "chip 未选 / 次要图标",
+    ),
+    (
+        Ink,
+        Role::InverseOnSurface,
+        Role::InverseSurface,
+        "snackbar 文字",
+    ),
+    (
+        Ink,
+        Role::InversePrimary,
+        Role::InverseSurface,
+        "snackbar 动作",
+    ),
+    (
+        Ink,
+        Role::OnSurfaceVariant,
+        Role::SurfaceContainer,
+        "卡片副文案",
+    ),
+    (
+        Ink,
+        Role::OnSurfaceVariant,
+        Role::SurfaceContainerHigh,
+        "对话框正文",
+    ),
+    (Silver, Role::OnPrimary, Role::Primary, "Filled 按钮"),
+    (
+        Silver,
+        Role::OnSecondaryContainer,
+        Role::SecondaryContainer,
+        "Tonal 按钮",
+    ),
+    (Silver, Role::OnSurface, Role::Surface, "Outlined 按钮"),
+    (Silver, Role::Primary, Role::Surface, "Text 按钮标签"),
+    (
+        Silver,
+        Role::OnSurfaceVariant,
+        Role::SurfaceContainerHighest,
+        "字段标签",
+    ),
+    (
+        Silver,
+        Role::OnSurface,
+        Role::SurfaceContainerHighest,
+        "字段内容",
+    ),
+    (
+        Silver,
+        Role::Error,
+        Role::SurfaceContainerHighest,
+        "错误字段标签",
+    ),
+    (
+        Silver,
+        Role::OnSurfaceVariant,
+        Role::SurfaceContainer,
+        "卡片副文案",
+    ),
+    (
+        Silver,
+        Role::InverseOnSurface,
+        Role::InverseSurface,
+        "snackbar 文字",
+    ),
+];
+
+#[test]
+fn spec_text_pairs_meet_aa() {
+    let mut failures = Vec::new();
+    for (board, fg, bg, usage) in SPEC_TEXT_ON_SURFACE {
+        let ratio = board.scheme().contrast(fg, bg);
+        if ratio < AA_TEXT {
+            failures.push(format!(
+                "{} / {usage}：{} on {} = {ratio:.2}",
+                board.name(),
+                fg.name(),
+                bg.name()
+            ));
+        }
+    }
+    assert!(
+        failures.is_empty(),
+        "规格卡用法未达 AA（4.5:1）：\n{}",
+        failures.join("\n")
+    );
+}
diff --git a/crates/design/tests/ink_cat_geometry.rs b/crates/design/tests/ink_cat_geometry.rs
new file mode 100644
index 0000000..3bae90a
--- /dev/null
+++ b/crates/design/tests/ink_cat_geometry.rs
@@ -0,0 +1,100 @@
+//! Ink Cat 规格卡的**几何与字级**门禁（M228）：按钮 XS~XL、FAB 四态、控件方框、字号校核。
+//!
+//! 与 `ink_cat_boards.rs` 分开是单文件 ≤400 行的硬约束；两侧都只用公开 API。
+
+use unlucky_design::inkcat::metrics;
+use unlucky_design::inkcat::size::{ControlSize, FabSize};
+use unlucky_design::inkcat::type_scale::{SpecFit, SpecText, UI_TEXT_FLOOR_PX};
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::typography::{TypeRole, Weight};
+
+#[test]
+fn buttons_and_fabs_hit_the_spec_geometry() {
+    // 按钮五档：32/40/56/96/136，圆角一律半高（药丸）。
+    let heights: Vec = ControlSize::ALL.iter().map(|s| s.height_px()).collect();
+    assert_eq!(heights, vec![32.0, 40.0, 56.0, 96.0, 136.0]);
+    for size in ControlSize::ALL {
+        assert_eq!(
+            size.radius_px(),
+            size.height_px() / 2.0,
+            "{size:?} 该是药丸"
+        );
+    }
+    // M 档就是规格卡 `BUTTONS / 5 LEVELS` 那一行的 56 高。
+    assert_eq!(ControlSize::M.height_px(), 56.0);
+    assert_eq!(ControlSize::M.label_px(), 16.0);
+
+    // FAB 四态圆角 12/16/20/16（都不是半高，所以不用 Full）。
+    let radii: Vec = FabSize::ALL.iter().map(|s| s.radius_px()).collect();
+    assert_eq!(radii, vec![12.0, 16.0, 20.0, 16.0]);
+    let sizes: Vec = FabSize::ALL.iter().map(|s| s.height_px()).collect();
+    assert_eq!(sizes, vec![40.0, 56.0, 80.0, 56.0]);
+}
+
+#[test]
+fn component_boxes_hit_the_spec_corners() {
+    assert_eq!(metrics::CARD.radius_px(), 16.0, "ELEVATED CARD rx=16");
+    assert_eq!(metrics::DIALOG.radius_px(), 28.0, "对话框 rx=28");
+    assert_eq!(metrics::SNACKBAR.radius_px(), 16.0, "snackbar rx=16");
+    assert_eq!(metrics::SNACKBAR.height, 52.0);
+    assert_eq!(metrics::LIST_ROW.radius_px(), 30.0, "列表行药丸");
+    assert_eq!(metrics::LIST_ROW.height, 60.0);
+    assert_eq!(metrics::CHIP.height, 32.0);
+    assert_eq!(metrics::CHIP.radius_px(), 8.0);
+    // 输入框：默认圆角 4、药丸变体 28，内距 16 / 32（规格卡专门提醒过）。
+    assert_eq!(metrics::FIELD_SHAPE, ShapeScale::ExtraSmall);
+    assert_eq!(metrics::FIELD_SHAPE_ROUNDED, ShapeScale::ExtraLarge);
+    assert_eq!(metrics::FIELD_HEIGHT, 56.0);
+    assert_eq!(metrics::FIELD_INSET, 16.0);
+    assert_eq!(metrics::FIELD_PILL_INSET, 32.0);
+    // 开关 / 勾选 / 进度。
+    assert_eq!(
+        (metrics::SWITCH_TRACK.width, metrics::SWITCH_TRACK.height),
+        (52.0, 32.0)
+    );
+    assert_eq!(metrics::SWITCH_THUMB, 24.0);
+    assert_eq!(metrics::CHECKBOX.radius_px(), 4.0);
+    assert_eq!(metrics::PROGRESS_THICKNESS, 4.0);
+}
+
+#[test]
+fn spec_font_sizes_map_onto_the_official_scale() {
+    // 命中官方档的六档。
+    for (text, role) in [
+        (SpecText::ControlLabelSmall, TypeRole::TitleSmall),
+        (SpecText::DialogTitle, TypeRole::HeadlineSmall),
+        (SpecText::DisplayLabel, TypeRole::HeadlineLarge),
+        (SpecText::Caption, TypeRole::BodySmall),
+        (SpecText::Badge, TypeRole::LabelSmall),
+    ] {
+        assert_eq!(text.fit(), SpecFit::Exact(role), "{text:?}");
+    }
+    // 落在两档之间的三档：取较大那档，登记 1px 级偏离。
+    for (text, lower, upper) in [
+        (SpecText::Body, TypeRole::BodySmall, TypeRole::TitleSmall),
+        (
+            SpecText::Subtitle,
+            TypeRole::TitleSmall,
+            TypeRole::TitleMedium,
+        ),
+        (
+            SpecText::PageTitle,
+            TypeRole::DisplaySmall,
+            TypeRole::DisplayMedium,
+        ),
+    ] {
+        assert_eq!(text.fit(), SpecFit::Between(lower, upper), "{text:?}");
+        assert_eq!(text.fit().recommended(), Some(upper));
+    }
+    // 低于 UI 下限的两档：只能是设计稿标注。
+    for text in [SpecText::SectionCaps, SpecText::SwatchCaption] {
+        assert!(!text.in_ui(), "{text:?} 不该进 UI");
+        assert_eq!(text.fit(), SpecFit::BelowFloor);
+        assert_eq!(text.fit().recommended(), None);
+    }
+    assert_eq!(UI_TEXT_FLOOR_PX, 11.0);
+    // 按钮标签字重：规格卡是 500（官方 body/headline 是 400，这是按钮语义）。
+    for size in ControlSize::ALL {
+        assert_eq!(size.label().weight, Weight::Medium);
+    }
+}
diff --git a/crates/design/tests/ink_cat_visibility.rs b/crates/design/tests/ink_cat_visibility.rs
new file mode 100644
index 0000000..4b5ccff
--- /dev/null
+++ b/crates/design/tests/ink_cat_visibility.rs
@@ -0,0 +1,133 @@
+//! Ink Cat 容器层可视性门禁（M228 债务裁决的可测一半）：状态容器 1.20 门禁、阶梯单调、
+//! 以及「容器层不能当状态指示」的实测钉子。
+//!
+//! 与 `ink_cat_boards.rs` / `ink_cat_geometry.rs` 分开是单文件 ≤400 行的硬约束。
+
+use unlucky_design::color::{BrandBoard, Color, Role, SchemeFlavor};
+use unlucky_design::palette::visibility::{
+    check_surface_hierarchy, LAYER_ROLES, STATE_CONTAINERS, STATE_CONTAINER_MIN,
+};
+use unlucky_design::palette::wcag::AA_TEXT;
+
+#[test]
+fn state_containers_clear_the_visibility_floor() {
+    // 债务台账「SecondaryContainer 对 Surface 仅 1.06」的令牌层裁决：状态容器 ≥1.20:1。
+    for board in BrandBoard::ALL {
+        let report = check_surface_hierarchy(&board.scheme());
+        assert!(
+            report.state_failures().is_empty(),
+            "{} 的状态容器未达 {STATE_CONTAINER_MIN}:1：{:?}",
+            board.name(),
+            report.state_failures()
+        );
+        let (role, ratio) = report.worst_state();
+        assert!(
+            ratio >= STATE_CONTAINER_MIN,
+            "{} 最弱的状态容器 {} 只有 {ratio:.3}",
+            board.name(),
+            role.name()
+        );
+        // 旧 baseline 的现场值 1.057 必须被显著甩开，否则「修了但没修好」。
+        assert!(
+            ratio > 1.20,
+            "{} 只是刚好卡线（{ratio:.3}），等于没修",
+            board.name()
+        );
+    }
+    // 两套板覆盖 4 个状态容器角色，一个不落。
+    assert_eq!(STATE_CONTAINERS.len(), 4);
+}
+
+#[test]
+fn surface_container_ladder_is_monotone_with_visible_steps() {
+    for board in BrandBoard::ALL {
+        let report = check_surface_hierarchy(&board.scheme());
+        assert!(
+            report.layer_violations().is_empty(),
+            "{} 的容器阶梯有断层或方向错：{:?}",
+            board.name(),
+            report.layer_violations()
+        );
+        assert!(report.is_clean(), "{} 的容器层体检没过", board.name());
+        // 方向：深色板越靠上越亮、浅色板越靠上越暗。
+        let steps = report.layer_steps();
+        for step in steps {
+            let expect_positive = board.flavor() == SchemeFlavor::Dark;
+            assert_eq!(
+                step.delta_lstar > 0.0,
+                expect_positive,
+                "{} 的 {} 阶梯方向错",
+                board.name(),
+                step.role.name()
+            );
+        }
+        assert_eq!(LAYER_ROLES.len(), 5);
+    }
+}
+
+#[test]
+fn container_layers_are_not_state_indicators() {
+    // 裁决第 3 条的可测化一半：把「状态容器压在容器层上」的最差值钉住，提醒后来者
+    // 别把它当唯一指示（浅色板必然贴到 1.02，深色板 1.54）。
+    let worst_over_layers = |board: BrandBoard| {
+        let scheme = board.scheme();
+        STATE_CONTAINERS
+            .iter()
+            .flat_map(|role| {
+                LAYER_ROLES
+                    .iter()
+                    .map(move |layer| (*role, *layer, scheme.contrast(*role, *layer)))
+            })
+            .map(|(_, _, ratio)| ratio)
+            .fold(f32::INFINITY, f32::min)
+    };
+    let silver = worst_over_layers(BrandBoard::Silver);
+    assert!(
+        (1.0..1.1).contains(&silver),
+        "Silver 的状态容器对容器层最低 = {silver:.3}，与「浅色 pale-on-pale 必然贴近」的登记（1.02）不符"
+    );
+    // Ink 相反：深色板的状态容器与容器层拉得开，所以深色可以靠底色差做弱指示。
+    let ink = worst_over_layers(BrandBoard::Ink);
+    assert!(
+        ink >= 1.5,
+        "Ink 最弱的状态容器对容器层 = {ink:.3}，应明显高于浅色板"
+    );
+    // 两条一起说明「为什么这不是调色问题而是构成问题」：同一套算法下深色能做的弱指示，
+    // 浅色做不到——所以门禁不能按容器层设，只能按 surface 设。
+    assert!(silver < ink);
+}
+
+#[test]
+fn field_backdrop_is_the_same_role_on_both_boards() {
+    // P2-1 的回归钉子：字段底在两套板都是 `surface-container-highest`。
+    // 若把 Silver 的字段底挪回 `surface-container-high`（#E4E4E5），错误标签会从 4.69 掉到 4.38（AA 失守）。
+    for board in BrandBoard::ALL {
+        let scheme = board.scheme();
+        for (fg, usage) in [
+            (Role::OnSurfaceVariant, "字段标签"),
+            (Role::OnSurface, "字段内容"),
+            (Role::Error, "错误字段标签"),
+        ] {
+            let ratio = scheme.contrast(fg, Role::SurfaceContainerHighest);
+            assert!(
+                ratio >= AA_TEXT,
+                "{} 的{usage}（{} on surface-container-highest）= {ratio:.3}",
+                board.name(),
+                fg.name()
+            );
+        }
+    }
+    // 浅色板的 high 必须比 highest 更亮、且是另一个色（阶梯方向 + 不许两档同值）。
+    let silver = BrandBoard::Silver.scheme();
+    let high = silver.get(Role::SurfaceContainerHigh);
+    let highest = silver.get(Role::SurfaceContainerHighest);
+    assert_ne!(high, highest);
+    assert!(
+        high.lstar() > highest.lstar(),
+        "Silver 的 surface-container-high 应比 highest 更亮（高 {} vs 最高 {}）",
+        high.lstar(),
+        highest.lstar()
+    );
+    // 规格卡给的字段底就是 highest 那个值。
+    assert_eq!(highest, Color::from_hex("#DCDDDE").expect("规格卡字段底"));
+}
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 = 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..c5bf211
--- /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()`（全仓唯一那份显示词表）
+    ("原版", 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..7a61255
--- /dev/null
+++ b/crates/i18n/src/catalog.rs
@@ -0,0 +1,354 @@
+//! 消息目录：`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 font_install;
+mod general;
+mod instances;
+mod launch;
+mod loader;
+mod logs;
+mod nav;
+mod settings;
+mod update;
+
+/// 拆分前的 `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 font_install::font_install_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_accent_entries, settings_ai_entries, settings_appearance_entries,
+    settings_download_entries, settings_general_entries, settings_java_entries,
+};
+use update::update_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,
+    // M159：自更新（设置页「更新」分组 + 顶部提示条）。同样只追加在链尾之后。
+    update_entries,
+    // M168：中文字体下载状态行（设置页 General 组）。同样只追加在链尾之后——
+    // `catalog/font.rs` 那四条老文案在链中间，往那里追加会平移其后所有 key（金表整片红）。
+    font_install_entries,
+    // M250：强调色一族（设置页 Appearance 组的第一个控件）。同理追加在链尾——`appearance`
+    // 那个域在链中间，往那里追加会平移其后所有 key（金表整片红）。
+    settings_accent_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::ALL
+            .iter()
+            .copied()
+            .filter(|key| self.get(*key).is_none())
+            .collect()
+    }
+
+    /// 人话诊断（`None` = 没有缺译）。一条缺译一行，附带英文原文当参考。
+    #[must_use]
+    pub fn diagnose(&self) -> Option {
+        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(|| "".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..56bcdd1
--- /dev/null
+++ b/crates/i18n/src/catalog/account.rs
@@ -0,0 +1,243 @@
+//! 账户页文案（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", "用浏览器登录"),
+            // M178 复审 r1 P2-5：这是**主按钮**（设备码流），不能读起来像备选。
+            AccountDeviceSignIn => ("Sign in with your Microsoft account", "使用 Microsoft 账户登录"),
+            AccountDeviceFallbackHint => ("No browser handy? This way shows a code you can type on any device.", "浏览器打不开就用这个：它会给一串用户码，在任何设备上输入即可。"),
+            // ── 第三方站表单
+            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.", "登录失败，完整原因在启动器日志里。"),
+            // M132：缺 client id 是**配置项缺失**，原因就是用户能执行的下一步，所以这一条
+            // 必须自己说清「缺什么、怎么补」，不许退回上面那句「完整原因在日志里」。
+            // 纪律：只写环境变量名与 `` 占位，**不许出现任何真实 client id**；
+            // 也不许写成「未支持 / unsupported」——登录链路是完整的。
+            AccountLoginNotConfigured => ("Microsoft sign-in is not configured", "微软登录未配置"),
+            AccountFailureMsaNotConfigured => (
+                "This build has no Azure public client id, so Microsoft sign-in cannot start (the sign-in flow itself is implemented). Set the environment variable ULL_MSA_CLIENT_ID= before starting the launcher, or build with ULL_MSA_CLIENT_ID=. Then restart the launcher: a running process does not pick up a new environment variable.",
+                "本启动器没有配置 Azure 公共客户端 id，微软登录无法开始（登录功能已实现，只差这一项配置）。启动前设置环境变量 ULL_MSA_CLIENT_ID=，或构建时注入：ULL_MSA_CLIENT_ID= cargo build。改完请重启启动器——已在运行的进程读不到新设的环境变量。"
+            ),
+            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.", "本地档案没有可重新登录的服务器账户，请新建一个档案。"),
+            // ── 浏览器登录回退到设备码的说明（M178）
+            // 口径：这不是「登录失败」——设备码接着跑。第一句说清「已改用设备码」，
+            // 需要改配置的那一条**必须给可照抄的下一步**（哪个门户、加什么值、端口不参与匹配），
+            // 且**不许**出现 AAD 的原始报文（`invalid_request` / `AADSTS…` / JSON）——
+            // 用户 2026-11-08 实测撞到的就是那张原始错误页。
+            AccountBrowserFallbackNotRegistered => (
+                "This build's app registration has no loopback redirect URI, so browser sign-in cannot work; switched to a device code. To fix: add http://localhost/auth under Redirect URIs in the Azure app registration (the port is ignored), then restart the launcher.",
+                "这个构建的应用注册里没有登记回环重定向 URI，浏览器登录用不了，已自动改用设备码。怎么修：在 Azure 应用注册的「重定向 URI」里加上 http://localhost/auth（端口不参与匹配），然后重启启动器。"
+            ),
+            AccountBrowserFallbackUnverified => (
+                "Could not confirm that browser sign-in is usable, so it switched to a device code.",
+                "没能确认浏览器登录是否可用（预检没成功），已自动改用设备码。"
+            ),
+            AccountBrowserFallbackFailed => (
+                "Browser sign-in did not finish, so it switched to a device code. If the browser page said the redirect URI is not valid, add http://localhost/auth under Redirect URIs of the app registration.",
+                "浏览器登录没有完成，已自动改用设备码。如果浏览器里提示 redirect_uri 无效，请把 http://localhost/auth 加进应用注册的「重定向 URI」。"
+            ),
+        } }
+    };
+}
+
+pub(crate) use account_entries;
+
+#[cfg(test)]
+mod tests {
+    use crate::{Catalog, Key, Lang};
+
+    /// **M178**：浏览器登录回退到设备码时那一句，必须「说清为什么 + 怎么修」，且**不许**把
+    /// AAD 的原始报文搬上屏（用户实测撞到的正是那张 `invalid_request ... redirect_uri` 错误页）。
+    ///
+    /// 抓得住：文案退回「登录失败，完整原因在日志里」、删掉可照抄的重定向 URI、或有人把
+    /// AAD 原始错误码/JSON 塞进词条。
+    /// 抓不住：读起来顺不顺（那靠 review 与截图）。
+    #[test]
+    fn the_browser_fallback_copy_explains_itself_without_raw_aad_text() {
+        for &lang in Lang::ALL {
+            let catalog = Catalog::of(lang);
+            let not_registered = catalog.text(Key::AccountBrowserFallbackNotRegistered);
+            let unverified = catalog.text(Key::AccountBrowserFallbackUnverified);
+            let failed = catalog.text(Key::AccountBrowserFallbackFailed);
+            // 「已改用设备码」这条结论三句里都得有（用户要知道画面为什么变了）。
+            for copy in [not_registered, unverified, failed] {
+                assert!(
+                    copy.contains("device code") || copy.contains("设备码"),
+                    "{}: {copy}",
+                    lang.tag()
+                );
+                // 原文不上屏：这两条是 AAD 的机器码，出现即语言/脱敏纪律失效。
+                assert!(!copy.contains("invalid_request"), "{}: {copy}", lang.tag());
+                assert!(!copy.contains("AADSTS"), "{}: {copy}", lang.tag());
+                assert!(!copy.contains('{'), "{}: {copy}", lang.tag());
+            }
+            // 「没登记回环」这一条必须给**可照抄**的下一步（门户 + 值 + 端口不参与匹配）。
+            assert!(
+                not_registered.contains("http://localhost/auth"),
+                "{not_registered}"
+            );
+            assert!(
+                not_registered.to_lowercase().contains("redirect uri")
+                    || not_registered.contains("重定向 URI"),
+                "{not_registered}"
+            );
+            assert!(
+                not_registered.to_lowercase().contains("port") || not_registered.contains("端口"),
+                "{not_registered}"
+            );
+        }
+    }
+
+    /// **M132**：缺 client id 这条是本页唯一「说清原因」的失败文案，它的纪律比别的正文更硬。
+    ///
+    /// 抓得住：文案退回「登录失败 / 完整原因在日志里」、退化成「未支持」、或者只说缺 id 却
+    ///         不给要设的变量名；也能抓住有人把某个真实 client id 写进词条。
+    /// 抓不住：读起来顺不顺（那靠 review 与截图）。
+    #[test]
+    fn the_missing_client_id_copy_says_what_to_configure_in_both_languages() {
+        for &lang in Lang::ALL {
+            let catalog = Catalog::of(lang);
+            let title = catalog.text(Key::AccountLoginNotConfigured);
+            let body = catalog.text(Key::AccountFailureMsaNotConfigured);
+            let all = format!("{title}\n{body}");
+
+            assert!(body.contains("ULL_MSA_CLIENT_ID"), "{}: {all}", lang.tag());
+            assert!(
+                body.contains(""),
+                "示例只许用占位：{}: {all}",
+                lang.tag()
+            );
+            // 面板上是「标题 + 正文」一起：结论（未配置）给标题，怎么做给正文。
+            assert!(
+                all.to_lowercase().contains("not configured") || all.contains("未配置"),
+                "要说清「未配置」：{}: {all}",
+                lang.tag()
+            );
+            assert!(!body.to_lowercase().contains("unsupported"), "{all}");
+            assert!(
+                !body.contains("未支持") && !body.contains("未实现"),
+                "{all}"
+            );
+            // 不许退回「完整原因在日志里」那句（那正是用户报的 bug）
+            assert!(!body.contains("launcher log"), "{all}");
+            assert!(!body.contains("启动器日志"), "{all}");
+            // 硬约束：`ULL_MSA_CLIENT_ID=` 后面只许跟 `` 占位——写进来一个真 id 就红。
+            assert_eq!(
+                body.matches("ULL_MSA_CLIENT_ID=").count(),
+                body.matches("ULL_MSA_CLIENT_ID=").count(),
+                "示例里出现了真 id：{all}"
+            );
+        }
+        for &lang in Lang::ALL {
+            let catalog = Catalog::of(lang);
+            let title = catalog.text(Key::AccountLoginNotConfigured);
+            assert!(
+                title.to_lowercase().contains("not configured") || title.contains("未配置"),
+                "{}: {title}",
+                lang.tag()
+            );
+            assert!(
+                !title.contains('=') && !title.contains("ULL_MSA_CLIENT_ID"),
+                "标题只报结论，变量名在正文里：{title}"
+            );
+        }
+    }
+}
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..60b71e1
--- /dev/null
+++ b/crates/i18n/src/catalog/content.rs
@@ -0,0 +1,363 @@
+//! 内容库文案（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.", "检查网络后重试。"),
+            ContentOfflineTitle => ("No connection", "未联网"),
+            ContentOfflineBody => (
+                "Content search needs the network. Check your connection, 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}"),
+            ContentDetailFetching => ("Loading versions…", "正在取版本列表…"),
+            ContentDetailFetchFailed => (
+                "Could not load versions: {reason}",
+                "版本列表取不到：{reason}"
+            ),
+            ContentDetailVersionCount => ("{count} versions", "{count} 个版本"),
+            ContentDetailVersionLine => ("{number} · {kind} · {date}", "{number}（{kind}）· {date}"),
+            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 来源的安装尚未开放"
+            ),
+            // --- M191：安装失败的两档分组与「只重试这些」---
+            // 两档**各一条**：不兼容要换版本/加载器，取不到要检查网络，合并成一句会让用户
+            // 对着一条重试必然失败的项反复点重试。
+            ContentInstallFailedTitle => (
+                "Install did not finish — {count} items failed",
+                "安装未完成 —— {count} 项没装上"
+            ),
+            ContentInstallRetryIncompatible => (
+                "Not available for this version/loader",
+                "不兼容所选版本/加载器"
+            ),
+            ContentInstallRetryUnreachable => (
+                "Could not fetch (network or missing project)",
+                "取不到（网络 / 项目不存在）"
+            ),
+            ContentInstallRetryOnly => (
+                "Retry just these {count}",
+                "只重试这 {count} 个"
+            ),
+            ContentInstallRetryHint => (
+                "Retry asks again only for the items above; files that already landed stay put.",
+                "重试只重新解析上面这几项，已落盘的文件不动。"
+            ),
+            // --- 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 => (
+                "Cancel requested — the pipeline is stopping now; the real outcome follows.",
+                "已请求取消 —— 后台正在停手，真实结果随后给出。"
+            ),
+            PackStatusCancelled => ("Cancelled — rolled back", "已取消 —— 已回滚"),
+            PackCancelIncomplete => (
+                "Cancelled — rollback incomplete: the target directory may differ from before the import.",
+                "已取消 —— 回滚没做完：目标目录可能与导入前不同。"
+            ),
+            PackCancelTooLate => (
+                "The cancel arrived too late: this import already finished. The instance is kept; same-name files may already be overwritten.",
+                "取消来得太晚：这次导入已经跑完，实例会保留，同名文件可能已被覆盖。"
+            ),
+            PackOverwriteAction => ("Re-import, the pack wins", "以包为准重新导入"),
+            PackOverwriteNote => (
+                "Keeping both (renamed) is not supported yet: for each existing file you pick either “keep” or “overwrite”.",
+                "「两者都留（改名）」暂不支持：每个已存在的文件只能选「保留」或「覆盖」。"
+            ),
+            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", "三方哈希"),
+            PackPickTitle => (
+                "Before importing: {count} files already exist with different content",
+                "导入前：有 {count} 个文件已存在且内容不同"
+            ),
+            PackPickSummary => (
+                "Keep {keep} · overwrite {overwrite} · overwriting discards {bytes}",
+                "保留 {keep} · 覆盖 {overwrite} · 覆盖将丢弃 {bytes}"
+            ),
+            PackPickKeepAll => ("Keep all mine", "全部保留我的"),
+            PackPickOverwriteAll => ("Overwrite all", "全部覆盖"),
+            PackPickRowKeep => ("Keep", "保留"),
+            PackPickRowOverwrite => ("Overwrite", "覆盖"),
+            PackPickPage => ("Items {from}-{to} of {total}", "第 {from}-{to} 项，共 {total} 项"),
+            PackPickPrev => ("Previous", "上一页"),
+            PackPickNext => ("Next", "下一页"),
+            PackPickConfirm => ("Import with these choices", "按这些选择导入"),
+            PackPickCancel => ("Cancel import", "取消导入"),
+            PackPickDefaultNote => (
+                "Anything you do not change stays as you have it: file content is only replaced where you pick “Overwrite”.",
+                "没有改动的一律按「保留」：只有你点了「覆盖」的文件才会被包内内容替换。"
+            ),
+            PackPickUnknownRemote => (
+                "{count} remote entries only learn their path after download; they follow “keep”.",
+                "还有 {count} 条远端条目要下载后才知道路径，一律按「保留」处置。"
+            ),
+            PackPickSourceOverrides => ("in the pack (overrides/)", "包内 overrides/"),
+            PackPickSourceClientOverrides => ("in the pack (client-overrides/)", "包内 client-overrides/"),
+            PackPickSourceManifest => ("manifest files[]", "清单 files[]"),
+            PackPickDisk => ("yours: {size}", "你的：{size}"),
+            PackPickIncoming => ("pack: {size}", "包内：{size}"),
+            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", "读不出来，已跳过"),
+            // --- M161：导入结果的两种失败**不许共用一句话** ---
+            // 「预检没通过（一个字节都没写）」与「写进去之后回滚完成」是两件事：
+            // 前者用户去修包/修配置再试，后者说明已经动过目标目录。此前两者共用
+            // `PackStatusFailed`（"Import failed — rolled back"），预检失败时那句话是假的。
+            PackStatusFailedNotStarted => (
+                "Import failed — nothing was written",
+                "导入失败 —— 还没写任何文件"
+            ),
+            PackStatusFailedIncomplete => (
+                "Import failed — rollback did not finish",
+                "导入失败 —— 回滚没做完"
+            ),
+            PackFatalTitleNotStarted => (
+                "Preflight failed — nothing was written",
+                "预检未通过 —— 一个字节都没写"
+            ),
+            PackFatalTitleIncomplete => (
+                "Rollback did not finish — the target folder may differ",
+                "回滚没做完 —— 目标目录可能与导入前不同"
+            ),
+        } }
+    };
+}
+
+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..6e3ee35
--- /dev/null
+++ b/crates/i18n/src/catalog/download.rs
@@ -0,0 +1,156 @@
+//! 版本管理页文案（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} 或更新"
+            ),
+            // M222：下载页只做「原版 + 加载器」一层，Forge 父链只有命令行能走。中性说明，
+            // 不是错误（不禁用确认键、不套错误色）——所以它不走 `problem` 那条通道。
+            DownloadOptionsLiteLoaderVanillaOnly => (
+                "Vanilla parent only — Forge goes through the CLI",
+                "只叠原版；叠 Forge 请走命令行"
+            ),
+            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/font_install.rs b/crates/i18n/src/catalog/font_install.rs
new file mode 100644
index 0000000..d389514
--- /dev/null
+++ b/crates/i18n/src/catalog/font_install.rs
@@ -0,0 +1,72 @@
+//! 中文字体**下载状态行**的文案（M168）：设置页 General 组那一行的四态文字 + 三类失败原因。
+//!
+//! ## 为什么单开一个域文件（而不是塞进 `font.rs`）
+//!
+//! `catalog/font.rs` 那四条（`FontCjkNeedsDownload` / `FontCjkDownloading` / `FontCjkDownloadFailed`
+//! / `FontCjkReady`）是 M92「只发信号」时代的文案，位置在装配链**中间**。往那个域后面追加会把
+//! 其后所有 key 在 `Key::ALL` 里整体平移一位 ⇒ 金表（逐 index 逐字节）整片红。
+//!
+//! 本域挂在**链尾**（`update_entries` 之后），于是 `Key::ALL` 的既有顺序一个不动，金表只需在
+//! 末尾追加（M104 / M106 / M107 / M109 / M114 / M159 都是这条做法）。
+//!
+//! ## 四条状态各一句话（tower 定死的口径）
+//!
+//! | 状态 | 文案说什么 |
+//! |---|---|
+//! | 下载中 | 「正在获取中文字体…（16.9 MB）」——**没有**假进度条，有真实量（字节数）才写 |
+//! | 完成 | 「中文字体已就绪：⟨族名⟩」（复用 `FontCjkReady`） |
+//! | 失败 | 「获取失败（⟨三类原因之一⟩）。界面照常可用，用的是系统字体；再切一次语言可以重试」 |
+//! | 无需下载 | 系统已有字体 / 当前语言不需要，两条分开说（对用户是两件事） |
+//!
+//! 「探测不出」也要有话说：那是「不知道」，既不是「没有」也不是「不需要」——写清楚「未下载」，
+//! 免得用户以为我们偷偷下过一份。
+//!
+//! 域文件的形状见 [`crate::catalog`] 的「域装配」一节。
+
+macro_rules! font_install_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* {
+            $($acc)*
+            // ── 中文字体下载状态行（M168：设置页 General 组）
+            FontCjkStatusLabel => ("Chinese font", "中文字体"),
+            FontCjkStatusNotNeeded => (
+                "Not needed for this interface language",
+                "当前界面语言不需要中文字体"
+            ),
+            FontCjkStatusSystem => ("Ready (system font: {family})", "已就绪（系统字体：{family}）"),
+            FontCjkStatusDownloading => (
+                "Fetching a Chinese font… ({size})",
+                "正在获取中文字体…（{size}）"
+            ),
+            FontCjkStatusFailed => (
+                "Download failed ({reason}). The interface keeps working with system fonts; switch the language again to retry.",
+                "获取失败（{reason}）。界面照常可用，用的是系统字体；再切一次语言可以重试。"
+            ),
+            // 超时也归这一档（M168 复审 P2-2）：用户要分清「太慢/没网」与「内容不对」，
+            // 但不需要知道我们内部把它叫 Timeout 还是 Network。
+            FontCjkReasonNetwork => (
+                "network unreachable or too slow (timed out)",
+                "网络不通或太慢（超时）"
+            ),
+            FontCjkReasonIntegrity => (
+                "the mirror sent content that failed verification",
+                "镜像内容校验不通过"
+            ),
+            FontCjkReasonDisk => ("cannot write to the data directory", "写不进数据目录"),
+            FontCjkStatusUnknown => (
+                "Not determined yet; nothing was downloaded",
+                "尚未判定；没有下载任何字体"
+            ),
+            FontCjkStatusUnprobeable => (
+                "System fonts cannot be probed, so nothing was downloaded",
+                "无法探测系统字体，因此没有下载"
+            ),
+            FontCjkStatusHint => (
+                "Downloaded once into the data directory and cached; the next start does not download it again. A mirror can be set with ui.font_cdn.",
+                "只下这一次，缓存在数据目录里，下次启动不重下。镜像可用配置键 ui.font_cdn 指定。"
+            ),
+        } }
+    };
+}
+
+pub(crate) use font_install_entries;
diff --git a/crates/i18n/src/catalog/general.rs b/crates/i18n/src/catalog/general.rs
new file mode 100644
index 0000000..78f4c41
--- /dev/null
+++ b/crates/i18n/src/catalog/general.rs
@@ -0,0 +1,65 @@
+//! 设置页 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", "跟随系统"),
+            // M229：主题三态改成「Ink / Silver / 跟随系统」——前两档就是两块品牌色板
+            // （Ink = 深色主方案 / Silver = 浅色主方案），落盘仍是 `appearance.theme_mode` 的
+            // `dark` / `light` / `auto` 三个值，不新增配置键。
+            SettingsThemeInk => ("Ink", "Ink（深色）"),
+            SettingsThemeSilver => ("Silver", "Silver（浅色）"),
+            SettingsThemeHint => (
+                "Ink is the dark scheme, Silver the light one. Follow system picks between them as Windows switches.",
+                "Ink 是深色主方案，Silver 是浅色主方案；跟随系统会随 Windows 的深浅在这两块之间切换。"
+            ),
+            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", "下载"),
+            // `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..439dd70
--- /dev/null
+++ b/crates/i18n/src/catalog/golden.rs
@@ -0,0 +1,185 @@
+//! 金表的**表数据**（`Key::ALL` 顺序 × (en, zh-CN) 逐字快照，第一列是 `Key::name()`）。「为什么
+//! 有这张表、它抓得住什么」全在 `catalog.rs` 的 `mod golden;` 里；本文件只放数据。
+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}"),
+    ("InstancesCrashed", "the game crashed (exit {code})", "游戏崩溃（退出码 {code}）"),
+    ("InstancesSilentFailed", "exit 0, but never started", "退出码 0，没起来"),
+    ("InstancesStageDownload", "Downloading", "下载中"),
+    ("InstancesStageVerify", "Verifying", "校验中"),
+    ("InstancesStageLaunch", "Starting", "启动中"),
+    ("InstancesStageWindow", "Waiting for window", "等待游戏窗口"),
+    ("InstancesLaunchTitle", "LAUNCH OPTIONS", "启动参数"),
+    ("InstancesLaunchJvm", "JVM arguments", "JVM 参数"),
+    ("InstancesLaunchJvmHint", "Space separated, quotes allowed. Empty = follow the global extra JVM arguments (both are sent; on duplicates the instance wins).", "空格分隔、支持引号。留空 = 跟随全局附加 JVM 参数（两者叠加下发，同名选项实例赢）。"),
+    ("InstancesLaunchGame", "Game arguments", "游戏参数"),
+    ("InstancesLaunchGameHint", "Appended last, so they override earlier game arguments. Empty = nothing appended.", "追加在命令行最后，可覆盖前面的游戏参数。留空 = 不追加。"),
+    ("InstancesLaunchMemory", "Max memory (MiB)", "最大内存（MiB）"),
+    ("InstancesLaunchMemoryHint", "Empty = follow the global default ({default} MiB).", "留空 = 跟随全局默认（{default} MiB）。"),
+    ("InstancesLaunchJava", "Java executable", "Java 可执行文件"),
+    ("InstancesLaunchJavaHint", "Empty = follow the global setting, then auto-pick (managed > JAVA_HOME > PATH).", "留空 = 跟随全局设置，再退到自动挑选（托管 > 环境变量 > 系统路径）。"),
+    ("InstancesLaunchBackend", "Graphics backend", "图形后端"),
+    ("InstancesLaunchBackendGated", "Requires MC {min}+ (this instance: {version}). The flag is not sent on this version.", "需游戏版本 {min} 及以上（本实例 {version}），这个版本不会下发该参数。"),
+    ("InstancesLaunchEffective", "Effective: {value}", "生效：{value}"),
+    ("InstancesBackendDefault", "Default", "默认"),
+    ("InstancesBackendOpengl", "OpenGL", "OpenGL 后端"),
+    ("InstancesBackendVulkan", "Vulkan", "Vulkan 后端"),
+    ("InstancesLaunchSave", "Save", "保存"),
+    ("InstancesLaunchReset", "Reset to global", "恢复跟随全局"),
+    ("AdoptTitle", "Import an existing version", "导入已有版本"),
+    ("AdoptSubtitle", "Register versions another launcher already installed. Nothing is copied: versions, libraries and assets stay where they are.", "把别的启动器已经装好的版本登记成实例。不复制任何东西：versions / libraries / assets 原地不动。"),
+    ("AdoptScanning", "Scanning versions/…", "正在扫描 versions/…"),
+    ("AdoptEmpty", "No version found under {dir}. Install one here, or point the game folder at the .minecraft another launcher uses.", "在 {dir} 下一个版本都没找到。可以用本启动器装一个，或者把游戏目录指向别的启动器用的那个 .minecraft。"),
+    ("AdoptSelectLabel", "Pick a version", "选择版本"),
+    ("AdoptReady", "Ready", "可导入"),
+    ("AdoptBlocked", "{count} problem(s)", "{count} 个问题"),
+    ("AdoptRegistered", "Already used by {name}", "已被 {name} 使用"),
+    ("AdoptTargetLabel", "Where should the game run?", "游戏在哪个目录里跑"),
+    ("AdoptTargetInstanceDir", "New folder in ULL data (default)", "ULL 数据区新建目录（缺省）"),
+    ("AdoptTargetInstanceDirHint", "mods, saves and config stay out of the other launcher's .minecraft", "mods / saves / config 不会落进别人的 .minecraft"),
+    ("AdoptTargetShared", "Share the game folder", "共用游戏目录"),
+    ("AdoptTargetSharedHint", "mods, saves and config are written into the other launcher's .minecraft", "mods / saves / config 会写进别人的 .minecraft"),
+    ("AdoptTargetVersionDir", "Use the version folder", "用版本目录"),
+    ("AdoptTargetVersionDirHint", "player data grows inside versions/", "玩家数据会长在 versions/ 里"),
+    ("AdoptNameLabel", "Instance name (empty = version id)", "实例名（留空 = 版本 id）"),
+    ("AdoptPreview", "Check", "预检"),
+    ("AdoptConfirm", "Import", "导入"),
+    ("AdoptBack", "Back", "返回"),
+    ("AdoptClose", "Close", "关闭"),
+    ("AdoptPlanTitle", "Ready to import", "可以导入"),
+    ("AdoptPlanRunDir", "Game folder", "运行目录"),
+    ("AdoptPlanIsolation", "Isolation", "隔离方式"),
+    ("AdoptFailureTitle", "Import failed", "导入失败"),
+    ("AdoptProblemCount", "Every reason is listed below:", "全部原因如下："),
+    ("AdoptInstanceName", "Instance name", "实例名"),
+    ("AdoptDoneTitle", "Imported", "已导入"),
+    ("AdoptDoneHint", "It is in the instance list now. Player data will live in the game folder below.", "它已经出现在实例列表里；玩家数据会落在下面这个运行目录。"),
+    ("InstancesModsTitle", "MODS", "模组"),
+    ("InstancesModsCount", "{enabled} enabled · {disabled} disabled", "{enabled} 启用 · {disabled} 禁用"),
+    ("InstancesModsLoading", "Reading mods/…", "正在读取 mods/…"),
+    ("InstancesModsEmpty", "No mods here yet — put jars into mods/ and they show up.", "这里还没有模组——把模组文件放进 mods/ 就会出现在这里。"),
+    ("InstancesModsMissingDir", "This instance has no mods/ directory yet.", "这个实例还没有 mods/ 目录。"),
+    ("InstancesModsRunning", "The game is running — toggles are read-only until it exits.", "游戏正在运行——退出前开关只读。"),
+    ("InstancesModsOldBadge", "legacy file", "旧版本残留"),
+    ("InstancesModsSkipped", "{count} entries skipped", "跳过 {count} 项"),
+    ("InstancesModsFailed", "Could not read mods/: {reason}", "读取 mods/ 失败：{reason}"),
+    ("InstancesModsToggleFailed", "Could not toggle {file}: {reason}", "启停 {file} 失败：{reason}"),
+    ("InstancesModsReasonRunning", "the game is running", "游戏正在运行"),
+    ("InstancesModsReasonInstance", "the instance is gone", "实例已不存在"),
+    ("InstancesModsReasonName", "the file name is not usable", "文件名不可用"),
+    ("InstancesModsReasonDirectory", "there is no usable mods/ directory", "没有可用的 mods/ 目录"),
+    ("InstancesModsReasonMissing", "the file is gone", "文件已不在"),
+    ("InstancesModsReasonNotFile", "that is not a regular file", "那不是普通文件"),
+    ("InstancesModsReasonCollision", "a file with that name already exists", "同名文件已存在"),
+    ("InstancesModsReasonRename", "the rename failed", "改名失败"),
+    ("InstancesSavesTitle", "SAVES", "存档"),
+    ("InstancesSavesCount", "{worlds} worlds · {shots} screenshots", "{worlds} 个世界 · {shots} 张截图"),
+    ("InstancesSavesLoading", "Reading saves/…", "正在读取 saves/…"),
+    ("InstancesSavesEmpty", "No worlds or screenshots yet — play once and they show up here.", "还没有世界或截图——玩一次就会出现在这里。"),
+    ("InstancesSavesMissingDir", "This instance has no saves/ or screenshots/ directory yet.", "这个实例还没有 saves/ 或 screenshots/ 目录。"),
+    ("InstancesSavesWorlds", "WORLDS", "世界"),
+    ("InstancesSavesScreenshots", "SCREENSHOTS", "截图"),
+    ("InstancesSavesNoWorlds", "No worlds yet.", "还没有世界。"),
+    ("InstancesSavesNoScreenshots", "No screenshots yet.", "还没有截图。"),
+    ("InstancesSavesWorldIcon", "has icon", "有图标"),
+    ("InstancesSavesTimeUnknown", "time unknown", "时间未知"),
+    ("InstancesSavesSkipped", "{count} entries skipped", "跳过 {count} 项"),
+    ("InstancesSavesOpenFolder", "Open saves folder", "打开存档文件夹"),
+    ("InstancesSavesRetry", "Retry", "重试"),
+    ("InstancesSavesFailed", "Could not read saves/: {reason}", "读取 saves/ 失败：{reason}"),
+    ("InstancesSavesOpenFailed", "Could not open the folder: {reason}", "打开文件夹失败：{reason}"),
+    ("InstancesSavesReasonDir", "the directory is not usable", "目录不可用"),
+    ("InstancesSavesReasonInstance", "the instance is gone", "实例已不存在"),
+    ("InstancesSavesReasonOpen", "the file manager did not start", "文件管理器没起来"),
+    ("InstancesSavesRename", "Rename", "重命名"),
+    ("InstancesSavesBackup", "Back up", "备份"),
+    ("InstancesSavesDelete", "Delete", "删除"),
+    ("InstancesSavesRenamePlaceholder", "New name for this world", "这个世界的新名字"),
+    ("InstancesSavesRenameConfirm", "Rename", "改名"),
+    ("InstancesSavesCancel", "Cancel", "取消"),
+    ("InstancesSavesBusy", "Working…", "正在处理…"),
+    ("InstancesSavesDeleteTitle", "Delete this world?", "删除这个世界？"),
+    ("InstancesSavesDeleteBody", "{dir} and everything inside it will be deleted. This cannot be undone.", "{dir} 和它里面的全部内容都会被删除，且不能撤销。"),
+    ("InstancesSavesDeleteConfirm", "Delete world", "删除世界"),
+    ("InstancesSavesRenamed", "Renamed {from} → {to}.", "已把 {from} 改名为 {to}。"),
+    ("InstancesSavesDeleted", "Deleted {dir}.", "已删除 {dir}。"),
+    ("InstancesSavesBackedUp", "Backed up {dir} to {path} ({size}).", "已把 {dir} 备份到 {path}（{size}）。"),
+    ("InstancesSavesBackupSkipped", "{count} symlinks skipped", "跳过 {count} 个符号链接"),
+    ("InstancesSavesRenameFailed", "Could not rename {file}: {reason}", "重命名 {file} 失败：{reason}"),
+    ("InstancesSavesDeleteFailed", "Could not delete {file}: {reason}", "删除 {file} 失败：{reason}"),
+    ("InstancesSavesBackupFailed", "Could not back up {file}: {reason}", "备份 {file} 失败：{reason}"),
+    ("InstancesSavesReasonUnsafeName", "the name is not usable", "名字不可用"),
+    ("InstancesSavesReasonSymlink", "that path is a symbolic link (not followed)", "那个路径是符号链接（不跟随）"),
+    ("InstancesSavesReasonMissing", "the world is gone", "那个世界已不在"),
+    ("InstancesSavesReasonNotDir", "that is not a directory", "那不是目录"),
+    ("InstancesSavesReasonConflict", "a world with that name already exists", "同名世界已存在"),
+    ("InstancesSavesReasonBoundary", "that path is outside saves/", "那个路径落在 saves/ 之外"),
+    ("InstancesSavesReasonTooLarge", "the world is too large for one zip", "这个世界太大，一个 zip 装不下"),
+    ("InstancesSavesReasonWrite", "the write failed", "写盘失败"),
+    ("InstancesSavesReasonRunning", "the game is running (exit it first)", "游戏正在运行（先退出再操作）"),
+    ("InstancesSavesPreviewNone", "no preview", "未生成预览"),
+    ("InstancesSavesPreviewTooLarge", "too large for a preview (over 8 MiB)", "文件过大，未生成预览（超过 8 MiB）"),
+    ("InstancesSavesPreviewUnreadable", "the file could not be read", "读不出这张图"),
+    ("InstancesSavesPreviewDecode", "not a decodable image", "解不出这张图（可能已损坏或格式不支持）"),
+];
+
+/// 金表的**全量**行（本文件 → [`tail`] → [`tail_ai`] → [`tail2`]，顺序即 `Key::ALL`）。
+///
+/// 拆成四段只为守 400 行硬线（M157/M159/M197 往金表追加文案后越线）；对调用方是**一条**序列，
+/// `catalog/tests.rs` 的逐字节断言不用关心分段。
+///
+/// ⚠️ 加段时**必须**在这里也 chain 上：条数与内容都只能从这一条序列导出（见 [`len`]）。
+pub(super) fn rows() -> impl Iterator {
+    GOLDEN
+        .iter()
+        .chain(tail::ROWS.iter())
+        .chain(tail_ai::ROWS.iter())
+        .chain(tail2::ROWS.iter())
+}
+
+/// 金表总行数（`Key::ALL` 的条数）。
+///
+/// **定义成 `rows().count()`，不是各段 `len()` 相加**：r3 复审实测过一条假绿——把
+/// [`rows`] 里的 `chain(tail2::ROWS)` 删掉，`catalog/tests.rs` 仍全绿，因为条数来自一处手工
+/// 聚合（仍有 tail2）而内容只遍历 `rows()`（少了 tail2），于是 213/459 行无人看守。
+/// 现在条数与内容同源：漏挂一段 ⇒ 条数当场对不上 ⇒ 用例必红。
+pub(super) fn len() -> usize {
+    rows().count()
+}
+
+mod tail;
+mod tail2;
+mod tail_ai;
diff --git a/crates/i18n/src/catalog/golden/tail.rs b/crates/i18n/src/catalog/golden/tail.rs
new file mode 100644
index 0000000..0557508
--- /dev/null
+++ b/crates/i18n/src/catalog/golden/tail.rs
@@ -0,0 +1,214 @@
+//! 金表的**后半段的前半截**（`InstancesLaunchReset` 之后、到 M197 的 Java 域结束）。
+//!
+//! 为什么拆：`golden.rs` 在 M157 加了 19 行启动参数文案后到 416 行，越过 400 行硬线；
+//! 拆分口径与仓库其它 `-p1/-p2` 一致——**纯搬移、一行不改**，顺序即 `Key::ALL` 的后半段。
+//! 拼装与断言在 `golden.rs` 的 [`rows`] 与 `catalog/tests.rs`。
+//!
+//! **M197 起本段只到 Java 域结束**：M197 往 `settings_java_entries` 追加了 68 行，加上 dev 侧
+//! 其它 mission 后加的行会涨到 470+（越过 400 行硬线），于是把 **M174 助手域起的那半截**
+//! 纯搬移到 [`super::tail_ai`]（链序：`golden` → `tail` → `tail_ai` → `tail2`）。
+//! 搬移只改位置：其余每一行逐字节原样（含其它 mission 后加的行）。
+pub(super) const ROWS: &[(&str, &str, &str)] = &[
+    ("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}"),
+    ("LaunchStageVersionManifest", "Reading the version file", "读版本文件"),
+    ("LaunchStageInheritance", "Resolving the inheritance chain", "解析继承链"),
+    ("LaunchStageInstanceConfig", "Reading the instance settings", "读实例设置"),
+    ("LaunchStageIsolation", "Preparing the isolated game folder", "准备隔离游戏目录"),
+    ("LaunchStageIdentity", "Preparing the account", "准备账户"),
+    ("LaunchStageSpawn", "Starting the game process", "启动游戏进程"),
+    ("LaunchStageFailed", "Launch failed · {stage}: {detail}", "启动失败 · {stage}：{detail}"),
+    ("LaunchToastEnded", "{outcome} · {seconds}s", "{outcome} · {seconds} 秒"),
+    ("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=, or set that environment variable before launching.", "微软登录未配置：缺少 Azure 公共客户端 id（登录功能已实现，只差这一项配置）。构建时注入：ULL_MSA_CLIENT_ID= cargo build；或启动前设置同名环境变量 ULL_MSA_CLIENT_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.", "切换界面语言。显示中文需要中文字体。"),
+    ("SettingsLogsFolder", "Log folder", "日志文件夹"),
+    ("SettingsLogsFolderHint", "What explains a crash lives here: the launcher's own runtime log (launcher.log, rolled over at 1 MiB with one old copy kept) and one jsonl per game session under logs/game/. Sessions from older versions (data/agent/sessions) are still read, not moved.", "解释一次崩溃要看的东西都在这：启动器自己的运行日志（launcher.log，满 1 MiB 滚动一次、只留一份旧档）与每次游戏会话的 jsonl（logs/game/）。旧版本留下的会话（data/agent/sessions）仍然读得出来，不会被搬动。"),
+    ("SettingsLogsCopy", "Copy path", "复制路径"),
+    ("SettingsLogsUnknown", "Data directory not resolved — restart the launcher from its own folder", "数据根没解析出来——从启动器所在目录重新启动试试"),
+    ("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% 圆角即恢复。"),
+    // M180：外观分组补齐（`catalog/settings/appearance.rs` 的第二批，M116 圆角那 5 条之后）。
+    // 位置就是装配链里那个域的位置——`settings_appearance_entries` 在 `settings_java_entries` 之前，
+    // 所以这 40 行必须落在 `SettingsAppearanceCornerSuspended` 与 `SettingsJavaScan` 之间
+    // （顺序 = `Key::ALL`；为排到文件尾而重排别人的族会让 `split_keeps_every_translation` 整片红）。
+    ("SettingsAppearanceWindowOpacity", "Window transparency", "整窗透明度"),
+    ("SettingsAppearanceWindowOpacityHint", "Applies to the whole window. Floor {floor}; 1.00 = fully opaque.", "作用于整个窗口。下限 {floor}；1.00 = 完全不透明。"),
+    ("SettingsAppearancePanelOpacity", "Panel transparency", "面板透明度"),
+    ("SettingsAppearancePanelOpacityHint", "Only the panel/card layer. Floor {floor}; independent of window transparency.", "只作用于面板 / 卡片这一层。下限 {floor}；与整窗透明度互不影响。"),
+    ("SettingsAppearancePanelOpacityForcedValue", "100% (forced from {requested})", "100%（强制，原请求值 {requested}）"),
+    ("SettingsAppearancePanelOpacityForcedHint", "Software renderer: panels and glass stay fully opaque (window transparency still works).", "软件渲染：面板与玻璃效果恒为不透明（整窗透明度仍然有效）。"),
+    ("SettingsAppearanceBackgroundImage", "Background image", "背景图"),
+    ("SettingsAppearanceOff", "Off", "关"),
+    ("SettingsAppearanceOn", "On", "开"),
+    ("SettingsAppearanceImagePath", "Image path", "图片路径"),
+    ("SettingsAppearancePaletteLevel", "Colours: {level}", "配色：{level}"),
+    ("SettingsAppearanceBgFill", "Fill", "填充方式"),
+    ("SettingsAppearanceBgFillCover", "Cover", "铺满"),
+    ("SettingsAppearanceBgFillContain", "Contain", "完整显示"),
+    ("SettingsAppearanceBgFillTile", "Tile", "平铺"),
+    ("SettingsAppearanceBgDim", "Dim", "暗化"),
+    ("SettingsAppearanceBgDimHint", "Blends the image toward the panel colour so text stays readable. Max {max}.", "把背景图往面板底色上退，让文字读得清。上限 {max}。"),
+    ("SettingsAppearancePaletteSource", "Colour source", "配色来源"),
+    ("SettingsAppearancePaletteBackground", "Background", "取自背景图"),
+    ("SettingsAppearancePaletteWallpaper", "Wallpaper", "取自壁纸"),
+    ("SettingsAppearancePalettePreset", "Preset", "内置色卡"),
+    ("SettingsAppearanceBgReadFailed", "Background image could not be read: {reason}", "背景图读不出来：{reason}"),
+    ("SettingsAppearanceBgDecodeFailed", "Background image could not be decoded ({reason}; this build decodes PNG, JPEG and BMP)", "背景图解不开（{reason}；这个构建只支持 PNG、JPEG 与 BMP）"),
+    ("SettingsAppearanceBgTooLarge", "Background image is too large to decode: {width}×{height} (limit {limit} px per edge)", "背景图太大，解不开：{width}×{height}（每边上限 {limit} 像素）"),
+    ("SettingsAppearanceBgSmallTile", "Small image ({width}×{height}): tiles are scaled up so the window stays covered (max {max} tiles, no gaps).", "图片很小（{width}×{height}）：图块会被放大，保证窗口铺满（最多 {max} 块，不留缝）。"),
+    ("SettingsAppearancePaletteBgUndecodable", "Background image could not be read; colours fall back.", "背景图读不出来，配色回落到下一级。"),
+    ("SettingsAppearancePaletteBgTooSmall", "Background image is too small to sample; colours fall back.", "背景图太小，取不了色，配色回落到下一级。"),
+    ("SettingsAppearancePaletteBgBadDimensions", "Background image data looks inconsistent; colours fall back.", "背景图数据前后不一致，配色回落到下一级。"),
+    ("SettingsAppearancePaletteBgNoOpaquePixels", "Background image is almost fully transparent; colours fall back.", "背景图几乎全透明，配色回落到下一级。"),
+    ("SettingsAppearancePaletteBgLowChroma", "Background image is too monochrome to tint from; colours fall back.", "背景图太单调（彩度不足），取不出配色，回落到下一级。"),
+    ("SettingsAppearancePaletteBgContrast", "Background image colours would be unreadable; colours fall back.", "按背景图取的颜色读不清，配色回落到下一级。"),
+    ("SettingsAppearancePaletteWallpaperUndecodable", "Desktop wallpaper could not be read.", "桌面壁纸读不出来。"),
+    ("SettingsAppearancePaletteWallpaperTooSmall", "Desktop wallpaper is too small to sample.", "桌面壁纸太小，取不了色。"),
+    ("SettingsAppearancePaletteWallpaperBadDimensions", "Desktop wallpaper data looks inconsistent.", "桌面壁纸数据前后不一致。"),
+    ("SettingsAppearancePaletteWallpaperNoOpaquePixels", "Desktop wallpaper is almost fully transparent.", "桌面壁纸几乎全透明。"),
+    ("SettingsAppearancePaletteWallpaperLowChroma", "Desktop wallpaper is too monochrome to tint from.", "桌面壁纸太单调（彩度不足），取不出配色。"),
+    ("SettingsAppearancePaletteWallpaperContrast", "Desktop wallpaper colours would be unreadable; colours fall back.", "按桌面壁纸取的颜色读不清，配色回落到下一级。"),
+    ("SettingsAppearancePalettePresetContrast", "The built-in card needed a small contrast correction.", "内置色卡做了一点对比度修正。"),
+    ("SettingsAppearancePaletteAdjusted", "A few colours were nudged for readability.", "有几个颜色为了可读性做了微调。"),
+    // M175：设置页「Java」分组（`catalog/settings/java.rs` 的 `settings_java_entries`）。
+    // 位置就是装配链里那个域的位置：`settings_java_entries` 在 `settings_appearance_entries` 之后、
+    // `settings_download_entries`（空）与 `settings_ai_entries`（M174）之前，所以这几行必须落在
+    // `SettingsAppearanceCornerSuspended` 与 `SettingsGroupAssistant` 之间（顺序 = `Key::ALL`）。
+    ("SettingsJavaScan", "Scan now", "立即扫描"),
+    ("SettingsJavaScanningStart", "Scanning…", "正在扫描…"),
+    ("SettingsJavaScanning", "Scanning… {done}/{total}", "正在扫描… {done}/{total}"),
+    ("SettingsJavaCancelling", "Cancelling…", "正在取消…"),
+    ("SettingsJavaCancel", "Cancel", "取消"),
+    ("SettingsJavaCancelled", "The scan was cancelled; the list below is from the previous run.", "扫描已取消；下面的列表还是上一次的结果。"),
+    ("SettingsJavaScanDone", "{count} JDK found", "找到 {count} 个 JDK"),
+    ("SettingsJavaNeverScanned", "Not scanned yet", "还没扫描过"),
+    ("SettingsJavaNeverScannedBody", "The list is still empty. The launcher scans once by itself when the settings page opens; press Scan now to look again right away.", "列表还是空的。打开设置页时启动器会自己扫一次；也可以点「立即扫描」立刻再扫一遍。"),
+    ("SettingsJavaEmptyTitle", "No Java runtime found", "未检测到 Java 运行时"),
+    ("SettingsJavaEmptyBody", "Nothing matched. Add the path of a JDK you already unpacked below, or install one with ull java install 21 on the command line.", "没找到任何 JDK。可以在下面手动加上你自己解压的那份，或者用命令行 ull java install 21 装一个。"),
+    ("SettingsJavaDefault", "Default", "默认"),
+    ("SettingsJavaSetDefault", "Use as default", "设为默认"),
+    ("SettingsJavaFits", "Meets the current instance requirement", "满足当前实例的要求"),
+    ("SettingsJavaTooOld", "Below the requirement: this instance needs Java {minimum}+", "低于要求：当前实例需要 Java {minimum} 及以上"),
+    ("SettingsJavaDefaultSet", "Default JDK is now {path}", "默认 JDK 已设为 {path}"),
+    ("SettingsJavaSourceManaged", "installed by this launcher", "本启动器安装"),
+    ("SettingsJavaSourceEnv", "JAVA_HOME (environment variable)", "JAVA_HOME（环境变量）"),
+    ("SettingsJavaSourcePath", "on PATH", "PATH 上"),
+    ("SettingsJavaSourceSystem", "system install", "系统安装"),
+    ("SettingsJavaSourceManual", "added by you", "手动添加"),
+    ("SettingsJavaAdd", "Add a JDK path", "手动添加 JDK 路径"),
+    ("SettingsJavaAddPlaceholder", "C:\\Program Files\\Java\\jdk-21", "例：C:\\Program Files\\Java\\jdk-21"),
+    ("SettingsJavaAddHint", "A JDK folder or its java executable. We run java -version on it; anything that cannot answer is refused.", "JDK 目录或它的 java 可执行文件。会真跑一次 java -version；答不出话的一律拒绝。"),
+    ("SettingsJavaAddAction", "Add", "添加"),
+    ("SettingsJavaAdded", "Added {path}", "已添加 {path}"),
+    ("SettingsJavaMemory", "Default memory (MB)", "默认内存（MB）"),
+    ("SettingsJavaMemoryHint", "Whole megabytes, {min}–{max}. Instances without their own override follow this value.", "整数 MB，范围 {min}~{max}。没有实例级覆盖的实例都用它。"),
+    ("SettingsJavaLayerGlobal", "In effect: {mb} MB, from the global default.", "生效：{mb} MB，来自全局默认值。"),
+    ("SettingsJavaLayerInstance", "In effect: {mb} MB, set by instance {instance}. Changing the global value below will not affect that instance.", "生效：{mb} MB，由实例 {instance} 覆盖。改下面的全局值不会影响它。"),
+    ("SettingsJavaJvm", "Extra JVM arguments", "额外 JVM 参数"),
+    ("SettingsJavaJvmPlaceholder", "-XX:+UseG1GC -Dfile.encoding=UTF-8", "例：-XX:+UseG1GC -Dfile.encoding=UTF-8"),
+    ("SettingsJavaJvmHint", "Separated by spaces, quotes allowed. Appended to the command line of every launch; an instance's own JVM arguments come after it.", "按空白分隔，支持引号。会拼到每次启动的命令行上；实例自己的 JVM 参数排在它后面。"),
+    ("SettingsJavaJvmSaved", "Saved value: {value}", "已保存的值：{value}"),
+    ("SettingsJavaJvmSavedNone", "No extra JVM arguments are saved yet.", "还没有保存任何额外参数。"),
+    ("SettingsJavaSave", "Save", "保存"),
+    ("SettingsJavaSaved", "Saved and read back from disk. The next launch uses the new value.", "已保存，并从磁盘读回确认。下次启动就用新值。"),
+    ("SettingsJavaUnsaved", "There are unsaved changes.", "有未保存的改动。"),
+    ("SettingsJavaRefused", "Not saved: {reason}", "未保存：{reason}"),
+    ("SettingsJavaSkipNotDirty", "there was nothing to change, so no file was written", "没有任何改动，因此没有写文件"),
+    ("SettingsJavaSkipReadOnly", "the settings file is read-only: a newer launcher wrote it, or it is marked untrusted", "配置文件只读：它被更新版本的启动器写过，或被标记为不可信"),
+    ("SettingsJavaSkipUnreadable", "the settings file is untrusted, so it is treated as read-only", "配置文件不可信，因此按只读处理"),
+    ("SettingsJavaNoStorage", "No settings file is available in this run, so nothing can be scanned or saved.", "这一次运行没有可用的设置文件，扫描与保存都做不了。"),
+    ("SettingsJavaReasonMemoryEmpty", "the memory field is empty", "内存没填"),
+    ("SettingsJavaReasonMemoryNotNumber", "the memory must be a whole number of MB", "内存必须是整数 MB"),
+    ("SettingsJavaReasonMemoryRange", "the memory is outside the allowed range", "内存超出允许范围"),
+    ("SettingsJavaReasonJvmQuotes", "the JVM arguments have an unclosed quote", "JVM 参数里有没配对的引号"),
+    ("SettingsJavaReasonJvmTooLong", "the JVM arguments are longer than the settings file allows (1024 characters)", "JVM 参数超过配置文件允许的长度（1024 字符）"),
+    ("SettingsJavaReasonAddEmpty", "the path is empty", "路径是空的"),
+    ("SettingsJavaReasonAddMissing", "nothing exists at that path", "那个路径上什么都没有"),
+    ("SettingsJavaReasonAddNotJava", "there is no java executable at that path", "那个路径里没有 java 可执行文件"),
+    ("SettingsJavaReasonAddNoVersion", "java -version did not answer there, so it is not a usable JDK", "在那里跑不出 java -version，不是一份能用的 JDK"),
+    ("SettingsJavaReasonAddTooLong", "the path is too long to be a JDK location", "路径太长，不像是一个 JDK 位置"),
+    ("SettingsJavaReasonAddWriteFailed", "the JDK is fine, but the list file could not be written (disk or permission)", "这份 JDK 没问题，但名单文件写不进去（磁盘或权限）"),
+    ("SettingsJavaReasonAddDuplicate", "that JDK is already in the list", "这份 JDK 已经在列表里了"),
+    ("SettingsJavaReasonWriteFailed", "the settings file could not be written (disk full, no permission, or the value was rejected)", "设置写不进去（磁盘满、没权限，或这个值被拒绝）"),
+    ("SettingsJavaTooNew", "Above the requirement: this instance can only use Java {maximum} or older (the old loader cannot read newer class files)", "高于要求：当前实例只能用 Java {maximum} 及以下（老加载器吃不了新 class 文件）"),
+    // M197：Java 分组的「下载一个 JDK」与三个设置键（`catalog/settings/java.rs` 里同一批追加）。
+    ("SettingsJavaDownloadTitle", "Download a JDK", "下载一个 JDK"),
+    ("SettingsJavaDownloadHint", "Downloads go through the built-in mirror table: in China the campus mirrors are tried first (Temurin over Tsinghua TUNA), and GitHub-hosted archives are fetched through gh-proxy. Every archive is verified against its SHA-256 before it is unpacked.", "下载走内置镜像表：国内先试院校镜像（Temurin 走清华 TUNA），GitHub 上的归档套 gh-proxy。落盘前一律按 SHA-256 校验。"),
+    ("SettingsJavaDownloadLts", "LTS", "长期支持版（LTS）"),
+    ("SettingsJavaDownloadBaseline", "Recommended baseline", "推荐基准版本"),
+    ("SettingsJavaDownloadVendors", "Vendors: {vendors}", "发行版：{vendors}"),
+    ("SettingsJavaDownloadNoVendor", "No vendor publishes this major version on this platform.", "这个平台上没有发行版发这个大版本。"),
+    ("SettingsJavaDownloadAction", "Install", "安装"),
+    ("SettingsJavaDownloadReinstall", "Install again", "重装"),
+    ("SettingsJavaDownloadInstalled", "Already installed: {path}", "已安装：{path}"),
+    ("SettingsJavaDownloadNeeded", "The current instance needs {requirement}.", "当前实例需要 {requirement}。"),
+    ("SettingsJavaDownloadFits", "Usable by the current instance", "当前实例可用"),
+    ("SettingsJavaDownloadTooLow", "The current instance needs Java {minimum} or newer, so installing this one will not start it.", "当前实例需要 Java {minimum} 及以上 —— 装这一档也起不来。"),
+    ("SettingsJavaDownloadTooHigh", "The current instance can only use Java {maximum} or older, so installing this one will not start it.", "当前实例只能用 Java {maximum} 及以下 —— 装这一档也起不来。"),
+    ("SettingsJavaDownloadRecommended", "Recommended for the current instance", "为当前实例推荐这一档"),
+    ("SettingsJavaDownloadBusy", "Installing Java {major}…", "正在安装 Java {major}…"),
+    ("SettingsJavaDownloadPhasePreparing", "Looking up the release…", "正在查版本…"),
+    ("SettingsJavaDownloadPhaseDownloading", "Downloading {percent}% ({done} of {total})", "下载中 {percent}%（{done} / {total}）"),
+    ("SettingsJavaDownloadPhaseVerifying", "Verifying the archive…", "正在校验归档…"),
+    ("SettingsJavaDownloadPhaseExtracting", "Unpacking…", "正在解压…"),
+    ("SettingsJavaDownloadSource", "Source: {source}", "来源：{source}"),
+    ("SettingsJavaDownloadRetry", "{source} failed ({reason}); retry {attempt} in {seconds}s", "{source} 失败（{reason}）；{seconds} 秒后重试第 {attempt} 次"),
+    ("SettingsJavaDownloadSwitch", "Switching source: {from} → {to}", "换源：{from} → {to}"),
+    ("SettingsJavaDownloadDone", "Java {major} ({vendor}) is ready at {root} · source {source}", "Java {major}（{vendor}）已就绪：{root} · 来源 {source}"),
+    ("SettingsJavaDownloadDoneReused", "Java {major} ({vendor}) was already installed at {root}; nothing was downloaded.", "Java {major}（{vendor}）之前已经装好：{root}，这一次没有下载。"),
+    ("SettingsJavaDownloadFailed", "Java {major} could not be installed; the last source tried was {source}. The full reason is in the log.", "Java {major} 没装成；最后试到的源是 {source}。完整原因在日志里。"),
+    ("SettingsJavaDownloadFailedNoSource", "Java {major} could not be installed: the version lookup itself failed. The full reason is in the log.", "Java {major} 没装成：查版本这一步就失败了。完整原因在日志里。"),
+    ("SettingsJavaDownloadFailedHint", "Check the network, or change the vendor order below.", "先查网络，或者改下面的发行版顺序。"),
+    ("SettingsJavaDownloadTriedHeader", "Sources tried:", "试过的源："),
+    ("SettingsJavaDownloadTried", "{source}: {reason}", "{source}：{reason}"),
+    ("SettingsJavaDownloadRefused", "Not started: {reason}", "没开始：{reason}"),
+    ("SettingsJavaReasonDownloadBusy", "another JDK install is already running", "已经有一个 JDK 在装了"),
+    ("SettingsJavaReasonDownloadUnknownMajor", "that major version is not in the catalog", "目录里没有这个大版本"),
+    ("SettingsJavaReasonDownloadNoVendor", "no vendor publishes that major version here", "没有发行版在这里发这个大版本"),
+    ("SettingsJavaReasonRootUnresolved", "the JDK install folder cannot be resolved on this system", "这台机器上解析不出 JDK 安装目录"),
+    ("SettingsJavaSourceReasonNotFound", "this mirror does not have that file (404)", "这个镜像没有这个文件（404）"),
+    ("SettingsJavaSourceReasonServer", "the server answered with a 5xx / 429 error", "服务器报错 5xx / 429"),
+    ("SettingsJavaSourceReasonTimeout", "the request timed out", "请求超时"),
+    ("SettingsJavaSourceReasonNetwork", "the connection failed", "连不上"),
+    ("SettingsJavaSourceReasonIntegrity", "the checksum did not match", "校验不符"),
+    ("SettingsJavaSourceReasonIo", "a local disk error", "本地磁盘错误"),
+    ("SettingsJavaSourceReasonOther", "the request was rejected", "请求被拒"),
+    ("SettingsJavaInstallRoot", "JDK install folder", "JDK 安装目录"),
+    ("SettingsJavaInstallRootPlaceholder", "D:\\Java", "例：D:\\Java"),
+    ("SettingsJavaInstallRootHint", "Leave it empty to follow the data mode: portable keeps JDKs inside the launcher folder, standard uses the system Java folder. A path here overrides both, and JDKs land in ///.", "留空 = 跟数据目录模式走：portable 放在启动器目录里，standard 放在系统 Java 目录。填了它覆盖前两者，JDK 落在 /<发行方>/<版本>/。"),
+    ("SettingsJavaInstallRootEffective", "In effect: {mode} · {path}", "生效：{mode} · {path}"),
+    ("SettingsJavaInstallRootLayerSetting", "this comes from java.installRoot", "这一项来自 java.installRoot"),
+    ("SettingsJavaInstallRootLayerDataMode", "this comes from core.data_mode ({mode})", "这一项来自 core.data_mode（{mode}）"),
+    ("SettingsJavaInstallRootUnresolved", "The system Java folder cannot be resolved here. Type a folder above, or set core.data_mode back to portable.", "这台机器上解析不出系统标准 Java 目录。在上面填一个目录，或把 core.data_mode 改回 portable。"),
+    ("SettingsJavaVendorPriority", "Vendor order", "发行版顺序"),
+    ("SettingsJavaVendorOrderEffective", "In effect: {order}", "生效顺序：{order}"),
+    ("SettingsJavaVendorOrderLayerSetting", "this comes from java.vendorPriority", "这一项来自 java.vendorPriority"),
+    ("SettingsJavaVendorOrderLayerRegion", "this comes from the built-in order for your region ({region})", "这一项来自内置的地区默认序（{region}）"),
+    ("SettingsJavaRegionDomestic", "China", "国内"),
+    ("SettingsJavaRegionGlobal", "rest of the world", "国外"),
+    ("SettingsJavaVendorUp", "Up", "上移"),
+    ("SettingsJavaVendorDown", "Down", "下移"),
+    ("SettingsJavaVendorReset", "Reset to the region default", "恢复地区默认序"),
+    ("SettingsJavaVendorSupports", "ships {majors}", "发 {majors}"),
+    ("SettingsJavaAutoInstall", "Recommend a JDK when none is found", "缺 JDK 时推荐一档"),
+    ("SettingsJavaAutoInstallHint", "On: the catalog below marks the version the current instance needs, and a freshly installed JDK becomes the default when no default is set yet. Nothing is downloaded on its own — you press Install. Off: nothing is marked and you pick everything yourself.", "开：下面的目录会按当前实例的要求标出该装哪一档，装完之后若还没有默认 JDK 就自动设为默认。不会自己开始下载 —— 点「安装」才会下。关：什么也不标，全部自己挑。"),
+    ("SettingsJavaAutoInstallOn", "on", "开"),
+    ("SettingsJavaAutoInstallOff", "off", "关"),
+    ("SettingsJavaPrefsSave", "Save", "保存"),
+    ("SettingsJavaPrefsSaved", "Saved and read back from disk: all three keys are in the settings file.", "已保存并从磁盘读回：三个键都进配置文件了。"),
+    ("SettingsJavaPrefsUnsaved", "There are unsaved changes in this section.", "这一段有未保存的改动。"),
+    ("SettingsJavaReasonInstallRootTooLong", "the folder path is too long", "目录路径太长"),
+    // M201：设置页 Downloads 组的文本行提交按钮（装配链里本域紧随 `settings_java_entries`）。
+    ("SettingsDownloadsApply", "Apply", "应用"),
+];
diff --git a/crates/i18n/src/catalog/golden/tail2.rs b/crates/i18n/src/catalog/golden/tail2.rs
new file mode 100644
index 0000000..1306bb6
--- /dev/null
+++ b/crates/i18n/src/catalog/golden/tail2.rs
@@ -0,0 +1,243 @@
+//! 金表的第三段（`tail.rs` 之后，M161 拆：`tail.rs` 到 M157 已有 411 行、加自更新那几条就 423）。
+//!
+//! 口径与 `golden.rs` / `tail.rs` 完全一致：**纯搬移、一行不改**，顺序即 `Key::ALL` 的续段。
+//! 拼装见 `golden.rs` 的 [`super::rows`]。
+
+pub(super) const ROWS: &[(&str, &str, &str)] = &[
+    ("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", "Cancel requested — the pipeline is stopping now; the real outcome follows.", "已请求取消 —— 后台正在停手，真实结果随后给出。"),
+    ("PackStatusCancelled", "Cancelled — rolled back", "已取消 —— 已回滚"),
+    ("PackCancelIncomplete", "Cancelled — rollback incomplete: the target directory may differ from before the import.", "已取消 —— 回滚没做完：目标目录可能与导入前不同。"),
+    ("PackCancelTooLate", "The cancel arrived too late: this import already finished. The instance is kept; same-name files may already be overwritten.", "取消来得太晚：这次导入已经跑完，实例会保留，同名文件可能已被覆盖。"),
+    ("PackOverwriteAction", "Re-import, the pack wins", "以包为准重新导入"),
+    ("PackOverwriteNote", "Keeping both (renamed) is not supported yet: for each existing file you pick either “keep” or “overwrite”.", "「两者都留（改名）」暂不支持：每个已存在的文件只能选「保留」或「覆盖」。"),
+    ("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", "三方哈希"),
+    ("PackPickTitle", "Before importing: {count} files already exist with different content", "导入前：有 {count} 个文件已存在且内容不同"),
+    ("PackPickSummary", "Keep {keep} · overwrite {overwrite} · overwriting discards {bytes}", "保留 {keep} · 覆盖 {overwrite} · 覆盖将丢弃 {bytes}"),
+    ("PackPickKeepAll", "Keep all mine", "全部保留我的"),
+    ("PackPickOverwriteAll", "Overwrite all", "全部覆盖"),
+    ("PackPickRowKeep", "Keep", "保留"),
+    ("PackPickRowOverwrite", "Overwrite", "覆盖"),
+    ("PackPickPage", "Items {from}-{to} of {total}", "第 {from}-{to} 项，共 {total} 项"),
+    ("PackPickPrev", "Previous", "上一页"),
+    ("PackPickNext", "Next", "下一页"),
+    ("PackPickConfirm", "Import with these choices", "按这些选择导入"),
+    ("PackPickCancel", "Cancel import", "取消导入"),
+    ("PackPickDefaultNote", "Anything you do not change stays as you have it: file content is only replaced where you pick “Overwrite”.", "没有改动的一律按「保留」：只有你点了「覆盖」的文件才会被包内内容替换。"),
+    ("PackPickUnknownRemote", "{count} remote entries only learn their path after download; they follow “keep”.", "还有 {count} 条远端条目要下载后才知道路径，一律按「保留」处置。"),
+    ("PackPickSourceOverrides", "in the pack (overrides/)", "包内 overrides/"),
+    ("PackPickSourceClientOverrides", "in the pack (client-overrides/)", "包内 client-overrides/"),
+    ("PackPickSourceManifest", "manifest files[]", "清单 files[]"),
+    ("PackPickDisk", "yours: {size}", "你的：{size}"),
+    ("PackPickIncoming", "pack: {size}", "包内：{size}"),
+    ("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", "读不出来，已跳过"),
+    ("PackStatusFailedNotStarted", "Import failed — nothing was written", "导入失败 —— 还没写任何文件"),
+    ("PackStatusFailedIncomplete", "Import failed — rollback did not finish", "导入失败 —— 回滚没做完"),
+    ("PackFatalTitleNotStarted", "Preflight failed — nothing was written", "预检未通过 —— 一个字节都没写"),
+    ("PackFatalTitleIncomplete", "Rollback did not finish — the target folder may differ", "回滚没做完 —— 目标目录可能与导入前不同"),
+    ("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", "用浏览器登录"),
+    ("AccountDeviceSignIn", "Sign in with your Microsoft account", "使用 Microsoft 账户登录"),
+    ("AccountDeviceFallbackHint", "No browser handy? This way shows a code you can type on any device.", "浏览器打不开就用这个：它会给一串用户码，在任何设备上输入即可。"),
+    ("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.", "登录失败，完整原因在启动器日志里。"),
+    ("AccountLoginNotConfigured", "Microsoft sign-in is not configured", "微软登录未配置"),
+    ("AccountFailureMsaNotConfigured", "This build has no Azure public client id, so Microsoft sign-in cannot start (the sign-in flow itself is implemented). Set the environment variable ULL_MSA_CLIENT_ID= before starting the launcher, or build with ULL_MSA_CLIENT_ID=. Then restart the launcher: a running process does not pick up a new environment variable.", "本启动器没有配置 Azure 公共客户端 id，微软登录无法开始（登录功能已实现，只差这一项配置）。启动前设置环境变量 ULL_MSA_CLIENT_ID=，或构建时注入：ULL_MSA_CLIENT_ID= cargo build。改完请重启启动器——已在运行的进程读不到新设的环境变量。"),
+    ("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.", "本地档案没有可重新登录的服务器账户，请新建一个档案。"),
+    ("AccountBrowserFallbackNotRegistered", "This build's app registration has no loopback redirect URI, so browser sign-in cannot work; switched to a device code. To fix: add http://localhost/auth under Redirect URIs in the Azure app registration (the port is ignored), then restart the launcher.", "这个构建的应用注册里没有登记回环重定向 URI，浏览器登录用不了，已自动改用设备码。怎么修：在 Azure 应用注册的「重定向 URI」里加上 http://localhost/auth（端口不参与匹配），然后重启启动器。"),
+    ("AccountBrowserFallbackUnverified", "Could not confirm that browser sign-in is usable, so it switched to a device code.", "没能确认浏览器登录是否可用（预检没成功），已自动改用设备码。"),
+    ("AccountBrowserFallbackFailed", "Browser sign-in did not finish, so it switched to a device code. If the browser page said the redirect URI is not valid, add http://localhost/auth under Redirect URIs of the app registration.", "浏览器登录没有完成，已自动改用设备码。如果浏览器里提示 redirect_uri 无效，请把 http://localhost/auth 加进应用注册的「重定向 URI」。"),
+    ("SettingsGroupUpdate", "Updates", "更新"),
+    ("SettingsUpdateCurrent", "Current version", "当前版本"),
+    ("SettingsUpdateChannel", "Channel", "更新渠道"),
+    ("SettingsUpdateChannelStable", "Stable", "稳定版"),
+    ("SettingsUpdateAutoCheck", "Check for updates on startup", "启动时检查更新"),
+    ("SettingsUpdateCheckNow", "Check now", "立即检查"),
+    ("SettingsUpdateChecking", "Checking…", "正在检查…"),
+    ("SettingsUpdateNever", "Not checked yet", "还没检查过"),
+    ("SettingsUpdateUpToDate", "You are on the latest version ({version})", "已是最新（{version}）"),
+    ("SettingsUpdateAvailable", "Version {version} is available ({size})", "有新版本 {version}（{size}）"),
+    ("SettingsUpdateMissingArtifact", "Version {version} is out, but there is no build for this platform yet.", "{version} 已发布，但还没有本平台的安装包。"),
+    ("SettingsUpdateFailed", "Check failed: {reason}", "检查失败：{reason}"),
+    ("SettingsUpdateApply", "Download and install", "下载并安装"),
+    ("SettingsUpdateApplying", "Downloading and verifying…", "正在下载并校验…"),
+    ("SettingsUpdateReady", "Version {version} is ready — restart to use it.", "版本 {version} 已就位，重启后生效。"),
+    ("SettingsUpdateNotes", "Release notes: {notes}", "更新说明：{notes}"),
+    ("SettingsUpdateForced", "This update is required", "这是一次强制更新"),
+    ("SettingsUpdateLastChecked", "Last check", "上次检查"),
+    ("SettingsUpdateHint", "Downloads are verified with SHA256 before they touch the launcher. The running copy stays as it is until you restart.", "更新包在落到启动器之前会做 SHA256 校验；正在运行的这一份在你重启之前不会变。"),
+    ("UpdateBannerTitleAvailable", "Version {version} is available", "发现新版本 {version}"),
+    ("UpdateBannerBodyAvailable", "Download size {size}", "下载体积 {size}"),
+    ("UpdateBannerTitleReady", "Update ready", "更新已就位"),
+    ("UpdateBannerBodyReady", "Version {version} will run after a restart.", "重启后运行版本 {version}。"),
+    ("UpdateBannerTitleFailed", "Update failed", "更新失败"),
+    ("UpdateBannerApplying", "Downloading the update…", "正在下载更新…"),
+    ("UpdateBannerInstall", "Download and install", "下载并安装"),
+    ("UpdateBannerDismiss", "Skip this version", "忽略这个版本"),
+    ("UpdateBannerRestartNow", "Restart now", "立即重启"),
+    ("UpdateBannerRetry", "Try again", "重试"),
+    // M168：中文字体下载状态行（链尾追加，既有顺序不动）
+    ("FontCjkStatusLabel", "Chinese font", "中文字体"),
+    ("FontCjkStatusNotNeeded", "Not needed for this interface language", "当前界面语言不需要中文字体"),
+    ("FontCjkStatusSystem", "Ready (system font: {family})", "已就绪（系统字体：{family}）"),
+    ("FontCjkStatusDownloading", "Fetching a Chinese font… ({size})", "正在获取中文字体…（{size}）"),
+    ("FontCjkStatusFailed", "Download failed ({reason}). The interface keeps working with system fonts; switch the language again to retry.", "获取失败（{reason}）。界面照常可用，用的是系统字体；再切一次语言可以重试。"),
+    ("FontCjkReasonNetwork", "network unreachable or too slow (timed out)", "网络不通或太慢（超时）"),
+    ("FontCjkReasonIntegrity", "the mirror sent content that failed verification", "镜像内容校验不通过"),
+    ("FontCjkReasonDisk", "cannot write to the data directory", "写不进数据目录"),
+    ("FontCjkStatusUnknown", "Not determined yet; nothing was downloaded", "尚未判定；没有下载任何字体"),
+    ("FontCjkStatusUnprobeable", "System fonts cannot be probed, so nothing was downloaded", "无法探测系统字体，因此没有下载"),
+    ("FontCjkStatusHint", "Downloaded once into the data directory and cached; the next start does not download it again. A mirror can be set with ui.font_cdn.", "只下这一次，缓存在数据目录里，下次启动不重下。镜像可用配置键 ui.font_cdn 指定。"),
+    ("SettingsAppearanceAccent", "Accent colour", "强调色"),
+    ("SettingsAppearanceAccentPresets", "Presets", "预设"),
+    ("SettingsAppearanceAccentFactory", "Factory", "出厂"),
+    ("SettingsAppearanceAccentHint", "Empty = the factory accent from the brand board. A custom accent replaces primary / secondary / tertiary only; neutral surfaces and error colours do not follow it.", "空 = 出厂品牌板的强调色。自定义强调色只替换 primary / secondary / tertiary 三族；中性表面与错误色不随强调色变。"),
+    ("SettingsAppearanceAccentShort", "Accent needs 6 hex digits (RRGGBB); got {digits}.", "强调色要 6 位十六进制（RRGGBB），现在 {digits} 位。"),
+    ("SettingsAppearanceAccentLong", "Accent has {digits} digits; a colour takes exactly 6.", "强调色有 {digits} 位，一个颜色只要 6 位。"),
+    ("SettingsAppearanceAccentDigit", "Accent contains a character that is not a hex digit: {ch}", "强调色里有非十六进制字符：{ch}"),
+];
diff --git a/crates/i18n/src/catalog/golden/tail_ai.rs b/crates/i18n/src/catalog/golden/tail_ai.rs
new file mode 100644
index 0000000..93ad7f8
--- /dev/null
+++ b/crates/i18n/src/catalog/golden/tail_ai.rs
@@ -0,0 +1,282 @@
+//! 金表的**第四段**（旧 `tail.rs` 从 M174 的助手域起的那一半；M197 拆出）。
+//!
+//! 为什么拆：`tail.rs` 在 M197 加了「下载一个 JDK / 三个设置键」这 70 多条文案后到 400+ 行
+//! （`guards.yml` 的 `file-size` 会红）。拆分口径与仓库其它 `-p1/-p2` / `tail2` 一致：
+//! **纯搬移、一行不改**，顺序即 `Key::ALL` 的续段——本段从 M174 的助手域开始，
+//! 一路到旧 `tail.rs` 末尾（后面还跟着 core_text / download / logs / agent / version /
+//! content / pack 各行，它们本来就在这个位置）。
+//!
+//! 拼装见 [`super::super::golden::rows`]（链序：`golden` → `tail` → 本段 → `tail2`）。
+//!
+//! 正文是 **dev 侧 `tail.rs` 从 M174 助手域起** 的全部行（含其它 mission 后加的行），
+//! 逐字节原样搬来；本段只负责把它们放到 `Key::ALL` 的同一位置。
+pub(super) const ROWS: &[(&str, &str, &str)] = &[
+    // M174：设置页「助手（AI）」分组（`catalog/settings/ai.rs` 的 `settings_ai_entries`）。
+    // 位置就是装配链里那个域的位置：`settings_ai_entries` 在 `settings_download_entries` 之后、
+    // `core_text_entries` 之前，所以这几行必须落在 `SettingsAppearanceCornerSuspended` 与
+    // `CoreTextUntranslated` 之间（顺序 = `Key::ALL`）。
+    ("SettingsGroupAssistant", "Assistant", "助手"),
+    ("SettingsAiStatusLabel", "Status: {status}", "状态：{status}"),
+    ("SettingsAiStatusUnconfigured", "not configured", "未配置"),
+    ("SettingsAiStatusConfigured", "configured", "已配置"),
+    ("SettingsAiStatusVerified", "verified", "连接已通过"),
+    ("SettingsAiStatusTestFailed", "test failed", "测试失败"),
+    ("SettingsAiEnable", "Enable the assistant", "启用助手"),
+    ("SettingsAiEnableHint", "With this off, the assistant stays quiet; crash diagnosis from the rule engine keeps working.", "关掉之后助手不再工作；规则引擎的崩溃诊断照常可用。"),
+    ("SettingsAiProviderLabel", "Provider", "提供商"),
+    ("SettingsAiProviderOpenAi", "OpenAI compatible", "OpenAI 兼容"),
+    ("SettingsAiProviderAnthropic", "Anthropic", "Anthropic 原生"),
+    ("SettingsAiProviderOllama", "Ollama", "Ollama 原生"),
+    ("SettingsAiProviderDisabled", "Disabled", "已禁用"),
+    ("SettingsAiBaseUrl", "Endpoint (base_url)", "端点（base_url）"),
+    ("SettingsAiBaseUrlPlaceholder", "http://127.0.0.1:8080/v1", "例：http://127.0.0.1:8080/v1"),
+    ("SettingsAiBaseUrlHint", "The /v1 root of an OpenAI-compatible service. Leave empty to use the provider default.", "OpenAI 兼容服务的 /v1 根地址；留空则用该提供商的默认端点。"),
+    ("SettingsAiEffective", "Effective: {value}", "生效：{value}"),
+    ("SettingsAiModel", "Model name", "模型名称"),
+    ("SettingsAiModelPlaceholder", "deepseek-chat", "例：deepseek-chat"),
+    ("SettingsAiApiKey", "API key", "API 密钥"),
+    ("SettingsAiApiKeyPlaceholder", "Paste the key", "粘贴密钥"),
+    ("SettingsAiApiKeyConfigured", "A key is stored ({chars} characters). Leave this empty to keep it.", "已保存密钥（{chars} 个字符）。留空则保持不变。"),
+    ("SettingsAiApiKeyMissing", "No key stored yet", "还没有保存密钥"),
+    ("SettingsAiShow", "Show", "显示"),
+    ("SettingsAiHide", "Hide", "隐藏"),
+    ("SettingsAiSave", "Save", "保存"),
+    ("SettingsAiTest", "Test connection", "测试连接"),
+    ("SettingsAiTesting", "Testing…", "正在测试…"),
+    ("SettingsAiSaved", "Saved. It takes effect immediately, no restart needed.", "已保存，立刻生效，不用重启。"),
+    ("SettingsAiRefused", "Not saved: {reason}", "未保存：{reason}"),
+    ("SettingsAiUnsaved", "There are unsaved changes.", "有未保存的改动。"),
+    ("SettingsAiNoStorage", "No settings file is available in this run, so nothing can be saved or tested.", "这一次运行没有可用的设置文件，保存与测试都做不了。"),
+    ("SettingsAiTestDisabled", "Fill in the missing field before testing: {missing}.", "先补上这一项再测试：{missing}。"),
+    ("SettingsAiMissingDisabled", "the assistant is disabled", "助手处于关闭状态"),
+    ("SettingsAiMissingBaseUrl", "the endpoint address", "端点地址"),
+    ("SettingsAiMissingModel", "the model name", "模型名称"),
+    ("SettingsAiMissingApiKey", "the API key", "API 密钥"),
+    ("SettingsAiReasonProvider", "the provider value is not recognised", "提供商取值不认识"),
+    ("SettingsAiReasonBaseUrl", "the endpoint must start with http:// or https://", "端点必须以 http:// 或 https:// 开头"),
+    ("SettingsAiReasonModel", "the model name is required", "必须填模型名称"),
+    ("SettingsAiTestPassed", "Connected — the endpoint answered.", "连接通过 —— 端点有正常回应。"),
+    ("SettingsAiTestAuth", "Authentication failed: the endpoint rejected the key.", "鉴权失败：端点拒绝了这个密钥。"),
+    ("SettingsAiTestModel", "The endpoint answered, but this model does not exist.", "端点通了，但没有这个模型。"),
+    ("SettingsAiTestUnreachable", "The endpoint is unreachable.", "端点不可达。"),
+    ("SettingsAiTestTimeout", "Timed out while waiting for the endpoint.", "等端点回应超时了。"),
+    ("SettingsAiTestOther", "The request failed for another reason (see the detail below).", "请求因为别的原因失败了（详情见下）。"),
+    ("SettingsAiTestNotConfigured", "Nothing was sent: the configuration is incomplete.", "什么都没有发出去：配置还不完整。"),
+    ("SettingsAiTestTarget", "Target: {base_url} · model {model} · {ms} ms", "目标：{base_url} · 模型 {model} · {ms} 毫秒"),
+    ("SettingsAiTestDetail", "Detail: {detail}", "详情：{detail}"),
+    ("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} 或更新"),
+    ("DownloadOptionsLiteLoaderVanillaOnly", "Vanilla parent only — Forge goes through the CLI", "只叠原版；叠 Forge 请走命令行"),
+    ("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", "选择实例"),
+    ("CrashDialogTitleFailed", "Launch failed", "启动失败"),
+    ("CrashDialogTitleCrashed", "The game crashed", "游戏崩溃"),
+    ("CrashDialogExitCode", "Exit code {code}", "退出码 {code}"),
+    ("CrashDialogStartedThenDied", "The game process started, then exited abnormally.", "游戏进程起来了，随后异常退出。"),
+    ("CrashDialogSilentFailure", "The game exited with code 0 but never really started.", "游戏以退出码 0 结束，但并没有真正起来。"),
+    ("CrashDialogStageReason", "It failed before the game could start: {stage}", "游戏还没起来就失败了：{stage}"),
+    ("CrashDialogCrashReportFound", "The game wrote a crash report — the details are below.", "游戏写出了崩溃报告，详见下方说明。"),
+    ("CrashDialogNoGameLog", "No crash report this time: the game stopped before it could write one. The last lines the launcher captured are below.", "这次没有生成崩溃报告：游戏还没来得及写就停了。下面是启动器捕获的最后若干行。"),
+    ("CrashDialogNoLogAtAll", "No crash report and no captured output. Most likely: missing Java, not enough memory, wrong launch arguments, or missing libraries.", "既没有崩溃报告，也没有捕获到输出。最可能的原因：缺少 Java、内存不足、启动参数错误、或库文件缺失。"),
+    ("CrashDialogShowDetail", "Show crash details", "展开崩溃说明"),
+    ("CrashDialogHideDetail", "Hide crash details", "收起崩溃说明"),
+    ("CrashDialogLauncherLogs", "Launcher logs", "启动器日志"),
+    ("CrashDialogSessionLog", "This session", "本次会话"),
+    ("CrashDialogGameLog", "Game latest.log", "游戏 latest.log"),
+    ("CrashDialogCrashReports", "Crash reports", "崩溃报告目录"),
+    ("CrashDialogCapturedTail", "CAPTURED OUTPUT (last {count} lines)", "捕获输出（最后 {count} 行）"),
+    ("CrashDialogExport", "Export report bundle", "导出诊断包"),
+    ("CrashDialogOpenFolder", "Open log folder", "打开日志文件夹"),
+    ("CrashDialogCopyPaths", "Copy file paths", "复制文件路径"),
+    ("CrashDialogClose", "Close", "关闭"),
+    ("CrashDialogCopied", "File paths copied to the clipboard", "文件路径已复制到剪贴板"),
+    ("CrashDialogExportDone", "Exported {bytes} bytes to {path}", "已导出 {bytes} 字节到 {path}"),
+    ("CrashDialogExportFailed", "Export failed: {error}", "导出失败：{error}"),
+    ("CrashDialogExportTruncated", "{count} file(s) were too large and are truncated (head + tail kept).", "有 {count} 个文件太大，已截断（保留头 + 尾）。"),
+    ("CrashDialogOpenFailed", "Could not open the folder: {error}", "打不开文件夹：{error}"),
+    ("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.", "可以问实例、下载或日志。"),
+    ("SettingsLanguageFollowSystem", "Follow system", "跟随系统"),
+    ("SettingsLanguageZhCn", "Chinese (Simplified)", "简体中文"),
+    ("SettingsLanguageEn", "English", "英文"),
+    ("SettingsLanguageEffective", "Interface right now: {language}", "界面当前使用：{language}"),
+    ("SettingsTheme", "Theme", "主题"),
+    ("SettingsThemeFollowSystem", "Follow system", "跟随系统"),
+    ("SettingsThemeInk", "Ink", "Ink（深色）"),
+    ("SettingsThemeSilver", "Silver", "Silver（浅色）"),
+    (
+        "SettingsThemeHint",
+        "Ink is the dark scheme, Silver the light one. Follow system picks between them as Windows switches.",
+        "Ink 是深色主方案，Silver 是浅色主方案；跟随系统会随 Windows 的深浅在这两块之间切换。",
+    ),
+    ("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", "下载"),
+    ("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 的骨架回退。"),
+    ("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", "看全部类型"),
+    ("VersionSearchHitsOne", "1 match", "1 个匹配"),
+    ("VersionSearchElsewhereTitle", "Found in another type", "在别的类型里找到了"),
+    ("VersionSearchElsewhereOne", "1 version matches, but it is in another type.", "有 1 个版本匹配，但它在别的类型里。"),
+    ("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.", "检查网络后重试。"),
+    ("ContentOfflineTitle", "No connection", "未联网"),
+    ("ContentOfflineBody", "Content search needs the network. Check your connection, 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}"),
+    ("ContentDetailFetching", "Loading versions…", "正在取版本列表…"),
+    ("ContentDetailFetchFailed", "Could not load versions: {reason}", "版本列表取不到：{reason}"),
+    ("ContentDetailVersionCount", "{count} versions", "{count} 个版本"),
+    ("ContentDetailVersionLine", "{number} · {kind} · {date}", "{number}（{kind}）· {date}"),
+    ("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 来源的安装尚未开放"),
+    ("ContentInstallFailedTitle", "Install did not finish — {count} items failed", "安装未完成 —— {count} 项没装上"),
+    ("ContentInstallRetryIncompatible", "Not available for this version/loader", "不兼容所选版本/加载器"),
+    ("ContentInstallRetryUnreachable", "Could not fetch (network or missing project)", "取不到（网络 / 项目不存在）"),
+    ("ContentInstallRetryOnly", "Retry just these {count}", "只重试这 {count} 个"),
+    ("ContentInstallRetryHint", "Retry asks again only for the items above; files that already landed stay put.", "重试只重新解析上面这几项，已落盘的文件不动。"),
+    ("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"),
+];
diff --git a/crates/i18n/src/catalog/instances.rs b/crates/i18n/src/catalog/instances.rs
new file mode 100644
index 0000000..c36d55b
--- /dev/null
+++ b/crates/i18n/src/catalog/instances.rs
@@ -0,0 +1,223 @@
+//! 实例页文案：页头、列表列头、详情动作、元信息卡的标签与值、运行状态与启动阶段。
+//!
+//! 域文件的形状见 [`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}"),
+            // 失败状态行的**框架**：`{reason}` 是「哪一步」或「结局」的短句
+            // （M161 复审 P1-1：「起来了又崩」与「没起来」必须能说出不同的话）。
+            InstancesFailed => ("Launch failed · {reason}", "启动失败 · {reason}"),
+            InstancesCrashed => ("the game crashed (exit {code})", "游戏崩溃（退出码 {code}）"),
+            // 单行列表行也要放得下（`Launch failed · ` + 这一句 ≤ 行宽），
+            // 「exit 0 却没起来」这一条信息必须留（复审 P1-1 第 ③ 条）。
+            InstancesSilentFailed => ("exit 0, but never started", "退出码 0，没起来"),
+            InstancesStageDownload => ("Downloading", "下载中"),
+            InstancesStageVerify => ("Verifying", "校验中"),
+            InstancesStageLaunch => ("Starting", "启动中"),
+            InstancesStageWindow => ("Waiting for window", "等待游戏窗口"),
+            // ── 启动参数区（M157）：实例配置页的五项 + 三态后端 + 门槛提示
+            InstancesLaunchTitle => ("LAUNCH OPTIONS", "启动参数"),
+            InstancesLaunchJvm => ("JVM arguments", "JVM 参数"),
+            InstancesLaunchJvmHint => ("Space separated, quotes allowed. Empty = follow the global extra JVM arguments (both are sent; on duplicates the instance wins).", "空格分隔、支持引号。留空 = 跟随全局附加 JVM 参数（两者叠加下发，同名选项实例赢）。"),
+            InstancesLaunchGame => ("Game arguments", "游戏参数"),
+            InstancesLaunchGameHint => ("Appended last, so they override earlier game arguments. Empty = nothing appended.", "追加在命令行最后，可覆盖前面的游戏参数。留空 = 不追加。"),
+            InstancesLaunchMemory => ("Max memory (MiB)", "最大内存（MiB）"),
+            InstancesLaunchMemoryHint => ("Empty = follow the global default ({default} MiB).", "留空 = 跟随全局默认（{default} MiB）。"),
+            InstancesLaunchJava => ("Java executable", "Java 可执行文件"),
+            InstancesLaunchJavaHint => ("Empty = follow the global setting, then auto-pick (managed > JAVA_HOME > PATH).", "留空 = 跟随全局设置，再退到自动挑选（托管 > 环境变量 > 系统路径）。"),
+            InstancesLaunchBackend => ("Graphics backend", "图形后端"),
+            InstancesLaunchBackendGated => ("Requires MC {min}+ (this instance: {version}). The flag is not sent on this version.", "需游戏版本 {min} 及以上（本实例 {version}），这个版本不会下发该参数。"),
+            InstancesLaunchEffective => ("Effective: {value}", "生效：{value}"),
+            InstancesBackendDefault => ("Default", "默认"),
+            InstancesBackendOpengl => ("OpenGL", "OpenGL 后端"),
+            InstancesBackendVulkan => ("Vulkan", "Vulkan 后端"),
+            InstancesLaunchSave => ("Save", "保存"),
+            InstancesLaunchReset => ("Reset to global", "恢复跟随全局"),
+
+            // ── 导入已有版本（M223）：向导的全部文案
+            AdoptTitle => ("Import an existing version", "导入已有版本"),
+            AdoptSubtitle => ("Register versions another launcher already installed. Nothing is copied: versions, libraries and assets stay where they are.", "把别的启动器已经装好的版本登记成实例。不复制任何东西：versions / libraries / assets 原地不动。"),
+            AdoptScanning => ("Scanning versions/…", "正在扫描 versions/…"),
+            AdoptEmpty => ("No version found under {dir}. Install one here, or point the game folder at the .minecraft another launcher uses.", "在 {dir} 下一个版本都没找到。可以用本启动器装一个，或者把游戏目录指向别的启动器用的那个 .minecraft。"),
+            AdoptSelectLabel => ("Pick a version", "选择版本"),
+            AdoptReady => ("Ready", "可导入"),
+            AdoptBlocked => ("{count} problem(s)", "{count} 个问题"),
+            AdoptRegistered => ("Already used by {name}", "已被 {name} 使用"),
+            AdoptTargetLabel => ("Where should the game run?", "游戏在哪个目录里跑"),
+            AdoptTargetInstanceDir => ("New folder in ULL data (default)", "ULL 数据区新建目录（缺省）"),
+            AdoptTargetInstanceDirHint => ("mods, saves and config stay out of the other launcher's .minecraft", "mods / saves / config 不会落进别人的 .minecraft"),
+            AdoptTargetShared => ("Share the game folder", "共用游戏目录"),
+            AdoptTargetSharedHint => ("mods, saves and config are written into the other launcher's .minecraft", "mods / saves / config 会写进别人的 .minecraft"),
+            AdoptTargetVersionDir => ("Use the version folder", "用版本目录"),
+            AdoptTargetVersionDirHint => ("player data grows inside versions/", "玩家数据会长在 versions/ 里"),
+            AdoptNameLabel => ("Instance name (empty = version id)", "实例名（留空 = 版本 id）"),
+            AdoptPreview => ("Check", "预检"),
+            AdoptConfirm => ("Import", "导入"),
+            AdoptBack => ("Back", "返回"),
+            AdoptClose => ("Close", "关闭"),
+            AdoptPlanTitle => ("Ready to import", "可以导入"),
+            AdoptPlanRunDir => ("Game folder", "运行目录"),
+            AdoptPlanIsolation => ("Isolation", "隔离方式"),
+            AdoptFailureTitle => ("Import failed", "导入失败"),
+            AdoptProblemCount => ("Every reason is listed below:", "全部原因如下："),
+            AdoptInstanceName => ("Instance name", "实例名"),
+            AdoptDoneTitle => ("Imported", "已导入"),
+            AdoptDoneHint => ("It is in the instance list now. Player data will live in the game folder below.", "它已经出现在实例列表里；玩家数据会落在下面这个运行目录。"),
+            // ── MODS 区（M224）：本地 mod 列表 + 启停开关。
+            // `mods` 是**目录名**（文件系统事实，不翻译），所以中文那栏里也出现它；
+            // 页面守门的 ALLOWED 里因此有一条 `mods`（见 `pages/instances/tests/i18n.rs`）。
+            InstancesModsTitle => ("MODS", "模组"),
+            InstancesModsCount => ("{enabled} enabled · {disabled} disabled", "{enabled} 启用 · {disabled} 禁用"),
+            InstancesModsLoading => ("Reading mods/…", "正在读取 mods/…"),
+            InstancesModsEmpty => ("No mods here yet — put jars into mods/ and they show up.", "这里还没有模组——把模组文件放进 mods/ 就会出现在这里。"),
+            InstancesModsMissingDir => ("This instance has no mods/ directory yet.", "这个实例还没有 mods/ 目录。"),
+            InstancesModsRunning => ("The game is running — toggles are read-only until it exits.", "游戏正在运行——退出前开关只读。"),
+            InstancesModsOldBadge => ("legacy file", "旧版本残留"),
+            InstancesModsSkipped => ("{count} entries skipped", "跳过 {count} 项"),
+            InstancesModsFailed => ("Could not read mods/: {reason}", "读取 mods/ 失败：{reason}"),
+            InstancesModsToggleFailed => ("Could not toggle {file}: {reason}", "启停 {file} 失败：{reason}"),
+            // 启停失败的**具名原因**（`ModFailureKind` → 一句话；`{detail}` 是 OS 原文，只进括号）
+            InstancesModsReasonRunning => ("the game is running", "游戏正在运行"),
+            InstancesModsReasonInstance => ("the instance is gone", "实例已不存在"),
+            InstancesModsReasonName => ("the file name is not usable", "文件名不可用"),
+            InstancesModsReasonDirectory => ("there is no usable mods/ directory", "没有可用的 mods/ 目录"),
+            InstancesModsReasonMissing => ("the file is gone", "文件已不在"),
+            InstancesModsReasonNotFile => ("that is not a regular file", "那不是普通文件"),
+            InstancesModsReasonCollision => ("a file with that name already exists", "同名文件已存在"),
+            InstancesModsReasonRename => ("the rename failed", "改名失败"),
+            // ── 存档区（M235 · STOREMVP 读路径 / M247 · SAVESOPS 写操作）。
+            // M235 那条「这一版只读」（`InstancesSavesReadOnly`）**已删**：写操作接上之后它是假的，
+            // 边界改由 core 的 `game::saves::write::boundary` 守（越界 / 符号链接 / 撞名都在那里拒）。
+            // `saves/` / `screenshots/` 是**目录名**，两套语言都原样保留（与 MODS 区的 `mods` 同一条口径）。
+            InstancesSavesTitle => ("SAVES", "存档"),
+            InstancesSavesCount => ("{worlds} worlds · {shots} screenshots", "{worlds} 个世界 · {shots} 张截图"),
+            InstancesSavesLoading => ("Reading saves/…", "正在读取 saves/…"),
+            InstancesSavesEmpty => ("No worlds or screenshots yet — play once and they show up here.", "还没有世界或截图——玩一次就会出现在这里。"),
+            InstancesSavesMissingDir => ("This instance has no saves/ or screenshots/ directory yet.", "这个实例还没有 saves/ 或 screenshots/ 目录。"),
+            InstancesSavesWorlds => ("WORLDS", "世界"),
+            InstancesSavesScreenshots => ("SCREENSHOTS", "截图"),
+            InstancesSavesNoWorlds => ("No worlds yet.", "还没有世界。"),
+            InstancesSavesNoScreenshots => ("No screenshots yet.", "还没有截图。"),
+            InstancesSavesWorldIcon => ("has icon", "有图标"),
+            InstancesSavesTimeUnknown => ("time unknown", "时间未知"),
+            InstancesSavesSkipped => ("{count} entries skipped", "跳过 {count} 项"),
+            InstancesSavesOpenFolder => ("Open saves folder", "打开存档文件夹"),
+            InstancesSavesRetry => ("Retry", "重试"),
+            InstancesSavesFailed => ("Could not read saves/: {reason}", "读取 saves/ 失败：{reason}"),
+            InstancesSavesOpenFailed => ("Could not open the folder: {reason}", "打开文件夹失败：{reason}"),
+            InstancesSavesReasonDir => ("the directory is not usable", "目录不可用"),
+            InstancesSavesReasonInstance => ("the instance is gone", "实例已不存在"),
+            InstancesSavesReasonOpen => ("the file manager did not start", "文件管理器没起来"),
+            // ── 存档**写操作**（M247 · SAVESOPS）：重命名 / 删除（二次确认）/ 备份导出。
+            // M235 那条「这一版只读」的 `InstancesSavesReadOnly` **已删**：写操作接上之后它就是假的
+            // （金表同步少了那一行，不是重排）。删除确认框的三句是**不可逆动作**的兜底，不许省。
+            InstancesSavesRename => ("Rename", "重命名"),
+            InstancesSavesBackup => ("Back up", "备份"),
+            InstancesSavesDelete => ("Delete", "删除"),
+            InstancesSavesRenamePlaceholder => ("New name for this world", "这个世界的新名字"),
+            InstancesSavesRenameConfirm => ("Rename", "改名"),
+            InstancesSavesCancel => ("Cancel", "取消"),
+            InstancesSavesBusy => ("Working…", "正在处理…"),
+            InstancesSavesDeleteTitle => ("Delete this world?", "删除这个世界？"),
+            InstancesSavesDeleteBody => ("{dir} and everything inside it will be deleted. This cannot be undone.", "{dir} 和它里面的全部内容都会被删除，且不能撤销。"),
+            InstancesSavesDeleteConfirm => ("Delete world", "删除世界"),
+            InstancesSavesRenamed => ("Renamed {from} → {to}.", "已把 {from} 改名为 {to}。"),
+            InstancesSavesDeleted => ("Deleted {dir}.", "已删除 {dir}。"),
+            InstancesSavesBackedUp => ("Backed up {dir} to {path} ({size}).", "已把 {dir} 备份到 {path}（{size}）。"),
+            InstancesSavesBackupSkipped => ("{count} symlinks skipped", "跳过 {count} 个符号链接"),
+            InstancesSavesRenameFailed => ("Could not rename {file}: {reason}", "重命名 {file} 失败：{reason}"),
+            InstancesSavesDeleteFailed => ("Could not delete {file}: {reason}", "删除 {file} 失败：{reason}"),
+            InstancesSavesBackupFailed => ("Could not back up {file}: {reason}", "备份 {file} 失败：{reason}"),
+            InstancesSavesReasonUnsafeName => ("the name is not usable", "名字不可用"),
+            InstancesSavesReasonSymlink => ("that path is a symbolic link (not followed)", "那个路径是符号链接（不跟随）"),
+            InstancesSavesReasonMissing => ("the world is gone", "那个世界已不在"),
+            InstancesSavesReasonNotDir => ("that is not a directory", "那不是目录"),
+            InstancesSavesReasonConflict => ("a world with that name already exists", "同名世界已存在"),
+            InstancesSavesReasonBoundary => ("that path is outside saves/", "那个路径落在 saves/ 之外"),
+            InstancesSavesReasonTooLarge => ("the world is too large for one zip", "这个世界太大，一个 zip 装不下"),
+            InstancesSavesReasonWrite => ("the write failed", "写盘失败"),
+            // 实例在启动/运行中：三个写操作**主动不写盘**（不是"写盘失败"——Linux 上删一个正在跑的
+            // 世界是会成功的，所以这条要直说"先退出"，别让用户以为是权限问题）。
+            InstancesSavesReasonRunning => ("the game is running (exit it first)", "游戏正在运行（先退出再操作）"),
+            // ── 截图**缩略图**（M251 · SAVESHOTS，D54）。
+            // 四句都是「这一格为什么没有图」：没轮到（超 60 张预算）/ 太大 / 读不出 / 解不出。
+            // 第 1 句与后三句分开是刻意的——"没生成"与"生成了但失败"对用户的含义不同，
+            // 前者点一下刷新可能就有了，后者得用户自己去动文件。
+            InstancesSavesPreviewNone => ("no preview", "未生成预览"),
+            InstancesSavesPreviewTooLarge => ("too large for a preview (over 8 MiB)", "文件过大，未生成预览（超过 8 MiB）"),
+            InstancesSavesPreviewUnreadable => ("the file could not be read", "读不出这张图"),
+            InstancesSavesPreviewDecode => ("not a decodable image", "解不出这张图（可能已损坏或格式不支持）"),
+        } }
+    };
+}
+
+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..1c80063
--- /dev/null
+++ b/crates/i18n/src/catalog/launch.rs
@@ -0,0 +1,70 @@
+//! 启动结局文案：一句话 = 一个 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}"),
+            // M161：启动失败的**阶段**词表。presenter 只给稳定 slug
+            // （`LaunchFailureStage`），界面在这里选词——此前这些前缀是 presenter 里拼的中文
+            // （「读版本 JSON 失败」「隔离目录派生失败」…），英文界面上原样露出来。
+            LaunchStageVersionManifest => ("Reading the version file", "读版本文件"),
+            LaunchStageInheritance => ("Resolving the inheritance chain", "解析继承链"),
+            LaunchStageInstanceConfig => ("Reading the instance settings", "读实例设置"),
+            LaunchStageIsolation => ("Preparing the isolated game folder", "准备隔离游戏目录"),
+            LaunchStageIdentity => ("Preparing the account", "准备账户"),
+            LaunchStageSpawn => ("Starting the game process", "启动游戏进程"),
+            LaunchStageFailed => ("Launch failed · {stage}: {detail}", "启动失败 · {stage}：{detail}"),
+            LaunchToastEnded => ("{outcome} · {seconds}s", "{outcome} · {seconds} 秒"),
+            // 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=, or set that environment variable before launching.",
+                "微软登录未配置：缺少 Azure 公共客户端 id（登录功能已实现，只差这一项配置）。构建时注入：ULL_MSA_CLIENT_ID= cargo build；或启动前设置同名环境变量 ULL_MSA_CLIENT_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（repo 任何文件都不许带）。
+        assert!(en.contains("") && zh.contains(""));
+    }
+}
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..a390680
--- /dev/null
+++ b/crates/i18n/src/catalog/logs.rs
@@ -0,0 +1,66 @@
+//! 日志页文案（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", "选择实例"),
+            // --- 启动失败弹窗（M187）---
+            CrashDialogTitleFailed => ("Launch failed", "启动失败"),
+            CrashDialogTitleCrashed => ("The game crashed", "游戏崩溃"),
+            CrashDialogExitCode => ("Exit code {code}", "退出码 {code}"),
+            CrashDialogStartedThenDied => ("The game process started, then exited abnormally.", "游戏进程起来了，随后异常退出。"),
+            CrashDialogSilentFailure => ("The game exited with code 0 but never really started.", "游戏以退出码 0 结束，但并没有真正起来。"),
+            CrashDialogStageReason => ("It failed before the game could start: {stage}", "游戏还没起来就失败了：{stage}"),
+            CrashDialogCrashReportFound => ("The game wrote a crash report — the details are below.", "游戏写出了崩溃报告，详见下方说明。"),
+            CrashDialogNoGameLog => ("No crash report this time: the game stopped before it could write one. The last lines the launcher captured are below.", "这次没有生成崩溃报告：游戏还没来得及写就停了。下面是启动器捕获的最后若干行。"),
+            CrashDialogNoLogAtAll => ("No crash report and no captured output. Most likely: missing Java, not enough memory, wrong launch arguments, or missing libraries.", "既没有崩溃报告，也没有捕获到输出。最可能的原因：缺少 Java、内存不足、启动参数错误、或库文件缺失。"),
+            CrashDialogShowDetail => ("Show crash details", "展开崩溃说明"),
+            CrashDialogHideDetail => ("Hide crash details", "收起崩溃说明"),
+            CrashDialogLauncherLogs => ("Launcher logs", "启动器日志"),
+            CrashDialogSessionLog => ("This session", "本次会话"),
+            CrashDialogGameLog => ("Game latest.log", "游戏 latest.log"),
+            CrashDialogCrashReports => ("Crash reports", "崩溃报告目录"),
+            CrashDialogCapturedTail => ("CAPTURED OUTPUT (last {count} lines)", "捕获输出（最后 {count} 行）"),
+            CrashDialogExport => ("Export report bundle", "导出诊断包"),
+            CrashDialogOpenFolder => ("Open log folder", "打开日志文件夹"),
+            CrashDialogCopyPaths => ("Copy file paths", "复制文件路径"),
+            CrashDialogClose => ("Close", "关闭"),
+            CrashDialogCopied => ("File paths copied to the clipboard", "文件路径已复制到剪贴板"),
+            CrashDialogExportDone => ("Exported {bytes} bytes to {path}", "已导出 {bytes} 字节到 {path}"),
+            CrashDialogExportFailed => ("Export failed: {error}", "导出失败：{error}"),
+            CrashDialogExportTruncated => ("{count} file(s) were too large and are truncated (head + tail kept).", "有 {count} 个文件太大，已截断（保留头 + 尾）。"),
+            CrashDialogOpenFailed => ("Could not open the folder: {error}", "打不开文件夹：{error}"),
+        } }
+    };
+}
+
+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/accent.rs b/crates/i18n/src/catalog/settings/accent.rs
new file mode 100644
index 0000000..e2583b0
--- /dev/null
+++ b/crates/i18n/src/catalog/settings/accent.rs
@@ -0,0 +1,48 @@
+//! 设置页「Appearance」分组**强调色**一族的文案（M250 ACCENTWIRE）。
+//!
+//! ## 为什么单开一个域文件，而不是写进 `settings/appearance.rs`
+//!
+//! `settings_appearance_entries` 在装配链**中间**。往那个域后面追加，会把其后所有 key 在
+//! `Key::ALL` 里整体平移 ⇒ 金表（逐 index 逐字节）整片红。本域挂在**链尾**
+//! （`font_install_entries` 之后），于是既有顺序一个不动，金表只需在 `tail2::ROWS` 末尾追加
+//! （M104 / M106 / M107 / M109 / M114 / M159 / M168 都是这条做法）。
+//!
+//! key 前缀仍叫 `SettingsAppearanceAccent*`：`catalog/settings/appearance.rs` 的译文守卫按
+//! **名字前缀**筛 key，改名会让那两条守卫漏掉这一族。
+//!
+//! ## 三档失败原因为什么分开写
+//!
+//! `#12`（位数不足）、`#006A5C00`（位数过多）、`zzzzzz`（非十六进制）是三种不同的手误，
+//! 而「格式不对」对用户没有行动性。分开写之后错行能直接说「现在 2 位」「有非十六进制字符 z」。
+//!
+//! 域文件的形状见 [`crate::catalog`] 的「域装配」一节。
+
+macro_rules! settings_accent_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* {
+            $($acc)*
+            // ── 强调色（M250：设置页 Appearance 组的第一个控件）
+            SettingsAppearanceAccent => ("Accent colour", "强调色"),
+            SettingsAppearanceAccentPresets => ("Presets", "预设"),
+            SettingsAppearanceAccentFactory => ("Factory", "出厂"),
+            SettingsAppearanceAccentHint => (
+                "Empty = the factory accent from the brand board. A custom accent replaces primary / secondary / tertiary only; neutral surfaces and error colours do not follow it.",
+                "空 = 出厂品牌板的强调色。自定义强调色只替换 primary / secondary / tertiary 三族；中性表面与错误色不随强调色变。"
+            ),
+            SettingsAppearanceAccentShort => (
+                "Accent needs 6 hex digits (RRGGBB); got {digits}.",
+                "强调色要 6 位十六进制（RRGGBB），现在 {digits} 位。"
+            ),
+            SettingsAppearanceAccentLong => (
+                "Accent has {digits} digits; a colour takes exactly 6.",
+                "强调色有 {digits} 位，一个颜色只要 6 位。"
+            ),
+            SettingsAppearanceAccentDigit => (
+                "Accent contains a character that is not a hex digit: {ch}",
+                "强调色里有非十六进制字符：{ch}"
+            ),
+        } }
+    };
+}
+
+pub(crate) use settings_accent_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..0525fb9
--- /dev/null
+++ b/crates/i18n/src/catalog/settings/ai.rs
@@ -0,0 +1,96 @@
+//! 设置页「助手（AI）」分组文案（M174）：状态矩阵四档 + 五个输入项 + 测试连接六档。
+//!
+//! 域文件的形状见 [`crate::catalog`] 的「域装配」一节。本域在装配链里排在
+//! `settings_download_entries` 之后、`core_text_entries` 之前（设置页五域的位置），
+//! 所以金表那几行也要插在 `SettingsAppearanceCornerSuspended` 之后——**顺序即 `Key::ALL`**。
+//!
+//! 三条口径：
+//!
+//! 1. **失败四种各写各的句子**（鉴权 / 模型不存在 / 不可达 / 超时）：合成一句「测试失败」等于
+//!    让用户自己猜是 key 错了还是地址错了；
+//! 2. 密钥的**值**永远不进文案：只有 `{chars}`（已存字符数）与「未配置」两种说法；
+//! 3. 技术名词不翻：`base_url` / `OpenAI` / `Anthropic` / `Ollama` 原样。
+
+macro_rules! settings_ai_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* {
+            $($acc)*
+            // ── 左列分组名（与 NavSettings 同源：左列是导航，标题在正文里）
+            SettingsGroupAssistant => ("Assistant", "助手"),
+            // ── 状态矩阵（未配置 / 已配置 / 已通过 / 测试失败）
+            SettingsAiStatusLabel => ("Status: {status}", "状态：{status}"),
+            SettingsAiStatusUnconfigured => ("not configured", "未配置"),
+            SettingsAiStatusConfigured => ("configured", "已配置"),
+            SettingsAiStatusVerified => ("verified", "连接已通过"),
+            SettingsAiStatusTestFailed => ("test failed", "测试失败"),
+            // ── 开关
+            SettingsAiEnable => ("Enable the assistant", "启用助手"),
+            SettingsAiEnableHint => (
+                "With this off, the assistant stays quiet; crash diagnosis from the rule engine keeps working.",
+                "关掉之后助手不再工作；规则引擎的崩溃诊断照常可用。"
+            ),
+            // ── 提供商
+            SettingsAiProviderLabel => ("Provider", "提供商"),
+            SettingsAiProviderOpenAi => ("OpenAI compatible", "OpenAI 兼容"),
+            SettingsAiProviderAnthropic => ("Anthropic", "Anthropic 原生"),
+            SettingsAiProviderOllama => ("Ollama", "Ollama 原生"),
+            SettingsAiProviderDisabled => ("Disabled", "已禁用"),
+            // ── 端点 / 模型
+            SettingsAiBaseUrl => ("Endpoint (base_url)", "端点（base_url）"),
+            SettingsAiBaseUrlPlaceholder => ("http://127.0.0.1:8080/v1", "例：http://127.0.0.1:8080/v1"),
+            SettingsAiBaseUrlHint => (
+                "The /v1 root of an OpenAI-compatible service. Leave empty to use the provider default.",
+                "OpenAI 兼容服务的 /v1 根地址；留空则用该提供商的默认端点。"
+            ),
+            SettingsAiEffective => ("Effective: {value}", "生效：{value}"),
+            SettingsAiModel => ("Model name", "模型名称"),
+            SettingsAiModelPlaceholder => ("deepseek-chat", "例：deepseek-chat"),
+            // ── 密钥（只有字符数与掩码，没有值）
+            SettingsAiApiKey => ("API key", "API 密钥"),
+            SettingsAiApiKeyPlaceholder => ("Paste the key", "粘贴密钥"),
+            SettingsAiApiKeyConfigured => (
+                "A key is stored ({chars} characters). Leave this empty to keep it.",
+                "已保存密钥（{chars} 个字符）。留空则保持不变。"
+            ),
+            SettingsAiApiKeyMissing => ("No key stored yet", "还没有保存密钥"),
+            SettingsAiShow => ("Show", "显示"),
+            SettingsAiHide => ("Hide", "隐藏"),
+            // ── 动作与回执
+            SettingsAiSave => ("Save", "保存"),
+            SettingsAiTest => ("Test connection", "测试连接"),
+            SettingsAiTesting => ("Testing…", "正在测试…"),
+            SettingsAiSaved => ("Saved. It takes effect immediately, no restart needed.", "已保存，立刻生效，不用重启。"),
+            SettingsAiRefused => ("Not saved: {reason}", "未保存：{reason}"),
+            SettingsAiUnsaved => ("There are unsaved changes.", "有未保存的改动。"),
+            SettingsAiNoStorage => (
+                "No settings file is available in this run, so nothing can be saved or tested.",
+                "这一次运行没有可用的设置文件，保存与测试都做不了。"
+            ),
+            SettingsAiTestDisabled => (
+                "Fill in the missing field before testing: {missing}.",
+                "先补上这一项再测试：{missing}。"
+            ),
+            // ── 缺项（四种各说各的）
+            SettingsAiMissingDisabled => ("the assistant is disabled", "助手处于关闭状态"),
+            SettingsAiMissingBaseUrl => ("the endpoint address", "端点地址"),
+            SettingsAiMissingModel => ("the model name", "模型名称"),
+            SettingsAiMissingApiKey => ("the API key", "API 密钥"),
+            // ── 拒绝保存的原因（本地校验）
+            SettingsAiReasonProvider => ("the provider value is not recognised", "提供商取值不认识"),
+            SettingsAiReasonBaseUrl => ("the endpoint must start with http:// or https://", "端点必须以 http:// 或 https:// 开头"),
+            SettingsAiReasonModel => ("the model name is required", "必须填模型名称"),
+            // ── 测试结论（六档）
+            SettingsAiTestPassed => ("Connected — the endpoint answered.", "连接通过 —— 端点有正常回应。"),
+            SettingsAiTestAuth => ("Authentication failed: the endpoint rejected the key.", "鉴权失败：端点拒绝了这个密钥。"),
+            SettingsAiTestModel => ("The endpoint answered, but this model does not exist.", "端点通了，但没有这个模型。"),
+            SettingsAiTestUnreachable => ("The endpoint is unreachable.", "端点不可达。"),
+            SettingsAiTestTimeout => ("Timed out while waiting for the endpoint.", "等端点回应超时了。"),
+            SettingsAiTestOther => ("The request failed for another reason (see the detail below).", "请求因为别的原因失败了（详情见下）。"),
+            SettingsAiTestNotConfigured => ("Nothing was sent: the configuration is incomplete.", "什么都没有发出去：配置还不完整。"),
+            SettingsAiTestTarget => ("Target: {base_url} · model {model} · {ms} ms", "目标：{base_url} · 模型 {model} · {ms} 毫秒"),
+            SettingsAiTestDetail => ("Detail: {detail}", "详情：{detail}"),
+        } }
+    };
+}
+
+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..3d3dce5
--- /dev/null
+++ b/crates/i18n/src/catalog/settings/appearance.rs
@@ -0,0 +1,258 @@
+//! 设置页「Appearance」分组文案（M116 落了圆角一族；M180 `I18NAPPEAR` 补齐全组）。
+//!
+//! 加 key 时把条目写进 `$($acc)*` 后面即可（形状见 [`crate::catalog`] 的「域装配」一节）。
+//!
+//! ## 两批 key：圆角（M116）在前，其余（M180）在后
+//!
+//! M116 只落了圆角那 5 条；本分组其余控件（整窗/面板透明度、背景图、填充、暗化、配色来源）
+//! 是 M93 落的，文案一直是英文基线字面量。M172 审计量出这一页 27 处文案里 22 处硬编码、中文界面
+//! 本地化 0/27。M180 把**控件文案 + 运行时诊断 + 配色回落提示**全部搬进本文件：
+//!
+//! | 批次 | 条目 | 来源 |
+//! |---|---|---|
+//! | M116 | `Corner` … `CornerSuspended` | `pages/appearance/section/window.rs` 的圆角一段 |
+//! | M180 | `WindowOpacity` … `PaletteAdjusted` | 卡片各段标签/说明 + `state.rs` / `background.rs` / `palette.rs` 的诊断 prose |
+//!
+//! ## 为什么诊断也在这里（而不是留在 `state.rs`）
+//!
+//! `pages/appearance/state.rs` 已经 390 行、贴着 400 行硬线，放不下任何一张文案表。所以那一层只
+//! 给 **key + 已格式化好的参数**（`background::Note`），句子一律在本文件里。
+//!
+//! ## 数值参数：模板里只有 `{name}`，格式在 Rust 侧做
+//!
+//! [`crate::catalog::Catalog::render`] 只做 `{name}` → 值的字面替换，**不认** `{:.2}` 这类格式说明。
+//! 所以「位置/尺寸/上限」这些数字由调用方先 `format!("{:.2}")` 好再当参数传进来：
+//!
+//! | key | 原字面量 | 现在 |
+//! |---|---|---|
+//! | `SettingsAppearancePanelOpacityForcedValue` | `format!("100% (forced from {:.2})")` | `{requested}` = `format!("{:.2}")` |
+//! | `SettingsAppearanceWindowOpacityHint` | `Floor {:.2}` = `WINDOW_ALPHA_FLOOR` | `{floor}` |
+//! | `SettingsAppearancePanelOpacityHint` | `Floor 0.40` = `PANEL_ALPHA_FLOOR` | `{floor}` |
+//! | `SettingsAppearanceBgDimHint` | `Max 0.95` = `BG_DIM_MAX` | `{max}` |
+//! | `SettingsAppearanceBgTooLarge` | `(limit 8192 px per edge)` = `MAX_SOURCE_EDGE` | `{limit}` |
+//! | `SettingsAppearanceBgSmallTile` | `(max 64 tiles …)` = `MAX_TILES` | `{max}` |
+//!
+//! 常量走占位符而不是写进译文，是为了「改常量不用改两套译文」（M180 任务口径）。
+//!
+//! ## 文案口径（不许暗示所有平台一致）
+//!
+//! 用户定案：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% 圆角即恢复。"
+            ),
+            // ---- M180 `I18NAPPEAR`：卡片内文案（① 整窗 / ③ 面板 / ④~⑧ 背景图 / ⑨ 配色来源）
+            SettingsAppearanceWindowOpacity => ("Window transparency", "整窗透明度"),
+            SettingsAppearanceWindowOpacityHint => (
+                "Applies to the whole window. Floor {floor}; 1.00 = fully opaque.",
+                "作用于整个窗口。下限 {floor}；1.00 = 完全不透明。"
+            ),
+            SettingsAppearancePanelOpacity => ("Panel transparency", "面板透明度"),
+            SettingsAppearancePanelOpacityHint => (
+                "Only the panel/card layer. Floor {floor}; independent of window transparency.",
+                "只作用于面板 / 卡片这一层。下限 {floor}；与整窗透明度互不影响。"
+            ),
+            SettingsAppearancePanelOpacityForcedValue => (
+                "100% (forced from {requested})",
+                "100%（强制，原请求值 {requested}）"
+            ),
+            SettingsAppearancePanelOpacityForcedHint => (
+                "Software renderer: panels and glass stay fully opaque (window transparency still works).",
+                "软件渲染：面板与玻璃效果恒为不透明（整窗透明度仍然有效）。"
+            ),
+            SettingsAppearanceBackgroundImage => ("Background image", "背景图"),
+            SettingsAppearanceOff => ("Off", "关"),
+            SettingsAppearanceOn => ("On", "开"),
+            SettingsAppearanceImagePath => ("Image path", "图片路径"),
+            SettingsAppearancePaletteLevel => ("Colours: {level}", "配色：{level}"),
+            SettingsAppearanceBgFill => ("Fill", "填充方式"),
+            SettingsAppearanceBgFillCover => ("Cover", "铺满"),
+            SettingsAppearanceBgFillContain => ("Contain", "完整显示"),
+            SettingsAppearanceBgFillTile => ("Tile", "平铺"),
+            SettingsAppearanceBgDim => ("Dim", "暗化"),
+            SettingsAppearanceBgDimHint => (
+                "Blends the image toward the panel colour so text stays readable. Max {max}.",
+                "把背景图往面板底色上退，让文字读得清。上限 {max}。"
+            ),
+            SettingsAppearancePaletteSource => ("Colour source", "配色来源"),
+            SettingsAppearancePaletteBackground => ("Background", "取自背景图"),
+            SettingsAppearancePaletteWallpaper => ("Wallpaper", "取自壁纸"),
+            SettingsAppearancePalettePreset => ("Preset", "内置色卡"),
+            // ---- M180：运行时诊断（`background.rs` 的三种读盘失败 + 小图平铺）。
+            //
+            // M180 r1 复审 P2-1：软件渲染那句**只有一条**，就挂在面板那一行（`PanelOpacityForcedHint`）
+            // 上——它挨着被禁用的滑块，正好回答「为什么拖不动」；这里不再有第二句。
+            SettingsAppearanceBgReadFailed => (
+                "Background image could not be read: {reason}",
+                "背景图读不出来：{reason}"
+            ),
+            SettingsAppearanceBgDecodeFailed => (
+                "Background image could not be decoded ({reason}; this build decodes PNG, JPEG and BMP)",
+                "背景图解不开（{reason}；这个构建只支持 PNG、JPEG 与 BMP）"
+            ),
+            SettingsAppearanceBgTooLarge => (
+                "Background image is too large to decode: {width}×{height} (limit {limit} px per edge)",
+                "背景图太大，解不开：{width}×{height}（每边上限 {limit} 像素）"
+            ),
+            SettingsAppearanceBgSmallTile => (
+                "Small image ({width}×{height}): tiles are scaled up so the window stays covered (max {max} tiles, no gaps).",
+                "图片很小（{width}×{height}）：图块会被放大，保证窗口铺满（最多 {max} 块，不留缝）。"
+            ),
+            // ---- M180：配色回落提示（`palette.rs` 把 design 的 `hint_key()` 翻成下面这些）
+            SettingsAppearancePaletteBgUndecodable => (
+                "Background image could not be read; colours fall back.",
+                "背景图读不出来，配色回落到下一级。"
+            ),
+            SettingsAppearancePaletteBgTooSmall => (
+                "Background image is too small to sample; colours fall back.",
+                "背景图太小，取不了色，配色回落到下一级。"
+            ),
+            SettingsAppearancePaletteBgBadDimensions => (
+                "Background image data looks inconsistent; colours fall back.",
+                "背景图数据前后不一致，配色回落到下一级。"
+            ),
+            SettingsAppearancePaletteBgNoOpaquePixels => (
+                "Background image is almost fully transparent; colours fall back.",
+                "背景图几乎全透明，配色回落到下一级。"
+            ),
+            SettingsAppearancePaletteBgLowChroma => (
+                "Background image is too monochrome to tint from; colours fall back.",
+                "背景图太单调（彩度不足），取不出配色，回落到下一级。"
+            ),
+            SettingsAppearancePaletteBgContrast => (
+                "Background image colours would be unreadable; colours fall back.",
+                "按背景图取的颜色读不清，配色回落到下一级。"
+            ),
+            SettingsAppearancePaletteWallpaperUndecodable => (
+                "Desktop wallpaper could not be read.",
+                "桌面壁纸读不出来。"
+            ),
+            SettingsAppearancePaletteWallpaperTooSmall => (
+                "Desktop wallpaper is too small to sample.",
+                "桌面壁纸太小，取不了色。"
+            ),
+            SettingsAppearancePaletteWallpaperBadDimensions => (
+                "Desktop wallpaper data looks inconsistent.",
+                "桌面壁纸数据前后不一致。"
+            ),
+            SettingsAppearancePaletteWallpaperNoOpaquePixels => (
+                "Desktop wallpaper is almost fully transparent.",
+                "桌面壁纸几乎全透明。"
+            ),
+            SettingsAppearancePaletteWallpaperLowChroma => (
+                "Desktop wallpaper is too monochrome to tint from.",
+                "桌面壁纸太单调（彩度不足），取不出配色。"
+            ),
+            SettingsAppearancePaletteWallpaperContrast => (
+                "Desktop wallpaper colours would be unreadable; colours fall back.",
+                "按桌面壁纸取的颜色读不清，配色回落到下一级。"
+            ),
+            SettingsAppearancePalettePresetContrast => (
+                "The built-in card needed a small contrast correction.",
+                "内置色卡做了一点对比度修正。"
+            ),
+            SettingsAppearancePaletteAdjusted => (
+                "A few colours were nudged for readability.",
+                "有几个颜色为了可读性做了微调。"
+            ),
+        } }
+    };
+}
+
+pub(crate) use settings_appearance_entries;
+
+#[cfg(test)]
+mod tests {
+    use crate::catalog::{placeholders, Catalog, Key};
+    use crate::Lang;
+
+    /// 本域的 key（`Key::ALL` 里按名字前缀筛；不手工列表，漏一条就少一条守卫）。
+    fn appearance_keys() -> Vec {
+        Key::ALL
+            .iter()
+            .copied()
+            .filter(|key| key.name().starts_with("SettingsAppearance"))
+            .collect()
+    }
+
+    /// 有没有汉字（与 `pages/settings/tests/appearance_section.rs` 的 `is_han` 同一段码位）。
+    fn is_han(ch: char) -> bool {
+        ('\u{4e00}'..='\u{9fff}').contains(&ch)
+    }
+
+    /// **M180 守门 ②**：外观分组的每条 key 都必须真翻过——英文照抄进中文表就地判红。
+    ///
+    /// 抓得住：① 新加 key 时中文栏直接抄英文（`chinese_catalog_is_actually_chinese` 也抓这条，
+    /// 但那条在 `catalog/tests.rs`、不属于本 mission 的 scope，而且不查「中文字里有没有汉字」）；
+    /// ② 中文译文变成纯 ASCII（比如只写了 `PNG` / `Preset` 这种专名）；③ 占位符集合两边不一致
+    /// （`{floor}` 只在一边有 ⇒ `render()` 吐出半截句子）。
+    /// 抓不住：译文翻得对不对（语义只能人审）。
+    ///
+    /// 变异证明：把任一条的第二个字符串换成第一个（`("Cover", "Cover")`）⇒ 本条立刻红（`assert_ne!`
+    /// 与 `is_han` 命中同一行）。
+    #[test]
+    fn every_appearance_key_is_translated_into_chinese() {
+        let keys = appearance_keys();
+        assert!(
+            keys.len() >= 40,
+            "外观分组至少 40 条 key（M180 落地时是 45 条），实际 {}：\
+             key 被搬走或前缀改名了？",
+            keys.len()
+        );
+
+        let en = Catalog::of(Lang::En);
+        let zh = Catalog::of(Lang::ZhCn);
+        for key in keys {
+            let (english, chinese) = (en.text(key), zh.text(key));
+            assert_ne!(english, chinese, "{} 的中文是英文照抄", key.name());
+            assert!(
+                chinese.chars().any(is_han),
+                "{} 的中文里一个汉字都没有：{chinese}",
+                key.name()
+            );
+            let mut left = placeholders(english);
+            let mut right = placeholders(chinese);
+            left.sort_unstable();
+            right.sort_unstable();
+            assert_eq!(left, right, "{} 的占位符两套译文不一致", key.name());
+        }
+    }
+
+    /// 数值参数必须走占位符，不许把常量写进译文（改常量时不该还要改两套译文）。
+    #[test]
+    fn numeric_limits_are_placeholders_not_text() {
+        let en = Catalog::of(Lang::En);
+        for (key, needle, placeholder) in [
+            (Key::SettingsAppearanceWindowOpacityHint, "0.08", "floor"),
+            (Key::SettingsAppearancePanelOpacityHint, "0.40", "floor"),
+            (Key::SettingsAppearanceBgDimHint, "0.95", "max"),
+            (Key::SettingsAppearanceBgTooLarge, "8192", "limit"),
+            (Key::SettingsAppearanceBgSmallTile, "64", "max"),
+        ] {
+            let text = en.text(key);
+            assert!(
+                !text.contains(needle),
+                "{} 把常量 {needle} 写死在译文里了（应当走 {{{placeholder}}}）",
+                key.name()
+            );
+            assert!(
+                placeholders(text).contains(&placeholder),
+                "{} 缺 {{{placeholder}}} 占位符：{text}",
+                key.name()
+            );
+        }
+    }
+}
diff --git a/crates/i18n/src/catalog/settings/download.rs b/crates/i18n/src/catalog/settings/download.rs
new file mode 100644
index 0000000..b6e5e00
--- /dev/null
+++ b/crates/i18n/src/catalog/settings/download.rs
@@ -0,0 +1,24 @@
+//! 设置页「Downloads」分组文案（M201 起有内容：这一组接了真控件）。
+//!
+//! 加 key 时把条目写进 `$($acc)*` 后面即可（形状见 [`crate::catalog`] 的「域装配」一节）。
+//! 本域在装配链里排在 `settings_java_entries` 之后、`settings_ai_entries` 之前，所以金表那几行
+//! 也落在 `SettingsJavaReasonInstallRootTooLong` 与 `SettingsGroupAssistant` 之间。
+//!
+//! ## 只有一条 key 的理由
+//!
+//! 下载组的**行文案**（`并发数` / `单源尝试次数` / 「原值 9999 已按出厂 8 生效」这些）不在这里：
+//! 它们由 presenter 按 schema 键现算（`dto::SettingRowView::label` / `description`），因为那些句子
+//! 里带着**生效值**——把数字搬进静态目录只会再长出一份会说谎的文案。这一域只放「页面自己的
+//! 按钮词」：提交文本框那一下的「应用」。
+
+macro_rules! settings_download_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* {
+            $($acc)*
+            // ── 文本行的提交按钮（`pages/settings/download.rs` 的 text 行）
+            SettingsDownloadsApply => ("Apply", "应用"),
+        } }
+    };
+}
+
+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..bfab316
--- /dev/null
+++ b/crates/i18n/src/catalog/settings/general.rs
@@ -0,0 +1,30 @@
+//! 设置页「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.",
+                "切换界面语言。显示中文需要中文字体。"
+            ),
+            // ── 日志文件夹（M188：用户投诉「找不到崩溃日志」的直接落点）
+            SettingsLogsFolder => ("Log folder", "日志文件夹"),
+            SettingsLogsFolderHint => (
+                "What explains a crash lives here: the launcher's own runtime log (launcher.log, rolled over at 1 MiB with one old copy kept) and one jsonl per game session under logs/game/. Sessions from older versions (data/agent/sessions) are still read, not moved.",
+                "解释一次崩溃要看的东西都在这：启动器自己的运行日志（launcher.log，满 1 MiB 滚动一次、只留一份旧档）与每次游戏会话的 jsonl（logs/game/）。旧版本留下的会话（data/agent/sessions）仍然读得出来，不会被搬动。"
+            ),
+            SettingsLogsCopy => ("Copy path", "复制路径"),
+            SettingsLogsUnknown => (
+                "Data directory not resolved — restart the launcher from its own folder",
+                "数据根没解析出来——从启动器所在目录重新启动试试"
+            ),
+        } }
+    };
+}
+
+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..4a47676
--- /dev/null
+++ b/crates/i18n/src/catalog/settings/java.rs
@@ -0,0 +1,323 @@
+//! 设置页「Java」分组文案（M175）：扫描 / 运行时列表 / 默认 JDK / 内存 / JVM 参数。
+//!
+//! 域文件的形状见 [`crate::catalog`] 的「域装配」一节。本域在装配链里排在
+//! `settings_appearance_entries` 之后、`settings_download_entries` 之前，所以金表那批行要插在
+//! `SettingsAppearanceCornerSuspended` 之后、`SettingsGroupAssistant`（M174 的助手域）之前
+//! ——**顺序即 `Key::ALL`**。
+//!
+//! 三条口径：
+//!
+//! 1. 技术名词不翻：`JDK` / `JVM` / `-version` / `bin/java` / `java.selected_path` 原样；
+//! 2. **不许出现写死的版本号或数字**：本组以前那三行（`Temurin 21.0.4` / `4 GiB`）正是被用户
+//!    当成假数据的那三条，现在所有数值都由页面从真读盘的结果里格式化进来；
+//! 3. 拒绝原因一句一条（空 / 不存在 / 不是 java / 跑不出 -version / 重复），合成一句
+//!    「路径无效」等于让用户自己猜。
+
+macro_rules! settings_java_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* {
+            $($acc)*
+            // ── 扫描（状态 / 进度 / 取消）
+            SettingsJavaScan => ("Scan now", "立即扫描"),
+            SettingsJavaScanningStart => ("Scanning…", "正在扫描…"),
+            SettingsJavaScanning => ("Scanning… {done}/{total}", "正在扫描… {done}/{total}"),
+            SettingsJavaCancelling => ("Cancelling…", "正在取消…"),
+            SettingsJavaCancel => ("Cancel", "取消"),
+            SettingsJavaCancelled => (
+                "The scan was cancelled; the list below is from the previous run.",
+                "扫描已取消；下面的列表还是上一次的结果。"
+            ),
+            SettingsJavaScanDone => ("{count} JDK found", "找到 {count} 个 JDK"),
+            SettingsJavaNeverScanned => ("Not scanned yet", "还没扫描过"),
+            SettingsJavaNeverScannedBody => (
+                "The list is still empty. The launcher scans once by itself when the settings page opens; press Scan now to look again right away.",
+                "列表还是空的。打开设置页时启动器会自己扫一次；也可以点「立即扫描」立刻再扫一遍。"
+            ),
+            SettingsJavaEmptyTitle => ("No Java runtime found", "未检测到 Java 运行时"),
+            SettingsJavaEmptyBody => (
+                "Nothing matched. Add the path of a JDK you already unpacked below, or install one with ull java install 21 on the command line.",
+                "没找到任何 JDK。可以在下面手动加上你自己解压的那份，或者用命令行 ull java install 21 装一个。"
+            ),
+            // ── 运行时列表
+            SettingsJavaDefault => ("Default", "默认"),
+            SettingsJavaSetDefault => ("Use as default", "设为默认"),
+            SettingsJavaFits => ("Meets the current instance requirement", "满足当前实例的要求"),
+            SettingsJavaTooOld => (
+                "Below the requirement: this instance needs Java {minimum}+",
+                "低于要求：当前实例需要 Java {minimum} 及以上"
+            ),
+            SettingsJavaDefaultSet => ("Default JDK is now {path}", "默认 JDK 已设为 {path}"),
+            SettingsJavaSourceManaged => ("installed by this launcher", "本启动器安装"),
+            SettingsJavaSourceEnv => ("JAVA_HOME (environment variable)", "JAVA_HOME（环境变量）"),
+            SettingsJavaSourcePath => ("on PATH", "PATH 上"),
+            SettingsJavaSourceSystem => ("system install", "系统安装"),
+            SettingsJavaSourceManual => ("added by you", "手动添加"),
+            // ── 手动添加
+            SettingsJavaAdd => ("Add a JDK path", "手动添加 JDK 路径"),
+            SettingsJavaAddPlaceholder => (
+                "C:\\Program Files\\Java\\jdk-21",
+                "例：C:\\Program Files\\Java\\jdk-21"
+            ),
+            SettingsJavaAddHint => (
+                "A JDK folder or its java executable. We run java -version on it; anything that cannot answer is refused.",
+                "JDK 目录或它的 java 可执行文件。会真跑一次 java -version；答不出话的一律拒绝。"
+            ),
+            SettingsJavaAddAction => ("Add", "添加"),
+            SettingsJavaAdded => ("Added {path}", "已添加 {path}"),
+            // ── 内存
+            SettingsJavaMemory => ("Default memory (MB)", "默认内存（MB）"),
+            SettingsJavaMemoryHint => (
+                "Whole megabytes, {min}–{max}. Instances without their own override follow this value.",
+                "整数 MB，范围 {min}~{max}。没有实例级覆盖的实例都用它。"
+            ),
+            SettingsJavaLayerGlobal => (
+                "In effect: {mb} MB, from the global default.",
+                "生效：{mb} MB，来自全局默认值。"
+            ),
+            SettingsJavaLayerInstance => (
+                "In effect: {mb} MB, set by instance {instance}. Changing the global value below will not affect that instance.",
+                "生效：{mb} MB，由实例 {instance} 覆盖。改下面的全局值不会影响它。"
+            ),
+            // ── JVM 参数
+            SettingsJavaJvm => ("Extra JVM arguments", "额外 JVM 参数"),
+            SettingsJavaJvmPlaceholder => ("-XX:+UseG1GC -Dfile.encoding=UTF-8", "例：-XX:+UseG1GC -Dfile.encoding=UTF-8"),
+            SettingsJavaJvmHint => (
+                "Separated by spaces, quotes allowed. Appended to the command line of every launch; an instance's own JVM arguments come after it.",
+                "按空白分隔，支持引号。会拼到每次启动的命令行上；实例自己的 JVM 参数排在它后面。"
+            ),
+            SettingsJavaJvmSaved => ("Saved value: {value}", "已保存的值：{value}"),
+            SettingsJavaJvmSavedNone => (
+                "No extra JVM arguments are saved yet.",
+                "还没有保存任何额外参数。"
+            ),
+            // ── 保存与回执
+            SettingsJavaSave => ("Save", "保存"),
+            SettingsJavaSaved => (
+                "Saved and read back from disk. The next launch uses the new value.",
+                "已保存，并从磁盘读回确认。下次启动就用新值。"
+            ),
+            SettingsJavaUnsaved => ("There are unsaved changes.", "有未保存的改动。"),
+            SettingsJavaRefused => ("Not saved: {reason}", "未保存：{reason}"),
+            SettingsJavaSkipNotDirty => (
+                "there was nothing to change, so no file was written",
+                "没有任何改动，因此没有写文件"
+            ),
+            SettingsJavaSkipReadOnly => (
+                "the settings file is read-only: a newer launcher wrote it, or it is marked untrusted",
+                "配置文件只读：它被更新版本的启动器写过，或被标记为不可信"
+            ),
+            SettingsJavaSkipUnreadable => (
+                "the settings file is untrusted, so it is treated as read-only",
+                "配置文件不可信，因此按只读处理"
+            ),
+            SettingsJavaNoStorage => (
+                "No settings file is available in this run, so nothing can be scanned or saved.",
+                "这一次运行没有可用的设置文件，扫描与保存都做不了。"
+            ),
+            // ── 拒绝原因（一条一句）
+            SettingsJavaReasonMemoryEmpty => ("the memory field is empty", "内存没填"),
+            SettingsJavaReasonMemoryNotNumber => ("the memory must be a whole number of MB", "内存必须是整数 MB"),
+            SettingsJavaReasonMemoryRange => (
+                "the memory is outside the allowed range",
+                "内存超出允许范围"
+            ),
+            SettingsJavaReasonJvmQuotes => (
+                "the JVM arguments have an unclosed quote",
+                "JVM 参数里有没配对的引号"
+            ),
+            SettingsJavaReasonJvmTooLong => (
+                "the JVM arguments are longer than the settings file allows (1024 characters)",
+                "JVM 参数超过配置文件允许的长度（1024 字符）"
+            ),
+            SettingsJavaReasonAddEmpty => ("the path is empty", "路径是空的"),
+            SettingsJavaReasonAddMissing => ("nothing exists at that path", "那个路径上什么都没有"),
+            SettingsJavaReasonAddNotJava => (
+                "there is no java executable at that path",
+                "那个路径里没有 java 可执行文件"
+            ),
+            SettingsJavaReasonAddNoVersion => (
+                "java -version did not answer there, so it is not a usable JDK",
+                "在那里跑不出 java -version，不是一份能用的 JDK"
+            ),
+            SettingsJavaReasonAddTooLong => (
+                "the path is too long to be a JDK location",
+                "路径太长，不像是一个 JDK 位置"
+            ),
+            SettingsJavaReasonAddWriteFailed => (
+                "the JDK is fine, but the list file could not be written (disk or permission)",
+                "这份 JDK 没问题，但名单文件写不进去（磁盘或权限）"
+            ),
+            SettingsJavaReasonAddDuplicate => ("that JDK is already in the list", "这份 JDK 已经在列表里了"),
+            SettingsJavaReasonWriteFailed => (
+                "the settings file could not be written (disk full, no permission, or the value was rejected)",
+                "设置写不进去（磁盘满、没权限，或这个值被拒绝）"
+            ),
+            // ── M197：版本与实例要求的匹配（两向）
+            SettingsJavaTooNew => (
+                "Above the requirement: this instance can only use Java {maximum} or older (the old loader cannot read newer class files)",
+                "高于要求：当前实例只能用 Java {maximum} 及以下（老加载器吃不了新 class 文件）"
+            ),
+            // ── M197：下载一个 JDK（版本目录 / 下载中 / 失败三态）
+            SettingsJavaDownloadTitle => ("Download a JDK", "下载一个 JDK"),
+            SettingsJavaDownloadHint => (
+                "Downloads go through the built-in mirror table: in China the campus mirrors are tried first (Temurin over Tsinghua TUNA), and GitHub-hosted archives are fetched through gh-proxy. Every archive is verified against its SHA-256 before it is unpacked.",
+                "下载走内置镜像表：国内先试院校镜像（Temurin 走清华 TUNA），GitHub 上的归档套 gh-proxy。落盘前一律按 SHA-256 校验。"
+            ),
+            SettingsJavaDownloadLts => ("LTS", "长期支持版（LTS）"),
+            SettingsJavaDownloadBaseline => ("Recommended baseline", "推荐基准版本"),
+            SettingsJavaDownloadVendors => ("Vendors: {vendors}", "发行版：{vendors}"),
+            SettingsJavaDownloadNoVendor => (
+                "No vendor publishes this major version on this platform.",
+                "这个平台上没有发行版发这个大版本。"
+            ),
+            SettingsJavaDownloadAction => ("Install", "安装"),
+            SettingsJavaDownloadReinstall => ("Install again", "重装"),
+            SettingsJavaDownloadInstalled => ("Already installed: {path}", "已安装：{path}"),
+            SettingsJavaDownloadNeeded => (
+                "The current instance needs {requirement}.",
+                "当前实例需要 {requirement}。"
+            ),
+            SettingsJavaDownloadFits => (
+                "Usable by the current instance",
+                "当前实例可用"
+            ),
+            SettingsJavaDownloadTooLow => (
+                "The current instance needs Java {minimum} or newer, so installing this one will not start it.",
+                "当前实例需要 Java {minimum} 及以上 —— 装这一档也起不来。"
+            ),
+            SettingsJavaDownloadTooHigh => (
+                "The current instance can only use Java {maximum} or older, so installing this one will not start it.",
+                "当前实例只能用 Java {maximum} 及以下 —— 装这一档也起不来。"
+            ),
+            SettingsJavaDownloadRecommended => (
+                "Recommended for the current instance",
+                "为当前实例推荐这一档"
+            ),
+            SettingsJavaDownloadBusy => ("Installing Java {major}…", "正在安装 Java {major}…"),
+            SettingsJavaDownloadPhasePreparing => ("Looking up the release…", "正在查版本…"),
+            SettingsJavaDownloadPhaseDownloading => (
+                "Downloading {percent}% ({done} of {total})",
+                "下载中 {percent}%（{done} / {total}）"
+            ),
+            SettingsJavaDownloadPhaseVerifying => ("Verifying the archive…", "正在校验归档…"),
+            SettingsJavaDownloadPhaseExtracting => ("Unpacking…", "正在解压…"),
+            SettingsJavaDownloadSource => ("Source: {source}", "来源：{source}"),
+            SettingsJavaDownloadRetry => (
+                "{source} failed ({reason}); retry {attempt} in {seconds}s",
+                "{source} 失败（{reason}）；{seconds} 秒后重试第 {attempt} 次"
+            ),
+            SettingsJavaDownloadSwitch => ("Switching source: {from} → {to}", "换源：{from} → {to}"),
+            SettingsJavaDownloadDone => (
+                "Java {major} ({vendor}) is ready at {root} · source {source}",
+                "Java {major}（{vendor}）已就绪：{root} · 来源 {source}"
+            ),
+            SettingsJavaDownloadDoneReused => (
+                "Java {major} ({vendor}) was already installed at {root}; nothing was downloaded.",
+                "Java {major}（{vendor}）之前已经装好：{root}，这一次没有下载。"
+            ),
+            SettingsJavaDownloadFailed => (
+                "Java {major} could not be installed; the last source tried was {source}. The full reason is in the log.",
+                "Java {major} 没装成；最后试到的源是 {source}。完整原因在日志里。"
+            ),
+            SettingsJavaDownloadFailedNoSource => (
+                "Java {major} could not be installed: the version lookup itself failed. The full reason is in the log.",
+                "Java {major} 没装成：查版本这一步就失败了。完整原因在日志里。"
+            ),
+            SettingsJavaDownloadFailedHint => (
+                "Check the network, or change the vendor order below.",
+                "先查网络，或者改下面的发行版顺序。"
+            ),
+            SettingsJavaDownloadTriedHeader => ("Sources tried:", "试过的源："),
+            SettingsJavaDownloadTried => ("{source}: {reason}", "{source}：{reason}"),
+            SettingsJavaDownloadRefused => ("Not started: {reason}", "没开始：{reason}"),
+            SettingsJavaReasonDownloadBusy => (
+                "another JDK install is already running",
+                "已经有一个 JDK 在装了"
+            ),
+            SettingsJavaReasonDownloadUnknownMajor => (
+                "that major version is not in the catalog",
+                "目录里没有这个大版本"
+            ),
+            SettingsJavaReasonDownloadNoVendor => (
+                "no vendor publishes that major version here",
+                "没有发行版在这里发这个大版本"
+            ),
+            SettingsJavaReasonRootUnresolved => (
+                "the JDK install folder cannot be resolved on this system",
+                "这台机器上解析不出 JDK 安装目录"
+            ),
+            // ── 源失败原因（结构化，`DownloadErrorKind` 的文案面；core 的原句只进日志）
+            SettingsJavaSourceReasonNotFound => (
+                "this mirror does not have that file (404)",
+                "这个镜像没有这个文件（404）"
+            ),
+            SettingsJavaSourceReasonServer => (
+                "the server answered with a 5xx / 429 error",
+                "服务器报错 5xx / 429"
+            ),
+            SettingsJavaSourceReasonTimeout => ("the request timed out", "请求超时"),
+            SettingsJavaSourceReasonNetwork => ("the connection failed", "连不上"),
+            SettingsJavaSourceReasonIntegrity => ("the checksum did not match", "校验不符"),
+            SettingsJavaSourceReasonIo => ("a local disk error", "本地磁盘错误"),
+            SettingsJavaSourceReasonOther => ("the request was rejected", "请求被拒"),
+            // ── M197：三个设置键（`java.installRoot` / `java.vendorPriority` / `java.auto_install`）
+            SettingsJavaInstallRoot => ("JDK install folder", "JDK 安装目录"),
+            SettingsJavaInstallRootPlaceholder => ("D:\\Java", "例：D:\\Java"),
+            SettingsJavaInstallRootHint => (
+                "Leave it empty to follow the data mode: portable keeps JDKs inside the launcher folder, standard uses the system Java folder. A path here overrides both, and JDKs land in ///.",
+                "留空 = 跟数据目录模式走：portable 放在启动器目录里，standard 放在系统 Java 目录。填了它覆盖前两者，JDK 落在 /<发行方>/<版本>/。"
+            ),
+            SettingsJavaInstallRootEffective => ("In effect: {mode} · {path}", "生效：{mode} · {path}"),
+            SettingsJavaInstallRootLayerSetting => (
+                "this comes from java.installRoot",
+                "这一项来自 java.installRoot"
+            ),
+            SettingsJavaInstallRootLayerDataMode => (
+                "this comes from core.data_mode ({mode})",
+                "这一项来自 core.data_mode（{mode}）"
+            ),
+            SettingsJavaInstallRootUnresolved => (
+                "The system Java folder cannot be resolved here. Type a folder above, or set core.data_mode back to portable.",
+                "这台机器上解析不出系统标准 Java 目录。在上面填一个目录，或把 core.data_mode 改回 portable。"
+            ),
+            SettingsJavaVendorPriority => ("Vendor order", "发行版顺序"),
+            SettingsJavaVendorOrderEffective => ("In effect: {order}", "生效顺序：{order}"),
+            SettingsJavaVendorOrderLayerSetting => (
+                "this comes from java.vendorPriority",
+                "这一项来自 java.vendorPriority"
+            ),
+            SettingsJavaVendorOrderLayerRegion => (
+                "this comes from the built-in order for your region ({region})",
+                "这一项来自内置的地区默认序（{region}）"
+            ),
+            SettingsJavaRegionDomestic => ("China", "国内"),
+            SettingsJavaRegionGlobal => ("rest of the world", "国外"),
+            SettingsJavaVendorUp => ("Up", "上移"),
+            SettingsJavaVendorDown => ("Down", "下移"),
+            SettingsJavaVendorReset => ("Reset to the region default", "恢复地区默认序"),
+            SettingsJavaVendorSupports => ("ships {majors}", "发 {majors}"),
+            SettingsJavaAutoInstall => ("Recommend a JDK when none is found", "缺 JDK 时推荐一档"),
+            SettingsJavaAutoInstallHint => (
+                "On: the catalog below marks the version the current instance needs, and a freshly installed JDK becomes the default when no default is set yet. Nothing is downloaded on its own — you press Install. Off: nothing is marked and you pick everything yourself.",
+                "开：下面的目录会按当前实例的要求标出该装哪一档，装完之后若还没有默认 JDK 就自动设为默认。不会自己开始下载 —— 点「安装」才会下。关：什么也不标，全部自己挑。"
+            ),
+            SettingsJavaAutoInstallOn => ("on", "开"),
+            SettingsJavaAutoInstallOff => ("off", "关"),
+            SettingsJavaPrefsSave => ("Save", "保存"),
+            SettingsJavaPrefsSaved => (
+                "Saved and read back from disk: all three keys are in the settings file.",
+                "已保存并从磁盘读回：三个键都进配置文件了。"
+            ),
+            SettingsJavaPrefsUnsaved => (
+                "There are unsaved changes in this section.",
+                "这一段有未保存的改动。"
+            ),
+            SettingsJavaReasonInstallRootTooLong => (
+                "the folder path is too long",
+                "目录路径太长"
+            ),
+        } }
+    };
+}
+
+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..9085834
--- /dev/null
+++ b/crates/i18n/src/catalog/settings/mod.rs
@@ -0,0 +1,31 @@
+//! 设置页文案：**一个分组一个文件**，与页面侧的 `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（语言） |
+//! | [`accent`] | Appearance 组的**强调色**一族（M250） | 7 条 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 accent;
+mod ai;
+mod appearance;
+mod download;
+mod general;
+mod java;
+
+pub(crate) use accent::settings_accent_entries;
+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..db2874f
--- /dev/null
+++ b/crates/i18n/src/catalog/tests.rs
@@ -0,0 +1,252 @@
+//! `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::>();
+        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::>();
+    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::>();
+
+    assert_eq!(
+        actual.len(),
+        super::golden::len(),
+        "key 条数与拆分前不一致（某条被搬丢，或多出来一条）"
+    );
+
+    for (index, expected) in super::golden::rows().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);
+    }
+}
+
+/// 用户可见文案里**不许**出现内部决策编号（`(D13)` / `(M175)` 这类）。
+///
+/// 为什么要在目录这一层守：`(D13)` 对用户没有任何意义（他不知道 D13 是什么），而这类串一旦
+/// 混进来就再没人记得删。M197 出图时实测到下载目录的基准版本徽标写着 `基准版本（D13）`。
+///
+/// 变异证明：把 `SettingsJavaDownloadBaseline` 的译文改回 `Baseline (D13)` / `基准版本（D13）`
+/// ⇒ 本用例红（中英两侧都扫）。判据是 `(`/`（` + `D`/`M` + 数字，不误伤 `(404)` / `(5xx / 429)`
+/// 这类真对用户有意义的括号短语。
+#[test]
+fn no_user_visible_string_mentions_an_internal_decision_id() {
+    for (key, en, zh) in super::golden::rows().copied() {
+        for (side, text) in [("en", en), ("zh-CN", zh)] {
+            assert!(
+                !mentions_decision_id(text),
+                "{key} 的{side}译文里出现了内部决策编号：{text}"
+            );
+        }
+    }
+}
+
+/// 用户可见文案里**不许**出现 markdown 反引号。
+///
+/// 渲染层没有内联代码通道（M175 r3 复审已核实 `RichText|markdown|Span::|spans(` 全树只命中
+/// 进度条与注释），反引号会原样上屏。M175 修过三处、M197 又修了三处；M168 的
+/// `FontCjkStatusHint` 是最后一条（M197 复审 r1 指出的），这里一并钉住。
+///
+/// 变异证明：给任意一条译文加一对反引号 ⇒ 本用例红。
+#[test]
+fn no_user_visible_string_carries_markdown_backticks() {
+    for (key, en, zh) in super::golden::rows().copied() {
+        for (side, text) in [("en", en), ("zh-CN", zh)] {
+            assert!(
+                !text.contains('`'),
+                "{key} 的{side}译文里还有 markdown 反引号：{text}"
+            );
+        }
+    }
+}
+
+/// 串里有没有「(D13)」「（M175）」这类内部编号（全角半角括号都算）。
+fn mentions_decision_id(text: &str) -> bool {
+    let chars: Vec = text.chars().collect();
+    chars.windows(3).any(|window| {
+        (window[0] == '(' || window[0] == '（')
+            && (window[1] == 'D' || window[1] == 'M')
+            && window[2].is_ascii_digit()
+    })
+}
diff --git a/crates/i18n/src/catalog/update.rs b/crates/i18n/src/catalog/update.rs
new file mode 100644
index 0000000..d513d15
--- /dev/null
+++ b/crates/i18n/src/catalog/update.rs
@@ -0,0 +1,59 @@
+//! 自更新文案（M159）：设置页「更新」分组 + 顶部提示条。
+//!
+//! 域文件的形状见 [`crate::catalog`] 的「域装配」一节；本域**追加在链尾**（`account_entries`
+//! 之后），于是 `Key::ALL` 顺序 = 金表顺序 = 先 main 的全部域，最后 update（金表只追加不重排）。
+//!
+//! 三条口径：
+//!
+//! 1. **「检查失败」与「已是最新」是两句不同的文案**（mission 的硬要求）：前者带原因，
+//!    后者带版本号。别为了少一个 key 把它们合并成一条；
+//! 2. 体积走 `{size}`（由页面按 `human_bytes` 格式化后传入），版本号走 `{version}`——
+//!    目录里不写死任何版本号；
+//! 3. 品牌/技术名词不翻：`OpenGL` / `SHA256` / `GitHub` 这类保持原样。
+
+macro_rules! update_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* {
+            $($acc)*
+            // ── 设置页「更新」分组
+            SettingsGroupUpdate => ("Updates", "更新"),
+            SettingsUpdateCurrent => ("Current version", "当前版本"),
+            SettingsUpdateChannel => ("Channel", "更新渠道"),
+            SettingsUpdateChannelStable => ("Stable", "稳定版"),
+            SettingsUpdateAutoCheck => ("Check for updates on startup", "启动时检查更新"),
+            SettingsUpdateCheckNow => ("Check now", "立即检查"),
+            SettingsUpdateChecking => ("Checking…", "正在检查…"),
+            SettingsUpdateNever => ("Not checked yet", "还没检查过"),
+            SettingsUpdateUpToDate => ("You are on the latest version ({version})", "已是最新（{version}）"),
+            SettingsUpdateAvailable => ("Version {version} is available ({size})", "有新版本 {version}（{size}）"),
+            SettingsUpdateMissingArtifact => (
+                "Version {version} is out, but there is no build for this platform yet.",
+                "{version} 已发布，但还没有本平台的安装包。"
+            ),
+            SettingsUpdateFailed => ("Check failed: {reason}", "检查失败：{reason}"),
+            SettingsUpdateApply => ("Download and install", "下载并安装"),
+            SettingsUpdateApplying => ("Downloading and verifying…", "正在下载并校验…"),
+            SettingsUpdateReady => ("Version {version} is ready — restart to use it.", "版本 {version} 已就位，重启后生效。"),
+            SettingsUpdateNotes => ("Release notes: {notes}", "更新说明：{notes}"),
+            SettingsUpdateForced => ("This update is required", "这是一次强制更新"),
+            SettingsUpdateLastChecked => ("Last check", "上次检查"),
+            SettingsUpdateHint => (
+                "Downloads are verified with SHA256 before they touch the launcher. The running copy stays as it is until you restart.",
+                "更新包在落到启动器之前会做 SHA256 校验；正在运行的这一份在你重启之前不会变。"
+            ),
+            // ── 顶部提示条
+            UpdateBannerTitleAvailable => ("Version {version} is available", "发现新版本 {version}"),
+            UpdateBannerBodyAvailable => ("Download size {size}", "下载体积 {size}"),
+            UpdateBannerTitleReady => ("Update ready", "更新已就位"),
+            UpdateBannerBodyReady => ("Version {version} will run after a restart.", "重启后运行版本 {version}。"),
+            UpdateBannerTitleFailed => ("Update failed", "更新失败"),
+            UpdateBannerApplying => ("Downloading the update…", "正在下载更新…"),
+            UpdateBannerInstall => ("Download and install", "下载并安装"),
+            UpdateBannerDismiss => ("Skip this version", "忽略这个版本"),
+            UpdateBannerRestartNow => ("Restart now", "立即重启"),
+            UpdateBannerRetry => ("Try again", "重试"),
+        } }
+    };
+}
+
+pub(crate) use update_entries;
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`：`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 {
+                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, ®istry_zh, &env_zh, Lang::En, ORIGIN_SETTING),
+            (zh, ®istry_en, &env_en, Lang::ZhCn, ORIGIN_SETTING),
+            // ② 跟随系统 → 系统源
+            (follow, ®istry_zh, &env_en, Lang::ZhCn, "registry"),
+            (follow, ®istry_en, &env_zh, Lang::En, "registry"),
+            // ③ 系统源取不到 → 环境变量
+            (follow, ¬hing, &env_zh, Lang::ZhCn, "env"),
+            (follow, ¬hing, &env_en, Lang::En, "env"),
+            // ④ 都没有 → 英文 + default（D28：纯英文环境不用管）
+            (follow, ¬hing, &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(®istry_en, &env_en).describe(),
+            "lang=zh-CN locale=zh_cn source=setting"
+        );
+        assert_eq!(
+            follow.resolve(®istry_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..634238a
--- /dev/null
+++ b/crates/i18n/src/font.rs
@@ -0,0 +1,278 @@
+//! 中文字体策略（D28 后半）：**只做判据与「该下载什么」，不联网**。
+//!
+//! ## 三句话
+//!
+//! 1. **英文环境不要字体**：`Lang::En` → [`Strategy::NotNeeded`]，与系统里装了什么无关。
+//!    D28 原话是「纯英文环境不用管（零额外体积/零网络）」，这条是本模块最重要的断言。
+//! 2. **中文环境先扫系统**：候选族名单见 [`CJK_FAMILIES`]，命中即用（[`Strategy::System`]）。
+//! 3. **扫不到才说要下载**：[`Strategy::NeedsDownload`] 是一个**信号**，不是动作——
+//!    真正下载由注入的 [`Fetcher`] 实现（M168 起的真实现是
+//!    `crates/app-iced/src/fonts/cdn.rs`，底层走 `unlucky_core::download::font`）。本 crate 保持
+//!    **零依赖**：它只携带「下什么」（[`Source::Pinned`]：URL 候选 + sha256 + 字节数），不碰网络。
+//!
+//! ## 谁在什么时刻问这里
+//!
+//! | 调用点 | 时机 | 后果 |
+//! |---|---|---|
+//! | `crates/app-iced/src/fonts.rs::resolve` | 启动（按系统 locale） | 打一行 `cjk=…` 日志 |
+//! | `crates/app-iced/src/fonts.rs::cjk_for` | 设置页切语言 | 复算 + 需要时**触发下载** |
+//!
+//! 两条路都**只**在 [`Strategy::NeedsDownload`] 时才碰 [`Fetcher`]（[`ensure`] 的判据），
+//! 英文环境与「系统已有字体」两条路一次网络调用都没有（守卫见本文件的单测与
+//! `crates/app-iced/src/fonts/install/tests.rs`）。
+//!
+//! ## 诚实边界（抓得住什么 / 抓不住什么）
+//!
+//! - **抓得住**：语言 → 是否需要中文 → 系统里有没有候选族 → 要不要下载 这条链路的判定；
+//! - **抓不住**：①**族名存在 ≠ 字形覆盖**——`fontdb` 里挂着一个叫 `SimSun` 的族也可能是个残缺子集，
+//!   真判据要用 `ttf-parser` 查 cmap（M60 Q3 的 spike 做过，本 crate 不引依赖）；
+//!   ②下载下来的字节能不能在**这台机器**的渲染器上正常出字（注册与回退在 app-iced；macOS/Linux
+//!   没有真机验证，见 M168 报告）。
+
+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];
+
+/// 可下载字体的来源：**已钉死**的 URL 候选 + `sha256` + 字节数。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Source {
+    /// 钉死的一套下载参数（M168）。
+    ///
+    /// 为什么是「常量 + 多重校验」而不是「让下载器自己挑」：CDN 上的字节会变（上游改字体、
+    /// 镜像换了实现），而**字体是注册进渲染器的可执行内容**。所以 URL 钉到 **git commit**
+    /// （不是 `@main`）、字节数与 `sha256` 一起钉，任何一项对不上就拒绝落盘（见
+    /// `unlucky_core::download::font`）。
+    ///
+    /// `urls` 是**候选**：首选挂了才试下一个。两个候选**必须是不同的失败域**（Cloudflare 侧 +
+    /// Fastly 侧，见 [`NOTO_SANS_SC`] 的实测表）；同一家 CDN 的两个域名不算冗余。
+    ///
+    /// 每次尝试与整条取回都有整体时限（`unlucky_core::download::font` 的 `ATTEMPT_DEADLINE` /
+    /// `TOTAL_DEADLINE`）：慢而不死的连接（IPv6 爬行实测 67 KB/s）会在时限处被打断、转下一个
+    /// 候选，而不是让用户在设置页干等四分钟。超时归「网络」档，界面文案是「网络不通或太慢」。
+    Pinned {
+        /// URL 候选（按顺序尝试）。
+        urls: &'static [&'static str],
+        /// 期望 `sha256`（小写十六进制，64 位）。
+        sha256: &'static str,
+        /// 期望字节数（进度预算 + 大小上限判据）。
+        bytes: u64,
+    },
+}
+
+/// 一套可下载的 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],
+    /// 下载源（URL 候选 + sha256 + 字节数，见 [`Source::Pinned`]）。
+    pub source: Source,
+}
+
+/// 缺字体时的默认方案：Noto Sans SC（OFL-1.1）**可变字体**（wght 100–900，整个简体字符集）。
+///
+/// 钉死的东西（M168 实测抓的，不是猜的）：
+///
+/// | 项 | 值 |
+/// |---|---|
+/// | 上游 | `google/fonts` 仓库的 `ofl/notosanssc/NotoSansSC[wght].ttf` |
+/// | 版本 | commit `2894aab31764f10f29c421bdfd2340d3b382d384`（该文件的最后一次改动，2022-12-09） |
+/// | 字节数 | 17 772 300（16.95 MiB） |
+/// | sha256 | `a3041811a78c361b1de50f953c805e0244951c21c5bd412f7232ef0d899af0da` |
+///
+/// 为什么钉 commit 而不是 `@main`：`@main` 会随上游改动漂移，哈希一漂就成了「每次中文环境都下
+/// 一份、然后校验失败、然后降级」——比不下更糟。commit 是不变内容，哈希因此是可复现的判据。
+///
+/// 为什么是**一个**可变字体而不是三个静态子集（400/500/700 各一份）：三份静态子集合计 ≈25 MiB，
+/// 而可变字体一份 16.9 MiB 就覆盖 100–900（cosmic-text 0.15 会把请求的字重写进 `wght` 轴，见
+/// `crates/core/src/download/font.rs` 模块文档与 M168 报告里的「抓不住」一段）。
+pub const NOTO_SANS_SC: CjkFont = CjkFont {
+    family: "Noto Sans SC",
+    license: "OFL-1.1",
+    weights: &[100, 200, 300, 400, 500, 600, 700, 800, 900],
+    source: Source::Pinned {
+        // 两个候选**必须是不同的失败域**（M168 复审 P2-1）：`cdn.jsdelivr.net` 与
+        // `fastly.jsdelivr.net` 都 CNAME 到 `jsdelivr.map.fastly.net`（同一批 Fastly 边缘），
+        // 「一个坏了换另一个」等于没有冗余——上一版就是这样，被复审当场打掉。
+        //
+        // 实测（两份独立的国内网络取证，同一份 17 772 300 B 内容，sha256 都是 a3041811…）：
+        //
+        // | 域名 | 解析 | 本机（本 worktree 开发机） | 复审机（无代理） |
+        // |---|---|---|---|
+        // | gcore.jsdelivr.net | Cloudflare 104.16.x | 13.3 s 完整 | 16.6 s 完整 |
+        // | testingcf.jsdelivr.net | Cloudflare 104.16.x | 11.8 s 完整 | 14.8 s 完整 |
+        // | cdn.jsdelivr.net | Fastly 151.101.x | 11.9 s 完整（另两次 5.7 s / 14.9 s）| 1.1 s，但**走 IPv6 时 3 次都掉到 ≈67 KB/s**（60 s 只到 4.0 MB）|
+        // | fastly.jsdelivr.net | 同上（Fastly）| — | 20 s 只到 2.5 MB（比它「要备的那条」还慢）|
+        //
+        // 排序依据（不是「听说更稳」）：**首选放 Cloudflare 那一侧**——Fastly 侧的 IPv6 边缘
+        // 在复审环境里会掉进 60~77 KB/s 的慢路径（那条路上 17.7 MB 要 ≈4 分钟），而 Cloudflare
+        // 侧两份取证都完整下完、且是独立的失败域。二选留 Fastly 侧：本机它反而最快（5.7~11.9 s），
+        // 保留它是为了「Cloudflare 一侧整体不可用时还有另一家 CDN」。
+        // 先后只影响速度，不影响正确性：sha256 只认一份，镜像给了别的内容会被当场拒。
+        urls: &[
+            "https://gcore.jsdelivr.net/gh/google/fonts@2894aab31764f10f29c421bdfd2340d3b382d384/ofl/notosanssc/NotoSansSC%5Bwght%5D.ttf",
+            "https://cdn.jsdelivr.net/gh/google/fonts@2894aab31764f10f29c421bdfd2340d3b382d384/ofl/notosanssc/NotoSansSC%5Bwght%5D.ttf",
+        ],
+        sha256: "a3041811a78c361b1de50f953c805e0244951c21c5bd412f7232ef0d899af0da",
+        bytes: 17_772_300,
+    },
+};
+
+/// 字体策略结论。
+#[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 }
+        })
+}
+
+/// 字体下载器接口（**注入式**：i18n 不碰网络，真实现由 app 层提供）。
+pub trait Fetcher {
+    /// 取一套字体（返回原始字节，装进字体系统是调用方的事）。
+    ///
+    /// 契约：**同一个进程里第二次调用应当零网络**（缓存命中），且返回的字节已通过校验
+    /// （实现方的责任，见 `unlucky_core::download::font`）。
+    ///
+    /// # Errors
+    /// 网络失败 / 校验失败 / 磁盘失败三类人话错误。
+    fn fetch(&self, font: &'static CjkFont) -> Result, FetchError>;
+}
+
+/// 下载失败的分类（给 UI 决定要不要重试；分类少是故意的）。
+///
+/// 三类对应三句不同的话：网络类「过会儿再试」、校验类「这个源给的东西不对」、磁盘类
+/// 「腾点空间」。UI 文案按 [`FetchError::class`] 选词，**不要**按错误串猜。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum FetchError {
+    /// 网络层失败（超时 / 连不上 / 非 2xx）。
+    Network(String),
+    /// 校验失败（哈希 / 长度不符，或不是字体文件）。
+    Integrity(String),
+    /// 本地磁盘失败（建目录 / 写文件 / 换名）。
+    Disk(String),
+}
+
+impl FetchError {
+    /// 稳定类别名（`network` / `integrity` / `disk`；日志与 i18n 金表按它选词）。
+    #[must_use]
+    pub const fn class(&self) -> &'static str {
+        match self {
+            Self::Network(_) => "network",
+            Self::Integrity(_) => "integrity",
+            Self::Disk(_) => "disk",
+        }
+    }
+
+    /// 人类可读描述。
+    #[must_use]
+    pub fn message(&self) -> &str {
+        match self {
+            Self::Network(message) | Self::Integrity(message) | Self::Disk(message) => message,
+        }
+    }
+}
+
+/// [`ensure`] 的结局。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Fetched {
+    /// 本来就不需要（英文环境）。
+    NothingToDo,
+    /// 系统已有，直接用。
+    AlreadySystem {
+        /// 命中的族名。
+        family: &'static str,
+    },
+    /// 下载成功，拿到字节（交给调用方注册）。
+    Downloaded(Vec),
+    /// 探测不出，什么都没做。
+    Unknown,
+}
+
+/// 按策略执行：需要下载时才碰 [`Fetcher`]。
+///
+/// # Errors
+/// 下载器返回的错误原样透出（不吞、不改写分类）。
+pub fn ensure(strategy: Strategy, fetcher: &dyn Fetcher) -> Result {
+    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)]
+#[path = "font/tests.rs"]
+mod tests;
diff --git a/crates/i18n/src/font/tests.rs b/crates/i18n/src/font/tests.rs
new file mode 100644
index 0000000..db52bfc
--- /dev/null
+++ b/crates/i18n/src/font/tests.rs
@@ -0,0 +1,177 @@
+//! `i18n::font` 的单测（拆出来只为守 400 行硬线）。
+
+use std::cell::Cell;
+
+use super::*;
+
+fn only(installed: &'static [&'static str]) -> impl Fn(&str) -> bool {
+    move |family| installed.contains(&family)
+}
+
+/// 假下载器：记录调用次数，避免「悄悄联网」这种事在单测里被放过。
+struct FakeFetcher {
+    calls: Cell,
+    result: Result, FetchError>,
+    seen: Cell>,
+}
+
+impl FakeFetcher {
+    fn new(result: Result, FetchError>) -> Self {
+        FakeFetcher {
+            calls: Cell::new(0),
+            result,
+            seen: Cell::new(None),
+        }
+    }
+}
+
+impl Fetcher for FakeFetcher {
+    fn fetch(&self, font: &'static CjkFont) -> Result, 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!(strategy.describe(), "cjk=needs-download(Noto Sans SC)");
+}
+
+/// pin 的形态守卫（M168）：URL 走 https、哈希是 64 位小写十六进制、字节数在大小上限内。
+///
+/// 抓得住：①有人把 URL 改成 `@main` 这类会漂移的引用（不是不行，但那样哈希必须跟着变，
+/// 这条断言至少逼他看见自己在动什么）；②手抄哈希抄错一位（下一个人只会在真机上看到
+/// 「校验失败」然后降级）；③把三个静态子集塞进来却没改字节数。
+/// 抓不住：CDN 上今天还发不发得出这份字节（要真联网，报告里写明未验）。
+#[test]
+fn the_pinned_source_is_well_formed() {
+    let Source::Pinned {
+        urls,
+        sha256,
+        bytes,
+    } = NOTO_SANS_SC.source;
+    assert!(!urls.is_empty(), "至少要有一个 URL");
+    for url in urls {
+        assert!(url.starts_with("https://"), "字体必须走 https：{url}");
+        assert!(
+            !url.contains("@main"),
+            "钉 commit 而不是会漂移的分支：{url}"
+        );
+    }
+    assert_eq!(sha256.len(), 64, "{sha256}");
+    assert!(
+        sha256.bytes().all(|byte| byte.is_ascii_hexdigit()),
+        "{sha256}"
+    );
+    assert_eq!(sha256, sha256.to_ascii_lowercase(), "哈希用小写：{sha256}");
+    assert!(bytes > 0 && bytes < 32 * 1024 * 1024, "{bytes}");
+}
+
+#[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::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;
+
+    /// 这个源在启动日志里的名字（`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 {
+        // 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,
+    /// 结论的来源（`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 {
+            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 {
+                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"), ®istry_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, ®istry_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, ¬hing, &env_en);
+        assert_eq!(
+            (detection.lang, detection.origin),
+            (Lang::En, "env"),
+            "环境变量说是英文，但来源必须是 env"
+        );
+        // ④ 全没有 → 英文 + default
+        let detection = resolve(None, ¬hing, &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::>();
+        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..1a8989b
--- /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.4" }
+
+# 只开两个编解码器（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..c996cb5
--- /dev/null
+++ b/crates/palette-extract/src/lib.rs
@@ -0,0 +1,236 @@
+//! # 配色取色的解码适配层（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};
+
+mod thumbnail;
+
+pub use thumbnail::{thumbnail, THUMBNAIL_MAX_EDGE};
+
+/// 交给 `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,
+}
+
+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 {
+    let reader = image::ImageReader::new(Cursor::new(bytes))
+        .with_guessed_format()
+        .map_err(ExtractError::Io)?;
+    finish(reader)
+}
+
+/// 从文件路径解码（格式按魔数嗅探，不看扩展名）。
+pub fn load(path: impl AsRef) -> Result {
+    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) -> Result {
+    seed_from_rgba8(&load(path)?)
+}
+
+/// 字节 → 种子色（与 [`extract_seed`] 同一条路径，测试与「内存里的图」用）。
+pub fn seed_from_bytes(bytes: &[u8]) -> Result {
+    seed_from_rgba8(&decode_bytes(bytes)?)
+}
+
+fn seed_from_rgba8(image: &Rgba8) -> Result {
+    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) -> ImageInput<'a> {
+    match loaded {
+        Ok(image) => ImageInput::Pixels(image.view()),
+        Err(_) => ImageInput::Undecodable,
+    }
+}
+
+fn finish(
+    reader: image::ImageReader,
+) -> Result {
+    Ok(fit(decode_with_limits(reader)?, MAX_EDGE))
+}
+
+/// 解码一个 reader（带 [`MAX_SOURCE_EDGE`] 头尺寸上限），**不缩放**。
+///
+/// 从 [`finish`] 里拆出来只有一个理由：取色（[`load`]）与缩略图（[`thumbnail`]）要**不同的
+/// 目标边长**，而「读文件 + 嗅探格式 + 卡解压炸弹」这段必须只有一份（两份就会有一份忘了卡上限）。
+pub(crate) fn decode_with_limits(
+    mut reader: image::ImageReader,
+) -> Result {
+    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)?;
+    Ok(decoded.to_rgba8())
+}
+
+/// 把解码结果等比缩到**长边 ≤ `max_edge`**（不放大：本来就小的图原样交付）。
+///
+/// `thumbnail` 是整数盒式采样：对取色（只关心色彩分布）与缩略图（160px 的墙）都够，
+/// 且比 Lanczos 快一个量级。
+pub(crate) fn fit(rgba: image::RgbaImage, max_edge: u32) -> Rgba8 {
+    let (width, height) = (rgba.width(), rgba.height());
+    let scaled = if width.max(height) > max_edge {
+        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
+    };
+    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..d4953d2
--- /dev/null
+++ b/crates/palette-extract/src/tests.rs
@@ -0,0 +1,281 @@
+//! 解码适配层的单测：真 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 {
+    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 {
+    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"),
+    }
+}
+
+// ---------------------------------------------------------------- 缩略图（M251 · D54）
+
+/// 一次性临时目录（本 crate 不引第三方 tempfile：整仓都没有）。
+struct TempDir(std::path::PathBuf);
+
+impl Drop for TempDir {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_dir_all(&self.0);
+    }
+}
+
+/// 写一个真 PNG 到临时目录，返回 `(目录守卫, 文件路径)`。
+fn png_on_disk(tag: &str, image: &RgbaImage) -> (TempDir, std::path::PathBuf) {
+    use std::sync::atomic::{AtomicU64, Ordering};
+    static COUNTER: AtomicU64 = AtomicU64::new(0);
+    let seq = COUNTER.fetch_add(1, Ordering::Relaxed);
+    let dir =
+        std::env::temp_dir().join(format!("palette-thumb-{tag}-{}-{seq}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    std::fs::create_dir_all(&dir).expect("建临时目录");
+    let path = dir.join("shot.png");
+    std::fs::write(&path, encode_png(image)).expect("写 PNG");
+    (TempDir(dir), path)
+}
+
+/// 真 PNG → 等比缩到给定长边。
+///
+/// 抓得住：`thumbnail` 拿错目标边长（例如误用取色那条路的 `MAX_EDGE = 256`）、宽高比被拉平、
+/// 缩放后字节数对不上 `width × height × 4`。
+/// 抓不住：缩放**画质**（盒式采样的观感只能靠出图看）；像素内容是否正确（只查尺寸与不透明通道）。
+#[test]
+fn thumbnail_scales_a_real_png_to_the_asked_edge() {
+    let (_dir, path) = png_on_disk("scale", &solid_image(40, 20, [0x2E, 0x7D, 0x4F]));
+    let thumb = thumbnail(&path, 10).expect("真 PNG 应当出缩略图");
+    assert_eq!((thumb.width(), thumb.height()), (10, 5), "等比缩到长边 10");
+    assert_eq!(thumb.pixels().len(), 10 * 5 * 4);
+    // 纯色图缩完还是那个色（盒式平均不该把纯色抹成别的色）。
+    assert_eq!(&thumb.pixels()[..4], &[0x2E, 0x7D, 0x4F, 0xFF]);
+}
+
+/// 小图**不放大**：图本身比墙上的格子小就原样交付（放大只会糊）。
+///
+/// 抓得住：有人在 `fit` 里把「长边超限才缩」改成无条件缩（那会把 8×6 的图拉成 160×120）。
+#[test]
+fn thumbnail_never_upscales() {
+    let (_dir, path) = png_on_disk("small", &solid_image(8, 6, [0x67, 0x50, 0xA4]));
+    let thumb = thumbnail(&path, THUMBNAIL_MAX_EDGE).expect("小图也应当成功");
+    assert_eq!((thumb.width(), thumb.height()), (8, 6));
+}
+
+/// 坏文件给**结构化错误**，不 panic、不返回灰图。
+///
+/// 抓得住：把 `?` 换成 `unwrap`/`unwrap_or_default`（前者 panic 让用例挂，后者返回一张图让
+/// `expect_err` 挂）。
+/// 抓不住：错误文案的措辞（那是 `image` 的原文，只进括号）。
+#[test]
+fn a_broken_png_is_a_decode_error_not_a_panic() {
+    use std::sync::atomic::{AtomicU64, Ordering};
+    static COUNTER: AtomicU64 = AtomicU64::new(0);
+    let seq = COUNTER.fetch_add(1, Ordering::Relaxed);
+    let dir = std::env::temp_dir().join(format!("palette-thumb-bad-{}-{seq}", std::process::id()));
+    std::fs::create_dir_all(&dir).expect("建临时目录");
+    let guard = TempDir(dir.clone());
+    let path = dir.join("2024-05-01_10.00.00.png");
+    std::fs::write(&path, b"\x89PNG\r\n\x1a\n truncated garbage").expect("写坏文件");
+
+    match thumbnail(&path, THUMBNAIL_MAX_EDGE) {
+        Err(ExtractError::Decode(_)) => {}
+        other => panic!("坏 PNG 应当给 Decode 错误，实际 {other:?}"),
+    }
+    drop(guard);
+}
+
+/// 文件不存在 ⇒ `Io`（与「解不出来」分开：一个是没读到，一个是读到了但读不懂）。
+#[test]
+fn a_missing_file_is_an_io_error() {
+    let path = std::env::temp_dir().join("palette-thumb-does-not-exist.png");
+    let _ = std::fs::remove_file(&path);
+    match thumbnail(&path, THUMBNAIL_MAX_EDGE) {
+        Err(ExtractError::Io(_)) => {}
+        other => panic!("不存在的文件应当给 Io 错误，实际 {other:?}"),
+    }
+}
+
+/// `max_edge = 0` 按 1 处理（防调用方传 0 得到 0×0 的图，墙上一格空着还查不出原因）。
+#[test]
+fn a_zero_edge_is_treated_as_one() {
+    let (_dir, path) = png_on_disk("zero", &solid_image(40, 20, [0x3C, 0x8D, 0xBC]));
+    let thumb = thumbnail(&path, 0).expect("0 也应当能出图");
+    assert_eq!((thumb.width(), thumb.height()), (1, 1));
+}
diff --git a/crates/palette-extract/src/thumbnail.rs b/crates/palette-extract/src/thumbnail.rs
new file mode 100644
index 0000000..ee0711f
--- /dev/null
+++ b/crates/palette-extract/src/thumbnail.rs
@@ -0,0 +1,57 @@
+//! 缩略图：路径 → 限尺寸的 [`Rgba8`]（D54 第 1 条，M251 · SAVESHOTS）。
+//!
+//! ## 为什么落在本 crate
+//!
+//! D54 定的分层没有变：图片解码**集中在 `palette-extract`**（`crates/design` 零第三方依赖的
+//! 代价就是把解码摊到这里；`app-iced` 另有一份 `image` 只用于截图编码与背景图，见它自己的
+//! `Cargo.toml` 注释）。截图是 PNG，本 crate 的 `image` 已经开了 `png`/`jpeg`/`bmp` 解码 feature，
+//! 所以加这条路**零新依赖、零新 crate、零新 feature**——只是把「解码 + 限尺寸」这段已有的能力
+//! 换个目标边长（[`THUMBNAIL_MAX_EDGE`]）暴露一次。
+//!
+//! ## 不落盘
+//!
+//! 这里**只返回像素**，不写任何缓存文件（D54 第 2 条）：写 PNG 需要编码器，而编码器只为一份
+//! 磁盘缓存引入不划算；内存缓存归调用方（presenter 的 `host::saves::thumbs`）。
+//!
+//! ## 失败不 panic
+//!
+//! 读不到 / 不是图片 / 头里写着 40000×40000，全都变成 [`ExtractError`]（与取色那条路同一族
+//! 错误）。调用方据此给「逐条可见」的失败原因——**不许**在这里「读不到就画个灰块」。
+//!
+//! 与 [`crate::load`] 的区别只有一条：目标边长。`load` 钉 `MAX_EDGE = 256`（取色只需要色彩分布），
+//! 这里由调用方给（缩略图墙用 160）。
+//!
+//! ```no_run
+//! use unlucky_palette_extract::{thumbnail, THUMBNAIL_MAX_EDGE};
+//!
+//! match thumbnail("screenshots/2024-05-01_10.00.00.png", THUMBNAIL_MAX_EDGE) {
+//!     Ok(thumb) => println!("{}×{}", thumb.width(), thumb.height()),
+//!     Err(error) => eprintln!("这张图没有缩略图：{error}"),
+//! }
+//! ```
+
+use std::path::Path;
+
+use crate::{decode_with_limits, fit, ExtractError, Rgba8};
+
+/// 缩略图的最大边（像素）。D54 定 160。
+///
+/// 依据：一屏缩略图墙按 4 列排、详情列宽约 700px ⇒ 每格 ≈ 160px。再大只是多占内存
+/// （160² × 4B ≈ 100KB/张，60 张 ≈ 6MB），肉眼在墙上看不出差别。
+pub const THUMBNAIL_MAX_EDGE: u32 = 160;
+
+/// 从文件路径解码并缩到**长边 ≤ `max_edge`**（等比、不放大），返回 RGBA8 像素。
+///
+/// 格式按**魔数**嗅探，不看扩展名（与 [`crate::load`] 同一条路：用户把 `.jpg` 改名成 `.png`
+/// 也照样读得出来）。`max_edge = 0` 按 1 处理（防调用方传 0 得到 0×0 的图）。
+///
+/// # Errors
+///
+/// - [`ExtractError::Io`]：文件不存在 / 无权限 / 被占用 / 打不开；
+/// - [`ExtractError::Decode`]：不是认得的图片、文件截断、或头尺寸超过 16384（解压炸弹）。
+pub fn thumbnail(path: impl AsRef, max_edge: u32) -> Result {
+    let max_edge = max_edge.max(1);
+    let reader = image::ImageReader::open(path).map_err(ExtractError::Io)?;
+    let reader = reader.with_guessed_format().map_err(ExtractError::Io)?;
+    Ok(fit(decode_with_limits(reader)?, max_edge))
+}
diff --git a/crates/presenter/Cargo.toml b/crates/presenter/Cargo.toml
new file mode 100644
index 0000000..f6b9b26
--- /dev/null
+++ b/crates/presenter/Cargo.toml
@@ -0,0 +1,50 @@
+[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.4" }
+
+# M251（D54 第 1/4 条）：截图缩略图在**后台线程**里解码，解码能力只能来自 palette-extract
+# （`image` 一个字节都不进 presenter，否则「解码集中在一处」这条边界当场作废）。
+# 方向只能是 presenter → palette-extract（反向不许）；那边也不许反过来依赖 core/presenter。
+unlucky-palette-extract = { path = "../palette-extract", version = "0.2.4" }
+
+[lints]
+workspace = true
+
+[features]
+# M169：转发 core 的测试通道（默认关）。GUI 侧「更新」这条链的**人工验收**需要它：
+# `cargo run -p unlucky-app-iced --features update-test-source` 配
+# `ULL_UPDATE_DIR` + `ULL_UPDATE_TEST_SOURCE=1` 才能让设置页指向本地更新源
+# （`-p` 认 package 名 `unlucky-app-iced`；`unlucky-launcher-iced` 是 bin 名，写 `-p` 会找不到包）。
+# 官方发布构建不带这个 feature（`packaging/check_test_source_off.py` 守门）。
+update-test-source = ["unlucky-core/update-test-source"]
+
+[dev-dependencies]
+# M190：presenter 的**更新链路用例**要构造「本构建认得」的签名清单（真发布必须带
+# `manifest.json.sig`，没有它 core 一律拒装）。这里打开 core 的 `update-test-key`：它**只**把一把
+# **公开**的测试公钥并进信任表，不开任何数据源开关（与 `update-test-source` 是两件事）。
+# 只出现在 `[dev-dependencies]`：库/发布构建拿不到它。守门：`packaging/check_test_key_off.py`。
+unlucky-core = { path = "../core", features = ["update-test-key"] }
+# 夹具用同一套种子现签清单（与 `crates/core/src/update/tests/support_sign.rs` 同源）。
+ed25519-dalek.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, String>;
+
+    /// 用户对写操作做了决定（`accept = false` 表示拒绝）。
+    fn confirm(&mut self, request_id: &str, accept: bool) -> Vec;
+}
+
+/// AI 助手的 presenter 门面：持有一份 [`AppState`] 与一个后端端口。
+///
+/// 事件仍走 [`AppState::apply`]（唯一状态变更入口）——[`Presenter::apply`] 只是转发，
+/// 不在这一层另做投影。
+pub struct Presenter {
+    state: AppState,
+    transport: Box,
+    audit: Vec,
+}
+
+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) -> Self {
+        Self::with_state(AppState::new(), transport)
+    }
+
+    /// 接管一份已有状态（UI 壳先建 `AppState` 再交给 presenter 时用）。
+    #[must_use]
+    pub fn with_state(state: AppState, transport: Box) -> 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,
+}
+
+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, 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 {
+        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 个（含 `/` `\`，不含 `;`），占位符也不同
+//!   （`` 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 不持有数据根，`` 掩码是 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 ` → `Bearer `。
+///
+/// core 的 `Redactor` 只认「点号 token / ≥64 不透明串」，短令牌（`Bearer abcdef123456`）
+/// 会原样放过——这条规则照 `unlucky_agent::redact::mask_bearer` 的意图补上（实现是自写的，
+/// 见模块文档 §2 的差异说明）。幂等：已经是 `` 的再跑一遍结果不变。
+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,
+    /// 栏不可见期间攒下的未读条数（`agent_mark_read` 清零）
+    pub unread: usize,
+    /// 是否该禁用输入（一轮回复进行中，或有写操作待确认）
+    pub busy: bool,
+    /// 输入框草稿（切形态不丢）
+    pub draft: String,
+    /// 待确认的写操作（`Some` = 弹确认框；非 YOLO 下 `busy` 必为 true）
+    pub confirm: Option,
+    /// 是否有流式消息在跑（Slint 壳读它切换「发送/停止」；新壳用 `busy` 即可）
+    pub streaming: bool,
+    /// YOLO 开关（跳过确认，审计照记）
+    pub yolo: bool,
+    /// 端点标签（栏顶显示）
+    pub endpoint_label: String,
+    /// 最近一次错误（横幅；下一次提交或 ingest 到新消息时清掉）
+    pub error: Option,
+}
+
+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 {
+        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 , retry=1"
+    );
+    assert_eq!(
+        scrub_text("Bearer abc123; rest"),
+        "Bearer ; rest"
+    );
+    assert_eq!(
+        scrub_text("\"Bearer abc123\""),
+        "\"Bearer \""
+    );
+    assert_eq!(scrub_text("Bearer abc123"), "Bearer ");
+    // 句点不是停字符：整段吞掉（宁可多掩，也不让短 JWT 只掩前半段）
+    assert_eq!(scrub_text("Bearer abc123."), "Bearer ");
+    assert_eq!(scrub_text("Bearer eyJ.abc.def"), "Bearer ");
+}
+
+// ─────────────────────── 提交前置条件 ───────────────────────
+
+#[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, String> {
+        Err("本地模型还没加载".to_string())
+    }
+
+    fn confirm(&mut self, _request_id: &str, _accept: bool) -> Vec {
+        Vec::new()
+    }
+}
+
+/// 收下输入但一个事件都不回的后端（异步推流的极端形态：这一拍还没到）。
+struct SilentTransport;
+
+impl AgentTransport for SilentTransport {
+    fn submit(&mut self, _text: &str, _history: &AgentRail) -> Result, String> {
+        Ok(Vec::new())
+    }
+
+    fn confirm(&mut self, _request_id: &str, _accept: bool) -> Vec {
+        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(""),
+        "应当被脱敏成占位符：{text}"
+    );
+    // 凭据键名的值整段打码（不只是靠内容规则）
+    let details = &rail.confirm.as_ref().expect("确认请求仍在").details;
+    assert_eq!(details["access_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!("");
+    // 键名命中：对象 / 嵌套 / 数组各一
+    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 "), "{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>>,
+}
+
+impl AgentTransport for RecordingTransport {
+    fn submit(&mut self, text: &str, _history: &AgentRail) -> Result, 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 {
+        Vec::new()
+    }
+}
+
+/// 一律报错的后端替身（用来守 Err 文案那道 scrub）。
+struct ErrorTransport(String);
+
+impl AgentTransport for ErrorTransport {
+    fn submit(&mut self, _text: &str, _history: &AgentRail) -> Result, String> {
+        Err(self.0.clone())
+    }
+
+    fn confirm(&mut self, _request_id: &str, _accept: bool) -> Vec {
+        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(""),
+        "出站 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(""), "{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 {
+    /// 钉死数据根（`/.ULL` + `/.minecraft`）；None = 按便携配置解析
+    pub data_root: Option,
+    /// 强制 mock 后端（UI 回归/无数据根演示）
+    pub mock: bool,
+}
+
+/// `/.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 {
+    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,
+    },
+}
+
+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,
+    pending: Vec,
+    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,
+        body: impl Into,
+        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..3e12bf7
--- /dev/null
+++ b/crates/presenter/src/dto/accounts.rs
@@ -0,0 +1,400 @@
+//! 账户页 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, BrowserLoginNote, 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}」，不伪造「最近使用」。
+    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,
+}
+
+impl AccountView {
+    /// 首字母块上的字：展示名第一个非空字符（大写化），空名字回落 `?`。
+    #[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 不引图片解码依赖，裁剪/缩放归 UI 层；
+/// 离线轨永远没有它——没有皮肤就不给假皮肤。
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct SkinImage {
+    /// PNG 字节（Minecraft 皮肤：64×64 或旧版 64×32）
+    pub png: Vec,
+    /// 来源 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,
+    /// 二维码内容（= 带码的链接）
+    pub qr_link: String,
+    /// 有效期（秒；0 = 未知）
+    pub expires_in: u64,
+    /// 状态/错误文案（**失败时是原始诊断，只进日志，不上屏**）
+    pub message: String,
+    /// 失败原因码（`None` = 不是失败态 / 未分类）
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub failure: Option,
+    /// 浏览器登录没走成、已回退设备码的说明码（M178；`None` = 没这回事）
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub browser_note: Option,
+    /// 成功后入库的账户展示名
+    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,
+            browser_note: 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,
+            browser_note: 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,
+            browser_note: None,
+            account_name: String::new(),
+        }
+    }
+
+    /// 附一条回退说明码（M178）。与 `message`（原文只进日志）分开：页面只拿码去查 i18n。
+    #[must_use]
+    pub fn with_browser_note(mut self, note: BrowserLoginNote) -> Self {
+        self.browser_note = Some(note);
+        self
+    }
+
+    /// 失败态（文案在入口就脱敏：错误原文里可能带着服务端回显的 token）。
+    pub fn failed(message: impl Into) -> Self {
+        Self::failed_as(LoginFailure::Other, message)
+    }
+
+    /// 带**原因码**的失败态（页面据码出 i18n；原文只进日志）。
+    pub fn failed_as(failure: LoginFailure, message: impl Into) -> Self {
+        Self {
+            phase: DeviceLoginPhase::Failed,
+            message: redact(&message.into()),
+            failure: Some(failure),
+            ..Self::new()
+        }
+    }
+
+    /// 成功态。
+    pub fn succeeded(account_name: impl Into) -> 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 取走即弃——不入账户库、不进日志、
+/// 不进任何回程 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,
+        login: impl Into,
+        password: impl Into,
+    ) -> 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,
+    /// 成功后入库的账户展示名
+    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) -> Self {
+        Self::failed_as(LoginFailure::Other, message)
+    }
+
+    /// 带**原因码**的失败态（页面据码出 i18n；原文只进日志）。
+    pub fn failed_as(failure: LoginFailure, message: impl Into) -> Self {
+        Self {
+            phase: DeviceLoginPhase::Failed,
+            message: redact(&message.into()),
+            failure: Some(failure),
+            ..Self::new()
+        }
+    }
+
+    /// 成功态。
+    pub fn succeeded(server_name: &str, account_name: impl Into) -> 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..2ecd2b1
--- /dev/null
+++ b/crates/presenter/src/dto/accounts/failure.rs
@@ -0,0 +1,175 @@
+//! 失败原因码与账户页横幅（M114 r2 / 复审 P1-1、P2-2）。
+//!
+//! ## 为什么这一层必须有
+//!
+//! core/presenter 的诊断串是中文人话。把它们直接画到英文界面上，就是复审 r1 那条 p1
+//! （「全英文界面里整句中文」）。根因不是 catalog 缺条目，而是**后端诊断串没有结构**：
+//! 页面除了原样画没有别的选择。
+//!
+//! 这里补的就是那个缺环——把「失败属于哪一类」「这次操作的结果是什么」变成**枚举**。
+//! 页面据 `code()` 选 i18n key 出标题 + 正文 + 一行 `Code: …`；原始诊断留在 `message` /
+//! `detail` 里，**只进日志与详细信息，不上屏**。
+//!
+//! ## 唯一一个「说清原因」的例外（M132）
+//!
+//! [`LoginFailure::MsaNotConfigured`]。它上屏的**不是后端诊断串**，而是 catalog 里一条固定
+//! 文案（`Key::AccountFailureMsaNotConfigured` / `Key::AccountLoginNotConfigured`，不含任何
+//! 凭据、token 或内部细节）——「原文不上屏」这条纪律原样保留，页面仍拿不到、也画不出
+//! `message`/`detail`。允许它说清原因的理由只有一条：**原因本身就是用户能执行的下一步**
+//! （缺 `ULL_MSA_CLIENT_ID`，设上或构建时注入即可）。判据：没读过代码的用户碰上它，必须能
+//! 从界面自己看出「是缺一个配置」并知道怎么补，而不是去翻日志。其余一切（网络 / 拒绝 /
+//! 落盘…）仍旧只给码与分类文案，原文只进日志。
+//!
+//! 约束：`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,
+    /// 微软轨的 client id 没配（`ULL_MSA_CLIENT_ID` 运行期/构建期两处都没有）——**配置缺失**，
+    /// 不是登录被拒、也不是「没实现」（M132）。
+    ///
+    /// 单独成码的理由见模块文档「唯一一个『说清原因』的例外」：这一类的原因就是用户能执行的
+    /// 下一步，所以它的正文必须说清「要设哪个环境变量」，而不是「完整原因在日志里」。
+    MsaNotConfigured,
+    /// 其它（未知原因；原文只在 `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::MsaNotConfigured => "msa_not_configured",
+            Self::Other => "other",
+        }
+    }
+}
+
+/// 「浏览器登录没走成，已自动改用设备码」的说明码（M178）。
+///
+/// 为什么与 [`LoginFailure`] 分开：这不是登录失败——设备码流接上了，用户照常在等码。
+/// 它解释的是「为什么面板变成了设备码」以及**要不要去改应用注册**，所以单独一个码族，
+/// 页面画成一行提示而不是错误横幅。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum BrowserLoginNote {
+    /// 应用注册里没有回环重定向 URI（授权端点当场拒绝）——**唯一带「怎么修」的一句**
+    RedirectNotRegistered,
+    /// 预检没问出结论（网络/超时），只能先用设备码
+    PreflightUnavailable,
+    /// 预检通过、授权码流仍然失败（超时 / 换 token 被拒 / 端口绑不上）
+    AttemptFailed,
+}
+
+impl BrowserLoginNote {
+    /// 稳定 ascii code（日志/测试用，**不随语言变**）。
+    #[must_use]
+    pub const fn code(self) -> &'static str {
+        match self {
+            Self::RedirectNotRegistered => "redirect_not_registered",
+            Self::PreflightUnavailable => "preflight_unavailable",
+            Self::AttemptFailed => "attempt_failed",
+        }
+    }
+}
+
+/// 账户页的**一次性横幅**（添加/删除/切换的结果；页面据 `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,
+        detail: impl Into,
+    ) -> 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/adopt.rs b/crates/presenter/src/dto/adopt.rs
new file mode 100644
index 0000000..1ad8e30
--- /dev/null
+++ b/crates/presenter/src/dto/adopt.rs
@@ -0,0 +1,384 @@
+//! 「导入已有版本」的 IPC 面（M223 GUIADOPT）：扫描 → 预检 → 确认三段。
+//!
+//! 能力本身在 core（`unlucky_core::game::adopt`，M221 的契约见
+//! `DevDocs/SubAgentsTalk/adoptcore-契约.md`）；本文件只有**可序列化的视图**，
+//! 一个 `unlucky_core::*` 类型都不出现（AGENTS §6 的跨边界纪律）。
+//!
+//! ## 三段：前两段零写盘，第三段只写 ULL 自己的配置
+//!
+//! | 段 | 指令 | 回程 | 写盘 |
+//! |---|---|---|---|
+//! | 扫描 | [`AdoptCommand::Scan`] | [`AdoptEvent::Scan`] | 零（不建目录、不改 mtime） |
+//! | 预检 | [`AdoptCommand::Preview`] | [`AdoptEvent::Planned`] / [`AdoptEvent::Failed`] | 零 |
+//! | 确认 | [`AdoptCommand::Confirm`] | [`AdoptEvent::Done`] / [`AdoptEvent::Failed`] | 实例设置 + `profiles.json`（+ 缺省运行目录） |
+//!
+//! ## 三条硬纪律（契约 §5 的 1/2/3）
+//!
+//! 1. **运行目录只认回程**：[`AdoptPlanView::run_dir`] / [`AdoptDoneView::run_dir`] 是唯一来源。
+//!    缺省档会带 `-2`/`-3` 后缀消歧（两个不同展示名可能落到同一个物理目录），**只有 core 知道
+//!    最后用了哪个**；页面拿展示名自己派生一次就是错的（会与实例真正启动时用的目录分叉）。
+//! 2. **后果话术只有一份**：`Shared` / `VersionDir` 的后果**不在本文件里另写**一句，
+//!    由预检把 core `target_notes()` 的原文放进 [`AdoptPlanView::notes`]——于是界面上的
+//!    「mods/saves/config 会落进别人的 `.minecraft`」与 CLI 打的是同一句。
+//!    想显示后果就必须先预检（预检零写盘，所以这不是成本）。
+//! 3. **问题逐条**：core 的结构化问题（[`AdoptProblemView`]，带稳定 `code`）与整次失败
+//!    （[`AdoptFailureView`]）都原样搬过来，**不折叠成一句「导入失败」**。
+//!
+//! ## 缺省档为什么是 `InstanceDir` 而不是 `isolated`
+//!
+//! 全局缺省 `isolated` 的运行目录就是 `versions//`——那是**别人的版本目录**。沿用它会让第一次
+//! 启动就在别人的 `.minecraft` 里长出 `mods/` `saves/` `logs/`。所以 [`AdoptTargetView`] 的
+//! 缺省是 `InstanceDir`（ULL 数据区新建独立目录），另两档必须**明确点选**。
+
+use std::path::PathBuf;
+
+use serde::{Deserialize, Serialize};
+
+/// app → host 的导入意图。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum AdoptCommand {
+    /// 扫当前游戏根的 `versions/`（只读；顺带得到每个版本能不能登记、已登记给谁）
+    Scan,
+    /// **预检**：按请求算落点与后果（零写盘）。页面拿回 [`AdoptEvent::Planned`] 才画确认按钮。
+    Preview(Box),
+    /// 确认登记（唯一写盘入口）。
+    Confirm(Box),
+    /// 关掉面板（扫描结果 / 预检 / 结果卡都收起来）
+    Dismiss,
+}
+
+/// host → app 的回程事件。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum AdoptEvent {
+    /// 扫描结果（`versions/` 里的全部条目，逐项带问题）
+    Scan(Box),
+    /// 预检结果（落点 + 后果原文 + 将写的展示名）
+    Planned(Box),
+    /// 失败：`code` 稳定、`message` 人读、`problems` 逐条（可能为空）
+    Failed(Box),
+    /// 登记完成
+    Done(Box),
+    /// 面板已关（状态复位）
+    Cleared,
+}
+
+/// 登记后的**运行目录从哪来**（隔离档由它决定）。
+///
+/// GUI 只开三档：[`Self::InstanceDir`]（缺省）/[`Self::Shared`] / [`Self::VersionDir`]。
+/// `custom`（用户手输绝对路径）留在 CLI：GUI 要它就得配目录选择器，不在本 mission 的交付面里。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
+pub enum AdoptTargetView {
+    /// 缺省：ULL 数据区新建独立运行目录（`custom` 档，与别人的 `.minecraft` 隔离）
+    #[default]
+    InstanceDir,
+    /// 共用游戏根（别人的 `.minecraft`）——必须明确点选
+    Shared,
+    /// 版本目录 `versions//`（`isolated` 档）——会在别人的版本目录里长玩家数据
+    VersionDir,
+}
+
+impl AdoptTargetView {
+    /// 三档的声明顺序（= 面板上的先后，缺省在最前）。
+    pub const ALL: [AdoptTargetView; 3] = [
+        AdoptTargetView::InstanceDir,
+        AdoptTargetView::Shared,
+        AdoptTargetView::VersionDir,
+    ];
+
+    /// 稳定 slug（与 core 的 `AdoptTarget::as_str` 同词表；`instance_dir` 不进 CLI 词表）。
+    #[must_use]
+    pub const fn slug(self) -> &'static str {
+        match self {
+            Self::InstanceDir => "instance_dir",
+            Self::Shared => "shared",
+            Self::VersionDir => "version_dir",
+        }
+    }
+
+    /// 从 slug 反解。
+    #[must_use]
+    pub fn from_slug(slug: &str) -> Option {
+        Self::ALL.into_iter().find(|target| target.slug() == slug)
+    }
+
+    /// 这一档会不会把玩家数据写进**别人的**目录（界面据此加警示标记）。
+    #[must_use]
+    pub const fn touches_foreign_dir(self) -> bool {
+        matches!(self, Self::Shared | Self::VersionDir)
+    }
+}
+
+/// 生效的隔离档（`core::game::install::instance::Isolation` 的视图形态）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum AdoptIsolationView {
+    /// `versions//` 当运行目录
+    Isolated,
+    /// 游戏根当运行目录
+    Shared,
+    /// 指定/新建目录当运行目录（缺省档就是这一档）
+    Custom,
+}
+
+impl AdoptIsolationView {
+    /// 稳定 slug（与 core 的 `Isolation::as_str` 同一套字面量）。
+    #[must_use]
+    pub const fn slug(self) -> &'static str {
+        match self {
+            Self::Isolated => "isolated",
+            Self::Shared => "shared",
+            Self::Custom => "custom",
+        }
+    }
+
+    /// 从 slug 反解（未知值返回 `None`，界面照原样上屏而不是猜）。
+    #[must_use]
+    pub fn from_slug(slug: &str) -> Option {
+        match slug {
+            "isolated" => Some(Self::Isolated),
+            "shared" => Some(Self::Shared),
+            "custom" => Some(Self::Custom),
+            _ => None,
+        }
+    }
+}
+
+/// 一次预检/登记的请求（页面表单 → host）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct AdoptRequestView {
+    /// 要接进来的版本 id（= `versions//` 的目录名）
+    pub version_id: String,
+    /// 展示名（`None` / 空串 = 用版本 id）
+    pub name: Option,
+    /// 运行目录选择（缺省 [`AdoptTargetView::InstanceDir`]）
+    pub target: AdoptTargetView,
+}
+
+impl AdoptRequestView {
+    /// 最小请求（缺省名 + 缺省运行目录）。
+    #[must_use]
+    pub fn new(version_id: impl Into) -> Self {
+        Self {
+            version_id: version_id.into(),
+            name: None,
+            target: AdoptTargetView::default(),
+        }
+    }
+}
+
+/// 一条**结构化**的不合格原因（`code` 稳定，`message` 人读）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct AdoptProblemView {
+    /// 稳定机读码（`manifest_missing` / `missing_parent` / `outside_game_root` …）
+    pub code: String,
+    /// 人读原因（core 的 `Display` 原文：带路径、行列号、缺哪个父版本）
+    pub message: String,
+}
+
+/// 盘上的一个候选版本。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct AdoptCandidateView {
+    /// 版本 id（= 目录名，登记后写进 `profiles.json`）
+    pub version_id: String,
+    /// 客户端 jar 在不在（只报事实，不校验内容）
+    pub jar_present: bool,
+    /// `inheritsFrom` 链（自身在前、最祖先在后）
+    pub inherits: Vec,
+    /// 已经绑定这个版本的实例名（空 = 还没登记过）
+    pub registered: Vec,
+    /// 问题清单（空 = 可登记）
+    pub problems: Vec,
+}
+
+impl AdoptCandidateView {
+    /// 能不能登记（没有任何问题）。
+    #[must_use]
+    pub fn adoptable(&self) -> bool {
+        self.problems.is_empty()
+    }
+
+    /// 已登记过（再登记会得到第二个实例，共用同一份版本文件）。
+    #[must_use]
+    pub fn is_registered(&self) -> bool {
+        !self.registered.is_empty()
+    }
+}
+
+/// 一次扫描的结果。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct AdoptScanView {
+    /// 被扫的目录（`<游戏根>/versions`）
+    pub versions_dir: PathBuf,
+    /// 候选（按版本 id 字典序）
+    pub candidates: Vec,
+}
+
+impl AdoptScanView {
+    /// 候选条数。
+    #[must_use]
+    pub fn total(&self) -> usize {
+        self.candidates.len()
+    }
+
+    /// 可登记的条数。
+    #[must_use]
+    pub fn adoptable(&self) -> usize {
+        self.candidates
+            .iter()
+            .filter(|candidate| candidate.adoptable())
+            .count()
+    }
+
+    /// `versions/` 存在但一个候选都没有（新数据根，或只剩别的启动器的空目录）。
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.candidates.is_empty()
+    }
+}
+
+/// 预检结果：落点 + 后果原文 + 将写的展示名。**零写盘**。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct AdoptPlanView {
+    /// 版本 id
+    pub version_id: String,
+    /// 将写进档案的展示名（空名已回落到版本 id）
+    pub name: String,
+    /// 运行目录选择
+    pub target: AdoptTargetView,
+    /// 生效隔离档
+    pub isolation: AdoptIsolationView,
+    /// **生效运行目录**（可能是顺延后的 `-2`/`-3`；页面不许自己派生）
+    pub run_dir: PathBuf,
+    /// 人读提示（含 `target_notes()` 的原文：共享档/版本目录档会把玩家数据写进别人的目录）
+    pub notes: Vec,
+}
+
+/// 登记完成。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct AdoptDoneView {
+    /// 实例 id（稳定 UUID）
+    pub instance_id: String,
+    /// 展示名
+    pub name: String,
+    /// 绑定的版本 id
+    pub version_id: String,
+    /// 生效隔离档
+    pub isolation: AdoptIsolationView,
+    /// 生效运行目录（**唯一来源**：启动时用的就是它）
+    pub run_dir: PathBuf,
+    /// 是否新建了缺省运行目录（`false` = 目录已存在但为空、直接复用）
+    pub dir_created: bool,
+    /// 人读提示（与预检同一份）
+    pub notes: Vec,
+}
+
+/// 一次失败（整次调用，不是单条候选问题）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct AdoptFailureView {
+    /// 稳定机读码（`adopt_not_adoptable` / `adopt_duplicate_name` / `adopt_target_not_empty` …）
+    pub code: String,
+    /// 人读原因（core 的 `Display` 原文）
+    pub message: String,
+    /// 候选问题清单（`adopt_not_adoptable` 时逐条给出；其它失败为空）
+    pub problems: Vec,
+}
+
+/// 向导的**事件态**（`AppState::adopt` 的全部内容）。
+///
+/// 只有从 [`AdoptEvent`] 来的事实：扫描结果、预检结果、失败、完成。页面的表单字段
+/// （选中的版本、展示名输入、目标选择、面板开没开）属于 UI 本地态，**不在这里**——
+/// 状态只有一个写入点，才不会有「页面显示的落点和真正写盘的落点不是一回事」。
+#[derive(Debug, Clone, PartialEq, Default)]
+pub struct AdoptState {
+    /// 最近一次扫描（`None` = 还没扫过 / 已被新一轮顶掉）
+    pub scan: Option,
+    /// 最近一次预检（`None` = 还没预检 / 已过期）
+    pub plan: Option,
+    /// 最近一次失败
+    pub failure: Option,
+    /// 最近一次完成的登记
+    pub done: Option,
+}
+
+impl AdoptState {
+    /// 事件 → 状态（**唯一**写入点，与 `PackState::apply` 同一条纪律）。
+    pub fn apply(&mut self, event: AdoptEvent) {
+        match event {
+            AdoptEvent::Scan(scan) => {
+                // 新一轮扫描：上一轮的预检/失败/完成都作废（候选集合可能已经变了）
+                self.scan = Some(*scan);
+                self.plan = None;
+                self.failure = None;
+                self.done = None;
+            }
+            AdoptEvent::Planned(plan) => {
+                self.plan = Some(*plan);
+                self.failure = None;
+                self.done = None;
+            }
+            AdoptEvent::Failed(failure) => {
+                // 预检失败时上一份预检必须消失：留着会让确认按钮继续亮着
+                self.plan = None;
+                self.failure = Some(*failure);
+            }
+            AdoptEvent::Done(done) => {
+                // 登记成功：预检与失败都过期（这一轮已经有结论）
+                self.plan = None;
+                self.failure = None;
+                self.done = Some(*done);
+            }
+            AdoptEvent::Cleared => {
+                self.scan = None;
+                self.plan = None;
+                self.failure = None;
+                self.done = None;
+            }
+        }
+    }
+
+    /// 面板此刻该画的那一段（扫描 / 选版本 / 预检 / 结果）。
+    ///
+    /// 优先级：完成 > 失败 > 预检 > 扫描列表。写成一个方法而不是让页面各判一遍，
+    /// 是为了「同一时刻只画一段」在单测里可断言。
+    #[must_use]
+    pub fn stage(&self) -> AdoptStage {
+        if self.done.is_some() {
+            return AdoptStage::Done;
+        }
+        if self.failure.is_some() {
+            return AdoptStage::Failed;
+        }
+        if self.plan.is_some() {
+            return AdoptStage::Preview;
+        }
+        AdoptStage::Pick
+    }
+}
+
+/// 面板当前画哪一段（[`AdoptState::stage`] 的产物）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum AdoptStage {
+    /// 扫出来的候选列表（选版本）
+    Pick,
+    /// 预检结果（落点 + 后果原文 + 确认按钮）
+    Preview,
+    /// 失败（原因逐条）
+    Failed,
+    /// 完成
+    Done,
+}
+
+impl AdoptStage {
+    /// 稳定 slug（进日志/测试断言用）。
+    #[must_use]
+    pub const fn slug(self) -> &'static str {
+        match self {
+            Self::Pick => "pick",
+            Self::Preview => "preview",
+            Self::Failed => "failed",
+            Self::Done => "done",
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/presenter/src/dto/adopt/tests.rs b/crates/presenter/src/dto/adopt/tests.rs
new file mode 100644
index 0000000..3d4be0a
--- /dev/null
+++ b/crates/presenter/src/dto/adopt/tests.rs
@@ -0,0 +1,136 @@
+//! `dto::adopt` 的 IPC 契约用例（M223 从 `dto/adopt.rs` **纯搬移**，断言一条未改）。
+//!
+//! 为什么搬：`dto/adopt.rs` 落笔 512 行，越过 400 行硬线（AGENTS §3.1）；口径与
+//! [`crate::dto::events::tests`] 完全一致——**纯搬移、一行不改**。`adopt.rs` 是非 `mod.rs`
+//! 文件，`mod tests;` 的落点就是本文件。
+
+use super::*;
+
+fn candidate(version_id: &str, problems: Vec) -> AdoptCandidateView {
+    AdoptCandidateView {
+        version_id: version_id.to_string(),
+        jar_present: true,
+        inherits: Vec::new(),
+        registered: Vec::new(),
+        problems,
+    }
+}
+
+fn scan_view() -> AdoptScanView {
+    AdoptScanView {
+        versions_dir: PathBuf::from("/game/versions"),
+        candidates: vec![
+            candidate("1.20.1", Vec::new()),
+            candidate(
+                "1.19.4",
+                vec![AdoptProblemView {
+                    code: "manifest_missing".to_string(),
+                    message: "版本 1.19.4 没有清单文件".to_string(),
+                }],
+            ),
+        ],
+    }
+}
+
+#[test]
+fn events_round_trip_through_json() {
+    let event = AdoptEvent::Failed(Box::new(AdoptFailureView {
+        code: "adopt_not_adoptable".to_string(),
+        message: "版本 1.19.4 不能登记".to_string(),
+        problems: vec![AdoptProblemView {
+            code: "manifest_missing".to_string(),
+            message: "清单缺了".to_string(),
+        }],
+    }));
+    let text = serde_json::to_string(&event).expect("序列化");
+    assert_eq!(
+        serde_json::from_str::(&text).expect("反序列化"),
+        event
+    );
+
+    let command = AdoptCommand::Preview(Box::new(AdoptRequestView {
+        version_id: "1.20.1".to_string(),
+        name: Some("生存".to_string()),
+        target: AdoptTargetView::Shared,
+    }));
+    let text = serde_json::to_string(&command).expect("序列化");
+    assert_eq!(
+        serde_json::from_str::(&text).expect("反序列化"),
+        command
+    );
+}
+
+#[test]
+fn scan_summarises_adoptable_and_empty() {
+    let view = scan_view();
+    assert_eq!(view.total(), 2);
+    assert_eq!(view.adoptable(), 1);
+    assert!(!view.is_empty());
+    assert!(AdoptScanView {
+        versions_dir: PathBuf::from("/game/versions"),
+        candidates: Vec::new(),
+    }
+    .is_empty());
+}
+
+#[test]
+fn target_slugs_round_trip_and_mark_foreign_dirs() {
+    for target in AdoptTargetView::ALL {
+        assert_eq!(AdoptTargetView::from_slug(target.slug()), Some(target));
+    }
+    assert_eq!(AdoptTargetView::default(), AdoptTargetView::InstanceDir);
+    assert!(!AdoptTargetView::InstanceDir.touches_foreign_dir());
+    assert!(AdoptTargetView::Shared.touches_foreign_dir());
+    assert!(AdoptTargetView::VersionDir.touches_foreign_dir());
+}
+
+#[test]
+fn state_follows_the_four_stages() {
+    let mut state = AdoptState::default();
+    assert_eq!(state.stage(), AdoptStage::Pick);
+
+    state.apply(AdoptEvent::Scan(Box::new(scan_view())));
+    assert_eq!(state.stage(), AdoptStage::Pick);
+    assert_eq!(state.scan.as_ref().map(AdoptScanView::adoptable), Some(1));
+
+    let plan = AdoptPlanView {
+        version_id: "1.20.1".to_string(),
+        name: "1.20.1".to_string(),
+        target: AdoptTargetView::InstanceDir,
+        isolation: AdoptIsolationView::Custom,
+        run_dir: PathBuf::from("/ull/data/instances/1.20.1"),
+        notes: vec!["运行目录 = /ull/data/instances/1.20.1".to_string()],
+    };
+    state.apply(AdoptEvent::Planned(Box::new(plan.clone())));
+    assert_eq!(state.stage(), AdoptStage::Preview);
+    assert_eq!(
+        state.plan.as_ref().map(|plan| &plan.run_dir),
+        Some(&plan.run_dir)
+    );
+
+    // 失败会把预检顶掉：留着预检，确认按钮就会在「不能登记」的结论上继续亮着
+    state.apply(AdoptEvent::Failed(Box::new(AdoptFailureView {
+        code: "adopt_duplicate_name".to_string(),
+        message: "已有同名实例".to_string(),
+        problems: Vec::new(),
+    })));
+    assert_eq!(state.stage(), AdoptStage::Failed);
+    assert!(state.plan.is_none());
+
+    state.apply(AdoptEvent::Done(Box::new(AdoptDoneView {
+        instance_id: "id-1".to_string(),
+        name: "1.20.1".to_string(),
+        version_id: "1.20.1".to_string(),
+        isolation: AdoptIsolationView::Custom,
+        run_dir: PathBuf::from("/ull/data/instances/1.20.1"),
+        dir_created: true,
+        notes: Vec::new(),
+    })));
+    assert_eq!(state.stage(), AdoptStage::Done);
+    assert!(state.failure.is_none());
+
+    // 关面板 = 全清（再开要重新扫，否则画的是上一轮的候选）
+    state.apply(AdoptEvent::Cleared);
+    assert_eq!(state.stage(), AdoptStage::Pick);
+    assert!(state.scan.is_none() && state.done.is_none());
+}
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,
+    /// 流式未收敛
+    pub streaming: bool,
+}
+
+impl ChatMessage {
+    /// 用户消息。
+    pub fn user(text: impl Into) -> 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) -> 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..43d3d61
--- /dev/null
+++ b/crates/presenter/src/dto/content.rs
@@ -0,0 +1,397 @@
+//! 内容库 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};
+
+pub use query::ContentSort;
+
+mod detail;
+mod query;
+
+pub use detail::{
+    ContentDetail, ContentDetailRequest, ContentFailure, ContentFailureKind, ContentVersionView,
+};
+
+/// 内容类型（内容库页左侧那四条一级侧栏）。
+#[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",
+        }
+    }
+}
+
+/// 加载器 → 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,
+    /// 加载器过滤（`None` = 不过滤；对资源包 / 光影也照发——静默丢掉会让筛选条撒谎）
+    pub loader: Option,
+    /// 排序
+    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,
+    /// 支持的加载器（`fabric` / `forge` / `neoforge` / `quilt`）
+    pub loaders: Vec,
+    /// 图标 URL（`None` = 没有；页面不拉图，只把主机名画成占位标记）
+    pub icon: Option,
+}
+
+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,
+    /// 命中总数（站点给的分页总数；`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,
+    /// **只重试上次失败的那些项目**（M191）。
+    ///
+    /// `true` 时 host 不再解根项目：它拿上一次装入留下的依赖计划调
+    /// `DependencyPlan::retry_request()`，只重解失败项（`present` 重新扫一遍目录），于是
+    /// 「已装好的不重下、没失败的不重发」。这种模式下本结构里**只有 `instance` 会被读**——
+    /// 过滤条件与落盘目录都来自那份计划。
+    ///
+    /// 没有可重试的计划时（换进程 / 那一次是别的实例）一律回一条失败，**不**退化成「整单重装」：
+    /// 那正是本字段要避免的事。
+    pub retry: bool,
+}
+
+/// 内容库页的状态（M109）：**检索条件 + 最近一批结果 + 请求态**。
+///
+/// 条件为什么也存在这里：页面层不持有业务状态是老纪律（同 `download_query`）；换页只挪游标、
+/// 条件只有一份，才不会出现「筛选条说的是 A、列表画的是 B」。
+#[derive(Debug, Clone, PartialEq)]
+pub struct ContentState {
+    /// 当前检索条件（游标也在里面：换页就是换一份 `query`）
+    pub query: ContentQuery,
+    /// 最近一批结果（`None` = 还没拉过）
+    pub results: Option,
+    /// 有请求在飞（页面画加载态的依据；命中项只由事件写进来，不做乐观回显）
+    pub pending: bool,
+    /// 最近一次失败（`None` = 没失败）。M162 起带**大类**，「没联网」不再是普通失败。
+    pub failed: Option,
+    /// **最近一页**是否装满（`hits.len() >= limit`）。
+    ///
+    /// 为什么不是「累计条数够一页」：分页是**累加**到 `results.hits` 里的，累计值在第 2 页之后
+    /// 必然 ≥ limit ⇒ 用累计判会得到「has_more 恒真」：加载更多永不消失、「没有更多了」在真实
+    /// 翻页路径上不可达，而且每点一次白发一次网络请求（复审 P1-2）。所以这一位单独记。
+    pub last_page_filled: bool,
+    /// 选中项目的详情（M162：`LoadContentDetail` 的结果；`None` = 还没拉过）
+    pub detail: Option>,
+    /// 详情请求在飞（哪个项目：迟到结果靠它判「还算不算当前这次」）
+    pub detail_pending: bool,
+    /// 在飞的那次详情请求的项目 id（`None` = 没有在飞）
+    pub detail_requested: Option,
+    /// 最近一次详情请求的失败
+    pub detail_failed: Option,
+}
+
+impl Default for ContentState {
+    fn default() -> Self {
+        Self {
+            query: ContentQuery::first(ContentKind::Mod),
+            results: None,
+            pending: false,
+            failed: None,
+            last_page_filled: false,
+            detail: None,
+            detail_pending: false,
+            detail_requested: None,
+            detail_failed: None,
+        }
+    }
+}
+
+impl ContentState {
+    /// 进「详情请求在飞」态并清掉上一条（换选中项时调）。
+    pub fn request_detail(&mut self, project: &str) {
+        if self
+            .detail
+            .as_ref()
+            .is_some_and(|detail| detail.project != project)
+        {
+            self.detail = None;
+        }
+        self.detail_pending = true;
+        self.detail_requested = Some(project.to_string());
+        self.detail_failed = None;
+    }
+
+    /// 详情落地：**只接受当前这次请求的结果**（迟到的、别的项目的一律丢掉）。
+    ///
+    /// 场景：选中 A（请求发出）→ 立刻切到 B（又发一条）→ A 的结果后到。没有这道闸门的话，
+    /// A 的版本列表会画在 B 的详情面板下，A 的失败也会被当成本次失败（r1 P2-3）。
+    pub fn apply_detail(&mut self, project: &str, detail: ContentDetail) {
+        if !self.accepts_detail(project) || detail.project != project {
+            return;
+        }
+        self.detail_pending = false;
+        self.detail_requested = None;
+        self.detail_failed = None;
+        self.detail = Some(Box::new(detail));
+    }
+
+    /// 详情失败：同样只看当前这次请求。
+    pub fn fail_detail(&mut self, project: &str, failure: ContentFailure) {
+        if !self.accepts_detail(project) {
+            return;
+        }
+        self.detail_pending = false;
+        self.detail_requested = None;
+        self.detail_failed = Some(failure);
+    }
+
+    /// 这条详情结果还算当前这次吗（`false` = 迟到 / 用户已经换了选中项）。
+    #[must_use]
+    pub fn accepts_detail(&self, project: &str) -> bool {
+        self.detail_requested.as_deref() == Some(project)
+    }
+
+    /// 这批结果还算当前条件吗（`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/detail.rs b/crates/presenter/src/dto/content/detail.rs
new file mode 100644
index 0000000..08a4d39
--- /dev/null
+++ b/crates/presenter/src/dto/content/detail.rs
@@ -0,0 +1,175 @@
+//! 内容库的**失败分类**与**详情/版本列表** DTO（M162：在线内容源接上真数据）。
+//!
+//! 从 `dto/content.rs` 拆出（那个文件已贴 400 行硬线）。两件事放一起，因为它们都是
+//! 「检索之后」的话：一次请求失败了要能说清是哪一类，选中一个项目要能拿到版本列表。
+//!
+//! # 为什么失败要分大类
+//!
+//! 无网时画「未联网，检查网络后重试」、站点 404 时画「换个关键词」是**两种界面**。
+//! 只有字符串就只能靠 `contains("网络")` 猜文案，一改文案就失效；所以大类在 core 那一侧
+//! （`OnlineErrorKind`）就分好了，这里只做一一映射，不重新判。
+//!
+//! # 详情为什么单独一条通道
+//!
+//! 检索结果里只有「支持哪些版本/加载器」（facets），拿不到「有哪些版本可以装」。
+//! 版本列表是另一个端点（`/v2/project/{id}/version`），而且**只在选中某个项目时才需要**——
+//! 跟着检索一起拉等于每页多 N 次请求。所以详情是一条独立命令/事件，页面选中才发。
+
+use serde::{Deserialize, Serialize};
+
+use super::ContentSource;
+use crate::dto::LoaderKind;
+
+/// 一次检索/详情失败的**大类**（M162：把「没联网」与「查无此项」分开）。
+///
+/// 为什么不是 `Option`：无网时画「未联网，检查网络后重试」、站点 404 时画「换个关键词」
+/// 是两件事；只有字符串就只能靠 `contains("网络")` 猜，一改文案就失效。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum ContentFailureKind {
+    /// 没联网 / 连不上站点（core 的 `OnlineErrorKind::NotConnected`）
+    Offline,
+    /// 站点说没有（404）
+    NotFound,
+    /// 站点出错（5xx / 退避后仍失败 / 限速）
+    Server,
+    /// 这条路走不通（缺密钥 / 没有可用下载地址 / 摘要格式不对）
+    Unsupported,
+    /// **站点有这个项目，但目标版本/加载器下没有条目**（M191；core 的 `FailureKind::Incompatible`）
+    ///
+    /// 与 [`Self::NotFound`] / [`Self::Offline`] 是**两种用户动作**：这里换版本或换加载器才有救，
+    /// 重试同样的条件只会得到同一条结论。以前它落在 `Unsupported`（与「缺密钥」共用一档），
+    /// 于是界面没法单独说「换个版本」——M191 把这一档单独拎出来。
+    Incompatible,
+    /// 其它（解析失败、本地 IO……）
+    Other,
+}
+
+impl ContentFailureKind {
+    /// 稳定字符串 id（日志 / 用例断言用，**不要改名**）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Offline => "offline",
+            Self::NotFound => "not_found",
+            Self::Server => "server",
+            Self::Unsupported => "unsupported",
+            Self::Incompatible => "incompatible",
+            Self::Other => "other",
+        }
+    }
+
+    /// 是不是「所选版本/加载器下没有条目」（换版本/加载器才有救，重试没用）。
+    #[must_use]
+    pub const fn is_incompatible(self) -> bool {
+        matches!(self, Self::Incompatible)
+    }
+
+    /// 是不是「没联网」（页面据此画独立的离线态，而不是通用失败态）。
+    #[must_use]
+    pub const fn is_offline(self) -> bool {
+        matches!(self, Self::Offline)
+    }
+}
+
+/// 一次检索/详情失败（大类 + 一句人读原因）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ContentFailure {
+    /// 大类
+    pub kind: ContentFailureKind,
+    /// 人读说明（原文来自 core / 站点；**不是**界面文案）
+    pub detail: String,
+}
+
+impl ContentFailure {
+    /// 构造。
+    #[must_use]
+    pub fn new(kind: ContentFailureKind, detail: impl Into) -> Self {
+        Self {
+            kind,
+            detail: detail.into(),
+        }
+    }
+
+    /// 没联网。
+    #[must_use]
+    pub fn offline(detail: impl Into) -> Self {
+        Self::new(ContentFailureKind::Offline, detail)
+    }
+
+    /// 这条路没通。
+    #[must_use]
+    pub fn unsupported(detail: impl Into) -> Self {
+        Self::new(ContentFailureKind::Unsupported, detail)
+    }
+
+    /// 没联网吗。
+    #[must_use]
+    pub const fn is_offline(&self) -> bool {
+        self.kind.is_offline()
+    }
+}
+
+impl std::fmt::Display for ContentFailure {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(formatter, "{}：{}", self.kind.as_str(), self.detail)
+    }
+}
+
+/// 「取项目详情 + 版本列表」的请求（M162）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ContentDetailRequest {
+    /// 项目 id
+    pub project: String,
+    /// 来源（详情端点目前只接了 Modrinth；CurseForge 会明确报「未接通」）
+    pub source: ContentSource,
+    /// 目标游戏版本（选版本用；`None` = 不限）
+    pub game_version: Option,
+    /// 目标加载器（选版本用；`None` = 不限）
+    pub loader: Option,
+}
+
+/// 一个可用版本（详情页「版本列表」的一行）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ContentVersionView {
+    /// 版本 id
+    pub id: String,
+    /// 版本名
+    pub name: String,
+    /// 版本号
+    pub number: String,
+    /// 版本类型（`release` / `beta` / `alpha`）
+    pub kind: String,
+    /// 支持的游戏版本
+    pub game_versions: Vec,
+    /// 支持的加载器
+    pub loaders: Vec,
+    /// 发布日期（站点原文）
+    pub published: String,
+    /// 主文件名（`None` = 站点没给）
+    pub file_name: Option,
+    /// 主文件字节数（`None` = 站点没给）
+    pub file_size: Option,
+}
+
+/// 项目详情 + 版本列表（M162）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ContentDetail {
+    /// 项目 id
+    pub project: String,
+    /// 标题
+    pub title: String,
+    /// 简介
+    pub description: String,
+    /// 长文（markdown 原文；页面只当纯文本画前几行）
+    pub body: String,
+    /// 可用版本（**最新在前**，已按请求的版本/加载器过滤）
+    pub versions: Vec,
+}
+
+impl ContentDetail {
+    /// 版本数量（页面「N 个可用版本」直接用）。
+    #[must_use]
+    pub fn version_count(&self) -> usize {
+        self.versions.len()
+    }
+}
diff --git a/crates/presenter/src/dto/content/query.rs b/crates/presenter/src/dto/content/query.rs
new file mode 100644
index 0000000..d097b83
--- /dev/null
+++ b/crates/presenter/src/dto/content/query.rs
@@ -0,0 +1,50 @@
+//! 排序方式（M109 起在 `dto/content.rs`，M162 拆出来给内容源抽象让位）。
+//!
+//! 四种排序是**两个站点都有的公共面**，各自映射到自己的参数（Modrinth 的 `index`、
+//! CurseForge 的 `sortField`）。映射函数放在各自的来源实现里，这里只有声明与稳定 slug。
+
+use serde::{Deserialize, Serialize};
+
+/// 排序方式（两个站点的官方排序项，口径对齐后再映射到各自参数）。
+#[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,
+        }
+    }
+}
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, loaders: Vec) -> 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..938ceb8
--- /dev/null
+++ b/crates/presenter/src/dto/events.rs
@@ -0,0 +1,331 @@
+//! 事件与指令：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,
+    AdoptCommand,
+    AdoptEvent,
+    AgentEvent,
+    AuthlibLoginView,
+    AuthlibRequest,
+    ContentInstallRequest,
+    ContentQuery,
+    ContentResults,
+    DeviceLoginView,
+    DiagnosisReport,
+    InstallProgressView,
+    InstanceId,
+    InstanceRuntime,
+    InstanceSummary,
+    JavaPageView,
+    LaunchArgsPatch,
+    LaunchFailureView,
+    LoaderKind,
+    LogLine,
+    LogOutcome,
+    LogSession,
+    ModFailureView,
+    ModListView,
+    ModsCommand,
+    NoticeView,
+    PackCommand,
+    PackEvent,
+    SavesCommand,
+    SavesFailureView,
+    SavesListView,
+    SessionId,
+    SettingGroupView,
+    // M159: 自更新 —— 一条快照整体替换
+    UpdateView,
+    VersionCategory,
+    VersionSummary,
+};
+use crate::toast::Toast;
+
+// M224：`AppCommand` 的构造器（从本文件搬出去守 400 行硬线，纯搬移）
+mod commands;
+
+/// 启动会话的一段实时日志（host 尾随 JSONL 后按批次发）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct LiveLogBatch {
+    /// 会话 id
+    pub session: SessionId,
+    /// 新增行
+    pub lines: Vec,
+    /// 会话是否还在跑（false = 收尾，可以触发诊断/刷新列表）
+    pub running: bool,
+}
+
+/// 一次启动收尾（磁贴状态回写 + 日志页会话列表刷新）。
+///
+/// **不带人读散文**（M161）：早先这里有一个 `summary: String`，内容是 presenter 拼的中文
+/// （`正常退出` / `崩溃（exit 1）` / `启动失败：找不到 Java`）。于是英文界面上弹出的是中文 Toast，
+/// 磁贴那行还叠成「Launch failed · 启动失败：…」。现在只给**结构**，文案由 app 层按 key 现求
+/// （与 `InstallCancelled` 同一条纪律：presenter 不依赖 `unlucky-i18n`）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct LaunchFinished {
+    /// 实例 id
+    pub id: InstanceId,
+    /// 会话 id
+    pub session: SessionId,
+    /// 结局
+    pub outcome: LogOutcome,
+    /// 进程退出码（`None` = 进程没起来 / 平台没给）
+    pub exit_code: Option,
+    /// 从 spawn 到收尾的毫秒数（没起来时是 0）
+    pub uptime_ms: u64,
+    /// 失败发生在哪一步（`None` = 这一场没有装配/启动阶段的失败；
+    /// 「跑起来又崩了」看 `outcome`）
+    pub failure: Option,
+}
+
+/// core 侧事件（不可变快照发布 + 事件流，01c §5 的三条通道之二）。
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub enum CoreEvent {
+    /// 实例列表整体刷新
+    InstancesChanged(Vec),
+    /// 单个实例运行时状态变化（启动进度/运行中/失败）
+    InstanceRuntimeChanged {
+        /// 实例 id
+        id: InstanceId,
+        /// 新状态
+        runtime: InstanceRuntime,
+    },
+    /// 下载页版本列表刷新
+    VersionListChanged(Vec),
+    /// 日志会话列表刷新
+    LogSessionsChanged(Vec),
+    /// 当前会话日志行刷新（整批替换）
+    LogLinesChanged(Vec),
+    /// 实时日志增量（启动中尾随 JSONL；`running=false` 表示会话收尾）
+    LogAppended(LiveLogBatch),
+    /// 启动收尾（磁贴状态回写 + toast）
+    LaunchFinished(LaunchFinished),
+    /// 诊断结论产出
+    DiagnosisReady(DiagnosisReport),
+    /// 账户列表刷新
+    AccountsChanged(Vec),
+    /// 微软登录状态刷新
+    DeviceLoginChanged(DeviceLoginView),
+    /// 第三方轨（authlib-injector）登录/校验状态刷新
+    AuthlibLoginChanged(AuthlibLoginView),
+    /// 账户页横幅（添加/删除/切换的结果；`None` = 清掉横幅）
+    AccountNoticeChanged(Option),
+    /// Java 页快照（发行版/回退链/运行时）
+    JavaChanged(JavaPageView),
+    /// 安装进度（`None` = 清掉进度面板）
+    InstallProgress(Option),
+    /// 用户取消了安装（**不带人读文案**）
+    ///
+    /// 为什么只有信号没有文本：`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, String>,
+    },
+    /// 设置分组刷新（设置页右栏）
+    SettingsChanged(Vec),
+    /// 横幅通知刷新（隔离切换提示/启动失败等）
+    NoticesChanged(Vec),
+    /// 内容库检索结果（M109）：**整批替换**（同一份 `query` 的命中项，含分页游标）
+    ContentResults(Box),
+    /// 内容库检索失败（M109；M162 起带大类）：没网 / 站点 5xx / 缺密钥要能分开画
+    ContentFailed(Box),
+    /// 内容库项目详情 + 版本列表（M162）：`project` 是**请求时**选中的 id，迟到结果靠它判。
+    ContentDetail {
+        /// 请求时选中的项目 id
+        project: String,
+        /// `Ok` = 详情；`Err` = 失败大类 + 原因
+        result: Box>,
+    },
+    // M113: import/export
+    /// 导入/导出（M113）：进度、结果、探测诊断、导出预检（子枚举见 [`PackEvent`]）
+    Pack(Box),
+    /// 导入已有版本（M223）：扫描 / 预检 / 完成 / 失败（子枚举见 [`AdoptEvent`]）
+    ///
+    /// 与 [`Self::Pack`] 分开是**语义**上必须的：整合包导入会把内容真搬进实例目录，
+    /// 而这里只登记盘上已有的版本、写两份配置（`versions/` 一个字节都不动）。
+    Adopt(Box),
+    /// 自更新（M159）：整份状态快照（检查结论 + 就位状态 + 用户是否已拒绝）。
+    ///
+    /// 与 `SettingsChanged` 同一条形态：快照整体替换，UI 不做增量合并。
+    Update(Box),
+    /// 本地 Mod 列表 / 启停（M224）：`Ok` = 整份快照；`Err` = 具名原因 + 原文（文案由 app 现求）。
+    Mods(Box>),
+    /// 实例存档 / 截图的只读列表（M235）：`Ok` = 整份快照；`Err` = 具名原因 + 原文。
+    ///
+    /// 与 [`Self::Mods`] 分开：这一族**没有任何写路径**（U3 只做只读列表 + 打开文件夹）。
+    Saves(Box>),
+}
+
+/// 统一事件队列的元素：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,
+    },
+    /// 写实例启动参数（M157 的「启动参数」区：JVM/游戏参数、内存、Java、图形后端）
+    ///
+    /// 补丁语义：`None` = 这一项不改；`Some("")` = 清空回「跟随全局」。
+    SetInstanceLaunchArgs {
+        /// 实例 id
+        id: InstanceId,
+        /// 五项补丁
+        patch: LaunchArgsPatch,
+    },
+    /// 刷新日志会话列表
+    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),
+    /// 取某个内容项目的详情与版本列表（M162；结果经 [`CoreEvent::ContentDetail`] 回来）
+    LoadContentDetail(Box),
+    // M113: import/export
+    /// 整合包导入/导出（M113）：导入 / 预检 / 确认写盘 / 关面板（子枚举见 [`PackCommand`]）
+    Pack(Box),
+    /// 导入已有版本（M223）：扫描 / 预检 / 确认登记 / 关面板（子枚举见 [`AdoptCommand`]）
+    Adopt(Box),
+    // M159: 自更新
+    /// 查一次更新（设置页「立即检查」；会清掉「忽略这个版本」的标记并重新请求网络）
+    CheckUpdate,
+    /// 把当前候选下载下来、校验、替换本程序（结果经 [`CoreEvent::Update`] 回来）
+    ApplyUpdate,
+    /// 忽略**这一个候选版本**（记的是版本号，不是「别再问我」）。
+    ///
+    /// 语义三条（`UpdateView::skipped` 的契约，`dto::update` 的模块文档与用例守着）：
+    /// 同一次运行里同一个版本不再弹提示条；**更高的版本照弹**（0.2.3 被忽略不影响 0.2.4）；
+    /// 设置页的「立即检查」会清掉它。候选本身仍留在快照里，设置页可手动装。
+    DismissUpdate,
+    /// 开关「启动时静默检查」。
+    ///
+    /// 落点是主配置 `config/launcher.json` 的 `update.auto_check`（M161 从更新域自己的
+    /// `cache/update/prefs.json` 迁过来的 schema 键）——`ull config get update.auto_check`
+    /// 读到的是同一个值。
+    SetUpdateAutoCheck(bool),
+    /// 本地 Mod 列表 / 启停（M224；子枚举与语义见 [`ModsCommand`] 的文档）。
+    Mods(Box),
+    /// 实例存档 / 截图的只读列表（M235；子枚举与语义见 [`SavesCommand`] 的文档）。
+    Saves(Box),
+}
+
+/// 后端通道：core/agent host 实现它；[`crate::mock::MockBackend`] 验证通道语义。
+///
+/// 轮询模型（而非回调）是为了让 Slint 的定时器成为唯一调度者，
+/// 避免跨线程回调里碰 Slint 模型。
+pub trait Backend {
+    /// 取走自上次调用以来积压的事件（FIFO，不可丢序号）。
+    fn drain_events(&mut self) -> Vec;
+
+    /// 下发一条用户意图。
+    fn dispatch(&mut self, command: AppCommand);
+
+    /// 时间推进（真实后端在这里收后台线程的结果并尾随日志）。
+    fn tick(&mut self, elapsed: std::time::Duration) {
+        let _ = elapsed;
+    }
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/presenter/src/dto/events/commands.rs b/crates/presenter/src/dto/events/commands.rs
new file mode 100644
index 0000000..66f913a
--- /dev/null
+++ b/crates/presenter/src/dto/events/commands.rs
@@ -0,0 +1,26 @@
+//! `AppCommand` 的**构造器**（从 `dto/events.rs` 搬出：那边 406 行越了 400 行硬线）。
+//!
+//! **纯搬移**：函数体、文档、可见性一字未改，只是换了文件；`impl AppCommand` 的另一个块，
+//! 于是调用点 `AppCommand::set_isolation(..)` / `AppCommand::set_launch_args(..)` 一个字都不用改。
+//! 这样 `events.rs` 只留两个枚举本体（`AppCommand` / `CoreEvent`），M224 才能在里面加
+//! `Mods` 变体而不越线。
+
+use crate::dto::{AppCommand, LaunchArgsPatch};
+
+impl AppCommand {
+    /// 构造「切换隔离档位」指令（磁贴/详情页共用）。
+    pub fn set_isolation(id: &str, mode: &str) -> Self {
+        Self::SetIsolation {
+            id: id.to_string(),
+            mode: mode.to_string(),
+        }
+    }
+
+    /// 构造「写实例启动参数」指令（详情页「启动参数」区）。
+    pub fn set_launch_args(id: &str, patch: LaunchArgsPatch) -> Self {
+        Self::SetInstanceLaunchArgs {
+            id: id.to_string(),
+            patch,
+        }
+    }
+}
diff --git a/crates/presenter/src/dto/events/tests.rs b/crates/presenter/src/dto/events/tests.rs
new file mode 100644
index 0000000..8853d68
--- /dev/null
+++ b/crates/presenter/src/dto/events/tests.rs
@@ -0,0 +1,87 @@
+//! `dto::events` 的 IPC 契约用例（M223 从 `events.rs` 尾部**纯搬移**，一行未改）。
+//!
+//! 为什么搬：M223 要给 `AppCommand` / `CoreEvent` 各加一条变体（「导入已有版本」的指令与事件），
+//! 而 `events.rs` 当时正好 399 行——加两行变体 + 两行 import 就顶破 400 行硬线（AGENTS §3.1）。
+//! 拆分口径与仓库其它拆分一致：**纯搬移、一行不改**，`mod tests;` 只是把位置挪到
+//! `dto/events/tests.rs`（`events.rs` 是非 `mod.rs` 文件，子模块目录就是 `events/`）。
+//!
+//! 搬移后 `events.rs` 只剩契约本体（枚举 + 构造器 + `Backend` trait），本文件的断言一条没动，
+//! 所以「搬移零行为变化」可以用逐行 diff 对。
+
+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::(&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::(&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..fd7b8dd
--- /dev/null
+++ b/crates/presenter/src/dto/install.rs
@@ -0,0 +1,368 @@
+//! 安装进度 DTO：下载页与新建向导共用的「一个安装任务」视图。
+//!
+//! 只放聚合量（文件计数 / 字节 / 速度 / 剩余时间）+ 一行状态文案：
+//! 逐文件的明细留在 core 的 `InstallReport`，UI 不需要也不该持有。
+//! 速度与 ETA 由 host 依据相邻两次字节数差分算（core 的事件只给绝对值）。
+
+use serde::{Deserialize, Serialize};
+
+use crate::dto::ContentFailureKind;
+
+/// 安装阶段。
+#[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)
+    }
+}
+
+/// 一条可只重试的失败的**档位**（M191；与 core 的 `FailureKind` 一一对应）。
+///
+/// ## 为什么不是一个 `bool` / 一句话
+///
+/// 「不兼容所选版本/加载器」与「取不到」要用户做的事不同：前者换版本或换加载器，后者检查网络
+/// 再试。**两档在类型上分开**，界面才能分组画两段、给两条不同的话；合并成一档之后
+/// 「重试」按钮会把一条重试必然失败的项也算进去（M191 的变异守门就钉这一条）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum InstallFailureKind {
+    /// 站点有这个项目，但目标版本/加载器下没有条目（换版本/加载器才有救）
+    Incompatible,
+    /// 取不到（没联网 / 项目不存在 / 站点出错 / 下载失败）
+    Unreachable,
+}
+
+impl InstallFailureKind {
+    /// 稳定字符串 id（日志 / 用例断言用，**不要改名**）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Incompatible => "incompatible",
+            Self::Unreachable => "unreachable",
+        }
+    }
+
+    /// 两档的固定顺序（界面分组按它排：先「换版本能救」，再「检查网络」）。
+    pub const ALL: [Self; 2] = [Self::Incompatible, Self::Unreachable];
+}
+
+/// 一条「可只重试」的失败项（M191）：项目键 + 可读标签 + 档位 + core 给的原话。
+///
+/// 这是界面画「可只重试这 N 个」和分组所需的**全部**信息：项目键就是重试时发出去的那个键
+/// （`DependencyPlan::retry_request()` 用的同一份）。
+///
+/// ## 为什么还要 `label`（M191 r1 复审 P2-1）
+///
+/// `project` 是站点 id（`P7dR8mSH`），直接画在界面上等于给用户一串哈希。可读名其实都在手边，
+/// 只是没进 DTO：根项目的名字就在请求的 `title` 里；失败文件的名字在 `PlannedNode.file.filename`
+/// 里（下载失败那种）。`label` 收的正是这两个**语言中立**的字符串（站点标题 / 文件名），
+/// **不是** `detail` 那种 core 中文散文——那会踩 i18n 的 R2（core 中文不进界面）。
+///
+/// `label` 为空是合法且**必须**保留的一档：项目不存在（404）时确实没有名字可显示，
+/// 那时界面只画 id（评审认这条兜底是合理的）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct InstallFailureView {
+    /// 请求它用的项目键（slug 或 id；重试也用它）
+    pub project: String,
+    /// 语言中立的可读标签（站点给的项目标题 / 文件名；空 = 拿不到名字）
+    pub label: String,
+    /// 哪一档
+    pub kind: InstallFailureKind,
+    /// core 给的人读说明（引擎原话 + 上下文，**不是**界面文案；**不要**画到界面上）
+    pub detail: String,
+}
+
+impl InstallFailureView {
+    /// 构造。
+    #[must_use]
+    pub fn new(
+        project: impl Into,
+        label: impl Into,
+        kind: InstallFailureKind,
+        detail: impl Into,
+    ) -> Self {
+        Self {
+            project: project.into(),
+            label: label.into(),
+            kind,
+            detail: detail.into(),
+        }
+    }
+
+    /// 界面该画的那一行：有名字就「名字 (id)」，没有就只画 id。
+    ///
+    /// 界面上**名字优先、id 次要**：名字让人认出是哪个项目，括号里的 id 是给「名字对不上时」
+    /// 或排查用的。定在这个方法里而不是视图里，是因为「有名字用名字」这条要有用例钉住。
+    #[must_use]
+    pub fn line(&self) -> String {
+        let label = self.label.trim();
+        if label.is_empty() || label == self.project {
+            self.project.clone()
+        } else {
+            format!("{label} ({})", self.project)
+        }
+    }
+}
+
+/// 一次安装的进度快照。
+#[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,
+    /// 失败大类（M162 r1）：`None` = 没失败，或失败来自不产生分类的路径。
+    ///
+    /// 放在进度快照里而不是只塞进文案：`message` 是给用户看的一句话，"没联网" 与
+    /// "这个项目不存在" 该画两种提示，判据不能靠那句话里有没有"网络"两个字。
+    pub failure_kind: Option,
+    /// 可只重试的失败项（M191）：空 = 没有失败项 ⇒ 界面**不渲染**那条入口。
+    ///
+    /// 每条自带档位（[`InstallFailureKind`]），界面按档分组；`project` 就是
+    /// `DependencyPlan::retry_request()` 会发出去的那几个项目键——名单由 plan 产出，
+    /// 界面不自己拼（拼一份就会与重试实际请求的那几个不一致）。
+    pub retry: Vec,
+}
+
+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(),
+            failure_kind: None,
+            retry: Vec::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)
+    }
+
+    /// 有可只重试的失败项吗（`false` ⇒ 界面**不渲染**那条入口，不是置灰）。
+    #[must_use]
+    pub fn has_retry(&self) -> bool {
+        !self.retry.is_empty()
+    }
+
+    /// 某一档的可重试项（两档分开画时用；顺序沿用计划里的顺序）。
+    pub fn retry_of(&self, kind: InstallFailureKind) -> impl Iterator {
+        self.retry.iter().filter(move |item| item.kind == kind)
+    }
+
+    /// 某一档有几项。
+    #[must_use]
+    pub fn retry_count(&self, kind: InstallFailureKind) -> usize {
+        self.retry_of(kind).count()
+    }
+}
+
+/// 字节数 → 人读（`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..6026bb3
--- /dev/null
+++ b/crates/presenter/src/dto/instances.rs
@@ -0,0 +1,28 @@
+//! 实例相关 DTO：磁贴与列表视图的唯一数据源。
+//!
+//! 按关注点拆成四个子模块（M222 为了给 LiteLoader 加入口而拆，纯搬移 + 新增一支）：
+//!
+//! | 子模块 | 内容 |
+//! |---|---|
+//! | [`loader`] | 加载器词表（磁贴徽标 + 向导可选）、[`LoaderInfo`] |
+//! | [`runtime`] | [`Progress`] / [`LaunchStage`] / [`InstanceRuntime`] / [`InstanceSummary`] |
+//! | [`create`] | 新建实例向导的提交请求 [`CreateRequest`] |
+//!
+//! 路径对外**一个字没变**（`unlucky_presenter::dto::InstanceSummary` 等仍从这里取），
+//! 拆的是文件不是 API。
+
+mod create;
+mod loader;
+mod runtime;
+
+#[cfg(test)]
+mod tests;
+
+pub use create::CreateRequest;
+pub use loader::{LoaderInfo, LoaderKind};
+pub use runtime::{InstanceRuntime, InstanceSummary, LaunchStage, Progress};
+
+pub use super::launch_failure::{LaunchFailureCause, LaunchFailureStage, LaunchFailureView};
+
+/// 实例标识：core::game 生成的稳定 id，app 视为不透明字符串。
+pub type InstanceId = String;
diff --git a/crates/presenter/src/dto/instances/create.rs b/crates/presenter/src/dto/instances/create.rs
new file mode 100644
index 0000000..54d7b3c
--- /dev/null
+++ b/crates/presenter/src/dto/instances/create.rs
@@ -0,0 +1,34 @@
+//! 新建实例向导提交给 host 的请求。
+
+use serde::{Deserialize, Serialize};
+
+use super::LoaderKind;
+
+/// 新建实例向导提交给 host 的请求（已通过向导校验）。
+///
+/// ⚠️ **没有「父版本」槽位**：向导/下载页只装「叠在原版上」的那一层。要把 LiteLoader 叠在
+/// Forge 上，core 侧已有真实装配路径（`LoaderSource::resolve_on` 的 `parent` 参数 +
+/// `LoaderPlanInput::parent_installed`），但把父版本从 UI 传下来需要同时扩 `CreateRequest`、
+/// 下载页草稿与向导校验三处，本轮只做原版父链（见 M222 报告「未做/待排」）。
+#[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()
+        }
+    }
+}
diff --git a/crates/presenter/src/dto/instances/loader.rs b/crates/presenter/src/dto/instances/loader.rs
new file mode 100644
index 0000000..e0ea750
--- /dev/null
+++ b/crates/presenter/src/dto/instances/loader.rs
@@ -0,0 +1,138 @@
+//! 加载器词表（磁贴徽标 + 向导可选）与 [`LoaderInfo`]。
+
+use serde::{Deserialize, Serialize};
+
+use unlucky_core::game::LoaderKind as CoreLoaderKind;
+
+/// 加载器种类（磁贴徽标 + 详情页版本链）。
+#[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",
+        }
+    }
+
+    /// 本 DTO 种类 → core 的宽种类。
+    ///
+    /// **结构映射，一个 id 字面量都没有**：词表只有一个真相源
+    /// （[`CoreLoaderKind::as_str`]），本 crate 写不进第二份。加一支 DTO 种类这里编不过。
+    const fn to_core(self) -> CoreLoaderKind {
+        match self {
+            Self::Vanilla => CoreLoaderKind::Vanilla,
+            Self::Fabric => CoreLoaderKind::Fabric,
+            Self::Quilt => CoreLoaderKind::Quilt,
+            Self::Forge => CoreLoaderKind::Forge,
+            Self::NeoForge => CoreLoaderKind::NeoForge,
+            Self::OptiFine => CoreLoaderKind::OptiFine,
+            Self::LiteLoader => CoreLoaderKind::LiteLoader,
+        }
+    }
+
+    /// core 的宽种类 → 本 DTO 种类（[`Self::to_core`] 的反向，同样不含字面量）。
+    ///
+    /// core 给 `game::LoaderKind` 加一支、而 DTO 还没跟上时，这里编不过——这正是要的：
+    /// UI 不许「新加载器默默显示成原版」。
+    const fn from_core(kind: CoreLoaderKind) -> Self {
+        match kind {
+            CoreLoaderKind::Vanilla => Self::Vanilla,
+            CoreLoaderKind::Fabric => Self::Fabric,
+            CoreLoaderKind::Quilt => Self::Quilt,
+            CoreLoaderKind::Forge => Self::Forge,
+            CoreLoaderKind::NeoForge => Self::NeoForge,
+            CoreLoaderKind::OptiFine => Self::OptiFine,
+            CoreLoaderKind::LiteLoader => Self::LiteLoader,
+        }
+    }
+
+    /// 稳定 id（`vanilla` / `fabric` / …；GUI 与 `--json` 同词表）。
+    ///
+    /// **委派**给 [`CoreLoaderKind::as_str`]（M126）：词表的源头表在 core（0.2.0 已发布契约；
+    /// 另一处逐字副本是 `ull help instances` 的词表行），这里只剩一次结构映射。
+    #[must_use]
+    pub fn as_str(self) -> &'static str {
+        self.to_core().as_str()
+    }
+
+    /// 从稳定 id 解析（未知给 `None`，由调用方决定报错文案）。
+    ///
+    /// 七个 id 的匹配委派给 [`CoreLoaderKind::parse`]；本方法只额外收 `none` / 空串这两个
+    /// **GUI 输入别名**（表单里「不装加载器」的写法）——它们不是对外输出的 id，也绝不参与
+    /// [`Self::as_str`]。
+    pub fn parse(raw: &str) -> Option {
+        let wanted = raw.trim();
+        if wanted.is_empty() || wanted.eq_ignore_ascii_case("none") {
+            return Some(Self::Vanilla);
+        }
+        Some(Self::from_core(CoreLoaderKind::parse(wanted)?))
+    }
+
+    /// 向导里的可选加载器（顺序即展示顺序）。
+    ///
+    /// 六选 = 原版 + 五家能装的。OptiFine 仍**不在这里**：它要跑外部 `optifine.Patcher` 并原地
+    /// 改 zip，core 侧至今没有安装路线（见 `DevDocs/artifacts/m218/SURVEY-p1.md` §3），
+    /// 放进向导只会让用户选完才失败。
+    pub fn wizard_choices() -> [Self; 6] {
+        [
+            Self::Vanilla,
+            Self::Fabric,
+            Self::Quilt,
+            Self::Forge,
+            Self::NeoForge,
+            Self::LiteLoader,
+        ]
+    }
+}
+
+/// 加载器 + 版本（例如 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)
+        }
+    }
+}
diff --git a/crates/presenter/src/dto/instances/runtime.rs b/crates/presenter/src/dto/instances/runtime.rs
new file mode 100644
index 0000000..cd80361
--- /dev/null
+++ b/crates/presenter/src/dto/instances/runtime.rs
@@ -0,0 +1,115 @@
+//! 进度 / 阶段 / 运行时状态 / 实例摘要（磁贴与列表的唯一数据源）。
+
+use std::path::PathBuf;
+
+use serde::{Deserialize, Serialize};
+
+use super::super::LaunchArgsView;
+use super::{InstanceId, LoaderInfo};
+
+/// 字节进度；`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,
+    },
+    /// 上次启动失败（磁贴显示「重试」）
+    ///
+    /// M161 之前这里只有一个 `reason: String`，而且里面已经写着「启动失败：…」——
+    /// 界面再包一层就成了「英文前缀 + 中文句子」，中文界面则是「启动失败 · 启动失败：…」。
+    /// 现在给的是结构化原因（见 [`crate::dto::LaunchFailureCause`]）：**没起来**与**起来又崩**是两种形状，
+    /// 界面各说各的话（复审 P1-1：早先崩溃被说成「启动游戏进程失败」）。
+    Failed {
+        /// 这一场为什么是失败态
+        cause: crate::dto::LaunchFailureCause,
+    },
+}
+
+/// 实例摘要：磁贴/列表视图唯一数据源。
+#[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,
+    /// 运行时状态
+    pub runtime: InstanceRuntime,
+    /// 实例图标路径（P0 直接给路径；P1 换成 core 提供的图像句柄）
+    pub icon: Option,
+    /// 隔离档位（`isolated` / `shared` / `custom`；未知为空）
+    pub isolation: String,
+    /// 该实例绑定的版本 id（详情页/启动用）
+    pub version_id: String,
+    /// 版本本体是否在盘上（缺载荷时磁贴亮黄条）
+    pub version_present: bool,
+    /// 启动参数（M157：实例配置页「启动参数」区的数据；含三级回落后的生效值与版本门槛）
+    pub launch: LaunchArgsView,
+}
diff --git a/crates/presenter/src/dto/instances/tests.rs b/crates/presenter/src/dto/instances/tests.rs
new file mode 100644
index 0000000..4ff5481
--- /dev/null
+++ b/crates/presenter/src/dto/instances/tests.rs
@@ -0,0 +1,148 @@
+//! 实例 DTO 的单测（词表契约 / 徽标 / 序列化往返）。
+
+use super::*;
+use unlucky_core::game::LoaderKind as CoreLoaderKind;
+
+use crate::dto::LaunchArgsView;
+
+#[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");
+    let liteloader = LoaderInfo {
+        kind: LoaderKind::LiteLoader,
+        version: "1.12.2-SNAPSHOT".to_string(),
+    };
+    assert_eq!(liteloader.badge(), "LiteLoader 1.12.2-SNAPSHOT");
+    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);
+}
+
+/// 向导可选集：**每一支都能被 core 的安装侧接受**（OptiFine 不在其中，因为它装不了）。
+///
+/// 抓得住：把 OptiFine 塞进向导（选完才失败）、漏掉 LiteLoader（GUI 走不到真实路线）。
+#[test]
+fn wizard_choices_are_all_installable() {
+    let installable: Vec<&str> = LoaderKind::wizard_choices()
+        .iter()
+        .filter(|kind| **kind != LoaderKind::Vanilla)
+        .map(|kind| kind.as_str())
+        .collect();
+    for id in &installable {
+        assert!(
+            unlucky_core::addon::loader::LoaderKind::parse(id).is_some(),
+            "`{id}` 在向导里但安装侧不认"
+        );
+    }
+    assert_eq!(installable.len(), 5, "原版 + 五家能装的：{installable:?}");
+    assert!(!installable.contains(&"optifine"));
+}
+
+/// 对外契约：七个 id 在测试里**独立抄一遍**（0.2.0 已发布形状），并与 core 的 `ALL` 做
+/// **集合比较**——这是对外词表的守卫（与 CLI 的 help 守卫互补）。显示路径另有守卫：
+/// `presenter::host::game::every_core_loader_kind_reaches_the_tile_as_itself`（按 `ALL` 遍历）。
+///
+/// 为什么不是编译器管：编译期只拦得到「漏 match」，而新种类在还有 match 的消费方用最省事的
+/// `=> Vanilla` 糊过去**编得过**，那时新加载器会静默显示成原版（`game::loader` 模块文档
+/// 第 ③ 步）。对外词表由下面第 ② 段的集合断言守，显示路径由上面那条测试守。
+///
+/// 抓得住：改词表（`neoforge` → `neo_forge`）；**新增一家加载器而没主动更新这份契约**
+/// （core 的 `ALL` 多一支 ⇒ 集合不等）；DTO 委派接错支（`OptiFine` 映到 `LiteLoader`）；
+/// `parse` 收进不该有的别名。
+/// 抓不住：core 的解析规则（那是 `game::loader` 的
+/// `every_stable_id_parses_back_to_its_kind` 等测试的职责），以及真二进制输出面的 JSON
+/// （CLI 的 `json_rows_expose_loader_kind_and_version`）。
+#[test]
+fn loader_kind_ids_are_the_released_contract() {
+    const CONTRACT: [(LoaderKind, &str); 7] = [
+        (LoaderKind::Vanilla, "vanilla"),
+        (LoaderKind::Fabric, "fabric"),
+        (LoaderKind::Quilt, "quilt"),
+        (LoaderKind::Forge, "forge"),
+        (LoaderKind::NeoForge, "neoforge"),
+        (LoaderKind::OptiFine, "optifine"),
+        (LoaderKind::LiteLoader, "liteloader"),
+    ];
+
+    // ① DTO 这一层：每支的 id、反查、大小写。
+    for (kind, id) in CONTRACT {
+        assert_eq!(kind.as_str(), id, "{kind:?} 的稳定 id 变了");
+        assert_eq!(LoaderKind::parse(id), Some(kind), "`{id}` 认不回来");
+        let upper = id.to_ascii_uppercase();
+        assert_eq!(LoaderKind::parse(&upper), Some(kind), "大写 `{upper}`");
+    }
+
+    // ② core 的词表 ↔ 这份契约：**集合相等**才过（多一支、少一支、改一个字都红）。
+    let mut actual: Vec<&str> = CoreLoaderKind::ALL
+        .iter()
+        .map(|kind| kind.as_str())
+        .collect();
+    actual.sort_unstable();
+    let mut expected: Vec<&str> = CONTRACT.iter().map(|(_, id)| *id).collect();
+    expected.sort_unstable();
+    assert_eq!(
+        actual, expected,
+        "core 的 `LoaderKind::ALL` 必须逐字等于对外契约：加一家加载器时先改这里 + help"
+    );
+
+    // GUI 输入别名（不是对外 id）：不装加载器有三种写法；别名与拼法都不许混进词表。
+    for alias in ["none", "", "   "] {
+        assert_eq!(
+            LoaderKind::parse(alias),
+            Some(LoaderKind::Vanilla),
+            "`{alias}`"
+        );
+    }
+    assert_eq!(LoaderKind::parse("neo-forge"), 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,
+        launch: LaunchArgsView::default(),
+    };
+    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,
+    /// 是否已装过这家（托管目录里有现成的）
+    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,
+    /// 回退链（计划链或上一次安装的真实链）
+    pub chain: Vec,
+    /// 本地运行时
+    pub runtimes: Vec,
+    /// 托管目录
+    pub managed_roots: Vec,
+    /// 是否有 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 {
+        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 {
+        let mut majors: Vec = 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/launch_args.rs b/crates/presenter/src/dto/launch_args.rs
new file mode 100644
index 0000000..3ec1c08
--- /dev/null
+++ b/crates/presenter/src/dto/launch_args.rs
@@ -0,0 +1,136 @@
+//! 实例启动参数 DTO（M157）：实例配置页「启动参数」区的唯一数据源 + 写回补丁。
+//!
+//! 口径三条：
+//! 1. **实例层与生效值分开给**：`jvm_args` 等是实例文件里的原文（空 = 跟随全局），
+//!    `*_effective` 是三级回落（实例 → 全局 → 默认）之后真正会下发的值。UI 要把两件事同时
+//!    画出来（「留空 = 跟随全局 {global}」这种提示与「生效值」是两回事）；
+//! 2. **图形后端的可选值与门槛由 host 算好**：`graphics_backend_options` 来自 core 的词表
+//!    （[`LaunchArgsView::graphics_backend_options`]），`graphics_backend_allowed` 来自 core 的
+//!    版本门槛判定——UI 不复制任何一条判据（任务书：判定用 core capability）；
+//! 3. **本模块不含 core 类型**（D42：dto 只放扁平 IPC 类型）。
+//!
+//! 补丁的「不改 / 清空」二分：`None` = 这一项不动；`Some("")` = 清空（回到跟随）。
+
+use serde::{Deserialize, Serialize};
+
+/// 实例启动参数的**读取**视图（详情页「启动参数」区）。
+#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
+pub struct LaunchArgsView {
+    /// 实例 id。
+    pub instance_id: String,
+    /// 实例层 JVM 参数原文（空 = 只用全局 `java.extra_args`）。
+    pub jvm_args: String,
+    /// 实例层游戏参数原文（空 = 不追加）。
+    pub game_args: String,
+    /// 实例层最大堆（`None` = 跟随全局）。
+    pub memory_mb: Option,
+    /// 生效最大堆（三级回落 + 出厂默认，恒有值）。
+    pub memory_effective_mb: u32,
+    /// 实例层 Java 可执行文件原文（空 = 跟随全局 / 自动挑）。
+    pub java_path: String,
+    /// 生效 Java 可执行文件（空 = 自动挑；展示用，不代表已探测）。
+    pub java_effective: String,
+    /// 实例层图形后端（`default` / `opengl` / `vulkan`）。
+    pub graphics_backend: String,
+    /// 生效图形后端（三级回落之后）。
+    pub graphics_backend_effective: String,
+    /// 该实例版本能不能用 `--graphicsBackend`（core 的版本门槛判定；`false` ⇒ UI 灰化 + 提示）。
+    pub graphics_backend_allowed: bool,
+    /// 判定所依据的游戏版本（提示文案「需 MC 26.2+」旁边给出实际版本）。
+    pub mc_version: String,
+    /// 门槛的最低版本（core 的 `GRAPHICS_BACKEND_MIN_VERSION`；文案与测试共用一份来源）。
+    pub graphics_backend_min_version: String,
+    /// 图形后端三态的词表（顺序即下拉顺序；来自 core，不让 UI 手抄）。
+    pub graphics_backend_options: Vec,
+}
+
+impl LaunchArgsView {
+    /// 三态下拉的 id → 是不是当前生效值（UI 高亮用；未知值原样比较）。
+    #[must_use]
+    pub fn is_effective_backend(&self, id: &str) -> bool {
+        self.graphics_backend_effective == id
+    }
+}
+
+/// 实例启动参数的**写回**补丁（GUI 表单与 CLI 共用）。
+///
+/// 每个字段：`None` = 不改；`Some("")` = 清空（回到跟随下一层）。
+#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
+pub struct LaunchArgsPatch {
+    /// 实例层 JVM 参数（文本，空白分隔）。
+    pub jvm_args: Option,
+    /// 实例层游戏参数（文本）。
+    pub game_args: Option,
+    /// 实例层最大堆（文本形态，host 解析；空 = 跟随全局）。
+    pub memory_mb: Option,
+    /// 实例层 Java 可执行文件。
+    pub java_path: Option,
+    /// 实例层图形后端（`default` / `opengl` / `vulkan`）。
+    pub graphics_backend: Option,
+}
+
+impl LaunchArgsPatch {
+    /// 是否什么都不改（UI 没动过表单时的短路）。
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.jvm_args.is_none()
+            && self.game_args.is_none()
+            && self.memory_mb.is_none()
+            && self.java_path.is_none()
+            && self.graphics_backend.is_none()
+    }
+
+    /// 只改图形后端（下拉切换的最小补丁）。
+    #[must_use]
+    pub fn backend(id: &str) -> Self {
+        Self {
+            graphics_backend: Some(id.to_string()),
+            ..Self::default()
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn empty_patch_touches_nothing() {
+        assert!(LaunchArgsPatch::default().is_empty());
+        assert!(!LaunchArgsPatch::backend("vulkan").is_empty());
+        // `Some("")` 是「清空」而不是「不改」——两者不能折叠成一个判据。
+        let clear = LaunchArgsPatch {
+            jvm_args: Some(String::new()),
+            ..LaunchArgsPatch::default()
+        };
+        assert!(!clear.is_empty());
+    }
+
+    #[test]
+    fn view_round_trips_as_ipc() {
+        let view = LaunchArgsView {
+            instance_id: "inst-1".to_string(),
+            jvm_args: "-XX:+UseG1GC".to_string(),
+            game_args: String::new(),
+            memory_mb: Some(4096),
+            memory_effective_mb: 4096,
+            java_path: String::new(),
+            java_effective: "C:/jdk21/bin/java.exe".to_string(),
+            graphics_backend: "vulkan".to_string(),
+            graphics_backend_effective: "vulkan".to_string(),
+            graphics_backend_allowed: true,
+            mc_version: "26.2-snapshot-2".to_string(),
+            graphics_backend_min_version: "26.2-snapshot-2".to_string(),
+            graphics_backend_options: vec![
+                "default".to_string(),
+                "opengl".to_string(),
+                "vulkan".to_string(),
+            ],
+        };
+        let text = serde_json::to_string(&view).expect("序列化");
+        let back: LaunchArgsView = serde_json::from_str(&text).expect("反序列化");
+        assert_eq!(back, view);
+        assert!(back.is_effective_backend("vulkan"));
+        assert!(!back.is_effective_backend("opengl"));
+    }
+}
diff --git a/crates/presenter/src/dto/launch_failure.rs b/crates/presenter/src/dto/launch_failure.rs
new file mode 100644
index 0000000..acf3c3a
--- /dev/null
+++ b/crates/presenter/src/dto/launch_failure.rs
@@ -0,0 +1,152 @@
+//! 启动失败的**结构**（M161：presenter 只给阶段 + 原文，文案由界面按 i18n key 现求）。
+//!
+//! 从 `dto/instances.rs` 拆出：那边贴着 400 行硬线，而这两个类型是「启动」这条线上的
+//! 独立一块（磁贴状态行、收尾事件、Toast 三处都读它）。
+
+use serde::{Deserialize, Serialize};
+
+/// 启动失败发生在**哪一步**（M161：界面文案按它选 i18n key，presenter 不写散文）。
+///
+/// 分档只在「用户该去做什么」不同的地方切，不按代码结构切：
+///
+/// | 档 | 意思 | 用户下一步 |
+/// |---|---|---|
+/// | [`Self::VersionManifest`] | `versions/.json` 读不出来 / 解析不了 | 去版本管理重装这个版本 |
+/// | [`Self::Inheritance`] | 继承链断了（父版本缺失） | 同上（父版本缺了） |
+/// | [`Self::InstanceConfig`] | 实例设置文件读不出来 | 去实例页看一眼那个实例 |
+/// | [`Self::Isolation`] | 隔离目录派生失败（路径/权限） | 换隔离档位或修目录权限 |
+/// | [`Self::Identity`] | 账户装配失败（找不到账户 / 凭据过期） | 去账户页重新登录 |
+/// | [`Self::Spawn`] | 命令行装配完了但进程起不来 | 看 Java 与日志 |
+///
+/// 「跑起来了但崩了」不在这张表里：那是**结局**，由 `LogOutcome` 表达（三个变体各有 i18n key）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum LaunchFailureStage {
+    /// 版本 JSON 读不出来 / 解析不了
+    VersionManifest,
+    /// 继承链断裂
+    Inheritance,
+    /// 实例设置文件读不出来
+    InstanceConfig,
+    /// 隔离目录派生失败
+    Isolation,
+    /// 账户装配失败
+    Identity,
+    /// 进程起不来
+    Spawn,
+}
+
+impl LaunchFailureStage {
+    /// 稳定 slug（日志 / 事件流 / 测试用；**不要改名**）。
+    #[must_use]
+    pub const fn slug(self) -> &'static str {
+        match self {
+            Self::VersionManifest => "version_manifest",
+            Self::Inheritance => "inheritance",
+            Self::InstanceConfig => "instance_config",
+            Self::Isolation => "isolation",
+            Self::Identity => "identity",
+            Self::Spawn => "spawn",
+        }
+    }
+}
+
+/// 一次启动失败：**哪一步** + 那一步的原文。
+///
+/// `detail` 是当场的原始错误文本（core / io / 账户层给的），**故意不翻译**：里面有路径、
+/// 版本 id、HTTP 状态这类机器细节，翻成人话就丢了取证价值。要本地化的是「哪一步」
+/// （[`LaunchFailureStage`]），界面按它选词。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct LaunchFailureView {
+    /// 失败阶段
+    pub stage: LaunchFailureStage,
+    /// 原始错误文本（不翻译）
+    pub detail: String,
+}
+
+impl LaunchFailureView {
+    /// 建一条。
+    pub fn new(stage: LaunchFailureStage, detail: impl Into) -> Self {
+        Self {
+            stage,
+            detail: detail.into(),
+        }
+    }
+}
+
+/// 磁贴/详情上「这一场为什么是失败态」的**完整原因**。
+///
+/// 两种**互斥**的形状，混成一种就会说假话（M161 复审 P1-1 抓的就是这个）：
+///
+/// | 形状 | 意思 | 界面该说什么 |
+/// |---|---|---|
+/// | [`Self::Stage`] | 进程**没起来**（装配/启动阶段失败） | 「启动失败 · <哪一步>：<原文>」 |
+/// | [`Self::Crashed`] | 进程起来过，**崩了** | 「启动失败 · 游戏崩溃（退出码 N）」 |
+/// | [`Self::SilentFailure`] | 进程起来过，但 exit 0 却没真正跑起来 | 「启动失败 · 退出码 0，但游戏没起来」 |
+///
+/// 为什么把结局也放在这里：磁贴的状态行与 Toast 必须说同一件事。早先「起来了又崩」被
+/// 硬塞进 [`LaunchFailureStage::Spawn`]（因为 `LaunchFinished.failure` 在这次是 `None`），
+/// 于是磁贴写「启动游戏进程失败」而 Toast 写「游戏崩溃」——同一时刻两句话打架，而且
+/// `detail` 还漏出了 `exit Some(1)` 这种 Rust Debug 文本。
+///
+/// `detail` 只在 [`Self::Stage`] 里有：那是 core / io 给的原文（路径、版本 id、os error），
+/// **故意不翻译**。结局类没有什么「原文」可给，退出码是数字，措辞由界面按语言出。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum LaunchFailureCause {
+    /// 装配/启动阶段失败：进程**没起来**
+    Stage {
+        /// 失败在上面的哪一步
+        stage: LaunchFailureStage,
+        /// 那一步的原始错误文本（不翻译）
+        detail: String,
+    },
+    /// 进程起来过，结局是崩溃
+    Crashed {
+        /// 退出码（`None` = 平台没给）
+        exit_code: Option,
+    },
+    /// 进程起来过，但疑似静默失败（exit 0 却没真正跑起来）
+    SilentFailure {
+        /// 退出码（通常是 0）
+        exit_code: Option,
+    },
+}
+
+impl LaunchFailureCause {
+    /// 稳定 slug（日志 / 测试用；**不要改名**）。
+    #[must_use]
+    pub const fn slug(&self) -> &'static str {
+        match self {
+            Self::Stage { .. } => "stage",
+            Self::Crashed { .. } => "crashed",
+            Self::SilentFailure { .. } => "silent_failure",
+        }
+    }
+
+    /// 进程到底有没有起来过。
+    #[must_use]
+    pub const fn started(&self) -> bool {
+        !matches!(self, Self::Stage { .. })
+    }
+
+    /// 由一次收尾组装原因。
+    ///
+    /// `failure` 有值 = 装配/启动阶段失败（进程没起来）；`None` = 跑起来了，此时**只能**
+    /// 看 `outcome`（`Ok` 不该走到这里，兜底按崩溃处理）。
+    #[must_use]
+    pub fn of(
+        outcome: crate::dto::LogOutcome,
+        failure: Option<&LaunchFailureView>,
+        exit_code: Option,
+    ) -> Self {
+        match failure {
+            Some(failure) => Self::Stage {
+                stage: failure.stage,
+                detail: failure.detail.clone(),
+            },
+            None if outcome == crate::dto::LogOutcome::SilentFail => {
+                Self::SilentFailure { exit_code }
+            }
+            None => Self::Crashed { exit_code },
+        }
+    }
+}
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,
+}
+
+/// 诊断结论 + 归属会话（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..db68d1d
--- /dev/null
+++ b/crates/presenter/src/dto/mod.rs
@@ -0,0 +1,99 @@
+//! 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;
+// M223: 导入已有版本（从别的启动器只读登记 versions/）
+mod adopt;
+mod agent;
+mod content;
+mod events;
+mod install;
+mod instances;
+mod java;
+// M157: 实例启动参数（启动参数区的读取视图 + 写回补丁）
+mod launch_args;
+mod launch_failure;
+mod logs;
+mod notices;
+// M113: import/export —— 整合包导入/导出的 DTO（M111/M112 管线的 IPC 面）
+mod pack;
+// M224: 本地 Mod 列表与启停（实例详情页的 MODS 区）
+mod mods;
+// M235: 实例存档 / 截图的只读列表（详情页的「存档」区）
+mod saves;
+mod settings;
+// M159: 自更新（检查结论 / 候选 / 就位状态）
+mod update;
+mod versions;
+
+pub use accounts::{
+    looks_like_jwt, redact, valid_offline_name, AccountKind, AccountNotice, AccountNoticeCode,
+    AccountView, AuthlibLoginView, AuthlibRequest, BrowserLoginNote, DeviceLoginPhase,
+    DeviceLoginView, LoginFailure, SkinImage, REDACTED,
+};
+pub use adopt::{
+    AdoptCandidateView, AdoptCommand, AdoptDoneView, AdoptEvent, AdoptFailureView,
+    AdoptIsolationView, AdoptPlanView, AdoptProblemView, AdoptRequestView, AdoptScanView,
+    AdoptStage, AdoptState, AdoptTargetView,
+};
+pub use agent::{AgentEvent, ChatMessage, ChatRole, ConfirmRequest, Sensitivity, ToolCallView};
+pub use content::{
+    loader_facet, ContentDetail, ContentDetailRequest, ContentFailure, ContentFailureKind,
+    ContentHit, ContentInstallRequest, ContentKind, ContentQuery, ContentResults, ContentSort,
+    ContentSource, ContentState, ContentVersionView,
+};
+pub use events::{AppCommand, AppEvent, Backend, CoreEvent, LaunchFinished, LiveLogBatch};
+pub use install::{
+    derive_speed, human_bytes, InstallFailureKind, InstallFailureView, InstallProgressView,
+    InstallStage,
+};
+pub use instances::{
+    CreateRequest, InstanceId, InstanceRuntime, InstanceSummary, LaunchFailureCause,
+    LaunchFailureStage, LaunchFailureView, LaunchStage, LoaderInfo, LoaderKind, Progress,
+};
+pub use java::{JavaChainOutcome, JavaChainStep, JavaPageView, JavaRuntimeView, JavaVendorView};
+pub use launch_args::{LaunchArgsPatch, LaunchArgsView};
+pub use logs::{Diagnosis, DiagnosisReport, LogLevel, LogLine, LogOutcome, LogSession, SessionId};
+// M224: 本地 Mod 列表与启停
+pub use mods::{
+    locate, ModEntryView, ModFailureKind, ModFailureView, ModListView, ModSkipKind, ModSkipView,
+    ModsCommand,
+};
+pub use notices::{NoticeLevel, NoticeView};
+// M113: import/export
+pub use pack::{
+    ConflictChoiceView, ConflictDecisionView, ConflictDecisionsView, ConflictFileView,
+    ConflictReasonView, ConflictSourceView, ExportClassView, ExportDoneView, ExportFileView,
+    ExportPreviewView, ExportReasonView, ExportRequestView, ExportState, FileActionView,
+    ImportCancelView, ImportConflictView, ImportErrorView, ImportFailureStageView,
+    ImportProgressView, ImportReportView, ImportRequestView, ImportScanView, ImportStageView,
+    ImportState, ImportStatusView, ImportedFileView, MissingFileView, MissingReasonView,
+    PackCommand, PackEvent, PackFormatView, PackState, ProbeView,
+};
+pub use settings::{
+    find_row, SettingControl, SettingGroupView, SettingRowView, JAVA_REFRESH_ACTION,
+};
+// M235: 实例存档 / 截图的只读列表（M251 加逐张缩略图预览）
+pub use saves::{
+    SavesArea, SavesCommand, SavesFailureKind, SavesFailureOp, SavesFailureView, SavesListView,
+    SavesOped, SavesSkipKind, SavesSkipView, ScreenshotPreview, ScreenshotThumbFailure,
+    ScreenshotThumbKind, ScreenshotView, ThumbnailView, WorldView,
+};
+// M159: 自更新
+pub use update::{
+    ReadyUpdate, UpdateBanner, UpdateCandidateView, UpdateFailureView, UpdateOutcome, UpdateView,
+};
+pub use versions::{AncientKind, VersionCategory, VersionKind, VersionSummary};
diff --git a/crates/presenter/src/dto/mods.rs b/crates/presenter/src/dto/mods.rs
new file mode 100644
index 0000000..0c8e0f6
--- /dev/null
+++ b/crates/presenter/src/dto/mods.rs
@@ -0,0 +1,238 @@
+//! 本地 Mod 列表与启停的 IPC 面（M224 · MODTOGGLE）。
+//!
+//! M218 的结论是这块要**新建三层**（core 读写目录 + presenter DTO + 实例详情页），且**不许**
+//! 给内容页加第五个 `ContentKind`（会打断 4 处穷尽 match）。本文件是中间那层：
+//!
+//! | 方向 | 类型 |
+//! |---|---|
+//! | app → host | [`ModsCommand`]（列目录 / 启停一个文件） |
+//! | host → app | [`ModListView`]（整份快照）或 [`ModFailureView`]（具名原因） |
+//!
+//! ## 为什么不复用内容页的 `ContentInstallRequest`
+//!
+//! 那条通路是「远端 → 本地」，入口在内容页；启停是「本地 → 本地」，入口在实例详情页。
+//! 把两者塞进一个 DTO 会让内容页为了一个它不画的字段多一次穷尽 match——正是 §3 点名要避免的。
+//!
+//! ## 文案纪律（M161）
+//!
+//! 本模块**不带人读散文**：失败给的是结构（[`ModFailureKind`] + 底层 detail 串），
+//! 由 app 层按 i18n key 现求。`detail` 是 OS 原文（`Access is denied.` 之类），只进括号，
+//! 不进主句——主句必须能翻译。
+
+use serde::{Deserialize, Serialize};
+
+use crate::dto::{InstanceId, InstanceSummary};
+
+/// app → host 的本地 Mod 指令。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ModsCommand {
+    /// 列某个实例的 `mods/`（进详情页时发、启停成功后 host 自己再发一次）。
+    List(InstanceId),
+    /// 启停一个文件（`file` 是**磁盘上的文件名**，含后缀）。
+    SetEnabled {
+        /// 实例 id
+        id: InstanceId,
+        /// 磁盘文件名（`sodium.jar.disabled`）
+        file: String,
+        /// 期望的启用状态
+        enabled: bool,
+    },
+}
+
+/// 列表里的一条。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ModEntryView {
+    /// 磁盘文件名（含 `.disabled` / `.old`，UI 的开关消息原样带回去）。
+    pub file: String,
+    /// 展示名（去掉两个后缀）。
+    pub name: String,
+    /// 是否启用。
+    pub enabled: bool,
+    /// 字节数（UI 自己格式化，不在这里拼 "1.2 MiB"）。
+    pub bytes: u64,
+    /// 是否带 `.old`（旧版本残留，只展示不清理）。
+    pub old: bool,
+}
+
+/// 没列出来的一条（UI 只需计数 + 一句"为什么"）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ModSkipView {
+    /// 文件名。
+    pub file: String,
+    /// 跳过原因（结构，不翻译）。
+    pub reason: ModSkipKind,
+}
+
+/// 跳过的原因（与 core 的 `addon::mods::SkipReason` 一一对应）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ModSkipKind {
+    /// 符号链接（不跟随）。
+    SymbolicLink,
+    /// 不是普通文件（目录 / 设备）。
+    NotAFile,
+    /// 名字过不了路径规则。
+    UnsafeName,
+    /// 元数据读不出来。
+    Unreadable,
+}
+
+/// 一次列目录的完整快照（**整体替换**，不做增量）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ModListView {
+    /// 实例 id
+    pub instance: InstanceId,
+    /// 被列的 `mods/` 目录（绝对路径，UI 的"打开文件夹"用）。
+    pub dir: String,
+    /// 目录存不存在（`false` = 这个实例还没装过 mod）。
+    pub exists: bool,
+    /// 列表（按展示名排序）。
+    pub entries: Vec,
+    /// 跳过条目。
+    pub skipped: Vec,
+    /// 这一份快照采样的时刻，游戏是否在该实例上运行（运行中开关只读）。
+    pub running: bool,
+    /// 采样时的实例快照里有没有这个实例（`false` = 实例被删了，页面该退回列表）。
+    pub known: bool,
+}
+
+impl ModListView {
+    /// 启用中的条数。
+    #[must_use]
+    pub fn enabled_count(&self) -> usize {
+        self.entries.iter().filter(|entry| entry.enabled).count()
+    }
+
+    /// 禁用中的条数。
+    #[must_use]
+    pub fn disabled_count(&self) -> usize {
+        self.entries.len() - self.enabled_count()
+    }
+}
+
+/// 一次启停失败的具名原因（app 按 key 现求文案）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ModFailureView {
+    /// 实例 id（迟到/串台的结果靠它判）。
+    pub instance: InstanceId,
+    /// 涉及的文件（列表里没有时为空串）。
+    pub file: String,
+    /// 失败大类。
+    pub kind: ModFailureKind,
+    /// 底层原文（OS 错误 / 路径细节）；只进括号，不进主句。
+    pub detail: String,
+}
+
+/// 失败大类。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ModFailureKind {
+    /// 文件名不是裸文件名。
+    UnsafeName,
+    /// `mods/` 不可用（不存在 / 符号链接 / 不是目录 / 读不了）。
+    ModsDirUnusable,
+    /// 文件不在了。
+    NotFound,
+    /// 目标不是普通文件。
+    NotARegularFile,
+    /// 目标名已被占用（不覆盖）。
+    Collision,
+    /// 改名失败。
+    Rename,
+    /// 实例不在了（快照里找不到），或隔离档位派生不出运行目录。
+    InstanceUnavailable,
+    /// 游戏正在这个实例上运行（host 侧主动挡：Windows 上 rename 会失败，别让用户猜）。
+    Running,
+}
+
+/// 实例 id 在快照里的最小定位结果（`None` = 实例已不在）。
+#[must_use]
+pub fn locate<'a>(instances: &'a [InstanceSummary], id: &str) -> Option<&'a InstanceSummary> {
+    instances
+        .iter()
+        .find(|instance| instance.id == id || instance.name == id)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::dto::InstanceRuntime;
+
+    fn summary(id: &str, name: &str) -> InstanceSummary {
+        InstanceSummary {
+            id: id.to_string(),
+            name: name.to_string(),
+            mc_version: "1.20.1".to_string(),
+            loader: crate::dto::LoaderInfo {
+                kind: crate::dto::LoaderKind::Vanilla,
+                version: String::new(),
+            },
+            last_played: None,
+            runtime: InstanceRuntime::Idle,
+            icon: None,
+            isolation: "isolated".to_string(),
+            version_id: "1.20.1".to_string(),
+            version_present: true,
+            launch: crate::dto::LaunchArgsView::default(),
+        }
+    }
+
+    /// 快照计数与 IPC round-trip（AGENTS §6：跨界类型必须能序列化）。
+    #[test]
+    fn view_counts_and_round_trips() {
+        let view = ModListView {
+            instance: "inst".to_string(),
+            dir: "/tmp/run/mods".to_string(),
+            exists: true,
+            entries: vec![
+                ModEntryView {
+                    file: "a.jar".to_string(),
+                    name: "a.jar".to_string(),
+                    enabled: true,
+                    bytes: 10,
+                    old: false,
+                },
+                ModEntryView {
+                    file: "b.jar.disabled".to_string(),
+                    name: "b.jar".to_string(),
+                    enabled: false,
+                    bytes: 20,
+                    old: false,
+                },
+            ],
+            skipped: Vec::new(),
+            running: false,
+            known: true,
+        };
+        assert_eq!(view.enabled_count(), 1);
+        assert_eq!(view.disabled_count(), 1);
+
+        let text = serde_json::to_string(&view).expect("序列化");
+        let back: ModListView = serde_json::from_str(&text).expect("反序列化");
+        assert_eq!(back, view);
+
+        let command = ModsCommand::SetEnabled {
+            id: "inst".to_string(),
+            file: "a.jar".to_string(),
+            enabled: false,
+        };
+        let text = serde_json::to_string(&command).expect("序列化");
+        assert_eq!(
+            serde_json::from_str::(&text).expect("反序列化"),
+            command
+        );
+    }
+
+    /// 定位：id 优先、名字兜底（与 `launch_target` 同口径）。
+    #[test]
+    fn locate_matches_by_id_then_name() {
+        let instances = vec![summary("survival", "生存"), summary("other", "别的")];
+        assert_eq!(
+            locate(&instances, "survival").map(|entry| entry.name.as_str()),
+            Some("生存")
+        );
+        assert_eq!(
+            locate(&instances, "别的").map(|entry| entry.id.as_str()),
+            Some("other")
+        );
+        assert!(locate(&instances, "gone").is_none());
+    }
+}
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(¬ice).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..a6bf806
--- /dev/null
+++ b/crates/presenter/src/dto/pack.rs
@@ -0,0 +1,63 @@
+//! 整合包导入/导出 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 必须让这两类**视觉可区分**——并且致命那一类还要按
+//!    [`ImportReportView::failure_stage`] 再分三档说（预检没过 / 已回滚 / 回滚没做完，M161）；
+//! 3. **导出的三分类**（[`ExportClassView`]）：`Inline` 是「证明不了可被远程替代，原字节进
+//!    `overrides/`」，`Skipped` 是「压根没进包」。`skipped > 0` 意味着包**不完整**。
+//!
+//! ## 文件分工（守 400 行）
+//!
+//! | 文件 | 职责 |
+//! |---|---|
+//! | [`format`] | [`PackFormatView`]（三个格式 + slug 对齐） |
+//! | [`import`] | 请求 / 进度 / 三态 / 逐项原因 / 探测诊断 |
+//! | [`conflict`] | 冲突成因、处置、三方哈希 |
+//! | [`export`] | 三分类 / 逐条原因 / 预检 |
+//!
+//! ## 冲突：预检清单 → 用户点头 → 事后账（M160）
+//!
+//! 三样东西在三处，别混：
+//!
+//! | 类型 | 时机 | 语义 |
+//! |---|---|---|
+//! | [`ImportScanView`] / [`ImportConflictView`] | 导入**前**（[`PackEvent::Scan`]） | 待用户点头的冲突清单 |
+//! | [`ConflictDecisionsView`] | 页面 → 宿主（[`ImportRequestView::decisions`]） | 全部保留 / 全部覆盖 / 逐项 |
+//! | [`ConflictFileView`] | 导入**后**（[`PackEvent::Report`]） | 每条实际怎么处置的 |
+//!
+//! 两处缺省都是**保留**（[`ConflictDecisionsView::default`] = `KeepAll`，core 的
+//! `ConflictChoice::default()` = `KeepUser`）：**绝不默认覆盖用户已有文件**。
+
+mod conflict;
+mod event;
+mod export;
+mod format;
+mod import;
+
+pub use conflict::{
+    ConflictChoiceView, ConflictDecisionView, ConflictDecisionsView, ConflictFileView,
+    ConflictReasonView, ConflictSourceView, ImportConflictView, ImportScanView,
+};
+pub use event::{PackCommand, PackEvent, PackState};
+pub use export::{
+    ExportClassView, ExportDoneView, ExportFileView, ExportPreviewView, ExportReasonView,
+    ExportRequestView, ExportState,
+};
+pub use format::PackFormatView;
+pub use import::{
+    FileActionView, ImportCancelView, ImportErrorView, ImportFailureStageView, 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..740158e
--- /dev/null
+++ b/crates/presenter/src/dto/pack/conflict.rs
@@ -0,0 +1,298 @@
+//! 冲突的 DTO：成因、本次处置、**预检的待决清单**、以及三方哈希的那一条账。
+//!
+//! 三种东西分得清清楚楚（混起来就会把"要不要覆盖"变成"已经覆盖了"）：
+//!
+//! | 类型 | 什么时候出现 | 语义 |
+//! |---|---|---|
+//! | [`ImportConflictView`] | **导入前**（`PackEvent::Scan`） | 待用户点头的一条：路径、来源、目标现有体积与哈希 |
+//! | [`ConflictFileView`] | **导入后**（`PackEvent::Report`） | 事后账：这条实际怎么处置的（`choice`） |
+//! | [`ConflictDecisionsView`] | 从页面发回去（`ImportRequestView::decisions`） | 用户点的「全部保留 / 全部覆盖 / 逐项」 |
+//!
+//! 「默认保留用户那一侧」这条硬线在 [`ConflictDecisionsView::default`] 上：缺省 = 全部保留，
+//! 而 core 侧 [`ConflictChoiceView::KeepUser`] 也是缺省档——两侧都不许"没收到决策就覆盖"。
+
+use serde::{Deserialize, Serialize};
+
+/// 一条冲突**来源**（预检清单里那一列）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ConflictSourceView {
+    /// 包内 `overrides/`（CF 清单点名的那个目录 / MultiMC 的 `.minecraft/` 也走这条）。
+    Overrides,
+    /// 包内 `client-overrides/`（叠层里胜出的那一侧）。
+    ClientOverrides,
+    /// CurseForge `files[]` 条目。
+    CurseForge,
+    /// Modrinth `files[]` 条目。
+    Modrinth,
+}
+
+impl ConflictSourceView {
+    /// 稳定 slug。
+    #[must_use]
+    pub const fn slug(self) -> &'static str {
+        match self {
+            Self::Overrides => "overrides",
+            Self::ClientOverrides => "client_overrides",
+            Self::CurseForge => "curseforge",
+            Self::Modrinth => "modrinth",
+        }
+    }
+
+    /// 从 core 的 id 反解。
+    #[must_use]
+    pub fn from_slug(slug: &str) -> Option {
+        match slug {
+            "overrides" => Some(Self::Overrides),
+            "client_overrides" => Some(Self::ClientOverrides),
+            "curseforge" => Some(Self::CurseForge),
+            "modrinth" => Some(Self::Modrinth),
+            _ => None,
+        }
+    }
+
+    /// 是不是"包内的覆盖目录"（相对于清单里的远端条目）。
+    #[must_use]
+    pub const fn is_override_dir(self) -> bool {
+        matches!(self, Self::Overrides | Self::ClientOverrides)
+    }
+}
+
+/// 一条**待用户点头**的冲突（导入前那张清单里的一行）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ImportConflictView {
+    /// 实例内相对路径。
+    pub path: String,
+    /// 来源（包内覆盖目录 / 清单远端条目）。
+    pub source: ConflictSourceView,
+    /// 成因。
+    pub reason: ConflictReasonView,
+    /// 包内那条是不是禁用态（`.disabled`）。
+    pub disabled: bool,
+    /// 包内声明的 SHA-1。
+    pub pack_sha1: String,
+    /// 包内声明的字节数。
+    pub pack_size: u64,
+    /// 目标现有文件的 SHA-1。
+    pub disk_sha1: String,
+    /// 目标现有文件的字节数（覆盖会丢掉的量）。
+    pub disk_size: u64,
+    /// 上次导入写下的 SHA-1（没有基线时 `None`）。
+    pub base_sha1: Option,
+}
+
+/// 用户的冲突决策（三条入口共用一个类型）。
+///
+/// 三条入口与 core 的 `ConflictDecisions`（`default` + `entries`）是同一件事的两种说法：
+///
+/// | 变体 | core 形状 |
+/// |---|---|
+/// | [`ConflictDecisionsView::KeepAll`] | `default = KeepUser`, 空表 |
+/// | [`ConflictDecisionsView::OverwriteAll`] | `default = Overwrite`, 空表 |
+/// | `PerItem { default, items }` | `default` + 逐项表 |
+///
+/// `PerItem` 带一个 `default` 是为了让"全部覆盖之后我又单独放回两条"这种真实操作可表达：
+/// 若只有"逐项覆盖 + 缺省保留"，用户就得把剩下的几百条全点一遍。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ConflictDecisionsView {
+    /// **全部保留**（缺省）：用户已有文件一个都不动。
+    KeepAll,
+    /// **全部覆盖**：整合包说了算。
+    OverwriteAll,
+    /// **逐项**：点过的路径按 `items`，其余按 `default`。
+    PerItem {
+        /// 没点过的路径按它处置。
+        default: ConflictChoiceView,
+        /// 点过的路径。
+        items: Vec,
+    },
+}
+
+impl Default for ConflictDecisionsView {
+    /// **缺省 = 全部保留**（绝不默认覆盖用户已有文件）。
+    fn default() -> Self {
+        Self::KeepAll
+    }
+}
+
+impl ConflictDecisionsView {
+    /// 逐项构造（缺省档 + 点过的那些）。
+    #[must_use]
+    pub fn per_item(default: ConflictChoiceView, items: Vec) -> Self {
+        if items.is_empty() {
+            return match default {
+                ConflictChoiceView::KeepUser => Self::KeepAll,
+                ConflictChoiceView::Overwrite => Self::OverwriteAll,
+            };
+        }
+        Self::PerItem { default, items }
+    }
+
+    /// 逐项表里的缺省档（`KeepAll` / `OverwriteAll` 也答得出）。
+    #[must_use]
+    pub const fn default_choice(&self) -> ConflictChoiceView {
+        match self {
+            Self::KeepAll => ConflictChoiceView::KeepUser,
+            Self::OverwriteAll => ConflictChoiceView::Overwrite,
+            Self::PerItem { default, .. } => *default,
+        }
+    }
+
+    /// 用户显式要求"以包为准"吗（整批覆盖）。
+    #[must_use]
+    pub fn overwrites_everything(&self) -> bool {
+        matches!(self, Self::OverwriteAll)
+    }
+
+    /// 逐项表里"覆盖"的条数（不含缺省档）。
+    #[must_use]
+    pub fn overwrite_count(&self) -> usize {
+        self.items()
+            .iter()
+            .filter(|item| item.choice == ConflictChoiceView::Overwrite)
+            .count()
+    }
+
+    /// 逐项表里"保留"的条数。
+    #[must_use]
+    pub fn keep_count(&self) -> usize {
+        self.items()
+            .iter()
+            .filter(|item| item.choice == ConflictChoiceView::KeepUser)
+            .count()
+    }
+
+    /// 逐项表（`KeepAll` / `OverwriteAll` 是空表）。
+    #[must_use]
+    pub fn items(&self) -> &[ConflictDecisionView] {
+        match self {
+            Self::PerItem { items, .. } => items,
+            Self::KeepAll | Self::OverwriteAll => &[],
+        }
+    }
+
+    /// 逐项表的条数。
+    #[must_use]
+    pub fn len(&self) -> usize {
+        self.items().len()
+    }
+
+    /// 有没有逐项决策。
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.items().is_empty()
+    }
+}
+
+/// 逐项决策的一条（路径 → 处置）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ConflictDecisionView {
+    /// 实例内相对路径。
+    pub path: String,
+    /// 处置。
+    pub choice: ConflictChoiceView,
+}
+
+/// 一次导入预检的结果（`PackEvent::Scan` 的载荷）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ImportScanView {
+    /// 目标实例目录（人要看到"装到哪"）。
+    pub target: std::path::PathBuf,
+    /// 命中的格式。
+    pub format: Option,
+    /// 包名。
+    pub pack_name: Option,
+    /// 包版本。
+    pub pack_version: Option,
+    /// 游戏版本。
+    pub game_version: Option,
+    /// 待用户点头的冲突（按路径排序）。
+    pub conflicts: Vec,
+    /// 补全前没有路径、因而判不了的远端条目数。
+    pub unknown_remote: usize,
+    /// 覆盖会丢掉的字节总量。
+    pub lost_bytes: u64,
+    /// 包内那些条目声明了多大。
+    pub incoming_bytes: u64,
+    /// 注记（与导入报告同源的人读串）。
+    pub notes: Vec,
+    /// 预检本身失败（探测不过 / 开包失败）时的原因。
+    pub error: Option,
+}
+
+impl ImportScanView {
+    /// 需要用户点头吗（`false` = 可以直接导入，别打扰）。
+    #[must_use]
+    pub fn needs_decision(&self) -> bool {
+        !self.conflicts.is_empty()
+    }
+
+    /// 一条冲突都没有、预检也成功（可以直接导）。
+    #[must_use]
+    pub fn is_clean(&self) -> bool {
+        self.error.is_none() && self.conflicts.is_empty()
+    }
+}
+
+/// 冲突成因（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 {
+        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 {
+        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,
+    /// 磁盘现状的 SHA-1（文件不存在时 `None`）。
+    pub disk_sha1: Option,
+    /// 包内声明的字节数。
+    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..d7a4051
--- /dev/null
+++ b/crates/presenter/src/dto/pack/event.rs
@@ -0,0 +1,150 @@
+//! 导入/导出的**指令、事件与面板状态**（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, ImportScanView, ImportState, ProbeView,
+};
+
+/// app → host 的导入/导出意图。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum PackCommand {
+    /// **预检**导入（只读：算出冲突清单，**不写一个字节**）
+    ///
+    /// 页面先发它，拿到 [`PackEvent::Scan`] 之后：没有冲突就直接发 [`PackCommand::Import`]
+    /// （不打扰用户）；有冲突就把清单画出来，用户点完再带着决策发 `Import`。
+    Scan(Box),
+    /// 开始导入（目标实例已选好；`instance` 为 `None` = 按 `instance_name` 新建目录）
+    Import(Box),
+    /// 跑**预检**（只扫描分类，**不写盘**）
+    Export(Box),
+    /// 确认写盘。载荷是**预检时那一份请求**，不是页面当前字段——否则「预检 A、写 B」。
+    Confirm(Box),
+    /// 关掉面板（导入结果 / 探测诊断 / 导出预检都收起来，回到入口态）
+    Dismiss,
+}
+
+/// host → app 的导入/导出事件。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum PackEvent {
+    /// 导入进度（`None` = 收回面板：取消，或流程已经给出结果）
+    Progress(Option>),
+    /// 导入**预检**结果：冲突清单（M160）。空清单 = 没有文件需要用户点头。
+    Scan(Box),
+    /// 导入结果（三态 + 逐项原因；致命失败也走它，`report.error` 里有原因）
+    Report(Box),
+    /// 探测失败：这个包看起来像什么、缺哪个标记文件
+    Probe(Box),
+    /// 导出预检结果
+    Preview(Box),
+    /// 导出写盘完成
+    Exported(Box),
+    /// 导出/预检在 host 侧失败（实例找不到、目录派生失败……一句人读原因）
+    ExportFailed(String),
+    /// 用户取消了导入（面板立刻收回）。
+    ///
+    /// 它只表示"取消后还没有结果"：M195 起 core 有取消令牌，管线会在检查点停手并回滚，**真实
+    /// 结局随后的 [`PackEvent::Report`] 才是准话**（`ImportReportView::cancel` 三档：已回滚 /
+    /// 回滚没做完 / 取消太晚），所以 `Report` 一到就清掉这一位。
+    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::Scan(scan) => {
+                // 预检到了：进度让位，上一轮的结果/诊断作废（这一轮还没开始导）。
+                self.import.progress = None;
+                self.import.probe = None;
+                self.import.report = None;
+                self.import.scan = Some(*scan);
+            }
+            PackEvent::Report(report) => {
+                // 结果到了：进度面板让位，探测诊断与预检清单都作废（这一轮已经有结论了）
+                self.import.progress = None;
+                self.import.probe = None;
+                self.import.scan = None;
+                // M195 r3：取消的**真实结局**在 `report.cancel` 里，`cancelled` 只作"取消后
+                // 还没有结果"时的占位；结果一到就清掉，免得它跨到下一次导入上撒谎。
+                self.import.cancelled = false;
+                self.import.report = Some(*report);
+            }
+            PackEvent::Probe(probe) => {
+                self.import.progress = None;
+                self.import.report = None;
+                self.import.scan = 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 {
+        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 {
+        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,
+    /// 已知的表达不了的差异 / 取舍（core 的 `notes`）。
+    pub notes: Vec,
+}
+
+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,
+}
+
+/// 导出完成（写盘之后的账）。
+#[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,
+    /// **这次预检是对着哪份请求做的**（确认写盘时原样发回，防「预检 A、写 B」）。
+    pub request: Option,
+    /// 预检在飞。
+    pub pending: bool,
+    /// 最近一次写盘的结果。
+    pub done: Option,
+    /// 失败原因（预检或写盘）。
+    pub failed: Option,
+}
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 {
+        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..0be448e
--- /dev/null
+++ b/crates/presenter/src/dto/pack/import.rs
@@ -0,0 +1,374 @@
+//! 导入侧 DTO：请求、进度、三态、逐项原因、探测诊断。
+//!
+//! 状态档（`Success` / `Partial` / `Failed` / `Cancelled`）与 core 一一对应，**`Partial` 不是
+//! `Success`**、**取消不是失败**；容忍域与致命域分属不同类型，UI 不可能混成一个列表。
+
+use std::path::PathBuf;
+
+use serde::{Deserialize, Serialize};
+
+use crate::dto::InstanceId;
+
+use super::conflict::{ConflictDecisionsView, ConflictFileView, ImportScanView};
+use super::format::PackFormatView;
+
+mod cancel;
+mod failure_stage;
+
+pub use cancel::ImportCancelView;
+pub use failure_stage::ImportFailureStageView;
+
+/// 导入阶段（与 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::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,
+    /// 致命失败。
+    ///
+    /// **「动没动过目标目录」不在这里**（M161）：同一个 `Failed` 既可能是预检没过（一个字节都没写），
+    /// 也可能是写完又回滚干净，还可能是回滚没做完——三种由
+    /// [`ImportReportView::failure_stage`] 分开说，界面按它选标题与图标。
+    Failed,
+    /// **用户取消，管线停手并回滚**（M195 r3）：不是失败，也不是「部分成功」。
+    /// 「回滚干净 / 没做完」由 [`ImportReportView::cancel`] 再分；取消**太晚**（管线已跑完）
+    /// 不落这一档——那时实例真装上了，状态是 `Success`/`Partial`，只在 `cancel` 记 `TooLate`。
+    Cancelled,
+}
+
+impl ImportStatusView {
+    /// 稳定 slug。
+    #[must_use]
+    pub const fn slug(self) -> &'static str {
+        match self {
+            Self::Success => "success",
+            Self::Partial => "partial",
+            Self::Failed => "failed",
+            Self::Cancelled => "cancelled",
+        }
+    }
+
+    /// 从 core 的 id 反解。
+    #[must_use]
+    pub fn from_slug(slug: &str) -> Option {
+        match slug {
+            "success" => Some(Self::Success),
+            "partial" => Some(Self::Partial),
+            "failed" => Some(Self::Failed),
+            "cancelled" => Some(Self::Cancelled),
+            _ => None,
+        }
+    }
+
+    /// 实例可用吗（`Success` / `Partial` 是「装上了」；取消与失败都没装上）。
+    #[must_use]
+    pub const fn installed(self) -> bool {
+        matches!(self, Self::Success | Self::Partial)
+    }
+}
+
+/// 一条落地文件本次被怎么处理。
+#[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 {
+        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,
+    /// 新实例的展示名（`None` = 用包名）。
+    pub instance_name: Option,
+    /// 冲突决策（**缺省 [`ConflictDecisionsView::KeepAll`]** = 用户已有文件一个都不动）。
+    ///
+    /// 页面上：`KeepAll` 是缺省与「全部保留」，`OverwriteAll` 是「全部覆盖」，
+    /// `PerItem` 是逐项勾选的结果。只有用户**显式点过**之后才会出现后两者。
+    pub decisions: ConflictDecisionsView,
+}
+
+/// 一条导入进度。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ImportProgressView {
+    /// 阶段。
+    pub stage: ImportStageView,
+    /// 阶段内已完成条目数。
+    pub done: u32,
+    /// 阶段内总条目数（`0` = 未知）。
+    pub total: u32,
+    /// 当前条目的实例内路径（阶段刚开始时为 `None`）。
+    pub current: Option,
+    /// 包名（面板标题那一行）。
+    pub pack: String,
+}
+
+impl ImportProgressView {
+    /// 空进度（刚派发，后端还没回第一条）。
+    #[must_use]
+    pub fn new(pack: impl Into) -> 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 {
+        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,
+    /// 人读标识（CF 条目是 `projectID:fileID`，其余是路径）。
+    pub display: String,
+    /// 为什么搞不到。
+    pub reason: MissingReasonView,
+    /// 细节（错误原文）。
+    pub detail: String,
+}
+
+/// 一次致命失败（是不是「已整包回滚」看 [`ImportReportView::failure_stage`]）。
+#[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,
+}
+
+/// 一次导入的完整结果。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ImportReportView {
+    /// 三态。
+    pub status: ImportStatusView,
+    /// 命中的格式（`None` = 探测都没过）。
+    pub format: Option,
+    /// 包名。
+    pub pack_name: Option,
+    /// 包版本。
+    pub pack_version: Option,
+    /// 游戏版本。
+    pub game_version: Option,
+    /// 加载器（人读串，如 `fabric-loader 0.15.11`）。
+    pub loader: Option,
+    /// 实例绑定的版本 id。
+    pub version_id: Option,
+    /// 目标实例目录。
+    pub target: PathBuf,
+    /// 落地的文件。
+    pub files: Vec,
+    /// 冲突清单。
+    pub conflicts: Vec,
+    /// 缺文件清单（容忍）。
+    pub missing: Vec,
+    /// MultiMC 不支持的 component（逐项）。
+    pub rejected: Vec,
+    /// 注记。
+    pub warnings: Vec,
+    /// 致命错误（`status == Failed` 时必有）。
+    pub error: Option,
+    /// 登记的实例名。
+    pub registered: Option,
+    /// 本次写入的字节数。
+    pub bytes_written: u64,
+    /// 回滚是否完整（`false` = 目标目录可能与导入前不一致，逐条在 `warnings` 里）。
+    ///
+    /// **注意**：`true` 有两种来源——「回滚完整完成」与「从未写过目标目录」（core 的
+    /// `abandoned`）。要区分它们看 [`ImportReportView::failure_stage`]；界面上的措辞
+    /// **必须**按那个字段选（M161）。
+    pub rolled_back: bool,
+    /// 失败发生在哪一步（`None` = 这次不是致命失败）。
+    pub failure_stage: Option,
+    /// 这次运行与「取消」的关系（M195 r3：取消的**真实结局**，界面按它选文案）。
+    ///
+    /// 只靠 `status` 表达不了三档：已回滚 / 回滚没做完都在 [`ImportStatusView::Cancelled`] 里，
+    /// 而「取消太晚、已经跑完」的状态是 `Success`/`Partial`——三档见 [`ImportCancelView`]。
+    pub cancel: ImportCancelView,
+}
+
+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,
+    /// 该格式**缺**的标记文件（逐条，按判据顺序）。
+    pub missing: Vec,
+    /// 包里实际看到的标记（逐条）。
+    pub saw: Vec,
+    /// 一句兜底说明（也是 core 的原文：试过哪些格式）。
+    pub detail: String,
+}
+
+/// 导入侧的宿主状态（`AppState::import` 的全部内容）。
+#[derive(Debug, Clone, PartialEq, Default)]
+pub struct ImportState {
+    /// 正在跑的进度（`None` = 没在跑）。
+    pub progress: Option,
+    /// 用户点了取消、**结果还没回来**（M195 r3 收窄了它的含义）。
+    ///
+    /// 它只作"取消后还没有结果"的占位：真实结局随后的 `report.cancel` 才是准话（已回滚 /
+    /// 回滚没做完 / 取消太晚）。所以 `PackEvent::Report` 一到就清掉这一位，免得它跨到下一次
+    /// 导入上替结局下结论。
+    pub cancelled: bool,
+    /// 最近一次的预检（M160：冲突清单；`None` = 还没预检过或已被新结果顶掉）。
+    pub scan: Option,
+    /// 最近一次的结果（`None` = 还没导过）。
+    pub report: Option,
+    /// 探测失败的具名诊断（有它就让用户看清「像 X 缺 Y」，而不是一句「无法识别」）。
+    pub probe: Option,
+}
diff --git a/crates/presenter/src/dto/pack/import/cancel.rs b/crates/presenter/src/dto/pack/import/cancel.rs
new file mode 100644
index 0000000..337a6cf
--- /dev/null
+++ b/crates/presenter/src/dto/pack/import/cancel.rs
@@ -0,0 +1,43 @@
+//! 一次导入与「取消」的关系（**真实结局**，不是"用户点没点过取消"）。
+//!
+//! 从父模块拆出来只为行数（父文件已到 400 硬限附近），判据与文案口径原样。
+//!
+//! 三档各有各的话要说，混成一句就是撒谎（M195 r3）：
+//! - [`ImportCancelView::RolledBack`]：停手了，目标目录与导入前一致；
+//! - [`ImportCancelView::RollbackIncomplete`]：停手了，但回滚没做完，目标目录可能与导入前不同；
+//! - [`ImportCancelView::TooLate`]：**没来得及停**，管线已经跑完——实例会保留，同名文件可能已被覆盖。
+
+use serde::{Deserialize, Serialize};
+
+/// 一次导入与「取消」的关系（**真实结局**）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
+pub enum ImportCancelView {
+    /// 这次运行没被取消过。
+    #[default]
+    NotRequested,
+    /// 取消生效，管线停手并**完整**回滚（目标目录与导入前一致，实例没登记）。
+    RolledBack,
+    /// 取消生效，但回滚没做完（目标目录可能与导入前不同，逐条在 `warnings` 里）。
+    RollbackIncomplete,
+    /// 取消到得太晚：管线已经跑完，实例保留，同名文件可能已被覆盖。
+    TooLate,
+}
+
+impl ImportCancelView {
+    /// 稳定 slug。
+    #[must_use]
+    pub const fn slug(self) -> &'static str {
+        match self {
+            Self::NotRequested => "not_requested",
+            Self::RolledBack => "rolled_back",
+            Self::RollbackIncomplete => "rollback_incomplete",
+            Self::TooLate => "too_late",
+        }
+    }
+
+    /// 用户这次取消有没有**真的生效**（前两档是真停手了）。
+    #[must_use]
+    pub const fn stopped(self) -> bool {
+        matches!(self, Self::RolledBack | Self::RollbackIncomplete)
+    }
+}
diff --git a/crates/presenter/src/dto/pack/import/failure_stage.rs b/crates/presenter/src/dto/pack/import/failure_stage.rs
new file mode 100644
index 0000000..8a36ef4
--- /dev/null
+++ b/crates/presenter/src/dto/pack/import/failure_stage.rs
@@ -0,0 +1,42 @@
+//! 致命失败发生在哪一步（M161：`rolled_back` 一个人说不了两件事）。
+//!
+//! 从父模块拆出来只为行数；判据与文案口径原样。
+
+use serde::{Deserialize, Serialize};
+
+/// 致命失败的**阶段**（M161：`rolled_back` 一个人说不了两件事）。
+///
+/// core 的 `ImportReport::rolled_back` 语义是「目标目录已确认与导入前一致」——它同时覆盖
+/// 「回滚完整完成」和「**从未写过**目标目录」两种情形（见 `core::addon::import::pipeline` 的
+/// `record_rollback` / `abandoned`）。UI 拿一个 bool 判不出该说哪一句，于是预检失败也会被
+/// 说成「已回滚」，而实际上一个字节都没写。这个枚举把两种情形重新分开，并补上第三种
+/// （回滚有失败项，目标目录可能与导入前不同）。
+///
+/// 只在 `status == Failed` 时有值：成功/部分成功的报告没有「失败阶段」可言。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ImportFailureStageView {
+    /// 预检/装配阶段就失败了：**目标目录一个字节都没写**（用户该去修包/修配置再试）。
+    NotStarted,
+    /// 已经写过目标目录，回滚**完整**完成（零残留）。
+    RolledBack,
+    /// 写过了，但回滚有失败项：目标目录可能与导入前不同（`warnings` 里逐条列了）。
+    RollbackIncomplete,
+}
+
+impl ImportFailureStageView {
+    /// 稳定 slug（日志 / 测试用；**不要改名**）。
+    #[must_use]
+    pub const fn slug(self) -> &'static str {
+        match self {
+            Self::NotStarted => "not_started",
+            Self::RolledBack => "rolled_back",
+            Self::RollbackIncomplete => "rollback_incomplete",
+        }
+    }
+
+    /// 本次失败到底动没动目标目录。
+    #[must_use]
+    pub const fn touched_target(self) -> bool {
+        !matches!(self, Self::NotStarted)
+    }
+}
diff --git a/crates/presenter/src/dto/saves.rs b/crates/presenter/src/dto/saves.rs
new file mode 100644
index 0000000..8bd74c8
--- /dev/null
+++ b/crates/presenter/src/dto/saves.rs
@@ -0,0 +1,310 @@
+//! 实例**存档 / 截图的快照**与写操作的 IPC 面（M235 · STOREMVP，M247 · SAVESOPS 加写路径）。
+//!
+//! # 三层里的第二层
+//!
+//! 这一版是「只读列表 + 打开文件夹」**加上**三个写操作：`core::game::saves`（读盘/写盘，唯一的
+//! 真相）→ 本模块（IPC 形状）→ `crates/app-iced/src/pages/instances/saves.rs`（画）。
+//!
+//! | 方向 | 类型 |
+//! |---|---|
+//! | app → host | [`SavesCommand`]（列目录 / 打开文件夹 / 重命名 / 删除 / 备份） |
+//! | host → app | [`SavesListView`]（整份快照 + 上一次写操作的[回执](SavesOped)）或 [`SavesFailureView`] |
+//!
+//! # 写操作为什么走同一条回程
+//!
+//! 三个写操作的结果都是**一份新快照**（`Ok`）+ 一个[回执](SavesOped)：写完之后磁盘变了，
+//! 界面必须跟着变；而回执是「这次动的是哪一条、动成了什么」。失败则走同一个事件的 `Err` 一支，
+//! 带上一个**具名类别**（重命名撞名 / 删除越界 / 备份超限……），见 [`SavesFailureKind`]。
+//! 两条都不静默：成功有回执、失败有类别 + OS 原文。
+//!
+//! # 为什么另开一族，不并进 `ModListView`
+//!
+//! 两者形状相近（都是"列一个实例的某个目录"），但语义不同：mod 有启停（看游戏在不在跑），
+//! 存档这边有三个写操作（重命名 / 删除 / 备份）。合并会让两边的 `pending` 字段互相变成
+//! 永远为假的分支（M224 拒绝给内容页加第五个 `ContentKind` 是同一条理由：别让穷尽 match 为
+//! 不相干的字段服务）。
+//!
+//! # 文案纪律（M161）
+//!
+//! 本模块**不带人读散文**：失败给的是结构（[`SavesFailureKind`] + 底层 `detail` 串）、
+//! 回执给的是事实（谁改成什么、备份落到哪个路径、几个字节、跳过几个链接），
+//! 时间戳给的是**毫秒数**（UTC 毫秒，UI 自己格式化）。文案一律由 app 层按 i18n key 现求。
+//!
+//! # 时间戳为什么是 `Option` 的毫秒
+//!
+//! 取不到（早于 1970 / 文件系统不给）就是 `None`——**不拿 0 或当前时间填**：那会让"时间未知"
+//! 看起来像"1970 年"或"刚刚"。格式化交给 UI（`dto::logs` 的时戳同理）。
+
+use serde::{Deserialize, Serialize};
+
+use crate::dto::InstanceId;
+
+mod preview;
+
+pub use preview::{ScreenshotPreview, ScreenshotThumbFailure, ScreenshotThumbKind, ThumbnailView};
+
+/// app → host 的存档指令。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum SavesCommand {
+    /// 列某个实例的 `saves/` 与 `screenshots/`（进详情页时发、点「重试」时再发）。
+    List(InstanceId),
+    /// 用系统文件管理器打开存档目录。
+    ///
+    /// 打开**哪个**目录由 host 决定（`saves/` → `screenshots/` → 运行目录，依次退化），
+    /// 因为那是"磁盘上到底有什么"的事实，不该让 UI 猜。
+    OpenFolder {
+        /// 实例 id
+        id: InstanceId,
+    },
+    /// 重命名一个世界（M247）：`saves/` → `saves/`。
+    ///
+    /// 名字规则、撞名、边界校验全在 core（host 只转发）：UI 传坏了也不会落到 `saves/` 之外。
+    RenameWorld {
+        /// 实例 id
+        id: InstanceId,
+        /// 现在的磁盘目录名
+        dir: String,
+        /// 新名字（单段；不许带 `/` `\` `:` 与 `..`）
+        to: String,
+    },
+    /// 删除一个世界（M247）：递归删 `saves/`。
+    ///
+    /// **UI 必须先二次确认**：这是本页唯一不可逆的动作。host 侧再走一遍边界校验
+    /// （越界 / 符号链接一律拒），不靠确认框把调用方「教好」。
+    DeleteWorld {
+        /// 实例 id
+        id: InstanceId,
+        /// 磁盘目录名
+        dir: String,
+    },
+    /// 备份一个世界（M247）：把一个世界导出成 zip。
+    ///
+    /// `dest` 是**父目录**（不是文件）：`None` = 启动器自己的 `/exports/saves/`。
+    /// 文件名由 core 按「世界名 + UTC 时戳」生成，撞名顺延，**绝不覆盖**上一份。
+    BackupWorld {
+        /// 实例 id
+        id: InstanceId,
+        /// 磁盘目录名
+        dir: String,
+        /// 导出到哪个父目录（`None` = 启动器自己的 exports）
+        dest: Option,
+    },
+}
+
+/// 一次写操作成功后的事实（**不含人读文案**：文案由 app 按 i18n key 现求）。
+///
+/// 为什么成功也要有回执：重命名 / 删除的结果在列表上自己会说话（行改名、行消失），
+/// 而**备份成功没有话可说**——zip 落到了文件系统某处，用户必须知道完整路径 + 字节数，
+/// 否则「点了备份然后什么也没发生」就是一次静默失败。
+///
+/// 回执挂在快照上（[`SavesListView::last_op`]）：下一次普通 `List` 会让它消失，
+/// 所以它表达的是「最近这一次操作」，不是一段历史。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum SavesOped {
+    /// 改名成功。
+    Renamed {
+        /// 原磁盘名
+        from: String,
+        /// 新磁盘名
+        to: String,
+    },
+    /// 删除成功。
+    Deleted {
+        /// 被删掉的磁盘名
+        dir: String,
+    },
+    /// 备份成功。
+    BackedUp {
+        /// 被备份的世界（磁盘名）
+        dir: String,
+        /// 落点文件名
+        file: String,
+        /// 落点完整路径
+        path: String,
+        /// zip 的字节数
+        bytes: u64,
+        /// 被跳过的符号链接数（不跟随；0 = 一个都没跳）
+        skipped: usize,
+    },
+}
+
+/// 一个世界目录。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct WorldView {
+    /// 磁盘上的目录名（这一版它就是展示名：`LevelName` 在 `level.dat` 里，本版不解析 NBT）。
+    pub dir: String,
+    /// 有没有 `icon.png`（只判存在，不解码）。
+    ///
+    /// M251 之后**世界图标仍未解**：缩略图墙（[`ScreenshotPreview`]）只覆盖 `screenshots/`，
+    /// 这是 D54 的范围。这行字眼原来写的是「缩略图墙不在 U3 范围内」，那句话已失真。
+    pub icon: bool,
+    /// 目录 mtime（UTC 毫秒；`None` = 取不到）。
+    pub modified_ms: Option,
+}
+
+/// 一张截图（元数据 + **预览**）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ScreenshotView {
+    /// 磁盘文件名（含扩展名）。
+    pub file: String,
+    /// 字节数（UI 自己格式化，不在这里拼 `1.2 MiB`）。
+    pub bytes: u64,
+    /// 文件 mtime（UTC 毫秒；`None` = 取不到）。
+    pub modified_ms: Option,
+    /// 预览（缩略图像素 / 没生成 / 具名失败原因），见 [`ScreenshotPreview`]。
+    ///
+    /// 像素**不落盘**（D54 第 2 条）：解码在 host 的后台线程里做完，随这份快照一次性交给
+    /// 壳层。`(file, modified_ms, bytes)` 同时也是 host 侧缓存键的三段——三者任一变了就是
+    /// 另一张图，必须重解。
+    pub preview: ScreenshotPreview,
+}
+
+/// 被跳过的条目来自哪个目录。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum SavesArea {
+    /// `/saves/`
+    Saves,
+    /// `/screenshots/`
+    Screenshots,
+}
+
+/// 没收进列表的原因（与 `core::game::saves::SkipKind` 一一对应）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum SavesSkipKind {
+    /// 符号链接（不跟随）。
+    SymbolicLink,
+    /// `saves/` 下的非目录。
+    NotADirectory,
+    /// `screenshots/` 下的非普通文件。
+    NotAFile,
+    /// 名字过不了路径规则。
+    UnsafeName,
+    /// 元数据读不出来。
+    Unreadable,
+    /// 不是认得的图片扩展名。
+    NotAnImage,
+}
+
+/// 一个没能进列表的条目。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct SavesSkipView {
+    /// 来自哪个目录。
+    pub area: SavesArea,
+    /// 磁盘名字。
+    pub file: String,
+    /// 为什么没收。
+    pub reason: SavesSkipKind,
+}
+
+/// 一次列举的完整快照（**整体替换**，不做增量）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct SavesListView {
+    /// 实例 id
+    pub instance: InstanceId,
+    /// 被列的 `saves/` 目录（绝对路径）。
+    pub dir: String,
+    /// `saves/` 存不存在（`false` = 这实例还没存过档，不是错误）。
+    pub exists: bool,
+    /// 世界列表（按名字排序）。
+    pub worlds: Vec,
+    /// 被列的 `screenshots/` 目录（绝对路径）。
+    pub screenshots_dir: String,
+    /// `screenshots/` 存不存在。
+    pub screenshots_exists: bool,
+    /// 截图列表（**新的在前**）。
+    pub screenshots: Vec,
+    /// 跳过的条目（UI 只需计数 + 一句"为什么"）。
+    pub skipped: Vec,
+    /// 最近一次写操作的回执（`None` = 这一拍只是列举，没写东西）。
+    pub last_op: Option,
+}
+
+impl SavesListView {
+    /// 世界数。
+    #[must_use]
+    pub fn world_count(&self) -> usize {
+        self.worlds.len()
+    }
+
+    /// 截图数。
+    #[must_use]
+    pub fn screenshot_count(&self) -> usize {
+        self.screenshots.len()
+    }
+
+    /// 跳过数。
+    #[must_use]
+    pub fn skipped_count(&self) -> usize {
+        self.skipped.len()
+    }
+
+    /// 两个目录都不存在（新实例的常态：还没进过游戏）。
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.worlds.is_empty() && self.screenshots.is_empty()
+    }
+}
+
+/// 一次失败（app 按 key 现求文案）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct SavesFailureView {
+    /// 实例 id（迟到/串台的结果靠它判）。
+    pub instance: InstanceId,
+    /// 涉及的那个世界（写操作才有；读路径给空串）。
+    ///
+    /// 为什么要这一格：失败那句话是「重命名 **A** 失败：同名世界已存在」——没有名字，
+    /// 用户不知道该改哪一行（与 `ModFailureView::file` 同一条理由）。
+    pub file: String,
+    /// 这是哪一类**写**操作（`None` = 读路径 / 打开文件夹的失败）。
+    pub op: Option,
+    /// 失败大类。
+    pub kind: SavesFailureKind,
+    /// 底层原文（OS 错误 / 路径细节）；只进括号，不进主句。
+    pub detail: String,
+}
+
+/// 失败出自哪一类写操作（决定失败那句主句用哪个动词）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum SavesFailureOp {
+    /// 重命名。
+    Rename,
+    /// 删除。
+    Delete,
+    /// 备份。
+    Backup,
+}
+
+/// 失败大类（**每一种在 UI 上都有一句话**，没有静默失败）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum SavesFailureKind {
+    /// 实例不在了（快照里找不到），或隔离档位派生不出运行目录。
+    InstanceUnavailable,
+    /// `saves/` / `screenshots/` 存在但不可用（符号链接 / 不是目录 / 读不了）。
+    DirUnusable,
+    /// 「打开文件夹」失败（目录不存在 / 拉不起文件管理器）。
+    OpenFailed,
+    /// 写操作：名字过不了规则（空、`.`、`..`、含 `/` `\` `:` NUL）。
+    WriteUnsafeName,
+    /// 写操作：目标或路径上的一段是符号链接（不跟随）。
+    WriteSymlink,
+    /// 写操作：那个世界（或 `saves/`）已经不在了。
+    WriteMissing,
+    /// 写操作：那个名字底下不是目录。
+    WriteNotADirectory,
+    /// 写操作：同名世界已存在 / 备份文件名撞满。
+    WriteConflict,
+    /// 写操作：路径落在 `saves/` 之外（含层级异常深）。
+    WriteBoundary,
+    /// 写操作：备份超过体积或条目上限。
+    WriteTooLarge,
+    /// 写操作：实例正在启动/运行中，**一个字节都没碰盘**（见 `host::saves::dispatch`）。
+    ///
+    /// 单独一类而不是折进 [`WriteFailed`](Self::WriteFailed)：Linux 上删一个正在跑的世界**会成功**，
+    /// 所以这不是"写盘失败了"，是"我们主动没写"。界面必须说「游戏正在运行，先退出再操作」。
+    GameRunning,
+    /// 写操作：其它系统错误（权限 / 被别的进程占用），OS 原文进 `detail`。
+    WriteFailed,
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/presenter/src/dto/saves/preview.rs b/crates/presenter/src/dto/saves/preview.rs
new file mode 100644
index 0000000..8c37e2e
--- /dev/null
+++ b/crates/presenter/src/dto/saves/preview.rs
@@ -0,0 +1,88 @@
+//! 一张截图的**预览**（M251 · SAVESHOTS，D54 第 2/6 条）。
+//!
+//! ## 像素为什么走 DTO
+//!
+//! D54 定「**不落盘缩略图**」：写 PNG 要编码器，而编码器只为一份磁盘缓存引入不划算。于是像素
+//! 就直接躺在快照里跟着 IPC 面走，由壳层用 `iced::widget::image::Handle::from_rgba` 建句柄。
+//! 代价是快照变大（60 张 × 160² × 4B ≈ 6MB），收益是零编码、零临时文件、零清理。
+//!
+//! ## 三种状态，一种都不许静默
+//!
+//! | 状态 | 什么时候 | 界面 |
+//! |---|---|---|
+//! | [`ScreenshotPreview::Ready`] | 解出来了 | 缩略图 |
+//! | [`ScreenshotPreview::NotGenerated`] | 本次刷新超出 60 张上限（按 mtime 倒序只解前 60） | 「未生成预览」占位 |
+//! | [`ScreenshotPreview::Failed`] | 超过 8 MiB / 读不出来 / 解不出来 | 占位 + **逐条**原因 |
+//!
+//! **不拼人读文案**（M161）：这里只有结构与 [`ScreenshotThumbKind`]，句子由 app 层按 i18n key 现求。
+//!
+//! ## 为什么失败也带 `detail`
+//!
+//! 「读不出来」有五种完全不同的原因（权限 / 被占用 / 文件已删 / 是目录 / 盘掉了），用户能自己
+//! 处理的那几种全靠这句话。原文只进括号，不进主句（与 [`super::SavesFailureView`] 同一条口径）。
+
+use serde::{Deserialize, Serialize};
+
+/// 一张截图的预览状态。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ScreenshotPreview {
+    /// 还没生成：本次刷新超出上限（按 mtime 倒序只解前 60 张，上限常量在
+    /// `crate::host::saves::thumbs::MAX_PER_REFRESH`——策略住在解码那一侧，DTO 只表达状态）。
+    NotGenerated,
+    /// 解出来了（RGBA8，行主序，`width × height × 4`）。
+    Ready(ThumbnailView),
+    /// 没解出来（逐条可见的原因 + 原文）。
+    Failed(ScreenshotThumbFailure),
+}
+
+impl ScreenshotPreview {
+    /// 这一拍有没有可画的像素。
+    #[must_use]
+    pub fn thumbnail(&self) -> Option<&ThumbnailView> {
+        match self {
+            Self::Ready(view) => Some(view),
+            Self::NotGenerated | Self::Failed(_) => None,
+        }
+    }
+}
+
+/// 一张缩略图的像素（**未落盘**，见模块文档）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ThumbnailView {
+    /// 宽（像素）。
+    pub width: u32,
+    /// 高（像素）。
+    pub height: u32,
+    /// RGBA8 字节，行主序，长度必须是 `width × height × 4`。
+    pub pixels: Vec,
+}
+
+impl ThumbnailView {
+    /// 像素数与宽高对得上吗（壳层建 `Handle` 之前**必须**成立：`from_rgba` 不校验长度，
+    /// 长度不对就是一张花屏图或者一次 panic 后的空窗）。
+    #[must_use]
+    pub fn is_consistent(&self) -> bool {
+        let expected = u64::from(self.width) * u64::from(self.height) * 4;
+        expected == self.pixels.len() as u64
+    }
+}
+
+/// 一张截图的预览为什么没出来（**每一种在 UI 上都有一句话**）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ScreenshotThumbFailure {
+    /// 大类。
+    pub kind: ScreenshotThumbKind,
+    /// 底层原文（OS 错误 / 解码器原文）；只进括号，不进主句。
+    pub detail: String,
+}
+
+/// 预览失败的大类。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ScreenshotThumbKind {
+    /// 单张超过解码上限（8 MiB）：**不解码**，直接跳过（D54 第 5 条）。
+    TooLarge,
+    /// 读不出来（不存在 / 无权限 / 被占用）。
+    Unreadable,
+    /// 读到了但解不出来（坏 PNG / 不支持的格式）。
+    Decode,
+}
diff --git a/crates/presenter/src/dto/saves/tests.rs b/crates/presenter/src/dto/saves/tests.rs
new file mode 100644
index 0000000..1c5a361
--- /dev/null
+++ b/crates/presenter/src/dto/saves/tests.rs
@@ -0,0 +1,192 @@
+//! 存档 IPC 面的用例：**IPC round-trip**（生成物必须能反序列化回来）。
+
+use super::*;
+
+fn view() -> SavesListView {
+    SavesListView {
+        instance: "inst".to_string(),
+        dir: "/tmp/run/saves".to_string(),
+        exists: true,
+        worlds: vec![WorldView {
+            dir: "World".to_string(),
+            icon: true,
+            modified_ms: Some(1_700_000_000_000),
+        }],
+        screenshots_dir: "/tmp/run/screenshots".to_string(),
+        screenshots_exists: true,
+        screenshots: vec![ScreenshotView {
+            file: "2024-05-01_10.00.00.png".to_string(),
+            bytes: 1024,
+            modified_ms: None,
+            // M251：像素真的能过 IPC（4 字节 = 1×1 RGBA），这是「不落盘直接交给壳层」的前提。
+            preview: ScreenshotPreview::Ready(ThumbnailView {
+                width: 1,
+                height: 1,
+                pixels: vec![0x2E, 0x7D, 0x4F, 0xFF],
+            }),
+        }],
+        skipped: vec![SavesSkipView {
+            area: SavesArea::Screenshots,
+            file: "notes.txt".to_string(),
+            reason: SavesSkipKind::NotAnImage,
+        }],
+        last_op: None,
+    }
+}
+
+/// 计数与 IPC round-trip（AGENTS §6：跨界类型必须能序列化）。
+#[test]
+fn view_counts_and_round_trips() {
+    let view = view();
+    assert_eq!(view.world_count(), 1);
+    assert_eq!(view.screenshot_count(), 1);
+    assert_eq!(view.skipped_count(), 1);
+    assert!(!view.is_empty());
+
+    let text = serde_json::to_string(&view).expect("序列化");
+    assert_eq!(
+        serde_json::from_str::(&text).expect("反序列化"),
+        view
+    );
+}
+
+/// 五条指令都要能过 IPC（含写操作三条——它们带世界名，名字里可能有空格与中文）。
+#[test]
+fn commands_round_trip() {
+    for command in [
+        SavesCommand::List("inst".to_string()),
+        SavesCommand::OpenFolder {
+            id: "inst".to_string(),
+        },
+        SavesCommand::RenameWorld {
+            id: "inst".to_string(),
+            dir: "Better World".to_string(),
+            to: "更好的世界".to_string(),
+        },
+        SavesCommand::DeleteWorld {
+            id: "inst".to_string(),
+            dir: "Better World".to_string(),
+        },
+        SavesCommand::BackupWorld {
+            id: "inst".to_string(),
+            dir: "Better World".to_string(),
+            dest: Some("D:/backups".to_string()),
+        },
+        SavesCommand::BackupWorld {
+            id: "inst".to_string(),
+            dir: "Better World".to_string(),
+            dest: None,
+        },
+    ] {
+        let text = serde_json::to_string(&command).expect("序列化");
+        assert_eq!(
+            serde_json::from_str::(&text).expect("反序列化"),
+            command
+        );
+    }
+}
+
+/// 成功回执也要能过 IPC（备份那一支字段最多：路径 / 字节 / 跳过数）。
+#[test]
+fn op_receipts_round_trip() {
+    let cases = [
+        SavesOped::Renamed {
+            from: "Old".to_string(),
+            to: "New".to_string(),
+        },
+        SavesOped::Deleted {
+            dir: "Old".to_string(),
+        },
+        SavesOped::BackedUp {
+            dir: "Old".to_string(),
+            file: "Old-20240501-100000.zip".to_string(),
+            path: "D:/exports/Old-20240501-100000.zip".to_string(),
+            bytes: 4096,
+            skipped: 2,
+        },
+    ];
+    for op in cases {
+        let mut view = view();
+        view.last_op = Some(op);
+        let text = serde_json::to_string(&view).expect("序列化");
+        assert_eq!(
+            serde_json::from_str::(&text).expect("反序列化"),
+            view
+        );
+    }
+}
+
+/// 两个目录都不存在 ⇒ 空（`is_empty` 只看内容，不看 `exists`：一个目录有空世界也算非空）。
+#[test]
+fn empty_means_no_worlds_and_no_screenshots() {
+    let mut view = view();
+    view.worlds.clear();
+    view.screenshots.clear();
+    assert!(view.is_empty(), "没有世界也没有截图就该算空");
+    view.screenshots.push(ScreenshotView {
+        file: "a.png".to_string(),
+        bytes: 0,
+        modified_ms: None,
+        preview: ScreenshotPreview::NotGenerated,
+    });
+    assert!(!view.is_empty());
+}
+
+/// 预览的三种状态都要能过 IPC，且**失败原因逐条带得回来**（M251 · D54 第 6 条）。
+#[test]
+fn previews_round_trip_in_every_state() {
+    let failure = ScreenshotThumbFailure {
+        kind: ScreenshotThumbKind::TooLarge,
+        detail: "9000000 > 8388608 字节".to_string(),
+    };
+    for preview in [
+        ScreenshotPreview::NotGenerated,
+        ScreenshotPreview::Ready(ThumbnailView {
+            width: 2,
+            height: 1,
+            pixels: vec![1, 2, 3, 4, 5, 6, 7, 8],
+        }),
+        ScreenshotPreview::Failed(failure),
+    ] {
+        let text = serde_json::to_string(&preview).expect("序列化");
+        assert_eq!(
+            serde_json::from_str::(&text).expect("反序列化"),
+            preview
+        );
+    }
+}
+
+/// 「像素长度与宽高对得上」这条判据本身（壳层建 `Handle` 前要它成立）。
+#[test]
+fn thumbnail_consistency_catches_a_short_buffer() {
+    let good = ThumbnailView {
+        width: 2,
+        height: 2,
+        pixels: vec![0; 16],
+    };
+    assert!(good.is_consistent());
+    let short = ThumbnailView {
+        pixels: vec![0; 15],
+        ..good.clone()
+    };
+    assert!(!short.is_consistent(), "少一个字节也必须判不一致");
+}
+
+/// 只有 `Ready` 才有像素可画（另外两支都是占位，界面不许把它们当成「黑图」）。
+#[test]
+fn only_ready_hands_out_pixels() {
+    assert!(ScreenshotPreview::Ready(ThumbnailView {
+        width: 1,
+        height: 1,
+        pixels: vec![0, 0, 0, 255],
+    })
+    .thumbnail()
+    .is_some());
+    assert!(ScreenshotPreview::NotGenerated.thumbnail().is_none());
+    assert!(ScreenshotPreview::Failed(ScreenshotThumbFailure {
+        kind: ScreenshotThumbKind::Unreadable,
+        detail: "access denied".to_string(),
+    })
+    .thumbnail()
+    .is_none());
+}
diff --git a/crates/presenter/src/dto/settings.rs b/crates/presenter/src/dto/settings.rs
new file mode 100644
index 0000000..3bc190a
--- /dev/null
+++ b/crates/presenter/src/dto/settings.rs
@@ -0,0 +1,247 @@
+//! 设置页 DTO：设置分组的通用行模型。
+//!
+//! 「行」是 UI 与 `core::setting` schema 之间的唯一形状：一行 = 一个键 + 一种控件 +
+//! 当前值。写回走 [`crate::dto::AppCommand::SetSetting`]，由 host 用 `SettingStore::set`
+//! 落盘（不自己拼 JSON、不另立配置文件，`AGENTS §6`）。
+
+use serde::{Deserialize, Serialize};
+
+/// 设置页 Java 组「写回完成，请重发快照」的动作键（M204）。
+///
+/// ## 它解决的问题
+///
+/// Java 组把三键（`java.default_memory_mb` / `java.extra_args` / `java.selected_path`）**一次原子**
+/// 写进 `launcher.json`（`app-iced` 的 `pages/settings/java/store.rs`：`set` 几个键 + 一次
+/// `save()`），走的是页面自己的 `SettingStore`，**不经过** [`crate::dto::AppCommand::SetSetting`]
+/// 的写盘分支。而 `CoreEvent::SettingsChanged` 全仓只有两处发出（`host/dispatch.rs` 的
+/// `SetSetting` 分支、`host/mod.rs` 的 `refresh_all`）。于是三键写成功之后，presenter 的 java 组
+/// 快照会陈旧到下一次任何别的写入——`AppState::settings_groups` 里的 `java.selected_path` /
+/// `java.extra_args` 还是旧值。
+///
+/// ## 为什么不是「把写盘搬进 SetSetting」
+///
+/// 那会把一次原子写拆成最多三条命令（`SetSetting` 一次只收一个键），于是内存与 JVM 参数的保存
+/// 会出现「第一键落盘、第二键被 schema 拒」的中间态；每条命令还要各走一次异步落盘，用户点一次
+/// 保存会看到三次写盘与三次快照回流。取舍见 M204 报告。
+///
+/// ## 形状
+///
+/// 与 `host::engine::DETECT_REGION_ACTION`（`download.action.detect_region`，M165）同一族：
+/// **动作键不写盘**，`host::settings::set` 见到它就返回 `Ok(())`，于是 `dispatch.rs` 的
+/// `SetSetting` 分支照常执行它那四个副作用臂（重建引擎 / 重发 `SettingsChanged` / 清 Java 链）。
+/// 键名带 `action` 段，是为了让人一眼看出它**不是** schema 键（`core::setting::keys` 里没有它，
+/// 手写进 `launcher.json` 也只会被当成未知键忽略）。
+pub const JAVA_REFRESH_ACTION: &str = "java.action.refresh";
+
+/// 控件类型（决定设置页画什么）。
+#[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,
+    /// 文本值
+    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,
+}
+
+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/update.rs b/crates/presenter/src/dto/update.rs
new file mode 100644
index 0000000..36caf77
--- /dev/null
+++ b/crates/presenter/src/dto/update.rs
@@ -0,0 +1,334 @@
+//! 自更新 DTO（M159）：一次检查的结论、候选、失败分类、就位状态。
+//!
+//! 口径四条：
+//!
+//! 1. **「检查失败」不是「已是最新」**——两者是 [`UpdateOutcome`] 的两个变体，各有自己的文案。
+//!    把它们折叠成一个（例如失败时也发 `UpToDate`）会让用户以为「已经最新」，而网络其实一次都没通；
+//! 2. **「有更高版本但没给你的平台发包」也不是「已是最新」**（[`UpdateOutcome::MissingArtifact`]）：
+//!    那是发布侧的漏项，说成「最新」等于把发布的错报成用户的好消息；
+//! 3. **版本比较只发生在 core**（[`unlucky_core::update::UpdateChecker`]）：本模块只搬运结论，
+//!    UI 与 CLI 都不许自己比版本号（mission：GUI 与 CLI 行为一致，不许两套逻辑）；
+//! 4. 本模块不含 core 类型（D42：dto 只放扁平 IPC 类型）。
+//!
+//! 「忽略这个版本」（[`UpdateView::skipped`]）记的是**版本号**，不是「别再问我了」：
+//!
+//! * 用户点「忽略这个版本」时写下**当时那个版本号**（会话级，不落盘）；
+//! * 同一次运行里如果又出现**更高**的版本（0.2.3 被忽略后冒出 0.2.4），提示条**照常弹**——
+//!   忽略的是那一个版本，文案也确实是「忽略这个版本」；
+//! * 设置页的「立即检查」会清掉它（手动检查 = 用户要看真结果），静默检查**永不**清。
+
+use serde::{Deserialize, Serialize};
+
+/// 检查更新的一次结论。
+#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
+pub enum UpdateOutcome {
+    /// 还没查过（启动那一刻的状态）。
+    #[default]
+    Idle,
+    /// 正在查（网络在后台线程）。
+    Checking,
+    /// 已是最新。
+    UpToDate {
+        /// 该渠道准入的最高版本；清单里还没有任何发布时为 `None`（「还没发过版」不是错误）。
+        latest: Option,
+    },
+    /// 有可装的更新。
+    Available(Box),
+    /// 有更高的版本，但里面没有本平台的产物（发布侧漏项，不能对用户说「已是最新」）。
+    MissingArtifact {
+        /// 那个更高版本。
+        version: String,
+    },
+    /// 检查失败（连不上 / 清单坏了 / 渠道不符 …）。
+    Failed(UpdateFailureView),
+}
+
+impl UpdateOutcome {
+    /// 是不是正在查。
+    #[must_use]
+    pub const fn is_checking(&self) -> bool {
+        matches!(self, Self::Checking)
+    }
+
+    /// 可装的候选（没有则为 `None`）。
+    #[must_use]
+    pub fn candidate(&self) -> Option<&UpdateCandidateView> {
+        match self {
+            Self::Available(candidate) => Some(candidate),
+            _ => None,
+        }
+    }
+
+    /// 失败信息（不是失败则为 `None`）。
+    #[must_use]
+    pub const fn failure(&self) -> Option<&UpdateFailureView> {
+        match self {
+            Self::Failed(failure) => Some(failure),
+            _ => None,
+        }
+    }
+
+    /// 稳定 id（日志 / 测试 / 事件流用；**不要改名**）。
+    #[must_use]
+    pub const fn as_str(&self) -> &'static str {
+        match self {
+            Self::Idle => "idle",
+            Self::Checking => "checking",
+            Self::UpToDate { .. } => "up_to_date",
+            Self::Available(_) => "available",
+            Self::MissingArtifact { .. } => "missing_artifact",
+            Self::Failed(_) => "failed",
+        }
+    }
+}
+
+/// 一个可安装的候选（提示条与设置页共用的四件）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct UpdateCandidateView {
+    /// 新版本号（清单里的原文，如 `0.2.3`）。
+    pub version: String,
+    /// 包体字节数（提示条上的「体积」）。
+    pub size: u64,
+    /// 更新说明摘要（清单里的 `notes`，已截断；空串 = 发布没写说明）。
+    pub notes: String,
+    /// 急不急（`true` = 发布标了强制，或当前版本低于发布侧的最低支持版本）。
+    pub forced: bool,
+}
+
+/// 检查失败的分类与人话。
+///
+/// `message` 直接来自 core 的错误（中文、含路径/URL 细节），UI 只在它前面加一句自己的话；
+/// `kind` 是 core 的稳定分类 id（`network` / `invalid_manifest` / `digest_mismatch` …），
+/// 给「要不要显示重试」这类判据用。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct UpdateFailureView {
+    /// 稳定分类 id（`UpdateErrorKind::as_str`）。
+    pub kind: String,
+    /// 人话原因。
+    pub message: String,
+    /// 换个时间/换个源再试是否可能变好。
+    pub retryable: bool,
+}
+
+impl UpdateFailureView {
+    /// 建一条。
+    pub fn new(kind: &str, message: impl Into, retryable: bool) -> Self {
+        Self {
+            kind: kind.to_string(),
+            message: message.into(),
+            retryable,
+        }
+    }
+}
+
+/// 已经就位的新版本（下载 + 校验 + 替换都成功，等用户重启）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ReadyUpdate {
+    /// 新版本号。
+    pub version: String,
+    /// 替换后的目标路径（人读展示；「下次启动生效」说的就是它）。
+    pub path: String,
+    /// 旧版本被挪到哪（`None` = 原本没有文件 / 已清理）。
+    pub backup: Option,
+}
+
+/// 提示条此刻要显示什么。
+///
+/// 「检查失败」只有在**用户主动查**的时候才弹条（[`UpdateView::silent`] = `false`）：
+/// 启动时的静默检查失败是常态（离线、公司网、镜像没同步），拿一条红条迎面上来等于每次开
+/// 启动器先骂网络一次。失败原因仍然进设置页的「更新」区，那里随时能看。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum UpdateBanner<'a> {
+    /// 有新版本（可下载）。
+    Available(&'a UpdateCandidateView),
+    /// 正在下载/校验/替换。
+    Applying,
+    /// 已就位，等重启。
+    Ready(&'a ReadyUpdate),
+    /// 检查/应用失败（只在用户主动查之后出现）。
+    Failed(&'a UpdateFailureView),
+}
+
+/// 更新页 / 提示条的全部状态（一条快照整体替换）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct UpdateView {
+    /// 当前版本（`CARGO_PKG_VERSION`，由 host 填）。
+    pub current_version: String,
+    /// 渠道（D50：先只发 stable）。
+    pub channel: String,
+    /// 启动时是否静默检查（设置页开关）。
+    pub auto_check: bool,
+    /// 检查结论。
+    pub outcome: UpdateOutcome,
+    /// 上次检查时间（`MM-DD HH:MM`；空串 = 没查过）。
+    pub checked_at: String,
+    /// 这一份结论来自**静默**检查（启动时/自动）而不是用户点的「立即检查」。
+    pub silent: bool,
+    /// 正在下载/校验/替换（一条慢操作，期间禁用「立即安装」）。
+    pub applying: bool,
+    /// 已经就位的新版本（等重启）。
+    pub ready: Option,
+    /// 用户点了「忽略这个版本」时记下的**版本号**（`None` = 没忽略）。
+    ///
+    /// 只压住**这一个**版本：0.2.3 被忽略后 0.2.4 仍然提示（文案是「忽略这个版本」，
+    /// 不是「别再问我」）。设置页手动检查会把它清空。
+    pub skipped: Option,
+}
+
+impl Default for UpdateView {
+    /// 出厂状态：当前版本取本进程的版本号（**不是空串**——mock 后端/未接线的路径下，
+    /// 设置页的「当前版本」那一行至少要显示自己的版本，而不是一片空白）。
+    fn default() -> Self {
+        Self::new(env!("CARGO_PKG_VERSION"), "stable", true)
+    }
+}
+
+impl UpdateView {
+    /// 建一份初始状态。
+    #[must_use]
+    pub fn new(current: impl Into, channel: &str, auto_check: bool) -> Self {
+        Self {
+            current_version: current.into(),
+            channel: channel.to_string(),
+            auto_check,
+            outcome: UpdateOutcome::Idle,
+            checked_at: String::new(),
+            silent: false,
+            applying: false,
+            ready: None,
+            skipped: None,
+        }
+    }
+
+    /// 提示条此刻要显示什么（`None` = 不显示）。
+    ///
+    /// 优先级：就位 > 进行中 > 失败（仅主动查） > 有新版本（未被忽略）。
+    #[must_use]
+    pub fn banner(&self) -> Option> {
+        if let Some(ready) = &self.ready {
+            return Some(UpdateBanner::Ready(ready));
+        }
+        if self.applying {
+            return Some(UpdateBanner::Applying);
+        }
+        if let Some(failure) = self.outcome.failure() {
+            return (!self.silent).then_some(UpdateBanner::Failed(failure));
+        }
+        self.outcome
+            .candidate()
+            .filter(|candidate| self.skipped.as_deref() != Some(candidate.version.as_str()))
+            .map(UpdateBanner::Available)
+    }
+
+    /// 有没有「需要用户看一眼」的结论（提示条 / 就位后的重启提示 / 强制更新）。
+    #[must_use]
+    pub fn needs_attention(&self) -> bool {
+        self.banner().is_some()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn candidate(version: &str) -> UpdateCandidateView {
+        UpdateCandidateView {
+            version: version.to_string(),
+            size: 21_000_000,
+            notes: "修掉启动崩溃".to_string(),
+            forced: false,
+        }
+    }
+
+    #[test]
+    fn failure_is_not_up_to_date() {
+        let mut view = UpdateView {
+            outcome: UpdateOutcome::Failed(UpdateFailureView::new(
+                "network",
+                "取更新清单失败：连接被重置",
+                true,
+            )),
+            ..UpdateView::default()
+        };
+        assert!(view.outcome.failure().is_some());
+        assert!(view.outcome.candidate().is_none());
+        assert!(!matches!(view.outcome, UpdateOutcome::UpToDate { .. }));
+        assert_eq!(view.outcome.as_str(), "failed");
+
+        // 用户主动查出来的失败 → 提示条要说清原因（不是「已是最新」）。
+        assert!(matches!(view.banner(), Some(UpdateBanner::Failed(_))));
+        // 静默检查的失败 → 不弹条（离线是常态，别每次开机先骂网络一次）。
+        view.silent = true;
+        assert!(view.banner().is_none(), "静默检查失败不该变成提示条");
+        assert!(
+            view.outcome.failure().is_some(),
+            "但失败原因仍留在快照里（设置页要看）"
+        );
+    }
+
+    #[test]
+    fn skipping_one_version_does_not_silence_the_next_one() {
+        let mut view = UpdateView {
+            outcome: UpdateOutcome::Available(Box::new(candidate("0.2.3"))),
+            ..UpdateView::default()
+        };
+        assert!(matches!(view.banner(), Some(UpdateBanner::Available(_))));
+
+        view.skipped = Some("0.2.3".to_string());
+        assert!(view.banner().is_none(), "忽略 0.2.3 之后它自己不再打扰");
+        // 候选没被丢掉：设置页仍能显示「有新版本 0.2.3」并手动装
+        assert_eq!(
+            view.outcome.candidate().map(|item| item.version.as_str()),
+            Some("0.2.3")
+        );
+
+        // 同一次运行里冒出更高的版本：**照常提示**（文案是「忽略这个版本」，不是「别再问我」）。
+        view.outcome = UpdateOutcome::Available(Box::new(candidate("0.2.4")));
+        assert!(
+            matches!(view.banner(), Some(UpdateBanner::Available(c)) if c.version == "0.2.4"),
+            "0.2.3 被忽略不该压住 0.2.4"
+        );
+    }
+
+    #[test]
+    fn ready_state_replaces_the_banner() {
+        let view = UpdateView {
+            outcome: UpdateOutcome::Available(Box::new(candidate("0.2.3"))),
+            ready: Some(ReadyUpdate {
+                version: "0.2.3".to_string(),
+                path: "C:/ULL/unlucky-launcher.exe".to_string(),
+                backup: Some("C:/ULL/.unlucky-launcher.exe.ullold-1-0".to_string()),
+            }),
+            ..UpdateView::default()
+        };
+        assert!(matches!(view.banner(), Some(UpdateBanner::Ready(_))));
+        assert!(view.needs_attention(), "就位之后要提示重启");
+    }
+
+    #[test]
+    fn up_to_date_and_idle_show_no_banner() {
+        let mut view = UpdateView::default();
+        assert!(view.banner().is_none(), "Idle 还没查过，不该弹条");
+        view.outcome = UpdateOutcome::UpToDate {
+            latest: Some("0.2.2".to_string()),
+        };
+        assert!(view.banner().is_none(), "已是最新没有任何要说的");
+        view.outcome = UpdateOutcome::MissingArtifact {
+            version: "0.2.3".to_string(),
+        };
+        assert!(view.banner().is_none(), "缺产物不进提示条，进设置页原因");
+    }
+
+    #[test]
+    fn view_round_trips_as_ipc() {
+        let mut view = UpdateView::new("0.2.2", "stable", false);
+        view.checked_at = "11-08 12:00".to_string();
+        view.outcome = UpdateOutcome::UpToDate {
+            latest: Some("0.2.2".to_string()),
+        };
+        let text = serde_json::to_string(&view).expect("序列化");
+        let back: UpdateView = serde_json::from_str(&text).expect("反序列化");
+        assert_eq!(back, view);
+        assert!(!back.auto_check);
+    }
+}
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..eb019f1
--- /dev/null
+++ b/crates/presenter/src/host/accounts.rs
@@ -0,0 +1,358 @@
+//! 账户：三轨统一列表（只读公开字段）+ 离线新增 + 删除/切换 + 微软登录（两条流）。
+//!
+//! 凭据红线（D9）：`Credentials` / `MicrosoftSession` 只在本模块与 `launch.rs` 里出现，
+//! 出口一律是 [`AccountView`] / [`DeviceLoginView`]。
+//!
+//! 两条登录流（M178 改了默认）：**设备码是默认**（[`start_login`]：不依赖任何应用注册项），
+//! 授权码（[`start_browser_login`]，浏览器 + 本地回调）降级成「用户显式要求才试」的加速路，
+//! 且带回环注册预检 + 失败自动回退设备码。除了「怎么拿到 MS access_token」之外完全共用：
+//! 同一个取消槽位、同一段账户入库、同一个刷新链。
+//!
+//! 取消语义：轮询/等回调都跑在 `core` 里、没有取消钩子，所以取消只把面板收回；线程收尾时
+//! 若发现「已取消」就不入库（避免用户点了取消却凭空多出一个账户）。
+//!
+//! M132：缺 client id 只在**登录入口**失败（`auth_failure`），所以说明接在账户页的登录面板，
+//! 不接启动流程——没配 id 的发布版根本建不出微软账户，启动那条路用户撞不到。
+//!
+//! M236 拆分：两条流的编排搬到 `accounts/login.rs`（纯搬移，路径靠下面的 `pub use` 保住），
+//! 本文件只留列表/增删/句柄/测试缝——原文件正好 400 行零余量，测试缝换身份前必须先拆。
+
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+
+use unlucky_core::auth::account::Credentials;
+use unlucky_core::auth::microsoft::{now_ms, BrowserFallbackReason};
+use unlucky_core::auth::offline::offline_meta;
+use unlucky_core::auth::{AccountStore, AuthError};
+
+use crate::dto::CoreEvent;
+use crate::dto::{
+    valid_offline_name, AccountKind, AccountNotice, AccountNoticeCode, AccountView,
+    BrowserLoginNote, LoginFailure,
+};
+
+use super::env::HostEnv;
+
+/// 第三方轨（服务发现 / 密码登录 / 皮肤抓取）。
+pub mod authlib;
+
+mod login;
+
+mod refresh;
+
+mod failure;
+
+pub use failure::AccountFailure;
+
+pub use login::{start_browser_login, start_login};
+
+pub use authlib::{fetch_skin, spawn_probe, start_login as start_authlib_login};
+
+use failure::classify;
+
+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 {
+    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 {
+    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 {
+    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)]
+pub struct LoginJob {
+    /// 用户点了取消（线程收尾时据此丢弃结果）
+    pub cancelled: Arc,
+    /// 测试缝的**稳定身份**（见 `test_seam`）：进程内单调递增、永不复用。
+    ///
+    /// 只在测试构建里存在——发布产物不需要它。它会存在，是因为「这条记录属于哪个 job」
+    /// 不能用堆地址回答：地址是会被复用的资源，不是身份（M236 的 ABA 假红）。
+    #[cfg(test)]
+    id: JobId,
+}
+
+impl Default for LoginJob {
+    /// 与 [`LoginJob::new`] 同一个东西：`id` 不许走 `Default` 的零值，否则两个 job 撞身份。
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl LoginJob {
+    /// 新建一个未取消的句柄。
+    pub fn new() -> Self {
+        Self {
+            cancelled: Arc::new(AtomicBool::new(false)),
+            #[cfg(test)]
+            id: JobId::next(),
+        }
+    }
+
+    /// 取消。
+    pub fn cancel(&self) {
+        self.cancelled.store(true, Ordering::SeqCst);
+    }
+
+    /// 是否已取消。
+    pub fn is_cancelled(&self) -> bool {
+        self.cancelled.load(Ordering::SeqCst)
+    }
+}
+
+/// [`LoginJob`] 的稳定身份：进程内单调递增，**永不复用**。
+///
+/// 为什么不用 `Arc::as_ptr(&job.cancelled)`：job 一 drop，它的控制块就可以被下一个
+/// `LoginJob` 复用，于是「新 job」会读到「旧 job」记下的模式（ABA）——并行跑的用例因此
+/// 偶发假红（实测形态：设备码入口读到别人的 `browser_first=true`）。
+#[cfg(test)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+struct JobId(u64);
+
+#[cfg(test)]
+impl JobId {
+    /// 取下一个身份。`Relaxed` 够用：只要求唯一与单调，不要求跨线程的可见性顺序。
+    fn next() -> Self {
+        use std::sync::atomic::AtomicU64;
+
+        static NEXT: AtomicU64 = AtomicU64::new(1);
+        Self(NEXT.fetch_add(1, std::sync::atomic::Ordering::Relaxed))
+    }
+}
+
+/// 回退原因码 → 页面说明码（两边各留一个枚举：presenter 的 DTO 不依赖 core 的中文诊断）。
+fn browser_note(reason: BrowserFallbackReason) -> BrowserLoginNote {
+    match reason {
+        BrowserFallbackReason::RedirectNotRegistered => BrowserLoginNote::RedirectNotRegistered,
+        BrowserFallbackReason::PreflightUnavailable => BrowserLoginNote::PreflightUnavailable,
+        BrowserFallbackReason::AttemptFailed => BrowserLoginNote::AttemptFailed,
+    }
+}
+
+/// 微软登录的两个入口（决定 `MicrosoftAuth::browser_first`，M178）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum MsaEntry {
+    /// 默认路：设备码。**一个监听口都不开**，也永远不做回环预检。
+    DeviceCode,
+    /// 用户显式点了「用浏览器登录」：浏览器优先（预检 → 授权码 → 失败自动回退设备码）。
+    Browser,
+}
+
+impl MsaEntry {
+    /// 这个入口要不要把 `browser_first` 置位。
+    const fn browser_first(self) -> bool {
+        matches!(self, Self::Browser)
+    }
+}
+
+/// 测试缝：记下生产入口**实际请求**的模式，让守卫能钉住「按钮 → browser_first=true」这条线。
+///
+/// 为什么需要它：两条入口在没有 client id 的测试构建里都会在网络之前早退，拿不到
+/// `MicrosoftAuth` 实例去问 `browser_first()`；而 P1-1 的 bug 恰恰在**调用点**。这里在被调用
+/// 的一刻就把模式记下来，把调用点变成可断言的事实。
+///
+/// 为什么按 job 分桶：同一进程里别的用例也在调这两个入口，一个全局「最后一次」记录会串台
+/// （实测过：并行跑时读到别人的 Browser ⇒ 假红）。
+///
+/// **身份是 [`JobId`]，不是堆地址**（M236）：`Arc::as_ptr` 那种做法会被地址复用骗到——job A
+/// drop 之后控制块立刻分给 job B，B 于是读到 A 的记录（ABA 假红）。
+#[cfg(test)]
+mod test_seam {
+    use std::sync::atomic::AtomicBool;
+    use std::sync::{Arc, Mutex, Weak};
+
+    use super::{JobId, LoginJob, MsaEntry};
+
+    /// 表里的一条记录。
+    ///
+    /// `alive` 只用来回收「job 已经 drop」的条目，**不参与身份判定**（身份是 `job`）。它同时把
+    /// 控制块钉住：`Weak` 还在时控制块不会释放，`strong_count() == 0` 因此读得准。
+    pub(super) struct Entry {
+        job: JobId,
+        alive: Weak,
+        browser_first: bool,
+    }
+
+    impl Entry {
+        pub(super) fn new(job: JobId, cancelled: &Arc, browser_first: bool) -> Self {
+            Self {
+                job,
+                alive: Arc::downgrade(cancelled),
+                browser_first,
+            }
+        }
+
+        /// job 还活着吗（`false` ⇒ 这条只是还没被收走的死条目）。
+        pub(super) fn is_alive(&self) -> bool {
+            self.alive.strong_count() > 0
+        }
+
+        pub(super) fn job(&self) -> JobId {
+            self.job
+        }
+
+        pub(super) fn browser_first(&self) -> bool {
+            self.browser_first
+        }
+    }
+
+    static ENTRIES: Mutex> = Mutex::new(Vec::new());
+
+    /// 写一条记录：**同一个 job 只留最后一次**，顺手收走已 drop 的 job。
+    ///
+    /// 「多条时取第一条」的歧义在这里被消掉：表里每个 job 恒为一条，所以 [`mode_for`] 取到的
+    /// 那条就是它最后一次请求的模式。收死条目的 `retain` 也在这里——表只随活 job 增长。
+    pub(super) fn remember(entries: &mut Vec, entry: Entry) {
+        entries.retain(Entry::is_alive);
+        match entries.iter_mut().find(|known| known.job == entry.job) {
+            Some(slot) => slot.browser_first = entry.browser_first,
+            None => entries.push(entry),
+        }
+    }
+
+    /// 生产入口被调用时记一笔。
+    pub(super) fn record(job: &LoginJob, entry: MsaEntry) {
+        let mut entries = ENTRIES.lock().unwrap_or_else(|error| error.into_inner());
+        remember(
+            &mut entries,
+            Entry::new(job.id, &job.cancelled, entry.browser_first()),
+        );
+    }
+
+    /// 这个 job 的生产构造请求的模式（`None` = 还没调用过）。
+    pub(super) fn mode_for(job: &LoginJob) -> Option {
+        let entries = ENTRIES.lock().unwrap_or_else(|error| error.into_inner());
+        entries
+            .iter()
+            .find(|known| known.job == job.id)
+            .map(Entry::browser_first)
+    }
+
+    /// 造一个「共用同一个取消槽、但确定是另一个 job」的句柄（ABA 用例的构造件）。
+    ///
+    /// 两个不同 job 指向同一个控制块：这正是 `Arc::as_ptr` 做 key 时无法区分的情形。
+    pub(super) fn job_around(cancelled: &Arc) -> LoginJob {
+        LoginJob {
+            cancelled: Arc::clone(cancelled),
+            id: JobId::next(),
+        }
+    }
+}
+
+/// `msa_auth` 失败 → 原因码。
+///
+/// **只有「两处都没配 client id」单独成码**（M132）：`from_env` 的 `Unsupported` 是它唯一的
+/// 产出点，且这条路径零网络。上屏的正文是 catalog 里的固定文案（原文照旧只进日志），理由是
+/// 这一类的原因就是用户的下一步（设 `ULL_MSA_CLIENT_ID`）；其余失败仍走 [`classify`]。
+fn auth_failure(error: &AuthError) -> LoginFailure {
+    match error {
+        AuthError::Unsupported(_) => LoginFailure::MsaNotConfigured,
+        other => classify(other),
+    }
+}
+
+#[cfg(test)]
+mod tests;
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) -> 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 {
+    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 {
+    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), 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, 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/login.rs b/crates/presenter/src/host/accounts/login.rs
new file mode 100644
index 0000000..f599ed5
--- /dev/null
+++ b/crates/presenter/src/host/accounts/login.rs
@@ -0,0 +1,161 @@
+//! 微软登录的两条流（设备码默认 / 浏览器优先失败回退设备码）+ 会话入库。
+//!
+//! 从 `accounts.rs` 拆出来（M236）：父文件顶着 400 行硬线，而本轮要给测试缝换一个**稳定身份**
+//! （`Arc::as_ptr` 会被堆地址复用骗到，见父模块的 `test_seam`），拆出子模块才有地方落。
+//!
+//! **纯搬移**：下面每个函数体、每一行签名都与搬移前逐行相同（没有改一个字的可见性）；原来的
+//! 公开路径靠父模块的 `pub use` 保住（`host::accounts::start_login` / `start_browser_login`）。
+//!
+//! 两条流除了「怎么拿到 MS access_token」之外完全共用：同一个取消槽位（父模块的 `LoginJob`）、
+//! 同一段入库（`store_session`）、同一个收尾（`finish`）——所以它们必须住在同一个文件里。
+
+use unlucky_core::auth::account::Credentials;
+use unlucky_core::auth::microsoft::{now_ms, MicrosoftAuth, MicrosoftSession};
+use unlucky_core::auth::{AccountStore, AuthResult};
+use unlucky_core::download::blocking::block_on;
+
+use crate::dto::{DeviceLoginView, LoginFailure};
+
+use super::super::env::HostEnv;
+use super::super::job::{spawn, HostTask, JobSender};
+use super::super::opener;
+use super::failure::classify;
+#[cfg(test)]
+use super::test_seam;
+use super::{accounts, auth_failure, browser_note, LoginJob, MsaEntry};
+
+/// 起一次微软登录（M178：**GUI 的默认路**——设备码）。
+///
+/// 设备码流不依赖任何应用注册项，是唯一「在官方产物上开箱可用」的路；它**一个本地监听口都不开**，
+/// 也就不会撞上 `redirect_uri is not valid`（守卫断言 `listeners_opened == 0`，在 bind 现场加）。
+pub fn start_login(env: HostEnv, tx: JobSender, job: LoginJob) {
+    spawn("msa-login", move || {
+        let auth = match msa_auth(&env, MsaEntry::DeviceCode, &job) {
+            Ok(auth) => auth,
+            Err(error) => return fail(&tx, auth_failure(&error), error.to_string()),
+        };
+        let tx_prompt = tx.clone();
+        let result = block_on(auth.device_code_login(|prompt| {
+            let _ = tx_prompt.send(HostTask::Login(Box::new(DeviceLoginView::waiting(
+                &prompt.user_code,
+                &prompt.verification_uri,
+                prompt.expires_in.as_secs(),
+                &format!("{}#{}", prompt.verification_uri, prompt.user_code),
+            ))));
+        }));
+        finish(&env, &tx, &job, result);
+    });
+}
+
+/// 起一次「浏览器优先、失败自动回退设备码」的登录（M178：可选加速路）。
+///
+/// 只在用户**显式要求**时才走到这里（账户页的「用浏览器登录」）。即使如此也不盲试：`core` 先做
+/// 回环注册预检，没登记就**不绑端口、不弹浏览器**，直接设备码；试了但失败同样回退并给一句说明。
+pub fn start_browser_login(env: HostEnv, tx: JobSender, job: LoginJob) {
+    spawn("msa-browser", move || {
+        // **P1-1 的那一行**：这里是「用户点了用浏览器登录」，必须把 browser_first 置位，
+        // 否则下面这段预检/回退编排整段不执行（复审 r1 实测的洞）。
+        let auth = match msa_auth(&env, MsaEntry::Browser, &job) {
+            Ok(auth) => auth,
+            Err(error) => return fail(&tx, auth_failure(&error), error.to_string()),
+        };
+        let tx_browser = tx.clone();
+        let tx_device = tx.clone();
+        let result = block_on(auth.browser_then_device_login(
+            |prompt| {
+                // 浏览器拉不起来不是致命错误：面板里还有可复制的授权链接。
+                let opened = opener::open_url(&prompt.authorization_url);
+                let _ =
+                    tx_browser.send(HostTask::Login(Box::new(DeviceLoginView::browser_waiting(
+                        &prompt.authorization_url,
+                        prompt.timeout.as_secs(),
+                        opened.err().as_deref(),
+                    ))));
+            },
+            |prompt, fallback| {
+                let view = DeviceLoginView::waiting(
+                    &prompt.user_code,
+                    &prompt.verification_uri,
+                    prompt.expires_in.as_secs(),
+                    &format!("{}#{}", prompt.verification_uri, prompt.user_code),
+                );
+                let view = match fallback {
+                    Some(fallback) => {
+                        // 回退原文只进日志；面板只看码。
+                        eprintln!(
+                            "[auth] 浏览器登录未走成（{}），已回退设备码：{}",
+                            fallback.reason.code(),
+                            fallback.detail
+                        );
+                        view.with_browser_note(browser_note(fallback.reason))
+                    }
+                    None => view,
+                };
+                let _ = tx_device.send(HostTask::Login(Box::new(view)));
+            },
+        ));
+        finish(&env, &tx, &job, result.map(|outcome| outcome.session));
+    });
+}
+
+/// 生产入口的 `MicrosoftAuth`（client id 取环境/构建期，失败日志落 `<数据根>/logs/`）。
+///
+/// **`browser_first` 必须在这里按入口置位**（复审 r1 P1-1）：只构造默认 `MicrosoftAuth` 的话，
+/// 浏览器按钮会静默退化成设备码——预检/回退码/说明全不可达。
+fn msa_auth(env: &HostEnv, entry: MsaEntry, _job: &LoginJob) -> AuthResult {
+    #[cfg(test)]
+    test_seam::record(_job, entry);
+    MicrosoftAuth::from_env().map(|auth| {
+        auth.with_browser_first(entry.browser_first())
+            .with_journal(Some(unlucky_core::auth::AuthJournal::in_logs_dir(
+                env.layout.logs(),
+            )))
+    })
+}
+
+/// 失败收尾（带**原因码**）：原文进日志，页面据码出 i18n（复审 r1 P1-1）。
+fn fail(tx: &JobSender, failure: LoginFailure, detail: impl Into) {
+    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) {
+    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 {
+    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)
+}
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/accounts/tests.rs b/crates/presenter/src/host/accounts/tests.rs
new file mode 100644
index 0000000..1e9ac58
--- /dev/null
+++ b/crates/presenter/src/host/accounts/tests.rs
@@ -0,0 +1,362 @@
+//! 账户 host 的判据：入库/删除/名字规则、失败分类，以及**缺 client id 的上屏链路**（M132）。
+//!
+//! ## 为什么这个文件要跟 `accounts.rs` 分开
+//!
+//! `accounts.rs` 顶着 400 行硬线，而 M132 的锚必须**真的走一遍登录入口**（`start_login` /
+//! `start_browser_login`）才能钉住「入口 → 原因码」那一行——只测 `auth_failure` 的话，把调用点
+//! 改回 `LoginFailure::Other` 仍然全绿（复审 r1 P2-1 实测）。测试拆出来是为了留出这段空间。
+//!
+//! 拆法照抄仓库既有先例（`dto/accounts.rs`、`host/install.rs` 等）：父文件里留
+//! `#[cfg(test)] mod tests;`，本文件 `use super::*;` 照旧拿到父模块的一切。
+
+use std::sync::atomic::AtomicBool;
+use std::sync::Arc;
+use std::time::Duration;
+
+use unlucky_core::auth::microsoft::{client_id_status, CLIENT_ID_ENV};
+use unlucky_core::auth::AuthError;
+
+use super::*;
+
+use super::super::job::{HostTask, JobSender};
+use super::failure::mentions_whitelist;
+
+#[test]
+fn time_display_matches_known_timestamps() {
+    assert_eq!(display_ms(0), "");
+    // 1_769_000_000_000 ms = 2026-01-21T12:53:20Z（取整到分钟）
+    assert_eq!(display_ms(1_769_000_000_000), "2026-01-21 12:53");
+}
+
+#[test]
+fn offline_add_list_remove_round_trips() {
+    let dir = std::env::temp_dir().join(format!("ull-host-accounts-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    let env = HostEnv::at_root(&dir);
+    std::fs::create_dir_all(env.layout.auth_data()).expect("auth 目录");
+
+    let name = add_offline(&env, "Steve").expect("加账户");
+    assert_eq!(name, "Steve");
+    let list = accounts(&env, None);
+    assert_eq!(list.len(), 1);
+    assert_eq!(list[0].kind, AccountKind::Offline);
+    assert!(!list[0].active);
+
+    let active = accounts(&env, Some(list[0].id.as_str()));
+    assert!(active[0].active);
+
+    let removed = remove(&env, "Steve").expect("删账户");
+    assert_eq!(removed, "Steve");
+    assert!(accounts(&env, None).is_empty());
+    assert!(add_offline(&env, "  ").is_err());
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+fn denied(code: &str) -> AuthError {
+    AuthError::Denied {
+        code: code.to_string(),
+        description: "bad".to_string(),
+    }
+}
+
+fn network() -> AuthError {
+    AuthError::Network {
+        url: "https://x".to_string(),
+        detail: "dns".to_string(),
+    }
+}
+
+#[test]
+fn failure_codes_are_classified_from_variants_not_chinese_text() {
+    assert_eq!(classify(&network()), LoginFailure::Unreachable);
+    let whitelist = classify(&denied("AADSTS7000218"));
+    assert_eq!(whitelist, LoginFailure::NotWhitelisted);
+    assert_eq!(classify(&denied("invalid_grant")), LoginFailure::Denied);
+    assert_eq!(classify(&AuthError::Canceled), LoginFailure::Other);
+    assert!(mentions_whitelist("AADSTS7000218"));
+    assert!(!mentions_whitelist("invalid_grant"));
+}
+
+/// **M132**：只有「缺 client id」变成「需要配置」，网络/凭据失败不许跟着变（否则成噪音）。
+#[test]
+fn only_a_missing_client_id_becomes_the_config_gap_code() {
+    let missing = auth_failure(&AuthError::Unsupported(String::new()));
+    assert_eq!(missing, LoginFailure::MsaNotConfigured);
+    assert_eq!(auth_failure(&network()), LoginFailure::Unreachable);
+    assert_eq!(auth_failure(&denied("invalid_grant")), LoginFailure::Denied);
+}
+
+/// **M132 的入口锚（复审 r1 P2-1）**：缺 client id 时，**两条登录流**回给页面的那条事件里
+/// 必须带 `MsaNotConfigured`。
+///
+/// 抓得住（实测过的变异）：把 `start_login` / `start_browser_login` 里的
+/// `auth_failure(&error)` 改回 `LoginFailure::Other`——那是页面退回「完整原因在启动器日志里」
+/// 的唯一开关，而 `auth_failure` 自己的单测对它一声不响。
+/// 零网络：`MicrosoftAuth::from_env` 在 id 判定处就地早退，连 HTTP 客户端都不建，所以这里
+/// 不需要任何桩，也不会因为没网而红。
+///
+/// **它要求一个「两处都没有 client id」的构建**：构建期烘焙了 id（`option_env!`）的构建里它
+/// `panic!` 而不是跳过——跳过就等于让这条锚悄悄失效（r2 复审实测过那种形态），红着喊人才
+/// 逼得人做决定（不带 id 构建，或给 `resolve_client_id` 加接缝后重写这条锚）。
+#[test]
+fn a_missing_client_id_reaches_the_login_panel_as_a_config_gap() {
+    // 环境变量是**进程级**的：动它的用例必须串行（core 侧同一套写法），否则并行跑互相污染。
+    static ENV_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
+
+    let _lock = ENV_LOCK.lock().unwrap_or_else(|error| error.into_inner());
+    let saved = std::env::var(CLIENT_ID_ENV).ok();
+    std::env::remove_var(CLIENT_ID_ENV);
+    // panic 也要还原：不还原的话后面所有用例都会在一个「没配 id」的进程里跑。
+    struct Restore(Option);
+    impl Drop for Restore {
+        fn drop(&mut self) {
+            match self.0.take() {
+                Some(value) => std::env::set_var(CLIENT_ID_ENV, value),
+                None => std::env::remove_var(CLIENT_ID_ENV),
+            }
+        }
+    }
+    let _restore = Restore(saved);
+
+    // 环境变量已经摘掉了，此时若仍报告「已配置」，来源只可能是构建期注入
+    // （`ULL_MSA_CLIENT_ID= cargo build` ⇒ `option_env!`），或者 `resolve_client_id` 的
+    // 实现变了。**这种构建里必须红**：这条锚验证不了缺 id 路径，静默 `return` 就是让锚悄悄失效
+    // （r2 复审实测：注入 id + 同一变异 → 全绿 22 passed，正是塔台最怕的「守门空跑」形态）。
+    if let Some(source) = client_id_status().source() {
+        panic!(
+            "这条锚要求「两处都没有 client id」的构建，但二进制里 client id 已被报告为已配置\
+             （source={source:?}，环境变量 {CLIENT_ID_ENV} 已摘掉）。要么不带 \
+             ULL_MSA_CLIENT_ID 构建，要么给 `unlucky_core::auth::microsoft::resolve_client_id` \
+             加一个可注入的接缝，再按接缝重写这条锚。"
+        );
+    }
+
+    assert_config_gap("device", start_login);
+    assert_config_gap("authcode", start_browser_login);
+}
+
+/// 起一条登录流、等它回的第一条登录事件，并断言那是一条「缺配置」而不是通用失败。
+///
+/// 缺 id 时这条路径**零网络**（`from_env` 在 id 判定处早退），所以事件立刻到，不需要桩。
+fn assert_config_gap(name: &str, start: fn(HostEnv, JobSender, LoginJob)) {
+    let dir = std::env::temp_dir().join(format!("ull-msa-{name}-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    let (tx, rx) = super::super::job::channel();
+    start(HostEnv::at_root(&dir), tx, LoginJob::new());
+    let view = match rx.recv_timeout(Duration::from_secs(10)) {
+        Ok(HostTask::Login(view)) => view,
+        Ok(_) => panic!("{name}：缺 id 时第一条事件就该是登录失败"),
+        Err(error) => panic!("{name}：等不到登录事件（{error}）"),
+    };
+    assert_eq!(view.failure, Some(LoginFailure::MsaNotConfigured), "{name}");
+    // 原文（含要设的变量名）仍然只在 `message` 里：它只进日志，页面画不出来。
+    assert!(
+        view.message.contains(CLIENT_ID_ENV),
+        "{name}: {}",
+        view.message
+    );
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+#[test]
+fn offline_name_rule_matches_the_ui_contract() {
+    assert!(valid_offline_name("Steve"));
+    assert!(valid_offline_name("a_1"));
+    assert!(!valid_offline_name("ab"), "太短");
+    assert!(!valid_offline_name("中文名字"), "非 ascii");
+    assert!(!valid_offline_name("has space"));
+    assert!(!valid_offline_name("x"));
+}
+
+#[test]
+fn a_bad_offline_name_is_classified_not_stringified() {
+    let dir = std::env::temp_dir().join(format!("ull-name-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    let env = HostEnv::at_root(&dir);
+    std::fs::create_dir_all(env.layout.auth_data()).expect("auth 目录");
+    let failure = add_offline(&env, "ab").expect_err("太短要报错");
+    assert_eq!(failure.code, AccountNoticeCode::OfflineNameInvalid);
+    assert!(!failure.detail.is_empty());
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+#[test]
+fn login_job_cancel_flag_is_shared() {
+    let job = LoginJob::new();
+    let clone = job.clone();
+    assert!(!clone.is_cancelled());
+    job.cancel();
+    assert!(clone.is_cancelled());
+}
+
+/// **M178 复审 r1 P1-1 的守卫**：生产路径上，「用浏览器登录」这颗按钮必须真的把
+/// `browser_first` 置位，设备码那颗必须不置位。
+///
+/// 修复前实测过的形态：`start_browser_login` 用共享的 `microsoft_auth(&env)`（默认
+/// `browser_first=false`），于是 `browser_then_device_login` 里整段预检/回退编排不执行——
+/// 按钮静默退化成设备码、连一句说明都不出，`preflight` / `BrowserFallbackReason` /
+/// `BrowserLoginNote` / 三条 i18n 文案全成不可达代码。
+///
+/// 抓得住（本用例就是为此写的）：把 `msa_auth(&env, MsaEntry::Browser)` 改回
+/// `MsaEntry::DeviceCode`（或删掉 `.with_browser_first(...)` 那一跳以外的模式选择），
+/// 记录会变成 `false` ⇒ 红。
+/// 抓不住：真的去连微软（无 client id 的测试构建里两条入口都在网络之前早退）。
+#[test]
+fn the_browser_button_actually_turns_on_browser_first() {
+    let dir = std::env::temp_dir().join(format!("ull-msa-entry-{}", 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 device_job = LoginJob::new();
+    let (tx, _rx) = super::super::job::channel();
+    start_login(env.clone(), tx, device_job.clone());
+    assert_eq!(
+        wait_for_entry(&device_job),
+        Some(false),
+        "设备码入口把 browser_first 置成了 true：默认路会去开监听口/弹浏览器"
+    );
+
+    // 浏览器入口：**必须**置位，否则预检与回退整段不可达。
+    let browser_job = LoginJob::new();
+    let (tx, _rx) = super::super::job::channel();
+    start_browser_login(env, tx, browser_job.clone());
+    assert_eq!(
+        wait_for_entry(&browser_job),
+        Some(true),
+        "「用浏览器登录」没有置位 browser_first：按钮会静默退化成设备码（复审 r1 P1-1 的洞）"
+    );
+}
+
+/// 等登录线程把「这个 job 的入口模式」记下来（线程是 `spawn` 出去的，最多等这么久）。
+///
+/// 按 job 分桶而不是读「最后一次」：同一进程里别的用例也在调这两个入口（实测会串台假红）。
+fn wait_for_entry(job: &LoginJob) -> Option {
+    for _ in 0..200 {
+        if let Some(flag) = super::test_seam::mode_for(job) {
+            return Some(flag);
+        }
+        std::thread::sleep(Duration::from_millis(10));
+    }
+    None
+}
+
+/// **M236（台账「真开着的测试债」之一）：测试缝的身份不许是会复用的堆地址。**
+///
+/// 构造：两个**不同**的 `LoginJob` 共用同一个 `cancelled` 控制块地址（`Arc::clone` 不换地址，
+/// `job_around` 各自给一个新身份）。这正是 `Arc::as_ptr` 做 key 时那个假设——「地址相同 ⇒
+/// 同一个 job」——失效的形态；真实世界里它由「job A 被 drop 后控制块立刻分给 job B」触发。
+///
+/// 反向证据（实测过）：把身份退回 `Arc::as_ptr` ⇒ 本用例红（`mode_for(&younger)` 读到
+/// `Some(true)`）；那个读串台正是并行跑时「设备码入口读到别人的 browser_first=true」的假红。
+/// 抓不住：两条入口真的去连微软（无 client id 的测试构建里它们都在网络之前早退）。
+#[test]
+fn the_test_seam_does_not_reuse_a_heap_address_as_identity() {
+    let shared = Arc::new(AtomicBool::new(false));
+    let older = super::test_seam::job_around(&shared);
+    let younger = super::test_seam::job_around(&shared);
+    assert_eq!(
+        Arc::as_ptr(&older.cancelled),
+        Arc::as_ptr(&younger.cancelled),
+        "前提：两个 job 必须共用同一个取消槽地址（否则本用例什么也没构造出来）"
+    );
+    assert_eq!(
+        super::test_seam::mode_for(&younger),
+        None,
+        "前提：这两个 job 都还没请求过"
+    );
+    super::test_seam::record(&older, MsaEntry::Browser);
+    assert_eq!(
+        super::test_seam::mode_for(&older),
+        Some(true),
+        "前提：记录本身要能按 job 读回来"
+    );
+    assert_eq!(
+        super::test_seam::mode_for(&younger),
+        None,
+        "同一个堆地址、但确定是另一个 job：读到 older 的记录就是把「会被复用的地址」当身份"
+    );
+}
+
+/// **M236**：测试缝的书写规则——每 job 恒一条（覆盖成最后一次）、死 job 的条目被 `retain` 收走。
+///
+/// 改之前 `ENTRIES` 只 push 不 clear/retain：条目随登录次数无上限增长；`mode_for` 又用「第一条」
+/// 回答，同一个 job 记两次（重试）时会永远读到第一次的模式。
+/// 这里直接对纯函数 `remember` 造活/死条目，不碰全局表——并行用例不会互相污染。
+#[test]
+fn the_test_seam_keeps_the_latest_mode_per_job_and_forgets_dropped_ones() {
+    let alive = Arc::new(AtomicBool::new(false));
+    // 一个已经 drop 的 job：`Entry` 里的 `Weak` 把控制块钉住 ⇒ `strong_count() == 0` 读得准。
+    let dead = {
+        let gone = Arc::new(AtomicBool::new(false));
+        super::test_seam::Entry::new(JobId(1), &gone, true)
+    };
+    assert!(!dead.is_alive(), "构造失败：这条应当已经是死条目");
+
+    let mut entries = vec![dead, super::test_seam::Entry::new(JobId(2), &alive, false)];
+    super::test_seam::remember(
+        &mut entries,
+        super::test_seam::Entry::new(JobId(2), &alive, true),
+    );
+
+    assert_eq!(
+        entries.len(),
+        1,
+        "死 job 的条目必须被收走（表只随活 job 增长）"
+    );
+    assert_eq!(entries[0].job(), JobId(2));
+    assert!(
+        entries[0].browser_first(),
+        "同一个 job 记两次必须取最后一次"
+    );
+}
+
+/// 置位不是「记了个数」：`msa_auth` 必须把模式真的落到 `MicrosoftAuth::browser_first` 上。
+///
+/// 前半段（入口 → 模式）由上一个用例守；这里守后半段（模式 → 实例字段）。两者缺一，
+/// 就会出现「日志说置位了、实际没置位」这类假绿。
+#[test]
+fn the_entry_mode_lands_on_the_auth_instance() {
+    assert!(!MsaEntry::DeviceCode.browser_first());
+    assert!(MsaEntry::Browser.browser_first());
+    // 无 client id 时 `from_env` 早退，所以这里用显式 id 走同一个 builder 链。
+    let auth = unlucky_core::auth::microsoft::MicrosoftAuth::new("0000-entry-test")
+        .expect("构造")
+        .with_browser_first(MsaEntry::Browser.browser_first());
+    assert!(
+        auth.browser_first(),
+        "with_browser_first 没把字段置上（core 里 browser_then_device_login 会整段跳过）"
+    );
+}
+
+/// **M178**：core 的回退原因码 → 页面的说明码。两边的 ascii 码必须逐字相同——
+/// 日志里看到的码就是页面上 `Code:` 那一行，对不上就没法用用户回报的码定位。
+///
+/// 抓得住：core 加/改一个回退原因而 presenter 忘了接（`browser_note` 是 `match`，
+/// 新增变体会编译失败；这里再把**码的字符串**钉住，防的是两侧各改各的）。
+#[test]
+fn browser_fallback_reasons_map_to_the_page_notes_with_the_same_codes() {
+    for (reason, note) in [
+        (
+            BrowserFallbackReason::RedirectNotRegistered,
+            BrowserLoginNote::RedirectNotRegistered,
+        ),
+        (
+            BrowserFallbackReason::PreflightUnavailable,
+            BrowserLoginNote::PreflightUnavailable,
+        ),
+        (
+            BrowserFallbackReason::AttemptFailed,
+            BrowserLoginNote::AttemptFailed,
+        ),
+    ] {
+        assert_eq!(browser_note(reason), note);
+        assert_eq!(note.code(), reason.code());
+    }
+    // 「没登记回环」是唯一带「怎么修」的那一条，码也必须稳定（排障脚本按它 grep 日志）。
+    assert_eq!(
+        BrowserLoginNote::RedirectNotRegistered.code(),
+        "redirect_not_registered"
+    );
+}
diff --git a/crates/presenter/src/host/addon.rs b/crates/presenter/src/host/addon.rs
new file mode 100644
index 0000000..ff2eb56
--- /dev/null
+++ b/crates/presenter/src/host/addon.rs
@@ -0,0 +1,124 @@
+//! 内容库的宿主实现（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`] | 一键装入：解析文件（含 `required` 前置）→ 下载到实例目录 → 进度回流 |
+//! | [`downloads`] | 下载阶段（可测）：逐个下、失败进名单不中断、两处取消点 |
+//! | [`plan`] | 依赖计划的宿主侧：扫目录、两档失败 → DTO 大类、人读文案 |
+//!
+//! ## 整合包与 CF 的边界（都写进报告）
+//!
+//! - 整合包**不做**「一键装入」：`ContentKind::Modpack.dir()` 是 `None`，UI 侧按钮禁用带原因，
+//!   host 侧再挡一次（就算绕过 UI 发指令也只回一条 `Failed`）。真流程是 M111 的导入管线。
+//! - CurseForge 本轮只做**检索**（需要用户配 `ULL_CF_API_KEY`），文件解析未接通。
+
+mod downloads;
+mod http;
+mod install;
+mod plan;
+// M113: import/export —— 整合包导入/导出（拆成子目录：父文件只留既有内容 + mod）
+mod pack;
+mod sources;
+
+pub(super) use pack::{cancel_pack, pack_epoch, take_terminal_epoch};
+
+#[cfg(test)]
+mod tests;
+
+use std::sync::atomic::AtomicBool;
+use std::sync::Arc;
+
+use crate::dto::{
+    ContentDetail, ContentDetailRequest, ContentFailure, 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 {
+    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 = sources::search(&env, &query);
+        let _ = tx.send(HostTask::Content(Box::new(result)));
+    });
+}
+
+/// 后台取项目详情 + 版本列表（M162；选中项目才发，一条独立通道）。
+pub fn spawn_detail(env: HostEnv, tx: JobSender, request: ContentDetailRequest) {
+    spawn("content-detail", move || {
+        let project = request.project.clone();
+        let result: Result = sources::detail(&env, &request);
+        let _ = tx.send(HostTask::ContentDetail {
+            project,
+            result: Box::new(result),
+        });
+    });
+}
+
+/// 后台「装进指定实例」。
+pub fn spawn_install(
+    env: HostEnv,
+    tx: JobSender,
+    request: crate::dto::ContentInstallRequest,
+    cancel: Arc,
+    epoch: u64,
+) {
+    spawn("content-install", move || {
+        install::install(&env, &tx, &request, &cancel, epoch);
+    });
+}
diff --git a/crates/presenter/src/host/addon/downloads.rs b/crates/presenter/src/host/addon/downloads.rs
new file mode 100644
index 0000000..3d91061
--- /dev/null
+++ b/crates/presenter/src/host/addon/downloads.rs
@@ -0,0 +1,315 @@
+//! 下载阶段的**可测那一段**：把计划里的文件逐个下下来，失败进名单而不中断。
+//!
+//! # 为什么单独一个文件
+//!
+//! 这段逻辑以前整块躺在 `install::run` 里，而 `run` 需要实例目录 + 真引擎 ⇒ 没有用例能驱动它，
+//! 于是「下载失败记进两档名单」这条改动**整段删掉也不会红一条**（M186 r2 复审实测：
+//! 整段包进 `if false` 后 `cargo test -p unlucky-presenter --lib host::addon` 仍 36 passed）。
+//! 抽成只依赖 [`ArtifactFetcher`] 的函数之后，假下载器就能驱动它。
+//!
+//! # 三条不变量（每条都有用例）
+//!
+//! 1. **失败不中断**：某个文件下载失败 ⇒ 记进 [`DependencyPlan::record_failure`]，继续下一个；
+//! 2. **已装的不回滚**：成功的文件留在盘上，并出现在返回的「已装」名单里；
+//! 3. **两处取消点**：进入本阶段先查一次（`run` 解析完就调它 ⇒ 解析阶段的取消生效，
+//!    全部文件都「已存在」而 `nodes` 为空时也不会漏掉取消），循环每次迭代再查一次。
+
+use std::path::Path;
+use std::sync::atomic::{AtomicBool, Ordering};
+
+use unlucky_core::addon::online::{
+    download_verified, ArtifactFetcher, DependencyFailure, DependencyPlan, FailureKind,
+    OnlineError, PlannedNode,
+};
+use unlucky_core::download::blocking::block_on;
+
+use crate::dto::{ContentFailure, InstallProgressView};
+
+use super::super::job::{HostTask, JobSender};
+use super::install::{local, node_label, safe_file_name};
+
+/// 下载失败 → 两档失败里的一条（`Unreachable` + 叶子成因 `cause`）。
+///
+/// 为什么归 `Unreachable`：`download_verified` 的失败就是「取不到这份字节」——没网 / 站点错 /
+/// 内容与声明不符 / 本地 IO，叶子成因留在 `cause` 上，上层照 `sources::failure_of` 映射成
+/// DTO 大类；**不是** `Incompatible`（换版本/加载器也救不了一次断网）。
+#[must_use]
+pub(super) fn download_failure(node: &PlannedNode, error: &OnlineError) -> DependencyFailure {
+    DependencyFailure {
+        requested_as: node.requested_as.clone(),
+        required_by: node.required_by.clone(),
+        depth: node.depth,
+        kind: FailureKind::Unreachable,
+        cause: Some(error.kind()),
+        message: format!(
+            "下载 {} 失败（{}）：{}",
+            node.file.filename,
+            error.kind().as_str(),
+            error.message()
+        ),
+    }
+}
+
+/// 下载阶段：先查一次取消，再逐个下（失败进名单、不中断）。
+///
+/// 返回**真落盘**的节点（失败的不在里面），调用方据此拼「装了 N 个」。
+///
+/// # Errors
+/// 用户取消时返回一条 `ContentFailure`（detail 以「已取消」开头，`install()` 据此画 `Cancelled`）。
+pub(super) fn download_stage(
+    plan: &mut DependencyPlan,
+    target_dir: &Path,
+    fetcher: &dyn ArtifactFetcher,
+    cancel: &AtomicBool,
+    progress: &mut InstallProgressView,
+    tx: &JobSender,
+    epoch: u64,
+) -> Result, ContentFailure> {
+    // 解析完立刻查一次：解析最多要跑 6 层版本请求，此时取消不该先下一份文件再说
+    // （main 的 `resolve_file` 之后就有这条检查，r2 复审指出我们把它丢了）。
+    if cancel.load(Ordering::SeqCst) {
+        return Err(local("已取消（下载开始前）"));
+    }
+    let mut installed: Vec = Vec::new();
+    for index in 0..plan.nodes.len() {
+        if cancel.load(Ordering::SeqCst) {
+            return Err(local("已取消（下载中途）"));
+        }
+        let node = plan.nodes[index].clone();
+        progress.message = node_label(&node);
+        let _ = tx.send(HostTask::Install {
+            progress: Box::new(progress.clone()),
+            epoch,
+        });
+        // M162：走 `online::download_verified`——sha1 交给引擎流式校验、sha512 落盘后复核，
+        // 失败重试且不留半截文件（内容库安装与整合包导入用**同一段**校验，不各写一份）。
+        let dest = target_dir.join(safe_file_name(&node.file.filename));
+        let outcome = block_on(download_verified(
+            fetcher,
+            &node.file.url,
+            node.file.sha1(),
+            node.file.sha512(),
+            (node.file.size > 0).then_some(node.file.size),
+            &dest,
+        ));
+        match outcome {
+            Ok(_) => installed.push(node),
+            Err(error) => {
+                // 下载阶段的失败**也记进同一套两档结构**（Unreachable + 叶子成因）：
+                // 已下好的不回滚、失败项进「可只重试」，整份计划的上下文（缺的是谁的前置）不丢。
+                plan.record_failure(download_failure(&node, &error));
+                continue;
+            }
+        }
+        progress.files_done += 1;
+        let _ = tx.send(HostTask::Install {
+            progress: Box::new(progress.clone()),
+            epoch,
+        });
+    }
+    Ok(installed)
+}
+
+#[cfg(test)]
+mod tests {
+    use std::sync::atomic::AtomicBool;
+    use std::sync::Mutex;
+
+    use unlucky_core::addon::online::{
+        ArtifactFetcher, DependencyPlan, FailureKind, FetchArgs, OnlineError, OnlineErrorKind,
+        OnlineFuture, PlannedNode, ResolveRequest, VersionFile,
+    };
+
+    use crate::dto::InstallProgressView;
+
+    use super::{download_failure, download_stage};
+
+    /// 假下载器：`fail_on` 里的文件名一律「没联网」，其余写一行字节（**不校验摘要**）。
+    struct FakeFetcher {
+        fail_on: Vec<&'static str>,
+        attempts: Mutex>,
+    }
+
+    impl FakeFetcher {
+        fn new(fail_on: &[&'static str]) -> Self {
+            Self {
+                fail_on: fail_on.to_vec(),
+                attempts: Mutex::new(Vec::new()),
+            }
+        }
+
+        fn attempts(&self) -> Vec {
+            self.attempts.lock().expect("锁没中毒").clone()
+        }
+    }
+
+    impl ArtifactFetcher for FakeFetcher {
+        fn fetch<'a>(&'a self, args: FetchArgs<'a>) -> OnlineFuture<'a, Result> {
+            Box::pin(async move {
+                let name = args
+                    .dest
+                    .file_name()
+                    .map(|name| name.to_string_lossy().to_string())
+                    .unwrap_or_default();
+                self.attempts.lock().expect("锁没中毒").push(name.clone());
+                if self.fail_on.contains(&name.as_str()) {
+                    return Err(OnlineError::offline("假装的断网"));
+                }
+                std::fs::write(args.dest, b"jar").map_err(|error| {
+                    OnlineError::new(OnlineErrorKind::Io, format!("写盘失败：{error}"))
+                })?;
+                Ok(4)
+            })
+        }
+    }
+
+    fn node(project: &str, file: &str, required_by: &[&str]) -> PlannedNode {
+        PlannedNode {
+            project: project.to_string(),
+            requested_as: project.to_string(),
+            version_id: format!("ver-{project}"),
+            version_name: project.to_string(),
+            version_number: "1.0".to_string(),
+            file: VersionFile {
+                url: format!("https://cdn.modrinth.com/data/{project}/1.0/{file}"),
+                filename: file.to_string(),
+                size: 0,
+                ..VersionFile::default()
+            },
+            depth: u8::from(!required_by.is_empty()),
+            required_by: required_by
+                .iter()
+                .map(|parent| (*parent).to_string())
+                .collect(),
+        }
+    }
+
+    fn plan(nodes: Vec) -> DependencyPlan {
+        DependencyPlan {
+            request: ResolveRequest::single("AANobbMI"),
+            nodes,
+            skipped: Vec::new(),
+            failures: Vec::new(),
+            truncated: Vec::new(),
+            unresolved_required: Vec::new(),
+        }
+    }
+
+    fn temp_dir(tag: &str) -> std::path::PathBuf {
+        let dir = std::env::temp_dir().join(format!("ull-m186-{tag}-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        std::fs::create_dir_all(&dir).expect("建临时目录");
+        dir
+    }
+
+    /// 失败的那一条**进名单**、父边与叶子成因都带着（守的是 [`download_failure`] 的映射）。
+    #[test]
+    fn a_download_error_becomes_an_unreachable_failure_with_its_leaf_cause() {
+        let node = node("P7dR8mSH", "fabric-api.jar", &["AANobbMI"]);
+        let failure = download_failure(&node, &OnlineError::offline("连不上 cdn.modrinth.com"));
+
+        assert_eq!(failure.kind, FailureKind::Unreachable);
+        assert_eq!(failure.cause, Some(OnlineErrorKind::NotConnected));
+        assert_eq!(failure.requested_as, "P7dR8mSH");
+        assert_eq!(failure.required_by, ["AANobbMI".to_string()]);
+        assert_eq!(failure.depth, 1);
+        assert!(
+            failure.message.contains("fabric-api.jar"),
+            "{}",
+            failure.message
+        );
+        assert!(
+            failure.message.contains("online_not_connected"),
+            "成因要带 code：{}",
+            failure.message
+        );
+    }
+
+    /// 第 2 个文件失败：**不中断**、已装的不回滚、失败进名单、第 3 个仍会被尝试。
+    #[test]
+    fn a_failed_file_does_not_stop_the_rest_and_keeps_what_already_landed() {
+        let dir = temp_dir("download-partial");
+        let mut plan = plan(vec![
+            node("AANobbMI", "sodium.jar", &[]),
+            node("P7dR8mSH", "fabric-api.jar", &["AANobbMI"]),
+            node("1eAoo2KR", "yacl.jar", &["P7dR8mSH"]),
+        ]);
+        let fetcher = FakeFetcher::new(&["fabric-api.jar"]);
+        let (tx, _rx) = std::sync::mpsc::channel();
+        let mut progress = InstallProgressView {
+            files_total: 3,
+            ..InstallProgressView::new()
+        };
+
+        let installed = download_stage(
+            &mut plan,
+            &dir,
+            &fetcher,
+            &AtomicBool::new(false),
+            &mut progress,
+            &tx,
+            7,
+        )
+        .expect("没取消就不该回 Err");
+
+        let names: Vec<&str> = installed
+            .iter()
+            .map(|node| node.file.filename.as_str())
+            .collect();
+        assert_eq!(
+            names,
+            ["sodium.jar", "yacl.jar"],
+            "成功的不回滚、后面的照下"
+        );
+        // 失败的那个会被 `download_verified` 重试 `RETRY_ATTEMPTS` 次（这里 3 次），
+        // 关键是**它之后**还会去试第 3 个文件。
+        let attempts = fetcher.attempts();
+        assert_eq!(attempts.first().map(String::as_str), Some("sodium.jar"));
+        assert_eq!(attempts.last().map(String::as_str), Some("yacl.jar"));
+        assert_eq!(
+            attempts
+                .iter()
+                .filter(|name| *name == "fabric-api.jar")
+                .count(),
+            3,
+            "失败的尝试 + 重试都发生在第 3 个文件之前：{attempts:?}"
+        );
+        assert_eq!(plan.failures.len(), 1, "{:?}", plan.failures);
+        assert_eq!(plan.failures[0].requested_as, "P7dR8mSH");
+        assert!(plan.failures[0].message.contains("fabric-api.jar"));
+        assert_eq!(progress.files_done, 2, "进度只数真落盘的");
+        assert!(dir.join("sodium.jar").exists(), "已下好的文件不许删");
+        assert!(!dir.join("fabric-api.jar").exists());
+        assert!(dir.join("yacl.jar").exists());
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+
+    /// 解析完就取消 ⇒ 一条文件都不下（r2 nit②：main 有这条检查，我们曾把它丢了）。
+    #[test]
+    fn cancelling_right_after_resolution_touches_nothing() {
+        let dir = temp_dir("download-cancelled");
+        let mut plan = plan(vec![
+            node("AANobbMI", "sodium.jar", &[]),
+            node("P7dR8mSH", "fabric-api.jar", &["AANobbMI"]),
+        ]);
+        let fetcher = FakeFetcher::new(&[]);
+        let (tx, _rx) = std::sync::mpsc::channel();
+        let mut progress = InstallProgressView::new();
+
+        let error = download_stage(
+            &mut plan,
+            &dir,
+            &fetcher,
+            &AtomicBool::new(true),
+            &mut progress,
+            &tx,
+            7,
+        )
+        .expect_err("取消必须回 Err");
+
+        assert!(error.detail.contains("已取消"), "{}", error.detail);
+        assert!(fetcher.attempts().is_empty(), "一份都不许下");
+        assert!(plan.failures.is_empty(), "取消不是失败，不进名单");
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+}
diff --git a/crates/presenter/src/host/addon/http.rs b/crates/presenter/src/host/addon/http.rs
new file mode 100644
index 0000000..60ff41f
--- /dev/null
+++ b/crates/presenter/src/host/addon/http.rs
@@ -0,0 +1,321 @@
+//! HTTP 取文本（内容库唯一的网络出口）。
+//!
+//! ## 两条路径，为什么不是一条
+//!
+//! | 请求 | 走哪 | 拿到什么 |
+//! |---|---|---|
+//! | 无自定义 header（[`get_via_engine`]，**生产零调用者**：内容库的 Modrinth 走 core 的 `EngineTransport`，同一条 `download_bytes`） | [`DownloadEngine::download_bytes`] | **信号量限流 + 源健康度 + 指数退避 + 分类错误**，全是 core 现成的 |
+//! | 带 header（只有 CurseForge 的 `X-API-KEY`） | `engine.client()` 直发 | 引擎的请求体没有 header 字段，只能自己发；代价是这条路径自己带一个 429/5xx 退避 |
+//!
+//! 两条路径用的是**同一个引擎**，而引擎是进程级共享的（M165：`host::engine::engine` →
+//! `core::download::shared::engine_for`，一个数据根一个）。所以 Modrinth 与 CurseForge 的请求、
+//! 以及它们与真正的文件下载，共用同一条连接池与同一套限流；`block_on` 也跑在同一个常驻运行时上，
+//! 池里的空闲连接不会随着某次调用结束而变成死连接。
+//!
+//! ## UA 只有一份定义（M207）
+//!
+//! `User-Agent` 定义在 core 的 `download::http::USER_AGENT`：`Unlucky-Launcher/
+//! (+https://github.com/AskaEth/Unlucky-Launcher)`。本文件**不拼** UA——带 header 的路径发的是
+//! `engine.config().user_agent`，无 header 的路径发的是同一个客户端的默认 UA，所以两条路径、以及真正的
+//! 文件下载，站点看到的都是同一个字符串。
+//!
+//! M205 复审核实过的旧状：`api.modrinth.com` 收到的是引擎那份 `UnluckyLauncher/`（无连字符、
+//! 无联系方式），带联系方式的 `Unlucky-Launcher/ (+repo)` 只发给 CurseForge 搜索——而 Modrinth 的
+//! UA 政策正是「带联系方式，否则限流」，也就是说那条政策在**真正会被限流的那条路上**没被满足。两份 UA
+//! 同时活着、改一处不带另一处，所以 M207 把定义收进 core 一处。
+//!
+//! 钉住它的是回环上的字节级用例 `both_download_paths_send_the_same_user_agent`：两条路径发出去的
+//! `User-Agent` 必须逐字节相同，且等于 `EngineConfig::default().user_agent`。
+//!
+//! ## 密钥纪律
+//!
+//! 带 header 的那条路径**只把 header 值喂给请求**：不进日志、不进错误串。错误串里只有 URL
+//! （CF 的 URL 不含密钥）与状态码。
+
+use std::time::Duration;
+
+use unlucky_core::download::blocking::block_on;
+use unlucky_core::download::config::DEFAULT_MAX_ATTEMPTS_PER_SOURCE;
+use unlucky_core::download::{DownloadRequest, ResourceKind};
+
+use super::super::env::HostEnv;
+
+/// 最多重试次数（含首次）。
+///
+/// **不在这里写数字**：取值就是下载引擎的出厂默认
+/// （`core::download::config::DEFAULT_MAX_ATTEMPTS_PER_SOURCE`，`download.retry_limit` 的 schema
+/// 默认值同源），改工厂默认时这里跟着走。
+///
+/// 边界说清：这条路径**没读**宿主设置（次数是编译期常量），所以固定吃出厂默认——**不是拿不到**。
+/// `env` 就在手上（`get_with_headers` 第一句 `engine(env)` 已经灌过调优），用户当前值就在
+/// `engine.config().max_attempts_per_source`；要让它跟随 `download.retry_limit`，读那个字段即可，
+/// 不需要新拉一条参数链。另一条无 header 的路径（[`get_via_engine`]）走引擎，本来就跟随设置
+/// （源冷却中时引擎只给 1 次，那是恢复探测，见 `DownloadEngine::attempts_for`）。
+const ATTEMPTS: u32 = DEFAULT_MAX_ATTEMPTS_PER_SOURCE;
+
+/// 取一段文本（JSON 原文）。
+pub(super) fn get(env: &HostEnv, url: &str, headers: &[(&str, &str)]) -> Result {
+    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 {
+    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 {
+    let engine = super::super::engine::engine(env);
+    // UA 取自引擎配置（**不在这里拼**）：定义只有 core 那一份，这条路径与引擎路径发的必须是同一个字符串。
+    let user_agent = engine.config().user_agent.clone();
+    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.as_str());
+            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::().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::().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
+}
+
+#[cfg(test)]
+mod tests {
+    use std::io::{Read as _, Write as _};
+    use std::net::TcpListener;
+    use std::time::Duration;
+
+    use unlucky_core::download::shared;
+
+    use super::get;
+    use crate::host::env::HostEnv;
+
+    /// 离线回环 HTTP 服务：只答固定 JSON，把每条请求的**原始请求头**送回主线程。
+    ///
+    /// 用 127.0.0.1 而不是真站点：**单测不许打公网**（CI 没网，也不该有）。回传原始头部是为了抓
+    /// 「站点实际收到的 `User-Agent`」——那是唯一能证明两条路径发同一个字符串的地方。
+    fn loopback(expected_requests: usize) -> (String, std::sync::mpsc::Receiver>) {
+        let listener = TcpListener::bind("127.0.0.1:0").expect("绑定回环端口");
+        let addr = listener.local_addr().expect("取端口");
+        let (tx, rx) = std::sync::mpsc::channel();
+        std::thread::spawn(move || {
+            let mut heads: Vec = Vec::new();
+            while heads.len() < expected_requests {
+                let Ok((mut socket, _)) = listener.accept() else {
+                    break;
+                };
+                let _ = socket.set_read_timeout(Some(Duration::from_secs(5)));
+                let mut seen = Vec::new();
+                loop {
+                    let mut chunk = [0u8; 1024];
+                    match socket.read(&mut chunk) {
+                        Ok(0) | Err(_) => break,
+                        Ok(read) => seen.extend_from_slice(&chunk[..read]),
+                    }
+                    if !seen.windows(4).any(|window| window == b"\r\n\r\n") {
+                        continue;
+                    }
+                    heads.push(String::from_utf8_lossy(&seen).into_owned());
+                    let body = br#"{"ok":true}"#;
+                    let reply = format!(
+                        "HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\n\r\n",
+                        body.len()
+                    );
+                    if socket.write_all(reply.as_bytes()).is_err()
+                        || socket.write_all(body).is_err()
+                    {
+                        break;
+                    }
+                    seen.clear();
+                    if heads.len() >= expected_requests {
+                        let _ = tx.send(heads);
+                        return;
+                    }
+                }
+            }
+            let _ = tx.send(heads);
+        });
+        (format!("http://{addr}/v2/search"), rx)
+    }
+
+    /// 一条原始请求头里 `User-Agent` 的值（大小写不敏感：reqwest 发的是小写字段名）。
+    fn user_agent_of(head: &str) -> Option {
+        head.lines().find_map(|line| {
+            let (name, value) = line.split_once(':')?;
+            name.trim()
+                .eq_ignore_ascii_case("user-agent")
+                .then(|| value.trim().to_string())
+        })
+    }
+
+    /// 一个只用来放缓存根的临时数据根（`/.ULL/cache`）。
+    fn data_root(tag: &str) -> std::path::PathBuf {
+        static SEQ: std::sync::atomic::AtomicUsize = std::sync::atomic::AtomicUsize::new(0);
+        let seq = SEQ.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
+        let dir = std::env::temp_dir().join(format!("ull-http-{tag}-{}-{seq}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        std::fs::create_dir_all(dir.join(".ULL").join("cache")).expect("建缓存根");
+        dir
+    }
+
+    /// 两条下载路径发出去的 `User-Agent` 必须是**同一个字符串**，且就是引擎配置里那一个（M207）。
+    ///
+    /// 为什么读回环上的字节、而不是断言常量相等：`header("User-Agent", …)` 到底传了什么，只有抓包才算
+    /// 「站点看到的事实」；断言两个常量相等只说明「借了同一个名字」，谁在发送处又拼了一份照旧全绿。
+    ///
+    /// 三段内容的正面断言在 core（`download::http` 的用例
+    /// `the_user_agent_carries_the_package_version_and_the_repo_url`：版本 == `CARGO_PKG_VERSION`、
+    /// 联系方式段 == 仓库 URL、不含邮箱）。这里钉的是**两条路径同源**：无 header 那条发引擎 reqwest
+    /// 客户端的默认 UA，带 header 那条发 `engine.config().user_agent`，两者都必须对
+    /// `EngineConfig::default()` 逐字节相等。
+    ///
+    /// 抓得住：presenter 又自己拼一份 UA（哪怕只差产品名的连字符）⇒ 红；发送处把 header 删掉或写成空串 ⇒ 红；
+    /// 客户端的默认 UA 与配置字段分叉（`build_client` 不再读 `cfg.user_agent`）⇒ 红。
+    /// 抓不住：真实 Modrinth / CurseForge 收到这条 UA 之后怎么限流（单测不出网）；也抓不住「联系方式
+    /// 那一串是不是站点认可的格式」——那要真发一次才知道。
+    #[test]
+    fn both_download_paths_send_the_same_user_agent() {
+        let dir = data_root("ua");
+        let env = HostEnv::at_root(&dir);
+        let (url, seen) = loopback(2);
+
+        get(&env, &url, &[]).expect("无 header 路径（引擎 `download_bytes`）");
+        get(&env, &url, &[("x-api-key", "test-key")])
+            .expect("带 header 路径（`engine.client()` 直发）");
+
+        let heads = seen
+            .recv_timeout(Duration::from_secs(10))
+            .expect("回环服务应回传请求头");
+        let sent: Vec = heads
+            .iter()
+            .filter_map(|head| user_agent_of(head))
+            .collect();
+        assert_eq!(sent.len(), 2, "两条请求都要带 User-Agent：{heads:?}");
+        assert_eq!(sent[0], sent[1], "两条路径的 UA 必须是同一个字符串");
+
+        let defined = unlucky_core::download::config::EngineConfig::default().user_agent;
+        assert_eq!(
+            sent[0], defined,
+            "发出去的 UA 必须就是引擎配置里那一个（定义只有 core 一份）"
+        );
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    /// **端到端守卫（M165 复审备注 2）**：连走三条真实宿主请求路径，只该构造一个引擎。
+    ///
+    /// 为什么不满足于「再断言一次 `engine()` 复用」：那种断言只钉漏斗本身——将来谁在调用点
+    /// 自己 `DownloadEngine::new`，它照旧全绿。这里数的是 `shared::constructions`，而记账卡在
+    /// `DownloadEngine::new` 这个卡口上（与谁造的无关），所以只要有一条路径另造引擎就会红。
+    ///
+    /// 三条路径：
+    /// 1. [`get`] 无 header = [`get_via_engine`]（走 `engine.download_bytes`）。**生产零调用者**：内容库的
+    ///    Modrinth 元数据 GET 走 core 的 `EngineTransport`（同一条 `download_bytes`），不经本文件；
+    /// 2. [`get`] 带 header = CurseForge 那条（走 `engine.client()`，另一条机制）；
+    /// 3. `host::java::vendors` = Java 页渲染（走 `domestic()`，非 HTTP 的漏斗消费者）。
+    ///
+    /// 没走 `versions` 清单：它的地址是写死的 launchermeta，单测里要么打真网、要么吃满连接超时
+    /// —— 那正是「测试里不该发生的事」，所以选了同样真实但完全离线的三条。
+    #[test]
+    fn three_host_request_paths_share_one_engine() {
+        let dir = data_root("paths");
+        let env = HostEnv::at_root(&dir);
+        let cache_root = env.layout.cache();
+        let (url, seen) = loopback(2);
+
+        let without_headers = get(&env, &url, &[]).expect("无 header 路径（`get_via_engine`）");
+        let with_headers =
+            get(&env, &url, &[("x-api-key", "test-key")]).expect("带 header 路径（CF）");
+        let vendors = crate::host::java::vendors(&env, &[]);
+
+        assert_eq!(
+            without_headers, with_headers,
+            "两条路径读的是同一份回环响应"
+        );
+        assert!(!vendors.is_empty(), "Java 页应有发行版行");
+        let heads = seen
+            .recv_timeout(Duration::from_secs(10))
+            .expect("回环服务应回传请求头");
+        assert_eq!(heads.len(), 2, "两条 HTTP 路径各发一条请求");
+        assert_eq!(
+            shared::constructions(&cache_root),
+            1,
+            "三条宿主请求路径必须共用同一个引擎（谁绕过漏斗另造一个，这条就红）"
+        );
+        std::fs::remove_dir_all(&dir).ok();
+    }
+}
diff --git a/crates/presenter/src/host/addon/install.rs b/crates/presenter/src/host/addon/install.rs
new file mode 100644
index 0000000..991aadc
--- /dev/null
+++ b/crates/presenter/src/host/addon/install.rs
@@ -0,0 +1,321 @@
+//! 「一键装入指定实例」（M109；M186 起把前置一起装上）。
+//!
+//! ## 网络只走 code 的在线内容源（M162 r1）
+//!
+//! 解析「哪个文件」用 `core::addon::online`（同一个引擎传输层 ⇒ 信号量、源健康度、退避都在
+//! 引擎里），下载用 `online::download_verified`（sha1 + sha512 双检）。本文件**不再**自己拼
+//! `api.modrinth.com` 的 URL，也不再自己 `serde_json::from_str`。
+//!
+//! ## 它到底做了什么（诚实版）
+//!
+//! | 内容类型 | 做什么 | 状态 |
+//! |---|---|---|
+//! | Mod / 资源包 / 光影 | 解析「该项目 + 它的 `required` 前置」在目标实例（版本 + 加载器）下的文件 → core 下载引擎下到 `mods/` `resourcepacks/` `shaderpacks/` → 进度经 `InstallProgressView` 回流 | 已接（M186 起含前置） |
+//! | 整合包 | 一律 `Failed` + 一句原因 | **未做**：core 没有「远程整合包装进实例」的管线（M111） |
+//! | CurseForge 文件解析 | 一律 `Failed` + 一句原因 | **未做**：需要带 key 的文件端点，本轮只做了 CF 的**检索** |
+//!
+//! ## 前置的两档失败与重试名单（M186 / M191）
+//!
+//! 解析在 [`super::plan`] + `core::addon::online::resolve`：某个前置「不兼容所选版本/加载器」
+//! 与「取不到（网络 / 项目不存在）」是**两条**记录，本文件把两档分开写进失败文案，并把失败项
+//! 列成「可只重试这 N 个」。**这不是自动重试**：重试要用户点（M191 的界面入口）。
+//!
+//! ## 「只重试这些」真的只重试这些（M191）
+//!
+//! 上一轮失败时，那份 `DependencyPlan` 被 [`plan::remember`] 记下来；`ContentInstallRequest.retry`
+//! 为真的第二次请求走 [`run`] 的重试入口——它调 core 的 `DependencyPlan::retry_request()`，
+//! 于是重解**只请求失败的那几个项目**（`present` 重新扫一遍目录，已装好的不会被重下）。
+//! 没有记录时回一条失败，**不**退化成「整单重装」：那会把已装好的再下一遍、请求数放大。
+//!
+//! 下载阶段的失败**也进同一套名单**（M186 r1）：以前 `download_verified` 一失败就整单中断，
+//! 用户既看不到「主文件已装、缺 fabric-api」，也拿不到可重试的项目。现在逐个文件下、失败记进
+//! `DependencyPlan::record_failure`（`Unreachable` + 叶子成因），已下好的不回滚，最后一起收口。
+//!
+//! ## 光影与数据包：支持到哪一步（M186 核对过，别写成「都支持」）
+//!
+//! | 内容 | 检索 | 装入 | 差在哪 |
+//! |---|---|---|---|
+//! | 光影 | 支持（`project_type:shader`）；命中项的加载器标签现在认得 `iris` / `optifine`（`KNOWN_LOADERS`） | 支持（落 `shaderpacks/`） | 加载器**过滤**仍筛不了：`LoaderKind::OptiFine` 没有 facet（`loader_facet` 返回 `None`），所以「只看 Iris 光影」只能靠标签目测 |
+//! | 数据包 | core 的 `ContentType::Datapack` 有 `datapack` facet | **不支持** | DTO 的 `ContentKind` 没有这一项；数据包还要落到「某个世界的 `datapacks/`」，现在没有选择世界这一步 |
+//!
+//! ## 为什么进度只有阶段级，没有字节条
+//!
+//! 字节级进度要走 `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::addon::online::{
+    resolve, EngineArtifactFetcher, EngineTransport, Modrinth, PlannedNode,
+};
+use unlucky_core::download::blocking::block_on;
+use unlucky_core::game::install::instance::read_instance_config;
+use unlucky_core::game::isolation::derive_game_dir;
+
+use crate::dto::{
+    loader_facet, ContentFailure, ContentFailureKind, ContentInstallRequest, ContentSource,
+    InstallProgressView, InstallStage, InstanceSummary,
+};
+
+use super::super::env::HostEnv;
+use super::super::job::{HostTask, JobSender};
+mod collect;
+
+pub(super) use collect::{collect, Placement, Ports};
+
+use super::{downloads, plan};
+
+/// 跑一次装入（同步；由 [`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(),
+        // 文件数要等解析完才知道（含前置），这里留 0 = 未知（面板画不确定态）。
+        files_total: 0,
+        ..InstallProgressView::new()
+    };
+
+    // 整合包：core 没有这条管线（M111），**不**假装能装。UI 侧按钮本来就是禁用的，
+    // 这里再挡一次是为了「绕过 UI 直接发指令」也不会静默做半件事。
+    // 重试模式不看 `kind`：那种模式下落盘目录来自上一次的计划（见 `run`）。
+    if !request.retry && request.kind.dir().is_none() {
+        fail(
+            tx,
+            progress,
+            ContentFailure::unsupported("整合包安装尚未开放；内容库对整合包只做检索"),
+            epoch,
+        );
+        return;
+    }
+
+    let _ = tx.send(HostTask::Install {
+        progress: Box::new(progress.clone()),
+        epoch,
+    });
+    match run(env, request, cancel, &mut progress, tx, epoch) {
+        Ok(done) => {
+            finish(&mut progress);
+            progress.message = done;
+            let _ = tx.send(HostTask::InstallDone {
+                progress: Box::new(progress),
+                result: Ok(request.title.clone()),
+                epoch,
+            });
+        }
+        Err(failure) => {
+            progress.stage = if cancel.load(Ordering::SeqCst) {
+                InstallStage::Cancelled
+            } else {
+                InstallStage::Failed
+            };
+            progress.message = failure.detail.clone();
+            progress.failure_kind = Some(failure.kind);
+            let _ = tx.send(HostTask::InstallDone {
+                progress: Box::new(progress),
+                result: Err(failure),
+                epoch,
+            });
+        }
+    }
+}
+
+fn fail(tx: &JobSender, mut progress: InstallProgressView, failure: ContentFailure, epoch: u64) {
+    progress.stage = InstallStage::Failed;
+    progress.message = failure.detail.clone();
+    progress.failure_kind = Some(failure.kind);
+    let _ = tx.send(HostTask::InstallDone {
+        progress: Box::new(progress),
+        result: Err(failure),
+        epoch,
+    });
+}
+
+/// 真正干活的那一段：解析（含前置）→ 逐个下载 → 汇总。
+///
+/// 返回「装了哪些 / 跳过了哪些」的人读描述；解析阶段的两档失败由
+/// [`plan::failure_of_plan`] 变成一条带大类的失败（**前置缺了不算装成**）。
+///
+/// 两条解析入口，别混：
+///
+/// | 入口 | 请求从哪来 | 发几次 |
+/// |---|---|---|
+/// | 首次装入 | 根项目 + 过滤条件（[`plan::request`]） | 一次，从根开始 BFS |
+/// | **只重试失败项** | 上一轮计划的 `retry_request()`（[`plan::retry_plan`]） | 一次，**只含失败的那几个项目** |
+fn run(
+    env: &HostEnv,
+    request: &ContentInstallRequest,
+    cancel: &AtomicBool,
+    progress: &mut InstallProgressView,
+    tx: &JobSender,
+    epoch: u64,
+) -> Result {
+    let instance = find_instance(env, &request.instance)?;
+
+    // 「只重试这些」：输入是上一轮那份计划，**不**重新发起根项目安装。
+    // 没有记录时（换了实例 / 进程重启过）回一条失败，而不是退化成「整单重装」。
+    if request.retry {
+        let Some(saved) = plan::remembered(env, &request.instance) else {
+            return Err(local(RETRY_LOST));
+        };
+        // 面板头继续显示那次的显示名（不是项目 id：r1 复审 N5）
+        progress.version = saved.title.clone();
+        let present = plan::present_files(&saved.dir);
+        let core_engine = super::super::engine::engine(env);
+        let dependency_plan = plan::retry_plan(&saved.plan, present, |retry| {
+            let transport = EngineTransport::new(&core_engine);
+            let client = Modrinth::new(&transport);
+            block_on(resolve(&client, retry))
+        });
+        let fetcher = EngineArtifactFetcher::new(&core_engine);
+        let title = |id: &str| plan::fetch_title(env, id);
+        let ports = Ports {
+            env,
+            fetcher: &fetcher,
+            title: &title,
+        };
+        return collect(
+            &ports,
+            request,
+            dependency_plan,
+            Placement {
+                dir: &saved.dir,
+                root: plan::Root {
+                    id: &saved.root,
+                    title: &saved.title,
+                },
+            },
+            cancel,
+            progress,
+            tx,
+            epoch,
+        );
+    }
+
+    let game_dir = game_dir_of(env, &instance)?;
+    let dir = request
+        .kind
+        .dir()
+        .ok_or_else(|| local("该内容类型不支持单文件装入"))?;
+    let target_dir = game_dir.join(dir);
+    std::fs::create_dir_all(&target_dir)
+        .map_err(|error| local(format!("建目录 {} 失败：{error}", target_dir.display())))?;
+    if request.source != ContentSource::Modrinth {
+        return Err(ContentFailure::unsupported(
+            "CurseForge 的文件解析未接通（要带 key 的文件端点；见报告「没验的部分」）",
+        ));
+    }
+
+    // 解析：根项目 + 只跟 `required` 的前置（顺序与父子关系由 core 给，这里不重排）。
+    let resolve_request = plan::request(
+        &request.project,
+        &request.game_version,
+        loader_facet(request.loader),
+        plan::present_files(&target_dir),
+    );
+    let core_engine = super::super::engine::engine(env);
+    let dependency_plan = {
+        let transport = EngineTransport::new(&core_engine);
+        let client = Modrinth::new(&transport);
+        block_on(resolve(&client, &resolve_request))
+    };
+    let fetcher = EngineArtifactFetcher::new(&core_engine);
+    let title = |id: &str| plan::fetch_title(env, id);
+    let ports = Ports {
+        env,
+        fetcher: &fetcher,
+        title: &title,
+    };
+    collect(
+        &ports,
+        request,
+        dependency_plan,
+        Placement {
+            dir: &target_dir,
+            root: plan::Root {
+                id: &request.project,
+                title: &request.title,
+            },
+        },
+        cancel,
+        progress,
+        tx,
+        epoch,
+    )
+}
+
+/// 没有可重试的记录时那句话（**不**退化成「整单重装」）。
+const RETRY_LOST: &str =
+    "没有可重试的记录：这次失败发生在别的实例上、或进程重启过。请重新装入那一次。";
+
+/// 完成态：`files_done` 对齐 `files_total`。
+///
+/// 别在这里另写数字：以前写死 `1`，装 3 个文件后终态是 `1/3`，下载页只要「已知」就画确定态
+/// 进度条 ⇒ 装完了条还停在 1/3（全部跳过时更糟，`1/0`）。
+pub(super) fn finish(progress: &mut InstallProgressView) {
+    progress.stage = InstallStage::Done;
+    progress.files_done = progress.files_total;
+}
+
+/// 进度面板上的那一行文件名（前置标出来，用户才知道多出来的文件是什么）。
+pub(super) fn node_label(node: &PlannedNode) -> String {
+    if node.is_root() {
+        node.file.filename.clone()
+    } else {
+        format!("{}（前置）", node.file.filename)
+    }
+}
+
+/// 本地失败（找实例 / 建目录 / 取消）——不是网络问题，归到 `Other`。
+pub(super) fn local(reason: impl Into) -> ContentFailure {
+    ContentFailure::new(ContentFailureKind::Other, reason)
+}
+
+fn find_instance(env: &HostEnv, id: &str) -> Result {
+    super::super::game::instances(env)
+        .into_iter()
+        .find(|instance| instance.id == id)
+        .ok_or_else(|| local(format!("找不到实例 {id}")))
+}
+
+/// 实例的运行目录（D20 覆盖链：实例 `isolation` > 全局 `instances.mode`）。
+fn game_dir_of(env: &HostEnv, instance: &InstanceSummary) -> Result {
+    let global = super::super::game::global_mode(env);
+    let config = read_instance_config(&env.layout, &instance.id)
+        .map_err(|error| local(format!("读实例设置失败：{error}")))?;
+    derive_game_dir(
+        &env.game,
+        &instance.version_id,
+        global,
+        config.as_ref(),
+        None,
+    )
+    .map(|derivation| derivation.game_dir)
+    .map_err(|error| local(format!("隔离目录派生失败：{error}")))
+}
+
+/// 只留文件名本身：站点给的名字可能带路径分隔符，落盘前必须砍掉
+/// （与 `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/install/collect.rs b/crates/presenter/src/host/addon/install/collect.rs
new file mode 100644
index 0000000..199bfcb
--- /dev/null
+++ b/crates/presenter/src/host/addon/install/collect.rs
@@ -0,0 +1,117 @@
+//! 解析之后的公共尾巴：进度 → 逐个下载 → 收口（失败名单 / 计划留存）。
+//!
+//! 从 `install.rs` 拆出（r3 复审的接线守卫加完 `Ports` 之后父文件到 415 行，越过 400 行硬线）。
+//! 拆法同既有 `-p1/-p2`：**纯搬移**，调用方路径不变（`install.rs` 仍 `pub(super) use` 这三个名字）。
+//!
+//! 为什么不把 `Ports` 再往里藏：`collect` 是**要能在用例里真跑**的那一段（r3 复审 p2：
+//! 「失败路径真的去取了名字」原来零覆盖）。下载器与取名字器从参数进来，假实现就能驱动整条
+//! 收口路径，不碰网络。
+
+use std::path::Path;
+use std::sync::atomic::AtomicBool;
+
+use unlucky_core::addon::online::{ArtifactFetcher, DependencyPlan};
+
+use crate::dto::{ContentFailure, ContentInstallRequest, InstallProgressView, InstallStage};
+
+use crate::host::env::HostEnv;
+use crate::host::job::{HostTask, JobSender};
+
+use super::{downloads, plan};
+
+/// `collect` 要用的「外部世界」：宿主环境 + 下载器 + 取名字器。
+///
+/// 三样都从这里进，是为了让**收口那段能在用例里真跑**：假下载器 + 假取名字器就能驱动
+/// 「下载 → 收口 → 失败名单」整条路，于是「失败路径真的去取了不兼容档的名字」这件事有用例
+/// 钉住（r3 复审 p2：那一行原来删掉也全绿）。
+pub(in crate::host::addon) struct Ports<'a> {
+    /// 宿主环境（记「上一轮的计划」要用它的数据根）
+    pub(in crate::host::addon) env: &'a HostEnv,
+    /// 下载器（生产 = 引擎；用例 = 假实现，不碰网络）
+    pub(in crate::host::addon) fetcher: &'a dyn ArtifactFetcher,
+    /// 取项目显示名（生产 = [`plan::fetch_title`]；用例 = 假实现）
+    pub(in crate::host::addon) title: &'a dyn Fn(&str) -> Option,
+}
+
+/// 「装到哪 + 那次装入的根是谁」——总是一起出现，捆成一个参数（否则 `collect` 顶破 8 个）。
+pub(in crate::host::addon) struct Placement<'a> {
+    /// 落盘目录（`mods/` / `resourcepacks/` / `shaderpacks/`）
+    pub(in crate::host::addon) dir: &'a Path,
+    /// 当初那次装入的根项目（id + 显示名）；重试轮里由 `plan::remembered` 提供
+    ///
+    /// **必须**带 id：重试那一轮 `plan.request.roots` 是上一轮的失败名单，不能拿它判「是不是根」
+    /// （r2 复审 P2-2 就是这条：第一前置被贴上了根的标题）。
+    pub(in crate::host::addon) root: plan::Root<'a>,
+}
+
+/// 解析之后**两条入口共用**的尾巴：进度 → 逐个下载 → 收口。
+///
+/// 收口的两件事在同一个地方做，是因为它们必须同时发生：
+///
+/// | 结果 | 计划 | 可重试名单 |
+/// |---|---|---|
+/// | 有失败 | 记下（`plan::remember`，重试的输入） | 填（界面据此画「只重试这 N 个」） |
+/// | 全成功 | 忘掉（`plan::forget`） | 清空（界面**不渲染**那条入口） |
+pub(in crate::host::addon) fn collect(
+    ports: &Ports<'_>,
+    request: &ContentInstallRequest,
+    mut dependency_plan: DependencyPlan,
+    placement: Placement<'_>,
+    cancel: &AtomicBool,
+    progress: &mut InstallProgressView,
+    tx: &JobSender,
+    epoch: u64,
+) -> Result {
+    progress.stage = InstallStage::Downloading;
+    progress.files_total = dependency_plan.nodes.len() as u64;
+    progress.files_done = 0;
+    progress.message = if dependency_plan.nodes.is_empty() {
+        "没有要下载的文件".to_string()
+    } else {
+        format!(
+            "{} 个文件（含 {} 个前置）",
+            dependency_plan.nodes.len(),
+            dependency_plan
+                .nodes
+                .iter()
+                .filter(|node| !node.is_root())
+                .count()
+        )
+    };
+    let _ = tx.send(HostTask::Install {
+        progress: Box::new(progress.clone()),
+        epoch,
+    });
+
+    // 下载阶段在 `downloads.rs`：可测（假下载器能驱动），失败进名单而不中断。
+    let installed = downloads::download_stage(
+        &mut dependency_plan,
+        placement.dir,
+        ports.fetcher,
+        cancel,
+        progress,
+        tx,
+        epoch,
+    )?;
+
+    // 解析与下载两段的失败在这里一起收口：两档分成两句话（不合并成「下载失败」），
+    // 并列出「可只重试这 N 个」。
+    if let Some(failure) = plan::failure_of_plan(&dependency_plan, installed.len()) {
+        // 「不兼容」那一档项目**存在**（站点只是没有匹配目标版本/加载器的条目），所以在这里
+        // 现取一次名字——只在失败路径上发、一个项目一次 GET，取不到就退回 id（见 `names_for_incompatible`）。
+        let names = plan::names_for_incompatible(&dependency_plan, ports.title);
+        progress.retry = plan::retry_items(&dependency_plan, placement.root, &names);
+        plan::remember(
+            ports.env,
+            &request.instance,
+            placement.dir,
+            placement.root.id,
+            placement.root.title,
+            &dependency_plan,
+        );
+        return Err(failure);
+    }
+    progress.retry.clear();
+    plan::forget(ports.env, &request.instance);
+    Ok(plan::summary(&dependency_plan, &installed))
+}
diff --git a/crates/presenter/src/host/addon/pack.rs b/crates/presenter/src/host/addon/pack.rs
new file mode 100644
index 0000000..79c304b
--- /dev/null
+++ b/crates/presenter/src/host/addon/pack.rs
@@ -0,0 +1,340 @@
+//! 整合包**导入 / 导出**（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` 用真管线钉住这个等式。
+//!
+//! ## 取消是**管线级**的（M195 起）
+//!
+//! [`cancel_pack`] 置模块级标记 + `dispatch` 里的 `CancelInstall` 把代次 +1，而**同一个标记**
+//! 从 M195 起就是 core 的取消令牌（`ImportRequest::with_cancel`）：
+//!
+//! 1. 面板立刻收回（不是等后台回一句话）；
+//! 2. 这一轮之后回来的事件因代次不符被 `handle` 丢掉；
+//! 3. **后台那次导入真的停手**：core 在阶段边界与长循环内检查令牌，停下就回滚（暂存目录删掉、
+//!    落盘过的撤回、实例不登记），结果是 `ImportStatus::Cancelled` 而**不是**失败。响应延迟的
+//!    底线是「当前这一条文件读完/下完」，见 `core::addon::import::cancel` 的逐段表；
+//!
+//!    **收尾永远把真实结局送到界面**（M195 r3）：取消可能落在最后一个检查点之后 —— 那时管线
+//!    已经跑完（用户的同名文件被覆盖、实例已登记），也可能回滚没做完。这两种结果以前被
+//!    `cancel` 的早退 + 代次过滤一起丢掉，界面只剩一句无条件的"已停手并回滚"。现在
+//!    `import::finish` 无条件发 `PackEvent::Report`，`HostPackState::terminal_epochs` 给
+//!    "刚被取消的那一次"留一条**只放行 Report** 的一次性通道（[`take_terminal_epoch`]），
+//!    DTO 的 `ImportReportView::cancel` 三档把区别带到界面；
+//! 4. **提示语不能借用安装那条**（复审 r1 P1-2）：`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`，导入线程拿克隆，`cancel_pack` 置位。
+///
+/// 为什么不挪进 `CoreHost`：那要给 `host/mod.rs` 加字段（不在本 mission 的 scope）。这张表等价，
+/// 只是把「每 host 的字段」放在模块里；`host/mod.rs` 一旦进 scope，搬过去只是把这张表删掉。
+#[derive(Default)]
+struct HostPackState {
+    epoch: u64,
+    in_flight: usize,
+    /// 「刚被取消、还欠界面一份终态报告」的那几个代次（M195 r3）。
+    ///
+    /// `cancel_pack` 会把代次 +1，于是被取消那次运行交上来的 `PackEvent::Report` 会被 `handle`
+    /// 按代次丢掉——可那份报告才是**真实结局**（停手并回滚 / 回滚没做完 / 取消太晚其实已装完）。
+    /// 记在这里的代次允许**一条** `Report` 穿透代次过滤，取走即销；新一轮导入（`fresh_cancel`）
+    /// 清空整表，旧运行的报告不会污染新面板。
+    terminal_epochs: Vec,
+}
+
+static PACK_STATE: Mutex> = Mutex::new(Vec::new());
+static PACK_CANCEL: Mutex)>> = Mutex::new(Vec::new());
+
+/// 这张表的键（数据根；`HostEnv::at_root` 的每个测试根都不同）。
+fn host_key(env: &HostEnv) -> PathBuf {
+    env.layout.home().to_path_buf()
+}
+
+fn with_state(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 的取消**
+/// （M195 起 core 真的停手并回滚，见模块文档），所以不能复用下载页那条「安装已取消、实例未创建」。
+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);
+        }
+    }
+    let running = in_flight(env) > 0;
+    if running {
+        // 记下**马上要被作废的那个代次**：那次运行随后交上来的报告是它的真实结局，必须能穿透
+        // 代次过滤（否则"取消太晚、其实已经装完"在界面上永远不成立）。重复取消只记一次。
+        let stale = pack_epoch(env);
+        with_state(env, |state| {
+            if !state.terminal_epochs.contains(&stale) {
+                state.terminal_epochs.push(stale);
+            }
+        });
+    }
+    bump_pack_epoch(env);
+    running
+}
+
+/// 这个代次是不是「刚被取消、还欠一份终态报告」的那一次（**取走即销**：只放行一条）。
+///
+/// 只给 `PackEvent::Report` 用：取消之后的**进度**事件仍旧一律按代次丢掉（面板早就收回了，
+/// 再点亮它就是「点了取消没反应」的旧病）。
+pub(in crate::host) fn take_terminal_epoch(env: &HostEnv, epoch: u64) -> bool {
+    with_state(env, |state| {
+        match state.terminal_epochs.iter().position(|seen| *seen == epoch) {
+            Some(index) => {
+                state.terminal_epochs.remove(index);
+                true
+            }
+            None => false,
+        }
+    })
+}
+
+/// 这个 host 新一次导入的取消标记（挂进表里供 [`cancel_pack`] 用）。
+///
+/// 顺手清掉「还欠终态报告」的代次：新一次运行占住面板，上一次的结局不该再冒出来。
+fn fresh_cancel(env: &HostEnv) -> Arc {
+    with_state(env, |state| state.terminal_epochs.clear());
+    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::Scan(request) => {
+                // 预检只读：不点亮导入面板（那会让用户以为已经在装了），也不计"在跑导入"。
+                let cancel = fresh_cancel(&self.env);
+                import::spawn_scan(self.env.clone(), self.tx.clone(), *request, epoch, cancel);
+            }
+            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 {
+    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 {
+    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())
+        }
+    }
+}
+
+/// 缺省落盘路径：`/exports/-.`。
+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..f490945
--- /dev/null
+++ b/crates/presenter/src/host/addon/pack/convert.rs
@@ -0,0 +1,365 @@
+//! core 报告 → DTO（M113）：**逐字段照搬，不重算任何结论**。
+//!
+//! 这一层的唯一职责是翻译：三态、五阶段、四种处置、三种冲突成因、十一种导出原因，
+//! 全部一一对应。任何一个「顺手换算一下」都会让 UI 说的和管线干的不是一回事，
+//! 所以这里没有一处 re-derive（唯一例外是把 `&'static str` 的稳定码换成人读串）。
+//!
+//! 翻译用的是 core 的稳定 slug（`as_str()`）+ DTO 的 `from_slug()`，
+//! 于是「翻译表」本身就是一份可审计的清单：core 加了新变体，`from_slug` 返回 `None`
+//! 时这里会落到一个有名字的兜底，而不是悄悄画成别的意思。
+
+mod cancel;
+
+use std::path::{Path, PathBuf};
+
+use unlucky_core::addon::export::{ExportReport, FileClass, FileReason};
+use unlucky_core::addon::import::report::ImportStatus;
+use unlucky_core::addon::import::{
+    ConflictChoice, ConflictDecisions, ConflictFile, ConflictReason, FileAction, FileSource,
+    ImportError, ImportProgress, ImportReport, ImportScan, LoaderTarget, MissingReason,
+};
+
+use crate::dto::{
+    ConflictChoiceView, ConflictDecisionsView, ConflictFileView, ConflictReasonView,
+    ConflictSourceView, ExportClassView, ExportDoneView, ExportReasonView, FileActionView,
+    ImportConflictView, ImportErrorView, ImportFailureStageView, ImportProgressView,
+    ImportReportView, ImportScanView, ImportStageView, ImportStatusView, ImportedFileView,
+    MissingFileView, MissingReasonView, PackFormatView,
+};
+
+/// 一次导入**预检** → DTO（M160：冲突清单）。
+pub(super) fn scan_view(scan: &ImportScan) -> ImportScanView {
+    ImportScanView {
+        target: scan.target.clone(),
+        format: scan.format.as_deref().and_then(PackFormatView::from_slug),
+        pack_name: scan.pack_name.clone(),
+        pack_version: scan.pack_version.clone(),
+        game_version: scan.game_version.clone(),
+        conflicts: scan
+            .conflicts
+            .iter()
+            .map(|conflict| ImportConflictView {
+                path: conflict.path.clone(),
+                source: source_view(conflict.source),
+                reason: reason_of(conflict.reason),
+                disabled: conflict.disabled,
+                pack_sha1: conflict.pack_sha1.clone(),
+                pack_size: conflict.pack_size,
+                disk_sha1: conflict.disk_sha1.clone(),
+                disk_size: conflict.disk_size,
+                base_sha1: conflict.base_sha1.clone(),
+            })
+            .collect(),
+        unknown_remote: scan.unknown_remote,
+        lost_bytes: scan.lost_bytes(),
+        incoming_bytes: scan.incoming_bytes(),
+        notes: scan
+            .notes
+            .iter()
+            .map(|issue| issue.message.clone())
+            .collect(),
+        error: scan.error.as_ref().map(error_view),
+    }
+}
+
+/// DTO 的决策 → core 的决策表（**形状一换，语义不换**）。
+///
+/// 三条入口一一对应；没点名的路径在 core 侧落到"保留"（`ConflictDecisions` 的缺省档），
+/// 所以"页面少传一条"永远不会变成"覆盖"。
+pub(super) fn decisions_of(view: &ConflictDecisionsView) -> ConflictDecisions {
+    let mut decisions = match view.default_choice() {
+        ConflictChoiceView::KeepUser => ConflictDecisions::keep_all(),
+        ConflictChoiceView::Overwrite => ConflictDecisions::overwrite_all(),
+    };
+    for item in view.items() {
+        decisions.set(item.path.clone(), choice_of(item.choice));
+    }
+    decisions
+}
+
+const fn choice_of(choice: ConflictChoiceView) -> ConflictChoice {
+    match choice {
+        ConflictChoiceView::KeepUser => ConflictChoice::KeepUser,
+        ConflictChoiceView::Overwrite => ConflictChoice::Overwrite,
+    }
+}
+
+const fn source_view(source: FileSource) -> ConflictSourceView {
+    match source {
+        FileSource::Overrides => ConflictSourceView::Overrides,
+        FileSource::ClientOverrides => ConflictSourceView::ClientOverrides,
+        FileSource::CurseForge => ConflictSourceView::CurseForge,
+        FileSource::Modrinth => ConflictSourceView::Modrinth,
+    }
+}
+
+const fn reason_of(reason: ConflictReason) -> ConflictReasonView {
+    match reason {
+        ConflictReason::UserModified => ConflictReasonView::UserModified,
+        ConflictReason::UserDeleted => ConflictReasonView::UserDeleted,
+        ConflictReason::PreExisting => ConflictReasonView::PreExisting,
+    }
+}
+
+/// 一次导入结果 → DTO。
+///
+/// `cancel_requested` = 这次运行**被点过取消**（presenter 手里的那个开关）。它只用来区分
+/// "取消太晚"那一档：管线已经跑完时报告是 `Success`/`Partial`，但那不是一次正常导入——
+/// 用户的取消没赶上，实例会保留、同名文件可能已被覆盖（M195 r3）。
+pub(super) fn report_view(
+    report: &ImportReport,
+    target: &Path,
+    cancel_requested: bool,
+) -> ImportReportView {
+    ImportReportView {
+        status: ImportStatusView::from_slug(report.status.as_str())
+            .unwrap_or(ImportStatusView::Failed),
+        cancel: cancel::cancel_view(report, cancel_requested),
+        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,
+        failure_stage: failure_stage(report),
+    }
+}
+
+/// 致命失败发生在哪一步（M161）。
+///
+/// 判据只用 core 的两个机器位，**不看 warnings 的措辞**：
+/// - `rollback: Some(outcome)` ⇒ 真的跑过回滚（写过了），完整与否看 `is_complete()`；
+/// - `rollback: None` ⇒ 没跑过回滚。core 的约定是「失败发生在碰目标目录之前」（`abandoned`），
+///   此时 `rolled_back == true`；若 `rolled_back` 也是 `false`（既没回滚也没宣称干净），
+///   那就如实报「可能不一致」，不替它圆场。
+fn failure_stage(report: &ImportReport) -> Option {
+    if report.status != ImportStatus::Failed {
+        return None;
+    }
+    Some(match &report.rollback {
+        Some(outcome) if outcome.is_complete() => ImportFailureStageView::RolledBack,
+        Some(_) => ImportFailureStageView::RollbackIncomplete,
+        None if report.rolled_back => ImportFailureStageView::NotStarted,
+        None => ImportFailureStageView::RollbackIncomplete,
+    })
+}
+
+/// 一次导出结果 → 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: reason_of(file.reason),
+        choice: choice_view(file.choice),
+        pack_sha1: file.pack_sha1.clone(),
+        base_sha1: file.base_sha1.clone(),
+        disk_sha1: file.disk_sha1.clone(),
+        pack_size: file.pack_size,
+    }
+}
+
+/// 一条 `ConflictChoice` → DTO（预检与事后账共用一张翻译表）。
+const fn choice_view(choice: ConflictChoice) -> ConflictChoiceView {
+    match choice {
+        ConflictChoice::KeepUser => ConflictChoiceView::KeepUser,
+        ConflictChoice::Overwrite => ConflictChoiceView::Overwrite,
+    }
+}
+
+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 {
+    failed_report_with(
+        target,
+        pack,
+        ImportErrorView {
+            code: code.to_string(),
+            label: label.to_string(),
+            message: message.to_string(),
+            hint: None,
+        },
+    )
+}
+
+/// 一条 core 的 [`ImportError`] → 失败报告（**逐字段照搬**，含 `hint`）。
+///
+/// 预检失败（`scan.error`）走它：那些错本来就是 core 判出来的（`pack_traversal` /
+/// `pack_limits` / `pack_metadata` …），没必要在宿主层再解释一遍，更不能把 `hint`
+/// （"先装好游戏再导出"这种可执行下一步）丢掉——丢掉的话用户看到的就是"失败了，然后呢"。
+pub(super) fn failed_report_of(
+    target: PathBuf,
+    pack: &Path,
+    error: &ImportError,
+) -> ImportReportView {
+    failed_report_with(target, pack, error_view(error))
+}
+
+/// 组装：形状只此一处，文案由调用方给。
+fn failed_report_with(target: PathBuf, pack: &Path, error: ImportErrorView) -> 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(error),
+        registered: None,
+        bytes_written: 0,
+        rolled_back: true,
+        // 预检/装配阶段就失败了：目标目录一个字节都没写（不是「写完又回滚」）。
+        failure_stage: Some(ImportFailureStageView::NotStarted),
+        // 这一路根本没进管线，谈不上取消。
+        cancel: crate::dto::ImportCancelView::NotRequested,
+    }
+}
+
+/// 包文件名（`Better MC.mrpack` → `Better MC`）。
+///
+/// **M216 ②**：函数体一行委托 core（`game::install::pack_dir`）——CLI 调的是同一个函数，
+/// 于是「CLI 缺省落点」与「GUI 落点」不只目录相同，连目录名归一化也只有一份实现。
+pub(super) fn pack_stem(pack: &Path) -> String {
+    unlucky_core::game::install::pack_dir::pack_stem(pack)
+}
+
+/// **实例目录名**（判据见 core 的 [`pack_dir::instance_dir_name`]）：本函数只有一行委托。
+///
+/// **只剩 presenter 自己的用例在调它**（生产侧落点已改成 `pack_dir::instance_dir`，见 M216
+/// P3-2），所以挂 `cfg(test)`：它是那组既有判据（空格折 `-`、中文补 `-`、两个中文名
+/// 不塌成同一个目录）继续钉住归一化规则的入口，生产构建里不需要它。
+///
+/// [`pack_dir::instance_dir_name`]: unlucky_core::game::install::pack_dir::instance_dir_name
+#[cfg(test)]
+pub(super) fn dir_name(name: &str) -> String {
+    unlucky_core::game::install::pack_dir::instance_dir_name(name)
+}
+
+/// 目录/文件名用的 slug（导出用的文件名也走它；实现同样收在 core `pack_dir`）。
+pub(super) fn slug(text: &str) -> String {
+    unlucky_core::game::install::pack_dir::slug(text)
+}
+
+#[cfg(test)]
+#[path = "convert/stage_tests.rs"]
+mod stage_tests;
diff --git a/crates/presenter/src/host/addon/pack/convert/cancel.rs b/crates/presenter/src/host/addon/pack/convert/cancel.rs
new file mode 100644
index 0000000..55bddc2
--- /dev/null
+++ b/crates/presenter/src/host/addon/pack/convert/cancel.rs
@@ -0,0 +1,122 @@
+//! 「取消的**真实结局**」→ DTO 三档（M195 r3）。
+//!
+//! 从父模块拆出来只为行数（父文件已到 400 硬限附近），判据与文案口径原样。
+
+use unlucky_core::addon::import::report::ImportStatus;
+use unlucky_core::addon::import::ImportReport;
+
+use crate::dto::ImportCancelView;
+
+/// core 的「取消真实结局」→ DTO 的三档（M195 r3：**不许**把三档混成一句）。
+///
+/// - core 说 `Cancelled` ⇒ 管线真的停手了；回滚完整与否看 `rolled_back`（两档分开说）；
+/// - core 说 `Success`/`Partial` 而这次被点过取消 ⇒ **取消太晚**：报告是真结局，但它不是
+///   "停下来了"，界面必须照实说「实例会保留、文件可能已被覆盖」；
+/// - core 说 `Failed` ⇒ **一律 `NotRequested`**（复审 r3 P2-1）：失败卡自己已经把真相说全了
+///   （`failure_stage` 分「没写过 / 回滚干净 / 回滚没做完」），再贴一句「取消太晚、已经跑完、
+///   文件可能被覆盖」就是与红卡**直接对立**的第二句假话——失败的导入没有"跑完"这一说。
+pub(super) fn cancel_view(report: &ImportReport, cancel_requested: bool) -> ImportCancelView {
+    match report.status {
+        ImportStatus::Cancelled => {
+            if report.rolled_back {
+                ImportCancelView::RolledBack
+            } else {
+                ImportCancelView::RollbackIncomplete
+            }
+        }
+        ImportStatus::Success | ImportStatus::Partial if cancel_requested => {
+            ImportCancelView::TooLate
+        }
+        ImportStatus::Success | ImportStatus::Partial | ImportStatus::Failed => {
+            ImportCancelView::NotRequested
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    //! 三档的**推导**（不是"给定这一档、文案怎么画"）：什么输入会推出哪一档。
+    //!
+    //! 这一族用例是复审 r3 P2-1/P2-2 的直接产物：此前只有下半段（文案）有用例，把推导删掉
+    //! 也全绿。
+
+    use unlucky_core::addon::import::report::ImportStatus;
+    use unlucky_core::addon::import::ImportReport;
+
+    use crate::dto::ImportCancelView;
+
+    use super::super::report_view;
+
+    fn core_report(status: ImportStatus, rolled_back: bool) -> ImportReport {
+        let mut report = ImportReport::empty(std::path::PathBuf::from("instance"));
+        report.status = status;
+        report.rolled_back = rolled_back;
+        report
+    }
+
+    fn cancel_of(
+        status: ImportStatus,
+        rolled_back: bool,
+        cancel_requested: bool,
+    ) -> ImportCancelView {
+        report_view(
+            &core_report(status, rolled_back),
+            std::path::Path::new("instance"),
+            cancel_requested,
+        )
+        .cancel
+    }
+
+    #[test]
+    fn an_incomplete_rollback_is_its_own_bucket() {
+        // 推导：`Cancelled` + `rolled_back == false` ⇒ **回滚没做完**（不是"已回滚"）。
+        // 把这条推导删掉（一律按已回滚）这里就红——那正是复审 r3 P2-2 说的零覆盖。
+        assert_eq!(
+            cancel_of(ImportStatus::Cancelled, false, true),
+            ImportCancelView::RollbackIncomplete
+        );
+        // 对照：回滚完整才是「已回滚」——两档不许并成一个。
+        assert_eq!(
+            cancel_of(ImportStatus::Cancelled, true, true),
+            ImportCancelView::RolledBack
+        );
+    }
+
+    #[test]
+    fn a_failed_run_is_never_dressed_up_as_a_late_cancel() {
+        // P2-1：失败 + 点过取消（例如"点取消的同时摘要不符"）⇒ 失败卡自己说全了真相，
+        // 不许再贴「取消太晚、已经跑完、文件可能被覆盖」——那两句直接对立。
+        assert_eq!(
+            cancel_of(ImportStatus::Failed, false, true),
+            ImportCancelView::NotRequested,
+            "失败的导入没有「跑完」这一说"
+        );
+        assert_eq!(
+            cancel_of(ImportStatus::Failed, true, true),
+            ImportCancelView::NotRequested
+        );
+        // 对照：成功/部分成功 + 点过取消，才是「太晚」。
+        for status in [ImportStatus::Success, ImportStatus::Partial] {
+            assert_eq!(
+                cancel_of(status, false, true),
+                ImportCancelView::TooLate,
+                "{status:?} + 取消 ⇒ 太晚"
+            );
+        }
+    }
+
+    #[test]
+    fn an_untouched_run_carries_no_cancel_verdict() {
+        for status in [
+            ImportStatus::Success,
+            ImportStatus::Partial,
+            ImportStatus::Failed,
+        ] {
+            assert_eq!(
+                cancel_of(status, false, false),
+                ImportCancelView::NotRequested,
+                "没点过取消就不该有取消结论"
+            );
+        }
+    }
+}
diff --git a/crates/presenter/src/host/addon/pack/convert/stage_tests.rs b/crates/presenter/src/host/addon/pack/convert/stage_tests.rs
new file mode 100644
index 0000000..eae6751
--- /dev/null
+++ b/crates/presenter/src/host/addon/pack/convert/stage_tests.rs
@@ -0,0 +1,108 @@
+//! M161 复审 P2-1：`failure_stage` 是⑥三档的**唯一**判定点，此前零覆盖（把它改成恒
+//! `RolledBack`，presenter 254 条全绿）。这里直接喂 core 的机器位，断言的是**判定**，
+//! 不是渲染（渲染在 app-iced 的 `packui/model/tests/stage.rs`）。
+//!
+//! 抓得住：`None if report.rolled_back` 被写反（预检失败 → 「已回滚」，正是⑥要消灭的谎）；
+//! `is_complete()` 被丢掉（回滚没做完也说成零残留）；`status != Failed` 也发阶段。
+
+use std::path::PathBuf;
+
+use unlucky_core::addon::import::{ImportError, ImportReport, ImportStatus, RollbackOutcome};
+
+use super::*;
+
+/// 一份「失败」的空报告（还没决定回滚结果）。
+fn failed() -> ImportReport {
+    let mut report = ImportReport::empty(PathBuf::from("C:/tmp/.minecraft"));
+    report.fail(ImportError::integrity("sha1 mismatch"));
+    report
+}
+
+/// 预检就失败（**从未写过目标目录**）⇒ `NotStarted`。
+///
+/// core 的 `abandoned()` 就是这一形：`rollback == None` + `rolled_back == true`。
+#[test]
+fn preflight_failure_is_not_started() {
+    let mut report = failed();
+    report.rolled_back = true;
+    assert_eq!(
+        failure_stage(&report),
+        Some(ImportFailureStageView::NotStarted),
+        "没写过目标目录就是「根本没开始」，不许说成「已回滚」"
+    );
+    assert_eq!(failure_stage(&report).unwrap().slug(), "not_started");
+    // 渲染层同一份判据（`failed_report_with` 走的是同一条）。
+    assert_eq!(
+        failed_report_with(
+            PathBuf::from("C:/tmp"),
+            std::path::Path::new("Better MC.mrpack"),
+            ImportErrorView {
+                code: "pack_traversal".to_string(),
+                label: "Path traversal".to_string(),
+                message: "../etc/passwd".to_string(),
+                hint: None,
+            },
+        )
+        .failure_stage,
+        Some(ImportFailureStageView::NotStarted),
+        "宿主侧失败（目标实例不可用）也是「没开始写」，不是「已回滚」"
+    );
+}
+
+/// 跑过回滚且完整 ⇒ `RolledBack`。
+#[test]
+fn a_complete_rollback_is_rolled_back() {
+    let mut report = failed();
+    report.rolled_back = true;
+    report.rollback = Some(RollbackOutcome {
+        attempted: 3,
+        failed: Vec::new(),
+    });
+    assert_eq!(
+        failure_stage(&report),
+        Some(ImportFailureStageView::RolledBack)
+    );
+    assert_eq!(failure_stage(&report).unwrap().slug(), "rolled_back");
+}
+
+/// 跑过回滚但有失败项 ⇒ `RollbackIncomplete`（目标目录可能与导入前不同）。
+#[test]
+fn a_partial_rollback_is_incomplete() {
+    let mut report = failed();
+    report.rolled_back = false;
+    report.rollback = Some(RollbackOutcome {
+        attempted: 3,
+        failed: vec!["mods/a.jar: 占用中".to_string()],
+    });
+    assert_eq!(
+        failure_stage(&report),
+        Some(ImportFailureStageView::RollbackIncomplete)
+    );
+    assert_eq!(
+        failure_stage(&report).unwrap().slug(),
+        "rollback_incomplete"
+    );
+}
+
+/// 既没回滚也没宣称干净（core 的 `failed()` 单独一支）⇒ 只能如实说「可能不一致」。
+#[test]
+fn a_failure_without_any_claim_is_incomplete_not_not_started() {
+    let mut report = failed();
+    report.rolled_back = false;
+    report.rollback = None;
+    assert_eq!(
+        failure_stage(&report),
+        Some(ImportFailureStageView::RollbackIncomplete),
+        "没跑回滚也不宣称干净：不许说「没开始写」"
+    );
+}
+
+/// 不是致命失败 ⇒ 没有「失败阶段」可言（成功/部分成功都不该发这一段）。
+#[test]
+fn a_non_fatal_report_has_no_stage() {
+    let mut report = ImportReport::empty(PathBuf::from("C:/tmp"));
+    report.rolled_back = false;
+    assert_eq!(failure_stage(&report), None, "Success 不该有失败阶段");
+    report.status = ImportStatus::Partial;
+    assert_eq!(failure_stage(&report), None, "Partial 不该有失败阶段");
+}
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 {
+    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 = 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 = DEFAULT_CONTENT_ROOTS
+        .iter()
+        .map(|entry| (*entry).to_string())
+        .collect();
+    let (files, skipped) = scan_instance(root, &roots);
+
+    let mut rows: Vec = 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..ed87683
--- /dev/null
+++ b/crates/presenter/src/host/addon/pack/import.rs
@@ -0,0 +1,309 @@
+//! 后台导入（M113/M160）：探测 → **预检（冲突清单）** → 目标目录 → core 的 `import_pack` → 报告。
+//!
+//! 四条纪律：
+//!
+//! 1. **探测失败不空跑管线**：先做具名诊断（[`super::diagnose`]），失败就只回 `Probe` 事件；
+//! 2. **先预检再导入**（M160）：预检只读，把"会盖掉用户哪几个文件"算清楚。没有冲突就直接
+//!    往下导（不打扰用户）；有冲突就回 [`PackEvent::Scan`] 让页面画清单，等用户点完再导；
+//! 3. **缺省档永远 `KeepAll`**：决策从 DTO 逐字段搬（[`convert::decisions_of`]），页面没点过的
+//!    路径在 core 侧落到"保留"；
+//! 4. **取消是真取消**（M195）：`cancel` 标记既挡界面事件、又**交给 core 当取消令牌**——管线
+//!    在检查点停手并回滚（逐段检查点见 `core::addon::import::cancel`）。取消之后的**进度**不再
+//!    打扰界面（回调与代次都挡），但**终态报告一定发出**：取消可能太晚（管线已跑完）或回滚
+//!    没做完，那两种结局必须让用户看见（见 [`finish`]）。
+
+use std::path::PathBuf;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+
+use unlucky_core::addon::import::report::ImportIssue;
+use unlucky_core::addon::import::{
+    import_pack, scan_pack_online, DownloadEngineFetcher, ImportCancel, ImportProgress,
+    ImportProgressSink, ImportRequest,
+};
+use unlucky_core::download::blocking::block_on;
+use unlucky_core::game::install::pack_dir;
+
+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,
+    inflight: super::InFlight,
+) {
+    spawn("pack-import", move || {
+        // 句柄跟着这次运行走到**出口**：正常收尾、两条早退、panic 展开都会 drop ⇒ 计数减一。
+        // 以前是手工 `finished()` 放在 `block_on()` 之后，两条早退路径直接漏掉（复审 r2 P2-1）。
+        let _inflight = inflight;
+        run(&env, &tx, &request, epoch, cancel);
+    });
+}
+
+/// 起一个后台**预检**线程（M160：只读，不写盘）。
+pub(super) fn spawn_scan(
+    env: HostEnv,
+    tx: JobSender,
+    request: ImportRequestView,
+    epoch: u64,
+    cancel: Arc,
+) {
+    spawn("pack-scan", move || {
+        // 探测先过一遍：失败就只给具名诊断，不空跑一遍预检。
+        if let Some(probe) = super::diagnose::of(&request.pack) {
+            send(&tx, epoch, PackEvent::Probe(Box::new(probe)));
+            return;
+        }
+        let target = 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;
+            }
+        };
+        // 预检本身只读（不写盘），但 M162 起会**先补全再判**：缺 `hashes.sha1` 的 mrpack 条目
+        // 按 sha512 反查 Modrinth。补不出仍按 M160 的口径计数，所以冷启动没网也不影响判定。
+        let engine = super::super::super::engine::engine(&env);
+        let fetcher = DownloadEngineFetcher::new(&engine);
+        let core_request = ImportRequest::new(&request.pack, &target).with_fetcher(&fetcher);
+        let scan = block_on(scan_pack_online(&core_request));
+        if cancel.load(Ordering::SeqCst) {
+            return;
+        }
+        // 先发预检结果（`error` 也照原样带出去：调用方按"有没有冲突"分流要用它）。
+        send(
+            &tx,
+            epoch,
+            PackEvent::Scan(Box::new(convert::scan_view(&scan))),
+        );
+        // **预检自己没算出来 ⇒ 必须再发一条结果事件**（复审 r1 P2-1）。
+        //
+        // 只发 `Scan(error)` 的话，页面那边 `pick` 为空（它只由 `conflicts` 生成）、进度与报告
+        // 又被 `Scan` 清空 ⇒ 落回入口态，用户点完「导入」屏幕上一个字都不变（静默空转）。
+        // 走 `Report` 就回到 M160 之前那条既有形状：结果块的「致命 —— 已回滚」把原因画出来，
+        // UI 一行不用改；`code`/`label`/`message`/`hint` 全部从 `scan.error` 搬。
+        if let Some(error) = &scan.error {
+            send(
+                &tx,
+                epoch,
+                PackEvent::Report(Box::new(convert::failed_report_of(
+                    target,
+                    &request.pack,
+                    error,
+                ))),
+            );
+        }
+    });
+}
+
+pub(super) fn run(
+    env: &HostEnv,
+    tx: &JobSender,
+    request: &ImportRequestView,
+    epoch: u64,
+    cancel: Arc,
+) {
+    // 探测先过一遍：失败就只给具名诊断（「看起来像 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;
+        }
+    };
+    if register {
+        if let Err(reason) = prepare_target(&target) {
+            send(
+                tx,
+                epoch,
+                PackEvent::Report(Box::new(convert::failed_report(
+                    target,
+                    &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);
+    // 这个开关从 M195 起是**真令牌**：core 的每个检查点都看它（不只是挡界面事件）。
+    let token = ImportCancel::from_flag(Arc::clone(&cancel));
+    let mut core_request = ImportRequest::new(&request.pack, &target)
+        .with_fetcher(&fetcher)
+        .with_cancel(&token)
+        .with_progress(sink)
+        // 决策逐字段搬过来：`KeepAll`（缺省）/ `OverwriteAll` / 逐项，语义在 core 那一侧落地。
+        .with_decisions(convert::decisions_of(&request.decisions));
+    if register {
+        core_request = core_request.with_registration(&env.layout, Some(&pack_name));
+    }
+
+    let mut report = block_on(import_pack(&core_request));
+    // **§5**：导入建出来的实例要绑到它的内容目录（`isolation=custom` + `gameDir`），否则运行
+    // 目录由全局档派生成 `/versions/`，这批 mods/config 永远不会被启动用到。
+    // 判据与文案在 core（与 CLI 同一份）；失败不把整次导入判失败，但要让用户看见。
+    match pack_dir::bind_created_instance(&env.layout, &target, register, &report) {
+        Some(Ok(note)) => report
+            .warnings
+            .push(ImportIssue::new("instance_bound", note)),
+        Some(Err(note)) => report
+            .warnings
+            .push(ImportIssue::new("instance_binding_failed", note)),
+        None => {}
+    }
+    // 取消标记要**在管线返回之后**再读一次：取消可能来得太晚（管线已经跑完），这一读就是
+    // "太晚"的唯一证据（`finish` 用它把报告标成 `TooLate`）。
+    let cancel_requested = cancel.load(Ordering::SeqCst);
+    finish(tx, &target, register, epoch, cancel_requested, &report);
+}
+
+/// 收尾：清掉我们自建的空目录 + 把 core 的报告变成事件。
+///
+/// # 取消也照发（M195 r3）
+///
+/// 以前这里 `cancel.load()` 是对**所有**事件的早退，于是"取消太晚、后台其实已经装完并登记"
+/// 这件事永远到不了界面，界面只能照着旧文案说「已停手并回滚」。现在报告无条件发出：它就是
+/// 真实结局——core 说 `Cancelled`（停手并回滚 / 回滚没做完），或者说 `Success`/`Partial`
+/// （取消没赶上），由 DTO 的 `cancel` 三档把区别带到界面。
+///
+/// 代次仍用**出发时**那个（`epoch`）：`handle` 给"刚被取消的那一次"留了一次性终态通道
+/// （[`super::super::addon::pack::take_terminal_epoch`]），进度事件照旧按代次丢。
+pub(super) fn finish(
+    tx: &JobSender,
+    target: &std::path::Path,
+    register: bool,
+    epoch: u64,
+    cancel_requested: bool,
+    report: &unlucky_core::addon::import::ImportReport,
+) {
+    if register
+        && matches!(
+            report.status,
+            ImportStatus::Failed | ImportStatus::Cancelled
+        )
+    {
+        // 失败 / 取消都已回滚，但**目录是我们建的**（`prepare_target`）、core 只清文件不清
+        // 目录 ⇒ 不清掉的话下一次重试会撞「directory already exists」（复审 r1 P2-9）。
+        remove_if_empty(target);
+    }
+    send(
+        tx,
+        epoch,
+        PackEvent::Report(Box::new(convert::report_view(
+            report,
+            target,
+            cancel_requested,
+        ))),
+    );
+}
+
+/// 目录里没有东西就删掉（失败回滚后的收尾；非空一律不动）。
+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);
+    }
+}
+
+/// 导入目标：`(目录, 是否登记新实例)` —— **只算路径，不建目录**（预检要能只读地用它）。
+///
+/// - 选了实例 ⇒ 它的运行目录，**不登记**（已经是一条实例记录）；
+/// - 没选实例 ⇒ `/instances/` 新目录 + 登记（实例名 = 用户给的名字或包名）。
+///   注意 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));
+            // **M216 P3-2**：落点也委托 core（`pack_dir::instance_dir`）——此前这里自己拼
+            // `/instances/`，core 改了目录语义时 GUI 不会跟着走。
+            let target = pack_dir::instance_dir(&env.layout, &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()
+                    ));
+                }
+            }
+            Ok((target, true))
+        }
+    }
+}
+
+/// 真要写盘之前建目录（**预检不调它**：预检是只读的，不建任何东西）。
+pub(super) fn prepare_target(target: &std::path::Path) -> Result<(), String> {
+    std::fs::create_dir_all(target).map_err(|error| format!("create dir failed: {error}"))
+}
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..eaf6d5d
--- /dev/null
+++ b/crates/presenter/src/host/addon/pack/tests.rs
@@ -0,0 +1,397 @@
+//! 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`] | 早退路径放回「在跑」计数，取消安装仍是安装的取消 |
+//! | [`cancel::a_pre_cancelled_flag_really_stops_the_core_pipeline`] | 取消标记**真的**交给 core（盘上零残留、档案零实例） |
+//!
+//! 夹具（临时目录、写文件、泵 host）在 [`harness`]。
+
+mod cancel;
+mod harness;
+mod scan;
+
+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::{ConflictDecisionsView, 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 = 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()),
+        decisions: ConflictDecisionsView::default(),
+    };
+    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()),
+        decisions: ConflictDecisionsView::default(),
+    };
+
+    // 第一次：`target_of` 只算路径（预检要能只读地用它），真要写盘前才 `prepare_target`。
+    let (first, register) = super::import::target_of(&env, &request).expect("首次应当算得出目录");
+    assert!(register);
+    assert!(
+        !first.exists(),
+        "`target_of` 不许建目录（M160：预检是只读的）"
+    );
+    super::import::prepare_target(&first).expect("写盘前建目录");
+    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()),
+            decisions: ConflictDecisionsView::default(),
+        },
+    )))));
+    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/cancel.rs b/crates/presenter/src/host/addon/pack/tests/cancel.rs
new file mode 100644
index 0000000..92e44f1
--- /dev/null
+++ b/crates/presenter/src/host/addon/pack/tests/cancel.rs
@@ -0,0 +1,215 @@
+//! presenter 的**真令牌**接线（M195 复审 P2-2）：取消标记必须真的交给 core。
+//!
+//! # 为什么判据只能是盘上的事实
+//!
+//! 只断言"没收到 `PackEvent::Report`"是**两条路都成立**的伪证明：`import::run` 的早退条件是
+//! `report.status == Cancelled || cancel.load()`，后者会把"根本没接线"完全遮住——core 照旧跑完
+//! 并登记实例，界面只看到面板收回。那正是本 mission 要消灭的形态，所以本用例盯的是**目标目录
+//! 与 `profiles.json`**：标记一进来就是 true ⇒ 目录里一个文件都不该有、实例一个都不该登记。
+
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+
+use crate::dto::{ConflictDecisionsView, ImportRequestView};
+
+use super::harness::{temp_dir, write};
+
+/// 一个能走完管线的最小 MultiMC 包（目录形态：不需要 zip 写入器）。
+fn multimc_pack(dir: &std::path::Path) -> std::path::PathBuf {
+    let source = dir.join("Better MC");
+    write(
+        &source.join("mmc-pack.json"),
+        br#"{"formatVersion": 1, "components": [
+            {"uid": "net.minecraft", "version": "1.20.1"}]}"#,
+    );
+    write(&source.join(".minecraft/mods/sodium.jar"), &[0x11; 1024]);
+    write(&source.join(".minecraft/config/options.txt"), b"fov=90\n");
+    source
+}
+
+#[test]
+fn a_pre_cancelled_flag_really_stops_the_core_pipeline() {
+    let dir = temp_dir("cancel-wired");
+    let source = multimc_pack(&dir);
+    let data = dir.join("data");
+    std::fs::create_dir_all(&data).expect("data root");
+    let env = crate::host::HostEnv::at_root(&data);
+    let request = ImportRequestView {
+        pack: source,
+        instance: None,
+        instance_name: Some("Cancelled Pack".to_string()),
+        decisions: ConflictDecisionsView::default(),
+    };
+    // 目标目录与"是否登记"都按 host 的真口径算（判据不能自己另算一份）。
+    let (target, register) = super::super::import::target_of(&env, &request).expect("目标目录");
+    assert!(register, "走新实例这条路才覆盖「登记」这一环");
+
+    let (tx, _rx) = crate::host::job::channel();
+    let cancel = Arc::new(AtomicBool::new(true));
+    super::super::import::run(&env, &tx, &request, 11, Arc::clone(&cancel));
+    drop(tx);
+    assert!(cancel.load(Ordering::SeqCst), "用例前提：标记一直是 true");
+
+    assert!(
+        !target.exists(),
+        "取消后目标目录不该存在（core 在入口检查点就停手，暂存目录也删了）：{}",
+        target.display()
+    );
+    let profiles =
+        unlucky_core::game::install::instance::read_profiles(&env.layout).expect("读档案");
+    assert!(
+        profiles.profiles.is_empty(),
+        "取消后不许登记实例：{:?}",
+        profiles.profiles
+    );
+
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+/// **路径 A：取消来得太晚**（M195 r3 的核心用例）。
+///
+/// 三段拼起来，全部确定性、没有 sleep：
+/// 1. **core 真管线**跑一次合并态导入，把取消置在**最后一条** `ImportStage::Commit` 进度上——
+///    之后没有任何检查点，于是管线一路跑完（用户的 `mods/a.jar` 被覆盖），报告是
+///    `Success` + `rolled_back == false`（core 一直是诚实的）；
+/// 2. `cancel_pack` 把代次 +1（这就是"取消"），并记下被作废的那个代次；
+/// 3. `finish` 照发 `PackEvent::Report`，`handle` 让它**穿透代次**——界面因此拿到「已完成 /
+///    未回滚 / 取消太晚」，而不是旧行为里那句无条件的「已停手并回滚」。
+///
+/// 变异：把终态通道去掉（`handle` 恢复"代次不符一律丢"）⇒ 本用例立刻红（报告到不了界面）。
+#[test]
+fn a_late_cancel_still_delivers_the_real_outcome_to_the_ui() {
+    use std::sync::atomic::AtomicUsize;
+
+    use unlucky_core::addon::import::{
+        import_pack, ConflictPolicy, ImportCancel, ImportProgress, ImportProgressSink,
+        ImportRequest, ImportStage, ImportStatus,
+    };
+    use unlucky_core::download::blocking::block_on;
+
+    use crate::dto::{AppEvent, Backend, CoreEvent, PackEvent};
+
+    let dir = temp_dir("cancel-late");
+    // 包里有 `mods/a.jar`，目标目录里也有（内容不同）⇒ 合并态"被覆盖"是真的会发生。
+    let source = dir.join("Path A Pack");
+    write(
+        &source.join("mmc-pack.json"),
+        br#"{"formatVersion": 1, "components": [
+            {"uid": "net.minecraft", "version": "1.20.1"}]}"#,
+    );
+    write(&source.join(".minecraft/mods/a.jar"), b"pack a");
+    let target = dir.join("instance");
+    write(&target.join("mods/a.jar"), b"user a");
+
+    let data = dir.join("data");
+    std::fs::create_dir_all(&data).expect("data root");
+    let env = crate::host::HostEnv::at_root(&data);
+
+    // ① core：取消置在最后一条逐文件进度上 ⇒ 之后没有检查点 ⇒ 管线跑完。
+    let token = ImportCancel::new();
+    let sink_token = token.clone();
+    let seen = Arc::new(AtomicUsize::new(0));
+    let seen_by_sink = Arc::clone(&seen);
+    let sink: ImportProgressSink = Arc::new(move |progress: &ImportProgress| {
+        if progress.stage != ImportStage::Commit || progress.total == 0 {
+            return;
+        }
+        seen_by_sink.fetch_add(1, Ordering::SeqCst);
+        if progress.done + 1 == progress.total {
+            sink_token.cancel();
+        }
+    });
+    let report = block_on(import_pack(
+        &ImportRequest::new(&source, &target)
+            .with_cancel(&token)
+            // 覆盖档：让用户的 `mods/a.jar` 真的被覆盖（缺省是"保留用户那一侧"）。
+            .with_conflict_policy(ConflictPolicy::Overwrite)
+            .with_progress(sink),
+    ));
+    assert!(token.is_cancelled(), "用例前提：取消确实置位了");
+    assert!(
+        seen.load(Ordering::SeqCst) > 1,
+        "确实逐文件走到了底（合并态）"
+    );
+    assert_eq!(
+        report.status,
+        ImportStatus::Success,
+        "取消置在最后一条之后 ⇒ 管线已经跑完：{:?}",
+        report.error
+    );
+    assert!(
+        !report.rolled_back,
+        "没有回滚就别说回滚过（core 的机器位是诚实的）"
+    );
+    assert_eq!(
+        std::fs::read(target.join("mods/a.jar")).expect("读被覆盖的文件"),
+        b"pack a",
+        "路径 A 的前提：用户的同名文件**已经被覆盖**"
+    );
+
+    // ② 用户点取消：代次 +1，被作废的那个代次进了终态通道。
+    let epoch = super::super::pack_epoch(&env);
+    let _in_flight = super::super::InFlight::begin(&env);
+    assert!(
+        super::super::cancel_pack(&env),
+        "取消应当看到一条在跑的导入"
+    );
+    assert_ne!(
+        super::super::pack_epoch(&env),
+        epoch,
+        "取消会作废本次代次（这正是旧实现丢报告的成因）"
+    );
+
+    // ③ 收尾照发报告；同代次上的**进度**事件仍按代次丢掉。
+    let mut host = crate::host::CoreHost::headless(env.clone());
+    let (tx, rx) = crate::host::job::channel();
+    super::super::import::finish(&tx, &target, false, epoch, true, &report);
+    tx.send(crate::host::job::HostTask::Pack {
+        event: Box::new(PackEvent::Progress(None)),
+        epoch,
+    })
+    .expect("送一条同代次的进度事件");
+    drop(tx);
+    for task in rx.iter() {
+        host.handle(task);
+    }
+    let events = host.drain_events();
+
+    let delivered: Vec<&crate::dto::ImportReportView> = events
+        .iter()
+        .filter_map(|event| match event {
+            AppEvent::Core(CoreEvent::Pack(inner)) => match inner.as_ref() {
+                PackEvent::Report(view) => Some(view.as_ref()),
+                _ => None,
+            },
+            _ => None,
+        })
+        .collect();
+    let view = delivered
+        .first()
+        .expect("取消太晚时，真实结果必须到达界面（丢掉就是路径 A 的假话）");
+    assert_eq!(
+        view.status,
+        crate::dto::ImportStatusView::Success,
+        "界面拿到的结局是「已完成」"
+    );
+    assert!(
+        !view.rolled_back,
+        "界面拿到的结局是「未回滚」，不是「已回滚」"
+    );
+    assert_eq!(
+        view.cancel,
+        crate::dto::ImportCancelView::TooLate,
+        "必须标成「取消太晚」，不能标成「已回滚」"
+    );
+    assert!(
+        !events.iter().any(|event| match event {
+            AppEvent::Core(CoreEvent::Pack(inner)) =>
+                matches!(inner.as_ref(), PackEvent::Progress(_)),
+            _ => false,
+        }),
+        "终态通道只放行报告：取消后的进度事件仍按代次丢掉"
+    );
+
+    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 {
+    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 {
+    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 {
+    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/pack/tests/scan.rs b/crates/presenter/src/host/addon/pack/tests/scan.rs
new file mode 100644
index 0000000..681f6fb
--- /dev/null
+++ b/crates/presenter/src/host/addon/pack/tests/scan.rs
@@ -0,0 +1,303 @@
+//! 预检与决策通道（M160）：DTO ↔ core 的翻译、以及"缺省不覆盖"在 presenter 这一侧的表现。
+//!
+//! 这里**不重算**任何判定（判定在 core）：只钉两件事——
+//!
+//! 1. 三条入口（全部保留 / 全部覆盖 / 逐项）翻成 core 的 `ConflictDecisions` 之后语义不变，
+//!    尤其"没点名的路径 = 保留"；
+//! 2. 预检清单逐字段搬进 DTO（来源、成因、两侧体积与哈希、计数摘要）。
+
+use std::path::PathBuf;
+
+use super::harness::{temp_dir, write};
+use crate::dto::{
+    ConflictChoiceView, ConflictDecisionView, ConflictDecisionsView, ConflictReasonView,
+    ConflictSourceView,
+};
+use unlucky_core::addon::import::{
+    ConflictChoice, ConflictReason, FileSource, ImportConflict, ImportScan,
+};
+
+/// 造一份 core 侧的预检结果（只填这条用例要看的字段）。
+fn scan_fixture() -> ImportScan {
+    ImportScan {
+        target: PathBuf::from("instances/survival/.minecraft"),
+        format: Some("modrinth".to_string()),
+        pack_name: Some("Better MC".to_string()),
+        pack_version: Some("1.2.0".to_string()),
+        game_version: Some("1.20.1".to_string()),
+        loader: None,
+        conflicts: vec![ImportConflict {
+            path: "config/sodium-options.json".to_string(),
+            source: FileSource::ClientOverrides,
+            reason: ConflictReason::UserModified,
+            disabled: false,
+            pack_sha1: "aa".repeat(20),
+            pack_size: 4_200,
+            disk_sha1: "bb".repeat(20),
+            disk_size: 5_100,
+            base_sha1: Some("cc".repeat(20)),
+        }],
+        unknown_remote: 2,
+        notes: Vec::new(),
+        error: None,
+    }
+}
+
+#[test]
+fn scan_view_carries_every_field_and_the_counts() {
+    let scan = scan_fixture();
+    let view = super::super::convert::scan_view(&scan);
+
+    assert_eq!(view.format, Some(crate::dto::PackFormatView::Modrinth));
+    assert_eq!(view.pack_name.as_deref(), Some("Better MC"));
+    assert_eq!(view.unknown_remote, 2, "判不了的远端条目要如实计数");
+    assert!(view.needs_decision(), "有一条冲突就要问用户");
+    let conflict = &view.conflicts[0];
+    assert_eq!(conflict.path, "config/sodium-options.json");
+    assert_eq!(
+        conflict.source,
+        ConflictSourceView::ClientOverrides,
+        "叠层胜者那一侧的来源"
+    );
+    assert_eq!(conflict.reason, ConflictReasonView::UserModified);
+    assert_eq!(conflict.pack_size, 4_200);
+    assert_eq!(conflict.disk_size, 5_100, "目标现有体积要出现在清单里");
+    assert_eq!(conflict.disk_sha1.len(), 40, "目标现有哈希也要有");
+    assert_eq!(view.lost_bytes, 5_100, "覆盖会丢掉的字节");
+    assert_eq!(view.incoming_bytes, 4_200);
+}
+
+#[test]
+fn a_clean_scan_is_not_a_reason_to_bother_the_user() {
+    let mut scan = scan_fixture();
+    scan.conflicts.clear();
+    let view = super::super::convert::scan_view(&scan);
+    assert!(!view.needs_decision());
+    assert!(view.is_clean(), "没有冲突也没有错误 ⇒ 可以直接导入");
+}
+
+#[test]
+fn decisions_are_keep_all_by_default() {
+    // 缺省 = 全部保留：页面不发决策、或发默认值，结果都必须是"一个文件都不动"。
+    let view = ConflictDecisionsView::default();
+    assert_eq!(view, ConflictDecisionsView::KeepAll);
+    assert!(!view.overwrites_everything());
+    let core = super::super::convert::decisions_of(&view);
+    assert_eq!(core.choice_for("config/a.toml"), ConflictChoice::KeepUser);
+    assert_eq!(core.default_choice(), ConflictChoice::KeepUser);
+    assert!(core.is_empty());
+}
+
+#[test]
+fn the_three_channels_map_one_to_one() {
+    // 全部覆盖
+    let all = super::super::convert::decisions_of(&ConflictDecisionsView::OverwriteAll);
+    assert_eq!(all.choice_for("anything.toml"), ConflictChoice::Overwrite);
+    assert_eq!(all.default_choice(), ConflictChoice::Overwrite);
+
+    // 逐项：点名的照点名走，没点名的落到"保留"。
+    let view = ConflictDecisionsView::per_item(
+        ConflictChoiceView::KeepUser,
+        vec![
+            ConflictDecisionView {
+                path: "mods/pin.jar".to_string(),
+                choice: ConflictChoiceView::Overwrite,
+            },
+            ConflictDecisionView {
+                path: "config/keep.toml".to_string(),
+                choice: ConflictChoiceView::KeepUser,
+            },
+        ],
+    );
+    assert_eq!(view.overwrite_count(), 1);
+    assert_eq!(view.keep_count(), 1);
+    assert_eq!(view.len(), 2);
+    assert!(!view.overwrites_everything(), "逐项不等于整批覆盖");
+
+    let core = super::super::convert::decisions_of(&view);
+    assert_eq!(core.choice_for("mods/pin.jar"), ConflictChoice::Overwrite);
+    assert_eq!(
+        core.choice_for("config/keep.toml"),
+        ConflictChoice::KeepUser
+    );
+    assert_eq!(
+        core.choice_for("mods/unlisted.jar"),
+        ConflictChoice::KeepUser,
+        "没点名的路径不许被逐项表顺手覆盖"
+    );
+    assert_eq!(core.overwrite_count(), 1);
+}
+
+#[test]
+fn the_scan_runs_without_writing_and_says_nothing_when_there_is_no_conflict() {
+    // 真跑一次后台预检：全新目标（什么都没有）⇒ 没有冲突，且**目标目录没被建出来**。
+    let dir = temp_dir("scan-fresh");
+    let source = dir.join("Better MC");
+    write(
+        &source.join("mmc-pack.json"),
+        br#"{"formatVersion": 1, "components": [
+            {"uid": "net.minecraft", "version": "1.20.1"}]}"#,
+    );
+    write(&source.join(".minecraft/mods/sodium.jar"), &[0x11; 64]);
+
+    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("Scan Only".to_string()),
+        decisions: ConflictDecisionsView::default(),
+    };
+    super::super::import::spawn_scan(
+        env,
+        tx,
+        request,
+        9,
+        std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false)),
+    );
+
+    let mut scan = None;
+    for task in rx.iter() {
+        if let crate::host::job::HostTask::Pack { event, epoch } = task {
+            assert_eq!(epoch, 9, "代次必须原样带回");
+            if let crate::dto::PackEvent::Scan(view) = *event {
+                scan = Some(*view);
+            }
+        }
+    }
+    let scan = scan.expect("必须回一条预检事件");
+    assert!(scan.error.is_none(), "{:?}", scan.error);
+    assert!(
+        !scan.needs_decision(),
+        "空目标上不该有冲突：{:?}",
+        scan.conflicts
+    );
+    assert_eq!(scan.format, Some(crate::dto::PackFormatView::Multimc));
+    assert!(
+        !scan.target.exists(),
+        "预检只读：目标目录不许被建出来（{}）",
+        scan.target.display()
+    );
+
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+/// 事件序列的名字（断言"用户到底能不能看见"用）。
+fn kind_of(event: &crate::dto::PackEvent) -> &'static str {
+    match event {
+        crate::dto::PackEvent::Progress(_) => "progress",
+        crate::dto::PackEvent::Scan(scan) if scan.error.is_some() => "scan-with-error",
+        crate::dto::PackEvent::Scan(_) => "scan",
+        crate::dto::PackEvent::Report(report) if report.error.is_some() => "report-failed",
+        crate::dto::PackEvent::Report(_) => "report",
+        crate::dto::PackEvent::Probe(_) => "probe",
+        crate::dto::PackEvent::Preview(_) => "preview",
+        crate::dto::PackEvent::Exported(_) => "exported",
+        crate::dto::PackEvent::ExportFailed(_) => "export-failed",
+        crate::dto::PackEvent::Cancelled => "cancelled",
+        crate::dto::PackEvent::Cleared => "cleared",
+    }
+}
+
+/// 跑一次 `spawn_scan`，把事件按顺序收回来。
+fn run_scan(source: std::path::PathBuf, data: &std::path::Path) -> Vec {
+    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("Scan Rework".to_string()),
+        decisions: ConflictDecisionsView::default(),
+    };
+    super::super::import::spawn_scan(
+        env,
+        tx,
+        request,
+        3,
+        std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false)),
+    );
+    let mut events = Vec::new();
+    for task in rx.iter() {
+        if let crate::host::job::HostTask::Pack { event, epoch } = task {
+            assert_eq!(epoch, 3, "代次必须原样带回");
+            events.push(*event);
+        }
+    }
+    events
+}
+
+#[test]
+fn a_failed_scan_still_reaches_the_screen_as_a_report() {
+    // 复审 r1 P2-1 的回归钉：**这条用例验的是"用户看得见"，不是"字段被填了"**。
+    //
+    // 达标形状（旧行为 / M160 之前）：`Import` 失败 → `PackEvent::Report` → 结果块画「已回滚」+ 原因。
+    // 出错形状（本 diff 引入的回归）：只发 `Scan(error)` ⇒ 页面 pick 为空、report 被清空 ⇒ 入口态，
+    // 屏幕上什么都不发生。所以这里逐一断言**事件序列**，而不只看 `scan.error`。
+    //
+    // 可达面：detect 认得、read 才失败的包。这里用最普通的一种——MultiMC 的
+    // `formatVersion: 2`（Prism 自己也会整份丢弃，不是刻意构造的畸形包）。
+    let dir = temp_dir("scan-error");
+    let source = dir.join("Prism 2");
+    write(
+        &source.join("mmc-pack.json"),
+        br#"{"formatVersion": 2, "components": [
+            {"uid": "net.minecraft", "version": "1.20.1"}]}"#,
+    );
+    write(&source.join(".minecraft/mods/sodium.jar"), &[0x11; 32]);
+    let data = dir.join("data");
+    std::fs::create_dir_all(&data).expect("data root");
+
+    let events = run_scan(source, &data);
+    let kinds: Vec<&str> = events.iter().map(kind_of).collect();
+    assert_eq!(
+        kinds,
+        vec!["scan-with-error", "report-failed"],
+        "预检自己失败时必须再发一条结果事件（否则页面静默空转）"
+    );
+
+    let crate::dto::PackEvent::Scan(scan) = &events[0] else {
+        panic!("第一条必须是预检结果");
+    };
+    let error = scan.error.as_ref().expect("预检要带出错误");
+    assert_eq!(
+        error.code, "pack_metadata",
+        "formatVersion != 1 是清单自身非法"
+    );
+    assert!(
+        error.message.contains("formatVersion"),
+        "原因要能读：{}",
+        error.message
+    );
+
+    // 结果事件：三态是 Failed、原因与预检那份同源（code/label/message 都搬过来）。
+    let crate::dto::PackEvent::Report(report) = &events[1] else {
+        panic!("第二条必须是结果");
+    };
+    assert_eq!(report.status, crate::dto::ImportStatusView::Failed);
+    let reported = report.error.as_ref().expect("报告要带出原因");
+    assert_eq!(reported.code, error.code);
+    assert_eq!(reported.message, error.message);
+    assert!(!reported.label.is_empty(), "人读大类名也要有");
+
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+#[test]
+fn a_clean_scan_does_not_emit_a_report() {
+    // 对照：干净预检只发一条 Scan（多发 Report 会把页面从"清单"顶到"结果"）。
+    let dir = temp_dir("scan-clean");
+    let source = dir.join("Vanilla");
+    write(
+        &source.join("mmc-pack.json"),
+        br#"{"formatVersion": 1, "components": [{"uid": "net.minecraft", "version": "1.20.1"}]}"#,
+    );
+    write(&source.join(".minecraft/mods/sodium.jar"), &[0x11; 32]);
+    let data = dir.join("data");
+    std::fs::create_dir_all(&data).expect("data root");
+
+    let kinds: Vec<&str> = run_scan(source, &data).iter().map(kind_of).collect();
+    assert_eq!(kinds, vec!["scan"], "干净预检只发一条");
+    let _ = std::fs::remove_dir_all(&dir);
+}
diff --git a/crates/presenter/src/host/addon/plan.rs b/crates/presenter/src/host/addon/plan.rs
new file mode 100644
index 0000000..2e7b8d8
--- /dev/null
+++ b/crates/presenter/src/host/addon/plan.rs
@@ -0,0 +1,336 @@
+//! 依赖计划的**宿主侧那一半**：扫目录、把两档失败映成 DTO 大类、拼给用户看的那句话。
+//!
+//! # 为什么判定在 core、说话在 presenter
+//!
+//! 「哪个前置不兼容、哪个前置取不到」由 `unlucky_core::addon::online::resolve` 判定并可离线
+//! 测试（录制 JSON 夹具）。本文件只做三件宿主才知道的事：
+//!
+//! | 事 | 为什么只能在这里 |
+//! |---|---|
+//! | 目标目录里有什么 | core 不读盘（`PresentFile` 由调用方扫） |
+//! | 失败大类怎么映 | DTO 在 presenter（`ContentFailureKind`） |
+//! | 文案怎么说 | 界面文案不归 core |
+//!
+//! # 两档失败**分开说**
+//!
+//! 「不兼容所选版本/加载器」与「取不到（网络 / 项目不存在）」是两句话、两种用户动作，
+//! 所以这里既不合并计数也不合并文案；DTO 大类按「用户接下来该做什么」选：离线优先说
+//! 检查网络，其次查无此项，只有**全是**不兼容时才说「这条路走不通」（换版本/加载器才有救）。
+//!
+//! # 「可只重试这些」的名单也在这里（M191）
+//!
+//! [`retry_items`] 把计划里的失败项摊成 DTO 的 [`InstallFailureView`]（项目键 + 可读标签 +
+//! 档位 + 原话），界面据此分组画两段；[`retry_plan`] 是**真正重试**那一步——它调 core 的
+//! `DependencyPlan::retry_request()`，于是重试只请求失败的那几个项目，**不是**重新发起根项目安装。
+//!
+//! 可读标签由 [`label_of`] 定（根项目用请求标题、下载失败用文件名、解析失败留空），
+//! **不许**拿 `failure.message` 顶上——那是 core 的中文散文，界面照画会踩 i18n R2。
+//!
+//! # 不兼容有自己的一档（M191 起）
+//!
+//! M186 把它映成 `Unsupported`（当时 DTO 没有这一档，与「缺密钥」共用），于是界面没法单独说
+//! 「换个版本/加载器」。M191 给 `ContentFailureKind` 加了 `Incompatible`，[`kind_of`] 直接映射，
+//! **不再借 `Unsupported`**。
+
+use std::path::Path;
+
+use unlucky_core::addon::online::{
+    DependencyFailure, DependencyPlan, FailureKind, OnlineError, PlannedNode, PresentFile,
+    ResolveRequest,
+};
+
+use crate::dto::{ContentFailureKind, InstallFailureKind, InstallFailureView};
+
+use super::sources::failure_of;
+
+mod labels;
+mod remembered;
+
+pub(super) use labels::{fetch_title, names_for_incompatible, Root};
+pub(super) use remembered::{forget, remember, remembered};
+
+/// 扫目标目录（不递归）里已存在的文件名。
+///
+/// 只给名字，不算摘要：为了「跳过」把整个 `mods/` 哈希一遍不划算，同名就是同一份 jar 的
+/// 最常见形态（我们落盘用站点给的文件名，不重命名）。
+pub(super) fn present_files(dir: &Path) -> Vec {
+    let Ok(entries) = std::fs::read_dir(dir) else {
+        return Vec::new();
+    };
+    entries
+        .flatten()
+        .filter(|entry| entry.path().is_file())
+        .map(|entry| PresentFile::new(entry.file_name().to_string_lossy()))
+        .collect()
+}
+
+/// 一次装入要用的解析请求（过滤条件与落盘目录一致）。
+pub(super) fn request(
+    project: &str,
+    game_version: &str,
+    loader: Option<&str>,
+    present: Vec,
+) -> ResolveRequest {
+    ResolveRequest {
+        roots: vec![project.to_string()],
+        game_version: Some(game_version.to_string()),
+        loader: loader.map(str::to_string),
+        present,
+        ..ResolveRequest::default()
+    }
+}
+
+/// 计划里有失败吗 ⇒ 一条带大类的失败（`None` = 干净）。
+///
+/// `installed` = **真落盘的**文件数（下载失败的不算）：失败文案里要能说清「主文件已装、
+/// 缺的是谁的前置」，所以不能拿 `plan.nodes.len()` 冒充。
+pub(super) fn failure_of_plan(
+    plan: &DependencyPlan,
+    installed: usize,
+) -> Option {
+    if plan.is_clean() {
+        return None;
+    }
+    Some(crate::dto::ContentFailure::new(
+        overall_kind(plan),
+        report(plan, installed),
+    ))
+}
+
+/// 整体大类：按「用户接下来该做什么」排序，离线 > 查无此项 > 站点错 > 其它 > 不兼容。
+fn overall_kind(plan: &DependencyPlan) -> ContentFailureKind {
+    let kinds: Vec = plan.failures.iter().map(kind_of).collect();
+    for wanted in [
+        ContentFailureKind::Offline,
+        ContentFailureKind::NotFound,
+        ContentFailureKind::Server,
+        ContentFailureKind::Other,
+        ContentFailureKind::Unsupported,
+    ] {
+        if kinds.contains(&wanted) {
+            return wanted;
+        }
+    }
+    // 只剩「不兼容」这一档：换版本/加载器才有救（M191 起它有自己的大类，不再借 `Unsupported`）
+    ContentFailureKind::Incompatible
+}
+
+/// 单条失败的 DTO 大类（**复用** `sources::failure_of` 的映射表，不另写一份判据）。
+fn kind_of(failure: &DependencyFailure) -> ContentFailureKind {
+    match failure.cause {
+        Some(cause) => failure_of(OnlineError::new(cause, failure.message.clone())).kind,
+        // 不兼容那一档没有网络成因：它要用户换版本/加载器，不是「再试一次」
+        None => ContentFailureKind::Incompatible,
+    }
+}
+
+/// 可只重试的失败项 → DTO 名单（M191；界面按档分组画的那几条）。
+///
+/// 档位**一一映射** core 的 [`FailureKind`]：两档在 DTO 上分开，界面才有两段文案。
+/// 顺序沿用计划里的顺序（`record_failure` 已按项目键去重，同一项目只出现一次）。
+#[must_use]
+pub(super) fn retry_items(
+    plan: &DependencyPlan,
+    root: labels::Root<'_>,
+    names: &labels::Names,
+) -> Vec {
+    plan.failures
+        .iter()
+        .map(|failure| {
+            InstallFailureView::new(
+                failure.requested_as.clone(),
+                labels::label_of(plan, failure, root, names),
+                failure_kind_of(failure.kind),
+                failure.message.clone(),
+            )
+        })
+        .collect()
+}
+
+/// core 的档位 → DTO 的档位（**穷尽 match**：谁把两档合并，这条会报错或让用例红）。
+const fn failure_kind_of(kind: FailureKind) -> InstallFailureKind {
+    match kind {
+        FailureKind::Incompatible => InstallFailureKind::Incompatible,
+        FailureKind::Unreachable => InstallFailureKind::Unreachable,
+    }
+}
+
+/// 下一次解析的请求：**只含失败项**（M191）。
+///
+/// 这就是「只重试这些」的全部实现——请求来自 core 的
+/// `DependencyPlan::retry_request()`（它只把失败项列进 `roots`），过滤条件沿用上次那份。
+/// `present` 必须**重新扫**：这一轮新落盘的文件不在旧名单里，不重扫会被当成「还没有」再下一份
+/// （core 的 `retry_request` 文档明确要求）。
+///
+/// 拿不到计划时（换进程 / 那次是别的实例）调用方**不许**退回「整单重装」：那会把已经装好的
+/// 文件再下一遍，且请求数放大——正是本函数要避免的行为。
+#[must_use]
+pub(super) fn retry_request(plan: &DependencyPlan, present: Vec) -> ResolveRequest {
+    ResolveRequest {
+        present,
+        ..plan.retry_request()
+    }
+}
+
+/// 用「只含失败项」的请求重新解析（**生产**用它；用例注入假解析器断言只请求了哪几个项目）。
+///
+/// 解析器用闭包注入而不是直接调 core：这样「重试请求里到底有哪几个项目、发了几次」在没有网络
+/// 的用例里也能钉住（M191 的变异守门：把 `retry_request()` 换成根项目请求，用例必须红）。
+pub(super) fn retry_plan(
+    plan: &DependencyPlan,
+    present: Vec,
+    resolve: impl FnOnce(&ResolveRequest) -> DependencyPlan,
+) -> DependencyPlan {
+    let request = retry_request(plan, present);
+    resolve(&request)
+}
+
+/// 失败清单（两档各起一段，各自的条数分开数）。
+fn report(plan: &DependencyPlan, installed: usize) -> String {
+    let mut lines: Vec = Vec::new();
+    let incompatible: Vec = plan
+        .failures_of(FailureKind::Incompatible)
+        .map(describe)
+        .collect();
+    let unreachable: Vec = plan
+        .failures_of(FailureKind::Unreachable)
+        .map(describe)
+        .collect();
+    if !incompatible.is_empty() {
+        lines.push(format!(
+            "不兼容所选版本/加载器 {} 个：{}",
+            incompatible.len(),
+            incompatible.join("；")
+        ));
+    }
+    if !unreachable.is_empty() {
+        lines.push(format!(
+            "取不到（网络 / 项目不存在）{} 个：{}",
+            unreachable.len(),
+            unreachable.join("；")
+        ));
+    }
+    if installed > 0 {
+        lines.push(format!("已装入 {installed} 个文件（已下好的不回滚）"));
+    }
+    if !plan.skipped.is_empty() {
+        lines.push(format!("跳过 {} 个已存在的文件", plan.skipped.len()));
+    }
+    if let Some(note) = unresolved_note(plan) {
+        lines.push(note);
+    }
+    if !plan.truncated.is_empty() {
+        lines.push(format!(
+            "依赖层数超过上限，未展开：{}",
+            plan.truncated.join("、")
+        ));
+    }
+    // 可重试名单：只列失败项（重试时也只重解这些，不重下已装好的）
+    let retry = plan.retry_request().roots;
+    if !retry.is_empty() {
+        lines.push(format!(
+            "可只重试这 {} 个：{}",
+            retry.len(),
+            retry.join("、")
+        ));
+    }
+    lines.join("\n")
+}
+
+fn describe(failure: &DependencyFailure) -> String {
+    if failure.required_by.is_empty() {
+        format!("{}（{}）", failure.requested_as, failure.message)
+    } else {
+        format!(
+            "{}（{}；被 {} 要求）",
+            failure.requested_as,
+            failure.message,
+            failure.required_by.join("、")
+        )
+    }
+}
+
+/// 「有 required 但没有项目 id」那一档的提示（解析不了，但也不是没事发生）。
+fn unresolved_note(plan: &DependencyPlan) -> Option {
+    if plan.unresolved_required.is_empty() {
+        return None;
+    }
+    let items: Vec = plan
+        .unresolved_required
+        .iter()
+        .map(|item| {
+            let what = item
+                .version_id
+                .clone()
+                .or_else(|| item.file_name.clone())
+                .unwrap_or_else(|| "未给版本".to_string());
+            format!("{}（被 {} 要求）", what, item.parent)
+        })
+        .collect();
+    Some(format!(
+        "有 {} 条必备前置只给了版本/文件名、没有项目 id，无法自动解析：{}",
+        items.len(),
+        items.join("；")
+    ))
+}
+
+/// 全部装成之后的落盘描述（含跳过与前置的条数、「为什么装」的父项目）。
+///
+/// `installed` 是**真落盘**的那些（下载失败的不在里面），所以条数与文件名都从它来，
+/// 不从 `plan.nodes` 来——否则「装成了 N 个」会把下载失败的也数进去。
+pub(super) fn summary(plan: &DependencyPlan, installed: &[PlannedNode]) -> String {
+    if installed.is_empty() && plan.skipped.is_empty() && plan.unresolved_required.is_empty() {
+        return "没有要装的文件".to_string();
+    }
+    let mut parts: Vec = Vec::new();
+    if !installed.is_empty() {
+        let dependencies = installed.iter().filter(|node| !node.is_root()).count();
+        // 「为什么装」：前置标出要求它的项目（根是用户自己点的，不标）
+        let names: Vec = installed
+            .iter()
+            .map(|node| {
+                if node.is_root() {
+                    node.file.filename.clone()
+                } else {
+                    format!(
+                        "{}（前置，被 {} 要求）",
+                        node.file.filename,
+                        node.required_by.join("、")
+                    )
+                }
+            })
+            .collect();
+        let head = if dependencies == 0 {
+            format!("装了 {} 个文件", installed.len())
+        } else {
+            format!(
+                "装了 {} 个文件（含 {} 个前置）",
+                installed.len(),
+                dependencies
+            )
+        };
+        parts.push(format!("{head}：{}", names.join("、")));
+    }
+    if !plan.skipped.is_empty() {
+        let names: Vec<&str> = plan
+            .skipped
+            .iter()
+            .map(|node| node.file_name.as_str())
+            .collect();
+        parts.push(format!(
+            "跳过 {} 个（目录里已存在，没有重复下载）：{}",
+            plan.skipped.len(),
+            names.join("、")
+        ));
+    }
+    if let Some(note) = unresolved_note(plan) {
+        parts.push(note);
+    }
+    if !plan.truncated.is_empty() {
+        parts.push(format!(
+            "依赖层数超过上限，未展开：{}",
+            plan.truncated.join("、")
+        ));
+    }
+    parts.join("\n")
+}
diff --git a/crates/presenter/src/host/addon/plan/labels.rs b/crates/presenter/src/host/addon/plan/labels.rs
new file mode 100644
index 0000000..458b2a8
--- /dev/null
+++ b/crates/presenter/src/host/addon/plan/labels.rs
@@ -0,0 +1,173 @@
+//! 「这条失败该显示什么名字」——**语言中立**的标签来源（M191 r1 P2-1 / r2 P2-1 续）。
+//!
+//! 从 `plan.rs` 拆出（加完失败路径上取名字那次 GET 之后父文件到 414 行，越过 400 行硬线）。
+//! 拆的口径是「一件事一个文件」：这里只管**名字从哪来**，判定与说话仍在 `plan.rs`。
+//!
+//! 三个来源，按可信度排（细节在 [`label_of`]）：原始根项目的标题、失败文件的文件名、
+//! 失败路径上现取的项目名；都没有就留空，界面只画项目 id。
+//!
+//! **不许**拿 `DependencyFailure::message` 顶：那是 core 的中文散文，画到界面上就是 i18n R2 的违规。
+
+use unlucky_core::addon::online::{
+    DependencyFailure, DependencyPlan, EngineTransport, FailureKind, Modrinth, OnlineError,
+    ProjectDetail,
+};
+use unlucky_core::download::blocking::block_on;
+
+use super::super::super::env::HostEnv;
+
+/// 这一次装入的**原始根项目**（id + 显示名）。
+///
+/// 「是不是根」只能按 `id` 比（r2 复审 P2-2）：重试那一轮的 plan 来自
+/// `DependencyPlan::retry_request()`，它的 `request.roots` **就是上一轮的失败名单**——
+/// 第一个是前置，拿它当「根」会把根的标题贴到前置头上。所以判据是「这条失败的 id 是不是
+/// 当初那次装入的根 id」，两个值都由 [`remembered`] / `ContentInstallRequest` 提供。
+#[derive(Clone, Copy)]
+pub(in crate::host::addon) struct Root<'a> {
+    /// 当初那次装入的根项目 id（`ContentInstallRequest.project`）
+    pub id: &'a str,
+    /// 它的显示名（`ContentInstallRequest.title`；只配给 `id` 用）
+    pub title: &'a str,
+}
+
+/// 失败路径上现取的项目名（id → title）。取不到的项目不在表里。
+pub(in crate::host::addon) type Names = Vec<(String, String)>;
+
+/// 为「不兼容」档现取项目名（**只在失败路径上**，一个项目一次 GET）。
+///
+/// 为什么只给这一档：`FailureKind::Incompatible` 是「站点**有这个项目**，但目标版本/加载器下
+/// 没有条目」——项目确实存在，所以这次 GET 有东西可拿。「取不到」档里 404 的那部分项目根本
+/// 不存在，给它发请求只会再吃一个 404，于是那一档仍显示 id（合理兜底）。
+///
+/// `lookup` 由调用方注入（生产是 `Modrinth::project`，用例是闭包）：于是「取名字失败也要能降级」
+/// 这件事在没有网络的用例里也能钉住。取不到 / 拿到空串的项一律**不进**名单。
+pub(in crate::host::addon) fn names_for_incompatible(
+    plan: &DependencyPlan,
+    lookup: impl Fn(&str) -> Option,
+) -> Names {
+    plan.failures_of(FailureKind::Incompatible)
+        .filter_map(|failure| {
+            let title = lookup(&failure.requested_as)?;
+            let title = title.trim();
+            (!title.is_empty()).then(|| (failure.requested_as.clone(), title.to_string()))
+        })
+        .collect()
+}
+
+/// 一条失败的可读标签（**语言中立**：站点标题、文件名或现取的项目名；拿不到就是空串）。
+///
+/// 三个来源，**按可信度排**：
+///
+/// | 情况 | 标签 | 为什么 |
+/// |---|---|---|
+/// | 这条失败的 id == 原始根 id | 请求里的 `title` | 用户刚才点的就是它 |
+/// | 计划里有这个节点（下载失败） | `node.file.filename` | 「哪个文件没下来」比项目名更具体 |
+/// | 不兼容档 | [`names_for_incompatible`] 现取的名字 | 项目存在，一次 GET 拿得到 |
+/// | 其余（解析 404 等） | 空 | 项目不存在，显示 id 是合理兜底 |
+///
+/// **不许**拿 `failure.message` 顶：那是 core 的中文散文，画到界面上就是 i18n R2 的违规。
+#[must_use]
+pub(super) fn label_of(
+    plan: &DependencyPlan,
+    failure: &DependencyFailure,
+    root: Root<'_>,
+    names: &Names,
+) -> String {
+    // ① 根项目自己失败：**按 id 比**，不看 `plan.request.roots`（重试轮里那是失败名单）
+    if failure.requested_as == root.id {
+        return root.title.to_string();
+    }
+    // ② 计划里有这个节点（下载失败）：文件名最具体
+    if let Some(node) = plan
+        .nodes
+        .iter()
+        .find(|node| node.requested_as == failure.requested_as)
+    {
+        return node.file.filename.clone();
+    }
+    // ③ 不兼容档：失败路径上现取的名字；取不到就空 ⇒ 界面只画 id
+    if failure.kind == FailureKind::Incompatible {
+        return names
+            .iter()
+            .find(|(id, _)| id == &failure.requested_as)
+            .map(|(_, title)| title.clone())
+            .unwrap_or_default();
+    }
+    String::new()
+}
+
+/// 取一个项目的显示名（**只在失败路径上**发）。
+///
+/// 一次 GET，折成「有名字 / 没名字」的那一步在 [`title_from`]（那里才是能坏的地方，因此那一步
+/// 单独可测；本函数只有「怎么发这一枪」）。
+pub(in crate::host::addon) fn fetch_title(env: &HostEnv, id: &str) -> Option {
+    let core_engine = crate::host::engine::engine(env);
+    let transport = EngineTransport::new(&core_engine);
+    let client = Modrinth::new(&transport);
+    title_from(|id| block_on(async { client.project(id).await }), id)
+}
+
+/// 把「一次项目查询」折成「有名字 / 没名字」——**降级就在这一层**（r3 复审 p2 要的守卫）。
+///
+/// 三种「没名字」都算 `None`，一个都不许往外冒：
+///
+/// | 情况 | 结果 |
+/// |---|---|
+/// | 查询失败（没网 / 404 / 坏响应） | `None`（**不是 panic，也不是错误**） |
+/// | 站点给了空标题 | `None` |
+/// | 站点给了全空白标题 | `None` |
+///
+/// 为什么单独抽出来：这条链路上唯一会「坏」的就是这一句折叠。抽成参数化的纯函数之后，
+/// 「查询失败仍退回 id」与「空白不算名字」都能在没有网络的用例里钉住（变异：`ok` 换 `expect`
+/// ⇒ 红；去掉空串过滤 ⇒ 红）。
+fn title_from(
+    query: impl FnOnce(&str) -> Result,
+    id: &str,
+) -> Option {
+    query(id)
+        .ok()
+        .map(|project| project.title)
+        .filter(|title| !title.trim().is_empty())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn detail(title: &str) -> ProjectDetail {
+        ProjectDetail {
+            id: "P7dR8mSH".to_string(),
+            title: title.to_string(),
+            ..ProjectDetail::default()
+        }
+    }
+
+    /// **降级层**：查询失败 / 空标题 / 全空白 ⇒ 一律 `None`（界面退回只画 id），不 panic。
+    ///
+    /// 抓得住：把 `.ok()` 换成 `expect`（查询失败即 panic）⇒ 第一条红；
+    /// 去掉 `.filter(..)`（空白也算名字）⇒ 后两条红。
+    #[test]
+    fn a_failed_or_blank_lookup_yields_no_name() {
+        // ① 查询失败（没网 / 404 / 坏响应）
+        assert!(title_from(|_| Err(OnlineError::offline("断网")), "P7dR8mSH").is_none());
+        // ② 站点给了空标题
+        assert!(title_from(|_| Ok(detail("")), "P7dR8mSH").is_none());
+        // ③ 站点给了全空白标题
+        assert!(title_from(|_| Ok(detail("   ")), "P7dR8mSH").is_none());
+        // ④ 正常情况：原样给出
+        assert_eq!(
+            title_from(|_| Ok(detail("Entity Culling")), "P7dR8mSH"),
+            Some("Entity Culling".to_string())
+        );
+        // 传进去的 id 就是查询用的那个（不要拿别的键去问）
+        let mut asked = String::new();
+        let _ = title_from(
+            |id| {
+                asked.push_str(id);
+                Ok(detail("X"))
+            },
+            "P7dR8mSH",
+        );
+        assert_eq!(asked, "P7dR8mSH");
+    }
+}
diff --git a/crates/presenter/src/host/addon/plan/remembered.rs b/crates/presenter/src/host/addon/plan/remembered.rs
new file mode 100644
index 0000000..e8bd735
--- /dev/null
+++ b/crates/presenter/src/host/addon/plan/remembered.rs
@@ -0,0 +1,106 @@
+//! 「上一次装入留下的计划」表（M191）：`retry_plan()` 的输入。
+//!
+//! 从 `plan.rs` 拆出（父文件加了 `label_of` 之后顶到 429 行，越过 400 行硬线）。
+//! 拆法与本仓既有 `-p1/-p2` 一致：**纯搬移**，一行不改语义；调用方路径不变
+//! （`plan.rs` 仍然 `pub(super) use` 这三个函数）。
+
+use std::path::{Path, PathBuf};
+use std::sync::Mutex;
+
+use unlucky_core::addon::online::DependencyPlan;
+
+use super::super::super::env::HostEnv;
+
+/// 「上一次装入留下的计划」表的一行（M191）：`只重试这些` 的输入。
+///
+/// ## 为什么要一张静态表（说清楚这笔债）
+///
+/// 重试要的输入是**上一轮那份 `DependencyPlan`**（`retry_request()` 是它的方法）。它现在活在
+/// `CoreHost`（`host/dispatch.rs`）之外，因为那个文件不在本 mission 的 scope；与
+/// `addon/pack.rs` 的 `PACK_STATE` 同一手法：每 host 一格（键 = 数据根），于是测试里两个 host
+/// 互不干扰。`host/mod.rs` 一旦进 scope，把这张表搬成一个字段即可（这表就是那个字段）。
+///
+/// 键里带 `instance`：同一台机器上往两个实例装过东西，重试只该重试这个实例那一次的计划。
+/// 成功之后由 [`forget`] 清掉——「全成功」时不该留下任何可重试的东西。
+///
+/// ## 为什么连**原始根项目 id** 一起记（r2 复审 P2-2）
+///
+/// 「这一条是不是根项目自己失败」不能靠 `plan.request.roots.first()` 判：重试那一轮的 plan 来自
+/// `DependencyPlan::retry_request()`，它的 `roots` 就是**上一轮的失败名单**——第一个是前置，
+/// 拿它跟根的显示名一比，就会把 `Sodium` 贴到一个前置头上。所以判据只能是「这个 id 是不是
+/// 当初那次装入的根 id」，那个 id 得跟计划一起记下来。
+struct Entry {
+    host: PathBuf,
+    instance: String,
+    /// 落盘目录（重试要按它重新扫 `present`，且**不许**换目录）
+    dir: PathBuf,
+    /// 当初那次装入的根项目 id（`ContentInstallRequest.project`，判「是不是根」的唯一依据）
+    root: String,
+    /// 当初那次装入的显示名（只配给 `root` 用）
+    title: String,
+    plan: DependencyPlan,
+}
+
+static REMEMBERED: Mutex> = Mutex::new(Vec::new());
+
+/// 取回的那一份记录（拆成结构体而不是四元组：调用点读得懂哪一个是哪个）。
+pub(in crate::host::addon) struct Remembered {
+    /// 落盘目录
+    pub dir: PathBuf,
+    /// 当初那次装入的根项目 id
+    pub root: String,
+    /// 当初那次装入的显示名
+    pub title: String,
+    /// 上一轮的依赖计划（`retry_request()` 的来源）
+    pub plan: DependencyPlan,
+}
+
+/// 记下这一轮的计划（**覆盖**同一个 host + 实例的上一份）。
+pub(in crate::host::addon) fn remember(
+    env: &HostEnv,
+    instance: &str,
+    dir: &Path,
+    root: &str,
+    title: &str,
+    plan: &DependencyPlan,
+) {
+    let host = env.layout.home().to_path_buf();
+    let mut table = REMEMBERED
+        .lock()
+        .unwrap_or_else(|poison| poison.into_inner());
+    table.retain(|item| !(item.host == host && item.instance == instance));
+    table.push(Entry {
+        host,
+        instance: instance.to_string(),
+        dir: dir.to_path_buf(),
+        root: root.to_string(),
+        title: title.to_string(),
+        plan: plan.clone(),
+    });
+}
+
+/// 忘掉这个实例的计划（装成功 / 没有失败项时调：没有可重试的东西了）。
+pub(in crate::host::addon) fn forget(env: &HostEnv, instance: &str) {
+    let host = env.layout.home().to_path_buf();
+    let mut table = REMEMBERED
+        .lock()
+        .unwrap_or_else(|poison| poison.into_inner());
+    table.retain(|item| !(item.host == host && item.instance == instance));
+}
+
+/// 这个实例上一次失败的计划（+ 落盘目录 + 原始根 id 与显示名）；`None` = 没有可重试的记录。
+pub(in crate::host::addon) fn remembered(env: &HostEnv, instance: &str) -> Option {
+    let host = env.layout.home().to_path_buf();
+    let table = REMEMBERED
+        .lock()
+        .unwrap_or_else(|poison| poison.into_inner());
+    table
+        .iter()
+        .find(|item| item.host == host && item.instance == instance)
+        .map(|item| Remembered {
+            dir: item.dir.clone(),
+            root: item.root.clone(),
+            title: item.title.clone(),
+            plan: item.plan.clone(),
+        })
+}
diff --git a/crates/presenter/src/host/addon/sources.rs b/crates/presenter/src/host/addon/sources.rs
new file mode 100644
index 0000000..fb219cb
--- /dev/null
+++ b/crates/presenter/src/host/addon/sources.rs
@@ -0,0 +1,349 @@
+//! 两个站点的检索方言（M109；M162 起 Modrinth 走 `core::addon::online`）+ **详情/版本列表**。
+//!
+//! # M162 之后的分工
+//!
+//! | 站点 | 检索 | 详情 / 版本列表 | 端点拼装与 JSON 解析在哪 |
+//! |------|------|------------------|--------------------------|
+//! | Modrinth | `core::addon::online` | `core::addon::online` | core（`online::modrinth` / `online::model`） |
+//! | CurseForge | 本文件（要 `X-API-KEY`） | **未接通**（明确报错） | 本文件 |
+//!
+//! 为什么 Modrinth 搬走：「在线内容源」是 core 的能力（导出的 `RemoteCatalog`、导入的
+//! `PackFetcher`、UI 的检索要共用同一份解析与同一套错误分类）。presenter 只留 DTO 映射与
+//! 失败分类——它不再自己拼 URL、不再自己读 JSON 字段名。
+//!
+//! # 两个站点的字段名完全不同（CF 这一半仍是本文件的活）
+//!
+//! | 语义 | 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」这种假加载器（core 那一侧的
+//! `known_loaders` 已经过滤，`sources/tests` 钉住了这一条）。
+
+use serde_json::Value;
+
+use unlucky_core::addon::online::{
+    ContentType, Modrinth, OnlineError, OnlineErrorKind, SearchQuery, SortIndex, VersionQuery,
+};
+
+use crate::dto::{
+    loader_facet, ContentDetail, ContentDetailRequest, ContentFailure, ContentFailureKind,
+    ContentHit, ContentQuery, ContentResults, ContentSource, ContentVersionView,
+};
+
+use super::super::engine;
+use super::super::env::HostEnv;
+use super::curseforge_ready;
+use super::http::{encode, get};
+use unlucky_core::addon::online::EngineTransport;
+use unlucky_core::download::blocking::block_on;
+
+// Modrinth 的根不再在本文件：URL 拼装与解析都在 `core::addon::online`，这里只留 CF 的
+// （它要 `X-API-KEY`，是 core 那一侧**故意**没接的那半）。
+/// 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 {
+    match query.source {
+        ContentSource::Modrinth => modrinth(env, query),
+        ContentSource::Curseforge => curseforge(env, query),
+    }
+}
+
+/// 详情 + 版本列表分派（M162）。
+pub(super) fn detail(
+    env: &HostEnv,
+    request: &ContentDetailRequest,
+) -> Result {
+    match request.source {
+        ContentSource::Modrinth => modrinth_detail(env, request),
+        ContentSource::Curseforge => Err(ContentFailure::unsupported(
+            "CurseForge 的详情/版本列表未接通（要 X-API-KEY 的文件端点）；先切到 Modrinth 源",
+        )),
+    }
+}
+
+// --------------------------------------------------------------- Modrinth
+
+fn modrinth(env: &HostEnv, query: &ContentQuery) -> Result {
+    let core_engine = engine::engine(env);
+    let transport = EngineTransport::new(&core_engine);
+    let client = Modrinth::new(&transport);
+    let page = block_on(client.search(&search_query(query))).map_err(failure_of)?;
+    Ok(ContentResults {
+        query: query.clone(),
+        hits: page.hits.iter().map(hit_of).collect(),
+        total: u32::try_from(page.total_hits).unwrap_or(0),
+        curseforge: curseforge_ready(),
+    })
+}
+
+fn modrinth_detail(
+    env: &HostEnv,
+    request: &ContentDetailRequest,
+) -> Result {
+    let core_engine = engine::engine(env);
+    let transport = EngineTransport::new(&core_engine);
+    let client = Modrinth::new(&transport);
+    let query = VersionQuery {
+        project: request.project.clone(),
+        game_version: request.game_version.clone(),
+        loader: request.loader.and_then(loader_facet).map(str::to_string),
+    };
+    // 项目详情 + 版本列表是**两次串行 GET**，包在**一次** `block_on` 里（宿主侧少一层阻塞边界，
+    // 也就少一次运行时进出——M165 登记的「单请求两次 block_on」在这里收掉）。
+    //
+    // 这不是嵌套 `block_on`：两段 `await` 依次跑在同一个 future 里，落在同一个常驻运行时
+    // （`core::download::blocking`）与同一个共享引擎上，连接池/限流照常复用。
+    // 失败语义不变：哪一步先失败就先返回，与拆成两次调用时的先后顺序一致，分类仍走 `failure_of`。
+    let (project, versions) = block_on(async {
+        let project = client.project(&request.project).await?;
+        let versions = client.versions(&query).await?;
+        Ok::<_, OnlineError>((project, versions))
+    })
+    .map_err(failure_of)?;
+    Ok(ContentDetail {
+        project: if project.id.is_empty() {
+            request.project.clone()
+        } else {
+            project.id
+        },
+        title: project.title,
+        description: project.description,
+        body: project.body,
+        versions: versions.iter().map(version_of).collect(),
+    })
+}
+
+/// DTO 检索条件 → core 的检索请求（**唯一**一处字段搬运）。
+fn search_query(query: &ContentQuery) -> SearchQuery {
+    SearchQuery {
+        text: query.text.clone(),
+        project_type: ContentType::parse(query.kind.modrinth_type()),
+        game_version: query.game_version.clone(),
+        loader: query.loader.and_then(loader_facet).map(str::to_string),
+        index: match query.sort {
+            crate::dto::ContentSort::Relevance => SortIndex::Relevance,
+            crate::dto::ContentSort::Downloads => SortIndex::Downloads,
+            crate::dto::ContentSort::Newest => SortIndex::Newest,
+            crate::dto::ContentSort::Updated => SortIndex::Updated,
+        },
+        limit: query.limit,
+        offset: query.offset,
+    }
+}
+
+/// core 的命中项 → DTO（缺字段一律给空/零，**不**编造）。
+fn hit_of(hit: &unlucky_core::addon::online::ProjectHit) -> ContentHit {
+    ContentHit {
+        id: hit.project_id.clone(),
+        slug: hit.slug.clone(),
+        title: hit.title.clone(),
+        summary: hit.description.clone(),
+        author: hit.author.clone(),
+        downloads: hit.downloads,
+        updated: date_part(&hit.updated),
+        source: ContentSource::Modrinth,
+        game_versions: hit.game_versions.clone(),
+        loaders: hit.loaders.clone(),
+        icon: hit.icon_url.clone(),
+    }
+}
+
+/// core 的版本 → DTO 的版本行（文件名/大小取 `primary` 那个）。
+fn version_of(version: &unlucky_core::addon::online::Version) -> ContentVersionView {
+    let file = version.primary_file();
+    ContentVersionView {
+        id: version.id.clone(),
+        name: version.name.clone(),
+        number: version.version_number.clone(),
+        kind: version.version_type.as_str().to_string(),
+        game_versions: version.game_versions.clone(),
+        loaders: version.loaders.clone(),
+        published: date_part(&version.date_published),
+        file_name: file
+            .map(|file| file.filename.clone())
+            .filter(|name| !name.trim().is_empty()),
+        file_size: file.map(|file| file.size).filter(|size| *size > 0),
+    }
+}
+
+/// core 的错误 → DTO 的失败大类（**一一映射，不重新判**）。
+pub(super) fn failure_of(error: OnlineError) -> ContentFailure {
+    let kind = match error.kind() {
+        OnlineErrorKind::NotConnected => ContentFailureKind::Offline,
+        OnlineErrorKind::NotFound => ContentFailureKind::NotFound,
+        OnlineErrorKind::Server => ContentFailureKind::Server,
+        OnlineErrorKind::Unsupported => ContentFailureKind::Unsupported,
+        OnlineErrorKind::Malformed | OnlineErrorKind::Io | OnlineErrorKind::Integrity => {
+            ContentFailureKind::Other
+        }
+    };
+    ContentFailure::new(kind, error.message().to_string())
+}
+
+// --------------------------------------------------------------- CurseForge
+
+fn curseforge(env: &HostEnv, query: &ContentQuery) -> Result {
+    let Some(key) = super::curseforge_key() else {
+        return Err(ContentFailure::unsupported(
+            "CurseForge 需要 API key（ULL_CF_API_KEY 未设置）",
+        ));
+    };
+    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())]).map_err(cf_failure)?;
+    let json: Value = serde_json::from_str(&body).map_err(|error| {
+        ContentFailure::new(
+            ContentFailureKind::Other,
+            format!("CurseForge 返回的不是合法 JSON：{error}"),
+        )
+    })?;
+    let hits = json
+        .get("data")
+        .and_then(Value::as_array)
+        .ok_or_else(|| {
+            ContentFailure::new(ContentFailureKind::Other, "CurseForge 返回里没有 data 字段")
+        })?
+        .iter()
+        .map(curseforge_hit)
+        .collect::>();
+
+    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,
+    })
+}
+
+/// CurseForge 的字符串错误 → 失败大类：只有「缺密钥」是 Unsupported，其余按站点/其它。
+fn cf_failure(reason: String) -> ContentFailure {
+    let kind = if reason.contains("ULL_CF_API_KEY") {
+        ContentFailureKind::Unsupported
+    } else if reason.contains("HTTP 503")
+        || reason.contains("HTTP 502")
+        || reason.contains("HTTP 500")
+    {
+        ContentFailureKind::Server
+    } else {
+        ContentFailureKind::Other
+    };
+    ContentFailure::new(kind, reason)
+}
+
+/// 一条 CF 命中项 → DTO。加载器只能从 `latestFilesIndexes[].modLoader` 的数字枚举反推。
+fn curseforge_hit(value: &Value) -> ContentHit {
+    let mut game_versions: Vec = Vec::new();
+    let mut loaders: Vec = 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 u64_of(value: &Value, key: &str) -> u64 {
+    value.get(key).and_then(Value::as_u64).unwrap_or(0)
+}
+
+/// 四条侧栏的常量表没被改乱（检索本身按 `kind` 走 facet）。
+#[must_use]
+pub(super) fn all_kinds() -> [crate::dto::ContentKind; 4] {
+    crate::dto::ContentKind::ALL
+}
+
+/// ISO-8601 → 日期部分（`2024-05-01T…` → `2024-05-01`；短串原样返回）。
+pub(super) fn date_part(raw: &str) -> String {
+    raw.get(..10).unwrap_or(raw).to_string()
+}
diff --git a/crates/presenter/src/host/addon/tests.rs b/crates/presenter/src/host/addon/tests.rs
new file mode 100644
index 0000000..9959ab7
--- /dev/null
+++ b/crates/presenter/src/host/addon/tests.rs
@@ -0,0 +1,385 @@
+//! 内容库宿主的守门测试（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, failure_of};
+use crate::dto::{ContentFailureKind, ContentKind};
+use unlucky_core::addon::online::{OnlineError, OnlineErrorKind};
+
+#[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"]
+    );
+}
+
+// ------------------------------------------------ M162：失败分类（core → DTO）
+
+/// core 的 `OnlineErrorKind` → DTO 的 `ContentFailureKind`：**一一映射，不重新判**。
+///
+/// 「没联网」是单独一类：页面据此画离线态（说「检查网络」），而不是画「换个关键词」。
+#[test]
+fn core_errors_map_to_dto_failure_kinds() {
+    let cases = [
+        (OnlineErrorKind::NotConnected, ContentFailureKind::Offline),
+        (OnlineErrorKind::NotFound, ContentFailureKind::NotFound),
+        (OnlineErrorKind::Server, ContentFailureKind::Server),
+        (
+            OnlineErrorKind::Unsupported,
+            ContentFailureKind::Unsupported,
+        ),
+        (OnlineErrorKind::Malformed, ContentFailureKind::Other),
+        (OnlineErrorKind::Io, ContentFailureKind::Other),
+        (OnlineErrorKind::Integrity, ContentFailureKind::Other),
+    ];
+    for (core, expected) in cases {
+        let failure = failure_of(OnlineError::new(core, "x"));
+        assert_eq!(failure.kind, expected, "{} 映射错了", core.as_str());
+    }
+    assert!(failure_of(OnlineError::offline("connect timed out")).is_offline());
+    // 详情/版本列表的文案要带出 core 的原话（不是二次包装的「出错了」）
+    assert_eq!(
+        failure_of(OnlineError::offline("connect timed out")).detail,
+        "connect timed out"
+    );
+}
+
+// ------------------------------------------------ M186：前置解析的两档失败与可重试名单
+
+use super::install::finish;
+use super::plan::{failure_of_plan, summary};
+use crate::dto::{InstallProgressView, InstallStage};
+use unlucky_core::addon::online::{
+    DependencyFailure, DependencyPlan, FailureKind, PlannedNode, ResolveRequest, SkipReason,
+    SkippedNode, UnresolvedRequired, VersionFile,
+};
+
+fn node(project: &str, file: &str, depth: u8, required_by: &[&str]) -> PlannedNode {
+    PlannedNode {
+        project: project.to_string(),
+        requested_as: project.to_string(),
+        version_id: format!("ver-{project}"),
+        version_name: project.to_string(),
+        version_number: "1.0".to_string(),
+        file: VersionFile {
+            url: format!("https://cdn.modrinth.com/data/{project}/1.0/{file}"),
+            filename: file.to_string(),
+            size: 1024,
+            ..VersionFile::default()
+        },
+        depth,
+        required_by: required_by
+            .iter()
+            .map(|parent| (*parent).to_string())
+            .collect(),
+    }
+}
+
+fn failure(
+    project: &str,
+    kind: FailureKind,
+    cause: Option,
+    message: &str,
+) -> DependencyFailure {
+    DependencyFailure {
+        requested_as: project.to_string(),
+        required_by: vec!["AANobbMI".to_string()],
+        depth: 1,
+        kind,
+        cause,
+        message: message.to_string(),
+    }
+}
+
+fn plan(
+    failures: Vec,
+    nodes: Vec,
+    skipped: Vec,
+) -> DependencyPlan {
+    DependencyPlan {
+        request: ResolveRequest::single("sodium"),
+        nodes,
+        skipped,
+        failures,
+        truncated: Vec::new(),
+        unresolved_required: Vec::new(),
+    }
+}
+
+/// 全是「不兼容」时：说换版本/加载器，而不是「下载失败」，并且照样给重试名单。
+#[test]
+fn an_incompatible_only_plan_is_not_reported_as_a_download_failure() {
+    let plan = plan(
+        vec![failure(
+            "P7dR8mSH",
+            FailureKind::Incompatible,
+            None,
+            "没有匹配所选游戏版本/加载器（1.20.1 / fabric）的版本",
+        )],
+        vec![node("AANobbMI", "sodium.jar", 0, &[])],
+        Vec::new(),
+    );
+    let failure = failure_of_plan(&plan, 0).expect("有失败就该给一条");
+    // M191：「不兼容」有了自己的大类（以前借 `Unsupported`，与「缺密钥」共用一档）
+    assert_eq!(failure.kind, ContentFailureKind::Incompatible);
+    assert!(failure.kind.is_incompatible());
+    assert!(!failure.is_offline());
+    assert!(failure.detail.contains("不兼容所选版本/加载器 1 个"));
+    assert!(failure.detail.contains("可只重试这 1 个：P7dR8mSH"));
+    assert!(!failure.detail.contains("下载失败"), "{}", failure.detail);
+    assert!(
+        !failure.detail.contains("取不到"),
+        "两档不许混：{}",
+        failure.detail
+    );
+}
+
+/// 两档同时出现时：两段都写，大类按「用户接下来该做什么」选（查无此项 > 不兼容）。
+#[test]
+fn a_mixed_plan_keeps_both_buckets_and_picks_the_actionable_kind() {
+    let plan = plan(
+        vec![
+            failure(
+                "P7dR8mSH",
+                FailureKind::Incompatible,
+                None,
+                "没有匹配的版本",
+            ),
+            failure(
+                "1eAoo2KR",
+                FailureKind::Unreachable,
+                Some(OnlineErrorKind::NotFound),
+                "取版本失败（online_not_found）：HTTP 404",
+            ),
+        ],
+        Vec::new(),
+        Vec::new(),
+    );
+    let failure = failure_of_plan(&plan, 0).expect("有失败就该给一条");
+    assert_eq!(failure.kind, ContentFailureKind::NotFound);
+    assert!(failure.detail.contains("不兼容所选版本/加载器 1 个"));
+    assert!(failure.detail.contains("取不到（网络 / 项目不存在）1 个"));
+    assert!(failure.detail.contains("可只重试这 2 个"));
+}
+
+/// 没网那一档：大类是离线（页面据此画「检查网络」而不是「换个关键词」）。
+#[test]
+fn an_offline_jump_wins_over_everything_else() {
+    let plan = plan(
+        vec![
+            failure(
+                "P7dR8mSH",
+                FailureKind::Incompatible,
+                None,
+                "没有匹配的版本",
+            ),
+            failure(
+                "1eAoo2KR",
+                FailureKind::Unreachable,
+                Some(OnlineErrorKind::NotConnected),
+                "连不上 api.modrinth.com",
+            ),
+        ],
+        Vec::new(),
+        Vec::new(),
+    );
+    let failure = failure_of_plan(&plan, 0).expect("有失败就该给一条");
+    assert_eq!(failure.kind, ContentFailureKind::Offline);
+    assert!(failure.is_offline());
+}
+
+/// 全装成的那句话要点出「含 N 个前置」与「跳过 M 个已存在」。
+#[test]
+fn the_success_message_counts_dependencies_and_skipped_files() {
+    let plan = plan(
+        Vec::new(),
+        vec![
+            node("AANobbMI", "sodium.jar", 0, &[]),
+            node("P7dR8mSH", "fabric-api.jar", 1, &["AANobbMI"]),
+        ],
+        vec![SkippedNode {
+            project: "1eAoo2KR".to_string(),
+            requested_as: "1eAoo2KR".to_string(),
+            file_name: "yacl.jar".to_string(),
+            depth: 2,
+            required_by: vec!["P7dR8mSH".to_string()],
+            reason: SkipReason::AlreadyPresent,
+        }],
+    );
+    assert!(failure_of_plan(&plan, 2).is_none());
+    let installed = plan.nodes.clone();
+    let message = summary(&plan, &installed);
+    assert!(
+        message.contains("装了 2 个文件（含 1 个前置）"),
+        "{message}"
+    );
+    // 「为什么装」：前置那句要带出要求它的项目
+    assert!(
+        message.contains("fabric-api.jar（前置，被 AANobbMI 要求）"),
+        "{message}"
+    );
+    assert!(message.contains("跳过 1 个（目录里已存在，没有重复下载）：yacl.jar"));
+}
+
+/// 扫目录只认文件、不认子目录（子目录不是 jar，混进来会让去重误判）。
+#[test]
+fn present_files_lists_only_files_in_the_target_directory() {
+    let dir = std::env::temp_dir().join(format!("ull-m186-present-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    std::fs::create_dir_all(dir.join("nested")).expect("建临时目录");
+    std::fs::write(dir.join("sodium.jar"), b"x").expect("写文件");
+    std::fs::write(dir.join("yacl.jar.disabled"), b"x").expect("写文件");
+    let mut names: Vec = super::plan::present_files(&dir)
+        .into_iter()
+        .map(|file| file.name)
+        .collect();
+    names.sort();
+    assert_eq!(names, ["sodium.jar", "yacl.jar.disabled"]);
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+// ------------------------------------------------ M186 r1：完成态进度、下载失败上下文、无地址前置
+
+/// 完成态不许把进度倒回 `1/N`（r1 P2-3：这里曾写死 `files_done = 1`）。
+#[test]
+fn finishing_aligns_the_terminal_progress_with_the_total() {
+    let mut progress = InstallProgressView {
+        files_total: 3,
+        files_done: 3,
+        stage: InstallStage::Downloading,
+        ..InstallProgressView::new()
+    };
+    finish(&mut progress);
+    assert_eq!(progress.stage, InstallStage::Done);
+    assert_eq!(progress.files_done, progress.files_total);
+    assert_eq!(progress.ratio(), 1.0, "装完了条必须满");
+
+    // 全部跳过（total = 0）时也不许变成 1/0
+    let mut skipped_all = InstallProgressView {
+        files_total: 0,
+        ..InstallProgressView::new()
+    };
+    finish(&mut skipped_all);
+    assert_eq!(skipped_all.files_done, 0);
+    assert_eq!(skipped_all.stage, InstallStage::Done);
+}
+
+/// 下载阶段的失败也要带上下文：已装几个 + 缺的是谁的前置 + 可只重试谁。
+#[test]
+fn a_download_failure_keeps_the_already_installed_context() {
+    let plan = plan(
+        vec![failure(
+            "P7dR8mSH",
+            FailureKind::Unreachable,
+            Some(OnlineErrorKind::NotConnected),
+            "下载 fabric-api.jar 失败（online_not_connected）：连不上 cdn.modrinth.com",
+        )],
+        vec![node("AANobbMI", "sodium.jar", 0, &[])],
+        Vec::new(),
+    );
+    let failure = failure_of_plan(&plan, 1).expect("有失败就该给一条");
+    assert_eq!(failure.kind, ContentFailureKind::Offline);
+    assert!(
+        failure.detail.contains("已装入 1 个文件（已下好的不回滚）"),
+        "{}",
+        failure.detail
+    );
+    assert!(failure.detail.contains("取不到（网络 / 项目不存在）1 个"));
+    assert!(failure.detail.contains("可只重试这 1 个：P7dR8mSH"));
+}
+
+/// 只有版本 id、没有项目 id 的必备前置：既装不了，也不许静默吞掉。
+#[test]
+fn a_required_dependency_without_a_project_id_is_reported() {
+    let mut plan = plan(
+        Vec::new(),
+        vec![node("AANobbMI", "sodium.jar", 0, &[])],
+        Vec::new(),
+    );
+    plan.unresolved_required = vec![UnresolvedRequired {
+        parent: "AANobbMI".to_string(),
+        version_id: Some("ver-embedded".to_string()),
+        file_name: Some("embedded-lib.jar".to_string()),
+    }];
+    let installed = plan.nodes.clone();
+    let message = summary(&plan, &installed);
+    assert!(
+        message.contains("有 1 条必备前置只给了版本/文件名、没有项目 id，无法自动解析：ver-embedded（被 AANobbMI 要求）"),
+        "{message}"
+    );
+}
+
+// M191：「只重试这些」的名单与重试路径（按主题分卷，父文件已贴 400 行硬线）
+mod retry;
diff --git a/crates/presenter/src/host/addon/tests/retry.rs b/crates/presenter/src/host/addon/tests/retry.rs
new file mode 100644
index 0000000..d4429a5
--- /dev/null
+++ b/crates/presenter/src/host/addon/tests/retry.rs
@@ -0,0 +1,332 @@
+//! M191：「只重试这些」的两档名单 + 真重试路径（`super` 的用例按主题分卷，这一卷专管重试）。
+//!
+//! 三条判据对应的变异守门在各自的文档里写清了「改了什么这条会红」。
+
+use super::{failure, node, plan};
+use crate::dto::{InstallFailureKind, InstallFailureView};
+use crate::host::addon::plan::{
+    failure_of_plan, forget, names_for_incompatible, remember, remembered, retry_items, retry_plan,
+    retry_request, Root,
+};
+use unlucky_core::addon::online::{DependencyPlan, FailureKind, OnlineErrorKind, PresentFile};
+
+/// 一份「根装好了、两个前置失败」的计划（重试路径的典型输入）。
+fn plan_with_two_tier_failures() -> DependencyPlan {
+    plan(
+        vec![
+            failure(
+                "P7dR8mSH",
+                FailureKind::Incompatible,
+                None,
+                "没有匹配的版本",
+            ),
+            failure(
+                "1eAoo2KR",
+                FailureKind::Unreachable,
+                Some(OnlineErrorKind::NotFound),
+                "取版本失败（online_not_found）：HTTP 404",
+            ),
+        ],
+        vec![node("AANobbMI", "sodium.jar", 0, &[])],
+        Vec::new(),
+    )
+}
+
+/// 可重试名单：**两档分在类型上**，每条的 project 就是重试会发出去的那个键。
+///
+/// 抓得住：把 `Incompatible` 并进 `Unreachable`（两档合成一档）⇒ 这条立刻红。
+#[test]
+fn the_retry_list_keeps_the_two_tiers_apart() {
+    let items = retry_items(
+        &plan_with_two_tier_failures(),
+        Root {
+            id: "AANobbMI",
+            title: "Sodium",
+        },
+        &Vec::new(),
+    );
+    assert_eq!(items.len(), 2);
+    assert_eq!(
+        items
+            .iter()
+            .map(|item| (item.project.as_str(), item.kind))
+            .collect::>(),
+        [
+            ("P7dR8mSH", InstallFailureKind::Incompatible),
+            ("1eAoo2KR", InstallFailureKind::Unreachable),
+        ]
+    );
+    // 两档的名字**必须不同**（界面拿它分组、也是日志/用例里的稳定 id）
+    assert_ne!(
+        InstallFailureKind::Incompatible.as_str(),
+        InstallFailureKind::Unreachable.as_str()
+    );
+}
+
+/// 全成功 ⇒ 名单是空的（界面据此**不渲染**那条入口，而不是画一个灰按钮）。
+#[test]
+fn a_clean_plan_offers_nothing_to_retry() {
+    let clean = plan(
+        Vec::new(),
+        vec![node("AANobbMI", "sodium.jar", 0, &[])],
+        Vec::new(),
+    );
+    assert!(retry_items(
+        &clean,
+        Root {
+            id: "AANobbMI",
+            title: "Sodium",
+        },
+        &Vec::new(),
+    )
+    .is_empty());
+    assert!(failure_of_plan(&clean, 1).is_none());
+}
+
+/// 「只重试这些」**只请求失败的那几个项目**：根项目不再发一次，解析只跑一次。
+///
+/// 这条是 M191 的变异守门①：把 `retry_request()` 换成「重新装根」（`ResolveRequest::single(root)`
+/// 或 `plan.request.clone()`）⇒ `roots` 里会出现 `AANobbMI`，这条红。
+#[test]
+fn retrying_asks_for_the_failed_projects_only() {
+    let plan = plan_with_two_tier_failures();
+    let present = vec![PresentFile::new("sodium.jar")];
+    let mut seen: Vec = Vec::new();
+    let _ = retry_plan(&plan, present, |request| {
+        seen.push(request.clone());
+        // 假解析器：把请求的根原样回成节点（用例只关心「请求了谁、请求了几次」）
+        DependencyPlan {
+            request: request.clone(),
+            nodes: request
+                .roots
+                .iter()
+                .map(|root| node(root, "x.jar", 0, &[]))
+                .collect(),
+            skipped: Vec::new(),
+            failures: Vec::new(),
+            truncated: Vec::new(),
+            unresolved_required: Vec::new(),
+        }
+    });
+
+    assert_eq!(seen.len(), 1, "重试只发一次解析，请求数不许放大");
+    let roots = &seen[0].roots;
+    assert_eq!(roots, &["P7dR8mSH".to_string(), "1eAoo2KR".to_string()]);
+    assert!(
+        !roots.contains(&"AANobbMI".to_string()),
+        "根项目已装好，重试不许再解它：{roots:?}"
+    );
+    // `present` 重新扫过（这一轮新落盘的文件要在里面，否则会被当成「还没有」再下一份）
+    assert_eq!(seen[0].present, vec![PresentFile::new("sodium.jar")]);
+    // 过滤条件沿用上次那份
+    assert_eq!(seen[0].game_version, plan.request.game_version);
+}
+
+/// 计划被记住 / 忘掉：键是「host + 实例」，成功之后不该留可重试的记录。
+#[test]
+fn the_last_failed_plan_is_remembered_per_instance() {
+    let root = std::env::temp_dir().join(format!("ull-m191-retry-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&root);
+    let env = crate::host::HostEnv::at_root(&root);
+    assert!(remembered(&env, "survival").is_none());
+
+    let plan = plan_with_two_tier_failures();
+    let dir = root.join(".minecraft/mods");
+    remember(&env, "survival", &dir, "AANobbMI", "Sodium", &plan);
+    let saved = remembered(&env, "survival").expect("记住了这一次");
+    assert_eq!(saved.dir, dir);
+    // 原始根 id + 显示名跟着计划一起记住：重试时面板头用它，判「是不是根」也用它（r2 P2-2）
+    assert_eq!(saved.root, "AANobbMI");
+    assert_eq!(saved.title, "Sodium");
+    assert_eq!(saved.plan.failures.len(), 2);
+    // 别的实例不受影响（同一台机器上装过两个实例）
+    assert!(remembered(&env, "modded").is_none());
+
+    // 重试请求从「记住的计划」里取：仍然只含失败项
+    let request = retry_request(&saved.plan, Vec::new());
+    assert_eq!(request.roots, vec!["P7dR8mSH", "1eAoo2KR"]);
+
+    forget(&env, "survival");
+    assert!(remembered(&env, "survival").is_none());
+    let _ = std::fs::remove_dir_all(&root);
+}
+
+/// DTO 名单与「真重试请求」是**同一份**：界面画的 N 个 = 重试会请求的 N 个。
+///
+/// 抓得住：界面名单自己另拼一份（多列/少列一个项目）⇒ 这条红。
+#[test]
+fn the_dto_list_is_exactly_what_the_retry_request_asks_for() {
+    let plan = plan_with_two_tier_failures();
+    let items: Vec = retry_items(
+        &plan,
+        Root {
+            id: "AANobbMI",
+            title: "Sodium",
+        },
+        &Vec::new(),
+    );
+    let request = retry_request(&plan, Vec::new());
+    assert_eq!(
+        items
+            .iter()
+            .map(|item| item.project.clone())
+            .collect::>(),
+        request.roots
+    );
+}
+
+/// **P2-1 的守门**：面板上写的是可读名，不是裸项目 id。
+///
+/// 三个来源各一条（`plan::label_of` 的三种情况），而且都必须**语言中立**（站点标题 / 文件名，
+/// 不是 core 的中文散文）：
+///
+/// | 项 | 情况 | 期望那一行 |
+/// |---|---|---|
+/// | 根项目 | 它自己失败 | `Sodium (AANobbMI)` —— 名字来自请求的 `title` |
+/// | 前置 | 下载失败（计划里有节点） | `fabric-api.jar (P7dR8mSH)` —— 名字来自文件名 |
+/// | 前置 | 解析阶段 404（没有节点） | `1eAoo2KR` —— 拿不到名，只画 id（合理兜底） |
+///
+/// 变异守门：把 `label_of` 的标签置空（或 `retry_items` 传空串）⇒ 这条红。
+#[test]
+fn the_retry_list_shows_a_readable_name_not_just_the_project_id() {
+    let mut plan = plan(
+        vec![
+            // 根项目自己失败（下载失败）：requested_as 与 roots[0] 相同
+            failure(
+                "AANobbMI",
+                FailureKind::Unreachable,
+                Some(OnlineErrorKind::NotConnected),
+                "下载 sodium.jar 失败（online_not_connected）：连不上 cdn.modrinth.com",
+            ),
+            // 前置下载失败：计划里有它的节点 ⇒ 用文件名
+            failure(
+                "P7dR8mSH",
+                FailureKind::Unreachable,
+                Some(OnlineErrorKind::NotConnected),
+                "下载 fabric-api.jar 失败（online_not_connected）：连不上 cdn.modrinth.com",
+            ),
+            // 前置解析 404：没有节点、也不是根 ⇒ 没有名字可显示
+            failure(
+                "1eAoo2KR",
+                FailureKind::Unreachable,
+                Some(OnlineErrorKind::NotFound),
+                "取版本失败（online_not_found）：HTTP 404",
+            ),
+        ],
+        vec![
+            node("AANobbMI", "sodium-fabric-0.6.0.jar", 0, &[]),
+            node("P7dR8mSH", "fabric-api.jar", 1, &["AANobbMI"]),
+        ],
+        Vec::new(),
+    );
+    // 根必须是请求里的那个键（`plan::request` 只放一个根）
+    plan.request = unlucky_core::addon::online::ResolveRequest::single("AANobbMI");
+
+    let items = retry_items(
+        &plan,
+        Root {
+            id: "AANobbMI",
+            title: "Sodium",
+        },
+        &Vec::new(),
+    );
+    let lines: Vec = items.iter().map(InstallFailureView::line).collect();
+    assert_eq!(
+        lines,
+        vec![
+            "Sodium (AANobbMI)".to_string(),
+            "fabric-api.jar (P7dR8mSH)".to_string(),
+            // 拿不到名的那一档：只画 id，不编造、也不拿 core 的中文 message 顶上
+            "1eAoo2KR".to_string(),
+        ]
+    );
+    // 标签是语言中立的：站点标题/文件名，不是 core 的中文散文
+    assert!(!items[0].label.contains("下载"), "{}", items[0].label);
+    assert!(!items[1].label.contains("失败"), "{}", items[1].label);
+}
+
+/// **r2 P2-2 的守门**：重试那一轮，第一条失败项**不许**被贴成原根项目的名字。
+///
+/// 形状就是复审给的那个：重试轮的 plan 来自 `retry_request()`，它的 `roots` 是上一轮的失败名单
+/// （第一个是**前置**），而 `root` 记的是原始根 `AANobbMI / Sodium`。老实现拿 `roots.first()`
+/// 判「是不是根」⇒ 画出 `Sodium (P7dR8mSH)`；现在按 id 比 ⇒ 第一条是它自己的名字（或 id）。
+///
+/// 变异守门：把 `label_of` 的判据换回 `plan.request.roots.first()` ⇒ 这条红。
+#[test]
+fn the_retry_round_does_not_paste_the_root_title_onto_a_dependency() {
+    let mut plan = plan_with_two_tier_failures();
+    // 重试请求：roots = 上一轮的失败名单
+    plan.request = unlucky_core::addon::online::ResolveRequest {
+        roots: vec!["P7dR8mSH".to_string(), "1eAoo2KR".to_string()],
+        ..plan.request.clone()
+    };
+    // 重试轮里没有被安装的节点（上一轮装好的不会再进计划），于是标签只能来自 id
+    let items = retry_items(
+        &plan,
+        Root {
+            id: "AANobbMI",
+            title: "Sodium",
+        },
+        &Vec::new(),
+    );
+    let lines: Vec = items.iter().map(InstallFailureView::line).collect();
+    assert_eq!(lines, vec!["P7dR8mSH".to_string(), "1eAoo2KR".to_string()]);
+    assert!(
+        !lines.iter().any(|line| line.contains("Sodium")),
+        "重试轮把根的标题贴到前置上了：{lines:?}"
+    );
+}
+
+/// **r2 P2-1 续的守门**：不兼容档要显示项目名，不是 id。
+///
+/// 那一档的项目**确实存在**（站点只是没有匹配目标版本/加载器的条目），所以失败路径上值得
+/// 现取一次名字。变异守门：把这次获取去掉（`names` 传空）⇒ 第一条退回 `P7dR8mSH`，这条红。
+#[test]
+fn an_incompatible_item_shows_the_project_name_once_it_is_known() {
+    let plan = plan_with_two_tier_failures();
+    let root = Root {
+        id: "AANobbMI",
+        title: "Sodium",
+    };
+    // 生产路径：`names_for_incompatible` 用注入的查询取名字（这里模拟"站点有回应"）
+    let names = names_for_incompatible(&plan, |id| {
+        (id == "P7dR8mSH").then(|| "Entity Culling".to_string())
+    });
+    assert_eq!(
+        names,
+        vec![("P7dR8mSH".to_string(), "Entity Culling".to_string())],
+        "只给不兼容档取名字（404 那条不发请求）"
+    );
+
+    let items = retry_items(&plan, root, &names);
+    assert_eq!(items[0].line(), "Entity Culling (P7dR8mSH)");
+    // 「取不到」那档不受影响：没有节点、没有名字 ⇒ 只画 id
+    assert_eq!(items[1].line(), "1eAoo2KR");
+}
+
+/// **降级**：取名字本身失败，不许把安装结果搞坏，也不许编名字——照旧画 id。
+///
+/// 变异守门：让 `project_title` 的错误往外冒（`?` / `expect`）⇒ 这条连编译都过不了，
+/// 或者（退回成「拿不到就 panic」）在这里红。
+#[test]
+fn a_failed_name_lookup_falls_back_to_the_id_without_breaking_anything() {
+    let plan = plan_with_two_tier_failures();
+    // 站点 404 / 没网 / 坏响应：`lookup` 全是 `None`
+    let names = names_for_incompatible(&plan, |_| None);
+    assert!(names.is_empty(), "{names:?}");
+    let items = retry_items(
+        &plan,
+        Root {
+            id: "AANobbMI",
+            title: "Sodium",
+        },
+        &names,
+    );
+    assert_eq!(items[0].line(), "P7dR8mSH", "取不到名字就画 id，不编造");
+    // 拿到空串（站点给了个空标题）同样不算名字
+    let blank = names_for_incompatible(&plan, |_| Some("   ".to_string()));
+    assert!(blank.is_empty(), "{blank:?}");
+}
+
+// r3 复审 p2：生产接线与降级守卫（按主题分卷，父文件已贴 400 行硬线）
+mod wire;
diff --git a/crates/presenter/src/host/addon/tests/retry/wire.rs b/crates/presenter/src/host/addon/tests/retry/wire.rs
new file mode 100644
index 0000000..6cfc285
--- /dev/null
+++ b/crates/presenter/src/host/addon/tests/retry/wire.rs
@@ -0,0 +1,115 @@
+//! r3 复审 p2：**生产接线**与**降级**的守卫（`super` 按主题分卷）。
+//!
+//! 这一卷的用例驱动的是生产那个 `collect`（不是它的复制品）：假下载器 + 假取名字器，
+//! 于是「失败路径真的去取了不兼容档的名字」这件事在没有网络的用例里也能钉住。
+
+use std::sync::atomic::AtomicBool;
+use std::sync::Mutex;
+
+use unlucky_core::addon::online::{
+    ArtifactFetcher, FetchArgs, OnlineError, OnlineErrorKind, OnlineFuture,
+};
+
+use super::plan_with_two_tier_failures;
+use crate::dto::{
+    ContentInstallRequest, ContentSource, InstallFailureKind, InstallProgressView, LoaderKind,
+};
+use crate::host::addon::install::{collect, Placement, Ports};
+use crate::host::addon::plan::Root;
+
+/// 假下载器：一律「写一行字节成功」——本组用例只关心收口那一半（下载阶段另有自己的用例）。
+struct QuietFetcher;
+
+impl ArtifactFetcher for QuietFetcher {
+    fn fetch<'a>(&'a self, args: FetchArgs<'a>) -> OnlineFuture<'a, Result> {
+        Box::pin(async move {
+            std::fs::write(args.dest, b"jar").map_err(|error| {
+                OnlineError::new(OnlineErrorKind::Io, format!("写盘失败：{error}"))
+            })?;
+            Ok(4)
+        })
+    }
+}
+
+fn request_for(instance: &str) -> ContentInstallRequest {
+    ContentInstallRequest {
+        project: "AANobbMI".to_string(),
+        title: "Sodium".to_string(),
+        kind: crate::dto::ContentKind::Mod,
+        source: ContentSource::Modrinth,
+        instance: instance.to_string(),
+        game_version: "1.20.1".to_string(),
+        loader: LoaderKind::Fabric,
+        retry: false,
+    }
+}
+
+/// **接线层守卫**（r3 复审 p2 第 1 条）：安装失败路径**真的**去取了不兼容档的名字。
+///
+/// 这条驱动的是生产那个 `collect`（不是它的复制品）：假下载器 + 假取名字器，
+/// 于是一份「一个文件下成功 + 一个不兼容前置 + 一条 404」的计划跑完后：
+///
+/// - 不兼容那条**拿到了名字**（`Entity Culling`）；
+/// - 取名字器只被**不兼容**那条问过一次（404 那条不发请求）。
+///
+/// 变异守门：把 `collect` 里那行 `names_for_incompatible(...)` 删掉/短路（传空名单）⇒ 红。
+#[test]
+fn the_failed_install_path_really_fetches_names_for_the_incompatible_items() {
+    let root = std::env::temp_dir().join(format!("ull-m191-wire-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&root);
+    let dir = root.join(".minecraft/mods");
+    std::fs::create_dir_all(&dir).expect("建目录");
+    let env = crate::host::HostEnv::at_root(&root);
+
+    let plan = plan_with_two_tier_failures();
+    let asked: Mutex> = Mutex::new(Vec::new());
+    let title = |id: &str| {
+        asked.lock().expect("锁没中毒").push(id.to_string());
+        (id == "P7dR8mSH").then(|| "Entity Culling".to_string())
+    };
+    let fetcher = QuietFetcher;
+    let ports = Ports {
+        env: &env,
+        fetcher: &fetcher,
+        title: &title,
+    };
+    let (tx, _rx) = crate::host::job::channel();
+    let cancel = AtomicBool::new(false);
+    let mut progress = InstallProgressView::new();
+    let request = request_for("survival");
+
+    let result = collect(
+        &ports,
+        &request,
+        plan,
+        Placement {
+            dir: &dir,
+            root: Root {
+                id: "AANobbMI",
+                title: "Sodium",
+            },
+        },
+        &cancel,
+        &mut progress,
+        &tx,
+        1,
+    );
+
+    assert!(result.is_err(), "有失败项就该回一条失败");
+    let incompatible = progress
+        .retry
+        .iter()
+        .find(|item| item.kind == InstallFailureKind::Incompatible)
+        .expect("不兼容档要在名单里");
+    assert_eq!(
+        incompatible.line(),
+        "Entity Culling (P7dR8mSH)",
+        "失败路径没有把取到的名字贴上去"
+    );
+    assert_eq!(
+        *asked.lock().expect("锁没中毒"),
+        vec!["P7dR8mSH".to_string()],
+        "只该给不兼容档取名字（404 那条不发请求）"
+    );
+    let _ = std::fs::remove_dir_all(&root);
+}
diff --git a/crates/presenter/src/host/adopt.rs b/crates/presenter/src/host/adopt.rs
new file mode 100644
index 0000000..6658cd2
--- /dev/null
+++ b/crates/presenter/src/host/adopt.rs
@@ -0,0 +1,261 @@
+//! 「导入已有版本」的宿主侧（M223 GUIADOPT）：扫描 / 预检 / 确认三条后台线程。
+//!
+//! 能力全在 core（`unlucky_core::game::adopt`，M221）：本模块只做三件事——**起线程、翻 DTO、
+//! 按代次回流**。这里不重新判定任何东西：能不能登记、落到哪个运行目录、有哪些问题，全部由 core
+//! 说了算，本模块逐字段照搬（[`scan_view`] / [`plan_view`] / [`done_view`] / [`failure_view`]）。
+//!
+//! ## 三个命令与写盘面
+//!
+//! | 命令 | core 调用 | 写盘 |
+//! |---|---|---|
+//! | [`AdoptCommand::Scan`] | `adopt::scan` | 零 |
+//! | [`AdoptCommand::Preview`] | `adopt::plan` | 零（预检就是 core 的 dry-run） |
+//! | [`AdoptCommand::Confirm`] | `adopt::adopt` | 实例设置 + `profiles.json`（+ 缺省运行目录） |
+//!
+//! 预检与确认走**同一个** `AdoptRequestView`：页面在预检拿到落点与后果原文，用户点确认时把
+//! **同一份请求**发回来（不是「预检 A、写 B」）。这也是「运行目录只认回程」的实现方式——
+//! 页面从头到尾没有机会自己派生一个目录名。
+//!
+//! ## 代次：为什么要它
+//!
+//! 三条命令各起一条线程，用户可能连点（扫完再扫、预检后改目标再预检、失败后关面板）。
+//! 每条线程带一个代次回来，`adopt_epoch` 只认**最新**那一条：关面板（[`AdoptCommand::Dismiss`]）
+//! 也会把代次 +1，于是「点了关闭，两秒后扫描结果又把面板点亮」这种旧病不会发生
+//! （它与 M105 安装取消、M113 导入取消是同一套做法）。
+//!
+//! ## 不做什么
+//!
+//! - **不自己派生运行目录**：`run_dir` 只从 `plan`/`adopt` 的返回里取（缺省档可能带 `-2` 后缀）；
+//! - **不自己拼后果话术**：`notes` 原样来自 core 的 `target_notes()`，与 CLI 打的是同一句；
+//! - **不折叠问题**：`problems[]` 逐条搬进 [`AdoptFailureView`]，一条都不省。
+
+use unlucky_core::game::adopt::{
+    self, AdoptCandidate, AdoptError, AdoptOutcome, AdoptPlan, AdoptProblem, AdoptRequest,
+    AdoptTarget,
+};
+use unlucky_core::game::install::instance::Isolation;
+use unlucky_core::launch::time::{format_rfc3339_millis, now};
+
+use crate::dto::{
+    AdoptCandidateView, AdoptCommand, AdoptDoneView, AdoptEvent, AdoptFailureView,
+    AdoptIsolationView, AdoptPlanView, AdoptProblemView, AdoptRequestView, AdoptScanView,
+    AdoptTargetView, CoreEvent,
+};
+
+use super::env::HostEnv;
+use super::job::{self, HostTask, JobSender};
+use super::CoreHost;
+
+/// 后台那一步是「只看不写」还是「真的写」。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(super) enum Mode {
+    /// `adopt::plan`（预检，零写盘）
+    Preview,
+    /// `adopt::adopt`（真写）
+    Confirm,
+}
+
+impl CoreHost {
+    /// 作废在飞的 adopt 结果，返回新代次（每条命令都调它，见模块文档「代次」一节）。
+    fn next_adopt_epoch(&mut self) -> u64 {
+        self.adopt_epoch = self.adopt_epoch.wrapping_add(1);
+        self.adopt_epoch
+    }
+
+    /// `AppCommand::Adopt` 的落点（M223）。
+    ///
+    /// 每条命令都先把代次 +1：这一条之后回来的旧结果一律被 [`Self::handle_adopt`] 丢掉。
+    pub(super) fn adopt(&mut self, command: AdoptCommand) {
+        match command {
+            AdoptCommand::Scan => {
+                let epoch = self.next_adopt_epoch();
+                spawn_scan(self.env.clone(), self.tx.clone(), epoch);
+            }
+            AdoptCommand::Preview(request) => {
+                let epoch = self.next_adopt_epoch();
+                spawn_adopt(
+                    self.env.clone(),
+                    self.tx.clone(),
+                    *request,
+                    Mode::Preview,
+                    epoch,
+                );
+            }
+            AdoptCommand::Confirm(request) => {
+                let epoch = self.next_adopt_epoch();
+                spawn_adopt(
+                    self.env.clone(),
+                    self.tx.clone(),
+                    *request,
+                    Mode::Confirm,
+                    epoch,
+                );
+            }
+            AdoptCommand::Dismiss => {
+                // 关面板 = 作废在飞的一切（否则迟到的扫描结果会把面板重新点亮）
+                self.next_adopt_epoch();
+                self.send(CoreEvent::Adopt(Box::new(AdoptEvent::Cleared)));
+            }
+        }
+    }
+
+    /// 后台线程的回流落点：代次不符就丢（见模块文档「代次」一节）。
+    ///
+    /// 登记成功之后补一次实例快照刷新：新实例必须**这一拍就出现在实例列表里**，
+    /// 而不是等用户手点刷新（否则「导入了但看不见」）。
+    pub(super) fn handle_adopt(&mut self, event: AdoptEvent, epoch: u64) {
+        if epoch != self.adopt_epoch {
+            return;
+        }
+        let registered = matches!(event, AdoptEvent::Done(_));
+        self.send(CoreEvent::Adopt(Box::new(event)));
+        if registered {
+            self.refresh_instances();
+        }
+    }
+}
+
+/// 扫描当前游戏根的 `versions/`（只读）。
+pub(super) fn spawn_scan(env: HostEnv, tx: JobSender, epoch: u64) {
+    job::spawn("adopt-scan", move || {
+        let event = match adopt::scan(&env.game, &env.layout) {
+            Ok(scan) => AdoptEvent::Scan(Box::new(AdoptScanView {
+                versions_dir: scan.versions_dir.clone(),
+                candidates: scan.candidates.iter().map(candidate_view).collect(),
+            })),
+            // 读目录失败也是**具名**失败（断链的 versions 联接 / 权限），不降级成空列表
+            Err(error) => AdoptEvent::Failed(Box::new(failure_view(error))),
+        };
+        let _ = tx.send(HostTask::Adopt {
+            event: Box::new(event),
+            epoch,
+        });
+    });
+}
+
+/// 预检（零写盘）或确认登记。
+pub(super) fn spawn_adopt(
+    env: HostEnv,
+    tx: JobSender,
+    request: AdoptRequestView,
+    mode: Mode,
+    epoch: u64,
+) {
+    job::spawn("adopt", move || {
+        let request = core_request(request);
+        let event = match mode {
+            Mode::Preview => match adopt::plan(&env.game, &env.layout, &request) {
+                Ok(plan) => AdoptEvent::Planned(Box::new(plan_view(plan))),
+                Err(error) => AdoptEvent::Failed(Box::new(failure_view(error))),
+            },
+            Mode::Confirm => match adopt::adopt(&env.game, &env.layout, &request) {
+                Ok(outcome) => AdoptEvent::Done(Box::new(done_view(outcome))),
+                Err(error) => AdoptEvent::Failed(Box::new(failure_view(error))),
+            },
+        };
+        let _ = tx.send(HostTask::Adopt {
+            event: Box::new(event),
+            epoch,
+        });
+    });
+}
+
+/// 视图请求 → core 请求（`created_at` 由宿主给：core 不碰时钟）。
+fn core_request(view: AdoptRequestView) -> AdoptRequest {
+    AdoptRequest {
+        version_id: view.version_id,
+        name: view.name.filter(|name| !name.trim().is_empty()),
+        target: target_of(view.target),
+        created_at: Some(format_rfc3339_millis(now())),
+    }
+}
+
+/// 三档视图 → core 的运行目录选择。
+///
+/// `custom` **不映射**：GUI 不开「用户手输绝对路径」这一档（那要目录选择器），
+/// 需要它的调用方走 CLI 的 `ull instances adopt --isolation custom --game-dir DIR`。
+fn target_of(view: AdoptTargetView) -> AdoptTarget {
+    match view {
+        AdoptTargetView::InstanceDir => AdoptTarget::InstanceDir,
+        AdoptTargetView::Shared => AdoptTarget::Shared,
+        AdoptTargetView::VersionDir => AdoptTarget::VersionDir,
+    }
+}
+
+/// core 隔离档 → 视图。
+fn isolation_view(isolation: Isolation) -> AdoptIsolationView {
+    match isolation {
+        Isolation::Isolated => AdoptIsolationView::Isolated,
+        Isolation::Shared => AdoptIsolationView::Shared,
+        Isolation::Custom => AdoptIsolationView::Custom,
+    }
+}
+
+/// core 候选 → 视图（`registered` 只带实例名：界面要的是「给谁登记过了」）。
+fn candidate_view(candidate: &AdoptCandidate) -> AdoptCandidateView {
+    AdoptCandidateView {
+        version_id: candidate.version_id.clone(),
+        jar_present: candidate.jar_present,
+        inherits: candidate.inherits.clone(),
+        registered: candidate
+            .registered
+            .iter()
+            .map(|instance| instance.name.clone())
+            .collect(),
+        problems: candidate.problems.iter().map(problem_view).collect(),
+    }
+}
+
+/// core 问题 → 视图（`code` 稳定 + `Display` 原文：路径、行列号、缺哪个父版本都在里面）。
+fn problem_view(problem: &AdoptProblem) -> AdoptProblemView {
+    AdoptProblemView {
+        code: problem.code().to_string(),
+        message: problem.to_string(),
+    }
+}
+
+/// core 计划 → 视图。`run_dir` / `notes` **原样**搬运，界面不许再算一遍。
+fn plan_view(plan: AdoptPlan) -> AdoptPlanView {
+    AdoptPlanView {
+        version_id: plan.candidate.version_id.clone(),
+        name: plan.name,
+        target: target_view(&plan.target),
+        isolation: isolation_view(plan.isolation),
+        run_dir: plan.run_dir,
+        notes: plan.notes,
+    }
+}
+
+/// core 结果 → 视图。
+fn done_view(outcome: AdoptOutcome) -> AdoptDoneView {
+    AdoptDoneView {
+        instance_id: outcome.instance_id,
+        name: outcome.name,
+        version_id: outcome.version_id,
+        isolation: isolation_view(outcome.isolation),
+        run_dir: outcome.run_dir,
+        dir_created: outcome.dir_created,
+        notes: outcome.notes,
+    }
+}
+
+/// core 运行目录选择 → 视图（`Custom` 只在 core 侧出现，界面按「缺省档」显示）。
+fn target_view(target: &AdoptTarget) -> AdoptTargetView {
+    match target {
+        AdoptTarget::InstanceDir | AdoptTarget::Custom(_) => AdoptTargetView::InstanceDir,
+        AdoptTarget::Shared => AdoptTargetView::Shared,
+        AdoptTarget::VersionDir => AdoptTargetView::VersionDir,
+    }
+}
+
+/// core 失败 → 视图：**`problems[]` 一条不少地带出来**（契约 §5.3）。
+fn failure_view(error: AdoptError) -> AdoptFailureView {
+    AdoptFailureView {
+        code: error.code().to_string(),
+        message: error.to_string(),
+        problems: error.problems().iter().map(problem_view).collect(),
+    }
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/presenter/src/host/adopt/tests.rs b/crates/presenter/src/host/adopt/tests.rs
new file mode 100644
index 0000000..ac1ad6a
--- /dev/null
+++ b/crates/presenter/src/host/adopt/tests.rs
@@ -0,0 +1,217 @@
+//! `host::adopt` 的用例（M223）：真盘夹具 + 三条命令的回程形状。
+//!
+//! 抓得住：扫描只读（`.ULL/config` 不出现）、预检与确认的落点一致且都来自 core、
+//! 坏清单失败时 `problems[]` 逐条带出（带行列号）、三档映射。
+//! 抓不住：真启动游戏用不用这个运行目录（那是 launch 链路的活）；D30 视觉（另走截图通道）。
+//!
+//! 为什么单独一个文件：`host/adopt.rs` 带用例会到 440 行，越过 400 行硬线（AGENTS §3.1）。
+
+use super::*;
+use crate::dto::AdoptStage;
+
+/// 真盘夹具：`/.minecraft/versions//`（清单 + jar）+ `/.ULL`。
+struct Fixture {
+    root: std::path::PathBuf,
+}
+
+impl Fixture {
+    fn new(tag: &str) -> Self {
+        let root = std::env::temp_dir().join(format!(
+            "ull-presenter-adopt-{tag}-{}-{}",
+            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(&root).expect("建临时根");
+        Self { root }
+    }
+
+    fn env(&self) -> HostEnv {
+        HostEnv::at_root(&self.root)
+    }
+
+    /// 铺一个「别的启动器装好的」版本（`manifest` 原样写，便于造坏清单）。
+    fn version(&self, id: &str, manifest: &str) {
+        let dir = self.root.join(".minecraft/versions").join(id);
+        std::fs::create_dir_all(&dir).expect("建版本目录");
+        std::fs::write(dir.join(format!("{id}.json")), manifest).expect("写清单");
+        std::fs::write(dir.join(format!("{id}.jar")), b"jar-bytes").expect("写 jar");
+    }
+}
+
+impl Drop for Fixture {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_dir_all(&self.root);
+    }
+}
+
+const MANIFEST: &str = r#"{
+  "id": "1.20.1",
+  "type": "release",
+  "mainClass": "net.minecraft.main.Main",
+  "libraries": []
+}"#;
+
+fn request(version_id: &str, target: AdoptTargetView) -> AdoptRequestView {
+    AdoptRequestView {
+        version_id: version_id.to_string(),
+        name: None,
+        target,
+    }
+}
+
+/// 收一条 `HostTask::Adopt`（同步等后台线程交卷）。
+fn recv(rx: &super::super::job::JobReceiver) -> AdoptEvent {
+    match rx.recv().expect("后台线程应回一条") {
+        HostTask::Adopt { event, .. } => *event,
+        other => panic!("期望 HostTask::Adopt，收到 {other:?}"),
+    }
+}
+
+#[test]
+fn scan_lists_the_foreign_versions_without_writing() {
+    let fixture = Fixture::new("scan");
+    fixture.version("1.20.1", MANIFEST);
+    let env = fixture.env();
+    let (tx, rx) = job::channel();
+    spawn_scan(env.clone(), tx, 1);
+
+    let AdoptEvent::Scan(scan) = recv(&rx) else {
+        panic!("扫描应回 AdoptEvent::Scan");
+    };
+    assert_eq!(scan.versions_dir, fixture.root.join(".minecraft/versions"));
+    assert_eq!(scan.total(), 1);
+    assert_eq!(scan.adoptable(), 1);
+    assert!(scan.candidates[0].jar_present);
+    // 扫描零写盘：`.ULL/config` 下不该出现任何东西
+    assert!(!fixture.root.join(".ULL/config/profiles.json").exists());
+}
+
+#[test]
+fn confirm_registers_and_reports_the_core_run_dir() {
+    let fixture = Fixture::new("confirm");
+    fixture.version("1.20.1", MANIFEST);
+    let env = fixture.env();
+
+    // 先预检：零写盘，落点与后果原文都来自 core
+    let (tx, rx) = job::channel();
+    spawn_adopt(
+        env.clone(),
+        tx,
+        request("1.20.1", AdoptTargetView::InstanceDir),
+        Mode::Preview,
+        1,
+    );
+    let AdoptEvent::Planned(plan) = recv(&rx) else {
+        panic!("预检应回 AdoptEvent::Planned");
+    };
+    assert_eq!(plan.target, AdoptTargetView::InstanceDir);
+    assert_eq!(plan.isolation, AdoptIsolationView::Custom);
+    // 缺省档的运行目录落数据区（**不是** `versions/`）
+    assert!(
+        plan.run_dir
+            .starts_with(fixture.root.join(".ULL/data/instances")),
+        "落点应在 ULL 数据区：{}",
+        plan.run_dir.display()
+    );
+    assert!(!plan.notes.is_empty(), "缺省档也要说清后果");
+    assert!(!fixture.root.join(".ULL/config/profiles.json").exists());
+
+    // 确认：同一份请求发回去，真的登记
+    let (tx, rx) = job::channel();
+    spawn_adopt(
+        env,
+        tx,
+        request("1.20.1", AdoptTargetView::InstanceDir),
+        Mode::Confirm,
+        2,
+    );
+    let AdoptEvent::Done(done) = recv(&rx) else {
+        panic!("确认应回 AdoptEvent::Done");
+    };
+    assert_eq!(done.version_id, "1.20.1");
+    assert_eq!(done.run_dir, plan.run_dir, "确认的落点必须与预检一致");
+    assert!(done.dir_created);
+    let profiles = std::fs::read_to_string(fixture.root.join(".ULL/config/profiles.json"))
+        .expect("profiles.json 应被写出来");
+    assert!(profiles.contains("1.20.1"));
+    // 游戏根的版本目录一个字节都没写（只有夹具自己那两个文件）
+    let dir = fixture.root.join(".minecraft/versions/1.20.1");
+    let mut names: Vec = std::fs::read_dir(&dir)
+        .expect("读版本目录")
+        .map(|entry| {
+            entry
+                .expect("条目")
+                .file_name()
+                .to_string_lossy()
+                .into_owned()
+        })
+        .collect();
+    names.sort();
+    assert_eq!(names, ["1.20.1.jar", "1.20.1.json"]);
+}
+
+#[test]
+fn a_bad_manifest_comes_back_as_every_problem_not_one_sentence() {
+    let fixture = Fixture::new("problems");
+    fixture.version("1.20.1", "{ this is not json");
+    let (tx, rx) = job::channel();
+    spawn_adopt(
+        fixture.env(),
+        tx,
+        request("1.20.1", AdoptTargetView::InstanceDir),
+        Mode::Preview,
+        1,
+    );
+    let AdoptEvent::Failed(failure) = recv(&rx) else {
+        panic!("坏清单应回 AdoptEvent::Failed");
+    };
+    assert_eq!(failure.code, "adopt_not_adoptable");
+    assert_eq!(failure.problems.len(), 1);
+    assert_eq!(failure.problems[0].code, "manifest_invalid_json");
+    assert!(
+        failure.problems[0].message.contains("line"),
+        "清单问题要带行列号：{}",
+        failure.problems[0].message
+    );
+}
+
+#[test]
+fn targets_map_to_core_and_custom_stays_out_of_the_gui() {
+    assert_eq!(
+        target_of(AdoptTargetView::InstanceDir),
+        AdoptTarget::InstanceDir
+    );
+    assert_eq!(target_of(AdoptTargetView::Shared), AdoptTarget::Shared);
+    assert_eq!(
+        target_of(AdoptTargetView::VersionDir),
+        AdoptTarget::VersionDir
+    );
+    // `Custom` 只在 core 侧出现（CLI 的 `--game-dir`）：界面按缺省档显示
+    assert_eq!(
+        target_view(&AdoptTarget::Custom(std::path::PathBuf::from("/x"))),
+        AdoptTargetView::InstanceDir
+    );
+    assert_eq!(
+        isolation_view(Isolation::Custom),
+        AdoptIsolationView::Custom
+    );
+    assert_eq!(
+        isolation_view(Isolation::Shared),
+        AdoptIsolationView::Shared
+    );
+    assert_eq!(
+        isolation_view(Isolation::Isolated),
+        AdoptIsolationView::Isolated
+    );
+    // 空名回落到版本 id 由 core 负责；这里只钉「空白名不进请求」
+    let request = core_request(AdoptRequestView {
+        version_id: "1.20.1".to_string(),
+        name: Some("   ".to_string()),
+        target: AdoptTargetView::Shared,
+    });
+    assert_eq!(request.name, None);
+    assert!(request.created_at.is_some());
+    assert_eq!(AdoptStage::Pick.slug(), "pick");
+}
diff --git a/crates/presenter/src/host/cancel_tests.rs b/crates/presenter/src/host/cancel_tests.rs
new file mode 100644
index 0000000..ce22bd7
--- /dev/null
+++ b/crates/presenter/src/host/cancel_tests.rs
@@ -0,0 +1,347 @@
+//! 取消安装的**实测装置**（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 侧还在被事件喂」；抓不住事件之外的后台动作 |
+//! | 断点文件 | `/**/*.ullpart*` 的总字节：取消时 vs 取消后 20 s，**并且**绝对值必须是 0 | 抓得住「还在写」与「留了半截垃圾」；抓不住「线程还活着」（`.ullpart` 不再长也可能是卡在等响应） |
+//! | 半成品变成品 | `/versions//.json`（版本清单）与 `/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()) {
+            // 中间文件 `.ullpart[--]` 与它的元数据 `.ullmeta.json`
+            if name.contains(".ullpart") {
+                total += meta.len();
+            }
+        }
+    }
+    total
+}
+
+/// 一次 tick 后抽干事件，返回本轮的全部事件。
+fn pump(host: &mut CoreHost, wait: Duration) -> Vec {
+    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();
+    // 实例登记的真相源是 `/config/profiles.json`（`LauncherLayout::profiles_config()`），
+    // 不是 `/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 = host.drain_events();
+    assert!(
+        live.iter()
+            .any(|event| matches!(event, AppEvent::Core(CoreEvent::InstallProgress(Some(_))))),
+        "当代次的事件必须照常点亮面板"
+    );
+
+    // 取消
+    host.dispatch(AppCommand::CancelInstall);
+    let cancelled: Vec = 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(crate::dto::ContentFailure::new(
+            crate::dto::ContentFailureKind::Other,
+            "已取消",
+        )),
+        epoch,
+    });
+    let after: Vec = 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..8d06f5d
--- /dev/null
+++ b/crates/presenter/src/host/dispatch.rs
@@ -0,0 +1,314 @@
+//! `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, mods, saves, 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 那条取消信号
+                // （它说的是「安装已取消、实例未创建」，而导入的取消是**管线级**的：core 在检查点
+                // 停手并回滚，文案见 `PackCancelled`；M195 之前它会在后台跑完并登记实例）。
+                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::SetInstanceLaunchArgs { id, patch } => {
+                match self.apply_launch_args(&id, &patch) {
+                    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(()) => {
+                    // 「重新检测地区」：`settings::set` 已经删了 `region.json` 并让共享引擎失效，
+                    // 但自更新的 `Factory` 常驻持有旧引擎 —— 不在这条路径上重建它，自更新会继续
+                    // 按旧地区档案跑，直到重启（M165 复审 P2-1）。
+                    if key == super::engine::DETECT_REGION_ACTION {
+                        self.refresh_update_factory();
+                    }
+                    // M193：下载三键（并发/重试/gh-proxy）改了要立刻换引擎参数。这是**显式**的同步点
+                    // ——不藏在任何读函数里。值没变时它一行不动。
+                    if settings::download::apply_tuning(&self.env) {
+                        self.refresh_update_factory();
+                    }
+                    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);
+            }
+            // M162：详情/版本列表（选中项目才发；结果经 `CoreEvent::ContentDetail` 回来）
+            AppCommand::LoadContentDetail(request) => {
+                addon::spawn_detail(self.env.clone(), self.tx.clone(), *request);
+            }
+            // M109：把某个内容项目装进指定实例。取消标记与安装面板共用同一条路
+            // （`CancelInstall` 会把标记置位，下载在阶段边界收尾）。
+            // M113: import/export —— 导入 / 预检 / 确认写盘 / 关面板
+            AppCommand::Pack(command) => self.pack(*command),
+            // M223: 导入已有版本 —— 扫描 / 预检 / 确认登记 / 关面板
+            AppCommand::Adopt(command) => self.adopt(*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);
+            }
+            // M159: 自更新 —— 检查 / 下载替换 / 拒绝 / 开关
+            AppCommand::CheckUpdate => self.start_update_check(true),
+            AppCommand::ApplyUpdate => self.start_update_apply(),
+            AppCommand::DismissUpdate => {
+                self.update.dismiss();
+                self.publish_update();
+            }
+            AppCommand::SetUpdateAutoCheck(on) => match self.update.set_auto_check(on) {
+                Ok(()) => self.publish_update(),
+                Err(reason) => {
+                    // 写不进去也要把这次的选择留在会话里（不把开关弹回去），并说清原因。
+                    self.publish_update();
+                    self.toast(ToastKind::Warn, reason);
+                }
+            },
+            // M224：本地 Mod 列表 / 启停（磁盘在后台线程碰；这里只算"游戏在不在跑"）
+            AppCommand::Mods(command) => {
+                let id = match &*command {
+                    crate::dto::ModsCommand::List(id) => id.clone(),
+                    crate::dto::ModsCommand::SetEnabled { id, .. } => id.clone(),
+                };
+                // 运行中挡在 host 这一侧（不只是 UI 灰掉）：Windows 上进程正持有 jar，
+                // rename 必然失败，与其让用户读一句 OS 报错，不如直说。
+                let running = self.in_flight(&id);
+                mods::dispatch(self.env.clone(), self.tx.clone(), *command, running);
+            }
+            // M235：实例存档 / 截图的只读列表 + 打开文件夹；M247 加了三个写操作。
+            //
+            // **写操作要看"游戏在不在跑"**（M247 补齐，与 `AppCommand::Mods` 同款判据）：
+            // Windows 上进程占着世界目录 ⇒ rename/删除会撞共享冲突；**Linux 上删一个正在跑的世界
+            // 会成功**——那是在用户正在玩的时候把存档删掉。所以判据放在 host 这一侧、落 core 之前，
+            // 在飞就回一条结构化失败「游戏正在运行，先退出再操作」，一个字节都不碰盘。
+            // 读路径与「打开文件夹」不受影响（它们不改盘）。
+            AppCommand::Saves(command) => {
+                let id = saves::instance_of(&command).to_string();
+                let running = self.in_flight(&id);
+                saves::dispatch(self.env.clone(), self.tx.clone(), *command, running);
+            }
+            // 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..13ab99f
--- /dev/null
+++ b/crates/presenter/src/host/engine.rs
@@ -0,0 +1,207 @@
+//! 下载引擎与 Java 落点的装配（versions / install / java 三个任务共用）。
+//!
+//! **引擎是进程级的、按数据根共享的**（M165）：本模块不再自己 `DownloadEngine::new`，而是向
+//! [`unlucky_core::download::shared`] 要那个数据根上已经存在的引擎。于是连接池、信号量限流、
+//! 镜像健康度、内容寻址缓存都跨请求累积，而不是每次请求清零（逐项代价与边界见那个模块的文档）。
+//!
+//! 与 CLI `install::build_engine` 同源：内容寻址缓存落 `.ULL/cache/`，地区判定走
+//! 24h 缓存 + 环境信号（**不做网络探测**，与 D7 的「不探测时」约定一致）；区别只在生命周期
+//! ——CLI 一条命令一个进程，建一次就够；GUI 进程要在成百上千次请求之间复用同一份。
+
+use std::path::PathBuf;
+use std::sync::Arc;
+
+use unlucky_core::download::shared;
+use unlucky_core::download::DownloadEngine;
+use unlucky_core::game::java::vendor::JdkVendor;
+use unlucky_core::game::java::{self, JavaInstallRoot};
+use unlucky_core::platform::paths::ProcessEnv;
+
+use super::env::HostEnv;
+
+/// 取该数据根上**共享**的下载引擎（缓存/健康度/地区判定都在数据根里）。
+///
+/// 同一个数据根无论被请求多少次，都是同一个引擎；不同数据根各一份（缓存/健康度不串味）。
+///
+/// **取引擎前先把下载设置灌进 core 的下载调优**（M193，按数据根存）：`download.concurrency` /
+/// `download.retry_limit` / `download.gh_proxy` 变了就重建引擎（值没变时 [`settings::download::apply_tuning`]
+/// 一行不动，所以每次调用都灌是安全的）。这是「用户改了设置 ⇒ 下一次下载真的按新值跑」的落点：
+/// 不在这里灌，进程级引擎会带着启动时那份参数活到进程结束——那正是「设置页看着有、实际没用」。
+#[must_use]
+pub fn engine(env: &HostEnv) -> Arc {
+    super::settings::download::apply_tuning(env);
+    shared::engine_for(env.layout.cache())
+}
+
+/// 让这个数据根的共享引擎失效：下一次 [`engine`] 重新构造（重读地区判定/健康度/缓存索引）。
+///
+/// 在飞请求手里的 `Arc` 不受影响。设置页「重新检测地区」清掉 `region.json` 之后必须调它，
+/// 否则那句话（「下次下载重新判定」）在进程级引擎下就不成立了。
+pub fn forget(env: &HostEnv) {
+    shared::forget(env.layout.cache());
+}
+
+/// 是否国内网络（决定默认发行版顺序与镜像优先级）。
+pub fn domestic(env: &HostEnv) -> bool {
+    engine(env).region().is_domestic()
+}
+
+/// 「重新检测地区」这个动作键（设置页的行 id、`settings::set` 的分派、`dispatch` 里「要不要重建
+/// 自更新 Factory」的判断共用一个真相源）。
+///
+/// 动作不是普通设置：它要清 `region.json`、让 [`forget`] 失效共享引擎，并让自更新的 `Factory`
+/// 换引擎（M165 复审 P2-1）——所以三处都得认出它。常量放这里（引擎/地区这一侧），不放已经顶到
+/// 400 行红线的 `settings.rs`。
+pub(super) const DETECT_REGION_ACTION: &str = "download.action.detect_region";
+
+/// 设置里的 `java.vendorPriority`（空 = 按地区默认序）。
+pub fn java_priority(env: &HostEnv) -> Vec {
+    env.store()
+        .effective("java.vendorPriority")
+        .and_then(serde_json::Value::as_array)
+        .map(|items| {
+            let texts: Vec = 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 {
+    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 {
+    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 {
+    java::location::scan_roots(
+        env.mode(),
+        &env.layout,
+        java_install_override(env).as_deref(),
+        env.platform,
+        &ProcessEnv,
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// 每个用例一个独立数据根（共享登记处是进程级的，键撞了会互相干扰）。
+    fn root(tag: &str) -> std::path::PathBuf {
+        static SEQ: std::sync::atomic::AtomicUsize = std::sync::atomic::AtomicUsize::new(0);
+        let seq = SEQ.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
+        let dir = std::env::temp_dir().join(format!(
+            "ull-host-engine-{tag}-{}-{seq}",
+            std::process::id()
+        ));
+        let _ = std::fs::remove_dir_all(&dir);
+        std::fs::create_dir_all(dir.join(".ULL").join("cache")).expect("cache");
+        dir
+    }
+
+    #[test]
+    fn engine_uses_the_data_root_cache() {
+        let dir = root("cache");
+        let env = HostEnv::at_root(&dir);
+        let engine = engine(&env);
+        assert_eq!(
+            engine.config().max_concurrency,
+            unlucky_core::download::config::DEFAULT_MAX_CONCURRENCY
+        );
+        assert_eq!(engine.concurrency_probe(), engine.config().max_concurrency);
+        // 地区判定不联网：只读缓存/信号
+        let _ = domestic(&env);
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    /// **M165 的守卫**：同一 host 的多次请求只建一个引擎。
+    ///
+    /// 断言的是**构造次数**（`shared::constructions`），不是「能不能下到文件」——每请求现建一个
+    /// 引擎照样能下到文件，只有次数能把「复用」与「没复用」分开。
+    ///
+    /// 抓得住的变异：把 `core::download::shared::engine_for` 里 `engines.get` 的命中分支删掉
+    /// （每次调用都现建），本用例红在 `constructions(...) == 1`。
+    #[test]
+    fn host_requests_share_one_engine() {
+        let dir = root("share");
+        let env = HostEnv::at_root(&dir);
+        let cache_root = env.layout.cache();
+
+        // 三条不同「请求」路径都从 engine() 取引擎（检索 / 清单 / 安装共用这一个漏斗）。
+        let first = engine(&env);
+        let second = engine(&env);
+        let third = engine(&HostEnv::at_root(&dir));
+
+        assert!(
+            Arc::ptr_eq(&first, &second) && Arc::ptr_eq(&second, &third),
+            "同一数据根的多次请求必须是同一个引擎"
+        );
+        assert_eq!(shared::constructions(&cache_root), 1, "只该构造一次引擎");
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    /// 不同数据根**不共享**引擎（缓存/健康度串味比多建一个引擎严重得多）。
+    #[test]
+    fn different_data_roots_get_their_own_engine() {
+        let dir_a = root("root-a");
+        let dir_b = root("root-b");
+        let env_a = HostEnv::at_root(&dir_a);
+        let env_b = HostEnv::at_root(&dir_b);
+        let engine_a = engine(&env_a);
+        let engine_b = engine(&env_b);
+        assert!(!Arc::ptr_eq(&engine_a, &engine_b));
+        assert_eq!(shared::constructions(env_a.layout.cache()), 1);
+        assert_eq!(shared::constructions(env_b.layout.cache()), 1);
+        std::fs::remove_dir_all(&dir_a).ok();
+        std::fs::remove_dir_all(&dir_b).ok();
+    }
+
+    /// `forget`（「重新检测地区」）之后下一次请求拿到新引擎。
+    #[test]
+    fn forget_makes_the_next_request_rebuild() {
+        let dir = root("forget");
+        let env = HostEnv::at_root(&dir);
+        let before = engine(&env);
+        forget(&env);
+        let after = engine(&env);
+        assert!(!Arc::ptr_eq(&before, &after));
+        assert_eq!(shared::constructions(env.layout.cache()), 2);
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    #[test]
+    fn java_merge_priority_reads_settings() {
+        let dir = root("priority");
+        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..28b22f6
--- /dev/null
+++ b/crates/presenter/src/host/env.rs
@@ -0,0 +1,307 @@
+//! host 的环境快照：一份 `ResolvedData` + 由其派生的布局视图。
+//!
+//! app 自己不解析三模式数据根（那是 `core::platform::data_dir` 的活）；这里只做两件事：
+//! ①按「exe 同级便携 `launcher.json` 的 `core.*` 四键」拼请求；②把解析结果与
+//! `Platform` / `DataMode` 打成一个可克隆的结构，交给后台线程。
+//!
+//! 截图/演示通道用 [`HostEnv::at_root`] 直接钉一个根（`/.ULL` + `/.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 {
+        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))
+    }
+
+    /// 直接钉一个根：`/.ULL` + `/.minecraft`（截图/演示通道）。
+    ///
+    /// 根下已有 `config/launcher.json` 时**尊重其中的 `core.game_home` / `core.launcher_home`**：
+    /// 演示根常用它把游戏目录指到既有真数据上（避免复制几 GB 的 assets/libraries）。
+    pub fn at_root(root: impl AsRef) -> Self {
+        let root = root.as_ref();
+        let request = request_from_portable(root);
+        let absolute = |path: Option| 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,
+        })
+    }
+
+    /// 由解析结果建环境。
+    ///
+    /// **顺带做一件有副作用的事**：把本进程的日志目录登记给 `launch::launcher_log`（M188）。
+    /// 这是**启动早期那几行诊断**能落到 `<.ULL>/logs/launcher.log` 的唯一时机——app 层在
+    /// presenter 打开之前就在打 `[probe]` / `[font]` / `[theme]`，那些行先被 core 缓冲
+    /// （上限 200 行），到这里一次刷出。此前只有「启动一次游戏」或「导出诊断包」才登记，
+    /// 于是「双击 → 启动 → 崩」的进程根本不产生 launcher.log——正是用户投诉的那一半。
+    pub fn from_data(data: ResolvedData) -> Self {
+        let layout = data.layout();
+        unlucky_core::launch::launcher_log::set_dir(layout.logs());
+        Self {
+            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())
+    }
+
+    /// 启动会话根（M188 起 = `logs/`；`LauncherConfig` 在其下建 `game/`）。
+    pub fn sessions_root(&self) -> PathBuf {
+        self.layout.sessions_root()
+    }
+
+    /// 会话日志的**旧家**（`data/agent/sessions/`）：只读兼容，M188 起不再往里写。
+    pub fn legacy_sessions_root(&self) -> PathBuf {
+        self.layout.agent_sessions()
+    }
+
+    /// 启动器日志目录（`logs/`：`launcher.log` + `game/` 会话）。
+    pub fn logs_dir(&self) -> PathBuf {
+        self.layout.logs()
+    }
+
+    /// 数据目录模式。
+    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
+}
+
+/// `/.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::*;
+    use unlucky_core::platform::paths::MapEnv;
+
+    #[test]
+    fn at_root_splits_launcher_and_game_homes() {
+        let root = std::env::temp_dir().join(format!("ull-host-env-root-{}", std::process::id()));
+        let env = HostEnv::at_root(&root);
+        assert_eq!(env.layout.home(), root.join(".ULL"));
+        assert_eq!(env.game.root(), root.join(".minecraft"));
+        assert_eq!(env.mode(), DataMode::Portable);
+        assert!(env.data_line().contains("portable"));
+        std::fs::remove_dir_all(&root).ok();
+    }
+
+    /// M188 的守门②：**日志根随数据模式变化**（便携 / 标准 / 自定义各一条断言）。
+    ///
+    /// 三条走的都是 `HostEnv` 真正用的那条解析链（`Resolver` → `ResolvedData::layout`）：
+    ///
+    /// | 模式 | 期望的 `` | 期望的日志根 |
+    /// |---|---|---|
+    /// | portable | `/.ULL` | `/.ULL/logs` |
+    /// | standard | `%APPDATA%/ULL` | `%APPDATA%/ULL/logs` |
+    /// | custom | `/.ULL` | `/.ULL/logs` |
+    ///
+    /// 这里只碰解析结果、不建 `HostEnv`：`from_data` 会真的去登记日志目录（那是产品行为，
+    /// 单测里拿假绝对路径调它会在盘根建目录）。
+    /// 变异证明：把 `LauncherLayout::logs` 改成返回 `cache/`，三条全红。
+    #[test]
+    fn logs_root_follows_the_three_data_modes() {
+        let env = MapEnv::new().with("APPDATA", "/roaming");
+        let exe_dir = PathBuf::from("/games/ULL");
+        // custom 模式的根必须是**绝对路径**（Windows 上 `/custom-root` 不算绝对，要带盘符）。
+        let custom_root = std::env::temp_dir().join("ull-m188-custom");
+        let resolver = Resolver::with_env(Platform::current(), Some(exe_dir.clone()), &env);
+
+        let cases = [
+            (
+                DataDirRequest {
+                    mode: DataMode::Portable,
+                    ..DataDirRequest::default()
+                },
+                exe_dir.join(".ULL/logs"),
+            ),
+            (
+                DataDirRequest {
+                    mode: DataMode::Standard,
+                    ..DataDirRequest::default()
+                },
+                PathBuf::new(),
+            ),
+            (
+                DataDirRequest {
+                    mode: DataMode::Custom,
+                    custom_root: Some(custom_root.clone()),
+                    ..DataDirRequest::default()
+                },
+                custom_root.join(".ULL/logs"),
+            ),
+        ];
+
+        for (request, expected) in cases {
+            let Ok(data) = resolver.resolve(&request) else {
+                // 标准模式在某些平台拿不到（没有 HOME/APPDATA）：这一档只能跳过，不许假绿。
+                assert_eq!(request.mode, DataMode::Standard, "{request:?}");
+                continue;
+            };
+            let home = data.launcher_home.clone();
+            let layout = data.layout();
+            assert_eq!(layout.logs(), home.join("logs"), "{request:?}");
+            assert_eq!(layout.sessions_root(), home.join("logs"), "{request:?}");
+            assert_eq!(layout.game_logs(), home.join("logs/game"), "{request:?}");
+            assert_eq!(
+                layout.agent_sessions(),
+                home.join("data/agent/sessions"),
+                "{request:?}"
+            );
+            if !expected.as_os_str().is_empty() {
+                assert_eq!(layout.logs(), expected, "{request:?}");
+            }
+            // 自定义模式的根在临时目录里，顺手把 `HostEnv` 那三个访问器也钉一遍——
+            // 「layout 对了但 `HostEnv::logs_dir` 写死」这种假绿只有这一段抓得住。
+            if request.mode == DataMode::Custom {
+                let env = HostEnv::from_data(data);
+                assert_eq!(env.logs_dir(), home.join("logs"), "{request:?}");
+                assert_eq!(env.sessions_root(), home.join("logs"), "{request:?}");
+                assert_eq!(
+                    env.legacy_sessions_root(),
+                    home.join("data/agent/sessions"),
+                    "{request:?}"
+                );
+            }
+        }
+    }
+
+    /// 三种模式的日志根**各不相同**（防止「都指向同一个写死的目录」这种假绿）。
+    #[test]
+    fn the_three_modes_do_not_share_one_logs_root() {
+        let env = MapEnv::new().with("APPDATA", "/roaming");
+        let resolver =
+            Resolver::with_env(Platform::current(), Some(PathBuf::from("/games/ULL")), &env);
+        let portable = resolver
+            .resolve(&DataDirRequest {
+                mode: DataMode::Portable,
+                ..DataDirRequest::default()
+            })
+            .expect("portable 一定解析得出");
+        let custom = resolver
+            .resolve(&DataDirRequest {
+                mode: DataMode::Custom,
+                custom_root: Some(std::env::temp_dir().join("ull-m188-custom")),
+                ..DataDirRequest::default()
+            })
+            .expect("custom 有绝对路径");
+        assert_ne!(portable.layout().logs(), custom.layout().logs());
+    }
+
+    /// `HostEnv` 自己的三格（日志根 / 会话根 / 旧会话根）指着同一份解析结果。
+    #[test]
+    fn env_paths_come_from_one_layout() {
+        let root = std::env::temp_dir().join(format!("ull-host-env-paths-{}", std::process::id()));
+        let env = HostEnv::at_root(&root);
+        assert_eq!(env.logs_dir(), root.join(".ULL/logs"));
+        assert_eq!(env.sessions_root(), root.join(".ULL/logs"));
+        assert_eq!(
+            env.legacy_sessions_root(),
+            root.join(".ULL/data/agent/sessions")
+        );
+        std::fs::remove_dir_all(&root).ok();
+    }
+
+    #[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..1a90fa3
--- /dev/null
+++ b/crates/presenter/src/host/game.rs
@@ -0,0 +1,208 @@
+//! 实例快照：`profiles.json` + 版本 JSON + 会话索引 + 实例设置 → [`InstanceSummary`]。
+//!
+//! 「磁贴上的每个字」都在这里翻译完：版本号取自继承链根、加载器取自版本 id（解析在
+//! [`unlucky_core::game::loader`]，本文件只做 DTO 翻译）、最后游玩时间取自会话索引、
+//! 隔离档位取自实例设置（缺省跟全局 `instances.mode`）。
+
+use std::collections::BTreeMap;
+use std::path::Path;
+
+use unlucky_core::game::install::instance::{
+    read_instance_config, read_profiles, write_instance_config,
+};
+use unlucky_core::game::isolation::IsolationMode;
+use unlucky_core::game::{ProfileList, VersionJson};
+
+use 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()
+}
+
+/// 全会话索引里「每个实例最近一次启动」的时间串（`logs/` + 旧家合并）。
+pub fn last_played(env: &HostEnv) -> BTreeMap {
+    let entries = super::logs::entries(env);
+    let mut map: BTreeMap = 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(¤t);
+        let Ok(text) = std::fs::read_to_string(&path) else {
+            break;
+        };
+        let Ok(json) = VersionJson::from_json_str(&text) else {
+            break;
+        };
+        match json.inherits_from {
+            Some(parent) if !parent.is_empty() => current = parent,
+            _ => break,
+        }
+    }
+    (current, loader)
+}
+
+/// 版本 id → 加载器。
+///
+/// 解析本身**不在这里**：真相源是 [`unlucky_core::game::loader`]（生成端
+/// `addon::loader::LoaderKind::version_id` 拼的是 `--`，如
+/// `1.20.4-fabric-0.16.5`）。本函数只做两件事：调 core 的解析、把 core 的种类翻成 DTO
+/// 种类（`dto` 里不许出现 core 类型，翻译只能发生在 host 这条边界上）。
+pub fn loader_from_id(version_id: &str) -> LoaderInfo {
+    let parsed = unlucky_core::game::InstanceLoader::parse(version_id);
+    LoaderInfo {
+        kind: dto_kind(parsed.kind),
+        version: parsed.version,
+    }
+}
+
+/// core 的加载器种类 → DTO 种类。
+///
+/// **这里没有映射表**：种类由 core 的稳定 id 反查 DTO 词表得来（[`LoaderKind::parse`] →
+/// `dto::LoaderKind::from_core`，全仓唯一那份 core↔DTO 映射）。M134 之前这里是七支手写 match，
+/// M126 r3 复审实测过：core 加第八家、契约与 help 都补齐、**只在这一支写 `=> Vanilla`**，三个
+/// crate 全绿（402 / 220 / 42）而磁贴静默显示「原版」——M122 修掉的用户可见 bug 复活。委派之后
+/// **没有落笔处**：新种类必须先过 `dto::LoaderKind::from_core`（那边编不过就说明 DTO 还没决定怎么
+/// 显示它），糊错的后果由 `dto::instances` 的 `loader_kind_ids_are_the_released_contract` 与本
+/// 文件的 `every_core_loader_kind_reaches_the_tile_as_itself` 钉住。反查不到只能是 core 的
+/// `as_str` 与 `parse` 自相矛盾（同一张宏表长出来，物理上做不到），真发生了就 panic：**不许**
+/// 退回「原版」。
+fn dto_kind(kind: unlucky_core::game::LoaderKind) -> LoaderKind {
+    LoaderKind::parse(kind.as_str()).unwrap_or_else(|| {
+        unreachable!(
+            "core 的稳定 id `{}` 反查不到 DTO 种类：词表两边脱节了",
+            kind.as_str()
+        )
+    })
+}
+
+/// 实例的隔离档位（实例文件优先，缺省显示全局档位）。
+pub fn isolation_of(env: &HostEnv, id: &str) -> String {
+    let global = global_mode(env);
+    match read_instance_config(&env.layout, id) {
+        Ok(Some(config)) => config.effective_isolation(global).as_str().to_string(),
+        _ => global.as_str().to_string(),
+    }
+}
+
+/// 实例快照。
+pub fn instances(env: &HostEnv) -> Vec {
+    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);
+            let id = profile.id.as_str();
+            InstanceSummary {
+                id: id.to_string(),
+                name: profile.name.clone(),
+                mc_version,
+                loader,
+                last_played: played.get(id).cloned(),
+                runtime: InstanceRuntime::Idle,
+                icon: None,
+                isolation: isolation_of(env, id),
+                version_present: env.game.is_version_installed(&version_id),
+                launch: super::launch_args::view(env, id, &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 {
+    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;
diff --git a/crates/presenter/src/host/game/tests.rs b/crates/presenter/src/host/game/tests.rs
new file mode 100644
index 0000000..a451237
--- /dev/null
+++ b/crates/presenter/src/host/game/tests.rs
@@ -0,0 +1,189 @@
+use super::*;
+
+/// 版本 id → DTO 加载器的接口面（解析在 core，这里只验翻译没走样）。
+///
+/// 抓得住：显示路径把某个种类翻错/翻塌（例如 Quilt 写成 Forge）——`dto_kind` 的委派与
+/// `dto` 的 `from_core` 都落在这一条上；以及 core 解析端退回老口径（`fabric-loader-…` 才认、
+/// 自家 `1.20.4-fabric-0.16.5` 认不出）——后两条正是 M122 的 bug 面。
+/// 抓不住：core 解析规则本身（真值表在 `unlucky_core::game::loader` 的测试里，那边才是
+/// 真相源）；也抓不住「版本号为空时不显示品牌名」那条（在 `LoaderInfo::badge` 与
+/// app-iced 的 `loader_badge`，M120 已修，别在这里重复）。
+#[test]
+fn loader_parsing_covers_all_shapes() {
+    let cases = [
+        ("1.20.4", LoaderKind::Vanilla, ""),
+        // 自家口径（生成端 `LoaderKind::version_id`）：`--`
+        ("1.20.4-fabric-0.16.5", LoaderKind::Fabric, "0.16.5"),
+        ("1.20.4-quilt-0.27.0", LoaderKind::Quilt, "0.27.0"),
+        ("1.20.1-forge-47.2.0", LoaderKind::Forge, "47.2.0"),
+        ("1.21.1-neoforge-21.1.80", LoaderKind::NeoForge, "21.1.80"),
+        // 老 HMCL 口径（存量实例还会带着它们）
+        ("fabric-loader-0.16.5-1.20.1", LoaderKind::Fabric, "0.16.5"),
+        ("quilt-loader-0.24.0-1.20.1", LoaderKind::Quilt, "0.24.0"),
+        // 第三方口径
+        ("1.13.2-OptiFine_HD_U_E6", LoaderKind::OptiFine, "HD_U_E6"),
+        ("1.12.2-LiteLoader", LoaderKind::LiteLoader, ""),
+    ];
+    for (id, kind, version) in cases {
+        let info = loader_from_id(id);
+        assert_eq!(info.kind, kind, "{id}");
+        assert_eq!(info.version, version, "{id}");
+        assert!(!info.badge().is_empty());
+    }
+}
+
+/// 显示路径的**全量**锚：core 的每一种加载器，从自家版本 id 走到磁贴时仍然是**它自己**。
+///
+/// 清单取自 [`unlucky_core::game::LoaderKind::ALL`]，**不手抄**：M126 r3 复审实测出的缺口正是
+/// 「手抄的清单跟着漏」——core 加第八家、契约与 help 都补齐、只在 `dto_kind` 那一支写
+/// `=> Vanilla`，三个 crate 全绿而磁贴静默显示「原版」。`ALL` 由 core 的宏表长出来，加一家
+/// 自动进圈，测试作者不需要（也没法）记得补一行。
+///
+/// 抓得住：显示路径任何一环把种类翻塌成原版——`dto_kind` 又变回手写映射、`dto` 的
+/// `from_core` 那一支接错、`label()` 被写成「原版」；**包括新加的那种**（那时 `ALL` 先变长）。
+/// 抓不住：core 的 id 解析规则本身（真值表在 `unlucky_core::game::loader`）；版本号为空的
+/// 徽标判据（M120 的 `loader_badge`，本 crate 不渲染）。
+#[test]
+fn every_core_loader_kind_reaches_the_tile_as_itself() {
+    use unlucky_core::game::LoaderKind as Core;
+    for kind in Core::ALL {
+        let info = loader_from_id(&format!("1.20.4-{}-0.16.5", kind.as_str()));
+        assert_eq!(
+            info.kind.as_str(),
+            kind.as_str(),
+            "core 的 {kind:?} 走到磁贴时变成了 `{}`（徽标 `{}`）",
+            info.kind.as_str(),
+            info.badge()
+        );
+        assert_eq!(
+            info.badge().starts_with(LoaderKind::Vanilla.label()),
+            kind == Core::Vanilla,
+            "core 的 {kind:?} 在磁贴上的徽标是 `{}`",
+            info.badge()
+        );
+    }
+}
+
+/// 端到端（数据层）：真装出来的四个加载器实例，走 [`instances`] 的快照各自带对加载器。
+///
+/// 造的是本启动器**真实产物**的形状：`profiles.json` 里 `versionId` 是自家 id，
+/// `versions//.json` 里 `inheritsFrom` 指向原版层（生成端见
+/// `unlucky_core::addon::loader`）。原版版本号由此取自继承链根，不是从 id 里切的。
+///
+/// 抓得住：`describe_version` ↔ `loader_from_id` ↔ `instances` 这条链上任何一环把加载器
+/// 丢掉（磁贴会显示「原版」——M122 的用户可见症状）；以及继承链根取错（磁贴的版本号）。
+/// 抓不住：实例页真出图（走 app-iced 的视图模型与 `loader_badge`，本 crate 不渲染）；
+/// 也抓不住「真下载安装了 Fabric/Quilt/Forge/NeoForge」——这里只伪造落盘结果。
+#[test]
+fn own_installed_instances_snapshot_carries_their_loader() {
+    let dir = std::env::temp_dir().join(format!("ull-host-game-own-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    let env = HostEnv::at_root(&dir);
+    std::fs::create_dir_all(env.layout.config()).expect("config 目录");
+
+    let cases = [
+        (
+            "1.20.4-fabric-0.16.5",
+            "1.20.4",
+            LoaderKind::Fabric,
+            "Fabric 0.16.5",
+        ),
+        (
+            "1.20.4-quilt-0.27.0",
+            "1.20.4",
+            LoaderKind::Quilt,
+            "Quilt 0.27.0",
+        ),
+        (
+            "1.20.1-forge-47.2.0",
+            "1.20.1",
+            LoaderKind::Forge,
+            "Forge 47.2.0",
+        ),
+        (
+            "1.21.1-neoforge-21.1.80",
+            "1.21.1",
+            LoaderKind::NeoForge,
+            "NeoForge 21.1.80",
+        ),
+    ];
+    for (version_id, mc_version, _, _) in cases {
+        for (id, inherits) in [(mc_version, None), (version_id, Some(mc_version))] {
+            let json = match inherits {
+                Some(parent) => format!(r#"{{"id":"{id}","inheritsFrom":"{parent}"}}"#),
+                None => format!(r#"{{"id":"{id}"}}"#),
+            };
+            let path = env.game.version_json(id);
+            std::fs::create_dir_all(path.parent().expect("版本目录")).expect("版本目录");
+            std::fs::write(&path, json).expect("写版本 JSON");
+        }
+    }
+
+    let profiles = ProfileList {
+        profiles: cases
+            .iter()
+            .map(
+                |(version_id, _, _, _)| unlucky_core::game::InstanceProfile {
+                    id: unlucky_core::game::ProfileId::generate(),
+                    name: format!("装好的 {version_id}"),
+                    version_id: (*version_id).to_string(),
+                    game_dir: None,
+                    running_dir: None,
+                    java_path: None,
+                    created_at: None,
+                    last_played_at: None,
+                    extra: BTreeMap::new(),
+                },
+            )
+            .collect(),
+        ..ProfileList::default()
+    };
+    unlucky_core::game::install::instance::write_profiles(&env.layout, &profiles).expect("写清单");
+
+    let snapshot = instances(&env);
+    assert_eq!(snapshot.len(), cases.len());
+    for ((version_id, mc_version, kind, badge), tile) in cases.iter().zip(&snapshot) {
+        assert_eq!(tile.version_id.as_str(), *version_id);
+        assert_eq!(
+            tile.mc_version.as_str(),
+            *mc_version,
+            "{version_id} 的版本号取错"
+        );
+        assert_eq!(tile.loader.kind, *kind, "{version_id} 的加载器");
+        assert_eq!(tile.loader.badge().as_str(), *badge, "{version_id} 的徽标");
+        assert!(tile.version_present, "{version_id} 的载荷应当存在");
+    }
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+#[test]
+fn isolation_write_then_read_round_trips() {
+    let dir = std::env::temp_dir().join(format!("ull-host-game-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    let env = HostEnv::at_root(&dir);
+    std::fs::create_dir_all(env.layout.config()).expect("config 目录");
+
+    // 直接建一份 profiles.json（register 需要版本本体，这里只测隔离写读）
+    let profiles = ProfileList {
+        profiles: vec![unlucky_core::game::InstanceProfile {
+            id: unlucky_core::game::ProfileId::generate(),
+            name: "demo".to_string(),
+            version_id: "1.20.1".to_string(),
+            game_dir: None,
+            running_dir: None,
+            java_path: None,
+            created_at: None,
+            last_played_at: None,
+            extra: BTreeMap::new(),
+        }],
+        ..ProfileList::default()
+    };
+    unlucky_core::game::install::instance::write_profiles(&env.layout, &profiles).expect("写清单");
+    let id = profiles.profiles[0].id.as_str().to_string();
+
+    assert_eq!(isolation_of(&env, &id), "isolated");
+    set_isolation(&env, &id, "shared").expect("切档位");
+    assert_eq!(isolation_of(&env, &id), "shared");
+    assert!(set_isolation(&env, &id, "nope").is_err());
+    std::fs::remove_dir_all(&dir).ok();
+}
diff --git a/crates/presenter/src/host/handle.rs b/crates/presenter/src/host/handle.rs
new file mode 100644
index 0000000..f16ec1e
--- /dev/null
+++ b/crates/presenter/src/host/handle.rs
@@ -0,0 +1,261 @@
+//! `HostTask` → `CoreEvent` 的翻译（从 `host/mod.rs` 拆出，守 400 行硬限）。
+//!
+//! 父模块的私有字段对子模块可见，所以这里直接读写 `self.tx` / `self.launches` 等。
+
+use crate::dto::{AppEvent, CoreEvent, InstanceRuntime, LaunchFailureCause, LogOutcome, PackEvent};
+use crate::toast::ToastKind;
+
+use super::{addon, logs, mods, 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(failure) => self.send(CoreEvent::ContentFailed(Box::new(failure))),
+            },
+            // M162：详情/版本列表（与检索同一套失败分类）
+            HostTask::ContentDetail { project, result } => {
+                self.send(CoreEvent::ContentDetail { project, result });
+            }
+            // M113: import/export —— 导入/导出事件带代次，取消后回来的旧事件一律丢掉
+            HostTask::Pack { event, epoch } => {
+                // pack 用**自己**的代次（复审 r1 P2-7）：共用安装的计数器会让
+                // 「关一次导入面板」把下载页正在跑的安装静默丢掉。
+                if epoch != addon::pack_epoch(&self.env) {
+                    // 唯一例外（M195 r3）：**刚被取消的那一次**交上来的终态报告。取消会把代次
+                    // +1，若连报告一起丢，界面就永远学不到"取消太晚、其实已经装完/回滚没做完"
+                    // 这个真相——只剩一句无条件的"已停手并回滚"。
+                    // 只放行 `Report`、且同一代次只放行一条；进度事件照旧按代次丢。
+                    if !(matches!(&*event, PackEvent::Report(_))
+                        && addon::take_terminal_epoch(&self.env, epoch))
+                    {
+                        return;
+                    }
+                }
+                // 导入成功可能登记了新实例：与 `InstallDone` 同一条刷新（复审 r1 P2-1），
+                // 否则新实例要等下一次无关的 `RefreshAll` 才出现在实例页与目标 chips 里。
+                if matches!(*event, PackEvent::Report(_)) {
+                    self.refresh_instances();
+                }
+                self.send(CoreEvent::Pack(event));
+            }
+            // M105 的形状（代次丢包）为准：旧任务（已取消 / 被下一轮顶掉）的进度一律丢掉。
+            // 这是「点了取消没反应」的根因：取消时 `InstallProgress(None)` 刚把面板收回，
+            // 旧任务的下一条「下载中」事件立刻又把它点亮。
+            HostTask::Adopt { event, epoch } => self.handle_adopt(*event, epoch),
+            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)));
+                    }
+                    // 只把**一句人读原因**弹出去：大类已经随 `progress.failure_kind` 进了 DTO，
+                    // 面板/调用方按大类决定怎么画（离线 vs 查无此项）。
+                    Err(failure) => self.toast(ToastKind::Error, failure.detail),
+                }
+            }
+            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
+                            .layout
+                            .game_logs()
+                            .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 盖掉。
+                    //
+                    // 原因**按形状**组装（复审 P1-1）：`failure` 有值 = 进程没起来（阶段失败）；
+                    // 没值 = 跑起来了，那就必须看 `outcome`（崩溃 / 疑似静默失败），
+                    // 不许再拿「启动游戏进程失败」去顶——那句话在进程明明起来时说不过去。
+                    let cause = LaunchFailureCause::of(
+                        finished.outcome,
+                        finished.failure.as_ref(),
+                        finished.exit_code,
+                    );
+                    self.failed.insert(finished.id.clone(), cause.clone());
+                    InstanceRuntime::Failed { cause }
+                };
+                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),
+            // M159：更新回报（检查结论 / 应用结局）→ 快照整体替换
+            HostTask::Update(report) => {
+                self.update.adopt(*report);
+                self.publish_update();
+            }
+            // M224：本地 Mod 列表 / 启停。列表成功 ⇒ 整份快照替换；失败 ⇒ 具名原因给 app 求文案。
+            // 启停**不做乐观回显**：开关跟着这一份快照翻（与启动/停止同一条纪律）。
+            HostTask::Mods(report) => {
+                let mods::Report {
+                    instance,
+                    list,
+                    toggled,
+                } = *report;
+                if let Some(toggled) = toggled {
+                    // 只留一行日志：开关自己会跟着快照翻，再弹 Toast 是噪音。
+                    eprintln!(
+                        "[mods] {instance}: {} → {} ({})",
+                        toggled.from,
+                        toggled.to,
+                        if toggled.enabled {
+                            "enabled"
+                        } else {
+                            "disabled"
+                        }
+                    );
+                }
+                self.send(CoreEvent::Mods(Box::new(list)));
+            }
+            // M235：实例存档 / 截图的只读列表。成功 ⇒ 整份快照；失败 ⇒ 具名原因给 app 求文案。
+            // 「打开文件夹」也是这条：拉起文件管理器之后再回一份新鲜快照（用户在那边删了世界，
+            // 切回来这一拍就跟上）。
+            HostTask::Saves(report) => {
+                self.send(CoreEvent::Saves(Box::new(report.list)));
+            }
+            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..e0b35f5
--- /dev/null
+++ b/crates/presenter/src/host/identity.rs
@@ -0,0 +1,116 @@
+//! 启动身份：选中账户 → `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::{LaunchFailureStage, LaunchFailureView, LogOutcome};
+
+use super::env::HostEnv;
+
+/// 把选中账户翻成启动占位符（**凭据只在这里读，读完即丢**）。
+///
+/// 微软轨：过期就静默续期并回写凭据（refresh_token 轮换，旧值作废）。
+///
+/// # Errors
+///
+/// 账户不存在/凭据类型不符/令牌过期且刷新失败时返回用户可读文案。
+pub fn resolve(
+    env: &HostEnv,
+    account: Option<&str>,
+) -> Result<(AuthPlaceholders, String), LaunchFailureView> {
+    let store = AccountStore::open(env.layout.auth_data());
+    let chosen = match account {
+        Some(key) => store
+            .find(key)
+            .cloned()
+            .ok_or_else(|| identity_failure(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(identity_failure(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| identity_failure(format!("离线账户解析失败：{error}")))?;
+            Ok((placeholders, line))
+        }
+        AccountKind::Microsoft => {
+            let Some(Credentials::Microsoft(session)) = store.credentials(&chosen.id) else {
+                return Err(identity_failure(format!(
+                    "账户 {} 的微软凭据缺失或类型不符，请重新登录",
+                    chosen.display_name()
+                )));
+            };
+            let auth = MicrosoftAuth::from_env()
+                .map_err(|error| identity_failure(format!("微软登录不可用：{error}")))?;
+            let (fresh, _) = block_on(auth.ensure_fresh(session))
+                .map_err(|error| identity_failure(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| identity_failure(format!("微软身份转换失败：{error}")))?;
+            Ok((placeholders, line))
+        }
+        AccountKind::AuthlibInjector => {
+            let Some(Credentials::AuthlibInjector(session)) = store.credentials(&chosen.id) else {
+                return Err(identity_failure(format!(
+                    "账户 {} 的第三方凭据缺失或类型不符",
+                    chosen.display_name()
+                )));
+            };
+            let placeholders = session
+                .to_placeholders()
+                .map_err(|error| identity_failure(format!("第三方身份转换失败：{error}")))?;
+            Ok((placeholders, line))
+        }
+    }
+}
+
+/// 账户/身份这一步的失败（阶段固定 `Identity`；`detail` 保留原始文案与本机错误）。
+fn identity_failure(detail: String) -> LaunchFailureView {
+    LaunchFailureView::new(LaunchFailureStage::Identity, detail)
+}
+
+/// `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..43310d4
--- /dev/null
+++ b/crates/presenter/src/host/install.rs
@@ -0,0 +1,307 @@
+//! 安装：新建实例向导 / 下载页「安装」→ 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/LiteLoader（五家，与 CLI 对齐）。OptiFine
+//! 仍没有安装管线（要跑外部 `optifine.Patcher` + 原地改 zip），在 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>,
+    cancel: &'a Arc,
+    journal: &'a Journal,
+}
+
+impl Job<'_> {
+    /// 把 core 的运行期告警与「清单被替换」写进安装日志（**M216 P2-2**）。
+    ///
+    /// 面板只有一行、Toast 4 秒就消失，安装日志是用户事后能自己回看的唯一渠道：动了共享
+    /// `.minecraft` 里那份 `versions//.json` 这件事必须先落在这里（issue #M216 复审
+    /// P2-2：`report.manifest` 以前零消费者，GUI 侧对用户完全静默）。
+    fn journal_report(&self, report: &InstallReport) {
+        for warning in &report.warnings {
+            self.journal.line(warning);
+        }
+        if let Some(backup) = report.manifest.as_ref().and_then(|write| write.backup()) {
+            self.journal.line(&format!(
+                "版本清单已替换，旧的那份备份在 {}",
+                backup.display()
+            ));
+        }
+    }
+
+    /// 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
+            | LoaderKind::LiteLoader
+    )
+}
+
+/// 不支持的加载器 → 给用户的可执行建议。
+pub fn unsupported_reason(kind: LoaderKind) -> String {
+    format!(
+        "{} 还没有接入安装管线（目前支持原版 + Fabric/Quilt/Forge/NeoForge/LiteLoader）；如果别的启动器已经装好了这个版本，可以在实例页用「导入已有版本」把它只读接进来（不复制文件），否则请换成受支持的加载器。",
+        kind.label()
+    )
+}
+
+/// 后台安装（向导提交 / 下载页行内安装共用）。
+///
+/// `epoch` 是本次任务的代次（[`super::CoreHost`] 的 `install_epoch`）：它随每条进度回流，
+/// 让 host 丢掉「已被取消 / 被下一轮顶掉」的旧任务的后续事件。
+pub fn spawn_install(
+    env: HostEnv,
+    tx: JobSender,
+    request: CreateRequest,
+    cancel: Arc,
+    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);
+                // 版本安装这条路的失败不是内容库的分类（它是本地/运行期错误），归到 Other：
+                // 大类字段仍然要填，面板才不会把「装坏了」误画成「没联网」。
+                progress.failure_kind = Some(crate::dto::ContentFailureKind::Other);
+                let _ = tx.send(HostTask::InstallDone {
+                    progress: Box::new(progress),
+                    result: Err(crate::dto::ContentFailure::new(
+                        crate::dto::ContentFailureKind::Other,
+                        text,
+                    )),
+                    epoch,
+                });
+            }
+        }
+    });
+}
+
+/// 真安装（同步跑完，调用方在后台线程里）。
+fn run(job: &Job<'_>, request: &CreateRequest) -> Result {
+    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 = 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..a6f0432
--- /dev/null
+++ b/crates/presenter/src/host/install/routes.rs
@@ -0,0 +1,188 @@
+//! 两条安装路线（原版 / 加载器）——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 {
+    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))?;
+        job.journal_report(&report);
+        ensure_complete(&report)?;
+        Ok::(version.to_string())
+    })
+}
+
+/// 加载器安装（原版前置 → installer processors → 加载器库 → 版本 JSON 落盘）。
+pub(super) fn install_loader(
+    job: &Job<'_>,
+    engine: &DownloadEngine,
+    request: &CreateRequest,
+) -> Result {
+    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(),
+        // 向导/下载页只能装「叠在原版上」的层（CreateRequest 没有父版本槽位），
+        // 所以父版本恒等于原版版本；真装缺原版时由下面的 `vanilla_install_needed` 补装。
+        parent_installed: env.game.is_version_installed(&release.parent_version_id),
+    })
+    .map_err(|error| error.to_string())?;
+    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))?;
+    job.journal_report(&report);
+    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,
+    ) -> InstallReport;
+    /// 按 M33 的解析链挑一个能跑 installer 的 Java。
+    fn select_java(&self, managed: &Path, requirement: &JavaRequirement) -> Option;
+    /// 串行跑 processors。
+    fn run(
+        &self,
+        plan: &ProcessorPlan,
+        java: &JavaRuntime,
+        sink: Option,
+    ) -> Result;
+}
+
+/// 真实后端：三件事全部转调 core 的同一个执行器（CLI 用的就是它）。
+pub(super) struct CoreBackend;
+
+impl Backend for CoreBackend {
+    fn download_libraries(
+        &self,
+        engine: &DownloadEngine,
+        files: &[PlanFile],
+        sink: Option,
+    ) -> InstallReport {
+        block_on(processors::download_libraries(
+            engine,
+            files,
+            CONCURRENCY,
+            sink,
+        ))
+    }
+
+    fn select_java(&self, managed: &Path, requirement: &JavaRequirement) -> Option {
+        processors::select_java(managed, requirement)
+    }
+
+    fn run(
+        &self,
+        plan: &ProcessorPlan,
+        java: &JavaRuntime,
+        sink: Option,
+    ) -> Result {
+        processors::run(plan, java, sink)
+    }
+}
+
+/// 段内的进度出口：进度面板（`HostTask::Install`）+ 装日志。
+pub(super) struct Reporter<'a> {
+    /// 后台线程 → host 的通道。
+    pub tx: &'a JobSender,
+    /// 进度记账器。
+    pub meter: &'a Arc>,
+    /// 装日志。
+    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,
+) -> Result, 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>, 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 = 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::()
+        .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..9cc4a06
--- /dev/null
+++ b/crates/presenter/src/host/install_processors_fixture.rs
@@ -0,0 +1,273 @@
+//! 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, usize);
+
+/// 一段 cases 的公共环境：临时数据根 + 引擎 + 进度通道。
+pub(super) struct Harness {
+    dir: PathBuf,
+    pub(super) env: HostEnv,
+    pub(super) engine: Arc,
+    tx: JobSender,
+    rx: Receiver,
+    pub(super) meter: Arc>,
+    pub(super) journal: Journal,
+    pub(super) cancel: Arc,
+}
+
+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 {
+        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,
+    pub(super) run_error: Option,
+    calls: RefCell>,
+    steps: RefCell>,
+}
+
+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 {
+        self.steps.borrow().clone()
+    }
+}
+
+impl Backend for Fake {
+    fn download_libraries(
+        &self,
+        _engine: &DownloadEngine,
+        files: &[PlanFile],
+        _sink: Option,
+    ) -> 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,
+            manifest: None,
+            warnings: Vec::new(),
+        }
+    }
+
+    fn select_java(&self, _managed: &Path, _requirement: &JavaRequirement) -> Option {
+        self.calls.borrow_mut().push("java");
+        self.java.clone()
+    }
+
+    fn run(
+        &self,
+        plan: &ProcessorPlan,
+        java: &JavaRuntime,
+        sink: Option,
+    ) -> Result {
+        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 = 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..9e3b0d7
--- /dev/null
+++ b/crates/presenter/src/host/install_processors_tests.rs
@@ -0,0 +1,214 @@
+//! 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 = (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,
+        manifest: 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..a16e17c
--- /dev/null
+++ b/crates/presenter/src/host/install_tests.rs
@@ -0,0 +1,219 @@
+//! 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>,
+    cancel: Arc,
+    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,
+        // M222：LiteLoader 走「官方版本表 + 从零合成 launchwrapper 清单」，不跑外部进程。
+        LoaderKind::LiteLoader,
+    ] {
+        assert!(supported(kind), "{} 应当受支持", kind.label());
+    }
+    // OptiFine 仍没有安装管线（要跑外部 Patcher + 原地改 zip），显式拒装并说清可替代做法。
+    let optifine = LoaderKind::OptiFine;
+    assert!(!supported(optifine), "{} 不该被当成可装", optifine.label());
+    let reason = unsupported_reason(optifine);
+    assert!(reason.contains(optifine.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..691bd81
--- /dev/null
+++ b/crates/presenter/src/host/java.rs
@@ -0,0 +1,308 @@
+//! 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 {
+    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::>()
+                    .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 {
+    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(),
+        JdkVendor::Termux => unlucky_core::game::java::termux::MIRRORS
+            .iter()
+            .map(|mirror| format!("{mirror}（系统包：pkg install openjdk-）"))
+            .collect(),
+    }
+}
+
+/// 本地运行时（托管 / JAVA_HOME / PATH / 系统安装位置，同一路径只留优先级高者）。
+pub fn runtimes(env: &HostEnv) -> Vec {
+    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 {
+    super::engine::java_scan_roots(env)
+        .iter()
+        .map(|root| root.display().to_string())
+        .collect()
+}
+
+/// 计划链（按生效顺序铺「待尝试」）。
+pub fn planned_chain(env: &HostEnv) -> Vec {
+    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 {
+    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, busy: bool, message: &str) -> JavaPageView {
+    let runtimes = runtimes(env);
+    let installed_vendors: Vec = 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::>()
+            .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) {
+    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..c8ffec5
--- /dev/null
+++ b/crates/presenter/src/host/job.rs
@@ -0,0 +1,201 @@
+//! 后台任务的回流消息：`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,
+    ContentDetail,
+    ContentFailure,
+    ContentResults,
+    DeviceLoginView,
+    DiagnosisReport,
+    InstallProgressView,
+    InstanceId,
+    InstanceRuntime,
+    JavaPageView,
+    LaunchFinished,
+    LiveLogBatch,
+    LoaderKind,
+    LogLine,
+    LogSession,
+    NoticeView,
+    PackEvent,
+    SessionId,
+    SkinImage,
+    VersionSummary,
+};
+use crate::toast::Toast;
+
+/// 后台任务 → host 的消息。
+#[derive(Debug, Clone, PartialEq)]
+pub enum HostTask {
+    /// 版本清单（下载页）
+    Versions(Result, String>),
+    /// 加载器版本清单（下载页「安装选项」的下拉）
+    LoaderVersions {
+        /// 加载器种类
+        kind: LoaderKind,
+        /// 目标原版版本（缓存键的一部分，回传原样）
+        mc_version: String,
+        /// `Ok(最新在前)` / `Err(人读原因)`
+        result: Result, String>,
+    },
+    /// 内容库检索（M109；`Err` = 失败大类 + 一句人读原因）
+    Content(Box>),
+    /// 内容库项目详情 + 版本列表（M162）：项目 id 随载荷一起回来（迟到结果靠它判）
+    ContentDetail {
+        /// 请求时选中的项目 id
+        project: String,
+        /// `Ok` = 详情；`Err` = 失败大类 + 原因
+        result: Box>,
+    },
+    // M113: import/export
+    /// 导入/导出（M113）：一条事件 + 任务代次
+    ///
+    /// 代次是 **pack 自己的一条**（`host::addon::pack` 的 `pack_epoch()`，按 host 分开），**不**与
+    /// [`HostTask::Install`] 的 `CoreHost::install_epoch` 共用 —— 共用会让「关一次导入面板」
+    /// 把下载页正在跑的安装静默丢掉（复审 r1 P2-7）。取消/关面板之后回来的旧事件按这条代次
+    /// 丢掉，面板不会被重新点亮。
+    Pack {
+        /// 事件载荷（进度 / 结果 / 探测诊断 / 预检 / 完成）
+        event: Box,
+        /// 任务代次
+        epoch: u64,
+    },
+    // M223: 导入已有版本
+    /// 扫描 / 预检 / 确认的结果（一条事件 + 任务代次）
+    ///
+    /// 代次是 adopt 自己的（`CoreHost::adopt_epoch`），**不**与安装或 pack 的代次共用：
+    /// 关一次导入面板不该把下载页在跑的安装静默丢掉。
+    Adopt {
+        /// 事件载荷（扫描 / 预检 / 完成 / 失败）
+        event: Box,
+        /// 任务代次
+        epoch: u64,
+    },
+    /// 安装进度（高频，host 只做聚合与转发）
+    Install {
+        /// 进度快照
+        progress: Box,
+        /// 任务代次（[`super::CoreHost`] 的 `install_epoch`）
+        ///
+        /// 取消/重新开工都会把代次 +1，于是**旧任务还在飞的事件**带着旧代次回来，
+        /// host 一眼就能认出来并丢掉。没有这一层的话：取消后 `InstallProgress(None)` 刚把面板
+        /// 收回，下一条「下载中」事件立刻把它点亮——用户看到的就是「点了取消没反应」（M105 实测）。
+        epoch: u64,
+    },
+    /// 安装收尾（成功带实例名，失败带**大类 + 文案**）
+    InstallDone {
+        /// 最终进度快照
+        progress: Box,
+        /// 成功时为 `Ok(实例名)`；失败时带分类（离线 ≠ 查无此项）
+        result: Result,
+        /// 任务代次（语义同 [`HostTask::Install`] 的 `epoch`）
+        epoch: u64,
+    },
+    /// 账户列表
+    Accounts(Vec),
+    /// 设备码登录状态
+    Login(Box),
+    /// 第三方轨（authlib-injector）登录/校验状态
+    Authlib(Box),
+    /// 账户皮肤抓取结果（`skin = None` = 没取到；UI 退回首字母块）
+    Avatar {
+        /// 账户 id
+        id: String,
+        /// 皮肤原图
+        skin: Option,
+    },
+    /// Java 页（发行版/回退链/运行时）
+    Java(Box),
+    /// 日志页快照（会话列表 + 选中会话的行 + 诊断）
+    Logs {
+        /// 会话列表
+        sessions: Vec,
+        /// 选中会话的行
+        lines: Vec,
+        /// 诊断结论
+        diagnosis: Option,
+    },
+    /// 实时日志增量
+    Tail(Box),
+    /// 启动开始（pid + 会话 id）
+    LaunchStarted {
+        /// 实例 id
+        id: InstanceId,
+        /// 会话 id
+        session_id: SessionId,
+        /// 进程号
+        pid: u32,
+    },
+    /// 启动阶段推进（磁贴进度环）
+    Runtime {
+        /// 实例 id
+        id: InstanceId,
+        /// 阶段状态
+        runtime: InstanceRuntime,
+    },
+    /// 启动收尾
+    LaunchEnd(Box),
+    /// 崩溃日志导入的分析结论
+    Crash(Box),
+    /// 横幅通知（隔离切换提示等）
+    Notice(Box),
+    /// Toast
+    Toast(Box),
+    /// 会话列表刷新（只换左栏）
+    Sessions(Vec),
+    /// 自更新（M159）：检查/应用的回报（载荷已翻成 DTO，见 `host::update::Report`）
+    Update(Box),
+    /// 本地 Mod 列表 / 启停（M224）：列表快照或具名失败（见 `host::mods::Report`）
+    Mods(Box),
+    /// 实例存档 / 截图的只读列表（M235）：快照或具名失败（见 `host::saves::Report`）
+    Saves(Box),
+}
+
+/// 后台线程用的发送端（`Sender` 克隆即可）。
+pub type JobSender = Sender;
+
+/// host 侧的接收端。
+pub type JobReceiver = Receiver;
+
+/// 建一对通道。
+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}"))
+}
+
+#[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"));
+    }
+}
diff --git a/crates/presenter/src/host/launch.rs b/crates/presenter/src/host/launch.rs
new file mode 100644
index 0000000..68bc05c
--- /dev/null
+++ b/crates/presenter/src/host/launch.rs
@@ -0,0 +1,385 @@
+//! 启动全链：实例 → `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::crash_report::{self, CrashReport, ReportContext};
+use unlucky_core::launch::launcher_log;
+use unlucky_core::launch::request::{LaunchRequest, MemoryOptions};
+use unlucky_core::launch::time::{format_rfc3339_millis, now};
+use unlucky_core::launch::tree_kill;
+use unlucky_core::launch::{Launcher, LauncherConfig};
+
+use crate::dto::{
+    InstanceId, InstanceRuntime, LaunchFailureStage, LaunchFailureView, LaunchFinished,
+    LaunchStage, LogOutcome, Progress,
+};
+
+use super::env::HostEnv;
+
+mod java;
+
+use super::job::{HostTask, JobSender};
+pub use java::pick_java;
+
+/// 启动器名（与 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,
+}
+
+/// 装配 [`LaunchRequest`]（与 CLI `snapshot::prepare` 同序）。
+///
+/// # Errors
+///
+/// 任一步失败都返回 [`LaunchFailureView`]：**阶段**（版本 JSON / 继承链 / 实例设置 / 隔离目录 /
+/// 账户）+ 那一步的原文。文案不在这一层拼（presenter 不依赖 `unlucky-i18n`）。
+pub fn build_request(
+    env: &HostEnv,
+    target: &LaunchTarget,
+) -> Result<(LaunchRequest, Vec), LaunchFailureView> {
+    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| {
+        LaunchFailureView::new(
+            LaunchFailureStage::VersionManifest,
+            format!("{}：{error}", manifest_path.display()),
+        )
+    })?;
+    let manifest = VersionJson::from_json_str(&text).map_err(|error| {
+        LaunchFailureView::new(
+            LaunchFailureStage::VersionManifest,
+            format!("{}：{error}", manifest_path.display()),
+        )
+    })?;
+    let source = |id: &str| -> Option {
+        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| {
+        LaunchFailureView::new(LaunchFailureStage::Inheritance, error.to_string())
+    })?;
+
+    let environment = Environment::host();
+    let expanded = resolved
+        .arguments
+        .as_ref()
+        .map(|arguments| arguments.expand(&environment))
+        .unwrap_or_default();
+
+    let mut libraries: Vec = Vec::new();
+    for library in resolved.libraries.as_deref().unwrap_or_default() {
+        if !library.applies(&environment) {
+            continue;
+        }
+        // 1.19+ 的 natives 是独立库条目（name 带分类器），必须进 classpath；
+        // ≤1.18 的 `natives` 表条目归 natives::collect，不进 classpath。
+        // Linux arm64：独立条目改写成 natives-linux-arm64（路径与展示名一起改）。
+        let arm64 = library.linux_arm64_native_name(&environment);
+        if arm64.is_none() && library.native_classifier(&environment).is_some() {
+            continue;
+        }
+        let (coordinate, name) = match arm64 {
+            Some(rewritten) => {
+                let Ok(coordinate) =
+                    unlucky_core::game::library::MavenCoordinate::parse(&rewritten)
+                else {
+                    continue;
+                };
+                (coordinate, rewritten)
+            }
+            None => {
+                let Ok(coordinate) = library.coordinate() else {
+                    continue;
+                };
+                (coordinate, library.name.clone())
+            }
+        };
+        let path = if library.is_local() {
+            env.game.version_library(&version_id, &coordinate)
+        } else {
+            env.game.library(&coordinate)
+        };
+        libraries.push(LibraryInput::new(path, name));
+    }
+    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()));
+    // 装配的门限 / 分支按**继承链的 MC 根版本**判，不是带加载器后缀的 version_id：
+    // `26w14a-fabric-0.16.5` 这种 id 在 `GameVersion::is_weekly_snapshot`（6 字符形态）上判不出来，
+    // 周快照的 `--graphicsBackend` 会在拼装链里被静默跳过——而详情页的门槛
+    // （`host::launch_args::backend_gate`）与 CLI 用的都是根版本，两边必须同一口径。
+    let (mc_version, _) = super::game::describe_version(env, &version_id);
+    let snapshot = SnapshotInput {
+        version_id: &version_id,
+        version_name: Some(&target.name),
+        version_type: None,
+        game_version: Some(mc_version.as_str()),
+        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 overrides = super::launch_args::resolved(env, &target.id);
+    let java = pick_java(env, &version_id, overrides.java_path.as_deref());
+    let (auth, identity_line) = super::identity::resolve(env, target.account.as_deref())?;
+    let options = AdapterOptions {
+        java: java.selection,
+        memory: MemoryOptions {
+            min_mb: None,
+            max_mb: Some(overrides.memory_mb),
+        },
+        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 = 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();
+    // 实例级启动参数（三级回落后的生效值）最后落位：user.* / memory / graphics_backend。
+    unlucky_core::launch::overrides::apply(&mut request, &overrides);
+    Ok((request, warnings))
+}
+
+/// 派生运行目录（D20 覆盖链：实例 `isolation` > 全局 `instances.mode`）。
+fn run_dir(env: &HostEnv, target: &LaunchTarget) -> Result {
+    let global = super::game::global_mode(env);
+    let config = read_instance_config(&env.layout, &target.id).map_err(|error| {
+        LaunchFailureView::new(LaunchFailureStage::InstanceConfig, error.to_string())
+    })?;
+    let derivation = derive_game_dir(&env.game, &target.version_id, global, config.as_ref(), None)
+        .map_err(|error| {
+            LaunchFailureView::new(LaunchFailureStage::Isolation, error.to_string())
+        })?;
+    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 || {
+        // M187：启动器自己的运行日志从这里开始有落点（早于这一拍的行由 core 缓冲接住）。
+        // M188 起 presenter 在构造 `HostEnv` 时已经登记过目录（缓冲那时就刷出去了），这里是
+        // 幂等的一次兜底：数据根被 `redirect.json` 改过时以最后一次为准。
+        let logs_dir = env.layout.logs();
+        launcher_log::set_dir(&logs_dir);
+        let started_at = std::time::SystemTime::now();
+        let mut report = ReportContext::new(
+            &target.id,
+            &target.name,
+            &target.version_id,
+            &env.data.game_home,
+            &logs_dir,
+            started_at,
+            unlucky_core::platform::os_info::current().summary_line(),
+        );
+        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(failure) => {
+                let line = format!("instance={} 装配失败：{}", target.id, failure.detail);
+                launcher_log::record("launch", &line);
+                publish_before_start(&report, failure.stage.slug(), &failure.detail);
+                let _ = tx.send(HostTask::LaunchEnd(Box::new(LaunchFinished {
+                    id,
+                    session: String::new(),
+                    outcome: LogOutcome::Crashed,
+                    exit_code: None,
+                    uptime_ms: 0,
+                    failure: Some(failure),
+                })));
+                return;
+            }
+        };
+        report.run_dir = request.dirs.game_dir.clone();
+        report.version_json = Some(env.game.version_json(&target.version_id));
+        report.java = launcher_log::java_label(&request.java.binary, request.java.major);
+        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,
+            ))));
+        }
+        // 命令行（脱敏版）进启动器日志：事故之后「到底用什么参数起的」是第一个要看的。
+        // M211/D5：`ull launch` 写同一个文件的同一行（格式在 core 的 `launcher_log` 里）。
+        launcher_log::record_start(
+            &target.id,
+            &report.run_dir,
+            Some((request.java.binary.as_path(), request.java.major)),
+            request.memory.max_mb,
+        );
+        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 failure = LaunchFailureView::new(LaunchFailureStage::Spawn, error.to_string());
+                launcher_log::record(
+                    "launch",
+                    &format!("instance={} spawn 失败：{error}", target.id),
+                );
+                publish_before_start(&report, "spawn", &failure.detail);
+                let _ = tx.send(HostTask::LaunchEnd(Box::new(LaunchFinished {
+                    id,
+                    session: String::new(),
+                    outcome: LogOutcome::Crashed,
+                    exit_code: None,
+                    uptime_ms: 0,
+                    failure: Some(failure),
+                })));
+                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);
+                launcher_log::record_end(&target.id, &handle);
+                report.secrets.push(session_id.clone());
+                let lines: Vec = super::logs::read_lines(&handle.log_path)
+                    .into_iter()
+                    .map(|line| line.text)
+                    .collect();
+                crash_report::publish(CrashReport::collect(&handle, &report, &lines));
+                let _ = tx.send(HostTask::LaunchEnd(Box::new(LaunchFinished {
+                    id,
+                    session: session_id,
+                    outcome,
+                    exit_code: Some(handle.exit.code),
+                    uptime_ms: handle.uptime_ms,
+                    // 跑起来再崩不算「装配失败」：结局由 `outcome` 表达，这里留 `None`。
+                    failure: None,
+                })));
+            }
+            Err(error) => {
+                let failure = LaunchFailureView::new(LaunchFailureStage::Spawn, error.to_string());
+                let line = format!(
+                    "instance={} session={session_id} 收尾失败：{error}",
+                    target.id
+                );
+                launcher_log::record("launch", &line);
+                publish_before_start(&report, "spawn", &failure.detail);
+                let _ = tx.send(HostTask::LaunchEnd(Box::new(LaunchFinished {
+                    id,
+                    session: session_id,
+                    outcome: LogOutcome::SilentFail,
+                    exit_code: None,
+                    uptime_ms: 0,
+                    failure: Some(failure),
+                })));
+            }
+        }
+    });
+}
+
+/// 登记一次「进程没起来」的现场（四个失败出口共用这一处，避免各写一遍 exit_type）。
+fn publish_before_start(report: &ReportContext, stage: &str, detail: &str) {
+    crash_report::publish(CrashReport::before_start(report, stage, detail, stage));
+}
+
+/// 停止一次启动（按 pid 回收进程树；`finish()` 会在后台线程里照常收尾）。
+pub fn stop(pid: u32) -> Result<(), String> {
+    tree_kill::kill_tree(pid, std::time::Duration::from_secs(3))
+        .map_err(|error| format!("停止进程 {pid} 失败：{error}"))
+}
+
+/// 适配层告警 → 人读一行。
+fn describe_warning(warning: &AdapterWarning) -> String {
+    match warning {
+        AdapterWarning::MissingLibrary { name, path } => {
+            format!("缺少库文件 {name}（{}）", path.display())
+        }
+        AdapterWarning::MissingGameArguments => "版本 JSON 没有游戏参数".to_string(),
+        AdapterWarning::MissingAssetsIndex => "版本 JSON 没有资源索引".to_string(),
+        AdapterWarning::MissingMainClass => "版本 JSON 没有 mainClass".to_string(),
+        AdapterWarning::MissingNativeJar { name, path } => {
+            format!("缺少 natives 构件 {name}（{}）", path.display())
+        }
+    }
+}
+
+/// 隔离档位的展示串（`isolated` / `shared`）。
+pub fn isolation_label(mode: IsolationMode) -> &'static str {
+    mode.as_str()
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/presenter/src/host/launch/java.rs b/crates/presenter/src/host/launch/java.rs
new file mode 100644
index 0000000..9a84f49
--- /dev/null
+++ b/crates/presenter/src/host/launch/java.rs
@@ -0,0 +1,88 @@
+//! 「用哪个 Java」：显式路径（实例 → 全局）> 托管 > JAVA_HOME > PATH（M161 从 `host/launch.rs` 拆出）。
+//!
+//! 拆出的理由与其它 400 行拆分一致：`host/launch.rs` 到线了，而「挑 Java」本来就是独立一段。
+//! 口径没变（见原文件与 `core::game::java` 的文档）：显式路径**先探测**，探测失败按版本要求的
+//! 基准主版本兜底——启动路径不该因为探测不到就拒绝启动。
+
+use std::path::PathBuf;
+
+use unlucky_core::launch::request::JavaSelection;
+use unlucky_core::platform::paths::ProcessEnv;
+
+use super::super::env::HostEnv;
+
+/// 选中并用起来的 Java（`summary` 给 UI 一行提示）。
+pub struct JavaPick {
+    /// 交给 adapter 的选择
+    pub selection: JavaSelection,
+    /// 人读一行
+    pub summary: String,
+}
+
+/// 选一个能用的 Java：显式路径（实例 → 全局 `java.selected_path`）> 托管 > JAVA_HOME > PATH。
+///
+/// 显式路径**先探测**（`java -version`）：探测失败不报错，按版本要求的基准主版本兜底——
+/// 与自动挑的退路同一口径（启动路径不该因为探测不到就拒绝启动）。
+pub fn pick_java(env: &HostEnv, version_id: &str, explicit: Option<&std::path::Path>) -> JavaPick {
+    let store = env.store();
+    let required = unlucky_core::game::java::requirement_for_version(&env.game, version_id);
+    if let Some(path) = explicit {
+        let runtime = unlucky_core::game::java::probe::probe(
+            path,
+            unlucky_core::game::java::probe::JavaOrigin::Instance,
+        );
+        let major = runtime.major.unwrap_or(required.minimum);
+        return JavaPick {
+            selection: JavaSelection::new(runtime.binary.clone(), major, runtime.bits),
+            summary: format!(
+                "实例指定 Java {}（{}）",
+                runtime.version.clone().unwrap_or_else(|| major.to_string()),
+                path.display()
+            ),
+        };
+    }
+    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 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} 启动）"),
+            }
+        }
+    }
+}
diff --git a/crates/presenter/src/host/launch/tests.rs b/crates/presenter/src/host/launch/tests.rs
new file mode 100644
index 0000000..93207b2
--- /dev/null
+++ b/crates/presenter/src/host/launch/tests.rs
@@ -0,0 +1,96 @@
+//! `host::launch` 的回归用例（M157 r3 复审 P2-1）：装配用的游戏版本必须是**继承链的 MC 根版本**。
+
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+
+use super::*;
+
+/// 一次性临时目录（同 `host::launch_args` 测试：不引第三方 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-host-launch-{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);
+    }
+}
+
+fn write_version(env: &HostEnv, id: &str, json: &str) {
+    let path = env.game.version_json(id);
+    std::fs::create_dir_all(path.parent().expect("版本目录")).expect("版本目录");
+    std::fs::write(&path, json).expect("写版本 JSON");
+}
+
+/// **周快照 + 加载器实例**的装配：`SnapshotInput.game_version` 要拿继承链根的 `26w14a`，
+/// 不是带加载器后缀的 `26w14a-fabric-0.16.5`。
+///
+/// 抓得住：`build_request` 回退成 `game_version: None`（装配链用 `version_id` 判门限）——
+/// 那时 `GameVersion::is_weekly_snapshot` 的 6 字符形态认不出这个 id，`--graphicsBackend`
+/// 会在拼装链里被静默跳过，而详情页的门槛（`host::launch_args::backend_gate`，用根版本）
+/// 显示「可用」——正是复审复现的「UI 说能开、命令行里没有」。
+/// 抓不住：拼装本身（`crates/core/src/launch/overrides/tests.rs` 的
+/// `modded_weekly_snapshot_needs_the_root_version_for_the_gate` 出完整 argv）。
+#[test]
+fn weekly_loader_instance_assembles_against_the_mc_root_version() {
+    let dir = TempDir::new("weekly");
+    let env = HostEnv::at_root(dir.path());
+    std::fs::create_dir_all(env.layout.config()).expect("config 目录");
+
+    // 周快照本体：库表带 lwjgl-vulkan（能力位），主类齐全。
+    write_version(
+        &env,
+        "26w14a",
+        r#"{"id":"26w14a","type":"snapshot","mainClass":"net.minecraft.client.main.Main",
+            "libraries":[{"name":"org.lwjgl:lwjgl-vulkan:3.4.3"}]}"#,
+    );
+    // Fabric 层：只写自己的主类 + inheritsFrom（真实落盘形状）。
+    write_version(
+        &env,
+        "26w14a-fabric-0.16.5",
+        r#"{"id":"26w14a-fabric-0.16.5","inheritsFrom":"26w14a",
+            "mainClass":"net.fabricmc.loader.impl.launch.knot.KnotClient"}"#,
+    );
+
+    let target = LaunchTarget {
+        id: "inst-1".to_string(),
+        name: "周快照 Fabric".to_string(),
+        version_id: "26w14a-fabric-0.16.5".to_string(),
+        account: None,
+    };
+    let (request, _warnings) = build_request(&env, &target).expect("装配应成功");
+
+    assert_eq!(
+        request.instance.version.raw(),
+        "26w14a",
+        "装配用的游戏版本必须是继承链的 MC 根版本（带加载器后缀的 id 会让周快照门限失效）"
+    );
+    assert!(
+        request.instance.version.is_weekly_snapshot(),
+        "根版本要能被识别成周快照形态"
+    );
+    assert!(
+        request.manifest.has_vulkan_backend,
+        "能力位来自继承链解析后的库表（lwjgl-vulkan 在父层）"
+    );
+    assert!(
+        !request.instance.version.is_known(),
+        "周快照刻意不可排序（is_known=false），门限只能靠库表兜底"
+    );
+}
diff --git a/crates/presenter/src/host/launch_args.rs b/crates/presenter/src/host/launch_args.rs
new file mode 100644
index 0000000..2ab059c
--- /dev/null
+++ b/crates/presenter/src/host/launch_args.rs
@@ -0,0 +1,356 @@
+//! 实例启动参数：读（三级回落 + 版本门槛）与写（`launch` 段）。
+//!
+//! 本模块是 M157 的 host 侧唯一入口：
+//! - [`view`] → [`LaunchArgsView`]（详情页「启动参数」区）；
+//! - [`apply`] → 写回实例文件（`launch.*`），空输入清成「跟随」；
+//! - [`resolved`] → 启动装配用的生效值（[`ResolvedLaunch`]），CLI 的 `snapshot::prepare`
+//!   与 GUI 的 `host::launch` 都从这里取，避免两条装配链各算一遍回落。
+//!
+//! 判据都在 core，本文件只做三件事：读设置文档填 [`GlobalLaunchDefaults`]、读实例文件、
+//! 把 core 的结论翻成 DTO。
+
+use std::path::PathBuf;
+
+use unlucky_core::game::install::instance::{
+    read_instance_config, write_instance_config, InstanceConfig,
+};
+use unlucky_core::game::launch_overrides::{
+    resolve as resolve_overrides, GlobalLaunchDefaults, GraphicsBackend, LaunchOverrides,
+    LaunchOverridesPatch, ResolvedLaunch,
+};
+use unlucky_core::game::{self, VersionCapabilities, VersionJson};
+use unlucky_core::launch::game_args::{graphics_backend_allowed, GRAPHICS_BACKEND_MIN_VERSION};
+use unlucky_core::launch::game_version::GameVersion;
+
+use crate::dto::{LaunchArgsPatch, LaunchArgsView};
+
+use super::env::HostEnv;
+
+/// 全局层：`java.extra_args` / `java.default_memory_mb` / `java.selected_path`。
+///
+/// 另外两项（游戏参数、图形后端）本轮没有全局键——回落链照样成立（全局层为 `None`），
+/// 理由见 M157 的定案（不为它们单开全局键，免得与实例语义打架）。
+pub fn global_defaults(env: &HostEnv) -> GlobalLaunchDefaults {
+    let store = env.store();
+    let text = |key: &str| -> Option {
+        store
+            .doc()
+            .effective_str(key)
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+            .map(str::to_string)
+    };
+    GlobalLaunchDefaults {
+        jvm_args: text("java.extra_args"),
+        game_args: None,
+        memory_mb: store
+            .effective("java.default_memory_mb")
+            .and_then(serde_json::Value::as_u64)
+            .and_then(|value| u32::try_from(value).ok()),
+        java_path: text("java.selected_path").map(PathBuf::from),
+        graphics_backend: None,
+    }
+}
+
+/// 读实例文件的 `launch` 段（文件缺失 / 读失败 = 空段，不让详情页因此打不开）。
+fn instance_overrides(env: &HostEnv, instance_id: &str) -> LaunchOverrides {
+    if instance_id.is_empty() {
+        return LaunchOverrides::default();
+    }
+    read_instance_config(&env.layout, instance_id)
+        .ok()
+        .flatten()
+        .map(|config| config.launch)
+        .unwrap_or_default()
+}
+
+/// 三级回落后的生效值（启动装配与详情页共用同一份）。
+pub fn resolved(env: &HostEnv, instance_id: &str) -> ResolvedLaunch {
+    resolve_overrides(
+        Some(&instance_overrides(env, instance_id)),
+        &global_defaults(env),
+    )
+}
+
+/// 版本能力位（解析继承链之后取库表；读不到版本 JSON = 什么能力都没有）。
+fn capabilities(env: &HostEnv, version_id: &str) -> Option {
+    let text = std::fs::read_to_string(env.game.version_json(version_id)).ok()?;
+    let manifest = VersionJson::from_json_str(&text).ok()?;
+    let source = |id: &str| -> Option {
+        std::fs::read_to_string(env.game.version_json(id))
+            .ok()
+            .and_then(|text| VersionJson::from_json_str(&text).ok())
+    };
+    game::resolve(&source, &manifest).ok()
+}
+
+/// 该实例版本能不能下发 `--graphicsBackend`，以及判定所依据的游戏版本。
+///
+/// 判据是 core 的两件套（库表能力位 + 版本门槛），**UI 不复制**：
+/// `graphics_backend_allowed(GameVersion, has_vulkan_backend)`。
+pub fn backend_gate(env: &HostEnv, version_id: &str) -> (bool, String) {
+    let mc_version = super::game::describe_version(env, version_id).0;
+    let has_vulkan = capabilities(env, version_id)
+        .map(|json| VersionCapabilities::from_json(&json).has_vulkan_backend)
+        .unwrap_or(false);
+    let allowed = graphics_backend_allowed(&GameVersion::parse(&mc_version), has_vulkan);
+    (allowed, mc_version)
+}
+
+/// 详情页「启动参数」区的读取视图。
+pub fn view(env: &HostEnv, instance_id: &str, version_id: &str) -> LaunchArgsView {
+    let instance = instance_overrides(env, instance_id);
+    let effective = resolved(env, instance_id);
+    let (allowed, mc_version) = backend_gate(env, version_id);
+    LaunchArgsView {
+        instance_id: instance_id.to_string(),
+        jvm_args: instance.jvm_args.unwrap_or_default(),
+        game_args: instance.game_args.unwrap_or_default(),
+        memory_mb: instance.memory_mb,
+        memory_effective_mb: effective.memory_mb,
+        java_path: instance
+            .java_path
+            .map(|path| path.display().to_string())
+            .unwrap_or_default(),
+        java_effective: effective
+            .java_path
+            .map(|path| path.display().to_string())
+            .unwrap_or_default(),
+        graphics_backend: instance
+            .graphics_backend
+            .unwrap_or_default()
+            .as_str()
+            .to_string(),
+        graphics_backend_effective: effective.graphics_backend.as_str().to_string(),
+        graphics_backend_allowed: allowed,
+        mc_version,
+        graphics_backend_min_version: GRAPHICS_BACKEND_MIN_VERSION.to_string(),
+        graphics_backend_options: GraphicsBackend::IDS
+            .iter()
+            .map(|id| (*id).to_string())
+            .collect(),
+    }
+}
+
+/// 写回实例启动参数（`None` = 不改；`Some("")` = 清空回「跟随」）。
+///
+/// 校验（内存整数/范围、后端词表）在 core 的 [`LaunchOverridesPatch`] 里做一次，
+/// GUI 与 CLI 拿同一条错误文案。
+///
+/// # Errors
+///
+/// 实例不存在、值非法（内存越界 / 未知图形后端）、读写实例文件失败时返回用户可读文案。
+pub fn apply(
+    env: &HostEnv,
+    instance_id: &str,
+    version_id: &str,
+    patch: &LaunchArgsPatch,
+) -> Result<(), String> {
+    let core_patch = LaunchOverridesPatch {
+        jvm_args: patch.jvm_args.clone(),
+        game_args: patch.game_args.clone(),
+        memory_mb: patch.memory_mb.clone(),
+        java_path: patch.java_path.clone(),
+        graphics_backend: patch.graphics_backend.clone(),
+    };
+    let overrides = instance_overrides(env, instance_id).patched(&core_patch)?;
+
+    let mut config = read_instance_config(&env.layout, instance_id)
+        .map_err(|error| format!("读实例设置失败：{error}"))?
+        .unwrap_or_else(|| InstanceConfig::new(instance_id, version_id));
+    config.launch = overrides;
+    write_instance_config(&env.layout, &config)
+        .map(|_| ())
+        .map_err(|error| format!("写实例设置失败：{error}"))
+}
+
+/// 门槛判据里的最低版本常量（提示文案用；判据本身在 core）。
+pub fn min_version_hint() -> &'static str {
+    GRAPHICS_BACKEND_MIN_VERSION
+}
+
+impl super::CoreHost {
+    /// 写实例启动参数（先按 id 找档案拿 `versionId`，再落盘）。
+    ///
+    /// 实例必须已登记：没有档案时写 `config/instances/.json` 会造出一个孤立的设置文件，
+    /// 启动链根本不会读它（它按 `profiles.json` 找实例）。
+    pub(super) fn apply_launch_args(
+        &mut self,
+        id: &str,
+        patch: &LaunchArgsPatch,
+    ) -> Result<(), String> {
+        let profiles = super::game::profiles(&self.env);
+        let profile = profiles
+            .profiles
+            .iter()
+            .find(|profile| profile.id.as_str() == id)
+            .ok_or_else(|| format!("找不到实例 `{id}`"))?;
+        apply(&self.env, id, &profile.version_id, patch)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn env() -> (HostEnv, tempdir::Dir) {
+        let dir = tempdir::Dir::new("ull-launch-args");
+        let env = HostEnv::at_root(&dir.path);
+        std::fs::create_dir_all(env.layout.config()).expect("config 目录");
+        (env, dir)
+    }
+
+    /// 最小的 tempdir（与本 crate 其它 host 测试同款：不引第三方 tempfile）。
+    mod tempdir {
+        use std::path::{Path, PathBuf};
+        use std::sync::atomic::{AtomicU64, Ordering};
+
+        pub struct Dir {
+            pub path: PathBuf,
+        }
+
+        impl Dir {
+            pub fn new(tag: &str) -> Self {
+                // 每个用例一个目录：同一进程里跑多个用例时，只用 PID 命名会互相 `remove_dir_all`
+                // （并行跑就是「系统找不到指定的路径」——M157 r2 实测）。
+                static COUNTER: AtomicU64 = AtomicU64::new(0);
+                let seq = COUNTER.fetch_add(1, Ordering::Relaxed);
+                let path = std::env::temp_dir().join(format!("{tag}-{}-{seq}", std::process::id()));
+                let _ = std::fs::remove_dir_all(&path);
+                std::fs::create_dir_all(&path).expect("建临时目录");
+                Self { path }
+            }
+        }
+
+        impl Drop for Dir {
+            fn drop(&mut self) {
+                let _ = std::fs::remove_dir_all(Path::new(&self.path));
+            }
+        }
+    }
+
+    fn write_version(env: &HostEnv, id: &str, json: &str) {
+        let path = env.game.version_json(id);
+        std::fs::create_dir_all(path.parent().expect("版本目录")).expect("版本目录");
+        std::fs::write(&path, json).expect("写版本 JSON");
+    }
+
+    /// 26.2-snapshot-2 的库表里带 `lwjgl-vulkan`（与 `research/05-mc-vulkan.md` 一致）。
+    const VULKAN_VERSION: &str = r#"{
+        "id": "26.2-snapshot-2",
+        "libraries": [{"name": "org.lwjgl:lwjgl-vulkan:3.4.3"}]
+    }"#;
+
+    #[test]
+    fn gate_uses_core_capability_and_version_threshold() {
+        let (env, _dir) = env();
+        write_version(&env, "26.2-snapshot-2", VULKAN_VERSION);
+        let (allowed, mc) = backend_gate(&env, "26.2-snapshot-2");
+        assert!(allowed, "26.2-snapshot-2 应当放行");
+        assert_eq!(mc, "26.2-snapshot-2");
+
+        // 26.1：版本不够（即使库表里硬塞了 vulkan 也不放行——精确门限优先）。
+        write_version(&env, "26.1", VULKAN_VERSION);
+        let (allowed, mc) = backend_gate(&env, "26.1");
+        assert!(!allowed, "26.1 不该放行");
+        assert_eq!(mc, "26.1");
+
+        // 没有版本 JSON：能力位全假 ⇒ 不放行（不 panic）。
+        let (allowed, _) = backend_gate(&env, "1.20.4");
+        assert!(!allowed);
+    }
+
+    #[test]
+    fn write_then_read_round_trips_through_the_instance_file() {
+        let (env, _dir) = env();
+        let patch = LaunchArgsPatch {
+            jvm_args: Some("  -XX:+UseG1GC  ".to_string()),
+            game_args: Some("--fullscreen".to_string()),
+            memory_mb: Some("6144".to_string()),
+            java_path: Some("D:/jdk21/bin/java.exe".to_string()),
+            graphics_backend: Some("vulkan".to_string()),
+        };
+        apply(&env, "inst-1", "1.20.4", &patch).expect("写回");
+        let config = read_instance_config(&env.layout, "inst-1")
+            .expect("读回")
+            .expect("文件应存在");
+        assert_eq!(config.launch.jvm_args.as_deref(), Some("-XX:+UseG1GC"));
+        assert_eq!(config.launch.memory_mb, Some(6144));
+        assert_eq!(
+            config.launch.graphics_backend,
+            Some(GraphicsBackend::Vulkan)
+        );
+        assert_eq!(config.version_id, "1.20.4");
+
+        // 清空 = 跟随：`default` 与空串都把键抹掉。
+        let clear = LaunchArgsPatch {
+            jvm_args: Some(String::new()),
+            game_args: Some("   ".to_string()),
+            memory_mb: Some(String::new()),
+            java_path: Some(String::new()),
+            graphics_backend: Some("default".to_string()),
+        };
+        apply(&env, "inst-1", "1.20.4", &clear).expect("清空");
+        let config = read_instance_config(&env.layout, "inst-1")
+            .expect("读回")
+            .expect("文件应存在");
+        assert!(
+            config.launch.is_empty(),
+            "清空之后 launch 段应为空：{:?}",
+            config.launch
+        );
+        let raw = config.to_json_string().expect("序列化");
+        assert!(!raw.contains("\"launch\""), "空段不落盘：{raw}");
+    }
+
+    #[test]
+    fn invalid_values_are_rejected_not_silently_dropped() {
+        let (env, _dir) = env();
+        let bad_backend = LaunchArgsPatch::backend("vulkan2");
+        let error = apply(&env, "inst-1", "1.20.4", &bad_backend).expect_err("未知后端要报错");
+        assert!(error.contains("vulkan2"), "{error}");
+
+        let bad_memory = LaunchArgsPatch {
+            memory_mb: Some("999999".to_string()),
+            ..LaunchArgsPatch::default()
+        };
+        let error = apply(&env, "inst-1", "1.20.4", &bad_memory).expect_err("越界内存要报错");
+        assert!(error.contains("256"), "{error}");
+
+        let not_a_number = LaunchArgsPatch {
+            memory_mb: Some("4g".to_string()),
+            ..LaunchArgsPatch::default()
+        };
+        assert!(apply(&env, "inst-1", "1.20.4", ¬_a_number).is_err());
+
+        // 失败的写入不许留下半截文件。
+        assert!(read_instance_config(&env.layout, "inst-1")
+            .expect("读")
+            .is_none());
+    }
+
+    #[test]
+    fn view_reports_instance_layer_and_effective_values_apart() {
+        let (env, _dir) = env();
+        write_version(&env, "26.2-snapshot-2", VULKAN_VERSION);
+        // 只填图形后端：其余各项都是「跟随」，生效值要给得出来。
+        apply(
+            &env,
+            "inst-1",
+            "26.2-snapshot-2",
+            &LaunchArgsPatch::backend("vulkan"),
+        )
+        .expect("写回");
+        let view = view(&env, "inst-1", "26.2-snapshot-2");
+        assert_eq!(view.graphics_backend, "vulkan");
+        assert_eq!(view.graphics_backend_effective, "vulkan");
+        assert!(view.graphics_backend_allowed);
+        assert_eq!(view.instance_id, "inst-1");
+        assert_eq!(view.memory_mb, None);
+        assert_eq!(
+            view.memory_effective_mb,
+            unlucky_core::game::launch_overrides::DEFAULT_MAX_MEMORY_MB
+        );
+        assert_eq!(view.graphics_backend_options.len(), 3);
+    }
+}
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..6bff8e3
--- /dev/null
+++ b/crates/presenter/src/host/launch_state_tests.rs
@@ -0,0 +1,368 @@
+//! 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,
+        exit_code: Some(0),
+        uptime_ms: 12_500,
+        failure: None,
+    })));
+    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,
+        exit_code: Some(1),
+        uptime_ms: 3_000,
+        failure: None,
+    })));
+    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("实例存在");
+    // 跑起来又崩：原因是**结局**，不是「进程起不来」（复审 P1-1）。
+    // 抓得住：把崩溃塞回 `LaunchFailureStage::Spawn`（磁贴会说「启动游戏进程失败」，假话），
+    // 或者把退出码漏成 `Some(1)` 这种 Debug 文本（这里只认数字）。
+    assert_eq!(
+        failed.runtime,
+        InstanceRuntime::Failed {
+            cause: crate::dto::LaunchFailureCause::Crashed { exit_code: Some(1) }
+        },
+        "崩溃要如实报成「起来了又崩」，且经得住一次刷新"
+    );
+}
+
+#[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,
+        exit_code: None,
+        uptime_ms: 0,
+        failure: Some(crate::dto::LaunchFailureView::new(
+            crate::dto::LaunchFailureStage::Identity,
+            "找不到账户 `steve`",
+        )),
+    })));
+
+    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 {
+            cause: crate::dto::LaunchFailureCause::Stage {
+                stage: crate::dto::LaunchFailureStage::Identity,
+                detail: "找不到账户 `steve`".to_string()
+            }
+        },
+        "早失败（进程没起来）要留在阶段那一支，不能被 Idle 盖掉"
+    );
+}
+
+/// **三种失败形状各归各的**（复审 P1-1 的核心判据）。
+///
+/// | 收尾事件 | 期望原因 |
+/// |---|---|
+/// | `failure: Some(..)` | `Stage{..}`（进程**没起来**）|
+/// | `failure: None` + `Crashed` | `Crashed{exit_code}`（起来又崩）|
+/// | `failure: None` + `SilentFail` | `SilentFailure{exit_code}` |
+///
+/// 抓得住：把「起来了又崩」塞进 `LaunchFailureStage::Spawn`（磁贴会说「启动游戏进程失败」，
+/// 而进程明明起来了）；或者把静默失败也塌成崩溃（丢掉「退出码 0 却没跑起来」这条信息）。
+/// 断言的是**枚举变体**，不是字符串里有没有某个词。
+#[test]
+fn a_launch_end_without_a_stage_reports_the_outcome_not_a_start_failure() {
+    use crate::dto::{LaunchFailureCause, LaunchFailureStage, LaunchFailureView};
+
+    /// 一行用例：`(标签, 结局, 阶段失败, 退出码, 期望原因)`。
+    type Case = (
+        &'static str,
+        LogOutcome,
+        Option,
+        Option,
+        LaunchFailureCause,
+    );
+
+    let cases: Vec = vec![
+        (
+            "spawn-failed",
+            LogOutcome::Crashed,
+            Some(LaunchFailureView::new(
+                LaunchFailureStage::Spawn,
+                "os error 5",
+            )),
+            None,
+            LaunchFailureCause::Stage {
+                stage: LaunchFailureStage::Spawn,
+                detail: "os error 5".to_string(),
+            },
+        ),
+        (
+            "crashed-after-start",
+            LogOutcome::Crashed,
+            None,
+            Some(1),
+            LaunchFailureCause::Crashed { exit_code: Some(1) },
+        ),
+        (
+            "silent-after-start",
+            LogOutcome::SilentFail,
+            None,
+            Some(0),
+            LaunchFailureCause::SilentFailure { exit_code: Some(0) },
+        ),
+    ];
+
+    for (label, outcome, failure, exit_code, expected) in cases {
+        let (mut host, id, _root) = host_with_instance(label);
+        host.mark_pending(&id);
+        host.handle(HostTask::LaunchEnd(Box::new(LaunchFinished {
+            id: id.clone(),
+            session: format!("20261031T120000-{label}"),
+            outcome,
+            exit_code,
+            uptime_ms: 1_000,
+            failure,
+        })));
+        let failed = instances_from_events({
+            host.refresh_instances();
+            host.drain_events()
+        })
+        .into_iter()
+        .find(|instance| instance.id == id)
+        .expect("实例存在");
+        match (&failed.runtime, &expected) {
+            (InstanceRuntime::Failed { cause }, want) => {
+                assert_eq!(cause, want, "{label}：失败原因说错了");
+                assert_eq!(
+                    cause.slug(),
+                    want.slug(),
+                    "{label}：slug 与变体不一致（日志/事件流按 slug 判）"
+                );
+            }
+            (other, want) => panic!("{label}：期望 Failed{{cause:{want:?}}}，实际 {other:?}"),
+        }
+    }
+}
+
+/// 从事件队列里取最后一次 `InstancesChanged`。
+fn instances_from_events(events: Vec) -> Vec {
+    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, 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..b126b1a
--- /dev/null
+++ b/crates/presenter/src/host/logs.rs
@@ -0,0 +1,378 @@
+//! 日志 / 诊断：会话索引 → 会话列表，事件 JSONL → 日志行，规则引擎 → 诊断卡片。
+//!
+//! 与 CLI `ull logs` / `ull diagnose` 同源（`launch::session_index` + `diagnose` 规则引擎）：
+//! 「同一份 jsonl 的两种读法」只有这一处实现（M39 ports/events.rs 的设计）。
+//! 实时滚动 = host 每拍尾随启动会话的 JSONL（只读新增字节），不额外开第二条事件通道。
+//!
+//! ## 会话日志在哪（M188）
+//!
+//! | 位置 | 角色 |
+//! |---|---|
+//! | `<.ULL>/logs/game/.jsonl` + `index.jsonl` | **新会话写这里** |
+//! | `<.ULL>/data/agent/sessions/game/…` | 旧家：**只读兼容**，不搬不删 |
+//!
+//! 两个根的合并、落点记录都在 [`location`] 里；本文件只做「读出来 → DTO」的翻译。
+
+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;
+
+#[path = "logs/diagnosis.rs"]
+mod diagnosis;
+#[path = "logs/location.rs"]
+mod location;
+
+pub use location::{entries, legacy_root, note_location, root, sessions};
+
+/// 送进规则引擎的默认尾巴行数（与 CLI 同值，避免两条路看到不同证据）。
+pub const DEFAULT_TAIL: usize = 2000;
+
+/// 日志页一次最多渲染的行数（超出的截断，避免大文件把 UI 拖死）。
+pub const MAX_RENDERED_LINES: usize = 2_000;
+
+/// 索引条目 → 左栏会话行。
+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}")
+}
+
+/// 事件流文件路径（`/`；新根没有时回落到旧家）。
+///
+/// `log_path` 由写入侧按**相对会话根**的形状产出（`game/.jsonl`，见
+/// [`session_index::log_path_for`]），解析只走 [`session_index::event_file`] 一处——
+/// CLI 与 GUI 两个读取点共用它，谁也不许再自己拼一层 `game/`（M211/D2）。
+///
+/// 两处都找不到就返回**新根**的路径：调用方据此说出「该去哪找」，而不是一个旧目录路径。
+pub fn event_path(env: &HostEnv, entry: &SessionIndexEntry) -> PathBuf {
+    let primary = session_index::event_file(&root(env), &entry.log_path);
+    if primary.is_file() {
+        return primary;
+    }
+    if let Some(legacy) = legacy_root(env) {
+        let fallback = session_index::event_file(&legacy, &entry.log_path);
+        if fallback.is_file() {
+            return fallback;
+        }
+    }
+    primary
+}
+
+/// 会话 id 或唯一前缀 → 索引条目（两个根的合并视图）。
+fn find(env: &HostEnv, key: &str) -> Option {
+    let entries = entries(env);
+    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 {
+    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,
+    })
+}
+
+/// 整个事件流的原始 JSON 行（解析失败的行跳过，容忍被 kill 时截断的尾行）。
+///
+/// 一次读完所有事件：日志行与诊断结论都从这同一份读里取，不重复读盘。
+pub fn read_events(path: &Path) -> Vec {
+    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::(line).ok())
+        .collect()
+}
+
+/// 整个事件流 → 日志行（**展示面**：`payload.line`，即写盘前已脱敏的文本）。
+pub fn read_lines(path: &Path) -> Vec {
+    read_events(path).iter().filter_map(line_of).collect()
+}
+
+/// 打开一个会话：日志行 + 规则引擎结论。
+///
+/// 结论优先取会话里**落盘的那份**（写会话时用原始行算过，见 [`diagnosis`] 模块文档）；
+/// 老会话没有它，才回落到「在脱敏文本上重跑规则」。
+pub fn open(env: &HostEnv, key: &str) -> (Vec, Option) {
+    let Some(entry) = find(env, key) else {
+        return (Vec::new(), None);
+    };
+    let events = read_events(&event_path(env, &entry));
+    let lines: Vec = events.iter().filter_map(line_of).collect();
+    let diagnosis = diagnosis::stored(&entry, &events).or_else(|| diagnose_lines(&entry, &lines));
+    (lines, diagnosis)
+}
+
+/// 在**脱敏文本**上重跑规则引擎（老会话的兜底路径）。
+///
+/// ⚠️ 这条路的证据是「写盘前脱敏过的」行：`≥64` 无点号长串（Sponge 类路径、长 hash）会被
+/// 抹成 ``，依赖那些字面量的规则（`fabric.loader_0_12`）在这里**不可能命中**。
+/// 新会话通常不必走这条路——写会话时用原始行算过结论，见 [`diagnosis::stored`]。
+pub fn diagnose_lines(entry: &SessionIndexEntry, lines: &[LogLine]) -> Option {
+    let stderr_text: String = lines
+        .iter()
+        .filter(|line| line.level == LogLevel::Error || line.level == LogLevel::Warn)
+        .map(|line| line.text.as_str())
+        .collect::>()
+        .join("\n");
+    let body: String = lines
+        .iter()
+        .rev()
+        .take(DEFAULT_TAIL)
+        .map(|line| line.text.as_str())
+        .collect::>()
+        .into_iter()
+        .rev()
+        .collect::>()
+        .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,
+    session: Option,
+    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)> {
+        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 = complete
+            .lines()
+            .filter(|line| !line.trim().is_empty())
+            .filter_map(|line| serde_json::from_str::(line).ok())
+            .filter_map(|event| line_of(&event))
+            .collect();
+        Some((session, lines))
+    }
+}
+
+/// 会话是否已收尾（任一索引里出现 `ended_at` 或文件停止增长超过一拍）。
+pub fn session_finished(env: &HostEnv, session: &str) -> bool {
+    location::roots(env).into_iter().any(|dir| {
+        let index = unlucky_core::launch::session_index::index_path(&dir);
+        unlucky_core::launch::session_index::read_all(&index)
+            .unwrap_or_default()
+            .iter()
+            .any(|entry| entry.session_id == session && !entry.ended_at.is_empty())
+    })
+}
+
+#[cfg(test)]
+#[path = "logs/m241_tests.rs"]
+mod m241_tests;
+#[cfg(test)]
+#[path = "logs_tests.rs"]
+mod tests;
diff --git a/crates/presenter/src/host/logs/diagnosis.rs b/crates/presenter/src/host/logs/diagnosis.rs
new file mode 100644
index 0000000..d5a11a3
--- /dev/null
+++ b/crates/presenter/src/host/logs/diagnosis.rs
@@ -0,0 +1,82 @@
+//! 会话里落盘的诊断结论（M241）：读回时优先用它，不要拿脱敏文本重跑规则。
+//!
+//! ## 为什么不能重跑
+//!
+//! 会话 JSONL 是**写前脱敏**的，脱敏的两条形状规则有损：`≥64` 无点号不透明串会把证据行
+//! 一起抹掉（`fabric.loader_0_12` 的 `org/spongepowered/…/FabricMixinTransformerProxy`
+//! 66 字符 → ``）。在脱敏文本上重跑规则必然空手——M239 实测那条 critical
+//! 规则在会话路上「永不命中」。
+//!
+//! 修法是**换证据**而不是换判据：写会话时原始行还在内存里，那时已经算过一份结论并落进
+//! `diagnosis` 事件（`launch::session::SessionWriter::finish` → `diagnose::session::conclude`），
+//! 那份结论在盘上仍然是脱敏过的（`Redactor::scrub_json`）。展示侧只读它。
+//!
+//! 老会话（本次改动之前写的 JSONL）没有 `diagnosis` 事件 → 调用方回落到
+//! [`super::diagnose_lines`]（在脱敏文本上重跑），行为与今天一致，不会凭空少一张卡片。
+
+use serde_json::Value;
+use unlucky_core::launch::session_index::SessionIndexEntry;
+
+use crate::dto::{Diagnosis, DiagnosisReport};
+
+use super::confidence_percent;
+
+/// 事件流里最后一条 `diagnosis` 事件 → 日志页的诊断卡片 DTO。
+///
+/// 正常只会有一条（挂钩写的，或收尾补的，二选一——见 `SessionWriter::conclude_from_raw` 的门槛）。
+/// 真出现多条时取**最后一条**：收尾补的那份证据最新鲜。
+pub(super) fn stored(entry: &SessionIndexEntry, events: &[Value]) -> Option {
+    let payload = events
+        .iter()
+        .rev()
+        .find(|event| event.get("kind").and_then(Value::as_str) == Some("diagnosis"))?
+        .get("payload")?;
+    let candidate = payload
+        .get("candidates")
+        .and_then(Value::as_array)
+        .and_then(|items| items.first())
+        .or_else(|| {
+            payload
+                .get("secondary")
+                .and_then(Value::as_array)
+                .and_then(|items| items.first())
+        })?;
+    let rule = candidate.get("id").and_then(Value::as_str)?;
+    let title = candidate.get("message").and_then(Value::as_str)?;
+    if title.is_empty() {
+        return None;
+    }
+    let confidence = candidate
+        .get("confidence")
+        .and_then(Value::as_f64)
+        .unwrap_or_default();
+    let hint = candidate
+        .get("detail")
+        .and_then(Value::as_str)
+        .map(str::to_string)
+        .or_else(|| {
+            payload
+                .get("exit")
+                .and_then(|exit| exit.get("exit_type"))
+                .and_then(Value::as_str)
+                .map(str::to_string)
+        })
+        .unwrap_or_else(|| "未知退出".to_string());
+    let fix = candidate
+        .get("fix_actions")
+        .and_then(Value::as_array)
+        .and_then(|items| items.first())
+        .and_then(|action| action.get("tool"))
+        .and_then(Value::as_str)
+        .map(str::to_string);
+    Some(DiagnosisReport {
+        session: entry.session_id.clone(),
+        diagnosis: Diagnosis {
+            rule: rule.to_string(),
+            title: title.to_string(),
+            confidence: confidence_percent(confidence as f32),
+            hint,
+            fix,
+        },
+    })
+}
diff --git a/crates/presenter/src/host/logs/location.rs b/crates/presenter/src/host/logs/location.rs
new file mode 100644
index 0000000..240c79a
--- /dev/null
+++ b/crates/presenter/src/host/logs/location.rs
@@ -0,0 +1,107 @@
+//! 会话日志的**落点**：新家 `logs/`、旧家 `data/agent/sessions/`，以及两者合并的读法（M188）。
+//!
+//! ## 为什么要搬
+//!
+//! 旧落点是 `<.ULL>/data/agent/sessions/game/`：目录名里的 `agent` 是历史遗留（它从来只装**游戏**
+//! 会话，与 AI 无关），而 `data/` 分区是「可重建但优先保留」的状态数据。用户投诉原话是「我们的
+//! 启动日志放在哪？…他找半天没找到崩溃日志」——把日志放在 `data/agent/…` 底下，找不着是必然的。
+//!
+//! 新落点 `<.ULL>/logs/game/`：与启动器自己的 `launcher.log` 同一个分区、同一个顶层目录，
+//! 「打开日志文件夹」一次就能看见两者。
+//!
+//! ## 旧数据怎么办：**不搬**
+//!
+//! 搬动用户已有数据是不可逆动作（中途失败留半份会话、崩溃弹窗的会话关联会断），收益只是目录好看。
+//! 所以旧目录**原样留着、继续被读**：本模块的 [`entries`] 是两个根的合并视图，同 id 以新根为准。
+//! 「我们没动你的数据」这件事写进 [`note_location`] 的记录里，事后可查。
+
+use std::path::PathBuf;
+
+use unlucky_core::launch::session_index::{self, SessionIndexEntry};
+use unlucky_core::platform::layout::GAME_LOG_DIR;
+
+use crate::dto::LogSession;
+
+use super::{session_of, HostEnv};
+
+/// 会话日志落点记录的文件名（`/session-log-location.json`，见 [`note_location`]）。
+pub const SESSION_LOCATION_FILE: &str = "session-log-location.json";
+
+/// 会话根（**新会话写在这里**：`logs/`；`launch::LauncherConfig` 在其下建 `game/`）。
+pub fn root(env: &HostEnv) -> PathBuf {
+    env.sessions_root()
+}
+
+/// 会话日志的**旧家**（`data/agent/sessions/`）：M188 起只读兼容。
+///
+/// 目录不存在时给 `None`——「兼容」不等于「凭空造一个旧目录出来」。
+pub fn legacy_root(env: &HostEnv) -> Option {
+    let dir = env.legacy_sessions_root();
+    dir.is_dir().then_some(dir)
+}
+
+/// 读会话要看的根，**新根在前**（同 id 撞车时新根赢）。
+pub(super) fn roots(env: &HostEnv) -> Vec {
+    let mut roots = vec![root(env)];
+    roots.extend(legacy_root(env));
+    roots
+}
+
+/// 全部索引条目（两个根合并；同 id 以**先出现的**为准，即 `logs/` 那条）。
+///
+/// 为什么两个根都读：用户已有的会话在 `data/agent/sessions/` 下，M188 只改「新会话写到哪」，
+/// 不改「旧会话还能不能看」——否则崩溃弹窗里的会话关联会突然断掉。
+pub fn entries(env: &HostEnv) -> Vec {
+    let mut merged: Vec = Vec::new();
+    for dir in roots(env) {
+        let index = session_index::index_path(&dir);
+        for entry in session_index::read_all(&index).unwrap_or_default() {
+            if merged
+                .iter()
+                .any(|item| item.session_id == entry.session_id)
+            {
+                continue;
+            }
+            merged.push(entry);
+        }
+    }
+    merged.sort_by(|left, right| right.started_at.cmp(&left.started_at));
+    merged
+}
+
+/// 会话列表（新→旧；`logs/` 与旧家合并）。
+pub fn sessions(env: &HostEnv) -> Vec {
+    entries(env).iter().map(session_of).collect()
+}
+
+/// 会话日志「换了个家」的记录：迁了什么、什么时候、旧路径还在不在。
+///
+/// ```json
+/// {"v":1,"at":"…","sessions_root":"/logs","legacy_root":"/data/agent/sessions",
+///  "legacy_present":true,"legacy_files":3,"moved":0,"policy":"read-only-compat"}
+/// ```
+///
+/// best-effort：写不进去就算了（日志目录不可写时不该让启动器起不来）。
+pub fn note_location(env: &HostEnv) -> Option {
+    let legacy = env.legacy_sessions_root();
+    let legacy_present = legacy.is_dir();
+    let legacy_files = std::fs::read_dir(legacy.join(GAME_LOG_DIR))
+        .map(|items| items.filter_map(Result::ok).count())
+        .unwrap_or(0);
+    let body = serde_json::json!({
+        "v": 1,
+        "at": unlucky_core::launch::time::format_rfc3339_millis(unlucky_core::launch::time::now()),
+        "sessions_root": root(env).display().to_string(),
+        "legacy_root": legacy.display().to_string(),
+        "legacy_present": legacy_present,
+        "legacy_files": legacy_files,
+        "moved": 0,
+        "policy": "read-only-compat",
+    });
+    let path = env.logs_dir().join(SESSION_LOCATION_FILE);
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent).ok()?;
+    }
+    std::fs::write(&path, serde_json::to_vec_pretty(&body).ok()?).ok()?;
+    Some(path)
+}
diff --git a/crates/presenter/src/host/logs/m241_tests.rs b/crates/presenter/src/host/logs/m241_tests.rs
new file mode 100644
index 0000000..0e749c1
--- /dev/null
+++ b/crates/presenter/src/host/logs/m241_tests.rs
@@ -0,0 +1,140 @@
+//! M241：诊断吃**原始**文本、展示/导出只吃脱敏文本（拆文件守 400 行上限）。
+
+use super::*;
+use unlucky_core::launch::exit_analysis::{self, ExitSignals};
+use unlucky_core::launch::pump::{LogLine as CoreLine, Stream};
+use unlucky_core::launch::redact::Redactor;
+use unlucky_core::launch::session::{EndReason, SessionMeta, SessionWriter};
+
+/// 一个临时数据根（`/.ULL` + `/.minecraft`）。
+fn temp_root(tag: &str) -> PathBuf {
+    let root = std::env::temp_dir().join(format!("ull-m241-{tag}-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&root);
+    root
+}
+
+/// `fabric.loader_0_12`（critical / priority 80）在 `rules.d/fabric.yaml:114` 的唯一证据行。
+///
+/// 类路径 66 字符、无点号 → 撞上 `redact.rs` 的「≥64 不透明串」规则 → 脱敏后被抹成
+/// ``。这正是 M239 报的那个「会话路上永不命中」。
+const EVIDENCE: &str = "java.lang.NoClassDefFoundError: \
+                        org/spongepowered/asm/mixin/transformer/FabricMixinTransformerProxy";
+/// 真凭据（写盘前必须被抹掉的形状）。
+const TOKEN: &str = "SECRET-TOKEN-123456";
+
+fn meta() -> SessionMeta {
+    SessionMeta::new("inst", "1.20.1", "1.20.1")
+}
+
+/// 判据（M241）：① 规则引擎对含长类名的行**能命中**；② 用户可见/导出的文本**仍是被脱敏的**。
+///
+/// 端到端走真链路：`SessionWriter` 写盘（写前脱敏）→ 真 JSONL → [`open`] 读回。
+///
+/// 变异证明：
+/// - 把 `SessionWriter::finish` 里补结论的输入换成脱敏后的行 ⇒ ① 红（`fabric.loader_0_12`
+///   命不中，`diagnosis_top` 不是它）；
+/// - 把 `SessionWriter::line` 里的 `scrub` 去掉（导出面改成原始文本）⇒ ② 红（类路径与凭据
+///   原样出现在展示行与盘上）。
+#[test]
+fn raw_evidence_hits_the_rule_while_the_export_surface_stays_redacted() {
+    let root = temp_root("diagraw");
+    let env = HostEnv::at_root(&root);
+    let redactor = Redactor::new().with_secret(TOKEN);
+    let mut writer =
+        SessionWriter::create_with_id(&env.sessions_root(), "diagraw-1", meta(), redactor)
+            .expect("建会话");
+    writer.session_start().expect("session_start");
+    let lines = vec![
+        CoreLine::new(Stream::Stderr, "Failed to start Fabric loader"),
+        CoreLine::new(Stream::Stderr, EVIDENCE),
+        CoreLine::new(Stream::Stdout, format!("auth: token={TOKEN}")),
+    ];
+    for line in &lines {
+        writer.line(line).expect("写行");
+    }
+    let analysis = exit_analysis::analyze(&ExitSignals::new(1, 40_000, &lines));
+    writer.exit(&analysis).expect("exit");
+    let entry = writer.finish(EndReason::Exit).expect("finish");
+
+    // ① 规则对含长类名的行能命中（结论在原始行上算过，落进索引）。
+    assert_eq!(
+        entry.diagnosis_top.as_deref(),
+        Some("fabric.loader_0_12"),
+        "会话路上必须命中 fabric.loader_0_12"
+    );
+    let (opened, diagnosis) = open(&env, "diagraw-1");
+    assert_eq!(
+        diagnosis.map(|report| report.diagnosis.rule),
+        Some("fabric.loader_0_12".to_string())
+    );
+
+    // ② 展示面（日志行 DTO）：M240 收窄之后词形长路径不再被抹，所以类名会**原样出现**——
+    // 这是有意的（它不是凭据，留着才看得懂崩溃原因）。凭据仍然必须被抹。
+    assert!(
+        opened
+            .iter()
+            .any(|line| line.text.contains("FabricMixinTransformerProxy")),
+        "M240 之后展示行应保留类路径：{opened:?}"
+    );
+    assert!(
+        !opened
+            .iter()
+            .any(|line| line.text.contains("")),
+        "类路径不该再被当成不透明串：{opened:?}"
+    );
+    assert!(
+        !opened.iter().any(|line| line.text.contains(TOKEN)),
+        "展示行不许出现凭据：{opened:?}"
+    );
+
+    // ②' 盘上那份（= 导出包收进去的同一份文件）也没有原文——修 bug 不等于把密钥写进盘。
+    let disk = std::fs::read_to_string(event_path(&env, &entry)).expect("读会话文件");
+    assert!(
+        disk.contains("FabricMixinTransformerProxy"),
+        "M240 之后盘上应保留类路径（它不是凭据）：{disk}"
+    );
+    assert!(!disk.contains(TOKEN), "盘上不许出现凭据：{disk}");
+    std::fs::remove_dir_all(&root).ok();
+}
+
+/// 老会话（本次改动之前写的 JSONL，没有 `diagnosis` 事件）走兜底：在脱敏文本上重跑规则。
+///
+/// 判据：短字面量的规则（`memory.out_of_memory`）在脱敏文本上照样命中 ⇒ 兜底没坏。
+#[test]
+fn sessions_without_a_stored_conclusion_still_get_a_card() {
+    let root = temp_root("diagraw-legacy");
+    let env = HostEnv::at_root(&root);
+    let entry = SessionIndexEntry {
+        session_id: "legacy".to_string(),
+        instance_id: "inst".to_string(),
+        started_at: "2026-11-01T10:00:00.000Z".to_string(),
+        ended_at: "2026-11-01T10:01:00.000Z".to_string(),
+        exit_code: Some(1),
+        exit_type: Some("application_error".to_string()),
+        log_path: "game/legacy.jsonl".to_string(),
+        ..SessionIndexEntry::default()
+    };
+    session_index::append(&session_index::index_path(&env.sessions_root()), &entry)
+        .expect("写索引");
+    let file = env.sessions_root().join("game/legacy.jsonl");
+    std::fs::create_dir_all(file.parent().expect("父目录")).expect("建目录");
+    std::fs::write(
+        &file,
+        concat!(
+            "{\"kind\":\"stderr\",\"payload\":{\"line\":\"java.lang.OutOfMemoryError: Java heap space\",\"level\":\"error\"}}\n",
+            "{\"kind\":\"session_end\",\"payload\":{\"reason\":\"exit\"}}\n"
+        ),
+    )
+    .expect("写会话");
+
+    let (lines, diagnosis) = open(&env, "legacy");
+    assert!(lines
+        .iter()
+        .any(|line| line.text.contains("OutOfMemoryError")));
+    assert_eq!(
+        diagnosis.map(|report| report.diagnosis.rule),
+        Some("memory.out_of_memory".to_string()),
+        "没有落盘结论时应回落到规则重跑"
+    );
+    std::fs::remove_dir_all(&root).ok();
+}
diff --git a/crates/presenter/src/host/logs_tests.rs b/crates/presenter/src/host/logs_tests.rs
new file mode 100644
index 0000000..5db1fb3
--- /dev/null
+++ b/crates/presenter/src/host/logs_tests.rs
@@ -0,0 +1,271 @@
+//! host/logs.rs 的单测（拆文件守 400 行上限）。
+
+use super::*;
+use unlucky_core::launch::session_index;
+
+#[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);
+}
+
+// ---------------------------------------------------------------- M188：会话日志搬家
+
+/// 一个临时数据根（`/.ULL` + `/.minecraft`）。
+fn temp_root(tag: &str) -> PathBuf {
+    let root = std::env::temp_dir().join(format!("ull-m188-{tag}-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&root);
+    root
+}
+
+/// 索引条目夹具。`log_path` **必须是生产写入的形状**（相对会话根：`game/.jsonl`）。
+///
+/// M211/D2：这里以前传不带 `game/` 的 `.jsonl`，于是「读取侧多 join 一层 `game/`」的 bug
+/// 在夹具里永远看不见——夹具和生产各自自洽，两边都是绿的。改夹具比改路径更重要。
+fn sample_entry(id: &str, file: &str, started_at: &str) -> SessionIndexEntry {
+    SessionIndexEntry {
+        v: 1,
+        session_id: id.to_string(),
+        instance_id: "inst".to_string(),
+        instance_name: "实例".to_string(),
+        game_version: "1.20.1".to_string(),
+        started_at: started_at.to_string(),
+        ended_at: String::new(),
+        duration_ms: 0,
+        exit_code: Some(0),
+        exit_type: Some("normal".to_string()),
+        silent_failure: false,
+        window_detected: true,
+        event_count: 1,
+        log_path: file.to_string(),
+        crash_found: false,
+        diagnosis_top: None,
+    }
+}
+
+/// 守门①前半：**旧家的会话仍然列得出来、打得开**（只读兼容）。
+///
+/// 变异证明：
+/// - 把 [`entries`] 改成只读 `root(env)`（新根）⇒ 列表里没有 `old-session`，本条红；
+/// - 把 `event_path` 的新旧回落删掉（只认新根）⇒ `open` 拿到 0 行，本条红。
+#[test]
+fn legacy_sessions_are_still_listed_and_openable() {
+    let root = temp_root("legacy");
+    let env = HostEnv::at_root(&root);
+    let legacy_game = env.legacy_sessions_root().join("game");
+    std::fs::create_dir_all(&legacy_game).expect("建旧家目录");
+    let entry = sample_entry(
+        "old-session",
+        "game/old-session.jsonl",
+        "2026-11-01T10:00:00.000Z",
+    );
+    session_index::append(
+        &session_index::index_path(&env.legacy_sessions_root()),
+        &entry,
+    )
+    .expect("写旧索引");
+    std::fs::write(
+        legacy_game.join("old-session.jsonl"),
+        "{\"kind\":\"stdout\",\"payload\":{\"line\":\"旧会话这一行\"}}\n",
+    )
+    .expect("写旧事件流");
+
+    let listed = sessions(&env);
+    assert!(
+        listed.iter().any(|session| session.id == "old-session"),
+        "旧家的会话没有出现在列表里：{listed:?}"
+    );
+    assert_eq!(
+        event_path(&env, &entry),
+        legacy_game.join("old-session.jsonl")
+    );
+    let (lines, _) = open(&env, "old-session");
+    assert!(
+        lines.iter().any(|line| line.text.contains("旧会话这一行")),
+        "旧家的事件流没读出来：{lines:?}"
+    );
+    // 「兼容」不等于「复制一份到新根」：旧文件原地不动、新根里没有它。
+    assert!(legacy_game.join("old-session.jsonl").is_file());
+    assert!(!root.join(".ULL/logs/game/old-session.jsonl").is_file());
+    std::fs::remove_dir_all(&root).ok();
+}
+
+/// 守门①后半：**新会话写在 `logs/game/`**，索引与事件流都在那儿。
+///
+/// 变异证明：把 `HostEnv::sessions_root` 改回 `layout.agent_sessions()` ⇒ 第一条断言红；
+/// 把 [`entries`] 改成只读旧家 ⇒ 列表里没有 `fresh`，本条红。
+#[test]
+fn new_sessions_are_written_under_logs_game() {
+    let root = temp_root("newhome");
+    let env = HostEnv::at_root(&root);
+    let index = session_index::index_path(&env.sessions_root());
+    assert_eq!(index, root.join(".ULL/logs/game/index.jsonl"));
+
+    let entry = sample_entry("fresh", "game/fresh.jsonl", "2026-11-08T09:00:00.000Z");
+    session_index::append(&index, &entry).expect("写新索引");
+    let file = env.sessions_root().join("game/fresh.jsonl");
+    std::fs::write(
+        &file,
+        "{\"kind\":\"stdout\",\"payload\":{\"line\":\"新会话\"}}\n",
+    )
+    .expect("写新事件流");
+
+    let listed = sessions(&env);
+    assert_eq!(
+        listed.first().map(|session| session.id.as_str()),
+        Some("fresh"),
+        "{listed:?}"
+    );
+    assert_eq!(event_path(&env, &entry), file);
+    // 旧目录不许被凭空造出来（我们没搬东西，也没义务建一个旧家）。
+    assert!(!env.legacy_sessions_root().exists());
+    std::fs::remove_dir_all(&root).ok();
+}
+
+/// 同一个 id 同时出现在两个根时**新根赢**（用户在新位置又跑了一局同名会话）。
+#[test]
+fn the_new_root_wins_when_both_indexes_know_the_same_id() {
+    let root = temp_root("both");
+    let env = HostEnv::at_root(&root);
+    let legacy_game = env.legacy_sessions_root().join("game");
+    std::fs::create_dir_all(&legacy_game).expect("建旧家目录");
+    let old = sample_entry("same", "game/same.jsonl", "2026-10-01T00:00:00.000Z");
+    session_index::append(
+        &session_index::index_path(&env.legacy_sessions_root()),
+        &old,
+    )
+    .expect("写旧索引");
+    std::fs::write(
+        legacy_game.join("same.jsonl"),
+        "{\"kind\":\"stdout\",\"payload\":{\"line\":\"旧\"}}\n",
+    )
+    .expect("写旧事件流");
+
+    let fresh = sample_entry("same", "game/same.jsonl", "2026-11-08T00:00:00.000Z");
+    session_index::append(&session_index::index_path(&env.sessions_root()), &fresh)
+        .expect("写新索引");
+    let new_file = env.sessions_root().join("game/same.jsonl");
+    std::fs::write(
+        &new_file,
+        "{\"kind\":\"stdout\",\"payload\":{\"line\":\"新\"}}\n",
+    )
+    .expect("写新事件流");
+
+    let entries = super::entries(&env);
+    let hits: Vec<&SessionIndexEntry> = entries
+        .iter()
+        .filter(|entry| entry.session_id == "same")
+        .collect();
+    assert_eq!(hits.len(), 1, "同一个 id 只能出现一次：{hits:?}");
+    assert_eq!(hits[0].started_at, fresh.started_at, "新根那条应当赢");
+    assert_eq!(event_path(&env, &fresh), new_file);
+    std::fs::remove_dir_all(&root).ok();
+}
+
+/// 落点记录：迁了什么（没有）、什么时候、旧路径还在不在。
+#[test]
+fn the_location_receipt_names_both_roots_and_the_policy() {
+    let root = temp_root("receipt");
+    let env = HostEnv::at_root(&root);
+    let legacy_game = env.legacy_sessions_root().join("game");
+    std::fs::create_dir_all(&legacy_game).expect("建旧家目录");
+    std::fs::write(legacy_game.join("a.jsonl"), "{}\n").expect("写旧文件");
+
+    let path = note_location(&env).expect("记录应当写得出来");
+    assert_eq!(
+        path,
+        env.logs_dir().join(super::location::SESSION_LOCATION_FILE)
+    );
+    let value: serde_json::Value =
+        serde_json::from_slice(&std::fs::read(&path).expect("读记录")).expect("记录是 JSON");
+    assert_eq!(value["policy"], "read-only-compat");
+    assert_eq!(value["moved"], 0, "我们一个文件都没搬");
+    assert_eq!(value["legacy_present"], true);
+    assert_eq!(value["legacy_files"], 1);
+    assert_eq!(
+        value["sessions_root"],
+        env.sessions_root().display().to_string()
+    );
+    assert_eq!(
+        value["legacy_root"],
+        env.legacy_sessions_root().display().to_string()
+    );
+    std::fs::remove_dir_all(&root).ok();
+}
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>) -> 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..d28434c
--- /dev/null
+++ b/crates/presenter/src/host/mod.rs
@@ -0,0 +1,394 @@
+//! 真实后端：把 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;
+// M223：导入已有版本（扫描 / 预检 / 确认三条后台线程）
+mod adopt;
+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 launch_args;
+mod loader_versions;
+mod logs;
+mod meter;
+mod mods;
+mod opener;
+mod saves;
+mod settings;
+mod update;
+mod update_state;
+mod versions;
+
+use std::collections::{BTreeMap, BTreeSet, VecDeque};
+use std::time::Duration;
+
+use crate::dto::{
+    AccountView, AppCommand, AppEvent, Backend, CoreEvent, DiagnosisReport, InstallProgressView,
+    InstanceRuntime, JavaChainStep, LaunchFailureCause, 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,
+    tx: JobSender,
+    rx: JobReceiver,
+    ticks: u64,
+    /// 当前启动账户 id（内存态；跨会话持久化要 core schema 增键，见 handoff）
+    active_account: Option,
+    accounts: Vec,
+    login: Option,
+    /// 第三方轨（authlib）登录任务句柄（与微软两条流共用取消语义，但**不复用槽位**：
+    /// 两条轨同时点「登录」时各自的结果不能互相踩）
+    authlib: Option,
+    /// 已抓到的皮肤（账户 id → 原图；`None` = 试过但没取到，不再重试）
+    skins: BTreeMap>,
+    /// 已经发起过皮肤抓取的账户 id（防每次刷新都重新抓一遍）
+    skin_requested: BTreeSet,
+    java_chain: Vec,
+    java_busy: bool,
+    java_message: String,
+    install: Option,
+    notices: Vec,
+    /// 在跑的启动（实例 → 会话 → pid；支持多个实例同时启动，停止按 id 找正确的 pid）
+    launches: Vec,
+    /// 已受理但后台线程还没回报 `LaunchStarted` 的实例（防「启动中重复点启动」起第二个进程）
+    pending: BTreeSet,
+    /// 上次启动失败的实例与原因（刷新快照时保住磁贴的「失败/重试」外观）
+    /// 上次启动失败（阶段 + 原文；磁贴的「失败/重试」外观靠它重建）
+    failed: BTreeMap,
+    /// 实时日志尾随器
+    tail: logs::Tail,
+    /// AI 对话的临时后端（agent GUI host 落地前的占位）
+    chat: MockBackend,
+    /// 当前安装任务的取消标记（`execute_with_cancel` 与段边界检查共同消费）
+    install_cancel: Option>,
+    /// 当前安装任务的代次。
+    ///
+    /// 开工（`InstallVersion` / `CreateInstance`）与取消都 +1：还在飞的后台线程把事件带回来时
+    /// 一眼能看出「这是旧任务的」，于是既不会被取消掉的安装重新点亮面板，也不会串到下一轮安装
+    /// （两轮安装同时存在时，旧任务的事件曾经把新任务的进度条顶掉）。
+    install_epoch: u64,
+    /// 「导入已有版本」的代次（M223）：每条 scan/preview/confirm 命令 +1，关面板也 +1。
+    ///
+    /// 只认最新代次的回程事件——用户连点或点了关闭之后，旧线程带回来的结果不许再把面板点亮。
+    adopt_epoch: u64,
+    /// 自更新（M159）：检查结论 / 应用状态 / 更新域偏好。
+    update: update_state::Runtime,
+}
+
+impl CoreHost {
+    /// 按便携数据根装配；解析不出数据根返回 `None`（调用方退回 mock）。
+    pub fn open() -> Option {
+        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);
+        // M188：把「会话日志换了家」这件事记一笔（旧目录还在不在、有几个文件、搬了什么）。
+        // 策略是**不搬**，所以这份记录是「我们没动你的数据」的唯一凭据。
+        logs::note_location(&env);
+        // M159：更新状态要在构造时就有一份（提示条/设置页都读它），静默检查在 `refresh_all`
+        // 里按开关派发——`headless` 走 `refresh=false`，于是单测不会发任何网络请求。
+        let update = update_state::Runtime::for_env(&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,
+            adopt_epoch: 0,
+            update,
+        };
+        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) {
+        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());
+        // M159：更新快照先发一份（设置页首帧就有「当前版本 / 上次结果」），
+        // 再按开关决定要不要静默查一次。关掉开关 ⇒ 这里一行网络都不发。
+        self.publish_update();
+        if self.update.should_check_on_start() {
+            self.start_update_check(false);
+        }
+    }
+
+    /// 重建实例快照，并把**真实运行时**盖回去。
+    ///
+    /// `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(cause) = self.failed.get(&instance.id) {
+                instance.runtime = InstanceRuntime::Failed {
+                    cause: cause.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 {
+        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 {
+        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 {
+        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/mods.rs b/crates/presenter/src/host/mods.rs
new file mode 100644
index 0000000..8513472
--- /dev/null
+++ b/crates/presenter/src/host/mods.rs
@@ -0,0 +1,269 @@
+//! 本地 Mod 列表与启停的宿主实现（M224 · MODTOGGLE）。
+//!
+//! ## 三条纪律
+//!
+//! | 纪律 | 落点 |
+//! |---|---|
+//! | 磁盘只在后台线程碰 | [`spawn_list`] / [`spawn_set_enabled`] 走 `job::spawn`，UI 只收快照 |
+//! | 单根语义（D20） | 运行目录来自 `game::isolation::derive_game_dir`——**与启动同一个答案**，不另派生、不做双根合并 |
+//! | 游戏在跑就不改名 | `running` 标记在 host 这一侧挡：Windows 上进程正持有 jar，rename 会失败，与其让用户读一句 OS 报错不如直说 |
+//!
+//! ## 为什么不复用启动路径的 `run_dir()`
+//!
+//! `host::launch` 的 `run_dir()` 顺带把「这次用哪个档位」写进实例设置（`observe_mode`）。列 mod /
+//! 启停**不该因为用户点开详情页就写盘**，所以这里只取派生结果、不落任何设置。
+//!
+//! ## 失败口径
+//!
+//! 一律走 [`crate::dto::ModFailureView`]（结构 + OS 原文），**不拼中文**：文案由 app 层按 i18n key
+//! 现求（M161 的纪律，`dto::events` 的 `LaunchFinished` 同款）。
+
+use std::path::PathBuf;
+
+use unlucky_core::addon::mods::{ModError, ModScan, SkipReason};
+use unlucky_core::game::install::instance::read_instance_config;
+use unlucky_core::game::isolation::derive_game_dir;
+
+use crate::dto::{
+    locate, InstanceId, InstanceSummary, ModEntryView, ModFailureKind, ModFailureView, ModListView,
+    ModSkipKind, ModSkipView, ModsCommand,
+};
+
+use super::env::HostEnv;
+use super::job::{spawn, JobSender};
+
+/// 后台线程回报的一次结果（`HostTask::Mods` 的载荷）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Report {
+    /// 实例 id（迟到结果靠它判「这条还是不是当前实例的」）。
+    pub instance: InstanceId,
+    /// 列表结果：成功 = 整份快照；失败 = 具名原因。
+    pub list: Result,
+    /// 这一拍是启停操作的结果时带上「改了什么」（host 只记日志；开关跟快照翻）。
+    pub toggled: Option,
+}
+
+/// 一次成功的启停（`renamed == false` ⇒ 本来就是那个状态，什么也没动）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Toggled {
+    /// 原磁盘名。
+    pub from: String,
+    /// 新磁盘名。
+    pub to: String,
+    /// 现在的启用状态。
+    pub enabled: bool,
+    /// 是否真的改了名。
+    pub renamed: bool,
+}
+
+/// 后台列一个实例的 `mods/`。
+pub fn spawn_list(env: HostEnv, tx: JobSender, id: InstanceId, running: bool) {
+    spawn("mods-list", move || {
+        let report = Report {
+            instance: id.clone(),
+            list: list(&env, &id, running),
+            toggled: None,
+        };
+        let _ = tx.send(super::HostTask::Mods(Box::new(report)));
+    });
+}
+
+/// 后台启停一个文件，然后把**新快照**一起带回来（app 不必再请求一次）。
+pub fn spawn_set_enabled(
+    env: HostEnv,
+    tx: JobSender,
+    id: InstanceId,
+    file: String,
+    enabled: bool,
+    running: bool,
+) {
+    spawn("mods-toggle", move || {
+        let report = toggle(&env, &id, &file, enabled, running);
+        let _ = tx.send(super::HostTask::Mods(Box::new(report)));
+    });
+}
+
+/// 一条指令 → 后台线程（`CoreHost::dispatch` 的唯一入口）。
+pub fn dispatch(env: HostEnv, tx: JobSender, command: ModsCommand, running: bool) {
+    match command {
+        ModsCommand::List(id) => spawn_list(env, tx, id, running),
+        ModsCommand::SetEnabled { id, file, enabled } => {
+            spawn_set_enabled(env, tx, id, file, enabled, running)
+        }
+    }
+}
+
+/// 实例 + 它的运行目录（找不到实例 / 派生不出目录都给具名失败）。
+fn target(
+    env: &HostEnv,
+    id: &str,
+    file: &str,
+) -> Result<(InstanceSummary, PathBuf), ModFailureView> {
+    let instances = super::game::instances(env);
+    let Some(instance) = locate(&instances, id) else {
+        return Err(failure(
+            id,
+            file,
+            ModFailureKind::InstanceUnavailable,
+            format!("实例 {id} 不在快照里（可能刚被删除）"),
+        ));
+    };
+    let dir = run_dir(env, instance).map_err(|detail| {
+        failure(
+            &instance.id,
+            file,
+            ModFailureKind::InstanceUnavailable,
+            detail,
+        )
+    })?;
+    Ok((instance.clone(), dir))
+}
+
+/// 列目录（后台线程里调）。
+fn list(env: &HostEnv, id: &str, running: bool) -> Result {
+    let (instance, dir) = target(env, id, "")?;
+    let scan = unlucky_core::addon::mods::scan(&dir).map_err(|error| {
+        let (kind, detail) = classify(&error);
+        failure(&instance.id, "", kind, detail)
+    })?;
+    Ok(view(&instance, &scan, running))
+}
+
+/// 启停一个文件 + 回来时带新快照。
+fn toggle(env: &HostEnv, id: &str, file: &str, enabled: bool, running: bool) -> Report {
+    let (instance, dir) = match target(env, id, file) {
+        Ok(found) => found,
+        Err(view) => {
+            return Report {
+                instance: id.to_string(),
+                list: Err(view),
+                toggled: None,
+            };
+        }
+    };
+    let instance_id = instance.id.clone();
+    if running {
+        return Report {
+            instance: instance_id,
+            list: Err(failure(
+                id,
+                file,
+                ModFailureKind::Running,
+                "游戏进程正在跑（Windows 会拒绝改名）",
+            )),
+            toggled: None,
+        };
+    }
+    let toggled = match unlucky_core::addon::mods::set_enabled(&dir, file, enabled) {
+        Ok(result) => Toggled {
+            from: result.from,
+            to: result.to,
+            enabled: result.enabled,
+            renamed: result.renamed,
+        },
+        Err(error) => {
+            let (kind, detail) = classify(&error);
+            return Report {
+                instance: instance_id,
+                list: Err(failure(id, file, kind, detail)),
+                toggled: None,
+            };
+        }
+    };
+    // 改名之后**重新扫一遍**再发：权威状态来自磁盘，app 不做乐观回显（与启动/停止同一条纪律）。
+    let list = unlucky_core::addon::mods::scan(&dir)
+        .map(|scan| view(&instance, &scan, running))
+        .map_err(|error| {
+            let (kind, detail) = classify(&error);
+            failure(&instance_id, file, kind, detail)
+        });
+    Report {
+        instance: instance_id,
+        list,
+        toggled: Some(toggled),
+    }
+}
+
+/// 实例的运行目录（D20 覆盖链，与启动同一份派生；**不写盘**）。
+fn run_dir(env: &HostEnv, instance: &InstanceSummary) -> Result {
+    let global = super::game::global_mode(env);
+    let config = read_instance_config(&env.layout, &instance.id)
+        .map_err(|error| format!("读实例设置失败：{error}"))?;
+    let derivation = derive_game_dir(
+        &env.game,
+        &instance.version_id,
+        global,
+        config.as_ref(),
+        None,
+    )
+    .map_err(|error| format!("派生运行目录失败：{error}"))?;
+    Ok(derivation.game_dir)
+}
+
+/// 快照映射：core 的扫描结果 → DTO（路径串在 host 这一侧才成形）。
+fn view(instance: &InstanceSummary, scan: &ModScan, running: bool) -> ModListView {
+    ModListView {
+        instance: instance.id.clone(),
+        dir: scan.dir.display().to_string(),
+        exists: scan.exists,
+        entries: scan
+            .entries
+            .iter()
+            .map(|entry| ModEntryView {
+                file: entry.file.clone(),
+                name: entry.name.clone(),
+                enabled: entry.enabled,
+                bytes: entry.bytes,
+                old: entry.variant.is_old(),
+            })
+            .collect(),
+        skipped: scan
+            .skipped
+            .iter()
+            .map(|skip| ModSkipView {
+                file: skip.file.clone(),
+                reason: match skip.reason {
+                    SkipReason::SymbolicLink => ModSkipKind::SymbolicLink,
+                    SkipReason::NotAFile => ModSkipKind::NotAFile,
+                    SkipReason::UnsafeName => ModSkipKind::UnsafeName,
+                    SkipReason::Unreadable => ModSkipKind::Unreadable,
+                },
+            })
+            .collect(),
+        running,
+        known: true,
+    }
+}
+
+fn failure(
+    instance: &str,
+    file: &str,
+    kind: ModFailureKind,
+    detail: impl Into,
+) -> ModFailureView {
+    ModFailureView {
+        instance: instance.to_string(),
+        file: file.to_string(),
+        kind,
+        detail: detail.into(),
+    }
+}
+
+/// core 的错误 → DTO 大类 + 原文（**不翻译**，翻译在 app 层）。
+fn classify(error: &ModError) -> (ModFailureKind, String) {
+    match error {
+        ModError::UnsafeName { detail, .. } => (ModFailureKind::UnsafeName, detail.clone()),
+        ModError::ModsDirUnusable { detail, .. } => {
+            (ModFailureKind::ModsDirUnusable, detail.clone())
+        }
+        ModError::NotFound { .. } => (ModFailureKind::NotFound, error.to_string()),
+        ModError::NotARegularFile { detail, .. } => {
+            (ModFailureKind::NotARegularFile, detail.clone())
+        }
+        ModError::Collision { .. } => (ModFailureKind::Collision, error.to_string()),
+        ModError::Rename { detail, .. } => (ModFailureKind::Rename, detail.clone()),
+    }
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/presenter/src/host/mods/tests.rs b/crates/presenter/src/host/mods/tests.rs
new file mode 100644
index 0000000..9d6c61e
--- /dev/null
+++ b/crates/presenter/src/host/mods/tests.rs
@@ -0,0 +1,192 @@
+//! `host::mods` 的用例（从 `host/mods.rs` 拆出：那边 457 行越了 400 行硬线）。
+//!
+//! 三条：**真盘端到端**（派生运行目录 → core 改名 → 快照回来）、跳过原因映射、错误分类。
+//! 端到端那条是这个模块存在的主要理由——启停的正确性只有"真的建一个实例根再改一次盘"能验。
+
+use super::*;
+use crate::dto::{InstanceRuntime, LaunchArgsView, LoaderInfo, LoaderKind};
+use unlucky_core::addon::mods::ModSkip;
+
+const ID: &str = "survival";
+const VERSION: &str = "1.20.4-fabric-0.16.5";
+
+/// 一次性临时根（与本 crate 其它 host 测试同款：不引第三方 tempfile）。
+struct TempRoot(PathBuf);
+
+impl Drop for TempRoot {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_dir_all(&self.0);
+    }
+}
+
+/// 一个可用的便携根：`mods/`（给定文件）+ `profiles.json` + `custom` 档位的实例设置。
+///
+/// 走 `custom` 是**故意**的：它是 D20 里唯一「运行目录由实例自己指」的档位，于是用例不必造
+/// `versions//` 也能验「派生出来的目录就是启停的目标目录」。
+fn fixture(tag: &str, files: &[(&str, &[u8])]) -> (TempRoot, HostEnv, PathBuf) {
+    use std::sync::atomic::{AtomicU64, Ordering};
+    static COUNTER: AtomicU64 = AtomicU64::new(0);
+    let seq = COUNTER.fetch_add(1, Ordering::Relaxed);
+    let path = std::env::temp_dir().join(format!("{tag}-{}-{seq}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&path);
+    let root = TempRoot(path);
+    std::fs::create_dir_all(&root.0).expect("建临时目录");
+    let env = HostEnv::at_root(&root.0);
+    let run = root.0.join("run");
+    std::fs::create_dir_all(run.join("mods")).expect("建 mods");
+    for (name, body) in files {
+        std::fs::write(run.join("mods").join(name), body).expect("写文件");
+    }
+    std::fs::create_dir_all(env.layout.config()).expect("建 config");
+    let profile = format!(r#"{{"id":"{ID}","name":"生存","versionId":"{VERSION}"}}"#);
+    std::fs::write(
+        env.layout.profiles_config(),
+        format!(r#"{{"schemaVersion":1,"profiles":[{profile}]}}"#),
+    )
+    .expect("写 profiles");
+    let config = format!(
+        r#"{{"schemaVersion":1,"id":"{ID}","versionId":"{VERSION}","isolation":"custom","gameDir":{}}}"#,
+        serde_json::to_string(&run).expect("路径转 JSON")
+    );
+    let path = env.layout.instance_config(ID).expect("实例 id");
+    std::fs::create_dir_all(path.parent().expect("instances 目录")).expect("建 instances");
+    std::fs::write(path, config).expect("写实例设置");
+    (root, env, run)
+}
+
+fn instance() -> InstanceSummary {
+    InstanceSummary {
+        id: ID.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: None,
+        runtime: InstanceRuntime::Idle,
+        icon: None,
+        isolation: "isolated".to_string(),
+        version_id: VERSION.to_string(),
+        version_present: true,
+        launch: LaunchArgsView::default(),
+    }
+}
+
+/// **端到端**（真盘 + 真派生）：列目录 → 启停 → 再列，顺带验运行中被挡。
+///
+/// 打通「派生运行目录 → core 改盘 → 快照回来」整条链。抓得住：派生用错目录、启停后没重扫、
+/// `.disabled` 判据与 core 不一致。抓不住：Windows 上的占用/权限失败（那要靠真跑）。
+#[test]
+fn list_and_toggle_round_trip_on_a_real_root() {
+    let (_root, env, run) = fixture(
+        "mods-e2e",
+        &[
+            ("sodium.jar", b"aa"),
+            ("jei.jar.disabled", b"bbb"),
+            ("old.jar.old", b"cccc"),
+        ],
+    );
+
+    let listed = list(&env, ID, false).expect("列目录");
+    assert!(listed.exists && listed.known && !listed.running);
+    assert_eq!((listed.enabled_count(), listed.disabled_count()), (2, 1));
+    assert!(listed.entries.iter().any(|entry| entry.old));
+
+    let report = toggle(&env, ID, "sodium.jar", false, false);
+    assert!(report.toggled.expect("要报告改了什么").renamed);
+    assert!(run.join("mods/sodium.jar.disabled").is_file());
+    assert_eq!(report.list.expect("新快照").enabled_count(), 1);
+
+    // 再启用回去（`.disabled` 剥掉，字节不动）
+    let report = toggle(&env, ID, "sodium.jar.disabled", true, false);
+    assert!(report.toggled.expect("报告").renamed);
+    assert_eq!(report.list.expect("快照").enabled_count(), 2);
+    assert_eq!(
+        std::fs::read(run.join("mods/sodium.jar")).expect("读回"),
+        b"aa"
+    );
+
+    // 游戏在跑：host 直接挡（不碰盘、不改名）
+    let blocked = toggle(&env, ID, "sodium.jar", false, true);
+    assert_eq!(
+        blocked.list.expect_err("运行中必须拒").kind,
+        ModFailureKind::Running
+    );
+    assert!(blocked.toggled.is_none());
+    assert!(run.join("mods/sodium.jar").is_file(), "盘被动了");
+    assert!(!run.join("mods/sodium.jar.disabled").exists());
+}
+
+/// 跳过原因一一对应，且 runtime/known 标记原样过桥。
+///
+/// 抓得住：`NotAFile` 归到 `SymbolicLink`（"为什么没列出来"撒谎）、`running` 被写死。
+#[test]
+fn the_snapshot_keeps_skip_reasons_and_flags() {
+    let scan = ModScan {
+        dir: PathBuf::from("m"),
+        exists: true,
+        entries: Vec::new(),
+        skipped: vec![ModSkip {
+            file: "x".to_string(),
+            reason: SkipReason::SymbolicLink,
+        }],
+    };
+    let listed = view(&instance(), &scan, true);
+    assert!(listed.running && listed.known && listed.exists);
+
+    let kinds = [
+        (SkipReason::SymbolicLink, ModSkipKind::SymbolicLink),
+        (SkipReason::NotAFile, ModSkipKind::NotAFile),
+        (SkipReason::UnsafeName, ModSkipKind::UnsafeName),
+        (SkipReason::Unreadable, ModSkipKind::Unreadable),
+    ];
+    for (reason, expected) in kinds {
+        let mut scan = scan.clone();
+        scan.skipped[0].reason = reason;
+        assert_eq!(view(&instance(), &scan, false).skipped[0].reason, expected);
+    }
+}
+
+/// 错误分类：每个 core 变体都落到自己的大类（没有「未知 → 一律 IO」的兜底），原因不丢。
+#[test]
+fn every_core_error_keeps_its_own_kind() {
+    let dir = PathBuf::from("m");
+    let cases = [
+        (
+            ModError::UnsafeName {
+                file: "a/b".into(),
+                detail: "含分隔符".into(),
+            },
+            ModFailureKind::UnsafeName,
+        ),
+        (
+            ModError::NotFound {
+                file: "x.jar".into(),
+                dir: dir.clone(),
+            },
+            ModFailureKind::NotFound,
+        ),
+        (
+            ModError::Collision {
+                file: "x.jar".into(),
+                target: "x.jar.disabled".into(),
+                dir,
+            },
+            ModFailureKind::Collision,
+        ),
+        (
+            ModError::Rename {
+                file: "x.jar".into(),
+                target: "x.jar.disabled".into(),
+                detail: "被占用".into(),
+            },
+            ModFailureKind::Rename,
+        ),
+    ];
+    for (error, expected) in cases {
+        let (kind, detail) = classify(&error);
+        assert_eq!(kind, expected, "{error}");
+        assert!(!detail.is_empty(), "{error} 的分类把原因吃掉了");
+    }
+}
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) {
+    // `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) {
+    ("open", vec![url.to_string()])
+}
+
+#[cfg(not(any(target_os = "windows", target_os = "macos")))]
+fn launcher(url: &str) -> (&'static str, Vec) {
+    ("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/saves.rs b/crates/presenter/src/host/saves.rs
new file mode 100644
index 0000000..00b3ca5
--- /dev/null
+++ b/crates/presenter/src/host/saves.rs
@@ -0,0 +1,340 @@
+//! 实例存档 / 截图的宿主实现（M235 · STOREMVP 读路径 + M247 · SAVESOPS 写路径）。
+//!
+//! ## 四条纪律
+//!
+//! | 纪律 | 落点 |
+//! |---|---|
+//! | 磁盘只在后台线程碰 | [`spawn_list`] / [`spawn_open_folder`] / [`spawn_rename`] / [`spawn_delete`] / [`spawn_backup`] 全走 `job::spawn`，UI 只收快照 |
+//! | 单根语义（D20） | 运行目录来自 `game::isolation::derive_game_dir`——**与启动同一个答案**，不另派生、不做双根合并 |
+//! | 读路径只读 | [`list`] 一次写盘都没有；`saves/` 不存在也不替玩家建（core 的 `saves::scan` 同理） |
+//! | 写路径自己重校边界 | 三个写操作**不在 host 这边信任自己**：core 的 `saves::write` 每次重新校验 `run_dir` 与目标路径（越界 / 符号链接 / 撞名都在那里拒） |
+//! | 游戏在跑就不写 | [`dispatch`] 的 `running` 为真时三条写命令**不 spawn、不碰盘**，直接回 [`crate::dto::SavesFailureKind::GameRunning`] |
+//!
+//! ## 三个写操作的回程形状
+//!
+//! | 操作 | 成功 | 失败 |
+//! |---|---|---|
+//! | 重命名 | 新快照 + [`SavesOped::Renamed`] | 具名 [`SavesFailureKind`]（撞名 / 名字不可用 / 越界 / 链接 / IO） |
+//! | 删除 | 新快照 + [`SavesOped::Deleted`] | 同上 |
+//! | 备份 | 新快照 + [`SavesOped::BackedUp`]（落点路径 / 字节数 / 跳过的链接数） | 同上 + `TooLarge` |
+//!
+//! **写成功后一律重新列一遍**（`snapshot`）：界面画的永远是磁盘上的真相，不是"我以为我改成了什么"。
+//! 回执只是"这次动的是哪一条"，与快照一起回去，所以 UI 不会出现「列表变了但不知道谁变的」。
+//!
+//! ## 「游戏在跑」为什么挡在 host 这一侧（M247）
+//!
+//! 判据是 `CoreHost::in_flight(&id)`（与 `AppCommand::Mods` 同一个），由 `host::dispatch` 传进来。
+//! 为真时 [`dispatch`] **不 spawn 线程**、直接发一条 [`SavesFailureKind::GameRunning`] 的失败回去：
+//!
+//! | 平台 | 不挡的后果 |
+//! |---|---|
+//! | Windows | 进程占着世界目录 ⇒ rename/删除撞共享冲突 ⇒ 用户读一句 `os error 32` |
+//! | **Linux** | **删一个正在跑的世界会成功** —— 用户在玩到一半时丢了存档 |
+//!
+//! 所以这不是"说得更清楚"，是**安全性**。也不能只靠界面灰按钮：判据留在 host，UI 那一侧只是
+//! 尽力而为的提示（本版没加"灰按钮"的形态，理由是快照里没有 `running` 字段——加它要动列表 DTO，
+//! 而这一版已经有那条明确的失败句子兜住）。
+//!
+//! 读路径（[`SavesCommand::List`]）与「打开文件夹」**不受影响**：它们不改盘。
+
+//! ## 为什么不复用启动路径的 `run_dir()`
+//!
+//! 与 [`super::mods`] 同一条理由：`host::launch` 的 `run_dir()` 顺带把「这次用哪个档位」写进实例
+//! 设置（`observe_mode`）。**列存档不该因为用户点开详情页就写盘**，所以这里只取派生结果。
+//!
+//! ## 「打开文件夹」为什么由 host 决定打开哪个目录
+//!
+//! `saves/` 可能还不存在（新实例），而用户点「打开文件夹」想看到的是**能放存档的地方**。
+//! 于是退化成：`saves/` → `screenshots/` → 运行目录，取第一个存在的。这个判断是"磁盘上到底
+//! 有什么"的事实，放在 host 这一侧；UI 只发一条 [`crate::dto::SavesCommand::OpenFolder`]。
+//!
+//! 真正拉起文件管理器的是 [`unlucky_core::platform::opener::open_dir`]（`AGENTS.md` §6：
+//! 平台差异只许收敛在 `core::platform`，本文件一个 `cfg` 都没有，也没有一次裸 spawn）。
+//!
+//! ## 备份落点为什么是启动器自己的 `exports/`
+//!
+//! 本仓没有 `rfd` 这类原生文件选择框依赖（`core::launch::crash_bundle::default_target_dir` 的
+//! 文档里记着同一条理由），所以「用户选定目录」先退化成：`/exports/saves/`。
+//! 命令带一个可选的 `dest`，将来接了选择框、或 CLI 想指定别处，都不用改 core。
+//! 成功的回执里带**完整路径 + 字节数**，用户不用猜落点。
+//!
+//! ## 失败口径
+//!
+//! 一律走 [`crate::dto::SavesFailureView`]（结构 + OS 原文），**不拼中文**：文案由 app 层按
+//! i18n key 现求（M161 的纪律）。读路径三类失败见 [`crate::dto::SavesFailureKind`]，
+//! 写路径八类见同一个枚举的 `Write*` 那一族——每一种在 UI 上都有一句话。
+
+use std::path::PathBuf;
+
+use unlucky_core::game::install::instance::read_instance_config;
+use unlucky_core::game::isolation::derive_game_dir;
+use unlucky_core::game::saves::{self, SavesError, SavesScan};
+use unlucky_core::platform::opener;
+
+use crate::dto::{
+    locate, InstanceId, InstanceSummary, SavesArea, SavesCommand, SavesFailureKind, SavesFailureOp,
+    SavesFailureView, SavesListView, SavesOped, SavesSkipKind, SavesSkipView, ScreenshotPreview,
+    ScreenshotView, WorldView,
+};
+
+use super::env::HostEnv;
+use super::job::{spawn, JobSender};
+
+/// 截图的缩略图：后台解码 + 进程级 memo（D54 第 3/4/5 条，见模块文档）
+pub mod thumbs;
+
+mod write;
+
+/// 后台线程回报的一次结果（`HostTask::Saves` 的载荷）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Report {
+    /// 实例 id（迟到结果靠它判「这条还是不是当前实例的」）。
+    pub instance: InstanceId,
+    /// 列表结果：成功 = 整份快照；失败 = 具名原因。
+    pub list: Result,
+}
+
+/// 后台列一个实例的 `saves/` 与 `screenshots/`。
+pub fn spawn_list(env: HostEnv, tx: JobSender, id: InstanceId) {
+    spawn("saves-list", move || {
+        let report = Report {
+            instance: id.clone(),
+            list: list(&env, &id),
+        };
+        let _ = tx.send(super::HostTask::Saves(Box::new(report)));
+    });
+}
+
+/// 后台用系统文件管理器打开存档目录，**并把刷新后的快照一起带回来**。
+///
+/// 带快照回来不是顺手：用户常在文件管理器里删掉旧世界再切回来，页面这一拍就能跟着更新，
+/// 不用等下一次进详情页。
+pub fn spawn_open_folder(env: HostEnv, tx: JobSender, id: InstanceId) {
+    spawn("saves-open", move || {
+        let report = Report {
+            instance: id.clone(),
+            list: open_folder(&env, &id),
+        };
+        let _ = tx.send(super::HostTask::Saves(Box::new(report)));
+    });
+}
+
+/// 一条指令属于哪个实例（host 侧算「游戏在不在跑」要用它）。
+///
+/// 五条命令都带实例 id，所以这里不返回 `Option`：少一条分支处理会让闸门在那条命令上
+/// **静默失效**，而这正是 M247 要修的东西。
+#[must_use]
+pub fn instance_of(command: &SavesCommand) -> &str {
+    match command {
+        SavesCommand::List(id)
+        | SavesCommand::OpenFolder { id }
+        | SavesCommand::RenameWorld { id, .. }
+        | SavesCommand::DeleteWorld { id, .. }
+        | SavesCommand::BackupWorld { id, .. } => id,
+    }
+}
+
+/// 这条命令是不是**改盘**的写操作（读路径与打开文件夹不是）。
+fn write_target(command: &SavesCommand) -> Option<(&str, SavesFailureOp)> {
+    match command {
+        SavesCommand::RenameWorld { dir, .. } => Some((dir, SavesFailureOp::Rename)),
+        SavesCommand::DeleteWorld { dir, .. } => Some((dir, SavesFailureOp::Delete)),
+        SavesCommand::BackupWorld { dir, .. } => Some((dir, SavesFailureOp::Backup)),
+        SavesCommand::List(_) | SavesCommand::OpenFolder { .. } => None,
+    }
+}
+
+/// 一条指令 → 后台线程（`CoreHost::dispatch` 的唯一入口）。
+///
+/// `running` = 这个实例正在启动/运行中（`CoreHost::in_flight`）。为真时**三个写操作不落 core**：
+/// 直接回一条 [`SavesFailureKind::GameRunning`] 的具名失败，一个字节都不碰盘。
+///
+/// 为什么这一层必须挡：Windows 上进程占着世界目录，rename/删除会撞共享冲突（难看但至少失败）；
+/// **Linux 上删一个正在跑的世界会成功**——那是在用户玩到一半时把存档删掉。所以判据不能只靠
+/// 界面灰按钮（那也是同一条纪律：`ModsCommand::SetEnabled` 同样挡在 host 这一侧）。
+///
+/// 不 spawn 线程：没有磁盘工作要排队，直接发一条结果回去更诚实（`tx` 是同步通道）。
+pub fn dispatch(env: HostEnv, tx: JobSender, command: SavesCommand, running: bool) {
+    if running {
+        if let Some((dir, op)) = write_target(&command) {
+            let id = instance_of(&command);
+            let report = Report {
+                instance: id.to_string(),
+                list: Err(blocked(id, dir, op)),
+            };
+            let _ = tx.send(super::HostTask::Saves(Box::new(report)));
+            return;
+        }
+    }
+    match command {
+        SavesCommand::List(id) => spawn_list(env, tx, id),
+        SavesCommand::OpenFolder { id } => spawn_open_folder(env, tx, id),
+        SavesCommand::RenameWorld { id, dir, to } => write::spawn_rename(env, tx, id, dir, to),
+        SavesCommand::DeleteWorld { id, dir } => write::spawn_delete(env, tx, id, dir),
+        SavesCommand::BackupWorld { id, dir, dest } => write::spawn_backup(env, tx, id, dir, dest),
+    }
+}
+
+/// 写操作被「游戏在跑」挡下时的那条失败（**结构化，带世界名与操作**，文案由 app 层现求）。
+fn blocked(instance: &str, dir: &str, op: SavesFailureOp) -> SavesFailureView {
+    let mut failure = failure(instance, SavesFailureKind::GameRunning, String::new());
+    failure.file = dir.to_string();
+    failure.op = Some(op);
+    failure
+}
+
+/// 列目录（后台线程里调）。
+fn list(env: &HostEnv, id: &str) -> Result {
+    let (instance, run_dir) = target(env, id)?;
+    snapshot(&instance, &run_dir, None)
+}
+
+/// 重新扫一遍目录 → 快照（可挂一条写操作的回执）。
+///
+/// 写成功后**一律**走这里：界面画的是磁盘上的真相，不是"我以为我改成了什么"。
+pub(super) fn snapshot(
+    instance: &InstanceSummary,
+    run_dir: &std::path::Path,
+    last_op: Option,
+) -> Result {
+    let scan = saves::scan(run_dir).map_err(|error| unusable(&instance.id, &error))?;
+    Ok(view(&instance.id, &scan, last_op))
+}
+
+/// 打开存档目录 → 再列一遍（失败只说"打不开"，原文进括号）。
+fn open_folder(env: &HostEnv, id: &str) -> Result {
+    let (instance, run_dir) = target(env, id)?;
+    let scan = saves::scan(&run_dir).map_err(|error| unusable(&instance.id, &error))?;
+    let target = open_target(&scan, &run_dir);
+    opener::open_dir(&target)
+        .map_err(|detail| failure(&instance.id, SavesFailureKind::OpenFailed, detail))?;
+    Ok(view(&instance.id, &scan, None))
+}
+
+/// 打开哪一个目录：`saves/` → `screenshots/` → 运行目录（取第一个存在的）。
+fn open_target(scan: &SavesScan, run_dir: &std::path::Path) -> PathBuf {
+    if scan.exists {
+        return scan.dir.clone();
+    }
+    if scan.screenshots_exists {
+        return scan.screenshots_dir.clone();
+    }
+    run_dir.to_path_buf()
+}
+
+/// 实例 + 它的运行目录（找不到实例 / 派生不出目录都给具名失败）。
+pub(super) fn target(
+    env: &HostEnv,
+    id: &str,
+) -> Result<(InstanceSummary, PathBuf), SavesFailureView> {
+    let instances = super::game::instances(env);
+    let Some(instance) = locate(&instances, id) else {
+        return Err(failure(
+            id,
+            SavesFailureKind::InstanceUnavailable,
+            format!("实例 {id} 不在快照里（可能刚被删除）"),
+        ));
+    };
+    let dir = run_dir(env, instance)
+        .map_err(|detail| failure(&instance.id, SavesFailureKind::InstanceUnavailable, detail))?;
+    Ok((instance.clone(), dir))
+}
+
+/// 实例的运行目录（D20 覆盖链，与启动同一份派生；**不写盘**）。
+pub(super) fn run_dir(env: &HostEnv, instance: &InstanceSummary) -> Result {
+    let global = super::game::global_mode(env);
+    let config = read_instance_config(&env.layout, &instance.id)
+        .map_err(|error| format!("读实例设置失败：{error}"))?;
+    let derivation = derive_game_dir(
+        &env.game,
+        &instance.version_id,
+        global,
+        config.as_ref(),
+        None,
+    )
+    .map_err(|error| format!("派生运行目录失败：{error}"))?;
+    Ok(derivation.game_dir)
+}
+
+/// 快照映射：core 的扫描结果 → DTO（路径串在 host 这一侧才成形）。
+///
+/// **截图带缩略图**（M251）：像素在这里（后台线程里）解好、随快照一起交出去，UI 只画。
+/// D54 明写「不许在渲染回调里解码」——这条纪律的落点就是「`view` 里 attach，`view()` 只在
+/// 后台线程被调」。解码失败/超限/超预算的每一张都带自己的状态，不留白（D54 第 6 条）。
+fn view(instance: &str, scan: &SavesScan, last_op: Option) -> SavesListView {
+    let mut screenshots: Vec = scan
+        .screenshots
+        .iter()
+        .map(|shot| ScreenshotView {
+            file: shot.file.clone(),
+            bytes: shot.bytes,
+            modified_ms: shot.modified_ms,
+            // 先摆占位，再让 thumbs 按 mtime 倒序挑前 60 张去解（顺序与上限都在那一个模块里）。
+            preview: ScreenshotPreview::NotGenerated,
+        })
+        .collect();
+    thumbs::attach(&scan.screenshots_dir, &mut screenshots);
+    SavesListView {
+        instance: instance.to_string(),
+        dir: scan.dir.display().to_string(),
+        exists: scan.exists,
+        worlds: scan
+            .worlds
+            .iter()
+            .map(|world| WorldView {
+                dir: world.dir.clone(),
+                icon: world.icon,
+                modified_ms: world.modified_ms,
+            })
+            .collect(),
+        screenshots_dir: scan.screenshots_dir.display().to_string(),
+        screenshots_exists: scan.screenshots_exists,
+        screenshots,
+        skipped: scan
+            .skipped
+            .iter()
+            .map(|skip| SavesSkipView {
+                area: match skip.area {
+                    saves::Area::Saves => SavesArea::Saves,
+                    saves::Area::Screenshots => SavesArea::Screenshots,
+                },
+                file: skip.file.clone(),
+                reason: match skip.reason {
+                    saves::SkipKind::SymbolicLink => SavesSkipKind::SymbolicLink,
+                    saves::SkipKind::NotADirectoryExpected => SavesSkipKind::NotADirectory,
+                    saves::SkipKind::NotAFile => SavesSkipKind::NotAFile,
+                    saves::SkipKind::UnsafeName => SavesSkipKind::UnsafeName,
+                    saves::SkipKind::Unreadable => SavesSkipKind::Unreadable,
+                    saves::SkipKind::NotAnImage => SavesSkipKind::NotAnImage,
+                },
+            })
+            .collect(),
+        last_op,
+    }
+}
+
+pub(super) fn failure(
+    instance: &str,
+    kind: SavesFailureKind,
+    detail: impl Into,
+) -> SavesFailureView {
+    SavesFailureView {
+        instance: instance.to_string(),
+        file: String::new(),
+        op: None,
+        kind,
+        detail: detail.into(),
+    }
+}
+
+/// core 的错误 → 「目录不可用」+ 原文（**不翻译**，翻译在 app 层）。
+fn unusable(instance: &str, error: &SavesError) -> SavesFailureView {
+    failure(
+        instance,
+        SavesFailureKind::DirUnusable,
+        format!("{}：{}", error.dir.display(), error.detail),
+    )
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/presenter/src/host/saves/tests.rs b/crates/presenter/src/host/saves/tests.rs
new file mode 100644
index 0000000..3d4c1a8
--- /dev/null
+++ b/crates/presenter/src/host/saves/tests.rs
@@ -0,0 +1,247 @@
+//! `host::saves` 的用例：**真盘端到端**（派生运行目录 → core 只读列目录 → 快照回来）。
+//!
+//! 端到端那条是这个模块存在的主要理由：只有"真的建一个实例根、真的放几个世界和截图再读回来"
+//! 才能验「派生出来的目录就是玩家看到的那个目录」。
+//!
+//! 抓不住什么：`OpenFolder` **不在这里真跑**（它会拉起用户的文件管理器）；它唯一的判断
+//! （打开哪个目录）由 [`open_target_degrades_from_saves_to_run_dir`] 这条纯函数用例钉住，
+//! 真正 spawn 的那一步在 core 的 `platform::opener` 用例里。
+//!
+//! 「游戏在跑就拒」（M247）由 [`write_commands_do_not_touch_the_disk_while_the_game_is_running`]
+//! 从 **`dispatch` 那一层**验：三条写命令一条都不落 core（盘上指纹前后一致 + 备份落点没被建），
+//! 并且回一条 `GameRunning` 的具名失败。
+
+use super::*;
+use crate::dto::{InstanceRuntime, LaunchArgsView, LoaderInfo, LoaderKind};
+use unlucky_core::game::saves::{SavesScan, SavesSkip, SkipKind};
+
+const ID: &str = "survival";
+const VERSION: &str = "1.20.4-fabric-0.16.5";
+
+/// 一次性临时根（与本 crate 其它 host 测试同款：不引第三方 tempfile）。
+struct TempRoot(PathBuf);
+
+impl Drop for TempRoot {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_dir_all(&self.0);
+    }
+}
+
+/// 一个可用的便携根 + 一个 `custom` 档位的实例（运行目录由实例自己指，D20 里唯一这样表达的档位）。
+///
+/// 走 `custom` 是**故意**的：用例不必造 `versions//` 就能验「派生出来的目录就是读的那个」。
+fn fixture(tag: &str) -> (TempRoot, HostEnv, PathBuf) {
+    use std::sync::atomic::{AtomicU64, Ordering};
+    static COUNTER: AtomicU64 = AtomicU64::new(0);
+    let seq = COUNTER.fetch_add(1, Ordering::Relaxed);
+    let path = std::env::temp_dir().join(format!("{tag}-{}-{seq}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&path);
+    let root = TempRoot(path);
+    std::fs::create_dir_all(&root.0).expect("建临时目录");
+    let env = HostEnv::at_root(&root.0);
+    let run = root.0.join("run");
+    std::fs::create_dir_all(&run).expect("建运行目录");
+    std::fs::create_dir_all(env.layout.config()).expect("建 config");
+    let profile = format!(r#"{{"id":"{ID}","name":"生存","versionId":"{VERSION}"}}"#);
+    std::fs::write(
+        env.layout.profiles_config(),
+        format!(r#"{{"schemaVersion":1,"profiles":[{profile}]}}"#),
+    )
+    .expect("写 profiles");
+    let config = format!(
+        r#"{{"schemaVersion":1,"id":"{ID}","versionId":"{VERSION}","isolation":"custom","gameDir":{}}}"#,
+        serde_json::to_string(&run).expect("路径转 JSON")
+    );
+    let path = env.layout.instance_config(ID).expect("实例 id");
+    std::fs::create_dir_all(path.parent().expect("instances 目录")).expect("建 instances");
+    std::fs::write(path, config).expect("写实例设置");
+    (root, env, run)
+}
+
+fn instance() -> InstanceSummary {
+    InstanceSummary {
+        id: ID.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: None,
+        runtime: InstanceRuntime::Idle,
+        icon: None,
+        isolation: "custom".to_string(),
+        version_id: VERSION.to_string(),
+        version_present: true,
+        launch: LaunchArgsView::default(),
+    }
+}
+
+/// 一个真世界（`saves//level.dat`）。
+fn world(run: &std::path::Path, name: &str) {
+    std::fs::create_dir_all(run.join("saves").join(name)).expect("建世界");
+    std::fs::write(run.join("saves").join(name).join("level.dat"), b"nbt").expect("写 level.dat");
+}
+
+/// **端到端**（真盘 + 真派生）：世界 / 截图 / 跳过原因都过桥，且快照里的路径就是派生目录。
+///
+/// 抓得住：派生用错目录、`icon.png` 被当成"读到了"、跳过原因被折叠、字节数丢了。
+#[test]
+fn list_round_trips_on_a_real_root() {
+    let (_root, env, run) = fixture("saves-e2e");
+    std::fs::create_dir_all(run.join("saves/My World")).expect("建世界");
+    std::fs::write(run.join("saves/My World/icon.png"), b"png").expect("写图标");
+    std::fs::create_dir_all(run.join("saves/Bare World")).expect("建世界 2");
+    std::fs::create_dir_all(run.join("screenshots")).expect("建截图目录");
+    std::fs::write(run.join("screenshots/2024-05-01_10.00.00.png"), b"abc").expect("写截图");
+    std::fs::write(run.join("screenshots/notes.txt"), b"x").expect("写非图片");
+
+    let listed = list(&env, ID).expect("列存档");
+    assert!(listed.exists && listed.screenshots_exists);
+    assert_eq!(std::path::PathBuf::from(&listed.dir), run.join("saves"));
+    assert_eq!(
+        std::path::PathBuf::from(&listed.screenshots_dir),
+        run.join("screenshots")
+    );
+
+    let worlds: Vec<(&str, bool)> = listed
+        .worlds
+        .iter()
+        .map(|world| (world.dir.as_str(), world.icon))
+        .collect();
+    assert_eq!(worlds, [("Bare World", false), ("My World", true)]);
+    assert_eq!(listed.world_count(), 2);
+
+    assert_eq!(listed.screenshot_count(), 1);
+    assert_eq!(listed.screenshots[0].bytes, 3);
+    assert_eq!(
+        listed.skipped_count(),
+        1,
+        "非图片文件要登记原因，不能静默丢"
+    );
+    assert_eq!(listed.skipped[0].reason, SavesSkipKind::NotAnImage);
+    assert_eq!(listed.skipped[0].area, SavesArea::Screenshots);
+}
+
+/// 「打开文件夹」打开哪个目录：`saves/` → `screenshots/` → 运行目录。
+///
+/// 纯函数，**不 spawn**（真拉起文件管理器那一步在 core 的 opener 用例里）。
+#[test]
+fn open_target_degrades_from_saves_to_run_dir() {
+    let run = PathBuf::from("D:/ULL/.ULL/data/instances/x");
+    let mut scan = SavesScan {
+        dir: run.join("saves"),
+        exists: true,
+        worlds: Vec::new(),
+        screenshots_dir: run.join("screenshots"),
+        screenshots_exists: true,
+        screenshots: Vec::new(),
+        skipped: Vec::new(),
+    };
+    assert_eq!(open_target(&scan, &run), run.join("saves"));
+
+    scan.exists = false;
+    assert_eq!(
+        open_target(&scan, &run),
+        run.join("screenshots"),
+        "saves 不在时退到 screenshots"
+    );
+
+    scan.screenshots_exists = false;
+    assert_eq!(open_target(&scan, &run), run, "两个都没有时打开运行目录");
+}
+
+/// 找不到实例 ⇒ 具名失败（不是"空列表"：那会让页面以为这实例没存档）。
+#[test]
+fn missing_instance_is_a_named_failure() {
+    let (_root, env, _run) = fixture("saves-unknown");
+    let failure = list(&env, "no-such-instance").expect_err("不存在的实例居然列成功了");
+    assert_eq!(failure.kind, SavesFailureKind::InstanceUnavailable);
+    assert_eq!(failure.instance, "no-such-instance");
+    assert!(!failure.detail.is_empty(), "原因被吃掉了");
+}
+
+/// `saves/` 存在但不可用 ⇒ `DirUnusable`，且原文里带着那个路径（用户能自己去看）。
+#[test]
+fn unusable_dir_maps_to_dir_unusable() {
+    let (_root, env, run) = fixture("saves-unusable");
+    std::fs::write(run.join("saves"), b"not a dir").expect("用文件占住 saves");
+
+    let failure = list(&env, ID).expect_err("saves 是个文件，居然列成功了");
+    assert_eq!(failure.kind, SavesFailureKind::DirUnusable);
+    assert!(
+        failure.detail.contains("saves"),
+        "原文里没有路径：{}",
+        failure.detail
+    );
+}
+
+/// 跳过原因一一对应（`NotADirectoryExpected` → `NotADirectory` 这条尤其容易抄错）。
+#[test]
+fn every_core_skip_reason_keeps_its_own_kind() {
+    let cases = [
+        (SkipKind::SymbolicLink, SavesSkipKind::SymbolicLink),
+        (
+            SkipKind::NotADirectoryExpected,
+            SavesSkipKind::NotADirectory,
+        ),
+        (SkipKind::NotAFile, SavesSkipKind::NotAFile),
+        (SkipKind::UnsafeName, SavesSkipKind::UnsafeName),
+        (SkipKind::Unreadable, SavesSkipKind::Unreadable),
+        (SkipKind::NotAnImage, SavesSkipKind::NotAnImage),
+    ];
+    for (reason, expected) in cases {
+        let scan = SavesScan {
+            dir: PathBuf::from("s"),
+            exists: true,
+            worlds: Vec::new(),
+            screenshots_dir: PathBuf::from("sh"),
+            screenshots_exists: true,
+            screenshots: Vec::new(),
+            skipped: vec![SavesSkip {
+                area: saves::Area::Saves,
+                file: "x".to_string(),
+                reason,
+            }],
+        };
+        assert_eq!(view(ID, &scan, None).skipped[0].reason, expected);
+    }
+}
+
+/// `(相对路径, 是否目录, 字节数, mtime 毫秒)` 的排序列表：「这一拍有没有写盘」的判据本体。
+fn fingerprint(root: &std::path::Path) -> Vec {
+    let mut out = Vec::new();
+    let mut stack = vec![root.to_path_buf()];
+    while let Some(dir) = stack.pop() {
+        let Ok(read) = std::fs::read_dir(&dir) else {
+            continue;
+        };
+        for entry in read.flatten() {
+            let path = entry.path();
+            let Ok(meta) = std::fs::symlink_metadata(&path) else {
+                continue;
+            };
+            let rel = path
+                .strip_prefix(root)
+                .unwrap_or(&path)
+                .display()
+                .to_string();
+            out.push(format!(
+                "{rel}|dir={}|len={}|mtime={}",
+                meta.is_dir(),
+                meta.len(),
+                meta.modified()
+                    .ok()
+                    .and_then(|time| time.duration_since(std::time::SystemTime::UNIX_EPOCH).ok())
+                    .map_or(0, |since| since.as_millis())
+            ));
+            if meta.is_dir() {
+                stack.push(path);
+            }
+        }
+    }
+    out.sort();
+    out
+}
+
+mod write;
diff --git a/crates/presenter/src/host/saves/tests/write.rs b/crates/presenter/src/host/saves/tests/write.rs
new file mode 100644
index 0000000..a45621e
--- /dev/null
+++ b/crates/presenter/src/host/saves/tests/write.rs
@@ -0,0 +1,341 @@
+//! 三个**写操作**与「游戏在跑」闸门的用例（M247）——从 `host/saves/tests.rs` 拆出
+//! （那边加完 7 条之后越过 400 行硬线；判据一条不改）。
+//!
+//! | 用例 | 抓得住 |
+//! |---|---|
+//! | [`rename_round_trips_on_a_real_root`] / [`delete_round_trips_on_a_real_root`] | 真盘改动 + 快照刷新 + 回执对得上 |
+//! | [`backup_round_trips_to_the_exports_dir`] | zip 落到 `/exports/saves/`，回执带路径/字节/跳过数；显式落点也照用 |
+//! | [`every_write_failure_keeps_its_own_kind`] | core 八类 → DTO 八类一一对应（不折叠），带世界名与操作 |
+//! | [`write_commands_do_not_touch_the_disk_while_the_game_is_running`] | **在飞时一条都不落 core**：盘上指纹不变、世界还在、备份落点没建、回 `GameRunning` |
+//! | [`write_commands_run_when_the_game_is_not_running`] | 闸门没有把写操作一并关死 |
+//! | [`read_commands_are_not_blocked_while_the_game_is_running`] | 读路径与打开文件夹不受影响 |
+//! | [`every_command_names_its_instance`] | 五条命令都答得上「哪个实例」（闸门靠它算在不在跑） |
+
+use super::super::write::{backup, delete, rename, write_failure};
+use super::super::*;
+use super::{fingerprint, fixture, world, ID};
+use crate::dto::{SavesCommand, SavesFailureOp, SavesFailureView, SavesOped};
+use unlucky_core::game::saves::SavesWriteKind;
+
+/// **端到端**：重命名 → 真盘改名 + 新快照 + 回执。
+///
+/// 抓得住：host 用错运行目录、写完成却忘了重新列（界面还画旧名字）、回执与快照对不上。
+#[test]
+fn rename_round_trips_on_a_real_root() {
+    let (_root, env, run) = fixture("saves-rename");
+    world(&run, "Old World");
+    world(&run, "Other");
+
+    let listed = rename(&env, ID, "Old World", "New World").expect("改名");
+    assert!(!run.join("saves/Old World").exists(), "旧目录还在");
+    assert!(
+        run.join("saves/New World/level.dat").exists(),
+        "新目录里没有内容"
+    );
+    let names: Vec<&str> = listed
+        .worlds
+        .iter()
+        .map(|world| world.dir.as_str())
+        .collect();
+    assert_eq!(names, ["New World", "Other"], "快照没跟着刷新");
+    assert_eq!(
+        listed.last_op,
+        Some(SavesOped::Renamed {
+            from: "Old World".to_string(),
+            to: "New World".to_string()
+        })
+    );
+}
+
+/// **端到端**：删除 → 真盘没了 + 新快照 + 回执。
+#[test]
+fn delete_round_trips_on_a_real_root() {
+    let (_root, env, run) = fixture("saves-delete");
+    world(&run, "Doomed");
+    world(&run, "Kept");
+
+    let listed = delete(&env, ID, "Doomed").expect("删除");
+    assert!(!run.join("saves/Doomed").exists(), "目录还在");
+    let names: Vec<&str> = listed
+        .worlds
+        .iter()
+        .map(|world| world.dir.as_str())
+        .collect();
+    assert_eq!(names, ["Kept"], "别的世界被连带删了 / 快照没刷新");
+    assert_eq!(
+        listed.last_op,
+        Some(SavesOped::Deleted {
+            dir: "Doomed".to_string()
+        })
+    );
+}
+
+/// **端到端**：备份 → zip 落在启动器自己的 `exports/saves/`，回执带路径与字节数。
+#[test]
+fn backup_round_trips_to_the_exports_dir() {
+    let (_root, env, run) = fixture("saves-backup");
+    world(&run, "My World");
+
+    let listed = backup(&env, ID, "My World", None).expect("备份");
+    let exports = env.layout.data().join("exports").join("saves");
+    let Some(SavesOped::BackedUp {
+        dir,
+        file,
+        path,
+        bytes,
+        skipped,
+    }) = listed.last_op.clone()
+    else {
+        panic!("备份成功却没有回执：{:?}", listed.last_op);
+    };
+    assert_eq!(dir, "My World");
+    assert!(
+        file.starts_with("My World-"),
+        "文件名要带世界名与时戳：{file}"
+    );
+    assert!(file.ends_with(".zip"), "文件名要带 .zip：{file}");
+    assert_eq!(std::path::PathBuf::from(&path), exports.join(&file));
+    assert!(std::path::Path::new(&path).exists(), "zip 没真的落盘");
+    assert!(bytes > 0);
+    assert_eq!(skipped, 0);
+    // 备份不改世界本身：列表还是一行。
+    assert_eq!(listed.world_count(), 1);
+    // 显式落点也要照用（将来接了目录选择框就走这条）。
+    let custom = backup(
+        &env,
+        ID,
+        "My World",
+        Some(&run.join("elsewhere").display().to_string()),
+    )
+    .expect("备份到指定目录");
+    assert!(matches!(custom.last_op, Some(SavesOped::BackedUp { .. })));
+    assert!(run.join("elsewhere").is_dir(), "显式落点没被采用");
+}
+
+/// 八种写失败各给**自己的**类别（没有一个落到「未知」兜底）。
+#[test]
+fn every_write_failure_keeps_its_own_kind() {
+    let (_root, env, run) = fixture("saves-write-kinds");
+    world(&run, "Taken");
+    world(&run, "Other");
+
+    let cases = [
+        ("Other", "Taken", SavesFailureKind::WriteConflict),
+        ("Other", "..", SavesFailureKind::WriteUnsafeName),
+        ("Nope", "Fresh", SavesFailureKind::WriteMissing),
+    ];
+    for (from, to, expected) in cases {
+        let failure = rename(&env, ID, from, to).expect_err("改成功了");
+        assert_eq!(failure.kind, expected, "{from} → {to}：{}", failure.detail);
+    }
+
+    let failure = delete(&env, ID, "Nope").expect_err("删成功了");
+    assert_eq!(failure.kind, SavesFailureKind::WriteMissing);
+    // 空 / 相对的落点目录：会落到进程当前目录，所以是「越界」而不是「IO 失败」。
+    let failure = backup(&env, ID, "Taken", Some("")).expect_err("备份到空目录居然成功了");
+    assert_eq!(
+        failure.kind,
+        SavesFailureKind::WriteBoundary,
+        "{}",
+        failure.detail
+    );
+
+    // core 的八个类别 → DTO 八个类别（一一对应，不折叠）。
+    let pairs = [
+        (
+            SavesWriteKind::UnsafeName,
+            SavesFailureKind::WriteUnsafeName,
+        ),
+        (SavesWriteKind::SymbolicLink, SavesFailureKind::WriteSymlink),
+        (SavesWriteKind::NotFound, SavesFailureKind::WriteMissing),
+        (
+            SavesWriteKind::NotADirectory,
+            SavesFailureKind::WriteNotADirectory,
+        ),
+        (SavesWriteKind::Conflict, SavesFailureKind::WriteConflict),
+        (SavesWriteKind::Boundary, SavesFailureKind::WriteBoundary),
+        (SavesWriteKind::TooLarge, SavesFailureKind::WriteTooLarge),
+        (SavesWriteKind::Io, SavesFailureKind::WriteFailed),
+    ];
+    for (core, expected) in pairs {
+        let error = unlucky_core::game::saves::SavesWriteError {
+            path: PathBuf::from("C:/mc/saves/x"),
+            kind: core,
+            detail: "原文".to_string(),
+        };
+        let failure = write_failure(ID, SavesFailureOp::Backup, "Taken", &error);
+        assert_eq!(failure.kind, expected, "{core:?}");
+        assert!(
+            failure.detail.contains("saves"),
+            "原文丢了：{}",
+            failure.detail
+        );
+        assert_eq!(failure.instance, ID);
+        assert_eq!(failure.file, "Taken", "失败那句话要指名是哪一行");
+        assert_eq!(failure.op, Some(SavesFailureOp::Backup));
+    }
+}
+
+/// **在飞闸门**：三条写命令一条都不落 core —— 盘上指纹前后一致、世界还在、备份落点没被建，
+/// 而且回的是 `GameRunning`（不是"写盘失败"）。
+///
+/// 抓得住：把闸门放回 UI（只灰按钮）——那时 `dispatch(..., running = true)` 会真的删掉世界，
+/// 这条用例立刻红（指纹变了 / 世界不在 / `kind` 不是 `GameRunning`）。
+#[test]
+fn write_commands_do_not_touch_the_disk_while_the_game_is_running() {
+    let (_root, env, run) = fixture("saves-running");
+    world(&run, "Doomed");
+    let before = fingerprint(&run);
+    let (tx, rx) = super::super::super::job::channel();
+
+    let commands = [
+        SavesCommand::RenameWorld {
+            id: ID.to_string(),
+            dir: "Doomed".to_string(),
+            to: "Renamed".to_string(),
+        },
+        SavesCommand::DeleteWorld {
+            id: ID.to_string(),
+            dir: "Doomed".to_string(),
+        },
+        SavesCommand::BackupWorld {
+            id: ID.to_string(),
+            dir: "Doomed".to_string(),
+            dest: None,
+        },
+    ];
+    for command in commands {
+        let expected = match &command {
+            SavesCommand::RenameWorld { .. } => SavesFailureOp::Rename,
+            SavesCommand::DeleteWorld { .. } => SavesFailureOp::Delete,
+            _ => SavesFailureOp::Backup,
+        };
+        dispatch(env.clone(), tx.clone(), command, true);
+        let task = rx
+            .recv_timeout(std::time::Duration::from_secs(5))
+            .expect("在飞时 host 没有回结果");
+        let crate::host::HostTask::Saves(report) = task else {
+            panic!("回程不是存档事件");
+        };
+        assert_eq!(report.instance, ID);
+        let failure = report.list.expect_err("在飞时居然写成功了");
+        assert_eq!(
+            failure.kind,
+            SavesFailureKind::GameRunning,
+            "{}",
+            failure.detail
+        );
+        assert_eq!(failure.file, "Doomed", "失败那句话要指名哪一行");
+        assert_eq!(failure.op, Some(expected));
+    }
+
+    assert_eq!(fingerprint(&run), before, "在飞时写了盘");
+    assert!(
+        run.join("saves/Doomed/level.dat").exists(),
+        "世界被删/被改名了"
+    );
+    assert!(
+        !env.layout.data().join("exports").exists(),
+        "在飞时备份落了盘"
+    );
+}
+
+/// 反向：不在飞时同一条 `dispatch` 该真的干（闸门不是把写操作一并关死）。
+#[test]
+fn write_commands_run_when_the_game_is_not_running() {
+    let (_root, env, run) = fixture("saves-idle-dispatch");
+    world(&run, "Doomed");
+    let (tx, rx) = super::super::super::job::channel();
+
+    dispatch(
+        env.clone(),
+        tx.clone(),
+        SavesCommand::DeleteWorld {
+            id: ID.to_string(),
+            dir: "Doomed".to_string(),
+        },
+        false,
+    );
+    let task = rx
+        .recv_timeout(std::time::Duration::from_secs(5))
+        .expect("host 没有回结果");
+    let crate::host::HostTask::Saves(report) = task else {
+        panic!("回程不是存档事件");
+    };
+    let listed = report.list.expect("不在飞时该照常删");
+    assert!(!run.join("saves/Doomed").exists(), "闸门把写操作一并关死了");
+    assert!(matches!(listed.last_op, Some(SavesOped::Deleted { .. })));
+}
+
+/// 读路径**不受**在飞闸门影响（它不改盘）。
+#[test]
+fn read_commands_are_not_blocked_while_the_game_is_running() {
+    let (_root, env, run) = fixture("saves-running-read");
+    world(&run, "Kept");
+    let (tx, rx) = super::super::super::job::channel();
+
+    dispatch(
+        env.clone(),
+        tx.clone(),
+        SavesCommand::List(ID.to_string()),
+        true,
+    );
+    let task = rx
+        .recv_timeout(std::time::Duration::from_secs(5))
+        .expect("host 没有回结果");
+    let crate::host::HostTask::Saves(report) = task else {
+        panic!("回程不是存档事件");
+    };
+    let listed = report.list.expect("在飞时读列表不该被拒");
+    assert_eq!(listed.world_count(), 1);
+    assert!(listed.last_op.is_none());
+}
+
+/// 每一层都认得同一个实例 id（闸门用它算「在不在跑」——漏一条分支就等于那条命令没有闸门）。
+#[test]
+fn every_command_names_its_instance() {
+    let commands = [
+        SavesCommand::List(ID.to_string()),
+        SavesCommand::OpenFolder { id: ID.to_string() },
+        SavesCommand::RenameWorld {
+            id: ID.to_string(),
+            dir: "A".to_string(),
+            to: "B".to_string(),
+        },
+        SavesCommand::DeleteWorld {
+            id: ID.to_string(),
+            dir: "A".to_string(),
+        },
+        SavesCommand::BackupWorld {
+            id: ID.to_string(),
+            dir: "A".to_string(),
+            dest: None,
+        },
+    ];
+    assert_eq!(commands.len(), 5, "新增了命令就要在这里补一条");
+    for command in &commands {
+        assert_eq!(instance_of(command), ID, "{command:?}");
+    }
+}
+
+/// 找不到实例的写操作 ⇒ 同一个具名失败（不是"写成功了个空的"）。
+#[test]
+fn write_ops_on_a_vanished_instance_are_named() {
+    let (_root, env, _run) = fixture("saves-write-unknown");
+    for failure in [
+        rename(&env, "gone", "A", "B").expect_err("改名成功了"),
+        delete(&env, "gone", "A").expect_err("删除成功了"),
+        backup(&env, "gone", "A", None).expect_err("备份成功了"),
+    ] {
+        assert_eq!(failure.kind, SavesFailureKind::InstanceUnavailable);
+        assert_eq!(failure.instance, "gone");
+    }
+    // 这个用例只借 `SavesFailureView` 的类型做一次构造检查：字段齐了才算「结构化失败」。
+    let _probe = SavesFailureView {
+        instance: "gone".to_string(),
+        file: String::new(),
+        op: None,
+        kind: SavesFailureKind::InstanceUnavailable,
+        detail: String::new(),
+    };
+}
diff --git a/crates/presenter/src/host/saves/thumbs.rs b/crates/presenter/src/host/saves/thumbs.rs
new file mode 100644
index 0000000..07fa327
--- /dev/null
+++ b/crates/presenter/src/host/saves/thumbs.rs
@@ -0,0 +1,202 @@
+//! 截图的**后台解码 + 进程级 memo**（M251 · SAVESHOTS，落地 D54 第 3/4/5/6 条）。
+//!
+//! ## 为什么解码在后台线程
+//!
+//! 一屏 60 张 PNG 解码是几百毫秒量级的工作。D54 明写「**不许**在渲染回调里解码」：把这段放进
+//! `iced` 的 `view()` 会直接把帧率打穿。所以解码发生在 [`super::spawn_list`] 那条后台线程里
+//! （`job::spawn`，与 `host/saves.rs` 同一模式），UI 那一侧只收一份**带像素的快照**。
+//!
+//! ## 缓存键为什么必须是三段
+//!
+//! `(路径, mtime, 大小)`——**只按路径**是错的，而且是那种「测试不会红」的错：
+//!
+//! | 场景 | 只按路径的后果 |
+//! |---|---|
+//! | 游戏又存了一张同名截图（覆盖） | 永远显示上一张的缩略图 |
+//! | 用户拿同名文件替换（修图后放回） | 同上，且没有任何日志 |
+//!
+//! 带上 mtime 与大小之后，覆盖 ⇒ 键变了 ⇒ 重解。这条由
+//! `tests::a_changed_file_is_decoded_again` 钉住（把 mtime 从键里去掉，它必红）。
+//!
+//! ## 为什么是**进程级** memo 而不是状态字段
+//!
+//! 解码发生在 `spawn_list` 起的线程里，而那条线程拿到的东西只有 `HostEnv` + `tx`（见
+//! `host/saves.rs`）。把缓存挂到 `CoreHost` 上要改 `host/mod.rs`（贴着 400 行）与
+//! `host/dispatch.rs`（M251 的 scope 外），换来的语义与这里**完全一样**：键是全路径，多实例
+//! 共享一份不会串味；它也不是业务状态，只是一份「同样的键不再重解」的记忆。
+//!
+//! ## 两条硬上限（D54 第 5 条）
+//!
+//! | 上限 | 值 | 为什么 |
+//! |---|---|---|
+//! | 单张字节数 | [`MAX_SOURCE_BYTES`] = 8 MiB | 一张 200MB 的 PNG 解码要几 GB 内存；**解码前**查大小，超了就不进解码器，并留一条可见原因 |
+//! | 每次刷新张数 | [`MAX_PER_REFRESH`] = 60 | 按 mtime 倒序只解前 60 张（最近玩的那几屏最有用），其余给「未生成预览」占位 |
+//!
+//! 上限是**逐条可见**的：跳过的那张在快照里带 [`ScreenshotPreview::Failed`] 或
+//! [`ScreenshotPreview::NotGenerated`]，不是静默少一张（D54 第 6 条）。
+//!
+//! ## 缓存不会无限长
+//!
+//! 键里有 mtime，覆盖一次就多一个键。所以超过 [`MAX_CACHE_ENTRIES`] 时只保留**这一次刷新碰到
+//! 的键**（换目录、删截图之后旧键一起掉）。代价是极端情况下重解一次，收益是常驻内存有界。
+
+use std::collections::HashMap;
+use std::path::Path;
+use std::sync::{Mutex, OnceLock};
+
+use unlucky_palette_extract::{thumbnail, ExtractError, THUMBNAIL_MAX_EDGE};
+
+use crate::dto::{
+    ScreenshotPreview, ScreenshotThumbFailure, ScreenshotThumbKind, ScreenshotView, ThumbnailView,
+};
+
+/// 单张截图的解码上限（字节）。超过就**不解码**（D54 第 5 条）。
+pub const MAX_SOURCE_BYTES: u64 = 8 * 1024 * 1024;
+
+/// 每次刷新最多解几张（按 mtime 倒序取前这么多）。
+pub const MAX_PER_REFRESH: usize = 60;
+
+/// 缓存的条目上限（超过就只留这一拍碰到的键）。
+///
+/// **算过内存**：一张缩略图最多 `160×160×4 = 102.4 KB`，120 条 ⇒ **上限 ≈ 12 MB**；
+/// 一次刷新最多碰 60 张（≈6 MB），所以 120 = 「当前这一屏 + 上一屏」的余量。
+/// 定这条上限的背景：缓存是**进程级静态**（见 [`cache`]），不随实例/数据根释放，
+/// 所以要有一个能算出来的天花板，而不是「反正删了就少一张」。
+pub const MAX_CACHE_ENTRIES: usize = 120;
+
+/// 缓存键：**(完整路径, mtime 毫秒, 字节数)**。
+///
+/// 三段缺一不可，理由见模块文档的表格。`mtime` 是 `Option`：取不到时间的文件用 `None` 占位
+/// （那种文件本来就没有「变了」的可靠判据，大小仍然兜住一部分）。
+type Key = (String, Option, u64);
+
+/// 缓存里存的是**结局**（成功或失败）。
+///
+/// 失败也缓存：一张坏 PNG 不该每次刷新都重解一遍（那是「滚动一次卡一次」的另一种来源）。
+/// 键里带 mtime ⇒ 用户修好文件（mtime 变）之后自然会重解。
+type Cache = HashMap>;
+
+fn cache() -> &'static Mutex {
+    static CACHE: OnceLock> = OnceLock::new();
+    CACHE.get_or_init(|| Mutex::new(HashMap::new()))
+}
+
+/// 清空缓存（**只给用例**：这是进程级静态，用例之间必须能从已知状态起跑）。
+///
+/// 生产路径没有任何调用点——键里带完整路径，两个数据根/两个实例共用一个静态表也不会串味
+/// （见模块文档「为什么是进程级 memo」）；但**用例**会反复用短路径造键，谁都不该依赖
+/// 「上一个用例刚好留了/没留什么」。
+#[cfg(test)]
+pub(super) fn clear_cache() {
+    cache()
+        .lock()
+        .unwrap_or_else(|poison| poison.into_inner())
+        .clear();
+}
+
+/// 给一批截图挂上预览（**在后台线程里调**，`super::view` 的唯一调用点）。
+pub(super) fn attach(dir: &Path, views: &mut [ScreenshotView]) {
+    attach_with(dir, views, &mut decode);
+}
+
+/// [`attach`] 的可测内核：解码器是一个参数，于是用例能数「到底进了几次解码器」。
+///
+/// 这类断言正是 D54 要求的那条「**缓存命中不重复解码**」：数的是解码器的调用次数，不是
+/// 「界面上看起来一样」。
+fn attach_with(
+    dir: &Path,
+    views: &mut [ScreenshotView],
+    decode: &mut impl FnMut(&Path, u64) -> Result,
+) {
+    if views.is_empty() {
+        return;
+    }
+    // ① 排序：mtime 倒序（取不到的排最后），同刻按文件名倒序兜底（两次刷新之间不抖）。
+    let mut order: Vec = (0..views.len()).collect();
+    order.sort_by(|&left, &right| {
+        views[right]
+            .modified_ms
+            .cmp(&views[left].modified_ms)
+            .then_with(|| views[right].file.cmp(&views[left].file))
+    });
+
+    let mut store = cache().lock().unwrap_or_else(|poison| poison.into_inner());
+    let mut touched: Vec = Vec::with_capacity(order.len().min(MAX_PER_REFRESH));
+    for (rank, &index) in order.iter().enumerate() {
+        // ② 超出这一拍的解码预算：占位，不碰盘、不进解码器。
+        if rank >= MAX_PER_REFRESH {
+            views[index].preview = ScreenshotPreview::NotGenerated;
+            continue;
+        }
+        let (file, bytes, modified) = {
+            let shot = &views[index];
+            (shot.file.clone(), shot.bytes, shot.modified_ms)
+        };
+        // ③ 单张太大：**解码前**就拒，理由逐条可见。
+        if bytes > MAX_SOURCE_BYTES {
+            views[index].preview = ScreenshotPreview::Failed(ScreenshotThumbFailure {
+                kind: ScreenshotThumbKind::TooLarge,
+                detail: format!("{bytes} > {MAX_SOURCE_BYTES}"),
+            });
+            continue;
+        }
+        // ④ 缓存 → 解码 → 回填。
+        let path = dir.join(&file);
+        let key: Key = (path.display().to_string(), modified, bytes);
+        let outcome = match store.get(&key) {
+            Some(cached) => cached.clone(),
+            None => {
+                let computed = decode(&path, bytes);
+                store.insert(key.clone(), computed.clone());
+                computed
+            }
+        };
+        touched.push(key);
+        views[index].preview = match outcome {
+            Ok(view) => ScreenshotPreview::Ready(view),
+            Err(failure) => ScreenshotPreview::Failed(failure),
+        };
+    }
+    // ⑤ 有界：只留这一拍碰到的键（旧的一律掉）。
+    prune(&mut store, &touched);
+}
+
+/// 淘汰策略：超过 [`MAX_CACHE_ENTRIES`] 时只留这一拍碰到的键。
+///
+/// 单独成函数是为了**能在本地 `Cache` 上测**：全局缓存被所有用例共享，谁往它里面灌 240+ 条
+/// 就会顺手把别的用例刚缓存的键清掉（M251 实测：并行跑时 `the_second_identical_refresh_...`
+/// 会假红）。策略与「共享状态」解耦之后，两条判据各自确定。
+fn prune(store: &mut Cache, touched: &[Key]) {
+    if store.len() > MAX_CACHE_ENTRIES {
+        store.retain(|key, _| touched.contains(key));
+    }
+}
+
+/// 真解码（唯一碰 `image` 的地方；错都在 `palette-extract` 里分好类了）。
+fn decode(path: &Path, _bytes: u64) -> Result {
+    match thumbnail(path, THUMBNAIL_MAX_EDGE) {
+        Ok(image) => Ok(ThumbnailView {
+            width: image.width(),
+            height: image.height(),
+            pixels: image.pixels().to_vec(),
+        }),
+        Err(error) => Err(failure(&error)),
+    }
+}
+
+/// `palette-extract` 的错误 → 预览失败的大类 + 原文（不翻译，翻译在 app 层）。
+fn failure(error: &ExtractError) -> ScreenshotThumbFailure {
+    let kind = match error {
+        ExtractError::Io(_) => ScreenshotThumbKind::Unreadable,
+        // 取色失败那条支在本路径上不可能出现（`thumbnail` 不做量化），但穷尽 match 比
+        // 通配兜底诚实：真出现了也算「解不出来」，不会被当成读到了。
+        ExtractError::Decode(_) | ExtractError::Palette(_) => ScreenshotThumbKind::Decode,
+    };
+    ScreenshotThumbFailure {
+        kind,
+        detail: error.to_string(),
+    }
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/presenter/src/host/saves/thumbs/tests.rs b/crates/presenter/src/host/saves/thumbs/tests.rs
new file mode 100644
index 0000000..44698a3
--- /dev/null
+++ b/crates/presenter/src/host/saves/thumbs/tests.rs
@@ -0,0 +1,319 @@
+//! `host::saves::thumbs` 的用例：**数解码器调用次数**，不靠"看起来一样"。
+//!
+//! 每一条都按 D54 的判据写，并且都带一句「抓得住什么 / 抓不住什么」。T27 要求的两条变异都有对应用例：
+//!
+//! | 变异 | 必红的用例 |
+//! |---|---|
+//! | 缓存键去掉 mtime（或改成只按路径） | [`a_changed_file_is_decoded_again`]（同一路径、同一大小、只改 mtime ⇒ 必须重解）与 [`a_changed_size_is_decoded_again`] |
+//! | 单张 8 MiB 上限改成无上限 | [`a_file_over_the_size_cap_never_reaches_the_decoder`]（解码器调用次数必须为 0） |
+//!
+//! 每个用例开头都调 [`clear_cache`]：缓存是进程级静态，用例之间不该互相借光（M251 复审 r1）。
+//!
+//! 抓不住：缩略图**画质**（盒式采样的观感只能靠出图看）；缓存淘汰策略的观感（`MAX_CACHE_ENTRIES`
+//! 只有一条「不会无限长」的结构性断言，没有逐条淘汰用例）。
+
+use std::path::{Path, PathBuf};
+
+use super::*;
+
+/// 一张真的 8×6 PNG（143 字节，RGBA，逐像素渐变）。
+///
+/// 内嵌字节而不是引素材文件：presenter 的 dev-dependencies 里没有图片编码器，而这条用例要的
+/// 正是「**真**解码器能读的真 PNG」——手写的 143 个字节比任何 mock 都硬。
+const PNG_8X6: &[u8] = &[
+    137, 80, 78, 71, 13, 10, 26, 10, 0, 0, 0, 13, 73, 72, 68, 82, 0, 0, 0, 8, 0, 0, 0, 6, 8, 6, 0,
+    0, 0, 254, 5, 223, 251, 0, 0, 0, 86, 73, 68, 65, 84, 120, 218, 21, 202, 33, 1, 195, 64, 12, 0,
+    192, 87, 50, 92, 17, 47, 162, 56, 74, 2, 171, 34, 184, 34, 34, 98, 56, 134, 182, 123, 112, 236,
+    214, 90, 207, 239, 195, 38, 72, 138, 102, 88, 235, 18, 216, 4, 73, 209, 204, 117, 194, 45, 176,
+    9, 146, 162, 153, 251, 132, 20, 216, 4, 73, 209, 76, 158, 240, 10, 108, 130, 164, 104, 230, 61,
+    225, 43, 176, 9, 146, 162, 25, 254, 48, 255, 110, 65, 247, 55, 89, 206, 0, 0, 0, 0, 73, 69, 78,
+    68, 174, 66, 96, 130,
+];
+
+/// 一次性临时目录（本 crate 不引第三方 tempfile）。
+struct TempDir(PathBuf);
+
+impl Drop for TempDir {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_dir_all(&self.0);
+    }
+}
+
+fn temp_dir(tag: &str) -> TempDir {
+    use std::sync::atomic::{AtomicU64, Ordering};
+    static COUNTER: AtomicU64 = AtomicU64::new(0);
+    let seq = COUNTER.fetch_add(1, Ordering::Relaxed);
+    let path = std::env::temp_dir().join(format!("ull-thumbs-{tag}-{}-{seq}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&path);
+    std::fs::create_dir_all(&path).expect("建临时目录");
+    TempDir(path)
+}
+
+/// 目录里放一张真 PNG，返回它的字节数。
+fn write_png(dir: &Path, file: &str) -> u64 {
+    let path = dir.join(file);
+    std::fs::write(&path, PNG_8X6).expect("写 PNG");
+    std::fs::metadata(&path).expect("读元数据").len()
+}
+
+/// 一张「快照里的截图」（`preview` 由被测代码填）。
+fn shot(file: &str, bytes: u64, modified_ms: Option) -> ScreenshotView {
+    ScreenshotView {
+        file: file.to_string(),
+        bytes,
+        modified_ms,
+        preview: ScreenshotPreview::NotGenerated,
+    }
+}
+
+/// **判据 ①**：真 PNG 出缩略图（像素 + 宽高 + 长度自洽）。
+///
+/// 抓得住：解码这条路断了（回 `NotGenerated`）、缩略图边长没按 `THUMBNAIL_MAX_EDGE` 走、
+/// `pixels` 长度与宽高对不上（壳层 `from_raw_rgba` 会画出花屏）。
+#[test]
+fn a_real_png_becomes_a_thumbnail() {
+    clear_cache();
+    let dir = temp_dir("ready");
+    let bytes = write_png(&dir.0, "2024-05-01_10.00.00.png");
+    let mut views = [shot(
+        "2024-05-01_10.00.00.png",
+        bytes,
+        Some(1_714_557_600_000),
+    )];
+    let calls = std::cell::Cell::new(0u32);
+    let mut counting = |path: &Path, size: u64| {
+        calls.set(calls.get() + 1);
+        decode(path, size)
+    };
+    attach_with(&dir.0, &mut views, &mut counting);
+
+    assert_eq!(calls.get(), 1, "一张新图应当正好进一次解码器");
+    let ready = views[0].preview.thumbnail().expect("真 PNG 应当出缩略图");
+    assert_eq!((ready.width, ready.height), (8, 6), "8×6 的图不放大");
+    assert!(ready.is_consistent(), "像素长度与宽高对不上");
+    assert_eq!(&ready.pixels[..4], &[0, 0, 128, 255], "左上角那一格的颜色");
+}
+
+/// **判据 ②**：坏文件给**结构化错误**（逐条可见），不 panic、不静默少一张。
+#[test]
+fn a_broken_file_is_a_visible_reason() {
+    clear_cache();
+    let dir = temp_dir("broken");
+    std::fs::write(dir.0.join("bad.png"), b"\x89PNG\r\n\x1a\n garbage").expect("写坏文件");
+    let bytes = std::fs::metadata(dir.0.join("bad.png"))
+        .expect("元数据")
+        .len();
+    let mut views = [shot("bad.png", bytes, Some(1))];
+    let calls = std::cell::Cell::new(0u32);
+    let mut counting = |path: &Path, size: u64| {
+        calls.set(calls.get() + 1);
+        decode(path, size)
+    };
+    attach_with(&dir.0, &mut views, &mut counting);
+
+    assert_eq!(calls.get(), 1, "坏文件也要真的试一次解码（不许提前判死）");
+    match &views[0].preview {
+        ScreenshotPreview::Failed(failure) => {
+            assert_eq!(failure.kind, ScreenshotThumbKind::Decode);
+            assert!(!failure.detail.is_empty(), "原因被吞掉了");
+        }
+        other => panic!("坏 PNG 应当给 Failed，实际 {other:?}"),
+    }
+}
+
+/// **判据 ③**：超过 8 MiB 的图**不进解码器**，且原因可见（T27 变异的目标）。
+///
+/// 抓得住：把上限改成「无上限」或把判断挪到解码之后（`calls` 会从 0 变成 1）。
+/// 抓不住：8 MiB 这个数字本身合不合理（那是 D54 定的产品取舍）。
+#[test]
+fn a_file_over_the_size_cap_never_reaches_the_decoder() {
+    clear_cache();
+    let dir = temp_dir("toolarge");
+    let file = "huge.png";
+    std::fs::write(dir.0.join(file), vec![0u8; MAX_SOURCE_BYTES as usize + 1]).expect("写大文件");
+    let mut views = [shot(file, MAX_SOURCE_BYTES + 1, Some(1))];
+    let calls = std::cell::Cell::new(0u32);
+    let mut counting = |path: &Path, size: u64| {
+        calls.set(calls.get() + 1);
+        decode(path, size)
+    };
+    attach_with(&dir.0, &mut views, &mut counting);
+
+    assert_eq!(calls.get(), 0, "超过 8 MiB 的图一个字节都不该进解码器");
+    match &views[0].preview {
+        ScreenshotPreview::Failed(failure) => {
+            assert_eq!(failure.kind, ScreenshotThumbKind::TooLarge);
+            assert!(
+                failure.detail.contains(&MAX_SOURCE_BYTES.to_string()),
+                "括号里要带上限，实际 {}",
+                failure.detail
+            );
+        }
+        other => panic!("超限的图应当给 Failed(TooLarge)，实际 {other:?}"),
+    }
+}
+
+/// **判据 ④**：第 61 张不解码（按 mtime 倒序）。
+///
+/// 抓得住：上限被去掉（`calls` 会变 61）、排序反了（最早的那张反而被解、最新的给占位）、
+/// 占位被画成失败（`NotGenerated` 与 `Failed` 是两种状态：一个是「没轮到」，一个是「试过但不行」）。
+#[test]
+fn the_sixty_first_screenshot_is_not_decoded() {
+    clear_cache();
+    let dir = temp_dir("cap");
+    let mut views: Vec = (0..MAX_PER_REFRESH + 1)
+        .map(|index| {
+            let file = format!("2024-05-01_10.00.{index:02}.png");
+            let bytes = write_png(&dir.0, &file);
+            // index 越小越新：排序之后 index 0 应当是 rank 0。
+            shot(&file, bytes, Some(1_714_557_600_000 - index as u64))
+        })
+        .collect();
+    let calls = std::cell::Cell::new(0u32);
+    let mut counting = |path: &Path, size: u64| {
+        calls.set(calls.get() + 1);
+        decode(path, size)
+    };
+    attach_with(&dir.0, &mut views, &mut counting);
+
+    assert_eq!(
+        calls.get(),
+        MAX_PER_REFRESH as u32,
+        "只该解前 {MAX_PER_REFRESH} 张"
+    );
+    assert!(
+        views[..MAX_PER_REFRESH]
+            .iter()
+            .all(|view| view.preview.thumbnail().is_some()),
+        "最新的 {MAX_PER_REFRESH} 张都该有缩略图"
+    );
+    assert_eq!(
+        views[MAX_PER_REFRESH].preview,
+        ScreenshotPreview::NotGenerated,
+        "第 61 张应当是「未生成预览」占位"
+    );
+}
+
+/// **判据 ⑤**：缓存命中不重复解码（同一 (路径, mtime, 大小) 第二次不进解码器）。
+///
+/// 抓得住：缓存根本没接上（`calls` 变 2）、键里多加了会让命中失效的东西（例如把「本次调用
+/// 序号」混进键）。
+#[test]
+fn the_second_identical_refresh_does_not_redecode() {
+    clear_cache();
+    let dir = temp_dir("hit");
+    let bytes = write_png(&dir.0, "2024-05-01_10.00.00.png");
+    let calls = std::cell::Cell::new(0u32);
+    let mut counting = |path: &Path, size: u64| {
+        calls.set(calls.get() + 1);
+        decode(path, size)
+    };
+    let mut first = [shot("2024-05-01_10.00.00.png", bytes, Some(7))];
+    attach_with(&dir.0, &mut first, &mut counting);
+    let mut second = [shot("2024-05-01_10.00.00.png", bytes, Some(7))];
+    attach_with(&dir.0, &mut second, &mut counting);
+
+    assert_eq!(calls.get(), 1, "第二次刷新不许再进解码器");
+    assert_eq!(first[0].preview, second[0].preview, "两拍的缩略图必须一致");
+}
+
+/// **判据 ⑥（T27 的第一条变异靶子）**：文件被覆盖（mtime 变了）必须重解。
+///
+/// 这是「截图被覆盖后仍显示旧缩略图」那个 bug 的唯一自动化抓手：把 mtime 从缓存键里去掉，
+/// 本用例立刻红（`calls` 停在 1）。大小故意保持不变——只改 mtime，才能把「大小也在键里」这条
+/// 排除掉。
+#[test]
+fn a_changed_file_is_decoded_again() {
+    clear_cache();
+    let dir = temp_dir("mtime");
+    let bytes = write_png(&dir.0, "2024-05-01_10.00.00.png");
+    let calls = std::cell::Cell::new(0u32);
+    let mut counting = |path: &Path, size: u64| {
+        calls.set(calls.get() + 1);
+        decode(path, size)
+    };
+    let mut first = [shot("2024-05-01_10.00.00.png", bytes, Some(1_000))];
+    attach_with(&dir.0, &mut first, &mut counting);
+    assert_eq!(calls.get(), 1);
+    // 同名文件被覆盖：**只有 mtime 变了**（大小相同）。
+    let mut second = [shot("2024-05-01_10.00.00.png", bytes, Some(2_000))];
+    attach_with(&dir.0, &mut second, &mut counting);
+    assert_eq!(calls.get(), 2, "mtime 变了就是另一张图，必须重解");
+}
+
+/// **判据 ⑦**：同名同刻但**大小变了**（例如用户替换了文件并保了 mtime）也必须重解。
+///
+/// 抓得住：缓存键只剩路径（`calls` 停在 1）。与用例 ⑥ 一起把三段键的两段独立钉住。
+#[test]
+fn a_changed_size_is_decoded_again() {
+    clear_cache();
+    let dir = temp_dir("size");
+    let bytes = write_png(&dir.0, "2024-05-01_10.00.00.png");
+    let calls = std::cell::Cell::new(0u32);
+    let mut counting = |path: &Path, size: u64| {
+        calls.set(calls.get() + 1);
+        decode(path, size)
+    };
+    let mut first = [shot("2024-05-01_10.00.00.png", bytes, Some(5))];
+    attach_with(&dir.0, &mut first, &mut counting);
+    let mut second = [shot("2024-05-01_10.00.00.png", bytes + 1, Some(5))];
+    attach_with(&dir.0, &mut second, &mut counting);
+    assert_eq!(calls.get(), 2, "大小变了必须重解");
+}
+
+/// 空快照不碰缓存、不 panic（新实例的常态）。
+#[test]
+fn an_empty_list_is_a_no_op() {
+    clear_cache();
+    let dir = temp_dir("empty");
+    let mut views: Vec = Vec::new();
+    let calls = std::cell::Cell::new(0u32);
+    let mut counting = |path: &Path, size: u64| {
+        calls.set(calls.get() + 1);
+        decode(path, size)
+    };
+    attach_with(&dir.0, &mut views, &mut counting);
+    assert_eq!(calls.get(), 0);
+}
+
+/// 缓存有界：**策略函数单独测**（不往全局缓存里灌 240 条——那会把并行用例的键清掉）。
+///
+/// 抓得住：淘汰那段被删掉（250 条 → 还是 250 条）；
+/// 抓不住：淘汰顺序（这里只留「本拍碰到的」，没有 LRU 语义，也不该有）。
+#[test]
+fn the_cache_stays_bounded() {
+    let mut store: Cache = HashMap::new();
+    let touched: Key = ("/x/keep.png".to_string(), Some(1), 10);
+    for round in 0..(MAX_CACHE_ENTRIES + 10) {
+        store.insert(
+            (format!("/x/{round}.png"), Some(round as u64), 10),
+            Ok(sample()),
+        );
+    }
+    store.insert(touched.clone(), Ok(sample()));
+    assert!(store.len() > MAX_CACHE_ENTRIES);
+
+    prune(&mut store, std::slice::from_ref(&touched));
+    assert_eq!(
+        store.len(),
+        1,
+        "超上限之后只该留这一拍碰到的键（实际 {}）",
+        store.len()
+    );
+    assert!(store.contains_key(&touched), "本拍碰到的键被自己清了");
+
+    // 没超上限时一条都不许掉。
+    let mut small: Cache = HashMap::new();
+    small.insert(touched.clone(), Ok(sample()));
+    prune(&mut small, std::slice::from_ref(&touched));
+    assert_eq!(small.len(), 1);
+}
+
+/// 一张可复用的小缩略图（`tests` 里只用来占位，不看内容）。
+fn sample() -> ThumbnailView {
+    ThumbnailView {
+        width: 1,
+        height: 1,
+        pixels: vec![0, 0, 0, 255],
+    }
+}
diff --git a/crates/presenter/src/host/saves/write.rs b/crates/presenter/src/host/saves/write.rs
new file mode 100644
index 0000000..fac574d
--- /dev/null
+++ b/crates/presenter/src/host/saves/write.rs
@@ -0,0 +1,167 @@
+//! 三个**写操作**的宿主实现（M247）：重命名 / 删除 / 备份导出。
+//!
+//! 从 `host/saves.rs` 拆出（那个文件加完在飞闸门与写失败映射之后越过 400 行硬线）。
+//! 判据与读路径共用的部分留在父模块（[`super::target`] / [`super::run_dir`] / [`super::snapshot`] /
+//! [`super::failure`]）——**派生运行目录只有一条路**，写路径不另算一份。
+//!
+//! | 函数 | 干什么 |
+//! |---|---|
+//! | [`spawn_rename`] / [`spawn_delete`] / [`spawn_backup`] | 起后台线程跑完再把**新快照 + 回执**送回去 |
+//! | `rename` / `delete` / `backup` | 前台实现（测试直接调它们，不必绕线程） |
+//! | [`export_dir`] | 备份的默认落点 `/exports/saves/` |
+//! | [`write_failure`] | core 的八类写失败 → DTO 的八类（一一对应，不折叠） |
+//!
+//! 三个 `spawn_*` 都**先跑 core 的写**再 `snapshot`：界面画的永远是磁盘上的真相，
+//! 回执只说这件事动的是哪一条（见父模块的「三个写操作的回程形状」）。
+
+use std::path::PathBuf;
+
+use unlucky_core::game::saves::{self, SavesWriteError, SavesWriteKind};
+
+use crate::dto::{
+    InstanceId, SavesFailureKind, SavesFailureOp, SavesFailureView, SavesListView, SavesOped,
+};
+
+use super::super::env::HostEnv;
+use super::super::job::{spawn, JobSender};
+use super::{failure, snapshot, target, Report};
+
+/// 后台重命名一个世界，**并把刷新后的快照与回执一起带回来**。
+pub fn spawn_rename(env: HostEnv, tx: JobSender, id: InstanceId, dir: String, to: String) {
+    spawn("saves-rename", move || {
+        let report = Report {
+            instance: id.clone(),
+            list: rename(&env, &id, &dir, &to),
+        };
+        let _ = tx.send(crate::host::HostTask::Saves(Box::new(report)));
+    });
+}
+
+/// 后台删除一个世界（**UI 已经二次确认过**；host 侧照样重新过边界校验）。
+pub fn spawn_delete(env: HostEnv, tx: JobSender, id: InstanceId, dir: String) {
+    spawn("saves-delete", move || {
+        let report = Report {
+            instance: id.clone(),
+            list: delete(&env, &id, &dir),
+        };
+        let _ = tx.send(crate::host::HostTask::Saves(Box::new(report)));
+    });
+}
+
+/// 后台把一个世界备份成 zip（落点见 [`export_dir`]），并带回新快照。
+pub fn spawn_backup(
+    env: HostEnv,
+    tx: JobSender,
+    id: InstanceId,
+    dir: String,
+    dest: Option,
+) {
+    spawn("saves-backup", move || {
+        let report = Report {
+            instance: id.clone(),
+            list: backup(&env, &id, &dir, dest.as_deref()),
+        };
+        let _ = tx.send(crate::host::HostTask::Saves(Box::new(report)));
+    });
+}
+
+/// 重命名 → 再列一遍（回执里记「谁改成了什么」）。
+pub(super) fn rename(
+    env: &HostEnv,
+    id: &str,
+    from: &str,
+    to: &str,
+) -> Result {
+    let (instance, run_dir) = target(env, id)?;
+    saves::rename_world(&run_dir, from, to)
+        .map_err(|error| write_failure(&instance.id, SavesFailureOp::Rename, from, &error))?;
+    snapshot(
+        &instance,
+        &run_dir,
+        Some(SavesOped::Renamed {
+            from: from.to_string(),
+            to: to.to_string(),
+        }),
+    )
+}
+
+/// 删除 → 再列一遍（回执里记被删掉的那个名字）。
+pub(super) fn delete(
+    env: &HostEnv,
+    id: &str,
+    dir: &str,
+) -> Result {
+    let (instance, run_dir) = target(env, id)?;
+    saves::delete_world(&run_dir, dir)
+        .map_err(|error| write_failure(&instance.id, SavesFailureOp::Delete, dir, &error))?;
+    snapshot(
+        &instance,
+        &run_dir,
+        Some(SavesOped::Deleted {
+            dir: dir.to_string(),
+        }),
+    )
+}
+
+/// 备份 → 再列一遍（回执里记落点路径 / 字节数 / 被跳过的链接数）。
+pub(super) fn backup(
+    env: &HostEnv,
+    id: &str,
+    dir: &str,
+    dest: Option<&str>,
+) -> Result {
+    let (instance, run_dir) = target(env, id)?;
+    let dest = dest.map_or_else(|| export_dir(env), PathBuf::from);
+    let done = saves::backup_world(&run_dir, dir, &dest)
+        .map_err(|error| write_failure(&instance.id, SavesFailureOp::Backup, dir, &error))?;
+    let file = done
+        .path
+        .file_name()
+        .map(|name| name.to_string_lossy().into_owned())
+        .unwrap_or_default();
+    snapshot(
+        &instance,
+        &run_dir,
+        Some(SavesOped::BackedUp {
+            dir: dir.to_string(),
+            file,
+            path: done.path.display().to_string(),
+            bytes: done.bytes,
+            skipped: done.skipped,
+        }),
+    )
+}
+
+/// 备份的默认落点：`/exports/saves/`（见模块文档「备份落点」一节）。
+fn export_dir(env: &HostEnv) -> PathBuf {
+    env.layout.data().join("exports").join("saves")
+}
+
+/// core 的写失败 → 具名类别 + 「路径：原文」（**不翻译**，翻译在 app 层）。
+///
+/// 八个类别一一对应，没有一个落到「未知」兜底里：兜底会变成静默（用户只看到"失败了"）。
+pub(super) fn write_failure(
+    instance: &str,
+    op: SavesFailureOp,
+    file: &str,
+    error: &SavesWriteError,
+) -> SavesFailureView {
+    let kind = match error.kind {
+        SavesWriteKind::UnsafeName => SavesFailureKind::WriteUnsafeName,
+        SavesWriteKind::SymbolicLink => SavesFailureKind::WriteSymlink,
+        SavesWriteKind::NotFound => SavesFailureKind::WriteMissing,
+        SavesWriteKind::NotADirectory => SavesFailureKind::WriteNotADirectory,
+        SavesWriteKind::Conflict => SavesFailureKind::WriteConflict,
+        SavesWriteKind::Boundary => SavesFailureKind::WriteBoundary,
+        SavesWriteKind::TooLarge => SavesFailureKind::WriteTooLarge,
+        SavesWriteKind::Io => SavesFailureKind::WriteFailed,
+    };
+    let mut failure = failure(
+        instance,
+        kind,
+        format!("{}：{}", error.path.display(), error.detail),
+    );
+    failure.file = file.to_string();
+    failure.op = Some(op);
+    failure
+}
diff --git a/crates/presenter/src/host/settings.rs b/crates/presenter/src/host/settings.rs
new file mode 100644
index 0000000..2c0f528
--- /dev/null
+++ b/crates/presenter/src/host/settings.rs
@@ -0,0 +1,400 @@
+//! 设置页分组：按 `core::setting` schema 的键生成行，写回走 `SettingStore::set`。
+//!
+//! 三件纪律（AGENTS §6）：① 读写同一份 `<数据根>/config/launcher.json`（与 `ull config set` /
+//! AI `set_config` 同源）；② 不自己拼 JSON、不绕 schema（非法键/越界值由 `store.set` 拒绝）；
+//! ③ 这里只认「键名 + 字符串值」，领域语义留在 core。
+//!
+//! 分组 id 与设置页子导航同名：`download` / `java` / `data` / `ai` / `mcp`。
+
+use std::path::{Path, PathBuf};
+
+use serde_json::Value;
+use unlucky_core::setting::keys::launcher_schema;
+use unlucky_core::setting::spec::ValueKind;
+use unlucky_core::setting::store::SettingStore;
+
+use crate::dto::{SettingGroupView, SettingRowView};
+
+use super::env::HostEnv;
+
+// M193：下载组的行与「设置 → 引擎调优」的翻译搬进子模块（`settings.rs` 顶在 400 行硬线上，
+// 理由与 `settings_tests.rs` 同源，见那个文件的文件头）。
+pub(crate) mod download;
+
+/// 全部设置分组（设置页右栏一次拿全，切分组不再请求）。
+pub fn groups(env: &HostEnv) -> Vec {
+    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)
+}
+
+/// 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 = 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::>()
+                .join(" · "),
+        ))
+}
+
+/// 数据目录（D6 三模式）。**M216 ①**：`core.data_custom_root` 读**写回的那份**（便携配置），否则
+/// 改完自定义根页面读「解析后」那份、输入凭空消失；`core.data_mode` 仍显示生效模式。
+fn data_group(env: &HostEnv) -> SettingGroupView {
+    data_group_at(env, exe_dir().as_deref())
+}
+
+/// [`data_group`] 的参数化入口（`exe_dir` 决定自定义根那行读哪份配置；单测注入用）。
+fn data_group_at(env: &HostEnv, exe_dir: Option<&Path>) -> SettingGroupView {
+    let modes = ["portable", "standard", "custom"];
+    let mode = env.mode().as_str().to_string();
+    let custom_root = exe_dir
+        .map(super::env::request_from_portable)
+        .and_then(|request| request.custom_root)
+        .map(|path| path.display().to_string())
+        .unwrap_or_default();
+    SettingGroupView::new("data", "数据目录（D6 三模式）")
+        .with(SettingRowView::choice(
+            "core.data_mode",
+            "存储模式",
+            "便携（运行目录）/ 标准（系统应用数据目录）/ 自定义",
+            &modes,
+            selected(&modes, &mode),
+        ))
+        .with(SettingRowView::text(
+            "core.data_custom_root",
+            "自定义根目录",
+            "custom 模式生效（绝对路径）",
+            &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。
+/// **选项表直接取 schema 的 `AI_PROVIDERS`**（M174）：原先手写三项、漏了 `disabled`，于是被别的
+/// 写者设成 `disabled` 的机器在这一页会显示成 `openai_compatible`（`selected()` 找不到就回 0）。
+/// **密钥只显示状态不显示值**：`ai.api_key` 是 `locked` 凭据，进 DTO 就等于进事件流/日志。
+fn ai_group(env: &HostEnv) -> SettingGroupView {
+    let providers = unlucky_core::setting::keys::AI_PROVIDERS;
+    let provider = text(env, "ai.provider");
+    let chosen = if provider.is_empty() {
+        "openai_compatible"
+    } else {
+        provider.as_str()
+    };
+    let key_state = match text(env, "ai.api_key").trim().chars().count() {
+        0 => "未配置（在 iced 设置页填写）".to_string(),
+        chars => format!("已配置（{chars} 个字符）"),
+    };
+    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, chosen),
+        ))
+        .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::read_only("API 密钥", &key_state))
+        .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> {
+    set_at(env, exe_dir().as_deref(), key, value)
+}
+
+/// [`set`] 的参数化入口（`exe_dir` 决定数据根四键写哪份；单测注入假 exe 目录）。**M216 ①**：
+/// 老实现写 `env.store()`（解析后那份），而启动只读便携那份 ⇒ 改「存储模式」下次启动看不见。
+fn set_at(env: &HostEnv, exe_dir: Option<&Path>, key: &str, value: &str) -> Result<(), String> {
+    if key == super::engine::DETECT_REGION_ACTION {
+        return detect_region(env);
+    }
+    // M204：Java 组的「写回完成，重发快照」动作键。**不写盘**——页面那一侧已把三键一次原子写进
+    // `launcher.json`（`pages/settings/java/store.rs::save`），这里返回 `Ok(())` 就能让
+    // `dispatch.rs` 重发 `SettingsChanged`。键的取舍见 `crate::dto::JAVA_REFRESH_ACTION`。
+    if key == crate::dto::JAVA_REFRESH_ACTION {
+        return Ok(());
+    }
+    let parsed = parse_value(key, value)?;
+    let path = crate::settings_bridge::setting_path(&env.launcher_config(), exe_dir, key);
+    let mut store = SettingStore::load(&path, launcher_schema());
+    store
+        .set(key, parsed)
+        .map_err(|error| format!("设置 {key} 失败：{error}"))?;
+    store
+        .save()
+        .map_err(|error| format!("保存设置失败：{error}"))?;
+    Ok(())
+}
+
+/// 本进程的 exe 目录（拿不到就退回 `None`：落在解析后那份，见 `setting_path`）。
+fn exe_dir() -> Option {
+    let exe = std::env::current_exe().ok()?;
+    exe.parent().map(Path::to_path_buf)
+}
+
+/// 键 → 正确类型的 JSON 值（schema 会再校验范围/枚举）。
+///
+/// **按 schema 的 `ValueKind` 取类型，不硬编码键名**（复审 P1-1）：硬编码会让 Float 键被当 String
+/// 送进 `store.set` ⇒ `InvalidValue` ⇒ `save()` 不执行。守门：`every_float_key_in_the_schema_can_be_written_back`。
+fn parse_value(key: &str, value: &str) -> Result {
+    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::()
+            .map(Value::from)
+            .map_err(|_| format!("{key} 需要整数：{value}")),
+        ValueKind::Float { .. } => match trimmed.parse::() {
+            Ok(number) if number.is_finite() => Ok(Value::from(number)),
+            _ => Err(format!("{key} 需要有限数字：{value}")),
+        },
+        // 文本 / 枚举 / 路径 / 列表 / 任意 JSON：字符串原样交下去（越界与词表由 schema 判）。
+        _ => Ok(Value::String(value.to_string())),
+    }
+}
+
+/// 清掉 24h 地区缓存并让共享引擎失效（下次请求重新判定；自更新那份由 `dispatch` 重建 Factory）。
+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}"))?;
+    }
+    super::engine::forget(env);
+    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}"))?;
+    Ok(())
+}
+
+/// **M216 ① 的回合用例**（不并进 `settings_tests.rs`：那是另一个文件，不在本条的文字范围里）。
+#[cfg(test)]
+mod data_mode_tests {
+    use unlucky_core::platform::data_dir::{DataMode, ResolvedData};
+
+    use super::*;
+
+    /// 写回与启动解析同源：切到 standard 再切回 portable，**两次都真的生效**；页面显示同源。
+    /// 抓得住：四键的落点（写进「解析后」那份 ⇒ 启动读到旧值 ⇒ 红）、不写副本、其余键不改道。
+    /// 抓不住：真实 `current_exe()`、`redirect.json` 跟随、GUI 派发。
+    #[test]
+    fn data_mode_written_back_is_the_one_the_next_start_reads() {
+        let root = std::env::temp_dir().join(format!("ull216-{}-{}", std::process::id(), line!()));
+        let exe_dir = root.join("exe");
+        std::fs::create_dir_all(exe_dir.join(".ULL/config")).expect("建目录");
+        let portable = crate::host::env::portable_config_path(&exe_dir);
+        std::fs::write(&portable, r#"{"core":{"data_mode":"portable"}}"#).expect("写便携配置");
+        // 「以为自己在 Standard 模式」：解析后的数据根在别处。
+        let running = HostEnv::from_data(ResolvedData {
+            mode: DataMode::Standard,
+            launcher_home: root.join("appdata/ULL"),
+            game_home: root.join("appdata/.minecraft"),
+            redirected_from: None,
+        });
+        let write = |mode: &str| set_at(&running, Some(&exe_dir), "core.data_mode", mode);
+        let write_key = |key: &str, value: &str| set_at(&running, Some(&exe_dir), key, value);
+        let at_startup = || crate::host::env::request_from_portable(&exe_dir).mode;
+        assert_eq!(at_startup(), DataMode::Portable, "起点");
+        assert_eq!(write("standard"), Ok(()));
+        assert_eq!(at_startup(), DataMode::Standard, "切出后启动读得到");
+        assert_eq!(write("portable"), Ok(()));
+        assert_eq!(at_startup(), DataMode::Portable, "切回也一样");
+        assert!(!running.launcher_config().is_file(), "四键不写副本");
+        assert_eq!(write_key("java.default_memory_mb", "4096"), Ok(()));
+        let text = std::fs::read_to_string(running.launcher_config()).expect("读配置");
+        assert!(text.contains("4096"), "非数据根键仍落解析后那份：{text}");
+
+        let shared = root.join("shared").display().to_string();
+        assert_eq!(write_key("core.data_custom_root", &shared), Ok(()));
+        let group = data_group_at(&running, Some(&exe_dir));
+        let row = group.rows.iter().find(|r| r.key == "core.data_custom_root");
+        assert_eq!(row.expect("有这一行").value_text, shared, "显示同源");
+        std::fs::remove_dir_all(&root).ok();
+    }
+}
+
+#[cfg(test)]
+#[path = "settings_tests.rs"]
+mod tests;
diff --git a/crates/presenter/src/host/settings/download.rs b/crates/presenter/src/host/settings/download.rs
new file mode 100644
index 0000000..41977ee
--- /dev/null
+++ b/crates/presenter/src/host/settings/download.rs
@@ -0,0 +1,269 @@
+//! 设置页「下载」分组 + 下载调优的**宿主侧翻译**（M193）。
+//!
+//! ## 为什么单开一个文件
+//!
+//! 同 `host/settings_tests.rs` 的理由：`host/settings.rs` 正好顶在 400 行硬线上，而本轮要往这一组加
+//! 「`download.gh_proxy` 三态行 + 并发硬上限说明 + 调优翻译」约 24 行。不拆就得砍 `settings.rs` 里
+//! 那些**留着防复发**的论证注释（`ai_group` 的 M174 回归说明、`parse_value` 的 P1-1 浮点键事故）
+//! ——那比多一个文件糟得多。搬出来还有一个附带好处：这一组是**唯一**要往 core 灌下载调优的一组，
+//! 代码与它的守卫（`settings_tests.rs`）现在挨在一起。
+//!
+//! ## 谁在读 / 谁在写
+//!
+//! ```text
+//! config/launcher.json   ←── store.set（`settings::set`，本模块只读）
+//!   download.concurrency ─┐
+//!   download.retry_limit ─┼─→ DownloadTuning（core 决定默认值与夹取）─→ shared::set_tuning
+//!   download.gh_proxy ───┘                                             （引擎重建时生效）
+//! ```
+//!
+//! **调优的同步点是显式的**：`host/engine.rs` 每次取引擎前、`dispatch.rs` 的 `SetSetting` 分支里，
+//! 都调 [`apply_tuning`]（幂等：值没变就什么都不做）。它**不是**藏在某个读函数里的副作用——
+//! 「读起来是纯读、实际改全局状态」正是本仓吃过亏的那类形状。
+
+use unlucky_core::download::config::{
+    DownloadTuning, GhProxyOverride, DEFAULT_MAX_ATTEMPTS_PER_SOURCE, DEFAULT_MAX_CONCURRENCY,
+    MAX_CONCURRENCY,
+};
+use unlucky_core::download::shared;
+
+use crate::dto::{SettingGroupView, SettingRowView};
+
+use super::super::env::HostEnv;
+use super::{selected, text};
+
+/// 并发数的推荐档位（`selected()` 找不到时回 0；手改出来的非档位值会被插进选项表，见 [`group`]）。
+const CONCURRENCY_LADDER: [&str; 5] = ["4", "8", "16", "32", "64"];
+/// 单源尝试次数的推荐档位（`0` 是旧版 GUI 提供过的档位，语义 = 只试一次，见 schema 描述）。
+const RETRY_LADDER: [&str; 6] = ["0", "1", "2", "3", "5", "10"];
+
+/// 下载（D7）：并发/重试/地区/镜像偏好/代理/GitHub 加速前缀。
+///
+/// ## P3-5：这两行显示的是**引擎生效值**，不是文件原值
+///
+/// `download.concurrency` / `download.retry_limit` 的生效判定在 core（[`DownloadTuning`]）：
+/// 越界、负数、手改坏值一律**回落出厂值**（不夹到边界——「想 9999 给 64」仍然是界面说谎）。
+/// 所以这一组必须画 [`tuning_of`] 的结论；文件里的原值只在**两者不一致**时作为一句解释出现
+/// （「原值 9999 已按出厂 8 生效」）。判定的两个输入都是**现读**的：文件原值取自
+/// `doc().get(..)`（显式写过的值），生效值取自 core 的翻译层 —— 没有一个数字来自常量或参数。
+pub(super) fn group(env: &HostEnv) -> SettingGroupView {
+    let tuning = tuning_of(env);
+    let concurrency = (tuning.max_concurrency as i64).to_string();
+    let retry = i64::from(tuning.max_attempts_per_source).to_string();
+    let concurrency_note = applied_note(
+        raw_text(env, unlucky_core::download::config::KEY_CONCURRENCY),
+        tuning.max_concurrency as i64,
+        DEFAULT_MAX_CONCURRENCY as i64,
+    );
+    let retry_note = applied_note(
+        raw_text(env, unlucky_core::download::config::KEY_RETRY_LIMIT),
+        i64::from(tuning.max_attempts_per_source),
+        i64::from(DEFAULT_MAX_ATTEMPTS_PER_SOURCE),
+    );
+    let concurrency_options = ladder(&CONCURRENCY_LADDER, &concurrency);
+    let retry_options = ladder(&RETRY_LADDER, &retry);
+    let concurrency_options: Vec<&str> = concurrency_options.iter().map(String::as_str).collect();
+    let retry_options: Vec<&str> = retry_options.iter().map(String::as_str).collect();
+    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(
+            unlucky_core::download::config::KEY_CONCURRENCY,
+            "并发数",
+            &with_note(
+                format!(
+                    "同时下载的文件数：出厂 {DEFAULT_MAX_CONCURRENCY}，可调 1~{MAX_CONCURRENCY}（引擎硬上限，防止填 9999 把机器拖死）；越界或手改坏值按出厂值生效"
+                ),
+                concurrency_note.as_deref(),
+            ),
+            &concurrency_options,
+            selected(&concurrency_options, &concurrency),
+        ))
+        .with(SettingRowView::choice(
+            unlucky_core::download::config::KEY_RETRY_LIMIT,
+            "单源尝试次数",
+            &with_note(
+                format!(
+                    "同一个源最多试几次（含首次；出厂 {DEFAULT_MAX_ATTEMPTS_PER_SOURCE}）。0 与 1 都等于「只试一次、不重试」——0 是旧版提供的档位，不代表「不下载」。换源不受此限"
+                ),
+                retry_note.as_deref(),
+            ),
+            &retry_options,
+            selected(&retry_options, &retry),
+        ))
+        .with(SettingRowView::choice(
+            "download.region",
+            "地区判定",
+            "auto = 时区+语言+探测；决定是否优先国内镜像",
+            ®ions,
+            selected(
+                ®ions,
+                if region_value.is_empty() {
+                    "auto"
+                } else {
+                    ®ion_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"),
+        ))
+        // M193：gh-proxy 三态。**留空与 off 是两件事**，描述里必须都写出来——用户最容易把
+        // 「我还没决定」当成「我不要加速」，于是以为自己关掉了、实际还在套前缀。
+        //
+        // P3-5：末尾那半句是**引擎生效档位**（`tuning.gh_proxy` 的翻译结论），不是文件原文。
+        .with(SettingRowView::text(
+            unlucky_core::download::config::KEY_GH_PROXY,
+            "GitHub 加速前缀（gh-proxy）",
+            &format!(
+                "留空 = 跟随内置默认（镜像优先/国内判定时自动套 gh-proxy.com）；填 off = 关闭（不生成任何 gh-proxy 候选）；填一个 URL 前缀 = 覆盖它；当前生效：{}",
+                gh_proxy_state(&tuning.gh_proxy)
+            ),
+            &text(env, unlucky_core::download::config::KEY_GH_PROXY),
+        ))
+        .with(SettingRowView::action(
+            super::super::engine::DETECT_REGION_ACTION,
+            "重新检测地区",
+            "清掉 24h 地区缓存，下次下载重新判定",
+            "detect_region",
+        ))
+}
+
+/// 推荐档位 + 「当前值不在档位里就把它插进去」（否则这一行会把 2 显示成 4 —— 又一个假值）。
+fn ladder(ladder: &[&str], current: &str) -> Vec {
+    let mut options: Vec = ladder.iter().map(|item| (*item).to_string()).collect();
+    if !current.is_empty() && !options.iter().any(|option| option == current) {
+        options.push(current.to_string());
+        options.sort_by_key(|option| option.parse::().unwrap_or(i64::MAX));
+    }
+    options
+}
+
+/// 文件里**显式写过**的原值，转成**上屏文本**（`None` = 文件没写这个键）。
+///
+/// 与 `super::int` 的区别：那个走 `effective()`（文件值 → schema 默认值），本函数只问文件本身。
+/// 「原值 X 已按出厂 N 生效」这句话的两个数必须现读（一个来自文件、一个来自 core 的翻译层），
+/// **不许**拿常量或请求参数冒充——那是 U1 明令禁止的假证据。
+///
+/// ## 为什么返回字符串而不是 `i64`（r1 代码复审 p2）
+///
+/// 手改文件可以把一个整数键写成 `"auto"` / `8.5` / `true`：`document::load` 对坏值只记
+/// `LoadProblem`、原样留在 `values` 里，所以 `doc().get(key)` 真的能拿到 `Some(String("auto"))`。
+/// 早先这里用 `Value::as_i64`，非整数一律 `None` ⇒ 行上画着生效值 8，却**不告诉用户他写的
+/// `auto` 被忽略了**——「设置项说假话」的最后一个洞。改成上屏文本后，越界整数（`9999` / `-4`）、
+/// 非整数 JSON（`8.5`）、别的类型（`true`）、字符串（`auto`）**都能进那句提示**；
+/// 数字 `to_string()` 出来仍是 `9999`，所以旧断言与旧措辞一字未变。
+fn raw_text(env: &HostEnv, key: &str) -> Option {
+    use serde_json::Value;
+    let store = env.store();
+    match store.doc().get(key)? {
+        // `null` 等于「没写」：`effective()` 也是这么当的（`filter(|value| !value.is_null())`）。
+        Value::Null => None,
+        // 字符串照原文上屏（不要 serde 的引号）：用户写的是 `auto`，提示里就该是 `auto`。
+        Value::String(text) => Some(text.clone()),
+        other => Some(other.to_string()),
+    }
+}
+
+/// 文件原值 ≠ 生效值时的说明；`None` = 没什么可说的（没写过，或写的就是生效值）。
+///
+/// `raw` 是**上屏文本**（见 [`raw_text`]），`effective` / `factory` 是 core 翻译层的结论。
+fn applied_note(raw: Option, effective: i64, factory: i64) -> Option {
+    let raw = raw?;
+    // 比的是「上屏文本」：文件写 `8`、生效也是 8 ⇒ 没什么可说的（`8.0` 会照实提示，因为那是一次
+    // 类型不一致的坏值）。
+    if raw == effective.to_string() {
+        return None;
+    }
+    Some(if effective == factory {
+        format!("原值 {raw} 已按出厂 {factory} 生效")
+    } else {
+        format!("原值 {raw} 已按 {effective} 生效")
+    })
+}
+
+/// 说明 +（有差异时）那一句「原值 … 生效」。
+///
+/// **那句结论独占一行（M201 r1 视觉复审 P2-2）**：原先用「；」接在说明末尾，于是在设置页 424 列的
+/// 表单宽里，越界那句的最后一个「效」被挤到第三行、单字成行（浅色 1180 / 深色 1180 / 窄窗 880
+/// 三张都是同一处孤字，x 396–407）。那句话恰好只在本 mission 的主场景（手改坏值/越界）出现，
+/// 让「用户最需要看懂的那一句」排得最难看。改法**不动排版**（换行由渲染器按 `\n` 分行），
+/// 只把结论从段落里挪出来——两个数（文件原值 / 生效值）与出厂/非出厂的两种措辞一个字都没丢。
+fn with_note(base: String, note: Option<&str>) -> String {
+    match note {
+        Some(note) => format!("{base}\n{note}"),
+        None => base,
+    }
+}
+
+/// gh-proxy 三态的上屏短句（与 [`GhProxyOverride`] 一一对应）。
+fn gh_proxy_state(state: &GhProxyOverride) -> String {
+    match state {
+        GhProxyOverride::Builtin => "跟随内置默认".to_string(),
+        GhProxyOverride::Off => "已关闭（off）".to_string(),
+        GhProxyOverride::Prefix(prefix) => format!("覆盖为 {prefix}"),
+    }
+}
+
+/// 从 `launcher.json` 读出下载调优（默认值与夹取口径在 core，本函数只做「取原始值」）。
+#[must_use]
+pub(crate) fn tuning_of(env: &HostEnv) -> DownloadTuning {
+    use unlucky_core::download::config::{KEY_CONCURRENCY, KEY_GH_PROXY, KEY_RETRY_LIMIT};
+    let store = env.store();
+    let doc = store.doc();
+    let gh = doc
+        .effective_str(KEY_GH_PROXY)
+        .map(str::to_string)
+        .unwrap_or_default();
+    DownloadTuning::from_settings(
+        doc.effective_i64(KEY_CONCURRENCY),
+        doc.effective_i64(KEY_RETRY_LIMIT),
+        Some(gh.as_str()),
+    )
+}
+
+/// 把当前设置灌进 core 的下载调优（按数据根），返回**是否真的变了**（变了就失效该根的引擎）。
+///
+/// 幂等：值没变时 `shared::set_tuning` 一行不动，所以「每次取引擎前都调」是安全的。
+pub(crate) fn apply_tuning(env: &HostEnv) -> bool {
+    shared::set_tuning(env.layout.cache(), tuning_of(env))
+}
+
+#[cfg(test)]
+#[path = "download_tests.rs"]
+mod tests;
diff --git a/crates/presenter/src/host/settings/download_tests.rs b/crates/presenter/src/host/settings/download_tests.rs
new file mode 100644
index 0000000..4f1dfe2
--- /dev/null
+++ b/crates/presenter/src/host/settings/download_tests.rs
@@ -0,0 +1,312 @@
+//! 下载设置组的「**生效值**」守门（P3-5 / P3-3）。
+//!
+//! 这一组画的是引擎真的会用的那个数，不是文件里那串字节。两者的判定在 core
+//! （`DownloadTuning::from_settings`：越界/坏值回落出厂，`0` 落成「只试一次」），这里守的是
+//! 「宿主把哪个数交给页面」以及「文件原值与生效值不一致时那句话有没有出现」。
+//!
+//! 构造真文件：手改坏值绕不过 `store.set` 的 schema 校验，所以测试**直接写 `launcher.json`**
+//! ——这正是用户手改文件的现场（`document::load` 对坏值只记 `LoadProblem`、原样保留）。
+
+use super::*;
+use crate::dto::find_row;
+use std::path::PathBuf;
+
+/// 一个装好「手写 `launcher.json`」的数据根。`json` 是整个文件的顶层对象。
+fn env_with(tag: &str, json: serde_json::Value) -> (PathBuf, HostEnv) {
+    let dir = std::env::temp_dir().join(format!("ull-download-group-{}-{tag}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    std::fs::create_dir_all(dir.join(".ULL/config")).expect("config 目录");
+    std::fs::write(
+        dir.join(".ULL/config/launcher.json"),
+        serde_json::to_string_pretty(&json).expect("序列化"),
+    )
+    .expect("写 launcher.json");
+    let env = HostEnv::at_root(&dir);
+    (dir, env)
+}
+
+/// 某一行（走页面同一条 `find_row`）。
+fn row<'a>(group: &'a SettingGroupView, key: &str) -> &'a SettingRowView {
+    find_row(std::slice::from_ref(group), key).unwrap_or_else(|| panic!("{key} 这一行不在组里"))
+}
+
+/// 选项表里被选中的那一项（页面正是按 `selected` 下标画选中的 chip）。
+fn chosen(row: &SettingRowView) -> &str {
+    row.options
+        .get(usize::try_from(row.selected).expect("下标非负"))
+        .map_or("<越界下标>", String::as_str)
+}
+
+/// **P3-5 主用例**：文件里是坏值 9999，行上画的是引擎真在用的 8，并把原值写明白。
+///
+/// 抓得住：① 宿主把文件值当生效值画（改回 `int(env, ..)`）⇒ 选中的 chip 变成 `9999`，红；
+/// ② 那句「原值 9999 已按出厂 8 生效」被删掉或写成常量 ⇒ 文案断言红；
+/// ③ core 的回落口径被改成「夹到边界 64」⇒ 选中项变成 64，红。
+/// 抓不住：界面上这行是否真的画出来（那是 `pages/settings/download.rs` 的 body 与截图的事），
+/// 也抓不住用户是否看得懂那句话。
+#[test]
+fn an_out_of_range_file_value_shows_the_engine_value_and_names_the_raw_one() {
+    let (dir, env) = env_with(
+        "concurrency",
+        serde_json::json!({ "download": { "concurrency": 9999 } }),
+    );
+
+    let group = group(&env);
+    let concurrency = row(&group, unlucky_core::download::config::KEY_CONCURRENCY);
+
+    assert_eq!(
+        group.id, "download",
+        "设置页按这个 id 找组（app-iced `pages/settings/download.rs` 的 GROUP_ID）；改名会静默退回演示行"
+    );
+    assert_eq!(
+        chosen(concurrency),
+        "8",
+        "行上画的必须是引擎生效值（出厂 8），不是文件里的 9999"
+    );
+    assert!(
+        concurrency
+            .description
+            .contains("原值 9999 已按出厂 8 生效"),
+        "文件值与生效值不一致时必须写明原值：{}",
+        concurrency.description
+    );
+    // r1 视觉复审 P2-2：那句结论必须**独占一行**（接在说明末尾时，最后一个「效」会被挤成孤字）。
+    assert!(
+        concurrency
+            .description
+            .ends_with("\n原值 9999 已按出厂 8 生效"),
+        "结论必须自成一行（`\\n` 分隔），否则 424 列的说明会把它折出单字孤行：{:?}",
+        concurrency.description
+    );
+    assert_eq!(
+        tuning_of(&env).max_concurrency,
+        8,
+        "同一份文件经 core 的翻译层也必须是 8（两处口径不许漂）"
+    );
+
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+/// 文件里写的就是生效值 ⇒ **不许**冒出「原值 …」那句话（否则它是常量而不是判决）。
+///
+/// 抓得住：`applied_note` 不管三七二十一都返回 `Some`（把那句话变成装饰）。
+/// 抓不住：句子出现的**位置**（埋在哪一段文案里）。
+#[test]
+fn a_file_value_that_matches_the_engine_value_gets_no_note() {
+    let (dir, env) = env_with(
+        "in-range",
+        serde_json::json!({ "download": { "concurrency": 2, "retry_limit": 5 } }),
+    );
+
+    let group = group(&env);
+    let concurrency = row(&group, unlucky_core::download::config::KEY_CONCURRENCY);
+    let retry = row(&group, unlucky_core::download::config::KEY_RETRY_LIMIT);
+
+    assert_eq!(chosen(concurrency), "2");
+    assert_eq!(chosen(retry), "5");
+    for row in [concurrency, retry] {
+        assert!(
+            !row.description.contains("原值"),
+            "没有差异就不该有那句话：{}",
+            row.description
+        );
+        // 没有结论行 ⇒ 说明里也不该有换行（那会让页面多出一行空白）。
+        assert!(
+            !row.description.contains('\n'),
+            "没有差异就不该有第二段：{:?}",
+            row.description
+        );
+    }
+
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+/// **每一种坏值形态都要说清原值**（r1 代码复审 p2：非整数坏值曾被静默丢掉）。
+///
+/// 任务书 P3-5 是无条件的「文件里的值与生效值不一致时，行上要写明原值 X 已按出厂 N 生效」，
+/// 而「手改坏值」不止越界整数这一种。四种形态各验一遍：
+///
+/// | 文件里写的 | 生效值 | 行上必须出现 |
+/// |---|---|---|
+/// | `9999`（越界整数） | 8 | `原值 9999 已按出厂 8 生效`（上面那条用例） |
+/// | `-4`（负整数） | 8 | `原值 -4 已按出厂 8 生效` |
+/// | `"auto"`（类型不对） | 8 | `原值 auto 已按出厂 8 生效` ← **本用例补的洞** |
+/// | `8.5` / `true`（类型不对） | 3 | `原值 8.5 / true 已按出厂 3 生效` |
+/// | `0`（retry 特例） | 1 | `原值 0 已按 1 生效`（上面那条用例） |
+///
+/// 抓得住：① 原值退回 `Value::as_i64`（非整数 → `None` → `let raw = raw?` 短路 ⇒ 一个字都不说）；
+/// ② 字符串原值被 serde 加上引号（上屏成 `"auto"`）；③ `null` 被当成「写过」（会冒出
+/// `原值 null …`）。
+/// 抓不住：别的键（region / mirror / proxy_mode）同族缺口——那三条不在 P3-5 点名范围，
+/// 已由 tower 登记为另一个 follow-up。
+#[test]
+fn every_bad_value_shape_says_what_the_raw_value_was() {
+    // 负整数
+    let (dir, env) = env_with(
+        "bad-negative",
+        serde_json::json!({ "download": { "concurrency": -4 } }),
+    );
+    let group_view = group(&env);
+    let concurrency = row(&group_view, unlucky_core::download::config::KEY_CONCURRENCY);
+    assert_eq!(chosen(concurrency), "8", "-4 越界 ⇒ 生效值是出厂 8");
+    assert!(
+        concurrency.description.contains("原值 -4 已按出厂 8 生效"),
+        "负整数也要说清原值：{}",
+        concurrency.description
+    );
+    std::fs::remove_dir_all(&dir).ok();
+
+    // 类型不对：字符串 + 浮点（一次覆盖两个）
+    let (dir, env) = env_with(
+        "bad-types",
+        serde_json::json!({ "download": { "concurrency": "auto", "retry_limit": 8.5 } }),
+    );
+    let group_view = group(&env);
+    let concurrency = row(&group_view, unlucky_core::download::config::KEY_CONCURRENCY);
+    let retry = row(&group_view, unlucky_core::download::config::KEY_RETRY_LIMIT);
+    assert_eq!(
+        chosen(concurrency),
+        "8",
+        "\"auto\" 不是整数 ⇒ 生效值是出厂 8"
+    );
+    assert!(
+        concurrency
+            .description
+            .contains("原值 auto 已按出厂 8 生效"),
+        "字符串坏值必须原样上屏（不带引号）并说清它被忽略了：{}",
+        concurrency.description
+    );
+    assert!(
+        !concurrency.description.contains("\"auto\""),
+        "上屏的是用户写的那个词，不是 serde 的转义形式：{:?}",
+        concurrency.description
+    );
+    assert_eq!(chosen(retry), "3", "8.5 不是整数 ⇒ 生效值是出厂 3");
+    assert!(
+        retry.description.contains("原值 8.5 已按出厂 3 生效"),
+        "浮点坏值也要说清：{}",
+        retry.description
+    );
+    std::fs::remove_dir_all(&dir).ok();
+
+    // 布尔 / null：`true` 要说；`null` 等于没写（不该冒出「原值 null …」）
+    let (dir, env) = env_with(
+        "bad-bool-null",
+        serde_json::json!({ "download": { "retry_limit": true, "concurrency": null } }),
+    );
+    let group_view = group(&env);
+    let retry = row(&group_view, unlucky_core::download::config::KEY_RETRY_LIMIT);
+    let concurrency = row(&group_view, unlucky_core::download::config::KEY_CONCURRENCY);
+    assert!(
+        retry.description.contains("原值 true 已按出厂 3 生效"),
+        "布尔坏值也要说清：{}",
+        retry.description
+    );
+    assert!(
+        !concurrency.description.contains("原值"),
+        "`null` 等于没写，不该有提示：{}",
+        concurrency.description
+    );
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+/// `retry_limit = 0`（旧版档位）落成「只试一次」：行上画 1，并说清原值是 0。
+///
+/// 抓得住：把 `0` 原样画上屏（那时引擎按 1 跑，界面说 0 —— 又一个「设置项说假话」）；
+/// 或者把这句话写成「按出厂 3 生效」（实际生效值是 1，不是出厂 3）。
+/// 抓不住：用户是否理解 0/1 同义（那是文案的事，本行 base 段已有说明）。
+#[test]
+fn a_zero_retry_in_the_file_is_shown_as_one_and_says_so() {
+    let (dir, env) = env_with(
+        "retry-zero",
+        serde_json::json!({ "download": { "retry_limit": 0 } }),
+    );
+
+    let group = group(&env);
+    let retry = row(&group, unlucky_core::download::config::KEY_RETRY_LIMIT);
+
+    assert_eq!(chosen(retry), "1", "0 生效为 1（只试一次）");
+    assert!(
+        retry.description.contains("原值 0 已按 1 生效"),
+        "必须写明 0 落成了 1（不是出厂 3）：{}",
+        retry.description
+    );
+    assert!(
+        !retry.description.contains("原值 0 已按出厂"),
+        "1 不是出厂值（出厂 3），措辞不许混"
+    );
+
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+/// **P3-3（选了「在下载设置页补一条 gh_proxy 端到端链」这一支）**：
+/// 文件里的 `download.gh_proxy` → `store` → [`tuning_of`] → core 的三态 → 行上的值与那句
+/// 「当前生效：…」。三档各走一遍。
+///
+/// 抓得住：① 键名读错（例如 `download.gh-proxy`）⇒ 三档全部退回 `Builtin`，`off`/`prefix` 两档红；
+/// ② 三态翻译被拍平（`off` 也当 `Builtin`）⇒ 第二档红；③ 行上只画文件原文、不画生效档位
+/// ⇒ 那一句文案红（页面上「填了 off 却没关」的那种谎正是它兜的）。
+/// 抓不住：候选链里到底生成了什么（那是 `shared.rs` 的 `expand()`，core 侧已有用例），
+/// 也抓不住真下载时是否走那条链（要网络）。
+///
+/// 为什么选这一支而不是拆 core 的 `gh_proxy_override_reaches_the_profile_and_the_chain`：
+/// 那个文件不在本 mission 的 scope（`crates/core/**`），拆它得由 core 线另立 mission；
+/// 而「设置文件 → 宿主 → 三态」这一段的缺口正是本 mission 要接的路，补在这里能证明整条链
+/// 从用户手写的那串字节开始就是通的。
+#[test]
+fn the_gh_proxy_key_travels_from_the_file_to_the_core_tri_state() {
+    use unlucky_core::download::config::KEY_GH_PROXY;
+
+    // ① 留空 = 跟随内置默认（空串不是「关」）。
+    let (empty_dir, empty_env) = env_with(
+        "gh-empty",
+        serde_json::json!({ "download": { "gh_proxy": "" } }),
+    );
+    let empty_group = group(&empty_env);
+    let empty_row = row(&empty_group, KEY_GH_PROXY);
+    assert_eq!(tuning_of(&empty_env).gh_proxy, GhProxyOverride::Builtin);
+    assert_eq!(empty_row.value_text, "", "文件里的原文照旧回填");
+    assert!(
+        empty_row.description.contains("当前生效：跟随内置默认"),
+        "空串必须说成「跟随内置默认」而不是「关闭」：{}",
+        empty_row.description
+    );
+    std::fs::remove_dir_all(&empty_dir).ok();
+
+    // ② 填 off = 关（不生成任何 gh-proxy 候选）。
+    let (off_dir, off_env) = env_with(
+        "gh-off",
+        serde_json::json!({ "download": { "gh_proxy": "off" } }),
+    );
+    let off_group = group(&off_env);
+    let off_row = row(&off_group, KEY_GH_PROXY);
+    assert_eq!(tuning_of(&off_env).gh_proxy, GhProxyOverride::Off);
+    assert_eq!(off_row.value_text, "off");
+    assert!(
+        off_row.description.contains("当前生效：已关闭（off）"),
+        "填了 off 就必须说「已关闭」：{}",
+        off_row.description
+    );
+    std::fs::remove_dir_all(&off_dir).ok();
+
+    // ③ 填 URL 前缀 = 覆盖它。
+    let (prefix_dir, prefix_env) = env_with(
+        "gh-prefix",
+        serde_json::json!({ "download": { "gh_proxy": "https://gh.example/" } }),
+    );
+    let prefix_group = group(&prefix_env);
+    let prefix_row = row(&prefix_group, KEY_GH_PROXY);
+    assert_eq!(
+        tuning_of(&prefix_env).gh_proxy,
+        GhProxyOverride::Prefix("https://gh.example/".to_string())
+    );
+    assert_eq!(prefix_row.value_text, "https://gh.example/");
+    assert!(
+        prefix_row
+            .description
+            .contains("当前生效：覆盖为 https://gh.example/"),
+        "覆盖档必须把生效的前缀写出来：{}",
+        prefix_row.description
+    );
+    std::fs::remove_dir_all(&prefix_dir).ok();
+}
diff --git a/crates/presenter/src/host/settings_tests.rs b/crates/presenter/src/host/settings_tests.rs
new file mode 100644
index 0000000..3dd3b7b
--- /dev/null
+++ b/crates/presenter/src/host/settings_tests.rs
@@ -0,0 +1,226 @@
+//! host/settings.rs 的单测（拆文件守 400 行上限）。
+//!
+//! **为什么单独一个文件**：`settings.rs` 正好顶在 400 行硬线上，而「设置写进去到底有没有生效」
+//! 这一类用例恰恰需要反复构造数据根 + 读写 `launcher.json`，塞回生产文件就只剩砍论证注释这一条路。
+//! 本文件与它守的代码同目录、同名族（`settings.rs` 的 `#[path]` 挂载），**不是**随手放的杂项目。
+
+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)
+}
+
+/// **M193 守门**：把设置改成 2 ⇒ **下一次取到的引擎**的并发闸门真是 2（探针读 `Semaphore`）。
+///
+/// 这是「设置项说假话」那条缺陷族的正面守门。断言分三段，缺一段都守不住：
+///
+/// 1. 写设置（走 `SetSetting` 同一条 `settings::set`）；
+/// 2. 走宿主真正的取引擎入口 `host::engine::engine(env)`（它负责把设置灌进 core 调优）；
+/// 3. 读**引擎的真实闸门** `concurrency_probe()`，不是 `config().max_concurrency`。
+///
+/// 变异证明（只改实现侧）：
+/// * 把 `host/engine.rs::engine` 里那行 `apply_tuning` 删掉 ⇒ 引擎按出厂 8 建，探针读到 8，红；
+/// * 把 `core::download::shared::build` 里的 `tune.apply_to(EngineConfig::default())` 换回
+///   `EngineConfig::default()` ⇒ 同样读到 8，红；
+/// * 把 `settings/download.rs::tuning_of` 读错键名（例如 `download.threads`）⇒ 读到默认 8，红。
+///
+/// `download.gh_proxy` 那一路**没有**端到端用例：那个键由 M197 登记，尚未合入 dev，而
+/// `setting::document` 只认已登记的键（未登记的键进不了 `effective()`），所以这里写进文件也读不出来。
+/// core 侧有「调优三档 → 候选链」的守卫（`download/shared.rs`），端到端那一半登记为 M197 的 follow-up。
+#[test]
+fn the_concurrency_setting_reaches_the_real_download_engine() {
+    let dir = std::env::temp_dir().join(format!("ull-host-tune-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    let env = env_in(&dir);
+
+    set(&env, "download.concurrency", "2").expect("写并发");
+    set(&env, "download.retry_limit", "1").expect("写尝试次数");
+
+    let engine = crate::host::engine::engine(&env);
+    assert_eq!(engine.concurrency_probe(), 2, "闸门必须真是 2 张许可");
+    assert_eq!(
+        engine.config().max_attempts_per_source,
+        1,
+        "尝试次数也要吃到设置"
+    );
+
+    // P2-1：`retry_limit = 0`（旧配置里真有）必须写得回去、且引擎真的只试一次（不是出厂 3）。
+    set(&env, "download.retry_limit", "0").expect("0 是合法值（旧版档位）");
+    let zero = crate::host::engine::engine(&env);
+    println!(
+        "retry_limit=0 => store={:?} engine.config().max_attempts_per_source={}",
+        env.store().doc().effective_i64("download.retry_limit"),
+        zero.config().max_attempts_per_source
+    );
+    assert_eq!(
+        zero.config().max_attempts_per_source,
+        1,
+        "0 必须落成「只试一次」，不许回落出厂 3"
+    );
+
+    // 改回去 ⇒ 下一次取到的引擎跟着换（不是「重启才生效」）。
+    set(&env, "download.concurrency", "16").expect("再写并发");
+    let rebuilt = crate::host::engine::engine(&env);
+    assert_eq!(rebuilt.concurrency_probe(), 16);
+    assert!(
+        !std::sync::Arc::ptr_eq(&engine, &rebuilt),
+        "参数变了必须换引擎，否则新值落不到在飞的那份上"
+    );
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+#[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/update.rs b/crates/presenter/src/host/update.rs
new file mode 100644
index 0000000..8fbd4f2
--- /dev/null
+++ b/crates/presenter/src/host/update.rs
@@ -0,0 +1,374 @@
+//! 自更新在宿主层的**装配与翻译**（M159）。
+//!
+//! # 分工
+//!
+//! ```text
+//! core::update::Job   ← 检查/应用的做法（版本比较、渠道准入、双检、原子替换全在 core）
+//!         ▲
+//!         │ 本模块只做四件事
+//! Factory             ← 用哪个源、暂存放哪、替换谁（生产：GitHub + 本进程 exe）
+//! outcome_of          ← core 的结论 → DTO（GUI 与 CLI 共用同一条判据）
+//! Paths / Migration   ← 两个开关的落点，以及旧 `cache/update/prefs.json` 的迁移（M161）
+//! ```
+//!
+//! 「GUI 与 CLI 行为一致」由结构保证：两边都只构造 `core::update::Job` 并调用 `check` / `apply`，
+//! 没有第二处版本比较、也没有第二个下载/校验流程（CLI 侧见 `crates/cli/src/commands/update.rs`）。
+//!
+//! # 静默检查的边界
+//!
+//! 启动时的检查能被关掉（`update.auto_check`）：关掉之后 host 的装配路径**根本不派发**
+//! （判据在 `CoreHost::refresh_all` 的那一行 `if self.update.should_check_on_start()`）。
+//!
+//! # 两个开关住在主配置里（M161）
+//!
+//! `update.auto_check` / `update.channel` 是 `crates/core/src/setting/keys.rs` 的 schema 键，
+//! 落在 `<数据根>/config/launcher.json`——与「所有配置走 `core::setting`」的约定一致，
+//! 于是 `ull config get update.auto_check` 读到的是**同一个值**。
+//!
+//! M159 曾把这两项临时放进更新域自己的文件 `<数据根>/cache/update/prefs.json`（当时
+//! `crates/core/src/setting/**` 不在那条 mission 的 scope），代价是「GUI 里关掉、CLI 仍报 true」。
+//! 存量值的迁移在 [`unlucky_core::setting::update_prefs`]：幂等（源指纹闸门）、不丢 `false`、
+//! 新值胜出、旧文件改名为 `prefs.json.migrated` 后不再有任何读路径。`Runtime::with_factory`
+//! 在建会话时跑一次并记住结局（[`Runtime::migration`]，`null` = 没有遗留文件）。
+
+use std::path::{Path, PathBuf};
+use std::sync::Arc;
+
+use crate::dto::{UpdateCandidateView, UpdateFailureView, UpdateOutcome};
+use unlucky_core::download::DownloadEngine;
+use unlucky_core::launch::time::{format_rfc3339_millis, now};
+use unlucky_core::setting::update_prefs;
+use unlucky_core::update::{
+    default_source, staging_dir, Applied, CheckOutcome, DirSource, Job, Target, UpdateError,
+    UpdateSource, Version,
+};
+
+use super::engine;
+use super::env::HostEnv;
+use super::logs::display_time;
+
+/// 本进程版本。整个 workspace 同版本（根 `Cargo.toml` 的 `[workspace.package]`）。
+#[must_use]
+pub fn current_version() -> &'static str {
+    env!("CARGO_PKG_VERSION")
+}
+
+/// 更新域的三个落点（都由数据根派生，core 不猜布局）。
+#[derive(Debug, Clone)]
+pub struct Paths {
+    /// `<数据根>/config/launcher.json`（两个开关的真相源）
+    pub launcher: PathBuf,
+    /// `<数据根>/cache/update/prefs.json`（M159 的旧文件；迁移后改名 `.migrated`）
+    pub legacy: PathBuf,
+    /// `<数据根>/config/update-prefs-migration.json`（迁移收据）
+    pub receipt: PathBuf,
+}
+
+impl Paths {
+    /// 按数据根装配。
+    #[must_use]
+    pub fn for_env(env: &HostEnv) -> Self {
+        Self {
+            launcher: env.launcher_config(),
+            legacy: env.layout.cache().join("update").join("prefs.json"),
+            receipt: env.layout.config().join(update_prefs::RECEIPT_FILE),
+        }
+    }
+
+    /// 迁移要的三个路径。
+    #[must_use]
+    pub fn targets(&self) -> update_prefs::Targets<'_> {
+        update_prefs::Targets {
+            launcher: &self.launcher,
+            legacy: &self.legacy,
+            receipt: &self.receipt,
+        }
+    }
+}
+
+/// 怎么造一个 [`Job`]（源 / 暂存 / 替换目标）。
+///
+/// 每派发一次就造一个新的（`Job` 里装的源是 `Box`，不共享、不复用）：
+/// 这样「上一次用的源」不会跟着下一次跑，测试也能各用例各给一份本地目录。
+#[derive(Clone)]
+pub enum Factory {
+    /// 生产/spec 形态：GitHub Releases（**带 `update-test-source` feature 的验收构建**里，两档
+    /// 环境变量给全时是本地目录源，见 `unlucky_core::update::job` 的 `test_source_root`），
+    /// 引擎懒建一次。
+    Default {
+        /// 下载引擎（镜像/地区/健康度策略都在里面）。
+        engine: Arc,
+        /// 目标平台。
+        target: Target,
+        /// 暂存目录。
+        staging: PathBuf,
+        /// 替换目标。
+        dest: PathBuf,
+    },
+    /// 单测/取证：钉死一个本地目录源。
+    Dir {
+        /// 源根目录（`/stable.json` + 产物）。
+        root: PathBuf,
+        /// 目标平台。
+        target: Target,
+        /// 暂存目录。
+        staging: PathBuf,
+        /// 替换目标。
+        dest: PathBuf,
+    },
+}
+
+impl std::fmt::Debug for Factory {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("Factory")
+            .field("dir", &self.dir())
+            .field("dest", &self.dest())
+            .finish()
+    }
+}
+
+impl Factory {
+    /// 生产装配：数据根的缓存做暂存，替换目标是**本进程的 exe**。
+    #[must_use]
+    pub fn for_env(env: &HostEnv) -> Self {
+        Self::Default {
+            engine: engine::engine(env),
+            target: Target::current(),
+            staging: staging_dir(&env.layout.cache()),
+            dest: unlucky_core::update::process_dest(),
+        }
+    }
+
+    /// 换替换目标（单测专用：测试**绝不**替换真的测试二进制）。
+    #[must_use]
+    pub fn with_dest(self, dest: impl Into) -> Self {
+        let dest = dest.into();
+        match self {
+            Self::Default {
+                engine,
+                target,
+                staging,
+                ..
+            } => Self::Default {
+                engine,
+                target,
+                staging,
+                dest,
+            },
+            Self::Dir {
+                root,
+                target,
+                staging,
+                ..
+            } => Self::Dir {
+                root,
+                target,
+                staging,
+                dest,
+            },
+        }
+    }
+
+    /// 换暂存目录（单测：落在临时目录里）。
+    #[must_use]
+    pub fn with_staging(self, staging: impl Into) -> Self {
+        let staging = staging.into();
+        match self {
+            Self::Default {
+                engine,
+                target,
+                dest,
+                ..
+            } => Self::Default {
+                engine,
+                target,
+                staging,
+                dest,
+            },
+            Self::Dir {
+                root, target, dest, ..
+            } => Self::Dir {
+                root,
+                target,
+                staging,
+                dest,
+            },
+        }
+    }
+
+    /// 换成本地目录源（单测/取证）。
+    #[must_use]
+    pub fn with_dir(self, root: impl Into) -> Self {
+        let root = root.into();
+        match self {
+            Self::Default {
+                target,
+                staging,
+                dest,
+                ..
+            } => Self::Dir {
+                root,
+                target,
+                staging,
+                dest,
+            },
+            Self::Dir {
+                target,
+                staging,
+                dest,
+                ..
+            } => Self::Dir {
+                root,
+                target,
+                staging,
+                dest,
+            },
+        }
+    }
+
+    /// 本地目录源根（`None` = 走 GitHub）。
+    #[must_use]
+    pub fn dir(&self) -> Option<&Path> {
+        match self {
+            Self::Default { .. } => None,
+            Self::Dir { root, .. } => Some(root),
+        }
+    }
+
+    /// 替换目标。
+    #[must_use]
+    pub fn dest(&self) -> &Path {
+        match self {
+            Self::Default { dest, .. } | Self::Dir { dest, .. } => dest,
+        }
+    }
+
+    /// 造一个 [`Job`]。
+    #[must_use]
+    pub fn job(&self) -> Job {
+        match self {
+            Self::Default {
+                engine,
+                target,
+                staging,
+                dest,
+            } => Job::new(
+                default_source(Arc::clone(engine)),
+                *target,
+                staging.clone(),
+                dest.clone(),
+            ),
+            Self::Dir {
+                root,
+                target,
+                staging,
+                dest,
+            } => Job::new(
+                Box::new(DirSource::new(root.clone())) as Box,
+                *target,
+                staging.clone(),
+                dest.clone(),
+            ),
+        }
+    }
+}
+
+/// 后台线程 → host 的**更新**回报（只含 DTO：`job.rs` 不必认识 core 类型）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Report {
+    /// 检查结论
+    Checked(UpdateOutcome),
+    /// 应用结局
+    Applied(ApplyReport),
+}
+
+/// 应用结局。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ApplyReport {
+    /// 成功：新版本已就位
+    Installed {
+        /// 新版本号
+        version: String,
+        /// 替换后的路径
+        path: String,
+        /// 旧版本备份路径（`None` = 原本没有文件 / 已清掉）
+        backup: Option,
+    },
+    /// 复查时已经没有可装的更新
+    Nothing(UpdateOutcome),
+    /// 失败（分类 + 人话）
+    Failed(UpdateFailureView),
+}
+
+impl Report {
+    /// 应用结局 → 回报（映射只在这一处）。
+    #[must_use]
+    pub fn applied(result: Result) -> Self {
+        match result {
+            Ok(Applied::Installed { receipt, version }) => Self::Applied(ApplyReport::Installed {
+                version,
+                path: receipt.dest.display().to_string(),
+                backup: receipt.backup.map(|backup| backup.display().to_string()),
+            }),
+            Ok(Applied::Nothing(outcome)) => {
+                Self::Applied(ApplyReport::Nothing(outcome_of(Ok(outcome))))
+            }
+            Err(error) => Self::Applied(ApplyReport::Failed(failure_of(&error))),
+        }
+    }
+}
+
+/// core 的检查结论 → DTO（**唯一**的映射点）。
+///
+/// 三条不许折叠的边界在这里体现：`UpToDate` 与 `Failed` 是两个变体；
+/// 「有更高版本但没有本平台产物」单独一个变体（[`UpdateOutcome::MissingArtifact`]）。
+#[must_use]
+pub fn outcome_of(result: Result) -> UpdateOutcome {
+    match result {
+        Ok(CheckOutcome::UpToDate { latest, .. }) => UpdateOutcome::UpToDate {
+            latest: latest.map(|version| version.to_string()),
+        },
+        Ok(CheckOutcome::Available(candidate)) => {
+            UpdateOutcome::Available(Box::new(UpdateCandidateView {
+                version: candidate.release.version.to_string(),
+                size: candidate.artifact.size,
+                notes: notes_summary(candidate.release.notes.as_deref()),
+                forced: candidate.urgency == unlucky_core::update::Urgency::Forced,
+            }))
+        }
+        Ok(CheckOutcome::MissingArtifact { release }) => UpdateOutcome::MissingArtifact {
+            version: release.version.to_string(),
+        },
+        Err(error) => UpdateOutcome::Failed(failure_of(&error)),
+    }
+}
+
+/// core 的错误 → 失败视图（分类 id + 人话 + 可重试）。
+#[must_use]
+pub fn failure_of(error: &UpdateError) -> UpdateFailureView {
+    UpdateFailureView::new(error.kind.as_str(), error.to_string(), error.is_retryable())
+}
+
+/// 更新说明摘要的字符上限（提示条上只放一段；整篇说明在 Release 页）。
+const NOTES_LIMIT: usize = 160;
+
+fn notes_summary(notes: Option<&str>) -> String {
+    let text = notes.unwrap_or("").trim();
+    if text.chars().count() <= NOTES_LIMIT {
+        return text.to_string();
+    }
+    let mut short: String = text.chars().take(NOTES_LIMIT).collect();
+    short.push('…');
+    short
+}
+
+/// 当前时刻的人读戳（`MM-DD HH:MM`，与日志页同一个格式函数）。
+pub(super) fn stamp() -> String {
+    display_time(&format_rfc3339_millis(now()))
+}
+
+/// 把版本号解析成 core 的 [`Version`]（`None` = 编译进来的版本号不合法，理论上不可能）。
+#[must_use]
+pub(super) fn parse_version(text: &str) -> Option {
+    Version::parse(text).ok()
+}
diff --git a/crates/presenter/src/host/update_apply_tests.rs b/crates/presenter/src/host/update_apply_tests.rs
new file mode 100644
index 0000000..14054d5
--- /dev/null
+++ b/crates/presenter/src/host/update_apply_tests.rs
@@ -0,0 +1,91 @@
+//! 应用（下载 → 双检 → 替换）的用例：校验失败不许碰目标、成功要留备份。
+//!
+//! 夹具（`TempDir` / `factory` / `job` / `manifest_for`）在父模块，本文件 `use super::*`。
+
+use super::*;
+
+// ------------------------------------------------------------------ 应用
+
+/// 摘要不符 ⇒ 拒绝应用 + 暂存文件不残留 + 目标文件没被换掉。
+#[test]
+fn sha256_mismatch_refuses_the_apply_and_leaves_no_temp_file() {
+    let tmp = TempDir::new("digest");
+    let good = b"new-binary-v2";
+    let evil = b"evil-binary-x"; // 同样长度：先过长度判据，才能测到摘要这一关
+    assert_eq!(good.len(), evil.len());
+    // 清单声明的是 good 的摘要，盘上给的却是 evil。
+    dir_source(&tmp, &manifest_for("0.9.0", good, ""), evil);
+
+    let dest = tmp.join("bin/unlucky-launcher.exe");
+    std::fs::create_dir_all(dest.parent().expect("父目录")).expect("bin");
+    std::fs::write(&dest, b"old-binary-v1").expect("旧版本");
+
+    let report = Report::applied(job(&tmp).apply(&version("0.2.2"), Channel::Stable));
+    match report {
+        Report::Applied(ApplyReport::Failed(failure)) => {
+            assert_eq!(failure.kind, "digest_mismatch", "失败分类要能区分摘要不符");
+            assert!(failure.retryable, "摘要不符是可重试的（换源/重下可能变好）");
+        }
+        other => panic!("摘要不符必须拒绝应用，实际 {other:?}"),
+    }
+
+    // 目标文件一个字节都没动
+    assert_eq!(
+        std::fs::read(&dest).expect("读旧版本"),
+        b"old-binary-v1",
+        "校验失败不许碰目标文件"
+    );
+    // 暂存目录里不许留 .ullupd 中间文件
+    let staging = tmp.join("staging");
+    let leftovers: Vec = std::fs::read_dir(&staging)
+        .map(|entries| {
+            entries
+                .filter_map(Result::ok)
+                .map(|entry| entry.file_name().to_string_lossy().into_owned())
+                .collect()
+        })
+        .unwrap_or_default();
+    assert!(
+        leftovers.is_empty(),
+        "校验失败后暂存目录里还有文件：{leftovers:?}"
+    );
+}
+
+/// 正常应用：新字节就位、旧字节进备份、回报是「已就位」。
+#[test]
+fn a_successful_apply_leaves_the_new_file_and_a_backup() {
+    let tmp = TempDir::new("apply");
+    let payload = b"new-binary-v2";
+    dir_source(
+        &tmp,
+        &manifest_for("0.9.0", payload, "修掉启动崩溃"),
+        payload,
+    );
+
+    let dest = tmp.join("bin/unlucky-launcher.exe");
+    std::fs::create_dir_all(dest.parent().expect("父目录")).expect("bin");
+    std::fs::write(&dest, b"old-binary-v1").expect("旧版本");
+
+    let applied = job(&tmp)
+        .apply(&version("0.2.2"), Channel::Stable)
+        .expect("应用成功");
+    let Applied::Installed { receipt, version } = applied else {
+        panic!("应当装上");
+    };
+    assert_eq!(version, "0.9.0");
+    assert_eq!(std::fs::read(&dest).expect("读新版本"), payload);
+    let backup = receipt.backup.clone().expect("旧版本应留备份");
+    assert_eq!(
+        std::fs::read(&backup).expect("读备份"),
+        b"old-binary-v1",
+        "回滚用的旧版本要在备份里"
+    );
+
+    // 回报 → 快照：「就位」状态让提示条变成「重启后生效」
+    let mut runtime = Runtime::with_factory(&HostEnv::at_root(tmp.join("root")), factory(&tmp));
+    runtime.adopt(Report::applied(Ok(Applied::Installed { receipt, version })));
+    let view = runtime.snapshot();
+    assert!(view.ready.is_some(), "就位状态要进快照");
+    assert!(matches!(view.banner(), Some(UpdateBanner::Ready(_))));
+    assert!(!view.applying);
+}
diff --git a/crates/presenter/src/host/update_session_tests.rs b/crates/presenter/src/host/update_session_tests.rs
new file mode 100644
index 0000000..4db422e
--- /dev/null
+++ b/crates/presenter/src/host/update_session_tests.rs
@@ -0,0 +1,212 @@
+//! 会话状态的用例：拒绝后不再打扰、关掉自动检查后启动不派发、偏好跨重启、GUI/CLI 同一内核。
+//!
+//! 夹具在父模块，本文件 `use super::*`。
+
+use super::*;
+
+// ------------------------------------------------------------------ 会话状态
+
+/// 忽略**某一个版本**之后：它自己不弹了，候选留着；**更高版本照弹**；手动检查清掉忽略。
+///
+/// 这条是复审 P3-1 的守门：`skipped` 曾经是会话级 bool，于是「忽略 0.2.3」把同一次运行里
+/// 后来发布的 0.2.4 也一起压住了——而文案写的是「忽略这个版本」。
+#[test]
+fn skipping_a_version_does_not_silence_the_next_one() {
+    fn available(version: &str) -> Report {
+        Report::Checked(UpdateOutcome::Available(Box::new(
+            crate::dto::UpdateCandidateView {
+                version: version.to_string(),
+                size: 12,
+                notes: String::new(),
+                forced: false,
+            },
+        )))
+    }
+
+    let tmp = TempDir::new("dismiss");
+    let mut runtime = Runtime::with_factory(&HostEnv::at_root(tmp.join("root")), factory(&tmp));
+    runtime.adopt(available("0.9.0"));
+    assert!(matches!(
+        runtime.view().banner(),
+        Some(UpdateBanner::Available(_))
+    ));
+
+    runtime.dismiss();
+    assert_eq!(
+        runtime.view().skipped.as_deref(),
+        Some("0.9.0"),
+        "忽略要记下**那一个**版本号"
+    );
+    assert!(runtime.view().banner().is_none(), "被忽略的版本不再打扰");
+    assert!(
+        runtime.view().outcome.candidate().is_some(),
+        "候选不能丢：设置页还要能手动装"
+    );
+
+    // 静默检查回来的是**同一个**版本：仍然压住（用户刚说过忽略它）。
+    let _ = runtime.begin_check(false).expect("静默检查派发");
+    runtime.adopt(available("0.9.0"));
+    assert!(
+        runtime.view().banner().is_none(),
+        "同一版本不许因为一次静默检查又弹出来"
+    );
+
+    // 静默检查回来的是**更高**版本：照弹（忽略的是 0.9.0，不是「以后别再问」）。
+    let _ = runtime.begin_check(false).expect("静默检查派发");
+    runtime.adopt(available("0.9.1"));
+    assert!(
+        matches!(runtime.view().banner(), Some(UpdateBanner::Available(c)) if c.version == "0.9.1"),
+        "0.9.0 被忽略不该压住 0.9.1"
+    );
+
+    // 手动检查 ⇒ 清掉忽略标记（用户要看真结果），重新查。
+    let _ = runtime.begin_check(true).expect("手动检查派发");
+    assert!(
+        runtime.view().skipped.is_none(),
+        "手动检查要清掉「忽略这个版本」"
+    );
+    assert!(runtime.view().outcome.is_checking());
+}
+
+/// 没有候选时点「忽略」是空操作：不该写进一个「你别问」的状态。
+#[test]
+fn dismissing_without_a_candidate_does_nothing() {
+    let tmp = TempDir::new("dismiss-none");
+    let mut runtime = Runtime::with_factory(&HostEnv::at_root(tmp.join("root")), factory(&tmp));
+    runtime.adopt(Report::Checked(UpdateOutcome::UpToDate {
+        latest: Some("0.2.2".to_string()),
+    }));
+    runtime.dismiss();
+    assert!(runtime.view().skipped.is_none());
+}
+
+/// 关掉「启动时检查」之后：状态上是 no-op、启动路径上根本不派发。
+///
+/// 开关的落点是**主配置**（`update.auto_check`），这里顺带把 M161 的迁移走一遍：
+/// 旧 `cache/update/prefs.json` 里的 `false` 必须是新会话看到的 `false`（不是默认的 `true`）。
+#[test]
+fn auto_check_off_means_no_request_on_start() {
+    let tmp = TempDir::new("autocheck");
+    let env = HostEnv::at_root(tmp.join("root"));
+    let prefs_path = env.layout.cache().join("update").join("prefs.json");
+    std::fs::create_dir_all(prefs_path.parent().expect("父目录")).expect("建 cache");
+    std::fs::write(&prefs_path, r#"{"auto_check": false}"#).expect("写旧偏好");
+
+    let runtime = Runtime::with_factory(&env, factory(&tmp));
+    assert!(!runtime.view().auto_check, "开关要读进快照");
+    assert!(!runtime.auto_check(), "关掉的值一路迁进主配置");
+    assert!(
+        !runtime.should_check_on_start(),
+        "关掉开关后启动不许派发检查"
+    );
+    // 迁移确实发生了：旧文件退役 + 收据落盘（收据可查）。
+    assert!(!prefs_path.exists(), "旧文件必须退役");
+    let receipt = runtime
+        .migration()
+        .receipt()
+        .expect("收据路径")
+        .to_path_buf();
+    assert!(receipt.exists(), "收据要落盘：{}", receipt.display());
+
+    // 结构性判据：`refresh_all` 里那次静默检查必须挂在 `should_check_on_start` 上，
+    // 否则单测绿着而启动仍然联网（这条读源码，理由同 `instances/tests.rs` 的源码断言）。
+    let host = include_str!("mod.rs");
+    assert!(
+        host.contains("if self.update.should_check_on_start()"),
+        "refresh_all 的静默检查必须由 should_check_on_start 门控"
+    );
+}
+
+/// 开关能写进主配置、能读回（换一份 Runtime 仍记得上次的选择）。
+#[test]
+fn the_auto_check_preference_survives_a_restart() {
+    let tmp = TempDir::new("prefs");
+    let env = HostEnv::at_root(tmp.join("root"));
+    let mut runtime = Runtime::with_factory(&env, factory(&tmp));
+    assert!(runtime.auto_check(), "缺省开");
+
+    runtime.set_auto_check(false).expect("落盘");
+    let restarted = Runtime::with_factory(&env, factory(&tmp));
+    assert!(!restarted.auto_check(), "重启后仍记得关掉");
+    assert!(!restarted.view().auto_check);
+
+    // 落点是主配置的 schema 键（CLI 读到的就是这一份），不是更新域自己的文件。
+    let text = std::fs::read_to_string(env.launcher_config()).expect("读主配置");
+    assert!(text.contains("\"auto_check\": false"), "{text}");
+    assert!(
+        !env.layout
+            .cache()
+            .join("update")
+            .join("prefs.json")
+            .exists(),
+        "新写入不许再落到旧文件"
+    );
+}
+
+/// GUI 与 CLI 共用**同一个** `Job::apply`（mission：不许两套逻辑）。
+///
+/// 判据是源码锚点：CLI 的 `update apply` 必须调 `Job::apply`，而不是自己拼一遍
+/// 「下载 + 校验 + 替换」。
+#[test]
+fn the_gui_and_the_cli_share_one_kernel_path() {
+    let cli = include_str!("../../../cli/src/commands/update.rs");
+    assert!(
+        cli.contains("Job::") && cli.contains(".apply("),
+        "CLI 必须复用 presenter 的 Job::apply（同一内核），实际没有调用"
+    );
+    // 反向：check 也只许走 Job::check
+    assert!(
+        cli.contains(".check("),
+        "CLI 的 update check 必须走 Job::check"
+    );
+}
+
+/// 辅助：装配自证用的是哪份源与哪个替换目标（日志/诊断用）。
+#[test]
+fn the_factory_names_its_source_and_target() {
+    let tmp = TempDir::new("source-id");
+    let factory = factory(&tmp);
+    assert_eq!(factory.dir(), Some(tmp.join("dist").as_path()));
+    assert_eq!(factory.dest(), tmp.join("bin/unlucky-launcher.exe"));
+}
+
+/// 渠道来自主配置的 `update.channel`（M161：不再是编译期常量）。
+///
+/// 抓得住：把渠道写回硬编码常量而键里是别的值；也抓得住「认不出的渠道 panic 而不是回出厂值」。
+#[test]
+fn the_channel_is_read_from_the_schema_key() {
+    let tmp = TempDir::new("channel-key");
+    let env = HostEnv::at_root(tmp.join("root"));
+    let runtime = Runtime::with_factory(&env, factory(&tmp));
+    assert_eq!(
+        runtime.channel().as_str(),
+        unlucky_core::setting::update_prefs::DEFAULT_CHANNEL,
+        "缺键 ⇒ 出厂渠道"
+    );
+    assert_eq!(runtime.view().channel, "stable", "快照里的渠道同源");
+
+    // 手改成一个 schema 不允许的值（越过 `config set` 的校验）⇒ 回出厂渠道，不许 panic。
+    std::fs::create_dir_all(env.layout.config()).expect("建 config");
+    std::fs::write(
+        env.launcher_config(),
+        r#"{"$schema":"https://schemas.unlucky-launcher.dev/ull/launcher/1.6.0","schemaVersion":1,
+            "update":{"channel":"hand-edited"}}"#,
+    )
+    .expect("写配置");
+    let runtime = Runtime::with_factory(&env, factory(&tmp));
+    assert_eq!(runtime.channel().as_str(), "stable", "认不出的渠道回出厂值");
+}
+
+/// CLI 与 GUI 用的是**同一个** core Job：源码锚点，防止有人另起一条流程。
+#[test]
+fn the_core_job_is_the_single_kernel() {
+    let job = include_str!("../../../core/src/update/job.rs");
+    assert!(
+        job.contains("pub fn apply(") && job.contains("pub fn check("),
+        "内核必须同时提供 check / apply"
+    );
+    assert!(
+        job.contains("install_staged(") && job.contains("stage("),
+        "替换与校验必须在内核里做（壳层不许自己拼）"
+    );
+}
diff --git a/crates/presenter/src/host/update_state.rs b/crates/presenter/src/host/update_state.rs
new file mode 100644
index 0000000..31105df
--- /dev/null
+++ b/crates/presenter/src/host/update_state.rs
@@ -0,0 +1,319 @@
+//! 更新状态的**会话层**：一份 `UpdateView`、主配置里的两个开关、以及把 `CoreHost` 接上后台线程。
+//!
+//! 与 [`super::update`] 的分工：那边是「一次检查/应用的纯做法」（选源、调 core、映射 DTO），
+//! 这边是「谁来记着它、谁来派发」。拆开是因为两边都各有一批判据要写清（静默检查的开关、
+//! 拒绝后不再打扰、应用失败不许丢掉候选），塞在一个文件里会越过 400 行硬线。
+
+use std::path::PathBuf;
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use serde_json::json;
+use unlucky_core::setting::keys::launcher_schema;
+use unlucky_core::setting::store::SettingStore;
+use unlucky_core::setting::update_prefs::{self, Migration};
+use unlucky_core::update::{Channel, Version};
+
+use crate::dto::{CoreEvent, ReadyUpdate, UpdateOutcome, UpdateView};
+
+use super::env::HostEnv;
+use super::update::{current_version, outcome_of, ApplyReport, Factory, Paths, Report};
+use super::CoreHost;
+
+/// 会话级更新状态（提示条 / 设置页共用一份）。
+#[derive(Debug)]
+pub struct Runtime {
+    view: UpdateView,
+    /// `update.auto_check` 的生效值（缓存：`should_check_on_start` 在 `refresh_all` 里被调）。
+    auto_check: bool,
+    factory: Factory,
+    /// `config/launcher.json`（两个开关的真相源；写它就走 `core::setting`）。
+    launcher: PathBuf,
+    /// 建会话时那次遗留文件迁移的结局（`Nothing` = 没有旧文件）。
+    migration: Migration,
+    /// 有一条检查/应用正在后台跑（防重复派发；进程内独占）。
+    inflight: bool,
+}
+
+impl Runtime {
+    /// 按数据根装配（顺带把 M159 的 `cache/update/prefs.json` 迁进主配置）。
+    #[must_use]
+    pub fn for_env(env: &HostEnv) -> Self {
+        Self::with_factory(env, Factory::for_env(env))
+    }
+
+    /// 用给定装配（单测：临时目录 + 本地目录源）。
+    #[must_use]
+    pub fn with_factory(env: &HostEnv, factory: Factory) -> Self {
+        let paths = Paths::for_env(env);
+        // 迁移在建会话时跑一次：**幂等**（源指纹闸门），没有旧文件时是纯 stat 一次。
+        let migration = update_prefs::migrate(paths.targets(), now_ms());
+        let store = SettingStore::load(&paths.launcher, launcher_schema());
+        let auto_check = update_prefs::auto_check(store.doc());
+        let channel = update_prefs::channel(store.doc()).to_string();
+        Self {
+            view: UpdateView::new(current_version(), &channel, auto_check),
+            auto_check,
+            factory,
+            launcher: paths.launcher,
+            migration,
+            inflight: false,
+        }
+    }
+
+    /// 当前快照。
+    #[must_use]
+    pub fn view(&self) -> &UpdateView {
+        &self.view
+    }
+
+    /// 重建「怎么造 Job」的装配（M165 复审 P2-1）。
+    ///
+    /// 自更新的 `Factory` 常驻持有下载引擎，`download::shared::forget` 换不掉它；「重新检测地区」
+    /// 要生效就得把新引擎接过来。只换 `factory`，**不动** `view` / `inflight` / 迁移收据：
+    /// 后台在飞的那条 Job 在派发时（`begin_check` / `begin_apply` → `Job`）就已经把 factory
+    /// 克隆进线程了，所以重建**不会**打断正在跑的检查/应用，只影响下一次派发。
+    pub fn rebuild_factory(&mut self, env: &HostEnv) {
+        self.factory = Factory::for_env(env);
+    }
+
+    /// 装配里那个下载引擎（单测断言「换了引擎」用；`Dir` 形态没有引擎）。
+    #[cfg(test)]
+    pub(super) fn factory_engine(
+        &self,
+    ) -> Option<&std::sync::Arc> {
+        match &self.factory {
+            Factory::Default { engine, .. } => Some(engine),
+            Factory::Dir { .. } => None,
+        }
+    }
+
+    /// 当前快照（克隆给事件/线程）。
+    #[must_use]
+    pub fn snapshot(&self) -> UpdateView {
+        self.view.clone()
+    }
+
+    /// 「启动时静默检查」的生效值（来自 `launcher.json` 的 `update.auto_check`）。
+    #[must_use]
+    pub const fn auto_check(&self) -> bool {
+        self.auto_check
+    }
+
+    /// 建会话时那次迁移的结局（`Nothing` = 没有遗留文件；收据路径见 [`Migration::receipt`]）。
+    #[must_use]
+    pub const fn migration(&self) -> &Migration {
+        &self.migration
+    }
+
+    /// 后台有没有一条在跑。
+    #[must_use]
+    pub const fn inflight(&self) -> bool {
+        self.inflight
+    }
+
+    /// 本进程版本解析（失败时 `None`：版本号是编译进来的常量，理论上不可能失败）。
+    #[must_use]
+    pub fn current(&self) -> Option {
+        Version::parse(current_version()).ok()
+    }
+
+    /// 启动时要不要静默检查（开关关掉 ⇒ 启动**一次网络都不发**）。
+    #[must_use]
+    pub fn should_check_on_start(&self) -> bool {
+        self.auto_check && !self.inflight
+    }
+
+    /// 检查/应用用的渠道：**每次都从主配置读**（用户在 CLI 里改了 `update.channel` 之后，
+    /// 下一次检查就按新渠道走，不用重启）。
+    ///
+    /// 认不出的值（手改文件 / 未来的渠道）回出厂渠道：schema 已经把写入侧卡在允许值上，
+    /// 读侧只兜底、不报错。
+    #[must_use]
+    pub fn channel(&self) -> Channel {
+        let store = SettingStore::load(&self.launcher, launcher_schema());
+        Channel::parse(update_prefs::channel(store.doc())).unwrap_or(Channel::Stable)
+    }
+
+    /// 开关「启动时静默检查」并写进主配置（`update.auto_check`）。
+    ///
+    /// # Errors
+    ///
+    /// 落盘失败返回人读文案（本会话的取值仍然生效——不因为写不进去就把开关弹回去）。
+    pub fn set_auto_check(&mut self, on: bool) -> Result<(), String> {
+        self.auto_check = on;
+        self.view.auto_check = on;
+        let mut store = SettingStore::load(&self.launcher, launcher_schema());
+        store
+            .set(update_prefs::KEY_AUTO_CHECK, json!(on))
+            .map_err(|error| format!("写 update.auto_check 被拒：{error}"))?;
+        match store.save() {
+            Ok(saved) if saved.wrote() || !store.is_dirty() => Ok(()),
+            Ok(_) => Err("update.auto_check 没有落盘（配置只读或文件不可信）".to_string()),
+            Err(error) => Err(format!("写 {} 失败：{error}", self.launcher.display())),
+        }
+    }
+
+    /// 开始一次检查：置「正在查」并返回要交给后台线程的 [`unlucky_core::update::Job`]
+    /// （`None` = 已经有一条在跑）。
+    ///
+    /// `manual` = 用户点的「立即检查」：会清掉「忽略这个版本」，并让失败也弹提示条。
+    pub fn begin_check(&mut self, manual: bool) -> Option {
+        if self.inflight {
+            return None;
+        }
+        self.inflight = true;
+        self.view.outcome = UpdateOutcome::Checking;
+        self.view.silent = !manual;
+        self.view.applying = false;
+        self.view.channel = self.channel().as_str().to_string();
+        if manual {
+            // 手动检查 = 用户要看真结果，把「忽略这个版本」清掉。
+            self.view.skipped = None;
+        }
+        Some(self.factory.job())
+    }
+
+    /// 开始应用：`None` = 没有在跑的必要（正在忙 / 没有候选 / 已经就位）。
+    pub fn begin_apply(&mut self) -> Option {
+        if self.inflight || self.view.ready.is_some() || self.view.outcome.candidate().is_none() {
+            return None;
+        }
+        self.inflight = true;
+        self.view.applying = true;
+        Some(self.factory.job())
+    }
+
+    /// 后台回报进快照（**唯一**的写入口：检查与应用都走这里）。
+    pub fn adopt(&mut self, report: Report) {
+        self.inflight = false;
+        match report {
+            Report::Checked(outcome) => {
+                // 「上次检查」只该被**检查**刷新：应用回来的那一刻不是一次检查。
+                self.view.checked_at = super::update::stamp();
+                // 「忽略这个版本」记的是版本号，所以**这里不需要动它**：
+                // 同一版本回来仍被压住，更高版本自然就提示了（见 `UpdateView::skipped`）。
+                // 手动检查那一支的清空在 `begin_check(manual)` 里。
+                self.view.outcome = outcome;
+            }
+            Report::Applied(ApplyReport::Installed {
+                version,
+                path,
+                backup,
+            }) => {
+                self.view.applying = false;
+                self.view.outcome = UpdateOutcome::UpToDate {
+                    latest: Some(version.clone()),
+                };
+                self.view.ready = Some(ReadyUpdate {
+                    version,
+                    path,
+                    backup,
+                });
+            }
+            Report::Applied(ApplyReport::Nothing(outcome)) => {
+                self.view.applying = false;
+                self.view.outcome = outcome;
+            }
+            Report::Applied(ApplyReport::Failed(failure)) => {
+                // 应用失败要说清是哪一步（校验不符 / 替换被占用）。候选随 `outcome` 一起换成
+                // `Failed`，**重试走「立即检查」重新复查**（清单只有几 KB，apply 本来也要复查一次）：
+                // 这样重试拿到的永远是最新那一份，而不是几分钟前的旧候选。失败也不再算「静默」，
+                // 提示条要把原因摆出来。
+                self.view.applying = false;
+                self.view.outcome = UpdateOutcome::Failed(failure);
+                self.view.silent = false;
+            }
+        }
+    }
+
+    /// 用户忽略**当前这个候选版本**：记下版本号（候选仍留在快照里，设置页可手动装）。
+    ///
+    /// 没有候选时是空操作（`skipped` 保持原样）：没版本可忽略就不该写进一个「你别问」的状态。
+    pub fn dismiss(&mut self) {
+        if let Some(candidate) = self.view.outcome.candidate() {
+            self.view.skipped = Some(candidate.version.clone());
+        }
+    }
+}
+
+impl CoreHost {
+    /// 发布更新快照（唯一的出口；`CoreEvent::Update` 是整份替换）。
+    pub(super) fn publish_update(&mut self) {
+        let view = self.update.snapshot();
+        self.send(CoreEvent::Update(Box::new(view)));
+    }
+
+    /// 让自更新子系统手里的引擎跟上共享登记处（M165 复审 P2-1）。
+    ///
+    /// 自更新的 `Factory` 从 `CoreHost::build` 起就把引擎存进字段，`shared::forget` 只让登记处
+    /// 不再持有那一份，换不掉它。所以「重新检测地区」除了失效登记处，还必须调本方法，否则自更新
+    /// 会继续按**旧地区档案**展开候选，直到进程结束。
+    pub(super) fn refresh_update_factory(&mut self) {
+        self.update.rebuild_factory(&self.env);
+    }
+
+    /// 派一次检查（`manual` = 设置页点的「立即检查」；`false` = 启动时的静默检查）。
+    pub(super) fn start_update_check(&mut self, manual: bool) {
+        let Some(current) = self.update.current() else {
+            return;
+        };
+        let Some(job) = self.update.begin_check(manual) else {
+            return;
+        };
+        let channel = self.update.channel();
+        // 先把「正在查」发出去：设置页的按钮据此转圈，而不是看起来没反应。
+        self.publish_update();
+        spawn_check(job, current, channel, self.tx.clone());
+    }
+
+    /// 应用更新（下载 → 长度/SHA256 双检 → 替换；全部在后台线程）。
+    pub(super) fn start_update_apply(&mut self) {
+        let Some(current) = self.update.current() else {
+            return;
+        };
+        let Some(job) = self.update.begin_apply() else {
+            return;
+        };
+        let channel = self.update.channel();
+        self.publish_update();
+        spawn_apply(job, current, channel, self.tx.clone());
+    }
+}
+
+/// 起一条检查线程（结果经 [`super::HostTask::Update`] 回来）。
+pub fn spawn_check(
+    job: unlucky_core::update::Job,
+    current: Version,
+    channel: Channel,
+    tx: super::JobSender,
+) {
+    super::job::spawn("update-check", move || {
+        let report = Report::Checked(outcome_of(job.check(¤t, channel)));
+        let _ = tx.send(super::HostTask::Update(Box::new(report)));
+    });
+}
+
+/// 起一条应用线程（下载 + 双检 + 替换都在里面）。
+pub fn spawn_apply(
+    job: unlucky_core::update::Job,
+    current: Version,
+    channel: Channel,
+    tx: super::JobSender,
+) {
+    super::job::spawn("update-apply", move || {
+        let report = Report::applied(job.apply(¤t, channel));
+        let _ = tx.send(super::HostTask::Update(Box::new(report)));
+    });
+}
+
+/// 当前时刻（毫秒 since UNIX_EPOCH；收据用）。
+fn now_ms() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|elapsed| u64::try_from(elapsed.as_millis()).unwrap_or(u64::MAX))
+        .unwrap_or(0)
+}
+
+#[cfg(test)]
+#[path = "update_tests.rs"]
+mod tests;
diff --git a/crates/presenter/src/host/update_tests.rs b/crates/presenter/src/host/update_tests.rs
new file mode 100644
index 0000000..50379af
--- /dev/null
+++ b/crates/presenter/src/host/update_tests.rs
@@ -0,0 +1,395 @@
+//! 自更新宿主通道的单测（M159）。
+//!
+//! 全部离线：清单与产物都在临时目录里造（[`Source::Dir`]），**没有一个用例发公网请求**。
+//! 覆盖 mission 的验收条目：
+//!
+//! | 用例 | 守什么 |
+//! |---|---|
+//! | [`version_matrix_decides_who_gets_prompted`] | 版本更高才提示；同版本/更低一律不提示；`v0.2.3` 这类真实 tag 形态 |
+//! | [`a_broken_manifest_degrades_to_failure_not_up_to_date`] | 坏 JSON → `invalid_*`、签名被拒 → `signature_*`；两种都是「检查失败」，**不是**「已是最新」 |
+//! | [`a_higher_version_without_our_platform_is_not_up_to_date`] | 有新版但没本平台产物 → 单独的变体 |
+//! | [`sha256_mismatch_refuses_the_apply_and_leaves_no_temp_file`] | 摘要不符拒绝应用、暂存文件不残留、目标没被换掉 |
+//! | [`a_successful_apply_leaves_the_new_file_and_a_backup`] | 换上去的是新字节、旧字节留在备份里、回报是「就位」 |
+//! | [`skipping_a_version_does_not_silence_the_next_one`] | 忽略的语义是**那一个版本**：同版本不再弹、更高版本照弹；手动检查清掉忽略 |
+//! | [`auto_check_off_means_no_request_on_start`] | 关掉开关后启动不派发检查（结构性 + 状态两层） |
+//! | [`the_gui_and_the_cli_share_one_kernel_path`] | GUI/CLI 走同一个 `Job`（源码锚点，不是口号） |
+
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+
+use unlucky_core::download::region::{RegionMode, RegionProfile};
+use unlucky_core::download::verify::digest_bytes;
+use unlucky_core::download::HashAlgo;
+use unlucky_core::update::{Applied, Channel, Target, Version};
+
+use crate::dto::{UpdateBanner, UpdateOutcome};
+
+use super::super::env::HostEnv;
+use super::super::update::{outcome_of, ApplyReport, Factory, Report};
+use super::Runtime;
+
+/// 一次性临时目录。
+struct TempDir {
+    path: PathBuf,
+}
+
+impl TempDir {
+    fn new(tag: &str) -> Self {
+        static COUNTER: AtomicU64 = AtomicU64::new(0);
+        let unique = COUNTER.fetch_add(1, Ordering::Relaxed);
+        let path =
+            std::env::temp_dir().join(format!("ull-m159-{}-{tag}-{unique}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&path);
+        std::fs::create_dir_all(&path).expect("建临时目录");
+        Self { path }
+    }
+
+    fn path(&self) -> &Path {
+        &self.path
+    }
+
+    fn join(&self, name: &str) -> PathBuf {
+        self.path.join(name)
+    }
+
+    fn write(&self, name: &str, bytes: &[u8]) -> PathBuf {
+        let path = self.join(name);
+        if let Some(parent) = path.parent() {
+            std::fs::create_dir_all(parent).expect("建父目录");
+        }
+        std::fs::write(&path, bytes).expect("写文件");
+        path
+    }
+}
+
+impl Drop for TempDir {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_dir_all(&self.path);
+    }
+}
+
+fn sha256(bytes: &[u8]) -> String {
+    digest_bytes(HashAlgo::Sha256, bytes)
+}
+
+/// 本平台在清单里的 `target` 写法。
+fn here() -> String {
+    Target::current().as_str().to_string()
+}
+
+/// 一份「本平台有产物」的清单（摘要按 `payload` 真实值算）。
+fn manifest_for(version: &str, payload: &[u8], notes: &str) -> String {
+    format!(
+        r#"{{"channel":"stable","releases":[{{"version":"{version}","channel":"stable","notes":"{notes}",
+        "artifacts":[{{"target":"{}","format":"portable-exe","url":"asset.exe","size":{},"sha256":"{}"}}]}}]}}"#,
+        here(),
+        payload.len(),
+        sha256(payload)
+    )
+}
+
+/// 测试签名钥的 32 字节种子。
+///
+/// **与 `crates/core/src/update/tests/support_sign.rs` 同源**（同一个种子、同一个 `key_id`、
+/// 同一个信封形状）：那边是 core 单测的夹具，这里是 presenter 侧的**等价薄夹具**——presenter 不能
+/// 依赖 core 的 `#[cfg(test)]` 资产，也不该把测试资产导出成生产 API。改一处就要改两处；
+/// 对不上时用例会以「签名验不过 / 不认识的钥」红，而不是静默变绿。
+const TEST_SIGNING_SEED: &[u8; 32] = b"ull-m190-test-key-seed-000000001";
+/// 测试钥的 `key_id`（与 `crates/core/src/update/trust.rs::TEST_ONLY` 一致）。
+const TEST_KEY_ID: &str = "test-only-key";
+
+/// 用测试钥给清单签一份 `manifest.sig` 信封（M190 的信封形状：多签名数组 + 冗余摘要）。
+///
+/// 只有 `[dev-dependencies]` 打开了 core 的 `update-test-key`，所以这把公开的测试公钥在**测试构建**
+/// 的信任表里；发布构建里没有它，也就装不了用公开种子签出来的清单。
+fn signature_envelope(manifest: &str) -> String {
+    use ed25519_dalek::{Signer, SigningKey};
+    let signature = SigningKey::from_bytes(TEST_SIGNING_SEED)
+        .sign(manifest.as_bytes())
+        .to_bytes();
+    let hex: String = signature.iter().map(|byte| format!("{byte:02x}")).collect();
+    let digest = sha256(manifest.as_bytes());
+    format!(
+        r#"{{"format":1,"signatures":[{{"alg":"ed25519","key_id":"{TEST_KEY_ID}","sig":"{hex}","manifest_sha256":"{digest}"}}]}}"#
+    )
+}
+
+/// 写一份清单**连它的签名**（`dist/stable.json` + `dist/stable.json.sig`）。
+///
+/// 真发布必须带 `.sig`（core 的 `verified_manifest` 先验签再解析），所以夹具一律成对落盘；
+/// 「坏清单」「空清单」这些用例也照签——它们要证的是「签名对、内容坏/为空」时的行为，
+/// 而不是绕过签名。
+fn write_manifest(tmp: &TempDir, manifest: &str) {
+    tmp.write("dist/stable.json", manifest.as_bytes());
+    tmp.write(
+        "dist/stable.json.sig",
+        signature_envelope(manifest).as_bytes(),
+    );
+}
+
+/// 造一个本地更新源目录（`dist/stable.json` + 它的签名 + `dist/asset.exe`）。
+fn dir_source(tmp: &TempDir, manifest: &str, payload: &[u8]) {
+    write_manifest(tmp, manifest);
+    tmp.write("dist/asset.exe", payload);
+}
+
+/// 造一份装配：本地源 + 临时目标 + 临时暂存。
+fn factory(tmp: &TempDir) -> Factory {
+    Factory::for_env(&HostEnv::at_root(tmp.join("root")))
+        .with_dir(tmp.join("dist"))
+        .with_dest(tmp.join("bin/unlucky-launcher.exe"))
+        .with_staging(tmp.join("staging"))
+}
+
+/// 一份 job（走同一份装配）。
+fn job(tmp: &TempDir) -> unlucky_core::update::Job {
+    factory(tmp).job()
+}
+
+fn version(text: &str) -> Version {
+    Version::parse(text).expect("合法版本")
+}
+
+// ------------------------------------------------------------------ 版本矩阵
+
+/// 版本更高才提示；同版本 / 更低一律不提示；真实 tag 形态（`v0.2.3`）照常解析。
+///
+/// 这条是 mission 第二条任务的核心判据，**判定本身在 core**（`UpdateChecker`），这里守的是
+/// 「host 把它翻成 DTO 之后仍然如此」——两处任何一处把 `<=` 写成 `<` 都会红。
+#[test]
+fn version_matrix_decides_who_gets_prompted() {
+    // (当前版本, 清单里的版本, 期望「有更新」)
+    let cases = [
+        ("0.2.2", "0.2.3", true),
+        ("0.2.2", "v0.2.3", true),
+        ("0.2.2", "0.2.2", false),
+        ("0.2.2", "v0.2.2", false),
+        ("0.2.2", "0.2.1", false),
+        ("0.2.2", "0.10.0", true),
+        ("0.2.2", "0.2.10", true),
+        ("0.2.2", "0.2.2-rc.1", false),
+        ("0.2.2-rc.1", "0.2.2", true),
+    ];
+    for (current, listed, expected) in cases {
+        let tmp = TempDir::new("matrix");
+        let payload = b"new";
+        dir_source(&tmp, &manifest_for(listed, payload, ""), payload);
+        let outcome = outcome_of(job(&tmp).check(&version(current), Channel::Stable));
+        assert_eq!(
+            outcome.candidate().is_some(),
+            expected,
+            "当前 {current} vs 清单 {listed}：期望 available={expected}，实际 {outcome:?}"
+        );
+        if !expected {
+            assert!(
+                matches!(outcome, UpdateOutcome::UpToDate { .. }),
+                "不提示的时候必须是「已是最新」，实际 {outcome:?}"
+            );
+        }
+    }
+}
+
+// ------------------------------------------------------------- 清单契约降级
+
+/// 坏 JSON / 缺字段 / 签名被拒 ⇒ **检查失败**，绝不是「已是最新」；而且两种坏法**分类不同**。
+///
+/// M199 复审 P3-2：旧版只断言「结果是 Failed」，而它喂的清单都**签对了**——验签一旦 fail-open，
+/// 坏签名清单会一路走到解析，坏 JSON 照样解析失败，断言全绿。现在内容坏必须落 `invalid_*`，
+/// 签名坏必须落 `signature_*` 且不可重试。
+/// 抓得住：验签被跳过/放行（② 会拿到 `Available 0.9.0`）、签名与解析互相误分类、失败被折叠成「已是最新」；
+/// 抓不住：签名信封字段与钥表（在 core 的 `signature_cases.rs`），以及 `manifest_sha256` 那条冗余校验
+/// （需「钥已钉住 + 方程验过 + 声明 sha 不同」，**全仓无用例**，已立 finding）。
+#[test]
+fn a_broken_manifest_degrades_to_failure_not_up_to_date() {
+    // ① 签名是对的（`write_manifest` 成对落盘），内容坏：分类只能是「清单结构 / 版本号不合法」。
+    for (label, manifest) in [
+        ("not json", "{ this is not json".to_string()),
+        (
+            "wrong field type",
+            r#"{"channel":"stable","releases":42}"#.to_string(),
+        ),
+        (
+            "bad digest",
+            format!(
+                r#"{{"channel":"stable","releases":[{{"version":"0.9.0","channel":"stable","artifacts":[{{"target":"{}","format":"portable-exe","url":"a.exe","size":3,"sha256":"zz"}}]}}]}}"#,
+                here()
+            ),
+        ),
+        (
+            "missing sha256",
+            format!(
+                r#"{{"channel":"stable","releases":[{{"version":"0.9.0","channel":"stable","artifacts":[{{"target":"{}","format":"portable-exe","url":"asset.exe","size":3}}]}}]}}"#,
+                here()
+            ),
+        ),
+        ("bad version", manifest_for("not-a-version", b"abc", "")),
+    ] {
+        let tmp = TempDir::new("badmanifest");
+        write_manifest(&tmp, &manifest);
+        let outcome = outcome_of(job(&tmp).check(&version("0.2.2"), Channel::Stable));
+        let Some(failure) = outcome.failure() else {
+            panic!("{label}：坏清单必须降级成「检查失败」，实际 {outcome:?}");
+        };
+        let kind = failure.kind.as_str();
+        assert!(
+            matches!(kind, "invalid_manifest" | "invalid_version"),
+            "{label}：坏内容分类是 {kind}"
+        );
+        assert!(!failure.message.trim().is_empty(), "{label}：失败没原因");
+    }
+    // ② 清单字节是好的（放行就会报「有更新 0.9.0」），只有签名对不上：必须落 `signature_invalid`。
+    let tmp = TempDir::new("badsignature");
+    tmp.write(
+        "dist/stable.json",
+        manifest_for("0.9.0", b"new", "").as_bytes(),
+    );
+    tmp.write(
+        "dist/stable.json.sig",
+        signature_envelope("another").as_bytes(),
+    );
+    let outcome = outcome_of(job(&tmp).check(&version("0.2.2"), Channel::Stable));
+    let Some(failure) = outcome.failure() else {
+        panic!("签名验不过必须拒装（放行就会报「有更新 0.9.0」），实际 {outcome:?}");
+    };
+    assert_eq!(failure.kind, "signature_invalid", "签名被拒的分类");
+    assert!(!failure.retryable, "签名问题不可重试");
+}
+
+/// 清单里**一条发布都没有**（`{"channel":"stable"}` / 空 `releases`）⇒ 已是最新，不是失败。
+///
+/// 这是 core 的既定口径（「该渠道还没发过版」不是错误），与上面那条「坏清单」要分得清清楚楚：
+/// 少一个字段是坏文件，空列表是「还没发」。两者都被报成同一种状态的话，发布脚本第一次上线
+/// 之前所有人都会看到红字。
+#[test]
+fn an_empty_manifest_means_nothing_published_yet() {
+    for manifest in [
+        r#"{"channel":"stable"}"#.to_string(),
+        r#"{"channel":"stable","releases":[]}"#.to_string(),
+    ] {
+        let tmp = TempDir::new("empty-manifest");
+        write_manifest(&tmp, &manifest);
+        let outcome = outcome_of(job(&tmp).check(&version("0.2.2"), Channel::Stable));
+        assert!(
+            matches!(&outcome, UpdateOutcome::UpToDate { latest: None }),
+            "空清单 = 还没发过版，实际 {outcome:?}"
+        );
+    }
+}
+
+/// 有更高的版本、但里面没有本平台的产物 ⇒ 单独的变体（不是「已是最新」，也不是「有更新」）。
+#[test]
+fn a_higher_version_without_our_platform_is_not_up_to_date() {
+    let tmp = TempDir::new("missing-artifact");
+    write_manifest(
+        &tmp,
+        &format!(
+            r#"{{"channel":"stable","releases":[{{"version":"0.9.0","channel":"stable","artifacts":[{{"target":"{}","format":"portable-exe","url":"asset.exe","size":3,"sha256":"{}"}}]}}]}}"#,
+            // 故意给一个不可能匹配本机的目标（`unknown` 架构永远对不上）
+            "linux-x86",
+            sha256(b"abc")
+        ),
+    );
+    let outcome = outcome_of(job(&tmp).check(&version("0.2.2"), Channel::Stable));
+    assert!(
+        matches!(&outcome, UpdateOutcome::MissingArtifact { version } if version == "0.9.0"),
+        "缺本平台产物要单独报出来，实际 {outcome:?}"
+    );
+    assert_eq!(outcome.as_str(), "missing_artifact");
+}
+
+// 两个子模块各守一段（拆开只为守 400 行硬线；夹具在本模块，子模块 `use super::*` 共用，
+// 不重复抄一份）。
+#[path = "update_apply_tests.rs"]
+mod apply;
+#[path = "update_session_tests.rs"]
+mod session;
+
+// ---------------------------------------------------------------- M165 复审 P2-1
+//
+// 这两条走的是**真实的命令路径**（`AppCommand::SetSetting` → `dispatch` → `settings::set`），
+// 不是直接调内部函数：要守的正是「动作路径上有没有把该做的事做全」。
+
+/// 「重新检测地区」之后，**自更新手里的引擎也要换**。
+///
+/// 自更新的 `Factory` 从 `CoreHost::build` 起就把引擎存在字段里（常驻到进程结束）；
+/// `download::shared::forget` 只让登记处不再持有那一份，**换不掉**它。于是只 forget 的话，
+/// 自更新会继续按**旧地区档案**展开候选，直到重启——M165 复审 P2-1 的那个洞。
+///
+/// 抓得住的变异：删掉 `host/dispatch.rs` 的 `SetSetting` 成功分支里那句
+/// `self.refresh_update_factory()` ⇒ 本用例红在 `Arc::ptr_eq`（Factory 还是淘汰前那一份）。
+#[test]
+fn detect_region_rebuilds_the_update_factory_engine() {
+    use std::sync::Arc;
+    use unlucky_core::download::shared;
+
+    let tmp = TempDir::new("region-refresh");
+    let env = HostEnv::at_root(tmp.path());
+    std::fs::create_dir_all(env.layout.cache()).expect("建缓存目录");
+    // 钉一份确定的地区档案：第一次构造不依赖本机时区/语言，断言才有确定的起点。
+    let region_path = env.layout.cache().join("region.json");
+    unlucky_core::download::region::store_cached(
+        ®ion_path,
+        &RegionProfile::pinned(RegionMode::Direct, unlucky_core::download::cache::now_ms()),
+    )
+    .expect("写 region.json");
+
+    let mut host = crate::host::CoreHost::headless(env.clone());
+    let cache_root = env.layout.cache();
+    assert_eq!(
+        shared::constructions(&cache_root),
+        1,
+        "装配时只该造一个引擎"
+    );
+    let before = host
+        .update
+        .factory_engine()
+        .expect("生产装配（Default）应有引擎")
+        .clone();
+    assert_eq!(before.region().mode, RegionMode::Direct);
+
+    host.dispatch_command(crate::dto::AppCommand::SetSetting {
+        key: "download.action.detect_region".to_string(),
+        value: String::new(),
+    });
+
+    let after = host
+        .update
+        .factory_engine()
+        .expect("重建后仍该有引擎")
+        .clone();
+    assert!(
+        !Arc::ptr_eq(&before, &after),
+        "「重新检测地区」必须换掉自更新用的引擎（否则它按旧地区档案跑到进程结束）"
+    );
+    assert!(
+        Arc::ptr_eq(&after, &crate::host::engine::engine(&env)),
+        "自更新必须指向登记处的当前引擎，而不是被淘汰的那一份"
+    );
+    assert_eq!(
+        shared::constructions(&cache_root),
+        2,
+        "淘汰一次 = 多构造一次（既不多也不少）"
+    );
+}
+
+/// 重建 `Factory` **不打断**在飞的检查/应用：在跑的那条 `Job` 派发时就已经把装配克隆走了。
+#[test]
+fn rebuilding_the_factory_does_not_touch_a_running_job() {
+    let tmp = TempDir::new("factory-rebuild");
+    dir_source(&tmp, &manifest_for("0.9.0", b"new", "notes"), b"new");
+    let env = HostEnv::at_root(tmp.path());
+    let mut runtime = Runtime::with_factory(&env, factory(&tmp));
+
+    // 派发一条（模拟「正在查」），再重建装配：
+    let job = runtime.begin_check(true).expect("应能派发");
+    assert!(runtime.inflight());
+    runtime.rebuild_factory(&env);
+    assert!(runtime.inflight(), "重建装配不该清掉在飞标记");
+    assert!(
+        matches!(runtime.view().outcome, UpdateOutcome::Checking),
+        "重建装配不该改状态快照"
+    );
+    // 在飞那条 Job 仍然可用（它拿着自己那份装配），能正常跑完并回报。
+    let outcome = outcome_of(job.check(&version("0.2.2"), Channel::Stable));
+    assert_eq!(outcome.as_str(), "available");
+}
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, 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 = 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..17fb0d7
--- /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` 用 |
+//! | [`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 侧自己造 `` 路径：路径只从 [`host::HostEnv`] / [`settings_bridge`] 拿。
+//!
+//! # 4. iced 接线的推荐用法（骨架，伪代码）
+//!
+//! ```ignore
+//! // 1) 启动：选后端（数据根解析不出来自动退回 mock）
+//! let backend: Box = build_backend(&AppOptions::default());
+//! let bridge = SettingsBridge::open();          // 读盘一次，主题/外观看这里
+//! let state = AppState::new();
+//!
+//! // 2) 订阅：iced 的 30fps 订阅里推进一拍
+//! fn subscription() -> Subscription { 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`
+// 等）。它们原本住在 `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,
+    /// 流式助手消息在 app 会话里的序号
+    message_index: usize,
+}
+
+/// 假后端。
+#[derive(Debug, Default)]
+pub struct MockBackend {
+    events: VecDeque,
+    launch: Option,
+    chat: Option,
+    /// 已投递给 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 {
+        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 {
+    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 {
+    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 {
+    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 {
+    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 {
+    match scenario {
+        "empty" => Vec::new(),
+        "running" => running(),
+        _ => mock_instances(),
+    }
+}
+
+/// 运行态矩阵：同一批实例换 runtime（名字/版本/加载器都还是 `mock_data` 那一份）。
+///
+/// 三种态各留一条，是为了**一屏看完**状态文案的三种形状：正在跑（`pid`）、启动中（百分比）、
+/// 启动失败（原因）。少一条就得再出一张图，而图多一张就多一处可以撒谎的地方。
+fn running() -> Vec {
+    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..b985977
--- /dev/null
+++ b/crates/presenter/src/mock_data.rs
@@ -0,0 +1,266 @@
+//! P0 假数据：实例 / 版本 / 日志 / 诊断 / 工具调用样例。
+//!
+//! 只被 [`crate::mock`] 与阶段 B 的 main.rs 使用；真实后端接入后整文件可删。
+
+use crate::dto::{
+    AncientKind, ChatMessage, ChatRole, Diagnosis, DiagnosisReport, InstanceRuntime,
+    InstanceSummary, LaunchArgsView, LoaderInfo, LoaderKind, LogLevel, LogLine, LogOutcome,
+    LogSession, SessionId, ToolCallView, VersionCategory, VersionKind, VersionSummary,
+};
+
+/// P0 演示实例：覆盖空闲 / 失败两种磁贴状态（运行中由启动脚本产生）。
+pub fn mock_instances() -> Vec {
+    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,
+            launch: mock_launch(),
+        },
+        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,
+            launch: mock_launch(),
+        },
+        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,
+            launch: mock_launch(),
+        },
+        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()),
+            // 静默失败 = **起来过**但 exit 0 没真正跑起来（不是「进程起不来」，见复审 P1-1）。
+            runtime: InstanceRuntime::Failed {
+                cause: crate::dto::LaunchFailureCause::SilentFailure { exit_code: Some(0) },
+            },
+            icon: None,
+            isolation: "isolated".to_string(),
+            version_id: "1.21.1-neoforge-21.1.72".to_string(),
+            version_present: true,
+            launch: mock_launch(),
+        },
+    ]
+}
+
+/// P0 演示版本列表（含远古版三子类，验证分类侧栏与警示徽标）。
+pub fn mock_versions() -> Vec {
+    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 {
+    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 {
+    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 {
+    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()
+}
+
+/// 演示用的启动参数视图（M157）：一条真实形状的实例（有 JVM 参数、Vulkan、门槛放行）。
+fn mock_launch() -> LaunchArgsView {
+    LaunchArgsView {
+        instance_id: "survival".to_string(),
+        jvm_args: "-XX:+UseG1GC".to_string(),
+        game_args: String::new(),
+        memory_mb: Some(4096),
+        memory_effective_mb: 4096,
+        java_path: String::new(),
+        java_effective: "C:/Java/temurin-21/bin/java.exe".to_string(),
+        graphics_backend: "vulkan".to_string(),
+        graphics_backend_effective: "vulkan".to_string(),
+        graphics_backend_allowed: true,
+        mc_version: "26.2-snapshot-2".to_string(),
+        graphics_backend_min_version: "26.2-snapshot-2".to_string(),
+        graphics_backend_options: vec![
+            "default".to_string(),
+            "opengl".to_string(),
+            "vulkan".to_string(),
+        ],
+    }
+}
+
+#[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..5441456
--- /dev/null
+++ b/crates/presenter/src/prefs.rs
@@ -0,0 +1,398 @@
+//! 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",
+];
+
+/// 强调色输入的**结构化失败原因**（M250 ACCENTWIRE）。
+///
+/// 为什么不是 `bool`：接线之后「填坏的串」必须能变成一条看得见的原因，回退成 `false` 只会让
+/// 用户再体验一次「保存成功、界面没变」。空串**不在这里**：空 = 出厂品牌板（合法取值）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum AccentError {
+    /// 去掉 `#` 后不足 6 位（`#12`、`#006A5`）。
+    Short {
+        /// 实际位数（原样报给用户，别把「6 位」写死在句子里）。
+        digits: usize,
+    },
+    /// 去掉 `#` 后超过 6 位（`#006A5C00`、粘了整行的串）。
+    Long {
+        /// 实际位数。
+        digits: usize,
+    },
+    /// 含非十六进制字符（`zzzzzz`）。
+    Digit {
+        /// 第一个不合法字符（比「格式不对」有用：用户能一眼看到错在哪个字符）。
+        ch: char,
+    },
+}
+
+/// 一次强调色输入的解析结果：`appearance.accent_color` 的**唯一**解析点（M250）：设置页输入框、
+/// 配置读回、出图取证开关都走它。少了 `#` 也接受（`006A5C` = `#006A5C`）——core 的 `normalize_hex`
+/// 同样接受，而 `ull config set appearance.accent_color 006A5C` 写出来的值必须能被界面吃下
+/// （否则 CLI 设的值会在设置页亮红行、颜色却是生效的）。输出一律规范化为大写 `#RRGGBB`。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum AccentChoice {
+    /// 空串 = 出厂品牌板（`DesignTokens::brand`）。**不是错误**。
+    Factory,
+    /// 合法的 `#RRGGBB`（大写、带 `#`）。
+    Custom(String),
+}
+
+impl AccentChoice {
+    /// 解析一段用户输入 / 配置值。
+    ///
+    /// # Errors
+    /// 位数不是 6 或含非十六进制字符时返回 [`AccentError`]；空串是 `Ok(Factory)`。
+    pub fn parse(text: &str) -> Result {
+        let trimmed = text.trim();
+        if trimmed.is_empty() {
+            return Ok(Self::Factory);
+        }
+        let body = trimmed.strip_prefix('#').unwrap_or(trimmed);
+        if let Some(ch) = body.chars().find(|ch| !ch.is_ascii_hexdigit()) {
+            return Err(AccentError::Digit { ch });
+        }
+        match body.chars().count() {
+            digits @ 0..=5 => Err(AccentError::Short { digits }),
+            6 => Ok(Self::Custom(format!("#{}", body.to_ascii_uppercase()))),
+            digits => Err(AccentError::Long { digits }),
+        }
+    }
+
+    /// 落盘字符串（`""` = 出厂；`#RRGGBB` = 自定义）。
+    #[must_use]
+    pub fn as_str(&self) -> &str {
+        match self {
+            Self::Factory => "",
+            Self::Custom(hex) => hex,
+        }
+    }
+}
+
+/// 磁贴尺寸（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` = 输入不合法、
+    /// 现状不变。需要**原因**时走 [`AppearancePrefs::set_accent_checked`]（设置页走那条）。
+    pub fn set_accent(&mut self, text: &str) -> bool {
+        self.set_accent_checked(text).is_ok()
+    }
+
+    /// 与 [`AppearancePrefs::set_accent`] 同一条路，但把结构化原因交出去。失败时**不动**
+    /// `accent_color`（保持上一次合法值）：非法串既不落盘、也不改生效色，只在 UI 上留一条原因。
+    ///
+    /// # Errors
+    /// 位数不是 6 或含非十六进制字符时返回 [`AccentError`]（见 [`AccentChoice::parse`]）。
+    pub fn set_accent_checked(&mut self, text: &str) -> Result<(), AccentError> {
+        let choice = AccentChoice::parse(text)?;
+        self.accent_color = choice.as_str().to_owned();
+        Ok(())
+    }
+
+    /// 用预设色板第 `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 {
+        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,
+}
+
+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..27ee8cb
--- /dev/null
+++ b/crates/presenter/src/settings_bridge.rs
@@ -0,0 +1,396 @@
+//! 设置持久化桥：把 UI 偏好落到 `core::setting` 的 schema 文件里，并支持**外部热改热切**。
+//!
+//! 三条纪律（`DevDocs/SubAgentsTalk/app-DTO通道约定.md` §6 / AGENTS §6）：
+//!
+//! 1. **不另立配置文件**：读写的就是 `ull config set/get` 与 AI `set_config` 用的那一份
+//!    `/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::Resolver;
+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};
+
+#[path = "settings_bridge/write.rs"]
+mod write;
+
+pub(crate) use write::Edit;
+
+/// 一次设置写回该落到哪份 `launcher.json`：数据根四键（`DATA_ROOT_KEYS`，判据只留
+/// `host::env` 那一份）→ 便携那份 `/.ULL/config/launcher.json`，启动解析读的就是它；
+/// 其余键 → `env_config`（解析后数据根那份）。
+///
+/// **写侧与读侧同源就是这一个函数**（M216 ①）：老代码在 Standard 模式下把 `core.data_mode`
+/// 写进 `%APPDATA%/ULL/config/launcher.json`，而下次启动只读 `/.ULL/…` 里的旧值 ⇒
+/// 切到 portable 后切不回来。CLI 的 `Ctx::setting_path_for` 早就是这个契约；`exe_dir = None`
+/// 时退回 `env_config`（不 panic、不丢写）。
+#[must_use]
+pub(crate) fn setting_path(env_config: &Path, exe_dir: Option<&Path>, key: &str) -> PathBuf {
+    match exe_dir {
+        Some(dir) if crate::host::env::DATA_ROOT_KEYS.contains(&key) => {
+            crate::host::env::portable_config_path(dir)
+        }
+        _ => env_config.to_path_buf(),
+    }
+}
+
+/// 设置文件桥（一个进程一份）。
+#[derive(Debug)]
+pub struct SettingsBridge {
+    /// `config/launcher.json`；`None` = 数据根解析不出来（内存态运行，不落盘）
+    pub(super) path: Option,
+    /// 设置文档（schema 校验 + 原子写的唯一入口）
+    pub(super) store: Option,
+    /// 上次读/写之后的文件 `mtime`（热切探测用）
+    pub(super) last_mtime: Option,
+}
+
+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) -> 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 卡住，诊断走日志）。
+    ///
+    /// **写走 [`SettingsBridge::write_with`]**（M174 r1/r2 复审）：本桥的 store 是长生命的
+    /// （启动时 load 一次），而 `SettingStore::save` 是**整份文档**落盘。不先重读就会拿「≤1 秒前
+    /// 的旧快照」整体覆盖文件：用户刚存下的 `ai.base_url` / `ai.model` / `ai.api_key` 会在下一秒
+    /// 被外观写回抹掉。现在「现读」这一步收在唯一写入口里，本函数只管改哪些键。
+    pub fn persist(&mut self, appearance: &AppearancePrefs, theme: ThemeMode) {
+        let _ = self.write_with(|store| {
+            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 Edit::Rejected;
+            }
+            Edit::Changed
+        });
+    }
+
+    /// 文件被外部（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` 跟随）。任何一步失败都退回内存态。
+///
+/// **M216 ①**：读这一步不再自带一份实现，直接用 [`crate::host::env::request_from_portable`]
+/// ——`HostEnv::resolve` 与 [`setting_path`] 读的也是它，于是「启动读到的」与「设置页写回的」
+/// 是同一份文件、同一段解析（presenter 侧原先两份逐字拷贝，现合一处）。
+fn resolve_config_path() -> Option {
+    let exe_dir = std::env::current_exe()
+        .ok()
+        .and_then(|path| path.parent().map(Path::to_path_buf))?;
+    let request = crate::host::env::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(crate::host::env::portable_config_path(&exe_dir)),
+    }
+}
+
+fn mtime(path: &Path) -> Option {
+    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
+    }
+
+    /// **M216 ①**：数据根四键的写回落点 = 启动解析读的那份文件。
+    ///
+    /// 抓得住：四键 → 便携那份、其余键 → 解析后那份、拿不到 exe 目录时退回。抓不住：真实
+    /// `current_exe()` 的取值与 `Resolver` 的 `redirect.json` 跟随（那两条靠 `set` 的回合用例）。
+    #[test]
+    fn data_root_keys_are_written_where_startup_reads_them() {
+        let exe = PathBuf::from("/games/ULL");
+        let portable = crate::host::env::portable_config_path(&exe);
+        let resolved = PathBuf::from("/appdata/ULL/config/launcher.json");
+        for key in crate::host::env::DATA_ROOT_KEYS {
+            assert_eq!(setting_path(&resolved, Some(&exe), key), portable, "{key}");
+        }
+        for key in ["java.default_memory_mb", "ai.model", "core.unknown_suffix"] {
+            assert_eq!(setting_path(&resolved, Some(&exe), key), resolved, "{key}");
+        }
+        // 拿不到 exe 目录：退回解析后那份（宁可写「没人读的那份」也不丢写、不 panic）。
+        assert_eq!(setting_path(&resolved, None, "core.data_mode"), resolved);
+    }
+
+    #[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 热切捕获");
+    }
+
+    /// **P2-4 回归**：外观写回不许盖掉别人刚写的键（`ai.api_key` 最贵）。修之前必红。
+    #[test]
+    fn persist_keeps_keys_another_writer_just_saved() {
+        let path = temp_config("persist-keeps-ai");
+        let mut bridge = SettingsBridge::with_path(&path);
+        // 先让本桥真的加载过一份文件（旧快照从这里来）。
+        bridge.persist(&AppearancePrefs::factory(), ThemeMode::Light);
+
+        {
+            use unlucky_core::setting::keys::launcher_schema;
+            use unlucky_core::setting::store::SettingStore;
+            // 另一个写者（M174 的助手设置页 / `ull config set`）写进三个 AI 键。
+            let mut store = SettingStore::load(&path, launcher_schema());
+            for (key, value) in [
+                ("ai.base_url", "https://api.deepseek.com/v1"),
+                ("ai.model", "deepseek-chat"),
+                ("ai.api_key", "sk-must-survive"),
+            ] {
+                store.set(key, value.to_string().into()).expect("写 AI 键");
+            }
+            store.save().expect("落盘");
+        }
+
+        // 同一秒内改主题：外观写回。
+        bridge.persist(&AppearancePrefs::factory(), ThemeMode::Dark);
+
+        let text = std::fs::read_to_string(&path).expect("读文件");
+        assert!(
+            text.contains("sk-must-survive"),
+            "外观写回把刚保存的密钥盖掉了：{text}"
+        );
+        assert!(text.contains("deepseek-chat"), "model 也被盖掉了：{text}");
+        assert!(text.contains("\"dark\""), "主题这一项该写进去：{text}");
+        std::fs::remove_dir_all(path.parent().unwrap().parent().unwrap()).ok();
+    }
+
+    #[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/write.rs b/crates/presenter/src/settings_bridge/write.rs
new file mode 100644
index 0000000..528ced9
--- /dev/null
+++ b/crates/presenter/src/settings_bridge/write.rs
@@ -0,0 +1,90 @@
+//! 设置桥的**唯一写入口**（M174 r2 复审 P2-1）。
+//!
+//! ## 为什么要把「写」收敛成一处
+//!
+//! [`SettingsBridge`] 的 store 是**长生命**的（启动时 `SettingStore::load` 一次，之后只读），
+//! 而 `SettingStore::save` 写的是**整份文档**（`core::setting::store` 的 `write_document`
+//! 序列化 `doc.to_value()`，不是脏字段补丁）。于是任何「拿旧快照直接 save」的入口都会把别人
+//! 刚写进文件的键整片抹掉：
+//!
+//! | 轮次 | 入口 | 现象 |
+//! |---|---|---|
+//! | r1 | [`SettingsBridge::persist`]（外观/主题） | 保存 AI 配置后 1 秒内改主题 ⇒ `ai.*` 连密钥一起消失 |
+//! | r2 | `persist_ui_language`（界面语言） | 保存 AI 配置后 1 秒内在同一页切成 English ⇒ 同样消失，而且函数**返回 true**（静默） |
+//!
+//! 两轮都是「同一类缺陷隔一个文件复发一次」。所以写这件事只留 [`SettingsBridge::write_with`]
+//! 一个出口：**现读 → 改 → 落盘 → 刷 mtime**，新入口只能传闭包，忘不了 `reload()`。
+//!
+//! ## 为什么返回 [`WriteOutcome`] 而不是 `bool`
+//!
+//! 「没写」有三种原因（内存态 / 没有改动 / 被 schema 只读闸门拦下 / 写盘失败），调用方要能分清：
+//! 语言入口要回答「真的落盘了吗」（旧版把 `Skipped` 也当成功），诊断要能说出原因。
+
+use unlucky_core::setting::store::{SaveOutcome, SettingStore, SkipReason};
+
+use super::{mtime, SettingsBridge};
+
+/// 闭包对文档做的事。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum Edit {
+    /// 文档改过了（需要落盘）。
+    Changed,
+    /// 没有可改的（幂等路径）：不落盘，也不算失败。
+    Unchanged,
+    /// 改不动（`store.set` 被 schema / 只读闸门拒绝）。
+    Rejected,
+}
+
+/// 一次写的结果（`Skipped` 的载荷给诊断用；界面只关心 [`WriteOutcome::is_saved`]）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum WriteOutcome {
+    /// 数据根解析不出来（内存态桥）：什么都没写。
+    NoStorage,
+    /// 闭包说没有改动：没落盘。
+    Unchanged,
+    /// 真的写进磁盘了。
+    Saved,
+    /// `save()` 跳过了（只读 / 不可信文件 / 没有脏键）。
+    Skipped(SkipReason),
+    /// 写盘报错（序列化 / 备份 / IO）。
+    Failed,
+}
+
+impl WriteOutcome {
+    /// 磁盘上真的有新内容吗（**只有这一档算成功**）。
+    #[must_use]
+    pub(crate) const fn is_saved(self) -> bool {
+        matches!(self, Self::Saved)
+    }
+}
+
+impl SettingsBridge {
+    /// 长生命 store 的**唯一写入口**：现读 → 改 → 落盘 → 刷 mtime。
+    ///
+    /// `edit` 拿到的 `&mut SettingStore` **已经是刚从磁盘重读的那一份**（这一句就是 r1/r2 两个
+    /// 缺陷的修法：任何入口都不许拿启动时的旧快照整份覆盖）。
+    pub(crate) fn write_with(&mut self, edit: F) -> WriteOutcome
+    where
+        F: FnOnce(&mut SettingStore) -> Edit,
+    {
+        let Some(store) = self.store.as_mut() else {
+            return WriteOutcome::NoStorage;
+        };
+        // ← 这一行是两轮复审的修复本体。
+        store.reload();
+        match edit(store) {
+            Edit::Changed => {}
+            Edit::Unchanged => return WriteOutcome::Unchanged,
+            Edit::Rejected => return WriteOutcome::Failed,
+        }
+        let outcome = match store.save() {
+            Ok(SaveOutcome::Saved(_)) => WriteOutcome::Saved,
+            Ok(SaveOutcome::Skipped(reason)) => WriteOutcome::Skipped(reason),
+            Err(_) => WriteOutcome::Failed,
+        };
+        if let Some(path) = self.path() {
+            self.last_mtime = mtime(path);
+        }
+        outcome
+    }
+}
diff --git a/crates/presenter/src/settings_bridge_lang.rs b/crates/presenter/src/settings_bridge_lang.rs
new file mode 100644
index 0000000..b1bb957
--- /dev/null
+++ b/crates/presenter/src/settings_bridge_lang.rs
@@ -0,0 +1,241 @@
+//! 界面语言这一个键的读写（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::{Edit, 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 {
+        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 卡住）。写法走 [`SettingsBridge::write_with`]（M174 r2 复审 P2-1）：与外观写回同一个
+    /// 唯一出口，**入口自己不再碰 `store.save()`**——r1 修了外观那条、这一条漏着，于是「保存 AI
+    /// 配置后 1 秒内切界面语言」照样把 `ai.*` 连密钥一起抹掉，而且本函数还返回 `true`。
+    ///
+    /// 为什么不自己 `store.reload()` 了事：这是**同一类缺陷的第二个入口**（第一个是
+    /// [`SettingsBridge::persist`]）。收敛成 `write_with` 之后，下一个写入口在类型上就拿不到
+    /// 「不重读的 save」——而不是靠每个人记得。
+    pub fn persist_ui_language(&mut self, value: Option<&str>) -> bool {
+        let outcome = self.write_with(|store| match value {
+            Some(language) => {
+                if store
+                    .set(UI_LANGUAGE, serde_json::Value::String(language.to_owned()))
+                    .is_err()
+                {
+                    return Edit::Rejected;
+                }
+                Edit::Changed
+            }
+            // 「跟随系统」= 删键：`SettingDocument` 没有 remove API，而落盘写的是全量视图，所以
+            // 把全量视图里的那个键去掉再 load 回一份文档就等价于删键（用户手写的未知键原样带回）。
+            None => {
+                if store.doc().get(UI_LANGUAGE).is_none() {
+                    return Edit::Unchanged;
+                }
+                if remove_ui_language(store) {
+                    Edit::Changed
+                } else {
+                    Edit::Unchanged
+                }
+            }
+        });
+        outcome.is_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
+    }
+
+    /// **P2-1（r2）的回归**：语言写回不许盖掉别人刚写的键。
+    ///
+    /// 现场（复审探针 `rev2_ai_keys_survive_a_language_write`）：保存 AI 配置后 1 秒内在同一页把
+    /// 界面语言切成 English ⇒ `persist_ui_language` 拿旧快照整份覆盖 ⇒ 文件里只剩 `appearance` +
+    /// `ui`，`ai` 整段消失，而本函数**返回 true**。
+    ///
+    /// 抓得住：`write_with` 少了 `store.reload()`（或某个入口又自己 `store.save()` 绕过它）。
+    #[test]
+    fn persisting_the_language_keeps_keys_another_writer_just_saved() {
+        let path = temp_config("lang-keeps-ai");
+        let mut bridge = SettingsBridge::with_path(&path);
+        // 先让本桥真的加载过一次文件（长生命 store 的旧快照从这里来）。
+        bridge.persist(
+            &crate::prefs::AppearancePrefs::factory(),
+            crate::prefs::ThemeMode::Light,
+        );
+
+        // 另一个写者（M174 的助手设置页）写进三个 AI 键。
+        {
+            use unlucky_core::setting::keys::launcher_schema;
+            use unlucky_core::setting::store::SettingStore;
+            let mut store = SettingStore::load(&path, launcher_schema());
+            for (key, value) in [
+                ("ai.base_url", "https://api.deepseek.com/v1"),
+                ("ai.model", "deepseek-chat"),
+                ("ai.api_key", "sk-must-survive-lang"),
+            ] {
+                store.set(key, value.to_string().into()).expect("写 AI 键");
+            }
+            store.save().expect("落盘");
+        }
+
+        // 同一秒内切界面语言（语言入口写回它那份整文档）。
+        assert!(
+            bridge.persist_ui_language(Some("en_us")),
+            "语言这一项该写进去"
+        );
+
+        let text = std::fs::read_to_string(&path).expect("读文件");
+        assert!(
+            text.contains("sk-must-survive-lang"),
+            "语言写回把刚保存的密钥盖掉了：{text}"
+        );
+        assert!(text.contains("deepseek-chat"), "模型名也被盖掉了：{text}");
+        assert!(text.contains("\"en_us\""), "语言这一项该写进去：{text}");
+        std::fs::remove_dir_all(path.parent().unwrap().parent().unwrap()).ok();
+    }
+
+    /// 「真的落盘了吗」不许撒谎：只读文件（`$schema` 认不出 ⇒ `FileAccess::ReadOnly`）上
+    /// `persist_ui_language` 必须是 `false`。
+    #[test]
+    fn persisting_the_language_reports_false_when_the_file_is_read_only() {
+        let path = temp_config("lang-read-only");
+        // `Invalid` 兼容档 ⇒ 只读：值照读，但不许被我们改写。
+        std::fs::write(
+            &path,
+            r#"{"$schema":"https://example.invalid/ull/launcher/9.9.9","ui":{"language":"zh_cn"}}"#,
+        )
+        .expect("写配置");
+        let before = std::fs::read_to_string(&path).expect("读配置");
+
+        let mut bridge = SettingsBridge::with_path(&path);
+        assert_eq!(
+            bridge.load_ui_language().as_deref(),
+            Some("zh_cn"),
+            "值照读"
+        );
+        assert!(
+            !bridge.persist_ui_language(Some("en_us")),
+            "只读文件上写成功是谎话"
+        );
+        assert_eq!(
+            std::fs::read_to_string(&path).expect("读配置"),
+            before,
+            "被只读闸门拦下的写不许改动文件"
+        );
+        std::fs::remove_dir_all(path.parent().unwrap().parent().unwrap()).ok();
+    }
+
+    /// 抓得住：①把 `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..ce16277
--- /dev/null
+++ b/crates/presenter/src/state.rs
@@ -0,0 +1,382 @@
+//! 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,
+    AdoptState,
+    AppEvent,
+    AuthlibLoginView,
+    CoreEvent,
+    DeviceLoginView,
+    DiagnosisReport,
+    InstallProgressView,
+    InstanceRuntime,
+    InstanceSummary,
+    JavaPageView,
+    LaunchFinished,
+    LoaderKind,
+    LogLine,
+    LogSession,
+    NoticeView,
+    PackState,
+    Progress,
+    SettingGroupView,
+    UpdateView,
+    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;
+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;
+// M223：AI 栏的事件投递与可见性（纯搬移，守 400 行硬线）
+mod agent;
+mod live;
+// M224: 本地 Mod 列表与启停的视图态（状态落地 + 在飞标记）
+mod mods;
+// M235: 实例存档 / 截图的只读快照（状态落地 + 迟到丢弃）
+mod saves;
+mod tiles;
+
+pub use live::MAX_LIVE_LINES;
+pub use mods::ModsState;
+pub use saves::{RenameDraft, SavesOp, SavesState};
+pub use tiles::{grid_positions, TileCell};
+
+/// 一份加载器版本清单查询的结果（`Ok` = 最新在前；`Err` = 人读原因）。
+pub type LoaderVersions = Result, String>;
+
+/// 应用全局状态。
+#[derive(Debug)]
+pub struct AppState {
+    /// UI 偏好（记忆项）
+    pub prefs: UiPrefs,
+    /// 导航栈
+    pub router: Router,
+    /// 实例列表快照
+    pub instances: Vec,
+    /// 当前分类的版本列表
+    pub versions: Vec,
+    /// 日志会话列表
+    pub log_sessions: Vec,
+    /// 当前会话日志行
+    pub log_lines: Vec,
+    /// 最近一次诊断结论
+    pub diagnosis: Option,
+    /// 选中的日志会话
+    pub selected_session: Option,
+    /// 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,
+    /// 微软登录状态
+    pub device_login: DeviceLoginView,
+    /// 第三方轨（authlib-injector）登录/校验状态
+    pub authlib_login: AuthlibLoginView,
+    /// 设备码等待态的开始时刻（倒计时；`None` = 没有在等）
+    pub device_login_started: Option,
+    /// 账户页横幅（一次性操作结果；页面渲染后由用户关掉）
+    pub account_notice: Option,
+    /// Java 页快照（发行版 / 回退链 / 运行时）
+    pub java: JavaPageView,
+    /// 安装进度（None = 没有安装任务）
+    pub install: Option,
+    /// 用户取消安装的**次数**（M105）：每次 `CoreEvent::InstallCancelled` +1。
+    ///
+    /// 只是信号，不带文案：app 层比对前后值决定「要不要弹一条 i18n Toast」，
+    /// 于是取消提示和页面用同一种语言（复审 P2-2）。
+    pub install_cancelled: u64,
+    /// 启动收尾次数（M161，每次 `LaunchFinished` +1）：与 `install_cancelled` 同一条纪律——
+    /// presenter 只发信号，文案由 app 层按 i18n key 现求。
+    pub launch_ends: u64,
+    /// 最近一次启动收尾的结构（结局 + 退出码 + 失败阶段；文案在 app 层求）。
+    pub last_launch_end: Option>,
+    /// 加载器版本清单（下载页「安装选项」的下拉；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>,
+    /// 设置分组（设置页右栏）
+    pub settings_groups: Vec,
+    /// 当前选中的设置分组（download / java / data / ai / mcp）
+    pub settings_tab: String,
+    /// 横幅通知
+    pub notices: Vec,
+    /// 自更新（M159）：检查结论 / 就位状态 / 是否已拒绝（提示条与设置页共用）
+    pub update: UpdateView,
+    /// 新建实例向导
+    pub wizard: WizardState,
+    /// 正在实时尾随的会话
+    pub live_session: Option,
+    /// 内容库（M109）：条件 / 结果 / 请求态
+    pub content: ContentState,
+    /// 整合包导入/导出：进度 / 结果 / 探测诊断 / 导出预检（M113）
+    pub pack: PackState,
+    /// 导入已有版本（M223）：扫描 / 预检 / 失败 / 完成（**只装事件态**，表单在页面本地态）
+    pub adopt: AdoptState,
+    /// 本地 Mod（M224）：当前实例的快照 / 失败 / 在飞启停
+    pub mods: ModsState,
+    /// 实例存档 / 截图（M235）：当前实例的只读快照 / 失败（可重试）
+    pub saves: SavesState,
+}
+
+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,
+            launch_ends: 0,
+            last_launch_end: None,
+            loader_versions: std::collections::HashMap::new(),
+            settings_groups: Vec::new(),
+            settings_tab: "download".to_string(),
+            notices: Vec::new(),
+            update: UpdateView::default(),
+            wizard: WizardState::new(),
+            live_session: None,
+            content: ContentState::default(),
+            pack: PackState::default(),
+            adopt: AdoptState::default(),
+            mods: ModsState::default(),
+            saves: SavesState::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());
+                // **不在这里拼文案**（M161）：presenter 不依赖 `unlucky-i18n`，写死的中文会在
+                // 英文界面上弹出来。这里只记「又收尾了一场」，Toast 由 app 层按 key 现求
+                // （与 `install_cancelled` 同一条纪律，见 `app/state/refresh.rs`）。
+                self.launch_ends = self.launch_ends.saturating_add(1);
+                self.last_launch_end = Some(Box::new(finished));
+            }
+            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,
+            CoreEvent::Update(view) => self.update = *view,
+            // M113: import/export
+            CoreEvent::Pack(event) => self.pack.apply(*event),
+            // M223: 导入已有版本（唯一写入点：`AdoptState::apply`）
+            CoreEvent::Adopt(event) => self.adopt.apply(*event),
+            CoreEvent::ContentResults(results) => self.apply_content(*results),
+            CoreEvent::ContentFailed(failure) => self.apply_content_failure(*failure),
+            // M162：详情/版本列表（判断逻辑在 `state/content.rs`，这里只有一行投递）
+            CoreEvent::ContentDetail { project, result } => {
+                self.apply_content_detail(&project, *result)
+            }
+            // M224：本地 Mod（落地判据在 `state/mods.rs`，含迟到丢弃与在飞标记）
+            CoreEvent::Mods(result) => self.mods.apply(*result),
+            // M235：实例存档 / 截图（落地判据在 `state/saves.rs`，含迟到丢弃）
+            CoreEvent::Saves(result) => self.saves.apply(*result),
+        }
+    }
+
+    /// 运行中的实例（实例页顶部迷你状态条）。
+    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 {
+        self.device_code_remaining_at(Instant::now())
+    }
+
+    /// [`Self::device_code_remaining`] 的可注入时钟版本（单测用）。
+    pub fn device_code_remaining_at(&self, now: Instant) -> Option {
+        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/agent.rs b/crates/presenter/src/state/agent.rs
new file mode 100644
index 0000000..8392325
--- /dev/null
+++ b/crates/presenter/src/state/agent.rs
@@ -0,0 +1,39 @@
+//! AI 栏的事件投递与可见性判定（M223 从 `state.rs` **纯搬移**，一行未改）。
+//!
+//! 为什么搬：M223 要往 `AppState` 加「导入已有版本」的状态字段与一条 `CoreEvent::Adopt` 分支，
+//! 而 `state.rs` 当时正好 400 行（零余量，AGENTS §3.9）。拆分口径与 [`super::tiles`] 一致：
+//! **纯搬移、一行不改**；`impl AppState` 写在子模块里，方法路径
+//! `AppState::apply_agent` / `AppState::agent_rail_visible` 对调用方完全不变
+//! （子模块看得见父模块的私有字段，所以这里直接用 `self.ai` / `self.prefs`）。
+
+use crate::dto::AgentEvent;
+use crate::router::AiPanelMode;
+
+use super::AppState;
+
+impl AppState {
+    /// 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
+    }
+}
diff --git a/crates/presenter/src/state/content.rs b/crates/presenter/src/state/content.rs
new file mode 100644
index 0000000..8fb6522
--- /dev/null
+++ b/crates/presenter/src/state/content.rs
@@ -0,0 +1,64 @@
+//! 内容库的状态机（M109）：结果落地与条件提交两件事。
+//!
+//! 从 `state.rs` 拆出（那个文件重新合流 M105 之后贴着 400 行上限）。放在 `impl AppState` 的
+//! **另一个 impl 块**里，路径与可见性都不变：`apply_core` 直接调 `self.apply_content(..)`。
+
+use crate::dto::{ContentDetail, ContentFailure, 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),
+        }
+    }
+
+    /// 检索失败落地（M162 起带大类）：清掉「在飞」并记下失败。
+    pub(super) fn apply_content_failure(&mut self, failure: ContentFailure) {
+        self.content.pending = false;
+        self.content.failed = Some(failure);
+    }
+
+    /// 详情事件落地（M162）：`Ok` 走 `apply_detail`、`Err` 走 `fail_detail`，两者都按
+    /// **请求时的项目 id** 判迟到（用户可能已经切到别的项目了）。
+    pub(super) fn apply_content_detail(
+        &mut self,
+        project: &str,
+        result: Result,
+    ) {
+        match result {
+            Ok(detail) => self.content.apply_detail(project, detail),
+            Err(failure) => self.content.fail_detail(project, failure),
+        }
+    }
+
+    /// 记下新的检索条件并进入「请求在飞」态（指令由调用方随后 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..9755758
--- /dev/null
+++ b/crates/presenter/src/state/content_tests.rs
@@ -0,0 +1,244 @@
+//! 内容库状态机的守门测试（M109；复审 P1-2 的补课）。
+//!
+//! 从 `state.rs` 拆出（那个文件贴 400 行硬上限）。钉的是**翻页判据**：
+//! `has_more` 必须读「最近一页是否装满」，不能读累计条数——否则第 2 页之后恒真。
+
+use crate::dto::{
+    AppEvent, ContentDetail, ContentFailure, ContentFailureKind, ContentHit, ContentKind,
+    ContentQuery, ContentResults, ContentSource, ContentVersionView, 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(), "迟到的一批被丢掉");
+}
+
+// ------------------------------------------------ M162：失败大类与详情通道
+
+/// 事件 → 状态：`ContentFailed` 带大类，没联网时 `is_offline()` 为真（页面据此画离线态）。
+#[test]
+fn a_content_failure_keeps_its_kind() {
+    let mut state = AppState::new();
+    state.set_content_query(ContentQuery::first(ContentKind::Mod));
+    state.apply_core(CoreEvent::ContentFailed(Box::new(ContentFailure::offline(
+        "connect timed out",
+    ))));
+    let failure = state.content.failed.as_ref().expect("要记住失败");
+    assert!(failure.is_offline(), "没联网必须能被页面认出来");
+    assert!(!state.content.pending);
+
+    state.apply_core(CoreEvent::ContentFailed(Box::new(ContentFailure::new(
+        ContentFailureKind::Server,
+        "HTTP 503",
+    ))));
+    let failure = state.content.failed.as_ref().expect("要记住失败");
+    assert!(!failure.is_offline(), "站点 5xx 不是「没联网」");
+}
+
+/// 详情通道：请求态 → 结果态；换项目时旧详情先清掉。
+#[test]
+fn the_detail_channel_replaces_the_previous_project() {
+    let mut state = AppState::new();
+    state.content.request_detail("p1");
+    assert!(state.content.detail_pending);
+    state.apply_core(CoreEvent::ContentDetail {
+        project: "p1".to_string(),
+        result: Box::new(Ok(detail("p1"))),
+    });
+    assert!(!state.content.detail_pending);
+    assert_eq!(
+        state.content.detail.as_ref().map(|d| d.project.as_str()),
+        Some("p1")
+    );
+
+    state.content.request_detail("p2");
+    assert!(
+        state.content.detail.is_none(),
+        "换了项目就不能留着上一个的版本列表"
+    );
+    state.apply_core(CoreEvent::ContentDetail {
+        project: "p2".to_string(),
+        result: Box::new(Err(ContentFailure::offline("connect timed out"))),
+    });
+    assert!(state
+        .content
+        .detail_failed
+        .as_ref()
+        .is_some_and(ContentFailure::is_offline));
+}
+
+fn detail(project: &str) -> ContentDetail {
+    ContentDetail {
+        project: project.to_string(),
+        title: "Sodium".to_string(),
+        description: "fast".to_string(),
+        body: String::new(),
+        versions: vec![ContentVersionView {
+            id: "v1".to_string(),
+            name: "Sodium 0.6.0".to_string(),
+            number: "mc1.20.1-0.6.0".to_string(),
+            kind: "release".to_string(),
+            game_versions: vec!["1.20.1".to_string()],
+            loaders: vec!["fabric".to_string()],
+            published: "2026-02-01T00:00:00Z".to_string(),
+            file_name: Some("sodium.jar".to_string()),
+            file_size: Some(2048),
+        }],
+    }
+}
+
+/// r1 P2-3：迟到的详情结果（A）不许写进 B 的请求/面板。
+#[test]
+fn a_late_detail_result_for_the_previous_project_is_dropped() {
+    let mut state = AppState::new();
+    state.content.request_detail("p1");
+    // 用户立刻切到 p2：新的请求在飞
+    state.content.request_detail("p2");
+    // p1 的失败这时才回来
+    state.apply_core(CoreEvent::ContentDetail {
+        project: "p1".to_string(),
+        result: Box::new(Err(ContentFailure::offline("connect timed out"))),
+    });
+    assert!(
+        state.content.detail_failed.is_none(),
+        "A 的失败不许画在 B 的面板上"
+    );
+    assert!(state.content.detail_pending, "B 仍应在飞");
+    assert_eq!(state.content.detail_requested.as_deref(), Some("p2"));
+
+    // p1 的成功结果同样被丢掉（哪怕载荷里写着 p1）
+    state.apply_core(CoreEvent::ContentDetail {
+        project: "p1".to_string(),
+        result: Box::new(Ok(detail("p1"))),
+    });
+    assert!(state.content.detail.is_none());
+    assert!(state.content.detail_pending);
+
+    // 真正属于 B 的结果才落地
+    state.apply_core(CoreEvent::ContentDetail {
+        project: "p2".to_string(),
+        result: Box::new(Ok(detail("p2"))),
+    });
+    assert!(!state.content.detail_pending);
+    assert_eq!(
+        state.content.detail.as_ref().map(|d| d.project.as_str()),
+        Some("p2")
+    );
+}
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/mods.rs b/crates/presenter/src/state/mods.rs
new file mode 100644
index 0000000..c55cb67
--- /dev/null
+++ b/crates/presenter/src/state/mods.rs
@@ -0,0 +1,188 @@
+//! 本地 Mod 的快照落地与「请求在飞」标记（M224 · MODTOGGLE）。
+//!
+//! 从 `state.rs` 拆出（那个文件正好贴着 400 行硬线），形状与 [`super::accounts`] / [`super::live`]
+//! 一致：**另一个 `impl AppState` 块**，路径与可见性都不变，`apply_core` 只有一行投递。
+//!
+//! # 为什么快照住在这里而不是页面
+//!
+//! 「列表画的永远是磁盘上的真相」是本模块唯一要保证的事，所以：
+//!
+//! - 快照走 [`crate::dto::CoreEvent::Mods`] 的 `Ok` 一支，**整体替换**（不做增量合并）——host 每次
+//!   都是重新扫一遍目录才发的，合并只会两处真相；
+//! - 失败走同一个事件的 `Err` 一支，记下一条**具名原因**，页面按 i18n key 现求文案
+//!   （presenter 不拼句子，M161 纪律）；
+//! - [`ModsState::pending`] 是**页面交互态**（哪个文件的请求在飞），只用来把那个开关先置灰
+//!   ——**不做乐观翻面**：`view` 里的 `enabled` 只跟磁盘快照走。
+//!
+//! # 迟到结果
+//!
+//! 启停是「后台线程 + 快照回来」：用户很可能点完就切到别的实例。所以 `view.instance` 与
+//! [`ModsState::bound`] 不一致的结果**直接丢掉**（与内容库按 request id 判迟到同一条纪律）——
+//! 否则 A 的列表会被 B 的启停结果顶掉。
+
+use std::collections::BTreeSet;
+
+use crate::dto::{ModFailureView, ModListView};
+
+use super::AppState;
+
+/// 本地 Mod 的视图态。
+#[derive(Debug, Clone, Default, PartialEq)]
+pub struct ModsState {
+    /// 当前详情页的实例 id（`None` = 不在详情页）。
+    pub bound: Option,
+    /// 最近一份快照（`None` = 还没请求过）。
+    pub view: Option,
+    /// 最近一条失败（具名原因；成功一次就清掉）。
+    pub failed: Option,
+    /// 正在飞的启停请求（磁盘文件名，含后缀）。
+    pub pending: BTreeSet,
+}
+
+impl ModsState {
+    /// 切到另一个实例（换实例必须清空：A 的列表不能画在 B 的详情页上）。
+    pub(super) fn bind(&mut self, instance: Option<&str>) {
+        if self.bound.as_deref() == instance {
+            return;
+        }
+        self.bound = instance.map(str::to_string);
+        self.view = None;
+        self.failed = None;
+        self.pending.clear();
+    }
+
+    /// 一条结果落地（`Ok` = 快照整体替换，`Err` = 记一条具名失败；迟到/串台的丢掉）。
+    pub fn apply(&mut self, result: Result) {
+        match result {
+            Ok(view) => self.changed(view),
+            Err(failure) => self.failed(failure),
+        }
+    }
+
+    /// 列表快照落地（整体替换；迟到/串台的丢掉）。
+    pub fn changed(&mut self, view: ModListView) {
+        if self.bound.as_deref() != Some(view.instance.as_str()) {
+            return;
+        }
+        // 这一批结果回来了 ⇒ 那个文件的"在飞"标记可以撤（不管成没成，另一条事件会说）。
+        self.pending.clear();
+        self.failed = None;
+        self.view = Some(view);
+    }
+
+    /// 失败落地（只记**当前绑定实例**的；列表那一份保留——用户还能看见旧列表，只是多一条红字）。
+    pub fn failed(&mut self, failure: ModFailureView) {
+        if self.bound.as_deref() != Some(failure.instance.as_str()) {
+            return;
+        }
+        self.pending.clear();
+        self.failed = Some(failure);
+    }
+
+    /// 标一个文件"请求在飞"（UI 把那个开关置灰，不做乐观翻面）。
+    pub fn mark_pending(&mut self, file: &str) {
+        self.pending.insert(file.to_string());
+    }
+
+    /// 某个文件的请求是否在飞。
+    #[must_use]
+    pub fn is_pending(&self, file: &str) -> bool {
+        self.pending.contains(file)
+    }
+
+    /// 当前绑定实例的列表是否已经有一份快照。
+    #[must_use]
+    pub fn has_view(&self) -> bool {
+        self.view.is_some()
+    }
+}
+
+impl AppState {
+    /// 进/出详情页时对齐绑定（`refresh_view` 调；与 `LaunchForm::sync` 同一处生命周期）。
+    pub fn bind_mods(&mut self, instance: Option<&str>) {
+        self.mods.bind(instance);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::dto::{ModEntryView, ModFailureKind};
+
+    fn view(instance: &str) -> ModListView {
+        ModListView {
+            instance: instance.to_string(),
+            dir: "C:/mc/mods".to_string(),
+            exists: true,
+            entries: vec![ModEntryView {
+                file: "x.jar".to_string(),
+                name: "x.jar".to_string(),
+                enabled: true,
+                bytes: 1,
+                old: false,
+            }],
+            skipped: Vec::new(),
+            running: false,
+            known: true,
+        }
+    }
+
+    fn failure(instance: &str) -> ModFailureView {
+        ModFailureView {
+            instance: instance.to_string(),
+            file: "x.jar".to_string(),
+            kind: ModFailureKind::Collision,
+            detail: "exists".to_string(),
+        }
+    }
+
+    /// 换实例必须清空（A 的列表不许画在 B 的详情页上）。
+    #[test]
+    fn binding_another_instance_drops_the_old_view() {
+        let mut mods = ModsState::default();
+        mods.bind(Some("a"));
+        mods.changed(view("a"));
+        assert!(mods.has_view());
+
+        mods.bind(Some("b"));
+        assert!(!mods.has_view(), "换实例后还留着 A 的列表");
+        assert_eq!(mods.bound.as_deref(), Some("b"));
+
+        // 同一个实例再 bind 一次不该清（`refresh_view` 每帧都调）。
+        mods.changed(view("b"));
+        mods.bind(Some("b"));
+        assert!(mods.has_view());
+    }
+
+    /// 迟到/串台的结果被丢掉；成功一次清掉旧失败。
+    #[test]
+    fn late_results_are_dropped() {
+        let mut mods = ModsState::default();
+        mods.bind(Some("a"));
+        mods.changed(view("b"));
+        assert!(!mods.has_view(), "B 的列表画到了 A 上");
+
+        mods.failed(failure("a"));
+        assert!(mods.failed.is_some());
+        mods.changed(view("a"));
+        assert!(mods.failed.is_none(), "成功后旧失败没清掉");
+
+        // 不在详情页（`bound = None`）时任何结果都不落地。
+        let mut idle = ModsState::default();
+        idle.changed(view("a"));
+        assert!(!idle.has_view());
+    }
+
+    /// 在飞标记：置位后能查，快照回来后自然清空。
+    #[test]
+    fn pending_tracks_in_flight_toggles() {
+        let mut mods = ModsState::default();
+        mods.bind(Some("a"));
+        mods.changed(view("a"));
+        mods.mark_pending("x.jar");
+        assert!(mods.is_pending("x.jar"));
+        assert!(!mods.is_pending("y.jar"));
+        mods.changed(view("a"));
+        assert!(!mods.is_pending("x.jar"), "快照回来后还挂着在飞标记");
+    }
+}
diff --git a/crates/presenter/src/state/saves.rs b/crates/presenter/src/state/saves.rs
new file mode 100644
index 0000000..bcb7bb4
--- /dev/null
+++ b/crates/presenter/src/state/saves.rs
@@ -0,0 +1,222 @@
+//! 实例存档 / 截图快照的落地（M235 · STOREMVP）+ 写操作的三样交互态（M247 · SAVESOPS）。
+//!
+//! 从 `state.rs` 拆出（那个文件贴着 400 行硬线），形状与 [`super::mods`] 一致：
+//! **另一个 `impl AppState` 块**，路径与可见性都不变，`apply_core` 只有一行投递。
+//!
+//! # 写操作的三样交互态（M247）
+//!
+//! | 字段 | 是什么 | 为什么必须住在这里 |
+//! |---|---|---|
+//! | [`SavesState::draft`] | 行内重命名的输入缓冲 | 页面模型每帧从快照重建（`from_state`），打字过程中的内容不在快照里 ⇒ 不留在这里就会每打一个字被事件冲掉 |
+//! | [`SavesState::pending`] | 哪个世界的哪个写操作在飞 | 与 [`super::mods::ModsState::pending`] **同一条先例**：只用来把那一行的按钮置灰，**不做乐观回显**（列表只跟快照走） |
+//! | [`SavesState::confirm`] | 删除确认框**正在等谁** | 模态队列只画框、不记得"确认之后要删哪个世界"；而点主按钮的那一刻是 `app/update/dialog.rs`，那里只能从状态里取 |
+//!
+//! ## 生命周期（谁写、谁清、何时必须清）
+//!
+//! | 字段 | 谁写 | 谁清 | 必须清的时刻 |
+//! |---|---|---|---|
+//! | `draft` | `start_rename`（预填当前磁盘名）、`edit_rename`（每敲一个字） | `cancel_rename` / `take_rename`（提交时取走）/ `mark_pending`（请求已发出，草稿没用了）/ `bind` / `changed` | **换实例**、**请求发出**、**快照回来**：三者之后草稿都属于"上一次对话"，留着会让「改名」按钮改到一个已经在别的实例上的名字 |
+//! | `pending` | `mark_pending`（发请求之前，一跳都不等） | `changed`（成功）/ `failed`（失败也要清——**按钮不能永远灰着**，用户要能直接再点一次）/ `bind` | **任何一次后台往返收尾**、**换实例** |
+//! | `confirm` | `ask_delete(dialog, dir)`（app 层先 `dialogs.push` 拿到 id 再登记） | [`SavesState::take_confirm(current)`](SavesState::take_confirm)（**只核销同一个框、取走即清**）/ [`SavesState::clear_confirm`]（次按钮 / 遮罩 / `Esc` / 换实例）/ [`SavesState::changed`]（**只在被确认的世界已从快照里消失时**） | **点主按钮那一刻**、**取消/关闭模态框**、**换实例**、**那个世界没了**（`closed_confirm` 会一并收框） |
+//! | `closed_confirm` | `changed`（世界从快照里消失时登记作废的那个框） | app 层 `refresh_view` → `settle_saves_confirm`（收框后取走）/ `ask_delete` / `clear_confirm` / `bind` | **同一拍或下一拍**：留着会让"世界已经不在了"的确认框一直挡在屏幕中央 |
+//!
+//! ### `confirm` 是**绑定到具体对话框**的一条安全不变量
+//!
+//! 三条判据，缺一条就会出安全事故（复审 r1 P1-1 的事故形态就是第三条缺失）：
+//!
+//! 1. **取走即清**：主按钮拿到目标的同时字段被置空 ⇒ 同一次确认连点两下只发一条删除。
+//! 2. **认框不认人**：`take_confirm(current)` 只在 `current` 等于登记时那个框的 id 时才交付。
+//!    「删存档 → `Esc` → 崩溃卡片 → 点『导出诊断包』」这条链上，第二个框的主按钮**拿不走**目标
+//!    （即使 `Esc` 那条关闭路径漏清——而它现在也清了）。
+//! 3. **世界没了就把框收起来**：快照回来时被确认的世界已不在列表里 ⇒ 清 `confirm` 并登记
+//!    `closed_confirm`，app 层据此收框。否则主按钮会变成一次**静默空操作**（点了没删、也不说一句）。
+//!
+//! 用例（presenter 层）：`the_delete_confirmation_hands_out_once`（取走即清 + 取消后不再有目标）、
+//! `a_dialog_can_only_redeem_its_own_target`（别的框的主按钮拿不走）、
+//! `an_unrelated_snapshot_no_longer_drops_the_confirmation`（P2-1：世界还在 ⇒ 目标还兑现得了）、
+//! `the_confirmation_is_dropped_and_reported_when_the_world_vanishes`（世界没了 ⇒ 清 + 登记收框）。
+//!
+//! # 为什么快照住在这里而不是页面
+//!
+//! 「列表画的永远是磁盘上的真相」是本模块唯一要保证的事，所以：
+//!
+//! - 快照走 [`crate::dto::CoreEvent::Saves`] 的 `Ok` 一支，**整体替换**（不做增量合并）——
+//!   host 每次都是重新扫一遍目录才发的，合并只会两处真相；
+//! - 失败走同一个事件的 `Err` 一支，记下一条**具名原因**，页面按 i18n key 现求文案；
+//! - **可重试**：失败时不清 `bound`，页面据此画"重试"按钮（再发一条
+//!   [`crate::dto::SavesCommand::List`] 就行，没有别的状态要复位）。
+//!
+//! # 迟到结果
+//!
+//! 用户很可能点开 A 的详情页、还没等后台回来就切到 B。所以 `view.instance` 与
+//! [`SavesState::bound`] 不一致的结果**直接丢掉**（与 [`super::mods`] 同一条纪律）。
+
+use crate::dialogs::DialogId;
+use crate::dto::{SavesFailureView, SavesListView};
+
+mod interaction;
+
+use super::AppState;
+
+/// 行内重命名的输入缓冲（见模块文档的三样交互态）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RenameDraft {
+    /// 哪个世界（磁盘名，提交时原样带回去当「源」）。
+    pub dir: String,
+    /// 输入框里的内容（**原样**：合不合法由 core 判，页面只管显示，不做前端过滤）。
+    pub text: String,
+}
+
+/// 一次在飞的写操作（只用来置灰那一行，列表仍然只跟快照）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum SavesOp {
+    /// 重命名中。
+    Rename {
+        /// 磁盘名
+        dir: String,
+    },
+    /// 删除中。
+    Delete {
+        /// 磁盘名
+        dir: String,
+    },
+    /// 备份中。
+    Backup {
+        /// 磁盘名
+        dir: String,
+    },
+}
+
+impl SavesOp {
+    /// 这个操作动的是哪个世界。
+    #[must_use]
+    pub fn dir(&self) -> &str {
+        match self {
+            Self::Rename { dir } | Self::Delete { dir } | Self::Backup { dir } => dir,
+        }
+    }
+}
+
+/// 存档区的视图态。
+#[derive(Debug, Clone, Default, PartialEq)]
+pub struct SavesState {
+    /// 当前详情页的实例 id（`None` = 不在详情页）。
+    pub bound: Option,
+    /// 最近一份快照（`None` = 还没请求过）。
+    pub view: Option,
+    /// 最近一条失败（具名原因；成功一次就清掉）。
+    pub failed: Option,
+    /// 行内重命名的输入缓冲（`None` = 没有在改名）。
+    pub draft: Option,
+    /// 在飞的写操作（`None` = 空闲）。
+    pub pending: Option,
+    /// 删除确认框正在等谁：**(框的 id, 世界名)**（点「确定」时才真的删）。
+    ///
+    /// 为什么带框 id（复审 r1 P1-1）：`take_confirm(current)` 只核销**同一个框**。即使某条
+    /// 关闭路径漏清，目标也不会被下一个不相干的对话框（例如崩溃卡片的「导出诊断包」）兑成一次删除。
+    pub confirm: Option<(DialogId, String)>,
+    /// 刚刚因为「被确认的世界已经不在快照里」而作废的那个框（app 层据此收框，见
+    /// [`SavesState::take_closed_confirm`]）。
+    pub closed_confirm: Option,
+}
+
+impl SavesState {
+    /// 切到另一个实例（换实例必须清空：A 的存档不能画在 B 的详情页上）。
+    ///
+    /// 三样交互态一起清：换实例之后还留着「A 的行内草稿 / A 的删除确认」是错位状态
+    /// （点确定会去删 B 页上的 A，或者把 A 的草稿提交成 B 的改名）。
+    pub(super) fn bind(&mut self, instance: Option<&str>) {
+        if self.bound.as_deref() == instance {
+            return;
+        }
+        self.bound = instance.map(str::to_string);
+        self.view = None;
+        self.failed = None;
+        self.reset_interaction();
+    }
+
+    /// 清掉三样交互态（换实例 / 操作回程时用）。
+    fn reset_interaction(&mut self) {
+        self.draft = None;
+        self.pending = None;
+        self.confirm = None;
+        self.closed_confirm = None;
+    }
+
+    /// 一条结果落地（`Ok` = 快照整体替换，`Err` = 记一条具名失败；迟到/串台的丢掉）。
+    ///
+    /// **成败对三样交互态的处理不一样**（复审 r1 P2-1；与模块文档的安全判据第 3 条同源）：
+    ///
+    /// | 支 | `draft` / `pending` | `confirm` |
+    /// |---|---|---|
+    /// | `Ok`（快照） | 清（这一拍写操作收尾了） | **只在「被确认的那个世界已不在快照里」时**清，并登记 [`SavesState::closed_confirm`] 让 app 收框 |
+    /// | `Err`（失败） | 只清 `pending`（按钮不能永远灰着） | **不动**：一条读盘失败不该把用户刚点出来的确认框变成"点了没反应" |
+    ///
+    /// 换言之「无论成败都清确认中」是**旧的**说法，已经不成立：无条件清会让主按钮静默空操作。
+    pub fn apply(&mut self, result: Result) {
+        match result {
+            Ok(view) => self.changed(view),
+            Err(failure) => self.failed(failure),
+        }
+    }
+
+    /// 快照落地（整体替换；迟到/串台的丢掉）。
+    ///
+    /// 三样交互态在这里**不是一起清**（复审 r1 P2-1）：
+    ///
+    /// | 字段 | 这一拍怎么处理 |
+    /// |---|---|
+    /// | `draft` / `pending` | **清**：写操作已经收尾，行按新快照画 |
+    /// | `confirm` | **只在「被确认的那个世界已经从快照里消失」时清**，并记下那个框（[`Self::closed_confirm`]）让 app 收框 |
+    ///
+    /// 为什么不能无条件清 `confirm`：备份一个大世界还在飞、「打开存档文件夹」的回程还在路上时，
+    /// 用户点「删除 X」→ 框刚弹出来 → 一拍无关快照先到 → 目标被清 → 用户点「删除世界」只关框、
+    /// 不删、也不说一句。少删是安全的，但**静默就是不安全的另一种形式**（用户以为删了）。
+    pub fn changed(&mut self, view: SavesListView) {
+        if self.bound.as_deref() != Some(view.instance.as_str()) {
+            return;
+        }
+        self.failed = None;
+        // 目标世界还在不在这一份快照里（`dir` 是磁盘上的名字，与列表同一口径）。
+        let gone = self
+            .confirm
+            .as_ref()
+            .map(|(_, dir)| !view.worlds.iter().any(|world| &world.dir == dir));
+        self.view = Some(view);
+        self.draft = None;
+        self.pending = None;
+        if gone == Some(true) {
+            if let Some((dialog, _)) = self.confirm.take() {
+                self.closed_confirm = Some(dialog);
+            }
+        }
+    }
+
+    /// 失败落地（只记**当前绑定实例**的；old 列表保留——用户还能看见旧列表，只是多一条红字）。
+    pub fn failed(&mut self, failure: SavesFailureView) {
+        if self.bound.as_deref() != Some(failure.instance.as_str()) {
+            return;
+        }
+        self.failed = Some(failure);
+        // 失败也收尾：按钮不能永远灰着（用户要能直接再点一次重试）。
+        // `confirm` **不动**（与 [`Self::changed`] 同一条理由）：一条读盘失败不该把用户
+        // 刚点出来的删除确认框变成"点了没反应"。
+        self.pending = None;
+    }
+
+    /// 当前绑定实例的列表是否已经有一份快照。
+    #[must_use]
+    pub fn has_view(&self) -> bool {
+        self.view.is_some()
+    }
+}
+
+impl AppState {
+    /// 进/出详情页时对齐绑定（`refresh_view` 调；与 `bind_mods` 同一处生命周期）。
+    pub fn bind_saves(&mut self, instance: Option<&str>) {
+        self.saves.bind(instance);
+    }
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/presenter/src/state/saves/interaction.rs b/crates/presenter/src/state/saves/interaction.rs
new file mode 100644
index 0000000..21a9460
--- /dev/null
+++ b/crates/presenter/src/state/saves/interaction.rs
@@ -0,0 +1,101 @@
+//! `SavesState` 的三样**交互态**：行内草稿 / 在飞标记 / 删除确认目标（M247）。
+//!
+//! 从 `state/saves.rs` 拆出（那个文件加完安全不变量文档之后越过 400 行硬线）。生命周期表在
+//! 父模块的文档里一张写全——**这里只放实现**，不重复判据。
+//!
+//! 三条边界（父模块文档的展开）：
+//! 1. `draft` / `pending` 只跟"这一拍在编辑/在飞什么"有关，快照落地一律清；
+//! 2. `confirm` **认框**：`take_confirm(current)` 只在 id 相等时交付（见 [`SavesState::take_confirm`]）；
+//! 3. `closed_confirm` 是"这个框该收起来了"的信号，app 层 `refresh_view` 取走并真的收框。
+
+use crate::dialogs::DialogId;
+
+use super::{RenameDraft, SavesOp, SavesState};
+
+impl SavesState {
+    /// 开一个行内重命名（输入框预填当前磁盘名：改个后缀比从零打更常见）。
+    pub fn start_rename(&mut self, dir: &str) {
+        self.draft = Some(RenameDraft {
+            dir: dir.to_string(),
+            text: dir.to_string(),
+        });
+    }
+
+    /// 输入框变了（**照原样存**，不做前端过滤：非法名字由 core 拒并给出具名原因）。
+    pub fn edit_rename(&mut self, text: String) {
+        if let Some(draft) = &mut self.draft {
+            draft.text = text;
+        }
+    }
+
+    /// 取走草稿并收起来（提交时用；`None` = 当前没有草稿）。
+    pub fn take_rename(&mut self) -> Option {
+        self.draft.take()
+    }
+
+    /// 取消行内重命名。
+    pub fn cancel_rename(&mut self) {
+        self.draft = None;
+    }
+
+    /// 记下「删除确认框正在等谁」：**框的 id + 世界名**（`dialog` 由调用方 `dialogs.push` 拿到）。
+    pub fn ask_delete(&mut self, dialog: DialogId, dir: &str) {
+        self.confirm = Some((dialog, dir.to_string()));
+        self.closed_confirm = None;
+    }
+
+    /// 取走确认目标（点「确定」时用）——**只核销 `current` 那一个框**。
+    ///
+    /// 「取走即清」+「认框不认人」两条合起来是**安全不变量**：
+    /// ①同一次确认连点两下只发一条删除（第二下拿不到目标）；
+    /// ②别的框（崩溃卡片的「导出诊断包」、进度框……）点主按钮**拿不走**这个目标——
+    ///   哪怕某条关闭路径漏清（复审 r1 P1-1 的事故形态），也只能核销它自己那个框。
+    pub fn take_confirm(&mut self, current: DialogId) -> Option {
+        match &self.confirm {
+            Some((dialog, _)) if *dialog == current => {
+                self.closed_confirm = None;
+                self.confirm.take().map(|(_, dir)| dir)
+            }
+            _ => None,
+        }
+    }
+
+    /// **某个**确认框被取消/关掉（次按钮、遮罩、`Esc` 三条路径都走它）：**只清它自己那个目标**。
+    ///
+    /// 为什么不无条件清（复审 r2 的加固）：`clear_confirm` 不认框，理论上够得着"清掉别人的删除目标"
+    /// ——今天三条关闭路径关的都是当前框，够不着，但把判据写死在这里比依赖调用顺序稳。
+    pub fn close_confirm(&mut self, current: DialogId) {
+        if self.confirm_dialog() == Some(current) {
+            self.clear_confirm();
+        }
+    }
+
+    /// 清掉目标（**无条件**）：换实例 / 复位时用——那时"哪个框"已经不重要了。
+    pub fn clear_confirm(&mut self) {
+        self.confirm = None;
+        self.closed_confirm = None;
+    }
+
+    /// 取走「因为世界已经不在快照里而作废」的那个框（app 层据此收框，避免主按钮空操作）。
+    pub fn take_closed_confirm(&mut self) -> Option {
+        self.closed_confirm.take()
+    }
+
+    /// 当前确认目标属于哪个框（`None` = 没有在等的目标）。
+    #[must_use]
+    pub fn confirm_dialog(&self) -> Option {
+        self.confirm.as_ref().map(|(dialog, _)| *dialog)
+    }
+
+    /// 标记一次写操作在飞（草稿同时收起来：请求已经发出去了）。
+    pub fn mark_pending(&mut self, op: SavesOp) {
+        self.pending = Some(op);
+        self.draft = None;
+    }
+
+    /// 这个世界的写操作在飞吗（用来把那一行置灰）。
+    #[must_use]
+    pub fn is_pending(&self, dir: &str) -> bool {
+        self.pending.as_ref().is_some_and(|op| op.dir() == dir)
+    }
+}
diff --git a/crates/presenter/src/state/saves/tests.rs b/crates/presenter/src/state/saves/tests.rs
new file mode 100644
index 0000000..d29570d
--- /dev/null
+++ b/crates/presenter/src/state/saves/tests.rs
@@ -0,0 +1,252 @@
+//! `SavesState` 的判据：绑定 / 迟到丢弃 / 三样交互态（含删除确认的安全不变量）。
+//!
+//! 从 `state/saves.rs` 拆出（父模块守 400 行）。**判据一条没改**，另外补了复审 r1 P1-1 / P2-1
+//! 那两条：认框不认人、无关快照不再吃掉确认目标。
+
+use super::*;
+use crate::dto::{SavesFailureKind, WorldView};
+
+fn view(instance: &str) -> SavesListView {
+    SavesListView {
+        instance: instance.to_string(),
+        dir: "C:/mc/saves".to_string(),
+        exists: true,
+        worlds: vec![WorldView {
+            dir: "World".to_string(),
+            icon: false,
+            modified_ms: None,
+        }],
+        screenshots_dir: "C:/mc/screenshots".to_string(),
+        screenshots_exists: false,
+        screenshots: Vec::new(),
+        skipped: Vec::new(),
+        last_op: None,
+    }
+}
+
+fn failure(instance: &str) -> SavesFailureView {
+    SavesFailureView {
+        instance: instance.to_string(),
+        file: String::new(),
+        op: None,
+        kind: SavesFailureKind::DirUnusable,
+        detail: "Access is denied.".to_string(),
+    }
+}
+
+/// 换实例必须清空（A 的存档不许画在 B 的详情页上）。
+#[test]
+fn binding_another_instance_drops_the_old_view() {
+    let mut saves = SavesState::default();
+    saves.bind(Some("a"));
+    saves.changed(view("a"));
+    assert!(saves.has_view());
+
+    saves.bind(Some("b"));
+    assert!(!saves.has_view(), "换实例后还留着 A 的存档");
+    assert_eq!(saves.bound.as_deref(), Some("b"));
+
+    // 同一个实例再 bind 一次不该清（`refresh_view` 每帧都调）。
+    saves.changed(view("b"));
+    saves.bind(Some("b"));
+    assert!(saves.has_view());
+}
+
+/// 迟到/串台的结果被丢掉；成功一次清掉旧失败（重试成功后红字要消失）。
+#[test]
+fn late_results_are_dropped_and_success_clears_the_failure() {
+    let mut saves = SavesState::default();
+    saves.bind(Some("a"));
+    saves.changed(view("b"));
+    assert!(!saves.has_view(), "B 的列表画到了 A 上");
+
+    saves.failed(failure("a"));
+    assert!(saves.failed.is_some());
+    assert!(saves.bound.is_some(), "失败不许把绑定清掉（要能重试）");
+    saves.changed(view("a"));
+    assert!(saves.failed.is_none(), "成功后旧失败没清掉");
+
+    // 不在详情页（`bound = None`）时任何结果都不落地。
+    let mut idle = SavesState::default();
+    idle.changed(view("a"));
+    idle.failed(failure("a"));
+    assert!(!idle.has_view());
+    assert!(idle.failed.is_none());
+}
+
+/// 换实例要把三样交互态一起清掉（草稿 / 在飞 / 确认目标）。
+///
+/// 抓得住：换到 B 之后「A 的草稿」还留着 ⇒ 用户点确定会去改 B 页上的一个不存在的名字。
+#[test]
+fn switching_instances_drops_draft_pending_and_confirm() {
+    let mut saves = SavesState::default();
+    saves.bind(Some("a"));
+    saves.changed(view("a"));
+    saves.start_rename("World");
+    saves.edit_rename("Renamed".to_string());
+    saves.ask_delete(7, "World");
+    saves.mark_pending(SavesOp::Backup {
+        dir: "World".to_string(),
+    });
+    assert!(saves.draft.is_none(), "发请求时草稿该收起来");
+    assert!(saves.pending.is_some());
+
+    saves.bind(Some("b"));
+    assert!(saves.draft.is_none(), "换实例后草稿还在");
+    assert!(saves.pending.is_none(), "换实例后在飞标记还在");
+    assert!(saves.confirm.is_none(), "换实例后删除确认目标还在");
+}
+
+/// 回程（成功或失败）都要把「在飞」收掉：按钮不能永远灰着。
+#[test]
+fn both_outcomes_clear_the_pending_marker() {
+    let mut saves = SavesState::default();
+    saves.bind(Some("a"));
+    saves.changed(view("a"));
+    saves.mark_pending(SavesOp::Delete {
+        dir: "World".to_string(),
+    });
+    assert!(saves.is_pending("World"));
+    saves.failed(failure("a"));
+    assert!(
+        !saves.is_pending("World"),
+        "失败后在飞标记没清：重试按钮会一直是灰的"
+    );
+
+    saves.mark_pending(SavesOp::Rename {
+        dir: "World".to_string(),
+    });
+    assert!(saves.is_pending("World"));
+    saves.changed(view("a"));
+    assert!(!saves.is_pending("World"), "成功后没清在飞标记");
+}
+
+/// 确认目标只发一次（同一次确认连点两下不该发两条删除）。
+#[test]
+fn the_delete_confirmation_hands_out_once() {
+    let mut saves = SavesState::default();
+    saves.bind(Some("a"));
+    saves.ask_delete(7, "Doomed");
+    assert_eq!(saves.take_confirm(7).as_deref(), Some("Doomed"));
+    assert!(
+        saves.take_confirm(7).is_none(),
+        "第二次取还拿得到：连点会删两次"
+    );
+
+    saves.ask_delete(8, "Other");
+    saves.clear_confirm();
+    assert!(saves.take_confirm(8).is_none(), "取消之后还留着目标");
+}
+
+/// **复审 r2 加固**：别人那个框被关掉时，不该清掉我们的删除目标。
+///
+/// `close_confirm(current)` 只在 `current` 等于登记的那个框时才清；`clear_confirm()` 仍然无条件
+/// （换实例复位时用——那时"哪个框"已经不重要了）。
+#[test]
+fn closing_another_dialog_leaves_our_target_alone() {
+    let mut saves = SavesState::default();
+    saves.bind(Some("a"));
+    saves.ask_delete(7, "Doomed");
+
+    saves.close_confirm(99);
+    assert_eq!(
+        saves.take_confirm(7).as_deref(),
+        Some("Doomed"),
+        "别的框关掉时把我们的目标清掉了"
+    );
+
+    saves.ask_delete(8, "Other");
+    saves.close_confirm(8);
+    assert!(
+        saves.take_confirm(8).is_none(),
+        "自己的框关掉了，目标还在（下一次点确定会删上一个）"
+    );
+}
+
+/// **P1-1 的核心**：目标只属于登记它的那个框。别的框点主按钮**拿不走**它。
+///
+/// 事故形态：`Esc` 关掉删除确认框（某条关闭路径漏清）→ 崩溃卡片弹出来 →
+/// 点「导出诊断包」（也是 `Confirm` 的主按钮）→ 若 `take_confirm` 无条件交付，
+/// 那个世界就被静默删掉了。判据是 **id 不等就不交付、也不清**（目标还是那个框的）。
+#[test]
+fn a_dialog_can_only_redeem_its_own_target() {
+    let mut saves = SavesState::default();
+    saves.bind(Some("a"));
+    saves.ask_delete(7, "Doomed");
+
+    assert!(
+        saves.take_confirm(99).is_none(),
+        "别的框的主按钮拿走了删除目标"
+    );
+    assert_eq!(saves.confirm_dialog(), Some(7), "拿不走也不该被顺手清掉");
+    assert_eq!(
+        saves.take_confirm(7).as_deref(),
+        Some("Doomed"),
+        "自己的框反而兑不了"
+    );
+}
+
+/// **P2-1**：一拍无关快照（世界还在）不许把确认目标吃掉——否则主按钮就是静默空操作。
+#[test]
+fn an_unrelated_snapshot_no_longer_drops_the_confirmation() {
+    let mut saves = SavesState::default();
+    saves.bind(Some("a"));
+    saves.changed(view("a"));
+    saves.ask_delete(7, "World");
+
+    // 「打开存档文件夹」的回程 / 备份在飞时的列表刷新：世界还在快照里。
+    saves.changed(view("a"));
+    assert_eq!(
+        saves.take_confirm(7).as_deref(),
+        Some("World"),
+        "无关快照把确认目标吃掉了：主按钮会变成静默空操作"
+    );
+
+    // 读盘失败同理：一条失败不该把用户刚点出来的框弄成"点了没反应"。
+    saves.ask_delete(8, "World");
+    saves.failed(failure("a"));
+    assert_eq!(saves.take_confirm(8).as_deref(), Some("World"));
+}
+
+/// **P2-1 的另一半**：被确认的世界从快照里消失 ⇒ 目标清掉，并且**登记那个框该收了**。
+///
+/// 只清不登记就是"框还在、主按钮点了什么也不发生"；只登记不清就是留着一个作废的目标。
+#[test]
+fn the_confirmation_is_dropped_and_reported_when_the_world_vanishes() {
+    let mut saves = SavesState::default();
+    saves.bind(Some("a"));
+    saves.changed(view("a"));
+    saves.ask_delete(7, "World");
+
+    // 快照回来时那个世界已经不在列表里（别的进程删掉了 / 改名了）。
+    let mut gone = view("a");
+    gone.worlds.clear();
+    saves.changed(gone);
+
+    assert!(saves.confirm.is_none(), "目标还留着一个已经不存在的世界");
+    assert_eq!(
+        saves.take_closed_confirm(),
+        Some(7),
+        "没有登记那个框 ⇒ 它会一直挡在屏幕中央、主按钮点了没反应"
+    );
+    assert!(saves.take_confirm(7).is_none(), "作废的目标还能被兑现");
+    assert!(saves.take_closed_confirm().is_none(), "信号只发一次");
+}
+
+/// 行内草稿照原样存：非法名字不在前端过滤（core 会拒并给出具名原因）。
+#[test]
+fn the_rename_draft_keeps_the_typed_text_verbatim() {
+    let mut saves = SavesState::default();
+    saves.bind(Some("a"));
+    saves.start_rename("World");
+    assert_eq!(
+        saves.draft.as_ref().expect("草稿").text,
+        "World",
+        "应预填当前名字"
+    );
+    saves.edit_rename("../escape".to_string());
+    let draft = saves.take_rename().expect("草稿");
+    assert_eq!(draft.dir, "World");
+    assert_eq!(draft.text, "../escape", "输入被前端偷偷改了");
+    assert!(saves.take_rename().is_none(), "取走之后草稿还在");
+}
diff --git a/crates/presenter/src/state/tiles.rs b/crates/presenter/src/state/tiles.rs
new file mode 100644
index 0000000..40f31ab
--- /dev/null
+++ b/crates/presenter/src/state/tiles.rs
@@ -0,0 +1,50 @@
+//! 磁贴网格的纯函数与单元类型（从 `state.rs` 原样搬出，守 400 行硬线）。
+//!
+//! **纯搬移**：类型、函数、文档一字未改，只是换了文件；`state.rs` 用 `pub use` 再导出，
+//! 于是 `crate::state::{TileCell, grid_positions}` 这两个老路径继续可用。
+//!
+//! M224 又把 [`AppState::tiles`] 从 `state.rs` 搬到这里（同一个 400 行原因）：筛选 + 排版是
+//! 磁贴域自己的事，方法留在 `impl AppState` 的另一个块里，调用点 `state.tiles()` 不变。
+
+use crate::dto::InstanceSummary;
+
+use super::AppState;
+
+/// 磁贴网格单元：位置由 [`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()
+}
+
+impl AppState {
+    /// 按搜索词过滤后的磁贴网格（顺序稳定 = 实例列表顺序）。
+    pub fn tiles(&self) -> Vec> {
+        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()
+    }
+}
diff --git a/crates/presenter/src/state_tests.rs b/crates/presenter/src/state_tests.rs
new file mode 100644
index 0000000..b7a508b
--- /dev/null
+++ b/crates/presenter/src/state_tests.rs
@@ -0,0 +1,372 @@
+//! 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,
+        launch: crate::dto::LaunchArgsView::default(),
+    }
+}
+
+#[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,
+    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) -> 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/docs/backend-cjk-evidence-matrix.md b/docs/backend-cjk-evidence-matrix.md
new file mode 100644
index 0000000..ccbbd00
--- /dev/null
+++ b/docs/backend-cjk-evidence-matrix.md
@@ -0,0 +1,78 @@
+# 后端 × 中文：什么断言只在软渲染下成立，什么必须在 GPU 下看（M187）
+
+本文件登记一条**通道级缺口**，不是一条 bug：自动化证据全部走软件渲染，所以「只有 GPU 后端
+才出现」的缺陷在 CI 里永远是盲区。下次有人要验「文字/像素在 GPU 上是否正常」时，先读这一页。
+
+## 1. 现状：所有自动出图都是 `--software-renderer`
+
+| 通道 | 位置 | 后端 |
+|---|---|---|
+| CI 冒烟截屏 | `.github/workflows/ci.yml:101` | `--software-renderer`（强制 CPU） |
+| CI 交互冒烟 | `.github/workflows/ci.yml:246`、`:283` | `--software-renderer` |
+| Linux 容器冒烟 | `packaging/linux-smoke-docker.sh:90` | `--software-renderer` |
+| D30 视觉验收（人工，按协议出图） | `DevDocs/PlanDoc/`（视觉验收协议） | 同上（CI 同款命令） |
+
+`--renderer=auto`（默认）会挑 wgpu；`--software-renderer` 强制 tiny-skia。CI 走后者是**有意的**：
+容器/无 GPU 机器上没有 Vulkan/DX12 设备，硬要 wgpu 会红在一句「adapter 创建失败」上，与皮肤无关。
+
+**代价**：tiny-skia 与 wgpu 是两套完全不同的文字光栅化路径（前者 `cosmic-text` + CPU 位图上传，
+后者经 `cryoglyph` 上传到 GPU 字形图集）。所以「GPU 侧字形图集出错」这类缺陷，**任何自动证据都抓不到**。
+
+## 2. 这轮实测：M190 的「owned 文字在 wgpu 下丢字」在本 branch 上**没有复现**
+
+同一份构建、同一串中文、同一字号，一次 wgpu 一次 tiny-skia：
+
+| 图 | 后端 | 内容 |
+|---|---|---|
+| `DevDocs/artifacts/m187/ab-wgpu.png` | wgpu（Vulkan，AMD RX 6600 XT） | 四行：`text_role_owned` / `text_role` × 大字号 / 正文字号，逐字相同 |
+| `DevDocs/artifacts/m187/ab-tinyskia.png` | tiny-skia（`--software-renderer`） | 同上，与 wgpu 那张逐字一致 |
+| `DevDocs/artifacts/m187/probe-acc-wgpu.png` | wgpu | 账户页设备码面板（M190 钉的那一行「剩 14:59」在 wgpu 下**正常画出**） |
+
+结论（只对这份构建、这台机器成立，不推广）：`frame::text_role_owned` 与 `frame::text_role`
+产出的控件在小规模中文下**行为一致**，两种后端都能画；把缺陷归因到「owned 路径」在本 branch
+上没有证据支撑。要复现 M190 的现象，需要它当时的构建/环境。
+
+## 3. 分工：哪些结论只信软渲染，哪些必须在 GPU 上看
+
+| 断言类型 | 软渲染（tiny-skia）够吗 | 必须在 GPU 下复核 | 理由 |
+|---|---|---|---|
+| 版面几何（位置、宽高、折行、间距） | ✅ 够 | 建议一次 | 几何由布局树决定，两后端共用 |
+| 文字**在不在**（整行缺失 / 空块） | ⚠️ 只能证明 CPU 路径 | **必须** | GPU 字形图集是独立实现（`cryoglyph`） |
+| 字形形状 / 连字 / 每字形字体落点（「个别字换了字体」） | ⚠️ 同上 | **必须** | 两种后备字体选择可能不同 |
+| 颜色 / 对比度 / 主题令牌 | ✅ 够（纯色由令牌给） | 建议一次 | 面板混合色只有 GPU 路径可验 |
+| 材质层 / 高程阴影 | ⚠️ | **必须** | 阴影在 wgpu 与 tiny-skia 是两套画法 |
+| 整窗 α / 无边框圆角（Win32） | ❌ 不看 | **必须**（且只在 Windows） | 与渲染后端无关，靠 DWM 下发 |
+| 背景图 / 壁纸取色 / 图片缩放 | ⚠️ | **必须** | GPU 侧走纹理采样 |
+| SVG 图标（含描边宽度） | ✅ 够 | 建议一次 | 光栅化后端不同 |
+
+读法：**「有没有画出来」与「字形对不对」这两类，只认 GPU 图**；几何与令牌只认一份即可。
+
+## 4. 怎么在 GPU 下出图（本机命令）
+
+```bash
+# GPU（wgpu；会自动挑适配器，日志里 [gpu] Selected: AdapterInfo{…} 是「真用上 GPU」的实证）
+unlucky-launcher-iced --screenshot out-gpu.png --screenshot-theme=light
+
+# CPU（tiny-skia）
+unlucky-launcher-iced --screenshot out-cpu.png --screenshot-theme=light --software-renderer
+
+# 两图逐像素比对（本程序自带，不需要 Python/PIL）
+unlucky-launcher-iced --diff out-gpu.png out-cpu.png
+```
+
+`--diff` 的退出码：`0` 一致 / `1` 有差异 / `2` 参数错。**几何应当一致**（D30 的硬项），
+颜色与字形抗锯齿允许不同——所以「有差异」不等于坏，要**看着图**判。
+
+启动失败弹窗的两态各两张（wgpu / tiny-skia）就是这么出的：
+
+```bash
+ULL_DIALOG_FIXTURE=crash-report unlucky-launcher-iced --screenshot dialog-crash-wgpu.png
+ULL_DIALOG_FIXTURE=no-logs      unlucky-launcher-iced --screenshot dialog-no-logs-wgpu.png
+```
+
+## 5. 机器条件（写下来，免得下次怀疑「没 GPU」）
+
+本机 `--renderer=auto` 的实测选择：`AMD Radeon RX 6600 XT` / Vulkan / `device_type: DiscreteGpu`。
+无独显的机器上 wgpu 会落到 `Microsoft Basic Render Driver`（CPU 实现，`device_type: Cpu`）——
+那种图**不能**算 GPU 证据（它仍是 CPU 光栅化，只是走了 DX12 接口）。
+判据：看 `[gpu] Selected:` 那行的 `device_type`，`Cpu` 一律不算。
diff --git a/docs/download-settings.md b/docs/download-settings.md
new file mode 100644
index 0000000..15654a3
--- /dev/null
+++ b/docs/download-settings.md
@@ -0,0 +1,197 @@
+# 下载设置到底改了谁（M193）
+
+一句话：**`download.concurrency` / `download.retry_limit` / `download.gh_proxy` 现在真的进引擎**；
+其余四个 `download.*` 键（`region` / `mirror_preference` / `proxy_mode` / `proxy_url`）**引擎侧零消费者**，
+界面上改了不会改变任何下载行为——这一页把它们逐条标出来，别再让「设置项说假话」。
+
+出处：M190 的 204 条 finding 复核（`DevDocs/PlanDoc/research/191-finding-triage.md` §3 A-3）挖出的
+「用户能改、改了没用」缺口：schema 说并发 8，引擎恒跑 64，两处各写一个数。
+
+## 1. 取证：八个下载类键的真实生效值
+
+「真实生效值」是**改造前**（M193 之前）代码里实际会用的值，不是界面上写的值。
+
+| 键 | schema 默认 / 范围 | 引擎侧消费者 | 真实生效值（改造前） | 本轮 |
+|---|---|---|---|---|
+| `download.concurrency` | 8 / 1–256 | **无**（恒用 `EngineConfig::default()`） | **64**（`Semaphore` 容量） | ✅ 接进引擎，范围收成 1–64 |
+| `download.retry_limit` | 3 / 0–10 | **无** | 3（碰巧与 schema 相同，但改它无效） | ✅ 接进引擎，范围 0–10（0 与 1 都 = 只试一次） |
+| `download.gh_proxy` | 空串 / ≤256 字符（M197 登记） | 共享引擎装配点（`shared::build` 的 gh-proxy 候选链）+ CLI 的 `download::tuning` | 地区档案里的内置值（镜像优先时 `gh-proxy.com`） | ✅ 下沉到共享装配点，GUI 与四条 CLI 命令一致 |
+| `download.region` | auto / auto·cn·global | **无**（`RegionProfile::pinned` 无生产调用点） | 永远按「时区+语言」自动判定 | ❌ 未接（见 §5） |
+| `download.mirror_preference` | auto / auto·official·mirror | **无** | 永远按地区模式（镜像优先/直连） | ❌ 未接（见 §5） |
+| `download.proxy_mode` | none / none·system·manual | **无**（`http::build_client` 从不调 `.proxy()`） | 只走环境变量代理（reqwest 默认），`system`/`manual` 都不生效 | ❌ 未接（见 §5） |
+| `download.proxy_url` | "" | **无** | 空（从不使用） | ❌ 未接（见 §5） |
+| `download.action.detect_region` | （动作键，不是设置） | presenter 的 `detect_region` | 清 `region.json` + 失效共享引擎 | ✅ 本来就真 |
+
+复现方法（改造前）：`grep -rn "download.concurrency" crates/` 只命中 `setting/keys.rs` 的定义与
+agent 的测试；同理 `download.proxy_mode` / `proxy_url` / `mirror_preference` 只有 presenter 的显示行。
+
+## 2. 唯一来源：默认值谁说了算
+
+```text
+crates/core/src/download/config.rs
+  DEFAULT_MAX_CONCURRENCY = 8          ← 唯一写死数字的地方
+  MAX_CONCURRENCY = 64                 ← 硬上限
+  DEFAULT_MAX_ATTEMPTS_PER_SOURCE = 3
+  MAX_ATTEMPTS_PER_SOURCE = 10
+        │
+        ├─→ EngineConfig::default()                 （引擎默认）
+        ├─→ DownloadTuning::default()               （宿主没灌任何值时）
+        └─→ setting::keys 的 schema 默认值与范围     （界面/AI/CLI 看到的契约）
+```
+
+守卫 `the_schema_contract_is_single_sourced`（`download/config.rs`，它合并了原先的「默认值相等」与
+「区间同源」两条）让「改一处另一个不变」直接变红——这是防 8 vs 64 复发的唯一手段。
+另有 `the_key_docs_quote_the_real_limits` 钉住 schema 描述里的数字（见 §6.1.1 表格的第三行）。
+
+## 3. 接线链（宿主 → 引擎）
+
+```text
+config/launcher.json
+  download.concurrency ─┐
+  download.retry_limit ─┼→ presenter::host::settings::download::tuning_of
+  download.gh_proxy ────┘        │  DownloadTuning::from_settings（默认值/夹取/回落都在 core）
+                                 ↓
+                     shared::set_tuning(, tuning)   变了吗？没变就什么都不做
+                                 ↓ 变了 → 淘汰该根的登记项
+                     shared::engine_for() → shared::build
+                                 ↓
+                     EngineConfig { max_concurrency, max_attempts_per_source } + RegionProfile.gh_proxy
+                                 ↓
+                     Semaphore(容量) / attempts_for() / MirrorTable::expand() 的 gh-proxy 候选
+```
+
+**同步点是显式的**，两处，共用同一个函数 `apply_tuning`：
+
+* `presenter/src/host/engine.rs::engine()` —— 每次取引擎前（幂等，值没变就一行不动）；
+* `presenter/src/host/dispatch.rs` 的 `SetSetting` 分支 —— 用户改完设置立刻生效，并让常驻持有
+  引擎的自更新 `Factory` 换一份（`refresh_update_factory`）。
+
+调优按**数据根**存（与引擎登记处同键），不是进程级：同一进程里多个数据根时互不串味。
+
+## 3.1 哪些路径吃这套设置
+
+**四条 CLI 命令与 GUI 都吃**（M203 起。M193 时期这张表把三条 CLI 记成「自建裸引擎、零消费者」，那已不成立——教训见本节末）。
+
+| 路径 | 入口 | 吃设置吗 |
+|---|---|---|
+| GUI 的**全部**下载：内容库（Modrinth/CurseForge）、版本清单、资源/库/日志文件、字体、JDK 安装、自更新 | `presenter::host::engine::engine` → `core::download::shared::engine_for` | ✅ 吃（并发/尝试次数/gh-proxy 都吃） |
+| CLI `ull install` | `crates/cli/src/commands/install/mod.rs:78` 的 `build_engine` → `crates/cli/src/download.rs::engine` | ✅ 吃（并发 / 尝试次数 / gh-proxy） |
+| CLI `ull java` | `crates/cli/src/commands/java.rs:312` 同上 | ✅ 吃（并发 + 尝试次数 + gh-proxy） |
+| CLI `ull pack` | `crates/cli/src/commands/pack.rs:286` 同上 | ✅ 吃（并发 / 尝试次数 / gh-proxy） |
+| CLI `ull update`（**自更新路径**） | `crates/cli/src/commands/update.rs:64` 复用 `install::build_engine` | ✅ 吃（**并发这条路径上不可观测**：自更新只下**一个** artifact，闸门开 1 还是 8 都只有一条连接；真正随设置变的是每源尝试次数与 gh-proxy 前缀） |
+
+四条 CLI 路径共用同一次装配：`crates/cli/src/download.rs` 从 **CLI 自己的** `launcher.json`（与
+`ull config set` 同一份文件）读三个 `download.*` 键 → `DownloadTuning::from_settings`（默认值/夹取/回落
+都在 core）→ `shared::engine_with_tuning(, tuning)`。所以 `presenter` 的 `shared::build` 不再是
+**全仓唯一**的装配点，但装配规则仍只有 core 那一份。
+
+回落仍是静默的：`SettingStore::load` 永不失败（坏值只进 `problems()`），类型不对 → `None`，越界 → 出厂
+值，不报错、不中断安装。历史教训保留在此：M193 把出厂并发从 64 改成 8 之后，当时还在用裸
+`EngineConfig::default()` 的那几条命令**静默**跟着降了——「用出厂值」和「读到了设置」在输出上一模一样，
+这正是 §6 里三条 CLI 变异要抓的东西。
+
+## 4. 三态语义：`download.gh_proxy`
+
+| 值 | 含义 | 效果 |
+|---|---|---|
+| 空串（出厂） | **没有覆盖**，跟随内置默认 | 镜像优先/国内判定时套 `mirrors.json` 里的 `gh-proxy.com` |
+| `off`（也认 `none`/`direct`/`disable`/`disabled`/`no`） | 明确关掉 | 一个 gh-proxy 候选都不生成 |
+| 其它非空 | 覆盖前缀 | 用它替换内置前缀（类别仍只在镜像优先/国内判定时启用） |
+
+**空串 ≠ 关**：「我还没决定」和「我明确不要」是两件事。设置页的说明文案（presenter 行 + iced 行）
+两档必须都写出来——这是最容易让用户以为「关掉了、其实还在套前缀」的地方。
+
+边界：非法值（负数、超上限、手改坏值）**一律回落出厂默认**，不报错、不阻断下载；schema 在写入口
+就拒绝越界值，引擎侧再夹一次是纵深防御（老文件里可能躺着旧 schema 允许的大数）。
+
+**`download.retry_limit = 0` 是合法值**（P2-1 复审的结论）：旧版 GUI 的档位表里就有 `0`，所以
+范围保留 `0~10`，语义定为 **`0` 与 `1` 都 = 只试一次、不重试**（`attempts = max(1, value)`）。
+这样老配置零迁移、`ull config get` 读到的 0 与引擎真做的事一致（试 1 次），不会再出现
+「界面显示 0、引擎按 3 跑」。
+
+## 5. 没接的四个键（已登记为 finding）
+
+`download.region` / `download.mirror_preference` / `download.proxy_mode` / `download.proxy_url`
+**引擎侧零消费者**：界面上改了不改变任何下载行为。要接它们分别需要：
+
+* `region` → `RegionProfile::pinned(mode, now)`（值 `cn`/`global` 映射到 `MirrorFirst`/`Direct`，
+  并把 `trigger` 置成 `UserPinned` 让 24h 重判不覆盖它）；
+* `mirror_preference` → 引擎候选排序里插一档「强制官方优先 / 强制镜像优先」；
+* `proxy_mode` / `proxy_url` → `http::build_client` 里加 `.proxy(reqwest::Proxy::all(url)?)`。
+
+三条都在 M193 的 scope 外（`http.rs` / 引擎候选排序 / 一处新装配），已单独立 finding。
+
+## 6. 守卫与变异证明（逐条只改实现侧，跑完即还原）
+
+| # | 变异（只改实现侧） | 守卫用例 | 结果 |
+|---|---|---|---|
+| M1 | `shared::build` 的 `tune.apply_to(...)` 换回裸 `EngineConfig::default()` | `download::shared::tests::the_setting_and_the_gh_proxy…` | 红（探针 8，期望 2） |
+| M2 | `shared::build` 的 `tune.apply_gh_proxy(region)` 换回 `region` | 同上 | 红（`off` 档仍有 gh-proxy 候选） |
+| M3 | 删掉 `set_tuning` 里的 `registry().remove` | 同上 | 红（换参数后交回旧引擎） |
+| M4 | 删掉构造点的 `clamp(1, MAX_CONCURRENCY)` | 同上 | 红（9999 张许可真开了） |
+| M5 | `EngineConfig::default()` 的并发写回字面量 64 | `download::config::tests::the_schema_contract_is_single_sourced` | 红 |
+| M6 | schema 的并发默认值写成字面量 16 | 同上 | 红（两处各写一个数） |
+| M7 | 删掉 `host/engine.rs::engine` 里的 `apply_tuning` | `host::settings::tests::the_concurrency_setting…` | 红（探针 8，期望 2） |
+| M8 | 下载设置页的 gh-proxy 行改回 `("Preferred source", "Automatic (region)")` | `the_downloads_rows_state_semantics…` | 红 |
+| M9 | `from_settings` 的尝试次数去掉 `.max(1)`（0 原样交给引擎） | `download::config::tests::missing_or_illegal_values_fall_back_to_the_defaults` | 红（`left: 0 / right: 1`） |
+| M10 | schema 描述里的「1~64」改成「1~99」（第三处字面量） | `download::config::tests::the_key_docs_quote_the_real_limits` | 红 |
+| M11 | `commands::pack::build_engine` 换回裸 `EngineConfig::default()`（其余三条不动） | `cli::download::tests::pack_engine_takes_the_concurrency_from_the_setting_store` | 红（探针 8 ≠ 2），另四条 CLI 用例绿 |
+| M12 | `commands::update::engine` 换回裸 `EngineConfig::default()` | `cli::download::tests::update_engine_takes_the_concurrency_from_the_setting_store` | 红（8 ≠ 4），另四条绿 |
+| M13 | `download::tuning` 不读 `KEY_GH_PROXY`（第三参传 `None`） | `cli::download::tests::the_gh_proxy_setting_reaches_the_candidate_chain` | 红（`off` 档仍有 gh-proxy 候选） |
+
+## 6.1 gh-proxy 那一行的形状（P3-1）：M201 之后已解决
+
+M193 时期这一组把「GitHub 加速前缀」的三态画成三行（`GitHub 加速前缀 / 留空 = 跟随内置默认`、
+`关掉它 / 填 off = 关闭`、`换掉它 / 填 URL 前缀 = 覆盖`）。这是**已知的观感问题**：
+①`关掉它` / `换掉它` 读起来像按钮而不是取值说明；②同一个设置画成三行比三态本身更难懂。
+
+当时的结论是「正确的家是下一条『iced 设置数据通路』mission」——**那一条已落地（M201）**，现状：
+
+| 项 | M193 时期 | M201 之后 |
+|---|---|---|
+| 控件 | 三行语义行（`&'static str`） | **一行真控件**：标题 + 说明 + 输入框 + 「应用」按钮（`pages/settings/download.rs::text_row`） |
+| 三态怎么说 | 拆成三行、每行一句 | 一句话说完（留空 / off / 前缀），末尾接「当前生效：…」（presenter 的 `gh_proxy_state`，读的是**引擎生效档位**，不是文件原文，见 P3-5） |
+| 当前值 | 不显示 | 输入框里是快照里那个值（`States::settings` ← `CoreEvent::SettingsChanged`） |
+| 改它 | 改不了 | 输入 → 本地草稿 → 点「应用」→ `AppCommand::SetSetting` → host 写盘 + 重发快照 |
+
+那三行**还在** `GROUP.rows` 里，但只在**没有快照**时画（harness / `pages_demo` / 首帧，走 `frame::demo_card`）：
+它们说的是语义（「出厂 8 · 可调 1~64」）而不是当前值，所以不会再被当成界面上的真值（M193 用户投诉的形状）。
+有快照时这一组画的是真控件，`GROUP.rows` 一行都不画。
+
+### 6.1.1 「数字的第二来源」现状（P3-2 登记，M207 复核）
+
+| 位置 | 能不能引用常量 | 守卫 |
+|---|---|---|
+| `presenter/src/host/settings/download.rs` 的行描述 | 能（`format!` + `DEFAULT_MAX_CONCURRENCY` / `MAX_CONCURRENCY`） | 已改；**有快照时界面显示的就是这一份文案** |
+| `app-iced/src/pages/settings/download.rs` 的 `GROUP.rows` | 不能：`&'static [(&'static str, &'static str)]` 是编译期字面量，要改运行时生成得动 `Group` 的类型 | 只有「字符串还在」的探针（`the_downloads_rows_state_semantics_and_never_fake_a_current_value` 断言 `"1~64"` 在）：改常量不会红 |
+| `setting/keys.rs` 的 `SettingSpec.doc` | 不能：`doc: &'static str`（`spec.rs:183`），`concat!` 只吃字面量、插不进常量 | ✅ `the_key_docs_quote_the_real_limits`（`config.rs`）：把「1~64」「出厂 8」「出厂 3」与常量比对，改常量不改文案就红 |
+
+第二行的**地位变了（M201）**：它不再是产品界面上的数字来源——有快照时界面画的是第一行那份（用常量
+`format!` 出来的），`GROUP.rows` 只在没有快照的兜底屏出现，而且那里的量词是「出厂 / 可调」而不是「当前」。
+于是它现在的风险是「兜底演示行与常量不一致（演示屏说谎）」，不是「设置页骗人」。
+
+`SettingSpec.doc` 那一处**不是注释**：`catalog.rs` 会把它当 JSON schema 的 `description` 发出去
+（AI 工具与文档可见），所以它必须有守卫——这也是三处里唯一补上了守卫的一处。
+
+## 7. 没验的部分
+
+* **真实网络下的并发/重试行为未验**：守卫读的是 `Semaphore` 的真实许可数与 `attempts_for()` 的
+  配置读点；「2 条真连接同时下载时服务器只看到 2 条」和「某个源真的被试 3 次」没有在真网络下跑过
+  （离线回环能验连接复用，验不了限流的端到端时序）。
+* **macOS / Linux 未验**：本轮只在 Windows 上编译与跑测试。
+* **`download.gh_proxy` 的端到端只到「候选生成」为止**（键已合入，M197/M203 之后不再是「登记了但读不到」）：
+  三处各有守卫——core 的「调优 → 候选链」（`gh_proxy_override_reaches_the_profile_and_the_chain`）、
+  CLI 的「文件 → 候选链」（`the_gh_proxy_setting_reaches_the_candidate_chain`）、GUI 的「文件 → 宿主 →
+  core 三态」（`the_gh_proxy_key_travels_from_the_file_to_the_core_tri_state`）。**没验的是真网络下那个前缀
+  能不能通**：离线只验候选链的生成，没发过一次真的 `gh-proxy.com` 请求。
+* **真机上的手点交互没验**（设置页自 M201 起已是真控件；M193 时期文档里那句「这一组只能看、改不了」已作废）：
+  Downloads 组的行来自 presenter 快照（`presenter::host::settings::groups` → `CoreEvent::SettingsChanged` →
+  `pages::Model.settings`），画的是 choice chip / 文本输入 + 「应用」/ 动作按钮，写回走
+  `AppCommand::SetSetting`；没有快照时（harness / `pages_demo` / 首帧）才退回 `GROUP.rows` 那几行语义演示行。
+  本次（M207）只读了代码与单测，没在 GPU 窗口里点过 chip / 输入 / 应用，也没量过「点了以后界面何时变」
+  （设计是**不做乐观回显**，只认 host 发回的快照——这一点同样没在真机上确认过）。
+* **UA 里的联系方式在真站点上的后果未知**（M207）：`User-Agent` 现在只有一份定义
+  （`core::download::http::USER_AGENT` = `Unlucky-Launcher/ (+仓库 URL)`），
+  两条 HTTP 路径发的是同一个字符串。证据只在**离线回环**上（发出去的字节 ==
+  `EngineConfig::default().user_agent`）；**没有向 Modrinth / CurseForge 发过一条带新 UA 的真实请求**，
+  限流阈值、CF 会不会因为多了 `(+URL)` 而拒、Modrinth 是否会因此放宽，全部未知。
diff --git a/docs/images/downloads-settings-zh.png b/docs/images/downloads-settings-zh.png
new file mode 100644
index 0000000..e3cef2d
Binary files /dev/null and b/docs/images/downloads-settings-zh.png differ
diff --git a/docs/images/instances-en-light.png b/docs/images/instances-en-light.png
new file mode 100644
index 0000000..ef98929
Binary files /dev/null and b/docs/images/instances-en-light.png differ
diff --git a/docs/images/linux-x64-wslg-window.png b/docs/images/linux-x64-wslg-window.png
new file mode 100644
index 0000000..bd972fa
Binary files /dev/null and b/docs/images/linux-x64-wslg-window.png differ
diff --git a/docs/images/logs-folder-zh.png b/docs/images/logs-folder-zh.png
new file mode 100644
index 0000000..ce11eda
Binary files /dev/null and b/docs/images/logs-folder-zh.png differ
diff --git a/docs/logs-location.md b/docs/logs-location.md
new file mode 100644
index 0000000..7f790c0
--- /dev/null
+++ b/docs/logs-location.md
@@ -0,0 +1,94 @@
+# 日志在哪（M188）
+
+一句话：**启动器自己写的东西全在 `<数据根>/logs/` 一个目录里**，游戏自己的东西在实例运行目录里。
+设置页那行「日志文件夹」显示的就是前者的绝对路径，旁边有 *打开文件夹* 与 *复制路径*；日志页页头
+也有 *打开文件夹*。两个入口走同一个落点（`crates/app-iced/src/app/logs_folder.rs`），失败时输出的
+文本带完整路径。
+
+## 1. 三个数据模式下的绝对路径
+
+`<数据根>` 由 `core::platform::data_dir` 的三模式解析（便携 / 标准 / 自定义）：
+
+| 模式 | 启动器数据目录（= `<数据根>`） | 日志根 |
+|---|---|---|
+| portable | `/.ULL` | `/.ULL/logs` |
+| standard | Windows `%APPDATA%\ULL` · macOS `~/Library/Application Support/ULL` · Linux `$XDG_DATA_HOME/ULL`（缺省 `~/.local/share/ULL`） | `<上者>/logs` |
+| custom | `<自定义根>/.ULL` | `<自定义根>/.ULL/logs` |
+
+GUI 的 `--data-dir ` 是 custom 模式的一种入口：那时日志根是 `/.ULL/logs`。设置页显示的
+路径与 `launcher.log` 的实际落点取的是**同一份解析结果**（`SettingsBridge` → `/config/launcher.json`
+→ ``），所以两者不会各说各话。
+
+## 2. 目录里有什么
+
+| 路径 | 写者 | 是什么 |
+|---|---|---|
+| `logs/launcher.log` | `core::launch::launcher_log` | 启动器自己的运行日志：启动拍（主题 / 语言 / 路由 / 窗口）、后端探测与降级、字体链、每一次启动的命令行事实 / spawn 结果 / 退出码、打开日志目录等用户动作的结果。 |
+| `logs/launcher.1.log` | 同上（滚动） | 上一份日志。**只留一份**历史。 |
+| `logs/game/.jsonl` | `core::launch::session` | 每次启动一份 JSONL 事件流（命令行已脱敏、每行 stdout/stderr、退出、诊断）。 |
+| `logs/game/index.jsonl` | `core::launch::session_index` | 一会话一行摘要的索引，日志页左栏读它。 |
+| `logs/install.log` | `presenter::host::install_journal` | 安装流水，每阶段一行。 |
+| `logs/session-log-location.json` | `presenter::host::logs::note_location` | 会话日志现在在哪 / 以前在哪 / 搬没搬（`moved: 0`），每次启动重写。 |
+| `data/agent/sessions/game/…` | **旧版本** | 只读兼容，见 §4。 |
+
+### 上限与滚动
+
+- 单文件上限 `launcher_log::MAX_BYTES = 1 MiB`；每次追加前检查，超过就把 `launcher.log` 改名成
+  `launcher.1.log`（旧的那份被替换），新文件从 0 开始。
+- 保留份数：**1**。所以 `logs/` 里启动器日志的稳态占用 ≤ 约 2 MiB（+ 同目录的会话 jsonl）。
+- 为什么不做按日期滚动：事故复现往往在「刚刚那一次」，份数比历史长度更重要；而无限份数会让「导出
+  诊断包」变成搬砖。
+
+## 3. 哪些行进 launcher.log、哪些只进 stderr
+
+判据（复审后收紧成这一句）：**逐帧度量不接；显式取证开关与一次性事故行可接**。实现是
+`crates/app-iced/src/app/diag.rs` 的 `diag!` 宏（stderr + 文件双写，行首 `[tag]` 就是日志里的 scope）。
+
+| 进 launcher.log | 只进 stderr |
+|---|---|
+| 启动编排：`[probe]`（`request=… -> ICED_BACKEND=…`、降级重开、探测耗时）、`[font]`、`[theme]`、`[appearance]`、`[gpu]` 的降级与拒绝降级、`[boot]`（含后端 request/effective）、`[shot]` 的通道提示 | 验收/出图矩阵的**逐帧度量**：`[window]` / `[perf]` / `[caps]` / `[theme] source=…`（`renderer::acceptance/**`，一次启动上百行，会冲掉事故现场） |
+| **一次性事故行**：`[gpu]  初始化失败（具名）` 与 `[gpu] 失败详情（具名）`（`renderer::report_failure`，复审 P2-1）、`[gpu] : …Selected: AdapterInfo…`（`renderer/log_bridge.rs` 转出的 wgpu 日志）、`[gpu-preflight]`（`ULL_PREFLIGHT=1`） | 组件几何探针的断言输出（`components/**` 的 `[feedback-probe]`、gallery 页面里的 `[gallery]`） |
+| 用户动作的结果：`[logs]`（打开日志文件夹成功/失败）、`[settings]` 写盘失败、`[i18n]` 语言没落盘、`[update]` 的忽略/重启、`[agent]` / `[content]` / `[page]` 的落点提示 | 每条日志行的正文里再套的括号（不是标签） |
+| 显式开关下的一次性行：`[tick]`（`ULL_TICK_TRACE=1`，≈1 行/秒，约 4.8 小时才滚一次）、`[corner]`（`app/update/appearance.rs` 打，`platform/win32/corner.rs` 只负责 `format_line`）、`[appearance]` / `[theme]` 的切换 | — |
+
+`[corner]` 到底在哪一侧，看**打印点**：唯一打印点是 `app/update/appearance.rs`（走 `diag!`），
+`platform/win32/corner.rs::format_line` 只拼字符串、不打印 ⇒ 它**进** launcher.log。
+
+## 3.1 还没接进日志的行（本 mission 之外）
+
+- `renderer::acceptance/**` 的 `[window]` / `[perf]` / `[caps]`：逐帧/矩阵取证，按上面的判据**故意不接**。
+- `components/**` 的几何探针（`[feedback-probe]` / `[gallery]`）：测试通道，不进产品日志。
+
+（`renderer/mod.rs` 的 `report_failure`、`renderer/log_bridge.rs`、`renderer/preflight.rs`、
+`probe.rs:apply_with_preflight` 已在 M188 复审后接上。）
+
+## 4. 会话日志搬家：策略是**不搬**
+
+M188 把新会话从 `data/agent/sessions/game/` 挪到 `logs/game/`（目录名里的 `agent` 是历史遗留，
+它从来只装游戏会话）。旧目录的处理方式：
+
+- **原样保留、继续读**：`presenter::host::logs` 与 `cli` 的会话读取都是两个根合并，同一个
+  `session_id` 同时存在时以 `logs/` 那条为准；
+- **不搬、不删**：搬运用户已有数据是不可逆动作，中途失败会留下半份会话，崩溃弹窗里的会话关联也会断；
+- **留记录**：`logs/session-log-location.json` 写明两个根、旧根在不在、旧根里几个文件、`moved: 0`、
+  `policy: "read-only-compat"`。
+
+## 5. 游戏自己的日志（不归启动器写）
+
+在实例的运行目录里（隔离实例是 `<游戏目录>/versions/<隔离名>/…`，共享实例直接是 `.minecraft`）：
+
+- `logs/latest.log`、`logs/<日期>-<序号>.log.gz` —— 游戏自己的日志；
+- `crash-reports/crash-*.txt` —— **只在 JVM 活到崩溃处理器那一步时才有**；
+- `hs_err_pid*.log` —— JVM 自己崩（native crash）时才写。
+
+模组 / 缺库 / Java 选错把游戏弄死在 Minecraft 初始化之前时，上面三个都不会出现——那不是启动器
+丢了日志，而是游戏没机会写。那种时候的证据是 `logs/game/.jsonl` 与 `logs/launcher.log`。
+
+## 6. 没验的部分
+
+- **真机「双击启动后日志确实在」**：本轮只在开发机上用 `cargo test` 与本地进程验证，Windows 桌面
+  双击启动需要用户实测。
+- **macOS / Linux 的日志根**：路径由同一条解析链给出（`standard_launcher_home` 有单测覆盖三个平台），
+  但「Mac 上点打开文件夹真的会开 Finder」「Linux 上没有 `xdg-open` 时会怎样」没有真机验证。
+- **只读数据目录**：日志写不进去时按设计静默放过（best-effort），此时设置页显示的路径仍然正确，
+  但文件不存在。
diff --git a/packaging/README.md b/packaging/README.md
new file mode 100644
index 0000000..9bbab58
--- /dev/null
+++ b/packaging/README.md
@@ -0,0 +1,229 @@
+# 打包与发布工程（packaging/）
+
+单一真相源：**单文件产物矩阵 + 发布契约**。`.github/workflows/release.yml` 按本文实现，
+`packaging/make_artifacts.py` 是本地与 CI **共用**的打包脚本（同一份代码 → 同一套目录布局）。
+本目录只放发布工程资产（脚本 / 说明 / 发布说明模板），不参与任何 crate 的编译。
+
+## 索引：§1–§12 各在哪份文件（M145 拆分）
+
+拆分原因：本文件与 `.github/workflows/release.yml` 都已是 400 行整，下一处改动必撞全仓行数红线（`guards.yml` 的
+`file-size`，单文件 ≤400 行）。按主题分开后每份都留出余量，**内容一字未改、只搬家**；**节号沿用原编号**，
+所以全仓那些「`packaging/README.md` §4 / §7.4 / §9」式引用不必改动 —— 按下表找承载文件即可。
+
+| 节 | 主题 | 承载文件 |
+|----|------|---------|
+| §1 | 产物矩阵 | `packaging/docs/artifacts-and-version.md` |
+| §2 | 版本来源（唯一真相源） | `packaging/docs/artifacts-and-version.md` |
+| §3 | 怎么构建（本地 / CI） | `packaging/docs/build-and-ci.md` |
+| §4 | 每平台运行时依赖 | `packaging/docs/runtime-deps.md` |
+| §5 | 软渲染兜底 | `packaging/docs/runtime-deps.md` |
+| §6 | Cargo 构建档位 | `packaging/docs/profiles-and-measurements.md` |
+| §7 | 实测（本机，不是估算） | `packaging/docs/profiles-and-measurements.md` |
+| §8 | 发行合规 | `packaging/docs/compliance-support-boundaries.md` |
+| §9 | 支持矩阵（对外口径） | `packaging/docs/compliance-support-boundaries.md` |
+| §10 | 已知边界 / 后续 | `packaging/docs/compliance-support-boundaries.md` |
+| §11 | CI 运行时冒烟（Linux 真渲染一帧） | 本文下方（细节在 `packaging/ci-runtime-smoke.md`） |
+| §12 | 文件清单 | 本文下方 |
+
+本文件仍是**契约的唯一真相源入口**：`.github/workflows/release.yml`（及拆出的 `release-build.yml` /
+`release-publish.yml`）的注释、`make_artifacts.py` 的说明、根 `README.md` / `README.zh-CN.md` 与
+`packaging/release-notes.md` 都按「`packaging/README.md` §N」引用。改契约时先改上表对应的承载文件，
+再看一眼 §12 的行数预算 —— 任何一份超过 400 行都要继续按主题拆。
+
+## 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 / 尺寸 / 非空白，artifact
+`runtime-smoke-screenshot`）。
+
+要点三条：
+
+- 只看退出码不够：「合法 PNG + 退出码 0」不等于画面有内容；「完全没字体」与「非软渲染」都是**硬失败**（panic /
+  报错，不产生 PNG；review 实测）。
+- 闸门下限 ≈「至少画出一条标题栏」（review 实测切片仍 pass）：证明「场景被真实渲染过」，**不证明界面元素齐全，
+  更不证明视觉正确**——视觉靠人眼看 artifact。
+- 只覆盖 Linux x64；macOS 是 dispatch-only 探针（无实测证据），Windows 已有本机人眼验收。
+- （M184）`linux-x64` 已进发布名单，所以这条**同类**判据也常驻在发布流水线里：`release-build.yml` 的
+  `Linux x64 运行时冒烟` 步用同一个 `check_screenshot.py` 判 release 产物的首帧，外加 `[theme]` /
+  `[backend] final=… result=started` 两行日志断言。证据账（含真机 WSLg 实测输出）在
+  [`packaging/docs/linux-evidence.md`](docs/linux-evidence.md)。
+
+**本地复跑**：`bash packaging/linux-smoke-docker.sh . D:/tmp/ull-smoke`——脚本逐步复刻这个 job（同样的 apt 依赖、
+`--bin unlucky-launcher-iced`、同样的 `xvfb-run … --software-renderer --screenshot --data-dir`）；输出目录别写 `/tmp`，
+Git Bash 下会静默落进 Docker VM（脚本内部用 `cygpath -m` 归一）。
+**M131 真跑过一次**（本机 Docker / Debian 12 容器 / 2026-11-05）：`exit=0`，截图 1180×760、`[ok] 截图非空白`。
+
+## 12. 文件清单
+
+| 文件 | 作用 | 行数上限 |
+|------|------|---------|
+| `packaging/README.md` | 本文：索引 + §11–§16（契约入口；§1–§10 见 `docs/`） | ≤400 |
+| `packaging/docs/artifacts-and-version.md` | §1 产物矩阵 + §2 版本来源 | ≤400 |
+| `packaging/docs/build-and-ci.md` | §3 怎么构建（本地 / CI） | ≤400 |
+| `packaging/docs/runtime-deps.md` | §4 每平台运行时依赖 + §5 软渲染兜底 | ≤400 |
+| `packaging/docs/profiles-and-measurements.md` | §6 Cargo 构建档位 + §7 实测 | ≤400 |
+| `packaging/docs/compliance-support-boundaries.md` | §8 发行合规 + §9 支持矩阵 + §10 已知边界 | ≤400 |
+| `packaging/make_artifacts.py` | 打包与校验（本地 + CI 共用） | ≤400 |
+| `packaging/release-notes.md` | GitHub Release 说明模板（`{{VERSION}}` / `{{SUMS}}` 占位） | ≤400 |
+| `packaging/check_screenshot.py` | 截图非空白判定（CI 门禁 + 本地手动跑，零第三方依赖） | ≤400 |
+| `packaging/check_gpu_shot.py` | GPU 截图证据判定（M249）：`[shot] … renderer=wgpu` + `Selected: AdapterInfo` 的 `device_type ∉ {Cpu, Other}` + PNG 非空/尺寸对账/非空白，逐条点名；`--expect-refuse` 判拒绝降级出图；`--self-test` 跑 `tests/gpu_shot_vectors.json` 的 19 条向量（脚手架 `tests/gpu_shot_selftest.py`）。CI 接线见下一行（M253），口径与能证/不能证见 `docs/gpu-evidence.md` | ≤400 |
+| `.github/workflows/gpu-evidence.yml` | GPU 证据门禁接线（M253）：`selftest` **无条件**跑 `--self-test` + 三个退出码 0/1/2；`probe` 探测可用产物与硬件适配器；`evidence` 只在 `needs.probe.outputs.available == 'true'` 时跑真判据 —— **无 GPU / 无产物时它整块显示 skipped（不是绿色 ✓）**，原因写进 job summary 并打 `::warning::`（跳过 ≠ 通过）。新开文件而不是并进 `guards.yml`：那份已 399/400 行，`release-build.yml` 正好 400。**dev 线复用**（r1 P2-1）：`dev-guards.yml` 里 `uses:` 同一份，dev 上只落 `selftest` 那一半 | ≤400 |
+| `packaging/tests/gpu_shot_ci_selftest.py` | 上一条的**接线自检**（M253，r1+r2 返工）：10 条判据 —— ① 五步按 `id:` 必须在场且无条件（`vectors`/`exitcodes`/`wiring`/`detect`/`judge`，`exitcodes` 还得真断言 0/1/2）；② 自测步必须**指向本脚本且是单条命令**（`|| echo 先忽略` 无从下手）；③ **解析 `if:` 表达式求值**判「判定挂门」（`available` 取 `'true'`/`'false'`/`''` 必须真/假/假，认不出即红）；④ 两种调用形态都在场且产物来自 `needs.probe.outputs.*`；⑤ **判据步真跑两次**（正例必须 0、CPU 档必须非 0，`bash -e` 与裸 bash 两种模式）；⑥ 跳过路径**实跑 7 种输入**；⑦ `continue-on-error` 按 YAML 布尔语义判；⑧ 吞码标记表（兜底）；⑨ `probe.outputs.*` 必须逐个绑到 `steps.detect.outputs.*`；⑩ `on:` 必须同时有 `push`（含 `main`）/`pull_request`/`workflow_call`。外加 **33 条变异向量**（`tests/gpu_shot_ci_vectors.json`：r1 复审表 20 条 + 1 条补充 + r2 复审 12 条）逐条必须当场红。**不覆盖**：不自守、载体依赖：整个 `gpu-evidence.yml` 被删掉/替换后，**没有任何东西会跑这个自检** —— 守门人住在被守对象自己的文件里（`guards.yml` 已经 399/400 行，塞不进去）。求值器与 GitHub 语义的差异、判据 4 的「合法调用替换」。**自 2026-11-11 起停止加固**，扩项须由人类新开 mission | ≤400 |
+| `packaging/tests/gpu_shot_ci_expr.py` | 上面判据 ③ 的**小求值器**：给 `needs.probe.outputs.available` 取 `'true'`/`'false'`/`''`，门必须分别判真/假/假 —— 门还挂不挂由**语义**决定，不由子串决定。只认 `==`/`!=`/`&&`/`||`/括号/字符串/`needs..outputs.<名>`/`true|false|null`/四个无参函数；`!` 与其余写法一律抛错（调用方按红处理）。不是 GitHub 语义的替身，是它的保守子集 | ≤400 |
+| `packaging/tests/gpu_shot_ci_probe.py` | 上面判据 ⑤⑥ 的**执行脚手架**：把 `detect` / `judge` 两步的 `run:` 原文落盘、用桩 env 起 bash。`detect` 跑 7 种输入，断言 `$GITHUB_OUTPUT` 的 `available` / summary 文案 / `::warning::` / 三条「点了名却找不到 ⇒ 必须红」；`judge` 跑两次（正例必须 0、CPU 档必须非 0，两种 bash 模式），一次封掉 `\|\| echo` / `; :` / 管道 / `if !` / `true # 原行` 整类「绿而没判」。找不到能跑的 bash 即判红（不降级） | ≤400 |
+| `packaging/tests/gpu_shot_ci_vectors.json` | 接线自检的变异向量：**33 条**，按**解析后的结构**注入（`step_delete`/`job_delete`/`step_set`/`job_set`/`path_set`/`trigger_set`/`run_append`/`run_replace`，`also` 可叠加），每条写明应红的判据名；来源见文件里的 `_note` | ≤400 |
+| `packaging/tests/gpu_shot_vectors.json` | `check_gpu_shot.py --self-test` 的向量：19 条（红 16 / 绿 3），每条给出**期望的失败判据清单**，数据与代码分开 | ≤400 |
+| `packaging/tests/gpu_shot_selftest.py` | 上面那 19 条向量的执行器（按真实行格式手拼日志 + 用 `check_screenshot.encode_png` 现造 PNG）：判据脚本自己守 ≤400 行，脚手架放这里 | ≤400 |
+| `packaging/check_publish_slots.py` | 发布名单守卫（M164/M184）：名单 ⇄ 产物两个方向 + `mode: ci` 槽位无产物的警告；`--self-test` 注入 11 条回归 | ≤400 |
+| `packaging/check_pe_subsystem.py` | PE 子系统守卫（M196）：**读产物 PE 头的 `Subsystem`**（GUI 必须 2 / CLI 必须 3），非 2 即红；`--self-test` 注入 8 条回归（红 6 / 绿 2）（见 §15） | ≤400 |
+| `packaging/check_test_source_off.py` | 测试通道守门（M169）：workflow / 打包脚本 / `Cargo.toml default` 都不许打开 `update-test-source`；归属按 `jobs.*.steps[]` 列表项判、默认拒绝；`--self-test` 按 `tests/guard_vectors.json` 注入 | ≤400 |
+| `packaging/check_test_key_off.py` | 测试公钥守门（M190 r3）：把公开的测试公钥并进信任表的那条 feature 只许出现在 `crates/core/Cargo.toml` 自己的声明与 `crates/presenter/Cargo.toml` 的 `[dev-dependencies]` 段内，其余（workflow / 打包脚本 / 根 `Cargo.toml` / `.cargo/config*.toml` / presenter 的 `[dependencies]`）出现即红；`--self-test` 注入 7 条向量（5 红 / 2 绿）+ 基线；其中一条专治「core 的声明里偷偷带子 feature」（`update-test-key = ["update-test-source"]` ⇒ 红） | ≤400 |
+| `packaging/tests/guard_vectors.json` | 守门自测向量（基线 + 32 条：26 红 / 6 绿），数据与代码分开 | ≤400 |
+| `packaging/check_signing_ready.py` | 签名就绪度播报（M255）：**只读**、零第三方依赖，三行读数 —— ① `PRODUCTION` 表空不空（解析 `PINNED-KEYS` 标记之间）② 环境里有没有钥（`ULL_MANIFEST_SIGNING_KEY` / `--key`，顺手对账「这把钥在不在表里」，**种子一个字节都不打印**）③ 最近一次发布的 `.sig`/清单痕迹（取不到写「未知」，不写「无」）。退出码 `0` 就绪 / `1` 未就绪（打印「这会让已安装用户永远验不过（fail-closed）」+ 一行修复命令）/ `2` 用法错（含标记丢了 —— 那时形不成判断） | ≤400 |
+| `packaging/tests/signing_ready_selftest.py` | 上一条的判据自测（M255）：表空必 `exit 1` 且三行都打印 / **副本**夹一条假 `PinnedKey` 变 `exit 0`（不碰真实 `trust.rs`）+ 不泄种子 / ② 对账 / ③ 有-无-未知（含 `.sig` 子串假读数）/ **`--key` 读不了 = 2**（不许 traceback + 1）/ **非 main ref 的 ② 写「未判定」不写「没配」** / 输出里的 `§N` 必须是 runbook 真实章节 / `--line` 写 summary / **两个方向的变异重放**（「退出码永远 0」⇒ 判据①必须红；「永远 1」⇒ 判据②必须红）。不覆盖：整个 workflow 被删后没人跑它（与 `gpu_shot_ci_selftest.py` 同一条边界） | ≤400 |
+| `packaging/tests/signing_ready_wiring_selftest.py` | 上上条的**接线**自测（M255 r1 分出，只为 400 行红线）：没有别的 workflow `uses:` 它 / 全文无 error 级注解 / 就绪度那步 `rc=$?` 后 `exit 0` / 文件头两句口径都在 / **生产种子只在 `refs/heads/main` 注入**（注入行必须是 `github.ref == 'refs/heads/main' && secrets.…` 条件式；`on:` 块里不许出现 `pull_request`；非 main 必须给 `ULL_SIGNING_KEY_WITHHELD` 原因串）/ **文档指针存在性**（`signing-runbook.md` 与 `signing.md` 里的 `packaging/…`、`crates/…`、`.github/…` 路径必须真在仓库里）。三处变异重放：去掉 ref 门 / 加回 `pull_request` / 改坏文档路径 ⇒ 对应用例必须红 | ≤400 |
+| `.github/workflows/signing-status.yml` | 就绪度**播报**接线（M255）：把三行搬进 job summary。**不是门禁**：未就绪用 `::warning::`、就绪度那步**恒 `exit 0`**、**不应被设为 required**、刻意不声明 `workflow_call:`（别人没法 `uses:` 它，接线自检另外扫全仓防「顺手接进 dev 线」）。**安全边界（r1 P2-1）**：`ULL_MANIFEST_SIGNING_KEY` 只在 `refs/heads/main` 上注入（条件式 env），且**没有 `pull_request` 触发** —— 仓库内分支的 PR 拿得到 Secret 而 CI 跑的是 PR 自己的代码，种子进过那种运行等于交给任何能推分支的人；非 main ref 由 `ULL_SIGNING_KEY_WITHHELD` 说明原因，于是 ② 读「未判定」不是「没配」。同 job 另有两步跑自测（会红 = 尺子坏了，与「未就绪」分开写）。新开文件而不是并进 `guards.yml`：那份已 399/400 行 | ≤400 |
+| `packaging/docs/signing-runbook.md` | **人类照做**的签名手册（M255）：现状读数 → 5 步下单清单（生成钥 / Secret 名字逐字 / 贴 `PinnedKey` / 发带 `.sig` 的 Release / `--verify-pinned` 回验）→ 每步判据 → 11 条已知坑 → 发布后回验 → 播报≠门禁 → **没验的部分**（Authenticode、托管签名、真机更新端到端、本手册命令未真跑）。不含任何真实密钥，全是占位符 | ≤400 |
+| `packaging/ci-runtime-smoke.md` | §11 的细节：断言口径/阈值依据/失效模式/复跑 | ≤400 |
+| `packaging/docs/linux-evidence.md` | Linux 槽位的证据账（M184）：现有证据盘点、WSLg 真机实测输出、xvfb 复跑、CI 增量估算、未验清单 | ≤400 |
+| `packaging/docs/gpu-evidence.md` | GPU 截图证据账（M249 + §8 CI 接线 M253：无 GPU 显式跳过、跳过 ≠ 通过、21 条接线变异）：判据逐条「抓得住什么/抓不住什么」、本机实跑退出码、**能证**（字形栅格与边缘 AA / 面板 α 与玻璃 / 两后端一致性）与**不能证**（首帧与帧率 / 整窗 α 与圆角观感，走 DWM 任何截图都拍不到）、历史 `--diff` 基线永久不可复核 | ≤400 |
+| `packaging/linux-smoke-docker.sh` | 本地复跑 `runtime-smoke`（Docker + xvfb） | ≤400 |
+| `packaging/linux-check-docker.sh` | 本地复跑 `ci.yml` 的两条 ubuntu 门禁（clippy / test，Docker） | ≤400 |
+| `.github/workflows/release.yml` | tag 触发 → 选槽位（`plan`）→ 调下面两个可复用工作流 | ≤400 |
+| `.github/workflows/release-build.yml` | `workflow_call`：单槽位构建（体检 / cargo / 打包 / 上传 artifact） | ≤400 |
+| `packaging/make_manifest.py` | 更新清单 `manifest.json` 的生成与自验（D50，见 §13） | ≤400 |
+| `packaging/tests/manifest.golden.json` | 清单 golden 样例：`make_manifest.py --self-test` 逐字节对拍 | ≤400 |
+| `.github/workflows/release-publish.yml` | `workflow_call`：发布（`PUBLISH_SLOTS` 裁剪 / SHA256SUMS / 清单 / Release） | ≤400 |
+
+## 13. 更新清单 `manifest.json`（D50）
+
+清单作为**固定文件名**的 Release 资产挂着；客户端按 `releases/latest/download/manifest.json` 取（D50）。
+字段形状的唯一权威是 `crates/core/src/update/manifest.rs` 的 `ReleaseManifest`（`deny_unknown_fields` +
+逐字段校验：semver、`size > 0`、摘要长度/字符集、`target`/`format` 取值表）——生成器只负责把那套形状填对。
+
+- **生成器**：`packaging/make_manifest.py`（零第三方依赖）。CI 在 `release-publish.yml` 里**重算
+  `SHA256SUMS.txt` 之后**调它，所以清单描述的是「真正要发的资产」，不是「构建出来的全部」。
+- **同源，不双写**：每个 `sha256` 直接读 `SHA256SUMS.txt`，`size` 取自同一批文件的 `stat()`；产物名里的版本段
+  必须等于 `--version`（tag 与 `Cargo.toml` 漂了就没有产物可对，当场失败）。`--self-test` 用
+  `packaging/tests/manifest.golden.json` 逐字节对拍，并跑 14 条负例证明严格解析不是摆设。
+- **只放启动器产物**：`ull` 不进清单。DTO 的 `Artifact` 没有角色字段，`Release::artifact_for()` 取「第一个
+  target 命中的产物」，把 CLI 并列写进去会让「该覆盖哪个文件」取决于数组顺序（`ull` 照旧进 `SHA256SUMS.txt`）。
+- **`url` 两种形态**：默认裸文件名（相对源根，`DirSource` 口径，本地/内网用）；CI 传 `--asset-base-url`
+  拼绝对地址，且**钉 tag 不钉 latest**——清单里每条都指向与它自报版本相符的字节。
+- `min_supported` / `notes` 只是**可填而不默认填**：前者是「收回老版本支持」的发布策略（未拍板，写错会强制升级），
+  后者在 Release 正文里已有，两处各写一份迟早漂。
+- 本地复跑：`python3 packaging/make_artifacts.py --manifest` → 与 CI 同一段代码，产出 `dist/manifest.json`。
+
+**D51 定案（2026-11-06，方案甲）+ M163 语义修正（2026-11-07）**：GitHub 的 `releases/latest/download/*`
+只指向**非 prerelease** 的最新 Release。而自更新清单固定取 `releases/latest/download/manifest.json`，所以
+「新版本必须被标成稳定版，latest 才会指过去」——M163 之前 push tag 默认打 `--prerelease`，v0.2.2 因此至今
+`releases/latest` 404、更新通道取不到清单。现在的语义（唯一真相源 `packaging/release_marker.py`）：
+
+| 触发 | create（新建 Release） | edit（Release 已存在） |
+| --- | --- | --- |
+| `push` tag `v*`（含其 Re-run） | **稳定版**（不带标记） | 不碰标记 |
+| `workflow_dispatch` + `prerelease=true` | 预发布 | 显式改成预发布 |
+| `workflow_dispatch` + `prerelease=false`（默认） | 稳定版 | 显式改成稳定版 |
+
+`v0.2.2` 那个 Release **保留为历史预发布不动**，稳定通道以 `v0.2.3` 为起点。发版 checklist 第六件 =
+确认 prerelease 标记与通道一致（`gh release view  --json isPrerelease`），守门是
+`packaging/check_release_semantics.py`（CI：`.github/workflows/release-guard.yml`）。
+
+## 14. 更新链路的测试通道（`update-test-source`，M169）
+
+「发现新版本 → 下载 → 长度 + SHA256 双检 → 就位」这条链要能在**发布档（release）**上验收，就得让
+二进制能指向本地更新源；而这条能力同时是「离任意本地目录最近的一条路」（终点是替换用户盘上的 exe），
+所以它必须是**编译期**的，不是运行期设置项：
+
+- **默认关**：`update-test-source` 是 `crates/core` / `cli` / `presenter` / `app-iced` 各一条 feature，
+  默认不启用。官方发布构建不带它 ⇒ `core::update::job::default_source` 里那段分支**根本编不进来**
+  （README 的「release builds do not contain that path at all」就是这么成立的）。
+- **验收构建**：`cargo build --release --features update-test-source`，再配
+  `ULL_UPDATE_DIR=` + `ULL_UPDATE_TEST_SOURCE=1`（两档缺一不可）。`ull update check --json` 会
+  如实写 `data.source: "file:"`、`data.test_source: true`，人读输出另有一行点名。
+- **守门**：`packaging/check_test_source_off.py`（CI：`.github/workflows/release-guard.yml`，两步：
+  `--self-test` + 正式扫描）扫 `.github/workflows/**`（含复合 action）、`packaging/**` 的递归脚本、
+  `Makefile`/`justfile`/`Taskfile` 与各 `Cargo.toml` 的 `default`。**唯一允许**出现该 feature 的地方是
+  `.github/workflows/ci.yml` 里名为 `update-e2e` 的那一步，且该步必须带 `--test update_e2e_test`
+  （文件名 / 步骤名 / 参数任一不符即红，见脚本的 `ALLOWED_STEP`）。
+  归属按 **`jobs.*.steps[]` 的列表项**判（不是「最近一行 `- name:`」）：落不到具名步骤上的行——`jobs:`
+  之前的孤儿行、项外键、没有 `name:` 的步骤、flow 风格步骤——**一律判红**（默认拒绝）。自测向量在
+  `packaging/tests/guard_vectors.json`（32 条向量：26 条注入必须红 + 6 条合法写法必须绿，另加基线必须绿；
+  条数以 `--self-test` 输出为准）。`.cargo/config*.toml` 也在扫描面里：`--cfg feature="…"` 与
+  `rustc-wrapper` 都能绕过 `--features`（后者一律判红，合法用途要 review 明确同意）。
+  抓不住（如实记）：变量间接拼接（`FEAT="update-""test-source"`）、**两步 `$GITHUB_ENV` 交接**
+  （第一步把 feature 写进 env、第二步只用 `--features "$FEAT"`——第二步没有字面量，任何静态扫描都
+  看不见，这是本守门的固有边界，不是漏判）、feature 改名后接回发布、`build.rs` 里 spawn cargo、以及
+  「把别的步骤**改名**成 `update-e2e` 并带 `--test update_e2e_test` 却干别的事」。
+- 验收本体：`cargo test --release -p unlucky-cli --features update-test-source --test update_e2e_test
+  --test update_e2e_tamper_test`（正路 + 幂等 / 篡改摘要 + 篡改包体 + 截断）。CI 里同一个命令挂在
+  `ci.yml` 的 `update-e2e` job（**只在 Windows**：夹具的「真形状」是 Windows 裸 `.exe` +
+  `portable-exe`；Linux/macOS 的真实产物是 `.tar.gz` + `portable-zip`，在本模块会被直接拒）。
+  **不验**真 GitHub 下载、GUI 点击与重启替换（需人工）。
+
+## 15. 产物 PE 子系统（M196：GUI 必须 `WINDOWS_GUI`=2）
+
+群友 2026-11-08 实测发布构建「运行时会带一个控制台窗口在底下」。根因：产物 PE 头的 `Subsystem` 仍是
+CUI(3)，`grep -rn windows_subsystem crates/` 当时零命中。同一个修复 2026-11-01 做过一次（`37d3039`），
+但只改了 `crates/app/src/main.rs`——那棵树自 M118 起被 workspace `exclude`、不进发布矩阵，所以那一笔
+**从未到达产物**。教训不是「忘了写属性」，而是没有一步去看产物本身。
+
+- 修在哪：`crates/app-iced/src/main.rs` 顶上的 `#![cfg_attr(windows, windows_subsystem = "windows")]`。
+  PE 子系统是**每个 bin 目标**的属性，`cfg_attr` 是它的原生长相；不放 `build.rs` 是因为那里要绕
+  `cargo:rustc-link-arg` 间接改链接命令行，且会把「这条 bin 是 GUI」挪到看不见 `[[bin]]` 声明的地方。
+- 代价与补救：GUI 子系统进程**不继承**父进程控制台，stdout/stderr 在 cmd 里是 0 号无效句柄。所以
+  `main()` 第一步调 `AttachConsole(ATTACH_PARENT_PROCESS)`（`crates/app-iced/src/platform/win32/console.rs`，
+  四种启动情形的实测表在该文件顶部）：重定向/管道两个句柄本来就可用（一个字节都不动）、cmd 里直接跑
+  附着后输出落进控制台、双击时附着失败且**绝不新建窗口**。
+- 守门：`python3 packaging/check_pe_subsystem.py --gui  --cli `，读 `MZ`→`e_lfanew`(`0x3C`)→
+  `PE\0\0`→COFF 头→可选头 `+0x44` 的 2 个字节，打印**文件偏移**（release 产物实测：`Subsystem=2
+  (WINDOWS_GUI) @ 文件偏移 0xDC`，`e_lfanew=0x80`、PE32+）。两向断言：GUI 产物必须 2，CLI 产物
+  `ull.exe` 必须仍是 3（CONSOLE）——反方向不守时，把属性贴错 crate 会被漏掉，而 `ull --version | …`
+  会静默丢输出。
+- 接在哪：`.github/workflows/release-build.yml`（发布侧，两个 Windows 槽位各跑一次）与
+  `.github/workflows/ci.yml` 的 `build` job（PR 阶段就红，不必等到 tag）。
+- 抓不住（如实记）：只看那 4 个字节，不看 GUI 双击的实际观感——「不再多一个黑框」在本仓库的验证环境
+  （RDP / 无干净无控制台桌面）只能由 PE 头 + 进程/窗口枚举间接证明，人眼验收归真机。
+- **既无控制台也不重定向的宿主：输出照旧无处可去，退出码不变**（M196 r2 实测，反驳 r1 复审 P2-3 的
+  「退出码会变成 `EXIT_INTERNAL`(2)」——那条是**纯推理、无实测**）。两个**近似**形态 × 两条命令，
+  `child_exit_code` 全是 **0**：① 父进程有 std 句柄、子进程不继承（`dwFlags=0` + `bInheritHandles=FALSE`）；
+  ② 父进程 `FreeConsole()` 后把 `in/out/err` 三个 std 句柄全置 0，再起子进程（子进程侧实测
+  `stdin/stdout/stderr = 0x0`、`AttachConsole` 返回 0 / `GetLastError=6`）。原因在 Rust std 的 Windows
+  实现：句柄取不到时 `Write`/`flush` 直接返回 `Ok`（独立探针实测 `SetStdHandle(out)` = `0x0` / `0x1234` /
+  `(HANDLE)-1` 三种取值，`write=Ok(())`、`flush=Ok(())` 全成立），所以 `crates/cli/src/runner.rs` 那条
+  「写失败 ⇒ `EXIT_INTERNAL`」的分支不会被触发。结论：本 diff **没有**给 CLI 退出码引入可观察差异；
+  真正的差异只有「没控制台就没人看得见输出」这件事本身。
+  **边界（别把上面读成「真服务也测过」）**：①② 都只是**近似**形态——真 SCM 服务与计划任务（session 0、
+  no window station）、`start /b`、Windows Terminal / ConPTY 全部**未测**；对它们的结论只能靠「句柄无效
+  时 std 写返回 `Ok`」这条机制外推，不是在那些形态里亲测。第三方交叉（**复审的读数，不是我跑的**）：
+  r1 复审在 r2 用更干净的形态（父 `FreeConsole()` + 三句柄置 0 + 子进程
+  `DETACHED_PROCESS | dwFlags=0 | bInheritHandles=FALSE`）独立复现，产品二进制 `--version` /
+  `instances list` / `--help` 全 0（`logs list` 是 1，但重定向跑同一条也是 1 ⇒ 用户错误，不是写失败）。
+  想让这种情形有专属退出码/文案，得在 CLI 侧显式判一次能力（`platform::win32::console` 的
+  `output_visible()` 就是现成判据），那在 `crates/cli/**`、不在 M196 的 scope 内——这里只如实记录形态。
+
+## 16. 产物署名与清单签名（M190）
+
+**编号来历（M203）**：本节原先也编作 §14，与 §14「更新链路的测试通道（M169）」撞号。撞号按「谁后插进来谁让位」
+处理：M169 的 §14 与 M196 的 §15 都被仓库里的引用钉着（`packaging/check_test_source_off.py` 引 §14；
+`.github/workflows/release-build.yml` 与 `crates/app-iced/src/platform/win32/console.rs` 引 §15），
+所以本节后移编 §16 并放到文末——**内容一字未改，只改了编号和位置**。
+
+这一节只放「去哪看」的三句话，手册本体在 **`packaging/docs/signing.md`**：
+
+- **PE 版本资源**（Windows「属性 → 详细信息」里的发布者/产品/版权/四段式版本）：口径唯一来源
+  `packaging/pe_version.rs`，被 `crates/cli/build.rs` 与 `crates/app-iced/build.rs` 各 `include!` 一次；
+  判据是**读产物字节**的 `packaging/check_pe_version.py`（CI：`release-build.yml` 的 Windows 槽位）。
+- **清单签名**：`manifest.json.sig` 与 `manifest.json` 并列上传，是分离的 Ed25519 签名文件（签的是清单
+  的**原始字节**，不是某个规范化后的 JSON）。信任锚是 `crates/core/src/update/trust.rs` 里的
+  **编译期公钥数组**（keyring）；源里没有 `.sig`、钥不在表里、签名对不上，一律 `signature_*` 分类拒装，
+  **不可重试**。签名脚本 `packaging/sign_manifest.py`（零第三方依赖，`--self-test` 跑 RFC 8032 向量）。
+- **签名就绪度与操作步骤（M255）**：今天 `PRODUCTION` 表在 `PINNED-KEYS` 标记之间是**空的** ⇒ 任何正式
+  二进制都验不过任何清单（fail-closed）。读数一条命令：`python3 packaging/check_signing_ready.py`
+  （三行 + `0/1/2`，未就绪时打印一行修复命令）；CI 里同一条读数在 `signing-status.yml` 的 job summary
+  上，**那是播报不是门禁**（不应设为 required）。要动手做的那 5 步在
+  [`docs/signing-runbook.md`](docs/signing-runbook.md)（不含任何真实密钥）。
+- **不得混淆**：项目自有签名解决的是「更新器怎么判断这份清单是不是我们发的」，**不解决 SmartScreen**
+  ——用户双击 exe 时看到的「未知发布者」要等 Authenticode 证书，那是另一条线。
diff --git a/packaging/check_gpu_shot.py b/packaging/check_gpu_shot.py
new file mode 100644
index 0000000..694063a
--- /dev/null
+++ b/packaging/check_gpu_shot.py
@@ -0,0 +1,313 @@
+#!/usr/bin/env python3
+"""GPU 截图证据判定（M249）：把「这张图真是 GPU 档出来的」变成机器判据，而不是靠人读日志。
+
+为什么需要它：M246 实测到 `--renderer=gpu` 落到 RX 6600 XT / Vulkan（DiscreteGpu）并出图，但那份
+结论是**人读 258 行日志**得出的。日志少一行、`Selected` 换了适配器、PNG 是上一次的残留，人眼复核
+一遍就得重来。本脚本把那套判据固定成三分钟能复跑一遍的门禁，且**缺哪条就点名哪条**。
+
+入参 = 一份 stderr 日志 + 一张 PNG（可选 `--expect-refuse` 走负例口径）。正例六条判据（每条抓得住
+什么、抓不住什么见 `packaging/docs/gpu-evidence.md` §2）：
+
+1. **全部** `[shot] … renderer=` 行都是 `wgpu`——不是「出现过」（把 CPU 那次的 stderr `>>` 拼进来
+   就会骗过旧写法），也**不是** `[probe] renderer = wgpu`：后者只是启动前的意图，M246 的 A6 负例里
+   它照样打印 wgpu，却一个像素都没画。
+2. `Selected: AdapterInfo { … device_type: X }` 的 `X` 不在 `DISALLOWED_DEVICE_TYPES` 内；
+   **取不到 `X` 也算失败**（多行 Debug 漂移不许静默给绿）。
+3. PNG 能解码且像素数 > 0。
+4. PNG 宽高 = 日志里 `[shot] W×H` 声明的宽高（把图和日志钉在一起）。
+5. `[backend] final=wgpu result=started`（后端自己的结论行与上面几条不矛盾）。
+6. PNG 过 `check_screenshot.py` 的非空白判据（复用它的解码器与阈值，不复制第二份）。
+
+`--expect-refuse` 是负例口径（M246 的 A6）：要求 `[backend] final=… via=refuse`、**没有**任何
+`[shot]` 出图行、且目标 PNG 不存在。它证明「该拒绝时真拒绝了」，不证明「GPU 能出图」。
+
+零第三方依赖；PNG 只解码一次，用的是同目录 `check_screenshot.py` 的 `decode_png` / `measure` / `verdict`。
+
+用法::
+
+    python packaging/check_gpu_shot.py shot.stderr.log shot.png       # 正例：判定，0/1 退出
+    python packaging/check_gpu_shot.py a6.stderr.log --expect-refuse  # 负例：判定拒绝是否成立
+    python packaging/check_gpu_shot.py --self-test                    # 19 条向量（数据+脚手架都在 tests/）
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+import zlib
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))  # 同目录 import（-m 方式调用时也要成立）
+from check_screenshot import (  # noqa: E402
+    DEFAULT_MIN_EDGE_RATIO,
+    DEFAULT_MIN_STDDEV,
+    DEFAULT_MIN_UNIQUE,
+    PngError,
+    decode_png,
+    measure,
+    verdict,
+)
+
+#: 这些 `device_type` 等于「不是硬件 GPU」：`Cpu` = WARP/软渲染适配器，`Other` = 未分类（本机那条
+#: `Other` 是 Gl 兼容层）。用 `not in` 而不是 `in {DiscreteGpu, IntegratedGpu}`，与
+#: `crates/app-iced/src/probe.rs:165-167` 的硬件判据同口径：`VirtualGpu` 之类新词条不会因为本脚本
+#: 没登记就被当成「不是硬件」。反过来，把 `Cpu` 从这张禁令里拿掉正是最想抓的回归（向量第 3 条）。
+DISALLOWED_DEVICE_TYPES = frozenset({"Cpu", "Other"})
+
+#: 截图行里的 renderer。只认 `[shot]` 行 —— `[probe] renderer = …` 是启动前的意图，不是结果。
+SHOT_RENDERER_RE = re.compile(r"^\[shot\][^\n]*?\brenderer=(\S+)", re.MULTILINE)
+#: `[shot] 1180x760 scale=1 -> …`：出图行声明的像素尺寸。
+SHOT_SIZE_RE = re.compile(r"^\[shot\]\s+(\d+)x(\d+)\b", re.MULTILINE)
+#: `[gpu] …compositor: Selected: AdapterInfo { … }`：真正建出来的那块适配器。这两处约束不是洁癖：
+#: 每份日志里还有一行 `[probe] 取证：出现 …Selected: AdapterInfo…` 的**提示文本**（含同样几个字、
+#: 但没有 `{`），锚 `^\[gpu\]` + 要求紧跟 `{` 才不会被那行骗过去。
+SELECTED_RE = re.compile(r"^\[gpu\][^\n]*Selected:\s*AdapterInfo\s*\{(?P[^\n]*)", re.MULTILINE)
+ADAPTER_NAME_RE = re.compile(r'name:\s*"([^"]*)"')
+DEVICE_TYPE_RE = re.compile(r"device_type:\s*(\w+)")
+ADAPTER_BACKEND_RE = re.compile(r"backend:\s*(\w+)")
+#: `[backend] final=… result=… … via=…`：后端自己的结论行。
+BACKEND_FINAL_RE = re.compile(r"^\[backend\] final=(\S+)\s+result=(\S+)(?P[^\n]*)", re.MULTILINE)
+VIA_RE = re.compile(r"\bvia=(\w+)")
+
+#: 判据编号 → 标签。编号是报告里的次序，也在 `--self-test` 的向量里被逐条点名。
+LABELS = {
+    1: "截图行 renderer=wgpu",
+    2: "Selected: AdapterInfo 的 device_type 不是 Cpu/Other",
+    3: "PNG 能解码且非空",
+    4: "PNG 宽高 = 日志 [shot] 的宽高",
+    5: "后端结论行 final=wgpu result=started",
+    6: "PNG 不是空白帧",
+    7: "后端结论行 via=refuse",
+    8: "没有出图行（[shot] 尺寸 + renderer 都不该有）",
+    9: "目标 PNG 不存在（拒绝出图就该一张都没有）",
+}
+
+
+class Report:
+    """逐条判据的结论。失败时由 `print_report` 逐条点名，绝不只印一个 FAILED。"""
+
+    def __init__(self) -> None:
+        self.items: list[tuple[int, bool, str]] = []
+
+    def add(self, criterion: int, ok: bool, detail: str = "") -> bool:
+        self.items.append((criterion, ok, detail))
+        return ok
+
+    def problems(self) -> list[str]:
+        return [LABELS[criterion] for criterion, ok, _detail in self.items if not ok]
+
+    def print_report(self, log_path: Path, png_path: Path | None) -> None:
+        for criterion, ok, detail in self.items:
+            print(f"{'[ok]' if ok else '[fail]'} {criterion}. {LABELS[criterion]}" + (f"：{detail}" if detail else ""))
+        target = str(log_path) if png_path is None else f"{log_path} + {png_path}"
+        problems = self.problems()
+        if problems:
+            print(f"[fail] 判据没过 {len(problems)}/{len(self.items)} 条（{target}）", file=sys.stderr)
+        else:
+            print(f"[ok] {len(self.items)} 条判据全过（{target}）")
+
+
+def read_log(path: Path) -> str:
+    """日志按 UTF-8 读、坏字节替换 —— 判据只看 ASCII 标记，不该因为一行中文乱码就崩。"""
+    return path.read_text(encoding="utf-8", errors="replace")
+
+
+def shot_renderers(text: str) -> list[str]:
+    return SHOT_RENDERER_RE.findall(text)
+
+
+def shot_size(text: str) -> tuple[int, int] | None:
+    match = SHOT_SIZE_RE.search(text)
+    return (int(match.group(1)), int(match.group(2))) if match else None
+
+
+def _pick(pattern: re.Pattern[str], text: str, default: str | None = "?") -> str | None:
+    match = pattern.search(text)
+    return match.group(1) if match else default
+
+
+def selected_adapter(text: str) -> dict[str, str | None] | None:
+    """只取 `Selected:` 那一行：`Available adapters: [...]` 里有 12 条 `AdapterInfo`，取错就全错。
+
+    `device_type` 取不到时返回 `None`（**不是** `"?"`）：一旦 iced 改成 pretty-print Debug，
+    字段就落不到 `{` 同一行，此时按「取不到 = 判红」处理，不许静默给绿（M249 r1 P2-1）。
+    """
+    match = SELECTED_RE.search(text)
+    if match is None:
+        return None
+    body = match.group("body")
+    return {
+        "name": _pick(ADAPTER_NAME_RE, body),
+        "device_type": _pick(DEVICE_TYPE_RE, body, None),
+        "backend": _pick(ADAPTER_BACKEND_RE, body),
+    }
+
+
+def backend_final(text: str) -> dict[str, str] | None:
+    match = BACKEND_FINAL_RE.search(text)
+    if match is None:
+        return None
+    via = VIA_RE.search(match.group("rest"))
+    return {"final": match.group(1), "result": match.group(2), "via": via.group(1) if via else ""}
+
+
+def decode_shot(png_path: Path, report: Report) -> tuple[int, int, dict | None]:
+    """解码 PNG 并核对像素数，返回 (宽, 高, 统计)。读不出就记一条失败并返回 0 尺寸。"""
+    try:
+        width, height, rows, channels = decode_png(png_path)
+    except (PngError, OSError, zlib.error) as error:
+        report.add(3, False, f"读不出 {png_path}：{error}")
+        return 0, 0, None
+    pixels = width * height
+    report.add(3, pixels > 0, f"{width}x{height} = {pixels} 像素")
+    return (width, height, measure(width, height, rows, channels)) if pixels > 0 else (width, height, None)
+
+
+def judge_evidence(log_path: Path, png_path: Path) -> Report:
+    """正例口径：这份日志 + 这张 PNG 能不能当「GPU 档真的出了这一帧」的证据。"""
+    report = Report()
+    try:
+        text = read_log(log_path)
+    except OSError as error:
+        report.add(1, False, f"日志读不出 {log_path}：{error}")
+        return report
+
+    renderers = list(dict.fromkeys(shot_renderers(text)))
+    # 「这张图是 wgpu 出的」= 日志里**每一行** `[shot] … renderer=` 都说 wgpu。用 `in` 就退化成
+    # 「曾经出现过」：把 CPU 那次的 stderr `>>` 追加进来、配 CPU 那张图，会静默判绿（M249 r1 P2-2）。
+    report.add(
+        1,
+        set(renderers) == {"wgpu"},
+        "实际 renderer=" + "/".join(renderers) if renderers else "日志里没有 `[shot] … renderer=…` 行（没走到出图那一步？）",
+    )
+
+    adapter = selected_adapter(text)
+    if adapter is None:
+        report.add(2, False, "日志里没有 `Selected: AdapterInfo { … }`（wgpu 没建成设备，或只打印了 Available adapters）")
+    else:
+        device_type = adapter["device_type"]
+        # `None` = 字段不在 `{` 同一行（多行 Debug 漂移）或字段缺失：按取不到即失败处理，
+        # 宁可假红也不许「格式一变就静默给绿」。
+        report.add(
+            2,
+            device_type not in (None, "?") and device_type not in DISALLOWED_DEVICE_TYPES,
+            f'device_type={device_type}（{adapter["name"]} / {adapter["backend"]}）'
+            if device_type not in (None, "?")
+            else "取不到 device_type：`Selected: AdapterInfo {` 与字段不在同一行（多行 Debug），或字段缺失",
+        )
+
+    width, height, stats = decode_shot(png_path, report)
+
+    size = shot_size(text)
+    if size is None:
+        report.add(4, False, "日志里没有 `[shot] WxH …` 出图行，尺寸无从对账")
+    elif width == 0:
+        report.add(4, False, f"PNG 没解出来，无法核对日志声明的 {size[0]}x{size[1]}")
+    else:
+        report.add(4, (width, height) == size, f"日志 {size[0]}x{size[1]} vs PNG {width}x{height}")
+
+    final = backend_final(text)
+    if final is None:
+        report.add(5, False, "日志里没有 `[backend] final=…` 行（ULL_ACCEPTANCE=1 才有）")
+    else:
+        report.add(
+            5,
+            final["final"] == "wgpu" and final["result"] == "started",
+            f"final={final['final']} result={final['result']}" + (f" via={final['via']}" if final["via"] else ""),
+        )
+
+    if stats is None:
+        report.add(6, False, "上一步没解出像素，无从统计")
+    else:
+        blank = verdict(stats, DEFAULT_MIN_UNIQUE, DEFAULT_MIN_STDDEV, DEFAULT_MIN_EDGE_RATIO)
+        report.add(
+            6,
+            not blank,
+            f"唯一色 {stats['unique_colors']} 亮度σ {stats['luma_stddev']} 强边缘 {stats['edge_ratio']}",
+        )
+    return report
+
+
+def judge_refuse(log_path: Path, png_path: Path | None) -> Report:
+    """负例口径：这次启动是不是**确实拒绝**降级出图（而不是悄悄换后端出了一张）。"""
+    report = Report()
+    try:
+        text = read_log(log_path)
+    except OSError as error:
+        report.add(7, False, f"日志读不出 {log_path}：{error}")
+        return report
+
+    final = backend_final(text)
+    if final is None:
+        report.add(7, False, "日志里没有 `[backend] final=…` 行")
+    else:
+        report.add(7, final["via"] == "refuse", f"final={final['final']} result={final['result']} via={final['via'] or '<缺>'}")
+
+    renderers = list(dict.fromkeys(shot_renderers(text)))
+    size = shot_size(text)
+    surplus = (["renderer=" + "/".join(renderers)] if renderers else []) + (
+        [f"[shot] {size[0]}x{size[1]}"] if size is not None else []
+    )
+    report.add(8, not surplus, "存在出图行：" + "、".join(surplus) if surplus else "")
+
+    if png_path is None:
+        return report
+    if png_path.exists():
+        report.add(9, False, f"{png_path} 存在（{png_path.stat().st_size} 字节）")
+    else:
+        report.add(9, True, f"{png_path} 不存在")
+    return report
+
+
+def main(argv: list[str]) -> int:
+    args = list(argv)
+    positional: list[str] = []
+    expect_refuse = False
+    while args:
+        arg = args.pop(0)
+        if arg == "--expect-refuse":
+            expect_refuse = True
+        elif arg == "--self-test":
+            sys.path.insert(0, str(Path(__file__).resolve().parent / "tests"))
+            from gpu_shot_selftest import run_selftest  # 延迟 import：脚手架反过来要拿本模块的判据函数
+
+            return run_selftest(judge_evidence, judge_refuse)
+        elif arg in ("-h", "--help"):
+            print(__doc__)
+            return 0
+        elif arg.startswith("-"):
+            print(f"::error::不认识的参数：{arg}", file=sys.stderr)
+            return 2
+        else:
+            positional.append(arg)
+
+    if not positional:
+        print("::error::至少要给一份 stderr 日志（--help 看用法）", file=sys.stderr)
+        return 2
+    if len(positional) > 2:
+        print(f"::error::最多两个位置参数（日志 + PNG），实际 {len(positional)} 个", file=sys.stderr)
+        return 2
+    log_path = Path(positional[0])
+    png_path = Path(positional[1]) if len(positional) == 2 else None
+    if png_path is None and not expect_refuse:
+        print("::error::正例必须给出那张 PNG（只有负例可用 --expect-refuse 省略）", file=sys.stderr)
+        return 2
+
+    report = judge_refuse(log_path, png_path) if expect_refuse else judge_evidence(log_path, png_path)
+    report.print_report(log_path, png_path)
+    return 1 if report.problems() else 0
+
+
+# ────────────────────────── 自测 ──────────────────────────
+#
+# 向量数据在 `packaging/tests/gpu_shot_vectors.json`，造样本与逐条比对的脚手架在
+# `packaging/tests/gpu_shot_selftest.py`（判据脚本自己守 ≤400 行，脚手架不占这里的行数）。
+# 每条的 `expect_fail` 是**期望的失败判据清单**，逐条对：关掉一条判据、或让某条判据被别的
+# 东西掩盖，清单就对不上。真图不在仓库里（`DevDocs/` 被 ignore），所以这颗钉子守判据，真实
+# 产物由报告里的实跑退出码守。
+
+if __name__ == "__main__":
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(errors="backslashreplace")
+    sys.exit(main(sys.argv[1:]))
diff --git a/packaging/check_pe_subsystem.py b/packaging/check_pe_subsystem.py
new file mode 100644
index 0000000..7027950
--- /dev/null
+++ b/packaging/check_pe_subsystem.py
@@ -0,0 +1,311 @@
+#!/usr/bin/env python3
+"""PE 子系统守卫（M196）：**读产物 PE 头的 `Subsystem` 字段**，不许用「代码看起来对」代替。
+
+起因：群友 2026-11-08 实测发布构建「运行时会带一个控制台窗口在底下」。根因是产物 PE 头的
+`Subsystem` 仍是 CUI(3)——`grep -rn windows_subsystem crates/` 当时**零命中**。这个修复在
+2026-11-01 做过一次（`37d3039`），但打在已退役的 Slint 树（`crates/app`，M118 起被 workspace
+`exclude`、不进发布矩阵），所以从未到达 iced 产物。教训不是「忘了属性」，而是**没有任何一步
+去看产物本身**：源码层面怎么写都可能被别的树顶替，只有读那 4 个字节是事实。
+
+两向断言（一条也不许静默）：
+
+1. **GUI 产物必须是 `Subsystem == 2`（`WINDOWS_GUI`）**：`unlucky-launcher-iced.exe`。
+   是 3 就意味着双击会多一个控制台宿主窗口——正是本 mission 要修的那个 bug。
+2. **CLI 产物必须是 `Subsystem == 3`（`CONSOLE`）**：`ull.exe`。它靠真控制台做 stdout/stderr，
+   谁把 `windows_subsystem = "windows"` 抄到它头上，`ull --version | …` 就会静默丢输出。
+   反方向同样要红：只守一个方向时，把属性贴错 crate 会被漏掉。
+
+读法（零第三方依赖，PE32 与 PE32+ 都吃）：`MZ` → `e_lfanew`(偏移 `0x3C`) → `PE\\0\\0` →
+COFF 头 20 字节 → 可选头起点 → `Subsystem` 在可选头 `+0x44`（两种 magic 一致）。
+读数含**文件字节偏移**，报告里贴的是真实位置，不是「我读过了」。
+
+用法（本地与 CI 同一份代码）：
+
+    python3 packaging/check_pe_subsystem.py --gui target/release/unlucky-launcher-iced.exe \\
+                                            --cli target/release/ull.exe
+    python3 packaging/check_pe_subsystem.py --self-test    # 合成 PE 桩，断言该红的红（8 条：红 6 / 绿 2）
+
+`--self-test` 是这条守门的自测证据：它造合成 PE 头（GUI / CUI / 非 MZ / 截断 / 缺文件），
+断言「GUI 读成 3 ⇒ 红」「CLI 读成 2 ⇒ 红」「两边都对 ⇒ 绿」——共 **8 条用例（红 6 / 绿 2）**，
+另加一条「Subsystem 真落在报出来的那个偏移上」的偏移自证。守门抓不住回归时它自己先红。
+"""
+
+from __future__ import annotations
+
+import struct
+import sys
+import tempfile
+from pathlib import Path
+
+#: PE 签名（`e_lfanew` 处那四个字节）。
+PE_SIGNATURE = b"PE\0\0"
+
+#: `IMAGE_OPTIONAL_HEADER.Subsystem` 在可选头里的偏移（PE32 与 PE32+ 同一个位置）。
+SUBSYSTEM_OFFSET = 0x44
+#: 想要的两种取值。
+WINDOWS_GUI = 2
+CONSOLE = 3
+
+SUBSYSTEM_NAMES = {
+    0: "UNKNOWN",
+    1: "NATIVE",
+    2: "WINDOWS_GUI",
+    3: "CONSOLE",
+    5: "OS2_CUI",
+    7: "POSIX_CUI",
+    9: "WINDOWS_CE_GUI",
+    10: "EFI_APPLICATION",
+    11: "EFI_BOOT_SERVICE_DRIVER",
+    12: "EFI_RUNTIME_DRIVER",
+    14: "XBOX",
+    16: "WINDOWS_BOOT_APPLICATION",
+}
+
+#: 可选头 magic → 人话（只用于打印，判据不看它）。
+MAGICS = {0x10B: "PE32", 0x20B: "PE32+", 0x107: "ROM"}
+
+
+class PeError(Exception):
+    """读 PE 头失败（不是 PE / 被截断）—— 同样是红的理由，不许当成「跳过」。"""
+
+
+class PeInfo:
+    """一次读数：值 + 它在文件里的位置（位置进报告，是「真读过」的凭据）。"""
+
+    __slots__ = ("path", "subsystem", "file_offset", "e_lfanew", "magic", "machine")
+
+    def __init__(self, path: Path, subsystem: int, file_offset: int, e_lfanew: int, magic: int, machine: int):
+        self.path = path
+        self.subsystem = subsystem
+        self.file_offset = file_offset
+        self.e_lfanew = e_lfanew
+        self.magic = magic
+        self.machine = machine
+
+    @property
+    def name(self) -> str:
+        return self.path.name
+
+    def describe(self) -> str:
+        return (
+            f"[pe] {self.name}: Subsystem={self.subsystem} "
+            f"({SUBSYSTEM_NAMES.get(self.subsystem, '?')}) @ 文件偏移 0x{self.file_offset:X}"
+            f"（e_lfanew=0x{self.e_lfanew:X}，{MAGICS.get(self.magic, f'0x{self.magic:X}')}，"
+            f"可选头+0x{SUBSYSTEM_OFFSET:X}，machine=0x{self.machine:X}）"
+        )
+
+
+def read_subsystem(path: Path) -> PeInfo:
+    """读 PE 可选头的 `Subsystem`。任何一步对不上都抛 [`PeError`]，绝不返回「猜的值」。"""
+    if not path.is_file():
+        raise PeError(f"{path} 不存在（构建步没跑？还是产物名改了？）")
+    with path.open("rb") as handle:
+        dos = handle.read(0x40)
+        if len(dos) < 0x40:
+            raise PeError(f"{path} 只有 {len(dos)} 字节，连 DOS 头都不够（文件被截断？）")
+        if dos[0:2] != b"MZ":
+            raise PeError(f"{path} 不是 PE：开头是 {dos[0:2]!r}，不是 b'MZ'")
+        e_lfanew = struct.unpack_from(" PeInfo | None:
+    """按角色断言一个产物的子系统；不匹配就往 `errors` 里写一条带文件注解的 error。"""
+    try:
+        info = read_subsystem(path)
+    except PeError as exc:
+        errors.append(f"::error::{role} 读数失败：{exc}")
+        return None
+    print(info.describe())
+    if info.subsystem != expected:
+        want = SUBSYSTEM_NAMES.get(expected, str(expected))
+        got = SUBSYSTEM_NAMES.get(info.subsystem, str(info.subsystem))
+        hint = {
+            WINDOWS_GUI: "双击会多一个控制台宿主窗口（M196 要修的就是这个）",
+            CONSOLE: "CLI 的 stdout/stderr 会静默丢失（ull 靠真控制台）",
+        }.get(expected, "")
+        errors.append(
+            f"::error file={path}::{role} 的 PE 子系统应为 {expected}（{want}），"
+            f"实际读到 {info.subsystem}（{got}）@ 偏移 0x{info.file_offset:X}；{hint}"
+        )
+    return info
+
+
+def main(argv: list[str]) -> int:
+    gui: Path | None = None
+    cli: Path | None = None
+    args = list(argv)
+    while args:
+        arg = args.pop(0)
+        if arg == "--gui" and args:
+            gui = Path(args.pop(0))
+        elif arg == "--cli" and args:
+            cli = Path(args.pop(0))
+        elif arg == "--self-test":
+            return self_test()
+        elif arg in ("-h", "--help"):
+            print(__doc__)
+            return 0
+        else:
+            print(f"::error::不认识的参数（或缺少取值）：{arg}", file=sys.stderr)
+            return 2
+    if gui is None and cli is None:
+        print("::error::至少要给 --gui  或 --cli ", file=sys.stderr)
+        return 2
+
+    errors: list[str] = []
+    if gui is not None:
+        check("GUI", gui, WINDOWS_GUI, errors)
+    if cli is not None:
+        check("CLI", cli, CONSOLE, errors)
+    for error in errors:
+        print(error, file=sys.stderr)
+    if errors:
+        return 1
+    print(
+        f"OK: PE 子系统符合预期（GUI={WINDOWS_GUI} {SUBSYSTEM_NAMES[WINDOWS_GUI]}"
+        f" / CLI={CONSOLE} {SUBSYSTEM_NAMES[CONSOLE]}）"
+    )
+    return 0
+
+
+# ────────────────────────── 自测：合成 PE 桩 ──────────────────────────
+
+
+def synth_pe(subsystem: int, *, pe32_plus: bool = True, signature: bytes = b"PE\0\0", mz: bytes = b"MZ") -> bytes:
+    """造一个只够本脚本读的 PE 头（不执行、不链接，只让 `Subsystem` 落在正确位置）。"""
+    e_lfanew = 0x80
+    buf = bytearray(0x200)
+    buf[0:2] = mz
+    struct.pack_into(" int:
+    failures = 0
+    with tempfile.TemporaryDirectory(prefix="ull-pe-subsystem-") as tmp:
+        root = Path(tmp)
+
+        def write(name: str, data: bytes) -> Path:
+            path = root / name
+            path.write_bytes(data)
+            return path
+
+        cases: list[tuple[str, Path, int, bool]] = [
+            (
+                "基线：GUI 产物 Subsystem=2",
+                write("gui_ok.exe", synth_pe(WINDOWS_GUI)),
+                WINDOWS_GUI,
+                False,
+            ),
+            (
+                "回归：GUI 产物退回 CUI(3) —— 就是本次 bug 的形状",
+                write("gui_cui.exe", synth_pe(CONSOLE)),
+                WINDOWS_GUI,
+                True,
+            ),
+            (
+                "基线：CLI 产物 Subsystem=3",
+                write("cli_ok.exe", synth_pe(CONSOLE, pe32_plus=False)),
+                CONSOLE,
+                False,
+            ),
+            (
+                "回归：CLI 产物被贴成 WINDOWS_GUI(2)",
+                write("cli_gui.exe", synth_pe(WINDOWS_GUI)),
+                CONSOLE,
+                True,
+            ),
+            (
+                "回归：不是 PE（开头不是 MZ）",
+                write("not_pe.exe", synth_pe(WINDOWS_GUI, mz=b"ZZ")),
+                WINDOWS_GUI,
+                True,
+            ),
+            (
+                "回归：PE 头被截断",
+                write("truncated.exe", synth_pe(WINDOWS_GUI)[: optional_start_of(synth_pe(WINDOWS_GUI)) + 0x10]),
+                WINDOWS_GUI,
+                True,
+            ),
+            (
+                "回归：签名不是 PE\\0\\0",
+                write("bad_sig.exe", synth_pe(WINDOWS_GUI, signature=b"PX\0\0")),
+                WINDOWS_GUI,
+                True,
+            ),
+            (
+                "回归：文件根本不存在（构建步没跑）",
+                root / "missing.exe",
+                WINDOWS_GUI,
+                True,
+            ),
+        ]
+
+        for label, path, expected, want_red in cases:
+            errors: list[str] = []
+            check("SELFTEST", path, expected, errors)
+            got_red = bool(errors)
+            if got_red != want_red:
+                want = "红" if want_red else "绿"
+                print(
+                    f"::error::自测失败：{label} 应该{want}，实际 {'红' if got_red else '绿'}",
+                    file=sys.stderr,
+                )
+                failures += 1
+            else:
+                print(f"OK: {label} → {'红' if got_red else '绿'}")
+
+        # 位置读数本身也要对：GUI 桩的 Subsystem 必须正好落在报告的那个文件偏移上。
+        gui = write("offset.exe", synth_pe(WINDOWS_GUI))
+        info = read_subsystem(gui)
+        if gui.read_bytes()[info.file_offset : info.file_offset + 2] != struct.pack(" int:
+    """合成桩里可选头的起点（给「截断」用例算切点用）。"""
+    return struct.unpack_from("
+
+It is deliberately a *byte* check, not a "did the build script run" check: a resource that got lost
+in linking still fails here. `--expect-version` also compares `dwFileVersionMS/LS` with the crate
+version, so "version drifted from Cargo.toml" is caught.
+
+    python3 packaging/check_pe_version.py ... --expect-version 0.2.3
+    python3 packaging/check_pe_version.py --self-test
+"""
+
+from __future__ import annotations
+
+import argparse
+import struct
+import sys
+from pathlib import Path
+
+PE_MAGIC = bytes([0x50, 0x45, 0, 0])  # "PE" + two NUL
+FIXED_SIGNATURE = b"\xbd\x04\xef\xfe"  # FIXEDFILEINFO.dwSignature = 0xFEEF04BD
+PE_VERSION_SOURCE = Path(__file__).resolve().parent / "pe_version.rs"
+
+# 承诺的署名（与 packaging/pe_version.rs 同一份口径；`--self-test` 解析那个文件对拍）。
+EXPECTED_STRINGS = {
+    "CompanyName": "Unlucky Launcher Project",
+    "ProductName": "Unlucky Launcher",
+    "FileDescription": "Unlucky Launcher",
+    "LegalCopyright": "© 2026 Unlucky Launcher Project · Apache-2.0",
+}
+
+
+def utf16(text: str) -> bytes:
+    return text.encode("utf-16-le")
+
+
+def four_part(version: str) -> tuple[int, int, int, int]:
+    """`v0.2.3` / `0.2.3-beta.1` → `(0, 2, 3, 0)`（与 `pe_version.rs::four_part` 同规则）。"""
+    numeric = version.split("-")[0].split("+")[0].strip().lstrip("v")
+    parts = [0, 0, 0, 0]
+    for index, piece in enumerate(numeric.split(".")[:4]):
+        try:
+            parts[index] = min(int(piece), 0xFFFF)
+        except ValueError:
+            parts[index] = 0
+    return (parts[0], parts[1], parts[2], parts[3])
+
+
+def pe_subsystem(data: bytes) -> int | None:
+    """可选头里的 `Subsystem`（2 = GUI，3 = 控制台）；PE 头不对时返回 None。"""
+    if len(data) < 0x40 or data[:2] != b"MZ":
+        return None
+    offset = struct.unpack_from(" len(data) or data[offset : offset + 4] != PE_MAGIC:
+        return None
+    return struct.unpack_from(" list[str]:
+    """返回没过的判据（空 = 通过）。"""
+    failures: list[str] = []
+    data = path.read_bytes()
+    if len(data) < 0x100:
+        return [f"{path}: 文件太小（{len(data)} 字节），不像 PE"]
+
+    subsystem = pe_subsystem(data)
+    if subsystem is None:
+        return [f"{path}: 不是可解析的 PE（MZ / PE 头不对）"]
+
+    has_resource = FIXED_SIGNATURE in data
+    if not has_resource:
+        failures.append(f"{path}: 找不到 FIXEDFILEINFO 签名 0xFEEF04BD —— 这个 exe 里**没有版本资源**")
+
+    for key in ("VS_VERSION_INFO", "StringFileInfo", "VarFileInfo", "Translation"):
+        if utf16(key) not in data:
+            failures.append(f"{path}: 版本资源里缺结构键 `{key}`（UTF-16LE 未命中）")
+
+    for field, value in EXPECTED_STRINGS.items():
+        if utf16(field) not in data:
+            failures.append(f"{path}: 缺字段名 `{field}`")
+        if utf16(value) not in data:
+            failures.append(f"{path}: 字段 `{field}` 的值不是 `{value}`")
+
+    if utf16(f"{path.stem}.exe") not in data:
+        failures.append(f"{path}: `OriginalFilename` 不是 `{path.stem}.exe`")
+
+    if expect_version:
+        parts = four_part(expect_version)
+        dotted = ".".join(str(part) for part in parts)
+        if utf16(dotted) not in data:
+            failures.append(f"{path}: 版本字符串 `{dotted}` 不在资源里（与 Cargo.toml 不同源？）")
+        index = data.find(FIXED_SIGNATURE)
+        if index >= 0 and index + 16 <= len(data):
+            ms, ls = struct.unpack_from("> 16, ms & 0xFFFF, ls >> 16, ls & 0xFFFF)
+            if actual != parts:
+                failures.append(f"{path}: 数值版本 {actual} 与期望 {parts} 不一致（dwFileVersion）")
+        else:
+            failures.append(f"{path}: FIXEDFILEINFO 之后读不到 dwFileVersion")
+
+    print(
+        f"{path.name}: {len(data)} 字节 / subsystem={subsystem}（2=GUI 3=控制台）"
+        f" / 版本资源={'有' if has_resource else '无'}"
+    )
+    return failures
+
+
+def self_test() -> int:
+    """口径表与 `pe_version.rs` 对拍 + 版本换算 + 「假 PE 必须红」。"""
+    import os
+    import tempfile
+
+    failures = 0
+    source = PE_VERSION_SOURCE.read_text(encoding="utf-8")
+    for field, value in (
+        ("COMPANY_NAME", EXPECTED_STRINGS["CompanyName"]),
+        ("PRODUCT_NAME", EXPECTED_STRINGS["ProductName"]),
+        ("COPYRIGHT", EXPECTED_STRINGS["LegalCopyright"]),
+    ):
+        if f'pub const {field}: &str = "{value}";' not in source:
+            print(f"FAIL: pe_version.rs 里找不到 {field} = {value!r}", file=sys.stderr)
+            failures += 1
+
+    for case, expect in (("0.2.3", (0, 2, 3, 0)), ("v1.2.3-beta.4", (1, 2, 3, 0)), ("1.2.3.4", (1, 2, 3, 4))):
+        if four_part(case) != expect:
+            print(f"FAIL: four_part({case!r}) = {four_part(case)}，期望 {expect}", file=sys.stderr)
+            failures += 1
+
+    # 判据本身要能变红：造一个「像 PE 但没有版本资源」的最小文件，check() 必须报错
+    # （否则这个脚本对任何输入都会「绿」，门禁等于没有）。
+    fake = bytearray(0x200)
+    fake[0:2] = b"MZ"
+    struct.pack_into(" int:
+    parser = argparse.ArgumentParser(description="读产物字节断言 PE 版本资源（M190）")
+    parser.add_argument("artifacts", nargs="*", type=Path, help="要检查的 exe")
+    parser.add_argument("--expect-version", help="与 Cargo.toml 同源的版本号（如 0.2.3）")
+    parser.add_argument("--self-test", action="store_true", help="自检（口径表 + 版本换算 + 假 PE 必红）")
+    args = parser.parse_args(argv)
+
+    if args.self_test:
+        return self_test()
+    if not args.artifacts:
+        parser.print_help()
+        return 2
+
+    failures: list[str] = []
+    for artifact in args.artifacts:
+        if not artifact.is_file():
+            failures.append(f"{artifact}: 文件不存在")
+            continue
+        failures.extend(check(artifact, args.expect_version))
+
+    for line in failures:
+        print(f"error: {line}", file=sys.stderr)
+    if failures:
+        print(f"FAIL：{len(failures)} 条判据没过（版本资源没进产物就是没进，构建日志不算证据）", file=sys.stderr)
+        return 1
+    print(f"ok: {len(args.artifacts)} 个产物的版本资源齐全")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/packaging/check_publish_slots.py b/packaging/check_publish_slots.py
new file mode 100644
index 0000000..de52100
--- /dev/null
+++ b/packaging/check_publish_slots.py
@@ -0,0 +1,394 @@
+#!/usr/bin/env python3
+"""发布名单守卫（M164）：**名单声明与实际产物必须对得上**，两个方向都管。
+
+起因：`PUBLISH_SLOTS` 是唯一决定「哪几个槽位进 Release」的开关，而它此前只有一半是守住的 ——
+「名单里有、产物没有」会被 `release-publish.yml` 的齐全性检查拦下，但反方向**静默**：某个槽位（例如
+`windows-arm64`）真编出了产物、名单却还没声明它时，那些文件会在裁剪步被 `rm` 掉，日志里只有一行
+`drop:`，没有任何注解、也没有任何非零退出码。修复的那个 tag 里「arm64 其实已经能出包了」这件事就
+这么被吞掉，没人会注意到（M164 的任务清单点名要这条）。
+
+四条断言：
+
+1. **名单非空且可解析**：`release-publish.yml` 里必须有 `PUBLISH_SLOTS: "..."`。开关消失时不要静默
+   变成「一个都不发」。
+2. **名单里每一项都是矩阵槽位**：`release.yml` 的槽位表（`dict(slot=... )`）才是槽位的唯一定义。
+   名单里写错一个字（`windows-aarch64`）此前只会表现为「Release 侧什么也不匹配、齐全性检查红在别处」，
+   根因要翻两层日志；这条在 PR 阶段就把它点出来。
+3. **名单里每一项的 `mode` 都必须是 `ci`**：`mode: probe` 的槽位默认构建根本不跑，写进发布名单等于
+   每一轮都缺一档 —— 一个自己写死要红的组合。
+4. **产物 ⇄ 名单两个方向**（`--dist`，只在发布侧有产物时跑）：
+   - 名单声明了但没有 GUI 或 CLI 产物 ⇒ `::error::` + exit 1（少一档不发版）。声明为发布的多半就是 `mode: ci`
+     的槽位，所以这条同时是「**声明为 ci 的槽位构建红了必须挡住发布**」的判据 —— 红在 build 矩阵里的那一档不会
+     让发布跳过（`release` job 是 `always()`），挡住它的就是这里；
+   - 有产物但名单没声明 ⇒ `::warning::` 明说「未发布、会被裁掉」，**不许静默**（M184 起 `linux-arm64` 正好是
+     这一档：它 `mode: ci`、每轮都编，但运行时未验所以不在名单，产物留着取证）；
+   - `mode: ci` 却本次没有产物（且不在名单）⇒ 也打 `::warning::`：那一档的构建很可能红了，不能只表现为「表里少一行」；
+   - 无论哪种，最后都打一张全槽位表：发布 / 未发布（无产物）/ 未发布（名单没声明）。
+
+用法（零第三方依赖，本地与 CI 同一份代码）：
+
+    python3 packaging/check_publish_slots.py                       # 源码级断言（PR CI）
+    python3 packaging/check_publish_slots.py --dist dist --slots "$PUBLISH_SLOTS"
+    python3 packaging/check_publish_slots.py --self-test           # 注入回归，断言每条都变红
+
+`--self-test` 是这条守门的自测证据：把两个 workflow 复制进临时目录、造合成 dist，逐项注入真实回归
+（漏一个资产 / 名单拼错 / 名单写了 probe 档 / 名单声明了但产物缺 / 名单没声明却有产物 /
+`mode: ci` 却没产物 / 声明的 `linux-x64` 构建红了 / 提前把 `linux-arm64` 写进名单），断言守门
+该红的红、该只警告的不红。守门抓不住回归时它自己先红。
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+
+PACKAGING = Path(__file__).resolve().parent
+ROOT = PACKAGING.parent
+
+MATRIX_YML = Path(".github/workflows/release.yml")
+PUBLISH_YML = Path(".github/workflows/release-publish.yml")
+
+#: 槽位表条目（`plan` job 里那份）：`dict(slot="windows-x64", ..., mode="ci")`，一条可能跨两行。
+SLOT_RE = re.compile(r'dict\(\s*slot="(?P[^"]+)"(?P.*?)\)', re.S)
+MODE_RE = re.compile(r'mode="(?P[^"]+)"')
+#: 发布白名单那一行（yaml 里是 `PUBLISH_SLOTS: "windows-x64 linux-x64"`）。
+PUBLISH_RE = re.compile(r'^\s*PUBLISH_SLOTS:\s*"(?P[^"]*)"', re.M)
+
+#: 每个槽位必须**两样都有**：GUI 与 CLI 各自一个资产（只按「槽位名出现过」判会被其中一个掩盖）。
+ASSET_PREFIXES = (("unlucky-launcher", "GUI"), ("ull", "CLI"))
+
+
+def stem(slot: str) -> str:
+    """槽位键落到文件名里是下划线形态（`windows-arm64` → `windows_arm64`）。"""
+    return slot.replace("-", "_")
+
+
+# ────────────────────────── 读两个 workflow ──────────────────────────
+
+
+def matrix_slots(text: str) -> dict[str, str]:
+    """`release.yml` 的槽位表 → {槽位: mode}。表在 `plan` job 里，是槽位的唯一定义。"""
+    slots: dict[str, str] = {}
+    for match in SLOT_RE.finditer(text):
+        mode = MODE_RE.search(match.group("rest"))
+        slots[match.group("slot")] = mode.group("mode") if mode else ""
+    return slots
+
+
+def declared_slots(text: str) -> list[str] | None:
+    """`release-publish.yml` 的 `PUBLISH_SLOTS` → 槽位列表；整行不见了返回 `None`（区别于「空名单」）。"""
+    match = PUBLISH_RE.search(text)
+    return None if match is None else match.group("value").split()
+
+
+def parse_slots_arg(raw: str) -> list[str]:
+    """`--slots "windows-x64 windows-arm64"` 的取值解析（CI 直接透传 `$PUBLISH_SLOTS`）。"""
+    return raw.replace(",", " ").split()
+
+
+# ────────────────────────── 1~3. 源码级断言 ──────────────────────────
+
+
+def check_source(root: Path, expected: list[str] | None = None) -> list[str]:
+    problems: list[str] = []
+    matrix_path = root / MATRIX_YML
+    publish_path = root / PUBLISH_YML
+    for path in (matrix_path, publish_path):
+        if not path.is_file():
+            return [f"找不到 {path.relative_to(root)}（流水线搬家了？这条守门要跟着搬）"]
+
+    matrix = matrix_slots(matrix_path.read_text(encoding="utf-8"))
+    if not matrix:
+        return [f"{MATRIX_YML} 里读不到任何槽位（`dict(slot=...)` 的写法变了？槽位表是槽位的唯一定义）"]
+
+    declared = declared_slots(publish_path.read_text(encoding="utf-8"))
+    if declared is None:
+        return [f"{PUBLISH_YML} 里没有 `PUBLISH_SLOTS:` 这一行：发布白名单消失了（别让它静默变成「一个都不发」）"]
+    if not declared:
+        problems.append("`PUBLISH_SLOTS` 是空名单：任何一个槽位都不会进 Release 与 SHA256SUMS")
+    if expected is not None and expected != declared:
+        # 运行期实际用的名单必须就是文件里那一行（有人在步内覆盖 PUBLISH_SLOTS 时就对不上）。
+        problems.append(f"运行期名单 {expected} 与 {PUBLISH_YML} 里声明的 {declared} 不一致")
+
+    for slot in declared:
+        if slot not in matrix:
+            problems.append(
+                f"名单里的 `{slot}` 不是矩阵槽位（矩阵只有 {' / '.join(matrix)}）："
+                "写错一个字，裁剪步就一个也匹配不到，而齐全性检查会红在别处、根因埋两层"
+            )
+        elif matrix[slot] != "ci":
+            problems.append(
+                f"名单里的 `{slot}` 在矩阵里是 mode={matrix[slot]!r}（默认不构建）："
+                "声明为发布却默认不编，等于每一轮都缺一档"
+            )
+    return problems
+
+
+# ────────────────────────── 4. 产物 ⇄ 名单（发布侧） ──────────────────────────
+
+
+def assets_for(dist: Path, slot: str) -> dict[str, list[str]]:
+    """{资产前缀: 命中的文件名}——按 `make_artifacts.py::asset_stem()` 的命名规则找。"""
+    out: dict[str, list[str]] = {}
+    for prefix, _role in ASSET_PREFIXES:
+        out[prefix] = sorted(p.name for p in dist.glob(f"{prefix}_*_{stem(slot)}*") if p.is_file())
+    return out
+
+
+def check_dist(dist: Path, declared: list[str], matrix: dict[str, str]) -> tuple[list[str], list[str], list[str]]:
+    """返回 (errors, warnings, 表格行)。errors 非空 ⇒ 调用方 exit 1。"""
+    errors: list[str] = []
+    warnings: list[str] = []
+    rows: list[str] = ["槽位                 名单      本次产物        结论"]
+    rows.append("-" * 78)
+    wanted = set(declared)
+
+    # 顺序：先按矩阵顺序（对外口径稳定），再有名单里多出来的（check_source 已负责报它是错字）。
+    order = list(matrix) + [s for s in declared if s not in matrix]
+    for slot in order:
+        found = assets_for(dist, slot)
+        present = [f"{prefix}({len(found[prefix])})" for prefix, _ in ASSET_PREFIXES if found[prefix]]
+        is_declared = slot in wanted
+        if is_declared:
+            missing = [role for prefix, role in ASSET_PREFIXES if not found[prefix]]
+            for role in missing:
+                suffix = (
+                    "（它是 mode=ci 的槽位：构建红了就必须挡住本次发布，别把缺一档的 Release 发出去）"
+                    if matrix.get(slot) == "ci"
+                    else ""
+                )
+                errors.append(f"发布白名单缺产物：{slot} 的 {role}（`{prefix_for(role)}_*_{stem(slot)}*`）{suffix}")
+            verdict = "发布" if not missing else "缺产物 ⇒ 不发版"
+            wanted.discard(slot)
+        elif present:
+            # **反方向**：真编出来了却没声明。裁剪步会把它 rm 掉，此前这里一句注解都没有。
+            warnings.append(
+                f"{slot} 有产物（{'、'.join(present)}）但不在 PUBLISH_SLOTS 里：本次不发布，产物会被裁掉。"
+                "若这是修复后的首次成功构建，把槽位加进名单即可（齐全性检查与 SHA256SUMS 自动跟着扩）"
+            )
+            verdict = "未发布（名单没声明）"
+        elif matrix.get(slot) == "ci":
+            # 声明为「默认在 CI 里构建」的槽位本次却没产物：那一档的构建红了（或矩阵被改窄了）。它不在名单里
+            # ⇒ **不该**让发布变红（arm64 的策略就是「红了不挡发布」），但也不能静默：否则「又红了」只剩翻 job 列表。
+            warnings.append(
+                f"{slot} 是 mode=ci 的槽位（tag 推送默认就编）却本次没有产物：那一档的构建红了或被裁了，"
+                "本次未发布。它不在 PUBLISH_SLOTS 里，故不影响本次发布"
+            )
+            verdict = "未发布（ci 槽位本次无产物）"
+        else:
+            verdict = "未发布（本次没有产物）"
+        rows.append(f"{slot:<20} {'声明' if is_declared else '未声明':<8} {'、'.join(present) or '无':<15} {verdict}")
+
+    for slot in sorted(wanted):
+        errors.append(f"发布白名单里的 `{slot}` 既不是矩阵槽位、也没有产物（详见上面的源码级断言）")
+    return errors, warnings, rows
+
+
+def prefix_for(role: str) -> str:
+    return next(prefix for prefix, name in ASSET_PREFIXES if name == role)
+
+
+# ────────────────────────── 汇总 ──────────────────────────
+
+
+def run_checks(root: Path, dist: Path | None = None, expected: list[str] | None = None) -> tuple[list[str], list[str], list[str]]:
+    problems = check_source(root, expected)
+    if dist is None or problems:
+        return problems, [], []
+    matrix = matrix_slots((root / MATRIX_YML).read_text(encoding="utf-8"))
+    declared = declared_slots((root / PUBLISH_YML).read_text(encoding="utf-8")) or []
+    errors, warnings, rows = check_dist(dist, declared, matrix)
+    return problems + errors, warnings, rows
+
+
+def report(root: Path, dist: Path | None, expected: list[str] | None = None) -> int:
+    errors, warnings, rows = run_checks(root, dist, expected)
+    # 全部走 **stdout**：Actions 在 stdout 上同样识别 `::error::` / `::warning::`，而分两个流写会让
+    # 「表格 → 注解」的顺序在 CI 日志里不可控（stderr 往往整段先刷出来，注解就跑到它解释的那张表前面）。
+    for row in rows:
+        print(row)
+    for item in warnings:
+        print(f"::warning::{item}")
+    for item in errors:
+        print(f"::error::{item}")
+    if errors:
+        print(f"发布名单守卫：{len(errors)} 条不通过")
+        return 1
+    print(f"OK: 发布名单守卫全绿（{len(warnings)} 条「未发布」提示）")
+    return 0
+
+
+# ────────────────────────── 自测：注入回归，断言每条都红 ──────────────────────────
+
+
+def snapshot(dst: Path) -> None:
+    for rel in (MATRIX_YML, PUBLISH_YML):
+        target = dst / rel
+        target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(ROOT / rel, target)
+
+
+def fake_dist(parent: Path, slots: tuple[str, ...]) -> Path:
+    """合成 dist：每槽位一个 GUI + 一个 CLI 资产（名字形状与 `make_artifacts.py` 一致）。"""
+    dist = parent / "dist"
+    dist.mkdir(parents=True, exist_ok=True)
+    version = "0.0.0"
+    for slot in slots:
+        platform, arch = slot.split("-", 1)
+        suffix = ".exe" if platform == "windows" else ".tar.gz"
+        (dist / f"unlucky-launcher_{version}_{platform}_{arch}{suffix}").write_bytes(b"gui")
+        (dist / f"ull_{version}_{platform}_{arch}{suffix}").write_bytes(b"cli")
+    return dist
+
+
+def set_declared(root: Path, value: str) -> None:
+    path = root / PUBLISH_YML
+    text = path.read_text(encoding="utf-8")
+    replaced, count = PUBLISH_RE.subn(f'PUBLISH_SLOTS: "{value}"', text)
+    if count != 1:
+        raise SystemExit(f"::error::自测自身失效：{PUBLISH_YML} 里找到 {count} 处 PUBLISH_SLOTS")
+    path.write_text(replaced, encoding="utf-8")
+
+
+def self_test() -> int:
+    failures = 0
+    with tempfile.TemporaryDirectory(prefix="ull-publish-slots-") as tmp:
+        base = Path(tmp) / "base"
+        snapshot(base)
+        declared = declared_slots((base / PUBLISH_YML).read_text(encoding="utf-8")) or []
+        if not declared:
+            print("::error::自测的基线读不出 PUBLISH_SLOTS", file=sys.stderr)
+            return 1
+
+        cases: list[tuple[str, Path, Path | None, list[str] | None, bool]] = []
+
+        # 0. 基线：名单齐全、产物齐全 ⇒ 绿。
+        cases.append(("基线（名单与产物都齐）", base, fake_dist(Path(tmp) / "c0", tuple(declared)), None, False))
+
+        # 1. 名单声明了，但缺 CLI 资产 ⇒ 必须红（这条就是「少一档不发版」）。
+        dist = fake_dist(Path(tmp) / "c1", tuple(declared))
+        for stale in dist.glob("ull_*"):
+            stale.unlink()
+        cases.append(("名单声明了但缺 CLI 产物", base, dist, None, True))
+
+        # 2. 名单声明了，但整个槽位没有产物 ⇒ 必须红。
+        cases.append(("名单声明了但整个槽位没产物", base, fake_dist(Path(tmp) / "c2", ()), None, True))
+
+        # 3. 有产物、名单没声明 ⇒ 只警告不红（反方向的静默必须被打破，但发布本身没错）。
+        #    名单内的槽位照旧齐全，只是多出一档没人声明的产物。
+        cases.append(("产物在但名单没声明（arm64 修复后的典型场景）", base, fake_dist(Path(tmp) / "c3", (*declared, "windows-arm64")), None, False))
+
+        # 4. 名单拼错一个字 ⇒ 必须红（此前要翻两层日志才能看出根因）。
+        typo = Path(tmp) / "c4"
+        snapshot(typo)
+        set_declared(typo, "windows-aarch64")
+        cases.append(("名单拼错成 windows-aarch64", typo, fake_dist(Path(tmp) / "c4d", ("windows-aarch64",)), None, True))
+
+        # 5. 名单写了 probe 档（默认不构建）⇒ 必须红。**要挑仍是 probe 的槽位**：`linux-x64` 已翻成 `mode: ci`，
+        #    再拿它当样例，这条用例就从「必须红」变成「本来该绿」——自测跟着矩阵走，否则它自己先变成假证据。
+        probe = Path(tmp) / "c5"
+        snapshot(probe)
+        set_declared(probe, "windows-x64 macos-arm64")
+        cases.append(("名单写了 mode=probe 的槽位", probe, fake_dist(Path(tmp) / "c5d", ("windows-x64", "macos-arm64")), None, True))
+
+        # 6. 运行期名单与文件里那一行不一致 ⇒ 必须红（防步内覆盖）。
+        cases.append(("运行期名单与文件不一致", base, fake_dist(Path(tmp) / "c6", tuple(declared)), ["windows-arm64"], True))
+
+        # 7. 「把 arm64 加回名单」这一行改动本身是干净的：名单+产物都对得上 ⇒ 绿。
+        flip = Path(tmp) / "c7"
+        snapshot(flip)
+        set_declared(flip, " ".join([*declared, "windows-arm64"]))
+        cases.append(("名单加上 windows-arm64 且产物齐全（下一 tag 的翻牌预演）", flip, fake_dist(Path(tmp) / "c7d", (*declared, "windows-arm64")), None, False))
+
+        # 8. （M184 核心）名单里的 `linux-x64` 构建红了（没有它的产物）⇒ **必须挡住发布**：`release` job 是
+        #    `always()`，构建矩阵里红一档不会把发布跳过；挡住它的只能是这条。
+        dist = fake_dist(Path(tmp) / "c8", tuple(s for s in declared if s != "linux-x64") + ("linux-arm64",))
+        cases.append(("名单声明的 linux-x64 构建红了（缺产物）", base, dist, None, True))
+
+        # 9. （M184 真实场景）`linux-arm64` 构建成功但不在名单 ⇒ 只警告、不挡发布（它是 `mode: ci` 的槽位，每轮都编）。
+        cases.append(("linux-arm64 构建成功但不在名单（只警告）", base, fake_dist(Path(tmp) / "c9", (*declared, "linux-arm64")), None, False))
+
+        # 10. 反过来：有人把 `linux-arm64` 提前写进名单、而它没构建出来 ⇒ 必须红（解锁条件还没满足）。
+        early = Path(tmp) / "c10"
+        snapshot(early)
+        set_declared(early, " ".join([*declared, "linux-arm64"]))
+        cases.append(("名单提前声明 linux-arm64 但缺产物", early, fake_dist(Path(tmp) / "c10d", tuple(declared)), None, True))
+
+        for label, root, dist, expected, want_red in cases:
+            errors, warnings, _rows = run_checks(root, dist, expected)
+            got_red = bool(errors)
+            if got_red != want_red:
+                want = "红" if want_red else "绿"
+                detail = "；".join(errors) or "（无 error）"
+                print(f"::error::自测失败：{label} 应该{want}，实际 {'红' if got_red else '绿'} —— {detail}", file=sys.stderr)
+                failures += 1
+            else:
+                print(f"OK: {label} → {'红' if got_red else '绿'}（{len(warnings)} 条未发布提示）")
+
+        # 第 3 / 9 条还要断言**确实打了警告**：不静默才是这两条规则的重点。
+        for ghost in ("windows-arm64", "linux-arm64"):
+            _e, warnings, _r = run_checks(base, fake_dist(Path(tmp) / f"c-warn-{ghost}", (*declared, ghost)), None)
+            if not any(ghost in w for w in warnings):
+                print(f"::error::自测失败：产物在但名单没声明时没有针对 {ghost} 的 ::warning::", file=sys.stderr)
+                failures += 1
+            else:
+                print(f"OK: 产物在但名单没声明 → 有 {ghost} 的 ::warning::")
+
+        # 第 9 条的另一半：`mode: ci` 的槽位**连产物都没有**（构建红了）时也要有注解，不能只在表里少一行。
+        ci_slots = [slot for slot, mode in matrix_slots((base / MATRIX_YML).read_text(encoding="utf-8")).items() if mode == "ci"]
+        missing_ci = [slot for slot in ci_slots if slot not in declared]
+        if not missing_ci:
+            print("::error::自测失败：没有「mode=ci 但不在名单」的槽位，这条用例失去意义（矩阵是不是被改窄了？）", file=sys.stderr)
+            failures += 1
+        else:
+            _e, warnings, _r = run_checks(base, fake_dist(Path(tmp) / "c-ci-red", tuple(declared)), None)
+            for slot in missing_ci:
+                if not any(slot in w and "ci" in w for w in warnings):
+                    print(f"::error::自测失败：{slot} 是 mode=ci 却没产物时没有 ::warning::（红在哪都不知道）", file=sys.stderr)
+                    failures += 1
+                else:
+                    print(f"OK: {slot} 是 mode=ci 却无产物 → 有 ::warning::")
+
+    if failures:
+        return 1
+    print("OK: 发布名单守卫自测全部通过（该红的红、该绿的不红）")
+    return 0
+
+
+def main(argv: list[str]) -> int:
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(errors="backslashreplace")
+
+    root = ROOT
+    dist: Path | None = None
+    expected: list[str] | None = None
+    args = list(argv)
+    while args:
+        arg = args.pop(0)
+        if arg == "--root" and args:
+            root = Path(args.pop(0)).resolve()
+        elif arg == "--dist" and args:
+            dist = Path(args.pop(0)).resolve()
+        elif arg == "--slots" and args:
+            expected = parse_slots_arg(args.pop(0))
+        elif arg == "--self-test":
+            return self_test()
+        elif arg in ("-h", "--help"):
+            print(__doc__)
+            return 0
+        else:
+            print(f"::error::不认识的参数：{arg}", file=sys.stderr)
+            return 2
+
+    if dist is not None and not dist.is_dir():
+        print(f"::error::--dist {dist} 不是目录（下载 artifact 那一步没跑成？）", file=sys.stderr)
+        return 1
+    return report(root, dist, expected)
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))
diff --git a/packaging/check_release_semantics.py b/packaging/check_release_semantics.py
new file mode 100644
index 0000000..dff6b3c
--- /dev/null
+++ b/packaging/check_release_semantics.py
@@ -0,0 +1,391 @@
+#!/usr/bin/env python3
+"""发布标记语义守门（M163）：**push tag 默认创建稳定版**，这条不是靠注释保证的。
+
+四条断言，任何一条不成立即 exit 1（CI 里红在 `.github/workflows/release-guard.yml`）：
+
+1. **标记表**：直接调 `packaging/release_marker.py::marks()`——
+   push tag（空串）的 create 标记里不许出现 `--prerelease`；`prerelease=true` 两个分支都带；
+   `prerelease=false` 的 create 稳定、edit 显式 `--prerelease=false`；非法取值必须抛。
+2. **bash 往返**：把 `release_marker.py --emit-bash` 的输出真的 `source` 进 bash，读回
+   `create_mark` / `edit_mark` 两个数组。第 1 条只证明函数对，这一条证明**流水线跑的那段代码**对
+   （数组拼错、`source` 漏了、`set -u` 炸掉都在这条里现原形）。
+3. **流水线必须用这份表**：`release-publish.yml` 的**可执行内容**里不许有 `--prerelease` 字面量
+   （注释里讲清楚为什么可以），必须调用 `--emit-bash`，且两个数组分别喂给 `gh release create/edit`。
+   否则表改得再对，流水线也可能自己写一套。
+4. **dispatch 默认值 == false**：读 `release.yml` 的 YAML 结构（`on.workflow_dispatch.inputs.prerelease.default`），
+   不是 grep 字符串——键被搬走 / 改名 / 缺省会当场红。
+
+`--self-mutation` 是这条守门的自测：把四个文件复制到临时目录，逐项注入真实回归（默认值改回
+`true`、publish 里塞回 `--prerelease`、标记表的 push 分支改成预发布），断言守门**每一项都红**，
+基线**绿**。变异自测本身失败也 exit 1——「守门抓不住」与「代码坏了」是两件事，不能混。
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+PACKAGING = Path(__file__).resolve().parent
+ROOT = PACKAGING.parent
+
+RELEASE_YML = Path(".github/workflows/release.yml")
+PUBLISH_YML = Path(".github/workflows/release-publish.yml")
+MARKER_REL = Path("packaging/release_marker.py")
+
+#: release.yml 里「dispatch 的 prerelease 默认值」在 YAML 结构中的位置。
+DEFAULT_PATH = ("on", "workflow_dispatch", "inputs", "prerelease", "default")
+
+#: 三种触发方式各自该展开成什么（与 release_marker.py 的表同源，这里独立写一份是为了对拍）。
+EXPECTED = {
+    "": ((), ()),
+    "true": (("--prerelease",), ("--prerelease",)),
+    "false": ((), ("--prerelease=false",)),
+}
+
+
+# ────────────────────────── 1. 标记表（语义断言） ──────────────────────────
+
+
+def load_marker(root: Path):
+    """从 `root` 里加载 release_marker.py（变异自测要能加载被改坏的那份）。"""
+    path = root / MARKER_REL
+    spec = importlib.util.spec_from_file_location(f"_release_marker_{hash(path)}", path)
+    if spec is None or spec.loader is None:
+        raise SystemExit(f"::error::加载不了 {path}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def check_table(root: Path) -> list[str]:
+    module = load_marker(root)
+    problems: list[str] = []
+
+    for raw, (create, edit) in EXPECTED.items():
+        got_create, got_edit = module.marks(raw)
+        trigger = "push tag（空串）" if raw == "" else f'dispatch prerelease="{raw}"'
+        if tuple(got_create) != create or tuple(got_edit) != edit:
+            problems.append(
+                f"{trigger}：期望 create={create} edit={edit}，实际 create={tuple(got_create)} edit={tuple(got_edit)}"
+            )
+
+    # 单独立一条：这条是 v0.2.2 至今 releases/latest 404 的根因，报告里点名它。
+    push_create, _ = module.marks("")
+    if "--prerelease" in push_create:
+        problems.append("push tag 的 create 标记带上了 --prerelease：稳定通道会一直是 404")
+
+    for bad in ("yes", "1", "TRUE", "False", "0"):
+        try:
+            module.marks(bad)
+        except ValueError:
+            continue
+        problems.append(f"非法取值 {bad!r} 没有被拒绝（会静默变成某个发布标记）")
+
+    if not module.CASES:
+        problems.append("release_marker.CASES 是空的：对外承诺的那张表不见了")
+    return problems
+
+
+# ────────────────────────── 2. bash 往返（真跑那段代码） ──────────────────────────
+
+BASH_ROUNDTRIP = r"""
+set -uo pipefail
+marks=$(mktemp)
+"$PYTHON" "$MARKER" --emit-bash --prerelease "$RAW" > "$marks" || { echo "emit failed"; exit 1; }
+# shellcheck disable=SC1090
+source "$marks"
+printf 'create=%s\n' "${create_mark[*]:-}"
+printf 'edit=%s\n' "${edit_mark[*]:-}"
+rm -f "$marks"
+"""
+
+
+def find_bash() -> str | None:
+    """找到「真的 bash」，而不是 Windows 上 System32 里那个 WSL 壳（它不认这套环境）。"""
+    candidates = [
+        os.environ.get("BASH"),
+        shutil.which("bash"),
+        "C:/Program Files/Git/bin/bash.exe",
+        "C:/Program Files/Git/usr/bin/bash.exe",
+    ]
+    for candidate in candidates:
+        if not candidate:
+            continue
+        if "system32" in candidate.replace("/", "\\").lower():
+            continue
+        if Path(candidate).is_file() or shutil.which(candidate):
+            return candidate
+    return None
+
+
+BASH = find_bash()
+
+
+def bash_marks(marker: Path, raw: str) -> tuple[str, str] | None:
+    if BASH is None:
+        return None
+    # 解释器用 sys.executable 而不是写死 python3：CI（ubuntu）上两者等价，本机 Windows 只有
+    # `python`，写死 python3 会让这条断言在本地跑不起来——一条本地跑不了的守门等于没有。
+    env = dict(
+        os.environ,
+        MARKER=str(marker),
+        RAW=raw,
+        PYTHON=sys.executable.replace("\\", "/"),
+        PYTHONIOENCODING="utf-8",
+    )
+    proc = subprocess.run(
+        [BASH, "-c", BASH_ROUNDTRIP], env=env, capture_output=True, text=True, encoding="utf-8"
+    )
+    if proc.returncode != 0:
+        return None
+    values = {}
+    for line in proc.stdout.splitlines():
+        key, _, value = line.partition("=")
+        values[key.strip()] = value.strip()
+    if "create" not in values or "edit" not in values:
+        return None
+    return values["create"], values["edit"]
+
+
+def check_bash_roundtrip(root: Path) -> list[str]:
+    marker = root / MARKER_REL
+    problems: list[str] = []
+    if BASH is None:
+        return ["找不到 bash：这条断言要真跑流水线里那段 source，不能跳过（CI 是 ubuntu-latest，一定有）"]
+
+    for raw, (create, edit) in EXPECTED.items():
+        got = bash_marks(marker, raw)
+        want = (" ".join(create), " ".join(edit))
+        trigger = "push tag（空串）" if raw == "" else f'dispatch prerelease="{raw}"'
+        if got is None:
+            problems.append(f"{trigger}：--emit-bash 的产物 source 进 bash 失败")
+        elif got != want:
+            problems.append(f"{trigger}：bash 展开成 create={got[0]!r} edit={got[1]!r}，期望 create={want[0]!r} edit={want[1]!r}")
+    return problems
+
+
+# ────────────────────────── 3. 流水线必须用这份表 ──────────────────────────
+
+
+def executable_text(text: str) -> str:
+    """去掉整行注释后的内容：注释里写 `--prerelease` 是解释，可执行位置上出现才是回归。"""
+    return "\n".join(line for line in text.splitlines() if not line.lstrip().startswith("#"))
+
+
+def check_pipeline(root: Path) -> list[str]:
+    path = root / PUBLISH_YML
+    if not path.is_file():
+        return [f"找不到 {PUBLISH_YML}（发布流水线搬家了？这条守门要跟着搬）"]
+    text = path.read_text(encoding="utf-8")
+    live = executable_text(text)
+    problems: list[str] = []
+
+    hits = [
+        line.strip()
+        for line in live.splitlines()
+        # 唯一允许出现它的位置：把值喂给表自己的那一行（`release_marker.py ... --prerelease "$PRERELEASE"`）。
+        # 其它任何可执行位置（`gh release` 的旗子、自己写的 case 分支）都是回归。
+        if "--prerelease" in line and "release_marker.py" not in line
+    ]
+    if hits:
+        problems.append(
+            "release-publish.yml 的可执行内容里出现了 --prerelease 字面量（标记必须只由 "
+            "packaging/release_marker.py 产出）：" + " | ".join(hits)
+        )
+    if "release_marker.py --emit-bash" not in live:
+        problems.append("release-publish.yml 没有调用 packaging/release_marker.py --emit-bash")
+    for array in ('"${create_mark[@]}"', '"${edit_mark[@]}"'):
+        if array not in live:
+            problems.append(f"release-publish.yml 没有把 {array} 喂给 gh release（create / edit 各要一个）")
+    if "github.event.inputs.prerelease" not in live:
+        problems.append("release-publish.yml 不再从 github.event.inputs.prerelease 取值（三态语义的来源没了）")
+    return problems
+
+
+# ────────────────────────── 4. dispatch 默认值 == false ──────────────────────────
+
+
+def yaml_scalars(text: str) -> dict[tuple[str, ...], tuple[str, int]]:
+    """极简 YAML 结构读取：只认「缩进 → key: value」的标量行，返回 {路径: (值, 行号)}。
+
+    不引第三方依赖（CI 上只有裸 python3）：本守门要读的是「某个键在哪个缩进层级上」，不是
+    完整 YAML 语义。块标量（`run: |`）的内容整段跳过，免得脚本里的 `a: b` 混进来。
+    """
+    out: dict[tuple[str, ...], tuple[str, int]] = {}
+    stack: list[tuple[int, str]] = []
+    block_indent: int | None = None
+    for lineno, raw in enumerate(text.splitlines(), 1):
+        if not raw.strip() or raw.lstrip().startswith("#"):
+            continue
+        indent = len(raw) - len(raw.lstrip(" "))
+        if block_indent is not None:
+            if indent > block_indent:
+                continue
+            block_indent = None
+        stripped = raw.strip()
+        if stripped == "-" or stripped.startswith("- "):
+            continue
+        if ":" not in stripped:
+            continue
+        key, _, value = stripped.partition(":")
+        key = key.strip().strip("'\"")
+        value = re.sub(r"\s+#.*$", "", value.strip())
+        while stack and stack[-1][0] >= indent:
+            stack.pop()
+        path = tuple(k for _, k in stack) + (key,)
+        if value in ("", "|", ">", "|-", ">-"):
+            stack.append((indent, key))
+            if value:
+                block_indent = indent
+        else:
+            out[path] = (value, lineno)
+    return out
+
+
+def check_default(root: Path) -> list[str]:
+    path = root / RELEASE_YML
+    if not path.is_file():
+        return [f"找不到 {RELEASE_YML}"]
+    scalars = yaml_scalars(path.read_text(encoding="utf-8"))
+    if DEFAULT_PATH not in scalars:
+        return [
+            "release.yml 里读不到 "
+            + ".".join(DEFAULT_PATH)
+            + "：dispatch 的 prerelease 输入被搬走/改名/删了（默认值判据必须留在原处）"
+        ]
+    value, lineno = scalars[DEFAULT_PATH]
+    if value.strip().strip("'\"").lower() != "false":
+        return [
+            f"release.yml:{lineno} dispatch 的 prerelease 默认值是 {value!r}，必须是 false"
+            "（默认值一旦回 true，Actions 页面点一次的产物就是预发布）"
+        ]
+    return []
+
+
+# ────────────────────────── 汇总 ──────────────────────────
+
+
+def run_checks(root: Path) -> list[str]:
+    problems: list[str] = []
+    for name, fn in (
+        ("标记表（push tag ⇒ 稳定版）", check_table),
+        ("bash 往返（流水线真跑的那段）", check_bash_roundtrip),
+        ("流水线只从表里取标记", check_pipeline),
+        ("dispatch 默认值 == false", check_default),
+    ):
+        found = fn(root)
+        problems.extend(f"{name}：{item}" for item in found)
+    return problems
+
+
+def report(root: Path) -> int:
+    problems = run_checks(root)
+    for item in problems:
+        print(f"::error::{item}", file=sys.stderr)
+    if problems:
+        print(f"发布标记语义守门：{len(problems)} 条不通过", file=sys.stderr)
+        return 1
+    marker = load_marker(root)
+    print("OK: 发布标记语义守门全绿")
+    print(marker.table())
+    return 0
+
+
+# ────────────────────────── 变异自测 ──────────────────────────
+
+
+def snapshot(dst: Path) -> None:
+    """把守门依赖的四个文件复制进 `dst`（只复制这四个，保持临时树最小）。"""
+    for rel in (RELEASE_YML, PUBLISH_YML, MARKER_REL, Path("packaging") / Path(__file__).name):
+        target = dst / rel
+        target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(ROOT / rel, target)
+
+
+def mutate_default_true(root: Path) -> str:
+    path = root / RELEASE_YML
+    text = path.read_text(encoding="utf-8")
+    scalars = yaml_scalars(text)
+    _, lineno = scalars[DEFAULT_PATH]
+    lines = text.splitlines()
+    lines[lineno - 1] = lines[lineno - 1].replace("false", "true")
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    return "release.yml 的 dispatch 默认值改回 true"
+
+
+def mutate_inline_flag(root: Path) -> str:
+    path = root / PUBLISH_YML
+    text = path.read_text(encoding="utf-8")
+    path.write_text(text + "          create_mark+=(--prerelease)\n", encoding="utf-8")
+    return "release-publish.yml 里塞回 --prerelease 字面量"
+
+
+def mutate_marker_push(root: Path) -> str:
+    path = root / MARKER_REL
+    text = path.read_text(encoding="utf-8")
+    old = '    if value == "":\n        return (), ()\n'
+    new = '    if value == "":\n        return (PRERELEASE,), ()\n'
+    if old not in text:
+        raise SystemExit(f"::error::变异自测自身失效：{MARKER_REL} 里找不到 push 分支的原样代码")
+    path.write_text(text.replace(old, new, 1), encoding="utf-8")
+    return "标记表的 push tag 分支改成预发布"
+
+
+MUTATIONS = (mutate_default_true, mutate_inline_flag, mutate_marker_push)
+
+
+def self_mutation() -> int:
+    with tempfile.TemporaryDirectory(prefix="ull-release-guard-") as tmp:
+        baseline = Path(tmp) / "baseline"
+        snapshot(baseline)
+        problems = run_checks(baseline)
+        if problems:
+            for item in problems:
+                print(f"::error::变异自测的基线本该是绿的：{item}", file=sys.stderr)
+            return 1
+        print("OK: 基线绿")
+
+        failures = 0
+        for index, mutate in enumerate(MUTATIONS):
+            root = Path(tmp) / f"mutation-{index}"
+            snapshot(root)
+            label = mutate(root)
+            if not run_checks(root):
+                print(f"::error::变异自测失败：注入「{label}」后守门仍然绿（这条守门抓不住它）", file=sys.stderr)
+                failures += 1
+            else:
+                print(f"OK: 注入「{label}」→ 守门红")
+        if failures:
+            return 1
+        print(f"OK: {len(MUTATIONS)} 项变异全部被抓红，基线绿")
+        return 0
+
+
+def main(argv: list[str]) -> int:
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(errors="backslashreplace")
+
+    root = ROOT
+    args = list(argv)
+    if "--root" in args:
+        index = args.index("--root")
+        root = Path(args[index + 1]).resolve()
+        del args[index : index + 2]
+    if "--self-mutation" in args:
+        return self_mutation()
+    unknown = [arg for arg in args if arg not in ("-h", "--help")]
+    if unknown:
+        print(f"::error::不认识的参数：{unknown}", file=sys.stderr)
+        return 2
+    return report(root)
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))
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/check_signing_ready.py b/packaging/check_signing_ready.py
new file mode 100644
index 0000000..1f74598
--- /dev/null
+++ b/packaging/check_signing_ready.py
@@ -0,0 +1,244 @@
+#!/usr/bin/env python3
+"""签名就绪度播报（M255）：**只读**、零第三方依赖，三行说清「今天能不能签发一份客户端会认的清单」。
+
+为什么要它：M254（CLAIMAUDIT）查出 `crates/core/src/update/trust.rs` 的 `PRODUCTION` 表在
+`PINNED-KEYS` 标记之间是**空的**，而空表一律 `KeyringEmpty` 拒装 —— 于是**今天任何正式二进制都验不过
+任何清单**（fail-closed 是成立的，但在用户机器上表现为「更新永远失败」）。工具链早就齐了
+（`sign_manifest.py` 的 `--generate-key` / `--check-pinned-keyring` / `--sign` / `--verify-pinned`），
+缺的是**操作步骤与可见性**。本脚本只负责「现在差什么」，它不生成钥、不写任何文件、不改 `trust.rs`。
+
+三行就绪度（各一条判据，互不替代）：
+
+| 行 | 判据 | 未就绪意味着 |
+|---|---|---|
+| ① | `PRODUCTION` 表非空：解析 `PINNED-KEYS` 标记之间的 `PinnedKey` 条目，0 条即未就绪 | 客户端一把公钥都没有，任何清单都验不过（今天就是这个状态） |
+| ② | 环境里有签名钥：`ULL_MANIFEST_SIGNING_KEY`（或 `--key <文件>`）能解出 32 字节种子，**且**它的公钥在 ① 的表里 | 没钥签不了；钥与信任表不是同一把 ⇒ 发布时 `--check-pinned-keyring` 当场红 |
+| ③ | 最近一次发布的 `manifest.json` / `.sig` 痕迹 | **不参与就绪判定**。取不到证据就写「未知」——「本地没留档」不等于「上次没签」 |
+
+②里的对账（`公钥 ∈ 表`）是刻意加的：只说「有钥」会给出一个**看着就绪、发布却红**的假象，与本仓
+「别再造假绿的尺子」的血泪账直接冲突。公钥是公开物，回显它是安全的；**种子（`seed_hex`）在本脚本里
+一次都不打印**。
+
+②还有第三种读数：**未判定**。CI 的播报 workflow 刻意只在 `main` ref 上注入 Secret（生产签名种子等于
+「给全量已装客户端签可信清单」的能力，既有设计把它锁在 tag ref 后面），非 main ref 的运行里这一行会写
+「未判定 —— 非 main ref（按设计不注入）」，**不写「没配」**：把「策略不注入」说成「没配」就是一次假读数。
+
+退出码是对外接口（改动即行为变化，`packaging/tests/signing_ready_selftest.py` 钉着它）：
+`0` 就绪 / `1` 未就绪（含 ② 未判定） / `2` 用法错（trust.rs 或 `--key` 读不到、标记丢了 ——
+那时脚本形不成判断，不是「未就绪」）。
+
+**它不是门禁**：CI 里的 `.github/workflows/signing-status.yml` 只把这三行搬进 job summary，
+不因「未就绪」变红。理由见 `packaging/docs/signing-runbook.md` §6。
+
+    python3 packaging/check_signing_ready.py
+    python3 packaging/check_signing_ready.py --trust <副本 trust.rs> --key <钥文件> --dist dist
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+SIGN = ROOT / "packaging/sign_manifest.py"
+RUNBOOK = "packaging/docs/signing-runbook.md"
+#: 未就绪时的固定措辞：判据与「人类一眼看懂后果」绑在一起（用例按字面断言这一句）。
+FAIL_CLOSED = "这会让已安装用户永远验不过（fail-closed）"
+#: 「这一趟按设计没有钥」的原因（人话）。CI 的 `signing-status.yml` 在非 main ref 上把它设成一句话，
+#: 于是 ② 读成「未判定」而不是「没配」—— 把**策略不注入**说成**没配置**是一次假读数（M255 r1 P2-1）。
+WITHHELD_ENV = "ULL_SIGNING_KEY_WITHHELD"
+
+
+sys.path.insert(0, str(ROOT / "packaging"))
+
+# 标记 / 环境变量名 / 信任表路径一律**从 sign_manifest.py 取**，不在这里写第二份字面量：
+# 两份标记各自漂开时，`--check-pinned-keyring` 与就绪度会给出互相矛盾的读数。
+from sign_manifest import KEY_ENV, KID_RE, PIN_BEGIN, PIN_END, TRUST_RS, load_key  # noqa: E402
+from ed25519_ref import public_key  # noqa: E402
+
+Line = tuple[bool, str]  # (就绪?, 该行文本)
+
+
+def table_state(path: Path) -> tuple[bool, str, list[tuple[str, str]]]:
+    """① 判据：`PINNED-KEYS` 标记之间有至少一条 `PinnedKey`。
+
+    标记缺失 / 文件读不到 ⇒ `RuntimeError`（调用方翻成退出码 2：脚本无法形成判断）。
+    """
+    text = path.read_text(encoding="utf-8")
+    begin, end = text.find(PIN_BEGIN), text.find(PIN_END)
+    if begin < 0 or end < begin:
+        raise RuntimeError(
+            f"{path} 里找不到 {PIN_BEGIN} / {PIN_END} 标记（标记本身不许动 —— sign_manifest.py 也按它解析）"
+        )
+    inside = text[begin:end]
+    keys = KID_RE.findall(inside)
+    line_no = text[:begin].count("\n") + 1
+    if keys:
+        names = "、".join(f"{kid}（{pk[:16]}…）" for kid, pk in keys)
+        return True, f"就绪 —— 标记之间 {len(keys)} 条：{names}（{path}:{line_no} 起）", keys
+    # 空表就是今天的状态。顺手查一个真实易错点：有人把条目贴到标记**外面**（`];` 之后）。
+    # ⚠ 本仓另有一把 `TEST_ONLY` 测试钥**本来就在标记之外**（那是它的正确位置），所以这里只**点名**，
+    # 不替人下结论 —— 上一版写成「贴错位置，等于没钉」，在真实 trust.rs 上是误报（实测抓出来的）。
+    strays = [kid for kid, _ in KID_RE.findall(text[:begin]) + KID_RE.findall(text[end:])]
+    hint = ""
+    if strays:
+        hint = (
+            f"；文件里另有 {len(strays)} 条在标记之外（key_id：{'、'.join(strays[:3])}）"
+            "—— `TEST_ONLY` 那条本来就在外面，属正常；**生产钥**贴在外面等于没钉"
+        )
+    return False, f"未就绪 —— 标记之间 0 条 PinnedKey{hint}（{path}:{line_no} 起）", []
+
+
+def read_key_text(key_file: str | None) -> str:
+    """② 的输入文本：`--key <文件>` 或环境变量 `ULL_MANIFEST_SIGNING_KEY`。
+
+    读不了（不存在 / 是目录 / 无权限 / 非 UTF-8）⇒ `OSError` / `UnicodeDecodeError`，由 `main` 翻成
+    **退出码 2**（用法错）。⚠ 这里必须抛而不是吞：吞掉就会变成 rc=1，与「未就绪」同码，
+    而事实是「你给的路径就是错的」——两者混了，退出码就不再可信（M255 r1 P2-2）。
+    """
+    if key_file:
+        return Path(key_file).read_text(encoding="utf-8")
+    return os.environ.get(KEY_ENV, "")
+
+
+def key_state(raw: str, source: str, pinned: list[tuple[str, str]]) -> tuple[bool, str, str | None]:
+    """② 判据：环境里有钥、解析得出、且它的公钥在 ① 的表里。
+
+    返回 `(就绪?, 该行文本, 可直接贴进 trust.rs 的那一行 PinnedKey)`。
+    **任何分支都不打印种子**；回显的只有 `key_id` 与公钥十六进制。
+    """
+    if not raw.strip():
+        reason = os.environ.get(WITHHELD_ENV, "").strip()
+        if reason:
+            # 「策略上不注入」≠「没配置」。这一行必须能分辨，否则非 main ref 的运行会报假的「没配」。
+            return False, f"未判定（未注入）—— 这一趟的钥按设计没有注入：{reason}；这不是「没配」", None
+        return False, f"未就绪 —— {source} 未设置/为空（没有私钥就签不出任何清单）", None
+    try:
+        key_id, seed = load_key(raw)
+    except SystemExit as error:  # load_key 用 SystemExit 报错（它会 sys.exit）；这里降级成一行读数
+        return False, f"未就绪 —— {source} 读不出钥：{error}", None
+    pk_hex = public_key(seed).hex()
+    paste = f'PinnedKey {{ key_id: "{key_id}", public_key_hex: "{pk_hex}" }},'
+    for pinned_id, pinned_hex in pinned:
+        if pinned_hex.lower() == pk_hex:
+            note = "" if pinned_id == key_id else f"（表里叫 {pinned_id}，钥文件叫 {key_id}；判据是公钥字节，能过）"
+            return True, f"就绪 —— {source} 里有钥 {key_id}，公钥 {pk_hex} 已在信任表里{note}", paste
+    if pinned:
+        return False, f"未就绪 —— {source} 里有钥 {key_id}（公钥 {pk_hex}），但**不在**信任表里，发布时会被拦", paste
+    return False, f"未就绪 —— {source} 里有钥 {key_id}（公钥 {pk_hex}），但信任表是空的，没处钉", paste
+
+
+def release_state(dist: Path | None, assets: Path | None) -> tuple[bool | None, str]:
+    """③ 判据：最近一次发布有没有 `manifest.json` / `.sig` 痕迹。**只取证，不参与就绪判定。**
+
+    `None` = 未知（既没给 `--dist` 里的留档，也没给 `--release-assets`）。「本地没留档」不是
+    「上次没签」的证据，所以这一档只写「未知」，不写「无」。
+    """
+    if dist is not None and dist.is_dir():
+        manifest = dist / "manifest.json"
+        signature = dist / f"{manifest.name}.sig"
+        if manifest.is_file() and signature.is_file():
+            return True, f"有 —— 本地留档 {manifest} + {signature}"
+        if manifest.is_file():
+            return False, f"无 —— 本地 {dist} 里有 manifest.json 但**没有** .sig（那份清单客户端会拒收）"
+    if assets is not None and assets.is_file():
+        text = assets.read_text(encoding="utf-8", errors="replace")
+        # 先剥掉 `.sig` 再判清单：`manifest.json.sig` 里含 `manifest.json`，只做子串匹配时
+        # 「资产里只有签名」会被读成「清单和签名都在」（r1 复审实测抓到的假读数）。
+        has_sig = "manifest.json.sig" in text
+        has_manifest = "manifest.json" in text.replace("manifest.json.sig", "")
+        if has_manifest and has_sig:
+            return True, f"有 —— {assets} 的资产清单里同时有 manifest.json 与 manifest.json.sig"
+        if has_manifest:
+            return False, f"无 —— {assets} 的资产清单里有 manifest.json，但没有 manifest.json.sig（没签名）"
+        return False, f"无 —— {assets} 的资产清单里既没有 manifest.json 也没有 .sig（那次发布没走上签名这条链）"
+    looked = [str(p) for p in (dist, assets) if p is not None]
+    where = f"（看过：{'、'.join(looked)}）" if looked else "（没给 --dist / --release-assets，也没本地 dist/ 留档）"
+    return None, f"未知 —— 取不到任何发布产物证据{where}"
+
+
+def fix_hint(table_ok: bool, key_ok: bool, paste: str | None) -> str:
+    """未就绪时的**一行**修复命令（不带任何密钥值；钥的事只指向 Secret 名与手册）。
+
+    指针必须落在手册**真实**的章节上：`packaging/tests/signing_ready_wiring_selftest.py` 会拿这里的
+    `§N` 去对 `signing-runbook.md` 的标题集合，漂了当场红（M255 r1 P2-3：`signing-ready.yml` 那个
+    文件名根本不存在，而指针正是本文件的交付物）。
+    """
+    if not table_ok and paste:
+        return f"修复：把这一行贴进 {TRUST_RS.name} 的 PINNED-KEYS 标记之间 —— {paste}（手册 {RUNBOOK} §2 步③）"
+    if not table_ok:
+        return (
+            "修复：python3 packaging/sign_manifest.py --generate-key --key-id   "
+            f"→ 私钥贴进 Secret {KEY_ENV}，打印的 PinnedKey 那行贴进 trust.rs 标记之间（手册 {RUNBOOK} §2 步①–③）"
+        )
+    if not key_ok and paste:
+        return f"修复：把这一行贴进 {TRUST_RS.name} 的 PINNED-KEYS 标记之间 —— {paste}（手册 {RUNBOOK} §2 步③）"
+    return f"修复：把密钥贴进仓库 Secret {KEY_ENV}（内容 = --generate-key 打印的那行 JSON；手册 {RUNBOOK} §2 步②）"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="签名就绪度播报：三行读数 + 0/1/2 退出码（M255）")
+    parser.add_argument("--trust", type=Path, default=TRUST_RS, help=f"trust.rs 路径（默认 {TRUST_RS}）")
+    parser.add_argument("--key", metavar="FILE", help=f"钥文件（不给则读环境变量 {KEY_ENV}）")
+    parser.add_argument("--dist", type=Path, default=Path("dist"), help="本地留档目录（默认 dist/；不存在则不看）")
+    parser.add_argument("--release-assets", type=Path, metavar="FILE", help="某次 Release 的资产清单文本（如 gh release view 的输出）")
+    parser.add_argument("--line", action="store_true", help="CI 用：额外把三行写进 $GITHUB_STEP_SUMMARY")
+    args = parser.parse_args(argv)
+
+    try:
+        table_ok, table_line, pinned = table_state(args.trust)
+    except (OSError, UnicodeDecodeError, RuntimeError) as error:
+        print(f"error: 读不了信任表：{error}（脚本无法形成判断，按用法错退出）", file=sys.stderr)
+        return 2
+    try:
+        key_text = read_key_text(args.key)
+    except (OSError, UnicodeDecodeError) as error:
+        # 与 `--trust` 同款：输入读不到 = 用法错（2）。**不能**退化成 1 —— 1 是「签名未就绪」的读数，
+        # 混了就会把「我路径写错了」读成「签名没配好」（M255 r1 P2-2）。
+        print(f"error: 读不了钥文件 {args.key}：{error}（这是用法错，不是「未就绪」）", file=sys.stderr)
+        return 2
+    source = f"--key {args.key}" if args.key else f"环境变量 {KEY_ENV}"
+    key_ok, key_line, paste = key_state(key_text, source, pinned)
+    release_ok, release_line = release_state(args.dist, args.release_assets)
+    withheld = not key_ok and not key_text.strip() and bool(os.environ.get(WITHHELD_ENV, "").strip())
+
+    lines: list[Line] = [
+        ("① 信任表 PRODUCTION", table_ok, table_line),
+        ("② 环境签名钥", key_ok, key_line),
+        ("③ 最近一次发布痕迹", release_ok is not False, release_line),
+    ]
+    for label, _ok, text in lines:
+        print(f"{label}：{text}")
+
+    ready = table_ok and key_ok
+    if ready:
+        print(f"结论：就绪（{args.trust} 里钉了钥，环境里的钥与它同源）—— 可以按 {RUNBOOK} §2 步⑤ 发一次带 .sig 的 Release，再按 §5 回验")
+    elif withheld:
+        # 「未判定」不许伪装成「未就绪」：这一趟根本没拿到钥，不是仓库缺钥。
+        tail = f"；① 仍是空的 ⇒ {FAIL_CLOSED}" if not table_ok else ""
+        print(f"结论：未判定（② 这一趟没注入钥，见上面那行的原因）{tail}")
+    else:
+        blockers = [label for label, ok, _ in lines[:2] if not ok]
+        print(f"结论：未就绪（差 {'、'.join(blockers)}）—— {FAIL_CLOSED}")
+        print(fix_hint(table_ok, key_ok, paste))
+
+    if args.line:
+        summary = os.environ.get("GITHUB_STEP_SUMMARY")
+        if summary:
+            verdict = "就绪" if ready else ("未判定" if withheld else "未就绪")
+            body = ["## 签名就绪度（M255，播报不是门禁）", ""]
+            body += [f"- **{label}**：{text}" for label, _ok, text in lines]
+            body += [
+                "",
+                f"- 结论：**{verdict}**",
+                f"- 本 job 的绿色**不代表签名就绪**：判据只看上面三行字，退出码恒为 0（见 `{RUNBOOK}` §6）。",
+            ]
+            Path(summary).write_text("\n".join(body) + "\n", encoding="utf-8")
+
+    return 0 if ready else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/packaging/check_test_key_off.py b/packaging/check_test_key_off.py
new file mode 100644
index 0000000..3289c8e
--- /dev/null
+++ b/packaging/check_test_key_off.py
@@ -0,0 +1,252 @@
+#!/usr/bin/env python3
+"""守 `update-test-key`：这把**公开**的测试公钥不许进发布构建（M190 r3）。
+
+背景：`crates/core` 的信任表（`trust::PRODUCTION`）正式构建里是空的（fail-closed，等用户录钥），
+测试公钥 `trust::TEST_ONLY` 只在三档「仅测试」构建里并入：`cfg(test)`、测试通道那条 feature、
+`update-test-key`。第三档是给 `crates/presenter` 的 `[dev-dependencies]` 用的——presenter 的更新链路
+用例要构造「本构建认得」的签名清单，而它编译 core 时既没有 `cfg(test)`，也不该打开
+「测试通道」那条 feature（它会**同时**给出「本地目录当更新源」这条路，是另一个更大的口子；
+那条由 `check_test_source_off.py` 守。⚠ 本文件**刻意不写那条 feature 的全名**：那个守门按字面
+扫 `packaging/**`，写了这里就红——这是它的设计（宁可误杀也不放过），不是笔误）。
+
+这一档比「测试通道」那条 feature 窄，但它仍然是**信任锚的开关**：一旦进发布构建，任何人都能用公开种子
+签出「官方更新」。所以它的出现位置必须是**白名单**，而不是「没人会这么写」：
+
+| 允许出现的地方 | 形态 |
+|---|---|
+| `crates/core/Cargo.toml` | 只能是它自己的声明，且必须是**空数组** `update-test-key = []`（写成带子 feature 的非空数组即红） |
+| `crates/presenter/Cargo.toml` | 只能出现在 `[dev-dependencies]` 段内 |
+| 本脚本 | 它必须写出这个 feature 名 |
+
+其余任何地方（workflow、`packaging/` 的脚本、根 `Cargo.toml`、`.cargo/config*.toml`、presenter 的
+`[dependencies]`）提到它即红。`--self-test` 把这四类真实回归各注入一次（workflow / presenter 的
+`[dependencies]` / 根 `Cargo.toml` / core 声明里偷偷带子 feature），并断言合法写法不误杀。
+
+    python3 packaging/check_test_key_off.py
+    python3 packaging/check_test_key_off.py --self-test
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+import tempfile
+from pathlib import Path
+
+FEATURE = "update-test-key"
+ROOT = Path(__file__).resolve().parent.parent
+GUARD = Path(__file__).resolve()
+
+#: 扫描面（逐项列举，不用 `**` 全仓：那会把 `target/` 拖进来）。
+GLOBS = (
+    ".github/workflows/**/*.yml",
+    ".github/workflows/**/*.yaml",
+    ".github/actions/**/*.yml",
+    ".github/actions/**/*.yaml",
+    "packaging/**/*.py",
+    "packaging/**/*.sh",
+    "packaging/**/*.ps1",
+    "Cargo.toml",
+    "crates/*/Cargo.toml",
+    "Makefile",
+    "justfile",
+    "Justfile",
+    "Taskfile.yml",
+    "Taskfile.yaml",
+    "crates/*/Makefile",
+    "packaging/Makefile",
+    ".cargo/config.toml",
+    ".cargo/config",
+    "crates/*/.cargo/config.toml",
+    "crates/*/.cargo/config",
+)
+
+#: 白名单：(相对路径, 允许的形态)。形态见 `check_manifest` 的三种判法。
+ALLOWED_DECLARATION = "crates/core/Cargo.toml"
+ALLOWED_DEV_DEPENDENCY = "crates/presenter/Cargo.toml"
+
+#: 另一条（更宽的）测试通道 feature 的名字。**刻意拼出来**：`check_test_source_off.py` 按字面扫
+#: `packaging/**`，这里写全名会让那个守门红 —— 那是它的设计（宁可误杀也不放过），不是笔误。
+#: 本文件与它同源同一套手法，别“顺手”把它写成字面量。
+OTHER_FEATURE = "-".join(("update", "test", "source"))
+
+#: core 只许**自己的声明**，而且必须是**空数组** `update-test-key = []`。
+#: 这里认**内容**、不只认形状：写成带子 feature 的非空数组（`["<另一条 feature>"]`）会让这个「窄口子」
+#: 顺手把「宽口子」（环境变量 + `DirSource` 那条测试通道）拉起来 —— 那正是本守门要防的逃逸。
+DECLARATION = re.compile(rf"^\s*{re.escape(FEATURE)}\s*=\s*\[\s*\]\s*$")
+SECTION = re.compile(r"^\s*\[([^\]]+)\]\s*$")
+
+
+def strip_comment(line: str) -> str:
+    """引号感知地剥注释（与 `check_test_source_off.py` 同一手法，省得两处对同一行有不同看法）。"""
+    quote = None
+    for index, char in enumerate(line):
+        if quote is not None:
+            if char == quote:
+                quote = None
+        elif char in "\"'":
+            quote = char
+        elif char == "#" and (index == 0 or line[index - 1].isspace()):
+            return line[:index]
+    return line
+
+
+def check_manifest(path: Path, where: str) -> list[str]:
+    """`Cargo.toml`：核心只许自己的声明；presenter 只许 `[dev-dependencies]` 段内。"""
+    problems: list[str] = []
+    section = ""
+    for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
+        code = strip_comment(line).strip()
+        if not code:
+            continue
+        header = SECTION.match(code)
+        if header:
+            section = header.group(1).strip()
+            continue
+        if FEATURE not in code:
+            continue
+        if where == ALLOWED_DECLARATION and DECLARATION.match(code):
+            continue
+        if where == ALLOWED_DEV_DEPENDENCY and section == "dev-dependencies":
+            continue
+        problems.append(
+            f"::error file={where}:{number}::{where} 在 `[{section or '顶部'}]` 里写了 `{FEATURE}`；"
+            "它只许出现在 crates/core/Cargo.toml 自己的声明与 crates/presenter/Cargo.toml 的 "
+            "`[dev-dependencies]` 里（这把公钥进发布构建 = 谁都能签出「官方更新」）"
+        )
+    return problems
+
+
+def check_plain(path: Path, where: str) -> list[str]:
+    """其余文件类型：出现即红（不解释形态）。"""
+    problems: list[str] = []
+    for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
+        if FEATURE in strip_comment(line):
+            problems.append(
+                f"::error file={where}:{number}::{where} 提到 `{FEATURE}`：它不进 workflow / 打包脚本 / "
+                "cargo 配置（测试钥只许由 crates/presenter 的 dev-dependencies 打开）"
+            )
+    return problems
+
+
+def scan(root: Path) -> list[str]:
+    """扫整个仓库，返回所有问题（空 = 绿）。"""
+    problems: list[str] = []
+    for pattern in GLOBS:
+        for path in sorted(root.glob(pattern)):
+            if not path.is_file() or path.resolve() == GUARD:
+                continue
+            where = path.relative_to(root).as_posix()
+            try:
+                if path.name == "Cargo.toml":
+                    problems += check_manifest(path, where)
+                else:
+                    problems += check_plain(path, where)
+            except (OSError, UnicodeDecodeError) as error:
+                problems.append(f"::error file={where}::读不到：{error}")
+    return problems
+
+
+# ────────────────────────── 变异自测 ──────────────────────────
+
+BASELINE = {
+    "crates/core/Cargo.toml": (
+        "[features]\nother-feature = []\n\n# 注释里提到 update-test-key 不算违规\ntest-key = []\n"
+        "update-test-key = []\n"
+    ),
+    "crates/presenter/Cargo.toml": (
+        "[dependencies]\nunlucky-core = { path = \"../core\" }\n\n"
+        "[dev-dependencies]\nunlucky-core = { path = \"../core\", features = [\"update-test-key\"] }\n"
+    ),
+    ".github/workflows/ci.yml": "jobs:\n  a:\n    steps:\n      - run: cargo test\n",
+}
+
+VECTORS = [
+    (
+        "workflow 里打开它",
+        {".github/workflows/ci.yml": "jobs:\n  a:\n    steps:\n      - run: cargo build --features update-test-key\n"},
+        "red",
+    ),
+    (
+        "presenter 的 [dependencies] 里打开它",
+        {
+            "crates/presenter/Cargo.toml": (
+                "[dependencies]\nunlucky-core = { path = \"../core\", features = [\"update-test-key\"] }\n"
+            )
+        },
+        "red",
+    ),
+    (
+        "根 Cargo.toml 把依赖提起来",
+        {
+            "Cargo.toml": (
+                '[workspace.dependencies]\nunlucky-core = { path = "crates/core", '
+                'features = ["update-test-key"] }\n'
+            )
+        },
+        "red",
+    ),
+    ("打包脚本提到它", {"packaging/x.sh": "cargo build --features update-test-key\n"}, "red"),
+    (
+        "core 自己的声明（合法）",
+        {"crates/core/Cargo.toml": "[features]\nupdate-test-key = []\n"},
+        "green",
+    ),
+    (
+        "core 的声明里偷偷带子 feature（形状合法、内容非法）",
+        {"crates/core/Cargo.toml": f'[features]\n{FEATURE} = ["{OTHER_FEATURE}"]\n'},
+        "red",
+    ),
+    ("注释里提到它（合法）", {"packaging/y.py": "# 见 update-test-key 的说明\n"}, "green"),
+]
+
+
+def _scan_case(files: dict[str, str]) -> list[str]:
+    with tempfile.TemporaryDirectory(prefix="ull-test-key-guard-") as temp:
+        root = Path(temp)
+        for relative, text in files.items():
+            path = root / relative
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(text, encoding="utf-8")
+        return scan(root)
+
+
+def self_test() -> int:
+    failures = 0
+    baseline = _scan_case(BASELINE)
+    if baseline:
+        print(f"FAIL 基线被判红：{baseline}", file=sys.stderr)
+        failures += 1
+    for label, files, expect in VECTORS:
+        merged = dict(BASELINE)
+        merged.update(files)
+        problems = _scan_case(merged)
+        red = bool(problems)
+        if (expect == "red") != red:
+            print(f"FAIL 向量「{label}」期望 {expect}，实际 {'red' if red else 'green'}", file=sys.stderr)
+            failures += 1
+    print(f"self-test: {'ok' if failures == 0 else f'{failures} 处失败'}（{len(VECTORS)} 条向量 + 基线）")
+    return 0 if failures == 0 else 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="测试公钥不许进发布构建（M190）")
+    parser.add_argument("--self-test", action="store_true", help="注入变异：该红的红、该绿的绿")
+    parser.add_argument("--dir", type=Path, default=ROOT, help="仓库根（默认本文件上一级）")
+    args = parser.parse_args(argv)
+
+    if args.self_test:
+        return self_test()
+    problems = scan(args.dir)
+    for line in problems:
+        print(line, file=sys.stderr)
+    if problems:
+        print(f"FAIL：{len(problems)} 处（`{FEATURE}` 只许由 crates/presenter 的 dev-dependencies 打开）", file=sys.stderr)
+        return 1
+    print(f"ok: `{FEATURE}` 只出现在允许的位置（core 的声明 + presenter 的 dev-dependencies）")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/packaging/check_test_source_off.py b/packaging/check_test_source_off.py
new file mode 100644
index 0000000..d62bb17
--- /dev/null
+++ b/packaging/check_test_source_off.py
@@ -0,0 +1,399 @@
+#!/usr/bin/env python3
+"""测试通道守门（M169，r3：allowlist 改成**结构判定 + 默认拒绝**）。
+
+`update-test-source` 让 `core::update::job::default_source` 可被两个环境变量指向任意本地目录，而更新
+链路终点是**替换用户盘上的 exe**。「默认关 + 编译期不存在」是唯一可靠边界，所以「谁也没在流水线里
+把它打开」必须是自动断言。
+
+四条断言（任一不成立即 exit 1，CI 里红在 `.github/workflows/release-guard.yml`）：
+
+1. **workflow / 复合 action 里不许打开它**。唯一例外：`.github/workflows/ci.yml` 里**名为
+   `update-e2e` 的那个列表项**，且该项自己的文本必须带 `--test update_e2e_test`。归属按
+   `jobs.*.steps[]` 的**列表项**判（见 `split_items`），不是「最近一行 `- name:`」——后者会把追加到
+   文件末尾的无名步骤 / 无名 job 的步骤 / flow 风格步骤算进上一块（r2 复审 P2-1 实测三条全绿）。
+   **任何落不到具名步骤上的行（`jobs:` 之前的孤儿行、项外键、无名项）一律判红**：默认拒绝。
+2. **不许「打开所有 feature」**：`--all-features`、`cargo hack --feature-powerset|--each-feature|--all`。
+3. **不许设成默认**：`Cargo.toml` 里它只许是**自己的声明**（含跨行数组）；进 `default` 或别的
+   feature 的依赖数组即红。
+4. **扫描面逐项列举**（`WORKFLOW_GLOBS` / `SCRIPT_GLOBS` / `BUILD_ENTRY_GLOBS` / `CONFIG_GLOBS`）：
+   含 `.github/actions/**`、`packaging/**` 递归子目录、`Makefile`/`justfile`/`Taskfile`、以及
+   `.cargo/config*.toml`（`--cfg feature="…"` 与 `rustc-wrapper` 都能绕过 `--features`，见
+   `scan_cargo_config`）。
+
+注释剥离是**引号感知**的（`echo "#"; cargo build --features …` 里那个 `#` 不是注释）。抓不住的都是
+**故意手打**或**运行期数据流**（完整清单见 `packaging/README.md` §14）：变量拼接、两步 `$GITHUB_ENV`
+交接（第二步没有字面量——静态扫描的固有边界）、feature 改名后接回、`build.rs` 里 spawn cargo、改名复用。
+
+`--self-test` 把每条断言的**真实回归**注入临时副本（数据在 `packaging/tests/guard_vectors.json`），
+断言该红的红、该绿的绿。守门自己抓不住回归时它会先红。
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+import tempfile
+from pathlib import Path
+
+#: 被守的 feature 名（改名就得同步改本文件与各 `Cargo.toml`）。
+FEATURE = "update-test-source"
+#: 仓库根（本文件在 `packaging/` 下）与本文件自身（扫描时跳过：它必须写出 feature 名）。
+ROOT = Path(__file__).resolve().parent.parent
+GUARD = Path(__file__).resolve()
+#: 扫描面（逐个列举，不用 `**` 全仓：那会把 `target/` 拖进来）。
+WORKFLOW_GLOBS = (
+    ".github/workflows/**/*.yml",
+    ".github/workflows/**/*.yaml",
+    ".github/actions/**/*.yml",
+    ".github/actions/**/*.yaml",
+)
+SCRIPT_GLOBS = ("packaging/**/*.py", "packaging/**/*.sh", "packaging/**/*.ps1")
+BUILD_ENTRY_GLOBS = (
+    "Makefile",
+    "justfile",
+    "Justfile",
+    "Taskfile.yml",
+    "Taskfile.yaml",
+    "crates/*/Makefile",
+    "packaging/Makefile",
+)
+MANIFEST_GLOBS = ("Cargo.toml", "crates/*/Cargo.toml")
+#: cargo 配置：`--cfg feature="…"` 与 `rustc-wrapper` 都能在没有 `--features` 时打开这条通道（P2-2）。
+CONFIG_GLOBS = (
+    ".cargo/config.toml",
+    ".cargo/config",
+    "crates/*/.cargo/config.toml",
+    "crates/*/.cargo/config",
+)
+#: 任意 wrapper 都能注入 `--cfg`，文本扫描看不见 ⇒ 一律判红。
+WRAPPER_KEY = re.compile(r"^\s*(rustc|rustc-workspace)-wrapper\s*=")
+#: 唯一允许出现该 feature 的地方：**文件 + 列表项名 + 必须同在的字符串**，三者不符即红。
+ALLOWED_STEP = {
+    "workflow": ".github/workflows/ci.yml",
+    "name": "update-e2e",
+    "must_contain": "--test update_e2e_test",
+}
+#: 「打开全部 feature」的开关。`--all` 后面不许跟 `-`/字母（否则 `--all-targets` 会被误杀）。
+ALL_FEATURES = (
+    re.compile(r"--all-features\b"),
+    re.compile(r"--feature-powerset\b"),
+    re.compile(r"--each-feature\b"),
+    re.compile(r"\bcargo\s+hack\b[^\n]*\s--all(?![-\w])"),
+)
+#: YAML 列表项（任意缩进）；名字只认键位置上的 `name:`（块风格 / flow 风格）。
+LIST_ITEM = re.compile(r"^(\s*)-\s+")
+NAME_BLOCK = re.compile(r"^['\"]?name['\"]?\s*:\s*(.+)$")
+NAME_FLOW = re.compile(r"^\{[^{}]*?\bname\s*:\s*([^,}]+)")
+#: Cargo.toml 里「自己的声明」：行首 `update-test-source = [`。
+DECLARATION = re.compile(rf"^\s*{re.escape(FEATURE)}\s*=\s*\[")
+#: 块标量开头（`run: |` / `run: >-`）：其后的更深缩进行是**内容**，不是键。
+BLOCK_SCALAR = ("|", ">", "|-", ">-", "|+", ">+")
+
+
+def strip_comment(line: str) -> str:
+    """引号感知地剥注释：`#` 只有「行首或空白之后」且不在引号内时才开始注释。"""
+    quote = None
+    for index, char in enumerate(line):
+        if quote is not None:
+            if char == quote:
+                quote = None
+        elif char in "\"'":
+            quote = char
+        elif char == "#" and (index == 0 or line[index - 1].isspace()):
+            return line[:index]
+    return line
+
+
+def dangerous_flag(code: str) -> str | None:
+    """这一行有没有「打开全部 feature」的开关（返回命中的开关，便于写清原因）。"""
+    for pattern in ALL_FEATURES:
+        match = pattern.search(code)
+        if match:
+            return match.group(0)
+    return None
+
+
+def _lines(path: Path) -> list[tuple[int, str]]:
+    return list(enumerate(path.read_text(encoding="utf-8").splitlines(), start=1))
+
+
+def _name_of(key_indent: int, body: list[tuple[int, str]]) -> str | None:
+    """列表项的名字：项内**同级**的 `name:` 键（键序无关；块标量内容不当键）。
+
+    「同级」= 项首行 `- ` 之后那一列（`item.end() == key_indent`，r3 复审 P2-1）：更深缩进的
+    `- name:`（`with:` / `env:` 子列表、`run: |` 内容）**不算**项名。找不到、或出现两个**不同**的
+    `name:` 都返回 `None` ⇒ 落不到具名步骤 ⇒ 带 feature 就红（默认拒绝）。
+    """
+    in_block = False
+    found: str | None = None
+    for _number, line in body:
+        text = line.strip()
+        if not text or text.startswith("#"):
+            continue
+        indent = len(line) - len(line.lstrip(" "))
+        item = LIST_ITEM.match(line)
+        if in_block and indent > key_indent:
+            continue
+        in_block = False
+        if item and item.end() == key_indent:
+            code = strip_comment(line[item.end() :])  # 项首行：`      - name: x` → `name: x`
+        elif not item and indent == key_indent:
+            code = strip_comment(text)
+        else:
+            continue
+        for pattern in (NAME_BLOCK, NAME_FLOW):
+            match = pattern.match(code.strip())
+            if match:
+                value = match.group(1).strip().rstrip("}").strip("'\"")
+                if found is not None and found != value:
+                    return None
+                found = value
+                break
+        if code.rstrip().endswith(BLOCK_SCALAR):
+            in_block = True
+    return found
+
+
+def split_items(
+    lines: list[tuple[int, str]],
+) -> tuple[list[tuple[str | None, list[tuple[int, str]]]], list[tuple[int, str]]]:
+    """按 YAML **列表项**切块，返回（(项名, 该项的行), 孤儿行）。
+
+    每个 `- ` 起一项；更深的行归当前项，**同级或更浅的非列表行结束当前项**（job 键 / `steps:` /
+    顶层键）。落不到列表项上的行是孤儿——不属于任何步骤，带 feature 就红。
+    """
+    items: list[tuple[str | None, list[tuple[int, str]]]] = []
+    orphans: list[tuple[int, str]] = []
+    body: list[tuple[int, str]] = []
+    base, key_indent = 0, 0
+    for number, line in lines:
+        text = line.strip()
+        if not text or text.startswith("#"):
+            (body if body else orphans).append((number, line))
+            continue
+        indent = len(line) - len(line.lstrip(" "))
+        item = LIST_ITEM.match(line)
+        if item and (not body or indent <= base):
+            if body:
+                items.append((_name_of(key_indent, body), body))
+            body, base, key_indent = [(number, line)], indent, item.end()
+            continue
+        if body and indent > base:
+            body.append((number, line))
+            continue
+        if body:
+            items.append((_name_of(key_indent, body), body))
+            body = []
+        orphans.append((number, line))
+    if body:
+        items.append((_name_of(key_indent, body), body))
+    return items, orphans
+
+
+def _reason(where: str, name: str | None, text: str) -> str | None:
+    """`None` = 这一项被放行；否则返回「为什么红」的一句话（按最具体的那条给）。"""
+    if where != ALLOWED_STEP["workflow"]:
+        return f"`{FEATURE}` 只许出现在 `{ALLOWED_STEP['workflow']}` 的 `{ALLOWED_STEP['name']}` 步骤里（这里是 `{where}`）"
+    if name is None:
+        return f"这一项没有同级 `name:`，落不到具名步骤（默认拒绝）；`{where}` 里只有 `{ALLOWED_STEP['name']}` 可以用它"
+    if name != ALLOWED_STEP["name"]:
+        return f"`{where}` 里只有名为 `{ALLOWED_STEP['name']}` 的步骤可以用 `{FEATURE}`（这一项叫 `{name}`）"
+    if ALLOWED_STEP["must_contain"] not in text:
+        return f"`{where}` 的 `{name}` 步骤少了 `{ALLOWED_STEP['must_contain']}`"
+    return None
+
+
+def _flag_problems(where: str, body: list[tuple[int, str]]) -> list[str]:
+    problems: list[str] = []
+    for number, line in body:
+        flag = dangerous_flag(strip_comment(line))
+        if flag:
+            problems.append(
+                f"::error file={where}:{number}::{where} 用了 `{flag}`：它会把 `{FEATURE}` 一起打开"
+            )
+    return problems
+
+
+def scan_workflow(path: Path, root: Path) -> list[str]:
+    """扫 workflow / 复合 action：feature 只许出现在 allowlist 点名的那一项里。"""
+    where = path.relative_to(root).as_posix()
+    items, orphans = split_items(_lines(path))
+    problems = _flag_problems(where, orphans)
+    for number, line in orphans:
+        if FEATURE in strip_comment(line):
+            problems.append(
+                f"::error file={where}:{number}::{where} 这一行落不到任何具名步骤（默认拒绝）；"
+                "官方发布产物里不许有测试通道"
+            )
+    for name, body in items:
+        problems += _flag_problems(where, body)
+        codes = [(number, strip_comment(line)) for number, line in body]
+        hits = [(number, code) for number, code in codes if FEATURE in code]
+        if not hits:
+            continue
+        reason = _reason(where, name, "\n".join(code for _number, code in codes))
+        if reason is None:
+            continue
+        for number, _code in hits:
+            problems.append(
+                f"::error file={where}:{number}::{reason}；"
+                "官方发布产物里不许有测试通道（它能把更新源指向任意本地目录）"
+            )
+    return problems
+
+
+def scan_code_file(path: Path, root: Path) -> list[str]:
+    """扫脚本 / 构建入口 / cargo config：没有 allowlist，字面量或开关出现即红。"""
+    where = path.relative_to(root).as_posix()
+    problems: list[str] = []
+    for number, line in _lines(path):
+        code = strip_comment(line)
+        if not code:
+            continue
+        if FEATURE in code:
+            problems.append(
+                f"::error file={where}:{number}::{where} 打开了 `{FEATURE}`："
+                "官方发布产物里不许有测试通道（它能把更新源指向任意本地目录）"
+            )
+        flag = dangerous_flag(code)
+        if flag:
+            problems.append(
+                f"::error file={where}:{number}::{where} 用了 `{flag}`：它会把 `{FEATURE}` 一起打开"
+            )
+    return problems
+
+
+def scan_manifest(path: Path, root: Path) -> list[str]:
+    """扫 Cargo.toml：feature 只许出现在自己的声明里（**含跨行数组**），不许进别的列表。"""
+    where = path.relative_to(root).as_posix()
+    problems: list[str] = []
+    in_declaration = False
+    for number, line in _lines(path):
+        code = strip_comment(line).strip()
+        if in_declaration:
+            in_declaration = "]" not in code
+            continue
+        if FEATURE not in code:
+            continue
+        if DECLARATION.match(code):
+            in_declaration = "]" not in code
+            continue
+        problems.append(
+            f"::error file={where}:{number}::{where} 把 `{FEATURE}` 写进了别的 feature 列表："
+            "只许它是自己的声明（可跨行），不许进 `default` 或别的 feature"
+        )
+    return problems
+
+
+def scan_cargo_config(path: Path, root: Path) -> list[str]:
+    """扫 `.cargo/config*.toml`：`--cfg feature="…"` 与 `rustc-wrapper` 都能绕过 `--features`。
+
+    r3 复审 P2-2 实测：`RUSTFLAGS='--cfg=feature="update-test-source"'` 能让 `#[cfg(feature = …)]`
+    段在没有 `--features` 时编进来。`[build] rustflags` / `[env]` 靠 feature 字面量抓（走
+    `scan_code_file`）；`rustc-wrapper` 抓不住（注入什么由程序决定）⇒ 一律判红，合法用途要 review 同意。
+    """
+    problems = scan_code_file(path, root)
+    where = path.relative_to(root).as_posix()
+    for number, line in _lines(path):
+        if WRAPPER_KEY.match(strip_comment(line)):
+            problems.append(
+                f"::error file={where}:{number}::{where} 设了 rustc wrapper：wrapper 能注入任意 "
+                f"`--cfg`，静态扫描看不见它是否打开了 `{FEATURE}`（默认拒绝）"
+            )
+    return problems
+
+
+def scan(root: Path) -> list[str]:
+    """扫整个仓库，返回所有问题（空 = 绿）。"""
+    problems: list[str] = []
+    for patterns, scanner in (
+        (WORKFLOW_GLOBS, scan_workflow),
+        (SCRIPT_GLOBS, scan_code_file),
+        (BUILD_ENTRY_GLOBS, scan_code_file),
+        (CONFIG_GLOBS, scan_cargo_config),
+        (MANIFEST_GLOBS, scan_manifest),
+    ):
+        for path in sorted({p for pattern in patterns for p in root.glob(pattern)}):
+            if scanner is scan_code_file and path.resolve() == GUARD:
+                continue
+            try:
+                problems += scanner(path, root)
+            except OSError as error:
+                problems.append(f"::error file={path}::读不到 {path}：{error}")
+    return problems
+
+
+# ────────────────────────── 变异自测 ──────────────────────────
+
+#: 自测数据（基线 + 向量）单独放一份 JSON：`packaging/tests/manifest.golden.json` 是同一手法。
+#: 每个向量 = 一份「覆盖/新增的文件」；期望红的是真实回归，期望绿的是防误杀（合法写法不许红）。
+#: 条目标签自带出处（`allowlist:` / `P2-1` / `P2-2` / `误杀` / `Cargo`），红的时候一眼看得出守哪条。
+VECTORS_FILE = Path(__file__).resolve().parent / "tests" / "guard_vectors.json"
+
+
+def _load_vectors() -> tuple[dict[str, str], list[tuple[str, dict[str, str], str]]]:
+    data = json.loads(VECTORS_FILE.read_text(encoding="utf-8"))
+    return data["baseline"], [
+        (item["label"], item["files"], item["expect"]) for item in data["vectors"]
+    ]
+
+
+def _scan_case(files: dict[str, str]) -> list[str]:
+    with tempfile.TemporaryDirectory(prefix="ull-test-source-guard-") as temp:
+        root = Path(temp)
+        for relative, text in files.items():
+            path = root / relative
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(text, encoding="utf-8")
+        return scan(root)
+
+
+def self_test() -> int:
+    try:
+        base_files, vectors = _load_vectors()
+    except (OSError, ValueError, KeyError) as error:
+        print(f"::error::读不到自测向量 {VECTORS_FILE}：{error}", file=sys.stderr)
+        return 1
+    failures: list[str] = []
+    baseline = _scan_case(base_files)
+    if baseline:
+        failures.append(f"基线应当绿，实际红了：{baseline}")
+    for label, changes, expect in vectors:
+        files = dict(base_files)
+        files.update(changes)
+        hits = _scan_case(files)
+        if expect == "red" and not hits:
+            failures.append(f"{label}：注入了真实回归，守门却没红（抓不住）")
+        if expect == "green" and hits:
+            failures.append(f"{label}：应当放行，实际红了（误杀）：{hits}")
+    if failures:
+        for failure in failures:
+            print(f"::error::{failure}", file=sys.stderr)
+        return 1
+    reds = sum(1 for _label, _changes, expect in vectors if expect == "red")
+    print(f"OK: 守门自测通过（{reds} 条注入全红，{len(vectors) - reds + 1} 条基线/放行保持绿）")
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=f"守门：官方发布产物里不许有 {FEATURE}")
+    parser.add_argument("--self-test", action="store_true", help="注入变异自测（该红的红、该绿的绿）")
+    parser.add_argument("--root", type=Path, default=ROOT, help="仓根（自测用）")
+    args = parser.parse_args()
+
+    if args.self_test:
+        return self_test()
+
+    problems = scan(args.root)
+    if problems:
+        for problem in problems:
+            print(problem, file=sys.stderr)
+        return 1
+    print(f"OK: 流水线与打包脚本都没有打开 {FEATURE}（默认关，发布产物不含测试通道）")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/packaging/check_workflows_yaml.py b/packaging/check_workflows_yaml.py
new file mode 100644
index 0000000..c0c565c
--- /dev/null
+++ b/packaging/check_workflows_yaml.py
@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""Parse every workflow file with a **real YAML parser** (M190 r1 复审 P1-1).
+
+Why this exists: a raw 0x01 byte slipped into `.github/workflows/release-build.yml` (a `sed` replacement
+string that should have been `\\1`). GitHub refuses to parse such a file, so the whole run would not even
+start — and no other guard noticed, because they all read workflow files as *text* (`check_release_semantics.py`
+does `yaml_scalars()`, the file-size job only counts lines). A text scanner cannot see a control byte that
+a YAML 1.2 reader rejects outright.
+
+So: hand every `.github/workflows/*.yml` to PyYAML. Two checks, both cheap:
+  ① it parses (real error message with position, not a mystery red);
+  ② no C0 control character other than TAB/LF/CR is present (YAML 1.2 forbids them; parsers differ in
+     whether they reject, so this is the belt-and-braces half).
+
+PyYAML is preinstalled on GitHub-hosted runners; if it is not, this script installs it. If that fails too
+the gate **fails** rather than degrading to a text scan ("工具缺失也 fail" — same rule as the other guards).
+
+    python3 packaging/check_workflows_yaml.py
+    python3 packaging/check_workflows_yaml.py --self-test
+"""
+
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+WORKFLOW_DIR = Path(__file__).resolve().parent.parent / ".github/workflows"
+ALLOWED_CONTROL = {0x09, 0x0A, 0x0D}
+
+
+def load_yaml():
+    """Import PyYAML, installing it once if the runner lacks it."""
+    try:
+        import yaml  # noqa: PLC0415
+
+        return yaml
+    except ImportError:
+        print("PyYAML 缺失，尝试安装一次（pip install --quiet pyyaml）…", file=sys.stderr)
+        done = subprocess.run(
+            [sys.executable, "-m", "pip", "install", "--quiet", "pyyaml"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if done.returncode != 0:
+            print(
+                "error: 装不上 PyYAML，YAML 门禁无法运行（门禁不降级）。输出：\n" + done.stdout + done.stderr,
+                file=sys.stderr,
+            )
+            raise SystemExit(2) from None
+        import yaml  # noqa: PLC0415
+
+        return yaml
+
+
+def control_characters(data: bytes) -> list[tuple[int, int]]:
+    """`[(位置, 字节)]`：YAML 1.2 不许出现的 C0 控制字符（TAB/LF/CR 除外）。"""
+    return [(index, byte) for index, byte in enumerate(data) if byte < 0x20 and byte not in ALLOWED_CONTROL]
+
+
+def check_file(path: Path, yaml) -> list[str]:
+    """返回该文件没过的判据（空 = 通过）。"""
+    failures: list[str] = []
+    data = path.read_bytes()
+    for index, byte in control_characters(data):
+        line = data[:index].count(b"\n") + 1
+        failures.append(
+            f"::error file={path},line={line}::第 {line} 行含裸控制字符 {byte:#04x}（YAML 1.2 禁止；"
+            "常见成因是 sed/printf 把 `\\1` 写成了 0x01）"
+        )
+    try:
+        text = data.decode("utf-8")
+    except UnicodeDecodeError as error:
+        failures.append(f"::error file={path}::不是合法 UTF-8（{error}）")
+        return failures
+    try:
+        yaml.safe_load(text)
+    except Exception as error:  # noqa: BLE001 - 解析器的异常类型随版本变，这里只关心「没通过」
+        first = str(error).splitlines()[0] if str(error) else repr(error)
+        failures.append(f"::error file={path}::YAML 解析失败：{first}")
+    return failures
+
+
+def self_test() -> int:
+    """注入一枚 0x01 到临时副本，断言门禁**会红**（否则这条门禁对任何输入都绿）。"""
+    import tempfile
+
+    yaml = load_yaml()
+    failures = 0
+    sample = "name: x\non: push\njobs:\n  a:\n    runs-on: ubuntu-latest\n    steps:\n      - run: |\n          echo hi\n"
+    with tempfile.TemporaryDirectory() as tmp:
+        good = Path(tmp) / "good.yml"
+        good.write_text(sample, encoding="utf-8")
+        if check_file(good, yaml):
+            print("FAIL: 合法 YAML 被判红（误杀）", file=sys.stderr)
+            failures += 1
+        bad = Path(tmp) / "bad.yml"
+        bad.write_bytes(sample.replace('"/\\1/p"', "").encode("utf-8") + b'x\n          v=$(s/"' + bytes([1]) + b'/p)\n')
+        if not check_file(bad, yaml):
+            print("FAIL: 含裸 0x01 的 YAML 竟然通过（判据失效）", file=sys.stderr)
+            failures += 1
+        # 只让 PyYAML 判的那一半也要能红：把控制字节换成合法字符，但结构坏掉。
+        broken = Path(tmp) / "broken.yml"
+        broken.write_text("a: [1, 2\nb: 3\n", encoding="utf-8")
+        if not check_file(broken, yaml):
+            print("FAIL: 结构坏的 YAML 竟然通过", file=sys.stderr)
+            failures += 1
+    print("self-test:", "ok" if failures == 0 else f"{failures} 处失败")
+    return 0 if failures == 0 else 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="用真 YAML 解析器 parse 全部 workflow（M190 r1 P1-1）")
+    parser.add_argument("--self-test", action="store_true", help="自检：注入 0x01 / 坏结构必须红")
+    parser.add_argument("--dir", type=Path, default=WORKFLOW_DIR, help="workflow 目录（默认 .github/workflows）")
+    args = parser.parse_args(argv)
+
+    if args.self_test:
+        return self_test()
+
+    yaml = load_yaml()
+    files = sorted(args.dir.glob("*.yml")) + sorted(args.dir.glob("*.yaml"))
+    if not files:
+        print(f"error: {args.dir} 里一个 workflow 都没有（路径错了？门禁不降级）", file=sys.stderr)
+        return 2
+
+    failures: list[str] = []
+    for path in files:
+        failures.extend(check_file(path, yaml))
+
+    for line in failures:
+        print(line, file=sys.stderr)
+    if failures:
+        print(f"FAIL：{len(failures)} 条判据没过（{len(files)} 个文件）", file=sys.stderr)
+        return 1
+    print(f"ok: {len(files)} 个 workflow 全部能被真 YAML 解析器 parse，且无裸控制字符")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
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  --data-dir `）渲出一帧 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/docs/artifacts-and-version.md b/packaging/docs/artifacts-and-version.md
new file mode 100644
index 0000000..5ed1abb
--- /dev/null
+++ b/packaging/docs/artifacts-and-version.md
@@ -0,0 +1,53 @@
+# 产物矩阵与版本来源（M145 拆自 `packaging/README.md`）
+
+本文承载原 `packaging/README.md` 的 §1、§2，**节号沿用原编号**（全仓 `packaging/README.md §N` 这类引用照旧有效，
+对照表在 [`packaging/README.md`](../README.md) 的索引里）。内容一字未改、只搬家：本行以上是 M145 新增的导航说明，
+以下逐行取自原文件。
+
+## 1. 产物矩阵
+
+| 槽位 | 本版发布 | 产物文件名 | 形态 | 归档内容 |
+|------|---------|-----------|------|---------|
+| `windows-x64` | ✅ 发布 | `unlucky-launcher__windows_x64.exe` | **裸 exe**（双击即用） | exe 单文件；三份合规文本作为并列 Release 资产 |
+| `linux-x64` | ✅ 发布 | `unlucky-launcher__linux_x64.tar.gz` | 单二进制归档 | `unlucky-launcher` + `LICENSE` + `NOTICE` + `README.md`；CI 在原生 `ubuntu-22.04`（glibc 2.35 地板）上构建，**并有同槽位的 xvfb 运行时门禁**（真渲一帧 + `[theme]` / `[backend] final` 日志断言 + 像素判定）；真机验收证据见 `docs/linux-evidence.md` |
+| `windows-arm64` | ❌ 不发布（构建取证中） | `unlucky-launcher__windows_arm64.exe` | **裸 exe**（同 x64 策略） | 同上；CI 在**原生** `windows-11-arm`（Windows 11 Arm64 + VS2026 镜像）上构建，**M164 起编译前体检只取证、不再判定红绿**（此前五轮全红其实全红在那个误判的体检步），**红了不挡发布**（M142，见 §3） |
+| `linux-arm64` | ❌ 已构建、不发布（运行时零证据） | `unlucky-launcher__linux_arm64.tar.gz` | 单二进制归档（原生 `ubuntu-22.04-arm` 构建，与 x64 同 glibc 地板） | 同上；M184 起**默认就编**（`mode: ci`），但没有任何 ARM64 真机跑过一帧 ⇒ 不进 `PUBLISH_SLOTS`。解锁条件 = 真机渲出一帧 + 主题日志 |
+| `macos-arm64` | ❌ 不构建（未验证） | `unlucky-launcher__macos_arm64.tar.gz` | 单二进制归档 | 同上 |
+| `macos-x64` | ❌ 不构建（未验证） | `unlucky-launcher__macos_x64.tar.gz` | 单二进制归档 | 同上 |
+| 每槽位 | 随所属槽位 | `ull__<平台>_<架构>[.exe]` | **裸 CLI 文件**（独立资产，不进 tar.gz） | 零 UI 依赖的 `ull` 本体，进同一份 `SHA256SUMS.txt` |
+| 全平台 | 仅已发布资产 | `SHA256SUMS.txt` | 校验清单 | 每行 `␠␠<文件名>`（`sha256sum -c` 可直吃） |
+| 全平台 | 仅已发布资产 | `manifest.json` | **更新清单**（D50，见 `README.md` §13） | 渠道 + 版本 + 各平台产物（`target`/`format`/`url`/`size`/`sha256`）；生成器 `make_manifest.py` |
+
+约定细节：
+
+- **「不构建」= CI 默认根本不跑**（M139）：macOS 那两档未验证，产物不给用户、构建配额也不花；要整表六槽位取证走
+  `gh workflow run release.yml -f all_slots=true`（§3）。发布白名单**是 `windows-x64` + `linux-x64`**（M184）。
+  「已构建但不发布」是独立的一档（`linux-arm64`、`windows-arm64`）：它们 `mode: ci`、每轮都编，产物留在
+  `dist-` artifact 里取证，裁剪步会把它们剔出 Release。
+  （M164/M184）名单 ⇄ 产物两个方向都有守卫 `packaging/check_publish_slots.py`：声明了缺产物 ⇒ 红；有产物但没声明 ⇒
+  `::warning::` 明说「未发布、会被裁掉」；`mode: ci` 却本次没产物 ⇒ 也打 `::warning::`（那一档红了要看得见）。
+- **产物命名**：`<名字>_<版本号>_<平台>_<架构>`，下划线分段、**不带实现细节字样**（不出现 `iced`）；真相源是 `make_artifacts.py::asset_stem()`。
+- **"单文件"指可执行文件本身零运行时依赖**（无 WebView、无 JRE、无 sidecar、无 DLL 旁挂）；归档里的三份合规文本是许可义务、不是运行时依赖，Windows 因为"一个 exe 装不下文本"，
+  把 `LICENSE` / `NOTICE` / `README.md` 作为 Release 的并列资产分发，条款同样随下载走。
+- 归档解压后是**一个顶层目录** `unlucky-launcher__<平台>_<架构>/`，用户不会解压出一堆散文件。
+- **`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` / 本文矩阵不变。
+- `` 不带前导 `v`（tag 是 `v0.2.2`，文件名是 `0.2.2`）——由脚本统一裁剪。
+- UNIX 归档内 `mtime`/`uid`/`gid` 归零、权限固定（二进制 0755、文本 0644），
+  同源构建的 sha256 不受打包时刻影响。
+- **架构不靠猜**：脚本打包前回读二进制的可执行文件头（PE 机器码 / ELF `e_machine` / Mach-O
+  `cputype`），与槽位声明的架构不符即失败——不会出现"名字是 arm64、内容还是 x64"的假产物。
+
+## 2. 版本来源（唯一真相源）
+
+版本号只有一个来源：**`Cargo.toml` 的 `[workspace.package] version`**。
+
+- `` 由 `make_artifacts.py` 通过 `cargo metadata --no-deps` 读出（不是正则扒文件），
+  任何一个 workspace member 版本不一致时直接失败。
+- 带 tag 构建时（CI）额外传 `--version "$TAG"`：脚本裁剪 `v` 后与 `Cargo.toml` 交叉校验，
+  **不一致即失败**——避免出现 tag 说 0.2.2、产物里写 0.2.1 的发布事故。
+- `ull --version` 必报同一版本（脚本打包前跑一次冒烟 `ull --version` 断言版本串在其中），
+  这是 `env!("CARGO_PKG_VERSION")` 的实际输出，不是估算。
+- 发布流程：先改 `Cargo.toml` 版本 + 提交 → `git tag v` → 推送 tag 触发流水线。
diff --git a/packaging/docs/build-and-ci.md b/packaging/docs/build-and-ci.md
new file mode 100644
index 0000000..b076911
--- /dev/null
+++ b/packaging/docs/build-and-ci.md
@@ -0,0 +1,139 @@
+# 构建与 CI 流水线（M145 拆自 `packaging/README.md`）
+
+本文承载原 `packaging/README.md` 的 §3，**节号沿用原编号**（全仓 `packaging/README.md §N` 这类引用照旧有效，
+对照表在 [`packaging/README.md`](../README.md) 的索引里）。内容一字未改、只搬家：本行以上是 M145 新增的导航说明，
+以下逐行取自原文件。
+
+## 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.2   # 顺带校验版本一致性
+python packaging/make_artifacts.py --no-smoke         # 跳过 ull --version 冒烟
+```
+
+脚本按宿主自动判定槽位（Windows x64 / Windows arm64 / Linux x64 / Linux arm64 / macOS arm64 /
+macOS x64），其它组合直接报错退出——不在矩阵里的平台不出"凑合能跑"的产物。
+
+交叉构建（例如在 x64 宿主上产 Windows arm64 产物）靠两个参数把"产物根"和"槽位"显式喂进去，
+脚本不去猜宿主与产物是不是同一架构（**CI 不用这条路径**，见下）：
+
+```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 不走交叉**（M140）：
+`windows-arm64` 在原生 `windows-11-arm` 上编，宿主=产物架构 → 冒烟**真跑**；`linux-arm64` 也是原生
+`ubuntu-22.04-arm` 构建 → 冒烟在 runner 上真跑（M184 起它默认就编，不再只在 `all_slots=true` 的取证跑里出现）。
+
+### CI（默认跑四个槽位：Windows 两档 + Linux 两档；`all_slots=true` 才整表六槽位）
+
+`.github/workflows/release.yml`：
+
+- 触发：`push` tag `v*`；`workflow_dispatch` 只构建不发布，且多一个 `all_slots` 开关（**默认 false =
+  只跑四个槽位**，true = 整表六槽位都编一遍取证）。`inputs.prerelease` **只在 tag ref 上 dispatch
+  才可达**——Actions 页面的 "Run workflow" 只能选分支，要跑 tag 得 `gh workflow run release.yml --ref v0.2.3`。
+  分支 ref 的 dispatch 与 push 一样被 `release` job 的 `if: github.ref_type == 'tag'` 挡在发布之外，所以
+  「分支 ref 的 dispatch 只构建不发布」与「tag ref 上 dispatch 能选标记」是两条互不冲突的规则。
+- 矩阵**由 `plan` job 按 `all_slots` 生成**（`matrix: ${{ fromJSON(needs.plan.outputs.matrix) }}`：矩阵本身
+  不能带 `if`，而 `strategy` 可读 `needs`），槽位表只在该 job 里有一份：`windows-latest` x64 与
+  **原生** `windows-11-arm` arm64（M140；后者是公开仓免费的标准 arm64 runner，4C/16G）——两者都是 MSVC +
+  `-C target-feature=+crt-static`、产物都在 `target/release`，标 `mode: ci`（默认编）；
+  （M184）`ubuntu-22.04`（glibc 2.35 地板）与 `ubuntu-22.04-arm`（原生 ARM64，同地板）**也标 `mode: ci`** ——
+  tag 推送默认就编这两档；只剩 `macos-latest` / `macos-15-intel` 是 `mode: probe`，**未验证、默认一个都不编**，
+  只有 `all_slots=true` 才进矩阵。
+- **运行时证据决定发布，构建绿了不够**：`linux-x64` 进 `PUBLISH_SLOTS` 的依据是「release 产物真开窗渲出一帧」
+  （真机 WSLg + 截图 + `[theme]` / `[backend] final` 日志，实测输出见 `packaging/docs/linux-evidence.md`），
+  所以 `release-build.yml` 给**这个槽位**配了一条 xvfb 运行时冒烟步（`if: inputs.slot == 'linux-x64'`）：
+  装 xvfb → `xvfb-run … --software-renderer --screenshot` 起 **release** 产物 → 断言 `[theme] source=` 与
+  `[backend] final=… result=started` 两行 → `check_screenshot.py` 判像素 → 上传首帧图。
+  `linux-arm64` **刻意没有**这条判据：arm64 上这条路一次都没验过，给它加一条没验证过的门禁就是造红。
+- 每个槽位 `cargo build --release --locked`（**不传 `--target`**：每槽原生编译，交叉槽位没了）。arm64 槽位在编译前
+  **把工具链显式备齐**（M164）：`rustup target add aarch64-pc-windows-msvc`、用微软自己的 `vcvarsall.bat arm64` 取
+  `LIB`/`INCLUDE`（写进本步环境与 `$GITHUB_ENV`）、用 vswhere 定位 arm64 `link.exe` 后显式导出
+  `CARGO_TARGET_AARCH64_PC_WINDOWS_MSVC_LINKER`（Hostarm64 原生优先、Hostx64 次之；`-find` 的斜杠/反斜杠两种形态都试）。
+  顺序不能反：只覆盖链接器而不给 `LIB`，撞上的就是 `LNK1181: cannot open input file 'kernel32.lib'`。
+  **`cmd //c` 不能直接收「带引号的 vcvarsall 路径」**：MSYS 会把 `"` 改写成 `\"`，cmd 的 `/c` 剥离规则接不住，
+  结果 `LIB`/`INCLUDE` 全空（M164 复审实测；`cmd //c` 只调**不含引号**的路径是好的）。故本步往 `$RUNNER_TEMP`
+  写一个 CRLF 的 wrapper `.bat`（`call "" arm64` + `set`），`cmd //c` 只收相对文件名——引号留在
+  `.bat` 内部由 cmd 自己解析，路径带空格也不受影响。
+- **编译前体检已降级为「只取证」**（M164）：M141/M142 的版本用 `find` 猜 `um/arm64/kernel32.lib` 在不在、猜缺就
+  `exit 1` —— v0.2.1~v0.2.3 五轮全红在**那一步**，`cargo build` 一次都没跑过（永远 skipped），而它跟自己打的快照
+  自相矛盾（`um/arm64` 明明在）。现在那一步只打印 vswhere 组件查询、各目录 `.lib` **计数**与 `link.exe` 候选，
+  永不 `exit 1`；**红绿只由编译器 / 链接器 / 静态 CRT 导入表门禁决定**。runner 实况：`windows-11-arm` 自 2026-09
+  是 Windows 11 Arm64 + **Visual Studio 2026** 镜像，`VC.Tools.ARM64` 与 `Windows11SDK.22621/26100` 都已装好。
+- **发布白名单（`PUBLISH_SLOTS`，唯一开关）**：只有白名单里的槽位进 Release 与 `SHA256SUMS.txt`。**M184 起是
+  `windows-x64 linux-x64`**：齐全性检查是「名单内少一档就 fail」，所以 `linux-x64` 进来之后它的构建红了就挡住整次
+  发布 —— 这正是「声明为 ci 的槽位失败必须阻断发布」那条要求，判据落在 `check_publish_slots.py` 的 `--dist` 模式里
+  （`release` job 是 `always()`，构建矩阵里红一档不会让它跳过，挡住它的只能是那道守卫）。
+  `linux-arm64` 本轮**只构建不发布**：它没有任何运行时证据（没有 ARM64 真机跑过一帧，也没有 arm64 的 xvfb 冒烟），
+  **解锁条件 = 真机上真跑出一帧 + 主题日志**，之后才把键加进 `release-publish.yml` 那一行，再同步 §1/§9 与
+  `release-notes.md`。`windows-arm64` 同理仍未进名单（M164：它的五轮红全红在误判的体检步，等下一 tag 的 CI 证）。
+  **可逆且只是一行**：翻牌只改 `PUBLISH_SLOTS` 那一行，齐全性与 SHA256SUMS 自动跟着扩。
+- **耗时（M184 估算，2 槽位 → 4 槽位）**：多出的两档是**并行**跑的（矩阵 `fail-fast: false`），所以墙钟增量 ≈
+  「`linux-x64` 那一档的时长（含新增 xvfb 冒烟步约 1~2 分钟）」与「`linux-arm64` 那一档的时长」取大者，而不是两者相加；
+  真正增加的是**并发作业数与总机时**（约 +2× 单槽位机时，公开仓 arm64 Linux runner 不额外计费）。
+  发布侧只多两个资产的裁剪/摘要/上传（秒级）。细节与逐项拆解见 `packaging/docs/linux-evidence.md`。
+- **名单 ⇄ 产物两个方向都有守卫（M164，M184 扩）**：`packaging/check_publish_slots.py`，同一份代码两处跑 —— PR 阶段
+  （`.github/workflows/release-guard.yml`）断言「名单非空 / 每项都是槽位表里 `mode: ci` 的档」；发布侧
+  （`release-publish.yml` 的 `--dist` 模式，跑在**裁剪前**的全量集上）断言「声明了就得有 GUI 与 CLI 两个产物，
+  缺一个就红」，并把「有产物但名单没声明」打成 `::warning::` 明说未发布 —— M142 之后那个方向是静的（裁剪步只
+  `echo drop:`），一个真编出来的 arm64 会被就地删掉而没人知道。M184 补第三条：`mode: ci` 的槽位**本次连产物都没有**
+  （那一档构建红了）也打 `::warning::`，别只在表里少一行。`--self-test` 注入 11 条回归（含「声明的 `linux-x64` 构建红了
+  ⇒ 必须红」「`linux-arm64` 有产物但没声明 ⇒ 只警告」「提前把 `linux-arm64` 写进名单 ⇒ 缺产物必红」），本地一条命令可跑。
+- `release` job：下载全部 artifact → **发布名单守卫**（断言 + 未发布提示）→ 按白名单裁剪 → 重算 `SHA256SUMS.txt` →
+  用 `packaging/release-notes.md` 模板渲染支持矩阵 → 生成更新清单 `manifest.json` → `gh release create`
+  （**push tag 默认建稳定版**：不带任何标记）。
+- **同一 tag 重跑幂等**：`gh release view` 命中已存在的 Release 时改走 `gh release upload --clobber`
+  + `gh release edit`，覆盖资产与说明而不是再 `create`（`create` 遇已存在会失败，把流水线最后一步染红）。
+- **预发布标记的语义表（M163，唯一真相源 `packaging/release_marker.py`）**：
+
+  | 触发 | create（新建 Release） | edit（Release 已存在） |
+  | --- | --- | --- |
+  | `push` tag `v*`（含其 Re-run） | **稳定版**（不带标记） | 不碰标记 |
+  | `workflow_dispatch` + `prerelease=true` | 预发布 | 显式改成预发布 |
+  | `workflow_dispatch` + `prerelease=false`（默认） | 稳定版 | 显式改成稳定版 |
+
+  空串必须是稳定版：`releases/latest/download/*` 只指向**非 prerelease** 的最新 Release，而自更新清单固定取
+  `releases/latest/download/manifest.json`（D50）——push tag 打成预发布，稳定通道就一直是 404（v0.2.2 至今
+  如此，M163 修的就是这条；**v0.2.2 那个 Release 保留为历史预发布不动**，稳定通道以 v0.2.3 为起点）。
+  edit 的空串是「不碰」而不是「改成稳定版」：同 tag 重跑**不会**把用户手工提成稳定版的 Release 翻回预发布。
+  要改已发版本的标记仍是两条等价路：① `gh workflow run release.yml --ref  -f prerelease=false`
+  （落到 edit 分支显式断言）② 直接 `gh release edit  --prerelease=false`（不经流水线，后续默认重跑不碰它）。
+- **这条语义有守门（M163）**：`packaging/check_release_semantics.py`（CI 在 `.github/workflows/release-guard.yml`）
+  断言四件事：标记表逐条对（push tag 的 create 不含 `--prerelease`）、把 `release_marker.py --emit-bash` 的产物
+  **真灌进 bash** 读回两个数组、`release-publish.yml` 的可执行内容里没有 `--prerelease` 字面量、dispatch 默认值
+  `== false`（读 YAML 结构，不是 grep）。`--self-mutation` 再把「默认值改回 true」「塞回字面量」「表里 push 分支
+  改成预发布」注入临时副本，断言守门**每一项都红**、基线绿——守门自己抓不住回归时它先红。
+- **M145 拆分（本节新增的唯一一段）**：上面所有口径都还成立，只是"在哪个文件里"变了 —— `release.yml` 只留
+  触发、`concurrency`、槽位表（`plan`）与两个 `uses:` 编排；`build` job 的 11 步逐字搬进
+  `.github/workflows/release-build.yml`（`workflow_call`，四个矩阵键换成同名 `inputs.*`），`release` job 的 6 步
+  逐字搬进 `.github/workflows/release-publish.yml`（同 `workflow_call`，`secrets.GITHUB_TOKEN` 改为调用方显式透传
+  的 secret）。触发（`on`）、`env`、顶层 `permissions`、`concurrency` 与 `plan` 的槽位表在 M145 搬家时**一字未动**；
+  后来只有 M163 动过 `on` 里 `prerelease` 的默认值（`true` → `false`，见上面那张语义表），M164 改过
+  `release-build.yml` 的 arm64 体检步与 `cargo build` 步、并在 `release-publish.yml` 裁剪前插了「发布名单守卫」
+  （于是本分支 8 步：checkout / download / **守卫** / 裁剪 / 重算 SHA256SUMS / manifest / 说明 / `gh release`；
+  搬家时 6 步、主线 7 步）。M184 又在 `release-build.yml` 里给 `linux-x64` 插了「运行时冒烟 + 上传首帧图」两步
+  （该文件 11 → 13 步，发布侧仍是 8 步）。改槽位仍只改 `release.yml` 那一处（`PUBLISH_SLOTS` 白名单在
+  `release-publish.yml`，翻牌时要改的仍是那两处）。
+- **M149 微软登录 id 的烘焙**：`release-build.yml` 的 `cargo build` 步带 `env.ULL_MSA_CLIENT_ID`（值
+  `${{ secrets.ULL_MSA_CLIENT_ID }}`），`option_env!` 把它烘进二进制，于是发布产物装完即可登录。id **不进
+  git 文件**：真值放仓库 Secret，由 `release.yml` 的 `build` job 按名显式透传（可复用工作流拿不到未显式传入的
+  secret；这里刻意不用 `secrets: inherit`——那会把仓库全部 secret 一起透进被调方）。Secret 未录入、或在整个
+  Actions 之外求值时该表达式为空串，`client_id.rs` 把空白当「没配」⇒ 非官方构建只是不烘 id，不会拿空 id 去
+  联网；本地自烘仍走 `ULL_MSA_CLIENT_ID= cargo build`。**别把这个 env 导出到跑 `cargo test` 的 shell**：
+  presenter 的 M132 入口锚会在「已烘焙 id」的构建里**故意红**（它要求一个两处都没有 id 的构建）。
+- 发布说明模板（`release-notes.md`）的 "Known limitations" 里，微软登录一条已改为「开箱即用、env 可覆盖」。
+
+Windows 为什么用 MSVC 静态 CRT 而不是本机这套 GNU 工具链：两者都属"标准工具链"（D21），
+但发布产物要**不依赖 VC++ 可再发行包**，`+crt-static` 把 CRT 静态链进 exe，Win10+ 的 UCRT 本身是
+系统组件，于是 exe 真正单文件可拷走。GNU 交叉产物在 CI 上还要拉 MinGW 链接器，收益为零。
diff --git a/packaging/docs/compliance-support-boundaries.md b/packaging/docs/compliance-support-boundaries.md
new file mode 100644
index 0000000..cd611df
--- /dev/null
+++ b/packaging/docs/compliance-support-boundaries.md
@@ -0,0 +1,72 @@
+# 发行合规、支持矩阵与已知边界（M145 拆自 `packaging/README.md`）
+
+本文承载原 `packaging/README.md` 的 §8、§9、§10，**节号沿用原编号**（全仓 `packaging/README.md §N` 这类引用照旧有效，
+对照表在 [`packaging/README.md`](../README.md) 的索引里）。内容一字未改、只搬家：本行以上是 M145 新增的导航说明，
+以下逐行取自原文件。
+
+## 8. 发行合规
+
+- `LICENSE`（Apache-2.0 全文）与 `NOTICE`（含 Slint Royalty-Free 2.0 义务说明）随包分发，
+  三份文本在 UNIX 归档内、在 Windows 侧作为并列 Release 资产。
+- Slint 的 RF 2.0 义务只跟 `v0.1.0` 那批资产：当时关于页有 `AboutSlint` 部件、选的是不触发 GPL 分支的 RF 分支
+  （见 `deny.toml` 的许可证白名单注释）。现役 iced UI 里没有、也不需要任何 Slint 部件。
+- **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 系统自带） |
+| Linux x64 X11 | ✅ | 一等 | glibc 2.35+（`ubuntu-22.04` 原生构建即地板）、xkbcommon、fontconfig、libGL（或软渲染）、xcb |
+| Linux x64 Wayland | ✅（同一归档；**Wayland 路径未验**） | 支持 | 上述 + wayland-client（XWayland 应用仍需 X11 那套） |
+| Windows 11 ARM64 | ❌ 不发布（构建取证中） | 一等（启动器产物） | 无额外库；启动器原生运行，游戏本体走系统 x64 模拟层 + x64 JDK |
+| Linux arm64 | ❌ 已构建、不发布（**运行时零证据**） | 一等（未真机验证） | glibc 2.35+（`ubuntu-22.04-arm` 原生构建，**与 x64 同地板**）、xkbcommon、fontconfig、libGL、xcb / wayland-client |
+| macOS 12+（arm64 / x64） | ❌ 不构建 | 一等（未真机验证） | 无第三方库；未签名需去 quarantine |
+| Windows 8.1/8/7 | — | 不支持 | 基线已上调（D21） |
+| Android Termux + X11 | — | 试验级（不承诺） | CLI 与 GUI 均需源码自建；GUI 已在单机真机验证两条路径各一次（CPU 软渲染 + 自编 Mesa/turnip GPU 加速，配方见 `packaging/docs/termux-glibc-build.md`、证据见 `README.termux.md`），不在本发布矩阵内 |
+
+`packaging/release-notes.md` 的 "Support matrix" 表与上表逐行对应（英文版同样带 published / not
+published 一列，Termux 行标注 experimental）——改一边必须同步另一边，否则标题里的"一致"就是假话。
+
+**M184 的翻牌（Linux x64 进发布名单，arm64 只构建）**：发布开关仍是 `release-publish.yml` 的 `PUBLISH_SLOTS`，
+现在是 `windows-x64 linux-x64`；`release.yml` 槽位表里 `linux-x64` 与 `linux-arm64` 都是 `mode: ci`（tag 推送默认就编）。
+两档的唯一差别是**运行时证据**：
+
+- `linux-x64` 有：release 产物在 Linux 真机（Ubuntu 22.04 + WSLg 真窗口）渲出一帧、`[theme]` 与
+  `[backend] final=… result=started` 两行齐全、像素判定通过；`release-build.yml` 里还有一条**同槽位**的 xvfb
+  运行时门禁，每轮发布都重跑（证据与实测输出：`packaging/docs/linux-evidence.md`）。
+- `linux-arm64` 没有：没有任何 ARM64 机器跑过它一帧，也没有 arm64 的 xvfb 冒烟。**解锁条件 = 真机（或原生
+  ARM64 runner）上真跑出一帧 + 主题日志**，之后才把键加进 `PUBLISH_SLOTS`。构建绿了不算解锁，别拿没跑过的包发人。
+
+`windows-arm64` 为什么还没进名单（M164 遗留）：它 v0.2.1~v0.2.3 的红**全部**红在一个编译前体检步（`find` 猜 SDK 的
+`um/arm64/kernel32.lib`），`cargo build` 一次都没跑过；M164 把那个门禁降级为只取证、判定权交回编译器，但「能不能
+出 PE」只能由**下一 tag 的 CI** 证明。名单 ⇄ 产物的两个方向都有守卫（`packaging/check_publish_slots.py`）：
+声明了缺产物 ⇒ 红（这正是「声明为 ci 的槽位构建红了就挡住发布」那条闸），有产物没声明 ⇒ `::warning::` 明说未发布，
+`mode: ci` 却本次没产物 ⇒ 也打 `::warning::`（红了要看得见）—— 所以那次 CI 真出包之后，翻一行名单即可。
+
+## 10. 已知边界 / 后续
+
+1. **GUI 的 `--version` 已解决**（M82）：现在命中子命令分发，输出与 `ull --version` 同一条版本 + 系统摘要后退出，
+   不再开窗；§7.2 里「无输出、8 秒后被 timeout 杀掉」那行是**改之前**的记录，留作对照。
+2. **签名/公证**：Windows 无 Authenticode、macOS 无 codesign/notarize（都要证书/开发者账号），
+   当前以 SHA256SUMS + Release 说明作为完整性参考。
+3. **macOS `.app` bundle / `.dmg`**：与单文件承诺冲突，暂不做；若用户要 Dock 图标再单开 mission。
+4. **Linux musl 静态版**：可彻底摆脱 glibc 地板，但现役 iced 版（winit + wgpu）在 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` 的老式抱怨，不影响产物；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：宿主判定注入、可执行文件头识别、把真 exe 的 PE 机器码改成 ARM64 当 stub 走完全流程）。
+8. **Linux 上自更新只"能查不能装"**（M184 发布 Linux x64 之后才有意义）：清单现在会带 `linux-x64` 的
+   `portable-zip` 产物，而 `ull update apply` 只做便携单文件 `.exe` 的自替换
+   （`crates/core/src/update/job.rs::ensure_self_replaceable`）——Linux 上它会带具名原因**拒绝**
+   （"发布里的 linux-x64 产物是 portable-zip 形态，不能原地替换启动器 … 压缩包请解压后再用"），
+   不会半装坏。Linux 的更新方式仍是「下载新归档覆盖旧副本」。真要做 Linux 自更新（换目录里的文件再重启）
+   是另一件事，未规划。
diff --git a/packaging/docs/gpu-evidence.md b/packaging/docs/gpu-evidence.md
new file mode 100644
index 0000000..98384d0
--- /dev/null
+++ b/packaging/docs/gpu-evidence.md
@@ -0,0 +1,235 @@
+# GPU 截图证据账（M249）
+
+判据的**唯一实现**是 `packaging/check_gpu_shot.py`（零第三方依赖，19 条自测向量）。
+样本是 M246 在本机的实测产物 `DevDocs/artifacts/gpu-probe/`（`DevDocs/` 被 `.gitignore:6` 忽略，
+**图不进仓库**，所以这里只引它的读数，不引它的字节）。
+
+一句话：这套判据把「这张图是 GPU 档出的」从**人读日志**变成**可复跑的退出码**，但它证明的是
+「像素由哪条光栅化路径产出」，**不是**「用户看到的窗口长这样」。第 4/5 节逐条划线。
+
+**CI 接线（M253）在第 8 节**：`--self-test` 无条件跑，真实产物判据只在有可用产物时跑；
+**无 GPU 时显式跳过并写明原因，跳过与通过分开写**（跳过 ≠ 通过）。
+
+## 1. 怎么跑
+
+```text
+python packaging/check_gpu_shot.py                # 正例：六条判据，0/1 退出
+python packaging/check_gpu_shot.py  --expect-refuse [PNG]  # 负例：拒绝降级出图是否成立
+python packaging/check_gpu_shot.py --self-test                     # 19 条向量（数据 tests/gpu_shot_vectors.json，脚手架 tests/gpu_shot_selftest.py）
+```
+
+退出码：`0` = 判据全过；`1` = 有判据没过（**逐条点名**，不只印 FAILED）；`2` = 用法错（少参数 / 认不出的参数）。
+判据不看日志的**请求值**（`[probe] renderer = wgpu` 只是意图），只看**结果行**（`[shot] … renderer=`）。
+
+**取日志必须带 `ULL_GPU_LOG=info`**：`Selected: AdapterInfo { … }` 那一行是 wgpu 的 info 日志，
+默认级别下根本不落盘（实测：a1b 那份 24 行 stderr 里 `^\[gpu\]` **0 条**，见 §5 第 2 条）。
+
+## 2. 本机实跑退出码（M246 产物，逐条）
+
+| 用例 | 命令（节选） | 退出码 | 判据怎么说话 |
+|------|-------------|--------|-------------|
+| A1 正例 GPU | `a1-gpu.stderr.log + a1-gpu-light.png` | **0** | 6/6 过：`renderer=wgpu`、`device_type=DiscreteGpu`（RX 6600 XT / Vulkan）、1180x760、`final=wgpu result=started`、唯一色 1856 / σ 33.21 / 强边缘 0.05778 |
+| A2 正例 GPU（preflight） | `a2-preflight.stderr.log + a2-preflight-gpu.png` | **0** | 6/6 过（与 A1 字节相同的图，另带 `[gpu-preflight] ok type=DiscreteGpu`） |
+| A4 正例 GPU（auto→shell） | `a4-auto.stderr.log + a4-auto-shell.png` | **0** | 6/6 过：`reason=auto-hardware-adapter` 也真的落到 wgpu |
+| A3 CPU 档 | `a3-cpu.stderr.log + a3-cpu-light.png` | **1** | 3 条红：`renderer=tiny-skia`、无 `Selected` 行、`final=tiny-skia`（PNG 本身没问题：唯一色 2519 / σ 35.43） |
+| A3b CPU 档重复 | `a3b-cpu-repeat.stderr.log + a3b-cpu-light.png` | **1** | 同上（重复性对照，结论一致） |
+| A5 CPU 档 shell | `a5-cpu-shell.stderr.log + a5-cpu-shell.png` | **1** | 同上 |
+| A6 负例，按正例口径判 | `a6-negative-refuse.stderr.log + a6-negative-refuse.png` | **1** | **6 条全红**（其中 3 条是「PNG 不存在」——负例本来就没图） |
+| A6 负例，`--expect-refuse`（传 PNG 路径） | `a6-negative-refuse.stderr.log --expect-refuse a6-negative-refuse.png` | **0** | **3/3** 过：`via=refuse`、无出图行、目标 PNG 不存在 |
+| A6 负例，`--expect-refuse`（不传 PNG） | `a6-negative-refuse.stderr.log --expect-refuse` | **0** | **2/2** 过（判据 9 不登记：`--expect-refuse` 的 PNG 参数是可选的） |
+| A1b 日志 + A1b 图 | `a1b-gpu-repeat.stderr.log + a1b-gpu-light.png` | **1** | 见 §5 第 2 条：这份日志没开 `ULL_GPU_LOG=info`，**没有** `Selected` 行 ⇒ 单独看它无法自证适配器 |
+| 串味：A1 日志 + A3 的 CPU 图 | `a1-gpu.stderr.log + a3-cpu-light.png` | **0** | **这是已知盲区**，见 §5 第 1 条（两张图同为 1180x760） |
+
+A6 的负例形状（`WGPU_BACKEND=metal`）：`Available adapters: []` → `wgpu 初始化失败（具名）` →
+`拒绝降级出图` → `[backend] final=none result=failed … via=refuse`，退出码 1，**没有 PNG**。
+
+## 3. 六条判据：每条抓得住什么、抓不住什么
+
+判据 1–3 来自 M246 的实测口径，4–6 是为「日志与图对不上号」补的钉子。每条都能单独判红、单独打印。
+
+| # | 判据 | 抓得住 | 抓不住 |
+|---|------|--------|--------|
+| 1 | **全部** `[shot] … renderer=` 行都是 `wgpu`（`set(renderers) == {"wgpu"}`） | 「其实走了 CPU 档」——CPU 档在这行写 `renderer=tiny-skia`（M97 起这行打的是**实际**后端，不是请求值，见 `crates/app-iced/src/renderer/mod.rs:52`） | 只证明这些行被打印过；日志被手工拼装、或从别的进程拷来的行，它分不清（判据只读文本）；「一次运行里混了两种 renderer」（`>>` 拼接、`via=respawn` 降级）**一律判红**，但**同种 renderer 的多次运行拼在一起**看不出来（§5 第 7 条） |
+| 2 | `Selected: AdapterInfo { device_type: X }` 且 `X ∉ {Cpu, Other}`；**取不到 `X` 一律判红** | 「wgpu 真建成了设备，而且选中的不是 WARP(`Cpu`) / Gl 兼容层(`Other`)」；与 `crates/app-iced/src/probe.rs:165-167` 的硬件判据同口径 | 选中的是**哪一块**卡不判（独显 vs 集显都算硬件）；不看 `Available adapters` 那 12 条，只看 `Selected` 那条 —— 也就抓不住「枚举里有独显、实际选了集显」之外的更细的驱动行为；**多行 Debug / 字段缺失**时不知道真值是啥，只按「取不到即判红」处理（宁可假红：iced 换成 pretty-print Debug 时真 GPU 图会被判红，得回来改正则） |
+| 3 | PNG 能解码且像素数 > 0 | 0 字节 / 半截写入 / 根本不是 PNG（签名、IHDR、IDAT 逐层查） | 只管「能解出来」，不管内容对不对（那是判据 6 的事）；不解调色板与隔行 PNG（沿用 `check_screenshot.py` 的同一条限制） |
+| 4 | PNG 宽高 = 日志 `[shot]` 声明的宽高 | 拿错文件的第一步：日志说 1180x760、图是别的尺寸 | **同尺寸互换抓不住**（见 §5 第 1 条）；分辨率和内容是否同一帧也抓不住 |
+| 5 | `[backend] final=wgpu result=started` | 后端结论行与判据 1/2 自相矛盾（例如 `final=none … via=refuse`） | 需要 `ULL_ACCEPTANCE=1` 才有这行；只看这一行的话，A6 那种「一行都没出图」和「出了图但日志没写」分不清 |
+| 6 | PNG 过 `check_screenshot.py` 的非空白阈值（唯一色 ≥64 / 亮度σ ≥3.0 / 强边缘 ≥0.001） | 「进程起来了、PNG 合法、但一个像素都没画」的空帧 | 阈值很低（这是它的设计：跨主题/字体不误报），**不判视觉正确性**，也不判元素齐全 |
+
+`--expect-refuse` 的三条（负例口径）：`via=refuse` 存在、**没有**任何 `[shot]` 出图行、目标 PNG 不存在。
+它证明「该拒绝时真拒绝了」，**不证明**「GPU 能出图」——两者互为对照，缺一个都能蒙混过关。
+
+### 3.1 判据对「行为被改坏」敏感（变异自证）
+
+`--self-test` 的向量在 `packaging/tests/gpu_shot_vectors.json`，每条的 `expect_fail` 是**期望的失败判据
+清单，逐条对**。三个变异都能被抓住（本轮 r1 又补了判据 2 的「取不到即红」）：
+
+| 变异 | 抓它的向量 | 结果 |
+|------|-----------|------|
+| `DISALLOWED_DEVICE_TYPES` 里删掉 `Cpu`（= 允许 WARP 当 GPU） | 「renderer=wgpu 但 Selected 是 Cpu」 | 由红转绿 ⇒ 清单对不上 ⇒ `--self-test` 退出 1 |
+| 删掉判据 1（不再要求 `renderer=wgpu`） | 「删掉 [shot] renderer 行」、「日志里混入第二种 renderer」 | 由红转绿 ⇒ 清单对不上 ⇒ `--self-test` 退出 1 |
+| 判据 2 不再把「取不到 device_type」当失败（恢复旧写法） | 「Selected 换成多行 Debug」、「`Selected: AdapterInfo {` 空体」 | 由红转绿 ⇒ 清单对不上 ⇒ `--self-test` 退出 1 |
+
+## 4. 这份证据**能**证明什么
+
+逐条都能指到「哪个文件 + 哪条判据过了」：
+
+1. **字形栅格与文字边缘的抗锯齿是 GPU 路径给的。** `a1-gpu-light.png` 的 1180×760 像素由 wgpu/Vulkan
+   在 RX 6600 XT 上光栅化（判据 1+2+5 全过，`Selected` 是 `DiscreteGpu`），而同一屏的 CPU 档（`a3`）
+   被同一套判据判红。⇒ 「12px 规格文本的覆盖率采样来自 MSAAx4 的那条路」这件事，是**图+日志**一起证的。
+2. **面板 α 与玻璃只有 GPU 档能出。** CPU 档在代码层就把它们强制掉了：`crates/app-iced/src/pages/
+   appearance/alpha.rs` 的 `panel_is_forced_opaque(Backend::Cpu) == true` ⇒ `effective_panel_alpha`
+   恒 1.0、`effective_glass` 恒 false。所以只要是**真的** GPU 档出的图，它拍到的面板 α/玻璃是产品
+   在 GPU 档下的真实合成结果，而不是「CPU 兜底也能喂出来」的近似。
+3. **两个后端在同一屏上的一致性是可复核的。** `--diff` 的读数（M246）：gallery `differing=51055/896800
+   (5.69%) max_delta=200 best_shift=(0,0)`、shell `19088/896800 (2.13%) max_delta=75 best_shift=(0,0)`；
+   差异 **99.3%** 落在亮度边缘上、`delta>32` 的 9301 像素连成 3002 块（最大 83 px）；两个后端各自连跑
+   两次 PNG **字节相同**（`52d4c1d6e464da16` ×2 / `10696a043bd9e7b9` ×2）。⇒ 「几何没有平移、差的是
+   边缘覆盖率」这个结论成立，5.69% 不是抖动。
+4. **`--renderer=auto` 不是「悄悄走 CPU」。** A4 的 `reason=auto-hardware-adapter` 与 `Selected:
+   DiscreteGpu` 同时成立，判据 0 退出。
+5. **断开的 RDP 会话也能出 GPU 图**（M246 的现场条件：`quser` 显示 `2 断开`）。⇒ 「断连 ⇒ GPU 截不了图」
+   这个说法不成立；成立的是 M245 §4 的「断连打折首帧耗时与整窗 α，不打折像素内容」。
+6. **「该拒绝时真拒绝」有机器判据。** A6 的 `via=refuse` + 无 PNG + 退出码 1 由 `--expect-refuse` 判 0。
+
+## 5. 这份证据**不能**证明什么（逐条，别把「没证」读成「没问题」）
+
+1. **图与日志的绑定只到「尺寸」一级。** 同一尺寸的两张正经图互换，本脚本判绿（实测：A1 日志 + A3 的
+   CPU 图 = 退出码 **0**）。要堵这个口得让产品把 PNG 的 sha256 打进日志（改 Rust，不在本 mission）。
+   ⇒ 现有用法是「一次运行、当场取日志与图」，**不是**「从一堆历史产物里随便挑两个配对」。
+2. **日志级别不够时判据 2 无从判定。** `Selected: AdapterInfo` 是 wgpu 的 info 级日志：a1b / a5 那两轮
+   没带 `ULL_GPU_LOG=info`，两份 stderr 里 `^\[gpu\]` 各 **0 条**。a1b 的「合格」来自它与 a1 **字节相同**
+   （`52d4c1d6e464da16`），**不是**来自它自己的日志 —— 所以本脚本对 a1b 判红是**如实**（这份日志单独
+   确实证不了适配器），不是误报。
+3. **首帧 / 帧率不能证。** 全部 `[perf]` 都是墙钟，且冷热差距极大（A1 首次 `probe=1281ms`、`font=749ms`；
+   后续进程 `584/587ms`、`55~57ms`）。A1 `3661ms` vs A3 `3146ms` **不能**读成「GPU 比 CPU 慢」。
+4. **整窗 α 与圆角观感不能证，任何截图都不行。** `window::screenshot` 读的是渲染目标，而整窗 α
+   （`LWA_ALPHA` 字节）与圆角（`DWMWA_WINDOW_CORNER_PREFERENCE`）由 **DWM 在合成时**施加，不在渲染
+   目标里 —— 同一份判据在 Windows 上拍到的是「DWM 之前」的像素。观感只能人眼看真显示器。
+5. **「窗口被 DWM 合成过」这件事没证。** 图是渲染目标，不是屏幕。DWM 是否真把这帧合成上屏、有没有掉帧、
+   有没有被别的窗口遮挡，这张图一概不知道。
+6. **换机器不成立。** 全部证据来自一台机器（RX 6600 XT / Raphael iGPU、12 个 adapter、RDP 断开会话）。
+   `VirtualGpu` 会不会被判成硬件只在**代码层**确认（`probe.rs:165-167` 会放行），**没在真 `VirtualGpu`
+   适配器上验过**（本机 12 条里一条都没有）。
+7. **同种 renderer 的多次运行拼在一起，无法分辨图属于哪一次。** 判据 1 只挡住「混入**异种** renderer」
+   （wgpu + tiny-skia 拼一起）；两次都是 `renderer=wgpu` 的日志 `>>` 到同一个文件时所有行都自洽，
+   判据 4 又只比尺寸 ⇒ 两张同为 1180×760 的 GPU 图互换仍然判绿。要堵它得把 PNG 的 sha256 / 运行 id
+   打进日志（改 Rust）。⇒ 一次取证 = 一份干净的 stderr，别往同一个文件里续写。
+8. **交互启动那一支没验。** A6 验的是「取证启动（`--screenshot`）下拒绝降级出图」；交互启动的
+   `via=respawn`（换进程降级）要求真窗口，本轮没开。
+9. **dark 主题、其它屏、`ULL_WINDOW_SIZE` 变尺寸、macOS / Linux** 全部没跑：只有 gallery + shell 的 light。
+
+## 6. 历史 `--diff` 基线：**永久不可复核**
+
+`DevDocs/00-债务台账-p1.md:29` 记着一条 `differing=8134/896800 (0.91%) max_delta=60 best_shift=(0,0)`，
+M246 本机实测是 **5.69% / 200**（gallery）与 **2.13% / 75**（shell）。两个数字**不可比**，原因是记录本身
+缺项：那条没有 commit、没有屏幕、对应图（`DevDocs/artifacts/m187/`）**已丢失**。
+
+⇒ 这条基线在任何将来都**无法复核**：没有图就没有分母，没有 commit 就没有树状态，重跑也只会得到新读数。
+唯一还能比的是**几何判据**（`best_shift=(0,0)`），它一致。别把 0.91% 当「回归阈值」用；本账不承认它是基线。
+
+## 7. 没验的部分（M249 自己）
+
+- **M249 当时没接进 CI**：那一轮 `.github/workflows/**` 一行未动（接 CI 是策略决定：runner 上有真 GPU，
+  还是接受「跑不起来就跳过」）。**M253 已接上**，见 §8；本节其余条目原样保留。
+- **没在任何非本机环境跑过**：Windows + 上述单卡 + RDP 断开会话之外，Linux/macOS/其它 GPU 全没跑。
+- **没改 Rust**：判据只读现有日志格式。若产品将来改了 `[shot]` / `Selected:` 的行格式，这里的正则
+  会同时失效（`--self-test` 用的是**按现格式手拼**的合成日志，抓不到格式漂移——它守判据，不守格式）。
+- **没验 `--diff` 阈值化**：本文第 4 节引的是 M246 的读数，本 mission 没有重跑 `--diff`。
+
+## 8. CI 接线（M253）：无 GPU 时显式跳过，**跳过 ≠ 通过**
+
+判据靠 **`.github/workflows/gpu-evidence.yml`** 跑（`push: main` / `pull_request` / `workflow_dispatch`，
+以及 `workflow_call`：日常线 `dev` 经 `dev-guards.yml` 复用同一份，见下）。
+**为什么新开一个文件而不是并进 `guards.yml`**：`guards.yml` 已是 399 行、红线 400（`file-size` 那道门
+就扫 `*.yml`），挂一个 job 必越线；`release-build.yml` 正好 400 行、动它得先拆。与 `release-guard.yml`
+当初单独成文的理由逐字相同。
+
+**日常线 `dev` 也跑**（M253 r1 P2-1）：`dev-guards.yml` 里多一个
+`gpu-evidence: uses: ./.github/workflows/gpu-evidence.yml`。`dev-guards.yml` 文件头自己写着
+「门禁存在但日常线上永不运行 = 空跑的门禁，长期等于没有」，而这条 workflow 原先只在 `main`/PR 触发，
+直推 `dev` 时**一次都不跑**。dev 上 `evidence` 照样显式跳过（无 GPU、无产物），所以 dev 拿到的是
+`selftest` 那一半：19 条向量 + 三个退出码 + 接线自检。**刻意不加**「只跑自测」的开关 —— 那会给这道
+门禁多开一个「可以合法关掉真判据」的旋钮。
+
+三个 job，各管一件事：
+
+| job | 什么时候跑 | 它的结论代表什么 |
+|-----|-----------|-----------------|
+| `selftest` | **无条件**（不需要 GPU、不需要真产物） | 「尺子合格」：19 条向量 + 三个退出码 0/1/2 用真 CLI 走一遍 |
+| `probe` | 无条件，只探测、不判定 | 工作区里有没有可判的产物；没有就把原因写进 job summary 并打 `::warning::` |
+| `evidence` | `if: needs.probe.outputs.available == 'true'` | 「这张图真是 GPU 档出的」：`check_gpu_shot.py` 的退出码（0 过 / 1 判据不过 / 2 用法错）即结论 |
+
+**跳过与通过分开写**：没有可用产物时 `evidence` job 的 `if:` 不成立 ⇒ 它在 Actions 里是**灰色
+skipped**，不是一个绿色 ✓；同时 `probe` 打出（本地手模拟的原样输出，见 §8.1）：
+
+```text
+GPU 证据：无硬件适配器（/dev/dri 下没有 renderD*，也没有可用的 nvidia-smi），且工作区里没有可用的样例产物
+（约定路径要求 stderr 日志与同次运行的 PNG 同时存在；DevDocs/ 被 .gitignore 忽略，图不进仓库；event=push），
+跳过真实产物判据（判据实现自测已过：那证明「尺子合格」，不证明「这张图是 GPU 出的」）
+```
+
+外加一条 `::warning::GPU 证据：跳过（…）—— 本次运行没有判过任何真实产物，不构成「GPU 证据已验证」`。
+`available` 同时作为 job output 交给 `evidence`，所以「跳过」与「通过」在数据流上也是两条路。
+
+四条路径的口径：
+
+| 情形 | 结果 | 为什么这么定 |
+|------|------|-------------|
+| 工作区里有 `DevDocs/artifacts/gpu-probe/gpu-shot.stderr.log` + `gpu-shot.png`（约定成对） | `available=true` ⇒ `evidence` 真判 | 一次取证 = 一份干净的 stderr + 同次运行的那张图（§5 第 1/7 条）；**只给一半仍按跳过**（半套产物不算可用） |
+| `workflow_dispatch` 填了 `shot_log` / `shot_png` | 同上 | 显式点名 ⇒ 真判 |
+| 点了名但**文件不存在**（或正例没给 PNG） | **红**（`::error::` + exit 1） | 「明确说要判、东西不在」若能退化成跳过，就又是一次假绿 —— 有意为之的输入缺失是错误，不是 skip |
+| 托管 runner 常态（无 GPU + 无产物） | 跳过 + 原因 + 黄条 | 见上；托管 runner 本来就没有硬件适配器 |
+
+**在 CI 里怎么让它真判**（r1 复审 P2-2：原先 §8 说的「把产物放到 `DevDocs/`」在 CI 里没人做得到 ——
+**checkout 只拿已跟踪文件**，而 `/DevDocs/` 在 `.gitignore:6` 里，也没有 `upload/download-artifact` 环节）：
+
+1. 把一次取证的那一对产物**提交进你打算 dispatch 的那个 ref**：`git add -f
+   DevDocs/artifacts/gpu-probe/gpu-shot.stderr.log DevDocs/artifacts/gpu-probe/gpu-shot.png`（`-f` 是必需的，
+   否则被 ignore）；
+2. 对该 ref 跑 `workflow_dispatch`，或干脆让它走 `push` / PR —— `probe` 会认这对约定路径，`available=true`；
+3. 不想提交到 `DevDocs/` 的话，把两个文件放到任一**已跟踪**目录，再用 dispatch 的
+   `shot_log` / `shot_png` 指过去（那两个输入只认「checkout 后确实存在的路径」）。
+
+就地往 workspace 里拷文件（不提交、靠上一步的产物）**在这个设计里做不到**：没有 artifact 传递环节。
+
+**接线自检的覆盖面**：`packaging/tests/gpu_shot_ci_selftest.py` 用 **10 条判据 + 33 条变异向量**
+（r1 复审表 20 条 + 1 条补充 + r2 复审 12 条）把上面这些口径钉住，逐条见
+`packaging/tests/gpu_shot_ci_vectors.json`：
+
+1. 五步按 `id:` 必须在场且无条件（`vectors`/`exitcodes`/`wiring`/`detect`/`judge`），`exitcodes` 还得真断言 0/1/2；
+2. 自测步必须**指向本脚本且是单条命令**（`|| echo 先忽略` 无从下手）；
+3. **解析 `if:` 表达式后求值**判「判定挂门」（`available` 取 `'true'`/`'false'`/`''` 必须真/假/假，认不出即红）；
+4. 两种调用形态都在场，且产物来自 `needs.probe.outputs.*`；
+5. **判据步真跑两次**（正例必须 0、CPU 档必须非 0，`bash -e` 与裸 bash 两种模式都跑）；
+6. 跳过路径**实跑 7 种输入**；
+7. `continue-on-error` 按 YAML 布尔语义判（`'true'` / `${{ true }}` 都算开启）；
+8. 吞码标记表（`|| true` / `; true` / `|| exit 0` / 裸 `exit 0`，兜底用）；
+9. `probe.outputs.*` 必须逐个绑到 `${{ steps.detect.outputs.* }}`；
+10. `on:` 必须同时有 `push`（含 `main`）/`pull_request`/`workflow_call`。
+
+**它不覆盖**：连判据一起改（它不自守）；`if:` 的 GitHub 语义（那是本脚本的小求值器模拟的）；真 Actions 里的
+job skip / required check 行为；判据 4 的「合法调用替换」（后果是假红不是假绿）；`exitcodes` 见证步自己的
+断言被削弱；判据 6 那 7 种输入之外的新分支。
+
+**载体依赖**：整个 `gpu-evidence.yml` 被删掉/替换后，**没有任何东西会跑这个自检** —— 守门人住在被守对象
+自己的文件里（`guards.yml` 已经 399/400 行，塞不进去）。
+
+本文件**不宣称**「不可能被改成总是绿」：r1 那一版这么写过，实测 19 条变异漏 11 条；r2 那一版
+（6 条判据）实测 40 条新变异漏 11 条。所以这里只写**能复跑的封闭清单**（10 类 / 33 条向量）。
+**这条门禁自 2026-11-11 起停止加固**：再往下是「守卫守守卫守守卫」，边际收益很低；要扩覆盖面必须由
+人类新开 mission。
+
+### 8.1 这一节**没验**的部分
+
+- **CI 上从没真跑过**：本 workflow 是本地写的，**一次 GitHub Actions 运行都没有**（未 push）。
+  本地验的是两件事，且都**已固化成每次自检都重跑的功能断言**：① `detect` 的 `run` 原文跑 7 种输入
+  （跳过 / 约定成对 / 约定半套 / dispatch 成对 / 点名不存在 / 正例缺 PNG / 负例 —— 判据 6）；
+  ② `judge` 的 `run` 原文跑两次（正例必须 0、CPU 档必须非 0，`bash -e` 与裸 bash 各跑一遍 —— 判据 5）。
+  **这不是 CI 实测**：`if:` 求值、job skip 在 UI 上的呈现、`needs` 的输出传递在真 Actions 里仍未跑过。
+- **没在真 GPU runner 上跑过**：`evidence` 的真判定只在本地用合成向量走过（0 与 1 都到达过），
+  「真产物 + 真 GPU runner」这个组合没实测。
+- **没验「跳过是否满足 required status check」**：本 workflow 没挂成必需检查；GitHub 对 skipped job
+  与 required check 的交互口径没实测，别把这一节读成「跳过也能当门过」。
+- **自检脚本自身的边界**在它自己的 docstring 里（不防「连判据一起改」；`!` 不在支持的表达式语法里，
+  出现即红；只有 `probe` 那一步是功能断言，`vectors`/`exitcodes` 两步只做结构断言）。
diff --git a/packaging/docs/linux-evidence.md b/packaging/docs/linux-evidence.md
new file mode 100644
index 0000000..78a2f23
--- /dev/null
+++ b/packaging/docs/linux-evidence.md
@@ -0,0 +1,208 @@
+# Linux 槽位的证据账（M184）
+
+本文是「Linux 到底验过什么、没验什么」的**唯一账本**。M184 把 `linux-x64` 写进了 `PUBLISH_SLOTS`（发布），
+把 `linux-arm64` 留在「构建但不发布」，两者都不是凭感觉：下面按「已有哪些证据 → 本轮补的实测 → CI 增量 →
+仍然没验的部分 → 解锁条件」逐条记账，任何一条被推翻都要回来改这里与 `compliance-support-boundaries.md` §9。
+
+## 1. M184 之前的证据盘点
+
+| 证据 | 位置 | 覆盖了什么 | 没覆盖什么 |
+|------|------|-----------|-----------|
+| xvfb 运行时冒烟（每次 PR/main） | `.github/workflows/ci.yml` 的 `runtime-smoke` | `ubuntu-latest`（x64）上装 xvfb + 软渲染依赖 + 字体，`xvfb-run … --software-renderer --screenshot` 真渲一帧，`packaging/check_screenshot.py` 对**像素本身**断言（唯一色数 / 亮度 σ / 强边缘占比），截图作为 artifact 留证 | 只有 x64；用的是 **debug** 档（`cargo build --bin unlucky-launcher-iced --locked`），不是发出去的那个 release 产物；不跑 GPU 通路；不验 Wayland；不校验 `[theme]` / `[backend] final` 日志行；没有 arm64 |
+| 本地复跑脚本（开发机） | `packaging/linux-smoke-docker.sh` | 在 `rust:1-bookworm`（**Debian 12 / glibc 2.36**）里逐步复刻上面那个 job；M131 真跑过一次（2026-11-05）：`exit=0`、截图 1180×760、`[ok] 截图非空白` | 基础镜像是 Debian 而不是 runner 的 Ubuntu；仍是 debug 档；同样没有 arm64 |
+| 编译期门禁复跑 | `packaging/linux-check-docker.sh` | 在 Linux 上跑 `clippy --workspace --all-targets -- -D warnings` 与 `test --workspace --all-targets`（M144 那两条只能在 Linux 复现的红） | 与运行时无关，只证明「编得过、测得过」 |
+| 阈值依据 | `packaging/ci-runtime-smoke.md` | 真实帧与纯色帧的实测数值（唯一色 342~2352、σ 19.45~27.46、强边缘 0.0076~0.0433）都在这里，阈值取在两者之间 | 标定样本来自 x64 软渲染 |
+| `ull --version` 冒烟 | `packaging/make_artifacts.py::smoke_version` | 槽位与宿主一致时**机制上会真跑** CLI 并断言版本串（`slot != host_slot()` 才跳过）。`linux-x64` 侧本轮**真跑过**（见 §2 `smoke: ull --version -> 0.2.3 (ok)`） | **机制存在 ≠ 有过一次运行**：截至本分支，仓库里找不到任何一次 `linux-arm64` 成功出包的记录（`git grep -rn "all_slots" DevDocs/` 零命中），所以 **arm64 侧运行时证据为零** —— 连这条 CLI 冒烟都没在 arm64 上真跑过。GUI 一帧更没有 |
+
+**glibc 地板怎么定的**：槽位表把 Linux 两档钉在 `ubuntu-22.04` / `ubuntu-22.04-arm`，**不跟 `latest` 走**
+（`release.yml` 的槽位表注释：跟 latest 走地板就会随镜像漂移）。Ubuntu 22.04 ⇒ glibc **2.35**，这就是
+`README` / §9 写的「glibc 2.35+」的来源，也是本轮真机验收为什么选 Ubuntu 22.04 的 WSL 发行版：**验证环境的地板
+与发布产物的地板一致**，在更新的发行版上验等于放宽了条件。
+
+**一处诚实记录**：M184 的任务描述里提到「曾用过 WSLg 开真窗口跑首帧」。本仓库里查不到那次留下的任何文档或
+脚本痕迹（`grep -rn WSLg` 在本轮改动之前零命中），所以下面这一节是**重新做了一遍并留证**的，不是转述。
+
+## 2. 本轮实测（WSLg 真机，linux-x64 release 产物）
+
+**环境**（2026-11-08，`wsl.exe -v` / 发行版内自报，逐字取自实测输出）：
+
+```
+Linux 6.6.114.1-microsoft-standard-WSL2 x86_64      # WSL 2.7.3.0，WSLg 1.0.73
+PRETTY_NAME="Ubuntu 22.04.5 LTS"                    # == 发布槽位 ubuntu-22.04 的同一代
+ldd (Ubuntu GLIBC 2.35-0ubuntu3.15) 2.35            # == 文档写的 glibc 2.35 地板
+DISPLAY=:0 WAYLAND_DISPLAY=wayland-0
+rustc 1.99.1 / cargo 1.99.1（rust-toolchain.toml 的 stable）
+```
+
+**构建**（与 CI 同一条命令，12 核 WSL，crates 走 rsproxy 镜像；镜像只影响下载速度，不影响产物）：
+
+```
+cargo build --release --locked --bin unlucky-launcher-iced --bin ull
+    Finished `release` profile [optimized] target(s) in 9m 38s      # BUILD_WALL=579.19s
+-rwxr-xr-x 19571328 unlucky-launcher-iced
+-rwxr-xr-x  7534848 ull
+```
+
+**打包**（CI 的同一份脚本 `packaging/make_artifacts.py`，`--slot linux-x64`）：
+
+```
+arch:     unlucky-launcher-iced -> x64 (ok for linux-x64)
+smoke:    ull --version -> 0.2.3 (ok)              # 真跑，不是跳过（宿主 == 产物）
+arch:     ull -> x64 (ok for linux-x64)
+artifact: unlucky-launcher_0.2.3_linux_x64.tar.gz  8.05 MiB  sha256=c78e9f6cbab44e0fa76912f5d3608b911d89e2de2adc473339341d8ac3b60c13
+artifact: ull_0.2.3_linux_x64  7.19 MiB  sha256=42ff569152f1af89899b0925b4a7495bfcaeb66988889a0348722aa2d6ae2369
+sums:     SHA256SUMS.txt
+```
+
+归档解开就是用户拿到的东西（`unlucky-launcher` 0755；`ELF 64-bit LSB pie executable, x86-64, stripped`）：
+
+```
+-rw-r--r-- LICENSE 11345 / NOTICE 4721 / README.md 30542
+-rwxr-xr-x unlucky-launcher 19571328
+$ ./unlucky-launcher --version
+unlucky-launcher 0.2.3（unlucky-cli）
+os: Ubuntu 22.04.5 LTS · 6.6.114.1-microsoft-standard-WSL2（x86_64）· 满足最低要求
+```
+
+**首帧（`--screenshot` 通道，真窗口在 WSLg 的真显示服务里开出来再渲）**，`exit=0`，关键日志行逐字：
+
+```
+[probe] adapters=0 hardware=false :: request=cpu -> ICED_BACKEND=tiny-skia
+[font] platform=linux text="Noto Sans CJK SC" display="Noto Sans CJK SC" mono="DejaVu Sans Mono" | … source=env cjk=not-needed
+[shot] 未指定主题，按 Light 出图（D30 可复现；CI 冒烟依赖这条默认值）
+[theme] source=default-light flavor=light follows_system=false
+[window] requested size=1180x760 min=880x560 resizable=true decorations=false transparent=false scale_requested=system size_source=default title="Unlucky Launcher"
+[boot] first frame in 485 ms（run() 开始 → 首次 view，含后端探测与字体扫描）
+[shot] 1180x760 scale=1 -> …/wslg-first-frame.png
+[shot] screen=shell theme=light renderer=tiny-skia route=Detail("survival")
+[backend] final=tiny-skia result=started elapsed=1333ms evidence=probe-single-item
+```
+
+像素判定（`packaging/check_screenshot.py --json`，图 132637 字节）：
+
+```
+{"width": 1180, "height": 760, "pixels": 896800, "unique_colors": 1858,
+ "top_color": "#f6faff", "top_color_share": 0.5564, "luma_mean": 241.18,
+ "luma_stddev": 24.06, "edge_ratio": 0.0372, "problems": []}
+[ok] 截图非空白
+```
+
+**真的开了一个窗口**（交互模式，不加 `--screenshot`）：进程 12 秒后仍存活，WSLg 侧出现
+`msrdc` 窗口 **"Unlucky Launcher (cyrene-wsl)"**，`GetWindowRect` 读回 **1180×760**（正是它请求的尺寸），
+从 Windows 侧对这块矩形截屏后**人眼可见**：自绘标题栏三键 + 左侧导航轨（Instances / Versions / Logs /
+Settings / Assistant）+ "No instance selected" 空态 + 左下 "Not signed in"。这张图已入库：
+[`docs/images/linux-x64-wslg-window.png`](../../docs/images/linux-x64-wslg-window.png)
+（1180×760，43084 字节，`check_screenshot.py`: 唯一色 871、σ 14.4、强边缘 0.0137 ⇒ 非空白 —— 比进程内那张低，
+因为桌面截屏是**已经合成到 Windows 桌面**的结果，抗锯齿被放大过一次；两张都远在阈值之上）。
+交互模式的日志另有两行值得记：
+
+```
+[probe] adapters=1 [D3D12 (AMD Radeon(TM) Graphics) [Other]] hardware=false :: request=auto -> ICED_BACKEND=tiny-skia
+[probe] 探测耗时 1527 ms（wgpu 实例 + 全后端适配器枚举）
+[boot] first frame in 2273 ms（…）
+[theme] source=system flavor=pending follows_system=true
+[theme] 系统主题 = None
+[appearance] hwnd=none（拿不到窗口句柄：整窗 α 无法下发）
+[corner] boot corner=policy=system source=square os=unknown excluded_reason=unknown-os radius=system pref=none readback=n/a window=none frame=? layered=?
+```
+
+读法（别过度解读）：① WSLg 能枚举到一个 D3D12 适配器但 `hardware=false`，所以 auto 也落到软渲染
+（`tiny-skia`）—— **GPU 通路在 Linux 上仍然没有证据**；② WSLg 没有"系统主题"，所以 `follows_system=true`
+而 `系统主题 = None`（真桌面上的系统主题跟随仍未验）；③ **整窗透明与圆角在 Linux 上本来就是 no-op**：日志自己说
+`hwnd=none`、`corner=os=unknown`（用户令：这两件事交给桌面合成器，我们不自绘）—— 所以它们不是"未验"，而是
+**在 Linux 上没有这条代码路径**。
+
+**一处 WSLg 的坑**（写在这里免得下次重复踩）：WSLg 的 X 侧只有 Weston 的代理窗口，
+`import -window root` / `xwd -root` 一律 `X_GetImage … BadMatch`，**拿不到桌面级截屏**；
+真窗口像素要么走进程内 `--screenshot`（CI 就是这么做的），要么从 Windows 侧对 `msrdc` 窗口矩形截屏（本节采用后者）。
+
+
+## 3. 本轮实测（Xvfb，同一个 release 产物）
+
+同一条命令在无头 X 里再跑一遍（Ubuntu 22.04 的 Xvfb，**release 产物**，判据与 CI 新增那步逐字一致）：
+
+```
+xvfb-run -a --server-args="-screen 0 1280x1024x24" ./unlucky-launcher --software-renderer \
+  --screenshot …/xvfb-first-frame.png --data-dir …/data-xvfb
+launcher exit=0
+[theme] source=default-light flavor=light follows_system=false
+[boot] first frame in 35 ms（run() 开始 → 首次 view，含后端探测与字体扫描）
+[shot] 1180x760 scale=1 -> …/xvfb-first-frame.png
+[backend] final=tiny-skia result=started elapsed=1147ms evidence=probe-single-item
+{"width": 1180, "height": 760, "pixels": 896800, "unique_colors": 1858, "top_color": "#f6faff",
+ "top_color_share": 0.5564, "luma_mean": 241.18, "luma_stddev": 24.06, "edge_ratio": 0.0372, "problems": []}
+[ok] 截图非空白
+```
+
+软渲染是确定性的：WSLg 与 Xvfb 两张图的统计量**逐个相同**（1858 / 24.06 / 0.0372），也正是这一点让
+`check_screenshot.py` 的阈值（唯一色 ≥64、亮度 σ ≥3.0、强边缘 ≥0.001）有 **8~37 倍**余量
+（唯一色 1858/64≈29×、强边缘 0.0372/0.001≈37×、**亮度 σ 只有 24.06/3.0≈8×** —— 与 `check_screenshot.py` 自己
+写的「阈值取在实测下限的 1/5~1/8」一致，三者里最紧的是亮度 σ）：CI 里这条门禁不会因为"某次抗锯齿抖了"而假红。
+
+本机 Docker 复跑（`packaging/linux-smoke-docker.sh`，Debian 12 容器 + **debug** 档，缓存卷是热的）：
+
+```
+$ bash packaging/linux-smoke-docker.sh . C:/Temp/ull-m184/smoke-out
+rustc 1.99.1 (58cf8f9c3 2026-10-13) / cargo 1.99.1 / 12.15      # 12.15 = Debian 版本号
+    Finished `dev` profile [unoptimized + debuginfo] target(s) in 1m 26s
+[font] platform=linux text="DejaVu Sans" display="DejaVu Sans" … source=default cjk=not-needed
+[theme] source=default-light flavor=light follows_system=false
+[boot] first frame in 69 ms（run() 开始 → 首次 view，含后端探测与字体扫描）
+[backend] final=tiny-skia result=started elapsed=1736ms evidence=probe-single-item
+exit=0
+/out/runtime-smoke.png: 1180x760 唯一色 1756 亮度σ 23.71 强边缘 0.03366 主色 #f6faff(55.7%)
+[ok] 截图非空白
+```
+
+两条差异值得写下来（说明"为什么容器绿了还不够"）：① 容器里没有中文字体，字体解析落到 `DejaVu Sans`，而 WSL 里是
+`Noto Sans CJK SC` —— **字体选择随环境变**，观感类验收只能在真桌面上做；② 基础镜像是 Debian 12（glibc 2.36），
+比发布地板 2.35 高一档，所以它能证明"这条运行时通路通"，**不能**代替 `ubuntu-22.04` 上的证据（后者见 §2/§3 前面那段）。
+
+单次启动的墙钟（`/usr/bin/time`，含 `xvfb-run` 起 X 的开销）：**WALL=1.96s**，日志里 `launch elapsed=1188ms`。
+
+
+## 4. CI 增量：2 个槽位 → 4 个槽位
+
+默认矩阵从 **2 档变 4 档**（`windows-x64` / `windows-arm64` / `linux-x64` / `linux-arm64`），多出来的两档是**并行**作业
+（`fail-fast: false`），所以：
+
+| 项 | 变化 | 依据 |
+|----|------|------|
+| 并发作业数 | 2 → 4 | `release.yml` 的 `plan` 输出（本地跑那段 python：默认 4 档、`all_slots=true` 6 档） |
+| 每档新增步骤 | `linux-x64` 多 **2 步**（xvfb 运行时冒烟 + 上传首帧图）；`linux-arm64` 多 **0 步** | `release-build.yml`：11 步 → 13 步（本地 YAML 解析计数） |
+| `linux-x64` 那 2 步的耗时 | apt 装 xvfb ≈ 30~50 s，跑一帧 ≈ 2 s，日志/像素断言 ≈ 1 s，上传 ≈ 3 s ⇒ **≈ 1~2 分钟** | 本地 Xvfb 实测单次启动 WALL=1.96s（`/usr/bin/time`） |
+| 单档 release 构建时长（**估算**） | 冷缓存 ≈ 20~30 min；`Swatinem/rust-cache` 命中后 ≈ 8~15 min | 本机 12 核实测 **9m38s**；官方 `ubuntu-22.04` runner 是 4 vCPU，编译墙钟按 2.5~3× 估，再乘缓存命中折扣 |
+| 总机时（**估算**） | 每 tag **+约 40 分钟**机时（2 档 × ≈20 min） | 同上 |
+| 墙钟（**估算**） | 增量 ≈ `max(0, linux 档时长 − 现有最慢档)`，量级 **0~10 分钟**；发布侧多两个资产，秒级 | 四档并行，墙钟由最慢那档决定 |
+| 配额风险 | `ubuntu-22.04-arm` 的可用性**本机无法核实**（无 `gh` CLI、无 Actions API 凭据） | 见 §5 最后一条：它不在发布名单里，起不来也不会挡住那两档发布 |
+
+诚实边界：单档构建时长是**估算**（本机不是 runner，核数、缓存命中率、网络都不同）。下一次 tag 的真实数字应该回来
+把这张表换成实测——**别让估算一直冒充实测**。
+
+
+## 5. 仍然没验的部分（如实划出）
+
+- **真实桌面发行版的观感**：拖动 / 缩放 / 字体度量与中文整形，一个都没在真桌面（GNOME/KDE 的可交互窗口）上
+  人眼验收过。本轮做的是「起窗 + 渲出一帧 + 断言像素与日志」，它证明「能跑出画面」，不证明「观感正确」。
+  （**整窗透明度与圆角不在这张清单里**：Linux 上它们没有代码路径 —— 见 §2 的三条读法，别把「不适用」写成「未验」。）
+- **GPU 通路**：所有 Linux 证据都是软件渲染（`--software-renderer` / tiny-skia）。wgpu→Vulkan/GL 那条路在 Linux
+  上一次都没跑过。
+- **Wayland 原生**：WSLg 同时提供 X11 与 Wayland，本轮只按 `DISPLAY` 走（见 §2 的实测环境），没单独验
+  `WAYLAND_DISPLAY` 那条路。
+- **linux-arm64 运行时完全未验**：GUI 进程在 ARM64 上一次都没启动过。连 `make_artifacts.py` 那条 `ull --version`
+  冒烟也**只是机制上会真跑**（`mode: ci` + 宿主==产物），**截至本分支没有一次 arm64 成功出包的记录**，所以 arm64
+  侧一份运行时证据都没有 —— 别把「这条冒烟以后会跑」读成「它跑过了」。
+- **`ubuntu-22.04-arm` runner 的可用性未在本机核实**：本机没有 `gh` CLI，也没有到 Actions API 的可用凭据，
+  所以「这档 runner 在这个仓库上真能起来」只能由下一次 CI 证明。风险是有界的：它**不在** `PUBLISH_SLOTS` 里，
+  起不来/红了不会挡住 `windows-x64` + `linux-x64` 的发布（只会让那一条 job 红，外加一条 `::warning::`）。
+
+## 6. `linux-arm64` 的解锁条件（写死在这里，别凭感觉放行）
+
+1. 在**真 ARM64 机器**（或原生 arm64 runner）上把 release 产物跑出一个非空白帧，`packaging/check_screenshot.py`
+   通过；
+2. 同一份日志里有 `[theme] source=…` 与 `[backend] final=… result=started` 两行（证明主题来源与渲染后端都按预期）；
+3. 把上面两条的原始输出（时间、命令、图尺寸、日志行）贴进本文 §2 的位置；
+4. 然后把 `linux-arm64` 加进 `release-publish.yml` 的 `PUBLISH_SLOTS`（一行），并同步 §9 与 `release-notes.md`。
+
+构建绿了**不算**解锁，`ull --version` 跑得过也**不算** —— 那两条只证明 CLI 与编译器，用户拿到的那个 `.tar.gz` 里
+装的是 GUI。（何况截至本分支 arm64 上连那条 CLI 冒烟都还没真跑过一次。）
diff --git a/packaging/docs/profiles-and-measurements.md b/packaging/docs/profiles-and-measurements.md
new file mode 100644
index 0000000..a4b13e6
--- /dev/null
+++ b/packaging/docs/profiles-and-measurements.md
@@ -0,0 +1,128 @@
+# Cargo 构建档位与实测数据（M145 拆自 `packaging/README.md`）
+
+本文承载原 `packaging/README.md` 的 §6、§7，**节号沿用原编号**（全仓 `packaging/README.md §N` 这类引用照旧有效，
+对照表在 [`packaging/README.md`](../README.md) 的索引里）。内容一字未改、只搬家：本行以上是 M145 新增的导航说明，
+以下逐行取自原文件。
+
+## 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.3 / §7.5 里的 `unlucky-launcher-0.1.0-windows-*.exe`（**连字符**）是 2026-11-01 那几次实测的原文，D49（2026-11-05）才改成下划线形态——同一槽位现在叫 `unlucky-launcher_0.2.3_windows_x64.exe`（规则见 §1）；拿旧名去 Release 页或磁盘上找文件必然找不到，那不代表发布挂了。
+
+### 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 槽位真跑；产物名是 D49 改名前的形态）
+
+```
+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` 与 `windows-11-arm` 两个镜像都自带 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` 在 `windows-11-arm` 上的真实链接与 ARM64 导入表、
+`linux-arm64` 在原生 arm64 runner 上的真跑（本机既没有 ARM 机器，也连 `raw.githubusercontent.com` 都解析不了）。
+**M164 的更正**：M141/M142 那个编译前体检不但没帮上忙，还是 arm64 五轮全红的唯一原因（`find` 猜 SDK 的
+`um/arm64/kernel32.lib`，猜缺就 `exit 1`，而 `cargo build` 永远 skipped）；M164 把它降级为只取证（打印 vswhere 组件、
+目录 `.lib` 计数、`link.exe` 候选），红绿交回编译器。闭环标准不是「两槽位都进 SHA256SUMS」（M142 起只有 x64 进），
+而是 arm64 的 `cargo build` 真跑绿 + 把键加回 `PUBLISH_SLOTS`（守卫会自动跟着扩，并在产物有了却没声明时报 `::warning::`）。
+本机能补的只有脚本层证据：`python packaging/check_publish_slots.py --self-test`（11 条注入回归）与
+`cargo check --target aarch64-pc-windows-msvc`（依赖图对该 target 的类型检查，**不链接、不产出 PE**）。
diff --git a/packaging/docs/runtime-deps.md b/packaging/docs/runtime-deps.md
new file mode 100644
index 0000000..e7d88cc
--- /dev/null
+++ b/packaging/docs/runtime-deps.md
@@ -0,0 +1,86 @@
+# 每平台运行时依赖与软渲染兜底（M145 拆自 `packaging/README.md`）
+
+本文承载原 `packaging/README.md` 的 §4、§5，**节号沿用原编号**（全仓 `packaging/README.md §N` 这类引用照旧有效，
+对照表在 [`packaging/README.md`](../README.md) 的索引里）。内容一字未改、只搬家：本行以上是 M145 新增的导航说明，
+以下逐行取自原文件。
+
+## 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）
+
+**本版不发布**（CI 照构建取证，红了不挡 x64 发布；等它绿了把键加回 `PUBLISH_SLOTS` 即可）。产物形态与门禁跟 x64
+一样（裸 exe + 静态 CRT + dumpbin 导入表硬门禁），差别只在**怎么编**：**M140 起在原生 `windows-11-arm` 上编**
+（GitHub 文档 2026 的 Standard runners 表明列该标签：4C/16G、公开仓库免费），产物落在 `target/release`。原路线
+是在 `windows-latest` 上交叉到 `aarch64-pc-windows-msvc`，但**CI 上从未成功过一次**（v0.2.1 首次真跑即红在
+「ARM64 工具链体检」）。M142 已确认那几轮「只剩一行 exit code 1」是**诊断脚本自己先死**（`set -uo pipefail` 关不掉
+runner 注入的 `-e`，`find` 扫不存在的根被 pipefail 判非零就退出），已修；ARM64 的静态库在这台 runner 上到底缺不缺
+要看下一次运行的新注解（固定 4 行实况清单，见 §3）。原生的附赠好处：宿主=产物架构，`ull --version` 冒烟**真跑**。
+
+运行时依赖与 x64 同表（UCRT 是 Win11 ARM 的系统组件，`+crt-static` 静态链 CRT，不需要可再发行包）。
+游戏侧如实说：**启动器原生运行**；Temurin 没有 windows-aarch64 产物，Microsoft OpenJDK 有该
+发行版（core 的 `microsoft` 源按 `-` 拼名，命名已覆盖），但 Minecraft 本体没有
+Windows ARM64 原生库（Mojang/LWJGL 只发 x64/x86），实际游玩仍走系统 x64 模拟层 + x64 JDK。
+所以本槽位只承诺「启动器产物」支持，不替 Java/游戏管理做架构级承诺。
+
+### Linux x64
+
+| 依赖 | 说明 |
+|------|------|
+| glibc ≥ 2.35 | 由 `ubuntu-22.04` 构建决定（该槽位默认不编，`all_slots=true` 取证跑才有产物）；更老的发行版请自行重建或等 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 上（默认矩阵不编它，只有 `all_slots=true` 取证跑才出产物），地板 = **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 / 老驱动 / 远程桌面）
+
+**现役入口（iced 版）**：`unlucky-launcher-iced --software-renderer`（等价 `--renderer=cpu`，即 `ICED_BACKEND=tiny-skia`）
+走 tiny-skia 光栅化，这是现役构建唯一的软渲染入口——CI 的 runtime-smoke 与 `packaging/linux-smoke-docker.sh` 都这么跑（§11）。
+
+**历史资产（`v0.1.0` 的 Slint 版）**：那批已发布二进制仍认 `unlucky-launcher --software-renderer`
+（解析在 `crates/app/src/main.rs` 的 `apply_renderer_flag()`，只认完全相等的那个串）。
+这条 Slint 路径（默认 `renderer-femtovg`/GL）已不在默认构建与发布矩阵内——`crates/app` 被 workspace `exclude`，
+源码仅作参考、不编译——所以它**对现役 `unlucky-launcher-iced` 无效**，别照抄到 iced 版上。
+
+- 软渲染是 CPU 光栅化，无 GPU 也能出图；代价是动画与大窗口重绘更慢（Metro 纯色界面影响有限）。
+- 截图通道 `--screenshot `：历史实现 `crates/app/src/screenshot.rs`，现役 `crates/app-iced/src/shot/`；
+  软渲染下照样出图，是 CI 与远程机唯一可靠的"真出图"证据（发布冒烟见 §7，本机实跑 `--software-renderer --screenshot`）。
diff --git a/packaging/docs/signing-runbook.md b/packaging/docs/signing-runbook.md
new file mode 100644
index 0000000..7203c2a
--- /dev/null
+++ b/packaging/docs/signing-runbook.md
@@ -0,0 +1,190 @@
+# 签名就绪度操作手册（M255）
+
+本文件是**人类照做**的手册：从「信任表是空的」走到「发出去的 Release 用客户端判据能验过」。
+背景/威胁模型/轮换纪律在 [`signing.md`](signing.md)；本文件只讲**步骤、命令、坑**。
+
+> ⚠ 本文件**不含**任何真实私钥、种子或公钥。所有示例都是 `<尖括号占位符>`。
+> `--generate-key` 的输出是**敏感物**：只在你要贴进 Secret 的那一次运行里存在，别存文件、别贴 issue。
+
+## 0. 现状读一遍（2026-11 的 M254 审计结论）
+
+`crates/core/src/update/trust.rs` 的 `PRODUCTION` 表在 `PINNED-KEYS` 标记之间是**空的**。空表 =
+`KeyringEmpty` 一律拒装 ⇒ **今天任何正式二进制都验不过任何清单**（fail-closed 成立，但用户端表现为
+「更新永远失败」）。已存在的部分（都能用）：
+
+| 环节 | 在哪 | 今天的状态 |
+|---|---|---|
+| 生成钥 | `sign_manifest.py --generate-key` | 有；打印 Secret JSON + `PinnedKey` 那一行 |
+| 钥 ↔ 信任表对账 | `sign_manifest.py --check-pinned-keyring` | 有；**今天必然红**（表空 ⇒ 「信任表是空的」） |
+| 签名 | `sign_manifest.py --sign dist/manifest.json` → `.sig` | 有；**今天必然红**（`ULL_MANIFEST_SIGNING_KEY` 没有，前面先红） |
+| 回验 | `sign_manifest.py --verify-pinned dist/manifest.json` | 有；**今天必然红**（表空 ⇒ 「无从回验」） |
+| 发布接线 | `release-publish.yml` 的「签更新清单」步 | 有；上面四条任一非零 ⇒ 不出 Release（**这是对的**） |
+| 资产上传 | `release-publish.yml` 的 `assets=(… manifest.json manifest.json.sig …)` | 有 |
+| **操作步骤与可见性** | 本文件 + `packaging/check_signing_ready.py` + `signing-status.yml` | **本次补上的就是这两样** |
+
+一句话：**工具链不缺，缺的是有人把钥钉进表里。** 那件事只有人类能做（塔不会自己生成生产私钥）。
+
+## 1. 先看读数（不用碰任何钥）
+
+```bash
+python3 packaging/check_signing_ready.py          # 三行读数 + 退出码
+python3 packaging/check_signing_ready.py --dist dist   # 顺手看一眼本地留档
+```
+
+三行分别是 ① `PRODUCTION` 表空不空 ② 环境里有没有签名钥（并顺手对账「这把钥在不在表里」）
+③ 最近一次发布的 `.sig`/清单痕迹（取不到就写「未知」——本地没留档 ≠ 上次没签）。
+
+退出码：`0` 就绪 / `1` 未就绪 / `2` 用法错（参数写错、`trust.rs` 读不到、标记丢了）。
+**未就绪时会打印一行修复命令**，直接照抄即可。CI 里同一条读数在 `Signing status（播报）` workflow 的
+job summary 里（见 §6 —— 它是播报，不是门禁）。
+
+## 2. 人类要亲手做的 5 步（下单清单）
+
+下面每一行都只有命令与占位符，**没有任何密钥值**。做完一步就把该步的验证跑一遍。
+
+> 🔴 **顺序硬要求（M255 r1 P2-1）：先合并「播报 workflow 的 ref 门」那笔改动，再录 Secret。**
+> 播报 workflow（`.github/workflows/signing-status.yml`）会把 `ULL_MANIFEST_SIGNING_KEY` 注入到
+> 就绪度那一步的环境里；那个注入**只在 `refs/heads/main` 上发生**，而且该 workflow **没有**
+> `pull_request` 触发。这两条是安全边界：仓库内分支的 PR 与任意分支的 `workflow_dispatch` 都拿得到
+> 仓库 Secret，而 CI 会在**那个 PR 自己的代码**上执行 checker —— 种子一旦进过那种运行，等于交给
+> 任何能推分支的人（这把种子能给**全量已安装客户端**签可信清单，即用户端 RCE）。
+> 所以：**ref 门那笔没合进去之前不要录 Secret**；录之前先确认线上版本里有
+> `github.ref == 'refs/heads/main'` 这个条件式（§6 也写了这条）。
+
+```bash
+# ① 生成钥（⚠ 输出是敏感物；不要跑在 CI 里，不要重定向到仓库里的文件）
+python3 packaging/sign_manifest.py --generate-key --key-id 
+
+# ② 把打印出来的那一行 JSON（{"key_id": …, "seed_hex": …}）贴进仓库 Secret（⚠ 先读上面的顺序硬要求）：
+#    Settings → Secrets and variables → Actions → New repository secret
+#    名字必须**逐字**是：ULL_MANIFEST_SIGNING_KEY
+#    （等价 CLI：gh secret set ULL_MANIFEST_SIGNING_KEY，然后按提示粘贴，别用 -b 把值留在 shell 历史里）
+
+# ③ 把打印出来的那一行 PinnedKey { … } 贴进 trust.rs 的 PINNED-KEYS 标记之间（标记本身别动）
+grep -n 'PINNED-KEYS' crates/core/src/update/trust.rs
+#    贴完提交这次改动 —— 公钥进 git 是对的：它是信任锚，本来就该公开可审计
+
+# ④ 对账（需要一个有钥的环境：本机就先 export，别写进任何文件）
+python3 packaging/sign_manifest.py --check-pinned-keyring     # 期望：ok: 签名钥  已被钉住
+
+# ⑤ 发一次带 .sig 的 Release，然后用**客户端的判据**回验（这一步不需要私钥）
+python3 packaging/sign_manifest.py --verify-pinned dist/manifest.json   # 期望：ok: 用钉住的公钥能验过
+```
+
+`--verify-pinned` 才是证据：`--sign` 说「签好了」不算 —— 客户端拿的是 `trust.rs` 里那把公钥。
+发布后建议再用**下载下来的资产**验一次（§5），因为「CI 上能验过」不等于「上传的那份就是被签的那份」。
+
+### 每一步的判据（怎么知道这步真的成了）
+
+| 步 | 成功长什么样 | 失败长什么样 |
+|---|---|---|
+| ① | 打印 ① 私钥 JSON、② 一行 `PinnedKey`、③ 公钥十六进制；脚本自带「自己签自己验」自检 | `error: 自己签自己验不过` ⇒ 不要用这把钥，环境有问题 |
+| ② | `gh secret list` 里能看到 `ULL_MANIFEST_SIGNING_KEY` | 列表里没有 / 名字拼错（大小写、下划线） |
+| ③ | `check_signing_ready.py` 的 ① 从「未就绪」翻成「就绪」 | ① 仍说 0 条 ⇒ 贴到了标记**外面**（读数里会点名「另有 N 条在标记之外（key_id：…）」） |
+| ④ | `ok: 签名钥 … 已被钉住` | `签名钥（…）不在信任表里` ⇒ ②③ 不是同一把钥 |
+| ⑤ | `ok: manifest.json.sig 用钉住的公钥 … 能验过（客户端会接受）` | `拿 trust.rs 里钉住的公钥回验不过 —— 这份 Release 的用户会全部拒装。别发版` |
+
+## 3. 一次发布里签名是怎么被执行的（不用额外操作）
+
+`release-publish.yml` 的「签更新清单」步按顺序跑四条，任一非零 ⇒ 本步红 ⇒ 不出 Release：
+
+```bash
+sign_manifest.py --self-test                    # RFC 8032 向量：脚本自己没坏
+sign_manifest.py --check-pinned-keyring         # Secret 里的钥必须已在 trust.rs 钉住
+sign_manifest.py --sign dist/manifest.json      # 产出 dist/manifest.json.sig
+sign_manifest.py --verify-pinned dist/manifest.json  # 用钉住的公钥回验产出
+```
+
+这一步已经把「未配置 Secret」「钥没钉」「钥不匹配」都变成**发版前的红**，所以「发了但没签名」这条
+不会发生 —— 它只会在发布 job 上红，不会静默发出去。
+
+## 4. 已知坑（按踩到的概率排序）
+
+1. **Secret 名字拼错**（`ULL_MANIFEST_...` vs `ULL_MANIFEST_KEY`）：可复用工作流只拿得到自己**声明过**的
+   secret，名字不对就是空串 ⇒ 签名步红，而错误文案会反过来指控「Secret 没配」。`release-publish.yml`
+   已经声明了这一个（`required: false`，缺省走 fail-closed），照抄名字即可。
+2. **只配 Secret 没钉表**：`--check-pinned-keyring` 报「信任表是空的（fail-closed）」，并**直接打印**
+   该贴的那一行 `PinnedKey`（只含公钥，安全）。照贴即可。
+3. **只钉表没配 Secret**：`--check-pinned-keyring` 报「没有签名密钥」。这不影响已有用户（表非空 ⇒
+   他们能验签），但发不了新版。
+4. **Secret 与 trust.rs 是两把不同的钥**：最常见于「换过钥但只更新了一边」。判据是**公钥字节**，
+   `key_id` 只是标签；`--check-pinned-keyring` 会把两边的公钥都打出来对账。
+5. **把条目贴到标记外面**（`];` 之后、或贴着别的 `const`）：等于没钉。`check_signing_ready.py` 会**点名**
+   标记之外的 `key_id`；注意本仓 `TEST_ONLY` 那条**本来就在标记之外**（那是它的正确位置），所以读数是
+   「另有 N 条在标记之外（key_id：…）」而不是「贴错了」—— 对着 `key_id` 自己认。
+6. **`set -x` / `echo $ULL_MANIFEST_SIGNING_KEY`**：一次就够把私钥泄进日志。工作流里那一步显式 `set +x`
+   且只回显**公钥**；本机调试同理，别开 trace。
+7. **`--generate-key` 的输出落进文件/issue/聊天**：当成泄露处理，走 `signing.md` §5 轮换（旧钥签新钥）。
+8. **以为「非 main 分支的读数」就是仓库状态**：播报 workflow **只在 `refs/heads/main` 上注入** Secret
+   （也没有 `pull_request` 触发 —— 见 §2 的顺序硬要求与 §6）。非 main ref 的运行里 ② 显示
+   「**未判定** —— 非 main ref（按设计不注入 Secret）」，这是**策略**，不是「没配」。以 `main` 上的读数为准。
+9. **`.sig` 没上传到 Release**（手改过 `assets=(…)` 那一行）：客户端取 `<产物根>/manifest.json.sig`
+   会 404 ⇒ 所有人验签失败。上传后请在资产列表里**亲眼看到** `manifest.json` 与 `manifest.json.sig`
+   两个名字（§5 的 `gh release view` 那条命令就是干这个的）。
+10. **删掉旧钥条目太早**：用户机器上装着旧二进制，它只认旧钥；删条目的那个版本必须**只**由新钥签，
+    并且至少一个发布周期的双签名之后（`signing.md` §5）。
+11. **「昨天验过」不等于「今天验得过」**：`PRODUCTION` 是**编译期**常量，改 `trust.rs` 只影响**下一次构建**。
+    已在用户盘上的旧二进制永远用旧表 —— 这是设计，不是 bug。
+12. **给播报 workflow 加回 `pull_request` 触发、或去掉注入行的 ref 门**：等于把生产签名种子交给任意推
+    分支的人的代码（自更新链 = 用户端 RCE）。这两处各有接线用例钉着（去掉任一处都会红），
+    别为了「PR 上也能看读数」去动它 —— 看读数请对 `main` 跑，或读 §1 在本地跑。
+
+## 5. 发布后回验（发布侧，不需要私钥）
+
+```bash
+# 资产里必须两个名字都在（漏一个等于全员验签失败）
+gh release view  --json assets --jq '.assets[].name' | grep -E 'manifest\.json(\.sig)?$'
+
+# 拿下载回来的真实资产复现客户端判据：manifest.json 与 .sig 必须成对、且是同一份字节
+mkdir -p /tmp/verify && gh release download  --pattern 'manifest.json*' --dir /tmp/verify
+python3 packaging/sign_manifest.py --verify-pinned /tmp/verify/manifest.json
+```
+
+退出码 0 = 「客户端会接受这份清单」。非零时**不要**手动 `edit` Release 绕过 —— 先看脚本 stderr
+（它会说清楚是表空、无 `.sig`、还是签名对不上）。
+
+## 6. CI 里那条读数：`Signing status（播报）`
+
+`.github/workflows/signing-status.yml` 在 `push: branches: [main]` 与**手动 dispatch** 上跑，把 §1 的三行
+搬进 job summary。**它不是门禁**：
+
+* 它**不应被设为 required check**（分支保护里不要勾它），也不阻断任何其它 job；
+* 它就绪度那一步**恒 `exit 0`**：未就绪用 `::warning::` 播报，不用 error 级注解（那会让人以为构建挂了）；
+* **生产签名种子只在 `refs/heads/main` 上注入**（`github.ref == 'refs/heads/main' && secrets.… || ''`），
+  而且**没有 `pull_request` 触发**。理由是安全：仓库内分支的 PR / 任意分支的 dispatch 都拿得到仓库 Secret，
+  而 CI 跑的是那个 ref 自己的代码 —— 种子进过那种运行就等于交给任何能推分支的人。
+  非 main ref 的运行里 ② 显示「**未判定** —— 非 main ref（按设计不注入）」，**不写「没配」**；
+* 它**刻意不声明 `workflow_call:`**，所以别的 workflow 没法 `uses:` 它；接线自检还会扫全部 workflow，
+  任何 `uses: …/signing-status.yml` 出现即红（防的是「顺手接进 dev 线把播报变成门禁」）；
+* 它**绿**只说明脚本跑完了；结论只看 summary 里的三行字。
+* 同一 workflow 里另有两步跑自测（`packaging/tests/signing_ready_selftest.py` +
+  `packaging/tests/signing_ready_wiring_selftest.py`）：那两步**会红**，红 = **尺子坏了**（三行读数/退出码/
+  变异重放/接线与 ref 门之一没过），与「签名未就绪」是两件不同的事，措辞在 summary 里分开写。
+
+为什么不做成门禁：今天已经有四次「守卫假绿」的账（见 `packaging/README.md` §12 里那几条先例）。
+把一条**按定义今天必然失败**的检查做成 required，只会有两种结局 —— 要么所有人学会忽略红叉，
+要么有人把它改成永远绿。真正的红留在 `release-publish.yml` 的签名步：那里今天红是**对的**，
+因为签不出来的产物本来就不能发。
+
+## 7. 本手册**没**覆盖 / 没验的部分（明账）
+
+* **Authenticode / SmartScreen**：项目自有签名解决的是「这条自更新链是不是我们发的」，用户双击 exe 看到
+  的「未知发布者」与此无关（`signing.md` §0）。
+* **托管签名**（如 SignPath）：只是后续可替换路径，本手册与判据都不依赖它。
+* **本文档里的命令没有被真跑过一遍**：`--generate-key` 会产出生产私钥，塔不生成、也不跑它；
+  ②③ 两步要动 GitHub Secret 与 Rust 常量，同理。所以本手册是「按现有脚本的接口写的步骤」，
+  首次执行时**以脚本的实际输出为准**，跑完请回来修正本文档。
+* **「用户机器上真的更新成功」**没有在本条里验：需要一次真 Release + 一台装着旧版本的机器。
+* **ref 门只在本地验证过**（抽 `run:` 块用 Git Bash 跑 + 接线用例的文本变异），没有在真 Actions 上看过
+  `secrets` 的求值结果 —— 第一次真跑请确认非 main ref 的 ② 显示「未判定」。
+
+## 8. 相关文件
+
+| 文件 | 作用 |
+|---|---|
+| `packaging/check_signing_ready.py` | 三行就绪度 + `0/1/2` 退出码（只读、零第三方依赖） |
+| `packaging/tests/signing_ready_selftest.py` | 判据自测：三行/退出码/两向变异重放/`--key` 用法错/指针章节 |
+| `packaging/tests/signing_ready_wiring_selftest.py` | 接线自测：不是门禁 / 不被 `uses:` / **ref 门** / 文档路径存在性 + 三处变异 |
+| `.github/workflows/signing-status.yml` | 把三行搬进 job summary 的**播报** workflow（不是门禁；种子只在 main 注入） |
+| `packaging/docs/signing.md` | 为什么签名、威胁模型、轮换纪律、四条发布侧命令的红法对照表 |
+| `packaging/sign_manifest.py` | 生成钥 / 签名 / 对账 / 回验的唯一实现（`--self-test` 跑 RFC 8032 向量） |
diff --git a/packaging/docs/signing.md b/packaging/docs/signing.md
new file mode 100644
index 0000000..9e24790
--- /dev/null
+++ b/packaging/docs/signing.md
@@ -0,0 +1,160 @@
+# 产物签名与更新验签（M190）
+
+本文件是**发布侧手册**：私钥从哪来、怎么用、怎么轮换、哪一步失败必须让发布变红。
+用户面的说明（README 里「为什么第一个包要手动下」那类话）不在本文件范围。
+
+> **M255 补充：要照做的那几步在 [`signing-runbook.md`](signing-runbook.md)** —— 生成钥 → 私钥进 GitHub
+> Secret（名字逐字是 `ULL_MANIFEST_SIGNING_KEY`）→ `PinnedKey` 贴进 `trust.rs` 标记之间 → 发一次带 `.sig`
+> 的 Release → 用 `--verify-pinned` 回验 → 已知坑。本文件讲**为什么**，那份讲**怎么做**。
+> 现状读数用 `python3 packaging/check_signing_ready.py`（三行 + `0/1/2`；未就绪时会打印一行修复命令）；
+> CI 里同一条读数挂在 `.github/workflows/signing-status.yml` 的 job summary 上 —— **那是播报，不是门禁**。
+
+## 0. 先说清这件事**不**解决什么
+
+| 有 / 没有 | 状态 |
+|---|---|
+| 更新器验「清单是不是我们发的」 | **有**（Ed25519 清单签名 + 二进制里钉住的公钥） |
+| Windows 上「未知发布者」提示消失 | **没有**。项目自有签名与 Authenticode 是两件事 |
+| SmartScreen 信誉 | **没有**。只有买了 OV/EV 证书并真签名才可能逐步积累 |
+
+> 一句话：**项目自有签名保护的是自更新这条链，不是 Windows 的信任判断。** 用户双击 exe 时看到的
+> 「未知发布者」来自 SmartScreen，与本文件的方案无关；买证书是另一条线（见 M190 报告里的
+> 「后续要用户拍板的两件事」）。
+
+## 1. 威胁模型（为什么要签名）
+
+清单里的 `sha256` 只保证「包体与清单对得上」。**能改 Release 的人可以同时改包和摘要**，所以摘要
+本身不是信任根。签名的对象因此是**清单文件的原始字节**：改了任意一个字段（哪怕只改版本号里一个数字），
+签名立刻对不上。
+
+```
+发布侧                                   用户机器
+------                                   --------
+manifest.json（字节）──签名──> manifest.json.sig
+       │                                   │
+       └── 挂到同一个 Release ─────────────┤
+                                           ├─ 取清单 + .sig
+                                           ├─ 用**编译进二进制**的公钥验签（trust.rs）
+                                           ├─ 过了 → 再解析、再比 sha256、再装
+                                           └─ 不过 → 五类签名错误，**什么都不会被安装**
+```
+
+## 2. 信任根在哪：`crates/core/src/update/trust.rs`
+
+* 公钥是**编译期常量数组**（`PRODUCTION`），不是用户机器上的文件 —— 没有环境变量、没有设置键、
+  没有「清单旁边的 keyring.json」这类运行期口子（`tests/signature_cases.rs::no_runtime_keyring_override`
+  守着这条）。
+* 是**数组**而不是一把：换签名方时新旧钥可以并存（见 §5）。
+* `key_id` 只是查表标签，**判据永远是公钥字节**：把 `key_id` 伪造成钉住的那个也过不了
+  （`key_id_spoofing_does_not_help`）。
+
+### 空表 = fail-closed
+
+正式表当前**是空的**：私钥只能来自仓库 Secret，任何代码仓库都不该自己生成并落盘私钥。
+空表的效果是「任何正式构建都拒装任何清单」，同时 `--check-pinned-keyring` 让发布流水线当场红。
+**这是有意的**：宁可不出 Release，也不出未签名的 Release。
+
+## 3. 一次性录入（只做一次）
+
+```bash
+# ① 生成：打印一段 Secret JSON + 一行可以直接贴进 trust.rs 的 PinnedKey
+python3 packaging/sign_manifest.py --generate-key --key-id ull-release-2026a
+```
+
+* 打印出来的 **第一行 JSON**（含 `seed_hex`）= 私钥，**只**贴进仓库 Secret：
+  Settings → Secrets and variables → Actions → New repository secret，名字
+  **`ULL_MANIFEST_SIGNING_KEY`**。
+* 打印出来的 **`PinnedKey { … }` 那一行**贴进 `crates/core/src/update/trust.rs` 的
+  `>>> PINNED-KEYS >>>` 与 `<<< PINNED-KEYS <<<` 标记之间（标记本身不要动，脚本按它解析）。
+* 提交这次改动（公钥进 git 是对的：它是信任锚，本来就该公开可审计）。
+
+### 私钥纪律（违反任何一条都算事故）
+
+1. **只**存在于仓库 Secret `ULL_MANIFEST_SIGNING_KEY`。本地需要签测试产物时，走 `--key <文件>`
+   并把那个文件放在**仓库外**（gitignore 不保险，别放仓库里）。
+2. **不得**出现在日志、产物、提交、issue、聊天记录里。CI 里任何 `echo`/`cat`/`set -x` 都不许碰到它
+   （工作流里的签名步骤显式 `set +x` 且只回显**公钥**）。
+3. 一旦怀疑泄露：立即按 §5 轮换，并在下一个 Release 的说明里点名旧 `key_id` 作废。
+4. 私钥文件/Secret 的备份不归仓库管；**丢了 = 旧钥作废**，用户机器上的旧二进制只能靠
+   「先手动装一次新版本」恢复（`trust.rs` 里的旧条目那时才可以删）。
+
+## 4. 发布时发生什么（`.github/workflows/release-publish.yml`）
+
+在 `manifest.json` 生成之后、`gh release create/upload` 之前，多了一步：
+
+```bash
+python3 packaging/sign_manifest.py --self-test                     # ① RFC 8032 向量自检
+python3 packaging/sign_manifest.py --check-pinned-keyring          # ② 密钥 ↔ trust.rs 必须对得上
+python3 packaging/sign_manifest.py --sign dist/manifest.json       # ③ 产出 dist/manifest.json.sig
+python3 packaging/sign_manifest.py --verify-pinned dist/manifest.json  # ④ 用钉住的公钥回验产出
+```
+
+第 ④ 步复现「客户端会怎么判」：它**不碰私钥**，只拿 `trust.rs` 里那把公钥去验刚落盘的 `.sig`。
+因此「签名脚本自己说签好了」不构成证据，证据是「按客户端的判据能验过」。
+
+四条命令任何一条非零退出 ⇒ **这一步红 ⇒ 整个 Release job 红 ⇒ 本次不出 Release**。常见红法：
+
+| 现象 | 原因 | 怎么补 |
+|---|---|---|
+| `没有签名密钥` | Secret `ULL_MANIFEST_SIGNING_KEY` 没配 / 名字拼错 | 按 §3 录入 |
+| `信任表是空的` | `trust.rs` 里还没钉任何公钥 | 把 §3 打印的 `PinnedKey` 那行贴进标记之间 |
+| `签名钥（…）不在信任表里` | Secret 与 `trust.rs` 是**两把不同的钥** | 用同一把钥重跑 §3，或回滚 `trust.rs` 的改动 |
+| `签出来的签名自己验不过` | 实现/环境异常 | 不要发布；把 `--self-test` 输出贴进 issue |
+
+`dist/manifest.json.sig` 与 `dist/manifest.json` 一起作为 Release 资产上传（`assets=(...)` 那一行）。
+
+## 5. 轮换（换钥 / 旧钥泄露 / 接托管签名）
+
+**纪律：旧钥签新钥。** 不允许在没有旧钥签名的情况下替换信任表 —— 那等于让「能改仓库的人」变成
+「能改信任根的人」。
+
+1. 生成新钥（§3），得到 `key_id = ull-release-2027a`。
+2. `trust.rs` 里**保留**旧条目、**追加**新条目（数组顺序无关；`key_id` 不能重名）。
+3. 在一次发布里，让清单**同时带两把钥的签名**（两条 `signatures`，客户端「任意一条通过即放行」）：
+   用旧钥签一次、新钥签一次，把两个信封的 `signatures` 数组拼起来放进 `manifest.json.sig`。
+   这一步让「装着旧二进制的用户」和「装着新二进制的用户」都过得去。
+4. 之后至少**一个完整发布周期**保持双签名，再观察下载/更新失败率。
+5. 确认新钥已被广泛接受后，用新钥单独签发下一次清单，并从 `trust.rs` 删掉旧条目
+   （删条目的那个版本必须**只**由新钥签）。
+6. changelog 里点名：新增/作废的 `key_id` 与公钥指纹。
+
+托管签名（例如 SignPath Foundation）作为**后续可替换路径**：它的产物签名由 CI 侧调用其服务完成，
+`trust.rs` 的数组形状不用变（多一条 `PinnedKey` 即可）；清单签名这一层保持本项目自有钥不动。
+**不允许**为了接托管签名把判据改成「只认证书」。
+
+## 6. 三条守门（都能单独变红）
+
+| 守门 | 脚本 / 用例 | 变红意味着 |
+|---|---|---|
+| 版本资源真的在产物里 | `packaging/check_pe_version.py  --expect-version <版本>` | 读回产物字节找不到 `VS_VERSIONINFO` / 字段值不对（构建日志绿也没用） |
+| 篡改清单 ⇒ 验签失败且不安装 | `cargo test -p unlucky-core --lib update::tests::signature_cases` | 改字段/只改签名/漏签名/陌生钥 任一仍能装 |
+| 签名失败阻断发布 | `release-publish.yml` 的签名步 + `--check-pinned-keyring` | 没钥/钥没钉/钥不匹配时仍发出 Release |
+
+另外 CI 的构建槽位会跑 `check_pe_version.py`（`release-build.yml`）：Windows 槽位上直接读
+`target/release/unlucky-launcher-iced.exe` 与 `ull.exe` 的字节，断言 `CompanyName` 等字符串在。
+
+## 7. 实现分工（M190 r1 复审后）
+
+| 哪一半 | 在哪 | 用什么 |
+|---|---|---|
+| **验签**（进二进制） | `crates/core/src/update/ed25519.rs` | `ed25519-dalek::verify_strict`（在非 strict 的基础上额外拒**小阶公钥**与**小阶 `R`**；`S` 规范性是非 strict 的 `verify` 也查的） |
+| **签名**（只在发布侧） | `packaging/ed25519_ref.py` + `packaging/sign_manifest.py` | 纯 Python 参考实现，零第三方依赖（CI 不装 pip 包） |
+
+两套实现互相独立，`--self-test` 用 RFC 8032 §7.1 的同一组向量把两边各自钉住。**第一版曾把验签写成
+仓内自写**（5x51 素域 + 扩展坐标）；r1 复审裁定不安全——信任锚的微妙错误后果是「验签通过但本不该通过」，
+因此整段删除，改为官方实现。`crates/core/src/update/tests/ed25519_cases.rs` 现在钉的是
+**dalek 的 strict 语义**：谁把 `verify_strict` 换成 `verify`，`small_order_public_key_is_rejected` 与
+`small_order_r_is_rejected_only_by_strict` 会红（这是 r2 实测的结论——其余几条拒绝类用例在非 strict
+下仍绿，别把它们当 strict 的守卫）。
+
+## 8. 本地自测（不需要私钥）
+
+```bash
+python3 packaging/sign_manifest.py --self-test          # RFC 8032 向量 + 标记解析
+python3 packaging/check_pe_version.py --self-test       # 口径表与 pe_version.rs 对拍
+cargo test -p unlucky-core --lib update::tests::signature_cases
+cargo test -p unlucky-core --lib update::tests::ed25519_cases
+```
+
+带 `update-test-source` 的验收构建里另有一把**公开的测试钥**（种子写在测试夹具里）：它只用于
+「本地目录源 + 真二进制」的端到端验收，**不在**正式信任表里，签不出任何正式版本能装的清单。
diff --git a/packaging/docs/termux-glibc-build.md b/packaging/docs/termux-glibc-build.md
new file mode 100644
index 0000000..5860174
--- /dev/null
+++ b/packaging/docs/termux-glibc-build.md
@@ -0,0 +1,279 @@
+# Termux + termux-x11 上的 glibc 构建（试验级）
+
+本页记录**在 Termux 里构建 glibc 版 GUI，并在 termux-x11 里跑起来**的可复现步骤。
+2026-11-06 在一台 OnePlus 15（Android 17、Termux、KirinSU/root 环境）上实测通过：
+`--software-renderer --screenshot` 出 1180×760 PNG，中文正常，`msa client_id=configured source=build`。
+
+**定位**：试验级、不承诺。发布矩阵里没有面向 Termux 的资产；本文只描述源码自建路径。
+GUI 只在上述设备 + CPU 渲染（tiny-skia）上验证过，GPU 路径见 §5（尚未在 glibc 侧验证）。
+
+## 1. 为什么不能直接 `cargo build`
+
+Termux 的 `rustc` host 是 `aarch64-linux-android`（`target_os = "android"`）：
+
+- `crates/app-iced/Cargo.toml` 的 `x11` / `wayland` feature 只挂在 `cfg(target_os = "linux")` 下；
+- iced 的窗口层 winit 0.30 在 android target 上走 Android（NativeActivity）后端，
+  会拉 `android-activity` 并要求 `game-activity`/`native-activity` feature，普通进程编不过也跑不了。
+
+所以要在 Termux 里产出一个 **`aarch64-unknown-linux-gnu`（glibc）** 二进制，靠 Termux 的
+[glibc 运行时](https://packages.termux.dev/apt/termux-glibc/) 原生执行。
+
+## 2. 工具链（一次性）
+
+以下路径用变量表示，实际可放在任意本地目录（示例放在仓库内的 `.gnu/`，已 gitignore）：
+
+```sh
+PREFIX="${PREFIX:-/data/data/com.termux/files/usr}"
+G="$PWD/.gnu"
+```
+
+### 2.1 glibc 运行时
+
+确认 `$PREFIX/glibc/lib/ld-linux-aarch64.so.1` 存在（`pkg install glibc-runner` 或装过 glibc 仓库
+的包即可）。**不需要 `gcc-glibc`**：链接用 Termux 自带的 clang + lld，glibc 的 CRT/头文件由
+`glibc` 包提供。
+
+### 2.2 Rust gnu 工具链
+
+下载 Rust 1.99.1（或与 `rust-version` 兼容的 stable）的 `rustc` / `rust-std` / `cargo`，
+以及跑门禁需要的 `clippy` / `rustfmt` 五个 `aarch64-unknown-linux-gnu` 组件。官方源在国内很慢，
+用 USTC 镜像：
+
+```sh
+mkdir -p "$TMPDIR/ull-gnu" && cd "$TMPDIR/ull-gnu"
+for c in rustc rust-std cargo clippy rustfmt; do
+  curl -fLO "https://mirrors.ustc.edu.cn/rust-static/dist/$c-1.99.1-aarch64-unknown-linux-gnu.tar.xz"
+done
+```
+
+解包后按组件布局合并到 `$G/toolchain`（`rustc/bin`、`cargo/bin` → `toolchain/bin`，
+两者的 `lib/` → `toolchain/lib`，`rust-std-*/lib/rustlib/aarch64-unknown-linux-gnu` →
+`toolchain/lib/rustlib/`）。
+
+### 2.3 改 interpreter / rpath
+
+工具链里的 `rustc`、`cargo`、`rustdoc` 是 glibc ELF，默认 interpreter 是 `/lib/ld-linux-*.so.1`，
+在 Termux 上不存在：
+
+```sh
+LD="$PREFIX/glibc/lib/ld-linux-aarch64.so.1"
+for f in rustc cargo rustdoc clippy-driver cargo-clippy rustfmt cargo-fmt; do
+  patchelf --set-interpreter "$LD" --set-rpath "$PREFIX/glibc/lib:$G/toolchain/lib" \
+    "$G/toolchain/bin/$f"
+done
+```
+
+> **坑（实测）**：`cargo clippy` 会在 PATH 里找 `cargo-clippy`。如果只装了 Termux 的 Rust，
+> 找到的是 android 版 `cargo-clippy`，`aws-lc-sys` 等构建脚本会被当成
+> `--target=aarch64-linux-android` 编译并失败。把 gnu 工具链的 `bin` 放在 PATH 最前面即可；
+> `rustc`/`rustfmt` 同理。
+
+### 2.4 gcc 运行时片段
+
+`clang -fuse-ld=lld` 仍然需要 `crtbeginS.o` / `crtendS.o` / `libgcc.a`。从 Debian 的
+`libgcc-14-dev`（arm64）取即可（只解包，不安装）：
+
+```sh
+curl -fLO https://deb.debian.org/debian/pool/main/g/gcc-14/libgcc-14-dev_14.2.0-19_arm64.deb
+dpkg-deb -x libgcc-14-dev_14.2.0-19_arm64.deb "$G/gnu-support"
+# crt/libgcc 在 $G/gnu-support/usr/lib/gcc/aarch64-linux-gnu/14/
+```
+
+### 2.5 linker 驱动
+
+写一个 `$G/bin/cc-glibc`（`chmod +x`）：
+
+```sh
+#!/data/data/com.termux/files/usr/bin/sh
+unset LD_PRELOAD
+P=$PREFIX
+S="<仓库>/.gnu/gnu-support/usr/lib/gcc/aarch64-linux-gnu/14"
+C="clang --target=aarch64-unknown-linux-gnu --sysroot=/ -isystem $P/glibc/include \
+   -B$P/glibc/lib -B$S -L$S -L$P/glibc/lib -fuse-ld=lld"
+for a in "$@"; do
+  case "$a" in -c|-E|-S) exec $C "$@" ;; esac
+done
+exec $C -Wl,--dynamic-linker=$P/glibc/lib/ld-linux-aarch64.so.1 -Wl,-rpath,$P/glibc/lib "$@"
+```
+
+要点：`--sysroot=/` 而不是 `--sysroot=$PREFIX/glibc`——glibc 的 `libc.so` 是含绝对路径的
+linker script，带 sysroot 会被二次拼接；`-B $P/glibc/lib` 让 clang 找到 `Scrt1.o`/`crti.o`/`crtn.o`。
+
+## 3. 构建
+
+```sh
+unset LD_PRELOAD                       # 必须：Termux 的 libtermux-exec 会被 glibc loader 当成坏 ELF
+G="$PWD/.gnu"
+export PATH="$G/toolchain/bin:$PATH"
+export CARGO_TARGET_DIR="$G/target"
+export RUSTFLAGS="-C linker=$G/bin/cc-glibc"
+export CC="$G/bin/cc-glibc" CXX="$G/bin/cc-glibc" AR="$PREFIX/glibc/bin/ar"
+export CARGO_HTTP_CAINFO="$PREFIX/etc/tls/cert.pem"   # glibc 版 cargo 不认 Android 的 CA 路径
+export ULL_MSA_CLIENT_ID=          # 可选；烘微软登录 id，值不进 git
+
+# crates 走 USTC 稀疏索引（官方源在部分网络下只有 ~20 KB/s）
+cargo --config 'source.crates-io.replace-with="ustc"' \
+      --config 'source.ustc.registry="sparse+https://mirrors.ustc.edu.cn/crates.io-index/"' \
+      build --release -p unlucky-app-iced --no-default-features
+```
+
+`--no-default-features` 关掉 `gpu`，只编 tiny-skia（CPU）。产物：`.gnu/target/release/unlucky-launcher-iced`。
+
+门禁（与 CI 同一组命令，环境同上）：
+
+```sh
+cargo fmt --all --check
+cargo clippy --workspace --all-targets -- -D warnings
+cargo test --workspace --all-targets --no-fail-fast
+```
+
+Termux 上有三条**环境差异**失败（不是回归）：`launch` 测试读
+`/proc//task//children`（Android 内核没有）、natives 事件的长路径被脱敏成
+``、`settings_bridge` 的 mtime 热重载偶发（flaky）。PC 的 Linux CI 不受影响。
+
+## 4. 运行（termux-x11）
+
+```sh
+# 一次性：glibc 版 X 运行库（cf 源慢时可把 sources.list 里的 packages-cf 换成 packages.termux.dev）
+pkg install libx11-glibc libxkbcommon-glibc fontconfig-glibc \
+            libxcursor-glibc libxrandr-glibc libxi-glibc libxext-glibc \
+            libxcb-glibc libwayland-glibc
+
+termux-x11 :0 -ac &          # 配合已安装的 termux-x11 App 使用
+DISPLAY=:0 .gnu/target/release/unlucky-launcher-iced --software-renderer
+```
+
+无头取证（CI 同款通道）：
+
+```sh
+DISPLAY=:0 .gnu/target/release/unlucky-launcher-iced \
+  --software-renderer --screenshot /tmp/ull-termux.png --data-dir /tmp/ull-termux-data
+```
+
+- 中文：GUI 在 Termux 上会把 `/system/fonts/NotoSansCJK-Regular.ttc` 注册进 cosmic-text
+  （fontdb 不扫 Android 的字体目录），无需额外环境变量。
+- 启动日志里 `[auth] msa client_id=configured source=build` 表示构建期 id 已烘入。
+- **横屏优先**：Termux 上默认窗口尺寸会按当前 X 屏幕等比自适应（日志
+  `[window] ... source=termux-screen`），横屏铺满、竖屏也不溢出；验收尺寸 1180×760 仍是
+  默认基准，`ULL_WINDOW_SIZE=1520x900` 这类覆盖仍然优先。
+
+### 4.1 Termux 上的 Java
+
+`ull java install ` 在 Termux 上**默认先用系统包**（`openjdk-17/21/25`）：
+
+- 内置 SAU / TUNA / USTC / 官方四个 termux-main 镜像，按顺序尝试；
+- `apt-get` 的 lists/cache 隔离在 `$PREFIX/tmp/ull-java-termux/`，不改用户的 apt 配置；
+  装完自动清理该目录（一次安装约 100 MB 临时占用）；
+- 装完从 `$PREFIX/lib/jvm/java--openjdk` 发现，`ull java list` 直接可见；
+- `--vendor termux` 只走系统包；`temurin|oracle|microsoft|zulu` 仍走归档下载链。
+- 已实测：`ull java install 17` 从 SAU 镜像装完 `openjdk-17`（含 `openjdk-17-x`），
+  约 20 秒；`ull java list` 随后列出 `[system]` 的 17。
+
+### 4.2 跑 MC 需要的运行时（已手动验证）
+
+bionic 的 Termux JVM 加载不了 MC 的 glibc natives，所以 MC 要用 **glibc JVM**：
+
+```sh
+# Temurin 21 JRE（linux-aarch64），用 glibc loader 直接跑
+curl -L -o jre21.tar.gz \
+  https://api.adoptium.net/v3/binary/latest/21/ga/linux/aarch64/jre/hotspot/normal/eclipse
+tar -xzf jre21.tar.gz -C "$G/jre"
+JRE="$G/jre/jdk-21.0.13+9-jre"
+$PREFIX/glibc/lib/ld-linux-aarch64.so.1 \
+  --library-path "$JRE/lib:$JRE/lib/server:$PREFIX/glibc/lib" "$JRE/bin/java" -version
+```
+
+- AWT/X11：`DISPLAY=:0` 下 Swing 窗口正常（`headless=false`、`swing-ok`）。
+- GL：需要 §5 的 Mesa 26 GL 构建（`-Dgallium-drivers=zink,softpipe -Dglx=dri`）。
+  `zink` 目前卡在 `DRI3 not available`；**softpipe 可用**：
+  `MESA_LOADER_DRIVER_OVERRIDE=swrast LIBGL_ALWAYS_SOFTWARE=1`。
+- 端到端探针：LWJGL 3.3.3 arm64 natives + GLFW + GLX → `GL_VERSION=3.3 (Compatibility
+  Profile) Mesa 26.2.6`、`GL_RENDERER=softpipe`、`gl-ok`。
+
+> **启动器已接线**（本分支）：
+> - Linux/aarch64 上 LWJGL3 的 natives 自动改写成 `natives-linux-arm64`
+>   （Mojang 的 `libraries.minecraft.net` 对 arm64 一律 404，下载兜底到阿里云 Maven 镜像）；
+> - Termux glibc 构建启动 MC 时，子进程默认带 `MESA_LOADER_DRIVER_OVERRIDE=swrast`
+>   与 `LIBGL_ALWAYS_SOFTWARE=1`（用户自定义环境变量仍可覆盖）。
+>
+> **还差一步**：把实例的 Java 指到 glibc JRE。Temurin 解包后 `bin/java` 默认的
+> interpreter 在 Android 上不存在，先 patchelf 一次即可直接执行：
+>
+> ```sh
+> patchelf --set-interpreter "$PREFIX/glibc/lib/ld-linux-aarch64.so.1" \
+>   --set-rpath "$PREFIX/glibc/lib:$JRE/lib:$JRE/lib/server" "$JRE/bin/java"
+> "$JRE/bin/java" -version
+> ```
+>
+> 之后在实例设置里把 Java 指向 `$JRE/bin/java`（或 `--java`）即可。
+>
+> **真机验证（1.20.4）**：`ull install 1.20.4 --name mc-test`（740 MB）成功后，
+> `ull launch mc-test --java "$JRE/bin/java" --account Tester`，
+> MC 主菜单在 termux-x11 中渲染（窗口 854×480；日志在实例目录
+> `versions/1.20.4/logs/latest.log`）。非致命项：narrator 的 flite 缺失、
+> LWJGL JNI 版本告警、oshi 的 cpuVendor NPE（都未阻断启动）。
+
+## 5. GPU（已打通：自编 Mesa 26.2.6 + KGSL）
+
+termux-x11 的 X 客户端可以走硬件；glibc 侧的问题在**驱动**，不在 loader：
+
+1. `vulkan-icd-loader-glibc` + ICD JSON 本身正常。
+2. Termux 软件源的 glibc Mesa 24.2.6 不认识 Adreno 840
+   （`chip_id = 44050A31 is unsupported`）。
+3. Arch 的 `vulkan-freedreno 26.2.6` 能加载，但它是 Linux/DRM 构建，缺 KGSL
+   （`/dev/dri` 对 `untrusted_app` 被 SELinux 拒绝）。
+
+**解法：给 glibc 自编一份带 KGSL 的 Mesa 26.2.6。** 本机实测通过：
+
+```sh
+# 1) 源码 + 依赖
+#    mesa-26.2.6.tar.xz（archive.mesa3d.org）
+#    Debian libstdc++-14-dev 的头（$G/gnu-support/usr/include/c++/14）
+#    meson / ninja（pip 装 meson）
+# 2) 把源码里 *.py 的 shebang 从 #!/usr/bin/env python3 改成 Termux python3
+#    （Android 没有 /usr/bin/env）
+# 3) meson setup（cc-glibc 包装器：-c 不带链接参数、C++ 加 -stdlib=libstdc++、
+#    共享库链接加 -lstdc++；详见 §3）
+meson setup build3 --native-file="$G/mesa-native.ini" --wrap-mode=nofallback \
+  -Dbuildtype=release -Dstrip=true -Dplatforms=x11 \
+  -Dvulkan-drivers=freedreno -Dfreedreno-kmds=kgsl \
+  -Dgallium-drivers=zink,softpipe -Dglx=dri -Dopengl=true -Degl=enabled \
+  -Dgles1=disabled -Dgles2=enabled -Dllvm=disabled -Dgbm=disabled \
+  -Dvideo-codecs= -Dzstd=enabled -Dbuild-tests=false
+ninja -C build3
+```
+
+`--wrap-mode=nofallback` 是为了跳过 libarchive 子项目（它只被 freedreno 的 decode 工具需要，
+且它自带的 `id_t` 兜底宏会和 glibc 头冲突）。
+
+安装与启用：
+
+```sh
+cp build3/src/freedreno/vulkan/libvulkan_freedreno.so \
+   "$PREFIX/glibc/lib/libvulkan_freedreno_ull.so"
+cat > "$PREFIX/glibc/share/vulkan/icd.d/ull_freedreno.json" < ICED_BACKEND=wgpu
+[gpu] Selected: AdapterInfo { name: "Adreno (TM) 840", driver: "turnip Mesa driver",
+      driver_info: "Mesa 26.2.6", backend: Vulkan }
+[shot] 1657x1067 renderer=wgpu，首帧 61 ms
+```
+
+没装驱动/没有 GPU 时仍会打印具名错误并自动降级 tiny-skia（同一进程不能重建事件循环，
+降级走 respawn），所以 GPU 变体在纯 CPU 环境也能跑。
+
+## 6. 已知边界
+
+- 没有面向 Termux 的发布资产，也不在 CI 矩阵里；每次都要源码自建。
+- 只在 CPU 渲染 + 单台设备（Adreno 840 / Android 17）上验证过。
+- **装好 JDK ≠ 能跑 MC**：MC 的 LWJGL natives 是 glibc `.so`，bionic 的 Termux JVM 加载不了；
+  这条与「启动器 GUI 能显示」是两件事，未在本文覆盖。
+- `ULL_MSA_CLIENT_ID` 属于仓库 Secret，构建时从环境/Secret 注入，**不写进任何 git 文件**。
diff --git a/packaging/ed25519_ref.py b/packaging/ed25519_ref.py
new file mode 100644
index 0000000..dea1ca5
--- /dev/null
+++ b/packaging/ed25519_ref.py
@@ -0,0 +1,142 @@
+"""Ed25519 的**参考实现**（RFC 8032），只给发布侧签名脚本用（M190）。
+
+为什么这里自写一套：发布侧签名必须**零第三方依赖**（CI 不装 pip 包），而仓里 `crates/core` 的验签
+用的是 `ed25519-dalek`。两套实现互相独立，`sign_manifest.py --self-test` 用 RFC 8032 §7.1 的同一组
+向量把两边各自钉住 —— 任何一边坏了，向量那一半会红；两边都「一致地错」的概率极低。
+
+⚠ 这里的私钥路径（`sign`）**只在发布侧**（`packaging/sign_manifest.py --sign`）跑，不进任何产物；
+二进制里只有验签（`ed25519-dalek::verify_strict`）。扩展坐标公式与 dalek/ref10 同源，向量自检兜底。
+
+    import ed25519_ref as ref
+    seed = bytes.fromhex("…")            # 32 字节种子
+    pk = ref.public_key(seed)
+    sig = ref.sign(seed, b"message")     # 64 字节
+    assert ref.verify(pk, b"message", sig)
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+ALG = "ed25519"
+
+Q = 2**255 - 19
+L = 2**252 + 27742317777372353535851937790883648493
+
+def _inv(x: int) -> int:
+    return pow(x, Q - 2, Q)
+
+D = -121665 * _inv(121666) % Q
+_D2 = 2 * D % Q
+_SQRT_M1 = pow(2, (Q - 1) // 4, Q)
+
+def _recover_x(y: int, sign: int) -> int | None:
+    u = (y * y - 1) % Q
+    v = (D * y * y + 1) % Q
+    v3 = pow(v, 3, Q)
+    v7 = pow(v, 7, Q)
+    x = u * v3 % Q * pow(u * v7 % Q, (Q - 5) // 8, Q) % Q
+    if (v * x * x - u) % Q != 0:
+        x = x * _SQRT_M1 % Q
+        if (v * x * x - u) % Q != 0:
+            return None
+    if x % 2 != sign:
+        x = (Q - x) % Q
+    return x
+
+def _decompress(data: bytes) -> tuple[int, int, int, int] | None:
+    if len(data) != 32:
+        return None
+    y = int.from_bytes(data, "little")
+    sign = (y >> 255) & 1
+    y &= (1 << 255) - 1
+    if y >= Q:
+        return None
+    x = _recover_x(y, sign)
+    if x is None:
+        return None
+    return (x, y, 1, x * y % Q)
+
+def _add(p: tuple[int, int, int, int], r: tuple[int, int, int, int]):
+    x1, y1, z1, t1 = p
+    x2, y2, z2, t2 = r
+    a = (y1 - x1) * (y2 - x2) % Q
+    b = (y1 + x1) * (y2 + x2) % Q
+    c = t1 * _D2 * t2 % Q
+    d = 2 * z1 * z2 % Q
+    e, f, g, h = (b - a) % Q, (d - c) % Q, (d + c) % Q, (b + a) % Q
+    return (e * f % Q, g * h % Q, f * g % Q, e * h % Q)
+
+def _double(p: tuple[int, int, int, int]):
+    x1, y1, z1, _ = p
+    a = x1 * x1 % Q
+    b = y1 * y1 % Q
+    c = 2 * z1 * z1 % Q
+    d = -a % Q
+    e = ((x1 + y1) * (x1 + y1) - a - b) % Q
+    g = (d + b) % Q
+    f = (g - c) % Q
+    h = (d - b) % Q
+    return (e * f % Q, g * h % Q, f * g % Q, e * h % Q)
+
+def _scalarmult(p, e: int):
+    acc = (0, 1, 1, 0)
+    for bit in bin(e)[2:] if e else "":
+        acc = _double(acc)
+        if bit == "1":
+            acc = _add(acc, p)
+    return acc
+
+def _encode(p) -> bytes:
+    x, y, z, _ = p
+    zi = _inv(z)
+    x, y = x * zi % Q, y * zi % Q
+    return (y | ((x & 1) << 255)).to_bytes(32, "little")
+
+def _base():
+    encoded = (4 * _inv(5) % Q).to_bytes(32, "little")
+    return _decompress(encoded)
+
+def _hint(data: bytes) -> int:
+    return int.from_bytes(hashlib.sha512(data).digest(), "little") % L
+
+def public_key(seed: bytes) -> bytes:
+    h = hashlib.sha512(seed).digest()
+    a = int.from_bytes(_clamp(bytearray(h[:32])), "little")
+    return _encode(_scalarmult(_base(), a))
+
+def _clamp(scalar: bytearray) -> bytes:
+    scalar[0] &= 248
+    scalar[31] &= 127
+    scalar[31] |= 64
+    return bytes(scalar)
+
+def sign(seed: bytes, message: bytes) -> bytes:
+    if len(seed) != 32:
+        raise SystemExit("error: Ed25519 种子必须 32 字节")
+    h = hashlib.sha512(seed).digest()
+    a = int.from_bytes(_clamp(bytearray(h[:32])), "little")
+    prefix = h[32:]
+    r = _hint(prefix + message)
+    r_encoded = _encode(_scalarmult(_base(), r))
+    pk = _encode(_scalarmult(_base(), a))
+    k = _hint(r_encoded + pk + message)
+    s = (r + k * a) % L
+    return r_encoded + s.to_bytes(32, "little")
+
+def verify(pk: bytes, message: bytes, signature: bytes) -> bool:
+    if len(pk) != 32 or len(signature) != 64:
+        return False
+    r_bytes, s_bytes = signature[:32], signature[32:]
+    if int.from_bytes(s_bytes, "little") >= L:
+        return False
+    a = _decompress(pk)
+    r_point = _decompress(r_bytes)
+    if a is None or r_point is None:
+        return False
+    k = _hint(r_bytes + pk + message)
+    left = _scalarmult(_base(), int.from_bytes(s_bytes, "little"))
+    return _encode(left) == _encode(_add(r_point, _scalarmult(a, k)))
+
+
+
diff --git a/packaging/linux-check-docker.sh b/packaging/linux-check-docker.sh
new file mode 100644
index 0000000..8867c1b
--- /dev/null
+++ b/packaging/linux-check-docker.sh
@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+# 本地复跑 `.github/workflows/ci.yml` 的两条 **ubuntu 门禁**：`clippy --workspace --all-targets
+# -- -D warnings` 与 `test --workspace --all-targets`。
+#
+# 为什么要有这条脚本（与 `linux-smoke-docker.sh` 同一动机，但受检对象不同）：
+# - smoke 脚本复刻的是 `runtime-smoke` job（能不能真跑起来）；本脚本复刻的是**编译期门禁**
+#   （能不能编过 / 测过）。M144 的三条红里有两条（clippy ubuntu、test ubuntu）属于后者，
+#   而它们只在「Linux + `--all-targets` + `-D warnings`」三件事凑齐时才炸——
+#   在 Windows 本机永远复现不了（Windows 上那些 `#[cfg(target_os = "windows")]` 分支都有使用者）。
+#   所以这条脚本是「本机提前挡住那两条红」的唯一通道。
+#
+# 用法：
+#   bash packaging/linux-check-docker.sh [仓库根目录]
+#   ULL_CHECK_STAGES=clippy bash packaging/linux-check-docker.sh       # 只跑 clippy
+#   ULL_CHECK_TEST_ARGS='-p unlucky-app-iced --lib' \
+#     ULL_CHECK_STAGES=test bash packaging/linux-check-docker.sh       # 只跑一个 crate 的单测
+#
+# 前置：基础镜像 `ull-linux-smoke:bookworm`（由 `packaging/linux-smoke-docker.sh` 建）。
+#       本脚本在它之上只加一层 `cmake` + `ninja-build`：`aws-lc-sys`（rustls 的汇编后端）
+#       缺 cmake 编不过，M144 实测过。
+#
+# 诚实边界（别把它当 runner 的等价物）：
+# - 基础镜像是 **Debian 12（glibc 2.36）**，官方 runner 是 **Ubuntu 24.04（glibc 2.39）**；
+#   两者 rustc 走同一份 `rust-toolchain.toml`（stable），所以**编译期 lint 与单测判定**可对齐，
+#   但发行版差异面（系统库版本、字体）不受本脚本保护。
+# - 本脚本只跑 ci.yml 里那两条命令，不跑 fmt / build / runtime-smoke。
+# - 冷编很贵（全 workspace + `--all-targets`，M144 实测 15–25 分钟）。缓存卷 `ull-linux-check-target`
+#   第二次起是热的；**别**把宿主机的 target 目录挂进来（路径与指纹都对不上，等于骗自己）。
+
+set -euo pipefail
+
+repo_root=$(cd "${1:-.}" && pwd)
+base_image=${ULL_SMOKE_IMAGE:-ull-linux-smoke:bookworm}
+image=${ULL_CHECK_IMAGE:-ull-linux-check:bookworm}
+cargo_volume=${ULL_CARGO_VOLUME:-ull-cargo-reg}
+target_volume=${ULL_CHECK_TARGET_VOLUME:-ull-linux-check-target}
+apt_mirror=${ULL_APT_MIRROR:-https://mirrors.tuna.tsinghua.edu.cn}
+stages=${ULL_CHECK_STAGES:-clippy test}
+test_args=${ULL_CHECK_TEST_ARGS:---workspace --all-targets --no-fail-fast}
+fail_fast=${ULL_CHECK_FAIL_FAST:-0}
+
+# Git Bash 里路径是 MSYS 虚拟路径：直接喂给 `docker -v` 会被当成容器内路径（M62 踩过）。
+if command -v cygpath >/dev/null 2>&1; then
+  repo_root=$(cygpath -m "$repo_root")
+fi
+echo "== 仓库: $repo_root"
+echo "== 阶段: $stages（test 参数: $test_args）"
+
+if ! docker image inspect "$base_image" >/dev/null 2>&1; then
+  echo "!! 缺基础镜像 $base_image —— 先跑一次：" >&2
+  echo "   bash packaging/linux-smoke-docker.sh . D:/tmp/ull-smoke" >&2
+  echo "   （它建的镜像里已经带了 ci.yml 那批图形栈编译依赖；本脚本只在其上加 cmake/ninja）" >&2
+  exit 2
+fi
+
+# 一层派生镜像：cmake + ninja-build。只在缺镜像或显式 ULL_CHECK_REBUILD_IMAGE=1 时重建。
+if ! docker image inspect "$image" >/dev/null 2>&1 || [ "${ULL_CHECK_REBUILD_IMAGE:-0}" = "1" ]; then
+  context=$(mktemp -d)
+  trap 'rm -rf "$context"' EXIT
+  cat >"$context/Dockerfile" <&2; exit 2 ;;
+      esac
+      echo "== 开始: $label"
+      set +e
+      "$run"
+      code=$?
+      set -e
+      # 退出码单独成行：一眼能看出是「编译期 lint」还是「单测」，也能与 CI 注解里的码对照。
+      echo "== 结束: $label → exit=$code"
+      if [ "$code" -ne 0 ]; then
+        overall=1
+        if [ "$ULL_CHECK_FAIL_FAST" = "1" ]; then exit "$code"; fi
+      fi
+    done
+    echo "== 汇总: $ULL_CHECK_STAGES → exit=$overall"
+    exit "$overall"
+  '
+
+echo "== 两条 ubuntu 门禁已跑完（上表 exit=0 才算绿）"
diff --git a/packaging/linux-smoke-docker.sh b/packaging/linux-smoke-docker.sh
new file mode 100644
index 0000000..8a124ac
--- /dev/null
+++ b/packaging/linux-smoke-docker.sh
@@ -0,0 +1,99 @@
+#!/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` 可覆盖）。
+# - 受检 bin 是 iced 版 `unlucky-launcher-iced`，与 `ci.yml` 的 runtime-smoke 逐步对应（M118：Slint 版
+#   bin/包 `unlucky-launcher`/`unlucky-app` 已随 `crates/app` 退出 workspace，改了这里要两边一起改）。
+
+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" <_windows_x64.exe      (bare exe, no zip)
+    Windows arm64   unlucky-launcher__windows_arm64.exe    (bare exe, native arm64 runner)
+    Linux x64       unlucky-launcher__linux_x64.tar.gz
+    Linux arm64     unlucky-launcher__linux_arm64.tar.gz
+    macOS arm64     unlucky-launcher__macos_arm64.tar.gz
+    macOS x64       unlucky-launcher__macos_x64.tar.gz
+    every slot      ull___[.exe]           (bare CLI binary, no archive)
+    all             SHA256SUMS.txt
+    all             manifest.json                              (only with --manifest, see below)
+
+Naming rule (user's call, 2026-11-05): `___`, 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.
+
+`--manifest` additionally writes `manifest.json` (the update manifest, D50) into the same
+output directory. The generation itself lives in `packaging/make_manifest.py`, invoked as a
+subprocess: this file stays the single source of truth for **naming** (`asset_stem()`), that
+one is the single writer of the **manifest**, and it derives every sha256/size from the
+`SHA256SUMS.txt` this script just wrote — one set of facts, no second bookkeeping. CI does not
+use this flag: `release-publish.yml` recomputes `SHA256SUMS.txt` after pruning the publish
+whitelist and generates the manifest from *that*, so the manifest always describes what ships.
+
+Slot and build directory are overridable because the build host is not always the
+artifact: a cross build's binaries live in `target//release` under an x64
+host, while every native slot (all six in CI, M140) puts them in `target/release`.
+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 write_manifest(out_dir: Path, version: str) -> Path:
+    """`manifest.json`（D50）：跑的是 CI 发布侧同一份脚本，事实全部来自刚写完的 SHA256SUMS.txt。"""
+    script = REPO_ROOT / "packaging" / "make_manifest.py"
+    proc = subprocess.run([sys.executable, str(script), "--dist", str(out_dir), "--version", version])
+    if proc.returncode != 0:
+        fail(f"manifest generation failed ({script.name} exited {proc.returncode})")
+    return out_dir / "manifest.json"
+
+
+def asset_stem(name: str, version: str, slot: str) -> str:
+    """`___` — 产物命名的唯一真相源。
+
+    用户令（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___[.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")
+    parser.add_argument("--manifest", action="store_true", help="also write manifest.json (update manifest, D50)")
+    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}")
+    if args.manifest:
+        manifest = write_manifest(out_dir, version)
+        print(f"manifest: {manifest.name}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/packaging/make_manifest.py b/packaging/make_manifest.py
new file mode 100644
index 0000000..4f41f91
--- /dev/null
+++ b/packaging/make_manifest.py
@@ -0,0 +1,396 @@
+#!/usr/bin/env python3
+"""Generate `manifest.json` — the update manifest the launcher reads (D50).
+
+Contract and rationale live in `packaging/README.md` §13; this docstring only states what the
+code must not get wrong.
+
+* **Shape authority** = `crates/core/src/update/manifest.rs` (`ReleaseManifest`,
+  `deny_unknown_fields` + per-field validation). This script only writes that shape.
+* **Facts come from one place**: every `sha256` is read out of the Release's own
+  `SHA256SUMS.txt`, every `size` is `stat()` of the same file — the two can never disagree.
+  The version token inside each asset name is asserted to equal `--version`, so a tag that
+  drifted from `Cargo.toml` cannot yield a manifest pointing at files that do not exist.
+* **Only launcher artifacts go in.** `ull` does not: the DTO has no role field and
+  `Release::artifact_for(target)` returns the *first* match, so listing the CLI beside the GUI
+  would make "which file do I overwrite" depend on array order.
+* **`url`**: bare asset name by default (the `DirSource` convention in
+  `crates/core/src/update/source.rs`); with `--asset-base-url` a tag-pinned absolute URL,
+  which is what CI uses.
+
+Usage:
+    python3 packaging/make_manifest.py --dist dist --version v0.2.2 --channel stable \\
+        --asset-base-url https://github.com/o/r/releases/download/v0.2.2
+    python3 packaging/make_manifest.py --self-test        # golden + strict-parse self check
+"""
+
+from __future__ import annotations
+
+import argparse
+import copy
+import json
+import re
+import sys
+from pathlib import Path
+from typing import NoReturn
+
+# 本机 Python 可能是 isolated 模式（`safe_path=True`，脚本目录不进 `sys.path`），CI 的标准
+# python3 则会自动加入。显式补一次，两种环境下 `import make_artifacts` 都成立。
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+# 只借常量：产物命名（SLOTS / LAUNCHER_ASSET）、CLI 名与 SHA256SUMS 文件名都是 make_artifacts
+# 的单一口径，这里不复制一份表（复制就会漂）；反向依赖不存在（make_artifacts 只用子进程调本脚本）。
+import make_artifacts
+
+MANIFEST_NAME = "manifest.json"
+CHANNELS = ("stable", "beta", "alpha", "nightly")
+# 文件名里的平台段 -> 清单 target 的系统段（`windows_x64` -> `win-x64`）。
+PLATFORM_TARGET = {"windows": "win", "macos": "mac", "linux": "linux"}
+# 产物扩展名 -> 清单 format。归档（tar.gz）在 DTO 里只有「解压即用」这一档 `portable-zip`：
+# 名字带 zip，语义是「非安装器、可原地替换」（PackageFormat::needs_installer() == false）。
+EXT_FORMAT = {".exe": "portable-exe", ".tar.gz": "portable-zip"}
+GOLDEN = Path(__file__).resolve().parent / "tests" / "manifest.golden.json"
+# DTO 侧的取值表镜像（crates/core/src/update/target.rs::parse_os / Arch::parse / PackageFormat::parse）。
+TARGET_OS = {"win", "windows", "mac", "macos", "osx", "darwin", "linux"}
+TARGET_ARCH = {
+    "x64", "x86_64", "x86-64", "amd64", "arm64", "aarch64", "arm64e", "x86", "i686", "i386", "x86_32",
+}
+FORMATS = {"msi", "dmg", "appimage", "deb", "rpm", "portable-zip", "zip", "portable-exe", "exe"}
+SEMVER = re.compile(r"^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+([0-9A-Za-z.-]+))?$")
+SUMS_LINE = re.compile(r"^([0-9A-Fa-f]{64})[ \t]+\*?(.+)$")
+
+
+def fail(message: str) -> NoReturn:
+    print(f"error: {message}", file=sys.stderr)
+    raise SystemExit(1)
+
+
+def normalize_version(text: str) -> str:
+    """`v0.2.2` -> `0.2.2`（tag 带 `v`，产物名与清单都不带）。"""
+    version = text.strip()
+    version = version[1:] if version.startswith("v") else version
+    if not semver_ok(version):
+        fail(f"version `{text}` is not a semver")
+    return version
+
+
+def semver_ok(text: str) -> bool:
+    """Mirror of `crates/core/src/update/version.rs::Version::parse` on the accepted shapes."""
+    match = SEMVER.match(text)
+    if not match:
+        return False
+    if any(len(number) > 1 and number.startswith("0") for number in match.group(1, 2, 3)):
+        return False
+    pre, build = match.group(4), match.group(5)
+    if pre is not None:
+        for ident in pre.split("."):
+            if not ident or (ident.isdigit() and len(ident) > 1 and ident.startswith("0")):
+                return False
+    if build is not None and any(not ident for ident in build.split(".")):
+        return False
+    return True
+
+
+def read_sums(dist: Path) -> dict[str, str]:
+    """`SHA256SUMS.txt` -> {file name: lowercase sha256}. Missing/odd entries are fatal."""
+    sums_path = dist / make_artifacts.SUMS_NAME
+    if not sums_path.is_file():
+        fail(f"missing {sums_path}（清单的 sha256 只从这里取，不另算一份）")
+    sums: dict[str, str] = {}
+    for lineno, line in enumerate(sums_path.read_text(encoding="utf-8").splitlines(), 1):
+        if not line.strip():
+            continue
+        match = SUMS_LINE.match(line)
+        if not match:
+            fail(f"{sums_path.name}:{lineno} 不是 `  <文件名>` 形态：{line!r}")
+        digest, name = match.group(1).lower(), match.group(2)
+        if name in sums:
+            fail(f"{sums_path.name} 里 {name} 出现两次（无法确定哪个 sha256 是对的）")
+        sums[name] = digest
+    if not sums:
+        fail(f"{sums_path} 是空的：没有产物就没有清单")
+    return sums
+
+
+def split_asset(name: str, version: str) -> tuple[str, str, str, str]:
+    """`___[.exe|.tar.gz]` -> (name, platform, arch, ext)."""
+    stem, ext = name, ""
+    for candidate in EXT_FORMAT:
+        if stem.endswith(candidate):
+            stem, ext = stem[: -len(candidate)], candidate
+            break
+    parts = stem.rsplit("_", 3)
+    if len(parts) != 4:
+        fail(f"`{name}` 不符合 `<名字>_<版本>_<平台>_<架构>` 命名（见 make_artifacts.asset_stem）")
+    product, tag_version, platform_name, arch_name = parts
+    if tag_version != version:
+        fail(f"`{name}` 里的版本是 {tag_version}，清单要的是 {version}（tag 与 Cargo.toml 漂了？）")
+    if (platform_name, arch_name) not in {
+        (slot_os, slot_arch) for slot_os, slot_arch, _kind in make_artifacts.SLOTS.values()
+    }:
+        fail(f"`{name}` 的平台/架构 {platform_name}/{arch_name} 不在发布矩阵里")
+    return product, platform_name, arch_name, ext
+
+
+def build_artifacts(dist: Path, version: str, base_url: str) -> list[dict[str, object]]:
+    """Launcher artifacts from `SHA256SUMS.txt`, in matrix order (= priority order)."""
+    sums = read_sums(dist)
+    by_slot: dict[tuple[str, str], dict[str, object]] = {}
+    for name, digest in sums.items():
+        product, platform_name, arch_name, ext = split_asset(name, version)
+        if product != make_artifacts.LAUNCHER_ASSET:
+            continue  # `ull` 不进清单，理由见模块注释
+        fmt = EXT_FORMAT.get(ext)
+        if fmt is None:
+            fail(f"`{name}` 没有可识别的扩展名，无法判定包形态（format）")
+        path = dist / name
+        if not path.is_file():
+            fail(f"{make_artifacts.SUMS_NAME} 提到 {name}，但 {path} 不存在")
+        size = path.stat().st_size
+        if size == 0:
+            fail(f"{path} 是 0 字节：这类产物只可能是打包漏了")
+        url = f"{base_url.rstrip('/')}/{name}" if base_url else name
+        if (platform_name, arch_name) in by_slot:
+            fail(f"{platform_name}/{arch_name} 出现两个启动器产物，清单无法确定该用哪一个")
+        by_slot[(platform_name, arch_name)] = {
+            "target": f"{PLATFORM_TARGET[platform_name]}-{arch_name}",
+            "format": fmt,
+            "url": url,
+            "size": size,
+            "sha256": digest,
+        }
+    order = [(slot_os, slot_arch) for slot_os, slot_arch, _kind in make_artifacts.SLOTS.values()]
+    artifacts_out = [by_slot[key] for key in order if key in by_slot]
+    if not artifacts_out:
+        fail(f"{make_artifacts.SUMS_NAME} 里没有任何 `{make_artifacts.LAUNCHER_ASSET}_*` 产物，清单会是空的")
+    return artifacts_out
+
+
+def build_manifest(
+    dist: Path,
+    version: str,
+    channel: str,
+    *,
+    base_url: str = "",
+    min_supported: str | None = None,
+    notes: str | None = None,
+    released_at: str | None = None,
+    force: bool = False,
+) -> dict[str, object]:
+    """Assemble the manifest document (the shape `ReleaseManifest` deserializes)."""
+    if channel not in CHANNELS:
+        fail(f"未知渠道 `{channel}`（只认 {' / '.join(CHANNELS)}）")
+    release: dict[str, object] = {"version": version, "channel": channel}
+    if released_at:
+        release["released_at"] = released_at
+    if notes:
+        release["notes"] = notes
+    release["force"] = force
+    if min_supported:
+        release["min_supported"] = normalize_version(min_supported)
+    release["artifacts"] = build_artifacts(dist, version, base_url)
+    return {"channel": channel, "releases": [release]}
+
+
+def render(doc: dict[str, object]) -> str:
+    """Deterministic JSON: same facts + same args ⇒ byte-identical file (golden-testable)."""
+    return json.dumps(doc, ensure_ascii=False, indent=2) + "\n"
+
+
+# ── 严格解析镜像（DTO 的看门规则）───────────────────────────────────────────────────────
+# `manifest.rs` 用 `deny_unknown_fields` + 逐字段校验；这里是它的 Python 镜像，只为了在没有
+# Rust 的机器上（本地打包、CI 发布步）也能当场炸掉拼错的字段。字段/取值的权威永远是 .rs。
+
+
+def check(condition: bool, message: str) -> None:
+    if not condition:
+        raise ValueError(message)
+
+
+def check_keys(where: str, obj: object, allowed: set[str], required: set[str]) -> dict:
+    check(isinstance(obj, dict), f"{where} 必须是对象")
+    unknown = set(obj) - allowed
+    check(not unknown, f"{where} 出现未知字段 {sorted(unknown)}（DTO 是 deny_unknown_fields）")
+    missing = required - set(obj)
+    check(not missing, f"{where} 缺字段 {sorted(missing)}")
+    return obj
+
+
+def strict_parse(doc: object) -> None:
+    """Raise `ValueError` on anything `ReleaseManifest::from_json` would reject."""
+    top = check_keys("清单", doc, {"channel", "releases"}, {"channel"})
+    check(top["channel"] in CHANNELS, f"清单渠道 `{top['channel']}` 无法识别")
+    releases = top.get("releases", [])
+    check(isinstance(releases, list), "releases 必须是数组")
+    seen: list[str] = []
+    for index, raw in enumerate(releases):
+        where = f"releases[{index}]"
+        release = check_keys(
+            where,
+            raw,
+            {"version", "channel", "released_at", "notes", "force", "min_supported", "artifacts"},
+            {"version"},
+        )
+        version = release["version"]
+        check(isinstance(version, str) and semver_ok(version), f"{where}.version 不是合法 semver")
+        check(version not in seen, f"{where}.version {version} 在清单里重复出现")
+        seen.append(version)
+        if "channel" in release:
+            check(release["channel"] in CHANNELS, f"{where}.channel 无法识别")
+        for key in ("released_at", "notes"):
+            check(release.get(key) is None or isinstance(release.get(key), str), f"{where}.{key} 必须是字符串")
+        check(isinstance(release.get("force", False), bool), f"{where}.force 必须是布尔")
+        if release.get("min_supported") is not None:
+            check(semver_ok(str(release["min_supported"])), f"{where}.min_supported 不是合法 semver")
+        artifacts_list = release.get("artifacts", [])
+        check(isinstance(artifacts_list, list), f"{where}.artifacts 必须是数组")
+        for art_index, raw_art in enumerate(artifacts_list):
+            art_where = f"{where}.artifacts[{art_index}]"
+            art = check_keys(
+                art_where,
+                raw_art,
+                {"target", "format", "url", "size", "sha256", "sha1"},
+                {"target", "format", "url", "size"},
+            )
+            os_part, _, arch_part = str(art["target"]).strip().partition("-")
+            check(
+                bool(arch_part) and os_part.lower() in TARGET_OS and arch_part.lower() in TARGET_ARCH,
+                f"{art_where}.target `{art['target']}` 无法识别（形如 win-x64）",
+            )
+            check(str(art["format"]).lower() in FORMATS, f"{art_where}.format 无法识别")
+            check(isinstance(art["url"], str) and art["url"].strip(), f"{art_where}.url 为空")
+            size = art["size"]
+            check(isinstance(size, int) and not isinstance(size, bool) and size > 0, f"{art_where}.size 必须 > 0")
+            sha256, sha1 = art.get("sha256"), art.get("sha1")
+            check(sha256 is not None or sha1 is not None, f"{art_where} 既没有 sha256 也没有 sha1")
+            digest_hex = str(sha256 if sha256 is not None else sha1)
+            expect = 64 if sha256 is not None else 40
+            check(
+                len(digest_hex) == expect and all(c in "0123456789abcdefABCDEF" for c in digest_hex),
+                f"{art_where} 的摘要应为 {expect} 位十六进制",
+            )
+
+
+def self_test() -> int:
+    """Golden 对拍（`.gitattributes` 的 `eol=lf` 保证跨平台同字节）+ 严格解析正负例：证明写出来的东西能被 DTO 吃下。"""
+    import tempfile
+
+    with tempfile.TemporaryDirectory() as tmp:
+        dist = Path(tmp)
+        version = "9.9.9"
+        # 两种启动器形态（裸 exe / 归档）+ 一个 CLI 资产：既覆盖 target/format 映射，
+        # 也钉住「`ull` 不进清单」这条决定。
+        payloads = {
+            f"{make_artifacts.LAUNCHER_ASSET}_{version}_windows_x64.exe": b"gui payload\n",
+            f"{make_artifacts.LAUNCHER_ASSET}_{version}_linux_x64.tar.gz": b"tar payload\n",
+            f"{make_artifacts.CLI_BIN}_{version}_windows_x64.exe": b"cli payload\n",
+        }
+        for name, payload in payloads.items():
+            (dist / name).write_bytes(payload)
+        (dist / make_artifacts.SUMS_NAME).write_text(
+            "".join(f"{make_artifacts.sha256(dist / name)}  {name}\n" for name in payloads),
+            encoding="utf-8",
+            newline="\n",
+        )
+        doc = build_manifest(
+            dist,
+            version,
+            "stable",
+            min_supported="9.0.0",
+            notes="golden 样例（自验用，不是真实发布）",
+            released_at="2026-01-02T03:04:05Z",
+        )
+        text = render(doc)
+
+    if "--write-golden" in sys.argv:
+        GOLDEN.parent.mkdir(parents=True, exist_ok=True)
+        GOLDEN.write_text(text, encoding="utf-8", newline="\n")
+        print(f"golden:  {GOLDEN} 已重写")
+    expected = GOLDEN.read_text(encoding="utf-8")
+    if text != expected:
+        print("--- generated ---", text, "--- golden ---", expected, sep="\n", file=sys.stderr)
+        fail("生成的清单与 golden 不一致（改了口径就 --write-golden 重出并对 diff）")
+    print(f"golden:   与 {GOLDEN.name} 逐字节一致")
+
+    strict_parse(doc)
+    print("strict:   生成物通过严格解析镜像（deny_unknown_fields + 逐字段校验）")
+    # 负例：只测「顺利通过」等于没测——每条篡改都必须被拒。
+    for label, mutate in (
+        ("未知字段", lambda d: d.update(extra=1)),
+        ("未知版本字段", lambda d: d["releases"][0].update(extra=1)),
+        ("未知产物字段", lambda d: d["releases"][0]["artifacts"][0].update(extra=1)),
+        ("缺 sha256", lambda d: d["releases"][0]["artifacts"][0].pop("sha256")),
+        ("摘要长度错", lambda d: d["releases"][0]["artifacts"][0].update(sha256="deadbeef")),
+        ("size 为 0", lambda d: d["releases"][0]["artifacts"][0].update(size=0)),
+        ("size 是字符串", lambda d: d["releases"][0]["artifacts"][0].update(size="12")),
+        ("未知 target", lambda d: d["releases"][0]["artifacts"][0].update(target="solaris-x64")),
+        ("未知 format", lambda d: d["releases"][0]["artifacts"][0].update(format="msix")),
+        ("空 url", lambda d: d["releases"][0]["artifacts"][0].update(url="  ")),
+        ("版本重复", lambda d: d["releases"].append(copy.deepcopy(d["releases"][0]))),
+        ("版本号不合法", lambda d: d["releases"][0].update(version="1.0")),
+        ("渠道不认识", lambda d: d.update(channel="canary")),
+        ("缺顶层 channel", lambda d: d.pop("channel")),
+    ):
+        tampered = copy.deepcopy(doc)
+        mutate(tampered)
+        try:
+            strict_parse(tampered)
+        except ValueError:
+            print(f"strict:   负例「{label}」被正确拒绝")
+            continue
+        fail(f"严格解析放过了负例「{label}」——这条校验形同虚设")
+    print("self-test: ok")
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--dist", default="dist", help="directory holding the assets + SHA256SUMS.txt (default: dist/)")
+    parser.add_argument("--version", help="release version, e.g. v0.2.2 (must match the asset file names)")
+    parser.add_argument("--channel", default="stable", choices=CHANNELS, help="manifest channel (D50: stable only for now)")
+    parser.add_argument("--out", help=f"output path (default: /{MANIFEST_NAME})")
+    parser.add_argument("--asset-base-url", default="", help="prefix for artifact urls; omit for bare file names")
+    parser.add_argument("--min-supported", help="lowest version still supported (omitted when not given)")
+    parser.add_argument("--notes", help="plain-text release notes for the update prompt")
+    parser.add_argument("--notes-file", help="read --notes from this file")
+    parser.add_argument("--released-at", help="RFC3339 timestamp (display only)")
+    parser.add_argument("--force", action="store_true", help="mark this release as force-update")
+    parser.add_argument("--self-test", action="store_true", help="golden + strict-parse self check (no files written)")
+    parser.add_argument("--write-golden", action="store_true", help=argparse.SUPPRESS)
+    args = parser.parse_args()
+
+    if args.self_test:
+        return self_test()
+    if not args.version:
+        parser.error("--version is required (it must match the asset file names)")
+    dist = Path(args.dist)
+    if not dist.is_absolute():
+        dist = make_artifacts.REPO_ROOT / dist
+    notes = args.notes
+    if args.notes_file:
+        notes = (make_artifacts.REPO_ROOT / args.notes_file).read_text(encoding="utf-8").strip()
+    doc = build_manifest(
+        dist,
+        normalize_version(args.version),
+        args.channel,
+        base_url=args.asset_base_url,
+        min_supported=args.min_supported,
+        notes=notes,
+        released_at=args.released_at,
+        force=args.force,
+    )
+    text = render(doc)
+    strict_parse(doc)
+    out = Path(args.out) if args.out else dist / MANIFEST_NAME
+    if not out.is_absolute():
+        out = make_artifacts.REPO_ROOT / out
+    out.write_text(text, encoding="utf-8", newline="\n")
+    release = doc["releases"][0]
+    artifacts_list = release["artifacts"]
+    print(f"manifest: {out.name}  channel={doc['channel']} version={release['version']} artifacts={len(artifacts_list)}")
+    for item in artifacts_list:
+        print(f"  {item['target']:<14} {item['format']:<13} {item['size']:>10} B  sha256={str(item['sha256'])[:12]}  {item['url']}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/packaging/pe_version.rs b/packaging/pe_version.rs
new file mode 100644
index 0000000..724c554
--- /dev/null
+++ b/packaging/pe_version.rs
@@ -0,0 +1,101 @@
+// PE 版本资源（VERSIONINFO）的唯一口径：发布者/产品/版权/版本号。
+//
+// 这个文件被 `crates/cli/build.rs` 与 `crates/app-iced/build.rs` 各 `include!` 一次——两个产物
+// （`ull` 与 `unlucky-launcher-iced`）的署名必须逐字相同，复制两份表迟早会漂。
+//
+// # 字段口径（M190，塔已拍板）
+//
+// | 字段 | 值 | 为什么 |
+// |---|---|---|
+// | `CompanyName` | `Unlucky Launcher Project` | 发布者。**不得出现个人真实姓名**：这个名字随每个下载的 exe 传播，将来买 Authenticode 证书时 SmartScreen 显示的是证书主体，二者要对得上 |
+// | `ProductName` / `FileDescription` | `Unlucky Launcher` | Windows「属性 → 详细信息」里最显眼的两行 |
+// | `LegalCopyright` | `© 2026 Unlucky Launcher Project · Apache-2.0` | 版权 + 许可（仓库是 Apache-2.0） |
+// | `FileVersion` / `ProductVersion` | `CARGO_PKG_VERSION` 的四段式 | 与 `Cargo.toml` **同源**：不另写一份版本号 |
+// | `InternalName` / `OriginalFilename` | bin 名 / `.exe` | 供「这个 exe 到底叫什么」的取证 |
+// | `Comments` | 仓库地址 | 项目署名 `AskaEth` 的可读落点（GitHub 命名空间，不是个人姓名） |
+//
+// # 只在 windows 目标上真跑
+//
+// 版本资源是 PE 概念：`build.rs` 先看 `CARGO_CFG_TARGET_OS`，不是 `windows` 就整段返回，
+// Linux/macOS 构建一个字节都不多编译（它们的发布产物本来也没有 PE 头）。
+//
+// # 为什么不用 `windows_subsystem` 之外的资源
+//
+// 只要 VERSIONINFO 一块：图标、清单（DPI/权限）另有归属，本 mission 不碰（加了会改变运行时行为）。
+//
+// # 守门
+//
+// `packaging/check_pe_version.py` 是「写进源码不算，读回产物才算」的那道判据：它直接读 exe 字节，
+// 断言 `VS_VERSION_INFO` 结构在、上述字符串（UTF-16LE）在。CI 的构建槽位跑它。
+
+/// 发布者（CompanyName）。**改它等于改署名**：同时要改 Authenticode 证书主体与 README 的署名口径。
+pub const COMPANY_NAME: &str = "Unlucky Launcher Project";
+
+/// 产品名（`ProductName` 与 `FileDescription`）。
+pub const PRODUCT_NAME: &str = "Unlucky Launcher";
+
+/// 版权行（`LegalCopyright`）。
+pub const COPYRIGHT: &str = "© 2026 Unlucky Launcher Project · Apache-2.0";
+
+/// 项目署名（GitHub 命名空间；`Comments` 里随仓库地址一起出现）。
+pub const PROJECT_HANDLE: &str = "AskaEth";
+
+/// 仓库地址（`Comments`）。
+pub const REPOSITORY: &str = "https://github.com/AskaEth/Unlucky-Launcher";
+
+/// 把版本号补成四段式的数值（`0.2.3` → `0.2.3.0`；预发布段丢掉，因为 PE 的数值字段只认数字）。
+///
+/// 返回 `(四段元组, 打包成 FILEVERSION 用的 u64)`；任一数字大于 65535 时按 65535 截断
+/// （PE 的每个分量只有 16 位，真实版本号远小于它）。
+#[must_use]
+pub fn four_part(version: &str) -> ([u64; 4], u64) {
+    // `0.2.3-beta.1` 的数值部分只有前三段；`+build` 元数据同理不计入版本资源。
+    let numeric = version.split(['-', '+']).next().unwrap_or(version).trim();
+    let mut parts = [0_u64; 4];
+    for (index, piece) in numeric.split('.').take(4).enumerate() {
+        parts[index] = piece.parse::().unwrap_or(0).min(0xFFFF);
+    }
+    let packed = (parts[0] << 48) | (parts[1] << 32) | (parts[2] << 16) | parts[3];
+    (parts, packed)
+}
+
+/// 给一个 bin 名（`ull` / `unlucky-launcher-iced`）写出版本资源。
+///
+/// 由两个 crate 的 `build.rs` 调用；非 windows 目标直接返回。
+pub fn emit_pe_version_resource(binary_name: &str) {
+    println!("cargo:rerun-if-changed=build.rs");
+    println!("cargo:rerun-if-env-changed=CARGO_PKG_VERSION");
+    // 共享口径文件改了也要重编（`include!` 不被 cargo 追踪）。
+    println!("cargo:rerun-if-changed=../../packaging/pe_version.rs");
+
+    if std::env::var("CARGO_CFG_TARGET_OS").as_deref() != Ok("windows") {
+        // Linux/macOS：没有 PE 头，整段不跑（发布产物的形状不变）。
+        return;
+    }
+
+    let version = std::env::var("CARGO_PKG_VERSION").unwrap_or_else(|_| "0.0.0".to_string());
+    let (parts, packed) = four_part(&version);
+    let dotted = format!("{}.{}.{}.{}", parts[0], parts[1], parts[2], parts[3]);
+
+    let mut resource = winresource::WindowsResource::new();
+    resource.set("CompanyName", COMPANY_NAME);
+    resource.set("ProductName", PRODUCT_NAME);
+    resource.set("FileDescription", PRODUCT_NAME);
+    resource.set("LegalCopyright", COPYRIGHT);
+    resource.set("InternalName", binary_name);
+    resource.set("OriginalFilename", &format!("{binary_name}.exe"));
+    resource.set("Comments", REPOSITORY);
+    // 字符串形态（「属性」页显示的）与数值形态（资源管理器/安装器排序用的）都要给。
+    resource.set("FileVersion", &dotted);
+    resource.set("ProductVersion", &dotted);
+    resource.set_version_info(winresource::VersionInfo::FILEVERSION, packed);
+    resource.set_version_info(winresource::VersionInfo::PRODUCTVERSION, packed);
+
+    if let Err(error) = resource.compile() {
+        // 资源编不出来就**中断构建**：宁可不出产物，也不出一个「属性里什么都没有」的 exe
+        // （那正是 M190 要修的病）。
+        panic!("写 PE 版本资源失败（{binary_name} {dotted}）：{error}");
+    }
+    println!("cargo:warning=PE VERSIONINFO: {binary_name} {dotted} / {COMPANY_NAME}");
+    let _ = PROJECT_HANDLE;
+}
diff --git a/packaging/release-notes.md b/packaging/release-notes.md
new file mode 100644
index 0000000..47e7e1b
--- /dev/null
+++ b/packaging/release-notes.md
@@ -0,0 +1,210 @@
+# Unlucky Launcher {{VERSION}}
+
+Rust-native **single-file** Minecraft launcher: iced 0.14 + Material 3 Expressive UI, built-in AI agent
+(chat / setting 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.
+
+## What's new in {{VERSION}}
+
+- **Linux x64 is a published platform.** The release workflow now builds `linux-x64` on a native `ubuntu-22.04`
+  runner by default (not only in manual all-slots runs) and publishes it: `unlucky-launcher_{{VERSION}}_linux_x64.tar.gz`
+  plus the bare `ull_{{VERSION}}_linux_x64`. The artifact itself was started on a Linux machine under a real display
+  server, rendered a frame and logged the expected theme/backend lines before this decision, and the same check is
+  now a per-slot CI gate. Linux ARM64 is built too, but stays unpublished until an ARM64 machine runs it.
+- **{{VERSION}} is the first release published as a stable release.** GitHub only points
+  `releases/latest` at the newest **non-prerelease** release, so `0.2.2` — kept as a historical
+  pre-release, untouched — never appeared there. A pushed tag now creates a stable release by default;
+  a pre-release has to be asked for explicitly (`workflow_dispatch` with `prerelease=true`).
+- **Self-update works end to end.** `ull update check` / `ull update apply` and the settings panel's
+  Update group share one core (`crates/core/src/update/`): manifest, version and channel admission,
+  length + SHA256 verification, and an atomic rename-based swap that rolls back on failure. Only the
+  stable channel is published today.
+- **Online content library (Modrinth, anonymous).** Search, project details and version lists come from
+  Modrinth's v2 API with facets derived from the target instance, and a known hash completes a remote
+  entry. Being offline is reported as "not connected", never as "no matching content".
+- **Per-file decisions when importing a modpack.** The pre-import scan lists every conflicting file in
+  pages of 40, and you choose keep-all, overwrite-all, or per item; files that do not conflict are
+  never rewritten, and the report names every conflict afterwards.
+- **Per-instance launch arguments.** JVM arguments, game arguments, memory, the Java executable and the
+  graphics backend (`default` / `opengl` / `vulkan`) are set per instance, each field falling back on
+  its own to the global setting and then the factory default. The CLI reads the same resolved values.
+
+## Downloads
+
+Asset names are `___`, underscore separated — the rule
+`packaging/make_artifacts.py::asset_stem()` applies:
+
+| Platform | Asset | Notes |
+| --- | --- | --- |
+| Windows 10/11 x64 | `unlucky-launcher_{{VERSION}}_windows_x64.exe` | single exe, double-click to run; this is also what you run on ARM64 Windows (x64 emulation) |
+| Linux x64 | `unlucky-launcher_{{VERSION}}_linux_x64.tar.gz` | one archive, one top-level directory holding the binary plus `LICENSE` / `NOTICE` / `README.md`; needs glibc 2.35+ and the usual X11/Wayland + fontconfig stack |
+
+**Windows ARM64 is not part of this release.** CI still builds it on a native `windows-11-arm` runner (Windows 11
+Arm64 with Visual Studio 2026), but the build has not delivered an artifact yet, so
+`unlucky-launcher_{{VERSION}}_windows_arm64.exe` is deliberately kept out of the download list and out of
+`SHA256SUMS.txt` instead of handing out a build nobody has verified. Worth stating plainly: every ARM64 failure
+so far happened in a **pre-build toolchain probe** that guessed whether the SDK's ARM64 import libraries were
+present and aborted before `cargo build` ever ran — the compiler and linker have not been heard from yet. That
+probe is now evidence-only (it prints what it sees and never decides the job), so the next CI run is the first
+one that can actually answer the question. ARM64 rejoins this table as soon as a run produces its artifact (one
+line in the workflow's `PUBLISH_SLOTS`, guarded on both sides by `packaging/check_publish_slots.py`).
+
+**Linux ARM64 is built but not published, and it has no runtime evidence yet.** `linux-arm64` joined the default
+build matrix in this release (native `ubuntu-22.04-arm`, same glibc 2.35 floor as x64), so the artifact exists as
+build evidence, but nothing has ever run it on ARM64 hardware — not one frame. It stays out of the download list
+and out of `SHA256SUMS.txt` until an ARM64 machine renders a frame and the theme/backend log lines come out as
+expected; that run is the single unlock condition, and copying a build nobody executed is exactly what this list
+is meant to prevent. The publish job prunes that artifact with an explicit "not published" warning rather than
+dropping it quietly.
+
+**macOS is not built by the release workflow at all.** The Apple Silicon and Intel slots never got past a manual
+probe, so no build minutes are spent on them and nothing unverified is handed out. They stay out of the download
+list and out of `SHA256SUMS.txt`; a manual workflow run can build all six slots for evidence, but the probe slots
+are never published. The support matrix below marks those slots accordingly.
+
+The Windows asset is a bare `.exe`, so `LICENSE`, `NOTICE` and `README.md` are attached to this release
+next to it: the license terms travel with every download. The Linux archive unpacks to one top-level directory
+of the same name holding the binary plus those three documents.
+
+## Command line
+
+Each published slot also ships the command line as its own small bare asset,
+`ull_{{VERSION}}__` (`.exe` on Windows):
+
+```powershell
+.\ull_{{VERSION}}_windows_x64.exe instances list   # servers and CI: no graphics stack needed
+```
+
+```bash
+./ull_{{VERSION}}_linux_x64 instances list         # same binary shape on Linux, no display needed
+```
+
+`ull` runs `instances`, `install`, `pack import`, `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 a desktop machine does not need `ull`.
+
+## Updating
+
+The launcher reads `releases/latest/download/manifest.json` on startup (switchable: `update.auto_check`)
+and shows four distinct outcomes: up to date, an update is available, a newer version exists but ships no
+artifact for this platform, or the check itself failed. `ull update check` prints the same verdict, and
+`ull update apply` downloads, verifies SHA256 and swaps the binary atomically, rolling back if the swap
+fails. Nothing installs without you asking for it.
+
+## Support matrix
+
+Published = shipped as a download of **this** release, listed in `SHA256SUMS.txt`.
+
+| Platform | Status in this release | Level | Runtime requirements |
+| --- | --- | --- | --- |
+| Windows 10/11 x64 | **published** | first class | nothing beyond the OS (UCRT is part of Win10+) |
+| Linux x64, X11 | **published** | first class | glibc 2.35+ (`libxkbcommon`, `fontconfig`, `libGL` or the software renderer, `libxcb`) |
+| Linux x64, Wayland | **published** (same archive, Wayland path unverified) | supported | the same archive; `wayland-client` + `libxkbcommon`, plus the X11 set for XWayland apps |
+| Windows 11 ARM64 | not published (build evidence only) | first class (launcher artifact) | nothing extra; the launcher runs natively, the game itself runs through the OS x64 emulation layer with an x64 JDK |
+| Linux arm64 | built, not published (no runtime evidence) | first class (unverified) | glibc 2.35+ (native `ubuntu-22.04-arm`, same floor as x64), `libxkbcommon`, `fontconfig`, `libGL`, `libxcb` / `wayland-client` |
+| macOS 12+ Apple Silicon | not built (unverified) | first class (unverified) | nothing; unsigned build, needs the Gatekeeper workaround |
+| macOS 12+ Intel | not built (unverified) | first class (unverified) | same as above |
+| Windows 8.1/8/7 | not built | unsupported | the baseline is Windows 10 |
+| Android — Termux + X11 | not built (no CI slot) | experimental, not promised | CLI and GUI from source only; GUI verified on-device twice: CPU software rendering and self-built Mesa/turnip GPU acceleration (see `packaging/docs/termux-glibc-build.md` and `README.termux.md`) |
+
+Two slots are published this release: `windows-x64` and `linux-x64`. Linux x64 is not a claim taken on faith — the
+release artifact itself was started on a Linux machine, opened a real window under a real display server, rendered a
+frame (PNG asserted non-blank) and printed the expected `[theme]` and `[backend] final=… result=started` lines, and
+the release build now carries the same check as a per-slot CI gate (`packaging/docs/linux-evidence.md` has the raw
+output). What that does **not** cover: dragging/resizing and font metrics / CJK shaping on a real desktop session.
+Whole-window transparency and rounded corners have no code path on Linux at all (transparency needs a native window
+handle the app does not get there; corners are delegated to the desktop compositor), so they are not "unverified" —
+they are not applicable. Nothing at all is known about Linux ARM64: no ARM64 machine has run the binary yet, which is
+why that row stays unpublished.
+
+Both arm64 rows are formal matrix slots, not the experimental Termux path, and Linux arm64 is not published until
+someone runs it on real hardware — a manual all-slots run builds it today, and one real frame on an ARM64 machine is
+the unlock. The rows above and the matrix table in `packaging/docs/compliance-support-boundaries.md` §9 are the same
+list — change one, change the other.
+
+## Install
+
+**Windows** — put the `.exe` anywhere and run it. `_windows_x64.exe` is the only Windows asset in this
+release, and it is also what you run on ARM64 Windows (the OS runs it through its x64 emulation layer).
+The first run creates `.ULL/` and `.minecraft/` next to the exe (portable is the default data mode); the
+per-user `%APPDATA%\ULL` plus `%APPDATA%\.minecraft`, or a custom root, are selectable instead.
+
+**Linux x64** — unpack the archive and run the binary inside it; nothing is installed system-wide:
+
+```bash
+tar -xzf unlucky-launcher_{{VERSION}}_linux_x64.tar.gz
+cd unlucky-launcher_{{VERSION}}_linux_x64
+./unlucky-launcher                 # X11 or Wayland; --software-renderer forces the CPU rasteriser
+```
+
+It needs glibc 2.35+ (the slot is built on Ubuntu 22.04, so that is the floor), `libxkbcommon`, `fontconfig`
+and `libGL` — or `--software-renderer` if there is no usable GPU adapter. On Debian/Ubuntu:
+
+```bash
+sudo apt-get install libxkbcommon0 libfontconfig1 libgl1 libx11-6 libxcursor1 libxrandr2 libxi6
+```
+
+The bare `ull_{{VERSION}}_linux_x64` next to the archive runs on a machine with no display at all.
+
+Linux arm64 and macOS are not part of this release; their asset names are already fixed by the same rule
+(`unlucky-launcher_{{VERSION}}_linux_arm64.tar.gz`, `_macos_arm64`, `_macos_x64`) so the links will not change
+shape when those slots open.
+
+## 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; `--software-renderer` (or its equivalent `--renderer=cpu`) forces that path.
+
+## Verify the download
+
+`SHA256SUMS.txt` lists exactly the assets attached to this release (Windows x64 and Linux x64, GUI + `ull` each), and
+`sha256sum -c` checks the ones you actually downloaded:
+
+```bash
+sha256sum -c SHA256SUMS.txt --ignore-missing   # Linux / WSL
+shasum -a 256 -c SHA256SUMS.txt                # macOS (sha256sum is not bundled)
+Get-FileHash .\unlucky-launcher_{{VERSION}}_windows_x64.exe -Algorithm SHA256   # Windows PowerShell
+```
+
+```
+{{SUMS}}
+```
+
+## Known limitations of this build
+
+- Microsoft (MSA) sign-in works out of the box: this build carries the Azure public client id it needs
+  (a public client id, not a credential — it ships inside the binary), so there is nothing to configure
+  before signing in. Setting `ULL_MSA_CLIENT_ID=` before launching still overrides it; the variable
+  is read at startup, so restart the launcher after changing it. A build with no id anywhere stops
+  before any network call, and the GUI banner says so plainly: the title "Microsoft sign-in is not
+  configured", a body naming `ULL_MSA_CLIENT_ID=` (set it, or build with it, then restart) and
+  `Code: msa_not_configured`, with no Retry button. Every other sign-in failure keeps the generic
+  banner plus its own `Code:` line, with the full reason only in the launcher log. `ull accounts add
+  msa` prints the same fix on the command line. Offline profiles and authlib-injector servers need no
+  id.
+- Binaries are not code-signed / notarized yet: Windows SmartScreen and macOS Gatekeeper warn on first
+  launch. The checksums above are the integrity reference for now.
+- **Linux x64 is verified, not "finished".** The published archive was built on Ubuntu 22.04 and started under a
+  real display server (WSLg) where it opened a window, rendered a non-blank first frame and printed its theme and
+  backend lines; CI repeats that with Xvfb on every release. What nobody has looked at yet on a real desktop
+  distribution: dragging and resizing, font metrics and CJK shaping. Whole-window transparency and rounded corners
+  are not "unverified" on Linux — they are not code paths there: transparency needs a native window handle the app
+  does not get (`hwnd=none`), and corners are delegated to the desktop compositor (`corner=policy=system`).
+- **On Linux the in-app update does not install itself.** The published Linux asset is a `.tar.gz`, and
+  `ull update apply` only self-replaces the portable single-file `.exe` form — on Linux it refuses with an explicit
+  message naming `portable-zip` instead of half-installing (see `crates/core/src/update/job.rs`). Updating on Linux
+  means downloading the new archive and unpacking it over the old copy; the update check itself (version + channel)
+  works normally.
+- **Linux ARM64 has no runtime evidence at all.** It compiles, and that is the whole story; the artifact is not
+  attached to this release.
+- When the macOS slot ships it is 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 in `NOTICE`. Not affiliated with Mojang or Microsoft; no game files ship.
+
+## UI framework in this build
+
+Every asset here is built from the iced UI (`crates/app-iced`, iced 0.14, MIT); no other UI framework is
+linked into it.
diff --git a/packaging/release_marker.py b/packaging/release_marker.py
new file mode 100644
index 0000000..2bc52cf
--- /dev/null
+++ b/packaging/release_marker.py
@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+"""发布标记（`gh release ... --prerelease`）的**唯一定义处**（M163）。
+
+# 三种触发方式各创建什么
+
+| 触发 | `github.event.inputs.prerelease` | 新建 Release（create） | 已存在 Release（edit） |
+| --- | --- | --- | --- |
+| push tag `v*`（以及它的 Re-run） | 空串（该字段不存在） | **稳定版**：不带任何标记 | 不传标记（**不碰**） |
+| `workflow_dispatch` + `prerelease=true` | `"true"` | 预发布 | 显式改成预发布 |
+| `workflow_dispatch` + `prerelease=false` | `"false"` | 稳定版 | 显式改成稳定版 |
+
+空串必须是稳定版：GitHub 的 `releases/latest` **只指向非 prerelease 的最新 Release**，而自更新
+客户端把清单地址钉在 `releases/latest/download/manifest.json`（D50）。v0.2.2 之前 push tag 默认打
+`--prerelease`，于是 latest 一直 404、更新通道取不到清单——M163 修的就是这条语义。
+
+edit 那一列的空串是「不碰」而不是「改成稳定版」：同 tag 重跑会落到 edit 分支，而用户手工把某个
+Release 提成稳定版之后，重跑**不应该**把它翻回预发布。
+
+# 流水线里唯一的走法
+
+    python3 packaging/release_marker.py --emit-bash --prerelease "${PRERELEASE:-}" > "$marks"
+    source "$marks"          # 得到 create_mark=(...) / edit_mark=(...)
+
+先落文件再 `source`，而不是 `source <(...)`：非法的 `prerelease` 取值必须让这一步**当场红**
+（`set -e` 只认前一条命令的退出码，进程替换里的失败会被吞掉）。
+
+守门在 `packaging/check_release_semantics.py`：它调本文件的 `marks()` 逐条对表，再真的把
+`--emit-bash` 灌进 bash 看展开出来的两个数组。本文件的 `--self-test` 只查自己这一层。
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+#: 打预发布标记。
+PRERELEASE = "--prerelease"
+#: 显式摘掉预发布标记（`gh release edit` 用；`create` 不带标记就已经是稳定版）。
+STABLE = "--prerelease=false"
+
+#: （触发方式，输入原始值，create 标记，edit 标记）——本仓对外承诺的那张表，逐行可对。
+CASES: tuple[tuple[str, str, tuple[str, ...], tuple[str, ...]], ...] = (
+    ("push tag v*（含其 Re-run）", "", (), ()),
+    ("workflow_dispatch + prerelease=true", "true", (PRERELEASE,), (PRERELEASE,)),
+    ("workflow_dispatch + prerelease=false", "false", (), (STABLE,)),
+)
+
+
+def marks(raw: str) -> tuple[tuple[str, ...], tuple[str, ...]]:
+    """`github.event.inputs.prerelease` 的原始字符串 → (create 标记, edit 标记)。
+
+    只认三种取值（空串 / `"true"` / `"false"`），其它一律抛 :class:`ValueError`——发布流水线
+    宁可红在一次错误的 dispatch 输入上，也不要把一个自己没预期的值当成「稳定版」发出去。
+    """
+    value = (raw or "").strip()
+    if value == "":
+        return (), ()
+    if value == "true":
+        return (PRERELEASE,), (PRERELEASE,)
+    if value == "false":
+        return (), (STABLE,)
+    raise ValueError(
+        f"非预期的 github.event.inputs.prerelease 取值：{raw!r}（只认 空串 / true / false）"
+    )
+
+
+def bash_snippet(raw: str) -> str:
+    """把两个数组渲染成可直接 `source` 的 bash 片段。"""
+    create, edit = marks(raw)
+    return (
+        "# 由 packaging/release_marker.py 生成，别手改：标记的全部判据都在那个脚本里。\n"
+        f"create_mark=({' '.join(create)})\n"
+        f"edit_mark=({' '.join(edit)})\n"
+    )
+
+
+def table() -> str:
+    """把 :data:`CASES` 渲染成 markdown 表（`--table`；报告与文档直接抄它）。"""
+
+    def cell(flags: tuple[str, ...], empty: str) -> str:
+        return "、".join(f"`{flag}`" for flag in flags) if flags else empty
+
+    rows = ["| 触发 | `prerelease` 输入 | create | edit |", "| --- | --- | --- | --- |"]
+    for trigger, raw, create, edit in CASES:
+        shown = "空串" if raw == "" else f'`"{raw}"`'
+        rows.append(f"| {trigger} | {shown} | {cell(create, '（不带标记）')} | {cell(edit, '不碰标记')} |")
+    return "\n".join(rows)
+
+
+def self_test() -> int:
+    """本文件自己这一层的断言（完整守门见 check_release_semantics.py）。"""
+    failures: list[str] = []
+
+    for trigger, raw, create, edit in CASES:
+        got = marks(raw)
+        if got != (create, edit):
+            failures.append(f"{trigger}：表里写 {(create, edit)}，marks({raw!r}) 给的是 {got}")
+
+    # 最关键的一条：push tag（空串）的新建路径**不许**带预发布标记。它是 v0.2.2 至今
+    # `releases/latest` 404 的根因，任何一次重构都不许把它带回来。
+    push_create, push_edit = marks("")
+    if PRERELEASE in push_create:
+        failures.append(f"push tag 的 create 标记里出现了 {PRERELEASE}：稳定通道会一直是 404")
+    if push_edit:
+        failures.append(f"push tag 的 edit 标记应为「不碰」，实际是 {push_edit}")
+
+    # dispatch 显式 false 时，新建同样是稳定版（create 不需要 `--prerelease=false`：不带就已经是了）。
+    false_create, false_edit = marks("false")
+    if PRERELEASE in false_create:
+        failures.append(f"dispatch prerelease=false 的 create 标记里出现了 {PRERELEASE}")
+
+    # 非法值必须炸，不许静默当稳定版（`True` 是 Python 的写法，Actions 的 boolean 输入给的是小写）。
+    for bad in ("yes", "1", "TRUE", "False", "0", "prerelease"):
+        try:
+            marks(bad)
+        except ValueError:
+            continue
+        failures.append(f"非法取值 {bad!r} 被当成了合法输入：{marks(bad)}")
+
+    if failures:
+        for item in failures:
+            print(f"::error::release_marker 自检失败：{item}", file=sys.stderr)
+        return 1
+    print("OK: release_marker 标记表自检通过（push tag → 稳定版）")
+    print(table())
+    return 0
+
+
+def main(argv: list[str]) -> int:
+    # Windows 控制台是 GBK：本文件的输出里有中文与箭头，缺了这行会在打印时抛
+    # UnicodeEncodeError（与判据无关的崩溃）。CI 是 UTF-8，不受影响。
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(errors="backslashreplace")
+
+    parser = argparse.ArgumentParser(
+        description="发布标记（--prerelease）的唯一定义处：打印 gh release 要带的参数。"
+    )
+    parser.add_argument(
+        "--prerelease",
+        default="",
+        metavar="VALUE",
+        help='github.event.inputs.prerelease 的原值：空串 / "true" / "false"',
+    )
+    group = parser.add_mutually_exclusive_group()
+    group.add_argument(
+        "--emit-bash",
+        action="store_true",
+        help="打印可直接 source 的 bash 片段（create_mark / edit_mark 两个数组）",
+    )
+    group.add_argument("--table", action="store_true", help="打印触发方式 ↔ 标记的对照表")
+    group.add_argument("--self-test", action="store_true", help="只查本文件这一层的断言")
+    args = parser.parse_args(argv)
+
+    if args.self_test:
+        return self_test()
+    if args.table:
+        print(table())
+        return 0
+
+    try:
+        sys.stdout.write(bash_snippet(args.prerelease))
+    except ValueError as error:
+        # 走 stderr：stdout 在这种情况下会被重定向进 marks 文件，注解会丢。
+        print(f"::error::{error}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))
diff --git a/packaging/sign_manifest.py b/packaging/sign_manifest.py
new file mode 100644
index 0000000..0984304
--- /dev/null
+++ b/packaging/sign_manifest.py
@@ -0,0 +1,298 @@
+#!/usr/bin/env python3
+"""Sign / verify the update manifest, and check the pinned keyring (M190).
+
+Why Ed25519 + a **detached** `.sig`: the manifest's `sha256` only says "the package matches the
+manifest"; it says nothing about who wrote the manifest. A signature over the manifest's *exact
+bytes* answers that, and a separate file avoids JSON canonicalisation games (any byte change
+breaks the signature).
+
+Key discipline: the **private key** lives only in the repository Secret
+`ULL_MANIFEST_SIGNING_KEY` (never in git, logs or artifacts); the **public key** is pinned
+*inside the binary* — `crates/core/src/update/trust.rs`, between the `>>> PINNED-KEYS >>>` /
+`<<< PINNED-KEYS <<<` markers. `--check-pinned-keyring` fails the release when the secret's key
+is not pinned (a release signed with a key clients do not trust is worse than no release).
+Manual: `packaging/docs/signing.md`.
+
+Usage: `--generate-key [--key-id K]` / `--sign dist/manifest.json`（钥从环境变量
+`ULL_MANIFEST_SIGNING_KEY` 取）/ `--check-pinned-keyring`（钥必须已钉住）/ `--verify-pinned
+dist/manifest.json`（用 trust.rs 里钉的公钥回验产出，复现客户端判据）/ `--self-test`。
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+FORMAT = 1
+ALG = "ed25519"
+KEY_ENV = "ULL_MANIFEST_SIGNING_KEY"
+SIG_SUFFIX = ".sig"
+TRUST_RS = Path(__file__).resolve().parent.parent / "crates/core/src/update/trust.rs"
+PIN_BEGIN = ">>> PINNED-KEYS >>>"
+PIN_END = "<<< PINNED-KEYS <<<"
+KID_RE = re.compile(r'key_id:\s*"([^"]+)"\s*,\s*public_key_hex:\s*"([0-9a-fA-F]{64})"')
+# Ed25519 的参考实现搬到了 `packaging/ed25519_ref.py`（M190 r1：本文件贴着 400 行红线）。
+# 目的与路径都写在那边的文件头：发布侧签名必须零第三方依赖，而仓里验签用的是 ed25519-dalek ——
+# 两套实现互相独立，`--self-test` 用 RFC 8032 的同一组向量把两边各自钉住。
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from ed25519_ref import ALG, sign, verify, public_key  # noqa: E402
+
+def load_key(text: str) -> tuple[str, bytes]:
+    """Parse the secret JSON (`{"key_id":…,"seed_hex":…}`) or a bare 64-char hex seed."""
+    text = text.strip()
+    try:
+        payload = json.loads(text)
+    except json.JSONDecodeError:
+        payload = None
+    if isinstance(payload, dict):
+        key_id = str(payload.get("key_id", "")).strip()
+        seed_hex = str(payload.get("seed_hex", "")).strip()
+    else:
+        key_id, seed_hex = "", text
+    if not key_id:
+        raise SystemExit("error: 密钥缺少 `key_id`（清单签名要靠它查信任表）")
+    try:
+        seed = bytes.fromhex(seed_hex)
+    except ValueError as error:
+        raise SystemExit(f"error: `seed_hex` 不是十六进制（{error}）") from error
+    if len(seed) != 32:
+        raise SystemExit(f"error: `seed_hex` 必须 32 字节（实际 {len(seed)}）")
+    return key_id, seed
+
+def key_from_env_or_arg(path: str | None) -> tuple[str, bytes]:
+    if path:
+        secret = Path(path).read_text(encoding="utf-8")
+    else:
+        secret = os.environ.get(KEY_ENV, "")
+        if not secret.strip():
+            raise SystemExit(
+                f"error: 没有签名密钥：设环境变量 {KEY_ENV}（内容 = --generate-key 打出来的那一行 JSON），"
+                "或显式给 --key <文件>。**绝不**把私钥写进仓库/日志/产物。"
+            )
+    return load_key(secret)
+
+def pinned_keys(trust_text: str) -> list[tuple[str, str]]:
+    """Extract `(key_id, public_key_hex)` pairs between the PINNED-KEYS markers."""
+    begin = trust_text.find(PIN_BEGIN)
+    end = trust_text.find(PIN_END)
+    if begin < 0 or end < 0 or end < begin:
+        raise SystemExit(f"error: {TRUST_RS} 里找不到 {PIN_BEGIN} / {PIN_END} 标记")
+    return KID_RE.findall(trust_text[begin:end])
+
+
+
+def do_generate_key(key_id: str) -> int:
+    seed = os.urandom(32)
+    pk = public_key(seed)
+    pk_hex = pk.hex()
+    if not verify(pk, b"self-check", sign(seed, b"self-check")):
+        print("error: 自己签自己验不过——不要用这把钥", file=sys.stderr)
+        return 1
+    secret = json.dumps({"key_id": key_id, "seed_hex": seed.hex()}, ensure_ascii=False)
+    print("# ① 私钥（**只**贴进仓库 Secret " + KEY_ENV + "，别写进任何文件/日志/提交）：")
+    print(secret)
+    print("# ② 公钥（贴进 crates/core/src/update/trust.rs 的 PINNED-KEYS 标记之间）：")
+    print(f'    PinnedKey {{ key_id: "{key_id}", public_key_hex: "{pk_hex}" }},')
+    print(f"# 公钥十六进制：{pk_hex}")
+    return 0
+
+def do_sign(manifest: Path, key_path: str | None, out: Path | None, key_id_override: str | None) -> int:
+    if not manifest.is_file():
+        print(f"error: 没有清单文件 {manifest}", file=sys.stderr)
+        return 1
+    raw = manifest.read_bytes()
+    # 签的必须是**能解析**的清单：签一串垃圾只会把事故推迟到用户机器上。
+    try:
+        parsed = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as error:
+        print(f"error: {manifest} 不是合法 JSON（{error}）", file=sys.stderr)
+        return 1
+    if not isinstance(parsed, dict) or "channel" not in parsed or "releases" not in parsed:
+        print(f"error: {manifest} 不像发布清单（缺 channel/releases）", file=sys.stderr)
+        return 1
+    key_id, seed = key_from_env_or_arg(key_path)
+    if key_id_override:
+        key_id = key_id_override
+    signature = sign(seed, raw)
+    if not verify(public_key(seed), raw, signature):
+        print("error: 签出来的签名自己验不过（实现有问题），拒绝落盘", file=sys.stderr)
+        return 1
+    envelope = {
+        "format": FORMAT,
+        "signatures": [
+            {
+                "alg": ALG,
+                "key_id": key_id,
+                "sig": signature.hex(),
+                "manifest_sha256": hashlib.sha256(raw).hexdigest(),
+            }
+        ],
+    }
+    out = out or manifest.with_name(manifest.name + SIG_SUFFIX)
+    out.write_text(json.dumps(envelope, ensure_ascii=False, indent=2) + "\n", encoding="utf-8", newline="\n")
+    print(f"signed: {manifest} → {out}")
+    print(f"  key_id          = {key_id}")
+    print(f"  public_key      = {public_key(seed).hex()}")
+    print(f"  manifest_sha256 = {envelope['signatures'][0]['manifest_sha256']}")
+    return 0
+
+def do_verify(manifest: Path, sig: Path, public_key_hex: str) -> int:
+    raw = manifest.read_bytes()
+    envelope = json.loads(sig.read_text(encoding="utf-8"))
+    pk = bytes.fromhex(public_key_hex)
+    for item in envelope.get("signatures", []):
+        if item.get("alg") != ALG:
+            continue
+        if verify(pk, raw, bytes.fromhex(item.get("sig", ""))):
+            print(f"ok: {sig} 里的签名（key_id={item.get('key_id')}）通过")
+            return 0
+    print("error: 没有任何一条签名能验过", file=sys.stderr)
+    return 1
+
+def do_check_pinned(key_path: str | None) -> int:
+    key_id, seed = key_from_env_or_arg(key_path)
+    pk_hex = public_key(seed).hex()
+    keys = pinned_keys(TRUST_RS.read_text(encoding="utf-8"))
+    if not keys:
+        # 「说人话的红」：因为什么、缺什么、怎么补，一行一行写清楚（不涉密，只回显公钥）。
+        print("error: 信任表是空的（fail-closed）：客户端一把公钥都没有，任何清单都验不过，所以拒绝发布。", file=sys.stderr)
+        print(f"error:   本次签名钥 = key_id {key_id} / 公钥 {pk_hex}", file=sys.stderr)
+        print("error:   补法：把这行贴进 crates/core/src/update/trust.rs 的 PINNED-KEYS 标记之间 ——", file=sys.stderr)
+        print(f'error:       PinnedKey {{ key_id: "{key_id}", public_key_hex: "{pk_hex}" }},', file=sys.stderr)
+        print("error:   手册：packaging/docs/signing.md §3", file=sys.stderr)
+        return 1
+    for pinned_id, pinned_hex in keys:
+        if pinned_hex.lower() == pk_hex:
+            print(f"ok: 签名钥 {key_id} 已被钉住（trust.rs 里叫 {pinned_id}）")
+            if pinned_id != key_id:
+                print(
+                    f"warning: 同一个公钥在 trust.rs 里叫 {pinned_id}、密钥文件里叫 {key_id}；"
+                    "清单会带后者，客户端按**公钥字节**验签，所以两种写法都能过（但建议改名对齐）",
+                    file=sys.stderr,
+                )
+            return 0
+    pinned_ids = [k[0] for k in keys]
+    print(
+        f"error: 签名钥（key_id={key_id} / 公钥={pk_hex}）不在信任表里 —— 签出来的清单没有任何客户端会认，所以拒绝发布。",
+        file=sys.stderr,
+    )
+    print(f"error:   trust.rs 现在钉的是：{pinned_ids}", file=sys.stderr)
+    for pinned_id, pinned_hex in keys:
+        print(f"error:     {pinned_id} = {pinned_hex}", file=sys.stderr)
+    print("error:   二选一：", file=sys.stderr)
+    print("error:   ① 用已钉住的那把钥签（换回对应的 Secret）；或", file=sys.stderr)
+    print(
+        "error:   ② 换钥：把上面的公钥按「旧钥签新钥」贴进 crates/core/src/update/trust.rs 的 PINNED-KEYS 之间，"
+        "并让本次清单同时带旧钥签名",
+        file=sys.stderr,
+    )
+    print("error:   手册：packaging/docs/signing.md §3/§5", file=sys.stderr)
+    return 1
+
+def do_verify_pinned(manifest: Path) -> int:
+    """用 trust.rs 里钉住的公钥回验 `.sig` —— 复现「客户端会怎么判」，不需要私钥。"""
+    keys = pinned_keys(TRUST_RS.read_text(encoding="utf-8"))
+    if not keys:
+        print("error: 信任表是空的，无从回验（先钉公钥，见 --check-pinned-keyring）", file=sys.stderr)
+        return 1
+    sig_path = manifest.with_name(manifest.name + SIG_SUFFIX)
+    if not sig_path.is_file():
+        print(f"error: 没有签名文件 {sig_path}", file=sys.stderr)
+        return 1
+    raw = manifest.read_bytes()
+    envelope = json.loads(sig_path.read_text(encoding="utf-8"))
+    for item in envelope.get("signatures", []):
+        if item.get("alg") != ALG:
+            continue
+        try:
+            signature = bytes.fromhex(item.get("sig", ""))
+        except ValueError:
+            continue
+        for pinned_id, pinned_hex in keys:
+            if verify(bytes.fromhex(pinned_hex), raw, signature):
+                print(f"ok: {sig_path.name} 用钉住的公钥 {pinned_id} 能验过（客户端会接受）")
+                return 0
+    print(
+        "error: 拿 trust.rs 里钉住的公钥回验不过 —— 这份 Release 的用户会全部拒装。别发版",
+        file=sys.stderr,
+    )
+    return 1
+
+
+def do_self_test() -> int:
+    vectors = [
+        ("9d61b19deffd5a60ba844af492ec2cc44449c5697b326919703bac031cae7f60", "d75a980182b10ab7d54bfed3c964073a0ee172f3daa62325af021a68f707511a", "",
+         "e5564300c360ac729086e2cc806e828a84877f1eb8e5d974d873e065224901555fb8821590a33bacc61e39701cf9b46bd25bf5f0595bbe24655141438e7a100b"),
+        ("4ccd089b28ff96da9db6c346ec114e0f5b8a319f35aba624da8cf6ed4fb8a6fb", "3d4017c3e843895a92b70aa74d1b7ebc9c982ccf2ec4968cc0cd55f12af4660c", "72",
+         "92a009a9f0d4cab8720e820b5f642540a2b27b5416503f8fb3762223ebdb69da085ac1e43e15996e458f3613d0f11d8c387b2eaeb4302aeeb00d291612bb0c00"),
+        ("c5aa8df43f9f837bedb7442f31dcb7b166d38535076f094b85ce3a2e0b4458f7", "fc51cd8e6218a1a38da47ed00230f0580816ed13ba3303ac5deb911548908025", "af82",
+         "6291d657deec24024827e69c3abe01a30ce548a284743a445e3680d7db5ac3ac18ff9b538d16f290ae67f760984dc6594a7c15e9716ed28dc027beceea1ec40a"),
+    ]
+    failures = 0
+    for index, (seed_hex, pk_hex, message_hex, sig_hex) in enumerate(vectors, 1):
+        seed, pk, message = bytes.fromhex(seed_hex), bytes.fromhex(pk_hex), bytes.fromhex(message_hex)
+        if public_key(seed).hex() != pk_hex:
+            print(f"FAIL vector {index}: public key mismatch", file=sys.stderr)
+            failures += 1
+        if sign(seed, message).hex() != sig_hex:
+            print(f"FAIL vector {index}: signature mismatch", file=sys.stderr)
+            failures += 1
+        if not verify(pk, message, bytes.fromhex(sig_hex)):
+            print(f"FAIL vector {index}: verify rejected", file=sys.stderr)
+            failures += 1
+        tampered = bytearray(message)
+        tampered.append(0)
+        if verify(pk, bytes(tampered), bytes.fromhex(sig_hex)):
+            print(f"FAIL vector {index}: tampered message still verifies", file=sys.stderr)
+            failures += 1
+    # 标记解析：信任表解析器必须在示例上命中一对，且在空表上返回空。
+    sample = f'{PIN_BEGIN}\n    PinnedKey {{ key_id: "k1", public_key_hex: "{"ab" * 32}" }},\n{PIN_END}'
+    if pinned_keys(sample) != [("k1", "ab" * 32)]:
+        print("FAIL: pinned_keys() 没解析出示例条目", file=sys.stderr)
+        failures += 1
+    if pinned_keys(f"{PIN_BEGIN}\n{PIN_END}") != []:
+        print("FAIL: pinned_keys() 在空表上应返回空", file=sys.stderr)
+        failures += 1
+    print("self-test:", "ok" if failures == 0 else f"{failures} 处失败")
+    return 0 if failures == 0 else 1
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="更新清单的 Ed25519 签名/验签与信任表检查（M190）")
+    parser.add_argument("--generate-key", action="store_true", help="生成一把新钥（打印 Secret 与 PinnedKey 片段）")
+    parser.add_argument("--key-id", default="ull-release", help="生成/签名时用的 key_id")
+    parser.add_argument("--sign", metavar="MANIFEST", type=Path, help="签这份清单（产出 <清单>.sig）")
+    parser.add_argument("--out", metavar="SIG", type=Path, help="签名输出路径（默认 <清单>.sig）")
+    parser.add_argument("--key", metavar="FILE", help=f"密钥文件（不给则读环境变量 {KEY_ENV}）")
+    parser.add_argument("--verify", nargs=2, metavar=("MANIFEST", "SIG"), help="手工验一份签名")
+    parser.add_argument("--public-key", metavar="HEX", help="--verify 用的公钥")
+    parser.add_argument("--check-pinned-keyring", action="store_true", help="检查密钥是否已被钉进 trust.rs")
+    parser.add_argument("--verify-pinned", metavar="MANIFEST", type=Path, help="用 trust.rs 里钉的公钥回验产出")
+    parser.add_argument("--self-test", action="store_true", help="跑 RFC 8032 向量与解析器自检")
+    args = parser.parse_args(argv)
+
+    if args.self_test:
+        return do_self_test()
+    if args.generate_key:
+        return do_generate_key(args.key_id)
+    if args.sign:
+        return do_sign(args.sign, args.key, args.out, args.key_id if args.key_id != "ull-release" else None)
+    if args.verify:
+        if not args.public_key:
+            print("error: --verify 需要 --public-key", file=sys.stderr)
+            return 1
+        return do_verify(Path(args.verify[0]), Path(args.verify[1]), args.public_key)
+    if args.check_pinned_keyring:
+        return do_check_pinned(args.key)
+    if args.verify_pinned:
+        return do_verify_pinned(args.verify_pinned)
+    parser.print_help()
+    return 2
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/packaging/tests/gpu_shot_ci_expr.py b/packaging/tests/gpu_shot_ci_expr.py
new file mode 100644
index 0000000..f0b8bb5
--- /dev/null
+++ b/packaging/tests/gpu_shot_ci_expr.py
@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+"""GitHub `if:` 表达式的小求值器（M253 / r2 复审返工，判据 3 用）。
+
+为什么需要它：字符串存在性判据被两轮复审证伪过 —— `if: needs.probe.outputs.available == 'true' || always()`
+用 `in` 判照样绿，`if: true` 也绿。所以这里**真求值**：给 `needs.probe.outputs.available` 分别取
+`'true'` / `'false'` / `''`，门必须分别判真 / 假 / 假 —— 门到底还挂不挂，由语义决定，不由子串决定。
+
+**只认一小撮语法，其余一律抛 `ConditionError`（调用方按红处理，宁可假红）**：
+`==` / `!=` / `&&` / `||` / 括号 / 单引号字符串 / 数字 / `needs..outputs.<名>` / `true|false|null` /
+`always()|success()|failure()|cancelled()`（后四个按「假定上游成功」取常量）。**不支持 `!`**：GitHub 与
+Python 的 `!` 优先级不同，认不出比误判安全。不是 GitHub 语义的替身，是它的一个保守子集。
+"""
+
+from __future__ import annotations
+
+import re
+
+AVAILABLE_IDENT = "needs.probe.outputs.available"
+CALL_FUNCS = {"always": True, "success": True, "failure": False, "cancelled": False}
+_TOKEN_RE = re.compile(r"(?P'[^']*')|(?P\d+)|(?P[A-Za-z_][\w.\-]*)|(?P==|!=|&&|\|\||[()!])")
+
+
+class ConditionError(Exception):
+    """`if:` 表达式认不出 —— 认不出即判红，绝不默认放过。"""
+
+
+def evaluate_condition(raw, available: str) -> bool:
+    """把 GitHub 的 `if:` 表达式求值。只认一小撮语法，其余抛 `ConditionError`（= 判红）。"""
+    text = str(raw).strip()
+    if text.startswith("${{") and text.endswith("}}"):
+        text = text[3:-2].strip()
+    for name, value in CALL_FUNCS.items():
+        text = re.sub(rf"\b{name}\s*\(\s*\)", "true" if value else "false", text)
+    if re.search(r"\b(" + "|".join(CALL_FUNCS) + r")\s*\(", text):
+        raise ConditionError("函数只支持不带参数的形式")
+    parts: list[str] = []
+    pos = 0
+    while pos < len(text):
+        if text[pos].isspace():
+            pos += 1
+            continue
+        match = _TOKEN_RE.match(text, pos)
+        if not match:
+            raise ConditionError(f"认不出的字符 {text[pos]!r}")
+        pos = match.end()
+        token = match.group()
+        if match.lastgroup in ("string", "number"):
+            parts.append(token)
+        elif match.lastgroup == "ident":
+            if token == AVAILABLE_IDENT:
+                parts.append("__available")
+            elif token in ("true", "false", "null"):
+                parts.append({"true": "True", "false": "False", "null": "None"}[token])
+            else:
+                raise ConditionError(f"认不出的标识符 `{token}`")
+        else:
+            if token == "!":
+                raise ConditionError("不支持 `!`（GitHub 与 Python 的优先级不同，宁可认不出）")
+            parts.append({"&&": "and", "||": "or"}.get(token, token))
+    source = " ".join(parts)
+    try:
+        return bool(eval(source, {"__builtins__": {}}, {"__available": available}))  # noqa: S307 - 词表是白名单，见上
+    except Exception as error:  # noqa: BLE001 - 任何求值失败都按「认不出」处理
+        raise ConditionError(f"求值失败（{error}）：`{source}`") from None
diff --git a/packaging/tests/gpu_shot_ci_probe.py b/packaging/tests/gpu_shot_ci_probe.py
new file mode 100644
index 0000000..1b4d266
--- /dev/null
+++ b/packaging/tests/gpu_shot_ci_probe.py
@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+"""`gpu-evidence.yml` 的**功能断言**部分（M253 / r1+r2 复审返工）：把 workflow 里的 `run:` 原文抽出来真跑。
+
+为什么单独一份：判据脚本自己守 ≤400 行硬线，而这里全是「把 `run:` 落盘、用桩 env 起 bash、读
+`$GITHUB_OUTPUT` / `$GITHUB_STEP_SUMMARY` / 退出码」的**执行脚手架**，与「哪条判据该红」的判断无关
+（同 `gpu_shot_selftest.py` 与 `check_gpu_shot.py` 的分工）。
+
+两组功能断言，各自对应一类「绿而没判」：
+
+**A. `detect` 步（`probe_problems`）—— 跳过要留痕、红线不许退化成跳过。**
+字符串存在性检查被 r1 复审证伪过：旧版只要求「同一步的 run 里同时出现 4 个字符串」，于是把
+`available` 写成恒 `false`（门禁永久关闭、每次运行都绿）它照样绿 —— **文案都在，执行路径却没走到**。
+
+| # | 输入 | 必须发生什么 |
+|---|------|-------------|
+| S1 | 无产物（CI 常态） | `available=false` + summary 写「跳过 / 未验证」+ stdout 有 `::warning::` |
+| S2 | 约定产物成对 | `available=true` |
+| S3 | 约定产物半套（只有日志） | `available=false`（半套不算可用） |
+| S4 | dispatch 成对 | `available=true` |
+| S5 | dispatch 点名不存在 | `exit≠0`，且**不写** `available`（写了就等于退化成跳过） |
+| S6 | dispatch 正例缺 PNG | `exit≠0`，同上 |
+| S7 | dispatch 负例只给日志 | `available=true`（`--expect-refuse` 允许省略 PNG） |
+
+**B. `judge` 步（`judge_problems`）—— 判据步必须真的把红判成红。**
+r2 复审实测：判据命令后面加 `|| echo "先忽略"`、`; :`、去掉 pipefail 再 `| cat`、`if ! python3 …`、
+`true  # python3 …`（保留子串锚点），五种写法的判据步**全 exit 0**（绿而没判），而标记表判据一条都没抓住。
+所以这里跑两次：正例成对必须 `exit 0`，CPU 档日志（`renderer=tiny-skia`）必须 `exit≠0`。第 2 条一红就
+同时封掉「吞码」整类，不依赖任何标记表。
+
+**跑的是原文，只改一个令牌**：`run` 原文里 `python3` 换成本进程的解释器（Windows 上没有 `python3`；
+控制流、运算符、参数一字不改）。夹具用 `gpu_shot_selftest.synth_log/synth_png`，不另造第二套。
+判据步的 `cwd` 是仓库根（它要 `packaging/check_gpu_shot.py` 的相对路径）。
+
+不降级：找不到能跑的 `bash` 就**判红**（「认不出/跑不了」≠「没问题」）。
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+PACKAGING = Path(__file__).resolve().parent.parent
+REPO = PACKAGING.parent
+sys.path[:0] = [str(PACKAGING), str(Path(__file__).resolve().parent)]
+from gpu_shot_selftest import SELFTEST_SIZE, synth_log, synth_png  # noqa: E402
+
+_CACHE: dict[str, list[str]] = {}
+PYTHON_TOKEN = re.compile(r"\bpython3\b")
+
+
+def _find_bash() -> str | None:
+    """挑一个**真能跑**的 bash。Windows 上 `bash.exe` 可能是 WSL 的 relay（没有 `/bin/bash`），要验一次。"""
+    candidates = [os.environ.get("BASH"), shutil.which("bash")]
+    if os.name == "nt":
+        candidates += [r"C:\Program Files\Git\bin\bash.exe", r"C:\Program Files\Git\usr\bin\bash.exe"]
+    candidates.append("bash")
+    for candidate in candidates:
+        if not candidate:
+            continue
+        try:
+            done = subprocess.run([candidate, "-c", "echo ok"], capture_output=True, text=True, timeout=60)
+        except (OSError, subprocess.SubprocessError):
+            continue
+        if done.returncode == 0 and "ok" in (done.stdout or ""):
+            return candidate
+    return None
+
+
+def _run(bash: str, script: Path, workdir: Path, env_extra: dict, cwd: str | None = None, flags: tuple[str, ...] = ("-e",)):
+    """跑一份 `run:` 原文，返回 `(CompletedProcess, GITHUB_OUTPUT 字典, GITHUB_STEP_SUMMARY 文本)`。
+
+    `flags` 默认 `-e`（GitHub 的 `bash -e {0}`）；判据步还会用**裸 bash**（不带 `-e`）再跑一遍 ——
+    `... ; :` 这种写法只有在不靠 `-e` 兜底时才会把红吞掉（实测：`bash -e` 仍 exit 1，裸 bash exit 0）。
+    """
+    out_path, sum_path = workdir / "gh_output", workdir / "gh_summary"
+    env = os.environ.copy()
+    env.update({"GITHUB_OUTPUT": out_path.as_posix(), "GITHUB_STEP_SUMMARY": sum_path.as_posix()})
+    env.update({key: ("" if value is None else str(value)) for key, value in env_extra.items()})
+    done = subprocess.run([bash, *flags, str(script)], cwd=cwd or str(workdir), env=env, capture_output=True, text=True, encoding="utf-8", errors="replace")
+    outputs: dict[str, str] = {}
+    if out_path.exists():
+        for line in out_path.read_text(encoding="utf-8", errors="replace").splitlines():
+            key, sep, value = line.partition("=")
+            if sep:
+                outputs[key.strip()] = value
+    summary = sum_path.read_text(encoding="utf-8", errors="replace") if sum_path.exists() else ""
+    return done, outputs, summary
+
+
+def _case(label: str, done, outputs: dict, summary: str, *, available: str, contains: tuple[str, ...] = (), warning: bool = False) -> list[str]:
+    problems: list[str] = []
+    if done.returncode != 0:
+        problems.append(f"{label}：退出码 {done.returncode}，应为 0（stderr: {(done.stderr or '').strip()[:200]}）")
+    if outputs.get("available") != available:
+        problems.append(f"{label}：`available={outputs.get('available')!r}`，应为 {available!r} —— 探测结论被改坏了，门就永久开或永久关")
+    for needle in contains:
+        if needle not in summary:
+            problems.append(f"{label}：job summary 里缺 `{needle}` —— 跳过不再留痕")
+    if warning and "::warning::" not in (done.stdout or ""):
+        problems.append(f"{label}：stdout 里没有 `::warning::` —— 跳过变成了静默 pass")
+    return problems
+
+
+def _probe_scenarios(bash: str, script_text: str) -> list[str]:
+    problems: list[str] = []
+    with tempfile.TemporaryDirectory(prefix="ull-gpu-ci-", ignore_cleanup_errors=True) as tmp:
+        root = Path(tmp)
+        fixtures = root / "fixtures"
+        fixtures.mkdir()
+        log = fixtures / "a1-gpu.stderr.log"
+        log.write_text("[shot] 200x120\n", encoding="utf-8")
+        png = fixtures / "a1-gpu.png"
+        png.write_bytes(b"\x89PNG\r\n\x1a\n")
+
+        def case(slug: str, tree: tuple[tuple[str, bytes], ...] = ()):
+            workdir = root / slug
+            workdir.mkdir()
+            for rel, payload in tree:
+                path = workdir / rel
+                path.parent.mkdir(parents=True, exist_ok=True)
+                path.write_bytes(payload)
+            script = workdir / "probe.sh"
+            script.write_text(script_text, encoding="utf-8")
+            return script, workdir
+
+        base = {"EVENT": "push", "SHOT_LOG": "", "SHOT_PNG": "", "EXPECT_REFUSE": None}
+        convention = "DevDocs/artifacts/gpu-probe/gpu-shot"
+        script, workdir = case("s1-none")
+        problems += _case("S1 无产物（CI 常态）", *_run(bash, script, workdir, base), available="false", contains=("跳过", "未验证"), warning=True)
+        script, workdir = case("s2-convention-pair", ((f"{convention}.stderr.log", b"x"), (f"{convention}.png", b"x")))
+        problems += _case("S2 约定产物成对", *_run(bash, script, workdir, base), available="true")
+        script, workdir = case("s3-convention-half", ((f"{convention}.stderr.log", b"x"),))
+        problems += _case("S3 约定产物半套（只有日志）", *_run(bash, script, workdir, base), available="false", contains=("跳过",))
+        script, workdir = case("s4-dispatch-pair")
+        problems += _case("S4 dispatch 成对", *_run(bash, script, workdir, dict(base, SHOT_LOG=str(log), SHOT_PNG=str(png))), available="true")
+        for slug, label, extra in (
+            ("s5-dispatch-missing", "S5 dispatch 点名不存在", {"SHOT_LOG": str(root / "nope.log"), "SHOT_PNG": str(png)}),
+            ("s6-dispatch-no-png", "S6 dispatch 正例缺 PNG", {"SHOT_LOG": str(log), "SHOT_PNG": ""}),
+        ):
+            script, workdir = case(slug)
+            done, outputs, _summary = _run(bash, script, workdir, dict(base, **extra))
+            if done.returncode == 0:
+                problems.append(f"{label}：退出码 0 —— 「明确说要判、东西不在」退化成了跳过（假绿）")
+            if outputs:
+                problems.append(f"{label}：该红却写了 `$GITHUB_OUTPUT`（{outputs}）")
+        script, workdir = case("s7-dispatch-refuse")
+        problems += _case("S7 dispatch 负例只给日志", *_run(bash, script, workdir, dict(base, SHOT_LOG=str(log), SHOT_PNG="", EXPECT_REFUSE="true")), available="true")
+    return problems
+
+
+def probe_problems(script_text: str) -> list[str]:
+    """判据 A：`id: detect` 那一步的 `run` 原文实跑 7 种输入（带缓存，同文本只跑一次）。"""
+    if not script_text.strip():
+        return ["`id: detect` 那一步没有 `run:` —— 跳过路径无从执行"]
+    if script_text not in _CACHE:
+        bash = _find_bash()
+        _CACHE[script_text] = (
+            ["找不到能跑的 `bash`：跳过路径的功能断言无法执行，本判据不降级（认不出就红）"]
+            if not bash
+            else _probe_scenarios(bash, script_text)
+        )
+    return _CACHE[script_text]
+
+
+def _judge_scenarios(bash: str, script_text: str) -> list[str]:
+    problems: list[str] = []
+    with tempfile.TemporaryDirectory(prefix="ull-gpu-judge-", ignore_cleanup_errors=True) as tmp:
+        root = Path(tmp)
+        passing = root / "pass.stderr.log"
+        passing.write_text(synth_log(size=SELFTEST_SIZE), encoding="utf-8")
+        cpu = root / "cpu.stderr.log"
+        cpu.write_text(synth_log(renderer="tiny-skia", size=SELFTEST_SIZE), encoding="utf-8")
+        png = root / "pass.png"
+        png.write_bytes(synth_png("content", SELFTEST_SIZE))
+        script = root / "judge.sh"
+        script.write_text(PYTHON_TOKEN.sub(lambda _match: f'"{Path(sys.executable).as_posix()}"', script_text), encoding="utf-8")
+        common = {"PNG": png.as_posix(), "EXPECT_REFUSE": "false"}
+        # 两种模式都跑：`-e` = GitHub 的默认 shell；裸 bash = 不靠 `-e` 兜底（`; :` 只在后者现形）。
+        for mode, flags in (("bash -e", ("-e",)), ("裸 bash", ())):
+            for label, log_path, want_zero in (
+                ("正例（六条判据全过）", passing, True),
+                ("CPU 档日志（`renderer=tiny-skia`，必须判红）", cpu, False),
+            ):
+                done, _outputs, _summary = _run(bash, script, root, dict(common, LOG=log_path.as_posix()), cwd=str(REPO), flags=flags)
+                if want_zero and done.returncode != 0:
+                    problems.append(
+                        f"[{mode}] 判据步对**正例**退出码 {done.returncode}，应为 0 —— 「判据全过」这条路走不通了"
+                        f"（stderr: {(done.stderr or '').strip()[:200]}）"
+                    )
+                if not want_zero and done.returncode == 0:
+                    problems.append(
+                        f"[{mode}] 判据步对**必须判红**的输入退出码 0 —— 「绿而没判」：`|| echo` / `; :` / 管道 / `if !` / "
+                        "`true  # 原行` / 裸 `exit 0` 都属于这一类"
+                    )
+    return problems
+
+
+def judge_problems(script_text: str) -> list[str]:
+    """判据 B：`id: judge` 那一步的 `run` 原文实跑两次（正例必须 0、CPU 档必须非 0）。"""
+    if not script_text.strip():
+        return ["`id: judge` 那一步没有 `run:` —— 判据步无从执行"]
+    key = "judge:" + script_text
+    if key not in _CACHE:
+        bash = _find_bash()
+        _CACHE[key] = (
+            ["找不到能跑的 `bash`：判据步的功能断言无法执行，本判据不降级（认不出就红）"]
+            if not bash
+            else _judge_scenarios(bash, script_text)
+        )
+    return _CACHE[key]
diff --git a/packaging/tests/gpu_shot_ci_selftest.py b/packaging/tests/gpu_shot_ci_selftest.py
new file mode 100644
index 0000000..5ee5b88
--- /dev/null
+++ b/packaging/tests/gpu_shot_ci_selftest.py
@@ -0,0 +1,377 @@
+#!/usr/bin/env python3
+r"""`gpu-evidence.yml` 的**接线自检**（M253 / r1+r2 复审返工）：把「这道门禁怎么才算没被改绿」变成判据。
+
+历史（留着，防止下一个人再写绝对化结论）：
+- r1 版宣称「不可能被改成总是绿」，复审造 19 条变异**漏 11 条**（最要命：`available` 恒 false ⇒ 门永久
+  关闭而每次绿）—— 根因是判据只做字符串存在性检查、自测步被整条豁免、`is True` 挡不住 `'true'`。
+- r2 版改成 6 条判据后，复审 40 条新变异**仍漏 11 条**：job outputs 的 `available` 绑到 `reason`/字面量
+  （门永久关、每次绿）、判据步 `|| echo "先忽略"` / `; :` / `| cat` / `if !` / `true # 原行`（**绿而没判**，
+  真 bash 实测 exit 0）、自检步被指向另一个脚本（自检根本不跑）、`on:` 触发面被删。
+  教训：**「不吞退出码」不能靠标记表**，得把 `run` 原文真跑一遍。
+
+现在十条判据，能结构化的不靠字符串、能跑的不靠读文本：
+
+| # | 判据 | 怎么判 |
+|---|------|--------|
+| 1 | 五步必须在场 | 按 `id:` 认 `vectors`/`exitcodes`/`wiring`/`detect`/`judge`，各恰好一步；前四步不许有 `if:`（step 或 job 级）；`exitcodes` 必须真断言 `expect 0/1/2` |
+| 2 | 自测步跑的是对脚本、且是单条命令 | `wiring` 的 `run` 必须含 `gpu_shot_ci_selftest.py`；`vectors`/`wiring` 的 `run` 不许有换行、`\|`、`&`、`;`、反引号、`#`、`$(` —— 否则红了之后一行 `\|\| echo 先忽略` 就能关掉它 |
+| 3 | 判定必须挂门 | **解析 `if:` 表达式后求值**：`available` 取 `'true'` 必须真、`'false'`/`''` 必须假；job 级与 step 级各自都要满足；认不出的表达式一律红 |
+| 4 | 判定用探测给的产物 | `run` 里两种调用形态都在场（`"$LOG" "$PNG"` 与 `"$LOG" --expect-refuse`），`env` 来自 `needs.probe.outputs.*` |
+| 5 | 判据步**真跑两次** | `judge` 的 `run` 原文实跑：正例成对必须 `exit 0`，CPU 档日志（`renderer=tiny-skia`）必须 `exit≠0` —— 一次封掉整类「吞码」 |
+| 6 | 跳过路径**真跑 7 种输入** | `detect` 的 `run` 原文实跑：`available` 的值、summary 文案、`::warning::`、三条红线必须 `exit≠0` 且不写 outputs |
+| 7 | 禁 `continue-on-error` | 按 YAML 布尔语义：`true` / `'true'` / `${{ true }}` / 任意表达式都算开启 |
+| 8 | 不吞退出码（标记表） | 扫所有 `python`+`packaging/` 的 `run`：`\|\| true` / `; true` / `\|\| exit 0` / 裸 `exit 0`（判据 5 的功能断言才是主守，这张表只是兜底） |
+| 9 | `probe.outputs` 必须绑到 `detect` | `available`/`log`/`png` 三个键的值必须**逐个**等于 `${{ steps.detect.outputs.<同名> }}` |
+| 10 | 触发面 | `on:` 必须同时有 `push`（含 `main`）、`pull_request`、`workflow_call` |
+
+## 覆盖的「改绿」类别（封闭清单：10 类，33 条变异向量）
+
+变异数据在 `packaging/tests/gpu_shot_ci_vectors.json`，**按解析后的结构注入**（`step_delete` /
+`job_delete` / `step_set` / `job_set` / `path_set` / `trigger_set` / `run_append` / `run_replace`，
+`also` 可叠加），每条都必须让对应判据当场红、基线必须全绿。类别与来源：
+
+1. 步骤被删 / 被 `if:` 挡住 / 被 `continue-on-error` 兜住（r1 M7/M9/M10/M13/M15/M16/M17/M18、r2 N15/N18）；
+2. 自测步指向别的脚本、或写成能被 `|| echo` 关掉的多行/带运算符命令（r2 N40/N41/N23）；
+3. 判定的门被写成恒真（`|| always()`、`if: true`、step 级 `if: ${{ always() }}`、删门）（r1 M3/M19、r2 N4/N5）；
+4. 判定的产物路径被写死或调用形态被换掉（r1 M20、r2 N9）；
+5. 判据步的退出码被吞 / 分支没走到（r1 M4、r2 N22/N24/N25/N26/N8'—— 都用真 bash 实跑判据步验证）；
+6. `detect` 的结论被改坏（`available` 恒 false、跳过不留痕、删 `$GITHUB_OUTPUT`）（r1 M11/M12/M5/M6/M14、r2 N6/N7/N20）；
+7. `probe.outputs.*` 被改指向别的 step 输出或字面量（**r2 N28/N29**）；
+8. `on:` 触发面被削（删 `push`/`pull_request`/`workflow_call`）（**r2 N11/N12**）；
+9. 排版变动**不误红**（加注释/空行基线仍绿）、变异锚点坏掉**报「向量失效」并红**（r2 N16/N17）；
+10. `if:` 求值器不接受近似写法（`!=`、`!(…)`、`fromJSON`、未知标识符一律红）（r2 N1/N2/N3）。
+
+## 明确**不覆盖**（边界，逐条给理由）
+
+- **改判据脚本本身**：能改这个文件的人也能改判据，它不自守。它只防「顺手改绿」，不防恶意改绿。
+- **载体依赖**：把整个 `gpu-evidence.yml` 删掉/换成别的文件，就没有任何东西会跑这个自检 —— 守门人住在
+  被守对象自己的文件里。`guards.yml` 已经 399/400 行（`file-size` 那道门就扫 `*.yml`），塞不进去。
+- **`if:` 求值器与 GitHub 语义的差异**：只认 `==`/`!=`/`&&`/`||`/括号/字符串/`needs..outputs.<名>`/
+  `true|false|null`/`always()|success()|failure()|cancelled()`（后四者取常量）；其余认不出就是红。
+- **判据 4 的「合法调用替换」**：把正例分支换成另一种**合法**调用（`"$PNG" --expect-refuse`）抓不到；
+  后果是假红不是假绿，判据 5 也会把它判红（正例跑成非 0）。
+- **`exitcodes` 那一步的断言被削弱**（例如末尾加 `|| echo`）：它是**见证步**，不是门；门的绿由判据 5/6
+  的功能断言守住，见证步被削只影响「退出码语义也被验过」这条证据。
+- **判据 6 的 7 种输入之外的分支**（例如 `detect` 里新增的第五个分支）。
+- **真 Actions 的行为**：`if:` 的真求值、job skip 的呈现、required status check 与 skipped 的交互，
+  本脚本一概不管（`if:` 语义是本脚本的小求值器模拟的）。
+
+## 自我定位与止步线
+
+本文件**不宣称**「不可能被改成总是绿」，只宣称「上面那张封闭清单（10 类 / 33 条向量）会被抓」。
+**这条门禁自 2026-11-11 起停止加固**：再往下就会无限递归（守卫守守卫守守卫），边际收益已很低。
+后续若要扩覆盖面，必须由**人类新开 mission**，不要在同一轮里继续加判据。
+
+    python3 packaging/tests/gpu_shot_ci_selftest.py
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import re
+import sys
+from pathlib import Path
+
+PACKAGING = Path(__file__).resolve().parent.parent
+WORKFLOW = PACKAGING.parent / ".github/workflows/gpu-evidence.yml"
+VECTORS_PATH = Path(__file__).resolve().parent / "gpu_shot_ci_vectors.json"
+sys.path.insert(0, str(PACKAGING))
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from check_workflows_yaml import load_yaml  # noqa: E402
+from gpu_shot_ci_expr import ConditionError, evaluate_condition  # noqa: E402
+from gpu_shot_ci_probe import judge_problems, probe_problems  # noqa: E402
+
+#: 必须在场、且必须无条件的步骤（按 `id:` 认，不按步骤名认）。
+REQUIRED_STEPS = {
+    "vectors": "判据实现自测（`--self-test`，19 条向量）",
+    "exitcodes": "退出码语义（真 CLI 走 0/1/2）",
+    "wiring": "接线自检（本脚本，必须在场）",
+    "detect": "产物探测（probe 的唯一步骤）",
+    "judge": "真实产物判据（evidence 的步骤）",
+}
+UNCONDITIONAL = ("vectors", "exitcodes", "wiring", "detect")
+PROBE_OUTPUT_KEYS = ("available", "log", "png")
+SINGLE_COMMAND_STEPS = ("vectors", "wiring")
+SHELL_OPERATOR = re.compile(r"[|&;`#$()<>\n]")
+SWALLOW_MARKS = ("|| true", "; true", "|| exit 0", "exit 0")
+PYTHON_RE = re.compile(r"\bpython3?\b")
+
+
+def coerce_flag(value) -> bool:
+    """YAML 里的开关按**真语义**判：`true` / `'true'` / `${{ true }}` 都算开启。"""
+    if value is True:
+        return True
+    if value is False or value is None:
+        return False
+    if isinstance(value, (int, float)):
+        return bool(value)
+    return str(value).strip().lower() not in {"false", "${{ false }}", "0", "no", "off", ""}
+
+
+def steps(doc: dict) -> list[tuple[str, dict, dict]]:
+    found: list[tuple[str, dict, dict]] = []
+    for job_id, job in (doc.get("jobs") or {}).items():
+        for step in (job or {}).get("steps") or []:
+            if isinstance(step, dict):
+                found.append((job_id, job, step))
+    return found
+
+
+def step_by_id(doc: dict, sid: str) -> tuple[str, dict, dict] | None:
+    found = [entry for entry in steps(doc) if entry[2].get("id") == sid]
+    return found[0] if len(found) == 1 else None
+
+
+def run_of(doc: dict, sid: str) -> str:
+    entry = step_by_id(doc, sid)
+    return (entry[2].get("run") or "") if entry else ""
+
+
+def check_presence(doc: dict) -> list[str]:
+    problems: list[str] = []
+    counts = {sid: len([e for e in steps(doc) if e[2].get("id") == sid]) for sid in REQUIRED_STEPS}
+    for sid, label in REQUIRED_STEPS.items():
+        if counts[sid] != 1:
+            problems.append(f"`id: {sid}`（{label}）必须恰好一步，实际 {counts[sid]} 步 —— 删掉或复制都算红")
+            continue
+        job_id, job, step = step_by_id(doc, sid)
+        if sid in UNCONDITIONAL and ("if" in step or "if" in job):
+            problems.append(f"`id: {sid}`（{label}）带 `if:`（步骤或 job 级）—— 这四步必须无条件跑，否则门禁可被静默关掉")
+    asserted = set(re.findall(r"\bexpect\s+([0-9]+)\b", run_of(doc, "exitcodes")))
+    missing = {"0", "1", "2"} - asserted
+    if step_by_id(doc, "exitcodes") and missing:
+        problems.append(f"`id: exitcodes` 没有断言退出码 {'/'.join(sorted(missing))}（`expect <码>`）—— 三个码就是门禁的接口")
+    return problems
+
+
+def check_selftest_commands(doc: dict) -> list[str]:
+    problems: list[str] = []
+    wiring = run_of(doc, "wiring").strip()
+    if wiring and "gpu_shot_ci_selftest.py" not in wiring:
+        problems.append("`id: wiring` 的 `run` 里没有 `gpu_shot_ci_selftest.py` —— 它可能指向别的脚本（自检根本没跑）")
+    for sid in SINGLE_COMMAND_STEPS:
+        run = run_of(doc, sid).strip()
+        if not run:
+            continue
+        if SHELL_OPERATOR.search(run):
+            problems.append(
+                f"`id: {sid}` 的 `run` 必须是**单条命令**（不许换行 / `|` / `&` / `;` / 反引号 / `#` / `$(`）"
+                f"—— 否则红了之后一行 `|| echo 先忽略` 就能把它关掉：`{run}`"
+            )
+    return problems
+
+
+def check_judge_gate(doc: dict) -> list[str]:
+    entry = step_by_id(doc, "judge")
+    if entry is None:
+        return []  # presence 已经报过
+    job_id, job, step = entry
+    gates: list[tuple[str, object]] = []
+    if "if" in job:
+        gates.append((f"job `{job_id}` 的 `if`", job.get("if")))
+    if "if" in step:
+        gates.append(("`id: judge` 步的 `if`", step.get("if")))
+    if not gates:
+        return ["`judge` 步与它的 job 都没有 `if:` —— 无产物时也会照跑，「跳过」与「通过」分不开"]
+    problems: list[str] = []
+    for label, raw in gates:
+        for available, want in (("true", True), ("false", False), ("", False)):
+            try:
+                got = evaluate_condition(raw, available)
+            except ConditionError as error:
+                problems.append(f"{label} 认不出（{error}）—— 认不出即红：`{raw}`")
+                break
+            if got is not want:
+                problems.append(f"{label} 在 `available={available!r}` 时求值为 {got}，应为 {want}：`{raw}`")
+    return problems
+
+
+def check_judge_invocation(doc: dict) -> list[str]:
+    entry = step_by_id(doc, "judge")
+    if entry is None:
+        return []
+    run = entry[2].get("run") or ""
+    env = entry[2].get("env") or {}
+    problems: list[str] = []
+    for form in ('check_gpu_shot.py "$LOG" "$PNG"', 'check_gpu_shot.py "$LOG" --expect-refuse'):
+        if form not in run:
+            problems.append(f"`id: judge` 的 `run` 里缺调用形态 `{form}` —— 该分支可以「什么都没判」就绿")
+    for name, ref in (("LOG", "needs.probe.outputs.log"), ("PNG", "needs.probe.outputs.png")):
+        if ref not in str(env.get(name, "")):
+            problems.append(f"`judge` 的 `{name}` 不是来自 `{ref}`（写死的路径会在跳过那条路上判错东西）")
+    return problems
+
+
+def check_probe_outputs(doc: dict) -> list[str]:
+    outputs = (doc.get("jobs") or {}).get("probe", {}).get("outputs") or {}
+    problems: list[str] = []
+    for key in PROBE_OUTPUT_KEYS:
+        want = "${{ steps.detect.outputs.%s }}" % key
+        got = str(outputs.get(key, "")).strip()
+        if got != want:
+            problems.append(
+                f"`probe.outputs.{key}` 必须恰好是 `{want}`，实际 {got!r} —— "
+                "改指向（`reason` / 字面量 `'false'`）会让门永久关掉，而每次运行都绿"
+            )
+    return problems
+
+
+def check_triggers(doc: dict) -> list[str]:
+    on_block = doc.get("on", doc.get(True))
+    if not isinstance(on_block, dict):
+        return ["`on:` 不是一个映射 —— 触发面认不出（认不出即红）"]
+    problems: list[str] = []
+    if "push" not in on_block:
+        problems.append("`on:` 少了 `push` —— main 上的门禁会停摆")
+    else:
+        branches = (on_block.get("push") or {}).get("branches") if isinstance(on_block.get("push"), dict) else None
+        if branches is not None and "main" not in [str(branch) for branch in branches]:
+            problems.append("`on.push.branches` 里没有 `main` —— main 上的门禁会停摆")
+    if "pull_request" not in on_block:
+        problems.append("`on:` 少了 `pull_request` —— PR 上的门禁会停摆")
+    if "workflow_call" not in on_block:
+        problems.append("`on:` 少了 `workflow_call` —— `dev-guards.yml` 的 `uses:` 会加载失败")
+    return problems
+
+
+def check_continue_on_error(doc: dict) -> list[str]:
+    problems: list[str] = []
+    for job_id, job in (doc.get("jobs") or {}).items():
+        if coerce_flag((job or {}).get("continue-on-error")):
+            problems.append(f"job `{job_id}` 带 `continue-on-error: {job.get('continue-on-error')!r}` —— 判据红也会变绿")
+        for step in (job or {}).get("steps") or []:
+            if isinstance(step, dict) and coerce_flag(step.get("continue-on-error")):
+                problems.append(f"job `{job_id}` 的 `{step.get('id') or step.get('name')}` 带 `continue-on-error: {step.get('continue-on-error')!r}`")
+    return problems
+
+
+def check_no_swallow(doc: dict) -> list[str]:
+    problems: list[str] = []
+    for job_id, _job, step in steps(doc):
+        run = step.get("run") or ""
+        if not (PYTHON_RE.search(run) and "packaging/" in run):
+            continue
+        hits = [mark for mark in SWALLOW_MARKS if mark in run]
+        if hits:
+            problems.append(f"job `{job_id}` 的 `{step.get('id') or step.get('name')}` 里出现 {'/'.join(f'`{h}`' for h in hits)} —— 退出码被吞掉，判据红也绿")
+    return problems
+
+
+CHECKS = {
+    "1 五步必须在场": check_presence,
+    "2 自测步跑的是对脚本且是单条命令": check_selftest_commands,
+    "3 判定必须挂门": check_judge_gate,
+    "4 判定用探测给的产物": check_judge_invocation,
+    "5 判据步真跑（正例 0 / CPU 档非 0）": lambda doc: judge_problems(run_of(doc, "judge")),
+    "6 跳过路径真跑（7 种输入）": lambda doc: probe_problems(run_of(doc, "detect")),
+    "7 禁 continue-on-error": check_continue_on_error,
+    "8 不吞退出码（标记表，兜底）": check_no_swallow,
+    "9 probe.outputs 绑定 detect": check_probe_outputs,
+    "10 触发面（push/pull_request/workflow_call）": check_triggers,
+}
+
+
+def evaluate(doc: dict) -> dict[str, list[str]]:
+    if not isinstance(doc, dict) or not isinstance(doc.get("jobs"), dict):
+        return {name: ["workflow 不是一个带 jobs 的 YAML 映射"] for name in CHECKS}
+    return {name: check(doc) for name, check in CHECKS.items()}
+
+
+def _walk(doc: dict, path: list) -> tuple[dict, object]:
+    node = doc
+    for key in path[:-1]:
+        node = node[key]
+    return node, path[-1]
+
+
+def apply_vector(doc: dict, vector: dict) -> dict:
+    """按**解析后的结构**注入变异（不碰文本格式，改动 workflow 的排版不会让向量过期）。"""
+    op = vector["op"]
+    target = str(vector.get("target", ""))
+    on_key = "on" if "on" in doc else True
+    if op in ("step_delete", "step_set", "run_append", "run_replace"):
+        entry = step_by_id(doc, target)
+        if entry is None:
+            raise KeyError(f"找不到唯一的 `id: {target}`")
+        step = entry[2]
+        if op == "step_delete":
+            entry[1]["steps"].remove(step)
+        elif op == "step_set":
+            step[vector["key"]] = vector["value"]
+        else:
+            text = step.get("run") or ""
+            if op == "run_append":
+                step["run"] = text + vector["value"]
+            else:
+                find, replacement, occurrence = vector["find"], vector["replace"], int(vector.get("occurrence", 1))
+                pos = -1
+                for _ in range(occurrence):
+                    pos = text.find(find, pos + 1)
+                    if pos < 0:
+                        raise KeyError(f"`id: {target}` 的 run 里找不到第 {occurrence} 处 `{find}`")
+                step["run"] = text[:pos] + replacement + text[pos + len(find) :]
+    elif op in ("job_delete", "job_set"):
+        if target not in (doc.get("jobs") or {}):
+            raise KeyError(f"没有 job `{target}`")
+        if op == "job_delete":
+            del doc["jobs"][target]
+        else:
+            doc["jobs"][target][vector["key"]] = vector["value"]
+    elif op == "path_set":
+        parent, key = _walk(doc, vector["path"])
+        if key not in parent:
+            raise KeyError(f"路径不存在：{vector['path']}")
+        parent[key] = vector["value"]
+    elif op == "trigger_set":
+        doc[on_key] = vector["value"]
+    else:
+        raise KeyError(f"不认识的变异操作 `{op}`")
+    for extra in vector.get("also", []):
+        apply_vector(doc, extra)
+    return doc
+
+
+def main() -> int:
+    yaml = load_yaml()
+    if not WORKFLOW.is_file():
+        print(f"::error file={WORKFLOW}::接线自检的靶子不存在", file=sys.stderr)
+        return 1
+    doc = yaml.safe_load(WORKFLOW.read_text(encoding="utf-8"))
+    failures = 0
+    for name, problems in evaluate(doc).items():
+        if problems:
+            failures += 1
+            print(f"FAIL: 判据「{name}」没过：", file=sys.stderr)
+            for problem in problems:
+                print(f"  - {problem}", file=sys.stderr)
+        else:
+            print(f"OK: 判据「{name}」")
+
+    vectors = json.loads(VECTORS_PATH.read_text(encoding="utf-8"))["vectors"]
+    for vector in vectors:
+        label = f"{vector['id']} {vector['label']}"
+        try:
+            mutated = apply_vector(copy.deepcopy(doc), vector)
+        except Exception as error:  # noqa: BLE001 - 向量失效（锚点没了）同样算红，逼着人更新它
+            failures += 1
+            print(f"FAIL: 变异「{label}」注入失败（向量失效）：{error}", file=sys.stderr)
+            continue
+        broken = [name for name, problems in evaluate(mutated).items() if problems]
+        if vector["expect"] not in broken:
+            failures += 1
+            print(f"FAIL: 变异「{label}」没被抓到（应红「{vector['expect']}」，实际红的是 {broken or '无'}）", file=sys.stderr)
+        else:
+            print(f"OK: 变异「{label}」→ 「{vector['expect']}」当场红")
+
+    if failures:
+        print(f"FAIL：{failures} 处没过（{WORKFLOW.name}）", file=sys.stderr)
+        return 1
+    print(f"ok: {len(CHECKS)} 条接线判据全过，{len(vectors)} 条变异向量全部被抓（{WORKFLOW.name}）")
+    print("   封闭清单 10 类（见 docstring）；不覆盖：改判据脚本 / 删掉整个 workflow（载体依赖）/ 求值器语义差 / 合法调用替换。")
+    print("   本门禁自 2026-11-11 起停止加固，扩项须由人类新开 mission。")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/packaging/tests/gpu_shot_ci_vectors.json b/packaging/tests/gpu_shot_ci_vectors.json
new file mode 100644
index 0000000..ce8b8a7
--- /dev/null
+++ b/packaging/tests/gpu_shot_ci_vectors.json
@@ -0,0 +1,38 @@
+{
+  "_note": "M253 接线自检的变异向量。全部按解析后的结构注入（排版变动不影响）：op ∈ step_delete / job_delete / step_set / job_set / path_set / trigger_set / run_append / run_replace；`also` 可叠加一组后续注入。expect = 必须报错的判据名（与 gpu_shot_ci_selftest.py 的 CHECKS 键逐字一致）。计数：33 = r1 复审表 20 条 + 1 条补充（M20）+ r2 复审 12 条（N28/N29/N22/N23/N24/N25/N26/N8'/N40/N41/N11/N12）。",
+  "vectors": [
+    {"id": "M1", "label": "自测步命令后加 || true（自测被吞）", "op": "run_append", "target": "vectors", "value": " || true", "expect": "8 不吞退出码（标记表，兜底）"},
+    {"id": "M2", "label": "接线自检步命令后加 || true（守卫守不到自己）", "op": "run_append", "target": "wiring", "value": " || true", "expect": "8 不吞退出码（标记表，兜底）"},
+    {"id": "M2b", "label": "接线自检步命令后加 ; true", "op": "run_append", "target": "wiring", "value": "; true", "expect": "2 自测步跑的是对脚本且是单条命令"},
+    {"id": "M3", "label": "判定的门加 || always()（门形同虚设）", "op": "job_set", "target": "evidence", "key": "if", "value": "needs.probe.outputs.available == 'true' || always()", "expect": "3 判定必须挂门"},
+    {"id": "M4", "label": "判据命令后加裸 exit 0", "op": "run_append", "target": "judge", "value": "\nexit 0\n", "expect": "8 不吞退出码（标记表，兜底）"},
+    {"id": "M5", "label": "整行删掉 ::warning:: 告警", "op": "run_replace", "target": "detect", "find": "echo \"::warning::GPU 证据：跳过（${reason}）—— 本次运行没有判过任何真实产物，不构成「GPU 证据已验证」\"", "replace": "", "expect": "6 跳过路径真跑（7 种输入）"},
+    {"id": "M6", "label": "不再写 $GITHUB_OUTPUT（判定永远拿不到产物）", "op": "run_replace", "target": "detect", "find": ">> \"$GITHUB_OUTPUT\"", "replace": ">> /dev/null", "expect": "6 跳过路径真跑（7 种输入）"},
+    {"id": "M7", "label": "selftest job 加 job 级 if: false", "op": "job_set", "target": "selftest", "key": "if", "value": false, "expect": "1 五步必须在场"},
+    {"id": "M8", "label": "探测步加 continue-on-error: true", "op": "step_set", "target": "detect", "key": "continue-on-error", "value": true, "expect": "7 禁 continue-on-error"},
+    {"id": "M9", "label": "接线自检步加 if: false", "op": "step_set", "target": "wiring", "key": "if", "value": false, "expect": "1 五步必须在场"},
+    {"id": "M10", "label": "整步删掉接线自检", "op": "step_delete", "target": "wiring", "expect": "1 五步必须在场"},
+    {"id": "M11", "label": "dispatch 分支 available 恒 false（门禁永久关闭）", "op": "run_replace", "target": "detect", "find": "available=true", "replace": "available=false", "occurrence": 1, "expect": "6 跳过路径真跑（7 种输入）"},
+    {"id": "M12", "label": "约定产物分支 available 恒 false（门禁永久关闭）", "op": "run_replace", "target": "detect", "find": "available=true", "replace": "available=false", "occurrence": 2, "expect": "6 跳过路径真跑（7 种输入）"},
+    {"id": "M13", "label": "整块删掉 evidence job", "op": "job_delete", "target": "evidence", "expect": "1 五步必须在场"},
+    {"id": "M14", "label": "::warning:: 改成裸 echo（跳过变静默 pass）", "op": "run_replace", "target": "detect", "find": "::warning::", "replace": "", "expect": "6 跳过路径真跑（7 种输入）"},
+    {"id": "M15", "label": "整步删掉 --self-test", "op": "step_delete", "target": "vectors", "expect": "1 五步必须在场"},
+    {"id": "M16", "label": "整步删掉退出码语义 0/1/2", "op": "step_delete", "target": "exitcodes", "expect": "1 五步必须在场"},
+    {"id": "M17", "label": "continue-on-error: 'true'（带引号）", "op": "step_set", "target": "detect", "key": "continue-on-error", "value": "true", "expect": "7 禁 continue-on-error"},
+    {"id": "M18", "label": "continue-on-error: ${{ true }}（表达式）", "op": "step_set", "target": "detect", "key": "continue-on-error", "value": "${{ true }}", "expect": "7 禁 continue-on-error"},
+    {"id": "M19", "label": "判定步加 if: ${{ always() }}", "op": "step_set", "target": "judge", "key": "if", "value": "${{ always() }}", "expect": "3 判定必须挂门"},
+    {"id": "M20", "label": "判定步的正例调用换成 true（不再调判据脚本）", "op": "run_replace", "target": "judge", "find": "python3 packaging/check_gpu_shot.py \"$LOG\" \"$PNG\"", "replace": "true", "expect": "4 判定用探测给的产物"},
+    {"id": "N28", "label": "probe.outputs.available 改指向 reason（门永久关、每次绿）", "op": "path_set", "path": ["jobs", "probe", "outputs", "available"], "value": "${{ steps.detect.outputs.reason }}", "expect": "9 probe.outputs 绑定 detect"},
+    {"id": "N29", "label": "probe.outputs.available 改成字面量 'false'（门永久关）", "op": "path_set", "path": ["jobs", "probe", "outputs", "available"], "value": "false", "expect": "9 probe.outputs 绑定 detect"},
+    {"id": "N22", "label": "判据命令后加 || echo 先忽略（绿而没判）", "op": "run_replace", "target": "judge", "find": "python3 packaging/check_gpu_shot.py \"$LOG\" \"$PNG\"", "replace": "python3 packaging/check_gpu_shot.py \"$LOG\" \"$PNG\" || echo \"判据没过（先忽略）\"", "expect": "5 判据步真跑（正例 0 / CPU 档非 0）"},
+    {"id": "N24", "label": "判据命令后加 ; :（吞退出码）", "op": "run_replace", "target": "judge", "find": "python3 packaging/check_gpu_shot.py \"$LOG\" \"$PNG\"", "replace": "python3 packaging/check_gpu_shot.py \"$LOG\" \"$PNG\" ; :", "expect": "5 判据步真跑（正例 0 / CPU 档非 0）"},
+    {"id": "N25", "label": "去掉 pipefail 再把判据命令接管道 | cat（吞退出码）", "op": "run_replace", "target": "judge", "find": "python3 packaging/check_gpu_shot.py \"$LOG\" \"$PNG\"", "replace": "python3 packaging/check_gpu_shot.py \"$LOG\" \"$PNG\" | cat", "also": [{"op": "run_replace", "target": "judge", "find": "set -uo pipefail", "replace": "set -u"}], "expect": "5 判据步真跑（正例 0 / CPU 档非 0）"},
+    {"id": "N26", "label": "判据命令包进 if ! … then echo; fi（吞退出码）", "op": "run_replace", "target": "judge", "find": "python3 packaging/check_gpu_shot.py \"$LOG\" \"$PNG\"", "replace": "if ! python3 packaging/check_gpu_shot.py \"$LOG\" \"$PNG\"; then echo \"没判过\"; fi", "expect": "5 判据步真跑（正例 0 / CPU 档非 0）"},
+    {"id": "N8b", "label": "判据命令改成 true 后注释掉原行（保留子串锚点）", "op": "run_replace", "target": "judge", "find": "python3 packaging/check_gpu_shot.py \"$LOG\" \"$PNG\"", "replace": "true  # python3 packaging/check_gpu_shot.py \"$LOG\" \"$PNG\"", "expect": "5 判据步真跑（正例 0 / CPU 档非 0）"},
+    {"id": "N40", "label": "接线自检步指向 gpu_shot_ci_probe.py（自检根本不跑）", "op": "step_set", "target": "wiring", "key": "run", "value": "python3 packaging/tests/gpu_shot_ci_probe.py", "expect": "2 自测步跑的是对脚本且是单条命令"},
+    {"id": "N41", "label": "接线自检步指向另一个自测（自检根本不跑）", "op": "step_set", "target": "wiring", "key": "run", "value": "python3 packaging/check_gpu_shot.py --self-test", "expect": "2 自测步跑的是对脚本且是单条命令"},
+    {"id": "N23", "label": "接线自检步后加 || echo 先忽略（守卫把自己关了）", "op": "run_append", "target": "wiring", "value": " || echo \"自检没过（先忽略）\"", "expect": "2 自测步跑的是对脚本且是单条命令"},
+    {"id": "N11", "label": "删掉 push / pull_request 触发（main、PR 侧停摆）", "op": "trigger_set", "value": ["workflow_dispatch"], "expect": "10 触发面（push/pull_request/workflow_call）"},
+    {"id": "N12", "label": "删掉 workflow_call 触发（dev 线 uses 会加载失败）", "op": "trigger_set", "value": {"push": {"branches": ["main"]}, "pull_request": null, "workflow_dispatch": null}, "expect": "10 触发面（push/pull_request/workflow_call）"}
+  ]
+}
diff --git a/packaging/tests/gpu_shot_selftest.py b/packaging/tests/gpu_shot_selftest.py
new file mode 100644
index 0000000..4341be0
--- /dev/null
+++ b/packaging/tests/gpu_shot_selftest.py
@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+"""`packaging/check_gpu_shot.py --self-test` 的执行器（M249）：合成日志 + 合成 PNG + 向量比对。
+
+为什么单独一份而不是塞进判据脚本：那一份要守 ≤400 行硬线，而这里全是「按真实行格式手拼日志、
+现造 PNG、逐条对 `expect_fail`」的**测试脚手架**，与判据逻辑无关。数据另外放
+`gpu_shot_vectors.json`（同 `guard_vectors.json` 的做法），被测的判据函数由调用方**以参数传入**
+——本文件不反向 import `check_gpu_shot`，免得循环导入。
+
+一颗诚实的钉子：本文件的样本是**按今天的日志格式**手拼的，所以它守**判据**，不守**格式漂移**。
+产品真换了 Debug 形状时，靠的是判据里「取不到 device_type 就算失败」这类保守口径（见 doc §3）。
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import tempfile
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))  # `check_screenshot` 在 packaging/
+from check_screenshot import encode_png  # noqa: E402
+
+#: 向量数据。`log` 是 `synth_log` 的关键字覆盖（缺省键取函数默认值，`null` = 该行不出现）。
+VECTORS_PATH = Path(__file__).resolve().parent / "gpu_shot_vectors.json"
+
+SELFTEST_SIZE = (200, 120)
+
+
+def synth_log(
+    *,
+    renderer: str | None = "wgpu",
+    device_type: str | None = "DiscreteGpu",
+    backend: str | None = "final=wgpu result=started",
+    size: tuple[int, int] | None = None,
+    no_size_line: bool = False,
+    multiline_selected: bool = False,
+    empty_selected: bool = False,
+    extra_shot_renderer: str | None = None,
+) -> str:
+    """按 M246 真实日志的**行格式**拼一份最小日志（传 `None` = 该行故意不出现）。"""
+    lines = [
+        "[probe] renderer = wgpu reason=forced-gpu 兜底=tiny-skia（失败会先打印具名错误）",
+        # 真实日志里永远有这一行提示文本，且它含 `Selected: AdapterInfo` 字样 —— 留着它，
+        # 「只有提示、没有真 Selected 行」的向量才是在测真东西。
+        "[probe] 取证：出现 `[gpu] iced_wgpu: …Selected: AdapterInfo…` ⇒ GPU 真生效；出现 `[gpu] wgpu 初始化失败` ⇒ 已降级 CPU",
+    ]
+    if empty_selected:  # `Selected: AdapterInfo {` 之后再没有内容（字段全丢）
+        lines.append("[gpu] iced_wgpu::window::compositor: Selected: AdapterInfo {")
+    elif device_type is not None:
+        fields = [
+            '     name: "AMD Radeon RX 6600 XT",',
+            f"     device_type: {device_type},",
+            '     backend: Vulkan,',
+        ]
+        if multiline_selected:  # pretty-print Debug：字段不在 `{` 那一行（P2-1 的形状）
+            lines.append("[gpu] iced_wgpu::window::compositor: Selected: AdapterInfo {")
+            lines.extend(fields)
+            lines.append("}")
+        else:
+            lines.append("[gpu] iced_wgpu::window::compositor: Selected: AdapterInfo {" + "".join(fields) + " }")
+    if not no_size_line:
+        dims = size or SELFTEST_SIZE
+        lines.append(f"[shot] {dims[0]}x{dims[1]} scale=1 -> selftest.png")
+    for value in (renderer, extra_shot_renderer):
+        if value is not None:
+            lines.append(f'[shot] screen=gallery theme=light renderer={value} route=Detail("survival")')
+    if backend is not None:
+        lines.append(f"[backend] {backend} elapsed=1000ms evidence=selftest")
+    return "\n".join(lines) + "\n"
+
+
+def synth_png(kind: str, size: tuple[int, int]) -> bytes:
+    """`content` = 有内容的合成帧（渐变 + 8px 棋盘格）；`flat` = 全白。"""
+    width, height = size
+
+    def content_row(y: int) -> bytes:
+        return b"".join(
+            bytes((x * 255 // max(width - 1, 1), y * 255 // max(height - 1, 1), 40))
+            if ((x // 8) + (y // 8)) % 2 == 0
+            else b"\x14\x14\x14"
+            for x in range(width)
+        )
+
+    if kind == "flat":
+        return encode_png(width, height, lambda _y: b"\xff" * (width * 3))
+    return encode_png(width, height, content_row)
+
+
+def run_vector(root: Path, index: int, case: dict, default_size: tuple[int, int], judges: tuple) -> list[str]:
+    """跑一条向量，返回它实际红的判据清单。`judges` = (judge_evidence, judge_refuse)。"""
+    judge_evidence, judge_refuse = judges
+    overrides = {key: (tuple(value) if isinstance(value, list) else value) for key, value in case.get("log", {}).items()}
+    log_path = root / f"case{index:02d}.log"
+    log_path.write_text(synth_log(**{"size": default_size, **overrides}), encoding="utf-8")
+    png_path = root / f"case{index:02d}.png"
+    png_size = tuple(case.get("png_size", default_size))
+    if case.get("png") == "truncated":
+        png_path.write_bytes(synth_png("content", png_size)[:200])
+    elif case.get("png") is not None:
+        png_path.write_bytes(synth_png(case["png"], png_size))
+    report = judge_refuse(log_path, png_path) if case.get("mode") == "refuse" else judge_evidence(log_path, png_path)
+    return report.problems()
+
+
+def run_selftest(judge_evidence, judge_refuse) -> int:
+    """跑 `gpu_shot_vectors.json` 的全部向量，逐条对 `expect_fail`（多一条少一条都算失败）。"""
+    data = json.loads(VECTORS_PATH.read_text(encoding="utf-8"))
+    default_size = tuple(data["size"])
+    failures = 0
+    with tempfile.TemporaryDirectory(prefix="ull-gpu-shot-") as tmp:
+        root = Path(tmp)
+        for index, case in enumerate(data["cases"], start=1):
+            got = run_vector(root, index, case, default_size, (judge_evidence, judge_refuse))
+            want = case["expect_fail"]
+            if got != want:
+                print(f"::error::自测失败：{case['label']} 期望失败 {want}，实际 {got}", file=sys.stderr)
+                failures += 1
+            else:
+                print(f"OK: {case['label']} → {'红 ' + ' / '.join(got) if got else '绿'}")
+    red = sum(1 for case in data["cases"] if case["expect_fail"])
+    if failures:
+        return 1
+    print(f"OK: GPU 截图证据判定自测通过（{len(data['cases'])} 条向量：红 {red} / 绿 {len(data['cases']) - red}）")
+    return 0
diff --git a/packaging/tests/gpu_shot_vectors.json b/packaging/tests/gpu_shot_vectors.json
new file mode 100644
index 0000000..90cee4e
--- /dev/null
+++ b/packaging/tests/gpu_shot_vectors.json
@@ -0,0 +1,120 @@
+{
+  "note": "M249 check_gpu_shot.py --self-test 的向量。log = synth_log 的关键字覆盖（缺省键取函数默认值；null = 该行不出现；no_size_line = 只省掉 [shot] WxH 那一行；multiline_selected / empty_selected = `Selected: AdapterInfo {` 的字段换了形状；extra_shot_renderer = 再追加一行异种 renderer 的 [shot] 行）；png = content/flat/truncated/null（null = 不写文件）；mode = evidence/refuse；expect_fail = **期望的失败判据清单（逐条对，多一条少一条都算自测失败）**——判据被关掉或被别的东西掩盖，都在这里现形。PNG 由 check_screenshot.encode_png 现造，不进仓库。",
+  "size": [200, 120],
+  "cases": [
+    {
+      "label": "基线：wgpu + DiscreteGpu + 有内容 PNG",
+      "png": "content",
+      "expect_fail": []
+    },
+    {
+      "label": "基线：IntegratedGpu 也算硬件（与 probe.rs 同口径）",
+      "log": { "device_type": "IntegratedGpu" },
+      "png": "content",
+      "expect_fail": []
+    },
+    {
+      "label": "变异靶子：renderer=wgpu 但 Selected 是 Cpu（WARP）",
+      "log": { "device_type": "Cpu" },
+      "png": "content",
+      "expect_fail": ["Selected: AdapterInfo 的 device_type 不是 Cpu/Other"]
+    },
+    {
+      "label": "变异靶子：Selected 是 Other（Gl 兼容层）",
+      "log": { "device_type": "Other" },
+      "png": "content",
+      "expect_fail": ["Selected: AdapterInfo 的 device_type 不是 Cpu/Other"]
+    },
+    {
+      "label": "变异靶子：Selected 换成多行 Debug（字段不在 { 那一行）",
+      "log": { "multiline_selected": true },
+      "png": "content",
+      "expect_fail": ["Selected: AdapterInfo 的 device_type 不是 Cpu/Other"]
+    },
+    {
+      "label": "变异靶子：`Selected: AdapterInfo {` 空体（字段全丢）",
+      "log": { "device_type": null, "empty_selected": true },
+      "png": "content",
+      "expect_fail": ["Selected: AdapterInfo 的 device_type 不是 Cpu/Other"]
+    },
+    {
+      "label": "变异靶子：删掉 [shot] renderer 行（只剩 Selected + backend）",
+      "log": { "renderer": null },
+      "png": "content",
+      "expect_fail": ["截图行 renderer=wgpu"]
+    },
+    {
+      "label": "变异靶子：日志里混入第二种 renderer（CPU 那次 >> 拼进来）",
+      "log": { "extra_shot_renderer": "tiny-skia" },
+      "png": "content",
+      "expect_fail": ["截图行 renderer=wgpu"]
+    },
+    {
+      "label": "回归：CPU 档出的图（renderer=tiny-skia）",
+      "log": { "renderer": "tiny-skia", "device_type": null, "backend": "final=tiny-skia result=started" },
+      "png": "content",
+      "expect_fail": ["截图行 renderer=wgpu", "Selected: AdapterInfo 的 device_type 不是 Cpu/Other", "后端结论行 final=wgpu result=started"]
+    },
+    {
+      "label": "回归：没有 Selected 行（wgpu 没建成设备）",
+      "log": { "device_type": null },
+      "png": "content",
+      "expect_fail": ["Selected: AdapterInfo 的 device_type 不是 Cpu/Other"]
+    },
+    {
+      "label": "回归：后端结论行是失败",
+      "log": { "backend": "final=none result=failed via=refuse" },
+      "png": "content",
+      "expect_fail": ["后端结论行 final=wgpu result=started"]
+    },
+    {
+      "label": "回归：完全空白帧（全白 PNG）",
+      "png": "flat",
+      "expect_fail": ["PNG 不是空白帧"]
+    },
+    {
+      "label": "回归：PNG 尺寸与日志 [shot] 不符",
+      "png": "content",
+      "png_size": [640, 480],
+      "expect_fail": ["PNG 宽高 = 日志 [shot] 的宽高"]
+    },
+    {
+      "label": "回归：PNG 根本不存在",
+      "png": null,
+      "expect_fail": ["PNG 能解码且非空", "PNG 宽高 = 日志 [shot] 的宽高", "PNG 不是空白帧"]
+    },
+    {
+      "label": "回归：PNG 半截（签名对、字节不够）",
+      "png": "truncated",
+      "expect_fail": ["PNG 能解码且非空", "PNG 宽高 = 日志 [shot] 的宽高", "PNG 不是空白帧"]
+    },
+    {
+      "label": "负例基线：via=refuse + 无出图行 + 无 PNG",
+      "log": { "renderer": null, "device_type": null, "no_size_line": true, "backend": "final=none result=failed via=refuse" },
+      "png": null,
+      "mode": "refuse",
+      "expect_fail": []
+    },
+    {
+      "label": "负例回归：拒绝日志旁边却躺着一张 PNG",
+      "log": { "renderer": null, "device_type": null, "no_size_line": true, "backend": "final=none result=failed via=refuse" },
+      "png": "content",
+      "mode": "refuse",
+      "expect_fail": ["目标 PNG 不存在（拒绝出图就该一张都没有）"]
+    },
+    {
+      "label": "负例回归：CPU 档日志不是「拒绝」（via 缺）",
+      "log": { "renderer": "tiny-skia", "device_type": null, "backend": "final=tiny-skia result=started" },
+      "png": null,
+      "mode": "refuse",
+      "expect_fail": ["后端结论行 via=refuse", "没有出图行（[shot] 尺寸 + renderer 都不该有）"]
+    },
+    {
+      "label": "负例回归：final=… via=refuse 却仍有出图行（自相矛盾）",
+      "log": { "backend": "final=none result=failed via=refuse" },
+      "png": "content",
+      "mode": "refuse",
+      "expect_fail": ["没有出图行（[shot] 尺寸 + renderer 都不该有）", "目标 PNG 不存在（拒绝出图就该一张都没有）"]
+    }
+  ]
+}
diff --git a/packaging/tests/guard_vectors.json b/packaging/tests/guard_vectors.json
new file mode 100644
index 0000000..4233773
--- /dev/null
+++ b/packaging/tests/guard_vectors.json
@@ -0,0 +1,236 @@
+{
+ "baseline": {
+  ".github/workflows/ci.yml": "jobs:\n  update-e2e:\n    steps:\n      - name: update-e2e\n        if: runner.os == 'Windows'\n        run: |\n          cargo test --release -p unlucky-cli --features update-test-source \\\n            --test update_e2e_test --test update_e2e_tamper_test\n",
+  ".github/workflows/release-build.yml": "jobs:\n  update-e2e:\n    steps:\n      - run: cargo build --release\n",
+  ".github/workflows/release-publish.yml": "jobs:\n  update-e2e:\n    steps:\n      - run: echo publish\n",
+  "packaging/make_artifacts.py": "def build():\n    return 'cargo build --release'\n",
+  "packaging/tests/build.sh": "#!/bin/sh\ncargo build --release\n",
+  "Makefile": "build:\n\tcargo build --release\n",
+  "Cargo.toml": "[workspace]\nmembers = []\n",
+  "crates/core/Cargo.toml": "[features]\nupdate-test-source = []\n# 注释里提到它不算违规\n"
+ },
+ "vectors": [
+  {
+   "label": "allowlist：ci.yml 的 update-e2e 一步",
+   "expect": "green",
+   "files": {}
+  },
+  {
+   "label": "allowlist：同一步放进 release-build.yml",
+   "expect": "red",
+   "files": {
+    ".github/workflows/release-build.yml": "jobs:\n  update-e2e:\n    steps:\n      - name: update-e2e\n        if: runner.os == 'Windows'\n        run: |\n          cargo test --release -p unlucky-cli --features update-test-source \\\n            --test update_e2e_test --test update_e2e_tamper_test\n"
+   }
+  },
+  {
+   "label": "allowlist：步骤名改成 update-e2e-r2",
+   "expect": "red",
+   "files": {
+    ".github/workflows/ci.yml": "jobs:\n  update-e2e:\n    steps:\n      - name: update-e2e-r2\n        if: runner.os == 'Windows'\n        run: |\n          cargo test --release -p unlucky-cli --features update-test-source \\\n            --test update_e2e_test --test update_e2e_tamper_test\n"
+   }
+  },
+  {
+   "label": "allowlist：少了 --test update_e2e_test",
+   "expect": "red",
+   "files": {
+    ".github/workflows/ci.yml": "jobs:\n  update-e2e:\n    steps:\n      - name: update-e2e\n        if: runner.os == 'Windows'\n        run: |\n          cargo test --release -p unlucky-cli --features update-test-source \\\n            --test update_e2e_tamper_test\n"
+   }
+  },
+  {
+   "label": "allowlist：发布工作流里另起一步",
+   "expect": "red",
+   "files": {
+    ".github/workflows/release-publish.yml": "jobs:\n  update-e2e:\n    steps:\n      - name: leak\n      - run: cargo build --release --features update-test-source\n"
+   }
+  },
+  {
+   "label": "allowlist：ci.yml 里另一个具名步骤",
+   "expect": "red",
+   "files": {
+    ".github/workflows/ci.yml": "jobs:\n  update-e2e:\n    steps:\n      - name: update-e2e\n        if: runner.os == 'Windows'\n        run: |\n          cargo test --release -p unlucky-cli --features update-test-source \\\n            --test update_e2e_test --test update_e2e_tamper_test\n      - name: another\n      - run: cargo build --release --features update-test-source\n"
+   }
+  },
+  {
+   "label": "P2-1 ①：末尾追加无名步骤",
+   "expect": "red",
+   "files": {
+    ".github/workflows/ci.yml": "jobs:\n  update-e2e:\n    steps:\n      - name: update-e2e\n        if: runner.os == 'Windows'\n        run: |\n          cargo test --release -p unlucky-cli --features update-test-source \\\n            --test update_e2e_test --test update_e2e_tamper_test\n      - run: cargo build --release --features update-test-source\n"
+   }
+  },
+  {
+   "label": "P2-1 ②：末尾追加无名步骤的整个 job",
+   "expect": "red",
+   "files": {
+    ".github/workflows/ci.yml": "jobs:\n  update-e2e:\n    steps:\n      - name: update-e2e\n        if: runner.os == 'Windows'\n        run: |\n          cargo test --release -p unlucky-cli --features update-test-source \\\n            --test update_e2e_test --test update_e2e_tamper_test\n  release-from-ci:\n    steps:\n      - run: cargo build --release --features update-test-source\n"
+   }
+  },
+  {
+   "label": "P2-1 ③：flow 风格步骤",
+   "expect": "red",
+   "files": {
+    ".github/workflows/ci.yml": "jobs:\n  update-e2e:\n    steps:\n      - name: update-e2e\n        if: runner.os == 'Windows'\n        run: |\n          cargo test --release -p unlucky-cli --features update-test-source \\\n            --test update_e2e_test --test update_e2e_tamper_test\n      - {name: release-build, run: \"cargo build --features update-test-source\"}\n"
+   }
+  },
+  {
+   "label": "P2-1 ④：步骤写在 jobs: 之前（孤儿行）",
+   "expect": "red",
+   "files": {
+    ".github/workflows/ci.yml": "      - run: cargo build --release --features update-test-source\njobs:\n  update-e2e:\n    steps:\n      - run: echo hi\n"
+   }
+  },
+  {
+   "label": "P2-1 ⑤：`run: |` 块里伪造 `name: update-e2e`",
+   "expect": "red",
+   "files": {
+    ".github/workflows/ci.yml": "jobs:\n  update-e2e:\n    steps:\n      - run: |\n          echo 'name: update-e2e'\n          cargo build --release --features update-test-source\n"
+   }
+  },
+  {
+   "label": "P2-2 ①：`#` 在引号内、真命令在后面",
+   "expect": "red",
+   "files": {
+    ".github/workflows/release-build.yml": "jobs:\n  update-e2e:\n    steps:\n      - run: echo \"#\"; cargo build --features update-test-source\n"
+   }
+  },
+  {
+   "label": "P2-2 ②：shell 变量拼接（字面量仍在）",
+   "expect": "red",
+   "files": {
+    ".github/workflows/release-build.yml": "jobs:\n  update-e2e:\n    steps:\n      - run: FEAT=\"update-test-source\"; cargo build --features \"$FEAT\"\n"
+   }
+  },
+  {
+   "label": "Cargo ①：default 把 feature 带上",
+   "expect": "red",
+   "files": {
+    "crates/core/Cargo.toml": "[features]\nupdate-test-source = []\n# 注释里提到它不算违规\ndefault = [\"update-test-source\"]\n"
+   }
+  },
+  {
+   "label": "Cargo ②：别的 feature 依赖它",
+   "expect": "red",
+   "files": {
+    "crates/core/Cargo.toml": "[features]\nupdate-test-source = []\n# 注释里提到它不算违规\nrelease = [\"update-test-source\"]\n"
+   }
+  },
+  {
+   "label": "误杀 ①：注释里提到该 feature",
+   "expect": "green",
+   "files": {
+    ".github/workflows/release-build.yml": "jobs:\n  update-e2e:\n    steps:\n      # 这里不许加 update-test-source\n      - run: cargo build --release\n"
+   }
+  },
+  {
+   "label": "误杀 ②：允许的那一步把 `run:` 写在 `name:` 之前（键序无关）",
+   "expect": "green",
+   "files": {
+    ".github/workflows/ci.yml": "jobs:\n  update-e2e:\n    steps:\n      - run: cargo test --release --features update-test-source --test update_e2e_test\n        name: update-e2e\n"
+   }
+  },
+  {
+   "label": "误杀 ③：`cargo hack check --all-targets`（不打开任何 feature）",
+   "expect": "green",
+   "files": {
+    ".github/workflows/release-build.yml": "jobs:\n  update-e2e:\n    steps:\n      - run: cargo hack check --all-targets\n"
+   }
+  },
+  {
+   "label": "误杀 ④：Cargo 多行 feature 声明",
+   "expect": "green",
+   "files": {
+    "crates/core/Cargo.toml": "[features]\nupdate-test-source = [\n    \"unlucky-core/update-test-source\",\n    \"unlucky-cli/update-test-source\",\n]\n"
+   }
+  },
+  {
+   "label": "P2-2：cargo hack --feature-powerset",
+   "expect": "red",
+   "files": {
+    ".github/workflows/release-build.yml": "jobs:\n  update-e2e:\n    steps:\n      - run: cargo hack --feature-powerset build\n"
+   }
+  },
+  {
+   "label": "P2-2：cargo hack --each-feature",
+   "expect": "red",
+   "files": {
+    ".github/workflows/release-build.yml": "jobs:\n  update-e2e:\n    steps:\n      - run: cargo hack --each-feature build\n"
+   }
+  },
+  {
+   "label": "P2-2：cargo hack --all",
+   "expect": "red",
+   "files": {
+    ".github/workflows/release-build.yml": "jobs:\n  update-e2e:\n    steps:\n      - run: cargo hack --all build\n"
+   }
+  },
+  {
+   "label": "P2-2 扫描面：packaging/tests/build.sh",
+   "expect": "red",
+   "files": {
+    "packaging/tests/build.sh": "#!/bin/sh\ncargo build --features update-test-source\n"
+   }
+  },
+  {
+   "label": "P2-2 扫描面：.github/actions/rebuild/action.yml",
+   "expect": "red",
+   "files": {
+    ".github/actions/rebuild/action.yml": "runs:\n  using: composite\n  steps:\n    - run: cargo build --features update-test-source\n      shell: bash\n"
+   }
+  },
+  {
+   "label": "P2-2 扫描面：.github/workflows/nested/extra.yml",
+   "expect": "red",
+   "files": {
+    ".github/workflows/nested/extra.yml": "jobs:\n  update-e2e:\n    steps:\n      - run: cargo build --release --features update-test-source\n"
+   }
+  },
+  {
+   "label": "P2-2 扫描面：Makefile",
+   "expect": "red",
+   "files": {
+    "Makefile": "build:\n\tcargo build --release --features update-test-source\n"
+   }
+  },
+  {
+   "label": "P2-1 ⑥：`name:` 写在更深缩进的 env 子项里",
+   "expect": "red",
+   "files": {
+    ".github/workflows/ci.yml": "jobs:\n  update-e2e:\n    steps:\n      - name: update-e2e\n        if: runner.os == 'Windows'\n        run: |\n          cargo test --release -p unlucky-cli --features update-test-source \\\n            --test update_e2e_test --test update_e2e_tamper_test\n      - run: cargo build --release -p unlucky-cli --features update-test-source\n        env:\n          T: --test update_e2e_test\n          HINT: |\n            - name: update-e2e\n"
+   }
+  },
+  {
+   "label": "P2-1 ⑦：`name:` 写在 `run: |` 块标量里",
+   "expect": "red",
+   "files": {
+    ".github/workflows/ci.yml": "jobs:\n  update-e2e:\n    steps:\n      - name: update-e2e\n        if: runner.os == 'Windows'\n        run: |\n          cargo test --release -p unlucky-cli --features update-test-source \\\n            --test update_e2e_test --test update_e2e_tamper_test\n      - run: |\n          name: update-e2e\n          cargo build --release --features update-test-source --test update_e2e_test\n"
+   }
+  },
+  {
+   "label": "P2-1 ⑧：同一项里两个不同的 `name:`",
+   "expect": "red",
+   "files": {
+    ".github/workflows/ci.yml": "jobs:\n  update-e2e:\n    steps:\n      - name: update-e2e\n        run: cargo build --release --features update-test-source --test update_e2e_test\n        name: release-build\n"
+   }
+  },
+  {
+   "label": "P2-2 ①：.cargo/config.toml 用 `--cfg feature=` 开该 feature",
+   "expect": "red",
+   "files": {
+    ".cargo/config.toml": "[build]\nrustflags = [\"--cfg\", 'feature=\"update-test-source\"']\n"
+   }
+  },
+  {
+   "label": "P2-2 ②：.cargo/config.toml 设 rustc-wrapper",
+   "expect": "red",
+   "files": {
+    ".cargo/config.toml": "[build]\nrustc-wrapper = \"./tools/wrapper\"\n"
+   }
+  },
+  {
+   "label": "误杀 ⑤：普通 .cargo/config.toml（无 feature / 无 wrapper）",
+   "expect": "green",
+   "files": {
+    ".cargo/config.toml": "[build]\njobs = 4\n"
+   }
+  }
+ ]
+}
diff --git a/packaging/tests/manifest.golden.json b/packaging/tests/manifest.golden.json
new file mode 100644
index 0000000..403794a
--- /dev/null
+++ b/packaging/tests/manifest.golden.json
@@ -0,0 +1,29 @@
+{
+  "channel": "stable",
+  "releases": [
+    {
+      "version": "9.9.9",
+      "channel": "stable",
+      "released_at": "2026-01-02T03:04:05Z",
+      "notes": "golden 样例（自验用，不是真实发布）",
+      "force": false,
+      "min_supported": "9.0.0",
+      "artifacts": [
+        {
+          "target": "win-x64",
+          "format": "portable-exe",
+          "url": "unlucky-launcher_9.9.9_windows_x64.exe",
+          "size": 12,
+          "sha256": "8ac2dbaad20a7b318a75485359b0302d6d2550093b69296cea39db18d4836ef0"
+        },
+        {
+          "target": "linux-x64",
+          "format": "portable-zip",
+          "url": "unlucky-launcher_9.9.9_linux_x64.tar.gz",
+          "size": 12,
+          "sha256": "dcd549d0571bb74eaee60af5c0bc702714fb0de052094336ab10e1e0c7faea0e"
+        }
+      ]
+    }
+  ]
+}
diff --git a/packaging/tests/signing_ready_selftest.py b/packaging/tests/signing_ready_selftest.py
new file mode 100644
index 0000000..cb63cfc
--- /dev/null
+++ b/packaging/tests/signing_ready_selftest.py
@@ -0,0 +1,399 @@
+#!/usr/bin/env python3
+"""`packaging/check_signing_ready.py` 的判据自测（M255）：让「三行读数 + 0/1/2 退出码」变成可执行的事实。
+
+为什么它必须存在：这个脚本的全部价值是「说清今天差什么」。它一旦退化成「永远 exit 0」，
+它就从**播报**变成了本仓栽过四次的**假绿尺子** —— 而且没人会当场发现（输出看起来一模一样）。
+所以这里的第一类用例判的是退出码语义，第二类用例判的是**把退出码改绿之后自测会红**（变异重放）。
+
+| 用例 | 抓什么 |
+|---|---|
+| `empty_table` | ① 表空 ⇒ `exit 1`、三行都打印、有 fail-closed 句 + 修复行 |
+| `pinned_and_key` | ② 副本夹假 `PinnedKey` ⇒ `exit 0`（**不碰真实 `trust.rs`**），且不泄种子 |
+| `mutation` A/B | 退出码永远 0 ⇒ 判据①必须红；永远 1 ⇒ 判据②必须红（两向都要） |
+| `key_mismatch` / `no_key` / `release_*` | ② 对账、③ 有/无/未知（含 `.sig` 子串假读数）、③ 不参与退出码 |
+| `key_unreadable` | `--key` 不存在 / 是目录 ⇒ **2**（不是 1，也不是 traceback —— r1 P2-2） |
+| `withheld` | 非 main ref ⇒ ② 写「未判定」+ 原因，**不写「没配」**（r1 P2-1 第三条） |
+| `section_refs` | 输出里每个 `§N` 都是 runbook 真实章节号（r1 P2-3） |
+| `stray_hint` / `no_seed_leak` / `usage` / `summary` | ① 标记外条目只点名不误报、种子不出现、用法错 = 2、`--line` 写 summary |
+
+接线（不是门禁 / 不被 `uses:` / **ref 门** / 文档路径存在性）在
+**`packaging/tests/signing_ready_wiring_selftest.py`** —— 拆成两份只因为全仓 400 行红线。
+两份都不覆盖「整个 workflow 被删掉」（守门人住在被守对象旁边，与 `gpu_shot_ci_selftest.py` 同一条边界）。
+
+`DUMMY_SEED` 是**由一句固定文本哈希出来的**假种子（同 `trust.rs` 里 `TEST_ONLY` 那把公开测试钥同一路数），
+只用来造读数，签不出任何正式清单；文档与本文件都不含任何真实私钥。
+
+    python3 packaging/tests/signing_ready_selftest.py
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent.parent
+SCRIPT = ROOT / "packaging/check_signing_ready.py"
+RUNBOOK = ROOT / "packaging/docs/signing-runbook.md"
+KEY_ENV = "ULL_MANIFEST_SIGNING_KEY"
+WITHHELD_ENV = "ULL_SIGNING_KEY_WITHHELD"
+FAIL_CLOSED = "这会让已安装用户永远验不过（fail-closed）"
+LABELS = ("① 信任表 PRODUCTION", "② 环境签名钥", "③ 最近一次发布痕迹")
+
+sys.path.insert(0, str(ROOT / "packaging"))
+from ed25519_ref import public_key  # noqa: E402
+
+DUMMY_SEED = hashlib.sha256(b"ull-m255-signing-ready-selftest-not-a-real-key").hexdigest()
+DUMMY_PUB = public_key(bytes.fromhex(DUMMY_SEED)).hex()
+OTHER_SEED = hashlib.sha256(b"ull-m255-selftest-the-other-dummy-key").hexdigest()
+
+TRUST_TEMPLATE = """\
+pub(crate) const PRODUCTION: &[PinnedKey] = &[
+    // >>> PINNED-KEYS >>>
+{body}    // <<< PINNED-KEYS <<<
+];
+"""
+
+
+def secret_json(seed: str = DUMMY_SEED, key_id: str = "selftest-key") -> str:
+    return '{"key_id": "%s", "seed_hex": "%s"}' % (key_id, seed)
+
+
+def write(path: Path, text: str) -> Path:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(text, encoding="utf-8", newline="\n")
+    return path
+
+
+def run(
+    args: list[str],
+    env_key: str | None,
+    summary: Path | None = None,
+    script: Path = SCRIPT,
+    withheld: str | None = None,
+) -> tuple[int, str]:
+    """跑一次脚本，返回 `(退出码, stdout+stderr)`。
+
+    `env_key` = 塞进 `KEY_ENV` 的内容（`None` = 不设）；`withheld` = 塞进 `WITHHELD_ENV` 的内容。
+    两个 key 都先**从父环境剔除**再按参数注入：否则本机残留的变量会让用例假绿。
+    """
+    env = {k: v for k, v in os.environ.items() if k not in (KEY_ENV, WITHHELD_ENV)}
+    env.pop("GITHUB_STEP_SUMMARY", None)
+    # 子进程与父进程的编码显式对齐成 UTF-8：本机 Windows 默认 gbk，中文读数会 decode 失败，
+    # 而 CI（ubuntu）本来就是 UTF-8。这条不是洁癖 —— 编码不一致会让整份自测在 Windows 上假红/假绿。
+    env["PYTHONIOENCODING"] = "utf-8"
+    if env_key is not None:
+        env[KEY_ENV] = env_key
+    if withheld is not None:
+        env[WITHHELD_ENV] = withheld
+    if summary is not None:
+        env["GITHUB_STEP_SUMMARY"] = str(summary)
+    done = subprocess.run(
+        [sys.executable, str(script), *args],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        env=env,
+        cwd=str(ROOT),
+        check=False,
+    )
+    return done.returncode, done.stdout + done.stderr
+
+
+def case_empty_table(work: Path, failures: list[str], script: Path = SCRIPT) -> None:
+    """① 今天的状态：空表 ⇒ exit 1，三行都要打印，且必须点明 fail-closed 后果与修复命令。
+
+    `script` 可换：变异用例把**同一组断言**原样套在「退出码永远 0」的副本上，断言集合必须报红。
+    """
+    trust = write(work / "empty/trust.rs", TRUST_TEMPLATE.format(body=""))
+    rc, out = run(["--trust", str(trust)], None, script=script)
+    if rc != 1:
+        failures.append(f"判据①：空表应 exit 1，实际 {rc}\n{out}")
+    missing = [label for label in LABELS if label not in out]
+    if missing:
+        failures.append(f"判据①：空表时没打印这三行中的 {missing}\n{out}")
+    if FAIL_CLOSED not in out:
+        failures.append(f"判据①：未就绪时必须写明「{FAIL_CLOSED}」（后果，不是术语）\n{out}")
+    if "修复：" not in out:
+        failures.append(f"判据①：未就绪时必须给一行修复命令\n{out}")
+
+
+def case_pinned_and_key(work: Path, failures: list[str], script: Path = SCRIPT) -> None:
+    """② 副本里夹一条假 PinnedKey + 环境里是同一把钥 ⇒ exit 0（真实 trust.rs 一个字节都不碰）。"""
+    body = f'    PinnedKey {{ key_id: "selftest-key", public_key_hex: "{DUMMY_PUB}" }},\n'
+    trust = write(work / "pinned/trust.rs", TRUST_TEMPLATE.format(body=body))
+    rc, out = run(["--trust", str(trust)], secret_json(), script=script)
+    if rc != 0:
+        failures.append(f"判据②：表非空 + 钥同源应 exit 0，实际 {rc}\n{out}")
+    missing = [label for label in LABELS if label not in out]
+    if missing:
+        failures.append(f"判据②：就绪时也要打印三行，缺 {missing}\n{out}")
+    if "就绪" not in out:
+        failures.append(f"判据②：就绪时必须明说「就绪」\n{out}")
+    if FAIL_CLOSED in out:
+        failures.append(f"判据②：就绪时不该出现 fail-closed 那段警告\n{out}")
+    # 不泄密：种子的十六进制在输出里一次都不许出现（公钥可以出现，它是公开物）。
+    if DUMMY_SEED in out:
+        failures.append(f"判据②：输出里出现了**种子**（私钥）—— 这是泄密\n{out}")
+
+
+def case_key_mismatch(work: Path, failures: list[str]) -> None:
+    """② 的对账：表里钉的是 A，环境里是 B ⇒ 未就绪（发布时 --check-pinned-keyring 会红）。"""
+    body = f'    PinnedKey {{ key_id: "selftest-key", public_key_hex: "{DUMMY_PUB}" }},\n'
+    trust = write(work / "mismatch/trust.rs", TRUST_TEMPLATE.format(body=body))
+    rc, out = run(["--trust", str(trust)], secret_json(OTHER_SEED, "other-key"))
+    if rc != 1:
+        failures.append(f"②对账：钥不在表里应 exit 1，实际 {rc}\n{out}")
+    if "不在" not in out:
+        failures.append(f"②对账：必须明说这把钥不在信任表里\n{out}")
+    if DUMMY_SEED in out or OTHER_SEED in out:
+        failures.append(f"②对账：输出里出现了种子\n{out}")
+
+
+def case_no_key(work: Path, failures: list[str]) -> None:
+    """② 没有钥：即便表是好的，也算未就绪（签不出任何清单）。"""
+    body = f'    PinnedKey {{ key_id: "selftest-key", public_key_hex: "{DUMMY_PUB}" }},\n'
+    trust = write(work / "nokey/trust.rs", TRUST_TEMPLATE.format(body=body))
+    rc, out = run(["--trust", str(trust)], None)
+    if rc != 1:
+        failures.append(f"②无钥：应 exit 1，实际 {rc}\n{out}")
+    if KEY_ENV not in out:
+        failures.append(f"②无钥：必须点名环境变量 {KEY_ENV}（换个人也知道该配什么）\n{out}")
+
+
+def case_release_evidence(work: Path, failures: list[str]) -> None:
+    """③ 只取证：有留档 / 有清单没签名 / 什么都没给 = 未知；且它不影响退出码。"""
+    body = f'    PinnedKey {{ key_id: "selftest-key", public_key_hex: "{DUMMY_PUB}" }},\n'
+    trust = write(work / "release/trust.rs", TRUST_TEMPLATE.format(body=body))
+    signed = work / "release/signed"
+    write(signed / "manifest.json", '{"channel": "stable", "releases": []}\n')
+    write(signed / "manifest.json.sig", '{"format": 1, "signatures": []}\n')
+    rc, out = run(["--trust", str(trust), "--dist", str(signed)], secret_json())
+    if rc != 0 or "有 ——" not in out:
+        failures.append(f"③有：留档齐全时应写「有」且退出码仍是 0，实际 rc={rc}\n{out}")
+
+    bare = work / "release/bare"
+    write(bare / "manifest.json", '{"channel": "stable", "releases": []}\n')
+    rc, out = run(["--trust", str(trust), "--dist", str(bare)], secret_json())
+    if "没有" not in out:
+        failures.append(f"③无：只有 manifest.json 时必须点明「没有 .sig」\n{out}")
+
+    nowhere = work / "release/absent"
+    rc, out = run(["--trust", str(trust), "--dist", str(nowhere)], secret_json())
+    if "未知" not in out:
+        failures.append(f"③未知：取不到证据时必须写「未知」，不许写成「无」（本地没留档 ≠ 上次没签）\n{out}")
+    if rc != 0:
+        failures.append(f"③未知：③ 不参与就绪判定，退出码应仍是 0，实际 {rc}\n{out}")
+
+
+def case_usage(work: Path, failures: list[str]) -> None:
+    """用法错 = 2：参数写错、标记丢了（脚本形不成判断）。绝不能混进 1（那是「未就绪」的读数）。"""
+    rc, out = run(["--nonsense"], None)
+    if rc != 2:
+        failures.append(f"用法错：未知参数应 exit 2，实际 {rc}\n{out}")
+    broken = write(work / "broken/trust.rs", "pub(crate) const PRODUCTION: &[PinnedKey] = &[];\n")
+    rc, out = run(["--trust", str(broken)], None)
+    if rc != 2:
+        failures.append(f"用法错：标记缺失应 exit 2（不是 1），实际 {rc}\n{out}")
+    rc, out = run(["--trust", str(work / "no-such-dir/trust.rs")], None)
+    if rc != 2:
+        failures.append(f"用法错：trust.rs 不存在应 exit 2，实际 {rc}\n{out}")
+
+
+def case_summary(work: Path, failures: list[str]) -> None:
+    """`--line`：CI 用，把三行搬进 $GITHUB_STEP_SUMMARY；且必须写明「不是门禁」。"""
+    trust = write(work / "summary/trust.rs", TRUST_TEMPLATE.format(body=""))
+    summary = work / "summary-step.md"
+    rc, out = run(["--trust", str(trust), "--line"], None, summary=summary)
+    if rc != 1:
+        failures.append(f"summary：空表仍应 exit 1，实际 {rc}\n{out}")
+    if not summary.is_file():
+        failures.append("summary：给了 $GITHUB_STEP_SUMMARY 却没写文件")
+        return
+    text = summary.read_text(encoding="utf-8")
+    missing = [label for label in LABELS if label not in text]
+    if missing:
+        failures.append(f"summary：三行没全部进 summary，缺 {missing}\n{text}")
+    if "不代表签名就绪" not in text:
+        failures.append(f"summary：必须写清「绿色不代表签名就绪」（播报 ≠ 门禁）\n{text}")
+
+
+TARGET_LINE = "    return 0 if ready else 1\n"
+
+
+def mutant(work: Path, name: str, replacement: str) -> Path | None:
+    """造一份「只改了退出码那一行」的副本。副本自成一体（模块一起拷）：脚本按 `__file__` 上一级找
+    `packaging/`，不靠 PYTHONPATH（实测本机 3.12 根本不把 PYTHONPATH 放进 sys.path）。"""
+    source = SCRIPT.read_text(encoding="utf-8")
+    if source.count(TARGET_LINE) != 1:
+        return None
+    root = work / name
+    path = write(root / "packaging/check_signing_ready_mutated.py", source.replace(TARGET_LINE, replacement))
+    for module in ("sign_manifest.py", "ed25519_ref.py"):
+        write(root / f"packaging/{module}", (ROOT / f"packaging/{module}").read_text(encoding="utf-8"))
+    write(root / "trust.rs", TRUST_TEMPLATE.format(body=""))
+    return path
+
+
+def case_stray_hint(work: Path, failures: list[str]) -> None:
+    """① 的「标记之外还有条目」提示：只**点名**，不替人断言「贴错了」。
+
+    实测抓到的误报：真实 `trust.rs` 里 `TEST_ONLY` 那一条**本来就在标记之外**（那是它的正确位置），
+    上一版措辞「另有 N 条写在标记之外（贴错位置，等于没钉）」会对今天的状态喊狼来了。
+    """
+    outside = 'pub(crate) const TEST_ONLY: &[PinnedKey] = &[PinnedKey { key_id: "test-only-key", public_key_hex: "%s" }];\n'
+    trust = write(
+        work / "stray/trust.rs",
+        outside % ("ab" * 32) + TRUST_TEMPLATE.format(body=""),
+    )
+    rc, out = run(["--trust", str(trust)], None)
+    if rc != 1:
+        failures.append(f"①提示：标记外有条目时表仍是空的 ⇒ 应 exit 1，实际 {rc}\n{out}")
+    if "test-only-key" not in out:
+        failures.append(f"①提示：标记之外的条目必须**点名**（否则人不知道贴漏了哪一条）\n{out}")
+    if "TEST_ONLY" not in out:
+        failures.append(f"①提示：必须说清 `TEST_ONLY` 本来就在标记之外（否则这就是一句误报）\n{out}")
+
+
+def case_key_unreadable(work: Path, failures: list[str]) -> None:
+    """② `--key` 指向读不了的路径 ⇒ **2**（用法错），不是 1、也不是 traceback（r1 P2-2）。
+
+    `read_text` 曾在 `main()` 的 try 之外 ⇒ `FileNotFoundError` 直接抛成 rc=1，与「未就绪」同码。
+    脚本的全部价值是「退出码可信」：1 和 2 混了，「我路径写错了」会被读成「签名没配好」。
+    """
+    body = f'    PinnedKey {{ key_id: "selftest-key", public_key_hex: "{DUMMY_PUB}" }},\n'
+    trust = write(work / "badkey/trust.rs", TRUST_TEMPLATE.format(body=body))
+    directory = work / "badkey/a-directory"
+    directory.mkdir(parents=True, exist_ok=True)
+    for label, path in (
+        ("不存在", work / "badkey/no-such.key"),
+        ("是目录", directory),
+    ):
+        rc, out = run(["--trust", str(trust), "--key", str(path)], None)
+        if rc != 2:
+            failures.append(f"--key（{label}）应 exit 2，实际 {rc}\n{out}")
+        if "Traceback" in out:
+            failures.append(f"--key（{label}）不许抛未捕获异常（traceback 会盖掉一行说明）\n{out}")
+        if "用法错" not in out:
+            failures.append(f"--key（{label}）必须说清这是用法错，不是「未就绪」\n{out}")
+        if LABELS[0] in out or LABELS[1] in out:
+            failures.append(f"--key（{label}）在形不成判断时不该打印三行读数（会被读成「读数」）\n{out}")
+
+
+def case_withheld(work: Path, failures: list[str]) -> None:
+    """② 非 main ref：写「未判定 + 原因」，**不写「没配」**（r1 P2-1 第三条）。
+
+    同一份空钥输入，有没有 `ULL_SIGNING_KEY_WITHHELD` 是两件事：「策略上不注入」不是「仓库没配置」。
+    """
+    body = f'    PinnedKey {{ key_id: "selftest-key", public_key_hex: "{DUMMY_PUB}" }},\n'
+    trust = write(work / "withheld/trust.rs", TRUST_TEMPLATE.format(body=body))
+    reason = "非 main ref（按设计不注入 Secret；要读这一行请对 main 跑）"
+    rc, out = run(["--trust", str(trust)], None, withheld=reason)
+    if rc != 1:
+        failures.append(f"未判定：这一趟没钥可读 ⇒ 不许声称就绪（应 exit 1），实际 {rc}\n{out}")
+    if "未判定" not in out or reason not in out:
+        failures.append(f"未判定：② 必须写「未判定」+ 原因串（否则会被读成「没配」）\n{out}")
+    if "未注入" not in out:
+        failures.append(f"未判定：② 必须写出「未注入」这个动作（「策略不注入」与「没配置」是两件事）\n{out}")
+    if "未设置" in out:
+        failures.append(f"未判定：非 main ref 上不许出现「未设置」（那是「没配」的措辞）\n{out}")
+    # 反方向：没有 withheld 时照样得说「未设置/为空」，别把两档并成一档。
+    rc, out = run(["--trust", str(trust)], None)
+    if "未设置" not in out:
+        failures.append(f"未判定：没有 withheld 时仍应报「未设置/为空」（两档不许合并）\n{out}")
+
+
+def case_section_refs(work: Path, failures: list[str]) -> None:
+    """输出里出现的每个 `§N` 都必须是 runbook **真实存在**的章节号（r1 P2-3）。
+
+    上一版把「贴 PinnedKey」指到 §3（那里讲发布时的执行顺序）、把「发布后回验」指到 §4（那里是已知坑）。
+    本文件的交付物就是「一行可照抄的指针」，所以指针要机器校验。
+    """
+    sections = set(re.findall(r"^##\s*(\d+)\.", RUNBOOK.read_text(encoding="utf-8"), re.MULTILINE))
+    if not sections:
+        failures.append("指针：runbook 里一个 `## N.` 标题都没解析到（章节号格式变了？）")
+        return
+    body = f'    PinnedKey {{ key_id: "selftest-key", public_key_hex: "{DUMMY_PUB}" }},\n'
+    trust = write(work / "pointer/trust.rs", TRUST_TEMPLATE.format(body=body))
+    empty = write(work / "pointer/empty.rs", TRUST_TEMPLATE.format(body=""))
+    seen: set[str] = set()
+    for args, key in (
+        (["--trust", str(trust)], secret_json()),  # 就绪：结论指向步⑤ / §5
+        (["--trust", str(trust)], None),  # ② 没钥：指向步②
+        (["--trust", str(empty)], None),  # ① 空表：修复行指向步①–③
+    ):
+        seen |= set(re.findall(r"§(\d+)", run(args, key)[1]))
+    if not seen:
+        failures.append("指针：一条 `§N` 都没从输出里抓到（用例失效了）")
+    unknown = sorted(seen - sections)
+    if unknown:
+        failures.append(f"指针：输出里指向了 runbook 没有的章节 {unknown}（真实章节：{sorted(sections)}）")
+
+
+def case_mutation(work: Path, failures: list[str]) -> None:
+    """变异重放：把被测对象改坏，**同一组断言原样套上去必须报红**（两个方向）。
+    （接线/ref 门那一侧的变异在 `signing_ready_wiring_selftest.py`。）"""
+    # ── 变异 A：退出码永远 0（「未就绪」伪装成「就绪」）⇒ 判据① 必须红 ──
+    always_zero = mutant(work, "mutant-zero", "    return 0\n")
+    if always_zero is None:
+        failures.append(f"变异 A：{SCRIPT.name} 里找不到唯一的 `{TARGET_LINE.strip()}`，变异无处下手（脚本形状变了就更新这里）")
+    else:
+        trust = work / "mutant-zero/trust.rs"
+        probe: list[str] = []
+        case_empty_table(work / "mutant-zero", probe, script=always_zero)
+        # 副本必须真的「跑得起来、只有退出码变了」：崩溃（rc=2）也会让 probe 非空，那就变成假绿了。
+        rc, out = run(["--trust", str(trust)], None, script=always_zero)
+        if rc != 0:
+            failures.append(f"变异 A：副本在空表上应返回 0（这就是变异本身），实际 {rc}\n{out}")
+        missing = [label for label in LABELS if label not in out]
+        if missing:
+            failures.append(f"变异 A：副本连三行读数都没打印（缺 {missing}），它不是在测退出码那一条\n{out}")
+        if not probe:
+            failures.append(f"变异 A：「退出码永远 0」的副本竟然让判据①全过 —— 断言抓不住改绿（副本空表返回 {rc}）")
+        elif not any("exit 1" in item for item in probe):
+            failures.append(f"变异 A：副本被判红，但不是因为退出码那一条 —— 变异用例没对准判据①：{probe}")
+
+    # ── 变异 B：退出码永远 1（「就绪」伪装成「未就绪」）⇒ 判据② 必须红 ──
+    # 反向也要试：只测一个方向的话，「就绪的正路根本不存在」这种回归仍然全绿。
+    always_one = mutant(work, "mutant-one", "    return 1\n")
+    if always_one is None:
+        failures.append(f"变异 B：{SCRIPT.name} 里找不到唯一的 `{TARGET_LINE.strip()}`")
+    else:
+        probe = []
+        case_pinned_and_key(work / "mutant-one", probe, script=always_one)
+        if not probe:
+            failures.append("变异 B：「退出码永远 1」的副本竟然让判据②全过 —— 就绪的正路没被断言（假绿的反面）")
+        elif not any("exit 0" in item for item in probe):
+            failures.append(f"变异 B：副本被判红，但不是因为退出码那一条 —— 变异用例没对准判据②：{probe}")
+
+
+def main() -> int:
+    failures: list[str] = []
+    with tempfile.TemporaryDirectory(prefix="ull-signing-ready-") as temp:
+        work = Path(temp)
+        case_empty_table(work, failures)
+        case_pinned_and_key(work, failures)
+        case_key_mismatch(work, failures)
+        case_no_key(work, failures)
+        case_release_evidence(work, failures)
+        case_stray_hint(work, failures)
+        case_key_unreadable(work, failures)
+        case_withheld(work, failures)
+        case_section_refs(work, failures)
+        case_usage(work, failures)
+        case_summary(work, failures)
+        case_mutation(work, failures)
+
+    for line in failures:
+        print(f"FAIL {line}", file=sys.stderr)
+    print("signing-ready selftest:", "ok" if not failures else f"{len(failures)} 处失败")
+    return 0 if not failures else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/packaging/tests/signing_ready_wiring_selftest.py b/packaging/tests/signing_ready_wiring_selftest.py
new file mode 100644
index 0000000..5a2b3f6
--- /dev/null
+++ b/packaging/tests/signing_ready_wiring_selftest.py
@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+"""`signing-status.yml` 的**接线**自测（M255 r1 从 `signing_ready_selftest.py` 分出）。
+
+拆成两份的唯一原因是全仓 400 行红线（`guards.yml` 的 `file-size`）：判据本体（三行读数 / `0/1/2` /
+两个方向的退出码变异）留在 `signing_ready_selftest.py`，这里只管**接线与文案里的指针**。
+
+钉住的判据（每条都对应一次真实会咬人的回归）：
+
+| 判据 | 抓什么 |
+|---|---|
+| 不是门禁 | 没有别的 workflow `uses:` 它；全文无 error 级注解；就绪度那步抓 `rc=$?` 后 `exit 0`；文件头两句口径都在 |
+| **生产种子只在 main 注入** | 注入行必须是 `github.ref == 'refs/heads/main' && secrets.` 这个条件式；`on:` 块里**不许出现 `pull_request`**；非 main 另有 `ULL_SIGNING_KEY_WITHHELD` 说明原因（于是 ② 读「未判定」而不是「没配」） |
+| 文档指针真的存在 | `signing-runbook.md` / `signing.md` 里出现的 `packaging/…`、`crates/…`、`.github/…` 路径必须真在仓库里（r1 P2-3：`signing-ready.yml` 那个文件名根本不存在） |
+| 变异必须红 | ①去掉 ref 门 ②加回 `pull_request` ③把文档里一个路径改坏 —— 三处各自重放，**对应用例必须报红** |
+
+为什么要 ref 门（这是本文件存在的最重要理由）：生产签名种子能给**全量已安装客户端**签出被信任的清单
+（自更新链 = 用户端 RCE）。仓库内分支的 PR 与任意分支的 `workflow_dispatch` 都**拿得到**仓库 Secret
+（只有 fork / Dependabot 拿不到），而 CI 会在**那个 PR 自己的代码**上执行 checker。既有设计把种子锁在
+tag ref 后面（`release.yml` 的 `if: … github.ref_type == 'tag'`），播报文件不许在旁边开一条新路。
+
+    python3 packaging/tests/signing_ready_wiring_selftest.py
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent.parent
+WORKFLOW_DIR = ROOT / ".github/workflows"
+WORKFLOW = WORKFLOW_DIR / "signing-status.yml"
+RUNBOOK = ROOT / "packaging/docs/signing-runbook.md"
+SIGNING_MD = ROOT / "packaging/docs/signing.md"
+
+sys.path.insert(0, str(ROOT / "packaging"))
+# 环境变量名从 checker 取，不写第二份字面量：两处漂开时，「ref 门注入了 A、checker 读 B」会静默失效。
+from check_signing_ready import KEY_ENV, WITHHELD_ENV  # noqa: E402
+
+MAIN_REF = "refs/heads/main"
+GATE = f"github.ref == '{MAIN_REF}' && secrets.{KEY_ENV}"
+#: 文档里允许出现的「路径」形状：仓库根的四个前缀（相对路径如 `docs/x.md` 不在此列，避免误判）。
+PATH_RE = re.compile(r"(?:packaging|crates|\.github|\.cargo)/[A-Za-z0-9_.\-]+(?:/[A-Za-z0-9_.\-]+)*")
+
+
+def on_block(text: str) -> str:
+    """取 `on:` 那一段（到下一个顶格键为止），并**去掉注释行**——注释里会正当地提到 `pull_request`。"""
+    lines = text.splitlines()
+    start = next((i for i, line in enumerate(lines) if re.match(r"^on:\s*$", line)), None)
+    if start is None:
+        return ""
+    body: list[str] = []
+    for line in lines[start + 1 :]:  # 跳过 `on:` 那一行本身（它顶格，会让下面的 break 立刻触发）
+        if line.startswith(" ") or not line:
+            if not line.strip().startswith("#"):
+                body.append(line)
+            continue
+        break
+    return "\n".join(body)
+
+
+def check_workflow(text: str) -> list[str]:
+    """返回该 workflow 文本没过的接线判据（空 = 通过）。变异用例把同一函数套在改坏的副本上。"""
+    problems: list[str] = []
+    for phrase in ("播报，不是门禁", "不应被设为 required"):
+        if phrase not in text:
+            problems.append(f"文件头必须写清「{phrase}」（不阻断要是可核的事实，不是靠没接线）")
+    if "::error::" in text:
+        problems.append("播报 workflow 里不许出现 error 级注解（会让人以为构建挂了，与播报定位冲突）")
+    if "rc=$?" not in text or "exit 0" not in text:
+        problems.append("就绪度那一步必须抓 `rc=$?` 后 `exit 0`（未就绪不许让 job 变红）")
+    # ── 安全口径：生产签名种子只在 main 注入 ──
+    if GATE not in text:
+        problems.append(f"注入行必须是 `{GATE} || ''` 这个条件式（去掉 ref 门 = 把种子交给任意分支的代码）")
+    if f"{WITHHELD_ENV}:" not in text:
+        problems.append(f"非 main 分支必须给 `{WITHHELD_ENV}` 一个原因串（否则 ② 会报假的「没配」）")
+    if "pull_request" in on_block(text):
+        problems.append("`on:` 块里不许出现 `pull_request`（仓库内分支的 PR 拿得到 Secret，而 CI 跑的是 PR 自己的代码）")
+    return problems
+
+
+def wired_elsewhere() -> list[str]:
+    """扫全部 workflow：有人 `uses:` 本文件 ⇒ 播报变成了别人的必需检查。"""
+    hits: list[str] = []
+    for path in sorted(WORKFLOW_DIR.glob("*.y*ml")):
+        if path.resolve() == WORKFLOW.resolve():
+            continue
+        for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
+            if re.match(r"^\s*uses:\s*", line) and WORKFLOW.name in line:
+                hits.append(f"{path.relative_to(ROOT).as_posix()}:{number}: {line.strip()}")
+    return hits
+
+
+def check_doc_paths(text: str, where: str) -> list[str]:
+    """文档里出现的仓库路径必须真实存在（r1 P2-3：指针错会把人送到无关文件/章节）。"""
+    problems: list[str] = []
+    for token in sorted(set(PATH_RE.findall(text))):
+        if not (ROOT / token).exists():
+            problems.append(f"{where} 里写了不存在的路径：{token}")
+    return problems
+
+
+def case_wiring(failures: list[str]) -> None:
+    """真实文件的接线判据 + 文档路径存在性。"""
+    if not WORKFLOW.is_file():
+        failures.append(f"接线：{WORKFLOW} 不存在")
+        return
+    text = WORKFLOW.read_text(encoding="utf-8")
+    failures.extend(f"接线：{item}" for item in check_workflow(text))
+    hits = wired_elsewhere()
+    if hits:
+        failures.append("接线：有 workflow `uses:` 了 " + WORKFLOW.name + " ⇒ 播报变成了别人的必需检查：\n  " + "\n  ".join(hits))
+    for doc in (RUNBOOK, SIGNING_MD):
+        failures.extend(f"指针：{item}" for item in check_doc_paths(doc.read_text(encoding="utf-8"), doc.name))
+
+
+def case_mutation(failures: list[str]) -> None:
+    """变异重放：把接线改坏，**同一组判据原样套上去必须报红**（r1 收尾要求的第 ④ 项）。"""
+    real = WORKFLOW.read_text(encoding="utf-8")
+    if GATE not in real:
+        failures.append("变异：真实文件里就没有 ref 门，先修 P2-1 再谈变异")
+        return
+    vectors = [
+        (
+            "去掉 ref 门（种子对任意 ref 可见）",
+            real.replace(GATE, f"secrets.{KEY_ENV}"),
+            "ref 门",
+        ),
+        (
+            "加回 pull_request 触发",
+            real.replace("  workflow_dispatch:\n", "  pull_request:\n  workflow_dispatch:\n", 1),
+            "pull_request",
+        ),
+        (
+            "去掉非 main 的 WITHHELD 说明",
+            "\n".join(line for line in real.splitlines() if WITHHELD_ENV not in line) + "\n",
+            WITHHELD_ENV,
+        ),
+    ]
+    for label, mutated, expect in vectors:
+        if mutated == real:
+            failures.append(f"变异「{label}」没改到任何字节（变异无处下手，用例什么都没证明）")
+            continue
+        problems = check_workflow(mutated)
+        if not any(expect in item for item in problems):
+            failures.append(f"变异「{label}」没有被抓：期望命中「{expect}」，实际 {problems or '零问题'}")
+    # 文档指针的变异：把 runbook 里一个真实路径改成不存在的名字，同一判据必须报红。
+    runbook = RUNBOOK.read_text(encoding="utf-8")
+    broken = runbook.replace("packaging/docs/signing.md", "packaging/docs/signing-oldext.md", 1)
+    if broken == runbook:
+        failures.append("变异「文档路径」：runbook 里找不到可替换的路径，用例失效")
+    elif not check_doc_paths(broken, "mutated-runbook"):
+        failures.append("变异「文档路径」：改成不存在的路径后判据仍然是绿的 —— 路径存在性没被判")
+
+
+def main() -> int:
+    failures: list[str] = []
+    case_mutation(failures)
+    case_wiring(failures)
+
+    for line in failures:
+        print(f"FAIL {line}", file=sys.stderr)
+    print("signing-status wiring selftest:", "ok" if not failures else f"{len(failures)} 处失败")
+    return 0 if not failures else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
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"]