From 8a8e5ca0c0d538f7b04814a7806dcdced381c4d1 Mon Sep 17 00:00:00 2001 From: AskaEth Date: Thu, 5 Nov 2026 14:22:11 +0800 Subject: [PATCH] Unlucky Launcher v0.2.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 首个 iced + Material 3 Expressive 版本的源码快照。 完整历史与日常提交在 dev 分支；main 只放阶段性快照。 --- .gitattributes | 34 + .github/workflows/ci.yml | 190 + .github/workflows/guards.yml | 381 + .github/workflows/release.yml | 369 + .gitignore | 28 + .rustfmt.toml | 5 + Cargo.lock | 6343 +++++++++++++++++ Cargo.toml | 164 + LICENSE | 202 + NOTICE | 66 + README.md | 243 + README.zh-CN.md | 203 + clippy.toml | 7 + crates/agent/Cargo.toml | 44 + crates/agent/src/audit.rs | 283 + crates/agent/src/brain/chat.rs | 267 + crates/agent/src/brain/exec.rs | 347 + crates/agent/src/brain/mod.rs | 323 + crates/agent/src/brain/provider.rs | 340 + crates/agent/src/brain/rig.rs | 368 + crates/agent/src/clock.rs | 139 + crates/agent/src/confirm.rs | 235 + crates/agent/src/event.rs | 197 + crates/agent/src/lib.rs | 45 + crates/agent/src/mcp/mod.rs | 159 + crates/agent/src/mcp/projection.rs | 106 + crates/agent/src/mcp/sample.rs | 80 + crates/agent/src/mcp/serve.rs | 144 + crates/agent/src/mcp/server.rs | 243 + crates/agent/src/port.rs | 315 + crates/agent/src/port/game.rs | 152 + crates/agent/src/redact.rs | 217 + crates/agent/src/registry/mod.rs | 260 + crates/agent/src/registry/schema.rs | 116 + crates/agent/src/registry/spec.rs | 262 + crates/agent/src/registry/validate.rs | 332 + crates/agent/src/testing.rs | 190 + crates/agent/src/testing/diagnose.rs | 87 + crates/agent/src/testing/game.rs | 158 + crates/agent/src/testing/settings.rs | 201 + crates/agent/src/tools/accounts.rs | 110 + crates/agent/src/tools/config.rs | 345 + crates/agent/src/tools/diagnose.rs | 335 + crates/agent/src/tools/game.rs | 199 + crates/agent/src/tools/mod.rs | 39 + crates/agent/src/tools/schema_tool.rs | 84 + crates/agent/src/tools/session.rs | 388 + crates/agent/tests/brain_loop.rs | 248 + crates/agent/tests/mcp_contract.rs | 132 + crates/agent/tests/mcp_http.rs | 336 + crates/agent/tests/schema_contract.rs | 163 + crates/agent/tests/support/mod.rs | 225 + crates/agent/tests/tools_security.rs | 365 + crates/app-iced/Cargo.toml | 92 + crates/app-iced/examples/pages_demo.rs | 37 + crates/app-iced/src/app/appearance.rs | 130 + crates/app-iced/src/app/backend.rs | 177 + crates/app-iced/src/app/boot.rs | 248 + crates/app-iced/src/app/boot/diagnostics.rs | 110 + crates/app-iced/src/app/boot/fallback.rs | 117 + crates/app-iced/src/app/boot/tests.rs | 271 + crates/app-iced/src/app/message.rs | 101 + crates/app-iced/src/app/mod.rs | 71 + crates/app-iced/src/app/state.rs | 188 + crates/app-iced/src/app/state/boot_probe.rs | 40 + crates/app-iced/src/app/state/construct.rs | 148 + crates/app-iced/src/app/state/refresh.rs | 61 + crates/app-iced/src/app/state/theme.rs | 86 + crates/app-iced/src/app/subscription.rs | 94 + crates/app-iced/src/app/tests.rs | 382 + crates/app-iced/src/app/tests/appearance.rs | 331 + crates/app-iced/src/app/tests/presenter.rs | 246 + crates/app-iced/src/app/update.rs | 288 + crates/app-iced/src/app/update/account.rs | 210 + .../app-iced/src/app/update/account/tests.rs | 303 + crates/app-iced/src/app/update/agent.rs | 381 + crates/app-iced/src/app/update/agent/tests.rs | 352 + crates/app-iced/src/app/update/appearance.rs | 81 + crates/app-iced/src/app/update/boot_env.rs | 26 + crates/app-iced/src/app/update/clock.rs | 143 + crates/app-iced/src/app/update/content.rs | 339 + crates/app-iced/src/app/update/download.rs | 381 + .../src/app/update/download_wiring.rs | 228 + .../app-iced/src/app/update/page_messages.rs | 232 + crates/app-iced/src/app/update/settings.rs | 55 + .../src/app/update/settings/ai_about.rs | 17 + .../src/app/update/settings/download.rs | 18 + .../app-iced/src/app/update/settings/java.rs | 33 + .../update/settings/language_appearance.rs | 19 + .../app-iced/src/app/update/settings/tests.rs | 267 + crates/app-iced/src/app/view.rs | 195 + crates/app-iced/src/app/view/account_page.rs | 73 + crates/app-iced/src/app/view/instances.rs | 162 + crates/app-iced/src/app/view/logs.rs | 144 + crates/app-iced/src/app/view/logs/tests.rs | 242 + crates/app-iced/src/app/view/rail.rs | 35 + crates/app-iced/src/app/view/tests.rs | 320 + crates/app-iced/src/app/window_alpha.rs | 134 + crates/app-iced/src/cli.rs | 287 + crates/app-iced/src/cli/tests.rs | 172 + .../src/components/buttons/assemble.rs | 230 + .../src/components/buttons/geometry.rs | 97 + crates/app-iced/src/components/buttons/mod.rs | 348 + .../app-iced/src/components/buttons/tests.rs | 351 + crates/app-iced/src/components/divider.rs | 109 + .../src/components/feedback/action.rs | 173 + .../src/components/feedback/dialog.rs | 262 + .../src/components/feedback/empty_state.rs | 149 + .../src/components/feedback/gallery_parts.rs | 97 + .../src/components/feedback/geometry.rs | 289 + .../src/components/feedback/keyframes.rs | 97 + .../app-iced/src/components/feedback/mod.rs | 92 + .../app-iced/src/components/feedback/panel.rs | 146 + .../app-iced/src/components/feedback/pixel.rs | 280 + .../app-iced/src/components/feedback/probe.rs | 342 + .../src/components/feedback/probe/circular.rs | 158 + .../src/components/feedback/probe/panels.rs | 315 + .../src/components/feedback/progress.rs | 308 + .../src/components/feedback/snackbar.rs | 193 + .../app-iced/src/components/feedback/tests.rs | 223 + .../src/components/feedback/tests/progress.rs | 281 + .../src/components/gallery/buttons.rs | 173 + .../src/components/gallery/feedback.rs | 365 + .../app-iced/src/components/gallery/inputs.rs | 341 + crates/app-iced/src/components/gallery/mod.rs | 375 + .../src/components/gallery/navigation.rs | 352 + .../app-iced/src/components/gallery/probe.rs | 368 + .../app-iced/src/components/gallery/scan.rs | 183 + .../src/components/gallery/selection.rs | 37 + crates/app-iced/src/components/gate.rs | 310 + .../app-iced/src/components/inputs/field.rs | 398 ++ .../src/components/inputs/field/tests.rs | 115 + .../src/components/inputs/geometry.rs | 309 + crates/app-iced/src/components/inputs/menu.rs | 354 + .../src/components/inputs/menu/tests.rs | 123 + crates/app-iced/src/components/inputs/mod.rs | 42 + .../app-iced/src/components/inputs/probe.rs | 347 + .../src/components/inputs/probe/menu.rs | 102 + .../src/components/inputs/probe/search.rs | 80 + .../src/components/inputs/probe/slider.rs | 96 + .../src/components/inputs/probe/text.rs | 205 + .../app-iced/src/components/inputs/search.rs | 353 + .../src/components/inputs/search/tests.rs | 93 + .../app-iced/src/components/inputs/slider.rs | 396 + .../src/components/inputs/slider/tests.rs | 122 + .../src/components/inputs/slider/track.rs | 66 + .../src/components/interaction/disabled.rs | 305 + .../src/components/interaction/mod.rs | 239 + .../src/components/interaction/tracker.rs | 155 + crates/app-iced/src/components/layout.rs | 129 + crates/app-iced/src/components/mod.rs | 58 + .../src/components/navigation/app_bar.rs | 353 + .../src/components/navigation/drawer.rs | 140 + .../src/components/navigation/drawer/item.rs | 296 + .../src/components/navigation/drawer/tests.rs | 115 + .../src/components/navigation/geometry.rs | 333 + .../components/navigation/geometry/tests.rs | 131 + .../src/components/navigation/list_item.rs | 306 + .../components/navigation/list_item/tests.rs | 127 + .../src/components/navigation/matrix.rs | 110 + .../app-iced/src/components/navigation/mod.rs | 80 + .../src/components/navigation/probe.rs | 393 + .../components/navigation/probe/divider.rs | 49 + .../src/components/navigation/probe/long.rs | 98 + .../src/components/navigation/probe/scan.rs | 379 + .../src/components/navigation/tabs.rs | 359 + .../src/components/navigation/tabs/tests.rs | 150 + .../src/components/selection/checkbox.rs | 186 + .../app-iced/src/components/selection/chip.rs | 187 + .../src/components/selection/geometry.rs | 259 + .../src/components/selection/matrix.rs | 211 + .../app-iced/src/components/selection/mod.rs | 50 + .../src/components/selection/paint/check.rs | 88 + .../src/components/selection/paint/chip.rs | 79 + .../src/components/selection/paint/mod.rs | 149 + .../src/components/selection/paint/radio.rs | 42 + .../src/components/selection/paint/switch.rs | 102 + .../src/components/selection/pixel.rs | 205 + .../src/components/selection/probe.rs | 326 + .../src/components/selection/radio.rs | 155 + .../src/components/selection/shell.rs | 156 + .../src/components/selection/switch.rs | 177 + .../src/components/selection/tests.rs | 358 + crates/app-iced/src/fonts.rs | 302 + crates/app-iced/src/fonts/cjk.rs | 188 + crates/app-iced/src/fonts/tests.rs | 175 + crates/app-iced/src/icons.rs | 400 ++ crates/app-iced/src/lib.rs | 62 + crates/app-iced/src/main.rs | 103 + crates/app-iced/src/pages/account.rs | 175 + crates/app-iced/src/pages/account/avatar.rs | 229 + crates/app-iced/src/pages/account/forms.rs | 322 + crates/app-iced/src/pages/account/login.rs | 352 + crates/app-iced/src/pages/account/model.rs | 337 + crates/app-iced/src/pages/account/panels.rs | 141 + crates/app-iced/src/pages/account/rows.rs | 274 + crates/app-iced/src/pages/account/tests.rs | 330 + .../app-iced/src/pages/account/tests_text.rs | 97 + crates/app-iced/src/pages/account/widgets.rs | 386 + .../app-iced/src/pages/agent/conversation.rs | 338 + .../src/pages/agent/conversation/banners.rs | 212 + .../src/pages/agent/conversation/composer.rs | 234 + .../pages/agent/conversation/transcript.rs | 122 + crates/app-iced/src/pages/agent/demo.rs | 130 + crates/app-iced/src/pages/agent/metrics.rs | 176 + .../app-iced/src/pages/agent/metrics/tests.rs | 189 + crates/app-iced/src/pages/agent/mod.rs | 371 + crates/app-iced/src/pages/agent/state.rs | 324 + crates/app-iced/src/pages/agent/strip.rs | 133 + crates/app-iced/src/pages/agent/tests.rs | 398 ++ .../src/pages/agent/tests/disclaimer.rs | 96 + crates/app-iced/src/pages/agent/tests/drag.rs | 150 + crates/app-iced/src/pages/appearance/alpha.rs | 235 + .../src/pages/appearance/background.rs | 294 + .../src/pages/appearance/background/tests.rs | 200 + crates/app-iced/src/pages/appearance/mod.rs | 219 + .../app-iced/src/pages/appearance/palette.rs | 279 + .../app-iced/src/pages/appearance/picture.rs | 113 + .../app-iced/src/pages/appearance/section.rs | 395 + crates/app-iced/src/pages/appearance/state.rs | 390 + crates/app-iced/src/pages/content.rs | 99 + crates/app-iced/src/pages/content/demo.rs | 221 + crates/app-iced/src/pages/content/layout.rs | 194 + crates/app-iced/src/pages/content/message.rs | 42 + crates/app-iced/src/pages/content/model.rs | 301 + .../app-iced/src/pages/content/model/items.rs | 238 + .../app-iced/src/pages/content/model/tests.rs | 294 + crates/app-iced/src/pages/content/packui.rs | 57 + .../app-iced/src/pages/content/packui/demo.rs | 245 + .../src/pages/content/packui/message.rs | 57 + .../src/pages/content/packui/model.rs | 227 + .../src/pages/content/packui/model/export.rs | 254 + .../pages/content/packui/model/progress.rs | 121 + .../src/pages/content/packui/model/report.rs | 255 + .../src/pages/content/packui/model/tests.rs | 394 + .../src/pages/content/packui/tests.rs | 107 + .../app-iced/src/pages/content/packui/view.rs | 257 + .../src/pages/content/packui/view/export.rs | 323 + .../src/pages/content/packui/view/parts.rs | 128 + .../src/pages/content/packui/view/progress.rs | 97 + .../src/pages/content/packui/view/report.rs | 296 + crates/app-iced/src/pages/content/parts.rs | 338 + .../src/pages/content/parts/detail.rs | 179 + .../src/pages/content/parts/filters.rs | 163 + crates/app-iced/src/pages/content/tests.rs | 87 + crates/app-iced/src/pages/content/view.rs | 232 + crates/app-iced/src/pages/download.rs | 241 + crates/app-iced/src/pages/download/demo.rs | 301 + crates/app-iced/src/pages/download/group.rs | 169 + .../src/pages/download/group/tests.rs | 104 + crates/app-iced/src/pages/download/install.rs | 252 + .../src/pages/download/install/tests.rs | 136 + crates/app-iced/src/pages/download/model.rs | 367 + .../src/pages/download/model/category.rs | 85 + .../src/pages/download/model/tests.rs | 78 + crates/app-iced/src/pages/download/options.rs | 36 + .../src/pages/download/options/model.rs | 286 + .../src/pages/download/options/tests.rs | 254 + .../src/pages/download/options/view.rs | 213 + crates/app-iced/src/pages/download/rails.rs | 375 + crates/app-iced/src/pages/download/rows.rs | 291 + .../app-iced/src/pages/download/rows/tests.rs | 41 + crates/app-iced/src/pages/download/states.rs | 164 + crates/app-iced/src/pages/download/tests.rs | 302 + .../app-iced/src/pages/download/tests/i18n.rs | 106 + .../src/pages/download/tests/rails.rs | 177 + .../src/pages/download/tests/search.rs | 217 + .../app-iced/src/pages/download/tests/view.rs | 147 + crates/app-iced/src/pages/frame.rs | 252 + crates/app-iced/src/pages/frame/pieces.rs | 333 + crates/app-iced/src/pages/frame/tests.rs | 101 + crates/app-iced/src/pages/harness.rs | 317 + crates/app-iced/src/pages/harness/app.rs | 241 + crates/app-iced/src/pages/harness/caps.rs | 53 + crates/app-iced/src/pages/harness/request.rs | 233 + crates/app-iced/src/pages/harness/tests.rs | 247 + crates/app-iced/src/pages/instances.rs | 267 + crates/app-iced/src/pages/instances/data.rs | 143 + crates/app-iced/src/pages/instances/demo.rs | 67 + crates/app-iced/src/pages/instances/detail.rs | 256 + crates/app-iced/src/pages/instances/tests.rs | 224 + .../src/pages/instances/tests/i18n.rs | 271 + crates/app-iced/src/pages/instances/text.rs | 103 + crates/app-iced/src/pages/layout.rs | 399 ++ crates/app-iced/src/pages/layout/block.rs | 83 + .../app-iced/src/pages/layout/block/tests.rs | 89 + crates/app-iced/src/pages/layout/rails.rs | 227 + .../app-iced/src/pages/layout/rails/tests.rs | 139 + crates/app-iced/src/pages/layout/source.rs | 235 + .../app-iced/src/pages/layout/source/tests.rs | 178 + crates/app-iced/src/pages/layout/tests.rs | 367 + crates/app-iced/src/pages/layout/wrap.rs | 84 + .../app-iced/src/pages/layout/wrap/tests.rs | 102 + crates/app-iced/src/pages/logs.rs | 159 + crates/app-iced/src/pages/logs/demo.rs | 182 + crates/app-iced/src/pages/logs/diagnostic.rs | 218 + crates/app-iced/src/pages/logs/lines.rs | 221 + crates/app-iced/src/pages/logs/model.rs | 299 + crates/app-iced/src/pages/logs/panel.rs | 89 + .../app-iced/src/pages/logs/sample_crash.log | 23 + .../app-iced/src/pages/logs/sample_live.log | 19 + crates/app-iced/src/pages/logs/tests.rs | 370 + crates/app-iced/src/pages/message.rs | 140 + crates/app-iced/src/pages/mod.rs | 296 + crates/app-iced/src/pages/model.rs | 124 + crates/app-iced/src/pages/nav.rs | 204 + crates/app-iced/src/pages/screen.rs | 89 + .../app-iced/src/pages/settings/ai_about.rs | 39 + .../app-iced/src/pages/settings/appearance.rs | 40 + .../app-iced/src/pages/settings/download.rs | 36 + crates/app-iced/src/pages/settings/frame.rs | 219 + crates/app-iced/src/pages/settings/general.rs | 225 + crates/app-iced/src/pages/settings/java.rs | 44 + .../src/pages/settings/language_appearance.rs | 35 + crates/app-iced/src/pages/settings/message.rs | 106 + crates/app-iced/src/pages/settings/mod.rs | 326 + crates/app-iced/src/pages/settings/state.rs | 85 + .../settings/tests/appearance_section.rs | 52 + .../pages/settings/tests/download_section.rs | 49 + .../pages/settings/tests/general_section.rs | 122 + .../src/pages/settings/tests/java_section.rs | 57 + .../app-iced/src/pages/settings/tests/mod.rs | 198 + crates/app-iced/src/pages/tests.rs | 385 + crates/app-iced/src/platform/locale.rs | 301 + crates/app-iced/src/platform/mod.rs | 170 + crates/app-iced/src/platform/win32/corner.rs | 293 + .../src/platform/win32/corner/tests.rs | 289 + crates/app-iced/src/platform/win32/mod.rs | 16 + .../src/platform/win32/transparency.rs | 398 ++ .../src/platform/win32/transparency/alpha.rs | 128 + .../src/platform/win32/transparency/dwm.rs | 394 + .../platform/win32/transparency/exstyle.rs | 107 + .../src/platform/win32/transparency/probe.rs | 342 + .../src/platform/win32/transparency/tests.rs | 233 + crates/app-iced/src/presenter/agent.rs | 279 + crates/app-iced/src/presenter/mod.rs | 41 + crates/app-iced/src/presenter/rig.rs | 211 + crates/app-iced/src/presenter/transport.rs | 339 + crates/app-iced/src/probe.rs | 226 + .../src/renderer/acceptance/locale.rs | 294 + .../src/renderer/acceptance/locale_tests.rs | 247 + .../app-iced/src/renderer/acceptance/mod.rs | 323 + .../app-iced/src/renderer/acceptance/tests.rs | 395 + .../src/renderer/acceptance/visual.rs | 103 + .../src/renderer/acceptance/window.rs | 142 + crates/app-iced/src/renderer/decision.rs | 331 + crates/app-iced/src/renderer/log_bridge.rs | 151 + crates/app-iced/src/renderer/mod.rs | 249 + crates/app-iced/src/renderer/preflight.rs | 244 + crates/app-iced/src/shell/mod.rs | 357 + crates/app-iced/src/shell/nav.rs | 335 + crates/app-iced/src/shell/nav/account.rs | 220 + crates/app-iced/src/shell/tests.rs | 131 + crates/app-iced/src/shot/diff.rs | 352 + crates/app-iced/src/shot/mod.rs | 100 + crates/app-iced/src/theme.rs | 400 ++ crates/app-iced/src/ui.rs | 17 + crates/app-iced/src/ui/lang.rs | 283 + crates/app-iced/tests/no_hardcoded_tokens.rs | 400 ++ crates/app/Cargo.toml | 50 + crates/app/build.rs | 7 + crates/app/src/appearance_bind.rs | 124 + crates/app/src/bg_image.rs | 370 + crates/app/src/callbacks.rs | 352 + crates/app/src/callbacks_pages.rs | 264 + crates/app/src/conv/agent.rs | 103 + crates/app/src/conv/instances.rs | 163 + crates/app/src/conv/logs.rs | 84 + crates/app/src/conv/mod.rs | 26 + crates/app/src/conv/pages.rs | 301 + crates/app/src/conv/pages_tests.rs | 172 + crates/app/src/conv/ui.rs | 136 + crates/app/src/conv/versions.rs | 105 + crates/app/src/main.rs | 116 + crates/app/src/page_sync.rs | 36 + crates/app/src/png.rs | 140 + crates/app/src/screenshot.rs | 177 + crates/app/src/theme_runtime.rs | 152 + crates/app/src/ui_bind.rs | 314 + crates/app/ui/components/ai-panel.slint | 283 + crates/app/ui/components/badge.slint | 27 + crates/app/ui/components/glass.slint | 59 + crates/app/ui/components/icons.slint | 192 + crates/app/ui/components/install-panel.slint | 73 + crates/app/ui/components/label.slint | 34 + crates/app/ui/components/nav.slint | 182 + crates/app/ui/components/notice-bar.slint | 57 + crates/app/ui/components/progress-bar.slint | 34 + crates/app/ui/components/progress-ring.slint | 22 + crates/app/ui/components/tile.slint | 198 + crates/app/ui/components/titlebar.slint | 126 + crates/app/ui/main.slint | 305 + crates/app/ui/models.slint | 364 + crates/app/ui/page_state.slint | 77 + crates/app/ui/pages/download-java.slint | 204 + crates/app/ui/pages/download.slint | 320 + crates/app/ui/pages/instances.slint | 260 + crates/app/ui/pages/logs.slint | 289 + crates/app/ui/pages/settings-account.slint | 201 + crates/app/ui/pages/settings-appearance.slint | 146 + crates/app/ui/pages/settings-groups.slint | 117 + crates/app/ui/pages/settings.slint | 280 + crates/app/ui/shell.slint | 387 + crates/app/ui/theme/metrics.slint | 48 + crates/app/ui/theme/tokens.slint | 208 + crates/app/ui/widgets/button.slint | 83 + crates/app/ui/widgets/dialog.slint | 122 + crates/app/ui/widgets/inputs.slint | 300 + crates/app/ui/widgets/setting-item.slint | 155 + crates/app/ui/widgets/toast.slint | 87 + crates/app/ui/widgets/wizard.slint | 301 + crates/cli/Cargo.toml | 35 + crates/cli/src/cli/help.rs | 183 + crates/cli/src/cli/mod.rs | 109 + crates/cli/src/cli/model.rs | 213 + crates/cli/src/cli/parse.rs | 393 + crates/cli/src/cli/parse/accounts.rs | 68 + crates/cli/src/cli/parse/agent.rs | 66 + crates/cli/src/cli/program.rs | 120 + crates/cli/src/commands/accounts.rs | 198 + crates/cli/src/commands/agent/mod.rs | 135 + .../cli/src/commands/agent/ports/accounts.rs | 49 + .../cli/src/commands/agent/ports/diagnose.rs | 187 + crates/cli/src/commands/agent/ports/events.rs | 136 + crates/cli/src/commands/agent/ports/game.rs | 204 + crates/cli/src/commands/agent/ports/mod.rs | 58 + .../cli/src/commands/agent/ports/session.rs | 201 + .../cli/src/commands/agent/ports/setting.rs | 211 + .../src/commands/agent/ports/setting/tests.rs | 226 + crates/cli/src/commands/agent/serve.rs | 218 + crates/cli/src/commands/config.rs | 341 + crates/cli/src/commands/config/tests.rs | 256 + crates/cli/src/commands/identity.rs | 216 + crates/cli/src/commands/install/loader.rs | 159 + .../src/commands/install/loader_processors.rs | 181 + crates/cli/src/commands/install/mod.rs | 151 + crates/cli/src/commands/install/report.rs | 262 + .../cli/src/commands/install/report_loader.rs | 274 + crates/cli/src/commands/install/vanilla.rs | 160 + crates/cli/src/commands/instances.rs | 90 + crates/cli/src/commands/java.rs | 365 + crates/cli/src/commands/java_launch.rs | 129 + crates/cli/src/commands/java_vendors.rs | 141 + crates/cli/src/commands/launch.rs | 377 + crates/cli/src/commands/meta.rs | 68 + crates/cli/src/commands/mod.rs | 224 + crates/cli/src/commands/pack.rs | 246 + crates/cli/src/commands/sessions.rs | 292 + crates/cli/src/commands/snapshot.rs | 205 + crates/cli/src/context.rs | 238 + crates/cli/src/error.rs | 165 + crates/cli/src/lib.rs | 27 + crates/cli/src/main.rs | 9 + crates/cli/src/os.rs | 78 + crates/cli/src/output.rs | 215 + crates/cli/src/runner.rs | 56 + crates/cli/tests/accounts_test.rs | 293 + crates/cli/tests/agent_mcp_stdio_test.rs | 185 + crates/cli/tests/config_secret_test.rs | 179 + crates/cli/tests/exit_code_test.rs | 109 + crates/cli/tests/isolation_launch_test.rs | 345 + crates/cli/tests/java_test.rs | 197 + crates/cli/tests/os_test.rs | 115 + crates/cli/tests/output_test.rs | 295 + crates/cli/tests/pack_test.rs | 199 + crates/cli/tests/parse_test.rs | 338 + crates/cli/tests/support/mod.rs | 159 + crates/core/Cargo.toml | 74 + crates/core/src/addon/export.rs | 65 + crates/core/src/addon/export/catalog.rs | 147 + crates/core/src/addon/export/classify.rs | 112 + crates/core/src/addon/export/pipeline.rs | 310 + crates/core/src/addon/export/report.rs | 235 + crates/core/src/addon/export/scan.rs | 189 + crates/core/src/addon/export/snapshot.rs | 209 + crates/core/src/addon/import.rs | 179 + crates/core/src/addon/import/baseline.rs | 162 + crates/core/src/addon/import/error.rs | 204 + crates/core/src/addon/import/fetch.rs | 234 + crates/core/src/addon/import/merge.rs | 139 + crates/core/src/addon/import/phase.rs | 379 + crates/core/src/addon/import/pipeline.rs | 389 + crates/core/src/addon/import/plan.rs | 373 + crates/core/src/addon/import/plan/paths.rs | 160 + crates/core/src/addon/import/report.rs | 243 + crates/core/src/addon/import/report/items.rs | 265 + crates/core/src/addon/import/report/keys.rs | 105 + crates/core/src/addon/import/stage.rs | 334 + crates/core/src/addon/import/stage/commit.rs | 290 + crates/core/src/addon/loader/fabric.rs | 247 + crates/core/src/addon/loader/forge.rs | 280 + crates/core/src/addon/loader/maven.rs | 173 + crates/core/src/addon/loader/meta.rs | 242 + crates/core/src/addon/loader/mod.rs | 249 + crates/core/src/addon/loader/plan.rs | 235 + .../src/addon/loader/processors/download.rs | 83 + .../core/src/addon/loader/processors/error.rs | 181 + .../core/src/addon/loader/processors/exec.rs | 363 + .../core/src/addon/loader/processors/jar.rs | 83 + .../core/src/addon/loader/processors/mod.rs | 56 + .../core/src/addon/loader/processors/plan.rs | 366 + .../src/addon/loader/processors/prepare.rs | 201 + .../core/src/addon/loader/processors/spec.rs | 121 + .../src/addon/loader/processors/tests/exec.rs | 185 + .../src/addon/loader/processors/tests/mod.rs | 71 + .../src/addon/loader/processors/tests/plan.rs | 224 + .../src/addon/loader/processors/tests/vars.rs | 181 + .../core/src/addon/loader/processors/text.rs | 71 + .../core/src/addon/loader/processors/vars.rs | 324 + crates/core/src/addon/loader/tests/fabric.rs | 135 + crates/core/src/addon/loader/tests/forge.rs | 258 + crates/core/src/addon/loader/tests/maven.rs | 134 + crates/core/src/addon/loader/tests/mod.rs | 56 + crates/core/src/addon/loader/tests/plan.rs | 192 + crates/core/src/addon/mod.rs | 48 + crates/core/src/addon/pack.rs | 71 + crates/core/src/addon/pack/archive.rs | 298 + crates/core/src/addon/pack/archive/entry.rs | 30 + crates/core/src/addon/pack/archive/limits.rs | 167 + crates/core/src/addon/pack/archive/open.rs | 158 + crates/core/src/addon/pack/curseforge.rs | 339 + .../src/addon/pack/curseforge/fingerprint.rs | 262 + crates/core/src/addon/pack/error.rs | 161 + crates/core/src/addon/pack/format.rs | 391 + crates/core/src/addon/pack/format/payload.rs | 70 + crates/core/src/addon/pack/manifest.rs | 395 + .../core/src/addon/pack/manifest/entries.rs | 155 + crates/core/src/addon/pack/modrinth.rs | 394 + crates/core/src/addon/pack/multimc.rs | 183 + crates/core/src/addon/pack/path.rs | 140 + crates/core/src/addon/pack/tests/detect.rs | 223 + crates/core/src/addon/pack/tests/export.rs | 156 + .../src/addon/pack/tests/export_harness.rs | 121 + .../src/addon/pack/tests/export_pipeline.rs | 370 + .../src/addon/pack/tests/export_roundtrip.rs | 280 + crates/core/src/addon/pack/tests/extend.rs | 172 + crates/core/src/addon/pack/tests/fixtures.rs | 185 + crates/core/src/addon/pack/tests/mod.rs | 107 + crates/core/src/addon/pack/tests/model.rs | 111 + crates/core/src/addon/pack/tests/roundtrip.rs | 306 + crates/core/src/addon/pack/tests/safety.rs | 312 + .../src/addon/pack/tests/unknown_fields.rs | 113 + .../core/src/addon/tests/import_curseforge.rs | 134 + .../core/src/addon/tests/import_failures.rs | 254 + crates/core/src/addon/tests/import_merge.rs | 293 + .../core/src/addon/tests/import_modrinth.rs | 178 + crates/core/src/addon/tests/import_multimc.rs | 210 + crates/core/src/addon/tests/import_report.rs | 159 + crates/core/src/addon/tests/mod.rs | 175 + crates/core/src/addon/tests/support.rs | 208 + crates/core/src/auth/account.rs | 339 + crates/core/src/auth/authlib.rs | 347 + crates/core/src/auth/authlib/server_meta.rs | 86 + crates/core/src/auth/authlib/tests.rs | 97 + crates/core/src/auth/body/mod.rs | 279 + crates/core/src/auth/body/tests.rs | 168 + crates/core/src/auth/error.rs | 256 + crates/core/src/auth/http.rs | 208 + crates/core/src/auth/journal.rs | 266 + crates/core/src/auth/microsoft/authcode.rs | 284 + crates/core/src/auth/microsoft/callback.rs | 346 + crates/core/src/auth/microsoft/chain.rs | 377 + crates/core/src/auth/microsoft/client_id.rs | 248 + crates/core/src/auth/microsoft/endpoints.rs | 132 + crates/core/src/auth/microsoft/flow.rs | 313 + crates/core/src/auth/microsoft/mod.rs | 366 + crates/core/src/auth/microsoft/session.rs | 231 + crates/core/src/auth/mod.rs | 55 + crates/core/src/auth/offline.rs | 197 + crates/core/src/auth/secret.rs | 182 + crates/core/src/auth/store.rs | 251 + crates/core/src/auth/store/payload.rs | 247 + crates/core/src/diagnose/collectors.rs | 267 + crates/core/src/diagnose/engine.rs | 321 + crates/core/src/diagnose/environment.rs | 155 + crates/core/src/diagnose/finding.rs | 256 + crates/core/src/diagnose/fix_action.rs | 213 + crates/core/src/diagnose/fix_params.rs | 252 + crates/core/src/diagnose/hs_err.rs | 298 + crates/core/src/diagnose/hs_err_report.rs | 210 + crates/core/src/diagnose/loader.rs | 398 ++ crates/core/src/diagnose/mod.rs | 17 + crates/core/src/diagnose/rules.d/fabric.yaml | 141 + crates/core/src/diagnose/rules.d/forge.yaml | 136 + .../core/src/diagnose/rules.d/graphics.yaml | 221 + .../core/src/diagnose/rules.d/integrity.yaml | 138 + crates/core/src/diagnose/rules.d/jvm.yaml | 142 + crates/core/src/diagnose/rules.d/memory.yaml | 39 + .../src/diagnose/rules.d/mod_conflict.yaml | 152 + .../src/diagnose/rules.d/mod_runtime.yaml | 136 + crates/core/src/diagnose/rules.d/other.yaml | 22 + .../rules.d/samples/fabric/loader_0_12.log | 2 + .../rules.d/samples/fabric/mod_resolution.log | 3 + .../fabric/mod_resolution_collection.log | 1 + .../fabric/mod_resolution_conflict.log | 1 + .../samples/fabric/mod_resolution_details.log | 3 + .../samples/fabric/mod_resolution_missing.log | 1 + .../mod_resolution_missing_minecraft.log | 1 + .../rules.d/samples/fabric/warnings.log | 3 + .../samples/forge/bootstrap_failed.log | 1 + .../rules.d/samples/forge/duplicate_mods.log | 3 + .../rules.d/samples/forge/duplicated_mod.log | 1 + .../samples/forge/missing_dependencies.log | 2 + .../samples/forge/module_name_invalid.log | 1 + .../forge/optifine_repeat_installation.log | 1 + .../samples/forge/repeat_installation.log | 1 + .../rules.d/samples/forge/too_many_mods.log | 1 + .../samples/graphics/gl_operation_failure.log | 3 + .../samples/graphics/graphics_driver.log | 7 + .../samples/graphics/macos_display_port.log | 1 + .../samples/graphics/no_graphics_backend.log | 15 + .../samples/graphics/opengl_not_supported.log | 1 + .../samples/graphics/resolution_too_high.log | 1 + .../rules.d/samples/graphics/rtss_sodium.log | 1 + .../vulkan_device_version_too_low.log | 5 + .../graphics/vulkan_loader_missing.log | 5 + .../graphics/vulkan_missing_extension.log | 5 + .../graphics/vulkan_missing_feature.log | 5 + .../samples/hs_err/access_violation.log | 34 + .../rules.d/samples/hs_err/out_of_memory.log | 19 + .../samples/integrity/file_already_exists.log | 1 + .../samples/integrity/file_changed.log | 2 + .../samples/integrity/illegal_access.log | 2 + .../samples/integrity/incomplete_forge.log | 1 + .../integrity/mod_files_decompressed.log | 2 + .../samples/integrity/no_class_def_found.log | 2 + .../samples/integrity/no_such_method.log | 3 + .../samples/integrity/unsatisfied_link.log | 2 + .../samples/jvm/java_version_is_too_high.log | 3 + .../diagnose/rules.d/samples/jvm/jdk_9.log | 2 + .../rules.d/samples/jvm/jvm_32bit.log | 3 + .../rules.d/samples/jvm/mac_jdk8u261.log | 1 + .../rules.d/samples/jvm/modlauncher_8.log | 3 + .../rules.d/samples/jvm/need_jdk11.log | 2 + .../diagnose/rules.d/samples/jvm/openj9.log | 2 + .../rules.d/samples/jvm/too_old_java.log | 2 + .../samples/memory/memory_exceeded.log | 3 + .../rules.d/samples/memory/out_of_memory.log | 3 + .../samples/mod_conflict/jade_optifine.log | 1 + .../mod_conflict/multipart_optifine.log | 1 + .../mod_conflict/neoforge_optifine.log | 1 + .../samples/mod_conflict/optifine_forge.log | 4 + .../mod_conflict/optifine_world_load.log | 1 + .../mod_conflict/performant_optifine.log | 1 + .../samples/mod_conflict/shaders_mod.log | 1 + .../mod_conflict/twilight_optifine.log | 1 + .../samples/mod_runtime/config_failed.log | 1 + .../samples/mod_runtime/forge_error.log | 3 + .../mod_runtime/install_mixinbootstrap.log | 1 + .../mod_runtime/loading_crashed_fabric.log | 1 + .../mod_runtime/loading_crashed_forge.log | 1 + .../mod_runtime/mixin_apply_failed.log | 1 + .../samples/mod_runtime/mixin_failure.log | 1 + .../mod_runtime/night_config_fixes.log | 1 + .../rules.d/samples/other/debug_crash.log | 1 + .../rules.d/samples/world/block_model.log | 6 + .../rules.d/samples/world/entity_tick.log | 6 + crates/core/src/diagnose/rules.d/world.yaml | 39 + crates/core/src/diagnose/rules.rs | 319 + crates/core/src/diagnose/signals.rs | 396 + crates/core/src/diagnose/sources.rs | 299 + crates/core/src/diagnose/synthetic.rs | 279 + crates/core/src/download/adoptium.rs | 204 + crates/core/src/download/atomic.rs | 384 + crates/core/src/download/backoff.rs | 120 + crates/core/src/download/blocking.rs | 55 + crates/core/src/download/bytes.rs | 138 + crates/core/src/download/cache.rs | 285 + crates/core/src/download/chunked.rs | 296 + crates/core/src/download/config.rs | 46 + crates/core/src/download/engine.rs | 397 ++ crates/core/src/download/error.rs | 125 + crates/core/src/download/health.rs | 399 ++ crates/core/src/download/health_store.rs | 80 + crates/core/src/download/http.rs | 183 + crates/core/src/download/jdk_sources.rs | 178 + crates/core/src/download/mirrors.json | 169 + crates/core/src/download/mirrors.rs | 386 + crates/core/src/download/mod.rs | 90 + crates/core/src/download/progress.rs | 197 + crates/core/src/download/region.rs | 343 + crates/core/src/download/region_system.rs | 158 + crates/core/src/download/resume.rs | 235 + crates/core/src/download/transfer.rs | 305 + crates/core/src/download/transfer_chunk.rs | 163 + crates/core/src/download/types.rs | 307 + crates/core/src/download/verify.rs | 123 + crates/core/src/game/arguments.rs | 331 + crates/core/src/game/capability.rs | 83 + .../core/src/game/data/unlisted-versions.json | 209 + crates/core/src/game/error.rs | 124 + crates/core/src/game/inherit.rs | 198 + crates/core/src/game/install/assets.rs | 190 + crates/core/src/game/install/execute.rs | 339 + crates/core/src/game/install/instance.rs | 351 + crates/core/src/game/install/libraries.rs | 258 + crates/core/src/game/install/mod.rs | 193 + crates/core/src/game/install/plan.rs | 342 + crates/core/src/game/install/plan_view.rs | 72 + crates/core/src/game/install/report.rs | 154 + crates/core/src/game/install/source.rs | 353 + crates/core/src/game/install/tests/execute.rs | 397 ++ .../core/src/game/install/tests/instance.rs | 122 + crates/core/src/game/install/tests/mod.rs | 8 + crates/core/src/game/install/tests/plan.rs | 285 + crates/core/src/game/isolation.rs | 345 + crates/core/src/game/java/api.rs | 344 + crates/core/src/game/java/discover.rs | 326 + crates/core/src/game/java/error.rs | 138 + crates/core/src/game/java/extract.rs | 318 + crates/core/src/game/java/install.rs | 379 + crates/core/src/game/java/location.rs | 335 + crates/core/src/game/java/mapping.rs | 376 + crates/core/src/game/java/microsoft.rs | 261 + crates/core/src/game/java/mod.rs | 90 + crates/core/src/game/java/net.rs | 60 + crates/core/src/game/java/oracle.rs | 344 + crates/core/src/game/java/probe.rs | 370 + crates/core/src/game/java/release.rs | 170 + crates/core/src/game/java/select.rs | 160 + crates/core/src/game/java/source.rs | 199 + crates/core/src/game/java/target.rs | 85 + crates/core/src/game/java/vendor.rs | 219 + crates/core/src/game/java/zulu.rs | 275 + crates/core/src/game/layout.rs | 165 + crates/core/src/game/library.rs | 213 + crates/core/src/game/manifest.rs | 265 + crates/core/src/game/mod.rs | 64 + crates/core/src/game/profiles.rs | 244 + crates/core/src/game/snapshot.rs | 174 + crates/core/src/game/unlisted.rs | 54 + crates/core/src/game/version.rs | 238 + crates/core/src/launch/adapter.rs | 368 + crates/core/src/launch/args_table.rs | 253 + crates/core/src/launch/argument.rs | 205 + crates/core/src/launch/command_builder.rs | 335 + crates/core/src/launch/crash_scan.rs | 152 + crates/core/src/launch/defaults.rs | 203 + crates/core/src/launch/diagnosis_hook.rs | 97 + crates/core/src/launch/error.rs | 165 + crates/core/src/launch/exit_analysis.rs | 264 + crates/core/src/launch/game_args.rs | 206 + crates/core/src/launch/game_version.rs | 178 + crates/core/src/launch/jvm_args.rs | 149 + crates/core/src/launch/launch_session.rs | 329 + crates/core/src/launch/launcher.rs | 298 + crates/core/src/launch/log_level.rs | 114 + crates/core/src/launch/mod.rs | 75 + crates/core/src/launch/natives/jar.rs | 250 + crates/core/src/launch/natives/mod.rs | 355 + crates/core/src/launch/placeholders.rs | 173 + crates/core/src/launch/platform.rs | 95 + crates/core/src/launch/process.rs | 231 + crates/core/src/launch/pump.rs | 379 + crates/core/src/launch/redact.rs | 299 + crates/core/src/launch/request.rs | 358 + crates/core/src/launch/session.rs | 375 + crates/core/src/launch/session_index.rs | 120 + crates/core/src/launch/session_meta.rs | 62 + crates/core/src/launch/session_payload.rs | 159 + crates/core/src/launch/session_sink.rs | 64 + crates/core/src/launch/sink.rs | 138 + crates/core/src/launch/time.rs | 118 + crates/core/src/launch/tree_kill.rs | 195 + crates/core/src/launch/watchdog.rs | 71 + crates/core/src/launch/window_detect.rs | 86 + crates/core/src/lib.rs | 24 + crates/core/src/platform/atomic.rs | 79 + crates/core/src/platform/data_dir.rs | 235 + crates/core/src/platform/dir_migration.rs | 252 + crates/core/src/platform/error.rs | 124 + crates/core/src/platform/hash.rs | 95 + crates/core/src/platform/layout.rs | 223 + crates/core/src/platform/linux_caps.rs | 225 + crates/core/src/platform/macos_version.rs | 100 + crates/core/src/platform/mod.rs | 46 + crates/core/src/platform/os_info.rs | 388 + crates/core/src/platform/paths.rs | 186 + crates/core/src/platform/receipt.rs | 202 + crates/core/src/platform/redirect.rs | 137 + crates/core/src/platform/theme_probe.rs | 182 + crates/core/src/platform/vk_probe.rs | 305 + crates/core/src/platform/wallpaper.rs | 358 + crates/core/src/platform/wallpaper/io.rs | 297 + crates/core/src/platform/wallpaper/linux.rs | 396 + crates/core/src/platform/wallpaper/macos.rs | 304 + crates/core/src/platform/wallpaper/parse.rs | 320 + crates/core/src/platform/wallpaper/windows.rs | 371 + .../src/platform/wallpaper/windows/parse.rs | 100 + crates/core/src/platform/windows_version.rs | 215 + crates/core/src/setting/appearance/mod.rs | 307 + crates/core/src/setting/appearance/modes.rs | 207 + crates/core/src/setting/appearance/tests.rs | 215 + crates/core/src/setting/catalog.rs | 195 + crates/core/src/setting/document.rs | 399 ++ crates/core/src/setting/error.rs | 121 + crates/core/src/setting/instance_keys.rs | 155 + crates/core/src/setting/json_path.rs | 124 + crates/core/src/setting/keys.rs | 398 ++ crates/core/src/setting/migrate.rs | 222 + crates/core/src/setting/mod.rs | 36 + crates/core/src/setting/policy.rs | 92 + crates/core/src/setting/save.rs | 217 + crates/core/src/setting/save_worker.rs | 181 + crates/core/src/setting/schema.rs | 292 + crates/core/src/setting/spec.rs | 331 + crates/core/src/setting/store.rs | 301 + .../core/tests/auth/auth_failure_journal.rs | 151 + crates/core/tests/auth/authlib_api.rs | 307 + crates/core/tests/auth/main.rs | 21 + crates/core/tests/auth/microsoft_authcode.rs | 295 + .../core/tests/auth/microsoft_diagnostics.rs | 231 + crates/core/tests/auth/microsoft_flow.rs | 274 + crates/core/tests/auth/microsoft_refresh.rs | 283 + crates/core/tests/auth/offline_uuid.rs | 105 + crates/core/tests/auth/store_separation.rs | 240 + crates/core/tests/auth/support/microsoft.rs | 136 + crates/core/tests/auth/support/mod.rs | 279 + .../core/tests/diagnose/collectors_probe.rs | 233 + crates/core/tests/diagnose/engine_rank.rs | 233 + crates/core/tests/diagnose/hs_err_parse.rs | 143 + crates/core/tests/diagnose/loader_reload.rs | 171 + crates/core/tests/diagnose/main.rs | 83 + crates/core/tests/diagnose/rules_samples.rs | 267 + crates/core/tests/download/backoff_test.rs | 68 + crates/core/tests/download/cache_test.rs | 149 + crates/core/tests/download/chunked_test.rs | 375 + .../core/tests/download/engine_mock_test.rs | 350 + crates/core/tests/download/health_test.rs | 268 + crates/core/tests/download/mirrors_test.rs | 281 + crates/core/tests/download/partfile_test.rs | 233 + crates/core/tests/download/region_test.rs | 121 + crates/core/tests/download/resume_test.rs | 223 + crates/core/tests/download/support/mod.rs | 278 + crates/core/tests/game/arguments_rules.rs | 256 + crates/core/tests/game/helpers.rs | 66 + crates/core/tests/game/inherit_chain.rs | 265 + crates/core/tests/game/isolation.rs | 194 + crates/core/tests/game/isolation_switch.rs | 222 + crates/core/tests/game/java_discover.rs | 129 + crates/core/tests/game/java_install.rs | 291 + crates/core/tests/game/java_location.rs | 136 + crates/core/tests/game/java_mapping.rs | 106 + crates/core/tests/game/java_mirrors.rs | 96 + crates/core/tests/game/java_vendor_chain.rs | 183 + crates/core/tests/game/layout.rs | 143 + crates/core/tests/game/main.rs | 30 + crates/core/tests/game/manifest_parse.rs | 186 + crates/core/tests/game/profiles.rs | 109 + crates/core/tests/game/snapshot.rs | 75 + crates/core/tests/game/unlisted.rs | 90 + crates/core/tests/game/version_list.rs | 137 + crates/core/tests/game/vulkan_capability.rs | 125 + crates/core/tests/launch/adapter_cases.rs | 166 + crates/core/tests/launch/cmdline_snapshot.rs | 338 + .../tests/launch/command_builder_cases.rs | 148 + crates/core/tests/launch/exit_cases.rs | 169 + .../tests/launch/graphics_backend_cases.rs | 147 + crates/core/tests/launch/main.rs | 16 + .../core/tests/launch/natives_args_cases.rs | 136 + crates/core/tests/launch/natives_cases.rs | 281 + crates/core/tests/launch/pipeline_cases.rs | 347 + crates/core/tests/launch/prelude.rs | 149 + crates/core/tests/launch/process_smoke.rs | 167 + crates/core/tests/launch/pump_buffer.rs | 111 + crates/core/tests/launch/session_events.rs | 257 + crates/core/tests/launch/sink_cases.rs | 73 + crates/core/tests/launch/tree_kill_cases.rs | 201 + .../core/tests/platform/linux_caps_cases.rs | 136 + crates/core/tests/platform/macos_cases.rs | 58 + crates/core/tests/platform/main.rs | 17 + crates/core/tests/platform/os_info_cases.rs | 299 + crates/core/tests/platform/prelude.rs | 53 + crates/core/tests/platform/rules_wiring.rs | 96 + crates/core/tests/platform/theme_cases.rs | 102 + crates/core/tests/platform/vk_cases.rs | 240 + .../tests/platform/windows_version_cases.rs | 179 + crates/core/tests/setting/appearance_keys.rs | 204 + crates/core/tests/setting/atomic_write.rs | 49 + crates/core/tests/setting/common.rs | 81 + crates/core/tests/setting/debounce.rs | 128 + crates/core/tests/setting/deprecated_keys.rs | 142 + crates/core/tests/setting/dir_migration.rs | 185 + crates/core/tests/setting/dirs.rs | 205 + crates/core/tests/setting/document.rs | 221 + crates/core/tests/setting/isolation_keys.rs | 251 + .../core/tests/setting/java_install_keys.rs | 119 + crates/core/tests/setting/layout.rs | 128 + crates/core/tests/setting/main.rs | 21 + crates/core/tests/setting/migration_chain.rs | 295 + crates/core/tests/setting/redirect.rs | 88 + crates/core/tests/setting/schema_compat.rs | 120 + crates/core/tests/setting/spec_ai.rs | 178 + crates/core/tests/setting/store.rs | 259 + crates/design/Cargo.toml | 19 + crates/design/src/color/cam16.rs | 120 + crates/design/src/color/critical_planes.rs | 77 + crates/design/src/color/hct.rs | 160 + crates/design/src/color/hct_solver.rs | 311 + crates/design/src/color/mod.rs | 335 + crates/design/src/color/palettes.rs | 400 ++ crates/design/src/color/roles.rs | 276 + crates/design/src/color/scheme.rs | 342 + crates/design/src/color/space.rs | 217 + crates/design/src/color/state.rs | 164 + crates/design/src/color/tonal.rs | 150 + crates/design/src/color/viewing_conditions.rs | 165 + crates/design/src/component_map/metrics.rs | 179 + crates/design/src/component_map/mod.rs | 212 + crates/design/src/component_map/table.rs | 371 + crates/design/src/component_map/tests.rs | 202 + crates/design/src/elevation.rs | 226 + crates/design/src/icons/glyphs.rs | 184 + crates/design/src/icons/kinds.rs | 208 + crates/design/src/icons/mod.rs | 342 + crates/design/src/lib.rs | 147 + crates/design/src/motion/mod.rs | 308 + crates/design/src/motion/spring.rs | 380 + crates/design/src/palette/card.rs | 340 + crates/design/src/palette/mod.rs | 60 + crates/design/src/palette/quantize.rs | 338 + crates/design/src/palette/resolve/mod.rs | 205 + .../design/src/palette/resolve/provenance.rs | 261 + crates/design/src/palette/resolve/tests.rs | 242 + crates/design/src/palette/score.rs | 207 + crates/design/src/palette/seed/mod.rs | 267 + crates/design/src/palette/seed/tests.rs | 254 + crates/design/src/palette/wcag.rs | 281 + crates/design/src/shape.rs | 313 + crates/design/src/spacing.rs | 290 + crates/design/src/typography/emphasized.rs | 88 + crates/design/src/typography/fonts.rs | 304 + crates/design/src/typography/fonts/tests.rs | 149 + crates/design/src/typography/mod.rs | 346 + crates/design/tests/card_neutral.rs | 400 ++ crates/design/tests/card_neutral/common.rs | 27 + crates/design/tests/card_neutral/dump.rs | 68 + crates/design/tests/contrast_aa.rs | 255 + crates/design/tests/official_accent.rs | 307 + crates/design/tests/official_baseline.rs | 198 + crates/design/tests/skyseed_candidates.rs | 341 + crates/design/tests/token_contract.rs | 246 + crates/design/tests/token_pins.rs | 252 + crates/design/tests/tokext_pins.rs | 297 + crates/design/tests/type_scale_pins.rs | 106 + crates/i18n/Cargo.toml | 20 + crates/i18n/src/bridge.rs | 184 + crates/i18n/src/catalog.rs | 342 + crates/i18n/src/catalog/account.rs | 113 + crates/i18n/src/catalog/agent.rs | 66 + crates/i18n/src/catalog/content.rs | 269 + crates/i18n/src/catalog/core_text.rs | 15 + crates/i18n/src/catalog/download.rs | 150 + crates/i18n/src/catalog/font.rs | 24 + crates/i18n/src/catalog/general.rs | 60 + crates/i18n/src/catalog/golden.rs | 399 ++ crates/i18n/src/catalog/instances.rs | 85 + crates/i18n/src/catalog/launch.rs | 59 + crates/i18n/src/catalog/loader.rs | 15 + crates/i18n/src/catalog/logs.rs | 40 + crates/i18n/src/catalog/nav.rs | 42 + crates/i18n/src/catalog/settings/ai.rs | 13 + .../i18n/src/catalog/settings/appearance.rs | 35 + crates/i18n/src/catalog/settings/download.rs | 12 + crates/i18n/src/catalog/settings/general.rs | 19 + crates/i18n/src/catalog/settings/java.rs | 12 + crates/i18n/src/catalog/settings/mod.rs | 28 + crates/i18n/src/catalog/tests.rs | 203 + crates/i18n/src/choice.rs | 258 + crates/i18n/src/font.rs | 331 + crates/i18n/src/lang.rs | 387 + crates/i18n/src/lib.rs | 45 + crates/palette-extract/Cargo.toml | 32 + crates/palette-extract/src/lib.rs | 217 + crates/palette-extract/src/tests.rs | 189 + crates/presenter/Cargo.toml | 28 + crates/presenter/src/agent.rs | 311 + crates/presenter/src/agent/mock.rs | 165 + crates/presenter/src/agent/rail.rs | 393 + crates/presenter/src/agent/tests.rs | 362 + crates/presenter/src/agent/tests_red_line.rs | 380 + crates/presenter/src/backend.rs | 36 + crates/presenter/src/dialogs.rs | 305 + crates/presenter/src/dto/accounts.rs | 395 + crates/presenter/src/dto/accounts/failure.rs | 132 + crates/presenter/src/dto/accounts/kind.rs | 43 + crates/presenter/src/dto/accounts/name.rs | 29 + crates/presenter/src/dto/accounts/redact.rs | 144 + crates/presenter/src/dto/accounts/tests.rs | 167 + crates/presenter/src/dto/agent.rs | 179 + crates/presenter/src/dto/content.rs | 366 + crates/presenter/src/dto/content/tests.rs | 87 + crates/presenter/src/dto/events.rs | 338 + crates/presenter/src/dto/install.rs | 249 + crates/presenter/src/dto/instances.rs | 296 + crates/presenter/src/dto/java.rs | 234 + crates/presenter/src/dto/logs.rs | 78 + crates/presenter/src/dto/mod.rs | 59 + crates/presenter/src/dto/notices.rs | 73 + crates/presenter/src/dto/pack.rs | 51 + crates/presenter/src/dto/pack/conflict.rs | 71 + crates/presenter/src/dto/pack/event.rs | 128 + crates/presenter/src/dto/pack/export.rs | 221 + crates/presenter/src/dto/pack/format.rs | 47 + crates/presenter/src/dto/pack/import.rs | 341 + crates/presenter/src/dto/settings.rs | 220 + crates/presenter/src/dto/versions.rs | 62 + crates/presenter/src/host/accounts.rs | 382 + crates/presenter/src/host/accounts/authlib.rs | 337 + .../src/host/accounts/authlib/util.rs | 129 + crates/presenter/src/host/accounts/failure.rs | 126 + crates/presenter/src/host/accounts/refresh.rs | 66 + crates/presenter/src/host/addon.rs | 106 + crates/presenter/src/host/addon/http.rs | 123 + crates/presenter/src/host/addon/install.rs | 252 + crates/presenter/src/host/addon/pack.rs | 290 + .../presenter/src/host/addon/pack/convert.rs | 256 + .../presenter/src/host/addon/pack/diagnose.rs | 104 + .../presenter/src/host/addon/pack/export.rs | 132 + .../presenter/src/host/addon/pack/import.rs | 176 + crates/presenter/src/host/addon/pack/tests.rs | 389 + .../src/host/addon/pack/tests/harness.rs | 56 + crates/presenter/src/host/addon/sources.rs | 262 + crates/presenter/src/host/addon/tests.rs | 85 + crates/presenter/src/host/cancel_tests.rs | 344 + crates/presenter/src/host/dispatch.rs | 248 + crates/presenter/src/host/engine.rs | 126 + crates/presenter/src/host/env.rs | 170 + crates/presenter/src/host/game.rs | 260 + crates/presenter/src/host/handle.rs | 206 + crates/presenter/src/host/identity.rs | 103 + crates/presenter/src/host/install.rs | 283 + crates/presenter/src/host/install/routes.rs | 183 + crates/presenter/src/host/install_journal.rs | 79 + .../presenter/src/host/install_processors.rs | 382 + .../src/host/install_processors_fixture.rs | 272 + .../src/host/install_processors_tests.rs | 213 + crates/presenter/src/host/install_tests.rs | 218 + crates/presenter/src/host/java.rs | 304 + crates/presenter/src/host/job.rs | 198 + crates/presenter/src/host/launch.rs | 353 + .../presenter/src/host/launch_state_tests.rs | 267 + crates/presenter/src/host/loader_versions.rs | 120 + crates/presenter/src/host/logs.rs | 342 + crates/presenter/src/host/logs_tests.rs | 86 + crates/presenter/src/host/meter.rs | 89 + crates/presenter/src/host/mod.rs | 366 + crates/presenter/src/host/opener.rs | 72 + crates/presenter/src/host/settings.rs | 399 ++ crates/presenter/src/host/settings_tests.rs | 163 + crates/presenter/src/host/versions.rs | 173 + crates/presenter/src/lib.rs | 120 + crates/presenter/src/mock.rs | 399 ++ crates/presenter/src/mock/accounts.rs | 177 + crates/presenter/src/mock/instances.rs | 122 + crates/presenter/src/mock_data.rs | 238 + crates/presenter/src/prefs.rs | 333 + crates/presenter/src/prefs/tests.rs | 109 + crates/presenter/src/router.rs | 200 + crates/presenter/src/settings_bridge.rs | 352 + crates/presenter/src/settings_bridge_lang.rs | 150 + crates/presenter/src/state.rs | 387 + crates/presenter/src/state/accounts.rs | 193 + crates/presenter/src/state/content.rs | 45 + crates/presenter/src/state/content_tests.rs | 130 + crates/presenter/src/state/live.rs | 30 + crates/presenter/src/state/tiles.rs | 27 + crates/presenter/src/state_tests.rs | 371 + crates/presenter/src/theme.rs | 165 + crates/presenter/src/toast.rs | 154 + crates/presenter/src/wizard.rs | 275 + deny.toml | 54 + packaging/README.md | 401 ++ packaging/check_screenshot.py | 317 + packaging/ci-runtime-smoke.md | 78 + packaging/linux-smoke-docker.sh | 97 + packaging/make_artifacts.py | 317 + packaging/release-notes.md | 124 + rust-toolchain.toml | 6 + 1079 files changed, 208035 insertions(+) create mode 100644 .gitattributes create mode 100644 .github/workflows/ci.yml create mode 100644 .github/workflows/guards.yml create mode 100644 .github/workflows/release.yml create mode 100644 .gitignore create mode 100644 .rustfmt.toml create mode 100644 Cargo.lock create mode 100644 Cargo.toml create mode 100644 LICENSE create mode 100644 NOTICE create mode 100644 README.md create mode 100644 README.zh-CN.md create mode 100644 clippy.toml create mode 100644 crates/agent/Cargo.toml create mode 100644 crates/agent/src/audit.rs create mode 100644 crates/agent/src/brain/chat.rs create mode 100644 crates/agent/src/brain/exec.rs create mode 100644 crates/agent/src/brain/mod.rs create mode 100644 crates/agent/src/brain/provider.rs create mode 100644 crates/agent/src/brain/rig.rs create mode 100644 crates/agent/src/clock.rs create mode 100644 crates/agent/src/confirm.rs create mode 100644 crates/agent/src/event.rs create mode 100644 crates/agent/src/lib.rs create mode 100644 crates/agent/src/mcp/mod.rs create mode 100644 crates/agent/src/mcp/projection.rs create mode 100644 crates/agent/src/mcp/sample.rs create mode 100644 crates/agent/src/mcp/serve.rs create mode 100644 crates/agent/src/mcp/server.rs create mode 100644 crates/agent/src/port.rs create mode 100644 crates/agent/src/port/game.rs create mode 100644 crates/agent/src/redact.rs create mode 100644 crates/agent/src/registry/mod.rs create mode 100644 crates/agent/src/registry/schema.rs create mode 100644 crates/agent/src/registry/spec.rs create mode 100644 crates/agent/src/registry/validate.rs create mode 100644 crates/agent/src/testing.rs create mode 100644 crates/agent/src/testing/diagnose.rs create mode 100644 crates/agent/src/testing/game.rs create mode 100644 crates/agent/src/testing/settings.rs create mode 100644 crates/agent/src/tools/accounts.rs create mode 100644 crates/agent/src/tools/config.rs create mode 100644 crates/agent/src/tools/diagnose.rs create mode 100644 crates/agent/src/tools/game.rs create mode 100644 crates/agent/src/tools/mod.rs create mode 100644 crates/agent/src/tools/schema_tool.rs create mode 100644 crates/agent/src/tools/session.rs create mode 100644 crates/agent/tests/brain_loop.rs create mode 100644 crates/agent/tests/mcp_contract.rs create mode 100644 crates/agent/tests/mcp_http.rs create mode 100644 crates/agent/tests/schema_contract.rs create mode 100644 crates/agent/tests/support/mod.rs create mode 100644 crates/agent/tests/tools_security.rs create mode 100644 crates/app-iced/Cargo.toml create mode 100644 crates/app-iced/examples/pages_demo.rs create mode 100644 crates/app-iced/src/app/appearance.rs create mode 100644 crates/app-iced/src/app/backend.rs create mode 100644 crates/app-iced/src/app/boot.rs create mode 100644 crates/app-iced/src/app/boot/diagnostics.rs create mode 100644 crates/app-iced/src/app/boot/fallback.rs create mode 100644 crates/app-iced/src/app/boot/tests.rs create mode 100644 crates/app-iced/src/app/message.rs create mode 100644 crates/app-iced/src/app/mod.rs create mode 100644 crates/app-iced/src/app/state.rs create mode 100644 crates/app-iced/src/app/state/boot_probe.rs create mode 100644 crates/app-iced/src/app/state/construct.rs create mode 100644 crates/app-iced/src/app/state/refresh.rs create mode 100644 crates/app-iced/src/app/state/theme.rs create mode 100644 crates/app-iced/src/app/subscription.rs create mode 100644 crates/app-iced/src/app/tests.rs create mode 100644 crates/app-iced/src/app/tests/appearance.rs create mode 100644 crates/app-iced/src/app/tests/presenter.rs create mode 100644 crates/app-iced/src/app/update.rs create mode 100644 crates/app-iced/src/app/update/account.rs create mode 100644 crates/app-iced/src/app/update/account/tests.rs create mode 100644 crates/app-iced/src/app/update/agent.rs create mode 100644 crates/app-iced/src/app/update/agent/tests.rs create mode 100644 crates/app-iced/src/app/update/appearance.rs create mode 100644 crates/app-iced/src/app/update/boot_env.rs create mode 100644 crates/app-iced/src/app/update/clock.rs create mode 100644 crates/app-iced/src/app/update/content.rs create mode 100644 crates/app-iced/src/app/update/download.rs create mode 100644 crates/app-iced/src/app/update/download_wiring.rs create mode 100644 crates/app-iced/src/app/update/page_messages.rs create mode 100644 crates/app-iced/src/app/update/settings.rs create mode 100644 crates/app-iced/src/app/update/settings/ai_about.rs create mode 100644 crates/app-iced/src/app/update/settings/download.rs create mode 100644 crates/app-iced/src/app/update/settings/java.rs create mode 100644 crates/app-iced/src/app/update/settings/language_appearance.rs create mode 100644 crates/app-iced/src/app/update/settings/tests.rs create mode 100644 crates/app-iced/src/app/view.rs create mode 100644 crates/app-iced/src/app/view/account_page.rs create mode 100644 crates/app-iced/src/app/view/instances.rs create mode 100644 crates/app-iced/src/app/view/logs.rs create mode 100644 crates/app-iced/src/app/view/logs/tests.rs create mode 100644 crates/app-iced/src/app/view/rail.rs create mode 100644 crates/app-iced/src/app/view/tests.rs create mode 100644 crates/app-iced/src/app/window_alpha.rs create mode 100644 crates/app-iced/src/cli.rs create mode 100644 crates/app-iced/src/cli/tests.rs create mode 100644 crates/app-iced/src/components/buttons/assemble.rs create mode 100644 crates/app-iced/src/components/buttons/geometry.rs create mode 100644 crates/app-iced/src/components/buttons/mod.rs create mode 100644 crates/app-iced/src/components/buttons/tests.rs create mode 100644 crates/app-iced/src/components/divider.rs create mode 100644 crates/app-iced/src/components/feedback/action.rs create mode 100644 crates/app-iced/src/components/feedback/dialog.rs create mode 100644 crates/app-iced/src/components/feedback/empty_state.rs create mode 100644 crates/app-iced/src/components/feedback/gallery_parts.rs create mode 100644 crates/app-iced/src/components/feedback/geometry.rs create mode 100644 crates/app-iced/src/components/feedback/keyframes.rs create mode 100644 crates/app-iced/src/components/feedback/mod.rs create mode 100644 crates/app-iced/src/components/feedback/panel.rs create mode 100644 crates/app-iced/src/components/feedback/pixel.rs create mode 100644 crates/app-iced/src/components/feedback/probe.rs create mode 100644 crates/app-iced/src/components/feedback/probe/circular.rs create mode 100644 crates/app-iced/src/components/feedback/probe/panels.rs create mode 100644 crates/app-iced/src/components/feedback/progress.rs create mode 100644 crates/app-iced/src/components/feedback/snackbar.rs create mode 100644 crates/app-iced/src/components/feedback/tests.rs create mode 100644 crates/app-iced/src/components/feedback/tests/progress.rs create mode 100644 crates/app-iced/src/components/gallery/buttons.rs create mode 100644 crates/app-iced/src/components/gallery/feedback.rs create mode 100644 crates/app-iced/src/components/gallery/inputs.rs create mode 100644 crates/app-iced/src/components/gallery/mod.rs create mode 100644 crates/app-iced/src/components/gallery/navigation.rs create mode 100644 crates/app-iced/src/components/gallery/probe.rs create mode 100644 crates/app-iced/src/components/gallery/scan.rs create mode 100644 crates/app-iced/src/components/gallery/selection.rs create mode 100644 crates/app-iced/src/components/gate.rs create mode 100644 crates/app-iced/src/components/inputs/field.rs create mode 100644 crates/app-iced/src/components/inputs/field/tests.rs create mode 100644 crates/app-iced/src/components/inputs/geometry.rs create mode 100644 crates/app-iced/src/components/inputs/menu.rs create mode 100644 crates/app-iced/src/components/inputs/menu/tests.rs create mode 100644 crates/app-iced/src/components/inputs/mod.rs create mode 100644 crates/app-iced/src/components/inputs/probe.rs create mode 100644 crates/app-iced/src/components/inputs/probe/menu.rs create mode 100644 crates/app-iced/src/components/inputs/probe/search.rs create mode 100644 crates/app-iced/src/components/inputs/probe/slider.rs create mode 100644 crates/app-iced/src/components/inputs/probe/text.rs create mode 100644 crates/app-iced/src/components/inputs/search.rs create mode 100644 crates/app-iced/src/components/inputs/search/tests.rs create mode 100644 crates/app-iced/src/components/inputs/slider.rs create mode 100644 crates/app-iced/src/components/inputs/slider/tests.rs create mode 100644 crates/app-iced/src/components/inputs/slider/track.rs create mode 100644 crates/app-iced/src/components/interaction/disabled.rs create mode 100644 crates/app-iced/src/components/interaction/mod.rs create mode 100644 crates/app-iced/src/components/interaction/tracker.rs create mode 100644 crates/app-iced/src/components/layout.rs create mode 100644 crates/app-iced/src/components/mod.rs create mode 100644 crates/app-iced/src/components/navigation/app_bar.rs create mode 100644 crates/app-iced/src/components/navigation/drawer.rs create mode 100644 crates/app-iced/src/components/navigation/drawer/item.rs create mode 100644 crates/app-iced/src/components/navigation/drawer/tests.rs create mode 100644 crates/app-iced/src/components/navigation/geometry.rs create mode 100644 crates/app-iced/src/components/navigation/geometry/tests.rs create mode 100644 crates/app-iced/src/components/navigation/list_item.rs create mode 100644 crates/app-iced/src/components/navigation/list_item/tests.rs create mode 100644 crates/app-iced/src/components/navigation/matrix.rs create mode 100644 crates/app-iced/src/components/navigation/mod.rs create mode 100644 crates/app-iced/src/components/navigation/probe.rs create mode 100644 crates/app-iced/src/components/navigation/probe/divider.rs create mode 100644 crates/app-iced/src/components/navigation/probe/long.rs create mode 100644 crates/app-iced/src/components/navigation/probe/scan.rs create mode 100644 crates/app-iced/src/components/navigation/tabs.rs create mode 100644 crates/app-iced/src/components/navigation/tabs/tests.rs create mode 100644 crates/app-iced/src/components/selection/checkbox.rs create mode 100644 crates/app-iced/src/components/selection/chip.rs create mode 100644 crates/app-iced/src/components/selection/geometry.rs create mode 100644 crates/app-iced/src/components/selection/matrix.rs create mode 100644 crates/app-iced/src/components/selection/mod.rs create mode 100644 crates/app-iced/src/components/selection/paint/check.rs create mode 100644 crates/app-iced/src/components/selection/paint/chip.rs create mode 100644 crates/app-iced/src/components/selection/paint/mod.rs create mode 100644 crates/app-iced/src/components/selection/paint/radio.rs create mode 100644 crates/app-iced/src/components/selection/paint/switch.rs create mode 100644 crates/app-iced/src/components/selection/pixel.rs create mode 100644 crates/app-iced/src/components/selection/probe.rs create mode 100644 crates/app-iced/src/components/selection/radio.rs create mode 100644 crates/app-iced/src/components/selection/shell.rs create mode 100644 crates/app-iced/src/components/selection/switch.rs create mode 100644 crates/app-iced/src/components/selection/tests.rs create mode 100644 crates/app-iced/src/fonts.rs create mode 100644 crates/app-iced/src/fonts/cjk.rs create mode 100644 crates/app-iced/src/fonts/tests.rs create mode 100644 crates/app-iced/src/icons.rs create mode 100644 crates/app-iced/src/lib.rs create mode 100644 crates/app-iced/src/main.rs create mode 100644 crates/app-iced/src/pages/account.rs create mode 100644 crates/app-iced/src/pages/account/avatar.rs create mode 100644 crates/app-iced/src/pages/account/forms.rs create mode 100644 crates/app-iced/src/pages/account/login.rs create mode 100644 crates/app-iced/src/pages/account/model.rs create mode 100644 crates/app-iced/src/pages/account/panels.rs create mode 100644 crates/app-iced/src/pages/account/rows.rs create mode 100644 crates/app-iced/src/pages/account/tests.rs create mode 100644 crates/app-iced/src/pages/account/tests_text.rs create mode 100644 crates/app-iced/src/pages/account/widgets.rs create mode 100644 crates/app-iced/src/pages/agent/conversation.rs create mode 100644 crates/app-iced/src/pages/agent/conversation/banners.rs create mode 100644 crates/app-iced/src/pages/agent/conversation/composer.rs create mode 100644 crates/app-iced/src/pages/agent/conversation/transcript.rs create mode 100644 crates/app-iced/src/pages/agent/demo.rs create mode 100644 crates/app-iced/src/pages/agent/metrics.rs create mode 100644 crates/app-iced/src/pages/agent/metrics/tests.rs create mode 100644 crates/app-iced/src/pages/agent/mod.rs create mode 100644 crates/app-iced/src/pages/agent/state.rs create mode 100644 crates/app-iced/src/pages/agent/strip.rs create mode 100644 crates/app-iced/src/pages/agent/tests.rs create mode 100644 crates/app-iced/src/pages/agent/tests/disclaimer.rs create mode 100644 crates/app-iced/src/pages/agent/tests/drag.rs create mode 100644 crates/app-iced/src/pages/appearance/alpha.rs create mode 100644 crates/app-iced/src/pages/appearance/background.rs create mode 100644 crates/app-iced/src/pages/appearance/background/tests.rs create mode 100644 crates/app-iced/src/pages/appearance/mod.rs create mode 100644 crates/app-iced/src/pages/appearance/palette.rs create mode 100644 crates/app-iced/src/pages/appearance/picture.rs create mode 100644 crates/app-iced/src/pages/appearance/section.rs create mode 100644 crates/app-iced/src/pages/appearance/state.rs create mode 100644 crates/app-iced/src/pages/content.rs create mode 100644 crates/app-iced/src/pages/content/demo.rs create mode 100644 crates/app-iced/src/pages/content/layout.rs create mode 100644 crates/app-iced/src/pages/content/message.rs create mode 100644 crates/app-iced/src/pages/content/model.rs create mode 100644 crates/app-iced/src/pages/content/model/items.rs create mode 100644 crates/app-iced/src/pages/content/model/tests.rs create mode 100644 crates/app-iced/src/pages/content/packui.rs create mode 100644 crates/app-iced/src/pages/content/packui/demo.rs create mode 100644 crates/app-iced/src/pages/content/packui/message.rs create mode 100644 crates/app-iced/src/pages/content/packui/model.rs create mode 100644 crates/app-iced/src/pages/content/packui/model/export.rs create mode 100644 crates/app-iced/src/pages/content/packui/model/progress.rs create mode 100644 crates/app-iced/src/pages/content/packui/model/report.rs create mode 100644 crates/app-iced/src/pages/content/packui/model/tests.rs create mode 100644 crates/app-iced/src/pages/content/packui/tests.rs create mode 100644 crates/app-iced/src/pages/content/packui/view.rs create mode 100644 crates/app-iced/src/pages/content/packui/view/export.rs create mode 100644 crates/app-iced/src/pages/content/packui/view/parts.rs create mode 100644 crates/app-iced/src/pages/content/packui/view/progress.rs create mode 100644 crates/app-iced/src/pages/content/packui/view/report.rs create mode 100644 crates/app-iced/src/pages/content/parts.rs create mode 100644 crates/app-iced/src/pages/content/parts/detail.rs create mode 100644 crates/app-iced/src/pages/content/parts/filters.rs create mode 100644 crates/app-iced/src/pages/content/tests.rs create mode 100644 crates/app-iced/src/pages/content/view.rs create mode 100644 crates/app-iced/src/pages/download.rs create mode 100644 crates/app-iced/src/pages/download/demo.rs create mode 100644 crates/app-iced/src/pages/download/group.rs create mode 100644 crates/app-iced/src/pages/download/group/tests.rs create mode 100644 crates/app-iced/src/pages/download/install.rs create mode 100644 crates/app-iced/src/pages/download/install/tests.rs create mode 100644 crates/app-iced/src/pages/download/model.rs create mode 100644 crates/app-iced/src/pages/download/model/category.rs create mode 100644 crates/app-iced/src/pages/download/model/tests.rs create mode 100644 crates/app-iced/src/pages/download/options.rs create mode 100644 crates/app-iced/src/pages/download/options/model.rs create mode 100644 crates/app-iced/src/pages/download/options/tests.rs create mode 100644 crates/app-iced/src/pages/download/options/view.rs create mode 100644 crates/app-iced/src/pages/download/rails.rs create mode 100644 crates/app-iced/src/pages/download/rows.rs create mode 100644 crates/app-iced/src/pages/download/rows/tests.rs create mode 100644 crates/app-iced/src/pages/download/states.rs create mode 100644 crates/app-iced/src/pages/download/tests.rs create mode 100644 crates/app-iced/src/pages/download/tests/i18n.rs create mode 100644 crates/app-iced/src/pages/download/tests/rails.rs create mode 100644 crates/app-iced/src/pages/download/tests/search.rs create mode 100644 crates/app-iced/src/pages/download/tests/view.rs create mode 100644 crates/app-iced/src/pages/frame.rs create mode 100644 crates/app-iced/src/pages/frame/pieces.rs create mode 100644 crates/app-iced/src/pages/frame/tests.rs create mode 100644 crates/app-iced/src/pages/harness.rs create mode 100644 crates/app-iced/src/pages/harness/app.rs create mode 100644 crates/app-iced/src/pages/harness/caps.rs create mode 100644 crates/app-iced/src/pages/harness/request.rs create mode 100644 crates/app-iced/src/pages/harness/tests.rs create mode 100644 crates/app-iced/src/pages/instances.rs create mode 100644 crates/app-iced/src/pages/instances/data.rs create mode 100644 crates/app-iced/src/pages/instances/demo.rs create mode 100644 crates/app-iced/src/pages/instances/detail.rs create mode 100644 crates/app-iced/src/pages/instances/tests.rs create mode 100644 crates/app-iced/src/pages/instances/tests/i18n.rs create mode 100644 crates/app-iced/src/pages/instances/text.rs create mode 100644 crates/app-iced/src/pages/layout.rs create mode 100644 crates/app-iced/src/pages/layout/block.rs create mode 100644 crates/app-iced/src/pages/layout/block/tests.rs create mode 100644 crates/app-iced/src/pages/layout/rails.rs create mode 100644 crates/app-iced/src/pages/layout/rails/tests.rs create mode 100644 crates/app-iced/src/pages/layout/source.rs create mode 100644 crates/app-iced/src/pages/layout/source/tests.rs create mode 100644 crates/app-iced/src/pages/layout/tests.rs create mode 100644 crates/app-iced/src/pages/layout/wrap.rs create mode 100644 crates/app-iced/src/pages/layout/wrap/tests.rs create mode 100644 crates/app-iced/src/pages/logs.rs create mode 100644 crates/app-iced/src/pages/logs/demo.rs create mode 100644 crates/app-iced/src/pages/logs/diagnostic.rs create mode 100644 crates/app-iced/src/pages/logs/lines.rs create mode 100644 crates/app-iced/src/pages/logs/model.rs create mode 100644 crates/app-iced/src/pages/logs/panel.rs create mode 100644 crates/app-iced/src/pages/logs/sample_crash.log create mode 100644 crates/app-iced/src/pages/logs/sample_live.log create mode 100644 crates/app-iced/src/pages/logs/tests.rs create mode 100644 crates/app-iced/src/pages/message.rs create mode 100644 crates/app-iced/src/pages/mod.rs create mode 100644 crates/app-iced/src/pages/model.rs create mode 100644 crates/app-iced/src/pages/nav.rs create mode 100644 crates/app-iced/src/pages/screen.rs create mode 100644 crates/app-iced/src/pages/settings/ai_about.rs create mode 100644 crates/app-iced/src/pages/settings/appearance.rs create mode 100644 crates/app-iced/src/pages/settings/download.rs create mode 100644 crates/app-iced/src/pages/settings/frame.rs create mode 100644 crates/app-iced/src/pages/settings/general.rs create mode 100644 crates/app-iced/src/pages/settings/java.rs create mode 100644 crates/app-iced/src/pages/settings/language_appearance.rs create mode 100644 crates/app-iced/src/pages/settings/message.rs create mode 100644 crates/app-iced/src/pages/settings/mod.rs create mode 100644 crates/app-iced/src/pages/settings/state.rs create mode 100644 crates/app-iced/src/pages/settings/tests/appearance_section.rs create mode 100644 crates/app-iced/src/pages/settings/tests/download_section.rs create mode 100644 crates/app-iced/src/pages/settings/tests/general_section.rs create mode 100644 crates/app-iced/src/pages/settings/tests/java_section.rs create mode 100644 crates/app-iced/src/pages/settings/tests/mod.rs create mode 100644 crates/app-iced/src/pages/tests.rs create mode 100644 crates/app-iced/src/platform/locale.rs create mode 100644 crates/app-iced/src/platform/mod.rs create mode 100644 crates/app-iced/src/platform/win32/corner.rs create mode 100644 crates/app-iced/src/platform/win32/corner/tests.rs create mode 100644 crates/app-iced/src/platform/win32/mod.rs create mode 100644 crates/app-iced/src/platform/win32/transparency.rs create mode 100644 crates/app-iced/src/platform/win32/transparency/alpha.rs create mode 100644 crates/app-iced/src/platform/win32/transparency/dwm.rs create mode 100644 crates/app-iced/src/platform/win32/transparency/exstyle.rs create mode 100644 crates/app-iced/src/platform/win32/transparency/probe.rs create mode 100644 crates/app-iced/src/platform/win32/transparency/tests.rs create mode 100644 crates/app-iced/src/presenter/agent.rs create mode 100644 crates/app-iced/src/presenter/mod.rs create mode 100644 crates/app-iced/src/presenter/rig.rs create mode 100644 crates/app-iced/src/presenter/transport.rs create mode 100644 crates/app-iced/src/probe.rs create mode 100644 crates/app-iced/src/renderer/acceptance/locale.rs create mode 100644 crates/app-iced/src/renderer/acceptance/locale_tests.rs create mode 100644 crates/app-iced/src/renderer/acceptance/mod.rs create mode 100644 crates/app-iced/src/renderer/acceptance/tests.rs create mode 100644 crates/app-iced/src/renderer/acceptance/visual.rs create mode 100644 crates/app-iced/src/renderer/acceptance/window.rs create mode 100644 crates/app-iced/src/renderer/decision.rs create mode 100644 crates/app-iced/src/renderer/log_bridge.rs create mode 100644 crates/app-iced/src/renderer/mod.rs create mode 100644 crates/app-iced/src/renderer/preflight.rs create mode 100644 crates/app-iced/src/shell/mod.rs create mode 100644 crates/app-iced/src/shell/nav.rs create mode 100644 crates/app-iced/src/shell/nav/account.rs create mode 100644 crates/app-iced/src/shell/tests.rs create mode 100644 crates/app-iced/src/shot/diff.rs create mode 100644 crates/app-iced/src/shot/mod.rs create mode 100644 crates/app-iced/src/theme.rs create mode 100644 crates/app-iced/src/ui.rs create mode 100644 crates/app-iced/src/ui/lang.rs create mode 100644 crates/app-iced/tests/no_hardcoded_tokens.rs create mode 100644 crates/app/Cargo.toml create mode 100644 crates/app/build.rs create mode 100644 crates/app/src/appearance_bind.rs create mode 100644 crates/app/src/bg_image.rs create mode 100644 crates/app/src/callbacks.rs create mode 100644 crates/app/src/callbacks_pages.rs create mode 100644 crates/app/src/conv/agent.rs create mode 100644 crates/app/src/conv/instances.rs create mode 100644 crates/app/src/conv/logs.rs create mode 100644 crates/app/src/conv/mod.rs create mode 100644 crates/app/src/conv/pages.rs create mode 100644 crates/app/src/conv/pages_tests.rs create mode 100644 crates/app/src/conv/ui.rs create mode 100644 crates/app/src/conv/versions.rs create mode 100644 crates/app/src/main.rs create mode 100644 crates/app/src/page_sync.rs create mode 100644 crates/app/src/png.rs create mode 100644 crates/app/src/screenshot.rs create mode 100644 crates/app/src/theme_runtime.rs create mode 100644 crates/app/src/ui_bind.rs create mode 100644 crates/app/ui/components/ai-panel.slint create mode 100644 crates/app/ui/components/badge.slint create mode 100644 crates/app/ui/components/glass.slint create mode 100644 crates/app/ui/components/icons.slint create mode 100644 crates/app/ui/components/install-panel.slint create mode 100644 crates/app/ui/components/label.slint create mode 100644 crates/app/ui/components/nav.slint create mode 100644 crates/app/ui/components/notice-bar.slint create mode 100644 crates/app/ui/components/progress-bar.slint create mode 100644 crates/app/ui/components/progress-ring.slint create mode 100644 crates/app/ui/components/tile.slint create mode 100644 crates/app/ui/components/titlebar.slint create mode 100644 crates/app/ui/main.slint create mode 100644 crates/app/ui/models.slint create mode 100644 crates/app/ui/page_state.slint create mode 100644 crates/app/ui/pages/download-java.slint create mode 100644 crates/app/ui/pages/download.slint create mode 100644 crates/app/ui/pages/instances.slint create mode 100644 crates/app/ui/pages/logs.slint create mode 100644 crates/app/ui/pages/settings-account.slint create mode 100644 crates/app/ui/pages/settings-appearance.slint create mode 100644 crates/app/ui/pages/settings-groups.slint create mode 100644 crates/app/ui/pages/settings.slint create mode 100644 crates/app/ui/shell.slint create mode 100644 crates/app/ui/theme/metrics.slint create mode 100644 crates/app/ui/theme/tokens.slint create mode 100644 crates/app/ui/widgets/button.slint create mode 100644 crates/app/ui/widgets/dialog.slint create mode 100644 crates/app/ui/widgets/inputs.slint create mode 100644 crates/app/ui/widgets/setting-item.slint create mode 100644 crates/app/ui/widgets/toast.slint create mode 100644 crates/app/ui/widgets/wizard.slint create mode 100644 crates/cli/Cargo.toml create mode 100644 crates/cli/src/cli/help.rs create mode 100644 crates/cli/src/cli/mod.rs create mode 100644 crates/cli/src/cli/model.rs create mode 100644 crates/cli/src/cli/parse.rs create mode 100644 crates/cli/src/cli/parse/accounts.rs create mode 100644 crates/cli/src/cli/parse/agent.rs create mode 100644 crates/cli/src/cli/program.rs create mode 100644 crates/cli/src/commands/accounts.rs create mode 100644 crates/cli/src/commands/agent/mod.rs create mode 100644 crates/cli/src/commands/agent/ports/accounts.rs create mode 100644 crates/cli/src/commands/agent/ports/diagnose.rs create mode 100644 crates/cli/src/commands/agent/ports/events.rs create mode 100644 crates/cli/src/commands/agent/ports/game.rs create mode 100644 crates/cli/src/commands/agent/ports/mod.rs create mode 100644 crates/cli/src/commands/agent/ports/session.rs create mode 100644 crates/cli/src/commands/agent/ports/setting.rs create mode 100644 crates/cli/src/commands/agent/ports/setting/tests.rs create mode 100644 crates/cli/src/commands/agent/serve.rs create mode 100644 crates/cli/src/commands/config.rs create mode 100644 crates/cli/src/commands/config/tests.rs create mode 100644 crates/cli/src/commands/identity.rs create mode 100644 crates/cli/src/commands/install/loader.rs create mode 100644 crates/cli/src/commands/install/loader_processors.rs create mode 100644 crates/cli/src/commands/install/mod.rs create mode 100644 crates/cli/src/commands/install/report.rs create mode 100644 crates/cli/src/commands/install/report_loader.rs create mode 100644 crates/cli/src/commands/install/vanilla.rs create mode 100644 crates/cli/src/commands/instances.rs create mode 100644 crates/cli/src/commands/java.rs create mode 100644 crates/cli/src/commands/java_launch.rs create mode 100644 crates/cli/src/commands/java_vendors.rs create mode 100644 crates/cli/src/commands/launch.rs create mode 100644 crates/cli/src/commands/meta.rs create mode 100644 crates/cli/src/commands/mod.rs create mode 100644 crates/cli/src/commands/pack.rs create mode 100644 crates/cli/src/commands/sessions.rs create mode 100644 crates/cli/src/commands/snapshot.rs create mode 100644 crates/cli/src/context.rs create mode 100644 crates/cli/src/error.rs create mode 100644 crates/cli/src/lib.rs create mode 100644 crates/cli/src/main.rs create mode 100644 crates/cli/src/os.rs create mode 100644 crates/cli/src/output.rs create mode 100644 crates/cli/src/runner.rs create mode 100644 crates/cli/tests/accounts_test.rs create mode 100644 crates/cli/tests/agent_mcp_stdio_test.rs create mode 100644 crates/cli/tests/config_secret_test.rs create mode 100644 crates/cli/tests/exit_code_test.rs create mode 100644 crates/cli/tests/isolation_launch_test.rs create mode 100644 crates/cli/tests/java_test.rs create mode 100644 crates/cli/tests/os_test.rs create mode 100644 crates/cli/tests/output_test.rs create mode 100644 crates/cli/tests/pack_test.rs create mode 100644 crates/cli/tests/parse_test.rs create mode 100644 crates/cli/tests/support/mod.rs create mode 100644 crates/core/Cargo.toml create mode 100644 crates/core/src/addon/export.rs create mode 100644 crates/core/src/addon/export/catalog.rs create mode 100644 crates/core/src/addon/export/classify.rs create mode 100644 crates/core/src/addon/export/pipeline.rs create mode 100644 crates/core/src/addon/export/report.rs create mode 100644 crates/core/src/addon/export/scan.rs create mode 100644 crates/core/src/addon/export/snapshot.rs create mode 100644 crates/core/src/addon/import.rs create mode 100644 crates/core/src/addon/import/baseline.rs create mode 100644 crates/core/src/addon/import/error.rs create mode 100644 crates/core/src/addon/import/fetch.rs create mode 100644 crates/core/src/addon/import/merge.rs create mode 100644 crates/core/src/addon/import/phase.rs create mode 100644 crates/core/src/addon/import/pipeline.rs create mode 100644 crates/core/src/addon/import/plan.rs create mode 100644 crates/core/src/addon/import/plan/paths.rs create mode 100644 crates/core/src/addon/import/report.rs create mode 100644 crates/core/src/addon/import/report/items.rs create mode 100644 crates/core/src/addon/import/report/keys.rs create mode 100644 crates/core/src/addon/import/stage.rs create mode 100644 crates/core/src/addon/import/stage/commit.rs create mode 100644 crates/core/src/addon/loader/fabric.rs create mode 100644 crates/core/src/addon/loader/forge.rs create mode 100644 crates/core/src/addon/loader/maven.rs create mode 100644 crates/core/src/addon/loader/meta.rs create mode 100644 crates/core/src/addon/loader/mod.rs create mode 100644 crates/core/src/addon/loader/plan.rs create mode 100644 crates/core/src/addon/loader/processors/download.rs create mode 100644 crates/core/src/addon/loader/processors/error.rs create mode 100644 crates/core/src/addon/loader/processors/exec.rs create mode 100644 crates/core/src/addon/loader/processors/jar.rs create mode 100644 crates/core/src/addon/loader/processors/mod.rs create mode 100644 crates/core/src/addon/loader/processors/plan.rs create mode 100644 crates/core/src/addon/loader/processors/prepare.rs create mode 100644 crates/core/src/addon/loader/processors/spec.rs create mode 100644 crates/core/src/addon/loader/processors/tests/exec.rs create mode 100644 crates/core/src/addon/loader/processors/tests/mod.rs create mode 100644 crates/core/src/addon/loader/processors/tests/plan.rs create mode 100644 crates/core/src/addon/loader/processors/tests/vars.rs create mode 100644 crates/core/src/addon/loader/processors/text.rs create mode 100644 crates/core/src/addon/loader/processors/vars.rs create mode 100644 crates/core/src/addon/loader/tests/fabric.rs create mode 100644 crates/core/src/addon/loader/tests/forge.rs create mode 100644 crates/core/src/addon/loader/tests/maven.rs create mode 100644 crates/core/src/addon/loader/tests/mod.rs create mode 100644 crates/core/src/addon/loader/tests/plan.rs create mode 100644 crates/core/src/addon/mod.rs create mode 100644 crates/core/src/addon/pack.rs create mode 100644 crates/core/src/addon/pack/archive.rs create mode 100644 crates/core/src/addon/pack/archive/entry.rs create mode 100644 crates/core/src/addon/pack/archive/limits.rs create mode 100644 crates/core/src/addon/pack/archive/open.rs create mode 100644 crates/core/src/addon/pack/curseforge.rs create mode 100644 crates/core/src/addon/pack/curseforge/fingerprint.rs create mode 100644 crates/core/src/addon/pack/error.rs create mode 100644 crates/core/src/addon/pack/format.rs create mode 100644 crates/core/src/addon/pack/format/payload.rs create mode 100644 crates/core/src/addon/pack/manifest.rs create mode 100644 crates/core/src/addon/pack/manifest/entries.rs create mode 100644 crates/core/src/addon/pack/modrinth.rs create mode 100644 crates/core/src/addon/pack/multimc.rs create mode 100644 crates/core/src/addon/pack/path.rs create mode 100644 crates/core/src/addon/pack/tests/detect.rs create mode 100644 crates/core/src/addon/pack/tests/export.rs create mode 100644 crates/core/src/addon/pack/tests/export_harness.rs create mode 100644 crates/core/src/addon/pack/tests/export_pipeline.rs create mode 100644 crates/core/src/addon/pack/tests/export_roundtrip.rs create mode 100644 crates/core/src/addon/pack/tests/extend.rs create mode 100644 crates/core/src/addon/pack/tests/fixtures.rs create mode 100644 crates/core/src/addon/pack/tests/mod.rs create mode 100644 crates/core/src/addon/pack/tests/model.rs create mode 100644 crates/core/src/addon/pack/tests/roundtrip.rs create mode 100644 crates/core/src/addon/pack/tests/safety.rs create mode 100644 crates/core/src/addon/pack/tests/unknown_fields.rs create mode 100644 crates/core/src/addon/tests/import_curseforge.rs create mode 100644 crates/core/src/addon/tests/import_failures.rs create mode 100644 crates/core/src/addon/tests/import_merge.rs create mode 100644 crates/core/src/addon/tests/import_modrinth.rs create mode 100644 crates/core/src/addon/tests/import_multimc.rs create mode 100644 crates/core/src/addon/tests/import_report.rs create mode 100644 crates/core/src/addon/tests/mod.rs create mode 100644 crates/core/src/addon/tests/support.rs create mode 100644 crates/core/src/auth/account.rs create mode 100644 crates/core/src/auth/authlib.rs create mode 100644 crates/core/src/auth/authlib/server_meta.rs create mode 100644 crates/core/src/auth/authlib/tests.rs create mode 100644 crates/core/src/auth/body/mod.rs create mode 100644 crates/core/src/auth/body/tests.rs create mode 100644 crates/core/src/auth/error.rs create mode 100644 crates/core/src/auth/http.rs create mode 100644 crates/core/src/auth/journal.rs create mode 100644 crates/core/src/auth/microsoft/authcode.rs create mode 100644 crates/core/src/auth/microsoft/callback.rs create mode 100644 crates/core/src/auth/microsoft/chain.rs create mode 100644 crates/core/src/auth/microsoft/client_id.rs create mode 100644 crates/core/src/auth/microsoft/endpoints.rs create mode 100644 crates/core/src/auth/microsoft/flow.rs create mode 100644 crates/core/src/auth/microsoft/mod.rs create mode 100644 crates/core/src/auth/microsoft/session.rs create mode 100644 crates/core/src/auth/mod.rs create mode 100644 crates/core/src/auth/offline.rs create mode 100644 crates/core/src/auth/secret.rs create mode 100644 crates/core/src/auth/store.rs create mode 100644 crates/core/src/auth/store/payload.rs create mode 100644 crates/core/src/diagnose/collectors.rs create mode 100644 crates/core/src/diagnose/engine.rs create mode 100644 crates/core/src/diagnose/environment.rs create mode 100644 crates/core/src/diagnose/finding.rs create mode 100644 crates/core/src/diagnose/fix_action.rs create mode 100644 crates/core/src/diagnose/fix_params.rs create mode 100644 crates/core/src/diagnose/hs_err.rs create mode 100644 crates/core/src/diagnose/hs_err_report.rs create mode 100644 crates/core/src/diagnose/loader.rs create mode 100644 crates/core/src/diagnose/mod.rs create mode 100644 crates/core/src/diagnose/rules.d/fabric.yaml create mode 100644 crates/core/src/diagnose/rules.d/forge.yaml create mode 100644 crates/core/src/diagnose/rules.d/graphics.yaml create mode 100644 crates/core/src/diagnose/rules.d/integrity.yaml create mode 100644 crates/core/src/diagnose/rules.d/jvm.yaml create mode 100644 crates/core/src/diagnose/rules.d/memory.yaml create mode 100644 crates/core/src/diagnose/rules.d/mod_conflict.yaml create mode 100644 crates/core/src/diagnose/rules.d/mod_runtime.yaml create mode 100644 crates/core/src/diagnose/rules.d/other.yaml create mode 100644 crates/core/src/diagnose/rules.d/samples/fabric/loader_0_12.log create mode 100644 crates/core/src/diagnose/rules.d/samples/fabric/mod_resolution.log create mode 100644 crates/core/src/diagnose/rules.d/samples/fabric/mod_resolution_collection.log create mode 100644 crates/core/src/diagnose/rules.d/samples/fabric/mod_resolution_conflict.log create mode 100644 crates/core/src/diagnose/rules.d/samples/fabric/mod_resolution_details.log create mode 100644 crates/core/src/diagnose/rules.d/samples/fabric/mod_resolution_missing.log create mode 100644 crates/core/src/diagnose/rules.d/samples/fabric/mod_resolution_missing_minecraft.log create mode 100644 crates/core/src/diagnose/rules.d/samples/fabric/warnings.log create mode 100644 crates/core/src/diagnose/rules.d/samples/forge/bootstrap_failed.log create mode 100644 crates/core/src/diagnose/rules.d/samples/forge/duplicate_mods.log create mode 100644 crates/core/src/diagnose/rules.d/samples/forge/duplicated_mod.log create mode 100644 crates/core/src/diagnose/rules.d/samples/forge/missing_dependencies.log create mode 100644 crates/core/src/diagnose/rules.d/samples/forge/module_name_invalid.log create mode 100644 crates/core/src/diagnose/rules.d/samples/forge/optifine_repeat_installation.log create mode 100644 crates/core/src/diagnose/rules.d/samples/forge/repeat_installation.log create mode 100644 crates/core/src/diagnose/rules.d/samples/forge/too_many_mods.log create mode 100644 crates/core/src/diagnose/rules.d/samples/graphics/gl_operation_failure.log create mode 100644 crates/core/src/diagnose/rules.d/samples/graphics/graphics_driver.log create mode 100644 crates/core/src/diagnose/rules.d/samples/graphics/macos_display_port.log create mode 100644 crates/core/src/diagnose/rules.d/samples/graphics/no_graphics_backend.log create mode 100644 crates/core/src/diagnose/rules.d/samples/graphics/opengl_not_supported.log create mode 100644 crates/core/src/diagnose/rules.d/samples/graphics/resolution_too_high.log create mode 100644 crates/core/src/diagnose/rules.d/samples/graphics/rtss_sodium.log create mode 100644 crates/core/src/diagnose/rules.d/samples/graphics/vulkan_device_version_too_low.log create mode 100644 crates/core/src/diagnose/rules.d/samples/graphics/vulkan_loader_missing.log create mode 100644 crates/core/src/diagnose/rules.d/samples/graphics/vulkan_missing_extension.log create mode 100644 crates/core/src/diagnose/rules.d/samples/graphics/vulkan_missing_feature.log create mode 100644 crates/core/src/diagnose/rules.d/samples/hs_err/access_violation.log create mode 100644 crates/core/src/diagnose/rules.d/samples/hs_err/out_of_memory.log create mode 100644 crates/core/src/diagnose/rules.d/samples/integrity/file_already_exists.log create mode 100644 crates/core/src/diagnose/rules.d/samples/integrity/file_changed.log create mode 100644 crates/core/src/diagnose/rules.d/samples/integrity/illegal_access.log create mode 100644 crates/core/src/diagnose/rules.d/samples/integrity/incomplete_forge.log create mode 100644 crates/core/src/diagnose/rules.d/samples/integrity/mod_files_decompressed.log create mode 100644 crates/core/src/diagnose/rules.d/samples/integrity/no_class_def_found.log create mode 100644 crates/core/src/diagnose/rules.d/samples/integrity/no_such_method.log create mode 100644 crates/core/src/diagnose/rules.d/samples/integrity/unsatisfied_link.log create mode 100644 crates/core/src/diagnose/rules.d/samples/jvm/java_version_is_too_high.log create mode 100644 crates/core/src/diagnose/rules.d/samples/jvm/jdk_9.log create mode 100644 crates/core/src/diagnose/rules.d/samples/jvm/jvm_32bit.log create mode 100644 crates/core/src/diagnose/rules.d/samples/jvm/mac_jdk8u261.log create mode 100644 crates/core/src/diagnose/rules.d/samples/jvm/modlauncher_8.log create mode 100644 crates/core/src/diagnose/rules.d/samples/jvm/need_jdk11.log create mode 100644 crates/core/src/diagnose/rules.d/samples/jvm/openj9.log create mode 100644 crates/core/src/diagnose/rules.d/samples/jvm/too_old_java.log create mode 100644 crates/core/src/diagnose/rules.d/samples/memory/memory_exceeded.log create mode 100644 crates/core/src/diagnose/rules.d/samples/memory/out_of_memory.log create mode 100644 crates/core/src/diagnose/rules.d/samples/mod_conflict/jade_optifine.log create mode 100644 crates/core/src/diagnose/rules.d/samples/mod_conflict/multipart_optifine.log create mode 100644 crates/core/src/diagnose/rules.d/samples/mod_conflict/neoforge_optifine.log create mode 100644 crates/core/src/diagnose/rules.d/samples/mod_conflict/optifine_forge.log create mode 100644 crates/core/src/diagnose/rules.d/samples/mod_conflict/optifine_world_load.log create mode 100644 crates/core/src/diagnose/rules.d/samples/mod_conflict/performant_optifine.log create mode 100644 crates/core/src/diagnose/rules.d/samples/mod_conflict/shaders_mod.log create mode 100644 crates/core/src/diagnose/rules.d/samples/mod_conflict/twilight_optifine.log create mode 100644 crates/core/src/diagnose/rules.d/samples/mod_runtime/config_failed.log create mode 100644 crates/core/src/diagnose/rules.d/samples/mod_runtime/forge_error.log create mode 100644 crates/core/src/diagnose/rules.d/samples/mod_runtime/install_mixinbootstrap.log create mode 100644 crates/core/src/diagnose/rules.d/samples/mod_runtime/loading_crashed_fabric.log create mode 100644 crates/core/src/diagnose/rules.d/samples/mod_runtime/loading_crashed_forge.log create mode 100644 crates/core/src/diagnose/rules.d/samples/mod_runtime/mixin_apply_failed.log create mode 100644 crates/core/src/diagnose/rules.d/samples/mod_runtime/mixin_failure.log create mode 100644 crates/core/src/diagnose/rules.d/samples/mod_runtime/night_config_fixes.log create mode 100644 crates/core/src/diagnose/rules.d/samples/other/debug_crash.log create mode 100644 crates/core/src/diagnose/rules.d/samples/world/block_model.log create mode 100644 crates/core/src/diagnose/rules.d/samples/world/entity_tick.log create mode 100644 crates/core/src/diagnose/rules.d/world.yaml create mode 100644 crates/core/src/diagnose/rules.rs create mode 100644 crates/core/src/diagnose/signals.rs create mode 100644 crates/core/src/diagnose/sources.rs create mode 100644 crates/core/src/diagnose/synthetic.rs create mode 100644 crates/core/src/download/adoptium.rs create mode 100644 crates/core/src/download/atomic.rs create mode 100644 crates/core/src/download/backoff.rs create mode 100644 crates/core/src/download/blocking.rs create mode 100644 crates/core/src/download/bytes.rs create mode 100644 crates/core/src/download/cache.rs create mode 100644 crates/core/src/download/chunked.rs create mode 100644 crates/core/src/download/config.rs create mode 100644 crates/core/src/download/engine.rs create mode 100644 crates/core/src/download/error.rs create mode 100644 crates/core/src/download/health.rs create mode 100644 crates/core/src/download/health_store.rs create mode 100644 crates/core/src/download/http.rs create mode 100644 crates/core/src/download/jdk_sources.rs create mode 100644 crates/core/src/download/mirrors.json create mode 100644 crates/core/src/download/mirrors.rs create mode 100644 crates/core/src/download/mod.rs create mode 100644 crates/core/src/download/progress.rs create mode 100644 crates/core/src/download/region.rs create mode 100644 crates/core/src/download/region_system.rs create mode 100644 crates/core/src/download/resume.rs create mode 100644 crates/core/src/download/transfer.rs create mode 100644 crates/core/src/download/transfer_chunk.rs create mode 100644 crates/core/src/download/types.rs create mode 100644 crates/core/src/download/verify.rs create mode 100644 crates/core/src/game/arguments.rs create mode 100644 crates/core/src/game/capability.rs create mode 100644 crates/core/src/game/data/unlisted-versions.json create mode 100644 crates/core/src/game/error.rs create mode 100644 crates/core/src/game/inherit.rs create mode 100644 crates/core/src/game/install/assets.rs create mode 100644 crates/core/src/game/install/execute.rs create mode 100644 crates/core/src/game/install/instance.rs create mode 100644 crates/core/src/game/install/libraries.rs create mode 100644 crates/core/src/game/install/mod.rs create mode 100644 crates/core/src/game/install/plan.rs create mode 100644 crates/core/src/game/install/plan_view.rs create mode 100644 crates/core/src/game/install/report.rs create mode 100644 crates/core/src/game/install/source.rs create mode 100644 crates/core/src/game/install/tests/execute.rs create mode 100644 crates/core/src/game/install/tests/instance.rs create mode 100644 crates/core/src/game/install/tests/mod.rs create mode 100644 crates/core/src/game/install/tests/plan.rs create mode 100644 crates/core/src/game/isolation.rs create mode 100644 crates/core/src/game/java/api.rs create mode 100644 crates/core/src/game/java/discover.rs create mode 100644 crates/core/src/game/java/error.rs create mode 100644 crates/core/src/game/java/extract.rs create mode 100644 crates/core/src/game/java/install.rs create mode 100644 crates/core/src/game/java/location.rs create mode 100644 crates/core/src/game/java/mapping.rs create mode 100644 crates/core/src/game/java/microsoft.rs create mode 100644 crates/core/src/game/java/mod.rs create mode 100644 crates/core/src/game/java/net.rs create mode 100644 crates/core/src/game/java/oracle.rs create mode 100644 crates/core/src/game/java/probe.rs create mode 100644 crates/core/src/game/java/release.rs create mode 100644 crates/core/src/game/java/select.rs create mode 100644 crates/core/src/game/java/source.rs create mode 100644 crates/core/src/game/java/target.rs create mode 100644 crates/core/src/game/java/vendor.rs create mode 100644 crates/core/src/game/java/zulu.rs create mode 100644 crates/core/src/game/layout.rs create mode 100644 crates/core/src/game/library.rs create mode 100644 crates/core/src/game/manifest.rs create mode 100644 crates/core/src/game/mod.rs create mode 100644 crates/core/src/game/profiles.rs create mode 100644 crates/core/src/game/snapshot.rs create mode 100644 crates/core/src/game/unlisted.rs create mode 100644 crates/core/src/game/version.rs create mode 100644 crates/core/src/launch/adapter.rs create mode 100644 crates/core/src/launch/args_table.rs create mode 100644 crates/core/src/launch/argument.rs create mode 100644 crates/core/src/launch/command_builder.rs create mode 100644 crates/core/src/launch/crash_scan.rs create mode 100644 crates/core/src/launch/defaults.rs create mode 100644 crates/core/src/launch/diagnosis_hook.rs create mode 100644 crates/core/src/launch/error.rs create mode 100644 crates/core/src/launch/exit_analysis.rs create mode 100644 crates/core/src/launch/game_args.rs create mode 100644 crates/core/src/launch/game_version.rs create mode 100644 crates/core/src/launch/jvm_args.rs create mode 100644 crates/core/src/launch/launch_session.rs create mode 100644 crates/core/src/launch/launcher.rs create mode 100644 crates/core/src/launch/log_level.rs create mode 100644 crates/core/src/launch/mod.rs create mode 100644 crates/core/src/launch/natives/jar.rs create mode 100644 crates/core/src/launch/natives/mod.rs create mode 100644 crates/core/src/launch/placeholders.rs create mode 100644 crates/core/src/launch/platform.rs create mode 100644 crates/core/src/launch/process.rs create mode 100644 crates/core/src/launch/pump.rs create mode 100644 crates/core/src/launch/redact.rs create mode 100644 crates/core/src/launch/request.rs create mode 100644 crates/core/src/launch/session.rs create mode 100644 crates/core/src/launch/session_index.rs create mode 100644 crates/core/src/launch/session_meta.rs create mode 100644 crates/core/src/launch/session_payload.rs create mode 100644 crates/core/src/launch/session_sink.rs create mode 100644 crates/core/src/launch/sink.rs create mode 100644 crates/core/src/launch/time.rs create mode 100644 crates/core/src/launch/tree_kill.rs create mode 100644 crates/core/src/launch/watchdog.rs create mode 100644 crates/core/src/launch/window_detect.rs create mode 100644 crates/core/src/lib.rs create mode 100644 crates/core/src/platform/atomic.rs create mode 100644 crates/core/src/platform/data_dir.rs create mode 100644 crates/core/src/platform/dir_migration.rs create mode 100644 crates/core/src/platform/error.rs create mode 100644 crates/core/src/platform/hash.rs create mode 100644 crates/core/src/platform/layout.rs create mode 100644 crates/core/src/platform/linux_caps.rs create mode 100644 crates/core/src/platform/macos_version.rs create mode 100644 crates/core/src/platform/mod.rs create mode 100644 crates/core/src/platform/os_info.rs create mode 100644 crates/core/src/platform/paths.rs create mode 100644 crates/core/src/platform/receipt.rs create mode 100644 crates/core/src/platform/redirect.rs create mode 100644 crates/core/src/platform/theme_probe.rs create mode 100644 crates/core/src/platform/vk_probe.rs create mode 100644 crates/core/src/platform/wallpaper.rs create mode 100644 crates/core/src/platform/wallpaper/io.rs create mode 100644 crates/core/src/platform/wallpaper/linux.rs create mode 100644 crates/core/src/platform/wallpaper/macos.rs create mode 100644 crates/core/src/platform/wallpaper/parse.rs create mode 100644 crates/core/src/platform/wallpaper/windows.rs create mode 100644 crates/core/src/platform/wallpaper/windows/parse.rs create mode 100644 crates/core/src/platform/windows_version.rs create mode 100644 crates/core/src/setting/appearance/mod.rs create mode 100644 crates/core/src/setting/appearance/modes.rs create mode 100644 crates/core/src/setting/appearance/tests.rs create mode 100644 crates/core/src/setting/catalog.rs create mode 100644 crates/core/src/setting/document.rs create mode 100644 crates/core/src/setting/error.rs create mode 100644 crates/core/src/setting/instance_keys.rs create mode 100644 crates/core/src/setting/json_path.rs create mode 100644 crates/core/src/setting/keys.rs create mode 100644 crates/core/src/setting/migrate.rs create mode 100644 crates/core/src/setting/mod.rs create mode 100644 crates/core/src/setting/policy.rs create mode 100644 crates/core/src/setting/save.rs create mode 100644 crates/core/src/setting/save_worker.rs create mode 100644 crates/core/src/setting/schema.rs create mode 100644 crates/core/src/setting/spec.rs create mode 100644 crates/core/src/setting/store.rs create mode 100644 crates/core/tests/auth/auth_failure_journal.rs create mode 100644 crates/core/tests/auth/authlib_api.rs create mode 100644 crates/core/tests/auth/main.rs create mode 100644 crates/core/tests/auth/microsoft_authcode.rs create mode 100644 crates/core/tests/auth/microsoft_diagnostics.rs create mode 100644 crates/core/tests/auth/microsoft_flow.rs create mode 100644 crates/core/tests/auth/microsoft_refresh.rs create mode 100644 crates/core/tests/auth/offline_uuid.rs create mode 100644 crates/core/tests/auth/store_separation.rs create mode 100644 crates/core/tests/auth/support/microsoft.rs create mode 100644 crates/core/tests/auth/support/mod.rs create mode 100644 crates/core/tests/diagnose/collectors_probe.rs create mode 100644 crates/core/tests/diagnose/engine_rank.rs create mode 100644 crates/core/tests/diagnose/hs_err_parse.rs create mode 100644 crates/core/tests/diagnose/loader_reload.rs create mode 100644 crates/core/tests/diagnose/main.rs create mode 100644 crates/core/tests/diagnose/rules_samples.rs create mode 100644 crates/core/tests/download/backoff_test.rs create mode 100644 crates/core/tests/download/cache_test.rs create mode 100644 crates/core/tests/download/chunked_test.rs create mode 100644 crates/core/tests/download/engine_mock_test.rs create mode 100644 crates/core/tests/download/health_test.rs create mode 100644 crates/core/tests/download/mirrors_test.rs create mode 100644 crates/core/tests/download/partfile_test.rs create mode 100644 crates/core/tests/download/region_test.rs create mode 100644 crates/core/tests/download/resume_test.rs create mode 100644 crates/core/tests/download/support/mod.rs create mode 100644 crates/core/tests/game/arguments_rules.rs create mode 100644 crates/core/tests/game/helpers.rs create mode 100644 crates/core/tests/game/inherit_chain.rs create mode 100644 crates/core/tests/game/isolation.rs create mode 100644 crates/core/tests/game/isolation_switch.rs create mode 100644 crates/core/tests/game/java_discover.rs create mode 100644 crates/core/tests/game/java_install.rs create mode 100644 crates/core/tests/game/java_location.rs create mode 100644 crates/core/tests/game/java_mapping.rs create mode 100644 crates/core/tests/game/java_mirrors.rs create mode 100644 crates/core/tests/game/java_vendor_chain.rs create mode 100644 crates/core/tests/game/layout.rs create mode 100644 crates/core/tests/game/main.rs create mode 100644 crates/core/tests/game/manifest_parse.rs create mode 100644 crates/core/tests/game/profiles.rs create mode 100644 crates/core/tests/game/snapshot.rs create mode 100644 crates/core/tests/game/unlisted.rs create mode 100644 crates/core/tests/game/version_list.rs create mode 100644 crates/core/tests/game/vulkan_capability.rs create mode 100644 crates/core/tests/launch/adapter_cases.rs create mode 100644 crates/core/tests/launch/cmdline_snapshot.rs create mode 100644 crates/core/tests/launch/command_builder_cases.rs create mode 100644 crates/core/tests/launch/exit_cases.rs create mode 100644 crates/core/tests/launch/graphics_backend_cases.rs create mode 100644 crates/core/tests/launch/main.rs create mode 100644 crates/core/tests/launch/natives_args_cases.rs create mode 100644 crates/core/tests/launch/natives_cases.rs create mode 100644 crates/core/tests/launch/pipeline_cases.rs create mode 100644 crates/core/tests/launch/prelude.rs create mode 100644 crates/core/tests/launch/process_smoke.rs create mode 100644 crates/core/tests/launch/pump_buffer.rs create mode 100644 crates/core/tests/launch/session_events.rs create mode 100644 crates/core/tests/launch/sink_cases.rs create mode 100644 crates/core/tests/launch/tree_kill_cases.rs create mode 100644 crates/core/tests/platform/linux_caps_cases.rs create mode 100644 crates/core/tests/platform/macos_cases.rs create mode 100644 crates/core/tests/platform/main.rs create mode 100644 crates/core/tests/platform/os_info_cases.rs create mode 100644 crates/core/tests/platform/prelude.rs create mode 100644 crates/core/tests/platform/rules_wiring.rs create mode 100644 crates/core/tests/platform/theme_cases.rs create mode 100644 crates/core/tests/platform/vk_cases.rs create mode 100644 crates/core/tests/platform/windows_version_cases.rs create mode 100644 crates/core/tests/setting/appearance_keys.rs create mode 100644 crates/core/tests/setting/atomic_write.rs create mode 100644 crates/core/tests/setting/common.rs create mode 100644 crates/core/tests/setting/debounce.rs create mode 100644 crates/core/tests/setting/deprecated_keys.rs create mode 100644 crates/core/tests/setting/dir_migration.rs create mode 100644 crates/core/tests/setting/dirs.rs create mode 100644 crates/core/tests/setting/document.rs create mode 100644 crates/core/tests/setting/isolation_keys.rs create mode 100644 crates/core/tests/setting/java_install_keys.rs create mode 100644 crates/core/tests/setting/layout.rs create mode 100644 crates/core/tests/setting/main.rs create mode 100644 crates/core/tests/setting/migration_chain.rs create mode 100644 crates/core/tests/setting/redirect.rs create mode 100644 crates/core/tests/setting/schema_compat.rs create mode 100644 crates/core/tests/setting/spec_ai.rs create mode 100644 crates/core/tests/setting/store.rs create mode 100644 crates/design/Cargo.toml create mode 100644 crates/design/src/color/cam16.rs create mode 100644 crates/design/src/color/critical_planes.rs create mode 100644 crates/design/src/color/hct.rs create mode 100644 crates/design/src/color/hct_solver.rs create mode 100644 crates/design/src/color/mod.rs create mode 100644 crates/design/src/color/palettes.rs create mode 100644 crates/design/src/color/roles.rs create mode 100644 crates/design/src/color/scheme.rs create mode 100644 crates/design/src/color/space.rs create mode 100644 crates/design/src/color/state.rs create mode 100644 crates/design/src/color/tonal.rs create mode 100644 crates/design/src/color/viewing_conditions.rs create mode 100644 crates/design/src/component_map/metrics.rs create mode 100644 crates/design/src/component_map/mod.rs create mode 100644 crates/design/src/component_map/table.rs create mode 100644 crates/design/src/component_map/tests.rs create mode 100644 crates/design/src/elevation.rs create mode 100644 crates/design/src/icons/glyphs.rs create mode 100644 crates/design/src/icons/kinds.rs create mode 100644 crates/design/src/icons/mod.rs create mode 100644 crates/design/src/lib.rs create mode 100644 crates/design/src/motion/mod.rs create mode 100644 crates/design/src/motion/spring.rs create mode 100644 crates/design/src/palette/card.rs create mode 100644 crates/design/src/palette/mod.rs create mode 100644 crates/design/src/palette/quantize.rs create mode 100644 crates/design/src/palette/resolve/mod.rs create mode 100644 crates/design/src/palette/resolve/provenance.rs create mode 100644 crates/design/src/palette/resolve/tests.rs create mode 100644 crates/design/src/palette/score.rs create mode 100644 crates/design/src/palette/seed/mod.rs create mode 100644 crates/design/src/palette/seed/tests.rs create mode 100644 crates/design/src/palette/wcag.rs create mode 100644 crates/design/src/shape.rs create mode 100644 crates/design/src/spacing.rs create mode 100644 crates/design/src/typography/emphasized.rs create mode 100644 crates/design/src/typography/fonts.rs create mode 100644 crates/design/src/typography/fonts/tests.rs create mode 100644 crates/design/src/typography/mod.rs create mode 100644 crates/design/tests/card_neutral.rs create mode 100644 crates/design/tests/card_neutral/common.rs create mode 100644 crates/design/tests/card_neutral/dump.rs create mode 100644 crates/design/tests/contrast_aa.rs create mode 100644 crates/design/tests/official_accent.rs create mode 100644 crates/design/tests/official_baseline.rs create mode 100644 crates/design/tests/skyseed_candidates.rs create mode 100644 crates/design/tests/token_contract.rs create mode 100644 crates/design/tests/token_pins.rs create mode 100644 crates/design/tests/tokext_pins.rs create mode 100644 crates/design/tests/type_scale_pins.rs create mode 100644 crates/i18n/Cargo.toml create mode 100644 crates/i18n/src/bridge.rs create mode 100644 crates/i18n/src/catalog.rs create mode 100644 crates/i18n/src/catalog/account.rs create mode 100644 crates/i18n/src/catalog/agent.rs create mode 100644 crates/i18n/src/catalog/content.rs create mode 100644 crates/i18n/src/catalog/core_text.rs create mode 100644 crates/i18n/src/catalog/download.rs create mode 100644 crates/i18n/src/catalog/font.rs create mode 100644 crates/i18n/src/catalog/general.rs create mode 100644 crates/i18n/src/catalog/golden.rs create mode 100644 crates/i18n/src/catalog/instances.rs create mode 100644 crates/i18n/src/catalog/launch.rs create mode 100644 crates/i18n/src/catalog/loader.rs create mode 100644 crates/i18n/src/catalog/logs.rs create mode 100644 crates/i18n/src/catalog/nav.rs create mode 100644 crates/i18n/src/catalog/settings/ai.rs create mode 100644 crates/i18n/src/catalog/settings/appearance.rs create mode 100644 crates/i18n/src/catalog/settings/download.rs create mode 100644 crates/i18n/src/catalog/settings/general.rs create mode 100644 crates/i18n/src/catalog/settings/java.rs create mode 100644 crates/i18n/src/catalog/settings/mod.rs create mode 100644 crates/i18n/src/catalog/tests.rs create mode 100644 crates/i18n/src/choice.rs create mode 100644 crates/i18n/src/font.rs create mode 100644 crates/i18n/src/lang.rs create mode 100644 crates/i18n/src/lib.rs create mode 100644 crates/palette-extract/Cargo.toml create mode 100644 crates/palette-extract/src/lib.rs create mode 100644 crates/palette-extract/src/tests.rs create mode 100644 crates/presenter/Cargo.toml create mode 100644 crates/presenter/src/agent.rs create mode 100644 crates/presenter/src/agent/mock.rs create mode 100644 crates/presenter/src/agent/rail.rs create mode 100644 crates/presenter/src/agent/tests.rs create mode 100644 crates/presenter/src/agent/tests_red_line.rs create mode 100644 crates/presenter/src/backend.rs create mode 100644 crates/presenter/src/dialogs.rs create mode 100644 crates/presenter/src/dto/accounts.rs create mode 100644 crates/presenter/src/dto/accounts/failure.rs create mode 100644 crates/presenter/src/dto/accounts/kind.rs create mode 100644 crates/presenter/src/dto/accounts/name.rs create mode 100644 crates/presenter/src/dto/accounts/redact.rs create mode 100644 crates/presenter/src/dto/accounts/tests.rs create mode 100644 crates/presenter/src/dto/agent.rs create mode 100644 crates/presenter/src/dto/content.rs create mode 100644 crates/presenter/src/dto/content/tests.rs create mode 100644 crates/presenter/src/dto/events.rs create mode 100644 crates/presenter/src/dto/install.rs create mode 100644 crates/presenter/src/dto/instances.rs create mode 100644 crates/presenter/src/dto/java.rs create mode 100644 crates/presenter/src/dto/logs.rs create mode 100644 crates/presenter/src/dto/mod.rs create mode 100644 crates/presenter/src/dto/notices.rs create mode 100644 crates/presenter/src/dto/pack.rs create mode 100644 crates/presenter/src/dto/pack/conflict.rs create mode 100644 crates/presenter/src/dto/pack/event.rs create mode 100644 crates/presenter/src/dto/pack/export.rs create mode 100644 crates/presenter/src/dto/pack/format.rs create mode 100644 crates/presenter/src/dto/pack/import.rs create mode 100644 crates/presenter/src/dto/settings.rs create mode 100644 crates/presenter/src/dto/versions.rs create mode 100644 crates/presenter/src/host/accounts.rs create mode 100644 crates/presenter/src/host/accounts/authlib.rs create mode 100644 crates/presenter/src/host/accounts/authlib/util.rs create mode 100644 crates/presenter/src/host/accounts/failure.rs create mode 100644 crates/presenter/src/host/accounts/refresh.rs create mode 100644 crates/presenter/src/host/addon.rs create mode 100644 crates/presenter/src/host/addon/http.rs create mode 100644 crates/presenter/src/host/addon/install.rs create mode 100644 crates/presenter/src/host/addon/pack.rs create mode 100644 crates/presenter/src/host/addon/pack/convert.rs create mode 100644 crates/presenter/src/host/addon/pack/diagnose.rs create mode 100644 crates/presenter/src/host/addon/pack/export.rs create mode 100644 crates/presenter/src/host/addon/pack/import.rs create mode 100644 crates/presenter/src/host/addon/pack/tests.rs create mode 100644 crates/presenter/src/host/addon/pack/tests/harness.rs create mode 100644 crates/presenter/src/host/addon/sources.rs create mode 100644 crates/presenter/src/host/addon/tests.rs create mode 100644 crates/presenter/src/host/cancel_tests.rs create mode 100644 crates/presenter/src/host/dispatch.rs create mode 100644 crates/presenter/src/host/engine.rs create mode 100644 crates/presenter/src/host/env.rs create mode 100644 crates/presenter/src/host/game.rs create mode 100644 crates/presenter/src/host/handle.rs create mode 100644 crates/presenter/src/host/identity.rs create mode 100644 crates/presenter/src/host/install.rs create mode 100644 crates/presenter/src/host/install/routes.rs create mode 100644 crates/presenter/src/host/install_journal.rs create mode 100644 crates/presenter/src/host/install_processors.rs create mode 100644 crates/presenter/src/host/install_processors_fixture.rs create mode 100644 crates/presenter/src/host/install_processors_tests.rs create mode 100644 crates/presenter/src/host/install_tests.rs create mode 100644 crates/presenter/src/host/java.rs create mode 100644 crates/presenter/src/host/job.rs create mode 100644 crates/presenter/src/host/launch.rs create mode 100644 crates/presenter/src/host/launch_state_tests.rs create mode 100644 crates/presenter/src/host/loader_versions.rs create mode 100644 crates/presenter/src/host/logs.rs create mode 100644 crates/presenter/src/host/logs_tests.rs create mode 100644 crates/presenter/src/host/meter.rs create mode 100644 crates/presenter/src/host/mod.rs create mode 100644 crates/presenter/src/host/opener.rs create mode 100644 crates/presenter/src/host/settings.rs create mode 100644 crates/presenter/src/host/settings_tests.rs create mode 100644 crates/presenter/src/host/versions.rs create mode 100644 crates/presenter/src/lib.rs create mode 100644 crates/presenter/src/mock.rs create mode 100644 crates/presenter/src/mock/accounts.rs create mode 100644 crates/presenter/src/mock/instances.rs create mode 100644 crates/presenter/src/mock_data.rs create mode 100644 crates/presenter/src/prefs.rs create mode 100644 crates/presenter/src/prefs/tests.rs create mode 100644 crates/presenter/src/router.rs create mode 100644 crates/presenter/src/settings_bridge.rs create mode 100644 crates/presenter/src/settings_bridge_lang.rs create mode 100644 crates/presenter/src/state.rs create mode 100644 crates/presenter/src/state/accounts.rs create mode 100644 crates/presenter/src/state/content.rs create mode 100644 crates/presenter/src/state/content_tests.rs create mode 100644 crates/presenter/src/state/live.rs create mode 100644 crates/presenter/src/state/tiles.rs create mode 100644 crates/presenter/src/state_tests.rs create mode 100644 crates/presenter/src/theme.rs create mode 100644 crates/presenter/src/toast.rs create mode 100644 crates/presenter/src/wizard.rs create mode 100644 deny.toml create mode 100644 packaging/README.md create mode 100644 packaging/check_screenshot.py create mode 100644 packaging/ci-runtime-smoke.md create mode 100644 packaging/linux-smoke-docker.sh create mode 100644 packaging/make_artifacts.py create mode 100644 packaging/release-notes.md create mode 100644 rust-toolchain.toml diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..f3f1a1b --- /dev/null +++ b/.gitattributes @@ -0,0 +1,34 @@ +# 换行策略：仓库内一律 LF（rustfmt 设 newline_style = "Unix"，CI 在 Linux 上跑 fmt --check）。 +# eol=lf 对工作区同样生效 —— Windows 克隆也不会被转换成 CRLF，避免「本地 fmt 过、CI fmt 挂」。 +* text=auto eol=lf + +# 明确为文本（显式列出，防止被误判成二进制） +*.rs text eol=lf +*.toml text eol=lf +*.md text eol=lf +*.slint text eol=lf +*.yml text eol=lf +*.yaml text eol=lf +*.json text eol=lf +Cargo.lock text eol=lf + +# 二进制：不做换行转换、不做文本 diff +*.png binary +*.ico binary +*.icns binary +*.jpg binary +*.jpeg binary +*.gif binary +*.webp binary +*.ttf binary +*.otf binary +*.woff binary +*.woff2 binary +*.zip binary +*.7z binary +*.gz binary +*.tar binary +*.exe binary +*.dll binary +*.lib binary +*.pdb binary diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..d335915 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,190 @@ +name: CI + +# 主干门禁：fmt / clippy / test / build 双平台矩阵。 +# 架构守门（core 零 UI、文件 ≤400 行、依赖许可）见 guards.yml。 +# 平台基线 Win10+（标准工具链产物），平台矩阵见 AGENTS.md §7。 +# +# M118（D26）：根 Cargo.toml 已 `exclude = ["crates/app"]`（Slint 退役树，源码原样保留）。 +# 所以本文件里所有 `--workspace` 都**不再**覆盖 `unlucky-app`：CI 不再编 slint 1.18 + usvg 0.48 +# 那棵依赖树（本机单路冷编 ≈14 分钟；并行超配时表现为 `rustc` 退 1 且零诊断， +# 见 DevDocs/00-踩坑记录-p2.md T7）。历史实现只作源码参考，**没有构建方式**（见 README： +# 它的 manifest 整份是 workspace 继承写法，离开 workspace 后连解析都过不了）。 + +on: + push: + branches: [main] + pull_request: + workflow_dispatch: + +env: + CARGO_TERM_COLOR: always + RUST_BACKTRACE: 1 + +concurrency: + group: ci-${{ github.ref }} + cancel-in-progress: true + +jobs: + fmt: + name: fmt (rustfmt --check) + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: dtolnay/rust-toolchain@stable + with: + components: rustfmt + - run: cargo fmt --all --check + + clippy: + name: clippy (${{ matrix.os }}) + strategy: + fail-fast: false + matrix: + os: [windows-latest, ubuntu-latest] + runs-on: ${{ matrix.os }} + steps: + - uses: actions/checkout@v4 + - name: Linux 图形栈构建依赖（winit / wgpu 编译期需要） + if: runner.os == 'Linux' + run: | + sudo apt-get update + sudo apt-get install -y --no-install-recommends \ + libxkbcommon-dev libfontconfig1-dev libgl1-mesa-dev libegl1-mesa-dev \ + libwayland-dev libxcb1-dev + - uses: dtolnay/rust-toolchain@stable + with: + components: clippy + - uses: Swatinem/rust-cache@v2 + # `--workspace` 现在是 8 个 crate，不含 `unlucky-app`（M118 的 workspace exclude）， + # 所以这条命令不会拉起 slint / usvg / i-slint-*。 + - run: cargo clippy --workspace --all-targets -- -D warnings + + test: + name: test (${{ matrix.os }}) + strategy: + fail-fast: false + matrix: + os: [windows-latest, ubuntu-latest] + runs-on: ${{ matrix.os }} + steps: + - uses: actions/checkout@v4 + - name: Linux 图形栈构建依赖 + if: runner.os == 'Linux' + run: | + sudo apt-get update + sudo apt-get install -y --no-install-recommends \ + libxkbcommon-dev libfontconfig1-dev libgl1-mesa-dev libegl1-mesa-dev \ + libwayland-dev libxcb1-dev + - uses: dtolnay/rust-toolchain@stable + - uses: Swatinem/rust-cache@v2 + # 同 clippy：`--workspace` 不含 `unlucky-app`（M118），Slint 退役树不再被 `--all-targets` 拉起。 + # 也因此**不要**再写 `--exclude unlucky-app`：它已不是成员，那面旗子只会打一条 + # `excluded package(s) … not found in workspace` 的警告然后空转（实测 exit 0，不报错）。 + - run: cargo test --workspace --all-targets + + build: + name: build release (${{ matrix.os }}) + strategy: + fail-fast: false + matrix: + os: [windows-latest, ubuntu-latest] + runs-on: ${{ matrix.os }} + steps: + - uses: actions/checkout@v4 + - name: Linux 图形栈构建依赖 + if: runner.os == 'Linux' + run: | + sudo apt-get update + sudo apt-get install -y --no-install-recommends \ + libxkbcommon-dev libfontconfig1-dev libgl1-mesa-dev libegl1-mesa-dev \ + libwayland-dev libxcb1-dev + - uses: dtolnay/rust-toolchain@stable + - uses: Swatinem/rust-cache@v2 + # 同上：`--workspace` 不含 `unlucky-app`（M118）。被摘掉的正是 release 档 + # （lto=fat + codegen-units=1）最贵的那棵 slint + usvg 树。 + - run: cargo build --workspace --release + + # 运行时冒烟（M62）：Linux 上**真渲染一帧**，补上「能编译 ≠ 能跑」的空白。 + # 上面四个 job 都只证明代码编得过、测得过，从不创建真实图形窗口；本 job 在 Xvfb 虚拟显示里 + # 启动 GUI 进程，让软件渲染器把当前场景渲进内存像素缓冲并编码成 PNG，再对**像素本身** + # 断言（不是只看退出码：窗口起来了但一帧空白同样是「退出码 0」）。 + # 诚实边界：证明「Linux 上真能跑出非空白的一帧」，**不**证明视觉正确——视觉靠人眼看 artifact。 + # M118（D26）：这里原本绑死 Slint 的 `Window::take_snapshot`，打的是 Slint 版 bin + # `unlucky-launcher`；`crates/app` 退出 workspace 后那个 bin 不再存在，改用 iced 版 + # `unlucky-launcher-iced` 自带的 `--screenshot` 通道（`crates/app-iced/src/shot/`）。 + # 命令行参数刻意不动：iced 的 `cli.rs` 就是照 Slint 版的口径写的，`--data-dir` 也仍被接受（忽略）。 + runtime-smoke: + name: runtime smoke (ubuntu x64, xvfb) + runs-on: ubuntu-latest + timeout-minutes: 30 + steps: + - uses: actions/checkout@v4 + - name: 无头 X 与图形栈依赖（xvfb + 软渲染 + 字体） + run: | + sudo apt-get update + sudo apt-get install -y --no-install-recommends \ + xvfb xauth \ + libxkbcommon-dev libxkbcommon-x11-0 libfontconfig1-dev \ + libgl1-mesa-dev libegl1-mesa-dev libwayland-dev libxcb1-dev \ + libx11-6 libxcursor1 libxrandr2 libxi6 \ + fonts-dejavu-core fonts-liberation2 + - uses: dtolnay/rust-toolchain@stable + - uses: Swatinem/rust-cache@v2 + # 用 debug 而不是 release：本 job 验的是「运行时渲染通路能通」，不是优化后二进制的行为； + # release 的 lto="fat" + codegen-units=1 会把这一步拖到十几分钟却不带来额外证据。 + # M118：bin 从 Slint 版 `unlucky-launcher` 换成 iced 版（见上方 job 注释）。 + - run: cargo build --bin unlucky-launcher-iced --locked + - name: 在 Xvfb 里跑一帧并截图（退出码非 0 即失败） + run: | + set -o pipefail # 当前没有管道（死行），保留是为将来加管道时先有失败传播 + mkdir -p "$RUNNER_TEMP/smoke/data" + xvfb-run -a --server-args="-screen 0 1280x1024x24" \ + target/debug/unlucky-launcher-iced --software-renderer \ + --screenshot "$RUNNER_TEMP/smoke/runtime-smoke.png" \ + --data-dir "$RUNNER_TEMP/smoke/data" + - name: 断言 PNG 存在且非空白（尺寸 / 唯一色数 / 亮度σ / 强边缘占比） + run: python3 packaging/check_screenshot.py "$RUNNER_TEMP/smoke/runtime-smoke.png" --json + - name: 上传截图与数据目录（失败也传，便于复盘） + if: always() + uses: actions/upload-artifact@v4 + with: + name: runtime-smoke-screenshot + path: ${{ runner.temp }}/smoke/ + if-no-files-found: warn + + # macOS 槽位探针（M62）：**默认不在 PR 上跑**，只有手动 dispatch 才触发。 + # 之所以是探针而不是常驻槽位：官方 macOS runner 处于 LaunchDaemon 上下文，没有登录的 + # WindowServer 会话，GUI 的 winit backend 创建窗口大概率直接失败；而 worker 禁 push， + # 本机也没有 macOS，这条路径**尚无任何实测证据**——不拿未验证的 job 卡住主干门禁。 + # 首跑结论决定去留：绿 → 去掉 if/continue-on-error 升为常驻槽位；红 → 按 D26 归入 iced + # 重写后再规划，并把错误原文贴进 progress 文档（不静默删 job、不吞失败原因）。 + # M118：bin 与 Linux 那条一样，从 Slint 版换成 iced 版（`unlucky-launcher-iced`）。 + runtime-smoke-macos: + name: runtime smoke (macos arm64, probe) + if: github.event_name == 'workflow_dispatch' + runs-on: macos-latest + timeout-minutes: 30 + # 探针阶段保留证据但不算流水线结论：log/artifact 里失败原因照常可见， + # 解除条件 = 该槽位在真实 runner 上首跑通过并把本行与上面那条 if 一起删掉。 + continue-on-error: true + steps: + - uses: actions/checkout@v4 + - uses: dtolnay/rust-toolchain@stable + - uses: Swatinem/rust-cache@v2 + - run: cargo build --bin unlucky-launcher-iced --locked + - name: 尝试截图（macOS 没有 X 服务器，直接跑；失败即为结论） + run: | + set -o pipefail # 当前没有管道（死行），保留是为将来加管道时先有失败传播 + mkdir -p "$RUNNER_TEMP/smoke/data" + target/debug/unlucky-launcher-iced --software-renderer \ + --screenshot "$RUNNER_TEMP/smoke/runtime-smoke.png" \ + --data-dir "$RUNNER_TEMP/smoke/data" + - name: 断言 PNG 存在且非空白 + run: python3 packaging/check_screenshot.py "$RUNNER_TEMP/smoke/runtime-smoke.png" --json + - name: 上传截图与数据目录（失败也传，便于复盘） + if: always() + uses: actions/upload-artifact@v4 + with: + name: runtime-smoke-screenshot-macos + path: ${{ runner.temp }}/smoke/ + if-no-files-found: warn diff --git a/.github/workflows/guards.yml b/.github/workflows/guards.yml new file mode 100644 index 0000000..767f8be --- /dev/null +++ b/.github/workflows/guards.yml @@ -0,0 +1,381 @@ +name: Guards + +# 架构与合规守门（与 fmt/clippy 同级，不允许 continue-on-error）： +# 1. core-no-ui —— crates/core 零 UI 依赖（D3 铁律），依赖表 + cargo tree 双查 +# 2. presenter-no-ui —— crates/presenter 零 UI 依赖（D26 / M85）：Slint 版与 iced 版共用的宿主层 +# 3. design-zero-dep —— crates/design 零第三方依赖（M61 / M87）：依赖表（含 dev/build）必须为空 + 依赖树只允许出现自身 +# 4. file-size —— 全仓代码/文档单文件 ≤400 行（用户硬约束） +# 5. licenses —— cargo-deny：许可证白名单 + GPL 依赖拦截 + 供应链来源校验 +# 6. unsafe-scope —— 全仓 `allow(unsafe_code)` 的文件集合必须恰好只有一个（D36 / M91） +# +# M118（D26）：根 Cargo.toml 已 `exclude = ["crates/app"]`（Slint 退役树）。逐条核对过本文件， +# **没有**任何一条守卫以 `--workspace` 为前提，所以排除不会让它们空转： +# ① core-no-ui / presenter-no-ui / design-zero-dep —— 「manifest 文本 + `cargo tree -p `」 +# 口径，被守的 crate 仍是 workspace 成员，依赖树与排除前逐行一致； +# ② file-size / unsafe-scope —— 走 `git ls-files` / `git grep`，与构建图无关，**仍然覆盖 +# `crates/app/**`**（源码还在仓库里，就还得守它的行数与 unsafe 落点）； +# ③ licenses —— 唯一走 workspace 依赖图的守卫。排除后 Slint 那棵树不再进图（实测 `cargo deny +# list` 里 `slint*` / `i-slint-*` 为 0 个），这与「不再随任何产物发布」一致；代价是它的许可证 +# 不再被本门禁审 —— 真要重新纳入发布，得先把它加回 workspace，门禁随之恢复。 + +on: + push: + branches: [main] + pull_request: + workflow_dispatch: + +env: + CARGO_TERM_COLOR: always + +jobs: + core-no-ui: + name: core 零 UI 守门 + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: dtolnay/rust-toolchain@stable + - name: 依赖表直查（crates/core/Cargo.toml 不得出现 UI 框架） + run: | + set -uo pipefail + forbidden='slint|egui|eframe|iced|winit|gtk|javafx|tauri|fltk|druid|relm' + # 只看非注释行：manifest 里说明「不许出现 slint」的注释本身不该触发守门 + if grep -vE '^[[:space:]]*#' crates/core/Cargo.toml | grep -nEi "$forbidden"; then + echo "::error file=crates/core/Cargo.toml::core 不得依赖 UI 框架（见 AGENTS.md 硬约束）" + exit 1 + fi + echo "OK: crates/core/Cargo.toml 无 UI 依赖" + - name: 依赖树泄漏检查（cargo tree -p unlucky-core，排除自身行） + run: | + set -uo pipefail + forbidden='slint|egui|eframe|iced|winit|gtk|javafx|tauri|fltk|druid|relm' + tree=$(cargo tree -p unlucky-core --edges normal --prefix none) + echo "$tree" + if echo "$tree" | grep -vE '^unlucky-core v' | grep -qiE "$forbidden"; then + echo "::error::core 的依赖树出现 UI 框架 —— 传递依赖也不允许" + exit 1 + fi + echo "OK: unlucky-core 依赖树零 UI" + + # presenter 是 Slint 版（crates/app）与 iced 版（crates/app-iced）共用的唯一业务层（D26）。 + # 一旦 slint/iced/winit 被拉进来，分层就废了，而编译与单测仍会全绿 —— 所以必须由 CI 守。 + # M118 之后 Slint 版已被 workspace `exclude`，但本条**照样守得住**：它查的是 presenter 自己的 + # manifest 与 `cargo tree -p unlucky-presenter`，与「谁在消费 presenter」无关；依赖树里一旦出现 + # slint/iced/winit 仍会当场红。名单里的 slint 继续留着，就是为了防「把 UI 依赖偷偷塞进宿主层」。 + # 与 core-no-ui 同样是「依赖表 + cargo tree」双查，名单保持一致；脚本刻意复制而非抽公共脚本， + # 理由是 CI 守门脚本自身挂掉的排查成本远高于这几行重复。 + presenter-no-ui: + name: presenter 零 UI 守门 + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: dtolnay/rust-toolchain@stable + - name: 依赖表直查（crates/presenter/Cargo.toml 的依赖表不得出现 UI 框架） + run: | + set -uo pipefail + forbidden='slint|egui|eframe|iced|winit|gtk|javafx|tauri|fltk|druid|relm' + # 与 core-no-ui 的整文件 grep 不同：本 crate 的 description 合法地写着 + # 「Slint 版与 iced 版共用」，整文件 grep 会把它当越线。所以先按表头切出依赖表 + # （含 target.*.dependencies 与 dev/build 表），再去掉注释行，只查键名。 + # 子表写法 `[dependencies.slint]` / `[target.'cfg(windows)'.dependencies.slint]` + # 是合法的等长写法，且表头本身带着包名，所以表头也要一并落进检查范围—— + # 否则「子表 + optional + 非默认 feature」这种组合能同时骗过依赖表与 cargo tree。 + awk ' + /^[[:space:]]*\[/ { + in_deps = ($0 ~ /^[[:space:]]*\[(target\..*\.)?(dependencies|dev-dependencies|build-dependencies)(\.[^]]*)?\][[:space:]]*$/) + if (in_deps && $0 ~ /\.[^]]*\]/) printf "%d:%s\n", NR, $0 + next + } + in_deps && !/^[[:space:]]*#/ && !/^[[:space:]]*$/ { printf "%d:%s\n", NR, $0 } + ' crates/presenter/Cargo.toml > /tmp/presenter-deps.txt + cat /tmp/presenter-deps.txt + if grep -iE "$forbidden" /tmp/presenter-deps.txt; then + echo "::error file=crates/presenter/Cargo.toml::presenter 不得依赖 UI 框架（D26）。窗口创建 / 渲染 / 图片解码属于 app 与 app-iced 侧；需要跨前端共用的类型请放进 presenter 的 dto。" + exit 1 + fi + echo "OK: crates/presenter/Cargo.toml 依赖表无 UI 依赖" + - name: 依赖树泄漏检查（cargo tree -p unlucky-presenter，排除自身行） + run: | + set -uo pipefail + forbidden='slint|egui|eframe|iced|winit|gtk|javafx|tauri|fltk|druid|relm' + # 注意：cargo tree 命中 UI 框架时**退出码仍是 0**，所以只能抓输出再判断。 + if ! tree=$(cargo tree -p unlucky-presenter --edges normal --prefix none); then + echo "::error::cargo tree -p unlucky-presenter 执行失败 —— crate 是否仍叫 unlucky-presenter？" + exit 1 + fi + echo "$tree" + hits=$(printf '%s\n' "$tree" | grep -vE '^unlucky-presenter v' | grep -iE "$forbidden") + if [ -n "$hits" ]; then + echo "::error::presenter 的依赖树出现 UI 框架（传递依赖也不允许），本次命中：" + printf '%s\n' "$hits" | sed 's/^/ - /' + echo "::error::presenter 是 Slint 版与 iced 版共用的宿主层：把窗口 / 渲染 / 图片解码留在 app 侧，presenter 只持有与框架无关的 DTO、状态 reducer 与 host 装配。" + exit 1 + fi + echo "OK: unlucky-presenter 依赖树零 UI" + + # unlucky-design 是「纯数据 + 纯函数、零第三方依赖」的设计令牌层，这是 README 明写的卖点 + # （连 serde 都不加），但目前只靠人肉守。零依赖的判据比 UI 名单更硬：依赖树只允许有自己一行。 + # 注意 `cargo tree --edges normal` 看不到 dev/build 依赖，所以另设一步按表头切依赖表逐个查空。 + design-zero-dep: + name: design 零第三方依赖守门 + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: dtolnay/rust-toolchain@stable + - name: 依赖表必须为空（dependencies / dev / build 表一律不许有键，含子表写法） + run: | + set -uo pipefail + # design 承诺的是「零第三方依赖」，不分 normal / dev / build —— 而 cargo tree + # --edges normal 对 dev/build 是瞎的。所以先按表头切出全部依赖表（含 + # `[dependencies.serde]` 这类子表写法，表头本身携带包名），再看是否为空。 + awk ' + /^[[:space:]]*\[/ { + in_deps = ($0 ~ /^[[:space:]]*\[(target\..*\.)?(dependencies|dev-dependencies|build-dependencies)(\.[^]]*)?\][[:space:]]*$/) + if (in_deps && $0 ~ /\.[^]]*\]/) printf "%d:%s\n", NR, $0 + next + } + in_deps && !/^[[:space:]]*#/ && !/^[[:space:]]*$/ { printf "%d:%s\n", NR, $0 } + ' crates/design/Cargo.toml > /tmp/design-deps.txt + if [ -s /tmp/design-deps.txt ]; then + cat /tmp/design-deps.txt + echo "::error file=crates/design/Cargo.toml::unlucky-design 的依赖表必须为空（normal / dev / build 都算），本次命中：" + sed 's/^/ - /' /tmp/design-deps.txt + echo "::error::design 是纯数据 + 纯函数的设计令牌，README 对外承诺零第三方依赖（连 serde 都不加）：色彩 / 排版 / 形状 / 高程 / 动效请不要引入任何 crate，测试与构建辅助依赖同样不许加。序列化与运行时能力放到消费方（app / app-iced / presenter）。" + exit 1 + fi + echo "OK: crates/design/Cargo.toml 依赖表全空（含 dev / build）" + - name: 依赖树只允许出现自身（cargo tree -p unlucky-design --edges normal） + run: | + set -uo pipefail + if ! tree=$(cargo tree -p unlucky-design --edges normal --prefix none); then + echo "::error::cargo tree -p unlucky-design 执行失败 —— crate 是否仍叫 unlucky-design？" + exit 1 + fi + echo "$tree" + # 空行不算，剩下的每一行都必须是自己：正常时整个输出只有一行 + # `unlucky-design v0.1.0 (/path/to/crates/design)`。 + lines=$(printf '%s\n' "$tree" | grep -cE '[^[:space:]]' || true) + others=$(printf '%s\n' "$tree" | grep -vE '^[[:space:]]*$' | grep -vE '^unlucky-design v' || true) + if [ -n "$others" ] || [ "$lines" -ne 1 ]; then + echo "::error file=crates/design/Cargo.toml::unlucky-design 必须零第三方依赖，本应只有自身一行，实际 $lines 行；越线的包：" + printf '%s\n' "$others" | sed 's/^/ - /' + echo "::error::design 是纯数据 + 纯函数的设计令牌：色彩 / 排版 / 形状 / 高程 / 动效请不要引入 serde、rand、once_cell 等任何 crate。序列化与运行时能力放到消费方（app / app-iced / presenter）。" + exit 1 + fi + echo "OK: unlucky-design 依赖树只有自身，零第三方依赖" + + # D36 定案：整窗 α 是全仓**唯一**需要 `unsafe` 的能力（Win32 的 + # `SetLayeredWindowAttributes` 没有安全替代），落点收在一个文件里。 + # 判据必须是**集合相等**而不是「黑名单命中」： + # - 新增第二个显式放行 unsafe 的文件 → 红（黑名单写法在这里会假绿）； + # - 落点文件把放行删掉 / 改名 / 搬走 → 红（否则门禁守着一条已经不存在的路径）； + # - 多行属性、同行合并属性、多行 `cfg_attr`、`expect(unsafe_code)` 都已覆盖 + # （r2 前的行级正则对前两种会假绿，当时只能靠 ci.yml 的 fmt job 兜底；r3 起由词法器直接抓）。 + unsafe-scope: + name: unsafe 落点守门（集合必须恰好一个文件） + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: 全仓显式放行 unsafe 的文件集合 == 唯一落点 + run: | + set -uo pipefail + EXPECTED='crates/app-iced/src/platform/win32/transparency.rs' + # 扫描口径（M91 r3）：一个小词法器，而不是正则。 + # + # 为什么必须用词法器：r2 的写法是「按全文方括号净深度合并续行」，但 Rust 里 + # `['[', '(']`、`"[2"`、`starts_with("[2")` 这类**不配对括号字面量**会让深度永久跑偏， + # 于是该文件后面的一切（包括一个真的 `#[allow(unsafe_code)]`）都再也不会被扫到—— + # 实测本仓 601 个文件里有 10 个扫到 EOF 仍非 0，`gate.rs` 就是其中之一（r3 复审实证： + # 在它尾部加作用域 allow，r2 门禁 exit 0 假绿）。 + # 现在的做法：逐字符状态机（普通 / 行注释 / 块注释（可嵌套）/ 字符串 / raw 字符串 / + # 字符字面量），只在「普通态」里认 `#` 或 `#!` 紧跟 `[` 的属性起点，然后只在这一个 + # 属性内部累计到它的 `]` 配平——数组字面量跨行不再参与合并，也就不会带偏。 + # + # 放行的两种拼法都算：`allow(...)` 与 `expect(...)`。`expect(unsafe_code)` 同样会 + # 放行 unsafe 代码（rustc 实测：`#![expect(unsafe_code)]` + `pub unsafe fn f() {}` 在 + # `-D unsafe_code` 下编译通过），所以它必须被同一条判据抓住，不能只认 allow。 + # + # 仍然抓不住的（已知边界，别当全覆盖）： + # - 落点文件**内部**多开别的 unsafe 能力（本门禁只看「有没有放行属性」，不看 unsafe 块个数）； + # - **在别处定义、这里只调用**的宏展开出来的 allow：宏体里直接写出的属性在源码文本里， + # 会被扫到；但「宏定义在别的文件、调用点展开出 allow」时，本文件源码里没有那个属性； + # - 注释（行注释/块注释）与字符串（普通/raw）里的属性文本**刻意不算**：它们不构成放行； + # 代价是「真把 allow 写进字符串」这种写法不会被当作落点（它也确实不放行任何代码）； + # - manifest 侧 `[lints.rust] unsafe_code = "allow"`：本门禁只扫 `*.rs`，看不见 Cargo.toml； + # + # r4 回归用例（属性内的 raw string / 字符字面量曾经是盲区；现在两处共用 step()， + # 它们不再是边界，但下面五条必须一直保持红/绿正确 —— 改这段词法器前先跑它们）： + # 红 #[doc = r#"a "b"#] 后跟真 allow + # 红 #[cfg_attr(docsrs, doc = r##"a " b "##)] 后跟真 allow + # 红 #[cfg_attr(docsrs, my_macro(39 as char))] 一类含字符字面量/转义的属性后跟真 allow + # 具体形态：#![cfg_attr(docsrs, my_macro('\''))] 后跟真 allow + # 红 以上三者的 CRLF 版本 + # 绿 #[doc = r#"x" allow(unsafe_code) is banned "y"#]（纯文档，不得误报） + scan() { + awk -v path="$1" ' + # ---- 唯一的状态机：主循环与属性内**共用**同一个 step() ---- + # 为什么必须复用：r2 是「属性外一套状态机、属性内另写一套」，两套各自演进， + # r3 的属性内就只剩「遇 " 跳到下一个 "」，于是 raw string / 字符字面量在属性内 + # 完全不认识 —— `#[doc = r#"a "b"#]` 之后的一切对门禁失明（假绿）， + # `#[doc = r#"x" allow(unsafe_code) "y"#]` 这种纯文档被误报（误红）。 + # 现在两处只认这一个 step()，属性解析只多一层「[ ] 深度决定何时离开属性」。 + # + # 状态：0 普通 / 1 行注释 / 2 块注释（可嵌套）/ 3 字符串 / 4 raw 字符串 / 5 字符字面量。 + # 返回值 = 本次消费到的位置（`//`、`/*`、`r#"`、raw 收尾会一次吃掉多个字符）； + # g_plain=1 表示该位置处在「普通态代码」里（注释/字符串内容一律 0， + # 所以它们既不会被当成属性、也不会参与属性内的 [ ] 计数与文本匹配）。 + function step(s, n, i, c, nx, j, h, ok) { + c = substr(s, i, 1) + g_plain = 0 + if (g_state == 1) { if (c == "\n") g_state = 0; return i } + if (g_state == 2) { + if (c == "/" && substr(s, i + 1, 1) == "*") { g_depth++; return i + 1 } + if (c == "*" && substr(s, i + 1, 1) == "/") { g_depth--; if (g_depth <= 0) g_state = 0; return i + 1 } + return i + } + if (g_state == 3) { + if (c == "\\") return i + 1 + if (c == "\"" || c == "\n") g_state = 0 + return i + } + if (g_state == 4) { + if (c == "\"") { + ok = 1 + for (j = 1; j <= g_hashes; j++) if (substr(s, i + j, 1) != "#") ok = 0 + if (ok) { g_state = 0; return i + g_hashes } + } + return i + } + if (g_state == 5) { + if (c == "\\") return i + 1 + if (c == g_q || c == "\n") g_state = 0 + return i + } + if (c == "/" && substr(s, i + 1, 1) == "/") { g_state = 1; return i + 1 } + if (c == "/" && substr(s, i + 1, 1) == "*") { g_state = 2; g_depth = 1; return i + 1 } + if (c == "\"") { g_state = 3; return i } + if (c == g_q) { + nx = substr(s, i + 1, 1) + if (nx == "\\" || substr(s, i + 2, 1) == g_q) { g_state = 5; return i } + g_plain = 1 + return i + } + if (c == "r" || c == "b") { + j = i + 1 + if (c == "b") { + if (substr(s, j, 1) == "\"") { g_state = 3; return j } + if (substr(s, j, 1) == g_q) { g_state = 5; return j } + if (substr(s, j, 1) != "r") { g_plain = 1; return i } + j++ + } + h = 0 + while (substr(s, j, 1) == "#") { h++; j++ } + if (substr(s, j, 1) == "\"") { g_hashes = h; g_state = 4; return j } + g_plain = 1 + return i + } + g_plain = 1 + return i + } + function lex( s, line, n, i, j, k, ch, adepth, attr) { + s = "" + while ((getline line < path) > 0) s = s line "\n" + close(path) + n = length(s) + g_state = 0; g_depth = 0; g_hashes = 0; g_found = 0 + for (i = 1; i <= n; i++) { + i = step(s, n, i) + if (!g_plain || substr(s, i, 1) != "#") continue + j = i + 1 + if (substr(s, j, 1) == "!") j++ + if (substr(s, j, 1) != "[") continue + # 属性：**复用 step()**，只多一层「[ ] 深度决定何时离开属性」。 + # 属性里的字符串 / raw 字符串 / 字符字面量因此与属性外同一套识别。 + attr = ""; adepth = 0; k = j + while (k <= n) { + k = step(s, n, k) + if (g_plain) { + ch = substr(s, k, 1) + if (ch == "[") adepth++ + else if (ch == "]") adepth-- + attr = attr ch + if (adepth <= 0) break + } + k++ + } + if (attr ~ /(allow|expect)\([^]]*unsafe_code/) g_found = 1 + i = k + } + return g_found + } + BEGIN { g_q = "\047"; g_found = 0; exit(lex() ? 0 : 1) } + ' + } + # 只对「文本里出现过 unsafe_code」的文件跑词法器（标识符不可能被空白拆开， + # 所以这个预筛不会漏）。601 个文件 → 个位数个候选，整个 job 约 2 秒。 + actual=$(git grep -l 'unsafe_code' -- '*.rs' 2>/dev/null | LC_ALL=C sort | while IFS= read -r f; do + if scan "$f"; then printf '%s\n' "$f"; fi + done | LC_ALL=C sort) + echo "期望（恰好这一个）：$EXPECTED" + echo "实际扫到的集合：" + if [ -n "$actual" ]; then printf '%s\n' "$actual" | sed 's/^/ - /'; else echo " （空）"; fi + if [ "$actual" != "$EXPECTED" ]; then + extra=$(printf '%s\n' "$actual" | grep -vxF "$EXPECTED" || true) + if [ -n "$extra" ]; then + echo "::error::多出来的 unsafe 落点（D36 只允许一个）：" + printf '%s\n' "$extra" | sed 's/^/ - /' + fi + if ! printf '%s\n' "$actual" | grep -qxF "$EXPECTED"; then + echo "::error file=$EXPECTED::这个文件里没有显式放行 unsafe（allow / expect(unsafe_code)）—— 落点被搬走/改名/删了放行？守门路径已失效。" + fi + echo "::error::整窗 α 的 FFI 只允许住在 $EXPECTED（D36）。需要新的 unsafe 能力请先立 mission：改这条守门 + 更新 D36 的定案，不要顺手放行。" + exit 1 + fi + echo "OK: 全仓显式放行 unsafe 的文件恰好只有 $EXPECTED" + + file-size: + name: 文件行数 ≤400 守门 + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: 检查单文件行数 + run: | + set -uo pipefail + LIMIT=400 + failed=0 + while IFS= read -r f; do + case "$f" in + LICENSE|*/LICENSE|LICENSE-*|*/LICENSE-*) continue ;; + CHANGELOG*|*/CHANGELOG*) continue ;; + # README 是「对外介绍」，不是可拆分的模块：拆成多份反而更难读，用户令 + # （2026-11-05）明确「不用 400 行红线压它，但要保证介绍不臃肿、逻辑完备」。 + # 只豁免仓库根的 README*.md；docs/ 下的长文仍按模块拆分。 + README.md|README.*.md) continue ;; + esac + n=$(wc -l < "$f") + if [ "$n" -gt "$LIMIT" ]; then + echo "::error file=$f::$f 有 $n 行，超过 $LIMIT 行上限，请按模块拆分" + failed=$((failed + 1)) + fi + # 覆盖范围含脚本（*.py/*.sh）：packaging/ 下的构建辅助脚本同样受 400 行约束； + # Cargo.lock 等机器生成文件刻意不在列（否则一生成就超限） + done < <(git ls-files '*.rs' '*.md' '*.slint' '*.yml' '*.yaml' '*.toml' '*.json' '*.py' '*.sh') + if [ "$failed" -ne 0 ]; then + echo "共 $failed 个文件超限" + exit 1 + fi + echo "OK: 全部受检文件 ≤$LIMIT 行" + + licenses: + name: 依赖许可与来源（cargo-deny） + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: EmbarkStudios/cargo-deny-action@v2 + with: + # 只跑许可/禁用/来源三类，advisories 由后续安全轮次单独接管 + # M118：cargo-deny 走 **workspace 依赖图**，`crates/app` 被 exclude 后 Slint 那棵树不再进图 + # （实测 `cargo deny list` 里 `slint*` / `i-slint-*` 命中 0 个），所以本门禁不再审 Slint 的 + # RF-2.0 许可 —— 与「它不再随任何产物发布」一致。这不是回退：`deny.toml` 里为 Slint 留的 + # allow 条目**故意没删**（删它得先确认没有别的路径重新引入），当前等于一条死条目。 + # 若将来把 `crates/app` 加回 workspace，本门禁的覆盖会自动恢复。 + command: check licenses bans sources diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..43ea686 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,369 @@ +name: Release + +# 发布流水线：tag `v*` → 四平台（六槽位）矩阵构建 → 单文件产物 + SHA256SUMS +# → 上传 artifact + 创建 GitHub Release（pre-release 默认开）。同一 tag 重跑幂等： +# Release 已存在时覆盖资产与说明，不再 `gh release create`（见 release job 末步）； +# 重跑**不碰** pre-release 标记，该标记只在 `inputs.prerelease` 显式给出时才被断言。 +# +# 契约唯一真相源：packaging/README.md（命名/目录/运行时依赖）。 +# 打包本体在 packaging/make_artifacts.py（本地与 CI 同一份脚本，逐字节同布局）。 +# 手动触发（workflow_dispatch）默认只跑构建不建 Release —— 用来验证矩阵仍然编得过。 +# 注意 `inputs.prerelease` 只在 **tag ref** 上 dispatch 才可达：Actions 页面的 +# "Run workflow" 只能选分支，要跑 tag 得 `gh workflow run release.yml --ref v0.1.0`。 +# 分支 ref 的 dispatch 与 push 事件一样被 release job 的 `if: github.ref_type == 'tag'` +# 挡在发布之外，所以「dispatch 只构建不发布」与「dispatch 可关 pre-release」并不矛盾。 + +on: + push: + tags: + - "v*" + workflow_dispatch: + inputs: + prerelease: + description: "标记为 pre-release（仅在 tag ref 上 dispatch 时才生效）" + type: boolean + default: true + +env: + CARGO_TERM_COLOR: always + RUST_BACKTRACE: 1 + +permissions: + contents: read + +concurrency: + group: release-${{ github.ref }} + cancel-in-progress: false + +jobs: + build: + name: build (${{ matrix.slot }}) + strategy: + fail-fast: false + matrix: + include: + # Windows x64：MSVC + 静态 CRT（+crt-static）→ exe 不依赖 VC++ 可再发行包， + # 双击即用的单文件形态；UCRT 本身就是 Win10+ 的系统组件。 + # 产物根 target/release；自检与打包都从 matrix.build_dir 取路径（不硬编码）。 + - slot: windows-x64 + os: windows-latest + build_dir: target/release + rustflags: -C target-feature=+crt-static + # Windows arm64：在 windows-latest（x64 宿主）上**交叉编译**到 aarch64-pc-windows-msvc。 + # 为什么不用 windows-11-arm 原生 runner（GitHub 文档 2026 已把 `windows-11-arm` 与 + # `windows-11-vs2026-arm` 列为公开仓库**免费**的标准 arm64 runner，原生路线可行）： + # ① 双 Windows 槽位共用同一套已验证镜像/工具链，tag 重跑行为与既有槽位一致； + # ② M50 的 dumpbin 定位链取的是 `Hostx64/x64/dumpbin.exe`，dumpbin 读 ARM64 PE 的 + # 导入表没问题，而原生 ARM 宿主上那条链得再长一条 `Hostarm64/arm64` 分支——为一个 + # 槽位放宽刚立的门禁不值得； + # ③ 交叉编译产物路径变成 target//release，已用 matrix.build_dir 参数化。 + # 若将来改成原生：只需把 os 换成 windows-11-arm、删掉 target/rustflags 依赖并给 dumpbin + # 定位链补 Hostarm64 分支（届时再评估，不在这里预先放宽）。 + - slot: windows-arm64 + os: windows-latest + target: aarch64-pc-windows-msvc + build_dir: target/aarch64-pc-windows-msvc/release + rustflags: -C target-feature=+crt-static + # Linux：固定 ubuntu-22.04（glibc 2.35 地板）而不是 latest， + # 否则产物的 glibc 底线会跟着 runner 漂移（24.04 的 glibc 明显更高）。 + - slot: linux-x64 + os: ubuntu-22.04 + build_dir: target/release + # Linux arm64：公开仓库免费的原生 ARM64 runner（原生构建，不做交叉）。 + # 用 `ubuntu-22.04-arm` 而**不是** 24.04：与 x64 同 glibc 地板（2.35）， + # 覆盖 Debian 12 / Ubuntu 22.04 arm64 / Raspberry Pi OS Bookworm（2.36）这类实际在跑的 + # ARM 发行版；换 24.04 会把地板抬高、把上面前两个挡在门外。该家族标签有 + # `ubuntu-22.04-arm` / `ubuntu-24.04-arm` / `ubuntu-26.04-arm`，均 4C/16GB、 + # 公开仓库免费不限量（GitHub 文档 Standard runners for public repositories）。 + - slot: linux-arm64 + os: ubuntu-22.04-arm + build_dir: target/release + # macOS：latest = arm64；Intel x64 用 macos-15-intel（macos-13 已下线）。 + - slot: macos-arm64 + os: macos-latest + build_dir: target/release + - slot: macos-x64 + os: macos-15-intel + build_dir: target/release + runs-on: ${{ matrix.os }} + steps: + - uses: actions/checkout@v4 + + - name: Linux 图形栈构建依赖（winit / femtovg 编译期需要） + if: runner.os == 'Linux' + shell: bash + run: | + sudo apt-get update + sudo apt-get install -y --no-install-recommends \ + libxkbcommon-dev libfontconfig1-dev libgl1-mesa-dev libegl1-mesa-dev \ + libwayland-dev libxcb1-dev + + - uses: dtolnay/rust-toolchain@stable + - uses: Swatinem/rust-cache@v2 + + # 只有交叉编译槽位需要额外 target（原生槽位留空 → 本步整体跳过）。 + # 不把 `${{ }}` 直接拼进 bash：与后面的打包步骤同一纪律，一律经 env 传入再展开。 + - name: 追加交叉编译目标 ${{ matrix.target }} + if: matrix.target != '' + shell: bash + env: + TARGET: ${{ matrix.target }} + run: rustup target add "$TARGET" + + # 交叉链接的前提是镜像里真有 ARM64 的 MSVC 库（VC `/lib/arm64/libcmt.lib`，+crt-static + # 就靠它）与 Windows SDK 的 ARM64 导入库（`um/arm64/kernel32.lib`）。缺了照样是失败， + # 但先给一句能照做的话，而不是让链接器吐一屏乱码才发现方向：门禁不降级，只把失败说清楚。 + - name: Windows ARM64 交叉工具链体检 + if: matrix.target == 'aarch64-pc-windows-msvc' + shell: bash + run: | + set -euo pipefail + roots=("C:/Program Files/Microsoft Visual Studio" "C:/Program Files (x86)/Microsoft Visual Studio") + vc_lib=$(find "${roots[@]}" -maxdepth 11 -type f -path '*/VC/Tools/MSVC/*/lib/arm64/libcmt.lib' 2>/dev/null | head -n1 || true) + sdk_version=$(ls -d "C:/Program Files (x86)/Windows Kits/10/Lib"/* 2>/dev/null | tail -n1 || true) + sdk_lib="" + if [ -n "$sdk_version" ]; then + sdk_lib=$(find "$sdk_version/um/arm64" -maxdepth 1 -name 'kernel32.lib' 2>/dev/null | head -n1 || true) + fi + echo "MSVC ARM64 静态 CRT: ${vc_lib:-<缺失>}" + echo "SDK ARM64 导入库: ${sdk_lib:-<缺失>}" + if [ -z "$vc_lib" ] || [ -z "$sdk_lib" ]; then + echo "::error::交叉链接缺 ARM64 库：给 VS 加上 Microsoft.VisualStudio.Component.VC.Tools.ARM64（含 ARM64 Windows SDK），或把该槽位改用原生 windows-11-arm runner" + exit 1 + fi + + # M118（D26）：**Slint 版停发**。旧写法 `--bin unlucky-launcher` 打的是 `crates/app` + # （Slint 退役树）的 bin —— 也就是说这条流水线一直在发 Slint 版二进制，而 D26 早已把 + # iced 定为产品 UI。现在 GUI 来源只有 `unlucky-launcher-iced`；`crates/app` 也已在根 + # Cargo.toml 被 `exclude`，不参与任何 workspace 构建（它连 `--manifest-path` 都编不了）。 + # 对外产物名由 `packaging/make_artifacts.py` 的 `asset_stem()` 统一生成，格式是 + # `<名字>_<版本号>_<平台>_<架构>`（用户令 2026-11-05）：下划线分段，且**不带实现细节 + # 字样**（产物名里不出现 `iced`）。`LAUNCHER_BIN` 只用来在构建产物里找文件。 + - name: cargo build --release --locked + shell: bash + env: + RUSTFLAGS: ${{ matrix.rustflags }} + TARGET: ${{ matrix.target }} + run: | + set -euo pipefail + target_args=() + if [ -n "$TARGET" ]; then + target_args+=(--target "$TARGET") + fi + cargo build --release --locked "${target_args[@]}" --bin unlucky-launcher-iced --bin ull + + - name: Windows 单文件自检（导入表不得出现 VC++ 可再发行 DLL） + if: runner.os == 'Windows' + shell: bash + env: + # 跨槽位的关键点：产物在 target//release 而不是 target/release。 + # M118：校验的是**构建产物**（iced bin 的原始文件名）。对外名 `unlucky-launcher` + # 由 packaging/make_artifacts.py 在落盘时才换上，那一步之后才存在。 + EXE: ${{ matrix.build_dir }}/unlucky-launcher-iced.exe + run: | + set -euo pipefail + # +crt-static 是否真的生效，只看导入表：出现 VCRUNTIME/MSVCP/msvcr/ucrtbase 说明还得装 + # 可再发行包，那就不是"单文件"了，直接 fail。 + # + # dumpbin 定位链（三级，全不命中才 fail —— 门禁不降级，只是把"猜路径"换成官方定位）： + # ① vswhere：VS 官方定位器，安装器自身路径固定，与 VS 版本/版次/安装布局无关； + # ② find 兜底：Program Files 与 Program Files (x86) 两个 VS 根都扫（Build Tools 落在 x86 根）； + # ③ PATH：镜像若已把工具链预置进 PATH 则直接可用。 + # PATH 排最后是刻意的：PATH 最不可控，官方定位器优先。 + # Hostx64 的 dumpbin 读 ARM64 PE 的导入表没问题，所以 arm64 槽位共用同一条链。 + VSWHERE="C:/Program Files (x86)/Microsoft Visual Studio/Installer/vswhere.exe" + DUMPBIN="" + VIA="" + if [ -x "$VSWHERE" ]; then + # -find 的模式优先用反斜杠（vswhere 官方文档即此形式），再试正斜杠以规避分隔符差异。 + for pattern in 'VC\Tools\MSVC\*\bin\Hostx64\x64\dumpbin.exe' \ + 'VC/Tools/MSVC/*/bin/Hostx64/x64/dumpbin.exe'; do + hit=$("$VSWHERE" -latest -products '*' -find "$pattern" 2>/dev/null | head -n1 || true) + if [ -n "$hit" ]; then + DUMPBIN=${hit//\\//} + VIA="vswhere" + break + fi + done + fi + if [ -z "$DUMPBIN" ]; then + # 镜像里的 VS 根形如 <年>/<版次>（2022/Enterprise、2022/BuildTools……）， + # 固定层数的 glob 会在 <年>/<版次> 这两级踩空，所以按路径模式扫。 + for root in "C:/Program Files/Microsoft Visual Studio" \ + "C:/Program Files (x86)/Microsoft Visual Studio"; do + [ -d "$root" ] || continue + hit=$(find "$root" -maxdepth 11 -type f \ + -path '*/VC/Tools/MSVC/*/bin/Hostx64/x64/dumpbin.exe' 2>/dev/null | head -n1 || true) + if [ -n "$hit" ]; then + DUMPBIN=$hit + VIA="find: $root" + break + fi + done + fi + if [ -z "$DUMPBIN" ]; then + hit=$(command -v dumpbin || true) + if [ -n "$hit" ]; then + DUMPBIN=$hit + VIA="PATH" + fi + fi + # 工具缺失同样 fail：windows-latest 自带 VS 工具链，基本找得到； + # "找不到就跳过"等于让这道门禁在最需要它的时候静默失效。 + if [ -z "$DUMPBIN" ]; then + echo "::error::找不到 dumpbin，无法校验导入表（静态 CRT 门禁不降级）" + exit 1 + fi + echo "dumpbin: $DUMPBIN（定位自 $VIA）" + ls -l "$EXE" + "$DUMPBIN" -nologo -dependents "$EXE" | tee dependents.txt + if grep -Eiq 'VCRUNTIME|MSVCP|MSVCR|ucrtbase\.dll' dependents.txt; then + echo "::error::静态 CRT 未生效：exe 仍动态依赖 VC++ 可再发行包" + exit 1 + fi + + - name: 打包（产物 + SHA256SUMS） + shell: bash + env: + # 不把 `${{ }}` 直接拼进 bash 脚本：git ref 名允许 `$`/反引号/`"`，一律经 env 传入再展开。 + REF_TYPE: ${{ github.ref_type }} + TAG: ${{ github.ref_name }} + SLOT: ${{ matrix.slot }} + BUILD_DIR: ${{ matrix.build_dir }} + run: | + set -euo pipefail + # git-bash 与 Linux/macOS runner 的 python 入口名不一致，先探一遍。 + PY=$(command -v python3 || command -v python) + # 槽位与产物根都从矩阵来：交叉槽位的二进制不在 target/release，脚本据此定位 + # 并回读可执行文件头校验架构（宿主 x64 ≠ 产物 arm64 时冒烟自动跳过，只等 CI 真机）。 + args=(--slot "$SLOT" --build-dir "$BUILD_DIR") + if [ "$REF_TYPE" = "tag" ]; then + args+=(--version "$TAG") # 与 Cargo.toml 版本交叉校验 + fi + "$PY" packaging/make_artifacts.py "${args[@]}" --out dist + ls -l dist + + - name: 归档内容自检（二进制定位 + 合规文本） + shell: bash + run: | + set -euo pipefail + for archive in dist/*.tar.gz; do + [ -e "$archive" ] || continue + listing=$(tar -tzf "$archive") + for required in unlucky-launcher LICENSE NOTICE README.md; do + if ! grep -q "/$required$" <<<"$listing"; then + echo "::error file=$archive::$archive 缺少 $required" + exit 1 + fi + done + echo "OK: $archive 含二进制与 LICENSE/NOTICE/README.md" + done + if ls dist/*.exe >/dev/null 2>&1; then + echo "Windows 单 exe 形态：LICENSE/NOTICE/README.md 作为 Release 资产并列分发" + fi + + - uses: actions/upload-artifact@v4 + with: + name: dist-${{ matrix.slot }} + path: dist + if-no-files-found: error + retention-days: 14 + + release: + name: GitHub Release + needs: build + if: github.ref_type == 'tag' + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - uses: actions/checkout@v4 + + - uses: actions/download-artifact@v4 + with: + path: dist + merge-multiple: true + + - name: 矩阵完整性 + 重算全量 SHA256SUMS + shell: bash + run: | + set -euo pipefail + ls -l dist + # 六槽位全齐才发版：缺任意一个就 fail（宁可不出 Release，也不出少一档的 Release）。 + # 每个槽位都要 GUI 与 CLI 两个资产——只按「槽位名出现过」判会被其中一个掩盖。 + for slot in windows-x64 windows-arm64 linux-x64 linux-arm64 macos-arm64 macos-x64; do + for prefix in unlucky-launcher ull; do + if ! compgen -G "dist/$prefix-*-$slot*" >/dev/null; then + echo "::error::矩阵缺产物：$prefix / $slot" + exit 1 + fi + done + done + # 各平台任务各写一份 SHA256SUMS.txt，合并后只有一份是真的 —— 在 Release 侧重算。 + # GUI 与 CLI 都要进清单：漏了 ull 就是「发了但没有校验和」。 + cd dist + rm -f SHA256SUMS.txt + sha256sum unlucky-launcher_* ull_* > SHA256SUMS.txt + sha256sum -c SHA256SUMS.txt + cat SHA256SUMS.txt + + - name: 生成 Release 说明（支持矩阵模板） + shell: bash + env: + TAG: ${{ github.ref_name }} + run: | + set -euo pipefail + python3 - <<'PY' + import os, pathlib + version = os.environ["TAG"].lstrip("v") + template = pathlib.Path("packaging/release-notes.md").read_text(encoding="utf-8") + sums = pathlib.Path("dist/SHA256SUMS.txt").read_text(encoding="utf-8").strip() + body = template.replace("{{VERSION}}", version).replace("{{SUMS}}", sums) + pathlib.Path("release-body.md").write_text(body, encoding="utf-8", newline="\n") + print(body[:400]) + PY + + - name: 创建或更新 GitHub Release（同 tag 重跑幂等） + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + TAG: ${{ github.ref_name }} + PRERELEASE: ${{ inputs.prerelease }} + shell: bash + run: | + set -euo pipefail + base_flags=(--title "Unlucky Launcher $TAG" --notes-file release-body.md) + # pre-release 标记只在**显式要求**时才断言： + # PRERELEASE=true / false —— 来自 tag ref 上的 workflow_dispatch 输入； + # PRERELEASE 空 —— push 触发的运行或它的 Re-run，此时**不碰**该标记， + # 否则会把用户手动提升为 stable 的 Release 静默翻回 pre-release。 + # 首次创建（create）仍保持「pre-release 默认开」的老契约：空值按 true 处理。 + create_mark=() + edit_mark=() + case "${PRERELEASE:-}" in + true) + create_mark=(--prerelease) + edit_mark=(--prerelease) + ;; + false) + edit_mark=(--prerelease=false) + ;; + "") + create_mark=(--prerelease) + ;; + *) + echo "::error::非预期的 inputs.prerelease 取值：$PRERELEASE" + exit 1 + ;; + esac + # Windows 单 exe 装不下 LICENSE/NOTICE/README.md，这三份与产物并列挂到 Release 上， + # 保证每个下载平台的许可条款都随包分发。 + # `ull` 是独立资产（不在 tar.gz 里）：headless 用户下一个小文件直接跑，不用解档。 + assets=(dist/unlucky-launcher_* dist/ull_* dist/SHA256SUMS.txt LICENSE NOTICE README.md) + if gh release view "$TAG" >/dev/null 2>&1; then + # 同 tag 重跑（补丁 / 重编）：Release 已存在 → 覆盖资产 + 刷新说明， + # 不再 `create`（那会因已存在而失败，把整条流水线在最后一步染红）。 + gh release upload "$TAG" "${assets[@]}" --clobber + gh release edit "$TAG" "${base_flags[@]}" "${edit_mark[@]}" + else + gh release create "$TAG" "${assets[@]}" "${base_flags[@]}" "${create_mark[@]}" + fi diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..7143e9e --- /dev/null +++ b/.gitignore @@ -0,0 +1,28 @@ +# Reference source repositories (local-only, git-ignored) +/HMCL/ +/PCL/ + +# Local development docs +/DevDocs/ + +# Local acceptance screenshots (screenshot channel output, never committed) +/.screens/ +/.tmp-screens/ + +# Agent workspace (local-only) +/.tower/ + +# Build outputs +build/ +dist/ +out/ +target/ + +# IDE +.idea/ +.vscode/ +*.iml + +# OS +Thumbs.db +.DS_Store diff --git a/.rustfmt.toml b/.rustfmt.toml new file mode 100644 index 0000000..bdb5303 --- /dev/null +++ b/.rustfmt.toml @@ -0,0 +1,5 @@ +edition = "2021" +max_width = 100 +newline_style = "Unix" +use_field_init_shorthand = true +use_try_shorthand = true diff --git a/Cargo.lock b/Cargo.lock new file mode 100644 index 0000000..fd7c9e4 --- /dev/null +++ b/Cargo.lock @@ -0,0 +1,6343 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 4 + +[[package]] +name = "ab_glyph" +version = "0.2.32" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "01c0457472c38ea5bd1c3b5ada5e368271cb550be7a4ca4a0b4634e9913f6cc2" +dependencies = [ + "ab_glyph_rasterizer", + "owned_ttf_parser", +] + +[[package]] +name = "ab_glyph_rasterizer" +version = "0.1.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "366ffbaa4442f4684d91e2cd7c5ea7c4ed8add41959a31447066e279e432b618" + +[[package]] +name = "adler2" +version = "2.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa" + +[[package]] +name = "ahash" +version = "0.8.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5a15f179cd60c4584b8a8c596927aadc462e27f2ca70c04e0071964a73ba7a75" +dependencies = [ + "cfg-if", + "getrandom 0.3.4", + "once_cell", + "version_check", + "zerocopy", +] + +[[package]] +name = "aho-corasick" +version = "1.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba" +dependencies = [ + "memchr", +] + +[[package]] +name = "android-activity" +version = "0.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0f2a1bb052857d5dd49572219344a7332b31b76405648eabac5bc68978251bcd" +dependencies = [ + "android-properties", + "bitflags 2.13.2", + "cc", + "jni", + "libc", + "log", + "ndk", + "ndk-context", + "ndk-sys", + "num_enum", + "thiserror 2.0.21", +] + +[[package]] +name = "android-build" +version = "0.1.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f9fc9904ad2ad097c3c1cfe2eacaaf0fc24710936fa9ed941cb310b7c6ed2ab7" +dependencies = [ + "windows-sys 0.52.0", +] + +[[package]] +name = "android-properties" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fc7eb209b1518d6bb87b283c20095f5228ecda460da70b44f0802523dea6da04" + +[[package]] +name = "android_system_properties" +version = "0.1.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ae221649c9976a6f6c56ae1facf410f3ddb33cc661c4b7b61020a912d4237fbc" +dependencies = [ + "libc", +] + +[[package]] +name = "arrayref" +version = "0.3.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "76a2e8124351fda1ef8aaaa3bbd7ebbcb486bbcd4225aca0aa0d84bb2db8fecb" + +[[package]] +name = "arrayvec" +version = "0.7.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d3fb67a6e08acf24fdeccbac2cb6ac4305825bd1f117462e0e6f2f193345ad56" + +[[package]] +name = "as-raw-xcb-connection" +version = "1.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "175571dd1d178ced59193a6fc02dde1b972eb0bc56c892cde9beeceac5bf0f6b" + +[[package]] +name = "ash" +version = "0.38.0+1.3.281" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0bb44936d800fea8f016d7f2311c6a4f97aebd5dc86f09906139ec848cf3a46f" +dependencies = [ + "libloading", +] + +[[package]] +name = "async-broadcast" +version = "0.7.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "435a87a52755b8f27fcf321ac4f04b2802e337c8c4872923137471ec39c37532" +dependencies = [ + "event-listener", + "event-listener-strategy", + "futures-core", + "pin-project-lite", +] + +[[package]] +name = "async-channel" +version = "2.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "924ed96dd52d1b75e9c1a3e6275715fd320f5f9439fb5a4a11fa51f4221158d2" +dependencies = [ + "concurrent-queue", + "event-listener-strategy", + "futures-core", + "pin-project-lite", +] + +[[package]] +name = "async-executor" +version = "1.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c96bf972d85afc50bf5ab8fe2d54d1586b4e0b46c97c50a0c9e71e2f7bcd812a" +dependencies = [ + "async-task", + "concurrent-queue", + "fastrand", + "futures-lite", + "pin-project-lite", + "slab", +] + +[[package]] +name = "async-io" +version = "2.6.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "456b8a8feb6f42d237746d4b3e9a178494627745c3c56c6ea55d92ba50d026fc" +dependencies = [ + "autocfg", + "cfg-if", + "concurrent-queue", + "futures-io", + "futures-lite", + "parking", + "polling", + "rustix 1.1.6", + "slab", + "windows-sys 0.61.2", +] + +[[package]] +name = "async-lock" +version = "3.4.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "290f7f2596bd5b78a9fec8088ccd89180d7f9f55b94b0576823bbbdc72ee8311" +dependencies = [ + "event-listener", + "event-listener-strategy", + "pin-project-lite", +] + +[[package]] +name = "async-process" +version = "2.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fc50921ec0055cdd8a16de48773bfeec5c972598674347252c0399676be7da75" +dependencies = [ + "async-channel", + "async-io", + "async-lock", + "async-signal", + "async-task", + "blocking", + "cfg-if", + "event-listener", + "futures-lite", + "rustix 1.1.6", +] + +[[package]] +name = "async-recursion" +version = "1.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4f8abc12baad266b1c8cec146854c195b5864b4221d4b2ca7296a7ae82d9e451" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.9", +] + +[[package]] +name = "async-signal" +version = "0.2.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "52b5aaafa020cf5053a01f2a60e8ff5dccf550f0f77ec54a4e47285ac2bab485" +dependencies = [ + "async-io", + "async-lock", + "atomic-waker", + "cfg-if", + "futures-core", + "futures-io", + "rustix 1.1.6", + "signal-hook-registry", + "slab", + "windows-sys 0.61.2", +] + +[[package]] +name = "async-stream" +version = "0.3.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0b5a71a6f37880a80d1d7f19efd781e4b5de42c88f0722cc13bcb6cc2cfe8476" +dependencies = [ + "async-stream-impl", + "futures-core", + "pin-project-lite", +] + +[[package]] +name = "async-stream-impl" +version = "0.3.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c7c24de15d275a1ecfd47a380fb4d5ec9bfe0933f309ed5e705b775596a3574d" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "async-task" +version = "4.7.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8b75356056920673b02621b35afd0f7dda9306d03c79a30f5c56c44cf256e3de" + +[[package]] +name = "async-trait" +version = "0.1.92" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "82f6aeea286b8eb4dd3431a1be1b59d290ace00f5bfd8e2a159bc2a05e2c1667" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.9", +] + +[[package]] +name = "atomic-waker" +version = "1.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1505bd5d3d116872e7271a6d4e16d81d0c8570876c8de68093a09ac269d8aac0" + +[[package]] +name = "autocfg" +version = "1.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53" + +[[package]] +name = "aws-lc-rs" +version = "1.19.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "048006790404103c488e6c5616b3e7e702a71292aadda08e8f7698a9e0d2eb53" +dependencies = [ + "aws-lc-sys", + "zeroize", +] + +[[package]] +name = "aws-lc-sys" +version = "0.47.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8bfbe32ac36b3c428696ce315464181bc4029d689fd58e3f2a4e58c252242f52" +dependencies = [ + "cc", + "cmake", + "dunce", + "fs_extra", + "pkg-config", +] + +[[package]] +name = "axum" +version = "0.8.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "31b698c5f9a010f6573133b09e0de5408834d0c82f8d7475a89fc1867a71cd90" +dependencies = [ + "axum-core", + "bytes", + "form_urlencoded", + "futures-util", + "http", + "http-body", + "http-body-util", + "hyper", + "hyper-util", + "itoa", + "matchit", + "memchr", + "mime", + "percent-encoding", + "pin-project-lite", + "serde_core", + "serde_json", + "serde_path_to_error", + "serde_urlencoded", + "sync_wrapper", + "tokio", + "tower", + "tower-layer", + "tower-service", + "tracing", +] + +[[package]] +name = "axum-core" +version = "0.5.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "08c78f31d7b1291f7ee735c1c6780ccde7785daae9a9206026862dab7d8792d1" +dependencies = [ + "bytes", + "futures-core", + "http", + "http-body", + "http-body-util", + "mime", + "pin-project-lite", + "sync_wrapper", + "tower-layer", + "tower-service", + "tracing", +] + +[[package]] +name = "base64" +version = "0.22.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6" + +[[package]] +name = "base64" +version = "0.23.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ac07cdecf99051d9a5238b80f35af32cdeba5b336e55d957b318b50137e18da5" + +[[package]] +name = "bit-set" +version = "0.8.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "08807e080ed7f9d5433fa9b275196cfc35414f66a0c79d864dc51a0d825231a3" +dependencies = [ + "bit-vec", +] + +[[package]] +name = "bit-vec" +version = "0.8.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5e764a1d40d510daf35e07be9eb06e75770908c27d411ee6c92109c9840eaaf7" + +[[package]] +name = "bitflags" +version = "1.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a" + +[[package]] +name = "bitflags" +version = "2.13.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06" + +[[package]] +name = "block" +version = "0.1.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0d8c1fef690941d3e7788d328517591fecc684c084084702d6ff1641e993699a" + +[[package]] +name = "block-buffer" +version = "0.10.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71" +dependencies = [ + "generic-array", +] + +[[package]] +name = "block2" +version = "0.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2c132eebf10f5cad5289222520a4a058514204aed6d791f1cf4fe8088b82d15f" +dependencies = [ + "objc2 0.5.3", +] + +[[package]] +name = "block2" +version = "0.6.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cdeb9d870516001442e364c5220d3574d2da8dc765554b4a617230d33fa58ef5" +dependencies = [ + "objc2 0.6.5", +] + +[[package]] +name = "blocking" +version = "1.7.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a70e4329df6cb94385eed412ec92375c3cdd8a6e502493d1229b6414e4036dfa" +dependencies = [ + "async-channel", + "async-task", + "futures-io", + "futures-lite", + "piper", +] + +[[package]] +name = "bumpalo" +version = "3.20.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649" + +[[package]] +name = "bytemuck" +version = "1.25.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "95832e849adfb21180ccb6826a99da14e5d266ae5c2e668e1602cf234f153797" +dependencies = [ + "bytemuck_derive", +] + +[[package]] +name = "bytemuck_derive" +version = "1.12.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6a1f896587b6f2c069c73d2f0913e2d590c3990285cd2f0b6aa02b786b4c679c" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.9", +] + +[[package]] +name = "byteorder-lite" +version = "0.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8f1fe948ff07f4bd06c30984e69f5b4899c516a3ef74f34df92a2df2ab535495" + +[[package]] +name = "bytes" +version = "1.12.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04" + +[[package]] +name = "calloop" +version = "0.13.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b99da2f8558ca23c71f4fd15dc57c906239752dd27ff3c00a1d56b685b7cbfec" +dependencies = [ + "bitflags 2.13.2", + "log", + "polling", + "rustix 0.38.44", + "slab", + "thiserror 1.0.69", +] + +[[package]] +name = "calloop" +version = "0.14.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "43b32313e937c8721c9d17ee9bf60699a6402b4b7c2cb6ac1bee0ffcaa4b4e5e" +dependencies = [ + "bitflags 2.13.2", + "polling", + "rustix 1.1.6", + "tracing", +] + +[[package]] +name = "calloop-wayland-source" +version = "0.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "95a66a987056935f7efce4ab5668920b5d0dac4a7c99991a67395f13702ddd20" +dependencies = [ + "calloop 0.13.0", + "rustix 0.38.44", + "wayland-backend", + "wayland-client", +] + +[[package]] +name = "calloop-wayland-source" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "138efcf0940a02ebf0cc8d1eff41a1682a46b431630f4c52450d6265876021fa" +dependencies = [ + "calloop 0.14.5", + "rustix 1.1.6", + "wayland-backend", + "wayland-client", +] + +[[package]] +name = "cc" +version = "1.10.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "86e055fa6e3e40ad6187ba25b6855eeb635d5271f8e0f0e1e9a5826b8d75bea0" +dependencies = [ + "find-msvc-tools", + "jobserver", + "libc", + "shlex", +] + +[[package]] +name = "cfg-if" +version = "1.0.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600" + +[[package]] +name = "cfg_aliases" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f079e83a288787bcd14a6aea84cee5c87a67c5a3e660c30f557a3d24761b3527" + +[[package]] +name = "chacha20" +version = "0.10.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "65c35e4b699c7e15ccbe7ee35c005e4fc0a278d22238a2857e6ce2dadeda1b06" +dependencies = [ + "cfg-if", + "cpufeatures 0.3.1", + "rand_core 0.10.1", +] + +[[package]] +name = "chrono" +version = "0.4.45" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1aa79e62e7697b8e29b513a68abacf485adcd1fe8284a4316c5ae868e6633327" +dependencies = [ + "iana-time-zone", + "num-traits", + "serde", + "windows-link", +] + +[[package]] +name = "clipboard-win" +version = "5.4.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "052af7878466feccda12ba7a6a67d019d712f296809559b47c12c8cc196d3a9a" +dependencies = [ + "error-code", +] + +[[package]] +name = "clipboard_macos" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9b7f4aaa047ba3c3630b080bb9860894732ff23e2aee290a418909aa6d5df38f" +dependencies = [ + "objc2 0.5.3", + "objc2-app-kit 0.2.2", + "objc2-foundation 0.2.2", +] + +[[package]] +name = "clipboard_wayland" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "003f886bc4e2987729d10c1db3424e7f80809f3fc22dbc16c685738887cb37b8" +dependencies = [ + "smithay-clipboard", +] + +[[package]] +name = "clipboard_x11" +version = "0.4.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bd63e33452ffdafd39924c4f05a5dd1e94db646c779c6bd59148a3d95fff5ad4" +dependencies = [ + "thiserror 2.0.21", + "x11rb", +] + +[[package]] +name = "cmake" +version = "0.1.58" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c0f78a02292a74a88ac736019ab962ece0bc380e3f977bf72e376c5d78ff0678" +dependencies = [ + "cc", +] + +[[package]] +name = "codespan-reporting" +version = "0.12.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fe6d2e5af09e8c8ad56c969f2157a3d4238cebc7c55f0a517728c38f7b200f81" +dependencies = [ + "serde", + "termcolor", + "unicode-width", +] + +[[package]] +name = "color_quant" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3d7b894f5411737b7867f4827955924d7c254fc9f4d91a6aad6b097804b1018b" + +[[package]] +name = "combine" +version = "4.6.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4356eba6976435498d05a311ee9fc486da3bc81c200d3f0d7dd9703b41913f92" +dependencies = [ + "bytes", + "memchr", +] + +[[package]] +name = "concurrent-queue" +version = "2.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4ca0197aee26d1ae37445ee532fefce43251d24cc7c166799f4d46817f1d3973" +dependencies = [ + "crossbeam-utils", +] + +[[package]] +name = "convert_case" +version = "0.11.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "affbf0190ed2caf063e3def54ff444b449371d55c58e513a95ab98eca50adb49" +dependencies = [ + "unicode-segmentation", +] + +[[package]] +name = "core-foundation" +version = "0.9.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "91e195e091a93c46f7102ec7818a2aa394e1e1771c3ab4825963fa03e45afb8f" +dependencies = [ + "core-foundation-sys", + "libc", +] + +[[package]] +name = "core-foundation" +version = "0.10.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b2a6cd9ae233e7f62ba4e9353e81a88df7fc8a5987b8d445b4d90c879bd156f6" +dependencies = [ + "core-foundation-sys", + "libc", +] + +[[package]] +name = "core-foundation-sys" +version = "0.8.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b" + +[[package]] +name = "core-graphics" +version = "0.23.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c07782be35f9e1140080c6b96f0d44b739e2278479f64e02fdab4e32dfd8b081" +dependencies = [ + "bitflags 1.3.2", + "core-foundation 0.9.4", + "core-graphics-types 0.1.3", + "foreign-types", + "libc", +] + +[[package]] +name = "core-graphics-types" +version = "0.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "45390e6114f68f718cc7a830514a96f903cccd70d02a8f6d9f643ac4ba45afaf" +dependencies = [ + "bitflags 1.3.2", + "core-foundation 0.9.4", + "libc", +] + +[[package]] +name = "core-graphics-types" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3d44a101f213f6c4cdc1853d4b78aef6db6bdfa3468798cc1d9912f4735013eb" +dependencies = [ + "bitflags 2.13.2", + "core-foundation 0.10.1", + "libc", +] + +[[package]] +name = "core_detect" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7f8f80099a98041a3d1622845c271458a2d73e688351bf3cb999266764b81d48" + +[[package]] +name = "core_maths" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "77745e017f5edba1a9c1d854f6f3a52dac8a12dd5af5d2f54aecf61e43d80d30" +dependencies = [ + "libm", +] + +[[package]] +name = "cosmic-text" +version = "0.15.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "173852283a9a57a3cbe365d86e74dc428a09c50421477d5ad6fe9d9509e37737" +dependencies = [ + "bitflags 2.13.2", + "fontdb", + "harfrust", + "linebender_resource_handle", + "log", + "rangemap", + "rustc-hash 1.1.0", + "self_cell", + "skrifa 0.37.0", + "smol_str", + "swash", + "sys-locale", + "unicode-bidi", + "unicode-linebreak", + "unicode-script", + "unicode-segmentation", +] + +[[package]] +name = "cpufeatures" +version = "0.2.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280" +dependencies = [ + "libc", +] + +[[package]] +name = "cpufeatures" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5ca28b0ae3115b884660db4118d803791fd6756b6e88f39c0f3f7859060d7566" +dependencies = [ + "libc", +] + +[[package]] +name = "crc32fast" +version = "1.5.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0ba106e844045ddc02c20768ac4b0b7cb45f2cc2ecbd833ac9f5dacb183c2055" +dependencies = [ + "cfg-if", +] + +[[package]] +name = "crossbeam-utils" +version = "0.8.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a31eee39dddec8330830986fcd7625edb5a24ec90ea038215273bbc3adb08ac6" + +[[package]] +name = "crunchy" +version = "0.2.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "460fbee9c2c2f33933d720630a6a0bac33ba7053db5344fac858d4b8952d77d5" + +[[package]] +name = "cryoglyph" +version = "0.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "08bc795bdbccdbd461736fb163930a009da6597b226d6f6fce33e7a8eb6ec519" +dependencies = [ + "cosmic-text", + "etagere", + "lru", + "rustc-hash 2.1.3", + "wgpu", +] + +[[package]] +name = "crypto-common" +version = "0.1.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a" +dependencies = [ + "generic-array", + "typenum", +] + +[[package]] +name = "ctor" +version = "0.10.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "83cf0d42651b16c6dfe68685716d18480d18a9c39c62d76e8cf3eb6ed5d8bcbf" +dependencies = [ + "dtor", +] + +[[package]] +name = "cursor-icon" +version = "1.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f27ae1dd37df86211c42e150270f82743308803d90a6f6e6651cd730d5e1732f" + +[[package]] +name = "darling" +version = "0.24.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ed17f5901b6630b993ca003def43f2f8ef4014fc13b047b57aad617ff32bc2ec" +dependencies = [ + "darling_core", + "darling_macro", +] + +[[package]] +name = "darling_core" +version = "0.24.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6837e2cf7485aaae18f86181d2f0e9a7ed297a025e220aeabf63fdebd3a2ddff" +dependencies = [ + "ident_case", + "proc-macro2", + "quote", + "strsim", + "syn 3.0.9", +] + +[[package]] +name = "darling_macro" +version = "0.24.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2ac7135c3ef02b2f7833bbeb1be5ba7f966dcde8a87c6b87f65a778d71a02785" +dependencies = [ + "darling_core", + "quote", + "syn 3.0.9", +] + +[[package]] +name = "data-encoding" +version = "2.11.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4583a4551df46e2792f82ceeac45e850d2e2d5debba0b91f102385cda5b11f06" + +[[package]] +name = "data-url" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "be1e0bca6c3637f992fc1cc7cbc52a78c1ef6db076dbf1059c4323d6a2048376" + +[[package]] +name = "digest" +version = "0.10.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292" +dependencies = [ + "block-buffer", + "crypto-common", +] + +[[package]] +name = "dispatch" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bd0c93bb4b0c6d9b77f4435b0ae98c24d17f1c45b2ff844c6151a07256ca923b" + +[[package]] +name = "dispatch2" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1e0e367e4e7da84520dedcac1901e4da967309406d1e51017ae1abfb97adbd38" +dependencies = [ + "bitflags 2.13.2", + "objc2 0.6.5", +] + +[[package]] +name = "displaydoc" +version = "0.2.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c6232dd377dcc64799954cbd3a9bb882e9cdc1308ccd87b1c098f1fb2eaf82a8" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.9", +] + +[[package]] +name = "dlib" +version = "0.5.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ab8ecd87370524b461f8557c119c405552c396ed91fc0a8eec68679eab26f94a" +dependencies = [ + "libloading", +] + +[[package]] +name = "document-features" +version = "0.2.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d4b8a88685455ed29a21542a33abd9cb6510b6b129abadabdcef0f4c55bc8f61" +dependencies = [ + "litrs", +] + +[[package]] +name = "downcast-rs" +version = "1.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "75b325c5dbd37f80359721ad39aca5a29fb04c89279657cffdda8736d0c0b9d2" + +[[package]] +name = "dpi" +version = "0.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d8b14ccef22fc6f5a8f4d7d768562a182c04ce9a3b3157b91390b52ddfdf1a76" + +[[package]] +name = "dtor" +version = "0.8.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "edf234dd1594d6dd434a8fb8cada51ddbbc593e40e4a01556a0b31c62da2775b" + +[[package]] +name = "dunce" +version = "1.0.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "92773504d58c093f6de2459af4af33faa518c13451eb8f2b5698ed3d36e7c813" + +[[package]] +name = "dyn-clone" +version = "1.0.20" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d0881ea181b1df73ff77ffaaf9c7544ecc11e82fba9b5f27b262a3c73a332555" + +[[package]] +name = "encoding_rs" +version = "0.8.42" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8e985e0451871ad22fb8d2b6b076e2028a502a0d3950998c2c5c0a4f9b5d9679" +dependencies = [ + "cfg-if", + "core_detect", + "multiversion_no_op", + "rustversion", + "scopeguard", + "simdutf8", +] + +[[package]] +name = "endi" +version = "1.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "66b7e2430c6dff6a955451e2cfc438f09cea1965a9d6f87f7e3b90decc014099" + +[[package]] +name = "enumflags2" +version = "0.7.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1027f7680c853e056ebcec683615fb6fbbc07dbaa13b4d5d9442b146ded4ecef" +dependencies = [ + "enumflags2_derive", + "serde", +] + +[[package]] +name = "enumflags2_derive" +version = "0.7.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "67c78a4d8fdf9953a5c9d458f9efe940fd97a0cab0941c075a813ac594733827" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "equivalent" +version = "1.0.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "00d174d5400e5e8fd687ad1049e2f578285fa914201b1af7e8b112a4546bd826" + +[[package]] +name = "errno" +version = "0.3.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb" +dependencies = [ + "libc", + "windows-sys 0.61.2", +] + +[[package]] +name = "error-code" +version = "3.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0b5343afd4a8365a643ac588dab4cf234a190c7f6c88c9f6dd6ffe00837661b7" + +[[package]] +name = "etagere" +version = "0.2.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fc89bf99e5dc15954a60f707c1e09d7540e5cd9af85fa75caa0b510bc08c5342" +dependencies = [ + "euclid", + "svg_fmt", +] + +[[package]] +name = "euclid" +version = "0.22.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f1a05365e3b1c6d1650318537c7460c6923f1abdd272ad6842baa2b509957a06" +dependencies = [ + "num-traits", +] + +[[package]] +name = "event-listener" +version = "5.4.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5a23add41df1562121a9393cb065eab5146a1242410f23a644851e90cfd669d2" +dependencies = [ + "parking", + "pin-project-lite", +] + +[[package]] +name = "event-listener-strategy" +version = "0.5.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8be9f3dfaaffdae2972880079a491a1a8bb7cbed0b8dd7a347f668b4150a3b93" +dependencies = [ + "event-listener", + "pin-project-lite", +] + +[[package]] +name = "fastrand" +version = "2.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223" + +[[package]] +name = "fdeflate" +version = "0.3.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1e6853b52649d4ac5c0bd02320cddc5ba956bdb407c4b75a2c6b75bf51500f8c" +dependencies = [ + "simd-adler32", +] + +[[package]] +name = "filetime" +version = "0.2.29" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5c287a33c7f0a620c38e641e7f60827713987b3c0f26e8ddc9462cc69cf75759" +dependencies = [ + "cfg-if", + "libc", +] + +[[package]] +name = "find-msvc-tools" +version = "0.1.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1c66915cc5391097de7a2b0b972e8505aa33c0df401fd3a6811dbdb32881ba48" + +[[package]] +name = "flate2" +version = "1.1.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6e634e2e0ebac1ee034020da1ca582e17ffe4e0f5e985823721e168928136dcb" +dependencies = [ + "crc32fast", + "miniz_oxide 0.9.1", + "zlib-rs", +] + +[[package]] +name = "float-cmp" +version = "0.9.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "98de4bbd547a563b716d8dfa9aad1cb19bfab00f4fa09a6a4ed21dbcf44ce9c4" + +[[package]] +name = "fnv" +version = "1.0.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1" + +[[package]] +name = "foldhash" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d9c4f5dac5e15c24eb999c26181a6ca40b39fe946cbe4c263c7209467bc83af2" + +[[package]] +name = "foldhash" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "77ce24cb58228fbb8aa041425bb1050850ac19177686ea6e0f41a70416f56fdb" + +[[package]] +name = "font-types" +version = "0.10.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "39a654f404bbcbd48ea58c617c2993ee91d1cb63727a37bf2323a4edeed1b8c5" +dependencies = [ + "bytemuck", +] + +[[package]] +name = "font-types" +version = "0.12.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "835ae9d781464a79026cde387f9cbc650c9a4909d7cf7e658b127e3c35d2f35d" +dependencies = [ + "bytemuck", +] + +[[package]] +name = "fontconfig-parser" +version = "0.5.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bbc773e24e02d4ddd8395fd30dc147524273a83e54e0f312d986ea30de5f5646" +dependencies = [ + "roxmltree", +] + +[[package]] +name = "fontdb" +version = "0.23.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "457e789b3d1202543297a350643cf459f836cade38934e7a4cf6a39e7cde2905" +dependencies = [ + "fontconfig-parser", + "log", + "memmap2", + "slotmap", + "tinyvec", + "ttf-parser", +] + +[[package]] +name = "foreign-types" +version = "0.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d737d9aa519fb7b749cbc3b962edcf310a8dd1f4b67c91c4f83975dbdd17d965" +dependencies = [ + "foreign-types-macros", + "foreign-types-shared", +] + +[[package]] +name = "foreign-types-macros" +version = "0.2.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ea5190182e6915eb873ddbc16e23b711b6eb1f9c00a0d0a3a91b5f6228475225" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.9", +] + +[[package]] +name = "foreign-types-shared" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "aa9a19cbb55df58761df49b23516a86d432839add4af60fc256da840f66ed35b" + +[[package]] +name = "form_urlencoded" +version = "1.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cb4cb245038516f5f85277875cdaa4f7d2c9a0fa0468de06ed190163b1581fcf" +dependencies = [ + "percent-encoding", +] + +[[package]] +name = "fs_extra" +version = "1.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "42703706b716c37f96a77aea830392ad231f44c9e9a67872fa5548707e11b11c" + +[[package]] +name = "futures" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9a31d2a3fbaaeb2af2368bbdd904aa8e812d3c04a1ee10d3171f52d556e5d0a3" +dependencies = [ + "futures-channel", + "futures-core", + "futures-executor", + "futures-io", + "futures-sink", + "futures-task", + "futures-util", +] + +[[package]] +name = "futures-channel" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b1f9e3d69d39e4862ffed03ed071a76f9a13ba1d9109d355b0f0aa6b15e393c4" +dependencies = [ + "futures-core", + "futures-sink", +] + +[[package]] +name = "futures-core" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "92d699e522242e69e3003b94ecc1f960f3a5e015aa7c5d7486e65ad01dd94f5e" + +[[package]] +name = "futures-executor" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "031b47cf1a3c6cc8bc2fc76cd437f521619387907d469316e7c0bc278f1f5432" +dependencies = [ + "futures-core", + "futures-task", + "futures-util", +] + +[[package]] +name = "futures-io" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "53c0fa8157de1303bfffdaa1cc2a673bfffb60102f76b0ef4441659124373fed" + +[[package]] +name = "futures-lite" +version = "2.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f78e10609fe0e0b3f4157ffab1876319b5b0db102a2c60dc4626306dc46b44ad" +dependencies = [ + "fastrand", + "futures-core", + "futures-io", + "parking", + "pin-project-lite", +] + +[[package]] +name = "futures-macro" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9fb9654ba8355388abeb8dcb4fc62f511300867002afc858860463bdd9fe0c44" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.9", +] + +[[package]] +name = "futures-sink" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1944426bf7d03f1d14f708785e4b33efd750b36d48a157b836b3efc15ede8e1d" + +[[package]] +name = "futures-task" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cd417de3d1d015fc3bfd2b1ea46dfc7bab72ef86f1cc7cc9c78e728b34a6d1fd" + +[[package]] +name = "futures-timer" +version = "3.0.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "af43fadb8a98512d547e37b4e92e0ced13e205c061b87b4623eff01d918d6968" +dependencies = [ + "gloo-timers", + "send_wrapper", +] + +[[package]] +name = "futures-util" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0d50a92467f8ba5dd6e3ee5d4bd04d73ab2e4e1c44474a0674821dfce14b79bc" +dependencies = [ + "futures-channel", + "futures-core", + "futures-io", + "futures-macro", + "futures-sink", + "futures-task", + "memchr", + "pin-project-lite", + "slab", +] + +[[package]] +name = "generic-array" +version = "0.14.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a" +dependencies = [ + "typenum", + "version_check", +] + +[[package]] +name = "gethostname" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1bd49230192a3797a9a4d6abe9b3eed6f7fa4c8a8a4947977c6f80025f92cbd8" +dependencies = [ + "rustix 1.1.6", + "windows-link", +] + +[[package]] +name = "getrandom" +version = "0.2.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0" +dependencies = [ + "cfg-if", + "js-sys", + "libc", + "wasi", + "wasm-bindgen", +] + +[[package]] +name = "getrandom" +version = "0.3.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd" +dependencies = [ + "cfg-if", + "libc", + "r-efi 5.3.0", + "wasip2", +] + +[[package]] +name = "getrandom" +version = "0.4.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099" +dependencies = [ + "cfg-if", + "js-sys", + "libc", + "r-efi 6.0.0", + "rand_core 0.10.1", + "wasm-bindgen", +] + +[[package]] +name = "gif" +version = "0.13.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4ae047235e33e2829703574b54fdec96bfbad892062d97fed2f76022287de61b" +dependencies = [ + "color_quant", + "weezl", +] + +[[package]] +name = "gl_generator" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1a95dfc23a2b4a9a2f5ab41d194f8bfda3cabec42af4e39f08c339eb2a0c124d" +dependencies = [ + "khronos_api", + "log", + "xml-rs", +] + +[[package]] +name = "glam" +version = "0.25.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "151665d9be52f9bb40fc7966565d39666f2d1e69233571b71b87791c7e0528b3" + +[[package]] +name = "glob" +version = "0.3.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e4eba85ea1d0a966a983acd07deee566e67395d2d96b6fb39e62b5a833f1eb0b" + +[[package]] +name = "gloo-timers" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "482ce8a491a501da4cd806bd190275363d674f2845005c6ddbd5d3e1dd54495d" +dependencies = [ + "futures-channel", + "futures-core", + "js-sys", + "wasm-bindgen", +] + +[[package]] +name = "glow" +version = "0.16.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c5e5ea60d70410161c8bf5da3fdfeaa1c72ed2c15f8bbb9d19fe3a4fad085f08" +dependencies = [ + "js-sys", + "slotmap", + "wasm-bindgen", + "web-sys", +] + +[[package]] +name = "glutin_wgl_sys" +version = "0.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2c4ee00b289aba7a9e5306d57c2d05499b2e5dc427f84ac708bd2c090212cf3e" +dependencies = [ + "gl_generator", +] + +[[package]] +name = "gpu-alloc" +version = "0.6.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "45cf04b2726f02df5508c6de726acdc90cdf97ac771a9a0ffd8ba10a6e696bf9" +dependencies = [ + "bitflags 2.13.2", + "gpu-alloc-types", +] + +[[package]] +name = "gpu-alloc-types" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b2bbed164dd10ed526c2e4fe3e721ca4a71c61730e5aafac6844b417b3227058" +dependencies = [ + "bitflags 2.13.2", +] + +[[package]] +name = "gpu-allocator" +version = "0.27.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c151a2a5ef800297b4e79efa4f4bec035c5f51d5ae587287c9b952bdf734cacd" +dependencies = [ + "log", + "presser", + "thiserror 1.0.69", + "windows 0.58.0", +] + +[[package]] +name = "gpu-descriptor" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b89c83349105e3732062a895becfc71a8f921bb71ecbbdd8ff99263e3b53a0ca" +dependencies = [ + "bitflags 2.13.2", + "gpu-descriptor-types", + "hashbrown 0.15.5", +] + +[[package]] +name = "gpu-descriptor-types" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fdf242682df893b86f33a73828fb09ca4b2d3bb6cc95249707fc684d27484b91" +dependencies = [ + "bitflags 2.13.2", +] + +[[package]] +name = "guillotiere" +version = "0.6.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b62d5865c036cb1393e23c50693df631d3f5d7bcca4c04fe4cc0fd592e74a782" +dependencies = [ + "euclid", + "svg_fmt", +] + +[[package]] +name = "h2" +version = "0.4.20" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7d29020232d6aa3fb1daca64c1127cf662cf97f254ae16c18c05b8ab635fc118" +dependencies = [ + "atomic-waker", + "bytes", + "fnv", + "futures-core", + "futures-sink", + "http", + "indexmap", + "slab", + "tokio", + "tokio-util", + "tracing", +] + +[[package]] +name = "half" +version = "2.7.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6ea2d84b969582b4b1864a92dc5d27cd2b77b622a8d79306834f1be5ba20d84b" +dependencies = [ + "cfg-if", + "crunchy", + "num-traits", + "zerocopy", +] + +[[package]] +name = "harfrust" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "92c020db12c71d8a12a3fe7607873cade3a01a6287e29d540c8723276221b9d8" +dependencies = [ + "bitflags 2.13.2", + "bytemuck", + "core_maths", + "read-fonts 0.35.0", + "smallvec", +] + +[[package]] +name = "hashbrown" +version = "0.15.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9229cfe53dfd69f0609a49f65461bd93001ea1ef889cd5529dd176593f5338a1" +dependencies = [ + "foldhash 0.1.5", +] + +[[package]] +name = "hashbrown" +version = "0.16.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "841d1cc9bed7f9236f321df977030373f4a4163ae1a7dbfe1a51a2c1a51d9100" +dependencies = [ + "foldhash 0.2.0", +] + +[[package]] +name = "hashbrown" +version = "0.17.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a" + +[[package]] +name = "hermit-abi" +version = "0.5.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e17592d60ebacc7d5e169f4663c5f84f9161cc90328abcfe8456f41e4dfcb284" + +[[package]] +name = "hex" +version = "0.4.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7f24254aa9a54b5c858eaee2f5bccdb46aaf0e486a595ed5fd8f86ba55232a70" + +[[package]] +name = "hexf-parse" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dfa686283ad6dd069f105e5ab091b04c62850d3e4cf5d67debad1933f55023df" + +[[package]] +name = "http" +version = "1.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "918d3568bebf352712bc2ef3d46a8bcf1a75b373be6539de198e9105cbbf9ce0" +dependencies = [ + "bytes", + "itoa", +] + +[[package]] +name = "http-body" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ca2a8f2913ee65f60facd6a5905613afaa448497a0230cc41ce022d93290bc2c" +dependencies = [ + "bytes", + "http", +] + +[[package]] +name = "http-body-util" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "23169fe34a5fbcdd3f3862e78fb9b6fccd5f02a6dc6f732547005d45631ce71c" +dependencies = [ + "bytes", + "futures-core", + "http", + "http-body", + "pin-project-lite", +] + +[[package]] +name = "httparse" +version = "1.10.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6dbf3de79e51f3d586ab4cb9d5c3e2c14aa28ed23d180cf89b4df0454a69cc87" + +[[package]] +name = "httpdate" +version = "1.0.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9" + +[[package]] +name = "hyper" +version = "1.12.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2c3e324da4c95177d6291d4c8730197c0d1822f8a9766814a4a44fa5ab797c9c" +dependencies = [ + "atomic-waker", + "bytes", + "futures-channel", + "futures-core", + "h2", + "http", + "http-body", + "httparse", + "httpdate", + "itoa", + "pin-project-lite", + "smallvec", + "tokio", + "want", +] + +[[package]] +name = "hyper-rustls" +version = "0.27.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dfa8e654703247911e29c23fbeaa261834bd9bb74efba2f9acddc37bfb127f53" +dependencies = [ + "http", + "hyper", + "hyper-util", + "rustls", + "tokio", + "tokio-rustls", + "tower-service", + "webpki-roots 1.0.11", +] + +[[package]] +name = "hyper-util" +version = "0.1.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ddc03d96684f9226b8a787cdb71488417b53ab5ea8fdb1dac946cb9431cc8bff" +dependencies = [ + "base64 0.23.1", + "bytes", + "futures-channel", + "futures-util", + "http", + "http-body", + "httparse", + "hyper", + "ipnet", + "libc", + "percent-encoding", + "pin-project-lite", + "socket2", + "system-configuration", + "tokio", + "tower-service", + "tracing", + "windows-registry", +] + +[[package]] +name = "iana-time-zone" +version = "0.1.65" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e31bc9ad994ba00e440a8aa5c9ef0ec67d5cb5e5cb0cc7f8b744a35b389cc470" +dependencies = [ + "android_system_properties", + "core-foundation-sys", + "iana-time-zone-haiku", + "js-sys", + "log", + "wasm-bindgen", + "windows-core 0.62.2", +] + +[[package]] +name = "iana-time-zone-haiku" +version = "0.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f31827a206f56af32e590ba56d5d2d085f558508192593743f16b2306495269f" +dependencies = [ + "cc", +] + +[[package]] +name = "iced" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "000e01026c93ba643f8357a3db3ada0e6555265a377f6f9291c472f6dd701fb3" +dependencies = [ + "iced_core", + "iced_debug", + "iced_futures", + "iced_renderer", + "iced_runtime", + "iced_widget", + "iced_winit", + "image", + "thiserror 2.0.21", +] + +[[package]] +name = "iced_core" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "91ab1937d699403e7e69252ae743a902bcee9f4ab2052cc4c9a46fcf34729d85" +dependencies = [ + "bitflags 2.13.2", + "bytes", + "glam", + "lilt", + "log", + "num-traits", + "rustc-hash 2.1.3", + "smol_str", + "thiserror 2.0.21", + "web-time", +] + +[[package]] +name = "iced_debug" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "25035ab0215a620e53f4103e36fc4e59a1fb2817e4bfc38a30ad27b4202ea0be" +dependencies = [ + "iced_core", + "iced_futures", + "log", +] + +[[package]] +name = "iced_futures" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8c0c85ccad42dfbec7293c36c018af0ea0dbcc52d137a4a9a0b0f6822a3fdf0a" +dependencies = [ + "futures", + "iced_core", + "log", + "rustc-hash 2.1.3", + "wasm-bindgen-futures", + "wasmtimer", +] + +[[package]] +name = "iced_graphics" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "234ca1c2cec4155055f68fa5fad1b5242c496ac8238d80a259bca382fb44a102" +dependencies = [ + "bitflags 2.13.2", + "bytemuck", + "cosmic-text", + "half", + "iced_core", + "iced_futures", + "image", + "kamadak-exif", + "log", + "raw-window-handle", + "rustc-hash 2.1.3", + "thiserror 2.0.21", + "unicode-segmentation", +] + +[[package]] +name = "iced_program" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6dfafec2947cda688d8eb00dac337ba11aa60f9ef6335aed343e189d26e4a673" +dependencies = [ + "iced_graphics", + "iced_runtime", +] + +[[package]] +name = "iced_renderer" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "250cc0802408e8c077986ec56c7d07c65f423ee658a4b9fd795a1f2aae5dac05" +dependencies = [ + "iced_graphics", + "iced_tiny_skia", + "iced_wgpu", + "log", + "thiserror 2.0.21", +] + +[[package]] +name = "iced_runtime" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d1889b819ce4c06674183242e336c8d49465665441396914dc07cc86f44fa8d4" +dependencies = [ + "bytes", + "iced_core", + "iced_futures", + "raw-window-handle", + "thiserror 2.0.21", +] + +[[package]] +name = "iced_tiny_skia" +version = "0.14.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c267596d742714b1853cc10c3983a367762816fc4836bd3b79f76ce76787d6f8" +dependencies = [ + "bytemuck", + "cosmic-text", + "iced_debug", + "iced_graphics", + "kurbo 0.10.4", + "log", + "resvg", + "rustc-hash 2.1.3", + "softbuffer", + "tiny-skia", +] + +[[package]] +name = "iced_wgpu" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ff144a999b0ca0f8a10257934500060240825c42e950ec0ebee9c8ae30561c13" +dependencies = [ + "bitflags 2.13.2", + "bytemuck", + "cryoglyph", + "futures", + "glam", + "guillotiere", + "iced_debug", + "iced_graphics", + "log", + "resvg", + "rustc-hash 2.1.3", + "thiserror 2.0.21", + "wgpu", +] + +[[package]] +name = "iced_widget" +version = "0.14.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b1596afa0d3109c2618e8bc12bae6c11d3064df8f95c42dfce570397dbe957ab" +dependencies = [ + "iced_renderer", + "log", + "num-traits", + "rustc-hash 2.1.3", + "thiserror 2.0.21", + "unicode-segmentation", +] + +[[package]] +name = "iced_winit" +version = "0.14.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7589888c8e951899cc688247a69933bb7a0511f0b4b2e122ac3fcd5dacb37f72" +dependencies = [ + "iced_debug", + "iced_program", + "log", + "mundy", + "rustc-hash 2.1.3", + "thiserror 2.0.21", + "tracing", + "wasm-bindgen-futures", + "web-sys", + "window_clipboard", + "winit", +] + +[[package]] +name = "icu_collections" +version = "2.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fe090a42a0d3140fed8c63263ed1fecc02422cb2f4bfe55cd8de2de1b8e105dd" +dependencies = [ + "displaydoc", + "potential_utf", + "utf8_iter", + "yoke", + "zerofrom", + "zerovec", +] + +[[package]] +name = "icu_locale_core" +version = "2.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "25d29b57c17c6528d0dc4c2141cfa2d08200465acb537a3909c8b9b8a4a984c0" +dependencies = [ + "displaydoc", + "litemap", + "tinystr", + "writeable", + "zerovec", +] + +[[package]] +name = "icu_normalizer" +version = "2.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "404a3b8c486f205c87fe7f23ab6894d84a4ad76d6e4671ae1981ba7def87c599" +dependencies = [ + "icu_collections", + "icu_normalizer_data", + "icu_properties", + "icu_provider", + "smallvec", + "zerovec", +] + +[[package]] +name = "icu_normalizer_data" +version = "2.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "20f0088bfb7441f7a37fa0c9e20cb1e9cba1cac6b9ce8cd2a6dc44294f8e8cbc" + +[[package]] +name = "icu_properties" +version = "2.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2ea83d991c56158f7cf898bf86436c1dfe7c07ee82fe88951f2695c9f37a379f" +dependencies = [ + "displaydoc", + "icu_collections", + "icu_locale_core", + "icu_properties_data", + "icu_provider", + "zerotrie", + "zerovec", +] + +[[package]] +name = "icu_properties_data" +version = "2.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b98f29af82d02b163fe50161388350e743bb3107cc8e8c2f7314cb505faddfcf" + +[[package]] +name = "icu_provider" +version = "2.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "413099315636c588ee8f011190b329b971a09a8fae9d157e01dcae8379468514" +dependencies = [ + "displaydoc", + "icu_locale_core", + "writeable", + "yoke", + "zerofrom", + "zerotrie", + "zerovec", +] + +[[package]] +name = "ident_case" +version = "1.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b9e0384b61958566e926dc50660321d12159025e767c18e043daf26b70104c39" + +[[package]] +name = "idna" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3b0875f23caa03898994f6ddc501886a45c7d3d62d04d2d90788d47be1b1e4de" +dependencies = [ + "idna_adapter", + "smallvec", + "utf8_iter", +] + +[[package]] +name = "idna_adapter" +version = "1.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cb68373c0d6620ef8105e855e7745e18b0d00d3bdb07fb532e434244cdb9a714" +dependencies = [ + "icu_normalizer", + "icu_properties", +] + +[[package]] +name = "image" +version = "0.25.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "85ab80394333c02fe689eaf900ab500fbd0c2213da414687ebf995a65d5a6104" +dependencies = [ + "bytemuck", + "byteorder-lite", + "moxcms", + "num-traits", + "png 0.18.1", + "zune-core 0.5.3", + "zune-jpeg 0.5.15", +] + +[[package]] +name = "image-webp" +version = "0.2.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "525e9ff3e1a4be2fbea1fdf0e98686a6d98b4d8f937e1bf7402245af1909e8c3" +dependencies = [ + "byteorder-lite", + "quick-error", +] + +[[package]] +name = "imagesize" +version = "0.13.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "edcd27d72f2f071c64249075f42e205ff93c9a4c5f6c6da53e79ed9f9832c285" + +[[package]] +name = "indexmap" +version = "2.14.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cc4e190f5d26ca7051642629da2c52fc03bde85a03197c99408dcd291734c855" +dependencies = [ + "equivalent", + "hashbrown 0.17.1", + "serde", + "serde_core", +] + +[[package]] +name = "ipnet" +version = "2.12.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "791930b43c0d5973160d90a8f3894509f2b273430f5c5c73b668636d0287c5c0" + +[[package]] +name = "itoa" +version = "1.0.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682" + +[[package]] +name = "jni" +version = "0.22.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5efd9a482cf3a427f00d6b35f14332adc7902ce91efb778580e180ff90fa3498" +dependencies = [ + "cfg-if", + "combine", + "jni-macros", + "jni-sys 0.4.1", + "log", + "simd_cesu8", + "thiserror 2.0.21", + "walkdir", + "windows-link", +] + +[[package]] +name = "jni-macros" +version = "0.22.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a00109accc170f0bdb141fed3e393c565b6f5e072365c3bd58f5b062591560a3" +dependencies = [ + "proc-macro2", + "quote", + "rustc_version", + "simd_cesu8", + "syn 2.0.119", +] + +[[package]] +name = "jni-sys" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "41a652e1f9b6e0275df1f15b32661cf0d4b78d4d87ddec5e0c3c20f097433258" +dependencies = [ + "jni-sys 0.4.1", +] + +[[package]] +name = "jni-sys" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c6377a88cb3910bee9b0fa88d4f42e1d2da8e79915598f65fb0c7ee14c878af2" +dependencies = [ + "jni-sys-macros", +] + +[[package]] +name = "jni-sys-macros" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "38c0b942f458fe50cdac086d2f946512305e5631e720728f2a61aabcd47a6264" +dependencies = [ + "quote", + "syn 2.0.119", +] + +[[package]] +name = "jobserver" +version = "0.1.35" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1c00acbd29eabad4a2392fa0e921c874934dbbf4194312ad20f04a0ed67a3cb3" +dependencies = [ + "getrandom 0.4.3", + "libc", +] + +[[package]] +name = "js-sys" +version = "0.3.106" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7883d941dae510fb2d978fc3fe018c71c9e2892fd38854de3e8b92c2e5ad9cc5" +dependencies = [ + "cfg-if", + "futures-util", + "wasm-bindgen", +] + +[[package]] +name = "kamadak-exif" +version = "0.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1130d80c7374efad55a117d715a3af9368f0fa7a2c54573afc15a188cd984837" +dependencies = [ + "mutate_once", +] + +[[package]] +name = "khronos-egl" +version = "6.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6aae1df220ece3c0ada96b8153459b67eebe9ae9212258bb0134ae60416fdf76" +dependencies = [ + "libc", + "libloading", + "pkg-config", +] + +[[package]] +name = "khronos_api" +version = "3.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e2db585e1d738fc771bf08a151420d3ed193d9d895a36df7f6f8a9456b911ddc" + +[[package]] +name = "kurbo" +version = "0.10.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1618d4ebd923e97d67e7cd363d80aef35fe961005cbbbb3d2dad8bdd1bc63440" +dependencies = [ + "arrayvec", + "smallvec", +] + +[[package]] +name = "kurbo" +version = "0.11.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c62026ae44756f8a599ba21140f350303d4f08dcdcc71b5ad9c9bb8128c13c62" +dependencies = [ + "arrayvec", + "euclid", + "smallvec", +] + +[[package]] +name = "libc" +version = "0.2.191" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a" + +[[package]] +name = "libloading" +version = "0.8.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d7c4b02199fee7c5d21a5ae7d8cfa79a6ef5bb2fc834d6e9058e89c825efdc55" +dependencies = [ + "cfg-if", + "windows-link", +] + +[[package]] +name = "libm" +version = "0.2.16" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b6d2cec3eae94f9f509c767b45932f1ada8350c4bdb85af2fcab4a3c14807981" + +[[package]] +name = "libredox" +version = "0.1.25" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "61ff90caf6077a803a240f62fdbe88645a890bbca49ef8174c3cb0404362171d" +dependencies = [ + "bitflags 2.13.2", + "libc", + "plain", + "redox_syscall 0.9.5", +] + +[[package]] +name = "lilt" +version = "0.8.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "337d4c256f7d9f2dbd633891d48ace853efa5b1554122d9220b172ad9c03c3a9" +dependencies = [ + "web-time", +] + +[[package]] +name = "linebender_resource_handle" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d4a5ff6bcca6c4867b1c4fd4ef63e4db7436ef363e0ad7531d1558856bae64f4" + +[[package]] +name = "linux-raw-sys" +version = "0.4.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d26c52dbd32dccf2d10cac7725f8eae5296885fb5703b261f7d0a0739ec807ab" + +[[package]] +name = "linux-raw-sys" +version = "0.12.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53" + +[[package]] +name = "litemap" +version = "0.8.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "47d9d19d1d6efa0109d2f65ff4c85cddd50bd572e5a00127ab10987290bcefae" + +[[package]] +name = "litrs" +version = "1.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4744e383959f0db86ede514b809b1c53251889093803c05267acc7d4e7030d70" + +[[package]] +name = "lock_api" +version = "0.4.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "224399e74b87b5f3557511d98dff8b14089b3dadafcab6bb93eab67d3aace965" +dependencies = [ + "scopeguard", +] + +[[package]] +name = "log" +version = "0.4.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f9f8bd3e56ce4dfc153cf470fffbfa98c7620958b312ca5c3a4b8d5181fd13c6" + +[[package]] +name = "lru" +version = "0.16.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7f66e8d5d03f609abc3a39e6f08e4164ebf1447a732906d39eb9b99b7919ef39" + +[[package]] +name = "lru-slab" +version = "0.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4050469837a6ff301cd14c1f8f24f88549e6d548f24f64e2148eb0f72cebc51f" + +[[package]] +name = "malloc_buf" +version = "0.0.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "62bb907fe88d54d8d9ce32a3cceab4218ed2f6b7d35617cafe9adf84e43919cb" +dependencies = [ + "libc", +] + +[[package]] +name = "matchit" +version = "0.8.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "47e1ffaa40ddd1f3ed91f717a33c8c0ee23fff369e3aa8772b9605cc1d22f4c3" + +[[package]] +name = "md-5" +version = "0.10.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d89e7ee0cfbedfc4da3340218492196241d89eefb6dab27de5df917a6d2e78cf" +dependencies = [ + "cfg-if", + "digest", +] + +[[package]] +name = "memchr" +version = "2.8.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98" + +[[package]] +name = "memmap2" +version = "0.9.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6b0ca1155a9ecc25aa12e8313a119f32edf0255fea2f44839c4ac0a12b2ac157" +dependencies = [ + "libc", +] + +[[package]] +name = "memoffset" +version = "0.9.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "488016bfae457b036d996092f6cb448677611ce4449e970ceaf42695203f218a" +dependencies = [ + "autocfg", +] + +[[package]] +name = "metal" +version = "0.32.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "00c15a6f673ff72ddcc22394663290f870fb224c1bfce55734a75c414150e605" +dependencies = [ + "bitflags 2.13.2", + "block", + "core-graphics-types 0.2.0", + "foreign-types", + "log", + "objc", + "paste", +] + +[[package]] +name = "mime" +version = "0.3.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6877bb514081ee2a7ff5ef9de3281f14a4dd4bceac4c09388074a6b5df8a139a" + +[[package]] +name = "mime_guess" +version = "2.0.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f7c44f8e672c00fe5308fa235f821cb4198414e1c77935c1ab6948d3fd78550e" +dependencies = [ + "mime", + "unicase", +] + +[[package]] +name = "miniz_oxide" +version = "0.8.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1fa76a2c86f704bdb222d66965fb3d63269ce38518b83cb0575fca855ebb6316" +dependencies = [ + "adler2", + "simd-adler32", +] + +[[package]] +name = "miniz_oxide" +version = "0.9.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b63fbc4a50860e98e7b2aa7804ded1db5cbc3aff9193adaff57a6931bf7c4b4c" +dependencies = [ + "adler2", + "simd-adler32", +] + +[[package]] +name = "mio" +version = "1.2.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1788edb87fdc09c7e26304471e2f5be8cdefb1b6930d6e3985fc02ff53bf86ee" +dependencies = [ + "libc", + "wasi", + "windows-sys 0.61.2", +] + +[[package]] +name = "moxcms" +version = "0.8.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bb85c154ba489f01b25c0d36ae69a87e4a1c73a72631fc6c0eb6dde34a73e44b" +dependencies = [ + "num-traits", + "pxfm", +] + +[[package]] +name = "multiversion_no_op" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "743fb55ba31b18fb1ecef6bdc9aa2743314978ac084044301a7eee33fb99a20d" + +[[package]] +name = "mundy" +version = "0.2.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f32eb0db40f2df2bcfb05c93b8f73938d4c26ce9ac8881f1df0c8d3296921a73" +dependencies = [ + "android-build", + "async-io", + "cfg-if", + "dispatch", + "futures-channel", + "futures-lite", + "jni", + "ndk-context", + "objc2 0.6.5", + "objc2-app-kit 0.3.2", + "objc2-foundation 0.3.2", + "pin-project-lite", + "wasm-bindgen", + "wasm-bindgen-futures", + "web-sys", + "windows 0.62.2", + "zbus", +] + +[[package]] +name = "mutate_once" +version = "0.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "13d2233c9842d08cfe13f9eac96e207ca6a2ea10b80259ebe8ad0268be27d2af" + +[[package]] +name = "naga" +version = "27.0.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "066cf25f0e8b11ee0df221219010f213ad429855f57c494f995590c861a9a7d8" +dependencies = [ + "arrayvec", + "bit-set", + "bitflags 2.13.2", + "cfg-if", + "cfg_aliases", + "codespan-reporting", + "half", + "hashbrown 0.16.1", + "hexf-parse", + "indexmap", + "libm", + "log", + "num-traits", + "once_cell", + "rustc-hash 1.1.0", + "spirv", + "thiserror 2.0.21", + "unicode-ident", +] + +[[package]] +name = "ndk" +version = "0.9.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c3f42e7bbe13d351b6bead8286a43aac9534b82bd3cc43e47037f012ebfd62d4" +dependencies = [ + "bitflags 2.13.2", + "jni-sys 0.3.1", + "log", + "ndk-sys", + "num_enum", + "raw-window-handle", + "thiserror 1.0.69", +] + +[[package]] +name = "ndk-context" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "27b02d87554356db9e9a873add8782d4ea6e3e58ea071a9adb9a2e8ddb884a8b" + +[[package]] +name = "ndk-sys" +version = "0.6.0+11769913" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ee6cda3051665f1fb8d9e08fc35c96d5a244fb1be711a03b71118828afc9a873" +dependencies = [ + "jni-sys 0.3.1", +] + +[[package]] +name = "nix" +version = "0.31.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf20d2fde8ff38632c426f1165ed7436270b44f199fc55284c38276f9db47c3d" +dependencies = [ + "bitflags 2.13.2", + "cfg-if", + "cfg_aliases", + "libc", +] + +[[package]] +name = "num-traits" +version = "0.2.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841" +dependencies = [ + "autocfg", + "libm", +] + +[[package]] +name = "num_enum" +version = "0.7.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5d0bca838442ec211fa11de3a8b0e0e8f3a4522575b5c4c06ed722e005036f26" +dependencies = [ + "num_enum_derive", + "rustversion", +] + +[[package]] +name = "num_enum_derive" +version = "0.7.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "680998035259dcfcafe653688bf2aa6d3e2dc05e98be6ab46afb089dc84f1df8" +dependencies = [ + "proc-macro-crate", + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "objc" +version = "0.2.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "915b1b472bc21c53464d6c8461c9d3af805ba1ef837e1cac254428f4a77177b1" +dependencies = [ + "malloc_buf", +] + +[[package]] +name = "objc-sys" +version = "0.3.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cdb91bdd390c7ce1a8607f35f3ca7151b65afc0ff5ff3b34fa350f7d7c7e4310" + +[[package]] +name = "objc2" +version = "0.5.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "19d5490aaf8f1d7cf7688dfa9b0ce07900e168852c45cd2c03f534dfd27cfd0b" +dependencies = [ + "objc-sys", + "objc2-encode", +] + +[[package]] +name = "objc2" +version = "0.6.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "08849bbd4767dfae9457696856ae1c84fe4e0281bbe4a7abff2d0e06fb7981f8" +dependencies = [ + "objc2-encode", +] + +[[package]] +name = "objc2-app-kit" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e4e89ad9e3d7d297152b17d39ed92cd50ca8063a89a9fa569046d41568891eff" +dependencies = [ + "bitflags 2.13.2", + "block2 0.5.1", + "libc", + "objc2 0.5.3", + "objc2-core-data 0.2.2", + "objc2-core-image 0.2.2", + "objc2-foundation 0.2.2", + "objc2-quartz-core 0.2.2", +] + +[[package]] +name = "objc2-app-kit" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d49e936b501e5c5bf01fda3a9452ff86dc3ea98ad5f283e1455153142d97518c" +dependencies = [ + "bitflags 2.13.2", + "block2 0.6.2", + "libc", + "objc2 0.6.5", + "objc2-cloud-kit 0.3.2", + "objc2-core-data 0.3.2", + "objc2-core-foundation", + "objc2-core-graphics", + "objc2-core-image 0.3.2", + "objc2-core-text", + "objc2-core-video", + "objc2-foundation 0.3.2", + "objc2-quartz-core 0.3.2", +] + +[[package]] +name = "objc2-cloud-kit" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "74dd3b56391c7a0596a295029734d3c1c5e7e510a4cb30245f8221ccea96b009" +dependencies = [ + "bitflags 2.13.2", + "block2 0.5.1", + "objc2 0.5.3", + "objc2-core-location", + "objc2-foundation 0.2.2", +] + +[[package]] +name = "objc2-cloud-kit" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "73ad74d880bb43877038da939b7427bba67e9dd42004a18b809ba7d87cee241c" +dependencies = [ + "bitflags 2.13.2", + "objc2 0.6.5", + "objc2-foundation 0.3.2", +] + +[[package]] +name = "objc2-contacts" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a5ff520e9c33812fd374d8deecef01d4a840e7b41862d849513de77e44aa4889" +dependencies = [ + "block2 0.5.1", + "objc2 0.5.3", + "objc2-foundation 0.2.2", +] + +[[package]] +name = "objc2-core-data" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "617fbf49e071c178c0b24c080767db52958f716d9eabdf0890523aeae54773ef" +dependencies = [ + "bitflags 2.13.2", + "block2 0.5.1", + "objc2 0.5.3", + "objc2-foundation 0.2.2", +] + +[[package]] +name = "objc2-core-data" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0b402a653efbb5e82ce4df10683b6b28027616a2715e90009947d50b8dd298fa" +dependencies = [ + "bitflags 2.13.2", + "objc2 0.6.5", + "objc2-foundation 0.3.2", +] + +[[package]] +name = "objc2-core-foundation" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2a180dd8642fa45cdb7dd721cd4c11b1cadd4929ce112ebd8b9f5803cc79d536" +dependencies = [ + "bitflags 2.13.2", + "dispatch2", + "objc2 0.6.5", +] + +[[package]] +name = "objc2-core-graphics" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e022c9d066895efa1345f8e33e584b9f958da2fd4cd116792e15e07e4720a807" +dependencies = [ + "bitflags 2.13.2", + "dispatch2", + "objc2 0.6.5", + "objc2-core-foundation", + "objc2-io-surface", +] + +[[package]] +name = "objc2-core-image" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "55260963a527c99f1819c4f8e3b47fe04f9650694ef348ffd2227e8196d34c80" +dependencies = [ + "block2 0.5.1", + "objc2 0.5.3", + "objc2-foundation 0.2.2", + "objc2-metal", +] + +[[package]] +name = "objc2-core-image" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e5d563b38d2b97209f8e861173de434bd0214cf020e3423a52624cd1d989f006" +dependencies = [ + "objc2 0.6.5", + "objc2-foundation 0.3.2", +] + +[[package]] +name = "objc2-core-location" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "000cfee34e683244f284252ee206a27953279d370e309649dc3ee317b37e5781" +dependencies = [ + "block2 0.5.1", + "objc2 0.5.3", + "objc2-contacts", + "objc2-foundation 0.2.2", +] + +[[package]] +name = "objc2-core-text" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0cde0dfb48d25d2b4862161a4d5fcc0e3c24367869ad306b0c9ec0073bfed92d" +dependencies = [ + "bitflags 2.13.2", + "objc2 0.6.5", + "objc2-core-foundation", + "objc2-core-graphics", +] + +[[package]] +name = "objc2-core-video" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d425caf1df73233f29fd8a5c3e5edbc30d2d4307870f802d18f00d83dc5141a6" +dependencies = [ + "bitflags 2.13.2", + "objc2 0.6.5", + "objc2-core-foundation", + "objc2-core-graphics", + "objc2-io-surface", +] + +[[package]] +name = "objc2-encode" +version = "4.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ef25abbcd74fb2609453eb695bd2f860d389e457f67dc17cafc8b8cbc89d0c33" + +[[package]] +name = "objc2-foundation" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0ee638a5da3799329310ad4cfa62fbf045d5f56e3ef5ba4149e7452dcf89d5a8" +dependencies = [ + "bitflags 2.13.2", + "block2 0.5.1", + "dispatch", + "libc", + "objc2 0.5.3", +] + +[[package]] +name = "objc2-foundation" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e3e0adef53c21f888deb4fa59fc59f7eb17404926ee8a6f59f5df0fd7f9f3272" +dependencies = [ + "bitflags 2.13.2", + "block2 0.6.2", + "libc", + "objc2 0.6.5", + "objc2-core-foundation", +] + +[[package]] +name = "objc2-io-surface" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "180788110936d59bab6bd83b6060ffdfffb3b922ba1396b312ae795e1de9d81d" +dependencies = [ + "bitflags 2.13.2", + "objc2 0.6.5", + "objc2-core-foundation", +] + +[[package]] +name = "objc2-link-presentation" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a1a1ae721c5e35be65f01a03b6d2ac13a54cb4fa70d8a5da293d7b0020261398" +dependencies = [ + "block2 0.5.1", + "objc2 0.5.3", + "objc2-app-kit 0.2.2", + "objc2-foundation 0.2.2", +] + +[[package]] +name = "objc2-metal" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dd0cba1276f6023976a406a14ffa85e1fdd19df6b0f737b063b95f6c8c7aadd6" +dependencies = [ + "bitflags 2.13.2", + "block2 0.5.1", + "objc2 0.5.3", + "objc2-foundation 0.2.2", +] + +[[package]] +name = "objc2-quartz-core" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e42bee7bff906b14b167da2bac5efe6b6a07e6f7c0a21a7308d40c960242dc7a" +dependencies = [ + "bitflags 2.13.2", + "block2 0.5.1", + "objc2 0.5.3", + "objc2-foundation 0.2.2", + "objc2-metal", +] + +[[package]] +name = "objc2-quartz-core" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "96c1358452b371bf9f104e21ec536d37a650eb10f7ee379fff67d2e08d537f1f" +dependencies = [ + "bitflags 2.13.2", + "objc2 0.6.5", + "objc2-core-foundation", + "objc2-foundation 0.3.2", +] + +[[package]] +name = "objc2-symbols" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0a684efe3dec1b305badae1a28f6555f6ddd3bb2c2267896782858d5a78404dc" +dependencies = [ + "objc2 0.5.3", + "objc2-foundation 0.2.2", +] + +[[package]] +name = "objc2-ui-kit" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b8bb46798b20cd6b91cbd113524c490f1686f4c4e8f49502431415f3512e2b6f" +dependencies = [ + "bitflags 2.13.2", + "block2 0.5.1", + "objc2 0.5.3", + "objc2-cloud-kit 0.2.2", + "objc2-core-data 0.2.2", + "objc2-core-image 0.2.2", + "objc2-core-location", + "objc2-foundation 0.2.2", + "objc2-link-presentation", + "objc2-quartz-core 0.2.2", + "objc2-symbols", + "objc2-uniform-type-identifiers", + "objc2-user-notifications", +] + +[[package]] +name = "objc2-uniform-type-identifiers" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "44fa5f9748dbfe1ca6c0b79ad20725a11eca7c2218bceb4b005cb1be26273bfe" +dependencies = [ + "block2 0.5.1", + "objc2 0.5.3", + "objc2-foundation 0.2.2", +] + +[[package]] +name = "objc2-user-notifications" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "76cfcbf642358e8689af64cee815d139339f3ed8ad05103ed5eaf73db8d84cb3" +dependencies = [ + "bitflags 2.13.2", + "block2 0.5.1", + "objc2 0.5.3", + "objc2-core-location", + "objc2-foundation 0.2.2", +] + +[[package]] +name = "once_cell" +version = "1.21.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50" + +[[package]] +name = "openssl-probe" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7e036b411754132fd6b74e94b74e9a13c5cf606fa93d1885c35860d3060820b1" + +[[package]] +name = "orbclient" +version = "0.3.55" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5df339f526ea9a60e371768d50efc2f2508c7203290731565d1f7a6f71d21747" +dependencies = [ + "libc", + "libredox", +] + +[[package]] +name = "ordered-float" +version = "5.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7f59006ce1e204c30956638535b74d317bca99477b9356dfaec54c37f6f600ab" +dependencies = [ + "num-traits", +] + +[[package]] +name = "ordered-stream" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9aa2b01e1d916879f73a53d01d1d6cee68adbb31d6d9177a8cfce093cced1d50" +dependencies = [ + "futures-core", + "pin-project-lite", +] + +[[package]] +name = "owned_ttf_parser" +version = "0.25.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "36820e9051aca1014ddc75770aab4d68bc1e9e632f0f5627c4086bc216fb583b" +dependencies = [ + "ttf-parser", +] + +[[package]] +name = "parking" +version = "2.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f38d5652c16fde515bb1ecef450ab0f6a219d619a7274976324d5e377f7dceba" + +[[package]] +name = "parking_lot" +version = "0.12.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "93857453250e3077bd71ff98b6a65ea6621a19bb0f559a85248955ac12c45a1a" +dependencies = [ + "lock_api", + "parking_lot_core", +] + +[[package]] +name = "parking_lot_core" +version = "0.9.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2621685985a2ebf1c516881c026032ac7deafcda1a2c9b7850dc81e3dfcb64c1" +dependencies = [ + "cfg-if", + "libc", + "redox_syscall 0.5.18", + "smallvec", + "windows-link", +] + +[[package]] +name = "paste" +version = "1.0.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "57c0d7b74b563b49d38dae00a0c37d4d6de9b432382b2892f0574ddcae73fd0a" + +[[package]] +name = "pastey" +version = "0.2.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2ee67f1008b1ba2321834326597b8e186293b049a023cdef258527550b9935b4" + +[[package]] +name = "percent-encoding" +version = "2.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220" + +[[package]] +name = "pico-args" +version = "0.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5be167a7af36ee22fe3115051bc51f6e6c7054c9348e28deb4f49bd6f705a315" + +[[package]] +name = "pin-project" +version = "1.1.13" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2466b2336ed02bcdca6b294417127b90ec92038d1d5c4fbeac971a922e0e0924" +dependencies = [ + "pin-project-internal", +] + +[[package]] +name = "pin-project-internal" +version = "1.1.13" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c96395f0a926bc13b1c17622aaddda1ecb55d49c8f1bf9777e4d877800a43f8b" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "pin-project-lite" +version = "0.2.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd" + +[[package]] +name = "pin-utils" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "13bee6c73da26345c729282832b60b0363cf3dd9f4bfd81d8551b7a1c889a113" + +[[package]] +name = "piper" +version = "0.2.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c835479a4443ded371d6c535cbfd8d31ad92c5d23ae9770a61bc155e4992a3c1" +dependencies = [ + "atomic-waker", + "fastrand", + "futures-io", +] + +[[package]] +name = "pkg-config" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f6b464fbc74e149a392436b17d523f769e057cb6877f6a5c4618bc6f11800548" + +[[package]] +name = "plain" +version = "0.2.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b4596b6d070b27117e987119b4dac604f3c58cfb0b191112e24771b2faeac1a6" + +[[package]] +name = "png" +version = "0.17.16" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "82151a2fc869e011c153adc57cf2789ccb8d9906ce52c0b39a6b5697749d7526" +dependencies = [ + "bitflags 1.3.2", + "crc32fast", + "fdeflate", + "flate2", + "miniz_oxide 0.8.9", +] + +[[package]] +name = "png" +version = "0.18.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "60769b8b31b2a9f263dae2776c37b1b28ae246943cf719eb6946a1db05128a61" +dependencies = [ + "bitflags 2.13.2", + "crc32fast", + "fdeflate", + "flate2", + "miniz_oxide 0.8.9", +] + +[[package]] +name = "polling" +version = "3.11.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5d0e4f59085d47d8241c88ead0f274e8a0cb551f3625263c05eb8dd897c34218" +dependencies = [ + "cfg-if", + "concurrent-queue", + "hermit-abi", + "pin-project-lite", + "rustix 1.1.6", + "windows-sys 0.61.2", +] + +[[package]] +name = "portable-atomic" +version = "1.15.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "05c8b63e8d9609db387f0324918f81d68fe27748f084ef092fb35954d0539a85" + +[[package]] +name = "portable-atomic-util" +version = "0.2.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "10ab3eb7f3becc3a1cbc4f2c6f20267996cfc1a6467a873763411b136a122715" +dependencies = [ + "portable-atomic", +] + +[[package]] +name = "potential_utf" +version = "0.1.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d83eb9bc6d8e5cf568e7a1101d60ee05e81ed50ea106026f3d18deeb046d7661" +dependencies = [ + "zerovec", +] + +[[package]] +name = "ppv-lite86" +version = "0.2.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "85eae3c4ed2f50dcfe72643da4befc30deadb458a9b590d720cde2f2b1e97da9" +dependencies = [ + "zerocopy", +] + +[[package]] +name = "presser" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e8cf8e6a8aa66ce33f63993ffc4ea4271eb5b0530a9002db8455ea6050c77bfa" + +[[package]] +name = "proc-macro-crate" +version = "3.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e67ba7e9b2b56446f1d419b1d807906278ffa1a658a8a5d8a39dcb1f5a78614f" +dependencies = [ + "toml_edit", +] + +[[package]] +name = "proc-macro2" +version = "1.0.107" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "profiling" +version = "1.0.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3d595e54a326bc53c1c197b32d295e14b169e3cfeaa8dc82b529f947fba6bcf5" + +[[package]] +name = "pxfm" +version = "0.1.30" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d55d956fa96f5ec02be2e13af0e20391a5aa83d6a074e3ad368959d0fab299ea" + +[[package]] +name = "quick-error" +version = "2.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a993555f31e5a609f617c12db6250dedcac1b0a85076912c436e6fc9b2c8e6a3" + +[[package]] +name = "quick-xml" +version = "0.41.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e660451e55124f798a69a5af3f49ccfbefbd41910eefd25caf2393e1f3473ec1" +dependencies = [ + "memchr", +] + +[[package]] +name = "quinn" +version = "0.11.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4051e23e9185c255a7e33ef59cdbca87a22d359052eecd22fc6b901fb37d9d11" +dependencies = [ + "bytes", + "cfg_aliases", + "pin-project-lite", + "quinn-proto", + "quinn-udp", + "rustc-hash 2.1.3", + "rustls", + "socket2", + "thiserror 2.0.21", + "tokio", + "tracing", + "web-time", +] + +[[package]] +name = "quinn-proto" +version = "0.11.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0e750cca55fe4f0439a15d0bb529da9651e79993e8e72c61a899a36d462befbe" +dependencies = [ + "aws-lc-rs", + "bytes", + "getrandom 0.4.3", + "lru-slab", + "rand 0.10.3", + "rand_pcg", + "ring", + "rustc-hash 2.1.3", + "rustls", + "rustls-pki-types", + "slab", + "thiserror 2.0.21", + "tinyvec", + "tracing", + "web-time", +] + +[[package]] +name = "quinn-udp" +version = "0.5.16" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "af66907df18639dcf4db56ca65490cabc4b27a97dbadd96f2926cca73298f016" +dependencies = [ + "cfg_aliases", + "libc", + "once_cell", + "socket2", + "tracing", + "windows-sys 0.61.2", +] + +[[package]] +name = "quote" +version = "1.0.47" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001" +dependencies = [ + "proc-macro2", +] + +[[package]] +name = "r-efi" +version = "5.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f" + +[[package]] +name = "r-efi" +version = "6.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf" + +[[package]] +name = "rand" +version = "0.9.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b9ef1d0d795eb7d84685bca4f72f3649f064e6641543d3a8c415898726a57b41" +dependencies = [ + "rand_chacha", + "rand_core 0.9.5", +] + +[[package]] +name = "rand" +version = "0.10.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "65c9fb96cbc91e3478eaae79a69fcd3f1ae4ad052e471fe6732fff548984b4af" +dependencies = [ + "chacha20", + "getrandom 0.4.3", + "rand_core 0.10.1", +] + +[[package]] +name = "rand_chacha" +version = "0.9.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d3022b5f1df60f26e1ffddd6c66e8aa15de382ae63b3a0c1bfc0e4d3e3f325cb" +dependencies = [ + "ppv-lite86", + "rand_core 0.9.5", +] + +[[package]] +name = "rand_core" +version = "0.9.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "76afc826de14238e6e8c374ddcc1fa19e374fd8dd986b0d2af0d02377261d83c" +dependencies = [ + "getrandom 0.3.4", +] + +[[package]] +name = "rand_core" +version = "0.10.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "63b8176103e19a2643978565ca18b50549f6101881c443590420e4dc998a3c69" + +[[package]] +name = "rand_pcg" +version = "0.10.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "caa0f4137e1c0a72f4c651489402276c8e8e1cf081f3b0ba156d2cbeef09e86a" +dependencies = [ + "rand_core 0.10.1", +] + +[[package]] +name = "range-alloc" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ca45419789ae5a7899559e9512e58ca889e41f04f1f2445e9f4b290ceccd1d08" + +[[package]] +name = "rangemap" +version = "1.8.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a611d15b50743feb4c76b7d03edcb0e64f399c26961e4efe6975bc398be6aa3d" + +[[package]] +name = "raw-window-handle" +version = "0.6.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "20675572f6f24e9e76ef639bc5552774ed45f1c30e2951e1e99c59888861c539" + +[[package]] +name = "read-fonts" +version = "0.35.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6717cf23b488adf64b9d711329542ba34de147df262370221940dfabc2c91358" +dependencies = [ + "bytemuck", + "core_maths", + "font-types 0.10.1", +] + +[[package]] +name = "read-fonts" +version = "0.41.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "046a7d674daf459825b32f5062056d6882db0d2f5a479fbd76ccfc870ac18709" +dependencies = [ + "bytemuck", + "font-types 0.12.7", + "once_cell", +] + +[[package]] +name = "redox_syscall" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4722d768eff46b75989dd134e5c353f0d6296e5aaa3132e776cbdb56be7731aa" +dependencies = [ + "bitflags 1.3.2", +] + +[[package]] +name = "redox_syscall" +version = "0.5.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d" +dependencies = [ + "bitflags 2.13.2", +] + +[[package]] +name = "redox_syscall" +version = "0.9.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "580c875845b41ecb1564ad1ae4703044cef774145e3d7a94dc2b3fa7c97868fd" +dependencies = [ + "bitflags 2.13.2", +] + +[[package]] +name = "ref-cast" +version = "1.0.27" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7e440fb4e4b4147295338efb76001ab9e4efc0e5839df2c47fc5ac2381d365c3" +dependencies = [ + "ref-cast-impl", +] + +[[package]] +name = "ref-cast-impl" +version = "1.0.27" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "92ecd8964f8453721699a1ed72037b0db49ce2f5a5138486ee89bed6f67cdf3a" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.9", +] + +[[package]] +name = "regex" +version = "1.13.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d" +dependencies = [ + "aho-corasick", + "memchr", + "regex-automata", + "regex-syntax", +] + +[[package]] +name = "regex-automata" +version = "0.4.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ad8553b9b26413251cbf30e620595c7a41b3887f03da04579c0e6b0d6a06b4b2" +dependencies = [ + "aho-corasick", + "memchr", + "regex-syntax", +] + +[[package]] +name = "regex-syntax" +version = "0.8.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4" + +[[package]] +name = "renderdoc-sys" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "19b30a45b0cd0bcca8037f3d0dc3421eaf95327a17cad11964fb8179b4fc4832" + +[[package]] +name = "reqwest" +version = "0.12.28" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "eddd3ca559203180a307f12d114c268abf583f59b03cb906fd0b3ff8646c1147" +dependencies = [ + "base64 0.22.1", + "bytes", + "futures-core", + "futures-util", + "http", + "http-body", + "http-body-util", + "hyper", + "hyper-rustls", + "hyper-util", + "js-sys", + "log", + "percent-encoding", + "pin-project-lite", + "quinn", + "rustls", + "rustls-pki-types", + "serde", + "serde_json", + "serde_urlencoded", + "sync_wrapper", + "tokio", + "tokio-rustls", + "tokio-util", + "tower", + "tower-http", + "tower-service", + "url", + "wasm-bindgen", + "wasm-bindgen-futures", + "wasm-streams 0.4.2", + "web-sys", + "webpki-roots 1.0.11", +] + +[[package]] +name = "reqwest" +version = "0.13.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "16a1cfa75cc186dd73d5818e510e042e40927bccc9c236b061cea97e1eb08029" +dependencies = [ + "base64 0.23.1", + "bytes", + "encoding_rs", + "futures-core", + "futures-util", + "h2", + "http", + "http-body", + "http-body-util", + "hyper", + "hyper-rustls", + "hyper-util", + "js-sys", + "log", + "mime", + "mime_guess", + "percent-encoding", + "pin-project-lite", + "quinn", + "rustls", + "rustls-pki-types", + "rustls-platform-verifier", + "serde", + "serde_json", + "sync_wrapper", + "tokio", + "tokio-rustls", + "tokio-util", + "tower", + "tower-http", + "tower-service", + "url", + "wasm-bindgen", + "wasm-bindgen-futures", + "wasm-streams 0.5.0", + "web-sys", +] + +[[package]] +name = "resvg" +version = "0.45.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a8928798c0a55e03c9ca6c4c6846f76377427d2c1e1f7e6de3c06ae57942df43" +dependencies = [ + "gif", + "image-webp", + "log", + "pico-args", + "rgb", + "svgtypes", + "tiny-skia", + "usvg", + "zune-jpeg 0.4.21", +] + +[[package]] +name = "rgb" +version = "0.8.53" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "47b34b781b31e5d73e9fbc8689c70551fd1ade9a19e3e28cfec8580a79290cc4" +dependencies = [ + "bytemuck", +] + +[[package]] +name = "rig-agent" +version = "0.45.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "856f21ab95b8b887df997fb34356aeb1ad5677504461f009c58cd7d48274ef74" +dependencies = [ + "async-stream", + "futures", + "http", + "indexmap", + "rig-core", + "rig-derive", + "rig-memory", + "schemars", + "serde", + "serde_json", + "thiserror 2.0.21", + "tracing", + "tracing-futures", +] + +[[package]] +name = "rig-core" +version = "0.45.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0d07ae8e85415d83f620eb4f519d03126227178ac67971b08368c087ce8f9052" +dependencies = [ + "async-stream", + "base64 0.22.1", + "bytes", + "fastrand", + "futures", + "glob", + "http", + "httpdate", + "indexmap", + "mime", + "mime_guess", + "ordered-float", + "rig-derive", + "rig-http", + "rig-reqwest", + "rig-tungstenite", + "schemars", + "serde", + "serde_json", + "serde_path_to_error", + "sha2", + "thiserror 2.0.21", + "tracing", + "url", + "uuid", + "web-time", +] + +[[package]] +name = "rig-derive" +version = "0.45.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "840ef7200097f7e7b7f757f09a80b2ffb494438fca12ad6c84a15ddffc9647d3" +dependencies = [ + "convert_case", + "proc-macro-crate", + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "rig-http" +version = "0.45.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "817c761f9949151fd099ec78e2fbacf7174f24c066ced84c9d28807a6b9d4cee" +dependencies = [ + "bytes", + "futures", + "futures-timer", + "http", + "mime", + "thiserror 2.0.21", + "tokio", + "url", +] + +[[package]] +name = "rig-memory" +version = "0.45.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d25fcf3f3a478d3ac1c0329aca68fdcb94c87cc32e6f2161463fae65270d58ec" +dependencies = [ + "base64 0.22.1", + "memchr", + "rig-core", + "serde", + "serde_json", + "sha2", + "thiserror 2.0.21", +] + +[[package]] +name = "rig-reqwest" +version = "0.45.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c9f13e51c8cbe597ab4ed79f4a1211dab83ac3d9ceaa3826d69b5c770274b9fa" +dependencies = [ + "bytes", + "futures", + "http", + "reqwest 0.13.5", + "rig-http", + "thiserror 2.0.21", + "tracing", + "url", + "webpki-root-certs", +] + +[[package]] +name = "rig-tungstenite" +version = "0.45.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4ba7906f696aee0da3d24825330bb5ff2cf2af86d8e308120f81d9cf581d1e30" +dependencies = [ + "futures", + "rig-http", + "thiserror 2.0.21", + "tokio", + "tokio-tungstenite", +] + +[[package]] +name = "ring" +version = "0.17.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a4689e6c2294d81e88dc6261c768b63bc4fcdb852be6d1352498b114f61383b7" +dependencies = [ + "cc", + "cfg-if", + "getrandom 0.2.17", + "libc", + "untrusted", + "windows-sys 0.52.0", +] + +[[package]] +name = "rmcp" +version = "3.8.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f8be15815186873ea063bf005011d16c356804973489e40c39116ae3a2878d1f" +dependencies = [ + "async-trait", + "base64 0.23.1", + "bytes", + "chrono", + "futures", + "http", + "http-body", + "http-body-util", + "indexmap", + "libc", + "pastey", + "pin-project-lite", + "rand 0.10.3", + "rmcp-macros", + "schemars", + "serde", + "serde_json", + "sse-stream", + "thiserror 2.0.21", + "tokio", + "tokio-stream", + "tokio-util", + "tower-service", + "tracing", + "uuid", +] + +[[package]] +name = "rmcp-macros" +version = "3.8.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8b0748e054a5f5598b3213cf72099ae6b2745ba4d996c59ccf455150a7dbb839" +dependencies = [ + "darling", + "proc-macro2", + "quote", + "serde_json", + "syn 3.0.9", +] + +[[package]] +name = "roxmltree" +version = "0.20.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6c20b6793b5c2fa6553b250154b78d6d0db37e72700ae35fad9387a46f487c97" + +[[package]] +name = "rustc-hash" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "08d43f7aa6b08d49f382cde6a7982047c3426db949b1424bc4b7ec9ae12c6ce2" + +[[package]] +name = "rustc-hash" +version = "2.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d" + +[[package]] +name = "rustc_version" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cfcb3a22ef46e85b45de6ee7e79d063319ebb6594faafcf1c225ea92ab6e9b92" +dependencies = [ + "semver", +] + +[[package]] +name = "rustix" +version = "0.38.44" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fdb5bc1ae2baa591800df16c9ca78619bf65c0488b41b96ccec5d11220d8c154" +dependencies = [ + "bitflags 2.13.2", + "errno", + "libc", + "linux-raw-sys 0.4.15", + "windows-sys 0.59.0", +] + +[[package]] +name = "rustix" +version = "1.1.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e5e76742e5294153d4dde1207dbec5bdd81eef6fabdc0d2118babadabfd858aa" +dependencies = [ + "bitflags 2.13.2", + "errno", + "libc", + "linux-raw-sys 0.12.1", + "windows-sys 0.61.2", +] + +[[package]] +name = "rustls" +version = "0.23.46" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "48e13bd8c0e9365c43cfa5c9e8f9ad49d3c8444926c9aac819e0e4dc503c8fdf" +dependencies = [ + "aws-lc-rs", + "once_cell", + "ring", + "rustls-pki-types", + "rustls-webpki", + "subtle", + "zeroize", +] + +[[package]] +name = "rustls-native-certs" +version = "0.8.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4a073f5dc7469f984c52ad2752b63b0807745133b6de880b7b64c1ac4c48aec4" +dependencies = [ + "openssl-probe", + "rustls-pki-types", + "schannel", + "security-framework", +] + +[[package]] +name = "rustls-pki-types" +version = "1.15.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2f4925028c7eb5d1fcdaf196971378ed9d2c1c4efc7dc5d011256f76c99c0a96" +dependencies = [ + "web-time", + "zeroize", +] + +[[package]] +name = "rustls-platform-verifier" +version = "0.7.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1167586491e2b18b8bfbb293e8180ec17c201c4f076d7cb3070ca964e7598f98" +dependencies = [ + "core-foundation 0.10.1", + "core-foundation-sys", + "jni", + "log", + "once_cell", + "rustls", + "rustls-native-certs", + "rustls-platform-verifier-android", + "rustls-webpki", + "security-framework", + "security-framework-sys", + "webpki-root-certs", + "windows-sys 0.61.2", +] + +[[package]] +name = "rustls-platform-verifier-android" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "eec689c0bc40ff2458a5977b6619cb718087084a18e02a131c599b62d05e1a5f" + +[[package]] +name = "rustls-webpki" +version = "0.103.16" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4443b1b6d39d7c663139942cc4558262562d2c84123bb6282ef177009ca8b281" +dependencies = [ + "aws-lc-rs", + "ring", + "rustls-pki-types", + "untrusted", +] + +[[package]] +name = "rustversion" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f" + +[[package]] +name = "rustybuzz" +version = "0.20.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fd3c7c96f8a08ee34eff8857b11b49b07d71d1c3f4e88f8a88d4c9e9f90b1702" +dependencies = [ + "bitflags 2.13.2", + "bytemuck", + "core_maths", + "log", + "smallvec", + "ttf-parser", + "unicode-bidi-mirroring", + "unicode-ccc", + "unicode-properties", + "unicode-script", +] + +[[package]] +name = "ryu" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f" + +[[package]] +name = "same-file" +version = "1.0.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "93fc1dc3aaa9bfed95e02e6eadabb4baf7e3078b0bd1b4d7b6b0b68378900502" +dependencies = [ + "winapi-util", +] + +[[package]] +name = "schannel" +version = "0.1.30" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9cb23c424d8ee841bb4d813677ca237e2a610067d594fec130f87d6093495ab5" +dependencies = [ + "windows-sys 0.61.2", +] + +[[package]] +name = "schemars" +version = "1.2.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ab508826f74a77ca9d5aba6ff19b522583ee3eaf28a19384ff3d0e5835fadf6e" +dependencies = [ + "chrono", + "dyn-clone", + "ref-cast", + "schemars_derive", + "serde", + "serde_json", +] + +[[package]] +name = "schemars_derive" +version = "1.2.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e1c3a92094fa7d61aa124645844facb6b554dfc797136d0f5fd1f890e2bffc69" +dependencies = [ + "proc-macro2", + "quote", + "serde_derive_internals", + "syn 3.0.9", +] + +[[package]] +name = "scoped-tls" +version = "1.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e1cf6437eb19a8f4a6cc0f7dca544973b0b78843adbfeb3683d1a94a0024a294" + +[[package]] +name = "scopeguard" +version = "1.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49" + +[[package]] +name = "sctk-adwaita" +version = "0.10.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b6277f0217056f77f1d8f49f2950ac6c278c0d607c45f5ee99328d792ede24ec" +dependencies = [ + "ab_glyph", + "log", + "memmap2", + "smithay-client-toolkit 0.19.2", + "tiny-skia", +] + +[[package]] +name = "security-framework" +version = "3.7.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b7f4bc775c73d9a02cde8bf7b2ec4c9d12743edf609006c7facc23998404cd1d" +dependencies = [ + "bitflags 2.13.2", + "core-foundation 0.10.1", + "core-foundation-sys", + "libc", + "security-framework-sys", +] + +[[package]] +name = "security-framework-sys" +version = "2.17.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6ce2691df843ecc5d231c0b14ece2acc3efb62c0a398c7e1d875f3983ce020e3" +dependencies = [ + "core-foundation-sys", + "libc", +] + +[[package]] +name = "self_cell" +version = "1.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2ab42ca02749e120097e328d91d415325bdf43b1c72c4c8badf37375fe40a813" + +[[package]] +name = "semver" +version = "1.0.28" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8a7852d02fc848982e0c167ef163aaff9cd91dc640ba85e263cb1ce46fae51cd" + +[[package]] +name = "send_wrapper" +version = "0.6.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cd0b0ec5f1c1ca621c432a25813d8d60c88abe6d3e08a3eb9cf37d97a0fe3d73" + +[[package]] +name = "serde" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba" +dependencies = [ + "serde_core", + "serde_derive", +] + +[[package]] +name = "serde_core" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48" +dependencies = [ + "serde_derive", +] + +[[package]] +name = "serde_derive" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.9", +] + +[[package]] +name = "serde_derive_internals" +version = "0.30.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f852137cce035d6a4df67ccce505ff6b3e9fd3a10e3e52b24dc71e650bb1a9bd" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.9", +] + +[[package]] +name = "serde_json" +version = "1.0.154" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6" +dependencies = [ + "foldhash 0.2.0", + "indexmap", + "itoa", + "memchr", + "serde", + "serde_core", + "zmij", +] + +[[package]] +name = "serde_path_to_error" +version = "0.1.20" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "10a9ff822e371bb5403e391ecd83e182e0e77ba7f6fe0160b795797109d1b457" +dependencies = [ + "itoa", + "serde", + "serde_core", +] + +[[package]] +name = "serde_repr" +version = "0.1.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8d3b1629de253c70a0508c3899572da79ca359fdab27c7920ff00406df418906" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.9", +] + +[[package]] +name = "serde_urlencoded" +version = "0.7.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d3491c14715ca2294c4d6a88f15e84739788c1d030eed8c110436aafdaa2f3fd" +dependencies = [ + "form_urlencoded", + "itoa", + "ryu", + "serde", +] + +[[package]] +name = "serde_yaml_ng" +version = "0.10.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7b4db627b98b36d4203a7b458cf3573730f2bb591b28871d916dfa9efabfd41f" +dependencies = [ + "indexmap", + "itoa", + "ryu", + "serde", + "unsafe-libyaml", +] + +[[package]] +name = "sha1" +version = "0.10.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a978451301f4db1d02937a4ab3ccce137717b81826e79b7d49ffe3244a13c3b8" +dependencies = [ + "cfg-if", + "cpufeatures 0.2.17", + "digest", +] + +[[package]] +name = "sha2" +version = "0.10.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283" +dependencies = [ + "cfg-if", + "cpufeatures 0.2.17", + "digest", +] + +[[package]] +name = "shlex" +version = "2.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba" + +[[package]] +name = "signal-hook-registry" +version = "1.4.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c4db69cba1110affc0e9f7bcd48bbf87b3f4fc7c61fc9155afd4c469eb3d6c1b" +dependencies = [ + "errno", + "libc", +] + +[[package]] +name = "simd-adler32" +version = "0.3.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3a219298ac11a56ea9a6d2120044824d6f01aeb034955e7af7bc16858527deea" + +[[package]] +name = "simd_cesu8" +version = "1.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "11031e251abf8611c80f460e19dbdeb54a66db918e49c65a7065b46ac7aec520" +dependencies = [ + "rustc_version", + "simdutf8", +] + +[[package]] +name = "simdutf8" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e3a9fe34e3e7a50316060351f37187a3f546bce95496156754b601a5fa71b76e" + +[[package]] +name = "simplecss" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7a9c6883ca9c3c7c90e888de77b7a5c849c779d25d74a1269b0218b14e8b136c" +dependencies = [ + "log", +] + +[[package]] +name = "siphasher" +version = "1.0.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "33f4fe9184a62d842c9ef383018f3306d8ba224fd9d836f56d7288308847c256" + +[[package]] +name = "skrifa" +version = "0.37.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8c31071dedf532758ecf3fed987cdb4bd9509f900e026ab684b4ecb81ea49841" +dependencies = [ + "bytemuck", + "read-fonts 0.35.0", +] + +[[package]] +name = "skrifa" +version = "0.44.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "819ab7d62b1d3e72d9d9dea5650bac30424f9111364bb94928dbf5ecad1baa68" +dependencies = [ + "bytemuck", + "read-fonts 0.41.0", +] + +[[package]] +name = "slab" +version = "0.4.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5" + +[[package]] +name = "slotmap" +version = "1.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bdd58c3c93c3d278ca835519292445cb4b0d4dc59ccfdf7ceadaab3f8aeb4038" +dependencies = [ + "version_check", +] + +[[package]] +name = "smallvec" +version = "1.16.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d0d5d4b1981b8bbbb7aed204cae5726d683d5d6ac7e74ec54122ea28f315e7c8" + +[[package]] +name = "smithay-client-toolkit" +version = "0.19.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3457dea1f0eb631b4034d61d4d8c32074caa6cd1ab2d59f2327bd8461e2c0016" +dependencies = [ + "bitflags 2.13.2", + "calloop 0.13.0", + "calloop-wayland-source 0.3.0", + "cursor-icon", + "libc", + "log", + "memmap2", + "rustix 0.38.44", + "thiserror 1.0.69", + "wayland-backend", + "wayland-client", + "wayland-csd-frame", + "wayland-cursor", + "wayland-protocols", + "wayland-protocols-wlr", + "wayland-scanner", + "xkeysym", +] + +[[package]] +name = "smithay-client-toolkit" +version = "0.20.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0512da38f5e2b31201a93524adb8d3136276fa4fe4aafab4e1f727a82b534cc0" +dependencies = [ + "bitflags 2.13.2", + "calloop 0.14.5", + "calloop-wayland-source 0.4.1", + "cursor-icon", + "libc", + "log", + "memmap2", + "rustix 1.1.6", + "thiserror 2.0.21", + "wayland-backend", + "wayland-client", + "wayland-csd-frame", + "wayland-cursor", + "wayland-protocols", + "wayland-protocols-experimental", + "wayland-protocols-misc", + "wayland-protocols-wlr", + "wayland-scanner", + "xkeysym", +] + +[[package]] +name = "smithay-clipboard" +version = "0.7.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "71704c03f739f7745053bde45fa203a46c58d25bc5c4efba1d9a60e9dba81226" +dependencies = [ + "libc", + "smithay-client-toolkit 0.20.0", + "wayland-backend", +] + +[[package]] +name = "smol_str" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dd538fb6910ac1099850255cf94a94df6551fbdd602454387d0adb2d1ca6dead" +dependencies = [ + "serde", +] + +[[package]] +name = "socket2" +version = "0.6.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c3d1e2c7f27f8d4cb10542a02c49005dbd6e93095799d6f3be745fae9f8fedd4" +dependencies = [ + "libc", + "windows-sys 0.61.2", +] + +[[package]] +name = "softbuffer" +version = "0.4.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "aac18da81ebbf05109ab275b157c22a653bb3c12cf884450179942f81bcbf6c3" +dependencies = [ + "as-raw-xcb-connection", + "bytemuck", + "fastrand", + "js-sys", + "memmap2", + "ndk", + "objc2 0.6.5", + "objc2-core-foundation", + "objc2-core-graphics", + "objc2-foundation 0.3.2", + "objc2-quartz-core 0.3.2", + "raw-window-handle", + "redox_syscall 0.5.18", + "rustix 1.1.6", + "tiny-xlib", + "tracing", + "wasm-bindgen", + "wayland-backend", + "wayland-client", + "wayland-sys", + "web-sys", + "windows-sys 0.61.2", + "x11rb", +] + +[[package]] +name = "spirv" +version = "0.3.0+sdk-1.3.268.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "eda41003dc44290527a59b13432d4a0379379fa074b70174882adfbdfd917844" +dependencies = [ + "bitflags 2.13.2", +] + +[[package]] +name = "sse-stream" +version = "0.2.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c25ac7aff0abd1dbc474536e40416e1102c7dd9bfba0b9861c6d357f835dcfb4" +dependencies = [ + "bytes", + "futures-util", + "http-body", + "http-body-util", + "pin-project-lite", +] + +[[package]] +name = "stable_deref_trait" +version = "1.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596" + +[[package]] +name = "static_assertions" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a2eb9349b6444b326872e140eb1cf5e7c522154d69e7a0ffb0fb81c06b37543f" + +[[package]] +name = "strict-num" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6637bab7722d379c8b41ba849228d680cc12d0a45ba1fa2b48f2a30577a06731" +dependencies = [ + "float-cmp", +] + +[[package]] +name = "strsim" +version = "0.11.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f" + +[[package]] +name = "subtle" +version = "2.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292" + +[[package]] +name = "svg_fmt" +version = "0.4.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0193cc4331cfd2f3d2011ef287590868599a2f33c3e69bc22c1a3d3acf9e02fb" + +[[package]] +name = "svgtypes" +version = "0.15.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "68c7541fff44b35860c1a7a47a7cadf3e4a304c457b58f9870d9706ece028afc" +dependencies = [ + "kurbo 0.11.3", + "siphasher", +] + +[[package]] +name = "swash" +version = "0.2.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6c2499c2d826531388872b2268718aed907a39bd785ab0dcfe57fab26283f92e" +dependencies = [ + "skrifa 0.44.0", + "yazi", + "zeno", +] + +[[package]] +name = "syn" +version = "2.0.119" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "syn" +version = "3.0.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d78c8dee4c7bf0e14673097256fed6142ce9d3b85a408189d07482442145823b" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "sync_wrapper" +version = "1.0.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0bf256ce5efdfa370213c1dabab5935a12e49f2c58d15e9eac2870d3b4f27263" +dependencies = [ + "futures-core", +] + +[[package]] +name = "synstructure" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "901704edd0dfe137f1987838ee4f259e4e063c31371bdb423f7ae38ec6f77f02" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.9", +] + +[[package]] +name = "sys-locale" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8eab9a99a024a169fe8a903cf9d4a3b3601109bcc13bd9e3c6fff259138626c4" +dependencies = [ + "libc", +] + +[[package]] +name = "system-configuration" +version = "0.7.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a13f3d0daba03132c0aa9767f98351b3488edc2c100cda2d2ec2b04f3d8d3c8b" +dependencies = [ + "bitflags 2.13.2", + "core-foundation 0.9.4", + "system-configuration-sys", +] + +[[package]] +name = "system-configuration-sys" +version = "0.6.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8e1d1b10ced5ca923a1fcb8d03e96b8d3268065d724548c0211415ff6ac6bac4" +dependencies = [ + "core-foundation-sys", + "libc", +] + +[[package]] +name = "tar" +version = "0.4.46" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3f6221d9a6003c78398e3b239969f352578258df48c8eb051caadae0015bc840" +dependencies = [ + "filetime", + "libc", + "xattr", +] + +[[package]] +name = "tempfile" +version = "3.27.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd" +dependencies = [ + "fastrand", + "getrandom 0.4.3", + "once_cell", + "rustix 1.1.6", + "windows-sys 0.61.2", +] + +[[package]] +name = "termcolor" +version = "1.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "06794f8f6c5c898b3275aebefa6b8a1cb24cd2c6c79397ab15774837a0bc5755" +dependencies = [ + "winapi-util", +] + +[[package]] +name = "thiserror" +version = "1.0.69" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b6aaf5339b578ea85b50e080feb250a3e8ae8cfcdff9a461c9ec2904bc923f52" +dependencies = [ + "thiserror-impl 1.0.69", +] + +[[package]] +name = "thiserror" +version = "2.0.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "09e52cb86a36cede5cb101bf8908837b3e4c6e5e59fe7fd85c23fb56200d189e" +dependencies = [ + "thiserror-impl 2.0.21", +] + +[[package]] +name = "thiserror-impl" +version = "1.0.69" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4fee6c4efc90059e10f81e6d42c60a18f76588c3d74cb83a0b242a2b6c7504c1" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "thiserror-impl" +version = "2.0.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fe5197923287db20a58125f0bc85c062f7f2c892de97b18c356f9efb14b28524" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.9", +] + +[[package]] +name = "tiny-skia" +version = "0.11.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "83d13394d44dae3207b52a326c0c85a8bf87f1541f23b0d143811088497b09ab" +dependencies = [ + "arrayref", + "arrayvec", + "bytemuck", + "cfg-if", + "log", + "png 0.17.16", + "tiny-skia-path", +] + +[[package]] +name = "tiny-skia-path" +version = "0.11.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9c9e7fc0c2e86a30b117d0462aa261b72b7a99b7ebd7deb3a14ceda95c5bdc93" +dependencies = [ + "arrayref", + "bytemuck", + "strict-num", +] + +[[package]] +name = "tiny-xlib" +version = "0.2.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a90a0ca3ee6a69f2ad28fd11621a4c3f03b371f366be500b64df260c4ffbafb4" +dependencies = [ + "as-raw-xcb-connection", + "ctor", + "libloading", + "pkg-config", + "tracing", +] + +[[package]] +name = "tinystr" +version = "0.8.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "abc840c238154d58f9e86b2792261edfde565a17696e1cda1a449de27979801a" +dependencies = [ + "displaydoc", + "zerovec", +] + +[[package]] +name = "tinyvec" +version = "1.13.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fd3ca314f692efd6c868f8408f53fe444634a845f96c028b97d35f6a1f79f0ee" + +[[package]] +name = "tokio" +version = "1.54.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b52fd3255258d26fac7264ab5a76b53c13367136dc011d3d6ad4f8ed070396a3" +dependencies = [ + "bytes", + "libc", + "mio", + "pin-project-lite", + "socket2", + "tokio-macros", + "windows-sys 0.61.2", +] + +[[package]] +name = "tokio-macros" +version = "2.7.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "78773a2a397f451582ce068015985c33193cf6dea8b74d2a639fe457b2f07b0e" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.9", +] + +[[package]] +name = "tokio-rustls" +version = "0.26.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c9cc2678c2cdd569ef8215e2afd7954ada2ae20b4fdd2c5fe6139a3b02d105db" +dependencies = [ + "rustls", + "tokio", +] + +[[package]] +name = "tokio-stream" +version = "0.1.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a3d06f0b082ba57c26b79407372e57cf2a1e28124f78e9479fe80322cf53420b" +dependencies = [ + "futures-core", + "pin-project-lite", + "tokio", +] + +[[package]] +name = "tokio-tungstenite" +version = "0.29.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8f72a05e828585856dacd553fba484c242c46e391fb0e58917c942ee9202915c" +dependencies = [ + "futures-util", + "log", + "rustls", + "rustls-pki-types", + "tokio", + "tokio-rustls", + "tungstenite", + "webpki-roots 0.26.11", +] + +[[package]] +name = "tokio-util" +version = "0.7.20" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e464cf451ba96ebfc6f9b6542f17ee8b8956e33f1e40d9690624e59d7a7f8a4b" +dependencies = [ + "bytes", + "futures-core", + "futures-sink", + "libc", + "pin-project-lite", + "tokio", +] + +[[package]] +name = "toml_datetime" +version = "1.1.2+spec-1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2b86d767906c6c42421dcba507eb9d203e779497710a47782a224bb871653053" +dependencies = [ + "serde_core", +] + +[[package]] +name = "toml_edit" +version = "0.25.17+spec-1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e3641d5bbb5349a79e1020a242d251efbc546ad8048d133958323ce9c40a9c9c" +dependencies = [ + "indexmap", + "toml_datetime", + "toml_parser", + "winnow", +] + +[[package]] +name = "toml_parser" +version = "1.1.5+spec-1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "baa693a8032d7e1cada7d0041e96126df243179ff061456783ac7f12bda4744c" +dependencies = [ + "winnow", +] + +[[package]] +name = "tower" +version = "0.5.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ebe5ef63511595f1344e2d5cfa636d973292adc0eec1f0ad45fae9f0851ab1d4" +dependencies = [ + "futures-core", + "futures-util", + "pin-project-lite", + "sync_wrapper", + "tokio", + "tower-layer", + "tower-service", + "tracing", +] + +[[package]] +name = "tower-http" +version = "0.6.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4cfcf7e2740e6fc6d4d688b4ef00650406bb94adf4731e43c096c3a19fe40840" +dependencies = [ + "bitflags 2.13.2", + "bytes", + "futures-util", + "http", + "http-body", + "pin-project-lite", + "tower", + "tower-layer", + "tower-service", + "url", +] + +[[package]] +name = "tower-layer" +version = "0.3.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "121c2a6cda46980bb0fcd1647ffaf6cd3fc79a013de288782836f6df9c48780e" + +[[package]] +name = "tower-service" +version = "0.3.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8df9b6e13f2d32c91b9bd719c00d1958837bc7dec474d94952798cc8e69eeec3" + +[[package]] +name = "tracing" +version = "0.1.44" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100" +dependencies = [ + "log", + "pin-project-lite", + "tracing-attributes", + "tracing-core", +] + +[[package]] +name = "tracing-attributes" +version = "0.1.31" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7490cfa5ec963746568740651ac6781f701c9c5ea257c58e057f3ba8cf69e8da" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "tracing-core" +version = "0.1.36" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a" +dependencies = [ + "once_cell", +] + +[[package]] +name = "tracing-futures" +version = "0.2.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "97d095ae15e245a057c8e8451bab9b3ee1e1f68e9ba2b4fbc18d0ac5237835f2" +dependencies = [ + "futures", + "futures-task", + "pin-project", + "tracing", +] + +[[package]] +name = "try-lock" +version = "0.2.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b" + +[[package]] +name = "ttf-parser" +version = "0.25.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d2df906b07856748fa3f6e0ad0cbaa047052d4a7dd609e231c4f72cee8c36f31" +dependencies = [ + "core_maths", +] + +[[package]] +name = "tungstenite" +version = "0.29.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6c01152af293afb9c7c2a57e4b559c5620b421f6d133261c60dd2d0cdb38e6b8" +dependencies = [ + "bytes", + "data-encoding", + "http", + "httparse", + "log", + "rand 0.9.5", + "rustls", + "rustls-pki-types", + "sha1", + "thiserror 2.0.21", +] + +[[package]] +name = "typed-path" +version = "0.13.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9ce898823d8cd0f028662d2f349694b1af0a5cc9be83f1d213a00d3147445e1e" + +[[package]] +name = "typenum" +version = "1.20.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20" + +[[package]] +name = "uds_windows" +version = "1.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f2f6fb2847f6742cd76af783a2a2c49e9375d0a111c7bef6f71cd9e738c72d6e" +dependencies = [ + "memoffset", + "tempfile", + "windows-sys 0.61.2", +] + +[[package]] +name = "unicase" +version = "2.10.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "357cc3acc6a036009fd6c973ed009037c732d60d0b4f6c673e9041497482a28f" + +[[package]] +name = "unicode-bidi" +version = "0.3.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5c1cb5db39152898a79168971543b1cb5020dff7fe43c8dc468b0885f5e29df5" + +[[package]] +name = "unicode-bidi-mirroring" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5dfa6e8c60bb66d49db113e0125ee8711b7647b5579dc7f5f19c42357ed039fe" + +[[package]] +name = "unicode-ccc" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ce61d488bcdc9bc8b5d1772c404828b17fc481c0a582b5581e95fb233aef503e" + +[[package]] +name = "unicode-ident" +version = "1.0.27" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563" + +[[package]] +name = "unicode-linebreak" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3b09c83c3c29d37506a3e260c08c03743a6bb66a9cd432c6934ab501a190571f" + +[[package]] +name = "unicode-properties" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "993ad287eb20e8ba755312801cfe1413e0f25d604075863acaddca10b04c1833" + +[[package]] +name = "unicode-script" +version = "0.5.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "383ad40bb927465ec0ce7720e033cb4ca06912855fc35db31b5755d0de75b1ee" + +[[package]] +name = "unicode-segmentation" +version = "1.13.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c6f5d3c3b1bf09027a88a6bc961fc00497d651009560b5463668dc81b0fa87a8" + +[[package]] +name = "unicode-vo" +version = "0.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b1d386ff53b415b7fe27b50bb44679e2cc4660272694b7b6f3326d8480823a94" + +[[package]] +name = "unicode-width" +version = "0.2.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ca718471876992059f251e33aafc334346ada08042b7661dd1fe313a9bced557" + +[[package]] +name = "unlucky-agent" +version = "0.2.0" +dependencies = [ + "axum", + "futures-util", + "rig-agent", + "rig-core", + "rmcp", + "serde", + "serde_json", + "tokio", + "unlucky-core", +] + +[[package]] +name = "unlucky-app-iced" +version = "0.2.0" +dependencies = [ + "iced", + "image", + "log", + "unlucky-cli", + "unlucky-design", + "unlucky-i18n", + "unlucky-presenter", +] + +[[package]] +name = "unlucky-cli" +version = "0.2.0" +dependencies = [ + "serde", + "serde_json", + "tokio", + "unlucky-agent", + "unlucky-core", +] + +[[package]] +name = "unlucky-core" +version = "0.2.0" +dependencies = [ + "flate2", + "futures-util", + "md-5", + "regex", + "reqwest 0.12.28", + "serde", + "serde_json", + "serde_yaml_ng", + "sha1", + "sha2", + "tar", + "tokio", + "zip", +] + +[[package]] +name = "unlucky-design" +version = "0.2.0" + +[[package]] +name = "unlucky-i18n" +version = "0.2.0" + +[[package]] +name = "unlucky-palette-extract" +version = "0.2.0" +dependencies = [ + "image", + "unlucky-design", +] + +[[package]] +name = "unlucky-presenter" +version = "0.2.0" +dependencies = [ + "serde", + "serde_json", + "unlucky-core", +] + +[[package]] +name = "unsafe-libyaml" +version = "0.2.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "673aac59facbab8a9007c7f6108d11f63b603f7cabff99fabf650fea5c32b861" + +[[package]] +name = "untrusted" +version = "0.9.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8ecb6da28b8a351d773b68d5825ac39017e680750f980f3a1a85cd8dd28a47c1" + +[[package]] +name = "url" +version = "2.5.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ff67a8a4397373c3ef660812acab3268222035010ab8680ec4215f38ba3d0eed" +dependencies = [ + "form_urlencoded", + "idna", + "percent-encoding", + "serde", +] + +[[package]] +name = "usvg" +version = "0.45.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "80be9b06fbae3b8b303400ab20778c80bbaf338f563afe567cf3c9eea17b47ef" +dependencies = [ + "base64 0.22.1", + "data-url", + "flate2", + "fontdb", + "imagesize", + "kurbo 0.11.3", + "log", + "pico-args", + "roxmltree", + "rustybuzz", + "simplecss", + "siphasher", + "strict-num", + "svgtypes", + "tiny-skia-path", + "unicode-bidi", + "unicode-script", + "unicode-vo", + "xmlwriter", +] + +[[package]] +name = "utf8_iter" +version = "1.0.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be" + +[[package]] +name = "uuid" +version = "1.29.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4a0e2d11620c50695fe12bbbfde96b3477fe606e7284c22d505c12ce51214514" +dependencies = [ + "getrandom 0.4.3", + "js-sys", + "serde_core", + "wasm-bindgen", +] + +[[package]] +name = "version_check" +version = "0.9.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a" + +[[package]] +name = "walkdir" +version = "2.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "29790946404f91d9c5d06f9874efddea1dc06c5efe94541a7d6863108e3a5e4b" +dependencies = [ + "same-file", + "winapi-util", +] + +[[package]] +name = "want" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ec4cdd0dd910afe868b7ef477227d8d538b46b3075031afee8a9f2acb0a2ed0b" +dependencies = [ + "try-lock", +] + +[[package]] +name = "wasi" +version = "0.11.1+wasi-snapshot-preview1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b" + +[[package]] +name = "wasip2" +version = "1.0.4+wasi-0.2.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b67efb37e106e55ce722a510d6b5f9c17f083e5fc79afc2badeb12cc313d9487" +dependencies = [ + "wit-bindgen", +] + +[[package]] +name = "wasm-bindgen" +version = "0.2.129" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9bb54f33acc68fd454578d9820b0bde1a1a3d17aa17bb7b6595806d02886d409" +dependencies = [ + "cfg-if", + "once_cell", + "rustversion", + "wasm-bindgen-macro", + "wasm-bindgen-shared", +] + +[[package]] +name = "wasm-bindgen-futures" +version = "0.4.79" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3cbab34de2d982e9b48e18d216d04c4a6f641066ff19ffb699980f591ee3610e" +dependencies = [ + "js-sys", + "tokio", + "wasm-bindgen", +] + +[[package]] +name = "wasm-bindgen-macro" +version = "0.2.129" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2e29d0c35b16e224a7eeb5cd2d25e3e1968fbd65604117b44d3b789d00ee8535" +dependencies = [ + "quote", + "wasm-bindgen-macro-support", +] + +[[package]] +name = "wasm-bindgen-macro-support" +version = "0.2.129" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6f501a8bc3719dba86ef8ae4728879c08001bea749eb1333ac5b91e040e2a6b7" +dependencies = [ + "bumpalo", + "proc-macro2", + "quote", + "syn 3.0.9", + "wasm-bindgen-shared", +] + +[[package]] +name = "wasm-bindgen-shared" +version = "0.2.129" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "23f0c9c52aa7cd7d77769a4cfe2a9adb1b331f489a41d912ce14513d5ab995c6" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "wasm-streams" +version = "0.4.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "15053d8d85c7eccdbefef60f06769760a563c7f0a9d6902a13d35c7800b0ad65" +dependencies = [ + "futures-util", + "js-sys", + "wasm-bindgen", + "wasm-bindgen-futures", + "web-sys", +] + +[[package]] +name = "wasm-streams" +version = "0.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9d1ec4f6517c9e11ae630e200b2b65d193279042e28edd4a2cda233e46670bbb" +dependencies = [ + "futures-util", + "js-sys", + "wasm-bindgen", + "wasm-bindgen-futures", + "web-sys", +] + +[[package]] +name = "wasmtimer" +version = "0.4.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1c598d6b99ea013e35844697fc4670d08339d5cda15588f193c6beedd12f644b" +dependencies = [ + "futures", + "js-sys", + "parking_lot", + "pin-utils", + "slab", + "wasm-bindgen", +] + +[[package]] +name = "wayland-backend" +version = "0.3.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "38a91b4eaddff87b1cd1074985e3713da4af2c49742d1b356b2c01670a67a078" +dependencies = [ + "cc", + "downcast-rs", + "rustix 1.1.6", + "scoped-tls", + "smallvec", + "wayland-sys", +] + +[[package]] +name = "wayland-client" +version = "0.31.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e3c36a0f861ad76d0901f2800b46321410d9f73f2ea88aac0650d86c32688073" +dependencies = [ + "bitflags 2.13.2", + "rustix 1.1.6", + "wayland-backend", + "wayland-scanner", +] + +[[package]] +name = "wayland-csd-frame" +version = "0.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "625c5029dbd43d25e6aa9615e88b829a5cad13b2819c4ae129fdbb7c31ab4c7e" +dependencies = [ + "bitflags 2.13.2", + "cursor-icon", + "wayland-backend", +] + +[[package]] +name = "wayland-cursor" +version = "0.31.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4a52d18780be9b1314328a3de5f930b73d2200112e3849ca6cb11822793fb34d" +dependencies = [ + "rustix 1.1.6", + "wayland-client", + "xcursor", +] + +[[package]] +name = "wayland-protocols" +version = "0.32.13" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "23d0c813de3daa2ed6520af85a3bd49b0e722a3078506899aa9686fea58dc4b6" +dependencies = [ + "bitflags 2.13.2", + "wayland-backend", + "wayland-client", + "wayland-scanner", +] + +[[package]] +name = "wayland-protocols-experimental" +version = "20250721.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "40a1f863128dcaaec790d7b4b396cc9b9a7a079e878e18c47e6c2d2c5a8dcbb1" +dependencies = [ + "bitflags 2.13.2", + "wayland-backend", + "wayland-client", + "wayland-protocols", + "wayland-scanner", +] + +[[package]] +name = "wayland-protocols-misc" +version = "0.3.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6e9567599ef23e09b8dad6e429e5738d4509dfc46b3b21f32841a304d16b29c8" +dependencies = [ + "bitflags 2.13.2", + "wayland-backend", + "wayland-client", + "wayland-protocols", + "wayland-scanner", +] + +[[package]] +name = "wayland-protocols-plasma" +version = "0.3.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2b6d8cf1eb2c1c31ed1f5643c88a6e53538129d4af80030c8cabd1f9fa884d91" +dependencies = [ + "bitflags 2.13.2", + "wayland-backend", + "wayland-client", + "wayland-protocols", + "wayland-scanner", +] + +[[package]] +name = "wayland-protocols-wlr" +version = "0.3.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "eb04e52f7836d7c7976c78ca0250d61e33873c34156a2a1fc9474828ec268234" +dependencies = [ + "bitflags 2.13.2", + "wayland-backend", + "wayland-client", + "wayland-protocols", + "wayland-scanner", +] + +[[package]] +name = "wayland-scanner" +version = "0.31.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "338e30461b3a2b67d70eb30a6d89f8e0c93a833e07d2ae89085cd070c4a00ac0" +dependencies = [ + "proc-macro2", + "quick-xml", + "quote", +] + +[[package]] +name = "wayland-sys" +version = "0.31.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d8eab23fefc9e41f8e841df4a9c707e8a8c4ed26e944ef69297184de2785e3be" +dependencies = [ + "dlib", + "log", + "once_cell", + "pkg-config", +] + +[[package]] +name = "web-sys" +version = "0.3.106" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "88261b9deccee56594c11a3460c462c41f58d148598fe70ad77070126a68aba4" +dependencies = [ + "js-sys", + "wasm-bindgen", +] + +[[package]] +name = "web-time" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5a6580f308b1fad9207618087a65c04e7a10bc77e02c8e84e9b00dd4b12fa0bb" +dependencies = [ + "js-sys", + "wasm-bindgen", +] + +[[package]] +name = "webpki-root-certs" +version = "1.0.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e49d0e65abc00c142e8f9428da991da9f1a250c39be97459901eb12b9b49f62a" +dependencies = [ + "rustls-pki-types", +] + +[[package]] +name = "webpki-roots" +version = "0.26.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "521bc38abb08001b01866da9f51eb7c5d647a19260e00054a8c7fd5f9e57f7a9" +dependencies = [ + "webpki-roots 1.0.11", +] + +[[package]] +name = "webpki-roots" +version = "1.0.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f5f280bbb2b287bc8e7de7e3852945a0ff50d1bbcb5ed42b6c7a568c546df171" +dependencies = [ + "rustls-pki-types", +] + +[[package]] +name = "weezl" +version = "0.1.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a28ac98ddc8b9274cb41bb4d9d4d5c425b6020c50c46f25559911905610b4a88" + +[[package]] +name = "wgpu" +version = "27.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bfe68bac7cde125de7a731c3400723cadaaf1703795ad3f4805f187459cd7a77" +dependencies = [ + "arrayvec", + "bitflags 2.13.2", + "cfg-if", + "cfg_aliases", + "document-features", + "hashbrown 0.16.1", + "js-sys", + "log", + "naga", + "parking_lot", + "portable-atomic", + "profiling", + "raw-window-handle", + "smallvec", + "static_assertions", + "wasm-bindgen", + "wasm-bindgen-futures", + "web-sys", + "wgpu-core", + "wgpu-hal", + "wgpu-types", +] + +[[package]] +name = "wgpu-core" +version = "27.0.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "27a75de515543b1897b26119f93731b385a19aea165a1ec5f0e3acecc229cae7" +dependencies = [ + "arrayvec", + "bit-set", + "bit-vec", + "bitflags 2.13.2", + "bytemuck", + "cfg_aliases", + "document-features", + "hashbrown 0.16.1", + "indexmap", + "log", + "naga", + "once_cell", + "parking_lot", + "portable-atomic", + "profiling", + "raw-window-handle", + "rustc-hash 1.1.0", + "smallvec", + "thiserror 2.0.21", + "wgpu-core-deps-apple", + "wgpu-core-deps-emscripten", + "wgpu-core-deps-windows-linux-android", + "wgpu-hal", + "wgpu-types", +] + +[[package]] +name = "wgpu-core-deps-apple" +version = "27.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0772ae958e9be0c729561d5e3fd9a19679bcdfb945b8b1a1969d9bfe8056d233" +dependencies = [ + "wgpu-hal", +] + +[[package]] +name = "wgpu-core-deps-emscripten" +version = "27.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b06ac3444a95b0813ecfd81ddb2774b66220b264b3e2031152a4a29fda4da6b5" +dependencies = [ + "wgpu-hal", +] + +[[package]] +name = "wgpu-core-deps-windows-linux-android" +version = "27.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "71197027d61a71748e4120f05a9242b2ad142e3c01f8c1b47707945a879a03c3" +dependencies = [ + "wgpu-hal", +] + +[[package]] +name = "wgpu-hal" +version = "27.0.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5b21cb61c57ee198bc4aff71aeadff4cbb80b927beb912506af9c780d64313ce" +dependencies = [ + "android_system_properties", + "arrayvec", + "ash", + "bit-set", + "bitflags 2.13.2", + "block", + "bytemuck", + "cfg-if", + "cfg_aliases", + "core-graphics-types 0.2.0", + "glow", + "glutin_wgl_sys", + "gpu-alloc", + "gpu-allocator", + "gpu-descriptor", + "hashbrown 0.16.1", + "js-sys", + "khronos-egl", + "libc", + "libloading", + "log", + "metal", + "naga", + "ndk-sys", + "objc", + "once_cell", + "ordered-float", + "parking_lot", + "portable-atomic", + "portable-atomic-util", + "profiling", + "range-alloc", + "raw-window-handle", + "renderdoc-sys", + "smallvec", + "thiserror 2.0.21", + "wasm-bindgen", + "web-sys", + "wgpu-types", + "windows 0.58.0", + "windows-core 0.58.0", +] + +[[package]] +name = "wgpu-types" +version = "27.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "afdcf84c395990db737f2dd91628706cb31e86d72e53482320d368e52b5da5eb" +dependencies = [ + "bitflags 2.13.2", + "bytemuck", + "js-sys", + "log", + "thiserror 2.0.21", + "web-sys", +] + +[[package]] +name = "winapi-util" +version = "0.1.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22" +dependencies = [ + "windows-sys 0.61.2", +] + +[[package]] +name = "window_clipboard" +version = "0.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d5654226305eaf2dde8853fb482861d28e5dcecbbd40cb88e8393d94bb80d733" +dependencies = [ + "clipboard-win", + "clipboard_macos", + "clipboard_wayland", + "clipboard_x11", + "raw-window-handle", + "thiserror 2.0.21", +] + +[[package]] +name = "windows" +version = "0.58.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dd04d41d93c4992d421894c18c8b43496aa748dd4c081bac0dc93eb0489272b6" +dependencies = [ + "windows-core 0.58.0", + "windows-targets", +] + +[[package]] +name = "windows" +version = "0.62.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "527fadee13e0c05939a6a05d5bd6eec6cd2e3dbd648b9f8e447c6518133d8580" +dependencies = [ + "windows-collections", + "windows-core 0.62.2", + "windows-future", + "windows-numerics", +] + +[[package]] +name = "windows-collections" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "23b2d95af1a8a14a3c7367e1ed4fc9c20e0a26e79551b1454d72583c97cc6610" +dependencies = [ + "windows-core 0.62.2", +] + +[[package]] +name = "windows-core" +version = "0.58.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6ba6d44ec8c2591c134257ce647b7ea6b20335bf6379a27dac5f1641fcf59f99" +dependencies = [ + "windows-implement 0.58.0", + "windows-interface 0.58.0", + "windows-result 0.2.0", + "windows-strings 0.1.0", + "windows-targets", +] + +[[package]] +name = "windows-core" +version = "0.62.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b8e83a14d34d0623b51dce9581199302a221863196a1dde71a7663a4c2be9deb" +dependencies = [ + "windows-implement 0.60.2", + "windows-interface 0.59.3", + "windows-link", + "windows-result 0.4.1", + "windows-strings 0.5.1", +] + +[[package]] +name = "windows-future" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e1d6f90251fe18a279739e78025bd6ddc52a7e22f921070ccdc67dde84c605cb" +dependencies = [ + "windows-core 0.62.2", + "windows-link", + "windows-threading", +] + +[[package]] +name = "windows-implement" +version = "0.58.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2bbd5b46c938e506ecbce286b6628a02171d56153ba733b6c741fc627ec9579b" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "windows-implement" +version = "0.60.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "windows-interface" +version = "0.58.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "053c4c462dc91d3b1504c6fe5a726dd15e216ba718e84a0e46a88fbe5ded3515" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "windows-interface" +version = "0.59.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "windows-link" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5" + +[[package]] +name = "windows-numerics" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6e2e40844ac143cdb44aead537bbf727de9b044e107a0f1220392177d15b0f26" +dependencies = [ + "windows-core 0.62.2", + "windows-link", +] + +[[package]] +name = "windows-registry" +version = "0.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "02752bf7fbdcce7f2a27a742f798510f3e5ad88dbe84871e5168e2120c3d5720" +dependencies = [ + "windows-link", + "windows-result 0.4.1", + "windows-strings 0.5.1", +] + +[[package]] +name = "windows-result" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1d1043d8214f791817bab27572aaa8af63732e11bf84aa21a45a78d6c317ae0e" +dependencies = [ + "windows-targets", +] + +[[package]] +name = "windows-result" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5" +dependencies = [ + "windows-link", +] + +[[package]] +name = "windows-strings" +version = "0.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4cd9b125c486025df0eabcb585e62173c6c9eddcec5d117d3b6e8c30e2ee4d10" +dependencies = [ + "windows-result 0.2.0", + "windows-targets", +] + +[[package]] +name = "windows-strings" +version = "0.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7837d08f69c77cf6b07689544538e017c1bfcf57e34b4c0ff58e6c2cd3b37091" +dependencies = [ + "windows-link", +] + +[[package]] +name = "windows-sys" +version = "0.52.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d" +dependencies = [ + "windows-targets", +] + +[[package]] +name = "windows-sys" +version = "0.59.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1e38bc4d79ed67fd075bcc251a1c39b32a1776bbe92e5bef1f0bf1f8c531853b" +dependencies = [ + "windows-targets", +] + +[[package]] +name = "windows-sys" +version = "0.61.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc" +dependencies = [ + "windows-link", +] + +[[package]] +name = "windows-targets" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973" +dependencies = [ + "windows_aarch64_gnullvm", + "windows_aarch64_msvc", + "windows_i686_gnu", + "windows_i686_gnullvm", + "windows_i686_msvc", + "windows_x86_64_gnu", + "windows_x86_64_gnullvm", + "windows_x86_64_msvc", +] + +[[package]] +name = "windows-threading" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3949bd5b99cafdf1c7ca86b43ca564028dfe27d66958f2470940f73d86d75b37" +dependencies = [ + "windows-link", +] + +[[package]] +name = "windows_aarch64_gnullvm" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3" + +[[package]] +name = "windows_aarch64_msvc" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469" + +[[package]] +name = "windows_i686_gnu" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b" + +[[package]] +name = "windows_i686_gnullvm" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66" + +[[package]] +name = "windows_i686_msvc" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66" + +[[package]] +name = "windows_x86_64_gnu" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78" + +[[package]] +name = "windows_x86_64_gnullvm" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d" + +[[package]] +name = "windows_x86_64_msvc" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec" + +[[package]] +name = "winit" +version = "0.30.13" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a6755fa58a9f8350bd1e472d4c3fcc25f824ec358933bba33306d0b63df5978d" +dependencies = [ + "ahash", + "android-activity", + "atomic-waker", + "bitflags 2.13.2", + "block2 0.5.1", + "bytemuck", + "calloop 0.13.0", + "cfg_aliases", + "concurrent-queue", + "core-foundation 0.9.4", + "core-graphics", + "cursor-icon", + "dpi", + "js-sys", + "libc", + "memmap2", + "ndk", + "objc2 0.5.3", + "objc2-app-kit 0.2.2", + "objc2-foundation 0.2.2", + "objc2-ui-kit", + "orbclient", + "percent-encoding", + "pin-project", + "raw-window-handle", + "redox_syscall 0.4.1", + "rustix 0.38.44", + "sctk-adwaita", + "smithay-client-toolkit 0.19.2", + "smol_str", + "tracing", + "unicode-segmentation", + "wasm-bindgen", + "wasm-bindgen-futures", + "wayland-backend", + "wayland-client", + "wayland-protocols", + "wayland-protocols-plasma", + "web-sys", + "web-time", + "windows-sys 0.52.0", + "x11-dl", + "x11rb", + "xkbcommon-dl", +] + +[[package]] +name = "winnow" +version = "1.0.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "23b97319f7b8343df12cc98938e5c3eb436064524c8d2b4e30a1d3a36eecdf81" +dependencies = [ + "memchr", +] + +[[package]] +name = "wit-bindgen" +version = "0.57.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e" + +[[package]] +name = "writeable" +version = "0.6.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3ad82d2a33cdc9674dc7465672f271e096168fcdbe0f799d9e6db8c5892679dc" + +[[package]] +name = "x11-dl" +version = "2.21.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "38735924fedd5314a6e548792904ed8c6de6636285cb9fec04d5b1db85c1516f" +dependencies = [ + "libc", + "once_cell", + "pkg-config", +] + +[[package]] +name = "x11rb" +version = "0.13.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9993aa5be5a26815fe2c3eacfc1fde061fc1a1f094bf1ad2a18bf9c495dd7414" +dependencies = [ + "as-raw-xcb-connection", + "gethostname", + "libc", + "libloading", + "once_cell", + "rustix 1.1.6", + "x11rb-protocol", +] + +[[package]] +name = "x11rb-protocol" +version = "0.13.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ea6fc2961e4ef194dcbfe56bb845534d0dc8098940c7e5c012a258bfec6701bd" + +[[package]] +name = "xattr" +version = "1.7.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "963d6fab92d5504b971dc8bd90ca743c2575e590bc8071ea5bc571598667ae08" +dependencies = [ + "libc", + "rustix 1.1.6", +] + +[[package]] +name = "xcursor" +version = "0.3.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "163b33ed8786455e2fa5d72f554057ce3f3182425434f756cd39c99839d88e23" + +[[package]] +name = "xkbcommon-dl" +version = "0.4.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d039de8032a9a8856a6be89cea3e5d12fdd82306ab7c94d74e6deab2460651c5" +dependencies = [ + "bitflags 2.13.2", + "dlib", + "log", + "once_cell", + "xkeysym", +] + +[[package]] +name = "xkeysym" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b9cc00251562a284751c9973bace760d86c0276c471b4be569fe6b068ee97a56" + +[[package]] +name = "xml-rs" +version = "0.8.29" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e450f9b2ed1dff33c94c12589a87338689467b9c4f5d8a5710bd09a847d2c8a7" + +[[package]] +name = "xmlwriter" +version = "0.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ec7a2a501ed189703dba8b08142f057e887dfc4b2cc4db2d343ac6376ba3e0b9" + +[[package]] +name = "yazi" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e01738255b5a16e78bbb83e7fbba0a1e7dd506905cfc53f4622d89015a03fbb5" + +[[package]] +name = "yoke" +version = "0.8.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "417ef3fcf6c300b7dbd25c85531a746931c02ad536f3cf4786ed1e88223340b3" +dependencies = [ + "stable_deref_trait", + "yoke-derive", + "zerofrom", +] + +[[package]] +name = "yoke-derive" +version = "0.8.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ec8ebde2db3681e8c9980cc27822030e68752690ddfa9473e739aeb4dbde6d71" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.9", + "synstructure", +] + +[[package]] +name = "zbus" +version = "5.19.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5db4be7c075cb421e4b7ee645541604239bd243ba7c357511f4ff3a74b555907" +dependencies = [ + "async-broadcast", + "async-executor", + "async-io", + "async-lock", + "async-process", + "async-recursion", + "async-task", + "async-trait", + "blocking", + "enumflags2", + "event-listener", + "futures-core", + "futures-lite", + "hex", + "libc", + "ordered-stream", + "rustix 1.1.6", + "serde", + "serde_repr", + "tracing", + "uds_windows", + "uuid", + "windows-sys 0.61.2", + "winnow", + "zbus_macros", + "zbus_names", + "zvariant", +] + +[[package]] +name = "zbus_macros" +version = "5.19.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2990635d09ade6df1868f72f8cac69a876a90981e8bd3c40b1be413f8dc88f40" +dependencies = [ + "proc-macro-crate", + "proc-macro2", + "quote", + "syn 3.0.9", + "zbus_names", + "zvariant", + "zvariant_utils", +] + +[[package]] +name = "zbus_names" +version = "4.3.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "812a12be4ead7a59e18ea8f047d08add0066b73bc62fc1467066a2472ae088dd" +dependencies = [ + "serde", + "winnow", + "zvariant", +] + +[[package]] +name = "zcheapstr" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d1afec51604565183aeb5c54c20aeab286120d4e4460f7f76e3e8bb8c0d99473" +dependencies = [ + "serde", +] + +[[package]] +name = "zeno" +version = "0.3.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6df3dc4292935e51816d896edcd52aa30bc297907c26167fec31e2b0c6a32524" + +[[package]] +name = "zerocopy" +version = "0.8.63" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e5fe1f8f1b06191a00962174c61aa5005e0bb391a6d80d07e24d115c01a92ed8" +dependencies = [ + "zerocopy-derive", +] + +[[package]] +name = "zerocopy-derive" +version = "0.8.63" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "863ad3ac83293fb4d740aedbfdc9240dd8d1a50c1099acd76ce80ce7c7230c7f" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "zerofrom" +version = "0.1.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0ec05a11813ea801ff6d75110ad09cd0824ddba17dfe17128ea0d5f68e6c5272" +dependencies = [ + "zerofrom-derive", +] + +[[package]] +name = "zerofrom-derive" +version = "0.1.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f75b4683f6c7f45248d4d64056a24298c6281e0993356d7d1b4a1a962ef10d4a" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.9", + "synstructure", +] + +[[package]] +name = "zeroize" +version = "1.9.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e13084392c5e4bc371903e2935a5eaeed24905a7511356b883835e18a78f6879" + +[[package]] +name = "zerotrie" +version = "0.2.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4ea269c3bd32f0a32c321907a2ae912ba6f4649bb0fc764a15627e99a7095a3f" +dependencies = [ + "displaydoc", + "yoke", + "zerofrom", +] + +[[package]] +name = "zerovec" +version = "0.11.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f58a2799cfe9a1670c7ea8edbd52ef8edb93cb37a7f83bf31ba9e35d9dae6a40" +dependencies = [ + "yoke", + "zerofrom", + "zerovec-derive", +] + +[[package]] +name = "zerovec-derive" +version = "0.11.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c3743ddbf47738d929cd1ae2e199d40d0162979dfe31aef8ae646d2bf00bf97a" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.9", +] + +[[package]] +name = "zip" +version = "9.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1156b39d142a34b999c2310a50455e0cb3760bf7efad0122f796d813bee26ccb" +dependencies = [ + "crc32fast", + "flate2", + "getrandom 0.4.3", + "indexmap", + "memchr", + "nix", + "typed-path", + "windows-sys 0.61.2", +] + +[[package]] +name = "zlib-rs" +version = "0.6.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b268e58e7c693d7c271f93ffc4ba3b380412554231c85bf61ca7af91042a4112" + +[[package]] +name = "zmij" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b" + +[[package]] +name = "zune-core" +version = "0.4.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3f423a2c17029964870cfaabb1f13dfab7d092a62a29a89264f4d36990ca414a" + +[[package]] +name = "zune-core" +version = "0.5.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d56377fd46368984a170bc5aac5567e52ca5da874caa60bea39fcbca78fb658b" + +[[package]] +name = "zune-jpeg" +version = "0.4.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "29ce2c8a9384ad323cf564b67da86e21d3cfdff87908bc1223ed5c99bc792713" +dependencies = [ + "zune-core 0.4.12", +] + +[[package]] +name = "zune-jpeg" +version = "0.5.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "27bc9d5b815bc103f142aa054f561d9187d191692ec7c2d1e2b4737f8dbd7296" +dependencies = [ + "zune-core 0.5.3", +] + +[[package]] +name = "zvariant" +version = "5.15.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "80bf6d6cd6a4b601acb64cfb8284cdc643fcfa75ef26ae3c46ec8aa4e8a1fbb7" +dependencies = [ + "endi", + "enumflags2", + "serde", + "winnow", + "zcheapstr", + "zvariant_derive", + "zvariant_utils", +] + +[[package]] +name = "zvariant_derive" +version = "5.15.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ef2672456ba1cb54b5eaec136e63135b3c7495fb938e53b28a62e633496d486d" +dependencies = [ + "proc-macro-crate", + "proc-macro2", + "quote", + "syn 3.0.9", + "zvariant_utils", +] + +[[package]] +name = "zvariant_utils" +version = "4.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bad0294361a320b694a328460dc73add56c306150f5cb6bfafc44446120008a3" +dependencies = [ + "proc-macro2", + "quote", + "serde", + "syn 3.0.9", + "winnow", +] diff --git a/Cargo.toml b/Cargo.toml new file mode 100644 index 0000000..cac3151 --- /dev/null +++ b/Cargo.toml @@ -0,0 +1,164 @@ +[workspace] +resolver = "2" +members = [ + "crates/core", + "crates/agent", + # M85（D26）：UI 框架无关的宿主层。Slint 版（crates/app）与 iced 版（crates/app-iced） + # 共用它；Slint 退役（M118 起 `crates/app` 已不是 workspace 成员）后只剩 iced 依赖，本 crate 不受影响。 + "crates/presenter", + "crates/cli", + "crates/design", + # P4（D26 iced 重写）第一步：与 Slint 版 `crates/app` 并存的新 UI crate。 + # bin 名 `unlucky-launcher-iced`，翻牌时才改名（见 DevDocs/SubAgentsTalk/app-iced-骨架与翻牌.md）。 + # M118 起它是发布矩阵里**唯一**的 GUI 来源：发布了 Slint 版的那个 bin 名属于被排除的 `crates/app`。 + "crates/app-iced", + # M87（D40 第 2 层）：配色取色的解码适配层。**唯一**允许引入 `image` 类依赖的地方， + # 使 `crates/design` 能继续宣称「零第三方依赖」。 + "crates/palette-extract", + # M92（D28）：国际化地基——语言探测 / 中英消息目录 / 中文字体策略。零第三方依赖、零 UI 依赖， + # 壳层（iced 版现在，别的壳将来）与 presenter 都依赖它，所以它不能认任何一个渲染框架。 + "crates/i18n", +] +# M118（D26）：`crates/app` 是 Slint 退役树 —— UI 已迁到 iced，目录与源码**原样保留**作历史 +# 参考（另一份参考资产见 DevDocs/ops/slint-reference/），但不再进默认构建与发布矩阵。摘出去的 +# 是整棵 slint 1.18 + usvg 0.48 依赖树：本机单路冷编 ≈14 分钟，而 CI 的 `--workspace` 每次都会 +# 编它，既拖长反馈，又会在并行超配时随机 OOM（见 DevDocs/00-踩坑记录-p2.md T7）。 +# 排除 ≠ 删除，但**它确实不再可编**：该 manifest 整份都是 `*.workspace = true` 继承写法， +# 一旦不是 workspace 成员，继承无源、manifest 解析即失败（实测： +# `cargo metadata --manifest-path crates/app/Cargo.toml` → "error inheriting `edition` …"）。 +# 要读这一版实现请直接读源码，别再尝试构建它。 +exclude = ["crates/app"] + +[workspace.package] +version = "0.2.0" +edition = "2021" +license = "Apache-2.0" +authors = ["AskaEth "] +repository = "https://github.com/AskaEth/Unlucky-Launcher" +rust-version = "1.92" +publish = false + +[workspace.dependencies] +# 共享依赖（版本在此集中，各 crate 用 `xxx.workspace = true` 引用） +# M15（core::diagnose）首批使用者：规则正则 / 规则 YAML 解析 / 诊断结果序列化。 +regex = "1" +serde = { version = "1", features = ["derive"] } +serde_json = "1" +# serde_yaml 上游已停维护（RUSTSEC-2024-0320），改用维护中的 API 兼容分支（tower 定案） +serde_yaml_ng = "0.10" + +# M13（core::download）：HTTP + 异步运行时 + 流 + 校验哈希。 +# rustls（ring）而非 native-tls —— 免 OpenSSL/系统证书栈依赖，MinGW 与 Win7 都省事。 +reqwest = { version = "0.12", default-features = false, features = ["rustls-tls", "stream"] } +tokio = { version = "1", features = [ + "rt-multi-thread", + "fs", + "io-util", + "time", + "sync", + "net", + "macros", +] } +futures-util = "0.3" +sha1 = "0.10" +sha2 = "0.10" +# M31（core::auth）：离线账户 UUID 必须与 Minecraft 服务端/HMCL 的 +# `UUID.nameUUIDFromBytes` 逐字节一致 = MD5 + v3 位改写，因此需要 MD5。 +# 与 sha1/sha2 同属 RustCrypto（Apache-2.0 OR MIT），版本对齐 digest 0.10。 +md-5 = "0.10" + +# M29（core::launch::natives）：读 natives jar（zip 容器）解压原生库。 +# 只开 inflate（`deflate-flate2-zlib-rs`，纯 Rust zlib）——解压方向不需要 zopfli 压缩器。 +zip = { version = "9", default-features = false, features = ["deflate-flate2-zlib-rs"] } + +# M33（core::game::java）：Temurin 的 Linux/macOS 产物只发 `.tar.gz`（Windows 是 `.zip`， +# 复用上面的 zip）。flate2/tar 都是纯 Rust + MIT OR Apache-2.0，白名单内。 +flate2 = "1" +tar = "0.4" + +# M87（D40）：配色取色的解码适配层。版本与 `crates/app-iced` 的截图通道对齐（同一份 +# `image` 只编译一次）；编解码器由各 crate 自己按需开 feature，这里只钉版本。 +image = { version = "0.25", default-features = false } + +# UI 层唯一入口（D2：Slint，RF 2.0 轨道）。 +# 默认特性已含 backend-default + renderer-femtovg（GL）+ renderer-software（CPU 软渲染兜底， +# Win7 老机无可用 GPU 时的降级路径，见 DevDocs/PlanDoc/01c-native-gui-options.md §6）。 +slint = "1.18" +# app 的 build script 用（把 ui/main.slint 编译成 Rust 代码），版本必须与 slint 主 crate 同步。 +slint-build = "1.18" + +# agent 层依赖（rig / rmcp）按 D4 在 M16 引入，脚手架期不引入以免版本冲突。 +# 版本锁定策略见 DevDocs/PlanDoc/02-ai-agent-design.md §0：rig 锁 =0.45.x，rmcp 3.8.x。 +# +# M39 的 MCP server（02 §0「传输定论」）：rmcp 官方 SDK（Apache-2.0），**锁精确版本**—— +# pre-1.0 且 ~6 天一个版、3.x 内已多次改 server API。只开需要的传输 feature： +# - `server`（default 带）+ `transport-io`（stdio，给 llama.cpp 内置 MCP client） +# - `transport-streamable-http-server`（主力：127.0.0.1 上的 Streamable HTTP） +# `macros` 一并留在 default 里（`#[tool]` 宏不用，但 default 拆开易漏 base64 等隐式依赖）。 +rmcp = { version = "=3.8.0", features = [ + "transport-io", + "transport-streamable-http-server", +] } +# rmcp 的 Streamable HTTP server 是个 tower Service，官方示例用 axum 挂监听（MIT）。 +# 只吃 `nest_service` + `serve`，不引入任何 TLS/模板/DB 生态。 +axum = "0.8" + +[workspace.lints.rust] +unsafe_code = "deny" +missing_docs = "warn" +rust_2018_idioms = { level = "warn", priority = -1 } + +[workspace.lints.clippy] +all = { level = "deny", priority = -1 } + +[profile.release] +opt-level = "z" +lto = "fat" +codegen-units = 1 +panic = "abort" +strip = "symbols" + +# P6（M96）：日常迭代 / 本机验收用的「快」档，发布仍走上面的 release。 +# `inherits = "release"` 让其余各项（strip / debug / overflow-checks …）照抄 release， +# 只覆盖拖慢构建的四处： +# - lto = "thin"：跨 crate 内联仍有，但可以并行；fat LTO 在 codegen-units = 1 下等于 +# 全程序串行链接（375 个 crate 排队），一次性吃掉十几分钟。 +# - codegen-units = 16：给 codegen 留并行度，不再把整个 crate 挤成一个 CGU。 +# - opt-level = 2：介于 "z" 与 3 之间，"z" 会为了体积关掉一批循环/内联优化，代价是运行期。 +# - panic = "unwind"：release 是 panic = "abort"，inherits 会照抄。留着它是为了让 fast 档编出来的 +# **二进制**走 unwind（panic 会栈展开，不是直接 abort）。 +# ⚠️ 理由不是「不写就跑不了测试」：`cargo test` **不**依赖这一行 —— cargo 对 test 目标自己强制 +# unwind。实测 `cargo test --profile release -p unlucky-i18n`（release = abort 档）照跑，23 个 +# 测试全过，且 test 单元的 rustc 参数里**没有** `-Cpanic=`。别拿「cargo test 能跑」当这行生效的证据； +# 要看就用 `cargo build --profile {fast,release} -v` 比 rustc 参数：release 有 `panic=abort`，fast 没有。 +# +# ⚠️ 定位（实测，别误读）：本机（12 核 + 机械盘源码盘 + -j 4）冷编译 fast = 24m27s， +# **比 release 的 16m01s 还慢**，体积是 2.3 倍（36.41 vs 15.72 MiB GUI）。瓶颈在两个大 +# UI crate 的编译 + 链接 + 磁盘 IO，LTO/CGU 这几个旋钮被掩盖了。它的价值在 **SSD 机器**和 +# **增量重编**（thin 不必每次全程序 LTO）；「加了 fast 档」≠「冷编译会变快」。 +[profile.fast] +inherits = "release" +opt-level = 2 +lto = "thin" +codegen-units = 16 +panic = "unwind" + +# P6（M96）：依赖不需要为体积做极致优化，但**实测结论与直觉相反**——把依赖的 opt-level 从 +# release 的 "z" 抬到 3（本档最初就是这么定的）会让冷编译**更慢**、体积还更大： +# 同机冷编译 opt-3 = 22m45s / 19.46 MiB（GUI），opt-"z" = 16m01s / 15.72 MiB（两臂同为 cu16）。 +# 所以这里**opt-level 保持 "z"，只把并行度放到 16**；workspace 自己的 crate 仍吃 "z" / 单 CGU。 +# ⚠️ **未测**：cu1 → cu16 的收益本轮没有同条件对照（两臂都是 cu16，唯一自变量是 opt-level）， +# 所以「cu16 才是收益来源」不是实测结论，要归因得单独跑一轮 cu1 对照。另：GUI 体积相对旧基线 +# 涨了 12.9%（13.92 → 15.72 MiB），其中「代码增长」与「依赖 cu16」也没分离。 +# **只调优化强度**：panic 与 strip 绝不写进这里。那两项改变的是整个二进制的运行时行为 +# （panic 策略决定能否 unwind 出栈、strip 决定符号表留不留），不是「给依赖放宽」的范畴。 +[profile.release.package."*"] +opt-level = "z" +codegen-units = 16 + +# `inherits = "release"` 会把 `[profile.release.package."*"]` **一起继承过来**（实测：删掉下面这块， +# fast 档的外部依赖就从 opt-level 2 退回 `"z"`；workspace 成员不受 `*` 覆盖、仍是 fast 自己的 2）。 +# 所以这块**必须存在**，它是承重墙不是冗余兜底 —— 删掉会让 fast 档的依赖静默退回 `"z"`。 +[profile.fast.package."*"] +opt-level = 2 +codegen-units = 16 diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..97bdc46 --- /dev/null +++ b/LICENSE @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2026 AskaEth (YeiJ) + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/NOTICE b/NOTICE new file mode 100644 index 0000000..9cf081c --- /dev/null +++ b/NOTICE @@ -0,0 +1,66 @@ +Unlucky-Launcher (ULL) +Copyright 2026 AskaEth (YeiJ) + +本产品采用 Apache License 2.0（见 LICENSE）。 + +-------------------------------------------------------------------------- +第三方组件声明 +-------------------------------------------------------------------------- + +1. Slint（https://slint.dev）——**历史源码，不随任何产物分发** + + 本产品**当前发布的 GUI 框架是 iced**（见第 3 节），二进制里不含任何 Slint 代码。 + 仓库里仍保留 Slint 版 GUI 的源码（`crates/app`），仅作历史参考：它已被 cargo workspace + `exclude`，不参与构建、测试与发布，也不会进入本项目的任何 Release 资产。 + + 因此 Slint Royalty-Free 2.0（LicenseRef-Slint-Royalty-free-2.0）**对当前产物不适用**；它适用的是 + 此前已发布、且确实链接了 Slint 的 `v0.1.0` 构建——义务挂在每一次「随应用分发」上，而不是挂在某个 + 版本号上。上游许可 §2 给出两种形式：(a) 在可从顶层菜单进入的「关于」页/对话框里显示官方 + `AboutSlint` 部件（没有该页时改为启动画面）；(b) 在可下载该二进制的公开网页上显示官方归属徽章。 + **`v0.1.0` 的设置页「关于」分组里内置了 `AboutSlint` 部件**（`crates/app/ui/pages/settings.slint`， + 从侧栏进入）；该部件是否满足 §2(a) 的全部条件、以及 `v0.1.0` 发布页上那是文字链接而不是 §2(b) 点名的 + 官方徽章图这两点，**本文件不作法律判断**，具体以 Slint 官方许可原文为准。`v0.1.0` 的 NOTICE、发布页 + 说明与本文件这一节**都只是记录，不构成履行声明**。后续版本不再链接 Slint，该义务不随新产物新增； + 本文件保留这一节，是为了不让这段历史丢失，而不是声明本产品依赖 Slint。 + + 若将来重新把 `crates/app` 纳入构建并发布链接 Slint 的二进制，该义务随之恢复——届时需同时恢复 + AboutSlint 部件/徽章与本节的现行声明。Slint 的其余许可分支（GPL-3.0-only / Slint Software + License 3.0）本项目始终不适用。 + +2. Google Material Color Utilities（https://github.com/material-foundation/material-color-utilities） + + 本产品的色彩令牌（crates/design 的 color 模块）是 Material 3 色彩算法（HCT 色彩空间 + + ColorSpec2021 调色板/角色映射）的 **Rust 重写移植**，依据 Apache License 2.0 使用，未把其任何语言的源码作为依赖 + 引入；除下面注明的那张生成常数表外，也没有复制其代码文件。 + + 实际移植的部分（均为纯算法，逐函数对照后以 Rust 重写）： + + - `hct/Cam16.java`、`hct/ViewingConditions.java`、`hct/Hct.java` → `crates/design/src/color/cam16.rs`、 + `viewing_conditions.rs`、`hct.rs`（CAM16 色相/彩度 + CIELAB `L*` 亮度） + - `hct/HctSolver.java` → `crates/design/src/color/hct_solver.rs` + `critical_planes.rs` + （色域映射求解器；其中 255 项 `CRITICAL_PLANES` 常数表是原样搬运的生成数据） + - `utils/ColorUtils.java`、`utils/MathUtils.java` → `crates/design/src/color/space.rs` + - `palettes/TonalPalette.java`、`dynamiccolor/ColorSpec2021.java`、`dynamiccolor/DynamicScheme.java` + → `crates/design/src/color/tonal.rs`、`palettes.rs`、`scheme.rs`（Tonal Spot 变体的彩度常数与 + 49 个角色的 tone 映射） + + 对齐验证：`crates/design/tests/official_baseline.rs` 与 `tests/official_accent.rs` 的期望色值， + 是把上述官方 Java 实现（Apache-2.0）在本机编译运行后输出的结果抄本——合计 290 项逐通道 + 比对（baseline 49 角色 × 2 模式 = 98 项；强调色 8 个种子 × 12 个强调族角色 × 2 模式 = 192 项）， + 误差上限 1（实测为 0）。两文件的表头各写着自己的分项口径。 + + Apache License 2.0 全文见 https://www.apache.org/licenses/LICENSE-2.0 + 上游版权声明：Copyright Google LLC。 + +3. Rust crates 生态 + + 当前 GUI 框架：iced 0.14（MIT），连同 winit（Apache-2.0）、wgpu（MIT OR Apache-2.0）、 + tiny-skia（BSD-3-Clause）——它们都在下面的白名单内。 + cargo-deny 白名单见 deny.toml：Apache-2.0 / MIT / BSD-2-Clause / BSD-3-Clause / Zlib / BSL-1.0 / ISC / + CC0-1.0 / MIT-0 / Unlicense / Unicode-3.0 / CDLA-Permissive-2.0 / Apache-2.0 WITH LLVM-exception。 + GPL 系（含 AGPL、LGPL 静态链接、SSPL）依赖不得进入主干。 + +4. 参考实现致谢 + + 本项目设计参考自 HMCL（https://github.com/HMCL-dev/HMCL）与 PCL2 + （https://github.com/Meloong-Git/PCL），两者均为 GPL-3.0，特此致谢。 diff --git a/README.md b/README.md new file mode 100644 index 0000000..8858d2c --- /dev/null +++ b/README.md @@ -0,0 +1,243 @@ +# Unlucky Launcher (ULL) + +**English** · [简体中文](README.zh-CN.md) + +> **Official project home**: https://github.com/AskaEth/Unlucky-Launcher ｜ downloads, issues and +> release notes all live there: + +Unlucky Launcher (ULL) is a free, open-source Minecraft: Java Edition launcher written in Rust +(Apache-2.0). It ships as one native binary per platform — no installer, no bundled runtime, no +WebView. The launcher embeds an AI agent client (chat / configuration / crash diagnosis) and can be +attached to other agent tooling as an MCP server. + +## Highlights + +- **Single-file native binary**: the launcher itself needs no JVM, no WebView and no sidecar + runtime. The JDK a game needs is downloaded and managed per instance, not as a launcher + dependency. +- **One binary, two shapes**: the GUI binary also answers every CLI subcommand before any UI code + runs — no window, no renderer probe, no font scan. A second, lighter `ull` artifact serves the + same command set from a binary that links no graphics stack at all. +- **One UI stack**: iced 0.14 + Material 3 Expressive, with self-drawn title bar, animated + navigation rail, light / dark / follow-system, and a background-image colour pipeline. The earlier + Slint implementation (`crates/app`) is kept as source-only history: excluded from the cargo + workspace, never built, tested or shipped. +- **CPU software-rendering fallback**: `--software-renderer` keeps the interface rendering normally + on machines with no usable GPU or with broken drivers; the backend probe falls back on its own when + no adapter is usable. +- **AI agent + MCP**: chat, setting edits and crash diagnosis inside the launcher; `ull agent serve` + exposes the same core as an MCP server (stdio or Streamable HTTP) to external agent tools. The + agent rail runs on real presenter state, and says so plainly when no model endpoint is wired. +- **Mod loaders and modpacks**: Fabric, Quilt, NeoForge, Forge; CurseForge manifest, Modrinth + `.mrpack` and MultiMC/Prism packs import, plus mrpack / CurseForge export. +- **Java management**: a Temurin → Oracle → Microsoft → Zulu fallback chain, region-aware. +- **Accounts**: Microsoft sign-in over OAuth 2.0 device code flow → Xbox Live → XSTS → + `api.minecraftservices.com`; third-party community auth servers; local offline profiles for + isolated testing. Account tokens are kept on this machine only. +- **Engine**: multi-source download (health scoring, mirrors, chunked transfers, hash while + downloading) and a YAML rule-based crash diagnosis engine. +- **License**: Apache-2.0 © AskaEth (YeiJ). + +## Status + +`v0.1.0` (2026-11-01) predates the UI rewrite: its assets are Slint builds, and it stays the last +Slint tag. `v0.2.0` is the first tag after the rewrite — the iced line, which is what the release +pipeline builds now. Everything described below lives on that line. + +- **The iced UI is feature-complete**: fourteen pages — instances, version management (three-column + rail layout with search), content library (modpacks / mods / resource packs / shaders with source + and version filters), logs, settings (general / appearance / Java / downloads), accounts + (Microsoft device code, third-party community servers, local profiles), the AI rail and the + installer flows — on top of one component library and one token set. +- **Localisation follows the system language**: detection, an explicit override in settings, and + persistence across restarts. UI copy goes through a single message catalogue; there is no + hard-coded string in the view layer. +- **Appearance**: window background image, per-panel transparency and whole-window transparency + (Windows), light / dark / follow-system, and system window corners where the platform grants them. + On CPU rendering the translucent layers are switched off and the UI says so. +- **Packaging and the installer paths** (curseforge / modrinth / multimc import, mrpack and + CurseForge export, install options with loader selection and real cancellation) are in the build. +- **What is not done yet**: installers / auto-update channel; macOS re-verification on a real + machine after the Windows pass; per-file conflict policy on pack import (the import pipeline has one + global policy today, and the UI states that rather than pretending otherwise); a native file + chooser (import accepts drag-and-drop and a pasted path). + +Binaries you may run into, so you can tell them apart: + +| Binary | Crate | State | +|--------|-------|-------| +| `unlucky-launcher-iced` | `crates/app-iced` (iced 0.14) | the GUI binary the workspace builds; the release pipeline stages it under the public name `unlucky-launcher`; the same binary answers every CLI subcommand | +| `unlucky-launcher` | `crates/app` (Slint) | **historical**: that crate is excluded from the workspace, so this binary is no longer built or shipped; the v0.1.0 assets are the last Slint builds | +| `ull` | `crates/cli` | the zero-UI build of the same command set, shipped as its own asset | + +`unlucky-launcher` (the GUI) and `ull` are not duplicates. The GUI binary needs the graphics stack +when it opens a window (it `dlopen`s X11 / Wayland / GL, and links `libfontconfig` at load); `ull` +needs nothing beyond glibc, so it runs on a server, a CI container or Termux where no window can +exist. Pick `ull` when there is no desktop, `unlucky-launcher ` when there is. Both print the +same CLI text and name themselves after the binary you invoked: `unlucky-launcher --help` starts with +`unlucky-launcher ·`, `ull --help` starts with `ull ·`. + +### Subcommand dispatch + +`unlucky-launcher ` first asks "is this a CLI call?" before any UI code runs: + +```bash +unlucky-launcher # GUI +unlucky-launcher --software-renderer # GUI, CPU renderer (unchanged) +unlucky-launcher instances list # CLI, no window +unlucky-launcher --json launch 1.20.1 # CLI, global options before the command +unlucky-launcher --version # CLI, prints version + OS summary +``` + +The rule is deliberately narrow, so nothing that used to work changed meaning: + +- The first argument is a bare word (not `-…`) → it sits in the subcommand position, so the CLI gets + it. GUI flags never appear there: `--screenshot` / `--diff` / `--data-dir` take their values + *after* the flag. +- The first argument is a flag → the line is a CLI call only if `crates/cli`'s parser also produces a + real command (`--help`, `--version`, `--json instances list`). `--data-dir X` alone parses to "no + subcommand", so it still opens the GUI; every GUI-only flag (`--software-renderer`, + `--screenshot*`, `--renderer`, `--theme`, `--diff`, `--force-state`, …) fails CLI parsing, so it + still opens the GUI. + +**Unknown subcommands are an error, not a GUI launch**: `unlucky-launcher lst` prints +"未知命令 `lst`", hints `unlucky-launcher --help`, and exits 1. Silently opening a window would tell +a script that its typo took effect. The subcommand table itself lives in exactly one place — +`crates/cli/src/cli/parse.rs` — so both the GUI binary and `ull` accept the same set by construction. + +## Module map + +``` +Unlucky-Launcher (cargo workspace) +├── crates/core # domain library: zero UI dependencies, eight modules +├── crates/agent # AI agent: ToolSpec registry + built-in client + MCP server (one core, two shapes) +├── crates/presenter # business host layer: framework-free state / host / dto / conversion +├── crates/design # design tokens: real HCT color / type / shape / spacing / elevation / motion / icons +│ # / component metrics — zero UI dependencies, no third-party crates +├── crates/i18n # language detection, message catalogue, CJK font policy +├── crates/palette-extract # the only crate that decodes images, for the wallpaper colour pipeline +├── crates/app # HISTORICAL Slint UI (bin `unlucky-launcher`): excluded from the workspace, +│ # source-only reference — never built, tested or shipped any more +├── crates/app-iced # the iced UI (bin `unlucky-launcher-iced`): the only GUI the workspace builds +├── crates/cli # CLI (bin `ull`): headless, zero UI +└── packaging # single-file artifact matrix and release scripts +``` + +Layering: `app-iced` → `presenter` → `core` / `agent`. `design` and `i18n` are consumed by the shell +and the presenter; none of them may depend on a rendering framework, and the guards enforce it. + +The eight modules of `crates/core`: + +| Module | Responsibility | +|--------|----------------| +| `setting` | three data-directory modes, schema-based config, atomic writes, migrations | +| `download` | multi-source health scoring, mirrors, chunked downloads, hash-while-downloading | +| `game` | version / instance repository, snapshots and inheritance resolution | +| `launch` | 10-stage launch pipeline, processes, JSONL event stream | +| `auth` | Microsoft sign-in (OAuth 2.0 device code → Xbox Live → XSTS → Minecraft Services), third-party community servers, local profiles | +| `addon` | mod loader installation, modpack import, CurseForge / Modrinth, pack export | +| `diagnose` | five signal collectors, YAML rule engine, hs_err parsing | +| `platform` | OS abstraction: paths, processes, file locks, capability probing, runtime OS detection | + +## Building + +Prerequisites: + +- Rust stable (`rust-toolchain.toml` selects the toolchain automatically; the gates also need the + `rustfmt` and `clippy` components) +- Windows: MSVC toolchain (what CI uses) or MinGW-w64 (`x86_64-pc-windows-gnu`) +- Linux: `libxkbcommon-dev libfontconfig1-dev libgl1-mesa-dev libegl1-mesa-dev libwayland-dev + libxcb1-dev` — winit + wgpu/tiny-skia ask for these at build time + +```bash +cargo fmt --all --check # formatting +cargo clippy --workspace --all-targets -- -D warnings # lints (zero-warning gate) +cargo test --workspace # tests +cargo build --release # binaries land in target/release/ +``` + +`--workspace` covers the members in the module map. `crates/app` is excluded at the workspace level +(M118), so none of these commands compiles the Slint tree — and there is no build command for it: +that crate is kept as source-only reference and can no longer be built as a workspace member. + +What the build produces: + +- `unlucky-launcher-iced` — the GUI (iced). It is also the CLI: the same binary answers every + subcommand listed above. The name is temporary — it becomes `unlucky-launcher` at the flip. The + release artifacts already carry the public name: the pipeline builds this bin and + `packaging/make_artifacts.py` stages it as `unlucky-launcher[.exe]`, so download links never change. +- `unlucky-launcher` — **historical**: no workspace build produces this binary any more; it belonged + to `crates/app`, which is excluded. The v0.1.0 assets are the last builds under this name. +- `ull` — the CLI as a standalone, UI-free binary. Same command set, no graphics stack, smaller, and + the right artifact for a machine that has no display at all. + +Rendering switches: + +- `unlucky-launcher-iced --software-renderer` forces tiny-skia (`ICED_BACKEND=tiny-skia`); + `--screenshot ` writes one frame and exits, which is the acceptance channel CI's headless + smoke job uses +- With no usable adapter the iced build's explicit probe falls back to the CPU path on its own +- **Historical** (v0.1.0's Slint build still takes it): `unlucky-launcher --software-renderer`, i.e. + `SLINT_BACKEND=winit-software`, forced the CPU renderer of that build through its own fallback chain + +Dependency license check (optional locally, required in CI): +`cargo deny check licenses bans sources`. + +## CI gates + +Every push to `main` and every pull request runs fmt / clippy (warnings are errors) / the full test +suite, and the Linux headless render smoke is a hard gate on the same footing: a red result blocks +the merge. The macOS runtime probe is not there yet — it only runs on a manual `workflow_dispatch` +and its result is recorded, not enforced (`continue-on-error`), until the slot passes a first run on +a real runner. + +| Workflow | Content | +|----------|---------| +| `.github/workflows/ci.yml` | fmt + clippy + test + release build (Windows / Linux matrix); Linux runtime smoke (Xvfb: renders one real frame, then asserts the PNG is not blank); macOS runtime probe (manual dispatch only) | +| `.github/workflows/guards.yml` | zero-UI guards (`crates/core`, `crates/presenter`, `crates/design`), 400-lines-per-file guard, cargo-deny license and source guard | +| `.github/workflows/release.yml` | tag `v*` → per-slot builds → single-file artifacts + `SHA256SUMS.txt` → GitHub Release | + +## Platform baseline + +Minimum baseline: **Windows 10**; Windows 8.1 / 8 / 7 are not supported. + +- Windows 10/11 builds use the **standard toolchain** (MSVC / GNU), built the same way as + upstream cargo +- macOS 12+ (Apple Silicon and Intel) and Linux x64 / arm64 are supported build slots; on Linux, + X11 is the preferred path today and Wayland is the long-term direction. macOS builds are unsigned, + so the first launch needs the Gatekeeper quarantine attribute cleared + (`xattr -d com.apple.quarantine`) +- Android Termux is experimental and not promised: CLI only, GUI unverified +- Each platform runs its own test matrix; capability differences use feature gates with runtime + probing. + +## License and acknowledgements + +- **This project**: Apache License 2.0, see [LICENSE](LICENSE); third-party notices in + [NOTICE](NOTICE). +- **Slint** (), Royalty-Free 2.0: obligation for the Slint build that `v0.1.0` + ships — the condition attaches to each distribution of an Application, not to a version number. + Upstream §2 offers two forms: (a) the official `AboutSlint` widget on an "About" screen or dialog + reachable from the top level menu (or the splash screen when there is none); (b) the official Slint + attribution badge on a public page where the binaries can be downloaded. **`v0.1.0`'s settings page + does embed the `AboutSlint` widget** (`crates/app/ui/pages/settings.slint`, reachable from the + sidebar); whether that satisfies §2(a), and the fact that the `v0.1.0` release page carries a text + link rather than the §2(b) badge, are **not judged here** — Slint's own licence text is the + authority. The `v0.1.0` NOTICE, that page's text and this section are **records, not a statement of + discharge**. Later builds link no Slint, so they add nothing to this obligation. The obligation + follows a **Slint-linked binary**: it applies to the `v0.1.0` assets (and to any later build that + links Slint again), not to new iced builds — `crates/app` is excluded from the workspace, so the + pipeline no longer produces one. +- **iced** (), MIT: the framework of the UI, together with `winit` + (Apache-2.0) and, through it, `wgpu` (MIT / Apache-2.0) / `tiny-skia` (BSD-3-Clause). +- **Google Material Color Utilities** (Apache-2.0): the color tokens in `crates/design` are a Rust + port of its HCT / ColorSpec2021 algorithms; details and the exact ported functions are listed in + [NOTICE](NOTICE). +- **Other major dependencies**: `rmcp` and `axum` (Apache-2.0 / MIT) for the MCP server, `tokio` + (MIT), `reqwest` with rustls (MIT / Apache-2.0), `serde` / `serde_json` (MIT / Apache-2.0), + `zip` / `flate2` / `tar` (MIT / Apache-2.0). The allow-list cargo-deny enforces is in `deny.toml`; + GPL-family dependencies may not enter the main line. + +Thanks to [HMCL](https://github.com/HMCL-dev/HMCL) and [PCL2](https://github.com/Meloong-Git/PCL) +(both GPL-3.0). They have been with the vast majority of Minecraft players for years, and this +project has benefited a great deal from their design choices and implementation details. diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 0000000..6143e5d --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,203 @@ +# Unlucky Launcher (ULL) + +[English](README.md) · **简体中文** + +> **官方项目主页**：https://github.com/AskaEth/Unlucky-Launcher ｜ 下载、议题、发布说明都在这里： +> + +Unlucky Launcher（ULL）是一个用 Rust 写的免费开源 Minecraft: Java 版启动器（Apache-2.0）。 +每个平台就一个原生二进制——没有安装包、没有捆绑运行时、没有 WebView。启动器内置 AI Agent +客户端（对话 / 改配置 / 崩溃诊断），也能作为 MCP server 接进别的 Agent 工具。 + +## 特性 + +- **单文件原生二进制**：启动器本体不需要 JVM、不需要 WebView、不带旁挂运行时。游戏要的 JDK 由 + 启动器按实例下载管理，不是启动器的依赖。 +- **默认构建里只有一套 UI**：UI 是 iced 0.14 + Material 3 Expressive。早先的 Slint 实现 + （`crates/app`）作为**历史参考**保留源码：已被 workspace `exclude`，默认构建不编、测试不跑、 + 发布不发。`v0.1.0` 那个 tag 发的仍是 Slint 版；iced 重写后的第一个 tag 是 `v0.2.0`（见「当前状态」）。 +- **CPU 软渲染兜底**：`--software-renderer` 让没有可用 GPU 或驱动有问题的老机也能正常显示界面。 +- **AI Agent + MCP**：启动器内可对话、改设置、读崩溃诊断；`ull agent serve` 把同一个内核以 MCP + server 形态（stdio 或 Streamable HTTP）开放给外部 Agent 工具。 +- **加载器**：Fabric / Quilt / NeoForge / Forge；整合包与 CurseForge / Modrinth 客户端在 core 里。 +- **Java 管理**：Temurin → Oracle → Microsoft → Zulu 回退链，带地区判定。 +- **账户**：用 Microsoft 账户登录，认证走 OAuth 2.0 device code flow → Xbox Live → XSTS → + `api.minecraftservices.com`；账户令牌只保存在本机。 +- **引擎**：多源下载（健康度评分、镜像、分块传输、边下边算）与 YAML 规则引擎的崩溃诊断。 +- **许可**：Apache-2.0 © AskaEth (YeiJ)。 + +## 当前状态 + +`v0.1.0`（2026-11-01）早于 UI 重写：那批资产是 Slint 版，它也是最后一个 Slint 版 tag。重写之后的 +第一个 tag 是 `v0.2.0`——也就是 iced 这条线，下面说的这套东西都在线上，也正是发布流水线现在会打 +出来的东西。 + +- **iced 版界面功能已齐**：十四页——实例、版本管理（三栏 + 搜索）、内容库（整合包 / Mod / 资源包 / + 光影，带来源与版本筛选）、日志、设置（通用 / 外观 / Java / 下载）、账户（微软设备码、第三方社区服、 + 本地档案）、AI 右栏，以及安装流程——共用一套组件库与一套令牌。 +- **文案跟随系统语言**：自动探测、设置里可显式切换、重启后保持。界面文案统一走一份消息目录，视图层 + 没有硬编码字符串。 +- **外观**：窗口背景图、面板透明度、整窗透明度（Windows）、浅色 / 深色 / 跟随系统，以及在系统愿意给 + 的时候使用系统窗口圆角。CPU 渲染档会关掉半透明层，并在界面上说清楚。 +- **整合包与安装链路都在构建里**：CurseForge 清单 / Modrinth `.mrpack` / MultiMC·Prism 导入，mrpack + 与 CurseForge 导出，安装选项（选加载器）与**真取消**。 +- **还没做**：安装器与自动更新通道；Windows 定型后的 macOS 真机复核；整合包导入的**逐文件**冲突策略 + （当前只有一份全局策略，界面如实写明而不是假装支持）；原生文件选择框（导入支持拖拽与粘贴路径）。 +- **Slint 版已退出构建，只留源码作参考**：`crates/app` 不再是 workspace 成员（M118）——源码留作历史 + 参考，不编译、不测试、不发布，也不再有可用的构建方式。翻牌只剩**改名**这一步：它的 bin 现在叫 + `unlucky-launcher-iced`，发布流水线已经把它按对外名 `unlucky-launcher` 打出去。 + +可能会遇到的 bin，先认清楚： + +| 二进制 | crate | 状态 | +|--------|-------|------| +| `unlucky-launcher-iced` | `crates/app-iced`（iced 0.14） | workspace 里**唯一**的 GUI bin；发布流水线把它按对外名 `unlucky-launcher` 落盘；子命令分发同款 | +| `unlucky-launcher` | `crates/app`（Slint） | **历史**：该 crate 已被 workspace `exclude`，这个 bin 不再被构建或分发；`v0.1.0` 的资产是最后一批 Slint 版 | +| `ull` | `crates/cli` | 同一套命令的零 UI 构建，作为独立资产随发布分发 | + +`unlucky-launcher` 与 `ull` 不是重复品：开窗时 GUI 二进制要用图形栈（X11 / Wayland / GL 走 +`dlopen`，启动时直接链接 `libfontconfig`）；`ull` 除了 glibc 什么都不需要，所以在没有窗口的服务器、 +CI 容器、Termux 上跑得起来。没有桌面就用 `ull`，有桌面就用 `unlucky-launcher <子命令>`。两者打出来的 +CLI 文案是同一套，自称的名字跟着**你敲的那个二进制**走：`unlucky-launcher --help` 首行是 +`unlucky-launcher ·`，`ull --help` 首行是 `ull ·`。 + +### 子命令分发 + +`unlucky-launcher <参数>` 在跑任何 UI 代码之前先问一句「这是不是一次 CLI 调用」： + +```bash +unlucky-launcher # GUI +unlucky-launcher --software-renderer # GUI，CPU 渲染（行为不变） +unlucky-launcher instances list # CLI，不开窗 +unlucky-launcher --json launch 1.20.1 # CLI，全局选项排在子命令前面 +unlucky-launcher --version # CLI，输出版本 + 系统摘要 +``` + +判据刻意收得很窄，所以原本能用的用法一条都没变： + +- 第一个参数是裸词（不以 `-` 开头）→ 它就在子命令的位置上，交给 CLI。GUI 的 flag 永远不会出现在 + 那个位置：`--screenshot` / `--diff` / `--data-dir` 的取值都排在 flag 之后。 +- 第一个参数是 flag → 只有当 `crates/cli` 的解析器也解析出一条真命令时才算 CLI 调用 + （`--help`、`--version`、`--json instances list`）。单独 `--data-dir X` 解析成「没有子命令」， + 仍然开 GUI；GUI 专属参数（`--software-renderer`、`--screenshot*`、`--renderer`、`--theme`、 + `--diff`、`--force-state` 等）在 CLI 里一律解析失败，也仍然开 GUI。 + +**未知子命令是错误，不是开窗**：`unlucky-launcher lst` 打印「未知命令 `lst`」、提示 +`unlucky-launcher --help`，以 1 退出。静默开窗会让脚本以为自己那个拼错的参数生效了。子命令表只有 +一处定义（`crates/cli/src/cli/parse.rs`），所以两个 GUI 二进制和 `ull` 认的命令集天然一致。 + +## 模块地图 + +``` +Unlucky-Launcher (cargo workspace) +├── crates/core # 领域库：零 UI 依赖，八模块 +├── crates/agent # AI Agent：ToolSpec 注册表 + 内置客户端 + MCP server（双形态共用一个内核） +├── crates/presenter # 业务宿主层：与框架无关的 state / host / dto / 转换 +├── crates/design # 设计令牌：真 HCT 色彩 / 排版 / 形状 / 间距 / 高程 / 动效 / 图标 / 组件度量 +│ # —— 零 UI 依赖、零第三方 crate +├── crates/i18n # 语言探测、消息目录、中文字体策略 +├── crates/palette-extract # 唯一解码图片的 crate，供壁纸取色链路使用 +├── crates/app # 历史 Slint UI（bin `unlucky-launcher`）：已被 workspace `exclude`， +│ # 仅作源码参考——不再被构建 / 测试 / 发布 +├── crates/app-iced # iced UI（bin `unlucky-launcher-iced`）：workspace 里唯一的 GUI bin +├── crates/cli # CLI（bin `ull`）：headless，零 UI +└── packaging # 单文件产物矩阵与发布脚本 +``` + +`crates/core` 的八个模块： + +| 模块 | 职责 | +|------|------| +| `setting` | 三模式数据目录、schema 配置、原子写、迁移 | +| `download` | 多源健康度、镜像、分块下载、边下边算 | +| `game` | 版本/实例仓库、快照与继承解析 | +| `launch` | 10 阶段启动管线、进程、JSONL 事件流 | +| `auth` | Microsoft 账户登录（OAuth 2.0 device code → Xbox Live → XSTS → Minecraft Services） | +| `addon` | 加载器安装、整合包、CurseForge / Modrinth | +| `diagnose` | 五类信号采集、YAML 规则引擎、hs_err 解析 | +| `platform` | OS 抽象：路径、进程、文件锁、能力探测、运行期 OS 检测 | + +## 构建 + +前置： + +- Rust stable（`rust-toolchain.toml` 会自动选工具链；门禁还需要 `rustfmt` / `clippy` 组件） +- Windows：MSVC 工具链（CI 用这套）或 MinGW-w64（`x86_64-pc-windows-gnu`） +- Linux：`libxkbcommon-dev libfontconfig1-dev libgl1-mesa-dev libegl1-mesa-dev libwayland-dev + libxcb1-dev`——winit + wgpu/tiny-skia 编译期要用（Slint 版当年还要 femtovg） + +```bash +cargo fmt --all --check # 格式 +cargo clippy --workspace --all-targets -- -D warnings # 静态检查（零 warning 门禁） +cargo test --workspace # 测试 +cargo build --release # bin 落在 target/release/ +``` + +`--workspace` 就是模块地图里那八个成员：`crates/app` 已在 workspace 层被排除（M118），上面这些命令 +都不会编 Slint 那棵树——而且**它没有构建方式**：该 crate 只作源码参考，作为 workspace 成员已不可编。 + +编出来的 bin： + +- `unlucky-launcher-iced`——GUI（iced）。它同时也是 CLI：同一个二进制认上面列的全部子命令。名字是 + 临时的，翻牌时才改成 `unlucky-launcher`；发布产物**已经**用对外名：流水线编这个 bin， + `packaging/make_artifacts.py` 落盘时改成 `unlucky-launcher[.exe]`，所以下载链接不用变。 +- `unlucky-launcher`——**历史**：workspace 构建已不产出它（它属于被排除的 `crates/app`）。 + `v0.1.0` 的资产是最后一批用这个名字发出去的构建。 +- `ull`——CLI 的独立无 UI 构建：同一套命令、不链接图形栈、体积更小，给完全没有显示设备的机器用。 + +渲染开关： + +- `unlucky-launcher-iced --software-renderer` 强制 tiny-skia（`ICED_BACKEND=tiny-skia`）； + `--screenshot ` 出一帧图后退出，这是 CI 无头冒烟 job 用的验收通道 +- 没有可用适配器时，iced 版靠显式后端探测自己退到 CPU +- **历史**（`v0.1.0` 的 Slint 版仍认这条）：`unlucky-launcher --software-renderer`，即 + `SLINT_BACKEND=winit-software`，让那一版走它自己的渲染器回退链 + +依赖许可检查（本地可选，CI 必跑）：`cargo deny check licenses bans sources`。 + +## CI 门禁 + +每次推送到 `main` 与每个 PR 都跑 fmt / clippy（warnings 视为错误）/ 全量测试，Linux 无头渲染冒烟 +与它们同级、是硬门禁：红了就不许合。macOS 运行期探针还不算——它只在手动 `workflow_dispatch` 时跑， +结果留证据但不作为流水线结论（`continue-on-error`），直到该槽位在真实 runner 上首跑通过。 + +| Workflow | 内容 | +|----------|------| +| `.github/workflows/ci.yml` | fmt + clippy + test + release build（Windows / Linux 矩阵）；Linux runtime smoke（Xvfb 里真渲染一帧，再断言 PNG 非空白）；macOS 运行期探针（仅手动 dispatch） | +| `.github/workflows/guards.yml` | `crates/core` 零 UI 守门（依赖表 + `cargo tree`）、单文件 ≤400 行守门、cargo-deny 许可与来源守门 | +| `.github/workflows/release.yml` | tag `v*` → 分槽位构建 → 单文件产物 + `SHA256SUMS.txt` → GitHub Release | + +## 平台基线 + +最低基线 **Windows 10**；Windows 8.1 / 8 / 7 不在支持范围内。 + +- Windows 10/11 的产物由**标准工具链**（MSVC / GNU）构建，构建方式与上游 cargo 一致 +- macOS 12+（Apple Silicon 与 Intel）与 Linux x64 / arm64 都是支持槽位；Linux 上 X11 是当前首选路径， + Wayland 是大方向。macOS 产物未签名，首次启动要自己清掉 Gatekeeper 隔离标记 + （`xattr -d com.apple.quarantine`） +- Android Termux 试验级、不承诺：只保证 CLI，GUI 未验证 +- 每个平台跑各自的测试矩阵；能力差异用 feature gate + 运行期探测表达。 + +## 许可证与致谢 + +- **本项目**：Apache License 2.0，见 [LICENSE](LICENSE)；第三方声明见 [NOTICE](NOTICE)。 +- **Slint**（），Royalty-Free 2.0：义务针对 `v0.1.0` 发布的那批构建——条件挂在每一次 + 「随应用分发」上，而不是挂在某个版本号上。上游 §2 给出两种形式：(a) 在可从顶层菜单进入的「关于」页/ + 对话框里显示官方 `AboutSlint` 部件（没有该页时改为启动画面）；(b) 在可下载该二进制的公开网页上显示 + 官方归属徽章。**`v0.1.0` 的设置页「关于」分组里内置了 `AboutSlint` 部件**（`crates/app/ui/pages/ + settings.slint`，从侧栏进入）；该部件是否满足 §2(a) 的全部条件、以及 `v0.1.0` 发布页上那是文字链接 + 而不是 §2(b) 点名的官方徽章图这两点，**本节不作法律判断**，具体以 Slint 官方许可原文为准。`v0.1.0` + 的 NOTICE、发布页说明与本节**都只是记录，不构成履行声明**。后续版本不再链接 Slint，该义务不随新产物 + 新增。义务跟着**链接了 Slint 的产物**走：已发布的 `v0.1.0` 资产（以及将来任何重新链接 Slint 的构建） + 适用；`crates/app` 已被 workspace `exclude`，流水线不再产出链接 Slint 的二进制，所以新的 iced 版不适用。 +- **iced**（），MIT：现役 UI 的框架；与它同栈的 `winit`（Apache-2.0）、 + 以及经它引入的 `wgpu`（MIT / Apache-2.0）/ `tiny-skia`（BSD-3-Clause）。 +- **Google Material Color Utilities**（Apache-2.0）：`crates/design` 的色彩令牌是它 HCT / + ColorSpec2021 算法的 Rust 重写移植，移植清单与逐函数对照写在 [NOTICE](NOTICE)。 +- **其余主要依赖**：MCP server 的 `rmcp` 与 `axum`（Apache-2.0 / MIT）、`tokio`（MIT）、`reqwest` + 与 rustls（MIT / Apache-2.0）、`serde` / `serde_json`（MIT / Apache-2.0）、`zip` / `flate2` / `tar` + （MIT / Apache-2.0）。cargo-deny 强制执行的白名单在 `deny.toml`；GPL 系依赖不得进主干。 + +感谢 [HMCL](https://github.com/HMCL-dev/HMCL) 和 [PCL2](https://github.com/Meloong-Git/PCL) +（均 GPL-3.0）。这两款启动器陪着绝大多数 MC 玩家走了很多年， +本项目在设计取舍与实现细节上都从中受益良多。 diff --git a/clippy.toml b/clippy.toml new file mode 100644 index 0000000..aca5e9c --- /dev/null +++ b/clippy.toml @@ -0,0 +1,7 @@ +# 与 Cargo.toml 的 rust-version 同步；改 MSRV 时两处一起改。 +msrv = "1.92" + +# core 的模块边界很薄，参数多于 8 个基本说明该拆结构体了。 +too-many-arguments-threshold = 8 +# 领域类型（版本号、哈希、URL）普遍是短名，不做最小名长惩罚。 +min-ident-chars-threshold = 2 diff --git a/crates/agent/Cargo.toml b/crates/agent/Cargo.toml new file mode 100644 index 0000000..72e1520 --- /dev/null +++ b/crates/agent/Cargo.toml @@ -0,0 +1,44 @@ +[package] +name = "unlucky-agent" +description = "Unlucky-Launcher AI Agent：工具注册表 + 内置客户端 + MCP server（双形态共用一个内核）" +version.workspace = true +edition.workspace = true +license.workspace = true +authors.workspace = true +repository.workspace = true +rust-version.workspace = true +publish.workspace = true + +# 依赖方向：agent 依赖 core 的公共 API，core 不知道 agent 的存在（AGENTS.md §2）。 +# 端口层（src/port*.rs）让 agent 能在没有 core 实现时独立编译与测试；装配层用 core 实现 +# 填充 `Ports`（GUI 侧是 `crates/app`，headless 侧是 `crates/cli` 的 `ull agent serve`）。 +[dependencies] +unlucky-core = { path = "../core", version = "0.2" } + +# 序列化：工具 JSON Schema 是手写 serde_json::Value（不引 schemars）， +# 工具结果 / 审计记录 / 事件流都用 serde derive。 +serde.workspace = true +serde_json.workspace = true + +# LLM Provider + agent 循环。**锁精确版本**：rig 12 周 5 个 minor、CHANGELOG 满是 breaking +# （DevDocs/PlanDoc/02-ai-agent-design.md §0 + research/02 §7 R1）。升级必须单独提交并跑回放回归。 +# 依赖面收口：整个 crate 只有 src/brain/rig.rs 允许 `use rig_*`。 +# feature `reqwest`：rig-core 0.45 的 default 只有 derive + rustls，HTTP 客户端要显式开；TLS 走 rustls +# （免 OpenSSL，对 Win7/MinGW 友好，见 research/02 §7 R3）。 +rig-core = { version = "=0.45.0", features = ["reqwest"] } +# TODO(M16-P1): 目前**声明但未使用**——对话循环/工具编排是自研的（要在中间插确认与审计）。 +# 保留是为了把版本按 02 §0 钉死；P1 接 rig 的 agent 运行时（工具服务句柄 / rig-cassette 回放 / +# rig-rmcp 让内置 agent 吃 MCP）时再真正消费。若 P1 决定彻底不用，删这一行即可。 +rig-agent = "=0.45.0" + +# 异步运行时（rig 的 HTTP/流式需要）与流工具（消费 rig 的 Stream）。 +tokio.workspace = true +futures-util.workspace = true + +# MCP server（M39）：rmcp 3.8 投影 + stdio / Streamable HTTP 传输。 +# 依赖面收口纪律与 rig 相同——整个 crate 只有 src/mcp/ 允许 `use rmcp::`。 +rmcp.workspace = true +axum.workspace = true + +[lints] +workspace = true diff --git a/crates/agent/src/audit.rs b/crates/agent/src/audit.rs new file mode 100644 index 0000000..de0f7ec --- /dev/null +++ b/crates/agent/src/audit.rs @@ -0,0 +1,283 @@ +//! 审计日志：**每一次工具调用**都留痕（02 文档 §3.1 末条 / mission M16 任务 4）。 +//! +//! 落盘位置由装配处给（`/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..152fb18 --- /dev/null +++ b/crates/agent/src/brain/mod.rs @@ -0,0 +1,323 @@ +//! Agent 大脑：Provider 抽象 + 对话循环 + 流式事件。 +//! +//! 选型（M10 定稿）：`rig-core` + `rig-agent`，**版本锁 `=0.45.x`**——上游 12 周 5 个 minor +//! 的 breaking 频率决定了必须锁死；依赖面只在本文件收口，其它模块不许直接碰 rig， +//! 以便随时换 genai / 自写循环逃生（`DevDocs/PlanDoc/02-ai-agent-design.md` §0）。 +//! +//! Provider 形态（02 §2）：OpenAI 兼容（默认，含本地 llama.cpp `127.0.0.1:PORT/v1`）、 +//! Anthropic 原生、Ollama 原生、以及「禁用」——禁用时规则引擎仍可用。 +//! +//! 统一 trait（M16 落地）：`stream_chat(messages, tools) -> Stream`，含 tool_call 事件。 +//! 本 crate 的落地形态是 [`chat::ChatProvider::complete`]（`request + observer → ChatReply`）： +//! rig 0.45 的流在 [`rig`] 适配层里展开成增量回调，循环侧只消费「文本增量 + 工具调用」两件事。 +//! **rig 依赖面收口在 [`rig`] 一个文件**，本文件不 `use rig_*`。 +//! +//! ## 对话循环（02 文档 §3.3） +//! +//! ```text +//! run_turn(user_input) +//! ├─ provider.complete(request) ← 流式增量经 EventDeltaObserver → UI +//! ├─ 有 tool_calls → ToolExecutor.execute（校验/确认/YOLO/审计）→ Tool 消息回灌 +//! └─ 没有 tool_calls → 结束，返回最终文本 +//! ``` +//! +//! 三条不变量： +//! 1. **system prompt 每轮重新注入**，不进历史（改提示词立刻生效，也不会被压缩逻辑吃掉）； +//! 2. 工具结果**永远回灌**（包括失败），模型才有机会改正； +//! 3. 步数上限 [`DEFAULT_MAX_STEPS`] 兜底，防止模型在两个工具间打转烧 token。 + +pub mod chat; +pub mod exec; +pub mod provider; +pub mod rig; + +use std::fmt; +use std::sync::Arc; + +use crate::audit::AuditSink; +use crate::clock::SharedClock; +use crate::confirm::{ConfirmGate, ConfirmPolicy}; +use crate::event::{AgentEvent, AgentEventSink}; +use crate::registry::ToolRegistry; + +pub use chat::{ + ChatMessage, ChatProvider, ChatReply, ChatRequest, DeltaObserver, EventDeltaObserver, + NoopObserver, ProviderFactory, ProviderFuture, ToolCall, Usage, +}; +pub use exec::{ToolExecOutcome, ToolExecutor}; +pub use provider::{ProviderConfig, ProviderError, ProviderKind}; + +/// 一轮对话最多几轮工具调用。 +pub const DEFAULT_MAX_STEPS: usize = 8; + +/// 内置系统提示词（P0 版本；P2 会按实例上下文按需注入）。 +#[must_use] +pub fn default_system_prompt() -> String { + [ + "你是 Unlucky-Launcher（ULL，Minecraft 启动器）的内置助手。", + "你能调用工具：读配置（get_config）、改配置（set_config）、列出游戏会话（list_game_sessions）、", + "读会话日志（read_game_log）、跑崩溃规则引擎（diagnose_crash）。", + "纪律：", + "1. 先查后改：改任何配置前先用 get_config 确认键名与现值。", + "2. 崩溃问题先看 diagnose_crash 的规则结论；规则未命中或需要更多信息时，才用 read_game_log", + " 取 stderr / exit / crash_found，不要拉全量日志。", + "3. 只能改 get_config 列出的可写键。敏感键会要求用户确认：被拒绝就换方案，不要重复尝试同一改动。", + "4. 用中文回答，给用户可以立即执行的下一步；不确定时直说不确定，不要编造规则或日志内容。", + ] + .join("\n") +} + +/// 循环参数。 +#[derive(Debug, Clone)] +pub struct BrainConfig { + /// 最多几轮工具调用。 + pub max_steps: usize, + /// 系统提示词。 + pub system_prompt: String, +} + +impl Default for BrainConfig { + fn default() -> Self { + Self { + max_steps: DEFAULT_MAX_STEPS, + system_prompt: default_system_prompt(), + } + } +} + +impl BrainConfig { + /// 自定义提示词（步数用默认）。 + #[must_use] + pub fn with_system_prompt(system_prompt: impl Into) -> 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..804fa3d --- /dev/null +++ b/crates/agent/src/brain/provider.rs @@ -0,0 +1,340 @@ +//! Provider 四态端点配置（02 文档 §2）。 +//! +//! | 形态 | 端点 | 备注 | +//! |------|------|------| +//! | OpenAI 兼容（默认） | `base_url` + `api_key` + `model` | 覆盖 OpenAI/DeepSeek/Qwen/GLM/**本地 llama.cpp server**（`http://127.0.0.1:8080/v1`）/LM Studio | +//! | Anthropic 原生 | `api_key` + `model` | Claude 系列（没有可用的 Rust 单厂商 SDK，见 research/02 §3.6） | +//! | Ollama 原生 | `http://127.0.0.1:11434` | 本地另一种主流 | +//! | 禁用 | — | 完全关闭 agent，规则引擎（`diagnose_crash`）仍可用 | +//! +//! 本文件只放**配置与校验**；对话协议在 [`super::chat`]。这样 rig 的 pre-1.0 破坏面 +//! （research/02 §7 R1）被关在 [`super::rig`] 一个文件里，这里连 rig 的名字都不出现。 + +use std::fmt; + +use serde::{Deserialize, Serialize}; + +/// 本地 llama.cpp server 的默认 OpenAI 兼容端点（research/02 §5.1）。 +pub const LLAMACPP_DEFAULT_BASE_URL: &str = "http://127.0.0.1:8080/v1"; +/// Ollama 默认端点（research/02 §5.2）。 +pub const OLLAMA_DEFAULT_BASE_URL: &str = "http://127.0.0.1:11434"; +/// Anthropic 官方 API 端点。 +pub const ANTHROPIC_DEFAULT_BASE_URL: &str = "https://api.anthropic.com"; + +/// Provider 四态。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum ProviderKind { + /// OpenAI 兼容（含本地 llama.cpp / LM Studio / DeepSeek / Qwen…）。 + OpenAiCompatible, + /// Anthropic 原生。 + Anthropic, + /// Ollama 原生。 + Ollama, + /// 完全禁用 agent。 + Disabled, +} + +impl ProviderKind { + /// 该形态是否必须提供 API key（本地推理通常不需要）。 + #[must_use] + pub fn requires_api_key(self) -> bool { + matches!(self, Self::Anthropic) + } + + /// 该形态的默认端点（OpenAI 兼容没有统一默认值，必须显式填； + /// 本地 llama.cpp 走 [`ProviderConfig::llamacpp_local`] 带的显式默认）。 + #[must_use] + pub fn default_base_url(self) -> &'static str { + match self { + Self::OpenAiCompatible => "", + Self::Anthropic => ANTHROPIC_DEFAULT_BASE_URL, + Self::Ollama => OLLAMA_DEFAULT_BASE_URL, + Self::Disabled => "", + } + } + + /// 设置页展示名。 + #[must_use] + pub fn display_name(self) -> &'static str { + match self { + Self::OpenAiCompatible => "OpenAI 兼容", + Self::Anthropic => "Anthropic 原生", + Self::Ollama => "Ollama 原生", + Self::Disabled => "已禁用", + } + } +} + +/// Provider 配置（设置 → AI 的一份快照）。 +/// +/// `api_key` 只在进程内存在，**任何日志/审计/事件都不得带它**—— +/// `Debug` 是手写的（掩码 key），要连形态一起看用 [`ProviderConfig::redacted_debug`]。 +#[derive(Clone, PartialEq, Serialize, Deserialize)] +pub struct ProviderConfig { + /// 四态。 + pub kind: ProviderKind, + /// 端点；空串表示用 [`ProviderKind::default_base_url`]。 + pub base_url: String, + /// 模型名；`Disabled` 时可为空。 + pub model: String, + /// API key（本地推理可空）。 + pub api_key: Option, + /// 采样温度。 + 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::new( + "AI 已禁用：请在设置 → AI 中选择端点（规则引擎诊断不受影响）", + )); + } + if self.model.trim().is_empty() { + return Err(ProviderError::new("没有配置模型名（model）")); + } + if self.resolved_base_url().trim().is_empty() { + return Err(ProviderError::new(format!( + "{} 需要填写端点（base_url）", + self.kind.display_name() + ))); + } + if self.kind.requires_api_key() + && self + .api_key + .as_deref() + .is_none_or(|key| key.trim().is_empty()) + { + return Err(ProviderError::new(format!( + "{} 需要 API key", + self.kind.display_name() + ))); + } + Ok(()) + } + + /// 可打印的形态描述（**key 已掩码**，给日志/审计/设置页用）。 + #[must_use] + pub fn redacted_debug(&self) -> String { + let key = match self.api_key.as_deref() { + None => "无".to_string(), + Some(k) if k.trim().is_empty() => "无".to_string(), + Some(_) => crate::redact::MASK.to_string(), + }; + format!( + "{} base_url={} model={} api_key={key}", + self.kind.display_name(), + self.resolved_base_url(), + if self.model.is_empty() { + "（未设置）" + } else { + &self.model + }, + ) + } +} + +impl fmt::Debug for ProviderConfig { + /// 手写 Debug：**key 掩码**（`api_key` 是唯一不能出现在日志里的字段）。 + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.debug_struct("ProviderConfig") + .field("kind", &self.kind) + .field("base_url", &self.resolved_base_url()) + .field("model", &self.model) + .field( + "api_key", + &self.api_key.as_deref().map(|_| crate::redact::MASK), + ) + .field("temperature", &self.temperature) + .field("max_tokens", &self.max_tokens) + .finish() + } +} + +/// Provider 层错误（消息面向用户：端点连不上、key 无效、模型不存在）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ProviderError { + message: String, +} + +impl ProviderError { + /// 从可读文本构造。 + #[must_use] + pub fn new(message: impl Into) -> Self { + Self { + message: message.into(), + } + } +} + +impl fmt::Display for ProviderError { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str(&self.message) + } +} + +impl std::error::Error for ProviderError {} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn local_defaults_match_research() { + assert_eq!( + ProviderConfig::llamacpp_local("qwen2.5").resolved_base_url(), + LLAMACPP_DEFAULT_BASE_URL + ); + assert_eq!( + ProviderConfig::ollama("llama3").resolved_base_url(), + OLLAMA_DEFAULT_BASE_URL + ); + assert_eq!( + ProviderConfig::anthropic("claude-sonnet-4").resolved_base_url(), + ANTHROPIC_DEFAULT_BASE_URL + ); + } + + #[test] + fn validate_requires_model_base_url_and_key() { + assert!(!ProviderConfig::disabled().is_enabled()); + assert!(ProviderConfig::disabled().validate().is_err()); + assert!(ProviderConfig::llamacpp_local("").validate().is_err()); + assert!(ProviderConfig::llamacpp_local("qwen").validate().is_ok()); + // OpenAI 兼容必须显式给端点 + assert!(ProviderConfig::openai_compatible("", "gpt-4o-mini") + .validate() + .is_err()); + assert!( + ProviderConfig::openai_compatible("https://api.deepseek.com/v1", "deepseek-chat") + .validate() + .is_ok() + ); + assert!(ProviderConfig::anthropic("claude").validate().is_err()); + assert!(ProviderConfig::anthropic("claude") + .with_api_key("sk-ant") + .validate() + .is_ok()); + } + + #[test] + fn redacted_debug_never_leaks_key() { + let config = + ProviderConfig::openai_compatible("https://api.deepseek.com/v1", "deepseek-chat") + .with_api_key("sk-super-secret"); + let text = config.redacted_debug(); + assert!(!text.contains("sk-super-secret"), "{text}"); + assert!(text.contains(crate::redact::MASK)); + // `{:?}` 也必须掩码：Debug 是 panic 消息/日志的默认出口。 + let debug = format!("{config:?}"); + assert!(!debug.contains("sk-super-secret"), "{debug}"); + assert!(debug.contains(crate::redact::MASK), "{debug}"); + } + + #[test] + fn empty_base_url_falls_back_to_default() { + let mut config = ProviderConfig::ollama("llama3"); + config.base_url = String::new(); + assert_eq!(config.resolved_base_url(), OLLAMA_DEFAULT_BASE_URL); + } + + #[test] + fn four_states_serialize_as_snake_case() { + assert_eq!( + serde_json::to_string(&ProviderKind::OpenAiCompatible).unwrap(), + "\"open_ai_compatible\"" + ); + assert_eq!( + serde_json::to_string(&ProviderConfig::disabled()).unwrap(), + "{\"kind\":\"disabled\",\"base_url\":\"\",\"model\":\"\",\"api_key\":null,\"temperature\":null,\"max_tokens\":null}" + ); + } +} diff --git a/crates/agent/src/brain/rig.rs b/crates/agent/src/brain/rig.rs new file mode 100644 index 0000000..3043564 --- /dev/null +++ b/crates/agent/src/brain/rig.rs @@ -0,0 +1,368 @@ +//! rig 适配层：[`ChatProvider`] 的**唯一**实现，也是整个 crate 唯一允许 `use rig_*` 的文件。 +//! +//! 依赖面收窄纪律（`DevDocs/PlanDoc/02-ai-agent-design.md` §0 + research/02 §7 R1）： +//! rig 是 pre-1.0、12 周 5 个 minor、CHANGELOG 满是 `[**breaking**]`（0.43 把 MCP 拆出 rig-agent、 +//! 0.45 升 rmcp 3.5 并改 owned connection）。所以把它关在这一个文件里：它变了，只有这里编译失败， +//! [`super::ChatProvider`] 以上的循环/编排/审计一行不用动。 +//! +//! ## 0.45 的接线（实读源码，非照文档猜） +//! +//! ```text +//! ProviderConfig ─┬─ OpenAiCompatible → OpenAIConfig::new(key).with_base_url(url).client().chat(model) +//! ├─ Anthropic → AnthropicConfig::new(key).with_base_url(url).client().completion(model) +//! ├─ Ollama → OllamaConfig::new().with_base_url(url).client().completion(model) +//! └─ Disabled → 不构造（Brain::run_turn 已提前返回） +//! ↓ Model.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::ProviderError as RigError; +use rig_core::message::{ + AssistantContent as RigAssistantContent, AssistantMessage as RigAssistantMessage, CallId, + Message as RigMessage, Text as RigText, ToolCall as RigToolCall, ToolFunction, + ToolName as RigToolName, ToolResult, ToolResultContent, UserContent, +}; +use rig_core::operation::Completion; +use rig_core::providers::anthropic::AnthropicConfig; +use rig_core::providers::ollama::OllamaConfig; +use rig_core::providers::openai::OpenAIConfig; +use rig_core::streaming::{Item, StreamEvent}; +use rig_core::DynModel; + +use super::chat::{ + ChatMessage, ChatProvider, ChatReply, ChatRequest, DeltaObserver, ProviderFactory, + ProviderFuture, +}; +use super::provider::{ProviderConfig, ProviderError, ProviderKind}; + +/// 锁定的 rig 版本（与 `Cargo.toml` 的唯一记录点，避免两处不一致）。 +pub const RIG_VERSION_PIN: &str = "=0.45.0"; + +/// 擦掉 wire / transport 之后的补全模型——本文件对外只暴露这一个 rig 类型之外的东西。 +type ErasedModel = DynModel; + +/// 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 错误 → 本方错误（文案面向用户）。 +fn map_error(error: RigError) -> ProviderError { + ProviderError::new(error.to_string()) +} + +/// 工具名 → rig 的 [`RigToolName`]（空名是唯一的非法输入）。 +fn tool_name(name: &str) -> Result { + RigToolName::new(name) + .map_err(|_| ProviderError::new("工具名不能为空（ToolSpec 注册阶段应已拦截）")) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn tool(id: &str, name: &str) -> super::super::chat::ToolCall { + super::super::chat::ToolCall { + id: id.to_string(), + name: name.to_string(), + arguments: serde_json::json!({ "path": "appearance.theme_mode" }), + } + } + + #[test] + fn disabled_config_is_rejected_before_touching_the_network() { + let Err(err) = RigProvider::new(ProviderConfig::disabled()) else { + panic!("禁用态应在构造阶段被拒"); + }; + assert!(err.to_string().contains("禁用")); + } + + #[test] + fn anthropic_without_key_is_rejected() { + assert!(RigProvider::new(ProviderConfig::anthropic("claude-sonnet-4")).is_err()); + assert!(RigProvider::new( + ProviderConfig::anthropic("claude-sonnet-4").with_api_key("sk-ant") + ) + .is_ok()); + } + + #[test] + fn local_states_build_offline() { + assert!(RigProvider::new(ProviderConfig::llamacpp_local("qwen2.5-7b")).is_ok()); + assert!(RigProvider::new(ProviderConfig::ollama("llama3.1")).is_ok()); + } + + #[test] + fn request_maps_messages_and_tools() { + let request = ChatRequest { + model: "mock".to_string(), + messages: vec![ + ChatMessage::system("你是助手"), + ChatMessage::user("把主题换成浅色"), + ChatMessage::Assistant { + text: String::new(), + tool_calls: vec![tool("call_1", "set_config")], + }, + ChatMessage::tool("call_1", "set_config", "{\"status\":\"written\"}"), + ], + tools: vec![crate::registry::ToolDefinition { + name: "set_config".to_string(), + description: "改配置".to_string(), + input_schema: serde_json::json!({ "type": "object" }), + }], + temperature: Some(0.5), + max_tokens: Some(512), + }; + let built = build_request(&request).expect("应能构造"); + assert_eq!(built.chat_history.len(), 4); + assert_eq!(built.tools.len(), 1); + assert_eq!(built.tools[0].name.as_str(), "set_config"); + assert_eq!(built.temperature, Some(0.5)); + assert_eq!(built.max_tokens, Some(512)); + // 工具结果在 rig 0.45 里是 user 角色的 ToolResult 内容块 + let json = serde_json::to_string(&built.chat_history[3]).expect("可序列化"); + assert!(json.contains("toolresult"), "{json}"); + } + + #[test] + fn empty_history_is_a_readable_error() { + let request = ChatRequest { + model: "m".to_string(), + messages: Vec::new(), + tools: Vec::new(), + temperature: None, + max_tokens: None, + }; + let err = build_request(&request).unwrap_err(); + assert!(err.to_string().contains("对话历史为空")); + } +} diff --git a/crates/agent/src/clock.rs b/crates/agent/src/clock.rs new file mode 100644 index 0000000..f24b042 --- /dev/null +++ b/crates/agent/src/clock.rs @@ -0,0 +1,139 @@ +//! 时间源：审计日志、事件流、工具耗时都要时间戳，但**测试不能依赖真实时钟** +//! （否则断言不稳定）。所以照既有做法注入 [`Clock`]。 +//! +//! 时间戳格式化自己实现（[`format_unix_ms`]），不引 `chrono`：agent 的依赖面按 +//! `DevDocs/PlanDoc/02-ai-agent-design.md` §0 越窄越好，RFC3339 UTC 只需要一个 +//! 民用历换算（Howard Hinnant 的 `civil_from_days`）。 + +use std::sync::atomic::{AtomicU64, Ordering}; +use std::sync::Arc; +use std::time::{SystemTime, UNIX_EPOCH}; + +/// 时间源。生产用 [`SystemClock`]，测试用 [`FixedClock`]。 +pub trait Clock: Send + Sync { + /// 当前 Unix 毫秒时间戳。 + fn now_unix_ms(&self) -> u64; +} + +/// 真实系统时钟（单调性不保证，审计只要"大致有序"）。 +#[derive(Debug, Default, Clone, Copy)] +pub struct SystemClock; + +impl Clock for SystemClock { + fn now_unix_ms(&self) -> u64 { + SystemTime::now() + .duration_since(UNIX_EPOCH) + .map_or(0, |d| d.as_millis() as u64) + } +} + +/// 可控时钟：测试里固定起点、必要时手动推进。 +#[derive(Debug)] +pub struct FixedClock { + ms: AtomicU64, + step_ms: u64, +} + +impl FixedClock { + /// 从固定时间戳开始，每次读走一步 `step_ms`（0 = 不自动推进）。 + #[must_use] + pub fn new(start_ms: u64) -> Self { + Self { + ms: AtomicU64::new(start_ms), + step_ms: 0, + } + } + + /// 每次读取自动前进 `step_ms`，用来断言工具耗时字段。 + #[must_use] + pub fn with_step(start_ms: u64, step_ms: u64) -> Self { + Self { + ms: AtomicU64::new(start_ms), + step_ms, + } + } + + /// 手动推进。 + pub fn advance(&self, ms: u64) { + self.ms.fetch_add(ms, Ordering::Relaxed); + } +} + +impl Clock for FixedClock { + fn now_unix_ms(&self) -> u64 { + if self.step_ms == 0 { + return self.ms.load(Ordering::Relaxed); + } + self.ms.fetch_add(self.step_ms, Ordering::Relaxed) + self.step_ms + } +} + +/// `Arc` 的简写。 +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..092f6e0 --- /dev/null +++ b/crates/app-iced/Cargo.toml @@ -0,0 +1,92 @@ +[package] +name = "unlucky-app-iced" +description = "Unlucky-Launcher 桌面壳（iced 0.14 重写版）：M3 Expressive 骨架 / 令牌适配 / 截图通道" +version.workspace = true +edition.workspace = true +license.workspace = true +authors.workspace = true +repository.workspace = true +rust-version.workspace = true +publish.workspace = true + +# 并存期（D26）：Slint 版仍是 `crates/app` 的 `unlucky-launcher`，本 crate 出 +# `unlucky-launcher-iced`。两个 package 在同一 target 目录产出同名 bin 会冲突， +# 所以**翻牌前不许改回 `unlucky-launcher`**（步骤见 SubAgentsTalk/app-iced-骨架与翻牌.md）。 +[[bin]] +name = "unlucky-launcher-iced" +path = "src/main.rs" + +[lib] +name = "unlucky_app_iced" +path = "src/lib.rs" + +[dependencies] +# 令牌唯一真源（M61）：颜色/排版/形状/间距/图标几何全部只从这里取。 +unlucky-design = { path = "../design", version = "0.2" } + +# M85：UI 框架无关的宿主层（DTO / 状态 reducer / host）。**只登记依赖，本 mission 不接线**—— +# 页面用它的时机由后续 iced 页面 mission 决定（接线流程见 crates/presenter/src/lib.rs 的 crate 文档）。 +# 与 Slint 版共用同一套 host 与状态语义，这是 D26「重写只换渲染」的落点。 +unlucky-presenter = { path = "../presenter", version = "0.2" } + +# UI 框架（D26 锁定 iced 0.14）。**不得依赖 slint**。 +# 关掉默认 features 后必须显式给执行器（M60 踩坑 Q2：否则 `No futures executor has been enabled`）， +# 这里给 `thread-pool`（iced 自己的默认执行器，不额外引 tokio 运行时）。 +# `wgpu` 由本 crate 的 `gpu` feature 打开，于是「仅 CPU」体积基线用 `--no-default-features` 就能量到。 +iced = { version = "=0.14.0", default-features = false, features = [ + "tiny-skia", + "crisp", + "advanced", + # M93：背景图要真图直出 ⇒ 需要渲染器的 image 支持。用 `image-without-codecs` 而不是 + # `image` 是刻意的：后者会打开 `image/default` 的全套编解码器；前者的编解码能力由本 crate + # 依赖表里那条 `image` 的 features 决定（png / jpeg / bmp），不必把 webp/tiff/exr/gif 拖进来。 + "image-without-codecs", + "svg", + "thread-pool", +] } + +# 截图落 PNG + 背景图解码（M93）：png 是截图通道，jpeg/bmp 是用户真会挑的背景图/壁纸格式 +# （M73 的壁纸探测不筛扩展名）。仍不开 default-features——那会拖进 avif/ravif/webp/tiff 一整套。 +image = { version = "0.25", default-features = false, features = [ + "png", + "jpeg", + "bmp", +] } + +# M82：同一个二进制也带 CLI 子命令（`unlucky-launcher-iced instances list` …）， +# 进 UI 之前分发，命中就把控制权交给 `unlucky_cli::run`。依赖方向 app-iced → cli → +# core/agent 不违反 core 零 UI 铁律（core 的依赖树里没有 cli）。零 UI 依赖的 `ull` +# 仍在 `crates/cli`，给没有图形库的机器用——两者不是重复品。 +unlucky-cli = { path = "../cli", version = "0.2" } + +# M92（D28）：国际化地基（语言探测 / 消息目录 / 中文字体策略）。零依赖 crate——它拿不到 iced， +# 所以系统字体扫描留在这里（`src/fonts/cjk.rs`），本 crate 只把族名喂给它的纯函数。 +unlucky-i18n = { path = "../i18n", version = "0.2" } + +# M97：判据表第 8 行的取证通道。`iced_wgpu` 在真创建设备时会 `log::info!("Selected: {adapter:#?}")`， +# 但进程里从来没人装 logger，于是「看不见」被当成了「没发生」。这里装一个只放行 `iced_wgpu*` / +# `wgpu*` 的 logger（见 `src/renderer/log_bridge.rs`），把这行捞出来。 +# 已是 iced 传递依赖树里的版本（0.4.34），不新增任何传递依赖；MIT OR Apache-2.0，许可白名单内。 +log = { version = "0.4", features = ["std"] } + +# X11 / Wayland 后端与 Linux 主题检测只在 Linux 上启用：macOS 没有 X11/Wayland（走 Metal + +# 系统外观），Windows 走 DX12，这三个 feature 在那边没有意义。同一个包在两处写 features 是 +# **取并集**（Cargo 的 feature 解析是加法），所以 Linux 上拿到的仍是上面 5 个 + 这 3 个， +# Windows / macOS 只拿上面那 5 个（`cargo tree --target` 可复核）。 +# 诚实边界：这**不**解决「iced 版至今没在 macOS 上编过」这件事——`iced_winit` 已把 `mundy` +# 放在 `cfg(target_os = "linux")` 段里，这三个 feature 在非 Linux 上本来就不拉依赖，这里只是 +# 让本仓库的依赖图按平台自述清楚，不再把 Linux 专属能力写成全平台事实。 +[target.'cfg(target_os = "linux")'.dependencies] +iced = { version = "=0.14.0", default-features = false, features = [ + "x11", + "wayland", + "linux-theme-detection", +] } + +[features] +default = ["gpu"] +# 硬件渲染后端（wgpu→Vulkan/DX12）。关闭后只剩 tiny-skia（CPU），用于体积基线与无 GPU 机器。 +gpu = ["iced/wgpu"] + +[lints] +workspace = true diff --git a/crates/app-iced/examples/pages_demo.rs b/crates/app-iced/examples/pages_demo.rs new file mode 100644 index 0000000..34122bf --- /dev/null +++ b/crates/app-iced/examples/pages_demo.rs @@ -0,0 +1,37 @@ +//! 页面骨架截图入口（M84 `PAGEFRAME` 的验收通道）。 +//! +//! ```text +//! cargo run -p unlucky-app-iced --example pages_demo -- \ +//! --screen=instances --width=1180 --height=760 \ +//! --screenshot=out.png --screenshot-theme=light --software-renderer +//! ``` +//! +//! 参数解析与 iced 接线都在 `unlucky_app_iced::pages::harness` 里：**本 example 只是入口**， +//! 它也刻意不接 `cli.rs`（那边归 M75）。详细口径见 `pages::harness` 的模块文档。 + +use std::process::ExitCode; + +use unlucky_app_iced::pages::harness::{self, Request}; + +fn main() -> ExitCode { + let request = match Request::parse(std::env::args().skip(1)) { + Ok(request) => request, + Err(message) => { + eprintln!("[cli] {message}"); + eprintln!( + "用法：pages_demo [--screen=instances|download|settings|logs] [--width ] \ + [--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/appearance.rs b/crates/app-iced/src/app/appearance.rs new file mode 100644 index 0000000..68fe4c7 --- /dev/null +++ b/crates/app-iced/src/app/appearance.rs @@ -0,0 +1,130 @@ +//! App 侧的外观动作：**下发整窗 α / 写回配置 / 打取证日志**。 +//! +//! 三件事各自只有一条路，且都从这里出去（`update` 只负责把它们按消息串起来）： +//! +//! | 动作 | 唯一落点 | 为什么 | +//! |---|---|---| +//! | 下发整窗 α | [`App::apply_window_alpha`] → `app::window_alpha::dispatch` | 判据在 `platform`、FFI 在 `platform/win32`，这里只做「取 α → 交给执行侧 → 记日志」 | +//! | 写回配置 | [`App::persist_appearance`]（8 个 UI 字段）+ `AppCommand::SetSetting`（另外**三个**只读键） | 每个键**只有一个写者**：`AppearancePrefs` 里没有 `window_opacity` / `palette_source` / `window_corner`，它们只能走 schema 指令 | +//! | 取证日志 | [`App::log_appearance`] | 一行里同时有请求值、生效值、下发字节与 FFI 结局 | +//! +//! ## 为什么「写回」要分两条路 +//! +//! `SettingsBridge::persist` 收的是 `AppearancePrefs`（背景图四件 + 面板 α + 玻璃 + 强调色）， +//! 它的实现是「先读文件当前值，再覆盖我们改的那几个字段」——所以用它写**它覆盖的键**最省事， +//! 也不会把用户的自定义强调色冲掉。而 `appearance.window_opacity` / `appearance.palette_source` / +//! `appearance.window_corner` 不在那个结构里（它们是「只读下层键」，见 +//! `presenter::prefs::AppearanceBase` 的**四个**字段：整窗 α / 标题栏三态 / 配色来源 / 窗口圆角）， +//! 写它们只能走 schema 白名单指令 `AppCommand::SetSetting`（真 host 用 `SettingStore::set` 落盘）。 +//! 其中「标题栏三态」目前**没有 UI 写者**（D37 的接线未落地），所以走 `SetSetting` 的是**三个**键。 + +use unlucky_presenter::dto::AppCommand; + +use crate::pages::appearance::Change; + +use super::state::App; +use super::window_alpha::{self, Dispatch}; + +impl App { + /// 把当前整窗 α 交给执行侧（补 `WS_EX_LAYERED` + `SetLayeredWindowAttributes`）并记一行日志。 + /// + /// 没有句柄时**也打日志**（`hwnd=none`）：不能让「α 没生效」这件事只体现为「屏幕上没变化」。 + pub(super) fn apply_window_alpha(&self, context: &str) { + let Some(hwnd) = self.hwnd else { + self.log_appearance(context, None); + return; + }; + let alpha = crate::platform::effective_window_alpha( + self.appearance.backend, + f64::from(self.appearance.window_opacity), + ); + let dispatch = window_alpha::dispatch(hwnd, alpha); + self.log_appearance(context, Some(&dispatch)); + } + + /// 取证日志：`[appearance] <状态行> layered=… outcome=…`。 + /// + /// 数值来自 [`crate::pages::appearance::State::log_line`]（请求值 / 生效值 / 下发字节）， + /// 尾巴来自执行侧。**这一行就是「透明度到底设成了多少」的证据**——RDP 上的观感不可信。 + pub(super) fn log_appearance(&self, context: &str, dispatch: Option<&Dispatch>) { + let mut line = self.appearance.log_line(context); + if let Some(dispatch) = dispatch { + line.push(' '); + line.push_str(&dispatch.describe()); + } else { + line.push_str(" layered=skipped outcome=no-window"); + } + eprintln!("{line}"); + } + + /// 设置页改了一项外观。 + pub(super) fn on_appearance(&mut self, change: Change) { + let needs_window = self.appearance.apply(change.clone()); + + // 配色来源 / 背景图可能变了 ⇒ `Ui` 可能要改用解析出的方案。 + self.rebuild_ui(); + self.view_dirty = true; + self.refresh_view(); + + match change.key() { + // 三个只读下层键（整窗 α / 配色来源 / 窗口圆角）：走 schema 指令 + // （`SettingsBridge` 的结构里没有它们；标题栏三态还没有 UI 写者，不在此列）。 + Some(_) + if matches!( + change, + Change::WindowOpacity(_) | Change::PaletteSource(_) | Change::Corner(_) + ) => + { + if let (Some(key), Some(value)) = (change.key(), change.value()) { + self.dispatch(AppCommand::SetSetting { + key: key.to_owned(), + value, + }); + } + } + // 其余键：走 bridge（它知道怎么保留强调色这类本 mission 不管的字段）。 + Some(_) => self.persist_appearance(), + None => {} + } + + if needs_window { + self.apply_window_alpha("change"); + } else { + self.log_appearance("change", None); + } + // M116：圆角档位变了要**重新判定 + 重新下发**（与整窗 α 是两条独立的管线）。 + self.apply_window_corner("change"); + } + + /// 重读配置后同步外观（热切：外部 CLI / AI 改完 1 秒内生效）。 + pub(super) fn reload_appearance(&mut self) { + let (prefs, _theme) = self.bridge.load(); + let base = self.bridge.load_base(); + self.appearance.reload(&prefs, &base); + self.appearance_prefs = prefs; + self.rebuild_ui(); + self.view_dirty = true; + self.apply_window_alpha("reload"); + // M116：外部（CLI / AI）改了 `appearance.window_corner` 也要热生效。 + self.apply_window_corner("reload"); + } + + /// 把外观写回 `launcher.json`（只改本 mission 管的字段，强调色/玻璃原样保留）。 + fn persist_appearance(&mut self) { + let mut prefs = self.appearance_prefs.clone(); + prefs.bg_image_enabled = self.appearance.bg_enabled; + prefs.bg_image = self.appearance.bg_path.clone(); + prefs.bg_fill = self.appearance.bg_fill; + prefs.bg_dim = self.appearance.bg_dim; + prefs.panel_alpha = self.appearance.panel_alpha; + prefs.glass = self.appearance.glass; + + self.bridge.persist(&prefs, self.theme_mode); + self.appearance_prefs = prefs; + + match self.bridge.path() { + Some(path) => eprintln!("[settings] 外观已写回 {}", path.display()), + None => eprintln!("[settings] 外观未落盘（数据根解析不出来，内存态运行）"), + } + } +} diff --git a/crates/app-iced/src/app/backend.rs b/crates/app-iced/src/app/backend.rs new file mode 100644 index 0000000..ab22442 --- /dev/null +++ b/crates/app-iced/src/app/backend.rs @@ -0,0 +1,177 @@ +//! 本进程**实际**用的是哪个渲染后端（D36 的「CPU 档」判据）。 +//! +//! ## 为什么不能直接看 `--renderer` 的请求值 +//! +//! `Options::backend` 是**请求**（默认 `Auto`）。真正落到哪个渲染器由 `probe::apply` 决定， +//! 它把结论写进进程环境变量 `ICED_BACKEND`（iced 只认这个）。于是默认参数 + 没有独显的机器上： +//! 请求是 `Auto`，实际是 tiny-skia（CPU）——如果面板 α / 玻璃的降级判据只看请求值， +//! D36 明写的「CPU 档面板 α 强制 1.0」**恰好在它最该生效的场景失效**（复审 r1 P2-2）。 +//! +//! 所以判据统一走 [`effective_backend`]：它把 `ICED_BACKEND` 翻译回 [`Backend`]。 +//! 这里是**唯一**的翻译点，别在别处再读一遍环境变量。 +//! +//! ## M97 之后这条链是准的（以前不是） +//! +//! 以前 `ICED_BACKEND` 可能是**候选列表**（`wgpu,tiny-skia`），运行期 wgpu 静默回退到 +//! tiny-skia 时这个变量还停在 wgpu ⇒ 本模块按 **GPU 档**判 ⇒ **半透明在 CPU 渲染器上照开**。 +//! 也就是说「静默降级」不只让日志说谎，还让 D36 的降级判据一起说谎。 +//! +//! 现在 `ICED_BACKEND` **永远是单项**（[`crate::renderer::Kind`]），而且 `app::boot` 的重试 +//! 在降级重开前会把它改成 `tiny-skia`，于是：**真降级到 CPU 的那一次，面板 α 会正确地强制 1.0**。 +//! +//! ## 已知边界（诚实登记） +//! +//! `iced` 0.14 没有公开的「当前后端」查询，所以本模块读的仍是**我们请求的那一项**。 +//! 单项 + 重试（[`crate::renderer`] 判据表第 8 行）把「请求 ≠ 实际」的窗口压到只剩一种： +//! 重试那次自己也失败——那时候进程会带着具名错误退出，不会带着错的档位继续画。 + +use crate::renderer::Kind; +use crate::Backend; + +/// `ICED_BACKEND` 的取值 → 后端（纯函数，好测）。 +/// +/// 逗号列表按**首项**解释：兼容 M97 之前写下的值（以及外部手设的实验值）， +/// 但本 crate 不再产出那种值（守门测试见 `probe::tests::apply_writes_exactly_one_backend`）。 +#[must_use] +pub(super) fn parse_kind(env: &str) -> Option { + 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..182e421 --- /dev/null +++ b/crates/app-iced/src/app/boot.rs @@ -0,0 +1,248 @@ +//! 启动编排：**探测 → 字体 → 打印诊断 → 起 iced**（四步，别把它撑回一坨）。 +//! +//! ## 三条纪律（每条都对应一次返工） +//! +//! 1. **后端起不来时的两条路策略不同**（判据表第 8/9 行）：交互启动换进程重开、取证启动 +//! （`--screenshot`）拒绝出图 —— 实现与测试都在 [`fallback`]。 +//! 2. **窗口设置只有一个产地**（[`diagnostics::window_settings`]），`[window]` / `[caps]` 两行日志 +//! 从**同一个** `&window::Settings` 取字段。M98 r1 p2-1 的教训：把 `decorations=false` 写进 +//! 格式化串，等于让日志与真实行为可以各走各的（踩坑记录 U1）。 +//! 3. **没测过的就写 `skipped`**，不许拿 `0ms` 冒充实测（[`diagnostics::report_font`] 的 `probe`）。 +//! +//! 为什么重开必须是**换进程**：Windows 实测本进程里再 `run()` 一次直接 panic +//! （`iced_winit-0.14.1/src/lib.rs:81` → `Create event loop: RecreationAttempt`）。 + +use std::time::{Duration, Instant}; + +use iced::Task; + +use unlucky_design::color::SchemeFlavor; + +use crate::cli::Options; +use crate::fonts; +use crate::probe; +use crate::renderer::{self, acceptance, Decision}; +use crate::theme::Families; + +use super::message::Message; +use super::state::{App, STARTED}; +use super::{MIN_SIZE, WINDOW_SIZE}; + +mod diagnostics; +mod fallback; + +use fallback::{on_failure, respawn, OnFailure}; + +/// 启动 iced（阻塞到退出）。`--diff` 不走这里，见 `main.rs`。 +pub(crate) fn run(options: Options) -> iced::Result { + let _ = STARTED.set(Instant::now()); + let boot_started = Instant::now(); + + // ① 探测（判据取在哪、日志在 `report_boot` 里统一打） + let boot = boot_probe(&options); + let decision = boot.decision; + diagnostics::report_boot(&options, &boot.probe, &decision); + + // ② 字体（`fonts` 自己打两行既有日志；新加的那行在 `report_font` 里） + let font_started = Instant::now(); + let resolved = fonts::resolve(); + let font_ms = font_started.elapsed(); + eprintln!("[font] 求值耗时 {:.0} ms", font_ms.as_secs_f64() * 1000.0); + eprintln!("{}", resolved.describe()); + if resolved.has_synthetic() { + eprintln!( + "[font] 警告：有字重落在「合成加粗」档（观感降级），D28 后半（CDN 字体/按档换字族）要处理" + ); + } + let families = resolved.families(); + + // ③ 打印（主题来源 + 字体回退链 + 启动耗时） + // 截图模式：`--screenshot-theme` > `--theme` > **Light**（唯一取值口 `Options::capture_flavor`）。 + // **不再有**「等系统主题到达」的闸门——CI 的 xvfb 没有主题会话，等它就是挂死（见 cli 文档）。 + if options.screenshot.is_some() && options.shot_flavor().is_none() { + eprintln!("[shot] 未指定主题，按 Light 出图（D30 可复现；CI 冒烟依赖这条默认值）"); + } + let flavor = options.capture_flavor().unwrap_or(SchemeFlavor::Light); + diagnostics::report_theme(&options, flavor); + diagnostics::report_font( + resolved.platform, + boot.probe_ms, + font_ms, + boot_started.elapsed(), + ); + + // ④ 起 iced（失败按判据表第 8/9 行分流；具名原因在分流之前就打到同一个 stderr 上了） + let launch_started = Instant::now(); + let result = match launch(&options, families, flavor, decision.primary) { + Err(iced::Error::GraphicsCreationFailed(error)) => { + renderer::report_failure(decision.primary, &error); + match on_failure(decision, options.screenshot.as_ref()) { + Some(OnFailure::Respawn(fallback)) => { + respawn(decision.primary, fallback, &error.to_string()) + } + Some(OnFailure::Refuse) => { + // 取证启动：**拒绝降级出图**（换了后端出的图会让报告撒谎）。 + eprintln!( + "[gpu] 拒绝降级出图：本次是取证启动（--screenshot {}），换后端出的图会撒谎。", + options + .screenshot + .as_ref() + .map_or_else(String::new, |path| path.display().to_string()) + ); + eprintln!( + "[gpu] 想用 CPU 出图请显式加 --renderer=cpu / --software-renderer（CI 就是这么跑的）。" + ); + Err(iced::Error::GraphicsCreationFailed(error)) + } + None => Err(iced::Error::GraphicsCreationFailed(error)), + } + } + other => other, + }; + let launch_elapsed = launch_started.elapsed(); + + diagnostics::report_outcome( + &decision, + result.as_ref().err().map(|error| { + renderer::named_graphics_error(error).unwrap_or_else(|| error.to_string()) + }), + acceptance::failure_via(decision.fallback.is_some(), options.screenshot.is_some()), + if options.screenshot.is_some() { + "screenshot" + } else { + "interactive" + }, + launch_elapsed, + ); + + result +} + +/// 按一次后端启动 iced。`backend` 决定这次写进 `ICED_BACKEND` 的唯一一项。 +fn launch( + options: &Options, + families: Families, + flavor: SchemeFlavor, + backend: renderer::Kind, +) -> iced::Result { + std::env::set_var("ICED_BACKEND", backend.env_value()); + + let boot_options = options.clone(); + + // M98：`ULL_WINDOW_SIZE=1520x900` 覆盖尺寸（矩阵的「最小 / 宽屏」两档靠它，且必须走**真外壳** + // ——`pages_demo` example 的标题栏是留白带，出不了「三键位置」那张图）。 + let (size, size_source) = acceptance::window_size( + (WINDOW_SIZE.width, WINDOW_SIZE.height), + (MIN_SIZE.width, MIN_SIZE.height), + ); + let settings = diagnostics::window_settings(size); + // 两行日志与开窗用的是**同一个** settings（见模块文档纪律 2） + diagnostics::report_window(&settings, options.scale_factor, size_source); + + let application = iced::application( + move || { + ( + App::new(boot_options.clone(), families, flavor), + Task::done(Message::Boot), + ) + }, + App::update, + App::view, + ) + .title(App::title) + .theme(App::theme) + .subscription(App::subscription) + .default_font(default_font(families)) + .window(settings); + + match options.scale_factor { + Some(scale) => application.scale_factor(move |_| scale).run(), + None => application.run(), + } +} + +/// [`boot_probe`] 的产物：判据 + 探测到的适配器 + **探测耗时（没测就是 `None`）**。 +/// +/// 为什么把 `Probe` 带出来：`[env]` 的 `gpu=` / `hardware=` 必须是**这一次真枚举到的**结果 +/// （再枚举一遍多花 0.65~1.2 s，还可能给出不同状态）。判据与诊断看同一份数据。 +struct Boot { + decision: Decision, + probe: probe::Probe, + probe_ms: Option, +} + +/// 渲染后端探测 + 写 `ICED_BACKEND`，返回判据产物（供 `run` 决定要不要换进程重开）。 +fn boot_probe(options: &Options) -> Boot { + // 「上一步失败后重开」的那一次：别再探（会得到同一个结论，然后无限重开）。兜底必须是 None + // ——由 `decision::fallback_round` 单点保证。 + if let Some(kind) = renderer::forced_fallback() { + let decision = renderer::fallback_round(kind); + std::env::set_var("ICED_BACKEND", kind.env_value()); + eprintln!( + "[probe] 本次是降级重开（{}={}）：跳过探测 -> ICED_BACKEND={}", + renderer::FALLBACK_ENV, + kind.env_value(), + kind.env_value() + ); + eprintln!("[probe] {}", decision.describe()); + // 验收要 `[env]` 里的真实适配器：这一轮**也枚举一次，并如实计时**（没计时就 `None` + // ⇒ 日志写 `probe=skipped`，不写 0ms）。 + let (probe, probe_ms) = if acceptance::enabled() { + let started = Instant::now(); + let probe = probe::Probe::run(); + (probe, Some(started.elapsed())) + } else { + (probe::Probe::default(), None) + }; + return Boot { + decision, + probe, + probe_ms, + }; + } + + // 只有 `auto` 需要探测（`cpu`/`gpu` 的决策与硬件无关，枚举 13 个适配器本机要 0.65~1.2 s）。 + // 验收模式例外：`[env]` 那行要 GPU 名，不管请求是哪个后端。 + let needs_probe = options.backend == crate::Backend::Auto || acceptance::enabled(); + let probe_started = Instant::now(); + let probe = if needs_probe { + probe::Probe::run() + } else { + probe::Probe::default() + }; + let probe_ms = needs_probe.then(|| probe_started.elapsed()); + + // `ULL_PREFLIGHT=1` 时先自己验一遍 wgpu（判据表第 7 行）；默认不跑，见 preflight 模块文档。 + let preflight = renderer::preflight::run_if_requested(); + let decision = probe::apply_with_preflight(options.backend, &probe, preflight.as_ref()); + + if cfg!(feature = "gpu") { + match probe_ms { + Some(elapsed) => eprintln!( + "[probe] 探测耗时 {:.0} ms（wgpu 实例 + 全后端适配器枚举）", + elapsed.as_secs_f64() * 1000.0 + ), + None => eprintln!( + "[probe] 探测耗时 跳过（--renderer={} 与硬件无关，未枚举）", + options.backend.name() + ), + } + } + Boot { + decision, + probe, + probe_ms, + } +} + +/// 默认字体（正文档解析出来的族）。 +fn default_font(families: Families) -> iced::Font { + iced::Font { + family: iced::font::Family::Name(families.text), + ..iced::Font::DEFAULT + } +} + +#[cfg(test)] +#[path = "boot/tests.rs"] +mod tests; diff --git a/crates/app-iced/src/app/boot/diagnostics.rs b/crates/app-iced/src/app/boot/diagnostics.rs new file mode 100644 index 0000000..071fb7b --- /dev/null +++ b/crates/app-iced/src/app/boot/diagnostics.rs @@ -0,0 +1,110 @@ +//! 启动阶段的**验收诊断编排**：把 `app/boot.rs` 的 `run()` 收成「探测 → 字体 → 打印 → 起 iced」。 +//! +//! ## 为什么单独一个文件（M98 r1 p2-1 的根因） +//! +//! 第一版把 `[window] requested … resizable=true decorations=false transparent=false` 直接写在 +//! 格式化串里，而 `boot.rs` 给窗口的 `settings` 是另一处常量 —— 两者**没有任何绑定**。定向变异 +//! 把 `settings.decorations` 改成 `true`，371 个测试全绿，而验收包里 `[caps] decorations=true` 与 +//! `[window] decorations=false` 会互相矛盾（踩坑记录 U1：常量冒充观测结果）。 +//! +//! 现在：窗口设置由 [`window_settings`] **一处**产生，日志由 [`report_window`] 从**同一个 +//! `&window::Settings`** 取字段。钉死它的守门测试在 `boot/tests.rs`（`window_settings_*`）。 +//! +//! 另一件事：所有「跑没跑」都要能如实说。降级重开那一轮没计时就写 `probe=skipped`， +//! 不许拿 `0ms` 冒充一次实测（M98 r1 p3-1）。 + +use std::time::Duration; + +use iced::window; + +use unlucky_design::color::SchemeFlavor; +use unlucky_design::typography::Platform as FontPlatform; + +use crate::cli::Options; +use crate::probe::Probe; +use crate::renderer::{acceptance, Decision}; + +use super::MIN_SIZE; +use crate::app::APP_TITLE; + +/// 产品窗口设置（**唯一产地**：`launch()` 用它开窗，`[window]` / `[caps]` 从它取字段）。 +/// +/// `ULL_WINDOW_SIZE` 的覆盖在 `boot.rs` 解析成 `size` 后从这里进来 —— 日志与真窗口永远同源。 +pub(super) fn window_settings(size: (f32, f32)) -> window::Settings { + window::Settings { + size: iced::Size::new(size.0, size.1), + min_size: Some(MIN_SIZE), + // 自绘三键（M93）：窗口**不许**带系统装饰，否则 macOS 上会出现原生标题栏 + 自绘三键两套。 + decorations: false, + resizable: true, + // M93 / D36：整窗 α 需要 `WS_EX_LAYERED`，但这里给不了——`window::Settings` 没有扩展样式 + // 字段，写它只有 `Get/SetWindowLongPtrW`（`unsafe`，全仓只允许出现在 + // `platform/win32/transparency.rs`）。所以 α 下发在拿到句柄之后（`Message::WindowHandle`）。 + transparent: false, + ..window::Settings::default() + } +} + +/// `[window] requested` + `[caps]` 两行，**都从同一个 `settings` 取**（不给手抄字面量的机会）。 +pub(super) fn report_window(settings: &window::Settings, scale: Option, 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..ef20a28 --- /dev/null +++ b/crates/app-iced/src/app/boot/fallback.rs @@ -0,0 +1,117 @@ +//! 起步后端失败后的**兜底/重开**一簇：判据、进程环境交接、`respawn`、退出码透传。 +//! +//! 从 `app/boot.rs` 拆出来的理由：这一簇**与启动编排零耦合**，但已有 5 条测试，而且它是 +//! M97 判据表第 8/9 行的落点。`boot.rs` 那边只负责「什么时候调它」。 +//! +//! ## 为什么必须换进程（别改回进程内重试） +//! +//! Windows 实测本进程里再 `run()` 一次直接 panic +//! （`iced_winit-0.14.1/src/lib.rs:81` → `Create event loop: RecreationAttempt`），winit 一个进程 +//! 只能建一次事件循环。 + +use crate::renderer::Decision; +use crate::renderer::{self, acceptance, Kind}; + +/// 起步后端失败后的去向（判据表第 8 行 vs 第 9 行——**两条路策略不同，别合成一条**）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(super) enum OnFailure { + /// 交互启动：安全网优先，换进程用这个后端重开。 + Respawn(Kind), + /// 取证启动：红着退出，**不出图**。 + Refuse, +} + +/// 纯判据：起步后端失败时走哪条路。 +/// +/// `evidence` 非空 = 本次是取证启动（带 `--screenshot`）；返回 `None` = 没有兜底可用 +/// （`--renderer=cpu` / 未编 wgpu），原样把错误交回去。抽成纯函数只为一个理由：这条分支以前 +/// **没有任何测试**，`respawn` / `Refuse` 两条路可以被静默改反（M97 r1 p2-1 就是这么测出来的）。 +pub(super) fn on_failure( + decision: Decision, + evidence: Option<&std::path::PathBuf>, +) -> Option { + let fallback = decision.fallback?; + Some(match evidence { + Some(_) => OnFailure::Refuse, + None => OnFailure::Respawn(fallback), + }) +} + +/// 降级重开要传给子进程的环境变量（**两条缺一不可**）。 +/// +/// ① `ICED_BACKEND`：让子进程直接用 `fallback` 跑。 +/// ② [`renderer::FALLBACK_ENV`]：**防无限重开的闸门**——子进程见它就必须跳过探测 +/// （`boot_probe` 的第一个分支），否则会算出同一个结论、再失败、再 respawn。 +/// +/// 抽成纯函数是为了让「漏传其中之一」变成**测试能抓到**的错误：两条都是静默失效型 +/// （漏 ① 重开又跑一遍 wgpu、漏 ② 无限重开），线上极难看出来。 +pub(super) fn fallback_env(fallback: Kind) -> [(&'static str, &'static str); 2] { + [ + ("ICED_BACKEND", fallback.env_value()), + (renderer::FALLBACK_ENV, fallback.env_value()), + ] +} + +/// 安全网：起一个**新进程**用 `fallback` 后端重开，然后带着它的退出码退出。 +/// +/// 只在**交互启动**时走到这里（取证启动宁可红着退出也不换后端出图）；子进程看到 +/// [`renderer::FALLBACK_ENV`] 必须跳过探测，否则无限递归重开（闸门在 `boot_probe` 入口）。 +pub(super) fn respawn(failed: Kind, fallback: Kind, error: &str) -> ! { + let exe = std::env::current_exe().unwrap_or_else(|err| { + eprintln!("[gpu] 降级重开失败：拿不到自身路径（{err}）"); + std::process::exit(exit_code(None)); + }); + eprintln!( + "[gpu] 降级 → {}（{} 已失败，原因见上两行；换一个进程重开：winit 不允许同进程建两次事件循环）。\ + 下一次的日志从 `[probe] 本次是降级重开` 开始。", + fallback.name(), + failed.name() + ); + // `[backend] final` 一行把「哪个后端失败了、去了哪、为什么」收在一起（可 grep 的单一结论行）。 + // 这里 `final=` 装的是**兜底**（进程即将带着它重开）；`via=respawn` 说明它是换进程去的。 + acceptance::report_backend_failed(failed, Some(fallback), Some(fallback), "respawn", error); + + let status = fallback_command(&exe, std::env::args_os().skip(1), fallback).status(); + + // 退出码**透传**子进程的：上层脚本/CI 靠它判断成败。写错的失效方式是「安静地给出一个错 + // 结论」——不崩、不静默降级、不无限重开，只是让 CI 把失败当成功。 + let code = match status { + Ok(status) => exit_code(status.code()), + Err(err) => { + eprintln!("[gpu] 降级重开失败：{err}"); + exit_code(None) + } + }; + std::process::exit(code) +} + +/// 子进程退出码 → 本进程退出码。 +/// +/// `None` = 子进程被信号杀死（只有 Unix）：走兜底码而**不是** panic、也不是 0——上层判据是 +/// 「非零 = 失败」，「拿不到退出码」和「退出码是某个非零值」对脚本是一回事。 +pub(super) fn exit_code(code: Option) -> i32 { + /// 重开失败 / 拿不到退出码时的兜底码（与 `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 { + let mut command = std::process::Command::new(program); + command.args(args).envs(fallback_env(fallback)); + command + .stdin(std::process::Stdio::inherit()) + .stdout(std::process::Stdio::inherit()) + .stderr(std::process::Stdio::inherit()); + command +} diff --git a/crates/app-iced/src/app/boot/tests.rs b/crates/app-iced/src/app/boot/tests.rs new file mode 100644 index 0000000..b247030 --- /dev/null +++ b/crates/app-iced/src/app/boot/tests.rs @@ -0,0 +1,271 @@ +//! `app/boot.rs` 的单元测试 + **变异验证说明**（M97 r1）。 +//! +//! 放独立文件（同 `pages/harness/tests.rs`）是为了让 `boot.rs` 留在 400 行内。 + +//! ## 变异验证怎么做（M97 r1 的教训，改测试前先读这段） +//! +//! 这批测试的价值不是「跑绿了」，而是「把实现改坏会红」。做变异时**只在目标函数体内替换**， +//! 并且把测试里的同一字面量排除在外： +//! +//! ```text +//! # // 示意（真实脚本是一次性的，没入库） +//! def in_body(path, marker, changes): +//! """按函数体范围替换。**不能**全局 sed：那会连测试期望里的同一字面量一起改掉， +//! 于是实现和断言被换成同一个错值 ⇒ 测试照样绿 ⇒ 验证的是变异脚本自己。""" +//! ``` +//! +//! M97 r1 第一次跑变异时，M1/M2/M3 三个变异「照样绿」——不是测试弱，是脚本用全局 `sed` +//! 把断言一起改了。这类假绿最阴：变异验证本来是我们判断「测试够不够」的终极手段， +//! 手段本身假绿时，它还会附赠「已验证」的强信心。 + +use super::fallback::*; +use super::*; + +use crate::renderer::acceptance::WindowFacts; +use crate::renderer::decision; +use crate::renderer::Kind; +use std::ffi::{OsStr, OsString}; +use std::path::Path; + +fn probe(device_type: &'static str) -> crate::Probe { + crate::Probe { + adapters: vec![crate::probe::AdapterSummary { + name: "adapter".to_owned(), + device_type, + }], + hardware: !matches!(device_type, "Cpu" | "Other"), + } +} + +/// **降级重开到底传了什么**（M97 r1 p2-1 的守门）。 +/// +/// 抓得住：`fallback_env` 少写/写错任一条——两条都是静默失效型： +/// 漏 `ICED_BACKEND` ⇒ 子进程又去试 wgpu（白开一次窗）；漏 `ULL_GPU_FALLBACK` ⇒ **无限重开**。 +/// 抓不住：`Command` 本身没被建起来（那要真起进程，见 §「Windows 实测」）。 +#[test] +fn fallback_env_carries_the_backend_and_the_gate() { + for fallback in [Kind::TinySkia, Kind::Wgpu] { + let env = fallback_env(fallback); + assert_eq!( + env.len(), + 2, + "就这两条，多一条少一条都要在这里改文档：{env:?}" + ); + assert!( + env.contains(&("ICED_BACKEND", fallback.env_value())), + "子进程必须直接用 {fallback:?} 跑，实际 {env:?}" + ); + assert!( + env.contains(&(renderer::FALLBACK_ENV, fallback.env_value())), + "缺防无限重开的闸门 {FALLBACK_ENV:?}，实际 {env:?}", + FALLBACK_ENV = renderer::FALLBACK_ENV + ); + } +} + +/// 闸门的另一半：子进程那一轮的决策**不能再有兜底**，否则失败后继续 respawn ⇒ 无限递归。 +/// +/// 抓得住：`fallback_round` 的 `fallback` 被写成 `Some(..)`（自杀式循环）。 +/// 抓不住：`forced_fallback()` 没被 `boot_probe` 调用（那是环境变量的读，见下一条的说明）。 +#[test] +fn fallback_round_never_degrades_again() { + for kind in [Kind::TinySkia, Kind::Wgpu] { + let decision = decision::fallback_round(kind); + assert_eq!(decision.primary, kind); + assert_eq!( + decision.fallback, None, + "降级重开那一次不许再有兜底，否则会无限递归重开" + ); + assert_eq!(decision.reason, "fallback-after-failure"); + } +} + +/// 判据表第 8 行 vs 第 9 行：**交互降级 / 取证拒绝**，两条路的策略不同。 +/// +/// 抓得住：`--screenshot` 分支被改回「也降级」（那正是 M97 要杀的「取证工具自己换后端」）。 +/// 抓不住：`screenshot` 传进来的时机（那是 `run()` 的接线，见 Windows 实测记录）。 +#[test] +fn evidence_start_refuses_instead_of_degrading() { + let auto = decision::decide(crate::Backend::Auto, &probe("IntegratedGpu"), true); + let evidence = std::path::PathBuf::from("out.png"); + + assert_eq!( + on_failure(auto, Some(&evidence)), + Some(OnFailure::Refuse), + "取证启动 + wgpu 起不来 ⇒ 拒绝出图" + ); + assert_eq!( + on_failure(auto, None), + Some(OnFailure::Respawn(Kind::TinySkia)), + "交互启动 + wgpu 起不来 ⇒ 换进程降级" + ); +} + +/// **构造侧**：argv 原样透传、两组 env 都在、program 就是传进来的那个。 +/// +/// 抓得住：重开时丢掉用户参数（`--screenshot` / `--screen` / `--data-dir` 全没了， +/// 子进程会按默认参数跑，那是最难查的一种「重开后行为变了」）、env 少传（M97 r1 的 p2-1）。 +/// 抓不住：stdio 继承（`Command` 没有 stdio getter，只能真跑一次，见 `fallback_command` 的注释）。 +#[test] +fn fallback_command_passes_program_argv_and_envs() { + let args = ["--renderer=auto", "--screenshot", "out.png"]; + let command = fallback_command( + Path::new("unlucky-launcher-iced"), + args.iter().map(OsString::from), + Kind::TinySkia, + ); + + assert_eq!( + command.get_program(), + OsStr::new("unlucky-launcher-iced"), + "program 必须是传进来的那个（生产里是 current_exe）" + ); + assert_eq!( + command.get_args().collect::>(), + 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/message.rs b/crates/app-iced/src/app/message.rs new file mode 100644 index 0000000..2fcaabb --- /dev/null +++ b/crates/app-iced/src/app/message.rs @@ -0,0 +1,101 @@ +//! 应用消息：单一大枚举。 +//! +//! 纪律：本枚举是**唯一**的消息类型，`view` 产出的所有回调都必须落到这里；组件库与页面层 +//! 各自用自己的 `Message`（组件契约 §2 的泛型纪律），由 `view` 做一次 `.map` 接上。 +//! +//! ## 三类输入（M90） +//! +//! | 来源 | 变体 | 落点 | +//! |---|---|---| +//! | 窗口/框架 | `Boot` / `WindowReady` / `Window` / `Frame` / `Captured` / 三个 caption | [`super::update`] 直接处理 | +//! | **时间** | `Frame`（忙碌，33 ms 闸门）+ `Heartbeat`（空闲，1 Hz） | presenter 的 TICK 节拍：`backend.tick` + `drain_events` + `apply` | +//! | **页面** | `Page(pages::Message)` | 导航 → `AppState::navigate`；启动/停止 → `AppCommand` | + +use iced::{window, window::Direction}; + +use unlucky_presenter::router::Route; + +use crate::pages; +use crate::shell::NavItem; + +use super::components; + +/// 消息（单一大枚举）。 +#[derive(Debug, Clone)] +pub enum Message { + /// 启动即发一次（`iced::application` 的 boot 闭包）。 + Boot, + /// `window::latest()` 的结果。 + WindowReady(Option), + /// 系统主题探测结果（只可能在**交互模式**出现，截图模式必有主题）。 + 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), +} + +/// 外壳导航项 → 路由（导航项只在一级页之间有对应；AI 项对应 [`Route::Agent`]）。 +/// +/// 这是 `NavItem → Route` 的**唯一**转换点：外壳（`src/shell/nav.rs`）与页面导航轨 +/// （`pages::NAV`）最终都落到同一个 `Route`，所以两条入口不会各走一套页面语义。 +pub(super) fn route_of(nav: NavItem) -> Route { + match nav { + NavItem::Instances => Route::Instances, + NavItem::Download => Route::Download, + NavItem::Logs => Route::Logs, + NavItem::Settings => Route::Settings, + NavItem::Ai => Route::Agent, + // 轨底头像位（M114）：账户是一级页，但**不在主序列**里 + NavItem::Account => Route::Accounts, + } +} + +/// 路由 → 外壳导航项（[`route_of`] 的逆；外壳 rail 与 caption 键都按它高亮）。 +/// +/// `Route::Detail(_)` 高亮「实例」（与 `Route::nav()` 同源）。 +pub(super) fn nav_item_of(route: &Route) -> NavItem { + match route { + Route::Instances | Route::Detail(_) => NavItem::Instances, + // M109：内容库与版本管理共用「下载」那一个导航项（B1 裁定） + Route::Download | Route::Content => NavItem::Download, + Route::Logs => NavItem::Logs, + Route::Settings => NavItem::Settings, + Route::Agent => NavItem::Ai, + Route::Accounts => NavItem::Account, + } +} diff --git a/crates/app-iced/src/app/mod.rs b/crates/app-iced/src/app/mod.rs new file mode 100644 index 0000000..a58ccbb --- /dev/null +++ b/crates/app-iced/src/app/mod.rs @@ -0,0 +1,71 @@ +//! Elm 三件套：`State` / `Message` / `update` + `view` 接线，以及启动序列。 +//! +//! 启动序列：①探测渲染后端并写 `ICED_BACKEND`（必须在 `run()` 之前，M60 Q1）→ ②求值字体栈 +//! （D28 前半）→ ③`iced::application(..).run()`（1180×760、无边框自绘标题栏）→ ④首个 `view()` +//! 打耗时；截图模式第 3 帧落盘后退出（无边框窗首帧可能是旧尺寸，M60 坑 #5）。 +//! +//! ## 为什么拆成目录（M90） +//! +//! 本文件原来是**单个 400 行的 `app.rs`**：正好卡在「单文件 ≤400 行、动它前必须先拆」的硬门槛上 +//! （AGENTS 的文件上限 + 本 mission 的第一条任务）。拆法与职责： +//! +//! | 文件 | 职责（**只做这一件事**） | +//! |---|---| +//! | [`state`] | [`App`] 字段 + 构造（presenter 三件在此持有）+ 主题切换 | +//! | [`message`] | [`Message`] 枚举与「导航项 → 路由」的翻译 | +//! | [`update`] | 全部 `Message` 分支 + 「用户动作 → `AppCommand`」的派发与事件回流 | +//! | [`subscription`] | 帧事件（截图）与 presenter 的 TICK 节拍 | +//! | [`view`] | `view` / `theme` / `title` | +//! | [`boot`] | [`run`]：后端探测 → 字体 → `iced::application(..)` | +//! +//! 拆分的每一步都保持**可观察行为不变**（截图四件套 `--screenshot` / `--screenshot-theme` / +//! `--screen=gallery` / `--diff` 出图逐字节相同），presenter 接线是在拆分**之后**另一步做的。 +//! +//! ## 组件库为什么还在本模块下声明 +//! +//! `src/lib.rs` 是五条组件线共用的文件，改它必然冲突；`#[path]` 保证物理路径仍是 +//! `src/components/`（组件目录自己的归属规则不变），逻辑路径仍是 `crate::app::components` +//! （组件源码里的文档与测试都按这个路径写）。 + +mod appearance; +mod backend; +mod boot; +mod message; +mod state; +mod subscription; +mod update; +mod view; +mod window_alpha; + +#[cfg(test)] +mod tests; + +pub(crate) use boot::run; +pub use message::Message; + +// 组件库（D39）在本文件声明：`src/lib.rs` 是五条组件线共用的文件，改它必然冲突； +// `#[path]` 保证物理路径仍是 `src/components/`（组件目录自己的归属规则不变）。 +// +// M90：可见性从 `mod` 放到 `pub(crate) mod` —— 页面层（`src/pages/**`）要**用**真组件 +// （`components::buttons` / `navigation` / `divider`），而 `app` 不是它的父模块。 +// 只放开 crate 内可见，组件目录的归属规则一字不改。 +#[path = "../components/mod.rs"] +pub(crate) mod components; + +/// 验收窗口尺寸（1180×760 @100% DPI —— D30 的硬要求）。 +pub const WINDOW_SIZE: iced::Size = iced::Size { + width: 1180.0, + height: 760.0, +}; + +/// 产品名（自绘标题栏的标题；`'static` 好让 view 借用）。 +pub const APP_TITLE: &str = "Unlucky Launcher"; + +/// 窗口最小尺寸（再小骨架会挤坏：88 导航 + 页面留白 + 卡片）。 +const MIN_SIZE: iced::Size = iced::Size { + width: 880.0, + height: 560.0, +}; + +/// 截图落盘的帧号（见模块文档）。 +const CAPTURE_AT_FRAME: u32 = 3; diff --git a/crates/app-iced/src/app/state.rs b/crates/app-iced/src/app/state.rs new file mode 100644 index 0000000..2ab97b1 --- /dev/null +++ b/crates/app-iced/src/app/state.rs @@ -0,0 +1,188 @@ +//! 应用状态：**只放字段与构造**，不放消息分支（那是 [`super::update`] 的事）。 +//! +//! ## presenter 三件（`crates/presenter/src/lib.rs` crate 文档 §4） +//! +//! | 字段 | 谁给 | 干什么 | +//! |---|---|---| +//! | `backend: Box` | [`build_backend`](unlucky_presenter::backend::build_backend) | 派发 [`AppCommand`](unlucky_presenter::dto::AppCommand)、收 [`AppEvent`](unlucky_presenter::dto::AppEvent) | +//! | `bridge: SettingsBridge` | [`SettingsBridge::open`](unlucky_presenter::settings_bridge::SettingsBridge::open) | 读一次外观/主题，之后每 N 拍问「文件变了吗」 | +//! | `state: AppState` | [`AppState::new`](unlucky_presenter::state::AppState::new) | **唯一**的状态写入口（`apply` / `navigate`） | +//! +//! `view: pages::Model` 是**展示转换的缓存**：presenter 快照 → 页面要画的东西。 +//! 它在**状态真的变了**时重建（[`App::view_dirty`] 门控，M90 r2/P2-1 起），不是每拍重建—— +//! 重建要把 N 个实例的名字/版本串克隆一遍，30 Hz 空转没有意义。缓存成字段是为了让 +//! `view(&self)` 能只借 `&self`：iced 的 `view` 签名不允许返回一棵借用局部变量的树。 +//! +//! ## 本文件只管「有哪些字段」 +//! +//! M119 起按功能拆出去（`state.rs` 当时正好 400 行、零余量）： +//! +//! | 子文件 | 内容 | +//! |---|---| +//! | [`construct`] | 两个构造器 + 字段初始化表 | +//! | [`refresh`] | [`App::refresh_view`]（快照 → 视图模型的唯一转换点） | +//! | [`theme`] | `Ui` 重算 / 主题档 / [`App::has_screenshot`] | +//! | [`boot_probe`] | 启动探针（`ULL_*` 取证开关与首帧日志） | + +use std::time::Instant; + +use iced::window; + +use unlucky_presenter::dto::Backend; +use unlucky_presenter::prefs::ThemeMode; +use unlucky_presenter::settings_bridge::SettingsBridge; +use unlucky_presenter::state::AppState; + +use crate::cli::Options; +use crate::pages; +use crate::theme::{Families, Ui}; +use crate::ui::lang::LangState; + +/// presenter 的 TICK 节拍（33 ms ≈ 30 fps）——**忙碌态**的节拍。 +/// +/// 与 Slint 版的 `TICK_MS` 同值：`backend.tick(..)` 的时间推进、toast 过期、 +/// `theme::config_poll_due` 的计数都按这个节拍走，两个 UI 版的时间语义因此一致。 +pub(super) const TICK_MS: u64 = 33; + +/// [`TICK_MS`] 的 `Duration` 形态。 +pub(super) const TICK: std::time::Duration = std::time::Duration::from_millis(TICK_MS); + +/// **空闲态**的低频心跳（1 Hz，M90 r3 / P2-2）。 +/// +/// 空闲时不能订阅 `window::frames()`：那条订阅会自持重绘循环（实测软件渲染约 500 帧/秒）， +/// 而空闲时唯一需要的时钟是「偶发一次」——外部 CLI / AI 工具改 `launcher.json` 后的热切 +/// （presenter 的 `theme::config_poll_due` 语义是 30 × 33 ms ≈ 1 秒一拍）。 +/// +/// 实现用的是 `Task::perform(async { sleep(1s) })` 的自续链：[`App::heartbeat`]。它每秒只唤醒 +/// 一次、只触发**一帧**重绘，而 `frames()` 是每秒几百帧。为什么不用 `iced::time::every`： +/// 它挂在 tokio/smol 后端下，本 crate 的执行器是 thread-pool（Cargo.toml 不在 scope）。 +pub(super) const IDLE_TICK: std::time::Duration = std::time::Duration::from_secs(1); + +/// 派发指令后保持帧订阅的观察窗（见 [`App::watch_until`]）。 +/// +/// 3 秒够真 host 把「命令已受理」的第一条事件交回来；之后由「有 Busy/Running 实例」这个条件续订。 +pub(super) const WATCH_WINDOW: std::time::Duration = std::time::Duration::from_secs(3); + +mod boot_probe; +mod construct; +mod refresh; +mod theme; + +/// iced 侧的 presenter 接线层（M119）：物理目录 `src/presenter/`，逻辑名字在 `crate::app::state` 下。 +/// +/// 为什么用 `#[path]` 而不是在 `lib.rs` 加一行 `mod presenter;`：本 mission 的 scope 不含 +/// `lib.rs` / `app/mod.rs`，而 `shell::agent` 挂 `pages/agent/` 是同一个先例。没有第二份实现。 +#[path = "../presenter/mod.rs"] +pub(super) mod presenter; + +pub(crate) use boot_probe::{log_first_frame, STARTED}; + +/// 应用状态：UI 状态 + presenter 三件 + 展示转换缓存。 +pub struct App { + /// 启动参数（截图/主题/画面开关）。 + pub(super) options: Options, + /// 字体族（切主题时重建 [`Ui`] 要用）。 + pub(super) families: Families, + /// 令牌求值器（浅/深两套）。 + pub(super) ui: Ui, + /// 后端通道（真 host 或 mock）。 + pub(super) backend: Box, + /// 设置持久化桥。 + 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, + /// 窗口高度（背景图平铺网格的视口判据；宽度在 `width`）。 + pub(super) height: f32, + /// 外观运行期状态（M93）：面板 α / 背景图 / 配色来源 / 诊断。 + pub(super) appearance: pages::appearance::State, + /// 设置文件里那 8 个「UI 写入」外观字段的最近快照（写回时只改我们真改了的字段， + /// 强调色这类本 mission 不管的字段原样保留）。 + pub(super) appearance_prefs: unlucky_presenter::prefs::AppearancePrefs, + /// 窗口句柄（`Message::WindowHandle` 之后才有；非 Windows 平台恒 `None`）。 + pub(super) hwnd: Option, + /// 设置页各组自己的运行期状态（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, + /// 内容库页的页面内选择（M109）：内容类型 / 选中项目 / 目标实例 / 关键词草稿。 + /// + /// 为什么在 `App` 而不是 presenter：这四样是「用户在这一屏上点了什么」，重建快照不该冲掉； + /// 而检索条件与结果（会跨页存活、要被事件写）在 `AppState::content`。放进 `view` 模型也 + /// 不行——`refresh_view` 每次都用快照重建模型，选择会被冲回默认值。 + pub(super) content: pages::content::PageState, + /// 账户页的**表单状态**（三条轨道的输入串；密码只活在这一次请求里）。 + pub(super) account_form: pages::account::Form, + /// 账户页视图模型（与 `view` 同一条「状态变了才重建」的门控）。 + pub(super) account: pages::account::Page, + /// 皮肤/头像解码缓存（M114：同一张皮肤只解一次）。 + pub(super) avatars: pages::account::avatar::Cache, + /// 上一次**真下发过**的圆角判定指纹（M116 r1 复审 P2-4：判定没变就不重下、不重记日志）。 + /// + /// `None` = 还没下发过（首屏 `boot` 那一次）。指纹类型见 + /// [`crate::platform::win32::corner::CornerApplied`]。 + pub(super) corner_applied: Option, +} diff --git a/crates/app-iced/src/app/state/boot_probe.rs b/crates/app-iced/src/app/state/boot_probe.rs new file mode 100644 index 0000000..a5852ed --- /dev/null +++ b/crates/app-iced/src/app/state/boot_probe.rs @@ -0,0 +1,40 @@ +//! 启动期取证：后端选项的换算 + 首帧耗时那一行日志。 +//! +//! 从 `app/state.rs` 拆出（rebase 到 5adac23 之后 `state.rs` 顶到 401 行）。这两件事都属于 +//! 「进程启动那一刻记了什么」，与 `App` 的状态机无关；`state.rs` 只留 `pub(super) use` 再导出， +//! 于是 `app/boot.rs`（`use super::state::STARTED`）与 `app/view.rs`（`log_first_frame`）的既有路径一字未变。 + +use std::sync::atomic::{AtomicBool, Ordering}; +use std::sync::OnceLock; +use std::time::Instant; + +use crate::cli::Options; +use unlucky_presenter::backend::AppOptions; + +/// 进程内「run() 开始」的时刻（首帧耗时基线）。 +pub(crate) static STARTED: OnceLock = 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(), + } +} + +/// 首帧耗时日志（只在第一次 `view()` 打一行）。 +pub(crate) fn log_first_frame() { + if FIRST_FRAME_LOGGED.swap(true, Ordering::Relaxed) { + return; + } + if let Some(started) = STARTED.get() { + eprintln!( + "[boot] first frame in {:.0} ms（run() 开始 → 首次 view，含后端探测与字体扫描）", + started.elapsed().as_secs_f64() * 1000.0 + ); + } +} diff --git a/crates/app-iced/src/app/state/construct.rs b/crates/app-iced/src/app/state/construct.rs new file mode 100644 index 0000000..8d65d91 --- /dev/null +++ b/crates/app-iced/src/app/state/construct.rs @@ -0,0 +1,148 @@ +//! `App` 的两个构造器（从 `state.rs` 搬出来守 400 行硬线；M119 拆，纯搬不改）。 +//! +//! | 构造器 | 谁用 | 碰不碰磁盘 | +//! |---|---|---| +//! | [`App::new`](super::App::new) | 生产（`main` → `boot`） | 按启动参数选后端 + 打开设置桥 | +//! | [`App::with_presenter`](super::App::with_presenter) | 单测（后端与桥都由调用方给） | **不碰** | +//! +//! 两个都走 `with_presenter`：生产路径只是先造好后端与桥。**字段初始化表**也在这一个文件里 +//! （构造 = 字段表 + 三件外部依赖），加字段时只改这一处。 + +use iced::window; + +use unlucky_design::color::SchemeFlavor; +use unlucky_presenter::backend::{build_backend, config_path}; +use unlucky_presenter::dto::Backend; +use unlucky_presenter::settings_bridge::SettingsBridge; +use unlucky_presenter::state::AppState; + +use crate::cli::Options; +use crate::pages; +use crate::theme::{Families, Ui}; +use crate::ui::lang::LangState; + +use super::super::WINDOW_SIZE; +use super::boot_probe::app_options; +use super::App; + +impl App { + /// 生产构造：按启动参数选后端、打开设置桥。 + /// + /// **截图通道强制 mock**：出图要可复现（D30），真 host 会按本机盘上的实例清单画面， + /// 同一份代码在两台机器上出不了同一张图。交互模式走真 host（数据根解析不出来时 + /// [`build_backend`] 自己退回 mock）。 + pub(in crate::app) fn new(options: Options, families: Families, flavor: SchemeFlavor) -> Self { + let backend = build_backend(&app_options(&options)); + // P2-2：设置桥必须与后端指向**同一个数据根**。早先这里无条件 `SettingsBridge::open()` + // （按便携配置解析），于是 `--data-dir X` 会出现「实例来自 X、主题/设置读写默认根」的一进程 + // 两个数据根。Slint 版是同一条口径：`app/src/ui_bind.rs` 的 + // `Some(root) => SettingsBridge::with_path(config_path(root))`。 + let bridge = match &options.data_dir { + Some(root) => SettingsBridge::with_path(config_path(root)), + None => SettingsBridge::open(), + }; + Self::with_presenter(options, families, flavor, backend, bridge) + } + + /// 注入式构造（单测用：后端与桥都由调用方给，**不碰磁盘**）。 + pub(in crate::app) fn with_presenter( + options: Options, + families: Families, + flavor: SchemeFlavor, + backend: Box, + bridge: SettingsBridge, + ) -> Self { + let width = WINDOW_SIZE.width; + let height = WINDOW_SIZE.height; + let theme_mode = bridge.load().1; + // 外观两半分开读：`load()` 给 8 个 UI 写入字段，`load_base()` 给 4 个只读下层键 + // （整窗 α / 标题栏三态 / 配色来源 / 窗口圆角）。M93 之前这些键在 app 侧**根本读不到**。 + // + // 截图通道**不读用户配置**（D30：同一份代码在两台机器上要出同一张图）：外观一律取出厂值， + // 矩阵需要的值由 `ULL_APPEARANCE_*` 显式灌进来。 + let (appearance_prefs, appearance_base) = if options.screenshot.is_some() { + ( + unlucky_presenter::prefs::AppearancePrefs::factory(), + unlucky_presenter::prefs::AppearanceBase::factory(), + ) + } else { + (bridge.load().0, bridge.load_base()) + }; + // 面板 α / 玻璃的降级判据要的是**实际**后端，不是 `--renderer` 的请求值（复审 r1 P2-2）： + // 默认 `Auto` + 无独显时请求是 Auto、实际是 tiny-skia，只看请求值就会漏掉 D36 的强制项。 + let backend_tier = super::super::backend::effective_backend(options.backend); + let mut appearance = pages::appearance::State::new( + &appearance_prefs, + &appearance_base, + backend_tier, + flavor, + ); + // 取证开关（D30）：`ULL_SETTINGS_GROUP=<下标>` 直达设置页的某一组（出图要看见语言行）。 + if let Some(index) = + crate::ui::lang::screenshot_settings_group(options.screenshot.is_some()) + { + appearance.selected_group = index; + } + // 界面语言（M106）：**M92 已经探测对了，问题是一直没人用**——`pages::Model.lang` 此前在 + // `view::model` 里被写死成 `Lang::En`，于是中文系统上开出来的是全英文界面。 + let lang = LangState::boot(&bridge, options.screenshot.is_some()); + let mut view = pages::Model::new( + pages::Screen::Instances, + width, + Some(pages::Screen::Instances.nav()), + ); + view.lang = lang.lang(); + + let mut app = Self { + ui: Ui::new(flavor, families), + families, + options, + backend, + bridge, + state: AppState::new(), + ticks: 0, + config_due_at: unlucky_presenter::theme::CONFIG_POLL_TICKS, + theme_mode, + lang, + last_tick: std::time::Instant::now(), + width, + view, + view_dirty: false, + watch_until: None, + window: None::, + frames: 0, + refreshes: 0, + auto_selected: false, + height, + appearance, + appearance_prefs, + hwnd: None, + settings: pages::settings::Groups::default(), + // 出厂是**空会话**（M119 删了 M104 的样本会话）；取证开关 `ULL_AGENT_*` 的档位 + // 与夹具在 `boot_agent` 里落地（它要先让 presenter 知道栏可见性，见那里）。 + agent: crate::shell::agent::AgentUi::new(), + agent_host: super::presenter::AgentHost::from_env(), + // 下载页安装草稿（M105）：出厂态 = 没选中、原版、两个空串 + download_draft: pages::InstallDraft::default(), + install_cancelled_seen: 0, + content: pages::content::PageState::default(), + account_form: pages::account::Form::new(), + account: pages::account::Page::build( + &AppState::new(), + &pages::account::Form::new(), + &mut pages::account::avatar::Cache::default(), + unlucky_i18n::Lang::En, + width, + ), + avatars: pages::account::avatar::Cache::default(), + corner_applied: None, + }; + // 配色来源档可能已经指向一张背景图：那时 `Ui` 必须由解析出的方案构造，而不是 baseline。 + app.rebuild_ui(); + // 两行日志：①档位 + 探测结论 + 生效语言 ②中文策略（D28 缺字体不许静默）。 + // 下一个人据此分得清「探测错了」还是「探测对了但没用上」。 + app.lang.log(); + app.lang.log_cjk(); + app + } +} diff --git a/crates/app-iced/src/app/state/refresh.rs b/crates/app-iced/src/app/state/refresh.rs new file mode 100644 index 0000000..855c3c8 --- /dev/null +++ b/crates/app-iced/src/app/state/refresh.rs @@ -0,0 +1,61 @@ +//! 快照 → 视图模型的重建口径（从 `state.rs` 搬出来守 400 行硬线；M119 拆，纯搬不改）。 +//! +//! 全仓只有 [`App::refresh_view`] 这一个「presenter 快照 → 页面要画的东西」的转换点， +//! 由 [`App::view_dirty`](super::App) 门控（M90 r2/P2-1 起）：只有真的改了状态的事情才置位， +//! 30 Hz 空转不重建（重建要把 N 个实例的名字/版本串克隆一遍）。 + +use unlucky_presenter::toast::ToastKind; + +use crate::pages; + +use super::App; + +impl App { + /// 把 presenter 的快照转换成页面视图模型（**展示转换在 UI 侧做**）。 + /// + /// 代价是「克隆 N 个实例的名字/版本串」，所以只在 [`App::view_dirty`] 置位时调用（P2-1）。 + pub(in crate::app) fn refresh_view(&mut self) { + // **不变式先对齐再算宽度**（M104 / 复审 r1 P2-1）：`Route::Agent` ⟺ `RailState::Detached`。 + // 每一次路由变化都会走到这里，所以它是「档位 ↔ 路由」的唯一点；放在算宽度之前， + // 是为了让模型拿到的 `content_width` 与页面头部读到的档位来自同一份状态。 + self.sync_agent_route(); + // M119：把「栏可见吗」写回 presenter（未读口径的输入，两个窄入口：`navigate` + `prefs_mut`）。 + // 必须在 `sync_agent_route` 之后：档位刚被它对齐过，这里读到的才是这一帧的真值。 + self.sync_agent_presenter(); + + // M105：取消安装的提示语在**这里**弹（`refresh_view` 是事件 apply 之后必经的那一处）。 + // 文案由页面层求（`pages::cancelled_toast`），presenter 只发信号 —— + // 否则会出现「选项区英文、取消弹窗中文」的同屏两语（复审 P2-2）。 + if self.state.install_cancelled != self.install_cancelled_seen { + self.install_cancelled_seen = self.state.install_cancelled; + // M106：提示语跟着**生效语言**走（M105 留的 `view::ui_lang()` 占位已删——它恒英文， + // 中文界面会弹出英文提示，那正是 M105 r1 复审 P2-2 要堵的同屏两语）。 + let text = pages::cancelled_toast(self.lang()); + self.state.toasts.push(ToastKind::Info, text); + } + + // 分类是**页面自己持有的过滤条件**（真 host 丢弃 `ListVersions` 的分类参数）： + // 重建视图模型时带回去，否则每次事件都会把 chip 打回「全部」（复审 P2-1）。 + let category = self.view.download.category; + // 草稿同理（M105）：它也是页面自己持有的输入，重建模型时带回去， + // 否则每来一条事件（连安装进度都算）用户填的加载器就被抹回「原版」。 + let draft = self.download_draft.clone(); + // 右栏占掉的宽度先扣掉：面板展开时页面按更窄的宽度排版（「收缩而不是溢出」，M104） + let width = self.agent.content_width(self.width); + // M106：语言形参跟着 `LangState` 走（`draft` 那一位是 M105 的安装草稿）。 + self.view = super::super::view::model( + &self.state, + width, + self.options.force_state, + category, + &draft, + self.lang(), + &self.content, + ); + // 账户页（M114）：与 `view` 同一次门控重建（实现见 `view/account_page.rs`， + // 皮肤解码走缓存，所以重复重建不重解图）。 + self.rebuild_account_page(width); + self.view_dirty = false; + self.refreshes += 1; + } +} diff --git a/crates/app-iced/src/app/state/theme.rs b/crates/app-iced/src/app/state/theme.rs new file mode 100644 index 0000000..6ecb723 --- /dev/null +++ b/crates/app-iced/src/app/state/theme.rs @@ -0,0 +1,86 @@ +//! 主题与 `Ui` 的重算口径（从 `state.rs` 搬出来守 400 行硬线；M119 拆，纯搬不改）。 +//! +//! 三件事在这里：①`Ui` 什么时候重建（[`App::rebuild_ui`]）②主题档怎么定 +//! （[`App::set_flavor`] / [`App::apply_config_theme`]）③读当前求值器（[`App::ui`]）。 +//! +//! 截图通道的判据 [`App::has_screenshot`] 也放在这儿：上面三条里两条都要「截图不读用户配置」。 + +use unlucky_design::color::SchemeFlavor; +use unlucky_presenter::prefs::ThemeMode; + +use crate::theme::Ui; + +use super::App; + +impl App { + /// 本次进程是否走截图通道。 + pub(in crate::app) fn has_screenshot(&self) -> bool { + self.options.screenshot.is_some() + } + + /// 切主题：重建 [`Ui`]（= 重建 Style），**不动任何 UI 状态**。 + /// + /// M93 起 `Ui` 有两个来源：配色来源取到了图（①②级）就用解析出的方案，否则用令牌 baseline。 + /// 所以这里改叫「重算 `Ui`」：先让外观状态记住新深浅（配色解析要它），再重建。 + pub(in crate::app) fn set_flavor(&mut self, flavor: SchemeFlavor) { + if self.ui.flavor() == flavor && self.appearance.flavor() == flavor { + return; + } + + self.appearance.set_flavor(flavor); + let previous = self.ui.name(); + self.rebuild_ui(); + eprintln!( + "[theme] {} -> {} (Theme::name 变化触发缓存重算)", + previous, + self.ui.name() + ); + } + + /// 按「配色来源是否取色成功」重建 [`Ui`]。 + /// + /// 色卡档（③）刻意继续走 `Scheme::baseline`：`resolve_source` 的色卡档返回的是 + /// `DEFAULT_CARD`（天蓝卡）方案，与令牌 baseline 逐色不同，应用它会把**全部既有验收图的 + /// 像素**改掉。这条偏离登记在 `pages::appearance` 的偏离表 #4。 + pub(in crate::app) fn rebuild_ui(&mut self) { + // 面板 α（D36）在这里注入 `Ui`：全仓所有表面色都从 `Ui::layer` 出去，所以这是**唯一** + // 生效点（外壳 / 三页卡片 / 外观分组卡片 / 空态图标块自动同源，调用点没有机会各处自乘）。 + let panel_alpha = self.appearance.effective_panel_alpha(); + self.ui = match self.appearance.derived_scheme() { + Some(scheme) => { + eprintln!( + "[appearance] palette={} → Ui::from_scheme（取色方案接管 49 个角色）", + self.appearance.palette_level() + ); + Ui::from_scheme(*scheme, self.families) + } + None => Ui::new(self.appearance.flavor(), self.families), + } + .with_panel_alpha(panel_alpha); + } + + /// 按设置文件里的主题模式切一次外观；`--theme` 显式给了就不动。 + /// + /// **截图通道直接跳过**：`--screenshot` 的主题唯一取值口是 `Options::capture_flavor` + /// （D30 可复现），读本机 `launcher.json` 会让同一份代码在两台机器上出不同的图。 + /// + /// `ThemeMode::Auto` 不在这里处理：那要看系统主题（`iced::system::theme()` 的结果在 + /// `Message::SystemTheme` 里落地）。 + pub(in crate::app) fn apply_config_theme(&mut self) { + if self.has_screenshot() || self.options.theme.is_some() { + return; + } + let mode = self.bridge.load().1; + self.theme_mode = mode; + match mode { + ThemeMode::Light => self.set_flavor(SchemeFlavor::Light), + ThemeMode::Dark => self.set_flavor(SchemeFlavor::Dark), + ThemeMode::Auto => {} + } + } + + /// 当前令牌求值器（测试与截图日志用）。 + pub(in crate::app) fn ui(&self) -> &Ui { + &self.ui + } +} diff --git a/crates/app-iced/src/app/subscription.rs b/crates/app-iced/src/app/subscription.rs new file mode 100644 index 0000000..15393d6 --- /dev/null +++ b/crates/app-iced/src/app/subscription.rs @@ -0,0 +1,94 @@ +//! 订阅：**按需**帧节拍（presenter 的 TICK）+ 窗口尺寸事件。 +//! +//! ## 为什么要「按需」 +//! +//! iced_winit 在处理完任何一条消息后都会 `request_redraw()`，而 `window::frames()` 监听的是 +//! `RedrawRequested` —— 于是「订阅帧 → 收 Frame → update → 再触发重绘」是一条**自持循环**： +//! 只要订阅着，窗口就永远在重绘（M90 r1 就是这样，CPU 空转）。 +//! +//! 现在只在**真的需要 33 ms 节拍**的时候订阅（[`App::needs_frames`]）： +//! +//! | 条件 | 为什么需要 33 ms 节拍 | +//! |---|---| +//! | 截图通道 | 第 3 帧要落盘 | +//! | 有 `Busy` / `Running` 实例 | 启动进度、日志尾随都靠 `backend.tick` 推进 | +//! | 有未过期的 toast | toast 按毫秒倒计时 | +//! | 刚派发过指令（3 s 观察窗） | 真 host 的异步事件要靠节拍抽出来 | +//! +//! 空闲态**一条帧消息都不来** ⇒ 窗口不重绘、`refresh_view` 不跑（配合 `view_dirty`）。 +//! +//! ## 空闲态的时钟从哪来（M90 r3 / P2-2） +//! +//! r2 把空闲的帧订阅掐掉之后，`config_poll_due` 就再也没被调用过 —— 外部 CLI / AI 工具改 +//! `launcher.json` 后主题**永不生效**（不是「等下次交互」，是「等下一次 dispatch」）。这与 +//! D4「AI 能读改 ULL 配置」直接冲突。 +//! +//! 所以空闲态换成一个 **1 Hz 的自续心跳**（[`crate::app::message::Message::Heartbeat`]， +//! 由 `Task::perform(sleep(1s))` 驱动，见 `update::heartbeat`）：每秒醒一次、推进一拍 +//! presenter（内部按 33 ms 折算 30 拍，于是 `config_poll_due` 仍是「约 1 秒比对一次 mtime」）。 +//! +//! 为什么不用 `window::frames()` + 1 s 闸门来实现这个低频时钟：帧订阅**本身就是**自持重绘循环 +//! （iced_winit 处理完任何消息都 `request_redraw()`），闸门只能省掉 `advance()` 里的活，省不掉 +//! 整窗重绘——实测软件渲染约 **500 帧/秒**。心跳是「每秒一帧」，差三个数量级。 +//! +//! ## 已知代价（都登记，不藏） +//! +//! 1. **忙碌态仍是自持帧循环**：`Running`/`Busy` 一天不结束，就一天按帧刷（软件渲染实测约 +//! 970 帧/秒，refreshes 不增长 = 纯像素空转）。功能上需要 tick 来发现游戏退出，但「整段 +//! 运行期近千帧/秒重绘」是真实开销；要收口得让 `Running` 走更慢的时钟（follow-up）。 +//! 2. 心跳用 `thread::sleep` 占线程池一个线程 1 秒；1 Hz 下可接受，但不是优雅解法（正解仍是 +//! `iced::time::every` + tokio/smol，Cargo.toml 在 scope 外，已报 finding）。 + +use std::time::Instant; + +use iced::{window, Subscription}; + +use super::message::Message; +use super::state::App; + +impl App { + /// 本次进程的订阅表。 + pub(super) fn subscription(&self) -> Subscription { + let frames = if self.needs_frames() { + window::frames().map(|_| Message::Frame) + } else { + Subscription::none() + }; + + // 断点 600 / 840 要跟着真窗口宽度走；截图模式的窗口尺寸由参数钉死，不吃 resize。 + let events = if self.has_screenshot() { + Subscription::none() + } else { + window::events().map(|(_, event)| Message::Window(event)) + }; + + // 键盘（M104）：`Esc` 收栗 / `Tab` 走焦点环 / `Enter` 激活焦点键。 + // + // 为什么订阅整条键盘流而不是自己挑键：`iced::keyboard::listen()` 是唯一的全窗键盘入口， + // 挑键与「什么状态下该做什么」的解释权放在 `app/update/agent.rs`（一眼看完）， + // 订阅表只负责搬运。截图通道不开它——D30 要可复现，键盘事件一个都不该进图。 + let keys = if self.has_screenshot() { + Subscription::none() + } else { + iced::keyboard::listen() + .map(|event| Message::Agent(crate::shell::agent::Message::Key(event))) + }; + + Subscription::batch([frames, events, keys]) + } + + /// 是否订阅帧事件（= 截图模式要帧数闸门）。 + pub(super) fn wants_frames(&self) -> bool { + self.has_screenshot() + } + + /// 现在要不要**时钟**（见模块文档的表）。 + pub(super) fn needs_frames(&self) -> bool { + self.has_screenshot() + || !self.state.toasts.is_empty() + || !self.state.running().is_empty() + || self + .watch_until + .is_some_and(|deadline| Instant::now() < deadline) + } +} diff --git a/crates/app-iced/src/app/tests.rs b/crates/app-iced/src/app/tests.rs new file mode 100644 index 0000000..ce40508 --- /dev/null +++ b/crates/app-iced/src/app/tests.rs @@ -0,0 +1,382 @@ +//! `app` 的单测：主题切换、窗口尺寸、截图闸门、gallery 能构图，以及**presenter 接线的闭环**。 +//! +//! 闭环测试用的是 `MockBackend`（presenter 自带的假后端）：它走的是与真 host 完全相同的 +//! `dispatch → drain_events → AppState::apply → 视图模型` 通道，所以「点 Play → 状态真的变」 +//! 这件事在这里就能判死，不必等图形环境。 + +use unlucky_design::color::SchemeFlavor; +use unlucky_presenter::mock::MockBackend; +use unlucky_presenter::router::Route; +use unlucky_presenter::settings_bridge::SettingsBridge; + +#[cfg(test)] +mod appearance; +#[cfg(test)] +mod presenter; + +use super::message::Message; +use super::state::App; +use super::{APP_TITLE, WINDOW_SIZE}; +use crate::cli::{Options, Screen}; +use crate::pages; +use crate::shell::agent::RailState; +use crate::shell::NavItem; +use crate::theme::Families; + +const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", +}; + +/// 不碰磁盘的 App（mock 后端 + 内存设置桥）。 +fn headless(options: Options, flavor: SchemeFlavor) -> App { + App::with_presenter( + options, + FAMILIES, + flavor, + Box::new(MockBackend::new()), + SettingsBridge::memory_only(), + ) +} + +fn screenshot_options() -> Options { + Options { + screenshot: Some(std::path::PathBuf::from("x.png")), + ..Options::default() + } +} + +#[test] +fn switching_flavor_rebuilds_styles_but_keeps_ui_state() { + let mut app = headless(Options::default(), SchemeFlavor::Light); + app.state.navigate(Route::Logs); + app.refresh_view(); + assert_eq!(app.ui().name(), "ull-m3-light"); + + app.set_flavor(SchemeFlavor::Dark); + + assert_eq!(app.ui().name(), "ull-m3-dark", "切主题要换主题名"); + assert_eq!(app.state.route(), &Route::Logs, "切主题不许重置 UI 状态"); + assert_eq!(app.view.screen, pages::Screen::Logs, "视图模型跟着路由"); + assert!(app.options.screenshot.is_none(), "切主题不许改启动参数"); +} + +#[test] +fn window_size_is_the_acceptance_size() { + assert_eq!((WINDOW_SIZE.width, WINDOW_SIZE.height), (1180.0, 760.0)); + assert_eq!(APP_TITLE, "Unlucky Launcher"); +} + +#[test] +fn screenshot_mode_never_waits_for_the_system_theme() { + // 门禁依赖：CI 的 runtime-smoke 不带主题，xvfb 里也没有主题会话。 + let options = screenshot_options(); + assert!(!options.wants_system_theme(), "截图模式不许等系统主题"); + assert_eq!(options.capture_flavor(), Some(SchemeFlavor::Light)); + + let app = headless(options, SchemeFlavor::Light); + assert!(app.has_screenshot() && app.ui().name() == "ull-m3-light"); +} + +#[test] +fn gallery_screen_builds_a_tree() { + assert_eq!(Options::default().screen, Screen::Shell, "默认仍是产品骨架"); + let options = Options { + screen: Screen::Gallery, + ..Options::default() + }; + let app = headless(options, SchemeFlavor::Light); + // 真实像素由 `--screen=gallery --screenshot` 出图 + `gallery::probe` 量 + let _ = app.view(); +} + +#[test] +fn frames_are_only_requested_in_screenshot_mode() { + let mut app = headless(Options::default(), SchemeFlavor::Light); + assert!(!app.wants_frames(), "普通运行不订阅帧，避免每帧重绘"); + + app.options.screenshot = Some(std::path::PathBuf::from("x.png")); + assert!( + app.wants_frames(), + "截图模式必须订阅帧事件才能在第 3 帧出图" + ); +} + +// --------------------------------------------------------------- P2-1 按需节拍 + +/// 空闲态**不要每帧节拍**（但要有 1 Hz 心跳）。 +/// +/// 意图与 r2 那条 `an_idle_app_asks_for_no_clock` 一致：空闲时不许按帧循环跑（那会以每秒几百帧 +/// 的速度重绘整窗），改成「低频心跳」。断言拆成两半： +/// +/// 1. `needs_frames()` 为假 ⇒ **不订阅** `window::frames()`； +/// 2. 空闲时钟的周期 = [`IDLE_TICK`] = 1 s，且心跳每拍推进的 tick 预算 = 30（= 1 s / 33 ms）， +/// 这样 `theme::config_poll_due`（30 拍）仍是「约 1 秒比对一次 mtime」。 +/// +/// 抓得住：有人把「无条件订阅帧」改回来（第 1 半红）；有人把心跳周期改快/改慢（第 2 半红）。 +/// 抓不住：真实窗口的重绘次数（那要 `ULL_TICK_TRACE=1` 跑一次交互模式看日志，见报告）。 +#[test] +fn an_idle_app_uses_a_slow_heartbeat_instead_of_frames() { + let app = headless(screenshot_options(), SchemeFlavor::Light); + assert!(app.needs_frames(), "截图通道永远要帧（第 3 帧落盘）"); + + let mut idle = headless(Options::default(), SchemeFlavor::Light); + let _ = idle.update(Message::Boot); + assert!( + idle.needs_frames(), + "Boot 刚派发过 RefreshAll：3 秒观察窗内要节拍（等真 host 的首批事件）" + ); + + // 观察窗过期、也没有忙碌实例 ⇒ 空闲态不订阅帧事件（改走 1 Hz 心跳） + idle.watch_until = None; + assert!(!idle.needs_frames(), "空闲交互态：不订阅帧事件（只有心跳）"); + + // 派发之后观察窗重新打开 + let _ = idle.update(Message::Page(pages::Message::Navigate(Route::Detail( + "survival".to_string(), + )))); + let _ = idle.update(Message::Page(pages::Message::Launch( + "survival".to_string(), + ))); + assert!(idle.needs_frames(), "派发后观察窗内要有节拍"); + + // 进入 Busy 之后由「忙碌实例」这个条件自己续订（不靠观察窗） + idle.watch_until = None; + assert!( + idle.needs_frames(), + "有 Busy 实例时即便观察窗过期也要继续 tick" + ); +} + +/// 心跳的**节奏**：1 Hz，且每拍折算 30 个 33 ms 单位 ⇒ `config_poll_due` ≈ 每秒一次。 +/// +/// 抓得住：心跳周期常量、以及 `advance()` 里「按流逝时间折算 ticks」这条记账（改回 +/// `ticks += 1` 会让空闲态的配置轮询变成 30 秒一次，这条就红）。 +/// 抓不住：`Task::perform` 那条自续链真的每秒触发一次（那是运行期 trace 的事，见报告）。 +#[test] +fn the_idle_heartbeat_budgets_one_config_poll_per_second() { + use unlucky_presenter::theme::config_poll_due; + + assert_eq!( + super::state::IDLE_TICK, + std::time::Duration::from_secs(1), + "空闲心跳周期必须是 1 s" + ); + + let mut app = headless(Options::default(), SchemeFlavor::Light); + let _ = app.update(Message::Boot); + app.watch_until = None; + + // 一次空闲心跳（1 s）之后：ticks 增加 30，且正好落在 config 轮询点上 + let before = app.ticks; + app.advance(super::state::IDLE_TICK); + assert_eq!(app.ticks - before, 30, "1 s 应折算 30 个 33 ms 拍"); + assert!( + config_poll_due(app.ticks), + "空闲心跳每拍都要落在 config 轮询点上（ticks={}）", + app.ticks + ); +} + +/// 空闲态每拍**不再重建视图模型**（P2-1 的另一半：`refresh_view` 的 30 Hz × N 实例白克隆）。 +/// +/// 抓得住：把 `advance()` 里的 `if self.view_dirty` 去掉（改回无条件 `refresh_view()`）时， +/// 这条断言里的 `refreshes` 会从「不增长」变成「每拍 +1」。 +/// 抓不住：「重建一次花了多少微秒」（没有基准测试；量级判断见报告）。 +#[test] +fn idle_ticks_do_not_rebuild_the_view_model() { + let mut app = headless(Options::default(), SchemeFlavor::Light); + let _ = app.update(Message::Boot); + + let before = app.refreshes; + for _ in 0..100 { + app.advance(super::state::TICK); + } + assert_eq!( + app.refreshes, + before, + "空闲 100 拍：视图模型一次都不该重建（实际 +{}）", + app.refreshes - before + ); + + // 有事件进来时仍然要重建（否则页面不刷新） + let _ = app.update(Message::Page(pages::Message::Navigate(Route::Logs))); + assert!(app.refreshes > before, "导航之后必须重建一次"); +} +/// 视图模型跟着窗口宽度走（交互模式下 600 / 840 两条断点靠 resize 事件生效）。 +/// +/// M104 起 `view.window_width` 装的是**中栗可用宽度**（窗口 − 右栗 − 拖拽缝），所以这里按三档 +/// 各钉一个**字面量**：48 的折叠条与 320 的面板各自的减法都得对。 +/// （断言里不调 `agent.content_width(..)`——那是同义反复，实现错一处它照样绿。） +#[test] +fn resizing_the_window_rebuilds_the_view_model() { + let mut app = headless(Options::default(), SchemeFlavor::Light); + let _ = app.update(Message::Boot); + + // 出厂是 Collapsed(48) 档：中栗 = 窗口 − 48 + let _ = app.update(Message::Window(iced::window::Event::Resized( + iced::Size::new(1180.0, 760.0), + ))); + assert!( + (app.view.window_width - 1132.0).abs() < f32::EPSILON, + "1180 − 48（折叠条）= 1132，实际 {}", + app.view.window_width + ); + + let _ = app.update(Message::Window(iced::window::Event::Resized( + iced::Size::new(700.0, 600.0), + ))); + assert!( + (app.view.window_width - 652.0).abs() < f32::EPSILON, + "700 − 48（折叠条）= 652，实际 {}", + app.view.window_width + ); + + // Expanded(320) 档：中栗 = 窗口 − 320（面板）− 8（拖拽缝）= 852 + app.agent.expand(); + app.view_dirty = true; + app.refresh_view(); + assert!( + (app.view.window_width - 652.0).abs() < f32::EPSILON, + "700 上展开档不成立（上限 700 − 88 − 472 − 8 = 132 < 280）⇒ 实际按折叠条 48 算： 700 − 48 = 652，实际 {}", + app.view.window_width + ); + let _ = app.update(Message::Window(iced::window::Event::Resized( + iced::Size::new(1180.0, 760.0), + ))); + assert!( + (app.view.window_width - 852.0).abs() < f32::EPSILON, + "1180 − 320 − 8 = 852，实际 {}", + app.view.window_width + ); + + // Detached 档：右栗不占宽，中栗 = 窗口 = 1180。 + // **必须走路由**（`Select(Ai)`）：r1 之后「档位 = Detached」与「路由 = Agent」是一条不变式， + // 直接 `agent.detach()` 再手工 refresh 会被 `sync_agent_route` 立刻收回右栗（那正是要的语义）。 + let _ = app.update(Message::Select(NavItem::Ai)); + app.view_dirty = true; + app.refresh_view(); + assert!( + (app.view.window_width - 1180.0).abs() < f32::EPSILON, + "拆出后右栗不占宽：1180 − 0 = 1180，实际 {}", + app.view.window_width + ); + // 页面照旧能构图（窄窗退化到单列，不 panic） + let _ = app.view(); +} + +/// **不变式（复审 r1 的 P2-1）**：`Route::Agent` ⟺ `RailState::Detached`。 +/// +/// 走的是**真实路由入口**（外壳导航第五项 `Assistant` → `Message::Select(NavItem::Ai)`），不是 +/// 直接调 `agent.detach()`：r1 复现的 bug 正是「导航进页面时档位没变」，只测 `detach()` 抓不到它。 +/// +/// 抓得住：①进独立页后档位 = Detached（页头才会是 `Dock back` 而不是 `Open assistant`/`Pop out`）； +/// ②未读在进页时清零；③`Esc` 在独立页真的离开（不是只把档位改成折叠）；④从页上点别的导航， +/// 会话收回右栗（档位不再停在 Detached）。 +/// 抓不住：按钮在像素上长什么样（那要出图，见 `13/14` 两张）。 +#[test] +fn entering_the_agent_route_detaches_the_rail() { + let mut app = headless(Options::default(), SchemeFlavor::Light); + let _ = app.update(Message::Boot); + assert_eq!(app.agent.rail, RailState::Collapsed, "出厂是折叠档"); + // M119：出厂没有样本会话，未读由 presenter 按真事件累加 ⇒ 出厂就是 0 + assert_eq!(app.agent_host.rail().unread, 0, "出厂 0 条未读"); + + // ① 外壳导航第五项（真实入口） + let _ = app.update(Message::Select(NavItem::Ai)); + assert_eq!(app.state.route(), &Route::Agent); + assert_eq!( + app.agent.rail, + RailState::Detached, + "进了独立页，档位必须是 Detached——否则页头会画右栗才有的动作" + ); + assert_eq!(app.agent_host.rail().unread, 0, "进独立页即读"); + + // ③ Esc 真的离开这一页 + let _ = app.update(Message::Agent(crate::shell::agent::Message::Escape)); + assert_ne!(app.state.route(), &Route::Agent, "独立页上 Esc 必须离开"); + assert_eq!(app.agent.rail, RailState::Expanded, "收回到右栗展开档"); + + // ④ 从独立页点别的导航：会话收回右栗（档位不能停在 Detached） + let _ = app.update(Message::Select(NavItem::Ai)); + assert_eq!(app.agent.rail, RailState::Detached); + let _ = app.update(Message::Select(NavItem::Instances)); + assert_eq!(app.state.route(), &Route::Instances); + assert_eq!( + app.agent.rail, + RailState::Expanded, + "离开独立页 ⇒ 会话收回右栗（否则页走了、栏还是 0 宽）" + ); +} + +/// 同一条不变式的另一个入口：页面层的 `Navigate(Route::Agent)`（右栗里的 `pages::Message` 路径）。 +#[test] +fn the_page_navigation_entry_also_detaches() { + let mut app = headless(Options::default(), SchemeFlavor::Light); + let _ = app.update(Message::Boot); + // 走真消息（不是直接改字段）：这样「展开即读」的 `agent_mark_read` 也会真的发生 + let _ = app.update(Message::Agent(crate::shell::agent::Message::Expand)); + assert_eq!(app.agent.rail, RailState::Expanded); + + let _ = app.update(Message::Page(pages::Message::Navigate(Route::Agent))); + assert_eq!(app.state.route(), &Route::Agent); + assert_eq!(app.agent.rail, RailState::Detached); + assert_eq!(app.agent_host.rail().unread, 0); + + // 页面层回退（不是 Dock 消息）也要把档位收回来 + let _ = app.update(Message::Page(pages::Message::Navigate(Route::Instances))); + assert_eq!(app.agent.rail, RailState::Expanded); +} + +/// 截图模式不读设置文件里的主题（D30 可复现：两台机器出同一张图）。 +#[test] +fn screenshot_mode_ignores_the_settings_file_theme() { + let mut app = headless(screenshot_options(), SchemeFlavor::Light); + app.apply_config_theme(); + assert_eq!(app.ui().name(), "ull-m3-light", "截图模式的主题只认命令行"); +} + +/// 主题优先级：`--theme` > 配置文件 `appearance.theme_mode` > 系统主题。 +/// +/// r2 之前 `Message::SystemTheme` 无条件 `set_flavor`，于是「配置文件写 dark、系统是浅色」会 +/// 出现 `light -> dark -> light` 的一次抖动、配置永远不生效（r3 做 P2-2 的配置热切实测时暴露 +/// 出来，一并修）。 +/// +/// 抓得住：系统主题不许盖掉显式配置/命令行给出的主题（三条分支各一条断言）。 +/// 抓不住：真实桌面切换系统主题时的事件时序（只有消息级验证）。 +#[test] +fn the_system_theme_never_overrides_an_explicit_one() { + use unlucky_presenter::prefs::ThemeMode; + + // ① auto（内存桥默认）：系统主题说了算 + let mut auto = headless(Options::default(), SchemeFlavor::Light); + assert_eq!(auto.theme_mode, ThemeMode::Auto); + let _ = auto.update(Message::SystemTheme(iced::theme::Mode::Dark)); + assert_eq!(auto.ui().name(), "ull-m3-dark", "auto 模式要跟随系统"); + + // ② 配置文件显式 dark：系统给浅色也不许改 + let mut pinned = headless(Options::default(), SchemeFlavor::Dark); + pinned.theme_mode = ThemeMode::Dark; + let _ = pinned.update(Message::SystemTheme(iced::theme::Mode::Light)); + assert_eq!( + pinned.ui().name(), + "ull-m3-dark", + "配置文件说 dark，系统说 light：不许改" + ); + + // ③ 命令行 `--theme` 优先级最高 + let mut explicit = headless( + Options { + theme: Some(SchemeFlavor::Dark), + ..Options::default() + }, + SchemeFlavor::Dark, + ); + let _ = explicit.update(Message::SystemTheme(iced::theme::Mode::Light)); + assert_eq!( + explicit.ui().name(), + "ull-m3-dark", + "--theme 优先级最高，系统主题不许盖" + ); +} diff --git a/crates/app-iced/src/app/tests/appearance.rs b/crates/app-iced/src/app/tests/appearance.rs new file mode 100644 index 0000000..cde13d8 --- /dev/null +++ b/crates/app-iced/src/app/tests/appearance.rs @@ -0,0 +1,331 @@ +//! 外观接线的单测：**配置 → 状态 → 下发字节 / 像素 / 落盘**。 +//! +//! 每条都按本 mission 的验收纪律写「抓得住 / 抓不住」。真机才有的东西（`WS_EX_LAYERED` 是否补上、 +//! `LWA_ALPHA` 的观感）不在这里假装——那是 `[appearance]` 日志与报告里「没验的部分」的事。 + +use std::path::PathBuf; + +use unlucky_design::color::SchemeFlavor; +use unlucky_presenter::mock::MockBackend; +use unlucky_presenter::prefs::{BgFill, PaletteSource}; +use unlucky_presenter::settings_bridge::SettingsBridge; + +use crate::cli::{Backend, Options}; +use crate::pages::appearance::{self, Change, State}; +use crate::pages::{self, Screen}; + +use super::{headless, FAMILIES}; + +use super::super::state::App; + +/// 一个把配置写在临时文件里的 App（测「读回 / 写回」必须真的过文件）。 +fn with_config(json: &str, backend: Backend, label: &str) -> (App, PathBuf) { + let dir = std::env::temp_dir().join(format!( + "ull-appear-{label}-{}-{}", + std::process::id(), + line!() + )); + std::fs::create_dir_all(dir.join("config")).expect("临时目录"); + let path = dir.join("config/launcher.json"); + std::fs::write(&path, json).expect("写配置文件"); + + let app = App::with_presenter( + Options { + backend, + ..Options::default() + }, + FAMILIES, + SchemeFlavor::Light, + Box::new(MockBackend::new()), + SettingsBridge::with_path(&path), + ); + (app, dir) +} + +fn cleanup(dir: &PathBuf) { + std::fs::remove_dir_all(dir).ok(); +} + +/// 抓得住：配置里写 `window_opacity=0.8` → 启动读回 0.8 → 下发字节 205（钳位链的入口那一段）。 +/// 抓不住：Win32 是否真的收下 204（`transparency` 的单测与本机日志各自举证）。 +#[test] +fn the_configured_window_alpha_is_read_back_and_turned_into_a_byte() { + let (app, dir) = with_config( + r#"{"appearance":{"window_opacity":0.8,"palette_source":"preset"}}"#, + Backend::Cpu, + "read", + ); + + assert_eq!(app.appearance.window_opacity, 0.8); + assert_eq!( + app.appearance.window_alpha_byte(), + Some(205), + "f32 0.8 → f64 略大于 0.8 → ceil 205（不向下取整）" + ); + // CPU 档：窗口 α 允许，面板 α 强制 1.0。 + assert_eq!(app.appearance.effective_panel_alpha(), 1.0); + assert!(app.appearance.panel_is_forced()); + cleanup(&dir); +} + +/// 抓得住：①面板 α 滑到 0.8 → 状态是 0.8、生效值 GPU 档也是 0.8； +/// ②CPU 档下滑到 0.5 → 生效值仍是 1.0，而**请求值**仍是 0.5（界面上的「requested → forced」靠这条）。 +/// 抓不住：这层半透明在屏幕上到底多透（RDP 上不可信，见报告）。 +#[test] +fn panel_alpha_is_independent_of_the_window_alpha_and_forced_on_cpu() { + let mut gpu = headless(Options::default(), SchemeFlavor::Light); + gpu.appearance.apply(Change::PanelAlpha(0.8)); + assert_eq!(gpu.appearance.panel_alpha, 0.8); + assert_eq!(gpu.appearance.effective_panel_alpha(), 0.8); + assert_eq!(gpu.appearance.window_opacity, 1.0, "面板 α 不许带动整窗 α"); + + let mut cpu = headless( + Options { + backend: Backend::Cpu, + ..Options::default() + }, + SchemeFlavor::Light, + ); + assert!( + !cpu.appearance.apply(Change::PanelAlpha(0.5)), + "只有整窗 α 需要立刻下发（面板 α 只重绘）" + ); + assert_eq!(cpu.appearance.panel_alpha, 0.5, "请求值保留"); + assert_eq!( + cpu.appearance.effective_panel_alpha(), + 1.0, + "CPU 档强制 1.0" + ); + assert_eq!(cpu.appearance.window_alpha_byte(), None, "整窗 α 仍是 1.0"); +} + +/// 抓得住：一次滑块改动 → 落盘 → **新开一个 bridge** 能读回（= 重启后还在）。 +/// 抓不住：真 host 是否也写了同一份文件（`AppCommand::SetSetting` 走的是同一份 schema）。 +#[test] +fn a_panel_alpha_change_is_written_back_to_the_config_file() { + let (mut app, dir) = with_config("{}", Backend::Gpu, "write"); + app.on_appearance(Change::PanelAlpha(0.8)); + app.on_appearance(Change::BgFill(BgFill::Tile)); + app.on_appearance(Change::BgDim(0.5)); + + let path = dir.join("config/launcher.json"); + let reopened = SettingsBridge::with_path(&path).load().0; + assert_eq!(reopened.panel_alpha, 0.8); + assert_eq!(reopened.bg_fill, BgFill::Tile); + assert!((reopened.bg_dim - 0.5).abs() < 1e-6); + assert_eq!( + app.appearance_prefs.panel_alpha, 0.8, + "内存里的「已落盘快照」也要跟上，否则下一次写回会拿旧基底覆盖" + ); + cleanup(&dir); +} + +/// 抓得住：路径读不出来时 ①不 panic ②`background_active()` 为假（静默回落） +/// ③诊断里有一句人话（不是空串）④配色回落到色卡档（不换 scheme）。 +/// 抓不住：这张图在别的机器上路径存在时会怎样（那是成功路径，另一条测试管）。 +#[test] +fn a_broken_background_path_falls_back_silently_but_says_why() { + let mut app = headless(Options::default(), SchemeFlavor::Light); + app.appearance + .apply(Change::BgImage("D:/definitely/not/here.png".to_owned())); + + assert!(!app.appearance.background_active()); + assert!(app.appearance.image().is_none(), "解码失败 ⇒ 没有可用图"); + assert_eq!(app.appearance.diagnostics().len(), 1, "恰好一条诊断"); + assert!( + app.appearance.diagnostics()[0].contains("could not be read"), + "诊断要是人话：{:?}", + app.appearance.diagnostics() + ); + assert_eq!(app.appearance.palette_level(), "preset", "回落色卡"); + assert!( + app.appearance.derived_scheme().is_none(), + "色卡档不换 scheme" + ); +} + +/// 抓得住：真 PNG → 背景真的生效（解出原图尺寸、路径留给渲染器、配色走「背景图取色」这一级）。 +/// 抓不住：渲染出来的像素（由截图举证），以及三种填充的覆盖范围（由 `background::tiles` 的 +/// 「覆盖 ≥ 视口」断言守）。 +#[test] +fn a_decodable_png_makes_the_background_and_the_palette_active() { + let dir = std::env::temp_dir().join(format!("ull-appear-png-{}", std::process::id())); + std::fs::create_dir_all(&dir).expect("临时目录"); + let path = dir.join("bg.png"); + let image = image::RgbImage::from_fn(64, 32, |x, _y| { + if x < 32 { + image::Rgb([200, 30, 30]) + } else { + image::Rgb([20, 60, 200]) + } + }); + image.save(&path).expect("写 png"); + + let mut app = headless(Options::default(), SchemeFlavor::Light); + app.appearance + .apply(Change::PaletteSource(PaletteSource::BackgroundImage)); + app.appearance + .apply(Change::BgImage(path.to_string_lossy().to_string())); + app.rebuild_ui(); + + assert!(app.appearance.background_active()); + assert!(app.appearance.image().is_some(), "解码成功 ⇒ 有可用图"); + assert!( + !app.appearance.bg_path.trim().is_empty(), + "渲染器按路径解码（见 picture::image_handle）" + ); + assert_eq!(app.appearance.diagnostics().len(), 0, "成功时没有诊断"); + assert_eq!(app.appearance.palette_level(), "background-image"); + assert!( + app.appearance.derived_scheme().is_some(), + "取色成功后 Ui 要换成解析出的方案" + ); + // 换 scheme 之后主题名仍是同一个（深浅没变），但 primary 必须与 baseline 不同。 + assert_eq!(app.ui().name(), "ull-m3-light"); + let baseline = crate::theme::Ui::new(SchemeFlavor::Light, FAMILIES); + assert_ne!( + app.ui().color(unlucky_design::color::Role::Primary), + baseline.color(unlucky_design::color::Role::Primary) + ); + std::fs::remove_dir_all(&dir).ok(); +} + +/// 抓得住：设置页在有外观状态时能真的构图（真控件树，含文本框/滑块/互斥按钮），并且 +/// 「外观」分组的下标与 `appearance::APPEARANCE_GROUP` 一致（点左列能切过去）。 +/// 抓不住：这些控件点下去之后的交互（`Message` 的落点由 `on_appearance` 的其它测试管）。 +#[test] +fn the_settings_page_renders_the_real_appearance_group() { + let mut app = headless(Options::default(), SchemeFlavor::Light); + app.state + .navigate(unlucky_presenter::router::Route::Settings); + app.refresh_view(); + assert_eq!(app.view.screen, Screen::Settings); + assert_eq!(app.appearance.selected_group, appearance::APPEARANCE_GROUP); + + let _tree = pages::page_with_appearance(&app.ui, &app.view, &app.appearance); + drop(_tree); + + // 切分组：只改视图状态，不落盘（`Change::SelectGroup` 的 key() == None）。 + app.appearance.apply(Change::SelectGroup(0)); + assert_eq!(app.appearance.selected_group, 0); + let _tree = pages::page_with_appearance(&app.ui, &app.view, &app.appearance); +} + +/// **P2-2 的守门（复审 r1）**：面板 α 只作用到允许半透明的层。 +/// +/// 抓得住：`Ui::layer(Canvas)` 在 α=0.55 时仍是不透明（标题栏/导航轨/页头带都取 Canvas， +/// 它们一旦透底，三个窗口键与导航文字就压在背景照片上）；`Card` / `Overlay` 必须真的吃到 α。 +/// 抓不住：真实合成后的观感（那由截图看）。 +#[test] +fn the_canvas_layer_stays_opaque_while_panels_take_the_alpha() { + use unlucky_design::elevation::MaterialLayer; + + let mut app = headless(Options::default(), SchemeFlavor::Light); + app.appearance.apply(Change::PanelAlpha(0.55)); + app.rebuild_ui(); + + let ui = app.ui(); + assert_eq!(ui.panel_alpha(), 0.55, "生效值进了 Ui"); + assert_eq!( + ui.layer(MaterialLayer::Canvas).a, + 1.0, + "窗口底（标题栏/导航轨/页头带）永远不透明——令牌的不变量" + ); + for layer in [MaterialLayer::Card, MaterialLayer::Overlay] { + assert!( + (ui.layer(layer).a - 0.55).abs() < 1e-6, + "{layer:?} 必须吃面板 α（实际 {}）", + ui.layer(layer).a + ); + } + + // CPU 档：α 被强制 1.0 ⇒ 连卡片也不透明。 + let mut cpu = headless( + Options { + backend: Backend::Cpu, + ..Options::default() + }, + SchemeFlavor::Light, + ); + cpu.appearance.apply(Change::PanelAlpha(0.55)); + cpu.rebuild_ui(); + assert_eq!(cpu.ui().layer(MaterialLayer::Card).a, 1.0, "CPU 档强制 1.0"); +} + +/// 抓得住：**把滑块从头拖到尾**（0.00 → 1.00 的 11 个档）时，状态里的整窗 α 与下发字节逐档单调 +/// 上升、且最低一档就是下限字节 21（= 0.0824 ≥ 0.08）、最后一档不透明（不给字节）。 +/// 这就是「拖动 → 实际 α」的链条在数值上的等价物；真机拖动的那一次由二进制日志举证。 +/// 抓不住：拖动的手感与真实观感（RDP 上不可信）。 +#[test] +fn a_slider_sweep_moves_the_alpha_and_the_byte_monotonically() { + let mut app = headless(Options::default(), SchemeFlavor::Light); + let mut bytes = Vec::new(); + for step in 0..=10 { + let fraction = step as f32 / 10.0; + let alpha = crate::pages::appearance::alpha::window_alpha_from_fraction(fraction); + app.appearance.apply(Change::WindowOpacity(alpha)); + let byte = app.appearance.window_alpha_byte(); + bytes.push(byte); + // 每一档都要能打出一行（数值而不是观感）。 + assert!(app.appearance.log_line("sweep").contains("window_alpha=")); + } + + assert_eq!(bytes[0], Some(21), "0% 一档 = 下限 0.08 → 21"); + assert_eq!(bytes[10], None, "100% 一档 = 不透明 → 不下发"); + let sent: Vec = bytes.iter().flatten().copied().collect(); + assert!( + sent.windows(2).all(|pair| pair[0] <= pair[1]), + "字节必须单调不减：{sent:?}" + ); + assert_eq!(sent.len(), 10, "除最后一档（不透明）之外每档都有字节"); + assert!( + sent.iter().all(|byte| *byte >= 21), + "任何一档都不许低于下限字节：{sent:?}" + ); +} + +/// 抓得住：日志行里有请求值、生效值与下发字节（RDP 上唯一可信的证据形态）。 +/// 抓不住：这行日志是否真的被写进了 stderr（本测试只钉格式，真机日志由跑起来的二进制举证）。 +#[test] +fn the_log_line_carries_requests_effective_values_and_the_byte() { + let mut cpu = headless( + Options { + backend: Backend::Cpu, + ..Options::default() + }, + SchemeFlavor::Light, + ); + cpu.appearance.apply(Change::WindowOpacity(0.5)); + cpu.appearance.apply(Change::PanelAlpha(0.4)); + + let line = cpu.appearance.log_line("change"); + assert!(line.starts_with("[appearance] change "), "{line}"); + assert!(line.contains("window_alpha=0.500"), "{line}"); + assert!(line.contains("panel_alpha=1.000"), "CPU 档生效值：{line}"); + assert!(line.contains("(requested 0.400)"), "请求值也要在：{line}"); + assert!( + line.contains("byte=128"), + "0.5×255=127.5 → 向上取整 128：{line}" + ); + + // 不透明时不给字节（而不是给 255）。 + let opaque = headless(Options::default(), SchemeFlavor::Light); + assert!(opaque.appearance.log_line("boot").contains("byte=none")); +} + +/// 抓得住：`State::new` 与 `apply_env` 之外，`State` 的构造不会偷偷读环境（测试之间不串味）。 +/// 抓不住：`ULL_APPEARANCE_*` 在真机上的解析（`apply_env` 由截图矩阵覆盖，见报告）。 +#[test] +fn a_fresh_state_is_the_factory_appearance() { + let state = State::new( + &unlucky_presenter::prefs::AppearancePrefs::factory(), + &unlucky_presenter::prefs::AppearanceBase::factory(), + Backend::Gpu, + SchemeFlavor::Light, + ); + assert_eq!(state.window_opacity, 1.0); + assert_eq!(state.effective_panel_alpha(), 1.0); + assert!(!state.background_active()); + assert!(state.diagnostics().is_empty()); + assert!(state.image().is_none()); +} diff --git a/crates/app-iced/src/app/tests/presenter.rs b/crates/app-iced/src/app/tests/presenter.rs new file mode 100644 index 0000000..f6b5abe --- /dev/null +++ b/crates/app-iced/src/app/tests/presenter.rs @@ -0,0 +1,246 @@ +//! presenter 闭环与节拍的断言（M90 r2 从 `app/tests.rs` 外置：那边 416 行会被 file-size 判红）。 +//! +//! 这里的每条都依赖一个可注入的 `Backend`： +//! - `MockBackend`（presenter 自带）验「命令 → 事件 → 状态」的闭环； +//! - `RecorderBackend`（本文件，只记账不回事件）验「UI 侧不做乐观回显」——用 MockBackend 验这条 +//! 会得到**假绿**，因为它是同步发事件的，本地回显与事件回流终态相同（P3-2 的教训）。 + +use std::cell::RefCell; +use std::rc::Rc; + +use unlucky_i18n::Key; +use unlucky_presenter::dto::{AppCommand, AppEvent, Backend, CoreEvent}; +use unlucky_presenter::mock_data::mock_instances; + +use super::*; + +// --------------------------------------------------------------- presenter 闭环 + +/// **首屏快照在 Boot 就到位**（截图在第 3 帧落盘，等 30 fps 的 tick 会拍进空页面）。 +#[test] +fn boot_drains_the_first_snapshot_before_the_first_frame() { + let mut app = headless(screenshot_options(), SchemeFlavor::Light); + assert!(app.view.instances.rows.is_empty(), "还没 Boot"); + + let _ = app.update(Message::Boot); + + assert_eq!( + app.view.instances.rows.len(), + 4, + "mock 的四个实例已进视图模型" + ); + assert_eq!(app.view.screen, pages::Screen::Instances); +} + +/// 首屏自动选中第一行（右栏不该开局空白），且**只做一次**：返回列表后再刷新不弹回详情。 +#[test] +fn the_first_snapshot_selects_the_first_instance_once() { + let mut app = headless(screenshot_options(), SchemeFlavor::Light); + let _ = app.update(Message::Boot); + assert_eq!( + app.state.route(), + &Route::Detail("survival".to_string()), + "首屏快照到位后自动选中第一行" + ); + + let _ = app.update(Message::Page(pages::Message::Navigate(Route::Instances))); + assert_eq!(app.state.route(), &Route::Instances); + + // 再推进一拍（会 drain_events + auto_select）：不该把他弹回详情页 + app.advance(super::super::state::TICK); + assert_eq!(app.state.route(), &Route::Instances, "自动选中只做一次"); +} + +/// 只记账、**不回任何事件**的后端（P3-2）。 +/// +/// 为什么需要它：`MockBackend::dispatch` 是**同步**发事件的，于是「UI 本地回显」与「事件回流」 +/// 在 dispatch 之后终态相同——拿 MockBackend 测「不乐观回显」是假绿（r1 就是栽在这条上）。 +/// 这个后端把两件事分开：命令只进 `dispatched`，`drain_events` 永远空 ⇒ 状态**不可能**变； +/// 一旦有人在 `update` 里偷偷改本地状态，下面那条断言立刻红（实测见报告「P3-2 取证」）。 +#[derive(Debug, Default)] +struct RecorderBackend { + dispatched: Rc>>, + 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/update.rs b/crates/app-iced/src/app/update.rs new file mode 100644 index 0000000..c81e4b5 --- /dev/null +++ b/crates/app-iced/src/app/update.rs @@ -0,0 +1,288 @@ +//! `update`：消息分支的**唯一**落点（含「用户动作 → 后端指令」的派发与事件回流）。 +//! +//! ## 数据流的三个入口（presenter crate 文档 §2） +//! +//! ```text +//! 用户动作 ──dispatch(AppCommand)──► backend ──► drain_events() ──► AppState::apply ──► 视图模型 +//! ▲ ▲ +//! └── pages::Message（导航/启动/停止）──────────────────┘ 忙碌 33 ms / 空闲 1 Hz +//! ``` +//! +//! 三条纪律： +//! +//! 1. **不做乐观回显**：点了「Play」不改本地状态，等 `InstanceRuntimeChanged` 事件回来才变 +//! （否则事件与本地状态打架时，磁贴与进度条会各说一套）； +//! 2. **状态只有一个写入口**：`AppState::apply`（事件）与 `AppState::navigate`（路由）； +//! 3. **只在状态变了才重建视图模型**：`refresh_view()` 是快照 → 页面的唯一转换点， +//! 由 `view_dirty` 门控（M90 r2/P2-1 起；此前是每拍无条件重建）。 +//! +//! ## 两个时钟（M90 r3 / P2-2） +//! +//! | 场景 | 时钟 | 周期 | 谁触发 | +//! |---|---|---|---| +//! | 截图 / 有 Busy-Running 实例 / 有 toast / 派发后 3 s 观察窗 | `window::frames()` + 闸门 | 33 ms | [`App::needs_frames`] | +//! | 其余（空闲） | `Heartbeat` 自续链 | 1 s | [`App::heartbeat`] | +//! +//! 两条时钟不会同时干活：心跳在 `needs_frames()` 为真时**只续排、不推进**，忙碌结束自动接回。 + +use std::time::Instant; + +use iced::{window, Task}; + +use unlucky_design::color::SchemeFlavor; +use unlucky_presenter::dto::AppCommand; +use unlucky_presenter::prefs::ThemeMode; +use unlucky_presenter::router::Route; + +use crate::pages; +use crate::renderer::Kind; + +use super::message::{route_of, Message}; +use super::state::{App, IDLE_TICK, TICK, WATCH_WINDOW}; +use super::CAPTURE_AT_FRAME; + +mod account; +mod agent; +mod appearance; +mod boot_env; +mod clock; +mod content; +mod download; +mod page_messages; +mod settings; + +impl App { + /// 一条消息进来，改状态并返回后续任务。 + pub(super) fn update(&mut self, message: Message) -> Task { + match message { + Message::Boot => self.on_boot(), + Message::WindowReady(id) => { + self.window = id; + // M93：整窗 α 要 Win32 句柄，而 iced 只给 `window::Id`。`window::run` 是唯一能把 + // `&dyn Window`（实现了 `HasWindowHandle`）拿出来的入口。 + match id { + Some(id) => { + window::run(id, super::window_alpha::probe_hwnd).map(Message::WindowHandle) + } + None => Task::none(), + } + } + Message::WindowHandle(hwnd) => { + self.hwnd = hwnd; + match hwnd { + Some(_) => self.apply_window_alpha("boot"), + None => { + eprintln!("[appearance] hwnd=none（拿不到窗口句柄：整窗 α 无法下发）"); + self.log_appearance("boot", None); + } + } + // M116：圆角放在 α **之后**——α < 1 时那一步才补上 `WS_EX_LAYERED`， + // 先打圆角日志会把 `layered=` 记成 `off`（那正是我们要分辨的那一位）。 + self.apply_window_corner("boot"); + Task::none() + } + Message::SystemTheme(mode) => { + let flavor = match mode { + iced::theme::Mode::Dark => SchemeFlavor::Dark, + iced::theme::Mode::None | iced::theme::Mode::Light => SchemeFlavor::Light, + }; + eprintln!("[theme] 系统主题 = {mode:?}"); + // 优先级：`--theme` > 配置文件里的 `appearance.theme_mode` > 系统。 + // 早先这里无条件盖掉，于是「配置文件写 dark、系统是浅色」会出现 + // `light -> dark -> light` 的一次抖动，配置永远不生效（M90 r3 顺手修）。 + if self.options.theme.is_none() && self.theme_mode == ThemeMode::Auto { + self.set_flavor(flavor); + } + Task::none() + } + Message::Frame => self.on_frame(), + Message::Heartbeat => self.on_heartbeat(), + Message::Window(event) => { + match event { + window::Event::Resized(size) => { + self.width = size.width; + // 高度是背景平铺网格的视口判据之一（宽度早就有），以前只记宽是因为没有背景层。 + self.height = size.height; + self.view_dirty = true; + self.refresh_view(); + } + // M113: import/export —— 拖入整合包（本版唯一的选文件通道；窗口级事件， + // 所以入口收起时也照样接得住。细节在 `on_pack_dropped` / `on_pack_hover`） + window::Event::FileDropped(path) => return self.on_pack_dropped(path), + window::Event::FileHovered(_) => return self.on_pack_hover(true), + window::Event::FilesHoveredLeft => return self.on_pack_hover(false), + _ => {} + } + Task::none() + } + Message::Page(message) => self.on_page(message), + Message::Agent(message) => self.on_agent(message), + // 外壳导航轨（`src/shell/nav.rs`）发来的点选：翻成同一次路由跳转 + Message::Select(nav) => { + self.state.navigate(route_of(nav)); + self.view_dirty = true; + self.refresh_view(); + Task::none() + } + Message::DragWindow => match self.window { + Some(id) => window::drag(id), + None => Task::none(), + }, + Message::ResizeStart(direction) => match self.window { + Some(id) => window::drag_resize(id, direction), + None => Task::none(), + }, + Message::Minimize => match self.window { + Some(id) => window::minimize(id, true), + None => Task::none(), + }, + Message::ToggleMaximize => match self.window { + Some(id) => window::toggle_maximize(id), + None => Task::none(), + }, + Message::Close => iced::exit(), + Message::Captured(screenshot) => self.on_captured(&screenshot), + Message::Demo(message) => { + // gallery 只是 harness：按下只打日志，不接业务（组件库要能脱离业务验收） + eprintln!("[gallery] {} pressed", message.id()); + Task::none() + } + } + } + + /// 启动：问窗口句柄 → 让后端发布首屏快照 → 决定主题。 + /// + /// **首屏快照在 `Boot` 就抽干**（不是等第一拍）：截图通道在第 3 帧落盘，33 ms 的节拍 + /// 未必来得及到达，等节拍会把空页面拍进图里。 + fn on_boot(&mut self) -> Task { + let mut tasks = vec![window::latest().map(Message::WindowReady)]; + + // M117：启动日志一行 —— `[auth] msa client_id=configured|missing source=env|build|none`。 + // 判据（配没配 + 从哪来）在 `core::auth::microsoft::client_id_status()`，零网络； + // 本 crate 不直接依赖 core，所以经 `unlucky_cli`（已是本 crate 的依赖）出面， + // 免得 UI 侧把判据重算一遍、两份口径漂。日后看日志能一眼分辨 + // 「没配置」与「配了但登录失败」。 + eprintln!("{}", unlucky_cli::commands::msa_client_id_log_line()); + + // 主题优先级：显式 `--theme` / `--screenshot-theme` > 设置文件 > 系统。 + // 截图通道**不读设置文件**（D30 可复现：同一份代码在两台机器上要出同一张图）。 + self.apply_config_theme(); + + // M93 外观取证开关（`ULL_APPEARANCE_*`）+ 启动那一行数值日志。 + // 必须在 `refresh_view` 之前：设置页要画的就是这份状态。 + self.appearance.apply_env(); + self.rebuild_ui(); + self.log_appearance("boot", None); + + // 交互模式且没显式指定主题 → 探系统；截图模式永不等（见 cli 模块文档） + if self.options.wants_system_theme() { + tasks.push(iced::system::theme().map(Message::SystemTheme)); + } + + // M104：助手栏的启动尾巴（窗口尺寸 adopt + 「拆出档直接落到独立页」）在 update/agent.rs。 + // **必须在 RefreshAll 之前**：那次 dispatch 会 `pump → auto_select`，把路由拉到实例详情， + // 而 `sync_agent_route` 看到「不在 Agent 页却还是 Detached」就会把档位收回来——顺序反了 + // 就会出现「`ULL_AGENT_RAIL=detached` 启动后停在实例页」（r2 实测踩到）。 + self.boot_agent(); + + // 「重新扫描实例目录 + 全部页面快照」：真 host 在这里发首批事件，mock 在构造时已预置 + self.dispatch(AppCommand::RefreshAll); + + // 取证开关 `ULL_START_ROUTE`：截图/冒烟直接落到某一页（`cli.rs` 不在本 mission 的 scope， + // 而「外观」分组只在设置页上，出矩阵必须能直达）。未知值忽略。 + if let Some(route) = boot_env::env_start_route() { + eprintln!("[boot] ULL_START_ROUTE → {route:?}"); + self.state.navigate(route); + // 直达某一页时不要再被「自动选中第一条实例」拉回详情页。 + self.auto_selected = true; + // M109：直达内容库时补一次检索（与页面内切换同一个入口） + self.ensure_content_loaded(); + } + account::force_account_state(self); + + self.auto_select(); + self.view_dirty = true; + self.refresh_view(); + + // 空闲心跳从这里开始自续（它是唯一能在「没有帧事件」时戳醒 app 的时钟） + tasks.push(heartbeat()); + + Task::batch(tasks) + } + + /// 空闲心跳：只有「不需要帧节拍」时才推进一拍，然后**无条件续排**下一拍。 + /// + /// 为什么无条件续排：忙碌结束（游戏退出、toast 过期、观察窗关闭）之后没有别的东西会叫醒 + /// app，心跳链必须一直在，才能把低频时钟接回去。忙碌期间它只是每秒醒一次、什么都不做。 + fn on_heartbeat(&mut self) -> Task { + if !self.needs_frames() { + let now = Instant::now(); + let elapsed = now.saturating_duration_since(self.last_tick).max(IDLE_TICK); + self.last_tick = now; + self.advance(elapsed); + } + heartbeat() + } + + /// 一帧画完：①够 33 ms 就推进一拍 presenter ②截图模式在第 [`CAPTURE_AT_FRAME`] 帧出图。 + /// + /// 时间闸门按**真实流逝时间**判（不是数帧）：掉帧不会把游戏启动进度拖慢， + /// 也不会在慢机器上把 1.5 s 的下载阶段拉成 4 s。 + fn on_frame(&mut self) -> Task { + self.frames += 1; + + let now = Instant::now(); + let elapsed = now.saturating_duration_since(self.last_tick); + if elapsed >= TICK { + self.last_tick = now; + self.advance(elapsed); + } + + // 主题在启动时就已确定（截图模式必有主题，见 cli 模块文档），这里只剩帧数闸门 + if !self.wants_frames() || self.frames < CAPTURE_AT_FRAME { + return Task::none(); + } + + match self.window { + Some(id) => window::screenshot(id).map(Message::Captured), + None => Task::none(), + } + } + + /// 截图回来了：落盘 + 打一行取证日志，然后退出。 + fn on_captured(&mut self, screenshot: &window::Screenshot) -> Task { + let Some(path) = self.options.screenshot.clone() else { + return Task::none(); + }; + match crate::shot::save(screenshot, &path) { + Ok(summary) => { + eprintln!("{}", summary.describe()); + // M97：打**实际**后端名（`wgpu`/`tiny-skia`），不是请求值——`renderer=auto` 曾经出现在每张验收图的日志里。 + eprintln!( + "[shot] screen={} theme={} renderer={} route={:?}", + self.options.screen.name(), + crate::shot::flavor_slug(&self.ui), + super::backend::effective_kind().map_or("?", Kind::name), + self.state.route() + ); + } + Err(error) => eprintln!("[shot] 失败：{error}"), + } + + iced::exit() + } +} + +/// 空闲心跳的一拍：睡 1 秒再发 [`Message::Heartbeat`]。 +/// +/// 用 `Task::perform` + `std::thread::sleep` 而不是 `iced::time::every`：后者只在 tokio/smol +/// 后端提供（本 crate 的执行器是 thread-pool，Cargo.toml 不在 scope）。代价是每拍让线程池里 +/// 一个线程阻塞 1 秒——按 1 Hz 算，对线程池（默认 = CPU 数）是可接受的占用。 +fn heartbeat() -> Task { + Task::perform(async { std::thread::sleep(IDLE_TICK) }, |()| { + Message::Heartbeat + }) +} + +#[cfg(test)] +mod download_wiring; diff --git a/crates/app-iced/src/app/update/account.rs b/crates/app-iced/src/app/update/account.rs new file mode 100644 index 0000000..c2a8467 --- /dev/null +++ b/crates/app-iced/src/app/update/account.rs @@ -0,0 +1,210 @@ +//! 账户页消息的落点（M114）：页面只发意图，这里翻成 `AppCommand` 或本地的表单状态写入。 +//! +//! 三条纪律（与 `update.rs` 同源）： +//! +//! 1. **不做乐观回显**：切账户/删账户/登录都只派命令，等 `AccountsChanged` / +//! `DeviceLoginChanged` / `AuthlibLoginChanged` 回来才改列表； +//! 2. **密码只走一次**：`Submit` 把 `AuthlibRequest` 交给后端后立刻清掉表单里的密码 +//! （成功失败都清——重试用新输入，不在内存里多留一份凭据）； +//! 3. **表单态是纯 UI 状态**：输入框改动只写 `App::account_form` + 置脏，不派命令。 +//! +//! ## 返回 `Task`（M114 r2 / 复审 P2-1） +//! +//! 复制用户码/链接必须把 `iced::clipboard::write` 的 `Task` **交回 runtime**——iced 0.14 的 +//! `Task` 是惰性 stream，丢掉返回值等于永不执行（日志页的 Copy summary 就是正确写法）。 + +use iced::Task; +use unlucky_presenter::dto::{AccountKind, AppCommand, AuthlibRequest, DeviceLoginPhase}; + +use crate::app::Message; +use crate::pages::account::{Hint, Message as Account, Panel, Track}; + +use super::super::state::App; + +impl App { + /// 账户页消息。 + pub(super) fn on_account(&mut self, message: Account) -> Task { + // 复制是唯一需要**交回 Task** 的分支：先把它的 Task 抓出来，其余分支照旧改状态 + let clipboard = match &message { + Account::Copy(text) => Some(text.clone()), + _ => None, + }; + + match message { + Account::Open(track) => { + self.account_form.open(track); + self.account_form.hint = None; + self.view_dirty = true; + } + Account::ToggleAdd => { + self.account_form.section_open = !self.account_form.section_open; + self.account_form.hint = None; + self.view_dirty = true; + } + Account::Close => { + self.account_form.close(); + // 关面板必须把**两条轨**的登录态都收回 Idle（复审 r2 P2-1：只看 `busy()` 时， + // `Failed`/`Succeeded` 不在 busy ⇒ 状态仍是非 Idle ⇒ `Page::build` 又把面板 + // 强制回 Microsoft，按钮成了死按钮）。`CancelDeviceLogin` 在 host 侧本来就 + // 同时收两条轨并发 Idle，所以判据用「非 Idle」而不是「busy」。 + if self.state.device_login.phase != DeviceLoginPhase::Idle + || self.state.authlib_login.phase != DeviceLoginPhase::Idle + { + self.dispatch(AppCommand::CancelDeviceLogin); + } + self.view_dirty = true; + } + Account::DismissNotice => self.dispatch(AppCommand::DismissAccountNotice), + Account::Server(value) => { + self.account_form.server = value; + self.view_dirty = true; + } + Account::Login(value) => { + self.account_form.login = value; + self.view_dirty = true; + } + Account::Password(value) => { + self.account_form.password = value; + self.view_dirty = true; + } + Account::OfflineName(value) => { + self.account_form.offline_name = value; + self.view_dirty = true; + } + Account::Probe => { + let server = self.account_form.server.clone(); + if !server.trim().is_empty() { + self.dispatch(AppCommand::ProbeAuthlibServer(server)); + } + } + Account::Submit => match self.account_form.panel { + Panel::Offline => { + // 名字**不清空**：失败时用户还要看见自己输入的（复审 r1 P2-2 的另一半） + let name = self.account_form.offline_name.trim().to_string(); + if !name.is_empty() { + self.dispatch(AppCommand::AddOfflineAccount(name)); + } + } + Panel::Authlib => { + if self.account_form.authlib_ready() { + let request = AuthlibRequest::new( + self.account_form.server.clone(), + self.account_form.login.clone(), + std::mem::take(&mut self.account_form.password), + ); + self.dispatch(AppCommand::AddAuthlibAccount(request)); + } + } + Panel::Microsoft => return self.on_account(Account::StartBrowser), + Panel::None => {} + }, + Account::StartDevice => self.dispatch(AppCommand::StartDeviceLogin), + Account::StartBrowser => self.dispatch(AppCommand::StartBrowserLogin), + Account::Cancel => { + self.account_form.close(); + self.dispatch(AppCommand::CancelDeviceLogin); + } + Account::Copy(_) => {} + Account::Switch(id) => self.dispatch(AppCommand::SwitchAccount(id)), + Account::Remove(id) => self.dispatch(AppCommand::RemoveAccount(id)), + Account::Relogin(id) => return self.relogin(&id), + } + self.refresh_view(); + + match clipboard { + Some(text) => iced::clipboard::write(text), + None => Task::none(), + } + } + + /// 「重新登录」按**账户类型**分派（复审 r1 P2-3）。 + /// + /// - 微软轨：走授权码流（原路）； + /// - 第三方轨：第三方站没有「一键重登」——预填服务器地址与登录名，让用户补密码； + /// - 本地档案：没有服务器账户可重登 ⇒ 明确说明，不假装能做。 + fn relogin(&mut self, id: &str) -> Task { + let Some(account) = self + .state + .accounts + .iter() + .find(|account| account.id == id) + .cloned() + else { + return Task::none(); + }; + self.account_form.hint = None; + match account.kind { + AccountKind::Microsoft => { + self.account_form.panel = Panel::Microsoft; + self.dispatch(AppCommand::StartBrowserLogin); + } + AccountKind::Authlib => { + self.account_form.open(Track::Authlib); + self.account_form.server = account.server_url.clone(); + self.account_form.login = account.login_name.clone(); + self.account_form.password.clear(); + self.account_form.hint = Some(Hint::AuthlibReauth); + self.view_dirty = true; + self.refresh_view(); + } + AccountKind::Offline => { + self.account_form.hint = Some(Hint::OfflineNoRelogin); + self.view_dirty = true; + self.refresh_view(); + } + } + Task::none() + } +} + +/// 取证开关 `ULL_ACCOUNT_STATE` 的落地（**只在 `--screenshot` 下生效**）。 +/// +/// 为什么需要：设备码过期要等 15 分钟、表单要手点两下，截图通道等不到自然发生的状态。 +pub(super) fn force_account_state(app: &mut App) { + if !app.has_screenshot() { + return; + } + let Ok(state) = std::env::var("ULL_ACCOUNT_STATE") else { + return; + }; + match state.trim().to_lowercase().as_str() { + // 设备码已过期：起点往前挪一小时（倒计时自己算出来就是 0） + "expired" => { + app.state.device_login_started = + Some(std::time::Instant::now() - std::time::Duration::from_secs(3_600)); + } + // 第三方站**失败**态：面板打开 + mock 那边给出的 `AuthlibLoginChanged(Failed)` + "authlib-failed" => { + app.account_form.panel = crate::pages::account::Panel::Authlib; + app.account_form.server = "https://example.invalid/api/yggdrasil/".to_string(); + app.account_form.login = "alex@example.com".to_string(); + } + // 离线档案失败态：面板打开（横幅由 mock 的 notice 场景给） + "notice" => { + app.account_form.panel = crate::pages::account::Panel::Offline; + app.account_form.offline_name = "ab".to_string(); + } + // 第三方站表单：直接把面板打开并预填地址 + "authlib" | "authlib-form" => { + app.account_form.panel = crate::pages::account::Panel::Authlib; + if app.account_form.server.trim().is_empty() { + app.account_form.server = "https://littleskin.cn/api/yggdrasil/".to_string(); + } + app.account_form.login = "steve@example.com".to_string(); + app.account_form.password = "not-a-real-password".to_string(); + } + // 「关掉之后」：mock 给的是 failed 种子，这里按一次 Close（走真实的 + // `on_account` → `CancelDeviceLogin` 通道），出「面板真的关了」的对照图。 + "closed" => { + let _ = app.on_account(crate::pages::account::Message::Close); + } + // 有账号时「Add an account」展开态（P2-4 的收敛后形态） + "add" => { + app.account_form.section_open = true; + } + _ => {} + } +} + +#[cfg(test)] +mod tests; diff --git a/crates/app-iced/src/app/update/account/tests.rs b/crates/app-iced/src/app/update/account/tests.rs new file mode 100644 index 0000000..d74492b --- /dev/null +++ b/crates/app-iced/src/app/update/account/tests.rs @@ -0,0 +1,303 @@ +//! **树测试②（M119 验收核心）**：账户页消费 presenter 的账户列表与登录事件。 +//! +//! 后端是 UI 侧的 [`AccountRig`]：它把 `AppCommand` 翻成**与真 host 同形状**的 `CoreEvent` +//! （`AccountsChanged` / `DeviceLoginChanged` / `AccountNoticeChanged`），数据在内存里。 +//! 于是这条测试钉住的是「**接线**」——用户点一下之后，命令出去、事件回来、页面重算、横幅出现； +//! 抓不住的是 `core::auth::AccountStore` 的落盘（那条由 presenter 自己的 +//! `host::accounts::offline_add_list_remove_round_trips` 覆盖，原因见 `presenter/rig.rs` 的模块文档）。 +//! +//! 覆盖任务书第 3 条与第 4 条的账户那一半： +//! +//! | 断言 | 抓得住什么 | +//! |---|---| +//! | 添加离线档案 → 列表出现一行 | `AddOfflineAccount` 没派发 / 事件没回流 / 页面没重建 | +//! | 切换当前账号 → 「当前」标记换人 | `SwitchAccount` 没派发（M114 的 `active` 标记是页面唯一来源）| +//! | 删除 → 列表回到空态 | `RemoveAccount` 没派发 | +//! | 设备码「进行中可见 + 可取消」 | `StartDeviceLogin` / `CancelDeviceLogin` 没接线（只剩转圈）| +//! | 失败态：名字不合法 / 凭据失效都给**具名**错误 | 失败被吞掉（复审 r1 P2-2 的老毛病）| + +use unlucky_design::color::SchemeFlavor; +use unlucky_i18n::{Catalog, Key, Lang}; +use unlucky_presenter::dto::{ + AccountNoticeCode, AppEvent, AuthlibLoginView, CoreEvent, DeviceLoginView, LoginFailure, +}; +use unlucky_presenter::mock::MockBackend; +use unlucky_presenter::settings_bridge::SettingsBridge; + +use crate::app::state::presenter::rig::AccountRig; +use crate::pages::account::model::{AuthlibPanel, DevicePanel}; +use crate::pages::account::{Form, Message as Account, Panel, Track}; +use crate::theme::Families; + +use super::App; + +const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", +}; + +/// 不碰磁盘的 App，后端换成**账户 rig**（其余分支照旧走 `MockBackend` 的能力就够）。 +fn with_rig() -> App { + App::with_presenter( + crate::cli::Options::default(), + FAMILIES, + SchemeFlavor::Light, + Box::new(AccountRig::new()), + SettingsBridge::memory_only(), + ) +} + +/// 不碰磁盘的 App（mock 后端 + 内存设置桥），与 `app/tests.rs` 的 `headless` 同源。 +fn headless() -> App { + App::with_presenter( + crate::cli::Options::default(), + FAMILIES, + SchemeFlavor::Light, + Box::new(MockBackend::new()), + SettingsBridge::memory_only(), + ) +} + +fn seed(app: &mut App, event: CoreEvent) { + app.state.apply(AppEvent::Core(event)); + app.refresh_view(); +} + +/// **添加 → 切换 → 删除**（任务书第 3 条，一条端到端）。 +/// +/// 抓得住：三条命令任何一条没派发 / 事件没回流 / `refresh_view` 没带上账户页。 +/// 抓不住：真实账户库的落盘（见模块文档）。 +#[test] +fn an_offline_profile_is_added_switched_and_removed_end_to_end() { + let mut app = with_rig(); + assert!(app.account.is_empty(), "出厂是空态"); + + // ① 添加离线档案：走真消息（点轨道卡 → 填名字 → 提交） + let _ = app.on_account(Account::Open(Track::Offline)); + assert_eq!(app.account_form.panel, Panel::Offline); + // 表单输入也走真消息（纯 UI 态，只写 `App::account_form` + 置脏） + let _ = app.on_account(Account::OfflineName("Steve".to_string())); + assert!( + app.account_form.offline_ready(), + "3–16 位字母：按钮该是亮的" + ); + let _ = app.on_account(Account::Submit); + + assert_eq!(app.account.rows.len(), 1, "列表出现一行（不是静默）"); + assert_eq!(app.account.rows[0].name, "Steve"); + assert_eq!( + app.account.notice.as_ref().map(|notice| notice.code), + Some(AccountNoticeCode::Added), + "页面横幅给出的是一次性结果" + ); + let id = app.account.rows[0].id.clone(); + + // ② 切换当前账号 + let _ = app.on_account(Account::Switch(id.clone())); + assert_eq!( + app.account.active_row().map(|row| row.name.as_str()), + Some("Steve"), + "「当前」标记跟着切换走" + ); + + // ③ 删除 + let _ = app.on_account(Account::Remove(id)); + assert!(app.account.rows.is_empty(), "删除后回到空态"); + assert_eq!( + app.account.notice.as_ref().map(|notice| notice.code), + Some(AccountNoticeCode::Removed) + ); + // 两个横幅文案都有词（中英各一条，不是硬编码） + for lang in [Lang::En, Lang::ZhCn] { + assert!(!Catalog::of(lang).text(Key::AccountNoticeRemoved).is_empty()); + } + // 整棵树在三种状态下都能构图 + let _ = app.view(); +} + +/// 设备码流程：**指令发出 + 进行中可见 + 可取消**（任务书第 3 条的后半，真实网络不要求）。 +#[test] +fn the_device_code_flow_is_started_visible_and_cancellable() { + let mut app = with_rig(); + assert_eq!(app.account.device, DevicePanel::Hidden); + + let _ = app.on_account(Account::StartDevice); + match &app.account.device { + DevicePanel::Code { + code, remaining, .. + } => { + assert_eq!(code, "ABCD-EFGH", "用户码要上屏"); + assert!(remaining.is_some_and(|left| left > 0), "倒计时在跑"); + } + other => panic!("进行中状态必须可见，实际 {other:?}"), + } + assert_eq!(app.account.panel, Panel::Microsoft, "面板要切到微软那条轨"); + let _ = app.view(); + + let _ = app.on_account(Account::Cancel); + assert_eq!(app.account.device, DevicePanel::Hidden, "取消要真的收掉"); + assert_eq!( + app.state.device_login.phase, + unlucky_presenter::dto::DeviceLoginPhase::Idle + ); +} + +/// 失败态①：**未实现 / 名字不合法** ⇒ 页面横幅给出结构化码（不是静默无语）。 +#[test] +fn an_invalid_profile_name_surfaces_a_named_failure() { + let mut app = with_rig(); + let _ = app.on_account(Account::Open(Track::Offline)); + // 名字不合法时**发送键是灰的**（与 host 同一份判据），所以这里直接派命令： + // 抓的是「host 真的回了一个结构化失败码」这条链路，而不是按钮的禁用态。 + assert!(!app.account_form.offline_ready()); + app.dispatch(unlucky_presenter::dto::AppCommand::AddOfflineAccount( + "ab".to_string(), + )); + + assert!(app.account.rows.is_empty(), "不合法的名字不入列表"); + let notice = app.account.notice.as_ref().expect("必须有横幅"); + assert_eq!(notice.code, AccountNoticeCode::OfflineNameInvalid); + assert!(notice.failure, "失败档（配色不同）"); + assert_eq!(notice.subject, "ab", "横幅要带上是哪个名字"); + // 文案走 catalog，中英各一条 + for lang in [Lang::En, Lang::ZhCn] { + assert!(!Catalog::of(lang) + .text(Key::AccountNoticeOfflineNameInvalid) + .is_empty()); + } + let _ = app.view(); +} + +/// 失败态②：**账户凭据失效** ⇒ 第三方轨面板进入 `Failed(BadCredentials)`（只带原因码）。 +/// +/// 为什么只断言原因码：M114 r3 起面板类型里**没有** `message`/`detail` 字段（原文只进 presenter +/// 日志），页面据码选 catalog 文案。这条测试与「页面画得出文案」之间的桥梁是 +/// `pages::account::login::failure_body_key`（同一 crate 内的穷尽 match，缺一条编译不过）。 +#[test] +fn expired_credentials_surface_a_named_failure_code() { + let mut app = headless(); + seed( + &mut app, + CoreEvent::AuthlibLoginChanged(AuthlibLoginView::failed_as( + LoginFailure::BadCredentials, + "服务器返回 401：凭据已失效（token=…已脱敏）", + )), + ); + app.account_form.open(Track::Authlib); + app.refresh_view(); + + assert_eq!( + app.account.authlib, + AuthlibPanel::Failed { + failure: LoginFailure::BadCredentials + }, + "凭据失效要落成具名原因码，而不是静默回 Idle" + ); + // 原因码对应的那句译文两套语言都得有 + for lang in [Lang::En, Lang::ZhCn] { + let text = Catalog::of(lang).text(Key::AccountFailureBadCredentials); + assert!(!text.trim().is_empty(), "{} 缺这条失败文案", lang.tag()); + } + // 原文不许出现在页面的任何可视文本里（M114 的凭据红线） + assert!( + !format!("{:?}", app.account).contains("服务器返回 401"), + "后端原文不许进页面模型" + ); + let _ = app.view(); +} + +// ---------------------------------------------------------------- M114 的既有回归闸 + +/// **复审 r2 P2-1 的回归闸**：登录失败/成功态下按 `Close`，面板必须真的关掉。 +/// +/// 为什么这条以前是死按钮：`Page::build` 只要 `device_login.phase != Idle` 就把面板强制 +/// 回 Microsoft，而 `Close` 只在 `busy()`（Requesting/Waiting）时才派 `CancelDeviceLogin` +/// ⇒ Failed/Succeeded 下点了没反应。现在判据改成「非 Idle」，两条轨都覆盖。 +/// +/// 抓得住：判据退回 `busy()`；`Close` 忘了 dispatch；`CancelDeviceLogin` 没有把状态收回 Idle。 +/// 抓不住：`CancelDeviceLogin` 在**真 host** 上的副作用（这里跑的是 mock，但 mock 已按 +/// 真 host 的契约发 Idle，见 `presenter/src/mock.rs`）。 +#[test] +fn close_really_closes_the_login_panel_on_both_tracks() { + // ① 微软轨：失败态 + let mut app = headless(); + seed( + &mut app, + CoreEvent::DeviceLoginChanged(DeviceLoginView { + phase: unlucky_presenter::dto::DeviceLoginPhase::Failed, + message: "微软拒绝了这次登录：AADSTS7000218（HTTP 403）".to_string(), + failure: Some(LoginFailure::NotWhitelisted), + ..DeviceLoginView::new() + }), + ); + assert_eq!(app.account.panel, Panel::Microsoft, "失败态面板要显示"); + let _ = app.on_account(Account::Close); + assert_eq!(app.account.panel, Panel::None, "Close 之后面板必须关掉"); + assert_eq!( + app.state.device_login.phase, + unlucky_presenter::dto::DeviceLoginPhase::Idle + ); + + // ② 微软轨：成功态（同样不在 busy 里） + let mut app = headless(); + seed( + &mut app, + CoreEvent::DeviceLoginChanged(DeviceLoginView::succeeded("Steve")), + ); + assert_eq!(app.account.panel, Panel::Microsoft); + let _ = app.on_account(Account::Close); + assert_eq!(app.account.panel, Panel::None, "成功提示也要能关掉"); + + // ③ 第三方轨：失败态 + let mut app = headless(); + seed( + &mut app, + CoreEvent::AuthlibLoginChanged(AuthlibLoginView { + phase: unlucky_presenter::dto::DeviceLoginPhase::Failed, + server: "https://example.invalid/api/yggdrasil/".to_string(), + server_name: String::new(), + message: "服务器返回 HTTP 404".to_string(), + failure: Some(LoginFailure::NotAuthlibServer), + account_name: String::new(), + }), + ); + app.account_form.open(Track::Authlib); + app.refresh_view(); + assert_eq!( + app.account.panel, + Panel::Authlib, + "第三方轨失败态面板要显示" + ); + let _ = app.on_account(Account::Close); + assert_eq!(app.account.panel, Panel::None, "第三方轨也要能关掉"); + assert_eq!( + app.state.authlib_login.phase, + unlucky_presenter::dto::DeviceLoginPhase::Idle + ); +} + +/// 表单态是纯 UI 状态：打开/关闭面板不派命令，但会把面板切对。 +/// +/// 抓得住：`Open` 忘了写 `panel`（点了轨道卡什么都不出现）、`close()` 不清密码。 +/// 抓不住：真实 dispatch 的副作用（那要真后端）。 +#[test] +fn the_form_state_follows_the_page_messages() { + let mut form = Form::new(); + assert_eq!(form.panel, Panel::None); + form.open(Track::Authlib); + assert_eq!(form.panel, Panel::Authlib); + form.password = "hunter2".to_string(); + form.close(); + assert_eq!(form.panel, Panel::None); + assert!(form.password.is_empty(), "关闭面板必须把一次性密码清掉"); +} + +/// 三张轨道卡默认收起（有账号时），`ToggleAdd` 展开（复审 r1 P2-4）。 +#[test] +fn the_add_section_starts_collapsed() { + let mut form = Form::new(); + assert!(!form.section_open); + form.section_open = true; + assert!(form.section_open); +} diff --git a/crates/app-iced/src/app/update/agent.rs b/crates/app-iced/src/app/update/agent.rs new file mode 100644 index 0000000..8f32caa --- /dev/null +++ b/crates/app-iced/src/app/update/agent.rs @@ -0,0 +1,381 @@ +//! 助手栏消息的落点（M104 建，M119 接线）：三档状态迁移 / 输入 / 键盘 / **presenter 四契约**。 +//! +//! ## 为什么单独一个文件 +//! +//! `app/update.rs` 已经贴着 400 行硬上限（M94 也因此把下载页四支拆到 `update/download.rs`）。 +//! 助手栏有十几个变体，塞回主文件必破线。 +//! +//! ## 分工：视图态 vs presenter 契约（M119 之后的分界线） +//! +//! | 消息 | 落到哪 | +//! |---|---| +//! | `Expand` / `Collapse` / `Dock` / `Escape` | **只改视图态**（`AgentUi`）+ 路由栈（离开/进入 `Route::Agent`）+ `agent_mark_read` | +//! | `Detach` | 视图态 + `Route::Agent`（压栈，`back()` 能回去）+ `agent_mark_read` | +//! | `Edit` | 视图态（草稿），并同步进 presenter 的草稿（`agent_set_draft`） | +//! | `Submit` | [`AgentHost::submit`] → `agent_submit`；失败**不留白**（具名错误进横幅） | +//! | `Stop` | `AppCommand::StopAgent`（真后端才收敛得出结果；同步 rig 下是 no-op） | +//! | `Confirm(accept)` | [`AgentHost::confirm`] → `agent_confirm`（YOLO 下 presenter 自己放行并记审计） | +//! | `Events(..)` | [`AgentHost::apply`] → `AppState::apply`（**事件回流的唯一落点**） | +//! | `DragStart` / `DragTo` / `DragEnd` | 视图态：吸附宽度 | +//! | `Key` / `Tab` / `Activate` | 键盘路径（`Tab` 的环要在流式中多一格，`busy` 从 rail 取） | +//! +//! **会话内容一行都不在这里攒**：`transcript` / `busy` / `unread` / `confirm` 全在 presenter 的 +//! `AgentRail` 上（M119 删掉了 M104 的自持副本）。 +//! +//! ## 事件为什么绕一圈消息再回来 +//! +//! `agent_submit` / `agent_confirm` 的端口是同步的，但**事件走队列**（见 +//! `app/state/presenter/transport.rs`）：抽队列的那一步必须和用户点击走同一条漏斗，否则两处各改 +//! 一次状态，流式标记与未读会打架。所以 [`App::drain_agent`] 抽出来之后立刻 +//! `on_agent(agent::Message::Events(..))` —— 同一条 `Message::Agent(..)` 通道。 + +use iced::keyboard::{key, Key}; +use iced::Task; + +use unlucky_i18n::{Catalog, Key as TextKey}; +use unlucky_presenter::dto::AppCommand; + +use crate::app::MIN_SIZE; +use crate::app::WINDOW_SIZE; +use crate::shell::agent::demo::{self, Fixture}; +use crate::shell::agent::{self, Focus, RailState}; + +use super::super::state::presenter::agent::SubmitOutcome; +use super::*; + +#[cfg(test)] +mod tests; + +impl App { + /// 助手栏消息（`app::Message::Agent(..)` 的唯一落点）。 + pub(super) fn on_agent(&mut self, message: agent::Message) -> Task { + // M106 口径：文案走**生效语言**的目录，不再恒英文 + let catalog = Catalog::of(self.lang()); + + // 只有**几何**会变的几支才需要重建页面模型（`pages::Model` 里没有会话内容：会话在 + // presenter 的 rail 上，右栗自己那棵树每次 `view()` 都从 rail 现读）。复审 P3-9 的教训： + // 每敲一个字符都重建整张模型是白克隆。 + let geometry_changed = matches!( + message, + agent::Message::Expand + | agent::Message::Collapse + | agent::Message::Detach + | agent::Message::Dock + | agent::Message::DragTo(_) + | agent::Message::DragEnd + | agent::Message::Escape + | agent::Message::Activate + | agent::Message::Key(_) + ); + + match message { + agent::Message::Expand => { + self.agent.expand(); + // 「展开即读」是 presenter 的语义（`agent_mark_read`），壳只负责在正确的时刻调它 + self.agent_host.mark_read(); + } + agent::Message::Collapse | agent::Message::Escape => self.collapse_agent(), + agent::Message::Detach => { + self.agent.detach(); + self.agent_host.mark_read(); + self.state.navigate(Route::Agent); + } + agent::Message::Dock => { + self.agent.dock(); + self.agent_host.mark_read(); + self.leave_agent_page(); + } + agent::Message::DragStart => self.agent.drag_start(), + agent::Message::DragTo(x) => self.agent.drag_to(self.width, x), + agent::Message::DragEnd => self.agent.drag_end(), + agent::Message::Edit(action) => { + self.agent.edit(action); + // 草稿同步给 presenter（切形态不丢；它也是 rail 上唯一允许躺原文的字段） + self.agent_host.set_draft(self.agent.draft.text()); + } + agent::Message::Submit => self.submit_agent(), + agent::Message::Stop => self.dispatch(AppCommand::StopAgent), + agent::Message::Confirm(accept) => { + self.agent_host.confirm(accept); + self.drain_agent(); + } + agent::Message::Events(events) => { + for event in events { + self.agent_host.apply(event); + } + self.view_dirty = true; + } + agent::Message::Tab { shift } => { + let rail = self.agent_host.rail(); + let (busy, pending) = (rail.busy, rail.confirm.is_some()); + self.agent.step_focus(shift, busy, pending); + } + agent::Message::Activate => self.activate_focused(catalog), + agent::Message::Key(event) => return self.on_agent_key(event), + } + + // 待确认请求出现/消失时，把键盘焦点挪到（或挪离）确认条的按钮上 + self.sync_confirm_focus(); + // 档位 / 路由变了就要把「栏可见吗」写回 presenter（未读口径的输入） + self.sync_agent_presenter(); + if geometry_changed { + self.view_dirty = true; + self.refresh_view(); + } + Task::none() + } + + /// 发送：草稿 → `agent_submit` → 抽事件。 + /// + /// 三种结局各自有落点：发出去（清草稿）/ 后端失败（具名横幅，见 [`App::agent_failure`]）/ + /// presenter 拒收（日志一行——这三种情形正常情况下被禁用态挡住，够不着）。 + fn submit_agent(&mut self) { + let text = self.agent.draft.text(); + if text.trim().is_empty() { + return; + } + match self.agent_host.submit(text) { + SubmitOutcome::Sent => { + self.agent.clear_draft(); + self.agent_host.set_draft(String::new()); + self.drain_agent(); + } + SubmitOutcome::Failed(failure) => { + eprintln!("[agent] 提交失败（{}）", failure.code()); + } + SubmitOutcome::Rejected => { + eprintln!("[agent] presenter 拒收：空文本 / 上一轮未完 / 待确认 三闸该先挡住"); + } + } + } + + /// 抽干 presenter 的事件队列，**经既有 Message 通道**回流（见模块文档末节）。 + pub(crate) fn drain_agent(&mut self) { + let events = self.agent_host.drain(); + if events.is_empty() { + return; + } + let _ = self.on_agent(agent::Message::Events(events)); + } + + /// 把「栏可见吗」写回 presenter（`navigate` + `prefs_mut` 两个窄入口，见 `AgentHost`）。 + pub(crate) fn sync_agent_presenter(&mut self) { + let on_page = self.state.route() == &Route::Agent; + let collapsed = self.agent.rail == RailState::Collapsed; + self.agent_host.sync_visibility(on_page, collapsed); + } + + /// 失败横幅要显示的东西（`None` = 没有错误）。 + /// + /// 两个来源都取**展示输入**：具名原因码 → catalog 译文；或 presenter 已脱敏的这一轮原因。 + /// 壳在这一层不做任何脱敏（那是 presenter 的`scrub_text`），也不拼中英（那是 catalog 的事）。 + pub(crate) fn agent_failure(&self) -> Option> { + let catalog = self.lang().catalog(); + if let Some(failure) = self.agent_host.last_failure() { + return Some(agent::Failure { + title: TextKey::AgentErrorTitle, + body: catalog.text(failure.body_key()), + }); + } + self.agent_host + .rail() + .error + .as_deref() + .map(|body| agent::Failure { + title: TextKey::AgentErrorTitle, + body, + }) + } + + /// 待确认请求出现 ⇒ 焦点直接落在「允许」；消失 ⇒ 收回输入框。 + /// + /// **只挪焦点，不替用户打开键盘巡航**（M119 r2 / 复审 P2-2）：r1 在这里顺手把 + /// `keyboard_mode` 置真，而 `sync_confirm_focus` 是 `on_agent` 的无条件尾巴、`Events` 又由心跳 + /// 驱动——于是只要冒出待确认，全局键盘闸就被打开；用户发完那句话接着打下一句，第一个空格 + /// 就成了「批准写操作」。现在那道闸只由真实的键盘表态打开（`Tab`，见 `AgentUi::step_focus`； + /// 或者 `on_agent_key` 把按键送进来时用户本来就在键盘巡航）。 + /// + /// 键盘用户怎么走到确认条：待确认时焦点已经在这两个按钮上，**按一次 `Tab` 点亮焦点环即是 + /// 表态**（`step_focus` 里那条 arming 规则：这一次不移动焦点），之后 `Enter`/`Space` 就能裁决。 + /// + /// 唯一写入口：`on_agent` 末尾（任何会改动 rail 的分支之后都要经过它）。 + fn sync_confirm_focus(&mut self) { + let pending = self.agent_host.rail().confirm.is_some(); + let on_confirm = matches!(self.agent.focus, Focus::ConfirmAllow | Focus::ConfirmDeny); + if pending && !on_confirm { + self.agent.focus = Focus::ConfirmAllow; + eprintln!("[agent] 写操作待确认 → 焦点落到 Allow（Tab 点亮焦点环后 Enter/Space 裁决）"); + } else if !pending && on_confirm { + self.agent.focus = Focus::Composer; + self.agent.keyboard_mode = false; + } + } + + /// **不变式**：`route() == Route::Agent` ⟺ `agent.rail == RailState::Detached`（唯一同步点）。 + /// + /// 为什么需要它（复审 r1 的 P2-1，实测复现）：`agent.rail` 只在自己发 `Detach`/`Dock` 时变， + /// 而路由还能从三条**别的**路径进 `Route::Agent`——左侧导航第五项、`pages::Message::Navigate`、 + /// `ULL_START_ROUTE=agent`。脱钩的后果：从导航进独立页时头部出现「Open assistant」（那是 + /// 「展开右栗」的意思）、标题旁挂着不化的未读胶囊、`Esc` 也收不走页面。 + /// + /// 两条对向规则： + /// - **在**独立页上 ⇒ `Detached`（顺带按「拆出即读」清未读）； + /// - **不在**独立页上而档位还是 `Detached`（用户从页上点了别的导航）⇒ 会话收回右栗（`dock()`）， + /// 否则会话会「两头都没有」：页走了、栏还是 0 宽。 + /// + /// 调用点只有一个：`App::refresh_view` 的开头。每一次路由变化都会经过它，于是**模型算宽度时** + /// 与**画头部动作时**读到的永远是同一份档位。 + pub(crate) fn sync_agent_route(&mut self) { + let on_page = self.state.route() == &Route::Agent; + match (on_page, self.agent.rail) { + (true, RailState::Detached) | (false, RailState::Collapsed | RailState::Expanded) => {} + (true, _) => self.agent.detach(), + (false, RailState::Detached) => self.agent.dock(), + } + } + + /// 启动时助手栏要做的三件事（从 `on_boot` 搬出来：那边只许留一行调用，复审 P3-6）。 + /// + /// 1. **窗口尺寸 adopt**：唯一真源是 `boot.rs` 开窗时用的那一个（`ULL_WINDOW_SIZE` + 最小尺寸 + /// 钳位）。`App::with_presenter` 只认识常量 1180×760，不 adopt 的话验收矩阵开 900 / 1520 的窗 + /// 时页面还按 1180 排版（窄窗里内容被裁）。 + /// 2. **取证夹具**（`ULL_AGENT_*`）：先落档位，再**跑一轮真提交**——夹具不造消息，消息只能 + /// 由 presenter 产生（M119 的口径，见 `pages/agent/demo.rs`）。 + /// 3. **拆出档直接落到独立页**：`ULL_AGENT_RAIL=detached`（以及将来持久化的偏好）时，会话就在 + /// 独立页里，启动后不该停在实例页。 + pub(super) fn boot_agent(&mut self) { + let (window_size, _source) = crate::renderer::acceptance::window::window_size( + (WINDOW_SIZE.width, WINDOW_SIZE.height), + (MIN_SIZE.width, MIN_SIZE.height), + ); + self.width = window_size.0; + self.height = window_size.1; + + if let Some((ui, fixture)) = demo::from_env() { + self.agent = ui; + // 先让 presenter 知道「栏现在看得见吗」，再跑提交，未读口径才对 + self.sync_agent_presenter(); + match fixture { + Fixture::None => {} + Fixture::Turn | Fixture::Unread => { + let _ = self.agent_host.submit(demo::DEMO_QUESTION.to_string()); + self.drain_agent(); + } + Fixture::Armed => { + // 先跑一轮（写操作脚本会挂一个待确认），再按一次 `Tab`： + // 待确认时这一下只 arm、不移动焦点（见 `AgentUi::step_focus` 的 arming 规则） + let _ = self.agent_host.submit(demo::DEMO_QUESTION.to_string()); + self.drain_agent(); + let rail = self.agent_host.rail(); + let (busy, pending) = (rail.busy, rail.confirm.is_some()); + self.agent.step_focus(false, busy, pending); + } + Fixture::Focused => { + let rail = self.agent_host.rail(); + let (busy, pending) = (rail.busy, rail.confirm.is_some()); + self.agent.step_focus(false, busy, pending); + } + } + } + + if self.agent.rail == RailState::Detached && self.state.route() != &Route::Agent { + eprintln!("[agent] rail=detached → Route::Agent"); + self.state.navigate(Route::Agent); + // 直达独立页时不要再被「自动选中第一条实例」拉回详情页。 + self.auto_selected = true; + } + } + + /// 键盘订阅来的按键（`app/subscription.rs` 把整条键盘事件搬过来，解释权在这一层）。 + /// + /// 为什么不让订阅层直接翻成三个枚举：那样 `Escape`/`Tab`/`Enter` 的语义（什么状态下该做什么） + /// 会散在订阅表里；这里一眼能看完。 + fn on_agent_key(&mut self, event: iced::keyboard::Event) -> Task { + let iced::keyboard::Event::KeyPressed { key, modifiers, .. } = event else { + return Task::none(); + }; + + let message = match key { + Key::Named(key::Named::Escape) => agent::Message::Escape, + // 折叠档没有会话动作可巡航，`Tab` 不该被助手栏吃掉 + Key::Named(key::Named::Tab) if self.agent.rail == RailState::Collapsed => { + return Task::none(); + } + Key::Named(key::Named::Tab) => agent::Message::Tab { + shift: modifiers.shift(), + }, + // `Activate` 只在软焦点落在**按钮**上时才动手（输入框的 Enter 由 + // `text_editor::key_binding` 分流成「发送」，不能在这里重复发一次）。 + // + // M119 r1 / P2-2：`Space` 与 `Enter` 等价（键盘用户对确认条的习惯动作是空格）。 + // 它不会抢输入框里的空格：`activate_focused` 头一行就是 `keyboard_mode` 闸， + // 而用鼠标点进输入框时那道闸是关的（`AgentUi::edit` 的 `Click` 分支）。 + Key::Named(key::Named::Enter | key::Named::Space) => agent::Message::Activate, + _ => return Task::none(), + }; + + self.on_agent(message) + } + + /// `Esc` / `⌄`：展开 → 收起；独立页 → 收回右栗并离开 `Route::Agent`。 + fn collapse_agent(&mut self) { + let was_detached = self.agent.rail == RailState::Detached; + self.agent.collapse(); + if was_detached { + self.leave_agent_page(); + } + } + + /// 离开 AI 独立页：能回退就回退（`Detach` 是压栈的），否则回实例页。 + fn leave_agent_page(&mut self) { + if self.state.route() != &Route::Agent { + return; + } + if !self.state.back() { + self.state.navigate(Route::Instances); + } + } + + /// 键盘 `Enter`：激活软焦点上的按钮（`Tab` 环的顺序见 [`Focus`]）。 + /// + /// 焦点在 [`Focus::Composer`] 上时**什么都不做**：那一条路径由输入框自己的 `key_binding` + /// 负责（按 `Tab` 走到输入框并不等于真的把 iced 焦点交过去，两次发送会打架）。 + fn activate_focused(&mut self, catalog: Catalog) { + // 鼠标刚点过输入框（或从没按过 `Tab`）⇒ 这个 Enter 不归助手栏管 + if !self.agent.keyboard_mode { + return; + } + + let intent = match (self.agent.rail, self.agent.focus) { + (RailState::Collapsed, Focus::Collapse) => Some(agent::Message::Expand), + (RailState::Expanded, Focus::Collapse) => Some(agent::Message::Collapse), + (RailState::Expanded, Focus::Detach) | (RailState::Detached, Focus::Detach) => { + Some(if self.agent.rail == RailState::Detached { + agent::Message::Dock + } else { + agent::Message::Detach + }) + } + (_, Focus::ConfirmAllow) => Some(agent::Message::Confirm(true)), + (_, Focus::ConfirmDeny) => Some(agent::Message::Confirm(false)), + (_, Focus::Send) => Some(agent::Message::Submit), + (_, Focus::Stop) => Some(agent::Message::Stop), + // 折叠档没有「拆出」、独立页没有「收起」：焦点环按 `Focus::order` 不会落到这两格， + // 显式列成 None 只是为了让编译器确认这份 intent 表是穷尽的。 + (RailState::Collapsed, Focus::Detach) + | (RailState::Detached, Focus::Collapse) + | (_, Focus::Composer) => None, + }; + + if let Some(message) = intent { + let _ = self.on_agent(message); + } else { + // 「不得静默无反应」：焦点在输入框上按 Enter 由输入框自己处理，这里只留一行日志。 + eprintln!( + "[agent] Enter on focus={} handled by the composer", + self.agent.focus.name() + ); + let _ = catalog; + } + } +} diff --git a/crates/app-iced/src/app/update/agent/tests.rs b/crates/app-iced/src/app/update/agent/tests.rs new file mode 100644 index 0000000..e1a6da3 --- /dev/null +++ b/crates/app-iced/src/app/update/agent/tests.rs @@ -0,0 +1,352 @@ +//! **树测试①（M119 验收核心）**：AI 右栏在**真实 presenter 状态**下渲染。 +//! +//! 走的是同一条用户路径：`Message::Agent(Submit)` → `AgentHost::submit` → `Presenter::agent_submit` +//! → transport → 事件队列 → `Message::Agent(Events)` → `Presenter::apply` → `AgentRail`。 +//! **没有一条断言看本地数组**：`transcript` 这类壳自己的会话副本 M119 已经删了，能断言的只剩 +//! presenter 的 rail，而 rail 正是右栏画的东西（`pages/agent::spec` 从它借）。 +//! +//! 覆盖任务书点名的四件事： +//! +//! | 断言 | 抓得住什么 | +//! |---|---| +//! | 提交后 rail 出现「你 + 助手」两条、正文来自事件的流式增量 | 提交没接到 presenter、或右栏还在画样本会话 | +//! | `busy` 翻真 → 收敛后翻假 | 事件没回流、或流式标记没收敛（输入框会永远禁用） | +//! | 标记已读后未读归零 | `agent_mark_read` 没接、或未读口径没跟着 rail | +//! | 三种失败都给**具名**横幅 | 失败被吞掉（M104 的「静默无语」）| + +use iced::widget::text_editor; + +use unlucky_design::color::SchemeFlavor; +use unlucky_i18n::{Catalog, Key, Lang}; +use unlucky_presenter::dto::{AgentEvent, AppEvent, ChatRole}; +use unlucky_presenter::mock::MockBackend; +use unlucky_presenter::settings_bridge::SettingsBridge; + +use iced::keyboard::key::{Code, Named, Physical}; +use iced::keyboard::{key, Location, Modifiers}; + +use crate::app::state::presenter::transport::Script; +use crate::app::state::presenter::AgentHost; +use crate::app::Message; +use crate::cli::Options; +use crate::shell::agent::{Focus, Message as AgentMessage, RailState}; +use crate::theme::Families; + +use super::App; + +const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", +}; + +/// 不碰磁盘的 App（mock 后端 + 内存设置桥 + **本脚本的** presenter 句柄）。 +fn app_with(script: Script) -> App { + let mut app = App::with_presenter( + Options::default(), + FAMILIES, + SchemeFlavor::Light, + Box::new(MockBackend::new()), + SettingsBridge::memory_only(), + ); + app.agent_host = AgentHost::with_script(script); + // 换句柄 = 可见性还没写回去；`refresh_view` 是那条单点同步 + app.refresh_view(); + app +} + +/// 走真消息提交（用户路径：填草稿 → 点发送）。 +fn submit(app: &mut App, text: &str) { + app.agent.draft = text_editor::Content::with_text(text); + let _ = app.update(Message::Agent(AgentMessage::Submit)); +} + +/// **提交 → 事件回流 → 右栏出现这一轮 → 标记已读归零**（任务书第 2 条）。 +/// +/// 抓得住：①`Submit` 没接 `agent_submit`（rail 空）；②事件没经 Message 通道回流（rail 只有半截）； +/// ③`expand` 没调 `agent_mark_read`（未读不清）；④右栏读的还是壳自己的副本。 +/// 抓不住：气泡在像素上长什么样（那要出图，见 `DevDocs/artifacts/m119/`）。 +#[test] +fn a_submitted_turn_lands_in_the_rail_and_reading_it_zeroes_unread() { + let mut app = app_with(Script::Qa); + // 出厂是折叠档 ⇒ presenter 认为「用户没在看着」，到达的助手消息应计未读 + assert_eq!(app.agent.rail, RailState::Collapsed); + assert_eq!(app.agent_host.rail().unread, 0, "空会话没有未读"); + + submit(&mut app, "Which instance should I start?"); + + let rail = app.agent_host.rail(); + assert_eq!( + rail.messages.len(), + 2, + "一条「你」+ 一条助手（事件产生，不是本地回显）" + ); + assert_eq!(rail.messages[0].role, ChatRole::User); + assert_eq!(rail.messages[0].text, "Which instance should I start?"); + assert_eq!(rail.messages[1].role, ChatRole::Assistant); + assert!( + rail.messages[1].text.contains("Fabric"), + "正文来自流式增量：{:?}", + rail.messages[1].text + ); + assert!(!rail.messages[1].streaming, "Qa 脚本会收敛"); + assert!(!rail.busy, "收敛之后不忙（发送键要能再按）"); + assert_eq!(rail.unread, 1, "折叠态到达的一条助手消息 = 一条未读"); + + // 右栏画的正是这份 rail（`pages/agent::spec` 直接借它）——构图不 panic + let _ = app.view(); + + // 打开栏 = 读过：`agent_mark_read` + let _ = app.update(Message::Agent(AgentMessage::Expand)); + assert_eq!(app.agent_host.rail().unread, 0, "标记已读后未读归零"); + assert_eq!(app.agent_host.rail().messages.len(), 2, "已读不改会话"); +} + +/// **busy 正确翻转**：流式中忙 → 后端收敛后不忙。 +/// +/// 抓得住：`busy` 还由壳自己算（那它不会跟 rail 走）；`Events` 通道被当成「只追加消息」而丢掉 +/// `MessageFinished`（输入框会永远禁用——这是最要命的坏法之一）。 +#[test] +fn busy_flips_with_the_backend_events() { + let mut app = app_with(Script::Streaming); + submit(&mut app, "hello"); + assert!(app.agent_host.rail().busy, "流式没收敛前输入要禁用"); + + // 后端收敛：一条 `MessageFinished` 经同一条 Message 通道回流 + let index = app.agent_host.rail().messages.len() - 1; + let _ = app.update(Message::Agent(AgentMessage::Events(vec![AppEvent::Agent( + AgentEvent::MessageFinished { index }, + )]))); + assert!(!app.agent_host.rail().busy, "收敛之后必须能再发"); +} + +/// 写操作确认：rail 上有待确认 ⇒ 忙；裁决后收敛并记一条审计。 +#[test] +fn a_pending_write_op_is_visible_and_decidable() { + let mut app = app_with(Script::WriteOp); + submit(&mut app, "把下载并发改小"); + + let rail = app.agent_host.rail(); + let request = rail.confirm.as_ref().expect("要挂一个待确认请求"); + assert_eq!(request.tool, "set_config"); + assert!( + rail.busy, + "等确认也算忙（否则用户能在一轮写操作中间再发一句）" + ); + let _ = app.view(); + + let _ = app.update(Message::Agent(AgentMessage::Confirm(true))); + assert!(app.agent_host.rail().confirm.is_none(), "裁决后清空"); + assert!(!app.agent_host.rail().busy); + assert_eq!(app.agent_host.audit_len(), 1, "裁决要进审计（YOLO 下也是）"); +} + +/// 失败态①：**AI 端点不可达** ⇒ 具名横幅（不是静默，也不是把后端原文糊上屏）。 +#[test] +fn an_unreachable_endpoint_shows_a_named_error() { + let mut app = app_with(Script::Unreachable); + submit(&mut app, "hello"); + + let failure = app.agent_failure().expect("提交失败必须给横幅"); + // 文案跟着**生效语言**走（`LangState` 在这台机器上探到 zh-CN，硬编码英文会假红） + let effective = app.lang().catalog(); + assert_eq!(failure.title, Key::AgentErrorTitle, "标题是 catalog 键"); + assert_eq!(failure.body, effective.text(Key::AgentErrorUnavailable)); + assert!(!failure.body.trim().is_empty()); + assert!( + app.agent_host.rail().messages.is_empty(), + "失败不产生消息：不许假装有回复" + ); + let _ = app.view(); +} + +/// 失败态②：**未实现路由** ⇒ 另一句具名错误（两种失败不能糊成一句）。 +#[test] +fn an_unimplemented_route_shows_its_own_named_error() { + let mut app = app_with(Script::NotImplemented); + submit(&mut app, "hello"); + + let failure = app.agent_failure().expect("必须给横幅"); + let effective = app.lang().catalog(); + assert_eq!(failure.body, effective.text(Key::AgentErrorNotImplemented)); + // 两条原因码要两句话（中英两套都得分开），不是一句万能错误 + for lang in [Lang::En, Lang::ZhCn] { + let catalog = Catalog::of(lang); + assert_ne!( + catalog.text(Key::AgentErrorNotImplemented), + catalog.text(Key::AgentErrorUnavailable), + "{} 下两条原因码糊成一句了", + lang.tag() + ); + } +} + +/// 失败态③：**这一轮回复中途断流** ⇒ 横幅用 presenter 已脱敏的那句原因，已到的增量保留。 +#[test] +fn a_turn_level_failure_keeps_the_partial_answer_and_the_reason() { + let mut app = app_with(Script::FailsMidStream); + submit(&mut app, "读一下日志"); + + let rail = app.agent_host.rail(); + // 用户 + 助手（流式占位）+ 系统条目（`Failed` 会额外追加一条，错误也要能回翻） + assert_eq!(rail.messages.len(), 3, "断流不撤销已到的增量"); + assert!( + rail.messages[1].text.contains("日志"), + "已到的增量要留着：{:?}", + rail.messages[1].text + ); + assert!(!rail.busy, "断流要收敛掉流式标记"); + let failure = app.agent_failure().expect("`Failed` 事件要立横幅"); + assert!( + failure.body.contains("read timeout"), + "横幅正文是 presenter 脱敏后的原因：{}", + failure.body + ); +} + +/// 输入框的草稿会同步给 presenter（切形态不丢的语义在 presenter 那边）。 +/// **P2-1**：默认配置下后端是脚本化 rig ⇒ 视图必须知道「这是模拟」（界面据此常驻标记）。 +/// +/// 抓得住：`is_simulated` 被写死成 `false`、或者视图拿不到这个事实（用户就会以为模型接上了）。 +/// 抓不住：标记在像素上长什么样（那要出图，见 `DevDocs/artifacts/m119/08-*`）。 +#[test] +fn the_default_backend_reports_itself_as_simulated() { + let app = app_with(Script::Qa); + assert!( + app.agent_host.is_simulated(), + "脚本化 rig 必须自报「模拟」，否则界面就能假装模型接上了" + ); + // 空会话（最容易被误读成一屏）也要能拿到：视图入参 `Session.simulated` 就是它 + let session = crate::shell::agent::Session { + agent: &app.agent, + rail: app.agent_host.rail(), + failure: app.agent_failure(), + simulated: app.agent_host.is_simulated(), + }; + assert!(session.simulated); +} + +#[test] +fn typing_syncs_the_draft_into_the_presenter() { + let mut app = app_with(Script::Qa); + app.agent.draft = text_editor::Content::with_text("half typed"); + let _ = app.update(Message::Agent(AgentMessage::Edit( + text_editor::Action::Edit(text_editor::Edit::Insert('!')), + ))); + assert_eq!( + app.agent_host.rail().draft, + app.agent.draft.text(), + "编辑器里是什么，rail 上就该是什么（同一个串，不是它自己的副本）" + ); + assert!(app.agent_host.rail().draft.contains('!'), "改动真的进去了"); + // 发送成功后草稿两边都清空 + let _ = app.update(Message::Agent(AgentMessage::Submit)); + assert!(app.agent.draft_is_blank(), "编辑器清空"); + assert!(app.agent_host.rail().draft.is_empty(), "presenter 侧也清空"); +} + +/// 手搓一条按键事件（订阅层搬过来的就是它；`on_agent_key` 只看 `KeyPressed`）。 +fn press(named: key::Named) -> iced::keyboard::Event { + let key = key::Key::Named(named); + iced::keyboard::Event::KeyPressed { + key: key.clone(), + modified_key: key, + physical_key: Physical::Code(Code::Enter), + location: Location::Standard, + modifiers: Modifiers::default(), + text: None, + repeat: false, + } +} + +/// **P2-2 的回归闸**：不碰鼠标、只用键盘消息，能完成一次写操作确认。 +/// +/// 为什么这条重要：确认条原本只有鼠标路径，而待确认时 `busy` 锁着发送、`Stop` 又走主后端 +/// （清不掉 presenter 的 pending）——键盘用户会在这一步**永久卡死**。 +/// +/// 抓得住：①焦点没主动落到确认条（`Enter` 够不着）；②`Enter` / `Space` 没映射成 `Activate`； +/// ③`Tab` 环里没有确认条那两格；④裁决完焦点没收回输入框（下一句话打不进去）。 +/// 抓不住：焦点环在像素上的样子（那要出图，见 `DevDocs/artifacts/m119/09-*`）。 +#[test] +fn a_blocking_confirm_can_be_decided_with_the_keyboard_alone() { + let mut app = app_with(Script::WriteOp); + submit(&mut app, "把下载并发改小"); + assert!( + app.agent_host.rail().confirm.is_some(), + "先要有一个待确认请求" + ); + // ① 焦点主动落在「允许」（阻塞态），但**键盘闸不替用户打开**（复审 r2 / P2-2） + assert_eq!( + app.agent.focus, + Focus::ConfirmAllow, + "焦点要落在可操作元素上" + ); + assert!( + !app.agent.keyboard_mode, + "塔台 r2：不许自动 arm——自动 arm 会让用户随手敲的空格变成「批准」" + ); + + // ② 第一次 Tab = 「我要用键盘」的表态：只点亮焦点环，**不移动**焦点 + let _ = app.update(Message::Agent(AgentMessage::Tab { shift: false })); + assert!(app.agent.keyboard_mode, "Tab 之后才算 armed"); + assert_eq!( + app.agent.focus, + Focus::ConfirmAllow, + "arming 的那一次不移动焦点（否则 Enter 会反着裁决）" + ); + + // ③ Enter = 允许 + let _ = app.update(Message::Agent(AgentMessage::Key(press(Named::Enter)))); + assert!( + app.agent_host.rail().confirm.is_none(), + "Enter 必须真的裁决掉" + ); + assert_eq!(app.agent_host.audit_len(), 1, "裁决进审计"); + assert_eq!(app.agent.focus, Focus::Composer, "裁决完焦点收回输入框"); + assert!(!app.agent.keyboard_mode, "阻塞态结束就不再亮焦点环"); + + // ④ 第二轮走「Tab 点环 → Tab 走到拒绝 → Space 触发」：键盘用户不必背 Enter 是哪一个 + submit(&mut app, "那把并发改回来"); + assert_eq!(app.agent.focus, Focus::ConfirmAllow); + let _ = app.update(Message::Agent(AgentMessage::Tab { shift: false })); + let _ = app.update(Message::Agent(AgentMessage::Tab { shift: false })); + assert_eq!(app.agent.focus, Focus::ConfirmDeny, "Tab 要能走到「拒绝」"); + let _ = app.update(Message::Agent(AgentMessage::Key(press(Named::Space)))); + assert!(app.agent_host.rail().confirm.is_none(), "Space 也要能裁决"); + assert_eq!(app.agent_host.audit_len(), 2); +} + +/// **复审 r2 / P2-2 的反向回归**：没 armed 的时候，空格与回车都不许裁决写操作。 +/// +/// 复审用临时用例复现的路径：WriteOp 提交后（r1 无条件 arm），用户接着打下一句，第一个空格就成了 +/// 「允许」。真实场景里编辑器仍持 iced 焦点，所以这条不是理论问题。 +/// +/// 抓得住：谁把 `sync_confirm_focus` 里的 `keyboard_mode = true` 加回来；谁把 `Space`/`Enter` 的 +/// `Activate` 绕到 `keyboard_mode` 闸之外。 +/// 抓不住：iced 组件树里空格到底有没有进输入框（那要真窗口，出图另算）——这里只断言「没裁决」。 +#[test] +fn a_stray_space_or_enter_never_approves_a_pending_write() { + let mut app = app_with(Script::WriteOp); + submit(&mut app, "把下载并发改小"); + assert!(app.agent_host.rail().confirm.is_some()); + assert!(!app.agent.keyboard_mode, "待确认不该自动 arm"); + + // 用户接着打下一句：先敲一个字符（编辑器自己消化），再敲空格 + let _ = app.update(Message::Agent(AgentMessage::Edit( + text_editor::Action::Edit(text_editor::Edit::Insert('a')), + ))); + let _ = app.update(Message::Agent(AgentMessage::Key(press(Named::Space)))); + assert!( + app.agent_host.rail().confirm.is_some(), + "未 armed 时空格不许批准写操作" + ); + assert_eq!(app.agent_host.audit_len(), 0, "也不许留下审计"); + + // 回车同理：未 armed 时它归编辑器（发送键），不归确认条 + let _ = app.update(Message::Agent(AgentMessage::Key(press(Named::Enter)))); + assert!( + app.agent_host.rail().confirm.is_some(), + "未 armed 时回车不许批准写操作" + ); + assert_eq!(app.agent_host.audit_len(), 0); +} diff --git a/crates/app-iced/src/app/update/appearance.rs b/crates/app-iced/src/app/update/appearance.rs new file mode 100644 index 0000000..e95f6f1 --- /dev/null +++ b/crates/app-iced/src/app/update/appearance.rs @@ -0,0 +1,81 @@ +//! M116：窗口圆角的下发落点（`impl App::apply_window_corner`）。 +//! +//! ## 为什么单独成文件 +//! +//! 圆角与整窗 α 是**两条独立的管线**，只是都必须拿到 HWND、都在同一个时点下发： +//! +//! | 管线 | 判据 | 落点 | 键 | +//! |---|---|---|---| +//! | 整窗 α（D36） | `platform::effective_window_alpha` | `SetLayeredWindowAttributes` | `appearance.window_opacity` | +//! | 圆角（M116） | `platform::plan_corner` | `DwmSetWindowAttribute` | `appearance.window_corner` | +//! +//! 合在一个函数里会让「α 变了要不要重设圆角」这种问题变成实现细节；分开之后两个判据各自可测。 +//! +//! ## 日志为什么是**一行、六栏** +//! +//! `corner=policy=… source=dwm|square os=… excluded_reason=… radius=system pref=… readback=… frame=… layered=…` +//! +//! 用户报的现象是「别的窗口都有圆角，只有我们的没有」。没有这一行，事后无法区分 +//! 「没生效」「生效了但看不见」「这台系统根本没有这个能力」；`frame` / `layered` 两栏则是 +//! 「圆角为什么不生效」的两个现场读数：`frame=`（窗口形状）与 `layered=`（整窗 α 引入的分层位）。 +//! +//! ⚠️ **产品窗口不是 `WS_POPUP`**（M116 r4 复审订正）：winit 在 `decorations = false` 下给的是 +//! `WS_CAPTION|WS_BORDER|WS_CLIPSIBLINGS|WS_SYSMENU`（可缩放时再加 `WS_THICKFRAME` 与 min/max 键）， +//! `WS_POPUP` 只在**带 owner** 的弹出窗才加；无边框观感来自 `WM_NCCALCSIZE` 把客户区铺满。 +//! 所以真进程日志里 `frame=` 应是 `overlapped`（关掉 min/max 则 `other`），**永远不会是 `popup`**。 +//! 真正让系统忽略圆角请求的是**整窗 α 补的 `WS_EX_LAYERED`**（`layered=on`）。 +//! +//! `radius=system` 是刻意的：系统不暴露 DWM 的圆角半径，我们也不自己定一个数字 +//! （M116 取消了 8/12/16 固定档）。 + +use crate::platform; +use crate::platform::win32::corner::{self, CornerApplied}; +use crate::platform::win32::transparency::{apply_corner, style_summary, CornerOutcome}; + +use super::super::state::App; + +impl App { + /// 把当前圆角策略下发到窗口，并打一行可分辨的日志。 + /// + /// ## 去重（M116 r1 复审 P2-4） + /// + /// 设置页的滑条（整窗 α / 面板 α / 暗化）每动一下都会走一次外观变更，而圆角与那些键无关。 + /// 判定完全没变时这里**直接返回**：不动窗口、不打日志。判据是 + /// [`corner::needs_redispatch`]（纯函数，有「同一策略 N 次只记 1 行」的测试）， + /// 指纹只含「策略 / 来源 / 原因码 / 有没有句柄」，不含只有真下发才拿得到的读数。 + /// + /// 没有句柄时**也打日志**（`window=none`）：不能让「没生效」只体现为屏幕上没变化。 + /// 句柄从无到有会让指纹变化 ⇒ 首次拿到 HWND 时必然重下一次。 + pub(crate) fn apply_window_corner(&mut self, context: &str) { + let policy = self.appearance.window_corner(); + let plan = platform::plan_corner( + policy, + platform::current_windows_version(), + self.appearance.backend, + ); + // 整窗 α < 1 ⇒ `window_alpha::dispatch` 会给窗口补 `WS_EX_LAYERED`；系统因此忽略圆角请求 + // （tower 裁定 A / D47）。这里只记**事实**：α 是否把我们自己的分层位打开了。 + let alpha_layered = self.appearance.window_opacity < 1.0; + let suppressed_by = alpha_layered.then_some("window_alpha"); + let next = CornerApplied::new(policy, &plan, self.hwnd.is_some(), alpha_layered); + if !corner::needs_redispatch(self.corner_applied.as_ref(), &next) { + return; + } + self.corner_applied = Some(next); + + // 行的形状只有一处（`corner::format_line`），因为那里能在没有窗口的环境里被单测钉住。 + // 关键的三栏必须在同一行：`pref=`（请求发出去了）、`layered=`（分层位在不在，来自 + // 整窗 α）、`frame=`（窗口形状 = `overlapped`，不是 `popup`）——否则以后只能猜是哪一条。 + let (outcome, style) = match self.hwnd { + Some(hwnd) => (apply_corner(hwnd, &plan).describe(), style_summary(hwnd)), + None => ( + CornerOutcome::NoWindow.describe(), + "frame=? layered=?".to_owned(), + ), + }; + eprintln!( + "{}", + corner::format_line(context, &plan, policy, &outcome, &style, suppressed_by) + ); + } +} diff --git a/crates/app-iced/src/app/update/boot_env.rs b/crates/app-iced/src/app/update/boot_env.rs new file mode 100644 index 0000000..65690a9 --- /dev/null +++ b/crates/app-iced/src/app/update/boot_env.rs @@ -0,0 +1,26 @@ +//! 启动期的取证环境变量解析（`ULL_START_ROUTE`）。 +//! +//! 从 `app/update.rs` 原样搬出（那个文件在 M105/M106/M109/M113 之后贴着 400 行硬线）： +//! **纯函数、无状态**，只是取值表长到了七条。 + +use unlucky_presenter::router::Route; + +/// 取证开关 `ULL_START_ROUTE` 的取值解析（`settings` / `instances` / `download` / `content` / `logs`）。 +/// +/// 为什么是环境变量：`crates/app-iced/src/cli.rs` 不在 M93 的 scope，而外观矩阵必须在**设置页**上 +/// 出图。语义与 `ULL_APPEARANCE_*` / `ULL_TICK_TRACE` 一致：只影响这一次进程。 +pub(super) fn env_start_route() -> Option { + match std::env::var("ULL_START_ROUTE").ok()?.trim() { + "instances" => Some(Route::Instances), + "download" => Some(Route::Download), + "logs" => Some(Route::Logs), + "settings" => Some(Route::Settings), + // M104：AI 独立页也要能直达（三态矩阵的 Detached 那张） + "agent" => Some(Route::Agent), + // M109：内容库（截图矩阵要能直达；页面内的四条侧栏不在路由里） + "content" => Some(Route::Content), + // M114：账户页的 D30 矩阵要能直达（`cli.rs` 不在本 mission 的 scope） + "accounts" => Some(Route::Accounts), + _ => None, + } +} diff --git a/crates/app-iced/src/app/update/clock.rs b/crates/app-iced/src/app/update/clock.rs new file mode 100644 index 0000000..b36909e --- /dev/null +++ b/crates/app-iced/src/app/update/clock.rs @@ -0,0 +1,143 @@ +//! 节拍：推进一拍 / 派发指令 / 抽干事件（M119 从 `update.rs` 拆出来守 400 行硬线；纯搬不改）。 +//! +//! ## 为什么这三件必须在一起 +//! +//! `advance` → `pump` → `apply` → `refresh_view` 是同一条链：时间推进、事件抽干、状态落地、 +//! 视图重建。拆开看每一段都无害，合起来才是「presenter 的异步事件在 UI 侧怎么被消费」的答案。 +//! +//! ## 两个时钟的相位（M90 r3 / P2-2 的老账，代码里有细节） +//! +//! | 场景 | 时钟 | 周期 | +//! |---|---|---| +//! | 截图 / 有 Busy-Running 实例 / 有 toast / 派发后 3 s 观察窗 | `window::frames()` + 闸门 | 33 ms | +//! | 其余（空闲） | `Heartbeat` 自续链 | 1 s | +//! +//! ## M119 增加了什么 +//! +//! [`App::pump`] 里多了一行 [`App::drain_agent`]：AI 助手的事件队列和 core 的事件队列同拍抽干， +//! 于是「右栗的未读/流式状态」和页面快照共享同一个刷新节奏（不会一个 30 Hz、一个 1 Hz）。 + +use std::time::{Duration, Instant}; + +use unlucky_presenter::dto::AppCommand; +use unlucky_presenter::theme::CONFIG_POLL_TICKS; + +use super::super::state::TICK_MS; +use super::*; + +impl App { + /// 推进一拍：后端消化时间 → 抽干事件 → 过期 toast → 偶发重读配置文件。 + /// + /// `elapsed` 是真实流逝时间（毫秒级抖动是正常的：`MockBackend` 的脚本按累计时长走）。 + pub(in crate::app) fn advance(&mut self, elapsed: Duration) { + self.backend.tick(elapsed); + self.pump(); + + self.state + .toasts + .expire(u64::try_from(elapsed.as_millis()).unwrap_or(u64::MAX)); + + // 设备码/授权码的倒计时（M114）：等待态每秒都要重画一次，否则「剩 900s」永远不动， + // 用户会以为卡死了——这正是任务里「不得只转圈」的那一条。 + if self.state.device_login.phase == unlucky_presenter::dto::DeviceLoginPhase::Waiting { + self.view_dirty = true; + } + // `ticks` 的单位是**33 ms 的一拍**，不是「advance 被调了几次」：空闲心跳一次跨 1 s， + // 要记 30 拍，这样 `theme::config_poll_due`（30 拍 ≈ 1 秒）在两种时钟下语义一致。 + let ticks = elapsed.as_millis().div_euclid(u128::from(TICK_MS)); + let ticks = u64::try_from(ticks).unwrap_or(u64::MAX).max(1); + let bucket_before = self.ticks / 30; + self.ticks += ticks; + let bucket_after = self.ticks / 30; + + // 外部（AI / CLI）改了配置文件：主题跟着换，其余外观项等玻璃/背景 mission。 + // + // 判据用**跨越**而不是 presenter 的 `config_poll_due(ticks)`（整除）：两个时钟的相位不同 + // （帧节拍按 33 ms 累加、空闲心跳按 30 拍累加），整除判定一旦错过一次就**再也命中不了** + // ——实测 ticks=137 之后每拍 +30 永远不整除，配置轮询静默死掉。间隔真源仍是 + // `CONFIG_POLL_TICKS`（30 拍 × 33 ms ≈ 1 秒）。截图通道不轮询（D30 可复现）。 + let poll_due = self.ticks >= self.config_due_at; + if poll_due { + // 追到「当前 ticks 之后的第一个间隔点」，避免心跳把相位拖飞 + self.config_due_at = self.ticks + CONFIG_POLL_TICKS; + } + let reloaded = + !self.has_screenshot() && poll_due && self.bridge.reload_if_changed().is_some(); + if reloaded { + eprintln!("[settings] 配置文件变了，重读主题 + 外观"); + self.apply_config_theme(); + // M93：外观也热切（面板 α / 背景图 / 配色来源 / 整窗 α 都在里面）。 + self.reload_appearance(); + } + + if self.view_dirty { + self.refresh_view(); + } + + // 取证开关（`ULL_TICK_TRACE=1`）：每跨过 30 拍（≈1 秒）打一行。 + // 忙碌态由帧节拍跨桶（≈1 行/秒），空闲态由心跳一次 +30 跨桶（**也是 1 行/秒**）—— + // 两种时钟都用同一把尺子，所以 trace 的密度本身就是「时钟在跑」的证据。 + if bucket_after != bucket_before && std::env::var_os("ULL_TICK_TRACE").is_some() { + eprintln!( + "[tick] n={} frames={} refreshes={} clock={}", + self.ticks, + self.frames, + self.refreshes, + if self.needs_frames() { + "frames" + } else { + "idle-1hz" + } + ); + } + } + + /// 派发一条指令并**立刻**抽干它带出来的事件（不本地回显，等价于 Slint 版的 `dispatch`）。 + pub(in crate::app) fn dispatch(&mut self, command: AppCommand) { + self.backend.dispatch(command); + // 观察窗：命令发出后 3 秒内保持帧订阅，等后端把第一条事件交回来 + // （真 host 是异步的，派发瞬间状态还没变；不设这个窗口，空闲态的帧订阅永远不会打开）。 + self.watch_until = Some(Instant::now() + WATCH_WINDOW); + self.pump(); + } + + /// 抽干事件队列并逐条 `apply`（**唯一**的状态写入口）。 + pub(in crate::app) fn pump(&mut self) { + // M119：AI 助手的事件队列与 core 的事件队列**同拍**抽干（顺序无关：两个队列互不依赖）。 + // 抽出来的这批事件经 `Message::Agent(Events)` 回流，见 `update/agent.rs`。 + self.drain_agent(); + + let events = self.backend.drain_events(); + if events.is_empty() { + return; + } + for event in events { + self.state.apply(event); + } + self.view_dirty = true; + self.auto_select(); + self.refresh_view(); + } + + /// 首屏快照到位后**自动选中第一行**（桌面 list-detail 的惯例：右栏不该开局就是空的）。 + /// + /// 只做一次：用户点「返回」回到列表后，再刷新实例列表也不会把他弹回详情页。 + /// 选中这件事走的是 `AppState::navigate`（路由栈），不是本地选中字段——于是「当前选中」 + /// 永远等于「路由栈顶」，用户点返回时栈语义自然成立。 + pub(in crate::app) fn auto_select(&mut self) { + if self.auto_selected || self.state.route() != &Route::Instances { + return; + } + let Some(first) = self + .state + .tiles() + .first() + .map(|cell| cell.instance.id.clone()) + else { + return; + }; + self.auto_selected = true; + self.state.navigate(Route::Detail(first)); + self.view_dirty = true; + } +} diff --git a/crates/app-iced/src/app/update/content.rs b/crates/app-iced/src/app/update/content.rs new file mode 100644 index 0000000..230f229 --- /dev/null +++ b/crates/app-iced/src/app/update/content.rs @@ -0,0 +1,339 @@ +//! 内容库页的消息落点（M109）：`pages::Message::Content(..)` 的穷尽分发。 +//! +//! ## 两件事分开（与 `update/download.rs` 同一条纪律） +//! +//! | 意图 | 谁改状态 | 派指令吗 | +//! |---|---|---| +//! | 关键词草稿 / 选中项目 / 目标实例 | `App::content`（页面内选择） | 不派 | +//! | 检索条件（类型/来源/排序/版本/加载器/关键词提交/翻页/重试） | `AppState::content`（presenter） | 派 `SearchContent` | +//! | 装入 | 谁都不改 | 派 `InstallContent` | +//! +//! 「装入」不改本地状态是关键：装上的证据是 `InstallProgress` 事件回流到安装面板 +//! （`pages/download::install_panel`），页面自己不做乐观回显。 +//! +//! ## 为什么条件写进 presenter 再派 +//! +//! `AppState::content.query` 是「当前结果对应哪份条件」的唯一真相：结果回来时 +//! `apply_content` 用它判「迟到的事件要不要丢」。页面自己存一份就会有两份真相。 + +use unlucky_presenter::dto::{ + AppCommand, ContentInstallRequest, ContentQuery, ContentSource, ExportRequestView, + ImportRequestView, PackCommand, +}; + +use crate::pages::content::{Blocker, Content}; + +use super::*; + +impl App { + /// 进入内容库页时补一次检索（首个用户动作不该是「再点一下搜索」）。 + /// + /// 判据是 `AppState::content` 里还没有结果、也没有请求在飞：重复进出不重复打网络。 + pub(super) fn ensure_content_loaded(&mut self) { + if self.state.content.results.is_some() || self.state.content.pending { + return; + } + let query = ContentQuery::first(self.content.kind); + self.search_content(query); + } + + /// 页面消息（穷尽分发：漏一支报 E0004）。 + pub(super) fn on_content(&mut self, message: pages::content::Message) -> Task { + match message { + pages::content::Message::SetKind(kind) => { + // 换类型 = 换一份条件（facet 全变）：选中项作废，条件回到该类型的首页 + self.content.kind = kind; + self.content.selected = None; + let mut query = ContentQuery::first(kind); + // 保留用户已经选好的来源/排序/版本/加载器：换成默认值会让筛选条自己跳回去 + query.source = self.state.content.query.source; + query.sort = self.state.content.query.sort; + query.game_version = self.state.content.query.game_version.clone(); + query.loader = self.state.content.query.loader; + self.search_content(query); + } + pages::content::Message::QueryChanged(text) => { + self.content.draft = text; + self.view_dirty = true; + } + pages::content::Message::Search => { + let mut query = self.state.content.query.clone(); + query.text = self.content.draft.trim().to_string(); + query.offset = 0; + self.search_content(query); + } + pages::content::Message::SetSource(source) => { + if source == ContentSource::Curseforge && !self.curseforge_available() { + // 筛选条那条本来就是禁用的；这里再挡一次（防绕过 UI 的消息） + return Task::none(); + } + self.with_query(|query| query.source = source); + } + pages::content::Message::SetSort(sort) => self.with_query(|query| query.sort = sort), + pages::content::Message::SetVersion(version) => { + self.with_query(|query| query.game_version = version); + } + pages::content::Message::SetLoader(loader) => { + self.with_query(|query| query.loader = loader) + } + pages::content::Message::Select(id) => { + self.content.selected = Some(id); + self.view_dirty = true; + } + pages::content::Message::SetTarget(id) => { + self.content.target = Some(id); + self.view_dirty = true; + } + pages::content::Message::LoadMore => { + let next = self.state.content.query.next_page(); + self.search_content(next); + } + pages::content::Message::Retry => { + let mut query = self.state.content.query.clone(); + query.offset = 0; + self.search_content(query); + } + pages::content::Message::Install => { + if let Some(request) = self.content_install_request() { + self.dispatch(AppCommand::InstallContent(Box::new(request))); + } + } + // M113: import/export —— 导入/导出区（细节在 `on_pack`） + pages::content::Message::Pack(message) => self.on_pack(message), + } + Task::none() + } + + /// 导入/导出区的消息（M113）。 + /// + /// 两条口径： + /// + /// 1. **页内选择改本地状态**（路径草稿 / 目标实例 / 格式 / 包名 / 展开的冲突）—— + /// 它们不属于业务状态，不进 presenter（同 `QueryChanged` 的处理）； + /// 2. **意图只派指令，不做乐观回显**（导入 / 预检 / 确认写盘 / 关面板）：进度、报告、预检结果 + /// 全部由 `CoreEvent::Pack` 回来（`dto::pack::event` 的 `PackState::apply` 是唯一写入点）。 + pub(super) fn on_pack(&mut self, message: pages::content::PackMessage) { + use pages::content::PackMessage; + match message { + PackMessage::Dropped(path) => { + // 拖进来的包属于「整合包」这一类：顺手把类型切过去，否则这一块根本不在屏上 + self.content.kind = unlucky_presenter::dto::ContentKind::Modpack; + self.content.pack.draft = path.display().to_string(); + self.content.pack.hover = false; + self.view_dirty = true; + } + PackMessage::Hover(hover) => { + self.content.pack.hover = hover; + self.view_dirty = true; + } + PackMessage::PathChanged(path) => { + self.content.pack.draft = path; + self.view_dirty = true; + } + PackMessage::SetInstance(instance) => { + self.content.pack.instance = instance; + self.view_dirty = true; + } + PackMessage::SetInstanceName(name) => { + self.content.pack.instance_name = name; + self.view_dirty = true; + } + PackMessage::SetFormat(format) => { + self.content.pack.format = format; + self.view_dirty = true; + } + PackMessage::SetExportName(name) => { + self.content.pack.export_name = name; + self.view_dirty = true; + } + PackMessage::SetExportVersion(version) => { + self.content.pack.export_version = version; + self.view_dirty = true; + } + PackMessage::SetOutput(path) => { + self.content.pack.output = path; + self.view_dirty = true; + } + PackMessage::ToggleConflict(path) => { + self.content.pack.expanded = if self.content.pack.expanded.as_deref() == Some(&path) + { + None + } else { + Some(path) + }; + self.view_dirty = true; + } + PackMessage::OpenExport => { + self.content.pack.export_open = true; + // 包名缺省取目标实例名（用户不该为一个名字再敲一遍键盘） + if self.content.pack.export_name.trim().is_empty() { + self.content.pack.export_name = + self.content.pack.instance.clone().unwrap_or_default(); + } + self.view_dirty = true; + } + PackMessage::AbortExport => { + self.content.pack.export_open = false; + // 连预检结果一起清：留着会让用户以为「还能再点一次确认」 + self.dispatch(AppCommand::Pack(Box::new(PackCommand::Dismiss))); + self.view_dirty = true; + } + PackMessage::Dismiss => { + // 报告 / 探测诊断 / 预检都在 presenter 里：关面板 = 让 host 清掉它们 + // （`PackEvent::Cleared`），于是界面回到入口态，浏览网格重新露出来 + self.content.pack.expanded = None; + self.dispatch(AppCommand::Pack(Box::new(PackCommand::Dismiss))); + self.view_dirty = true; + } + PackMessage::Import => { + if let Some(request) = self.pack_import_request(false) { + self.dispatch(AppCommand::Pack(Box::new(PackCommand::Import(Box::new( + request, + ))))); + } + } + PackMessage::Overwrite => { + // 「以包为准重新导入」：整次导入翻成 Overwrite 档（core 只有全局档） + if let Some(request) = self.pack_import_request(true) { + self.dispatch(AppCommand::Pack(Box::new(PackCommand::Import(Box::new( + request, + ))))); + } + } + PackMessage::Cancel => { + // 与面板上那个「取消」同一个指令：host 会把导入的取消标记与代次一起处理 + self.dispatch(AppCommand::CancelInstall); + } + PackMessage::Precheck => { + if let Some(request) = self.pack_export_request() { + // 先记下「这次预检对的是哪份请求」，确认写盘时原样发回 + self.state.pack.set_export_request(request.clone()); + self.view_dirty = true; + self.dispatch(AppCommand::Pack(Box::new(PackCommand::Export(Box::new( + request, + ))))); + } + } + PackMessage::Confirm => { + if let Some(request) = self.state.pack.export.request.clone() { + self.dispatch(AppCommand::Pack(Box::new(PackCommand::Confirm(Box::new( + request, + ))))); + } + } + } + } + + /// 组一份导入请求（路径草稿 → DTO）。草稿为空 ⇒ `None`（按钮不该发指令）。 + /// + /// `overwrite` 只有「以包为准重新导入」会给 `true`；默认路径永远是 `false` + /// （core 那边就是 `ConflictPolicy::KeepUser`，**绝不默认覆盖用户改过的文件**）。 + fn pack_import_request(&self, overwrite: bool) -> Option { + let draft = self.content.pack.draft.trim(); + if draft.is_empty() { + return None; + } + let name = self.content.pack.instance_name.trim(); + Some(ImportRequestView { + pack: std::path::PathBuf::from(draft), + instance: self.content.pack.instance.clone(), + instance_name: (!name.is_empty()).then(|| name.to_string()), + overwrite, + }) + } + + /// 组一份导出请求（预检与写盘**共用同一份**，确认时原样发回）。 + /// + /// 没有选中实例就没有导出对象 ⇒ `None`。**「Save to」必须真的进请求** + /// （复审 r1 P1-1：以前这里硬编码 `target: None`，那个输入框是死的）。 + fn pack_export_request(&self) -> Option { + 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) + } + + /// 组一份内容库的「装入」请求；闸门与页面上的按钮**同一个判据**（`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) { + eprintln!("[content] 装入被挡下：{reason}"); + } + if model.blockers.contains(&Blocker::NeedsPipeline) { + eprintln!("[content] 整合包装入未实现（M111）"); + } + return None; + } + let hit = model.selected_hit()?; + let target = model + .targets + .iter() + .find(|target| Some(&target.id) == model.target.as_ref())?; + Some(ContentInstallRequest { + project: hit.id.clone(), + title: hit.title.clone(), + // 整合包走不到这里：`ContentKind::Modpack` 的 `dir()` 是 `None` ⇒ 必然带 + // `Blocker::NeedsPipeline` ⇒ `can_install()` 为假。所以这里就是「单文件」那一类。 + kind: model.kind, + source: hit.source, + instance: target.id.clone(), + game_version: target.mc_version.clone(), + loader: target.loader, + }) + } +} diff --git a/crates/app-iced/src/app/update/download.rs b/crates/app-iced/src/app/update/download.rs new file mode 100644 index 0000000..cff3c40 --- /dev/null +++ b/crates/app-iced/src/app/update/download.rs @@ -0,0 +1,381 @@ +//! 下载页在 app 层的那几支（M94；M105 补上安装选项）。 +//! +//! 为什么单独一个文件：M93（外观三件套接线）合入后 `update.rs` 已经贴到 400 行，下载页再往里塞 +//! 几个 arm 就顶破硬线；拆出来是既不动 M93 的代码、又能守住 ≤400 的办法（`app/update/**` 属本 +//! mission scope）。 +//! +//! ## 各支各自的纪律（M105 后的口径） +//! +//! | 消息 | 落点 | 为什么 | +//! |---|---|---| +//! | [`pages::Message::SelectVersion`] | 只改**草稿** | 选中是页面内状态，不是业务命令；顺手清掉加载器版本（换了原版版本，旧版本号几乎必然不适用） | +//! | [`pages::Message::SetLoader`] | 改草稿 + 必要时派 `ListLoaderVersions` | 加载器版本列表来自官方元数据，页面不能自己编 | +//! | [`pages::Message::SetLoaderVersion`] / `SetInstanceName` | 只改草稿 | 纯输入 | +//! | [`pages::Message::InstallVersion`] | `AppCommand::CreateInstance(草稿)` | **确认才开工**（带加载器 / 加载器版本 / 实例名） | +//! | [`pages::Message::CancelInstall`] | `AppCommand::CancelInstall` | 见 `host/dispatch.rs`：真停 + 作废旧代次 | +//! | [`pages::Message::SetCategory`] | 写分类 → 重建 → `AppCommand::ListVersions` | 见下 | +//! +//! [「刷新下载源」](pages::Action::RefreshSources) 也在这里：它不是占位动作，具体分类 → 重拉该分类、 +//! 「全部」→ 让 host 重扫一遍（`RefreshAll`）。 +//! +//! ## 分类为什么既写视图模型、又派指令 +//! +//! 真 host 的 `AppCommand::ListVersions(_)` 会丢掉分类参数、回全量清单（复审 P2-1），所以**过滤在 +//! 本页做**：写进视图模型 → 立刻 `refresh_view()`（它会把 category 带回去、按同一谓词过滤行）→ +//! 再派指令。这不是「乐观回显」：写的是**过滤条件本身**，chip 与列表用同一个 +//! [`Category::matches`](crate::pages::Category)，于是不可能出现「chip 说正式版、列表是全量」的两份真相。 +//! +//! ## 草稿为什么住在这里而不是页面模型里 +//! +//! `refresh_view()` 每次事件都把 `self.view` 整棵重建（连安装进度都算），页面存不住「用户正在填、 +//! 还没确认」的东西。于是草稿放 `App::download_draft`，与分类筛选同一个做法： +//! 改草稿 → `view_dirty = true` → `refresh_view()`。 + +use unlucky_presenter::dto::CreateRequest; + +use super::*; + +impl App { + /// 下载页的消息。**处理了返回 `true`**（`on_page` 里就不用再写一遍这些 arm）。 + pub(super) fn on_download(&mut self, message: &pages::Message) -> bool { + match message { + pages::Message::SelectVersion(id) => { + if self.download_draft.selected.as_deref() != Some(id.as_str()) { + // 换了原版版本：加载器版本是**按 (加载器, 原版版本)** 取的（见 + // `CoreEvent::LoaderVersions` 的缓存键），旧的版本号留着只会误导。 + self.download_draft.loader_version.clear(); + } + self.download_draft.selected = Some(id.clone()); + self.mark_download_dirty(); + // 选了加载器版本之后换原版版本，列表要跟着换——已经查过的直接从快照读，不重复派。 + self.ensure_loader_versions(); + } + pages::Message::SetLoader(loader) => { + self.download_draft.loader = *loader; + self.download_draft.loader_version.clear(); + self.mark_download_dirty(); + self.ensure_loader_versions(); + } + pages::Message::SetLoaderVersion(version) => { + self.download_draft.loader_version = version.clone(); + self.mark_download_dirty(); + } + pages::Message::SetInstanceName(name) => { + self.download_draft.instance_name = name.clone(); + self.mark_download_dirty(); + } + pages::Message::InstallVersion(id) => { + // 防守：按钮带的是**页面上那一行**的 id，草稿里的选中项理论上与它一致； + // 万一不一致（例如列表刚换过、用户手快），不能让 A 版本的加载器版本落到 B 版本上。 + if self.download_draft.selected.as_deref() != Some(id.as_str()) { + self.download_draft.selected = Some(id.clone()); + self.download_draft.loader_version.clear(); + } + let request = self.install_request(id); + self.dispatch(AppCommand::CreateInstance(request)); + } + pages::Message::CancelInstall => self.dispatch(AppCommand::CancelInstall), + pages::Message::SetCategory(category) => { + self.view.download.category = *category; + self.view_dirty = true; + self.refresh_view(); + if let Some(kind) = category.command() { + self.dispatch(AppCommand::ListVersions(kind)); + } + } + // M107：查询词落在快照里（无状态视图的唯一存活方式），再走同一条重建路径过滤。 + pages::Message::SetVersionQuery(query) => { + self.rebuild_after_query(query.clone()); + } + pages::Message::ClearVersionQuery => { + self.rebuild_after_query(String::new()); + } + // M107：主版本桶的选中是纯视图态，不重建、不派命令（同 `SelectVersion`）。 + // + // **搜索期间点桶 = 「我就是要看这个桶」**（复审 r2 P2-1(b)）：搜索让第二级失效（P2-1 的 + // 一致性放宽），如果这里只改选择而不清查询，用户会看到「点了没反应、清空搜索后才生效」 + // 的活控件。所以搜索中点桶顺带退出搜索，按新桶过滤——一次点击做完用户想要的两件事。 + pages::Message::SelectMajor(key) => { + if self.view.download.has_query() { + // 先退出搜索再落选择：`rebuild_after_query` 会用**全量行**重算桶并回填选择 + // （它带回 `selected_major`，且校验桶仍存在）。 + self.view.download.selected_major = key.clone(); + self.rebuild_after_query(String::new()); + } else { + self.view.download.selected_major = key.clone(); + } + } + // M107：类型栏的手动折叠也是纯视图态。 + pages::Message::ToggleTypeRail => { + self.view.download.type_rail_folded = !self.view.download.type_rail_folded; + } + pages::Message::Action(pages::Action::RefreshSources) => { + match self.view.download.category.command() { + Some(kind) => self.dispatch(AppCommand::ListVersions(kind)), + None => self.dispatch(AppCommand::RefreshAll), + } + } + _ => return false, + } + true + } + + /// 改草稿之后统一走这一条：置脏 + 立刻重建（不等下一拍，点了就有反应）。 + fn mark_download_dirty(&mut self) { + self.view_dirty = true; + self.refresh_view(); + } + + /// 确认安装时的 `CreateRequest`（草稿 → 指令载荷）。 + /// + /// 实例名留空就让 core 用版本号（`CreateRequest::instance_name` 的既有口径）， + /// 所以这里**不**自己拼一个默认名——两处各拼一份迟早会漂。 + fn install_request(&self, id: &str) -> CreateRequest { + let draft = &self.download_draft; + CreateRequest { + name: draft.instance_name.trim().to_string(), + version: id.to_string(), + loader: draft.loader.kind(), + loader_version: draft.loader_version.trim().to_string(), + } + } + + /// 当前草稿需要加载器版本列表、而快照里还没有时，派一次查询。 + /// + /// 判据是 `state.loader_versions_for(...)` 的 `None`（= 没查过）：查过的（成功或失败）都不再重复派， + /// 失败要重试走 `RefreshSources` 那条路，页面上的红色原因行不会因为一次点击就消失。 + fn ensure_loader_versions(&mut self) { + let loader = self.download_draft.loader; + if loader == pages::Loader::Vanilla { + return; + } + let Some(version) = self.download_draft.selected.clone() else { + return; + }; + // 静态就不支持的组合不联网（否则只会换来一条「取不到」的假原因；真正的原因是 + // 「这个加载器没有这个版本的构建」，页面已经用静态规则说清了）。 + let kind = self + .state + .versions + .iter() + .find(|summary| summary.id == version) + .map(|summary| summary.kind); + if let Some(kind) = kind { + if loader.supports(&version, kind).is_err() { + return; + } + } + if self + .state + .loader_versions_for(loader.kind(), &version) + .is_some() + { + return; + } + self.dispatch(AppCommand::ListLoaderVersions { + kind: loader.kind(), + mc_version: version, + }); + } + + /// 搜索词变了：写进快照 → 重建视图 → **把纯视图态捡回来**。 + /// + /// `refresh_view()` 整块换掉 `self.view`，而它只把 `category` 与**安装草稿**带回去（`app/state.rs` + /// 归 M105/M106）。所以「折叠状态」与「选中的主版本桶」必须在重建前后自己搬一次——否则用户敲第一个 + /// 字符，展开着的类型栏就自己收起来、选中的主版本也跳回「全部」。 + /// 「搜索时侧栏保留当前位置」这条要求，落点就是这里的四行。 + fn rebuild_after_query(&mut self, query: String) { + self.state.download_query = query; + let major = self.view.download.selected_major.take(); + let folded = self.view.download.type_rail_folded; + self.view_dirty = true; + self.refresh_view(); + // 回填要**校验**：桶是按当前行聚合法出来的，新桶列表里没有的那个选择不该被复活 + // （复审 P2-1(a)：否则会出现「侧栏没有任何一项点亮」的幽灵选中）。 + self.view.download.selected_major = major.filter(|key| { + self.view + .download + .buckets + .iter() + .any(|bucket| bucket.key.as_deref() == Some(key.as_str())) + }); + self.view.download.type_rail_folded = folded; + } +} + +#[cfg(test)] +mod tests { + //! 搜索链路的**端到端**断言（复审 P2-5）。 + //! + //! 为什么非要在 app 层写：这条链是 `Message → on_page → on_download → AppState.download_query + //! → refresh_view → from_snapshot 过滤`，中间任何一环断掉，页面层测试都看不见（页面只拿到 + //! 已经过滤好的模型）。复审原话：「把 `rebuild_after_query` 第一行删掉，现有测试全绿，而搜索 + //! 变成假控件」——这几条就是补那个洞的。 + + use std::cell::RefCell; + use std::rc::Rc; + + use unlucky_presenter::dto::{AppEvent, Backend, CoreEvent, VersionKind, VersionSummary}; + use unlucky_presenter::settings_bridge::SettingsBridge; + + use super::*; + + /// 只记账、不回事件的后端（同 `app/update/download_wiring.rs`）：命令出了 UI 层，状态一个字节 + /// 都不许变——否则「本地乐观回显」与「事件回流」终态相同，断言会假绿。 + struct Recorder(Rc>>); + + 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/page_messages.rs b/crates/app-iced/src/app/update/page_messages.rs new file mode 100644 index 0000000..2247c88 --- /dev/null +++ b/crates/app-iced/src/app/update/page_messages.rs @@ -0,0 +1,232 @@ +//! 页面消息的落点（`on_page`）：解 M94 冲突时从 `update.rs` 拆出来。 +//! +//! 为什么拆：`main` 上 `update.rs` 已经 **397 行**（M94 自己也是因此把下载页四支拆到 +//! `update/download.rs`），日志页再往里塞「剪贴板 + 清日志」两支就顶破 400 硬线。 +//! 与 M94 同一种做法：`app/update/**` 属本 mission scope。 +//! +//! ## 穷尽性（M94 复审的 p3，本轮收掉） +//! +//! 这里是全 crate **唯一**对 [`pages::Message`] 的穷尽匹配点，所以**没有** `_ => {}` 兜底： +//! 谁往枚举里加变体却忘了接线，编译器立刻报 E0004。原来是 `_ => {}` + 注释「做穷尽性」—— +//! 方向正好写反了，它**取消**穷尽性，把「漏接线」变成「点了没反应」。 +//! +//! 代价：由前置分支（`on_download` / 本文件里的剪贴板分支）先消费的变体，在 match 里**仍要 +//! 显式列出**。那是保住穷尽性的必要代价，也是这条守卫抓得住东西的原因。 +//! +//! ## 边界（抓得住什么 / 抓不住什么） +//! +//! - 抓得住：**加一个 `pages::Message` 变体却没接线** → 编译失败（E0004），不会静默； +//! - 抓不住：加一个 `pages::Action` 变体 —— 它落进 `Action(action)` 的占位分支（打印一行 +//! `[page] 占位动作 …`），编译期不会报。这是占位期的既有设计，不是本文件能守的。 + +use unlucky_i18n::{Lang, LangChoice}; + +use crate::pages; +use crate::ui::lang::LangState; + +use super::*; + +// --------------------------------------------------------------- 界面语言（M106） +// +// 这三个方法住在本文件而不是 `app/state.rs`：`state.rs` 贴着 400 行硬线（M104 的 `agent`、 +// M105 的 `download_draft` 都往那儿长），而 `set_language` 的唯一调用点就是本文件的 +// `pages::Message::Language` 分支——落点与调用点放一起，读的人不用来回跳。 +// 与 M93 把 appearance 那批 `App` 方法放进 `app/appearance.rs` 是同一手法。 + +impl App { + /// 页面消息：导航走路由栈，真业务命令派发，纯视图态改本地呈现。 + pub(super) fn on_page(&mut self, message: pages::Message) -> Task { + // 下载页的四支（含「刷新下载源」）在 `update/download.rs`：`update.rs` 早已贴 400 行 + if self.on_download(&message) { + return Task::none(); + } + + match message { + pages::Message::Navigate(route) => { + // M109：进内容库时补一次检索（首个动作不该是「再点一下搜索」）。 + // 判据在 `ensure_content_loaded` 里（已有结果/请求在飞就不重复打网络）。 + let entering_content = route == Route::Content; + self.state.navigate(route); + self.view_dirty = true; + self.refresh_view(); + if entering_content { + self.ensure_content_loaded(); + } + } + pages::Message::Launch(id) => self.dispatch(AppCommand::LaunchInstance(id)), + pages::Message::Stop(id) => self.dispatch(AppCommand::StopInstance(id)), + pages::Message::Appearance(change) => self.on_appearance(change), + // M101：设置页的四条填页线共用一个投递口；组内变体在 `update/settings.rs` 里穷尽分发 + // （那一层没有 `_ =>`，见本文件末尾与 `update/settings/tests.rs` 的两条守门） + pages::Message::Settings(group) => return self.on_settings(group), + // M106：换界面语言（落盘 + 重建视图模型；档位不是业务命令，不派 `AppCommand`）。 + // 这是**唯一**一处绕开 M101 投递口的页面消息：语言档位不是「某一组的状态」， + // 它要落盘到 `ui.language` 并重建整棵视图模型（设置页的语言行只是它的第一个出口）。 + pages::Message::Language(choice) => self.set_language(choice), + // M109：内容库那一套意图在自己的文件里穷尽分发（`update/content.rs`） + pages::Message::Content(message) => return self.on_content(message), + // M95：摘要落剪贴板（文本由页面造，这里只搬） + pages::Message::CopySummary(text) => return iced::clipboard::write(text), + // 下面四支已由 `on_download` 提前消化；显式列出而不是 `_ => {}`，见模块文档 + pages::Message::SelectVersion(_) + | pages::Message::InstallVersion(_) + | pages::Message::CancelInstall + // M105 的三支 + M107 的四支 + 分类：全部由 `on_download` 提前消化（显式列出保住穷尽性） + | pages::Message::SetLoader(_) + | pages::Message::SetLoaderVersion(_) + | pages::Message::SetInstanceName(_) + | pages::Message::SetCategory(_) + // M107 的四支同属下载页（查询 / 清空 / 主版本桶 / 折叠类型栏） + | pages::Message::SetVersionQuery(_) + | pages::Message::ClearVersionQuery + | pages::Message::SelectMajor(_) + | pages::Message::ToggleTypeRail => debug_assert!(false, "应由 on_download 消费"), + // M95：清空日志是**呈现层**操作（`log_lines` 是 presenter 的公开快照字段， + // 不派业务命令、不写持久状态） + pages::Message::Action(pages::Action::ClearLogs) => { + self.state.log_lines.clear(); + self.view_dirty = true; + self.refresh_view(); + } + // M114：账户页（三轨登录 / 列表动作 / 表单输入） + pages::Message::Account(message) => return self.on_account(message), + // 还没接后端的占位动作：只打日志（哪几个、为什么，见 pages 模块文档的偏离登记） + pages::Message::Action(action) => { + eprintln!("[page] 占位动作 {action:?} pressed（没有对应 AppCommand）"); + } + } + + Task::none() + } +} + +impl App { + /// 当前生效的界面语言（= 目录选择；页面文案一律由它派生）。 + pub(in crate::app) fn lang(&self) -> Lang { + self.lang.lang() + } + + /// 设置页语言行要的两件：档位（画选中态）+ 生效语言（画回显）。 + pub(in crate::app) fn language(&self) -> pages::Language { + self.lang.for_settings() + } + + /// 换界面语言（设置页语言行 → `pages::Message::Language`）。 + /// + /// 三件事缺一不可：①档位与结论换掉 ②视图模型重建（`view_dirty` + `refresh_view`，目录是 + /// 视图模型的一部分）③落盘（重启后保持所选语言）。字体不在这里重扫：中文档缺字体时的 + /// 判据/信号归 `i18n::font::decide` + `fonts/cjk.rs`（见报告「没验的部分」）。 + pub(in crate::app) fn set_language(&mut self, choice: LangChoice) { + if choice == self.lang.choice() { + return; + } + self.lang = LangState::of(choice); + self.lang.log(); + if !self.bridge.persist_ui_language(choice.setting_value()) { + eprintln!( + "[i18n] 语言偏好没落盘（配置只读或数据根解析不出来）：本次生效，重启会回到旧值" + ); + } + self.lang.log_cjk(); + self.view_dirty = true; + self.refresh_view(); + } +} + +#[cfg(test)] +mod tests { + use unlucky_design::color::SchemeFlavor; + use unlucky_i18n::LangChoice; + use unlucky_presenter::mock::MockBackend; + use unlucky_presenter::settings_bridge::SettingsBridge; + + use crate::app::state::App; + use crate::cli::Options; + use crate::pages; + use crate::theme::Families; + + const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", + }; + + /// 不碰磁盘的 App（mock 后端 + 内存设置桥），与 `app/tests.rs` 的 `headless` 同型。 + fn headless() -> App { + App::with_presenter( + Options::default(), + FAMILIES, + SchemeFlavor::Light, + Box::new(MockBackend::new()), + SettingsBridge::memory_only(), + ) + } + + /// M106：设置页语言行点一下 → 生效语言与视图模型都跟着换。 + /// + /// 抓得住：①`pages::Message::Language` 没接进 `on_page`（点了没反应，编译器不会报——它接得住， + /// 但接错了分支就静默）；②`set_language` 只改字段不重建视图（界面要等下一次刷新才变）； + /// ③档位与生效语言各说各话（设置页会画错选中态）。 + /// 抓不住：界面真的画成中文了没有（那要截图，见 `DevDocs/artifacts/m106/`）。 + #[test] + fn the_language_message_switches_the_catalog_and_rebuilds_the_view() { + let mut app = headless(); + assert_eq!( + app.view.lang, + app.lang(), + "首帧的视图模型要已经按生效语言建好" + ); + + let _ = app.update(crate::app::message::Message::Page( + pages::Message::Language(LangChoice::Fixed(unlucky_i18n::Lang::ZhCn)), + )); + assert_eq!(app.lang(), unlucky_i18n::Lang::ZhCn); + assert_eq!(app.view.lang, unlucky_i18n::Lang::ZhCn, "目录要跟着换"); + assert_eq!( + app.language(), + pages::Language { + choice: LangChoice::Fixed(unlucky_i18n::Lang::ZhCn), + effective: unlucky_i18n::Lang::ZhCn, + } + ); + + let refreshes = app.refreshes; + let _ = app.update(crate::app::message::Message::Page( + pages::Message::Language(LangChoice::Fixed(unlucky_i18n::Lang::En)), + )); + assert_eq!(app.view.lang, unlucky_i18n::Lang::En); + assert_eq!(app.refreshes, refreshes + 1, "换语言要重建一次视图模型"); + + // 同一档再点一次：什么都不该发生（不白重建） + let refreshes = app.refreshes; + let _ = app.update(crate::app::message::Message::Page( + pages::Message::Language(LangChoice::Fixed(unlucky_i18n::Lang::En)), + )); + assert_eq!(app.refreshes, refreshes, "同一档不该再重建"); + } + + /// 抓得住：有人给 `on_page` 的 match 重新加 `_ => {}` 兜底 —— 那正是 M94 复审的 p3： + /// 兜底让「加了变体忘了接线」从**编译错误**退化成「点了没反应」，这条测试把它拽回来。 + /// 抓不住：别的兜底写法（把 match 拆成 if-else 链、给子枚举加通配之后再漏变体）， + /// 也抓不住「加了变体但接错分支」——那两条只有编译器和人读得出来。 + #[test] + fn the_page_match_has_no_wildcard_fallback() { + let source = include_str!("page_messages.rs"); + let wildcards: Vec<(usize, &str)> = source + .lines() + .enumerate() + .filter(|(_, line)| { + let trimmed = line.trim(); + trimmed.starts_with("_ =>") || trimmed.starts_with("_=>") + }) + .map(|(index, line)| (index + 1, line)) + .collect(); + + assert!( + wildcards.is_empty(), + "on_page 里出现了 `_ =>` 兜底（行 {:?}）：它会取消对 pages::Message 的穷尽性，\ + 新变体漏接线时编译器不再报 E0004", + wildcards + ); + } +} diff --git a/crates/app-iced/src/app/update/settings.rs b/crates/app-iced/src/app/update/settings.rs new file mode 100644 index 0000000..5cd00f8 --- /dev/null +++ b/crates/app-iced/src/app/update/settings.rs @@ -0,0 +1,55 @@ +//! 设置页分组消息的**二级分发**（M101 `SETTINGSMSG`）： +//! `pages::Message::Settings(GroupMessage)` → 四条填页线各自的 handler。 +//! +//! ## 为什么分两级 +//! +//! `app/update/page_messages.rs` 对 [`pages::Message`] 做穷尽匹配（没有 `_ =>`，有 +//! `the_page_match_has_no_wildcard_fallback` 守门）。设置页的四条填页线若各自往 `pages::Message` +//! 里加变体，就都得改那个文件——四路并行必然冲突。M101 把它们收进一个投递口 +//! `pages::Message::Settings(GroupMessage)`，本文件再把 `GroupMessage` 分给四条线： +//! +//! ```text +//! GroupMessage::Java(m) → settings/java.rs +//! GroupMessage::Download(m) → settings/download.rs +//! GroupMessage::LanguageAppearance(m) → settings/language_appearance.rs +//! GroupMessage::AiAbout(m) → settings/ai_about.rs +//! ``` +//! +//! ## 穷尽性：抓得住什么 / 抓不住什么 +//! +//! - **抓得住**：某条线给 `GroupMessage` 加了载荷变体（= 在自己文件里加了一支消息）却忘了在本 +//! match 里接线 → **E0004**；四个 handler 里对空枚举的 `match message {}` 一旦有人写成 +//! `_ => {}`，`the_group_dispatch_has_no_wildcard_fallback` 会红（兜底会把「漏接线」从编译 +//! 错误降级成「点了没反应」，`page_messages.rs` 的同类守卫是这么写的，这里照抄）。 +//! - **抓不住**：handler 忽略自己的消息（`let _ = message; Task::none()`）、两个 handler 身体写反 +//! 或写成一样——类型对得上就编得过，只有人读能看出来。也因此「接错了组」的一半是编译期兜住的 +//! （载荷类型不同 ⇒ 编不过），另一半（接了个空壳）不是。 +//! +//! ## 加一支设置页消息要改哪 +//! +//! 自己那条线的两个文件：消息口（`pages/settings/<线>.rs`）+ 落点（本目录 `<线>.rs`）。 +//! 本文件的 match 只在 `GroupMessage` **加变体**时才动，而那意味着新增一条线，不是加一支消息。 + +use super::*; + +impl App { + /// 设置页的分组消息：分给四条线各自的文件，本文件不认识任何一支具体消息。 + pub(super) fn on_settings(&mut self, message: pages::settings::GroupMessage) -> Task { + match message { + pages::settings::GroupMessage::Java(message) => self.on_settings_java(message), + pages::settings::GroupMessage::Download(message) => self.on_settings_download(message), + pages::settings::GroupMessage::LanguageAppearance(message) => { + self.on_settings_language_appearance(message) + } + pages::settings::GroupMessage::AiAbout(message) => self.on_settings_ai_about(message), + } + } +} + +mod ai_about; +mod download; +mod java; +mod language_appearance; + +#[cfg(test)] +mod tests; diff --git a/crates/app-iced/src/app/update/settings/ai_about.rs b/crates/app-iced/src/app/update/settings/ai_about.rs new file mode 100644 index 0000000..4ac6bb3 --- /dev/null +++ b/crates/app-iced/src/app/update/settings/ai_about.rs @@ -0,0 +1,17 @@ +//! AI / About 分组消息的落点（M101 `SETTINGSMSG`）：**只归 ai+about 线**。 +//! +//! 消息口在 `pages/settings/ai_about.rs`（`pages::settings::ai_about::Message`）。 +//! +//! 首版是空枚举上的 `match message {}`：这是**穷尽**的写法（不是兜底），加了变体不接线就报 E0004。 + +use super::super::*; + +impl App { + /// AI / About 分组的一条消息。首版没有可处理的东西（空枚举）。 + pub(super) fn on_settings_ai_about( + &mut self, + message: pages::settings::ai_about::Message, + ) -> Task { + match message {} + } +} diff --git a/crates/app-iced/src/app/update/settings/download.rs b/crates/app-iced/src/app/update/settings/download.rs new file mode 100644 index 0000000..2bb52fb --- /dev/null +++ b/crates/app-iced/src/app/update/settings/download.rs @@ -0,0 +1,18 @@ +//! Downloads 分组消息的落点（M101 `SETTINGSMSG`）：**只归 download 线**。 +//! +//! 消息口在 `pages/settings/download.rs`（`pages::settings::download::Message`）。与下载页 +//! （`pages/download*` 与 `app/update/download.rs`）无关：那是「装哪个版本」，这一组是「怎么下」。 +//! +//! 首版是空枚举上的 `match message {}`：这是**穷尽**的写法（不是兜底），加了变体不接线就报 E0004。 + +use super::super::*; + +impl App { + /// Downloads 分组的一条消息。首版没有可处理的东西（空枚举）。 + pub(super) fn on_settings_download( + &mut self, + message: pages::settings::download::Message, + ) -> Task { + match message {} + } +} diff --git a/crates/app-iced/src/app/update/settings/java.rs b/crates/app-iced/src/app/update/settings/java.rs new file mode 100644 index 0000000..a8f3fe7 --- /dev/null +++ b/crates/app-iced/src/app/update/settings/java.rs @@ -0,0 +1,33 @@ +//! Java 分组消息的落点（M101 `SETTINGSMSG`）：**只归 java 线**。 +//! +//! 消息口在 `pages/settings/java.rs`（`pages::settings::java::Message`）。加一支消息 = 改那两个 +//! 文件，`pages/mod.rs` / `page_messages.rs` / `app/update/settings.rs` 都不用动。 +//! +//! 消息进来的通道有两条，都不经过共享文件： +//! 1. **页面点击**：`pages::Message::Settings(GroupMessage::Java(..))` → `on_page` → `on_settings`； +//! 2. **异步结果**：本文件自己构造 `Message::Page(pages::Message::Settings(GroupMessage::Java(..)))` +//! （`app::Message::Page` 是既有通道，不用加新变体）。 +//! +//! 穷尽性：这里对 `java::Message` 做**穷尽**匹配（没有 `_ =>`、没有 `other =>`）。加了变体不接线 +//! 立刻 E0004；写成兜底会把编译错误降级成「点了没反应」，`app/update/settings/tests.rs` 的 +//! `the_group_dispatch_has_no_catch_all_arm` 会红。 + +use super::super::*; + +impl App { + /// Java 分组的一条消息。 + pub(super) fn on_settings_java( + &mut self, + message: pages::settings::java::Message, + ) -> Task { + match message { + // M101 r2 的**活的端到端证据**：只有测试构造这一支（java 线接第一个真控件时换成真变体）。 + // 它真的改一个 app 状态，所以「消息从外壳走到 handler」这件事有运行时证据，不只是编译期。 + #[cfg(test)] + pages::settings::java::Message::Ping => { + self.view_dirty = true; + Task::none() + } + } + } +} diff --git a/crates/app-iced/src/app/update/settings/language_appearance.rs b/crates/app-iced/src/app/update/settings/language_appearance.rs new file mode 100644 index 0000000..b2c18eb --- /dev/null +++ b/crates/app-iced/src/app/update/settings/language_appearance.rs @@ -0,0 +1,19 @@ +//! 语言 + 外观两组消息的落点（M101 `SETTINGSMSG`）：**只归 language+appearance 线**。 +//! +//! 消息口在 `pages/settings/language_appearance.rs`（`pages::settings::language_appearance::Message`）。 +//! 为什么两组共用一个消息口：它俩本就是同一条线的两个分组（General 的语言 / 主题 / 启动页， +//! Appearance 的密度 / 圆角 / 动效 / 文字缩放），`GroupMessage` 只给这条线留一个变体。 +//! +//! 首版是空枚举上的 `match message {}`：这是**穷尽**的写法（不是兜底），加了变体不接线就报 E0004。 + +use super::super::*; + +impl App { + /// 语言 / 外观线的一条消息。首版没有可处理的东西（空枚举）。 + pub(super) fn on_settings_language_appearance( + &mut self, + message: pages::settings::language_appearance::Message, + ) -> Task { + match message {} + } +} diff --git a/crates/app-iced/src/app/update/settings/tests.rs b/crates/app-iced/src/app/update/settings/tests.rs new file mode 100644 index 0000000..150f2ba --- /dev/null +++ b/crates/app-iced/src/app/update/settings/tests.rs @@ -0,0 +1,267 @@ +//! 设置页分组消息分发的**守门测试**（M101 `SETTINGSMSG`）。 +//! +//! 判据与 `app/update/page_messages.rs` 里那条 `the_page_match_has_no_wildcard_fallback` 同源： +//! 兜底会把「加了变体忘了接线」从**编译错误**降级成「点了没反应」。两级 dispatch 各守一条： +//! 那一层守 `pages::Message`，本文件守 `GroupMessage` 与四个 handler。 +//! +//! ## 判据（r2 复审 P2-3 之后收窄过一次） +//! +//! 上一版的判据是「除已知前缀外，任何含 `=>` 的行都算兜底」——**过宽**：往 handler 里加一个 +//! **没有兜底臂**的嵌套 match（`match true { true => …, false => … }`），或者 rustfmt 把长 +//! or-pattern 折行成 `| X =>`，都会让它假红。四条填页线一写真实逻辑就撞，守门反而推高成本。 +//! +//! 现在的判据是**结构化的**：只找 `match message {` 这一层（用大括号深度计数把嵌套 match 排除 +//! 在外），**只看深度 1 的臂**—— +//! +//! - `app/update/settings.rs` 的 `on_settings`：恰好 **4 条**臂，每条以 `pages::settings::GroupMessage::` +//! （或短写 `GroupMessage::`）开头； +//! - 四个 handler：每条臂以该组自己的 `pages::settings::<线>::Message::`（或短写 `Message::`）开头， +//! 还没有臂的（空枚举 `match message {}`）一条臂都没有； +//! - 以 `|` 开头的折行 or-pattern 续行放行（它不可能是兜底）。 +//! +//! ## 抓得住什么 / 抓不住什么 +//! +//! 抓得住： +//! 1. `on_settings` 里加 `_ =>` 或 binding 臂 `other =>`（`GroupMessage` 不再穷尽）； +//! 2. handler 把 `match message {}` 改成 `_ => Task::none()` / `other => { … }`； +//! 3. `on_settings` 的臂数不是 4（删了一条、或把两条合并）； +//! 4. handler 的臂写成别的组的变体路径（前缀不对）。 +//! +//! 抓不住（老实列出来）： +//! 1. **嵌套 match 里的兜底**——深度 ≥2 的臂不看。这是刻意的：嵌套 match 的穷尽性由它自己的类型 +//! 保证，跟 `GroupMessage` 漏接线无关；代价是没人守「嵌套 match 自己写了个 `_ =>`」； +//! 2. **跨行 pattern 分两种，别当一种**：以 `|` 开头的 or-pattern 续行**放行**（不误红）； +//! 但**花括号形状**的多行 pattern（例如 `Message::SetRuntime {` 折成多行、`=>` 落在后面） +//! 会被**静默跳过**——那一行不带 `=>`，于是既不算臂也不算违规（臂数 0、零违规），是**漏检** +//! 而不是误红。两种都是洞，当前代码风格都不出现；真要用这种写法时把规则补上，别把守门删掉； +//! 3. **字符串/字符字面量里的 `{` `}`** 会扰乱深度计数（本文件与四个 handler 都没有这种写法）； +//! 4. handler 忽略消息（`let _ = message; Task::none()`）、两个 handler 身体写反或写成一样 +//! ——类型对得上就编得过，只有人读能看出来； +//! 5. `match message` 被改名或换变量名时找不到匹配，臂数为 0 —— 这时 +//! `the_group_dispatch_has_exactly_four_arms` 会红（不是静默通过）。 +//! +//! 站位：本文件是 `app::update::settings::tests`，`include_str!` 的路径相对本文件所在目录。 + +use unlucky_design::color::SchemeFlavor; +use unlucky_presenter::mock::MockBackend; +use unlucky_presenter::settings_bridge::SettingsBridge; + +use crate::app::message::Message; +use crate::app::state::App; +use crate::cli::Options; +use crate::pages; +use crate::theme::Families; + +/// `on_settings` 的臂允许的前缀。 +const GROUP_ARMS: &[&str] = &["pages::settings::GroupMessage::", "GroupMessage::"]; + +/// 一行的净大括号增量（`{` 加、`}` 减）。 +fn brace_delta(line: &str) -> i32 { + let open = line.matches('{').count() as i32; + let close = line.matches('}').count() as i32; + open - close +} + +/// 扫一条 `match message { … }`，只看**本层**（深度 1）的臂。 +/// +/// 返回 `(本层的合法臂数, 违规行)`：违规 = 本层里含 `=>`、又不是「已知前缀开头」的行 +/// （`|` 开头的折行 or-pattern 续行放行）。嵌套 match 的臂在深度 ≥2，整段跳过。 +fn dispatch_arms(path: &str, source: &str, allowed: &[&str]) -> (usize, Vec) { + 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; + + let _ = app.update(Message::Page(pages::Message::Settings( + pages::settings::GroupMessage::Java(pages::settings::java::Message::Ping), + ))); + + assert!( + app.view_dirty, + "java 线的消息没有走到 `on_settings_java`：消息漏斗在某一环断了" + ); +} diff --git a/crates/app-iced/src/app/view.rs b/crates/app-iced/src/app/view.rs new file mode 100644 index 0000000..4576bd6 --- /dev/null +++ b/crates/app-iced/src/app/view.rs @@ -0,0 +1,195 @@ +//! `view`：presenter 快照 → 页面视图模型 → 控件树。 +//! +//! 展示转换（快照字段 → 显示文本/网格）**全部在这里**，页面层只认 [`pages::Model`]。 +//! +//! 实例页那一段（`1.20.4 · Fabric`、运行状态、元信息卡）M120 搬进 [`instances`]：本文件 +//! 当时贴着 400 行硬线，而 i18n 还要在这个函数里接一批阶段标签。 + +use iced::{Element, Theme}; + +use unlucky_i18n::Lang; +use unlucky_presenter::router::Route; +use unlucky_presenter::state::AppState; + +use crate::app::components::interaction::Interaction; +use crate::cli::Screen; +use crate::pages::{self, Row}; +use crate::shell::{self, agent, NavItem}; + +use super::message::{nav_item_of, Message}; +use super::state::{log_first_frame, App}; +use super::APP_TITLE; + +mod account_page; +mod instances; +mod logs; +mod rail; + +use instances::{detail_of, runtime_status, supporting_line}; +use logs::logs_model; + +impl App { + /// 主题名（iced 只在 `Theme::name()` 变化时重算受主题影响的缓存）。 + pub(super) fn theme(&self) -> Theme { + self.ui().theme() + } + + /// 窗口标题（自绘标题栏另画一份，这里是给系统/截图工具看的）。 + pub(super) fn title(&self) -> String { + APP_TITLE.to_owned() + } + + /// 整棵树。 + pub(super) fn view(&self) -> Element<'_, Message> { + log_first_frame(); + + // `--screen=gallery`：组件库 harness（D39 §5）。它用自己的 DemoMessage， + // 这里只做一次 map，组件库与业务 Message 依然解耦。 + if self.options.screen == Screen::Gallery { + return super::components::gallery::view(&self.ui).map(Message::Demo); + } + + // 产品页走**内容槽位**：外壳（标题栏 / 拖动与缩放热区 / 三个 caption 键 / rail）由 + // `shell` 画，中间那块才是页面（`DragWindow`/`ResizeStart`/`Minimize`/`ToggleMaximize`/`Close` + // 五种消息的构造点只在外壳里，页面树自己画的标题栏拖不动窗口）。 + // + // M93：三样东西从外观状态进来——①背景层（垫在最底下）②面板 α（外壳层的底色）③设置页要读 + // 的那份状态。M101 r2 起 ③ 走 `page_with_settings`：外观状态 + 各组自己的状态一起递进去。 + let background = + pages::appearance::layer(&self.ui, &self.appearance, (self.width, self.height)) + .map(|element| element.map(Message::Page)); + // 右栗（M104）：拆出档返回 `None`（会话已在独立页里）；拖拽期间另有铺满窗口的取指针层。 + let overlay = agent::drag_overlay(&self.agent).map(|element| element.map(Message::Agent)); + // M119：会话内容 / 未读 / busy / 待确认全部来自 presenter 的 rail，失败横幅是 app 层 + // 备好的**展示输入**（标题 catalog 键 + 已脱敏正文）。壳在这里不做任何脱敏。 + // 界面语言的真值源是 `App::lang`（M106）：右栏的静态文案也走它，不再有 `const LANG` + let agent_catalog = self.lang().catalog(); + // 会话入参：rail 借 presenter、失败横幅由 app 层备好、`simulated` 是后端的事实 + let session = agent::Session { + agent: &self.agent, + rail: self.agent_host.rail(), + failure: self.agent_failure(), + simulated: self.agent_host.is_simulated(), + }; + + let account = self.rail_account(); + match pages::Screen::of(self.state.route()) { + Some(_) => shell::view_with_account( + &self.ui, + shell::NavRail { + selected: nav_item_of(self.state.route()), + account: account.clone(), + }, + APP_TITLE, + background, + // M101 r2：设置页的只读状态（外观运行期状态 + 各组自己的状态）一次递进去。 + pages::page_with_settings( + &self.ui, + &self.view, + pages::settings::States { + appearance: Some(&self.appearance), + groups: &self.settings, + }, + // M106：设置页 General 组要画「当前档位 + 生效语言」。 + self.language(), + ) + .map(Message::Page), + agent::docked(&self.ui, session, agent_catalog, self.width) + .map(|element| element.map(Message::Agent)), + overlay, + self.options.force_state, + self.lang(), + ), + // 账户页（M114）：它不走 `pages::Screen` 那四页的 `Model`，自己一棵树 + // （树在 `app/view/account_page.rs`，与其它页共用 M104 的中栏可用宽）。 + None if self.state.route() == &Route::Accounts => { + self.account_page(&account, background, overlay) + } + // `Route::Agent`：独立页与右栏共用同一个 `conversation::view`（`agent::page` 内部调的它）。 + None => shell::view_with_account( + &self.ui, + shell::NavRail { + selected: NavItem::Ai, + account: account.clone(), + }, + APP_TITLE, + background, + agent::page(&self.ui, session, agent_catalog, self.width).map(Message::Agent), + None, + overlay, + self.options.force_state, + self.lang(), + ), + } + } +} + +// --------------------------------------------------------------- 快照 → 视图模型 + +/// 把 presenter 的快照转成页面视图模型（**唯一**的展示转换点）。 +/// +/// `forced` 是 `--force-state` 的落点（P3-1）：它只影响**画出来的**状态层，不改任何状态机。 +/// +/// `width` 是**中栗可用宽度**（窗口 − 右栗 − 拖拽缝，由 `AgentUi::content_width` 算），不是窗口宽： +/// 页面布局系统仍按「一个窗口宽」扣左轨与页边距，所以右栗占掉的那一段必须在这里先减掉—— +/// 否则助手栏一展开，页面还按 1180 排版，内容就顶到面板底下了（任务里的「收缩而不是溢出」）。 +pub(super) fn model( + state: &AppState, + width: f32, + forced: Option, + 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(&cell.instance.runtime, catalog), + }) + .collect(); + + let detail = match &route { + Route::Detail(id) => state + .instances + .iter() + .find(|instance| &instance.id == id) + .map(|instance| detail_of(instance, catalog)), + _ => None, + }; + + pages::Model { + screen, + window_width: width, + active: route.nav(), + instances: pages::Instances { rows, detail }, + download: pages::Download::from_snapshot(state, category, draft, lang.catalog()), + // M109：检索条件/结果来自快照，页面内选择（类型/选中/目标/草稿）来自 `App::content` + content: pages::content::Content::from_snapshot(state, content, lang.catalog()), + logs: logs_model(state).with_status(lang), + lang, + forced: forced.map(|state| match state { + // `Rest` = 常态（压掉系统光标 hover）；`Interaction::Enabled` 就是静息态，不叠状态层。 + crate::cli::ForcedState::Rest => Interaction::Enabled, + crate::cli::ForcedState::Hover => Interaction::Hovered, + crate::cli::ForcedState::Pressed => Interaction::Pressed, + }), + } +} + +#[cfg(test)] +#[path = "view/tests.rs"] +mod tests; + +/// 测试只借这一条（其余三条 `model()` 自己用）。 +#[cfg(test)] +use instances::last_played; diff --git a/crates/app-iced/src/app/view/account_page.rs b/crates/app-iced/src/app/view/account_page.rs new file mode 100644 index 0000000..a90ca99 --- /dev/null +++ b/crates/app-iced/src/app/view/account_page.rs @@ -0,0 +1,73 @@ +//! 账户页（M114）的**整页装配**：从 `App` 的状态拼出内容树，再交给外壳。 +//! +//! 为什么单独一个文件：`app/view.rs` 贴着 400 行硬线（M104 的右栏分支已经把余量吃掉了）， +//! 而这段是纯装配（没有状态数学），搬出来不改变任何语义。 +//! +//! 宽度口径：用 `AccountPage::width`（= M104 的 `AgentUi::content_width`，中栏可用宽）， +//! 与其它页、与 `refresh_view` 同一份来源——右栏展开时账户页**一起收缩**，不会顶到面板底下。 + +use iced::Element; + +use crate::app::Message; +use crate::pages; +use crate::pages::account::Page as AccountPage; +use crate::shell::{self, agent, NavItem, RailAccount}; + +use super::super::state::App; +use super::super::APP_TITLE; + +impl App { + /// 账户页视图模型的重建（`refresh_view` 的账户那一步）。 + /// + /// 与 `view` 同一次门控；语言跟着 M106 的 `LangState` 走（M114 早期钉死 `Lang::En` + /// 的写法已删），宽度用 M104 的中栏可用宽。放在这里是为了让 `app/state.rs` 守住 400 行。 + pub(in crate::app) fn rebuild_account_page(&mut self, width: f32) { + let lang = self.lang(); + self.account = AccountPage::build( + &self.state, + &self.account_form, + &mut self.avatars, + lang, + width, + ); + } + + /// 账户页（走 `pages::account` 自己的树，而不是 `pages::Screen` 那四页的 `Model`）。 + pub(super) fn account_page<'a>( + &'a self, + account: &RailAccount, + background: Option>, + 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..da88dbf --- /dev/null +++ b/crates/app-iced/src/app/view/instances.rs @@ -0,0 +1,162 @@ +//! 实例页的**展示转换**（M120 从 `app/view.rs` 原样搬出：那边给 i18n 让出行数）。 +//! +//! | 函数 | 产物 | 谁读 | +//! |---|---|---| +//! | [`supporting_line`] | 列表行 / 详情副标题 `1.20.4 · Fabric 0.16.5` | [`crate::pages::Row`] / [`crate::pages::Detail`] | +//! | [`runtime_status`] | 运行状态行（列表 overline + 详情状态行共用一份） | 同上 | +//! | [`detail_of`] | 详情列的全部字段 | [`crate::pages::Detail`] | +//! | [`last_played`] | `2026-10-29 19:22 UTC` / `Never` | 元信息卡 `LAST PLAYED` | +//! +//! 这里只做「快照字段 → 要画什么」，不碰控件树。**文案的语言由调用方的 [`Catalog`] 决定** +//! （`view::model` 把 `App::lang` 的目录传进来），不再是 M90 时期的英文基线字面量。 +//! +//! ## 两条接法上的取舍 +//! +//! 1. **原版徽标走词表**：`LoaderInfo::badge()` 对原版返回**中文**「原版」（那是 presenter 的 +//! 面向中文日志的 `label()`），英文界面里直接画它就是「中文漏进英文界面」。所以原版这一支 +//! 改走 [`Key::LoaderVanilla`]，装加载器时仍是 `Fabric 0.16.5`（品牌 + 版本号，不翻译）； +//! 2. **运行状态只翻标签本体**：`Running · pid 1234` → `运行中 · pid 1234`，`pid` 与数字、 +//! `·` 分隔符一个字都不动（[`Key::InstancesRunning`] 的占位符只有 `{pid}`）。 + +use unlucky_i18n::{Catalog, Key}; +use unlucky_presenter::dto::{InstanceRuntime, InstanceSummary, LaunchStage, LoaderKind}; + +use crate::pages::{Detail, Meta}; + +/// 列表行的副文案：`1.20.4 · Fabric 0.16.5`（原版只写「原版 / Vanilla」，见 [`loader_badge`]）。 +pub(super) fn supporting_line(instance: &InstanceSummary, catalog: Catalog) -> String { + format!( + "{} · {}", + instance.mc_version, + loader_badge(instance, catalog) + ) +} + +/// 加载器徽标：原版走词表，其余交给 `LoaderInfo::badge()`（品牌 + 版本号，原样）。 +/// +/// **判据只能是「加载器类型本身是原版」**。曾经写成「原版 **或** 版本号为空」⇒ +/// `1.20.1-forge` / `1.20.1-neoforge` / `1.20.1-OptiFine` 这类**取不到版本段**的 id（`badge()` +/// 对它们给的就是品牌名 `Forge` / `NeoForge` / `OptiFine`）会被显示成「原版 / Vanilla」—— +/// 那是 M120 r1 的 p2-1 回归，`the_loader_badge_keeps_the_brand_when_the_version_is_missing` 守着。 +fn loader_badge(instance: &InstanceSummary, catalog: Catalog) -> String { + match instance.loader.kind { + // 唯一需要过词表的一支：`LoaderKind::label()` 对原版返回的是**中文**「原版」 + LoaderKind::Vanilla => catalog.text(Key::LoaderVanilla).to_string(), + // 其余品牌名不翻译；版本号为空时 `badge()` 自己就只给品牌名 + _ => instance.loader.badge(), + } +} + +/// 隔离档位：`isolated` / `shared` 是两个稳定 id（`core::game::IsolationMode::as_str`）， +/// 直接上屏就是英文界面漏中文、中文界面漏英文。只认这两档，**其余原样**（`inherit` / `custom` / +/// 未来新增的值不许在这里被猜成一个意思）。 +fn isolation(raw: &str, catalog: Catalog) -> String { + match raw { + "isolated" => catalog.text(Key::InstancesIsolationIsolated).to_string(), + "shared" => catalog.text(Key::InstancesIsolationShared).to_string(), + other => other.to_string(), + } +} + +/// 运行状态（列表行的 overline 与详情页的状态行共用一份文案）。 +pub(super) fn runtime_status(runtime: &InstanceRuntime, catalog: Catalog) -> Option { + match runtime { + InstanceRuntime::Idle => None, + // 「阶段 · 百分比」：百分比是数字，不过词表；只有阶段名换语言 + InstanceRuntime::Busy { stage, progress } => Some(format!( + "{} · {:.0}%", + stage_label(*stage, catalog), + progress.ratio() * 100.0 + )), + InstanceRuntime::Running { pid } => { + Some(catalog.render(Key::InstancesRunning, &[("pid", &pid.to_string())])) + } + // `reason` 是 core 给的诊断原文（**数据**，不翻译）；只有前半句是界面文案 + InstanceRuntime::Failed { reason } => { + Some(catalog.render(Key::InstancesFailed, &[("reason", reason)])) + } + } +} + +/// 阶段文案：**不**复用 `LaunchStage::label()`（那是核心层的中文诊断串，英文界面会漏中文）。 +fn stage_label(stage: LaunchStage, catalog: Catalog) -> &'static str { + catalog.text(match stage { + LaunchStage::Download => Key::InstancesStageDownload, + LaunchStage::Verify => Key::InstancesStageVerify, + LaunchStage::Launch => Key::InstancesStageLaunch, + LaunchStage::Window => Key::InstancesStageWindow, + }) +} + +/// 详情列的内容（字段全部来自 [`InstanceSummary`]）。 +pub(super) fn detail_of(instance: &InstanceSummary, catalog: Catalog) -> Detail { + Detail { + id: instance.id.clone(), + name: instance.name.clone(), + subtitle: supporting_line(instance, catalog), + meta: vec![ + meta( + catalog.text(Key::InstancesMetaVersion), + &instance.mc_version, + ), + meta( + catalog.text(Key::InstancesMetaLoader), + &loader_badge(instance, catalog), + ), + meta( + catalog.text(Key::InstancesMetaIsolation), + &isolation(&instance.isolation, catalog), + ), + meta( + catalog.text(Key::InstancesMetaVersionId), + &instance.version_id, + ), + meta( + catalog.text(Key::InstancesMetaFiles), + catalog.text(if instance.version_present { + Key::InstancesPresentOnDisk + } else { + Key::InstancesMissing + }), + ), + meta( + catalog.text(Key::InstancesMetaLastPlayed), + &last_played(instance.last_played.as_deref(), catalog), + ), + ], + // 真快照没有「正文描述」这种字段（偏离 #9）：演示数据才有正文段 + note: None, + status: runtime_status(&instance.runtime, catalog), + can_launch: matches!( + instance.runtime, + InstanceRuntime::Idle | InstanceRuntime::Failed { .. } + ), + can_stop: matches!( + instance.runtime, + InstanceRuntime::Busy { .. } | InstanceRuntime::Running { .. } + ), + } +} + +fn meta(label: &str, value: &str) -> Meta { + Meta { + label: label.to_string(), + value: value.to_string(), + } +} + +/// ISO-8601（`2026-10-29T19:22:00Z`）→ `2026-10-29 19:22 UTC`；`None` = 从未启动。 +/// +/// 只做切片不做时区换算：core 给的是 UTC，`Z` 就是它的时区；本地时区换算等时间格式 mission。 +/// 非 ASCII 或长度不足时原样返回（不 panic、不猜）。 +pub(super) fn last_played(raw: Option<&str>, catalog: Catalog) -> String { + let Some(text) = raw else { + return catalog.text(Key::InstancesNeverPlayed).to_string(); + }; + match (text.get(0..10), text.get(11..16)) { + (Some(date), Some(time)) if date.starts_with(|c: char| c.is_ascii_digit()) => { + format!("{date} {time} UTC") + } + _ => text.to_string(), + } +} diff --git a/crates/app-iced/src/app/view/logs.rs b/crates/app-iced/src/app/view/logs.rs new file mode 100644 index 0000000..136c635 --- /dev/null +++ b/crates/app-iced/src/app/view/logs.rs @@ -0,0 +1,144 @@ +//! 日志页的展示转换：presenter 快照 → [`pages::Logs`]（从 `app/view.rs` 拆出来，M95 r3）。 +//! +//! ## 跨会话串场（M95 r3 的 p2，代码复审抓的） +//! +//! r2 的写法先按 `state.diagnosis` 定「这是哪一场」： +//! +//! ```ignore +//! let session = report.and_then(|r| log_sessions.find(|s| s.id == r.session)).or_else(|| …selected…); +//! ``` +//! +//! 而 `state.diagnosis` **全仓只写不清**（`presenter::state::apply_core` 里 +//! `CoreEvent::DiagnosisReady` 是唯一赋值点，没有任何清零点），host 也只在崩溃 / 打开会话 / +//! 导入崩溃文件时发它。于是「崩溃一场 → 再启动一场正常跑」这个最普通的路径下： +//! 页头把**新**会话标成上一场的 `The game crashed`、诊断卡挂着上一场的结论，而用户复制去贴 +//! issue 的摘要里 `lines=` 是新的那一场的行数——**结论与行数不同源**，用户会把错诊断递出去。 +//! +//! 现在的口径（不动 presenter 的写入口，只在页面侧判别）： +//! +//! | 概念 | 取值 | +//! |---|---| +//! | **身份**（这一场是谁） | `live_session`（正在跑）→ `selected_session`（打开/刚结束的），**不从 `diagnosis` 反推** | +//! | 诊断结论 | 见下表的三个分支（r4 修正了 r3 的一条**回归**：r3 只认身份，把「导入崩溃文件」与「打开会话」两条路径的诊断一并关掉了） | +//! | 实例/时间/结局（给页头描述） | 身份优先；身份为空才退到报告的 session | +//! +//! 归属判据（`report.session` 与身份的关系）： +//! +//! | `live_session` | `selected_session` | 报告算数的条件 | +//! |---|---|---| +//! | `Some(live)` | 任意 | `report.session == live` —— 只有它在线时日志行是它自己在追加，别人的报告挂上来就是串场 | +//! | `None` | `Some(sel)` | `report.session == sel` **或** 报告不属于任何已知会话（`ImportCrashLog` 用 `file:<文件名>` 当会话 id，永远不在索引里） | +//! | `None` | `None` | 全部算数 —— 此时日志行只可能来自 `open_session` 或导入，两者都与报告同一次调用发出 | +//! +//! 已知残留（今天 iced 侧不可达，登记在报告里）：`open_session(A)` 在 `selected_session` 仍停在上 +//! 一场 B 时会被第三行判据挡掉（A 是已知会话且 ≠ B）——真正要修得让 presenter 在 +//! `LogLinesChanged` 时把「日志行属于哪一场」记下来（`AppState` 今天没有这个字段）。 +//! +//! 「没有命中规则」的**占位报告**也不画：host 的 `open_session` 在规则引擎无结论时会发一份 +//! `rule: ""` / `confidence: 0` / `title: "该会话没有命中已知规则"` 的假报告（`CoreEvent::DiagnosisReady` +//! 是非 Option，host 无法表达「没有结论」）——它是标记不是结论，画出来等于给用户看一条「严重度提示」。 +//! +//! 已知缺口（已报 finding，不在本 mission 修）：`clear_logs` 之后 `selected_session` 不清， +//! 身份会继续指向那一场；导入崩溃文件只发 `DiagnosisReady`（不带日志行），所以页面上会出现 +//! 「结论 + 上一场的日志正文」——行由 `open_session` 负责，那是 presenter 的缺口。 + +use unlucky_presenter::dto::{Diagnosis, LogLevel, LogOutcome}; +use unlucky_presenter::state::AppState; + +use crate::pages; + +/// 日志页视图模型：presenter 快照 → 要画的东西。 +/// +/// 两处 DTO 侧的**信息丢失**（已报 finding）：`dto::Diagnosis` 没有 core 的 `severity` +/// （所以页面按置信度档分组，不冒称严重度）与 `cause.key`（`title`/`hint` 只能当数据画）。 +pub(super) fn logs_model(state: &AppState) -> pages::Logs { + let live = state.live_session.as_deref(); + let selected = state.selected_session.as_deref(); + let identity = live.or(selected); + + // 归属判据（r4 修正 r3 的**回归**：r3 的「有选中就只认选中」把导入/打开这两条路径的诊断 + // 一起关掉了）。三条命中任一即认： + // + // 1. 报告属于**正在跑**的那一场 —— 这一条必须单独成立：只有它在线时日志行是它自己在追加， + // 别的会话的报告挂上来就是串场（r3 修的正是这个）； + // 2. 报告属于**当前选中**的那一场（没有 live 会话时）； + // 3. 报告的会话**不在会话索引里** —— `ImportCrashLog` 用 `file:<文件名>` 当会话 id， + // `open_session` 也不一定把 id 写进 `selected_session`；这两条路径与报告是同一次调用发出的， + // 把它们一并关掉就是把「导入崩溃日志」这条功能画成空（r3 的实测回归）。 + let known = |id: &str| state.log_sessions.iter().any(|session| session.id == id); + let report = state.diagnosis.as_ref().filter(|report| { + let id = report.session.as_str(); + match (live, selected) { + // 有会话在跑：日志行是它自己在追加，别的会话的报告挂上来就是串场（r3 修的 P1）。 + (Some(live), _) => id == live, + // 没有在跑、但有选中项：报告要么是它的，要么是「会话索引里没有的那一份」 + // （`ImportCrashLog` 用 `file:<文件名>`；`open_session` 不写 `selected_session`， + // 所以只能靠「不在索引里」认它）。 + (None, Some(selected)) => id == selected || !known(id), + // 什么身份都没有：日志行只可能来自 `open_session` 或导入，两者与报告同一次发出。 + (None, None) => true, + } + }); + + // 身份为空时，描述的来源只能退到报告（见模块文档的表格）。 + let described = identity.or_else(|| report.map(|report| report.session.as_str())); + let session = + described.and_then(|id| state.log_sessions.iter().find(|session| session.id == id)); + + pages::Logs { + instance: session.map(|session| session.instance.clone()), + when: session.map(|session| session.when.clone()), + outcome: session.map(|session| log_outcome(session.outcome)), + // 运行中的会话不在 `log_sessions` 里（索引只在结束时追加），所以页头要靠这个标记 + // 走「正在运行」那条文案，而不是「当前没有运行中的实例」。 + live: live.is_some(), + lines: state + .log_lines + .iter() + .map(|line| pages::Line { + text: line.text.clone(), + level: log_level(line.level), + }) + .collect(), + findings: report + .filter(|report| !report.diagnosis.rule.is_empty()) + .map(|report| diagnosis_of(&report.diagnosis)) + .into_iter() + .collect(), + ..pages::Logs::default() + } +} + +/// 日志等级：presenter 枚举 → 页面等级（**结构化出口**，不是认字符串）。 +fn log_level(level: LogLevel) -> pages::Level { + match level { + LogLevel::Debug => pages::Level::Debug, + LogLevel::Info => pages::Level::Info, + LogLevel::Warn => pages::Level::Warn, + LogLevel::Error => pages::Level::Error, + } +} + +/// 会话结局：presenter 枚举 → 页面结局（文案走 `LaunchOutcome*` key，页面不画 core 的中文串）。 +fn log_outcome(outcome: LogOutcome) -> pages::Outcome { + match outcome { + LogOutcome::Ok => pages::Outcome::Ok, + LogOutcome::Crashed => pages::Outcome::Crashed, + LogOutcome::SilentFail => pages::Outcome::SilentFail, + } +} + +/// 一条诊断结论 → 页面结论（置信度档见 [`pages::Confidence`]）。 +fn diagnosis_of(diagnosis: &Diagnosis) -> pages::Finding { + pages::Finding { + rule: diagnosis.rule.clone(), + confidence_band: pages::Confidence::of(diagnosis.confidence), + title: diagnosis.title.clone(), + hint: diagnosis.hint.clone(), + confidence: diagnosis.confidence, + action: diagnosis.fix.clone(), + } +} + +#[cfg(test)] +mod tests; diff --git a/crates/app-iced/src/app/view/logs/tests.rs b/crates/app-iced/src/app/view/logs/tests.rs new file mode 100644 index 0000000..624732a --- /dev/null +++ b/crates/app-iced/src/app/view/logs/tests.rs @@ -0,0 +1,242 @@ +//! 日志页展示转换的守门测试（从 `app/view/logs.rs` 拆出：那边已经 382 行，贴着 400 硬上限）。 +//! +//! 全部走**真实 reducer 路径**（`AppState::apply_core`），不造注入源——r3 的教训是 +//! 「测试全走注入源而真实路径零覆盖」，所以这里的夹具就是线上那串事件本身。 + +use unlucky_i18n::Lang; +use unlucky_presenter::dto::{ + CoreEvent, DiagnosisReport, LaunchFinished, LiveLogBatch, LogLevel, LogLine, LogOutcome, + LogSession, +}; +use unlucky_presenter::state::AppState; + +use crate::pages; + +use super::logs_model; + +/// 崩溃的那一场。 +const CRASH: &str = "s-1029-1840"; +/// 崩溃之后又启动的、正常跑的一场。 +const OK_RUN: &str = "s-1029-1922"; + +fn session(id: &str, when: &str, outcome: LogOutcome) -> LogSession { + LogSession { + id: id.to_string(), + instance: "开发测试".to_string(), + when: when.to_string(), + outcome, + duration_secs: 62, + } +} + +fn line(text: &str, level: LogLevel) -> LogLine { + LogLine { + text: text.to_string(), + level, + } +} + +fn report(session: &str, rule: &str) -> DiagnosisReport { + DiagnosisReport { + session: session.to_string(), + diagnosis: pages_dto(rule), + } +} + +fn pages_dto(rule: &str) -> unlucky_presenter::dto::Diagnosis { + unlucky_presenter::dto::Diagnosis { + rule: rule.to_string(), + title: "显卡驱动过旧（OpenGL 版本不足）".to_string(), + confidence: 92, + hint: "升级显卡驱动".to_string(), + fix: Some("change_graphics.driver".to_string()), + } +} + +/// **真实数据路径**（复审要求：不许造注入源绕过去）： +/// 崩溃一场跑完 → 再启动一场正常跑。`state.diagnosis` 在这里**故意不清**， +/// 因为 presenter 里根本没有清零点——这就是线上发生串场的条件。 +fn crashed_only() -> AppState { + let mut state = AppState::new(); + state.apply_core(CoreEvent::LogSessionsChanged(vec![ + session(CRASH, "10-29 18:40", LogOutcome::Crashed), + session(OK_RUN, "10-29 19:22", LogOutcome::Ok), + ])); + + // 第一场跑起来（live_session = CRASH）→ 日志 → 规则结论 → 收尾（selected_session = CRASH） + state.apply_core(CoreEvent::LogAppended(LiveLogBatch { + session: CRASH.to_string(), + lines: vec![line("[18:40] boom: GLFW error", LogLevel::Error)], + running: true, + })); + state.apply_core(CoreEvent::DiagnosisReady(report(CRASH, "gpu.driver_old"))); + state.apply_core(CoreEvent::LaunchFinished(LaunchFinished { + id: "dev".to_string(), + session: CRASH.to_string(), + outcome: LogOutcome::Crashed, + summary: "崩溃（exit 1）".to_string(), + })); + + state +} + +/// 崩溃之后又启动一场正常跑：`live_session` 前进，`diagnosis` 仍是上一场的。 +fn after_a_new_run() -> AppState { + let mut state = crashed_only(); + state.apply_core(CoreEvent::LogAppended(LiveLogBatch { + session: OK_RUN.to_string(), + lines: vec![line("[19:22] launching 1.20.4", LogLevel::Info)], + running: true, + })); + state +} + +#[test] +fn a_new_run_does_not_inherit_the_previous_crash() { + let state = after_a_new_run(); + let logs = logs_model(&state).with_status(Lang::En); + + // 抓得住：身份被上一场的 `diagnosis.session` 顶掉（r2 的 bug）——那时 outcome 会是 + // Crashed、findings 挂着 gpu.driver_old、摘要里 `lines=` 与结论不同源。 + // 抓不住：presenter 自己 `clear_logs` 后 `selected_session` 不清的缺口（已报 finding）， + // 以及多场并行会话（本仓一次只跑一场）。 + assert_eq!( + logs.outcome, + Some(pages::Outcome::Ok), + "身份应该是正在跑的这一场" + ); + + let status = logs.status.clone().expect("有会话身份就该有副标题"); + assert!(status.contains("Finished normally"), "{status}"); + assert!( + !status.contains("The game crashed"), + "页头把新会话标成了上一场的崩溃：{status}" + ); + + assert!( + logs.findings.is_empty(), + "上一场的结论不能挂到这一场：{:?}", + logs.findings + ); + + // 摘要必须与身份同源：outcome 是 ok、不含旧规则、行数就是当前这些行。 + let summary = logs.summary(); + assert!(summary.contains("outcome=ok"), "{summary}"); + assert!(!summary.contains("gpu.driver_old"), "{summary}"); + assert!( + summary.contains(&format!("lines={}", logs.lines.len())), + "{summary}" + ); + assert!(!summary.contains("findings="), "{summary}"); +} + +#[test] +fn the_crash_itself_is_still_reported() { + // 上一条测试的**对照**：崩溃当场必须画结论，否则那条断言「findings 为空」是空的。 + // 抓得住：把判别写成「永远不画诊断」（用空断言骗过 P2）。 + // 抓不住：结论排序/去重（那是 core 的规则引擎的事）。 + let state = crashed_only(); + let logs = logs_model(&state).with_status(Lang::En); + + assert_eq!(logs.outcome, Some(pages::Outcome::Crashed)); + assert_eq!(logs.findings.len(), 1, "{:?}", logs.findings); + assert_eq!(logs.findings[0].rule, "gpu.driver_old"); + let status = logs.status.clone().unwrap_or_default(); + assert!(status.contains("The game crashed"), "{status}"); + assert!(logs.summary().contains("gpu.driver_old:high(92)")); +} + +#[test] +fn an_imported_crash_file_still_shows_its_findings() { + // r3 的**回归**：r3 把归属判据写成「有选中就只认选中」，于是导入崩溃日志 + // （`ImportCrashLog` → `DiagnosisReady` 带 `file:<文件名>` 的会话 id，且**不发** + // `LogLinesChanged`）被整条丢掉。今天 iced 侧还没有 dispatch 站点（那些还在遗留的 + // Slint shell 里），所以复审没判 p1；这条测试是为了**将来接线的人**不再踩。 + // 抓得住：只有「属于当前选中/live 会话」才画的窄判据（导入的 `file:` 会话不等于任何 + // 索引里的会话，会被误杀）。 + // 抓不住：导入后日志正文该显示什么（`ImportCrashLog` 不载入日志行，那是 presenter 的事）。 + let mut state = AppState::new(); + state.apply_core(CoreEvent::LogSessionsChanged(vec![session( + CRASH, + "10-29 18:40", + LogOutcome::Crashed, + )])); + // 上一场刚结束 ⇒ selected_session = CRASH（过期选中项），随后用户导入一份崩溃文件 + state.apply_core(CoreEvent::LaunchFinished(LaunchFinished { + id: "dev".to_string(), + session: CRASH.to_string(), + outcome: LogOutcome::Crashed, + summary: "崩溃（exit 1）".to_string(), + })); + state.apply_core(CoreEvent::DiagnosisReady(report( + "file:crash-2026-11-02_19.40.15-client.txt", + "integrity.unsatisfied_link", + ))); + + let logs = logs_model(&state).with_status(Lang::En); + assert_eq!( + logs.findings.len(), + 1, + "导入的崩溃日志必须画出它的结论：{:?}", + logs.findings + ); + assert_eq!(logs.findings[0].rule, "integrity.unsatisfied_link"); +} + +#[test] +fn a_live_run_says_it_is_running_instead_of_nothing_runs() { + // 视觉复审 r3 的 P2-3：session 索引只在**结束**时追加（`host::logs::sessions`）， + // 所以运行中的那一场永远不在 `log_sessions` 里 ⇒ 拿不到实例名与结局 ⇒ r3 的页头在 + // 每次实时运行都说「当前没有运行中的实例」。demo 伪造了身份，截图上根本照不出来。 + // 抓得住：页头退回 Idle 文案（这次走真实 reducer：只有 `LogAppended(running=true)`）。 + // 抓不住：文案长度在某尺寸下会不会撞右侧动作区（那要看截图）。 + let mut state = AppState::new(); + state.apply_core(CoreEvent::LogSessionsChanged(vec![session( + CRASH, + "10-29 18:40", + LogOutcome::Crashed, + )])); + state.apply_core(CoreEvent::LogAppended(LiveLogBatch { + session: OK_RUN.to_string(), + lines: vec![line("[19:22] launching", LogLevel::Info)], + running: true, + })); + + let logs = logs_model(&state).with_status(Lang::En); + assert!(logs.live, "live_session 非空就该标记为运行中"); + let status = logs.status.clone().expect("运行中必须有副标题"); + let idle = unlucky_i18n::catalog::Catalog::of(Lang::En) + .text(unlucky_i18n::catalog::Key::LogsSubtitleIdle); + assert_ne!(status, idle, "运行中的页头不能说「没有运行」"); + assert!(status.contains("Running now"), "{status}"); +} + +#[test] +fn the_hosts_no_rule_matched_placeholder_is_not_a_finding() { + // host 的 `open_session` 在规则引擎无结论时发一份 `rule: ""` 的假报告（非 Option 逼的）。 + // 抓得住：把「没命中」画成一条严重度结论（用户会去修一个不存在的毛病）。 + // 抓不住：host 该不该改发 `None`（那是 presenter 的 finding）。 + let mut state = AppState::new(); + state.apply_core(CoreEvent::LogSessionsChanged(vec![session( + CRASH, + "10-29 18:40", + LogOutcome::Crashed, + )])); + state.apply_core(CoreEvent::LogLinesChanged(vec![line( + "[18:40] nothing to see", + LogLevel::Info, + )])); + + state.apply_core(CoreEvent::DiagnosisReady(report(CRASH, ""))); + assert!( + logs_model(&state).findings.is_empty(), + "空 rule 是『没命中』的占位，不是结论" + ); + + state.apply_core(CoreEvent::DiagnosisReady(report(CRASH, "gpu.driver_old"))); + assert_eq!( + logs_model(&state).findings.len(), + 1, + "换成真规则就得画出来（证明上面的过滤不是把诊断一起关了）" + ); +} diff --git a/crates/app-iced/src/app/view/rail.rs b/crates/app-iced/src/app/view/rail.rs new file mode 100644 index 0000000..e67285d --- /dev/null +++ b/crates/app-iced/src/app/view/rail.rs @@ -0,0 +1,35 @@ +//! 导航轨底部**账户头像位**的状态换算（M114）。 +//! +//! 为什么单独一个文件：`app/view.rs` 贴着 400 行硬线，而这块逻辑与页面树无关—— +//! 它只回答「轨底那个头像位现在该显示成未登录，还是某个账户」。 + +use crate::shell; + +use super::super::state::App; + +/// 导航轨收成「图标条」的窗口高度（M114）。 +/// +/// 判据不是「项数」而是**真实可用高度**：四项 + 底部头像位在 48 标题栏之上还要放得下 +/// 4 × 52 + 4 × 4 + 52 ≈ 300；留出一屏正文的最小高度（424 行宽 + 页头 + 边距）， +/// 低于 720 就把标签收掉，只留图标与头像位（头像位**永远可见**，任务要求）。 +const RAIL_COMPACT_HEIGHT: f32 = 720.0; + +impl App { + /// 导航轨底部头像位的状态（M114）：未登录 / 已登录两态要一眼能分。 + pub(super) fn rail_account(&self) -> shell::RailAccount { + let compact = self.height < RAIL_COMPACT_HEIGHT; + match self.state.active_account() { + Some(account) => { + shell::RailAccount::signed_in(account.monogram(), account.name.clone()) + .compact(compact) + } + // M106：未登录标签跟着**生效语言**走（早期钉死 `Lang::En` 的写法已删）。 + None => shell::RailAccount::signed_out( + self.lang() + .catalog() + .text(unlucky_i18n::Key::AccountRailSignedOut), + ) + .compact(compact), + } + } +} diff --git a/crates/app-iced/src/app/view/tests.rs b/crates/app-iced/src/app/view/tests.rs new file mode 100644 index 0000000..d011570 --- /dev/null +++ b/crates/app-iced/src/app/view/tests.rs @@ -0,0 +1,320 @@ +//! `app/view.rs` 的守门测试（rebase 到 5adac23 之后 view.rs 贴 400 行上限，按「测试独立成文件」拆出）。 + +use super::*; +use unlucky_i18n::Key; +use unlucky_presenter::dto::{ + InstanceRuntime, InstanceSummary, LaunchStage, LoaderInfo, LoaderKind, Progress, +}; +use unlucky_presenter::mock_data::mock_instances; + +fn instance(runtime: InstanceRuntime) -> InstanceSummary { + InstanceSummary { + id: "survival".to_string(), + name: "Survival".to_string(), + mc_version: "1.20.4".to_string(), + loader: LoaderInfo { + kind: LoaderKind::Fabric, + version: "0.16.5".to_string(), + }, + last_played: Some("2026-10-29T19:22:00Z".to_string()), + runtime, + icon: None, + isolation: "isolated".to_string(), + version_id: "1.20.4".to_string(), + version_present: true, + } +} + +/// **取证不变量（M100）**：`ForcedState` 的三档在产品路径上必须映射成「页面控件怎么画」。 +/// +/// 抓得住：① 谁把 `Rest` 映射成 Hovered/Pressed（那会让 `--screenshot` 的默认值反而画出状态层， +/// 与「取证密闭」正好相反，而且图看起来完全正常）；② 加了变体却映射到别的态这种复制粘贴错。 +/// 抓不住：`shell::overridden`（标题栏 / 导航轨按钮走的**另一处** match，断言在 `shell/tests.rs`）， +/// 也抓不住不消费 `model.forced` 的裸 `iced::button`（设置页「外观」区就是）。 +/// 测试用的薄包装：默认宽度 / 默认分类 / 空草稿 / **给定语言**。 +fn at_lang(state: &AppState, forced: Option, lang: Lang) -> pages::Model { + let draft = pages::InstallDraft::default(); + let page = pages::content::PageState::default(); + model( + state, + 1180.0, + forced, + pages::Category::All, + &draft, + lang, + &page, + ) +} + +/// 同 [`at_lang`]，语言取英文（绝大多数断言只关心「快照 → 模型」的映射，不关心译文）。 +fn at(state: &AppState, forced: Option) -> pages::Model { + at_lang(state, forced, Lang::En) +} + +#[test] +fn the_forced_state_maps_to_the_expected_interaction() { + let state = AppState::new(); + let forced = |forced| at(&state, Some(forced)).forced; + + assert_eq!( + forced(crate::cli::ForcedState::Rest), + Some(Interaction::Enabled), + "Rest = 静息态（压掉系统光标 hover）" + ); + assert_eq!( + forced(crate::cli::ForcedState::Hover), + Some(Interaction::Hovered) + ); + assert_eq!( + forced(crate::cli::ForcedState::Pressed), + Some(Interaction::Pressed) + ); + assert_eq!(at(&state, None).forced, None); +} + +#[test] +fn the_snapshot_becomes_the_page_model() { + let mut state = AppState::new(); + state.apply(unlucky_presenter::dto::AppEvent::Core( + unlucky_presenter::dto::CoreEvent::InstancesChanged(mock_instances()), + )); + state.navigate(Route::Detail("survival".to_string())); + + let model = at(&state, None); + assert_eq!(model.screen, pages::Screen::Instances); + assert_eq!(model.active, Some(pages::Screen::Instances.nav())); + assert_eq!(model.window_width, 1180.0); + assert_eq!(model.instances.rows.len(), 4, "mock 的四个实例"); + assert_eq!(model.instances.rows[0].id, "survival"); + + let detail = model.instances.detail.expect("路由是 Detail，要有详情"); + assert_eq!(detail.id, "survival"); + assert_eq!(detail.meta.len(), 6); + assert!(detail.can_launch, "空闲实例可启动"); + assert!(!detail.can_stop); + assert!(detail.note.is_none(), "真快照没有正文段"); +} + +#[test] +fn a_busy_instance_offers_stop_instead_of_play() { + let mut state = AppState::new(); + state.apply(unlucky_presenter::dto::AppEvent::Core( + unlucky_presenter::dto::CoreEvent::InstancesChanged(vec![instance( + InstanceRuntime::Busy { + stage: LaunchStage::Download, + progress: Progress { + done: 750, + total: 1_500, + }, + }, + )]), + )); + state.navigate(Route::Detail("survival".to_string())); + + let model = at(&state, None); + assert_eq!( + model.instances.rows[0].status.as_deref(), + Some("Downloading · 50%") + ); + let detail = model.instances.detail.expect("有详情"); + assert!(!detail.can_launch, "启动中不许再点 Play（不做乐观回显）"); + assert!(detail.can_stop, "启动中要能 Stop"); +} + +#[test] +fn failed_instances_can_be_retried() { + let failed = instance(InstanceRuntime::Failed { + reason: "exit 1".to_string(), + }); + assert_eq!( + runtime_status(&failed.runtime, Lang::En.catalog()).as_deref(), + Some("Launch failed · exit 1") + ); + assert!( + detail_of(&failed, Lang::En.catalog()).can_launch, + "失败后要能重试" + ); +} + +#[test] +fn timestamps_are_sliced_not_guessed() { + let en = Lang::En.catalog(); + assert_eq!( + last_played(Some("2026-10-29T19:22:00Z"), en), + "2026-10-29 19:22 UTC" + ); + assert_eq!(last_played(None, en), "Never"); + // 短串 / 非 ASCII 原样返回（不 panic） + assert_eq!(last_played(Some("2026-10"), en), "2026-10"); + assert_eq!(last_played(Some("昨天"), en), "昨天"); + // 「从未游玩」是唯一走词表的那一支 + assert_eq!(last_played(None, Lang::ZhCn.catalog()), "从未游玩"); +} + +/// **快照 → 页面文案跟着 `App::lang` 走**（M120 的核心接线断言，模型这一层）。 +/// +/// 抓得住：`view::model` 又把语言写死成 `Lang::En`（M106 之前的原样）、阶段/元信息标签还留着 +/// 英文基线字面量、原版徽标直接画 presenter 的中文「原版」。这三种都不会让任何别的测试红。 +/// 抓不住：页面把 key 画没画上屏（那是 `pages/instances/tests/i18n.rs` 的取样口 + 出图）。 +#[test] +fn the_runtime_lines_and_meta_labels_follow_the_language() { + let mut state = AppState::new(); + state.apply(unlucky_presenter::dto::AppEvent::Core( + unlucky_presenter::dto::CoreEvent::InstancesChanged(vec![ + instance(InstanceRuntime::Running { pid: 1234 }), + instance(InstanceRuntime::Busy { + stage: LaunchStage::Verify, + progress: Progress { + done: 750, + total: 1_500, + }, + }), + ]), + )); + state.navigate(Route::Detail("survival".to_string())); + + let en = at_lang(&state, None, Lang::En); + let zh = at_lang(&state, None, Lang::ZhCn); + + // 列表 overline：中英各一份，数字与分隔符不动 + assert_eq!( + en.instances.rows[0].status.as_deref(), + Some("Running · pid 1234") + ); + assert_eq!( + zh.instances.rows[0].status.as_deref(), + Some("运行中 · pid 1234") + ); + assert_eq!( + en.instances.rows[1].status.as_deref(), + Some("Verifying · 50%") + ); + assert_eq!(zh.instances.rows[1].status.as_deref(), Some("校验中 · 50%")); + + // 元信息卡的标签与值 + let (en_detail, zh_detail) = ( + en.instances.detail.expect("有详情"), + zh.instances.detail.expect("有详情"), + ); + let labels = |detail: &pages::Detail| -> Vec { + detail.meta.iter().map(|cell| cell.label.clone()).collect() + }; + assert_eq!( + labels(&en_detail), + vec![ + "VERSION", + "LOADER", + "ISOLATION", + "VERSION ID", + "FILES", + "LAST PLAYED" + ] + ); + assert_eq!( + labels(&zh_detail), + vec!["版本", "加载器", "隔离方式", "版本标识", "文件", "上次游玩"] + ); + + // 值里只有「是否在磁盘上」与「上次游玩」是可翻译的；版本号 / 隔离方式 / 版本标识是数据 + // 隔离档位是 core 的稳定 id（`isolated` / `shared`），也要换成人话；认不出来的原样上屏 + assert_eq!(en_detail.meta[2].value, "Isolated"); + assert_eq!(zh_detail.meta[2].value, "独立目录"); + assert_eq!(en_detail.meta[4].value, "Present on disk"); + assert_eq!(zh_detail.meta[4].value, "已在磁盘上"); + assert_eq!( + en_detail.meta[5].value, "2026-10-29 19:22 UTC", + "时间戳是数据：只切片，不随语言变形" + ); + assert_eq!(zh_detail.meta[5].value, "2026-10-29 19:22 UTC"); + + // 详情状态行与列表 overline 同源 + assert_eq!(zh_detail.status.as_deref(), Some("运行中 · pid 1234")); +} + +/// 原版徽标：`LoaderInfo::badge()` 对原版返回**中文**「原版」，英文界面里必须换回 `Vanilla`。 +/// +/// 抓得住：`loader_badge` 退回直接调 `badge()`（M90 ~ M119 的形状）——那样英文界面会漏中文， +/// 而中文界面又是对的，所以只有这条双语断言抓得住它。 +#[test] +fn the_vanilla_badge_follows_the_language() { + let mut bare = instance(InstanceRuntime::Idle); + bare.loader = LoaderInfo { + kind: LoaderKind::Vanilla, + version: String::new(), + }; + let mut state = AppState::new(); + state.apply(unlucky_presenter::dto::AppEvent::Core( + unlucky_presenter::dto::CoreEvent::InstancesChanged(vec![bare]), + )); + state.navigate(Route::Detail("survival".to_string())); + + let en = at_lang(&state, None, Lang::En); + let zh = at_lang(&state, None, Lang::ZhCn); + assert_eq!(en.instances.rows[0].supporting, "1.20.4 · Vanilla"); + assert_eq!(zh.instances.rows[0].supporting, "1.20.4 · 原版"); +} + +/// **品牌名不许被「版本号为空」吞掉**（M120 r1 复审的 p2-1 回归）。 +/// +/// 背景：`host::game::loader_from_id("1.20.1-forge")` 这类 id 里取不到版本段（它按 `forge-` +/// 找，而 id 的写法是 `-forge` 结尾），于是 `LoaderInfo { kind: Forge, version: "" }`。 +/// `LoaderInfo::badge()` 对这种输入给的正是品牌名 `Forge`——所以判据只能是「类型是原版」， +/// 不能是「版本号为空」。 +/// +/// 三个 id 各一条断言（复审点名的三档）；`Vanilla` 那一支由 +/// `the_vanilla_badge_follows_the_language` 守，两条合起来把 `loader_badge` 的两侧都钉住。 +/// +/// 抓得住：`loader_badge` 把「非原版 + 空版本号」也送进 `Key::LoaderVanilla` +/// （r1 的真实形状：`left: "1.20.4 · Vanilla" / right: "1.20.4 · Forge"`）； +/// 抓不住：`loader_from_id` 认不出自家 `-fabric-` / `-quilt-` 口径这个**更老**的 bug +/// （在 presenter 里，另一条 mission）。 +#[test] +fn the_loader_badge_keeps_the_brand_when_the_version_is_missing() { + // (版本 id, 期望徽标) —— id 形状取自 `host::game::loader_from_id` 的三条真实输入 + let cases = [ + ("1.20.1-forge", LoaderKind::Forge, "Forge"), + ("1.20.1-neoforge", LoaderKind::NeoForge, "NeoForge"), + ("1.20.1-OptiFine", LoaderKind::OptiFine, "OptiFine"), + ]; + + for (id, kind, brand) in cases { + let mut one = instance(InstanceRuntime::Idle); + one.loader = LoaderInfo { + kind, + // `loader_from_id` 对这三条 id 取不到版本段 ⇒ 空串 + version: String::new(), + }; + let mut state = AppState::new(); + state.apply(unlucky_presenter::dto::AppEvent::Core( + unlucky_presenter::dto::CoreEvent::InstancesChanged(vec![one]), + )); + state.navigate(Route::Detail("survival".to_string())); + + // 品牌名两套语言都不翻译 ⇒ 中英逐字相同 + for lang in [Lang::En, Lang::ZhCn] { + let model = at_lang(&state, None, lang); + assert_eq!( + model.instances.rows[0].supporting, + format!("1.20.4 · {brand}"), + "{id} 的徽标被显示成了别的东西（新增的判据「版本号为空 ⇒ 原版」就是这条要拦的）" + ); + let detail = model.instances.detail.expect("有详情"); + assert_eq!( + detail.meta[1].label, + lang.catalog().text(Key::InstancesMetaLoader) + ); + assert_eq!(detail.meta[1].value, brand, "{id} 的 LOADER 卡值"); + } + } +} + +#[test] +fn the_agent_route_has_no_page() { + let mut state = AppState::new(); + state.navigate(Route::Agent); + let model = at(&state, None); + // Agent 没有页面：模型退回实例页的空壳，view 会走外壳回退（`None` 分支） + assert_eq!(pages::Screen::of(state.route()), None); + assert!(model.instances.detail.is_none()); + assert_eq!(model.active, None, "AI 页不高亮任何导航项"); +} diff --git a/crates/app-iced/src/app/window_alpha.rs b/crates/app-iced/src/app/window_alpha.rs new file mode 100644 index 0000000..e3366d9 --- /dev/null +++ b/crates/app-iced/src/app/window_alpha.rs @@ -0,0 +1,134 @@ +//! 整窗 α 的**执行侧**：句柄探测 → `WS_EX_LAYERED` → `SetLayeredWindowAttributes` → 一行日志。 +//! +//! ## 为什么句柄要绕一圈 iced +//! +//! iced 0.14 只给 `window::Id`（它自己的编号），没有「给我 HWND」的公开 API；唯一的入口是 +//! `window::run(id, callback)`——回调里拿到的 `&dyn Window` 实现了 `HasWindowHandle` +//! （raw-window-handle 0.6），于是能取到 `RawWindowHandle::Win32(hwnd)`。 +//! +//! ## 三层责任（顺序不能换） +//! +//! 1. **探测句柄**：[`probe_hwnd`]，纯取；拿不到就整条链跳过（并如实打日志，不许假装成功）； +//! 2. **补分层样式**：`ensure_layered`（唯一 `unsafe` 落点，`platform/win32/transparency.rs`）； +//! `SetLayeredWindowAttributes` 在没有 `WS_EX_LAYERED` 的窗口上**必然失败**（Win32 返回 0， +//! 本机 `GetLastError` 常见 87），所以这一步是硬前提； +//! 3. **下发 α**：`apply_window_alpha`。`α ≥ 1` 时它返回 `Opaque` 并且**不调 FFI**，那时也就不必 +//! 改扩展样式（1、2 步都是白改），[`dispatch`] 里按这个条件短路。 +//! +//! ## 为什么日志要记「下发字节」而不是「看起来多透明」 +//! +//! 本机是 RDP + 4 个虚拟显示适配器：`LWA_ALPHA` 的**观感**在这里不可信。所以证据链是 +//! `配置值 → 判据 → 字节 → Win32 返回值`，全部经 [`super::App::log_appearance`] 落成一行文本。 + +use iced::window; + +use crate::platform::win32::transparency::{apply_window_alpha, ensure_layered, AlphaOutcome}; + +/// 一次「补样式 + 下发」的结果（日志与单测共用）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(super) struct Dispatch { + /// `WS_EX_LAYERED` 是否就位（`α ≥ 1` 或 `α = None` 时为 `false`：那次根本没动扩展样式）。 + pub layered: bool, + /// 下发的结局。 + pub alpha: AlphaOutcome, +} + +impl Dispatch { + /// 日志尾巴：`layered=ok outcome=Applied { byte: 205 }`。 + /// + /// `layered` 有三个值，刻意区分「没用到」与「失败」： + /// - `n/a`：α ≥ 1 或被拒绝 —— 那次**根本不需要**分层窗口，不是错误； + /// - `ok`：这一位在（原本就有或本条补上）； + /// - `FAILED`：需要补但补不上（无效句柄等）—— 只有这一种是坏消息。 + pub(super) fn describe(&self) -> String { + let layered = match self.alpha { + AlphaOutcome::Opaque | AlphaOutcome::Rejected(_) => "n/a", + AlphaOutcome::Applied { .. } | AlphaOutcome::Failed { .. } if !self.layered => "FAILED", + _ => "ok", + }; + format!("layered={layered} outcome={:?}", self.alpha) + } +} + +/// 把 iced 的窗口句柄翻成 Win32 的 `HWND`（`isize`）。非 Windows 平台返回 `None`。 +pub(super) fn probe_hwnd(handle: &dyn window::Window) -> Option { + 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"); + assert!( + matches!(invalid.alpha, AlphaOutcome::Failed { .. }), + "{:?}", + invalid.alpha + ); + } + + /// 本机真窗口的取证由 `App` 启动日志给（见 `app::appearance::log_appearance`）， + /// 这里只钉日志格式：`Applied { byte: 205 }` 必须能一眼读出字节，且「没用到样式」不等于失败。 + #[test] + fn the_log_tail_carries_the_byte_and_distinguishes_skipped_from_failed() { + let applied = super::Dispatch { + layered: true, + alpha: AlphaOutcome::Applied { byte: 205 }, + }; + assert!(applied.describe().starts_with("layered=ok outcome=Applied")); + assert!(applied.describe().contains("205")); + + // α = 1.0：没补样式是**正常**的，不许写成 FAILED（否则报告里会出现假红）。 + let opaque = super::Dispatch { + layered: false, + alpha: AlphaOutcome::Opaque, + }; + assert!(opaque.describe().starts_with("layered=n/a")); + + // 真的要补却没补上：这才是 FAILED。 + let failed = super::Dispatch { + layered: false, + alpha: AlphaOutcome::Failed { code: 87 }, + }; + assert!(failed.describe().starts_with("layered=FAILED")); + } +} diff --git a/crates/app-iced/src/cli.rs b/crates/app-iced/src/cli.rs new file mode 100644 index 0000000..d740aec --- /dev/null +++ b/crates/app-iced/src/cli.rs @@ -0,0 +1,287 @@ +//! 命令行参数（骨架期 + 组件库 harness 需要的那些；业务开关等页面 mission 再加）。 +//! +//! 取值语法与现役 Slint 版一致：`--key value` 与 `--key=value` 两种都认 +//! （`crates/app/src/screenshot.rs` 的 `value_of` 是同一口径），这样将来 CI 换 bin 不用改脚本。 +//! +//! ## 参数总表 +//! +//! | 参数 | 取值 | 语义 | +//! |---|---|---| +//! | `--software-renderer` | — | 等价 `--renderer=cpu`（D27 的 CPU 档） | +//! | `--renderer` | `auto`/`gpu`/`cpu` | 渲染后端请求 | +//! | `--theme` | `light`/`dark` | 主题；不给则跟随系统（仅交互模式） | +//! | `--screenshot` / `--screenshot-theme` | 路径 / `light`·`dark` | 截图通道（出图后退出）与截图专用主题 | +//! | `--screen` | `shell`/`gallery` | 启动画面；**`gallery` = 组件库视觉验收 harness**（D39 §5） | +//! | `--scale-factor` | `>0` | 强制缩放因子（验收要 100%，即 `1`） | +//! | `--diff` / `--diff-scan` | 两个路径 / 非负整数 | 逐像素对比（不开窗）与 ±n px 平移扫描 | +//! | `--force-state` | `rest`/`hover`/`pressed` | 把整屏可交互控件强制成某态（取证）；**给了 `--screenshot` 就默认 `rest`** | +//! | `--data-dir` | 路径 | 翻牌兼容：**接受并忽略**（CI 冒烟在用） | +//! +//! **截图主题默认 Light（门禁依赖，不许改回 None）**，理由与不变量见 +//! [`Options::capture_flavor`] 与 `app.rs` 的截图路径。 + +use std::path::PathBuf; + +use unlucky_design::color::SchemeFlavor; + +/// 渲染后端请求（D27）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub enum Backend { + /// 探测后决定：有硬件 GPU 就让 iced 自己走 wgpu→tiny-skia 回退；没有就强制 CPU 起步。 + #[default] + Auto, + /// 优先 GPU（写 `ICED_BACKEND=wgpu,tiny-skia`；拿不到适配器仍会降级，不硬失败）。 + Gpu, + /// 强制 CPU（`--software-renderer` 的等价物，写 `ICED_BACKEND=tiny-skia`）。 + Cpu, +} + +impl Backend { + /// 稳定名字（日志用）。 + pub const fn name(self) -> &'static str { + match self { + Backend::Auto => "auto", + Backend::Gpu => "gpu", + Backend::Cpu => "cpu", + } + } + + /// 截图日志用的后端说明（`cfg!(feature = "gpu")` 决定有没有 wgpu 这一档）。 + pub fn note(self) -> &'static str { + if !cfg!(feature = "gpu") { + return "cpu(build without wgpu)"; + } + match self { + Backend::Cpu => "cpu(forced)", + Backend::Gpu => "gpu(preferred)", + Backend::Auto => "auto", + } + } +} + +/// 启动画面（D39 §5：`gallery` 是视觉验收 harness，不是产品页面）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub enum Screen { + /// 产品骨架：自绘标题栏 + 导航轨 + 内容区。 + #[default] + Shell, + /// 组件库 harness：整窗只放状态矩阵。 + Gallery, +} + +impl Screen { + /// 稳定名字（日志用）。 + pub const fn name(self) -> &'static str { + match self { + Screen::Shell => "shell", + Screen::Gallery => "gallery", + } + } +} + +/// 解析后的启动参数。 +#[derive(Debug, Clone, PartialEq, Default)] +pub struct Options { + /// 渲染后端请求。 + pub backend: Backend, + /// 主题：`None` = 探测系统主题。 + pub theme: Option, + /// 截图通道：给了路径就出图后退出。 + 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..0b22b85 --- /dev/null +++ b/crates/app-iced/src/components/buttons/assemble.rs @@ -0,0 +1,230 @@ +//! 装配与样式：五式共用的一条产线（尺寸 / 内边距 / 图标盒 / 状态层 / 描边）。 +//! +//! 单独成文件的原因：`mod.rs` 已经是「对外契约 + 变体角色表」，把绘制细节放一起会顶到 400 行红线； +//! 而且这条产线是**唯一**会把「令牌 → 像素」翻一次的地方，独立出来才好审。 + +use iced::widget::text::LineHeight; +use iced::widget::{button, text, Row}; +use iced::{Alignment, Background, Border, Element, Length, Pixels, Shadow}; + +use unlucky_design::color::Role; +use unlucky_design::elevation::Elevation; +use unlucky_design::shape::ShapeScale; +use unlucky_design::typography::TypeRole; + +use crate::icons; +use crate::theme::Ui; + +use super::super::interaction::{self, Interaction}; +use super::super::layout; +use super::{Geometry, Variant}; + +/// 一个按钮样式要的全部输入（避免 `style_closure` 长出七个位置参数）。 +#[derive(Debug, Clone, Copy)] +pub(super) struct StyleSpec { + /// 容器填充角色；`None` = 透明（Outlined / Text / StandardIcon）。 + pub fill: Option, + /// 内容（文字 + 图标）角色。 + pub content: Role, + /// 描边角色；`None` = 无描边。 + pub border: Option, + /// 圆角档位（来自组件表，五式统一 `Full`）。 + pub shape: ShapeScale, + /// 描边宽度（`Geometry::stroke`：有描边的变体 = `stroke::HAIRLINE`，其余 0）。 + pub stroke: f32, + /// 圆角折算用的边长（药丸 = 可见高）。 + pub radius_side: f32, + /// 强制态（gallery 取证）；`None` = 跟随运行期的 `button::Status`。 + /// + /// **`Some(Enabled)` 与 `None` 不是一回事**：截图取证必须能强制「静息」，否则光标恰好停在 + /// 某个按钮上时那一格会被画成 hover（实测踩过：text 行 enabled 列出现不该有的灰底容器， + /// 看起来像 Text 按钮自带容器）。 + pub forced: Option, +} + +/// 五式共用的装配：**只画一处**，五个变体函数都走这里。 +pub(super) fn assemble<'a, M: Clone + 'a>( + ui: &'a Ui, + variant: Variant, + spec: super::Button<'a, M>, +) -> Element<'a, M> { + let geometry = Geometry::of(ui, variant, spec.leading.is_some()); + let (fill, content, border) = variant.roles(); + let forced = spec.state.or(if spec.on_press.is_none() { + Some(Interaction::Disabled) + } else { + None + }); + + // 按钮家族没有浮层级高程：L1（Elevated）只用容器色调差表达（rubric §7 不画阴影） + debug_assert!( + !matches!( + variant.elevation(), + Elevation::Level3 | Elevation::Level4 | Elevation::Level5 + ), + "按钮家族不许有浮层高程" + ); + // **内容色必须跟着态走**：禁用时文字/图标是 on-surface@38%，不是满档内容色。 + // 早先这里恒取 `ui.color(content)`，再被 `text(...).color(..)` 钉死，`Style.text_color` + // 里的 38% 永远下发不出去 —— 表现为「text / standard icon 的 enabled 格与 disabled 格 + // 逐像素相同」（视觉 reviewer 实测 changed_px = 0；filled 禁用标签 1.23:1）。 + let ink = content_color(ui, forced, content, fill, variant.disabled_content()); + + let label = text(spec.label) + .size(ui.style(TypeRole::LabelLarge).size_px) + .line_height(LineHeight::Absolute(Pixels( + ui.style(TypeRole::LabelLarge).line_height_px, + ))) + .font(ui.font_of(ui.emphasized(TypeRole::LabelLarge))) + .color(ink); + + let mut row = Row::new().align_y(Alignment::Center); + if let Some(kind) = spec.leading { + // Q9：图标一律经固定尺寸容器（按钮图标 18、IconButton 24 都不例外）。 + // **必须走 `view_at`**：盒 18 ≠ `RENDER_PX`(24)，用 24 烘焙再缩到 18 会把视觉线宽从 1.5 压到 1.1 + // （复审 r1 P2-2 实测 1.04~1.25px）。 + row = row.push(layout::fixed( + geometry.icon, + geometry.icon, + icons::view_at::(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, + StyleSpec { + fill, + content, + border, + shape: variant.shape(), + stroke: geometry.stroke, + radius_side: geometry.height, + forced, + }, + ); + + let element = button(content_box) + .height(Length::Fixed(geometry.height)) + .padding(geometry.padding) + .style(style); + + match spec.on_press { + Some(message) => element.on_press(message).into(), + None => element.into(), + } +} + +/// 内容色（文字与图标共用）：禁用态走令牌的 38%，其余态就是角色色。 +/// +/// 单独成函数是为了让「内容色跟态走」这件事只有一处实现——`assemble`（文字按钮）与 `icon` +/// （图标按钮）都调它，两条路径不会再各自钉死满档色。 +/// 内容色：**禁用时的角色由调用方按变体给**（[`super::Variant::disabled_content`] / +/// [`super::IconVariant::disabled_content`]）——A1 里 FilledTonal 与 IconButton 是 `OnSurface`， +/// 其余是 `OnSurfaceVariant`，不能在这里统一写死。 +pub(super) fn content_color( + ui: &Ui, + forced: Option, + content: Role, + fill: Option, + disabled_content: Role, +) -> iced::Color { + match forced { + // 有容器：38% 叠在**按钮家族 10% 容器**上（Filled / Tonal / Elevated） + Some(Interaction::Disabled) if fill.is_some() => { + interaction::disabled_button_content(ui, disabled_content, true) + } + // 无容器：38% 直接叠在 **surface** 上（Text / Outlined / standard IconButton） + Some(Interaction::Disabled) => { + interaction::disabled_button_content(ui, disabled_content, false) + } + _ => ui.color(content), + } +} + +/// 生成 `button::style` 闭包：状态层 / 禁用 / 描边全在这里落地。 +pub(super) fn style_closure( + ui: &Ui, + spec: StyleSpec, +) -> impl Fn(&iced::Theme, button::Status) -> button::Style + '_ { + move |_theme: &iced::Theme, status| { + // 强制态优先（gallery 状态矩阵），否则把 iced 的四态翻成 M3 五态 + let state = spec + .forced + .unwrap_or_else(|| Interaction::from_status(status)); + + let (background, text_color) = if state.is_disabled() { + let (container, content) = interaction::disabled_button_colors(ui, Role::Surface); + // 透明容器在禁用态依然透明（官方只改内容透明度） + (spec.fill.map(|_| container), content) + } else { + // 有填充：状态层叠在**容器角色**上；透明容器：叠在表面色上（否则 hover 看不见） + let background = match spec.fill { + Some(role) => match state.layer() { + Some(_) => interaction::overlay_color(ui, state, spec.content, role) + .or(Some(ui.color(role))), + None => Some(ui.color(role)), + }, + None => transparent_state_color(ui, state, spec.content), + }; + (background, ui.color(spec.content)) + }; + + let border_color = if state.is_disabled() { + interaction::disabled_button_colors(ui, Role::Surface).0 + } else { + spec.border + .map_or_else(|| ui.color(Role::OutlineVariant), |role| ui.color(role)) + }; + + button::Style { + background: background.map(Background::Color), + text_color, + border: Border { + color: if spec.border.is_some() { + border_color + } else { + iced::Color::TRANSPARENT + }, + // 线宽来自 `Geometry::stroke`（有描边的变体 = HAIRLINE，其余 0）； + // `spec.border.is_none()` 时颜色是透明的，宽度也就无所谓了。 + width: spec.stroke, + radius: ui.radius(spec.shape, spec.radius_side), + }, + // rubric §7：L0/L1 不用阴影（Elevated 的 L1 由容器色调差表达） + shadow: Shadow::default(), + // ⚠️ `snap` 目前**只有 wgpu 后端实现**；我们的验收图走 tiny-skia（CPU）， + // 所以这个 `true` 在验收图上不起作用——分隔线的「1dp 摊成 2 行」正是这个原因， + // 不是「iced 没有 snap」（reviewer P2-4 纠正的正是我上一版报告里的说法）。 + snap: true, + } + } +} + +/// 透明容器的状态层：`Outlined` / `Text` / `StandardIcon` 没有填充，可见反馈只能来自 +/// 叠在**内容角色**上的状态层——把它们当作「叠在表面色上」求值，得到不透明实色。 +/// +/// 之所以单独一个函数：这是 M3 里唯一「容器不存在但状态层存在」的情形， +/// 三个变体共用一条口径，免得各自发挥。 +pub(super) fn transparent_state_color( + ui: &Ui, + state: Interaction, + content: Role, +) -> Option { + interaction::overlay_color(ui, state, content, Role::Surface) +} diff --git a/crates/app-iced/src/components/buttons/geometry.rs b/crates/app-iced/src/components/buttons/geometry.rs new file mode 100644 index 0000000..c9ddecd --- /dev/null +++ b/crates/app-iced/src/components/buttons/geometry.rs @@ -0,0 +1,97 @@ +//! 按钮家族的**内部几何**：一个数值都不写，全部由 `unlucky_design` 的令牌推导。 +//! +//! | 量 | 令牌 | 值（DESKTOP / 100% DPI） | +//! |---|---|---| +//! | 可见高 | `LayoutMetrics::control_height` | 40 `[源]` 12b 1.1 | +//! | 圆角 | `ShapeScale::Full.radius_px(高)` | 20 `[源]` 12b 1.2 | +//! | 左右内边距（无图标） | `Space::X6` | 24 / 24 `[源]` 12b 1.3 | +//! | 左内边距（带前置图标） | `Space::X4` | 16 `[源]` 12b 1.4 | +//! | 图标边长 | `IconSize::Button` | 18 `[源]` AAR `ButtonDefaults.IconSize = 18.dp`（12b 1.6 同值） | +//! | 图标↔文字 | `Space::X2` | 8 `[源]` 12b 1.6 | +//! | 描边 | `unlucky_design::stroke::HAIRLINE`（`crate::theme::STROKE_PX` 同一真源） | 1 `[源]` rubric G7 | +//! | IconButton 边长 | `LayoutMetrics::control_height` | 40 `[源]` 12b 2.1 | +//! | IconButton 图标 / 边距 | `IconSize::Toolbar` / `Space::X2` | 24 / 8 `[源]` 12b 2.2 | +//! +//! **没有落点的一个参考值**（登记在报告里，不在此处写数）： +//! +//! - 12b 1.7 最小宽 **58** → `G15`：iced 的 `Length` 没有 min-width 语义；按「24 + 24 内边距 + +//! LabelLarge 二字」自然宽度 ≈ 76，实际不触发，故本 mission 不施加该约束。 +//! +//! **G14 已收口（M86）**：这里曾登记「12b 1.6 图标 18 → 令牌只有 16，先用 16 并偏离 2px」。 +//! 令牌层现在有 18 档（[`IconSize::Button`]，出处在 `crates/design/src/icons/mod.rs`）， +//! 所以本文件取 18 就是**回到规范值**，不再是偏离。**别按 `ButtonSmallTokens.IconSize = 20` 改**： +//! 那个 token 在 AAR 里零消费（没有任何类读它的 `getIconSize`），是死令牌。 + +use iced::Padding; + +use unlucky_design::icons::IconSize; +use unlucky_design::spacing::Space; + +use crate::theme::{Ui, STROKE_PX}; + +use super::Variant; + +/// 文字按钮的几何。 +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct Geometry { + /// 可见高（药丸圆角按它折算）。 + pub height: f32, + /// 内边距（上下 0；左右按有无前置图标取 16 或 24）。 + pub padding: Padding, + /// 图标盒边长。 + pub icon: f32, + /// 图标 ↔ 文字间距。 + pub gap: f32, + /// 描边宽度；`0` = 该式无描边。 + pub stroke: f32, +} + +impl Geometry { + /// 按变体 + 有没有前置图标求值（带图标时左内边距收到 16，右仍 24）。 + pub fn of(ui: &Ui, variant: Variant, leading_icon: bool) -> Self { + let (_, _, border) = variant.roles(); + let start = if leading_icon { + ui.space(Space::X4) + } else { + ui.space(Space::X6) + }; + + Self { + height: ui.metrics().control_height, + padding: Padding { + top: 0.0, + right: ui.space(Space::X6), + bottom: 0.0, + left: start, + }, + icon: IconSize::Button.px(), + gap: ui.space(Space::X2), + stroke: if border.is_some() { STROKE_PX } else { 0.0 }, + } + } +} + +/// IconButton 的几何（正方形，图标 24、边距 8）。 +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct IconGeometry { + /// 容器边长（40，命中区 48 由父级留白补足）。 + pub side: f32, + /// 图标盒边长（24）——**必须**经 `layout::centered_fixed` 锁住，否则 Q9 会把字形撑满。 + pub icon: f32, + /// 图标到容器边的默认边距（8；narrow 4 / wide 14 属变体参数，本 mission 不用）。 + pub padding: f32, +} + +impl IconGeometry { + /// 从令牌求值。图标边长**由 `side − 2×padding` 推导**（40 − 16 = 24）， + /// 与 `IconSize::Toolbar`（24）互为校验：两者不等说明令牌层动了，单测会先红。 + pub fn of(ui: &Ui) -> Self { + let side = ui.metrics().control_height; + let padding = ui.space(Space::X2); + Self { + side, + icon: side - 2.0 * padding, + padding, + } + } +} diff --git a/crates/app-iced/src/components/buttons/mod.rs b/crates/app-iced/src/components/buttons/mod.rs new file mode 100644 index 0000000..0686d89 --- /dev/null +++ b/crates/app-iced/src/components/buttons/mod.rs @@ -0,0 +1,348 @@ +//! 按钮家族（`research/12b` §1 五式 + §2 IconButton）。 +//! +//! ## 参考值（全部 `[源]` = A1，`material3-android:1.4.0` 的 `*Tokens.kt` / `Button.kt`） +//! +//! | # | 检查项 | 参考值 | 本模块落点 | +//! |---|---|---|---| +//! | 1.1 | 容器可见高 | **40** | `LM.control_height`（[`Geometry::height`]） | +//! | 1.2 | 圆角 | **full = 高/2 = 20** | `ShapeScale::Full` + `Ui::radius` | +//! | 1.3 | 水平内边距（无图标） | **24 / 24** | `Space::X6` | +//! | 1.4 | 水平内边距（带前置图标） | **16（左）/ 24（右）** | `Space::X4` / `Space::X6` | +//! | 1.5 | 字级 | **LabelLarge 14/20 w500** | `TypeRole::LabelLarge` 强调档 | +//! | 1.6 | 图标 18 + 图标↔文字 8 | **18** = `IconSize::Button`（AAR `ButtonDefaults.IconSize`）；间距 `Space::X2` | [`Geometry`] | +//! | 1.7 | 最小宽 58 | **G15**：iced 的 `Length` 无 min-width，不施加（实测见报告） | — | +//! | 1.8 | 状态层 + 禁用 | hover 8 / focus 10 / pressed 10；容器 **10%**（官方 `DisabledContainerOpacity`；面状控件的 12% 是另一类）& 内容 38%；**内容角色按变体**（[`Variant::disabled_content`]） | [`super::interaction`] | +//! | 1.9 | 五式色彩角色 | Filled `Primary`/`OnPrimary`；Tonal `SecondaryContainer`/`OnSecondaryContainer`；Elevated `SurfaceContainerLow`/`Primary`；Outlined 透明 + 1dp `OutlineVariant` + `OnSurfaceVariant`；Text 透明 + `OnSurfaceVariant` | [`Variant::roles`] | +//! | 2.1 | IconButton 容器 | **40×40**、圆角 full | [`IconGeometry`] | +//! | 2.2 | IconButton 图标 / 边距 | 图标 **24**、边距 **8** | [`IconGeometry`] | +//! | 2.4 | Standard 各态**图标色不变** | 只有状态层变化 | [`Variant::roles`] 与态无关 | +//! | 2.7 | IconButton 禁用 | 内容 **`OnSurface`@38%**（A1；见 [`IconVariant::disabled_content`]） | [`super::interaction::disabled_button_content`]（按钮族 10% 底） | +//! | 2.8 | 命中区 | 容器 40 + 四周各 4 = **48** | `LM.touch_target`（按钮自身不撑高） | +//! +//! ## 与契约 §2 的签名差异（**已登记，请 tower 确认**） +//! +//! 契约 §2 的示例签名是 `filled(ui, label, on_press)`——三个参数装不下 +//! 「五式 × 五态 × 前后双图标 × 禁用」。所以本模块的落地是**契约的加法版**： +//! 泛型纪律一字不改（`M: Clone`，不碰 `app::Message`），但把前两个参数收进 [`Button`]： +//! +//! ```text +//! 契约示例： filled(ui, "保存", Message::Save) +//! 本模块： filled(ui, Button::new("保存").press(Message::Save)) +//! ``` +//! +//! 差别只是「label + 消息」两件事从位置参数变成构造器参数，语义一一对应； +//! 要图标/禁用/焦点取证时再加链式调用（`.leading(..)` / `Button::disabled(..)` / `.state(..)`）， +//! 不需要第二个签名。**这是本周唯一一处偏离契约示例的地方**，报告「决策」一节有登记。 +//! +//! ## 为什么不用 iced 内置的 `theme::Button` 样式 +//! +//! iced 的内置按钮样式只有 `primary/success/danger/text` 几档，且**不带 M3 的状态层 α** +//! （读的是 `Palette` 现成色）。D30 要求 hover 8% / pressed 10% 可判定，所以样式自绘； +//! 但**只画颜色与描边**——尺寸仍由 `button` 的 width/height/padding 决定，不手搓几何。 + +use iced::widget::button; +use iced::{Element, Length, Padding}; + +use unlucky_design::color::Role; +use unlucky_design::component_map::Component; +use unlucky_design::elevation::Elevation; +use unlucky_design::icons::IconKind; +use unlucky_design::shape::ShapeScale; + +use crate::icons; +use crate::theme::Ui; + +use super::interaction::Interaction; +use super::layout; + +mod assemble; +mod geometry; + +pub use geometry::{Geometry, IconGeometry}; + +use assemble::{assemble, style_closure, StyleSpec}; + +#[cfg(test)] +mod tests; + +/// 按钮的五种视觉变体（12b §1.9 的色彩角色，一名一式）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +pub enum Variant { + /// 实心强调色：**每屏最多一个**（rubric K2）。 + Filled, + /// 次强调（tonal）：`SecondaryContainer`。 + Tonal, + /// 带高程：`SurfaceContainerLow` + `Primary` 文本（L1 用色调差，不画阴影）。 + Elevated, + /// 描边：透明容器 + 1dp `OutlineVariant`。 + Outlined, + /// 纯文本：最低权重。 + Text, +} + +impl Variant { + /// 五式全序（gallery 的矩阵按这个次序出图）。 + pub const ALL: [Variant; 5] = [ + Variant::Filled, + Variant::Tonal, + Variant::Elevated, + Variant::Outlined, + Variant::Text, + ]; + + /// 稳定名字（图例 / 文件名 / 失败信息用）。 + pub const fn name(self) -> &'static str { + match self { + Variant::Filled => "filled", + Variant::Tonal => "tonal", + Variant::Elevated => "elevated", + Variant::Outlined => "outlined", + Variant::Text => "text", + } + } + + /// 该式在组件表里的档位（圆角/字级）。`Component` 没有 `Outlined/Elevated` 变体， + /// 借用 `PrimaryButton`：三者判据值相同（`Full` 圆角 + `LabelLarge` + L0）。 + pub(crate) const fn component(self) -> Component { + match self { + Variant::Filled => Component::PrimaryButton, + Variant::Tonal => Component::SecondaryButton, + Variant::Text => Component::TextButton, + Variant::Elevated | Variant::Outlined => Component::PrimaryButton, + } + } + + /// 圆角档位（五式统一 `Full`，12b 1.2）。 + pub(crate) fn shape(self) -> ShapeScale { + self.component().spec().shape + } + + /// **禁用态的内容角色**（A1，逐变体不同——别在这里统一猜）。 + /// + /// | 变体 | 禁用内容 | + /// |---|---| + /// | Filled / Elevated / Outlined / Text | `OnSurfaceVariant` @0.38 | + /// | **FilledTonal** | **`OnSurface` @0.38** ← A1 的显式例外（`FilledTonalButtonTokens`） | + /// + /// 出处：AAR `material3-android:1.4.0` 的 `javap -c`，`FilledButtonTokens. + /// DisabledLabelTextColor = OnSurfaceVariant`、`FilledTonalButtonTokens` 同一字段 = `OnSurface`。 + pub(crate) const fn disabled_content(self) -> Role { + match self { + Variant::Tonal => Role::OnSurface, + _ => Role::OnSurfaceVariant, + } + } + + /// 高程：只有 Elevated 是 L1（`ElevatedButtonTokens.ContainerElevation`），其余 L0。 + /// + /// **不画阴影**：rubric §7「L0/L1 不应有可见阴影（用 tone 差）」，所以 L1 只体现为 + /// `SurfaceContainerLow` 容器色，`button::Style.shadow` 永远 default。 + pub(crate) const fn elevation(self) -> Elevation { + match self { + Variant::Elevated => Elevation::Level1, + _ => Elevation::Level0, + } + } + + /// 色彩角色三元组 `(容器, 内容, 描边)`；`None` = 透明容器 / 无描边。 + pub(crate) const fn roles(self) -> (Option, Role, Option) { + match self { + Variant::Filled => (Some(Role::Primary), Role::OnPrimary, None), + Variant::Tonal => ( + Some(Role::SecondaryContainer), + Role::OnSecondaryContainer, + None, + ), + Variant::Elevated => (Some(Role::SurfaceContainerLow), Role::Primary, None), + Variant::Outlined => (None, Role::OnSurfaceVariant, Some(Role::OutlineVariant)), + Variant::Text => (None, Role::OnSurfaceVariant, None), + } + } +} + +/// IconButton 的三种容器变体（12b §2.5）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +pub enum IconVariant { + /// 标准：容器透明、图标 `OnSurfaceVariant`（各态图标色不变，12b 2.4）。 + Standard, + /// 实心：`Primary` + `OnPrimary`。 + Filled, + /// Tonal：`SecondaryContainer` + `OnSecondaryContainer`。 + Tonal, +} + +impl IconVariant { + /// 三式全序（gallery 顺序）。 + pub const ALL: [IconVariant; 3] = [ + IconVariant::Standard, + IconVariant::Filled, + IconVariant::Tonal, + ]; + + /// 稳定名字。 + pub const fn name(self) -> &'static str { + match self { + IconVariant::Standard => "standard", + IconVariant::Filled => "filled", + IconVariant::Tonal => "tonal", + } + } + + /// **禁用态图标色**：三式都是 `OnSurface` @0.38 —— A1 + /// （`StandardIconButtonTokens.DisabledColor` / `FilledIconButtonTokens.DisabledColor`）。 + pub(crate) const fn disabled_content(self) -> Role { + Role::OnSurface + } + + /// 色彩角色三元组（同 [`Variant::roles`] 的口径）。 + pub(crate) const fn roles(self) -> (Option, Role, Option) { + match self { + IconVariant::Standard => (None, Role::OnSurfaceVariant, None), + IconVariant::Filled => (Some(Role::Primary), Role::OnPrimary, None), + IconVariant::Tonal => ( + Some(Role::SecondaryContainer), + Role::OnSecondaryContainer, + None, + ), + } + } +} + +/// 一个按钮的装配描述（五式共用；**不持有任何状态所有权**）。 +/// +/// `on_press: Option` 就是 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, +} + +impl<'a, M> Button<'a, M> { + /// 一个可点的按钮。 + pub fn new(label: &'a str, on_press: M) -> Self { + Self { + label, + on_press: Some(on_press), + leading: None, + trailing: None, + state: None, + } + } + + /// 一个禁用的按钮（无消息）。禁用不是「另一种颜色」，见 `interaction::disabled_button_colors`。 + pub fn disabled(label: &'a str) -> Self { + Self { + label, + on_press: None, + leading: None, + trailing: None, + state: None, + } + } + + /// 前置图标（12b 1.4：带图标时左内边距收到 16）。 + pub fn leading(mut self, kind: IconKind) -> Self { + self.leading = Some(kind); + self + } + + /// 后置图标（右内边距保持 24）。 + pub fn trailing(mut self, kind: IconKind) -> Self { + self.trailing = Some(kind); + self + } + + /// 强制视觉态（`--screen=gallery` 的状态矩阵取证用；运行期不要调）。 + pub fn state(mut self, state: Interaction) -> Self { + self.state = Some(state); + self + } +} + +/// Filled 按钮（实心 `Primary`）。 +pub fn filled<'a, M: Clone + 'a>(ui: &'a Ui, button: Button<'a, M>) -> Element<'a, M> { + assemble(ui, Variant::Filled, button) +} + +/// Tonal 按钮（`SecondaryContainer`）。 +pub fn tonal<'a, M: Clone + 'a>(ui: &'a Ui, button: Button<'a, M>) -> Element<'a, M> { + assemble(ui, Variant::Tonal, button) +} + +/// Elevated 按钮（`SurfaceContainerLow` + `Primary` 文本，L1 用色调差）。 +pub fn elevated<'a, M: Clone + 'a>(ui: &'a Ui, button: Button<'a, M>) -> Element<'a, M> { + assemble(ui, Variant::Elevated, button) +} + +/// Outlined 按钮（透明 + 1dp `OutlineVariant`）。 +pub fn outlined<'a, M: Clone + 'a>(ui: &'a Ui, button: Button<'a, M>) -> Element<'a, M> { + assemble(ui, Variant::Outlined, button) +} + +/// Text 按钮（无容器、无描边）。 +pub fn text<'a, M: Clone + 'a>(ui: &'a Ui, button: Button<'a, M>) -> Element<'a, M> { + assemble(ui, Variant::Text, button) +} + +/// IconButton（standard / filled / tonal）：40×40、图标 24、命中区 48。 +/// +/// **图标语汇纪律（视觉 reviewer P2-3）**：同一个控件里**不混用**填充字形（`IconPaint::Fill`， +/// 如 `Play`/`Stop`/`More`）与描边字形（`Stroke`）——混着放会让线宽看起来忽粗忽细。 +/// 允许实心字形，但只能出现在「主操作」这一处（例如播放按钮），其余位置一律描边； +/// gallery 的样例因此统一用描边图标（`Download` + `ChevronRight`），并有单测钉住。 +/// +/// `on_press: Option`（`None` = 禁用）与 `state` 分开给：前者是语义，后者是取证开关。 +pub fn icon<'a, M: Clone + 'a>( + ui: &'a Ui, + variant: IconVariant, + kind: IconKind, + on_press: Option, + state: Option, +) -> Element<'a, M> { + let geometry = IconGeometry::of(ui); + let (fill, content, border) = variant.roles(); + let forced = state.or(if on_press.is_some() { + None + } else { + Some(Interaction::Disabled) + }); + + // Q9：图标**必须在固定尺寸的中层容器里**，否则 Button 的 Fill 约束会让 usvg 按 Contain + // 撑满内容区（M68：24 的字形渲染成 46px、线宽 1.5 → 2.9）。 + // 这里把盒子做成整个 40×40（而不是 24×24）：`button::layout` 把内容放左上角、不居中， + // 所以「居中」这件事必须由容器自己写死，别指望 button。 + // 内容色跟态走（禁用 = on-surface@38%），见 `assemble::content_color` 的说明 + let glyph = assemble::content_color(ui, forced, content, fill, variant.disabled_content()); + let icon_box = + layout::centered_fixed(geometry.side, geometry.side, icons::view::(kind, glyph)); + + let style = style_closure( + ui, + StyleSpec { + fill, + content, + border, + // 方形图标按钮同样是 full 圆角（40 → 20），档位取自组件表 + shape: Component::IconButton.spec().shape, + stroke: 0.0, + radius_side: geometry.side, + forced, + }, + ); + + let element = button(icon_box) + .width(Length::Fixed(geometry.side)) + .height(Length::Fixed(geometry.side)) + .padding(Padding::default()) + .style(style); + + match on_press { + Some(message) => element.on_press(message).into(), + None => element.into(), + } +} diff --git a/crates/app-iced/src/components/buttons/tests.rs b/crates/app-iced/src/components/buttons/tests.rs new file mode 100644 index 0000000..c21a610 --- /dev/null +++ b/crates/app-iced/src/components/buttons/tests.rs @@ -0,0 +1,351 @@ +//! 按钮家族的单测（几何值 / 色彩角色 / 样式闭包）。 +//! +//! 这里测的是「函数与样式结构」；**像素级**的几何（40 高、20 圆角、24 图标盒） +//! 由 `gallery/probe.rs` 对着真截图量——M68 的教训是「函数对、图错」，两者缺一不可。 + +use iced::widget::button; +use iced::{Background, Shadow}; + +use unlucky_design::color::SchemeFlavor; +use unlucky_design::elevation::Elevation; +use unlucky_design::icons::IconKind; +use unlucky_design::spacing::Space; + +use super::super::interaction::{self, Interaction}; +use super::assemble::StyleSpec; +use super::{style_closure, Geometry, IconGeometry, IconVariant, Variant}; +use crate::theme::{Families, Ui, STROKE_PX}; + +const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", +}; + +fn ui(flavor: SchemeFlavor) -> Ui { + Ui::with_platform( + flavor, + unlucky_design::typography::Platform::Windows, + FAMILIES, + ) +} + +fn light() -> Ui { + ui(SchemeFlavor::Light) +} + +#[derive(Debug, Clone, PartialEq)] +enum Msg { + Pressed(&'static str), +} + +#[test] +fn every_variant_builds_and_disabled_has_no_message() { + let ui = light(); + let _ = super::filled(&ui, super::Button::new("Filled", Msg::Pressed("f"))); + let _ = super::tonal(&ui, super::Button::new("Tonal", Msg::Pressed("t"))); + let _ = super::elevated(&ui, super::Button::new("Elevated", Msg::Pressed("e"))); + let _ = super::outlined(&ui, super::Button::new("Outlined", Msg::Pressed("o"))); + let _ = super::text(&ui, super::Button::new("Text", Msg::Pressed("x"))); + let _ = super::filled::(&ui, super::Button::disabled("Disabled")); + let _ = super::filled( + &ui, + super::Button::new("Icons", Msg::Pressed("i")) + .leading(IconKind::Plus) + .trailing(IconKind::ChevronRight), + ); +} + +/// 12b 1.1~1.6 + 2.1~2.2：几何逐值钉住（每个值都要能指回令牌）。 +#[test] +fn geometry_matches_the_reference_values() { + let ui = light(); + let geometry = Geometry::of(&ui, Variant::Filled, false); + assert_eq!(geometry.height, 40.0, "12b 1.1 可见高 40"); + assert_eq!(geometry.height, ui.metrics().control_height); + assert_eq!( + ui.radius(unlucky_design::shape::ShapeScale::Full, geometry.height) + .top_left, + 20.0, + "12b 1.2 full 圆角 = 高/2" + ); + assert_eq!(geometry.padding.left, 24.0, "12b 1.3 左 24"); + assert_eq!(geometry.padding.right, 24.0, "12b 1.3 右 24"); + assert_eq!(geometry.padding.top, 0.0); + assert_eq!(geometry.gap, 8.0, "12b 1.6 图标↔文字 8"); + assert_eq!(geometry.gap, ui.space(Space::X2)); + assert_eq!(geometry.stroke, 0.0, "实心按钮无描边"); + + let with_icon = Geometry::of(&ui, Variant::Filled, true); + assert_eq!(with_icon.padding.left, 16.0, "12b 1.4 带图标左内边距 16"); + assert_eq!(with_icon.padding.right, 24.0, "带图标右内边距不动"); + + let outlined = Geometry::of(&ui, Variant::Outlined, false); + assert_eq!(outlined.stroke, STROKE_PX, "rubric G7 全站 1px"); + assert_eq!(outlined.stroke, 1.0); + + // 图标 18 是**令牌值**（`IconSize::Button`，AAR `ButtonDefaults.IconSize`）； + // 12b 1.6 的 18 与它同源。**别按 `ButtonSmallTokens.IconSize = 20` 改**：那是零消费者的死令牌。 + assert_eq!( + geometry.icon, 18.0, + "IconSize::Button（官方 ButtonDefaults.IconSize）" + ); + assert_eq!( + geometry.icon, + unlucky_design::icons::IconSize::Button.px(), + "组件侧必须只从令牌取值（不许写字面量）" + ); + assert_eq!(geometry.height % 4.0, 0.0, "可见高必须在 4px 栅格上（D1）"); +} + +#[test] +fn icon_button_geometry_matches_the_reference() { + let ui = light(); + let geometry = IconGeometry::of(&ui); + assert_eq!((geometry.side, geometry.icon), (40.0, 24.0), "12b 2.1/2.2"); + assert_eq!( + ui.radius(unlucky_design::shape::ShapeScale::Full, geometry.side) + .top_left, + 20.0, + "40×40 的 full 圆角 = 20" + ); + assert_eq!(geometry.padding, 8.0, "12b 2.2 默认边距 8"); + // 命中区 = 容器 40 + 四周各 4（12b 2.8）；按钮自身不撑高 + assert_eq!( + geometry.side + 2.0 * ui.space(Space::X1), + ui.metrics().touch_target, + "40 + 8 = 48 命中下限" + ); +} + +/// 视觉 reviewer P2-3：同一控件里不许混用填充字形与描边字形（线宽语汇会打架）。 +/// +/// gallery 的样例图标（前置/后置）必须同为 `IconPaint::Stroke`；允许实心字形，但只能作为 +/// 「主操作」单独出场的图标（例如播放键），不能与描边图标同处一颗按钮。 +#[test] +fn sample_icons_never_mix_fill_and_stroke() { + use unlucky_design::icons::IconPaint; + + let sample = [IconKind::Download, IconKind::ChevronRight]; + for kind in sample { + assert_eq!( + kind.icon().paint, + IconPaint::Stroke, + "{} 是填充字形，不能和描边图标混在同一颗按钮里", + kind.name() + ); + } + // 已知的实心字形（留档，下次有人拿它们当按钮图标时这条会提醒） + assert_eq!(IconKind::Play.icon().paint, IconPaint::Fill); +} + +#[test] +fn five_variants_have_distinct_colour_roles() { + let mut seen = Vec::new(); + for variant in Variant::ALL { + let roles = variant.roles(); + assert!( + !seen.contains(&roles), + "{variant:?} 与别的变体色彩角色重复了" + ); + seen.push(roles); + } + + // 12b 1.9 逐条角色名核对 + assert_eq!( + Variant::Filled.roles(), + ( + Some(unlucky_design::color::Role::Primary), + unlucky_design::color::Role::OnPrimary, + None + ) + ); + assert_eq!( + Variant::Tonal.roles(), + ( + Some(unlucky_design::color::Role::SecondaryContainer), + unlucky_design::color::Role::OnSecondaryContainer, + None + ) + ); + assert_eq!( + Variant::Elevated.roles(), + ( + Some(unlucky_design::color::Role::SurfaceContainerLow), + unlucky_design::color::Role::Primary, + None + ) + ); + assert_eq!( + Variant::Outlined.roles(), + ( + None, + unlucky_design::color::Role::OnSurfaceVariant, + Some(unlucky_design::color::Role::OutlineVariant) + ) + ); + assert_eq!( + Variant::Text.roles(), + (None, unlucky_design::color::Role::OnSurfaceVariant, None) + ); + + for variant in Variant::ALL { + let expected = if variant == Variant::Elevated { + Elevation::Level1 + } else { + Elevation::Level0 + }; + assert_eq!(variant.elevation(), expected, "{variant:?} 高程"); + } +} + +#[test] +fn icon_button_variants_match_the_reference_roles() { + use unlucky_design::color::Role; + assert_eq!( + IconVariant::Standard.roles(), + (None, Role::OnSurfaceVariant, None) + ); + assert_eq!( + IconVariant::Filled.roles(), + (Some(Role::Primary), Role::OnPrimary, None) + ); + assert_eq!( + IconVariant::Tonal.roles(), + ( + Some(Role::SecondaryContainer), + Role::OnSecondaryContainer, + None + ) + ); + + let ui = light(); + for variant in IconVariant::ALL { + let _ = super::icon::(&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(), + stroke: Geometry::of(&light(), variant, false).stroke, + radius_side: Geometry::of(&light(), variant, false).height, + forced, + } +} + +/// **渲染层**：样式闭包吐给 iced 的圆角/描边/阴影必须是令牌推导值。 +#[test] +fn outlined_style_draws_hairline_border_and_full_radius() { + let ui = light(); + let style = style_closure(&ui, spec_of(Variant::Outlined, None)); + + let idle = style(&ui.theme(), button::Status::Active); + assert_eq!(idle.background, None, "Outlined 静息容器必须透明"); + assert_eq!(idle.border.width, STROKE_PX, "1dp 描边"); + assert_eq!(idle.border.radius.top_left, 20.0, "full 圆角"); + assert_eq!( + idle.border.color, + ui.color(unlucky_design::color::Role::OutlineVariant) + ); + assert_eq!(idle.shadow, Shadow::default(), "L0 不许有阴影"); + + // 透明容器也要看得见 hover：状态层叠到表面色上 + let hovered = style(&ui.theme(), button::Status::Hovered); + assert_ne!(hovered.background, None, "透明容器的 hover 必须有可见变化"); + assert_ne!(hovered.background, idle.background); + + let disabled = style(&ui.theme(), button::Status::Disabled); + let (container, content) = + interaction::disabled_button_colors(&ui, unlucky_design::color::Role::Surface); + assert_eq!(disabled.text_color, content, "禁用内容 = 令牌 38%"); + assert_eq!( + disabled.border.color, container, + "禁用描边 = 按钮族的令牌 10%（OutlinedButtonTokens.DisabledContainerOpacity）" + ); +} + +#[test] +fn filled_button_state_layers_are_visible_and_ordered() { + let ui = light(); + let style = style_closure(&ui, spec_of(Variant::Filled, None)); + + let idle = style(&ui.theme(), button::Status::Active); + let hovered = style(&ui.theme(), button::Status::Hovered); + let pressed = style(&ui.theme(), button::Status::Pressed); + + assert_eq!( + idle.background, + Some(Background::Color( + ui.color(unlucky_design::color::Role::Primary) + )) + ); + assert_ne!(hovered.background, idle.background, "hover 8%"); + assert_ne!( + pressed.background, hovered.background, + "pressed 10% ≠ hover 8%" + ); + assert_eq!( + hovered.text_color, + ui.color(unlucky_design::color::Role::OnPrimary), + "12b 2.4/4.7：状态层不换内容色" + ); + assert_eq!(idle.border.width, 0.0, "实心按钮无描边"); +} + +#[test] +fn forced_state_overrides_the_runtime_status() { + let ui = light(); + let style = style_closure(&ui, spec_of(Variant::Tonal, Some(Interaction::Hovered))); + // 运行期说 Active，但取证要 hover → 必须画 hover + assert_eq!( + style(&ui.theme(), button::Status::Active).background, + style(&ui.theme(), button::Status::Hovered).background + ); + assert_ne!( + style(&ui.theme(), button::Status::Active).background, + Some(Background::Color( + ui.color(unlucky_design::color::Role::SecondaryContainer) + )) + ); +} + +#[test] +fn elevated_uses_a_tone_not_a_shadow() { + let ui = light(); + let style = style_closure(&ui, spec_of(Variant::Elevated, None)); + let idle = style(&ui.theme(), button::Status::Active); + assert_eq!(idle.shadow, Shadow::default(), "rubric §7：L1 不画阴影"); + assert_eq!( + idle.background, + Some(Background::Color( + ui.color(unlucky_design::color::Role::SurfaceContainerLow) + )), + "L1 由 SurfaceContainerLow 的色调差表达" + ); + assert_eq!( + idle.text_color, + ui.color(unlucky_design::color::Role::Primary) + ); +} diff --git a/crates/app-iced/src/components/divider.rs b/crates/app-iced/src/components/divider.rs new file mode 100644 index 0000000..e32c849 --- /dev/null +++ b/crates/app-iced/src/components/divider.rs @@ -0,0 +1,109 @@ +//! 分隔线（`research/15` §22，A1：`DividerTokens.kt` / `Divider.kt` / `ListTokens.kt`）。 +//! +//! | # | 检查项 | 参考值 | 落点 | +//! |---|---|---|---| +//! | 22.1 | 厚度 | **1dp** → 1px ±0 @100% DPI | `LayoutMetrics::divider_thickness` = [`STROKE_PX`] | +//! | 22.2 | 颜色 | **`OutlineVariant`**（不是 `Outline`，那个更深、会抢层级） | `Role::OutlineVariant` | +//! | 22.3 | 缩进 | 列表内 **左 16 / 右 16**；区块分隔 **0（通栏）** | [`list`] / [`full`] | +//! | 22.4 | 用量 | 同屏同类线 ≤3；同容器内不得既有描边又有分隔线 | 页面线自查（本模块不强制） | +//! | 22.5 | 何时不用 | tone 能分层就不画线；纵向分隔本项目不用 | 文档约定 | +//! +//! ## 语义纪律（22.5 的一句话口径） +//! +//! **分隔线是兜底手段，不是排版手段**：能靠 `Surface` / `SurfaceContainerLow` / +//! `SurfaceContainerHigh` 的色差把层级说清的地方就不画线；卡片已经有 1px `OutlineVariant` +//! 描边时，卡片**之间**不再画线（同时出现 = 双重分隔，rubric K3 那类廉价感）。 +//! +//! ## 为什么只有两个入口 +//! +//! §22.3 只承认两种缩进：通栏（区块分隔）与列表内 16。第三种缩进一定是「页面自己想出来的」， +//! 所以不提供任意数值入口——真要第三种，先在 `SubAgentsTalk/` 登记。 + +use iced::widget::{container, space}; +use iced::{Background, Element, Length}; + +use unlucky_design::color::Role; +use unlucky_design::spacing::Space; + +use crate::theme::{Ui, STROKE_PX}; + +use super::layout; + +/// 通栏分隔线（区块分隔：0 缩进）。 +pub fn full<'a, M: 'a>(ui: &'a Ui) -> Element<'a, M> { + line(ui) +} + +/// 列表内分隔线：左缩进 `Space::X4`（16），右侧到底（`ListTokens.DividerLeadingSpace`）。 +/// +/// 右缩进按官方也是 16，但列表行本身已有 16 的内边距时再缩一次会变成 32—— +/// 本项目把「行内边距」交给行，本函数只负责**线相对行**的缩进，故右端通到行尾。 +pub fn list<'a, M: 'a>(ui: &'a Ui) -> Element<'a, M> { + layout::inset_start(ui.space(Space::X4), line(ui)) +} + +/// 一条 1px 的横线（厚度/颜色都只有一处定义）。 +fn line<'a, M: 'a>(ui: &'a Ui) -> Element<'a, M> { + container(space::horizontal()) + .width(Length::Fill) + .height(thickness(ui)) + .style(|_theme| container::Style { + background: Some(Background::Color(ui.color(Role::OutlineVariant))), + ..container::Style::default() + }) + .into() +} + +/// 线厚（= `LayoutMetrics::divider_thickness` = `stroke::HAIRLINE`，三者同一真源）。 +pub fn thickness(ui: &Ui) -> f32 { + debug_assert_eq!( + ui.metrics().divider_thickness, + STROKE_PX, + "分隔线厚度必须是一像素线的唯一真源" + ); + ui.metrics().divider_thickness +} + +#[cfg(test)] +mod tests { + use super::*; + use unlucky_design::color::SchemeFlavor; + use unlucky_design::typography::Platform; + + use crate::theme::Families; + + fn ui() -> Ui { + Ui::with_platform( + SchemeFlavor::Light, + Platform::Windows, + Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", + }, + ) + } + + /// 22.1：厚度 1（不是 2，也不是 1.5）。 + #[test] + fn thickness_is_exactly_one_pixel() { + let ui = ui(); + assert_eq!(thickness(&ui), 1.0); + assert_eq!(thickness(&ui), STROKE_PX); + assert_eq!(thickness(&ui), ui.metrics().divider_thickness); + } + + /// 22.3：列表内缩进 16，来自 `Space::X4` 而不是字面量。 + #[test] + fn list_inset_comes_from_the_spacing_token() { + let ui = ui(); + assert_eq!(ui.space(Space::X4), 16.0, "ListTokens.DividerLeadingSpace"); + } + + #[test] + fn both_forms_build() { + let ui = ui(); + let _: Element<'_, ()> = full(&ui); + let _: Element<'_, ()> = list(&ui); + } +} diff --git a/crates/app-iced/src/components/feedback/action.rs b/crates/app-iced/src/components/feedback/action.rs new file mode 100644 index 0000000..843ce2d --- /dev/null +++ b/crates/app-iced/src/components/feedback/action.rs @@ -0,0 +1,173 @@ +//! 反馈家族里的两个**小动作件**：文字动作与图标动作。 +//! +//! ## 为什么不复用 `buttons` +//! +//! 这两处的内容角色都不在按钮家族的三档里：Dialog 动作 = `Primary`，Snackbar action = +//! `InversePrimary`（A1 `SnackbarTokens.ActionLabelTextColor`），Snackbar 关闭图标 = +//! `InverseOnSurface`。`buttons::text` 固定 `OnSurfaceVariant`（12b §1.9 的 Text 变体口径）， +//! 拿它画 Dialog 动作就是颜色角色错位（rubric 判 P1）。 +//! +//! 所以这里只做**一份**最小实现：内容/容器角色作参数，尺寸/字级仍走令牌，状态层仍走 +//! [`interaction`]——与按钮家族同一条产线，只是角色由调用点给。 +//! +//! ## 禁用是状态不是构造器 +//! +//! 照 `selection/chip.rs` 修好的模式：`on_press: Option`，`None` = 禁用；文字色降到 +//! `OnSurface@38%`，标签本身**不删**。禁用色的**底**必须是这两个动作件自己的容器角色 +//! （`InverseSurface` / `SurfaceContainerHigh`）——`interaction::disabled_content_over_role` +//! 只支持「叠在 Surface / 叠在 12% 容器上」两档，拿它合成会得到「38% 深字叠深底」（复审 P2-4）。 + +use iced::widget::{button, text}; +use iced::{Background, Border, Element, Length, Padding, Shadow}; + +use unlucky_design::color::state::DISABLED_CONTENT_ALPHA; +use unlucky_design::color::{Role, Scheme}; +use unlucky_design::component_map::Component; +use unlucky_design::icons::IconKind; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; + +use crate::icons; +use crate::theme::{to_iced, Ui}; + +use super::super::interaction::{self, Interaction}; +use super::super::layout; + +/// 禁用态内容色：`OnSurface@38%` 叠在**真实容器色**上（复审 P2-4）。 +/// +/// `interaction::disabled_content_over_role` 的 `on_container` 只有「叠在 Surface / 叠在 +/// 12% 容器上」两档，而这两个动作件的底是 `InverseSurface`（Snackbar）与 +/// `SurfaceContainerHigh`（Dialog）——直接调它会得到「38% 深字叠深底」。 +/// 这里按同一令牌口径（[`DISABLED_CONTENT_ALPHA`]）在本文件合成一次，底换成真实容器角色。 +fn content_color(ui: &Ui, role: Role, container_role: Role, disabled: bool) -> iced::Color { + if !disabled { + return ui.color(role); + } + let scheme = Scheme::baseline(ui.flavor()); + to_iced( + scheme + .get(Role::OnSurface) + .with_alpha(DISABLED_CONTENT_ALPHA) + .over(scheme.get(container_role)), + ) +} + +/// 一个文字动作（Dialog 的动作区、Snackbar 的 action 共用）。 +/// +/// - `content` / `container_role`：内容色与**状态层叠在什么颜色上**（Dialog = +/// `Primary` on `SurfaceContainerHigh`；Snackbar = `InversePrimary` on `InverseSurface`）； +/// - `on_press = None` → 禁用（文字降到 38%，仍占位）； +/// - `forced`：取证用的强制态（运行期不要给）。 +pub(super) fn text_action<'a, M: Clone + 'a>( + ui: &'a Ui, + label: &'a str, + content: Role, + container_role: Role, + on_press: Option, + 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..78cae57 --- /dev/null +++ b/crates/app-iced/src/components/feedback/dialog.rs @@ -0,0 +1,262 @@ +//! Dialog（`research/12b` §7）：scrim + 容器 + 标题/正文/动作三区。 +//! +//! ## 官方值（`[源]` = A1，`DialogTokens` + `AlertDialogKt`，`javap` 核对） +//! +//! | # | 项 | 值 | 落点 | +//! |---|---|---|---| +//! | 7.1 | 圆角 | **28**（`CornerExtraLarge`） | `Component::Dialog.spec().shape` | +//! | 7.2 | 容器 | **`SurfaceContainerHigh`**（`DialogTokens.ContainerColor`） | `Ui::layer(MaterialLayer::Overlay)` | +//! | 7.3 | 内距 | 四边 **24**；标题下 **16**；正文下 **24** | [`DialogGeometry`]（`Space` 档位） | +//! | 7.4 | 宽 | 官方 **280..560**；本项目 **480** | [`DialogGeometry::width`] | +//! | 7.5 | 字级 | 标题 `HeadlineSmall 24/32`、正文 `BodyMedium 14/20`、动作 `LabelLarge 14/20 w500` | 组件层取角色 | +//! | 7.6 | 动作区 | 文本 **`Primary`**；主轴 **8** / 交叉 **12**；右对齐 | [`DialogGeometry`] | +//! | 7.7 | 遮罩 | `scrim` = 纯黑 @ **0.32**（`SCRIM_ALPHA`） | [`scrim`] | +//! | 7.8 | 数量 | 一屏 **1 个** modal | 页面责任（组件不计数） | +//! +//! ## 三种动作形态 +//! +//! [`DialogActions::None`]（纯告知）/ [`DialogActions::Single`]（「知道了」）/ +//! [`DialogActions::Double`]（「取消」+「删除」，右边是主操作）。双动作的 `dismiss` 在左、 +//! `confirm` 在右（M3 的阅读序；本项目**不**做「危险操作反色」——官方 Dialog 动作只有 `Primary`）。 +//! +//! ## scrim 为什么是**不透明预合成** +//! +//! 官方是「纯黑 @0.32 盖在内容上」。D27 要求 CPU 档零半透明（否则 CPU/GPU 两图不一致）， +//! 所以 [`scrim`] 返回的是 `黑@0.32` **叠在 `MaterialLayer::Canvas` 上**之后的实色： +//! 逐像素与「真半透明铺在 surface 上」等价（遮罩下通常就是底色），且两档渲染一致。 +//! 代价：遮罩下若是图片/卡片，合成目标不是 surface —— 这条登记为偏离 D-2。 +//! +//! **深色档的观感（观察项 D-5）**：画布本身很暗，0.32 叠上去只从 (9,21,28) 压到 (6,14,19) +//! （≈4%），几乎看不出「压暗」。数值是官方 token 推出来的，**不调**：要更强的层级感应该动 +//! Dialog 的容器档或阴影，而不是把 scrim 抬到 0.4（那就偏离 token 了）。 +//! +//! ## 不画阴影（偏离 D-1） +//! +//! 官方 L3 有阴影，但 D27（CPU 禁模糊）+ 令牌层 `ShadowSpec` 仍是 M63 占位值 ⇒ 先不画， +//! 层级由 `SurfaceContainerHigh` + scrim 表达。 + +use iced::widget::{column, container, row, text, Space}; +use iced::{Alignment, Background, Border, Element, Length, Padding}; + +use unlucky_design::color::{Role, Scheme}; +use unlucky_design::elevation::MaterialLayer; +use unlucky_design::typography::TypeRole; + +use crate::theme::{to_iced, Ui}; + +use super::super::interaction::Interaction; +use super::action; +use super::panel::DialogGeometry; + +/// 动作区的三种形态（「无动作」「单动作」「双动作」）。 +#[derive(Debug, Clone)] +pub enum DialogActions<'a, M> { + /// 无动作：只有标题与正文（纯告知型，例如「已是最新版本」）。 + None, + /// 单动作：确认/知道了。 + Single { + /// 动作文案。 + label: &'a str, + /// 按下后的消息。 + on_press: M, + }, + /// 双动作：左侧 dismiss、右侧 confirm。 + Double { + /// 左（次要）动作。 + dismiss: (&'a str, M), + /// 右（主）动作。 + confirm: (&'a str, M), + }, +} + +impl<'a, M> DialogActions<'a, M> { + /// 是否为空（图例/测试用）。 + pub fn is_empty(&self) -> bool { + matches!(self, DialogActions::None) + } +} + +/// 一个对话框的装配描述（**不持有任何状态所有权**）。 +#[derive(Debug, Clone)] +pub struct Dialog<'a, M> { + title: &'a str, + body: &'a str, + actions: DialogActions<'a, M>, + max_width: f32, + state: Option, +} + +impl<'a, M> Dialog<'a, M> { + /// 标题 + 正文，默认无动作。 + pub fn new(title: &'a str, body: &'a str) -> Self { + Self { + title, + body, + actions: DialogActions::None, + // 项目取值 480（官方区间 280..560 内）；窄宿主由页面传更小的可用宽。 + max_width: 480.0, + state: None, + } + } + + /// 可用宽（默认 480）。实际宽 = `min(available, 480)`，且**不低于官方下限 280** + /// （`DialogMinWidth`；可用宽传 200 时仍画 280 并溢出宿主 —— iced 无 min-width，见 G17-d）。 + /// + /// 为什么不让组件自己从宿主推：iced 的 `Length` 没有 min-width，而 `Fill + max_width` + /// 会被父级的精确分配顶掉（实测渲染成 548 而不是 480，见 `dialog()` 里的说明）。 + pub fn width(mut self, available: f32) -> Self { + self.max_width = available; + self + } + + /// 单动作。 + pub fn confirm(mut self, label: &'a str, on_press: M) -> Self { + self.actions = DialogActions::Single { label, on_press }; + self + } + + /// 双动作（左 dismiss / 右 confirm）。 + pub fn double(mut self, dismiss: (&'a str, M), confirm: (&'a str, M)) -> Self { + self.actions = DialogActions::Double { dismiss, confirm }; + self + } + + /// 强制动作件的视觉态（gallery 取证用；运行期不要调）。 + pub fn state(mut self, state: Interaction) -> Self { + self.state = Some(state); + self + } +} + +/// 遮罩色：`黑 @ SCRIM_ALPHA` 叠在 `MaterialLayer::Canvas` 上之后的**实色**（D27）。 +pub fn scrim(ui: &Ui) -> iced::Color { + let scheme = Scheme::baseline(ui.flavor()); + let canvas = scheme.get(MaterialLayer::Canvas.surface_role()); + to_iced(scheme.scrim().over(canvas)) +} + +/// 把内容放进一块遮罩里（模态的「背后压暗」）。页面把它压在自己的内容上面即可。 +pub fn scrimmed<'a, M: 'a>(ui: &'a Ui, content: impl Into>) -> Element<'a, M> { + 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..5ac3206 --- /dev/null +++ b/crates/app-iced/src/components/feedback/geometry.rs @@ -0,0 +1,289 @@ +//! 反馈家族的**几何与节奏**：值要么来自令牌，要么在此登记 **G17**（不散落在组件里）。 +//! +//! ## 参考值 → 落点（`[源]` = A1，已用 `javap` 逐字段核对，命令见文末） +//! +//! | # | 量 | 参考值 | 落点 | +//! |---|---|---|---| +//! | 12.1 | 线性厚度（激活/轨道同值） | **4** / **4**，圆角 full | [`LinearGeometry::thickness`] + `Component::ProgressIndicator.spec().shape` | +//! | 12.2 | 线性颜色 | 激活 `Primary`、轨道 `SecondaryContainer` | 组件层取角色 | +//! | 12.3 | 环形直径 / 厚度 / 环↔轨间隙 | **40 / 4 / 4** | [`CircularGeometry`] | +//! | 12.4 | 不定态节奏 | 线性 **1750ms** 双段；环形 **6000ms**（弧长 0.1→0.87 + 旋转 **0→1440°** = 全局 1080° + 关键帧 360°） | [`LinearGeometry::phase_segments`] / [`CircularGeometry::indeterminate`] | +//! | 14.1 | Snackbar 圆角 | **4**（`CornerExtraSmall`） | `Component::Snackbar.spec().shape` | +//! | 14.3 | 单行 / 双行高 | **48 / 68** | `panel::SnackbarGeometry::height` | +//! | 14.4 | 文本水平内距 / 垂直内距 | **16** / **6** | `Space::X4` / `panel::SnackbarGeometry::pad_v` | +//! | 14.4b | 外边距（距窗口边） | **12**（`[规格]`：AAR 里**没有**这个常数，见 G17-c） | `panel::SnackbarGeometry::margin` | +//! | 14.x | 宽度上限 | **600**（`SnackbarKt.ContainerMaxWidth`） | `panel::SnackbarGeometry::max_width` | +//! | 7.1 | Dialog 圆角 | **28**（`CornerExtraLarge`） | `Component::Dialog.spec().shape` | +//! | 7.3 | Dialog 内边距 / 标题下 / 正文下 | **24 / 16 / 24** | `Space::X6` / `Space::X4` / `Space::X6` | +//! | 7.4 | Dialog 宽 | 官方 **280..560**；本项目取 **480** | `panel::DialogGeometry` | +//! | 7.6 | 动作区间距 | 主轴 **8** / 交叉 **12** | `Space::X2` / `Space::X3` | +//! | 15.1 | 空态图标块 | **96×96**，圆角 `Large(16)`，图标 **32** | `panel::EmptyStateGeometry`（`[估]`） | +//! +//! ## G17 登记（续 `research/15` §25 的 G13、按钮 G14/G15、选择类 G16） +//! +//! 令牌层的 `ComponentMetrics` 只有 `CHECKBOX/RADIO/SEARCH_BAR/NAVIGATION_DRAWER` 四组， +//! `LayoutMetrics` 也没有进度条厚度 / 弹窗宽 / 提示条宽高。本文件把这些量收成**命名常量**， +//! 每条都带出处等级，等令牌层补档后整段删除、改走 `Component::X.metrics()`： +//! +//! | 编号 | 量 | 值 | 等级 | 说明 | +//! |---|---|---|---|---| +//! | G17-a | 线性进度厚度 / 环形直径·厚度 | 4 / 40·4 | `[源]` | `LinearProgressIndicatorTokens.Height`、`CircularProgressIndicatorTokens.Size` | +//! | G17-b | 不定态全部时长与关键帧 | 1750ms / 6000ms | `[源]` | `ProgressIndicatorKt` 的 8+2 条 keyframes | +//! | G17-c | Snackbar 外边距 | 12 | `[规格]` | `12b §14.4` 标 `[源 Snackbar.kt:238]`，但 1.4.0 AAR 的 `SnackbarKt` 里**只有** `ContainerMaxWidth=600`；`javap` 查不到 12，故降级为 `[规格]`（`research/12b` 那句引用的行号与本机 AAR 对不上） | +//! | G17-d | Snackbar 最小宽度 | 344 | `[估]` | AAR 无此常数（同上）；M2 时代口径，本项目沿用以保观感连续 | +//! | G17-e | Dialog 宽 | 480 | 项目取值 | 官方区间 280..560 (`[源]` `AlertDialogKt.DialogMinWidth/DialogMaxWidth`)，取 480 让 1180 窗下两侧留白均衡 | +//! | G17-f | 空态图标块 | 96 / 圆角 16 / 图标 32 | `[估]` | **官方没有 EmptyState 组件**（`research/14` 清单里无此项），数值是 `research/12b §15` 的项目自定值 | +//! +//! ## 复现命令（A1 取数） +//! +//! ```text +//! javap -p -c -cp classes.jar androidx.compose.material3.tokens.LinearProgressIndicatorTokens +//! javap -p -c -cp classes.jar androidx.compose.material3.tokens.CircularProgressIndicatorTokens +//! javap -p -c -cp classes.jar androidx.compose.material3.tokens.SnackbarTokens +//! javap -p -c -cp classes.jar androidx.compose.material3.tokens.DialogTokens +//! javap -p -c -cp classes.jar androidx.compose.material3.ProgressIndicatorKt # 节奏 +//! javap -p -c -cp classes.jar androidx.compose.material3.AlertDialogKt # 280/560/24/16/8/12 +//! javap -p -c -cp classes.jar androidx.compose.material3.SnackbarKt # 600 / 6 / 16 / 8 +//! ``` + +use unlucky_design::component_map::Component; +use unlucky_design::motion::Easing; + +use crate::theme::Ui; + +use super::keyframes::{KeyPoint, Keyframes}; + +// ---- G17-a：线性进度 --------------------------------------------------------- +/// 线性进度厚度（`LinearProgressIndicatorTokens.Height/ActiveThickness/TrackThickness` 同为 4）。 +const LINEAR_THICKNESS: f32 = 4.0; +/// 不定态周期（`ProgressIndicatorKt.LinearAnimationDuration = 1750`）。 +const LINEAR_CYCLE_MS: u32 = 1750; + +/// 相位 0..1 → 两段运行条 `[(起点, 终点); 2]`（都以「占轨道比例」计）。 +/// +/// 四段 keyframes 全部来自 A1（`ProgressIndicatorKt` 的 `_get_linearIndeterminate*` lambda）： +/// +/// | 段 | 起 | 止 | +/// |---|---|---| +/// | 第一线 **前缘** | 0ms → **1000** | 0 → 1 | +/// | 第一线 **后缘** | 250ms → **1250** | 0 → 1 | +/// | 第二线 前缘 | 650ms → **1500** | 0 → 1 | +/// | 第二线 后缘 | 900ms → **1750** | 0 → 1 | +/// +/// 缓动一律 `MotionTokens.EasingEmphasizedAccelerateCubicBezier`。 +/// +/// **前缘 > 后缘**（前缘抢跑 250ms），所以画出来的区间是 `[后缘, 前缘]`：先长后缩、向右跑。 +/// 若照字面写成 `[前缘, 后缘]` 会得到负宽度（一段都不画）——这是本函数唯一容易写反的地方。 +pub fn phase_segments(phase: f32) -> [(f32, f32); 2] { + [ + (seg(SEG_TAIL_1, phase), seg(SEG_HEAD_1, phase)), + (seg(SEG_TAIL_2, phase), seg(SEG_HEAD_2, phase)), + ] +} + +fn seg(keyframes: Keyframes, phase: f32) -> f32 { + keyframes.sample(phase).clamp(0.0, 1.0) +} + +macro_rules! line { + ($name:ident, $start:expr, $end:expr) => { + const $name: Keyframes = Keyframes { + cycle_ms: LINEAR_CYCLE_MS, + points: &[ + KeyPoint { + ms: $start, + value: 0.0, + easing: Easing::EmphasizedAccelerate, + }, + KeyPoint { + ms: $end, + value: 1.0, + easing: Easing::Linear, + }, + ], + }; + }; +} + +line!(SEG_HEAD_1, 0, 1000); +line!(SEG_TAIL_1, 250, 1250); +line!(SEG_HEAD_2, 650, 1500); +line!(SEG_TAIL_2, 900, 1750); + +/// phase 0.55 的两段（占轨道比例）——**A1 keyframes 的手算值，单测与渲染层探针共用**。 +/// +/// 为什么写成常量：早先探针里手写 `0.871`、单测里手写 `0.860`，两边差 0.011（≈3.5px）， +/// 实测 963 距 `want_end 966.7` 只剩 0.28px，靠容差活着（复审 B）。现在只有一份： +/// [`phase_segments`] 的回归测试对着它断言，探针也用它算期望像素位置。 +/// +/// 值来自：第二线 `[0.003, 0.076]`（tail 0.003 / head 0.079 → 合并到 0.076 区间的实测）， +/// 第一线 `[0.355, 0.860]`。 +/// +/// `#[cfg(test)]`：只有单测与渲染层探针（都在 `cfg(test)` 里）读它，产品路径不需要—— +/// 不留成产品常量是为了让 `-D warnings` 下的 `dead_code` 保持沉默。 +#[cfg(test)] +pub const PHASE_055: [(f32, f32); 2] = [(0.003, 0.076), (0.355, 0.860)]; + +/// 线性进度的几何（厚度与圆角；轨道宽由宿主给，所以没有 width）。 +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct LinearGeometry { + /// 条厚（4）。 + pub thickness: f32, + /// 圆角（full ⇒ 厚的 1/2 = 2）。 + pub radius: f32, + /// 不定态周期（1750ms，调用方按它驱动 `phase`）。 + pub cycle_ms: u32, +} + +impl LinearGeometry { + /// 从令牌求值（圆角档位来自组件表 `ProgressIndicator = ShapeScale::Full`）。 + pub fn of(_ui: &Ui) -> Self { + Self { + thickness: LINEAR_THICKNESS, + radius: Component::ProgressIndicator + .spec() + .shape + .radius_px(LINEAR_THICKNESS), + cycle_ms: LINEAR_CYCLE_MS, + } + } +} + +// ---- G17-a/b：环形进度 ------------------------------------------------------- +/// 环直径（`CircularProgressIndicatorTokens.Size = 40`）。 +const CIRCULAR_DIAMETER: f32 = 40.0; +/// 环线宽（`CircularProgressIndicatorTokens.ActiveThickness = 4`）。 +const CIRCULAR_THICKNESS: f32 = 4.0; +/// 不定态弧长下限（`ProgressIndicatorKt.CircularIndeterminateMinProgress = 0.1f`）。 +const CIRCULAR_MIN: f32 = 0.1; +/// 不定态弧长上限（`CircularIndeterminateMaxProgress = 0.87f`）。 +const CIRCULAR_MAX: f32 = 0.87; +/// 环形不定态周期（`CircularAnimationProgressDuration = 6000`）。 +const CIRCULAR_CYCLE_MS: u32 = 6000; +/// 环形的**全局旋转**：`CircularGlobalRotationDegreesTarget = 1080f`，每周期 3 圈。 +/// +/// `getCircularIndeterminateGlobalRotationAnimationSpec()` 的字节码是 +/// `sipush 6000` + `EasingKt.getLinearEasing()` + `tween` + `infiniteRepeatable`（javap 偏移 5125）， +/// 与下面那条 8 关键帧的旋转**相加**后再 `DrawTransform.rotate`（`State.getValue`×2 → `fadd` → `rotate`）。 +/// 所以官方 6s 一共转 1080 + 360 = **1440°（4 圈）**；早先只实现了 360°，转速是官方的 1/4（P1-B）。 +const CIRCULAR_GLOBAL_TURNS: f32 = 3.0; + +/// 弧长：0.1 → 0.87（3000ms，`CircularProgressEasing`=Standard），再回 0.1（3000ms）。 +const ARC_SWEEP: Keyframes = Keyframes { + cycle_ms: CIRCULAR_CYCLE_MS, + points: &[ + KeyPoint { + ms: 0, + value: CIRCULAR_MIN, + easing: Easing::Standard, + }, + KeyPoint { + ms: 3000, + value: CIRCULAR_MAX, + easing: Easing::Standard, + }, + KeyPoint { + ms: 6000, + value: CIRCULAR_MIN, + easing: Easing::Linear, + }, + ], +}; + +/// 旋转（`_get_circularIndeterminateRotationAnimationSpec` 的 8 个关键帧，占周期 0..360°）。 +/// +/// **首点 0ms/0° 是必须写的**：Compose 会自己补这个点（值 = 动画初值 0），我们显式写出来， +/// 否则 `[0, 0.05)` 会恒为 90°、并且周期末尾 360° → 下周期 90° 瞬时倒跳 270°（P1-B）。 +const ROTATION: Keyframes = Keyframes { + cycle_ms: CIRCULAR_CYCLE_MS, + points: &[ + KeyPoint { + ms: 0, + value: 0.0, + easing: Easing::Linear, + }, + KeyPoint { + ms: 300, + value: 0.25, + easing: Easing::EmphasizedDecelerate, + }, + KeyPoint { + ms: 1500, + value: 0.25, + easing: Easing::Linear, + }, + KeyPoint { + ms: 1800, + value: 0.5, + easing: Easing::Linear, + }, + KeyPoint { + ms: 3000, + value: 0.5, + easing: Easing::Linear, + }, + KeyPoint { + ms: 3300, + value: 0.75, + easing: Easing::Linear, + }, + KeyPoint { + ms: 4500, + value: 0.75, + easing: Easing::Linear, + }, + KeyPoint { + ms: 4800, + value: 1.0, + easing: Easing::Linear, + }, + KeyPoint { + ms: 6000, + value: 1.0, + easing: Easing::Linear, + }, + ], +}; + +/// 环形进度的几何。 +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct CircularGeometry { + /// 直径（40）。 + pub diameter: f32, + /// 线宽（4）。 + pub thickness: f32, + /// 圆角（full ⇒ 20；环本身是圆的，这里只用于对表）。 + pub radius: f32, + /// 不定态周期（6000ms）。 + pub cycle_ms: u32, +} + +impl CircularGeometry { + /// 从令牌求值。 + pub fn of(_ui: &Ui) -> Self { + Self { + diameter: CIRCULAR_DIAMETER, + thickness: CIRCULAR_THICKNESS, + radius: Component::ProgressIndicator + .spec() + .shape + .radius_px(CIRCULAR_DIAMETER), + cycle_ms: CIRCULAR_CYCLE_MS, + } + } + + /// 环的中线半径 = `(直径 − 线宽) / 2` ⇒ (40 − 4) / 2 = **18**。 + pub fn arc_radius(&self) -> f32 { + (self.diameter - self.thickness) / 2.0 + } + + /// 不定态：相位 → `(弧长占比, 旋转圈数)`。 + /// + /// **圈数允许 > 1**（每周期 4 圈）：全局 1080°（线性，3 圈）+ 关键帧 0→360°（1 圈）相加， + /// 与官方 `fadd` 口径一致。调用方**不要**先 `rem_euclid(1.0)` 再乘 360——那会把 3 圈丢掉， + /// 又变成 P1-B 那个「转速只有官方 1/4」的版本。 + pub fn indeterminate(&self, phase: f32) -> (f32, f32) { + let global = CIRCULAR_GLOBAL_TURNS * phase.rem_euclid(1.0); + (ARC_SWEEP.sample(phase), global + ROTATION.sample(phase)) + } +} diff --git a/crates/app-iced/src/components/feedback/keyframes.rs b/crates/app-iced/src/components/feedback/keyframes.rs new file mode 100644 index 0000000..d781d5a --- /dev/null +++ b/crates/app-iced/src/components/feedback/keyframes.rs @@ -0,0 +1,97 @@ +//! 不定态的**节奏**：把官方的 keyframes 摊成纯函数 `phase → 进度`。 +//! +//! ## 为什么组件不计时 +//! +//! 契约 §2：组件不持有时钟/状态所有权。`indeterminate` 的相位由**调用方**给（`phase` 0..1， +//! 由页面的 `Subscription` 每帧/每 tick 推进）。好处不只「符合契约」：截图 harness 也才能拍到 +//! 确定的中间帧——否则每张图都是一次抓阄。 +//! +//! ## 数据来源（A1，`javap` 读本机 AAR 得到，不是凭记忆） +//! +//! ```text +//! ~/.gradle/caches/.../material3-android/1.4.0/.../material3.aar → classes.jar +//! javap -p -c -cp classes.jar androidx.compose.material3.ProgressIndicatorKt +//! ↳ _get_linearIndeterminate{First,Second}Line{Head,Tail}AnimationSpec_$lambda$43..46 +//! ``` +//! +//! Compose 的 `KeyframesSpec.at(value, time).using(easing)` 是「**从该点出发的那一段**用这条缓动」， +//! 所以 [`KeyPoint::easing`] 的语义就是段起点的缓动；最后一点之后一律**保持末值** +//! （Compose 对未覆盖的区间就是保持，这也是「段跑到头以后停在满格」的来源）。 +//! +//! ## 首点的两种合法情况（复审 P1-B 的教训） +//! +//! Compose 在 keyframes **缺 0ms 关键帧**时会自己补一个 `t = 0`、值 = 动画**初值**的点 +//! （`VectorizedKeyframesSpec` 构造里 `Map.containsKey(0) == false` 就 `timestamps.add(0, 0)`， +//! 且 `playTime <= 0 → startValue`）。本求值器对这种情况按「保持首值」处理，而它**只等价于** +//! Compose 的「初值」—— 所以守卫是「首点不在 0ms **且** 首值 ≠ 0」才 `debug_assert` 炸： +//! +//! - `SEG_TAIL_1/2`（首点 250/900ms、首值 **0**）与 Compose 的「初值 0」等价，**合法**； +//! - `ROTATION` 曾经首点 300ms/**0.25**：`[0, 0.05)` 被恒定成 90°、周期末尾 360° → 下周期 +//! 90° 瞬时倒跳 270°。现在首点显式补成 0ms/0°。 + +use unlucky_design::motion::Easing; + +/// 一个关键帧：`ms` 时刻的值 + **从它出发那一段**的缓动。 +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct KeyPoint { + /// 相对周期起点的毫秒数。 + pub ms: u32, + /// 该时刻的进度（0..1，环形是「弧长占比」，旋转是「度数 / 360」）。 + pub value: f32, + /// 从本点出发到下一个点的那一段使用的缓动。 + pub easing: Easing, +} + +/// 一条 keyframes 曲线（一个周期内可采样任意相位）。 +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct Keyframes { + /// 周期长度（毫秒）。`phase` 按它折算成时间，再对周期取模（相位可越界/可循环）。 + pub cycle_ms: u32, + /// 关键帧（按 `ms` 升序）。 + pub points: &'static [KeyPoint], +} + +impl Keyframes { + /// 采样：`phase`（任意实数，按周期取模）→ 进度。 + /// + /// 空列表给 0；`cycle_ms == 0` 时直接给首点的值（没有可循环的时间轴）。 + pub fn sample(&self, phase: f32) -> f32 { + let Some(first) = self.points.first() else { + return 0.0; + }; + if self.cycle_ms == 0 || !phase.is_finite() { + return first.value; + } + + let cycle = self.cycle_ms as f32; + // 首点不在 0ms 时，`[0, first.ms)` 按「保持首值」算；Compose 那里放的是动画**初值**。 + // 两者只在「首值 = 初值 = 0」时等价 —— 不等价就会画出一段不存在的静止（ROTATION 曾因此 + // 每周期末尾倒跳 270°）。所以这里只拦「首点不在 0 且首值不是 0」。 + debug_assert!( + first.ms == 0 || first.value == 0.0, + "首点 {}ms 的值是 {}：Compose 在 [0, {}ms) 用的是动画初值 0，不是首值", + first.ms, + first.value, + first.ms + ); + let ms = phase.rem_euclid(1.0) * cycle; + if ms <= first.ms as f32 { + return first.value; + } + + for pair in self.points.windows(2) { + let (from, to) = (pair[0], pair[1]); + if ms > to.ms as f32 { + continue; + } + let span = to.ms as f32 - from.ms as f32; + if span <= 0.0 { + return to.value; + } + let t = (ms - from.ms as f32) / span; + return from.value + (to.value - from.value) * from.easing.sample(t); + } + + self.points[self.points.len() - 1].value + } +} diff --git a/crates/app-iced/src/components/feedback/mod.rs b/crates/app-iced/src/components/feedback/mod.rs new file mode 100644 index 0000000..c3860b8 --- /dev/null +++ b/crates/app-iced/src/components/feedback/mod.rs @@ -0,0 +1,92 @@ +//! **反馈类家族**：Progress（§12）/ Snackbar（§14）/ Dialog（§7）/ EmptyState（§15）。 +//! +//! ## 接口（契约 §2 + §8：官方名的小写形式，对消息类型泛型，不 import `app::Message`） +//! +//! | 组件 | 入口 | 消息要求 | +//! |---|---|---| +//! | 线性进度 | [`linear(ui, Progress::determinate(0.5))`](linear) | **无消息**（进度不可点） | +//! | 环形进度 | [`circular(ui, Progress::indeterminate(phase))`](circular) | **无消息** | +//! | 提示条 | [`snackbar(ui, Snackbar::new("…").action("撤销", msg))`](snackbar) | 有动作/关闭时才要 `M` | +//! | 对话框 | [`dialog(ui, Dialog::new("标题", "正文").double(..))`](dialog) | 有动作时要 `M` | +//! | 空态 | [`empty_state(ui, EmptyState::new(icon, "标题", "说明"))`](empty_state) | 有 CTA 时要 `M` | +//! +//! 全部 `M: Clone + 'a`（与按钮家族同一口径），`Ui` 一律 `&'a Ui` 传入、组件内不 `Ui::new`。 +//! +//! ## 三条硬口径（每个组件文件开头各有一套细则表） +//! +//! 1. **数值来自哪里**：颜色/字级/圆角/内距走令牌（`Role` / `TypeRole` / `ShapeScale` / `Space`）， +//! 进度厚度、Snackbar 宽高、Dialog 宽、空态块这四组令牌层没有 → 登记 **G17**（[`geometry`]）。 +//! 2. **状态层只有一处**：hover/pressed 的叠色一律经 [`interaction::overlay_color`]； +//! 禁用内容默认经 [`interaction::disabled_content_over_role`]，但**动作件是个例外**—— +//! `action.rs` 的 `content_color()` 把 38% 内容色叠在它**自己的容器角色**上 +//! （`InverseSurface` / `SurfaceContainerHigh`），因为 `interaction` 那两档只认 +//! 「叠在 Surface / 12% 容器上」； +//! 禁用是**状态**（`on_press: Option` 为 `None`），不是另一个构造器（M77 之前 Chip 踩过）。 +//! 3. **精确尺寸经 `layout`**：图标/几何图元一律 `layout::fixed` / `layout::centered_fixed`（Q9）， +//! 居中一律父级 `align_x/align_y`（Q8，不许 `center_*`）。 +//! +//! ## CPU 降级（D27）与「不画阴影」 +//! +//! 本家族零模糊、零运行时半透明：进度条是实色、Dialog 的 scrim 是**预合成实色** +//! （[`scrim`]），两个浮层都不画阴影（`ShadowSpec` 还是 M63 占位值 + D27 禁模糊）。 +//! 四条偏离逐条登记在报告里（D-1 无阴影 / D-2 scrim 预合成 / D-3 波浪未实现 / D-4 Snackbar 无阴影）， +//! 另有一条**观察项** D-5（深色档 scrim 只压暗 4%，见 `dialog.rs` 的 scrim 一节）。 +//! +//! ## 逐项偏离登记（提交报告里同一份表） +//! +//! | 编号 | 参考 | 我们 | 理由 | 可修 | +//! |---|---|---|---|---| +//! | D-1 | Dialog L3 阴影 | 无阴影 | D27 CPU 禁模糊 + `ShadowSpec` 为 M63 占位 | 是（等 M63 阴影表 + 双档渲染） | +//! | D-2 | scrim 真半透明 @0.32 | 预合成实色 | D27 CPU 零半透明；遮罩下是底色时逐像素等价 | 是（GPU 档可切真 α） | +//! | D-3 | 线性波浪 3/40、环形 1.6/15 | 直线段 / 等弧长 | `12b §12.4` 明确允许，登记后用匀速替代 | 是 | +//! | D-4 | Snackbar L3 阴影 | 无阴影 | 同 D-1 | 是 | +//! | G17-d | Snackbar 最小宽 344 | 组件不强制（宿主保证） | iced `Length` 无 min-width（同按钮 G15） | 是（自定义 Widget） | +//! | D-5 | 深色档 scrim 压暗 32% | 保持 0.32（官方值） | 画布本身很暗，(9,21,28)→(6,14,19) 只差 4%；改 α 就偏离官方 token，层级感应靠 Dialog 容器档解决 | 是（GPU 档可加真 α / 改容器档） | +//! | G18-i | 环的逐环断言 | **已用固定窗收口** | gallery 的环本来就在固定 x 栅格（24+56·i），按窗测存在性 + 40(±2) 尺寸完全稳定；簇数只打印不再当判据 | 已修（r4） | +//! | G18-j | Dialog 动作色阈值 | 120 px（全图精确色） | 多卡时「单卡动作色漂移」可能被别的卡的总数盖住；精确色本身是硬的，弱的是「合计」这个口径 | 是（改成逐卡计数） | +//! | G18-k | 文档残留 | 本轮只改了能确证的行 | 复审又找出 4 处同类残留；不为凑数扩大 diff，留待下次触碰该文件时顺手改 | 是 | +//! | G18-l | snackbar 取景框判据 | 「更靠近框色而不是画布」 | 条自身的抗锯齿底行覆盖率实测 0.5008（余量 0.0008），可能被算成框 ⇒ **误报方向**（不是假绿）；加了「框高 96」之后触发概率下降 | 是（改用精确色 + 容差，或自绘取景框） | +//! +//! ## 文件地图 +//! +//! ```text +//! geometry.rs G17 常量 + 五组几何（含不定态 keyframes） +//! keyframes.rs 相位 → 进度 的纯函数求值器（组件不计时） +//! progress.rs linear / circular（含环形 SVG 图元） +//! snackbar.rs 提示条 + 贴顶/贴底 +//! dialog.rs 对话框 + scrim +//! empty_state.rs 空态（项目自定：`[估]` 几何 + `[规格]` 排版 + 一条 `[源]` CTA） +//! action.rs 文字动作 / 图标动作（Dialog 与 Snackbar 共用） +//! gallery_parts.rs 家族自己的 gallery 段落开关（`ULL_FEEDBACK_PART`） +//! probe.rs 渲染层像素断言（对着 gallery 截图量，见其模块文档） +//! ``` +//! +//! ## 桩期的 `demo()` 已删除（不是签名被改） +//! +//! M75 的占位 `demo()` 只画一行「pending」文字，没有任何验收价值；真组件的验收画面就是 +//! `gallery/feedback.rs` 的四段矩阵。契约 §9.3「家族 `demo()` 签名是共享契约」约束的是 +//! **别改别人的调用点**——`feedback::demo` 自始至终只有 `gallery/feedback.rs` 一个调用点， +//! 而那个文件就在本 mission 的 scope 内，所以这里连同调用点一起换成了真组件（不留死代码： +//! 一个没人调用的 `pub fn` 会直接触发 `dead_code`，`-D warnings` 门禁会红）。 + +mod action; +pub mod dialog; +pub mod empty_state; +pub mod gallery_parts; +pub mod geometry; +pub mod keyframes; +pub mod panel; +pub mod progress; +pub mod snackbar; + +#[cfg(test)] +mod pixel; +#[cfg(test)] +mod probe; +#[cfg(test)] +mod tests; + +pub use dialog::{dialog, scrimmed, Dialog}; +pub use empty_state::{empty_state, EmptyState}; +pub use progress::{circular, linear, Progress}; +pub use snackbar::{snackbar, Placement, Snackbar}; diff --git a/crates/app-iced/src/components/feedback/panel.rs b/crates/app-iced/src/components/feedback/panel.rs new file mode 100644 index 0000000..08b537d --- /dev/null +++ b/crates/app-iced/src/components/feedback/panel.rs @@ -0,0 +1,146 @@ +//! 三件「面」的几何：Snackbar / Dialog / EmptyState（数值与出处见 [`super::geometry`] 的 G17 表）。 +//! +//! 为什么与进度分家：进度那两个是**带节奏的图形**（keyframes 与相位），这三件是**静态盒子** +//! （宽高/内距/圆角）。合在一个文件里会顶到 400 行红线（AGENTS.md §3-1）。 + +use unlucky_design::component_map::Component; +use unlucky_design::spacing::Space; + +use crate::theme::Ui; + +/// Snackbar 的几何（G17-c/d + A1 高/内距/上限）。 +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct SnackbarGeometry { + /// 最小宽度（344，`[估]`；iced 无 min-width，见组件文档）。 + pub min_width: f32, + /// 最大宽度（600，`[源]` `SnackbarKt.ContainerMaxWidth`）。 + pub max_width: f32, + /// 单行高（48）。 + pub single_height: f32, + /// 双行高（68）。 + pub two_height: f32, + /// 距宿主边距（12，`[规格]`）。 + pub margin: f32, + /// 文本水平内距（16）。 + pub pad_h: f32, + /// 文本垂直内距（6）。 + pub pad_v: f32, + /// 文本 ↔ 动作间距（8）。 + pub gap: f32, + /// 圆角（4）。 + pub radius: f32, +} + +impl SnackbarGeometry { + /// 从令牌求值。 + pub fn of(ui: &Ui) -> Self { + let single_height = 48.0; + Self { + min_width: 344.0, + max_width: 600.0, + single_height, + two_height: 68.0, + margin: ui.space(Space::X3), + pad_h: ui.space(Space::X4), + pad_v: 6.0, + gap: ui.space(Space::X2), + radius: Component::Snackbar.spec().shape.radius_px(single_height), + } + } + + /// 按行数取高：`lines >= 2` → 68，否则 48（官方 `heightIn(min=...)` 的等价口径）。 + pub fn height_for(&self, lines: u8) -> f32 { + if lines >= 2 { + self.two_height + } else { + self.single_height + } + } +} + +/// Dialog 的几何。 +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct DialogGeometry { + /// 本项目宽度（480，落在官方 280..560 内）。 + pub width: f32, + /// 官方下限（280）。 + pub min_width: f32, + /// 官方上限（560）。 + pub max_width: f32, + /// 圆角（28）。 + pub radius: f32, + /// 四边内边距（24）。 + pub padding: f32, + /// 标题下间距（16）。 + pub title_gap: f32, + /// 正文下间距（24）。 + pub body_gap: f32, + /// 动作主轴间距（8）。 + pub action_gap: f32, + /// 动作交叉间距（12）。 + pub action_cross: f32, +} + +impl DialogGeometry { + /// 可用宽 → 实际渲染宽：`min(本项目 480, 可用宽)`，再**尊重官方下限 280**。 + /// + /// 复审 E：早先 `Dialog::width(200)` 会真的画 200（官方 `DialogMinWidth = 280` 只在测试里）。 + /// 可用宽 < 280 时仍画 280（**溢出宿主**）—— iced 没有 min-width，这条是 G17-d 之二。 + pub fn effective_width(&self, available: f32) -> f32 { + available.min(self.width).max(self.min_width) + } + + /// 从令牌求值（内边距与三个间距全部落在 4px 栅格上 ⇒ 走 `Space`）。 + pub fn of(ui: &Ui) -> Self { + let width = 480.0; + Self { + width, + min_width: 280.0, + max_width: 560.0, + radius: Component::Dialog.spec().shape.radius_px(width), + padding: ui.space(Space::X6), + title_gap: ui.space(Space::X4), + body_gap: ui.space(Space::X6), + action_gap: ui.space(Space::X2), + action_cross: ui.space(Space::X3), + } + } +} + +/// 空态图标边长（`IconSize::Empty` = 32）。 +/// +/// M86 起 `icons::view_at` 会按请求尺寸**重新烘焙 stroke**，所以 32 渲染仍是视觉 1.5px 线宽 +/// （早先 `view` 把 svg 钉成 24，32 的盒子只是居中不拉伸，实渲 24 —— 那个欠账已随 M86 消解）。 +pub const EMPTY_ICON: f32 = 32.0; + +/// 空态的几何（**项目自定**：官方没有这个组件；`[估]` 几何 + `[规格]` 排版 + `[源]` CTA）。 +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct EmptyStateGeometry { + /// 图标块边长（96）。 + pub block: f32, + /// 图标块圆角（16，`ShapeScale::Large`）。 + pub block_radius: f32, + /// 块内图标（**32**，`IconSize::Empty`；由 `icons::view_at` 按 32 烘焙，stroke 同步重算）。 + pub icon: f32, + /// 块 ↔ 标题（16）。 + pub gap_title: f32, + /// 标题 ↔ 副文案（8）。 + pub gap_body: f32, + /// 副文案 ↔ 动作（24）。 + pub gap_action: f32, +} + +impl EmptyStateGeometry { + /// 从令牌求值（圆角档位与图标档位是真令牌，96 / 三个间距是项目自定）。 + pub fn of(ui: &Ui) -> Self { + let block = 96.0; + Self { + block, + block_radius: Component::EmptyState.spec().shape.radius_px(block), + icon: EMPTY_ICON, + gap_title: ui.space(Space::X4), + gap_body: ui.space(Space::X2), + gap_action: ui.space(Space::X6), + } + } +} diff --git a/crates/app-iced/src/components/feedback/pixel.rs b/crates/app-iced/src/components/feedback/pixel.rs new file mode 100644 index 0000000..704de58 --- /dev/null +++ b/crates/app-iced/src/components/feedback/pixel.rs @@ -0,0 +1,280 @@ +//! 像素取证的小工具（**仅测试**）：读 PNG、按「底色 → 墨色」的覆盖率找连通块与长条。 +//! +//! 为什么不复用 `gallery/scan.rs`：那个模块的可见性是 +//! `pub(in crate::app::components::gallery)`，从家族目录拿不到（`selection/pixel.rs` 也是 +//! 同样的理由自己写了一份）。这里只重写本家族真正用到的几个纯函数。 +//! +//! **判据口径 1：覆盖率而不是精确色。** 4px 厚的进度条、28 圆角的卡片，边缘全是抗锯齿； +//! 按「精确色」连通会把它们切碎（实测进度条只剩中间 1~2 行）。 +//! **判据口径 2：覆盖率 ≥50%。** 50% 是几何边界（30% 会把半格抗锯齿也算进去，4px 量成 6）。 + +use std::path::PathBuf; + +use iced::Color; + +/// 8bit RGB。 +pub(super) fn rgb(color: Color) -> [u8; 3] { + [ + (color.r * 255.0).round() as u8, + (color.g * 255.0).round() as u8, + (color.b * 255.0).round() as u8, + ] +} + +/// 容差比较（抗锯齿/取整）。 +pub(super) fn matches(pixel: [u8; 3], expected: [u8; 3]) -> bool { + pixel.iter().zip(expected).all(|(a, b)| a.abs_diff(b) <= 10) +} + +/// `ULL_GALLERY_SHOT` → 截图路径（相对路径按**工作区根**解释：`cargo test` 的 cwd 是 crate 目录）。 +pub(super) fn shot_path() -> Option { + 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 + } +} + +/// 尺寸容差 ±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) +} + +/// 某种颜色的**精确色**连通块（只用于「找着一大块实心」这种粗定位）。 +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..bd88fe2 --- /dev/null +++ b/crates/app-iced/src/components/feedback/probe.rs @@ -0,0 +1,342 @@ +//! 反馈家族的**渲染层**几何断言：对着真截图量像素（M68 的教训：纯函数对、图可能是错的）。 +//! +//! 为什么住在 `feedback/` 而不是 `gallery/`：`gallery/feedback.rs` 只负责把矩阵摆进 harness， +//! 断言加上去会把它顶到 400 行红线。像素工具在 [`super::pixel`]，环形与两个「面」的判据 +//! 拆在同级子模块 [`circular`] / [`panels`]（`inputs/probe/` 的同一先例）。 +//! +//! ## 量什么（每条对一个具体错误，打红它的是「变异」那一列） +//! +//! | 类 | 判据 | 打红它的变异 | +//! |---|---|---| +//! | 线性厚度 / 圆角 | 轨道带**恰好 4 行**；条的四角**透出底色** | 厚度 4→6 / `Full`→`None` | +//! | 线性不定态 | phase 0.55 列必须**数出两段**（P1-A 回归） | 段不排序（旧实现：两段压成一段） | +//! | 环形 | 环 40 且四角无墨（真圆） | 直径 40→48 | +//! | Snackbar 宽上下限 | 宿主 800→**600**、368→**344**、324→**300**（无下限 G17-d） | 上限 600→560 | +//! | Snackbar 高 | 单行带 **48** / 双行带 **68** | 48→40 | +//! | Dialog 宽 / 内距 | 最宽行 **480**（在 280..560 内）· 标题墨迹左缩 **≈24**、顶缩 **≈26** | 480→488 / pad 24→16 | +//! | 空态块 / 间距 / CTA | 块 **96×96** · 块↔标题 **≈16**+bearing · 条目总高 **≈232** · CTA **40** | 96→88 / spacing 双算回来 | +//! | scrim | 一块 ≥700 宽的遮罩带，颜色 = 预合成实色 | 遮罩改成 surface | +//! +//! ## 复现（worktree 根目录；四个部分各一张图，浅/深各一轮） +//! +//! ```text +//! for part in progress snackbar dialog empty; do +//! ULL_GALLERY_SECTION=feedback ULL_FEEDBACK_PART=$part \ +//! ./target/debug/unlucky-launcher-iced --software-renderer --screen=gallery \ +//! --screenshot target/m78/$part-light.png --screenshot-theme=light +//! ULL_FEEDBACK_PART=$part ULL_GALLERY_SHOT=target/m78/$part-light.png \ +//! cargo test -p unlucky-app-iced feedback::probe +//! done +//! ``` + +mod circular; +mod panels; + +use unlucky_design::color::{Role, SchemeFlavor}; +use unlucky_design::typography::Platform; + +use super::geometry::PHASE_055; +use super::pixel::{band_width, bands, matches, near, rgb, runs, shot_path, Shot}; +use crate::theme::{Families, Ui}; + +const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", +}; + +fn ui(flavor: SchemeFlavor) -> Ui { + Ui::with_platform(flavor, Platform::Windows, FAMILIES) +} + +/// 第三条（phase 0.55）线性轨道的左缘与宽度（gallery 的宿主尺寸：页内边距 24 + 2×332）。 +const TRACK3_X0: usize = 688; +/// 单条轨道宽（gallery 的 `TRACK_HOST`）。 +const TRACK3_W: usize = 320; + +/// 一条测试覆盖当前截图对应的那一段（段由 `ULL_FEEDBACK_PART` 指定，默认 `all`）。 +#[test] +fn feedback_geometry_matches_the_reference() { + let Some(path) = shot_path() else { + eprintln!( + "[feedback-probe] SKIPPED：未设置 ULL_GALLERY_SHOT。这是**渲染层**几何断言，\ + 需要先出图（命令见本文件模块文档，注意 ULL_GALLERY_SECTION=feedback + ULL_FEEDBACK_PART）。" + ); + return; + }; + let shot = Shot::load(&path).expect("读 feedback 截图"); + assert_eq!( + (shot.width, shot.height), + (1180, 760), + "验收图必须 1180×760 @100% DPI" + ); + + let flavor = if matches( + shot.at(2, 2), + rgb(ui(SchemeFlavor::Light).color(Role::Surface)), + ) { + SchemeFlavor::Light + } else { + SchemeFlavor::Dark + }; + let ui = ui(flavor); + let part = std::env::var("ULL_FEEDBACK_PART").unwrap_or_else(|_| "all".to_owned()); + let part = part.trim().to_ascii_lowercase(); + + match part.as_str() { + "progress" => { + check_linear(&shot, &ui); + circular::check(&shot, &ui); + } + "snackbar" => check_snackbar(&shot, &ui), + "dialog" => panels::check_dialog(&shot, &ui), + "empty" => panels::check_empty(&shot, &ui), + other => { + // 整屏时只查最不容易被折叠线切掉的那一类；分图才是逐项判据的场合。 + check_linear(&shot, &ui); + eprintln!("[feedback-probe] part={other:?} 只查了 progress 那一类；其余请在分图里查"); + } + } + + eprintln!("[feedback-probe] OK flavor={flavor:?} part={part}"); +} + +/// §12.1 + §12.4：线性厚度 / 圆角 / **不定态两段**。 +fn check_linear(shot: &Shot, ui: &Ui) { + // 参考值写字面量（A1）：**不能**从 `LinearGeometry` 读回期望值——那样把 4 改成 6 之后 + // 「实测 6 == 期望 6」会照样绿，等于没有断言。 + let surface = ui.color(Role::Surface); + let track = ui.color(Role::SecondaryContainer); + let active = ui.color(Role::Primary); + + // ---- 12.1 厚度：轨道带恰好 4 行（宿主 320 宽 ⇒ 每行 ~320 个轨道墨点）-------- + let bar_bands = bands(shot, track, surface, 300); + assert!( + !bar_bands.is_empty(), + "没找到线性进度轨道（宿主宽 320，应有 ≥300 个墨点的行）" + ); + for (top, bottom) in &bar_bands { + let height = bottom - top + 1; + assert!( + near(height, 4), + "12.1：线性进度厚必须 4（A1 Height；实测 {height} @ 行 {top}）" + ); + } + + // ---- 12.1 圆角 full：条的四角必须透出底色（直角会把角填满）------------------ + let (top, _) = bar_bands[0]; + let (left, len) = runs(shot, top + 1, track, surface) + .into_iter() + .find(|(_, len)| *len >= 300) + .expect("轨道那一行必须有 ≥300 的长段"); + assert!( + !matches(shot.at(left, top), rgb(track)), + "12.1：圆角 full(2) 的左上角必须透出底色（直角会填满）" + ); + assert!( + matches(shot.at(left + len / 2, top + 1), rgb(track)), + "条的中间必须有墨（否则是没画出来，不是圆角）" + ); + + // ---- 12.4 不定态：phase 0.55 那一列必须**数出两段**（复审 P1-A 的回归断言）---- + // + // 旧实现把两段按返回顺序铺 `FillPortion`（第一线在右、第二线在左），并且份额之和 + // 在某 34/100 相位上 >1，被 iced 归一 ⇒ 图上只剩一段 100px 的台阶（x 749..848）。 + let row = indeterminate_row(shot, active, surface); + let found: Vec<(usize, usize)> = runs(shot, row, active, surface) + .into_iter() + .filter(|(start, len)| { + *start >= TRACK3_X0 && start + len <= TRACK3_X0 + TRACK3_W + 2 && *len >= 8 + }) + .collect(); + assert_eq!( + found.len(), + 2, + "12.4：phase 0.55 必须是**两段**（P1-A 修完才成立），实测 {found:?} @ 行 {row}" + ); + + // 期望位置与单测**共用同一个常量**（`geometry::PHASE_055`）：早先这里写 0.871、单测写 + // 0.860，实测 963 距 want_end 966.7 只剩 0.28px，靠容差活着（复审 B）。 + let expected = PHASE_055; + for (index, (start, len)) in found.iter().enumerate() { + let want_start = TRACK3_X0 as f32 + expected[index].0 * TRACK3_W as f32; + let want_end = TRACK3_X0 as f32 + expected[index].1 * TRACK3_W as f32; + assert!( + (*start as f32 - want_start).abs() <= 4.0, + "12.4 第 {} 段左端应在 {want_start:.1}（实测 {start}）", + index + 1 + ); + assert!( + ((start + len) as f32 - want_end).abs() <= 4.0, + "12.4 第 {} 段右端应在 {want_end:.1}（实测 {}）", + index + 1, + start + len + ); + } + + eprintln!( + "[feedback-probe] progress：轨道带 {} 条（高 {:?}）· phase 0.55 两段 {found:?}", + bar_bands.len(), + bar_bands + .iter() + .map(|(top, bottom)| bottom - top + 1) + .collect::>(), + ); +} + +/// 线性不定态那一行的 y：主色墨迹在**第一条轨道**里出现、且不在确定态行的最上一组。 +/// +/// 不想硬编码坐标（gallery 一改间距就失准），所以按「主色横带 + 排除最高那条带」找。 +fn indeterminate_row(shot: &Shot, active: iced::Color, surface: iced::Color) -> usize { + let found = bands(shot, active, surface, 20); + assert!( + found.len() >= 2, + "至少要找到确定态行与不定态行两组主色横带，实测 {found:?}" + ); + // 第一组是确定态（0% 无墨、50%/100% 有墨），第二组是不定态 + let (top, bottom) = found[1]; + (top + bottom) / 2 +} + +/// §14：宽度上下限 + 单/双行高。 +fn check_snackbar(shot: &Shot, ui: &Ui) { + // 参考值写字面量（A1）：600 = SnackbarKt.ContainerMaxWidth，48/68 = SnackbarTokens。 + let surface = ui.color(Role::Surface); + let bar = ui.color(Role::InverseSurface); + + // 行墨量下限 200：最窄的那条只有 300 宽，里面还有 ~60px 的文字 ⇒ 每行 ~240 个实心点。 + // 高度 ≥40 才算提示条（标题行偶有一两行落在这条混色线上，那类 1 行的带要滤掉）。 + let found: Vec<(usize, usize)> = bands(shot, bar, surface, 200) + .into_iter() + .filter(|(top, bottom)| bottom - top + 1 >= 40) + .collect(); + assert!( + found.len() >= 3, + "14.x：应有 ≥3 条提示条（上限宽 / 双行 / 两条窄的），实测 {}", + found.len() + ); + + // 宽度集 = 每条带里最宽的那一行（留白行没有文字，量得到全宽）。 + let mut widths: Vec = 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, 48)), + "14.3：单行高 48，实测高度集 {heights:?}" + ); + assert!( + heights.iter().any(|h| near(*h, 68)), + "14.3：双行高 68，实测高度集 {heights:?}" + ); + + // 14.6 动作色：`InversePrimary` 必须出现在提示条内（不是按钮家族的 OnSurfaceVariant） + let action = rgb(ui.color(Role::InversePrimary)); + let action_pixels: usize = (0..shot.height) + .map(|y| { + (0..shot.width) + .filter(|x| matches(shot.at(*x, y), action)) + .count() + }) + .sum(); + assert!( + action_pixels > 40, + "14.6：动作标签应是 InversePrimary（实测该色只有 {action_pixels} px）" + ); + + // ---- 位置语义（复审 D）：两条 bottom 条的**条底距取景框底 = 12** --------------- + // + // 取景框是 gallery 给窄宿主画的 1px `OutlineVariant` 边（`framed_host`）：透明宿主没有 + // 可见底边时「贴底」在像素上不可证（旧宿主 72 = 48 + 2×12，上下留白相等）。 + let frame = rgb(ui.color(Role::OutlineVariant)); + let mut margins: Vec = Vec::new(); + for (top, bottom) in &found { + let width = band_width(shot, (*top, *bottom), bar, surface); + if !(near(width, 300) || near(width, 344)) { + continue; + } + // 1px 描边常落在半像素上（两行各 ~50% 覆盖），精确色匹配抓不住 ⇒ 用「更靠近框色 + // 而不是画布」判。但条自身（深色）比画布**更接近**框色，所以还要一条：这一行的 + // 框色连续段必须**比条本身更宽**（框横贯整个宿主），否则会认成条自己（实测过：差值 1）。 + let distance = |pixel: [u8; 3], target: [u8; 3]| -> u32 { + pixel + .iter() + .zip(target) + .map(|(a, b)| u32::from(a.abs_diff(b))) + .sum() + }; + let surface_rgb = rgb(surface); + let frame_run = |y: usize| -> usize { + let mut longest = 0; + let mut current = 0; + for x in 0..shot.width { + let pixel = shot.at(x, y); + if distance(pixel, frame) < distance(pixel, surface_rgb) { + current += 1; + longest = longest.max(current); + } else { + current = 0; + } + } + longest + }; + // 框的横贯长度 > 条宽 + 10 ⇒ 只有框那一两行满足 + let is_frame_row = |y: usize| frame_run(y) >= width + 10; + + let frame_row = ((bottom + 1)..shot.height) + .find(|y| is_frame_row(*y)) + .unwrap_or_else(|| { + panic!("D：窄条下方没找到宿主取景框（条 y {top}..{bottom}，宽 {width}）") + }); + let frame_top_row = (0..*top) + .rev() + .find(|y| is_frame_row(*y)) + .unwrap_or_else(|| panic!("D：窄条上方没找到宿主取景框（条顶 y {top}）")); + // 复审 P2-1：宿高回退到 72（上下留白相等）时这条会红。 + assert!( + (*top as i64 - frame_top_row as i64 - 36).abs() <= 1, + "D：贴底 ⇒ 框顶到条顶应为 36（96 − 48 − 12），实测 {}", + *top as i64 - frame_top_row as i64 + ); + let frame_height = frame_row - frame_top_row + 1; + assert!( + frame_height.abs_diff(96) <= 1, + "D：取景框高应 96（宿主高），实测 {frame_height}" + ); + margins.push(frame_row - bottom); + } + assert!( + !margins.is_empty(), + "D：应至少量到一条 bottom 条的宿主边距，实测 {margins:?}" + ); + for margin in &margins { + assert!( + near(*margin, 12), + "D：贴底 ⇒ 条底距宿主底 12（官方外边距），实测 {margin}：{margins:?}" + ); + } + + eprintln!( + "[feedback-probe] snackbar：宽度集 {widths:?} · 高度集 {heights:?} · InversePrimary {action_pixels}px · 底边距 {margins:?}" + ); +} diff --git a/crates/app-iced/src/components/feedback/probe/circular.rs b/crates/app-iced/src/components/feedback/probe/circular.rs new file mode 100644 index 0000000..42e7a7a --- /dev/null +++ b/crates/app-iced/src/components/feedback/probe/circular.rs @@ -0,0 +1,158 @@ +//! 环形进度的渲染层判据（`probe` 的子模块，`inputs/probe/` 的同一先例）。 +//! +//! ## 判据：六个**固定窗**逐个测存在性与尺寸 +//! +//! gallery 里这一排环在**固定 x 栅格**上：左缘 `24 + 56·i`（环宽 40、间距 16），共 6 个 +//! （0% / 25% / 50% / 75% / 100% / ind 0.30）。判据是「每个窗里都必须有一圈 +//! **40(±2)×40(±2)** 的墨迹（轨道 ∪ 激活色的并集）」： +//! +//! - 少一个环 → 该窗没有墨迹 → 红； +//! - 某个环被画小了（例如 20×20）→ 该窗墨迹的外接框变小 → 红； +//! - 0% 那格只有轨道、没有激活色 → 用「并集」判，不把「没有激活色」当失败。 +//! +//! 早先用「主色连通簇数」判（只要求非空）：把 5 个环涂掉仍然绿（复审 r3 P2-3 的反证）， +//! 所以 G18-i 的处置从「不修」改成**已用固定窗收口**。簇数仍在日志里打印供复核。 +//! +//! 不定态的**节奏**（4 圈/周期、跨周期不跳变）不在这里量：那是时间的函数，截图只有一帧， +//! 判据在 `tests/progress.rs::circular_indeterminate_rotation_is_four_turns_and_continuous`。 +//! +//! 欠账 **G18-l**（登记不修）：`snackbar` 的「取景框」判据会把条自身的抗锯齿底行算成框 +//! （覆盖率 0.5008，余量 0.0008），方向是**误报**不是假绿；本轮给 snackbar 加了「框高 = 96」 +//! 之后触发概率下降，但那 0.0008 的余量仍在。 + +use iced::Color; + +use super::super::pixel::{blobs, coverage, dims, rgb, BBox, Shot}; +use unlucky_design::color::Role; + +use crate::theme::Ui; + +/// 环直径（A1 `CircularProgressIndicatorTokens.Size = 40`）。 +const DIAMETER: usize = 40; +/// 环排栅格的左缘（页内边距 24）。 +const RING_X0: usize = 24; +/// 栅格间距（40 环 + 16 = `Space::X4`）。 +const RING_PITCH: usize = 56; +/// 窗数（0 / 25 / 50 / 75 / 100 / ind）。 +const RINGS: usize = 6; + +/// 某个像素算不算「这块墨」（覆盖率 ≥50%，与 `pixel::runs` 同一口径）。 +fn is_ink(pixel: [u8; 3], fill: Color, under: Color) -> bool { + coverage(pixel, rgb(fill), rgb(under)) >= 0.5 +} + +/// 环形那一排的判据：逐窗测「有没有一圈 40×40 的墨迹」。 +pub(super) fn check(shot: &Shot, ui: &Ui) { + let active = ui.color(Role::Primary); + let track = ui.color(Role::SecondaryContainer); + let surface = ui.color(Role::Surface); + + // 环带的 y：以第一个窗（0% 环，只有轨道色）的**圆环签名**定位 —— 中间那几十行在窗的 + // 左右两侧都有墨迹；再向上/下各扩到「窗内还有墨」为止（把圆顶/圆底那两行收回来）。 + // + // 为什么不按「每行墨点数 4..20」判：圆顶那一行笔画横跨 ~20~28 px，会落在区间外， + // 按连续段会把 40 高的带子切成 32 行；为什么不按「首行..末行」：深色档里正文的抗锯齿 + // 像素也会落在轨道色的混色线上，跨度会扩到 274 行（两种都实测过）。 + let ink_count = |y: usize, from: usize, to: usize| -> usize { + (from..to) + .filter(|x| is_ink(shot.at(*x, y), track, surface)) + .count() + }; + let left = RING_X0; + let right = RING_X0 + DIAMETER; + + // 环带 = 第一个窗里「有墨」的**连续行组**中、高度 ≈40 的那一组。 + // + // 走过的两条弯路都实测过： + // ①「每行墨点 4..20」→ 圆顶那一行笔画横跨 ~20~28 px，被排除，带子切成 32 行； + // ②「左右两侧都有墨」→ 进度条那一行也满足（通栏），会认成 4 行高的假带。 + // 连续行组 + 高度窗口同时把「进度条」（4~5 行）与「正文行」排除在外。 + let mut runs: Vec<(usize, usize)> = Vec::new(); + let mut current: Option<(usize, usize)> = None; + for y in 0..shot.height { + match (ink_count(y, left, right) > 0, current) { + (true, None) => current = Some((y, y)), + (true, Some((top, _))) => current = Some((top, y)), + (false, Some(run)) => { + runs.push(run); + current = None; + } + (false, None) => {} + } + } + if let Some(run) = current { + runs.push(run); + } + let (top, bottom) = runs + .iter() + .copied() + .find(|(top, bottom)| (DIAMETER - 6..=DIAMETER + 6).contains(&(bottom - top + 1))) + .unwrap_or_else(|| panic!("没找到高约 {DIAMETER} 的环形带；窗口 0 的连续行组：{runs:?}")); + + let mut report = Vec::new(); + for index in 0..RINGS { + let left = RING_X0 + RING_PITCH * index; + let right = left + DIAMETER - 1; + let mut ink: Option = 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/progress.rs b/crates/app-iced/src/components/feedback/progress.rs new file mode 100644 index 0000000..765dc42 --- /dev/null +++ b/crates/app-iced/src/components/feedback/progress.rs @@ -0,0 +1,308 @@ +//! 进度指示器（`research/12b` §12）：`linear` 与 `circular`，各有确定态与不定态。 +//! +//! ## 两种形态、四种态 +//! +//! | 形态 | 确定态 | 不定态 | +//! |---|---|---| +//! | [`linear`] | 轨道 `SecondaryContainer` + 指示条 `Primary`，厚 **4**、圆角 full | 官方 1750ms **双段**追逐（[`phase_segments`]） | +//! | [`circular`] | 40 环 + 4 线宽，弧长 = 数值 × 360° | 官方 6000ms（弧长 0.1↔0.87 + 旋转 **0→1440°**：全局 1080° 线性 + 关键帧 360°，[`CircularGeometry::indeterminate`]） | +//! +//! ## 为什么不定态要调用方给 `phase` +//! +//! 契约 §2：组件不持有时钟。`phase`（0..1 的一个周期）由页面按 `Subscription` 推进； +//! harness 因此能拍**确定**的中间帧（否则每张图都是抓阄）。周期时长在几何里 +//! （[`LinearGeometry::cycle_ms`] / [`CircularGeometry::cycle_ms`]），调用方按它换算。 +//! +//! ## CPU 降级路径（D27） +//! +//! 本组件**零半透明、零模糊**：轨道/指示条都是不透明实色，环形是 `stroke` 实色。 +//! 波浪形态（线性振幅 3 / 波长 40，环形振幅 1.6 / 波长 15，`[源]`）**未实现**， +//! 用直线段/等弧长替代——这是 `12b §12.4` 明确允许的登记项（见报告「偏离登记」）。 +//! +//! ## 环形为什么手搓 SVG +//! +//! iced 的 `canvas` feature 没开（`Cargo.toml` 不归本 mission），而圆弧用容器边框画不出来。 +//! 令牌图标的做法（24 网格 SVG path + `currentColor` + 内容哈希缓存）同样适用于几何图元： +//! 一份 handle 渲染两层（轨道一层、弧一层），相位不变时 iced 侧命中缓存。 + +use iced::border::Radius; +use iced::widget::{container, row, svg, Space}; +use iced::{Background, Border, Element, Length}; + +use unlucky_design::color::Role; + +use crate::theme::Ui; + +use super::super::layout; +use super::geometry::{phase_segments, CircularGeometry, LinearGeometry}; + +/// `FillPortion` 的比例分辨率：0..1 的占比 × 1000 取整（1/1000 像素级，够用且不溢出 u16）。 +const PORTIONS: f32 = 1000.0; + +/// 弧长小于这个角度就不画激活层（圆头在 0 弧长上会画出一个点，看着像「已完成」）。 +const MIN_SWEEP_DEG: f32 = 1.0; + +/// 100% 时弧首尾重合，`A` 命令画不出整圆 ⇒ 超过这个角度改画整环。 +const FULL_SWEEP_DEG: f32 = 359.9; + +/// 进度的取值：确定（0..1）或不定（相位 0..1）。 +#[derive(Debug, Clone, Copy, PartialEq)] +pub enum Amount { + /// 确定态：0..1。 + Determinate(f32), + /// 不定态：一个周期内的相位（0..1，可越界，采样时按周期取模）。 + Indeterminate(f32), +} + +/// 一个进度指示器的取值（**不持有任何状态**）。 +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct Progress { + amount: Amount, +} + +impl Progress { + /// 确定态：`value` 越界会被夹到 0..1（0% 只画轨道）。 + pub fn determinate(value: f32) -> Self { + Self { + amount: Amount::Determinate(value.clamp(0.0, 1.0)), + } + } + + /// 不定态：`phase` 是周期内的相位（调用方按 `cycle_ms` 推进）。 + pub fn indeterminate(phase: f32) -> Self { + Self { + amount: Amount::Indeterminate(phase), + } + } + + /// 取值（断言用；生产路径不读它，内部直接 match 字段）。 + #[cfg(test)] + pub fn amount(self) -> Amount { + self.amount + } + + /// 本帧要画的占轨道比例区间（0..1）。 + /// + /// 确定态 1 段、不定态 2 段（官方双线）；区间可能为空（相位在「两段都在屏幕外」的时刻）， + /// 调用方按 `end > start` 过滤。 + pub fn spans(self) -> Vec<(f32, f32)> { + match self.amount { + Amount::Determinate(value) => vec![(0.0, value.clamp(0.0, 1.0))], + Amount::Indeterminate(phase) => phase_segments(phase).to_vec(), + } + } +} + +/// 把 0..1 的区间**排序 + 合并重叠**，摊成「间隙 / 指示条」交替的列表（总长恒为 1.0）。 +/// +/// ## 为什么必须排序（复审 P1-A，视觉 r1 的 p1） +/// +/// [`phase_segments`] 返回的两段**不保证有序**：第一线的前缘抢跑 250ms，所以它的区间在右， +/// 第二线从 0 起跑的区间在左。照顺序铺 `FillPortion` 会把左段接到右段**之后**，并且 +/// `FillPortion` 之和一旦 ≠ 1000，iced 就按总和归一 —— 位置和宽度一起被压扁。 +/// 实测 phase 0.55：本应两段 `[0.003,0.079]` + `[0.355,0.860]`（x 689..713 / 802..963）， +/// 实际被画成一段 100px 的台阶（x 749..848），且 **34/100 个相位**上总和 >1（最大 1.99）。 +/// +/// 返回的每项是 `(是不是指示条, 占比)`；间隙项也显式给出来，才能断言「总和 = 1.0」。 +pub fn layout_spans(spans: &[(f32, f32)]) -> Vec<(bool, f32)> { + let mut clipped: Vec<(f32, f32)> = spans + .iter() + .map(|(start, end)| (start.clamp(0.0, 1.0), end.clamp(0.0, 1.0))) + .filter(|(start, end)| end > start) + .collect(); + clipped.sort_by(|a, b| a.0.total_cmp(&b.0)); + + let mut merged: Vec<(f32, f32)> = Vec::new(); + for (start, end) in clipped { + match merged.last_mut() { + Some(last) if start <= last.1 => last.1 = last.1.max(end), + _ => merged.push((start, end)), + } + } + + let mut items = Vec::new(); + let mut cursor = 0.0_f32; + for (start, end) in merged { + if start > cursor { + items.push((false, start - cursor)); + } + items.push((true, end - start)); + cursor = end; + } + if cursor < 1.0 { + items.push((false, 1.0 - cursor)); + } + items +} + +/// 占比 → `FillPortion` 整数份额，**总和恒为 `PORTIONS`**（累计舍入，最后一项吃掉残差）。 +/// +/// 为什么不用「每项各自 round」：各项独立取整后总和可能是 999 或 1001，iced 按总和归一， +/// 就又回到 P1-A 那个「整条被压扁」的坑。这里让每个**累计边界**取整，最后一项补足， +/// 于是任意相位下份额之和都精确等于 1000。 +pub fn portion_shares(items: &[(bool, f32)]) -> Vec<(bool, u16)> { + let mut shares = Vec::with_capacity(items.len()); + let mut accumulated = 0.0_f32; + let mut previous = 0_u16; + for (index, (is_bar, fraction)) in items.iter().enumerate() { + accumulated += fraction; + let target = if index + 1 == items.len() { + PORTIONS as u16 + } else { + (accumulated * PORTIONS).round() as u16 + }; + let share = target.saturating_sub(previous); + previous = target; + shares.push((*is_bar, share)); + } + shares +} + +/// 线性进度条（轨道 + 指示条，厚 4、圆角 full）。 +/// +/// 轨道宽 `Fill`（由宿主决定），指示条按占比分到 `FillPortion` 上——**不需要知道轨道像素宽**， +/// 所以 50% 在任何宿主宽度下都精确是半条。 +pub fn linear<'a, M: 'a>(ui: &'a Ui, progress: Progress) -> Element<'a, M> { + let geometry = LinearGeometry::of(ui); + let track_color = ui.color(Role::SecondaryContainer); + let active_color = ui.color(Role::Primary); + + let mut bar = row![] + .width(Length::Fill) + .height(Length::Fixed(geometry.thickness)); + for (is_bar, share) in portion_shares(&layout_spans(&progress.spans())) { + if share == 0 { + continue; + } + bar = bar.push(if is_bar { + container(Space::new().width(Length::Fill).height(Length::Fill)) + .width(Length::FillPortion(share)) + .height(Length::Fill) + .style(move |_theme| container::Style { + background: Some(Background::Color(active_color)), + border: Border { + radius: Radius::new(geometry.radius), + ..Border::default() + }, + ..container::Style::default() + }) + .into() + } else { + spacer(share) + }); + } + + container(bar) + .width(Length::Fill) + .height(Length::Fixed(geometry.thickness)) + .style(move |_theme| container::Style { + background: Some(Background::Color(track_color)), + border: Border { + radius: Radius::new(geometry.radius), + ..Border::default() + }, + ..container::Style::default() + }) + .into() +} + +/// 环形进度（40 直径 / 4 线宽；确定态画弧，不定态按官方节奏扫）。 +pub fn circular<'a, M: 'a>(ui: &'a Ui, progress: Progress) -> Element<'a, M> { + let geometry = CircularGeometry::of(ui); + let (sweep, rotation) = match progress.amount { + Amount::Determinate(value) => (value.clamp(0.0, 1.0) * 360.0, 0.0), + Amount::Indeterminate(phase) => { + // 圈数直接乘 360（不做 rem_euclid）：每周期 4 圈是官方口径，截断就丢转速。 + let (sweep_fraction, turns) = geometry.indeterminate(phase); + (sweep_fraction * 360.0, turns * 360.0) + } + }; + + let track = glyph( + &geometry, + ring_source(&geometry), + ui.color(Role::SecondaryContainer), + ); + + // 0% 只画轨道（不画弧，也不画圆头小点）；100% 画整环（`A` 命令的首尾重合画不出整圆） + let active = if sweep < MIN_SWEEP_DEG { + None + } else if sweep >= FULL_SWEEP_DEG { + Some(glyph( + &geometry, + ring_source(&geometry), + ui.color(Role::Primary), + )) + } else { + Some(glyph( + &geometry, + arc_source(&geometry, sweep, rotation), + ui.color(Role::Primary), + )) + }; + + let mut layers = vec![track]; + layers.extend(active); + + // Q9 的同族：几何图元也必须落在**固定尺寸**的盒子里，否则 usvg 会按 Contain 撑满父级。 + layout::fixed( + geometry.diameter, + geometry.diameter, + iced::widget::stack(layers), + ) +} + +/// 两段之间/两端的透明占位。 +fn spacer<'a, M: 'a>(share: u16) -> Element<'a, M> { + Space::new() + .width(Length::FillPortion(share)) + .height(Length::Fill) + .into() +} + +/// 一层几何图元（固定尺寸 + `currentColor` 上色）。 +fn glyph<'a, M: 'a>( + geometry: &CircularGeometry, + source: String, + color: iced::Color, +) -> Element<'a, M> { + svg(svg::Handle::from_memory(source.into_bytes())) + .width(Length::Fixed(geometry.diameter)) + .height(Length::Fixed(geometry.diameter)) + .style(move |_theme, _status| svg::Style { color: Some(color) }) + .into() +} + +/// 整环（轨道用，也用作 100% 的激活层）。 +fn ring_source(geometry: &CircularGeometry) -> String { + let (size, thickness) = (geometry.diameter, geometry.thickness); + let center = size / 2.0; + let radius = geometry.arc_radius(); + format!( + "" + ) +} + +/// 一段圆弧（`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..713dd49 --- /dev/null +++ b/crates/app-iced/src/components/feedback/snackbar.rs @@ -0,0 +1,193 @@ +//! Snackbar（`research/12b` §14）：底/顶部提示条 + 动作 + 关闭。 +//! +//! ## 官方值（`[源]` = A1，`SnackbarTokens` + `SnackbarKt`，`javap` 核对） +//! +//! | # | 项 | 值 | 落点 | +//! |---|---|---|---| +//! | 14.1 | 圆角 | **4**（`CornerExtraSmall`） | `Component::Snackbar.spec().shape` | +//! | 14.2 | 容器色 | **`InverseSurface`**（高程 L3 是设计口头径，见下「不画阴影」） | [`Role::InverseSurface`] | +//! | 14.3 | 高 | 单行 **48** / 双行 **68** | [`SnackbarGeometry::height`] | +//! | 14.4 | 内距 | 水平 **16** / 垂直 **6** / 文本↔动作 **8** | `Space::X4` / 6 / `Space::X2` | +//! | 14.6 | 颜色 | 文本 `InverseOnSurface`、动作 **`InversePrimary`**、图标 24 `InverseOnSurface` | 组件层取角色 | +//! | — | 宽度上限 | **600**（`SnackbarKt.ContainerMaxWidth`） | `max_width` | +//! +//! ## 宽度上下限（一条**真实**限制，登记 G17-d） +//! +//! 官方只有上限 600，没有下限常数；本项目取 **344 `[估]`**（M2 时代口径，观感连续）。 +//! iced 的 `Length` **没有 min-width**（与按钮家族 G15「最小宽 58 不施加」同一堵墙）， +//! 所以：**上限在组件里强制**（`container::max_width`），**下限由宿主保证**——页面给提示条 +//! 的区域至少 344 宽。gallery 用三个宿主宽度把这条限制摊开（300 → 300、344 → 344、800 → 600）， +//! 渲染层断言量的是这三种实测值，不假装下限被组件强制住了。 +//! +//! ## 超时与 dismiss：状态归调用方 +//! +//! 组件**不计时**：显示时长、自动消失、`on_timeout` 全在调用方（页面）手里。 +//! 组件的语义只有三条：`placement` 决定贴顶还是贴底（并给出 12 的外边距）、 +//! `action` 给一个文字动作、`dismiss` 给关闭键。消息要不要触发「撤销」由调用方决定。 +//! +//! ## 不画阴影 +//! +//! 官方是 L3，但 D27（CPU 档禁模糊）与令牌层 `ShadowSpec` 仍是 M63 占位值这两条都指向 +//! 「先不画」——层级靠 `InverseSurface` 与页面的 scrim/留白表达。登记为偏离 **D-4** +//! （D-3 是进度条的波浪降级，别混号）。 + +use iced::widget::{container, row, text}; +use iced::{Alignment, Background, Border, Element, Length, Padding}; + +use unlucky_design::color::Role; +use unlucky_design::icons::IconKind; +use unlucky_design::typography::TypeRole; + +use crate::theme::Ui; + +use super::super::interaction::Interaction; +use super::action; +use super::panel::SnackbarGeometry; + +/// 贴底还是贴顶（官方两种都有；本项目默认贴底）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Placement { + /// 贴底（桌面默认：不挡页头，也不挡主操作）。 + Bottom, + /// 贴顶（页头有刷新按钮时用于「结果在页头附近」的场景）。 + Top, +} + +impl Placement { + /// 垂直对齐：贴底 = `End`，贴顶 = `Start`。 + fn vertical(self) -> Alignment { + match self { + Placement::Bottom => Alignment::End, + Placement::Top => Alignment::Start, + } + } +} + +/// 一条提示条的装配描述（**不持有任何状态所有权**）。 +#[derive(Debug, Clone)] +pub struct Snackbar<'a, M> { + text: &'a str, + lines: u8, + placement: Placement, + action: Option<(&'a str, M)>, + dismiss: Option, + state: Option, +} + +impl<'a, M> Snackbar<'a, M> { + /// 单行提示条（高 48）。 + pub fn new(text: &'a str) -> Self { + Self { + text, + lines: 1, + placement: Placement::Bottom, + action: None, + dismiss: None, + state: None, + } + } + + /// 双行（高 68）。**行数由调用方声明**：iced 没有 `heightIn(min=…)`，官方那两条高度值 + /// 只能显式给（文本自己换行与否不改变容器高，这是 M3 的口径）。 + pub fn two_lines(mut self) -> Self { + self.lines = 2; + self + } + + /// 贴底 / 贴顶。 + pub fn placement(mut self, placement: Placement) -> Self { + self.placement = placement; + self + } + + /// 右侧文字动作（`InversePrimary`）。 + pub fn action(mut self, label: &'a str, on_press: M) -> Self { + self.action = Some((label, on_press)); + self + } + + /// 关闭键（`InverseOnSurface`）。 + pub fn dismiss(mut self, on_press: M) -> Self { + self.dismiss = Some(on_press); + self + } + + /// 强制动作件的视觉态（gallery 取证用；运行期不要调）。 + pub fn state(mut self, state: Interaction) -> Self { + self.state = Some(state); + self + } +} + +/// 画一条提示条。 +/// +/// 返回的元素是 **`Fill` 高度的容器**：贴底/贴顶由它内部的对齐决定，调用方只要给它一块 +/// 可用区（`stack` 在页面上、或 gallery 的宿主盒），它就是那个位置上的居中提示条。 +pub fn snackbar<'a, M: Clone + 'a>(ui: &'a Ui, spec: Snackbar<'a, M>) -> Element<'a, M> { + let geometry = SnackbarGeometry::of(ui); + let style = ui.style(TypeRole::BodyMedium); + let height = geometry.height_for(spec.lines); + let surface = ui.color(Role::InverseSurface); + let radius = iced::border::Radius::new(geometry.radius); + + let mut content = row![] + .align_y(Alignment::Center) + .spacing(geometry.gap) + .push( + text(spec.text) + .size(style.size_px) + .font(ui.font_of(style)) + .color(ui.color(Role::InverseOnSurface)) + .width(Length::Fill), + ); + + if let Some((label, message)) = spec.action { + content = content.push(action::text_action( + ui, + label, + Role::InversePrimary, + Role::InverseSurface, + Some(message), + spec.state, + )); + } + + if let Some(message) = spec.dismiss { + content = content.push(action::icon_action( + ui, + IconKind::Close, + Role::InverseOnSurface, + Role::InverseSurface, + Some(message), + spec.state, + )); + } + + let bar = container(content) + .width(Length::Fill) + .max_width(geometry.max_width) + .height(Length::Fixed(height)) + .padding(Padding { + top: geometry.pad_v, + right: geometry.pad_h, + bottom: geometry.pad_v, + left: geometry.pad_h, + }) + .style(move |_theme| container::Style { + background: Some(Background::Color(surface)), + border: Border { + radius, + ..Border::default() + }, + ..container::Style::default() + }); + + // 位置层：`Fill` 高度 + 外边距 12 + 水平居中；贴底/贴顶只改 `align_y`（Q8：不用 center_*）。 + container(bar) + .width(Length::Fill) + .height(Length::Fill) + .padding(Padding::from(geometry.margin)) + .align_x(Alignment::Center) + .align_y(spec.placement.vertical()) + .into() +} diff --git a/crates/app-iced/src/components/feedback/tests.rs b/crates/app-iced/src/components/feedback/tests.rs new file mode 100644 index 0000000..7ecc203 --- /dev/null +++ b/crates/app-iced/src/components/feedback/tests.rs @@ -0,0 +1,223 @@ +//! 纯函数级断言：几何对令牌、节奏对 A1、角色对变体。 +//! +//! 这里**只测数值与结构**（M68 的教训：函数对不代表图对）。对着真截图量像素的是 +//! [`super::probe`]，两者缺一不可——本文件保证「数字对」，probe 保证「画出来是那个数字」。 + +use iced::Element; + +use unlucky_design::color::{Role, Scheme, SchemeFlavor, SCRIM_ALPHA}; +use unlucky_design::elevation::MaterialLayer; +use unlucky_design::typography::Platform; + +use crate::theme::{to_iced, Families, Ui}; + +use super::super::interaction::{self, Interaction}; +use super::dialog::scrim; +use super::panel::{DialogGeometry, EmptyStateGeometry, SnackbarGeometry}; +use super::progress::Progress; +use super::snackbar::{Placement, Snackbar}; +use super::{circular, dialog, empty_state, linear, snackbar, Dialog, EmptyState}; + +mod progress; + +const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", +}; + +pub(super) fn ui(flavor: SchemeFlavor) -> Ui { + Ui::with_platform(flavor, Platform::Windows, FAMILIES) +} + +// ---- §14 Snackbar ----------------------------------------------------------- + +/// 14.3 / 14.1 / 宽度上限：48 / 68 / 4 / 600。 +#[test] +fn snackbar_heights_widths_and_radius_are_the_tokens() { + let geometry = SnackbarGeometry::of(&ui(SchemeFlavor::Light)); + assert_eq!(geometry.height_for(1), 48.0, "14.3 单行 48"); + assert_eq!(geometry.height_for(2), 68.0, "14.3 双行 68"); + assert_eq!(geometry.radius, 4.0, "14.1 圆角 4（CornerExtraSmall）"); + assert_eq!(geometry.max_width, 600.0, "SnackbarKt.ContainerMaxWidth"); + assert_eq!(geometry.min_width, 344.0, "G17-d [估] 最小宽"); + assert!(geometry.min_width < geometry.max_width, "上下限必须有区间"); + assert_eq!(geometry.margin, 12.0, "G17-c [规格] 外边距 12"); + assert_eq!(geometry.pad_h, 16.0, "A1 HorizontalSpacing"); + assert_eq!(geometry.pad_v, 6.0, "A1 SnackbarVerticalPadding"); +} + +// ---- §7 Dialog -------------------------------------------------------------- + +/// 7.4：官方区间 **280..560**，本项目取 **480**，且 480 落在区间内。 +#[test] +fn dialog_geometry_sits_inside_the_official_bounds() { + let geometry = DialogGeometry::of(&ui(SchemeFlavor::Light)); + assert_eq!(geometry.min_width, 280.0, "A1 DialogMinWidth"); + assert_eq!(geometry.max_width, 560.0, "A1 DialogMaxWidth"); + assert_eq!(geometry.width, 480.0, "G17-e 本项目取值"); + assert!( + geometry.min_width <= geometry.width && geometry.width <= geometry.max_width, + "自选宽必须落在官方区间内" + ); +} + +/// 复审 P2-2：`max(280)` 那条支以前一次都没被执行过（只有定义 + 一个调用点）。 +/// +/// 抓得住：有人把下限去掉（200 → 200）、或把 `min/max` 顺序写反（200 → 480 之外的值）。 +/// 抓不住：渲染时是否真的画了 280（那需要真窗口；gallery 的 360 那格由 probe 的逐卡宽度兜）。 +#[test] +fn dialog_width_respects_the_official_minimum() { + let geometry = DialogGeometry::of(&ui(SchemeFlavor::Light)); + assert_eq!( + geometry.effective_width(200.0), + 280.0, + "可用宽 200 → 仍画官方下限 280" + ); + assert_eq!(geometry.effective_width(360.0), 360.0, "窄宿主取可用宽"); + assert_eq!( + geometry.effective_width(800.0), + 480.0, + "宽宿主夹到项目值 480" + ); +} + +/// 7.1 / 7.3 / 7.6：圆角 28、内距 24 / 16 / 24、动作 8 / 12。 +#[test] +fn dialog_padding_and_action_gaps_are_the_tokens() { + let geometry = DialogGeometry::of(&ui(SchemeFlavor::Light)); + assert_eq!(geometry.radius, 28.0, "7.1 CornerExtraLarge"); + assert_eq!(geometry.padding, 24.0, "7.3 DialogPadding"); + assert_eq!(geometry.title_gap, 16.0, "7.3 TitlePadding bottom"); + assert_eq!(geometry.body_gap, 24.0, "7.3 TextPadding bottom"); + assert_eq!(geometry.action_gap, 8.0, "7.6 ButtonsMainAxisSpacing"); + assert_eq!(geometry.action_cross, 12.0, "7.6 ButtonsCrossAxisSpacing"); +} + +/// 7.7 + D27：scrim = 黑@0.32 叠在 canvas 上之后的**不透明**实色。 +#[test] +fn scrim_is_scrimalpha_precomposited_onto_the_canvas() { + for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] { + let ui = ui(flavor); + let scheme = Scheme::baseline(flavor); + let canvas = scheme.get(MaterialLayer::Canvas.surface_role()); + let expected = to_iced(scheme.scrim().over(canvas)); + assert_eq!( + scrim(&ui), + expected, + "{flavor:?}：scrim 必须逐位等于「黑@0.32 叠 canvas」" + ); + assert_eq!( + scrim(&ui).a, + 1.0, + "D27：CPU 档不出现半透明（预合成后必须不透明）" + ); + assert_ne!( + scrim(&ui), + ui.layer(MaterialLayer::Canvas), + "遮罩必须与画布有可见差异" + ); + assert!((SCRIM_ALPHA - 0.32).abs() < f32::EPSILON, "令牌口径 α=0.32"); + } +} + +// ---- §15 空态（项目自定） ---------------------------------------------------- + +/// 15.1：图标块 96 / 圆角 16 / 图标 32（**全部 `[估]`**，官方没有这个组件）。 +#[test] +fn empty_state_geometry_is_the_project_defined_set() { + let geometry = EmptyStateGeometry::of(&ui(SchemeFlavor::Light)); + assert_eq!(geometry.block, 96.0); + assert_eq!(geometry.block_radius, 16.0, "ShapeScale::Large"); + // 复审 C：登记值 32（`IconSize::Empty`）。这条守「登记值 = 交给 `view_at` 的 px」—— + // 它抓不住「盒子 32 而 svg 仍钉 24」那种情况（那是渲染层的事，probe 量墨迹 22..34 兜）。 + assert_eq!( + geometry.icon, 32.0, + "盒内图标 32（`view_at` 按 32 烘焙 stroke）" + ); + // **复审 P2-1 的回归断言**：三个间距必须精确等于令牌档位。 + // 早先这里只写 `> 0.0`，所以「Column::spacing(8) 与显式 gap(16/24) 双算成 32/40」 + // 完全藏得住（渲染实测 264 vs 登记 232）。 + assert_eq!(geometry.gap_title, 16.0, "块↔标题 = Space::X4"); + assert_eq!(geometry.gap_body, 8.0, "标题↔副文案 = Space::X2"); + assert_eq!(geometry.gap_action, 24.0, "副文案↔CTA = Space::X6"); + assert_eq!(geometry.block, 96.0); + assert_eq!( + super::empty_state::BLOCK_LAYER, + MaterialLayer::Overlay, + "块底色是 SurfaceContainerHigh（材质层 Overlay）" + ); +} + +// ---- 结构 / 角色 ------------------------------------------------------------ + +/// 五个入口都能在**任意**消息类型下构建（契约 §2：不 import `app::Message`）。 +#[test] +fn every_component_builds_for_a_foreign_message_type() { + #[derive(Clone, Debug, PartialEq)] + enum Other { + Yes, + No, + } + + let ui = ui(SchemeFlavor::Light); + let _: Element<'_, Other> = linear(&ui, Progress::determinate(0.5)); + let _: Element<'_, Other> = circular(&ui, Progress::indeterminate(0.3)); + let _: Element<'_, Other> = snackbar( + &ui, + Snackbar::new("已保存") + .placement(Placement::Top) + .two_lines() + .action("撤销", Other::No) + .dismiss(Other::No), + ); + let _: Element<'_, Other> = dialog( + &ui, + Dialog::new("确认删除？", "此操作不可撤销。") + .double(("取消", Other::No), ("删除", Other::Yes)), + ); + let _: Element<'_, Other> = empty_state( + &ui, + EmptyState::new( + unlucky_design::icons::IconKind::Instances, + "还没有实例", + "建一个开始游戏", + ) + .action("新建", Other::Yes), + ); + // 无动作的三种形态也要能构建（DialogActions::None / 无 action 的 Snackbar） + let _: Element<'_, Other> = dialog(&ui, Dialog::new("已是最新版本", "没有可用更新。")); + let _: Element<'_, Other> = snackbar(&ui, Snackbar::new("已复制")); + let _: Element<'_, Other> = empty_state( + &ui, + EmptyState::new( + unlucky_design::icons::IconKind::Logs, + "没有日志", + "启动一次游戏后这里会有内容", + ), + ); +} + +/// 状态层必须来自 `interaction`（不是组件里自己乘 α）：hover 层不透明且与容器色不同。 +#[test] +fn snackbar_state_layers_come_from_the_interaction_module() { + let ui = ui(SchemeFlavor::Light); + let hover = interaction::overlay_color( + &ui, + Interaction::Hovered, + Role::InversePrimary, + Role::InverseSurface, + ) + .expect("hover 有状态层"); + assert_eq!(hover.a, 1.0, "状态层必须是实色（CPU/GPU 一致）"); + assert_ne!( + hover, + ui.color(Role::InverseSurface), + "叠了 8% 必须看得出来" + ); + + // 禁用内容走 token 口径（38%），不是「变灰一点」 + let disabled = interaction::disabled_content_over_role(&ui, Role::OnSurface, false); + assert_ne!(disabled, ui.color(Role::OnSurface)); + assert_eq!(disabled.a, 1.0); +} diff --git a/crates/app-iced/src/components/feedback/tests/progress.rs b/crates/app-iced/src/components/feedback/tests/progress.rs new file mode 100644 index 0000000..60f0f53 --- /dev/null +++ b/crates/app-iced/src/components/feedback/tests/progress.rs @@ -0,0 +1,281 @@ +//! 进度两式的纯函数断言（`tests` 的子模块，从 `tests.rs` 拆出来控行数）。 +//! +//! 三条回归都住在这里： +//! - [`raw_segments_are_unordered_and_layout_sorts_them`]：`phase_segments` 的原始输出**不有序** +//! （视觉 r1 P1-A 就是把两段按顺序铺 `FillPortion`，图上被压成一段）； +//! - [`portion_shares_always_sum_to_the_full_track`]：份额之和恒为 1000（旧实现 34/100 相位 >1）； +//! - [`circular_indeterminate_rotation_is_four_turns_and_continuous`]：每周期 4 圈、跨周期不跳变 +//! （代码 r1 P1-B：旧实现只有 1 圈，且末尾倒跳 270°）。 + +use unlucky_design::color::SchemeFlavor; +use unlucky_design::shape::ShapeScale; + +use super::super::geometry::{phase_segments, CircularGeometry, LinearGeometry, PHASE_055}; +use super::super::keyframes::{KeyPoint, Keyframes}; +use super::super::progress::{layout_spans, portion_shares, Amount, Progress}; +use super::ui; + +// ---- §12 进度 --------------------------------------------------------------- + +/// 12.1：线性厚度 **4**、圆角 full ⇒ 2（`ShapeScale::Full.radius_px(4)`）。 +#[test] +fn linear_thickness_and_radius_come_from_the_tokens() { + let geometry = LinearGeometry::of(&ui(SchemeFlavor::Light)); + assert_eq!(geometry.thickness, 4.0, "12.1 线性厚度 = 4（A1 Height）"); + assert_eq!( + geometry.radius, + ShapeScale::Full.radius_px(4.0), + "12.1 圆角 full = 厚的一半" + ); + assert_eq!(geometry.radius, 2.0); + assert_eq!( + geometry.cycle_ms, 1750, + "不定态周期 = LinearAnimationDuration" + ); +} + +/// 12.3：环形 **40 / 4**，环中线半径 (40 − 4) / 2 = **18**。 +#[test] +fn circular_geometry_matches_the_tokens() { + let geometry = CircularGeometry::of(&ui(SchemeFlavor::Dark)); + assert_eq!( + geometry.diameter, 40.0, + "A1 CircularProgressIndicatorTokens.Size" + ); + assert_eq!(geometry.thickness, 4.0, "A1 ActiveThickness"); + assert_eq!(geometry.radius, 20.0, "圆角 full = 直径的一半"); + assert_eq!(geometry.arc_radius(), 18.0); + assert_eq!( + geometry.cycle_ms, 6000, + "A1 CircularAnimationProgressDuration" + ); +} + +/// 12.4：不定态两段**逐段非负**——这条只证「单段自身合法」，**不证两段的先后** +/// （视觉 r1 P1-A 就是从这里漏过去的：函数名曾经叫 `..._stay_ordered`，其实没验排序）。 +#[test] +fn indeterminate_segments_are_each_well_formed() { + let mut travelled = false; + let mut previous_end = 0.0; + for step in 0..=200 { + let phase = step as f32 / 200.0; + for (start, end) in phase_segments(phase) { + assert!( + start <= end + f32::EPSILON, + "相位 {phase:.3}：段起点 {start} 大于终点 {end}（前缘/后缘写反就会这样）" + ); + assert!( + (0.0..=1.0).contains(&start) && (0.0..=1.0).contains(&end), + "相位 {phase:.3}：段越出轨道 {start}..{end}" + ); + } + let first = phase_segments(phase)[0].1; + if phase > 0.0 && phase < 0.5 && first > previous_end { + travelled = true; + } + previous_end = first; + } + assert!(travelled, "段前沿必须随相位右移（否则就是一根不动的条）"); + assert_eq!(phase_segments(0.0), [(0.0, 0.0), (0.0, 0.0)]); + let (_, head) = phase_segments(1000.0 / 1750.0)[0]; + assert!((head - 1.0).abs() < 1.0e-5, "第一线前沿应在 1000ms 到 1.0"); +} + +/// **复审 P1-A 的回归测试**：`phase_segments` 的原始输出**不有序**（第一线的前缘在右、第二线在左）， +/// 所以铺布局前必须排序 + 合并；排序后的两段位置要与 A1 keyframes 对得上。 +#[test] +fn raw_segments_are_unordered_and_layout_sorts_them() { + // 原始顺序：第一线（右，0.355..0.87）在前，第二线（左，0.003..0.079）在后 + let raw = phase_segments(0.55); + assert!( + raw[0].0 > raw[1].0, + "phase 0.55 的原始两段应当是「右段在前、左段在后」，实际 {raw:?}" + ); + + let laid = layout_spans(&raw); + // 期望：间隙 / 左段 / 间隙 / 右段 / 间隙（5 项，总长 1.0） + assert_eq!(laid.len(), 5, "两段应摊成 5 项：{laid:?}"); + assert!(!laid[0].0 && laid[1].0 && !laid[2].0 && laid[3].0 && !laid[4].0); + let left = laid[1].1; + let right = laid[3].1; + let left_start: f32 = laid[0].1; + let right_start: f32 = laid[0].1 + left + laid[2].1; + // 期望值来自 `geometry::PHASE_055`——与渲染层探针**共用**（复审 B：早先两边差 0.011） + let [(a0, a1), (b0, b1)] = PHASE_055; + assert!( + (left_start - a0).abs() < 0.01, + "左段起点 {left_start} vs {a0}" + ); + assert!( + (left - (a1 - a0)).abs() < 0.01, + "左段宽 {left} vs {}", + a1 - a0 + ); + assert!( + (right_start - b0).abs() < 0.01, + "右段起点 {right_start} vs {b0}" + ); + assert!( + (right - (b1 - b0)).abs() < 0.01, + "右段宽 {right} vs {}", + b1 - b0 + ); + + let total: f32 = laid.iter().map(|(_, fraction)| fraction).sum(); + assert!( + (total - 1.0).abs() < 1.0e-5, + "铺开的占比之和必须 = 1.0，实测 {total}" + ); +} + +/// 任意相位下 `FillPortion` 份额之和**恒为 1000**（iced 按总和归一 ⇒ 不等于 1000 就会压扁）。 +/// +/// 复审 P1-A 的实测反例：旧实现 **34/100 个相位**总和 >1（最大 1.99）。 +#[test] +fn portion_shares_always_sum_to_the_full_track() { + for step in 0..=200 { + let phase = step as f32 / 200.0; + let items = layout_spans(&phase_segments(phase)); + let shares = portion_shares(&items); + let total: u32 = shares.iter().map(|(_, share)| u32::from(*share)).sum(); + assert_eq!(total, 1000, "相位 {phase:.3} 的份额之和是 {total}"); + assert!( + shares.iter().filter(|(is_bar, _)| *is_bar).count() <= 2, + "最多两段指示条，相位 {phase:.3}" + ); + // 指示条之间必须留间隙（除非两段相接，那时会被合并成一段） + let mut previous_bar = false; + for (is_bar, share) in &shares { + if *is_bar && previous_bar && *share > 0 { + panic!("相位 {phase:.3}：两段指示条相邻但没合并"); + } + previous_bar = *is_bar; + } + } +} + +/// 环形不定态：弧长在 0.1..0.87 之间（A1 min/max），旋转走满一圈。 +#[test] +fn circular_indeterminate_sweeps_the_official_range() { + let geometry = CircularGeometry::of(&ui(SchemeFlavor::Light)); + let mut min = f32::MAX; + let mut max = f32::MIN; + let mut rotation = f32::MIN; + for step in 0..=600 { + let (sweep, spin) = geometry.indeterminate(step as f32 / 600.0); + min = min.min(sweep); + max = max.max(sweep); + rotation = rotation.max(spin); + } + assert!( + (min - 0.1).abs() < 1.0e-3, + "弧长下限 0.1（CircularIndeterminateMinProgress），实测 {min}" + ); + assert!((max - 0.87).abs() < 1.0e-3, "弧长上限 0.87，实测 {max}"); + // P1-B：每周期 4 圈（1080° 全局 + 360° 关键帧），不是 1 圈 + assert!( + (rotation - 4.0).abs() < 0.01, + "旋转应走满 4 圈，实测 {rotation}" + ); +} + +/// **复审 P1-B 的回归测试**：环形不定态每周期 4 圈（官方 1440°），且跨周期**不跳变**。 +/// +/// 修之前：`ROTATION` 首点在 300ms/90°，且没有全局旋转 ⇒ +/// `turns(0.9999) = 1.0`、`turns(0.0) = 0.25`，跨周期差 0.75 圈 = **270° 瞬时倒跳**。 +#[test] +fn circular_indeterminate_rotation_is_four_turns_and_continuous() { + let geometry = CircularGeometry::of(&ui(SchemeFlavor::Light)); + + // 每周期 4 圈 = 1440°（1080° 全局 + 360° 关键帧） + let start = geometry.indeterminate(0.0).1; + let end = geometry.indeterminate(1.0 - 1.0e-6).1; + assert!( + ((end - start) - 4.0).abs() < 1.0e-3, + "每周期应为 4 圈（1440°），实测 {} 圈", + end - start + ); + + // 跨周期连续性：按「圈」取最短距离，必须 ≤ 一帧的位移（60fps ⇒ 4/60 ≈ 0.067 圈） + let before = geometry.indeterminate(1.0 - 1.0e-4).1; + let after = geometry.indeterminate(0.0).1; + let mut jump = (before - after).rem_euclid(1.0); + if jump > 0.5 { + jump = 1.0 - jump; + } + assert!( + jump <= 4.0 / 60.0, + "跨周期旋转跳变 {jump} 圈（应 ≤ 4/60；修之前是 0.75 圈 = 270°）" + ); + // 给报告用的一行实测数值（`--nocapture` 可见）：跨周期跳变 + 每周期圈数 + eprintln!( + "[rotation] turns(0.9999)={before:.6} turns(0.0)={after:.6} 跳变={jump:.6} 圈（{:.2}°）· 每周期 {:.4} 圈 = {:.1}°", + jump * 360.0, + end - start, + (end - start) * 360.0 + ); + + // 旋转必须单调（相位 0 → 1 逐帧不回退，按圈算） + // 只扫 [0, 1) 的相位：phase == 1.0 就是下一周期的 0，回绕是**正常的**（mod 1 等价）。 + let mut previous = geometry.indeterminate(0.0).1; + for step in 1..600 { + let phase = step as f32 / 600.0; + let current = geometry.indeterminate(phase).1; + assert!( + current >= previous - 1.0e-6, + "相位 {phase:.3}：旋转从 {previous} 回退到 {current}" + ); + previous = current; + } +} + +/// 确定态：越界值夹到 0..1（0% 只画轨道，100% 画满）。 +#[test] +fn determinate_values_are_clamped() { + assert_eq!( + Progress::determinate(1.5).amount(), + Amount::Determinate(1.0) + ); + assert_eq!( + Progress::determinate(-2.0).amount(), + Amount::Determinate(0.0) + ); + assert_eq!(Progress::determinate(0.5).spans(), vec![(0.0, 0.5)]); + assert_eq!(Progress::determinate(0.0).spans(), vec![(0.0, 0.0)]); +} + +/// keyframes 求值器：端点保持、相位循环、越界相位按周期取模。 +#[test] +fn keyframes_hold_ends_and_wrap() { + const LINE: Keyframes = Keyframes { + cycle_ms: 1000, + points: &[ + KeyPoint { + ms: 250, + value: 0.0, + easing: unlucky_design::motion::Easing::Linear, + }, + KeyPoint { + ms: 750, + value: 1.0, + easing: unlucky_design::motion::Easing::Linear, + }, + ], + }; + assert_eq!(LINE.sample(0.0), 0.0, "第一点之前保持首值"); + assert_eq!(LINE.sample(0.25), 0.0, "正好在第一点"); + assert!((LINE.sample(0.5) - 0.5).abs() < 1.0e-5, "中点线性插值"); + assert_eq!(LINE.sample(0.75), 1.0); + assert_eq!(LINE.sample(0.9), 1.0, "最后一点之后保持末值"); + assert_eq!(LINE.sample(1.25), 0.0, "相位 1.25 = 0.25（循环）"); + assert_eq!( + LINE.sample(-0.75), + 0.0, + "负相位按周期折返：-0.75 → 0.25 相位 = 250ms = 首点" + ); + assert!( + (LINE.sample(-0.6) - 0.3).abs() < 1.0e-5, + "-0.6 → 0.4 相位 = 400ms = 30%" + ); + assert_eq!(LINE.sample(f32::NAN), 0.0, "NaN 不 panic，给首值"); +} diff --git a/crates/app-iced/src/components/gallery/buttons.rs b/crates/app-iced/src/components/gallery/buttons.rs new file mode 100644 index 0000000..b6b1451 --- /dev/null +++ b/crates/app-iced/src/components/gallery/buttons.rs @@ -0,0 +1,173 @@ +//! 按钮家族的状态矩阵（D30：浅/深 × 五态）。 +//! +//! ## 矩阵形状 +//! +//! ```text +//! | enabled | hovered | pressed | focused | disabled | +//! filled | [btn] | [btn] | [btn] | [btn] | [btn] | +//! tonal | ... （下同） +//! elevated | +//! outlined | +//! text | +//! icon·standard | [ico] | ... +//! icon·filled | +//! icon·tonal | +//! ``` +//! +//! 40 个单元格共 5 列 × 8 行，一屏（1180×760）装不下，靠 `gallery/mod.rs` 的 scrollable 滚动； +//! 截图取的是**整窗**，所以首屏能看到按钮家族的全部 5 行（图标行可能需要滚动，报告里会说明）。 +//! +//! ## 为什么每格都强制状态 +//! +//! iced 的 `button::Status` 只由**真实鼠标**驱动，截图时没法让 40 个按钮同时 hover。 +//! 组件层的 `Button::state(...)` 就是为这件事开的取证开关（`--force-state` 只能给整屏一种态）。 +//! 强制值**只影响画什么**，不动任何状态机——所以矩阵图里的五态与运行期五态逐像素同源。 + +use iced::widget::{column, row}; +use iced::{Element, Length}; + +use unlucky_design::color::Role; +use unlucky_design::icons::IconKind; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; + +use crate::theme::Ui; + +use super::super::buttons::{self, Button, IconVariant, Variant}; +use super::super::interaction::Interaction; +use super::{cell_width, heading, row_label, state_cells, DemoMessage}; + +/// 按钮家族整段（标题 + 列头 + 5 行文字按钮 + 3 行图标按钮 + 一条图例说明）。 +pub(super) fn section<'a>(ui: &'a Ui) -> Element<'a, DemoMessage> { + let legend = ui.style(TypeRole::BodySmall); + + let mut rows = column![header_row(ui)].spacing(ui.space(Space::X2)); + + for variant in Variant::ALL { + let cells = Interaction::ALL + .iter() + .map(|state| cell(ui, text_button(ui, variant, *state))) + .collect::>(); + + 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：高 40 · 圆角 full(20) · 内边距 24（带图标 16/24）· 图标 18 间距 8 · \ + hover 8% / focus 10% / pressed 10% / disabled 容器 10% 内容 38%" + ), + rows, + iced::widget::text( + "图例：列 = 五态（focus 与 pressed 同 α 10%，看起来一样是规范要求）；\ + 行 = 变体。虚线不表示任何东西，只是矩阵栅格。" + ) + .size(legend.size_px) + .font(ui.font_of(legend)) + .color(ui.color(Role::OnSurfaceVariant)), + ] + .spacing(ui.space(Space::X2)) + .into() +} + +/// 列头（五态名）。 +fn header_row<'a>(ui: &'a Ui) -> Element<'a, DemoMessage> { + let style = ui.style(TypeRole::LabelSmall); + let mut head = row![row_label(ui, "")].spacing(ui.space(Space::X2)); + + for (name, width) in state_cells(ui) { + head = head.push( + iced::widget::container( + iced::widget::text(name) + .size(style.size_px) + .font(ui.font_of(style)) + .color(ui.color(Role::OnSurfaceVariant)), + ) + .width(Length::Fixed(width)), + ); + } + + head.into() +} + +/// 一个矩阵单元格（固定宽，内容左对齐；高度只由按钮自己决定）。 +fn cell<'a>(ui: &'a Ui, content: Element<'a, DemoMessage>) -> Element<'a, DemoMessage> { + iced::widget::container(content) + .width(Length::Fixed(cell_width(ui))) + .into() +} + +/// 文字按钮的一格（强制成 `state`）。 +fn text_button<'a>(ui: &'a Ui, variant: Variant, state: Interaction) -> Element<'a, DemoMessage> { + // 标签用变体名 + 首字母大写：图上要能一眼对上左栏，且不引入 i18n 依赖（gallery 不是产品页） + let label = match variant { + Variant::Filled => "Filled", + Variant::Tonal => "Tonal", + Variant::Elevated => "Elevated", + Variant::Outlined => "Outlined", + Variant::Text => "Text", + }; + + // 五态共用**同一套**装配，只有「有没有消息」随禁用变： + // 早先禁用格单独走 `Button::disabled(label)`，把前后图标一起丢了，于是 disabled 列看起来 + // 像另一个组件（视觉 reviewer P2-3）。 + let mut spec = if state.is_disabled() { + Button::disabled(label) + } else { + Button::new(label, DemoMessage::Pressed(label)) + } + .state(state); + if variant != Variant::Text { + // 两个样例都必须是**描边**字形：`Play` 是填充字形，和 `ChevronRight` 混在一颗按钮里 + // 会显得线宽不一致（视觉 reviewer P2-3）。主操作允许实心，但只能单独出现。 + spec = spec + .leading(IconKind::Download) + .trailing(IconKind::ChevronRight); + } + + match variant { + Variant::Filled => buttons::filled(ui, spec), + Variant::Tonal => buttons::tonal(ui, spec), + Variant::Elevated => buttons::elevated(ui, spec), + Variant::Outlined => buttons::outlined(ui, spec), + Variant::Text => buttons::text(ui, spec), + } +} + +/// 图标按钮的一格（强制成 `state`）。 +fn icon_button<'a>( + ui: &'a Ui, + variant: IconVariant, + state: Interaction, +) -> Element<'a, DemoMessage> { + let press = if state.is_disabled() { + None + } else { + Some(DemoMessage::Pressed(variant.name())) + }; + + buttons::icon(ui, variant, IconKind::Settings, press, Some(state)) +} diff --git a/crates/app-iced/src/components/gallery/feedback.rs b/crates/app-iced/src/components/gallery/feedback.rs new file mode 100644 index 0000000..7da2d75 --- /dev/null +++ b/crates/app-iced/src/components/gallery/feedback.rs @@ -0,0 +1,365 @@ +//! gallery 里的反馈类小节：把状态矩阵摆进 harness（**断言不在这里**，在 +//! [`crate::app::components::feedback::probe`]）。 +//! +//! ## 段落切分：`ULL_FEEDBACK_PART`（本文件自己的开关） +//! +//! `ULL_GALLERY_SECTION=feedback` 只能把**整个家族**拎出来，而四件的高度超过 1180×760 首屏， +//! 所以再加一层**家族内**切分（契约 §9.2 的口径：环境变量 + 默认向后兼容 + 未识别的值回落 +//! 默认并打 stderr；区别只是它住在**本家族自己的文件**里，不动 `gallery/mod.rs`）： +//! +//! ```text +//! ULL_FEEDBACK_PART=all # 默认：四件全渲染（progress → snackbar → empty → dialog） +//! ULL_FEEDBACK_PART=progress # Linear 0/50/100 + 三相位 · Circular 0/25/50/75/100 + 不定态 +//! ULL_FEEDBACK_PART=snackbar # 四格：贴顶·上限宽 / 双行 / 宿主 300 / 宿主 344 +//! ULL_FEEDBACK_PART=dialog # 两形态并排 + 双动作 + 一屏 scrim +//! ULL_FEEDBACK_PART=empty # 空态（带 CTA） +//! ``` +//! +//! ## 宿主尺寸为什么写死 +//! +//! 量宽度必须有确定的宿主宽：`Snackbar` 的 600 是「宿主给 800 时的夹取值」、344 与 300 是 +//! 「宿主给多少就是多少」的反证（组件没有 min-width，G17-d）。`Linear` 轨道统一 320（一行 3 格 = 960 < 1128）。 +//! +//! 复现（worktree 根目录）： +//! +//! ```text +//! ULL_GALLERY_SECTION=feedback ULL_FEEDBACK_PART=progress ./target/debug/unlucky-launcher-iced \ +//! --software-renderer --screen=gallery \ +//! --screenshot target/m78/progress-light.png --screenshot-theme=light +//! ULL_GALLERY_SHOT=target/m78/progress-light.png cargo test -p app-iced feedback::probe +//! ``` + +use iced::widget::{column, container, row, text}; +use iced::{Element, Length}; + +use unlucky_design::color::Role; +use unlucky_design::icons::IconKind; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; + +use crate::theme::Ui; + +use super::super::feedback::gallery_parts::{Part, DIALOG, EMPTY, PROGRESS, SNACKBAR}; +use super::super::feedback::{self, Dialog, EmptyState, Placement, Progress, Snackbar}; +use super::super::interaction::Interaction; +use super::{heading, DemoMessage}; + +/// 线性进度的宿主宽（格宽，不是组件尺寸）。 +const TRACK_HOST: f32 = 320.0; +/// `Snackbar` 的宿主宽：**条宽 + 2×12 外边距**（12 是官方外边距，组件的定位层会扣掉）。 +/// +/// 800（条夹到上限 600）/ 368（条 344）/ 324（条 300，用来证明**没有**下限，G17-d）。 +const HOST_WIDE: f32 = 800.0; +const HOST_MIN: f32 = 368.0; +const HOST_NARROW: f32 = 324.0; +/// `Snackbar` 宿主高（比 68 + 2×12 略高，留出贴顶/贴底的判定余量）。 +const HOST_TALL: f32 = 96.0; +/// 窄宿主：给 `Dialog::width` 递 360，量「窄宿主不再被裁」的那一格（复审 E）。 +const NARROW_HOST: f32 = 360.0; + +/// 单行提示条的宿主高。 +/// +/// **96 而不是 72**（复审 D）：72 = 48 + 2×12 时上下外边距相等，像素上分不出「贴底」还是 +/// 「居中」；96 让贴底那格的上留白 = 36、下留白 = 12，探针能量到「条底距宿主底 = 12」。 +const HOST_SHORT: f32 = 96.0; +/// 空态宿主高：内容本征高 ≈96+16+32+8+16+24+40 ≈ 232，留出上下各 40 的余量。 +const HOST_EMPTY: f32 = 320.0; + +/// 反馈类家族的小节。 +pub(super) fn section<'a>(ui: &'a Ui) -> Element<'a, DemoMessage> { + let part = Part::from_env(); + part.log_once(); + + let mut body = column![heading( + ui, + "feedback · progress / snackbar / dialog / empty state", + "12b §7/§12/§14/§15：Linear 厚 4 圆角 full · Circular 40/4 · Snackbar 48/68 上限宽 600 · \ + Dialog R28 pad24 宽 480 · EmptyState 项目自定[估]（官方无此组件）" + )] + .spacing(ui.space(Space::X3)); + + if part.has(PROGRESS) { + body = body.push(progress_block(ui)); + } + if part.has(SNACKBAR) { + body = body.push(snackbar_block(ui)); + } + if part.has(EMPTY) { + body = body.push(empty_block(ui)); + } + if part.has(DIALOG) { + // 只有这一屏不画进度/提示条时，才把三形态与 scrim 都摆开（高度够）。 + let roomy = !part.has(PROGRESS) && !part.has(SNACKBAR); + body = body.push(dialog_block(ui, roomy)); + } + + body.into() +} + +/// 一行判据说明（`LabelSmall`，与矩阵的正文档分开）。 +fn caption<'a>(ui: &'a Ui, value: &'a str) -> Element<'a, DemoMessage> { + let style = ui.style(TypeRole::LabelSmall); + text(value) + .size(style.size_px) + .font(ui.font_of(style)) + .color(ui.color(Role::OnSurfaceVariant)) + .into() +} + +/// 带 1px 取景框的宿主：`Snackbar` 的贴底/贴顶需要一条**可见的宿主边界**才量得出来 +/// （描边画在盒内但**不参与布局**：内容区仍是整盒宽，实测条宽不受影响）。 +/// （透明宿主的底边在图上不存在，`Placement::Bottom` 就不可证）。 +fn framed_host<'a>( + ui: &'a Ui, + width: f32, + height: f32, + content: impl Into>, +) -> Element<'a, DemoMessage> { + 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%（轨道 SecondaryContainer · 指示条 Primary）" + ), + determinate, + caption( + ui, + "Linear · indeterminate（官方 1750ms 双段追逐；下面是同一周期的三个相位）" + ), + indeterminate, + caption( + ui, + "Circular · 直径 40 · 线宽 4 · 弧长 = 数值 × 360°（第六格 = 不定态 phase 0.30）" + ), + rings, + ] + .spacing(ui.space(Space::X2)) + .into() +} + +/// 提示条的宿主：固定宽 + 提示条宿主高（比 68 + 2×12 略高，贴顶/贴底都量得到）。 +fn bar_host<'a>( + width: f32, + content: impl Into>, +) -> Element<'a, DemoMessage> { + host(width, Some(HOST_TALL), content) +} + +/// §14：四格 —— 贴顶·上限宽 / 双行 + action + 关闭 / 宿主 300 / 宿主 344。 +fn snackbar_block<'a>(ui: &'a Ui) -> Element<'a, DemoMessage> { + let press = |id| DemoMessage::Pressed(id); + + let wide = bar_host( + HOST_WIDE, + feedback::snackbar( + ui, + Snackbar::new("版本清单已刷新") + .placement(Placement::Top) + .dismiss(press("snackbar/wide")), + ), + ); + let two_lines = host( + HOST_WIDE, + Some(HOST_TALL * 2.0), + feedback::snackbar( + ui, + Snackbar::new( + "启动失败：找不到 Java 21。请在「设置 · Java」里指定运行时路径，或让启动器自动下载一个 21 的运行时。", + ) + .two_lines() + .placement(Placement::Top) + .action("去设置", press("snackbar/settings")) + .dismiss(press("snackbar/close")) + .state(Interaction::Hovered), + ), + ); + let mid = framed_host( + ui, + HOST_MIN, + HOST_SHORT, + feedback::snackbar( + ui, + Snackbar::new("已删除实例") + .placement(Placement::Bottom) + .action("撤销", press("snackbar/undo")), + ), + ); + let narrow = framed_host( + ui, + HOST_NARROW, + HOST_SHORT, + feedback::snackbar(ui, Snackbar::new("宿主 324").placement(Placement::Bottom)), + ); + + column![ + caption( + ui, + "Snackbar · 贴顶 + 上限宽（宿主 800 → 夹到 600）· 关闭键 InverseOnSurface" + ), + wide, + caption( + ui, + "Snackbar · 双行 68 + action InversePrimary + 关闭键（动作强制 hover 态）" + ), + two_lines, + caption( + ui, + "宿主 324（取景框）⇒ 条 300：组件没有 min-width，宿主给多少就是多少（G17-d）；贴底 = 条底距框底 12" + ), + narrow, + caption(ui, "宿主 368 ⇒ 条 344：最小宽的取值口径（[估]）"), + mid, + ] + .spacing(ui.space(Space::X2)) + .into() +} + +/// §15：空态（项目自定；浅/深两种主题各出一张图，主题来自 `--screenshot-theme`）。 +fn empty_block<'a>(ui: &'a Ui) -> Element<'a, DemoMessage> { + let press = |id| DemoMessage::Pressed(id); + host( + HOST_WIDE, + Some(HOST_EMPTY), + feedback::empty_state( + ui, + EmptyState::new( + IconKind::Instances, + "还没有任何实例", + "建一个实例，或者从整合包导入。[项目自定 · 估]", + ) + .action("新建实例", press("empty/create")), + ), + ) +} + +/// §7：三形态（无动作 / 单动作 / 双动作）+ 一屏 scrim。 +/// +/// `full = true` 表示**这一屏只渲染 dialog 段**（`ULL_FEEDBACK_PART=dialog` 或 `=empty` 之类 +/// 单独出图）：此时多摆一屏 scrim，并把三形态都摆开；全家族同屏时留高度给别的段。 +fn dialog_block<'a>(ui: &'a Ui, full: bool) -> Element<'a, DemoMessage> { + let press = |id| DemoMessage::Pressed(id); + + // 页面把自己的**可用宽**递给对话框（组件取 `min(可用宽, 480)`）——窄窗口时靠这一手， + // 组件自己无法从宿主推（iced 的 Length 没有 min-width，见 `Dialog::width` 的说明）。 + let plain = feedback::dialog( + ui, + Dialog::new("已是最新版本", "当前没有可用更新。").width(HOST_WIDE), + ); + let single = feedback::dialog( + ui, + Dialog::new("已导入整合包", "共 42 个模组，缺失 0 个。") + .confirm("知道了", press("dialog/ok")), + ); + // 窄宿主那格：可用宽 360 ⇒ `min(480, 360) = 360`，且不得低于官方下限 280。 + let narrow = feedback::dialog( + ui, + Dialog::new("窄宿主 360", "可用宽 360 时取 min(480, 360)。").width(NARROW_HOST), + ); + // 强制 hover：动作件的状态层必须来自 `interaction`（不是组件里自己乘 8%）。 + let double = feedback::dialog( + ui, + Dialog::new("删除实例「1.20.1 生存」？", "存档与模组会一起删除。") + .double( + ("取消", press("dialog/cancel")), + ("删除", press("dialog/delete")), + ) + .state(Interaction::Hovered), + ); + + let mut body = column![caption( + ui, + "Dialog · R28 · SurfaceContainerHigh + L3（**本项目不画阴影，见 D-1**）· pad 24（标题下 16 / 正文下 24）· 动作 Primary 间距 8", + )] + .spacing(ui.space(Space::X2)); + + body = body.push(row![plain, single].spacing(ui.space(Space::X6))); + // 双动作 + 窄宿主并排：探针要同时量到 480 与 360 两种宽 + body = body.push(row![double, narrow].spacing(ui.space(Space::X6))); + if full { + body = body.push(caption( + ui, + "Dialog · scrim = 黑@0.32 叠 canvas 的实色（D27 预合成；详见 dialog.rs 模块文档）", + )); + body = body.push(host( + HOST_WIDE, + Some(HOST_EMPTY), + feedback::scrimmed( + ui, + feedback::dialog(ui, Dialog::new("已是最新版本", "当前没有可用更新。")), + ), + )); + } + + body.into() +} diff --git a/crates/app-iced/src/components/gallery/inputs.rs b/crates/app-iced/src/components/gallery/inputs.rs new file mode 100644 index 0000000..04f8e20 --- /dev/null +++ b/crates/app-iced/src/components/gallery/inputs.rs @@ -0,0 +1,341 @@ +//! gallery 里的输入类小节（D30 的状态矩阵登记）：TextField / Search / Slider / Menu。 +//! +//! ## 为什么分成四个 `part` +//! +//! 一整段（四组件 × 五态 × 两式）比 760 高的窗口还高，`--screen=gallery` 的截图只能看到顶部。 +//! 所以本文件把证据拆成四个自足的 `part`（[`text_field_part`] / [`search_part`] / +//! [`slider_part`] / [`menu_part`]），[`section`] 按 D30 的顺序把它们竖排—— +//! 出图时用副本工程把 `section()` 换成单个 `part`（只调段序、不改组件代码，报告里有 diff 与说明）。 +//! +//! ## 矩阵形状 +//! +//! ```text +//! TextField（两行 × 五态） 列 = enabled / hovered / pressed / focused / disabled +//! filled | [字段] | ... +//! outlined | [字段] | ... +//! 另加三格：空 / 有值 / 错误（9.7 的判据要单独一眼） +//! +//! Search （五行 + 一个展开面板） +//! Slider （五态一行 + 0% / 50% / 100% 三行 + 离散 4 段一行） +//! Menu （五态各一项的一只菜单 + 一只「展开态」菜单：选中 / 分隔线 / 禁用） +//! ``` +//! +//! ## 每个格子都强制状态 +//! +//! 与按钮家族同一个理由：截图时没法让 20 个控件同时 hover。`state(..)` 只是取证开关， +//! 不动任何状态机——图上的五态与运行期五态同源。 + +use iced::widget::{column, container, row, text}; +use iced::{Element, Length}; + +use unlucky_design::color::Role; +use unlucky_design::icons::IconKind; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; + +use crate::theme::Ui; + +use super::super::inputs::{ + self, Field, FieldVariant, Menu, MenuItem, SearchBar, SearchView, Slider, +}; +use super::super::interaction::Interaction; +use super::{cell_width, heading, row_label, state_cells, DemoMessage}; + +/// 演示消息（组件只认泛型，gallery 的映射在这里落地）。 +fn pressed(id: &'static str) -> DemoMessage { + DemoMessage::Pressed(id) +} + +/// 输入类家族整段（四个 part 竖排；见模块文档的「为什么分成四个 part」）。 +pub(super) fn section<'a>(ui: &'a Ui) -> Element<'a, DemoMessage> { + column![ + heading( + ui, + "inputs · text field / search / slider / menu", + "12b §9/§11/§8 + 15 §20：TextField 高 56（无标签 40）· Search 条 56 药丸 + 图标可视边 16 \ + （= pad 12 + offset 4）· Slider 轨 16 + 竖条 4×44 · Menu 项 48 + L2 阴影" + ), + text_field_part(ui), + search_part(ui), + slider_part(ui), + menu_part(ui), + ] + .spacing(ui.space(Space::X8)) + .into() +} + +/// 一行小字（图例/说明）。 +fn note<'a>(ui: &'a Ui, value: &'a str) -> Element<'a, DemoMessage> { + let style = ui.style(TypeRole::BodySmall); + text(value) + .size(style.size_px) + .font(ui.font_of(style)) + .color(ui.color(Role::OnSurfaceVariant)) + .into() +} + +/// 固定宽的矩阵格。 +fn cell<'a>(ui: &'a Ui, content: impl Into>) -> Element<'a, DemoMessage> { + 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) · SurfaceContainerHigh · 图标可视边 16 = pad 12 + offset 4（M69 不变量）· \ + 聚焦 1px Secondary；view：docked，头部 56 + 1px Outline 分隔 + 结果区最小高 240" + ), + row![bars, view].spacing(ui.space(Space::X6)), + ] + .spacing(ui.space(Space::X2)) + .into() +} + +/// Slider：五态一行 + 0%/50%/100% 三行 + 离散 4 段一行。 +fn slider_part<'a>(ui: &'a Ui) -> Element<'a, DemoMessage> { + let cells = Interaction::ALL + .iter() + .map(|state| { + let enabled = !state.is_disabled(); + let mut spec = Slider::new(ui, 0.5).state(*state); + if enabled { + spec = spec.on_change(|_| pressed("slider")); + } + cell(ui, inputs::slider(spec)) + }) + .collect::>(); + + let track_width = ui.space(Space::X8) * 14.0; + let mut values = column![].spacing(ui.space(Space::X2)); + for (label, fraction) in [("0%", 0.0), ("50%", 0.5), ("100%", 1.0)] { + let spec = Slider::new(ui, fraction) + .on_change(|_| pressed("slider")) + .state(Interaction::Enabled); + values = values.push( + row![ + row_label(ui, label), + container(inputs::slider(spec)).width(Length::Fixed(track_width)), + ] + .spacing(ui.space(Space::X2)) + .align_y(iced::Alignment::Center), + ); + } + + // 离散：4 段 = 3 个内部停靠点（25 / 50 / 75%），当前 25% ⇒ 能看到 50% 与 75% 两个点 + let discrete = row![ + row_label(ui, "离散 4"), + container(inputs::slider( + Slider::new(ui, 0.25) + .steps(4) + .on_change(|_| pressed("slider")) + .state(Interaction::Enabled) + )) + .width(Length::Fixed(track_width)), + ] + .spacing(ui.space(Space::X2)) + .align_y(iced::Alignment::Center); + + column![ + note( + ui, + "轨 16 full（Primary / SecondaryContainer）· 竖条 4×44 full（overflow 上下各 14）· \ + focus/pressed 收窄到 2 · 命中 48 · 离散停靠点 4" + ), + state_row(ui, "五态", cells), + note(ui, "0% / 50% / 100%：竖条在两端贴边但不越界（左缘 = 轨道左缘，右缘 = 轨道右缘）"), + values, + note( + ui, + "离散：steps(4) ⇒ 3 个内部停靠点（25/50/75%），未激活轨在停靠点两侧留 6 空隙，\n 激活段只画到竖条中心", + ), + discrete, + ] + .spacing(ui.space(Space::X2)) + .into() +} + +/// Menu：一只五态菜单 + 一只展开态菜单（选中 / 分组线 / 禁用）。 +fn menu_part<'a>(ui: &'a Ui) -> Element<'a, DemoMessage> { + let width = ui.space(Space::X8) * 8.0; + + let mut states = Menu::new().width(Length::Fixed(width)); + for state in Interaction::ALL { + let mut item = MenuItem::new("重命名", pressed("menu")).state(state); + if state.is_disabled() { + item = MenuItem::disabled("重命名").state(state); + } + states = states.item(item.leading(IconKind::Folder)); + } + + let open = Menu::new() + .width(Length::Fixed(width)) + .item(MenuItem::new("重命名", pressed("menu")).leading(IconKind::Folder)) + .item( + MenuItem::new("复制实例", pressed("menu")) + .leading(IconKind::Download) + .trailing(IconKind::Check) + .selected(), + ) + .divider() + .item(MenuItem::disabled("删除").leading(IconKind::Trash)); + + column![ + note( + ui, + "容器 SurfaceContainer + L2 阴影（blur 6 / offset 2 / Shadow 角色）· 圆角 4（令牌表）· \ + 项高 48 · 水平 12 · 上下留白 8 · 选中项 SecondaryContainer 指示器内缩 4、圆角 8" + ), + row![ + column![note(ui, "五态（每项强制一态）"), inputs::menu(ui, states)] + .spacing(ui.space(Space::X2)), + column![ + note(ui, "展开：含选中项 / 分组分隔线（复用 divider）/ 不可点项"), + inputs::menu(ui, open) + ] + .spacing(ui.space(Space::X2)), + ] + .spacing(ui.space(Space::X6)), + ] + .spacing(ui.space(Space::X2)) + .into() +} diff --git a/crates/app-iced/src/components/gallery/mod.rs b/crates/app-iced/src/components/gallery/mod.rs new file mode 100644 index 0000000..f83897a --- /dev/null +++ b/crates/app-iced/src/components/gallery/mod.rs @@ -0,0 +1,375 @@ +//! `--screen=gallery` 的壳：**视觉验收 harness**（D30 / D39 §5），不是产品页面。 +//! +//! ## 它是什么、不是什么 +//! +//! - 是：**状态矩阵的取景框**。每个家族在自己的 `gallery/.rs` 里摆出 +//! 「五变体 × 五态」的矩阵，一张截图就能判完该家族（浅/深各一张 = 10 张证据）。 +//! - 不是：页面。gallery 允许堆叠、不分页、不做空态，**难看不算问题**； +//! 但**每个组件本身**必须按官方口径做到位。 +//! +//! ## 并行地基（后续四条线怎么加东西） +//! +//! 五个家族文件在下面 `mod` 里**全部预先声明**了，每个都有自己的 `section()`： +//! +//! ```text +//! gallery/buttons.rs ← COMPBASE（本 mission） +//! gallery/selection.rs ← 后续 mission（只改这个文件） +//! gallery/inputs.rs ← 同上 +//! gallery/feedback.rs ← 同上 +//! gallery/navigation.rs ← 同上 +//! ``` +//! +//! 加组件 = 只改自己那个文件里的 `section()`，**不用碰本文件**（这是「五条线并行不冲突」的 +//! 具体保证，也是 tower 会亲手验的一条）。 +//! +//! ## DemoMessage 为什么独立 +//! +//! 契约 §2：组件不 import `crate::app::Message`。gallery 用自己定义的消息枚举， +//! 正好当「组件能脱离业务验收」的示范——`app.rs` 只做一次 `.map(Message::Demo)` 就接上了。 +//! +//! ## 截图命令（D30） +//! +//! ```text +//! unlucky-launcher-iced --software-renderer --screen=gallery \ +//! --screenshot out.png --screenshot-theme=light +//! ``` +//! +//! `--screenshot` 不带主题时**默认 Light**（可复现；见 `cli::Options::capture_flavor`）。 +//! +//! ## 段落过滤：环境变量 `ULL_GALLERY_SECTION`（M76 起） +//! +//! 五段拼成一列、外面套 `scrollable`，而截图只截**首屏** `1180×760`。段数一多，后面的家族 +//! 就落到折叠线以下（实测：selection 段从 y≈735 起，只剩标题一行）——那条线的 +//! 「渲染层像素断言」就没有一个像素可量。所以这里加一个**段落选择器**： +//! +//! ```text +//! ULL_GALLERY_SECTION=all # 默认：五段全渲染（行为与加开关之前逐像素一致） +//! ULL_GALLERY_SECTION=buttons # 只渲染 buttons 段 +//! ULL_GALLERY_SECTION=selection # 只渲染 selection 段（本 mission 的取证与 probe 用它） +//! ``` +//! +//! 取值：`all` / `buttons` / `divider` / `selection` / `inputs` / `feedback` / `navigation`。 +//! 语义是「**不构建**没被选中的段」（不是构建后隐藏）：`column` 里根本不 push 它， +//! 于是该家族的 `view` 一行都不跑。未识别的值**回落 `all`** 并在 stderr 打一行提示 +//! （静默回落会让人拿错图还以为拍的是那一段）。 +//! +//! 为什么用环境变量而不是 `--screen=gallery:`：`cli.rs` 不归组件线（M82 在改它）， +//! 而环境变量既能被测试（`cargo test` 里 `std::env::set_var`）又不用跟别人的 CLI 解析抢文件。 +//! 各家族的 `demo()` 签名**不因此改变**——本文件只决定「push 哪几段」。 +//! +//! 实际渲染了哪几段会打一行 `[gallery] section=... → 渲染 ...`（首帧一次）， +//! 拿它当出图日志的证据。 + +use std::sync::atomic::{AtomicBool, Ordering}; + +use iced::widget::{column, container, scrollable, text}; +use iced::{Alignment, Background, Element, Length}; + +use unlucky_design::color::Role; +use unlucky_design::elevation::MaterialLayer; +use unlucky_design::shape::ShapeScale; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; + +use crate::shot::flavor_slug; +use crate::theme::Ui; + +use super::divider; +use super::interaction::Interaction; +use super::layout; + +mod buttons; +mod feedback; +mod inputs; +mod navigation; +#[cfg(test)] +mod probe; +#[cfg(test)] +mod scan; +mod selection; + +/// 段落过滤的环境变量名（语义见模块文档「段落过滤」）。 +pub const SECTION_ENV: &str = "ULL_GALLERY_SECTION"; + +/// 段落开关：**构建**哪几段（`false` = 这一段连 `view` 都不跑）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +struct Sections { + buttons: bool, + divider: bool, + selection: bool, + inputs: bool, + feedback: bool, + navigation: bool, +} + +impl Sections { + /// 五段全渲染（默认）。 + const ALL: Self = Self { + buttons: true, + divider: true, + selection: true, + inputs: true, + feedback: true, + navigation: true, + }; + + /// 只有一段。 + fn only(name: &str) -> Option { + let mut sections = Self { + buttons: false, + divider: false, + selection: false, + inputs: false, + feedback: false, + navigation: false, + }; + match name { + "buttons" => sections.buttons = true, + "divider" => sections.divider = true, + "selection" => sections.selection = true, + "inputs" => sections.inputs = true, + "feedback" => sections.feedback = true, + "navigation" => sections.navigation = true, + _ => return None, + } + Some(sections) + } + + /// 读 `ULL_GALLERY_SECTION`。 + /// + /// 未设置 / 空 / `all`（大小写不敏感）→ 全渲染；**未识别的值 → 回落全渲染 + stderr 一行**。 + fn from_env() -> Self { + let Ok(raw) = std::env::var(SECTION_ENV) else { + return Self::ALL; + }; + let name = raw.trim().to_ascii_lowercase(); + if name.is_empty() || name == "all" { + return Self::ALL; + } + if let Some(sections) = Self::only(&name) { + return sections; + } + eprintln!( + "[gallery] {SECTION_ENV}={raw:?} 不是已知段（all|buttons|divider|selection|inputs|feedback|navigation），已回落 all" + ); + Self::ALL + } + + /// 本次渲染的段名（stderr 日志 / 测试断言用）。 + fn names(self) -> Vec<&'static str> { + let mut names = Vec::new(); + for (on, name) in [ + (self.buttons, "buttons"), + (self.divider, "divider"), + (self.selection, "selection"), + (self.inputs, "inputs"), + (self.feedback, "feedback"), + (self.navigation, "navigation"), + ] { + if on { + names.push(name); + } + } + names + } +} + +/// `[gallery] ... 渲染 ...` 只打一次（`view` 每帧都会跑）。 +static SECTION_LOGGED: AtomicBool = AtomicBool::new(false); + +fn log_sections(sections: Sections) { + if SECTION_LOGGED.swap(true, Ordering::Relaxed) { + return; + } + let raw = std::env::var(SECTION_ENV).unwrap_or_else(|_| "all".to_owned()); + eprintln!( + "[gallery] section={raw} → 渲染 {} 段：{}", + sections.names().len(), + sections.names().join(", ") + ); +} + +/// gallery 自己的消息（与业务 `Message` 解耦，契约 §2）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum DemoMessage { + /// 某个演示按钮被按下（`&'static str` = 演示 id，只用于日志）。 + Pressed(&'static str), +} + +impl DemoMessage { + /// 演示 id（日志用；将来加变体时这里跟着改，`app.rs` 不用动）。 + pub fn id(&self) -> &'static str { + match self { + DemoMessage::Pressed(id) => id, + } + } +} + +/// gallery 根视图（整窗：不带标题栏与导航轨，验收图上只有组件）。 +pub fn view<'a>(ui: &'a Ui) -> Element<'a, DemoMessage> { + let page = ui.style(TypeRole::BodySmall); + + let header = column![ + text("Component gallery") + .size(ui.emphasized(TypeRole::TitleLarge).size_px) + .font(ui.emphasized_font(TypeRole::TitleLarge)) + .color(ui.color(Role::OnSurface)), + text(format!( + "M3 Expressive component base · flavor={} · 1180×760 @100% DPI · \ + focus 与 pressed 同为 10%（令牌口径，图上一样是对的）", + flavor_slug(ui) + )) + .size(page.size_px) + .font(ui.font_of(page)) + .color(ui.color(Role::OnSurfaceVariant)), + ] + .spacing(ui.space(Space::X1)); + + // 小节之间**不画分隔线**：rubric（15 §22.4）要求同屏同类线 ≤3， + // 而验收图里要给分隔线自己留证据（见 `divider_proof`）。分组靠 32px 留白 + 标题。 + // + // 段落过滤（`ULL_GALLERY_SECTION`）：**没被选中的段根本不 push**，于是该家族的 + // `view` 一行都不跑——不是「构建后隐藏」。默认 `all` 与加开关之前逐像素一致。 + let picked = Sections::from_env(); + log_sections(picked); + let mut sections = column![].spacing(ui.space(Space::X8)).width(Length::Fill); + if picked.buttons { + sections = sections.push(buttons::section(ui)); + } + if picked.divider { + sections = sections.push(divider_proof(ui)); + } + if picked.selection { + sections = sections.push(selection::section(ui)); + } + if picked.inputs { + sections = sections.push(inputs::section(ui)); + } + if picked.feedback { + sections = sections.push(feedback::section(ui)); + } + if picked.navigation { + sections = sections.push(navigation::section(ui)); + } + + // 滚动条：默认是主题给的 10px 深灰 thumb，压过组件本体（视觉 reviewer P2-4）。 + // 这里把它改成 **透明轨 + OutlineVariant thumb**；宽度 10px 是 `scrollable` 的内部常量 + // （该控件不暴露 Scrollbar 配置），所以只做了「低对比」这一半，已登记为偏离 D7。 + let body = scrollable(sections) + .height(Length::Fill) + .width(Length::Fill) + .style(move |theme, status| { + // `scrollable::Style` 没有 `Default`：底色/间隙从主题默认值出发，只覆盖竖轨 + let base = scrollable::default(theme, status); + scrollable::Style { + vertical_rail: scrollable::Rail { + background: None, + border: iced::Border::default(), + scroller: scrollable::Scroller { + background: Background::Color(ui.color(Role::OutlineVariant)), + border: iced::Border { + radius: ui.radius(ShapeScale::Full, ui.space(Space::X2)), + ..iced::Border::default() + }, + }, + }, + ..base + } + }); + + // 页面留白走 `layout::inset`（左右/上下各 24）：这是 Q8/Q9 那两个 helper 的第三个兄弟， + // 存在意义是「只改内边距、不改尺寸」，也顺手避免把 Padding 的上右下左写反。 + let page_padding = ui.space(Space::X6); + container(layout::inset( + page_padding, + page_padding, + column![header, body].spacing(ui.space(Space::X4)), + )) + .width(Length::Fill) + .height(Length::Fill) + .style(|_theme| container::Style { + background: Some(Background::Color(ui.layer(MaterialLayer::Canvas))), + ..container::Style::default() + }) + .into() +} + +/// 分隔线的视觉证据（§22）：一条通栏 + 一条列表内缩进，各自带说明。 +/// +/// 单独一节而不是散落各处：`15 §22.4` 说「同屏同类线 ≤3」，这两条是**唯一**计入的两条。 +fn divider_proof<'a>(ui: &'a Ui) -> Element<'a, DemoMessage> { + let caption = ui.style(TypeRole::LabelSmall); + let label = |text_value: &'a str| { + text(text_value) + .size(caption.size_px) + .font(ui.font_of(caption)) + .color(ui.color(Role::OnSurfaceVariant)) + }; + + column![ + heading( + ui, + "divider · full / list-inset", + "15 §22：厚度 1px（stroke::HAIRLINE）· 颜色 OutlineVariant · 列表内左缩进 16 · 同屏 ≤3 条" + ), + label("full (通栏，区块分隔)"), + divider::full::(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..73f927f --- /dev/null +++ b/crates/app-iced/src/components/gallery/probe.rs @@ -0,0 +1,368 @@ +//! 渲染层几何断言：**对着真截图量像素**（M68 的教训：纯函数返回对，图可能是错的）。 +//! +//! `buttons::tests` 只能证明「几何结构体里的数字是 40/20/24」——M68 的药丸正是这样：单测全绿、 +//! 图上是 88×32（容器被 `center_x(Length::Fill)` 覆盖）。唯一能抓住这类错误的是**真渲染的像素**。 +//! CI 没有桌面，所以这里不自己开窗：先用 `--screen=gallery --screenshot` 出真窗截图，本测试读 +//! 那张 PNG 量几何、与令牌逐项比对。**没给图就跳过并大声说出来**（不静默通过）。 +//! +//! 复现命令（在 worktree 根目录）： +//! +//! ```text +//! cargo build -p unlucky-app-iced --bin unlucky-launcher-iced +//! ./target/debug/unlucky-launcher-iced --software-renderer --screen=gallery \ +//! --screenshot target/m75/gallery-light.png --screenshot-theme=light +//! ULL_GALLERY_SHOT=target/m75/gallery-light.png cargo test -p unlucky-app-iced gallery::probe +//! ``` +//! +//! 量什么（每条对一个已发生过的错误）：实心块高 **40**（12b 1.1）· 药丸顶行**左内缩 ≈14** ⇒ 圆角 full=20 +//! （12b 1.2，8 圆角会接近通栏）· IconButton **40×40**（12b 2.1）· 字形墨迹 **16~26** +//! （Q9：24 盒被填满会到 40）· 分隔线 **1px**（22.1）· 禁用容器 **on-surface@10%**（按钮族）存在（12b 1.8）。 + +use unlucky_design::color::{Role, SchemeFlavor}; +use unlucky_design::typography::Platform; + +use crate::theme::{Families, Ui}; + +use crate::app::components::interaction; + +use super::scan::{matches, nearer, rgb, Shot}; + +const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", +}; + +fn ui(flavor: SchemeFlavor) -> Ui { + Ui::with_platform(flavor, Platform::Windows, FAMILIES) +} + +/// 一条 1dp 细线在竖直方向的「墨量覆盖率」：各行相对底色的不透明度之和（1dp ⇒ ≈1.0）。 +/// +/// **只统计「长横线行」**（连续非底色像素 > 900）：标题/正文那些行也有几百个零散墨迹像素， +/// 按「任意非底色像素数」筛会把文字算进墨量（首版实测 57.9，明显是文字被算进去了）。 +fn line_coverage(shot: &Shot, surface: [u8; 3], line: [u8; 3]) -> f32 { + let mut total = 0.0; + for y in 0..shot.height { + let mut longest = 0; + let mut current = 0; + let mut sum = 0.0f32; + let mut run_sum = 0.0f32; + for x in 0..shot.width { + let pixel = shot.at(x, y); + if !matches(pixel, surface) { + current += 1; + run_sum += delta_ratio(pixel, surface, line); + if current > longest { + longest = current; + sum = run_sum; + } + } else { + current = 0; + run_sum = 0.0; + } + } + if longest > 900 { + total += sum / longest as f32; + } + } + total +} + +/// `pixel` 相对 `surface` 的偏移占「满档 line 色偏移」的比例（0..=1）。 +fn delta_ratio(pixel: [u8; 3], surface: [u8; 3], line: [u8; 3]) -> f32 { + let channel = |i: usize| { + let full = f32::from(line[i]) - f32::from(surface[i]); + if full.abs() < 1.0 { + return 0.0; + } + ((f32::from(pixel[i]) - f32::from(surface[i])) / full).clamp(0.0, 1.0) + }; + let (dr, dg, db) = (channel(0), channel(1), channel(2)); + (dr + dg + db) / 3.0 +} + +/// `ULL_GALLERY_SHOT` → 截图路径（相对路径按**工作区根**解释：`cargo test` 的 cwd 是 crate 目录）。 +fn shot_path() -> Option { + let raw = std::env::var_os("ULL_GALLERY_SHOT")?; + let path = std::path::PathBuf::from(raw); + if path.is_absolute() || path.exists() { + return Some(path); + } + let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../.."); + Some(root.join(path)) +} + +/// 一条测试覆盖全部几何断言（每张图各跑一次）。 +#[test] +fn gallery_geometry_matches_the_tokens() { + let Some(path) = shot_path() else { + eprintln!( + "[probe] SKIPPED：未设置 ULL_GALLERY_SHOT。这是**渲染层**几何断言，\ + 需要先出一张真窗截图（命令见本文件模块文档）。" + ); + return; + }; + + let shot = Shot::load(&path).expect("读 gallery 截图"); + assert_eq!( + (shot.width, shot.height), + (1180, 760), + "验收图必须是 D30 的 1180×760 @100% DPI" + ); + + // 用左上角背景色判定深浅（页面 padding 区就是 `Surface`） + let corner = shot.at(2, 2); + let flavor = if matches(corner, rgb(ui(SchemeFlavor::Light).color(Role::Surface))) { + SchemeFlavor::Light + } else { + SchemeFlavor::Dark + }; + let ui = ui(flavor); + + // ---- 12b 1.1 / 1.2：实心按钮 40 高、药丸圆角 20 ------------------------------ + let primary = shot.bbox_of(rgb(ui.color(Role::Primary))); + assert!( + primary.len() >= 2, + "至少该找到 Filled 按钮与 Filled IconButton 两块实心（实际 {}）", + primary.len() + ); + + let mut label_button = None; + for bbox in &primary { + // 字形（OnPrimary）会把实心块割出小碎片，只判「成块的」（40×40 = 1600） + if bbox.area() < 800 { + continue; + } + assert!( + (39..=41).contains(&bbox.height()), + "实心块高 {}（参考 40，12b 1.1）@ {:?}", + bbox.height(), + (bbox.left, bbox.top) + ); + if bbox.width() > 60 { + label_button = Some(*bbox); + } + // 12b 2.1：IconButton 容器精确 40×40（别再用区间——reviewer 已证 +2px 抓不住） + if bbox.width() < 60 { + // 宽 = 40（最宽那行是实色，量得准）；高会把底部抗锯齿行排除掉，所以是 39 或 40。 + // 区间收到 39..=40 仍能抓 ±2px 的回归（42 → 41、38 → 37 都会落区间外）。 + assert_eq!(bbox.width(), 40, "IconButton 容器宽必须 40（12b 2.1）"); + assert!( + (39..=40).contains(&bbox.height()), + "IconButton 容器高应 40（实色 39 + 抗锯齿行），实测 {}", + bbox.height() + ); + } + } + + let label_button = label_button.expect("没找到文字按钮的实心块"); + assert!( + label_button.width() >= 58, + "12b 1.7：最小宽 58，实测 {}", + label_button.width() + ); + + // 含抗锯齿的真实外框：中心列上「更接近填充色而不是底色」的连续行 + let fill = rgb(ui.color(Role::Primary)); + let surface = rgb(ui.color(Role::Surface)); + let center = (label_button.left + label_button.right) / 2; + let mut true_top = label_button.top; + while true_top > 0 && nearer(shot.at(center, true_top - 1), fill, surface) { + true_top -= 1; + } + let mut true_bottom = label_button.bottom; + while true_bottom + 1 < shot.height && nearer(shot.at(center, true_bottom + 1), fill, surface) { + true_bottom += 1; + } + let true_height = true_bottom - true_top + 1; + + // **精确 40**：变异成 42 必须红。上一版写的是 `(39..=41).contains(..)`， + // reviewer 把高度改成 42 重新出图后断言照样绿 —— 那就是「渲层断言等于没有」。 + assert_eq!( + true_height, 40, + "可见高必须精确 40（12b 1.1）；变异成 42 这里就会红" + ); + + // 圆角档位：量**顶部那一行的左内缩**。按像素中心口径，第 k 行（k 从 0 起）的闭式是 + // inset(k) = r − √(r² − (r − k − 0.5)²)；r=20、k=1 给 **12.40**（实测 12~14）， + // r=8 只有 ≈3.6，直角为 0。比「数圆角行数」抗锯齿得多。 + let top_row_left = (label_button.left..=label_button.right) + .find(|x| matches(shot.at(*x, label_button.top), fill)) + .expect("顶部行应至少有一个填充像素"); + let top_inset = top_row_left - label_button.left; + assert!( + (11..=17).contains(&top_inset), + "药丸圆角应 = 20（12b 1.2）：顶部行左内缩应 ≈14，实测 {top_inset}（8 圆角 ≈4，直角 0）" + ); + + // ---- 12b 1.4：带前置图标的左内边距 = 16（用 Filled 格量，避开圆角只扫中间带）---- + // 判「墨迹」的方式：比容器色更接近 OnPrimary。不要用字面量白——浅色页面底色 (246,250,255) + // 与白在容差内，会把圆角外的底色当成墨迹（首次实现就踩了，量出 3）。 + let on_primary = rgb(ui.color(Role::OnPrimary)); + let mut left_ink: Option = None; + for y in (label_button.top + 12)..=(label_button.bottom - 12) { + for x in (label_button.left + 4)..=label_button.right { + if nearer(shot.at(x, y), on_primary, fill) { + left_ink = Some(left_ink.map_or(x, |best: usize| best.min(x))); + } + } + } + let icon_pad = left_ink.expect("Filled 格应带前置图标（量内边距用）") - label_button.left; + // 图标盒左缘 = 16；字形在 24 viewBox 里自带 ≈5.3 左边距 ⇒ 墨迹落在 21 附近 + // （16 → 21；24 → 29；8 → 13，三档互不重叠） + assert!( + (18..=24).contains(&icon_pad), + "12b 1.4：带图标左内边距应 16（墨迹 ≈21），实测 {icon_pad}" + ); + + // ---- Q9：IconButton 的字形不许撑满 40 盒 ----------------------------------- + let tonal = rgb(ui.color(Role::SecondaryContainer)); + let tonal_boxes = shot.bbox_of(tonal); + let icon_states = tonal_boxes + .iter() + .filter(|bbox| (39..=41).contains(&bbox.width()) && (39..=41).contains(&bbox.height())) + .count(); + // 只有 **enabled** 列是精确的 SecondaryContainer（hover/pressed/focus 列叠了状态层，颜色不同）， + // 所以这里只要求 ≥1：量几何一只就够，五态的可见性由图本身给。 + assert!( + icon_states >= 1, + "tonal IconButton 至少 1 个（实际 {icon_states}）" + ); + + let gear = rgb(ui.color(Role::OnSecondaryContainer)); + let mut measured_glyph = false; + let mut glyph_width = 0; + for bbox in tonal_boxes + .iter() + .filter(|bbox| (39..=41).contains(&bbox.width())) + { + if let Some(ink) = shot.ink_inside(bbox, gear) { + let width = ink.width(); + if width > glyph_width { + glyph_width = width; + } + assert!( + (16..=26).contains(&width), + "图标盒 24 的字形墨迹应 16~26 宽，实测 {width}（Q9 回归时会接近 40）" + ); + measured_glyph = true; + } + } + assert!(measured_glyph, "没量到 IconButton 的字形"); + + // ---- 22.1：分隔线 1px（按「非底色的长横线」判，不按精确色：线被抗锯齿摊到两行）---- + let surface = rgb(ui.color(Role::Surface)); + let mut runs = 0; + for y in 0..shot.height { + let mut longest = 0; + let mut current = 0; + for x in 0..shot.width { + if !matches(shot.at(x, y), surface) { + current += 1; + longest = longest.max(current); + } else { + current = 0; + } + } + if longest > 300 { + runs += 1; + } + } + // 两条线 × 各摊 1~2 行 ⇒ 2..=4 行 + assert!( + (2..=4).contains(&runs), + "分隔线应 2 条（每条 1px，抗锯齿最多摊 2 行）⇒ 2..=4 行，实测 {runs} 行" + ); + // **墨量覆盖率**：一条 1dp 的线，其各行相对底色的不透明覆盖率之和应 ≈1.0。 + // 1.5dp 的线会到 ≈1.5，2dp 会到 ≈2.0 —— 这是「容忍 1.5 倍粗」的补丁。 + let full = rgb(ui.color(Role::OutlineVariant)); + // 屏上正好 2 条线（通栏 + 列表内缩），所以把总墨量除以 2 得到「单条线的覆盖率」 + let coverage = line_coverage(&shot, surface, full) / 2.0; + assert!( + (0.8..=1.3).contains(&coverage), + "单条分隔线墨量覆盖率应 ≈1.0（= 1dp），实测 {coverage:.2}（1.5dp 会到 ~1.5）" + ); + + // ---- 12b 1.8 禁用态：容器 + **每一行**的内容色（A1 逐变体不同）---------------- + // + // 上一版把两个 reviewer 都指出的重复块留在这里（`disabled_colors` 被调两次、 + // `disabled_container` 被绑定两次），且只有一条「全图数墨迹」的护栏 —— 深色下阈值失效、 + // 单行回退也抓不住。现在按矩阵的行逐条断言。 + // + // **按钮族**：容器 10%（官方 `*ButtonTokens.DisabledContainerOpacity = 0.1f`）、内容 38%。 + // M86 之前这里和 chip 共用同一个 12% 常量，所以断言与实现「一起错」、永远同源——拆族后才对得上。 + let (disabled_container, _) = interaction::disabled_button_colors(&ui, Role::Surface); + assert!( + shot.bbox_of(rgb(disabled_container)) + .iter() + .any(|b| b.width() > 60), + "没找到禁用态实心按钮（12b 1.8：容器 = on-surface@10%）" + ); + + // 矩阵行序（gallery/buttons.rs 的 Variant::ALL + IconVariant::ALL），行距 48 = 40 + 8 + let row_step = 48usize; + let rows: [(usize, Role, bool, &str); 8] = [ + (0, Role::OnSurfaceVariant, true, "filled"), + (1, Role::OnSurface, true, "tonal"), // A1：FilledTonal 是例外 + (2, Role::OnSurfaceVariant, true, "elevated"), + (3, Role::OnSurfaceVariant, false, "outlined"), + (4, Role::OnSurfaceVariant, false, "text"), + (5, Role::OnSurface, false, "icon·standard"), // A1：IconButton 全是 OnSurface + (6, Role::OnSurface, false, "icon·filled"), + // 第 7 行（矩阵最后一行的 tonal IconButton）上一版漏了 —— reviewer 把它的禁用墨迹涂回 + // 满档色时 probe 全绿。A1 同样是 OnSurface（`FilledTonalIconButtonTokens`）。 + (7, Role::OnSurface, true, "icon·tonal"), + ]; + let column_from = shot.width * 2 / 3; // 矩阵最右列 = disabled 列 + for (index, role, on_container, name) in rows { + let y0 = label_button.top + index * row_step; + let y1 = y0 + 44; + // **与实现同源**：按钮族的内容色一律走 `disabled_button_content`（38% 叠在 10% 底上）。 + // 这里若用面状控件族的 `disabled_content_over_role`（12% 底），断言的底就比实现宽一档， + // 差的 1/255 会让「容器对了内容错了」这类错逃过门控——M86 明确要防这个。 + let ink = interaction::disabled_button_content(&ui, role, on_container); + let count = shot.count_in(rgb(ink), column_from, shot.width, y0, y1); + assert!( + count > 40, + "{name} 行的禁用内容（{role:?}@38%）在 disabled 列里只有 {count} px —— 说明这一行没走 A1 的禁用角色" + ); + } + + // filled 禁用容器里不许出现满档 OnPrimary（旧实现是白字压在容器上 = 1.23:1） + let full_content = rgb(ui.color(Role::OnPrimary)); + for bbox in shot.bbox_of(rgb(disabled_container)) { + if bbox.width() < 60 { + continue; + } + // 只扫**内带**：圆角外的页面底色与 OnPrimary 在容差内，贴边扫描会误报。 + for y in (bbox.top + 12)..=(bbox.bottom - 12) { + for x in (bbox.left + 12)..=(bbox.right - 12) { + assert!( + !matches(shot.at(x, y), full_content), + "禁用容器内出现满档 OnPrimary @({x},{y})：禁用标签没降到 38%" + ); + } + } + } + + eprintln!( + "[probe] OK flavor={:?}： + Filled 药丸 {}×{}（参考 高 40 / 宽 ≥58） + 顶行左内缩 {}（r=20 应 ≈14；8 圆角 ≈4；直角 0） + 实心块 {} 个（含 40×40 IconButton） + 分隔线长行 {} 行（每条 1px） + 禁用容器 (on-surface@10%，按钮族) 命中 · 逐行禁用内容断言 {} 行通过 + 分隔线墨量覆盖率 {:.2}（1dp 应 ≈1.0） + 字形墨迹 {}px（24 盒应 16~26）", + flavor, + label_button.width(), + true_height, + top_inset, + primary.len(), + runs, + rows.len(), + coverage, + glyph_width + ); +} diff --git a/crates/app-iced/src/components/gallery/scan.rs b/crates/app-iced/src/components/gallery/scan.rs new file mode 100644 index 0000000..b33f933 --- /dev/null +++ b/crates/app-iced/src/components/gallery/scan.rs @@ -0,0 +1,183 @@ +//! 截图像素扫描工具（`gallery::probe` 的底层，四个后续家族的 probe 也能复用）。 +//! +//! 只做「按颜色找连通块 / 量外接框 / 量某行的连续长度」三件事，不含任何判据—— +//! 判据在同级 `probe.rs` 里，这样每条家族线可以自带 probe 而不用重写扫描逻辑。 + +use std::path::Path; + +use iced::Color; + +/// 颜色比对的通道容差（抗锯齿/取整）。 +const TOLERANCE: u8 = 10; + +/// iced 颜色 → 8bit RGB（截图里的原值）。 +pub(super) fn rgb(color: Color) -> [u8; 3] { + [ + (color.r * 255.0).round() as u8, + (color.g * 255.0).round() as u8, + (color.b * 255.0).round() as u8, + ] +} + +/// 颜色是否落在容差内。 +pub(super) fn matches(pixel: [u8; 3], expected: [u8; 3]) -> bool { + pixel + .iter() + .zip(expected) + .all(|(a, b)| a.abs_diff(b) <= TOLERANCE) +} + +/// 一张图的像素访问器。 +pub(super) struct Shot { + pub(super) width: usize, + pub(super) height: usize, + pixels: Vec<[u8; 3]>, +} + +impl Shot { + pub(super) fn load(path: &Path) -> Result { + 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/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..32a0bad --- /dev/null +++ b/crates/app-iced/src/components/inputs/field.rs @@ -0,0 +1,398 @@ +//! 文本框（`research/12b` §9）：Filled / Outlined 两式，**受控组件**。 +//! +//! ## 参考值（`[源]` = A1，本机 `material3-android:1.4.0` 的 `*TextFieldTokens` + `TextFieldDefaults`） +//! +//! | # | 检查项 | 参考值 | 落点 | +//! |---|---|---|---| +//! | 9.1 | 高度 | min **56**（带标签）；无标签单行本项目 **40** | `FIELD_HEIGHT`（G16）/ `LM.control_height` | +//! | 9.2 | 最小宽 | **280** → **G21 未施加**（iced 的 `Length` 无 min-width，同按钮 G15） | 文档 | +//! | 9.3 | 形状 | Outlined **4**；Filled 顶圆角 4、底直角 | `Component::TextField.spec().shape` | +//! | 9.4 | 描边 / 指示线 | Outlined 静息 1dp `Outline` → hover 1dp `OnSurface` → 聚焦 **2dp `Primary`**；Filled 底指示线静息 `OnSurfaceVariant` | [`Filled`] / [`Palette`] | +//! | 9.5 | 字级 | 输入/标签 `BodyLarge 16/24`；辅助/错误 `BodySmall 12/16` | `TypeRole` | +//! | 9.6 | 图标 | 前后 **24**、`OnSurfaceVariant`；图标可视边 **12**、文本从 **48** 起 | `FieldGeometry` | +//! | 9.7 | 错误态 | 线/标签/辅助文本全 **`Error`**、线宽 **2dp** | [`Field::error`] | +//! | 9.8 | 禁用态 | Filled 容器 `OnSurface`@**4%**（→ 令牌只有 12%，**登记偏离 D10**）；Outlined 描边 `OnSurface`@**12%**；内容 @**38%** | `interaction::*` | +//! +//! ## 三处口径说明 +//! +//! 1. **状态差异落在指示线/描边/标签上，容器底色不叠状态层**（A1 的口径，与按钮家族的 8%/10% 状态层不同）；press 无独立 token，按 hover 处理（D11）。 +//! 2. 标签是「**常浮起**」的两段式（占上面 16px，不做上浮动画，登记 D12）；缺省宽度 `Fill`（最小宽 280 无法在 iced 表达，G21）。 + +use iced::widget::text::LineHeight; +use iced::widget::{column, container, row, text, text_input}; +use iced::{Alignment, Background, Border, Color, Element, Length, Padding, Pixels}; + +use unlucky_design::color::Role; +use unlucky_design::icons::IconKind; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; + +use crate::icons; +use crate::theme::Ui; + +use super::super::interaction::{self, Interaction}; +use super::super::layout; +use super::geometry::FieldGeometry; + +/// 两式容器（12b 9.3 / 9.4 的差别：Filled 有容器色 + 底部指示线；Outlined 只有描边）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +pub enum FieldVariant { + /// 实心：`SurfaceContainerHighest` + 底部指示线，顶圆角 4 底直角。 + Filled, + /// 描边：透明容器 + 1dp `Outline`，四角 4。 + Outlined, +} + +impl FieldVariant { + /// 两式全序（gallery 的行序）。 + pub const ALL: [FieldVariant; 2] = [FieldVariant::Filled, FieldVariant::Outlined]; + + /// 稳定名字（图例 / 测试信息）。 + pub const fn name(self) -> &'static str { + match self { + FieldVariant::Filled => "filled", + FieldVariant::Outlined => "outlined", + } + } +} + +/// 一个文本框的装配描述（不持有 `String`：受控组件只借值，契约 §2）。 +#[derive(Debug, Clone)] +pub struct Field<'a> { + variant: FieldVariant, + value: &'a str, + label: Option<&'a str>, + placeholder: &'a str, + supporting: Option<&'a str>, + leading: Option, + trailing: Option, + error: bool, + state: Option, + width: Length, + secure: bool, +} + +impl<'a> Field<'a> { + /// 一个 Filled 文本框。 + pub fn new(value: &'a str) -> Self { + Self { + variant: FieldVariant::Filled, + value, + label: None, + placeholder: "", + supporting: None, + leading: None, + trailing: None, + error: false, + state: None, + width: Length::Fill, + secure: false, + } + } + + /// 选式（Filled / Outlined）。 + pub fn variant(mut self, variant: FieldVariant) -> Self { + self.variant = variant; + self + } + + /// 浮动标签（`BodySmall`，常浮起，见模块文档第 2 条）。 + pub fn label(mut self, label: &'a str) -> Self { + self.label = Some(label); + self + } + + /// 占位文案（只在值为空时可见，`OnSurfaceVariant`）。 + pub fn placeholder(mut self, placeholder: &'a str) -> Self { + self.placeholder = placeholder; + self + } + + /// 辅助/错误说明（字段下方 `BodySmall`）。 + pub fn supporting(mut self, supporting: &'a str) -> Self { + self.supporting = Some(supporting); + self + } + + /// 前置图标（24，图标可视边 12）。 + pub fn leading(mut self, kind: IconKind) -> Self { + self.leading = Some(kind); + self + } + + /// 后置图标（24，右侧内边距 16）。 + pub fn trailing(mut self, kind: IconKind) -> Self { + self.trailing = Some(kind); + self + } + + /// 错误态：线 / 标签 / 辅助文本转 `Error`，线宽 2dp（9.7）。 + pub fn error(mut self) -> Self { + self.error = true; + self + } + + /// 强制视觉态（gallery 状态矩阵取证；运行期不要调）。 + pub fn state(mut self, state: Interaction) -> Self { + self.state = Some(state); + self + } + + /// 定宽（默认 `Fill`；gallery 的矩阵格用它钉宽度）。 + pub fn width(mut self, width: Length) -> Self { + self.width = width; + self + } + + /// 密码式输入（M114）：上屏是掩码（明文上屏＝UI 侧凭据泄漏）。 + pub fn secure(mut self, secure: bool) -> Self { + self.secure = secure; + self + } +} + +/// 一个字段在某一态下的全套颜色（9.4 / 9.7 / 9.8 的落点）。 +#[derive(Debug, Clone, Copy, PartialEq)] +struct Palette { + /// 容器底色；`None` = 透明（Outlined）。 + fill: Option, + /// 描边/指示线色。 + line: Color, + /// 描边/指示线宽（1 或 2）。 + stroke: f32, + /// 标签（`BodySmall`）。 + label: Color, + /// 输入文本。 + input: Color, + /// 前后图标。 + icon: Color, + /// 辅助文本。 + supporting: Color, + /// 占位文本。 + placeholder: Color, +} + +/// 解析某一态的颜色（**唯一**做角色映射的地方）。 +fn palette(ui: &Ui, variant: FieldVariant, state: Interaction, error: bool) -> Palette { + let geometry = FieldGeometry::of(ui, true, None); + + if state.is_disabled() { + // 9.8：内容一律 OnSurface@38%；Filled 容器叠 12%（官方 4%，令牌无 4% 档 → D10）； + // Outlined 描边正好是官方 12%。 + let container = interaction::disabled_colors(ui, Role::Surface).0; + let ink = interaction::disabled_content_over_role( + ui, + Role::OnSurface, + matches!(variant, FieldVariant::Filled), + ); + return Palette { + fill: match variant { + FieldVariant::Filled => Some(container), + FieldVariant::Outlined => None, + }, + line: match variant { + FieldVariant::Filled => ink, + FieldVariant::Outlined => container, + }, + stroke: geometry.stroke, + label: ink, + input: ink, + icon: ink, + supporting: ink, + placeholder: ink, + }; + } + + let focused = matches!(state, Interaction::Focused); + let hovered = matches!(state, Interaction::Hovered | Interaction::Pressed); + + let (line, stroke) = if error { + (ui.color(Role::Error), geometry.focus_stroke) + } else if focused { + (ui.color(Role::Primary), geometry.focus_stroke) + } else if hovered { + (ui.color(Role::OnSurface), geometry.stroke) + } else { + ( + match variant { + FieldVariant::Filled => ui.color(Role::OnSurfaceVariant), + FieldVariant::Outlined => ui.color(Role::Outline), + }, + geometry.stroke, + ) + }; + + Palette { + fill: match variant { + FieldVariant::Filled => Some(ui.color(Role::SurfaceContainerHighest)), + FieldVariant::Outlined => None, + }, + line, + stroke, + label: if error { + ui.color(Role::Error) + } else if focused { + ui.color(Role::Primary) + } else { + ui.color(Role::OnSurfaceVariant) + }, + input: ui.color(Role::OnSurface), + icon: if error { + ui.color(Role::Error) + } else { + ui.color(Role::OnSurfaceVariant) + }, + supporting: if error { + ui.color(Role::Error) + } else { + ui.color(Role::OnSurfaceVariant) + }, + placeholder: ui.color(Role::OnSurfaceVariant), + } +} + +/// 一个文本框（Filled / Outlined 由 [`Field::variant`] 选）。 +/// +/// 受控：值由外部持有，输入经 `on_input` 回传；`state` 强制成 `Disabled` 时输入被摘掉 +/// （`on_input_maybe(None)`），所以禁用字段真的点不动，不只是变灰。 +pub fn text_field<'a, M: Clone + 'a>( + ui: &'a Ui, + field: Field<'a>, + on_input: impl Fn(String) -> M + 'a, +) -> Element<'a, M> { + let geometry = FieldGeometry::of(ui, field.label.is_some(), field.leading); + let state = field.state.unwrap_or(Interaction::Enabled); + let colors = palette(ui, field.variant, state, field.error); + + let input_style = ui.style(TypeRole::BodyLarge); + let label_style = ui.style(TypeRole::BodySmall); + + let text_input = text_input(field.placeholder, field.value) + .on_input_maybe(if state.is_disabled() { + None + } else { + Some(on_input) + }) + .secure(field.secure) + .size(input_style.size_px) + .line_height(LineHeight::Absolute(Pixels(input_style.line_height_px))) + .font(ui.font_of(input_style)) + .padding(Padding::default()) + .width(Length::Fill) + .style(move |_theme, _status| text_input::Style { + background: Background::Color(Color::TRANSPARENT), + border: Border::default(), + icon: colors.icon, + placeholder: colors.placeholder, + value: colors.input, + selection: colors.line, + }); + + let mut content = row![].align_y(Alignment::Center).spacing(geometry.icon_gap); + if let Some(kind) = field.leading { + // Q9：图标必须经固定尺寸容器，否则会被 Fill 约束撑满（M68 的 46px 字形） + content = content.push(layout::fixed( + geometry.icon, + geometry.icon, + icons::view::(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/tests.rs b/crates/app-iced/src/components/inputs/field/tests.rs new file mode 100644 index 0000000..f24e9ff --- /dev/null +++ b/crates/app-iced/src/components/inputs/field/tests.rs @@ -0,0 +1,115 @@ +//! field 的单测（从 `field.rs` 拆出：单文件 ≤400 行，AGENTS.md §3-1）。 + +use super::*; +use unlucky_design::color::SchemeFlavor; +use unlucky_design::typography::Platform; + +use crate::theme::Families; + +const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", +}; + +fn ui(flavor: SchemeFlavor) -> Ui { + Ui::with_platform(flavor, Platform::Windows, FAMILIES) +} + +fn build(field: Field<'_>, flavor: SchemeFlavor) -> Element<'_, u8> { + let ui = Box::leak(Box::new(ui(flavor))); + text_field(ui, field, |_| 0_u8) +} + +#[test] +fn every_variant_and_state_builds() { + for variant in FieldVariant::ALL { + for state in Interaction::ALL { + for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] { + let field = Field::new("实例一") + .variant(variant) + .label("名称") + .placeholder("请输入") + .supporting("辅助说明") + .leading(IconKind::Folder) + .trailing(IconKind::Close) + .state(state); + let _: Element<'_, u8> = build(field, flavor); + } + } + } +} + +/// 9.4：聚焦 2dp `Primary`、hover 1dp `OnSurface`、静息 Outlined 1dp `Outline`（Filled 用 OnSurfaceVariant）。 +#[test] +fn outline_colors_and_widths_follow_the_state() { + let ui = ui(SchemeFlavor::Light); + let rest = palette(&ui, FieldVariant::Outlined, Interaction::Enabled, false); + assert_eq!(rest.line, ui.color(Role::Outline)); + assert_eq!(rest.stroke, 1.0); + assert_eq!(rest.fill, None, "Outlined 无容器色"); + + let hover = palette(&ui, FieldVariant::Outlined, Interaction::Hovered, false); + assert_eq!(hover.line, ui.color(Role::OnSurface)); + assert_eq!(hover.stroke, 1.0); + + let focus = palette(&ui, FieldVariant::Outlined, Interaction::Focused, false); + assert_eq!(focus.line, ui.color(Role::Primary)); + assert_eq!(focus.stroke, 2.0, "FocusOutlineWidth = 2dp"); + assert_eq!(focus.label, ui.color(Role::Primary), "FocusLabelColor"); + + // A1 没有 Pressed token：按 hover 处理（D11），不是漏做 + assert_eq!( + palette(&ui, FieldVariant::Outlined, Interaction::Pressed, false), + hover + ); +} + +/// 9.7：错误态线/标签/辅助全 `Error`，线宽 2dp；错误优先于聚焦。 +#[test] +fn error_beats_focus_and_paints_everything_error() { + let ui = ui(SchemeFlavor::Light); + let error = palette(&ui, FieldVariant::Outlined, Interaction::Focused, true); + assert_eq!(error.line, ui.color(Role::Error)); + assert_eq!(error.label, ui.color(Role::Error)); + assert_eq!(error.supporting, ui.color(Role::Error)); + assert_eq!(error.stroke, 2.0, "错误线宽 2dp"); + assert_eq!(error.input, ui.color(Role::OnSurface), "ErrorInputColor"); +} + +/// 9.8：禁用内容 38%、Outlined 描边 12%、Filled 容器 12%（官方 4%，令牌缺口 → D10）。 +#[test] +fn disabled_uses_the_token_alphas() { + for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] { + let ui = ui(flavor); + let container = interaction::disabled_colors(&ui, Role::Surface).0; + + let filled = palette(&ui, FieldVariant::Filled, Interaction::Disabled, false); + assert_eq!(filled.fill, Some(container)); + assert_eq!( + filled.input, + interaction::disabled_content_over_role(&ui, Role::OnSurface, true) + ); + + let outlined = palette(&ui, FieldVariant::Outlined, Interaction::Disabled, false); + assert_eq!(outlined.fill, None); + assert_eq!(outlined.line, container, "DisabledOutlineOpacity = 0.12"); + assert_eq!( + outlined.input, + interaction::disabled_content_over_role(&ui, Role::OnSurface, false) + ); + assert_ne!(outlined.input, ui.color(Role::OnSurface), "禁用不许满档"); + } +} + +/// Filled 有容器色、Outlined 没有；两者圆角都取 `Component::TextField`（4）。 +#[test] +fn filled_carries_the_container_role() { + let ui = ui(SchemeFlavor::Light); + assert_eq!( + palette(&ui, FieldVariant::Filled, Interaction::Enabled, false).fill, + Some(ui.color(Role::SurfaceContainerHighest)), + "FilledTextFieldTokens.ContainerColor" + ); + assert_eq!(FieldGeometry::of(&ui, true, None).shape.dp(), 4.0); +} diff --git a/crates/app-iced/src/components/inputs/geometry.rs b/crates/app-iced/src/components/inputs/geometry.rs new file mode 100644 index 0000000..fc7995d --- /dev/null +++ b/crates/app-iced/src/components/inputs/geometry.rs @@ -0,0 +1,309 @@ +//! 输入类家族的**内部几何**：能取令牌的一律取令牌，取不到的登记 G 编号后集中在这里。 +//! +//! ## 为什么这个文件存在 +//! +//! `components::gate` 的 `t2_no_size_literals_in_components` 扫 `.width(40.0)` 这类**调用点字面量**； +//! 但「TextField 高 56」这种 A 级参考值在 `LayoutMetrics` / `ComponentMetrics` 里确实没有落点 +//! （令牌层是另一条 mission 的 scope，不许我改）。所以按契约 §6.2：**登记 G 编号 + 只在这个文件里 +//! 定义一次**，组件实现一个数字都不写。 +//! +//! ## 参考值表（`[源]` = A1，本机 `material3-android:1.4.0` 的 token 源码；`[估]` = 团队口径） +//! +//! | G | 名称 | 参考值 | 出处 | 本文件落点 | +//! |---|---|---|---|---| +//! | G16 | TextField 可见高（带标签） | **56** | `TextFieldDefaults.MinHeight` / `OutlinedTextFieldTokens.ContainerHeight` | [`FIELD_HEIGHT`] | +//! | G17 | 聚焦/错误描边 | **2** | `OutlinedTextFieldTokens.FocusOutlineWidth`、`FilledTextFieldTokens.FocusActiveIndicatorHeight` | [`FOCUS_STROKE`] | +//! | G18 | Slider 轨道 / 竖条 / 停靠点 | **16 / 4×44 / 4** | `SliderTokens.ActiveTrackHeight` / `HandleWidth`+`HandleHeight` / `StopIndicatorSize` | [`TRACK_HEIGHT`] 等 | +//! | G19 | 菜单项高 | **48** | `Menu.kt:524 MenuListItemContainerHeight` | [`MENU_ITEM_HEIGHT`] | +//! | G20 | Search 宽高 | **min 360 / max 720 / 面板最小 240** | `SearchBar.kt:2712-2713`、`DockedExpandedTableMinHeight` | [`SEARCH_MIN_WIDTH`] 等 | +//! +//! **已经能取令牌、不许在这里重复定义的**（同一数值只许一份，见 `ComponentMetrics` 模块文档）： +//! 搜索条高 56 = `LayoutMetrics::search_bar_height`；无标签单行 40 = `LayoutMetrics::control_height`； +//! 命中区 48 = `LayoutMetrics::touch_target`；水平/上下内边距与图标间距 = `Space::{X2,X3,X4}`； +//! 图标 24 = `IconSize::Toolbar`；圆角 = `ComponentSpec::shape`（TextField/Menu = 4，Search = Full， +//! SearchView = ExtraLarge 28）；一像素线 = `stroke::HAIRLINE`。 +//! +//! ## 与文档的两处口径冲突（按「代码优先」处理，报告里有偏离登记） +//! +//! 1. `12b §8.1` 说菜单圆角「本项目 12（偏离官方 4）」；令牌表 `Component::Menu.spec().shape` +//! 是 `ExtraSmall`（**4**）。令牌层是 M69 定案的真源，本实现取 **4**，不取 12。 +//! 2. `12b §9.1` 说「无标签单行 40」是登记偏离——40 正好是 `LM.control_height`， +//! 所以那条偏离在实现上是「用骨架令牌」而不是「用字面量」。 + +use iced::Padding; + +use unlucky_design::component_map::Component; +use unlucky_design::icons::{IconKind, IconSize}; +use unlucky_design::shape::ShapeScale; +use unlucky_design::spacing::Space; + +use crate::theme::{Ui, STROKE_PX}; + +/// G16：文本字段可见高（带浮动标签）。 +pub const FIELD_HEIGHT: f32 = 56.0; + +/// G17：聚焦/错误态的描边与指示线宽（官方 2dp；令牌层的 `stroke::HAIRLINE` 只有 1dp）。 +pub const FOCUS_STROKE: f32 = 2.0; + +/// G18：Slider 轨道高（激活/未激活同值）。 +pub const TRACK_HEIGHT: f32 = 16.0; + +/// G18：Slider 竖条 handle 宽（静息 / hover）。 +pub const HANDLE_WIDTH: f32 = 4.0; + +/// G18：Slider 竖条 handle 宽（focus / pressed）——A1 在这两态收窄到 2。 +pub const HANDLE_WIDTH_ACTIVE: f32 = 2.0; + +/// G18：Slider 竖条 handle 高（纵向溢出轨道，上下各 14）。 +pub const HANDLE_HEIGHT: f32 = 44.0; + +/// G18：离散停靠点直径。 +pub const STOP_SIZE: f32 = 4.0; + +/// G18：停靠点与轨道段之间的空隙（官方 `StopIndicatorTrailingSpace = 6`；6 不在 4px 栅格上）。 +pub const STOP_GAP: f32 = 6.0; + +/// G19：菜单项高。 +pub const MENU_ITEM_HEIGHT: f32 = 48.0; + +/// G20：搜索条最小宽（列宽不足时**不许压窄**，降级为 40 高 TextField 或 icon 入口）。 +pub const SEARCH_MIN_WIDTH: f32 = 360.0; + +/// G20：搜索条最大宽。 +pub const SEARCH_MAX_WIDTH: f32 = 720.0; + +/// G20：展开面板最小高（空结果也不许矮于它）。 +pub const SEARCH_VIEW_MIN_HEIGHT: f32 = 240.0; + +/// 文本字段的几何（Filled / Outlined 共用；差别只在颜色与形状）。 +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct FieldGeometry { + /// 可见高：带标签 [`FIELD_HEIGHT`]，无标签 `LM.control_height`。 + pub height: f32, + /// 内容内边距（无图标 16/16；有前置图标 12/16，图标与文本间距另算）。 + pub padding: Padding, + /// 前置图标可视左边距（无偏移，就是内边距 12）。 + pub icon_inset: f32, + /// 图标 ↔ 文本间距（12：12 + 24 + 12 = 48 起文本，与官方 48 的图标槽一致）。 + pub icon_gap: f32, + /// 图标边长（24）。 + pub icon: f32, + /// 静息描边（一像素线）。 + pub stroke: f32, + /// 聚焦/错误描边（2）。 + pub focus_stroke: f32, + /// 圆角档位（`Component::TextField` = ExtraSmall）。 + pub shape: ShapeScale, +} + +impl FieldGeometry { + /// 求值；`labeled` = 带浮动标签（56），否则单行 40；`leading` = 有没有前置图标。 + pub fn of(ui: &Ui, labeled: bool, leading: Option) -> Self { + let icon_inset = ui.space(Space::X3); + let pad_end = ui.space(Space::X4); + let padding = if leading.is_some() { + Padding { + top: 0.0, + right: pad_end, + bottom: 0.0, + left: icon_inset, + } + } else { + Padding { + top: 0.0, + right: pad_end, + bottom: 0.0, + left: pad_end, + } + }; + + Self { + height: if labeled { + FIELD_HEIGHT + } else { + ui.metrics().control_height + }, + padding, + icon_inset, + icon_gap: ui.space(Space::X3), + icon: IconSize::Toolbar.px(), + stroke: STROKE_PX, + focus_stroke: FOCUS_STROKE, + shape: Component::TextField.spec().shape, + } + } +} + +/// Slider 的几何（轨道 / 竖条 / 停靠点 / 命中区）。 +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct SliderGeometry { + /// 轨道高（16）。 + pub track: f32, + /// 竖条宽（静息 4 / focus·pressed 2）。 + pub handle: f32, + /// 竖条高（44）。 + pub handle_tall: f32, + /// 停靠点直径（4）。 + pub stop: f32, + /// 控件高 = 命中区（`LM.touch_target` 48：竖条 44 + 上下各 2）。 + pub height: f32, +} + +impl SliderGeometry { + /// 从令牌求值。 + pub fn of(ui: &Ui) -> Self { + Self { + track: TRACK_HEIGHT, + handle: HANDLE_WIDTH, + handle_tall: HANDLE_HEIGHT, + stop: STOP_SIZE, + height: ui.metrics().touch_target, + } + } +} + +/// 菜单（Menu / DropdownMenuItem）的几何。 +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct MenuGeometry { + /// 项高（48）。 + pub item_height: f32, + /// 水平内边距（12，来自 `Space::X3`）。 + pub pad_h: f32, + /// 上下留白（8，来自 `Space::X2`）。 + pub pad_v: f32, + /// 槽位图标边长（24）。 + pub icon: f32, + /// 图标 ↔ 文本间距（12）。 + pub gap: f32, + /// 容器圆角档位（`Component::Menu` = ExtraSmall 4）。 + pub shape: ShapeScale, +} + +impl MenuGeometry { + /// 从令牌求值。 + pub fn of(ui: &Ui) -> Self { + Self { + item_height: MENU_ITEM_HEIGHT, + pad_h: ui.space(Space::X3), + pad_v: ui.space(Space::X2), + icon: IconSize::Toolbar.px(), + gap: ui.space(Space::X3), + shape: Component::Menu.spec().shape, + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use unlucky_design::color::SchemeFlavor; + use unlucky_design::typography::Platform; + + use crate::theme::Families; + + const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", + }; + + fn ui() -> Ui { + Ui::with_platform(SchemeFlavor::Light, Platform::Windows, FAMILIES) + } + + /// G16 / G17：两个 2dp 与 56dp 的参考值钉在这里（改参考表会让这条红）。 + #[test] + fn field_geometry_matches_the_reference_table() { + let ui = ui(); + let labeled = FieldGeometry::of(&ui, true, None); + assert_eq!(labeled.height, 56.0, "G16 TextFieldDefaults.MinHeight"); + assert_eq!(labeled.stroke, 1.0, "静息一像素线"); + assert_eq!(labeled.focus_stroke, 2.0, "G17 FocusOutlineWidth"); + assert_eq!(labeled.shape.dp(), 4.0, "CornerExtraSmall"); + + // 无标签单行 40 = 骨架令牌，不是字面量 + let compact = FieldGeometry::of(&ui, false, None); + assert_eq!(compact.height, ui.metrics().control_height); + assert_eq!(compact.height, 40.0); + + // 内边距：无图标 16/16 + assert_eq!(compact.padding.left, 16.0); + assert_eq!(compact.padding.right, 16.0); + assert_eq!(compact.padding.left, compact.padding.right); + } + + /// 前置图标：图标可视边 12、文本从 48 起（= 12 + 24 + 12，官方 48 的图标槽）。 + #[test] + fn field_icon_slot_matches_the_official_48() { + let ui = ui(); + let leading = FieldGeometry::of(&ui, true, Some(IconKind::Search)); + assert_eq!(leading.icon, 24.0, "LeadingIconSize"); + assert_eq!(leading.icon_inset, 12.0, "textFieldHorizontalIconPadding"); + // 文本起点 = 图标可视边 12 + 图标 24 + 间距 12 = 48（官方图标槽） + assert_eq!(leading.icon_inset + leading.icon + leading.icon_gap, 48.0); + // 右侧仍是 16（官方内边距不因图标变） + assert_eq!(leading.padding.right, 16.0); + } + + /// G18：轨道 16 / 竖条 4×44 / 停靠点 4 / 命中 48；竖条比轨道高 28 ⇒ 上下各溢出 14。 + #[test] + fn slider_geometry_matches_the_reference_table() { + let ui = ui(); + let slider = SliderGeometry::of(&ui); + assert_eq!(slider.track, 16.0, "ActiveTrackHeight"); + assert_eq!(slider.handle, 4.0, "HandleWidth"); + assert_eq!(slider.handle_tall, 44.0, "HandleHeight"); + assert_eq!(slider.stop, 4.0, "StopIndicatorSize"); + assert_eq!( + (slider.handle_tall - slider.track) / 2.0, + 14.0, + "上下各溢出" + ); + assert_eq!(slider.height, 48.0, "命中下限 LM.touch_target"); + assert!(slider.height >= slider.handle_tall, "命中区必须容得下竖条"); + // focus / pressed 收窄到 2（A1 FocusHandleWidth / PressedHandleWidth） + assert_eq!(HANDLE_WIDTH_ACTIVE, 2.0); + assert!(HANDLE_WIDTH_ACTIVE < slider.handle); + } + + /// G19：项高 48、水平 12、上下 8、图标 24、圆角按令牌表（4，**不是** 12b 说的 12）。 + #[test] + fn menu_geometry_matches_the_reference_table() { + let ui = ui(); + let menu = MenuGeometry::of(&ui); + assert_eq!(menu.item_height, 48.0, "MenuListItemContainerHeight"); + assert_eq!(menu.pad_h, 12.0, "DropdownMenuItemHorizontalPadding"); + assert_eq!(menu.pad_v, 8.0, "DropdownMenuVerticalPadding"); + assert_eq!(menu.icon, 24.0); + assert_eq!( + menu.shape.dp(), + 4.0, + "MenuTokens.ContainerShape = CornerExtraSmall" + ); + assert_eq!( + menu.shape, + Component::Menu.spec().shape, + "圆角只能来自令牌表" + ); + assert_eq!(menu.gap, ui.space(Space::X3), "图标 ↔ 文本 12 走栅格令牌"); + } + + /// G20：搜索条 min 360 / max 720；面板最小高 240；条高取骨架令牌 56（**不在这里重复定义**）。 + #[test] + fn search_constants_do_not_duplicate_layout_metrics() { + let ui = ui(); + assert_eq!(SEARCH_MIN_WIDTH, 360.0); + assert_eq!(SEARCH_MAX_WIDTH, 720.0); + assert_eq!(SEARCH_VIEW_MIN_HEIGHT, 240.0); + assert_eq!(ui.metrics().search_bar_height, 56.0, "条高来自 LM"); + assert_eq!( + ShapeScale::Full.radius_px(ui.metrics().search_bar_height), + 28.0 + ); + assert_eq!(Component::Search.spec().shape, ShapeScale::Full); + // 图标可视边 = pad + offset（M69 的 SEARCH_BAR 不变量，本文件不重复定义 12/4） + let bar = Component::Search.metrics().expect("Search 有组件级度量"); + assert_eq!(bar.pad_start + bar.icon_offset, 16.0); + assert_eq!(bar.icon, 24.0); + } +} diff --git a/crates/app-iced/src/components/inputs/menu.rs b/crates/app-iced/src/components/inputs/menu.rs new file mode 100644 index 0000000..9dc7050 --- /dev/null +++ b/crates/app-iced/src/components/inputs/menu.rs @@ -0,0 +1,354 @@ +//! 菜单（`research/12b` §8）：`Menu` 弹出层 + `DropdownMenuItem`。 +//! +//! ## 参考值（`[源]` = A1，`MenuTokens` / `Menu.kt` 1.4.0） +//! +//! | # | 检查项 | 参考值 | 落点 | +//! |---|---|---|---| +//! | 8.1 | 容器圆角 | 官方 **4**（`ContainerShape = CornerExtraSmall`）；`12b` 说「本项目 12」——**取令牌表的 4**（报告偏离 D18） | `Component::Menu.spec().shape` | +//! | 8.2 | 容器色 / 高程 | `SurfaceContainer` + **L2** | `Role::SurfaceContainer` + `Elevation::Level2` | +//! | 8.3 | 项高 | **48** | `MENU_ITEM_HEIGHT`（G19） | +//! | 8.4 | 项内边距 | 水平 **12**、菜单上下留白 **8** | `Space::X3` / `Space::X2` | +//! | 8.5 | 字级 / 图标 | 文本 `BodyMedium 14/20`；图标 **24** | `TypeRole` + `IconSize::Toolbar` | +//! | 8.6 | 选中项 | 容器 `SecondaryContainer` + 文本 `OnSecondaryContainer`；指示器水平内缩 **4**、圆角 **8** | [`MenuItem::selected`] | +//! | 8.7 | 宽度 | 不窄于触发元素、长文本不换行（`ellipsis` 本轮不做，登记 D19） | [`Menu::width`] | +//! +//! ## 弹出层阴影 +//! +//! 高程取 `Component::Menu.spec().elevation`（= L2），阴影参数取 `Elevation::shadow()` +//! （`ShadowSpec`：blur 6 / offset 2 / alpha 0.14，令牌层给的值），阴影色取 `Role::Shadow`。 +//! **容器色不取 `MaterialLayer::Overlay`**：那是 `SurfaceContainerHigh`，比 A1 的 `SurfaceContainer` +//! 高一档；`MaterialLayer` 只用来确认「弹出层属于 Overlay 语义」，颜色以 A1 为准。 +//! +//! ## 分组分隔线 +//! +//! 复用 [`crate::app::components::divider::full`]（一像素线 + `OutlineVariant`），**不自己画线**。 +//! 菜单水平内边距 12 由容器给，所以分隔线自然落在 12 内缩后的宽度上。 + +use iced::widget::text::LineHeight; +use iced::widget::{button, column, container, text}; +use iced::{ + Alignment, Background, Border, Color, Element, Length, Padding, Pixels, Shadow, Vector, +}; + +use unlucky_design::color::Role; +use unlucky_design::component_map::Component; +use unlucky_design::elevation::Elevation; +use unlucky_design::icons::IconKind; +use unlucky_design::shape::ShapeScale; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; + +use crate::icons; +use crate::theme::Ui; + +use super::super::divider; +use super::super::interaction::{self, Interaction}; +use super::super::layout; +use super::geometry::MenuGeometry; + +/// 菜单里的一项。 +#[derive(Debug, Clone)] +pub struct MenuItem<'a, M> { + label: &'a str, + leading: Option, + 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, +} + +impl<'a, M> Default for Menu<'a, M> { + fn default() -> Self { + Self::new() + } +} + +impl<'a, M> Menu<'a, M> { + /// 空菜单（默认按容器宽度伸展，宽度由调用方定）。 + pub fn new() -> Self { + Self { + entries: Vec::new(), + width: Length::Fill, + } + } + + /// 追加一项。 + pub fn item(mut self, item: MenuItem<'a, M>) -> Self { + self.entries.push(Entry::Item(item)); + self + } + + /// 追加一条分组分隔线。 + pub fn divider(mut self) -> Self { + self.entries.push(Entry::Divider); + self + } + + /// 菜单宽度（8.7：不窄于触发元素由调用方保证）。 + pub fn width(mut self, width: Length) -> Self { + self.width = width; + self + } +} + +/// 一项的颜色（8.5 / 8.6 / 禁用）。 +#[derive(Debug, Clone, Copy, PartialEq)] +struct ItemPalette { + /// 项底色；`None` = 透明（不画状态层）。 + fill: Option, + /// 文本色。 + ink: Color, + /// 图标色（前置槽位；A1 是 `OnSecondaryContainer`）。 + icon: Color, + /// 圆角档位（选中指示器 8）。 + shape: ShapeScale, +} + +/// 解析一项的颜色：选中优先，其余按五态叠状态层（`interaction::overlay_color`）。 +fn item_palette(ui: &Ui, state: Interaction, selected: bool) -> ItemPalette { + if state.is_disabled() { + // 禁用：内容 38%（无容器时叠在表面色上；菜单项本身透明） + let ink = interaction::disabled_content_over_role(ui, Role::OnSurface, false); + return ItemPalette { + fill: None, + ink, + icon: ink, + shape: ShapeScale::Small, + }; + } + + if selected { + // 选中项也要跟态走：状态层叠在 SecondaryContainer 上（不透明结果，D27） + let fill = interaction::overlay_color( + ui, + state, + Role::OnSecondaryContainer, + Role::SecondaryContainer, + ) + .unwrap_or_else(|| ui.color(Role::SecondaryContainer)); + return ItemPalette { + fill: Some(fill), + ink: ui.color(Role::OnSecondaryContainer), + icon: ui.color(Role::OnSecondaryContainer), + shape: ShapeScale::Small, + }; + } + + ItemPalette { + // 状态层叠在**菜单容器色**上（SurfaceContainer），得到不透明结果（D27） + fill: interaction::overlay_color(ui, state, Role::OnSurface, Role::SurfaceContainer), + ink: ui.color(Role::OnSurface), + icon: ui.color(Role::OnSecondaryContainer), + shape: ShapeScale::Small, + } +} + +/// 菜单弹出层（`SurfaceContainer` + L2 阴影）。 +pub fn menu<'a, M: Clone + 'a>(ui: &'a Ui, menu: Menu<'a, M>) -> Element<'a, M> { + let geometry = MenuGeometry::of(ui); + let spec = Component::Menu.spec(); + let elevation = spec.elevation; + debug_assert_eq!( + elevation, + Elevation::Level2, + "MenuTokens.ContainerElevation" + ); + let shadow_spec = elevation.shadow(); + let panel = ui.color(Role::SurfaceContainer); + let shape = geometry.shape; + + let mut rows = column![].width(Length::Fill); + for entry in menu.entries { + rows = rows.push(match entry { + Entry::Item(item) => item_row(ui, item, geometry), + // 分组分隔线：复用 `divider::full`（一像素线 + OutlineVariant），不自己画 + Entry::Divider => divider::full::(ui), + }); + } + + container(layout::inset(0.0, geometry.pad_v, rows)) + .width(menu.width) + .style(move |_theme| container::Style { + background: Some(Background::Color(panel)), + border: Border { + radius: ui.radius_dp(shape), + ..Border::default() + }, + shadow: Shadow { + color: Color { + a: shadow_spec.alpha, + ..ui.color(Role::Shadow) + }, + offset: Vector::new(0.0, shadow_spec.offset_y_px), + blur_radius: shadow_spec.blur_px, + }, + ..container::Style::default() + }) + .into() +} + +/// 一行菜单项（用 `button` 承载命中与四态，几何与颜色自绘）。 +fn item_row<'a, M: Clone + 'a>( + ui: &'a Ui, + item: MenuItem<'a, M>, + geometry: MenuGeometry, +) -> Element<'a, M> { + let forced = item.state.or(if item.on_press.is_none() { + Some(Interaction::Disabled) + } else { + None + }); + // 选中项的背景也要跟态走：禁用时不许留满档 SecondaryContainer + let colors = item_palette(ui, forced.unwrap_or(Interaction::Enabled), item.selected); + let body = ui.style(TypeRole::BodyMedium); + + let label = text(item.label) + .size(body.size_px) + .line_height(LineHeight::Absolute(Pixels(body.line_height_px))) + .font(ui.font_of(body)) + .color(colors.ink); + + let mut row = iced::widget::Row::new() + .align_y(Alignment::Center) + .spacing(geometry.gap); + if let Some(kind) = item.leading { + // Q9：图标必须经固定尺寸容器 + row = row.push(layout::fixed( + geometry.icon, + geometry.icon, + icons::view::(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, state, selected); + button::Style { + background: colors.fill.map(Background::Color), + text_color: colors.ink, + border: Border { + radius: ui.radius_dp(colors.shape), + ..Border::default() + }, + shadow: Shadow::default(), + snap: true, + } + }; + + let inset = ui.space(Space::X1); + let button = button(content) + .width(Length::Fill) + .height(Length::Fixed(geometry.item_height)) + .padding(Padding { + top: 0.0, + // 选中指示器水平内缩 4（8.6 / 参考图纸），内容仍落在 12 上：12 = 4 + 8 + right: geometry.pad_h - inset, + bottom: 0.0, + left: geometry.pad_h - inset, + }) + .style(style); + + let element: Element<'a, M> = match item.on_press { + Some(message) => button.on_press(message).into(), + None => button.into(), + }; + + container(element) + .width(Length::Fill) + .padding(Padding { + top: 0.0, + right: inset, + bottom: 0.0, + left: inset, + }) + .into() +} + +#[cfg(test)] +mod tests; diff --git a/crates/app-iced/src/components/inputs/menu/tests.rs b/crates/app-iced/src/components/inputs/menu/tests.rs new file mode 100644 index 0000000..19f041b --- /dev/null +++ b/crates/app-iced/src/components/inputs/menu/tests.rs @@ -0,0 +1,123 @@ +//! menu 的单测（从 `menu.rs` 拆出：单文件 ≤400 行，AGENTS.md §3-1）。 + +use super::*; +use unlucky_design::color::SchemeFlavor; +use unlucky_design::typography::Platform; + +use crate::theme::Families; + +const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", +}; + +fn ui(flavor: SchemeFlavor) -> Ui { + Ui::with_platform(flavor, Platform::Windows, FAMILIES) +} + +fn sample(flavor: SchemeFlavor) -> Element<'static, u8> { + let ui = Box::leak(Box::new(ui(flavor))); + let spec = Menu::new() + .item(MenuItem::new("重命名", 1_u8).leading(IconKind::Folder)) + .item( + MenuItem::new("复制实例", 2_u8) + .selected() + .trailing(IconKind::Check), + ) + .divider() + .item(MenuItem::disabled("删除").leading(IconKind::Trash)); + menu(ui, spec) +} + +/// 8.2：容器 `SurfaceContainer` + L2；阴影参数来自高程令牌。 +#[test] +fn container_uses_surface_container_and_level2_shadow() { + let ui = ui(SchemeFlavor::Light); + assert_eq!(Component::Menu.spec().elevation, Elevation::Level2); + assert_eq!( + Component::Menu.spec().elevation.surface_role(), + Role::SurfaceContainer, + "L2 的容器角色与 MenuTokens.ContainerColor 一致" + ); + let shadow = Elevation::Level2.shadow(); + assert!(shadow.is_visible(), "菜单是浮层，必须有可见阴影"); + assert_eq!(shadow.blur_px, 6.0); + assert_eq!(shadow.offset_y_px, 2.0); + // 容器色**不是** MaterialLayer::Overlay（那会高一档） + assert_ne!( + ui.layer(unlucky_design::elevation::MaterialLayer::Overlay), + ui.color(Role::SurfaceContainer) + ); +} + +/// 8.6：选中 = SecondaryContainer + OnSecondaryContainer；禁用内容 38%。 +#[test] +fn selected_and_disabled_items_use_the_right_roles() { + let ui = ui(SchemeFlavor::Light); + let selected = item_palette(&ui, Interaction::Enabled, true); + assert_eq!(selected.fill, Some(ui.color(Role::SecondaryContainer))); + assert_eq!(selected.ink, ui.color(Role::OnSecondaryContainer)); + assert_eq!(selected.icon, ui.color(Role::OnSecondaryContainer)); + + // 选中 + hover：状态层叠在 SecondaryContainer 上（不是满档底色） + let hovered = item_palette(&ui, Interaction::Hovered, true); + assert_ne!(hovered.fill, selected.fill); + assert_eq!( + hovered.fill, + interaction::overlay_color( + &ui, + Interaction::Hovered, + Role::OnSecondaryContainer, + Role::SecondaryContainer + ) + ); + + let disabled = item_palette(&ui, Interaction::Disabled, true); + assert_eq!(disabled.fill, None, "禁用项不留满档选中底色"); + assert_eq!( + disabled.ink, + interaction::disabled_content_over_role(&ui, Role::OnSurface, false) + ); + assert_ne!(disabled.ink, ui.color(Role::OnSurface)); +} + +/// 五态：hover 8% / pressed 10% / focus 10% 都叠在 SurfaceContainer 上（不透明）。 +#[test] +fn item_states_blend_on_the_menu_container() { + let ui = ui(SchemeFlavor::Light); + let rest = item_palette(&ui, Interaction::Enabled, false); + assert_eq!(rest.fill, None, "静息不叠色（菜单底色透出来）"); + for state in [ + Interaction::Hovered, + Interaction::Pressed, + Interaction::Focused, + ] { + let fill = item_palette(&ui, state, false) + .fill + .expect("可交互态必须给底色"); + assert_eq!(fill.a, 1.0, "结果必须不透明（D27）"); + assert_ne!(Some(fill), rest.fill); + } +} + +/// 8.3 / 8.4：项高 48、水平 12（内容）、选中指示器内缩 4 ⇒ 内容仍在 12。 +#[test] +fn item_geometry_matches_the_reference_table() { + let ui = ui(SchemeFlavor::Light); + let geometry = MenuGeometry::of(&ui); + assert_eq!(geometry.item_height, 48.0); + assert_eq!(geometry.pad_h, 12.0); + assert_eq!(geometry.pad_v, 8.0); + let inset = ui.space(Space::X1); + assert_eq!(inset, 4.0); + assert_eq!((geometry.pad_h - inset) + inset, 12.0, "内容落在 12 上"); +} + +/// 三种形态（带槽位 / 选中 / 禁用 / 分组线）都能构建。 +#[test] +fn menu_shapes_build() { + for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] { + let _: Element<'static, u8> = sample(flavor); + } +} diff --git a/crates/app-iced/src/components/inputs/mod.rs b/crates/app-iced/src/components/inputs/mod.rs new file mode 100644 index 0000000..5e880ba --- /dev/null +++ b/crates/app-iced/src/components/inputs/mod.rs @@ -0,0 +1,42 @@ +//! **输入类家族**（D39 §1 的 `inputs/`）：§9 TextField / §20 Search / §11 Slider / §8 Menu。 +//! +//! 四个组件的共同纪律（与本目录外的契约一一对应）： +//! +//! - **对消息类型泛型**（`M: Clone`，不 import `crate::app::Message`）——组件库要能脱离业务验收； +//! - **`&'a Ui` 传入**，组件内部不 `Ui::new`（深浅热切靠外部重建整树）； +//! - **不持有 `String`**：文本框与搜索条是受控组件（借值 + `on_input`/`on_change` 回传）， +//! 滑块也只借一个比例； +//! - **hover/pressed/focus/disabled 一律走 [`super::interaction`]**（α 只有一处定义）； +//! - **精确尺寸走 [`super::layout`]**（Q8/Q9 的两个固定解法），图标一律 `layout::fixed`； +//! - **零尺寸字面量**：能取令牌的取令牌，取不到的集中登记在 [`geometry`] 的 G16~G20。 +//! +//! ## 文件分工 +//! +//! | 文件 | 内容 | +//! |---|---| +//! | [`geometry`] | 内部几何 + G 编号常量（`FieldGeometry` / `SliderGeometry` / `MenuGeometry`） | +//! | [`field`] | [`text_field`]（Filled / Outlined） | +//! | [`search`] | [`search_bar`]（收起）+ [`search_view`]（展开 docked） | +//! | [`slider`] | [`slider`]（自绘 `Widget`：轨道 16 + 竖条 4×44） | +//! | [`menu`] | [`menu`]（`Menu` + `MenuItem` + 分组分隔线） | +//! +//! ## 与契约 §2 示例签名的关系 +//! +//! 契约示例是 `filled(ui, label, on_press)`；本家族的四个组件都比三个参数多（变体 × 五态 × +//! 前后槽位 × 错误/辅助文本），所以照按钮家族的先例把「部件参数」收进构造器结构体： +//! `text_field(ui, Field::new(value).label("名称"), on_input)`。**泛型纪律一字不改**， +//! 差别只是位置参数变命名参数（按钮家族已登记同一决定，见 `buttons` 模块文档）。 + +pub mod geometry; + +mod field; +mod menu; +#[cfg(test)] +mod probe; +mod search; +mod slider; + +pub use field::{text_field, Field, FieldVariant}; +pub use menu::{menu, Menu, MenuItem}; +pub use search::{search_bar, search_view, SearchBar, SearchView}; +pub use slider::{slider, Slider}; diff --git a/crates/app-iced/src/components/inputs/probe.rs b/crates/app-iced/src/components/inputs/probe.rs new file mode 100644 index 0000000..8a1086e --- /dev/null +++ b/crates/app-iced/src/components/inputs/probe.rs @@ -0,0 +1,347 @@ +//! 渲染层几何断言（D30 / M68 的教训：**纯函数对 ≠ 图画对**）。 +//! +//! ## 为什么这个文件在 `inputs/` 而不是 `gallery/probe.rs` +//! +//! 像素工具 `gallery::scan` 是 `mod scan;`（**私有**于 `gallery`），我的 probe 拿不到它， +//! 而 `gallery/mod.rs` 不在本 mission 的 scope 里。所以这里自带一份最小的读图器 +//! （约 40 行：读 PNG / 取点 / 连通块 / 行覆盖），判据全在本文件——已作为 finding 报给 tower +//! （建议把 `gallery::scan` 提升为 `pub(crate)`，四个家族就能共用一份）。 +//! +//! ## 怎么跑（worktree 根目录） +//! +//! ```text +//! # ① 出图：副本工程只把 inputs 段提到首位（组件代码逐字节相同），见 target/m77/sync.py +//! python target/m77/sync.py && (cd /d/tmp/m77-shot && cargo build --no-default-features ...) +//! M77_PART=text ./target/debug/unlucky-launcher-iced.exe --software-renderer --screen=gallery \ +//! --screenshot target/m77/text-light.png --screenshot-theme=light +//! # ② 量图 +//! ULL_INPUTS_DIR=target/m77 cargo test -p unlucky-app-iced inputs::probe +//! ``` +//! +//! 没给 `ULL_INPUTS_DIR` 就**大声跳过**（不静默通过），与 `gallery::probe` 的口径一致。 +//! +//! ## 量什么（每条都对着一个「已经可能画错」的形态） +//! +//! | 断言 | 抓的错误 | +//! |---|---| +//! | 文本框高 **56**、宽 **320** | 高度被内容/内边距吃掉（不是 56 的 A 级值） | +//! | Filled 底部指示线 静息 **1.0** / 聚焦 **2.0** 墨量 | 把 2dp 画成 1dp（或反过来） | +//! | Outlined 描边 静息 **1.0** / 聚焦 **2.0** 墨量 | 同上 | +//! | 错误态：标签 / 线 / 辅助文本全 `Error` | 只把线染红、忘了标签与辅助文本 | +//! | 搜索条高 **56**、图标墨迹偏移 **20**（= 16 + viewBox 4） | 手抄 16/20 当图标边、或 pad 与 offset 少加一段 | +//! | docked 面板 宽 **360** / 头 **56** / 分隔线 **1.0 `Outline`** / 体 **240** | 用 `OutlineVariant`、或头部高度与 bar 不一致 | +//! | Slider 0%（竖条贴左）、50%（分界在中央）、100%（无未激活段） | 位移区间取错（0..W 而不是 handle/2..W−handle/2） | +//! | Slider 竖条 **4×44** | 画成圆点或撑满命中区 | +//! | 菜单项 pitch **48**、选中指示器内缩 **4**、容器高 **161** | 项高/内边距抄错 | +//! | 分组分隔线 **1.0** 墨量 | 分隔线变成 2px | + +use std::path::{Path, PathBuf}; + +use unlucky_design::color::{Role, SchemeFlavor}; +use unlucky_design::typography::Platform; + +use crate::theme::{Families, Ui}; + +const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", +}; + +/// 颜色比对容差（抗锯齿/取整）。 +const TOLERANCE: u8 = 10; + +type Rgb = [u8; 3]; + +fn ui(flavor: SchemeFlavor) -> Ui { + Ui::with_platform(flavor, Platform::Windows, FAMILIES) +} + +fn rgb(color: iced::Color) -> Rgb { + [ + (color.r * 255.0).round() as u8, + (color.g * 255.0).round() as u8, + (color.b * 255.0).round() as u8, + ] +} + +fn matches(pixel: Rgb, expected: Rgb) -> bool { + matches_within(pixel, expected, TOLERANCE) +} + +/// 指定容差的同色判断（量**阴影边**时要用更严的容差：阴影叠上去会落在 10 的容差内）。 +fn matches_within(pixel: Rgb, expected: Rgb, tolerance: u8) -> bool { + pixel + .iter() + .zip(expected) + .all(|(a, b)| a.abs_diff(b) <= tolerance) +} + +/// 一张图的最小访问器（读 PNG / 取点 / 连通块）。 +struct Shot { + width: usize, + height: usize, + pixels: Vec, +} + +/// 一张图里某颜色的连通块外接框（闭区间）。 +#[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..40dc2c3 --- /dev/null +++ b/crates/app-iced/src/components/inputs/probe/search.rs @@ -0,0 +1,80 @@ +//! M77 probe · search（从 `probe.rs` 拆出：单文件 ≤400 行，AGENTS.md §3-1）。 + +use super::*; + +/// 20.1 / 20.4 / 20.6 / 20.8 / 20.9：条 56、图标墨迹偏移 20（= 16 + viewBox 4）、 +/// docked 面板 360 / 头 56 / 分隔线 1.0 `Outline` / 体 240。 +#[test] +fn search_bar_and_docked_panel_geometry() { + let dir = require_dir!(); + for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] { + let shot = shot(&dir, "search", flavor); + let ui = ui(flavor); + let bar_color = rgb(ui.color(Role::SurfaceContainerHigh)); + let ink = rgb(ui.color(Role::OnSurface)); + + let bars = shot.bbox_of(bar_color, 2000); + let bar = bars + .iter() + .filter(|b| b.height() <= 60 && b.width() >= 360) + .min_by_key(|b| b.top) + .copied() + .expect("找不到搜索条（高 ≤60、宽 ≥360）"); + assert_eq!(bar.height(), 56, "20.1 搜索条高必须 56"); + assert!(bar.width() >= 360, "20.2 搜索条宽 ≥ 360"); + + // 20.4：图标墨迹左缘 = pad 12 + offset 4 + viewBox 内 ≈4 = 20（±1） + let inner = (bar.top + 12)..(bar.bottom - 12); + let mut left_ink = usize::MAX; + for y in inner.clone() { + for x in bar.left..bar.right { + if matches(shot.at(x, y), ink) { + left_ink = left_ink.min(x); + } + } + } + let offset = left_ink - bar.left; + assert!( + (19..=21).contains(&offset), + "20.4 前置图标墨迹偏移应 20（= 12 + 4 + viewBox 4）：实测 {offset}" + ); + + // 20.6 / 20.9：docked 面板 360 宽，头 56 + 1px 分隔线 + 体 240 + // （头与体被那条线切成**两个同色块**，所以按 top 排序取前两块） + let mut parts = bars + .iter() + .filter(|b| b.width() == 360) + .copied() + .collect::>(); + 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..3d99951 --- /dev/null +++ b/crates/app-iced/src/components/inputs/search.rs @@ -0,0 +1,353 @@ +//! 搜索（`research/15` §20）：官方是**两个组件**——[`search_bar`]（收起）+ [`search_view`]（展开）。 +//! +//! ## 参考值（`[源]` = A1；本机 `material3-android:1.4.0` 的 `SearchBarTokens` / `SearchBar.kt`） +//! +//! | # | 检查项 | 参考值 | 落点 | +//! |---|---|---|---| +//! | 20.1 | 高 + 圆角 | 高 **56**、圆角 **full = 28**（药丸，不是圆角矩形） | `LM.search_bar_height` + `Component::Search.spec().shape` | +//! | 20.2 | 宽 | min **360** / max **720**（G20：iced 无 min-width，只施加 max） | [`SEARCH_MAX_WIDTH`](super::geometry::SEARCH_MAX_WIDTH) | +//! | 20.3 | 容器色 / 高程 | `SurfaceContainerHigh` + **L0**（token 写 L3，默认值是 L0，按观感取 L0） | `Role::SurfaceContainerHigh` | +//! | 20.4 | 图标位 | leading 24/`OnSurface`、trailing 24/`OnSurfaceVariant`；**可视边 16 = pad 12 + offset 4** | `ComponentMetrics::SEARCH_BAR` | +//! | 20.5 | 文本 / 占位 / 聚焦 | 输入 `BodyLarge`+`OnSurface`；占位 `OnSurfaceVariant`；聚焦 `Secondary` 1px 指示 | `TypeRole` / `Role::Secondary` | +//! | 20.6 | docked 面板 | 头部 **56**、形状 `CornerExtraLarge` = **28** | `ShapeScale::ExtraLarge` | +//! | 20.8 | 头部 / 结果区分隔 | **1px `Outline`**（**不是** `OutlineVariant`！） | 见下 | +//! | 20.9 | 面板尺寸 | 顶距 8、最小高 **240**、docked 宽 **360** | §20B | +//! +//! ## 三处实现口径 +//! +//! 1. **图标可视边一律 `pad + icon_offset` 求和**（`SEARCH_BAR.pad_start = 12` + `icon_offset = 4` = 16）。 +//! M69 把这两个值钉成不变量，本文件**不写 16、也不写 12/4**——只做加法。 +//! 2. `20.8` 的分隔线用 `Role::Outline`，而 `components::divider` 给的是 `OutlineVariant` +//! （那是正文分隔线的角色）。两个角色在 A1 里明确不同，所以这里**不复用** `divider`， +//! 只按一像素线（`stroke::HAIRLINE`）画一条 —— 复用会把 20.8 判成「报 OutlineVariant 即错」。 +//! 3. bar 的 hover / pressed / disabled 在 `SearchBarTokens` 里**没有** token。 +//! hover/pressed 按通用状态层（`interaction::overlay_color`，8%/10%），disabled 按令牌的 +//! 12%/38%，都登记为 [估]（D14 / D15）；焦点指示用 A1 的 `FocusIndicatorColor = Secondary`。 + +use iced::widget::text::LineHeight; +use iced::widget::{column, container, row, text, text_input}; +use iced::{Alignment, Background, Border, Color, Element, Length, Padding, Pixels}; + +use unlucky_design::color::Role; +use unlucky_design::component_map::{Component, ComponentMetrics}; +use unlucky_design::icons::IconKind; +use unlucky_design::shape::ShapeScale; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; + +use crate::icons; +use crate::theme::{Ui, STROKE_PX}; + +use super::super::interaction::{self, Interaction}; +use super::super::layout; +use super::geometry::{SEARCH_MAX_WIDTH, SEARCH_MIN_WIDTH, SEARCH_VIEW_MIN_HEIGHT}; + +/// 搜索条（收起形态）。 +/// +/// 状态矩阵用 [`SearchBar::state`] 强制；运行期五态由 `Tracker`/`text_input` 的真实事件驱动。 +#[derive(Debug, Clone)] +pub struct SearchBar<'a> { + value: &'a str, + placeholder: &'a str, + trailing: Option, + state: Option, + width: Length, +} + +impl<'a> SearchBar<'a> { + /// 一条收起态搜索条（默认占位文案由页面给，组件内不拼中文）。 + pub fn new(value: &'a str) -> Self { + Self { + value, + placeholder: "", + trailing: Some(IconKind::Filter), + state: None, + width: Length::Fill, + } + } + + /// 占位文案。 + pub fn placeholder(mut self, placeholder: &'a str) -> Self { + self.placeholder = placeholder; + self + } + + /// 强制视觉态（gallery 取证）。 + pub fn state(mut self, state: Interaction) -> Self { + self.state = Some(state); + self + } + + /// 定宽（默认 `Fill`）。 + pub fn width(mut self, width: Length) -> Self { + self.width = width; + self + } +} + +/// 搜索条内的一行内容（bar 与 view 头部共用，保证「展开时头部不跳」——20.6）。 +#[allow(clippy::too_many_arguments)] +fn bar_content<'a, M: Clone + 'a>( + ui: &'a Ui, + value: &'a str, + placeholder: &'a str, + trailing: Option, + state: Interaction, + on_input: impl Fn(String) -> M + 'a, +) -> Element<'a, M> { + // 20.4：可视边 = pad + offset（**求和**，不抄 16） + let bar: ComponentMetrics = Component::Search.metrics().expect("Search 有组件级度量"); + // 20.4：图标**可视边** = pad + offset（M69 不变量）。这里反解出偏移，两侧共用同一个量。 + let icon_edge = bar.pad_start + bar.icon_offset; + let icon_offset = icon_edge - bar.pad_start; + + let ink = if state.is_disabled() { + interaction::disabled_content_over_role(ui, Role::OnSurface, true) + } else { + ui.color(Role::OnSurface) + }; + let subtle = if state.is_disabled() { + ink + } else { + ui.color(Role::OnSurfaceVariant) + }; + + let body_style = ui.style(TypeRole::BodyLarge); + let input = text_input(placeholder, value) + .on_input_maybe(if state.is_disabled() { + None + } else { + Some(on_input) + }) + .size(body_style.size_px) + .line_height(LineHeight::Absolute(Pixels(body_style.line_height_px))) + .font(ui.font_of(body_style)) + .padding(Padding::default()) + .width(Length::Fill) + .style(move |_theme, _status| text_input::Style { + background: Background::Color(Color::TRANSPARENT), + border: Border::default(), + icon: subtle, + placeholder: subtle, + value: ink, + selection: ink, + }); + + // 前置图标：左边 = pad（容器内边距 12）+ offset（4）= 16。两层分别来自令牌的两个字段。 + let leading = container(layout::fixed( + bar.icon, + bar.icon, + icons::view::(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 高、药丸、`SurfaceContainerHigh`、无可见阴影）。 +pub fn search_bar<'a, M: Clone + 'a>( + ui: &'a Ui, + bar: SearchBar<'a>, + on_input: impl Fn(String) -> M + 'a, +) -> Element<'a, M> { + let state = bar.state.unwrap_or(Interaction::Enabled); + let component = Component::Search.spec(); + let height = ui.metrics().search_bar_height; + + let background = if state.is_disabled() { + interaction::disabled_colors(ui, Role::Surface).0 + } else { + let role = Role::SurfaceContainerHigh; + interaction::overlay_color(ui, state, Role::OnSurface, role).unwrap_or(ui.color(role)) + }; + + // 20.5：聚焦指示 = 1px `Secondary`（A1 的 token 存在但 Compose 未消费 → 标 [规格]） + let focus_ring = matches!(state, Interaction::Focused); + let border = Border { + color: if focus_ring { + ui.color(Role::Secondary) + } else { + Color::TRANSPARENT + }, + width: if focus_ring { STROKE_PX } else { 0.0 }, + radius: ui.radius(component.shape, height), + }; + + container(bar_content( + ui, + bar.value, + bar.placeholder, + bar.trailing, + state, + on_input, + )) + .width(bar.width) + // 20.2：max **720**（`SearchBarMaxWidth`）。min 360 无法在 iced 表达（G20），由页面保证列宽。 + .max_width(SEARCH_MAX_WIDTH) + .height(Length::Fixed(height)) + .style(move |_theme| container::Style { + background: Some(Background::Color(background)), + border, + ..container::Style::default() + }) + .into() +} + +/// 展开态搜索面板（docked 形态：桌面 1180 窗口永远用它，`20C` 的结论）。 +/// +/// 形状：头部 56（半径 28）+ 1px `Outline` 分隔 + 结果区（最小 240）。 +#[derive(Debug, Clone)] +pub struct SearchView<'a> { + value: &'a str, + placeholder: &'a str, + empty: &'a str, + results: &'a [&'a str], + width: f32, +} + +impl<'a> SearchView<'a> { + /// 一个展开面板（`empty` = 空结果文案，由页面给 i18n 文本）。 + pub fn new(value: &'a str, results: &'a [&'a str], empty: &'a str) -> Self { + Self { + value, + placeholder: "", + empty, + results, + width: SEARCH_MIN_WIDTH, + } + } + + /// 占位文案。 + pub fn placeholder(mut self, placeholder: &'a str) -> Self { + self.placeholder = placeholder; + self + } +} + +/// 展开态搜索面板。 +pub fn search_view<'a, M: Clone + 'a>( + ui: &'a Ui, + view: SearchView<'a>, + on_input: impl Fn(String) -> M + 'a, +) -> Element<'a, M> { + let panel = ui.color(Role::SurfaceContainerHigh); + let header_height = ui.metrics().search_bar_height; + let body_style = ui.style(TypeRole::BodyMedium); + + // 20.8：头部/结果区分隔是 **`Outline`**（正文分隔线才是 OutlineVariant） + let divider = container(iced::widget::space::horizontal()) + .width(Length::Fill) + .height(Length::Fixed(STROKE_PX)) + .style(move |_theme| container::Style { + background: Some(Background::Color(ui.color(Role::Outline))), + ..container::Style::default() + }); + + let mut rows = column![].width(Length::Fill).spacing(0); + for result in view.results { + rows = rows.push( + container( + text(*result) + .size(body_style.size_px) + .font(ui.font_of(body_style)) + .color(ui.color(Role::OnSurface)), + ) + .width(Length::Fill) + .padding(Padding { + top: ui.space(Space::X2), + right: ui.space(Space::X4), + bottom: ui.space(Space::X2), + left: ui.space(Space::X4), + }), + ); + } + if view.results.is_empty() { + let small = ui.style(TypeRole::BodySmall); + rows = rows.push( + container( + text(view.empty) + .size(small.size_px) + .font(ui.font_of(small)) + .color(ui.color(Role::OnSurfaceVariant)), + ) + .width(Length::Fill) + .padding(Padding { + top: ui.space(Space::X4), + right: ui.space(Space::X4), + bottom: ui.space(Space::X4), + left: ui.space(Space::X4), + }), + ); + } + + let body = container(rows) + .width(Length::Fill) + .height(Length::Fixed(SEARCH_VIEW_MIN_HEIGHT)) + .align_y(Alignment::Start); + + let panel_content = column![ + container(bar_content( + ui, + view.value, + view.placeholder, + Some(IconKind::Close), + Interaction::Enabled, + on_input, + )) + .width(Length::Fill) + .height(Length::Fixed(header_height)), + divider, + body, + ]; + + container(panel_content) + .width(Length::Fixed(view.width)) + .style(move |_theme| container::Style { + background: Some(Background::Color(panel)), + // 20.6：docked 面板 = CornerExtraLarge（28）；bar ⇄ view 半径不变（§20C） + border: Border { + radius: ui.radius_dp(ShapeScale::ExtraLarge), + ..Border::default() + }, + ..container::Style::default() + }) + .into() +} + +#[cfg(test)] +mod tests; diff --git a/crates/app-iced/src/components/inputs/search/tests.rs b/crates/app-iced/src/components/inputs/search/tests.rs new file mode 100644 index 0000000..b635884 --- /dev/null +++ b/crates/app-iced/src/components/inputs/search/tests.rs @@ -0,0 +1,93 @@ +//! search 的单测（从 `search.rs` 拆出：单文件 ≤400 行，AGENTS.md §3-1）。 + +use super::*; +use unlucky_design::color::SchemeFlavor; +use unlucky_design::typography::Platform; + +use crate::theme::Families; + +const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", +}; + +fn ui(flavor: SchemeFlavor) -> Ui { + Ui::with_platform(flavor, Platform::Windows, FAMILIES) +} + +fn leaked(flavor: SchemeFlavor) -> &'static Ui { + Box::leak(Box::new(ui(flavor))) +} + +/// **M69 不变量**：图标可视边 = pad + offset（12 + 4 = 16），且本实现只做加法。 +#[test] +fn icon_edge_is_pad_plus_offset_not_a_literal() { + let bar = Component::Search.metrics().expect("Search 有组件级度量"); + assert_eq!(bar.pad_start, 12.0, "M69 钉住的 pad_start"); + assert_eq!(bar.icon_offset, 4.0, "M69 钉住的 icon_offset"); + assert_eq!(bar.pad_start + bar.icon_offset, 16.0); + assert_eq!(bar.icon, 24.0, "SearchBarTokens 图标 24"); + // 文本从 pad（12）起：图标（16..40）+ gap 8 → 48 是文字的实际起点 + assert_eq!( + bar.pad_start + bar.icon_offset + bar.icon + bar.gap, + 48.0, + "图标槽 + 间距后文字起点 48" + ); +} + +/// 20.1：高 56、圆角 full = 28（药丸）；条高来自 LM，不重复定义。 +#[test] +fn bar_height_and_radius_come_from_tokens() { + let ui = ui(SchemeFlavor::Light); + assert_eq!(ui.metrics().search_bar_height, 56.0); + assert_eq!( + ShapeScale::Full.radius_px(ui.metrics().search_bar_height), + 28.0, + "SearchBarCornerRadius = InputFieldHeight / 2" + ); + assert_eq!(Component::Search.spec().shape, ShapeScale::Full); + // 高程按观感取 L0（无可见阴影） + assert_eq!( + Component::Search.spec().elevation, + unlucky_design::elevation::Elevation::Level0 + ); +} + +/// 20.6 / 20.9：面板头部 56、形状 ExtraLarge(28)、最小高 240、docked 宽 360。 +#[test] +fn docked_panel_geometry() { + let ui = ui(SchemeFlavor::Light); + assert_eq!(ShapeScale::ExtraLarge.dp(), 28.0, "DockedContainerShape"); + assert_eq!( + SEARCH_VIEW_MIN_HEIGHT, 240.0, + "DockedExpandedTableMinHeight" + ); + assert_eq!(SEARCH_MIN_WIDTH, 360.0, "SearchBarMinWidth = docked 面板宽"); + assert_eq!(ui.metrics().search_bar_height, 56.0, "头部与 bar 同高"); +} + +/// bar 与 view 都能构建（含禁用态：输入被摘掉）。 +#[test] +fn both_forms_build() { + for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] { + for state in Interaction::ALL { + let ui = leaked(flavor); + let bar = SearchBar::new("").placeholder("搜索").state(state); + let _: Element<'_, u8> = search_bar(ui, bar, |_| 0_u8); + + let results: &[&str] = &["实例一", "1.21.4"]; + let view = SearchView::new("实例", results, "没有结果").placeholder("搜索"); + let _: Element<'_, u8> = search_view(ui, view, |_| 0_u8); + } + } +} + +/// 空结果也必须给面板内容（20C：不许收回到 bar）。 +#[test] +fn empty_results_still_render_a_panel() { + let ui = leaked(SchemeFlavor::Light); + let empty: &[&str] = &[]; + let view = SearchView::new("xyz", empty, "没有结果"); + let _: Element<'_, u8> = search_view(ui, view, |_| 0_u8); +} diff --git a/crates/app-iced/src/components/inputs/slider.rs b/crates/app-iced/src/components/inputs/slider.rs new file mode 100644 index 0000000..91449a2 --- /dev/null +++ b/crates/app-iced/src/components/inputs/slider.rs @@ -0,0 +1,396 @@ +//! 滑块（`research/12b` §11，A1）：**自绘 `Widget`**——M3 Expressive 的滑块是「竖条」，不是圆点。 +//! +//! ## 参考值（`[源]` = A1，`SliderTokens`） +//! +//! | # | 检查项 | 参考值 | 落点 | +//! |---|---|---|---| +//! | 11.1 | 轨道高 | **16**，圆角 full（= 8） | `TRACK_HEIGHT`（G18） | +//! | 11.2 | handle 形态 | **4 宽 × 44 高**，圆角 full；focus / pressed 收窄到 **2** | `HANDLE_WIDTH` / `HANDLE_HEIGHT` | +//! | 11.3 | 颜色 | 激活轨 `Primary`、未激活轨 `SecondaryContainer`、handle `Primary` | `Role::*` | +//! | 11.4 | handle 与轨道 | 纵向溢出：上下各 **14**（(44−16)/2） | 推导 | +//! | 11.5 | 命中高度 | **48**（`LM.touch_target`；竖条 44 + 上下各 2） | `SliderGeometry::height` | +//! | 11.6 | 禁用 | 激活轨 `OnSurface`@**38%**、未激活 @**12%**、handle @**38%** | `interaction::*` | +//! | — | 离散停靠点 | **4** 圆点 `SecondaryContainer`（`StopIndicatorSize`）；尾随间距 6 | [`Slider::steps`] | +//! +//! ## 为什么必须自绘 +//! +//! iced 内置 `slider` 只能画「轨道 + 圆形/矩形 handle（高度 = 控件高）」， +//! **没有停靠点、没有禁用态、无法强制取证态**；而 §11.2 的 4×44 竖条要求 handle 高（44） +//! 与轨道高（16）分离。所以这里用 `advanced::Widget` 自绘：布局只有「宽 × 48」一个原子， +//! 轨道/激活段/停靠点/竖条全部用 `fill_quad` 画进同一个 bounds——几何因此在像素级可断言。 +//! +//! ## 状态层（[估]，登记 D16） +//! +//! `SliderTokens` **没有**状态层直径（M3 Expressive 去掉了旧版的水滴 halo），hover/pressed 只体现为 +//! handle 宽度与颜色。为了让五态在验收图上可辨且 α 只认令牌，这里把**通用状态层** +//! （`interaction::overlay_color`：hover 8% / focus 10% / pressed 10%）叠在 handle 上， +//! 宽度仍按 A1 收窄——两件事都来自令牌，没有新数值。 +//! +//! ## 拖动 +//! +//! `on_change` 有值就启用拖动与点击跳转；`None` = 禁用（也不吃事件）。 +//! 值由外部持有（受控组件），拖动只 `publish` 新比例：组件不持有业务状态（契约 §2）。 + +use iced::advanced::layout::{self, Layout}; +use iced::advanced::renderer::Quad; +use iced::advanced::widget::{tree, Tree}; +use iced::advanced::{mouse, Clipboard, Shell, Widget}; +use iced::{Background, Border, Color, Element, Event, Length, Rectangle, Size}; + +use unlucky_design::color::Role; + +use crate::theme::Ui; + +use super::super::interaction::{self, Interaction, Tracker}; +use super::geometry::{SliderGeometry, HANDLE_HEIGHT, HANDLE_WIDTH_ACTIVE, STOP_GAP, STOP_SIZE}; + +mod track; + +pub use track::TrackGeometry; + +use track::{fraction_at, quantize, EPSILON}; + +/// 一个滑块（受控：`fraction` 由外部给，变化经 `on_change` 回传）。 +pub struct Slider<'a, M> { + ui: &'a Ui, + fraction: f32, + steps: Option, + on_change: Option M + 'a>>, + forced: Option, +} + +impl<'a, M> Slider<'a, M> { + /// 连续值滑块（0.0 ~= 1.0）。 + pub fn new(ui: &'a Ui, fraction: f32) -> Self { + Self { + ui, + fraction: fraction.clamp(0.0, 1.0), + steps: None, + on_change: None, + forced: None, + } + } + + /// 离散值：`steps` = 分段数（4 → 5 个停靠点 0 / 25 / 50 / 75 / 100%）。 + pub fn steps(mut self, steps: u32) -> Self { + self.steps = Some(steps.max(1)); + self.fraction = quantize(self.fraction, self.steps); + self + } + + /// 值变化回调；不给 = 禁用。 + pub fn on_change(mut self, on_change: impl Fn(f32) -> M + 'a) -> Self { + self.on_change = Some(Box::new(on_change)); + self + } + + /// 强制视觉态（gallery 状态矩阵取证）。 + pub fn state(mut self, state: Interaction) -> Self { + self.forced = Some(state); + self + } + + /// 当前比例（量化后）。 + fn value(&self) -> f32 { + quantize(self.fraction, self.steps) + } + + /// 禁用与否：没有回调就是禁用（与按钮 `on_press: Option` 同一口径）。 + 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 (active_color, inactive_color, handle_color, handle_width) = if disabled { + ( + interaction::disabled_content_over_role(ui, Role::OnSurface, false), + interaction::disabled_colors(ui, Role::Surface).0, + interaction::disabled_content_over_role(ui, Role::OnSurface, false), + geometry.handle, + ) + } else { + // 状态层只叠在 handle 上（D16）：α 全部来自 interaction（hover 8 / focus 10 / pressed 10） + let handle_color = + interaction::overlay_color(ui, state, Role::OnSurface, Role::Primary) + .unwrap_or_else(|| ui.color(Role::Primary)); + let handle_width = match state { + Interaction::Focused | Interaction::Pressed => HANDLE_WIDTH_ACTIVE, + _ => geometry.handle, + }; + ( + ui.color(Role::Primary), + ui.color(Role::SecondaryContainer), + handle_color, + handle_width, + ) + }; + + let centre_y = bounds.y + bounds.height / 2.0; + let track_x = bounds.x; + let track_w = bounds.width; + let track = TrackGeometry::of(bounds, self.value()); + let centre_x = track.handle_centre(); + let track_rect = |x: f32, width: f32| Rectangle { + x, + y: centre_y - geometry.track / 2.0, + width: width.max(0.0), + height: geometry.track, + }; + + // 离散停靠点：A1 的 `StopIndicatorColor = SecondaryContainer` 与未激活轨**同色**， + // 所以停靠点只有在「未激活轨在它两侧留出空隙」时才读得出来（官方也是这么画的： + // `StopIndicatorSize = 4` + `StopIndicatorTrailingSpace = 6`）。空隙两侧各留半个点 + 6。 + // **不含两端**：0% 与 100% 上不画停靠点（那是轨道自己的圆角端，官方也不画） + let stops: Vec = 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/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/disabled.rs b/crates/app-iced/src/components/interaction/disabled.rs new file mode 100644 index 0000000..4e033c5 --- /dev/null +++ b/crates/app-iced/src/components/interaction/disabled.rs @@ -0,0 +1,305 @@ +//! 禁用态的颜色口径：**两个族、两套 α**（M86 收口）。 +//! +//! ## 为什么不是「一个 12%」 +//! +//! 官方禁用 α 分两类（A 级：`material3-android-1.4.0.aar` 的字节码 ``）： +//! +//! | 族 | α | 官方 token | 消费者 | +//! |---|---|---|---| +//! | **按钮容器** | **0.10** | `*ButtonTokens.DisabledContainerOpacity`（`Filled` / `Outlined` / `Text` / `Elevated` / `Tonal` / `Baseline`） | `buttons::assemble` | +//! | **面状控件**容器与描边 | **0.12** | `AssistChipTokens.FlatDisabledOutlineOpacity`、`FilterChipTokens.FlatDisabled(SelectedContainer/UnselectedOutline)Opacity`、`SliderTokens.DisabledInactiveTrackOpacity`、`SwitchTokens.DisabledTrackOpacity` | chip / switch / slider / TextField 描边 | +//! | 内容（两族共用） | 0.38 | `Disabled{Icon,LabelText,Input}Opacity` | 全部 | +//! +//! 历史上这里只有一个 12% 常量供两族共用：**按钮那半边一直错、chip/slider/switch 那半边一直对**。 +//! 现在按族分开两个入口——取错入口的后果是「差 1/255」，肉眼看不见，只有像素 probe 会红， +//! 所以入口**必须按名字就能选对**。 +//! +//! ⚠️ TextField 的 **Filled 容器**不在这两族里：官方 +//! `FilledTextFieldTokens.FieldDisabledContainerOpacity = 0.04f`，我们仍在用面状族的值 +//! （既有 D10 偏离，未在本轮收口）。`inputs::field` 走 [`disabled_colors`] 的口径，行为未变。 +//! +//! ⚠️ **filled-tonal 是另一条已知偏离**：官方 +//! `FilledTonalButtonTokens.DisabledContainerOpacity = 0.12f`（`javap -p -constants` 可见它是个 +//! **编译期常量**，被内联进 `getDefaultFilledTonalButtonColors` 的 `ldc_w 0.12f`，所以调用点是常量、 +//! `getDisabledContainerOpacity()` 不会被调用）；而本模块的 `disabled_button_*` **不区分变体**， +//! tonal 与 filled 共用 0.10 ⇒ tonal 实际画 10%。这不是对齐、是登记过的偏离；要修得让入口知道变体， +//! 本轮（M86）不做。 + +use iced::Color; + +use unlucky_design::color::state::{ + DISABLED_CONTAINER_ALPHA, DISABLED_CONTENT_ALPHA, DISABLED_SURFACE_ALPHA, +}; +use unlucky_design::color::{Role, Scheme}; + +use crate::theme::{to_iced, Ui}; + +/// 禁用态内容色（**按角色、按有没有容器**求值）——A1 口径的入口（**面状控件族**的底）。 +/// +/// - `role`：由变体决定（Filled/Outlined/Text/Elevated = `OnSurfaceVariant`； +/// FilledTonal 与三式 IconButton = `OnSurface`，见 `Variant::disabled_content`）； +/// - `on_container = true`：叠在**面状控件族的 12% 容器**（[`DISABLED_SURFACE_ALPHA`]）上 +/// （Filled TextField / 有容器控件在 12% 底上求内容时）； +/// `false`：直接叠在 **surface** 上（Text / Outlined / standard IconButton / 描边类控件的内容）。 +/// +/// **按钮家族不要用这个函数**（按钮容器是 10%）：走 [`disabled_button_content`]。 +/// +/// 之前这里写死 `OnSurfaceVariant` 且只有一个「底」，导致 FilledTonal 与 IconButton 两族偏浅 +/// 15/255（视觉 r3 用像素量的）。 +pub fn disabled_content_over_role(ui: &Ui, role: Role, on_container: bool) -> Color { + let scheme = Scheme::baseline(ui.flavor()); + disabled_content_with_alpha(&scheme, role, on_container, DISABLED_SURFACE_ALPHA) +} + +/// 禁用态内容色——**按钮家族**（`on_container`：是否叠在本族 10% 容器上）。 +/// +/// 与 [`disabled_content_over_role`] 的差别只有「底」的 α：按钮 10%、面状控件 12%。 +/// 两个入口分开是 M86 的结论：合成一个数会让一族永远差 1/255，肉眼看不见、只有 probe 会红。 +pub fn disabled_button_content(ui: &Ui, role: Role, on_container: bool) -> Color { + let scheme = Scheme::baseline(ui.flavor()); + disabled_content_with_alpha(&scheme, role, on_container, DISABLED_CONTAINER_ALPHA) +} + +/// 两个族共用的内容色求值（「底」的 α 由调用方给）。 +fn disabled_content_with_alpha( + scheme: &Scheme, + role: Role, + on_container: bool, + container_alpha: f32, +) -> Color { + let base = if on_container { + scheme + .get(Role::OnSurface) + .with_alpha(container_alpha) + .over(scheme.get(Role::Surface)) + } else { + scheme.get(Role::Surface) + }; + + to_iced( + scheme + .get(role) + .with_alpha(DISABLED_CONTENT_ALPHA) + .over(base), + ) +} + +/// 禁用态的一对颜色 `(容器, 内容)`——**面状控件族**（12% 容器/描边）。 +/// +/// ⚠️ 这个名字是历史遗留（当年只有它一个），**语义是「面状控件族」**： +/// - chip 容器与描边（`AssistChipTokens.FlatDisabledOutlineOpacity = 0.12f` 等） +/// - switch 轨道（`SwitchTokens.DisabledTrackOpacity = 0.12f`） +/// - slider 未激活轨（`SliderTokens.DisabledInactiveTrackOpacity = 0.12f`） +/// - TextField 禁用描边（Filled 容器的 4% 是另一条 D10 偏离，不在这里收口） +/// +/// **按钮家族用 [`disabled_button_colors`]**（0.10，`*ButtonTokens.DisabledContainerOpacity = 0.1f`）。 +/// +/// `ui` 不暴露 [`Scheme`]，这里按同一个 flavor 求一次基线方案——调的是 +/// `unlucky_design` 的**同一个**函数与同一套角色，不是第二份令牌。 +/// +/// 顺序必须「先容器后内容」：Compose 也是这么画的，先叠容器再叠 label， +/// 所以内容叠的角色是容器实色而不是底下的 surface。 +pub fn disabled_colors(ui: &Ui, surface: Role) -> (Color, Color) { + disabled_colors_with_alpha(ui, surface, DISABLED_SURFACE_ALPHA) +} + +/// 禁用态的一对颜色 `(容器, 内容)`——**按钮家族**（10% 容器）。 +/// +/// - 容器 = `OnSurface` @ 10%（[`DISABLED_CONTAINER_ALPHA`]）叠在 `surface` 上； +/// - 内容 = **默认** `OnSurfaceVariant` @ 38%；按变体的取值走 [`disabled_button_content`]。 +/// +/// 除了按钮家族，**没有别的消费者**：面状控件（chip / slider 轨道 / switch 轨道 / 描边）走 +/// [`disabled_colors`] 的 12%。 +pub fn disabled_button_colors(ui: &Ui, surface: Role) -> (Color, Color) { + disabled_colors_with_alpha(ui, surface, DISABLED_CONTAINER_ALPHA) +} + +/// 两个族共用的求值：容器 = `OnSurface` @ `container_alpha` 叠在 `surface` 上，内容 = 38% 叠在容器上。 +fn disabled_colors_with_alpha(ui: &Ui, surface: Role, container_alpha: f32) -> (Color, Color) { + let scheme = Scheme::baseline(ui.flavor()); + let base = scheme.get(surface); + let container = scheme + .get(Role::OnSurface) + .with_alpha(container_alpha) + .over(base); + // 这里是**默认口径**（OnSurfaceVariant）；按变体取值请走 [`disabled_content_over_role`] + // ——FilledTonal 与三式 IconButton 的禁用内容是 `OnSurface`（A1）。 + let content = scheme + .get(Role::OnSurfaceVariant) + .with_alpha(DISABLED_CONTENT_ALPHA) + .over(container); + + (to_iced(container), to_iced(content)) +} + +#[cfg(test)] +mod tests { + use super::*; + use unlucky_design::color::SchemeFlavor; + use unlucky_design::typography::Platform; + + use crate::theme::Families; + + const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", + }; + + fn ui(flavor: SchemeFlavor) -> Ui { + Ui::with_platform(flavor, Platform::Windows, FAMILIES) + } + + /// 两族的 α 必须都钉住（只钉一条，另一族被合并时会静默错 1/255）。 + #[test] + fn both_disabled_alpha_classes_are_pinned_to_the_tokens() { + // 绑定成局部变量再过断言：直接比两个常量会被 clippy 判成「常量断言」。 + let button_alpha = DISABLED_CONTAINER_ALPHA; + let surface_alpha = DISABLED_SURFACE_ALPHA; + let content_alpha = DISABLED_CONTENT_ALPHA; + // 按钮容器：官方 *ButtonTokens.DisabledContainerOpacity = 0.1f + assert!( + (button_alpha - 0.10).abs() < f32::EPSILON, + "按钮禁用容器 α 必须是 0.10（官方 DisabledContainerOpacity）；\ + 0.12 是面状控件那一类，别混用" + ); + // 面状控件：chip 描边 / slider 未激活轨 / switch 轨道 = 0.12f + assert!( + (surface_alpha - 0.12).abs() < f32::EPSILON, + "面状控件禁用 α 必须是 0.12（官方 FlatDisabledOutlineOpacity / \ + DisabledInactiveTrackOpacity / DisabledTrackOpacity）" + ); + assert!((content_alpha - 0.38).abs() < f32::EPSILON); + assert!( + surface_alpha > button_alpha, + "两族必须可区分：面状控件比按钮容器更实（{surface_alpha} > {button_alpha}）" + ); + } + + /// **面状控件族**的那一对颜色 = 0.12 预混合（chip / switch / slider / TextField 描边）。 + /// + /// ⚠️ 期望值**写死 0.12 / 0.38**，不从 `DISABLED_SURFACE_ALPHA` 取： + /// 从被测常量求期望是**自指断言**——常量一改，expected 跟着改，永远相等（复审 r1 P2-1 实测： + /// 把 `DISABLED_SURFACE_ALPHA` 改成 0.10，旧版这条照样绿）。现在常量改坏必红。 + #[test] + fn surface_family_disabled_colors_are_the_12_percent_class() { + const EXPECTED_SURFACE_ALPHA: f32 = 0.12; + const EXPECTED_CONTENT_ALPHA: f32 = 0.38; + let actual_alpha = DISABLED_SURFACE_ALPHA; + assert_eq!( + actual_alpha, EXPECTED_SURFACE_ALPHA, + "面状控件族 α 必须是官方 0.12f；改常量会让下面每一条合成色断言同时红" + ); + + for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] { + let ui = ui(flavor); + let scheme = Scheme::baseline(flavor); + let base = scheme.get(Role::Surface); + let expected_container = scheme + .get(Role::OnSurface) + .with_alpha(EXPECTED_SURFACE_ALPHA) + .over(base); + + let (surface, surface_content) = disabled_colors(&ui, Role::Surface); + assert_eq!( + surface, + to_iced(expected_container), + "{flavor:?}：面状控件容器 = on-surface@12% 叠表面（期望值硬编码，不取自常量）" + ); + assert_eq!( + surface_content, + to_iced( + scheme + .get(Role::OnSurfaceVariant) + .with_alpha(EXPECTED_CONTENT_ALPHA) + .over(expected_container) + ), + "{flavor:?}：面状控件内容仍是 38%，只是叠的底不同" + ); + assert_ne!(surface, ui.color(Role::Surface), "12% 叠上去必须能看出来"); + assert_eq!(surface.a, 1.0, "禁用容器也是实色（CPU/GPU 一致）"); + assert_eq!(surface_content.a, 1.0, "禁用内容也是实色"); + // 内容叠在容器上 vs 叠在表面上，是两回事（probe 量的是前者） + assert_ne!( + surface_content, + to_iced( + scheme + .get(Role::OnSurfaceVariant) + .with_alpha(EXPECTED_CONTENT_ALPHA) + .over(base) + ), + "{flavor:?}：内容必须叠在容器上" + ); + // 跨族对照：面状族的合成色必须与按钮族不同（两族一旦合流，这条红） + let (button, _) = disabled_button_colors(&ui, Role::Surface); + assert_ne!( + surface, button, + "{flavor:?}：面状族 12% 与按钮族 10% 必须落在不同像素值上" + ); + } + } + + /// **按钮家族**的那一对颜色 = 0.10 预混合，且与面状控件族**必须落在不同像素值上**。 + /// + /// 期望值同样写死（0.10 / 0.38），理由见上一条：自指断言抓不住常量被改坏。 + #[test] + fn button_family_disabled_colors_are_the_10_percent_class() { + const EXPECTED_BUTTON_ALPHA: f32 = 0.10; + const EXPECTED_CONTENT_ALPHA: f32 = 0.38; + let actual_alpha = DISABLED_CONTAINER_ALPHA; + assert_eq!( + actual_alpha, EXPECTED_BUTTON_ALPHA, + "按钮族 α 必须是官方 0.1f（*ButtonTokens.DisabledContainerOpacity）" + ); + + for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] { + let ui = ui(flavor); + let scheme = Scheme::baseline(flavor); + let base = scheme.get(Role::Surface); + let expected_container = scheme + .get(Role::OnSurface) + .with_alpha(EXPECTED_BUTTON_ALPHA) + .over(base); + + let (button, button_content) = disabled_button_colors(&ui, Role::Surface); + assert_eq!( + button, + to_iced(expected_container), + "{flavor:?}：按钮容器 = on-surface@10% 叠表面（官方 DisabledContainerOpacity = 0.1f）" + ); + assert_eq!( + button_content, + to_iced( + scheme + .get(Role::OnSurfaceVariant) + .with_alpha(EXPECTED_CONTENT_ALPHA) + .over(expected_container) + ), + ); + + let (surface, _) = disabled_colors(&ui, Role::Surface); + assert_ne!( + button, surface, + "{flavor:?}：10% 与 12% 必须落在不同像素值上（合成一个数就是这次要防的回归）" + ); + + // 内容色同理：按钮 38% 叠 10% 底 ≠ 面状 38% 叠 12% 底 + assert_ne!( + button_content, + disabled_content_over_role(&ui, Role::OnSurfaceVariant, true), + "{flavor:?}：两族的「有容器」内容色不能同源" + ); + assert_eq!( + disabled_button_content(&ui, Role::OnSurfaceVariant, true), + button_content, + "{flavor:?}：按钮内容入口必须与按钮颜色入口同源" + ); + // 无容器时两族完全一致（都叠 surface）——差异只在「有容器」那一支 + assert_eq!( + disabled_button_content(&ui, Role::OnSurfaceVariant, false), + disabled_content_over_role(&ui, Role::OnSurfaceVariant, false), + "{flavor:?}：没有容器时不该有族差异" + ); + } + } +} diff --git a/crates/app-iced/src/components/interaction/mod.rs b/crates/app-iced/src/components/interaction/mod.rs new file mode 100644 index 0000000..8fd640a --- /dev/null +++ b/crates/app-iced/src/components/interaction/mod.rs @@ -0,0 +1,239 @@ +//! 交互状态层：hover / focus / pressed / disabled 的**唯一实现点**（D39 §3）。 +//! +//! ## 为什么必须只有一处 +//! +//! M3 的状态层不是「另一种灰」，而是**内容色自身 + 固定 alpha** 叠在容器色上 +//! （`unlucky_design::color::state` 的文档）。五个家族各写一遍 +//! `if hovered { 0.08 }`，第一周就会出现 0.08 / 0.1 / 0.12 三种 hover—— +//! 这一层存在的意义就是让「组件里出现 α 字面量」变成不可能： +//! +//! | 态 | α | 令牌来源 | +//! |---|---|---| +//! | hover | 0.08 | [`StateLayer::Hover`] | +//! | focus | 0.10 | [`StateLayer::Focus`] | +//! | pressed | 0.10 | [`StateLayer::Pressed`] | +//! | dragged | 0.16 | [`StateLayer::Dragged`]（按钮家族不用，列表拖拽用） | +//! | disabled 容器（**按钮家族**） | 0.10 | [`DISABLED_CONTAINER_ALPHA`]（按钮 `*ButtonTokens.DisabledContainerOpacity`） | +//! | disabled 容器/描边（**面状控件族**） | 0.12 | [`DISABLED_SURFACE_ALPHA`]（chip / slider 轨道 / switch 轨道 / TextField 禁用描边） | +//! | disabled 内容 | 0.38 | [`DISABLED_CONTENT_ALPHA`] | +//! +//! ## ⚠️ 禁用 α 有**两类**（M86 收口，别再合成一个数） +//! +//! 官方禁用 α 从来不是「一个 12%」： +//! +//! - **按钮容器 0.10**：`BaselineButtonTokens` / `FilledButtonTokens` / `OutlinedButtonTokens` / +//! `TextButtonTokens` / `ElevatedButtonTokens` / `TonalButtonTokens` 的 `DisabledContainerOpacity` +//! = `0.1f`（AAR 字节码 `` 里的 `ldc 0.1f`）； +//! - **面状控件 0.12**：`AssistChipTokens.FlatDisabledOutlineOpacity` / `FilterChipTokens. +//! FlatDisabledSelectedContainerOpacity` / `SliderTokens.DisabledInactiveTrackOpacity` / +//! `SwitchTokens.DisabledTrackOpacity` 都是 `0.12f`。 +//! +//! 本模块过去只有一个 12% 常量供两条线共用：**按钮那半边一直错、chip/slider/switch 那半边一直对**。 +//! 现在按族分两个入口，谁也别再拿一个数服务两族： +//! +//! | 入口 | α | 谁用 | +//! |---|---|---| +//! | [`disabled_button_colors`] / [`disabled_button_content`] | 0.10 | **只有按钮家族**（`buttons::assemble`） | +//! | [`disabled_colors`] / [`disabled_content_over_role`] | 0.12 | **面状控件族**：chip 容器与描边、switch 轨道、slider 未激活轨、TextField 禁用描边（`disabled_colors` 这个名字是历史遗留，**语义是面状控件族**） | +//! +//! 上表右列是**唯一**允许的取值口；左列只是给人看的，代码里一个数字都不许出现 +//! （`components::gate` 会扫）。 +//! +//! ## 两个消费形态 +//! +//! 1. **iced `button` 系**（本 mission 的按钮家族）：拿 [`Interaction`] 直接配 [`overlay_color`]； +//! 2. **自定义 `Widget`**（后续若需要自绘轨道/滑块）：用 [`Tracker`] 把事件折成五态， +//! `update()` 的返回值告诉你「要不要重绘」，`state()` 给出当前态。 +//! +//! ## 与 `Ui::state_over` 的关系 +//! +//! 颜色一律经 [`crate::theme::Ui::state_over`] 求值（它返回**不透明**结果，所以 GPU/CPU 两档 +//! 逐像素一致，D27）。本模块只做「哪一态叠哪一层」的映射，不做任何颜色算术。 + +use iced::widget::button; +use iced::Color; + +use unlucky_design::color::{Role, StateLayer}; + +use crate::theme::Ui; + +mod tracker; + +// 本 mission 没有自绘控件，所以这条再导出在 crate 内暂时无人使用； +// 它是给四条家族线（Slider / Switch 轨道要自绘）的公共入口，路径与拆分前一致。 +#[allow(unused_imports)] +pub use tracker::Tracker; + +// 本模块会被四条家族线各扩一次：加东西前先看行数余额（单文件 ≤400，AGENTS.md §3-1）。 +// `mod.rs` 只装「五态 + 颜色映射」这类纯函数；事件 → 态的**状态机在 [`tracker`]**， +// 需要新的状态机就加到那边，别把本文件再撑到红线上。 + +/// 一个控件的视觉态（五态，M3 的完整集合）。 +/// +/// `Enabled` 是**静息态**（不叠状态层）；`Focused` / `Pressed` 在 M3 里 α 相同（都 10%）， +/// 所以两者在图上会一模一样——这是规范，不是漏画（12b §1.8 判据只要求 α 对得上）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +pub enum Interaction { + /// 静息：可交互，不叠状态层。 + Enabled, + /// 悬停：叠 8%。 + Hovered, + /// 键盘焦点：叠 10%。 + Focused, + /// 按下：叠 10%。 + Pressed, + /// 禁用：按钮容器 10% / 面状控件 12% / 内容 38%，**不叠状态层**。 + Disabled, +} + +impl Interaction { + /// 五态全序（gallery 的状态矩阵按这个次序出图）。 + pub const ALL: [Interaction; 5] = [ + Interaction::Enabled, + Interaction::Hovered, + Interaction::Pressed, + Interaction::Focused, + Interaction::Disabled, + ]; + + /// 稳定名字（截图文件名 / 图例 / 测试失败信息用）。 + pub const fn name(self) -> &'static str { + match self { + Interaction::Enabled => "enabled", + Interaction::Hovered => "hovered", + Interaction::Focused => "focused", + Interaction::Pressed => "pressed", + Interaction::Disabled => "disabled", + } + } + + /// 是否禁用（禁用不是「第六态」，它要不要画容器由组件决定）。 + pub const fn is_disabled(self) -> bool { + matches!(self, Interaction::Disabled) + } + + /// 该态要叠的状态层；`None` = 不叠（静息与禁用）。 + pub const fn layer(self) -> Option { + 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 disabled; + +pub use disabled::{ + disabled_button_colors, disabled_button_content, disabled_colors, disabled_content_over_role, +}; + +#[cfg(test)] +mod tests { + use super::*; + use unlucky_design::color::SchemeFlavor; + use unlucky_design::typography::Platform; + + use crate::theme::Families; + + const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", + }; + + fn ui(flavor: SchemeFlavor) -> Ui { + Ui::with_platform(flavor, Platform::Windows, FAMILIES) + } + + /// 契约 §3 的状态层 α 全表：**钉住令牌值**（改令牌会让这条红，改组件抓不到）。 + /// + /// 禁用态的两族 α（按钮 0.10 / 面状控件 0.12）在 [`super::disabled`] 的测试里， + /// 那边还负责「两族不能同源」的判据。 + #[test] + fn state_layer_alphas_are_the_contract_values() { + assert!((StateLayer::Hover.alpha() - 0.08).abs() < f32::EPSILON); + assert!((StateLayer::Focus.alpha() - 0.10).abs() < f32::EPSILON); + assert!((StateLayer::Pressed.alpha() - 0.10).abs() < f32::EPSILON); + assert!((StateLayer::Dragged.alpha() - 0.16).abs() < f32::EPSILON); + } + + #[test] + fn five_states_map_onto_four_layers() { + assert_eq!(Interaction::ALL.len(), 5); + assert_eq!(Interaction::Enabled.layer(), None); + assert_eq!(Interaction::Disabled.layer(), None); + assert_eq!(Interaction::Hovered.layer(), Some(StateLayer::Hover)); + assert_eq!(Interaction::Focused.layer(), Some(StateLayer::Focus)); + assert_eq!(Interaction::Pressed.layer(), Some(StateLayer::Pressed)); + // focus 与 pressed 同 α（M3 口径）——图上一样是**对的** + assert_eq!( + Interaction::Focused.layer().map(StateLayer::alpha), + Interaction::Pressed.layer().map(StateLayer::alpha) + ); + } + + #[test] + fn overlay_color_is_the_token_blend_not_local_math() { + for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] { + let ui = ui(flavor); + for (state, layer) in [ + (Interaction::Hovered, StateLayer::Hover), + (Interaction::Focused, StateLayer::Focus), + (Interaction::Pressed, StateLayer::Pressed), + ] { + assert_eq!( + overlay_color(&ui, state, Role::OnPrimary, Role::Primary), + Some(ui.state_over(layer, Role::OnPrimary, Role::Primary)), + "{flavor:?}/{state:?} 必须逐位等于令牌求值结果" + ); + assert!( + overlay_color(&ui, state, Role::OnSurface, Role::Surface).is_some(), + "可交互态必须给颜色" + ); + } + assert_eq!( + overlay_color(&ui, Interaction::Enabled, Role::OnSurface, Role::Surface), + None + ); + assert_eq!( + overlay_color(&ui, Interaction::Disabled, Role::OnSurface, Role::Surface), + None, + "禁用态不叠状态层（它换的是容器/内容色）" + ); + } + } + + #[test] + fn hover_is_weaker_than_pressed_on_the_same_container() { + let ui = ui(SchemeFlavor::Light); + let hover = overlay_color(&ui, Interaction::Hovered, Role::OnSurface, Role::Surface) + .expect("hover 有颜色"); + let pressed = overlay_color(&ui, Interaction::Pressed, Role::OnSurface, Role::Surface) + .expect("pressed 有颜色"); + assert_ne!(hover, pressed, "8% 与 10% 必须能区分"); + assert_eq!(hover.a, 1.0, "结果必须不透明（GPU/CPU 逐像素一致）"); + } +} diff --git a/crates/app-iced/src/components/interaction/tracker.rs b/crates/app-iced/src/components/interaction/tracker.rs new file mode 100644 index 0000000..8139171 --- /dev/null +++ b/crates/app-iced/src/components/interaction/tracker.rs @@ -0,0 +1,155 @@ +//! 自定义 `Widget` 的状态机（[`Tracker`]）：把 iced 事件折成 [`Interaction`] 五态。 +//! +//! 与 [`super`] 的分工：`super` 只有「态 → 颜色」的纯映射；**事件 → 态**在这里。 +//! 本 mission 的按钮家族全走 iced 的 `button`（自带四态），所以 `Tracker` 目前只有单测在用—— +//! 它给四个后续家族里**要自绘**的控件（Slider 轨道 / Switch 轨道 / 进度条）准备。 +//! +//! 加东西前先看行数余额（单文件 ≤400，AGENTS.md §3-1）。 + +use iced::Event; + +use super::Interaction; + +/// 自定义 `Widget` 的状态机：把 iced 事件折成 [`Interaction`]。 +/// +/// 这是 D39 §3 说的「状态机的公共部分」。用法（自定义 Widget 的 `update` 里）： +/// +/// ```ignore +/// if self.tracker.event(event, cursor.is_over(layout.bounds())) { +/// shell.request_redraw(); // 只有真变了才重绘 +/// } +/// let style = style_of(self.tracker.state()); +/// ``` +#[allow(dead_code)] +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub struct Tracker { + enabled: bool, + hovered: bool, + focused: bool, + pressed: bool, +} + +#[allow(dead_code)] +impl Tracker { + /// 新建；`enabled` 由组件自己决定（例如 `on_press.is_some()`）。 + pub fn new(enabled: bool) -> Self { + Self { + enabled, + ..Self::default() + } + } + + /// 启用/禁用热切换（禁用时清掉悬停与按下：禁用元素不该留着 hover 高亮）。 + pub fn set_enabled(&mut self, enabled: bool) -> bool { + let changed = self.enabled != enabled; + self.enabled = enabled; + if !enabled { + self.hovered = false; + self.pressed = false; + self.focused = false; + } + changed + } + + /// 键盘焦点（由 `operation`/`shell` 侧的聚焦消息驱动）。 + pub fn set_focused(&mut self, focused: bool) -> bool { + let next = focused && self.enabled; + let changed = self.focused != next; + self.focused = next; + changed + } + + /// 折进一个事件；返回「视觉态变了，要重绘吗」。 + /// + /// `over` = 指针是否在控件 bounds 内（`Cursor::is_over(bounds)` 的结果，由调用方算—— + /// 这样本函数不依赖 `Layout`，可以在单测里直接喂）。 + pub fn event(&mut self, event: &Event, over: bool) -> bool { + if !self.enabled { + return false; + } + + let before = self.state(); + match event { + Event::Mouse(iced::mouse::Event::CursorMoved { .. }) => self.hovered = over, + Event::Mouse(iced::mouse::Event::CursorLeft) => { + self.hovered = false; + self.pressed = false; + } + Event::Mouse(iced::mouse::Event::ButtonPressed(iced::mouse::Button::Left)) => { + self.pressed = over; + } + Event::Mouse(iced::mouse::Event::ButtonReleased(iced::mouse::Button::Left)) => { + self.pressed = false; + } + _ => {} + } + self.state() != before + } + + /// 当前态（优先级：按下 > 焦点 > 悬停 > 静息；禁用最高）。 + pub const fn state(&self) -> Interaction { + if !self.enabled { + Interaction::Disabled + } else if self.pressed { + Interaction::Pressed + } else if self.focused { + Interaction::Focused + } else if self.hovered { + Interaction::Hovered + } else { + Interaction::Enabled + } + } +} + +/// `Tracker` 的行为用例（自绘控件用，与颜色无关）。 +#[cfg(test)] +mod tests { + use super::*; + use iced::Event; + + fn moved() -> Event { + Event::Mouse(iced::mouse::Event::CursorMoved { + position: iced::Point::ORIGIN, + }) + } + + #[test] + fn tracker_folds_events_into_the_five_states() { + let mut tracker = Tracker::new(true); + assert_eq!(tracker.state(), Interaction::Enabled); + + assert!(tracker.event(&moved(), true), "首次悬停要报变化"); + assert_eq!(tracker.state(), Interaction::Hovered); + assert!(!tracker.event(&moved(), true), "重复悬停不该再报变化"); + + let press = Event::Mouse(iced::mouse::Event::ButtonPressed(iced::mouse::Button::Left)); + assert!(tracker.event(&press, true)); + assert_eq!(tracker.state(), Interaction::Pressed); + + let release = Event::Mouse(iced::mouse::Event::ButtonReleased( + iced::mouse::Button::Left, + )); + assert!(tracker.event(&release, true)); + assert_eq!(tracker.state(), Interaction::Hovered); + + assert!(tracker.set_focused(true)); + assert_eq!(tracker.state(), Interaction::Focused, "焦点态优先于悬停"); + + let left = Event::Mouse(iced::mouse::Event::CursorLeft); + tracker.event(&left, false); + assert_eq!(tracker.state(), Interaction::Focused, "鼠标离开不影响焦点"); + } + + #[test] + fn disabled_tracker_swallows_everything() { + let mut tracker = Tracker::new(true); + assert!(tracker.set_enabled(false)); + assert_eq!(tracker.state(), Interaction::Disabled); + + let press = Event::Mouse(iced::mouse::Event::ButtonPressed(iced::mouse::Button::Left)); + assert!(!tracker.event(&press, true), "禁用态不响应事件"); + assert_eq!(tracker.state(), Interaction::Disabled); + assert!(!tracker.set_focused(true), "禁用态拿不到焦点"); + } +} diff --git a/crates/app-iced/src/components/layout.rs b/crates/app-iced/src/components/layout.rs new file mode 100644 index 0000000..998a838 --- /dev/null +++ b/crates/app-iced/src/components/layout.rs @@ -0,0 +1,129 @@ +//! 布局陷阱的两个固定解法（D39 §4）：**要精确尺寸就调这里，别手写**。 +//! +//! ## 陷阱 Q8：`center_x(Length::Fill)` 会把已设的 `.width()` 覆盖成 Fill +//! +//! iced 的 `container::center_x/center_y/center` 不只是「对齐」——它们**同时**把容器该轴的 +//! `Length` 改成 `Fill`（源码里 `self.width = Length::Fill`）。于是 +//! `.width(56).center_x(Length::Fill)` 最终是 `Fill`，56 被父级宽度吃掉： +//! M68 的导航药丸因此从 **56×32 变成 88×32**（父级是 88 宽的轨），图上看着「横贯全轨」， +//! 而单元测试测的 `indicator_size()` 返回值一直是 56×32 —— **函数对、图错**。 +//! +//! 正确写法是二选一： +//! +//! - 尺寸留在**自己**身上，居中交给**父级**（`row/column` 的 `align_x`）——`shell/nav.rs` 的做法； +//! - 或者用 [`centered_fixed`]：容器写死宽高，**用 `align_x/align_y` 居中**（它们只改对齐， +//! 不改 `Length`）。 +//! +//! ## 陷阱 Q9：`Button` 给内容 Fill 约束，`svg().width(24)` 会被忽略 +//! +//! `button` 在 layout 里把「内容可用区」作为约束交给子元素，`svg` 拿到的是 Fill， +//! usvg 于是按 `Contain` 撑满内区：**字形渲染成 46px、线宽从 1.5 变 2.9**（M68 视觉复审 P2-2）， +//! 比导航图标重一倍。反过来「把 `.width(24)` 设在 button 上」也不行——那会缩掉点击区。 +//! +//! 正确写法：**在中间插一层固定尺寸容器**——[`fixed`]： +//! +//! ```text +//! let icon = layout::fixed(24.0, 24.0, icons::view(kind, color)); // 字形 24×24 +//! button(icon).width(46).height(48) // 命中区仍是 46×48 +//! ``` +//! +//! ## 为什么还要 [`inset`] +//! +//! 「左右缩进 16 的一条线」「内容四周留 24」这类**只改内边距、不改尺寸**的语义， +//! 写 `.padding(Padding::from([...]))` 时数组顺序（上右下左）极易写反；封装一次， +//! 全组件线只写一次顺序。 +//! +//! ## 自检 +//! +//! `components::gate` 会扫 `src/components/**`：出现 `center_x(` / `center_y(` / `.center(` +//! 即判红（这条门禁就是 Q8 的回归测试）；图标一律经 [`fixed`] / [`centered_fixed`] 包一层。 + +use iced::widget::container; +use iced::{Alignment, Element, Length, Padding}; + +/// 固定尺寸的盒子：宽高**只由参数决定**，子元素贴左上（对齐交给子元素自己或父级）。 +/// +/// Q9 的解法：`svg` 放进 24×24 的盒子，它拿到的约束就是 24，`Contain` 无从撑满。 +pub fn fixed<'a, M: 'a>( + width: f32, + height: f32, + content: impl Into>, +) -> Element<'a, M> { + 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..ac7d52c --- /dev/null +++ b/crates/app-iced/src/components/mod.rs @@ -0,0 +1,58 @@ +//! 组件库（D39 定案）：五家族并行，**目录所有权切分**，接口见 +//! `DevDocs/SubAgentsTalk/app-iced-组件库契约.md`。 +//! +//! ## 模块地图与归属（谁能写哪里） +//! +//! ```text +//! components/ +//! mod.rs ← 本文件（COMPBASE 独占）：只声明子模块，不含实现 +//! interaction.rs ← COMPBASE 独占：hover/focus/pressed/disabled 的唯一实现 +//! layout.rs ← COMPBASE 独占：Q8/Q9 两个布局陷阱的固定解法 +//! buttons/ ← COMPBASE（12b §1 按钮家族 + §2 IconButton） +//! divider.rs ← COMPBASE（15 §22） +//! selection/ ← 本文件只放桩；后续 mission 在自己的目录里填（§18/§19/§10/§13） +//! inputs/ ← 同上（§9/§20/§11/§8） +//! feedback/ ← 同上（§12/§14/§7/§15） +//! navigation/ ← 同上（§4/§6/§21/§16） +//! gallery/ ← 视觉验收 harness（`--screen=gallery`） +//! ``` +//! +//! **后续 mission 只写自己目录内的文件，不改本文件**：四个家族桩已经在这里声明好， +//! 每个家族文件自带一个 `demo()`（占位 → 真组件），gallery 侧对应文件也在 +//! `gallery/` 里预置了同构的桩。加组件 = 只改自家目录里的文件。 +//! +//! ## 组件签名纪律（契约 §2） +//! +//! 组件**对消息类型泛型**，不 import `crate::app::Message`： +//! +//! ```text +//! pub fn filled<'a, M: Clone + 'a>(ui: &'a Ui, ...) -> Element<'a, M> +//! ``` +//! +//! `Ui` 一律 `&'a Ui` 传入，组件内部**不许** `Ui::new`；深浅热切靠外部重建整树。 +//! +//! ## 令牌纪律 +//! +//! 组件里**零**色值 / 字号 / 半径 / 间距 / α 字面量：颜色走 [`crate::theme::Ui`]， +//! 状态层走 [`interaction`]，尺寸走 `unlucky_design` 的 `LayoutMetrics` / `Space` / +//! `IconSize` / `ShapeScale`。缺令牌 → 登记 G 编号（续 15 §25 的 G13），**不发明**。 +//! [`gate`] 里的测试会扫本目录源码执行这条纪律。 +//! +//! ## 为什么 `components` 由 `app.rs` 声明 +//! +//! `src/lib.rs` 是五条组件线共用的文件（并行线改它必然冲突）。本模块挂在 +//! `app.rs` 的 `#[path]` 声明下，路径仍是 `src/components/`，这样 COMPBASE 的 +//! 全部改动都落在自己 scope 内。 + +pub mod buttons; +pub mod divider; +pub mod feedback; +pub mod gallery; +pub mod inputs; +pub mod interaction; +pub mod layout; +pub mod navigation; +pub mod selection; + +#[cfg(test)] +mod gate; diff --git a/crates/app-iced/src/components/navigation/app_bar.rs b/crates/app-iced/src/components/navigation/app_bar.rs new file mode 100644 index 0000000..0f6e5a6 --- /dev/null +++ b/crates/app-iced/src/components/navigation/app_bar.rs @@ -0,0 +1,353 @@ +//! AppBar（small）（`research/12b` §16）：页头 56、标题 + 副标题、leading / trailing 槽位、滚动换色。 +//! +//! ## 参考值（`[源]` = A1，本轮 `javap` 实读本机 AAR） +//! +//! | # | 检查项 | 参考值 | 本项目 | +//! |---|---|---|---| +//! | 16.1 | 页头高 | `AppBarSmallTokens.ContainerHeight` = **64** | **56** = `LM.page_header_height`（登记偏离 −8） | +//! | 16.3 | 容器 | `AppBarTokens.ContainerColor = Surface` + L0；**滚动后** `OnScrollContainerColor = SurfaceContainer` + `OnScrollContainerElevation`（L2） | 同 | +//! | 16.4 | 字级 | `TitleFont = TitleLarge`（emphasized w500）· `SubtitleFont = LabelMedium` + `SubtitleColor = OnSurfaceVariant` | 同 | +//! | 16.5 | 图标 | `IconSize = 24`；leading `OnSurface`、trailing `OnSurfaceVariant` | 同 | +//! | 16.6 | 左右内边距 | `LeadingSpace = 4` / `TrailingSpace = 4`（+ IconButton 自带 40 宽 → 视觉起手 20） | 同 | +//! +//! ## 「滚动时的高度变化」——**规范上不存在**（不是我们没做） +//! +//! A1 的 `AppBarTokens` 全字段实读（`javap -p -c androidx.compose.material3.tokens.AppBarTokens`）： +//! +//! ```text +//! AvatarSize 32 · ContainerColor Surface · ContainerElevation · ContainerShape CornerNone +//! IconButtonSpace · IconSize 24 · LeadingIconColor · LeadingSpace 4 +//! OnScrollContainerColor SurfaceContainer · OnScrollContainerElevation ← 滚动只改这两项 +//! SubtitleColor/SubtitleFont · TitleColor/TitleFont · TrailingIconColor · TrailingSpace 4 +//! ``` +//! +//! **整个 tokens 包里 `OnScroll*` 只有两个字段**（颜色与高程，见 `grep` 全量核对的报告）， +//! 没有任何 `OnScroll…Height`；高度只在**尺寸档**（`AppBarSmallTokens.ContainerHeight = 64`）里， +//! 而那是 `small` / `medium` / `large` 三个**不同组件**的分档，不是滚动驱动的形变。 +//! 所以滚动时**高度不变**、只换容器色 + 升到 L2 阴影——这是规范，不是偏离。 +//! +//! 我们与规范的两处差异各登记一条： +//! +//! - **D-M79-2** 高度 56 而不是 64（项目骨架口径 `LM.page_header_height`，已有页面按 56 排版）； +//! - 不做 `Medium` / `Large` 的**折叠（collapsing）**形态——那是另外两个组件（`AppBarMediumTokens` +//! / `AppBarLargeTokens`），本 mission 的 §16 只要求 small。 + +use iced::widget::text::{LineHeight, Wrapping}; +use iced::widget::{button, container, text}; +use iced::{ + Alignment, Background, Border, Color, Element, Length, Padding, Pixels, Shadow, Vector, +}; + +use unlucky_design::color::Role; +use unlucky_design::elevation::Elevation; +use unlucky_design::icons::IconKind; +use unlucky_design::shape::ShapeScale; +use unlucky_design::typography::TypeRole; + +use crate::icons; +use crate::theme::Ui; + +use super::super::interaction::{self, Interaction}; +use super::super::layout; +use super::geometry::AppBarGeometry; + +/// 页头里的一个图标动作。 +#[derive(Debug, Clone)] +pub struct AppBarAction { + 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..2a8a690 --- /dev/null +++ b/crates/app-iced/src/components/navigation/drawer.rs @@ -0,0 +1,140 @@ +//! NavigationDrawer / NavigationRail（`research/15` §21 + 12b §5）：**同一个容器的两个宽度**（D33）。 +//! +//! 本文件只装「容器」：宽度（88 ⇄ 240）、`CornerLargeEnd` 圆角、分组标题、组间分隔线。 +//! 一项长什么样（`NavItem` / `NavGroup` / 颜色求值 / 药丸排布）在 `drawer/item.rs`。 +//! +//! ## 参考值与 D33（详见 `geometry.rs` 的表） +//! +//! ```text +//! 折叠 = Rail 88 = LayoutMetrics::nav_rail_width 项高 52 = 药丸 32 + 4 + 标签 16 +//! 展开 = Drawer 240 = LayoutMetrics::nav_drawer_width 项高 56 = A1 ActiveIndicatorHeight（G24） +//! 药丸：rail 88 − 2×16 = 56（M68 的 56×32）；drawer 240 − 2×12 = 216（= A1 的 360 − 2×12） +//! ``` +//! +//! 两者共用 [`navigation`] 一个入口、一套颜色角色、一套 full 圆角药丸；切换时圆角语言不变， +//! 一屏导航容器数恒为 1（§21.9）。**不是两套组件**——D33 的可验收形式就是「同一函数两个宽度」。 +//! +//! ## Q8 的现场 +//! +//! M68 的药丸写 56 宽后用 `center_x(Length::Fill)` 居中，容器尺寸被 Fill 覆盖成 88 宽（图上横贯全轨）。 +//! 这里药丸宽由 [`NavPaneGeometry::pill_width`] 给出，居中一律交给父级 `align_x`。 +//! +//! ## 分组标题（只 drawer 侧，§21.8） +//! +//! `TitleSmall` + `OnSurfaceVariant`，**不可点**；组与组之间 1px `OutlineVariant` +//! （复用 [`crate::app::components::divider`]），不用背景色块分区。 + +use iced::widget::container; +use iced::{Background, Border, Element, Length, Padding}; + +use unlucky_design::color::Role; +use unlucky_design::elevation::MaterialLayer; +use unlucky_design::typography::TypeRole; + +use crate::theme::Ui; + +use super::super::divider; +use super::geometry::{NavLayout, NavPaneGeometry}; + +mod item; +use item::{line, nav_row}; +pub use item::{NavGroup, NavItem}; + +/// 导航容器（D33：`layout` 决定 88 还是 240，其余全同）。 +#[derive(Debug, Clone)] +pub struct Navigation<'a, M> { + layout: NavLayout, + groups: Vec>, +} + +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, item, geometry)); + } + } + + container(body) + .width(Length::Fixed(geometry.width)) + .height(Length::Fill) + // 轨顶留白走 padding（不是 spacer 元素：会被 column 的 spacing 再加一档，M68 P3-5） + .padding(Padding { + top: ui.space(unlucky_design::spacing::Space::X6), + right: 0.0, + bottom: 0.0, + left: 0.0, + }) + .style(move |_theme| container::Style { + // §21.3 标准（常驻）= Surface + L0；形状 CornerLargeEnd（内侧两角 16） + background: Some(Background::Color(ui.layer(MaterialLayer::Canvas))), + border: Border { + radius: geometry.radius, + ..Border::default() + }, + ..container::Style::default() + }) + .into() +} + +#[cfg(test)] +mod tests; diff --git a/crates/app-iced/src/components/navigation/drawer/item.rs b/crates/app-iced/src/components/navigation/drawer/item.rs new file mode 100644 index 0000000..4b4a667 --- /dev/null +++ b/crates/app-iced/src/components/navigation/drawer/item.rs @@ -0,0 +1,296 @@ +//! 导航项的公共类型与一行渲染（`drawer.rs` 的私有子模块：单文件 ≤400 行，AGENTS.md §3-1）。 +//! +//! 拆出去的是「一项长什么样」（`NavItem` / `NavGroup` + 颜色求值 + 一行布局）， +//! `drawer.rs` 只留「容器长什么样」（宽度、圆角、分组标题、分隔线）。 + +use iced::widget::text::{LineHeight, Wrapping}; +use iced::widget::{button, container, text}; +use iced::{Alignment, Background, Border, Color, Element, Length, Padding, Pixels, Shadow}; + +use unlucky_design::color::Role; +use unlucky_design::icons::IconKind; +use unlucky_design::typography::TypeRole; + +use crate::icons; +use crate::theme::Ui; + +use super::super::super::interaction::{self, Interaction}; +use super::super::super::layout; +use super::super::geometry::{NavLayout, NavPaneGeometry}; + +/// 一条导航项。 +#[derive(Debug, Clone)] +pub struct NavItem<'a, M> { + pub(super) label: &'a str, + pub(super) icon: IconKind, + pub(super) selected: bool, + pub(super) on_press: Option, + 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, + layout: NavLayout, + state: Interaction, + selected: bool, +) -> ItemPalette { + if state.is_disabled() { + let ink = interaction::disabled_content_over_role(ui, Role::OnSurface, false); + return ItemPalette { + pill: None, + icon: ink, + label: ink, + }; + } + + if selected { + let pill = interaction::overlay_color( + ui, + state, + Role::OnSecondaryContainer, + Role::SecondaryContainer, + ) + .unwrap_or_else(|| ui.color(Role::SecondaryContainer)); + return ItemPalette { + pill: Some(pill), + icon: ui.color(Role::OnSecondaryContainer), + // rail 的选中标签是 `Secondary`（12b 5.6）；drawer 是 `OnSecondaryContainer`（§21.7） + label: match layout { + NavLayout::Rail => ui.color(Role::Secondary), + NavLayout::Drawer => ui.color(Role::OnSecondaryContainer), + }, + }; + } + + // 未选中：静息 `OnSurfaceVariant`，hover/focus/pressed 提到 `OnSurface` + let ink = match state { + Interaction::Enabled => ui.color(Role::OnSurfaceVariant), + _ => ui.color(Role::OnSurface), + }; + ItemPalette { + pill: interaction::overlay_color(ui, state, Role::OnSurface, Role::Surface), + icon: ink, + label: ink, + } +} + +/// 一块文字（显式行高，让项高与行高对得上）。 +pub(super) fn line<'a, M: 'a>( + ui: &'a Ui, + value: &'a str, + role: TypeRole, + color: Color, +) -> Element<'a, M> { + let style = ui.style(role); + text(value) + .size(style.size_px) + .line_height(LineHeight::Absolute(Pixels(style.line_height_px))) + // 单行（项高固定 52/56）：长分组名/实例名不许折行（偏离 D-M79-5） + .wrapping(Wrapping::None) + .font(ui.font_of(style)) + .color(color) + .into() +} + +/// 一项（rail：图标在上、标签在下；drawer：图标在左、标签在右）。 +pub(super) fn nav_row<'a, M: Clone + 'a>( + ui: &'a Ui, + item: NavItem<'a, M>, + geometry: NavPaneGeometry, +) -> Element<'a, M> { + let forced = item.state.or(if item.on_press.is_none() { + Some(Interaction::Disabled) + } else { + None + }); + let state = forced.unwrap_or(Interaction::Enabled); + let colors = palette(ui, geometry.layout, state, item.selected); + let radius = iced::border::Radius::new(geometry.pill_height / 2.0); + + let icon = layout::fixed( + geometry.icon, + geometry.icon, + icons::view::(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..c160951 --- /dev/null +++ b/crates/app-iced/src/components/navigation/drawer/tests.rs @@ -0,0 +1,115 @@ +//! `drawer` 的单元测试（单文件 ≤400 行，AGENTS.md §3-1 拆出来）。 + +use super::super::super::interaction::{self, Interaction}; +use super::item::palette; +use super::*; + +use unlucky_design::color::SchemeFlavor; +use unlucky_design::icons::IconKind; +use unlucky_design::typography::Platform; + +use crate::theme::Families; + +fn ui() -> Ui { + Ui::with_platform( + SchemeFlavor::Light, + Platform::Windows, + Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", + }, + ) +} + +/// §21.7：选中项图标/标签都是 `OnSecondaryContainer`，药丸 `SecondaryContainer`。 +#[test] +fn drawer_selected_uses_secondary_container() { + let ui = ui(); + let palette = palette(&ui, NavLayout::Drawer, Interaction::Enabled, true); + assert_eq!(palette.pill, Some(ui.color(Role::SecondaryContainer))); + assert_eq!(palette.icon, ui.color(Role::OnSecondaryContainer)); + assert_eq!(palette.label, ui.color(Role::OnSecondaryContainer)); +} + +/// 12b §5.6：**rail** 的选中标签是 `Secondary`（与 drawer 不同，别串线）。 +#[test] +fn rail_selected_label_is_secondary() { + let ui = ui(); + let rail = palette(&ui, NavLayout::Rail, Interaction::Enabled, true); + let drawer = palette(&ui, NavLayout::Drawer, Interaction::Enabled, true); + assert_eq!(rail.label, ui.color(Role::Secondary)); + assert_ne!(rail.label, drawer.label, "两条线的选中标签角色不同"); + // 但图标与药丸相同（同一套语言） + assert_eq!(rail.icon, drawer.icon); + assert_eq!(rail.pill, drawer.pill); +} + +/// 未选中：静息 `OnSurfaceVariant`；hover/focus/pressed 提到 `OnSurface` 且叠状态层。 +#[test] +fn inactive_lifts_to_on_surface() { + let ui = ui(); + let resting = palette(&ui, NavLayout::Drawer, Interaction::Enabled, false); + assert_eq!(resting.label, ui.color(Role::OnSurfaceVariant)); + assert_eq!(resting.pill, None); + for state in [ + Interaction::Hovered, + Interaction::Focused, + Interaction::Pressed, + ] { + let active = palette(&ui, NavLayout::Drawer, state, false); + assert_eq!(active.label, ui.color(Role::OnSurface), "{state:?}"); + assert_eq!(active.icon, ui.color(Role::OnSurface), "{state:?}"); + assert!(active.pill.is_some(), "{state:?} 必须叠状态层"); + } +} + +/// 禁用：`OnSurface`@38%，不画药丸，不叠状态层。 +#[test] +fn disabled_draws_no_pill() { + let ui = ui(); + let palette = palette(&ui, NavLayout::Drawer, Interaction::Disabled, true); + assert_eq!( + palette.icon, + interaction::disabled_content_over_role(&ui, Role::OnSurface, false) + ); + assert_eq!(palette.label, palette.icon); + assert_eq!(palette.pill, None); +} + +/// 禁用是**修饰器**：只清消息，图标 / 选中态全部保留。 +#[test] +fn disabled_only_clears_the_message() { + let item = NavItem::new("Settings", IconKind::Settings, ()) + .selected() + .disabled(); + assert!(item.on_press.is_none()); + assert!(item.selected); + assert_eq!(item.icon, IconKind::Settings); + assert_eq!(item.label, "Settings"); +} + +/// D33：两种宽度都能建出树（同一个 `navigation` 入口）。 +#[test] +fn both_layouts_build_a_tree() { + let ui = ui(); + for layout in NavLayout::ALL { + let base = match layout { + NavLayout::Rail => Navigation::rail(), + NavLayout::Drawer => Navigation::drawer(), + }; + let _: Element<'_, ()> = navigation( + &ui, + base.group( + NavGroup::titled("LIBRARY") + .item(NavItem::new("Instances", IconKind::Instances, ()).selected()) + .item(NavItem::new("Download", IconKind::Download, ())), + ) + .group(NavGroup::titled("SYSTEM").item(NavItem::new( + "Settings", + IconKind::Settings, + (), + ))), + ); + } +} diff --git a/crates/app-iced/src/components/navigation/geometry.rs b/crates/app-iced/src/components/navigation/geometry.rs new file mode 100644 index 0000000..1e1b88e --- /dev/null +++ b/crates/app-iced/src/components/navigation/geometry.rs @@ -0,0 +1,333 @@ +//! 导航类家族的**几何**：能取令牌的取令牌，取不到的在此登记 G 编号（不散落在组件里）。 +//! +//! ## 参考值 → 落点（`[源]` = A1，`material3-android:1.4.0`；本轮逐条用 `javap` 读本机 AAR 复核） +//! +//! ```text +//! javap -p -c androidx.compose.material3.tokens.ListTokens → 56/72/88、16/16、图标 24 +//! javap -p -c androidx.compose.material3.tokens.NavigationDrawerTokens +//! → ActiveIndicatorHeight 56、ActiveIndicatorWidth 336、ContainerWidth 360、CornerLargeEnd +//! javap -p -c androidx.compose.material3.NavigationDrawerItemDefaults +//! → ItemPadding = 12（bipush 12 → PaddingValues(12f, 0f)） +//! javap -p -c androidx.compose.material3.tokens.PrimaryNavigationTabTokens +//! → ContainerHeight 48、IconAndLabelTextContainerHeight 64、ActiveIndicatorHeight 3、图标 24 +//! javap -p -c androidx.compose.material3.tokens.SecondaryNavigationTabTokens → ContainerHeight 48 +//! javap -p -c androidx.compose.material3.tokens.AppBarSmallTokens → ContainerHeight 64 +//! ``` +//! +//! | # | 量 | 参考值（A1） | 本项目 | 来源 | 落点 | +//! |---|---|---|---|---|---| +//! | 4.1 | ListItem 一行高 | **56** | **44** = `LM.row_height`（登记偏离 −12） | `[源]` `ListItemOneLineContainerHeight` | [`ListItemGeometry::heights`] | +//! | 4.2 | ListItem 两/三行高 | **72 / 88** | **60 / 76**（每多一行 +16，与官方同 delta） | `[源]` | 同上 | +//! | 4.3 | ListItem 左右内边距 | **16 / 16** | 同 | `[源]` `ListItemLeading/TrailingSpace` | `pad_start` / `pad_end` | +//! | 4.4 | ListItem leading 图标 | **24** | 同 | `[源]` `ListItemLeadingIconSize` | `icon`（`IconSize::Toolbar`） | +//! | 4.4b | 图标 ↔ 文本间距 | 无 token | **16** | `[估]`（Compose 由 ListItem 内部排版决定） | `gap`（`Space::X4`） | +//! | 6.1 | Tabs 容器高 | **48**（带图标 **64**） | 同 | `[源]` | [`TABS_HEIGHT`]（**G22**：`LM` 无此档） | +//! | 6.2 | 指示条 | 高 **3**、圆角 **3**、`Primary` | 同 | `[源]` `ActiveIndicatorHeight` + `RoundedCornerShape(3dp)` | [`TABS_INDICATOR`]（**G23**） | +//! | 6.6 | Secondary 分隔线 | **1dp `SurfaceVariant`** | 同 | `[源]` `DividerHeight` / `DividerColor` | [`TabsGeometry::secondary_bar`] | +//! | 21.4 | drawer 项高 | **56**（`heightIn(min = ActiveIndicatorHeight)`） | **56**（`LM.nav_item_height` 是 44，登记偏离 +12） | `[源]` | [`DRAWER_ITEM_HEIGHT`]（**G24**） | +//! | 21.5 | drawer 指示器 | 宽 = 容器宽 − **24**（360 → 336）；高 = 项高；圆角 full | 240 − 24 = **216** | `[源]` `ItemPadding = 12` | [`NavPaneGeometry::pill_width`] | +//! | 21.6 | drawer 项内 | 项外 **12**；内 start **16** / end **24**；图标 24；图标↔label **12**；label `LabelLarge` | 同 | `[源]` `ItemPadding` + `navigation/15 §21.6` | [`ComponentMetrics::NAVIGATION_DRAWER`] | +//! | 21.2 | drawer 形状 | **`CornerLargeEnd`**（只有靠内容那侧两角 16，贴边侧直角） | 同（右两角 16） | `[源]` `ContainerShape` | [`NavPaneGeometry::radius`] | +//! | 16.1 | AppBar small 高 | **64** | **56** = `LM.page_header_height`（登记偏离 −8） | `[源]` `AppBarSmallTokens.ContainerHeight` | [`AppBarGeometry::height`] | +//! | 16.5/16.6 | AppBar 图标 / 左右内边距 | **24** / **4** | 同 | `[源]` `AppBarTokens.IconSize/LeadingSpace/TrailingSpace` | [`AppBarGeometry`] | +//! +//! **G 编号**（续 `research/15` §25 的 G13；G16~G20 已被 selection/inputs 用掉）： +//! +//! - **G22** Tabs 容器高 48 / 带图标 64：`LayoutMetrics` 无此档，收在本文件的 [`TABS_HEIGHT`]； +//! - **G23** Tabs 指示条高 3 / 最小项宽 90：同上，收在本文件 [`TABS_INDICATOR`]， +//! 而**最小项宽 90（`TabMinWidth`）本轮不施加**——iced 无 min-width，tab 按内容 hug， +//! 指示条因此严格等于「该 tab 的内容宽 + 2×16」，见 [`TabsGeometry::pad`] 的说明； +//! - **G24** drawer 项高 56：令牌 `LM.nav_item_height = 44` 是**列表行**的密集档，drawer 项按 A1 取 56。 +//! +//! ## 两个「同一个容器两个宽度」（D33） +//! +//! [`NavPaneGeometry::of`] 是**唯一**一处同时知道 88 与 240 的地方：宽 → 药丸宽、项高、内边距 +//! 全部由 `layout` 派生。Q8 的历史事故（药丸 56×32 被 `center_x(Fill)` 撑成 88×32）就出在 +//! 「药丸宽度不是从容器宽派生」——这里把派生写成函数，组件层拿不到手写数字。 + +use iced::border::Radius; + +use unlucky_design::component_map::{Component, ComponentMetrics}; +use unlucky_design::icons::IconSize; +use unlucky_design::shape::ShapeScale; +use unlucky_design::spacing::Space; + +use crate::theme::Ui; + +/// Tabs 容器高（A1 `PrimaryNavigationTabTokens.ContainerHeight`，**G22**）。 +pub const TABS_HEIGHT: f32 = 48.0; +/// 带图标的 Tabs 容器高（A1 `IconAndLabelTextContainerHeight`，**G22**；本轮只做文字档）。 +pub const TABS_ICON_HEIGHT: f32 = 64.0; +/// Tabs 指示条高（A1 `PrimaryNavigationTabTokens.ActiveIndicatorHeight`，**G23**）。 +pub const TABS_INDICATOR: f32 = 3.0; +/// drawer 项高（A1 `NavigationDrawerItemDefaults` 的 `heightIn(min = ActiveIndicatorHeight)`，**G24**）。 +pub const DRAWER_ITEM_HEIGHT: f32 = 56.0; + +/// 导航容器的两种宽度（D33：**同一个容器**的折叠 / 展开，不是两套组件）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +pub enum NavLayout { + /// 折叠：宽 **88**（`LayoutMetrics::nav_rail_width`），项内「药丸在上、标签在下」。 + Rail, + /// 展开：宽 **240**（`LayoutMetrics::nav_drawer_width`），项内「图标在左、标签在右」。 + Drawer, +} + +impl NavLayout { + /// 两种宽度（gallery）与测试用。 + pub const ALL: [NavLayout; 2] = [NavLayout::Rail, NavLayout::Drawer]; + + /// 稳定名字（截图文件名 / 图例用）。 + pub const fn name(self) -> &'static str { + match self { + NavLayout::Rail => "rail", + NavLayout::Drawer => "drawer", + } + } +} + +/// ListItem 的几何（`research/12b` §4）。 +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct ListItemGeometry { + /// 一 / 两 / 三行行高（44 / 60 / 76；A1 是 56 / 72 / 88，本项目登记偏离 −12）。 + pub heights: [f32; 3], + /// 内容起始侧内边距（16，A1 `ListItemLeadingSpace`）。 + pub pad_start: f32, + /// 内容结束侧内边距（16，A1 `ListItemTrailingSpace`）。 + pub pad_end: f32, + /// leading / trailing 图标边长（24，A1 `ListItemLeading/TrailingIconSize`）。 + pub icon: f32, + /// 图标 ↔ 文本间距（16，`[估]`）。 + pub gap: f32, +} + +impl ListItemGeometry { + /// 从令牌求值。 + pub fn of(ui: &Ui) -> Self { + let one = ui.metrics().row_height; + let step = ui.space(Space::X4); + Self { + // 每多一行 +16：与官方 56→72→88 的 delta 一致，差的只是基准值（−12）。 + heights: [one, one + step, one + step * 2.0], + pad_start: ui.space(Space::X4), + pad_end: ui.space(Space::X4), + icon: IconSize::Toolbar.px(), + gap: ui.space(Space::X4), + } + } + + /// `lines` 行的行高（1/2/3 之外按就近夹取，不 panic——调用方传入的是枚举值）。 + pub fn height(&self, lines: usize) -> f32 { + self.heights[lines.clamp(1, 3) - 1] + } + + /// `lines` 行的文本块高（行高 − 文本块 = 上下各一半的内边距）。 + pub fn text_block(&self, ui: &Ui, lines: usize) -> f32 { + let headline = ui.style(typography_headline()).line_height_px; + match lines.clamp(1, 3) { + // 一行：主文本（BodyLarge 24） + 1 => headline, + // 两行：主 + 辅助（BodyLarge 24 + BodyMedium 20） + 2 => headline + ui.style(typography_supporting()).line_height_px, + // 三行：overline（LabelSmall 16）+ 主 + 辅助 + _ => { + ui.style(typography_overline()).line_height_px + + headline + + ui.style(typography_supporting()).line_height_px + } + } + } + + /// 垂直内边距 = (行高 − 文本块) / 2（一行 44 → 10，两行 60 → 8，三行 76 → 8）。 + pub fn pad_y(&self, ui: &Ui, lines: usize) -> f32 { + (self.height(lines) - self.text_block(ui, lines)) / 2.0 + } +} + +/// ListItem 主文本字级（12b 4.5：`BodyLarge 16/24` `[源] ListTokens.ListItemLabelTextFont`）。 +pub const fn typography_headline() -> unlucky_design::typography::TypeRole { + unlucky_design::typography::TypeRole::BodyLarge +} + +/// ListItem 辅助文本字级（12b 4.5：`BodyMedium 14/20`）。 +pub const fn typography_supporting() -> unlucky_design::typography::TypeRole { + unlucky_design::typography::TypeRole::BodyMedium +} + +/// ListItem overline 字级（12b 4.5：`LabelSmall 11/16`）。 +pub const fn typography_overline() -> unlucky_design::typography::TypeRole { + unlucky_design::typography::TypeRole::LabelSmall +} + +/// Tabs 的几何（`research/12b` §6）。 +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct TabsGeometry { + /// 容器高（48，**G22**）。 + pub height: f32, + /// 图标边长（24，A1 `Primary/SecondaryNavigationTabTokens.IconSize`）。 + pub icon: f32, + /// 标签左右内边距（16，`[估]`：Compose `TabRow` 的 `HorizontalTextPadding`）。 + /// + /// 这条同时决定「指示条跟随选中项宽度」的**可测形态**：指示条宽 = 标签墨迹宽 + 2×16， + /// 所以两段文案长度不同的 tab，其指示条宽度必然不同（渲染层断言用它）。 + pub pad: f32, + /// Primary 指示条高（3，**G23**）。 + pub primary_bar: f32, + /// Secondary 分隔线厚度（1 = `LM.divider_thickness`）。 + pub secondary_bar: f32, +} + +impl TabsGeometry { + /// 从令牌求值。 + pub fn of(ui: &Ui) -> Self { + Self { + height: TABS_HEIGHT, + icon: IconSize::Toolbar.px(), + pad: ui.space(Space::X4), + primary_bar: TABS_INDICATOR, + secondary_bar: ui.metrics().divider_thickness, + } + } + + /// 指示条 / 分隔线高度：Primary 取 3px，Secondary 取 1px。 + pub fn bar(&self, primary: bool) -> f32 { + if primary { + self.primary_bar + } else { + self.secondary_bar + } + } + + /// Primary 指示条圆角：`RoundedCornerShape(3dp)` 落在 3px 高的条上，与 `Full`（=1.5 半径）渲染结果相同。 + /// + /// Secondary 的 1px 分隔线**没有圆角**：A1 是一条直线；早先给 0.5 圆角，相邻 tab 的分段之间 + /// 因此留下 1px 亮缝（视觉 r1 P2-2 实测 `25..101 | 103..191 | 193..265`）。 + pub fn indicator_radius(&self) -> Radius { + Radius::new(self.primary_bar / 2.0) + } +} + +/// 导航容器（rail ⇄ drawer）的几何（`research/15` §21 + D33）。 +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct NavPaneGeometry { + /// 哪种宽度（88 / 240）。 + pub layout: NavLayout, + /// 容器宽（88 / 240）。 + pub width: f32, + /// 项高（rail 52 = 药丸 32 + 4 + 标签 16；drawer 56，**G24**）。 + pub item_height: f32, + /// 选中药丸宽（rail 56 = 88 − 2×16；drawer 216 = 240 − 2×12）。 + pub pill_width: f32, + /// 选中药丸高（rail 32；drawer 56 = 项高）。 + pub pill_height: f32, + /// 药丸离容器左右各缩多少（rail 16；drawer 12 = `ItemPadding`）。 + pub pill_inset: f32, + /// 内容起始侧内边距（drawer 16；rail 由药丸居中决定）。 + pub pad_start: f32, + /// 内容结束侧内边距（drawer 24）。 + pub pad_end: f32, + /// 图标边长（24）。 + pub icon: f32, + /// 图标 ↔ 标签间距（rail 是纵向 4；drawer 是横向 12）。 + pub gap: f32, + /// 容器圆角（`CornerLargeEnd`：贴边侧直角、靠内容侧 16）。 + pub radius: Radius, +} + +impl NavPaneGeometry { + /// 从令牌求值：**88 与 240 只在这里分叉**，其余全部由宽度派生。 + pub fn of(ui: &Ui, layout: NavLayout) -> Self { + let metrics = ui.metrics(); + let item = drawer_metrics(); + // CornerLargeEnd：只有靠内容那一侧（右侧）两角 16，贴边侧直角。 + let corner = shape_radius(); + let radius = Radius { + top_left: 0.0, + top_right: corner, + bottom_right: corner, + bottom_left: 0.0, + }; + + match layout { + NavLayout::Rail => { + let width = metrics.nav_rail_width; + let pill_inset = ui.space(Space::X4); + let pill_height = metrics.control_height - ui.space(Space::X2); + Self { + layout, + width, + // 52 = 药丸 32 + 4 + 标签行高 16（与 `shell/nav.rs` 的项高同源） + item_height: pill_height + + ui.space(Space::X1) + + ui.style(unlucky_design::typography::TypeRole::LabelMedium) + .line_height_px, + pill_width: width - pill_inset * 2.0, + pill_height, + pill_inset, + pad_start: pill_inset, + pad_end: pill_inset, + icon: IconSize::Toolbar.px(), + gap: ui.space(Space::X1), + radius, + } + } + NavLayout::Drawer => { + let width = metrics.nav_drawer_width; + Self { + layout, + width, + item_height: DRAWER_ITEM_HEIGHT, + pill_width: item.indicator_width(width), + pill_height: DRAWER_ITEM_HEIGHT, + pill_inset: item.inset, + pad_start: item.pad_start, + pad_end: item.pad_end, + icon: item.icon, + gap: item.gap, + radius, + } + } + } + } +} + +/// 导航容器的组件级微度量（`ComponentMetrics::NAVIGATION_DRAWER`；缺令牌会直接炸，不静默回退）。 +fn drawer_metrics() -> ComponentMetrics { + Component::NavigationDrawer + .metrics() + .expect("NavigationDrawer 的 ComponentMetrics 是 G10 的落点") +} + +/// 容器圆角（`Component::NavigationDrawer.spec().shape = ShapeScale::Large` → 16）。 +fn shape_radius() -> f32 { + let shape = Component::NavigationDrawer.spec().shape; + debug_assert_eq!(shape, ShapeScale::Large, "ContainerShape=CornerLargeEnd"); + shape.dp() +} + +/// AppBar（small）的几何（`research/12b` §16）。 +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct AppBarGeometry { + /// 页头高（56 = `LM.page_header_height`；A1 是 64，登记偏离 −8）。 + pub height: f32, + /// 图标边长（24，A1 `AppBarTokens.IconSize`）。 + pub icon: f32, + /// 左右内边距（4，A1 `AppBarTokens.Leading/TrailingSpace`）。 + pub edge: f32, + /// 头像边长（32，A1 `AppBarTokens.AvatarSize`）。 + pub avatar: f32, +} + +impl AppBarGeometry { + /// 从令牌求值。 + pub fn of(ui: &Ui) -> Self { + Self { + height: ui.metrics().page_header_height, + icon: IconSize::Toolbar.px(), + edge: ui.space(Space::X1), + avatar: IconSize::Empty.px(), + } + } +} + +#[cfg(test)] +mod tests; diff --git a/crates/app-iced/src/components/navigation/geometry/tests.rs b/crates/app-iced/src/components/navigation/geometry/tests.rs new file mode 100644 index 0000000..263832b --- /dev/null +++ b/crates/app-iced/src/components/navigation/geometry/tests.rs @@ -0,0 +1,131 @@ +//! `geometry` 的单元测试（split 拆出来的：单文件 ≤400 行，AGENTS.md §3-1）。 + +use super::*; +use unlucky_design::color::SchemeFlavor; +use unlucky_design::typography::Platform; + +use crate::theme::Families; + +fn ui() -> Ui { + Ui::with_platform( + SchemeFlavor::Light, + Platform::Windows, + Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", + }, + ) +} + +/// 4.1 / 4.2：三种行高 44 / 60 / 76（A1 56/72/88 的登记偏离 −12）。 +#[test] +fn list_item_heights_are_44_60_76() { + let geometry = ListItemGeometry::of(&ui()); + assert_eq!(geometry.heights, [44.0, 60.0, 76.0]); + for lines in 1..=3 { + assert_eq!(geometry.height(lines), geometry.heights[lines - 1]); + } + // 官方 delta 也是每行 +16 + assert_eq!(geometry.heights[1] - geometry.heights[0], 16.0); + assert_eq!(geometry.heights[2] - geometry.heights[1], 16.0); +} + +/// 行高必须**装得下**文本块（否则文字会被裁）：三行文本块 16+24+20 = 60 ≤ 76。 +#[test] +fn list_item_rows_fit_their_text_block() { + let ui = ui(); + let geometry = ListItemGeometry::of(&ui); + for lines in 1..=3 { + let block = geometry.text_block(&ui, lines); + let pad = geometry.pad_y(&ui, lines); + assert!(pad >= 0.0, "{lines} 行的垂直内边距是负数（行高装不下文本）"); + assert!( + (block + pad * 2.0 - geometry.height(lines)).abs() < f32::EPSILON, + "{lines} 行：文本块 {block} + 2×{pad} ≠ 行高 {}", + geometry.height(lines) + ); + } + assert_eq!(geometry.text_block(&ui, 1), 24.0, "BodyLarge 24/24"); + assert_eq!(geometry.text_block(&ui, 2), 44.0, "24 + BodyMedium 20"); + assert_eq!(geometry.text_block(&ui, 3), 60.0, "LabelSmall 16 + 24 + 20"); + assert_eq!(geometry.pad_y(&ui, 1), 10.0, "(44 − 24) / 2"); + assert_eq!(geometry.pad_y(&ui, 3), 8.0, "(76 − 60) / 2"); +} + +/// 21.1 / 21.5 / 21.6：drawer 240、药丸 216（左右各缩 12）、项高 56、内边距 16/24。 +#[test] +fn drawer_pane_is_240_wide_with_a_216_pill() { + let geometry = NavPaneGeometry::of(&ui(), NavLayout::Drawer); + assert_eq!(geometry.width, 240.0, "D33 的展开宽度"); + assert_eq!(geometry.pill_inset, 12.0, "ItemPadding"); + assert_eq!( + geometry.pill_width, 216.0, + "240 − 2×12（A1: 360 − 2×12 = 336）" + ); + assert_eq!(geometry.item_height, 56.0, "G24：A1 ActiveIndicatorHeight"); + assert_eq!(geometry.pill_height, 56.0, "指示器高 = 项高"); + assert_eq!((geometry.pad_start, geometry.pad_end), (16.0, 24.0)); + assert_eq!(geometry.gap, 12.0, "图标 ↔ label"); + assert_eq!(geometry.icon, 24.0); + // 药丸 + 两侧内缩 = 容器宽（这条是「药丸从容器宽派生」的等式，Q8 的回归点） + assert!((geometry.pill_width + geometry.pill_inset * 2.0 - geometry.width).abs() < 0.01); +} + +/// D33：rail 与 drawer 是**同一个容器**的两个宽度（88 ⇄ 240），不是两套组件。 +#[test] +fn rail_and_drawer_share_one_container() { + let ui = ui(); + let rail = NavPaneGeometry::of(&ui, NavLayout::Rail); + let drawer = NavPaneGeometry::of(&ui, NavLayout::Drawer); + + assert_eq!(rail.width, 88.0); + assert_eq!(drawer.width, 240.0); + assert!(rail.width < drawer.width); + + // 同一个「药丸 = 容器宽 − 2×内缩」公式 + for pane in [rail, drawer] { + assert!( + (pane.pill_width + pane.pill_inset * 2.0 - pane.width).abs() < 0.01, + "{:?} 的药丸宽不是从容器宽派生的", + pane.layout + ); + // 圆角语言不变：都是 CornerLargeEnd（外侧直角、内侧 16） + assert_eq!((pane.radius.top_left, pane.radius.bottom_left), (0.0, 0.0)); + assert_eq!( + (pane.radius.top_right, pane.radius.bottom_right), + (16.0, 16.0) + ); + assert_eq!(pane.icon, 24.0); + } + + // rail 的药丸是 56×32（M68 已修正的结论），不是 drawer 的 216×56 + assert_eq!((rail.pill_width, rail.pill_height), (56.0, 32.0)); + assert_eq!((drawer.pill_width, drawer.pill_height), (216.0, 56.0)); +} + +/// 6.1 / 6.2 / 6.6：Tabs 48 高、指示条 3、Secondary 线 1。 +#[test] +fn tabs_geometry_matches_the_reference() { + let ui = ui(); + let geometry = TabsGeometry::of(&ui); + assert_eq!(geometry.height, 48.0, "G22"); + assert_eq!(geometry.icon, 24.0); + assert_eq!(geometry.pad, 16.0); + assert_eq!(geometry.bar(true), 3.0, "ActiveIndicatorHeight"); + assert_eq!(geometry.bar(false), 1.0, "DividerHeight"); + // RoundedCornerShape(3dp) 落在 3px 高的条上 = 半径 1.5（与 Full 同渲染） + assert_eq!(geometry.indicator_radius().top_left, 1.5); +} + +/// 16.1 / 16.5：AppBar 56（LM）、图标 24、左右 4、头像 32。 +#[test] +fn app_bar_geometry_matches_the_skeleton() { + let geometry = AppBarGeometry::of(&ui()); + assert_eq!( + geometry.height, 56.0, + "LM.page_header_height（A1 64，登记偏离）" + ); + assert_eq!((geometry.icon, geometry.edge), (24.0, 4.0)); + assert_eq!(geometry.avatar, 32.0); +} diff --git a/crates/app-iced/src/components/navigation/list_item.rs b/crates/app-iced/src/components/navigation/list_item.rs new file mode 100644 index 0000000..3f44d0a --- /dev/null +++ b/crates/app-iced/src/components/navigation/list_item.rs @@ -0,0 +1,306 @@ +//! ListItem（`research/12b` §4）：一行 / 两行 / 三行，leading / trailing 槽位，选中态，五态状态层。 +//! +//! ## 参考值（`[源]` = A1，本轮 `javap` 实读本机 AAR 的 `ListTokens` / `ListItemColors`） +//! +//! | # | 检查项 | 参考值 | 落点 | +//! |---|---|---|---| +//! | 4.1 | 一行高 | A1 **56** → 本项目 **44**（`LM.row_height`，登记偏离 −12） | [`ListItemGeometry::heights`] | +//! | 4.2 | 两 / 三行高 | A1 **72 / 88** → 本项目 **60 / 76**（每多一行 +16，与官方同 delta） | 同上 | +//! | 4.3 | 左右内边距 | **16 / 16** | `pad_start` / `pad_end` | +//! | 4.4 | leading | 图标 **24** `OnSurfaceVariant` | `IconSize::Toolbar` | +//! | 4.5 | 字级 | 主 `BodyLarge 16/24`、辅助 `BodyMedium 14/20`、overline `LabelSmall 11/16` | `TypeRole` | +//! | 4.7 | 状态 | hover/focus/pressed **文本与图标色不变**，只叠状态层（8/10/10%） | [`interaction`] | +//! | 4.8 | 选中 trailing | 图标 → **`Primary`** | `Role::Primary` | +//! +//! ## 禁用是**修饰器**，不是构造函数（照 `selection/chip.rs` 复审 P2-1 的结论） +//! +//! [`ListItem::disabled`] **只清消息**：图标、选中态、状态层全部保留。早期 chip 的 +//! `Chip::disabled(label)` 构造函数把图标和选中态一起丢了，图上是「另一行」，不是「这一行禁用」。 +//! +//! ## 禁用内容角色是 **`OnSurface`**，不是默认的 `OnSurfaceVariant` +//! +//! A1 实读（`javap -p -c androidx.compose.material3.tokens.ListTokens`）： +//! +//! ```text +//! ListItemDisabledLabelTextColor = OnSurface （+ ListItemDisabledLabelTextOpacity = 0.38f） +//! ListItemDisabledLeadingIconColor = OnSurface （+ 0.38f） +//! ListItemDisabledTrailingIconColor = OnSurface （+ 0.38f） +//! ``` +//! +//! 所以这里必须走 `interaction::disabled_content_over_role(ui, OnSurface, false)`； +//! 用默认的 `disabled_colors()`（写死 `OnSurfaceVariant`）会偏浅一档。 +//! +//! ## 选中态：本项目口径（**偏离登记 D-M79-1**） +//! +//! A1 的 `ListItemColors` **没有** selected 容器色（实读字段：containerColor / headline / leadingIcon / +//! overline / supporting / trailingIcon + 三个 disabled），选中只把 trailing 图标换成 `Primary`。 +//! mission 要求「选中态（SecondaryContainer）」，且本项目的菜单项（M77）与 drawer 项都用 +//! `SecondaryContainer` 表示「当前项」——三处保持同一语言，故 ListItem 也填 `SecondaryContainer` +//! + `OnSecondaryContainer`。**这是实质偏离**：A1 的 ListItem 选中行不换底色。 + +use iced::widget::text::{LineHeight, Wrapping}; +use iced::widget::{button, container, text}; +use iced::{Alignment, Background, Border, Color, Element, Length, Padding, Pixels, Shadow}; + +use unlucky_design::color::Role; +use unlucky_design::icons::IconKind; +use unlucky_design::shape::ShapeScale; + +use crate::icons; +use crate::theme::Ui; + +use super::super::interaction::{self, Interaction}; +use super::super::layout; +use super::geometry::{ + typography_headline, typography_overline, typography_supporting, ListItemGeometry, +}; + +/// 一个列表项（一行 / 两行 / 三行由槽位决定）。 +#[derive(Debug, Clone)] +pub struct ListItem<'a, M> { + overline: Option<&'a str>, + headline: &'a str, + supporting: Option<&'a str>, + leading: Option, + trailing: Option, + on_press: Option, + selected: bool, + state: Option, +} + +impl<'a, M> ListItem<'a, M> { + /// 一行项（主文本 + 可点消息）。 + pub fn new(headline: &'a str, on_press: M) -> Self { + Self { + overline: None, + headline, + supporting: None, + leading: None, + trailing: None, + on_press: Some(on_press), + selected: false, + state: None, + } + } + + /// 加一行辅助文本 → **两行**项（4.5：辅助 `BodyMedium`）。 + pub fn supporting(mut self, supporting: &'a str) -> Self { + self.supporting = Some(supporting); + self + } + + /// 加上方 overline → **三行**项（4.5：overline `LabelSmall`，`OnSurfaceVariant`）。 + pub fn overline(mut self, overline: &'a str) -> Self { + self.overline = Some(overline); + self + } + + /// 前置槽位（图标 24，`OnSurfaceVariant`）。 + pub fn leading(mut self, kind: IconKind) -> Self { + self.leading = Some(kind); + self + } + + /// 后置槽位（未选中 `OnSurface`，选中 `Primary`，见 4.8）。 + pub fn trailing(mut self, kind: IconKind) -> Self { + self.trailing = Some(kind); + self + } + + /// 选中态（`SecondaryContainer` + `OnSecondaryContainer`；偏离 D-M79-1 见模块文档）。 + pub fn selected(mut self) -> Self { + self.selected = true; + self + } + + /// 强制视觉态（gallery 状态矩阵取证；不动状态机）。 + pub fn state(mut self, state: Interaction) -> Self { + self.state = Some(state); + self + } + + /// 转禁用：**只清消息**，槽位与选中态一律保留。 + pub fn disabled(mut self) -> Self { + self.on_press = None; + self + } + + /// 行数（1 + 有 overline + 有 supporting）。 + pub fn lines(&self) -> usize { + usize::from(self.overline.is_some()) + 1 + usize::from(self.supporting.is_some()) + } +} + +/// 一项的颜色（按态 + 选中求值；禁用按 A1 的 `OnSurface`@38%）。 +#[derive(Debug, Clone, Copy, PartialEq)] +struct ItemPalette { + fill: Option, + headline: Color, + supporting: Color, + leading: Color, + trailing: Color, +} + +fn palette(ui: &Ui, state: Interaction, selected: bool) -> ItemPalette { + if state.is_disabled() { + // A1：ListItemDisabled*Color = OnSurface × 0.38（无容器时叠在 surface 上） + let ink = interaction::disabled_content_over_role(ui, Role::OnSurface, false); + return ItemPalette { + fill: None, + headline: ink, + supporting: ink, + leading: ink, + trailing: ink, + }; + } + + if selected { + let fill = interaction::overlay_color( + ui, + state, + Role::OnSecondaryContainer, + Role::SecondaryContainer, + ) + .unwrap_or_else(|| ui.color(Role::SecondaryContainer)); + return ItemPalette { + fill: Some(fill), + headline: ui.color(Role::OnSecondaryContainer), + supporting: ui.color(Role::OnSecondaryContainer), + leading: ui.color(Role::OnSecondaryContainer), + // 4.8：选中时 trailing 图标是 `Primary`（A1 ListItemSelectedTrailingIconColor） + trailing: ui.color(Role::Primary), + }; + } + + ItemPalette { + // 状态层叠在**行自己的底**（Surface）上，得到不透明结果（D27） + fill: interaction::overlay_color(ui, state, Role::OnSurface, Role::Surface), + headline: ui.color(Role::OnSurface), + supporting: ui.color(Role::OnSurfaceVariant), + leading: ui.color(Role::OnSurfaceVariant), + trailing: ui.color(Role::OnSurface), + } +} + +/// 一行文本（显式行高：三行块的 16+24+20 必须能精确等于 60，靠的就是它）。 +fn line<'a, M: 'a>( + ui: &'a Ui, + value: &'a str, + role: unlucky_design::typography::TypeRole, + color: Color, +) -> Element<'a, M> { + let style = ui.style(role); + text(value) + .size(style.size_px) + .line_height(LineHeight::Absolute(Pixels(style.line_height_px))) + // **单行**：行高是固定值（44/60/76），`Text` 默认 `Wrapping::Word` 会把长实例名 + // 折成两行、把三行块顶穿。官方要的是单行 ellipsis，iced 没有 ellipsis（D19 先例） + // → 单行 + 超长由外层 `clip(true)` 直接切（偏离 D-M79-5）。 + .wrapping(Wrapping::None) + .font(ui.font_of(style)) + .color(color) + .into() +} + +/// 列表项（`research/12b` §4）。 +pub fn list_item<'a, M: Clone + 'a>(ui: &'a Ui, item: ListItem<'a, M>) -> Element<'a, M> { + let geometry = ListItemGeometry::of(ui); + let lines = item.lines(); + let height = geometry.height(lines); + // 禁用 = 「没有消息」；`state` 是取证强制值，优先级更高（矩阵里画 hover 的禁用项也成立） + let forced = item.state.or(if item.on_press.is_none() { + Some(Interaction::Disabled) + } else { + None + }); + let colors = palette(ui, forced.unwrap_or(Interaction::Enabled), item.selected); + + let mut body = iced::widget::Column::new().spacing(0); + if let Some(overline) = item.overline { + body = body.push(line::( + 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 style = move |_theme: &iced::Theme, status: button::Status| { + let state = forced.unwrap_or_else(|| Interaction::from_status(status)); + let colors = palette(ui, state, selected); + button::Style { + background: colors.fill.map(Background::Color), + text_color: colors.headline, + // 4.x：ListItem 的形状是 `CornerNone`（直角），没有圆角档 + border: Border { + radius: ui.radius_dp(ShapeScale::None), + ..Border::default() + }, + shadow: Shadow::default(), + snap: true, + } + }; + + let button = button(body) + .width(Length::Fill) + .height(Length::Fixed(height)) + .padding(Padding { + top: pad_y, + right: geometry.pad_end, + bottom: pad_y, + left: geometry.pad_start, + }) + .style(style); + + let element: Element<'a, M> = match item.on_press { + Some(message) => button.on_press(message).into(), + None => button.into(), + }; + element +} + +#[cfg(test)] +mod tests; diff --git a/crates/app-iced/src/components/navigation/list_item/tests.rs b/crates/app-iced/src/components/navigation/list_item/tests.rs new file mode 100644 index 0000000..b1be068 --- /dev/null +++ b/crates/app-iced/src/components/navigation/list_item/tests.rs @@ -0,0 +1,127 @@ +//! `list_item` 的单元测试（split 拆出来的：单文件 ≤400 行，AGENTS.md §3-1）。 + +use super::*; + +use unlucky_design::color::SchemeFlavor; +use unlucky_design::typography::Platform; + +use crate::theme::Families; + +fn ui() -> Ui { + Ui::with_platform( + SchemeFlavor::Light, + Platform::Windows, + Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", + }, + ) +} + +/// 槽位决定行数：1 / 2 / 3（三行是 overline + headline + supporting）。 +#[test] +fn line_count_follows_the_slots() { + let one = ListItem::<()>::new("Instances", ()); + assert_eq!(one.lines(), 1); + let two = ListItem::<()>::new("Instances", ()).supporting("3 versions"); + assert_eq!(two.lines(), 2); + let three = ListItem::<()>::new("Instances", ()) + .overline("RECENT") + .supporting("3 versions"); + assert_eq!(three.lines(), 3); + // overline 单独存在也是两行（overline + headline） + let overline_only = ListItem::<()>::new("Instances", ()).overline("RECENT"); + assert_eq!(overline_only.lines(), 2); +} + +/// **禁用是修饰器**：只清消息，槽位与选中态全部保留（复审 P2-1 那条）。 +#[test] +fn disabled_only_clears_the_message() { + let item = ListItem::new("Instances", ()) + .leading(unlucky_design::icons::IconKind::Instances) + .trailing(unlucky_design::icons::IconKind::Settings) + .supporting("3 versions") + .selected() + .disabled(); + assert!(item.on_press.is_none(), "禁用必须清消息"); + assert!(item.leading.is_some(), "禁用不许删前置图标"); + assert!(item.trailing.is_some(), "禁用不许删后置图标"); + assert!(item.selected, "禁用不许删选中态"); + assert!(item.supporting.is_some(), "禁用不许删槽位"); + assert_eq!(item.lines(), 2); +} + +/// 禁用内容角色是 **`OnSurface`**@38%（A1 ListTokens），不是默认的 `OnSurfaceVariant`。 +#[test] +fn disabled_content_uses_on_surface() { + let ui = ui(); + let palette = palette(&ui, Interaction::Disabled, false); + let expected = interaction::disabled_content_over_role(&ui, Role::OnSurface, false); + assert_eq!(palette.headline, expected); + assert_eq!(palette.leading, expected); + assert_eq!(palette.trailing, expected); + assert_ne!( + palette.headline, + interaction::disabled_content_over_role(&ui, Role::OnSurfaceVariant, false), + "走默认的 OnSurfaceVariant 就会偏浅一档（这条钉住 A1 的角色）" + ); + assert!(palette.fill.is_none(), "禁用不叠状态层容器"); +} + +/// 选中态：`SecondaryContainer` + `OnSecondaryContainer`，trailing 是 `Primary`（4.8）。 +#[test] +fn selected_row_is_secondary_container() { + let ui = ui(); + let palette = palette(&ui, Interaction::Enabled, true); + assert_eq!(palette.fill, Some(ui.color(Role::SecondaryContainer))); + assert_eq!(palette.headline, ui.color(Role::OnSecondaryContainer)); + assert_eq!(palette.trailing, ui.color(Role::Primary), "4.8"); +} + +/// 4.7：hover / pressed 只叠状态层，**内容色不变**。 +#[test] +fn interaction_states_keep_the_content_colors() { + let ui = ui(); + let resting = palette(&ui, Interaction::Enabled, false); + for state in [ + Interaction::Hovered, + Interaction::Focused, + Interaction::Pressed, + ] { + let active = palette(&ui, state, false); + assert_eq!(active.headline, resting.headline, "{state:?} 不许改文本色"); + assert_eq!(active.leading, resting.leading, "{state:?} 不许改图标色"); + assert!(active.fill.is_some(), "{state:?} 必须叠状态层"); + } + assert_eq!(resting.fill, None, "静息态不叠状态层"); +} + +/// 三档行高与 `LM.row_height` 的关系**钉死**（有人按 A1 改回 56 时这里会红）。 +#[test] +fn heights_are_pinned_to_the_row_height_token() { + let ui = ui(); + let geometry = ListItemGeometry::of(&ui); + assert_eq!(geometry.heights[0], ui.metrics().row_height); + assert_eq!(geometry.heights, [44.0, 60.0, 76.0]); + assert_ne!( + geometry.heights[0], 56.0, + "56 是 A1 的值；本项目按 12b §4.1 取 44（改回去会破坏页面排版）" + ); +} + +/// 元素构造不 panic（`Element` 树的形状也一并过一遍）。 +#[test] +fn view_builds_a_tree() { + let ui = ui(); + let _: Element<'_, ()> = list_item( + &ui, + ListItem::new("Instances", ()) + .overline("RECENT") + .supporting("3 versions") + .leading(unlucky_design::icons::IconKind::Instances) + .trailing(unlucky_design::icons::IconKind::Settings) + .selected(), + ); + let _: Element<'_, ()> = list_item(&ui, ListItem::new("Logs", ()).disabled()); +} diff --git a/crates/app-iced/src/components/navigation/matrix.rs b/crates/app-iced/src/components/navigation/matrix.rs new file mode 100644 index 0000000..9efd37f --- /dev/null +++ b/crates/app-iced/src/components/navigation/matrix.rs @@ -0,0 +1,110 @@ +//! 导航家族的长文案取证块（D-M79-5）：**单行 + 裁切**，页面真接长实例名时不许折行。 +//! +//! 为什么不放在 `gallery/navigation.rs`：那个文件已经贴到 400 行红线（AGENTS.md §3-1）， +//! 而它属于 harness 单文件、scope 只授权一个路径。按 `selection::matrix` 的先例，把**取证块** +//! 收进组件目录、对消息类型泛型（`pressed: impl Fn() -> M`），gallery 只做一次 `.map`。 + +use iced::widget::{column, container, text}; +use iced::{Background, Element, Length}; + +use unlucky_design::color::Role; +use unlucky_design::icons::IconKind; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; + +use crate::theme::Ui; + +use super::{ + app_bar, list_item, navigation, tabs, AppBar, AppBarAction, ListItem, NavGroup, NavItem, + Navigation, Tab, Tabs, +}; + +/// 一行小字图例。 +fn note<'a, M: 'a>(ui: &'a Ui, value: &'a str) -> Element<'a, M> { + let style = ui.style(TypeRole::BodySmall); + text(value) + .size(style.size_px) + .font(ui.font_of(style)) + .color(ui.color(Role::OnSurfaceVariant)) + .into() +} + +/// 取景板（`SurfaceContainerLow`）：`Surface` 的页头与页面底色同色，要垫一层才量得到边界。 +fn plate<'a, M: 'a>(ui: &'a Ui, pad: f32, content: impl Into>) -> Element<'a, M> { + 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..68d2730 --- /dev/null +++ b/crates/app-iced/src/components/navigation/probe.rs @@ -0,0 +1,393 @@ +//! 渲染层几何断言：**对着真截图量像素**（M68 的教训——纯函数返回对，图可能是错的）。 +//! +//! ## 为什么自带一份最小读图器 +//! +//! `gallery::scan` 是 `pub(super)`（私有于 `gallery`），而 `gallery/mod.rs` 不在本 mission 的 scope 里， +//! 所以这里自带 ~60 行读图器（读 PNG / 取点 / 连通块 / 横带墨迹范围），判据全在本文件。 +//! 与 `inputs/probe.rs` 同一个处置（已作为 finding 报给 tower：建议把 `gallery::scan` 提升为 `pub(crate)`）。 +//! +//! ## 怎么跑（worktree 根目录） +//! +//! ```text +//! # ① 出 4 张图（每块一条命令，块选择器见 gallery/navigation.rs 的模块文档） +//! ULL_GALLERY_SECTION=navigation ULL_NAV_PART=list ./target/debug/unlucky-launcher-iced.exe \ +//! --software-renderer --screen=gallery --screenshot target/m79/list-light.png --screenshot-theme=light +//! # ② 量图 +//! ULL_NAV_DIR=target/m79 cargo test -p unlucky-app-iced navigation::probe +//! ``` +//! +//! 没给 `ULL_NAV_DIR` 就**大声跳过**（不静默通过），与 `gallery::probe` 的口径一致。 +//! +//! ## 量什么（每条都对着一个「已经画错过」的形态） +//! +//! | 断言 | 抓的错误 | +//! |---|---| +//! | ListItem 三行高 **44 / 60 / 76** | 抄 A1 的 56/72/88、或用内容撑高（行高被文本吃掉） | +//! | ListItem 禁用内容 = `OnSurface`@38% | 走 `disabled_colors()` 的默认 `OnSurfaceVariant` | +//! | Primary 指示条宽 = 选中项文本宽 + 2×16 | 条写成 `Fill`（= 整行宽，Q8 的另一面）或写死 | +//! | drawer **240** / rail **88**，药丸内缩 **12** / **16** | 药丸不贴边（Q8）、或两套组件各写死一个宽度 | +//! | AppBar **56** 高（静息 + 滚动） | 页头被内容撑高、或按 A1 改回 64 | + +use std::path::{Path, PathBuf}; + +use unlucky_design::color::{Role, SchemeFlavor}; +use unlucky_design::spacing::Space; + +use crate::app::components::interaction; + +mod divider; +mod long; +mod scan; +use scan::{rgb, ui as ui_of, BBox, Rgb, Shot}; + +/// 有这张图就读，没有就 `None`（深色档的可选覆盖用）。 +fn shot_opt(dir: &Path, part: &str, flavor: SchemeFlavor) -> Option { + 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, + Role::OnSurface, + false, + )); + let wrong = rgb(interaction::disabled_content_over_role( + &ui, + Role::OnSurfaceVariant, + false, + )); + let near = |a: Rgb, b: Rgb| { + a.iter() + .zip(b) + .all(|(x, y)| x.abs_diff(y) <= scan::TOLERANCE) + }; + assert!( + near(darkest, right), + "禁用内容最深像素是 {darkest:?}，A1 的 OnSurface@38% 是 {right:?}（用 OnSurfaceVariant 会得到 {wrong:?}）" + ); + assert!( + !near(darkest, wrong), + "禁用内容用了 OnSurfaceVariant@38%（{wrong:?}）而不是 A1 的 OnSurface@38%（{right:?}）" + ); + + eprintln!( + "[navigation::probe] list: 行高 {heights:?}，禁用最深像素 {darkest:?}（A1 = {right:?}）" + ); +} + +/// Tabs：Primary 指示条宽 = **选中项**文本宽 + 2×16（短/长文案各选中一次 → 两条宽度必须不同）。 +#[test] +fn tabs_indicator_tracks_the_selected_tab() { + let dir = require_dir!(); + let ui = ui_of(SchemeFlavor::Light); + let shot = shot(&dir, "tabs", SchemeFlavor::Light); + + let primary = rgb(ui.color(Role::Primary)); + let surface = rgb(ui.color(Role::Surface)); + // 指示条：3px 高、宽 ≥ 40 的 `Primary` 块（选中项的标签是同色，但笔画块远小于 40 宽） + let mut bars: Vec = 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..a89d683 --- /dev/null +++ b/crates/app-iced/src/components/navigation/tabs.rs @@ -0,0 +1,359 @@ +//! Tabs（`research/12b` §6）：**Primary**（下方 3px 指示条）与 **Secondary**（1px 分隔线）。 +//! +//! ## 参考值（`[源]` = A1，本轮 `javap` 实读本机 AAR） +//! +//! ```text +//! PrimaryNavigationTabTokens: ContainerHeight 48、IconAndLabelTextContainerHeight 64、 +//! ActiveIndicatorHeight 3、ActiveIndicatorShape RoundedCornerShape(3dp)、 +//! IconSize 24、ContainerShape CornerNone、LabelTextFont TitleSmall +//! ActiveIndicatorColor=Primary；Active*/Inactive* 各态内容色（见下表） +//! SecondaryNavigationTabTokens: ContainerHeight 48、DividerHeight、DividerColor=SurfaceVariant、 +//! ActiveLabelTextColor=OnSurface、InactiveLabelTextColor=OnSurfaceVariant +//! ``` +//! +//! | 项 | Primary | Secondary | +//! |---|---|---| +//! | 选中内容色 | **`Primary`** | **`OnSurface`**（不是 Primary——6.5 明写） | +//! | 未选内容色 | `OnSurfaceVariant` | `OnSurfaceVariant` | +//! | hover / focus / pressed | 未选项提到 **`OnSurface`**，选中项保持不变 | 同左 | +//! | 底部条 | 仅选中项：**3px `Primary`**，宽度**跟随该 tab** | 所有项：**1px `SurfaceVariant`**（连成一条线） | +//! +//! 尺寸/圆角/线厚全部来自 [`TabsGeometry`]（**G22/G23**：`LayoutMetrics` 没有 Tabs 档）。 +//! +//! ## 指示条怎么做到「宽度跟随选中项」 +//! +//! iced 没有「取到渲染后文本宽度」的公开 API，所以这里用 [`stack`] 的**分层语义**： +//! +//! 1. `Stack` 的**底层**是 tab 自己的内容容器（`Length::Shrink` → 宽度 = 文本实测宽 + 2×16）； +//! 2. `Stack` 的**上层**是 `Length::Fill` 的指示条。`Stack::layout` 先按**底层**定尺寸，再用 +//! 「已知尺寸」的 `Limits` 布局其余层（`iced_widget-0.14.2/src/stack.rs` 的 +//! `size = limits.resolve(self.width, self.height, base.size())`）——于是 Fill 的指示条 +//! 拿到的正好是「这个 tab 的宽」，**不是**整行宽。 +//! +//! 这也顺带避开 Q8 的另一面：把条写成 `center_x(Fill)` 会把它撑成整行。 +//! +//! ## 横向滚动 +//! +//! 整行外面套 `scrollable`（`Direction::Horizontal`，滚动条 `Scrollbar::hidden()`）： +//! tab 宽度因此是**内容宽**而不是「行宽 ÷ n」——官方 `ScrollableTabRow` 的口径。 +//! `TabMinWidth = 90` **本轮不施加**（iced 无 min-width，登记在 G23）。 + +use iced::widget::text::{LineHeight, Wrapping}; +use iced::widget::{button, container, scrollable, space, text, Row, Stack}; +use iced::{Alignment, Background, Border, Color, Element, Length, Padding, Pixels, Shadow}; + +use unlucky_design::color::Role; +use unlucky_design::icons::IconKind; +use unlucky_design::shape::ShapeScale; +use unlucky_design::typography::TypeRole; + +use crate::icons; +use crate::theme::Ui; + +use super::super::interaction::{self, Interaction}; +use super::super::layout; +use super::geometry::{TabsGeometry, TABS_ICON_HEIGHT}; + +/// 两种 Tabs（`research/12b` §6；M3 的 `PrimaryTabRow` / `SecondaryTabRow`）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +pub enum TabsVariant { + /// 主标签页：选中项下方 3px `Primary` 指示条。 + Primary, + /// 次标签页：1px `SurfaceVariant` 分隔线 + 选中项 `OnSurface` 文字。 + Secondary, +} + +impl TabsVariant { + /// 两种变体（gallery 状态矩阵按这个次序出图）。 + pub const ALL: [TabsVariant; 2] = [TabsVariant::Primary, TabsVariant::Secondary]; + + /// 稳定名字（截图文件名 / 图例用）。 + pub const fn name(self) -> &'static str { + match self { + TabsVariant::Primary => "primary", + TabsVariant::Secondary => "secondary", + } + } + + /// 是否是 Primary（指示条 3px）。 + pub const fn is_primary(self) -> bool { + matches!(self, TabsVariant::Primary) + } +} + +/// 一个标签页。 +#[derive(Debug, Clone)] +pub struct Tab<'a, M> { + label: &'a str, + icon: Option, + 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>, +} + +impl<'a, M> Tabs<'a, M> { + /// Primary tabs（3px 指示条）。 + pub fn primary() -> Self { + Self { + variant: TabsVariant::Primary, + tabs: Vec::new(), + } + } + + /// Secondary tabs（1px 分隔线）。 + pub fn secondary() -> Self { + Self { + variant: TabsVariant::Secondary, + tabs: Vec::new(), + } + } + + /// 追加一个 tab。 + pub fn tab(mut self, tab: Tab<'a, M>) -> Self { + self.tabs.push(tab); + self + } +} + +/// 一个 tab 的内容色（A1 的 `Active*` / `Inactive*` / 各态表，见模块文档）。 +fn content_color(ui: &Ui, primary: bool, state: Interaction, selected: bool) -> Color { + if state.is_disabled() { + // A1 的 Tabs 没有 Disabled* token（实读：Primary/Secondary 两套都只有 Active/Inactive × 四态）， + // 按 ListItem 的 38% 口径处理 —— 登记 `[估]`。 + return interaction::disabled_content_over_role(ui, Role::OnSurface, false); + } + if selected { + // 6.5：Primary 选中 `Primary`；Secondary 选中 `OnSurface` + return if primary { + ui.color(Role::Primary) + } else { + ui.color(Role::OnSurface) + }; + } + match state { + // 未选中静息 `OnSurfaceVariant`；hover/focus/pressed 提到 `OnSurface`（A1 的 Inactive* 四态） + Interaction::Enabled => ui.color(Role::OnSurfaceVariant), + _ => ui.color(Role::OnSurface), + } +} + +/// Primary 指示条的颜色（只有选中项有；禁用项降档，否则「点不动却亮着」）。 +fn bar_color(ui: &Ui, state: Interaction, selected: bool) -> Option { + if !selected { + return None; + } + if state.is_disabled() { + return Some(interaction::disabled_content_over_role( + ui, + Role::OnSurface, + false, + )); + } + Some(ui.color(Role::Primary)) +} + +/// 6.6：Secondary 的分隔线色 = **`SurfaceVariant`**（不是 `OutlineVariant`——那是 §22 的分隔线）。 +/// +/// 色值只在这里出现一次：整行那条线与逐 tab 的实现都从这里取。 +fn secondary_line_color(ui: &Ui) -> Color { + ui.color(Role::SurfaceVariant) +} + +/// 一行标签页（自带横向滚动）。 +pub fn tabs<'a, M: Clone + 'a>(ui: &'a Ui, tabs: Tabs<'a, M>) -> Element<'a, M> { + let geometry = TabsGeometry::of(ui); + let primary = tabs.variant.is_primary(); + // 6.1：带图标时容器高 **64**（`IconAndLabelTextContainerHeight`），纯文字 48 + let height = if tabs.tabs.iter().any(|tab| tab.icon.is_some()) { + TABS_ICON_HEIGHT + } else { + geometry.height + }; + + let mut row = Row::new() + .height(Length::Fixed(height)) + .align_y(Alignment::Center); + for tab in tabs.tabs { + row = row.push(tab_cell(ui, tab, geometry, primary, height)); + } + + let body: Element<'a, M> = if primary { + row.into() + } else { + // A1 的 Secondary 分隔线是**整行一条直线**，不是每个 tab 一段： + // 逐段画会在相邻段之间留缝（视觉 r1 P2-2）。这里用 `Stack` 把一条 Fill 线压在整行底下， + // 底座是 tab 行本身（Shrink → 内容宽），所以线长 = tab 行总宽，横向滚动时跟着走。 + let line = container(space::vertical()) + .width(Length::Fill) + .height(Length::Fixed(geometry.secondary_bar)) + .style(move |_theme| container::Style { + background: Some(Background::Color(secondary_line_color(ui))), + ..container::Style::default() + }); + Stack::new() + .push(container(row)) + .push( + container(line) + .width(Length::Fill) + .height(Length::Fill) + .align_y(Alignment::End), + ) + .into() + }; + + scrollable(body) + .direction(scrollable::Direction::Horizontal( + scrollable::Scrollbar::hidden(), + )) + .height(Length::Fixed(height)) + .into() +} + +/// 一个 tab 单元（内容 + 底部条）。 +fn tab_cell<'a, M: Clone + 'a>( + ui: &'a Ui, + tab: Tab<'a, M>, + geometry: TabsGeometry, + primary: bool, + height: f32, +) -> Element<'a, M> { + let forced = tab.state.or(if tab.on_press.is_none() { + Some(Interaction::Disabled) + } else { + None + }); + let state = forced.unwrap_or(Interaction::Enabled); + let selected = tab.selected; + let color = content_color(ui, primary, state, selected); + let style = ui.style(TypeRole::TitleSmall); + + let label = text(tab.label) + .size(style.size_px) + .line_height(LineHeight::Absolute(Pixels(style.line_height_px))) + // 单行（容器高固定 48/64）：长标签让 tab 变宽 + 横向滚动，不折行（偏离 D-M79-5） + .wrapping(Wrapping::None) + .font(ui.font_of(style)) + .color(color); + + let mut content = Row::new().align_y(Alignment::Center).spacing(geometry.pad); + if let Some(kind) = tab.icon { + content = content.push(layout::fixed( + geometry.icon, + geometry.icon, + icons::view::(kind, color), + )); + } + content = content.push(label); + + let bar_height = geometry.bar(primary); + // 底层：内容自己决定宽度（Shrink），底部留出条的高度 —— 未选中的 Primary tab 也占同样的高 + let base = container(content) + .height(Length::Fixed(height)) + // Q21：要给居中就两轴都显式给（`Container` 默认 Left/Top） + .align_x(Alignment::Center) + .align_y(Alignment::Center) + .padding(Padding { + top: 0.0, + right: geometry.pad, + bottom: bar_height, + left: geometry.pad, + }); + + // Primary：逐 tab 画条（要跟随该 tab 的宽度）；Secondary：整行一条，在 `tabs()` 里画 + let bar = if primary { + bar_color(ui, state, selected) + } else { + None + }; + let radius = geometry.indicator_radius(); + let mut stack = Stack::new().push(base); + if let Some(color) = bar { + // 上层：Fill —— `Stack` 先按底层定尺寸，所以这里的 Fill = 这个 tab 的宽（不是整行） + stack = stack.push( + container( + container(space::vertical()) + .width(Length::Fill) + .height(Length::Fixed(bar_height)) + .style(move |_theme| container::Style { + background: Some(Background::Color(color)), + border: Border { + radius, + ..Border::default() + }, + ..container::Style::default() + }), + ) + .width(Length::Fill) + .height(Length::Fill) + .align_y(Alignment::End), + ); + } + + let fill = interaction::overlay_color(ui, state, Role::OnSurface, Role::Surface); + let button = button(stack) + .height(Length::Fixed(height)) + .padding(0) + .style(move |_theme, _status| button::Style { + background: fill.map(Background::Color), + text_color: color, + // ContainerShape = CornerNone（tab 本身是直角；圆角只在指示条上） + border: Border { + radius: ui.radius_dp(ShapeScale::None), + ..Border::default() + }, + shadow: Shadow::default(), + snap: true, + }); + + match tab.on_press { + Some(message) => button.on_press(message).into(), + None => button.into(), + } +} + +#[cfg(test)] +mod tests; diff --git a/crates/app-iced/src/components/navigation/tabs/tests.rs b/crates/app-iced/src/components/navigation/tabs/tests.rs new file mode 100644 index 0000000..0446961 --- /dev/null +++ b/crates/app-iced/src/components/navigation/tabs/tests.rs @@ -0,0 +1,150 @@ +//! `tabs` 的单元测试（split 拆出来的：单文件 ≤400 行，AGENTS.md §3-1）。 + +use super::*; + +use unlucky_design::color::SchemeFlavor; +use unlucky_design::typography::Platform; + +use crate::theme::Families; + +use super::super::super::interaction; + +fn ui() -> Ui { + Ui::with_platform( + SchemeFlavor::Light, + Platform::Windows, + Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", + }, + ) +} + +/// 6.5：选中色 Primary 用 `Primary`，Secondary 用 `OnSurface`（**不是** Primary）。 +#[test] +fn active_colors_follow_the_variant() { + let ui = ui(); + assert_eq!( + content_color(&ui, true, Interaction::Enabled, true), + ui.color(Role::Primary) + ); + assert_eq!( + content_color(&ui, false, Interaction::Enabled, true), + ui.color(Role::OnSurface), + "6.5：Secondary 的选中项是 OnSurface" + ); + assert_ne!( + content_color(&ui, false, Interaction::Enabled, true), + ui.color(Role::Primary), + "把 Secondary 的选中色写成 Primary 是最常见的串线" + ); +} + +/// 未选中静息 `OnSurfaceVariant`；hover / focus / pressed 提到 `OnSurface`。 +#[test] +fn inactive_states_lift_to_on_surface() { + let ui = ui(); + for primary in [true, false] { + assert_eq!( + content_color(&ui, primary, Interaction::Enabled, false), + ui.color(Role::OnSurfaceVariant) + ); + for state in [ + Interaction::Hovered, + Interaction::Focused, + Interaction::Pressed, + ] { + assert_eq!( + content_color(&ui, primary, state, false), + ui.color(Role::OnSurface), + "{state:?} 必须提到 OnSurface" + ); + } + } +} + +/// 6.2：Primary 只有选中项有 3px `Primary` 条；禁用项降档。 +#[test] +fn primary_bar_only_on_the_selected_tab() { + let ui = ui(); + assert_eq!(bar_color(&ui, Interaction::Enabled, false), None); + assert_eq!( + bar_color(&ui, Interaction::Enabled, true), + Some(ui.color(Role::Primary)) + ); + assert_eq!( + bar_color(&ui, Interaction::Disabled, true), + Some(interaction::disabled_content_over_role( + &ui, + Role::OnSurface, + false + )), + "禁用项「点不动却亮着」是错的" + ); +} + +/// 6.6：Secondary 的分隔线整行一条，颜色 `SurfaceVariant`（不是 §22 的 `OutlineVariant`）。 +#[test] +fn secondary_line_is_surface_variant() { + let ui = ui(); + assert_eq!(secondary_line_color(&ui), ui.color(Role::SurfaceVariant)); + assert_ne!( + secondary_line_color(&ui), + ui.color(Role::OutlineVariant), + "OutlineVariant 是 §22 分隔线的角色，Tabs 不用它" + ); +} + +/// 禁用是**修饰器**：只清消息，label / 选中态 / 图标全部保留。 +#[test] +fn disabled_only_clears_the_message() { + let tab = Tab::new("Mods", ()) + .icon(unlucky_design::icons::IconKind::Settings) + .selected() + .disabled(); + assert!(tab.on_press.is_none()); + assert!(tab.icon.is_some()); + assert!(tab.selected); + assert_eq!(tab.label, "Mods"); +} + +/// 指示条宽度 = tab 宽 = 文本宽 + 2×16（这条是「跟随选中项宽度」的公式面）。 +#[test] +fn indicator_width_is_the_tab_width() { + let geometry = TabsGeometry::of(&ui()); + let tab_width = |text_width: f32| text_width + geometry.pad * 2.0; + assert_eq!(tab_width(0.0), 32.0, "空文本 = 2×16"); + // 两段不同长度的文案 ⇒ 指示条宽度必然不同（渲染层断言用它打红） + let short = tab_width(40.0); + let long = tab_width(120.0); + assert_eq!(long - short, 80.0); + assert!(long > short); +} + +/// 6.1：带图标的 Tabs 容器高 64（`IconAndLabelTextContainerHeight`），纯文字 48。 +#[test] +fn icon_tabs_use_the_taller_container() { + let ui = ui(); + assert_eq!(TABS_ICON_HEIGHT, 64.0); + assert!(TABS_ICON_HEIGHT > TabsGeometry::of(&ui).height); +} + +/// 3 个 tab 的树能建出来（含选中 / 禁用 / 带图标三条路径）。 +#[test] +fn view_builds_a_tree() { + let ui = ui(); + let _: Element<'_, ()> = tabs( + &ui, + Tabs::primary() + .tab(Tab::new("General", ()).selected()) + .tab(Tab::new("Mods", ()).icon(unlucky_design::icons::IconKind::Settings)) + .tab(Tab::new("Logs", ()).disabled()), + ); + let _: Element<'_, ()> = tabs( + &ui, + Tabs::secondary() + .tab(Tab::new("Release", ()).selected()) + .tab(Tab::new("Snapshot", ())), + ); +} diff --git a/crates/app-iced/src/components/selection/checkbox.rs b/crates/app-iced/src/components/selection/checkbox.rs new file mode 100644 index 0000000..41a7d69 --- /dev/null +++ b/crates/app-iced/src/components/selection/checkbox.rs @@ -0,0 +1,186 @@ +//! Checkbox（`research/15` §18）：20×20 / 圆角 2 / 描边向内收的 2px 框 / 勾形 12dp 方头 / +//! indeterminate 形变为居中短横 / Ø40 状态层 / 48 命中区。 +//! +//! ## 三条容易画错的（每条都有对应的像素断言或单测） +//! +//! 1. **描边向内**：外缘恒 20（§18.3）。iced 的 quad 渲染器把描边路径**向内缩半个线宽** +//! （`iced_tiny_skia::engine::draw_quad`：`border_bounds + border_width / 2`），与 Compose +//! `drawBox` 的 `topLeft = stroke/2, size = 20 − stroke` 同一口径，所以选中/未选中外缘同尺寸。 +//! 2. **勾不是图标**：勾形按路径比例画（`shell::glyph`），代码里**没有第二个 `IconKind`**（§18.6）。 +//! 3. **状态层是 Ø40 的圆**、命中区是 48：两者不同尺寸，所以外壳是透明的 48 按钮， +//! 里面套一个 40 的圆容器，再套 20 的方框（见 `shell` 的模块文档）。 + +use iced::widget::{container, row, text}; +use iced::{Alignment, Element, Length, Padding}; + +use unlucky_design::typography::TypeRole; + +use crate::theme::Ui; + +use super::super::interaction::Interaction; +use super::geometry::ControlGeometry; +use super::paint::{self, Frame}; +use super::shell::{self, StateSource}; + +/// 复选框的三种取值（§18.6：indeterminate 不是第四种「选中」，是「部分选中」）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum CheckValue { + /// 未选中：透明内部 + 2px `OnSurfaceVariant` 描边。 + Unchecked, + /// 选中：`Primary` 实心 + 勾。 + Checked, + /// 部分选中：**同样是实心**，勾形变成一条居中短横（不换图标）。 + Indeterminate, +} + +impl CheckValue { + /// 框是否**填充**（选中与 indeterminate 都填，后者只是把勾换成短横）。 + pub const fn filled(self) -> bool { + !matches!(self, CheckValue::Unchecked) + } + + /// 是否要画短横而不是勾。 + pub const fn indeterminate(self) -> bool { + matches!(self, CheckValue::Indeterminate) + } +} + +/// 一个复选框（框 + 可选标签；`on_toggle` 为 `None` = 禁用）。 +#[derive(Debug, Clone)] +pub struct Checkbox<'a, M> { + label: &'a str, + value: CheckValue, + on_toggle: Option, + error: bool, + state: Option, +} + +impl<'a, M> Checkbox<'a, M> { + /// 一个二态复选框。 + pub fn new(label: &'a str, selected: bool, on_toggle: M) -> Self { + Self::tri( + label, + if selected { + CheckValue::Checked + } else { + CheckValue::Unchecked + }, + on_toggle, + ) + } + + /// 三态复选框（`indeterminate` 由调用方给值）。 + pub fn tri(label: &'a str, value: CheckValue, on_toggle: M) -> Self { + Self { + label, + value, + on_toggle: Some(on_toggle), + error: false, + state: None, + } + } + + /// 禁用的复选框（无消息；禁用不是「另一种颜色」，见 `paint::checkbox` 的禁用分支）。 + pub fn disabled(label: &'a str, value: CheckValue) -> Self { + Self { + label, + value, + on_toggle: None, + error: false, + state: None, + } + } + + /// 校验失败态（§18.7：未选中描边 `Error`，选中填 `Error` + 勾 `OnError`）。 + pub fn error(mut self) -> Self { + self.error = true; + self + } + + /// 强制视觉态（`--screen=gallery` 取证用；运行期不要调）。 + pub fn state(mut self, state: Interaction) -> Self { + self.state = Some(state); + self + } +} + +/// 画一个复选框（框 + 标签）。 +pub fn checkbox<'a, M: Clone + 'a>(ui: &'a Ui, spec: Checkbox<'a, M>) -> Element<'a, M> { + let geometry = ControlGeometry::checkbox(ui); + let filled = spec.value.filled(); + let indeterminate = spec.value.indeterminate(); + let error = spec.error; + let radius = geometry.radius; + let stroke = geometry.stroke; + let source = StateSource::new(spec.state, spec.on_toggle.is_some()); + + // 勾的颜色与 hover/pressed 无关（A1：`SelectedHover/Focus/PressedIconColor` 都是 `OnPrimary`）， + // 只随「选中 + 禁用」变 —— 所以这里用**静态**态求值（SVG 的颜色在构建期就要定）。 + let at_rest = paint::checkbox(ui, filled, error, source.get(), radius, stroke); + let glyph: Element<'a, M> = if filled { + shell::square( + geometry.side, + shell::glyph(geometry, indeterminate, at_rest.glyph), + ) + } else { + iced::widget::Space::new().into() + }; + + // 20 方框：填/描边（跟态走）+ 勾 + let boxed = container(glyph) + .width(Length::Fixed(geometry.side)) + .height(Length::Fixed(geometry.side)) + .style(source.container_style(move |state| { + paint::checkbox(ui, filled, error, state, radius, stroke) + .frame + .container_style() + })); + + // Ø40 状态层：圆（半径 = 直径/2，`ShapeScale::Full` 的等价写法） + let layer_side = geometry.state_layer; + let layer = container(boxed) + .width(Length::Fixed(layer_side)) + .height(Length::Fixed(layer_side)) + .align_x(Alignment::Center) + .align_y(Alignment::Center) + .style(source.container_style(move |state| { + Frame { + fill: paint::state_layer(ui, state, paint::checkbox_layer_role(filled, error)), + outline: None, + stroke: 0.0, + radius: layer_side / 2.0, + } + .container_style() + })); + + let mut content = row![layer].align_y(Alignment::Center).spacing(geometry.gap); + if !spec.label.is_empty() { + let style = ui.style(TypeRole::BodyLarge); + content = content.push( + text(spec.label) + .size(style.size_px) + .font(ui.font_of(style)) + .color(paint::label(ui, source.get())), + ); + } + + // 命中区 48：方框 20 + 状态层 40 都在里面垂直居中； + // 左右各留 `hit_padding` 透明内边距，无标签时命中区也是 48×48（复审 P2-2） + let pad = geometry.hit_padding(); + let body = container(content) + .height(Length::Fill) + .align_y(Alignment::Center) + .padding(Padding { + left: pad, + right: pad, + ..Padding::default() + }); + + shell::shell( + &source, + Length::Shrink, + Length::Fixed(geometry.hit), + spec.on_toggle, + body.into(), + ) +} diff --git a/crates/app-iced/src/components/selection/chip.rs b/crates/app-iced/src/components/selection/chip.rs new file mode 100644 index 0000000..e84353d --- /dev/null +++ b/crates/app-iced/src/components/selection/chip.rs @@ -0,0 +1,187 @@ +//! Chip（`research/12b` §13）：高 **32** / 圆角 **8** / 水平内边距 **8** / 元素间距 **8** / +//! 图标 **18**（`IconSize::Button` = 官方 `AssistChipTokens.IconSize`）/ 描边 1px `OutlineVariant`。 +//! +//! ## 三类（§13 的 Assist / Filter / Input） +//! +//! | 类 | 选中态 | 容器 | 文字 | 前置图标 | +//! |---|---|---|---|---| +//! | Assist | **无**（一次动作，不是开关） | 透明 + 1px 描边 | `OnSurface` | `Primary` | +//! | Filter | 有 | 未选透明+描边；选中 `SecondaryContainer` **无描边** | `OnSurfaceVariant` / `OnSecondaryContainer` | 选中态才给勾 | +//! | Input | 有 | 同 Filter | 同 Filter | 可给 + 后置关闭图标 | +//! +//! ## 为什么 Chip 不用 `selection::shell` 那条透明外壳 +//! +//! M3 的 chip **没有圆形状态层**：hover / pressed 就是把状态层叠在**自己的容器**上， +//! 而容器尺寸 = 命中区尺寸。所以 chip 直接走 `button` 的样式闭包（与按钮家族同一条产线）， +//! 不需要「48 外壳 + 40 圆」那套。 + +use iced::widget::{button, container, row, text}; +use iced::{Alignment, Background, Border, Element, Length, Padding, Shadow}; + +use unlucky_design::icons::IconKind; +use unlucky_design::typography::TypeRole; + +use crate::icons; +use crate::theme::Ui; + +use super::super::interaction::Interaction; +use super::geometry::ChipGeometry; +use super::paint::{self, ChipVariant}; + +/// 一个 chip（可带前后图标；`on_press` 为 `None` = 禁用）。 +#[derive(Debug, Clone)] +pub struct Chip<'a, M> { + label: &'a str, + variant: ChipVariant, + selected: bool, + leading: Option, + trailing: Option, + on_press: Option, + state: Option, +} + +impl<'a, M> Chip<'a, M> { + /// Assist chip：辅助动作，**没有**选中态。 + pub fn assist(label: &'a str, on_press: M) -> Self { + Self::new(label, ChipVariant::Assist, false, on_press) + } + + /// Filter chip：筛选开关（`selected` 决定容器是否 `SecondaryContainer`）。 + pub fn filter(label: &'a str, selected: bool, on_press: M) -> Self { + Self::new(label, ChipVariant::Filter, selected, on_press) + } + + /// Input chip：用户输入的实体（可选中 + 可带关闭图标）。 + pub fn input(label: &'a str, on_press: M) -> Self { + Self::new(label, ChipVariant::Input, false, on_press) + } + + /// 转成禁用：**只清消息**，图标 / 选中态 / 状态层全部保留（复审 P2-1）。 + /// + /// 官方禁用态是「容器/描边 12%、文字与**图标** 38%」——只降**不删**。早先的 + /// `Chip::disabled(label, variant)` 把 leading / trailing / selected 一起丢掉，实测 + /// assist 78→54、filter·on 74→50（连填充和勾都没了），禁用列里 `filter·on` 与 `filter` + /// 逐像素同形，看不出选中与否。 + pub fn disabled(mut self) -> Self { + self.on_press = None; + self + } + + fn new(label: &'a str, variant: ChipVariant, selected: bool, on_press: M) -> Self { + Self { + label, + variant, + selected, + leading: None, + trailing: None, + on_press: Some(on_press), + state: None, + } + } + + /// 前置图标（Assist / Filter 用）。 + pub fn leading(mut self, kind: IconKind) -> Self { + self.leading = Some(kind); + self + } + + /// 后置图标（Input chip 的关闭键）。 + pub fn trailing(mut self, kind: IconKind) -> Self { + self.trailing = Some(kind); + self + } + + /// 强制视觉态（gallery 取证用；运行期不要调）。 + pub fn state(mut self, state: Interaction) -> Self { + self.state = Some(state); + self + } +} + +/// 画一个 chip。 +pub fn chip<'a, M: Clone + 'a>(ui: &'a Ui, spec: Chip<'a, M>) -> Element<'a, M> { + let geometry = ChipGeometry::of(ui); + let variant = spec.variant; + let selected = spec.selected; + let disabled = spec.on_press.is_none(); + let forced = spec.state; + + // 文字/图标色只看「选中 + 禁用」（A1：Filter/Input 的 label 色在 hover/focus/pressed 不变）， + // 所以这里静态求值；容器（含状态层）在样式闭包里跟态走。 + let at_rest = paint::chip( + ui, + variant, + selected, + if disabled { + Interaction::Disabled + } else { + forced.unwrap_or(Interaction::Enabled) + }, + geometry.radius, + ); + + let mut content = row![].align_y(Alignment::Center).spacing(geometry.gap); + if let Some(kind) = spec.leading { + // Q9：图标一律经固定尺寸容器；盒 18 ≠ RENDER_PX(24)，所以必须走 `view_at` 按 18 烘焙， + // 否则线宽会被布局缩水（复审 r1 P2-2）。 + content = content.push(super::super::layout::centered_fixed( + geometry.icon, + geometry.icon, + icons::view_at::(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| { + let state = forced.unwrap_or_else(|| Interaction::from_status(status)); + let paint = paint::chip(ui, variant, selected, state, geometry.radius); + button::Style { + background: paint.frame.fill.map(Background::Color), + text_color: paint.label, + border: Border { + color: paint.frame.outline.unwrap_or(iced::Color::TRANSPARENT), + width: if paint.frame.outline.is_some() { + paint.frame.stroke + } else { + 0.0 + }, + radius: iced::border::Radius::new(paint.frame.radius), + }, + shadow: Shadow::default(), + snap: true, + } + }); + + match spec.on_press { + Some(message) => element.on_press(message).into(), + None => element.into(), + } +} diff --git a/crates/app-iced/src/components/selection/geometry.rs b/crates/app-iced/src/components/selection/geometry.rs new file mode 100644 index 0000000..3a6656e --- /dev/null +++ b/crates/app-iced/src/components/selection/geometry.rs @@ -0,0 +1,259 @@ +//! 选择类家族的**几何**：值要么来自令牌，要么在此登记 G 编号（不散落在组件里）。 +//! +//! ## 参考值 → 落点 +//! +//! | # | 量 | 参考值 | 来源 | 落点 | +//! |---|---|---|---|---| +//! | 18.1 | Checkbox 外框 / 圆角 | **20×20** / **2** | `[源]` `Checkbox.kt:737-738`（`COMPONENT_WIDTH/HEIGHT=18` 是死值，见 §26.2） | `Component::Checkbox.metrics()` + `ComponentRadius::Micro` | +//! | 18.2 | Checkbox 描边 | **2**（选中时 0） | `[源]` `UnselectedOutlineWidth` | `ComponentMetrics::CHECKBOX.stroke` | +//! | 18.5 | Checkbox 状态层 | **Ø40** | `[源]` `StateLayerSize` | `ComponentMetrics::CHECKBOX.state_layer` | +//! | 18.9 | 命中区 / 标签间距 | **48** / **8** | `[源]` `minimumInteractiveComponentSize` / 间距 `[估]` | `LayoutMetrics::touch_target` / `metrics.gap` | +//! | 19.1 | Radio 外圈 / 环线 | **20** / **2** | `[源]` `IconSize` / `RadioStrokeWidth` | `Component::Radio.metrics()` | +//! | 19.2 | Radio 内点 | **10**（不是 12） | `[源]` `DotSize=12`，绘制半径 12/2−2/2=5 | `ComponentMetrics::RADIO.inner_dot` | +//! | 10.1 | Switch 轨道 | **52×32**，圆角 full(16) | `[源]` `TrackWidth/TrackHeight/TrackShape` | [`SwitchGeometry`]（**G16**） | +//! | 10.2 | Switch 滑块 | 选中 **24** / 未选 **16** / 按下 **28** | `[源]` `Selected/Unselected/PressedHandleWidth` | [`SwitchGeometry`]（**G16**） | +//! | 13.1 | Chip 高 / 圆角 | **32** / **8** | `[源]` `ContainerHeight` / `ContainerShape=CornerSmall` | `Space::X8` + `Component::Chip.spec().shape` | +//! +//! **G16 登记**（续 `research/15` §25 的 G13）：`ComponentMetrics` 只有 +//! `CHECKBOX/RADIO/SEARCH_BAR/NAVIGATION_DRAWER` 四组，**Switch 与 Chip 没有落点**。 +//! 本文件把它们的量收成命名常量（每个都带 A1 出处），等令牌层补 +//! `ComponentMetrics::SWITCH/CHIP` 后整段删除、改走 `Component::Switch.metrics()`。 +//! +//! **G14 已收口（M86）**：Chip 图标取 `IconSize::Button` = **18**（AAR `AssistChipTokens.IconSize = +//! 18.0d`，与 12b 13.4 同值），不再是偏离。Switch 滑块内的图标是**另一个值 16** +//! （`SwitchTokens.SelectedIconSize / UnselectedIconSize = 16.0d`），所以走 `IconSize::SwitchThumb`： +//! 两者在官方就是两个 token，别为了省一个档位把它们合成一个。 + +use unlucky_design::component_map::{Component, ComponentMetrics}; +use unlucky_design::icons::IconSize; +use unlucky_design::spacing::Space; + +use crate::theme::Ui; + +/// Switch 轨道宽（`SwitchTokens.TrackWidth = 52.0`，**G16**：令牌层无此档）。 +const SWITCH_TRACK_WIDTH: f32 = 52.0; +/// Switch 轨道描边（`SwitchTokens.TrackOutlineWidth = 2.0`，**G16**）。 +const SWITCH_TRACK_STROKE: f32 = 2.0; +/// Switch 选中态滑块（`SwitchTokens.SelectedHandleWidth = 24.0`，**G16**）。 +const SWITCH_THUMB_SELECTED: f32 = 24.0; +/// Switch 未选中态滑块（`SwitchTokens.UnselectedHandleWidth = 16.0`，**G16**）。 +const SWITCH_THUMB_UNSELECTED: f32 = 16.0; +/// Switch 按下态滑块（`SwitchTokens.PressedHandleWidth = 28.0`，**G16**）。 +const SWITCH_THUMB_PRESSED: f32 = 28.0; +/// Switch 状态层（`SwitchTokens.StateLayerSize = 40.0`，**G16**；与 Checkbox 同值）。 +const SWITCH_STATE_LAYER: f32 = 40.0; + +/// Checkbox / Radio 共用的方框几何（两控件同尺寸、不同形状语言，§18 / §19）。 +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct ControlGeometry { + /// 可见外框边长（20）。 + pub side: f32, + /// 描边 / 环线宽度（2；**禁用态不变细**，§18.8）。 + pub stroke: f32, + /// 状态层圆的直径（40）。 + pub state_layer: f32, + /// 最小命中区（48，`LayoutMetrics::touch_target`）。 + pub hit: f32, + /// 框 ↔ 标签间距（8，团队口径 `[估]`）。 + pub gap: f32, + /// 圆角半径：Checkbox = 2（`ComponentRadius::Micro`），Radio = 10（`ShapeScale::Full` 的真圆）。 + pub radius: f32, + /// Radio 内点直径（10）；Checkbox 为 0（没有内点）。 + pub inner_dot: f32, +} + +impl ControlGeometry { + /// Checkbox：20×20 / 圆角 2 / 描边 2 / 状态层 Ø40（全部 `[源]`，见模块表）。 + pub fn checkbox(ui: &Ui) -> Self { + let metrics = metrics(Component::Checkbox); + Self { + side: metrics.width, + stroke: metrics.stroke, + state_layer: metrics.state_layer, + hit: ui.metrics().touch_target, + gap: metrics.gap, + // 微控件层（D32）：2dp 不在 `ShapeScale` 刻度里，只能走 `ComponentRadius`。 + // 传 20 拿不到值说明有人把它挪到容器层了——那是 D32 违规，`unwrap_or` 会悄悄 + // 变成直角，所以这里用 `expect` 直接炸（比图画错好查）。 + radius: metrics + .radius + .expect("Checkbox 的圆角必须在微控件层（ComponentSpec::micro_radius）") + .radius_px(metrics.width) + .expect("Checkbox 20dp ≤ 微控件上限 24dp"), + // Checkbox 没有内点（内点是 radio 的语言，§19.6 明令两者不许混用） + inner_dot: metrics.inner_dot, + } + } + + /// Radio：20 / 环线 2 / 内点 10 / 状态层 Ø40；圆角是**真圆**（`ShapeScale::Full`）。 + pub fn radio(ui: &Ui) -> Self { + let metrics = metrics(Component::Radio); + Self { + side: metrics.width, + stroke: metrics.stroke, + state_layer: metrics.state_layer, + hit: ui.metrics().touch_target, + gap: metrics.gap, + radius: Component::Radio.spec().shape.radius_px(metrics.width), + // 内点 **10 不是 12**（§19.2：12 是含描边前的名义值，绘制半径 = 12/2 − 2/2 = 5） + inner_dot: metrics.inner_dot, + } + } + + /// 命中区比可见状态层宽出来的部分（左右**各一份**）：`(48 − 40) / 2 = 4`。 + /// + /// 无标签时行宽只有状态层的 40dp，命中区就少 8dp；A1 的 + /// `minimumInteractiveComponentSize` 是 **48**，所以 view 侧左右各留这段透明内边距 + /// （复审 P2-2）。有标签时行宽本来 ≥48，这段内边距不改变结论，只是保持两处口径一致。 + pub fn hit_padding(&self) -> f32 { + (self.hit - self.state_layer) / 2.0 + } + + /// 勾形横向端点跨度（20 画布内 0.2→0.8）：`[源]` `Checkbox.kt:496-514` 的路径比例。 + /// + /// 这是 research/15 §25 明确允许的「组件级常量」（路径比例 0.2/0.4/0.5/0.7/0.8 不进令牌层）。 + /// 只在取证/测试里用（生产路径由 `shell::glyph` 直接按比例构路径）。 + #[cfg(test)] + pub fn check_span(&self) -> f32 { + self.side * (0.8 - 0.2) + } + + /// 方头（`StrokeCap.Square`）渲染后墨迹相对端点跨度的**外扩量**：两侧各 `1/√2 × 线宽`。 + /// + /// 只用于把「参考值 12 是端点跨度、实测是墨迹跨度」这件事写进断言：勾的两端是 45° 斜线， + /// 方头沿斜向外扩，投影到 x 轴正好是 `stroke / √2`（每端）。`#[cfg(test)]`：同 `check_span`。 + #[cfg(test)] + pub fn square_cap_bleed(&self) -> f32 { + self.stroke * std::f32::consts::FRAC_1_SQRT_2 + } +} + +/// Switch 的几何（`research/12b` §10；数值标 **G16** 的部分令牌层暂无档位）。 +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct SwitchGeometry { + /// 轨道宽（52）。 + pub track_width: f32, + /// 轨道高（32 = `Space::X8`）。 + pub track_height: f32, + /// 轨道描边（2，仅未选中态画）。 + pub track_stroke: f32, + /// 滑块：选中 / 未选中 / 按下三档（24 / 16 / 28）。 + pub thumb_selected: f32, + /// 未选中滑块（16）。 + pub thumb_unselected: f32, + /// 按下滑块（28）。 + pub thumb_pressed: f32, + /// 滑块内图标（16 = `IconSize::SwitchThumb`；AAR `SwitchTokens.SelectedIconSize / + /// UnselectedIconSize = 16.0d`。**不是按钮的 18**）。 + pub icon: f32, + /// 状态层直径（40）。 + pub state_layer: f32, + /// 最小命中区（48）。 + pub hit: f32, +} + +impl SwitchGeometry { + /// 从令牌 + G16 常量求值。 + pub fn of(ui: &Ui) -> Self { + Self { + track_width: SWITCH_TRACK_WIDTH, + track_height: ui.space(Space::X8), + track_stroke: SWITCH_TRACK_STROKE, + thumb_selected: SWITCH_THUMB_SELECTED, + thumb_unselected: SWITCH_THUMB_UNSELECTED, + thumb_pressed: SWITCH_THUMB_PRESSED, + icon: IconSize::SwitchThumb.px(), + state_layer: SWITCH_STATE_LAYER, + hit: ui.metrics().touch_target, + } + } + + /// 滑块直径：按下态胀到 28，其余按选中与否取 24 / 16（§10.2）。 + pub fn thumb(&self, selected: bool, pressed: bool) -> f32 { + if pressed { + self.thumb_pressed + } else if selected { + self.thumb_selected + } else { + self.thumb_unselected + } + } + + /// 滑块离轨道边的内距 = `(轨道高 − 滑块) / 2`（三个档位都成立：32−24=8→4，32−16=16→8，32−28=4→2）。 + pub fn thumb_inset(&self, thumb: f32) -> f32 { + (self.track_height - thumb) / 2.0 + } + + /// 状态层相对轨道的横向外扩：状态层比轨道高，未选中时滑块又靠左， + /// 所以状态层会**超出轨道左侧**——绘制区因此要多留这一段（见 [`Self::layer_offset`]）。 + pub fn bleed(&self) -> f32 { + (self.state_layer - self.track_height) / 2.0 + } + + /// 滑块圆心到状态层左缘的距离（= 状态层半径）。 + pub fn layer_radius(&self) -> f32 { + self.state_layer / 2.0 + } + + /// 滑块圆心离轨道左缘的距离：未选中 = 内距 + 半滑块；选中 = 轨道宽 − 内距 − 半滑块。 + pub fn thumb_center(&self, selected: bool, thumb: f32) -> f32 { + let inset = self.thumb_inset(thumb); + if selected { + self.track_width - inset - thumb / 2.0 + } else { + inset + thumb / 2.0 + } + } + + /// 状态层左缘相对**绘制区**的位置：绘制区左缘 = 轨道左缘 − [`Self::bleed`]。 + pub fn layer_offset(&self, selected: bool, thumb: f32) -> f32 { + self.thumb_center(selected, thumb) + self.bleed() - self.layer_radius() + } + + /// 绘制区宽（轨道 + 两侧各一段状态层外扩）。 + pub fn draw_width(&self) -> f32 { + self.track_width + self.bleed() * 2.0 + } + + /// 绘制区高（= 状态层直径，轨道在中间垂直居中）。 + pub fn draw_height(&self) -> f32 { + self.state_layer + } +} + +/// Chip 的几何（`research/12b` §13）。 +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct ChipGeometry { + /// 容器高（32 = `Space::X8`，`AssistChipTokens.ContainerHeight`）。 + pub height: f32, + /// 圆角（8 = `Component::Chip.spec().shape = ShapeScale::Small`）。 + pub radius: f32, + /// 水平内边距（8 = `Space::X2`，`Chip.kt HorizontalElementsPadding`）。 + pub pad: f32, + /// 元素间距（8，同上）。 + pub gap: f32, + /// 图标边长（18 = `IconSize::Button`；AAR `AssistChipTokens.IconSize = 18.0d`，12b 13.4 同值）。 + pub icon: f32, +} + +impl ChipGeometry { + /// 从令牌求值（`shape` 档位来自组件表，半径按边长折算）。 + pub fn of(ui: &Ui) -> Self { + let height = ui.space(Space::X8); + let shape = Component::Chip.spec().shape; + Self { + height, + radius: shape.radius_px(height), + pad: ui.space(Space::X2), + gap: ui.space(Space::X2), + icon: IconSize::Button.px(), + } + } +} + +/// 组件表里的微度量；缺组 = 令牌层还没建这一档（G16 的判据）。 +fn metrics(component: Component) -> ComponentMetrics { + component + .metrics() + .unwrap_or_else(|| panic!("{component:?} 缺 ComponentMetrics（G10 的消费入口）")) +} diff --git a/crates/app-iced/src/components/selection/matrix.rs b/crates/app-iced/src/components/selection/matrix.rs new file mode 100644 index 0000000..5f44807 --- /dev/null +++ b/crates/app-iced/src/components/selection/matrix.rs @@ -0,0 +1,211 @@ +//! 选择类家族的**状态矩阵**（D30：浅/深 × 五态）：12 行 × 5 列。 +//! +//! ```text +//! | enabled | hovered | pressed | focused | disabled | +//! checkbox·off/on/indet/error · radio·off/on · switch·off/on +//! chip·assist / chip·filter / chip·filter·on / chip·input +//! ``` +//! +//! 每格都**强制**成该态（`Checkbox::state(..)` 等取证开关）：截图时不能让 60 个控件同时 hover， +//! 而强制值只影响「画什么」，不动任何状态机——所以矩阵图里的五态与运行期五态逐像素同源。 +//! +//! 为什么住在 `selection/` 而不是 `gallery/`：`gallery/.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 20×20 圆角 2 描边 2（向内收）勾 12 方头 · \ + radio 外圈 20 环线 2 内点 10 · switch 轨道 52×32 滑块 24/16 · chip 高 32 圆角 8 · \ + Ø40 状态层 · 命中 48", + ) + .map(|_| ()) +} + +/// 图例（一行说明五态口径）。 +pub fn legend<'a>(ui: &'a Ui) -> Element<'a, ()> { + let style = ui.style(TypeRole::BodySmall); + text( + "图例：列 = 五态（focus 与 pressed 同 α 10%，看起来一样是规范要求）；行 = 组件×取值。\ + 复选框第三行是 indeterminate（勾形变成居中短横，不换图标）；第四行是错误态。", + ) + .size(style.size_px) + .font(ui.font_of(style)) + .color(ui.color(Role::OnSurfaceVariant)) + .into() +} + +/// 矩阵的一行（组件 × 取值）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +enum Row { + /// 三态复选框；布尔位 = 错误态。 + Checkbox(CheckValue, bool), + /// 单选框；布尔位 = 选中。 + Radio(bool), + /// 开关；布尔位 = 打开。 + Switch(bool), + /// Chip；`(类, 选中)`。 + Chip(ChipVariant, bool), +} + +impl Row { + /// 行序（矩阵自上而下）。 + const ALL: [Row; 12] = [ + Row::Checkbox(CheckValue::Unchecked, false), + Row::Checkbox(CheckValue::Checked, false), + Row::Checkbox(CheckValue::Indeterminate, false), + Row::Checkbox(CheckValue::Unchecked, true), + Row::Radio(false), + Row::Radio(true), + Row::Switch(false), + Row::Switch(true), + Row::Chip(ChipVariant::Assist, false), + Row::Chip(ChipVariant::Filter, false), + Row::Chip(ChipVariant::Filter, true), + Row::Chip(ChipVariant::Input, false), + ]; + + /// 左栏标签。 + fn name(self) -> &'static str { + match self { + Row::Checkbox(CheckValue::Unchecked, false) => "checkbox·off", + Row::Checkbox(CheckValue::Checked, false) => "checkbox·on", + Row::Checkbox(CheckValue::Indeterminate, false) => "checkbox·indet", + Row::Checkbox(..) => "checkbox·error", + Row::Radio(false) => "radio·off", + Row::Radio(true) => "radio·on", + Row::Switch(false) => "switch·off", + Row::Switch(true) => "switch·on", + Row::Chip(ChipVariant::Assist, _) => "chip·assist", + Row::Chip(ChipVariant::Filter, false) => "chip·filter", + Row::Chip(ChipVariant::Filter, true) => "chip·filter·on", + Row::Chip(..) => "chip·input", + } + } +} + +/// 一格的组件（强制成 `state`）。 +fn draw(ui: &Ui, spec: Row, state: Interaction) -> Element<'_, ()> { + let disabled = state.is_disabled(); + + match spec { + // 五态共用同一套装配：只有「有没有消息」随禁用变（语义上的禁用，不是画成禁用） + Row::Checkbox(value, error) => { + let mut checkbox = match (disabled, value) { + (true, value) => Checkbox::disabled("", value), + (false, CheckValue::Indeterminate) => Checkbox::tri("", value, ()), + (false, CheckValue::Checked) => Checkbox::new("", true, ()), + (false, CheckValue::Unchecked) => Checkbox::new("", false, ()), + } + .state(state); + if error { + checkbox = checkbox.error(); + } + selection::checkbox(ui, checkbox) + } + Row::Radio(selected) => { + let radio = if disabled { + Radio::disabled("", selected) + } else { + Radio::new("", selected, ()) + }; + selection::radio(ui, radio.state(state)) + } + Row::Switch(value) => { + let switch = if disabled { + Switch::disabled("", value) + } else { + Switch::new("", value, ()) + }; + selection::switch(ui, switch.state(state)) + } + Row::Chip(variant, selected) => { + let label = match variant { + ChipVariant::Assist => "Assist", + ChipVariant::Filter => "Filter", + ChipVariant::Input => "Input", + }; + // 禁用**只清消息**（`Chip::disabled()` 是修饰器）：图标与选中态必须保留， + // 否则禁用列里 `filter·on` 与 `filter` 会逐像素同形（复审 P2-1）。 + let chip = match variant { + ChipVariant::Assist => Chip::assist(label, ()).leading(IconKind::Download), + // Filter 的勾只在**选中**时给（选中态才需要「已筛选」的强提示） + ChipVariant::Filter if selected => { + Chip::filter(label, true, ()).leading(IconKind::Check) + } + ChipVariant::Filter => Chip::filter(label, false, ()).leading(IconKind::Filter), + // Input chip：前置图标 + 后置关闭键（avatar 位用图标代替） + ChipVariant::Input => Chip::input(label, ()) + .leading(IconKind::Folder) + .trailing(IconKind::Close), + }; + let chip = if disabled { chip.disabled() } else { chip }; + selection::chip(ui, chip.state(state)) + } + } +} + +/// 列头（五态名）。 +fn header_row(ui: &Ui) -> Element<'_, ()> { + let style = ui.style(TypeRole::LabelSmall); + let mut head = row![row_label(ui, "").map(|_| ())].spacing(ui.space(Space::X2)); + + for (name, width) in state_cells(ui) { + head = head.push( + container( + text(name) + .size(style.size_px) + .font(ui.font_of(style)) + .color(ui.color(Role::OnSurfaceVariant)), + ) + .width(Length::Fixed(width)), + ); + } + + head.into() +} + +/// 一个矩阵单元格（固定宽，内容左对齐）。 +fn cell<'a>(ui: &Ui, content: Element<'a, ()>) -> Element<'a, ()> { + container(content) + .width(Length::Fixed(cell_width(ui))) + .into() +} diff --git a/crates/app-iced/src/components/selection/mod.rs b/crates/app-iced/src/components/selection/mod.rs new file mode 100644 index 0000000..c6c15cc --- /dev/null +++ b/crates/app-iced/src/components/selection/mod.rs @@ -0,0 +1,50 @@ +//! **选择类家族**（D39 §1 的 ownership 切片）：Checkbox / Radio / Switch / Chip。 +//! +//! | 组件 | 参考章节 | 尺寸一句话 | +//! |---|---|---| +//! | [`Checkbox`] | `research/15` §18 | 20×20 / 圆角 2 / 描边 2（向内收）/ 勾 12dp 方头 / Ø40 状态层 / 命中 48 | +//! | [`Radio`] | `research/15` §19 | 外圈 20 / 环线 2 / 内点 **10**（不是 12）/ Ø40 状态层 | +//! | [`Switch`] | `research/12b` §10 | 轨道 52×32 / 滑块 24·16 / Ø40 状态层 | +//! | [`Chip`] | `research/12b` §13 | 高 32 / 圆角 8 / 内边距 8 / Assist·Filter·Input | +//! +//! ## 分层（照抄按钮家族，审起来只需看四处） +//! +//! ```text +//! geometry.rs 令牌 → 像素（唯一把 ComponentMetrics / Space / ShapeScale 读成数字的地方） +//! paint.rs Interaction × 选中 × 错误 → 角色 → 颜色（唯一写角色名的地方） +//! shell.rs button 四态 → 内部自绘样式的帧内通道 + 勾形 SVG +//! .rs 布局与装配（一行一个 Element） +//! ``` +//! +//! ## 纪律（D39 契约 §2 / §3） +//! +//! - 全部组件**对消息类型泛型**（`M: Clone`），不 import `crate::app::Message`； +//! - hover / pressed / focus / disabled 的 α 只从 [`super::interaction`] 取（本目录零 α 字面量）； +//! - 精确尺寸只从 [`super::layout`]（`centered_fixed` / `fixed`）与 `geometry` 取，不许手写； +//! - 图标一律 `icons::view_at(kind, color, geometry.icon)` + 固定尺寸容器（Q9）：本目录的盒是 +//! **18（chip）与 16（switch 滑块）**，都不是 `icons::RENDER_PX`(24)，所以必须按盒烘焙——用 +//! `icons::view`（24 烘焙）会被布局缩到 1.1px 视觉线宽（复审 r1 P2-2）。圆角按 D32 分层 +//! （微控件 2 / 容器刻度 / full）。 + +mod checkbox; +mod chip; +mod radio; +mod shell; +mod switch; + +pub mod geometry; +pub mod matrix; +pub mod paint; + +#[cfg(test)] +mod pixel; +#[cfg(test)] +mod probe; +#[cfg(test)] +mod tests; + +pub use checkbox::{checkbox, CheckValue, Checkbox}; +pub use chip::{chip, Chip}; +pub use paint::ChipVariant; +pub use radio::{radio, Radio}; +pub use switch::{switch, Switch}; diff --git a/crates/app-iced/src/components/selection/paint/check.rs b/crates/app-iced/src/components/selection/paint/check.rs new file mode 100644 index 0000000..6fdab48 --- /dev/null +++ b/crates/app-iced/src/components/selection/paint/check.rs @@ -0,0 +1,88 @@ +//! Checkbox 的角色映射（`research/15` §18.2 / §18.7 / §18.8）。 + +use unlucky_design::color::Role; + +use crate::theme::Ui; + +use super::super::super::interaction::Interaction; +use super::{disabled_ink, lifted, CheckboxPaint, Frame}; + +/// Checkbox 的外观。 +/// +/// **描边宽度恒 2**（禁用态也是 2，§18.8：禁用不是「变淡变细」）； +/// 选中态没有描边（`SelectedOutlineWidth = 0`，走填充分支）。 +pub fn checkbox( + ui: &Ui, + selected: bool, + error: bool, + state: Interaction, + radius: f32, + stroke: f32, +) -> CheckboxPaint { + if state.is_disabled() { + return CheckboxPaint { + frame: Frame { + // A1：`SelectedDisabledContainerColor = OnSurface` + + // `SelectedDisabledContainerOpacity = 0.38` —— **不是** 12%（复审 P2-3）。 + // 与未选中禁用的描边是同一个 38% 叠色，两格看起来才成对。 + fill: selected.then(|| disabled_ink(ui, Role::OnSurface)), + outline: (!selected).then(|| disabled_ink(ui, Role::OnSurface)), + stroke, + radius, + }, + // `SelectedDisabledIconColor = Surface`：勾是「透出底色」的浅色 + glyph: ui.color(Role::Surface), + }; + } + + match (selected, error) { + (true, false) => CheckboxPaint { + frame: Frame { + fill: Some(ui.color(Role::Primary)), + outline: None, + stroke: 0.0, + radius, + }, + glyph: ui.color(Role::OnPrimary), + }, + (true, true) => CheckboxPaint { + frame: Frame { + fill: Some(ui.color(Role::Error)), + outline: None, + stroke: 0.0, + radius, + }, + glyph: ui.color(Role::OnError), + }, + (false, error) => { + let role = if error { + Role::Error + } else if lifted(state) { + // `UnselectedHover/Focus/PressedOutlineColor = OnSurface`（A1；不是 OnSurfaceVariant） + Role::OnSurface + } else { + Role::OnSurfaceVariant + }; + CheckboxPaint { + frame: Frame { + fill: None, + outline: Some(ui.color(role)), + stroke, + radius, + }, + glyph: ui.color(role), + } + } + } +} + +/// Checkbox 状态层的 content 角色（选中/部分选中 = `Primary`，错误 = `Error`，否则 `OnSurfaceVariant`）。 +/// +/// 出处：Compose 的 ripple 色就是 `selectedContainerColor` / `unselectedOutlineColor`。 +pub fn checkbox_layer_role(filled: bool, error: bool) -> Role { + match (filled, error) { + (true, false) => Role::Primary, + (true, true) | (false, true) => Role::Error, + (false, false) => Role::OnSurfaceVariant, + } +} diff --git a/crates/app-iced/src/components/selection/paint/chip.rs b/crates/app-iced/src/components/selection/paint/chip.rs new file mode 100644 index 0000000..3277f33 --- /dev/null +++ b/crates/app-iced/src/components/selection/paint/chip.rs @@ -0,0 +1,79 @@ +//! Chip 的角色映射（`research/12b` §13.5 / §13.6 / §13.7）。 + +use unlucky_design::color::Role; + +use crate::theme::{Ui, STROKE_PX}; + +use super::super::super::interaction::Interaction; +use super::{disabled_container, disabled_ink, state_layer, ChipPaint, Frame}; + +/// Chip 的三种（§13.6 / §13.7）：Assist / Filter / Input。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum ChipVariant { + /// Assist：**永远未选中**，前置图标 `Primary`（`AssistChipTokens.IconColor`）。 + Assist, + /// Filter：可选中（`SecondaryContainer`），选中态无描边。 + Filter, + /// Input：可选中 + 后置关闭图标。 + Input, +} + +/// Chip 的外观。 +/// +/// 与 Checkbox/Radio 的区别：Chip 的**状态层就是它自己的容器**（M3 的 chip 没有圆形状态层）， +/// 所以未选中 + hover 的 fill 是「状态层叠在 surface 上」的实色。 +pub fn chip( + ui: &Ui, + variant: ChipVariant, + selected: bool, + state: Interaction, + radius: f32, +) -> ChipPaint { + let selected = selected && !matches!(variant, ChipVariant::Assist); + let label_role = if selected { + Role::OnSecondaryContainer + } else if matches!(variant, ChipVariant::Assist) { + Role::OnSurface + } else { + Role::OnSurfaceVariant + }; + + if state.is_disabled() { + let ink = disabled_ink(ui, Role::OnSurface); + return ChipPaint { + frame: Frame { + fill: selected.then(|| disabled_container(ui)), + outline: (!selected).then(|| disabled_container(ui)), + stroke: STROKE_PX, + radius, + }, + label: ink, + icon: ink, + }; + } + + let outline = (!selected).then(|| ui.color(Role::OutlineVariant)); + let fill = if selected { + Some(ui.color(Role::SecondaryContainer)) + } else { + state_layer(ui, state, label_role) + }; + // Assist / 选中态的前置图标是 `Primary`（`AssistChipTokens.IconColor` / + // `InputChipTokens.SelectedLeadingIconColor`）；其余跟文字同色。 + let icon_role = if matches!(variant, ChipVariant::Assist) || selected { + Role::Primary + } else { + label_role + }; + + ChipPaint { + frame: Frame { + fill, + outline, + stroke: STROKE_PX, + radius, + }, + label: ui.color(label_role), + icon: ui.color(icon_role), + } +} diff --git a/crates/app-iced/src/components/selection/paint/mod.rs b/crates/app-iced/src/components/selection/paint/mod.rs new file mode 100644 index 0000000..b52e4ee --- /dev/null +++ b/crates/app-iced/src/components/selection/paint/mod.rs @@ -0,0 +1,149 @@ +//! 选择类家族的**角色映射**：`Interaction × 选中 × 错误 → 颜色`（公共件 + 各组件分文件）。 +//! +//! ## 出处（全部 A1：`material3-android:1.4.0` 的 token 类，本机 AAR `javap` 复核，见报告） +//! +//! | 组件 | 静息 | hover / focus / pressed | 禁用 | +//! |---|---|---|---| +//! | Checkbox 未选中 | 描边 `OnSurfaceVariant` 2px | 描边提到 **`OnSurface`**（宽度仍 2） | 描边 `OnSurface`@38% | +//! | Checkbox 选中 | 填 `Primary` + 勾 `OnPrimary` | 填 `Primary`（不变） | 填 `OnSurface`@38% + 勾 `Surface` | +//! | Radio | 环 `OnSurfaceVariant` / 选中环+点 `Primary` | 未选中环提到 **`OnSurface`**；**选中态仍是 `Primary`** | 环+点 `OnSurface`@38% | +//! | Switch | 轨 `Primary`（选中）/`SurfaceContainerHighest`+2px `Outline`；滑块 `OnPrimary`/`Outline` | 滑块 `PrimaryContainer`/`OnSurfaceVariant` | 轨 `OnSurface`@12%；滑块 `Surface`/@38% | +//! | Chip | 未选中：透明+1px `OutlineVariant`，文字 `OnSurfaceVariant`；选中：`SecondaryContainer` **无描边** | 描边不变，状态层成为底色 | 描边 `OnSurface`@12%；文字/图标 @38% | +//! +//! **A1 改过参考表的三处**：`UnselectedHover/Focus/PressedOutlineColor` 与 Radio 的 +//! `UnselectedHover/Focus/PressedIconColor` 都是 `OnSurface`（不是 `OnSurfaceVariant`）； +//! `SelectedDisabledIconColor` 是 `Surface`。α 一律从 [`interaction`] 取。 +//! +//! ## 为什么拆成目录（复审 P2-5） +//! +//! 原来一个文件正好 400 行、零余量：再加一个态就得动它。按组件拆成 +//! `check.rs` / `radio.rs` / `switch.rs` / `chip.rs`，公共件（[`Frame`]、状态层、禁用色）留在本文件， +//! **对外 API 一字不改**（`selection::paint::*` 的路径全部保持）。 + +use iced::widget::container; +use iced::{Background, Border, Color}; + +use unlucky_design::color::Role; + +use crate::theme::Ui; + +use super::super::interaction::{self, Interaction}; + +mod check; +mod chip; +mod radio; +mod switch; + +pub use check::{checkbox, checkbox_layer_role}; +pub use chip::{chip, ChipVariant}; +pub use radio::{radio, radio_layer_role}; +pub use switch::{switch, switch_layer}; + +/// 一个「方框」的外观：填色 / 描边 / 线宽 / 半径。 +/// +/// Checkbox 的框、Radio 的环、Switch 的轨道、Chip 的容器都用它——差别只在颜色与线宽。 +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct Frame { + /// 填充色；`None` = 透明（未选中的 Checkbox / Radio 外圈、Chip 的 flat 底）。 + pub fill: Option, + /// 描边色；`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` 角色 @ 该态的 α 叠在 `surface` 上（不透明；α 的唯一实现点是 +/// [`interaction::overlay_color`]，本目录零 α 字面量）。 +pub fn state_layer(ui: &Ui, state: Interaction, content: Role) -> Option { + interaction::overlay_color(ui, state, content, Role::Surface) +} + +/// `OnSurface`@12% 叠 surface（**容器**禁用色：Switch 轨道、Chip 未选中描边）。 +/// +/// 注意：Checkbox「选中且禁用」的**填充**不是这个 12%，A1 的 +/// `SelectedDisabledContainerOpacity = 0.38` → 见 [`disabled_ink`]（复审 P2-3）。 +pub(super) fn disabled_container(ui: &Ui) -> Color { + interaction::disabled_colors(ui, Role::Surface).0 +} + +/// 内容禁用色：`role` @38% 叠在 surface 上（`on_container = false`）。 +pub(super) fn disabled_ink(ui: &Ui, role: Role) -> Color { + interaction::disabled_content_over_role(ui, role, false) +} + +/// hover / focus / pressed（「抬起来」的三态）。 +pub(super) fn lifted(state: Interaction) -> bool { + matches!( + state, + Interaction::Hovered | Interaction::Focused | Interaction::Pressed + ) +} + +/// 控件旁的标签色：`OnSurface`；禁用 → `OnSurface`@38%。 +/// +/// A1 里 checkbox/radio 都没有「标签色随 hover 变」的字段（标签不属于控件本体）， +/// 所以这里只看禁用与否。 +pub fn label(ui: &Ui, state: Interaction) -> Color { + if state.is_disabled() { + disabled_ink(ui, Role::OnSurface) + } else { + ui.color(Role::OnSurface) + } +} diff --git a/crates/app-iced/src/components/selection/paint/radio.rs b/crates/app-iced/src/components/selection/paint/radio.rs new file mode 100644 index 0000000..7d09072 --- /dev/null +++ b/crates/app-iced/src/components/selection/paint/radio.rs @@ -0,0 +1,42 @@ +//! Radio 的角色映射（`research/15` §19.3 / §19.4 / §19.5）。 + +use unlucky_design::color::Role; + +use crate::theme::Ui; + +use super::super::super::interaction::Interaction; +use super::{disabled_ink, lifted, Frame, RadioPaint}; + +/// Radio 的外观。 +/// +/// **选中态 hover 不换色**：环与点在四态里都是 `Primary`（只有状态层变）。 +pub fn radio(ui: &Ui, selected: bool, state: Interaction, radius: f32, stroke: f32) -> RadioPaint { + let ink = if state.is_disabled() { + disabled_ink(ui, Role::OnSurface) + } else if selected { + ui.color(Role::Primary) + } else if lifted(state) { + ui.color(Role::OnSurface) + } else { + ui.color(Role::OnSurfaceVariant) + }; + + RadioPaint { + ring: Frame { + fill: None, + outline: Some(ink), + stroke, + radius, + }, + dot: selected.then_some(ink), + } +} + +/// Radio 状态层的 content 角色（选中 = `Primary`，未选中 = `OnSurfaceVariant`）。 +pub fn radio_layer_role(selected: bool) -> Role { + if selected { + Role::Primary + } else { + Role::OnSurfaceVariant + } +} diff --git a/crates/app-iced/src/components/selection/paint/switch.rs b/crates/app-iced/src/components/selection/paint/switch.rs new file mode 100644 index 0000000..d4b2520 --- /dev/null +++ b/crates/app-iced/src/components/selection/paint/switch.rs @@ -0,0 +1,102 @@ +//! Switch 的角色映射（`research/12b` §10.3 / §10.4 / §10.6 / §10.7）。 + +use iced::Color; + +use unlucky_design::color::Role; +use unlucky_design::shape::ShapeScale; + +use crate::theme::Ui; + +use super::super::super::interaction::{self, Interaction}; +use super::super::geometry::SwitchGeometry; +use super::{disabled_container, disabled_ink, lifted, Frame, SwitchPaint}; + +/// Switch 的外观。 +pub fn switch(ui: &Ui, selected: bool, state: Interaction) -> SwitchPaint { + let geometry = SwitchGeometry::of(ui); + let radius = ShapeScale::Full.radius_px(geometry.track_height); + + if state.is_disabled() { + let container = disabled_container(ui); + return if selected { + SwitchPaint { + track: Frame { + fill: Some(container), + outline: None, + stroke: 0.0, + radius, + }, + // `DisabledSelectedHandleColor = Surface` 且不透明度 1（A1 的 fconst_1） + thumb: ui.color(Role::Surface), + icon: Some(disabled_ink(ui, Role::OnSurface)), + } + } else { + SwitchPaint { + track: Frame { + fill: Some(ui.color(Role::SurfaceContainerHighest)), + outline: Some(container), + stroke: geometry.track_stroke, + radius, + }, + thumb: disabled_ink(ui, Role::OnSurface), + icon: None, + } + }; + } + + if selected { + SwitchPaint { + track: Frame { + fill: Some(ui.color(Role::Primary)), + outline: None, + stroke: 0.0, + radius, + }, + // `SelectedHover/Focus/PressedHandleColor = PrimaryContainer`（A1，1.4.0 起） + thumb: if lifted(state) { + ui.color(Role::PrimaryContainer) + } else { + ui.color(Role::OnPrimary) + }, + icon: Some(ui.color(Role::OnPrimaryContainer)), + } + } else { + SwitchPaint { + track: Frame { + fill: Some(ui.color(Role::SurfaceContainerHighest)), + outline: Some(ui.color(Role::Outline)), + stroke: geometry.track_stroke, + radius, + }, + // `UnselectedHover/Focus/PressedHandleColor = OnSurfaceVariant`（A1） + thumb: if lifted(state) { + ui.color(Role::OnSurfaceVariant) + } else { + ui.color(Role::Outline) + }, + icon: None, + } + } +} + +/// 状态层的 content 角色（选中 = 滑块色 `OnPrimary`，未选中 = `Outline`）。 +pub fn switch_layer_role(selected: bool) -> Role { + if selected { + Role::OnPrimary + } else { + Role::Outline + } +} + +/// Switch 状态层的颜色：**叠在轨道色上**，不是叠在 surface 上。 +/// +/// switch 的状态层圆（Ø40）有一大半压在轨道（52×32）上：若照别的控件那样叠 surface， +/// 圆会在轨道里画出一块「更亮的补丁」（实测第一版就是这个样子，轨道像被啃掉一块）。 +pub fn switch_layer(ui: &Ui, state: Interaction, selected: bool) -> Option { + let track = if selected { + Role::Primary + } else { + Role::SurfaceContainerHighest + }; + interaction::overlay_color(ui, state, switch_layer_role(selected), track) +} diff --git a/crates/app-iced/src/components/selection/pixel.rs b/crates/app-iced/src/components/selection/pixel.rs new file mode 100644 index 0000000..d5528ab --- /dev/null +++ b/crates/app-iced/src/components/selection/pixel.rs @@ -0,0 +1,205 @@ +//! 像素取证的小工具（**仅测试**）：读 PNG、按「底色→墨色混色线」找连通块、量内缩墨迹。 +//! +//! 为什么不去用 `gallery/scan.rs`：它的可见性是 `pub(in crate::app::components::gallery)`， +//! 跨目录拿不到；这里只重写 4 个纯函数（`rgb` / `matches` / 像素访问 / 外接框），其余判据 +//! （[`on_ramp`] / [`ink_boxes`] / [`inner_ink`]）是一次性的测量逻辑，本来就只服务本家族。 + +use std::path::PathBuf; + +use iced::Color; + +/// 8bit RGB。 +pub(super) fn rgb(color: Color) -> [u8; 3] { + [ + (color.r * 255.0).round() as u8, + (color.g * 255.0).round() as u8, + (color.b * 255.0).round() as u8, + ] +} + +/// 容差比较（抗锯齿/取整）。 +pub(super) fn matches(pixel: [u8; 3], expected: [u8; 3]) -> bool { + pixel.iter().zip(expected).all(|(a, b)| a.abs_diff(b) <= 10) +} + +/// `ULL_GALLERY_SHOT` → 截图路径（相对路径按工作区根解释）。 +pub(super) fn shot_path() -> Option { + 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` +/// 更接近深色，于是未选中的框被当成 20×20 的 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..7a7e697 --- /dev/null +++ b/crates/app-iced/src/components/selection/probe.rs @@ -0,0 +1,326 @@ +//! 选择类家族的**渲染层**几何断言：对着真截图量像素（M68 的教训：纯函数对、图可能是错的）。 +//! +//! 为什么住在 `selection/` 而不是 `gallery/`：`gallery/selection.rs` 只负责「把矩阵摆进 harness」， +//! 断言加上去会把它顶到 400 行红线。像素扫描的 4 个纯函数在 [`super::pixel`]（同一目录、`cfg(test)`）。 +//! +//! 量什么（每条对一个具体错误，容差 ±1）： +//! +//! - **Checkbox 外缘 20，且选中/未选中同尺寸**（§18.3：描边向内收；向外画会变 22）——逐块断言； +//! - **Radio 内点 10 不是 12**（§19.2）· 环是真圆、不是圆角方（§19.6）； +//! - **状态层直径 40 且四角无墨**（§18.5 / §19.7）——**每一块**都查； +//! - 勾形墨迹 ≈14.8（端点 12 + 方头外扩）· **indeterminate 是短横**（§18.4/§18.6）； +//! - Switch 轨道**恰好一块** 52×32（§10.1）· Chip **恰好一块** 32 高（§13.1）； +//! - 禁用：chip 只降不删（P2-1）· 选中禁用的 Checkbox 容器是 38% 不是 12%（P2-3）。 +//! +//! 复现（worktree 根目录）： +//! +//! ```text +//! cargo build -p unlucky-app-iced --bin unlucky-launcher-iced +//! ULL_GALLERY_SECTION=selection ./target/debug/unlucky-launcher-iced \ +//! --software-renderer --screen=gallery \ +//! --screenshot target/m76/selection-light.png --screenshot-theme=light +//! ULL_GALLERY_SHOT=target/m76/selection-light.png cargo test -p unlucky-app-iced selection::probe +//! ``` + +use unlucky_design::color::{Role, SchemeFlavor}; +use unlucky_design::typography::Platform; + +use super::super::interaction::{self, Interaction}; +use super::pixel::{center, dims, ink_boxes, inner_ink, matches, near, rgb, shot_path, Shot}; +use crate::theme::{Families, Ui}; + +const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", +}; + +fn ui(flavor: SchemeFlavor) -> Ui { + Ui::with_platform(flavor, Platform::Windows, FAMILIES) +} + +/// 一条测试覆盖全部几何断言（浅/深各跑一次）。 +#[test] +fn selection_geometry_matches_the_reference() { + let Some(path) = shot_path() else { + eprintln!( + "[selection-probe] SKIPPED：未设置 ULL_GALLERY_SHOT。这是**渲染层**几何断言，\ + 需要先出图（见本文件模块文档，注意 ULL_GALLERY_SECTION=selection）。" + ); + return; + }; + let shot = Shot::load(&path).expect("读 selection 截图"); + assert_eq!( + (shot.width, shot.height), + (1180, 760), + "验收图必须 1180×760 @100% DPI" + ); + let light = matches( + shot.at(2, 2), + rgb(ui(SchemeFlavor::Light).color(Role::Surface)), + ); + let flavor = if light { + SchemeFlavor::Light + } else { + SchemeFlavor::Dark + }; + let ui = ui(flavor); + let surface = ui.color(Role::Surface); + let primary = ui.color(Role::Primary); + let on_primary = ui.color(Role::OnPrimary); + let unselected = ui.color(Role::OnSurfaceVariant); + + // ---- §18.1 / §18.3 / §19.1：20 的外缘，选中与未选中**同尺寸** ----------------- + // 逐块断言（复审 P2-4）：**每一块** Primary 都必须是 20(±1)——任何一块到 22 就说明描边 + // 画到了框外。只数「20×20 有几块」的时候，「把其中一格放大成 22」照样绿。 + let filled = ink_boxes(&shot, primary, surface, 15, 24); + for bbox in &filled { + assert!( + bbox.width() <= 21 && bbox.height() <= 21, + "18.3：Primary 块不得超过 21（22 = 描边画到框外），实测 {}×{} @ {:?}", + bbox.width(), + bbox.height(), + (bbox.left, bbox.top) + ); + } + let twenty: Vec<_> = filled + .iter() + .copied() + .filter(|bbox| near(bbox.width(), 20) && near(bbox.height(), 20)) + .collect(); + assert_eq!( + twenty.len(), + 12, + "18.1：应**恰好** 12 块 20(±1) 的 Primary（checkbox 选中 4 + 部分选中 4 + radio 环 4），\ + 实际 {}：{}", + twenty.len(), + dims(&filled) + ); + + // 未选中（OnSurfaceVariant 描边）：逐块都必须 20(±1)，且内部透底 + let candidates = ink_boxes(&shot, unselected, surface, 17, 24); + let rings: Vec<_> = candidates + .iter() + .copied() + .filter(|bbox| !matches(shot.at(center(bbox).0, bbox.top + 3), rgb(unselected))) + .collect(); + assert!( + !rings.is_empty(), + "18.2：没找到未选中的复选框；候选：{}", + dims(&candidates) + ); + for bbox in &rings { + assert!( + near(bbox.width(), 20) && near(bbox.height(), 20), + "18.3：未选中外缘必须与选中同尺寸 20（描边向内收），实测 {}×{} @ {:?}", + bbox.width(), + bbox.height(), + (bbox.left, bbox.top) + ); + assert!( + !matches(shot.at(center(bbox).0, center(bbox).1), rgb(unselected)), + "18.2：未选中框内部必须透出底色" + ); + } + // A1：hover/pressed/focused 三列的未选中描边提到 `OnSurface` + let on_surface = ui.color(Role::OnSurface); + let lifted: Vec<_> = ink_boxes(&shot, on_surface, surface, 17, 24) + .into_iter() + .filter(|bbox| !matches(shot.at(center(bbox).0, bbox.top + 3), rgb(on_surface))) + .collect(); + assert!( + lifted.len() >= 3, + "A1：未选中复选框在 hover/pressed/focused 的描边应是 OnSurface（3 个），实际 {}", + lifted.len() + ); + for bbox in &lifted { + assert!( + near(bbox.width(), 20) && near(bbox.height(), 20), + "18.3：提到 OnSurface 之后外缘仍是 20，实测 {}×{}", + bbox.width(), + bbox.height() + ); + } + + // ---- §19.2：Radio 内点 **10 不是 12**；§19.6：环是真圆 ------------------------ + // 环/实心看**上沿内缩 3px 的点**（环在那里是内孔）；不看正中心——短横正好压中心。 + let mut dots = 0; + for bbox in &twenty { + if matches(shot.at(center(bbox).0, bbox.top + 3), rgb(primary)) { + continue; + } + assert!( + !matches(shot.at(bbox.left + 1, bbox.top + 1), rgb(primary)), + "19.6：Radio 外圈必须是真圆（不是圆角方）@ {:?}", + (bbox.left, bbox.top) + ); + let dot = inner_ink(&shot, bbox, primary, surface, 4).expect("选中的 radio 必须有内点"); + assert!( + near(dot.width(), 10) && near(dot.height(), 10), + "19.2：Radio 内点可视直径 10（12 是含描边前的名义值），实测 {}×{}", + dot.width(), + dot.height() + ); + assert_ne!(dot.width(), 12, "19.2：照名义值抄 12 会明显偏大"); + dots += 1; + } + assert_eq!( + dots, 4, + "19.2：应恰好 4 个选中的 radio（四态），实际 {dots}" + ); + + // ---- §18.4 / §18.6：勾形墨迹跨度；indeterminate 是**短横**不是勾 -------------- + let mut bars = 0; + let mut checks = 0; + for bbox in &twenty { + let Some(glyph) = inner_ink(&shot, bbox, on_primary, primary, 3) else { + continue; + }; + if glyph.height() <= 4 { + bars += 1; + assert!( + glyph.width() >= 12, + "18.6：indeterminate 必须是居中短横，实测 {}×{}", + glyph.width(), + glyph.height() + ); + } else { + checks += 1; + // 端点 12 + 方头两侧各 2/√2 ≈ 1.41 → 墨迹 ≈14.8（见 `ControlGeometry`） + assert!( + (13..=16).contains(&glyph.width()), + "18.4：勾形墨迹横向应 ≈14.8（端点 12 + 方头外扩），实测 {}", + glyph.width() + ); + assert!( + glyph.height() >= 6, + "18.4：勾形有折点，实测高 {}", + glyph.height() + ); + } + } + assert!( + bars >= 4 && checks >= 4, + "18.4/18.6：勾 {checks} 个、短横 {bars} 个（各应 ≥4）" + ); + + // ---- §18.5 / §19.7：状态层直径 40，且**每一块**都是圆（四角无墨）---------------- + // hover 是 8%、pressed/focus 是 10%：**两种颜色都要查**。只查 8% 会漏掉「按下那一列被画成 + // 方块」——代码 reviewer 的第二次变异正好落在这个盲点上（实测它当时是绿的）。 + let mut circles = 0; + for state in [Interaction::Hovered, Interaction::Pressed] { + let layer = interaction::overlay_color(&ui, state, Role::OnSurfaceVariant, Role::Surface) + .expect("可交互态有状态层"); + let found: Vec<_> = ink_boxes(&shot, layer, surface, 37, 43) + .into_iter() + .filter(|bbox| near(bbox.width(), 40) && near(bbox.height(), 40)) + .collect(); + assert!( + found.len() >= 2, + "18.5：{state:?} 的 Ø40 状态层应 ≥2 块（checkbox×3 + radio + switch），实测 {}：{}", + found.len(), + dims(&found) + ); + for circle in &found { + for (x, y) in [ + (circle.left, circle.top), + (circle.right, circle.top), + (circle.left, circle.bottom), + (circle.right, circle.bottom), + ] { + assert!( + !matches(shot.at(x, y), rgb(layer)), + "18.5：{state:?} 状态层必须是圆（外接框四角不该有墨）@ ({x},{y})" + ); + } + } + circles += found.len(); + } + + // ---- §10.1 Switch 轨道 52×32 · §13.1 Chip 高 32 ------------------------------- + let on_tracks: Vec<_> = ink_boxes(&shot, primary, surface, 28, 57) + .into_iter() + .filter(|bbox| near(bbox.width(), 52) && near(bbox.height(), 32)) + .collect(); + assert_eq!( + on_tracks.len(), + 1, + "10.1：选中的 switch 轨道应**恰好一块** 52×32，实测 {}：{}", + on_tracks.len(), + dims(&on_tracks) + ); + let chips: Vec<_> = ink_boxes(&shot, ui.color(Role::SecondaryContainer), surface, 20, 140) + .into_iter() + .filter(|bbox| near(bbox.height(), 32)) + .collect(); + // 选中的 chip 在**四态**里容器都是 `SecondaryContainer`（状态层只叠在未选中的透明底上）， + // 所以这里应恰好 4 块——多于 4 说明别的组件的容器也是这个角色、且高 32。 + assert_eq!( + chips.len(), + 4, + "13.1：选中的 filter chip 应**恰好四块**（enabled/hover/pressed/focused 各一，32 高），\ + 实测 {}：{}", + chips.len(), + dims(&chips) + ); + assert!( + chips[0].width() >= 58, + "13.1：chip 宽应 ≥58（图标 18 + 两侧各 8 + 文字），实测 {}", + chips[0].width() + ); + + // ---- 复审 P2-1：禁用的 chip **只降不删**（选中态与图标都要在）------------------ + // 判据：禁用列里必须**恰好有一块** 12% 填充的 chip（= filter·on）。旧 API 把 selected + // 一起删掉，这一块根本不存在（实测 0 块）；能查到它、且宽度 ≥58，说明选中态与图标都还在。 + // （未选中的那三个禁用 chip 只有 1px 描边，落在半像素上时覆盖率不足 50%，量不稳，故不在此断言。） + let disabled_container = interaction::disabled_colors(&ui, Role::Surface).0; + let disabled_chips: Vec<_> = ink_boxes(&shot, disabled_container, surface, 28, 140) + .into_iter() + .filter(|bbox| near(bbox.height(), 32) && bbox.width() >= 58) + .collect(); + assert_eq!( + disabled_chips.len(), + 1, + "P2-1：禁用列应**恰好一块**填充 chip（filter·on 的选中态不能被删掉），实测 {}：{}", + disabled_chips.len(), + dims(&disabled_chips) + ); + assert!( + disabled_chips[0].width() >= 58, + "P2-1：禁用 chip 宽度应 ≥58（图标还在），实测 {}", + disabled_chips[0].width() + ); + + // ---- 复审 P2-3：**选中且禁用**的 Checkbox 容器是 38%，不是 12% ----------------- + let disabled_ink = interaction::disabled_content_over_role(&ui, Role::OnSurface, false); + let ink38: Vec<_> = ink_boxes(&shot, disabled_ink, surface, 17, 24) + .into_iter() + .filter(|bbox| near(bbox.width(), 20) && near(bbox.height(), 20)) + .collect(); + assert!( + ink38.len() >= 3, + "18.8：禁用列应有 ≥3 块 20(±1) 的 38% 叠色（选中禁用填充 + 未选中禁用描边 + radio 环），\ + 实测 {}：{}", + ink38.len(), + dims(&ink38) + ); + let container_20: Vec<_> = ink_boxes(&shot, disabled_container, surface, 19, 21) + .into_iter() + .filter(|bbox| near(bbox.width(), 20) && near(bbox.height(), 20)) + .collect(); + assert!( + container_20.is_empty(), + "P2-3：20×20 的禁用块不许是 12% 容器色（那是普通禁用容器，选中禁用是 38%），实测 {}", + dims(&container_20) + ); + + eprintln!( + "[selection-probe] OK flavor={flavor:?}：20(±1) Primary 块 {} · 未选中环 {} · 内点 {dots} · \ + 勾 {checks} / 短横 {bars} · 状态层 {} · 禁用 38% {} · 禁用 chip {}", + twenty.len(), + rings.len(), + circles, + ink38.len(), + disabled_chips.len() + ); +} diff --git a/crates/app-iced/src/components/selection/radio.rs b/crates/app-iced/src/components/selection/radio.rs new file mode 100644 index 0000000..64680cd --- /dev/null +++ b/crates/app-iced/src/components/selection/radio.rs @@ -0,0 +1,155 @@ +//! Radio button（`research/15` §19）：外圈 **20** / 环线 **2** / 内点 **10**（不是 12）/ +//! 选中环+点 `Primary` / 未选中环 `OnSurfaceVariant`（hover 提到 `OnSurface`）/ Ø40 状态层。 +//! +//! ## 为什么它不是「基于 Checkbox 画的」 +//! +//! §19.6 明令：Radio **只能**是「2px 环 + 实心内点」，Checkbox **只能**是「2px 方框 + 勾/横」； +//! 两者尺寸相同（20）但形状语言不同，禁止混用。所以本文件是独立实现，**没有** import +//! `super::checkbox`（gallery 的 probe 另有一条断言：radio 的墨迹里不得出现方角像素）。 +//! +//! ## 几何怎么落到像素 +//! +//! 环：20×20 容器 + `Border { width: 2, radius: 10 }`。iced 的 quad 渲染器把描边路径向内缩 +//! 半个线宽（半径 10−1=9、路径外接 18），再以 2 描边 → 外缘正好 20、内缘 16。这与 Compose +//! `RadioButton.kt` 的「环半径 = 10 − 1 = 9 且描边居中 → 外缘正好 20」逐像素同源。 +//! 内点：独立 10×10 圆容器居中在环里（绘制半径 12/2 − 2/2 = 5，即**直径 10**，§19.2）。 + +use iced::widget::{container, row, text}; +use iced::{Alignment, Element, Length, Padding}; + +use unlucky_design::typography::TypeRole; + +use crate::theme::Ui; + +use super::super::interaction::Interaction; +use super::geometry::ControlGeometry; +use super::paint::{self, Frame}; +use super::shell::{self, StateSource}; + +/// 一个单选框（环 + 可选标签；`on_select` 为 `None` = 禁用）。 +#[derive(Debug, Clone)] +pub struct Radio<'a, M> { + label: &'a str, + selected: bool, + on_select: Option, + state: Option, +} + +impl<'a, M> Radio<'a, M> { + /// 一个可选的单选框。 + pub fn new(label: &'a str, selected: bool, on_select: M) -> Self { + Self { + label, + selected, + on_select: Some(on_select), + state: None, + } + } + + /// 禁用的单选框（无消息）。 + pub fn disabled(label: &'a str, selected: bool) -> Self { + Self { + label, + selected, + on_select: None, + state: None, + } + } + + /// 强制视觉态（gallery 取证用；运行期不要调）。 + pub fn state(mut self, state: Interaction) -> Self { + self.state = Some(state); + self + } +} + +/// 画一个单选框（环 + 内点 + 标签）。 +pub fn radio<'a, M: Clone + 'a>(ui: &'a Ui, spec: Radio<'a, M>) -> Element<'a, M> { + let geometry = ControlGeometry::radio(ui); + let selected = spec.selected; + let radius = geometry.radius; + let stroke = geometry.stroke; + let dot_side = geometry.inner_dot; + let source = StateSource::new(spec.state, spec.on_select.is_some()); + + // 内点与环的颜色与 hover/pressed 无关（A1：选中态四态都是 `Primary`）， + // 只随「选中 + 禁用」变 —— 所以点的颜色在这里静态求值即可。 + let at_rest = paint::radio(ui, selected, source.get(), radius, stroke); + + // Ø10 内点（半径 = 直径/2） + let dot: Element<'a, M> = match at_rest.dot { + Some(ink) => container(iced::widget::Space::new()) + .width(Length::Fixed(dot_side)) + .height(Length::Fixed(dot_side)) + .style(move |_theme| { + Frame { + fill: Some(ink), + outline: None, + stroke: 0.0, + radius: dot_side / 2.0, + } + .container_style() + }) + .into(), + None => iced::widget::Space::new().into(), + }; + + // 20 外圈：环（未选中时环就是唯一的墨迹；选中时环 + 点同色） + let ring = container(dot) + .width(Length::Fixed(geometry.side)) + .height(Length::Fixed(geometry.side)) + .align_x(Alignment::Center) + .align_y(Alignment::Center) + .style(source.container_style(move |state| { + paint::radio(ui, selected, state, radius, stroke) + .ring + .container_style() + })); + + // Ø40 状态层 + let layer_side = geometry.state_layer; + let layer = container(ring) + .width(Length::Fixed(layer_side)) + .height(Length::Fixed(layer_side)) + .align_x(Alignment::Center) + .align_y(Alignment::Center) + .style(source.container_style(move |state| { + Frame { + fill: paint::state_layer(ui, state, paint::radio_layer_role(selected)), + outline: None, + stroke: 0.0, + radius: layer_side / 2.0, + } + .container_style() + })); + + let mut content = row![layer].align_y(Alignment::Center).spacing(geometry.gap); + if !spec.label.is_empty() { + let style = ui.style(TypeRole::BodyLarge); + content = content.push( + text(spec.label) + .size(style.size_px) + .font(ui.font_of(style)) + .color(paint::label(ui, source.get())), + ); + } + + // 命中区 48×48：左右各留 `hit_padding` 透明内边距（无标签时行宽才不是 40；复审 P2-2） + let pad = geometry.hit_padding(); + let body = container(content) + .height(Length::Fill) + .align_y(Alignment::Center) + .padding(Padding { + left: pad, + right: pad, + ..Padding::default() + }); + + shell::shell( + &source, + Length::Shrink, + Length::Fixed(geometry.hit), + spec.on_select, + body.into(), + ) +} diff --git a/crates/app-iced/src/components/selection/shell.rs b/crates/app-iced/src/components/selection/shell.rs new file mode 100644 index 0000000..0034cdf --- /dev/null +++ b/crates/app-iced/src/components/selection/shell.rs @@ -0,0 +1,156 @@ +//! 交互外壳：`button` 的四态 → 内部自绘容器的样式；以及勾形的 SVG。 +//! +//! ## 为什么需要 [`StateSource`] 这条「帧内通道」 +//! +//! M3 的 Checkbox / Radio / Switch 状态层是**Ø40 的圆**，而命中区是 **48** +//! （`research/15` §18.5 / §18.9）——两者尺寸不同，所以状态层不可能就是 `button` 自己的 +//! 矩形四角（`button` 只能给自己的 bounds 上色）。正确画法是「48 的透明按钮里放一个 40 的圆」， +//! 但这个圆的颜色要跟着**按钮的状态**走，而 iced 的 `container` 样式闭包只有 `&Theme`、拿不到 +//! `button::Status`。 +//! +//! 所以这里留一个帧内通道：`button` 的样式闭包先跑（父先于子绘制，`iced_widget::button::draw` +//! 第 382 行 `fill_quad` 在 `content.draw` 之前），把状态写进 [`StateSource`]；子容器的样式闭包 +//! 随后读到**本帧**的状态。α 仍然只从 [`super::super::interaction`] 取，这里不做任何颜色算术。 +//! +//! 取证（gallery 状态矩阵）时用 [`StateSource::forced`] 直接钉住某态，通道根本不参与。 + +use std::cell::Cell; +use std::rc::Rc; + +use iced::widget::{button, svg}; +use iced::{Color, Element, Length, Padding}; + +use super::super::interaction::Interaction; +use super::geometry::ControlGeometry; + +/// 当前视觉态的取值口：**外部钉住**（取证）或**跟随 `button` 的实况**（运行期）。 +#[derive(Debug, Clone)] +pub struct StateSource { + forced: Option, + 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..b097cda --- /dev/null +++ b/crates/app-iced/src/components/selection/switch.rs @@ -0,0 +1,177 @@ +//! Switch（`research/12b` §10）：轨道 **52×32** / 圆角 full(16) / 未选中 2px `Outline` 描边 / +//! 滑块 **24·16**（按下 28，见偏离 D-SW1）/ 滑块内图标 16 / **Ø40 状态层**。 +//! +//! ## 状态层为什么跟滑块走 +//! +//! M3 的 switch 状态层是围着**滑块**的 Ø40 圆（`StateLayerSize = 40`），而轨道只有 32 高、 +//! 52 宽、滑块最小 16——圆会同时超出轨道的上下与左右。所以绘制区比轨道大一圈： +//! 宽 = 52 + 2×4（[`SwitchGeometry::draw_width`]）、高 = 40，轨道在中间，滑块与状态层浮在上面。 +//! +//! ## 偏离 D-SW1（登记在报告里） +//! +//! `PressedHandleWidth = 28` 的「按下胀开」**未做**：iced 的 `button` 只在事件时重绘， +//! 不会重建视图，而滑块尺寸是**布局量**（不是颜色）。要做它必须写自定义 `Widget` +//! （`interaction::Tracker` 那条路），本 mission 的时间盒留给四条线的像素断言与视觉证据。 +//! 按下的可判定反馈仍在：状态层 α 从 8% 升到 10%（`StateLayer::Pressed`）。 + +use iced::widget::{container, row, text, Space as Spacer}; +use iced::{Alignment, Element, Length, Padding}; + +use unlucky_design::icons::IconKind; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; + +use crate::icons; +use crate::theme::Ui; + +use super::super::interaction::Interaction; +use super::geometry::SwitchGeometry; +use super::paint::{self, Frame}; +use super::shell::{self, StateSource}; + +/// 一个开关（轨道 + 滑块 + 可选标签；`on_toggle` 为 `None` = 禁用）。 +#[derive(Debug, Clone)] +pub struct Switch<'a, M> { + label: &'a str, + value: bool, + on_toggle: Option, + state: Option, +} + +impl<'a, M> Switch<'a, M> { + /// 一个可切换的开关。 + pub fn new(label: &'a str, value: bool, on_toggle: M) -> Self { + Self { + label, + value, + on_toggle: Some(on_toggle), + state: None, + } + } + + /// 禁用的开关（无消息）。 + pub fn disabled(label: &'a str, value: bool) -> Self { + Self { + label, + value, + on_toggle: None, + state: None, + } + } + + /// 强制视觉态（gallery 取证用；运行期不要调）。 + pub fn state(mut self, state: Interaction) -> Self { + self.state = Some(state); + self + } +} + +/// 画一个开关（轨道 + 滑块 + 标签）。 +pub fn switch<'a, M: Clone + 'a>(ui: &'a Ui, spec: Switch<'a, M>) -> Element<'a, M> { + let geometry = SwitchGeometry::of(ui); + let selected = spec.value; + let thumb_side = geometry.thumb(selected, false); + let source = StateSource::new(spec.state, spec.on_toggle.is_some()); + + // 滑块内的勾：颜色只随选中/禁用变（A1 的 `Selected*IconColor` 都是 `OnPrimaryContainer`）， + // 所以静态求值；未选中态官方图标色 = 轨道色（画了也看不见），因此不画。 + let at_rest = paint::switch(ui, selected, source.get()); + let glyph: Element<'a, M> = match at_rest.icon { + Some(ink) => super::super::layout::centered_fixed( + geometry.icon, + geometry.icon, + // 盒 16 ≠ RENDER_PX(24)：必须按 16 烘焙，否则线宽被布局压细（复审 r1 P2-2）。 + icons::view_at::(IconKind::Check, ink, geometry.icon), + ), + None => Spacer::new().into(), + }; + + // 滑块（颜色跟态走：hover/pressed 是 `PrimaryContainer`） + let thumb = container(glyph) + .width(Length::Fixed(thumb_side)) + .height(Length::Fixed(thumb_side)) + .align_x(Alignment::Center) + .align_y(Alignment::Center) + .style(source.container_style(move |state| { + Frame { + fill: Some(paint::switch(ui, selected, state).thumb), + outline: None, + stroke: 0.0, + radius: thumb_side / 2.0, + } + .container_style() + })); + + // Ø40 状态层（围着滑块，圆心与滑块同心） + let layer_side = geometry.state_layer; + let layer = container(thumb) + .width(Length::Fixed(layer_side)) + .height(Length::Fixed(layer_side)) + .align_x(Alignment::Center) + .align_y(Alignment::Center) + .style(source.container_style(move |state| { + Frame { + fill: paint::switch_layer(ui, state, selected), + outline: None, + stroke: 0.0, + radius: layer_side / 2.0, + } + .container_style() + })); + + // 轨道（52×32；未选中态有 2px `Outline` 描边） + let track = container(Spacer::new()) + .width(Length::Fixed(geometry.track_width)) + .height(Length::Fixed(geometry.track_height)) + .style(source.container_style(move |state| { + paint::switch(ui, selected, state).track.container_style() + })); + + // 绘制区 = 轨道 + 状态层外扩；两层叠放（层序：轨道在下，滑块与状态层在上） + let draw_width = geometry.draw_width(); + let draw_height = geometry.draw_height(); + let area = iced::widget::stack![ + container(track) + .width(Length::Fixed(draw_width)) + .height(Length::Fixed(draw_height)) + .padding(Padding { + left: geometry.bleed(), + ..Padding::default() + }) + .align_y(Alignment::Center), + container(layer) + .width(Length::Fixed(draw_width)) + .height(Length::Fixed(draw_height)) + .padding(Padding { + left: geometry.layer_offset(selected, thumb_side), + ..Padding::default() + }), + ] + .width(Length::Fixed(draw_width)) + .height(Length::Fixed(draw_height)); + + let mut content = row![area] + .align_y(Alignment::Center) + .spacing(ui.space(Space::X3)); + if !spec.label.is_empty() { + let style = ui.style(TypeRole::BodyMedium); + content = content.push( + text(spec.label) + .size(style.size_px) + .font(ui.font_of(style)) + .color(paint::label(ui, source.get())), + ); + } + + let body = container(content) + .height(Length::Fill) + .align_y(Alignment::Center); + + shell::shell( + &source, + Length::Shrink, + Length::Fixed(geometry.hit), + spec.on_toggle, + body.into(), + ) +} diff --git a/crates/app-iced/src/components/selection/tests.rs b/crates/app-iced/src/components/selection/tests.rs new file mode 100644 index 0000000..3bb995b --- /dev/null +++ b/crates/app-iced/src/components/selection/tests.rs @@ -0,0 +1,358 @@ +//! 选择类家族的单测：几何取自令牌、角色取自 A1（`#[cfg(test)]` 下的纯值断言）。 +//! +//! **这些测试测的是「值与映射」**——它们抓不住「函数对、图错」（M68 的教训）， +//! 像素级几何在 `components/gallery/selection.rs` 的 `probe` 里对着真截图量。 + +use unlucky_design::color::{Role, SchemeFlavor}; +use unlucky_design::typography::Platform; + +use super::super::interaction::{self, Interaction}; +use super::geometry::{ChipGeometry, ControlGeometry, SwitchGeometry}; +use super::paint::{self, ChipVariant}; +use crate::theme::{Families, Ui}; + +const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", +}; + +fn ui() -> Ui { + Ui::with_platform(SchemeFlavor::Light, Platform::Windows, FAMILIES) +} + +/// 复审 P2-2：命中区恒 **48×48**——Ø40 状态层之外左右各 4dp 透明内边距（无标签时行宽才不是 40）。 +#[test] +fn hit_area_is_48_square_even_without_a_label() { + let ui = ui(); + for (name, geometry) in [ + ("checkbox", ControlGeometry::checkbox(&ui)), + ("radio", ControlGeometry::radio(&ui)), + ] { + assert_eq!(geometry.hit, 48.0, "{name} 命中区必须是 48"); + assert_eq!(geometry.state_layer, 40.0, "{name} 状态层 Ø40"); + assert_eq!(geometry.hit_padding(), 4.0, "{name} 左右各留 4dp"); + assert_eq!( + geometry.state_layer + geometry.hit_padding() * 2.0, + geometry.hit, + "{name}：可见 40 + 左右各 4 = 命中 48" + ); + } +} + +/// §18.1 / §18.5 / §18.9：Checkbox 的四个参考值全部来自令牌层。 +#[test] +fn checkbox_geometry_comes_from_the_token_layer() { + let ui = ui(); + let g = ControlGeometry::checkbox(&ui); + assert_eq!(g.side, 20.0, "18.1：容器 20×20（ContainerWidth=18 是死值）"); + assert_eq!(g.radius, 2.0, "18.1：圆角 2（ComponentRadius::Micro）"); + assert_eq!(g.stroke, 2.0, "18.2：未选中描边 2px"); + assert_eq!(g.state_layer, 40.0, "18.5：状态层 Ø40"); + assert_eq!(g.hit, 48.0, "18.9：命中区 48"); + assert_eq!(g.gap, 8.0, "18.9：框↔标签 8（[估] 团队口径）"); + assert_eq!(g.inner_dot, 0.0, "Checkbox 没有内点"); + // 18.4：勾形横向端点跨度 = 0.8−0.2 = 0.6 × 20 = 12 + assert!((g.check_span() - 12.0).abs() < 0.001, "18.4：勾横向 12dp"); + // 方头外扩：每端 2/√2 ≈ 1.41 → 墨迹跨度 ≈ 14.8（参考值 12 是端点跨度，不是墨迹） + let bleed = g.square_cap_bleed(); + assert!( + (bleed - std::f32::consts::SQRT_2).abs() < 0.001, + "方头外扩 1/√2×线宽" + ); + assert!( + (g.check_span() + bleed * 2.0 - 14.83).abs() < 0.05, + "墨迹跨度 ≈14.83" + ); +} + +/// §19.1 / §19.2：Radio 外圈 20、环线 2、**内点 10 不是 12**、真圆。 +#[test] +fn radio_inner_dot_is_ten_not_twelve() { + let ui = ui(); + let g = ControlGeometry::radio(&ui); + assert_eq!(g.side, 20.0, "19.1：外圈直径 20"); + assert_eq!(g.stroke, 2.0, "19.1：环线 2px"); + assert_eq!(g.radius, 10.0, "19.1：真圆（半径 = 边长/2）"); + assert_eq!(g.inner_dot, 10.0, "19.2：内点可视直径 10"); + assert_ne!( + g.inner_dot, 12.0, + "19.2：12 是含描边前的名义值，抄 12 会明显偏大" + ); + assert_eq!(g.state_layer, 40.0, "19.7：状态层 Ø40"); + assert_eq!(g.hit, 48.0, "19.7：命中区 48"); +} + +/// §10.1 / §10.2 / §10.6：Switch 的三档滑块与状态层，以及「状态层必然溢出轨道」这条布局不变量。 +#[test] +fn switch_geometry_matches_the_tokens() { + let ui = ui(); + let g = SwitchGeometry::of(&ui); + assert_eq!(g.track_width, 52.0, "10.1：轨道宽 52"); + assert_eq!(g.track_height, 32.0, "10.1：轨道高 32"); + assert_eq!(g.track_stroke, 2.0, "10.3：未选中态 2px Outline"); + assert_eq!(g.thumb(false, false), 16.0, "10.2：未选中滑块 16"); + assert_eq!(g.thumb(true, false), 24.0, "10.2：选中滑块 24"); + assert_eq!(g.thumb(false, true), 28.0, "10.2：按下滑块 28"); + assert_eq!(g.thumb(true, true), 28.0, "10.2：按下档与选中无关"); + assert_eq!( + g.icon, 16.0, + "10.5：滑块内图标 16（官方 SwitchTokens.SelectedIconSize，令牌 IconSize::SwitchThumb）" + ); + assert_eq!( + g.icon, + unlucky_design::icons::IconSize::SwitchThumb.px(), + "滑块图标必须走 SwitchThumb 档，不许借按钮的 18" + ); + assert_eq!(g.state_layer, 40.0, "10.6：状态层 Ø40"); + assert_eq!(g.hit, 48.0, "命中区 48"); + + // 内距公式在三个档位都成立（32−24=8→4、32−16=16→8、32−28=4→2） + for thumb in [24.0, 16.0, 28.0] { + assert!((g.thumb_inset(thumb) * 2.0 + thumb - g.track_height).abs() < 0.001); + } + // 状态层必然溢出轨道左右：未选中时滑块靠左、选中时靠右 + assert_eq!(g.bleed(), 4.0, "状态层比轨道高 → 上下各溢出 4"); + assert_eq!(g.draw_width(), 60.0, "绘制区宽 = 52 + 2×4"); + for (selected, thumb) in [(false, 16.0), (true, 24.0), (false, 28.0), (true, 28.0)] { + let offset = g.layer_offset(selected, thumb); + assert!( + offset >= 0.0, + "状态层左缘不得为负（selected={selected} thumb={thumb} → {offset}）" + ); + // 圆心与滑块同心：offset + 半径 = 滑块圆心 + 外扩 + let center = offset + g.layer_radius(); + assert!((center - (g.thumb_center(selected, thumb) + g.bleed())).abs() < 0.001); + } +} + +/// §13.1 / §13.3 / §13.4：Chip 高 32、圆角 8、内边距 8、图标 18（官方 `AssistChipTokens.IconSize`，G14 已收口）。 +#[test] +fn chip_geometry_matches_the_tokens() { + let ui = ui(); + let g = ChipGeometry::of(&ui); + assert_eq!(g.height, 32.0, "13.1：容器高 32"); + assert_eq!(g.radius, 8.0, "13.1：圆角 8（ContainerShape=CornerSmall）"); + assert_eq!(g.pad, 8.0, "13.3：水平内边距 8"); + assert_eq!(g.gap, 8.0, "13.3：元素间距 8"); + // 旧期望 16 记的是 G14 偏离（令牌层当时没有 18 档）；令牌补齐后官方值 18 才是对的 + // ——AAR `AssistChipTokens.IconSize = 18.0d`，12b 13.4 也写 18。这不是「把期望改成实现」， + // 是偏离被取消。 + assert_eq!( + g.icon, 18.0, + "13.4：图标 18（官方 AssistChipTokens.IconSize）" + ); + assert_eq!( + g.icon, + unlucky_design::icons::IconSize::Button.px(), + "chip 图标与按钮图标同源（令牌 IconSize::Button）" + ); +} + +/// §18.2 / A1：未选中 Checkbox 在 hover/focus/pressed 下描边提到 `OnSurface`（不是 `OnSurfaceVariant`）。 +#[test] +fn checkbox_unselected_lifts_the_outline_to_on_surface() { + let ui = ui(); + let g = ControlGeometry::checkbox(&ui); + let at_rest = paint::checkbox(&ui, false, false, Interaction::Enabled, g.radius, g.stroke); + assert_eq!( + at_rest.frame.outline, + Some(ui.color(Role::OnSurfaceVariant)) + ); + for state in [ + Interaction::Hovered, + Interaction::Focused, + Interaction::Pressed, + ] { + let lifted = paint::checkbox(&ui, false, false, state, g.radius, g.stroke); + assert_eq!( + lifted.frame.outline, + Some(ui.color(Role::OnSurface)), + "A1：{state:?} 的 UnselectedOutlineColor = OnSurface" + ); + assert_eq!(lifted.frame.stroke, 2.0, "18.8：描边宽度不随态变"); + } + // 错误态优先于 hover + let error = paint::checkbox(&ui, false, true, Interaction::Hovered, g.radius, g.stroke); + assert_eq!(error.frame.outline, Some(ui.color(Role::Error))); +} + +/// §18.8：禁用不是「变淡变细」——描边仍 2；选中禁用是 `OnSurface`@38% 容器 + `Surface` 勾。 +#[test] +fn checkbox_disabled_keeps_the_stroke_and_uses_the_a1_roles() { + let ui = ui(); + let g = ControlGeometry::checkbox(&ui); + let unchecked = paint::checkbox(&ui, false, false, Interaction::Disabled, g.radius, g.stroke); + assert_eq!(unchecked.frame.stroke, 2.0, "18.8：禁用描边仍 2px"); + assert_eq!(unchecked.frame.fill, None, "18.8：未选中禁用内部仍透明"); + assert!( + unchecked + .frame + .outline + .is_some_and(|color| color != ui.color(Role::OnSurfaceVariant)), + "18.8：禁用描边是 OnSurface@38%，不是满档角色色" + ); + + let checked = paint::checkbox(&ui, true, false, Interaction::Disabled, g.radius, g.stroke); + assert_eq!( + checked.glyph, + ui.color(Role::Surface), + "A1：SelectedDisabledIconColor = Surface" + ); + // 复审 P2-3：**选中且禁用**的填充是 OnSurface@38%（`SelectedDisabledContainerOpacity`）， + // 不是普通禁用容器的 12%。两格差一眼就能看出来，所以逐字钉住。 + let ink38 = interaction::disabled_content_over_role(&ui, Role::OnSurface, false); + let container12 = interaction::disabled_colors(&ui, Role::Surface).0; + assert_eq!( + checked.frame.fill, + Some(ink38), + "A1：SelectedDisabledContainerOpacity = 0.38" + ); + assert_ne!( + checked.frame.fill, + Some(container12), + "选中禁用不是 12% 容器色" + ); + assert_eq!( + unchecked.frame.outline, + Some(ink38), + "同一行里未选中禁用描边与选中禁用填充是同一个 38% 叠色" + ); +} + +/// §19.4：**选中态 hover/pressed 不换环色**（只有状态层变）。 +#[test] +fn radio_keeps_primary_on_hover_when_selected() { + let ui = ui(); + let g = ControlGeometry::radio(&ui); + let primary = Some(ui.color(Role::Primary)); + for state in Interaction::ALL { + if state.is_disabled() { + continue; + } + let paint = paint::radio(&ui, true, state, g.radius, g.stroke); + assert_eq!( + paint.ring.outline, primary, + "19.4：{state:?} 环仍是 Primary" + ); + assert_eq!(paint.dot, primary, "19.4：{state:?} 点仍是 Primary"); + } + // 未选中：静息 OnSurfaceVariant → hover/focus/pressed 提到 OnSurface + let at_rest = paint::radio(&ui, false, Interaction::Enabled, g.radius, g.stroke); + assert_eq!(at_rest.dot, None, "未选中不画内点"); + assert_eq!(at_rest.ring.outline, Some(ui.color(Role::OnSurfaceVariant))); + let lifted = paint::radio(&ui, false, Interaction::Hovered, g.radius, g.stroke); + assert_eq!(lifted.ring.outline, Some(ui.color(Role::OnSurface))); +} + +/// §10.4 + A1：选中态 hover 的滑块是 `PrimaryContainer`；禁用选中滑块是 `Surface`（不透明度 1）。 +#[test] +fn switch_handle_roles_follow_the_tokens() { + let ui = ui(); + let at_rest = paint::switch(&ui, true, Interaction::Enabled); + assert_eq!(at_rest.track.fill, Some(ui.color(Role::Primary))); + assert_eq!(at_rest.thumb, ui.color(Role::OnPrimary)); + assert_eq!(at_rest.icon, Some(ui.color(Role::OnPrimaryContainer))); + + let hovered = paint::switch(&ui, true, Interaction::Hovered); + assert_eq!( + hovered.thumb, + ui.color(Role::PrimaryContainer), + "A1：选中 hover 滑块 PrimaryContainer" + ); + assert_eq!( + hovered.track.fill, + Some(ui.color(Role::Primary)), + "轨道不随 hover 变" + ); + + let off = paint::switch(&ui, false, Interaction::Enabled); + assert_eq!( + off.track.outline, + Some(ui.color(Role::Outline)), + "10.3：未选中 2px Outline" + ); + assert_eq!(off.track.stroke, 2.0); + assert_eq!( + off.thumb, + ui.color(Role::Outline), + "10.4：未选中滑块 Outline" + ); + assert_eq!(off.icon, None, "未选中态图标与轨道同色（不画）"); + + let disabled = paint::switch(&ui, true, Interaction::Disabled); + assert_eq!( + disabled.thumb, + ui.color(Role::Surface), + "A1：DisabledSelectedHandleColor=Surface" + ); +} + +/// §13.5 / §13.6 / §13.7：选中态**无描边**、Assist 不可选中、禁用文字 @38%。 +#[test] +fn chip_roles_follow_the_tokens() { + let ui = ui(); + let radius = ChipGeometry::of(&ui).radius; + + let selected = paint::chip(&ui, ChipVariant::Filter, true, Interaction::Enabled, radius); + assert_eq!( + selected.frame.fill, + Some(ui.color(Role::SecondaryContainer)) + ); + assert_eq!(selected.frame.outline, None, "13.5：选中描边 0dp"); + assert_eq!(selected.label, ui.color(Role::OnSecondaryContainer)); + + let unselected = paint::chip( + &ui, + ChipVariant::Filter, + false, + Interaction::Enabled, + radius, + ); + assert_eq!( + unselected.frame.outline, + Some(ui.color(Role::OutlineVariant)) + ); + assert_eq!(unselected.label, ui.color(Role::OnSurfaceVariant)); + + // Assist 没有选中态：即使传 selected = true 也不会变 SecondaryContainer + let assist = paint::chip(&ui, ChipVariant::Assist, true, Interaction::Enabled, radius); + assert_ne!(assist.frame.fill, Some(ui.color(Role::SecondaryContainer))); + assert_eq!( + assist.icon, + ui.color(Role::Primary), + "13.4：Assist 前置图标 Primary" + ); + + let disabled = paint::chip( + &ui, + ChipVariant::Filter, + false, + Interaction::Disabled, + radius, + ); + assert_ne!(disabled.label, unselected.label, "13.7：禁用文字降到 38%"); +} + +/// 状态层只在三态存在，且**不是**满档角色色（α 由 `interaction` 给）。 +#[test] +fn state_layer_only_exists_on_lifted_states() { + let ui = ui(); + for (state, expected) in [ + (Interaction::Enabled, false), + (Interaction::Hovered, true), + (Interaction::Focused, true), + (Interaction::Pressed, true), + (Interaction::Disabled, false), + ] { + let layer = paint::state_layer(&ui, state, Role::OnSurfaceVariant); + assert_eq!(layer.is_some(), expected, "{state:?} 的状态层有无"); + if let Some(color) = layer { + assert_eq!(color.a, 1.0, "状态层必须是实色（D27：CPU/GPU 一致）"); + } + } + // 同态下 hover 比 pressed 浅（8% < 10%） + let hover = paint::state_layer(&ui, Interaction::Hovered, Role::OnSurface).unwrap(); + let pressed = paint::state_layer(&ui, Interaction::Pressed, Role::OnSurface).unwrap(); + assert_ne!(hover, pressed); +} diff --git a/crates/app-iced/src/fonts.rs b/crates/app-iced/src/fonts.rs new file mode 100644 index 0000000..74c5b5e --- /dev/null +++ b/crates/app-iced/src/fonts.rs @@ -0,0 +1,302 @@ +//! 字体基座（D28 前半）：把令牌的字体栈求值成「本机真的有的族名」，并打一行启动日志。 +//! +//! ## 做什么 +//! +//! 1. 取 `Platform::current()` 的三条栈（Display / Text / Mono，见 `unlucky_design::typography`）； +//! 2. 用 iced 的**全局字体系统**（`iced_graphics::text::font_system()`，即 cosmic-text 的 +//! `FontSystem`，首次调用会扫系统字体）核对每个族名是否装机 → 取栈里第一个装机可用的族； +//! 3. 给出 400/500/700 三档字重的落点（原生 / 最近档 / 合成加粗）： +//! **先查系统里这个族真实提供的字面（fontdb 的 `FaceInfo.weight`）**，查不到才回落到令牌的 +//! 纯函数 `Platform::resolve_weight`。缺档按降级记录。 +//! +//! ## 为什么要真查系统 +//! +//! 令牌栈写的是「Win11 有 Segoe UI Variable Text」，但 Win10 / Server 只有 `Segoe UI`（静态 +//! 300/400/600/700，**没有 500**），干净安装的 Linux 可能一个都没有。只按栈头写死族名会把 +//! 「实际使用哪个族、哪一档字重」变成猜测——本 mission 的开发机就是 Windows Server 2025， +//! 实测就回退到了经典 `Segoe UI`（见交接文档的启动日志）。 + +//! ## 不做什么 +//! +//! **中文字体 CDN 下载不在这里**（后续 mission）。本模块只做「系统字体优先」这一半， +//! 也没有能力判断 CJK 字形覆盖（那是 `ttf-parser` 查 cmap 的活，M60 Q3 的 spike 做过）。 +//! +//! ## 中文那一半（M92 / D28 后半） +//! +//! 语言探测 + 「中文环境有没有中文字体」的判据在 [`cjk`]（判据本体在零依赖的 `unlucky_i18n::font`）， +//! 语言的真值源是 [`crate::platform::locale`]（Windows 上 `reg.exe` 读注册表，零 FFI）， +//! 结论作为 [`Resolved::cjk`] 进同一行启动日志。**英文环境结论恒为 `NotNeeded`**：不要求中文字体、 +//! 不下载任何字体（系统里已有的 CJK 族照旧躺在 iced 的字体库里，我们既不注册新的也删不掉——那是 +//! cosmic-text 的全局状态，不是本模块能管的事）。 + +mod cjk; + +use cjk::CjkReport; +use unlucky_design::typography::{FontFamily, Platform, Weight, WeightMatch}; + +use crate::theme::Families; + +/// 一条栈的求值结果。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct FamilyReport { + /// 栈的用途（`text` / `display` / `mono`）。 + pub stack: &'static str, + /// 实际选中的族名（栈里第一个装机可用的；都没装就是栈头）。 + pub family: &'static str, + /// 选中的族是否真的在系统字体库里。 + pub installed: bool, +} + +/// 一档字重的求值结果。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct WeightReport { + /// 请求的字重（400/500/700）。 + pub requested: u16, + /// 实际可用的字重（降级后）。 + pub available: u16, + /// 匹配质量（原生 / 最近档 / 合成加粗）。 + pub quality: WeightMatch, +} + +/// 字体求值的全部结论（启动日志与测试都用它）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Resolved { + /// 平台（决定栈与字重覆盖表）。 + pub platform: Platform, + /// 三条栈的落点。 + pub families: [FamilyReport; 3], + /// 三档字重的落点（对**正文**栈求值）。 + pub weights: [WeightReport; 3], + /// 语言 + 中文环境的中文字体策略（D28；英文环境恒为 `NotNeeded`）。 + pub cjk: CjkReport, +} + +impl Resolved { + /// 把结论塞回主题适配层要的形状。 + pub fn families(&self) -> Families { + Families { + text: self.families[0].family, + display: self.families[1].family, + mono: self.families[2].family, + } + } + + /// 是否有任何一档走了「合成加粗」（= 观感降级，要记日志）。 + pub fn has_synthetic(&self) -> bool { + self.weights + .iter() + .any(|weight| weight.quality == WeightMatch::Synthetic) + } + + /// 启动日志（**一行**：族 / 字重 / 语言与中文字体策略）。 + pub fn describe(&self) -> String { + let families = self + .families + .iter() + .map(|report| { + format!( + "{}={:?}{}", + report.stack, + report.family, + if report.installed { + "" + } else { + "(未装机→回落)" + } + ) + }) + .collect::>() + .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) +} + +/// 同 [`resolve`]，但把配置里 `ui.language` 的显式值喂给中文策略（D28 的第一级）。 +pub fn resolve_with(setting: Option<&str>) -> Resolved { + let platform = Platform::current(); + let faces = system_faces(); + + let is_installed = |family: &str| -> bool { + faces + .as_ref() + .is_none_or(|faces: &Vec| faces.iter().any(|face| face.family == family)) + }; + + let families = [ + FamilyReport { + stack: "text", + family: pick(platform, FontFamily::Text, &is_installed), + installed: is_installed(pick(platform, FontFamily::Text, &is_installed)), + }, + FamilyReport { + stack: "display", + family: pick(platform, FontFamily::Display, &is_installed), + installed: is_installed(pick(platform, FontFamily::Display, &is_installed)), + }, + FamilyReport { + stack: "mono", + family: pick(platform, FontFamily::Mono, &is_installed), + installed: is_installed(pick(platform, FontFamily::Mono, &is_installed)), + }, + ]; + + // 字重：**优先用系统里这个族真实提供的档位**（令牌表的 `WeightCoverage` 是「这个族通常有哪几档」， + // 装机版可能是静态子集：Win Server / 精简版只有经典 Segoe UI，没有 500）。查不到才回落到令牌纯函数。 + let weights = [Weight::Regular, Weight::Medium, Weight::Bold] + .map(|weight| weight_report(platform, families[0].family, weight, faces.as_deref())); + + // D28 后半：语言 + 中文环境的中文字体策略。`faces` 的 `None` 在这里是「字体库读不出来」， + // 适配层会把它翻成 `Unprobeable` 而不是「缺字体」（否则会误触发一次 CDN 下载）。 + let cjk_report = cjk::probe_with(setting, faces.as_deref()); + + Resolved { + platform, + families, + weights, + cjk: cjk_report, + } +} + +/// 语言切换后的中文策略重算（M106）：`setting` 是配置里 `ui.language` 的**显式值** +/// （`None` = 跟随系统，由 [`crate::platform::locale::SystemLocale`] 决定）。 +/// +/// 为什么需要它：启动那一轮（[`resolve`]）拿不到配置，只按系统 locale 判。用户在英文系统上 +/// 手选「简体中文」时，若不复算，策略会停在 `NotNeeded`——界面文字是中文、字体却没有中文字形， +/// 那就是白块。复算出的 `NeedsDownload` 是 D28 的**信号**（下载器仍是 `Source::PendingPin`， +/// 见 `unlucky_i18n::font`），本 crate 只负责把它打进日志、不让它静默。 +pub fn cjk_for(setting: Option<&str>) -> CjkReport { + cjk::probe_with(setting, system_faces().as_deref()) +} + +/// 一条系统字面（族名 + 字重）。 +#[derive(Debug, Clone, PartialEq, Eq)] +struct Face { + family: String, + weight: u16, +} + +/// 某档字重的落点：先问系统，再问令牌。 +fn weight_report( + platform: Platform, + family: &str, + weight: Weight, + faces: Option<&[Face]>, +) -> WeightReport { + let requested = weight.value(); + + let available = faces.and_then(|faces| { + let mut weights = faces + .iter() + .filter(|face| face.family == family) + .map(|face| face.weight) + .collect::>(); + 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/cjk.rs b/crates/app-iced/src/fonts/cjk.rs new file mode 100644 index 0000000..346f6f4 --- /dev/null +++ b/crates/app-iced/src/fonts/cjk.rs @@ -0,0 +1,188 @@ +//! 中文环境的 CJK 字体探测（D28 后半）：把 iced 系统字体库里的族名喂给 `unlucky_i18n::font::decide`。 +//! +//! ## 分工 +//! +//! - **判据**（要不要中文字体、哪些族算候选、缺了要不要下载）全在 `unlucky_i18n::font`，是纯函数， +//! 零 UI 依赖、脱机可测； +//! - **语言**从 [`unlucky_i18n::lang::resolve`] 拿：`ui.language` 显式值 > [`SystemLocale`] +//! （Windows 读注册表，零 FFI）> 环境变量 > 英文； +//! - **本模块只做适配**：把 [`super::Face`] 列表变成一个「某族装没装」的查询，并处理 +//! **读不到字体库**这种情况。 +//! +//! ## 为什么「读不到」不等于「需下载」 +//! +//! `system_faces()` 拿不到字体库时返回 `None`。把它当成「没有中文字体」会直接触发一次 CDN 下载 +//! （D28 的自动下载路径），而真相是**我们不知道**。所以这一路走 [`Strategy::Unprobeable`]： +//! 日志里留痕，不下载、不弹提示。 +//! +//! ## 诚实边界（抓得住什么 / 抓不住什么） +//! +//! - **抓得住**：语言 + 字体库族名 → 策略（含 `Unprobeable` 这一支）；优先级顺序（注入的假源可测）； +//! - **抓不住**：①族名存在 ≠ 字形覆盖（`SimSun` 也可能是个残缺子集）。真判据要开 `ttf-parser` +//! 查 cmap，本 mission 不引依赖（M60 Q3 spike 做过，结论见 `DevDocs`）； +//! ②下载与注册（`Strategy::NeedsDownload` 只是信号，`Source::PendingPin` 还没钉 URL/哈希）。 +//! +//! ## `ui.language` 的接线（M106） +//! +//! 启动编排（`app/boot.rs`）那一拍只按系统 locale 判（`fonts::resolve` → `probe_with(None, ..)`）；真正的 +//! `ui.language` 在 `App` 构造/切语言时读到，随后走 `fonts::cjk_for(setting)` 复算一次并打日志。 +//! 所以「英文系统上手动切中文」也会得到 `needs-download` 而不是 `not-needed`——白块那条路被堵住了。 + +use unlucky_i18n::font::{self, Strategy}; +use unlucky_i18n::lang::{self, Detection, EnvLocale}; + +use super::Face; +use crate::platform::locale::SystemLocale; + +/// 一次中文探测的结论（启动日志的第二段）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct CjkReport { + /// 语言探测（含原始 locale 与来源，便于解释「为什么是英文」）。 + pub detection: Detection, + /// 字体策略结论。 + pub strategy: Strategy, +} + +impl CjkReport { + /// 一行日志片段（`lang=zh-CN locale=zh-CN source=registry cjk=system:"Microsoft YaHei"`）。 + pub fn describe(&self) -> String { + format!("{} {}", self.detection.describe(), self.strategy.describe()) + } +} + +/// 用给定语言 + 字体库内容做判定。 +/// +/// `faces` 为 `None` = 字体库读不出来（→ [`Strategy::Unprobeable`]，**不是**「需下载」）。 +pub fn report(detection: Detection, faces: Option<&[Face]>) -> CjkReport { + let strategy = faces.map_or(Strategy::Unprobeable, |faces| { + let is_installed = |family: &str| faces.iter().any(|face| face.family == family); + font::decide(detection.lang, &is_installed) + }); + + CjkReport { + detection, + strategy, + } +} + +/// 探测本机：优先级见 [`unlucky_i18n::lang::resolve`]。 +/// +/// `setting` 是配置里 `ui.language` 的原文（`zh_cn` / `en_us`）；`None` = **配置里没写过这个键** +/// （= 跟随系统，不是「没读」）。注意 `None` 与 `Some("不认识的值")` 效果相同：都不当显式选择， +/// 继续往下走。 +pub fn probe_with(setting: Option<&str>, faces: Option<&[Face]>) -> CjkReport { + report(lang::resolve(setting, &SystemLocale, &EnvLocale), faces) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn faces(families: &[&str]) -> Vec { + families + .iter() + .map(|family| Face { + family: (*family).to_owned(), + weight: 400, + }) + .collect() + } + + fn zh() -> Detection { + Detection { + lang: unlucky_i18n::Lang::ZhCn, + raw: Some("zh-CN".to_owned()), + origin: "injected", + } + } + + fn en() -> Detection { + Detection { + lang: unlucky_i18n::Lang::En, + raw: Some("en-US".to_owned()), + origin: "injected", + } + } + + #[test] + fn chinese_host_with_a_cjk_font_uses_the_system_one() { + // 抓得住：适配层把字体库查反/查漏（例如只按第一个族判断、或把 `Segoe UI` 当候选）。 + // 抓不住：这台机器实测有没有这个族（测试用的是注入的假字面表）。 + let installed = faces(&["Segoe UI", "Microsoft YaHei", "Cascadia Mono"]); + let report = report(zh(), Some(&installed)); + assert_eq!( + report.strategy, + Strategy::System { + family: "Microsoft YaHei" + } + ); + assert_eq!( + report.describe(), + "lang=zh-CN locale=zh-CN source=injected cjk=system:\"Microsoft YaHei\"" + ); + } + + #[test] + fn chinese_host_without_cjk_fonts_gets_the_download_signal() { + // 抓得住：D28 的「中文环境扫不到 → 要下载」这条路（信号必须能被日志看出来）。 + // 抓不住：信号之后的下载与提示（本 mission 不联网，页面也没接）。 + let latin_only = faces(&["Segoe UI", "Roboto"]); + let report = report(zh(), Some(&latin_only)); + assert_eq!( + report.strategy, + Strategy::NeedsDownload(&unlucky_i18n::font::NOTO_SANS_SC) + ); + assert!(report + .describe() + .contains("cjk=needs-download(Noto Sans SC)")); + } + + #[test] + fn english_host_never_asks_for_a_chinese_font() { + // 抓得住：英文环境的「零字体负担」（D28）——系统里有没有中文字体都不影响结论。 + // 抓不住：程序真的没去读那些字体文件（那是 iced/cosmic-text 的加载行为）。 + assert_eq!(report(en(), Some(&[])).strategy, Strategy::NotNeeded); + assert_eq!( + report(en(), Some(&faces(&["Microsoft YaHei"]))).strategy, + Strategy::NotNeeded + ); + } + + #[test] + fn unreadable_font_database_is_unknown_not_missing() { + // 抓得住：把「读不到字体库」错判成「缺字体」——那会在探测失败时触发一次多余的 CDN 下载。 + // 抓不住：真的读不到字体库时的运行行为（那条路径要 poisoned lock，测试造不出来）。 + let report = report(zh(), None); + assert_eq!(report.strategy, Strategy::Unprobeable); + assert!( + report.describe().ends_with("cjk=unprobeable"), + "{}", + report.describe() + ); + } + + #[test] + fn explicit_setting_overrides_the_platform_source() { + // 抓得住：`ui.language` 显式值被平台源盖掉（用户手选中文/英文必须赢过系统语言）； + // 也让「平台源真的接在链路上」有个不依赖本机语言的证据。 + // 抓不住：`ui.language` 在真机上读到什么（那一级由 `App` 读配置后经 `fonts::cjk_for` 喂进来）。 + let installed = faces(&["Microsoft YaHei"]); + + let forced_english = probe_with(Some("en_us"), Some(&installed)); + assert_eq!(forced_english.detection.lang, unlucky_i18n::Lang::En); + assert_eq!( + forced_english.detection.origin, + unlucky_i18n::lang::ORIGIN_SETTING + ); + assert_eq!(forced_english.strategy, Strategy::NotNeeded); + + let forced_chinese = probe_with(Some("zh_cn"), Some(&installed)); + assert_eq!( + forced_chinese.strategy, + Strategy::System { + family: "Microsoft YaHei" + } + ); + assert!(forced_chinese.describe().contains("source=setting")); + } +} diff --git a/crates/app-iced/src/fonts/tests.rs b/crates/app-iced/src/fonts/tests.rs new file mode 100644 index 0000000..5616c58 --- /dev/null +++ b/crates/app-iced/src/fonts/tests.rs @@ -0,0 +1,175 @@ +//! `fonts` 的单元测试（拆出来只为「src 文件 ≤400 行」的门禁）。 + +use super::cjk::CjkReport; +use super::*; +use unlucky_design::typography::WeightCoverage; +use unlucky_i18n::font::Strategy; +use unlucky_i18n::lang::Detection; + +fn only(installed: &'static [&'static str]) -> impl Fn(&str) -> bool { + move |family| installed.contains(&family) +} + +#[test] +fn windows_stack_falls_back_to_classic_segoe_when_variable_is_absent() { + // Win10 没有 Segoe UI Variable Text + let family = pick( + Platform::Windows, + FontFamily::Text, + &only(&["Segoe UI", "Microsoft YaHei UI"]), + ); + assert_eq!(family, "Segoe UI"); +} + +#[test] +fn windows_stack_prefers_the_variable_face_on_win11() { + let family = pick( + Platform::Windows, + FontFamily::Text, + &only(&["Segoe UI Variable Text", "Segoe UI"]), + ); + assert_eq!(family, "Segoe UI Variable Text"); +} + +#[test] +fn generic_family_names_are_never_reported_as_the_resolved_family() { + // 一个都没装：返回栈头，且栈头不是通用族名 + let family = pick(Platform::Linux, FontFamily::Text, &only(&[])); + assert_eq!(family, "Roboto"); + assert!(!is_generic(family)); +} + +#[test] +fn missing_cjk_fonts_do_not_change_the_latin_pick() { + // 装了苹方但没装 SF：macOS 栈应该选 Helvetica Neue 而不是中文族 + let family = pick( + Platform::MacOs, + FontFamily::Text, + &only(&["PingFang SC", "Helvetica Neue"]), + ); + assert_eq!(family, "Helvetica Neue"); +} + +#[test] +fn weight_reports_use_the_token_degradation_path() { + // 没有系统字面表时回落到令牌纯函数：Windows 栈里 Segoe UI Variable Text 是可变 300..700 + let medium = weight_report( + Platform::Windows, + "Segoe UI Variable Text", + Weight::Medium, + None, + ); + assert_eq!(medium.requested, 500); + assert_eq!(medium.quality, WeightMatch::Native); + + // 手工构造一个「只有 400/700」的族（= 经典 Segoe UI），500 应该落到最近档 + let faces = [ + Face { + family: "Segoe UI".to_owned(), + weight: 400, + }, + Face { + family: "Segoe UI".to_owned(), + weight: 700, + }, + ]; + let medium = weight_report(Platform::Windows, "Segoe UI", Weight::Medium, Some(&faces)); + assert_eq!(medium.available, 400, "400 比 700 更近"); + assert_eq!(medium.quality, WeightMatch::Nearest); + + // 只有 400 却要 700 → 合成加粗 + let only_regular = [Face { + family: "Narrow".to_owned(), + weight: 400, + }]; + let bold = weight_report( + Platform::Windows, + "Narrow", + Weight::Bold, + Some(&only_regular), + ); + assert_eq!(bold.quality, WeightMatch::Synthetic); + + // 原生有 500 就用 500 + let has_medium = [Face { + family: "Noto".to_owned(), + weight: 500, + }]; + assert_eq!( + weight_report(Platform::Linux, "Noto", Weight::Medium, Some(&has_medium)).quality, + WeightMatch::Native + ); + + let narrow = WeightCoverage::Static(&[400]); + assert_eq!(narrow.nearest(700), 400); +} + +#[test] +fn describe_is_one_line_and_mentions_all_three_stacks() { + let resolved = Resolved { + platform: Platform::Windows, + families: [ + FamilyReport { + stack: "text", + family: "Segoe UI", + installed: true, + }, + FamilyReport { + stack: "display", + family: "Segoe UI Variable Display", + installed: false, + }, + FamilyReport { + stack: "mono", + family: "Cascadia Mono", + installed: true, + }, + ], + weights: [ + WeightReport { + requested: 400, + available: 400, + quality: WeightMatch::Native, + }, + WeightReport { + requested: 500, + available: 400, + quality: WeightMatch::Nearest, + }, + WeightReport { + requested: 700, + available: 400, + quality: WeightMatch::Synthetic, + }, + ], + cjk: CjkReport { + detection: Detection { + lang: unlucky_i18n::Lang::En, + raw: None, + origin: unlucky_i18n::lang::ORIGIN_DEFAULT, + }, + strategy: Strategy::NotNeeded, + }, + }; + + let line = resolved.describe(); + assert_eq!(line.lines().count(), 1); + assert!(line.contains("text=\"Segoe UI\""), "{line}"); + assert!(line.contains("未装机"), "{line}"); + assert!(line.contains("w700=400(synthetic)"), "{line}"); + assert!(line.contains("cjk=not-needed"), "英文环境要进日志：{line}"); + assert!(resolved.has_synthetic()); + assert_eq!(resolved.families().text, "Segoe UI"); +} + +#[test] +fn type_roles_pick_the_display_stack_for_big_text() { + use unlucky_design::typography::TypeRole; + + assert_eq!( + TypeRole::TitleLarge.style().family, + FontFamily::Display, + "22px 标题走 Display 栈" + ); + assert_eq!(TypeRole::BodyMedium.style().family, FontFamily::Text); +} diff --git a/crates/app-iced/src/icons.rs b/crates/app-iced/src/icons.rs new file mode 100644 index 0000000..b431060 --- /dev/null +++ b/crates/app-iced/src/icons.rs @@ -0,0 +1,400 @@ +//! 令牌图标（`unlucky_design::icons` 的 24 网格 SVG path）→ iced `svg` 控件。 +//! +//! ## 为什么走 SVG 而不是自绘 canvas +//! +//! 令牌里存的是 **SVG path 字符串**（含 `A` 弧线命令），自绘要自己写 path parser + 弧线细分， +//! 那是一份将来只有自己在维护的代码；iced 的 `svg` 控件已经带 usvg 解析与按 id 缓存的位图。 +//! 代价是二进制多一份 resvg/usvg（体积基线里会单列出来）。 +//! +//! ## 描边语义（`design-令牌约定.md` §4） +//! +//! 令牌的 `Icon::stroke_width(render_px)` 已经把「视觉 1.5px」折算成 **viewBox 单位** +//! （`1.5 × 24 / render_px`），本模块**不重算也不手抄常数**。 +//! +//! ## ⚠️ 渲染尺寸**不是**一个全局值（M86 收口） +//! +//! **盒子多宽就按多宽烘焙**，规则只有两条： +//! +//! | 盒尺寸 | 用哪个入口 | +//! |---|---| +//! | **等于** [`RENDER_PX`]（24） | [`view`]（导航、卡片头、表单、IconButton…） | +//! | **不等于** 24（按钮 18 / chip 18 / switch 滑块 16 / 标题栏 caption 20） | **[`view_at`]（必须）** | +//! +//! 尺寸只有一个来源：`unlucky_design::icons` 的令牌（[`IconSize`] / +//! [`unlucky_design::icons::TITLEBAR_CAPTION_ICON_PX`]）——本文件里不许出现 `18.0` / `20.0` / `24.0` +//! 这类字面量，也不许把某个组件的尺寸「凑」进 [`RENDER_PX`]。 +//! +//! **为什么必须按盒烘焙**：`stroke-width` 是 viewBox 单位，同一个 viewBox 线宽在更小的盒子里 +//! 视觉更细。把 24px 烘焙的位图塞进 18px 盒子，视觉线宽会从 1.5px 掉到 **1.125px** +//! （复审 r1 实测 1.04~1.25px，而同屏 caption 的 20px 走 [`view_at`] 实测正好 1.50px）。 +//! 所以：**每个用到的尺寸各缓存一份**，缓存键是 `(图标种类, 渲染尺寸)`——但「缓存支持多尺寸」 +//! 不等于「调用点都用上了」，**不等于 24 的盒子一律走 [`view_at`]** 才是这条的落点。 + +use std::collections::HashMap; +use std::sync::{Mutex, OnceLock}; + +use iced::widget::svg; +use iced::Color; + +use unlucky_design::icons::{IconKind, IconPaint, IconSize}; + +/// 图标缓存键里的尺寸精度（px × 100 取整），避免拿 f32 做哈希键。 +const PX_KEY_SCALE: f32 = 100.0; + +/// 骨架期图标的默认渲染尺寸（12b：标题栏与导航轨都是 24；`SmallIconButtonTokens.IconSize = 24`）。 +pub const RENDER_PX: f32 = IconSize::Toolbar.px(); + +/// 标题栏 caption 三键（最小化 / 最大化 / 关闭）的图标边长。 +/// +/// **项目偏离**（用户点名）：官方 `SmallIconButtonTokens.IconSize = 24`，这里 20；容器 46×48 不动。 +/// 值只在令牌层定义一次（`unlucky_design::icons::TITLEBAR_CAPTION_ICON_PX`），本文件只是转口。 +pub const CAPTION_PX: f32 = unlucky_design::icons::TITLEBAR_CAPTION_ICON_PX; + +/// 生成一个图标的 SVG 源码（`viewBox` 24×24，颜色用 `currentColor` 交给 iced 的色滤镜）。 +/// +/// 之所以用 `currentColor` 而不是把令牌色写进 SVG：色滤镜（`svg::Style::color`）会按 +/// **alpha 蒙版**重涂 RGB，这样一份 SVG 位图能被浅/深两套主题复用，缓存不会翻倍。 +/// +/// `render_px` 决定两件事：SVG 的 `width`/`height` 属性与 `stroke-width` 的 viewBox 折算， +/// 两者必须同源，否则线宽会被二次缩放（见模块文档最后一段）。 +pub fn source(kind: IconKind, render_px: f32) -> String { + let icon = kind.icon(); + let paint = match icon.paint { + IconPaint::Stroke => format!( + "fill=\"none\" stroke=\"currentColor\" stroke-width=\"{}\" \ + stroke-linecap=\"round\" stroke-linejoin=\"round\"", + icon.stroke_width(render_px) + ), + IconPaint::Fill => "fill=\"currentColor\" stroke=\"none\"".to_owned(), + }; + + format!( + "", + 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..2638a5a --- /dev/null +++ b/crates/app-iced/src/lib.rs @@ -0,0 +1,62 @@ +//! # unlucky-app-iced · iced 版桌面壳（P4 / D26） +//! +//! 本 crate 是「UI 从头写」的第一步：**只做骨架**（能开窗、颜色/字体对、层级在）， +//! 业务页面、组件库、i18n 全文案、玻璃 shader 都是后续 mission。 +//! +//! | 模块 | 职责 | 不负责 | +//! |---|---|---| +//! | [`theme`] | 令牌（`unlucky-design`）→ iced 类型：`Color` / `Font` / `Radius` / `Theme` | 发明令牌值 | +//! | `cli` | `--renderer` / `--software-renderer` / `--theme` / `--screenshot*` 参数 | 业务开关 | +//! | `probe` | 渲染后端探测（D27）+ 写 `ICED_BACKEND`，失败自动降级 CPU | 绘制 | +//! | `fonts` | 字体栈求值（D28 前半）：平台族名 → 系统字体库校验 → 启动日志 | 中文字体下载 | +//! | `renderer` | **渲染后端判据表**（M97）+ wgpu 预检 + `log` 桥：什么条件选 wgpu / 什么时候降级 CPU / 日志该长什么样 | 实际绘帧 | +//! | `app` / `shell` | Elm 三件套 + 自绘标题栏 / 导航轨 / 内容骨架 | 业务逻辑 | +//! | `shot` | `window::screenshot` → PNG（验收通道） | 图像比对 | +//! | `icons` | 令牌里的 SVG path → iced `svg` 控件 | 画新图标 | +//! | [`ui`] | 界面语言的入口层（M106）：`LangState` = 用户档位 + 探测结论，目录由它选 | 翻译（那是 `unlucky-i18n`） | +//! | `platform` | 平台窗口能力（D36）：整窗 α 的纯判据 + win32 FFI（补分层样式 + 下发 α）—— **全仓唯一** `unsafe` 落点 | 窗口创建 / 业务开关 | +//! +//! ## 消费纪律 +//! +//! **组件层零硬编码色值/字号/半径/间距**：一律走 [`theme::Ui`]。守门测试在 +//! `tests/no_hardcoded_tokens.rs`（扫 `src/**`，出现 `#RRGGBB` / `Color::from_rgb(` 即红）。 +//! +//! ## 与 Slint 版的关系 +//! +//! 并存期：`crates/app` 仍出 `unlucky-launcher`，本 crate 出 `unlucky-launcher-iced`。 +//! 等价验收后翻牌（bin 改名 + 旧 crate 降级），步骤写在 +//! `DevDocs/SubAgentsTalk/app-iced-骨架与翻牌.md`。 + +pub mod pages; +pub mod platform; +pub mod renderer; +pub mod shot; +pub mod theme; + +mod app; +mod cli; +mod fonts; +mod icons; +mod probe; +mod shell; +mod ui; + +pub use cli::{Backend, Options}; +pub use probe::Probe; + +/// 启动 UI（阻塞到窗口关闭）。渲染后端由 `probe` 在 `run()` 之前写进 `ICED_BACKEND`。 +pub fn run(options: Options) -> iced::Result { + app::run(options) +} + +/// 与 [`run`] 同义，但把命令行做成最终结论：`Options::from_env()` + 启动日志。 +/// +/// 二进制入口用 [`Options::from_env`] + [`run`] 自己拼（要额外处理 `--diff`），这个函数留给 +/// 集成测试与将来的 CLI 复用。 +/// +/// # Errors +/// 参数不合法时返回人话（不 panic、不 `exit`）。 +pub fn run_from_env() -> Result { + let options = Options::from_env()?; + Ok(run(options)) +} diff --git a/crates/app-iced/src/main.rs b/crates/app-iced/src/main.rs new file mode 100644 index 0000000..f3dad9c --- /dev/null +++ b/crates/app-iced/src/main.rs @@ -0,0 +1,103 @@ +//! 入口。所有实际逻辑在 lib（`unlucky_app_iced`）里： +//! +//! 一个二进制两种用法（M82），分发在进 UI 之前完成： +//! +//! - 被子命令命中（`instances` / `install` / `launch` / `accounts` / `sessions` / `logs` / +//! `diag` / `config` / `java` / `agent`，或 `--help` / `--version`）→ 直接转给 +//! `unlucky_cli::run`，**不初始化任何 UI**（不 probe 后端、不扫字体、不碰图形库）。 +//! 子命令表不在这里抄一份：唯一真相源是 `crates/cli` 的解析器 +//! （`unlucky_cli::cli::looks_like_cli`，本文件只调用）。 +//! - 其余参数（`--software-renderer` / `--renderer` / `--theme` / `--screenshot*` / +//! `--diff` …）：开窗跑骨架，`--screenshot` 出图后退出；`--diff ` 只读两张 PNG +//! 做逐像素对比（D30 的 GPU/CPU 几何一致性检查），不开窗。 +//! +//! 零 UI 依赖的 `ull` 仍然保留（D18）：它是唯一连 fontconfig 都不需要的产物， +//! 给服务器 / CI / Termux 这类没有图形库的机器用。 +//! +//! 退出码：`0` 成功 / `1` 截图有差异（diff 模式）或 CLI 用户错误 / `2` 参数或运行错误。 + +use std::process::ExitCode; + +use unlucky_app_iced::shot; +use unlucky_app_iced::Options; + +fn main() -> ExitCode { + let args: Vec = 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（[env]/[backend]/[window]/[font]/[theme]/[perf]/[i18n]/[caps]）\ + ，ULL_WINDOW_SIZE=1520x900 覆盖窗口尺寸" + ); + ExitCode::from(2) + } + } +} + +/// 子命令命中 CLI 就跑 CLI 并以它的退出码收尾；返回 `None` 表示「这不是 CLI 调用，去开窗」。 +/// +/// 这条路径上**不构造窗口、不探后端、不扫字体、不依赖任何图形库**（这些库缺失时同一条命令照样 +/// 跑完，实测见 packaging/README.md §7.4）。`unlucky-launcher-iced launch …` 的耗时因此与首帧无关—— +/// 这句是结构性判断，**没有重量**（原因见 §10-8）。 +/// +/// 「这条命令行算不算 CLI 调用」的判据不在这里重复：`unlucky_cli::cli::looks_like_cli` 是唯一 +/// 一处（M82 复审去重），两个 GUI 二进制都只调它，改语义不会漂。 +fn run_cli_if_requested(args: &[String]) -> Option { + 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..a7ef912 --- /dev/null +++ b/crates/app-iced/src/pages/account.rs @@ -0,0 +1,175 @@ +//! 账户页（M114）：**三轨**登录（微软正版 / 第三方皮肤站 / 本地档案）+ 账户列表 + 皮肤区。 +//! +//! ## 这一页回答什么 +//! +//! 用户的原话是「用户管理页面还没做吗？包括不限于正版登录 离线登录 第三方皮肤站登录」。 +//! Slint 版曾有这个页面（`DevDocs/ops/screens-m43/account-data.png`），换 iced 时没搬过来， +//! 于是 iced 版**一个账户入口都没有**——本页就是把它补回来，并按 M114 的口径做成三轨。 +//! +//! ## 四条红线（都在本页的断言里） +//! +//! | 红线 | 落点 | +//! |---|---| +//! | 页面不得出现任何 token / refresh_token | 上屏文案只来自 [`model`] 的公开字段；`tests` 里有「把 JWT 塞进事件、断言模型干净」的用例 | +//! | 离线档案的说明必须带「仅本地/隔离网络测试用，无法连接启用正版验证的服务器」 | `Key::AccountTrackOfflineBody` / `Key::AccountOfflineWarning` 两处都写全 | +//! | 设备码不得只转圈 | [`login`]：用户码 + 链接 + 倒计时 + 「已过期，重试」 | +//! | 没有皮肤不给假皮肤 | 头像位 = 首字母块（`profile_id` 稳定取色）；第三方轨才可能出真图 | +//! +//! ## 模块 +//! +//! | 文件 | 职责 | +//! |---|---| +//! | [`model`] | 状态 → 视图模型（列表行 / 当前账户 / 三条轨道的面板态） | +//! | [`avatar`] | 首字母块 + 皮肤图（解码/裁剪缓存；失败一律退回首字母块，**绝不白块**） | +//! | [`widgets`] | 本页的小件（头像块 / 章节标题 / 徽标），样式全部走令牌 | +//! | [`rows`] | 当前账户卡片 + 账户列表行 | +//! | [`forms`] | 三条轨道的入口卡 + 本地档案/第三方站表单 | +//! | [`login`] | 微软登录面板（设备码倒计时 / 浏览器授权 / 失败态） | +//! | `tests` | 视图模型的判据（凭据红线、空态、倒计时、皮肤回落） | + +pub mod avatar; +pub mod forms; +pub mod login; +pub mod model; +pub mod panels; +pub mod rows; +pub mod widgets; + +#[cfg(test)] +mod tests; +#[cfg(test)] +#[path = "account/tests_text.rs"] +mod tests_text; + +pub use model::{Form, Hint, Notice, Page, Panel, Track}; + +use iced::widget::{column, container, scrollable}; +use iced::{Element, Length, Padding}; + +use unlucky_design::spacing::Space; +use unlucky_i18n::{Key, Lang}; + +use crate::app::components::buttons::{self, Button}; +use crate::pages::frame::{self, Header}; +use crate::pages::layout::FrameMetrics; +use crate::theme::Ui; + +use super::Message as PageMessage; + +/// 账户页的页面消息（app 层把它翻成 `AppCommand` / 状态写入）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum Message { + /// 打开某条轨道的表单 + Open(Track), + /// 关掉表单/登录面板 + Close, + /// 第三方站地址输入 + Server(String), + /// 登录名输入 + Login(String), + /// 密码输入（只存在内存里，随请求交给 host，用完即弃） + Password(String), + /// 本地档案名输入 + OfflineName(String), + /// 校验服务器地址（服务发现） + Probe, + /// 表单提交（本地档案 → 建档案；第三方站 → 登录） + Submit, + /// 微软：设备码流 + StartDevice, + /// 微软：授权码流（拉起系统浏览器） + StartBrowser, + /// 取消/关掉登录面板 + Cancel, + /// 复制一段文本（用户码 / 链接） + Copy(String), + /// 切换当前启动账户 + Switch(String), + /// 删除账户 + Remove(String), + /// 重新登录（按账户类型分派：微软 → 授权码流；第三方 → 预填表单；离线 → 明确说明） + Relogin(String), + /// 展开/收起「Add an account」的三张轨道卡（复审 r1 P2-4） + ToggleAdd, + /// 关掉横幅 + DismissNotice, +} + +impl Message { + /// 包成页面的消息（本模块内部与 app 层都用它，保证只有一处包装点）。 + pub fn into_page(self) -> PageMessage { + PageMessage::Account(self) + } +} + +/// 整页。 +pub fn view<'a>( + ui: &'a Ui, + metrics: FrameMetrics, + page: &'a Page, + lang: Lang, +) -> Element<'a, PageMessage> { + let text = lang.catalog(); + let subtitle = text.text(Key::AccountSubtitle); + let add = text.text(Key::AccountEmptyAction); + let header = Header::new(text.text(Key::AccountTitle)) + .subtitle(subtitle) + .action(buttons::tonal( + ui, + Button::new(add, Message::ToggleAdd.into_page()), + )); + + let top = if page.rows.is_empty() { + forms::empty(ui, text, lang) + } else { + column![ + rows::active_card(ui, page, text, lang), + rows::list(ui, page, text, lang), + ] + .spacing(ui.space(Space::X6)) + .into() + }; + + // 三条轨道入口 + 表单/登录面板：面板存在时**只画面板**，且**置顶**—— + // 否则在 1180×760 下设备码的「复制用户码 / 取消」会掉到折线以下（D30 复审实测）。 + let flows = match page.panel { + Panel::None => forms::tracks(ui, text, lang), + _ => forms::panel(ui, page, text, lang), + }; + + let mut content = column![].spacing(ui.space(Space::X6)).width(Length::Fill); + if let Some(notice) = &page.notice { + content = content.push(widgets::banner(ui, notice, text)); + } + if let Some(hint) = page.hint { + content = content.push(widgets::hint(ui, hint, page, text)); + } + // 三张轨道卡：空态**总是**画（那就是空态的入口）；有账号时收在「Add an account」后面 + let show_tracks = page.panel == Panel::None && (page.rows.is_empty() || page.form.section_open); + content = if page.panel == Panel::None { + if show_tracks { + content.push(top).push(flows) + } else { + content.push(top) + } + } else { + content.push(flows).push(top) + }; + + // 右缘留 8px gutter：全局 `frame::scroll_style` 的滚动条是 6px + 2px 内缩， + // 满宽卡片会被它压住（tower 看图意见 ②）。页面级留白是这条的最小修法。 + let padded = container(content).width(Length::Fill).padding(Padding { + right: ui.space(Space::X2), + ..Padding::default() + }); + + frame::page( + ui, + metrics, + header, + scrollable(padded) + .style(frame::scroll_style(ui)) + .width(Length::Fill) + .height(Length::Fill), + ) +} diff --git a/crates/app-iced/src/pages/account/avatar.rs b/crates/app-iced/src/pages/account/avatar.rs new file mode 100644 index 0000000..d180dbe --- /dev/null +++ b/crates/app-iced/src/pages/account/avatar.rs @@ -0,0 +1,229 @@ +//! 头像位与皮肤区：**首字母块**（无皮肤时）与**真图**（第三方轨抓到皮肤时）。 +//! +//! ## 为什么头像可以「真有图」 +//! +//! presenter 只把皮肤的 **PNG 原图**送到 UI（它不引入图片解码依赖），裁剪/缩放全部在这里做： +//! Minecraft 皮肤的头部在 `(8,8)` 的 8×8 方块（64×64 皮肤），帽子层在 `(40,8)`， +//! 两层贴起来再放大到 64×64 就是一张真正的头像。**解码失败一律退回首字母块**—— +//! 头像位不允许出现白块（M114 明文要求）。 +//! +//! ## 依赖口径 +//! +//! 用的是 `crates/app-iced/Cargo.toml` **既有**的 `image`（png feature，M93 背景图那一条）， +//! 本 mission 没有改任何依赖表。 + +use std::collections::BTreeMap; + +use iced::widget::image; + +use unlucky_presenter::dto::SkinImage; + +/// 头像边长（像素）：列表行 40、当前账户卡片 56 共用同一张 64 的图（缩下来仍然清晰）。 +const HEAD_PX: u32 = 64; +/// 皮肤原图的头部坐标（64×64 皮肤的标准布局）。 +const FACE: (u32, u32) = (8, 8); +/// 帽子/头发层的坐标（叠在脸上一层）。 +const HAT: (u32, u32) = (40, 8); +/// 头部方块边长（8×8）。 +const FACE_EDGE: u32 = 8; + +/// 一个账户的解码结果（失败就是两个 `None`，UI 画首字母块）。 +#[derive(Debug, Clone, Default, PartialEq)] +pub struct Avatar { + /// 裁好的头像（64×64 RGBA） + pub head: Option, + /// 皮肤原图（皮肤预览区用） + 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..17a9455 --- /dev/null +++ b/crates/app-iced/src/pages/account/login.rs @@ -0,0 +1,352 @@ +//! 微软登录面板：设备码（用户码 + 链接 + **倒计时** + 过期重试）与授权码（浏览器 + 可复制链接 + 取消）。 +//! +//! ## 为什么不是「一个转圈」 +//! +//! 设备码流的等待期可以长到 15 分钟。只画转圈的话，用户既不知道要做什么、也不知道还剩多久， +//! 更不知道已经过期了——M114 把这三件事都做成可见状态：用户码（可复制）、链接（可复制/打开）、 +//! 倒计时（`{secs}s left`）与过期后的「已过期，重试」。授权码流同理，另外必须能**取消**。 + +use iced::widget::{column, row}; +use iced::{Alignment, Element}; + +use unlucky_design::color::Role; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; +use unlucky_i18n::{Catalog, Key}; +use unlucky_presenter::dto::LoginFailure; + +use crate::app::components::buttons::{self, Button}; +use crate::pages::frame; +use crate::theme::Ui; + +use crate::pages::account::model::DevicePanel; +use crate::pages::Message as PageMessage; + +use super::Message as Account; + +/// 微软登录面板。 +pub fn panel<'a>( + ui: &'a Ui, + device: &'a DevicePanel, + catalog: Catalog, +) -> Element<'a, PageMessage> { + match device { + DevicePanel::Hidden => idle(ui, catalog), + DevicePanel::Requesting => requesting(ui, catalog), + DevicePanel::Code { + code, + link, + remaining, + expired, + } => device_code(ui, code, link, *remaining, *expired, catalog), + DevicePanel::Browser { + link, + remaining, + expired, + } => browser(ui, link, *remaining, *expired, catalog), + DevicePanel::Failed { failure } => failed(ui, *failure, catalog), + DevicePanel::Succeeded { name } => succeeded(ui, name, catalog), + } +} + +/// 空闲：给出两条流的入口（GUI 默认授权码流，设备码是备选）。 +fn idle<'a>(ui: &'a Ui, catalog: Catalog) -> Element<'a, PageMessage> { + let body = column![row![ + buttons::filled( + ui, + Button::new( + catalog.text(Key::AccountDeviceBrowser), + Account::StartBrowser.into_page(), + ) + ), + buttons::outlined( + ui, + Button::new( + catalog.text(Key::AccountDeviceUseCode), + Account::StartDevice.into_page(), + ) + ), + buttons::text( + ui, + Button::new( + catalog.text(Key::AccountDeviceCancel), + Account::Close.into_page() + ) + ), + ] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Center),] + .spacing(ui.space(Space::X3)); + frame::card(ui, body) +} + +/// 「正在申请」：一句 i18n 状态 + 取消。 +/// +/// presenter 那边的进度串是中文诊断（只进日志），面板态里**根本没有**这个字段可画。 +fn requesting<'a>(ui: &'a Ui, catalog: Catalog) -> Element<'a, PageMessage> { + let body = column![ + frame::text_role( + ui, + TypeRole::BodyMedium, + false, + catalog.text(Key::AccountDeviceRequesting), + ui.color(Role::OnSurfaceVariant), + ), + row![buttons::text( + ui, + Button::new( + catalog.text(Key::AccountDeviceCancel), + Account::Cancel.into_page() + ) + )] + .align_y(Alignment::Center), + ] + .spacing(ui.space(Space::X3)); + frame::card(ui, body) +} + +/// 设备码等待态：**码 + 链接 + 倒计时**。 +fn device_code<'a>( + ui: &'a Ui, + code: &'a str, + link: &'a str, + remaining: Option, + expired: bool, + catalog: Catalog, +) -> Element<'a, PageMessage> { + let mut actions = row![ + buttons::tonal( + ui, + Button::new( + catalog.text(Key::AccountDeviceCodeCopy), + Account::Copy(code.to_string()).into_page(), + ) + ), + buttons::outlined( + ui, + Button::new( + catalog.text(Key::AccountDeviceLinkCopy), + Account::Copy(link.to_string()).into_page(), + ) + ), + ] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Center); + + if expired { + actions = actions.push(buttons::filled( + ui, + Button::new( + catalog.text(Key::AccountDeviceRetry), + Account::StartDevice.into_page(), + ), + )); + } + actions = actions.push(buttons::text( + ui, + Button::new( + catalog.text(Key::AccountDeviceCancel), + Account::Cancel.into_page(), + ), + )); + + let countdown = countdown_line(ui, remaining, expired, catalog); + + let body = column![ + frame::text_role( + ui, + TypeRole::LabelMedium, + false, + catalog.text(Key::AccountDeviceCodeLabel), + ui.color(Role::OnSurfaceVariant), + ), + frame::text_role( + ui, + TypeRole::HeadlineSmall, + true, + code, + ui.color(Role::OnSurface), + ), + frame::text_role( + ui, + TypeRole::BodySmall, + false, + link, + ui.color(Role::OnSurfaceVariant), + ), + countdown, + frame::text_role( + ui, + TypeRole::BodySmall, + false, + catalog.text(Key::AccountDeviceHint), + ui.color(Role::OnSurfaceVariant), + ), + actions, + ] + .spacing(ui.space(Space::X3)); + frame::card(ui, body) +} + +/// 授权码等待态：浏览器已拉起，链接可复制；过期可重试。 +fn browser<'a>( + ui: &'a Ui, + link: &'a str, + remaining: Option, + expired: bool, + catalog: Catalog, +) -> Element<'a, PageMessage> { + let mut actions = row![buttons::outlined( + ui, + Button::new( + catalog.text(Key::AccountDeviceLinkCopy), + Account::Copy(link.to_string()).into_page(), + ) + )] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Center); + if expired { + actions = actions.push(buttons::filled( + ui, + Button::new( + catalog.text(Key::AccountDeviceRetry), + Account::StartBrowser.into_page(), + ), + )); + } + actions = actions.push(buttons::text( + ui, + Button::new( + catalog.text(Key::AccountDeviceCancel), + Account::Cancel.into_page(), + ), + )); + + let body = column![ + frame::text_role( + ui, + TypeRole::BodyMedium, + false, + catalog.text(Key::AccountDeviceBrowserHint), + ui.color(Role::OnSurface), + ), + frame::text_role( + ui, + TypeRole::BodySmall, + false, + link, + ui.color(Role::OnSurfaceVariant), + ), + countdown_line(ui, remaining, expired, catalog), + actions, + ] + .spacing(ui.space(Space::X3)); + frame::card(ui, body) +} + +/// 倒计时 / 过期提示（**这一行是「不得只转圈」的落点**）。 +fn countdown_line<'a>( + ui: &'a Ui, + remaining: Option, + expired: bool, + catalog: Catalog, +) -> Element<'a, PageMessage> { + if expired { + return frame::text_role( + ui, + TypeRole::LabelMedium, + true, + catalog.text(Key::AccountDeviceExpired), + ui.color(Role::Error), + ); + } + let text = remaining.map_or_else(String::new, |secs| { + // mm:ss（`15:00 left`）而不是 `900s left`：人读的是分秒，而且不随语言换格式 + // （数字与冒号在两种语言里同形，只有 `left`/`剩` 走 catalog）。 + let clock = format!("{:02}:{:02}", secs / 60, secs % 60); + catalog.render(Key::AccountDeviceCountdown, &[("time", &clock)]) + }); + // 运行时格式化的串走 `text_role_owned`（`text_role` 只借 `&'a str`） + frame::text_role_owned( + ui, + TypeRole::LabelMedium, + false, + text, + ui.color(Role::OnSurfaceVariant), + ) +} + +/// 失败态：**M3 内联 alert**（左侧 `ErrorContainer` 图标块 + 标题/正文/Code + 重试/关闭）。 +/// +/// 两条修订叠在这里： +/// - **语言泄漏（r1 p1）**：只画原因码对应的 i18n + 一行 `Code: …`，后端中文原文不上屏； +/// - **不许通栏实心红（tower r2）**：面板底走 `SurfaceContainerHigh` + 描边， +/// `ErrorContainer`/`OnErrorContainer` 只作左侧图标块的强调（角色不变，面积收小）。 +fn failed<'a>(ui: &'a Ui, failure: LoginFailure, catalog: Catalog) -> Element<'a, PageMessage> { + let body = catalog.text(failure_body_key(failure)).to_string(); + let code = catalog.render(Key::AccountFailureCode, &[("code", failure.code())]); + let actions = vec![ + buttons::tonal( + ui, + Button::new( + catalog.text(Key::AccountDeviceRetry), + Account::StartDevice.into_page(), + ), + ), + buttons::text( + ui, + Button::new( + catalog.text(Key::AccountDialogClose), + Account::Close.into_page(), + ), + ), + ]; + super::widgets::alert( + ui, + super::widgets::Tone::Error, + catalog.text(Key::AccountLoginFailed), + body, + Some(code), + actions, + ) +} + +/// 成功态。 +fn succeeded<'a>(ui: &'a Ui, name: &'a str, catalog: Catalog) -> Element<'a, PageMessage> { + // 成功也走 key + 参数（名字是 `{name}` 参数）——presenter 不再拼任何人类可读句子 + // （复审 r1 P1-1 那条「报告与代码不符」的收口：`已登录：{name}` 这类拼接全部消失）。 + let text = catalog.render(Key::AccountLoginSucceeded, &[("name", name)]); + let body = column![ + frame::text_role_owned( + ui, + TypeRole::BodyMedium, + true, + text, + ui.color(Role::OnSurface), + ), + row![buttons::text( + ui, + Button::new( + catalog.text(Key::AccountDialogClose), + Account::Close.into_page() + ) + )] + .align_y(Alignment::Center), + ] + .spacing(ui.space(Space::X3)); + frame::card(ui, body) +} + +/// 原因码 → i18n 正文 key（页面里唯一的「码→文案」映射点）。 +pub(super) fn failure_body_key(failure: LoginFailure) -> Key { + match failure { + LoginFailure::Denied => Key::AccountFailureDenied, + LoginFailure::NotWhitelisted => Key::AccountFailureWhitelist, + LoginFailure::Unreachable => Key::AccountFailureUnreachable, + LoginFailure::NotAuthlibServer => Key::AccountFailureNotAuthlib, + LoginFailure::BadCredentials => Key::AccountFailureBadCredentials, + LoginFailure::NoProfile => Key::AccountFailureNoProfile, + LoginFailure::StoreFailed => Key::AccountFailureStore, + LoginFailure::Other => Key::AccountFailureOther, + } +} diff --git a/crates/app-iced/src/pages/account/model.rs b/crates/app-iced/src/pages/account/model.rs new file mode 100644 index 0000000..03d6eea --- /dev/null +++ b/crates/app-iced/src/pages/account/model.rs @@ -0,0 +1,337 @@ +//! 状态 → 账户页视图模型（页面层不认识 presenter 的其它类型，只认这里）。 +//! +//! 三条轨道在 UI 上只有三种「面板」：微软登录面板 / 第三方站表单 / 本地档案表单。 +//! 表单里那些**输入串**是纯 UI 状态，归 [`Form`]（app 层持有）；从 presenter 来的只有 +//! 账户列表、登录进度与倒计时。 + +use iced::widget::image; + +use unlucky_i18n::{Key, Lang}; +use unlucky_presenter::dto::{AccountKind, AccountNotice, AccountNoticeCode, AccountView}; +use unlucky_presenter::state::AppState; + +use super::avatar::{Avatar, Cache}; +use super::panels::{authlib_panel, device_panel}; + +pub use super::panels::{AuthlibPanel, DevicePanel}; + +/// 三条轨道。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Track { + /// 微软正版（设备码 / 授权码两条流） + Microsoft, + /// 第三方皮肤站（authlib-injector） + Authlib, + /// 本地档案（离线） + Offline, +} + +impl Track { + /// 卡片标题的 key。 + #[must_use] + pub const fn title_key(self) -> Key { + match self { + Self::Microsoft => Key::AccountTrackMicrosoftTitle, + Self::Authlib => Key::AccountTrackAuthlibTitle, + Self::Offline => Key::AccountTrackOfflineTitle, + } + } + + /// 卡片说明的 key。 + #[must_use] + pub const fn body_key(self) -> Key { + match self { + Self::Microsoft => Key::AccountTrackMicrosoftBody, + Self::Authlib => Key::AccountTrackAuthlibBody, + Self::Offline => Key::AccountTrackOfflineBody, + } + } + + /// 卡片主按钮的 key（微软/第三方是「登录」，本地是「创建档案」）。 + #[must_use] + pub const fn action_key(self) -> Key { + match self { + Self::Microsoft => Key::AccountTrackOpen, + Self::Authlib => Key::AccountTrackOpen, + Self::Offline => Key::AccountTrackCreate, + } + } + + /// 三条轨道（卡片顺序）。 + pub const ALL: [Track; 3] = [Track::Microsoft, Track::Authlib, Track::Offline]; +} + +/// 当前打开的面板。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub enum Panel { + /// 只画三条轨道入口 + #[default] + None, + /// 微软登录面板 + Microsoft, + /// 第三方站表单 + Authlib, + /// 本地档案表单 + Offline, +} + +/// 表单的**纯 UI 状态**（app 层持有，随消息改动）。 +/// +/// 密码只存在这里和「一次 `AppCommand::AddAuthlibAccount` 的载荷」里：不进日志、不进快照、 +/// 不进任何回程 DTO（M114 凭据红线）。 +/// **手写 `Debug`**：`Form` 里持着一次性密码，任何 `{:?}` 都不许带出明文（凭据红线）。 +impl std::fmt::Debug for Form { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.debug_struct("Form") + .field("panel", &self.panel) + .field("server", &self.server) + .field("login", &self.login) + .field("password", &"⟪redacted⟫") + .field("offline_name", &self.offline_name) + .field("section_open", &self.section_open) + .field("hint", &self.hint) + .finish() + } +} + +/// 三条轨道的表单输入（纯 UI 状态；密码是**一次性请求值**）。 +#[derive(Clone, Default, PartialEq, Eq)] +pub struct Form { + /// 当前面板 + pub panel: Panel, + /// 第三方站地址 + pub server: String, + /// 登录名 + pub login: String, + /// 密码（一次性的请求值） + pub password: String, + /// 本地档案名 + pub offline_name: String, + /// 「Add an account」展开态（有账号时三张轨道卡默认收起，复审 r1 P2-4） + pub section_open: bool, + /// 一次性引导（重新登录时告诉用户下一步；`None` = 没有引导） + pub hint: Option, +} + +/// 一次性引导（由 app 层在「重新登录」时设置，页面画一行 i18n）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Hint { + /// 第三方轨重登：重新输入密码 + AuthlibReauth, + /// 本地档案没有可重登的服务器账户 + OfflineNoRelogin, +} + +impl Form { + /// 空表单（只画三条轨道）。 + pub fn new() -> Self { + Self::default() + } + + /// 打开某条轨道的面板（已开着同一个就用原值，避免输入被清掉）。 + pub fn open(&mut self, track: Track) { + self.panel = match track { + Track::Microsoft => Panel::Microsoft, + Track::Authlib => Panel::Authlib, + Track::Offline => Panel::Offline, + }; + } + + /// 关掉面板（**密码一起清掉**：留着没有意义，只是多留一份凭据在内存里）。 + pub fn close(&mut self) { + self.password.clear(); + self.hint = None; + self.panel = Panel::None; + } + + /// 提交之后清掉一次性凭据（成功与否都清：重试用新输入）。 + pub fn clear_secret(&mut self) { + self.password.clear(); + } + + /// 本地档案名是否已填（`trim` 后非空才算）。 + #[must_use] + pub fn offline_ready(&self) -> bool { + // 与 host 写盘前用的是**同一份判据**（`unlucky_presenter::dto::valid_offline_name`）： + // 按钮亮着却必然失败，比按钮灰着更糟（复审 r1 P2-2 的另一半）。 + unlucky_presenter::dto::valid_offline_name(self.offline_name.trim()) + } + + /// 第三方站表单是否已填（三项都非空；地址的语法问题由 host 的规范化兜）。 + #[must_use] + pub fn authlib_ready(&self) -> bool { + !self.server.trim().is_empty() && !self.login.trim().is_empty() && !self.password.is_empty() + } +} + +/// 列表行 / 当前账户卡片用的数据。 +#[derive(Debug, Clone, PartialEq)] +pub struct Row { + /// 稳定 id（切/删/重登都按它派命令） + pub id: String, + /// 展示名 + pub name: String, + /// 首字母块的字 + pub monogram: String, + /// 首字母块色号（0..6，`profile_id` 稳定推导） + pub tone: u8, + /// 轨道 + pub kind: AccountKind, + /// 轨道文案（i18n） + pub kind_label: String, + /// 「添加于 {date}」 + pub added: String, + /// 副行：服务器 / 登录名（没有就空） + pub detail: String, + /// 是否是当前启动账户 + pub active: bool, + /// 裁好的头像（`None` = 画首字母块） + pub head: Option, + /// 皮肤原图（皮肤预览区） + 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 device = device_panel(&state.device_login, state.device_code_remaining()); + // 登录在进行（或刚失败/刚成功）时，面板**必须**是微软那条轨：否则用户点了登录、 + // 后台已经在等设备码，页面上却只剩三张入口卡——那正是「只转圈」的另一种坏法。 + let panel = if matches!(device, DevicePanel::Hidden) { + form.panel + } else { + Panel::Microsoft + }; + let (authlib, checked_server) = authlib_panel(&state.authlib_login); + // 「校验通过」的服务器名只在该面板打开且地址一致时显示（换了地址就不再是它） + let checked_server = if form.server.trim().is_empty() + || state.authlib_login.server.trim().is_empty() + || form.server.trim() != state.authlib_login.server.trim() + { + String::new() + } else { + checked_server + }; + Page { + rows, + active, + panel, + form: form.clone(), + device, + authlib, + checked_server, + notice: state.account_notice.as_ref().map(Notice::of), + hint: form.hint, + width, + } + } + + /// 当前账户行。 + #[must_use] + pub fn active_row(&self) -> Option<&Row> { + self.active.and_then(|index| self.rows.get(index)) + } + + /// 有没有账户（空态判据）。 + #[must_use] + pub fn is_empty(&self) -> bool { + self.rows.is_empty() + } + + /// 皮肤预览区要画的那张图（当前账户有皮肤才画）。 + #[must_use] + pub fn active_skin(&self) -> Option<&image::Handle> { + self.active_row().and_then(|row| row.skin.as_ref()) + } +} + +/// 单行。 +fn row_of(account: &AccountView, avatars: &mut Cache, lang: Lang) -> Row { + let text = lang.catalog(); + let avatar: Avatar = avatars.resolve(&account.id, account.skin.as_ref()); + let kind_label = match account.kind { + AccountKind::Microsoft => text.text(Key::AccountKindMicrosoft), + AccountKind::Authlib => text.text(Key::AccountKindAuthlib), + AccountKind::Offline => text.text(Key::AccountKindOffline), + }; + let detail = if !account.server_url.is_empty() { + text.render( + Key::AccountServer, + &[("server", account.server_url.as_str())], + ) + } else { + account.login_name.clone() + }; + Row { + id: account.id.clone(), + name: account.name.clone(), + monogram: account.monogram(), + tone: account.monogram_tone(), + kind: account.kind, + kind_label: kind_label.to_string(), + added: text.render(Key::AccountAddedOn, &[("date", account.created.as_str())]), + detail, + active: account.active, + head: avatar.head, + skin: avatar.skin, + } +} diff --git a/crates/app-iced/src/pages/account/panels.rs b/crates/app-iced/src/pages/account/panels.rs new file mode 100644 index 0000000..5feb6b9 --- /dev/null +++ b/crates/app-iced/src/pages/account/panels.rs @@ -0,0 +1,141 @@ +//! 两条登录流的面板态（微软设备码/授权码 + 第三方站校验/登录）。 +//! +//! 从 `model.rs` 拆出来守 400 行硬线：这些类型是「UI 要画什么」的枚举， +//! 判定逻辑（倒计时 → 已过期、服务发现 → 可用）也在这里，页面与表单只消费结果。 +//! +//! ## 为什么这里**没有** `message` / `detail` 字段（M114 r3 / 复审 r2 P2-2） +//! +//! 后端的原始诊断串是中文人话，只该进日志。r2 时它们还以 `message`/`detail` 存在于此， +//! 「页面把它们画上屏」只能靠一条**平行实现**的取样断言去拦（复审用变异证明那条断言是哑的）。 +//! 现在直接把字段删掉：视图**没有材料可画**，想画原文是编译错误——比任何测试都硬。 +//! 原文仍在 presenter 的 `DeviceLoginView/AuthlibLoginView::message` 里（只进 `eprintln!`）。 + +use unlucky_presenter::dto::{AuthlibLoginView, DeviceLoginPhase, DeviceLoginView, LoginFailure}; + +/// 微软登录面板要画什么（每态都不同，**不允许只有一个转圈**）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum DevicePanel { + /// 没有登录在跑 + Hidden, + /// 正在申请设备码（进度文案由页面按 i18n 出） + Requesting, + /// 设备码等待用户操作 + Code { + /// 用户码 + code: String, + /// 验证链接 + link: String, + /// 剩余秒数 + remaining: Option, + /// 是否已过期 + expired: bool, + }, + /// 授权码流：等浏览器回调 + Browser { + /// 授权链接（可复制） + link: String, + /// 剩余秒数 + remaining: Option, + /// 是否已过期 + expired: bool, + }, + /// 失败（**只有原因码**；原文在 presenter 的日志里） + Failed { + /// 原因码（页面据此选 i18n） + failure: LoginFailure, + }, + /// 成功 + Succeeded { + /// 账户名 + name: String, + }, +} + +/// 第三方轨面板的可见状态。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum AuthlibPanel { + /// 没在跑 + Idle, + /// 正在校验/登录 + Running, + /// 地址校验通过（服务发现拿到服务器名） + Ready { + /// 服务器名 + server_name: String, + }, + /// 失败（**只有原因码**；原文在 presenter 的日志里） + Failed { + /// 原因码（页面据此选 i18n） + failure: LoginFailure, + }, + /// 成功 + Succeeded { + /// 账户名 + name: String, + }, +} + +/// 微软登录状态 → 面板态（倒计时与「已过期」都在这里定性，UI 只画）。 +pub(super) fn device_panel(view: &DeviceLoginView, remaining: Option) -> DevicePanel { + let expired = remaining == Some(0); + match view.phase { + DeviceLoginPhase::Idle => DevicePanel::Hidden, + DeviceLoginPhase::Requesting => DevicePanel::Requesting, + DeviceLoginPhase::Waiting => { + if view.user_code.trim().is_empty() { + DevicePanel::Browser { + link: view.verification_uri.clone(), + remaining, + expired, + } + } else { + DevicePanel::Code { + code: view.user_code.clone(), + link: view.qr_link.clone(), + remaining, + expired, + } + } + } + DeviceLoginPhase::Failed => DevicePanel::Failed { + failure: view.failure.unwrap_or(LoginFailure::Other), + }, + DeviceLoginPhase::Succeeded => DevicePanel::Succeeded { + name: view.account_name.clone(), + }, + } +} + +/// 第三方轨状态 → 面板态（顺带取出「校验通过的服务器名」）。 +pub(super) fn authlib_panel(view: &AuthlibLoginView) -> (AuthlibPanel, String) { + match view.phase { + DeviceLoginPhase::Idle => (AuthlibPanel::Idle, String::new()), + DeviceLoginPhase::Requesting => (AuthlibPanel::Running, String::new()), + DeviceLoginPhase::Waiting => ( + AuthlibPanel::Ready { + server_name: view.server_name.clone(), + }, + view.server_name.clone(), + ), + DeviceLoginPhase::Succeeded => ( + AuthlibPanel::Succeeded { + name: view.account_name.clone(), + }, + view.server_name.clone(), + ), + DeviceLoginPhase::Failed => ( + AuthlibPanel::Failed { + failure: view.failure.unwrap_or(LoginFailure::Other), + }, + String::new(), + ), + } +} + +impl AuthlibPanel { + /// 是否正在跑（此时表单字段禁用，避免改了一半的地址被提交）。 + #[must_use] + pub fn busy(&self) -> bool { + matches!(self, Self::Running { .. }) + } +} diff --git a/crates/app-iced/src/pages/account/rows.rs b/crates/app-iced/src/pages/account/rows.rs new file mode 100644 index 0000000..9e29ede --- /dev/null +++ b/crates/app-iced/src/pages/account/rows.rs @@ -0,0 +1,274 @@ +//! 账户列表：当前账户卡片 + 全部账户行 + 皮肤预览区。 + +use iced::widget::{column, container, image, row, space}; +use iced::{Alignment, ContentFit, Element, Length}; + +use unlucky_design::color::Role; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; +use unlucky_i18n::{Catalog, Key, Lang}; + +use crate::app::components::buttons::{self, Button}; +use crate::pages::frame; +use crate::theme::Ui; + +use crate::pages::account::{model::Page as Model, widgets}; +use crate::pages::Message as PageMessage; + +use super::Message as Account; + +/// 当前账户卡片（含皮肤预览区）。 +pub fn active_card<'a>( + ui: &'a Ui, + page: &'a Model, + catalog: Catalog, + lang: Lang, +) -> Element<'a, PageMessage> { + let Some(current) = page.active_row() else { + return container(space::vertical()).into(); + }; + let _ = lang; + + let mut actions = row![] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Center); + actions = actions.push(buttons::text( + ui, + Button::new( + catalog.text(Key::AccountRelogin), + Account::Relogin(current.id.clone()).into_page(), + ), + )); + actions = actions.push(buttons::text( + ui, + Button::new( + catalog.text(Key::AccountRemove), + Account::Remove(current.id.clone()).into_page(), + ), + )); + + let mut name_line = row![ + frame::text_role( + ui, + TypeRole::TitleMedium, + true, + ¤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..debfc41 --- /dev/null +++ b/crates/app-iced/src/pages/account/tests.rs @@ -0,0 +1,330 @@ +//! 账户页视图模型的判据（M114 的核心断言都在这里）。 +//! +//! | 用例 | 抓得住什么 | +//! |---|---| +//! | `a_jwt_injected_into_events_never_reaches_the_page` | **凭据红线**：DTO → 状态 → 视图模型这一路漏了脱敏 | +//! | `a_failure_with_a_provider_code_renders_english_and_the_code` | **语言泄漏（r1 p1）**：模型 + i18n 查表这一路又出现中文（视图层由类型禁画原文，见 `tests_text` 的边界说明） | +//! | `the_device_code_panel_shows_a_countdown_and_expires` | 设备码「只转圈」/ 倒计时不是人话格式 | + +use unlucky_i18n::{Key, Lang}; +use unlucky_presenter::dto::{ + AccountKind, AccountNotice, AccountNoticeCode, AccountView, AppEvent, AuthlibLoginView, + CoreEvent, DeviceLoginPhase, DeviceLoginView, LoginFailure, SkinImage, +}; +use unlucky_presenter::state::AppState; + +use super::avatar::Cache; +use super::model::{DevicePanel, Form, Page, Panel, Track}; +use super::tests_text::{has_cjk, on_screen}; + +fn account(name: &str, kind: AccountKind, active: bool) -> AccountView { + AccountView { + id: format!("account:{name}"), + name: name.to_string(), + kind, + profile_id: "0f8f1d3c4b5a69788796a5b4c3d2e1f0".to_string(), + login_name: String::new(), + created: "2026-10-31 20:12".to_string(), + active, + server_url: String::new(), + skin: None, + } +} + +fn build(state: &AppState, form: &Form) -> Page { + // 断言口径是英文界面（app 钉死 `Lang::En`）：英文目录下「视图里有中文」=「后端原文上屏了」。 + // 宽度取验收窗口 1180（r2 起 `Page` 记中栏可用宽）。 + Page::build(state, form, &mut Cache::default(), Lang::En, 1180.0) +} + +const JWT: &str = + "eyJhbGciOiJSUzI1NiIsIng1dCI6IkFCQyJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.c2lnbmF0dXJlLXZhbHVl"; + +/// **凭据红线（审核项）**：把 JWT 形状串注入事件 → 状态与视图模型里都不许出现。 +/// +/// 抓得住：presenter 状态层的脱敏被删（`AppState::apply_device_login` / `apply_authlib_login`）。 +/// 视图层不在此列：面板态里已无 `message`/`detail` 字段，想画原文是编译错误。 +#[test] +fn a_jwt_injected_into_events_never_reaches_the_page() { + let mut state = AppState::new(); + state.accounts = vec![account("Steve", AccountKind::Microsoft, true)]; + // **绕过构造器**直接摆一个带 JWT 的 DTO：模拟「将来某个新构造器忘了脱敏」/「后端把原文塞进来」。 + state.apply(AppEvent::Core(CoreEvent::DeviceLoginChanged( + DeviceLoginView { + phase: DeviceLoginPhase::Failed, + message: format!("微软返回错误：accessToken={JWT} refresh_token={JWT}"), + failure: Some(LoginFailure::Denied), + ..DeviceLoginView::new() + }, + ))); + state.apply(AppEvent::Core(CoreEvent::AuthlibLoginChanged( + AuthlibLoginView { + phase: DeviceLoginPhase::Failed, + server: "https://littleskin.cn/api/yggdrasil/".to_string(), + server_name: String::new(), + message: format!("服务器回包异常 {JWT}"), + failure: Some(LoginFailure::Denied), + account_name: String::new(), + }, + ))); + + // ① 状态层已经脱敏（这一条抓得住「摘掉 state 层 redact」的变异） + assert!( + !state.device_login.message.contains("eyJ"), + "{}", + state.device_login.message + ); + assert!( + !state.authlib_login.message.contains("eyJ"), + "{}", + state.authlib_login.message + ); + + // ② 上屏文案更不可能有它（页面根本不画原文） + let text = on_screen(&build(&state, &Form::new())); + assert!(!text.contains("eyJ"), "视图里出现了 JWT：{text}"); + assert!(!text.contains("⟪redacted⟫"), "脱敏占位符也不该上屏：{text}"); +} + +/// **语言泄漏（复审 r1 p1）**：带 AADSTS 码的失败事件 → 英文取样里不许有中文，且要带 code。 +/// +/// 抓得住：`failure_body_key` 的码→key 映射被摘/接错；DTO 或状态层把中文混进模型字段。 +/// 抓不住（复审 r2 P2-2 实测过）：视图层把原文画上屏——这条断言是**平行实现**。 +/// 那道回归改由**类型**拦：`DevicePanel`/`AuthlibPanel` 已无 `message`/`detail` 字段。 +/// 也抓不住：catalog 里某条英文译文本身写得差（那只能人工审图）。 +#[test] +fn a_failure_with_a_provider_code_renders_english_and_the_code() { + let mut state = AppState::new(); + state.apply(AppEvent::Core(CoreEvent::DeviceLoginChanged( + DeviceLoginView { + phase: DeviceLoginPhase::Failed, + message: + "微软拒绝了这次登录：AADSTS7000218（HTTP 403）—— 应用白名单还没批准，或网络被拦截" + .to_string(), + failure: Some(LoginFailure::NotWhitelisted), + ..DeviceLoginView::new() + }, + ))); + let page = build(&state, &Form::new()); + let text = on_screen(&page); + assert!(!has_cjk(&text), "英文界面里出现了中文：{text}"); + assert!( + text.contains("whitelist_pending"), + "面板要给稳定 code：{text}" + ); + assert!( + text.to_lowercase().contains("approved"), + "要给出可读的英文原因：{text}" + ); + + // 第三方轨的失败同样只有 i18n + code + state.apply(AppEvent::Core(CoreEvent::AuthlibLoginChanged( + AuthlibLoginView { + phase: DeviceLoginPhase::Failed, + server: "https://example.invalid/".to_string(), + server_name: String::new(), + message: "服务器不可达：dns error".to_string(), + failure: Some(LoginFailure::Unreachable), + account_name: String::new(), + }, + ))); + let text = on_screen(&build(&state, &Form::new())); + assert!(!has_cjk(&text), "{text}"); + assert!(text.contains("unreachable"), "{text}"); +} + +/// 空态：**三条轨道都有入口**，不是一张白页；且三张卡的标题各不相同。 +#[test] +fn an_empty_account_list_offers_all_three_tracks() { + let state = AppState::new(); + let page = build(&state, &Form::new()); + assert!(page.is_empty()); + assert_eq!(page.panel, Panel::None); + assert!(page.active_row().is_none()); + let mut keys: Vec<&str> = Track::ALL + .iter() + .map(|track| track.title_key().name()) + .collect(); + keys.sort_unstable(); + keys.dedup(); + assert_eq!(keys.len(), 3); +} + +/// 设备码：**倒计时是人话格式（mm:ss）**，过期后是「已过期」而不是继续转圈。 +#[test] +fn the_device_code_panel_shows_a_countdown_and_expires() { + let mut state = AppState::new(); + state.apply(AppEvent::Core(CoreEvent::DeviceLoginChanged( + DeviceLoginView::waiting("ABCD-EFGH", "https://www.microsoft.com/link", 900, ""), + ))); + let page = build(&state, &Form::new()); + match &page.device { + DevicePanel::Code { + code, + remaining, + expired, + .. + } => { + assert_eq!(code, "ABCD-EFGH"); + assert_eq!(*remaining, Some(900)); + assert!(!expired); + } + other => panic!("等待态应该是设备码面板，实际 {other:?}"), + } + let text = on_screen(&page); + assert!(text.contains("15:00"), "倒计时要画成 mm:ss：{text}"); + assert!(!text.contains("900s"), "不再是 `900s left`：{text}"); + + // 起点往前挪 20 分钟 ⇒ 过期 + state.device_login_started = + Some(std::time::Instant::now() - std::time::Duration::from_secs(1_200)); + let page = build(&state, &Form::new()); + match &page.device { + DevicePanel::Code { + remaining, expired, .. + } => { + assert_eq!(*remaining, Some(0)); + assert!(*expired, "过期必须被标出来（面板要画「已过期，重试」）"); + } + other => panic!("过期态仍是设备码面板，实际 {other:?}"), + } + + // 授权码流也走同一条倒计时（没有用户码时是 Browser 面板） + state.apply(AppEvent::Core(CoreEvent::DeviceLoginChanged( + DeviceLoginView::browser_waiting("https://login.microsoftonline.com/x", 300, None), + ))); + let page = build(&state, &Form::new()); + assert!(matches!(page.device, DevicePanel::Browser { .. })); +} + +/// 没有皮肤 = 首字母块（不是白块、不是假皮肤）；坏图也必须回落；无皮肤时**明说**。 +#[test] +fn a_third_party_account_falls_back_to_the_monogram() { + let mut state = AppState::new(); + state.accounts = vec![ + account("Alex", AccountKind::Authlib, true), + account("Steve", AccountKind::Microsoft, false), + ]; + let page = build(&state, &Form::new()); + assert!( + page.rows.iter().all(|row| row.head.is_none()), + "没有皮肤就不许有图" + ); + assert!(page.rows.iter().all(|row| !row.monogram.is_empty())); + assert!(page.active_skin().is_none(), "皮肤预览区没有图就不画图"); + let text = on_screen(&page); + assert!(!has_cjk(&text)); + + // 塞一张坏图：解码失败 → 仍然回落到首字母块（不 panic、不白块） + state.accounts[0].skin = Some(SkinImage { + png: b"not a png".to_vec(), + source: "test".to_string(), + }); + let page = build(&state, &Form::new()); + assert!(page.rows[0].head.is_none()); +} + +/// 离线档案的说明**必须**带「无法连接启用正版验证的服务器」这条限定（中英都要）。 +#[test] +fn the_offline_track_keeps_the_agreed_wording() { + for lang in Lang::ALL { + let catalog = lang.catalog(); + for key in [Key::AccountTrackOfflineBody, Key::AccountOfflineWarning] { + let text = catalog.text(key); + assert!( + text.contains("cannot join servers that require a genuine Minecraft account") + || text.contains("无法连接启用正版验证的服务器"), + "{} 的 {key:?} 丢了「仅本地/隔离网络测试用」口径：{text}", + lang.tag() + ); + assert!( + !text.contains("migration") && !text.contains("迁移"), + "不许改写成「兼容旧启动器迁移」：{text}" + ); + } + } +} + +/// **离线轨的失败必须可见**（复审 r1 P2-2）：横幅进模型、文案走 i18n、原文不上屏。 +#[test] +fn a_failed_offline_add_is_visible() { + let mut state = AppState::new(); + state.apply(AppEvent::Core(CoreEvent::AccountNoticeChanged(Some( + AccountNotice::new( + AccountNoticeCode::OfflineNameInvalid, + "ab", + "离线名字必须是 3–16 位字母/数字/下划线，收到 \"ab\"", + ), + )))); + let page = build(&state, &Form::new()); + let notice = page.notice.as_ref().expect("失败要有横幅"); + assert_eq!(notice.code, AccountNoticeCode::OfflineNameInvalid); + assert!(notice.failure, "失败横幅要用 error 配色"); + let text = on_screen(&page); + assert!(text.contains("3–16"), "要说清规则：{text}"); + assert!(!has_cjk(&text), "英文界面不许出现中文：{text}"); +} + +/// 表单状态：三条轨道各开各的，密码关面板即清，三卡默认收起。 +#[test] +fn the_form_tracks_are_independent() { + let mut form = Form::new(); + assert!(!form.section_open, "有账号时三卡默认收起（P2-4）"); + form.open(Track::Offline); + assert_eq!(form.panel, Panel::Offline); + assert!(!form.offline_ready(), "空名字不能提交"); + form.offline_name = "ab".to_string(); + assert!( + !form.offline_ready(), + "太短也不许提交（与 host 同一条规则）" + ); + assert!( + !unlucky_presenter::dto::valid_offline_name("ab"), + "UI 判据 = host 那份规则" + ); + form.offline_name = "Alex".to_string(); + assert!(form.offline_ready()); + + form.open(Track::Authlib); + assert!(!form.authlib_ready(), "地址/登录名/密码缺一不可"); + form.server = "https://littleskin.cn/api/yggdrasil/".to_string(); + form.login = "alex".to_string(); + form.password = "hunter2".to_string(); + assert!(form.authlib_ready()); + form.clear_secret(); + assert!(form.password.is_empty()); + assert!(!form.authlib_ready()); +} + +/// 登录阶段的可判据性：Requesting / Waiting / Failed 各自映射到不同面板。 +#[test] +fn login_phases_map_to_distinct_panels() { + let mut state = AppState::new(); + state.apply(AppEvent::Core(CoreEvent::DeviceLoginChanged( + DeviceLoginView { + phase: DeviceLoginPhase::Requesting, + message: "正在向微软申请设备码…".to_string(), + ..DeviceLoginView::new() + }, + ))); + let page = build(&state, &Form::new()); + assert!(matches!(page.device, DevicePanel::Requesting)); + // 进行中也只有 i18n（不再复读 presenter 的中文状态串） + assert!(!has_cjk(&on_screen(&page))); + + state.apply(AppEvent::Core(CoreEvent::DeviceLoginChanged( + DeviceLoginView::failed("HTTP 403"), + ))); + assert!(matches!( + build(&state, &Form::new()).device, + DevicePanel::Failed { .. } + )); + + state.apply(AppEvent::Core(CoreEvent::DeviceLoginChanged( + DeviceLoginView::new(), + ))); + assert!(matches!( + build(&state, &Form::new()).device, + DevicePanel::Hidden + )); +} diff --git a/crates/app-iced/src/pages/account/tests_text.rs b/crates/app-iced/src/pages/account/tests_text.rs new file mode 100644 index 0000000..a10299b --- /dev/null +++ b/crates/app-iced/src/pages/account/tests_text.rs @@ -0,0 +1,97 @@ +//! 「**模型这一层会给出什么**」的取样器：视图模型字段 + **按码做的 i18n 查表**，拼成一串。 +//! +//! ## 边界（复审 r2 P2-2 订正，别把这条读成「视图覆盖」） +//! +//! 这是**平行实现**：它自己调 `catalog` 查表，**不调用** `login::panel` / `forms::status_line`， +//! 也不遍历 iced 的元素树。所以它证明的是「模型 + i18n 表里没有中文」，**不证明**「视图真的照它画」。 +//! +//! 视图层靠两道别的闸： +//! 1. **类型**：`DevicePanel` / `AuthlibPanel` 里**没有** `message`/`detail` 字段（r3 删掉了）， +//! 想画后端原文是编译错误，不是测试问题； +//! 2. **出图**：`DevDocs/artifacts/m114/after/*` 由人（tower/复审）逐张看。 +//! +//! 为什么单独一个文件：`pages/account/tests.rs` 贴着 400 行硬线，而这段是**纯取样** +//! （不给任何断言）——断言都在 `tests.rs` 里。 + +use unlucky_i18n::{Key, Lang}; +use unlucky_presenter::dto::AccountNoticeCode; + +use super::login::failure_body_key; +use super::model::{AuthlibPanel, DevicePanel, Hint, Page}; + +/// 页面**会画什么**：模型里的数据 + 视图层对码的 i18n 查表结果。 +pub(super) fn on_screen(page: &Page) -> String { + let catalog = Lang::En.catalog(); + let mut out = String::new(); + for row in &page.rows { + out.push_str(&row.name); + out.push_str(&row.monogram); + out.push_str(&row.kind_label); + out.push_str(&row.added); + out.push_str(&row.detail); + } + out.push_str(&page.form.offline_name); + out.push_str(&page.form.server); + if let Some(notice) = &page.notice { + // 与 `widgets::banner` 同源：码 → i18n（主题名拼进去） + out.push_str(match notice.code { + AccountNoticeCode::OfflineNameInvalid => { + catalog.text(Key::AccountNoticeOfflineNameInvalid) + } + AccountNoticeCode::AccountExists => catalog.text(Key::AccountNoticeAccountExists), + AccountNoticeCode::StoreFailed => catalog.text(Key::AccountNoticeStoreFailed), + AccountNoticeCode::NotFound => catalog.text(Key::AccountNoticeNotFound), + AccountNoticeCode::Other => catalog.text(Key::AccountNoticeOther), + AccountNoticeCode::Added => catalog.text(Key::AccountNoticeAdded), + AccountNoticeCode::Removed => catalog.text(Key::AccountNoticeRemoved), + AccountNoticeCode::Switched => catalog.text(Key::AccountNoticeSwitched), + }); + out.push_str(¬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, + remaining, + expired, + } => { + out.push_str(code); + out.push_str(link); + if *expired { + out.push_str(catalog.text(Key::AccountDeviceExpired)); + } else if let Some(secs) = remaining { + let clock = format!("{:02}:{:02}", secs / 60, secs % 60); + out.push_str(&catalog.render(Key::AccountDeviceCountdown, &[("time", &clock)])); + } + } + DevicePanel::Browser { link, .. } => out.push_str(link), + DevicePanel::Failed { failure } => { + out.push_str(catalog.text(failure_body_key(*failure))); + out.push_str(&catalog.render(Key::AccountFailureCode, &[("code", failure.code())])); + } + DevicePanel::Succeeded { name } => { + out.push_str(&catalog.render(Key::AccountLoginSucceeded, &[("name", name)])); + } + } + match &page.authlib { + AuthlibPanel::Idle => {} + AuthlibPanel::Running => out.push_str(catalog.text(Key::AccountServerChecking)), + AuthlibPanel::Ready { server_name } => out.push_str(server_name), + AuthlibPanel::Failed { failure } => out.push_str(failure.code()), + AuthlibPanel::Succeeded { name } => out.push_str(name), + } + out +} + +/// 有没有中日韩统一表意文字（语言泄漏的最直接判据）。 +pub(super) fn has_cjk(text: &str) -> bool { + text.chars().any(|c| matches!(c, '\u{3400}'..='\u{4DBF}' | '\u{4E00}'..='\u{9FFF}' | '\u{3000}'..='\u{303F}' | '\u{FF00}'..='\u{FFEF}')) +} diff --git a/crates/app-iced/src/pages/account/widgets.rs b/crates/app-iced/src/pages/account/widgets.rs new file mode 100644 index 0000000..d378036 --- /dev/null +++ b/crates/app-iced/src/pages/account/widgets.rs @@ -0,0 +1,386 @@ +//! 本页小件：头像块（首字母块 / 真图）、章节标题、轨道徽标。 +//! +//! ## 令牌纪律 +//! +//! 本文件**零**色值 / 字号 / 半径字面量：颜色一律 [`Ui::color`]，尺寸走 `Space` / +//! `LayoutMetrics` / `ui.style(..)`。首字母块的「色号」也只是**挑哪一个角色**， +//! 不是一个具体颜色——深浅两套主题各自成立。 + +use iced::widget::text::LineHeight; +use iced::widget::{container, image, row, text}; +use iced::{Alignment, Background, Border, ContentFit, Element, Length, Pixels}; + +use unlucky_design::color::Role; +use unlucky_design::component_map::Component; +use unlucky_design::elevation::MaterialLayer; +use unlucky_design::icons::IconKind; +use unlucky_design::shape::ShapeScale; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; +use unlucky_i18n::{Catalog, Key}; +use unlucky_presenter::dto::AccountNoticeCode; + +use crate::pages::frame; +use crate::pages::frame::ICON_PX; +use crate::theme::Ui; + +use crate::app::components::buttons::{self, Button}; + +use crate::pages::Message as PageMessage; +use crate::pages::Message; + +use super::model::{Hint, Notice, Row}; +use super::Message as Account; + +/// 头像块的可选尺寸（列表 40 / 当前账户 56）。 +pub const AVATAR_LIST: f32 = 40.0; +/// 当前账户卡片上的头像边长。 +pub const AVATAR_ACTIVE: f32 = 56.0; + +/// 色号 → (底色, 字色) 角色对。 +/// +/// 只有「挑角色」这一步是硬的：六个色号对应六个容器角色，深浅主题各有一套值， +/// 所以同一个账户在两种主题下都成立，也不会撞出低对比。 +fn tone(ui: &Ui, tone: u8) -> (iced::Color, iced::Color) { + match tone % 6 { + 0 => ( + ui.color(Role::PrimaryContainer), + ui.color(Role::OnPrimaryContainer), + ), + 1 => ( + ui.color(Role::SecondaryContainer), + ui.color(Role::OnSecondaryContainer), + ), + 2 => ( + ui.color(Role::TertiaryContainer), + ui.color(Role::OnTertiaryContainer), + ), + 3 => ( + ui.color(Role::SurfaceContainerHighest), + ui.color(Role::OnSurface), + ), + 4 => (ui.color(Role::PrimaryFixed), ui.color(Role::OnPrimaryFixed)), + _ => ( + ui.color(Role::SurfaceVariant), + ui.color(Role::OnSurfaceVariant), + ), + } +} + +/// 提示条的语义档（决定图标块与图标字形用哪一对角色）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Tone { + /// 失败（`ErrorContainer` / `OnErrorContainer` 图标块 + `Error` 图形） + Error, + /// 成功/信息（`SecondaryContainer` / `OnSecondaryContainer` 图标块 + `Check` 图形） + Info, +} + +/// **M3 内联提示条**（账户页横幅与登录失败面板共用）。 +/// +/// ## 为什么不是通栏实心色块（tower r2 意见） +/// +/// r1 的失败面板把 `errorContainer` 铺满整条内容宽——角色本身是对的（复审按像素采样反证过： +/// 暗色取到容器角色 30 档、浅色取到 90 档，与设计层逐值一致），但**面积**让它像一条通栏告警带。 +/// 现在改成 M3 的 alert 形态：面板底走 `SurfaceContainerHigh` + 1dp 描边， +/// `ErrorContainer` / `OnErrorContainer` 只作左侧**图标块**的强调（成功档换成 Secondary 容器）， +/// 标题用 `OnSurface`、正文与 code 行用 `OnSurfaceVariant`。语义仍由角色表达，视觉不再是红条。 +pub fn alert<'a>( + ui: &'a Ui, + tone: Tone, + title: &'a str, + body: String, + code: Option, + 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(Component::OutlinedCard.spec().shape), + ..container::Style::default() + }) + .into() +} + +/// 账户页横幅：添加/删除/切换的结果（**页面上真实可见的控件**，不是 toast）。 +/// +/// 为什么必须有它：app-iced 不渲染 toast（复审 r1 P2-2），离线名字不合法/重名/落盘失败时 +/// 用户原本什么都看不到。文案按 `AccountNoticeCode` 查 i18n，后端原文不进 UI。 +pub fn banner<'a>(ui: &'a Ui, notice: &'a Notice, catalog: Catalog) -> Element<'a, PageMessage> { + let tone = if notice.failure { + Tone::Error + } else { + Tone::Info + }; + let title = if notice.failure { + catalog.text(Key::AccountNoticeTitleFailed) + } else { + catalog.text(Key::AccountNoticeTitleDone) + }; + let message = notice_text(notice, catalog); + let dismiss = buttons::text( + ui, + Button::new( + catalog.text(Key::AccountNoticeDismiss), + Account::DismissNotice.into_page(), + ), + ); + // 只有失败才显示稳定 code（成功态列一串 `added` 是噪音） + let code = notice + .failure + .then(|| catalog.render(Key::AccountFailureCode, &[("code", notice.code.code())])); + alert(ui, tone, title, message, code, vec![dismiss]) +} + +/// 横幅文案（码 → i18n；主题名拼进带占位符的几句）。 +fn notice_text(notice: &Notice, catalog: Catalog) -> String { + let name = notice.subject.as_str(); + match notice.code { + AccountNoticeCode::Added => catalog.render(Key::AccountNoticeAdded, &[("name", name)]), + AccountNoticeCode::Removed => catalog.render(Key::AccountNoticeRemoved, &[("name", name)]), + AccountNoticeCode::Switched => { + catalog.render(Key::AccountNoticeSwitched, &[("name", name)]) + } + AccountNoticeCode::OfflineNameInvalid => catalog + .text(Key::AccountNoticeOfflineNameInvalid) + .to_string(), + AccountNoticeCode::AccountExists => { + catalog.text(Key::AccountNoticeAccountExists).to_string() + } + AccountNoticeCode::StoreFailed => catalog.text(Key::AccountNoticeStoreFailed).to_string(), + AccountNoticeCode::NotFound => catalog.text(Key::AccountNoticeNotFound).to_string(), + AccountNoticeCode::Other => catalog.text(Key::AccountNoticeOther).to_string(), + } +} + +/// 一次性引导（重新登录时告诉用户下一步）。 +pub fn hint<'a>( + ui: &'a Ui, + hint: Hint, + page: &'a super::Page, + catalog: Catalog, +) -> Element<'a, PageMessage> { + let message = match hint { + Hint::AuthlibReauth => catalog.render( + Key::AccountHintAuthlibReauth, + &[("server", page.form.server.as_str())], + ), + Hint::OfflineNoRelogin => catalog.text(Key::AccountHintOfflineNoRelogin).to_string(), + }; + container(frame::text_role_owned( + ui, + TypeRole::BodySmall, + false, + message, + ui.color(Role::OnSurfaceVariant), + )) + .width(Length::Fill) + .into() +} + +/// 头像块：有真图就画图（圆角裁切），没有就画**首字母块**。 +/// +/// 三条铁律：① 图解码失败一定回到首字母块（不白块）；② 首字母块的字来自 `AccountView::monogram`， +/// 永不空串；③ 两者尺寸完全一致，切换时不跳版。 +pub fn avatar<'a>(ui: &'a Ui, row: &Row, size: f32) -> Element<'a, Message> { + if let Some(handle) = &row.head { + return container( + image(handle.clone()) + .width(Length::Fixed(size)) + .height(Length::Fixed(size)) + .content_fit(ContentFit::Cover), + ) + .width(Length::Fixed(size)) + .height(Length::Fixed(size)) + .style(move |_theme| container::Style { + border: Border { + radius: ui.radius(ShapeScale::Full, size), + ..Border::default() + }, + ..container::Style::default() + }) + .into(); + } + monogram(ui, &row.monogram, row.tone, size) +} + +/// 首字母块（没有皮肤时的头像位）。 +pub fn monogram<'a>(ui: &'a Ui, letter: &str, tone_index: u8, size: f32) -> Element<'a, Message> { + let (background, foreground) = tone(ui, tone_index); + let style = ui.emphasized(TypeRole::TitleMedium); + container( + text(letter.to_string()) + .size(style.size_px) + .line_height(LineHeight::Absolute(Pixels(style.line_height_px))) + .font(ui.font_of(style)) + .color(foreground), + ) + .width(Length::Fixed(size)) + .height(Length::Fixed(size)) + .align_x(Alignment::Center) + .align_y(Alignment::Center) + .style(move |_theme| container::Style { + background: Some(Background::Color(background)), + border: Border { + radius: ui.radius(ShapeScale::Full, size), + ..Border::default() + }, + ..container::Style::default() + }) + .into() +} + +/// 章节标题（`TitleMedium` + 可选副文案）。 +pub fn section<'a>(ui: &'a Ui, title: &'a str, support: Option<&'a str>) -> Element<'a, Message> { + let mut column = iced::widget::column![frame::text_role( + ui, + TypeRole::TitleMedium, + true, + title, + ui.color(Role::OnSurface), + )] + .spacing(ui.space(Space::X1)); + if let Some(support) = support { + column = column.push(frame::text_role( + ui, + TypeRole::BodySmall, + false, + support, + ui.color(Role::OnSurfaceVariant), + )); + } + column.into() +} + +/// 轨道徽标（小药丸：`LabelMedium` + `SecondaryContainer`）。 +pub fn badge<'a>(ui: &'a Ui, label: &'a str, active: bool) -> Element<'a, Message> { + let (background, foreground) = if active { + ( + ui.color(Role::SecondaryContainer), + ui.color(Role::OnSecondaryContainer), + ) + } else { + ( + ui.color(Role::SurfaceContainerHighest), + ui.color(Role::OnSurfaceVariant), + ) + }; + let style = ui.style(TypeRole::LabelMedium); + container( + text(label.to_string()) + .size(style.size_px) + .line_height(LineHeight::Absolute(Pixels(style.line_height_px))) + .font(ui.font_of(style)) + .color(foreground), + ) + .padding(iced::Padding::from([0.0, ui.space(Space::X2)])) + .height(ui.metrics().control_height - ui.space(Space::X2) * 2.0) + .align_y(Alignment::Center) + .style(move |_theme| container::Style { + background: Some(Background::Color(background)), + border: Border { + radius: ui.radius(ShapeScale::Full, ui.metrics().control_height), + ..Border::default() + }, + ..container::Style::default() + }) + .into() +} + +/// 一条「标签 + 值」的元信息行（列表行副文案之外的结构化信息）。 +pub fn meta_line<'a>(ui: &'a Ui, label: &'a str, value: &'a str) -> Element<'a, Message> { + row![ + frame::text_role( + ui, + TypeRole::LabelSmall, + false, + label, + ui.color(Role::OnSurfaceVariant), + ), + frame::text_role( + ui, + TypeRole::LabelMedium, + false, + value, + ui.color(Role::OnSurface) + ), + ] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Center) + .into() +} diff --git a/crates/app-iced/src/pages/agent/conversation.rs b/crates/app-iced/src/pages/agent/conversation.rs new file mode 100644 index 0000000..84980b6 --- /dev/null +++ b/crates/app-iced/src/pages/agent/conversation.rs @@ -0,0 +1,338 @@ +//! **会话视图组件**：右栗面板与 `Route::Agent` 独立页的**同一份**对话 UI。 +//! +//! ## 输入契约（纯数据入、消息出） +//! +//! ```text +//! Conversation { messages, busy, unread, confirm, failure, draft, blank, rail, host, focus } +//! ──view()──▶ Element +//! ``` +//! +//! - **入**：全部是**借用**的纯数据。会话三件（`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/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..d706029 --- /dev/null +++ b/crates/app-iced/src/pages/appearance/background.rs @@ -0,0 +1,294 @@ +//! 背景图：**读盘解码（png / jpeg / bmp）→ 三种填充 → 暗化系数 → 可读诊断**。 +//! +//! ## 真图（M93 r2 起） +//! +//! 渲染走 iced 的 `image`（`crates/app-iced/Cargo.toml` 的 `image-without-codecs`）：`Cover` / +//! `Contain` 交给 `ContentFit`，`Tile` 用本模块的 [`tiles`] 算网格后由 `picture` 真铺图块。 +//! 本模块只负责「解码一次（取色 + 诊断 + 尺寸）」与「网格/暗化的纯数学」。 +//! +//! | 档 | 渲染 | 露底色 | +//! |---|---|---| +//! | `cover` | `ContentFit::Cover`（铺满、裁掉溢出） | 否 | +//! | `contain` | `ContentFit::Contain`（完整显示、等比） | **是**（上下或左右） | +//! | `tile` | 原图尺寸平铺（[`tiles`] 给行列数，上限 [`MAX_TILES`]） | 否（图比视口大时=裁切） | +//! +//! ## 解码只在这里（一次） +//! +//! 一张图会被两处用到：①渲染器（`image::Handle::from_path`，由 iced 自己解码；r2 实测 +//! `from_bytes` 的异步纹理分配赶不上截图第 3 帧，画面会是空的）；②取色（`unlucky_design` 要 RGBA +//! 像素，本模块把解码结果缩到 [`MAX_EDGE`] 内交给它）。本模块的解码只为「取色 + 诊断 + 尺寸」。 +//! +//! ## 暗化（`appearance.bg_dim`） +//! +//! 语义是「让背景往面板底色退」，即把版面底色（`Role::Surface`）以 α = `dim` 叠在图上—— +//! 与 `rgb + (toward − rgb) × dim` **在数学上等价**（图不透明时），所以这里只给一个钳位函数 +//! [`dim_alpha`]，真正的合成交给渲染器（CPU/GPU 两档都支持普通 alpha 混合）。 +//! 为什么向底色退而不是「叠黑」：浅色主题下叠黑会把亮图压成暗块，深色正文反而更读不清 +//! （偏离登记在 [`super`] 的偏离表 #7）。 + +use unlucky_presenter::prefs::BgFill; + +/// 暗化上限（core 的 `BG_DIM_MAX` = 0.95，经 `unlucky_presenter::prefs` 重导出；这里只给 f32 形态）。 +pub const BG_DIM_MAX: f32 = unlucky_presenter::prefs::BG_DIM_MAX as f32; + +/// 解码后保留给取色的最大边长：取色只需要色彩分布，4K 图缩到 256 边后内存从 33MB 掉到 147KB。 +pub const MAX_EDGE: u32 = 256; + +/// 解码**之前**允许的原始边长上限。 +/// +/// 复审 r1 P2-4：原来写 16_384，等于允许一张 16384×16384 的 PNG 被**整幅解成 RGBA** +/// （≈1.07 GB）再缩到 256——那是解压炸弹。现在按「真实会遇到的壁纸尺寸」定：8K（7680×4320） +/// 留一倍余量 ⇒ **8192**。再大的图直接 [`LoadError::TooLarge`] + 可读提示（不静默）。 +pub const MAX_SOURCE_EDGE: u32 = 8_192; + +/// 解码时允许的最大内存占用（`image::Limits::max_alloc`）。 +/// +/// 8192×8192 的 RGBA 是 256 MB；给到 320 MB 足够正常图，同时把「边长合法但通道数/位深 +/// 变态」的图挡在分配之前（第二道闸，第一道是 [`MAX_SOURCE_EDGE`]）。 +pub const MAX_DECODE_BYTES: u64 = 320 * 1024 * 1024; + +/// 平铺档「小图」的判据（dp）：短边低于它就一定会被放大铺，值得给一句提示。 +pub const SMALL_TILE_EDGE: f32 = 200.0; + +/// 平铺档一次最多铺多少个图块（列 × 行）。超了**放大图块**而不是少铺——见 [`tiles`] 的不变量。 +pub const MAX_TILES: u32 = 64; + +/// 图块放大步长（每次乘这个数，直到块数落进预算）。 +pub const TILE_SCALE_STEP: f32 = 1.15; + +/// 图块缩放上限（**只是安全阀**，正常情况下远达不到）。 +/// +/// 取 1024 而不是 64：`cols·rows ≤ MAX_TILES` 与「覆盖 ≥ 视口」在**极小图**上要求很大的缩放 +/// （1×1 的图在 1180×760 上要 ~118 倍才能用 64 块盖满）。取小了就等于两者不可兼得——那一侧 +/// 会退化成「留缝」，正是 r1 的 P2-1。真实图片不会走到这个上限。 +pub const MAX_TILE_SCALE: f32 = 1024.0; + +/// 解码失败的原因（人话在 [`LoadError::describe`]）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum LoadError { + /// 读文件失败：不存在 / 没权限 / 被占用。 + Io(String), + /// 解码失败：格式不认识（webp/tiff 等没开编码器）/ 文件截断 / 不是图片。 + Undecodable(String), + /// 图片头里的尺寸超限。 + TooLarge { + /// 宽。 + width: u32, + /// 高。 + height: u32, + }, +} + +impl LoadError { + /// 可读诊断（设置页提示行与日志共用同一句）。 + #[must_use] + pub fn describe(&self) -> String { + match self { + Self::Io(reason) => format!("Background image could not be read: {reason}"), + Self::Undecodable(reason) => format!( + "Background image could not be decoded ({reason}; this build decodes PNG, JPEG and BMP)" + ), + Self::TooLarge { width, height } => format!( + "Background image is too large to decode: {width}×{height} (limit {MAX_SOURCE_EDGE} px per edge)" + ), + } + } +} + +/// 一张解码好的背景图。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Image { + /// **原图**尺寸（像素）：填充几何按它算（`tile` = 原始尺寸平铺）。 + pub source: (u32, u32), + /// 缩略图宽（≤ [`MAX_EDGE`]）。 + pub width: u32, + /// 缩略图高（≤ [`MAX_EDGE`]）。 + pub height: u32, + /// 缩略图 RGBA8（取色用；`width × height × 4`）。 + pub rgba: Vec, +} + +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(format!( + "Small image ({}×{}): tiles are scaled up so the window stays covered (max {MAX_TILES} tiles, no gaps).", + image.source.0, image.source.1 + )) +} + +/// 暗化系数（叠在图上那层底色的 α）：`0` = 不暗化，上限 [`BG_DIM_MAX`]。 +#[must_use] +pub fn dim_alpha(dim: f32) -> f32 { + if dim.is_nan() { + 0.0 + } else { + dim.clamp(0.0, BG_DIM_MAX) + } +} + +/// 平铺档的网格（列 × 行 × 图块缩放）。 +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct Tiles { + /// 列数。 + pub cols: u32, + /// 行数。 + pub rows: u32, + /// 单块图相对原尺寸的缩放（`1.0` = 原尺寸；超预算时**只放大图块**，不减少覆盖）。 + pub scale: f32, +} + +impl Tiles { + /// 总块数。 + #[must_use] + pub fn count(self) -> u32 { + self.cols * self.rows + } + + /// 一块图的实际边长（dp）：`源尺寸 × scale`。 + #[must_use] + pub fn tile_size(self, source: (u32, u32)) -> (f32, f32) { + ( + source.0.max(1) as f32 * self.scale, + source.1.max(1) as f32 * self.scale, + ) + } + + /// 铺满后覆盖的宽高（dp）：**恒 ≥ 视口**（[`tiles`] 的硬不变量，单测钉住）。 + #[must_use] + pub fn covered(self, source: (u32, u32)) -> (f32, f32) { + let (w, h) = self.tile_size(source); + (self.cols as f32 * w, self.rows as f32 * h) + } +} + +/// 平铺档的网格（原图 1 像素 = 1 dp）。 +/// +/// **硬不变量：`covered >= viewport`**——任何情况都不许留缝（复审 r1 P2-1 的返工点）。 +/// +/// r1 的写法是「超预算就减列/减行」，于是 120×120 的图需要 10×7=70 块 > [`MAX_TILES`]， +/// 列数被砍到 9 ⇒ 覆盖宽 1080 < 1180，右缘 100px 裸白。现在的做法是**放大图块步长**： +/// `scale` 从 1.0 起按 [`TILE_SCALE_STEP`] 逐级变大，直到 `ceil(视口/图块) 的乘积 ≤ 预算`。 +/// 图块按同一比例放大 ⇒ 图不变形；`ceil` 保证每行/每列都盖过视口边界（多出来的部分由渲染器裁掉）。 +/// +/// 图比视口大时是 `1×1, scale=1.0`（= 以原尺寸裁切），与小图平铺是同一套算式。 +#[must_use] +pub fn tiles(source: (u32, u32), viewport: (f32, f32)) -> Tiles { + let mut tiles = Tiles { + cols: 1, + rows: 1, + scale: 1.0, + }; + + loop { + let (width, height) = tiles.tile_size(source); + tiles.cols = ceil_div(viewport.0.max(1.0), width); + tiles.rows = ceil_div(viewport.1.max(1.0), height); + if tiles.count() <= MAX_TILES || tiles.scale >= MAX_TILE_SCALE { + return tiles; + } + tiles.scale = (tiles.scale * TILE_SCALE_STEP).min(MAX_TILE_SCALE); + } +} + +fn ceil_div(value: f32, step: f32) -> u32 { + let count = (value / step).ceil(); + if count.is_finite() && count >= 1.0 { + count as u32 + } else { + 1 + } +} + +#[cfg(test)] +mod tests; diff --git a/crates/app-iced/src/pages/appearance/background/tests.rs b/crates/app-iced/src/pages/appearance/background/tests.rs new file mode 100644 index 0000000..4e69b88 --- /dev/null +++ b/crates/app-iced/src/pages/appearance/background/tests.rs @@ -0,0 +1,200 @@ +//! `background` 的单测：解码（png + jpeg）、失败分类、暗化钳位、平铺网格。 +//! +//! 每条测试的「抓得住 / 抓不住」写在注释里——这是本 mission 的验收纪律：能断言的不许只靠肉眼。 + +use super::{dim_alpha, load, small_tile_note, tiles, LoadError, BG_DIM_MAX, MAX_TILES}; +use std::path::{Path, PathBuf}; +use unlucky_presenter::prefs::BgFill; + +fn temp_file(label: &str, name: &str) -> PathBuf { + let dir = + std::env::temp_dir().join(format!("ull-bg-{label}-{}-{}", std::process::id(), line!())); + std::fs::create_dir_all(&dir).expect("临时目录"); + dir.join(name) +} + +fn cleanup(path: &Path) { + if let Some(dir) = path.parent() { + std::fs::remove_dir_all(dir).ok(); + } +} + +#[test] +fn a_real_png_decodes_with_its_original_size_and_raw_bytes() { + // 抓得住：真磁盘 PNG 能读、原图尺寸按图头、缩略图不超预算、原始字节留着给渲染器。 + // 抓不住：渲染器用这些字节画出来的颜色（那要看截图）。 + let path = temp_file("png", "bg.png"); + let source: image::RgbImage = image::RgbImage::from_pixel(300, 20, image::Rgb([12, 200, 90])); + source.save(&path).expect("写 png"); + + let image = load(path.to_str().unwrap()).expect("真 PNG 必须能读"); + assert_eq!(image.source, (300, 20)); + assert!( + image.width <= super::MAX_EDGE && image.height <= super::MAX_EDGE, + "缩略图 {}×{} 超预算", + image.width, + image.height + ); + assert_eq!(image.rgba.len(), (image.width * image.height * 4) as usize); + assert_eq!(image.rgba.len(), (image.width * image.height * 4) as usize); + cleanup(&path); +} + +/// M93 r2 的硬要求：`.jpg` 必须能加载（用户挑的背景图/壁纸多半是 jpeg）。 +/// +/// 抓得住：`image` 的 jpeg 编码器真的开了（没开时 `load` 会返回 `Undecodable`）。 +/// 抓不住：渲染器那边（`iced/image`）解码 jpeg 的能力——那条由截图矩阵里那张 jpg 出图举证。 +#[test] +fn a_real_jpeg_decodes_too() { + let path = temp_file("jpeg", "bg.jpg"); + let source = + image::RgbImage::from_fn(64, 32, |x, y| image::Rgb([x as u8 * 4, y as u8 * 8, 90])); + source + .save_with_format(&path, image::ImageFormat::Jpeg) + .expect("写 jpeg"); + + let image = load(path.to_str().unwrap()).expect("jpeg 必须能读（M93 r2）"); + assert_eq!(image.source, (64, 32)); + assert_eq!( + image.rgba.len(), + (image.width * image.height * 4) as usize, + "像素解出来了" + ); + cleanup(&path); +} + +#[test] +fn a_missing_or_broken_file_reports_a_readable_reason() { + // 抓得住：①路径不存在 → Io；②文件存在但不是图片 → Undecodable；③空路径 → Io。 + // 都必须是 Err（不许静默回默认色），且 describe() 是人话。 + // 抓不住：webp/tiff 这类没开编码器的格式具体报什么字符串（只钉分类，不钉解码库原文）。 + let missing = temp_file("missing", "bg.png"); + let error = load(missing.to_str().unwrap()).expect_err("不存在的路径必须报错"); + assert!(matches!(error, LoadError::Io(_)), "实际 {error:?}"); + assert!(error + .describe() + .starts_with("Background image could not be read")); + + let broken = temp_file("broken", "bg.png"); + std::fs::write(&broken, b"this is not an image").expect("写坏文件"); + let error = load(broken.to_str().unwrap()).expect_err("非图片必须报错"); + assert!(matches!(error, LoadError::Undecodable(_)), "实际 {error:?}"); + cleanup(&broken); + + let empty = load(" ").expect_err("空路径必须报错"); + assert!(matches!(empty, LoadError::Io(_))); +} + +#[test] +fn dim_is_clamped_to_the_supported_range() { + // 抓得住：暗化系数夹在 0..=0.95（下限允许 0 = 不暗化，上限防「背景看不见」），NaN 取 0。 + // 抓不住：0.35 这个默认值在真实壁纸上的观感（视觉判断）。 + assert_eq!(dim_alpha(0.0), 0.0); + assert_eq!(dim_alpha(0.35), 0.35); + assert_eq!(dim_alpha(-1.0), 0.0); + assert_eq!(dim_alpha(f32::NAN), 0.0); + assert_eq!(dim_alpha(9.0), BG_DIM_MAX); + assert_eq!(BG_DIM_MAX, 0.95, "与 core 同源（presenter 重导出）"); +} + +/// **P2-1 的守门**：任何尺寸/视口组合下，平铺网格铺出来的覆盖宽高都必须 ≥ 视口（不许留缝）， +/// 同时块数不超预算（不留缝的代价只能是「放大图块」，不能是「少铺」）。 +/// +/// 抓得住：谁把 `tiles()` 改回「超预算就减列」——120×120 @ 1180×760 那条会立刻红 +/// （r1 实测右缘裸白 100px）。 +/// 抓不住：渲染器把单块图铺进格子时的实际像素对齐（有没有半像素缝由截图看）。 +#[test] +fn tile_grid_always_covers_the_viewport_within_budget() { + let cases = [ + ((120, 120), (1180.0, 760.0)), + ((300, 200), (1180.0, 760.0)), + ((16, 16), (1920.0, 1080.0)), + ((8, 8), (3840.0, 2160.0)), + ((1600, 900), (1180.0, 760.0)), + ((1, 1), (1180.0, 760.0)), + ]; + for (source, viewport) in cases { + let grid = tiles(source, viewport); + let (covered_w, covered_h) = grid.covered(source); + assert!( + covered_w >= viewport.0 - 0.01 && covered_h >= viewport.1 - 0.01, + "{source:?} @ {viewport:?} 覆盖 {covered_w}×{covered_h} 小于视口（会留缝）：{grid:?}" + ); + assert!( + grid.count() <= MAX_TILES, + "{source:?} @ {viewport:?} 块数 {} 超预算", + grid.count() + ); + assert!(grid.scale >= 1.0, "图块只许放大，不许缩小：{grid:?}"); + } + + // 图比视口大 ⇒ 1×1 原尺寸裁切（scale 必须还是 1.0，否则等于缩小了原图）。 + let big = tiles((1600, 900), (1180.0, 760.0)); + assert_eq!((big.cols, big.rows, big.scale), (1, 1, 1.0)); + + // 小图按原尺寸铺够（不放大时）。 + let small = tiles((300, 200), (1180.0, 760.0)); + assert_eq!((small.cols, small.rows, small.scale), (4, 4, 1.0)); +} + +/// 编译期钉住：填充档解析走 core 的词表（`cover`/`contain`/`tile`）。 +#[test] +fn fill_keys_are_the_schema_vocabulary() { + // 抓得住：有人改了落盘词表却没改这里（截图矩阵的 env 也按这三个词传）。 + assert_eq!(BgFill::from_key_value("cover"), BgFill::Cover); + assert_eq!(BgFill::from_key_value("contain"), BgFill::Contain); + assert_eq!(BgFill::from_key_value("tile"), BgFill::Tile); +} + +/// **复审 r1 P2-4**：解压炸弹的第二道闸——图头就超上限时要走 `TooLarge`，而且这条分支 +/// 以前**没有任何测试**（三态诊断里唯一没被钉住的一态）。 +/// +/// 抓得住：`header_size` 的尺寸判据（构造一张 9000×4 的真 PNG，只花 ~100 KB 就能造出来）。 +/// 抓不住：内存分配真的被 `image::Limits` 挡住（那要真喂一张巨图跑到 OOM，本机不做）。 +#[test] +fn an_over_sized_image_reports_too_large_instead_of_trying_to_decode() { + let path = temp_file("huge", "huge.png"); + let source = image::RgbImage::new(9_000, 4); + source.save(&path).expect("写大尺寸图"); + + let error = load(path.to_str().unwrap()).expect_err("超过 MAX_SOURCE_EDGE 必须报错"); + assert!( + matches!( + error, + LoadError::TooLarge { + width: 9_000, + height: 4 + } + ), + "实际 {error:?}" + ); + assert!( + error.describe().contains("too large"), + "提示要人话：{}", + error.describe() + ); + // 上限不许再放宽（r1 的 16384 等于允许 1 GB 的中间缓冲）：常量级约束放在测试里钉。 + const _: () = assert!(super::MAX_SOURCE_EDGE <= 8_192); + cleanup(&path); +} + +/// **复审 r1 P2-1 的诊断面**：小图平铺会被放大（图块步长放大，见 `tiles`），必须说出来。 +/// +/// 抓得住：短边 < `SMALL_TILE_EDGE` 的图在 tile 档下一定有提示；cover/contain 档不提示； +/// 大图不提示。 +/// 抓不住：提示文案在真实界面上的位置（由截图看）。 +#[test] +fn small_images_get_a_tile_diagnostic_instead_of_silently_degrading() { + let small = super::Image::from_rgba((32, 32), 4, 4, vec![0; 64]); + let note = small_tile_note(&small, BgFill::Tile).expect("小图 tile 必须有提示"); + assert!(note.contains("32×32"), "{note}"); + assert!(note.contains("scaled up"), "{note}"); + + // 非 tile 档不提示（cover/contain 会等比铺满，不存在「小图被放大铺」这件事）。 + assert!(small_tile_note(&small, BgFill::Cover).is_none()); + assert!(small_tile_note(&small, BgFill::Contain).is_none()); + + // 大图不提示。 + let big = super::Image::from_rgba((1200, 800), 4, 4, vec![0; 64]); + assert!(small_tile_note(&big, BgFill::Tile).is_none()); +} diff --git a/crates/app-iced/src/pages/appearance/mod.rs b/crates/app-iced/src/pages/appearance/mod.rs new file mode 100644 index 0000000..1cbda1c --- /dev/null +++ b/crates/app-iced/src/pages/appearance/mod.rs @@ -0,0 +1,219 @@ +//! # 外观接线（M93 / APPEARWIRE）：**键 → 像素** +//! +//! 本模块把 `appearance.*` 那批键接到真正的窗口与真正的像素上，并把「哪里是判据、哪里是观感」 +//! 分开写清楚。底座（M91）已经给了键、钳位判据与唯一的不安全落点；这里补的是**调用方**。 +//! +//! ## 两层透明度（D34 / D36） +//! +//! | 层 | 作用范围 | 实现 | CPU 档 | 下限 | +//! |---|---|---|---|---| +//! | 整窗 α | 整扇窗口（标题栏 + 导航轨 + 内容 + 卡片） | `SetLayeredWindowAttributes(LWA_ALPHA)`，DWM 常数乘法 | **允许** | 0.08（α=0 = 整窗穿透，拒绝） | +//! | 面板 α | 只有面板/卡片表面这一层（背景图能透出来） | 容器色的 alpha（[`section`] / `shell`） | **强制 1.0** | 0.4 | +//! +//! 真值表在 [`alpha`] 的模块文档里（三层 × 三个后端，含「钳位还是拒绝」）。 +//! +//! ## 模块分工 +//! +//! | 文件 | 是什么 | 有没有 IO | +//! |---|---|---| +//! | [`alpha`] | 两层 α 的钳位链、CPU 档降级、滑块映射、下发字节 | 无（纯函数） | +//! | [`background`] | 背景图解码（png/jpeg/bmp）、平铺网格、暗化系数、可读诊断 | 读盘一次（`load`） | +//! | `palette` | D38 三级优先序的调用侧 + 提示文案 | 无（像素由 `background` 给） | +//! | `state` | 运行期状态：把上面三件的输入输出连起来 | 只在 `refresh_background` | +//! | `section` | 设置页「外观」分组（真控件） | 无 | +//! | `picture` | 背景层 Element：真图直出（Cover/Contain/Tile）+ 暗化叠层 | 无 | +//! +//! ## 偏离登记（D30 要求逐条写清） +//! +//! | # | 偏离 | 为什么 | 什么时候收口 | +//! |---|---|---|---| +//! | 1 | ~~背景图按 36dp 马赛克画~~ → **r2 已销**：iced 的 `image-without-codecs` 打开，真图直出（`ContentFit` + 平铺网格） | r1 时 `Cargo.toml` 不在 scope；M93 r2 由 tower 扩 scope 解决 | ✅ | +//! | 2 | ~~面板 α 只覆盖外壳层~~ → **r2 已销**：α 收敛到 `Ui::layer`（唯一施加点），`frame::card` / 页头带 / 外壳 / 外观卡片自动同源 | M93 r2 扩了 `pages/frame.rs` + `theme.rs` 的 scope | ✅ | +//! | 3 | 桌面壁纸取色（第二级）永远 `Absent` | 壁纸探测（M73）还没落地；优先序本身仍按 design 的三级走，测试里用合成像素证明第二级会被用到 | M73 | +//! | 4 | 色卡档**不换** `Ui` 的 scheme | `resolve_source` 的色卡档返回 `DEFAULT_CARD`（天蓝卡）的方案，与令牌 baseline 逐色不同；应用它会把全部既有验收图的像素改掉。取色档（①②）才换 | 色卡选择 UI 落地时一并决议 | +//! | 5 | `Backend::Auto` 不触发 CPU 档降级 | 「强制 1.0」是 CPU 渲染档的规则，而 `Auto` 是「探测前的请求值」；探测结果没有回灌 `Backend` | 让 `probe` 把结果回灌 `Options::backend` | +//! | 6 | ~~背景图只支持 png~~ → **r2 已销**：`image` 补了 `jpeg`/`bmp`，单测与截图都用 `.jpg` 举证 | 同上 | ✅ | +//! | 7 | `bg_dim` 是「往**面板底色**退」，不是「叠黑」 | 浅色主题下叠黑会把亮图压成暗块，深色正文反而更读不清；向底色退在两种主题下都单调变好（见 [`background::dim_alpha`]） | 若将来为了「夜间压暗」需要真叠黑，加一档独立键（不要复用这个） | +//! | 8 | ~~页头文字压在画布上~~ → **r2 已销**：`frame::header_bar` 加了面板底色 | M93 r2 扩了 `pages/frame.rs` 的 scope | ✅ | +//! +//! ## 取证 +//! +//! 每一处改动都打一行 [`state::State::log_line`]：`[appearance] window_alpha=… panel_alpha=… +//! byte=… corner=…`；圆角另有一条独立管线，行形如 +//! `[corner] corner=policy=system source=dwm os=10.0.26100 excluded_reason=none +//! radius=system pref=2 readback=? read_hr=0x80070057 frame=overlapped layered=on +//! suppressed_by=window_alpha`（真进程实跑的两条见 `DevDocs/artifacts/m116/README.md`； +//! `frame=` 恒为 `overlapped`/`other`，**不会是 `popup`**） +//! （见 `app::update::appearance` 与 `platform::win32::corner::format_line`）。数值是**下发前**的 +//! 字节/属性值（不是观感），因为在 RDP + 虚拟显示适配器上「看上去多透明 / 圆不圆」不可信。 +//! 截图矩阵用 `ULL_APPEARANCE_*` 环境变量灌值（见 [`state`] 的常量）。 + +use iced::widget::container; +use iced::{Background, Border, Element, Length, Padding}; + +use unlucky_design::color::Role; +use unlucky_design::shape::ShapeScale; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; + +use crate::pages::frame; +use crate::pages::Message; +use crate::theme::Ui; + +pub mod alpha; +pub mod background; + +mod palette; +mod picture; +mod section; +mod state; + +/// 状态提示的 **tonal notice**（`section.rs` 的 400 行硬顶把它放在模块根）。 +/// +/// `SurfaceContainerHighest` 底 + `ShapeScale::Small` 圆角 + 两侧 `X2` 内边距，文字 `OnSurfaceVariant`。 +/// 用它而不是「换色的正文」：容器才是 M3 表达「当前状态」的形态，也和说明段在**形态**上分开 +/// （不靠色相、不新增令牌）。调用点见 [`section::section`] 的圆角一节。 +fn notice<'a>(ui: &'a Ui, text: &str) -> Element<'a, Message> { + let background = ui.color(Role::SurfaceContainerHighest); + let tone = ui.color(Role::OnSurfaceVariant); + let body = frame::text_role_owned(ui, TypeRole::BodySmall, true, text.to_owned(), tone); + let pad = ui.space(Space::X2); + let radius = ui.radius_dp(ShapeScale::Small); + container(body) + .width(Length::Fill) + .padding(Padding::from([ui.space(Space::X1), pad])) + .style(move |_theme| container::Style { + background: Some(Background::Color(background)), + border: Border { + radius, + ..Border::default() + }, + ..container::Style::default() + }) + .into() +} + +pub use picture::layer; +pub use section::section; +pub use state::State; + +/// 设置页「外观」分组在左列里的下标（0 = General，1 = Appearance …）。 +pub const APPEARANCE_GROUP: usize = 1; + +/// 设置页「外观」分组的显示名。 +pub const GROUP_LABEL: &str = "Appearance"; + +/// 一次外观改动（设置页 → `App`）。 +/// +/// 值都是**用户请求值**（未钳位）：钳位与降级只发生在 [`alpha`]，这样「用户设了 0.5、CPU 档实际 +/// 1.0」这种差别在状态里能看出来，日志也就不会把请求值写成生效值。 +#[derive(Debug, Clone, PartialEq)] +pub enum Change { + /// 整窗透明度（请求值，0.08~1.0）。 + WindowOpacity(f32), + /// 面板透明度（请求值，0.4~1.0）。 + PanelAlpha(f32), + /// 背景图开关。 + BgEnabled(bool), + /// 背景图路径（空串 = 清掉）。 + BgImage(String), + /// 填充档。 + BgFill(unlucky_presenter::prefs::BgFill), + /// 暗化强度（0~0.95）。 + BgDim(f32), + /// 配色来源档。 + PaletteSource(unlucky_presenter::prefs::PaletteSource), + /// 窗口圆角档位（M116：跟随系统 / 直角）。 + Corner(unlucky_presenter::prefs::WindowCorner), + /// 设置页切分组（左列点选）。 + SelectGroup(usize), +} + +impl Change { + /// 这条改动对应哪个 schema 键（写回配置用；`SelectGroup` 不落盘）。 + #[must_use] + pub fn key(&self) -> Option<&'static str> { + Some(match self { + Self::WindowOpacity(_) => unlucky_presenter::prefs::keys::WINDOW_OPACITY, + Self::PanelAlpha(_) => unlucky_presenter::prefs::keys::PANEL_ALPHA, + Self::BgEnabled(_) => unlucky_presenter::prefs::keys::BG_IMAGE_ENABLED, + Self::BgImage(_) => unlucky_presenter::prefs::keys::BG_IMAGE, + Self::BgFill(_) => unlucky_presenter::prefs::keys::BG_FILL, + Self::BgDim(_) => unlucky_presenter::prefs::keys::BG_DIM, + Self::PaletteSource(_) => unlucky_presenter::prefs::keys::PALETTE_SOURCE, + Self::Corner(_) => unlucky_presenter::prefs::keys::WINDOW_CORNER, + Self::SelectGroup(_) => return None, + }) + } + + /// 这条改动的落盘字符串形态（与 `schema` 的取值词表逐字一致）。 + /// + /// `None` = 不落盘（分组选择）。数字一律给 `f64` 的十进制字面量（`store.set` 按 schema 类型转）。 + #[must_use] + pub fn value(&self) -> Option { + Some(match self { + Self::WindowOpacity(alpha) => format!("{alpha}"), + Self::PanelAlpha(alpha) => format!("{alpha}"), + Self::BgEnabled(enabled) => enabled.to_string(), + Self::BgImage(path) => path.clone(), + Self::BgFill(fill) => fill.as_str().to_owned(), + Self::BgDim(dim) => format!("{dim}"), + Self::PaletteSource(source) => source.as_str().to_owned(), + Self::Corner(corner) => corner.as_str().to_owned(), + Self::SelectGroup(_) => return None, + }) + } +} + +#[cfg(test)] +mod tests { + use super::{Change, APPEARANCE_GROUP}; + use unlucky_presenter::prefs::{keys, BgFill, PaletteSource}; + + /// 抓得住：每条改动都点名到自己那个 schema 键（写错键 = 静默写到别的配置项上）。 + /// 抓不住：这些键是否真的在 core 的 schema 白名单里（那由 presenter/core 的测试守）。 + #[test] + fn every_change_names_its_own_schema_key() { + assert_eq!(APPEARANCE_GROUP, 1, "左列第 1 项是 Appearance"); + let cases = [ + (Change::WindowOpacity(0.8), keys::WINDOW_OPACITY), + (Change::PanelAlpha(0.6), keys::PANEL_ALPHA), + (Change::BgEnabled(true), keys::BG_IMAGE_ENABLED), + (Change::BgImage("D:/x.png".to_owned()), keys::BG_IMAGE), + (Change::BgFill(BgFill::Tile), keys::BG_FILL), + (Change::BgDim(0.5), keys::BG_DIM), + ( + Change::PaletteSource(PaletteSource::Wallpaper), + keys::PALETTE_SOURCE, + ), + ( + Change::Corner(unlucky_presenter::prefs::WindowCorner::Square), + keys::WINDOW_CORNER, + ), + ]; + for (change, key) in cases { + assert_eq!(change.key(), Some(key), "{change:?}"); + assert!(change.value().is_some()); + } + assert_eq!(Change::SelectGroup(2).key(), None, "切分组不落盘"); + assert_eq!(Change::SelectGroup(2).value(), None); + } + + /// 抓得住：落盘字符串必须是 schema 认识的词表（枚举档写错就整条配置读回默认值）。 + /// 抓不住：数值是否在范围内（钳位在 core 侧，越界写入会被 schema 拒绝）。 + #[test] + fn persisted_values_use_the_schema_vocabulary() { + assert_eq!( + Change::BgFill(BgFill::Contain).value().as_deref(), + Some("contain") + ); + assert_eq!( + Change::PaletteSource(PaletteSource::BackgroundImage) + .value() + .as_deref(), + Some("background-image") + ); + assert_eq!(Change::BgEnabled(false).value().as_deref(), Some("false")); + assert_eq!(Change::WindowOpacity(0.8).value().as_deref(), Some("0.8")); + } +} diff --git a/crates/app-iced/src/pages/appearance/palette.rs b/crates/app-iced/src/pages/appearance/palette.rs new file mode 100644 index 0000000..b611027 --- /dev/null +++ b/crates/app-iced/src/pages/appearance/palette.rs @@ -0,0 +1,279 @@ +//! D38 三级配色来源的**调用侧**：用户选的档 → `unlucky_design::palette::resolve_source`。 +//! +//! ## 档位与优先序 +//! +//! `appearance.palette_source` 的取值是「**从哪一级起**试」：① `background-image` ② `wallpaper` +//! ③ `preset`。起点的级别以下的级别**不参与**（在 `Provenance` 里记为 `Absent` = 用户没让它们 +//! 参与），起点以上的每一级只要「有输入但不合格」就自动往下一级落——回落链本身由 design 实现 +//! （`crates/design/src/palette/resolve/`），本文件只做两件事： +//! +//! 1. 把「没设」与「设了但坏了」**分开传**（[`Source::Absent`] vs [`Source::Undecodable`]）—— +//! 混成一个 `None` 会让设置页说错话（「没设背景图」 vs 「你那张图读不出来」）； +//! 2. 把 `Provenance::hint_key()` 翻成一句可读提示（键 → 文案是 UI 层的活，i18n 之后再统一）。 +//! +//! ## 为什么不在这里做对比度 +//! +//! WCAG 收敛在 `unlucky_design` 里（`converge` + `check`，任何来源的方案都跑同一套）。本文件 +//! 只负责「选哪一级」，越俎代庖会让两条路径各有一套门禁。测试里仍然断言「任何一级的结果都 +//! `is_clean()`」，那是**验收**，不是实现。 + +use unlucky_design::color::{Scheme, SchemeFlavor}; +use unlucky_design::palette::{resolve_source, ImageInput, Level, Provenance}; +use unlucky_presenter::prefs::PaletteSource; + +use super::background::Image; + +/// 某一级的输入（三态：没设 / 设了但坏了 / 解码好了）。 +#[derive(Debug, Clone, Copy)] +pub enum Source<'a> { + /// 用户没设这一级（没开关 / 路径空）。 + Absent, + /// 设了，但读盘或解码失败（原因在调用侧记着，这里只用来说「坏」）。 + Undecodable, + /// 解码好的像素。 + Pixels(&'a Image), +} + +impl<'a> Source<'a> { + /// 翻成 design 的输入形态。 + #[must_use] + pub fn input(self) -> Option> { + match self { + Self::Absent => None, + Self::Undecodable => Some(ImageInput::Undecodable), + Self::Pixels(image) => Some(ImageInput::pixels(&image.rgba, image.width, image.height)), + } + } +} + +/// 一次解析的结果。 +#[derive(Debug, Clone, PartialEq)] +pub struct Resolved { + /// 最终生效的方案（49 个角色）。 + pub scheme: Scheme, + /// 用哪一级、前几级为什么没用。 + pub provenance: Provenance, +} + +impl Resolved { + /// 生效的层级（日志与设置页展示用）。 + #[must_use] + pub fn level(&self) -> Level { + self.provenance.level + } + + /// 可读提示（`None` = 一级成功、没什么可解释的）。 + #[must_use] + pub fn note(&self) -> Option<&'static str> { + note(&self.provenance) + } +} + +/// 按档位解析一套方案。 +/// +/// `preset` 固定传 `None`：本仓库的「用户选中的色卡」还没有 UI（M91 只落了档位）， +/// 所以 design 用它自己的出厂卡（`DEFAULT_CARD` = 天蓝）。色卡选择接上后从 `state` 传进来即可。 +#[must_use] +pub fn resolve( + source: PaletteSource, + background: Source<'_>, + wallpaper: Source<'_>, + flavor: SchemeFlavor, +) -> Resolved { + // 档位 = 起点：起点以下的级别不参与（传 `Source::Absent`）。 + let background = if source == PaletteSource::BackgroundImage { + background + } else { + Source::Absent + }; + let wallpaper = + if source == PaletteSource::BackgroundImage || source == PaletteSource::Wallpaper { + wallpaper + } else { + Source::Absent + }; + + let (scheme, provenance) = resolve_source(background.input(), wallpaper.input(), None, flavor); + Resolved { scheme, provenance } +} + +/// `Provenance::hint_key()` → 一句可读提示（英文基线；i18n mission 之后走词表）。 +/// +/// 键的完整表在 `unlucky_design::palette::resolve::Provenance::hint_key` 的文档里； +/// 这里只翻「本 mission 真会产生的那几个」，未识别键返回 `None` 而不是编一句话。 +#[must_use] +pub fn note(provenance: &Provenance) -> Option<&'static str> { + Some(match provenance.hint_key()? { + "palette.hint.background.undecodable" => { + "Background image could not be read; colours fall back." + } + "palette.hint.background.too-small" => { + "Background image is too small to sample; colours fall back." + } + "palette.hint.background.bad-dimensions" => { + "Background image data looks inconsistent; colours fall back." + } + "palette.hint.background.no-opaque-pixels" => { + "Background image is almost fully transparent; colours fall back." + } + "palette.hint.background.low-chroma" => { + "Background image is too monochrome to tint from; colours fall back." + } + "palette.hint.background.contrast" => { + "Background image colours would be unreadable; colours fall back." + } + "palette.hint.wallpaper.undecodable" => "Desktop wallpaper could not be read.", + "palette.hint.wallpaper.low-chroma" => "Desktop wallpaper is too monochrome to tint from.", + "palette.hint.wallpaper.too-small" => "Desktop wallpaper is too small to sample.", + "palette.hint.wallpaper.bad-dimensions" => "Desktop wallpaper data looks inconsistent.", + "palette.hint.wallpaper.no-opaque-pixels" => { + "Desktop wallpaper is almost fully transparent." + } + "palette.hint.wallpaper.contrast" => { + "Desktop wallpaper colours would be unreadable; colours fall back." + } + "palette.hint.preset.contrast" => "The built-in card needed a small contrast correction.", + "palette.hint.adjusted" => "A few colours were nudged for readability.", + _ => return None, + }) +} + +#[cfg(test)] +mod tests { + use super::{note, resolve, Source}; + use crate::pages::appearance::background::Image; + use unlucky_design::color::SchemeFlavor; + use unlucky_design::palette::wcag::check; + use unlucky_design::palette::{Level, Outcome, Skip}; + use unlucky_presenter::prefs::PaletteSource; + + /// 高彩度的图（纯红）：取色一定成功。 + fn vivid() -> Image { + let rgba = [0xC0, 0x20, 0x20, 0xFF].repeat(64); + Image::from_rgba((8, 8), 8, 8, rgba) + } + + /// 极低彩度的图（近灰）：D40 的彩度门槛会拒绝它（`< 8`）。 + fn grey() -> Image { + let rgba = [0x80, 0x80, 0x82, 0xFF].repeat(64); + Image::from_rgba((8, 8), 8, 8, rgba) + } + + #[test] + fn background_tier_wins_when_the_image_is_usable() { + // 抓得住：档位 ① 有合格输入时就用它，且不回落、没有提示。 + let image = vivid(); + let resolved = resolve( + PaletteSource::BackgroundImage, + Source::Pixels(&image), + Source::Absent, + SchemeFlavor::Light, + ); + assert_eq!(resolved.level(), Level::BackgroundImage); + assert!(!resolved.provenance.did_fall_back()); + assert_eq!(resolved.note(), None, "一级成功时不该有提示"); + assert!(check(&resolved.scheme).is_clean(), "取色结果也必须过 WCAG"); + } + + #[test] + fn a_broken_background_falls_back_and_says_why() { + // 抓得住：「设了但坏了」（Undecodable）与「没设」（Absent）在 Provenance 里分得开， + // 且提示文案对应的是前者；结果仍然过 WCAG（回落不静默变黑白）。 + let resolved = resolve( + PaletteSource::BackgroundImage, + Source::Undecodable, + Source::Absent, + SchemeFlavor::Dark, + ); + assert_eq!(resolved.level(), Level::Preset, "解码失败 → 落到色卡"); + assert_eq!( + resolved.provenance.background(), + Outcome::Failed(Skip::Undecodable) + ); + assert!(resolved.provenance.did_fall_back()); + assert_eq!( + resolved.note(), + Some("Background image could not be read; colours fall back.") + ); + assert!(check(&resolved.scheme).is_clean()); + } + + #[test] + fn a_monochrome_background_falls_back_instead_of_turning_grey() { + // 抓得住：彩度不足**不是**「压成灰方案」，而是回落到色卡（D40 的纪律），并留下 low-chroma。 + let image = grey(); + let resolved = resolve( + PaletteSource::BackgroundImage, + Source::Pixels(&image), + Source::Absent, + SchemeFlavor::Light, + ); + assert_eq!(resolved.level(), Level::Preset); + match resolved.provenance.background() { + Outcome::Failed(skip) => { + assert!(matches!(skip, Skip::LowChroma { .. }), "实际 {skip:?}") + } + other => panic!("灰图必须被判不合格，实际 {other:?}"), + } + assert!(resolved.note().unwrap().contains("monochrome")); + } + + #[test] + fn the_three_tiers_are_tried_in_order_and_never_out_of_order() { + // 抓得住：① 档位=wallpaper 时背景图**不参与**（即使手里有像素）；② 档位=preset 时前两级 + // 都不参与。这两条是「优先序」的唯一可断言形态（顺序本身在 design 里）。 + let background = vivid(); + let wallpaper = vivid(); + + let wallpaper_tier = resolve( + PaletteSource::Wallpaper, + Source::Pixels(&background), + Source::Pixels(&wallpaper), + SchemeFlavor::Light, + ); + assert_eq!(wallpaper_tier.level(), Level::Wallpaper); + assert_eq!( + wallpaper_tier.provenance.background(), + Outcome::Absent, + "档位是壁纸 → 背景图那一级没参与" + ); + + let preset_tier = resolve( + PaletteSource::Preset, + Source::Pixels(&background), + Source::Pixels(&wallpaper), + SchemeFlavor::Light, + ); + assert_eq!(preset_tier.level(), Level::Preset); + assert_eq!(preset_tier.provenance.background(), Outcome::Absent); + assert_eq!(preset_tier.provenance.wallpaper(), Outcome::Absent); + assert!(check(&preset_tier.scheme).is_clean()); + + // 而档位=background-image 且壁纸也在时：一级成功 ⇒ 壁纸是 NotReached（不是 Absent）。 + let background_tier = resolve( + PaletteSource::BackgroundImage, + Source::Pixels(&background), + Source::Pixels(&wallpaper), + SchemeFlavor::Light, + ); + assert_eq!(background_tier.level(), Level::BackgroundImage); + assert_eq!(background_tier.provenance.wallpaper(), Outcome::NotReached); + } + + #[test] + fn hints_are_only_produced_for_keys_we_ship_a_sentence_for() { + // 抓得住：note() 不会为未知键编文案（返回 None 而不是 Some("")）。 + assert_eq!( + note( + &resolve( + PaletteSource::Preset, + Source::Absent, + Source::Absent, + SchemeFlavor::Light, + ) + .provenance + ), + None + ); + } +} diff --git a/crates/app-iced/src/pages/appearance/picture.rs b/crates/app-iced/src/pages/appearance/picture.rs new file mode 100644 index 0000000..f4280fa --- /dev/null +++ b/crates/app-iced/src/pages/appearance/picture.rs @@ -0,0 +1,113 @@ +//! 背景层的**像素**：真图直出（`Cover` / `Contain` / `Tile`）+ 暗化叠层。 +//! +//! 与 [`super::section`] 拆开只为单文件 ≤400 行的纪律；对外入口仍是 +//! `pages::appearance::layer`（本文件 [`layer`] 的再导出）。 +//! +//! ## 三种填充 +//! +//! `Cover`/`Contain` 交给渲染器的 `ContentFit`（等比缩放 + 裁切/留白由它做）；`Tile` 用 +//! [`background::tiles`] 算行列后铺 N 个图块（单块尺寸 = 原尺寸 × `tiles.scale`）。 +//! +//! 暗化不是逐像素改色，而是**盖一层「版面底色 @ α=dim」**：图不透明时它与「向底色插值」 +//! 数学等价（[`background::dim_alpha`] 有推导），而普通 alpha 混合 CPU/GPU 两档都支持。 + +use iced::widget::image; +use iced::widget::{column, container, image as image_widget, space}; +use iced::{ContentFit, Element, Length}; + +use unlucky_design::color::Role; +use unlucky_presenter::prefs::BgFill; + +use crate::pages::{frame, Message}; +use crate::theme::Ui; + +use super::background; +use super::state::State; + +/// 背景层（铺满整窗、垫在最下层）。`None` = 没有可用的背景图（调用方就不叠这一层）。 +/// +/// 真图直出（M93 r2）：`Cover` / `Contain` 交给 iced 的 `ContentFit`，`Tile` 用 +/// [`background::tiles`] 算网格铺 N 个图块。暗化 = 一层「版面底色 @ α=dim」盖在图上 +/// （见 [`background::dim_alpha`] 的等价性说明）。 +#[must_use] +pub fn layer(ui: &Ui, state: &State, viewport: (f32, f32)) -> Option> { + 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/section.rs b/crates/app-iced/src/pages/appearance/section.rs new file mode 100644 index 0000000..04e3ada --- /dev/null +++ b/crates/app-iced/src/pages/appearance/section.rs @@ -0,0 +1,395 @@ +//! 设置页「外观」分组（**真控件**）+ 背景层 Element + 面板层配色。 +//! +//! ## 控件与键的对应 +//! +//! | 控件 | 键 | 改动消息 | +//! |---|---|---| +//! | 整窗透明度滑块（下限 0.08） | `appearance.window_opacity` | [`Change::WindowOpacity`] | +//! | 窗口圆角（跟随系统 / 直角，M116） | `appearance.window_corner` | [`Change::Corner`] | +//! | 面板透明度滑块（下限 0.4，CPU 档禁用） | `appearance.panel_alpha` | [`Change::PanelAlpha`] | +//! | 背景图开关 | `appearance.bg_image_enabled` | [`Change::BgEnabled`] | +//! | 背景图路径（文本框） | `appearance.bg_image` | [`Change::BgImage`] | +//! | 填充（封面 / 拉伸 / 平铺） | `appearance.bg_fill` | [`Change::BgFill`] | +//! | 暗化强度（0~0.95） | `appearance.bg_dim` | [`Change::BgDim`] | +//! | 配色来源（三档） | `appearance.palette_source` | [`Change::PaletteSource`] | +//! +//! 文案一律英文基线（i18n 是别的 mission；本文件不拼中文、不 import 尚不存在的 crate）。 +//! +//! ## 为什么「值」与「生效值」分开显示 +//! +//! CPU 档下面板 α 被强制 1.0（D36），而用户请求值可能是 0.5。滑块位置按**生效值**画、旁边写 +//! 「requested 0.50 → forced 1.00」，这样「为什么拖了没反应」在界面上就有答案，而不是只躺在日志里。 + +use iced::widget::{button, column, container, row, space}; +use iced::{ + Alignment, Background, Border, Color, Element, Length, Padding, Shadow, Theme as IcedTheme, +}; + +use unlucky_design::color::Role; +use unlucky_design::component_map::Component; +use unlucky_design::elevation::MaterialLayer; +use unlucky_design::shape::ShapeScale; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; +use unlucky_i18n::catalog::Key; +use unlucky_presenter::prefs::{BgFill, PaletteSource, WindowCorner}; + +use crate::app::components::inputs::{slider, text_field, Field, Slider}; +use crate::pages::{frame, Message}; +use crate::theme::Ui; + +use super::alpha::{ + panel_alpha_from_fraction, panel_fraction, window_alpha_from_fraction, window_fraction, + WINDOW_ALPHA_FLOOR, +}; +use super::background::{self, BG_DIM_MAX}; +use super::state::State; +use super::Change; + +/// 「外观」分组整块（一张卡）。 +pub fn section<'a>(ui: &'a Ui, state: &'a State) -> Element<'a, Message> { + let mut rows = column![].spacing(ui.space(Space::X1)).width(Length::Fill); + + // ① 整窗透明度 + let window_percent = format!("{:.0}%", state.window_opacity * 100.0); + rows = rows.push(slider_row( + ui, + "Window transparency", + window_percent, + format!( + "Applies to the whole window. Floor {:.2}; 1.00 = fully opaque.", + WINDOW_ALPHA_FLOOR + ), + state.window_opacity < 1.0, + slider( + Slider::new(ui, window_fraction(state.window_opacity)).on_change(|fraction| { + Message::Appearance(Change::WindowOpacity(window_alpha_from_fraction(fraction))) + }), + ), + )); + + // ② 窗口圆角（M116）：只有两档 + 一句按平台说明；不做 8/12/16 档（系统不暴露半径）。 + let corner = state.window_corner(); + rows = rows.push(choice_row( + ui, + t(Key::SettingsAppearanceCorner), + vec![ + choice( + ui, + t(Key::SettingsAppearanceCornerSystem), + corner == WindowCorner::System, + Change::Corner(WindowCorner::System), + ), + choice( + ui, + t(Key::SettingsAppearanceCornerSquare), + corner == WindowCorner::Square, + Change::Corner(WindowCorner::Square), + ), + ], + )); + // **tonal notice**（r5 视觉终稿）：M3 里表达「当前状态」的惯用形态是**容器**，不是改字色。 + // 只在「跟随系统 + α<1」出现；与下面的说明段之间再留 `Space::X1`（列间距 X1 + 这里 X1 = X2）。 + if corner == WindowCorner::System && state.window_opacity < 1.0 { + rows = rows.push(super::notice(ui, t(Key::SettingsAppearanceCornerSuspended))); + let gap: Element<'a, Message> = space::vertical().height(ui.space(Space::X1)).into(); + rows = rows.push(gap); + } + let tone = ui.color(Role::OnSurfaceVariant); + rows = rows.push(note_line(ui, t(Key::SettingsAppearanceCornerHint), tone)); + + // ③ 面板透明度（CPU 档强制 1.0） + let forced = state.panel_is_forced(); + let panel_percent = if forced { + format!("100% (forced from {:.2})", state.panel_alpha) + } else { + format!("{:.0}%", state.effective_panel_alpha() * 100.0) + }; + let panel_hint = if forced { + "Software renderer: panels stay fully opaque (window transparency still works)." + } else { + "Only the panel/card layer. Floor 0.40; independent of window transparency." + }; + let panel_control = if forced { + slider(Slider::new(ui, panel_fraction(1.0))) + } else { + slider( + Slider::new(ui, panel_fraction(state.panel_alpha)).on_change(|fraction| { + Message::Appearance(Change::PanelAlpha(panel_alpha_from_fraction(fraction))) + }), + ) + }; + rows = rows.push(slider_row( + ui, + "Panel transparency", + panel_percent, + panel_hint.to_owned(), + !forced, + panel_control, + )); + + // ④ 背景图开关 + rows = rows.push(choice_row( + ui, + "Background image", + vec![ + choice(ui, "Off", !state.bg_enabled, Change::BgEnabled(false)), + choice(ui, "On", state.bg_enabled, Change::BgEnabled(true)), + ], + )); + + // ⑤ 路径（文本框：受控，输入即生效） + let path_field: Element<'a, Message> = text_field( + ui, + Field::new(&state.bg_path) + .label("Image path") + .placeholder("D:/Pictures/background.png"), + |value| Message::Appearance(Change::BgImage(value)), + ); + rows = rows.push( + column![label(ui, "Image path"), path_field] + .spacing(ui.space(Space::X1)) + .width(Length::Fill), + ); + + // ⑥ 诊断（读盘失败 / CPU 降级 / 配色回落）——**不许静默**，且必须在**首屏可见处** + // （复审 r1 P2-3：文案落在折叠线以下等于没提示）。位置就在背景图那两行的紧下方。 + for note in state.diagnostics() { + rows = rows.push(note_line(ui, note, ui.color(Role::Error))); + } + if let Some(note) = state.backend_note() { + rows = rows.push(note_line(ui, note, ui.color(Role::OnSurfaceVariant))); + } + if let Some(note) = state + .image() + .and_then(|image| background::small_tile_note(image, state.bg_fill)) + { + rows = rows.push(note_line(ui, ¬e, ui.color(Role::OnSurfaceVariant))); + } + if let Some(note) = state.palette_note() { + rows = rows.push(note_line(ui, note, ui.color(Role::OnSurfaceVariant))); + } + let resolved = format!("Colours: {}", state.palette_level()); + rows = rows.push(note_line(ui, &resolved, ui.color(Role::OnSurfaceVariant))); + + // ⑦ 填充 + rows = rows.push(choice_row( + ui, + "Fill", + vec![ + choice( + ui, + "Cover", + state.bg_fill == BgFill::Cover, + Change::BgFill(BgFill::Cover), + ), + choice( + ui, + "Contain", + state.bg_fill == BgFill::Contain, + Change::BgFill(BgFill::Contain), + ), + choice( + ui, + "Tile", + state.bg_fill == BgFill::Tile, + Change::BgFill(BgFill::Tile), + ), + ], + )); + + // ⑧ 暗化 + rows = rows.push(slider_row( + ui, + "Dim", + format!("{:.0}%", state.bg_dim * 100.0), + format!( + "Blends the image toward the panel colour so text stays readable. Max {BG_DIM_MAX:.2}." + ), + state.bg_dim > 0.0, + slider( + Slider::new(ui, state.bg_dim / BG_DIM_MAX) + .on_change(|fraction| Message::Appearance(Change::BgDim(fraction * BG_DIM_MAX))), + ), + )); + + // ⑨ 配色来源 + rows = rows.push(choice_row( + ui, + "Colour source", + vec![ + choice( + ui, + "Background", + state.palette_source == PaletteSource::BackgroundImage, + Change::PaletteSource(PaletteSource::BackgroundImage), + ), + choice( + ui, + "Wallpaper", + state.palette_source == PaletteSource::Wallpaper, + Change::PaletteSource(PaletteSource::Wallpaper), + ), + choice( + ui, + "Preset", + state.palette_source == PaletteSource::Preset, + Change::PaletteSource(PaletteSource::Preset), + ), + ], + )); + + card(ui, rows) +} + +/// 外观卡片：底色走 `ui.layer`（面板 α 的唯一来源），与其它页的卡片同源。 +fn card<'a>(ui: &'a Ui, content: impl Into>) -> Element<'a, Message> { + let spec = Component::OutlinedCard.spec(); + let background = ui.layer(MaterialLayer::Card); + + container(content) + .width(Length::Fill) + .padding(ui.metrics().card_padding) + .style(move |_theme| container::Style { + background: Some(Background::Color(background)), + border: ui.outlined(spec.shape), + ..container::Style::default() + }) + .into() +} + +// --------------------------------------------------------------- 行与控件 + +fn label<'a>(ui: &'a Ui, content: &'a str) -> Element<'a, Message> { + frame::text_role( + ui, + TypeRole::BodyMedium, + false, + content, + ui.color(Role::OnSurface), + ) +} + +/// 设置页文案的 i18n 取词口（M116 起新条目一律走词表，不再写字面量）。 +/// +/// 为什么是 [`Lang::En`]：本文件的既有文案是英文基线（i18n 接线是另一条 mission， +/// 见本文件头部「文案一律英文基线」）。走词表的意义是**新增条目已经有中英两套**， +/// 接线时只换这一行，不用回来重写控件。 +fn t(key: Key) -> &'static str { + unlucky_i18n::Lang::En.catalog().text(key) +} + +fn note_line<'a>(ui: &'a Ui, content: &str, color: Color) -> Element<'a, Message> { + // 诊断文案是**运行时拼出来的**（路径、错误原因），只能走 owned 版本。 + frame::text_role_owned(ui, TypeRole::BodySmall, false, content.to_owned(), color) +} + +/// 一行「标签 + 值 + 滑块 + 说明」。 +fn slider_row<'a>( + ui: &'a Ui, + title: &'a str, + value: String, + hint: String, + enabled: bool, + control: Element<'a, Message>, +) -> Element<'a, Message> { + let value_color = if enabled { + ui.color(Role::OnSurface) + } else { + ui.color(Role::OnSurfaceVariant) + }; + + let head = row![ + container(label(ui, title)) + .width(Length::Fill) + .align_y(Alignment::Center), + frame::text_role_owned(ui, TypeRole::LabelLarge, true, value, value_color), + ] + .width(Length::Fill) + .align_y(Alignment::Center); + + column![ + head, + control, + frame::text_role_owned( + ui, + TypeRole::BodySmall, + false, + hint, + ui.color(Role::OnSurfaceVariant), + ), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill) + .padding(Padding::from([ui.space(Space::X2), 0.0])) + .into() +} + +/// 一行「标签 + 一排互斥按钮」。 +fn choice_row<'a>( + ui: &'a Ui, + title: &'a str, + choices: Vec>, +) -> Element<'a, Message> { + row![ + container(label(ui, title)) + .width(Length::Fill) + .align_y(Alignment::Center), + row(choices) + .spacing(ui.space(Space::X1)) + .align_y(Alignment::Center), + ] + .width(Length::Fill) + .align_y(Alignment::Center) + .padding(Padding::from([ui.space(Space::X2), 0.0])) + .into() +} + +/// 一个互斥按钮（选中态用 `SecondaryContainer`，未选中用透明 + `OnSurfaceVariant`）。 +fn choice<'a>(ui: &'a Ui, text: &'a str, selected: bool, change: Change) -> Element<'a, Message> { + let height = ui.metrics().control_height; + let content_color = if selected { + ui.color(Role::OnSecondaryContainer) + } else { + ui.color(Role::OnSurfaceVariant) + }; + + button( + container(frame::text_role( + ui, + TypeRole::LabelLarge, + selected, + text, + content_color, + )) + .align_y(Alignment::Center), + ) + .height(height) + .padding(Padding::from([0.0, ui.space(Space::X3)])) + .style(move |_theme: &IcedTheme, status| { + let background = if selected { + Some(Background::Color(ui.color(Role::SecondaryContainer))) + } else if matches!(status, button::Status::Hovered | button::Status::Pressed) { + Some(Background::Color(ui.state_over( + unlucky_design::color::StateLayer::Hover, + Role::OnSurface, + Role::Surface, + ))) + } else { + None + }; + + button::Style { + background, + text_color: content_color, + border: Border { + radius: ui.radius(ShapeScale::Full, height), + ..Border::default() + }, + shadow: Shadow::default(), + snap: true, + } + }) + .on_press(Message::Appearance(change)) + .into() +} diff --git a/crates/app-iced/src/pages/appearance/state.rs b/crates/app-iced/src/pages/appearance/state.rs new file mode 100644 index 0000000..e1868bf --- /dev/null +++ b/crates/app-iced/src/pages/appearance/state.rs @@ -0,0 +1,390 @@ +//! 外观的**运行期状态**：配置值 → 生效值（钳位 / CPU 档降级）→ 要下发的字节与要画的格子。 +//! +//! 这一层是「键 → 像素」的中间站，App 持有一份（`crate::app::state::App::appearance`）： +//! +//! ```text +//! launcher.json ──SettingsBridge::load/load_base──┐ +//! ▼ +//! State（本文件） +//! ┌────────────┴────────────┐ +//! 整窗 α → 字节 │ │ 面板 α / 背景图 → Element +//! ▼ ▼ +//! app::window_alpha（FFI） shell / 设置页（像素） +//! ``` +//! +//! **纯的与不纯的**分界刻意写在这里：钳位链（[`super::alpha`]）、几何（[`super::background`]）、 +//! 优先序（[`super::palette`]）都是纯函数；本文件只把它们的输入输出连起来，并把「读盘失败」 +//! 变成一条**可读诊断**而不是一个 `unwrap`。 + +use unlucky_design::color::{Scheme, SchemeFlavor}; +use unlucky_presenter::prefs::{ + AppearanceBase, AppearancePrefs, BgFill, PaletteSource, WindowCorner, +}; + +use crate::Backend; + +use super::alpha::{self, effective_glass, effective_panel_alpha, panel_is_forced_opaque}; +use super::background::{self, Image}; +use super::palette::{self, Resolved, Source}; + +/// 取证开关的环境变量名（截图矩阵与真机日志用；生产默认全部不设）。 +pub const ENV_WINDOW_ALPHA: &str = "ULL_APPEARANCE_WINDOW_ALPHA"; +/// 面板 α。 +pub const ENV_PANEL_ALPHA: &str = "ULL_APPEARANCE_PANEL_ALPHA"; +/// 背景图路径。 +pub const ENV_BG_IMAGE: &str = "ULL_APPEARANCE_BG_IMAGE"; +/// 填充档（`cover` / `contain` / `tile`）。 +pub const ENV_BG_FILL: &str = "ULL_APPEARANCE_BG_FILL"; +/// 暗化强度。 +pub const ENV_BG_DIM: &str = "ULL_APPEARANCE_BG_DIM"; +/// 配色来源档（`background-image` / `wallpaper` / `preset`）。 +pub const ENV_PALETTE: &str = "ULL_APPEARANCE_PALETTE"; + +/// 外观的运行期状态。 +#[derive(Debug, Clone, PartialEq)] +pub struct State { + /// 用户请求的整窗 α（未钳位原值；下发前过 [`super::alpha`]）。 + pub window_opacity: f32, + /// 用户请求的面板 α（CPU 档会被强制成 1.0，见 [`State::effective_panel_alpha`]）。 + pub panel_alpha: f32, + /// 背景图总开关。 + pub bg_enabled: bool, + /// 背景图路径（空 = 未设置）。 + pub bg_path: String, + /// 填充档。 + pub bg_fill: BgFill, + /// 暗化强度。 + pub bg_dim: f32, + /// 配色来源档。 + pub palette_source: PaletteSource, + /// 玻璃拟态开关（CPU 档强制关）。 + pub glass: bool, + /// 窗口圆角策略（M116：`system` / `square`；真能不能圆由平台判，见 `platform::plan_corner`）。 + pub window_corner: WindowCorner, + /// 渲染后端（决定 CPU 档的两条降级）。 + pub backend: Backend, + /// 设置页当前分组（0 = General … 1 = Appearance；见 [`super::APPEARANCE_GROUP`]）。 + pub selected_group: usize, + /// 已解码的背景图（`None` = 没设 / 读失败）。 + image: Option, + /// 读盘/解码失败的**可读诊断**（按发生顺序追加）。 + 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, + backend, + selected_group: super::APPEARANCE_GROUP, + image: None, + diagnostics: Vec::new(), + resolved: None, + flavor, + }; + state.refresh_background(); + state.refresh_palette(); + state + } + + /// 截图/真机取证用：把 `ULL_APPEARANCE_*` 灌进来（不设 = 不动）。 + /// + /// 为什么用环境变量而不是 CLI 参数：`crates/app-iced/src/cli.rs` 不在本 mission 的 scope。 + /// 语义与既有取证开关（`ULL_TICK_TRACE`）一致：**只影响这次进程**，不落盘。 + pub fn apply_env(&mut self) { + if let Some(value) = env_f32(ENV_WINDOW_ALPHA) { + self.window_opacity = value; + } + if let Some(value) = env_f32(ENV_PANEL_ALPHA) { + self.panel_alpha = value; + } + if let Some(value) = std::env::var_os(ENV_BG_IMAGE) { + let path = value.to_string_lossy().to_string(); + self.bg_enabled = !path.trim().is_empty(); + self.bg_path = path; + } + if let Some(value) = std::env::var_os(ENV_BG_FILL) { + self.bg_fill = BgFill::from_key_value(&value.to_string_lossy()); + } + if let Some(value) = env_f32(ENV_BG_DIM) { + self.bg_dim = value; + } + if let Some(value) = std::env::var_os(ENV_PALETTE) { + self.palette_source = PaletteSource::from_key_value(&value.to_string_lossy()); + } + self.refresh_background(); + self.refresh_palette(); + } + + /// 面板 α 的**生效值**（CPU 档恒 1.0）。 + #[must_use] + pub fn effective_panel_alpha(&self) -> f32 { + effective_panel_alpha(self.backend, self.panel_alpha) + } + + /// 面板 α 是否被后端强制（设置页据此禁用滑块并给说明）。 + #[must_use] + pub fn panel_is_forced(&self) -> bool { + panel_is_forced_opaque(self.backend) + } + + /// 当前圆角策略（设置页显示选中项、日志与下发都用它）。 + #[must_use] + pub fn window_corner(&self) -> WindowCorner { + self.window_corner + } + + /// 改圆角策略（消息落点见 `app::update::appearance`；这里只管状态，不碰窗口）。 + pub fn set_window_corner(&mut self, policy: WindowCorner) { + self.window_corner = policy; + } + + /// 玻璃是否生效（CPU 档恒关）。 + #[must_use] + pub fn effective_glass(&self) -> bool { + effective_glass(self.backend, self.glass) + } + + /// 整窗 α 要下发的字节（`None` = 不调 FFI）。 + #[must_use] + pub fn window_alpha_byte(&self) -> Option { + alpha::window_alpha_byte(self.backend, self.window_opacity) + } + + /// 背景图是否真的会画（开关开 + 路径非空 + 解码成功）。 + #[must_use] + pub fn background_active(&self) -> bool { + self.bg_enabled && self.image.is_some() + } + + /// 已解码的背景图。 + #[must_use] + pub fn image(&self) -> Option<&Image> { + self.image.as_ref() + } + + /// 取色得到的方案（`None` = 色卡档，继续用令牌 baseline）。 + /// + /// 为什么色卡档不换 scheme：`resolve_source` 的色卡档走的是 `DEFAULT_CARD`（天蓝卡）， + /// 与令牌 baseline 逐色不同；直接应用会把**全部既有验收图的像素**改掉。色卡档的视觉基线 + /// 归令牌层（`Scheme::baseline`），这里只接管「取色真的成功」的那两档。 + #[must_use] + pub fn derived_scheme(&self) -> Option<&Scheme> { + let resolved = self.resolved.as_ref()?; + if resolved.level() == unlucky_design::palette::Level::Preset { + return None; + } + Some(&resolved.scheme) + } + + /// 读盘/解码失败的诊断（设置页逐条显示）。 + #[must_use] + pub fn diagnostics(&self) -> &[String] { + &self.diagnostics + } + + /// CPU 档降级的说明（`None` = 没有降级）。 + #[must_use] + pub fn backend_note(&self) -> Option<&'static str> { + self.panel_is_forced().then_some( + "Software renderer: panel transparency and glass stay fully opaque (window \ + transparency still works).", + ) + } + + /// 配色来源的提示（`None` = 一级成功）。 + #[must_use] + pub fn palette_note(&self) -> Option<&'static str> { + self.resolved.as_ref()?.note() + } + + /// 生效的配色层级码（日志用）。 + #[must_use] + pub fn palette_level(&self) -> &'static str { + match &self.resolved { + Some(resolved) => resolved.level().code(), + None => self.palette_source.as_str(), + } + } + + /// 深浅切换后重算配色（`Ui` 换主题时调）。 + pub fn set_flavor(&mut self, flavor: SchemeFlavor) { + if self.flavor == flavor { + return; + } + self.flavor = flavor; + self.refresh_palette(); + } + + /// 当前深浅。 + #[must_use] + pub fn flavor(&self) -> SchemeFlavor { + self.flavor + } + + /// 应用一条改动（设置页 → 状态）。返回**是否需要立刻下发整窗 α**。 + pub fn apply(&mut self, change: super::Change) -> bool { + use super::Change; + match change { + Change::WindowOpacity(alpha) => { + self.window_opacity = alpha; + true + } + Change::PanelAlpha(alpha) => { + self.panel_alpha = alpha; + false + } + Change::BgEnabled(enabled) => { + self.bg_enabled = enabled; + self.refresh_background(); + self.refresh_palette(); + false + } + Change::BgImage(path) => { + self.bg_path = path; + self.bg_enabled = !self.bg_path.trim().is_empty(); + self.refresh_background(); + self.refresh_palette(); + false + } + Change::BgFill(fill) => { + self.bg_fill = fill; + false + } + Change::BgDim(dim) => { + self.bg_dim = dim; + false + } + Change::PaletteSource(source) => { + self.palette_source = source; + self.refresh_palette(); + false + } + Change::Corner(policy) => { + self.window_corner = policy; + false + } + Change::SelectGroup(index) => { + self.selected_group = index; + false + } + } + } + + /// 写回配置用的快照（`SettingsBridge::persist` 覆盖的那 8 个字段）。 + /// + /// 注意：**强调色 / 玻璃不在本 mission 的管辖内**，调用方（`app::appearance`）会拿配置里 + /// 已有的快照做基底、只覆盖本 mission 真改了的字段，所以这里不产出完整快照。 + /// 这个函数只给「当前值是什么」一个只读视图（日志与测试用）。 + #[must_use] + pub fn current_values(&self) -> AppearancePrefs { + AppearancePrefs { + bg_image_enabled: self.bg_enabled, + bg_image: self.bg_path.clone(), + bg_fill: self.bg_fill, + bg_dim: self.bg_dim, + panel_alpha: self.panel_alpha, + glass: self.glass, + accent_color: String::new(), + } + } + + /// 取证日志（**一行**，数值而不是观感）：`[appearance] window_alpha=… panel_alpha=… byte=…`。 + #[must_use] + pub fn log_line(&self, context: &str) -> String { + let byte = self + .window_alpha_byte() + .map_or_else(|| "none".to_owned(), |byte| byte.to_string()); + format!( + "[appearance] {context} window_alpha={:.3} panel_alpha={:.3} (requested {:.3}) \ + byte={byte} corner={} backend={} bg={} fill={} dim={:.2} palette={} group={}", + self.window_opacity, + self.effective_panel_alpha(), + self.panel_alpha, + self.window_corner.as_str(), + self.backend.name(), + if self.background_active() { + self.bg_path.as_str() + } else { + "none" + }, + self.bg_fill.as_str(), + self.bg_dim, + self.palette_level(), + self.selected_group + ) + } + + /// 重读配置后同步（热切）。 + pub fn reload(&mut self, prefs: &AppearancePrefs, base: &AppearanceBase) { + self.window_opacity = base.window_opacity; + self.palette_source = base.palette_source; + self.window_corner = base.window_corner; + self.panel_alpha = prefs.panel_alpha; + self.bg_enabled = prefs.bg_image_enabled; + self.bg_fill = prefs.bg_fill; + self.bg_dim = prefs.bg_dim; + self.glass = prefs.glass; + if self.bg_path != prefs.bg_image { + self.bg_path = prefs.bg_image.clone(); + } + self.refresh_background(); + self.refresh_palette(); + } + + // ------------------------------------------------------------ 内部 + + fn refresh_background(&mut self) { + self.image = None; + self.diagnostics.clear(); + let trimmed = self.bg_path.trim(); + if !self.bg_enabled || trimmed.is_empty() { + return; + } + match background::load(trimmed) { + Ok(image) => self.image = Some(image), + Err(error) => self.diagnostics.push(error.describe()), + } + } + + fn refresh_palette(&mut self) { + let background = match (&self.image, self.bg_enabled) { + (Some(image), true) => Source::Pixels(image), + (None, true) if !self.bg_path.trim().is_empty() => Source::Undecodable, + _ => Source::Absent, + }; + // 桌面壁纸探测（M73）尚未落地：这一级永远 `Absent`，回落链仍按 design 的规则走。 + self.resolved = Some(palette::resolve( + self.palette_source, + background, + Source::Absent, + self.flavor, + )); + } +} + +fn env_f32(key: &str) -> Option { + 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/content.rs b/crates/app-iced/src/pages/content.rs new file mode 100644 index 0000000..736ee55 --- /dev/null +++ b/crates/app-iced/src/pages/content.rs @@ -0,0 +1,99 @@ +//! # 内容库页（M109 `CONTENTDL`）：整合包 / Mod / 资源包 / 光影 +//! +//! 用户令：「下载页只负责下载整合包和Mod/光影」。于是版本管理页（M107/M108 改名）只做版本， +//! **这一页**做内容：四条内容类型（页内一级侧栏）+ 关键词/来源/版本/加载器/排序筛选 + +//! 结果列表与详情面板 + **一键装入指定实例**。 +//! +//! ## 入口（B1 裁定：不新增导航项） +//! +//! `Route::Content` 是新顶层路由，但 `Route::nav()` 返回 `NavSection::Download`：导航轨仍是 +//! 五项，页头右上是「版本管理 | 内容库」一级切换（[`parts::section_switcher`]）。 +//! 为什么不是第六个图标：轨宽 88 塞六项会挤，且用户要的是「同一入口下两块内容」。 +//! +//! ## 分页 vs 无限滚动：**选分页** +//! +//! 三条理由，都是这一页的实际约束： +//! +//! 1. **快照只有一个槽**（`AppState::content.results`）：无限滚动要求「滚到底就自动续」，而 +//! 自动续在没有虚拟化列表的 iced 里会一次挂上几百个控件； +//! 2. **翻页要有明确出口**：站点限流 / 失败重试都发生在「下一批」上，用户得能看见自己正在 +//! 等第 3 页，而不是画面莫名一卡； +//! 3. **可截图复现**：分页的每一次状态都是一份确定的快照，D30 的矩阵能钉住「还有更多 / 没有更多了」。 +//! +//! 所以尾部是一个「加载更多」按钮 + 一句「没有更多了」（[`parts::more`]），追加逻辑在 +//! presenter 的 `AppState::apply_content`（同条件换页 ⇒ 追加；换条件 ⇒ 整批替换；迟到 ⇒ 丢掉）。 +//! +//! ## 四态（都必须能画出来） +//! +//! | 态 | 判据 | 画什么 | +//! |---|---|---| +//! | 加载 | `pending` 或还没有结果 | 一句「正在加载」+ 说明 + 重试 | +//! | 空 | 拉到了、零命中 | 真 `EmptyState` + 重试 CTA | +//! | 失败 | `failed` 有原因 | `Error` 图标 + 原因原文 + 重试（实心） | +//! | 有数据 | 有命中项 | 计数头 + 列表 +（还有更多 ⇒ 加载更多 / 否则 ⇒ 没有更多了） | +//! +//! ## 不在这里做的事 +//! +//! - **不发 HTTP**：检索与装入都在 presenter 的 `host/addon`（任务书第 4 条）。 +//! - **不做乐观回显**：点「装入」不改本地状态，进度只由 `InstallProgress` 事件回流。 +//! - **不自己画安装面板**：复用 `pages::download::install_panel`（同一个函数、同一套文案）。 +//! +//! ## 偏离登记 +//! +//! | # | 偏离 | 为什么 | 何时收口 | +//! |---|---|---|---| +//! | 1 | 四种内容类型借用现有字形（`Folder` / `Plus` / `Restore` / `Expand`，见 `parts::kind_icon`） | 设计令牌的 28 枚图标里没有这四类内容，且**不许**借用导航那五枚（同屏撞形）、不许用填充字形（门禁） | 图标集补「整合包 / Mod / 资源包 / 光影」时 | +//! | 2 | 本页自带一份栏几何（`content/layout.rs`） | M107 的 `pages/layout/rails.rs` 未并入本分支的 base | M107 合并后改为复用、删掉本文件 | +//! | 3 | 整合包的「装入」是禁用态 | core 没有远程整合包的安装管线 | 导入管线落地后接同一入口 | +//! | 5 | CurseForge 的「装入」同样是禁用态（`Blocker::SourceNotWired`） | 检索通了，**文件端点**还没接（CF 的文件列表要带 key） | 接上 CF 文件端点后删掉这条原因 | +//! | 4 | 安装进度只有阶段级（无字节条） | presenter 依赖表里没有 tokio/futures，拿不到 `ProgressEmitter` 的接收端 | presenter 补依赖后换成字节级 | + +mod demo; +mod layout; +mod message; +mod model; +// M113: import/export —— 导入/导出区的界面（新代码全在 `packui*`） +mod packui; +mod parts; +mod view; + +#[cfg(test)] +mod tests; + +pub use message::Message; +pub use model::{loader_name, Blocker, Content, ContentQueryView, Hit, PageState, Status, Target}; +// M113: import/export +pub use packui::{request_export, Pack, PackMessage, PackPageState}; + +use iced::Element; + +use unlucky_i18n::Lang; + +pub use unlucky_presenter::dto::ContentKind; + +use crate::pages::layout::FrameMetrics; +use crate::pages::Message as PageMessage; +use crate::theme::Ui; + +/// 整页入口（`pages/mod.rs` 的 `render` 调它；页面层不认识 presenter 的 DTO）。 +pub fn view<'a>( + ui: &'a Ui, + metrics: FrameMetrics, + model: &'a Content, + lang: Lang, +) -> Element<'a, PageMessage> { + view::view(ui, metrics, model, lang) +} + +/// 演示数据（`pages_demo` 出图与单测用；产品路径走 `Content::from_snapshot`）。 +pub fn demo(kind: ContentKind, lang: Lang) -> Content { + demo::demo(kind, lang) +} + +/// 页头那条一级切换（版本管理页也要用同一个函数：两页共用一个入口才不会各画一套）。 +pub(crate) fn section_switcher<'a>( + ui: &'a Ui, + catalog: unlucky_i18n::Catalog, +) -> Element<'a, PageMessage> { + parts::section_switcher(ui, catalog, true) +} diff --git a/crates/app-iced/src/pages/content/demo.rs b/crates/app-iced/src/pages/content/demo.rs new file mode 100644 index 0000000..9259019 --- /dev/null +++ b/crates/app-iced/src/pages/content/demo.rs @@ -0,0 +1,221 @@ +//! 内容库的演示数据（`pages_demo` 出图与单测用；产品路径永远走 `Content::from_snapshot`）。 +//! +//! ## 为什么要环境变量选「哪一屏」 +//! +//! D30 的验收矩阵要求「四类内容 × 浅/深」加「搜索无结果」「加载器不兼容禁用」两种状态， +//! 共 10 张。`pages_demo` 的 `--screen=` 只够选到**哪一页**，选不到「同一页的哪一态」； +//! 而 `pages/harness.rs` 与 `cli.rs` 不在本 mission 的 scope。 +//! +//! 所以沿用本仓既有的取证开关范式（`ULL_START_ROUTE` / `ULL_APPEARANCE_*` / `ULL_TICK_TRACE`）： +//! +//! | 变量 | 取值 | 作用 | +//! |---|---|---| +//! | `ULL_CONTENT_KIND` | `modpack` / `mod` / `resourcepack` / `shader` | 选内容类型（默认 `mod`） | +//! | `ULL_CONTENT_STATE` | `ok` / `empty` / `incompatible` | 选状态（默认 `ok`） | +//! +//! 只影响本来就用演示数据的 harness 路径；产品二进制里 `demo()` 根本不会被调用。 + +use unlucky_i18n::{Catalog, Lang}; +use unlucky_presenter::dto::{ContentHit, ContentKind, ContentSort, ContentSource, LoaderKind}; + +use super::model::{blockers_of, Content, ContentQueryView, Hit, HitFacts, Status, Target}; +use crate::pages::download::Download; + +/// 一个固定的演示环境：两个实例（一个 Fabric / 一个 Forge）。 +fn targets() -> Vec { + 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"; + // 「装入中」那一屏：面板就是下载页那块（同一个函数），用来证明它在内容库语义下也可读 + let installing = state == "install"; + let list = if empty { + Vec::new() + } else { + hits(kind, catalog, state != "incompatible") + }; + // 「不兼容」那一屏：选中的那条是 1.21.1 + Forge 的项目，而目标是 1.20.1 + Fabric + // 「CF 未接通」那一屏：选中的那条来自 CurseForge（文件端点还没接，按钮必须禁用） + let selected_index = match state.as_str() { + "incompatible" => 2, + "cf" => 1, + _ => 0, + }; + let selected = list.get(selected_index).map(|hit| hit.id.clone()); + let blockers = blockers_of( + list.get(selected_index).map(|hit| HitFacts { + versions: hit.versions.as_slice(), + loaders: hit.loaders.as_slice(), + source: hit.source, + }), + kind, + &targets, + target.as_deref(), + ); + let target_label = targets + .iter() + .find(|item| Some(&item.id) == target.as_ref()) + .map(|item| item.label()); + + // M113: import/export —— 导入导出区自己那一态由 `ULL_CONTENT_PACK` 选 + // （`importing` / `partial` / `conflict` / `export`；不设 = 只有入口） + let pack = super::packui::demo_pack(lang).0; + + Content { + kind, + query: ContentQueryView { + source: ContentSource::Modrinth, + sort: ContentSort::Relevance, + version: Some("1.20.1".to_string()), + loader: Some(LoaderKind::Fabric), + text: if empty { + "quarkonium".to_string() + } else { + String::new() + }, + }, + hits: list, + selected, + status: if empty { Status::Empty } else { Status::Ready }, + total: if empty { 0 } else { 1_284 }, + // 演示数据故意把 `has_more` 置真（真实判据是「本页装满」）：出图要能看到「加载更多」 + has_more: !empty, + curseforge: false, + targets, + target: target.clone(), + target_label, + blockers, + panel: if installing { + Some(install_panel(catalog)) + } else { + None + }, + versions: vec!["1.20.1".to_string(), "1.21.1".to_string()], + draft: if empty { + "quarkonium".to_string() + } else { + String::new() + }, + pack, + } +} diff --git a/crates/app-iced/src/pages/content/layout.rs b/crates/app-iced/src/pages/content/layout.rs new file mode 100644 index 0000000..b2a253a --- /dev/null +++ b/crates/app-iced/src/pages/content/layout.rs @@ -0,0 +1,194 @@ +//! 内容库页的栏几何（纯函数 + 数值表）。 +//! +//! ## 为什么这一页自带一份几何 +//! +//! 任务书要求「与 M107 同一套视觉语言」：类型栏 140 / 图标栏 64、间距 24、列表列下限 424 +//! （行宽红线）、详情 320。M107 的那份几何在 `pages/layout/rails.rs`（M107 分支，尚未并入 main）， +//! 本 mission 的分支基于 main，所以这里按**同一组数值**先落一份，并在报告里登记 +//! 「M107 合并后应改为复用 `pages/layout/rails.rs`，删掉本文件」。 +//! +//! ## 四档的判据是**算出来的**，不是拍的 +//! +//! | 档 | 条件（可用宽，已扣导航轨与页边距） | 版面 | +//! |---|---|---| +//! | `Wide` | ≥ 140 + 24 + 424 + 24 + 320 = **932** | 标签栏 + 列表 + 详情 | +//! | `Narrow` | ≥ 64 + 24 + 424 + 24 + 320 = **856**（类型栏收成图标栏） | 图标栏 + 列表 + 详情 | +//! | `Compact` | ≥ 140 + 24 + 424 = **588** | 标签栏 + 单列（详情整页替换列表） | +//! | `Tight` | 其余 | 类型条变成顶部一行 chip + 单列 | +//! +//! 三个门槛都是「Σ栏宽 + 间距」算出来的，改动任何一档都会让数值表用例红。 + +use unlucky_design::spacing::Space; + +use crate::pages::layout; + +/// 类型栏宽（标签形态）。 +/// +/// M107 的版本类型栏是 140；这里取 200：四个**内容类型**的名字（`Resource packs`）比 +/// 版本类型（`Release` / `Snapshot`）长，140 会把标签切掉。登记在 `pages/content.rs` 的偏离表。 +pub const RAIL_LABEL: f32 = 200.0; +/// 类型栏宽（图标形态）。 +pub const RAIL_ICON: f32 = 64.0; +/// 详情面板宽。 +pub const DETAIL: f32 = 320.0; +/// 栏间距（`Space::X6` = 24，与 `pages::layout::PANES_GAP` 同源）。 +pub const GAP: f32 = Space::X6.dp(); + +/// 一屏三栏各自多宽。 +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct Rails { + /// 档位 + pub tier: Tier, + /// 类型栏宽（`Tight` 档是 0：类型条在顶部） + pub rail: f32, + /// 列表列宽 + pub list: f32, + /// 详情面板宽（0 = 这一档没有独立详情列） + pub detail: f32, + /// 栏间距 + pub gap: f32, +} + +/// 版面档位。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Tier { + /// 标签栏 + 列表 + 详情 + Wide, + /// 图标栏 + 列表 + 详情 + Narrow, + /// 标签栏 + 单列 + Compact, + /// 顶部 chip 条 + 单列 + Tight, +} + +impl Tier { + /// 这一档有独立详情列吗。 + pub const fn has_detail(self) -> bool { + matches!(self, Self::Wide | Self::Narrow) + } + + /// 这一档的类型栏是标签形态吗（`Tight` 没有栏）。 + pub const fn rail_has_labels(self) -> bool { + matches!(self, Self::Wide | Self::Compact) + } +} + +/// `Wide` 的门槛：标签栏 + 间距 + 列表下限 + 间距 + 详情。 +pub fn wide_min() -> f32 { + RAIL_LABEL + GAP + layout::LINE_SAFE_WIDTH_PX + GAP + DETAIL +} + +/// `Narrow` 的门槛：图标栏 + 间距 + 列表下限 + 间距 + 详情。 +pub fn narrow_min() -> f32 { + RAIL_ICON + GAP + layout::LINE_SAFE_WIDTH_PX + GAP + DETAIL +} + +/// `Compact` 的门槛：标签栏 + 间距 + 列表下限。 +pub fn compact_min() -> f32 { + RAIL_LABEL + GAP + layout::LINE_SAFE_WIDTH_PX +} + +/// 可用宽 → 三栏几何。 +pub fn resolve(available: f32) -> Rails { + let cap = layout::measure_cap_px(); + + if available >= wide_min() { + let rail = RAIL_LABEL; + return Rails { + tier: Tier::Wide, + rail, + gap: GAP, + detail: DETAIL, + list: (available - rail - GAP - DETAIL - GAP).max(layout::LINE_SAFE_WIDTH_PX), + }; + } + if available >= narrow_min() { + let rail = RAIL_ICON; + return Rails { + tier: Tier::Narrow, + rail, + gap: GAP, + detail: DETAIL, + list: (available - rail - GAP - DETAIL - GAP).max(layout::LINE_SAFE_WIDTH_PX), + }; + } + if available >= compact_min() { + let rail = RAIL_LABEL; + return Rails { + tier: Tier::Compact, + rail, + gap: GAP, + detail: 0.0, + list: (available - rail - GAP).min(cap.max(layout::LINE_SAFE_WIDTH_PX)), + }; + } + Rails { + tier: Tier::Tight, + rail: 0.0, + gap: GAP, + detail: 0.0, + list: available.min(cap.max(layout::LINE_SAFE_WIDTH_PX)), + } +} + +#[cfg(test)] +mod tests { + use super::*; + + /// 门槛必须由「Σ栏宽 + 间距」算出来（抓得住：谁把 932 抄成 900 这种拍值）。 + #[test] + fn the_three_thresholds_are_sums_not_magic_numbers() { + assert_eq!(wide_min(), 200.0 + 24.0 + 424.0 + 24.0 + 320.0); + assert_eq!(narrow_min(), 64.0 + 24.0 + 424.0 + 24.0 + 320.0); + assert_eq!(compact_min(), 200.0 + 24.0 + 424.0); + assert_eq!(wide_min(), 992.0); + assert_eq!(narrow_min(), 856.0); + assert_eq!(compact_min(), 648.0); + } + + #[test] + fn each_tier_takes_effect_at_its_own_threshold() { + assert_eq!(resolve(wide_min()).tier, Tier::Wide); + assert_eq!(resolve(wide_min() - 0.5).tier, Tier::Narrow); + assert_eq!(resolve(narrow_min()).tier, Tier::Narrow); + assert_eq!(resolve(narrow_min() - 0.5).tier, Tier::Compact); + assert_eq!(resolve(compact_min()).tier, Tier::Compact); + assert_eq!(resolve(compact_min() - 0.5).tier, Tier::Tight); + } + + #[test] + fn a_wide_page_never_gives_the_list_less_than_the_row_width_red_line() { + // 1180 窗宽（右栗收起）：1044 可用 → Wide，列表 536 + let rails = resolve(1044.0); + assert_eq!(rails.tier, Tier::Wide); + assert!(rails.list >= layout::LINE_SAFE_WIDTH_PX, "{}", rails.list); + // 逐档扫一遍：只要还有独立列表列，就不许低于 424（行宽红线） + for available in 500..=1600 { + let rails = resolve(available as f32); + if rails.rail > 0.0 { + assert!( + rails.list >= layout::LINE_SAFE_WIDTH_PX, + "available={available} 时列表只剩 {}", + rails.list + ); + } + } + } + + #[test] + fn the_detail_column_only_exists_in_the_two_wide_tiers() { + assert!(Tier::Wide.has_detail()); + assert!(Tier::Narrow.has_detail()); + assert!(!Tier::Compact.has_detail()); + assert!(!Tier::Tight.has_detail()); + assert_eq!(resolve(1200.0).detail, DETAIL); + assert_eq!(resolve(700.0).detail, 0.0); + // 图标形态只在这两档出现，且窄档的标签栏不存在 + assert_eq!(resolve(900.0).rail, RAIL_ICON); + assert_eq!(resolve(700.0).rail, RAIL_LABEL); + assert_eq!(resolve(400.0).rail, 0.0); + assert!(Tier::Wide.rail_has_labels()); + assert!(!Tier::Narrow.rail_has_labels()); + } +} diff --git a/crates/app-iced/src/pages/content/message.rs b/crates/app-iced/src/pages/content/message.rs new file mode 100644 index 0000000..a5e9286 --- /dev/null +++ b/crates/app-iced/src/pages/content/message.rs @@ -0,0 +1,42 @@ +//! 内容库页的**自有**消息（M109）。 +//! +//! 与设置页同一个范式（`pages/settings/message.rs` + `pages::Message::Settings`）：页面自己的一套 +//! 意图在这个文件里声明，`pages::Message` 只留一个 `Content(..)` 投递口，于是「加一条内容库消息」 +//! 不碰共享枚举的正文，也不碰 `app/update/page_messages.rs` 那条不许 `_ =>` 的 match。 +//! +//! **一条纪律**：这里的每个变体都是**意图**，不是状态变更。改了条件 ≠ 已经发请求 +//! （`QueryChanged` 只改输入框里的字，`Search` 才发指令）；点了「装入」≠ 已装上 +//! （装上的证据是 `InstallProgress` 事件回流到面板）。 + +use unlucky_presenter::dto::{ContentKind, ContentSort, ContentSource, LoaderKind}; + +/// 内容库页的消息。 +#[derive(Debug, Clone)] +pub enum Message { + /// 换内容类型（左侧四条一级侧栏） + SetKind(ContentKind), + /// 关键词输入框变了（**只改草稿**，不 dispatch） + QueryChanged(String), + /// 提交搜索（零偏移重来） + Search, + /// 换来源（Modrinth / CurseForge） + SetSource(ContentSource), + /// 换排序 + SetSort(ContentSort), + /// 换游戏版本过滤（`None` = 不限） + SetVersion(Option), + /// 换加载器过滤（`None` = 不限） + SetLoader(Option), + /// 选中一个项目（**页面内选中**，不 dispatch） + Select(String), + /// 选目标实例（一键装入的对象） + SetTarget(String), + /// 加载下一页 + LoadMore, + /// 同条件重试（失败态的出口） + Retry, + /// 装进目标实例 + Install, + /// 导入/导出区（M113：整合包导入与导出；一切细节在 `packui::Message`） + Pack(super::packui::PackMessage), +} diff --git a/crates/app-iced/src/pages/content/model.rs b/crates/app-iced/src/pages/content/model.rs new file mode 100644 index 0000000..f9f9199 --- /dev/null +++ b/crates/app-iced/src/pages/content/model.rs @@ -0,0 +1,301 @@ +//! 内容库页的视图模型：**presenter 快照 + 页面选中项 → 要画的东西**。 +//! +//! ## 分层（与实例页 / 下载页同一条） +//! +//! | 数据源 | 谁转 | 用途 | +//! |---|---|---| +//! | `AppState::content`（检索条件 + 结果 + 请求态） | [`Content::from_snapshot`] | 产品运行时的真页面 | +//! | [`super::demo`] 的固定夹具 | 同上 | `pages_demo` 出图与单测 | +//! +//! ## 「点之前就知道装不装得上」（任务书第 3 条） +//! +//! 兼容性判定在 [`Content::blockers`]：**纯函数**，输入是「选中的项目 + 目标实例」， +//! 输出是 [`Blocker`] 列表。视图拿它决定按钮 `disabled` 与旁边那几句原因——于是「点完才报错」 +//! 在结构上不可能发生（按钮根本发不出消息）。 +//! +//! 两条判据各自独立、**都能同时成立**（版本对不上 + 加载器也不对）：把两条合成一条会在 +//! 「都不兼容」时只说一半原因。 +//! +//! ## 为什么要 `PageState`（页面自留的那点状态） +//! +//! `kind` / `selected` / `target` / `draft` 都是**页面内**的选择：检索条件与结果在 presenter +//! （`AppState::content`），这四样是「用户在这一屏上点了什么」，重建快照不该把它们冲掉。 +//! 它们的所有者是 `app/state.rs` 的 `App::content`，本文件只借用。 + +use unlucky_presenter::dto::{ + loader_facet, ContentKind, ContentSort, ContentSource, ContentState, LoaderKind, +}; +use unlucky_presenter::state::AppState; + +use unlucky_i18n::Catalog; + +use crate::pages::download::Download; + +mod items; + +pub(crate) use items::HitFacts; +pub(crate) use items::{capitalize, thousands}; +pub use items::{loader_name, Blocker, Hit, PageState, Status, Target}; + +/// 内容库页要画的东西。 +#[derive(Debug, Clone, PartialEq)] +pub struct Content { + /// 当前内容类型（左栏四条侧栏的选中项） + pub kind: ContentKind, + /// 当前检索条件（筛选条 + 分页游标） + pub query: ContentQueryView, + /// 命中项 + pub hits: Vec, + /// 选中项 + 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, + /// 游戏版本筛选的候选（来自实例；去重、保持实例顺序） + pub versions: Vec, + /// 关键词草稿 + pub draft: String, + /// 导入/导出区（M113）：入口 + 进度 + 结果 + 导出预检 + pub pack: super::packui::Pack, +} + +/// 筛选条的展示态（数字/枚举都在这里，页面不再从 `ContentQuery` 里挖字段）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ContentQueryView { + /// 来源 + pub source: ContentSource, + /// 排序 + pub sort: ContentSort, + /// 游戏版本过滤 + pub version: Option, + /// 加载器过滤 + 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, + ); + + Self { + kind: page.kind, + query: ContentQueryView { + source: content.query.source, + sort: content.query.sort, + version: content.query.game_version.clone(), + loader: content.query.loader, + text: content.query.text.clone(), + }, + hits, + selected: page.selected.clone(), + status, + total: content.results.as_ref().map_or(0, |results| results.total), + // 读「最近一页是否装满」（不是累计条数）：见 `ContentState::last_page_filled` 的文档 + has_more: content.last_page_filled && !content.pending, + curseforge: content + .results + .as_ref() + .is_some_and(|results| results.curseforge), + targets, + target: target.clone(), + target_label, + blockers, + panel: content_install(state, catalog), + versions, + draft: page.draft.clone(), + pack, + } + } + + /// 选中项在命中列表里的那一行（详情面板读它）。 + pub fn selected_hit(&self) -> Option<&Hit> { + let id = self.selected.as_deref()?; + self.hits.iter().find(|hit| hit.id == id) + } + + /// 「装入」按钮此刻能不能按（`false` 时按钮禁用，`blockers()` 给原因）。 + pub fn can_install(&self) -> bool { + self.selected_hit().is_some() && self.blockers.is_empty() + } + + /// 原因的人读文案（顺序 = 判定顺序；空 = 没有原因）。 + pub fn blocker_reasons(&self, catalog: Catalog) -> Vec { + self.blockers + .iter() + .map(|blocker| blocker.reason(catalog)) + .collect() + } + + /// 加载中（首屏 / 换条件）。 + pub const fn is_loading(&self) -> bool { + matches!(self.status, Status::Loading) + } +} + +/// 快照 → 四态。判据只有三个字段（请求在飞 / 失败原因 / 命中项），没有第四份真相。 +fn status_of(content: &ContentState, hits: &[Hit]) -> Status { + if let Some(reason) = &content.failed { + return Status::Failed(reason.clone()); + } + if content.pending || content.results.is_none() { + return Status::Loading; + } + if hits.is_empty() { + Status::Empty + } else { + Status::Ready + } +} + +/// 安装面板（**只借用下载页那块面板**，不另写一套画法）。 +/// +/// 转换与「成功/取消这类终态不占面板」的判断都在 `pages::download::install_panel_model` 里 +/// （M105 起 `InstallView` 不再从那个模块导出）：内容库只拿 `Option`。 +fn content_install(state: &AppState, catalog: Catalog) -> Option { + state + .install + .as_ref() + .and_then(|progress| crate::pages::download::install_panel_model(progress, catalog)) +} + +/// 兼容性判定（**纯函数**，单测直接钉它；见模块文档第 2 节）。 +/// +/// `hit` 是「选中项的两个支持列表」：`None` = 没选中，`Some((版本, 加载器))` = 选中了。 +/// **空列表 ≠ 不兼容**：站点没给数据时按「未知」处理，不许把「不知道」画成「不支持」。 +pub(super) fn blockers_of( + hit: Option>, + 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..7e4be4e --- /dev/null +++ b/crates/app-iced/src/pages/content/model/items.rs @@ -0,0 +1,238 @@ +//! 内容库页的类型：页面自留状态 / 四态 / 展示行 / 目标实例 / 装不上的原因。 +//! +//! 从 `pages/content/model.rs` 拆出（那个文件已贴 400 行硬上限）。纯数据类型与纯函数， +//! 不认识 iced：`model/tests.rs` 直接钉它们的判定。 + +use unlucky_presenter::dto::{ContentHit, ContentKind, ContentSource, InstanceSummary, LoaderKind}; + +use unlucky_i18n::{Catalog, Key}; + +/// 页面自留的选择（检索条件与结果在 presenter 的 `AppState::content`）。 +#[derive(Debug, Clone, PartialEq)] +pub struct PageState { + /// 当前内容类型 + pub kind: ContentKind, + /// 选中的项目 id（`None` = 没选 → 详情面板空态） + pub selected: Option, + /// 目标实例 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), +} + +impl Status { + /// 失败了吗（视图用它决定画错误面板还是列表）。 + pub const fn failed(&self) -> bool { + matches!(self, Self::Failed(_)) + } +} + +/// 一条命中项的展示态（文案在这一层求好：iced 的文本控件借用内容）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Hit { + /// 项目 id（选中 / 装入指令的载荷） + pub id: String, + /// 标题 + pub title: String, + /// 一行说明 + pub summary: String, + /// 来源 + 作者（`Modrinth · jelly`） + pub supporting: String, + /// 下载量（已加千分位） + pub downloads: String, + /// 更新日期的人读串 + pub updated: String, + /// 支持的游戏版本（详情面板用；空 = 站点没给） + pub versions: Vec, + /// 支持的加载器（**站点原样的小写 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/tests.rs b/crates/app-iced/src/pages/content/model/tests.rs new file mode 100644 index 0000000..b20074b --- /dev/null +++ b/crates/app-iced/src/pages/content/model/tests.rs @@ -0,0 +1,294 @@ +//! 内容库视图模型的守门测试（M109）：四态判定、兼容性判定、装入闸门。 +//! +//! 全部是纯函数级断言（不开图形环境）：`status_of` / `blockers_of` / `Content::can_install` +//! 是页面「该画什么、按钮能不能按」的唯一判据，钉住它们比截图更早期。 + +use super::*; +use unlucky_i18n::Lang; +use unlucky_presenter::dto::{ + ContentHit, ContentKind, ContentQuery, ContentResults, ContentSource, InstanceRuntime, + LoaderKind, +}; + +fn hit(versions: &[&str], loaders: &[&str]) -> ContentHit { + ContentHit { + id: "p1".to_string(), + slug: "p".to_string(), + title: "Sodium".to_string(), + summary: "fast".to_string(), + author: "jelly".to_string(), + downloads: 10, + updated: "2026-01-01".to_string(), + source: ContentSource::Modrinth, + game_versions: versions.iter().map(|item| (*item).to_string()).collect(), + loaders: loaders.iter().map(|item| (*item).to_string()).collect(), + icon: None, + } +} + +fn targets() -> Vec { + 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("网络不通".to_string()); + let model = Content::from_snapshot(&state, &PageState::default(), Lang::En.catalog()); + assert_eq!(model.status, Status::Failed("网络不通".to_string())); + assert!(model.status.failed()); +} + +#[test] +fn can_install_needs_a_selection_and_no_blockers() { + let mut state = state_with(Some(results(vec![hit(&["1.20.1"], &["fabric"])], 0)), false); + state.instances = vec![unlucky_presenter::dto::InstanceSummary { + id: "fabric-1.20.1".to_string(), + name: "Survival".to_string(), + mc_version: "1.20.1".to_string(), + loader: unlucky_presenter::dto::LoaderInfo { + kind: LoaderKind::Fabric, + version: "0.16.5".to_string(), + }, + last_played: None, + runtime: InstanceRuntime::Idle, + icon: None, + isolation: "isolated".to_string(), + version_id: "1.20.1".to_string(), + version_present: true, + }]; + let catalog = Lang::En.catalog(); + let page = PageState { + kind: ContentKind::Mod, + selected: None, + target: None, + draft: String::new(), + pack: super::super::packui::PackPageState::default(), + }; + + // 没选中项目 ⇒ 不能装（也不该说「成功」） + let no_selection = Content::from_snapshot(&state, &page, catalog); + assert!(!no_selection.can_install()); + assert_eq!( + no_selection.target.as_deref(), + Some("fabric-1.20.1"), + "只有一个实例就默认选它" + ); + + // 选中兼容项 ⇒ 能装 + let page = PageState { + selected: Some("p1".to_string()), + ..page + }; + let compatible = Content::from_snapshot(&state, &page, catalog); + assert!(compatible.can_install()); + assert!(compatible.blocker_reasons(catalog).is_empty()); + assert!(compatible.target_label.is_some()); +} + +#[test] +fn the_panel_only_shows_while_an_install_is_unfinished() { + use unlucky_presenter::dto::{InstallProgressView, InstallStage}; + + let mut state = state_with(None, false); + state.install = Some(InstallProgressView { + version: "Sodium".to_string(), + stage: InstallStage::Downloading, + files_total: 1, + ..InstallProgressView::new() + }); + let running = Content::from_snapshot(&state, &PageState::default(), Lang::En.catalog()); + assert!(running.panel.is_some(), "下载中要有面板"); + + state.install = Some(InstallProgressView { + stage: InstallStage::Done, + ..InstallProgressView::new() + }); + let done = Content::from_snapshot(&state, &PageState::default(), Lang::En.catalog()); + assert!(done.panel.is_none(), "装完的面板不该钉在页面上"); +} + +#[test] +fn loader_names_are_ascii_so_the_english_baseline_stays_english() { + for loader in [ + LoaderKind::Vanilla, + LoaderKind::Fabric, + LoaderKind::Forge, + LoaderKind::NeoForge, + LoaderKind::Quilt, + ] { + assert!(loader_name(loader).is_ascii(), "{loader:?}"); + } + assert_eq!( + loader_name(LoaderKind::Vanilla), + "Vanilla", + "不能画「原版」" + ); +} diff --git a/crates/app-iced/src/pages/content/packui.rs b/crates/app-iced/src/pages/content/packui.rs new file mode 100644 index 0000000..c734909 --- /dev/null +++ b/crates/app-iced/src/pages/content/packui.rs @@ -0,0 +1,57 @@ +//! 整合包**导入 / 导出**区（M113 `PACKUI`）：内容库页里「把我的包装进来」与「把我的实例打出去」。 +//! +//! ## 为什么长在内容库页上 +//! +//! 用户令：「下载页只负责下载整合包和Mod/光影」+「支持当前主流的整合包格式导入导出的功能」。 +//! 下载页（+内容库）是「拿内容进来」的地方，所以： +//! +//! - **导入**（本地包 → 实例）：入口在这里，和「从站点拿整合包」摆在同一页； +//! - **导出**（实例 → 包）：同一块，选目标实例 + 格式，预检之后再写盘。 +//! +//! ## 三种格式都是 core 的既有能力，本模块只做界面 +//! +//! | 格式 | 导入 | 导出 | 界面上的如实说明 | +//! |---|---|---|---| +//! | CurseForge `manifest.json` | 是（`files[]` 远程补全**未接通**） | 是 | 缺 CF 客户端 ⇒ 那些条目只能记成「没搞到」，逐条列出，**绝不猜 URL** | +//! | Modrinth `.mrpack` | 是 | 是 | —— | +//! | MultiMC / Prism 实例目录 | 是 | **否**（core 有意省略） | 文案明写「只能导入、不能导出」 | +//! +//! `.disabled` 是**路径后缀**（不是 `env.client=optional`）——这条在导出预检的逐条原因里出现， +//! 界面上不解释「可选依赖」，因为那不是同一件事。 +//! +//! ## 文件分工 +//! +//! | 文件 | 职责 | +//! |---|---| +//! | [`message`] | 本区的意图（挂在 `content::Message::Pack` 下） | +//! | [`model`] | 视图模型（快照 → 要画的东西；纯决策可单测） | +//! | [`view`] | 画法（进度**整块**复用下载页的安装面板） | +//! | `demo` | 出图夹具（`ULL_CONTENT_PACK` 选态） | +//! +//! ## 本版明确的边界（报告里同样登记） +//! +//! - **没有系统文件选择框**：依赖树里没有 `rfd` 一类的对话框依赖，加它要动根 `Cargo.toml`、 +//! 过许可门禁、还要给 Linux 选后端（GTK / xdg-portal），直接影响「单文件产物」。所以入口是 +//! **拖拽（真能用）+ 路径输入框**，并且把原因写在界面上（[`model::Pack::no_dialog_note`]）。 +//! - **冲突没有逐文件决策**：core 的 `ConflictPolicy` 是整次导入一个全局档（`KeepUser` 默认 / +//! `Overwrite`），`ConflictFile` 是**事后账**。所以这一块给的是「逐文件看 + 整体翻档」， +//! 文案如实写「两者都留（改名）暂不支持」。逐文件策略已登记为后续 core mission。 + +mod demo; +mod message; +mod model; +mod view; + +#[cfg(test)] +mod tests; + +pub use message::Message as PackMessage; +pub use model::{request_export, Pack, PackPageState}; + +/// 区入口（内容库页的正列调它）。 +pub(crate) use view::section; + +/// 出图夹具：按 `ULL_CONTENT_PACK` 选态（`importing` / `partial` / `conflict` / `export`）。 +pub(crate) fn demo_pack(lang: unlucky_i18n::Lang) -> (Pack, PackPageState) { + demo::pack(lang) +} diff --git a/crates/app-iced/src/pages/content/packui/demo.rs b/crates/app-iced/src/pages/content/packui/demo.rs new file mode 100644 index 0000000..47ad0ea --- /dev/null +++ b/crates/app-iced/src/pages/content/packui/demo.rs @@ -0,0 +1,245 @@ +//! 出图夹具（D30）：`ULL_CONTENT_PACK` 选「同一页的哪一态」。 +//! +//! ## 为什么是环境变量 +//! +//! `pages_demo` 的 `--screen=` 只够选到**哪一页**，选不到「同一页的哪一态」；而 +//! `pages/harness.rs` 与 `cli.rs` 不在本 mission 的 scope。所以沿用本仓既有的取证开关范式 +//! （`ULL_START_ROUTE` / `ULL_CONTENT_KIND` / `ULL_CONTENT_STATE`）： +//! +//! | 变量 | 取值 | 作用 | +//! |---|---|---| +//! | `ULL_CONTENT_PACK` | `importing` / `partial` / `conflict` / `failed` / `export` | 选导入导出区的哪一态（不设 = 只有入口） | +//! +//! 夹具**不直接造视图模型**，而是造 presenter 侧的快照（`ImportState` / `ExportState`）， +//! 再走产品路径同一个 [`Pack::of`]。这样截图里看到的每一行字都是产品路径会画的那一行， +//! 而不是「为了出图另写一套」。 + +use std::path::PathBuf; + +use unlucky_i18n::Lang; +use unlucky_presenter::dto::{ + ConflictChoiceView, ConflictFileView, ConflictReasonView, ExportClassView, ExportFileView, + ExportPreviewView, ExportReasonView, ExportState, FileActionView, ImportErrorView, + ImportProgressView, ImportReportView, ImportStageView, ImportState, ImportStatusView, + InstanceId, LoaderKind, MissingFileView, MissingReasonView, PackFormatView, +}; + +use crate::pages::content::Target; + +use super::model::{Pack, PackPageState}; + +/// 取证开关名。 +const ENV_PACK: &str = "ULL_CONTENT_PACK"; + +/// 两个实例（与内容库页的演示环境同一批，避免同一张图上出现两套实例名）。 +fn targets() -> Vec { + 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()), + "partial" => import.report = Some(report(ImportStatusView::Partial, false)), + "conflict" => { + import.report = Some(report(ImportStatusView::Partial, true)); + page.expanded = Some("config/sodium-options.json".to_string()); + } + // 致命态：整包回滚 + 容忍域仍在（展示两类失败的视觉分野） + "failed" => { + let mut fatal = report(ImportStatusView::Failed, false); + fatal.error = Some(ImportErrorView { + code: "pack_traversal".to_string(), + label: "Path traversal".to_string(), + message: "overrides/../../etc/passwd".to_string(), + hint: Some("Re-download the pack from its source".to_string()), + }); + fatal.files.clear(); + fatal.bytes_written = 0; + import.report = Some(fatal); + } + // 取消态：面板收回了，但「后台还在跑」这句话要留在屏上 + "cancelled" => import.cancelled = true, + "export" => { + page.export_open = true; + page.export_name = "Survival 1.20.1".to_string(); + export.preview = Some(preview()); + } + _ => {} + } + + let model = Pack::of(&import, &export, &page, &targets(), catalog); + (model, page) +} + +/// 导入中：第 2 阶段（解包覆盖内容），计数已知。 +fn progress() -> ImportProgressView { + ImportProgressView { + stage: ImportStageView::Extract, + done: 418, + total: 640, + current: Some("overrides/config/sodium-options.json".to_string()), + pack: "Better MC 1.2.0".to_string(), + } +} + +/// 一条落地文件。 +fn file( + path: &str, + action: FileActionView, + bytes: u64, +) -> unlucky_presenter::dto::ImportedFileView { + unlucky_presenter::dto::ImportedFileView { + path: path.to_string(), + action, + bytes, + } +} + +/// 报告（`conflicts` 决定造不造冲突那一块）。 +fn report(status: ImportStatusView, conflicts: bool) -> ImportReportView { + let mut report = ImportReportView { + status, + format: Some(PackFormatView::Curseforge), + pack_name: Some("Better MC".to_string()), + pack_version: Some("1.2.0".to_string()), + game_version: Some("1.20.1".to_string()), + loader: Some("fabric-loader 0.15.11".to_string()), + version_id: Some("1.20.1-fabric0.15.11".to_string()), + target: PathBuf::from("C:/ULL/instances/survival/.minecraft"), + files: vec![ + file("mods/sodium.jar", FileActionView::Installed, 812_000), + file("mods/lithium.jar", FileActionView::Installed, 640_000), + file("config/xaeroplus.cfg", FileActionView::KeptUser, 4_200), + ], + conflicts: Vec::new(), + missing: vec![ + MissingFileView { + path: Some("mods/create-1.2.3.jar".to_string()), + display: "mods/create-1.2.3.jar".to_string(), + reason: MissingReasonView::FetchFailed, + detail: "HTTP 404".to_string(), + }, + MissingFileView { + path: None, + display: "123456:789012".to_string(), + reason: MissingReasonView::NoSource, + detail: "CurseForge 文件端点未接通".to_string(), + }, + MissingFileView { + path: Some("mods/jei-1.20.1.jar".to_string()), + display: "mods/jei-1.20.1.jar".to_string(), + reason: MissingReasonView::Offline, + detail: String::new(), + }, + ], + rejected: vec!["org.lwjgl3:3.3.1".to_string()], + warnings: vec!["`server-overrides/` was not unpacked (client import)".to_string()], + error: None, + registered: Some("Survival".to_string()), + bytes_written: 3_400_000, + rolled_back: true, + }; + if conflicts { + report.conflicts = vec![ + conflict( + "config/sodium-options.json", + ConflictReasonView::UserModified, + ), + conflict("mods/xaeroplus.jar", ConflictReasonView::UserDeleted), + conflict("options.txt", ConflictReasonView::PreExisting), + ]; + } + report +} + +fn conflict(path: &str, reason: ConflictReasonView) -> ConflictFileView { + ConflictFileView { + path: path.to_string(), + reason, + // 默认档永远是「保留我的」——夹具也一样，截图不许示范成默认覆盖 + choice: ConflictChoiceView::KeepUser, + pack_sha1: "9f2c41ab77de3350aa1b8c0d5e6f708192a3b4c5".to_string(), + base_sha1: Some("3a7d90ff11bc22445566ef7788990011aabbccdd".to_string()), + disk_sha1: Some("c1d2e3f4050617283940a5b6c7d8e9f0a1b2c3d4".to_string()), + pack_size: 4_200, + } +} + +/// 导出预检：12 内联 / 1 跳过（包不完整）。 +fn preview() -> ExportPreviewView { + let mut files = vec![ExportFileView { + path: "mods/create-1.2.3.jar".to_string(), + class: ExportClassView::Inline, + reason: ExportReasonView::NoRemoteMatch, + bytes: 2_100_000, + disabled: false, + }]; + for index in 0..11 { + files.push(ExportFileView { + path: format!("mods/generated-{index:02}.jar"), + class: ExportClassView::Inline, + reason: ExportReasonView::NoRemoteMatch, + bytes: 512_000, + disabled: false, + }); + } + // 13 条「没进包」是真实形态：预检那块必须自己做有界滚动，否则把「确认写盘」顶出屏幕 + for index in 0..12 { + files.push(ExportFileView { + path: format!("mods/.cache/backup-{index:02}.jar"), + class: ExportClassView::Skipped, + reason: ExportReasonView::SymbolicLink, + bytes: 0, + disabled: false, + }); + } + files.push(ExportFileView { + path: "mods/bad:name.jar".to_string(), + class: ExportClassView::Skipped, + reason: ExportReasonView::UnsafePath, + bytes: 0, + disabled: false, + }); + + ExportPreviewView { + format: PackFormatView::Modrinth, + instance: "survival".to_string(), + name: "Survival 1.20.1".to_string(), + version: "1.0.0".to_string(), + target: PathBuf::from("C:/ULL/downloads/Survival-1.0.0.mrpack"), + files, + notes: vec![ + "CF 表达不了禁用位：`.disabled` 文件已内联".to_string(), + "离线目录：所有文件都证明不了可被远程替代，全部内联".to_string(), + ], + } +} diff --git a/crates/app-iced/src/pages/content/packui/message.rs b/crates/app-iced/src/pages/content/packui/message.rs new file mode 100644 index 0000000..62b8983 --- /dev/null +++ b/crates/app-iced/src/pages/content/packui/message.rs @@ -0,0 +1,57 @@ +//! 整合包导入/导出区的**自有**消息（M113 `PACKUI`）。 +//! +//! 与内容库页同一个范式（`pages/content/message.rs`）：这一支挂在 +//! [`super::Message::Pack`] 下面，`pages::Message` 只留 `Content(..)` 一个投递口， +//! 于是「加一条导入/导出消息」不碰共享枚举的正文，也不碰 `app/update/page_messages.rs` +//! 那条**不许 `_ =>`** 的 match。 +//! +//! **一条纪律**（与内容库页同一句）：这里的每个变体都是**意图**，不是状态变更。 +//! 拖入文件 ≠ 已经导入（证据是 `ImportProgress` / `ImportReport` 事件回流）； +//! 点「导出」≠ 已经写了盘（证据是预检与 `ExportDone` 事件）。 + +use std::path::PathBuf; + +use unlucky_presenter::dto::{InstanceId, PackFormatView}; + +/// 导入/导出区的消息。 +#[derive(Debug, Clone)] +pub enum Message { + /// 拖入了一个文件或目录（由 `app/update.rs` 的窗口事件转发） + /// + /// 只**落成草稿并立刻探测**，不直接开跑：用户要能看到「这个包看起来像 X」再决定。 + Dropped(PathBuf), + /// 拖拽悬停状态变了（`true` = 有文件在窗口上方） + Hover(bool), + /// 路径输入框变了（**只改草稿**，不派指令） + PathChanged(String), + /// 提交导入（用当前草稿路径） + Import, + /// 取消正在跑的导入（阶段边界生效） + Cancel, + /// 关掉结果面板（报告 / 致命错误都走这一条） + Dismiss, + /// 以包为准重新导入（对应 `overwrite = true`；**只在用户显式点过之后**） + Overwrite, + /// 展开/收起某一条冲突的三方明细 + ToggleConflict(String), + /// 换目标实例（`None` = 按包名新建） + SetInstance(Option), + /// 换新实例名（`None` 语义由 `SetInstance` 承担，这里只改名字） + SetInstanceName(String), + /// 换导出格式 + SetFormat(PackFormatView), + /// 换导出包名 + SetExportName(String), + /// 换导出包版本 + SetExportVersion(String), + /// 换落盘路径（留空 = 让 host 给缺省） + SetOutput(String), + /// 跑预检（**不写盘**） + Precheck, + /// 确认写盘（预检已经有结果才可达） + Confirm, + /// 放弃这次导出（关掉预检面板，不写盘） + AbortExport, + /// 打开导出面板 + OpenExport, +} diff --git a/crates/app-iced/src/pages/content/packui/model.rs b/crates/app-iced/src/pages/content/packui/model.rs new file mode 100644 index 0000000..46bfa9d --- /dev/null +++ b/crates/app-iced/src/pages/content/packui/model.rs @@ -0,0 +1,227 @@ +//! 导入/导出区的视图模型：**presenter 快照 + 页面选择 → 要画的东西**。 +//! +//! ## 分层（与内容库页、下载页同一条） +//! +//! | 数据源 | 谁转 | 用途 | +//! |---|---|---| +//! | `AppState::import` / `AppState::export` | [`Pack::of`] | 产品运行时的真页面 | +//! | [`super::demo`] 的固定夹具 | 同上 | `pages_demo` 出图与单测 | +//! +//! 页面自己**不留**业务状态：进度、报告、预检都在 presenter（`ImportState` / `ExportState`）。 +//! [`PackPageState`] 里只有「用户在这一屏上点了什么」——路径草稿、目标实例、格式、包名、 +//! 展开的那条冲突。 +//! +//! ## 文件分工（守 400 行） +//! +//! | 文件 | 职责 | +//! |---|---| +//! | 本文件 | 整块 [`Pack`] + 页内选择 [`PackPageState`] + 探测诊断 [`Probe`] | +//! | [`progress`] | 阶段 / 进度 → 下载页面板的入参（**唯一**的进度形状来源） | +//! | [`report`] | 导入结果：三态 + 容忍域逐条 + 致命块 | +//! | [`export`] | 导出：格式选择 + 预检（不写盘） | +//! +//! ## 容忍 / 致命在模型层就分开 +//! +//! [`report::Report::missing`] 是「搞不到某个文件」（实例可用），[`report::Report::fatal`] +//! 是「已整包回滚」。两者字段类型不同、画的时候颜色与图标也不同，不可能混成一个列表。 + +mod export; +mod progress; +mod report; + +pub use export::{format_label, request_of as request_export, Export, Preview}; +pub use progress::Running; +pub use report::{ConflictRow, Report, Row}; + +use unlucky_i18n::{Catalog, Key}; +use unlucky_presenter::dto::{ExportState, ImportState, InstanceId, PackFormatView, ProbeView}; + +use crate::pages::content::Target; + +/// 页面自留的选择（所有者在 `App::pack`，重建快照不该把它们冲掉）。 +#[derive(Debug, Clone, PartialEq)] +pub struct PackPageState { + /// 路径草稿（拖入或手输；提交后才进请求） + pub draft: String, + /// 有文件悬在窗口上方（拖拽高亮） + pub hover: bool, + /// 目标实例（`None` = 按包名新建） + pub instance: Option, + /// 新实例名 + 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, +} + +impl Default for PackPageState { + fn default() -> Self { + Self { + draft: String::new(), + hover: false, + instance: None, + instance_name: String::new(), + // 导出的首选是 Modrinth：CF 的 `files[]` 只能写能证明 `projectID`/`fileID` 的项， + // 而离线目录证明不了任何一条 ⇒ 全内联 + 一堆「表达不了」的注记。mrpack 才是主路。 + format: PackFormatView::Modrinth, + export_name: String::new(), + export_version: "1.0.0".to_string(), + output: String::new(), + export_open: false, + expanded: None, + } + } +} + +/// 一个实例候选（导入目标与导出源共用）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct PackTarget { + /// 实例 id + pub id: InstanceId, + /// 一行显示名（`Survival · 1.20.1 · Fabric`） + pub label: String, +} + +/// 探测失败时的具名诊断块。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Probe { + /// 最像哪个格式（`None` = 三个都不像） + pub looks_like: Option, + /// 「看起来像 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, + /// 用户取消过这次导入：面板收回但**后台还在跑**（core 没有取消令牌）， + /// 所以要把这句话留在界面上，别让用户以为「没建成」（复审 r1 P1-2）。 + pub cancelled: bool, + /// 取消提示的正文 + pub cancelled_note: &'static str, + /// 导入结果 + pub report: 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)), + export: export::export_of(export, page, candidates, catalog), + } + } + + /// 有没有东西可画（没有就整块收起来，不占版面）。 + pub fn is_idle(&self) -> bool { + self.running.is_none() + && self.probe.is_none() + && self.report.is_none() + && !self.cancelled + && !self.export.open + && self.draft.is_empty() + } +} + +/// 探测诊断：把「缺哪个标记」摊开。 +/// +/// `saw` 为空时补一句「没有可识别的东西」——空列表直接画出来是一行空白，用户会以为是渲染坏了。 +fn probe_of(probe: &ProbeView, catalog: Catalog) -> Probe { + let lead = match probe.looks_like { + Some(format) => catalog.render( + Key::PackProbeLooksLike, + &[ + ("format", export::format_label(format, catalog)), + ("missing", &probe.missing.join(" · ")), + ], + ), + None => catalog.text(Key::PackProbeUnknown).to_owned(), + }; + let saw = if probe.saw.is_empty() { + vec![catalog.text(Key::PackProbeNothing).to_owned()] + } else { + probe.saw.clone() + }; + Probe { + looks_like: probe.looks_like, + lead, + saw, + detail: probe.detail.clone(), + } +} + +#[cfg(test)] +mod tests; diff --git a/crates/app-iced/src/pages/content/packui/model/export.rs b/crates/app-iced/src/pages/content/packui/model/export.rs new file mode 100644 index 0000000..d4e3f37 --- /dev/null +++ b/crates/app-iced/src/pages/content/packui/model/export.rs @@ -0,0 +1,254 @@ +//! 导出：格式选择 + **预检**（不写盘）。 +//! +//! ## 预检与写盘是两次调用，同一套判据 +//! +//! [`Preview`] 只扫描分类、不写盘；确认之后才是真导出。任务书要的 +//! 「将内联 N 个文件 / 无法导出 M 项」正是 [`Preview::head`]。 +//! +//! 三分类的口径（与 core 一致，**没有第四类**）： +//! +//! | 类 | 含义 | 预检里怎么呈现 | +//! |---|---|---| +//! | `Remote` | 能证明可被远程替代 | 一行计数 | +//! | `Inline` | 证明不了 ⇒ 原字节进 `overrides/` | 计数 + 字节 + 前几条样例 | +//! | `Skipped` | 压根没进包 | **逐条列出**（包不完整，不许合并成一句「已导出」） | +//! +//! `Skipped` 非零时 [`Preview::complete`] 为假，界面上会明确写「有文件不会进包」—— +//! 这是 M112 那句「不认识的 mod 不能丢、不能编」的用户侧落点：丢了就要看见丢在哪。 + +use unlucky_i18n::{Catalog, Key}; +use unlucky_presenter::dto::{ + human_bytes, ExportClassView, ExportFileView, ExportPreviewView, ExportReasonView, + ExportRequestView, ExportState, PackFormatView, +}; + +use super::{PackPageState, PackTarget, Row}; + +/// 页内选择 → 导出请求（预检与写盘**共用同一份**）。 +/// +/// `target` 必须从这里进去（复审 r1 P1-1）：之前全仓唯一构造点硬编码 `target: None`， +/// 于是用户敲的「Save to」永远不进请求 —— 输入框是死的。 +#[must_use] +pub fn request_of(page: &PackPageState, instance: &str) -> ExportRequestView { + let name = page.export_name.trim(); + let version = page.export_version.trim(); + let output = page.output.trim(); + ExportRequestView { + instance: instance.to_string(), + format: page.format, + name: if name.is_empty() { + instance.to_string() + } else { + name.to_string() + }, + version: if version.is_empty() { + "1.0.0".to_string() + } else { + version.to_string() + }, + target: (!output.is_empty()).then(|| std::path::PathBuf::from(output)), + } +} + +/// 预检里「内联文件样例」最多列几条（其余用一句「还有 N 个」收口）。 +const INLINE_SAMPLE: usize = 6; + +/// 预检块（**还没写盘**）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Preview { + /// 一句话主结论：`将内联 12 个文件 · 无法导出 0 项` + pub head: String, + /// 远程引用行 + pub remote_line: String, + /// 内联字节行 + pub inline_line: String, + /// 落盘路径行 + pub target_line: String, + /// 包会完整吗（`false` = 有文件压根没进包） + pub complete: bool, + /// 完整性那句话 + pub complete_line: String, + /// 无法导出的项（逐条） + pub skipped: Vec, + /// 内联文件样例 + 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/progress.rs b/crates/app-iced/src/pages/content/packui/model/progress.rs new file mode 100644 index 0000000..646056f --- /dev/null +++ b/crates/app-iced/src/pages/content/packui/model/progress.rs @@ -0,0 +1,121 @@ +//! 阶段与进度：**把导入进度映射成下载页那块面板的入参**（不另画一套进度 UI）。 +//! +//! ## 任务书第 5 条怎么落 +//! +//! 「沿用既有安装面板组件与状态机，禁止再写第二套进度 UI」—— +//! +//! 1. 导入的 `ImportStageView` / 计数先映射成面板的入参形状（[`panel_progress`] → +//! `InstallProgressView` → [`InstallView`]）； +//! 2. 画法交给 `pages::download::install_panel`（同一个函数、同一套几何，进度条 / 计数 / +//! 取消按钮都归它）； +//! 3. 任务书要的「解包 / overrides / 补文件」三档由**一行步骤说明**（[`stage_line`]）承载。 +//! +//! **已知重叠（如实写，别再说成修好了）**：面板自带的阶段词是**安装**语义 +//! （`Resolving version` / `Downloading files` / `Building the version` / `Registering instance`）， +//! 而 `install_panel_model` 永远会填它（M109 合流 M105 后 `InstallView` 不再对外导出， +//! 没法从外面塞一个自定义标签或清空）。所以屏幕上同时出现「Step 2/5 · Unpacking overrides」 +//! 与「Building the version」：**粗/细两层，不是两句矛盾的话**，但 `Extract`/`Commit` 都映射到 +//! `Installing`，那一档的用词偏「安装」。 +//! +//! 要彻底解决得让面板接受调用方给的阶段词（已报 finding：把安装面板提成共享组件）。 + +use unlucky_i18n::{Catalog, Key}; +use unlucky_presenter::dto::{ + ImportProgressView, ImportStageView, InstallProgressView, InstallStage, +}; + +use crate::pages::download::Download; + +/// 抛进面板的进度行。 +#[derive(Debug, Clone, PartialEq)] +pub struct Running { + /// 包名（面板标题那一行） + pub pack: String, + /// 细档位说明（`步骤 2/5 · 解包覆盖内容`） + pub stage_line: String, + /// 交给下载页那块面板的进度（**唯一**的进度形状来源；`None` = 面板无话可说） + pub panel: Option, +} + +/// 细档位说明（`步骤 2/5 · 解包覆盖内容`）。 +#[must_use] +pub fn stage_line(stage: ImportStageView, catalog: Catalog) -> String { + let total = ImportStageView::ALL.len(); + let index = ImportStageView::ALL + .iter() + .position(|item| *item == stage) + .map_or(1, |at| at + 1); + catalog.render( + Key::PackStageLine, + &[ + ("index", &index.to_string()), + ("total", &total.to_string()), + ("stage", catalog.text(stage_key(stage))), + ], + ) +} + +/// 阶段 → 文案 key。 +#[must_use] +pub const fn stage_key(stage: ImportStageView) -> Key { + match stage { + ImportStageView::Probe => Key::PackStageProbe, + ImportStageView::Extract => Key::PackStageExtract, + ImportStageView::Fetch => Key::PackStageFetch, + ImportStageView::Commit => Key::PackStageCommit, + ImportStageView::Register => Key::PackStageRegister, + } +} + +/// 导入阶段 → 安装面板的粗阶段（**唯一映射处**）。 +/// +/// `Extract` / `Commit` 都落到 `Installing`：对那块面板而言它们都是「在写盘」，区别由 +/// [`stage_line`] 说给用户。 +#[must_use] +pub const fn panel_stage(stage: ImportStageView) -> InstallStage { + match stage { + ImportStageView::Probe => InstallStage::Planning, + ImportStageView::Extract | ImportStageView::Commit => InstallStage::Installing, + ImportStageView::Fetch => InstallStage::Downloading, + ImportStageView::Register => InstallStage::Registering, + } +} + +/// 导入进度 → 下载页面板的入参。 +/// +/// `version` / `instance` 都填包名：面板第一行显示的就是「这次在装什么」， +/// 而导入的对象是包，不是某个版本 id。 +#[must_use] +pub fn panel_progress(progress: &ImportProgressView) -> InstallProgressView { + InstallProgressView { + version: progress.pack.clone(), + instance: progress.pack.clone(), + loader: String::new(), + stage: panel_stage(progress.stage), + files_done: u64::from(progress.done), + files_total: u64::from(progress.total), + bytes_done: 0, + bytes_total: 0, + speed_bps: 0, + eta_secs: 0, + message: progress.current.clone().unwrap_or_default(), + } +} + +/// 进度事件 → 面板要的视图模型。 +/// +/// 面板入参走 `pages::download::install_panel_model`（M109 合流 M105 后提供的**唯一**入口）： +/// 它把 `InstallProgressView` 转成面板要的 `Download`，终态（完成/取消）返回 `None`。 +/// 导入的五个阶段都不是终态，所以正常路径下一定是 `Some`；`None` 只做防御（面板没了就只留步骤行）。 +/// +/// 面板自带那个粗阶段词是**安装**语义（`Resolving version` / `Downloading files` / +/// `Building the version` / `Registering instance`），所以细档位由 [`stage_line`] 说， +/// 二者是「粗/细」关系而不是两套说法——[`panel_stage`] 只挑语义最近的那一档。 +pub(super) fn running_of(progress: &ImportProgressView, catalog: Catalog) -> Running { + let panel = panel_progress(progress); + Running { + pack: progress.pack.clone(), + stage_line: stage_line(progress.stage, catalog), + panel: crate::pages::download::install_panel_model(&panel, catalog), + } +} diff --git a/crates/app-iced/src/pages/content/packui/model/report.rs b/crates/app-iced/src/pages/content/packui/model/report.rs new file mode 100644 index 0000000..c056317 --- /dev/null +++ b/crates/app-iced/src/pages/content/packui/model/report.rs @@ -0,0 +1,255 @@ +//! 导入结果的视图模型：**三态 + 容忍域逐条 + 致命块**。 +//! +//! ## 为什么容忍域与致命域连字段类型都不同 +//! +//! 任务书：「失败原因逐条展示（能容忍的缺文件与致命错误必须视觉可区分）」。 +//! 只在颜色上区分不够——颜色一关掉（截图/高对比/色弱）就没了。所以： +//! +//! | 域 | 类型 | 画法 | +//! |---|---|---| +//! | 容忍（缺文件 / 被拒 component / 注记） | [`Row`]（路径 + 原因） | 中性容器 + `Info` 图标 + 逐条列表 | +//! | 致命（已回滚） | [`Fatal`]（大类 + 原文 + 建议 + 稳定码） | `ErrorContainer` + `Error` 图标 + 标题换措辞 | +//! +//! 一个 `Option` 与一个 `Vec` 之间没有「误合并」的写法，这比任何样式约定都硬。 + +use unlucky_i18n::{Catalog, Key}; +use unlucky_presenter::dto::{ + ConflictChoiceView, ConflictFileView, ConflictReasonView, ImportErrorView, ImportReportView, + ImportStatusView, MissingFileView, MissingReasonView, +}; + +use super::PackPageState; + +/// 报告里的一行（容忍域：缺文件 / 被拒 component）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Row { + /// 左列（路径 / 组件名） + pub path: String, + /// 右列（原因的人读文案） + pub note: String, +} + +/// 一条冲突（三方哈希 + 本次处置）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ConflictRow { + /// 实例内路径 + pub path: String, + /// 成因（`你改过` / `你删过` / `本来就在`） + pub reason: String, + /// 本次实际处置（`保留我的` / `用包里的`） + pub choice: String, + /// 包内 SHA-1（截短） + pub pack_sha1: String, + /// 基线 SHA-1（`None` = 没有基线） + pub base_sha1: Option, + /// 磁盘 SHA-1（`None` = 文件不在） + pub disk_sha1: Option, + /// 展开中（展开才画三方哈希那行） + pub expanded: bool, +} + +/// 致命失败块（**已整包回滚**）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Fatal { + /// 「已回滚 —— 目标目录零残留」 + pub title: String, + /// 大类名（`路径穿越` / `清单损坏` …） + pub label: String, + /// 具体是什么 + pub message: String, + /// 稳定码 + pub code: String, + /// 补救建议 + pub hint: Option, +} + +/// 导入结果块。 +#[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, +} + +impl Report { + /// 实例可用吗（`Success` / `Partial` 都是装上了）。 + pub const fn installed(&self) -> bool { + self.status.installed() + } +} + +/// 一次导入结果 → 视图模型。 +pub(super) fn report_of( + report: &ImportReportView, + page: &PackPageState, + catalog: Catalog, +) -> Report { + let missing_title = (!report.missing.is_empty()).then(|| { + catalog.render( + Key::PackReportMissing, + &[("count", &report.missing.len().to_string())], + ) + }); + let conflicts_title = (!report.conflicts.is_empty()).then(|| { + catalog.render( + Key::PackReportConflicts, + &[("count", &report.conflicts.len().to_string())], + ) + }); + + Report { + status: report.status, + title: status_title(report.status, catalog).to_owned(), + subtitle: subtitle(report, catalog), + written_line: catalog.render( + Key::PackReportWritten, + &[ + ("count", &report.written().to_string()), + ("bytes", &human(report)), + ], + ), + fatal: report.error.as_ref().map(|error| fatal_of(error, catalog)), + missing_title, + missing: report + .missing + .iter() + .map(|file| missing_row(file, catalog)) + .collect(), + conflicts_title, + conflicts: report + .conflicts + .iter() + .map(|file| conflict_row(file, page.expanded.as_deref(), catalog)) + .collect(), + rejected_title: (!report.rejected.is_empty()).then(|| { + catalog.render( + Key::PackReportRejected, + &[("count", &report.rejected.len().to_string())], + ) + }), + rejected: report + .rejected + .iter() + .map(|component| Row { + path: component.clone(), + note: catalog.text(Key::PackReportRejectedNote).to_owned(), + }) + .collect(), + warnings: report.warnings.clone(), + // 「以包为准重新导入」只在**导入到已有实例**时有意义（复审 r1 P2-2）：新建实例那条路上 + // 目标目录已经建好，再点一次必然撞「directory already exists」——一个必然失败的按钮 + // 等于死按钮，所以那种流程下不显示。 + can_overwrite: !report.conflicts.is_empty() + && report.status == ImportStatusView::Partial + && page.instance.is_some(), + overwrite_note: (!report.conflicts.is_empty()) + .then(|| catalog.text(Key::PackOverwriteNote).to_owned()), + } +} + +/// 字节数的人读串。 +fn human(report: &ImportReportView) -> String { + unlucky_presenter::dto::human_bytes(report.bytes_written) +} + +fn status_title(status: ImportStatusView, catalog: Catalog) -> &'static str { + match status { + ImportStatusView::Success => catalog.text(Key::PackStatusSuccess), + ImportStatusView::Partial => catalog.text(Key::PackStatusPartial), + ImportStatusView::Failed => catalog.text(Key::PackStatusFailed), + } +} + +/// 副标题：包名 · 格式 · 游戏版本 · 加载器（缺哪个就不写哪个，不拼「未知」）。 +fn subtitle(report: &ImportReportView, catalog: Catalog) -> String { + let mut parts: Vec = Vec::new(); + if let Some(format) = report.format { + parts.push(super::format_label(format, catalog).to_owned()); + } + if let Some(version) = &report.game_version { + parts.push(version.clone()); + } + if let Some(loader) = &report.loader { + parts.push(loader.clone()); + } + if let Some(name) = &report.pack_name { + parts.insert(0, name.clone()); + } + parts.join(" · ") +} + +fn fatal_of(error: &ImportErrorView, catalog: Catalog) -> Fatal { + Fatal { + title: catalog.text(Key::PackFatalTitle).to_owned(), + label: error.label.clone(), + message: error.message.clone(), + code: error.code.clone(), + hint: error.hint.clone(), + } +} + +fn missing_row(file: &MissingFileView, catalog: Catalog) -> Row { + Row { + path: file.path.clone().unwrap_or_else(|| file.display.clone()), + note: match file.reason { + MissingReasonView::Offline => catalog.text(Key::PackMissingOffline).to_owned(), + MissingReasonView::NoSource => catalog.text(Key::PackMissingNoSource).to_owned(), + MissingReasonView::FetchFailed => catalog.render( + Key::PackMissingFetchFailed, + &[("detail", file.detail.as_str())], + ), + }, + } +} + +fn conflict_row(file: &ConflictFileView, expanded: Option<&str>, catalog: Catalog) -> ConflictRow { + ConflictRow { + path: file.path.clone(), + reason: match file.reason { + ConflictReasonView::UserModified => catalog.text(Key::PackConflictUserModified), + ConflictReasonView::UserDeleted => catalog.text(Key::PackConflictUserDeleted), + ConflictReasonView::PreExisting => catalog.text(Key::PackConflictPreExisting), + } + .to_owned(), + choice: match file.choice { + ConflictChoiceView::KeepUser => catalog.text(Key::PackChoiceKeepUser), + ConflictChoiceView::Overwrite => catalog.text(Key::PackChoiceOverwrite), + } + .to_owned(), + pack_sha1: short_sha(&file.pack_sha1), + base_sha1: file.base_sha1.as_deref().map(short_sha), + disk_sha1: file.disk_sha1.as_deref().map(short_sha), + expanded: expanded == Some(file.path.as_str()), + } +} + +/// SHA-1 截短（前 8 位够人眼区分；全 40 位会把一行撑爆）。 +#[must_use] +pub fn short_sha(sha: &str) -> String { + sha.chars().take(8).collect() +} diff --git a/crates/app-iced/src/pages/content/packui/model/tests.rs b/crates/app-iced/src/pages/content/packui/model/tests.rs new file mode 100644 index 0000000..991fcbd --- /dev/null +++ b/crates/app-iced/src/pages/content/packui/model/tests.rs @@ -0,0 +1,394 @@ +//! 导入/导出区视图模型的守门（M113）：阶段映射、预检计数、三方哈希、容忍/致命分野。 +//! +//! 这里**不测画法**（画法靠出图），测的是「决策」：哪些数字进了哪一行、哪些字段被截短、 +//! 哪一态该出现哪一块。所有断言都能在没有图形环境的情况下跑。 + +use std::path::PathBuf; + +use unlucky_i18n::Lang; +use unlucky_presenter::dto::{ + ConflictChoiceView, ConflictFileView, ConflictReasonView, ExportClassView, ExportFileView, + ExportPreviewView, ImportErrorView, ImportProgressView, ImportReportView, ImportStageView, + ImportStatusView, InstallStage, MissingFileView, MissingReasonView, PackFormatView, +}; + +use super::progress::{panel_progress, panel_stage, stage_line}; +use super::report::report_of; +use super::report::short_sha; +use super::{Pack, PackPageState}; + +fn catalog() -> unlucky_i18n::Catalog { + Lang::En.catalog() +} + +#[test] +fn stage_line_counts_the_five_steps_in_order() { + let expected = [ + (ImportStageView::Probe, "1/5"), + (ImportStageView::Extract, "2/5"), + (ImportStageView::Fetch, "3/5"), + (ImportStageView::Commit, "4/5"), + (ImportStageView::Register, "5/5"), + ]; + for (stage, position) in expected { + let line = stage_line(stage, catalog()); + assert!(line.contains(position), "{stage:?} 的步号不对：{line}"); + } + // 阶段名要真的是「那一档」，不能五个阶段都显示同一句 + let lines: Vec = 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, + }; + let block = report_of(&report, &PackPageState::default(), catalog()); + assert!(block.fatal.is_some(), "致命块必须单独存在"); + assert_eq!(block.missing.len(), 1, "容忍域仍要逐条列出"); + assert!(!block.installed(), "Failed 不是「装上了」"); + assert!(!block.can_overwrite, "没有冲突时不给翻档动作"); +} + +#[test] +fn conflicts_default_to_keeping_the_user_copy() { + let report = ImportReportView { + status: ImportStatusView::Partial, + format: Some(PackFormatView::Modrinth), + pack_name: Some("Pack".to_string()), + pack_version: None, + game_version: None, + loader: None, + version_id: None, + target: PathBuf::from("C:/tmp"), + files: Vec::new(), + conflicts: vec![ConflictFileView { + path: "config/x.json".to_string(), + reason: ConflictReasonView::UserModified, + choice: ConflictChoiceView::KeepUser, + pack_sha1: "fixture".to_string(), + base_sha1: None, + disk_sha1: Some("disk".to_string()), + pack_size: 12, + }], + missing: Vec::new(), + rejected: Vec::new(), + warnings: Vec::new(), + error: None, + registered: None, + bytes_written: 0, + rolled_back: true, + }; + // 「以包为准」只在导入到**已有实例**时给（复审 r1 P2-2），所以这里选一个实例 + let page = PackPageState { + instance: Some("survival".to_string()), + ..PackPageState::default() + }; + let block = report_of(&report, &page, catalog()); + assert_eq!(block.conflicts.len(), 1); + assert!(!block.conflicts[0].expanded, "默认收起"); + assert_eq!( + block.conflicts[0].choice, + catalog().text(unlucky_i18n::Key::PackChoiceKeepUser), + "默认档必须是「保留我的」" + ); + assert!(block.can_overwrite, "有冲突要能整体翻档"); + assert!(block.overwrite_note.is_some(), "不支持「两者都留」要如实写"); + + // 展开的那一条才画三方哈希 + let expanded = PackPageState { + expanded: Some("config/x.json".to_string()), + ..page.clone() + }; + let block = report_of(&report, &expanded, catalog()); + assert!(block.conflicts[0].expanded); +} + +#[test] +fn an_idle_pack_has_nothing_to_draw_but_the_entry() { + let import = unlucky_presenter::dto::ImportState::default(); + let export = unlucky_presenter::dto::ExportState::default(); + let model = Pack::of(&import, &export, &PackPageState::default(), &[], catalog()); + assert!(model.is_idle()); + assert!(model.running.is_none()); + assert!(model.report.is_none()); + // 入口说明永远在（用户得知道可以拖什么、为什么没有「选择文件」按钮） + assert!(!model.drop_hint.is_empty()); + assert!(!model.no_dialog_note.is_empty()); +} + +#[test] +fn the_save_to_field_really_reaches_the_request() { + // 复审 r1 P1-1：这个字段以前是死的（构造点硬编码 target: None） + let page = PackPageState { + output: " D:/packs/my.mrpack ".to_string(), + ..PackPageState::default() + }; + let request = super::export::request_of(&page, "survival"); + assert_eq!( + request.target.as_deref(), + Some(std::path::Path::new("D:/packs/my.mrpack")), + "用户敲的路径必须真的进请求（去首尾空白）" + ); + + // 留空 ⇒ None（由 host 给缺省路径），不是空串路径 + let blank = PackPageState { + output: " ".to_string(), + ..PackPageState::default() + }; + assert!(super::export::request_of(&blank, "survival") + .target + .is_none()); + + // 包名/版本留空时的缺省值也钉一下（预检与写盘共用同一份请求，不能各算一套） + let request = super::export::request_of(&blank, "survival"); + assert_eq!(request.name, "survival"); + assert_eq!(request.version, "1.0.0"); +} + +#[test] +fn overwrite_is_offered_only_when_importing_into_an_existing_instance() { + // 复审 r1 P2-2：新建实例那条路上再点「以包为准」必然撞「directory already exists」 + let report = unlucky_presenter::dto::ImportReportView { + status: ImportStatusView::Partial, + format: Some(PackFormatView::Modrinth), + pack_name: Some("Pack".to_string()), + pack_version: None, + game_version: None, + loader: None, + version_id: None, + target: std::path::PathBuf::from("C:/tmp"), + files: Vec::new(), + conflicts: vec![ConflictFileView { + path: "config/x.json".to_string(), + reason: ConflictReasonView::UserModified, + choice: ConflictChoiceView::KeepUser, + pack_sha1: "abc".to_string(), + base_sha1: None, + disk_sha1: None, + pack_size: 1, + }], + missing: Vec::new(), + rejected: Vec::new(), + warnings: Vec::new(), + error: None, + registered: None, + bytes_written: 0, + rolled_back: true, + }; + + let new_instance = PackPageState::default(); + assert!( + !super::report::report_of(&report, &new_instance, catalog()).can_overwrite, + "新建实例流程下不该出现「以包为准」（那按钮必然失败）" + ); + + let existing = PackPageState { + instance: Some("survival".to_string()), + ..PackPageState::default() + }; + assert!( + super::report::report_of(&report, &existing, catalog()).can_overwrite, + "导入到已有实例时才给翻档动作" + ); +} + +#[test] +fn cancelled_state_is_visible_and_says_the_import_keeps_running() { + // 复审 r1 P1-2：面板收回之后，界面上必须留一句「后台还在跑」 + let import = unlucky_presenter::dto::ImportState { + cancelled: true, + ..unlucky_presenter::dto::ImportState::default() + }; + let export = unlucky_presenter::dto::ExportState::default(); + let model = Pack::of(&import, &export, &PackPageState::default(), &[], catalog()); + assert!(model.cancelled); + assert!( + model.cancelled_note.to_lowercase().contains("background"), + "取消提示必须说清后台还在跑：{}", + model.cancelled_note + ); + assert!(!model.is_idle(), "取消态不能被当成「什么都没有」"); +} diff --git a/crates/app-iced/src/pages/content/packui/tests.rs b/crates/app-iced/src/pages/content/packui/tests.rs new file mode 100644 index 0000000..f0d0d5a --- /dev/null +++ b/crates/app-iced/src/pages/content/packui/tests.rs @@ -0,0 +1,107 @@ +//! 导入/导出区的守门（M113）：四种出图态都装得满、入口文案都在。 +//! +//! 出图（D30）靠这几条夹具：任何一态装不满，截图就会是一块空容器，而不是「有话说」的界面。 +//! 视图模型的判定在 `model/tests.rs`，这里只管**夹具本身**。 + +use unlucky_i18n::Lang; + +use super::demo::pack_in; +use super::model::Pack; + +/// D30 要求的四态（导入中 / 部分成功 / 冲突选择 / 导出预检）。 +const STATES: [&str; 4] = ["importing", "partial", "conflict", "export"]; + +#[test] +fn every_screenshot_state_fills_something() { + for state in STATES { + let (model, _page) = pack_in(state, Lang::En); + assert!( + !model.is_idle(), + "{state} 这一态什么都没画（截图会是一块空容器）" + ); + assert_eq!(model.targets.len(), 2, "{state} 的实例候选不足"); + assert!(!model.drop_hint.is_empty()); + assert!( + !model.no_dialog_note.is_empty(), + "没有系统文件框这件事必须写在界面上" + ); + } +} + +#[test] +fn importing_shows_the_shared_install_panel() { + let (model, _page) = pack_in("importing", Lang::En); + let running = model.running.expect("导入中要有进度"); + // 进度形状来自下载页那块面板（`Download.install`），不是本区另造的 + assert!( + running + .panel + .as_ref() + .is_some_and(|panel| panel.install.is_some()), + "进度必须走下载页的安装面板视图模型" + ); + assert!( + running.stage_line.contains("2/5"), + "解包阶段是第 2/5 步：{}", + running.stage_line + ); + assert!(model.report.is_none(), "导入中不该同时有结果"); +} + +#[test] +fn partial_keeps_the_tolerable_rows_one_by_one() { + let (model, _page) = pack_in("partial", Lang::En); + let report = model.report.expect("部分成功要有报告"); + assert!(report.installed(), "Partial 仍是「装上了」"); + assert!(report.fatal.is_none(), "部分成功不是致命失败"); + assert_eq!(report.missing.len(), 3, "缺文件要逐条列出"); + assert!(report.missing_title.is_some()); + assert!(!report.rejected.is_empty(), "被拒 component 也要逐条"); +} + +#[test] +fn conflict_state_defaults_to_keeping_the_user_copy_and_expands_one_row() { + let (model, page) = pack_in("conflict", Lang::En); + let report = model.report.expect("冲突态要有报告"); + assert_eq!(report.conflicts.len(), 3); + assert!( + report.conflicts.iter().all(|row| !row.expanded) + || report.conflicts.iter().filter(|row| row.expanded).count() == 1, + "只展开用户点过的那一条" + ); + assert_eq!( + report.conflicts.iter().filter(|row| row.expanded).count(), + 1, + "夹具要展开一条，截图才看得见三方哈希" + ); + assert!(page.expanded.is_some()); + assert!(report.can_overwrite); + assert!(report.overwrite_note.is_some()); +} + +#[test] +fn export_state_has_a_preview_but_has_not_written_anything() { + let (model, _page) = pack_in("export", Lang::En); + assert!(model.export.open); + let preview = model.export.preview.expect("预检要有结果"); + assert!( + preview.head.contains('2'), + "内联数要进主结论：{}", + preview.head + ); + assert!(!preview.skipped.is_empty(), "无法导出的项要逐条"); + assert!(!preview.complete, "有跳过项 ⇒ 包不完整"); + assert!(!preview.notes.is_empty(), "已知损失要列出来"); + assert!( + model.export.done.is_none(), + "预检阶段不许出现「已写出」（那是写盘之后的事）" + ); +} + +#[test] +fn default_state_offers_the_entry_with_nothing_else() { + let (model, page): (Pack, _) = pack_in("", Lang::En); + assert!(model.is_idle()); + assert!(!model.export.open); + assert!(page.draft.is_empty()); +} diff --git a/crates/app-iced/src/pages/content/packui/view.rs b/crates/app-iced/src/pages/content/packui/view.rs new file mode 100644 index 0000000..7e41d0a --- /dev/null +++ b/crates/app-iced/src/pages/content/packui/view.rs @@ -0,0 +1,257 @@ +//! 导入/导出区的画法：入口（拖拽 + 路径）→ 进度（**下载页那块面板**）→ 结果 → 导出预检。 +//! +//! ## 版面 +//! +//! ```text +//! ┌ 导入整合包 ──────────────────────────────────┐ +//! │ ┌ 拖拽区（hover 时变主色描边） ─────────────┐ │ +//! │ └ 路径输入框 ──────────┘ [导入] │ │ +//! │ [装到实例：chips] [实例名] │ │ +//! ├ 进度：步骤 2/5 · 解包覆盖内容 │ +//! │ <下载页的安装面板：进度条 + 计数 + 取消> │ +//! ├ 探测失败：看起来像 X，但缺 Y │ +//! ├ 结果：三态标题 + 缺文件逐条 + 冲突逐条 + 致命块 │ +//! └ 导出：格式 chips + 预检（将内联 N / 无法导出 M）│ +//! ``` +//! +//! ## 三处「视觉可区分」不是靠颜色一种通道 +//! +//! | 域 | 图标 | 颜色角色 | 容器 | 措辞 | +//! |---|---|---|---|---| +//! | 容忍（缺文件 / 被拒 component） | `Warn` | `Tertiary` | 无底色 | 「可容忍」 | +//! | 致命（已回滚） | `Error` | `Error` | `ErrorContainer` | 「已回滚 —— 零残留」 | +//! | 成功 | `Check` | `Primary` | 无底色 | 「已导入」 | +//! +//! 关掉颜色也还认得出（图标 + 措辞），这是任务书「必须视觉可区分」的落点。 +//! +//! ## 进度只有一份 +//! +//! 进行中的进度**整块交给** `pages::download::install_panel`（同一个函数、同一套几何与文案）； +//! 本区只额外画一行 [`Running::stage_line`] 补足「解包 / overrides / 补文件」三档的粒度。 +//! +//! ## 文件分工（守 400 行） +//! +//! | 文件 | 职责 | +//! |---|---| +//! | 本文件 | 区入口 + 拖拽区 + 路径输入 + 目标实例 | +//! | [`parts`] | 三个共用小件（底色容器 / 容忍标题 / 逐条列表） | +//! | [`progress`] | 进度块（复用面板）与探测失败块 | +//! | [`report`] | 结果块：三态 + 冲突 + 致命 | +//! | [`export`] | 导出块与预检块 | + +mod export; +mod parts; +mod progress; +mod report; + +use iced::widget::{column, container, row}; +use iced::{Alignment, Background, Border, Element, Length}; + +use unlucky_design::color::Role; +use unlucky_design::icons::IconKind; +use unlucky_design::shape::ShapeScale; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; + +use unlucky_i18n::{Catalog, Key}; + +use crate::app::components::buttons::{self, Button}; +use crate::app::components::divider; +use crate::app::components::inputs::{text_field, Field}; +use crate::app::components::selection::{chip, Chip}; +use crate::pages::frame; +use crate::pages::Message as PageMessage; +use crate::theme::Ui; + +use self::export::export_block; +use self::progress::{probe_block, running_block}; +use self::report::report_block; +use super::model::Pack; +use super::PackMessage; + +/// 内容库意图 → 页面消息（唯一的一层包装）。 +pub(super) fn intent(message: PackMessage) -> PageMessage { + PageMessage::Content(super::super::Message::Pack(message)) +} + +/// 整块（导入入口 + 进度 + 结果 + 导出）。 +pub(crate) fn section<'a>( + ui: &'a Ui, + catalog: Catalog, + model: &'a Pack, +) -> Element<'a, PageMessage> { + let mut block = column![].spacing(ui.space(Space::X3)).width(Length::Fill); + + // **一次只摊开一件事**：入口（拖什么/装到哪）、进度、结果、导出预检各占一态。 + // 全都堆在一起时，内容库页正列没有整页滚动 ⇒ 动作按钮被顶出屏幕（出图实测：冲突态与 + // 导出预检态的「确认写盘 / 关闭」都落在 900px 以下）。收起的入口不会丢功能：拖拽是窗口级 + // 事件，任何时候把文件拖进来都算数。 + if model.export.open { + block = block.push(export_block(ui, catalog, &model.export)); + } else if let Some(running) = &model.running { + block = block.push(running_block(ui, catalog, running)); + } else if let Some(report) = &model.report { + block = block.push(report_block(ui, catalog, report)); + } else if model.cancelled { + // 取消过、还没有新结果：把「后台还在跑」这句话留在屏上（复审 r1 P1-2） + block = block.push( + column![ + frame::text_role( + ui, + TypeRole::BodySmall, + false, + model.cancelled_note, + ui.color(Role::Tertiary), + ), + buttons::text( + ui, + Button::new(catalog.text(Key::PackDismiss), intent(PackMessage::Dismiss)), + ), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill), + ); + } else { + block = block.push(entry(ui, catalog, model)); + if let Some(probe) = &model.probe { + // 探测失败要和路径输入框在一起：用户下一步就是改路径 + block = block.push(probe_block(ui, catalog, probe)); + } + block = block.push(divider::full(ui)); + block = block.push(export_block(ui, catalog, &model.export)); + } + + container(block).width(Length::Fill).into() +} + +/// 入口：拖拽区 + 路径输入 + 目标实例。 +fn entry<'a>(ui: &'a Ui, catalog: Catalog, model: &'a Pack) -> Element<'a, PageMessage> { + let zone = container( + column![ + frame::text_role( + ui, + TypeRole::BodyMedium, + false, + if model.hover { + catalog.text(Key::PackDropActive) + } else { + model.drop_hint + }, + ui.color(if model.hover { + Role::Primary + } else { + Role::OnSurface + }), + ), + // 没有系统文件框这件事**写在界面上**：不能让用户点了半天「选择文件」找不到按钮 + frame::text_role( + ui, + TypeRole::BodySmall, + false, + model.no_dialog_note, + ui.color(Role::OnSurfaceVariant), + ), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill), + ) + .width(Length::Fill) + .padding(ui.space(Space::X4)) + .style(move |_theme| container::Style { + border: Border { + color: ui.color(if model.hover { + Role::Primary + } else { + Role::Outline + }), + width: 1.0, + radius: ui.radius_dp(ShapeScale::Large), + }, + background: model + .hover + .then(|| Background::Color(ui.color(Role::PrimaryContainer))), + ..container::Style::default() + }); + + let field = text_field( + ui, + Field::new(model.draft.as_str()) + .label(catalog.text(Key::PackPathLabel)) + .placeholder(catalog.text(Key::PackPathPlaceholder)) + .leading(IconKind::Folder), + move |text| intent(PackMessage::PathChanged(text)), + ); + let submit = buttons::filled( + ui, + Button::new( + catalog.text(Key::PackImportAction), + intent(PackMessage::Import), + ) + .leading(IconKind::Folder), + ); + + let mut block = column![ + frame::text_role( + ui, + TypeRole::TitleSmall, + true, + catalog.text(Key::PackImportTitle), + ui.color(Role::OnSurface), + ), + zone, + row![field, submit] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::End) + .width(Length::Fill), + targets(ui, catalog, model), + ] + .spacing(ui.space(Space::X2)) + .width(Length::Fill); + + if model.instance.is_none() { + block = block.push(text_field( + ui, + Field::new(model.instance_name.as_str()).label(catalog.text(Key::PackInstanceName)), + move |text| intent(PackMessage::SetInstanceName(text)), + )); + } + + block.into() +} + +/// 目标实例那一行（chips + 「新建实例」）。 +fn targets<'a>(ui: &'a Ui, catalog: Catalog, model: &'a Pack) -> Element<'a, PageMessage> { + let mut chips: Vec> = 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/progress.rs b/crates/app-iced/src/pages/content/packui/view/progress.rs new file mode 100644 index 0000000..2afb9cf --- /dev/null +++ b/crates/app-iced/src/pages/content/packui/view/progress.rs @@ -0,0 +1,97 @@ +//! 进度块（**整块复用下载页的安装面板**）与探测失败块。 + +use iced::widget::{column, row}; +use iced::{Alignment, Element, Length}; + +use unlucky_design::color::Role; +use unlucky_design::icons::IconKind; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; + +use unlucky_i18n::{Catalog, Key}; + +use crate::app::components::buttons::{self, Button}; +use crate::pages::download; +use crate::pages::frame; +use crate::pages::Message as PageMessage; +use crate::theme::Ui; + +use super::super::model::{Probe, Running}; +use super::super::PackMessage; +use super::intent; +use super::parts::marker_box; + +/// 进行中：一行步骤说明 + **下载页那块面板**。 +pub(super) fn running_block<'a>( + ui: &'a Ui, + catalog: Catalog, + running: &'a Running, +) -> Element<'a, PageMessage> { + let mut block = column![frame::text_role( + ui, + TypeRole::LabelMedium, + false, + running.stage_line.as_str(), + ui.color(Role::OnSurfaceVariant), + )] + .spacing(ui.space(Space::X1)) + .width(Length::Fill); + + // 同一块面板：进度条、计数行、取消按钮都归它，这里不另画一条。 + // `None` 只会在「阶段已收尾」时出现（导入的五个阶段都不是终态），那时只剩步骤行。 + if let Some(panel) = &running.panel { + block = block.push(download::install_panel(ui, catalog, panel)); + } + block.into() +} + +/// 探测失败：把「缺哪个标记」摊开。 +pub(super) fn probe_block<'a>( + ui: &'a Ui, + catalog: Catalog, + probe: &'a Probe, +) -> Element<'a, PageMessage> { + let mut block = column![ + row![ + frame::glyph(IconKind::Warn, ui.color(Role::Tertiary), frame::ICON_PX), + frame::text_role( + ui, + TypeRole::TitleSmall, + true, + catalog.text(Key::PackProbeTitle), + ui.color(Role::Tertiary), + ), + ] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Center), + frame::text_role( + ui, + TypeRole::BodyMedium, + false, + probe.lead.as_str(), + ui.color(Role::OnSurface), + ), + frame::text_role_owned( + ui, + TypeRole::BodySmall, + false, + catalog.render(Key::PackProbeSaw, &[("saw", &probe.saw.join(" · "))]), + ui.color(Role::OnSurfaceVariant), + ), + frame::text_role( + ui, + TypeRole::BodySmall, + false, + probe.detail.as_str(), + ui.color(Role::OnSurfaceVariant), + ), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill); + + block = block.push(buttons::text( + ui, + Button::new(catalog.text(Key::PackDismiss), intent(PackMessage::Dismiss)), + )); + marker_box(ui, Role::TertiaryContainer, block) +} diff --git a/crates/app-iced/src/pages/content/packui/view/report.rs b/crates/app-iced/src/pages/content/packui/view/report.rs new file mode 100644 index 0000000..8cc8f1d --- /dev/null +++ b/crates/app-iced/src/pages/content/packui/view/report.rs @@ -0,0 +1,296 @@ +//! 结果块：三态标题 + 容忍域逐条 + 冲突逐条 + 致命块。 + +use iced::widget::{column, row}; +use iced::{Alignment, Element, Length}; + +use unlucky_design::color::Role; +use unlucky_design::icons::IconKind; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; + +use unlucky_i18n::{Catalog, Key}; + +use crate::app::components::buttons::{self, Button}; +use crate::pages::frame; +use crate::pages::Message as PageMessage; +use crate::theme::Ui; + +use super::super::model::{ConflictRow, Report}; +use super::super::PackMessage; +use super::intent; +use super::parts::{bounded, marker_box, rows_block, tolerable_title}; + +/// 结果块。 +pub(super) fn report_block<'a>( + ui: &'a Ui, + catalog: Catalog, + report: &'a Report, +) -> Element<'a, PageMessage> { + let mut block = column![ + row![ + frame::glyph( + status_icon(report), + ui.color(status_role(report)), + frame::ICON_PX + ), + frame::text_role( + ui, + TypeRole::TitleSmall, + true, + report.title.as_str(), + ui.color(status_role(report)), + ), + ] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Center), + frame::text_role( + ui, + TypeRole::BodySmall, + false, + report.subtitle.as_str(), + ui.color(Role::OnSurfaceVariant), + ), + frame::text_role( + ui, + TypeRole::BodySmall, + false, + report.written_line.as_str(), + ui.color(Role::OnSurfaceVariant), + ), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill); + + if let Some(fatal) = &report.fatal { + block = block.push(marker_box( + ui, + Role::ErrorContainer, + column![ + frame::text_role( + ui, + TypeRole::LabelLarge, + true, + fatal.title.as_str(), + ui.color(Role::OnErrorContainer), + ), + frame::text_role_owned( + ui, + TypeRole::BodyMedium, + false, + format!("{} · {}", fatal.label, fatal.code), + ui.color(Role::OnErrorContainer), + ), + frame::text_role( + ui, + TypeRole::BodySmall, + false, + fatal.message.as_str(), + ui.color(Role::OnErrorContainer), + ), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill), + )); + if let Some(hint) = &fatal.hint { + block = block.push( + row![ + frame::text_role( + ui, + TypeRole::LabelMedium, + false, + catalog.text(Key::PackFatalHint), + ui.color(Role::OnSurfaceVariant), + ), + frame::text_role( + ui, + TypeRole::BodySmall, + false, + hint.as_str(), + ui.color(Role::OnSurfaceVariant), + ), + ] + .spacing(ui.space(Space::X2)), + ); + } + } + + // 容忍域（缺文件 / 被拒 component）：中性容器 + `Warn` 图标 + 逐条 + if let Some(title) = &report.missing_title { + block = block.push( + column![ + tolerable_title(ui, title.clone()), + bounded( + ui, + rows_block(ui, catalog, &report.missing), + report.missing.len(), + 3, + 120.0, + ), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill), + ); + } + if let Some(title) = &report.rejected_title { + // 没有这句的话，「Could not fetch (tolerated): 3」下面会多出一行没有归属的 + // 「not supported by the client」（复审 r1 P2-4） + block = block.push( + column![ + tolerable_title(ui, title.clone()), + // 与 missing / conflicts 同一条口径：条目多时框起来滚，别把动作顶出屏幕 + bounded( + ui, + rows_block(ui, catalog, &report.rejected), + report.rejected.len(), + 3, + 110.0, + ), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill), + ); + } + + if let Some(title) = &report.conflicts_title { + block = block.push( + column![ + tolerable_title(ui, title.clone()), + bounded( + ui, + column( + report + .conflicts + .iter() + .map(|conflict| conflict_row(ui, catalog, conflict)) + .collect::>() + ) + .spacing(ui.space(Space::X1)) + .width(Length::Fill), + report.conflicts.len(), + 2, + 160.0, + ), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill), + ); + } + + for warning in &report.warnings { + block = block.push(frame::text_role( + ui, + TypeRole::BodySmall, + false, + warning.as_str(), + ui.color(Role::OnSurfaceVariant), + )); + } + + if let Some(note) = &report.overwrite_note { + block = block.push(frame::text_role( + ui, + TypeRole::BodySmall, + false, + note.as_str(), + ui.color(Role::OnSurfaceVariant), + )); + } + + let mut actions = row![] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Center); + if report.can_overwrite { + actions = actions.push(buttons::outlined( + ui, + Button::new( + catalog.text(Key::PackOverwriteAction), + intent(PackMessage::Overwrite), + ) + .leading(IconKind::Refresh), + )); + } + actions = actions.push(buttons::text( + ui, + Button::new(catalog.text(Key::PackDismiss), intent(PackMessage::Dismiss)), + )); + block = block.push(actions); + + block.into() +} + +/// 一条冲突：路径 + 成因 + 本次处置（点一行展开三方哈希）。 +pub(super) fn conflict_row<'a>( + ui: &'a Ui, + catalog: Catalog, + conflict: &'a ConflictRow, +) -> Element<'a, PageMessage> { + let head = row![ + frame::text_role( + ui, + TypeRole::BodySmall, + false, + conflict.path.as_str(), + ui.color(Role::OnSurface), + ), + frame::text_role( + ui, + TypeRole::BodySmall, + false, + conflict.reason.as_str(), + ui.color(Role::OnSurfaceVariant), + ), + frame::text_role( + ui, + TypeRole::LabelMedium, + false, + conflict.choice.as_str(), + ui.color(Role::Tertiary), + ), + buttons::text( + ui, + Button::new( + catalog.text(Key::PackConflictDetail), + intent(PackMessage::ToggleConflict(conflict.path.clone())), + ) + .leading(IconKind::ChevronDown), + ), + ] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Center) + .width(Length::Fill); + + let mut block = column![head].width(Length::Fill); + if conflict.expanded { + block = block.push(frame::text_role_owned( + ui, + TypeRole::BodySmall, + false, + catalog.render( + Key::PackConflictHashes, + &[ + ("pack", conflict.pack_sha1.as_str()), + ("base", conflict.base_sha1.as_deref().unwrap_or("—")), + ("disk", conflict.disk_sha1.as_deref().unwrap_or("—")), + ], + ), + ui.color(Role::OnSurfaceVariant), + )); + } + block.into() +} + +pub(super) fn status_icon(report: &Report) -> IconKind { + match report.status { + unlucky_presenter::dto::ImportStatusView::Success => IconKind::Check, + unlucky_presenter::dto::ImportStatusView::Partial => IconKind::Warn, + unlucky_presenter::dto::ImportStatusView::Failed => IconKind::Error, + } +} + +pub(super) fn status_role(report: &Report) -> Role { + match report.status { + unlucky_presenter::dto::ImportStatusView::Success => Role::Primary, + unlucky_presenter::dto::ImportStatusView::Partial => Role::Tertiary, + unlucky_presenter::dto::ImportStatusView::Failed => Role::Error, + } +} diff --git a/crates/app-iced/src/pages/content/parts.rs b/crates/app-iced/src/pages/content/parts.rs new file mode 100644 index 0000000..45bebfb --- /dev/null +++ b/crates/app-iced/src/pages/content/parts.rs @@ -0,0 +1,338 @@ +//! 内容库页的零件：筛选条 / 结果列表 / 详情面板 / 四态（加载 / 空 / 失败 / 无更多）/ 一级切换。 +//! +//! 全是既有真组件（`chip` / `list_item` / `buttons` / `empty_state`），页面不自己画状态层。 +//! +//! ## 消息口径 +//! +//! 本文件的每个控件都直接发 [`crate::pages::Message`]：内容库自己的意图包一层 +//! `PageMessage::Content(..)`（[`intent`]），而「取消安装 / 打开日志」用的是**下载页就有的** +//! 那两个变体——因为对用户来说它们是同一件事（同一个 `AppCommand::CancelInstall`）。 + +use iced::widget::{column, container, row, scrollable}; +use iced::{Alignment, Element, Length, Padding}; + +use unlucky_design::color::Role; +use unlucky_design::icons::IconKind; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; + +use unlucky_i18n::{Catalog, Key}; +use unlucky_presenter::dto::ContentSort; +use unlucky_presenter::router::Route; + +use crate::app::components::buttons::{self, Button}; +use crate::app::components::feedback::{empty_state, EmptyState}; +use crate::app::components::navigation::list_item::{list_item, ListItem}; +use crate::app::components::selection::{chip, Chip}; +use crate::theme::Ui; + +use super::layout::Rails; +use super::model::{Content, Hit, Status}; + +mod detail; +mod filters; + +pub(crate) use detail::detail; +pub(crate) use filters::{filters, labelled}; + +use super::Message as ContentMessage; +use crate::pages::frame; +use crate::pages::Message as PageMessage; + +/// 内容库意图 → 页面消息（唯一的一层包装）。 +pub(super) fn intent(message: ContentMessage) -> PageMessage { + PageMessage::Content(message) +} + +/// 结果行与行之间的间距（与下载页同值）。 +const ROW_GAP: Space = Space::X1; + +/// 一级切换：版本管理 | 内容库（M109 按 B1 裁定：共用同一条导航轨项，页内切换）。 +pub(super) fn section_switcher<'a>( + ui: &'a Ui, + catalog: Catalog, + on_content: bool, +) -> Element<'a, PageMessage> { + let versions = Chip::filter( + catalog.text(Key::ContentSectionVersions), + !on_content, + PageMessage::Navigate(Route::Download), + ); + let content = Chip::filter( + catalog.text(Key::ContentSectionContent), + on_content, + PageMessage::Navigate(Route::Content), + ); + row![chip(ui, versions), chip(ui, content)] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Center) + .into() +} + +/// 关键词搜索条（输入只改草稿；回车/按钮才发检索指令）。 +pub(super) fn search<'a>( + ui: &'a Ui, + catalog: Catalog, + model: &'a Content, +) -> Element<'a, PageMessage> { + // 输入只改草稿，**提交**才发检索（每敲一个字就打一次网络既没必要也会被限流）。 + // 搜索条自身没有提交回调，所以旁边给一个显式的「搜索」按钮——这也是键盘外的唯一出口。 + let bar = crate::app::components::inputs::search_bar( + ui, + crate::app::components::inputs::SearchBar::new(model.draft.as_str()) + .placeholder(catalog.text(Key::ContentSearchPlaceholder)), + move |text| intent(ContentMessage::QueryChanged(text)), + ); + let submit = crate::app::components::buttons::text( + ui, + crate::app::components::buttons::Button::new( + catalog.text(Key::ContentSearch), + intent(ContentMessage::Search), + ) + .leading(IconKind::Search), + ); + row![bar, submit] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Center) + .width(Length::Fill) + .into() +} + +/// 结果列表（独立滚动；底部「加载更多」钉在列表之外，见 [`more`]）。 +pub(super) fn list<'a>( + ui: &'a Ui, + catalog: Catalog, + model: &'a Content, + rails: Rails, +) -> Element<'a, PageMessage> { + let rows = column( + model + .hits + .iter() + .map(|hit| hit_row(ui, model, hit)) + .collect::>(), + ) + .spacing(ui.space(ROW_GAP)) + .padding(Padding::from([0.0, ui.space(Space::X2)])) + .width(Length::Fill); + + let _ = catalog; + container( + scrollable(rows) + .direction(scrollable::Direction::Vertical( + scrollable::Scrollbar::new() + .width(frame::SCROLLBAR_WIDTH) + .scroller_width(frame::SCROLLBAR_WIDTH) + .margin(frame::SCROLLBAR_MARGIN), + )) + .height(Length::Fill) + .style(frame::scroll_style(ui)), + ) + .width(Length::Fixed(rails.list)) + .height(Length::Fill) + .into() +} + +fn hit_row<'a>(ui: &'a Ui, model: &Content, hit: &'a Hit) -> Element<'a, PageMessage> { + let mut item = ListItem::new( + hit.title.as_str(), + intent(ContentMessage::Select(hit.id.clone())), + ) + .overline(hit.supporting.as_str()) + .supporting(hit.summary.as_str()) + .leading(kind_icon(model.kind)); + if model.selected.as_deref() == Some(hit.id.as_str()) { + item = item.selected(); + } + list_item(ui, item) +} + +/// 计数头 + 翻页尾（分页而非无限滚动：见 `pages/content.rs` 的模块文档）。 +pub(super) fn count_head<'a>( + ui: &'a Ui, + catalog: Catalog, + model: &Content, +) -> Element<'a, PageMessage> { + let count = if model.total > 0 { + model.total + } else { + u32::try_from(model.hits.len()).unwrap_or(u32::MAX) + }; + frame::text_role_owned( + ui, + TypeRole::LabelMedium, + false, + catalog.render( + Key::ContentCount, + &[("count", &super::model::thousands(u64::from(count)))], + ), + ui.color(Role::OnSurfaceVariant), + ) +} + +/// 列表尾部：还有更多 ⇒「加载更多」；没有了 ⇒ 一句「没有更多了」。 +pub(super) fn more<'a>(ui: &'a Ui, catalog: Catalog, model: &Content) -> Element<'a, PageMessage> { + if model.has_more { + return buttons::text( + ui, + Button::new( + catalog.text(Key::ContentLoadMore), + intent(ContentMessage::LoadMore), + ) + .leading(IconKind::ChevronDown), + ); + } + frame::text_role( + ui, + TypeRole::BodySmall, + false, + catalog.text(Key::ContentNoMore), + ui.color(Role::OnSurfaceVariant), + ) +} + +pub(super) fn loading<'a>(ui: &'a Ui, catalog: Catalog) -> Element<'a, PageMessage> { + centered( + column![ + frame::text_role_centered( + ui, + TypeRole::TitleMedium, + true, + catalog.text(Key::ContentLoading), + ui.color(Role::OnSurface) + ), + frame::text_role_centered( + ui, + TypeRole::BodySmall, + false, + catalog.text(Key::ContentLoadingHint), + ui.color(Role::OnSurfaceVariant) + ), + buttons::text( + ui, + Button::new( + catalog.text(Key::ContentRetry), + intent(ContentMessage::Retry) + ) + ), + ] + .spacing(ui.space(Space::X3)) + .width(Length::Fill) + .align_x(Alignment::Center), + ) +} + +/// 空态（真 `EmptyState`：CTA 是标准 Filled 按钮）。 +pub(super) fn empty<'a>(ui: &'a Ui, catalog: Catalog) -> Element<'a, PageMessage> { + centered(empty_state( + ui, + EmptyState::new( + IconKind::Search, + catalog.text(Key::ContentEmptyTitle), + catalog.text(Key::ContentEmptyBody), + ) + .action( + catalog.text(Key::ContentRetry), + intent(ContentMessage::Retry), + ), + )) +} + +/// 失败态（带原因与重试出口；原因来自 host，不打码不打折）。 +pub(super) fn failed<'a>( + ui: &'a Ui, + catalog: Catalog, + reason: &'a str, +) -> Element<'a, PageMessage> { + centered( + column![ + row![ + frame::glyph(IconKind::Error, ui.color(Role::Error), frame::ICON_PX), + frame::text_role( + ui, + TypeRole::TitleSmall, + true, + catalog.text(Key::ContentFailedTitle), + ui.color(Role::Error) + ), + ] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Center), + frame::text_role( + ui, + TypeRole::BodySmall, + false, + reason, + ui.color(Role::OnSurfaceVariant) + ), + frame::text_role( + ui, + TypeRole::BodySmall, + false, + catalog.text(Key::ContentFailedBody), + ui.color(Role::OnSurfaceVariant) + ), + buttons::filled( + ui, + Button::new( + catalog.text(Key::ContentRetry), + intent(ContentMessage::Retry) + ) + .leading(IconKind::Refresh) + ), + ] + .spacing(ui.space(Space::X3)) + .width(Length::Fill) + .align_x(Alignment::Center), + ) +} + +fn centered<'a>(content: impl Into>) -> Element<'a, PageMessage> { + container(content) + .width(Length::Fill) + .height(Length::Fill) + .align_x(Alignment::Center) + .align_y(Alignment::Center) + .into() +} + +/// 内容类型 → 图标（**借用**现有字形：图标集里还没有「整合包/Mod/资源包/光影」四枚专用图标， +/// 已在报告里登记为偏离）。 +pub(super) const fn kind_icon(kind: unlucky_presenter::dto::ContentKind) -> IconKind { + // 两条硬约束（都来自门禁与复审）： + // ① `Play`/`Stop`/`More` 是**填充**字形，pages 里禁用（`tests/no_hardcoded_tokens`）； + // ② **不许与全局导航撞形**：`Instances`/`Download`/`Logs`/`Settings`/`Ai` 五枚在同一个屏上 + // 就在左边那条轨里，页内四类再借用它们会让「同形不同义」（复审 P2-3）。 + // + // 剩下的描边字形里挑语义最近的： + // `Folder`（包=文件夹）/ `Plus`（加装内容=加号）/ `Restore`（双层方框≈贴图分层）/ `Expand`（四散光线）。 + match kind { + unlucky_presenter::dto::ContentKind::Modpack => IconKind::Folder, + unlucky_presenter::dto::ContentKind::Mod => IconKind::Plus, + unlucky_presenter::dto::ContentKind::Resourcepack => IconKind::Restore, + unlucky_presenter::dto::ContentKind::Shader => IconKind::Expand, + } +} + +pub(super) fn sort_label(sort: ContentSort, catalog: Catalog) -> &'static str { + match sort { + ContentSort::Relevance => catalog.text(Key::ContentSortRelevance), + ContentSort::Downloads => catalog.text(Key::ContentSortDownloads), + ContentSort::Newest => catalog.text(Key::ContentSortNewest), + ContentSort::Updated => catalog.text(Key::ContentSortUpdated), + } +} + +/// 状态分派（四态各一支；`Ready` 由调用方画列表 + 详情）。 +pub(super) fn status_body<'a>( + ui: &'a Ui, + catalog: Catalog, + model: &'a Content, +) -> Option> { + match &model.status { + Status::Loading => Some(loading(ui, catalog)), + Status::Empty => Some(empty(ui, catalog)), + Status::Failed(reason) => Some(failed(ui, catalog, reason.as_str())), + Status::Ready => None, + } +} diff --git a/crates/app-iced/src/pages/content/parts/detail.rs b/crates/app-iced/src/pages/content/parts/detail.rs new file mode 100644 index 0000000..5d616a1 --- /dev/null +++ b/crates/app-iced/src/pages/content/parts/detail.rs @@ -0,0 +1,179 @@ +//! 详情面板：选中项的支持范围 + 目标实例 + 装入（不兼容时**禁用并逐条给原因**）。 +//! +//! 从 `pages/content/parts.rs` 拆出（那个文件已贴 400 行硬上限）。 +//! +//! 这块是「一键装入指定实例」的**唯一**入口：按钮能不能按由 [`Content::can_install`] 决定， +//! 按不动时旁边逐条列出原因——判定与画法分开，`model/tests.rs` 才能不开图形环境就钉住它。 + +use iced::widget::{column, container}; +use iced::{Element, Length}; + +use unlucky_design::color::Role; +use unlucky_design::icons::IconKind; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; + +use unlucky_i18n::{Catalog, Key}; + +use crate::app::components::buttons::{self, Button}; +use crate::app::components::divider; +use crate::app::components::selection::{chip, Chip}; +use crate::theme::Ui; + +use super::super::model::{capitalize, Content}; +use super::super::Message as ContentMessage; +use super::{intent, labelled}; +use crate::pages::frame; +use crate::pages::Message as PageMessage; + +/// 详情面板：选中项的支持范围 + 目标实例 + 装入（不兼容时**禁用并给原因**）。 +pub(crate) fn detail<'a>( + ui: &'a Ui, + catalog: Catalog, + model: &'a Content, +) -> Element<'a, PageMessage> { + let Some(hit) = model.selected_hit() else { + return container(frame::text_role( + ui, + TypeRole::BodySmall, + false, + catalog.text(Key::ContentDetailEmpty), + ui.color(Role::OnSurfaceVariant), + )) + .width(Length::Fill) + .into(); + }; + + let head = column![ + frame::text_role( + ui, + TypeRole::TitleMedium, + true, + hit.title.as_str(), + ui.color(Role::OnSurface) + ), + frame::text_role( + ui, + TypeRole::BodySmall, + false, + hit.supporting.as_str(), + ui.color(Role::OnSurfaceVariant), + ), + frame::text_role( + ui, + TypeRole::BodySmall, + false, + hit.summary.as_str(), + ui.color(Role::OnSurfaceVariant), + ), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill); + + let meta = column![ + frame::text_role( + ui, + TypeRole::LabelMedium, + false, + hit.downloads.as_str(), + ui.color(Role::OnSurfaceVariant) + ), + frame::text_role( + ui, + TypeRole::LabelMedium, + false, + hit.updated.as_str(), + ui.color(Role::OnSurfaceVariant) + ), + support_line(ui, catalog, Key::ContentDetailVersions, &hit.versions), + support_line(ui, catalog, Key::ContentDetailLoaders, &hit.loaders), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill); + + let mut body = column![head, divider::full(ui), meta].spacing(ui.space(Space::X3)); + + // 目标实例：一行 chip（选中的那个高亮） + if model.targets.is_empty() { + body = body.push(frame::text_role( + ui, + TypeRole::BodySmall, + false, + catalog.text(Key::ContentNoInstances), + ui.color(Role::OnSurfaceVariant), + )); + } else { + let mut targets = Vec::new(); + for target in &model.targets { + targets.push(chip( + ui, + Chip::filter( + target.name.as_str(), + model.target.as_deref() == Some(target.id.as_str()), + intent(ContentMessage::SetTarget(target.id.clone())), + ), + )); + } + body = body.push(labelled( + ui, + catalog.text(Key::ContentTargetInstance), + targets, + )); + } + + // 装入：能装 ⇒ 实心按钮；不能 ⇒ 禁用 + 逐条原因（**点之前**就说清楚） + if model.can_install() { + body = body.push(buttons::filled( + ui, + Button::new( + catalog.text(Key::ContentInstall), + intent(ContentMessage::Install), + ) + .leading(IconKind::Download), + )); + } else { + body = body.push(buttons::outlined( + ui, + Button::disabled(catalog.text(Key::ContentInstall)), + )); + for reason in model.blocker_reasons(catalog) { + body = body.push(frame::text_role_owned( + ui, + TypeRole::BodySmall, + false, + reason, + ui.color(Role::OnSurfaceVariant), + )); + } + } + + container(body.spacing(ui.space(Space::X3))) + .width(Length::Fill) + .into() +} + +/// 「游戏版本：1.20.1, 1.20.4」一行（空列表给 `—`，不编造）。 +fn support_line<'a>( + ui: &'a Ui, + catalog: Catalog, + key: Key, + values: &[String], +) -> Element<'a, PageMessage> { + let list = if values.is_empty() { + "—".to_string() + } else { + // 加载器是站点给的小写 facet（`fabric`）：这一层只管怎么显示 + values + .iter() + .map(|value| capitalize(value)) + .collect::>() + .join(", ") + }; + frame::text_role_owned( + ui, + TypeRole::BodySmall, + false, + catalog.render(key, &[("list", &list)]), + ui.color(Role::OnSurfaceVariant), + ) +} diff --git a/crates/app-iced/src/pages/content/parts/filters.rs b/crates/app-iced/src/pages/content/parts/filters.rs new file mode 100644 index 0000000..6e1a9f7 --- /dev/null +++ b/crates/app-iced/src/pages/content/parts/filters.rs @@ -0,0 +1,163 @@ +//! 筛选条：来源 / 排序 / 游戏版本 / 加载器四组 chip，外加分组标签与换行容器。 +//! +//! 从 `pages/content/parts.rs` 拆出（那个文件已贴 400 行硬上限）。 +//! +//! 缺 key 的源（CurseForge）画成**禁用**而不是消失：筛选条要能被发现，也要能解释自己。 + +use iced::widget::{column, container, row}; +use iced::{Alignment, Element, Length}; + +use unlucky_design::color::Role; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; + +use unlucky_i18n::{Catalog, Key}; +use unlucky_presenter::dto::{loader_facet, ContentSort, ContentSource, LoaderKind}; + +use crate::app::components::selection::{chip, Chip}; +use crate::theme::Ui; + +use super::super::model::{loader_name, Content}; +use super::super::Message as ContentMessage; +use super::{intent, sort_label}; +use crate::pages::frame; +use crate::pages::Message as PageMessage; + +/// 来源 + 排序 + 版本 + 加载器四组 chip（一行放不下就换行，`row` 变 `column`）。 +pub(crate) fn filters<'a>( + ui: &'a Ui, + catalog: Catalog, + model: &'a Content, +) -> Element<'a, PageMessage> { + let mut source = Vec::new(); + for item in ContentSource::ALL { + let available = match item { + ContentSource::Modrinth => true, + ContentSource::Curseforge => model.curseforge, + }; + let label = match item { + ContentSource::Modrinth => catalog.text(Key::ContentSourceModrinth), + ContentSource::Curseforge => catalog.text(Key::ContentSourceCurseforge), + }; + let mut spec = Chip::filter( + label, + model.query.source == item, + intent(ContentMessage::SetSource(item)), + ); + if !available { + // 缺 key 的源：**禁用并说明**，不是静默消失（否则用户找不到它） + spec = spec.disabled(); + } + source.push(chip(ui, spec)); + } + + let mut sort = Vec::new(); + for item in ContentSort::ALL { + sort.push(chip( + ui, + Chip::filter( + sort_label(item, catalog), + model.query.sort == item, + intent(ContentMessage::SetSort(item)), + ), + )); + } + + let mut versions = vec![chip( + ui, + Chip::filter( + catalog.text(Key::ContentFilterAny), + model.query.version.is_none(), + intent(ContentMessage::SetVersion(None)), + ), + )]; + for version in &model.versions { + versions.push(chip( + ui, + Chip::filter( + version.as_str(), + model.query.version.as_deref() == Some(version.as_str()), + intent(ContentMessage::SetVersion(Some(version.clone()))), + ), + )); + } + + let mut loaders = vec![chip( + ui, + Chip::filter( + catalog.text(Key::ContentFilterAny), + model.query.loader.is_none(), + intent(ContentMessage::SetLoader(None)), + ), + )]; + for loader in [ + LoaderKind::Fabric, + LoaderKind::Forge, + LoaderKind::NeoForge, + LoaderKind::Quilt, + ] { + let usable = loader_facet(loader).is_some(); + let mut spec = Chip::filter( + loader_name(loader), + model.query.loader == Some(loader), + intent(ContentMessage::SetLoader(Some(loader))), + ); + if !usable { + spec = spec.disabled(); + } + loaders.push(chip(ui, spec)); + } + + let mut column = column![ + labelled(ui, catalog.text(Key::ContentFilterVersion), versions), + labelled(ui, catalog.text(Key::ContentFilterLoader), loaders), + wrapped_row(ui, source), + wrapped_row(ui, sort), + ] + .spacing(ui.space(Space::X2)) + .width(Length::Fill); + + if !model.curseforge { + column = column.push(frame::text_role( + ui, + TypeRole::BodySmall, + false, + catalog.text(Key::ContentSourceUnavailable), + ui.color(Role::OnSurfaceVariant), + )); + } + column.into() +} + +/// 分组标签 + 一行 chip（标签左、chip 右，纵向居中对齐）。 +pub(crate) fn labelled<'a>( + ui: &'a Ui, + label: &'a str, + chips: Vec>, +) -> Element<'a, PageMessage> { + 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/tests.rs b/crates/app-iced/src/pages/content/tests.rs new file mode 100644 index 0000000..e4dcb08 --- /dev/null +++ b/crates/app-iced/src/pages/content/tests.rs @@ -0,0 +1,87 @@ +//! 内容库页的守门（M109）：演示数据、四类内容、页面自留状态的默认值。 +//! +//! 视图模型的判定在 `model/tests.rs`，栏几何在 `layout.rs`，这里只管「演示数据真的装得满」—— +//! 出图靠它，装不满就说明 `demo()` 与 `Content` 的字段对不上。 + +use unlucky_i18n::Lang; +use unlucky_presenter::dto::ContentKind; + +use super::model::{PageState, Status}; +use super::{demo, Content}; + +#[test] +fn the_page_state_starts_on_mods_with_nothing_selected() { + let page = PageState::default(); + assert_eq!(page.kind, ContentKind::Mod); + assert!(page.selected.is_none()); + assert!(page.target.is_none()); + assert!(page.draft.is_empty()); +} + +#[test] +fn every_kind_gets_a_full_demo_screen() { + // 四种内容各出一屏（状态矩阵的前 8 张靠这一条） + for kind in ContentKind::ALL { + let model: Content = demo(kind, Lang::En); + assert_eq!(model.kind, kind, "{} 的演示数据换了类型", kind.slug()); + assert_eq!(model.status, Status::Ready, "{}", kind.slug()); + assert_eq!(model.hits.len(), 4, "{} 的命中项不足", kind.slug()); + assert!( + model.selected.is_some(), + "演示数据要选中一条（详情面板才有内容）" + ); + assert!(model.total > 0); + assert!(model.has_more, "演示数据要能画「加载更多」"); + // 整合包**不**在这一条里断（它天生不可装：`ContentKind::Modpack.dir()` 是 `None`）， + // 由下一条用例专钉。 + if kind != ContentKind::Modpack { + assert!( + model.can_install(), + "默认那一屏应当是「能装」的（{}）", + kind.slug() + ); + } + } +} + +#[test] +fn the_modpack_screen_is_browsable_but_never_installable() { + // 整合包：检索能看，装入一律禁用（M111 未落地）——演示图上必须看得到原因 + let model = demo(ContentKind::Modpack, Lang::En); + assert!(model.selected.is_some()); + assert!(!model.can_install()); + assert_eq!( + model.blocker_reasons(Lang::En.catalog()).len(), + 1, + "整合包只有一条原因（导入管线未落地）" + ); +} + +#[test] +fn the_installable_kinds_block_only_when_the_target_disagrees() { + for kind in [ + ContentKind::Mod, + ContentKind::Resourcepack, + ContentKind::Shader, + ] { + let model = demo(kind, Lang::En); + assert!( + model.blocker_reasons(Lang::En.catalog()).is_empty(), + "{} 的默认演示项应当可装", + kind.slug() + ); + } +} + +#[test] +fn the_demo_selection_is_always_one_of_the_hits() { + for kind in ContentKind::ALL { + let model = demo(kind, Lang::En); + let selected = model.selected.clone().expect("有选中项"); + assert!( + model.hits.iter().any(|hit| hit.id == selected), + "{} 的选中项不在命中列表里（详情面板会是空的）", + kind.slug() + ); + } +} diff --git a/crates/app-iced/src/pages/content/view.rs b/crates/app-iced/src/pages/content/view.rs new file mode 100644 index 0000000..bf9d9fd --- /dev/null +++ b/crates/app-iced/src/pages/content/view.rs @@ -0,0 +1,232 @@ +//! 内容库页的整页装配：页头（含一级切换）+ 左侧类型栏 + 主列（筛选/结果）+ 详情 + 安装面板。 +//! +//! ## 版面（几何在 [`super::layout`]，这里只消费结果） +//! +//! ```text +//! ┌─ 页头：Content [版本管理 | 内容库] ─┐ +//! ├──────┬────────────────────────┬──────────────┤ +//! │ 类型 │ 搜索 + 四组 chip │ 详情 / 装入 │ +//! │ 四条 │ 计数头 │ 原因逐条列出 │ +//! │ 侧栏 │ 结果列表（独立滚动） │ │ +//! │ │ 加载更多 / 没有更多了 │ │ +//! ├──────┴────────────────────────┴──────────────┤ +//! │ 安装面板（**下载页那块**，只在有安装时出现） │ +//! └──────────────────────────────────────────────┘ +//! ``` +//! +//! ## 为什么类型栏用 `list_item`（与 M107 的版本类型栏同一套） +//! +//! 四条内容类型是**一级侧栏**（页面内导航），几何与状态层必须与版本管理页一致：`list_item` +//! 自带 60 高两行档与选中态，页面不自己写 hover/pressed。窄档（`Tight`）退成一行 chip—— +//! 栏宽没了就不该硬塞一条 140px 的栏。 + +use iced::widget::{column, container, row}; +use iced::{Element, Length}; + +use unlucky_design::spacing::Space; + +use unlucky_i18n::{Catalog, Key}; +use unlucky_presenter::dto::ContentKind; + +use crate::app::components::divider; +use crate::app::components::navigation::list_item::{list_item, ListItem}; +use crate::app::components::selection::{chip, Chip}; +use crate::theme::Ui; + +use crate::pages::download; +use crate::pages::frame::{self, Header}; +use crate::pages::layout::FrameMetrics; +use crate::pages::Message as PageMessage; + +use super::layout::{self as content_layout, Rails, Tier}; +use super::model::{Content, Status}; +use super::parts; +use super::Message as ContentMessage; + +/// 整页入口（由 `pages/mod.rs` 的 `render` 调；页面层不认识 presenter 类型）。 +pub(super) fn view<'a>( + ui: &'a Ui, + metrics: FrameMetrics, + model: &'a Content, + lang: unlucky_i18n::Lang, +) -> Element<'a, PageMessage> { + let catalog = lang.catalog(); + let header = Header::new(catalog.text(Key::ContentTitle)) + .subtitle(catalog.text(Key::ContentSubtitle)) + .action(parts::section_switcher(ui, catalog, true)); + frame::page(ui, metrics, header, body(ui, metrics, catalog, model)) +} + +fn body<'a>( + ui: &'a Ui, + metrics: FrameMetrics, + catalog: Catalog, + model: &'a Content, +) -> Element<'a, PageMessage> { + let rails = content_layout::resolve(metrics.available); + + let mut columns = row![kind_rail(ui, catalog, model, rails)] + .spacing(rails.gap) + .width(Length::Fill) + .height(Length::Fill); + + if rails.tier == Tier::Tight { + // 窄到放不下侧栏：类型条跑到主列上方（同一个 `kind_rail`，chip 形态） + let main = column![ + kind_rail(ui, catalog, model, rails), + divider::full(ui), + main_column(ui, catalog, model, rails) + ] + .spacing(ui.space(Space::X2)) + .width(Length::Fill) + .height(Length::Fill); + columns = row![main].width(Length::Fill).height(Length::Fill); + } else { + columns = columns.push(main_column(ui, catalog, model, rails)); + if rails.tier.has_detail() { + columns = columns.push(detail_column(ui, catalog, model, rails)); + } + } + + let mut stack = column![columns] + .spacing(ui.space(Space::X3)) + .width(Length::Fill) + .height(Length::Fill); + if let Some(panel) = &model.panel { + // **同一块安装面板**（下载页那个函数）：内容库不另画一套进度/失败/取消。 + stack = stack + .push(divider::full(ui)) + .push(download::install_panel(ui, catalog, panel)); + } + stack.into() +} + +/// 左侧四条内容类型（`Wide`/`Compact` 是列表项，`Narrow` 是图标项，`Tight` 是一行 chip）。 +fn kind_rail<'a>( + ui: &'a Ui, + catalog: Catalog, + model: &'a Content, + rails: Rails, +) -> Element<'a, PageMessage> { + if rails.tier == Tier::Tight { + let mut chips = Vec::new(); + for kind in ContentKind::ALL { + chips.push(chip( + ui, + Chip::filter( + kind_label(kind, catalog), + model.kind == kind, + PageMessage::Content(ContentMessage::SetKind(kind)), + ), + )); + } + return row(chips) + .spacing(ui.space(Space::X2)) + .width(Length::Fill) + .into(); + } + + let labels = rails.tier.rail_has_labels(); + let mut items = column(Vec::new()) + .spacing(ui.space(Space::X1)) + .width(Length::Fill); + for kind in ContentKind::ALL { + let label = kind_label(kind, catalog); + // 图标档没有文字位：标签仍传（无障碍/日志用），宽度由几何裁掉 + let mut item = ListItem::new( + if labels { label } else { " " }, + PageMessage::Content(ContentMessage::SetKind(kind)), + ) + .leading(parts::kind_icon(kind)); + if model.kind == kind { + item = item.selected(); + } + items = items.push(list_item(ui, item)); + } + + container(items) + .width(Length::Fixed(rails.rail)) + .height(Length::Fill) + .into() +} + +/// 主列：搜索条 + 筛选 + 计数 + 结果（或四态之一）。 +fn main_column<'a>( + ui: &'a Ui, + catalog: Catalog, + model: &'a Content, + rails: Rails, +) -> Element<'a, PageMessage> { + // 主列的横向内边距不在这里加：`rails.list` 已经把可用宽算干了，再加 2×X2 会让整排 + // 溢出 32px（详情列被切掉一半，复审截图上正是这条） + let mut head = column![parts::search(ui, catalog, model)] + .spacing(ui.space(Space::X2)) + .width(Length::Fill); + + // 筛选条**永远在**：它是控制面，不是数据。加载中把筛选条藏起来，用户就没法在慢网络下 + // 换条件或换类型（只能干等），这是「加载态顺手把入口收走」的经典坑。 + head = head.push(parts::filters(ui, catalog, model)); + head = head.push(divider::full(ui)); + if model.status == Status::Ready { + // 计数头只在有数据时出现：0 条的「0 results」和空态说的是同一件事，画两遍是噪音 + head = head.push(parts::count_head(ui, catalog, model)); + } + + let body: Element<'a, PageMessage> = if let Some(state) = parts::status_body(ui, catalog, model) + { + state + } else { + // **必须给间距**（复审 P2-1）：这一列原先漏了 `.spacing(..)`，而列表自身的纵向内边距是 0， + // 于是「列表视口底边」与「加载更多」贴在一起，末行正好被切在半行上。 + let mut list = column![parts::list(ui, catalog, model, rails)] + .spacing(ui.space(Space::X2)) + .width(Length::Fill) + .height(Length::Fill); + // 紧凑档没有独立详情列：详情压在列表下面（整页替换的成本比「多一块」高） + if !rails.tier.has_detail() { + list = list + .push(divider::full(ui)) + .push(parts::detail(ui, catalog, model)); + } + list.push(parts::more(ui, catalog, model)).into() + }; + + let mut column = column![] + .spacing(ui.space(Space::X2)) + .width(Length::Fixed(rails.list)) + .height(Length::Fill); + + // M113: import/export —— 只有整合包这一类才有「把本地的包装进来 / 把实例打出去」。 + // 其它三类（Mod / 资源包 / 光影）的导入就是把文件拖进目录，不属于本条任务。 + if model.kind == ContentKind::Modpack { + column = column + .push(super::packui::section(ui, catalog, &model.pack)) + .push(divider::full(ui)); + } + + column.push(head).push(body).into() +} + +/// 详情列（只在 `Wide` / `Narrow` 存在）。 +fn detail_column<'a>( + ui: &'a Ui, + catalog: Catalog, + model: &'a Content, + rails: Rails, +) -> Element<'a, PageMessage> { + container(parts::detail(ui, catalog, model)) + .width(Length::Fixed(rails.detail)) + .height(Length::Fill) + .style(move |_theme| container::Style::default()) + .into() +} + +/// 四种内容类型的界面名。 +fn kind_label(kind: ContentKind, catalog: Catalog) -> &'static str { + match kind { + ContentKind::Modpack => catalog.text(Key::ContentKindModpack), + ContentKind::Mod => catalog.text(Key::ContentKindMod), + ContentKind::Resourcepack => catalog.text(Key::ContentKindResourcepack), + ContentKind::Shader => catalog.text(Key::ContentKindShader), + } +} diff --git a/crates/app-iced/src/pages/download.rs b/crates/app-iced/src/pages/download.rs new file mode 100644 index 0000000..d0e85dd --- /dev/null +++ b/crates/app-iced/src/pages/download.rs @@ -0,0 +1,241 @@ +//! **版本管理页**（原下载页）：三栏版面 —— 版本类型 / 主版本 / 列表 + 安装面板。 +//! +//! 用户令（信息架构调整）把这一页从「下载」改称「版本管理」：下载页只负责整合包与 Mod/光影， +//! 而这一页管的是**游戏版本与加载器安装**。本文件是那次改版后的页面装配点。 +//! **标识符不改**（用户令 2026-11-04 的「只改显示层」边界）：`Route::Download` / +//! `Screen::Download` / 文件名 / 类型名一律保留，全仓重命名另开 finding 后置——所以本文件里 +//! 「下载页」三个字到处都是，那是标识符的叫法，不是界面上出现的词。 +//! **M102 版面订正**：旧版把整页块压到 424 并水平居中（1180 宽下左缘 422、页头标题在 112， +//! 左右各空 ~300px，视觉复审判为「内容缩在中间一条窄栏」）。现在页面块走 [`frame::body`] +//! ——左缘与页头标题同一条线（= 页边距 24），宽 = 块宽 `frame::body_width`（1180 下 1044， +//! 极宽窗封顶 **1440**）。424 只约束**成段散文**（本页没有），三栏的每一栏都吃块宽。 +//! +//! ## 版面：三栏，宽度由布局系统裁决 +//! +//! ```text +//! ┌─────────┬─────────┬──────────────────────────────┐ +//! │ 版本类型 │ 主版本 │ 搜索条 · 命中数 · 计数头 │ +//! │ 140/64 │ 140/64 │ 版本行（单行四项） │ +//! │ │ │ … │ +//! │ │ │ 安装面板（M105 的选项区在这里）│ +//! └─────────┴─────────┴──────────────────────────────┘ +//! ``` +//! +//! 三个数字**没有一个是在本文件里拍的**：它们来自 +//! [`VersionRails`](super::layout::VersionRails)（宽档裁决 + 数值表在 `pages/layout/rails.rs`）。 +//! 页面只做一件事：把裁决结果交给 [`rails`] 画出来。 +//! +//! ## 原顶部 4 个 tab 的去处（不是新造分类） +//! +//! 四个 chip（全部 / 正式版 / 预览版 / 远古版）**语义一字不改**，只是从顶部横排搬到第一栏竖排； +//! 窄到三栏不成立时（可用宽 < 600）它们**原样回到顶部**（[`rails::stacked_chips`]）——同一条 +//! [`Category`] 谓词、同一条 `AppCommand::ListVersions`。 +//! +//! ## 意图 → 消息 → 指令（页面只发意图，不做乐观回显） +//! +//! | 用户动作 | 页面消息 | app 层落点 | +//! |---|---|---| +//! | 点分类 tab | [`Message::SetCategory`] | `AppCommand::ListVersions(category)`（`All` 不派：画现有快照） | +//! | 点一行 | [`Message::SelectVersion`] | **只改视图模型**（选中不是业务命令） | +//! | 点「安装」 | [`Message::InstallVersion`] | `AppCommand::CreateInstance(草稿)`（M105：带加载器与实例名） | +//! | 点「取消安装」 | [`Message::CancelInstall`] | `AppCommand::CancelInstall` | +//! | 点「刷新」/「打开日志」 | `Message::Action(RefreshSources)` / `Message::Navigate(Logs)` | `ListVersions` / `AppState::navigate` | +//! +//! ## M105：安装选项（加载器维度） +//! +//! 选中版本**不再直接开工**。面板下半块变成「安装选项」区：五家加载器（原版 / Forge / +//! NeoForge / Fabric / Quilt）的 chip、该加载器的官方版本列表、实例名，点「安装」才派 +//! `CreateInstance`。选项的决策与画法在 [`options`]（子模块），本文件只负责把模型交给它。 +//! 加载器版本列表来自 core 的 `LoaderSource::loader_versions`（经 +//! `AppCommand::ListLoaderVersions` 回流到快照）；取不到时页面给具名原因并**禁掉确认**—— +//! 不许「选完才失败」。 +//! +//! 进度条只读 `model.install`：它由 presenter 的 `InstallProgress` 事件经 `apply` 灌进来。 +//! 于是「点了没变」只有一种解释——后端还没回事件，这正是要的（P3-2 的纪律）。 +//! +//! ## M107：两级侧栏从哪来（第一级 = 版本类型，第二级 = 主版本桶） +//! +//! 第一级 = 版本类型（4 项，固定）；第二级 = 主版本桶（由快照里的版本 id 按 [`group`] 的规则归纳， +//! 远古版这类「没有主版本概念」的只有「全部版本」一项）。 +//! +//! ## 搜索（三层口径） +//! +//! | 情形 | 画面 | +//! |---|---| +//! | 有命中 | 列表照常；侧栏**位置不动**；搜索条右侧给「N 个匹配」（跨类型读数） | +//! | 一个都不命中 | [`states::no_match`]：没有匹配 + 换短片段 + 清空 | +//! | 有命中但不在当前类型 | [`states::elsewhere`]：N 个在别的类型 + 「看全部类型」 | +//! | 搜索中点第二级桶 | **退出搜索 + 按那个桶过滤**（点桶 = 「我就是要看这个桶」，见 `on_download`） | +//! +//! 查询词写在 presenter 快照的 `download_query` 里（页面无状态，见 [`model::Download::from_snapshot`]）， +//! 所以「搜索 → 任何事件回来之后仍然在搜」这条不需要页面持有任何字段。 +//! +//! ## 状态矩阵（加载 / 空 / 有数据 / 安装中 / 失败） +//! +//! 与 M94 时一致，唯一的改动是**空态与搜索态都留在三栏骨架里**：侧栏与搜索框照旧在， +//! 只有列表区换成占位内容——白屏会让人以为列表坏了。 +//! +//! ## 两个纯视图态的字段（快照里没有，重建会丢） +//! +//! `selected_major`（第二级侧栏选中）与 `type_rail_folded`（类型栏手动折叠）**不在 presenter 快照里** +//! （`AppState` 没有这两个字段，加字段要动 `pages/mod.rs` 的偏离表与 presenter，见 M107 报告）。 +//! 所以它们与既有的 `selected` 同一档处理：`on_download` 直接改视图模型，**不重建**； +//! 唯一会重建的路径是搜索（`rebuild_after_query`），那里把两个字段在重建前后各搬一次。 +//! 其余事件（安装进度、版本列表刷新）回来时这两个字段会回到默认值——与 `selected` 的既有缺口同源， +//! 长期要靠 presenter 加字段，已登记在报告里。 +//! +//! ## 版面判据（M102 口径：页面块 vs 散文列） +//! +//! 页面仍是 `PaneKit::Single`（页内自己切三栏）。整页内容走 [`frame::body`]：块左缘 = +//! 页头标题左缘 = `rail 88 + gutter 24 = 112`，块宽 = [`frame::body_width`]（pane 宽封顶 +//! **1440**）——视觉复审 ①（内容缩在中间一条窄栏、与页头错位）因此收口。 +//! **三栏的列宽从「块宽」算**（[`VersionRails::of_metrics`] 读 `frame::body_width`，不是 +//! `metrics.available`）：否则 1576+ 的超宽窗上三列之和会超出 1440 的块、右侧被裁。 +//! 424（[`super::layout::measure_cap_px`]）在本页只对**成段散文**有效——这一页没有散文。 + +mod demo; +mod group; +mod install; +mod model; +mod options; +mod rails; +mod rows; +mod states; + +#[cfg(test)] +mod tests; + +pub use demo::demo; +pub use model::{cancelled_toast, Category, Download}; +pub use options::{InstallDraft, Loader}; + +// M109：内容库页复用**同一块**安装面板（同一个函数、同一套文案与几何），不另写一套。 +// +// 两个薄包装为什么必须在**这个文件**里：①`install::panel` 是 `pub(super)`（只在 `pages::download` +// 可见），再导出到 crate 会撞 `E0364`；②面板的入参是 `&Download`，而 `InstallView` 是页面私有 +// 类型（M105 起不再从本模块导出），所以「快照 → 面板形状」的转换也留在这里——内容库只拿到 +// `Option`，它不需要也不该认识 `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`）；页面自己不读全局、不猜语言。 +pub fn view<'a>( + ui: &'a Ui, + metrics: FrameMetrics, + model: &'a Download, + lang: Lang, +) -> Element<'a, Message> { + let catalog = lang.catalog(); + + let header = Header::new(catalog.text(Key::DownloadTitle)) + .subtitle(catalog.text(Key::DownloadSubtitle)) + // M109：一级切换「版本管理 | 内容库」。两页共用同一条导航轨项（`NavSection::Download`）， + // 所以这个切换是进内容库的唯一产品入口——少了它，内容库只能靠 `ULL_START_ROUTE` 到达。 + .action(content::section_switcher(ui, catalog)) + .action(buttons::text( + ui, + Button::new( + catalog.text(Key::DownloadRefresh), + Message::Action(Action::RefreshSources), + ), + )); + + frame::page(ui, metrics, header, body(ui, metrics, catalog, model)) +} + +/// 正文：加载态仍是居中占位；其余状态都长在三栏骨架上。 +fn body<'a>( + ui: &'a Ui, + metrics: FrameMetrics, + catalog: Catalog, + model: &'a Download, +) -> Element<'a, Message> { + if model.is_loading() { + // 还没拉到版本列表：三栏没有内容可填，给占位（安装面板照旧带着，见 M94 复审 p3） + let content: Element<'a, Message> = if model.install.is_some() { + column![ + states::loading(ui, catalog), + divider::full(ui), + install::panel(ui, catalog, model) + ] + .spacing(ui.space(Space::X3)) + .width(Length::Fill) + .height(Length::Fill) + .into() + } else { + states::loading(ui, catalog) + }; + return frame::body(metrics, content); + } + + // 宽度裁决：档位来自布局系统，「用户手动折叠了类型栏」这一条覆盖叠在上面。 + let rails = { + let rails = VersionRails::of_metrics(metrics); + if model.type_rail_folded { + rails.with_type_folded() + } else { + rails + } + }; + + let content: Element<'a, Message> = if rails.tier.is_three_column() { + rails::three_column(ui, catalog, model, rails) + } else { + // 三栏不成立（可用宽 < 600）：类型与主版本原样退回顶部 chips，列表吃掉整条可用宽 + column![ + rails::stacked_chips(ui, catalog, model), + divider::full(ui), + rows::content(ui, catalog, model), + ] + .spacing(ui.space(Space::X2)) + .width(Length::Fill) + .height(Length::Fill) + .into() + }; + + // M102：整页块走 `frame::body`（贴左、块宽封顶 1440），与页头标题同一条左缘。 + // 三栏都在这个块里切，所以 `VersionRails` 读的是块宽而不是 `metrics.available`。 + frame::body(metrics, content) +} diff --git a/crates/app-iced/src/pages/download/demo.rs b/crates/app-iced/src/pages/download/demo.rs new file mode 100644 index 0000000..63d9b38 --- /dev/null +++ b/crates/app-iced/src/pages/download/demo.rs @@ -0,0 +1,301 @@ +//! 下载页的**演示数据**（截图 harness 与单测的输入，产品路径不读）。 +//! +//! 与 `pages/instances/data.rs` 同一条纪律：演示条目是**页面侧常量**，不是业务 DTO—— +//! 于是核心 DTO 每改一次字段，基线图不会跟着漂。真页面的数据只走 +//! [`Download::from_snapshot`](super::model::Download::from_snapshot)。 +//! +//! 演示条目本身也是一步「DTO → 视图模型」的真转换（[`VersionRow::of`](super::model::VersionRow)、 +//! [`InstallView::of`](super::model::InstallView)）：图上看到的副文案 / 进度行就是产品路径 +//! 那条转换的产物，不是另写一套拼串。 +//! +//! ## 为什么要一个环境变量 +//! +//! 状态矩阵（加载 / 空 / 有数据 / 安装中 / 安装失败）都要出图，而 harness 的 +//! `--screen` 只选页面、选不了页面状态： +//! +//! ```text +//! ULL_DL_DEMO=empty cargo run -p unlucky-app-iced --example pages_demo -- \ +//! --screen=download --screenshot=out.png --screenshot-theme=light --software-renderer +//! ``` +//! +//! 取值：`ready`（缺省）/ `loading` / `empty` / `selected` / `category-release` / `installing` / +//! `installing-late` / `installing-empty` / `failed` / `done` / `done-next` / +//! **`options` / `options-fabric` / `options-incompat`**（M105 的安装选项区三态）/ +//! **`category-ancient` / `search` / `search-major` / `search-empty` / `search-elsewhere`** +//! （M107 的两级侧栏与搜索取样点）。 +//! +//! M107 那几个取样点**都走产品那条真转换**（`Download::from_snapshot`，查询词写在快照的 +//! `download_query` 里）：图证明的是产品路径的行为，不是演示的特权。 +//! +//! `category-release` / `done` / `done-next` 都**不手搓结果**，而是拿一份 `AppState` 跑 +//! [`Download::from_snapshot`]：图证明的是产品路径的行为（分类本地过滤、装完后面板让回列表）， +//! 不是演示的特权。 +//! +//! `done` / `done-next` 是「**刚装完**」的两个采样点：它们不手搓模型，而是拿一份 +//! `AppState`（版本列表 + `InstallStage::Done`）跑 [`Download::from_snapshot`]，所以图上看到的是 +//! 产品路径的真行为（复审 p2：`Done` 之后面板必须让回列表，否则第二个版本装不了）。 +//! **只有 harness 与演示走这里**：产品路径由 `app/view.rs` 从 presenter 快照建模型。 + +use unlucky_presenter::dto::{ + AncientKind, InstallProgressView, InstallStage, VersionKind, VersionSummary, +}; + +use unlucky_presenter::dto::{AppEvent, CoreEvent}; +use unlucky_presenter::state::AppState; + +use unlucky_i18n::Catalog; + +use super::model::{Category, Download, InstallView, VersionRow}; +use super::options::{InstallDraft, Loader}; + +/// 取证开关的名字（[`demo`] 读它）。 +pub const DEMO_STATE_ENV: &str = "ULL_DL_DEMO"; + +/// 演示模型：按 [`DEMO_STATE_ENV`] 选状态，缺省是「有数据」。 +pub fn demo(catalog: Catalog) -> Download { + match std::env::var(DEMO_STATE_ENV).ok().as_deref() { + Some("loading") => Download::loading(), + Some("empty") => Download { + loaded: true, + ..Download::loading() + }, + Some("installing") => Download { + install: Some(install(InstallStage::Downloading, 0.42, catalog)), + selected: Some("1.21.9".to_string()), + ..ready(catalog) + }, + // 同一状态的第二个采样点：进度条随**事件**推进（不是动画），出图时两帧对照 + Some("installing-late") => Download { + install: Some(install(InstallStage::Downloading, 0.8, catalog)), + selected: Some("1.21.9".to_string()), + ..ready(catalog) + }, + // M105：安装选项区三态（未选加载器 / 已选 Fabric / 不兼容组合）。 + // 三条都走**产品那条真转换**（`from_snapshot` + 草稿），图里看到的是页面真会画的东西。 + Some("options") => options(catalog, "1.21.9", Loader::Vanilla, None), + Some("options-fabric") => options( + catalog, + "1.21.9", + Loader::Fabric, + Some(vec!["0.16.5", "0.16.4", "0.15.11"]), + ), + // NeoForge 最早只到 1.20.1，远古版（列表里的 `rd-132211`）根本没有构建 ⇒ 选中即报原因 + Some("options-incompat") => options(catalog, "rd-132211", Loader::NeoForge, None), + Some("selected") => Download { + selected: Some("1.21.9".to_string()), + ..ready(catalog) + }, + Some("failed") => Download { + install: Some(install(InstallStage::Failed, 0.0, catalog)), + selected: Some("1.21.9".to_string()), + ..ready(catalog) + }, + // 装完之后：走**产品那条真转换**（见 `finished`），图里看到的就是页面真会画的东西 + Some("done") => finished(catalog, None), + // 装完之后再点下一个版本：面板必须重新给出实心「安装」 + Some("done-next") => finished(catalog, Some("1.21.9-pre3")), + // 安装进行中、但列表被过滤空：面板要跟着占位态一起在（复审 p3 的边角） + // 分类筛选（本页本地过滤：真 host 丢弃 ListVersions 的分类参数）——混合清单里只留正式版 + Some("category-release") => category(catalog, Category::Release), + // M107 的两级侧栏 + 搜索：这三种状态**都走产品那条真转换**（from_snapshot）， + // 图里看到的是页面真会画的东西，不是演示的特权。 + Some("category-ancient") => searched(catalog, Category::Ancient, ""), + Some("search") => searched(catalog, Category::All, "1.20"), + Some("search-major") => majored(searched(catalog, Category::All, ""), "1.21"), + Some("search-empty") => searched(catalog, Category::All, "zzz"), + Some("search-elsewhere") => searched(catalog, Category::Release, "24w"), + // 复审 P2-1 的取样点：**选中 1.21 桶的同时搜 1.20**。修好之后列表里是 2 行命中、 + // 侧栏点亮「全部版本」（第二级在搜索期间放宽），不会出现「2 个匹配 + 没有版本」。 + Some("search-over-bucket") => majored(searched(catalog, Category::All, "1.20"), "1.21"), + // 复审 P2-2 的取样点：**22 个主版本桶**（MOJANG 清单里 `Release` 就是这个量级）。 + // chips 档一行放不下 ⇒ 主版本行必须能横向滚，否则后面的桶永远点不到。 + Some("many-buckets") => many(catalog), + Some("installing-empty") => Download { + install: Some(install(InstallStage::Downloading, 0.42, catalog)), + ..Download::loading() + }, + _ => ready(catalog), + } +} + +/// 有数据：八行（四条正式、两条预览、两条远古），覆盖四种版本形态与三个主版本桶。 +/// +/// 不复用 `mock_data::mock_versions()`：演示数据是**出图的基线**，得比 mock 稳定 +/// （mock 随 P3 的假数据一起漂）。 +fn ready(catalog: Catalog) -> Download { + let versions = demo_versions(); + let rows: Vec = 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) +} + +/// 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(), + }, + 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..93d34c2 --- /dev/null +++ b/crates/app-iced/src/pages/download/install.rs @@ -0,0 +1,252 @@ +//! 安装面板（页面底部）：选中版本 → **安装选项** → 「安装」/ 进度 + 「取消」/ 失败 → 「打开日志」。 +//! +//! M105 之前这里是「选中版本 → 直接『安装』」：点下去就开工，加载器维度整个不存在 +//! （用户实跑的原话：「没是否有选择有前置加载器(版本选择)选项」）。选项区在 `options/`， +//! 本文件只管**面板形态的决策**（纯函数 [`panel_state`]）与「安装中 / 失败」两种形态。 +//! +//! ## 这一块为什么钉在底部而不是跟着列表滚 +//! +//! 列表装的是几十行版本；底部按钮如果跟着滚，用户在列表中间永远看不到「安装」在哪。 +//! 所以列表独立滚动（`rows::list`），面板固定占尾部一块高度。 +//! +//! ## 只有意图，没有乐观回显 +//! +//! | 控件 | 消息 | app 层落点 | +//! |---|---|---| +//! | 「安装」 | [`Message::InstallVersion`] | `AppCommand::CreateInstance(草稿)`（带加载器与实例名） | +//! | 「取消安装」 | [`Message::CancelInstall`] | `AppCommand::CancelInstall` | +//! | 「打开日志」 | [`Message::Navigate`]（`Route::Logs`） | `AppState::navigate`（不派指令） | +//! +//! 按钮按下**不改任何本地状态**：进度条读的是 `model.install`，它只由 presenter 的 +//! `InstallProgress` 事件灌进来（`apply` → 视图模型重建）。于是「点了没变」= 后端还没回事件。 +//! +//! ## 三种面板形态刻意不同构（M94 r1 / P2-3 + P2-4） +//! +//! | 状态 | 形态 | 为什么 | +//! |---|---|---| +//! | 选好了 | 版本 id + 实心「安装」 | 本页唯一的实心按钮（rubric K2） | +//! | 安装中 | 版本 id + 阶段 + **进度条**（仅当进度已知）+ 计数 + 文本「取消安装」 | 有进度才有条 | +//! | 失败 | **整块 `ErrorContainer` 面板**：`Error` 图标 + `Error` 色标题 + 停在哪 + 实心「打开日志」 | **不画进度条**——进度条正是「看起来还在跑」的来源；颜色/图标/措辞/按钮四样一起变，才一眼可辨 | +//! +//! 进度未知（刚派发、后端还没给文件计数）时**不画条**：页面没有帧订阅，`Progress::indeterminate` +//! 只会得到一个静止的假进度（复审 P2-3 的「17% 卡住」），不如只写「等第一个文件…」。 + +use iced::widget::{column, container, row}; +use iced::{Alignment, Background, Border, Element, Length, Padding}; + +use unlucky_design::color::Role; +use unlucky_design::icons::IconKind; +use unlucky_design::shape::ShapeScale; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; + +use unlucky_presenter::router::Route; + +use unlucky_i18n::{Catalog, Key}; + +use crate::app::components::buttons::{self, Button}; +use crate::app::components::feedback::{linear, Progress}; +use crate::theme::Ui; + +use super::super::frame; +use super::super::Message; +use super::model::{Download, InstallView}; +use super::options::OptionsView; + +/// 面板要画哪一种形态（**决策与画法分开**：决策是纯函数，单测直接钉它）。 +/// +/// 分开的理由就是本轮复审那件事：「装完之后面板还占着、用户再也装不了第二个版本」—— +/// 这是**决策**错了，画法本身没错；把决策抽出来，测试才能在不开图形环境的情况下断言它。 +#[derive(Debug, Clone, PartialEq)] +pub(super) enum PanelState<'a> { + /// 没有安装、也没选中：一句「选一个版本再安装」 + Hint, + /// 选中了一个版本：给出**安装选项区**（M105；加载器 / 加载器版本 / 实例名 + 「安装」） + Options(&'a OptionsView), + /// 有安装（进行中 / 失败）：进度或错误面板 + Install(&'a InstallView), +} + +/// 面板此刻该画哪一种（纯函数，无 iced）。 +/// +/// 顺序是**安装优先**：有安装时面板讲安装，讲不了列表；安装结束后 `model.install` 由 +/// [`Download::from_snapshot`](super::model::Download::from_snapshot) 清掉，于是这里自然回到 +/// [`PanelState::Options`] / [`PanelState::Hint`]，用户能接着选下一个版本。 +pub(super) fn panel_state(model: &Download) -> PanelState<'_> { + match &model.install { + Some(install) => PanelState::Install(install), + None => match &model.options { + Some(options) => PanelState::Options(options), + None => PanelState::Hint, + }, + } +} + +/// 底部的安装面板。 +pub(super) fn panel<'a>(ui: &'a Ui, catalog: Catalog, model: &'a Download) -> Element<'a, Message> { + let content = match panel_state(model) { + PanelState::Install(install) => installing(ui, catalog, install), + // 选中版本之后**先给选项，再点「安装」**（M105：以前是选中就直接开工，等于没有加载器维度） + PanelState::Options(options) => super::options::section(ui, catalog, options), + PanelState::Hint => hint(ui, catalog), + }; + + container(content) + .width(Length::Fill) + .padding(Padding::from([ui.space(Space::X3), 0.0])) + .into() +} + +/// 没选中任何版本：给一句「选一个版本再安装」（不静默禁用，也不画一个点不动的按钮）。 +fn hint<'a>(ui: &'a Ui, catalog: Catalog) -> Element<'a, Message> { + frame::text_role( + ui, + TypeRole::BodySmall, + false, + catalog.text(Key::DownloadSelectHint), + ui.color(Role::OnSurfaceVariant), + ) +} + +/// 安装中 / 已收尾（失败另走 [`failed`]）。 +fn installing<'a>(ui: &'a Ui, catalog: Catalog, install: &'a InstallView) -> Element<'a, Message> { + if install.failed() { + return failed(ui, catalog, install); + } + + let head = row![ + container(frame::text_role( + ui, + TypeRole::BodyMedium, + false, + install.version.as_str(), + ui.color(Role::OnSurface), + )) + .width(Length::Fill), + frame::text_role( + ui, + TypeRole::LabelMedium, + false, + install.stage_label.as_str(), + ui.color(Role::OnSurfaceVariant), + ), + ] + .width(Length::Fill) + .align_y(Alignment::Center); + + let mut body = column![head]; + // 进度已知才画条：未知时画 indeterminate 会得到一个静止的假进度（见模块文档）。 + if install.known { + body = body.push(linear(ui, Progress::determinate(install.ratio))); + } + body = body.push(frame::text_role( + ui, + TypeRole::BodySmall, + false, + install.detail.as_str(), + ui.color(Role::OnSurfaceVariant), + )); + if let Some(rate) = &install.rate { + body = body.push(frame::text_role( + ui, + TypeRole::BodySmall, + false, + rate.as_str(), + ui.color(Role::OnSurfaceVariant), + )); + } + + let action = if install.running() { + buttons::text( + ui, + Button::new(catalog.text(Key::DownloadCancel), Message::CancelInstall), + ) + } else { + frame::gap(0.0) + }; + + column![ + body.spacing(ui.space(Space::X2)).width(Length::Fill), + action + ] + .spacing(ui.space(Space::X2)) + .width(Length::Fill) + .into() +} + +/// 失败态：一整块 `ErrorContainer` 面板（**没有进度条**）。 +/// +/// 四样一起变，保证与「正在下载」一眼可辨：容器色（`ErrorContainer`）/ 图标（`Error`）/ +/// 措辞（`Install failed` 用 `Error` 色标题）/ 主按钮（实心「打开日志」，不是文本按钮）。 +fn failed<'a>(ui: &'a Ui, catalog: Catalog, install: &'a InstallView) -> Element<'a, Message> { + let head = row![ + frame::glyph(IconKind::Error, ui.color(Role::Error), frame::ICON_PX), + frame::text_role( + ui, + TypeRole::TitleSmall, + true, + catalog.text(Key::DownloadStageFailed), + ui.color(Role::Error), + ), + ] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Center); + + let stopped = frame::text_role_owned( + ui, + TypeRole::BodySmall, + false, + format!("{} · {}", install.version, install.detail), + ui.color(Role::OnErrorContainer), + ); + + let actions = row![ + buttons::filled( + ui, + Button::new( + catalog.text(Key::DownloadOpenLogs), + Message::Navigate(Route::Logs), + ) + .leading(IconKind::Logs), + ), + // 失败把面板钉住了：不给出口的话用户既重试不了、也装不了别的版本（只能重启）。 + // `CancelInstall` 在 host 侧就是「清 install + 发 InstallProgress(None)」，对没在跑的任务是安全 no-op。 + buttons::text( + ui, + Button::new(catalog.text(Key::DownloadDismiss), Message::CancelInstall), + ), + ] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Center); + + container( + column![ + head, + stopped, + frame::text_role( + ui, + TypeRole::BodySmall, + false, + catalog.text(Key::DownloadFailedHint), + ui.color(Role::OnErrorContainer), + ), + actions, + ] + .spacing(ui.space(Space::X2)) + .width(Length::Fill), + ) + .width(Length::Fill) + .padding(ui.space(Space::X4)) + .style(move |_theme| container::Style { + background: Some(Background::Color(ui.color(Role::ErrorContainer))), + border: Border { + radius: ui.radius_dp(ShapeScale::Large), + ..Border::default() + }, + ..container::Style::default() + }) + .into() +} + +#[cfg(test)] +mod tests; diff --git a/crates/app-iced/src/pages/download/install/tests.rs b/crates/app-iced/src/pages/download/install/tests.rs new file mode 100644 index 0000000..e960bb5 --- /dev/null +++ b/crates/app-iced/src/pages/download/install/tests.rs @@ -0,0 +1,136 @@ +//! 安装面板的决策测试（M94 r2）。 +//! +//! 从 `install.rs` 外置（那边加上本轮修复会顶到 400 行）。`use super::*` 仍指向 +//! `crate::pages::download::install`，`PanelState` / `panel_state` 是那里的 `pub(super)`。 +//! +//! **不走 `MockBackend`**：`MockBackend::script_install` 只发 Dialog + Toast、从不发 +//! `InstallProgress`（复审 r1 的取证），所以 mock 下 `install` 恒为 `None`，终态分支永远跑不到—— +//! 用 mock 写的测试会**假绿**。这里直接构造 `AppState` 并 `apply(CoreEvent::InstallProgress(..))`。 + +use unlucky_presenter::dto::{ + AppEvent, CoreEvent, InstallProgressView, InstallStage, VersionKind, VersionSummary, +}; +use unlucky_presenter::state::AppState; + +use unlucky_i18n::Lang; + +use super::super::model::{Category, Download}; +use super::super::options::InstallDraft; +use super::{panel_state, PanelState}; + +fn version(id: &str) -> VersionSummary { + VersionSummary { + id: id.to_string(), + kind: VersionKind::Release, + released: "2026-09-20".to_string(), + installed: false, + } +} + +fn progress(stage: InstallStage) -> InstallProgressView { + InstallProgressView { + version: "1.21.9".to_string(), + stage, + files_done: 512, + files_total: 512, + ..InstallProgressView::new() + } +} + +fn snapshot(stage: InstallStage) -> AppState { + let mut state = AppState::new(); + state.apply(AppEvent::Core(CoreEvent::VersionListChanged(vec![ + version("1.21.9"), + version("1.21.8"), + ]))); + state.apply(AppEvent::Core(CoreEvent::InstallProgress(Some(progress( + stage, + ))))); + state +} + +/// **装完之后页面必须回到「能再装下一个」**（复审 p2 的修复验收）。 +/// +/// 复审现象：`InstallDone` 从不清 `AppState.install`（presenter 只在取消时清），而面板**优先** +/// 用 `install`，终态又没有可执行动作 ⇒ 装完第一个版本后按钮永久消失，只能重启进程。 +/// +/// 抓得住：`Done` 之后面板还被 `install` 占着（= 装不了第二个版本的根因）、列表没回来、 +/// 面板不再给「安装」。测试直接钉 [`panel_state`]——那是 `panel()` 唯一的决策入口，两者不会漂。 +/// 抓不住：presenter 侧 `AppState.install` 仍是 `Some(Done)`（proper fix 不在本 mission，已报 finding）； +/// 也抓不住「装完后已装标记不刷新」（同一个 finding）。 +#[test] +fn a_finished_install_gives_the_page_back_to_the_list() { + let running = Download::from_snapshot( + &snapshot(InstallStage::Downloading), + Category::All, + &InstallDraft::default(), + Lang::En.catalog(), + ); + assert!(running.install.is_some(), "跑着的时候面板要在"); + assert!(matches!(panel_state(&running), PanelState::Install(_))); + + let state = snapshot(InstallStage::Done); + assert_eq!( + state.install.as_ref().map(|view| view.stage), + Some(InstallStage::Done), + "现实如此：快照里仍留着终态（presenter 不清），页面必须自己让位" + ); + + let model = Download::from_snapshot( + &state, + Category::All, + &InstallDraft::default(), + Lang::En.catalog(), + ); + assert!(model.install.is_none(), "Done 之后不许再占着安装面板"); + assert!(model.selected.is_none(), "装完不替用户选中任何行"); + assert_eq!(model.rows.len(), 2, "列表要回来"); + assert_eq!( + panel_state(&model), + PanelState::Hint, + "回到「选一个版本再安装」" + ); + + // 再装一次：选中下一个版本 → 面板重新给出**安装选项区**（M105 起「安装」在选项区里） + let next = Download::from_snapshot( + &state, + Category::All, + &InstallDraft { + selected: Some("1.21.9".to_string()), + ..InstallDraft::default() + }, + Lang::En.catalog(), + ); + let options = match panel_state(&next) { + PanelState::Options(options) => options, + other => panic!("装完之后必须能接着装下一个版本，实际 {other:?}"), + }; + assert_eq!(options.version, "1.21.9"); + assert!(options.can_confirm, "原版 + 列表里的版本 = 可以装"); +} + +/// 取消与失败**不许**一起被清：失败态是 P2-4 的错误出口，取消是「已经没事了」。 +/// +/// 抓得住：把 `finished()` 写成「terminated()」（那会把失败态的日志入口一起清掉，用户失去原因）。 +/// 抓不住：presenter 在取消后是否补发 `InstallProgress(None)`（那是 presenter 的行为）。 +#[test] +fn only_done_and_cancelled_release_the_panel() { + let failed = Download::from_snapshot( + &snapshot(InstallStage::Failed), + Category::All, + &InstallDraft::default(), + Lang::En.catalog(), + ); + assert!(failed.install.is_some(), "失败态要留在屏幕上"); + assert!(matches!(panel_state(&failed), PanelState::Install(_))); + + for stage in [InstallStage::Done, InstallStage::Cancelled] { + let model = Download::from_snapshot( + &snapshot(stage), + Category::All, + &InstallDraft::default(), + Lang::En.catalog(), + ); + assert!(model.install.is_none(), "{stage:?} 之后面板要让位"); + } +} diff --git a/crates/app-iced/src/pages/download/model.rs b/crates/app-iced/src/pages/download/model.rs new file mode 100644 index 0000000..b2756f2 --- /dev/null +++ b/crates/app-iced/src/pages/download/model.rs @@ -0,0 +1,367 @@ +//! 下载页视图模型：**presenter 快照 → 页面要画的东西**（与 [`super::super::model`] 同一套分层）。 +//! +//! ## 为什么这一页也要中间层 +//! +//! 页面层不认识 presenter 的 DTO（同实例页的理由）：真页面吃 `AppState` 的快照， +//! 演示数据与单测吃 [`super::demo`]，两边都转成这里的纯展示字段。 +//! +//! 文案在这一层就按 [`Catalog`] 求好值（`supporting` / `detail` / `rate` 都是 `String`）： +//! iced 的文字控件**借用**内容，行内文案又是 `format!` 出来的，不先落成字段就没法进控件树 +//! （`pages/frame` 的 `text_role_owned` 是同一个理由的单行版）。 +//! +//! ## 快照里**没有**的东西（都登记在 `pages/mod.rs` 的偏离表里） +//! +//! | 缺什么 | 后果 | 兜法 | +//! |---|---|---| +//! | 「版本列表已加载完成」标志 | 空列表既可能是「还没拉到」也可能是「真的没有」 | [`Download::loaded`] 按「快照里有没有版本」判：没有 = 加载中 | +//! | 版本列表**失败**事件 | 拉取失败会停在加载态（不静默：页面上有说明与刷新入口） | 错误态借安装阶段的 `Failed`（结构化、可翻译） | +//! | 「当前选中」字段 | 选中态存在模型里，任何快照重建都会回到「正在安装的那个版本」 | 见 `pages/mod.rs` 偏离登记；长期要靠 presenter 加字段 | +//! +//! ## 中文串一个都不许画 +//! +//! `InstallProgressView::message` / `InstallStage::label()` 都是**中文业务串**（`i18n::bridge` +//! 的规矩 2：core 的中文串只给日志和 CLI）。所以这里只搬**结构化字段**（阶段枚举、计数、字节）， +//! 文案按 `Key` 现求——中文环境自然出中文，英文环境不需要任何中文字体。 + +use unlucky_presenter::dto::{ + human_bytes, InstallProgressView, InstallStage, VersionKind, VersionSummary, +}; +use unlucky_presenter::state::AppState; + +use unlucky_i18n::{Catalog, Key, Lang}; + +use super::options::{InstallDraft, OptionsView}; + +/// 取消安装之后那一句提示（M105）。 +/// +/// 为什么文案在页面层而不是 presenter：取消的**信号**由 host 发（`CoreEvent::InstallCancelled`）， +/// 但 presenter 不依赖 `unlucky-i18n`，写死的中文会和页面语言打架（复审 P2-2 抓的就是这个： +/// 选项区是英文、取消弹窗是中文）。所以文本按 `Key` 现求，语言跟着页面走。 +#[must_use] +pub fn cancelled_toast(lang: Lang) -> String { + lang.catalog().text(Key::DownloadCancelled).to_owned() +} + +mod category; + +pub use category::Category; + +/// 版本列表的一行（`ListItem` 的两行档：headline = 版本 id，supporting = `正式版 · 发布于 …`）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct VersionRow { + /// 版本 id（`1.21.9` / `rd-132211`）——也是「安装」指令的载荷 + pub id: String, + /// 发布日期（ISO-8601 日期部分，快照原样） + pub released: String, + /// 版本类型 + pub kind: VersionKind, + /// 本地是否已安装（行上给勾 / overline `Installed`） + pub installed: bool, + /// 副文案（`正式版 · 发布于 2026-09-20`；一行 = 一个 key，不拼片段） + pub supporting: String, +} + +impl VersionRow { + pub(super) fn of(version: &VersionSummary, catalog: Catalog) -> Self { + Self { + id: version.id.clone(), + released: version.released.clone(), + kind: version.kind, + installed: version.installed, + supporting: catalog.render( + Key::DownloadRowSupporting, + &[ + ("kind", catalog.text(kind_label_key(version.kind))), + ("date", version.released.as_str()), + ], + ), + } + } + + /// 这个版本属于哪个主版本桶（规则见 [`super::group`]）。 + pub fn major(&self) -> Option { + super::group::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..27a8ed1 --- /dev/null +++ b/crates/app-iced/src/pages/download/options.rs @@ -0,0 +1,36 @@ +//! 安装选项区（M105）：**选中版本之后先给选项，点「安装」才开工**。 +//! +//! ## 为什么要有这一步 +//! +//! 用户实跑反馈的原话是「点击下载之后它就直接下载了，没有选择前置加载器(版本选择)选项」。 +//! 这不是画得不好，是**功能没做**：`Message::InstallVersion` 直接派 `InstallVersion`， +//! 而 core 早就会装四家加载器（M32/M35/M45 已合）。于是「能装什么」与「UI 让你装什么」 +//! 之间差着一整个加载器维度。 +//! +//! ## 文件分工 +//! +//! | 文件 | 内容 | +//! |---|---| +//! | [`model`] | **决策**（无 iced）：加载器词表、兼容性静态规则、选项视图、确认键判据 | +//! | [`view`] | 控件树：加载器 chip ×2 行 + 加载器版本列表 + 实例名 + 不兼容提示 | +//! | `tests`（`options/tests.rs`） | 兼容性真值表 + 确认键门（纯函数，不开图形环境） | +//! +//! ## 一条纪律：页面只发意图 +//! +//! | 控件 | 消息 | app 层落点 | +//! |---|---|---| +//! | 加载器 chip | [`Message::SetLoader`](super::Message::SetLoader) | 改草稿 + 按需派 `ListLoaderVersions` | +//! | 加载器版本一行 | [`Message::SetLoaderVersion`](super::Message::SetLoaderVersion) | 改草稿 | +//! | 实例名输入 | [`Message::SetInstanceName`](super::Message::SetInstanceName) | 改草稿 | +//! | 「安装」 | [`Message::InstallVersion`](super::Message::InstallVersion) | `AppCommand::CreateInstance(草稿)` | +//! +//! 草稿（选中版本 + 三个选项）住在 `App`，由 `refresh_view` 带进页面模型——与分类筛选同一个做法， +//! 因为 `refresh_view` 每次事件都会把整棵模型重建，页面自己存不住任何东西。 + +mod model; +#[cfg(test)] +mod tests; +mod view; + +pub use model::{InstallDraft, Loader, OptionsView}; +pub(crate) use view::section; diff --git a/crates/app-iced/src/pages/download/options/model.rs b/crates/app-iced/src/pages/download/options/model.rs new file mode 100644 index 0000000..3db89f3 --- /dev/null +++ b/crates/app-iced/src/pages/download/options/model.rs @@ -0,0 +1,286 @@ +//! 安装选项的**决策**（无 iced）：选哪个加载器、它配不配这个原版版本、确认键能不能按。 +//! +//! ## 为什么选项要有自己的模型层 +//! +//! M105 之前「点安装」直接开工，于是用户装不了带加载器的版本（core 早就会装四家加载器， +//! 只是 UI 没接）。补上这一步之后，页面要回答的问题从一个变成四个： +//! +//! | 问题 | 判据 | +//! |---|---| +//! | 这个加载器配这个原版版本吗 | [`Loader::supports`]（静态规则，**不联网**） | +//! | 加载器版本有哪些 | presenter 的 `LoaderVersions` 快照（`state.loader_versions_for`） | +//! | 用哪个加载器版本 | 用户选的；没选就取列表里最新的一条（core 的 `resolve(kind, mc, None)` 也是这个口径） | +//! | 现在能不能点「安装」 | [`OptionsView::can_confirm`]（不兼容 / 列表没到位 / 已装 都按不下去） | +//! +//! ## 兼容性为什么是静态规则而不是问网络 +//! +//! 「选完才失败」是用户最讨厌的一种交互。凡是**官方根本没有**的组合（NeoForge × 1.12.2、 +//! 远古版 × 任何加载器），必须在选中那一刻就说清，不能等点了安装再回一个 404。 +//! 反过来说：**能**装但列表拉不到（网络问题）属于「取不到」，由 [`LoaderVersionsView::Failed`] +//! 显示具名原因并禁掉确认——两条都不会让用户「选完才失败」。 +//! +//! 规则来源（不猜：都是 core 安装管线自己的判据）： +//! - Fabric/Quilt 的 loader 列表从 `1.14` 起才有（core 走 fabric meta，1.13 及以前没有）； +//! - NeoForge 的第一个版本是 `1.20.1`（`maven::NEOFORGE_FORGE_LAYOUT_MC`）； +//! - Forge 从 `1.1` 起有正式构建；远古版（`rd-*` / `a*` / `b*`）与预览版在 maven 表里没有条目。 + +use unlucky_i18n::{Catalog, Key}; +use unlucky_presenter::dto::{LoaderKind, VersionKind}; +use unlucky_presenter::state::AppState; + +use super::super::model::VersionRow; + +/// 加载器版本下拉此刻的内容。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum LoaderVersionsView { + /// 还没查过 / 正在查（页面显示「正在获取…」，确认键按下不去） + Loading, + /// 查到了（**最新在前**，与 core 的 `loader_versions` 同序） + Ready(Vec), + /// 查不到：人读原因（页面显示它并禁掉确认，不静默显示成空列表） + Failed(String), +} + +/// 页面侧的加载器词表：只列 GUI 真能装的五家（与 `dto::LoaderKind::wizard_choices` 同集）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub enum Loader { + /// 原版（不装加载器） + #[default] + Vanilla, + /// Forge + Forge, + /// NeoForge + NeoForge, + /// Fabric + Fabric, + /// Quilt + Quilt, +} + +impl Loader { + /// 展示顺序（任务书的口径：原版 / Forge / NeoForge / Fabric / Quilt）。 + pub const ALL: [Loader; 5] = [ + Loader::Vanilla, + Loader::Forge, + Loader::NeoForge, + Loader::Fabric, + Loader::Quilt, + ]; + + /// 对应的 presenter 词表（派 `AppCommand` 时用）。 + pub const fn kind(self) -> LoaderKind { + match self { + Loader::Vanilla => LoaderKind::Vanilla, + Loader::Forge => LoaderKind::Forge, + Loader::NeoForge => LoaderKind::NeoForge, + Loader::Fabric => LoaderKind::Fabric, + Loader::Quilt => LoaderKind::Quilt, + } + } + + /// 从 presenter 词表回来（`OptiFine` / `LiteLoader` 不是本页选项）。 + pub const fn of(kind: LoaderKind) -> Option { + match kind { + LoaderKind::Vanilla => Some(Loader::Vanilla), + LoaderKind::Forge => Some(Loader::Forge), + LoaderKind::NeoForge => Some(Loader::NeoForge), + LoaderKind::Fabric => Some(Loader::Fabric), + LoaderKind::Quilt => Some(Loader::Quilt), + LoaderKind::OptiFine | LoaderKind::LiteLoader => None, + } + } + + /// chip 文案。 + /// + /// 四家加载器的名字是**专有名词**（Fabric/Forge/NeoForge/Quilt 官方各语言都写原样）， + /// 所以只有「原版」走 i18n；硬给品牌名建一条 en==zh 的 key 会被 + /// `catalog::tests::chinese_catalog_is_actually_chinese` 判为「未翻译」。 + pub fn label(self, catalog: Catalog) -> &'static str { + match self { + Loader::Vanilla => catalog.text(Key::LoaderVanilla), + Loader::Forge => "Forge", + Loader::NeoForge => "NeoForge", + Loader::Fabric => "Fabric", + Loader::Quilt => "Quilt", + } + } + + /// 这个加载器配不配这个原版版本（静态规则，见模块文档的判据表）。 + /// + /// 参数是 `(版本 id, 版本类型)` 而不是一整行：app 层在**派查询之前**也要问同一个问题 + /// （静态就不支持的组合不该去联网问，否则会白白换来一条「取不到」的 Toast）。 + pub fn supports(self, id: &str, kind: VersionKind) -> Result<(), Incompat> { + if self == Loader::Vanilla { + return Ok(()); + } + // 远古版：四家都没有构建（maven 表 / fabric meta 都没有这些版本）。 + if kind.is_ancient() { + return Err(Incompat::Unsupported); + } + let rank = release_rank(id); + match self { + Loader::Vanilla => Ok(()), + // 预览版：Fabric 系的确会为快照发 loader，交给列表回答（拉不到就显示原因）； + // maven 系（Forge/NeoForge）没有快照条目，直接拒。 + Loader::Fabric | Loader::Quilt => match rank { + Some(version) if version >= (1, 14, 0) => Ok(()), + Some(_) => Err(Incompat::NeedsAtLeast("1.14")), + None if kind == VersionKind::Snapshot => Ok(()), + None => Err(Incompat::Unsupported), + }, + Loader::Forge => match rank { + Some(_) => Ok(()), + None => Err(Incompat::Unsupported), + }, + Loader::NeoForge => match rank { + Some(version) if version >= (1, 20, 1) => Ok(()), + Some(_) => Err(Incompat::NeedsAtLeast("1.20.1")), + None => Err(Incompat::Unsupported), + }, + } + } +} + +/// 不支持的原因（两种，页面各一句文案）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Incompat { + /// 官方没有这个组合的构建 + Unsupported, + /// 需要某个最低原版版本 + NeedsAtLeast(&'static str), +} + +/// `1.20.1` → `(1, 20, 1)`；预览版 / 远古版 / 乱七八糟的串 → `None`。 +/// +/// 只要有一段落不是纯数字就给 `None`：宁可保守地拒绝一个自定义版本号，也不把 +/// `1.20.1-pre3` 当成 `1.20.1` 放过去（那会装出加载器找不到父版本）。 +pub fn release_rank(id: &str) -> Option<(u64, u64, u64)> { + let mut pieces = id.trim().split('.'); + let major: u64 = pieces.next()?.parse().ok()?; + let minor: u64 = pieces.next()?.parse().ok()?; + let patch: u64 = match pieces.next() { + Some(patch) => patch.parse().ok()?, + None => 0, + }; + if pieces.next().is_some() { + return None; + } + Some((major, minor, patch)) +} + +/// 用户还没确认的安装输入（**app 持有**，不是 presenter 快照的一部分）。 +/// +/// 为什么住在 app 而不是 presenter：这是「用户正在填、还没提交」的草稿， +/// 和下载页的分类筛选（`App::view.download.category` 的来源）是同一层的东西； +/// 塞进 presenter 快照会让后端视图模型混进 UI 草稿。 +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub struct InstallDraft { + /// 选中的版本 id（点行得到；点别的版本会清掉加载器版本，见 `app/update/download.rs`） + pub selected: Option, + /// 选中的加载器 + 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, + /// 本地已装（确认键给「已安装」禁用态） + pub installed: bool, + /// 现在能不能点「安装」 + pub can_confirm: bool, +} + +impl OptionsView { + /// 选中行 + 快照 + 草稿 → 选项区的样子。 + pub fn of(row: &VersionRow, state: &AppState, draft: &InstallDraft, catalog: Catalog) -> Self { + let loader = draft.loader; + let incompat = loader.supports(&row.id, row.kind); + // 静态就不支持的组合**不去查列表**（查了也只会换来一条「取不到」的假原因）： + // 空表 + 上面那条「没有适配构建」就是说清这件事的那一句话。 + let versions = if loader == Loader::Vanilla || incompat.is_err() { + LoaderVersionsView::Ready(Vec::new()) + } else { + match state.loader_versions_for(loader.kind(), &row.id) { + None => LoaderVersionsView::Loading, + Some(Ok(items)) => LoaderVersionsView::Ready(items.clone()), + Some(Err(reason)) => LoaderVersionsView::Failed(reason.clone()), + } + }; + // 用户选过就用它；没选过取列表里最新的一条（core 的默认口径也是「最新」）。 + let loader_version = if loader == Loader::Vanilla { + String::new() + } else if !draft.loader_version.trim().is_empty() { + draft.loader_version.clone() + } else { + match &versions { + LoaderVersionsView::Ready(items) => items.first().cloned().unwrap_or_default(), + _ => String::new(), + } + }; + + let problem = match (incompat, &versions) { + (Err(Incompat::Unsupported), _) => Some(catalog.render( + Key::DownloadOptionsIncompatible, + &[ + ("loader", loader.label(catalog)), + ("version", row.id.as_str()), + ], + )), + (Err(Incompat::NeedsAtLeast(min)), _) => Some(catalog.render( + Key::DownloadOptionsNeedsAtLeast, + &[("loader", loader.label(catalog)), ("min", min)], + )), + (Ok(()), LoaderVersionsView::Failed(reason)) => Some(catalog.render( + Key::DownloadOptionsLoaderVersionsFailed, + &[("reason", reason.as_str())], + )), + (Ok(()), LoaderVersionsView::Ready(items)) + if loader != Loader::Vanilla && items.is_empty() => + { + Some(catalog.render( + Key::DownloadOptionsLoaderVersionsEmpty, + &[("version", row.id.as_str())], + )) + } + (Ok(()), _) => None, + }; + + // 四条同时成立才按得下去：不兼容没有、列表真的就位（原版不需要列表）、没装过。 + // 「列表没到位」既包括 `Loading` 也包括 `Failed` 与空表——它们都已经在 `problem` 里说了原因。 + let ready = loader == Loader::Vanilla + || matches!(&versions, LoaderVersionsView::Ready(items) if !items.is_empty()); + let can_confirm = problem.is_none() && ready && !row.installed; + + Self { + version: row.id.clone(), + loader, + versions, + loader_version, + instance_name: draft.instance_name.clone(), + problem, + installed: row.installed, + can_confirm, + } + } + + /// 确认安装要提交的加载器版本（`None` = 让 core 用官方默认，只在原版路径出现）。 + pub fn loader_version_arg(&self) -> Option<&str> { + (!self.loader_version.is_empty()).then_some(self.loader_version.as_str()) + } +} diff --git a/crates/app-iced/src/pages/download/options/tests.rs b/crates/app-iced/src/pages/download/options/tests.rs new file mode 100644 index 0000000..aa81251 --- /dev/null +++ b/crates/app-iced/src/pages/download/options/tests.rs @@ -0,0 +1,254 @@ +//! 安装选项的决策单测（M105）：兼容性真值表 + 确认键门 + 默认加载器版本。 +//! +//! 全部是**纯函数**（`OptionsView::of` 吃 `AppState` 与 `VersionRow`，不碰 iced）， +//! 所以不开图形环境也能钉住「什么组合能装、什么组合按下不去」。 +//! +//! **为什么用 `AppState` 而不是 mock 后端**：加载器版本列表是快照字段 +//! （`state.loader_versions`），灌一条 `CoreEvent::LoaderVersions` 就能造出三种状态 +//! （没查过 / 查到了 / 取不到），比 mock 更直接，也不依赖 `MockBackend` 的脚本。 + +use unlucky_i18n::Lang; +use unlucky_presenter::dto::{ + AncientKind, AppEvent, CoreEvent, LoaderKind, VersionKind, VersionSummary, +}; +use unlucky_presenter::state::AppState; + +use super::model::{release_rank, Incompat, InstallDraft, Loader, LoaderVersionsView, OptionsView}; +use crate::pages::download::model::VersionRow; + +fn row(id: &str, kind: VersionKind) -> VersionRow { + VersionRow::of( + &VersionSummary { + id: id.to_string(), + kind, + released: "2026-09-20".to_string(), + installed: false, + }, + Lang::En.catalog(), + ) +} + +fn state_with(kind: LoaderKind, mc: &str, items: Result, &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 +} + +fn draft(loader: Loader) -> InstallDraft { + InstallDraft { + selected: Some("1.20.1".to_string()), + loader, + loader_version: String::new(), + instance_name: String::new(), + } +} + +/// 版本号解析：只有纯数字三段（或缺末段）才算正式版。 +#[test] +fn release_rank_only_accepts_plain_release_ids() { + assert_eq!(release_rank("1.20.1"), Some((1, 20, 1))); + assert_eq!(release_rank("1.20"), Some((1, 20, 0)), "缺末段按 0 算"); + assert_eq!(release_rank("24w14a"), None, "快照不是正式版号"); + assert_eq!(release_rank("rd-132211"), None); + assert_eq!( + release_rank("1.20.1-pre3"), + None, + "预发布不许当正式版放过去" + ); + assert_eq!(release_rank("1.20.1.2"), None, "多一段不认"); +} + +/// 兼容性真值表（任务书点名的「老版本 × NeoForge」在这条里）。 +#[test] +fn loader_support_matrix_is_explicit() { + // 原版永远可以 + for id in ["1.21.9", "1.12.2", "rd-132211"] { + let kind = if id.starts_with("rd") { + VersionKind::Ancient(AncientKind::Classic) + } else { + VersionKind::Release + }; + assert_eq!(Loader::Vanilla.supports(id, kind), Ok(())); + } + // NeoForge 要 1.20.1+ + assert_eq!( + Loader::NeoForge.supports("1.20.1", VersionKind::Release), + Ok(()) + ); + assert_eq!( + Loader::NeoForge.supports("1.12.2", VersionKind::Release), + Err(Incompat::NeedsAtLeast("1.20.1")), + "老版本 × NeoForge 必须在选中那一刻就说清，而不是点安装才失败" + ); + // Fabric/Quilt 要 1.14+ + assert_eq!( + Loader::Fabric.supports("1.20.1", VersionKind::Release), + Ok(()) + ); + assert_eq!( + Loader::Fabric.supports("1.12.2", VersionKind::Release), + Err(Incompat::NeedsAtLeast("1.14")) + ); + // Forge 任何正式版都行，但预览版/远古版没有 maven 条目 + assert_eq!( + Loader::Forge.supports("1.12.2", VersionKind::Release), + Ok(()) + ); + assert_eq!( + Loader::Forge.supports("24w14a", VersionKind::Snapshot), + Err(Incompat::Unsupported) + ); + // 远古版：四家全都不支持 + let ancient = ("a1.2.6", VersionKind::Ancient(AncientKind::OldAlpha)); + for loader in [ + Loader::Fabric, + Loader::Quilt, + Loader::Forge, + Loader::NeoForge, + ] { + assert_eq!( + loader.supports(ancient.0, ancient.1), + Err(Incompat::Unsupported) + ); + } +} + +/// 不兼容的组合：给具名提示，并且**确认键按下不去**。 +#[test] +fn incompatible_combination_disables_confirm_with_a_named_reason() { + let state = AppState::new(); + let options = OptionsView::of( + &row("1.12.2", VersionKind::Release), + &state, + &draft(Loader::NeoForge), + Lang::En.catalog(), + ); + assert!(!options.can_confirm, "不兼容就不许按下确认"); + let problem = options.problem.expect("要给出具名原因"); + assert!(problem.contains("NeoForge"), "{problem}"); + assert!(problem.contains("1.20.1"), "{problem}"); +} + +/// 默认加载器版本 = 列表里最新的一条（core 的默认口径）；用户选过就用用户的。 +#[test] +fn loader_version_defaults_to_the_newest_and_honours_the_choice() { + let state = state_with(LoaderKind::Fabric, "1.20.1", Ok(vec!["0.16.5", "0.16.4"])); + let options = OptionsView::of( + &row("1.20.1", VersionKind::Release), + &state, + &draft(Loader::Fabric), + Lang::En.catalog(), + ); + assert!(options.can_confirm); + assert_eq!(options.loader_version, "0.16.5", "没选过就用最新"); + assert_eq!(options.loader_version_arg(), Some("0.16.5")); + + let mut chosen = draft(Loader::Fabric); + chosen.loader_version = "0.16.4".to_string(); + let options = OptionsView::of( + &row("1.20.1", VersionKind::Release), + &state, + &chosen, + Lang::En.catalog(), + ); + assert_eq!(options.loader_version, "0.16.4", "用户选的就是用户选的"); +} + +/// 三条「列表还没到位」的状态都不许按下确认，且各自说清是哪种。 +#[test] +fn versions_pending_or_failed_blocks_confirm() { + let bare = AppState::new(); + let loading = OptionsView::of( + &row("1.20.1", VersionKind::Release), + &bare, + &draft(Loader::Fabric), + Lang::En.catalog(), + ); + assert_eq!(loading.versions, LoaderVersionsView::Loading); + assert!(!loading.can_confirm, "还没查过就不许装"); + + let failed = state_with(LoaderKind::Fabric, "1.20.1", Err("network down")); + let options = OptionsView::of( + &row("1.20.1", VersionKind::Release), + &failed, + &draft(Loader::Fabric), + Lang::En.catalog(), + ); + assert!(!options.can_confirm); + assert!( + options + .problem + .as_deref() + .is_some_and(|p| p.contains("network down")), + "取不到要给具名原因（不是空下拉）" + ); + + let empty = state_with(LoaderKind::Fabric, "1.20.1", Ok(vec![])); + let options = OptionsView::of( + &row("1.20.1", VersionKind::Release), + &empty, + &draft(Loader::Fabric), + Lang::En.catalog(), + ); + assert!(!options.can_confirm, "官方没有版本就不许装"); + assert!(options.problem.is_some()); +} + +/// 缓存键带原版版本：A 版本的列表不会挂到 B 版本下面。 +#[test] +fn cached_versions_are_keyed_by_minecraft_version() { + let state = state_with(LoaderKind::Fabric, "1.20.1", Ok(vec!["0.16.5"])); + let other = OptionsView::of( + &row("1.21.9", VersionKind::Release), + &state, + &draft(Loader::Fabric), + Lang::En.catalog(), + ); + assert_eq!( + other.versions, + LoaderVersionsView::Loading, + "换原版版本就得重新查，不许复用上一版的结果" + ); +} + +/// 原版：不查列表、不需要加载器版本，确认键直接可用。 +#[test] +fn vanilla_needs_no_loader_version_at_all() { + let state = AppState::new(); + let options = OptionsView::of( + &row("1.20.1", VersionKind::Release), + &state, + &draft(Loader::Vanilla), + Lang::En.catalog(), + ); + assert!(options.can_confirm); + assert_eq!(options.versions, LoaderVersionsView::Ready(Vec::new())); + assert_eq!(options.loader_version, ""); + assert_eq!(options.loader_version_arg(), None); +} + +/// 已装的版本：确认键给「已安装」禁用态（列表行上也有勾，按钮再点一次不会更清楚）。 +#[test] +fn installed_versions_cannot_be_confirmed_again() { + let state = AppState::new(); + let mut installed = row("1.20.1", VersionKind::Release); + installed.installed = true; + let options = OptionsView::of( + &installed, + &state, + &draft(Loader::Vanilla), + Lang::En.catalog(), + ); + assert!(options.installed); + assert!(!options.can_confirm); +} diff --git a/crates/app-iced/src/pages/download/options/view.rs b/crates/app-iced/src/pages/download/options/view.rs new file mode 100644 index 0000000..54fb428 --- /dev/null +++ b/crates/app-iced/src/pages/download/options/view.rs @@ -0,0 +1,213 @@ +//! 选项区的控件树（M105）。 +//! +//! ## 版面（424 正文列里的四段） +//! +//! ```text +//! 1.21.9 [安装] +//! 安装选项 +//! [原版][Forge][NeoForge] +//! [Fabric][Quilt] +//! 加载器版本 ← 只在选了加载器时出现 +//! ┌ 0.16.5 ┐ ← 官方那份列表（menu + 滚动，最多看两行） +//! │ 0.16.4 │ +//! └───────────────────┘ +//! [实例名 ] +//! NeoForge 需要 Minecraft 1.20.1 或更新 ← 不兼容时（Error 色） +//! ``` +//! +//! ## 为什么加载器分成两行 +//! +//! 五家一起排在 424 宽里最宽的那组（`原版 + Forge + NeoForge + Fabric + Quilt`）实测会溢出， +//! 而 chip 的几何是组件自己的真源（`ChipGeometry`），页面不许压它 ⇒ 折成两行。 +//! 顺序仍是任务书的口径（原版 / Forge / NeoForge / Fabric / Quilt），只是换行。 +//! +//! ## 为什么「不兼容」不禁用 chip、而是禁用确认键 +//! +//! 禁用的 chip 点不动，用户就**看不到原因**（那正是「选完才失败」的另一种形态）。 +//! 现在的做法：五家永远都能点，选中不兼容的那家时下面出现一行具名原因，同时「安装」变成禁用态。 +//! 于是「为什么不能装」和「怎么才能装」永远同屏。 + +use iced::widget::{column, container, row, scrollable}; +use iced::{Alignment, Element, Length}; + +use unlucky_design::color::Role; +use unlucky_design::icons::IconKind; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; + +use unlucky_i18n::{Catalog, Key}; + +use crate::app::components::buttons::{self, Button}; +use crate::app::components::inputs::{menu, Menu, MenuItem}; +use crate::app::components::inputs::{text_field, Field, FieldVariant}; +use crate::app::components::selection::{chip, Chip}; +use crate::theme::Ui; + +use super::super::frame; +use super::super::Message; +use super::model::{Loader, LoaderVersionsView, OptionsView}; + +/// 五家加载器（一行放得下：实测五枚 chip 合计约 311 dp，正文列 424）。 +const LOADERS: [Loader; 5] = [ + Loader::Vanilla, + Loader::Forge, + Loader::NeoForge, + Loader::Fabric, + Loader::Quilt, +]; + +/// 菜单项高度 = 48（`MenuGeometry` 的项高）×2 行 + 上下留白 8×2 = 112。 +/// 这么算是为了避免「列表被截掉半行」——滚动区高度必须覆盖整行。 +const VERSION_ROWS: f32 = 7.0; + +/// 选项区（面板的下半块）。 +pub(crate) fn section<'a>( + ui: &'a Ui, + catalog: Catalog, + options: &'a OptionsView, +) -> Element<'a, Message> { + let head = row![ + container(frame::text_role( + ui, + TypeRole::BodyMedium, + false, + options.version.as_str(), + ui.color(Role::OnSurface), + )) + .width(Length::Fill), + confirm(ui, catalog, options), + ] + .width(Length::Fill) + .align_y(Alignment::Center); + + let mut body = column![ + head, + frame::text_role( + ui, + TypeRole::LabelMedium, + false, + catalog.text(Key::DownloadOptionsTitle), + ui.color(Role::OnSurfaceVariant), + ), + loader_row(ui, catalog, options), + ] + .spacing(ui.space(Space::X2)) + .width(Length::Fill); + + // 「加载器版本」这一段只在**真该有列表**时出现：原版没有、静态不兼容没有（原因在下面那行）、 + // 取不到也没有（同样在原因行）。留一个空标题只会让人以为界面缺了一块。 + if show_versions(options) { + body = body.push(frame::text_role( + ui, + TypeRole::LabelMedium, + false, + catalog.text(Key::DownloadOptionsLoaderVersion), + ui.color(Role::OnSurfaceVariant), + )); + body = body.push(version_list(ui, catalog, options)); + } + + body = body.push(text_field( + ui, + Field::new(options.instance_name.as_str()) + .variant(FieldVariant::Outlined) + .label(catalog.text(Key::DownloadOptionsInstanceName)) + .placeholder(catalog.text(Key::DownloadOptionsInstanceNameHint)), + Message::SetInstanceName, + )); + + if let Some(problem) = &options.problem { + body = body.push(frame::text_role( + ui, + TypeRole::BodySmall, + false, + problem.as_str(), + ui.color(Role::Error), + )); + } + + body.into() +} + +/// 加载器版本这一段要不要画（见 `section` 的注释）。 +fn show_versions(options: &OptionsView) -> bool { + if options.loader == Loader::Vanilla || options.problem.is_some() { + return false; + } + match &options.versions { + LoaderVersionsView::Loading => true, + LoaderVersionsView::Ready(items) => !items.is_empty(), + LoaderVersionsView::Failed(_) => false, + } +} + +/// 一行加载器 chip（Filter 档：选中 = `SecondaryContainer`）。 +fn loader_row<'a>(ui: &'a Ui, catalog: Catalog, options: &'a OptionsView) -> Element<'a, Message> { + let mut line = row![] + .spacing(ui.space(Space::X1)) + .align_y(Alignment::Center); + for loader in LOADERS.iter() { + line = line.push(chip( + ui, + Chip::filter( + loader.label(catalog), + options.loader == *loader, + Message::SetLoader(*loader), + ), + )); + } + line.into() +} + +/// 官方那份加载器版本列表（`menu` + 滚动：Fabric 有上百条，不做下拉也不铺满屏）。 +fn version_list<'a>( + ui: &'a Ui, + catalog: Catalog, + options: &'a OptionsView, +) -> Element<'a, Message> { + match &options.versions { + LoaderVersionsView::Loading => frame::text_role( + ui, + TypeRole::BodySmall, + false, + catalog.text(Key::DownloadOptionsLoaderVersionsLoading), + ui.color(Role::OnSurfaceVariant), + ), + // 取不到 / 一条都没有：原因已经在上面那行 `problem` 里说清，这里不再重复。 + LoaderVersionsView::Failed(_) => frame::gap(0.0), + LoaderVersionsView::Ready(items) if items.is_empty() => frame::gap(0.0), + LoaderVersionsView::Ready(items) => { + let mut list = Menu::new().width(Length::Fill); + for item in items { + let mut entry = + MenuItem::new(item.as_str(), Message::SetLoaderVersion(item.clone())); + if *item == options.loader_version { + entry = entry.selected(); + } + list = list.item(entry); + } + scrollable(menu(ui, list)) + .height(Length::Fixed(ui.space(Space::X4) * VERSION_ROWS)) + .style(frame::scroll_style(ui)) + .into() + } + } +} + +/// 「安装」：不兼容 / 列表没到位 / 已装 都按下不去（禁用态保留几何，只清消息）。 +fn confirm<'a>(ui: &'a Ui, catalog: Catalog, options: &'a OptionsView) -> Element<'a, Message> { + if options.installed { + return buttons::outlined(ui, Button::disabled(catalog.text(Key::DownloadInstalled))); + } + if !options.can_confirm { + return buttons::outlined(ui, Button::disabled(catalog.text(Key::DownloadInstall))); + } + buttons::filled( + ui, + Button::new( + catalog.text(Key::DownloadInstall), + Message::InstallVersion(options.version.clone()), + ) + .leading(IconKind::Download), + ) +} diff --git a/crates/app-iced/src/pages/download/rails.rs b/crates/app-iced/src/pages/download/rails.rs new file mode 100644 index 0000000..0aa3b8d --- /dev/null +++ b/crates/app-iced/src/pages/download/rails.rs @@ -0,0 +1,375 @@ +//! 版本管理页的**三栏装配**：类型栏 + 主版本栏 + 列表列（宽档不够时退回顶部 chips）。 +//! +//! ## 三栏各自的内容 +//! +//! | 栏 | 画什么 | 交互 | +//! |---|---|---| +//! | 版本类型（第一栏） | 折叠开关 + 四个类型项（原顶部 tabs 的四个 chip，语义一字不改） | [`Message::SetCategory`]（真指令：`AppCommand::ListVersions`） | +//! | 主版本（第二栏） | 「全部版本」+ 快照里出现的每个主版本桶（[`super::group`]） | [`Message::SelectMajor`]（纯视图态） | +//! | 列表 / 内容（第三栏） | 搜索条 + 命中数 + 计数头 + 版本行 + 底部安装面板 | [`Message::SetVersionQuery`] / 选版本 / 安装 | +//! +//! ## 宽度不在这里拍 +//! +//! 两条栏的宽度来自 [`VersionRails`]（宽档裁决，见 `pages/layout/rails.rs` 的数值表）。 +//! 本文件只做两件事：把裁决出来的数字用上、把「用户手动折叠类型栏」这条覆盖叠上去。 +//! +//! ## 为什么搜索条在第三栏而不是横跨三栏 +//! +//! 搜索过滤的对象是**第三栏的列表**；横跨三栏会让人以为它也在搜侧栏里的类型。放进列表列顶部， +//! 「输入 → 下面的行变少」这条因果在视觉上就是同一条竖线；命中数是这条因果的读数，紧贴右侧。 +//! +//! ## 键盘可达 +//! +//! 两层侧栏的每一项都是真组件按钮（`navigation::list_item` / `navigation::tabs` / +//! `buttons::icon`）：焦点由 iced 的焦点系统给，Tab 依次走「类型栏 → 主版本栏 → 搜索框 → 版本行 → +//! 安装」，Enter 激活。页面不自己写焦点环（那是组件的状态层）。 + +use iced::widget::tooltip::Position; +use iced::widget::{column, container, row, scrollable, tooltip}; +use iced::{Alignment, Element, Length, Padding}; + +use unlucky_design::color::Role; +use unlucky_design::elevation::MaterialLayer; +use unlucky_design::icons::IconKind; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; + +use unlucky_i18n::{Catalog, Key}; + +use crate::app::components::buttons::{self, IconVariant}; +use crate::app::components::navigation::list_item::{list_item, ListItem}; +use crate::app::components::navigation::tabs::{tabs, Tab, Tabs}; +use crate::app::components::selection::{chip, Chip}; +use crate::theme::Ui; + +use super::super::frame; +use super::super::layout::{VersionRails, RAIL_ICON_WIDTH}; +use super::super::Message; +use super::model::{Category, Download}; +use super::{group, rows}; + +/// 类型栏里一项的图标。 +/// +/// 图标语汇只有 28 个描边字形（没有 `History` / `Camera`），所以借用： +/// **全部 = 网格、正式版 = 勾、预览版 = 刷新、远古版 = 档案袋**。已登记为偏离。 +pub(super) const fn category_icon(category: Category) -> IconKind { + match category { + Category::All => IconKind::Instances, + Category::Release => IconKind::Check, + Category::Snapshot => IconKind::Refresh, + Category::Ancient => IconKind::Folder, + } +} + +/// 三栏装配（`Wide` / `Narrow` / `Compact` 三档共用）。 +pub(super) fn three_column<'a>( + ui: &'a Ui, + catalog: Catalog, + model: &'a Download, + rails: VersionRails, +) -> Element<'a, Message> { + row![ + panel( + ui, + rails.type_rail, + type_rail(ui, catalog, model, rails.type_rail) + ), + panel( + ui, + rails.major_rail, + major_rail(ui, catalog, model, rails.major_rail) + ), + container(rows::content(ui, catalog, model)) + .width(Length::Fixed(rails.list)) + .height(Length::Fill), + ] + .spacing(super::super::layout::rails::RAIL_GAP) + .width(Length::Fill) + .height(Length::Fill) + .into() +} + +/// 一条侧栏的外壳：固定宽 + 面板底色 + 独立滚动（栏内内容不横向挤）。 +fn panel<'a>( + ui: &'a Ui, + width: f32, + content: impl Into>, +) -> Element<'a, Message> { + container(scrollable(content).height(Length::Fill).style(frame::scroll_style(ui))) + .width(Length::Fixed(width)) + .height(Length::Fill) + // 水平不留内边距：140 宽里 `ListItem` 自己的 16+16 已经够，再多 8 会把 `Snapshot` 切掉 + // （首轮出图实测「Snapsh」）。垂直留 8 让第一项不贴顶。 + // + // 底色取 `Card` 层（`SurfaceContainerLow`，比页面 Canvas 高一档）：首轮出图用的是 Canvas， + // 两条栏和页面底色一模一样 ⇒ 读起来像「一堆文字浮在左边」，不像两条侧栏。 + .padding(Padding::from([ui.space(Space::X2), 0.0])) + .style(move |_theme| frame::filled(ui.layer(MaterialLayer::Card))) + .into() +} + +/// 第一栏：版本类型（`140` 展开 / `64` 图标条）。 +fn type_rail<'a>( + ui: &'a Ui, + catalog: Catalog, + model: &'a Download, + width: f32, +) -> Element<'a, Message> { + // 宽度 ≤ 图标条宽 ⇒ 只画图标。用户手动折叠与窄档折叠走同一条判据（不另设开关）。 + let icon_only = width <= RAIL_ICON_WIDTH; + + let mut body = column![].spacing(ui.space(Space::X1)).width(Length::Fill); + let fold = fold_action(ui, model, icon_only); + if icon_only { + body = body.push( + container(fold) + .width(Length::Fill) + .align_x(Alignment::Center), + ); + } else { + body = body.push(rail_title(ui, catalog.text(Key::VersionRailTitle), fold)); + } + + for category in Category::ALL { + let selected = category == model.category; + let label = catalog.text(category.label_key()); + let press = Message::SetCategory(category); + + body = body.push(if icon_only { + // 图标条：40×40 图标按钮（命中区 48 由栏内留白补足），选中 = `Tonal`。 + // 64 宽放不下标签，所以每一项都挂 tooltip（复审建议）：四个图标既不说话也没有标题时， + // 用户只能靠猜。tooltip 的容器色/圆角走令牌，不新造样式。 + container(labeled(ui, label, category_icon(category), selected, press)) + .width(Length::Fill) + .align_x(Alignment::Center) + .into() + } else { + let mut item = ListItem::new(label, press).leading(category_icon(category)); + if selected { + item = item.selected(); + } + list_item(ui, item) + }); + } + + body.into() +} + +/// 带 tooltip 的图标项（图标条用）。tooltip 位置在右侧——它是竖栏，右边就是内容区， +/// 弹在下面会盖住下一项。 +fn labeled<'a>( + ui: &'a Ui, + label: &'a str, + kind: IconKind, + selected: bool, + press: Message, +) -> Element<'a, Message> { + let button = buttons::icon(ui, select_variant(selected), kind, Some(press), None); + tooltip( + button, + container(frame::text_role( + ui, + TypeRole::BodySmall, + false, + label, + ui.color(Role::OnSurface), + )) + .padding(ui.space(Space::X2)) + .style(move |_theme| frame::filled(ui.layer(MaterialLayer::Overlay))), + Position::Right, + ) + .into() +} + +/// 选中态 → 图标按钮的三式（`Tonal` = 当前项，与 ListItem 的 `SecondaryContainer` 同色系）。 +fn select_variant(selected: bool) -> IconVariant { + if selected { + IconVariant::Tonal + } else { + IconVariant::Standard + } +} + +/// 折叠 / 展开类型栏的图标按钮（`Sidebar` 字形；折叠中 = `Tonal`）。 +fn fold_action<'a>(ui: &'a Ui, model: &Download, icon_only: bool) -> Element<'a, Message> { + // 已经被宽度压成图标条时不再给开关：那时点它也不会变宽（档位说了算）， + // 一个按了没反应的按钮正是 D30 判 p1 的那种假控件。 + if icon_only && !model.type_rail_folded { + return frame::gap(ui.metrics().nav_item_gap); + } + buttons::icon( + ui, + select_variant(model.type_rail_folded), + IconKind::Sidebar, + Some(Message::ToggleTypeRail), + None, + ) +} + +/// 栏标题（`LabelMedium` + `OnSurfaceVariant`，与列表计数头同一档字级）。 +/// +/// 高度固定成 `control_height`（40 = 图标按钮的边长）：两条栏的标题必须**横向对齐**， +/// 而第一栏标题右侧有个 40 高的折叠按钮、第二栏没有。不固定高度的话两行标题会差 12px。 +fn rail_title<'a>( + ui: &'a Ui, + title: &'a str, + action: Element<'a, Message>, +) -> Element<'a, Message> { + container( + row![ + container(frame::text_role( + ui, + TypeRole::LabelMedium, + false, + title, + ui.color(Role::OnSurfaceVariant), + )) + .width(Length::Fill), + action, + ] + .width(Length::Fill) + .align_y(Alignment::Center) + .padding(Padding::from([0.0, ui.space(Space::X2)])), + ) + .height(Length::Fixed(ui.metrics().control_height)) + .align_y(Alignment::Center) + .into() +} + +/// 第二栏：主版本桶（第一项永远是「全部版本」；没有主版本概念的版本不单独占一项）。 +fn major_rail<'a>( + ui: &'a Ui, + catalog: Catalog, + model: &'a Download, + width: f32, +) -> Element<'a, Message> { + let icon_only = width <= RAIL_ICON_WIDTH; + + let mut body = column![].spacing(ui.space(Space::X1)).width(Length::Fill); + if !icon_only { + body = body.push(rail_title( + ui, + catalog.text(Key::VersionMajorTitle), + frame::gap(ui.metrics().nav_item_gap), + )); + } + + for entry in major_entries(catalog, model) { + body = body.push(major_item(ui, entry.label, entry.key, entry.selected)); + } + + body.into() +} + +/// 第二级侧栏的一项（「全部版本」与每个主版本桶共用一套结构，好让**两条渲染路径** +/// ——竖栏与 chips 行 —— 都用同一份数据，测试也只钉这一份）。 +/// +/// 字段全部**借**模型里的桶标签与目录里的静态串：这两条渲染路径都要把标签塞进 iced 控件树， +/// 借本地的 `String` 会让整棵树的生命周期塌到函数作用域里（E0515）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(super) struct MajorEntry<'a> { + /// 选中它要发的键（`None` = 「全部版本」） + pub key: Option<&'a str>, + /// 画出来的标签 + pub label: &'a str, + /// 此刻是否选中（**按生效值算**：搜索期间恒为「全部」，见 `group::bucket_selected`） + pub selected: bool, +} + +/// 第二级侧栏要画的全部项：`[全部版本, 1.21, 1.20, …]`，顺序 = 桶的版本序。 +/// +/// 抽成纯函数是为了让「最后一个桶可点」这件事**可断言**（复审 P2-2 的要求）： +/// 竖栏与 chips 行都从这一份数据画，chips 行外面还套了横向滚动，所以「画得出来」= 「够得着」。 +/// 返回 `Vec` 而不是迭代器：调用方两处都要 len（chips 的宽度预算）与随机访问。 +pub(super) fn major_entries<'a>(catalog: Catalog, model: &'a Download) -> Vec> { + let mut entries = vec![MajorEntry { + key: None, + label: catalog.text(Key::VersionMajorAll), + selected: group::bucket_selected(model, None), + }]; + + for bucket in &model.buckets { + // `None` 桶 = 远古版那类没有主版本的版本：第二级只有一个「全部」，不画空桶 + let Some(key) = bucket.key.as_deref() else { + continue; + }; + entries.push(MajorEntry { + key: Some(key), + label: key, + selected: group::bucket_selected(model, Some(key)), + }); + } + + entries +} + +/// 主版本的一项：`ListItem` 单行（64 宽里 `1.21` 仍完整——`BodyLarge` 4 字符 ≈ 32px ≤ 64−32 内边距）。 +fn major_item<'a>( + ui: &'a Ui, + label: &'a str, + key: Option<&str>, + selected: bool, +) -> Element<'a, Message> { + let mut item = ListItem::new(label, Message::SelectMajor(key.map(str::to_string))); + if selected { + item = item.selected(); + } + list_item(ui, item) +} + +/// 顶部 chips（可用宽 < 600 时三栏不成立：类型退回 Primary tabs，主版本变成 Secondary chips 行）。 +/// +/// 与三栏档**同源**：同一批 [`Category`] / 同一批主版本桶 / 同两条消息，不是另造一套筛选状态。 +pub(super) fn stacked_chips<'a>( + ui: &'a Ui, + catalog: Catalog, + model: &'a Download, +) -> Element<'a, Message> { + let mut types = Tabs::primary(); + for category in Category::ALL { + let mut tab = Tab::new( + catalog.text(category.label_key()), + Message::SetCategory(category), + ); + if category == model.category { + tab = tab.selected(); + } + types = types.tab(tab); + } + + // 主版本 chips：**从同一份 `major_entries` 画**，并且整行套横向滚动（复审 P2-2）。 + // + // 为什么必须能滚：真实清单里 `Release` 就有 ~20 个桶（1.21…1.7），chips 档的可用宽不到 600、 + // 一行只放得下 5~6 个。没有横向滚动时后面的桶**永远点不到**——而这正是「主版本下拉」要解决的 + // 那件事（设计系统里没有 dropdown 组件，所以用可横向滚动的 chips 行承担同一职责）。 + let mut majors = row![] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Center); + for entry in major_entries(catalog, model) { + majors = majors.push(chip( + ui, + Chip::filter( + entry.label, + entry.selected, + Message::SelectMajor(entry.key.map(str::to_string)), + ), + )); + } + + let strip = scrollable(majors) + .direction(scrollable::Direction::Horizontal( + scrollable::Scrollbar::new() + .width(frame::SCROLLBAR_WIDTH) + .scroller_width(frame::SCROLLBAR_WIDTH) + .margin(frame::SCROLLBAR_MARGIN), + )) + .height(Length::Fixed( + ui.metrics().control_height + ui.space(Space::X2), + )) + .style(frame::scroll_style(ui)); + + column![tabs(ui, types), strip] + .spacing(ui.space(Space::X2)) + .width(Length::Fill) + .into() +} diff --git a/crates/app-iced/src/pages/download/rows.rs b/crates/app-iced/src/pages/download/rows.rs new file mode 100644 index 0000000..31f6bc2 --- /dev/null +++ b/crates/app-iced/src/pages/download/rows.rs @@ -0,0 +1,291 @@ +//! 列表列：搜索条 + 计数头 + **单行**版本行 + 底部安装面板。 +//! +//! ## 这一列的职责边界 +//! +//! | 位置 | 画什么 | 消息 | +//! |---|---|---| +//! | 搜索条 | 真实控件的 `search_bar`（56 高、药丸）+ 清空按钮 + 命中数 | [`Message::SetVersionQuery`] / [`Message::ClearVersionQuery`] | +//! | 计数头 | `{count} versions`（`LabelMedium` + `OnSurfaceVariant`，与实例页列表头同一个语言） | 无 | +//! | 列表 | `ListItem` + 三列短文本 + 尾随图标按钮 | [`Message::SelectVersion`] / [`Message::InstallVersion`] | +//! | 面板 | 见 [`super::install`]（M105 的安装选项区**不在这里**） | — | +//! +//! ## 版本行为什么必须是**单行** +//! +//! 任务硬约束：列表列最窄 424（行宽下限），此时「版本号 + 类型 + 日期 + 安装按钮」四样仍要在 +//! 一行里。所以：版本号那一格是 `ListItem`（它自己的 `Wrapping::None` 保证不折行，超长由外层 +//! clip 切掉），类型 / 日期 / 安装按钮三格是**定宽**（[`super::super::layout::rails`] 的音阶）。 +//! 折行的唯一可能来源是定宽格子挤爆容器——那条由列表列下限 424 挡住（`layout/rails/tests.rs` +//! 的扫描断言）。 +//! +//! ## 搜索的三条口径 +//! +//! | 情形 | 画什么 | 为什么 | +//! |---|---|---| +//! | 有命中 | 列表照常，侧栏**位置不动**，搜索条右侧显示「N 个匹配」 | 命中数是「我搜的词有货」的读数，不是分页读数 | +//! | 一个都不命中（跨类型也没有） | [`super::states::no_match`]：一句「没有匹配」+ 一句「换短一点的片段」 | 白屏会让人以为列表坏了 | +//! | 有命中但都不在当前类型 | [`super::states::elsewhere`]：说清「有 N 个在别的类型里」+ 一个「看全部类型」按钮 | 否则用户会以为自己搜错了 | +//! +//! ## 行距归零（M102，与本页的单行版本行同时成立） +//! +//! M102 把列表行距归零：原先页面在 `ListItem` 的可视高度之外又加了 `Space::X1`（4），行节奏 +//! 与可视高度除不尽，实例页复现成「末行被卡片底边切半行」（视觉复审 ②）。规则：行距只由 +//! 组件自己的几何决定，`Space` 里也没有 0 这一档 ⇒ `list()` 里**不写** `.spacing(…)`。 +//! 本页的行是 44 的单行档，同样不加行距；[`ROW_GAP`] 只用在**行内**那三个格子的间距上。 + +use iced::widget::{column, container, row, scrollable}; +use iced::{Alignment, Element, Length, Padding}; + +use unlucky_design::color::Role; +use unlucky_design::icons::IconKind; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; + +use unlucky_i18n::{Catalog, Key}; + +use crate::app::components::buttons::{self, IconVariant}; +use crate::app::components::divider; +use crate::app::components::inputs::{search_bar, SearchBar}; +use crate::app::components::navigation::list_item::{list_item, ListItem}; +use crate::theme::Ui; + +use super::super::frame; +use super::super::layout::rails::{LIST_DATE_WIDTH, LIST_KIND_WIDTH, ROW_GAP, ROW_ICON_BUTTON}; +use super::super::Message; +use super::model::{Download, VersionRow}; +use super::{install, states}; + +/// 列表列（三栏档与 chips 档共用一份）。 +pub(super) fn content<'a>( + ui: &'a Ui, + catalog: Catalog, + model: &'a Download, +) -> Element<'a, Message> { + let visible = visible(model); + + let body: Element<'a, Message> = if model.no_match() { + states::no_match(ui, catalog) + } else if model.only_elsewhere() { + states::elsewhere(ui, catalog, model.hits) + } else if visible.is_empty() { + states::empty(ui, catalog) + } else { + list(ui, catalog, model, &visible) + }; + + let tail: Element<'a, Message> = if model.install.is_some() { + column![divider::full(ui), install::panel(ui, catalog, model)] + .spacing(ui.space(Space::X3)) + .width(Length::Fill) + .into() + } else { + install::panel(ui, catalog, model) + }; + + column![ + search_row(ui, catalog, model), + divider::full(ui), + head(ui, catalog, visible.len()), + body, + tail, + ] + .spacing(ui.space(Space::X2)) + .width(Length::Fill) + .height(Length::Fill) + .into() +} + +/// 搜索条 + 清空按钮 + 命中数（三者一行；命中数只在有查询词时出现）。 +pub(super) fn search_row<'a>( + ui: &'a Ui, + catalog: Catalog, + model: &'a Download, +) -> Element<'a, Message> { + let bar = search_bar( + ui, + SearchBar::new(model.query.as_str()) + .placeholder(catalog.text(Key::VersionSearchPlaceholder)), + Message::SetVersionQuery, + ); + + let mut line = row![container(bar).width(Length::Fill)] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Center) + .width(Length::Fill); + + if model.has_query() { + // 命中数是**跨类型**的读数（`Download::hits`），所以它在「当前分类没命中」时也照画 + line = line.push(frame::text_role_owned( + ui, + TypeRole::LabelMedium, + false, + hits_text(catalog, model.hits), + ui.color(Role::OnSurfaceVariant), + )); + line = line.push(buttons::icon( + ui, + IconVariant::Standard, + IconKind::Close, + Some(Message::ClearVersionQuery), + None, + )); + } + + line.into() +} + +/// 命中数的文案：`1` 与 `>1` 是两条 key（英文的 `1 matches` 是错的，复审 P2-4）。 +/// +/// 中文两侧都是「个匹配」，但**不能**因此只留一条 key：英文的复数规则要在目录里可读， +/// 而且将来加第三种语言时这条分支已经在那儿了。 +pub(super) fn hits_text(catalog: Catalog, count: usize) -> String { + let key = if count == 1 { + Key::VersionSearchHitsOne + } else { + Key::VersionSearchHits + }; + catalog.render(key, &[("count", &count.to_string())]) +} + +/// 「命中在别的类型里」的正文（同样单复数两条 key）。 +pub(super) fn elsewhere_text(catalog: Catalog, count: usize) -> String { + let key = if count == 1 { + Key::VersionSearchElsewhereOne + } else { + Key::VersionSearchElsewhere + }; + catalog.render(key, &[("count", &count.to_string())]) +} + +/// 计数头（`LabelMedium`）：一行 = 一个 key，数字走占位符，不拼片段。 +pub(super) fn head<'a>(ui: &'a Ui, catalog: Catalog, count: usize) -> Element<'a, Message> { + frame::text_role_owned( + ui, + TypeRole::LabelMedium, + false, + catalog.render(Key::DownloadCount, &[("count", &count.to_string())]), + ui.color(Role::OnSurfaceVariant), + ) +} + +/// 当前可见的行：先按分类（模型已过滤），再按第二级侧栏**此刻生效**的主版本桶。 +/// +/// 桶的生效值来自 [`super::group::active_bucket`]：搜索期间它恒为「全部」，于是 +/// 「命中数说 N 个、列表却 0 行」这种自相矛盾在结构上不可能出现（复审 P2-1）。 +pub(super) fn visible(model: &Download) -> Vec<&VersionRow> { + match super::group::active_bucket(model) { + None => model.rows.iter().collect(), + Some(key) => model + .rows + .iter() + .filter(|entry| entry.major().as_deref() == Some(key)) + .collect(), + } +} + +/// 版本行列表（**独立滚动**：只有列表滚，安装面板钉在底部不跟着滚）。 +fn list<'a>( + ui: &'a Ui, + catalog: Catalog, + model: &'a Download, + visible: &[&'a VersionRow], +) -> Element<'a, Message> { + let entries = column( + visible + .iter() + .map(|entry| version_row(ui, catalog, model, entry)) + .collect::>(), + ) + // M102：行距归零（见模块文档），只留横向留白 + .padding(Padding::from([0.0, ui.space(Space::X2)])) + .width(Length::Fill); + + scrollable(entries) + .direction(scrollable::Direction::Vertical( + scrollable::Scrollbar::new() + .width(frame::SCROLLBAR_WIDTH) + .scroller_width(frame::SCROLLBAR_WIDTH) + .margin(frame::SCROLLBAR_MARGIN), + )) + .height(Length::Fill) + .style(frame::scroll_style(ui)) + .into() +} + +/// 一行：`ListItem`（版本号，可点选）+ 类型 + 日期 + 安装图标按钮（**四样同一行**）。 +/// +/// 点版本号 = [`Message::SelectVersion`]（页面内选中，不 dispatch）；点尾随按钮 = +/// [`Message::InstallVersion`]。已装的版本给勾 + 禁用按钮（不重复安装）。 +fn version_row<'a>( + ui: &'a Ui, + catalog: Catalog, + model: &Download, + entry: &'a VersionRow, +) -> Element<'a, Message> { + let mut item = ListItem::new(entry.id.as_str(), Message::SelectVersion(entry.id.clone())) + .leading(IconKind::Download); + + if entry.installed { + item = item.trailing(IconKind::Check); + } + if model.selected.as_deref() == Some(entry.id.as_str()) { + item = item.selected(); + } + + // 版本号那一格吃掉剩下的宽（`ListItem` 自己是 `Wrapping::None`：再长也**不折行**， + // 由外层 clip 切掉）。定宽的三格因此永远落在右边，行宽下限 424 保证它们不会被挤出容器。 + row![ + container(list_item(ui, item)).width(Length::Fill), + cell( + ui, + catalog.text(super::model::kind_label_key(entry.kind)), + LIST_KIND_WIDTH + ), + cell(ui, entry.released.as_str(), LIST_DATE_WIDTH), + install_action(ui, entry), + ] + .spacing(ui.space(ROW_GAP)) + .align_y(Alignment::Center) + .width(Length::Fill) + .into() +} + +/// 一格定宽文本（`LabelMedium` + `OnSurfaceVariant`；单行，超长由外层 clip）。 +fn cell<'a>(ui: &'a Ui, text: &'a str, width: f32) -> Element<'a, Message> { + container(frame::text_role( + ui, + TypeRole::LabelMedium, + false, + text, + ui.color(Role::OnSurfaceVariant), + )) + .width(Length::Fixed(width)) + .into() +} + +/// 行尾的安装按钮：已装 → `Check`（`Primary`）；未装 → `Download` 图标按钮（命中区 40/48）。 +/// +/// 「本页唯一实心 accent」留在底部面板那个带文字的「安装」按钮上（rubric K2），行内用标准图标按钮： +/// 一行一个实心药丸会让列表变成一排强调色。 +fn install_action<'a>(ui: &'a Ui, entry: &'a VersionRow) -> Element<'a, Message> { + if entry.installed { + return container(frame::glyph( + IconKind::Check, + ui.color(Role::Primary), + frame::ICON_PX, + )) + .width(Length::Fixed(ROW_ICON_BUTTON)) + .align_x(Alignment::Center) + .into(); + } + + container(buttons::icon( + ui, + IconVariant::Standard, + IconKind::Download, + Some(Message::InstallVersion(entry.id.clone())), + None, + )) + .width(Length::Fixed(ROW_ICON_BUTTON)) + .align_x(Alignment::Center) + .into() +} diff --git a/crates/app-iced/src/pages/download/rows/tests.rs b/crates/app-iced/src/pages/download/rows/tests.rs new file mode 100644 index 0000000..e05ab31 --- /dev/null +++ b/crates/app-iced/src/pages/download/rows/tests.rs @@ -0,0 +1,41 @@ +//! 列表列的两条判据：**单行**（四样挤得下）与**搜索框真的在**（不是摆样子）。 + +use crate::pages::layout::rails::{ + version_list_min_width, version_row_min_width, LIST_DATE_WIDTH, LIST_KIND_WIDTH, ROW_GAP, + ROW_ICON_BUTTON, +}; + +/// 行宽下限 424 之下，四样东西仍在一行里（并留出够放 `1.21.9-pre3` 的版本号格）。 +/// +/// 抓得住：有人把类型 / 日期 / 按钮的格子改宽（改到 424 放不下时这条红），或者把行宽下限调小。 +/// 抓不住：真的渲染出来会不会折行（`ListItem` 的 `Wrapping::None` 是组件层的事，成图在报告里）。 +#[test] +fn the_version_row_still_fits_on_one_line_at_the_floor() { + let floor = version_list_min_width(); + assert_eq!(floor, 424.0, "行宽下限就是既有的 424"); + + let needed = version_row_min_width(); + assert!( + needed <= floor, + "四样固定格加起来要 {needed}，超过行宽下限 {floor} 就得折行" + ); + + // 版本号那一格在最窄情况下还剩多少 + let label_room = floor - LIST_KIND_WIDTH - LIST_DATE_WIDTH - ROW_ICON_BUTTON - 3.0 * ROW_GAP.dp(); + assert!( + label_room >= 176.0, + "版本号那一格只剩 {label_room}，`1.21.9-pre3`（11 字符）会被切" + ); +} + +/// 搜索条出现在列表列里（源码层面钉住：「有搜索框」这件事不能悄悄被删掉）。 +/// +/// 抓得住：有人把搜索条从列表列里拿掉（那一整块需求就没了）。 +/// 抓不住：搜索条是否**生效**（效果由 `download/tests.rs` 的跨类型命中数断言与出图负责）。 +#[test] +fn the_search_bar_is_actually_mounted() { + let source = include_str!("../rows.rs"); + assert!(source.contains("search_bar("), "搜索条没装"); + assert!(source.contains("Message::SetVersionQuery"), "搜索条不产生查询消息"); + assert!(source.contains("Message::ClearVersionQuery"), "搜索条没有清空入口"); +} diff --git a/crates/app-iced/src/pages/download/states.rs b/crates/app-iced/src/pages/download/states.rs new file mode 100644 index 0000000..42215b3 --- /dev/null +++ b/crates/app-iced/src/pages/download/states.rs @@ -0,0 +1,164 @@ +//! 占位状态（加载 / 空）：**同一套占位规则——内容在可用区居中**（M94 r1 / P2-1）。 +//! +//! | 状态 | 条件（都能从快照推出来） | 画什么 | +//! |---|---|---| +//! | 加载 | `model.is_loading()`：快照里还没有版本列表 | 标题 + 一句说明（**没有任何进度形状**） | +//! | 空 | `model.is_empty()`：列表拉到了，但过滤后一行不剩 | 真 [`empty_state`]（图标块 96 + 24 标题 + 说明 + 刷新 CTA） | +//! +//! ## 为什么是「都居中」（P2-1） +//! +//! `components::feedback::empty_state` 的既有口径（`12b §15.4`）就是「内容在可用区居中」； +//! 加载态原先贴顶，等于同一个页面里两套占位规则，两态互切时内容会纵向跳一次。所以本轮把加载态 +//! 也放进同一条规则里。**有数据时列表仍然贴顶**——那是有内容的状态，不属于占位规则。 +//! +//! ## 为什么加载态没有进度条（P2-3） +//! +//! 页面**没有帧订阅**（`app/subscription.rs` 的 `needs_frames` 归 app 层），所以 +//! `Progress::indeterminate(phase)` 拿到的是一个**静止的**相位——用户看到的是「17% 卡住」。 +//! 与其留一个「看起来有进度但不动」的控件，不如给一句明确的「正在加载」文字；等 app 层真有了 +//! 帧订阅再来带动画（那时这里换回 indeterminate 才有意义）。 +//! +//! ## 文案口径（P2-2） +//! +//! 只说页面真能做到的动作：说明里那句「点右上角的刷新」对应页头那个真的 Refresh 按钮 +//! （`Message::Action(Action::RefreshSources)`）；没有写「稍后会自动重试」这种 UI 做不到的承诺。 + +use iced::widget::{column, container}; +use iced::{Alignment, Element, Length}; + +use unlucky_design::color::Role; +use unlucky_design::icons::IconKind; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; + +use unlucky_i18n::{Catalog, Key}; + +use crate::app::components::buttons::{self, Button}; +use crate::app::components::feedback::{empty_state, EmptyState}; +use crate::theme::Ui; + +use super::super::frame; +use super::super::{Action, Message}; +use super::model::Category; + +/// 空态图标块边长（12b §15.1：**96×96**，与 `components::feedback::EmptyState` 内部同一个项目值； +/// 那里是 `frame::pieces::EMPTY_ICON_BLOCK`（`pub(super)`，本模块取不到，只能同值声明一次）。 +const EMPTY_ICON_BLOCK: f32 = 96.0; + +/// 两个占位状态共用的外壳：水平 + 垂直都居中（见模块文档的两条理由）。 +fn centered<'a>(content: impl Into>) -> Element<'a, Message> { + container(content) + .width(Length::Fill) + .height(Length::Fill) + .align_x(Alignment::Center) + .align_y(Alignment::Center) + .into() +} + +/// 加载态：一句「正在加载」+ 一句这个页面真能做的事（点刷新）。 +pub(super) fn loading<'a>(ui: &'a Ui, catalog: Catalog) -> Element<'a, Message> { + centered( + column![ + frame::text_role_centered( + ui, + TypeRole::TitleMedium, + true, + catalog.text(Key::DownloadLoading), + ui.color(Role::OnSurface), + ), + frame::text_role_centered( + ui, + TypeRole::BodySmall, + false, + catalog.text(Key::DownloadLoadingHint), + ui.color(Role::OnSurfaceVariant), + ), + ] + .spacing(ui.space(Space::X3)) + .width(Length::Fill) + .align_x(Alignment::Center), + ) +} + +/// 空态（真 `EmptyState`：CTA 就是标准 Filled 按钮，走按钮家族）。 +pub(super) fn empty<'a>(ui: &'a Ui, catalog: Catalog) -> Element<'a, Message> { + centered(empty_state( + ui, + EmptyState::new( + IconKind::Download, + catalog.text(Key::DownloadEmptyTitle), + catalog.text(Key::DownloadEmptyBody), + ) + .action( + catalog.text(Key::DownloadRefresh), + Message::Action(Action::RefreshSources), + ), + )) +} + +/// 搜索**一个都不命中**（跨类型也没有）：说「没有匹配」+ 一句「换短一点的片段」+ 清空入口。 +/// +/// 与 [`empty`] 分开的理由：那个是「这个分类里没有版本」，这个是「这个词没有任何版本」—— +/// 两种情况该给的下一步动作不同（前者换分类/刷新，后者改搜索词）。 +pub(super) fn no_match<'a>(ui: &'a Ui, catalog: Catalog) -> Element<'a, Message> { + centered(empty_state( + ui, + EmptyState::new( + IconKind::Search, + catalog.text(Key::VersionSearchEmptyTitle), + catalog.text(Key::VersionSearchEmptyBody), + ) + .action( + catalog.text(Key::VersionSearchClear), + Message::ClearVersionQuery, + ), + )) +} + +/// **有命中但不在当前分类**：说清「N 个在别的类型里」+ 一个「看全部类型」的出口。 +/// +/// 不给出口的话，用户只能自己猜「是不是要切到快照 tab」——这正是本条的验收口径。 +/// +/// 标题**不再复用命中数那条 key**（复审 P2-4）：原来同一个数在同屏报三遍 +/// （右上角「1 matches」+ 标题「1 matches」+ 正文「1 versions match」），而且单数时英文是错的。 +/// 现在标题是一条固定文案，正文的单复数由 [`super::rows::elsewhere_text`] 选 key。 +pub(super) fn elsewhere<'a>(ui: &'a Ui, catalog: Catalog, hits: usize) -> Element<'a, Message> { + let title = catalog.text(Key::VersionSearchElsewhereTitle).to_owned(); + let body = super::rows::elsewhere_text(catalog, hits); + + // 手搭而不是用 `EmptyState`：它的标题/正文借 `&'a str`，而这里的句子是 `render()` 出来的 + // `String`（带命中数），借不到 `'a`。字形、字级、按钮全走同一套令牌，视觉上仍是空态。 + centered( + column![ + frame::glyph_box( + IconKind::Search, + ui.color(Role::OnSurfaceVariant), + EMPTY_ICON_BLOCK + ), + frame::text_role_owned( + ui, + TypeRole::HeadlineSmall, + false, + title, + ui.color(Role::OnSurface), + ), + frame::text_role_owned( + ui, + TypeRole::BodySmall, + false, + body, + ui.color(Role::OnSurfaceVariant), + ), + buttons::filled( + ui, + Button::new( + catalog.text(Key::VersionSearchElsewhereAction), + Message::SetCategory(Category::All), + ), + ), + ] + .spacing(ui.space(Space::X3)) + .width(Length::Fill) + .align_x(Alignment::Center), + ) +} diff --git a/crates/app-iced/src/pages/download/tests.rs b/crates/app-iced/src/pages/download/tests.rs new file mode 100644 index 0000000..a1b3e56 --- /dev/null +++ b/crates/app-iced/src/pages/download/tests.rs @@ -0,0 +1,302 @@ +//! 版本管理页的判据：**快照 → 模型 → 控件树**三段各自的断言。 +//! +//! 每条都写清「抓得住什么 / 抓不住什么」——这里只测纯转换与树能构建，**像素**由 +//! `DevDocs/artifacts/m107/` 的十张图与报告的量测表负责（同 `pages/tests.rs` 的口径）。 + +use unlucky_design::color::SchemeFlavor; +use unlucky_design::typography::Platform; +use unlucky_i18n::Lang; +use unlucky_presenter::dto::{ + AncientKind, AppEvent, CoreEvent, InstallProgressView, InstallStage, VersionCategory, + VersionKind, VersionSummary, +}; +use unlucky_presenter::state::AppState; + +use crate::theme::{Families, Ui}; + +use super::super::layout::{frame_metrics, PaneKit}; +use super::model::{Category, Download}; +use super::options::InstallDraft; + +mod i18n; + +const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", +}; + +fn ui() -> Ui { + Ui::with_platform(SchemeFlavor::Light, Platform::Windows, FAMILIES) +} + +fn version(id: &str, kind: VersionKind, installed: bool) -> VersionSummary { + VersionSummary { + id: id.to_string(), + kind, + released: "2026-09-20".to_string(), + installed, + } +} + +fn state_with(versions: Vec) -> 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; diff --git a/crates/app-iced/src/pages/download/tests/i18n.rs b/crates/app-iced/src/pages/download/tests/i18n.rs new file mode 100644 index 0000000..b5fa3ab --- /dev/null +++ b/crates/app-iced/src/pages/download/tests/i18n.rs @@ -0,0 +1,106 @@ +//! 下载页的**文案守门**（M105 从 `download/tests.rs` 搬出：那边加了安装选项的用例之后顶破 400 行）。 +//! +//! 两条各守一件事：死 key（目录里有、页面没用）与「模型说的是目录的语言」。 + +use unlucky_i18n::{Key, Lang}; +use unlucky_presenter::dto::VersionKind; + +use super::*; + +// --------------------------------------------------------------- 文案（i18n） + +/// 每个 `Download*` key 都**真的被页面引用**（死 key 守门，M94 r1 / P2-6）。 +/// +/// 复审抓到的 `DownloadSelected` 就是这条要拦的东西：目录里定义了、页面没人用。所以这里把页面 +/// 源码用 `include_str!` 编进来扫一遍。**抓不住什么也说清**：反向（引用了不存在的 key）是编译错误， +/// 不需要测试；译文对不对、两套语言都填了没由 `i18n` 自己的 `built_in_catalogs_have_every_key` 守； +/// 它只看字面出现，用宏拼 key 名能骗过它。 +#[test] +fn every_download_key_is_referenced_by_the_page() { + const SOURCES: [&str; 11] = [ + include_str!("../../download.rs"), + include_str!("../model.rs"), + // M107：分类枚举搬进 `model/category.rs`（`Category::label_key` 在那儿，漏扫会误判死 key） + include_str!("../model/category.rs"), + include_str!("../rows.rs"), + // M107：两级侧栏与分组规则（`VersionRailTitle` / `VersionMajorAll` 的落点） + include_str!("../rails.rs"), + include_str!("../group.rs"), + include_str!("../install.rs"), + include_str!("../states.rs"), + include_str!("../demo.rs"), + // M105：安装选项区的两条填页线（漏扫的话新 key 会被判成死 key） + include_str!("../options/model.rs"), + include_str!("../options/view.rs"), + ]; + + let mut checked = 0; + for key in Key::ALL + .iter() + .filter(|key| key.name().starts_with("Download") || key.name().starts_with("Version")) + { + let needle = format!("Key::{}", key.name()); + assert!( + SOURCES.iter().any(|source| source.contains(&needle)), + "{needle} 在目录里定义了，但下载页没有任何地方用它（死 key，删掉或接上）" + ); + checked += 1; + } + assert!( + checked > 20, + "下载页的 key 不该被成批删掉（只查到 {checked} 条）" + ); + assert!( + checked > 50, + "M107 之后这一页的 key（Download* + Version*）不该少于 50 条，只查到 {checked}" + ); +} + +/// 页面级的文案全部按 `Catalog` 走：中文目录出中文，英文目录出英文，**且不含 core 的中文业务串**。 +/// +/// 抓得住：页面里又出现硬编码英文/中文字面量、或把 `InstallStage::label()` / `progress.message` +/// （core 的中文串）画到界面上。 +/// 抓不住：目录里那条译文本身写错了。 +#[test] +fn the_model_speaks_the_catalog_language() { + let versions = vec![version("1.21.9", VersionKind::Release, false)]; + let state = state_with(versions); + + let en = Download::from_snapshot( + &state, + Category::All, + &InstallDraft::default(), + Lang::En.catalog(), + ); + let zh = Download::from_snapshot( + &state, + Category::All, + &InstallDraft::default(), + Lang::ZhCn.catalog(), + ); + + assert_eq!(en.rows[0].supporting, "Release · released 2026-09-20"); + assert_eq!(zh.rows[0].supporting, "正式版 · 发布于 2026-09-20"); + + let progress = InstallProgressView { + version: "1.21.9".to_string(), + stage: InstallStage::Planning, + message: "正在解析版本清单…".to_string(), + ..InstallProgressView::new() + }; + let install_en = crate::pages::download::model::InstallView::of(&progress, Lang::En.catalog()); + assert_eq!(install_en.stage_label, "Planning"); + assert_eq!(install_en.detail, "Waiting for the first file…"); + assert!( + !install_en.stage_label.contains('解'), + "core 的中文阶段串不许直接上屏" + ); + assert!( + !install_en.detail.contains('正'), + "`InstallProgressView::message` 是中文业务串，页面不许画它" + ); + + let install_zh = + crate::pages::download::model::InstallView::of(&progress, Lang::ZhCn.catalog()); + assert_eq!(install_zh.stage_label, "解析版本"); +} diff --git a/crates/app-iced/src/pages/download/tests/rails.rs b/crates/app-iced/src/pages/download/tests/rails.rs new file mode 100644 index 0000000..b575d76 --- /dev/null +++ b/crates/app-iced/src/pages/download/tests/rails.rs @@ -0,0 +1,177 @@ +//! 两层侧栏的护栏（**变异可证**）+ 三栏宽度账。 +//! +//! 从 `download/tests.rs` 拆出来：那边已经贴着 400 行硬线。 + +use unlucky_i18n::Lang; +use unlucky_presenter::dto::{AppEvent, CoreEvent, VersionKind, VersionSummary}; +use unlucky_presenter::state::AppState; + +use crate::pages::download::options::InstallDraft; +use crate::pages::download::rails::major_entries; +use crate::pages::download::{Category, Download}; +use crate::pages::layout::{ + available_width, frame_metrics, measure_cap_px, PaneKit, VersionRailTier, VersionRails, + RAIL_GAP, +}; + +/// 三栏要吃掉整条可用宽（不是 424 的居中正文列）——三个宽度档各取一个采样点。 +/// +/// 抓得住：有人把第三栏写成 `Length::Fill`（那会让三列宽度之和**超过**可用宽、右侧被挤出屏）。 +/// 抓不住：像素级对齐（出图在报告里）。 +#[test] +fn the_three_columns_spend_the_whole_available_width() { + for (window, tier) in [ + (1180.0, VersionRailTier::Wide), + (900.0, VersionRailTier::Narrow), + (700.0, VersionRailTier::Chips), + ] { + let rails = VersionRails::of(available_width(window)); + assert_eq!(rails.tier, tier, "{window} 的档位"); + if tier.is_three_column() { + let spent = rails.type_rail + rails.major_rail + rails.list + 2.0 * RAIL_GAP; + assert!( + (spent - available_width(window)).abs() < f32::EPSILON, + "{window}：三列 + 两处间距应正好等于可用宽（{spent} vs {}）", + available_width(window) + ); + } + } +} + +/// **两层侧栏都存在、且选中态真的传给列表**——M107 的护栏，改坏要红。 +/// +/// 四件事一起钉： +/// 1. 页面装配点仍调 `rails::three_column`（三栏装配是唯一入口）； +/// 2. 装配点里**两个**侧栏函数都被调用（删掉 `major_rail(` → 只剩一级侧栏 ⇒ 红）； +/// 3. 两级各自都有可点的消息（`SetCategory` / `SelectMajor`）； +/// 4. 列表的行确实按第二级选中态过滤（`rows::visible` + `selected_major`）。 +/// +/// 抓得住：删掉一层侧栏、或者让列表无视 `selected_major`（第二级点了没反应）。 +/// 抓不住：两层是否**看起来**是两层（那要出图，见报告）。 +#[test] +fn both_rail_levels_exist_and_the_selection_reaches_the_list() { + let rails_source = include_str!("../rails.rs"); + let download_source = include_str!("../../download.rs"); + let rows_source = include_str!("../rows.rs"); + + assert!( + download_source.contains("rails::three_column"), + "页面装配点不再调三栏装配" + ); + for required in ["type_rail(ui", "major_rail(ui"] { + assert!( + rails_source.contains(required), + "两层侧栏缺了一级：找不到 {required}" + ); + } + assert!( + rails_source.contains("Message::SelectMajor"), + "第二级（主版本）没有可点的消息" + ); + assert!( + rails_source.contains("Message::SetCategory"), + "第一级（版本类型）没有可点的消息" + ); + // 列表按第二级的**生效值**过滤（搜索期间放宽到「全部」，见 `group::active_bucket`）： + // 这两样只要有一样不在，第二级点了就等于没反应。 + assert!( + rows_source.contains("fn visible") && rows_source.contains("group::active_bucket"), + "列表没有按第二级选中态过滤" + ); + assert_eq!(Category::ALL.len(), 4, "第一级还是原来那四类，不许新造分类"); +} + +/// `< 600` 可用宽时两栏都退场、列表吃掉可用宽（chips 档的账）。 +#[test] +fn the_chips_tier_gives_the_whole_width_to_the_list() { + let rails = VersionRails::of(564.0); + assert_eq!(rails.tier, VersionRailTier::Chips); + assert_eq!(rails.type_rail, 0.0); + assert_eq!(rails.major_rail, 0.0); + assert_eq!(rails.list, 564.0); +} + +/// **Chips 档的最后一个桶也要够得着**（复审 P2-2）。 +/// +/// 夹具按真实清单的量级造：`1.21 … 1.0` 共 **22 个桶**（`Release` 在 MOJANG 清单里就是这个量级）。 +/// 三条一起钉： +/// 1. `major_entries` 把**每一个桶**都吐出来（含最后一个 `1.0`）——渲染两条路径都吃这一份数据； +/// 2. chips 行外面套了 `Direction::Horizontal` 的滚动（源码层，删掉那一层就够不着后面的桶）； +/// 3. 选中态按**生效值**算：搜索期间「全部版本」点亮（P2-1 的放宽）。 +/// +/// 抓得住：把 chips 行的横向滚动拿掉（第 2 条红）；或让 `major_entries` 在某个桶处截断（第 1 条红）。 +/// 抓不住：滚动条在真机上好不好拖（那要出图 + 手感，报告里登记为未验）。 +#[test] +fn every_bucket_is_reachable_in_the_chips_tier() { + let versions: Vec = (0..=21) + .rev() + .map(|minor| VersionSummary { + id: format!("1.{minor}.4"), + kind: VersionKind::Release, + released: "2026-09-20".to_string(), + installed: false, + }) + .collect(); + + let mut state = AppState::new(); + state.apply(AppEvent::Core(CoreEvent::VersionListChanged(versions))); + + let catalog = Lang::En.catalog(); + let mut model = + Download::from_snapshot(&state, Category::All, &InstallDraft::default(), catalog); + assert_eq!(model.buckets.len(), 22, "夹具应有 22 个主版本桶"); + + let entries = major_entries(catalog, &model); + assert_eq!(entries.len(), 23, "「全部版本」+ 22 个桶"); + assert_eq!( + entries.last().and_then(|entry| entry.key), + Some("1.0"), + "最后一个桶（版本序最老的那个）必须在列表里，否则它永远点不到" + ); + assert_eq!(entries[1].label, "1.21", "第一条桶是版本序最新的"); + + // 选中态按生效值：选中 1.0 时那一项点亮；搜索期间整体放宽到「全部」 + model.selected_major = Some("1.0".to_string()); + let entries = major_entries(catalog, &model); + assert!(entries.last().expect("有最后一项").selected); + state.download_query = "1.0".to_string(); + let mut searching = + Download::from_snapshot(&state, Category::All, &InstallDraft::default(), catalog); + searching.selected_major = Some("1.0".to_string()); + let entries = major_entries(catalog, &searching); + assert!(entries[0].selected, "搜索期间「全部版本」点亮（P2-1）"); + assert!( + entries.iter().skip(1).all(|entry| !entry.selected), + "搜索期间不许留下幽灵选中" + ); + + // chips 行的横向滚动是「够得着」的实现手段 + let source = include_str!("../rails.rs"); + assert!( + source.contains("Direction::Horizontal"), + "chips 档的主版本行必须可横向滚动（否则 22 个桶里大部分点不到）" + ); + assert!( + source.contains("major_entries(catalog, model)"), + "竖栏与 chips 行必须吃同一份 entries" + ); +} + +/// 宽窗下多出来的宽度归**页面块**，不归散文列（M102 订正；旧口径是「留白」）。 +/// +/// 抓得住：谁把整页块又压回 424（视觉复审 ① 的原样：块宽 = `column`，1180 下左右各留 ~300px）； +/// 抓不住：真实像素（报告里的量测表负责）。 +#[test] +fn extra_width_goes_to_the_page_block_not_to_the_prose_column() { + let metrics = frame_metrics(PaneKit::Single, 1180.0); + assert_eq!(metrics.column, measure_cap_px(), "散文列仍是行宽上限 424"); + assert_eq!( + crate::pages::frame::body_width(metrics), + metrics.available, + "页面块必须吃满可用宽度（1044），不是被居中压成 424" + ); + assert!( + metrics.available - metrics.column >= 400.0, + "两个量要分得开：块宽 1044 比散文列 424 宽出 620" + ); +} diff --git a/crates/app-iced/src/pages/download/tests/search.rs b/crates/app-iced/src/pages/download/tests/search.rs new file mode 100644 index 0000000..b6b1a78 --- /dev/null +++ b/crates/app-iced/src/pages/download/tests/search.rs @@ -0,0 +1,217 @@ +//! 搜索 × 主版本桶的一致性判据（复审 P2-1）+ 复数口径（P2-4）。 +//! +//! 这两条都是「一屏之内两句话打架」那类问题：命中数说 N 个、列表却 0 行；或者英文写 `1 matches`。 +//! 所以断言都写成**不变式**（对一张输入矩阵扫），而不是挑一个例子。 + +use unlucky_i18n::Lang; +use unlucky_presenter::dto::{AppEvent, CoreEvent, VersionKind, VersionSummary}; +use unlucky_presenter::state::AppState; + +use super::super::group; +use super::super::model::{Category, Download}; +use super::super::options::InstallDraft; +use super::super::rows; +use super::version; + +fn state_with(versions: Vec, 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..e0e5c3e --- /dev/null +++ b/crates/app-iced/src/pages/download/tests/view.rs @@ -0,0 +1,147 @@ +//! 控件树那一节：九个状态 × 四档宽度都要能构图（M105/M107 合流后 `tests.rs` 到 433 行， +//! 按 AGENTS.md §3-1 拆出来）。 +//! +//! 只测「能构建出树」——**抓不住**画出来长什么样（像素由 `DevDocs/artifacts/m107/` 的图负责）。 + +use unlucky_i18n::Lang; +use unlucky_presenter::dto::{InstallProgressView, InstallStage, VersionKind}; + +use crate::pages::download::model::{Download, InstallView, VersionRow}; +use crate::pages::download::{view, Category, Message}; +use crate::pages::layout::{frame_metrics, PaneKit}; + +use super::{ui, version}; + +/// 九个状态都能构建出控件树，且四档宽度都能构建（不 panic、消息类型对得上）。 +/// +/// 抓得住：某个状态分支漏了返回值、或消息类型接错（编译期就红）；空态/加载态忘了给内容。 +/// 抓不住：**画出来长什么样**——像素由 `DevDocs/artifacts/m107/` 的图负责。 +#[test] +fn every_state_builds_a_tree_at_every_width() { + let ui = ui(); + let catalog = Lang::En.catalog(); + + let loading = Download::loading(); + let empty = Download { + loaded: true, + ..Download::loading() + }; + let ready = Download { + options: None, + rows: vec![VersionRow::of( + &version("1.21.9", VersionKind::Release, false), + catalog, + )], + category: Category::Release, + selected: Some("1.21.9".to_string()), + install: None, + loaded: true, + // M107 的五个新字段：桶 / 查询 / 命中数 / 第二级选中 / 折叠态 + ..Download::default() + }; + + let installing = Download { + install: Some(InstallView::of( + &InstallProgressView { + version: "1.21.9".to_string(), + stage: InstallStage::Downloading, + files_done: 128, + files_total: 512, + ..InstallProgressView::new() + }, + catalog, + )), + ..ready.clone() + }; + + let failed = Download { + install: Some(InstallView::of( + &InstallProgressView { + version: "1.21.9".to_string(), + stage: InstallStage::Failed, + ..InstallProgressView::new() + }, + catalog, + )), + ..ready.clone() + }; + + // M107：搜索 / 第二级选中 / 搜不到 / 手动折叠四个新增状态的取样 + let searching = Download { + query: "1.21".to_string(), + hits: 1, + ..ready.clone() + }; + let majored = Download { + selected_major: Some("1.21".to_string()), + ..ready.clone() + }; + let no_match = Download { + query: "zzz".to_string(), + hits: 0, + ..ready.clone() + }; + let folded = Download { + type_rail_folded: true, + ..ready.clone() + }; + + // 四档宽度：1180 / 1024（Wide 门槛）/ 900（Narrow）/ 700（Chips） + for width in [1180.0, 1024.0, 900.0, 700.0] { + let metrics = frame_metrics(PaneKit::Single, width); + for model in [ + loading.clone(), + empty.clone(), + ready.clone(), + installing.clone(), + failed.clone(), + searching.clone(), + majored.clone(), + no_match.clone(), + folded.clone(), + ] { + let _: iced::Element<'_, Message> = view(&ui, metrics, &model, Lang::En); + } + } +} + +/// 安装失败的模型：可读文案 + 出口都有（不静默）。 +#[test] +fn a_failed_install_stays_visible() { + let model = InstallView::of( + &InstallProgressView { + version: "1.21.9".to_string(), + stage: InstallStage::Failed, + ..InstallProgressView::new() + }, + Lang::En.catalog(), + ); + assert!(model.failed()); + assert!(model.terminal()); + assert!(!model.running(), "失败之后不再给「取消安装」"); + assert_eq!(model.stage_label, "Install failed"); +} + +/// 演示数据自己也得守规矩（它是出图的基线）：八行、四个主版本桶、英文目录下不出现中文类型词。 +#[test] +fn the_demo_data_is_sane() { + let catalog = Lang::En.catalog(); + let demo = crate::pages::download::demo(catalog); + assert!(demo.loaded); + assert_eq!(demo.rows.len(), 8); + assert_eq!(demo.category, Category::All, "混合列表没有单个分类该亮"); + assert!(demo.query.is_empty(), "缺省演示没有搜索词"); + assert_eq!( + demo.buckets + .iter() + .map(|bucket| bucket.key.as_deref()) + .collect::>(), + vec![Some("24w"), Some("1.21"), Some("1.20"), None], + "第二级侧栏的桶顺序与内容" + ); + assert!(demo + .rows + .iter() + .all(|row| row.supporting.contains("released"))); + assert!(demo.rows.iter().all(|row| !row.supporting.contains('版'))); +} diff --git a/crates/app-iced/src/pages/frame.rs b/crates/app-iced/src/pages/frame.rs new file mode 100644 index 0000000..e78c3c2 --- /dev/null +++ b/crates/app-iced/src/pages/frame.rs @@ -0,0 +1,252 @@ +//! 页面骨架：**页头**（标题 + 副标题 + 可选操作区）+ **内容区**（列宽由 [`super::layout`] 决定） +//! + **空态位**。 +//! +//! ## 边界 +//! +//! 这里只放「页面级」的东西：页头、页边距、内容块、两列骨架、空态位的摆放。 +//! 具体控件（卡片 / 分隔线 / 文本按钮 / 图标）在 [`pieces`]，它们是**占位实现** +//! （同一份令牌，没有完整状态机），等 M75 的 `components/` 家族合入后由另一条 mission 换掉。 +//! +//! ## 对齐口径（M102）：页头标题左缘 = 正文块左缘 +//! +//! 页头带与内容区共用同一个 `gutter`（`Padding::from([0.0, metrics.gutter])` / `padding(gutter)`）， +//! 所以页头标题的左缘 = `rail 88 + gutter 24 = 112`。正文块必须从**同一条线**起： +//! +//! - 单列页用 [`body`]（贴左 + 宽 `layout::block::body_width` = pane 宽，封顶 1440）； +//! - 成段散文再套一层 [`prose`]（宽 `layout::block::prose_width` ≤424，保证一行 ≤72 字符）； +//! - 两列页的正文在 [`panes`] 的主列里，左缘 = `112 + 列表列 336 + 间隙 24 = 472`（有据的分栏，不是错位）。 +//! +//! 旧 [`single_column`] 把 424 的块**居中**摆进 1044，于是左缘 422、标题 112——视觉复审的 ① 就是这个。 +//! 它保留给设置页（`pages/settings/**`，几何归设置页线）。 +//! +//! **这三个量都在 [`super::layout::block`]（纯函数 + 单测）**；[`body`] / [`prose`] 只是把 +//! 「从哪个数建盒」写死在一处，`pages/tests.rs` 有两条**源码结构断言**盯着这两个盒子 +//! （iced 的 Element 没有几何内省，量不到摆法，只能断言「照哪个数建的」）。 +//! +//! ## 判据落点（`research/12b`） +//! +//! | 部件 | 参考 | 落点 | +//! |---|---|---| +//! | 页头 | 16.1 AppBar 高 56（登记偏离官方 64）/ 两行 84 | `LayoutMetrics::header_height` | +//! | 页头标题 | 16.4 `TitleLarge 22/28` | `Component::TopAppBar.spec().text` | +//! | 页头副标题 | 16.4 `LabelMedium 12/16` `OnSurfaceVariant` | 同上 `.support` | +//! | 空态 | 15.1 图标块 96×96 / `Large(16)`；15.2 标题 `HeadlineSmall 24`；15.3 副文案 `BodySmall 12` | `Component::EmptyState` | + +mod pieces; + +#[cfg(test)] +mod tests; + +pub use pieces::{ + card, divider, empty_state, filled, gap, glyph, glyph_box, scroll_style, text_action, + text_role, text_role_centered, text_role_owned, ICON_PX, ICON_SMALL_PX, SCROLLBAR_MARGIN, + SCROLLBAR_WIDTH, +}; + +use iced::widget::{column, container, row}; +use iced::{Alignment, Element, Length, Padding}; + +use unlucky_design::color::Role; +use unlucky_design::component_map::Component; +use unlucky_design::elevation::MaterialLayer; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; + +use crate::theme::Ui; + +use super::layout::{self, block, FrameMetrics}; +use super::Message; + +/// 页头操作区之间的间隔（`Space::X2`）。 +const HEADER_ACTION_GAP: f32 = Space::X2.dp(); + +/// 页头内容。 +pub struct Header<'a> { + /// 标题（`TitleLarge`）。 + pub title: &'a str, + /// 副标题（`LabelMedium`，给了页头就是两行高）。 + pub subtitle: Option<&'a str>, + /// 右侧操作区（text button 占位，数量 ≤3）。 + pub actions: Vec>, +} + +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() +} + +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..1a6b0f0 --- /dev/null +++ b/crates/app-iced/src/pages/frame/pieces.rs @@ -0,0 +1,333 @@ +//! 页面用的**占位控件**：卡片 / 分隔线 / 空态 / 文本按钮 / 图标 / 容器样式。 +//! +//! 全部走令牌（颜色、圆角、排版、间距、一像素线），但**没有完整状态机**—— +//! 这些是给页面骨架站稳版式用的临时件，M74/M75 的 `components/` 家族合入后由另一条 mission 替换。 +//! 每个函数都在文档里点明它对应哪个组件的档位（12b 的参考值）。 + +use iced::widget::text::LineHeight; +use iced::widget::{button, column, container, row, rule, scrollable, space, svg}; +use iced::Theme as IcedTheme; +use iced::{Alignment, Background, Border, Color, Element, Length, Padding, Pixels, Shadow}; + +use unlucky_design::color::{Role, StateLayer}; +use unlucky_design::component_map::Component; +use unlucky_design::elevation::MaterialLayer; +use unlucky_design::icons::{IconKind, IconPaint}; +use unlucky_design::shape::ShapeScale; +use unlucky_design::spacing::Space; +use unlucky_design::typography::{TypeRole, TypeStyle}; + +use crate::icons; +use crate::pages::{Action, Message}; +use crate::theme::Ui; + +/// 空态图标块边长（12b 15.1：96×96，圆角 `Large`）。 +pub(super) const EMPTY_ICON_BLOCK: f32 = 96.0; +/// 空态字形渲染尺寸（12b 15.1：图标 32~48 `[估]`，取 40）。 +pub(super) const EMPTY_ICON_GLYPH: f32 = 40.0; +/// 滚动条轨宽（视觉复审 P2-2：原来用 iced 默认的 10px，压过了列表内容）。 +/// +/// 取 6：细到不抢视线，又还在命中/可见的下限之上；滑块做成 full 圆角药丸（半径 3）。 +pub const SCROLLBAR_WIDTH: f32 = 6.0; +/// 滑块离卡片内边的留白（2px，避免贴边）。 +pub const SCROLLBAR_MARGIN: f32 = 2.0; + +/// 描边卡片（占位：M75 的 `components` 会提供真正的 `OutlinedCard`）。 +pub fn card<'a>(ui: &'a Ui, content: impl Into>) -> Element<'a, Message> { + let spec = Component::OutlinedCard.spec(); + container(content) + .width(Length::Fill) + .padding(ui.metrics().card_padding) + .style(move |_theme| container::Style { + background: Some(Background::Color(ui.layer(MaterialLayer::Card))), + border: ui.outlined(spec.shape), + ..container::Style::default() + }) + .into() +} + +/// 一像素分隔线（`OutlineVariant`，厚度取令牌）。 +pub fn divider<'a>(ui: &'a Ui) -> Element<'a, Message> { + rule::horizontal::(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` 完全解耦。 +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..4f9689e --- /dev/null +++ b/crates/app-iced/src/pages/frame/tests.rs @@ -0,0 +1,101 @@ +//! `frame` 的断言：空态 / 卡片 / 页头规格与一屏字号档。 +use super::pieces::{EMPTY_ICON_BLOCK, EMPTY_ICON_GLYPH}; +use super::*; + +use unlucky_design::color::SchemeFlavor; +use unlucky_design::shape::ShapeScale; +use unlucky_design::typography::Platform; + +use crate::pages::layout::{frame_metrics, PaneKit}; +use crate::theme::Families; + +fn ui() -> Ui { + Ui::with_platform( + SchemeFlavor::Light, + Platform::Windows, + Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", + }, + ) +} + +#[test] +fn empty_state_follows_the_12b_reference() { + // 15.1 图标块 96×96、圆角 Large(16)；15.2 标题 HeadlineSmall；15.3 副文案 BodySmall + let spec = Component::EmptyState.spec(); + assert_eq!(EMPTY_ICON_BLOCK, 96.0); + assert_eq!(spec.shape, ShapeScale::Large); + assert_eq!(spec.text, TypeRole::HeadlineSmall); + assert_eq!(ui().style(spec.text).size_px, 24.0); + assert_eq!(spec.support, Some(TypeRole::BodySmall)); + assert_eq!(ui().style(TypeRole::BodySmall).size_px, 12.0); + // 字形 32~48（[估]） + assert!((32.0..=48.0).contains(&EMPTY_ICON_GLYPH)); + const { assert!(EMPTY_ICON_GLYPH < EMPTY_ICON_BLOCK) }; +} + +#[test] +fn card_uses_the_outlined_card_spec() { + let spec = Component::OutlinedCard.spec(); + assert_eq!(spec.shape, ShapeScale::Medium); + assert_eq!(ui().radius_dp(spec.shape).top_left, 12.0); + assert_eq!(spec.text, TypeRole::TitleMedium); + assert_eq!(spec.support, Some(TypeRole::BodySmall)); +} + +#[test] +fn page_header_uses_the_two_documented_heights() { + let ui = ui(); + assert_eq!(ui.metrics().header_height(false), 56.0); + assert_eq!(ui.metrics().header_height(true), 84.0); +} + +/// 一屏字号 ≤4 档（rubric D4）。规格表来源：12b §16.4 / §15 / 3.x OutlinedCard。 +#[test] +fn every_screen_keeps_at_most_four_text_sizes() { + let ui = ui(); + + let header = ui.emphasized(Component::TopAppBar.spec().text).size_px; + let row_title = ui.style(Component::ListItem.spec().text).size_px; + let row_support = ui + .style(Component::ListItem.spec().support.unwrap()) + .size_px; + let action = ui.style(Component::TextButton.spec().text).size_px; + let body = ui.style(TypeRole::BodyMedium).size_px; + let empty_title = ui.style(Component::EmptyState.spec().text).size_px; + + let screens: [(&str, &[f32]); 3] = [ + // 实例页（list-detail 与窄窗单列）：页头 + 行标题 + 行副文案 + 操作/正文 + ("instances", &[header, row_title, row_support, action, body]), + // 设置页：页头 + 分组项/操作 + 行标签 + 行值 + 空态标题 + ( + "settings", + &[header, action, row_support, body, empty_title], + ), + // 下载 / 日志：页头 + 空态标题 + 空态副文案 + 操作 + ("empty-pages", &[header, empty_title, row_support, action]), + ]; + + for (name, sizes) in screens { + let mut unique = sizes.to_vec(); + unique.sort_by(f32::total_cmp); + unique.dedup(); + assert!( + unique.len() <= 4, + "{name} 一屏用了 {} 档字号 {unique:?}，超过 rubric D4 的 4 档", + unique.len() + ); + assert!(unique[0] >= 12.0, "{name} 出现小于 12px 的字号"); + assert!(unique[unique.len() - 1] <= 24.0, "{name} 字号过大"); + } +} + +/// 版面几何是页面唯一宽度来源：两列版面的正文列必须窄于可用宽度。 +#[test] +fn two_pane_body_is_narrower_than_the_available_width() { + let wide = frame_metrics(PaneKit::ListDetail, 1180.0); + assert!(wide.column < wide.available); + assert!(wide.secondary.is_some()); +} diff --git a/crates/app-iced/src/pages/harness.rs b/crates/app-iced/src/pages/harness.rs new file mode 100644 index 0000000..b97a376 --- /dev/null +++ b/crates/app-iced/src/pages/harness.rs @@ -0,0 +1,317 @@ +//! 截图 harness：把**一页**按给定窗口宽度 / 主题单独渲染并出图（`examples/pages_demo.rs` 的入口）。 +//! +//! **刻意不接 `cli.rs`**：等 `cli.rs` 具备 `--screen` / `--window-width` 之后，这个 harness 应当 +//! 删掉，改由正式启动参数出图。参数：`--screen=instances|download|settings|logs`、`--width`、 +//! `--height`、`--theme` / `--screenshot-theme`（后者优先）、`--screenshot`、`--renderer`、 +//! `--software-renderer`、`--scale-factor`、`--appearance=real|demo`、`--passthrough=on|off`。 +//! 解析与默认值在 [`request`]（M100 拆出去：本文件当时正好 400 行、零余量）；没给 `--screenshot` +//! 就只是开窗看。 +//! +//! ## 取证密闭（M100）：取证图不许跟着系统指针变 +//! +//! M99 复审实测过：同一个 exe 连跑 8 次，第 6 次给出**第三个 hash**，差异区是某个按钮被画成 Hovered +//! ——根因是 harness 开真窗口，`button::Status` 由**系统光标位置**决定。 +//! +//! 于是 `--screenshot` 有一条**通道级**钉死：开窗那一刻调 `window::enable_mouse_passthrough` +//! （winit 的 `set_cursor_hittest(false)`）⇒ 窗口从此收不到指针事件 ⇒ 全树控件恒为 `Active`。 +//! +//! ⚠️ **限定**：上句的因果链在**有指针输入的会话**里才被实测过。本机（RDP 断开）连 +//! `SetCursorPos` 都失败，所以「`指针事件=0`」在本环境里**既可能是穿透生效，也可能是根本没输入**。 +//! 要让 `指针事件=N` 变成密闭证据，必须同一 argv 再跑一次 `--passthrough=off` 做对照： +//! 那一跑该给出 `N>0`（复审注入后实测 12）**并且** hash 与开穿透时不同。没有这个对照， +//! `指针事件=0` 就退回成「没观测到输入」，而不能读成「输入被挡住了」。 +//! +//! ### 证据怎么读（M100 r1 复审订正，优先级从高到低） +//! +//! 1. **`[caps] passthrough_ext=on|off|unknown`** ← 主证据。winit 0.30 在 Windows 把 +//! `set_cursor_hittest(false)` 落成 `WS_EX_TRANSPARENT | WS_EX_LAYERED`，这一位可以从 +//! `GWL_EXSTYLE` 读回来（[`caps`] → `platform::win32::transparency::click_through`）。 +//! 复审探针实测：`--screenshot` 默认 176/214 次采样命中、`--passthrough=off` **0/320**、 +//! 产品 bin **0/535**。三态里的 `unknown` 是「没读到」，**不许**读成 `off`。 +//! 2. `指针事件=N`：**辅助**指标。它证明「鼠标消息到没到」，**不**证明「像素会不会变」 +//! （复审实测：注入 12 个事件而像素不变）。别拿它当密闭证据。 +//! 3. ~~hash 连跑几次都一样~~：**不是证据**。同 argv 加 `--passthrough=off` 出来的 hash 与 +//! 开穿透时完全相同 ⇒ 它只能说明「那几帧恰好静止」。 +//! +//! ### 同一族的另一个坑：一次一采样（P2-1） +//! +//! 以前第 3 帧之后**每一帧**都请求一次采样、每次都覆盖同一文件才 `exit()`，而已派发的采样不会 +//! 因为 exit 撤回 ⇒ **最后写入者说了算**（复审实测 12 次里 7 次写了两次；把窗口在两次采样之间 +//! 改成 900×600，落盘的就是 900×600 那张）。现在闸门在 [`should_request_capture`]，日志里的 +//! `落盘次数=` 必须恒为 1。 +//! +//! **为什么不是给每个控件灌 forced**：设置页「外观」区的滑块 / 文本框 / 裸 `iced::button` 都不 +//! 消费 forced，那样做要改十几个组件文件——为取证去动产品组件，代价与风险都不对，而且新产品 +//! 组件随时会漏。 +//! +//! ```text +//! cargo run -p unlucky-app-iced --example pages_demo -- --screen=instances --width=1180 \ +//! --height=760 --screenshot=out.png --screenshot-theme=light --software-renderer +//! ``` +//! +//! 等 3 帧再截图与 `app.rs` 同一口径（M60 坑 #5）：第一帧可能是启动时的旧尺寸，字体首次上屏会抖动。 + +use std::sync::atomic::{AtomicU32, Ordering}; +use std::sync::Arc; +use std::time::Instant; + +use iced::{window, Element, Point, Subscription, Task}; + +use crate::pages::appearance; +use crate::renderer; +use crate::shot; +use crate::theme::Ui; + +use super::{app_with_appearance, demo_model, Model}; + +mod app; +mod caps; +mod request; + +pub use app::run; +pub use request::{Request, CAPTURE_POSITION}; + +/// 截图落盘的帧号（见模块文档）。 +const CAPTURE_AT_FRAME: u32 = 3; + +/// 这一帧要不要请求采样？ +/// +/// **M100 r1 P2-1 的核心判据**：`dispatched` 一旦置位就永不再次请求。以前这里是 +/// `frames >= CAPTURE_AT_FRAME`，于是第 3 帧之后**每一帧**都发一次 `window::screenshot`， +/// 而 `Captured` 每次都覆盖同一文件才 `exit()`——已派发的采样不会因为 exit 被撤回， +/// 落盘内容变成调度结果（复审实测 12 次里 7 次写了两次）。 +/// +/// 单独拎成自由函数是为了让它可被断言（`Harness::update` 要 iced 运行时才能跑）。 +fn should_request_capture(frames: u32, dispatched: bool, capture_mode: bool) -> bool { + capture_mode && !dispatched && frames >= CAPTURE_AT_FRAME +} + +/// 采样「派发了却回不来」的宽限帧数（M100 r2 p3-b）。 +/// +/// 为什么需要它：一次性闸门（上面那条）把「每帧重试」换成了「只试一次」，于是若 +/// `window::screenshot` 的 Task 回不来，harness 既不再采样也不 `exit()` ⇒ CI 上表现成**超时**， +/// 而不是红灯。超时会被当成基础设施抖动重跑过去，红才会被人看。 +/// +/// ⚠️ **这条兜底只覆盖「还有帧」的情形**（M100 r3 P2-1 订正，我原来在这里写反了）： +/// `window::frames()` 只在 `Event::Window(RedrawRequested)` 时产消息，**窗口消失 ⇒ 不再有帧 +/// ⇒ 这里的判据根本求值不到**。那一路由 `run()` 里的**终态不变量**兜住（跑完没图 ⇒ 红着退出）； +/// 而后端报错是另一回事：`run()` 直接返回 `Err`，本来就是非 0。 +/// +/// 30 帧**不换算成秒**（M100 r4 P3-1）：帧间隔在不同机器/负载下量级差异极大——复审实测 2~3ms/帧， +/// 而本机 `[perf]` 日志里是 `frames=4 elapsed=1133ms` / `frames=5 elapsed=1605ms`（≈200~300ms/帧）。 +/// 所以这里只承诺「若干帧的宽限」，不写时间预算；要调就按「正常路径是第 3 帧派发、第 4~5 帧落盘」 +/// 这个结构关系调，别按秒。 +const CAPTURE_GIVE_UP_FRAMES: u32 = 30; + +/// 采样是不是**卡住了**：过了宽限帧数，一次都没落盘。 +/// +/// 不区分「一直没派发」（窗口始终没就绪）与「派发了没回来」——两者对使用者的表现都是 +/// 「没有图」，都该红着退出而不是挂死。 +fn capture_stalled(frames: u32, written: u32) -> bool { + written == 0 && frames > CAPTURE_AT_FRAME + CAPTURE_GIVE_UP_FRAMES +} + +struct Harness { + request: Request, + ui: Ui, + /// 视图模型（演示数据；harness 不接 presenter，只出**单页**图） + model: Model, + /// 外观运行期状态（`--appearance=real`）；`None` = 设置页画演示行。 + appearance: Option, + 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()).map(Message::Page) + } +} + +#[cfg(test)] +#[path = "harness/tests.rs"] +mod tests; diff --git a/crates/app-iced/src/pages/harness/app.rs b/crates/app-iced/src/pages/harness/app.rs new file mode 100644 index 0000000..2e2dea1 --- /dev/null +++ b/crates/app-iced/src/pages/harness/app.rs @@ -0,0 +1,241 @@ +//! 截图 harness 的**运行部分**（M100 r1：`harness.rs` 撞 400 行后从那里搬出来）。 +//! +//! 这里只有 [`run`]：探后端 → 造外观真状态 → 起 iced → 出图 → 按验收口径打日志。 +//! 参数解析在 [`super::request`]，窗口状态机与采样闸门在 [`super`]，OS 侧密闭指标在 +//! [`super::caps`]。搬出来没有改行为（同一 argv 的 PNG sha256 不变）。 + +use std::sync::atomic::{AtomicU32, Ordering}; +use std::sync::Arc; +use std::time::Instant; + +use iced::{window, Point, Task}; + +use unlucky_presenter::prefs::{AppearanceBase, AppearancePrefs}; + +use crate::app::components::interaction::Interaction; +use crate::cli::Backend; +use crate::fonts; +use crate::pages::appearance; +use crate::probe::{self, Probe}; +use crate::renderer; +use crate::theme::Ui; + +use super::{demo_model, Harness, Message, Request, CAPTURE_POSITION}; + +/// **终态判据**：取证运行跑完了却一张图都没落盘 ⇒ 失败。 +/// +/// 单独拎成纯函数是为了让它能被断言（`run()` 要真窗口才能跑）。它守的是 M100 r3 P2-1 那个 +/// 真实缺陷：窗口在第 3 帧消失时，`window::frames()` 不再产消息 ⇒ 帧超时兜底**求值不到**， +/// 而 iced_winit 对「最后一个窗口 Destroyed」直接退出 ⇒ 曾经是 **exit 0 + 没有 PNG**。 +/// +/// ## 为什么必须有 `capture_mode` 前提（M100 r4 P2-1） +/// +/// 不给 `--screenshot` 是文档明确支持的**交互预览模式**（「没给 `--screenshot` 就只是开窗看」）： +/// 该模式 `subscription()` 直接 `Subscription::none()`，**永远不会有 `Captured`** ⇒ `written` 恒 0。 +/// 没有这个前提，用户**正常关掉预览窗**会拿到 exit 1 和一句「取证结束但没有任何图落盘」的 +/// 假消息——那是把"从未要求出图"判成"取证失败"，通道的退出码就此失去区分力 +/// （真崩溃 / 真取证失败 / 正常关个预览窗全是 1）。 +/// +/// ## 为什么用计数器而不是 `path.exists()` +/// +/// `written` 是**本进程**成功落盘的次数，不会被执行前就存在的旧 PNG 骗过；换成「目标文件存在」 +/// 会在脏路径下给出「exit 0 + 上一次的旧图」。这一点写在这里，免得后来人「顺手改成 exists」。 +pub(super) fn no_evidence(capture_mode: bool, written: u32) -> bool { + capture_mode && written == 0 +} + +/// 启动（阻塞到出图或关窗）。 +/// +/// **取证通道的硬规则（M97）**：宁可红着退出，也不能悄悄换一种后端继续出图（以前 wgpu 挂掉时 +/// 会静默降级 tiny-skia 照样落 PNG，而报告上写着「GPU 渲染截图」）。所以这里 ① 决策被 +/// [`renderer::strict`] 剥掉兜底、② 起不来带**具名**错误返回、③ 每张图日志都带 `backend=`。 +/// +/// # Errors +/// 后端探测/字体求值失败、**渲染后端起不来（含 iced 的具名图形错误）**、截图落盘失败时返回人话。 +pub fn run(request: Request) -> Result<(), String> { + let started = Instant::now(); + + let needs_probe = request.backend == Backend::Auto || renderer::acceptance::enabled(); + let probe = if needs_probe { + Probe::run() + } else { + Probe::default() + }; + // 剥掉兜底：gallery 没有「偷偷换 CPU」这个选项。 + let decision = renderer::strict(probe::apply(request.backend, &probe)); + eprintln!( + "[shot] 出图后端 = {} reason={}（取证通道无回退：起不来就红着退出，绝不换 CPU 出图）", + decision.primary.name(), + decision.reason + ); + renderer::acceptance::report_backend_plan(&decision, request.backend); + + let resolved = fonts::resolve(); + eprintln!("{}", resolved.describe()); + let families = resolved.families(); + + // 这一份就是喂给 iced 的真值：`[window]` 那行从它取字段（M98 r1 p2-1 的同一个教训） + let settings = window::Settings { + size: iced::Size::new(request.width, request.height), + decorations: false, + resizable: true, + // 取证窗口钉在固定落点：这样「把指针放进窗口某个位置」是可复算的（真实矩形由 + // `Harness` 用 `window::position` / `window::size` 的返回值打日志报出，见 `Message::Sized`） + position: match request.screenshot { + Some(_) => { + window::Position::Specific(Point::new(CAPTURE_POSITION.0, CAPTURE_POSITION.1)) + } + None => window::Position::default(), + }, + ..window::Settings::default() + }; + renderer::acceptance::report_window( + &renderer::acceptance::WindowFacts::from_settings(&settings), + request.scale_factor, + "pages_demo", + None, + ); + + // 外观**真状态**（`--appearance=real`）：工厂态 + `ULL_APPEARANCE_*` 覆盖。 + // 这不是给设置页塞常量：状态从 `State::new` / `apply_env` 来，打日志的是它算出来的生效值。 + let appearance = request.real_appearance.then(|| { + let mut state = appearance::State::new( + &AppearancePrefs::factory(), + &AppearanceBase::factory(), + request.backend, + request.flavor, + ); + state.apply_env(); + eprintln!( + "[harness] 外观真状态：window={:.2} panel={:.2}（生效 {:.2}）bg={} fill={:?} dim={:.2} \ + 配色来源={:?} 选中分组={}", + state.window_opacity, + state.panel_alpha, + state.effective_panel_alpha(), + state.bg_enabled, + state.bg_fill, + state.bg_dim, + state.palette_source, + state.selected_group, + ); + state + }); + + // 落盘计数器（终态不变量 + 日志共用）：只在 `shot::save` 成功后自增。 + let written = Arc::new(AtomicU32::new(0)); + + let application = |backend: renderer::Kind| { + let boot = request.clone(); + let appearance = appearance.clone(); + // 落盘次数要能被 `run()` 读到（终态不变量用它），所以走共享计数器而不是 `Harness` 的私有字段： + // 值只在 `shot::save` **成功**之后自增，是「真的写出去了」而不是「我们打算写」（U1）。 + let written = Arc::clone(&written); + iced::application( + move || { + let mut model = demo_model(boot.screen, boot.width); + // 截图通道把**消费 forced 的那批控件**（实例页）钉成常态，与产品 `--screenshot` + // 的 `ForcedState::Rest` 同一条纪律。它管不到设置页 / 外观区（那边不读 forced）， + // 那两屏的密闭靠窗口级 passthrough——别把这条当成万能的。 + if boot.screenshot.is_some() { + model.forced = Some(Interaction::Enabled); + } + ( + Harness { + ui: Ui::new(boot.flavor, families), + model, + appearance: appearance.clone(), + request: boot.clone(), + window: None, + hwnd: None, + placed: None, + frames: 0, + dispatched: false, + written: Arc::clone(&written), + pointer: 0, + started, + first_frame: None, + backend: backend.name(), + }, + Task::done(Message::Boot), + ) + }, + Harness::update, + Harness::view, + ) + .theme(Harness::theme) + .subscription(Harness::subscription) + .default_font(iced::Font { + family: iced::font::Family::Name(families.text), + ..iced::Font::DEFAULT + }) + .window(settings) + }; + + eprintln!( + "[harness] screen={} width={} height={} slug={}（布局档位 {}）", + request.screen.slug(), + request.width, + request.height, + request.slug(), + crate::pages::layout::WidthClass::of(request.width).name() + ); + + // 兜底已被 `strict` 剥掉，所以这条最多跑一次；具名错误的口径与 App 启动一致， + // 但**取证通道不许降级**：出不了图就红着退出，不换后端（那是另一处 iced 行为）。 + let session_started = Instant::now(); + let result = renderer::run_once(decision, |backend| { + std::env::set_var("ICED_BACKEND", backend.env_value()); + let application = application(backend); + match request.scale_factor { + Some(scale) => application.scale_factor(move |_| scale).run(), + None => application.run(), + } + }); + let session = session_started.elapsed(); + + let outcome = result.map_err(|error| match renderer::named_graphics_error(&error) { + Some(named) => format!( + "渲染后端 {} 初始化失败（取证通道无回退，未出图）：{named}", + decision.primary.name() + ), + None => format!("iced 启动失败：{error}"), + }); + + // 取证通道恒为 evidence 启动 ⇒ 有兜底时 via=refuse、没兜底时 none（不再写死，M98 r1 p3-4） + renderer::acceptance::report_outcome( + &decision, + outcome.as_ref().err().map(String::as_str), + renderer::acceptance::failure_via(decision.fallback.is_some(), true), + "screenshot", + session, + ); + + outcome?; + + // **终态不变量（M100 r3 P2-1）**：取证跑完了却一张图都没落盘 = 失败。 + // + // 为什么要有这一条（复审变异实测）：兜底原来只有「帧数超时」，而 `window::frames()` 只在 + // `Event::Window(RedrawRequested)` 时产消息 —— 窗口一旦消失就不再 redraw ⇒ `Message::Frame` + // 不再产生 ⇒ `capture_stalled` **永远求值不到**；同时 iced_winit 对「最后一个窗口 Destroyed」 + // 直接 `Control::Exit`，`run()` 返回 `Ok(())`。表现是 **exit 0 + 没有 PNG**，与成功跑同一形状 + // 只少了出图那几行 —— 只看退出码的脚本会读到「成功 + 零证据」。 + // + // 所以判据从「超时」升级成「终态」：**跑完了没有图就是失败**。它比超时强，因为覆盖 + // 「帧不再产生」这一类；帧超时那条保留，管「有帧但采样回不来」。 + // + // **前提是这次真的是取证运行**（M100 r4 P2-1）：不给 `--screenshot` 的交互预览模式本来 + // 就不出图，判成失败会打出假消息、并让退出码失去区分力。前提写在判据里，不写在这里。 + if no_evidence( + request.screenshot.is_some(), + written.load(Ordering::Relaxed), + ) { + eprintln!("[harness] 取证结束但没有任何图落盘（窗口提前消失 / 落盘失败），按失败退出"); + std::process::exit(1); + } + + eprintln!( + "[harness] 用时 {:.0} ms", + started.elapsed().as_secs_f64() * 1000.0 + ); + Ok(()) +} diff --git a/crates/app-iced/src/pages/harness/caps.rs b/crates/app-iced/src/pages/harness/caps.rs new file mode 100644 index 0000000..4dcbff8 --- /dev/null +++ b/crates/app-iced/src/pages/harness/caps.rs @@ -0,0 +1,53 @@ +//! 取证窗口的**OS 侧密闭指标**（M100 r1 P2-2）：`WS_EX_TRANSPARENT` 在不在。 +//! +//! 为什么单独一个文件：① `harness.rs` 正卡在 400 行硬线上；② 「三态映射」这件事本身值得有断言 +//! （把 `unknown` 掉成 `off` 是这类日志最典型的假绿）。 +//! +//! 判据来自 winit 0.30 的 Windows 实现：`set_cursor_hittest(false)` ⇒ +//! `WS_EX_TRANSPARENT | WS_EX_LAYERED`。读位的手在 +//! [`crate::platform::win32::transparency::click_through`]（全仓唯一 unsafe 落点）。 + +use crate::platform::win32::transparency; + +/// 窗口是不是点击穿透 → 日志里的三态字面量。 +/// +/// - `on` = 读到了，且有 `WS_EX_TRANSPARENT`（winit 已把命中测试关掉）； +/// - `off` = 读到了，没有这一位； +/// - `unknown` = **没读到**（非 Windows / 句柄无效 / 还没拿到句柄）。 +/// +/// `unknown` 绝不许写成 `off`：「拿不到」和「没有」是两件事（U1 同族）。 +#[must_use] +pub fn passthrough_label(hwnd: Option) -> &'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..43b9ac6 --- /dev/null +++ b/crates/app-iced/src/pages/instances.rs @@ -0,0 +1,267 @@ +//! 实例页：**list-detail** 的唯一用例，也是 M90 唯一打通到「真组件 + 真数据 + 真命令」的页。 +//! +//! ## 版式（由 [`super::layout`] 决议，页面不自己算宽度） +//! +//! | 版面 | 结构 | 退化行为 | +//! |---|---|---| +//! | `ListDetail`（窗口 ≥840） | 左列 336 固定、**独立滚动**；右列详情，散文 ≤424 | — | +//! | `SingleColumn`（<840） | 列表与详情**整页切换**：本页只渲染详情列（块贴左吃满页宽，散文 ≤424） | 顶部给「Back to instances」，列表退成上一屏 | +//! +//! 为什么窄窗不是「上下堆」：官方 compact 下 list-detail 的口径是一次只显示一个 pane（列表 → 详情， +//! 整页切换）。上下堆会把详情挤到折叠线以下，等于详情不存在。 +//! +//! ## M90：占位控件 → 真组件（逐项对照） +//! +//! | 位置 | M84（占位） | M90（真组件） | +//! |---|---|---| +//! | 列表行 | 手搓 `container` + `text_role`（行高 56） | `navigation::list_item`（一/两/三行 44/60/76，五态状态层） | +//! | 页头动作 | `frame::text_action`（纯 `text` + 手搓 hover） | `buttons::text`（`Button` 五式 + 状态层） | +//! | 「Play」 | `frame::text_action` | `buttons::filled`（**全屏唯一实心 accent**，rubric K2） | +//! | 分隔线 | `frame::divider` | `divider::full` | +//! | 数据 | `DEMO` 常量 | [`super::model::Instances`]（真页面由 presenter 快照转，演示由 `DEMO` 转） | +//! +//! 判据没有因此放松：列宽仍由 [`super::layout`] 给（见 `pages/tests.rs` 的 424 断言）。 +//! +//! ## 行高为什么从 56 变成 60（M90 登记） +//! +//! M84 的行高是「`row_height` 44 + `Space::X3` 12 = 56」的手工值；真 `ListItem` 的两行档是 +//! **60**（令牌 `row_height` 44 + 每多一行 16，A1 是 72）。差异来自组件自己的几何真源， +//! 页面不许覆盖——这正是「接真组件」的应有结果。列表仍高于可视区，独立滚动条照样可见。 +//! +//! ## 行距归零 + 底部内缩（M102，视觉复审 ②） +//! +//! 视觉复审在 1180×760 的截图里抓到「末行 Redstone Lab 被卡片底边切掉半行（副标题消失）」。 +//! 根因是**两道页级附加量**：`Space::X1` 的行距让行节奏变成 64，与可视高度除不尽； +//! 列表滚动区贴到卡片的 1px 圆角描边上，切点正好落在描边线上。修法两件： +//! +//! | 改什么 | 值 | 结果 | +//! |---|---|---| +//! | 页级行距 | 4 → **0**（真源 [`ROW_SPACING`] = `None`） | 行节奏回到组件的 60 | +//! | 滚动区底部内缩 | 0 → **`Space::X2` 8**（真源 [`LIST_BOTTOM_INSET`]） | 切点落在卡片的内边距带里，不压描边 | +//! +//! 于是可视区 = 580 − 列头 32 − 内缩 8 = **540 = 9 × 60**，正好 9 整行：末行完整可见， +//! 第 10 行整体落在裁切线之外。两个数都**只有一个真源**，页面与护栏都从它取 +//! （`instances/tests.rs` 引 [`LIST_BOTTOM_INSET`].`dp()` 与 [`ROW_SPACING`] 算 pitch， +//! 另有一条源码结构断言盯着 `list_column()` 不许再叠字面量间距）。 +//! 列表内容 12×60 = 720 仍高过可视区，独立滚动条照样可见。 + +mod data; +mod demo; +mod detail; +mod text; + +#[cfg(test)] +mod tests; + +#[cfg(test)] +pub(crate) use data::{DEMO, NOTE, SELECTED}; +pub(super) use demo::demo; +pub(super) use text::Texts; + +use iced::widget::{column, container, row, scrollable}; +use iced::{Alignment, Background, Border, Element, Length, Padding}; + +use unlucky_design::color::Role; +use unlucky_design::elevation::MaterialLayer; +use unlucky_design::icons::IconKind; +use unlucky_design::shape::ShapeScale; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; + +use crate::app::components::buttons::{self, Button}; +use crate::app::components::interaction::Interaction; +use crate::app::components::navigation::list_item::{list_item, ListItem}; +use crate::theme::Ui; +use unlucky_presenter::router::Route; + +use super::frame::{self, Header}; +use super::layout::{FrameMetrics, PageLayout}; +use super::model::{Instances, Model, Row}; +use super::{Action, Message}; + +/// 列表行距：**`None` = 这一层不加间距**（页面与护栏**共用这一个真源**）。 +/// +/// M102 的 ② 就是页级附加量：`ListItem` 自己的 60 高已含上下 8px 内边距，页面再叠一道 +/// `Space::X1`(4) 就把行节奏变成 64、与可视高度除不尽（1180×760 下末行被切半行）。 +/// 所以行距不写成字面量、也不散落在 `list_column` 里，而是这个常量—— +/// 页面 `match` 它，`instances/tests.rs` 也从它算 pitch（改这里，测试立刻红）。 +pub(super) const ROW_SPACING: Option = None; + +/// 列表滚动区的**底部内缩**：让裁切线落在卡片的内边距带里，而不是压在 1px 描边上。 +/// +/// 与 [`ROW_SPACING`] 是一对（行距管「切在哪」、内缩管「切在什么底色上」）， +/// 两个数都由 `instances/tests.rs` 的几何断言直接引用。 +pub(super) const LIST_BOTTOM_INSET: Space = Space::X2; + +/// 整页（`block.detail = None` 时详情区显示空态）。 +/// +/// 文案全部走 [`Texts`]（`model.lang` 的语言）：这个函数是实例页唯一的取词入口， +/// 页面里不留任何可见英文字面量（守门见 `instances/tests/i18n.rs`）。 +pub fn view<'a>(ui: &'a Ui, metrics: FrameMetrics, model: &'a Model) -> Element<'a, Message> { + let block = &model.instances; + let forced = model.forced; + let texts = Texts::of(model.lang.catalog()); + let header = Header::new(texts.title()) + .subtitle(texts.subtitle()) + .action(buttons::text( + ui, + forced_state( + Button::new(texts.new_instance(), Message::Action(Action::NewInstance)), + forced, + ), + )) + .action(buttons::text( + ui, + forced_state( + Button::new(texts.import(), Message::Action(Action::Import)), + forced, + ), + )); + + let body = match metrics.layout { + PageLayout::ListDetail => frame::panes( + metrics, + list_column(ui, block, forced, texts), + match &block.detail { + Some(detail) => detail::detail_column(ui, metrics, detail, forced, texts), + None => detail::detail_empty(ui, texts), + }, + ), + _ => match &block.detail { + Some(detail) => detail::narrow_detail(ui, metrics, detail, forced, texts), + None => frame::body(metrics, detail::detail_empty(ui, texts)), + }, + }; + + frame::page(ui, metrics, header, body) +} + +// --------------------------------------------------------------- 列表列 + +fn list_column<'a>( + ui: &'a Ui, + block: &'a Instances, + forced: Option, + 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 / 视觉复审 ②）。 + 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); + } + + list_item(ui, item) +} diff --git a/crates/app-iced/src/pages/instances/data.rs b/crates/app-iced/src/pages/instances/data.rs new file mode 100644 index 0000000..df9899e --- /dev/null +++ b/crates/app-iced/src/pages/instances/data.rs @@ -0,0 +1,143 @@ +//! 实例页的**演示数据**（骨架期没有业务状态机，也没有业务数据）。 +//! +//! 12 条，**故意比可视区高**：列表列的独立滚动条要能在截图里看见（单测钉住这条）。 +//! +//! **这里的数据是夹具（用户数据），不是界面文案**：`1.20.4` / `Fabric 0.15.7` / `4 GiB` / +//! `2 hours ago` 这些是「实例清单里会长成什么样」的样本，M120 没有把它们搬进词表——它们不是 +//! 界面说的那句话。界面文案（标题 / 按钮 / 元信息标签 / 空态 / 阶段）走 `catalog/instances.rs`， +//! 见 `text.rs` 与 `app/view/instances.rs`。 +//! +//! 这条路径（`pages_demo` harness / 单测）**恒英文**：`pages::demo_model` 走 `Model::new`， +//! `lang` 是 `Lang::En`。产品路径不读这份数据，它画的是 presenter 快照。 + +/// 演示条目（骨架期没有业务数据；夹具文案，见模块文档）。 +pub(crate) struct Entry { + pub(crate) name: &'static str, + pub(crate) version: &'static str, + pub(crate) loader: &'static str, + pub(crate) memory: &'static str, + pub(crate) java: &'static str, + pub(crate) mods: &'static str, + pub(crate) last_played: &'static str, +} + +/// 12 条演示数据：**比可视区高**，这样列表列的独立滚动条在截图里能看见。 +pub(crate) const DEMO: [Entry; 12] = [ + Entry { + name: "Fabulous World", + version: "1.20.4", + loader: "Fabric 0.15.7", + memory: "4 GiB", + java: "Temurin 21", + mods: "148 mods", + last_played: "2 hours ago", + }, + Entry { + name: "Skyblock Origins", + version: "1.21.1", + loader: "NeoForge 21.1.72", + memory: "6 GiB", + java: "Temurin 21", + mods: "86 mods", + last_played: "yesterday", + }, + Entry { + name: "Vanilla Survival", + version: "1.21.4", + loader: "Vanilla", + memory: "2 GiB", + java: "Temurin 21", + mods: "0 mods", + last_played: "3 days ago", + }, + Entry { + name: "Create: Above and Beyond", + version: "1.18.2", + loader: "Forge 40.2.0", + memory: "8 GiB", + java: "Temurin 17", + mods: "312 mods", + last_played: "last week", + }, + Entry { + name: "All the Mods 9", + version: "1.20.1", + loader: "NeoForge 20.4.237", + memory: "8 GiB", + java: "Temurin 17", + mods: "412 mods", + last_played: "2 weeks ago", + }, + Entry { + name: "Better MC", + version: "1.20.1", + loader: "Fabric 0.14.24", + memory: "6 GiB", + java: "Temurin 17", + mods: "264 mods", + last_played: "last month", + }, + Entry { + name: "RLCraft", + version: "1.12.2", + loader: "Forge 14.23.5", + memory: "4 GiB", + java: "Zulu 8", + mods: "184 mods", + last_played: "2 months ago", + }, + Entry { + name: "Origins SMP", + version: "1.20.4", + loader: "Quilt 0.24.0", + memory: "4 GiB", + java: "Temurin 21", + mods: "57 mods", + last_played: "3 months ago", + }, + Entry { + name: "Redstone Lab", + version: "1.19.4", + loader: "Fabric 0.15.2", + memory: "3 GiB", + java: "Temurin 17", + mods: "34 mods", + last_played: "April 12", + }, + Entry { + name: "Pixelmon Reforged", + version: "1.16.5", + loader: "Forge 36.2.34", + memory: "6 GiB", + java: "Temurin 8", + mods: "121 mods", + last_played: "March 3", + }, + Entry { + name: "Techopolis 2", + version: "1.20.1", + loader: "Forge 47.2.20", + memory: "8 GiB", + java: "Temurin 17", + mods: "198 mods", + last_played: "January 28", + }, + Entry { + name: "Cobblemon", + version: "1.21.1", + loader: "Fabric 0.16.9", + memory: "5 GiB", + java: "Temurin 21", + mods: "74 mods", + last_played: "January 9", + }, +]; + +/// 演示选中的条目（第一条）。 +pub(crate) const SELECTED: usize = 0; + +/// 详情正文（**故意写长**：这是行宽上限的视觉证据——1180 宽窗口下也只断在 ~72 字符）。 +pub(crate) const NOTE: &str = "This instance keeps its own mods, configs and saves. The launcher resolves the version chain \ + (instance → mod loader → vanilla) at launch time, verifies every jar it downloaded against the mirror \ + manifest, and streams progress back as structured events so the UI never has to guess. Nothing on this \ + page is wired to real data yet: the layout is, the numbers are."; diff --git a/crates/app-iced/src/pages/instances/demo.rs b/crates/app-iced/src/pages/instances/demo.rs new file mode 100644 index 0000000..64443c9 --- /dev/null +++ b/crates/app-iced/src/pages/instances/demo.rs @@ -0,0 +1,67 @@ +//! 实例页的**演示数据 → 视图模型**转换（M84 的出图基线靠这份数据）。 +//! +//! 只被 [`crate::pages::demo_model`] 用：产品路径的转换在 `app/view.rs`（presenter 快照 → 模型）。 +//! 两份数据源喂同一个渲染函数，这是 [`crate::pages::model`] 存在的理由。 + +use unlucky_i18n::{Catalog, Key, Lang}; + +use super::super::model::{Detail, Instances, Meta, Row}; +use super::data::{DEMO, NOTE, SELECTED}; + +/// 演示路径的目录：**恒英文**。 +/// +/// 为什么不是 `model.lang`：本函数只被 `pages::demo_model` 调用，而那条路（`pages_demo` harness / +/// 单测）走 `Model::new`，`lang` 恒为 `Lang::En`（harness 没有换语言的开关）。产品路径不读这里 +/// ——它走 `app/view.rs` 的快照转换。等 harness 有 `--lang` 时把这一行换成参数即可。 +fn catalog() -> Catalog { + Lang::En.catalog() +} + +/// 元信息卡的标签（与 `app/view/instances.rs` 的 `detail_of` 同一批 key，只是这里恒英文）。 +fn label(key: Key) -> &'static str { + catalog().text(key) +} + +/// 把 M84 的演示条目 [`DEMO`] 转成视图模型（真页面走 `app/view.rs` 的 `AppState` 转换）。 +pub(crate) fn demo() -> Instances { + let rows = DEMO + .iter() + .map(|entry| Row { + id: entry.name.to_string(), + name: entry.name.to_string(), + supporting: format!("{} · {}", entry.version, entry.loader), + status: None, + }) + .collect(); + + let entry = &DEMO[SELECTED]; + let detail = Detail { + id: entry.name.to_string(), + name: entry.name.to_string(), + subtitle: format!("{} · {}", entry.version, entry.loader), + meta: vec![ + meta(label(Key::InstancesMetaVersion), entry.version), + meta(label(Key::InstancesMetaLoader), entry.loader), + meta(label(Key::InstancesMetaMemory), entry.memory), + meta(label(Key::InstancesMetaJava), entry.java), + meta(label(Key::InstancesMetaMods), entry.mods), + meta(label(Key::InstancesMetaLastPlayed), entry.last_played), + ], + note: Some(NOTE.to_string()), + status: None, + can_launch: true, + can_stop: false, + }; + + Instances { + rows, + detail: Some(detail), + } +} + +fn meta(label: &str, value: &str) -> Meta { + Meta { + label: label.to_string(), + value: value.to_string(), + } +} diff --git a/crates/app-iced/src/pages/instances/detail.rs b/crates/app-iced/src/pages/instances/detail.rs new file mode 100644 index 0000000..4d6d41c --- /dev/null +++ b/crates/app-iced/src/pages/instances/detail.rs @@ -0,0 +1,256 @@ +//! 实例页的**详情列**（M90 r2 从 `instances.rs` 拆出来：那边超过 400 行会被 guards 的 file-size 判红）。 +//! +//! 结构：标题行（名字 + 版本 + Play/Stop）→ 元信息网格（列数由 `layout::meta_columns` 决定） +//! → 一条分隔线 → 正文段 / 运行状态行 → 动作行（Duplicate / Open folder / Delete）。 +//! 窄窗（<840）时列表退成上一屏，本文件只画详情 + 一个「返回」按钮。 + +use iced::widget::{column, container, row}; +use iced::{Alignment, Element, Length}; + +use unlucky_design::color::Role; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; +use unlucky_presenter::router::Route; + +use crate::app::components::buttons::{self, Button}; +use crate::app::components::divider; +use crate::app::components::interaction::Interaction; +use crate::theme::Ui; +use unlucky_design::icons::IconKind; + +use super::super::frame; +use super::super::layout::{self, FrameMetrics}; +use super::super::model::Detail; +use super::super::{Action, Message}; +use super::forced_state; +use super::Texts; + +// --------------------------------------------------------------- 详情列 + +pub(super) fn detail_column<'a>( + ui: &'a Ui, + metrics: FrameMetrics, + detail: &'a Detail, + forced: Option, + texts: Texts, +) -> Element<'a, Message> { + let mut body = column![ + detail_head(ui, detail, forced, texts), + meta_grid(ui, metrics, detail), + divider::full(ui), + ] + .spacing(ui.space(Space::X4)) + .width(Length::Fill); + + body = push_text(ui, metrics, body, detail); + + // 页头 + 元信息网格 + **一条**分隔线以下才是正文与操作区（M84 那两条线是占位时期的排版残留） + frame::left_aligned(metrics.column, body.push(action_row(ui, forced, texts))) +} + +pub(super) fn narrow_detail<'a>( + ui: &'a Ui, + metrics: FrameMetrics, + detail: &'a Detail, + forced: Option, + texts: Texts, +) -> Element<'a, Message> { + // 窄窗：列表退成上一屏，本屏只放详情（官方 compact 的 list-detail 口径）。 + let mut body = column![ + row![buttons::text( + ui, + forced_state( + Button::new(texts.back(), Message::Navigate(Route::Instances)), + forced, + ), + )] + .width(Length::Fill) + .align_y(Alignment::Center), + detail_head(ui, detail, forced, texts), + meta_grid(ui, metrics, detail), + divider::full(ui), + ] + .spacing(ui.space(Space::X4)) + .width(Length::Fill); + + body = push_text(ui, metrics, body, detail); + + body = body.push(frame::text_role( + ui, + TypeRole::BodySmall, + false, + texts.narrow_note(), + ui.color(Role::OnSurfaceVariant), + )); + + frame::body(metrics, body.push(action_row(ui, forced, texts))) +} + +/// 正文段（演示数据才有）与运行状态行（真数据才有）——两者都是可选的，顺序固定。 +/// +/// 散文段套 [`frame::prose`]：M102 起页面块吃满页宽，但「一行 ≤72 字符」的承诺仍然只由 +/// 散文承担（`frame::body_width` 管块、`metrics.column` 管一句话）。 +fn push_text<'a>( + ui: &'a Ui, + metrics: FrameMetrics, + mut body: iced::widget::Column<'a, Message>, + detail: &'a Detail, +) -> iced::widget::Column<'a, Message> { + if let Some(note) = &detail.note { + body = body.push(frame::prose( + metrics, + frame::text_role( + ui, + TypeRole::BodyMedium, + false, + note.as_str(), + ui.color(Role::OnSurfaceVariant), + ), + )); + } + if let Some(status) = &detail.status { + body = body.push(frame::text_role( + ui, + TypeRole::BodyMedium, + false, + status.as_str(), + ui.color(Role::OnSurface), + )); + } + body +} + +fn detail_head<'a>( + ui: &'a Ui, + detail: &'a Detail, + forced: Option, + texts: Texts, +) -> Element<'a, Message> { + let titles = column![ + frame::text_role( + ui, + TypeRole::TitleLarge, + true, + detail.name.as_str(), + ui.color(Role::OnSurface) + ), + frame::text_role( + ui, + TypeRole::BodySmall, + false, + detail.subtitle.as_str(), + ui.color(Role::OnSurfaceVariant), + ), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill); + + // 主操作：**全屏唯一**实心 accent（rubric K2）。不可用时退化成禁用态（只清消息，不改身份）。 + let launch = if detail.can_launch { + buttons::filled( + ui, + forced_state( + Button::new(texts.play(), Message::Launch(detail.id.clone())), + forced, + ), + ) + } else { + buttons::filled(ui, Button::disabled(texts.play())) + }; + let stop = if detail.can_stop { + buttons::text( + ui, + forced_state( + Button::new(texts.stop(), Message::Stop(detail.id.clone())), + forced, + ), + ) + } else { + buttons::text(ui, Button::disabled(texts.stop())) + }; + + row![titles, launch, stop] + .spacing(ui.space(Space::X2)) + .width(Length::Fill) + .align_y(Alignment::Center) + .into() +} + +/// 元信息网格：列数由 [`layout::meta_columns`]（按正文列宽）决定 —— **1180 与 900 都是 2 列**。 +/// +/// 3 列需要 `3 × META_CARD_MIN_WIDTH + 2 × META_GAP` = 504px，而行宽上限是 424，**数学上不可行**； +/// 硬塞回 3 列会让 `NeoForge 20.4.237`（118px）这类值按词折行、同排卡底不齐。 +fn meta_grid<'a>(ui: &'a Ui, metrics: FrameMetrics, detail: &'a Detail) -> Element<'a, Message> { + let mut grid = column![].spacing(layout::META_GAP).width(Length::Fill); + let columns = metrics.meta_columns.clamp(1, detail.meta.len().max(1)); + + for chunk in detail.meta.chunks(columns) { + let mut cells_row = row![].spacing(layout::META_GAP).width(Length::Fill); + for cell in chunk { + let card = frame::card( + ui, + column![ + frame::text_role( + ui, + TypeRole::LabelMedium, + false, + cell.label.as_str(), + ui.color(Role::OnSurfaceVariant), + ), + frame::text_role( + ui, + TypeRole::BodyMedium, + false, + cell.value.as_str(), + ui.color(Role::OnSurface) + ), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill), + ); + cells_row = cells_row.push(container(card).width(Length::Fill)); + } + grid = grid.push(cells_row); + } + + grid.into() +} + +fn action_row<'a>(ui: &'a Ui, forced: Option, texts: Texts) -> Element<'a, Message> { + row![ + buttons::text( + ui, + forced_state( + Button::new(texts.duplicate(), Message::Action(Action::Duplicate)), + forced, + ) + ), + buttons::text( + ui, + forced_state( + Button::new(texts.open_folder(), Message::Action(Action::OpenFolder)), + forced, + ) + ), + buttons::text( + ui, + forced_state( + Button::new(texts.delete(), Message::Action(Action::Delete)), + forced + ), + ), + ] + .spacing(ui.space(Space::X2)) + .align_y(Alignment::Center) + .into() +} + +pub(super) fn detail_empty<'a>(ui: &'a Ui, texts: Texts) -> Element<'a, Message> { + frame::empty_state( + ui, + IconKind::Instances, + texts.empty_title(), + texts.empty_body(), + Vec::new(), + ) +} diff --git a/crates/app-iced/src/pages/instances/tests.rs b/crates/app-iced/src/pages/instances/tests.rs new file mode 100644 index 0000000..0385462 --- /dev/null +++ b/crates/app-iced/src/pages/instances/tests.rs @@ -0,0 +1,224 @@ +//! `instances` 的断言：演示数据、窄窗退化，以及**页面摆法**（源码结构断言）。 +use super::*; + +/// M120 的文案守门（中文无英文词 / 切语言真的变 / 页面里不许写死英文案·白名单）。 +mod i18n; + +use super::super::layout::source; +use super::super::layout::{frame_metrics, measure_cap_px, PaneKit, WidthClass}; + +/// **M102 几何判据**：列表可视区正好放下整数行——末行不会被卡片底边切半行。 +/// +/// 算式里的三个页面真源**直接引用**（不写字面量），所以改页面常量会让这条立刻红： +/// [`LIST_BOTTOM_INSET`]（滚动区底部内缩）、[`ROW_SPACING`]（页级行距，`None` = 0）。 +/// +/// ```text +/// 卡片高 = 760 − 标题栏 48 − 两行页头 84 − 2×gutter 24 = 580 +/// 列头 = 上 12 + LabelMedium 16 + 下 4 = 32 +/// 内缩 = LIST_BOTTOM_INSET = Space::X2 = 8 +/// 可视区 = 580 − 32 − 8 = 540 +/// 行高 = ListItem 两行档 44 + 16 = 60 +/// pitch = 行高 + ROW_SPACING（None ⇒ 0） = 60 +/// 整行数 = 540 / 60 = 9 行整 +/// ``` +/// +/// **抓得住**：页面把内缩换档（`LIST_BOTTOM_INSET` → `X1` 立刻除不尽）、行距真源被改、 +/// 列头算错、演示数据被缩到不够滚（独立滚动条消失）； +/// **抓不住**：`list_column()` 里被另写一层 `.spacing(…)`（那一条由 +/// `list_column_spaces_rows_only_from_the_shared_constant` 扫源码守）。 +#[test] +fn list_viewport_fits_whole_rows_and_still_overflow() { + use unlucky_design::spacing::LayoutMetrics; + use unlucky_design::typography::TypeRole; + + let lm = LayoutMetrics::DESKTOP; + let gutter = WidthClass::Expanded.gutter(); + + let card = 760.0 - lm.titlebar_height - lm.header_height(true) - 2.0 * gutter; + assert_eq!(card, 580.0, "1180×760 下列表卡片的内部高度"); + + let head = Space::X3.dp() + TypeRole::LabelMedium.style().line_height_px + Space::X1.dp(); + let viewport = card - head - LIST_BOTTOM_INSET.dp(); + assert_eq!(viewport, 540.0, "列表滚动区高度必须以页面的内缩真源算"); + + // 页级行距的**唯一真源**：None = 这一层不加间距 + let gap = ROW_SPACING.map_or(0.0, Space::dp); + let row = lm.row_height + Space::X4.dp(); + let pitch = row + gap; + assert_eq!(pitch, 60.0, "行节奏 = ListItem 两行档 60（不留页级行距）"); + assert_eq!( + viewport % pitch, + 0.0, + "可视区 {viewport} 不是 {pitch} 的整数倍 ⇒ 末行会被切半行（ROW_SPACING={ROW_SPACING:?}）" + ); + + // 同时必须还能滚：12 行内容高过可视区，截图里才看得到独立滚动条 + let content = DEMO.len() as f32 * pitch; + assert!( + content > viewport, + "列表内容 {content} 不比可视区 {viewport} 高，截图里看不到独立滚动条" + ); +} + +/// **源码结构**：`list_column()` 里对行容器的间距**只能**来自 [`ROW_SPACING`]。 +/// +/// 为什么读源码：变异实测（M102 r1）把 `.spacing(ui.space(Space::X1))` 加回行容器后， +/// 几何断言照样绿——它算的是常量，看不见页面又叠了一层。iced 的 Element 又没有内省接口， +/// 所以只能断言这段代码的形状。 +/// +/// ## 两层判据（r4 复审的 M4 订正） +/// +/// | 层 | 判据 | 抓的是 | +/// |---|---|---| +/// | ① 构建链 | `let mut rows = column(…);` 这条语句链上不许有 `.spacing(` | 直接写在链上的间距（变异 D） | +/// | ② 语句序列 | `list_column()` 里**每一处** `rows.spacing(…)` 的实参都要**顺绑定追回 `ROW_SPACING`** | **另起一条语句**再叠间距（变异 M4，含「先把令牌挪进一条 `let`」的写法） | +/// +/// 为什么②要追绑定而不是比字面：合法写法有几种形状——`rows = rows.spacing(ui.space(spacing))` +/// 直接取自 `if let Some(spacing) = ROW_SPACING`，或先 `let spacing = ROW_SPACING;` 再中转 +/// （变异 H3）。`layout/source.rs::derived_from` 顺 `let` / `Some(…) =` 两种绑定往回追最多三跳， +/// 于是「真源」放行、「中转了一层 `Space::X1`」判否。 +/// +/// **抓得住**：构建链上的字面量间距（D）、另起语句的行距（M4）、`ROW_SPACING` / `LIST_BOTTOM_INSET` +/// 两个真源被摘掉；`column![head, scroller]` 上的合法间距不受影响（变异 J，绿）； +/// **抓不住**：把间距算进别处再以非令牌形式传进 `list_row()`（那要改组件几何，代码评审能看出来）、 +/// 以及绕过 `rows.spacing(…)` 这个调用形状的写法。 +#[test] +fn list_column_spaces_rows_only_from_the_shared_constant() { + let file = include_str!("../instances.rs"); + let body = source::function_region(file, "fn list_column"); + let rows_chain = source::statement(file, "let mut rows = column("); + + assert!( + body.contains("ROW_SPACING"), + "列表行距必须从 ROW_SPACING 取，不许另写：\n{body}" + ); + assert!( + body.contains("LIST_BOTTOM_INSET"), + "底部内缩必须从 LIST_BOTTOM_INSET 取：\n{body}" + ); + + // ① 行容器的构建链上不许叠间距（`column![head, scroller]` 上的合法间距不在这条链里） + assert!( + !rows_chain.contains(".spacing("), + "行容器的构建链上又出现了间距（M102 ② 的页级附加量）：\n{rows_chain}" + ); + + // ② 语句序列：每一处 `rows.spacing(…)` 的实参都必须**顺绑定追回 `ROW_SPACING`** + // （直接用它、或 `let spacing = ROW_SPACING` 再中转都算；先 `let extra = Space::X1;` + // 再 `rows.spacing(ui.space(extra))` 则红——r4 复审的变异 M4） + let applied = source::call_arguments(&body, "rows.spacing("); + assert!( + !applied.is_empty(), + "`list_column()` 里没有把 ROW_SPACING 应用到行容器的调用：\n{body}" + ); + for argument in &applied { + let ident = argument + .split_once("ui.space(") + .map(|(_, rest)| rest) + .unwrap_or(argument); + let ident: String = ident + .chars() + .take_while(|ch| ch.is_alphanumeric() || *ch == '_') + .collect(); + + assert!( + argument.contains("ui.space("), + "行容器的间距实参必须走令牌栅格（`ui.space(…)`），收到 {argument:?}" + ); + assert!( + !argument.contains("Space::"), + "行容器的间距实参里直接写了令牌档位：{argument:?}\n{body}" + ); + assert!( + source::derived_from(&body, &ident, "ROW_SPACING"), + "行容器的间距不是从 ROW_SPACING 来的（`{ident}` 追不到 ROW_SPACING）——\ + M102 ② 的页级附加量不许另起一条语句塞回来：{argument:?}\n{body}" + ); + } +} + +/// **散文接线**：详情页的正文段必须进 `frame::prose`（424），不许直接塞进 `frame::body`（1044）。 +/// +/// M102 把「块宽」与「散文列宽」拆成两个量之后，接错一行代码就会让 361 字符的正文在 1180 窗宽下 +/// 排成 170 字符一行，而不红任何测试。这条断言把接线本身钉住。 +#[test] +fn the_detail_note_goes_through_the_prose_box() { + let body = source::function_body(include_str!("../instances/detail.rs"), "fn push_text"); + + assert!( + body.contains("frame::prose("), + "正文段没有走 frame::prose：\n{body}" + ); + assert!( + !body.contains("frame::body("), + "正文段被塞进了整页块（会失去 72 字符行宽承诺）：\n{body}" + ); +} + +/// 元信息卡必须装得下**卡内最长的那条值**（视觉 r2：136 漏算 padding，版本串折行让卡底不齐）。 +#[test] +fn meta_card_is_wide_enough_for_the_longest_value() { + use super::super::layout::{measure_cap_px, META_CARD_MIN_WIDTH, META_GAP}; + use unlucky_design::spacing::LayoutMetrics; + + // 实测（Segoe UI 14px）：demo 数据里最宽的元信息值是加载器版本串 + const LONGEST_VALUE: &str = "NeoForge 20.4.237"; + const LONGEST_VALUE_PX: f32 = 118.0; + + let padding = LayoutMetrics::DESKTOP.card_padding; + assert_eq!(padding, 20.0, "卡内边距来自令牌"); + + // 夹具与 demo 数据不许脱节：这个值必须真在 DEMO 里 + assert!( + DEMO.iter().any(|entry| entry.loader == LONGEST_VALUE), + "夹具 {LONGEST_VALUE:?} 已经不在 DEMO 里了，请重新量最长值" + ); + + // ① 单卡外框减掉两侧内边距，必须放得下这条值（否则 text 会按词折行 → 卡底不齐） + let inner = META_CARD_MIN_WIDTH - 2.0 * padding; + assert!( + inner >= LONGEST_VALUE_PX, + "卡内可用 {inner}px 装不下 {LONGEST_VALUE_PX}px 的 {LONGEST_VALUE:?}（外框 {META_CARD_MIN_WIDTH} − 2×{padding}）" + ); + + // ② 实际版面里每张卡的内宽（2 列时）也要够 + let two_columns = (measure_cap_px() - META_GAP) / 2.0; + assert!( + two_columns - 2.0 * padding >= LONGEST_VALUE_PX, + "两列布局下卡内可用 {}px 装不下 {LONGEST_VALUE_PX}px", + two_columns - 2.0 * padding + ); +} + +#[test] +fn every_demo_entry_has_name_version_and_loader() { + for entry in &DEMO { + assert!(!entry.name.is_empty()); + assert!(!entry.version.is_empty()); + assert!(!entry.loader.is_empty()); + } + assert!(SELECTED < DEMO.len()); +} + +#[test] +fn detail_paragraph_is_long_enough_to_wrap() { + // 行宽上限 ≈ 72 字符/行；写够几行才看得出断行位置 + assert!(NOTE.len() > 200, "正文档太短，看不出行宽上限"); +} + +#[test] +fn narrow_widths_switch_the_page_to_one_column() { + // 1180 / 900 → 两列；700 → 单列（整页切换） + assert_eq!( + frame_metrics(PaneKit::ListDetail, 1180.0).layout, + PageLayout::ListDetail + ); + assert_eq!( + frame_metrics(PaneKit::ListDetail, 700.0).layout, + PageLayout::SingleColumn + ); + // 窄窗下详情不吃满窗口：正文列仍 ≤ 行宽上限 + let narrow = frame_metrics(PaneKit::ListDetail, 700.0); + assert!(narrow.column <= measure_cap_px() + f32::EPSILON); + assert!(narrow.secondary.is_none()); +} diff --git a/crates/app-iced/src/pages/instances/tests/i18n.rs b/crates/app-iced/src/pages/instances/tests/i18n.rs new file mode 100644 index 0000000..4e96787 --- /dev/null +++ b/crates/app-iced/src/pages/instances/tests/i18n.rs @@ -0,0 +1,271 @@ +//! 实例页的**文案守门**（M120）：中文态不许漏英文、切语言必须真的变、运行状态的数字不许变形。 +//! +//! | 用例 | 抓得住什么 | +//! |---|---| +//! | [`the_chinese_page_has_no_english_words`] | 目录里某条中文忘了翻（或翻完还留着英文词） | +//! | [`every_instances_text_changes_with_the_language`] | 两套语言写成一样（= 切换语言时那一处不动，看着像「已 i18n」其实是死文案） | +//! | [`the_running_line_keeps_its_number_and_separator`] | `Running · pid 1234` 的数字 / `pid` / `·` 被翻译走样 | +//! | [`every_english_literal_in_the_page_sources_is_whitelisted`] | 页面里写死**任何**英文（旧串或新写的，白名单判定；r1 之前是黑名单，对新写的英文是哑的） | +//! | [`every_instances_key_is_referenced_by_the_page`] | 目录里加了 key、页面没人用（死 key，M117 那七条就是这么来的） | +//! +//! ## 边界（别把这张表读成「视图覆盖」） +//! +//! iced 0.14 的 `Element` **没有内省接口**（`instances/tests.rs` 里那条「为什么读源码」写的就是它）， +//! 所以「上屏文本」取样只能从页面取词的那**一个入口** [`Texts`] 拿：页面用它画、测试用同一个 +//! `Texts` 断言，不是另写一份平行实现。「页面又冒出一条**新**硬编码英文字面量」由 +//! [`every_english_literal_in_the_page_sources_is_whitelisted`] 兜（白名单）；**中文**写死的 +//! 字面量它看不见，那只能靠 `Texts::of(` 的反向锚与出图人工看。 +//! 「模型这一层（快照 → 状态行 / 元信息）跟着 `Lang` 变」由 `app/view/tests.rs` 守。 + +use unlucky_i18n::catalog::MISSING; +use unlucky_i18n::{Catalog, Key, Lang}; + +use super::super::Texts; + +/// 中文界面里允许出现的 ASCII 词：**品牌名与技术标识**。 +/// +/// 每一条都要说清为什么： +/// +/// - `Java`：运行时品牌名（`JAVA` 那格的值域里也全是 `Temurin 21` 这类品牌串），翻成「爪哇」是错的； +/// - `pid`：进程号的技术标识。用户拿它去任务管理器里搜进程，翻成「进程」就丢了这条可操作性。 +const ALLOWED: &[&str] = &["Java", "pid"]; + +/// 页面取词的五个源码文件（死 key 扫描与旧串扫描共用）。 +const PAGE_SOURCES: [(&str, &str); 5] = [ + ("instances.rs", include_str!("../../instances.rs")), + ("instances/detail.rs", include_str!("../detail.rs")), + ("instances/demo.rs", include_str!("../demo.rs")), + ("instances/text.rs", include_str!("../text.rs")), + ( + "app/view/instances.rs", + include_str!("../../../app/view/instances.rs"), + ), +]; + +/// 页面五件套里**允许出现的字符串字面量**（凡是带 ASCII 单词的都必须在这张表里）。 +/// +/// M120 r1 复审实测出黑名单的哑点：只兜「已知的 29 条旧串」时，往页面里**新写一句英文** +/// 照样 612/612 + 12/12 全绿。判据现在反过来——**白名单**：页面源码里每个带 ASCII 单词的 +/// 字面量都要在这里找到归宿，新写一句英文立刻红。 +/// +/// 全部 6 条都写了理由（剩下一批 `"{} · {}"` / `"{} · {:.0}%"` / `"{} {}"` 这类格式化模板 +/// **连一个词都没有**，所以不需要条目）： +/// +/// | 字面量 | 为什么它可以是英文 | +/// |---|---| +/// | `{date} {time} UTC` | `UTC` 是时区缩写，不是界面文案（本地时区换算属时间格式 mission） | +/// | `isolated` / `shared` | core 的隔离档位**稳定 id**（`IsolationMode::as_str`），`isolation()` 只认这两档，其余原样上屏 | +/// | `pid` / `reason` | `Catalog::render` 的**占位符名**（与 catalog 里的 `{pid}` / `{reason}` 对应） | +/// | `Instances` | `Texts::keys()` 的**族名前缀**（`Key::ALL` 的过滤条件，不是文案） | +const ALLOWED_LITERALS: [&str; 6] = [ + "{date} {time} UTC", + "isolated", + "shared", + "pid", + "reason", + "Instances", +]; + +/// 抽出源码里的字符串字面量（够用的实现：本仓这五个文件没有 `\"` 转义、没有多行字符串）。 +/// +/// 按 `"` 切开取**奇数段**即可：`a"b"c"d"e` → 段 1 = `b`、段 3 = `d`。 +fn string_literals(source: &str) -> Vec<&str> { + source.split('"').skip(1).step_by(2).collect() +} + +/// 把 `{占位符}` 抹掉再切 ASCII 词：占位符是**运行时数据**（pid / 原因 / 时间），不是文案。 +fn ascii_words(text: &str) -> Vec { + let mut stripped = String::new(); + let mut depth = 0usize; + for ch in text.chars() { + match ch { + '{' => depth += 1, + '}' if depth > 0 => depth -= 1, + _ if depth > 0 => {} + _ => stripped.push(ch), + } + } + + let mut words = Vec::new(); + let mut current = String::new(); + for ch in stripped.chars() { + if ch.is_ascii_alphabetic() { + current.push(ch); + } else if !current.is_empty() { + words.push(std::mem::take(&mut current)); + } + } + if !current.is_empty() { + words.push(current); + } + words +} + +/// 有没有中日韩统一表意文字（「这条文案真的翻成中文了吗」的最直接判据）。 +fn has_cjk(text: &str) -> bool { + text.chars().any(|c| { + matches!(c, '\u{3400}'..='\u{4DBF}' | '\u{4E00}'..='\u{9FFF}' | '\u{3000}'..='\u{303F}') + }) +} + +/// **中文界面无英文词**：实例页这一族的每一条中文译文，除了 [`ALLOWED`] 之外不许出现 ASCII 单词。 +/// +/// 抓得住：漏翻（中英写成一样）、翻了一半（`Present on disk` → `已在磁盘上 Present`）、 +/// 新加 key 时中文那栏顺手抄了英文。 +/// 抓不住：译文本身读着别扭；也抓不住「页面另写了一条字面量」（见模块文档的边界一节）。 +/// +/// **变异实测**（M120 交付时跑过）：把 `InstancesPresentOnDisk` 的中文改回 `Present on disk`， +/// 这条立刻红并指出 key 名。 +#[test] +fn the_chinese_page_has_no_english_words() { + let zh = Lang::ZhCn.catalog(); + let mut offenders = Vec::new(); + let mut checked = 0; + + for key in Texts::keys() { + let text = zh.text(key); + assert_ne!(text, MISSING, "{} 没有中文译文", key.name()); + checked += 1; + for word in ascii_words(text) { + if !ALLOWED.contains(&word.as_str()) { + offenders.push(format!("{} · 出现 {word:?} ← 「{text}」", key.name())); + } + } + } + + assert!( + offenders.is_empty(), + "中文界面上这些英文词会漏出来（品牌名 / 技术标识请加进 ALLOWED 并写明理由）：\n{}", + offenders.join("\n") + ); + assert!( + checked >= 30, + "实例页的 key 不该被成批删掉（只查到 {checked} 条）" + ); +} + +/// **切换语言，文本真的变**：这一族的每一条中英译文都必须不同。 +/// +/// 抓得住：翻完没改（两栏抄同一句）——那种 key 在切语言时**一个字都不动**，界面上看起来 +/// 「已经国际化」，其实那一处永远是英文。今夜反复出现的「测试绿着但什么都没守住」就是这一类。 +/// 抓不住：某条译文翻错了词。 +#[test] +fn every_instances_text_changes_with_the_language() { + let en = Lang::En.catalog(); + let zh = Lang::ZhCn.catalog(); + + for key in Texts::keys() { + let (a, b) = (en.text(key), zh.text(key)); + assert_ne!(a, MISSING, "{} 没有英文译文", key.name()); + assert_ne!(b, MISSING, "{} 没有中文译文", key.name()); + assert_ne!( + a, + b, + "{} 的两套语言写成了一样（{a:?}）——切语言时这一处不会变", + key.name() + ); + // 中文那栏必须真的有汉字——**整句只有品牌名时例外**（`InstancesMetaJava` = "Java"： + // 那一格的值域是 `Temurin 21` 这种品牌串，翻成「爪哇」是错的）。 + let brand_only = { + let words = ascii_words(b); + !words.is_empty() && words.iter().all(|word| ALLOWED.contains(&word.as_str())) + }; + assert!( + has_cjk(b) || brand_only, + "{} 的中文译文里一个汉字都没有：{b:?}", + key.name() + ); + } +} + +/// **数字与分隔符不随语言变形**：`Running · pid 1234` 的两套语言只换前半句。 +/// +/// 抓得住：把 `pid` 翻成「进程」、把 `·` 换成 `-`、把 `{pid}` 写成固定文字、少一个空格。 +/// 抓不住：真实 pid 的取值（那是 core 的事，出图那台机器上也没真跑过）。 +#[test] +fn the_running_line_keeps_its_number_and_separator() { + let en = Catalog::of(Lang::En).render(Key::InstancesRunning, &[("pid", "1234")]); + let zh = Catalog::of(Lang::ZhCn).render(Key::InstancesRunning, &[("pid", "1234")]); + + assert_eq!(en, "Running · pid 1234"); + assert_eq!(zh, "运行中 · pid 1234"); + assert_ne!(en, zh, "切换语言时这一行要变（只换标签本体）"); + for text in [en, zh] { + assert!(text.contains("1234"), "数字丢了：{text}"); + assert!(text.contains(" · pid "), "分隔符或 pid 变形了：{text}"); + } + + // 失败那一行同理：core 给的原因原文原样保留，只翻前半句 + let failed_en = Catalog::of(Lang::En).render(Key::InstancesFailed, &[("reason", "exit 1")]); + let failed_zh = Catalog::of(Lang::ZhCn).render(Key::InstancesFailed, &[("reason", "exit 1")]); + assert_eq!(failed_en, "Launch failed · exit 1"); + assert_eq!(failed_zh, "启动失败 · exit 1"); +} + +/// **页面里不许再写死界面文案**（白名单）：带 ASCII 单词的字面量必须在 [`ALLOWED_LITERALS`] 里。 +/// +/// 抓得住：①M120 之前那 29 条旧串被抄回页面（它们都带英文词 ⇒ 不在白名单 ⇒ 红）； +/// ②**任何新写的英文字面量**（r1 复审抓到的哑点：黑名单版本把 `"Ready"` 写进页面是全绿的）。 +/// 抓不住：中文写死的字面量（`"实例"` 没有 ASCII 词）——那要靠 `Texts::of(` 的反向锚与出图； +/// 也抓不住夹具数据（`pages/instances/data.rs` 故意不在扫描范围：那是**用户数据**的样子， +/// 不是界面文案，见该文件的模块文档）。 +/// +/// **变异实测（M120 r1 交付时跑过三条）**：写回 `"ALL INSTANCES"` ⇒ 红；写进一条全新的 +/// `"Ready"` ⇒ 红；把 `Texts::of(` 从实例页删掉 ⇒ 反向锚红。 +#[test] +fn every_english_literal_in_the_page_sources_is_whitelisted() { + let mut checked = 0; + for (name, source) in PAGE_SOURCES { + for literal in string_literals(source) { + if ascii_words(literal).is_empty() { + continue; + } + checked += 1; + assert!( + ALLOWED_LITERALS.contains(&literal), + "{name} 里的字面量 {literal:?} 带 ASCII 单词但不在白名单里：界面文案要走 Texts / 目录；确属专有名词的话加进 ALLOWED_LITERALS 并写明理由" + ); + } + } + + // 反向锚①：扫描器真的扫到了东西（否则上面那个循环是空转） + assert!( + checked >= 6, + "只扫到 {checked} 条带英文的字面量，扫描器可能失效了" + ); + + // 反向锚②：这些来源**必须**真的在用 Texts / 目录 + assert!( + PAGE_SOURCES[0].1.contains("Texts::of("), + "实例页没有从 Texts 取词" + ); + assert!( + PAGE_SOURCES[0].1.contains("Header::new(texts.title())"), + "页头标题必须是词表里的那条（`Header::new` 里写死字符串 = 中文界面上顶着英文标题）" + ); + assert!( + PAGE_SOURCES[3].1.contains("Key::Instances"), + "text.rs 没有引用本族的 key" + ); + assert!( + PAGE_SOURCES[4].1.contains("Key::InstancesStage"), + "阶段标签没有走目录" + ); +} + +/// **死 key 守门**：目录里每一条 `Instances*` 都必须被页面（或产品快照转换）真的引用。 +/// +/// M117 加的那七条就是这么沉的：目录里写着，页面上一个都没用。扫描是字面出现的 +/// `Key::<名字>`，所以用宏拼 key 名能骗过它——这个局限写在这里，不假装它更强。 +#[test] +fn every_instances_key_is_referenced_by_the_page() { + for key in Texts::keys() { + let needle = format!("Key::{}", key.name()); + assert!( + PAGE_SOURCES + .iter() + .any(|(_, source)| source.contains(&needle)), + "{needle} 在目录里定义了，但实例页没有任何地方用它（死 key，删掉或接上）" + ); + } +} diff --git a/crates/app-iced/src/pages/instances/text.rs b/crates/app-iced/src/pages/instances/text.rs new file mode 100644 index 0000000..b792445 --- /dev/null +++ b/crates/app-iced/src/pages/instances/text.rs @@ -0,0 +1,103 @@ +//! 实例页的**文案入口**：页面上一处可见英文字面量都不留，全部从目录取。 +//! +//! ## 为什么要有这一层（而不是在控件树里直接 `catalog.text(..)`） +//! +//! 页面要的文案有 20 多条，直接写的话每个调用点都是「key 名 + 这一处画什么」的重复劳动， +//! 而且**守门测试没法取样**：iced 0.14 的 `Element` 没有内省接口（`instances/tests.rs` 里 +//! 「读源码」那条注释解释过同一件事），所以「上屏文本」只能从**页面取词的那一个入口**拿。 +//! 于是所有取词收进 [`Texts`]，页面用 `texts.xxx()` 画，测试用同一个 `Texts` 断言—— +//! 一处定义、两处消费，不存在「测试抄了一份平行实现」。 +//! +//! ## 它抓得住什么 / 抓不住什么 +//! +//! - **抓得住**：目录里某条中文忘了翻（「无 ASCII 英文单词」）、某条中英写成一样（「切换语言文本真的变」）、 +//! `Running · pid {pid}` 的数字与分隔符被翻译走样、页面里写死**英文**字面量 +//! （`every_english_literal_in_the_page_sources_is_whitelisted`，白名单判定）； +//! - **抓不住**：页面里写死的**中文**字面量（没有 ASCII 词，扫不到）、`PAGE_SOURCES` 五个文件 +//! 之外的东西（如 `data.rs` 夹具数据）、译文翻得顺不顺——这些只能靠出图人工看 +//! （`DevDocs/artifacts/m120/`）。 +//! +//! ## 口径 +//! +//! 品牌名不翻译（`Java` / `Fabric` / `Forge` 原样）；`pid` 是进程号的技术标识，两套语言都写 +//! `pid`（改成「进程」会丢掉「拿它去任务管理器里搜」这条可操作性）。 +//! +//! **启动阶段（下载中 / 校验中 / …）不在这张表里**：它在 `app/view/instances.rs` 拼进 +//! `Row.status`（「阶段 · 百分比」是一整句），与元信息卡同一层——页面只画模型给的字符串。 + +use unlucky_i18n::{Catalog, Key}; + +/// 实例页 + 详情列的文案（一个 `Catalog` 的薄包装，`Copy`）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(crate) struct Texts(Catalog); + +impl Texts { + /// 从目录取一套（调用方给 `model.lang.catalog()`）。 + pub(super) fn of(catalog: Catalog) -> Self { + Self(catalog) + } + + // ------------------------------------------------------------- 页头 + pub(super) fn title(self) -> &'static str { + self.text(Key::InstancesTitle) + } + pub(super) fn subtitle(self) -> &'static str { + self.text(Key::InstancesSubtitle) + } + pub(super) fn new_instance(self) -> &'static str { + self.text(Key::InstancesNew) + } + pub(super) fn import(self) -> &'static str { + self.text(Key::InstancesImport) + } + + // --------------------------------------------------------------- 列表列 + pub(super) fn all_title(self) -> &'static str { + self.text(Key::InstancesAllTitle) + } + + // --------------------------------------------------------------- 详情列 + pub(super) fn back(self) -> &'static str { + self.text(Key::InstancesBack) + } + pub(super) fn play(self) -> &'static str { + self.text(Key::InstancesPlay) + } + pub(super) fn stop(self) -> &'static str { + self.text(Key::InstancesStop) + } + pub(super) fn duplicate(self) -> &'static str { + self.text(Key::InstancesDuplicate) + } + pub(super) fn open_folder(self) -> &'static str { + self.text(Key::InstancesOpenFolder) + } + pub(super) fn delete(self) -> &'static str { + self.text(Key::InstancesDelete) + } + pub(super) fn empty_title(self) -> &'static str { + self.text(Key::InstancesEmptyTitle) + } + pub(super) fn empty_body(self) -> &'static str { + self.text(Key::InstancesEmptyBody) + } + pub(super) fn narrow_note(self) -> &'static str { + self.text(Key::InstancesNarrowNote) + } + + fn text(self, key: Key) -> &'static str { + self.0.text(key) + } + + /// 这一页的全部 key（守门测试的取样口：**从 `Key::ALL` 过滤出来**，不是手抄一份清单）。 + /// + /// 域判据是前缀 `Instances`——本族的 key 名是契约（`catalog/instances.rs` 里一条一条写着）， + /// 新加的 key 只要还在这个族里就自动进守门范围，不需要有人记得来登记。 + #[cfg(test)] + pub(super) fn keys() -> impl Iterator { + Key::ALL + .iter() + .copied() + .filter(|key| key.name().starts_with("Instances")) + } +} diff --git a/crates/app-iced/src/pages/layout.rs b/crates/app-iced/src/pages/layout.rs new file mode 100644 index 0000000..4c55fed --- /dev/null +++ b/crates/app-iced/src/pages/layout.rs @@ -0,0 +1,399 @@ +//! 页面布局系统：**窗口宽度档位 → 版面 → 列宽**。纯函数，不碰 iced 控件树。 +//! +//! 这是本 mission 的核心交付物，四个页面只是它的用例。`layout.rs` 是页面级几何的 +//! **唯一定义点**：页面文件里不许再出现列宽字面量。 +//! +//! ## 1. 宽度档位（官方响应式断点 600 / 840） +//! +//! 档位定义照官方 M3「Window size classes」（A 级：m3.material.io 的 app-quality/window-size-classes， +//! Compose `WindowSizeClass` 的同一组硬值）：**600dp 与 840dp** 是两个分界。 +//! +//! | 档位 | 窗口宽度（逻辑 px @100% DPI） | 页边距（gutter） | +//! |---|---|---| +//! | `Compact` | `< 600` | 16（`Space::X4`） | +//! | `Medium` | `600 ≤ w < 840` | 24（`Space::X6`） | +//! | `Expanded` | `≥ 840` | 24（`Space::X6`） | +//! +//! 页边距取 16/24 而不是 16/24/32：官方 expanded 页边距也是 24，写 32 会白白多一条偏离登记。 +//! +//! > 本 crate 的真实窗口下限是 880（`app.rs` 的 `MIN_SIZE`），所以日常只有 `Expanded`； +//! > 600 以下的档位是给「将来允许更窄窗口 / 内嵌面板」准备的，也让布局规则**可测**。 +//! +//! ## 2. 三种版面与「什么宽度用哪种」 +//! +//! | 版面 | 含义 | 页面上用它 | 成立条件 | 退化到 | +//! |---|---|---|---|---| +//! | `SingleColumn` | 单列，列宽 ≤ 行宽上限 | 下载 / 日志（全部档位）；实例 / 设置（窄窗） | 总是成立 | — | +//! | `SupportingPane` | 主列 + 窄侧列（侧列是辅助，主列是阅读对象） | 设置（分组导航 240 + 表单列） | `w ≥ 600` 且 `w ≥ 720` | `SingleColumn` | +//! | `ListDetail` | 固定列表列（320~360，**独立滚动**）+ 详情列 | 实例 | `w ≥ 840` 且 `w ≥ 816` | `SingleColumn` | +//! +//! 两个门槛都是**算出来的**，不是拍的（见 [`panes_min_window`]）： +//! +//! - 设置：`240（drawer）+ 24（间隙）+ 320（表单列下限）+ 2×24（gutter）+ 88（rail）= 720`； +//! - 实例：`336（列表列）+ 24（间隙）+ 320（详情列下限）+ 2×24（gutter）+ 88（rail）= 816`。 +//! +//! 实例的几何门槛 816 低于官方 expanded 断点 840 —— 所以**档位是更严的那一条**， +//! 单测 `expanded_is_wide_enough_for_list_detail` 把这条「余量 24px」钉死。 +//! +//! ## 3. 行宽约束（历史事故：M68 的全宽单卡） +//! +//! M68 骨架的内容区是**一张全宽卡**：卡片横跨 x=112..1156（**1044px**），卡片内文本区 **1004px** +//! （边距 24 + 卡片内边距 20）。那张卡里的正文是 `BodySmall` 12px：步进 = 14px 实测值 +//! 6.0526 × 12/14 = **5.19px/字符**，所以 137 字符 × 5.19 ≈ **711px** —— 与 +//! `DevDocs/ops/screens-m68/shell-light-cpu.png` 里那一行**实测 ink 712px**（x=133..845）吻合。 +//! 视觉复审的判词因此是「**不能把全宽单卡当页面模板**，官方桌面口径是 supporting-pane / list-detail」。 +//! +//! > **两个订正记录**（P2 复审抓出）：① **712 是那行的墨迹宽，不是列宽**（列宽 1004；旧文档的减法得 1044）； +//! > ② 那行是 **137 字符**（12px × 0.4323em = 5.19px/字符），早期拿 `0.5em` 估算既高估步进、也错了字号。 +//! > 现在事故描述一律用**实测步进 × 实际字号**——这也是 `line_length_is_capped_at_72_characters` +//! > 里那条「旧口径 504px 能放 83 字符」护栏的由来。 +//! +//! ### 逐行口径：72 字符是**最长一行**的上界，不是平均（r2 复审的教训） +//! +//! 「平均步进 × 72」只能保证**平均**一行 72 字符：r2 复审在交付图里抓到一行 **73 字符** +//! （`guess. Nothing on this page is wired to real data yet: the layout is, the`，ink 428px）。 +//! 所以上限**不是算术结果，而是逐行折行模拟的结果**——用 FreeType 量宽 + 贪心词折行， +//! 对实例页那段正文（361 字符）扫不同列宽： +//! +//! | 列宽 | 最长一行 | 该行 ink | 结论 | +//! |---|---|---|---| +//! | 435（= 平均口径上界） | 73 字符 | 428px | ✗ 破了 72 | +//! | 428 | 73 字符 | 428px | ✗ | +//! | 426 | 71 字符 | 426px | ✓ 但只剩 1 字符余量 | +//! | **424**（4px 栅格） | **67 字符** | **402px** | ✓ 取这个：满足上界 + 留 5 字符余量 | +//! +//! 于是 [`measure_cap_px`] = **424**（= `min(逐行安全宽 424, 平均口径上界 435)`），由 +//! [`content_column_width`] 与 [`frame_metrics`] 无条件施加：任何窗口宽度、任何版面， +//! 正文列都不会超过它。1180 宽窗口下正文列是 **424**（不是 712）。 +//! +//! **作用域**：这条承诺只覆盖 `BodyMedium` 14px 的正文。`BodySmall` 12px 的辅助文案 +//! （空态副文案、窄窗提示）在同一列宽下每行可到 ~82 字符——它们都是 1~2 行的短句，不做逐行承诺； +//! 中文（全角 1em）另算，等 i18n mission 定。 +//! +//! ### M102 订正：`column` 是**正文（prose）列宽**，不是页面块宽 +//! +//! 视觉复审抓到「正文列左缘 423 对标题 110」，根因是**把 424 当成整页块宽再居中**。 +//! 现在三个量分开，口径与常量全在 [`block`]（本文件只留指针，免得文档把 file-size 门禁顶到红线）。 +//! +//! ### 步进是怎么量的（口径 + 可复现） +//! +//! - **测的是哪组字形**：`BodyMedium` 的字体栈（本机解析到 Segoe UI **Regular**，14px）， +//! **无 letter-spacing**——令牌的 0.5px 字距 iced 0.14 不支持（已登记的令牌丢失），渲染里没有； +//! - **样本**：实例页详情那段正文（`pages/instances/data.rs` 的 `NOTE`，**361 字符**， +//! 大小写 / 标点 / 空格 / `→` 混排，是我们自己的真实正文，不是造出来的 `mmmm`）； +//! - **量法**：FreeType `getlength`（PIL `ImageFont.truetype(segoeui.ttf, 14)`）求整段排版宽， +//! 再除以字符数 → **2185.00px / 361 = 6.0526 px/字符 = 0.43233em**；× 72 = 435.79（这是**平均**口径上界，逐行口径见下）； +//! - **交叉验证**：同一段的首行（78 字符）渲染实测墨迹 **484px**，FreeType 对同一串给 479px +//! （差 ~1%，抗锯齿外扩），说明「步进」这个口径在 iced 渲染器与 FreeType 之间是一致的； +//! - **CJK 不适用**：全角字形是 1em（14px），中文的 72 字符是 1008px。页面文案走 i18n 之后 +//! 要按语言分别定上限，这条留给 i18n mission；本模块只保证英文基线。 + +use unlucky_design::spacing::{LayoutMetrics, Space}; +use unlucky_design::typography::TypeRole; + +pub mod block; +pub mod wrap; + +#[cfg(test)] +pub(crate) mod source; + +/// 官方 M3 窗口档的 medium 断点（600dp）。 +pub const BREAKPOINT_MEDIUM: f32 = 600.0; +/// 官方 M3 窗口档的 expanded 断点（840dp）。 +pub const BREAKPOINT_EXPANDED: f32 = 840.0; + +/// 列表列宽（list-detail 左列）。任务区间 320~360，取 4px 栅格内的 **336**： +/// 落在区间中段，既放得下「名字 + 版本 + 尾随图标」，又给详情列多留 16px。 +pub const LIST_COLUMN_WIDTH: f32 = 336.0; + +/// 详情列下限：再窄就不再分栏。 +/// +/// 按实测步进算：45 字符 × 6.05px ≈ 272，取 4px 栅格并留余量 → **320** +/// （320 / 6.05 = 53 字符，仍在行宽下限之上）。 +pub const DETAIL_MIN_WIDTH: f32 = 320.0; + +/// 侧列宽（设置页分组导航）= D33 的 drawer 宽 240。 +/// +/// 复用 rail 的**尺寸语义**（88 ⇄ 240 同一容器的两种形态），但**不复制 rail 的实现**： +/// 分组导航是页内元素，没有 hover 药丸、没有二级标签。 +pub const SIDE_NAV_WIDTH: f32 = LayoutMetrics::DESKTOP.nav_drawer_width; + +/// 表单列下限（supporting-pane 主列）：与详情列下限同源（320 ≈ 45 字符）。 +pub const FORM_MIN_WIDTH: f32 = DETAIL_MIN_WIDTH; + +/// 两列之间的间隙（`Space::X6` = 24）。 +pub const PANES_GAP: f32 = Space::X6.dp(); + +/// 详情里元信息网格的**单卡最小宽度 = 由卡内最长内容反推**：**160**。 +/// +/// 推导（不是凑出来的）： +/// - 卡内最长值是 demo 里的 `NeoForge 20.4.237`，Segoe UI 14px 实测 **118px**； +/// - 卡两侧内边距 `LayoutMetrics::card_padding` = 20，故最小外框 = 118 + 2×20 = **158**； +/// - 取 4px 栅格的 **160**（等价于旧值，但这次是**内容推出来的**，不是凑上限凑出来的）。 +/// +/// r2 复审抓到的回归：上一轮为了塞三列把这里收到 136，忘了算 padding —— +/// 卡内只剩 96px，`NeoForge 20.4.237`（118px）与 `NeoForge 21.1.72`（110px）都会折成两行， +/// 同排另两张卡仍一行 → **卡底不齐**。160 之下 3 列要 3×160 + 2×12 = 504，超出行宽上限， +/// 所以元信息网格在 1180 宽是 **2 列**（2×160 + 12 = 332，卡内可排 166px，装得下 118）。 +/// 这也是有意的：mod 加载器版本串只会更长，2 列宽卡比 3 列挤卡更抗将来。 +pub const META_CARD_MIN_WIDTH: f32 = 160.0; +/// 元信息网格卡片间距（`Space::X3` = 12）。 +pub const META_GAP: f32 = Space::X3.dp(); + +/// 正文平均字符步进（em）——**实测值**，口径见模块文档 §3。 +/// +/// `BodyMedium` 14px / Segoe UI Regular / 361 字符英文混排正文，FreeType 实测 +/// **6.0526px/字符 = 0.43233em**。 +/// +/// 旧的 `0.5`（`[估]`）把 72 字符的列宽算成 504px，而实测 504px 能塞 **83 字符**—— +/// 「72 字符」这个名字和数字对不上的根因就在这里。换字体栈要重新量（这不是令牌）。 +pub const CHAR_ADVANCE_EM: f32 = 0.43233; +/// 舒适行宽的字符数上限（任务建议 60~72，取上界 72）。 +pub const MAX_MEASURE_CHARS: f32 = 72.0; +/// 行宽下限的字符数（再窄正文就碎成短行，45 是最低可读长度）。 +pub const MIN_MEASURE_CHARS: f32 = 45.0; + +/// 导航轨宽度（与 `shell::nav` 同一令牌值；布局系统只读它，不重定义）。 +pub const fn rail_width() -> f32 { + LayoutMetrics::DESKTOP.nav_rail_width +} + +/// **逐行**安全宽度（px）：折行模拟下「最长一行 ≤72 字符」的最大 4px 栅格列宽 = **424**。 +/// +/// 见模块文档 §3 的模拟表：428 会出现 73 字符行，426 起降到 71，424 给到 67（留 5 字符余量）。 +/// 这个数是**量出来的**，不是 `advance × 72` 算出来的——后者只保证平均。 +pub const LINE_SAFE_WIDTH_PX: f32 = 424.0; + +/// 平均口径上界（px）：`floor(14px × 0.43233em × 72)` = **435**。 +/// +/// 只能保证**平均**一行 72 字符（实测 435 下会冒出 73 字符行），所以它是上界而不是取值。 +pub fn measure_average_bound_px() -> f32 { + (TypeRole::BodyMedium.style().size_px * CHAR_ADVANCE_EM * MAX_MEASURE_CHARS).floor() +} + +/// 正文列宽上限（px）= `min(逐行安全宽 424, 平均口径上界 435)` = **424**。 +/// +/// 硬上限，任何版面 / 任何窗口宽度都不许超；`1180` 窗宽下正文列就是它（而非 M68 的 712）。 +pub fn measure_cap_px() -> f32 { + LINE_SAFE_WIDTH_PX.min(measure_average_bound_px()) +} + +/// 正文列宽下限（px）：`floor(14 × 0.43233 × 45)` = **272**。 +pub fn measure_floor_px() -> f32 { + (TypeRole::BodyMedium.style().size_px * CHAR_ADVANCE_EM * MIN_MEASURE_CHARS).floor() +} + +/// 窗口宽度档位（官方 600 / 840 两个断点）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum WidthClass { + /// `< 600` + Compact, + /// `600 ≤ w < 840` + Medium, + /// `≥ 840` + Expanded, +} + +impl WidthClass { + /// 按**窗口宽度**（含导航轨，逻辑 px）判档。 + pub fn of(window_width: f32) -> Self { + if window_width < BREAKPOINT_MEDIUM { + Self::Compact + } else if window_width < BREAKPOINT_EXPANDED { + Self::Medium + } else { + Self::Expanded + } + } + + /// 稳定名字（日志/测试/文件名用）。 + pub const fn name(self) -> &'static str { + match self { + Self::Compact => "compact", + Self::Medium => "medium", + Self::Expanded => "expanded", + } + } + + /// 页边距：compact 16 / medium 24 / expanded 24（官方 expanded 也是 24）。 + pub const fn gutter(self) -> f32 { + match self { + Self::Compact => Space::X4.dp(), + Self::Medium | Self::Expanded => Space::X6.dp(), + } + } +} + +/// 三种版面。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum PageLayout { + /// 单列（列宽 ≤ 行宽上限，水平居中）。 + SingleColumn, + /// 主列 + 辅助侧列。 + SupportingPane, + /// 固定列表列 + 详情列。 + ListDetail, +} + +impl PageLayout { + /// 稳定名字。 + pub const fn name(self) -> &'static str { + match self { + Self::SingleColumn => "single-column", + Self::SupportingPane => "supporting-pane", + Self::ListDetail => "list-detail", + } + } + + /// 是否有两个列（侧列 + 主列）。 + pub const fn is_two_pane(self) -> bool { + !matches!(self, Self::SingleColumn) + } +} + +/// 页面声明的「最宽版面」——布局系统按窗口宽度降级。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum PaneKit { + /// 单列页（下载 / 日志）。 + Single, + /// 主列 + 侧列（设置）。 + Supporting, + /// 列表 + 详情（实例）。 + ListDetail, +} + +/// 两列版面成立所需的最小窗口宽度（**公式**，不是拍值）： +/// `Σ列宽 + 间隙 + 2×gutter + rail`。 +pub fn panes_min_window(first: f32, second: f32) -> f32 { + first + second + PANES_GAP + 2.0 * WidthClass::Expanded.gutter() + rail_width() +} + +/// `ListDetail` 的几何门槛：336 + 320 + 24 + 48 + 88 = **816**。 +pub fn list_detail_min_window() -> f32 { + panes_min_window(LIST_COLUMN_WIDTH, DETAIL_MIN_WIDTH) +} + +/// `SupportingPane` 的几何门槛：240 + 320 + 24 + 48 + 88 = **720**。 +pub fn supporting_pane_min_window() -> f32 { + panes_min_window(SIDE_NAV_WIDTH, FORM_MIN_WIDTH) +} + +/// 版面决议：档位与几何门槛**同时**满足才升到两列，否则退化单列。 +pub fn resolve(kit: PaneKit, window_width: f32) -> PageLayout { + let class = WidthClass::of(window_width); + let wide_enough = match kit { + PaneKit::Single => false, + PaneKit::Supporting => { + class != WidthClass::Compact && window_width >= supporting_pane_min_window() + } + PaneKit::ListDetail => { + class == WidthClass::Expanded && window_width >= list_detail_min_window() + } + }; + + match (kit, wide_enough) { + (PaneKit::Single, _) | (_, false) => PageLayout::SingleColumn, + (PaneKit::Supporting, true) => PageLayout::SupportingPane, + (PaneKit::ListDetail, true) => PageLayout::ListDetail, + } +} + +/// 页面可用宽度：窗口 − 导航轨 − 两侧页边距（下限 0）。 +pub fn available_width(window_width: f32) -> f32 { + let class = WidthClass::of(window_width); + (window_width - rail_width() - 2.0 * class.gutter()).max(0.0) +} + +/// **给定窗口宽度 → 内容（正文）列宽**。本 mission 的「行宽约束」入口。 +/// +/// - 单列页：就是正文列宽（水平居中摆放）； +/// - 两列页：这是**主列**的正文列宽；实际值还要看 [`frame_metrics`]（详情列会被列表列挤窄）。 +/// +/// 返回值永远 ≤ [`measure_cap_px`]：1180 窗宽下是 424（逐行 67 字符，≤72），不是 M68 的 712。 +pub fn content_column_width(window_width: f32) -> f32 { + available_width(window_width).min(measure_cap_px()) +} + +/// 元信息网格的列数：3 列需要 504（超出行宽上限，1180 下用不到），2 列需要 332，否则 1 列。 +pub fn meta_columns(width: f32) -> usize { + for columns in [3usize, 2] { + let needed = columns as f32 * META_CARD_MIN_WIDTH + (columns - 1) as f32 * META_GAP; + if width >= needed { + return columns; + } + } + 1 +} + +/// 一屏的版面几何（页面直接消费，不再自己算列宽）。 +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct FrameMetrics { + /// 窗口宽度（输入）。 + pub window_width: f32, + /// 宽度档位。 + pub class: WidthClass, + /// 决议出来的版面。 + pub layout: PageLayout, + /// 页边距。 + pub gutter: f32, + /// 页面可用宽度（已扣导航轨与页边距）。 + pub available: f32, + /// 正文列宽（≤ 行宽上限）。两列版面时是**主列**的正文列宽。 + pub column: f32, + /// 第二列（list-detail 的列表列 / supporting-pane 的侧列）。 + pub secondary: Option, + /// 主列所在 pane 的宽度（单列 = 正文列宽）。 + pub main_pane: f32, + /// 详情元信息网格列数。 + pub meta_columns: usize, +} + +/// 一次算齐版面几何。 +pub fn frame_metrics(kit: PaneKit, window_width: f32) -> FrameMetrics { + let class = WidthClass::of(window_width); + let gutter = class.gutter(); + let available = available_width(window_width); + let layout = resolve(kit, window_width); + + let (column, secondary, main_pane) = match layout { + PageLayout::SingleColumn => { + let column = available.min(measure_cap_px()); + (column, None, column) + } + PageLayout::ListDetail => { + let list = LIST_COLUMN_WIDTH.min(available); + let pane = (available - list - PANES_GAP).max(0.0); + (pane.min(measure_cap_px()), Some(list), pane) + } + PageLayout::SupportingPane => { + let side = SIDE_NAV_WIDTH.min(available); + let pane = (available - side - PANES_GAP).max(0.0); + (pane.min(measure_cap_px()), Some(side), pane) + } + }; + + FrameMetrics { + window_width, + class, + layout, + gutter, + available, + column, + secondary, + main_pane, + meta_columns: meta_columns(column), + } +} + +/// 版本管理页的**页内**三栏几何（版本类型栏 / 主版本栏 / 列表列）。 +/// +/// 页面级版面只有三种（[`PageLayout`]），而版本管理页要在单列里再切三栏——那次裁决住在这里， +/// 与 `PaneKit` 分开：`PaneKit` 决定「页面占多宽」，[`rails`] 决定「这宽度怎么切成三栏」。 +pub mod rails; + +pub use rails::{ + VersionRailTier, VersionRails, MAJOR_RAIL_WIDTH, RAIL_GAP, RAIL_ICON_WIDTH, TYPE_RAIL_WIDTH, +}; + +#[cfg(test)] +mod tests; diff --git a/crates/app-iced/src/pages/layout/block.rs b/crates/app-iced/src/pages/layout/block.rs new file mode 100644 index 0000000..7b4fae6 --- /dev/null +++ b/crates/app-iced/src/pages/layout/block.rs @@ -0,0 +1,83 @@ +//! 页面块几何：**块宽 / 块偏移 / 散文列宽**（纯函数，不碰 iced 控件树）。 +//! +//! ## 为什么这三个量单独住一个文件（M102 r2） +//! +//! M102 把「一句话多宽」和「整页块多宽」拆成两个量，那段口径原本写在 `layout.rs` 的模块文档里， +//! 连同 1440 上限一起把主文件顶到 **399 行**（CI 的 file-size 门禁是 `wc -l`，只剩 1 行余量）。 +//! 挪到本文件：主文件回到安全线以下，**口径与常量同处一室**——谁改上限都得读同一段话。 +//! +//! ## 三个量（页面只许从这里取，不许自己算） +//! +//! | 量 | 值 | 用在哪 | +//! |---|---|---| +//! | [`body_width`] | `min(pane, 1440)`；pane = `available`（单列）/ `main_pane`（两列） | 页面块：Tabs / 列表 / 卡片 / 分隔线 | +//! | [`body_offset`] | **0**（贴左） | 块的左缘相对页边距的偏移 —— 0 就是「与页头标题同一条线」 | +//! | [`prose_width`] | [`FrameMetrics::column`]（≤424） | 成段散文（`frame::prose`），保证一行 ≤72 字符 | +//! +//! ## 为什么 1440 是上限（tower 拍板，M102 r2） +//! +//! 块宽**没有上限**时，2560 窗宽下单列页的块会一路长到 2424px：一行 80 个英文字符的列表行 +//! 空得发慌，中文正文同一行更能排到 170 字。取 **1440**（落在 4px 栅格上，= 360 × 4）： +//! 在 1180（可用 1044）与 900（764）上**都不生效**，只拦极宽窗。 +//! +//! 与 [`super::measure_cap_px`]（424，用 FreeType 实测步进 × 逐行折行模拟推出来的）不同， +//! 1440 是**决策值**不是量出来的：它没有排版学推导，只有「别让列表行排成一条高速路」这一条理由。 +//! 所以它只该在这一处出现——谁想改，改这里并同时改 `block/tests.rs` 的断言。 +//! +//! 贴左不变：块左缘仍是 `rail 88 + gutter 24 = 112`，封顶后**右侧留白**（不是居中）。 +//! 这是有意的：页头标题在左，正文块跟着左缘；把块居中又会回到视觉复审 ① 的「内容缩在中间」。 +//! +//! ## 这一层唯一的行为变化，以及它从哪一版开始 +//! +//! 封顶是 M102 r2 引入的**有意行为变化**：`≥ 1576` 窗宽（`112 + 1440 + 24`）下块宽不再跟随可用宽度。 +//! 在 1180 / 900 上它**不生效**——那两张验收图与 r1 逐字节相同（9/9 `cmp`）。所以对外口径是 +//! 「**≤1440 窗宽零像素变化；更宽的窗口按本上限有意改变**」，不是笼统的「零变化」。 +//! （`frame::body` 那行 `padding(left(body_offset))` 在同一轮加进来，值恒 0 ⇒ 像素中性。） +//! +//! ## 偏移为什么是个常量函数而不是 `align_x` +//! +//! iced 的 `Element` **没有几何内省接口**，「块摆在哪」在单测里量不到。所以把「贴左」写成一个 +//! 可断言的纯量 [`body_offset`]（= 0），让 `frame::body` 从它建盒，再配一条**源码结构**断言 +//! （`pages/tests.rs::frame_body_is_built_from_the_block_quantities`）钉住「盒子的左内边距来自它」。 +//! 变异实测：把 `frame::body` 换回 `centered(metrics.column, …)`（视觉复审 ① 的原样）⇒ 该断言红。 + +use super::{FrameMetrics, PageLayout}; + +/// 页面块宽度上限（逻辑像素，4px 栅格的 1440 = 360dp × 4）。 +/// +/// 只拦极宽窗：1180 窗宽下可用 1044、900 下 764，都够不到它。 +pub const BODY_MAX_WIDTH: f32 = 1440.0; + +/// 页面块宽度（px）：pane 宽封顶 1440。 +/// +/// 单列 = 整条可用宽度；两列 = 主列 pane（列表列 / 侧列已被扣掉）。 +pub fn body_width(metrics: FrameMetrics) -> f32 { + let pane = match metrics.layout { + PageLayout::SingleColumn => metrics.available, + PageLayout::SupportingPane | PageLayout::ListDetail => metrics.main_pane, + }; + + if pane < BODY_MAX_WIDTH { + pane + } else { + BODY_MAX_WIDTH + } +} + +/// 页面块相对页边距的**左偏移**（px）：恒为 **0**（贴左）。 +/// +/// 「贴左」是 M102 的头号交付（视觉复审 ① 是「424 居中 ⇒ 左缘 422 对标题 112」）， +/// 所以它必须是一个能被断言的数，而不是一处 `align_x` 的写法。 +pub const fn body_offset(_metrics: FrameMetrics) -> f32 { + 0.0 +} + +/// 散文块宽度（px）= [`FrameMetrics::column`]（≤424 ⇒ 逐行 ≤72 字符）。 +/// +/// 与 [`body_width`] 是两个量：块可以是 1044，一句话仍然只排 424。 +pub const fn prose_width(metrics: FrameMetrics) -> f32 { + metrics.column +} + +#[cfg(test)] +mod tests; diff --git a/crates/app-iced/src/pages/layout/block/tests.rs b/crates/app-iced/src/pages/layout/block/tests.rs new file mode 100644 index 0000000..6c2a652 --- /dev/null +++ b/crates/app-iced/src/pages/layout/block/tests.rs @@ -0,0 +1,89 @@ +//! `block` 的断言：三个纯量的数值口径。 +//! +//! 「块摆在哪」量不到（iced 无 Element 内省），所以这里只钉**数**； +//! 「盒子是不是照这个数摆的」由 `pages/tests.rs` 的源码结构断言负责 +//! （`frame_body_is_built_from_the_block_quantities`）。 + +use super::*; +use crate::pages::layout::{frame_metrics, measure_cap_px, rail_width, PaneKit}; + +/// 贴左：**任何**版面、任何窗宽，块偏移都是 0。 +/// +/// 抓得住：有人把偏移改成居中/右对齐（那它就不再是 0）； +/// 抓不住：`frame::body` 有没有真的用这个数（源码结构断言负责）。 +#[test] +fn the_block_is_always_left_aligned() { + for kit in [PaneKit::Single, PaneKit::Supporting, PaneKit::ListDetail] { + for width in [320.0, 600.0, 720.0, 840.0, 900.0, 1180.0, 1440.0, 2560.0] { + assert_eq!( + body_offset(frame_metrics(kit, width)), + 0.0, + "{kit:?} @{width} 的块偏移必须贴左" + ); + } + } +} + +/// 块宽 = pane 宽（单列 = 可用宽度，两列 = 主列 pane），未到上限时不缩水。 +#[test] +fn body_width_is_the_pane_until_the_cap() { + for width in [320.0, 600.0, 840.0, 1180.0] { + let single = frame_metrics(PaneKit::Single, width); + assert_eq!(body_width(single), single.available, "单列 @{width}"); + assert_eq!(body_offset(single), 0.0, "@{width}"); + } + + // 两列版面：块宽 = 主列 pane（低于门槛时 list-detail 会退化成单列，那时块宽回到可用宽度） + let two = frame_metrics(PaneKit::ListDetail, 1180.0); + assert_eq!(body_width(two), two.main_pane); + assert!(two.main_pane < two.available); + let degraded = frame_metrics(PaneKit::ListDetail, 700.0); + assert_eq!(body_width(degraded), degraded.available); + + // 1440 上限只拦极宽窗：1180 可用 1044、2560 可用 2424 + assert_eq!(frame_metrics(PaneKit::Single, 1180.0).available, 1044.0); + assert_eq!(frame_metrics(PaneKit::Single, 2560.0).available, 2424.0); + assert_eq!( + body_width(frame_metrics(PaneKit::Single, 2560.0)), + BODY_MAX_WIDTH + ); + // 两列版面同样封顶（2560 下主列 pane 是 2064） + let wide_two = frame_metrics(PaneKit::ListDetail, 2560.0); + assert!(wide_two.main_pane > BODY_MAX_WIDTH); + assert_eq!(body_width(wide_two), BODY_MAX_WIDTH); + + // 封顶之后左缘不变、右侧留白（不是居中） + let huge = frame_metrics(PaneKit::Single, 2560.0); + let left = rail_width() + huge.gutter; + assert_eq!(left, 112.0); + let right_gap = 2560.0 - (left + body_width(huge)) - huge.gutter; + assert_eq!(right_gap, 984.0, "2560 宽下封顶后右侧留白"); + assert!(right_gap > 900.0); +} + +/// 散文列宽 = `FrameMetrics::column`，永远 ≤ 行宽上限（与块宽脱钩）。 +#[test] +fn prose_width_stays_at_the_measure_cap() { + for width in [600.0, 840.0, 900.0, 1180.0, 2560.0] { + let metrics = frame_metrics(PaneKit::Single, width); + assert_eq!(prose_width(metrics), metrics.column, "@{width}"); + assert!(prose_width(metrics) <= measure_cap_px()); + } + + // 块已经封顶的地方，散文列仍是 424 —— 两个量确实分开了 + let huge = frame_metrics(PaneKit::Single, 2560.0); + assert_eq!(body_width(huge), BODY_MAX_WIDTH); + assert_eq!(prose_width(huge), measure_cap_px()); + assert_eq!(prose_width(huge), 424.0); +} + +/// 上限本身：在 4px 栅格上，且远宽于散文列（否则「把两个量拆开」这件事是白做的）。 +#[test] +fn the_cap_is_on_the_grid_and_far_wider_than_the_measure() { + assert_eq!(BODY_MAX_WIDTH % 4.0, 0.0, "块宽上限必须在 4px 栅格上"); + assert!( + BODY_MAX_WIDTH >= measure_cap_px() * 3.0, + "块宽上限 {BODY_MAX_WIDTH} 必须远宽于散文列 {}", + measure_cap_px() + ); +} diff --git a/crates/app-iced/src/pages/layout/rails.rs b/crates/app-iced/src/pages/layout/rails.rs new file mode 100644 index 0000000..951f1a2 --- /dev/null +++ b/crates/app-iced/src/pages/layout/rails.rs @@ -0,0 +1,227 @@ +//! 版本管理页的**三栏几何**：版本类型栏 + 主版本栏 + 列表列。纯函数，不碰 iced 控件树。 +//! +//! 这一页是 `PaneKit::Single` 之外的第二种「页内分栏」：外层仍是单列（页头铺满页宽）， +//! 正文自己切成三栏。所以它不能复用 [`super::PaneKit`]（那是**页面级**版面决议）， +//! 而是在可用宽上再做一次**页内**裁决 —— 本文件就是那次裁决的唯一真源。 +//! +//! ## 1. 两个侧栏的宽度 +//! +//! | 栏 | 展开 | 收成图标条 | 依据 | +//! |---|---|---|---| +//! | 版本类型栏 | **140** | **64** | 140 = `12b §7` drawer 项「图标 24 + 间距 12 + 8 字符标签」；`Snapshot` 是最长标签（8 字符 ≈ 62px），24+12+62+2×16 内边距 = 130，取 4px 栅格 **140** | +//! | 主版本栏 | **140** | **64** | 同一档宽度：主版本是 `1.21` 这种 3~5 字符的短串，140 里放得下「主版本 + 该组版本数」两行；64 里只放得下版本号本身（40 可用宽够 4 字符 `LabelMedium`） | +//! +//! 64 = `LayoutMetrics::nav_rail_width` 的一半再对齐栅格？**不是**：64 是 4px 栅格上的 +//! 「图标 24 + 两侧内边距 2×16 + 余量 8」，比导航轨 88 窄一档（导航轨要放 56 宽的选中药丸， +//! 页内侧栏只要 40 宽的选中条）。 +//! +//! ## 2. 四档与各自的门槛（门槛都是**算出来的**） +//! +//! 记 `A` = **页面块宽**（[`super::block::body_width`](super::block::body_width) = 可用宽 +//! 封顶 1440，M102 的口径；≤1440 时它就是可用宽，所以下面这张表在 1180/1024/900/700 上不变）。 +//! +//! | 档 | 门槛 | 类型栏 | 主版本栏 | 列表列 | +//! |---|---|---|---|---| +//! | `Wide` | `A ≥ 888` | 140 | 140 | `A − 328` | +//! | `Narrow` | `676 ≤ A < 888` | **64** | 140 | `A − 252` | +//! | `Compact` | `600 ≤ A < 676` | 64 | **64** | `A − 176` | +//! | `Chips` | `A < 600` | 0 | 0 | `A` | +//! +//! 三个门槛的来源（`L` = 列表列下限 [`version_list_min_width`] = 行宽上限 **424**）： +//! +//! - `888` = `available_width(1024)`：任务给的产品口径「≫1024 两栏都展开」，换成可用宽就是它； +//! - `676` = `64 + 24 + 140 + 24 + 424`：**类型栏收成图标条之后**三栏仍能让列表停在 424； +//! - `600` = `64 + 24 + 64 + 24 + 424`：两条栏都收成 64 也救不回来时，三栏这件事就不成立了。 +//! +//! ## 3. 列表列下限为什么是 424（这条是硬的） +//! +//! 版本行要**单行不折**地放「版本号 + 类型 + 日期 + 安装按钮」。424 是 [`super::measure_cap_px`] +//! ——正文行宽上限（逐行实测 67 字符 ≤72），比这一行真正需要的宽得多： +//! `1.21.9-pre3`（11 字符 `BodyMedium` 14px ≈ 67）+ `Snapshot`（`LabelMedium` 12px ≈ 50） +//! + `2026-09-20`（10 字符 ≈ 52）+ 安装按钮（`control_height` 40 高的 text 按钮 ≈ 76） +//! + 两侧内边距 2×16 + 三处间距 3×12 = **293**。取 424 不是「凑」：它是本仓既有的 +//! 行宽红线，列表列比它还窄就等于在 424 的正文列旁边又开了一条更窄的正文列。 +//! +//! ## 4. 数值表（报告里贴的是同一张） +//! +//! 页面拿到的宽度 → 可用宽 `A`（扣 rail 88 与 2×24 页边距）→ 档位 → 三列。 +//! 「右栏收起 / 展开」列按 M104 的 `content_width`（窗口 − 右栗 − 拖拽缝）计算： +//! +//! | 窗口 | 右栏 | 页面拿到 | `A` | 档 | 类型 | 主版本 | 列表 | +//! |---|---|---|---|---|---|---|---| +//! | 1180 | 无（本分支） | 1180 | 1044 | Wide | 140 | 140 | **716** | +//! | 1180 | 收起 48 | 1132 | 996 | Wide | 140 | 140 | **668** | +//! | 1180 | 展开 320 | 852 | 716 | Narrow | 64 | 140 | **464** | +//! | 1024 | 无 | 1024 | 888 | Wide | 140 | 140 | **560** | +//! | 900 | 无 | 900 | 764 | Narrow | 64 | 140 | **512** | +//! | 880 | 无 | 880 | 744 | Narrow | 64 | 140 | **492** | +//! | 700 | 无 | 700 | 564 | Chips | — | — | **564** | +//! +//! **任务书那句「1180−88−320−140−140 = 492」算错了**：它漏掉 2×24 页边距与 2×24 栏间距 +//! （共 96）。按真实链路，1180 展开右栏后页面拿到 **852**，可用宽 **716**， +//! 两条 140 栏 + 两处间距要 328 ⇒ 列表只剩 **388 < 424**，**那正是「一条栏必须收成 64」的 +//! 触发条件**；收到 64 之后列表是 **464**（不是 492）。492 这个数在 **880 窗宽**上成立 +//! （744 − 252 = 492），两者差 28 就是 1180−852−88−48 里被漏掉的那部分。 +//! +//! ## 5. 为什么 Narrow 档收的是**类型栏**而不是主版本栏 +//! +//! 两栏都放 3~5 个字符的短串，但可辨性不同：类型栏是**四个固定项**（有图标可认：列表 / 星 / +//! 相机 / 历史），主版本栏放的是**用户正在找的那串版本号**——同一屏里两种 64 栏，先收有图标的那个。 +//! `Compact` 档才把主版本栏也收成 64（`1.21` 在 40 可用宽里仍是完整串，不会被截断）。 + +use unlucky_design::spacing::Space; + +use super::{available_width, measure_cap_px, FrameMetrics}; + +/// 版本类型栏（第一栏）展开宽。 +pub const TYPE_RAIL_WIDTH: f32 = 140.0; +/// 主版本栏（第二栏）展开宽。 +pub const MAJOR_RAIL_WIDTH: f32 = 140.0; +/// 两条侧栏收成图标条时的宽度。 +pub const RAIL_ICON_WIDTH: f32 = 64.0; +/// 栏与栏之间的间距（与两列版面的 `PANES_GAP` 同值：同一屏里不出现两种分栏节奏）。 +pub const RAIL_GAP: f32 = Space::X6.dp(); + +/// 列表列下限 = 行宽上限 **424**（见模块文档 §3）。 +pub fn version_list_min_width() -> f32 { + measure_cap_px() +} + +/// `Wide` 档门槛：`available_width(1024)` = **888**（产品口径「≫1024 两栏都展开」）。 +pub fn wide_min_available() -> f32 { + available_width(1024.0) +} + +/// `Narrow` 档门槛：类型栏 64 + 间距 + 主版本栏 140 + 间距 + 列表下限 = **676**。 +pub fn narrow_min_available() -> f32 { + RAIL_ICON_WIDTH + RAIL_GAP + MAJOR_RAIL_WIDTH + RAIL_GAP + version_list_min_width() +} + +/// `Compact` 档门槛：两条 64 栏 + 两处间距 + 列表下限 = **600**。 +pub fn compact_min_available() -> f32 { + RAIL_ICON_WIDTH + RAIL_GAP + RAIL_ICON_WIDTH + RAIL_GAP + version_list_min_width() +} + +/// 版本行里「类型」一格的宽度：最长标签 `Snapshot`（8 字符 × `LabelMedium` 12px ≈ 50）+ +/// 一格间距余量，取 4px 栅格 **84**。 +pub const LIST_KIND_WIDTH: f32 = 84.0; + +/// 版本行里「日期」一格的宽度：ISO 日期 `2026-09-20`（10 字符 ≈ 52）+ 余量，取 **88**。 +pub const LIST_DATE_WIDTH: f32 = 88.0; + +/// 版本行尾的安装图标按钮格子宽 = 图标按钮边长 **40**（`IconGeometry::side`；命中区 48 由行高 44 补）。 +pub const ROW_ICON_BUTTON: f32 = 40.0; + +/// 版本行内三处间距（`Space::X2` = 8）：比栏间距小一档，行内节奏不与分栏节奏打架。 +pub const ROW_GAP: Space = Space::X2; + +/// 版本行的最小内容宽（报告里的推导用它当校验）： +/// `Listitem 最小格 176 + 84 + 88 + 40 + 3×8 = 412 < 424`。 +/// +/// 412 略小于行宽下限 424，说明「424 下四样仍在同一行」不是估计而是有 12px 余量的结论； +/// 版本号那一格最窄拿到 `424 − 84 − 88 − 40 − 24 = 188`（比推导里取的 176 还宽 12）。 +pub fn version_row_min_width() -> f32 { + 176.0 + LIST_KIND_WIDTH + LIST_DATE_WIDTH + ROW_ICON_BUTTON + 3.0 * ROW_GAP.dp() +} + +/// 版本管理页此刻用哪一档（四档，见模块文档 §2）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum VersionRailTier { + /// 两栏都展开（`A ≥ 888`）。 + Wide, + /// 类型栏收成图标条（`676 ≤ A < 888`）。 + Narrow, + /// 两条栏都收成图标条（`600 ≤ A < 676`）。 + Compact, + /// 三栏不成立：退回顶部 chips（`A < 600`）。 + Chips, +} + +impl VersionRailTier { + /// 稳定名字（日志 / 测试 / 出图文件名用）。 + pub const fn name(self) -> &'static str { + match self { + Self::Wide => "wide", + Self::Narrow => "narrow", + Self::Compact => "compact", + Self::Chips => "chips", + } + } + + /// 这一档还画不画页内侧栏。 + pub const fn is_three_column(self) -> bool { + !matches!(self, Self::Chips) + } +} + +/// 三栏的宽度裁决结果（页面直接消费，不再自己算）。 +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct VersionRails { + /// 档位。 + pub tier: VersionRailTier, + /// 版本类型栏宽（`Chips` 档为 0）。 + pub type_rail: f32, + /// 主版本栏宽（`Chips` 档为 0）。 + pub major_rail: f32, + /// 列表 / 内容列宽。 + pub list: f32, +} + +impl VersionRails { + /// 按可用宽裁决（门槛见模块文档 §2）。 + /// + /// 降级是**逐档下沉**的，不做「挤一挤」：每一档都保证 `list ≥ `[`version_list_min_width`]， + /// 除非已经沉到 `Chips`（那时列表就是整条可用宽）。 + pub fn of(available: f32) -> Self { + let (tier, type_rail, major_rail) = if available >= wide_min_available() { + (VersionRailTier::Wide, TYPE_RAIL_WIDTH, MAJOR_RAIL_WIDTH) + } else if available >= narrow_min_available() { + (VersionRailTier::Narrow, RAIL_ICON_WIDTH, MAJOR_RAIL_WIDTH) + } else if available >= compact_min_available() { + (VersionRailTier::Compact, RAIL_ICON_WIDTH, RAIL_ICON_WIDTH) + } else { + (VersionRailTier::Chips, 0.0, 0.0) + }; + + let list = if tier.is_three_column() { + (available - type_rail - RAIL_GAP - major_rail - RAIL_GAP).max(0.0) + } else { + available.max(0.0) + }; + + Self { + tier, + type_rail, + major_rail, + list, + } + } + + /// 一屏的版本管理页几何（`metrics` 来自 [`super::frame_metrics`]）。 + /// + /// **读的是块宽**（[`super::block::body_width`] = pane 宽封顶 1440，M102 的口径）， + /// 不是 `metrics.available`：三栏都长在 `frame::body` 那个块里，超宽窗（≥1576）上 + /// 可用宽 2424 > 块宽 1440，按 available 切会让三列之和超出块、右侧被裁。 + pub fn of_metrics(metrics: FrameMetrics) -> Self { + Self::of(super::block::body_width(metrics)) + } + + /// 叠上「用户手动折叠了类型栏」这条覆盖。 + /// + /// 只动第一栏：收窄到 [`RAIL_ICON_WIDTH`]，省下来的宽**原样进列表列**（折叠只会让列表更宽， + /// 所以不需要再校验一次 424 下限）。`Chips` 档没有第一栏，返回原值。 + #[must_use] + pub fn with_type_folded(self) -> Self { + if !self.tier.is_three_column() || self.type_rail <= RAIL_ICON_WIDTH { + return self; + } + Self { + type_rail: RAIL_ICON_WIDTH, + list: self.list + (self.type_rail - RAIL_ICON_WIDTH), + ..self + } + } +} + +#[cfg(test)] +mod tests; diff --git a/crates/app-iced/src/pages/layout/rails/tests.rs b/crates/app-iced/src/pages/layout/rails/tests.rs new file mode 100644 index 0000000..5c650f7 --- /dev/null +++ b/crates/app-iced/src/pages/layout/rails/tests.rs @@ -0,0 +1,139 @@ +//! 三栏几何的判据：**报告里的数值表就是这张表**，改任何一个门槛或栏宽都会在这里红。 +//! +//! 每条都写清「抓得住什么 / 抓不住什么」——这里只测纯函数，**像素**由 `DevDocs/artifacts/m107/` +//! 的图与报告的量测表负责。 + +use super::*; +use crate::pages::layout::available_width; + +/// 报告里那张数值表的**逐行快照**（窗口 → 页面拿到多宽 → 可用宽 → 档 → 三列）。 +/// +/// 抓得住：任何一处门槛 / 栏宽 / 间距被改动（表里 7 行的档位或列宽立刻对不上）。 +/// 抓不住：改完之后画面**看起来**是否还行（那要出图，见报告）。 +#[test] +fn the_numeric_table_matches_the_report() { + // (页面拿到的宽, 期望档, 类型栏, 主版本栏, 列表) + let table: [(f32, VersionRailTier, f32, f32, f32); 7] = [ + (1180.0, VersionRailTier::Wide, 140.0, 140.0, 716.0), + (1132.0, VersionRailTier::Wide, 140.0, 140.0, 668.0), + (852.0, VersionRailTier::Narrow, 64.0, 140.0, 464.0), + (1024.0, VersionRailTier::Wide, 140.0, 140.0, 560.0), + (900.0, VersionRailTier::Narrow, 64.0, 140.0, 512.0), + (880.0, VersionRailTier::Narrow, 64.0, 140.0, 492.0), + (700.0, VersionRailTier::Chips, 0.0, 0.0, 564.0), + ]; + + for (page_width, tier, type_rail, major_rail, list) in table { + let rails = VersionRails::of(available_width(page_width)); + assert_eq!(rails.tier, tier, "{page_width} 的档位"); + assert_eq!(rails.type_rail, type_rail, "{page_width} 的类型栏"); + assert_eq!(rails.major_rail, major_rail, "{page_width} 的主版本栏"); + assert_eq!(rails.list, list, "{page_width} 的列表列"); + } +} + +/// 三栏档里，列表列**永远**不低于行宽下限 424（任务里那条硬约束：版本行不许折行）。 +/// +/// 抓得住：有人把门槛算小了（比如把 `Compact` 档门槛写成 560，列表会掉到 384 以下， +/// `1.21.9-pre3 · Snapshot · 2026-09-20 · Install` 这一行就得折）。 +/// 抓不住：折行到底发生在第几个字符（那要 FreeType 量宽 + 出图）。 +#[test] +fn every_three_column_tier_keeps_the_list_at_the_reading_floor() { + let floor = version_list_min_width(); + let mut sweep = 0; + // 4px 栅格扫一遍：从 480 到 2400 的可用宽 + let mut available = 480.0_f32; + while available <= 2400.0 { + let rails = VersionRails::of(available); + if rails.tier.is_three_column() { + assert!( + rails.list + f32::EPSILON >= floor, + "可用宽 {available}（{} 档）的列表列 {} 低于行宽下限 {floor}", + rails.tier.name(), + rails.list + ); + sweep += 1; + } + available += 4.0; + } + assert!(sweep > 100, "扫描没跑到（只命中 {sweep} 档）"); +} + +/// 档位随可用宽**单调**下沉：变窄只可能降档，不会「窄一点反而三栏都展开」。 +#[test] +fn the_tiers_only_ever_step_down_as_the_width_shrinks() { + let order = |tier: VersionRailTier| match tier { + VersionRailTier::Wide => 0, + VersionRailTier::Narrow => 1, + VersionRailTier::Compact => 2, + VersionRailTier::Chips => 3, + }; + + let mut previous = VersionRails::of(4096.0); + let mut available = 4092.0_f32; + while available >= 200.0 { + let rails = VersionRails::of(available); + assert!( + order(rails.tier) >= order(previous.tier), + "{available} 反而比更宽时更「展开」：{:?} → {:?}", + previous.tier, + rails.tier + ); + previous = rails; + available -= 4.0; + } +} + +/// 三个门槛都是**算出来的**，不是拍的：把它们与文档里的公式对上。 +#[test] +fn the_three_thresholds_are_derived() { + assert_eq!(wide_min_available(), 888.0, "1024 窗宽换算的可用宽"); + assert_eq!( + narrow_min_available(), + 64.0 + 24.0 + 140.0 + 24.0 + 424.0, + "类型栏收成图标条后三栏仍成立的最小可用宽" + ); + assert_eq!( + compact_min_available(), + 64.0 + 24.0 + 64.0 + 24.0 + 424.0, + "两条栏都收成 64 时的最小可用宽" + ); + assert!(compact_min_available() < narrow_min_available()); + assert!(narrow_min_available() < wide_min_available()); + + // 门槛上的两个采样点：刚好到就进这一档，差 4px 就退一档 + assert_eq!( + VersionRails::of(narrow_min_available()).tier, + VersionRailTier::Narrow + ); + assert_eq!( + VersionRails::of(narrow_min_available() - 4.0).tier, + VersionRailTier::Compact + ); + assert_eq!( + VersionRails::of(compact_min_available()).tier, + VersionRailTier::Compact + ); + assert_eq!( + VersionRails::of(compact_min_available() - 4.0).tier, + VersionRailTier::Chips + ); +} + +/// 右栏展开（M104 的 `content_width`：窗口 − 320 − 拖拽缝 8）之后**仍是三栏**，且列表够宽。 +/// +/// 这条钉的是任务里那个场景：1180 窗宽开右栏，用户还能看见两条侧栏 + 一个不折行的版本列表。 +/// 抓得住：有人把 `Narrow` 门槛抬到 716 以上（那会让右栏一展开就掉进 chips）。 +/// 抓不住：`content_width` 自己算错（那是 M104 的测试）。 +#[test] +fn the_agent_rail_open_at_1180_keeps_three_columns() { + // M104 `content_width` = 窗口 − 右栗 320 − 拖拽缝 8 + let page_width = 1180.0 - 320.0 - 8.0; + let rails = VersionRails::of(available_width(page_width)); + + assert_eq!(page_width, 852.0); + assert_eq!(rails.tier, VersionRailTier::Narrow); + assert!(rails.tier.is_three_column(), "右栏展开不许把侧栏收掉"); + assert_eq!(rails.list, 464.0, "列表列 464（任务书写的 492 漏扣了 96）"); + assert!(rails.list >= version_list_min_width()); +} diff --git a/crates/app-iced/src/pages/layout/source.rs b/crates/app-iced/src/pages/layout/source.rs new file mode 100644 index 0000000..28e74f7 --- /dev/null +++ b/crates/app-iced/src/pages/layout/source.rs @@ -0,0 +1,235 @@ +//! **源码结构断言**的小工具：把某个函数的实现文本切出来（只给测试用）。 +//! +//! ## 为什么要读源码（而不是量 Element） +//! +//! iced 的 `Element` 没有几何内省接口（`size()` 只是 `Size`，取不到布局结果）， +//! 所以「页面把块摆在哪 / 有没有在行之间叠间距」在单测里**量不到**。M102 r1 的教训正是这个： +//! 护栏只喂 `frame_metrics()` 与常量重算，把 `frame::body` 换回「居中 424」的实现， +//! 测试照样全绿——钉住的是公式，不是摆法。 +//! +//! 本仓已有同一条纪律的先例：`tests/no_hardcoded_tokens.rs` 直接扫 `src/**`， +//! `pages/download/tests.rs::every_download_key_is_referenced_by_the_page` 用 `include_str!` +//! 扫页面源码找 key 引用。这里只是把「切出某个函数」这件小事做成一个共用工具， +//! 让护栏能断言「盒子是不是照那个数建的」。 +//! +//! ## 边界（它抓不住什么） +//! +//! 它读的是**文本**：换个写法（先赋值给局部变量再 `.width(...)`）就可能绕过。 +//! 所以它只配一条**明确的契约**用：`frame::body` / `frame::prose` / `list_column` 这几处的 +//! 写法本身就是契约的一部分（它们各自只有 5~10 行），不是为了抠实现细节。 +//! 真要守像素，还是得靠软件渲染金图（`shot::diff`，绑 Windows + 字体栈，属另一个决定）。 + +/// 把 `source` 里第一个 `signature` 起始、到该函数**顶层**右花括号为止的文本切出来。 +/// +/// 「顶层」= 行首的 `}`（本仓函数都是顶格收尾，内层块都是缩进收尾），所以不会在内层 `}` 提前断。 +/// +/// # Panics +/// 签名不存在时 panic（护栏自己的前置条件坏了要立刻红，不能静默放行）。 +pub(crate) fn function_body<'a>(source: &'a str, signature: &str) -> &'a str { + let start = source + .find(signature) + .unwrap_or_else(|| panic!("源码里找不到签名 {signature:?}")); + + let rest = &source[start..]; + let end = rest.find("\n}").map_or(rest.len(), |index| index + 2); + &rest[..end] +} + +/// 从 `start` 起到**第一个 `;`** 为止的一条语句（构建链断言用）。 +/// +/// 例如 `statement(instances.rs, "let mut rows = column(")` 拿到的是 +/// `let mut rows = column(...).padding(...).width(Length::Fill);` 这一整条链—— +/// 于是「这条链上不许叠间距」可以精确到**这一个**容器，不会连带禁掉旁边 `column![head, scroller]` +/// 上的合法间距。 +/// +/// # Panics +/// `start` 不存在时 panic（守卫的前置条件坏了要立刻红）。 +pub(crate) fn statement<'a>(source: &'a str, start: &str) -> &'a str { + let from = source + .find(start) + .unwrap_or_else(|| panic!("源码里找不到语句起点 {start:?}")); + + let rest = &source[from..]; + let end = rest.find(';').map_or(rest.len(), |index| index + 1); + &rest[..end] +} + +/// `signature` 的函数体 **+ 它内部转调的函数体**（同文件，最多两层）。 +/// +/// 为什么不只切一个函数：**等价重构不该假红**。把 `frame::body` 拆成 +/// `body` → `body_impl` 两层再转调，盒子一个像素都没变，`function_body` 却会拿到三行转调桩、 +/// needle 全缺（r2 复审的变异 H1 就是这样假红的）。这里把「被它调用的函数」也算进契约， +/// 于是「拆一层再转调」放行，「换成居中盒子」照样红。 +/// +/// 跨文件转调用 [`region_across`]。两者都不跟「先赋局部变量再建盒」的写法。 +pub(crate) fn function_region(source: &str, signature: &str) -> String { + region_across(&[source], signature) +} + +/// 多文件版的 [`function_region`]：[`expand`] 会在给定的**所有**文件里按名字找转调目标。 +/// +/// 存在的理由（r4 复审的变异 M6）：把盒子原样搬进 `layout/block.rs::body_box` 再由 +/// `frame::body` 转调，是**等价重构**，单文件版会把 needle 全丢掉并假红。 +/// 现在把 `frame.rs` 与 `layout/block.rs` 一起交进来，搬运不再被惩罚。 +/// +/// # Panics +/// `signature` 在任何一个文件里都找不到时 panic（护栏前置条件坏了要立刻红）。 +pub(crate) fn region_across(sources: &[&str], signature: &str) -> String { + let mut region = sources + .iter() + .find(|source| source.contains(signature)) + .map(|source| function_body(source, signature).to_owned()) + .unwrap_or_else(|| panic!("这几个文件里都找不到签名 {signature:?}")); + + for _ in 0..2 { + if !expand(&mut region, sources) { + break; + } + } + + region +} + +/// 把 `region` 里出现、且定义在 `sources` 某处的函数体补进来。返回是否有增长。 +fn expand(region: &mut String, sources: &[&str]) -> bool { + let mut grew = false; + + for source in sources { + let mut cursor = 0; + + while let Some(found) = source[cursor..].find("fn ") { + let at = cursor + found + "fn ".len(); + cursor = at; + + let name: String = source[at..] + .chars() + .take_while(|ch| ch.is_alphanumeric() || *ch == '_') + .collect(); + if name.is_empty() { + continue; + } + + // `defined` 不带 `(`：签名可能带泛型（`fn body_impl<'a>(`）， + // 带括号的 needle 会找不到定义、直接把护栏自己搞 panic。 + let defined = format!("fn {name}"); + if region.contains(&format!("{name}(")) + && !region.contains(&defined) + && source.contains(&defined) + { + region.push('\n'); + region.push_str(function_body(source, &defined)); + grew = true; + } + } + } + + grew +} + +/// `haystack` 里每一处 `callee(…)` 调用的**实参文本**（不含括号本身）。 +/// +/// 括号按深度配对，所以 `ui.space(Space::X1)` 这种嵌套实参会完整取到 `ui.space(Space::X1)`； +/// 找不到闭合括号时取到文本末尾（宁可让断言看见多余文本，也不静默返回空）。 +pub(crate) fn call_arguments<'a>(haystack: &'a str, callee: &str) -> Vec<&'a str> { + let mut found = Vec::new(); + let mut from = 0; + + while let Some(index) = haystack[from..].find(callee) { + let start = from + index + callee.len(); + let mut depth = 1usize; + let mut end = haystack.len(); + + for (offset, ch) in haystack[start..].char_indices() { + match ch { + '(' => depth += 1, + ')' => { + depth -= 1; + if depth == 0 { + end = start + offset; + break; + } + } + _ => {} + } + } + + found.push(&haystack[start..end]); + from = end.max(start); + } + + found +} + +/// 顺绑定链往回追：`ident` 是否（直接或经至多 3 跳中转）来自 `root`。 +/// +/// 认两种绑定形状（本仓就这两种）： +/// +/// - `let = ;` +/// - `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/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..ba3143c --- /dev/null +++ b/crates/app-iced/src/pages/logs/diagnostic.rs @@ -0,0 +1,218 @@ +//! 诊断结果区：**按置信度档分组**的结论卡片 + 可直接粘进 issue 的一行摘要。 +//! +//! ## 一条结论要能看出什么（tower 的三问） +//! +//! | 问题 | 落点 | 数据来源 | +//! |---|---|---| +//! | 哪条规则命中 | 规则 id（等宽、`LabelMedium`） | `Finding::rule` | +//! | 置信度（不是严重度） | 分组标题 + 分组顺序（`HIGH` → `MEDIUM` → `LOW`） | `Finding::confidence_band` | +//! | 建议动作 | `Suggested fix` 一行（规则表的 `fix_action`，技术标识原样） | `Finding::action` | +//! +//! ## 用户真的要拿去用的两样东西 +//! +//! 1. **结论原文**（`title` / `hint`）：规则表 `rules.d/*.yaml` 写的 `cause.summary` / `detail`。 +//! 它是**数据**（诊断结论），页面不翻译也不改写——改写会让「规则命中」与「用户读到的」 +//! 变成两套说法。界面文案（分组名 / 标签 / 按钮）仍然全部走 i18n key。 +//! 2. **一行摘要**（[`Logs::summary`]）：等宽显示 + 「Copy summary」按钮；按钮把字符串塞进 +//! 剪贴板（`Message::CopySummary` → `iced::app/update.rs` → `iced::clipboard::write`）。 +//! 崩溃日志换 issue 时粘这一行就够：实例 / 时间 / 结局 / 行数 / 命中的规则与置信度都在里面。 + +use iced::widget::text::{LineHeight, Wrapping}; +use iced::widget::{column, row, text}; +use iced::{Alignment, Color, Element, Length, Pixels}; + +use unlucky_design::color::Role; +use unlucky_design::spacing::Space; +use unlucky_design::typography::{TypeRole, TypeStyle}; +use unlucky_i18n::catalog::{Catalog, Key}; +use unlucky_i18n::Lang; + +use crate::app::components::buttons::{self, Button}; +use crate::theme::Ui; + +use super::super::frame; +use super::super::layout::wrap; +use super::super::Message; +use super::lines::{mono, mono_owned}; +use super::model::{Confidence, Finding, Logs, GROUPS}; +use super::panel; + +/// 诊断卡片（只在有结论时画）。高度由调用方定（见 [`panel`]）。 +/// +/// 结构 = 头（`DIAGNOSIS` + 条数）/ **可滚动的分组区** / **固定的摘要页脚**。 +/// 摘要钉在页脚而不是跟着滚（视觉复审 P2-3）：三条结论就足以把它顶到折叠线以下， +/// 而「Copy」复制的是用户必须看得见的东西——看不见的字符串不该能被复制。 +pub fn card<'a>(ui: &'a Ui, logs: &'a Logs, lang: Lang, height: Length) -> Element<'a, Message> { + let catalog = Catalog::of(lang); + + let mut group = column![].spacing(ui.space(Space::X2)).width(Length::Fill); + + for band in GROUPS { + let findings = logs.group(band); + if findings.is_empty() { + continue; + } + + group = group.push(frame::divider(ui)); + group = group.push(title_row(ui, catalog.text(key_of(band)), findings.len())); + for finding in findings { + group = group.push(finding_block(ui, &catalog, finding)); + } + } + + panel::card( + ui, + height, + column![ + title_row( + ui, + catalog.text(Key::LogsDiagnosisTitle), + logs.findings.len(), + ), + panel::scroll(ui, group), + frame::divider(ui), + summary_block(ui, &catalog, logs), + ] + .spacing(ui.space(Space::X2)) + .width(Length::Fill), + ) +} + +/// 标题行：左边标签（大写字距靠令牌档），右边条数。 +fn title_row<'a>(ui: &'a Ui, label: &'a str, count: usize) -> Element<'a, Message> { + row![ + frame::text_role( + ui, + TypeRole::LabelMedium, + true, + label, + ui.color(Role::OnSurfaceVariant), + ), + iced::widget::Space::new().width(Length::Fill), + frame::text_role_owned( + ui, + TypeRole::LabelMedium, + false, + count.to_string(), + ui.color(Role::OnSurfaceVariant), + ), + ] + .width(Length::Fill) + .align_y(Alignment::Center) + .into() +} + +/// 一条结论：规则 id / 结论 / 说明 / 建议动作 / 置信度。 +fn finding_block<'a>(ui: &'a Ui, catalog: &Catalog, finding: &'a Finding) -> Element<'a, Message> { + let mut block = column![ + mono(ui, &finding.rule, ui.color(Role::OnSurfaceVariant)), + wrapped( + ui, + TypeRole::BodyMedium, + &finding.title, + ui.color(Role::OnSurface) + ), + wrapped( + ui, + TypeRole::BodySmall, + &finding.hint, + ui.color(Role::OnSurfaceVariant) + ), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill); + + if let Some(action) = &finding.action { + block = block.push( + column![ + frame::text_role( + ui, + TypeRole::LabelMedium, + false, + catalog.text(Key::LogsSuggestedFix), + ui.color(Role::OnSurfaceVariant), + ), + mono(ui, action, ui.color(Role::OnSurface)), + ] + .spacing(0.0) + .width(Length::Fill), + ); + } + + block = block.push(frame::text_role_owned( + ui, + TypeRole::LabelMedium, + false, + catalog.render( + Key::LogsConfidence, + &[("percent", &finding.confidence.to_string())], + ), + ui.color(Role::OnSurfaceVariant), + )); + + block.into() +} + +/// **固定的摘要页脚**：标签 +「Copy summary」+ 等宽摘要（可整段带走）。 +/// +/// 页脚不滚动（见 [`card`] 的文档）：按钮紧邻它要复制的那段文字，用户复制的一定是看得见的串。 +fn summary_block<'a>(ui: &'a Ui, catalog: &Catalog, logs: &Logs) -> Element<'a, Message> { + column![ + row![ + frame::text_role( + ui, + TypeRole::LabelMedium, + false, + catalog.text(Key::LogsSummaryLabel), + ui.color(Role::OnSurfaceVariant), + ), + iced::widget::Space::new().width(Length::Fill), + buttons::text( + ui, + Button::new( + catalog.text(Key::LogsCopySummary), + Message::CopySummary(logs.summary()), + ), + ), + ] + .width(Length::Fill) + .align_y(Alignment::Center), + mono_owned( + ui, + wrap::breakable(&logs.summary()), + ui.color(Role::OnSurface) + ) + .width(Length::Fill) + .wrapping(Wrapping::WordOrGlyph), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill) + .into() +} + +/// 置信度档 → 分组标题的 key。 +/// +/// 刻意**不叫严重度**（`CRITICAL` / `WARNING` / `NOTICE`）：DTO 没带 core 的 severity， +/// 拿置信度去凑严重度会让 64 条规则里的 12 条进错组（`mod.mixin_failure` critical/0.70 沉底、 +/// `other.debug_crash` info/0.95 冒顶）。标题只说它对「这条结论有多确定」。 +fn key_of(band: Confidence) -> Key { + match band { + Confidence::High => Key::LogsConfidenceHigh, + Confidence::Medium => Key::LogsConfidenceMedium, + Confidence::Low => Key::LogsConfidenceLow, + } +} + +/// 令牌排版档 + **按词或字形折行**（长堆栈里的点分标识符没有空格，只按词会溢出）。 +fn wrapped<'a>(ui: &'a Ui, role: TypeRole, content: &'a str, color: Color) -> Element<'a, Message> { + let style: TypeStyle = ui.style(role); + + text(content) + .size(style.size_px) + .line_height(LineHeight::Absolute(Pixels(style.line_height_px))) + .font(ui.font_of(style)) + .color(color) + .width(Length::Fill) + .wrapping(Wrapping::WordOrGlyph) + .into() +} diff --git a/crates/app-iced/src/pages/logs/lines.rs b/crates/app-iced/src/pages/logs/lines.rs new file mode 100644 index 0000000..2e10e8b --- /dev/null +++ b/crates/app-iced/src/pages/logs/lines.rs @@ -0,0 +1,221 @@ +//! 日志行列表：**等宽 + 折行 + 独立滚动**。 +//! +//! ## 为什么折行而不是横向滚动（tower 要求二选一，这里选折行） +//! +//! 一行崩溃堆栈动辄 200+ 字符（样例里最长的一行 214 字符）。M102 起卡片吃满页宽 +//! （1180 窗宽 → 卡内约 1004px），但 214 字符 × 等宽 12px ≈ 1412px 仍要折一次。两条路： +//! +//! | 方案 | 代价 | +//! |---|---| +//! | 横向滚动 | 一条日志要横甩两屏；外壳已经是竖向滚动，横竖两向嵌套后滚轮归属会打架 | +//! | **折行（本页选）** | 一条日志可能占 2~3 行，行号/等级栏必须能标明「这是同一条」 | +//! +//! 选折行的决定性理由：**折行让等宽族只承担「视觉密度」，不承担「列对齐」**。等宽栈在 +//! Windows 上是 `Cascadia Mono` / `Consolas`，它们没有 CJK 字形——中文日志要靠 cosmic-text +//! 逐字回退到系统 CJK 族（本机实测回退到 `Microsoft YaHei UI`），回退字形的 advance 不是 1ch。 +//! 横向滚动方案里「第 40 列对齐」是有意义的（堆栈缩进、`at a.b.C(File.java:12)` 的括号列）， +//! 一旦 CJK 回退把列宽带偏，对齐就废了；折行版面不承诺任何列对齐，回退只影响同一行内的观感。 +//! ## 悬挂缩进（M95 r2 落地，视觉复审 P2-1） +//! +//! r1 的 `entry()` 只有 `row![等级条, 单个 Text]`：折行的续行回到文本自己的左边距， +//! 于是 `at com.mojang…(GLX.java:64)` 被拆成「`at` 独占一行 + 帧名一行」，和「下一条日志」 +//! 视觉上无法区分（一屏白花 ~5 行）。**现在的落地方式**是把一行拆成**前缀 + 正文两个文本控件**： +//! +//! ```text +//! │ [19:40:14] [Render thread/ERROR] 显卡驱动不支持 OpenGL 3.2，初始化窗口失败 +//! │ ↑ 前缀（第一个空格及其之前，含空格） ↑ 正文从它右边开始，带着 Fill 宽度自己折行 +//! │ java.lang.IllegalStateException: GLFW error before init: [0x10008] Failed to create window… +//! │ ↑ 无前缀（第一个「词」超过 20 字符）⇒ 整行一个文本块 +//! ``` +//! +//! 为什么不是「NBSP 绑定前缀 + 单个 Text」：NBSP 只阻止断行，**改不了续行的起点**——续行依旧 +//! 回到文本左边距，`at` 还是独占一行（除非整行按字形硬断，那会把时间戳也断掉）。两段布局是 +//! iced 里唯一能同时做到「`at` 与帧名同行」+「续行比行首缩进」的写法。 +//! +//! 代价与边界：续行缩进量 = **该行前缀宽度**（时间戳行 ≈ 10 字符、栈帧 `at` 行 ≈ 3 字符）， +//! 所以不同行的续行缩进不一样——这是悬挂缩进的正常形态（按行首标签缩进），不是 bug。 +//! +//! ## 软断点（M102，视觉复审 ③） +//! +//! 没有空格的长串（`graphics.gl_operation_failure:medium(70)`）在原版里只能按字形硬断， +//! 图里出现 `gl_o` / `peration_failure`。现在正文先过 +//! [`super::super::layout::wrap::breakable`]：在 `.` `_` `:` `/` `\` 后插零宽空格，折行落回 +//! 词边界；悬挂缩进不受影响（前缀仍是独立文本控件），`Line::text` 仍是原文。 +//! +//! ## 贴底（M95 r2，视觉复审 P2-4） +//! +//! 崩溃排查看的是**最后几行**，所以行列表用 `panel::scroll_tail`（`Anchor::End`）：偏移按 +//! 「距底多远」记，内容增长时视图保持距底同一位置 ⇒ 天然跟随尾部。用户上滚后的行为与 +//! 「是否冻结」的边界写在 [`panel::scroll_tail`] 的文档里（结论：**没有**冻结，需要 app 层 +//! 回灌滚动状态才做得到）。 +//! +//! ## 等宽族的实际落点 +//! +//! `ui.families().mono` 是启动时用系统字体库核对过的族名（[`crate::fonts`] 求值，启动日志里 +//! 有一行 `mono=…`），本页只通过 [`mono_style`] 用它，不写死族名。字号/行高走 +//! `TypeRole::BodySmall`（12/16），与报告里的数值表对得上（见 `logs/tests.rs`）。 + +use iced::widget::text::LineHeight; +use iced::widget::{column, container, row, space}; +use iced::{Alignment, Background, Border, Color, Element, Length, Padding, Pixels}; + +use unlucky_design::color::Role; +use unlucky_design::shape::ShapeScale; +use unlucky_design::spacing::Space; +use unlucky_design::typography::{FontFamily, TypeRole, TypeStyle}; +use unlucky_i18n::catalog::{Catalog, Key}; +use unlucky_i18n::Lang; + +use crate::theme::Ui; + +use super::super::frame; +use super::super::layout::wrap; +use super::super::Message; +use super::model::{Level, Line, Logs}; +use super::panel; + +/// 前缀上限（字符）：超过就不拆（见 [`split_prefix`]）。 +const PREFIX_MAX_CHARS: usize = 20; + +/// 等级条宽度（2px：够看见，又不抢日志正文的起始列）。 +const BAR_WIDTH: f32 = 2.0; + +/// 日志卡片：标题行（`OUTPUT` + 行数）+ 独立滚动的行列表。高度由调用方定（见 [`panel`]）。 +pub fn card<'a>(ui: &'a Ui, logs: &'a Logs, lang: Lang, height: Length) -> Element<'a, Message> { + let catalog = Catalog::of(lang); + + let head = row![ + container(frame::text_role( + ui, + TypeRole::LabelMedium, + false, + catalog.text(Key::LogsOutputTitle), + ui.color(Role::OnSurfaceVariant), + )) + .width(Length::Fill) + .align_y(Alignment::Center), + frame::text_role_owned( + ui, + TypeRole::LabelMedium, + false, + logs.lines.len().to_string(), + ui.color(Role::OnSurfaceVariant), + ), + ] + .width(Length::Fill) + .align_y(Alignment::Center) + .padding(Padding::default().bottom(ui.space(Space::X2))); + + let rows = column( + logs.lines + .iter() + .map(|line| entry(ui, line)) + .collect::>(), + ) + .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..64c401d --- /dev/null +++ b/crates/app-iced/src/pages/logs/panel.rs @@ -0,0 +1,89 @@ +//! 两块的共用外壳：**定高的卡片 + 内部独立滚动**。 +//! +//! ## 为什么必须定高（M95 r1 的实拍 bug） +//! +//! 第一版把诊断卡按内容自然高度画、日志卡吃剩余高度。三条结论在 424×540 的正文里就要 +//! ~500px，结果：诊断卡被裁掉尾部（一行摘要整块消失）、日志卡拿到 **0** 高度（整块不见）。 +//! 截图见报告里的「r1 崩了」。 +//! +//! 所以两块都**由调用方给定高**（`FillPortion`），各自内部滚动： +//! +//! | 块 | 高度 | 为什么 | +//! |---|---|---| +//! | 诊断 | `FillPortion(4)` | 崩溃时先读结论；份额要够 177px 的滚动视口，才放得下**一条完整结论**（含建议动作与置信度） | +//! | 日志 | `FillPortion(2)` | 日志是长流水，滚就是了 | +//! +//! 两者都是**兄弟**滚动区（不是嵌套）：滚轮归属清楚，不存在「滚动条套滚动条」。 + +use iced::widget::{container, scrollable}; +use iced::{Background, Element, Length}; + +use unlucky_design::component_map::Component; +use unlucky_design::elevation::MaterialLayer; + +use crate::theme::Ui; + +use super::super::frame; +use super::super::Message; + +/// 定高卡片（`Card` 材质层 + `OutlinedCard` 形状与 **1px 描边**，与 `frame::card` 同一套令牌： +/// 实例页 / 下载页的卡都带这条描边，日志页的两张主卡不能例外）。 +pub fn card<'a>( + ui: &'a Ui, + height: Length, + content: impl Into>, +) -> Element<'a, Message> { + let shape = Component::OutlinedCard.spec().shape; + + container(content) + .width(Length::Fill) + .height(height) + .padding(ui.metrics().card_padding) + .style(move |_theme| container::Style { + background: Some(Background::Color(ui.layer(MaterialLayer::Card))), + border: ui.outlined(shape), + ..container::Style::default() + }) + .into() +} + +/// 卡片内的竖向滚动区（贴顶：诊断卡从头读）。 +pub fn scroll<'a>(ui: &'a Ui, content: impl Into>) -> Element<'a, Message> { + 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..baa530d --- /dev/null +++ b/crates/app-iced/src/pages/message.rs @@ -0,0 +1,140 @@ +//! 页面消息与动作表（M101 r2 从 `pages/mod.rs` **原样搬出**）。 +//! +//! 为什么拆：合并 M100/M101 之后 `pages/mod.rs` 是 397 行，只剩 3 行余量，下一条线往枚举里加 +//! 一个变体（含文档）就顶破 400 硬线。拆法与 M99 的 `pages/nav.rs` 同一种范式：**纯搬移**、 +//! 一行不改、路径靠 `pages/mod.rs` 的 `pub use` 再导出保持不变（`pages::Message` / `pages::Action`）。 +//! +//! `pages::Message` 是页面层的自有消息类型（**不** import `crate::app::Message`，组件契约 §2 的 +//! 同一条纪律）；app 层只做一次 `.map`。 + +use unlucky_i18n::LangChoice; +use unlucky_presenter::router::Route; + +use super::appearance; +use super::content; +use super::download::{Category, Loader}; +use super::settings; + +/// 页面消息。 +/// +/// **故意不用 `crate::app::Message`**（组件库契约 §2 的同一条理由）：页面不绑 app 的状态层， +/// 接线时由 app 层把这里的三类意图翻成 presenter 的 `AppCommand` / `Route`。 +#[derive(Debug, Clone)] +pub enum Message { + /// 骨架期动作（三页的占位按钮 + 实例页上还没接后端的两个页头动作）。 + Action(Action), + /// 路由跳转：导航轨、列表行、窄窗「返回」都走这一条（栈语义归 `presenter::router`）。 + Navigate(Route), + /// 启动某实例（app 层翻成 `AppCommand::LaunchInstance`）。 + Launch(String), + /// 停止某实例（app 层翻成 `AppCommand::StopInstance`）。 + Stop(String), + /// 外观项改动（设置页「外观」分组 → `App` 的状态与落盘）。 + /// + /// 载荷是**用户请求值**（未钳位）：钳位与 CPU 档降级在 `appearance::alpha` 里做， + /// 页面只表达意图（与组件库「不持有业务状态」同一条纪律）。 + Appearance(appearance::Change), + /// 选中下载页的一个版本（M94）：**页面内选中**，app 层只改视图模型，不 dispatch。 + SelectVersion(String), + /// **确认安装**选中的版本（用当前安装选项）。 + /// + /// M105 起语义变了：以前是「立刻装原版」（`AppCommand::InstallVersion`），现在是 + /// 「用选项区里选好的加载器 / 加载器版本 / 实例名开工」（`AppCommand::CreateInstance`）。 + /// 载荷仍是版本 id，app 层拿它去草稿里取其余三项。 + InstallVersion(String), + /// 改安装选项的加载器（M105；app 层改草稿，必要时派 `AppCommand::ListLoaderVersions`）。 + SetLoader(Loader), + /// 改加载器版本（M105；空串 = 用官方最新）。 + SetLoaderVersion(String), + /// 改实例名（M105；空串 = 用版本号）。 + SetInstanceName(String), + /// 取消正在跑的安装（M94；`AppCommand::CancelInstall`）。 + CancelInstall, + /// 切换下载页分类（M94；app 层翻成 `AppCommand::ListVersions`，`All` 只画现有快照）。 + SetCategory(Category), + /// 搜索版本号（**M107**）：查询词写进 `AppState.download_query`，页面走同一条重建路径过滤。 + /// + /// 为什么不是「页面自己存一份查询」：下载页是**无状态视图**（每帧由快照重建），页面持有的 + /// 字段活不过下一次事件；查询词只有落在 presenter 的快照里才能跨帧存活，而 + /// `Download::from_snapshot` 本来就读 `download_query` —— 复用这条路，过滤只有一份真相。 + SetVersionQuery(String), + /// 清空搜索框（**M107**）。与 [`Self::SetVersionQuery`] 同一支的 `""` 特例， + /// 单独一个变体是为了让「清空」这个意图在日志与测试里一眼可辨。 + ClearVersionQuery, + /// 选中第二级侧栏的一个主版本桶（**M107**；`None` = 全部版本）。 + /// + /// **纯视图态**（与 [`Self::SelectVersion`] 同一类）：不派业务命令，app 层只改视图模型。 + SelectMajor(Option), + /// 折叠 / 展开第一级（版本类型）侧栏（**M107**）。纯视图态。 + ToggleTypeRail, + /// 把现成文本塞进剪贴板（**M95**：诊断卡片的一行摘要，文本由页面造，app 只搬）。 + CopySummary(String), + /// 设置页的一组消息（**M101 `SETTINGSMSG`**）：设置页的**唯一**投递口。 + /// + /// 四条填页线（java / download / language+appearance / ai+about）各自在自己的文件里定义 + /// 消息枚举，本枚举**不再**为设置页增加第二个变体——「加一支设置页消息」从此不碰本文件， + /// 也不碰 `app/update/page_messages.rs` 那条不许 `_ =>` 的 match。加变体与落点见 + /// `pages/settings/message.rs`（`app/update/settings.rs` 对它做穷尽分发，漏接线报 E0004）。 + Settings(settings::GroupMessage), + /// 换界面语言（**M106**：设置页 General 分组的语言行 → `App::set_language`）。 + /// + /// 载荷是**用户意图**（跟随系统 / 手选某一门语言），不是「生效语言」：生效语言由 + /// `LangChoice::resolve` 按 D28 的顺序算出来，页面不参与计算。 + /// + /// 为什么不折进 [`Message::Settings`] 那个投递口：语言档位不是「某一组的状态」——它要**落盘** + /// 到 `ui.language` 并**重建整棵视图模型**（目录是 `pages::Model` 的一部分），而那条落点 + /// （`app/update/settings/language_appearance.rs`）是 language+appearance 线的文件。 + /// 代价是本文件多一个变体；收口方向写在 `settings/general.rs` 的文档里。 + Language(LangChoice), + /// 内容库页的一组消息（**M109**）：与设置页同一个范式（页面自己的枚举 + 一个投递口）。 + /// + /// 加一条内容库消息只动 `pages/content/message.rs`，不动本枚举的正文，也不动 + /// `app/update/page_messages.rs` 那条不许 `_ =>` 的 match。 + Content(content::Message), + /// 账户页消息（**M114**：三轨登录 / 列表动作 / 表单输入；app 层翻成 `AppCommand`）。 + /// + /// 与 `Settings` 同一种做法：账户页自己的消息枚举在 `pages/account.rs`，这里只加一支入口。 + Account(crate::pages::account::Message), +} + +/// 页面动作清单（骨架期够用就行；接线时按业务语义重命名/扩充）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Action { + /// 新建实例（**还没有后端**，见模块文档偏离 #8）。 + NewInstance, + /// 导入（同上）。 + Import, + /// 返回实例列表（窄窗整页切换）。**已由 `Message::Navigate(Route::Instances)` 取代**， + /// 这里保留枚举项是为了别把「返回」这件意图从动作表里抹掉（外壳回退路径仍可能用到）。 + Back, + /// 启动（占位动作表里的「启动」；真启动走 `Message::Launch`）。 + Play, + /// 更多。 + More, + /// 复制实例。 + Duplicate, + /// 打开实例目录。 + OpenFolder, + /// 删除实例。 + Delete, + /// 重新探测下载源。 + RefreshSources, + /// 浏览版本列表。 + BrowseVersions, + /// 导入整合包。 + ImportModpack, + /// 检查下载源。 + CheckSources, + /// 打开日志目录。 + OpenLogs, + /// 复制诊断信息。 + CopyDiagnostics, + /// 清空日志。 + ClearLogs, + /// 重置当前设置分组。 + ResetSection, + /// 保存设置。 + SaveSettings, + /// 新增逐实例覆盖。 + AddOverride, +} diff --git a/crates/app-iced/src/pages/mod.rs b/crates/app-iced/src/pages/mod.rs new file mode 100644 index 0000000..18fb0f8 --- /dev/null +++ b/crates/app-iced/src/pages/mod.rs @@ -0,0 +1,296 @@ +//! # 页面层（P4）：布局系统 + 四页 + **路由/真组件的接入口**（M84 `PAGEFRAME` → M90 `APPSKEL`） +//! +//! ## 这一层交了什么 +//! +//! | 阶段 | 交付 | 判据 | +//! |---|---|---| +//! | M84 | **布局系统**（档位/版面/列宽）+ 四页占位视觉 | 下面的版面阈值表 | +//! | **M90（本文件当前状态）** | ①视图模型 [`model`] ②导航项接上 `presenter::router::Route` ③**实例页整页接真组件 + 真数据** | 「接真组件后版面约束一条没破」（见 `pages/tests.rs` 的数值断言） | +//! | M99 `SETTINGSFRAME` | **纯搬移**：导航表搬到 [`nav`]，设置页拆成目录（`pages/settings/**`），i18n 目录按域拆开 | 截图逐字节相同 + `catalog` 金表（`key -> 译文` 全量不变） | +//! +//! **导航轨归属（M90 r3 订正，复审 P2-1）**：产品路径（`app/view.rs`）走 +//! `shell::view_with_content`，导航轨由 **`shell/nav.rs` 的手搓实现**画——它与 M78 组件几何同值 +//! （宽 88、药丸 56×32），复审逐像素量过「r1 产品图（真组件 rail）vs r2 产品图（shell rail） +//! 在 y≥48 区域差异为 0」；组件版的 `nav::rail` 现在只服务 `pages::app`（`pages_demo` 出口图、 +//! harness）与单测。为什么不是「把 rail 挪进内容槽位」：那需要把 `shell` 的消息类型泛型化/映射， +//! 成本远大于收益（见偏离表 #10）。 +//! +//! 实例页之外的三页**仍是 M84 的占位视觉**（下载/日志/设置），但它们已经： +//! 走同一个 `Message` → `update` → `Route` 通道，导航轨点得动、路由栈按 `presenter::router` 的语义走。 +//! 页面美化是后续 mission 的事，本 mission 只保证「地基是通的」。 +//! +//! ## 版面规矩（M84 立的三条，M90 一条没动） +//! +//! 1. **宽度档位**：官方响应式断点 **600 / 840**（[`layout::WidthClass`]）； +//! 2. **版面**：单列 / supporting-pane / list-detail，各自的成立条件与退化阈值写在 [`layout`]； +//! 3. **行宽上限**：正文列硬上限 **424px（逐行实测 67 字符 ≤72）**（[`layout::measure_cap_px`]）， +//! 由 [`layout::content_column_width`] / [`layout::frame_metrics`] **无条件施加**， +//! 页面拿不到「更宽」的选项。 +//! +//! ## 版面阈值表（`layout` 模块文档是全文，这里给速查） +//! +//! | 版面 | 用它的页面 | 成立条件 | 退化 | +//! |---|---|---|---| +//! | `SingleColumn` | 下载 / 日志（永远）；实例 / 设置（窄窗） | 总是 | — | +//! | `SupportingPane` | 设置 | `w ≥ 600` 且 `w ≥ 720`（240 + 24 + 320 + 2×24 + 88） | 单列（分组按组堆叠） | +//! | `ListDetail` | 实例 | `w ≥ 840`（官方 expanded）且 `w ≥ 816` | 单列（列表 ↔ 详情整页切换） | +//! +//! ## 模块 +//! +//! | 文件 | 职责 | +//! |---|---| +//! | [`layout`] | **布局系统**：档位 / 版面 / 列宽 / 阈值，纯函数 + 单测（无 iced 控件树） | +//! | [`model`] | **视图模型**：presenter 快照 → 页面要画的东西（页面层不认识 presenter 类型） | +//! | [`frame`] | 页头 / 内容列 / 两列骨架 / 空态 / 卡片 / 分隔线 | +//! | [`nav`] | 导航轨的 `NAV` 表 + 部件版 `rail()`（harness / 单测；产品走 `shell/nav.rs`） | +//! | [`message`] / [`screen`] | `pages::Message` / `Action` / `Screen`（M101 r2 从本文件原样搬出） | +//! | `instances` | 实例页（list-detail）——**M90 唯一打通到真组件 + 真数据真命令的页** | +//! | `settings` | 设置页（supporting-pane，占位视觉）：分组注册表 + 每个分组一个文件 | +//! | `download` / `logs` | 下载 / 日志页（单列，占位视觉） | +//! | [`harness`] | 截图 harness（`examples/pages_demo.rs` 的入口，**不是** `cli.rs` 的一部分） | +//! +//! ## 消息与路由（M90 新增） +//! +//! 页面**不 import `crate::app::Message`**（组件契约 §2 的同一条纪律）：它有自己的 +//! [`Message`]，app 层只做一次 `.map`。路由跳转的载荷是 `presenter::router::Route` 本身， +//! 于是「页面里点一行」= 「压一层栈」，语义与 presenter 的 `Router` 天然一致， +//! 中间不再有一层「页面自定义的选中项」需要同步。 +//! +//! ### 设置页只有一个投递口（M101 `SETTINGSMSG`） +//! +//! 设置页的四条填页线各自在自己的文件里定义消息与状态，本文件的 [`Message`] 只留一个 +//! [`Message::Settings`]（详见 `pages/settings/mod.rs` 的「消息 / 状态」两节）；`Message` 与 +//! `Screen` 本身也在 M101 r2 搬到 [`message`] / [`screen`]（`pages/mod.rs` 合并后 397 行，只剩 +//! 3 行余量），这里的 `pub use` 保证了 `pages::Message` / `pages::Action` / `pages::Screen` +//! 三条路径一字未变。 +//! +//! ## 偏离登记（D30 要求逐条写清；M84 六条 + M90 三条） +//! +//! | # | 偏离 | 为什么 | 什么时候收口 | +//! |---|---|---|---| +//! | 1 | 页头按 M3 口径**铺满页面宽度**（贴页边距），不与正文列对齐 | AppBar 本来就该满宽；1180 下页头右缘 **1156** 与详情列右缘 **896** 有 **260px 分歧** | 真 top bar 落地时按 M3 定语（页头右侧是操作区，不跟随列宽） | +//! | 2 | 空态标题 `HeadlineSmall 24` 比页标题 `TitleLarge 22` 大 | 12b §15.2 明确「空态是唯一允许 Headline 级的场景」，与 §16.4 的页标题档有 spec 张力 | 有意保留，不修 | +//! | 3 | 单列页（下载 / 日志）在 1180 下只用掉 **40.6%** 内容宽（424/1044） | 行宽上限的必然结果；空态居中不显空 | 版本浏览真正接数据后重新决议 `PaneKit` | +//! | 4 | 空态图标字形 **40px**（12b 15.1 是 `[估]` 32~48） | 令牌 `IconSize` 只有 24 一档，`frame::glyph` 按尺寸重算 stroke | 组件库的 `EmptyState`（M77）落地时 | +//! | 5 | 窄窗「Back to instances」没有前导箭头 | 占位文本按钮没有图标位 | 真 top bar / M78 的导航件落地时 | +//! | 6 | 实例页「未选中详情」空态**没有出图** | 演示数据固定选中第 1 条；空态代码路径在（`detail_empty`） | D30 状态矩阵补齐时补一张，不必重跑全套 | +//! | 7 | ~~标题栏仍是 48px 留白带~~ → **已于 M90 r2 修**：产品页现在走 `shell::view_with_content`，标题栏 / 拖动热区 / 两条缩放热区 / 三个 caption 键全在 | r1 的实质问题是**交互面缺失**（无边框窗口 + 产品页没有任何窗口装饰 ⇒ 拖不动、缩不了、点不到关闭），不是「少画了一条栏」 | ✅ 已收口（见下） | +//! | 8 | 实例页的「New instance / Import」仍是**没有后端的按钮**（M90） | presenter 没有「打开新建向导」的指令（`wizard` 只有状态机，`AppCommand` 里无对应项），已报 finding | 向导 mission 补 `AppCommand::OpenWizard` 之后 | +//! | 10 | **两套 rail 各测各的**（M90 r3）：产品走 `shell/nav.rs`，组件版只给 harness/单测 | r2 把产品页接进真外壳后，rail 自然落到 `shell/nav.rs`（像素等价，见上）。但两边的守门是分开的：`shell/nav.rs` 自带 indicator 56×32 的单测，`pages/tests.rs` 守的是组件 rail 的 88 ⇒ **将来哪边先漂没人拦**。统一要泛型化 shell 的消息类型，成本大于收益 | 谁做「rail 单一实现」的 mission（已在报告登记）；在那之前任何改 rail 几何的改动都要两处一起改并各自跑守门 | +//! | 9 | 实例页的正文段落只在**演示数据**里出现（M90） | 真快照里没有「正文描述」这种字段；M84 那段 361 字符的 `NOTE` 是给行宽测量当样本的，不能凭空造到真页面里 | i18n / 实例详情 mission 补真实描述字段 | +//! +//! ### 偏离 #7 的收口记录（M90 r2 / P1-1） +//! +//! r1 的产品页渲染的是 `pages::app`：一条**只有高度、没有任何控件**的标题栏留白带。而 +//! `DragWindow` / `ResizeStart` / `Minimize` / `ToggleMaximize` / `Close` 五种消息的**构造点只有 +//! `shell/mod.rs`**，窗口又是 `decorations: false` ⇒ 交互模式下拖不动、缩不了、点不到关闭。 +//! +//! 修法：`shell::view_with_content(ui, nav, title, content, forced)` 把外壳（标题栏 + 三条热区 + +//! 导航轨）与内容区拆开，产品页把 [`page`] 的树塞进内容槽位；`shell::view`（M68 骨架卡）保留给 +//! `Route::Agent` 回落 —— 删了会让私有模块里的 `view` / `shell::nav::rail` 变死代码，`-D warnings` 会红。 +//! +//! `pages::app`（本文件）现在**只服务 harness**（`pages_demo` example 与单测）：它的标题栏仍是留白带， +//! 因为 `shell` 的回调类型是 `crate::app::Message`，套不进 `pages::Message` 的树里。 +//! +//! ## 截图通道 +//! +//! ```text +//! cargo run -p unlucky-app-iced --example pages_demo -- \ +//! --screen=instances --width=1180 --height=760 \ +//! --screenshot=out.png --screenshot-theme=light --software-renderer +//! ``` +//! +//! 产品二进制的截图走 `--screenshot`（页面树由 app 层按路由装配），本 harness 只出**单页**图， +//! 用于页面级回归与宽度对照。 + +pub mod appearance; +pub mod frame; +pub mod harness; +pub mod layout; +pub mod model; + +pub mod account; +pub mod content; +mod download; +mod instances; +mod logs; +mod message; +mod nav; +mod screen; +// M101：设置页的两条漏斗（消息 / 状态）都从这个模块树里出——app 层要构造 +// `settings::GroupMessage`、借用 `settings::Groups`，所以最小暴露面是 `pub(crate)`。 +// **不是** `pub`：`private_interfaces` 按**类型自身的声明可见性**判（四个 `Message` 枚举与 +// `GroupMessage` 声明成 `pub` 就够），把整个设置页模块树暴露成 crate 公开 API 没有回报。 +pub(crate) mod settings; + +#[cfg(test)] +mod tests; +pub use download::{cancelled_toast, Category, Download, InstallDraft, Loader}; +pub use layout::{FrameMetrics, PageLayout, PaneKit, WidthClass}; +pub use logs::{Confidence, Finding, Level, Line, Logs, Outcome}; +pub use message::{Action, Message}; +pub use model::{Detail, Instances, Meta, Model, Row}; +pub use screen::Screen; +pub use settings::Language; + +use iced::widget::{column, container, row, space}; +use iced::{Element, Length}; + +use unlucky_design::elevation::MaterialLayer; + +use crate::theme::Ui; + +use frame::filled; + +/// **单页内容**（不含外壳）：交给 `shell::view_with_content` 塞进真标题栏与导航轨之间。 +/// +/// 产品路径（`app/view.rs`）走 [`page_with_settings`]：外壳由 `shell` 画（拖动/缩放/三个 +/// caption 键、rail 88），这里只画「页头 + 内容列」。列宽仍按**整个窗口宽**算 +/// （`layout::frame_metrics` 内部会扣掉 rail 88 与页边距），所以外壳换了不影响版面判据。 +/// +/// 视图模型由**调用方持有**（`App` 在状态变化时重建一次 `Model`），这里只借用： +/// `view(&self)` 不能返回一棵借用局部变量的树。 +pub fn page<'a>(ui: &'a Ui, model: &'a Model) -> Element<'a, Message> { + render( + ui, + model, + settings::States { + appearance: None, + groups: settings::demo_groups(), + }, + Language::default(), + ) +} + +/// 同 [`page`]，但带上**外观状态**（设置页的「外观」分组要读当前值与诊断）。 +/// +/// 为什么另开一个入口而不是给 `Model` 加字段：`pages/model.rs` 是页面与 presenter 之间的展示 +/// 契约（`Model` 只装「要画什么」），外观是**运行时状态**（滑块请求值、已解码的背景图、诊断）， +/// 塞进去会让演示数据（`pages::demo`）也得伪造一份外观状态。 +/// +/// 这条入口拿的是**演示组状态**（[`settings::demo_groups`]）：页面层没有真组状态可用， +/// 产品路径走 [`page_with_settings`]。 +pub fn page_with_appearance<'a>( + ui: &'a Ui, + model: &'a Model, + appearance: &'a appearance::State, +) -> Element<'a, Message> { + render( + ui, + model, + settings::States { + appearance: Some(appearance), + groups: settings::demo_groups(), + }, + Language::default(), + ) +} + +/// 产品路径：带上**设置页那份只读状态**（外观运行期状态 + 各组自己的状态）。 +/// +/// 为什么要单独一个入口：组状态的所有者是 `App`（`app/state.rs` 的 `settings` 字段），页面层 +/// 只借用一帧。加/改某一组的字段不改变这条签名（`States` 里只有 `&Groups`），所以四条填页线 +/// 都不必来这里动一行。 +/// `language` 是 M106 加的：「当前档位 + 生效语言」只有 `App` 知道（`App::language()`），而设置页 +/// 的 General 组要画它。唯一调用点是 `app/view.rs`；harness 那三条入口（[`page`] / +/// [`page_with_appearance`] / [`app_with_appearance`]）仍用 [`Language::default`]。 +pub fn page_with_settings<'a>( + ui: &'a Ui, + model: &'a Model, + states: settings::States<'a>, + language: Language, +) -> Element<'a, Message> { + render(ui, model, states, language) +} + +fn render<'a>( + ui: &'a Ui, + model: &'a Model, + states: settings::States<'a>, + language: Language, +) -> Element<'a, Message> { + let metrics = layout::frame_metrics(model.screen.kit(), model.window_width); + + match model.screen { + Screen::Instances => instances::view(ui, metrics, model), + // M106：下载页此前写死成 `Lang::En`，现在跟 `model.lang`（页面文案跟着界面语言走）。 + Screen::Download => download::view(ui, metrics, &model.download, model.lang), + // M109：内容库页同样跟 `model.lang` + Screen::Content => content::view(ui, metrics, &model.content, model.lang), + Screen::Settings => settings::view(ui, metrics, states, language), + Screen::Logs => logs::view(ui, metrics, &model.logs, model.lang), + } +} + +/// 整窗（**harness 专用**）：标题栏留白带 + 导航轨 + 当前路由的页面。 +/// +/// 产品路径**不走这里**（它走 [`page`] + `shell::view_with_content`，用真标题栏）。这个入口留给 +/// `pages_demo` example 与单测：它们要一张「只有页面、不接 app 消息」的独立图，而 `shell` 的 +/// 回调类型是 `crate::app::Message`，套不进 `pages::Message` 的树里。 +pub fn app<'a>(ui: &'a Ui, model: &'a Model) -> Element<'a, Message> { + app_with_appearance(ui, model, None) +} + +/// 同 [`app`]，但可以带上**外观运行期状态**。 +/// +/// `Some(state)` ⇒ 设置页「外观」分组画**真控件**（`pages/appearance/section.rs`）； +/// `None` ⇒ 画演示行，与 [`app`] 逐像素等价。harness 的 `--appearance=real` 走的就是这一支： +/// M100 之前 harness 恒传 `None`，于是 D30 要的「带真实外观控件」那一屏**根本不存在**—— +/// 报告上写着「设置页已接真控件」，图里却只有演示行（U1 的形状）。 +pub fn app_with_appearance<'a>( + ui: &'a Ui, + model: &'a Model, + appearance: Option<&'a appearance::State>, +) -> Element<'a, Message> { + // harness 路径没有真组状态：用演示状态（[`settings::demo_groups`]），外观状态照传。 + let body = render( + ui, + model, + settings::States { + appearance, + groups: settings::demo_groups(), + }, + Language::default(), + ); + + let shell = row![nav::rail(ui, model.active), body] + .width(Length::Fill) + .height(Length::Fill); + + let titled = column![titlebar_placeholder(ui), shell] + .width(Length::Fill) + .height(Length::Fill); + + container(titled) + .width(Length::Fill) + .height(Length::Fill) + .style(move |_theme| filled(ui.layer(MaterialLayer::Canvas))) + .into() +} + +/// 演示模型（`pages_demo` example 与单测用；真页面走 `app/view.rs` 的 `AppState` 转换）。 +/// +/// 实例 / 下载 / 日志三页带演示数据，设置页仍是占位视觉。 +pub fn demo_model(screen: Screen, window_width: f32) -> Model { + let mut model = Model::new(screen, window_width, Some(screen.nav())); + match screen { + Screen::Instances => model.instances = instances::demo(), + Screen::Download => model.download = download::demo(unlucky_i18n::Lang::En.catalog()), + Screen::Content => model.content = content::demo(content::ContentKind::Mod, model.lang), + Screen::Logs => model.logs = logs::demo(model.lang), + Screen::Settings => {} + } + model +} + +/// 标题栏留白带（高 = `LayoutMetrics::titlebar_height`）——**只给 [`app`] 的 harness 路径用**。 +/// +/// 产品路径的标题栏是 `shell::view_with_content` 画的那个真的（三个 caption 键 + 拖动热区）， +/// 见模块文档偏离 #7（M90 r2 已修）。 +fn titlebar_placeholder<'a>(ui: &'a Ui) -> Element<'a, Message> { + container(space::horizontal()) + .width(Length::Fill) + .height(ui.metrics().titlebar_height) + .style(move |_theme| filled(ui.layer(MaterialLayer::Canvas))) + .into() +} diff --git a/crates/app-iced/src/pages/model.rs b/crates/app-iced/src/pages/model.rs new file mode 100644 index 0000000..fdde68d --- /dev/null +++ b/crates/app-iced/src/pages/model.rs @@ -0,0 +1,124 @@ +//! 视图模型：**presenter 快照 → 页面要画的东西**的唯一转换产物。 +//! +//! ## 为什么页面不直接吃 presenter 的快照 +//! +//! 页面层（`pages/*`）要能用**两套数据源**喂同一个渲染函数： +//! +//! | 数据源 | 谁转 | 用途 | +//! |---|---|---| +//! | presenter 的 `AppState` 快照 | `app/view.rs` 的自由函数 `model(&AppState, width, forced)` | 产品运行时的真页面 | +//! | `pages/instances/data.rs` 的演示条目 | [`crate::pages::demo`] | M84 骨架图的可复现基线、`pages_demo` example | +//! +//! 如果页面直接读 `InstanceSummary`，演示数据就得先伪造成 `InstanceSummary`（含 core 语义字段）， +//! 基线图会跟着业务 DTO 的每次改动漂。所以中间加一层**纯展示字段**的模型：它只含「要画什么」。 +//! +//! 文本都是 `String`/`&'static str`，没有框架类型——这一层可以纯单测（见 `pages/tests.rs`）。 + +use unlucky_i18n::Lang; +use unlucky_presenter::router::NavSection; + +use crate::app::components::interaction::Interaction; + +use super::content::Content; +use super::logs::Logs; +use super::{Download, Screen}; + +/// 实例列表的一行（`ListItem` 的槽位：overline = 运行状态，headline = 名字，supporting = 版本）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Row { + /// 实例 id（点行 → `Route::Detail(id)`） + pub id: String, + /// 显示名 + pub name: String, + /// 副文案（`1.20.4 · Fabric 0.16.5`） + pub supporting: String, + /// 运行状态（`None` = 空闲，不占 overline 槽位） + pub status: Option, +} + +/// 元信息卡：标签 + 值（`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, +} + +/// 实例页要画的东西。 +#[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, + /// 导航轨高亮项（`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, + /// 界面语言（M106）：页面文案走 i18n key，语言由 app 层决定后灌进来。 + /// + /// 谁填：`app/state.rs` 的 `App::refresh_view`（`LangState::lang()` → `view::model(..)`）， + /// 即「用户档位 / 系统 locale → 生效语言」这条链的结论。**不是**基线值：M95 以前这里是 + /// `Lang::En` 占位，M106 之后中文系统上灌进来的是 `Lang::ZhCn`。 + pub lang: Lang, + /// 取证用的强制交互态（`--force-state`）：`Some` 时页面里的控件按该态画。 + /// + /// M90 r2（P3-1）之前这个开关只作用到 `shell` 回退路径，产品页是**静默失效**的； + /// 现在由 `app/view.rs` 把 `cli::ForcedState` 翻成 `Interaction` 灌进模型。 + pub forced: Option, +} + +impl Model { + /// 空模型（只有外壳参数，页面数据全空）——窄窗退化与空态的构造入口。 + pub fn new(screen: Screen, window_width: f32, active: Option) -> Self { + Self { + screen, + window_width, + active, + instances: Instances::default(), + download: Download::loading(), + logs: Logs::default(), + // 演示模型也从这个空壳起步（`demo_model` 再按页面填数据） + content: super::content::demo(unlucky_presenter::dto::ContentKind::Mod, Lang::En), + lang: Lang::En, + forced: None, + } + } +} diff --git a/crates/app-iced/src/pages/nav.rs b/crates/app-iced/src/pages/nav.rs new file mode 100644 index 0000000..f9dddd1 --- /dev/null +++ b/crates/app-iced/src/pages/nav.rs @@ -0,0 +1,204 @@ +//! 导航轨的**部件版**实现：`NAV` 表 + [`rail`]（宽 = 令牌 `nav_rail_width` = 88）。 +//! +//! ## 两套 rail 的关系（M90 r3 订正，复审 P2-1；M99 把这张表从 `pages/mod.rs` 搬到这里） +//! +//! 产品路径（`app/view.rs`）走 `shell::view_with_content`，导航轨由 **`shell/nav.rs` 的手搓实现**画 +//! ——它与 M78 组件几何同值（宽 88、药丸 56×32），复审逐像素量过「r1 产品图（真组件 rail）vs r2 +//! 产品图（shell rail）在 y≥48 区域差异为 0」。组件版的 [`rail`] 只服务 `pages::app` +//! （`pages_demo` 出口图、harness）与单测。 +//! +//! 两边的守门是分开的：`shell/nav.rs` 自带 indicator 56×32 的单测，`pages/tests.rs` 守的是下面 +//! 这张表（表长 5 / 每一项都指向能高亮它的路由 / 第 5 项没有 section）。**将来哪边先漂没人拦** +//! ——统一要泛型化 shell 的消息类型，成本大于收益；在那之前任何改 rail 几何的改动都要两处一起改 +//! 并各自跑守门（`pages/mod.rs` 偏离登记 #10）。 + +use iced::Element; + +use unlucky_design::icons::IconKind; +use unlucky_i18n::{Key, Lang}; +use unlucky_presenter::router::{NavSection, Route}; + +use crate::app::components::navigation::drawer::{self, Navigation}; +use crate::app::components::navigation::navigation; +use crate::theme::Ui; + +use super::Message; + +/// 导航轨的固定项：图标 + 文案 key + 目标路由（顺序 = 自上而下）。 +/// +/// 顺序与 `presenter::router::NavSection` 的声明顺序一致，改这里等于改导航栏。 +/// +/// 第 3 列是 [`Key`] 而不是字面量（M108）：导航文案归目录管，`pages_demo` 出的图与将来的中文 +/// 界面读的是同一份表，不会出现「页面翻译了、导航还是硬编码英文」。 +/// +/// **显示名 ≠ 标识符**：`Key::NavDownload` 这条说的是「版本管理 / Versions」，而它指向的仍是 +/// `Route::Download`（用户令只改显示层，标识符改名后置）。 +/// +/// 表里存的是**收起态（88）的 key**；展开态（240）要对 [`label_key`] 过一道才换全名。 +/// 可见性是 `pub(crate)`：`pages/tests.rs` 的三条断言读它（M99 从 `pages/mod.rs` 搬出来时， +/// 它从「模块私有」变成「crate 内可见」，断言一条没动、强度也没降）。 +pub(crate) const NAV: [(Option, 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_about.rs b/crates/app-iced/src/pages/settings/ai_about.rs new file mode 100644 index 0000000..6d5aa62 --- /dev/null +++ b/crates/app-iced/src/pages/settings/ai_about.rs @@ -0,0 +1,39 @@ +//! 设置页「AI / About」分组：**预留**（页面上还没有这个分组，左列 4 项里没有它）。 +//! +//! 为什么先留一个空文件：设置页正文接下来由四条线并行接（java / download / language+appearance / +//! ai+about）。文件位置先占好，四条线就不会在同一天抢同一个新文件名；本文件现在是**只有文档**的 +//! 空模块（不产生任何代码，`-D warnings` 不会红）。 +//! +//! ## 接线步骤（ai+about 线照做） +//! +//! 1. 在本文件写 `pub(super) const GROUP: Group = Group { … }`，形状抄 `java.rs`； +//! 2. 到 `settings/mod.rs` 的 `GROUPS` 里加一行 `ai_about::GROUP,`，并把数组长度 `4` 改成 `5`； +//! 3. 文案 key 写进 `crates/i18n/src/catalog/settings/ai.rs`（那边已经接进装配链，同样只改一个文件）。 +//! +//! 界面上「多了一组」这件事本身是行为变化，所以**只在真有那一组内容时才做**，不要为占位先加。 +//! +//! ## M101 起本文件还装本线的状态与消息口 +//! +//! - 状态：[`State`]（`Groups.ai_about` 的载荷，加字段只改本文件）； +//! - 消息：[`Message`]（落点 `app/update/settings/ai_about.rs`）。 +//! +//! 上第 5 组时**额外**要动的共享文件（按上面的步骤 2 + 测试装配）： +//! - `settings/mod.rs` 的 `GROUPS`（加一行，长度 +1）； +//! - `settings/tests/mod.rs` 顶部加一行 `mod ai_section;`（新测试文件不挂 `mod` 就不编译）， +//! 并且左列顺序那条字面量断言会红——那是刻意的（页面上多一组就是观感变了，要人确认）。 +//! +//! 注意 i18n 那边是按**分组**命名的，文案文件叫 `ai.rs` 而不是 `ai_about.rs`。 + +/// AI / About 分组的运行期状态（M101 r2：**只归 ai+about 线**）。 +/// +/// 加字段只改本文件：`Groups` 只认 `Groups.ai_about` 这一个字段。 +#[derive(Debug, Default)] +pub struct State {} + +/// AI / About 线的消息（**只归本线**）。 +/// +/// 首版是空枚举：这一条线的分组还没上页面。空枚举的好处是 +/// `app/update/settings/ai_about.rs` 里的 `match message {}` 天然穷尽——加了变体不接线就报 +/// E0004，不会静默。 +#[derive(Debug, Clone)] +pub enum Message {} diff --git a/crates/app-iced/src/pages/settings/appearance.rs b/crates/app-iced/src/pages/settings/appearance.rs new file mode 100644 index 0000000..6d98023 --- /dev/null +++ b/crates/app-iced/src/pages/settings/appearance.rs @@ -0,0 +1,40 @@ +//! 设置页「Appearance」分组：演示行 + **真控件的接线**（M93 / APPEARWIRE）。 +//! +//! 这一组是设置页唯一接了真控件的：`body = Some(body)`，`body` 直接调 +//! `crate::pages::appearance::section`。`settings/mod.rs` 只按 `group.body` 分发，**不认识 +//! 「Appearance」这个名字**；分组在左列的下标仍由 `crate::pages::appearance::APPEARANCE_GROUP` +//! 声明，`settings/tests/mod.rs` 拿它和本文件比对（顺序被调换会红）。 +//! +//! **这一组归 language+appearance 线**：真控件的实现全在 `pages/appearance/section.rs`（本文件只负责 +//! 把它挂进注册表），所以改控件时不用碰设置页目录。 +//! +//! M101 r2：本组的渲染器签名改成收 [`States`]（组状态 + 外观状态），于是「这一组要读哪些状态」 +//! 由本文件决定——`settings/mod.rs` 不再认识 `appearance::State`。 + +use iced::Element; +use unlucky_design::icons::IconKind; + +use crate::theme::Ui; + +use super::{Group, Message, States}; + +/// Appearance 分组。`body` 指着 [`body`]（它再转给 `pages/appearance/section.rs` 的真控件）； +/// 没有外观运行期状态时（harness / `pages_demo`）返回 `None`，由 `form` 退回下面的演示行。 +pub(super) const GROUP: Group = Group { + name: "Appearance", + icon: IconKind::Sidebar, + rows: &[ + ("Density", "Comfortable"), + ("Corner style", "Follow system"), + ("Motion", "Full"), + ("Text scale", "100%"), + ], + body: Some(body), +}; + +/// 本组的真控件渲染器：有外观状态就画真控件（M93），没有（harness）返回 `None`。 +fn body<'a>(ui: &'a Ui, states: States<'a>) -> Option> { + states + .appearance + .map(|state| crate::pages::appearance::section(ui, state)) +} diff --git a/crates/app-iced/src/pages/settings/download.rs b/crates/app-iced/src/pages/settings/download.rs new file mode 100644 index 0000000..b3d8a09 --- /dev/null +++ b/crates/app-iced/src/pages/settings/download.rs @@ -0,0 +1,36 @@ +//! 设置页「Downloads」分组：首选源 / 并发数 / 校验（演示行）。 +//! +//! **这一组归 download 线**：接真控件时在本文件把 `body` 换成 `Some(download::body)`（渲染器也写在本文件）， +//! `settings/mod.rs` 的注册表不用动。 +//! +//! 注意与下载页（`pages/download*`）的区别：那是「装哪个版本」，这里是「怎么下」的默认值。 + +use unlucky_design::icons::IconKind; + +use super::Group; + +/// Downloads 分组。 +pub(super) const GROUP: Group = Group { + name: "Downloads", + icon: IconKind::Download, + rows: &[ + ("Preferred source", "Automatic (region)"), + ("Concurrency", "8 threads"), + ("Verify checksums", "On"), + ], + body: None, +}; + +/// Downloads 分组的运行期状态（M101 r2：**只归 download 线**）。 +/// +/// 加字段只改本文件：`Groups` 只认 `Groups.download` 这一个字段。 +#[derive(Debug, Default)] +pub struct State {} + +/// Downloads 分组的消息（M101：**只归 download 线**，加变体只改本文件）。 +/// +/// 落点是 `app/update/settings/download.rs`；`pages/mod.rs` 与 `page_messages.rs` 都不用动（它们只认 +/// [`GroupMessage`](super::GroupMessage)）。异步结果（例如「测这个源可用」）在自己那条落点里构造 +/// `Message::Page(pages::Message::Settings(GroupMessage::Download(…)))` 回来即可。 +#[derive(Debug, Clone)] +pub enum Message {} diff --git a/crates/app-iced/src/pages/settings/frame.rs b/crates/app-iced/src/pages/settings/frame.rs new file mode 100644 index 0000000..438744d --- /dev/null +++ b/crates/app-iced/src/pages/settings/frame.rs @@ -0,0 +1,219 @@ +//! 设置页骨架：页头、左列分组导航、表单列的滚动区、演示卡片、空态位。 +//! +//! ## 为什么这里还再导出一批 `pages::frame` 的名字 +//! +//! M99 拆目录时立的硬要求是**纯搬移**：调用点一字不改。设置页原来的代码从 `super::frame` 取词 +//! （`frame::text_role` / `frame::card` / `frame::ICON_PX` …）；拆成目录后 `frame` 这个名字落到了 +//! 本文件上，于是把用到的那几件**再导出**一次，`mod.rs` / `tests.rs` 的调用点就能原样保留。 +//! 这不是新 API，只是一条转发（新增控件仍归 [`crate::pages::frame`]）。 + +pub(super) use super::super::frame::{ + card, divider, empty_state, glyph_box, left_aligned, page, panes, scroll_style, single_column, + text_action, text_role, Header, ICON_PX, SCROLLBAR_MARGIN, SCROLLBAR_WIDTH, +}; + +use iced::widget::{column, container, mouse_area, row, scrollable}; +use iced::{Alignment, Background, Border, Element, Length, Padding}; + +use unlucky_design::color::Role; +use unlucky_design::component_map::Component; +use unlucky_design::elevation::MaterialLayer; +use unlucky_design::icons::IconKind; +use unlucky_design::shape::ShapeScale; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; +use unlucky_i18n::{Key, Lang}; + +use crate::pages::appearance::Change; +use crate::pages::{Action, Message}; +use crate::theme::Ui; + +use super::Group; + +/// 空态位高度：给图标块 96 + 标题 + 副文案 + 按钮留够空间（`[估]`，按 12b §15 的元素最小高度累加）。 +const EMPTY_SLOT_HEIGHT: f32 = 320.0; + +/// 页头：标题 + 副标题 + 两个占位动作。 +/// +/// M106：三条文案走 catalog（`lang` 由 `settings::view` 传下来）。页标题复用 `NavSettings`—— +/// 左列与页头说的是同一件事，不该有第二条译文。 +pub(super) fn header<'a>(ui: &'a Ui, lang: Lang) -> Header<'a> { + let catalog = lang.catalog(); + Header::new(catalog.text(Key::NavSettings)) + .subtitle(catalog.text(Key::SettingsSubtitle)) + .action(text_action( + ui, + catalog.text(Key::SettingsResetSection), + Action::ResetSection, + )) + .action(text_action( + ui, + catalog.text(Key::SettingsSave), + Action::SaveSettings, + )) +} + +// --------------------------------------------------------------- 侧列 + +/// 左列分组导航（supporting-pane 的辅助列，宽 = 令牌 `nav_drawer_width` = 240）。 +pub(super) fn group_nav<'a>(ui: &'a Ui, selected: usize, lang: Lang) -> Element<'a, Message> { + let catalog = lang.catalog(); + let items = column( + super::GROUPS + .iter() + .enumerate() + .map(|(index, group)| { + let label = super::GROUP_LABELS + .get(index) + .map_or(group.name, |key| catalog.text(*key)); + group_item(ui, group, label, index, index == selected) + }) + .collect::>(), + ) + .spacing(ui.space(Space::X1)) + .padding(Padding::from([ui.space(Space::X2), ui.space(Space::X2)])) + .width(Length::Fill); + + container(items) + .width(Length::Fill) + .height(Length::Fill) + .style(move |_theme| container::Style { + background: Some(Background::Color(ui.layer(MaterialLayer::Card))), + border: Border { + radius: ui.radius_dp(ShapeScale::Large), + ..Border::default() + }, + ..container::Style::default() + }) + .into() +} + +fn group_item<'a>( + ui: &'a Ui, + group: &'a Group, + label: &'a str, + index: usize, + selected: bool, +) -> Element<'a, Message> { + let spec = Component::NavigationItem.spec(); + let height = ui.metrics().row_height; + + let content_color = if selected { + ui.color(Role::OnSecondaryContainer) + } else { + ui.color(Role::OnSurfaceVariant) + }; + + let inner = row![ + glyph_box(group.icon, content_color, ICON_PX), + text_role(ui, spec.text, false, label, content_color), + ] + .spacing(ui.space(Space::X3)) + .width(Length::Fill) + .align_y(Alignment::Center); + + let pill = container(inner) + .width(Length::Fill) + .height(height) + .padding(Padding::from([0.0, ui.space(Space::X3)])) + .align_y(Alignment::Center) + .style(move |_theme| container::Style { + background: selected.then(|| Background::Color(ui.color(Role::SecondaryContainer))), + border: Border { + radius: ui.radius(ShapeScale::Full, height), + ..Border::default() + }, + ..container::Style::default() + }); + + // 点选切分组：走页面自己的 `Message::Appearance(SelectGroup)`（只改视图状态，不落盘）。 + mouse_area(pill) + .on_press(Message::Appearance(Change::SelectGroup(index))) + .into() +} + +// --------------------------------------------------------------- 表单列 + +/// 表单列的滚动区：只有正文滚，页头不动（与实例页列表列同一套口径）。 +/// +/// 「外观」分组有 7 个控件 + 最多 3 行诊断，1180×760 下会超出可视区，所以这一层是必需的。 +pub(super) fn scroll<'a>( + ui: &'a Ui, + content: impl Into>, +) -> Element<'a, Message> { + scrollable(content) + .direction(scrollable::Direction::Vertical( + scrollable::Scrollbar::new() + .width(SCROLLBAR_WIDTH) + .scroller_width(SCROLLBAR_WIDTH) + .margin(SCROLLBAR_MARGIN), + )) + .height(Length::Fill) + .style(scroll_style(ui)) + .into() +} + +/// 演示行构成的一组设置 = 一张卡，行间 1px 分隔线（M3 设置列表的常规做法）。 +/// +/// 已经接了真控件的分组（`GROUP.body` 是 `Some`）不走这里。 +pub(super) fn demo_card<'a>( + ui: &'a Ui, + rows: &'a [(&'static str, &'static str)], +) -> Element<'a, Message> { + let mut stacked = column![].spacing(0.0).width(Length::Fill); + + for (index, (label, value)) in rows.iter().enumerate() { + if index > 0 { + stacked = stacked.push(divider(ui)); + } + stacked = stacked.push(setting_row(ui, label, value)); + } + + card(ui, stacked) +} + +fn setting_row<'a>(ui: &'a Ui, label: &'a str, value: &'a str) -> Element<'a, Message> { + let height = ui.metrics().control_height + Space::X2.dp(); + + row![ + container(text_role( + ui, + TypeRole::BodyMedium, + false, + label, + ui.color(Role::OnSurface), + )) + .width(Length::Fill) + .align_y(Alignment::Center), + text_role( + ui, + TypeRole::BodySmall, + false, + value, + ui.color(Role::OnSurfaceVariant), + ), + ] + .height(height) + .width(Length::Fill) + .align_y(Alignment::Center) + .into() +} + +/// 空态位：没有逐实例覆盖时的样子（12b §15 的口径）。 +pub(super) fn overrides_empty<'a>(ui: &'a Ui, lang: Lang) -> Element<'a, Message> { + let catalog = lang.catalog(); + container(empty_state( + ui, + IconKind::Instances, + catalog.text(Key::SettingsOverridesEmptyTitle), + catalog.text(Key::SettingsOverridesEmptyBody), + vec![text_action( + ui, + catalog.text(Key::SettingsOverridesAdd), + Action::AddOverride, + )], + )) + .width(Length::Fill) + .height(Length::Fixed(EMPTY_SLOT_HEIGHT)) + .into() +} diff --git a/crates/app-iced/src/pages/settings/general.rs b/crates/app-iced/src/pages/settings/general.rs new file mode 100644 index 0000000..9ece9c3 --- /dev/null +++ b/crates/app-iced/src/pages/settings/general.rs @@ -0,0 +1,225 @@ +//! 设置页「General」分组：语言选择器 + 主题 / 启动页 / 关闭按钮（M106 接真控件）。 +//! +//! **这一组归 language+appearance 线**（M101 的分线口径）。 +//! +//! ## 这一组为什么特殊 +//! +//! 它**不走** `Group::body`：那个渲染器的签名是 `fn(&Ui, States) -> Option`，`States` 只有 +//! `appearance` + `groups` 两格，装不下「当前语言档位 + 生效语言」。语言行要的两件在 +//! `pages::Language` 里，由 `pages::settings::view` 的 `language` 形参一路递进来、`form` 按下标 +//! 转交 [`body`]；所以 `GROUP.body` 仍是 `None`，`tests/mod.rs` 那条「只有外观组带真控件」照样成立。 +//! +//! ## 语言切换**没有**走 M101 的 `GroupMessage` 投递口（偏离，已登记） +//! +//! `settings/mod.rs` 的文档说本线要加消息就加到 `settings/language_appearance.rs` 的 `Message` 上。 +//! M106 走的是 `pages::Message::Language(choice)` 这条独立增量，理由：语言档位不是「某一组的状态」， +//! 它要**落盘**（`ui.language`）+ **重建整棵视图模型**（目录是 `pages::Model` 的一部分），而落点 +//! `app/update/settings/language_appearance.rs` 与消息口 `language_appearance.rs` 都不在本 mission 的 +//! scope 内。代价：`page_messages.rs` 多一支（那是 M101 想收掉的共享锚点）。**收口方向**：等本线 +//! 再动设置页时，把 `Message::Language` 折进 `GroupMessage::LanguageAppearance(SetChoice)`，并把 +//! `pages/mod.rs` 的这支删掉——finding 已登记。 +//! +//! ## 语言行的三个事实 +//! +//! 1. **选中态显示的是档位**（跟随系统 / 简体中文 / 英文），不是「猜出来的语言」——用户点过什么 +//! 就得画回什么，否则「我明明选了跟随系统」这件事在界面上无从确认； +//! 2. **旁边回显生效语言**（`界面当前使用：简体中文`）：中文系统 + 跟随系统时，这一行是「界面 +//! 真的用了中文」的唯一可见证据（用户报的 bug 正是「识别到了但没用上」）； +//! 3. **文案全部走 catalog**（[`Key`]），三档选项名跟着界面语言走（见 `catalog/general.rs` +//! 的头注释：为什么不写语言自称）。 +//! +//! ## 其余三行仍只读 +//! +//! 主题 / 启动页 / 关闭按钮还没有后端（`pages::Action` 里是占位动作），所以它们是**只读行**； +//! 但标签与取值已经进 catalog，中文界面下不会再冒出英文。 +//! +//! 分组元数据只有一份（这里的 [`GROUP`]）：`settings/mod.rs` 的 `GROUPS` 直接引用它。 + +use iced::widget::{button, column, container, row}; +use iced::{Alignment, Background, Border, Element, Length, Padding, Shadow, Theme as IcedTheme}; + +use unlucky_design::color::{Role, StateLayer}; +use unlucky_design::icons::IconKind; +use unlucky_design::shape::ShapeScale; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; +use unlucky_i18n::catalog::Key; +use unlucky_i18n::LangChoice; + +use crate::pages::{frame, Language, Message}; +use crate::theme::Ui; + +use super::frame::{card, divider}; +use super::Group; + +/// General 分组（左列名固定英文：左列是**导航**，与导航轨同源，不进 catalog）。 +pub(super) const GROUP: Group = Group { + name: "General", + icon: IconKind::Settings, + // 只给 harness（`pages_demo` 走 `appearance: None` 时）用的演示行：产品路径走 [`body`]。 + // 语言那一行**不在**这里——它的值是要跟着语言变的，写死在静态表里就是用户看到的那条假值。 + rows: &[ + ("Theme", "Follow system"), + ("Startup page", "Instances"), + ("Close button", "Exit to tray"), + ], + body: None, +}; + +/// 这一组的正文（**产品路径**）。 +pub(super) fn body<'a>(ui: &'a Ui, language: Language) -> Element<'a, Message> { + let catalog = language.effective.catalog(); + let mut stacked = column![].spacing(0.0).width(Length::Fill); + stacked = stacked.push(language_row(ui, language)); + + // 主题 / 启动页 / 关闭按钮：还没有后端，只读；文案已经进 catalog。 + for (label, value) in [ + (Key::SettingsTheme, Key::SettingsThemeFollowSystem), + (Key::SettingsStartupPage, Key::SettingsStartupInstances), + (Key::SettingsCloseButton, Key::SettingsCloseToTray), + ] { + stacked = stacked.push(divider(ui)); + stacked = stacked.push(setting_row(ui, catalog.text(label), catalog.text(value))); + } + + card(ui, stacked) +} + +/// 语言行：标题 + 生效语言回显 + 三档互斥按钮 + 一句说明。 +fn language_row<'a>(ui: &'a Ui, language: Language) -> Element<'a, Message> { + let catalog = language.effective.catalog(); + let effective = LangChoice::Fixed(language.effective).label_key(); + + let head = row![ + container(frame::text_role( + ui, + TypeRole::BodyMedium, + false, + catalog.text(Key::SettingsLanguage), + ui.color(Role::OnSurface), + )) + .width(Length::Fill) + .align_y(Alignment::Center), + frame::text_role_owned( + ui, + TypeRole::LabelLarge, + true, + catalog.render( + Key::SettingsLanguageEffective, + &[("language", catalog.text(effective))], + ), + ui.color(Role::OnPrimaryFixedVariant), + ), + ] + .width(Length::Fill) + .align_y(Alignment::Center); + + let chips = row(LangChoice::ALL + .iter() + .map(|choice| { + chip( + ui, + catalog.text(choice.label_key()), + *choice == language.choice, + *choice, + ) + }) + .collect::>()) + .spacing(ui.space(Space::X1)) + .align_y(Alignment::Center); + + column![ + head, + chips, + frame::text_role( + ui, + TypeRole::BodySmall, + false, + catalog.text(Key::SettingsLanguageHint), + ui.color(Role::OnSurfaceVariant), + ), + ] + .spacing(ui.space(Space::X1)) + .width(Length::Fill) + .padding(Padding::from([ui.space(Space::X2), 0.0])) + .into() +} + +/// 一个只读的「标签 + 取值」行（与 `frame::demo_card` 的一行同高同排版）。 +fn setting_row<'a>(ui: &'a Ui, label: &'a str, value: &'a str) -> Element<'a, Message> { + let height = ui.metrics().control_height + Space::X2.dp(); + + row![ + container(frame::text_role( + ui, + TypeRole::BodyMedium, + false, + label, + ui.color(Role::OnSurface), + )) + .width(Length::Fill) + .align_y(Alignment::Center), + frame::text_role( + ui, + TypeRole::BodySmall, + false, + value, + ui.color(Role::OnSurfaceVariant), + ), + ] + .height(height) + .width(Length::Fill) + .align_y(Alignment::Center) + .into() +} + +/// 一个互斥按钮（选中态 `SecondaryContainer`，未选中透明 + `OnSurfaceVariant`）。 +/// +/// 与 `pages/appearance/section.rs` 的 `choice` 同款，但文案来自 catalog（那份是英文基线）。 +fn chip<'a>(ui: &'a Ui, text: &'a str, selected: bool, choice: LangChoice) -> Element<'a, Message> { + let height = ui.metrics().control_height; + let content_color = if selected { + ui.color(Role::OnSecondaryContainer) + } else { + ui.color(Role::OnSurfaceVariant) + }; + + button( + container(frame::text_role( + ui, + TypeRole::LabelLarge, + selected, + text, + content_color, + )) + .align_y(Alignment::Center), + ) + .height(height) + .padding(Padding::from([0.0, ui.space(Space::X3)])) + .style(move |_theme: &IcedTheme, status| { + let background = if selected { + Some(Background::Color(ui.color(Role::SecondaryContainer))) + } else if matches!(status, button::Status::Hovered | button::Status::Pressed) { + Some(Background::Color(ui.state_over( + StateLayer::Hover, + Role::OnSurface, + Role::Surface, + ))) + } else { + None + }; + + button::Style { + background, + text_color: content_color, + border: Border { + radius: ui.radius(ShapeScale::Full, height), + ..Border::default() + }, + shadow: Shadow::default(), + snap: true, + } + }) + .on_press(Message::Language(choice)) + .into() +} diff --git a/crates/app-iced/src/pages/settings/java.rs b/crates/app-iced/src/pages/settings/java.rs new file mode 100644 index 0000000..dac13c9 --- /dev/null +++ b/crates/app-iced/src/pages/settings/java.rs @@ -0,0 +1,44 @@ +//! 设置页「Java」分组：运行时 / 默认内存 / JVM 参数（演示行）。 +//! +//! **这一组归 java 线**：接真控件时在本文件把 `body` 换成 `Some(java::body)`（渲染器也写在本文件）， +//! 再把 `rows` 换成真数据源给的文本；`settings/mod.rs` 的注册表不用动。 +//! +//! 图标说明（视觉复审 P2-3）：令牌里 `Play` 是填充字形，和同屏其它描边图标语汇打架； +//! Java 分组讲的是运行时安装位置，用目录图标语义也对得上。 + +use unlucky_design::icons::IconKind; + +use super::Group; + +/// Java 分组。 +pub(super) const GROUP: Group = Group { + name: "Java", + icon: IconKind::Folder, + rows: &[ + ("Runtime", "Temurin 21.0.4"), + ("Default memory", "4 GiB"), + ("JVM arguments", "Automatic"), + ], + body: None, +}; + +/// Java 分组的运行期状态（M101 r2：**只归 java 线**）。 +/// +/// 加字段只改本文件：`Groups` 只认 `Groups.java`（一个字段），不认这个类型里的任何字段， +/// 所以 `settings/mod.rs` / `app/state.rs` / `app/view.rs` 都不用动。 +#[derive(Debug, Default)] +pub struct State {} + +/// Java 分组的消息（M101：**只归 java 线**，加变体只改本文件）。 +/// +/// 落点是 `app/update/settings/java.rs`；`pages/mod.rs` 与 `page_messages.rs` 都不用动（它们只认 +/// [`GroupMessage`](super::GroupMessage)）。 +#[derive(Debug, Clone)] +pub enum Message { + /// **只有测试构造它**：M101 r2 留的「活的端到端证据」——外壳消息 → + /// `on_page` → `on_settings` → `on_settings_java` 这条路在运行时真的跑通，不是只靠编译期穷尽。 + /// java 线接第一个真控件时把这一支换成真变体：`tests/java_section.rs` 的 + /// `the_java_group_is_still_demo_rows` 就是那条会提醒你的绊线（它断言 `body.is_none()`）。 + #[cfg(test)] + Ping, +} diff --git a/crates/app-iced/src/pages/settings/language_appearance.rs b/crates/app-iced/src/pages/settings/language_appearance.rs new file mode 100644 index 0000000..f167c03 --- /dev/null +++ b/crates/app-iced/src/pages/settings/language_appearance.rs @@ -0,0 +1,35 @@ +//! 设置页 language+appearance 线的**消息口 + 状态口**（M101 `SETTINGSMSG`）。 +//! +//! 为什么另开一个文件而不是塞进 `general.rs`：这一条线管**两个分组**（General 的语言 / 主题 / +//! 启动页 / 关闭按钮，Appearance 的密度 / 圆角 / 动效 / 文字缩放）。两个分组各有自己的正文文件 +//! （`settings/general.rs`、`settings/appearance.rs`），消息与状态却只能有一个类型挂到 +//! [`GroupMessage::LanguageAppearance`](super::GroupMessage::LanguageAppearance) / +//! [`Groups::language_appearance`](super::Groups) 上——否则 `GroupMessage` 与 `Groups` 会多出第五个 +//! 槽位，本线就要改 `settings/message.rs` / `settings/state.rs`（共享文件）。 +//! +//! ## 本线的文件集合（只归本线，四条线两两不相交） +//! +//! | 文件 | 作用 | +//! |---|---| +//! | 本文件 | 消息枚举 + 状态结构（加一支消息 / 一个字段只改这里） | +//! | `settings/general.rs` / `settings/appearance.rs` | 两个分组各自的 `GROUP`（名字 / 图标 / 行 / body） | +//! | `settings/tests/general_section.rs` / `settings/tests/appearance_section.rs` | 两组的独立断言 | +//! | `crates/i18n/src/catalog/settings/general.rs` / `appearance.rs` | 两组的文案 key | +//! | `crates/app-iced/src/app/update/settings/language_appearance.rs` | 消息的落点 | +//! +//! 真控件那半边在 `pages/appearance/section.rs`（`appearance.rs` 只负责把 `body` 挂上去）。 + +/// 语言 + 外观线的状态（**只归本线**）。 +/// +/// 首版是空结构：这一条线还没有自己的运行期状态（外观那份状态是 `pages::appearance::State`， +/// 归 M93，走 `States::appearance` 那条既有通道，不在这里）。加字段只改本文件。 +#[derive(Debug, Default)] +pub struct State {} + +/// 语言 + 外观线的消息（**只归本线**）。 +/// +/// 首版是空枚举：这一条线还没有接真下拉 / 真控件之前，没有可点的东西。空枚举的好处是 +/// `app/update/settings/language_appearance.rs` 里的 `match message {}` 天然穷尽——加了变体 +/// 不接线就报 E0004，不会静默。 +#[derive(Debug, Clone)] +pub enum Message {} diff --git a/crates/app-iced/src/pages/settings/message.rs b/crates/app-iced/src/pages/settings/message.rs new file mode 100644 index 0000000..be4fcdd --- /dev/null +++ b/crates/app-iced/src/pages/settings/message.rs @@ -0,0 +1,106 @@ +//! 设置页的**分组消息投递口**（M101 `SETTINGSMSG`）：四条填页线各写各的变体，不再抢 +//! `pages/mod.rs` 的枚举尾部与 `app/update/page_messages.rs` 那条不许兜底的 match。 +//! +//! ## 这一层为什么存在 +//! +//! M100 把设置页的**文件**按分区拆开了，但四条线真正的交汇处仍是同一处追加锚点： +//! `pages::Message` 的枚举尾部 + `page_messages.rs` 的 match 臂（该 match 有 +//! `the_page_match_has_no_wildcard_fallback` 守门，不许 `_ =>`）。四个变体、四条线、两个共享 +//! 文件 ⇒ 四路并行必然四路冲突。M101 只做一件事：把「加消息」从共享文件搬进各组自己的文件—— +//! `pages::Message` 从此只有**这一个**设置页变体。 +//! +//! ```text +//! pages::Message::Settings(GroupMessage) +//! ├─ Java(java::Message) → settings/java.rs +//! ├─ Download(download::Message) → settings/download.rs +//! ├─ LanguageAppearance(language_appearance::Message) → settings/language_appearance.rs +//! └─ AiAbout(ai_about::Message) → settings/ai_about.rs +//! ``` +//! +//! 四个载荷**必须**是四个不同类型、分别定义在四个文件里；否则「两条线往同一个枚举里加变体」的 +//! 冲突只是从 `pages/mod.rs` 搬到了这里。`each_group_owns_its_own_message_type` 用 `type_name` +//! 里的模块路径守这一条。 +//! +//! ## 加一支设置页消息要改几个文件（M101 r2 之后） +//! +//! **2 个**：你自己那条线的消息口文件（`settings/<线>.rs`）加一个变体，加上你那条落点 +//! （`app/update/settings/<线>.rs`）接一条臂——两处都只归你。`pages/mod.rs`、 +//! `page_messages.rs`、`settings/message.rs`、`settings/state.rs`、`app/update/settings.rs` 都不用动。 +//! +//! ## 穷尽性：抓得住什么 / 抓不住什么 +//! +//! - **抓得住**：某条线加了变体却忘了接线 → 编译器在 `app/update/settings.rs` 的 match 上报 +//! **E0004**（那里对 [`GroupMessage`] 做穷尽匹配，没有 `_ =>`）。注意 `page_messages.rs` +//! 那条守卫只认 `pages::Message`，**它抓不住组内变体**——把守卫下放到 `settings.rs` 正是本层 +//! 的第二个目的，两个 dispatch 各守一层。 +//! - **抓不住**：handler 忽略消息（`let _ = message; Task::none()`）或两个 handler 的**身体**被 +//! 写成一样——类型对得上就编得过。那要人读，或者等真接业务后由「点了没反应」的用例抓。 +//! +//! 类型还顺手挡掉了另一种错：把 `Java(m)` 转给 `on_settings_download` 编不过（载荷类型不同）， +//! 所以「接错组」这一半是编译期兜住的，「接了个空壳」那一半不是。 +//! +//! ## 测试 +//! +//! 本文件的 [`tests::each_group_owns_its_own_message_type`]；dispatch 侧的 +//! `the_group_dispatch_has_no_catch_all_arm` 在 `app/update/settings/tests.rs`（`app/update/settings.rs` +//! 只是 `#[cfg(test)] mod tests;` 的声明点，别去那里找）。 + +use super::{ai_about, download, java, language_appearance}; + +/// 设置页分组消息：**唯一**一个进 `pages::Message` 的投递口。 +/// +/// 每个变体只归一条线，载荷类型定义在那条线自己的文件里（见模块文档的四个箭头）。 +/// 加变体 = 改自己那个文件 + 改 `app/update/settings/<线>.rs`，两处都只归你。 +#[derive(Debug, Clone)] +pub enum GroupMessage { + /// Java 分组（`settings/java.rs`）。 + Java(java::Message), + /// Downloads 分组（`settings/download.rs`）。 + Download(download::Message), + /// 语言 + 外观两组的共同消息口（`settings/language_appearance.rs`）。 + LanguageAppearance(language_appearance::Message), + /// AI / About 分组（`settings/ai_about.rs`）。 + AiAbout(ai_about::Message), +} + +#[cfg(test)] +mod tests { + use super::*; + + /// 四条线的载荷**必须**住在四个不同文件里。 + /// + /// 抓得住：① 为了少建一个文件，把两个组的 `Message` 塞进同一个文件（四条线又会撞同一个 + /// 追加锚点，本 mission 的目的当场作废）；② 谁把某个分组文件改名后忘了同步（`type_name` + /// 里带模块路径，改名就红）。 + /// 抓不住：变体装得对不对（那是 `app/update/settings.rs` 的 E0004 与其守卫的事），也抓不住 + /// handler 身体写空/写反（类型对得上就编得过）。 + #[test] + fn each_group_owns_its_own_message_type() { + let homes = [ + ( + std::any::type_name::(), + "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..d06d737 --- /dev/null +++ b/crates/app-iced/src/pages/settings/mod.rs @@ -0,0 +1,326 @@ +//! 设置页：**supporting-pane** 的用例（左侧分组导航 240 + 右侧表单列 ≤424）。 +//! +//! ## 为什么是 supporting-pane 而不是 list-detail +//! +//! 分组导航是**辅助**（它不承载数据，只切换右侧表单的内容），右侧表单才是阅读对象； +//! 官方把这种「主列 + 窄侧列」叫 supporting pane。list-detail 的前提是左列本身是一份可浏览的数据集 +//! （实例列表就是），设置页不满足。 +//! +//! ## 侧列与 rail 的关系（D33） +//! +//! 宽度 240 直接取 `LayoutMetrics::nav_drawer_width`（D33：同一容器 rail 88 ⇄ drawer 240 的展开态）， +//! 但**不复制 rail 的实现**：这里没有 hover 药丸、没有二级标签、没有 `Message::Select`。 +//! 将来真正的 `NavigationDrawer` 由 M78 提供，本页换掉 [`frame::group_nav`] 即可。 +//! +//! ## 退化（窗口 <720 或 compact 档） +//! +//! 侧列消失，分组导航退化成「按组堆叠」：同一列里每组一张卡 + 一段 12pt 组名。整页仍居中、正文列仍 ≤424。 +//! +//! ## 文件地图（M99 `SETTINGSFRAME`：**纯搬移**，行为与视觉零变化） +//! +//! 本文件只做三件事：**分组注册表**（[`GROUPS`]）、**内容分发**（[`form`] 按分组挑渲染器）、 +//! 以及 M101 加的两条漏斗的**转发**（消息 → [`message`]，状态 → [`state`]）。 +//! 一组的正文、文案、演示行、状态、消息都在它自己的文件里： +//! +//! | 分组 | 文件（正文 / 状态 / 消息） | 谁会动它 | +//! |---|---|---| +//! | General | [`general`] | language+appearance 线（语言下拉 + 主题 / 启动页） | +//! | Appearance | [`appearance`] | language+appearance 线（真控件已在 `pages/appearance/section.rs`） | +//! | Java | [`java`] | java 线 | +//! | Downloads | [`download`] | download 线 | +//! | （页面上还没有这个分组） | [`ai_about`] | ai+about 线：先建分组再接线 | +//! | 页头 / 侧列 / 滚动区 / 演示卡片 / 空态位 | [`frame`] | 谁都不该改（改了就是改版面） | +//! +//! ## 测试也按 section 分（M100） +//! +//! 断言跟着它守的东西走，于是四条 section 线**各改各的测试**： +//! +//! | 测试文件 | 守什么 | 谁会动它 | +//! |---|---|---| +//! | `tests/general_section.rs` | General 自己的行 / 图标 / body 现状 | language+appearance 线 | +//! | `tests/appearance_section.rs` | Appearance 自己的行 / 图标 / body 现状 | language+appearance 线 | +//! | `tests/java_section.rs` | Java 自己的行 / 图标 / body 现状 | java 线 | +//! | `tests/download_section.rs` | Downloads 自己的行 / 图标 / body 现状 | download 线 | +//! | `tests/mod.rs` | **跨 section**：版面契约、行宽上限、窄窗退化、注册表顺序 / 分组下标 / 每条线的漏斗安装情况 | 谁都别随手改（每条都写了为什么不能下放） | +//! +//! 判据：**给某一组加一条新断言 = 只改它自己那个测试文件**。 +//! +//! **加一个分组要动哪里**：① 在它自己的文件里写一个 `pub(super) const GROUP`（名字 / 图标 / 演示行 / +//! 可选的真控件渲染器 `body`）；② 本文件的 [`GROUPS`] 加一行、数组长度 +1；③ [`state::Groups`] 加一个 +//! 字段、[`message::GroupMessage`] 加一个变体、`app/update/settings.rs` 加一条臂。**不需要**动 `frame.rs`、 +//! 别的分组文件或 `pages/mod.rs`。 +//! +//! ## 消息：一个投递口，四条线各写各的（M101 `SETTINGSMSG`） +//! +//! 四条填页线都要往 `pages::Message` 里加变体，而那是**一个**枚举加上 +//! `app/update/page_messages.rs` 里一条不许 `_ =>` 的 match —— 四路并行必然四路冲突。 +//! M101 把这件事收成一个投递口： +//! +//! ```text +//! pages::Message::Settings(GroupMessage) ← 全 crate 只有这一个设置页变体 +//! ├─ Java(java::Message) → settings/java.rs +//! ├─ Download(download::Message) → settings/download.rs +//! ├─ LanguageAppearance(language_appearance::Message) → settings/language_appearance.rs +//! └─ AiAbout(ai_about::Message) → settings/ai_about.rs +//! ``` +//! +//! 加一支消息 = 改自己那个消息口文件 + 自己那条落点（`app/update/settings/<线>.rs`），2 个文件、 +//! 0 个共享文件。四个消息口枚举声明成 `pub` 是为了过 `private_interfaces`：那条 lint 按**类型自身 +//! 的声明可见性**判，所以模块用最小的 `pub(crate)`（`pages/mod.rs` 的 `pub(crate) mod settings;`） +//! 就够，不必把整个设置页模块树暴露成 crate 公开 API。 +//! +//! ## 状态：与消息同构的状态漏斗（M101 r2，r1 复审 P1） +//! +//! ```text +//! App.settings: state::Groups ← app/state.rs 一行（M101 加一次，四条线都不碰） +//! ├─ java / download / language_appearance / ai_about：各自的 State 在各自文件里 +//! States { appearance, groups } ← 只读视图，按值传给 view；每组的 GROUP.body 自己取自己要的那份 +//! ``` +//! +//! **加/改某一组的字段**只改 `pages/settings/<组>.rs`；**异步结果**在自己那条落点里构造 +//! `Message::Page(pages::Message::Settings(GroupMessage::<线>(…)))` 回来——`Page` 这条既有通道就是 +//! 异步结果的入口，`app::Message` / `app/update.rs` 都不用动。 +//! +//! ### 仍然共享的点（四条线都可能碰到，只能靠 tower 串行合并，或者由专人一次性做掉） +//! +//! 1. `crates/i18n/src/catalog/golden.rs` —— 每加一条文案 key 都要按声明顺序往金表里插一行 +//! （`split_keeps_every_translation` 逐条比 key + 英/中译文）。**注意**：`catalog.rs` 的 `Key` +//! 枚举由 `catalog!` 宏从各域文件累积生成，加 key **不用**改 `catalog.rs`，也不用改 +//! `catalog/settings/mod.rs`（五个域已全部接进装配链）。 +//! 2. 本文件的 [`GROUPS`] —— 只有 ai+about 线**上第 5 组**时加一行（页面上多一组本来就是整页的变化）。 +//! 3. `tests/mod.rs` —— ai+about 线新建 `tests/ai_section.rs` 时要加一行 `mod ai_section;` +//! （测试文件不挂 `mod` 就不编译），以及「左列顺序」那条字面量断言会连带红，需要人确认。 +//! 4. **读页外真值**（r2 复审 P1 补的）—— [`States`] 只有 `appearance` + `groups` 两格，组正文读不到 +//! `pages::Model`（「当前语言」的值在 `Model.lang`，`pages/model.rs`），也读不到 presenter 的设置 +//! 快照。两条路的**真实成本**（`States` 没有 `Default`，加字段必然 E0063，已实测）： +//! - 把 `model` **塞进 [`States`]** ⇒ struct literal 有 **4 处**（`pages/mod.rs:154/177/232` 与 +//! `app/view.rs:70`），四处都要补字段 ⇒ **3 个共享文件**：`settings/state.rs`、`pages/mod.rs`、 +//! **`app/view.rs`**（最后这个正是 M104 的落点，本 mission 反复设锚点要避开的就是它）； +//! - 给 `settings::view` **加一个 `model: &Model` 形参**（`pages/mod.rs` 的 `render` 本来就拿着 +//! `model`，直接往下传）⇒ **2 个共享文件**（`settings/mod.rs` + `pages/mod.rs`）， +//! `app/view.rs` 不用动 —— **推荐这个形状**。 +//! +//! 顺带订正 r3 之前那句「在 `app/state.rs` 用真值初始化 `Groups.language_appearance`（1 个文件）」： +//! **M106 起语言已经有真值源**——`App::lang: LangState`（`crates/app-iced/src/ui/lang.rs`，用户档位 +//! `LangChoice` + 探测结论 `Detection`），由 `App::refresh_view` 经 `view::model(…, lang)` 灌进 +//! `pages::Model.lang`，设置页再从 `settings::view` 的 `language` 形参拿到它。所以下一条线要给某一组 +//! 读「当前语言」时，**不需要**再造一层状态：要么走 `Model.lang`（给 `settings::view` 加形参， +//! 与 M106 同形状），要么读 `Groups` 里本线的字段。两种形状都是「谁先撞谁付一次钱」的一次性代价， +//! 不是永久性四路撞车。 +//! 5. **首帧取数 / 异步发起**（同上，r2 复审 P1 补）—— [`Body`] 是 +//! `fn(&Ui, States) -> Option`，返回不了 `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_about; +mod appearance; +pub(crate) mod download; +mod frame; +mod general; +pub(crate) mod java; +pub(crate) mod language_appearance; +mod message; +mod state; + +#[cfg(test)] +mod tests; + +pub use message::GroupMessage; +pub use state::{demo_groups, Groups, States}; + +use iced::widget::column; +use iced::{Element, Length}; + +use unlucky_design::color::Role; +use unlucky_design::icons::IconKind; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; +use unlucky_i18n::{Lang, LangChoice}; + +use crate::theme::Ui; + +use super::layout::{FrameMetrics, PageLayout}; +use super::Message; + +/// 设置页 General 分组要的两件（M106）：用户选的档位 + 这一次生效的语言。 +/// +/// 为什么不塞进 `pages::Model`：那是页面与 presenter 之间的**展示契约**（由快照派生），而档位是 +/// **用户意图**（`App` 的字段）；塞进去会让 `pages::demo_model` 也得伪造一个档位。 +/// 为什么不是单个 `Lang`：语言行要画**选中态**——「我明明选了跟随系统」得在界面上看得出来。 +/// 为什么不塞进 [`States`]：那条路要改 `settings/state.rs` 并补齐 4 处 struct literal +/// （`settings/mod.rs` 文档「仍然共享」第 4 条已算过账），而 `view` 多一个形参只动 2 个文件。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct Language { + /// 用户选的那一档（跟随系统 / 手选）。 + pub choice: LangChoice, + /// 这一次真正生效的语言（目录选的就是它）。 + pub effective: Lang, +} + +impl Default for Language { + /// harness / 演示路径的默认值：跟随系统 + 英文基线（与 M84 起的截图基线一致）。 + fn default() -> Self { + Self { + choice: LangChoice::System, + effective: Lang::En, + } + } +} + +/// 一个分组正文的**真控件渲染器**：入参是「画一帧时那份只读状态」（组状态 + 外观状态）， +/// 返回 `None` = 这一组现在没东西可画（例如外观分组在 harness 路径下没有外观状态）， +/// 由 [`form`] 退回演示行。 +/// +/// 各组自己的渲染器**定义在自己文件里**，签名是这一条：于是「这一组要读哪些状态」由它自己决定， +/// 本文件不需要认识任何一组的字段（r1 复审 P1 要的正是这一点）。 +type Body = for<'a> fn(&'a Ui, States<'a>) -> Option>; + +/// 一个设置分组：名字、图标、演示行、（可选）把这一组正文画成真控件的渲染器。 +/// +/// 除 `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; 4] = [ + general::GROUP, + appearance::GROUP, + java::GROUP, + download::GROUP, +]; + +/// 演示选中的分组（没有真实外观状态时——`pages_demo` harness——用它）。 +const SELECTED: usize = 0; + +/// General 分组在 [`GROUPS`] 里的下标（0）。它与 [`SELECTED`] 同值**是巧合，不是依赖**。 +/// +/// 为什么需要它：语言行要的是「当前档位 + 生效语言」（[`Language`]），而 `Group.body` 的签名只带 +/// [`States`]（外观 + 组状态）——给 `States` 加字段要动 `settings/state.rs` 与 4 处 struct literal +/// （见本文件文档「仍然共享」第 4 条），给 `Body` 加形参会令另外三组各自的 `body` 函数编译不过。 +/// 所以这里做一次**按下标的分发**：代价是一行 `if`，换来 `general::GROUP.body` 仍是 `None` +/// （`tests/mod.rs` 的「只有外观组带真控件 body」照样成立）。 +const GENERAL_GROUP: usize = 0; + +/// 左列分组的**显示名** key（下标与 [`GROUPS`] 一一对应，M106）。 +/// +/// 为什么不放进 [`Group`]：那会让另外三组的 `GROUP` 字面量（各自文件、各自填页线）编译不过—— +/// 与 [`GENERAL_GROUP`] 同一条理由。`Group.name` 因此退化为**id**（测试按它认组；显示走这张表）。 +pub(super) const GROUP_LABELS: [unlucky_i18n::Key; 4] = [ + unlucky_i18n::Key::SettingsGroupGeneral, + unlucky_i18n::Key::SettingsGroupAppearance, + unlucky_i18n::Key::SettingsGroupJava, + unlucky_i18n::Key::SettingsGroupDownloads, +]; + +/// 整页。 +/// +/// `states` 是「画一帧时那份只读状态」：[`States::appearance`] 是 M93 接进来的外观运行期状态 +/// （`None` = harness / 演示路径，设置页仍画占位行），[`States::groups`] 是各组自己的状态。 +pub fn view<'a>( + ui: &'a Ui, + metrics: FrameMetrics, + states: States<'a>, + language: Language, +) -> Element<'a, Message> { + // 选中分组：有真实外观状态时看状态（点左列可切），否则退回演示值 0。 + let selected = states + .appearance + .map_or(SELECTED, |state| state.selected_group); + + let body = match metrics.layout { + PageLayout::SupportingPane => frame::panes( + metrics, + frame::group_nav(ui, selected, language.effective), + frame::left_aligned(metrics.column, form(ui, Some(selected), states, language)), + ), + _ => frame::single_column(metrics, form(ui, None, states, language)), + }; + + frame::page(ui, metrics, frame::header(ui, language.effective), body) +} + +// --------------------------------------------------------------- 内容分发 + +/// 表单列（正文列宽 ≤424）。`only = Some(i)` 只渲染一组（supporting-pane）， +/// `None` 渲染全部（窄窗：分组导航退化成按组堆叠）。 +/// +/// **分发点**：一组的正文由它自己文件里的 `GROUP.body` 决定——`Some(f)` 让 `f` 自己去 +/// [`States`] 里取它要的数据（`None` 返回值 ⇒ 退回演示行），`None` 直接画演示行 +/// （[`frame::demo_card`]）。这里不出现任何一个分组名，也不比较下标，更不认识任何一组的字段。 +fn form<'a>( + ui: &'a Ui, + only: Option, + states: States<'a>, + language: Language, +) -> Element<'a, Message> { + let catalog = language.effective.catalog(); + let mut stack = column![].spacing(ui.space(Space::X6)).width(Length::Fill); + + for (index, group) in GROUPS.iter().enumerate() { + if only.is_some_and(|selected| selected != index) { + continue; + } + + // 「外观」分组：有真实外观状态时画真控件（M93），否则退回演示行（harness）。 + // 这两条的差别由 `GROUP.body` 的返回值表达，而不是「下标 == APPEARANCE_GROUP」的硬比较。 + // + // M106：General 是**唯一一处按下标分发**的例外（理由见 [`GENERAL_GROUP`]）——语言行的 + // 档位与生效语言不在 [`States`] 里，只能从 `pages::Language` 进来；它与 `appearance` 在不在场 + // 无关（harness 那条路径也画得出真控件）。 + let card = if index == GENERAL_GROUP { + general::body(ui, language) + } else { + group + .body + .and_then(|body| body(ui, states)) + .unwrap_or_else(|| frame::demo_card(ui, group.rows)) + }; + + stack = stack.push( + column![ + frame::text_role( + ui, + TypeRole::LabelMedium, + false, + // 卡片标题与左列同一个词源（`GROUP_LABELS`）：`Group.name` 只是 id。 + GROUP_LABELS + .get(index) + .map_or(group.name, |key| catalog.text(*key)), + ui.color(Role::OnSurfaceVariant), + ), + card, + ] + .spacing(ui.space(Space::X2)) + .width(Length::Fill), + ); + } + + stack = stack.push(frame::overrides_empty(ui, language.effective)); + + frame::scroll(ui, stack) +} diff --git a/crates/app-iced/src/pages/settings/state.rs b/crates/app-iced/src/pages/settings/state.rs new file mode 100644 index 0000000..44113a8 --- /dev/null +++ b/crates/app-iced/src/pages/settings/state.rs @@ -0,0 +1,85 @@ +//! 设置页的**状态漏斗**（M101 r2）：与 [`super::message`] 的消息漏斗同构——一个组的状态归它自己的 +//! 文件，[`Groups`] 只是一个按组排开的架子。 +//! +//! ## 为什么要这一层（r1 复审的 P1） +//! +//! 消息漏斗解决了「加一支消息要改哪些文件」，但一组要画**真值**就得有数据进渲染器：r1 之前 +//! `settings::view` 只收 `Option<&appearance::State>`，于是 java / download / language+appearance +//! 三条线要显示「当前运行时 / 当前并发数 / 当前语言」时，**都得改 `settings/mod.rs`**；带运行期状态 +//! 的还要改 `pages/mod.rs` / `app/view.rs` / `app/state.rs`。四条线一铺开就是第二处四路撞车。 +//! +//! 现在的形状： +//! +//! ```text +//! App.settings: pages::settings::Groups ← 唯一的所有者（app/state.rs 一行） +//! ├─ java: java::State → pages/settings/java.rs +//! ├─ download: download::State → pages/settings/download.rs +//! ├─ language_appearance: language_appearance::State → pages/settings/language_appearance.rs +//! └─ ai_about: ai_about::State → pages/settings/ai_about.rs +//! +//! settings::view(ui, metrics, States { appearance, groups }) ← 只读视图，按值传 +//! └─ 每组的 GROUP.body(ui, states) 自己从 states 里取自己要的那份 +//! ``` +//! +//! **加/改某一组的字段** = 只改 `pages/settings/<组>.rs`（状态类型在它自己文件里）+ 用它自己的 +//! handler 更新（`app/update/settings/<线>.rs`）。本文件、`pages/mod.rs`、`app/state.rs`、 +//! `app/view.rs` **都不用动**——本 mission 的这半边判据就是这么验的（见报告「变异证据」）。 +//! +//! **加一整条新线**（多一个组）才需要：本文件加一个字段、`message.rs` 加一个变体、 +//! `app/update/settings.rs` 加一条臂。那是「加一条线」，不是「加一个字段」。 +//! +//! ## 外观那条真控件路径（M93）没有被挤掉 +//! +//! `appearance::State` 仍是 `App` 的字段（不复用、不搬走），[`States::appearance`] 原样借用它； +//! 「没有外观状态（harness）⇒ 画演示行」这条判据现在由 `appearance` 组自己的 `GROUP.body` +//! 表达（返回 `None` ⇒ [`super::frame::demo_card`]），与 r1 之前逐像素等价。 + +use std::sync::LazyLock; + +use crate::pages::appearance; + +use super::{ai_about, download, java, language_appearance}; + +/// 各组自己拥有的运行期状态：**一个组一个字段**，字段类型定义在那条线自己的文件里。 +/// +/// 字段的**内部**结构归各组（加字段只改它自己的文件）；架子（有哪几个组）归这里。 +#[derive(Debug, Default)] +pub struct Groups { + /// Java 分组的状态（`pages/settings/java.rs`）。 + pub java: java::State, + /// Downloads 分组的状态（`pages/settings/download.rs`）。 + pub download: download::State, + /// 语言 + 外观两组的状态（`pages/settings/language_appearance.rs`）。 + pub language_appearance: language_appearance::State, + /// AI / About 分组的状态（`pages/settings/ai_about.rs`）。 + pub ai_about: ai_about::State, +} + +/// 画一帧时**按值**递给各组渲染器的只读视图：组状态 + 外观运行期状态（两个引用，`Copy`）。 +/// +/// 为什么按值而不是按引用：`Settings::view` 返回的 `Element<'a>` 会借走它，按引用传会逼着 +/// harness 那条路径（[`super::demo_groups`] 撑着的 `page()` / `page_with_appearance()`）为一份 +/// **临时构造**的 `States` 造 `'static`，或者把默认状态塞进 `Model`（两份真相）。按值传没有 +/// 这层借用纠缠，调用方写一行就够。 +#[derive(Debug, Clone, Copy)] +pub struct States<'a> { + /// 外观运行期状态（M93）：`None` = harness / 演示路径（设置页画演示行）。 + pub appearance: Option<&'a appearance::State>, + /// 各组自己的状态（见 [`Groups`]）。 + pub groups: &'a Groups, +} + +/// 演示 / harness 路径的默认组状态（`pages::page` 与 `pages::page_with_appearance` 用它）。 +/// +/// `'static` 是有意的：那两条入口不持有任何组状态，而返回的 `Element<'a>` 会借走这份 `Groups`； +/// 让它活得比调用方长，借用就不会把返回值钉在函数栈上。 +/// +/// **隐性代价（r2 复审 P3）**：`static` 要求 `Groups: Sync + Default`，于是某个组的 `State` 里一旦 +/// 放了 `Rc` 这类非 `Sync` 字段，编译会红在**本文件**（共享）而不是那一组自己的文件。真需要 +/// 非 `Sync` 状态时的改法：去掉这个 `static`，改成每个调用点自己造一份 `Groups`——`pages/mod.rs` 的 +/// **三个**调用点都要改（`page` / `page_with_appearance` / `app_with_appearance`，行 156 / 179 / 234）， +/// 一次性代价，见 [`super`] 文档「仍然共享」第 6 条。 +pub fn demo_groups() -> &'static Groups { + static DEMO: LazyLock = LazyLock::new(Groups::default); + &DEMO +} diff --git a/crates/app-iced/src/pages/settings/tests/appearance_section.rs b/crates/app-iced/src/pages/settings/tests/appearance_section.rs new file mode 100644 index 0000000..e318042 --- /dev/null +++ b/crates/app-iced/src/pages/settings/tests/appearance_section.rs @@ -0,0 +1,52 @@ +//! 「Appearance」分组自己的断言（M100 **新增**：`settings/tests.rs` 那 7 条全是跨 section 的， +//! 一条 section 断言都没有；这 3 条是新增，不是搬移）。 +//! +//! **归 language+appearance 线**：这是设置页唯一接了真控件的一组，真控件实现全在 +//! `pages/appearance/section.rs`；本文件只守「注册表这一侧的接线」。 +//! 本组已经把 `body` 接上了；`tests/mod.rs` 那条「只有一组有真控件」的**聚合绊线已在 M101 r2 删除** +//! （被四条 per-group 断言完全蕴含——代价是「唯一性」从此没人守，那段说明写在 `tests/mod.rs` 同处）。 + +use super::super::appearance; +use unlucky_design::icons::IconKind; + +/// 这一组的**演示行**（没有外观运行期状态时才画）。 +/// +/// 抓得住：四条线并行合并时把别人的行粘到本文件（四份 `GROUP` 长得几乎一样）； +/// 漏掉/多一条行；标签与值错位。 +/// 抓不住：真控件那一屏（那是 `pages/appearance` 的事，靠出图判）。 +#[test] +fn the_appearance_group_shows_density_corner_motion_and_text_scale() { + let rows: Vec<(&str, &str)> = appearance::GROUP.rows.to_vec(); + assert_eq!( + rows, + vec![ + ("Density", "Comfortable"), + ("Corner style", "Follow system"), + ("Motion", "Full"), + ("Text scale", "100%"), + ] + ); +} + +/// 左列图标（`IconKind::Sidebar`）。 +#[test] +fn the_appearance_group_keeps_its_icon() { + assert_eq!(appearance::GROUP.icon, IconKind::Sidebar); +} + +/// **本组的绊线**：外观分组必须一直是「挂了真控件」的那一组。 +/// +/// 抓得住：language+appearance 线把 `body` 换回 `None`（真控件消失、退回演示行，而截图对这种 +/// 「只在有外观状态时出现」的差别不一定抓得住）。 +/// 抓不住：`body` 到底指向哪个渲染器——**函数指针相等性断言不了**（rustc +/// `unpredictable_function_pointer_comparisons`：fn 地址不保证唯一，比出来的结果没有意义）， +/// 所以「指向 `pages::appearance::section`」这件事只能由 +/// `settings/appearance.rs` 那一行源码 + 两张图的 sha256 不同来担保。 +#[test] +fn the_appearance_group_keeps_a_real_control_body() { + assert!( + appearance::GROUP.body.is_some(), + "外观分组必须是挂了真控件的那一组（`settings/appearance.rs` 里是 `body: Some(body)`，\ + `body` 是本文件那个本地 fn；具体渲染器由那一行源码 + 截图担保，函数指针相等性断言不了）" + ); +} diff --git a/crates/app-iced/src/pages/settings/tests/download_section.rs b/crates/app-iced/src/pages/settings/tests/download_section.rs new file mode 100644 index 0000000..f3ca8bc --- /dev/null +++ b/crates/app-iced/src/pages/settings/tests/download_section.rs @@ -0,0 +1,49 @@ +//! 「Downloads」分组自己的断言（M100 **新增**：`settings/tests.rs` 那 7 条全是跨 section 的， +//! 一条 section 断言都没有；这 3 条是新增，不是搬移）。 +//! +//! **归 download 线**。接真控件那天要改**两个**文件（M101 r2 删掉了原先的第 3 处跨 section 绊线）： +//! `settings/download.rs` + 本文件 `the_downloads_group_is_still_demo_rows`。 +//! +//! 别把它和下载页（`pages/download*`）搞混：那是「装哪个版本」，这一组是「怎么下」的默认值。 + +use super::super::download; +use unlucky_design::icons::IconKind; + +/// 这一组的行集合（标签 + 值）。 +/// +/// 抓得住：① 四条线并行合并时把别人的行粘到本文件（四份 `GROUP` 长得几乎一样，最容易整块贴错）； +/// ② 漏掉/多出一条行；③ 标签与值错位（`("Concurrency", "8 threads")` 被写成 `"Off"`）。 +/// 抓不住：值对不对（`Automatic (region)` 是不是本机真选中的源）——那是接线后真数据源的事。 +#[test] +fn the_downloads_group_shows_source_concurrency_and_checksums() { + let rows: Vec<(&str, &str)> = download::GROUP.rows.to_vec(); + assert_eq!( + rows, + vec![ + ("Preferred source", "Automatic (region)"), + ("Concurrency", "8 threads"), + ("Verify checksums", "On"), + ] + ); +} + +/// 左列图标（`IconKind::Download`）。与导航轨的「下载」同族，换掉就与 rail 语汇不一致。 +#[test] +fn the_downloads_group_keeps_its_icon() { + assert_eq!(download::GROUP.icon, IconKind::Download); +} + +/// **绊线**：这一组还没接真控件，画的是演示行。 +/// +/// 抓得住：download 线接上了 `body` 却没更新这里的期望（那会让本文件静默变成假绿）。 +/// 抓不住：界面上真控件长什么样。 +/// +/// 接真控件时：把 `is_none()` 改成 `is_some()`，**只改这一行**（M101 r2 起不必再去 +/// `tests/mod.rs` 报到：那条跨 section 聚合绊线已删）。 +#[test] +fn the_downloads_group_is_still_demo_rows() { + assert!( + download::GROUP.body.is_none(), + "Downloads 还没接真控件：接了就改本断言" + ); +} diff --git a/crates/app-iced/src/pages/settings/tests/general_section.rs b/crates/app-iced/src/pages/settings/tests/general_section.rs new file mode 100644 index 0000000..8825de1 --- /dev/null +++ b/crates/app-iced/src/pages/settings/tests/general_section.rs @@ -0,0 +1,122 @@ +//! 「General」分组自己的断言（M106 `I18NFOLLOW` 重写：语言行换成真控件）。 +//! +//! **归 language+appearance 线**。接真控件那天要改**两个**文件（M101 r2 删掉了原先的第 3 处跨 +//! section 绊线）：`settings/general.rs` + 本文件 `the_general_group_is_still_demo_rows`。 +//! +//! M106（`I18NFOLLOW`）已经接了这一组的语言行。用户报的 bug 有两半：**界面全英文**（探测对了 +//! 但没人用）与**设置页写着 `English (System)`**（一行硬编码假值）。本文件的断言守后半：那行 +//! 假值不许回来，语言行的三档必须真的能在两套目录里取到词。 +//! +//! 接线形状：语言行的正文由 [`general::body`] 画（入口是 `pages::settings` 的 `GENERAL_GROUP` +//! 按下标分发），`GROUP.body` 仍是 `None`——那个槽位的签名是 `fn(&Ui, States) -> Option`， +//! `States` 只有 `appearance` + `groups` 两格，装不下「当前语言档位」。所以 M101 r2 的 +//! 「本组接真控件只需改两个文件」这条口径，在语言行上**仍然是两个文件**。 + +use super::super::general; +use unlucky_design::icons::IconKind; +use unlucky_i18n::LangChoice; +use unlucky_i18n::{Key, Lang}; + +/// 这一组的**静态演示行**：语言那一行已经换真控件，所以只剩三行。 +/// +/// 抓得住：①四条线并行合并时把别人的行粘到本文件；②语言行被「顺手」加回静态表—— +/// 那等于把用户看到的假值又写回去（它的值必须跟着语言变，静态表做不到）。 +/// 抓不住：真控件画出来长什么样（那是截图验收的事，见 `DevDocs/artifacts/m106/`）。 +#[test] +fn the_general_group_keeps_theme_startup_and_close_as_static_rows() { + let rows: Vec<(&str, &str)> = general::GROUP.rows.to_vec(); + assert_eq!( + rows, + vec![ + ("Theme", "Follow system"), + ("Startup page", "Instances"), + ("Close button", "Exit to tray"), + ] + ); +} + +/// 左列图标（`IconKind::Settings`）。分组图标是左列的语义标签，换掉就是换观感。 +#[test] +fn the_general_group_keeps_its_icon() { + assert_eq!(general::GROUP.icon, IconKind::Settings); +} + +/// **回归绊线（用户原话）**：`"English (System)"` 那条硬编码字面量不许回来。 +/// +/// 抓得住：①原来那条「这一组还没接真控件」在接上之后没更新（静默变假绿）； +/// ②语言行**退回静态演示行**（哪怕换个说法，只要还写着「English」就是同一个 bug 的复盘）。 +/// 抓不住：界面上真控件长什么样、三档选项名对不对（下一条与截图各管一段）。 +/// +/// 现状（M106）：`body` 仍是 `None`（语言行走 `GENERAL_GROUP` 的按下标分发），但这一组**已经** +/// 有真控件了——所以这里断言的**不再是「还没接」**，而是「不许回到静态行」。 +#[test] +fn the_language_row_is_not_a_static_string() { + for (label, value) in general::GROUP.rows { + assert_ne!( + *label, "Language", + "语言行必须走真控件（pages::Language），不许回到静态演示行" + ); + assert!( + !value.contains("English"), + "静态行里不许再出现写死的语言名：{value}" + ); + } +} + +/// 语言行**三档**，且在**两套目录**里都有词（中文界面不该出现 `⟪missing⟫`）。 +/// +/// 抓得住：①少一档（用户就没法切回去了）；②标签 key 只加进了中文表（英文界面上一档变成 +/// `⟪missing⟫`）；③回显那句的占位符名字与调用点对不上（会原样印出 `{language}`）。 +/// 抓不住：译文翻得对不对（金表 + `chinese_catalog_is_actually_chinese` 管那一层）。 +#[test] +fn the_language_row_offers_three_choices_in_both_languages() { + assert_eq!( + LangChoice::ALL.len(), + 3, + "跟随系统 / 简体中文 / 英文，少一档就切不回来" + ); + + for lang in Lang::ALL { + let catalog = lang.catalog(); + for choice in LangChoice::ALL { + assert!( + catalog.get(choice.label_key()).is_some(), + "{} 在 {} 目录里没词", + choice.label_key().name(), + lang.tag() + ); + } + + // 「界面当前使用：⟨语言名⟩」——中文系统下这句必须真的出现「简体中文」。 + let effective = catalog.text(LangChoice::Fixed(*lang).label_key()); + let line = catalog.render(Key::SettingsLanguageEffective, &[("language", effective)]); + assert!(line.contains(effective), "回显没带上语言名：{line}"); + assert!(!line.contains('{'), "占位符没被替换：{line}"); + } + + // 中文系统 + 跟随系统 ⇒ 回显是「简体中文」（用户报的 bug 的直接判据）。 + let zh = Lang::ZhCn.catalog(); + assert_eq!( + zh.render( + Key::SettingsLanguageEffective, + &[( + "language", + zh.text(LangChoice::Fixed(Lang::ZhCn).label_key()) + )] + ), + "界面当前使用：简体中文" + ); +} + +/// **绊线**：这一组仍不走 `Group.body`。 +/// +/// 为什么不是「接了真控件」：语言行的入口是 `pages::Language`（`GENERAL_GROUP` 那条分发）， +/// 而 `Group.body` 那个槽位的签名是 `fn(&Ui, &pages::appearance::State)`——装不下「当前语言档位」。 +/// 谁把语言行塞进 `body`，就得先给它换签名（那会改到另外三组的文件），这条断言逼他先想一遍。 +#[test] +fn the_general_group_does_not_use_the_appearance_body_slot() { + assert!( + general::GROUP.body.is_none(), + "General 的真控件走 pages::Language 入口（见 settings/mod.rs 的 GENERAL_GROUP），不是 body" + ); +} diff --git a/crates/app-iced/src/pages/settings/tests/java_section.rs b/crates/app-iced/src/pages/settings/tests/java_section.rs new file mode 100644 index 0000000..0dbcef4 --- /dev/null +++ b/crates/app-iced/src/pages/settings/tests/java_section.rs @@ -0,0 +1,57 @@ +//! 「Java」分组自己的断言（M100 **新增**：`settings/tests.rs` 里一条 section 断言都没有， +//! 那 7 条全是跨 section 的；所以这 3 条是新增，不是搬移）。 +//! +//! **归 java 线**。接真控件那天要改**两个**文件（M101 r2 删掉了原先的第 3 处跨 section 绊线， +//! 见 `tests/mod.rs` 的 `every_line_can_be_wired_alone` 说明）： +//! 1. `settings/java.rs`（`body = Some(java::body)` + 渲染器）； +//! 2. 本文件 `the_java_group_is_still_demo_rows`（把 `is_none()` 改成 `is_some()`）。 +//! +//! download / general 同型。 +//! +//! 判据（M100 交付里正面回答的那条）：给 java 加一条**新断言** = **只改本文件**。 + +use super::super::java; +use unlucky_design::icons::IconKind; + +/// 这一组的行集合（标签 + 值）。改文案就是改观感，所以逐条钉住，而不是「非空就行」。 +/// +/// 抓得住：① 四条线并行合并时把别人的行粘到本文件（四份 `GROUP` 长得几乎一样，最容易整块贴错）； +/// ② 漏掉/多出一条行；③ 标签与值错位（`("Default memory", "4 GiB")` 被写成 `"8 threads"`）。 +/// 抓不住：值对不对（`Temurin 21.0.4` 是不是本机真检测到的运行时）——那是接线后真数据源的事。 +#[test] +fn the_java_group_shows_runtime_memory_and_jvm_arguments() { + let rows: Vec<(&str, &str)> = java::GROUP.rows.to_vec(); + assert_eq!( + rows, + vec![ + ("Runtime", "Temurin 21.0.4"), + ("Default memory", "4 GiB"), + ("JVM arguments", "Automatic"), + ] + ); +} + +/// 左列图标必须是 `IconKind::Folder`。 +/// +/// 抓得住：谁把它换回 `IconKind::Play`——那是视觉复审 P2-3 判过的（`Play` 是填充字形， +/// 和同屏其它描边图标语汇打架；Java 组讲的是运行时安装位置，目录图标语义才对得上）。 +/// 抓不住：图标画出来的大小/线宽（那是 tokens 层的事）。 +#[test] +fn the_java_group_keeps_the_folder_icon_from_the_visual_review() { + assert_eq!(java::GROUP.icon, IconKind::Folder); +} + +/// **绊线**：这一组还没接真控件，画的是演示行。 +/// +/// 抓得住：java 线接上了 `body` 却没更新这里的期望（那会让本文件静默变成假绿）。 +/// 抓不住：界面上真控件长什么样。 +/// +/// 接真控件时：把 `is_none()` 改成 `is_some()`，**只改这一行**（M101 r2 起不必再去 +/// `tests/mod.rs` 报到：那条跨 section 聚合绊线已删，见那里的 `every_line_can_be_wired_alone`）。 +#[test] +fn the_java_group_is_still_demo_rows() { + assert!( + java::GROUP.body.is_none(), + "Java 还没接真控件：接了就改本断言" + ); +} diff --git a/crates/app-iced/src/pages/settings/tests/mod.rs b/crates/app-iced/src/pages/settings/tests/mod.rs new file mode 100644 index 0000000..3159dfc --- /dev/null +++ b/crates/app-iced/src/pages/settings/tests/mod.rs @@ -0,0 +1,198 @@ +//! 设置页的**跨 section** 守门测试（M100：跨 section 的留在这里，section 自己的断言**新增**在 +//! `tests/
_section.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; + +use super::super::layout::{self, frame_metrics, measure_cap_px, PaneKit, SIDE_NAV_WIDTH}; +use super::*; +use crate::pages::appearance::{APPEARANCE_GROUP, GROUP_LABEL}; + +// --------------------------------------------------------------- 版面（不属于任何一组） + +/// 守的是**版面契约**：分组导航走 drawer 240（D33），不是 rail 的 88。 +/// +/// 不能下放到分组：它不是「某一组」的属性，而是整个 supporting-pane 的几何。 +#[test] +fn side_nav_reuses_the_drawer_width() { + assert_eq!(SIDE_NAV_WIDTH, 240.0); + let metrics = frame_metrics(PaneKit::Supporting, 1180.0); + assert_eq!(metrics.secondary, Some(240.0)); + assert_ne!(metrics.secondary, Some(layout::rail_width())); +} + +/// 守的是**行宽上限**（逐行 67 字符 ≤72）在所有宽度档下都成立。 +/// +/// 不能下放：它是四个分组共用的正文列，任何一组把列撑宽都会连带别人。 +#[test] +fn form_column_never_exceeds_the_measure_cap() { + for width in [720.0, 840.0, 1180.0, 1920.0] { + let metrics = frame_metrics(PaneKit::Supporting, width); + assert!( + metrics.column <= measure_cap_px() + f32::EPSILON, + "{width} 宽下表单列 {:?} 超过行宽上限", + metrics.column + ); + assert!(metrics.column >= layout::measure_floor_px()); + } +} + +/// 守的是**窄窗退化**：<720 时侧列消失、分组改为按组堆叠。 +/// +/// 不能下放：退化是整页行为，四组一起变（单组文件里没法验证「侧列没了」）。 +#[test] +fn narrow_window_stacks_the_groups_instead_of_the_side_nav() { + let narrow = frame_metrics(PaneKit::Supporting, 700.0); + assert_eq!(narrow.layout, PageLayout::SingleColumn); + assert!(narrow.secondary.is_none(), "窄窗不许留侧列"); +} + +// --------------------------------------------------------------- 注册表（四组一起看） + +/// 守的是**注册表的结构不变量**：每组都有名字、图标、演示行，且演示下标在范围内。 +/// +/// 下放不了：它遍历的是 `GROUPS`（四组拼出来的数组），单组文件拿不到其它三组， +/// 而「新增一组忘了填 rows」正是这条要抓的。 +#[test] +fn every_group_has_a_name_icon_and_rows() { + assert!(GROUPS.len() >= 3); + assert!(SELECTED < GROUPS.len()); + for group in &GROUPS { + assert!(!group.name.is_empty()); + assert!(!group.icon.icon().path.is_empty(), "{} 缺图标", group.name); + assert!(!group.rows.is_empty(), "{} 没有设置行", group.name); + for (label, value) in group.rows { + assert!(!label.is_empty() && !value.is_empty()); + } + } +} + +/// M93：设置页「外观」分组的下标与 `pages::appearance` 声明的常量必须一致。 +/// +/// 抓得住：谁把 `GROUPS` 的顺序调了却忘了改 `APPEARANCE_GROUP`（那样真控件会画到别的分组上， +/// 而支持列显示的分组名也对不上）。 +/// 抓不住：控件本身画得对不对（那由截图与 app 侧测试管）。 +/// +/// 下放不了：它同时读 `GROUPS`（注册表）与 `pages::appearance` 的常量，横跨两处； +/// 放进 `appearance_section.rs` 会让「外观那条线」替注册表顺序作证。 +#[test] +fn the_appearance_group_is_where_the_module_says_it_is() { + assert_eq!(GROUPS[APPEARANCE_GROUP].name, GROUP_LABEL); + assert!(SELECTED < GROUPS.len(), "演示下标仍在范围内"); +} + +/// M99：拆分后**左列顺序**必须还是拆分前那四项（顺序变了就是观感变了，不是「纯搬移」）。 +/// +/// 抓得住：① 注册表顺序被调换（`GROUPS` 是四条线各自文件拼出来的，最容易在合并时错位）； +/// ② 某组被误删/误加（长度不等）。 +/// 抓不住：组内那些行还在不在、译文对不对（各组自己的文件与 `catalog` 金表各管一段）。 +/// +/// 下放不了：它是一句「四组顺序 = 这四个名字」的断言，任何单组文件都只能看到自己那一个名字。 +#[test] +fn the_split_kept_the_left_column_order() { + let names: Vec<&str> = GROUPS.iter().map(|group| group.name).collect(); + assert_eq!(names, vec!["General", "Appearance", "Java", "Downloads"]); +} + +/// M101 r2：`settings/mod.rs` 里**不许出现任何一组的 `State` 类型**（r1 复审 P1 的判据钉在这里）。 +/// +/// 抓得住：谁把状态漏斗拆回去——让 `view` / `form` 直接收 `appearance::State` 或某一组的 `State` +/// （那正是四条线「加一个字段就要改本文件」的形状，本次复审要求修掉的就是它）。 +/// 抓不住：各组的**字段**（那些活在各组自己的文件里，本文件本来就不该知道，也就没有可断言的东西）。 +/// +/// **M106 的例外要读清楚**：General 已经接了真控件（语言行），但它**不走 `Group.body`**—— +/// 那个槽位的签名是 `fn(&Ui, States) -> Option`，`States` 只有 `appearance` + `groups` +/// 两格，装不下「当前语言档位 + 生效语言」。它走 `settings::view` 的 `language` 形参 + +/// `GENERAL_GROUP` 那条按下标分发，`body` 仍是 `None`，所以本断言不动。 +/// 判据没变：**`body: Some(..)` 仍然只有外观组**。 +#[test] +fn the_settings_module_does_not_name_any_group_state() { + let source = include_str!("../mod.rs"); + let forbidden = [ + "appearance::State", + "java::State", + "download::State", + "language_appearance::State", + "ai_about::State", + ]; + + let hits: Vec<&str> = forbidden + .into_iter() + .filter(|needle| source.contains(needle)) + .collect(); + + assert!( + hits.is_empty(), + "`settings/mod.rs` 里出现了具体的组状态类型 {hits:?}：状态漏斗被打回去了——\ + 四条填页线又要改本文件。状态应该只在 `settings/state.rs` 的 `Groups` 与各组自己的\ + `State` 定义里出现，本文件只转发 `States`" + ); +} + +/// +/// 为什么能删：`tests/appearance_section.rs` 断言外观组 `body.is_some()`， +/// `tests/{general,java,download}_section.rs` 各自断言本组 `body.is_none()`——四条合起来与 +/// 原来那条聚合断言等价（成员与顺序另有 [`the_split_kept_the_left_column_order`] 钉住）。 +/// 删掉之后每条线「接真控件」只需改自己那 2 个文件，不必来本文件报到。 +/// +/// ## 删掉之后**抓不住什么**（tower 要求写明） +/// +/// 那四条都只看**本组**，没有任何一条再断言「唯一性」——「四组里恰好一组挂了真控件」这件事 +/// **现在没有守卫**。具体漏法： +/// +/// | 情形 | 还红吗 | +/// |---|---| +/// | 某条线接上 `body` 却忘了翻自己那条 `is_none()` | **红**（本组断言还在） | +/// | 两条线的断言被同时改成 `is_some()`，页面上两组同时长真控件 | **绿着过去**（没人指认「唯一」） | +/// | 谁把 `body: Some(..)` 挂到一个不该有的组、又顺手改了它那条断言 | **绿着过去** | +/// +/// 接受这个损失的理由：接真控件是**每组各自的一次性动作**，谁做谁翻自己那一条；而「唯一」在 +/// 四条线并行的阶段是最容易假红的约束（一条线接上就替另外三条红）。想要回这条守卫，等四条线 +/// 都落地后在这里加一条**计数**断言（`GROUPS.iter().filter(|g| g.body.is_some()).count()`）， +/// 而不是现在钉死某个下标。 +/// +/// 这条 `#[test]` 本体已删；保留这段文档是为了让后来的人知道「这里原本有一条绊线」。 +#[test] +fn every_line_can_be_wired_alone() { + // 判据是「每条线只改自己的文件」，不是任何一条具体断言：这里只钉住架子本身的两件事—— + // ① 每组都有 `GROUP`（成员齐）；② 演示下标合法。真正的 per-group 断言在各自文件里。 + assert_eq!(GROUPS.len(), 4, "四条线各一个分组"); + assert!(SELECTED < GROUPS.len(), "演示下标仍在范围内"); +} diff --git a/crates/app-iced/src/pages/tests.rs b/crates/app-iced/src/pages/tests.rs new file mode 100644 index 0000000..469b772 --- /dev/null +++ b/crates/app-iced/src/pages/tests.rs @@ -0,0 +1,385 @@ +//! 页面层的**数值判据**：M90 接真组件后，「M84 的版面约束一条没破」这件事在这里钉死。 +//! +//! 每条断言都注明了「抓得住什么 / 抓不住什么」——只测到纯函数，渲染真像素另见报告里的图与量测。 + +use super::layout::{self, frame_metrics, measure_cap_px, PaneKit, WidthClass}; +use super::nav::NAV; +use super::*; +use unlucky_design::color::SchemeFlavor; +use unlucky_design::typography::Platform; +use unlucky_i18n::Lang; +use unlucky_presenter::router::{NavSection, Route}; + +use crate::theme::Families; + +const FAMILIES: Families = Families { + text: "Segoe UI", + display: "Segoe UI", + mono: "Consolas", +}; + +fn ui() -> Ui { + Ui::with_platform(SchemeFlavor::Light, Platform::Windows, FAMILIES) +} + +#[test] +fn five_screens_answer_the_mission_list() { + // M109：内容库是第五页（`download` 与 `content` 共用导航轨的「下载」项） + assert_eq!(Screen::ALL.len(), 5); + let slugs: Vec<&str> = Screen::ALL.iter().map(|screen| screen.slug()).collect(); + assert_eq!( + slugs, + vec!["instances", "download", "content", "settings", "logs"] + ); + for screen in Screen::ALL { + assert_eq!(Screen::from_slug(screen.slug()), Some(screen)); + } + assert_eq!(Screen::from_slug("gallery"), None); +} + +#[test] +fn screens_declare_the_layout_their_page_needs() { + assert_eq!(Screen::Instances.kit(), PaneKit::ListDetail); + assert_eq!(Screen::Settings.kit(), PaneKit::Supporting); + assert_eq!(Screen::Download.kit(), PaneKit::Single); + // 内容库自带页内三栏，版面基座仍是单列（见 `pages/content/layout.rs`） + assert_eq!(Screen::Content.kit(), PaneKit::Single); + assert_eq!(Screen::Logs.kit(), PaneKit::Single); +} + +/// 四个页面 × 三个对照宽度都能构图（不 panic、不依赖运行时）。 +/// +/// **抓得住**：`view` 的每条分支都能产出一棵树（含真空列表、无选中详情）。 +/// **抓不住**：像素级观感（那要出图，见报告）。 +#[test] +fn every_screen_builds_at_the_three_comparison_widths() { + let ui = ui(); + for width in [1180.0, 900.0, 700.0] { + for screen in Screen::ALL { + let model = demo_model(screen, width); + let _element: Element<'_, Message> = app(&ui, &model); + } + } +} + +/// 空数据也要能构图（真实后端的「还没扫到实例」是常态，不能 panic）。 +#[test] +fn an_empty_snapshot_still_builds() { + let ui = ui(); + for screen in Screen::ALL { + let model = Model::new(screen, 1180.0, Some(screen.nav())); + let _element: Element<'_, Message> = app(&ui, &model); + } +} + +/// 版面对照：同一页在 1180 / 900 / 700 三个宽度上必须**真的换版面**。 +#[test] +fn the_width_comparison_really_changes_the_layout() { + let wide = frame_metrics(PaneKit::ListDetail, 1180.0); + let mid = frame_metrics(PaneKit::ListDetail, 900.0); + let narrow = frame_metrics(PaneKit::ListDetail, 700.0); + + assert_eq!(wide.layout, PageLayout::ListDetail); + assert_eq!(mid.layout, PageLayout::ListDetail); + assert_eq!(narrow.layout, PageLayout::SingleColumn); + + // 900 与 1180 同为 list-detail，但详情列必须真的变窄（不是硬编码 1180 的宽度） + assert!(mid.column < wide.column, "900 的详情列应窄于 1180"); + assert!(narrow.secondary.is_none(), "700 不许再有列表列"); +} + +/// **M102 的对齐判据**：正文块左缘 = 页头标题左缘（`body_offset == 0`），块宽 = pane 宽（封顶 1440）。 +/// +/// 页头标题的左缘 = `rail + gutter`（`frame::header_bar` 的 padding 与 `frame::page` 的内容 +/// padding 是同一个 `metrics.gutter`）；正文块宽 = `frame::body_width`。 +/// +/// **抓得住**：块宽被改回 424（视觉复审 ①：左缘 422 对标题 112）、偏移不再是 0（居中/右对齐）、 +/// 上限被挪动； +/// **抓不住**：`frame::body` 到底有没有照这两个数建盒子（那由 +/// [`frame_body_is_built_from_the_block_quantities`] 扫源码守）。 +#[test] +fn body_block_starts_at_the_header_title_and_fills_the_page() { + for width in [600.0, 840.0, 900.0, 1180.0] { + let metrics = frame_metrics(PaneKit::Single, width); + let title_x = layout::rail_width() + metrics.gutter; + let block = frame::body_width(metrics); + + assert_eq!( + block, metrics.available, + "{width}: 单列页块宽必须是可用宽度" + ); + assert_eq!( + layout::block::body_offset(metrics), + 0.0, + "{width}: 块必须贴左" + ); + assert!( + (title_x + block + metrics.gutter - width).abs() < f32::EPSILON, + "{width}: 块从 {title_x} 起、宽 {block}，没铺到右页边距" + ); + // 块变宽不等于一句话变宽：散文列仍 ≤424 + assert!(metrics.column <= measure_cap_px() + f32::EPSILON); + } + + // 验收尺寸 1180：标题左缘 112、块宽 1044（旧版居中时正文左缘是 422） + let wide = frame_metrics(PaneKit::Single, 1180.0); + assert_eq!(layout::rail_width() + wide.gutter, 112.0, "页头标题左缘"); + assert_eq!(frame::body_width(wide), 1044.0, "正文块宽度"); + + // 极宽窗：块宽封顶 1440（tower 拍板），仍然贴左 ⇒ 右侧留白而不是居中 + let huge = frame_metrics(PaneKit::Single, 2560.0); + assert_eq!(frame::body_width(huge), layout::block::BODY_MAX_WIDTH); + assert_eq!(frame::body_width(huge), 1440.0); + assert_eq!(layout::block::body_offset(huge), 0.0); + assert!(112.0 + frame::body_width(huge) < 2560.0); + + // 两列版面的块宽 = 主列 pane（实例页正文在 panes 的主列里，不铺整页） + let two = frame_metrics(PaneKit::ListDetail, 1180.0); + assert_eq!(frame::body_width(two), two.main_pane); + assert_eq!(two.main_pane, 1180.0 - 88.0 - 48.0 - 336.0 - 24.0); +} + +/// **源码结构**：`frame::body` 的盒子必须从「块宽 + 块偏移 + 贴左」这三个数建。 +/// +/// 为什么读源码：iced 的 `Element` 没有几何内省接口，`frame::body` 换成 +/// `centered(metrics.column, content)`（**就是视觉复审 ① 的改前写法**）不会红任何数值断言 —— +/// M102 r1 的变异实测就是这样漏掉的（`pages/tests.rs` 那条只喂 `frame_metrics()` 与 +/// `body_width()`）。所以这条盯的是**摆法**：宽度来自 `body_width(metrics)`、左内边距来自 +/// `body_offset(metrics)`、`align_x` 只许是 `Start`（不写 = container 默认 Start，等价）， +/// 且不出现居中/散文列宽。 +/// +/// 扫的是 [`layout::source::region_across`]：`frame.rs` **加上** `layout/block.rs`， +/// 于是「拆成 `body` → `body_impl`」（变异 H1）与「把盒子原样搬进 `block::body_box`」（变异 M6） +/// 这两种**等价重构都不假红**，而「换成居中 424 盒子」照样红（变异 A）。 +/// +/// **抓得住**：盒子的**语义**变了（居中 / 用散文列宽 / 用 `centered`）； +/// **抓不住**：`frame::centered(metrics.column, …)` 这种**与 `frame::body` 逐像素等价**的另写 +/// （r4 复审的 M1/M2 —— 按塔的裁定那是等价重构，护栏不该为此红），也不抓「先赋局部变量再建盒」。 +#[test] +fn frame_body_is_built_from_the_block_quantities() { + let body = layout::source::region_across( + &[include_str!("frame.rs"), include_str!("layout/block.rs")], + "pub fn body<'a>(", + ); + + for needle in ["body_width(metrics)", "body_offset(metrics)"] { + assert!( + body.contains(needle), + "`frame::body` 必须从 {needle} 建盒（贴左 + 块宽 + 零偏移）：\n{body}" + ); + } + + // `align_x` 出现就必须是 Start：`.align_y(Alignment::Start)` 单独存在不算数（r2 复审 P2-3）， + // 而「干脆不写 align_x」（container 默认 Start）视为等价重构，放行。 + // 判的是**实参**而不是整段文本，所以 `Alignment::Start` 与 `iced::Alignment::Start` 同等放行 + // （把盒子搬进别的模块后路径要写全，那是等价重构，不该假红 —— r4 复审的变异 M6）。 + for argument in layout::source::call_arguments(&body, ".align_x(") { + assert!( + argument.trim().ends_with("Alignment::Start"), + "`frame::body` 的 align_x 只许是 Start，收到 {argument:?}：\n{body}" + ); + } + + for forbidden in [ + "centered(", + "single_column(", + "metrics.column", + "Alignment::Center", + ] { + assert!( + !body.contains(forbidden), + "`frame::body` 里出现了 {forbidden:?} —— 那是居中 / 散文列宽的老写法：\n{body}" + ); + } +} + +/// **源码结构**：`frame::prose` 的宽度必须来自 `prose_width`（= `metrics.column`），不来自块宽。 +/// +/// M102 把两个量拆开后，「把散文塞进 1044 的块」不会红任何数值断言；这条盯接线。 +/// 与 `frame::body` 那条一样用 [`layout::source::region_across`]（`frame.rs` + `layout/block.rs`）， +/// 所以把盒子搬进 `layout/block.rs` 的等价重构不假红；抓的是**语义**（用块宽/可用宽度就红）。 +#[test] +fn frame_prose_is_built_from_the_prose_width() { + let prose = layout::source::region_across( + &[include_str!("frame.rs"), include_str!("layout/block.rs")], + "pub fn prose<'a>(", + ); + + assert!( + prose.contains("prose_width(metrics)"), + "`frame::prose` 必须从 prose_width 取宽：\n{prose}" + ); + for forbidden in ["body_width(", "metrics.available", "metrics.main_pane"] { + assert!( + !prose.contains(forbidden), + "`frame::prose` 里出现了 {forbidden:?} —— 散文会失去 72 字符行宽承诺：\n{prose}" + ); + } +} + +/// **源码结构（调用点）**：单列页必须调 `frame::body`，不许退回 `frame::single_column`。 +/// +/// r2 复审的变异 G：把四个页面文件里的 7 个调用点（`download.rs` 2 / `logs.rs` 3 / +/// `instances.rs` 1 / `instances/detail.rs` 1）一键改回 `frame::single_column` ⇒ 420 条全绿， +/// 而视觉复审 ① 原样回来。r2 的护栏只盯 `frame::body` **内部**，`single_column` 又是为设置页 +/// 合法保留的，所以「哪个页面用它」必须单独守。 +/// +/// 逐文件断言（而不是只数一条调用）：**同一个文件里退一个调用点**也会让 +/// `frame::single_column(` 出现，立刻红。 +/// +/// **抓得住**：页面退回居中的老写法（视觉复审 ① 原样）； +/// **抓不住**：新增的页面文件（它不在这个清单里——新页要自己登记）。 +#[test] +fn single_column_pages_call_the_body_box_not_the_centred_one() { + for (name, source) in [ + ("download.rs", include_str!("download.rs")), + ("logs.rs", include_str!("logs.rs")), + ("instances.rs", include_str!("instances.rs")), + ("instances/detail.rs", include_str!("instances/detail.rs")), + ] { + assert!( + source.contains("frame::body("), + "{name} 没有调用 frame::body —— 正文块不再从块宽/块偏移建盒" + ); + assert!( + !source.contains("frame::single_column("), + "{name} 退回了 frame::single_column（= 424 居中，视觉复审 ① 的原样）" + ); + } + + // 实例页窄窗那一屏的唯一入口也得走 body + let narrow = + layout::source::function_body(include_str!("instances/detail.rs"), "fn narrow_detail"); + assert!( + narrow.contains("frame::body("), + "narrow_detail 没走 frame::body：\n{narrow}" + ); +} + +/// **M84 的行宽红线**：任何页、任何窗口宽度、任何版面，正文列都不许超过 424px。 +/// +/// **抓得住**：`frame_metrics` 的 `column`（页面唯一的列宽来源）不会越界； +/// **抓不住**：页面自己绕过 metrics 写死宽度（那条由 `tests/no_hardcoded_tokens.rs` 的 +/// 「`.width(` 后面不许跟数字字面量」守门——它扫的是 `src/shell` + `src/pages` + `src/app` +/// （M90 r2/P3-3 把 `app` 加进去了）。 +#[test] +fn every_page_any_width_stays_under_the_measure_cap() { + let cap = measure_cap_px(); + assert!((cap - 424.0).abs() < f32::EPSILON, "行宽上限必须是 424"); + + for screen in Screen::ALL { + for width in [416.0, 600.0, 700.0, 840.0, 900.0, 1180.0, 1600.0, 2560.0] { + let metrics = frame_metrics(screen.kit(), width); + assert!( + metrics.column <= cap + f32::EPSILON, + "{} @{width} 的正文列 {} 超过 424", + screen.slug(), + metrics.column + ); + } + } +} + +/// 断点 600 / 840 与 rail 88：M84 的三条硬值，接真组件后不许漂。 +/// +/// **抓得住**：布局系统的常量与 `WidthClass::of` 的分档； +/// **抓不住**：导航轨真画出来是不是 88（那条要量像素；组件自己声明 88 见下一个断言）。 +#[test] +fn the_three_frozen_numbers_are_unchanged() { + assert!((layout::BREAKPOINT_MEDIUM - 600.0).abs() < f32::EPSILON); + assert!((layout::BREAKPOINT_EXPANDED - 840.0).abs() < f32::EPSILON); + assert!((layout::rail_width() - 88.0).abs() < f32::EPSILON); + + assert_eq!(WidthClass::of(599.9), WidthClass::Compact); + assert_eq!(WidthClass::of(600.0), WidthClass::Medium); + assert_eq!(WidthClass::of(839.9), WidthClass::Medium); + assert_eq!(WidthClass::of(840.0), WidthClass::Expanded); +} + +/// **组件版**导航轨（M78 的 `NavigationRail`）声明的宽度必须与布局系统同值。 +/// +/// 注意这不是产品路径的实现（M90 r3 订正）：产品页的 rail 由 `shell/nav.rs` 画，组件版只服务 +/// `pages::app`（harness 出口图）与单测。这条守的是「组件与布局系统没分叉」，**不是**「产品 rail +/// 没问题」——两套实现的漂移风险见 `pages/mod.rs` 偏离表 #10。 +/// +/// **抓得住**：`NavPaneGeometry::rail().width` == `layout::rail_width()` == 88； +/// **抓不住**：容器圆角/药丸摆放的像素级正确性（组件自己的 probe 管），也抓不住 `shell/nav.rs`。 +#[test] +fn the_real_rail_agrees_with_the_layout_system() { + let ui = ui(); + let geometry = crate::app::components::navigation::geometry::NavPaneGeometry::of( + &ui, + crate::app::components::navigation::NavLayout::Rail, + ); + assert!( + (geometry.width - layout::rail_width()).abs() < f32::EPSILON, + "真组件 rail 宽 {} 与布局系统的 {} 分叉了", + geometry.width, + layout::rail_width() + ); +} + +/// 路由 → 页面：四个一级页各自落到自己那页，`Detail` 落在实例页，`Agent` 没有页面（app 层回退）。 +#[test] +fn routes_map_onto_pages() { + assert_eq!(Screen::of(&Route::Instances), Some(Screen::Instances)); + assert_eq!( + Screen::of(&Route::Detail("survival".to_string())), + Some(Screen::Instances), + "详情页仍是实例页的那一屏" + ); + assert_eq!(Screen::of(&Route::Download), Some(Screen::Download)); + assert_eq!(Screen::of(&Route::Logs), Some(Screen::Logs)); + assert_eq!(Screen::of(&Route::Settings), Some(Screen::Settings)); + assert_eq!(Screen::of(&Route::Agent), None, "AI 独立页还没有页面实现"); +} + +/// 导航轨的每一项都指向一个**它能高亮的**路由（点完不会出现「没有任何项高亮」的悬空态）。 +/// +/// **抓得住**：`NAV` 表的 5 项与 `Screen::nav` / `Route::nav` 三者没有错位； +/// **抓不住**：点下去真的换页（那是 `app/update.rs` 的 `Navigate` 分支 + 集成图）。 +#[test] +fn every_rail_item_points_at_a_route_that_highlights_it() { + assert_eq!(NAV.len(), 5, "导航轨 5 项（4 个一级页 + AI）"); + let catalog = Lang::En.catalog(); + + for (section, _icon, label, route) in NAV { + assert!(!catalog.text(label).is_empty(), "{} 没有文案", label.name()); + assert_eq!( + route.nav(), + section, + "{} 指向的 {route:?} 高亮的是 {:?}", + label.name(), + route.nav() + ); + } + assert_eq!( + NAV[4].0, None, + "AI 项没有导航高亮（Route::Agent.nav() 是 None）" + ); + + // 四个一级页的 page-nav 与 route-nav 同源 + assert_eq!(Screen::Instances.nav(), NavSection::Instances); + assert_eq!(Screen::Settings.nav(), NavSection::Settings); +} + +/// 演示模型：12 行 + 1 条选中详情（M84 的出图基线就靠这份数据）。 +#[test] +fn the_demo_model_carries_the_m84_baseline() { + let model = demo_model(Screen::Instances, 1180.0); + assert_eq!(model.instances.rows.len(), 12); + let detail = model.instances.detail.as_ref().expect("演示数据有选中项"); + assert_eq!(detail.meta.len(), 6, "元信息 6 格"); + assert!(detail.note.is_some(), "演示数据带正文段"); + assert_eq!(model.active, Some(NavSection::Instances)); + + // 其余三页不带实例数据（占位视觉不读它） + for screen in [Screen::Download, Screen::Settings, Screen::Logs] { + let model = demo_model(screen, 1180.0); + assert!( + model.instances.rows.is_empty(), + "{} 不该带实例数据", + screen.slug() + ); + } +} diff --git a/crates/app-iced/src/platform/locale.rs b/crates/app-iced/src/platform/locale.rs new file mode 100644 index 0000000..bd28142 --- /dev/null +++ b/crates/app-iced/src/platform/locale.rs @@ -0,0 +1,301 @@ +//! 系统语言的**真值源**（D28）：Windows 走 `reg.exe` 读注册表——**零 `unsafe`、零 FFI、零新依赖**。 +//! +//! ## 为什么是子进程而不是 FFI +//! +//! 先例是 M73 的壁纸探测（`crates/core/src/platform/wallpaper/windows.rs`）：同样是「Windows 上 +//! 只有注册表知道答案」的问题，它用 `reg.exe query` 解决，`unsafe` 一个没加。本 crate 的 `unsafe` +//! 只允许出现在 [`crate::platform::win32`]（D36 的纪律），所以这里照抄那条路。 +//! +//! 为什么不 `GetUserDefaultLocaleName`：它要 FFI，而它对**本用途**并不比注册表准——Windows 的 +//! 「区域格式」与「显示语言」本来就是两个设置，两者都有各自的说法（见下面的诚实边界）。 +//! +//! ## 读什么、按什么顺序 +//! +//! 1. `HKCU\Control Panel\International` 的 `LocaleName`——Win7+ 都有，值就是 `zh-CN` 这种标签， +//! [`unlucky_i18n::Lang::from_locale`] 直接吃得下； +//! 2. 读不到 `LocaleName` 时退到同一个键的 `Locale`（8 位十六进制 LCID，如 `00000804`）， +//! 用一张**很短的**表翻成标签；表里没有的返回 `None`（宁可英文，也不猜错语种）。 +//! +//! 优先级链在 [`unlucky_i18n::lang::resolve`]：**`ui.language` 显式值 > 本模块 > 环境变量 > 英文**。 +//! +//! ## 诚实边界（抓得住什么 / 抓不住什么） +//! +//! - **抓得住**：`reg query` 输出的解析（含 CRLF、空值、值名大小写）、`LocaleName` 缺失时退 LCID +//! 的分支、命令失败/缺失时的 `None`； +//! - **抓不住**：①`LocaleName` 是**区域格式**，用户完全可能在设置里把「显示语言」改成英文而区域 +//! 仍是 `zh-CN`（或反过来）——真要读显示语言得 `GetUserDefaultUILanguage`（FFI）或多语言 +//! 用户界面注册表（`...\Control Panel\Desktop` 的 `PreferredUILanguages`，本 mission 未做）； +//! ②策略禁用 `reg.exe` / Wine 环境 → `None` → 落到环境变量 → 英文； +//! ③代码页（`chcp`）与这里无关，注册表值不受它影响。 + +use unlucky_i18n::lang::LocaleSource; + +/// 语言相关的注册表键。 +const INTERNATIONAL_KEY: &str = r"HKCU\Control Panel\International"; + +/// 首选值名：值是 BCP-47 风格标签（`zh-CN`）。 +const LOCALE_NAME_VALUE: &str = "LocaleName"; + +/// 兜底值名：值是 8 位十六进制 LCID（`00000804`）。 +const LOCALE_VALUE: &str = "Locale"; + +/// 常见 LCID → 语言的短表（**故意短**：不认识的返回 `None`，让链路落到英文）。 +/// +/// 覆盖面：中文四地 + 英语三地 + 几个大语种。这张表只在 `LocaleName` 缺失时用到， +/// 而 `LocaleName` 从 Win7 起就有，所以它实际上是「老系统 / 被裁剪的系统」专用。 +const LCID_TAGS: &[(&str, &str)] = &[ + ("00000804", "zh-CN"), + ("00000404", "zh-TW"), + ("00000c04", "zh-HK"), + ("00001004", "zh-SG"), + ("00000409", "en-US"), + ("00000809", "en-GB"), + ("00000c09", "en-AU"), + ("00000411", "ja-JP"), + ("00000412", "ko-KR"), + ("00000407", "de-DE"), + ("0000040c", "fr-FR"), + ("00000410", "it-IT"), + ("00000c0a", "es-ES"), + ("00000416", "pt-BR"), + ("00000419", "ru-RU"), + ("00000415", "pl-PL"), + ("0000041f", "tr-TR"), + ("00000406", "da-DK"), + ("0000040b", "fi-FI"), + ("00000413", "nl-NL"), +]; + +/// 跑外部命令的接口（注入点：单测不 spawn 进程）。 +pub trait RegIo { + /// 跑一条命令取 stdout；命令缺失 / 非零退出 / 空输出都返回 `None`。 + fn run(&self, program: &str, args: &[&str]) -> Option; +} + +/// 真实实现：`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; + } + + let output = std::process::Command::new(program) + .args(args) + .output() + .ok()?; + // `Command::output` 对非零退出同样返回 `Ok`，退出码要单独判（`reg.exe` 查不到值就是非零）。 + if !output.status.success() || output.stdout.is_empty() { + return None; + } + Some(String::from_utf8_lossy(&output.stdout).into_owned()) + } +} + +/// 系统语言源（实现 [`LocaleSource`]，日志里自称 `registry`）。 +#[derive(Debug, Clone, Copy, Default)] +pub struct SystemLocale; + +impl LocaleSource for SystemLocale { + fn locale(&self) -> Option { + 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/mod.rs b/crates/app-iced/src/platform/mod.rs new file mode 100644 index 0000000..e4e1e3f --- /dev/null +++ b/crates/app-iced/src/platform/mod.rs @@ -0,0 +1,170 @@ +//! 平台相关的窗口能力（P4 / D36 / M116）：整窗透明度与窗口圆角的**判据**、唯一 `unsafe` 落点， +//! 以及系统语言真值源，三件事分居三处。 +//! +//! - 本文件 = 整窗 α 的纯判据 [`effective_window_alpha`]：不读环境变量、不调 FFI、不碰窗口句柄， +//! 只回答「按这个渲染后端和用户要的 α，最终该给窗口什么值」； +//! - [`win32::corner`] = 圆角的纯判据 [`plan_corner`]（M116）：用户策略 × 系统版本 × 渲染档 → +//! 来源与原因码。两个判据都**不碰** FFI，因此都能被断言证明； +//! - [`win32::transparency`] = 唯一允许 `unsafe` 的文件（补 `WS_EX_LAYERED` + +//! `SetLayeredWindowAttributes`，以及 M116 的 `DwmSetWindowAttribute`）； +//! - [`locale`] = 系统语言真值源（D28）：`reg.exe` 子进程读注册表，**零 `unsafe` / 零 FFI**。 +//! +//! 为什么判据要单独拎出来：D36 的降级规则（α 下限 0.08 / `≤0` 一律拒绝 / CPU 档也允许 +//! 窗口级 α）**可以**被断言证明；而 FFI 的**视觉**结果在本仓库的验证环境（RDP + 虚拟显示 +//! 适配器）上没有参考价值。把可测的那一半独立出来，才有「有测试的判据 + 没测试的观感」这条 +//! 诚实的分界。 + +use unlucky_presenter::prefs::WINDOW_ALPHA_MIN; + +use crate::Backend; + +pub mod locale; +pub mod win32; + +/// 窗口圆角的**判定**（M116）住在 `win32::corner`：判据是 Windows 版本与 DWM 能力， +/// 非 Windows 平台在这里恒得「直角」（平台没有可承诺的系统圆角）。 +pub use win32::corner::{plan_corner, CornerExclusion, CornerPlan, CornerSource}; + +/// 本机 Windows 版本（`None` = 非 Windows / 读不到）。**进程内只探测一次**。 +/// +/// 为什么缓存：底层是 `reg.exe` 子进程（`unlucky_core::platform::windows_version`，实测约 50 ms）， +/// 而圆角判定会在启动、切档、热重载时各问一次。探测结果在进程生命周期内不会变。 +/// +/// 为什么走 `unlucky_presenter::prefs` 的重导出而不是 `unlucky_core` 直连： +/// `unlucky-app-iced` 不直接依赖 core（分层：UI → presenter → core），这是既有的唯一通道。 +#[must_use] +pub fn current_windows_version() -> Option { + 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/corner.rs b/crates/app-iced/src/platform/win32/corner.rs new file mode 100644 index 0000000..b4a8c87 --- /dev/null +++ b/crates/app-iced/src/platform/win32/corner.rs @@ -0,0 +1,293 @@ +//! M116：窗口外框圆角的**判据**（纯函数，零 `unsafe`、零 FFI、零环境读取）。 +//! +//! ## 判据为什么单独拎出来 +//! +//! 「能不能圆」= 用户策略 × 系统版本 × 渲染档，这三件事**可以被断言证明**；而 DWM 的**视觉** +//! 结果在本仓库的验证环境（RDP 断连、抓屏失效）上没有参考价值。把可测的那一半独立出来， +//! 才有「有测试的判据 + 没测试的观感」这条诚实的分界（与 [`super::super::effective_window_alpha`] +//! 同一套分法）。 +//! +//! 真正下发给窗口的动作在 [`super::transparency`]（全仓唯一 `unsafe` 落点）。 +//! +//! ## 平台矩阵（哪些是实测、哪些是推断） +//! +//! | 平台 | 我们做什么 | 依据级别 | +//! |---|---|---| +//! | Win11 / Server 2025（build ≥ 22000） | 下发 `DWMWCP_ROUND`（**请求**系统圆角） | 写入被接受 = **本机 API 实测**；「圆没圆 / 边缘什么样」= **未验**（无像素、回读不可用） | +//! | Win10 及更早（build < 22000） | 直角；不做 `SetWindowRgn` 毛边默认 | 「该属性不存在」= **外部文档证据**；本机没有 Win10 | +//! | macOS | 不主动加，交给系统 | **推断**（未真机验） | +//! | Linux X11 / Wayland | 不承诺，直角即如实结果 | **推断**（未真机验） | +//! +//! ⚠️ **「Win11 上我们的窗口一定有圆角、边缘平滑」这句话本分支的证据不支持**，别写回去。 +//! 本机（Server 2025 build 26100、RDP 会话断开）测到的是： +//! ① `DwmSetWindowAttribute(DWMWA_WINDOW_CORNER_PREFERENCE)` 被接受（三种窗口样式都接受）； +//! ② `DwmGetWindowAttribute` 同一属性返回 `E_INVALIDARG`（本会话不支持回读，与窗口形状无关）； +//! ③ DWM 的调整带只给**有 `WS_CAPTION|WS_THICKFRAME` 的窗口**：`EXTENDED_FRAME_BOUNDS − +//! GetWindowRect` 在有边框窗口上是 `+0,−7`，在**裸 `WS_POPUP` 假形状**上是 `+0,+0`。 +//! +//! ⚠️ **第 ③ 条不能拿裸 popup 的读数去解释产品窗口**（M116 r4 复审订正）：产品窗口 +//! **不是** `WS_POPUP`（winit 只在带 owner 的弹出窗才加它；无边框观感来自 `WM_NCCALCSIZE`）， +//! 它带 `WS_CAPTION|WS_THICKFRAME` ⇒ 按同一张表应得 `+0,−7`，与 `decorated` 同族。 +//! 探针里 `product` / `product+alpha` 两行量的就是这个真实形状。 +//! +//! ④ **整窗 α 会关掉圆角**（tower 裁定 A / D47：整窗透明度优先于 DWM 圆角）：α < 1 时我们补 +//! `WS_EX_LAYERED`，此时系统会忽略圆角请求——请求照样发出（日志里 `pref=` 有值）， +//! 只是不生效；α 回到 1.0 就恢复。日志用 `suppressed_by=window_alpha` 记这一条**观测事实**。 +//! +//! 「圆角长什么样」归真机验收，证据目录见 `DevDocs/artifacts/m116/`。 +//! +//! 后两行在本 crate 里落到同一格：探测不到 Windows 版本 ⇒ `UnknownOs` ⇒ 直角。 +//! 这是「不承诺」，不是「做不到」——两者的区别写在日志的原因码里。 + +use unlucky_presenter::prefs::{WindowCorner, WindowsVersion, WIN11_MIN_BUILD}; + +use crate::Backend; + +/// 一次「圆角该从哪来」的判定结果（M116）。 +/// +/// 只有两种来源，且**互相排斥**： +/// +/// | 来源 | 谁画圆角 | 我们做什么 | +/// |---|---|---| +/// | [`CornerSource::Dwm`] | 系统合成器（是否真画、半径多少都不由我们定，也读不到） | 只下发 `DWMWA_WINDOW_CORNER_PREFERENCE` | +/// | [`CornerSource::Square`] | 没人 | 明确下发 `DWMWCP_DONOTROUND`，把「方」也变成可观测的选择 | +/// +/// **没有 `Self`（自绘圆角）这一档**，这是刻意的（用户定案 2026-11-03 + tower 裁定）： +/// 窗口是 `decorations=false` + 自绘标题栏 + 整窗 `LWA_ALPHA`，自绘圆角意味着把内容层裁成圆角， +/// 那会把标题栏三键与边缘缩放热区一起裁掉；系统也不暴露圆角半径（无 API 可读）， +/// 「固定 8/12/16」只是凭空维护一个数字。所以非 DWM 平台**就是直角**，并且日志里说明原因。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum CornerSource { + /// DWM 系统圆角（Win11 / Server 2025 内核，build ≥ [`WIN11_MIN_BUILD`]）。 + Dwm, + /// 直角（用户选择、系统不支持、或该平台不承诺）。 + Square, +} + +impl CornerSource { + /// 日志取值（`corner=… source=dwm|square`）。 + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::Dwm => "dwm", + Self::Square => "square", + } + } + + /// 是否要求 DWM 真去画圆角。 + #[must_use] + pub const fn is_dwm(self) -> bool { + matches!(self, Self::Dwm) + } +} + +/// 为什么**不是** DWM 圆角（`None` = 就是 DWM 圆角）。日志里逐字打出来。 +/// +/// 为什么要这个枚举而不是一个 `bool`：用户报的现象是「别的窗口都有圆角，只有我们的没有」， +/// 于是「没圆角」至少有四种完全不同的原因，混成一个 `square` 以后没人能分辨 +/// 「没生效」与「生效了但看不见」（M116 任务书原话）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum CornerExclusion { + /// 用户在设置里选了「直角」。 + UserSquare, + /// 系统太老：Win10 及更早（build < [`WIN11_MIN_BUILD`]）——DWM 没有这个偏好属性。 + OsBuild, + /// 版本探测不出来（非 Windows / 注册表读不到 / 有东西在骗版本号）。 + UnknownOs, + /// 非 DWM 平台上的软件渲染档：圆角只能靠自绘/`SetWindowRgn` 毛边路，D36 的 + /// 「CPU 档不碰合成技巧」优先，所以退回直角。 + CpuTier, +} + +impl CornerExclusion { + /// 日志取值（`excluded_reason=…`）。 + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::UserSquare => "user", + Self::OsBuild => "os-build", + Self::UnknownOs => "unknown-os", + Self::CpuTier => "cpu-tier", + } + } +} + +/// 判定结果：来源 + 排除原因 + 平台版本（日志与测试共用）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct CornerPlan { + /// 圆角从哪来。 + pub source: CornerSource, + /// `None` = 走 DWM；`Some(..)` = 走直角，并说明为什么。 + pub excluded: Option, + /// 探测到的 Windows 版本（`None` = 不是 Windows / 读不到）。 + pub os: Option, +} + +impl CornerPlan { + /// 日志行：`corner=policy=system source=dwm os=10.0.26100 excluded_reason=none radius=system`。 + /// + /// **`radius=system` 是刻意的**：系统不暴露 DWM 的圆角半径，我们也不自己定一个数字 + /// （用户定案取消了 8/12/16 档），所以这一栏永远只说「系统决定」。 + #[must_use] + pub fn log_line(&self, policy: WindowCorner) -> String { + let os = self + .os + .map_or_else(|| "unknown".to_owned(), |os| os.version_string()); + format!( + "corner=policy={} source={} os={os} excluded_reason={} radius=system", + policy.as_str(), + self.source.as_str(), + self.excluded.map_or("none", CornerExclusion::as_str), + ) + } +} + +/// 判定「这一次窗口该不该有系统圆角」（纯函数，不调 FFI、不读环境）。 +/// +/// 真值表（`backend` 只影响**非 DWM** 平台，见下）： +/// +/// | `policy` | `os.build` | backend | `source` | `excluded` | +/// |---|---|---|---|---| +/// | `Square` | 任意 | 任意 | `Square` | `UserSquare` | +/// | `System` | `None` | 任意 | `Square` | `UnknownOs` | +/// | `System` | `< 22000` | GPU/Auto | `Square` | `OsBuild` | +/// | `System` | `< 22000` | CPU | `Square` | `CpuTier` | +/// | `System` | `>= 22000` | 任意 | `Dwm` | `None` | +/// +/// 为什么 CPU 档在 Win11 上**照样**用 DWM 圆角（**tower 2026-11-03 裁定，按此执行**）： +/// D36 的 CPU 档约束针对的是**我们自己的渲染路径**（面板 α / 玻璃 / 模糊要关、不许拿透明叠加 +/// 去换效果），而 DWM 圆角是**合成器侧**的效果，不增加我们的 GPU/CPU 绘制负担。所以 +/// 「CPU 档关掉 Win11 圆角」不是 D36 的要求，而是凭空造一个没人要的降级。 +/// +/// 反过来在非 DWM 平台上，圆角只剩「自绘裁切 / `SetWindowRgn` 毛边」这两条**我们自己的** +/// 合成技巧，那才是 D36 要拦的东西 ⇒ 那一格落 `cpu-tier` 而不是 `os-build` +/// （同一个直角，**原因不同**，日志里可分辨）。 +#[must_use] +pub fn plan_corner( + policy: WindowCorner, + os: Option, + backend: Backend, +) -> CornerPlan { + let square = |excluded| CornerPlan { + source: CornerSource::Square, + excluded: Some(excluded), + os, + }; + + if policy == WindowCorner::Square { + return square(CornerExclusion::UserSquare); + } + match os { + None => square(CornerExclusion::UnknownOs), + Some(os) if os.build < WIN11_MIN_BUILD => match backend { + Backend::Cpu => square(CornerExclusion::CpuTier), + Backend::Gpu | Backend::Auto => square(CornerExclusion::OsBuild), + }, + Some(_) => CornerPlan { + source: CornerSource::Dwm, + excluded: None, + os, + }, + } +} + +/// 产品日志行的**唯一格式化落点**（纯函数：把四段文本拼成一个固定形状）。 +/// +/// ```text +/// [corner] corner=policy=system source=dwm os=10.0.26100 excluded_reason=none \ +/// radius=system pref=2 readback=? read_hr=0x80070057 frame=overlapped layered=on \ +/// suppressed_by=window_alpha +/// ``` +/// +/// 为什么单独拎出来：`App::apply_window_corner` 要真句柄、真 DWM 才能跑，而**这一行的形状** +/// 恰恰是「以后分辨没生效 / 生效了看不见」的唯一依据（M116 任务书原话）。形状必须在没有窗口的 +/// 环境里也能被断言——tower 2026-11-03 明确要求：不为了这行日志去构建 bin。 +/// +/// 参数里 `outcome` / `style` 由调用方给（`CornerOutcome::describe()` / `style_summary(hwnd)`）， +/// 本文件不依赖 FFI 层，因此可以在非 Windows 目标上编、也能被单测覆盖。 +/// +/// `suppressed_by` 是**观测事实**（tower 裁定 A / D47 要求的那一栏）：整窗 α < 1 时我们补了 +/// `WS_EX_LAYERED`，此时系统忽略圆角请求。配合同一行里的 `pref=`（请求确实发出去了）与 +/// `layered=`（分层位确实在），读者能自己推出「不是我们没发请求」——本函数不写结论性措辞。 +#[must_use] +pub fn format_line( + context: &str, + plan: &CornerPlan, + policy: WindowCorner, + outcome: &str, + style: &str, + suppressed_by: Option<&'static str>, +) -> String { + let mut line = format!( + "[corner] {context} {} {outcome} {style}", + plan.log_line(policy) + ); + if let Some(reason) = suppressed_by { + line.push(' '); + line.push_str("suppressed_by="); + line.push_str(reason); + } + line +} + +/// 一次「已经下发过」的**指纹**：只由判定本身与「当时有没有窗口」组成，不含读数。 +/// +/// 为什么需要它：设置页的滑条（整窗 α / 面板 α / 暗化）每动一下就触发一次外部外观变更， +/// 而圆角与那些键**无关**。没有去重时，拖一次滑条就会刷出一串 +/// `[corner] change …`，把「分辨有没有生效」的那条日志淹掉（M116 r1 复审 P2-4）。 +/// +/// 指纹**刻意不含 `pref=` / `readback=` 这类读数**：那些只有真下发才知道，拿它们参与比较 +/// 会变成「自己比较自己」。判定没变就不重下、也不重记——这也是「同一策略 N 次只记 1 行」的判据。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct CornerApplied { + /// 当时的策略（`system` / `square`）。 + pub policy: WindowCorner, + /// 判定出来的来源。 + pub source: CornerSource, + /// 直角时的原因码（`None` = 走 DWM）。 + pub excluded: Option, + /// 下发时**有没有窗口句柄**：`false → true` 必须重下（首次拿到 HWND 时才真能设属性）。 + pub has_window: bool, + /// 整窗 α 是否 < 1（= 我们补了 `WS_EX_LAYERED`，系统会忽略圆角请求）。 + /// + /// 进指纹是为了让「α 从 1.0 拉低 / 拉回 1.0」各触发一次重下与一行日志——那两次的 + /// 系统行为确实不同，不重记就看不出来。 + pub suppressed_by_window_alpha: bool, +} + +impl CornerApplied { + /// 由判定 + 「有没有句柄」+ 「整窗 α 是否补了分层」构造指纹。 + #[must_use] + pub const fn new( + policy: WindowCorner, + plan: &CornerPlan, + has_window: bool, + suppressed_by_window_alpha: bool, + ) -> Self { + Self { + policy, + source: plan.source, + excluded: plan.excluded, + has_window, + suppressed_by_window_alpha, + } + } +} + +/// 这一次要不要真的下发 / 记日志（纯函数）。 +/// +/// `false` = 判定与上次完全一致（策略、来源、原因码、有没有句柄都没变）⇒ **不动窗口、不打日志**。 +/// `true` 的四种情形：首次、换档、系统版本变化导致判定变化、首次拿到句柄。 +/// +/// 注意：判定不变而上次**下发失败**时这里也返回 `false`——失败原因（`pref=none hresult=…`） +/// 已经在那一行日志里了，重复重试只会刷屏；真要重试应该由「换档 / 重启」触发，不是每帧。 +#[must_use] +pub fn needs_redispatch(previous: Option<&CornerApplied>, next: &CornerApplied) -> bool { + match previous { + None => true, + Some(previous) => previous != next, + } +} + +#[cfg(test)] +mod tests; diff --git a/crates/app-iced/src/platform/win32/corner/tests.rs b/crates/app-iced/src/platform/win32/corner/tests.rs new file mode 100644 index 0000000..796db2d --- /dev/null +++ b/crates/app-iced/src/platform/win32/corner/tests.rs @@ -0,0 +1,289 @@ +//! `win32::corner` 的单测（M116 从 `corner.rs` 搬出来：那个文件要守 400 行上限， +//! 而日志行的形状断言本身就有几十行）。 +//! +//! 判据与真实读数的出处：`DevDocs/artifacts/m116/probe-table.md`。 + +use super::{format_line, plan_corner, CornerExclusion, CornerPlan, CornerSource}; +use crate::Backend; +use unlucky_presenter::prefs::{WindowCorner, WindowsVersion, WIN11_MIN_BUILD}; + +/// 本机实测版本（Server 2025 / build 26100）。 +fn win11() -> WindowsVersion { + WindowsVersion::new(10, 0, 26_100) +} + +/// Win10 22H2（build 19045）：DWM 没有圆角偏好属性。 +fn win10() -> WindowsVersion { + WindowsVersion::new(10, 0, 19_045) +} + +/// **抓得住**：判定链的顺序与每一格的原因码（把 `policy`/`os`/`backend` 任一条判反都会红）。 +/// **抓不住**：DWM 到底有没有真画圆角（那要像素，见 `platform/win32` 的探针输出）。 +#[test] +fn truth_table_policy_os_backend() { + let cases = [ + // policy=Square：任何系统/后端都直角，原因是用户选的。 + ( + WindowCorner::Square, + Some(win11()), + Backend::Gpu, + CornerSource::Square, + Some(CornerExclusion::UserSquare), + ), + ( + WindowCorner::Square, + Some(win10()), + Backend::Cpu, + CornerSource::Square, + Some(CornerExclusion::UserSquare), + ), + ( + WindowCorner::Square, + None, + Backend::Auto, + CornerSource::Square, + Some(CornerExclusion::UserSquare), + ), + // policy=System + 探测不出系统：不许猜「Win11」。 + ( + WindowCorner::System, + None, + Backend::Gpu, + CornerSource::Square, + Some(CornerExclusion::UnknownOs), + ), + // Win10：直角，GPU 档原因是版本、CPU 档原因是渲染档（同一个直角，原因不同）。 + ( + WindowCorner::System, + Some(win10()), + Backend::Gpu, + CornerSource::Square, + Some(CornerExclusion::OsBuild), + ), + ( + WindowCorner::System, + Some(win10()), + Backend::Auto, + CornerSource::Square, + Some(CornerExclusion::OsBuild), + ), + ( + WindowCorner::System, + Some(win10()), + Backend::Cpu, + CornerSource::Square, + Some(CornerExclusion::CpuTier), + ), + // Win11 / Server 2025：三个后端都用 DWM（D36 只管我们自己的合成技巧）。 + ( + WindowCorner::System, + Some(win11()), + Backend::Gpu, + CornerSource::Dwm, + None, + ), + ( + WindowCorner::System, + Some(win11()), + Backend::Cpu, + CornerSource::Dwm, + None, + ), + ( + WindowCorner::System, + Some(win11()), + Backend::Auto, + CornerSource::Dwm, + None, + ), + ]; + + for (policy, os, backend, want_source, want_excluded) in cases { + let plan = plan_corner(policy, os, backend); + assert_eq!( + plan.source, want_source, + "policy={policy:?} os={os:?} backend={backend:?}" + ); + assert_eq!( + plan.excluded, want_excluded, + "policy={policy:?} os={os:?} backend={backend:?} 的原因码" + ); + } +} + +/// 边界：`WIN11_MIN_BUILD` **本身**算 Win11（`>=`，不是 `>`）。 +/// +/// 抓得住：把 `build < WIN11_MIN_BUILD` 写成 `<=`——Win11 21H2（build 22000）会静默掉成直角， +/// 而那正好是第一台 Win11 机器。 +#[test] +fn the_win11_boundary_is_inclusive() { + let at = WindowsVersion::new(10, 0, WIN11_MIN_BUILD); + assert_eq!( + plan_corner(WindowCorner::System, Some(at), Backend::Gpu).source, + CornerSource::Dwm + ); + let below = WindowsVersion::new(10, 0, WIN11_MIN_BUILD - 1); + assert_eq!( + plan_corner(WindowCorner::System, Some(below), Backend::Gpu).source, + CornerSource::Square, + "build 21999 = Win10 22H2 家族末尾，不能算 Win11" + ); +} + +/// 日志行的形状：四个字段都在，且 `excluded_reason=none` 与 `reason=user` 不许混。 +/// +/// 为什么要钉这一条：这行是「后来的人分辨没生效 / 生效了看不见」的唯一依据（任务书原话）， +/// 少一栏就等于把这条线索丢掉。 +#[test] +fn the_log_line_carries_every_field() { + let dwm = plan_corner(WindowCorner::System, Some(win11()), Backend::Gpu) + .log_line(WindowCorner::System); + assert!(dwm.starts_with("corner=policy=system"), "{dwm}"); + assert!(dwm.contains("source=dwm"), "{dwm}"); + assert!(dwm.contains("os=10.0.26100"), "{dwm}"); + assert!(dwm.contains("excluded_reason=none"), "{dwm}"); + assert!(dwm.contains("radius=system"), "{dwm}"); + + let square = plan_corner(WindowCorner::Square, Some(win11()), Backend::Gpu) + .log_line(WindowCorner::Square); + assert!(square.contains("source=square"), "{square}"); + assert!(square.contains("excluded_reason=user"), "{square}"); + + let unknown: CornerPlan = plan_corner(WindowCorner::System, None, Backend::Gpu); + assert!(unknown + .log_line(WindowCorner::System) + .contains("os=unknown")); +} + +/// **日志行的形状**，用 M116 探针窗口的**真实读数**构造（`DevDocs/artifacts/m116/probe-table.md`）。 +/// +/// 抓得住：字段被删/改名/顺序错乱（`excluded_reason` 少一栏、`radius=system` 丢了、 +/// `frame` / `layered` 被挪出这一行）——这些都会让「没生效 vs 生效了看不见」的区分重新变成猜谜。 +/// 抓不住：**产品进程**里那一行（本测试只钉格式）。真值已有：2026-11-04 两次真跑产品 bin +/// （α=1.0 / α=0.85）的 `[corner] boot …` 两行，见 `DevDocs/artifacts/m116/README.md`。 +#[test] +fn the_log_line_shape_is_pinned_with_the_measured_readings() { + // 本机实测：Server 2025 / build 26100；读回 `E_INVALIDARG`；产品形状是 `overlapped`， + // 而 `layered=on` 只可能来自整窗 α（我们的 `WS_EX_LAYERED`） ⇒ 带 `suppressed_by=`。 + let os = WindowsVersion::new(10, 0, 26_100); + let plan: CornerPlan = plan_corner(WindowCorner::System, Some(os), Backend::Gpu); + let line = format_line( + "boot", + &plan, + WindowCorner::System, + "pref=2 readback=? read_hr=0x80070057", + "frame=overlapped layered=on", + Some("window_alpha"), + ); + assert_eq!( + line, + concat!( + "[corner] boot corner=policy=system source=dwm os=10.0.26100 ", + "excluded_reason=none radius=system pref=2 readback=? ", + "read_hr=0x80070057 frame=overlapped layered=on ", + "suppressed_by=window_alpha" + ) + ); + + // 设置里选「直角」：原因码必须从 `none` 变成 `user`，其余字段不动。 + let square = format_line( + "change", + &plan_corner(WindowCorner::Square, Some(os), Backend::Gpu), + WindowCorner::Square, + "pref=1 readback=? read_hr=0x80070057", + "frame=overlapped layered=off", + None, + ); + assert!( + square.contains("corner=policy=square source=square"), + "{square}" + ); + assert!(square.contains("excluded_reason=user"), "{square}"); + assert!(square.contains("frame=overlapped layered=off"), "{square}"); + // α = 1（不补分层）时**不许**出现 `suppressed_by=`：那一栏只在整窗 α 打开时才有意义。 + assert!(!square.contains("suppressed_by"), "{square}"); + + // Win10：原因码是 `os-build`（GPU 档）/ `cpu-tier`（CPU 档），来源仍是 square。 + let win10 = WindowsVersion::new(10, 0, 19_045); + let os_build = + plan_corner(WindowCorner::System, Some(win10), Backend::Gpu).log_line(WindowCorner::System); + assert!( + os_build.contains("source=square") && os_build.contains("excluded_reason=os-build"), + "{os_build}" + ); + let cpu = + plan_corner(WindowCorner::System, Some(win10), Backend::Cpu).log_line(WindowCorner::System); + assert!(cpu.contains("excluded_reason=cpu-tier"), "{cpu}"); + + // 探测不到版本（macOS / X11 / Wayland 落到同一格）：`unknown-os`，不许猜 Win11。 + let unknown = + plan_corner(WindowCorner::System, None, Backend::Gpu).log_line(WindowCorner::System); + assert!( + unknown.contains("os=unknown") && unknown.contains("excluded_reason=unknown-os"), + "{unknown}" + ); +} + +/// **同一策略 N 次只下发 / 只记 1 行**（M116 r1 复审 P2-4 的判据）。 +/// +/// 为什么要有这条：设置页的整窗 α / 面板 α / 暗化滑条每动一下都会触发一次外观变更， +/// 而圆角与它们无关。没有去重时拖一次滑条会刷出一串 `[corner] change …`， +/// 把「分辨有没有生效」的那唯一一行日志淹掉。 +/// +/// 抓得住：把去重删掉（`needs_redispatch` 恒 `true` 时这里会数到 N）、或指纹里漏掉某一维 +/// （换档 / 首次拿到句柄就不重下了）。 +/// 抓不住：真进程里到底打了几行（`eprintln!` 在 `App` 里，本测试只钉判定）。 +#[test] +fn the_same_policy_is_dispatched_only_once() { + use super::{needs_redispatch, plan_corner, CornerApplied}; + use crate::Backend; + use unlucky_presenter::prefs::{WindowCorner, WindowsVersion}; + + let os = WindowsVersion::new(10, 0, 26_100); + let plan = plan_corner(WindowCorner::System, Some(os), Backend::Gpu); + + // 模拟「滑条被拖动 20 次」：每次都是同一个策略、同一个系统、句柄一直在。 + let mut last: Option = None; + let mut dispatches = 0; + for _ in 0..20 { + let next = CornerApplied::new(WindowCorner::System, &plan, true, false); + if needs_redispatch(last.as_ref(), &next) { + dispatches += 1; + last = Some(next); + } + } + assert_eq!(dispatches, 1, "同一策略连按 20 次只该下发/记 1 次"); + + // 换档必须重下。 + let square = plan_corner(WindowCorner::Square, Some(os), Backend::Gpu); + assert!(needs_redispatch( + last.as_ref(), + &CornerApplied::new(WindowCorner::Square, &square, true, false) + )); + + // 句柄从无到有必须重下（首次拿到 HWND 时才真能设属性）。 + let mut no_window: Option = None; + let first = CornerApplied::new(WindowCorner::System, &plan, false, false); + assert!(needs_redispatch(no_window.as_ref(), &first)); + no_window = Some(first); + assert!(needs_redispatch( + no_window.as_ref(), + &CornerApplied::new(WindowCorner::System, &plan, true, false) + )); + + // 整窗 α 拉低（补分层）与拉回 1.0 都必须各重下/各记一行：系统行为在这两次确实不同。 + let opaque = CornerApplied::new(WindowCorner::System, &plan, true, false); + let translucent = CornerApplied::new(WindowCorner::System, &plan, true, true); + assert!( + needs_redispatch(Some(&opaque), &translucent), + "α 从 1.0 拉低必须重下（那一行才会出现 suppressed_by=window_alpha）" + ); + assert!( + needs_redispatch(Some(&translucent), &opaque), + "α 拉回 1.0 也必须重下（圆角请求重新生效）" + ); + assert!( + !needs_redispatch(Some(&translucent), &translucent), + "α 一直在 <1 时重复触发不该刷屏" + ); +} diff --git a/crates/app-iced/src/platform/win32/mod.rs b/crates/app-iced/src/platform/win32/mod.rs new file mode 100644 index 0000000..85239d3 --- /dev/null +++ b/crates/app-iced/src/platform/win32/mod.rs @@ -0,0 +1,16 @@ +//! Win32 专属的窗口能力。 +//! +//! | 子模块 | 是什么 | 有没有 `unsafe` | +//! |---|---|---| +//! | [`transparency`] | D36 定案的整窗 α 唯一实现落点（也是 M116 的 DWM 圆角落点） | **有**（全仓唯一） | +//! | [`corner`] | M116 的圆角**判据**：策略 × 系统版本 × 渲染档 → 来源与原因码 | 没有（纯函数） | +//! +//! 目录形态（而非 `win32.rs` 单文件）是为了让「每个平台一份实现」在路径上一眼可见： +//! 将来 macOS / Wayland 的对应能力各自成目录，互不干扰。 +//! +//! **非 Windows 平台也在编译**：`transparency` 里的公开函数有同签名的空实现， +//! `corner` 的判据在探测不到系统版本时给出「直角 + `unknown-os`」，所以调用点不需要 `#[cfg]`， +//! 行为（返回「本平台不支持」）可被测试断言。 + +pub mod corner; +pub mod transparency; diff --git a/crates/app-iced/src/platform/win32/transparency.rs b/crates/app-iced/src/platform/win32/transparency.rs new file mode 100644 index 0000000..4458a5f --- /dev/null +++ b/crates/app-iced/src/platform/win32/transparency.rs @@ -0,0 +1,398 @@ +//! 整窗透明度（D36）：**全仓唯一**允许 `unsafe` 的文件。 +//! +//! ## 为什么只有这里有 unsafe +//! +//! 窗口级 α 没有任何「安全」的 Rust API 可达：`SetLayeredWindowAttributes` 是 Win32 的 +//! 唯一路径（D36 逐路核实过 wgpu / iced / winit 都没有代理入口）。所以把**整个仓库**的 +//! FFI 面收在这一处，其余一层（[`super::super::effective_window_alpha`]）保持纯函数。 +//! 守门在 `.github/workflows/guards.yml` 的 `unsafe-scope` job：全仓带这个 allow 的文件集合 +//! 必须**恰好等于**本文件的路径（集合相等，不是黑名单命中）。 +//! +//! ## 只做 LWA_ALPHA +//! +//! `LWA_COLORKEY` / `DwmEnableBlurBehindWindow` 一律不用：色键会把某个颜色整块变透明（视觉 +//! 事故），模糊是另一条路线（D36 已排除）。 +//! +//! `WS_EX_LAYERED`（`SetLayeredWindowAttributes` 的调用前提）**也归本文件**：加扩展位只有 +//! `Get/SetWindowLongPtrW` 能走，必须 `unsafe`，而全仓放行 unsafe 的文件集合恰好只有本文件。 +//! 所以窗口创建侧（`app::boot`）不碰扩展样式，它只负责拿到句柄后先调 [`ensure_layered`] +//! 再调 [`apply_window_alpha`]——两件事都在同一个 unsafe 落点里，门禁仍是「集合相等」。 +//! +//! ## 为什么它不影响命中测试与自绘标题栏拖动（D36 任务书要求写清） +//! +//! `LWA_ALPHA` 只改**合成**（DWM 把整窗乘一个常数），不动窗口的命中测试： +//! +//! | 机制 | 会不会让鼠标穿透 | 本项目用不用 | +//! |---|---|---| +//! | `WS_EX_TRANSPARENT`（分层窗口的「点击穿透」位） | **会**（鼠标事件直接发给下层的窗口） | 不用 | +//! | `LWA_COLORKEY`（色键：某种颜色整块变透明） | **会**（命中测试按颜色挖洞） | 不用 | +//! | `WS_EX_LAYERED` + `LWA_ALPHA` | **不会**（只是合成时乘 α，整个矩形仍然接收命中） | 用这一条 | +//! +//! 所以自绘标题栏的拖动照旧：`Message::DragWindow` → `window::drag(id)` 走 winit 的 +//! `WM_NCLBUTTONDOWN(HTCAPTION)`，它依赖的是**窗口矩形内的鼠标事件**，与 α 无关。 +//! 唯一会「点不动」的情形是 α = 0（整窗不可见，用户以为程序消失）——这就是 +//! [`unlucky_presenter::prefs::WINDOW_ALPHA_MIN`]（0.08）作为硬底、且 `α ≤ 0` 直接拒绝的原因。 +//! +//! D36 已在真机上实测「α ≥ 1 时分层样式不破坏命中测试与拖动」；本仓库的 RDP 环境无法复核 +//! 观感，所以这条结论的**行为**部分归真机验收（见 M93 报告「没验的部分」）。 +//! +//! ## 非 Windows +//! +//! 同签名的空实现返回 [`AlphaOutcome::Unsupported`]：调用点不需要 `#[cfg]`， +//! 而「这个平台不支持」这件事本身可以被断言。 + +// D36：这是全仓唯一的 unsafe 落点，CI 的 `unsafe-scope` job 会比对文件集合。 +#![allow(unsafe_code)] + +mod alpha; +mod dwm; +mod exstyle; +mod probe; + +pub use dwm::{apply_corner, style_summary, CornerOutcome}; +pub use exstyle::{click_through, is_click_through_style, WS_EX_TRANSPARENT}; +pub use probe::{controlled_experiment, TABLE_HEADER}; + +pub use alpha::{ + alpha_byte, apply_window_alpha, ensure_layered, AlphaOutcome, AlphaRejection, GWL_EXSTYLE, + LWA_ALPHA, WS_EX_LAYERED, +}; + +/// 读扩展样式（跨位宽的唯一落点：64 位走 `GetWindowLongPtrW`，32 位走 `GetWindowLongW`）。 +#[cfg(all(target_os = "windows", target_pointer_width = "64"))] +pub(super) fn raw_ex_style(hwnd: isize) -> isize { + // SAFETY: 只读一个窗口属性，按值传参、不持有指针、无所有权转移；无效句柄只会返回 0。 + unsafe { GetWindowLongPtrW(hwnd, GWL_EXSTYLE) } +} + +/// 32 位目标：符号是 `GetWindowLongW`（`link_name` 已映射），返回 `i32`，扩到 `isize`。 +#[cfg(all(target_os = "windows", target_pointer_width = "32"))] +pub(super) fn raw_ex_style(hwnd: isize) -> isize { + // SAFETY: 同 64 位分支。 + unsafe { isize::from(GetWindowLongPtrW(hwnd, GWL_EXSTYLE)) } +} + +/// 非 Windows：没有扩展样式这个概念，读 0（`ensure_layered` 因此恒 `false`）。 +#[cfg(not(target_os = "windows"))] +pub(super) fn raw_ex_style(_hwnd: isize) -> isize { + 0 +} + +/// 写扩展样式（位宽分档同上）。 +#[cfg(all(target_os = "windows", target_pointer_width = "64"))] +pub(super) fn raw_set_ex_style(hwnd: isize, style: isize) { + // SAFETY: 同 `raw_ex_style`：按值传参、不持有指针；返回值刻意不用（改完靠回读取证）。 + unsafe { + SetWindowLongPtrW(hwnd, GWL_EXSTYLE, style); + } +} + +/// 32 位目标：符号是 `SetWindowLongW`；扩展样式本身就是 32 位量，收窄无损。 +#[cfg(all(target_os = "windows", target_pointer_width = "32"))] +pub(super) fn raw_set_ex_style(hwnd: isize, style: isize) { + let style = i32::try_from(style).unwrap_or(i32::MAX); + // SAFETY: 同 64 位分支。 + unsafe { + SetWindowLongPtrW(hwnd, GWL_EXSTYLE, style); + } +} + +/// 非 Windows：空实现。 +#[cfg(not(target_os = "windows"))] +pub(super) fn raw_set_ex_style(_hwnd: isize, _style: isize) {} + +/// 回读判据：这一位在不在扩展样式里。 +pub(super) fn has_layered(hwnd: isize) -> bool { + raw_ex_style(hwnd) & WS_EX_LAYERED != 0 +} + +/// 句柄是否指向一个**存在**的窗口（全仓唯一 `unsafe` 落点的一部分）。 +/// +/// 为什么在这里而不是在取证探针那个文件里：`transparency.rs` 是全仓**唯一**允许 `unsafe` 的 +/// 文件（`unsafe-scope` 判据 = 「带 `#![allow(unsafe_code)]` 的文件集合恰好等于本文件」）。 +/// 探针用到 FFI 时就只能**把 FFI 搬进来**，不能让 `unsafe` 溜到没有标记的文件里—— +/// 那会让门禁照样绿、而「唯一落点」这个性质已经破了（M100 r1 复审实测抓到的形状）。 +/// +/// `0` / 无效句柄 → `false`（Win32 的 `IsWindow` 对无效句柄返回 0）。 +#[cfg(target_os = "windows")] +pub(super) fn window_exists(hwnd: isize) -> bool { + // SAFETY: `IsWindow` 只按值接受句柄，不持有指针、无所有权转移；无效句柄返回 0。 + (unsafe { IsWindow(hwnd) }) != 0 +} + +#[cfg(target_os = "windows")] +#[link(name = "user32")] +extern "system" { + /// `IsWindow`：句柄是否指向一个存在的窗口。 + /// + /// 为什么需要它（M100 r1）：`GetWindowLongPtrW` 对**无效句柄**返回 0，与「扩展样式全 0」 + /// 不可区分。取证探针要分「拿不到」与「读到了没有这一位」，所以先验一次句柄。 + fn IsWindow(hwnd: isize) -> i32; + + /// `SetLayeredWindowAttributes`：窗口必须已带 `WS_EX_LAYERED`，α 才生效。 + /// + /// 签名照 Win32 头文件：`BOOL SetLayeredWindowAttributes(HWND, COLORREF, BYTE, DWORD)`。 + fn SetLayeredWindowAttributes(hwnd: isize, color_key: u32, alpha: u8, flags: u32) -> i32; + + /// `GetWindowLongPtrW`：读窗口属性（`GWL_EXSTYLE` = `-20`）。 + /// + /// 头文件里 `GetWindowLongPtrW` 是宏：64 位映射到 `GetWindowLongPtrW`、32 位映射到 + /// `GetWindowLongW`。user32 在 32 位导出里**没有** `...PtrW`，所以这里按指针宽度分档声明， + /// 否则 i686 目标会在链接期失败（本仓的 Win7 冒烟是 x64，但编译不该只在一个位宽上成立）。 + #[cfg(target_pointer_width = "64")] + fn GetWindowLongPtrW(hwnd: isize, index: i32) -> isize; + /// `SetWindowLongPtrW`：写窗口属性（同上，32 位映射到 `SetWindowLongW`）。 + #[cfg(target_pointer_width = "64")] + fn SetWindowLongPtrW(hwnd: isize, index: i32, new_value: isize) -> isize; + + /// 32 位目标的实际符号（见上）。 + #[cfg(target_pointer_width = "32")] + #[link_name = "GetWindowLongW"] + fn GetWindowLongPtrW(hwnd: isize, index: i32) -> i32; + /// 32 位目标的实际符号（见上）。 + #[cfg(target_pointer_width = "32")] + #[link_name = "SetWindowLongW"] + fn SetWindowLongPtrW(hwnd: isize, index: i32, new_value: i32) -> i32; + + /// `GetWindowRect`：窗口矩形的屏幕坐标（**含** DWM 加出来的不可见边框）。 + /// + /// 与 `DWMWA_EXTENDED_FRAME_BOUNDS` 对照，是 M116 探针里「DWM 到底给这个窗口加了多宽的 + /// 边框」这条差值的来源：差值 ≈ 系统认为的边框带宽度。 + fn GetWindowRect(hwnd: isize, rect: *mut WinRect) -> i32; + + /// `CreateWindowExW`：M116 的**受控对照实验**要用它造三种样式的窗口（同进程）。 + /// + /// 只用系统自带类 `STATIC`（不需要 `RegisterClassW`，也就没有窗口过程要写）。 + fn CreateWindowExW( + ex_style: u32, + class: *const u16, + name: *const u16, + style: u32, + x: i32, + y: i32, + width: i32, + height: i32, + parent: isize, + menu: isize, + instance: isize, + param: *mut core::ffi::c_void, + ) -> isize; + + /// `DestroyWindow`：探针窗口用完即毁（不泄漏 HWND）。 + fn DestroyWindow(hwnd: isize) -> i32; + + /// `ShowWindow`：DWM 只管理**可见**窗口，所以探针窗口必须真显示一次才有读数。 + fn ShowWindow(hwnd: isize, command: i32) -> i32; +} + +/// `RECT`（`GetWindowRect` 的 out 参数）。字段顺序照 Win32 头文件，`repr(C)` 保证布局。 +#[cfg(target_os = "windows")] +#[repr(C)] +#[derive(Debug, Clone, Copy, Default)] +pub(super) struct WinRect { + /// 左 + pub left: i32, + /// 上 + pub top: i32, + /// 右 + pub right: i32, + /// 下 + pub bottom: i32, +} + +#[cfg(target_os = "windows")] +#[link(name = "dwmapi")] +extern "system" { + /// `DwmSetWindowAttribute`：M116 圆角的唯一落点（`DWMWA_WINDOW_CORNER_PREFERENCE`）。 + /// + /// 返回 `HRESULT`：`S_OK`(0) = 成功；属性不被这个 Windows 版本认识时是 `E_INVALIDARG` + /// （`0x8007_0057`）——Win10 上就是这个返回值，**不是**「设了但没效果」。 + fn DwmSetWindowAttribute( + hwnd: isize, + attribute: u32, + value: *const core::ffi::c_void, + size: u32, + ) -> i32; + + /// `DwmGetWindowAttribute`：读回 DWM 侧的属性（探针与日志的证据来源）。 + fn DwmGetWindowAttribute( + hwnd: isize, + attribute: u32, + value: *mut core::ffi::c_void, + size: u32, + ) -> i32; +} + +/// 写一个 `u32` 的 DWM 属性，返回 `HRESULT`（0 = `S_OK`）。 +#[cfg(target_os = "windows")] +pub(super) fn dwm_set_u32(hwnd: isize, attribute: u32, value: u32) -> i32 { + // SAFETY: `value` 是栈上的 POD，指针只在调用期间有效，`size` 与它逐字节一致； + // DWM 只按值读取，不保留指针。 + unsafe { + DwmSetWindowAttribute( + hwnd, + attribute, + (&raw const value).cast::(), + 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..3990bae --- /dev/null +++ b/crates/app-iced/src/platform/win32/transparency/dwm.rs @@ -0,0 +1,394 @@ +//! DWM 圆角（M116）：把 [`CornerPlan`](super::super::corner::CornerPlan) 落成一次属性下发。 +//! +//! ## 本文件零 `unsafe`、零 `extern` +//! +//! `DwmSetWindowAttribute` / `DwmGetWindowAttribute` 的声明与调用点在 [`super`] +//! （全仓唯一 `unsafe` 落点）；这里只做「哪一档 → 哪个属性值」的映射、`HRESULT` 解释与回读。 +//! +//! ## 为什么「直角」也要真的下发一次 +//! +//! `DWMWCP_DONOTROUND` 是**显式**的直角请求。不下发也能得到直角（Win10 就没有这个属性）， +//! 但那样日志里「方」与「没生效」长得一模一样。下发 + 回读之后， +//! `corner=… source=square excluded_reason=user` 与 `excluded_reason=os-build` 是两条 +//! 可区分的事实，而不是一句猜测。 +//! +//! ## 回读为什么是证据而不是自证 +//! +//! `DwmSetWindowAttribute` 返回 `S_OK` 只说明「参数被接受了」。属性值由 DWM 保存， +//! 回读拿到的是 **DWM 侧的当前值**——它能抓住「设了 A 属性、读回还是旧值」这类事 +//! （比如把 `DWMWA_WINDOW_CORNER_PREFERENCE` 写成别的号，回读会给出 `None` 或旧值）。 + +/// `DWMWA_WINDOW_CORNER_PREFERENCE`：窗口圆角偏好的属性号（Win11 / Server 2025，build ≥ 22000）。 +pub const DWMWA_WINDOW_CORNER_PREFERENCE: u32 = 34; +/// `DWMWCP_DONOTROUND`：显式直角。 +pub const DWMWCP_DONOTROUND: u32 = 1; +/// `DWMWCP_ROUND`：显式圆角（半径由系统决定，**不暴露**给应用）。 +pub const DWMWCP_ROUND: u32 = 2; +/// `DWMWA_VISIBLE_FRAME_BORDER_THICKNESS`：可见边框厚度（像素，Win11 起）。 +/// +/// ⚠️ **本机实测它不能当「圆不圆」的判据**（我最初以为能，被探针否掉了）： +/// 三种窗口样式 × 三种状态（默认 / `DWMWCP_ROUND` / `DWMWCP_DONOTROUND`）读出来**全是 `1`**， +/// 没有任何区分度。保留它只作诊断读数（万一将来在别的机器上有变化），不参与判定。 +/// 证据：`DevDocs/artifacts/m116/probe-table.md` 的 `bdef` / `brnd` / `bsq` 三列。 +pub const DWMWA_VISIBLE_FRAME_BORDER_THICKNESS: u32 = 37; +/// `DWMWA_EXTENDED_FRAME_BOUNDS`：DWM 认为的窗口边界（**含**不可见的调整带）。 +pub const DWMWA_EXTENDED_FRAME_BOUNDS: u32 = 9; + +/// 一次圆角下发的结局（日志与测试共用）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum CornerOutcome { + /// 非 Windows：空实现，什么都没做。 + UnsupportedPlatform, + /// 句柄为 0：还没拿到窗口，或窗口已销毁。 + NoWindow, + /// 已下发且回读一致。`readback == None` 表示**这一版 DWM 不接受回读** + /// （属性不被认识时 `DwmGetWindowAttribute` 返回 `E_INVALIDARG`），此时只有 `S_OK` 作证。 + Applied { + /// 下发下去的偏好值（[`DWMWCP_ROUND`] / [`DWMWCP_DONOTROUND`]）。 + preference: u32, + /// DWM 侧回读到的值（`None` = 读不回来）。 + readback: Option, + /// 回读那一次的 `HRESULT`（`0` = `S_OK`）。 + read_hresult: u32, + }, + /// 属性不被这个 Windows 版本认识（`E_INVALIDARG`）：Win10 就是这个结局。 + Unsupported { + /// `DwmSetWindowAttribute` 的原始 `HRESULT`。 + hresult: u32, + }, + /// 其他失败（句柄无效等），`hresult` 来自 DWM。 + Failed { + /// `DwmSetWindowAttribute` 的原始 `HRESULT`。 + hresult: u32, + }, +} + +impl CornerOutcome { + /// 一行日志尾巴：`corner=source=dwm pref=2 readback=2`。 + /// + /// `readback=?` 与 `pref=none`（平台不支持）是不同的坏消息：前者是「设了但读不回来」， + /// 后者是「这里根本没有这个能力」。 + #[must_use] + pub fn describe(&self) -> String { + match self { + Self::UnsupportedPlatform => "pref=none readback=n/a platform=unsupported".to_owned(), + Self::NoWindow => "pref=none readback=n/a window=none".to_owned(), + Self::Applied { + preference, + readback, + read_hresult, + } => format!( + "pref={preference} readback={} read_hr=0x{read_hresult:08X}", + readback.map_or_else(|| "?".to_owned(), |value| value.to_string()) + ), + Self::Unsupported { hresult } => { + format!("pref=none readback=n/a hresult=0x{hresult:08X} (attribute unsupported)") + } + Self::Failed { hresult } => format!("pref=none readback=n/a hresult=0x{hresult:08X}"), + } + } +} + +/// `HRESULT` 是不是 `E_INVALIDARG`（`0x8007_0057`）：Win10 上设这个属性就是这个返回值。 +#[cfg(target_os = "windows")] +const E_INVALIDARG: u32 = 0x8007_0057; + +/// 把「来源」映射成要下发的偏好值（纯函数，测试直接钉它）。 +/// +/// `Dwm` → [`DWMWCP_ROUND`]；`Square` → [`DWMWCP_DONOTROUND`]。 +/// 刻意**不用**默认值（`0`）：那在 Win11 上等于「请 DWM 自己决定」，而无边框窗口 +/// 到底算不算「有框」由 DWM 的启发式决定——那正是我们要么拿到、要么明确放弃的东西。 +#[must_use] +pub const fn preference_for(source: super::super::corner::CornerSource) -> u32 { + use super::super::corner::CornerSource; + match source { + CornerSource::Dwm => DWMWCP_ROUND, + CornerSource::Square => DWMWCP_DONOTROUND, + } +} + +/// 下发一次圆角偏好（幂等：重复调用结果相同）。 +pub fn apply_corner(hwnd: isize, plan: &super::super::corner::CornerPlan) -> CornerOutcome { + if hwnd == 0 { + return CornerOutcome::NoWindow; + } + set_preference(hwnd, preference_for(plan.source)) +} + +/// 下发一个具体的偏好值并回读（拆开是为了让探针能逐格遍历）。 +pub fn set_preference(hwnd: isize, preference: u32) -> CornerOutcome { + #[cfg(not(target_os = "windows"))] + { + let _ = (hwnd, preference); + return CornerOutcome::UnsupportedPlatform; + } + #[cfg(target_os = "windows")] + { + if hwnd == 0 { + return CornerOutcome::NoWindow; + } + let hresult = super::dwm_set_u32(hwnd, DWMWA_WINDOW_CORNER_PREFERENCE, preference); + if !super::hresult_ok(hresult) { + // 原始位，不是 `unsigned_abs()`（见 `dwm_get_u32_hr` 的注释：后者印不出 HRESULT）。 + let code = hresult as u32; + return if code == E_INVALIDARG { + CornerOutcome::Unsupported { hresult: code } + } else { + CornerOutcome::Failed { hresult: code } + }; + } + let (readback, read_hresult) = corner_preference_hr(hwnd); + CornerOutcome::Applied { + preference, + readback, + read_hresult, + } + } +} + +/// 读圆角偏好**以及它的 `HRESULT`**（`(None, code)` = 读不回来，`code` 是 DWM 给的原因）。 +/// +/// 为什么要暴露 `HRESULT`：M116 本机实测——**写成功、读回 `E_INVALIDARG`**。只报 `?` +/// 会让「设上了吗」变成猜谜；有了码就能说清是「属性不支持读」而不是「没设上」。 +#[must_use] +pub fn corner_preference_hr(hwnd: isize) -> (Option, u32) { + #[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 { + use super::{ + apply_corner, corner_preference_hr, preference_for, CornerOutcome, + DWMWA_VISIBLE_FRAME_BORDER_THICKNESS, DWMWA_WINDOW_CORNER_PREFERENCE, DWMWCP_DONOTROUND, + DWMWCP_ROUND, + }; + use crate::platform::win32::corner::{CornerPlan, CornerSource}; + use unlucky_presenter::prefs::WindowsVersion; + + /// **抓得住**：属性号写错（34 写成 33 / 37 写成 36 —— 这两个都在 Win11 上存在，改错不会崩， + /// 只会静默读出别的东西）、两个偏好值互换。 + /// **抓不住**：这些值在真窗口上是否真的生效（那要探针读数，见 `probe` 与报告）。 + #[test] + fn attribute_numbers_follow_the_win32_header() { + assert_eq!(DWMWA_WINDOW_CORNER_PREFERENCE, 34); + assert_eq!(DWMWA_VISIBLE_FRAME_BORDER_THICKNESS, 37); + assert_eq!(DWMWCP_ROUND, 2); + assert_eq!(DWMWCP_DONOTROUND, 1); + } + + /// **抓得住**：`preference_for` 把圆角/直角映射反了（这一格反了就是「设置里选直角反而更圆」）。 + #[test] + fn the_preference_mapping_cannot_be_swapped() { + assert_eq!(preference_for(CornerSource::Dwm), DWMWCP_ROUND); + assert_eq!(preference_for(CornerSource::Square), DWMWCP_DONOTROUND); + } + + /// 无效句柄：**不下发**、也不 panic。句柄 0 走 `NoWindow`（还没拿到窗口 ≠ 平台不支持）。 + #[test] + fn a_missing_window_is_reported_not_guessed() { + let plan = CornerPlan { + source: CornerSource::Dwm, + excluded: None, + os: Some(WindowsVersion::new(10, 0, 26_100)), + }; + assert_eq!(apply_corner(0, &plan), CornerOutcome::NoWindow); + assert_eq!(corner_preference_hr(0).0, None); + // 1 号句柄永远无效：非 Windows 上是「平台不支持」，Windows 上是 DWM 的失败码， + // 两种都不许表现成「成功」。 + let outcome = apply_corner(1, &plan); + assert!( + matches!( + outcome, + CornerOutcome::Failed { .. } + | CornerOutcome::Unsupported { .. } + | CornerOutcome::UnsupportedPlatform + ), + "无效句柄应报失败，实际 {outcome:?}" + ); + } + + /// 日志尾巴三态可区分：设了 / 设了但读不回 / 属性不支持。 + #[test] + fn the_log_tail_separates_applied_from_unsupported() { + let applied = CornerOutcome::Applied { + preference: DWMWCP_ROUND, + readback: Some(DWMWCP_ROUND), + read_hresult: 0, + }; + assert!( + applied.describe().starts_with("pref=2 readback=2"), + "{applied:?}" + ); + + let blind = CornerOutcome::Applied { + preference: DWMWCP_ROUND, + readback: None, + read_hresult: 0x8000_4005, + }; + assert!( + blind.describe().contains("readback=?"), + "{}", + blind.describe() + ); + + let old = CornerOutcome::Unsupported { + hresult: 0x8007_0057, + }; + assert!( + old.describe().contains("attribute unsupported"), + "{}", + old.describe() + ); + assert!(CornerOutcome::UnsupportedPlatform + .describe() + .contains("platform=unsupported")); + } +} + +/// **抓得住**：`frame_label` 把 `WS_POPUP` 与 `WS_OVERLAPPEDWINDOW` 判反（那会让日志把 +/// 「我们自己的窗口」写成「普通窗口」，这行日志的全部价值就是分辨这个）。 +/// **抓不住**：真窗口上到底置了哪一位（那属于运行时读数）。 +#[test] +fn the_frame_label_separates_popup_from_a_decorated_window() { + assert_eq!(WS_POPUP, 0x8000_0000_u32 as isize); + assert_eq!(frame_label(WS_POPUP | 0x1000_0000), "popup"); + assert_eq!(frame_label(0x00CF_0000), "overlapped"); + assert_eq!(frame_label(0), "other"); +} + +/// 分层位标签：只认 `WS_EX_LAYERED`，别把 `WS_EX_TRANSPARENT` 之类的邻居混进来。 +#[test] +fn the_layered_label_reads_the_right_bit() { + let layered = crate::platform::win32::transparency::WS_EX_LAYERED; + assert_eq!(layered_label(layered), "on"); + assert_eq!(layered_label(WS_POPUP), "off"); + assert_eq!(layered_label(0), "off"); +} + +/// 读不到句柄时摘要不许编：`frame=? layered=?`（「不知道」与「没有」是两件事）。 +#[test] +fn the_style_summary_never_guesses() { + assert_eq!(style_summary(0), "frame=? layered=?"); +} diff --git a/crates/app-iced/src/platform/win32/transparency/exstyle.rs b/crates/app-iced/src/platform/win32/transparency/exstyle.rs new file mode 100644 index 0000000..82c8ab4 --- /dev/null +++ b/crates/app-iced/src/platform/win32/transparency/exstyle.rs @@ -0,0 +1,107 @@ +//! 取证用的**扩展样式探针**（M100 r1 P2-2）：这个窗口是不是「点击穿透」。 +//! +//! ## 本文件零 `unsafe`、零 `extern` +//! +//! 全仓 `unsafe` 只允许出现在 [`super`]（`transparency.rs`）一个文件里，判据是 +//! 「**带放行属性**的文件集合恰好等于它」。所以探针需要的 FFI 一律由 `transparency.rs` 提供 +//! **安全包装**（[`super::window_exists`] / [`super::raw_ex_style`]），本文件只做纯判断、 +//! 三态映射与测试。 +//! +//! ⚠️ **别把 FFI 写回来**（M100 r1 复审实测抓过一次）：lint 级别沿模块树继承，所以在这里写 +//! 一个 `unsafe` 块 + `extern` 声明也**编得过**，`unsafe-scope` 门禁也照样绿（它只数「带放行 +//! 属性的文件」）——但「全仓唯一允许 unsafe 的文件」这个性质就破了。 +//! 属性的作用是可审计性，不是给 CI 看的。 +//! +//! ## 判据来源 +//! +//! winit 0.30 在 Windows 把 `set_cursor_hittest(false)` 落成 +//! `WS_EX_TRANSPARENT | WS_EX_LAYERED`（`window_state.rs`）。所以读回这一位，就是 +//! 「取证窗口真的把命中测试关掉了」的 OS 侧证据——比「出图 hash 不变」有判别力得多 +//! （实测：同 argv 开/关穿透，hash 完全相同）。 + +use super::raw_ex_style; + +/// `WS_EX_TRANSPARENT`：**点击穿透**位（`0x0000_0020`）。 +pub const WS_EX_TRANSPARENT: isize = 0x0000_0020; + +/// 纯判据：扩展样式里 [`WS_EX_TRANSPARENT`] 在不在。 +/// +/// 单独拎成 `const fn` 是为了让「位判断写反」有断言盯着——`& WS_EX_TRANSPARENT != 0` 写成 +/// `== 0` 是这类 getter 最经典的错，而且只会在「开/关恰好反向」时暴露（两边都"有输出"）。 +#[must_use] +pub const fn is_click_through_style(ex_style: isize) -> bool { + ex_style & WS_EX_TRANSPARENT != 0 +} + +/// 取证用：窗口**现在**是否点击穿透（`WS_EX_TRANSPARENT` 在扩展样式里）。 +/// +/// ## 为什么是三态而不是 `bool` +/// +/// `None` = **没读到**（非 Windows / 句柄无效 / 句柄还没拿到）。这时调用方必须记 `unknown`， +/// **不许记成 `off`**——「拿不到」和「没有」是两件事，混为一谈就是假绿（本项目在别处栽过： +/// 扫描读不全时报「没有」）。所以这里宁可 `None`，也不用「读失败的 0」冒充「没这一位」。 +/// +/// ## 为什么本文件零 `unsafe`、零 `extern` +/// +/// `unsafe` 全仓只在 [`super`]（`transparency.rs`）那一个文件里。探针需要的 FFI +/// （`IsWindow` / `GetWindowLongPtrW`）都由 `super` 提供安全包装 +/// （[`super::window_exists`] / [`super::raw_ex_style`]），本文件只做**纯判断**。 +/// +/// ## 用途 +/// +/// 出图时把它打进日志（`pages::harness` 的 `[caps] passthrough_ext=…`），于是「取证窗口到底 +/// 有没有把指针输入关掉」每次运行都能自证，不依赖外部探针。 +#[cfg(target_os = "windows")] +#[must_use] +pub fn click_through(hwnd: isize) -> Option { + 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..2a307ac --- /dev/null +++ b/crates/app-iced/src/platform/win32/transparency/probe.rs @@ -0,0 +1,342 @@ +//! M116 的**受控对照实验**：同进程里造几种窗口样式，逐个读 DWM 属性。 +//! +//! ## 为什么需要它 +//! +//! 用户的观察是「同一台机器上别的窗口都有圆角，只有我们的没有」。于是「没圆角」至少有三种 +//! 可能：①这是 DWM 的默认行为（我们没申请）；②某个**样式位**把它 opt-out 了；③属性根本设不上。 +//! +//! 只在自己的窗口上读一次，分不清 ①②③。所以这里**同一进程**里造几个窗口，除「样式」外 +//! 条件全相同： +//! +//! | 标签 | 样式 | 它代表什么 | +//! |---|---|---| +//! | `decorated` | `WS_OVERLAPPEDWINDOW` | 用户说的「别的窗口」（对照） | +//! | `probe:popup` | 裸 `WS_POPUP` | **对照，不是产品形状**：带 owner 的弹出窗才用这一位 | +//! | `probe:popup+layered` | `WS_POPUP` + `WS_EX_LAYERED`(α) | **对照**：把两个嫌疑同时打开 | +//! | `product` | [`PRODUCT_STYLE`]（α = 1，不补分层） | 产品的**真实**样式（出厂态） | +//! | `product+alpha` | [`PRODUCT_STYLE`] + `WS_EX_LAYERED`(α) | 产品真实样式 + 用户把整窗 α 拉低 | +//! +//! ## ⚠️ 产品窗口**不是** `WS_POPUP`（M116 r4 复审订正） +//! +//! iced/winit 在 `decorations = false` 下**不会**用 `WS_POPUP`：winit 的 +//! `window_state.rs::to_window_styles` 起点是 `WS_CAPTION|WS_BORDER|WS_CLIPSIBLINGS|WS_SYSMENU`， +//! 可缩放/可最大化时再加 `WS_THICKFRAME|WS_MINIMIZEBOX|WS_MAXIMIZEBOX`；`WS_POPUP` 只在 +//! `WindowFlags::POPUP`（**带 owner** 的弹出窗）时才加。产品的「无边框观感」来自 +//! `WM_NCCALCSIZE` 把客户区铺满，**不是**样式位。 +//! +//! 所以本文件早期那句「`popup+layered` = 本产品窗口的完整形状」是**错的**：那一行的读数 +//! （尤其 `Δframe = +0,+0`）只属于假形状，不能拿去解释产品窗口。要解释产品，看 `product` +//! 与 `product+alpha` 两行。 +//! +//! ## 这个实验能证明什么、不能证明什么 +//! +//! **能**：属性层能不能开（`DwmSetWindowAttribute` 的 `HRESULT`）、开完 DWM 侧回读是多少、 +//! 各样式之间 `DWMWA_VISIBLE_FRAME_BORDER_THICKNESS` 与 +//! `DWMWA_EXTENDED_FRAME_BOUNDS - GetWindowRect` 的数值差是否随样式变化。 +//! +//! **不能**：角上到底是不是透明的（那要合成输出像素，本机 RDP 断连拿不到）。所以本文件 +//! 的读数只回答「属性层」，观感归真机验收——报告里逐条标注。 + +#[cfg(target_os = "windows")] +use super::alpha::{apply_window_alpha, ensure_layered}; +use super::dwm::{ + corner_preference_hr, extended_frame_bounds, set_preference, visible_border_thickness, + window_rect, window_style, CornerOutcome, DWMWCP_DONOTROUND, DWMWCP_ROUND, +}; + +/// `WS_POPUP`（`0x8000_0000`）：**带 owner 的弹出窗**才用它；产品主窗口没有 owner，不用。 +pub const WS_POPUP: u32 = 0x8000_0000; +/// `WS_OVERLAPPEDWINDOW`：普通有边框窗口（对照组的「别的窗口」）。 +pub const WS_OVERLAPPEDWINDOW: u32 = 0x00CF_0000; + +/// `WS_CAPTION`（`WS_BORDER | WS_DLGFRAME`）。 +const WS_CAPTION: u32 = 0x00C0_0000; +/// `WS_BORDER`（= `WS_THICKFRAME` 的低位别名，`0x0080_0000`）。 +const WS_BORDER: u32 = 0x0080_0000; +/// `WS_CLIPSIBLINGS`：子窗口层叠顺序位（DWM 不看它，winit 的起点里有）。 +const WS_CLIPSIBLINGS: u32 = 0x0400_0000; +/// `WS_SYSMENU`。 +const WS_SYSMENU: u32 = 0x0008_0000; +/// `WS_THICKFRAME`（可缩放边框）。 +const WS_THICKFRAME: u32 = 0x0004_0000; +/// `WS_MINIMIZEBOX`。 +const WS_MINIMIZEBOX: u32 = 0x0002_0000; +/// `WS_MAXIMIZEBOX`。 +const WS_MAXIMIZEBOX: u32 = 0x0001_0000; + +/// **产品窗口的真实样式位**（iced/winit，`decorations = false`，可缩放、可最大化、可最小化）。 +/// +/// 出处（可复核）：winit `window_state.rs::to_window_styles` 从 +/// `WS_CAPTION|WS_BORDER|WS_CLIPSIBLINGS|WS_SYSMENU` 起手，`RESIZABLE` / `MAXIMIZABLE` / +/// `MINIMIZABLE` 分别加 `WS_THICKFRAME` / `WS_MAXIMIZEBOX` / `WS_MINIMIZEBOX`；`WS_POPUP` +/// 只在 `WindowFlags::POPUP`（带 owner）时才加——产品主窗口不带。 +/// +/// 这些**位**是输入（照抄 winit 的产物，带出处）；表里那一行 `product` 的**读数**是跑出来的， +/// 不是我写死的。 +pub const PRODUCT_STYLE: u32 = WS_CAPTION + | WS_BORDER + | WS_CLIPSIBLINGS + | WS_SYSMENU + | WS_THICKFRAME + | WS_MINIMIZEBOX + | WS_MAXIMIZEBOX; + +/// `WS_EX_LAYERED` 的 `u32` 形态（`create_probe_window` 的参数类型）。 +const WS_EX_LAYERED_U32: u32 = 0x0008_0000; + +/// 实验里的一行（一个窗口样式）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ProbeRow { + /// 这一行是什么样式（见模块文档的表）。 + pub label: &'static str, + /// 创建时请求的样式位。 + pub style: u32, + /// 创建时请求的扩展样式位。 + pub ex_style: u32, + /// 读回的 `GWL_STYLE`（证明请求的样式真的生效了）。 + pub style_readback: Option, + /// 什么都没设时 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..4f55898 --- /dev/null +++ b/crates/app-iced/src/platform/win32/transparency/tests.rs @@ -0,0 +1,233 @@ +//! `transparency` 的测试（M116 从 `transparency.rs` 搬出来：那个文件要留行数给 DWM 的 FFI）。 +//! +//! **本文件零 `unsafe`、零 `extern`**：只调父模块的安全包装。别把 FFI 写进来—— +//! 「全仓唯一允许 unsafe 的文件」是 `transparency.rs`，不是它下面的每个文件。 + +use super::{ + alpha_byte, apply_window_alpha, ensure_layered, AlphaOutcome, AlphaRejection, GWL_EXSTYLE, + LWA_ALPHA, WS_EX_LAYERED, +}; +use unlucky_presenter::prefs::WINDOW_ALPHA_MIN; + +#[test] +fn layered_constants_match_the_win32_header() { + // 抓得住：常量写错（例如把 GWL_EXSTYLE 写成 -16 = GWL_STYLE，或 WS_EX_LAYERED 少写一个 0）。 + // 抓不住：这些值在真实窗口上是否真的生效（那要靠真机日志，见 app 侧）。 + assert_eq!(WS_EX_LAYERED, 0x0008_0000); + assert_eq!(GWL_EXSTYLE, -20); +} + +#[test] +fn ensure_layered_refuses_a_missing_or_invalid_window() { + // 句柄 0 = 还没拿到窗口：不许「假设成功」。 + assert!(!ensure_layered(0), "句柄 0 必须返回 false"); + // 1 号句柄永远无效：读不到扩展样式，也就加不上这一位。 + assert!(!ensure_layered(1), "无效句柄必须返回 false（不 panic）"); +} + +#[test] +fn alpha_byte_quantizes_upward_never_below_the_floor() { + assert_eq!(alpha_byte(1.0), 255); + assert_eq!(alpha_byte(0.5), 128, "0.5×255=127.5 → 向上取整 128"); + assert_eq!( + alpha_byte(WINDOW_ALPHA_MIN), + 21, + "0.08×255=20.4 → 向上取整 21；用 round 会得到 20，实际下发 20/255=0.0784 低于 D36 下限" + ); + // 漏过预处理的坏值也不会变成「穿透」：一律落到下限字节。 + for bad in [0.0, -3.0, f64::NAN] { + assert_eq!( + alpha_byte(bad), + alpha_byte(WINDOW_ALPHA_MIN), + "{bad} 应取下限" + ); + } + assert_eq!( + LWA_ALPHA, 0x2, + "0x2 就是 LWA_ALPHA；写成 0x1 会变成色键、等于没设 α" + ); +} + +#[test] +fn applied_alpha_is_never_below_the_floor() { + // 真正生效的 α 是 `bAlpha / 255`，不是传进来的 f64。这条把「改用 round」的行为钉死： + // round 下 0.08 → 20 → 20/255 = 0.0784 < 0.08 → 这里红。 + for requested in [WINDOW_ALPHA_MIN, 0.081, 0.1, 0.33, 0.5, 0.77, 0.999, 1.0] { + let byte = alpha_byte(requested); + let applied = f64::from(byte) / 255.0; + assert!( + applied >= WINDOW_ALPHA_MIN - 1e-12, + "requested={requested} → byte={byte} → 实际 α={applied}，低于下限 {WINDOW_ALPHA_MIN}" + ); + assert!( + applied <= 1.0, + "requested={requested} → 实际 α={applied} 超过 1.0" + ); + } +} + +#[test] +fn missing_or_opaque_alpha_never_touches_the_window() { + for none in [None, Some(0.0), Some(-0.5), Some(f64::NAN)] { + assert_eq!( + apply_window_alpha(1234, none), + AlphaOutcome::Rejected(AlphaRejection::NoAlpha), + "{none:?} 应被拒绝（整窗穿透不许发生）" + ); + } + // α = 1.0：两个平台都返回 Opaque —— 正好证明「不调 FFI」不是靠 Unsupported 混过去的。 + assert_eq!(apply_window_alpha(1234, Some(1.0)), AlphaOutcome::Opaque); + // 合法 α 但没有句柄：拒绝，绝不下发。 + assert_eq!( + apply_window_alpha(0, Some(0.5)), + AlphaOutcome::Rejected(AlphaRejection::NoWindow) + ); +} + +#[cfg(target_os = "windows")] +#[test] +fn invalid_handle_reports_a_win32_failure_instead_of_panicking() { + // 用 1 号句柄（永远无效）真调一次 API：验的是**返回值语义**，不是观感。 + match apply_window_alpha(1, Some(0.5)) { + AlphaOutcome::Failed { code } => { + assert_eq!(code, 1400, "ERROR_INVALID_WINDOW_HANDLE") + } + other => panic!("无效句柄应报 Failed，实际 {other:?}"), + } +} + +#[cfg(not(target_os = "windows"))] +#[test] +fn non_windows_stub_reports_unsupported() { + assert_eq!(apply_window_alpha(1, Some(0.5)), AlphaOutcome::Unsupported); +} + +/// **受控对照实验**（M116）：同进程造三种窗口样式，逐行读 DWM 属性。 +/// +/// 为什么是 `#[ignore]`：它要真造窗口（CI 的无桌面环境里跑不出读数），所以只在需要出证据时 +/// 手动跑： +/// +/// ```text +/// cargo test -p unlucky-app-iced --lib m116 -- --ignored --nocapture +/// ``` +/// +/// 输出就是报告里那张表（`| style | requested | exstyle | readback | … |`）。 +/// **抓不住**：角上到底是透明还是方块（那要合成输出像素，本机 RDP 断连拿不到）。 +#[cfg(target_os = "windows")] +#[test] +#[ignore = "要真窗口：手动跑 cargo test -p unlucky-app-iced --lib m116 -- --ignored --nocapture"] +fn m116_corner_controlled_experiment() { + println!("{}", super::probe::TABLE_HEADER); + for row in super::controlled_experiment() { + println!("{}", row.describe()); + } +} + +/// **成功判据的语义**：`HRESULT` 看严重性位（bit 31），不是「等于 0」——`S_FALSE`(1) 也算成功。 +/// +/// ⚠️ 这条测试**不是**「本机 DWM 会返回某个正数」的证据：本机 +/// `DwmGetWindowAttribute` 三种窗口样式实测全 `E_INVALIDARG (0x80070057)`（失败）。 +/// 下面那个 `0x7FF8_FFA9` 是**合成值**，只用来钉住「非零但严重性位为 0 ⇒ 成功」这条规则， +/// 以及钉住「`unsigned_abs()` 不能用来打印 HRESULT」这个打印坑。 +/// +/// 抓得住：把成功判据写回 `hr == 0`；把打印改回 `unsigned_abs()`。 +/// 抓不住：DWM 在别的机器上返回什么（那是运行期读数）。 +#[test] +fn hresult_success_follows_the_severity_bit_not_equality_with_zero() { + use super::hresult_ok; + assert!(hresult_ok(0), "S_OK"); + assert!(hresult_ok(1), "S_FALSE 也是成功"); + assert!( + hresult_ok(0x7FF8_FFA9), + "合成值：非零但严重性位为 0 ⇒ 按 HRESULT 语义是成功（不是 DWM 的实测返回值）" + ); + // 失败码：严重性位为 1（i32 负数）。**本机探针实际拿到的就是这个**。 + assert!(!hresult_ok(0x8007_0057_u32 as i32), "E_INVALIDARG"); + assert!(!hresult_ok(-1)); + // **打印规则**：失败码必须印成 `hr as u32` 的原始位。 + // `unsigned_abs()` 会把 `0x8007_0057` 印成 `0x7FF8_FFA9`（M116 踩过，一次误读的源头）， + // 于是「E_INVALIDARG」读起来像「一个信息级成功码」，整个证据链就毁了。 + let e_invalidarg = 0x8007_0057_u32 as i32; + assert_eq!(e_invalidarg as u32, 0x8007_0057); + assert_ne!(e_invalidarg.unsigned_abs(), 0x8007_0057); +} + +/// **两种「错误号」不同源，打印方式也不同**（tower 裁定 2026-11-03：不许统一）。 +/// +/// - `GetLastError()` 是 **DWORD**：`87`（`ERROR_INVALID_PARAMETER`）/ `1400` +/// （`ERROR_INVALID_WINDOW_HANDLE`）这类小整数，没有严重性位，`set_layered` 用 +/// `raw_os_error().unsigned_abs()` 取的就是它； +/// - `Dwm*WindowAttribute` 返回 **HRESULT**：成功看 bit 31，打印用 `as u32` 原始位。 +/// +/// 抓得住：有人把 `set_layered` 也改成 `as u32`（或把 DWM 那侧改成 `unsigned_abs`）—— +/// 前者对 `87` 无害但对高位被置的错误号会印出负数，后者会把 `E_INVALIDARG` 印成 +/// `0x7FF8FFA9`（M116 实测踩过的那个坑）。 +#[test] +fn dword_error_codes_and_hresults_are_printed_differently() { + use super::hresult_ok; + + // DWORD 侧：典型值是小的正数，两种打印结果一致（所以错误只会在高位情形暴露）。 + for dword in [87_i32, 1400] { + assert_eq!(dword.unsigned_abs(), dword as u32); + assert!( + hresult_ok(dword), + "DWORD 不是 HRESULT，不该拿这个判据去读它" + ); + } + + // HRESULT 侧：失败码的原始位与 `unsigned_abs()` 必须不同。 + let e_invalidarg = 0x8007_0057_u32 as i32; + assert!(!hresult_ok(e_invalidarg)); + assert_eq!(e_invalidarg as u32, 0x8007_0057); + assert_ne!(e_invalidarg.unsigned_abs(), e_invalidarg as u32); +} + +/// **产品日志行 `[corner] …` 的真实取值**（同一套判据 + 同一套格式化，句柄换成探针窗口）。 +/// +/// `excluded_reason=` / `frame=` / `layered=` 三栏是「为什么我们的窗口没有圆角」的唯一现场线索； +/// 报告里要贴真实取值，不是模板。跑法同 `m116`： +/// +/// ```text +/// cargo test -p unlucky-app-iced --lib m116 -- --ignored --nocapture +/// ``` +#[cfg(target_os = "windows")] +#[test] +#[ignore = "要真窗口：手动跑 cargo test -p unlucky-app-iced --lib m116 -- --ignored --nocapture"] +fn m116_corner_log_line_on_real_windows() { + use crate::platform::win32::corner::plan_corner; + use unlucky_presenter::prefs::WindowCorner; + + let os = crate::platform::current_windows_version(); + let plan = plan_corner(WindowCorner::System, os, crate::Backend::Gpu); + // 直接遍历 `controlled_experiment` 的**同一份**行定义（含 `product` / `product+alpha`）， + // 免得这里另抄一份样式表、跟探针悄悄分叉。 + for row in super::controlled_experiment() { + let hwnd = super::create_probe_window(row.style, row.ex_style); + if hwnd == 0 { + println!("[corner] {} window=none", row.label); + continue; + } + super::show_probe_window(hwnd); + // layered=on 的那几行（产品的 α<1 档与裸 popup 对照）按裁定 A 带 `suppressed_by=`。 + let layered = row.ex_style & 0x0008_0000 != 0; + println!( + "{}", + crate::platform::win32::corner::format_line( + row.label, + &plan, + WindowCorner::System, + &super::apply_corner(hwnd, &plan).describe(), + &super::dwm::style_summary(hwnd), + layered.then_some("window_alpha"), + ) + ); + super::destroy_probe_window(hwnd); + } + + // 设置里选「直角」时的取值（`excluded_reason` 必须变成 `user`）。 + let square = plan_corner(WindowCorner::Square, os, crate::Backend::Gpu); + println!( + "[corner] policy=square {}", + square.log_line(WindowCorner::Square) + ); +} diff --git a/crates/app-iced/src/presenter/agent.rs b/crates/app-iced/src/presenter/agent.rs new file mode 100644 index 0000000..f6dd375 --- /dev/null +++ b/crates/app-iced/src/presenter/agent.rs @@ -0,0 +1,279 @@ +//! AI 助手栏的 presenter 句柄（M119）：四个契约 + 事件队列 + 具名错误。 +//! +//! ## 它替掉的是什么 +//! +//! M104 交付的壳是**自带样本会话**的（`pages/agent/demo.rs` 的 `transcript()`，`Submit` 只往 +//! 本地数组里追加一条「没发给模型」的提示）。M119 把这些全部删掉：会话内容的唯一来源是 +//! [`Presenter::agent_rail`]，壳里的 `Submit` / `Stop` / `Confirm` / 标记已读**全部**翻成 +//! presenter 的那四个签名——**壳里一行会话状态都不留**。 +//! +//! | 壳里的动作 | 落到哪 | +//! |---|---| +//! | 输入框打字 | [`AgentHost::set_draft`] → `Presenter::agent_set_draft`（切形态不丢） | +//! | 发送 | [`AgentHost::submit`] → `Presenter::agent_submit` | +//! | 打开栏 / 停在独立页 | [`AgentHost::mark_read`] → `Presenter::agent_mark_read` | +//! | 允许/拒绝写操作 | [`AgentHost::confirm`] → `Presenter::agent_confirm` | +//! | 事件回流 | [`AgentHost::apply`] → `Presenter::apply`（唯一状态写入口） | +//! | 栏可见性 | [`AgentHost::sync_visibility`] → `Presenter::navigate` + `prefs_mut` | +//! +//! ## 为什么句柄里还要持一份队列与失败槽 +//! +//! presenter 不持有定时器，也不认识 iced（crate 文档 §4）。异步后端的事件只能落在**进程内队列** +//! 里由 UI 抽；失败原因同理（`AgentTransport::submit` 只回一个 `String`，而 UI 要按**原因码** +//! 选 i18n 文案，不能去匹配错误串）。两个 `Arc>` 就这两件东西，和 +//! [`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..3b53de0 --- /dev/null +++ b/crates/app-iced/src/probe.rs @@ -0,0 +1,226 @@ +//! 渲染后端探测 + 自动降级（D27）。 +//! +//! ## 为什么需要探测 +//! +//! iced 0.14 的 `Renderer` 本身就是「wgpu → tiny-skia」的运行时回退枚举（M60 Q1）： +//! **不设** `ICED_BACKEND` 时，拿不到 GPU 适配器会自动降级到 CPU，零代码。 +//! 需要自研的只有**判据**： +//! +//! - 本机会枚举出 `Microsoft Basic Render Driver [Cpu]`（= WARP 软光栅）， +//! 所以「有没有适配器」不能当「有没有 GPU」（M60 实测），必须看 `device_type`。 +//! - 没有硬件 GPU 时要**主动**把 CPU 放到候选首位，否则 wgpu 会先花时间尝试 WARP， +//! 观感与行为都难料。 +//! +//! ## M97 订正：判据在 [`crate::renderer::decide`]，日志不再说谎 +//! +//! 本模块只负责**探测**（`Probe::run`）和**落地**（[`apply`]）；决策表、兜底、日志格式 +//! 全部搬到了 [`crate::renderer`] 的模块文档里（那张判据表就是验收标准）。 +//! +//! 三条被删掉/改掉的东西，别再加回来： +//! +//! 1. **`ICED_BACKEND` 不再写候选列表**（`wgpu,tiny-skia` / `tiny-skia,wgpu` 这种）。 +//! 列表语义让 iced 自己回退，而它的回退是静默的：`iced_renderer-0.14.0/src/fallback.rs` +//! 把 wgpu 的错误装进 `errors` 向量，tiny-skia 一成功就整体丢弃。现在只写**一项**， +//! 起不来就必然是具名错误，由 `app::boot` 打印并重开降级。 +//! 2. **`auto` + 有硬件不再「不设变量」**。那等于把决策权交给一条我们看不见的路径。 +//! 3. **`renderer = auto (wgpu -> tiny-skia)` 这行删了**。它是按「变量未设」打出来的常量， +//! 跟实际后端无关——M97 的 macOS 报告就是被它误导的。 + +use crate::renderer::{self, Decision}; +use crate::Backend; + +/// 单个适配器的摘要（只留日志要用的字段）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct AdapterSummary { + /// 适配器名（如 `AMD Radeon RX 6600 XT`）。 + pub name: String, + /// `device_type` 的字符串形式（`DiscreteGpu` / `IntegratedGpu` / `Cpu` / …）。 + pub device_type: &'static str, +} + +/// 探测结论。 +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct Probe { + /// 枚举到的全部适配器（含 WARP 这类软光栅）。 + pub adapters: Vec, + /// 是否存在**真**硬件适配器（`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 { + "" + }; + + eprintln!( + "[probe] {} :: request={} -> ICED_BACKEND={}{note}", + probe.describe(), + request.name(), + decision.primary.env_value() + ); + eprintln!("[probe] {}", decision.describe()); + if decision.primary == renderer::Kind::Wgpu { + eprintln!( + "[probe] 取证：出现 `[gpu] iced_wgpu: …Selected: AdapterInfo…` ⇒ GPU 真生效；\ + 出现 `[gpu] wgpu 初始化失败` ⇒ 已降级 CPU" + ); + } + + decision +} + +#[cfg(feature = "gpu")] +fn run_wgpu() -> Probe { + // `iced::wgpu` 就是 wgpu crate 本身（`pub use iced_renderer::wgpu::wgpu` 再导出）， + // 所以不需要单独依赖 wgpu，版本也不会和 iced 打架。 + use iced::wgpu::{Backends, Instance, InstanceDescriptor}; + + let instance = Instance::new(&InstanceDescriptor { + backends: Backends::all(), + ..Default::default() + }); + + let adapters = instance + .enumerate_adapters(Backends::all()) + .into_iter() + .map(|adapter| { + let info = adapter.get_info(); + AdapterSummary { + name: info.name, + device_type: renderer::preflight::device_type_name(info.device_type), + } + }) + .collect::>(); + + 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..64c73b5 --- /dev/null +++ b/crates/app-iced/src/renderer/acceptance/locale.rs @@ -0,0 +1,294 @@ +//! `[env]` 与 `[i18n]`：**本机是什么**（系统 / arch / 核数 / GPU / 时区）与**为什么是这个语言**。 +//! +//! ## 语言链为什么在这里而不是 `platform/` +//! +//! `platform::locale::SystemLocale` 是 **Windows 注册表**那一路（`reg.exe`，零 FFI）。macOS 的 +//! 真值源是 `defaults read -g AppleLanguages`，而 M98 的 scope 没有 `platform/**`，所以 +//! [`AppleLanguages`] 先落在这里。**它该搬去 `platform/locale.rs`**——两处并存会漂（见交接报告）。 + +use unlucky_i18n::lang::{self, Detection, LocaleSource}; +use unlucky_presenter::settings_bridge::SettingsBridge; + +use crate::Probe; + +// ---------------------------------------------------------------- [env] + +/// `[env]`：系统 / arch / 核数 / 语言 / 时区 / 缩放请求 / GPU。 +/// +/// `gpu` 与 `hardware` **来自真实适配器枚举**（[`Probe`]），不是请求值；枚举不到就写 +/// `<无适配器>` 并把 `hardware=false` 一起打出来——「没有适配器」与「没枚举」是两件事。 +/// +/// `display=` 恒为 `needs-window`：显示器尺寸只有拿到窗口句柄才问得到，而这一行在开窗之前就打了。 +/// 真值由验收脚本用 `system_profiler SPDisplaysDataType` 采进 `logs/00-env.txt`——**写个猜的值 +/// 比留白更坏**（那会让「Monitor 4K / 无外接」这种结论变成猜测）。 +#[must_use] +pub fn env_line(probe: &Probe, language: &str, scale: Option, 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")] + { + let output = std::process::Command::new("defaults") + .args(["read", "-g", "AppleLanguages"]) + .output() + .ok()?; + if !output.status.success() { + return None; + } + parse_apple_languages(&String::from_utf8_lossy(&output.stdout)) + } + #[cfg(not(target_os = "macos"))] + { + None + } + } + + fn label(&self) -> &'static str { + "applelanguages" + } +} + +/// 解析 `defaults` 的输出，取**第一条**语言（真机格式见测试夹具）。 +/// +/// ```text +/// ( +/// "zh-Hans-CN", +/// "en-US" +/// ) +/// ``` +/// +/// 首项是用户的**首选语言**；后面几项是「语言与地区」里的备选，与本 crate「只看主语言子标签」 +/// 的口径无关。 +#[must_use] +pub fn parse_apple_languages(text: &str) -> Option { + 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..d45f9a6 --- /dev/null +++ b/crates/app-iced/src/renderer/log_bridge.rs @@ -0,0 +1,151 @@ +//! 把 `iced_wgpu` / `wgpu` 的 `log` 输出转到 stderr（判据表第 8 行的取证通道）。 +//! +//! ## 为什么需要它 +//! +//! `iced_wgpu` 在**真的**创建设备时会自己打一行： +//! +//! ```text +//! Selected: AdapterInfo { name: "Apple M1", backend: Metal, device_type: IntegratedGpu, … } +//! ``` +//! +//! 这行只有「wgpu 走到适配器那一步」才会出现，所以它是**GPU 真生效的实证**——不是我们的推断。 +//! 但它走 `log` crate，而本进程从来没装过 logger，于是 M1 那份报告里这行根本不存在： +//! 「看不到」被当成了「没有」。装一个只放行 GPU 相关 target 的 logger，成本 60 行， +//! 换来的是以后每次验收都能直接看见 wgpu 说了什么。 +//! +//! ## 过滤 +//! +//! 按 **target 分级**，不是一刀切：`wgpu_hal` / `wgpu_core` 在 Info 级别会刷出上百行 Vulkan +//! loader 噪声（M97 实测：启动时 90 行 registry 扫描），把真正有用的 +//! `iced_wgpu: Selected: AdapterInfo{…}` 埋掉。 +//! +//! | `ULL_GPU_LOG` | `iced_wgpu*` | `wgpu*`（hal / core） | 用途 | +//! |---|---|---|---| +//! | 未设 / `info` | Info | **Warn** | 默认：看得见选中的适配器/格式 + wgpu 的告警 | +//! | `warn` | Warn | Warn | 只留告警（启动日志最干净） | +//! | `debug` | Debug | Debug | 全量（诊断用；含 Vulkan loader 噪声） | +//! | `off` | — | — | 不装 logger（回到 M97 之前，仅用于对照实验） | +//! +//! 其它 target（`winit`、`iced_winit` …）一律不放行：它们只会把启动日志淹掉。 + +use std::sync::Once; + +/// 装 logger（进程内只生效一次；重复调用无害）。 +pub fn install() { + static ONCE: Once = Once::new(); + ONCE.call_once(|| { + let Some(level) = level_from_env() else { + return; + }; + // `set_boxed_logger` 只能成功一次；已被别人装过就安静让位，不 panic。 + if log::set_boxed_logger(Box::new(Bridge { level })).is_ok() { + log::set_max_level(level); + } + }); +} + +/// `ULL_GPU_LOG` → 过滤级别；`None` = 别装（`off`）。 +fn level_from_env() -> Option { + 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', " "); + eprintln!("[gpu] {}: {}", record.target(), message.trim_end()); + } + + fn flush(&self) {} +} + +/// `iced_wgpu::window::compositor` / `wgpu_core::…` / `wgpu_hal::…` 都算。 +fn is_gpu_target(target: &str) -> bool { + ["iced_wgpu", "wgpu"] + .iter() + .any(|prefix| target.starts_with(prefix)) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn only_gpu_targets_pass() { + assert!(is_gpu_target("iced_wgpu::window::compositor")); + assert!(is_gpu_target("wgpu_core::instance")); + assert!(is_gpu_target("wgpu_hal::metal")); + assert!(!is_gpu_target("iced_winit::lib")); + assert!(!is_gpu_target("winit::event_loop")); + } + + #[test] + fn level_env_values_are_interpreted() { + assert_eq!(parse_level(""), Some(log::LevelFilter::Info)); + assert_eq!(parse_level("info"), Some(log::LevelFilter::Info)); + assert_eq!(parse_level(" WARN "), Some(log::LevelFilter::Warn)); + assert_eq!(parse_level("off"), None); + assert_eq!(parse_level("0"), None); + } + + /// 默认档（`info`）下 `wgpu_hal`/`wgpu_core` 被压到 Warn：它们是 Vulkan loader 原文， + /// M97 实测一屏 90 行噪声，会把 `Selected: AdapterInfo` 埋掉。 + #[test] + fn default_level_mutes_wgpu_noise_but_keeps_adapter_line() { + use log::LevelFilter; + assert_eq!( + target_level(LevelFilter::Info, "iced_wgpu::window::compositor"), + LevelFilter::Info, + "选中适配器那行必须留" + ); + assert_eq!( + target_level(LevelFilter::Info, "wgpu_hal::vulkan::instance"), + LevelFilter::Warn, + "Vulkan loader 噪声必须压掉" + ); + assert_eq!( + target_level(LevelFilter::Info, "wgpu_core::instance"), + LevelFilter::Warn + ); + // 显式要 debug 时全放行（诊断用）。 + assert_eq!( + target_level(LevelFilter::Debug, "wgpu_hal::vulkan::instance"), + LevelFilter::Debug + ); + } +} diff --git a/crates/app-iced/src/renderer/mod.rs b/crates/app-iced/src/renderer/mod.rs new file mode 100644 index 0000000..90ea616 --- /dev/null +++ b/crates/app-iced/src/renderer/mod.rs @@ -0,0 +1,249 @@ +//! 渲染后端的**判据表**（M97）+ 三段可观测性基建。 +//! +//! 本模块回答一个问题：**这个进程到底跑在哪个渲染器上，凭什么这么断定。** +//! +//! ## 判据表（验收直接对照这张表） +//! +//! `ICED_BACKEND` **永远是单项**（不是候选列表）。理由见下节「为什么不再用候选列表」： +//! 单项 ⇒ 「跑起来了 ⇒ 就是它」，不存在需要事后猜的空间。`兜底` 列是**本 crate 自己的重试**， +//! 不是 iced 的回退，所以它一定伴随一行具名错误日志。 +//! +//! | # | 条件 | 选哪个 | 日志该打印什么 | 谁能验证 | +//! |---|---|---|---|---| +//! | 1 | `--renderer=cpu` / `--software-renderer` | `tiny-skia` | `renderer = tiny-skia reason=forced-cpu` | 三平台（CI 只用这条） | +//! | 2 | `--renderer=gpu` 但本构建没编 wgpu | `tiny-skia` | `reason=gpu-not-compiled` + `；本构建未编入 wgpu` | 三平台（`--no-default-features`） | +//! | 3 | `--renderer=gpu` 且编了 wgpu | `wgpu`，兜底 `tiny-skia` | `renderer = wgpu reason=forced-gpu 兜底=tiny-skia` | Windows / Linux 本机；macOS 需真机 | +//! | 4 | `--renderer=auto` 但没编 wgpu | `tiny-skia` | `reason=auto-gpu-not-compiled` | 三平台（`--no-default-features`） | +//! | 5 | `auto` + 枚举不到硬件适配器（只有 WARP / llvmpipe） | `tiny-skia`，兜底 `wgpu` | `reason=auto-no-hardware-adapter` | Windows 本机（软渲染 VM） | +//! | 6 | `auto` + 有硬件适配器 | `wgpu`，兜底 `tiny-skia` | `reason=auto-hardware-adapter` | Windows 本机 **√**；macOS 需真机 | +//! | 7 | 同上但 `ULL_PREFLIGHT=1` 预检失败 | `tiny-skia`，兜底 `wgpu` | `[gpu-preflight] FAILED stage=… error=…` + `reason=preflight-failed` | 三平台（可用 `WGPU_BACKEND=gl` 造） | +//! | 8 | 任何一行选了 wgpu，但 iced 真初始化失败，且**交互启动**（无 `--screenshot`） | 具名错误 → **换一个进程**重开 `tiny-skia` | `[gpu] wgpu 初始化失败（具名）：…` → `[gpu] 降级 → tiny-skia（…换一个进程重开…）` → 子进程 `[probe] 本次是降级重开（ULL_GPU_FALLBACK=tiny-skia）` | **Windows 已验**（`WGPU_BACKEND=metal` 造）；macOS 需真机 | +//! | 9 | 同上行，但**取证启动**（带 `--screenshot`，含 `--screen=gallery`） | 具名错误 → **不出图**，退出码 1 | `[gpu] wgpu 初始化失败（具名）：…` → `[gpu] 拒绝降级出图：本次是取证启动（--screenshot …）` | **Windows 已验**（同造法）；macOS 需真机 | +//! +//! **第 8/9 行的硬规则（M97 定）**： +//! +//! - 取证工具（`--screenshot`）宁可红着退出，也不能悄悄换一种后端继续出图。以前 gallery 在 +//! wgpu 挂掉时会静默降级到 tiny-skia 照样落 PNG，而报告上写的是「GPU 渲染截图」——所有视觉 +//! 结论的可信度都被悄悄打折，而且从输出上看不出来。现在每张图的日志里都带 +//! **实际**后端名（`[shot] … renderer=wgpu`），图能自证来源。 +//! - 交互启动保留安全网：真无 GPU / wgpu 起不来时降级到 tiny-skia，不崩。 +//! +//! **降级为什么是换进程**：第一版写的是「打印错误 → 在本进程里再 `run()` 一次」，Windows 实测 +//! 直接 panic（`iced_winit-0.14.1/src/lib.rs:81` → `Create event loop: RecreationAttempt`）—— +//! winit 不允许一个进程建两次事件循环。所以安全网是 `respawn`：起一个子进程、只换 +//! `ICED_BACKEND` + `ULL_GPU_FALLBACK`，然后带着子进程的退出码退出。子进程看到 +//! `ULL_GPU_FALLBACK` 就跳过探测（否则会得到同一个结论、无限重开）。 +//! +//! `ULL_PREFLIGHT` 开关的代价（**实测**，不是估计）：Windows RX 6600 XT / Vulkan 上 +//! `took=717ms`（首次要扫一遍 Vulkan loader），不可用时 `took=0ms`。打开它等于启动多 ~0.7 s， +//! 所以默认关。它测不了 `create_surface`（那时还没有窗口），代替不了真跑一次，只用来「开窗前拿原因」。 +//! 注意：`ULL_PREFLIGHT=1` + 预检失败 + `--screenshot` 时**仍会**降级出图（`reason=preflight-failed`， +//! 图上是 `renderer=tiny-skia`）——那条路径不是静默的，但图确实是 CPU 的，读图前先读日志。 +//! +//! ## 怎么从日志判断「有没有静默降级」 +//! +//! | 你看到 | 结论 | +//! |---|---| +//! | `[probe] renderer = wgpu` 且之后有 `[gpu] iced_wgpu: …Selected: AdapterInfo…` | **真在走 GPU**（这行是 iced_wgpu 自己在创建设备时打的，不是我们的猜测） | +//! | `[gpu] wgpu 初始化失败（具名）：…` | wgpu 起不来，**原因就在这行里**；交互启动已换进程降级 CPU，取证启动已拒绝出图 | +//! | `[gpu] 拒绝降级出图：…` | 这张图**没有**产出（取证启动 + wgpu 起不来）。想用 CPU 出图请显式 `--renderer=cpu` | +//! | `[gpu] 降级 → tiny-skia（…换一个进程重开…）` | 交互启动降级了；后面必然跟一行 `[probe] 本次是降级重开` | +//! | `[probe] renderer = tiny-skia reason=…`（`reason` 不是 `forced-cpu`） | 探测判定不该上 GPU，**原因在 `reason`** | +//! | `[shot] … renderer=wgpu` / `renderer=tiny-skia` | 这张图**实际**由哪个后端产出（M97 之前这里打的是请求值 `auto`，等于没打） | +//! | 只有 `[probe] renderer = …` 一行、没有 `[gpu] iced_wgpu:` 也没有取证行 | 那是 M97 之前的旧日志——**它从来没观测过实际后端**，不可采信 | +//! +//! ## 为什么不再用候选列表（M97 的根因订正） +//! +//! M97 之前：`auto` + 有硬件 → **不设** `ICED_BACKEND`，把决策交给 iced 的 +//! `fallback::Compositor`；那条路径里 wgpu 的失败被 `errors` 向量装起来、tiny-skia 一成功就整体丢弃 +//! （`iced_renderer-0.14.0/src/fallback.rs`，我们改不了）。日志只剩 `renderer = auto (wgpu -> tiny-skia)` +//! ——而这行是 `probe.rs` 里按 `env == None` 打出来的**常量字符串**，跟实际后端无关。 +//! 于是 macOS M1 上「枚举到 Apple M1」与「最终是不是真在用 GPU」彻底脱钩：**看起来正常但可能在跑 CPU**。 +//! +//! 现在的唯一判据：`ICED_BACKEND` 只写一项 ⇒ 能跑起来就必定是它；起不来就必然是 +//! `iced::Error::GraphicsCreationFailed` 里那串具名错误（哪个 backend、reason 是什么）， +//! 由 `app/boot.rs` 打印后决定「换进程降级」还是「拒绝出图」。 +//! +//! ## 四段基建 +//! +//! | 模块 | 作用 | 默认 | +//! |---|---|---| +//! | [`preflight`] | 在 iced 之前自己跑一遍 wgpu 的「实例→适配器→设备」，把失败原因拿在手里 | **关**（`ULL_PREFLIGHT=1` 打开；会重复创建实例/设备，别放默认路径） | +//! | [`log_bridge`] | 把 `iced_wgpu` / `wgpu` 的 `log` 输出转到 stderr（`Selected: AdapterInfo{…}` 这行就是 GPU 生效的实证） | 开（`ULL_GPU_LOG=off` 可关） | +//! | [`acceptance`] | **验收诊断（M98）**：`[env]` `[backend]` `[window]` `[font] chain` `[theme]` `[perf]` `[i18n]` `[caps]` 八类里本 crate 能观测的那部分，固定前缀、单行可 grep | 便宜的行恒开；贵的（适配器枚举）由 `ULL_ACCEPTANCE=1` 打开 | +//! +//! ### 「单项 ⇒ 没有静默回退」这条推理的依据（M98 r1 复审挖到源码层） +//! +//! `iced_renderer` 的 `fallback::Compositor` 拿到 `ICED_BACKEND` 后**仍会把每个候选依次拿去试 +//! wgpu 和 tiny-skia**，两个子渲染器收同一个 backend 字符串，所以「单项」本身并不阻止它去试 +//! tiny-skia。真正挡住它的是 `iced_tiny_skia` 的 `with_backend`：它只接受 +//! `None | "tiny-skia" | "tiny_skia"`，`Some("wgpu")` 直接返回 `GraphicsAdapterNotFound`。 +//! 于是 `ICED_BACKEND=wgpu` 这条路**不可能**落到 tiny-skia：起不来就两项都失败、返回 +//! `GraphicsCreationFailed`（判据表第 8/9 行接住它）。 +//! +//! 这条依赖 iced 的实现细节，所以：① `iced = "=0.14.0"` 精确钉版本；② 验收脚本另有 +//! `[gpu] …Selected: AdapterInfo` 这条**不依赖本 crate 推理**的实证断言。升级 iced 时这两条都要重看。 +//! +//! **本模块自己只回答「判据」**；「结果」由三处分别取证，别混：① `[backend] final=`（本 crate 的 +//! 起步结果，判据是单项 `ICED_BACKEND`）；② `[gpu] iced_wgpu: …Selected:`（iced 自己打的， +//! GPU 真生效的实证）；③ `[shot] … renderer=`（这张图是哪个后端出的）。 +//! +//! ## 真机验收（macOS Metal 路径 —— **需真机复核**，Windows 验不了这一段） +//! +//! 判据表第 3/6/8/9 行的 macOS 分支只能真机验。下面每段都可直接粘贴；`# 期望` 后面是**必须能在 +//! stderr 里 grep 到的原文**（M98 的验收包会直接把这些字符串编成断言）。 +//! +//! ```bash +//! # 0) 一次 +//! cargo build -p unlucky-app-iced +//! +//! # 1) 交互启动：这才是判「M1 到底有没有在用 GPU」的那次。看完关窗即可。 +//! ./target/debug/unlucky-launcher-iced --renderer=auto +//! # 期望（这两行同一次运行里都要有）： +//! # [probe] renderer = wgpu reason=auto-hardware-adapter 兜底=tiny-skia +//! # [gpu] iced_wgpu::window::compositor: Selected: AdapterInfo { name: "Apple M1", +//! # 上面第二行里的 backend 必须是 Metal（同一行靠后）。 +//! # 若出现下面任一行 ⇒ 这次**不是** GPU，把那段原文（含上一行）发回来： +//! # [gpu] wgpu 初始化失败（具名）： +//! # [gpu] 降级 → tiny-skia +//! # [probe] 本次是降级重开（ULL_GPU_FALLBACK=tiny-skia） +//! +//! # 2) 开窗前拿原因（不建窗；多花 ~0.7 s） +//! ULL_PREFLIGHT=1 ./target/debug/unlucky-launcher-iced --renderer=auto +//! # 期望：[gpu-preflight] ok adapter="Apple M1" type=IntegratedGpu backend=Metal took= +//! +//! # 3) 取证出图（D30 通道；这一张图自证来源） +//! ./target/debug/unlucky-launcher-iced --screen=gallery --screenshot /tmp/gallery.png +//! # 期望（三行都该有）： +//! # [gpu] iced_wgpu::window::compositor: Selected: AdapterInfo { name: "Apple M1", +//! # [shot] 1180x760 scale=1 -> /tmp/gallery.png +//! # [shot] screen=gallery theme=light renderer=wgpu +//! # 若 wgpu 起不来 ⇒ 没有 /tmp/gallery.png、退出码 1、且打印 [gpu] 拒绝降级出图： +//! +//! # 4) 强制 CPU 对照（必须与 M97 之前逐字一致） +//! ./target/debug/unlucky-launcher-iced --renderer=cpu --screenshot /tmp/cpu.png +//! # 期望： +//! # [probe] adapters=0 hardware=false :: request=cpu -> ICED_BACKEND=tiny-skia +//! # [probe] renderer = tiny-skia reason=forced-cpu 兜底=none（候选表唯一项） +//! # [shot] screen=shell theme=light renderer=tiny-skia +//! +//! # 5) 负例：取证启动遇到 wgpu 不可用时必须红着退出（Mac 上用一个不存在的后端来造） +//! WGPU_BACKEND=dx12 ./target/debug/unlucky-launcher-iced --screen=gallery --screenshot /tmp/bad.png +//! # 期望：**没有** /tmp/bad.png、退出码 1、并且打印： +//! # [gpu] wgpu 初始化失败（具名）：multiple errors occurred: [GraphicsAdapterNotFound { backend: "wgpu", reason: RequestFailed("no adapter was found for the options requested: +//! # [gpu] 拒绝降级出图：本次是取证启动（--screenshot /tmp/bad.png），换后端出的图会撒谎。 +//! ``` +//! +//! 第 5 段在 Windows 上已用同构的 `WGPU_BACKEND=metal` 验过（`metal support not compiled in` +//! → 具名错误 → 拒绝出图 → exit 1）；macOS 上要确认打印的是 `dx12 support not compiled in` 那类 +//! wgpu 原话，而不是我们自己的话。 + +pub mod acceptance; +pub mod decision; +pub mod log_bridge; +pub mod preflight; + +pub use decision::{decide, demote_after_preflight, fallback_round, strict, Decision, Kind}; + +/// 把 `iced::Error` 里的**具名**图形错误掏出来（`Display` 那句笼统的话不算原因）。 +/// +/// `iced::Error::GraphicsCreationFailed(inner)` 的 `Display` 只有 +/// 「the application graphics context could not be created」，**没有** `{0}`； +/// 真正的 backend 名与 `Reason` 在内层 `graphics::Error` 里。所以这里同时给 Display 与 Debug。 +#[must_use] +pub fn named_graphics_error(error: &iced::Error) -> Option { + 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}`）， +/// 所以这里必须显式把内层错误打出来，否则又变回「只知道失败，不知道为什么」。 +pub fn report_failure(backend: Kind, error: &(impl std::fmt::Display + std::fmt::Debug)) { + eprintln!("[gpu] {} 初始化失败（具名）：{error}", backend.name()); + eprintln!("[gpu] 失败详情（具名）：{error:?}"); +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::{Backend, Probe}; + + /// `run_once` **必须**把决策里的起步后端传下去。 + /// + /// 抓得住：`run_once` 被改成传死值（例如恒 `Kind::Wgpu`）——那会让「强制 CPU」也去试 GPU。 + /// 抓不住：真 iced 启动成功/失败（那条只能真跑，见判据表第 6/8/9 行的实测记录）。 + #[test] + fn run_once_passes_the_decision_primary() { + for request in [Backend::Cpu, Backend::Gpu] { + let decision = decide(request, &Probe::default(), true); + let mut seen = None; + let result = run_once(decision, |kind| { + seen = Some(kind); + Ok(()) + }); + assert!(result.is_ok(), "闭包返回 Ok 时 run_once 必须原样返回"); + assert_eq!( + seen, + Some(decision.primary), + "run_once 传给 iced 的后端必须是决策里的起步项" + ); + } + } + + /// `run_once` 只跑一次：失败也**不**在进程内重试（winit 只允许建一次事件循环）。 + /// + /// 抓得住：谁把「进程内重试」加回 `run_once`（会 panic：`RecreationAttempt`）。 + /// 抓不住：`respawn` 那条换进程的路（见 `app::boot::tests`）。 + #[test] + fn run_once_never_retries_in_process() { + let mut calls = 0; + let _ = run_once(decide(Backend::Gpu, &Probe::default(), true), |_| { + calls += 1; + Err(iced::Error::WindowCreationFailed(Box::new( + std::io::Error::other("测试用"), + ))) + }); + assert_eq!(calls, 1, "进程内只许跑一次；重试只能换进程"); + } +} diff --git a/crates/app-iced/src/renderer/preflight.rs b/crates/app-iced/src/renderer/preflight.rs new file mode 100644 index 0000000..ff6b101 --- /dev/null +++ b/crates/app-iced/src/renderer/preflight.rs @@ -0,0 +1,244 @@ +//! wgpu 自检（判据表第 7 行）：在把控制权交给 iced **之前**自己跑一遍 +//! 「实例 → 适配器 → 设备」，把 wgpu 的具名错误拿在手里。 +//! +//! ## 为什么默认关 +//! +//! 它会**重复** iced 马上要做的活（再建一个实例、再要一个设备），macOS 上一个 Metal 设备 +//! 不是免费的；而且它测不了 `create_surface`（那时还没有窗口），所以它**代替不了**真跑一次。 +//! 它的价值只有一个：让「不上 GPU」这个结论在**开窗之前**就有原因，验收时不用盯着一个闪窗猜。 +//! +//! 开关：`ULL_PREFLIGHT=1`（判据表里登记过，不是隐藏口子）。 +//! +//! ## 它镜像的是谁 +//! +//! 逐字对着 `iced_wgpu-0.14.0/src/window/compositor.rs` 的 `Compositor::request()` 抄的： +//! `Backends::from_env().unwrap_or(all)`、`PowerPreference::from_env().unwrap_or(HighPerformance)`、 +//! `Limits { max_bind_groups: 2, max_non_sampler_bindings: 2048, ..default }`。 +//! 差一处都会让预检和真实路径说不同的话，那时预检就不是证据而是噪声了。 + +/// 预检开关的环境变量名（`1` / `true` 打开）。 +pub const ENV_SWITCH: &str = "ULL_PREFLIGHT"; + +/// 预检成功：拿到的适配器摘要。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Verdict { + /// 适配器名（`Apple M1` / `AMD Radeon RX 6600 XT` / `Microsoft Basic Render Driver`）。 + pub adapter: String, + /// `device_type` 的字符串形式。 + pub device_type: &'static str, + /// 命中哪个 wgpu 后端（`Metal` / `Vulkan` / `Dx12` / `Gl`）。 + pub backend: String, +} + +impl Verdict { + /// 一行日志。 + #[must_use] + pub fn describe(&self) -> String { + format!( + "ok adapter={:?} type={} backend={}", + self.adapter, self.device_type, self.backend + ) + } +} + +/// 预检失败：卡在哪一步 + wgpu 自己的错误文本。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Failure { + /// 失败阶段（日志里 `stage=` 的取值）。 + pub stage: &'static str, + /// wgpu 具名错误（`Display`，原样保留，不翻译成「失败」）。 + pub detail: String, +} + +impl Failure { + /// 一行日志（`stage=` 可直接 grep）。 + #[must_use] + pub fn describe(&self) -> String { + format!("FAILED stage={} error={}", self.stage, self.detail) + } +} + +/// 用户是否要求预检。 +#[must_use] +pub fn requested() -> bool { + std::env::var(ENV_SWITCH).is_ok_and(|value| matches!(value.trim(), "1" | "true" | "yes" | "on")) +} + +/// 按 `ULL_PREFLIGHT` 决定跑不跑；跑了就顺手把结论打进 stderr（带耗时，别让开关成本变成传说）。 +/// +/// 返回 `None` = 没要求预检（调用方按判据表 1~6 行原样走）。 +#[must_use] +pub fn run_if_requested() -> Option> { + if !requested() { + return None; + } + + let started = std::time::Instant::now(); + let verdict = run(); + let took = started.elapsed().as_secs_f64() * 1000.0; + match &verdict { + Ok(ok) => eprintln!("[gpu-preflight] {} took={took:.0}ms", ok.describe()), + Err(failure) => { + eprintln!("[gpu-preflight] {} took={took:.0}ms", failure.describe()); + } + } + Some(verdict) +} + +#[cfg(feature = "gpu")] +/// 真跑一遍 wgpu 初始化（不开窗、不建 surface）。 +/// +/// # Errors +/// 无适配器 / 设备请求被拒时返回 [`Failure`]，`detail` 是 wgpu 的原话。 +pub fn run() -> Result { + 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..e726fc0 --- /dev/null +++ b/crates/app-iced/src/shell/mod.rs @@ -0,0 +1,357 @@ +//! 首屏骨架（**不做业务**）：自绘标题栏 + 左侧导航轨 + 内容区 + **右侧 AI 助手栏**（M104）。 +//! +//! ## 与参考判据的对应（`research/12b-component-fidelity.md`） +//! +//! | 部件 | 参考 | 令牌落点 | +//! |---|---|---| +//! | 标题栏高度 | 16.2 桌面标题栏 **40**（登记偏离） | `LM.titlebar_height = 48`（M63 §1.4/R13 桌面档，令牌优先） | +//! | 标题栏按钮 | 16.5 官方图标 **24** → 本项目 **20**（M86 项目偏离，用户点名「图标稍大」） | `icons::CAPTION_PX`（令牌 `TITLEBAR_CAPTION_ICON_PX`）+ `LM.titlebar_button_width = 46` | +//! | 页头 | 16.1 官方 AppBar **64**；本项目 **56** | `LM.page_header_height = 56`（已有偏离登记） | +//! | 卡片 | 3.x Outlined：**Medium(12)**、L0、`OutlineVariant` 1px、`SurfaceContainerLow` | `Component::OutlinedCard.spec()` + `STROKE_PX` | +//! | 字级 | 16.4 标题 `TitleLarge`；卡片 `TitleMedium` / `BodySmall` | `Ui::style` / `Ui::emphasized` | +//! +//! 导航轨在 [`nav`] 子模块里（12b §5 的判据表也在那边）。 +//! +//! 一屏只出现 4 档字号（22 / 16 / 14 / 12），且**没有实心 accent**（rubric K2：一屏最多一个实心 +//! Primary，骨架期一个都不要）。阴影只给浮层，骨架里没有浮层，所以**全屏零阴影**（rubric K3）。 + +mod nav; + +/// AI 助手栏与 AI 独立页（M104）：**物理目录是 `crates/app-iced/src/pages/agent/`**， +/// 用 `#[path]` 挂到外壳的命名空间。 +/// +/// 为什么是 `#[path]` 而不是在 `pages/mod.rs` 加一行 `mod agent;`：`pages/mod.rs` 是四条页面线 +/// 共用的声明文件（M104 的 scope 没给它），而右栏是**外壳的一部分**（它挂在任何页面右边）。 +/// 先例是 `app/mod.rs` 挂 `../components/mod.rs`。物理路径只有一份，逻辑名字有两个用途： +/// 宿主（右栏）归外壳，视图（会话组件）归页面目录。 +#[path = "../pages/agent/mod.rs"] +pub(crate) mod agent; + +// M114：轨底账户头像位的状态也归外壳（`NavItem` + `RailAccount` 一起导出）。 +pub use nav::{NavItem, RailAccount}; + +use iced::widget::text::LineHeight; +use iced::widget::{button, column, container, mouse_area, row, space, stack, text}; +use iced::{mouse, Alignment, Background, Border, Color, Element, Length, Padding, Pixels, Shadow}; +use iced::{window::Direction, Theme as IcedTheme}; + +use unlucky_design::color::{Role, StateLayer}; +use unlucky_design::elevation::MaterialLayer; +use unlucky_design::icons::IconKind; +use unlucky_design::spacing::Space; +use unlucky_design::typography::TypeRole; + +use unlucky_i18n::Lang; + +use crate::app::Message; +use crate::cli::ForcedState; +use crate::icons; +use crate::theme::Ui; + +/// 导航轨的一帧状态（M114）：主序列高亮项 + 轨底账户头像位。 +/// +/// 绑成一个结构体是为了让 [`view_with_account`] 的参数停在 8 个以内（clippy `too_many_arguments`）， +/// 也把「这两个值永远一起传」这件事写进类型：谁加导航项都绕不开轨底那一格。 +pub struct NavRail { + /// 高亮哪个主序列项（账户页是 `NavItem::Account`） + pub selected: NavItem, + /// 轨底头像位的状态（**按值持有**：它是每帧现算的，引用会让整棵树的生存期挂到临时值上） + pub account: nav::RailAccount, +} + +/// 整棵树（**内容槽位版**）：外壳画标题栏 / 缩放热区 / 导航轨 / 右栏，中间那块交给调用方。 +/// +/// 产品页的唯一入口（M90 r2 / P1-1；M104 起多两样东西：右侧助手栏与拖拽取指针层； +/// M114 起导航轨还会画轨底的账户头像位）。 +/// +/// 分工写死： +/// +/// - 本模块负责：标题栏（拖动面 = **整条 48px 栏里从窗口左缘到第一个 caption** 的 `mouse_area`， +/// 没有单独的 8px 热区；三个 caption 键各 46×48）、东/南两条缩放热区（各 `Space::X1` = 4px）、 +/// 导航轨、右栏、根容器底色； +/// - 调用方负责：`content`（页面内容区）。它拿到的可用宽度是 `窗口宽 − rail 88 − 右栏`， +/// 而页面自己的 `layout::frame_metrics` 仍以**中栏可用宽**为输入（M104 的 `content_width`）。 +/// +/// 面板 α（D36 / M93）不从这里传：它是**表面色**的属性，唯一施加点是 `Ui::layer` +/// （`crate::theme`）。外壳的根容器 / 标题栏 / 导航轨都走 `ui.layer(..)`，因此自动同源。 +/// +/// 产品页入口：**内容槽位 + 背景层 + 右栏 + 拖拽层 + 轨底账户头像位**。 +/// +/// `background` 由 `pages::appearance::layer` 产出（已与 `Message::Page` 映射过）；垫在 `stack!` +/// 最底层，于是「面板 α < 1」时能真的看见它——这就是 D34 在像素上的落点。 +// 9 个形参：M104 的 `right`/`overlay`、M106 的 `lang`（导航轨标签按语言取词）， +// 加上 M114 把「高亮项 + 轨底账户态」捆成的 `NavRail`（捆它是为了少一个形参）。 +// 再拆就得动 `app/view.rs` / `account_page.rs` 的调用点，而那正是 M104/M105/M109 反复设锚点的 +// 地方——先就地 `allow`（主线原本也在这条上 `allow`），等下次合流再结构体化。 +#[allow(clippy::too_many_arguments)] +pub fn view_with_account<'a>( + ui: &'a Ui, + nav_state: NavRail, + app_title: &'a str, + background: Option>, + 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..4d512db --- /dev/null +++ b/crates/app-iced/src/theme.rs @@ -0,0 +1,400 @@ +//! 令牌 → iced 类型（`Color` / `Font` / `Border` / `Radius` / `Theme`）。 +//! +//! 本模块是**唯一**允许把 `unlucky-design` 的值翻成 iced 类型的地方（M61 §0）：组件层只调 +//! [`Ui`]，绝不出现色值/字号/半径/间距字面量（`tests/no_hardcoded_tokens.rs` 扫 `src/**`）。 +//! +//! ## 为什么不用 `iced::theme::Base` 承载 49 个角色 +//! +//! iced 的 `Palette` 只有 6 色，M3 有 49 个角色（M60 Q5）：真源是本模块的 [`Scheme`]，`Theme` +//! 只用来「换名字」（名字变了 iced 才重算缓存），控件外观由各自的 `Style` 注入。 +//! `success`/`warning` 没有对应角色，按邻近语义映射（→ `Secondary` / `Tertiary`），不许读。 + +use iced::border::Radius; +use iced::theme::Palette; +use iced::{Border, Color, Font, Theme}; + +use unlucky_design::color::{Role, Scheme, SchemeFlavor, StateLayer}; +use unlucky_design::elevation::MaterialLayer; +use unlucky_design::shape::ShapeScale; +use unlucky_design::spacing::{LayoutMetrics, Space}; +use unlucky_design::typography::{FontFamily, Platform, TypeRole, TypeStyle, Weight}; + +/// 全站描边宽度（rubric G7：1px）。令牌层的 `stroke::HAIRLINE` 是唯一定义点，这里只再导出。 +pub use unlucky_design::stroke::HAIRLINE as STROKE_PX; + +/// 已经解析到系统的字体族名（`&'static str` 才能塞进 `iced::Font`）。 +/// +/// 由 `fonts` 模块按令牌栈 + 系统字体库求值，本模块只消费。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct Families { + /// 正文族（`FontFamily::Text` 栈里第一个装机可用的）。 + pub text: &'static str, + /// 展示族（`FontFamily::Display`）。 + pub display: &'static str, + /// 等宽族（`FontFamily::Mono`，日志/版本号用）。 + pub mono: &'static str, +} + +/// 令牌求值器：一个 `Ui` 对应一套主题（浅或深）。热切 = 重建 `Ui` 并整树重绘， +/// 控件里不要缓存颜色。 +#[derive(Debug, Clone)] +pub struct Ui { + scheme: Scheme, + platform: Platform, + metrics: LayoutMetrics, + families: Families, + /// 面板层不透明度（D36 / M93）：**唯一的 α 来源**，由 [`Ui::layer`] 统一施加。 + panel_alpha: f32, +} + +impl Ui { + /// 按平台（由 `cfg!` 决定）与令牌基线方案求值。 + pub fn new(flavor: SchemeFlavor, families: Families) -> Self { + Self::with_platform(flavor, Platform::current(), families) + } + + /// 显式指定平台（跨平台核对与测试用）。 + pub fn with_platform(flavor: SchemeFlavor, platform: Platform, families: Families) -> Self { + Self { + scheme: Scheme::baseline(flavor), + platform, + metrics: LayoutMetrics::DESKTOP, + families, + panel_alpha: 1.0, + } + } + + /// 当前深浅。 + pub fn flavor(&self) -> SchemeFlavor { + self.scheme.flavor() + } + + /// 用**已解析的方案**构造求值器（D38：背景图 / 壁纸取色 → 49 个角色换掉 baseline）。 + /// + /// 追加式入口：`new` / `with_platform` 的行为一字未动（默认仍是 [`Scheme::baseline`]）； + /// 平台与骨架尺寸仍按当前环境求值——方案只带颜色。 + pub fn from_scheme(scheme: Scheme, families: Families) -> Self { + Self { + scheme, + platform: Platform::current(), + metrics: LayoutMetrics::DESKTOP, + families, + panel_alpha: 1.0, + } + } + + /// 当前平台（决定字体族与字重降级）。 + pub fn platform(&self) -> Platform { + self.platform + } + + /// 骨架尺寸（标题栏/导航/行高…）。 + pub fn metrics(&self) -> LayoutMetrics { + self.metrics + } + + /// 已解析的字体族名。 + pub fn families(&self) -> Families { + self.families + } + + /// 间距档位（4px 栅格）。 + pub fn space(&self, space: Space) -> f32 { + space.dp() + } + + /// M3 角色 → iced 颜色。 + pub fn color(&self, role: Role) -> Color { + to_iced(self.scheme.get(role)) + } + + /// 材质层（Canvas/Card/Overlay）→ 容器色；**只有令牌允许半透明的层才乘面板 α**（M93 唯一来源）。 + /// + /// α 乘在这里而不是调用点：所有表面色都从这里出去（根容器/标题栏/导航轨/页头带/卡片）， + /// 一次同源、调用点无从「各自自乘」。Canvas 层恒不透明（r1 P2-2）：令牌 + /// [`MaterialLayer::allows_translucency`] 写死 `Canvas => false`（窗口底），而三个窗口键与 + /// 导航轨、页头带都取 Canvas——给它们乘 α 会让文字直接压在背景照片上（α=0.55 实测不可读）。 + pub fn layer(&self, layer: MaterialLayer) -> Color { + let base = self.color(layer.surface_role()); + if layer.allows_translucency() { + base.scale_alpha(self.panel_alpha) + } else { + base + } + } + + /// 当前面板 α（CPU 档由 `app` 侧强制成 1.0）。 + pub fn panel_alpha(&self) -> f32 { + self.panel_alpha + } + + /// 换一个面板 α（只影响 `layer()` 出的表面色，不动角色色 `color()`；默认 `1.0`）。 + #[must_use] + pub fn with_panel_alpha(mut self, alpha: f32) -> Self { + self.panel_alpha = if alpha.is_finite() { + alpha.clamp(0.0, 1.0) + } else { + 1.0 + }; + self + } + + /// 状态层叠在容器色上，返回**不透明**结果（D27：GPU/CPU 两档状态色逐像素一致； + /// 只有材质/面板才允许两档不同）。 + pub fn state_over(&self, state: StateLayer, content: Role, container: Role) -> Color { + to_iced(state.over(self.scheme.get(content), self.scheme.get(container))) + } + + /// 圆角（`side` = 控件在该轴上的边长，`Full` 要按它折算）。 + pub fn radius(&self, shape: ShapeScale, side: f32) -> Radius { + Radius::new(shape.radius_px(side)) + } + + /// 固定档圆角。`ShapeScale::Full` 必须走 [`Ui::radius`]（它没有绝对值）。 + pub fn radius_dp(&self, shape: ShapeScale) -> Radius { + debug_assert!( + !matches!(shape, ShapeScale::Full), + "Full 需要边长，请用 Ui::radius(shape, side)" + ); + Radius::new(if matches!(shape, ShapeScale::Full) { + 0.0 + } else { + shape.dp() + }) + } + + /// 描边：`OutlineVariant` + [`STROKE_PX`]，圆角走刻度（固定档）。 + pub fn outlined(&self, shape: ShapeScale) -> Border { + Border { + color: self.color(Role::OutlineVariant), + width: STROKE_PX, + radius: self.radius_dp(shape), + } + } + + /// baseline 排版档。 + pub fn style(&self, role: TypeRole) -> TypeStyle { + role.style() + } + + /// Expressive 强调档（官方值：字重升到 500/700）。 + pub fn emphasized(&self, role: TypeRole) -> TypeStyle { + role.emphasized() + } + + /// 排版档 → iced 字体（族 + 字重）。 + pub fn font_of(&self, style: TypeStyle) -> Font { + let family = match style.family { + FontFamily::Display => self.families.display, + FontFamily::Text => self.families.text, + FontFamily::Mono => self.families.mono, + }; + + Font { + family: iced::font::Family::Name(family), + weight: weight_of(style.weight), + ..Font::DEFAULT + } + } + + /// baseline 档的字体。 + pub fn font(&self, role: TypeRole) -> Font { + self.font_of(self.style(role)) + } + + /// 强调档的字体。 + pub fn emphasized_font(&self, role: TypeRole) -> Font { + self.font_of(self.emphasized(role)) + } + + /// iced 的 6 色 `Palette`（只给 devtools；M3 的 49 角色在 [`Ui::color`]）。 + pub fn palette(&self) -> Palette { + Palette { + background: self.color(Role::Surface), + text: self.color(Role::OnSurface), + primary: self.color(Role::Primary), + success: self.color(Role::Secondary), + warning: self.color(Role::Tertiary), + danger: self.color(Role::Error), + } + } + + /// iced 主题对象：**名字带深浅**，切主题时 `Theme::name()` 变化会触发重算。 + pub fn theme(&self) -> Theme { + Theme::custom(self.name(), self.palette()) + } + + /// `Theme::name()` 的取值（稳定字符串，改名要先在协作文档登记）。 + pub fn name(&self) -> &'static str { + match self.flavor() { + SchemeFlavor::Light => "ull-m3-light", + SchemeFlavor::Dark => "ull-m3-dark", + } + } +} + +/// 令牌色（8 bit sRGB）→ iced 的 sRGB 分量。 +pub fn to_iced(color: unlucky_design::color::Color) -> Color { + Color::from_rgba8( + color.r, + color.g, + color.b, + f32::from(color.a) / f32::from(u8::MAX), + ) +} + +/// 令牌字重 → iced 字重。 +pub fn weight_of(weight: Weight) -> iced::font::Weight { + match weight { + Weight::Regular => iced::font::Weight::Normal, + Weight::Medium => iced::font::Weight::Medium, + Weight::SemiBold => iced::font::Weight::Semibold, + Weight::Bold => iced::font::Weight::Bold, + } +} + +#[cfg(test)] +mod tests { + use super::*; + + const FAMILIES: Families = Families { + text: "Segoe UI Variable Text", + display: "Segoe UI Variable Display", + mono: "Cascadia Mono", + }; + + fn ui(flavor: SchemeFlavor) -> Ui { + Ui::with_platform(flavor, Platform::Windows, FAMILIES) + } + + #[test] + fn theme_name_tracks_the_flavor() { + assert_eq!(ui(SchemeFlavor::Light).name(), "ull-m3-light"); + assert_eq!(ui(SchemeFlavor::Dark).name(), "ull-m3-dark"); + assert_ne!( + ui(SchemeFlavor::Light).theme().to_string(), + ui(SchemeFlavor::Dark).theme().to_string() + ); + } + + #[test] + fn canvas_card_overlay_follow_surface_containers() { + let ui = ui(SchemeFlavor::Light); + assert_eq!(ui.layer(MaterialLayer::Canvas), ui.color(Role::Surface)); + assert_eq!( + ui.layer(MaterialLayer::Card), + ui.color(Role::SurfaceContainerLow) + ); + assert_eq!( + ui.layer(MaterialLayer::Overlay), + ui.color(Role::SurfaceContainerHigh) + ); + } + + #[test] + fn radii_only_come_from_the_scale() { + let ui = ui(SchemeFlavor::Light); + // 卡片 Medium(12)：边长够大时就是 12 + assert_eq!(ui.radius_dp(ShapeScale::Medium).top_left, 12.0); + assert_eq!(ui.radius_dp(ShapeScale::ExtraSmall).top_left, 4.0); + // 药丸 Full：按边长一半折算 + assert_eq!(ui.radius(ShapeScale::Full, 32.0).top_left, 16.0); + // 不许超过边长一半 + assert_eq!(ui.radius(ShapeScale::ExtraLarge, 20.0).top_left, 10.0); + } + + #[test] + fn outlines_are_one_pixel_and_use_outline_variant() { + let ui = ui(SchemeFlavor::Light); + let border = ui.outlined(ShapeScale::Medium); + assert_eq!(border.width, STROKE_PX); + assert_eq!(border.width, 1.0, "rubric G7：全站 1px"); + assert_eq!(border.color, ui.color(Role::OutlineVariant)); + assert_eq!(border.radius.top_left, 12.0); + } + + #[test] + fn emphasized_weights_are_the_official_ones() { + let ui = ui(SchemeFlavor::Light); + // title-small 的强调档是 700（官方 Emphasized） + assert_eq!( + ui.emphasized_font(TypeRole::TitleSmall).weight, + iced::font::Weight::Bold + ); + // baseline 正文是 400 + assert_eq!( + ui.font(TypeRole::BodyMedium).weight, + iced::font::Weight::Normal + ); + } + + #[test] + fn body_text_keeps_wcag_contrast_in_both_flavors() { + for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] { + let scheme = Scheme::baseline(flavor); + assert!( + scheme.contrast(Role::OnSurface, Role::Surface) >= 4.5, + "{flavor:?} 的正文对比度不够" + ); + assert!( + scheme.contrast(Role::OnSecondaryContainer, Role::SecondaryContainer) >= 4.5, + "{flavor:?} 的选中态药丸对比度不够" + ); + } + } + + #[test] + fn every_role_maps_to_an_iced_color() { + for role in Role::ALL { + let color = ui(SchemeFlavor::Dark).color(role); + assert!((0.0..=1.0).contains(&color.a), "{role:?} 的 alpha 越界"); + } + } + + #[test] + fn state_layers_are_opaque_so_cpu_and_gpu_match() { + let ui = ui(SchemeFlavor::Light); + let hovered = ui.state_over(StateLayer::Hover, Role::OnSurface, Role::Surface); + assert_eq!(hovered.a, 1.0, "状态层必须给出不透明结果"); + assert_ne!(hovered, ui.color(Role::Surface)); + } + + /// D38：配色方案必须真的换色；默认构造逐字段等于 baseline（防回流的那一半）。 + /// 抓不住：取色好不好看、设置页是否真切过去（后者由 app 侧日志举证）。 + #[test] + fn a_resolved_scheme_replaces_the_baseline_colours() { + use unlucky_design::palette::{resolve_source, CardKey, ImageInput}; + + // 4×4 的纯红图：种子彩度远高于门槛，必然走到「背景图取色」这一级。 + let pixels = [0xC0_u8, 0x20, 0x20, 0xFF].repeat(16); + let input = ImageInput::pixels(&pixels, 4, 4); + let (scheme, provenance) = + resolve_source(Some(input), None, Some(CardKey::Sky), SchemeFlavor::Light); + assert_eq!( + provenance.level, + unlucky_design::palette::Level::BackgroundImage, + "纯红图必须取色成功（否则本测试的输入不合格）" + ); + + let tinted = Ui::from_scheme(scheme, FAMILIES); + let baseline = ui(SchemeFlavor::Light); + assert_ne!( + tinted.color(Role::Primary), + baseline.color(Role::Primary), + "取色方案必须换掉 primary" + ); + // 深浅仍跟着方案走（方案自带 flavor），不会把 Light 变成 Dark。 + assert_eq!(tinted.flavor(), SchemeFlavor::Light); + assert_eq!(tinted.name(), baseline.name()); + + // 默认构造不变：`with_platform` 与 baseline 逐块相等。 + let explicit = Ui::from_scheme(Scheme::baseline(SchemeFlavor::Light), FAMILIES); + for role in Role::ALL { + assert_eq!( + explicit.color(role), + baseline.color(role), + "{role:?}：不传 scheme 时默认行为必须与改动前一致" + ); + } + } +} diff --git a/crates/app-iced/src/ui.rs b/crates/app-iced/src/ui.rs new file mode 100644 index 0000000..8fbbf70 --- /dev/null +++ b/crates/app-iced/src/ui.rs @@ -0,0 +1,17 @@ +//! # 界面语言入口（M106 `I18NFOLLOW`） +//! +//! 用户报的原话：「我系统语言是中文 为什么打开软件是英文 并且设置页里面显示的是 English (System)」。 +//! 前半是**探测对了但没人用**（`app/view.rs` 里 `Lang::En` 写死），后半是一行硬编码假值。 +//! +//! 这个模块就是那条缺失的入口：把「用户选的档位 + M92 的探测结论」变成一个值，交给 +//! `pages::Model.lang`（目录）与设置页语言行（档位回显）。 +//! +//! | 文件 | 是什么 | +//! |---|---| +//! | [`lang`] | [`lang::LangState`]：启动判定（`ULL_LANG` > 配置 > 系统 locale > 英文）、切档、两行日志 | +//! +//! 为什么不叫 `theme::Ui` 的字段：`theme.rs` 是令牌求值器（颜色/字号/间距），语言不是令牌—— +//! 它是**运行期状态**，随设置变化，还要落盘。混进 `Ui` 会让「切主题」与「切语言」共享一条重建路径， +//! 而它们该重建的东西根本不是同一批（一个重建 Style，一个重建视图模型）。 + +pub mod lang; diff --git a/crates/app-iced/src/ui/lang.rs b/crates/app-iced/src/ui/lang.rs new file mode 100644 index 0000000..1ef28d5 --- /dev/null +++ b/crates/app-iced/src/ui/lang.rs @@ -0,0 +1,283 @@ +//! 界面语言的**入口层**（M106 `I18NFOLLOW`）：`Ui` 缺的那条语言入口就是这里。 +//! +//! ## 它解决的是什么 +//! +//! M92 把探测链做对了（启动日志里 `lang=zh-CN locale=zh-CN source=registry` 一直是对的），但 +//! **没人消费它**：`app/view.rs` 的 `model()` 里 `Lang::En` 是写死的，于是中文系统上开出来的是 +//! 全英文界面，设置页还写着 `English (System)`。本模块把「用户档位 + 探测结论」变成一个**值** +//! （[`LangState`]），`App` 持有它、`view::model` 只认它，页面侧 `pages::Model.lang` 决定目录。 +//! +//! ## 判定的四级优先级（[`LangState::boot`]） +//! +//! | 级 | 来源 | 什么时候用 | +//! |---|---|---| +//! | 1 | `ULL_LANG`（`zh_cn` / `en_us`） | 截图矩阵要**可复现地**换语言（D30） | +//! | 2 | 配置里的 `ui.language` | 用户手选（设置页写入） | +//! | 3 | 系统 locale（注册表 / 环境变量） | 跟随系统 | +//! | 4 | 英文 | 一个源都没有 | +//! +//! **截图通道不读用户配置**（与 `appearance_prefs` 同一条 D30 纪律）：同一份代码在两台机器上出 +//! 不了同一张图，除非语言也由 `ULL_LANG` 显式给。 +//! +//! ## 日志（两个下一个人要问的问题） +//! +//! 「探测错了吗」与「探测对了但没用上吗」在日志里必须分得开： +//! +//! ```text +//! [i18n] choice=system lang=zh-CN locale=zh-CN source=registry effective=zh-CN +//! [i18n] lang=zh-CN locale=zh-CN source=registry cjk=system:"Microsoft YaHei UI" +//! ``` +//! +//! 第一行是**档位 + 探测结论 + 最终生效语言**（[`LangState::log`]），第二行是中文策略（D28： +//! 缺字体是信号，不许静默；[`LangState::log_cjk`]）。 +//! +//! ## 诚实边界 +//! +//! - **抓得住**：档位的选择顺序、坏值不猜、截图通道忽略配置、切档后生效语言跟着换； +//! - **抓不住**：系统 locale 的真机行为（那在 [`crate::platform::locale::SystemLocale`]，Windows 上 +//! 真的去跑 `reg.exe`）；中文字体到底装没装（`fonts::cjk_for` 查 iced 的字体库）。 + +use unlucky_i18n::lang::{Detection, EnvLocale}; +use unlucky_i18n::{Lang, LangChoice}; +use unlucky_presenter::settings_bridge::SettingsBridge; + +use crate::pages; +use crate::platform::locale::SystemLocale; + +/// 截图通道的语言覆盖（D30 可复现）：`ULL_LANG=zh_cn` / `ULL_LANG=en_us`。 +/// +/// 为什么走环境变量而不是 `--lang`：`cli.rs` 不在本 mission 的 scope 里，而截图矩阵要能**只**改 +/// 一个环境变量就换语言（与 `ULL_APPEARANCE_*` 那批同一条做法）。 +pub(crate) const LANG_ENV: &str = "ULL_LANG"; + +/// 设置页左侧分组的取证开关：`ULL_SETTINGS_GROUP=0` 直达 General（语言行在那里）。 +/// +/// 只影响 `--screenshot` 那一次进程（设置页出厂停在「外观」，而用户抱怨的语言行在 General 组； +/// 出图必须能直达）。交互模式一律按用户点的那一组，所以这里拿 `screenshot` 当闸门。 +/// 为什么住在 `ui/lang.rs`：它与 [`LANG_ENV`] 是同一族「出图取证开关」，一起放在语言入口层， +/// `App` 那边只留一行调用（`app/state.rs` 贴着 400 行硬线）。 +pub(crate) fn screenshot_settings_group(screenshot: bool) -> Option { + 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(_) + ) { + eprintln!( + "[i18n] 缺中文字体：界面会是中文但字形可能缺失（D28 的下载通道还是 PendingPin）" + ); + } + } +} + +/// 档位选择的**纯判据**（单测直接打这张表）。 +/// +/// **产品路径与验收路径共用它**：`LangState::boot` 用它决定目录，`renderer::acceptance::locale` +/// 的 `[i18n]` 行也用它算结论——两行日志因此不可能再说出不同的语言（r4 复审 p2-1 就是 +/// 「两处各算一遍」造成的）。 +/// +/// | 输入 | 结果 | +/// |---|---| +/// | `ULL_LANG` 给了合法值 | 那一档（压过配置） | +/// | 没给 + 配置写了 `zh_cn` / `en_us` | 那一档 | +/// | 没给 + 配置没写（或写了坏值） | 跟随系统 | +/// | **截图通道** + 配置写了值 | 跟随系统（除非 `ULL_LANG` 另给） | +pub(crate) fn choose_choice( + forced: Option<&str>, + setting: Option<&str>, + screenshot: bool, +) -> LangChoice { + let configured = if screenshot { None } else { setting }; + LangChoice::from_setting(forced.or(configured)) +} + +#[cfg(test)] +mod tests { + use super::*; + + /// 档位判据的真值表（D28 第一级 + D30 的截图可复现）。 + /// + /// 抓得住：①`ULL_LANG` 没压过配置（截图矩阵就换不了语言）；②截图通道读了用户配置（同一份代码 + /// 在两台机器上出不同的图）；③坏值被猜成某种语言。 + /// 抓不住：系统 locale 真探测成什么（那是 `SystemLocale` + `i18n::lang::resolve` 的事）。 + #[test] + fn the_language_choice_is_ull_lang_then_config_then_system() { + let en = Some("en_us"); + let zh = Some("zh_cn"); + + assert_eq!(choose_choice(None, None, false), LangChoice::System); + assert_eq!( + choose_choice(None, zh, false), + LangChoice::Fixed(Lang::ZhCn), + "配置里的手选要生效" + ); + assert_eq!( + choose_choice(en, zh, false), + LangChoice::Fixed(Lang::En), + "ULL_LANG 压过配置（截图矩阵靠它换语言）" + ); + assert_eq!( + choose_choice(zh, None, false), + LangChoice::Fixed(Lang::ZhCn) + ); + + assert_eq!( + choose_choice(None, zh, true), + LangChoice::System, + "截图通道必须忽略配置文件里的语言，否则同一份代码出不了同一张图" + ); + assert_eq!(choose_choice(en, zh, true), LangChoice::Fixed(Lang::En)); + + for bogus in ["zh-CN", "system", "", "fr_fr"] { + assert_eq!( + choose_choice(Some(bogus), None, false), + LangChoice::System, + "{bogus}" + ); + } + } + + /// 「重启后保持所选语言」的**闭环证据**：真的落一个临时 `launcher.json`，再用**新开的** bridge + /// 读回来（等价于重启）。 + /// + /// 抓得住：①「跟随系统」被读成 schema 默认值 `zh_cn`（英文机器一启动就是中文）； + /// ②「跟随系统」写了哨兵值（下次启动撒谎）；③删键时把别的键一起删了。 + /// 抓不住：数据根解析（`SettingsBridge::open` 那条路）——这里用的是显式路径。 + #[test] + fn the_choice_round_trips_through_the_config_file() { + use unlucky_presenter::settings_bridge::SettingsBridge; + + let dir = std::env::temp_dir().join(format!("ull-m106-lang-{}", std::process::id())); + std::fs::create_dir_all(dir.join("config")).expect("临时目录"); + let path = dir.join("config/launcher.json"); + std::fs::write( + &path, + r#"{"appearance":{"theme_mode":"dark"},"custom":{"keep":true}}"#, + ) + .expect("写配置"); + + // ① 没写过 = 跟随系统（不是默认值 zh_cn） + let bridge = SettingsBridge::with_path(&path); + assert_eq!( + bridge.load_ui_language(), + None, + "没写过这个键 = 跟随系统，不许回落成 schema 默认值" + ); + + // ② 手选落盘 → 新开的 bridge（= 重启）读回来 + let mut bridge = SettingsBridge::with_path(&path); + assert!(bridge.persist_ui_language(Some("zh_cn"))); + assert_eq!( + SettingsBridge::with_path(&path) + .load_ui_language() + .as_deref(), + Some("zh_cn"), + "重启后要保持所选语言" + ); + + // ③ 切回跟随系统 = 删键，且不许顺手删别的键 + let mut bridge = SettingsBridge::with_path(&path); + assert!(bridge.persist_ui_language(None)); + assert_eq!(SettingsBridge::with_path(&path).load_ui_language(), None); + let text = std::fs::read_to_string(&path).expect("读配置"); + assert!(text.contains("theme_mode"), "外观键被删了：{text}"); + assert!(text.contains("custom"), "用户手写的未知键被删了：{text}"); + + // ④ 已经是跟随系统时再点一次是幂等的 + let mut bridge = SettingsBridge::with_path(&path); + assert!(!bridge.persist_ui_language(None), "没有键可删 = 没有落盘"); + std::fs::remove_dir_all(&dir).ok(); + } + + /// 手选档会赢过系统源，且 `raw`/`origin` 看得出来是手选的（日志可分诊）。 + /// + /// 抓得住：`of()` 忘了重算（切档后结论还停在旧语言）、手选被系统源盖掉。 + /// 抓不住：真机上系统源读到什么（`SystemLocale` 跑 `reg.exe`）。 + #[test] + fn a_fixed_choice_wins_over_the_system_locale() { + let zh = LangState::of(LangChoice::Fixed(Lang::ZhCn)); + assert_eq!(zh.lang(), Lang::ZhCn); + assert_eq!(zh.for_settings().effective, Lang::ZhCn); + assert_eq!(zh.for_settings().choice, LangChoice::Fixed(Lang::ZhCn)); + + let en = LangState::of(LangChoice::Fixed(Lang::En)); + assert_eq!(en.lang(), Lang::En, "手选英文压过任何中文系统源"); + assert_eq!(en.detection.origin, "setting"); + } +} diff --git a/crates/app-iced/tests/no_hardcoded_tokens.rs b/crates/app-iced/tests/no_hardcoded_tokens.rs new file mode 100644 index 0000000..1645758 --- /dev/null +++ b/crates/app-iced/tests/no_hardcoded_tokens.rs @@ -0,0 +1,400 @@ +//! 门禁：**组件层零硬编码**（色值 / 尺寸）与「不依赖 slint」。 +//! +//! 这三条测试会扫本 crate 的 `src/**` 与 `Cargo.toml`，故意写得「宁可错杀」： +//! 将来 reviewer 复跑 `cargo test -p unlucky-app-iced` 就能挡住「顺手写个 #RRGGBB」的提交。 +//! +//! 判定口径（与 `component-fidelity-rubric.md` T1/T2、`visual-acceptance-protocol.md` §1 对齐）： +//! +//! - **色值字面量**：`#` + 6 位十六进制（且**至少含一个数字**，这样文档里的 `#RRGGBB` 占位不会被误杀） +//! 或 `Color::from_rgb(0.1, …)` / `color!(0x…)` 这类带数值参数的构造。 +//! - **令牌优先**：唯一允许的是 `theme.rs`（适配层），且它也只做 `token → iced` 的搬运。 +//! - **尺寸字面量**：`shell.rs` 里 `.width(12.0)` / `.height(34)` / `.size(22)` 一律不许出现 +//! （必须走 `LayoutMetrics` / `TypeStyle` / `Space`）。 + +use std::path::{Path, PathBuf}; + +/// 本 crate 根目录（编译期注入，换机器也成立）。 +fn manifest_dir() -> PathBuf { + PathBuf::from(env!("CARGO_MANIFEST_DIR")) +} + +/// 递归收集 `dir` 下的 `.rs` 文件。 +fn rust_files(dir: &Path, collected: &mut Vec) { + 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..81b016e --- /dev/null +++ b/crates/cli/Cargo.toml @@ -0,0 +1,35 @@ +[package] +name = "unlucky-cli" +description = "Unlucky-Launcher 命令行（bin `ull`）：headless 消费者，零 UI 框架依赖（D18）" +version.workspace = true +edition.workspace = true +license.workspace = true +authors.workspace = true +repository.workspace = true +rust-version.workspace = true +publish.workspace = true + +# 产物名钉死 `ull`（D18 定案）：单文件 CLI，与 GUI 的 `unlucky-launcher` 并列。 +[[bin]] +name = "ull" +path = "src/main.rs" + +[lib] +name = "unlucky_cli" +path = "src/lib.rs" + +# 依赖纪律（10-cli-design.md §2）：core + agent，**不引 Slint**。 +# 参数解析手写（不引 clap）：子命令集小，没必要为它多引一棵依赖树（Win10+ 单基线， +# 但 CLI 是 headless/服务器场景的产物，体积与启动开销仍是关注项）。 +[dependencies] +unlucky-core = { path = "../core", version = "0.2" } +# agent：`redact`（输出脱敏）+ `ull agent serve`（M39 的 MCP server：注册表 → rmcp 双投影， +# core 侧五个端口在 src/commands/agent/ports/ 装配）。 +unlucky-agent = { path = "../agent", version = "0.2" } +# `ull agent serve` 要长驻跑 rmcp 的 stdio / Streamable HTTP 传输（tokio 运行时）。 +tokio.workspace = true +serde.workspace = true +serde_json.workspace = true + +[lints] +workspace = true diff --git a/crates/cli/src/cli/help.rs b/crates/cli/src/cli/help.rs new file mode 100644 index 0000000..c2689a6 --- /dev/null +++ b/crates/cli/src/cli/help.rs @@ -0,0 +1,183 @@ +//! 帮助文案（`ull --help` / `ull help <命令>`）。 +//! +//! 命令集与 `10-cli-design.md` §3 对齐；`agent serve|config`（M39 的 MCP server）已列， +//! `agent ask`（内置对话的 headless 形态）仍未列。 + +/// 总帮助。 +#[must_use] +pub const fn general() -> &'static str { + "\ +%prog% · Unlucky-Launcher 命令行（D18） + +用法: + %prog% [全局选项] <命令> [参数] + +命令: + instances list 列出实例与已安装版本 + install [--loader X] [--loader-version V] [--name N] [--dry-run] + 下载并安装版本本体（--loader fabric|quilt|neoforge|forge + 时再叠一层加载器）→ 登记实例；--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 钉死一家） + java vendors 列出四家发行版的镜像/支持版本/当前优先级 + agent serve [--stdio] [--port N] 起对外 MCP server（默认 127.0.0.1 的 Streamable HTTP； + [--allow-write] --stdio 给 llama.cpp 内置 client 用；默认只读） + agent config [--port N] 打印 Claude Code / Cursor 的配置样例 + version 版本 + 系统摘要（同 --version） + help [命令] 本帮助 + +全局选项: + --json 机器可读输出：成功 {\"ok\":true,\"data\":…}，失败 {\"ok\":false,\"error\":…} + --data-dir P 覆盖数据根（等价 custom 模式的根目录，即含 .ULL/ 与 .minecraft/ 的父目录） + --no-color 关闭颜色（v1 输出不含 ANSI，参数保留以兼容脚本） + --quiet 静默人类可读输出（错误与提示仍进 stderr） + --help, -h 帮助（有位置参数时按该命令给帮助） + --version, -V 版本 + 系统摘要 + +退出码: 0 成功 / 1 用户错误 / 2 内部错误 / 3 部分成功（仅 pack import）" +} + +/// 单个命令的帮助；未知主题返回 `None`（调用方退回总帮助）。 +#[must_use] +pub fn topic(name: &str) -> Option<&'static str> { + match name { + "instances" => Some( + "\ +%prog% instances list + +列出 profiles.json 里的实例与 versions/ 下已安装的版本。 + --json 输出 {\"data\":{\"instances\":[…],\"installed_versions\":[…],\"data_root\":…}}", + ), + "pack" => Some( + "\ +%prog% pack import [--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 会逐项列进报告，不静默丢） + +目标目录缺省 = 数据根的共享游戏目录（.minecraft/）；`--target` 可钉到实例目录。 +两阶段落盘：先 overrides（三方合并：包内原值 / 磁盘现状 / 上次基线），再补远端文件。 + · 用户改过的文件不会被静默覆盖（默认保留，逐条进冲突清单）；`--overwrite` 才用包覆盖 + · 缺文件（断网 / CurseForge files[] 补不出来）可容忍，但结果降级为「部分成功」 + · 目录穿越 / 符号链接 / 清单损坏 / 摘要不符一律整包回滚，目标目录零残留 +`--no-register`：只落内容，不写 profiles.json。 +退出码：0 成功 / 3 部分成功 / 1 失败（2 内部错误）。 +--json：信封恒为 {\"ok\":true,\"data\":{…}}，分流看 data.status 与 data.error.code； + data.stages 列出实际走过的阶段。", + ), + "install" => Some( + "\ +%prog% install [--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。装加载器时先生成 +versions/<原版>-<加载器>-<版本>/<…>.json（inheritsFrom 原版 + 主类 + loader 库）， +原版没装会先装原版，实例的 versionId 指向 loader 版本。 +--loader-version：加载器版本；缺省取官方默认（Fabric 系首个稳定版，maven 系最新）。 + Forge 可写 47.2.0 或 1.20.1-47.2.0 两种形态。 + NeoForge/Forge 里需要跑官方 installer processors 的版本会真跑一遍（M35 已实装）： + 缺 Java 时按 D23 的回退链自动装一个托管 JDK；--dry-run 只列出要跑的 processor 与依赖库。 +--json：stdout 是单个结果信封 {\"data\":{\"plan\":…,\"result\":…,\"instance\":…}}， +实时进度改走 stderr 的 JSONL（一行一条 {\"event\":\"progress\"|\"file_failed\"}）； +--quiet 时连进度也不打。", + ), + "launch" => Some( + "\ +%prog% launch [--dry-run] [--account ] [--java ] [--username ] + [--max-memory ] + + 可以是实例 id、实例名，或直接是版本 id。 +--dry-run（D18）：只组装命令行并打印，不 spawn 进程、不写会话文件、不刷新令牌。 +账户：--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 输码）。 +它需要一个 Azure 公共客户端 id —— 登录链路是完整的，缺的只是这一项配置；id 不进仓库： + ULL_MSA_CLIENT_ID= %prog% accounts add msa 每次运行时给（环境变量优先） + ULL_MSA_CLIENT_ID= cargo build 构建时注入，二进制自带 +两处都没有时命令立刻报「微软登录未配置」（含怎么配），**不会去联网**。 +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 钉死一家、不自动降级。 +每家失败的原因（版本不存在 / 镜像全 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..8f04c14 --- /dev/null +++ b/crates/cli/src/cli/mod.rs @@ -0,0 +1,109 @@ +//! 命令行解析（手写，不引 clap —— 子命令集小，省一棵依赖树）。 +//! +//! 语法：`ull [全局选项] <命令> [子命令/参数]`。全局选项可以出现在任意位置 +//! （脚本里 `ull instances list --json` 与 `ull --json instances list` 等价）。 +//! +//! 帮助与版本是「提前返回」的伪命令：`--help` / `-h` 出现在任何位置都立即给帮助， +//! 有位置参数时按该主题给帮助。 + +pub mod help; +pub mod model; +pub mod parse; +pub mod program; + +pub use model::{ + AccountsAddArgs, AccountsAddKind, AgentServeArgs, Command, ConfigGetArgs, ConfigSetArgs, + DiagArgs, Globals, InstallArgs, Invocation, LaunchArgs, LogsArgs, PackImportArgs, +}; +pub use parse::parse; + +/// 这条命令行是 CLI 调用，还是「不该由 CLI 接管」（GUI 启动 / 只有全局选项）？ +/// +/// GUI 二进制（`unlucky-launcher` / `unlucky-launcher-iced`）用它做分发判据，`ull` 自己的 +/// `main` 不用——**判据只有这一处**，两个 GUI 各调一次，改语义不会漂。 +/// +/// 规则（刻意不列 GUI 的 flag 表：cli crate 不该知道 GUI 有什么参数）： +/// +/// - 首个 token 是裸词（不以 `-` 开头）→ 一定在子命令位置（GUI 不接受位置参数，`--diff` / +/// `--screenshot` 的取值都排在 flag 之后）→ 接管。未知子命令也在这里，由 CLI 自己报错。 +/// - 首个 token 是 flag → 只有当 [`parse`] 解析出一条**真命令**时才算 CLI 调用：`--help` / +/// `--version` / `--json instances list` 接管；`--data-dir X` 解析成 [`Command::Welcome`] +/// （没有子命令）、GUI 专属参数（`--screenshot` / `--renderer` / `--diff` …）根本解析失败， +/// 两种情况都不接管。**「解析失败」必须留在调用方**：`--screenshot out.png` 也会让本解析器 +/// 报错，把它判成 CLI 就会让 GUI 的截图通道失效。 +#[must_use] +pub fn looks_like_cli(args: &[String]) -> bool { + match args.first() { + None => false, + Some(first) if !first.starts_with('-') => true, + Some(_) => match parse(args) { + Ok(invocation) => !matches!(invocation.command, Command::Welcome), + Err(_) => false, + }, + } +} + +#[cfg(test)] +mod tests { + use super::looks_like_cli; + + fn cli(args: &[&str]) -> bool { + looks_like_cli(&args.iter().map(|arg| (*arg).to_owned()).collect::>()) + } + + #[test] + fn no_args_is_not_a_cli_call() { + assert!(!cli(&[])); + } + + #[test] + fn gui_flags_are_never_taken_over() { + // CI 与验收脚本在用这些参数，一条都不能被当成子命令吃掉。 + assert!(!cli(&["--software-renderer"])); + assert!(!cli(&["--screenshot", "out.png", "--data-dir", "/d/tmp/x"])); + assert!(!cli(&["--screenshot-theme", "dark"])); + assert!(!cli(&["--renderer=gpu", "--theme=dark"])); + assert!(!cli(&["--scale-factor", "1.0"])); + assert!(!cli(&["--force-state", "hover"])); + assert!(!cli(&["--diff", "a.png", "b.png"])); + assert!(!cli(&["--mock"])); + // 只有 --data-dir 时解析成 Welcome（没有子命令），仍是 GUI 启动。 + assert!(!cli(&["--data-dir", "/d/tmp/x"])); + } + + #[test] + fn known_subcommands_are_taken_over() { + for args in [ + vec!["instances", "list"], + vec!["install", "1.20.1", "--dry-run"], + vec!["launch", "1.20.1", "--dry-run"], + vec!["accounts", "list"], + vec!["sessions", "list"], + vec!["logs", "abc", "--tail", "10"], + vec!["diag", "abc"], + vec!["config", "get"], + vec!["java", "list"], + vec!["agent", "config"], + // 全局选项可以排在子命令前面 + vec!["--json", "instances", "list"], + ] { + assert!(cli(&args), "{args:?} 应该交给 CLI"); + } + } + + #[test] + fn help_and_version_are_taken_over() { + assert!(cli(&["--version"])); + assert!(cli(&["--help"])); + assert!(cli(&["-h"])); + assert!(cli(&["-V"])); + } + + #[test] + fn unknown_subcommands_are_left_to_the_cli_to_reject() { + // 语义定案（README 两版同款）：未知子命令 → CLI 报「未知命令 + <名字> --help」并以 1 退出， + // 不静默落到 GUI（否则脚本用户会以为参数生效了）。 + assert!(cli(&["lst"])); + assert!(cli(&["intsances", "list"])); + } +} diff --git a/crates/cli/src/cli/model.rs b/crates/cli/src/cli/model.rs new file mode 100644 index 0000000..19f5fd0 --- /dev/null +++ b/crates/cli/src/cli/model.rs @@ -0,0 +1,213 @@ +//! 命令模型（纯数据）：解析结果就是这里的一个 [`Invocation`]。 + +use std::path::PathBuf; + +/// 全局选项（所有命令共享）。 +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct Globals { + /// `--json`：机器可读输出。 + pub json: bool, + /// `--no-color`：关闭颜色。v1 输出本身不含 ANSI，参数保留以兼容脚本。 + pub no_color: bool, + /// `--quiet`：静默人类可读输出（错误仍进 stderr）。 + pub quiet: bool, + /// `--data-dir `：覆盖数据根（等价 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, + /// `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), + /// `agent config`：打印 Claude Code / Cursor 的客户端配置样例。 + AgentConfig { + /// 覆盖端点端口（默认取设置键 `agent.mcp.port`）。 + port: 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`）。 + 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, + /// 目标实例目录（缺省 = 数据根的共享游戏目录 `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, +} + +/// `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..7280b77 --- /dev/null +++ b/crates/cli/src/cli/parse.rs @@ -0,0 +1,393 @@ +//! 手写解析器：全局选项 → 子命令 → 子命令内的选项。 + +use std::collections::BTreeMap; +use std::path::PathBuf; + +use unlucky_core::game::java::JdkVendor; + +use crate::error::CliError; + +mod accounts; +mod agent; + +use super::model::{ + Command, ConfigGetArgs, ConfigSetArgs, DiagArgs, Globals, InstallArgs, Invocation, LaunchArgs, + LogsArgs, PackImportArgs, +}; + +/// `logs` 缺省尾巴行数。 +const DEFAULT_LOG_TAIL: usize = 200; +/// `diag` 缺省送入规则引擎的行数。 +const DEFAULT_DIAG_TAIL: usize = 2000; +/// `sessions list` 缺省条数。 +const DEFAULT_SESSION_LIMIT: usize = 20; + +/// 解析整条命令行（不含 argv[0]）。 +/// +/// # Errors +/// +/// 用法错误（未知命令/选项、缺参数、数字解析失败）返回 [`CliError`]（退出码 1）。 +pub fn parse(args: &[String]) -> Result { + 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" => parse_instances(tail), + "install" => parse_install(tail, globals), + "pack" => parse_pack(tail), + "launch" => parse_launch(tail), + "sessions" => parse_sessions(tail), + "logs" => parse_logs(tail), + "diag" => parse_diag(tail), + "config" => parse_config(tail), + "java" => parse_java(tail), + "accounts" => accounts::parse_accounts(tail), + "agent" => agent::parse_agent(tail), + other => { + Err(CliError::usage(format!("未知命令 `{other}`")) + .with_hint("%prog% --help 查看命令列表")) + } + } +} + +fn parse_instances(tail: &[String]) -> Result { + let args = match tail.first().map(String::as_str) { + None | Some("list") => tail.get(1..).unwrap_or_default(), + Some(other) => { + return Err(CliError::usage(format!( + "instances 的子命令只有 list，收到 `{other}`" + ))); + } + }; + let parsed = parse_flags(args, &[], &[])?; + ensure_no_positionals(&parsed, "instances list")?; + Ok(Command::InstancesList) +} + +fn parse_install(tail: &[String], globals: &Globals) -> Result { + 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/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..06088e7 --- /dev/null +++ b/crates/cli/src/commands/agent/mod.rs @@ -0,0 +1,135 @@ +//! `ull agent`：对外 MCP server 的 headless 入口（02 文档 §1 的第二形态）。 +//! +//! 两个子命令： +//! - `agent serve`：长驻服务（`--stdio` 或 Streamable HTTP on 127.0.0.1）； +//! - `agent config`：打印 Claude Code / Cursor 的配置样例（含当前端口与令牌状态）。 +//! +//! 为什么 `serve` 不能走 `commands::run` 的「返回 Report 再打印」套路：stdio 形态下 +//! **stdout 就是 JSON-RPC 流**，任何一行多余输出都会让客户端解析失败。所以 runner +//! 里对 `Command::AgentServe` 提前分流，不走 `output::print_report`。 + +pub mod ports; +pub mod serve; + +use serde_json::{json, Value}; +use unlucky_agent::mcp::config_samples; +use unlucky_core::setting::keys::launcher_schema; +use unlucky_core::setting::store::SettingStore; + +use crate::cli::AgentServeArgs; +use crate::context::Ctx; +use crate::error::CliError; +use crate::output::Report; + +/// `ull agent serve`：起服务（阻塞）。 +/// +/// # Errors +/// 见 [`serve::run`]。 +pub fn run_serve(ctx: &Ctx, args: &AgentServeArgs) -> Result { + 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..0143f0e --- /dev/null +++ b/crates/cli/src/commands/agent/ports/diagnose.rs @@ -0,0 +1,187 @@ +//! 诊断端口：调用 M15 的规则引擎（**规则先跑，模型补位**，02 §3.2）。 +//! +//! 工具层只把「规则结论 + 相关片段」交给模型，不把裸日志倒进去——这是 token 预算 +//! 与结论质量的双重考虑，也是 analyse/02 §8.3 的分层思路。 + +use std::collections::BTreeMap; + +use unlucky_agent::port::{ + CrashDiagnosis, DiagnosePort, DiagnosisCandidate, ExitSummary, FixAction, FixActionKind, + PortResult, +}; +use unlucky_core::diagnose::collectors::{ExitSignal, SignalOrigin}; +use unlucky_core::diagnose::engine::{Diagnoser, DiagnosisInput, Finding}; +use unlucky_core::diagnose::loader::RuleLoader; +use unlucky_core::diagnose::rules::FixActionKind as CoreFixKind; + +use super::events::{tail_join, SessionSource}; + +/// 送进规则引擎的默认尾巴行数（与 CLI `diag` 同值，避免两条路看到不同证据）。 +pub const DEFAULT_TAIL: usize = 2000; + +/// M15 规则引擎的端口实现。 +#[derive(Debug, Clone)] +pub struct CoreDiagnose { + source: SessionSource, + tail: usize, +} + +impl CoreDiagnose { + /// `root` = `<数据根>/.ULL/data/agent/sessions`。 + #[must_use] + pub fn new(root: impl Into) -> Self { + Self { + source: SessionSource::new(root), + tail: DEFAULT_TAIL, + } + } +} + +fn map_kind(kind: CoreFixKind) -> FixActionKind { + match kind { + CoreFixKind::ChangeJava => FixActionKind::ChangeJava, + CoreFixKind::AdjustMemory => FixActionKind::AdjustMemory, + CoreFixKind::ChangeGraphics => FixActionKind::ChangeGraphics, + CoreFixKind::RemoveMod => FixActionKind::RemoveMod, + CoreFixKind::Reinstall => FixActionKind::Reinstall, + CoreFixKind::SeekHelp => FixActionKind::SeekHelp, + } +} + +fn candidate_of(finding: &Finding) -> DiagnosisCandidate { + let core_candidate = finding.to_candidate(); + DiagnosisCandidate { + id: core_candidate.id, + severity: core_candidate.severity.to_string(), + category: core_candidate.category.to_string(), + confidence: core_candidate.confidence, + message_key: core_candidate.message_key, + message: core_candidate.message, + detail: core_candidate.detail.unwrap_or_default(), + evidence: core_candidate.evidence, + fix_actions: core_candidate + .fix_actions + .into_iter() + .map(|action| FixAction { + kind: map_kind(action.kind), + tool: action.tool.to_string(), + label: String::new(), + args: action + .args + .into_iter() + .collect::>(), + }) + .collect(), + } +} + +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 exit = ExitSignal::classify( + entry.exit_code, + Some(entry.duration_ms), + error_lines, + &stderr.join("\n"), + ); + let mut input = DiagnosisInput::new().with_exit(exit); + let stdout_text = tail_join(&stdout, self.tail); + if !stdout_text.is_empty() { + input.push_text(SignalOrigin::Stdout, stdout_text); + } + let stderr_text = tail_join(&stderr, self.tail); + if !stderr_text.is_empty() { + input.push_text(SignalOrigin::Stderr, stderr_text); + } + + let loader = RuleLoader::embedded(); + let diagnoser = Diagnoser::new(loader.rule_set().rules().to_vec()); + let report = diagnoser.analyze(&input); + + Ok(CrashDiagnosis { + session_id: entry.session_id.clone(), + source: "rules".to_string(), + needs_more_info: report.needs_more_info(), + candidates: report.findings.iter().map(candidate_of).collect(), + secondary: report.secondary.iter().map(candidate_of).collect(), + evidence: stderr.iter().rev().take(3).cloned().collect(), + exit: ExitSummary { + code: entry.exit_code, + exit_type: entry.exit_type.clone(), + silent_failure: entry.silent_failure, + }, + }) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use serde_json::json; + + fn seed(root: &std::path::Path, stderr_line: &str) { + let game = root.join("game"); + std::fs::create_dir_all(&game).expect("建目录"); + let entry = json!({ + "v": 1, + "session_id": "20261029T124501-9f3c2a", + "instance_id": "inst-1", + "instance_name": "1.20.1 Forge", + "game_version": "1.20.1", + "started_at": "2026-10-29T12:45:01.123Z", + "ended_at": "2026-10-29T12:45:05.123Z", + "duration_ms": 4000, + "exit_code": 1, + "exit_type": "application_error", + "silent_failure": false, + "window_detected": false, + "event_count": 1, + "log_path": "20261029T124501-9f3c2a.jsonl", + "crash_found": true, + "diagnosis_top": null + }); + std::fs::write(game.join("index.jsonl"), format!("{entry}\n")).expect("写索引"); + let event = json!({ + "seq": 0, "ts": "2026-10-29T12:45:01.123Z", "t_ms": 0, + "kind": "stderr", + "payload": { "line": stderr_line, "level": "error" } + }); + std::fs::write( + game.join("20261029T124501-9f3c2a.jsonl"), + format!("{event}\n"), + ) + .expect("写事件"); + } + + #[test] + fn runs_the_rule_engine_over_a_session() { + let root = std::env::temp_dir().join(format!("ull-mcp-diagnose-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&root); + seed( + &root, + "java.lang.NoClassDefFoundError: cpw/mods/bootstraplauncher/BootstrapLauncher", + ); + + let port = CoreDiagnose::new(root.clone()); + let report = port.diagnose("20261029T124501-9f3c2a").expect("应能诊断"); + assert_eq!(report.session_id, "20261029T124501-9f3c2a"); + assert_eq!(report.source, "rules"); + assert_eq!(report.exit.code, Some(1)); + // 规则集里应有 JVM/完整性类结论命中这条 stderr + assert!(!report.candidates.is_empty(), "应至少命中一条规则"); + + let _ = std::fs::remove_dir_all(&root); + } + + #[test] + fn unknown_session_is_a_readable_error() { + let root = + std::env::temp_dir().join(format!("ull-mcp-diagnose-none-{}", std::process::id())); + let port = CoreDiagnose::new(root); + let err = port.diagnose("nope").unwrap_err(); + assert!(err.contains("找不到会话"), "{err}"); + } +} diff --git a/crates/cli/src/commands/agent/ports/events.rs b/crates/cli/src/commands/agent/ports/events.rs new file mode 100644 index 0000000..d313200 --- /dev/null +++ b/crates/cli/src/commands/agent/ports/events.rs @@ -0,0 +1,136 @@ +//! 会话数据的读取底座：索引（`index.jsonl`）+ 事件流（`.jsonl`）。 +//! +//! 三个端口（[`super::session::CoreSessions`] 的列表/切片、[`super::diagnose::CoreDiagnose`] +//! 的规则跑批）共用这一份读取逻辑——「同一份 jsonl 两种读法」若各写一遍， +//! 迟早出现「列表说有 5 条事件、诊断只看到 3 条」这种对不上的账。 +//! +//! 形状依据 `DevDocs/SubAgentsTalk/launch-接口约定.md` §2/§5。 + +use std::path::{Path, PathBuf}; + +use serde_json::Value; +use unlucky_core::launch::session_index::{self, SessionIndexEntry}; + +use unlucky_agent::port::PortResult; + +/// 一个数据根下的会话索引 + 事件流。 +#[derive(Debug, Clone)] +pub struct SessionSource { + root: PathBuf, +} + +impl SessionSource { + /// `root` = `<数据根>/.ULL/data/agent/sessions`。 + #[must_use] + pub fn new(root: impl Into) -> Self { + Self { root: root.into() } + } + + /// 索引文件路径。 + #[must_use] + pub fn index(&self) -> PathBuf { + session_index::index_path(&self.root) + } + + /// 全部会话（按 `started_at` 倒序，同 id 取最后一行）。 + /// + /// # Errors + /// 索引读不了（权限/IO）时返回用户可读错误；不存在视为空列表。 + pub fn entries(&self) -> PortResult> { + let index = self.index(); + let mut entries = session_index::read_all(&index) + .map_err(|error| format!("读会话索引 {} 失败：{error}", index.display()))?; + entries.sort_by(|a, b| b.started_at.cmp(&a.started_at)); + Ok(entries) + } + + /// 按完整 id 或唯一前缀找会话。 + /// + /// # Errors + /// 找不到 / 前缀歧义时返回用户可读错误。 + pub fn find(&self, key: &str) -> PortResult { + 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()) + } + + /// 事件流文件路径。 + #[must_use] + pub fn event_path(&self, entry: &SessionIndexEntry) -> PathBuf { + self.root.join("game").join(&entry.log_path) + } + + /// 事件里的 stdout / stderr 文本（诊断与日志阅读共用）。 + /// + /// 返回 `(stdout 行, stderr 行, stderr 里 level=error 的条数)`。 + #[must_use] + pub fn split_text(events: &[Value]) -> (Vec, 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() +} 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..195b067 --- /dev/null +++ b/crates/cli/src/commands/agent/ports/mod.rs @@ -0,0 +1,58 @@ +//! 端口装配：把 `unlucky-core` 的实现塞进 agent 的五个端口。 +//! +//! 为什么这一层在 CLI 而不在 agent：agent 只知道 trait（`#!` 依赖倒置）， +//! `crates/app` 是 GUI 的装配处，而 `ull agent serve` 是**headless 的另一个装配入口**。 +//! 放这里让 CLI 自洽，也让 GUI 后续复用同一批适配器（把本目录上移到 app 是一次纯搬家）。 +//! +//! 每个文件一个端口，与 `crates/agent/src/port*.rs` 一一对应，读起来不用跳来跳去。 + +pub mod accounts; +pub mod diagnose; +pub mod events; +pub mod game; +pub mod session; +pub mod setting; + +use std::sync::Arc; + +use unlucky_agent::port::Ports; +use unlucky_core::platform::data_dir::DataMode; +use unlucky_core::platform::paths::Platform; + +use crate::context::Ctx; + +pub use accounts::CoreAccounts; +pub use diagnose::CoreDiagnose; +pub use game::CoreGame; +pub use session::CoreSessions; +pub use setting::CoreSetting; + +/// 按一次 CLI 上下文装配五个端口。 +#[must_use] +pub fn build(ctx: &Ctx) -> Ports { + Ports { + // 数据根键（`core.*`）落便携目录那份，与 `Ctx::resolve` 同源——CLI `config set` + // 与 AI `set_config` 共用 `Ctx` 给出的两个落点（finding …-agent-settingport-core-ai）。 + setting: Arc::new(CoreSetting::split( + ctx.launcher_config(), + ctx.portable_launcher_config(), + )), + sessions: Arc::new(CoreSessions::new(ctx.sessions_root())), + diagnose: Arc::new(CoreDiagnose::new(ctx.sessions_root())), + game: Arc::new(CoreGame::new( + ctx.layout(), + ctx.game(), + data_mode(ctx), + platform(ctx), + )), + accounts: Arc::new(CoreAccounts::new(ctx.auth_data())), + } +} + +pub(crate) fn data_mode(ctx: &Ctx) -> DataMode { + ctx.data.mode +} + +pub(crate) fn platform(ctx: &Ctx) -> Platform { + ctx.platform +} diff --git a/crates/cli/src/commands/agent/ports/session.rs b/crates/cli/src/commands/agent/ports/session.rs new file mode 100644 index 0000000..773fc85 --- /dev/null +++ b/crates/cli/src/commands/agent/ports/session.rs @@ -0,0 +1,201 @@ +//! 会话端口：索引 → `list_game_sessions`，事件流切片 → `read_game_log`。 + +use serde_json::{json, Value}; + +use unlucky_agent::port::{ + GameSessionPort, GameSessionSummary, LogEvent, LogPage, LogQuery, PortResult, +}; + +use super::events::SessionSource; + +/// M18 的会话索引 + 事件流。 +#[derive(Debug, Clone)] +pub struct CoreSessions { + source: SessionSource, +} + +impl CoreSessions { + /// `root` = `<数据根>/.ULL/data/agent/sessions`。 + #[must_use] + pub fn new(root: impl Into) -> Self { + Self { + source: SessionSource::new(root), + } + } +} + +fn summary_of( + entry: &unlucky_core::launch::session_index::SessionIndexEntry, +) -> GameSessionSummary { + GameSessionSummary { + session_id: entry.session_id.clone(), + instance_id: Some(entry.instance_id.clone()).filter(|id| !id.is_empty()), + instance_name: Some(entry.instance_name.clone()).filter(|name| !name.is_empty()), + game_version: Some(entry.game_version.clone()).filter(|v| !v.is_empty()), + started_at: Some(entry.started_at.clone()).filter(|v| !v.is_empty()), + ended_at: Some(entry.ended_at.clone()).filter(|v| !v.is_empty()), + duration_ms: entry.duration_ms, + exit_code: entry.exit_code, + exit_type: entry.exit_type.clone(), + silent_failure: entry.silent_failure, + window_detected: entry.window_detected, + event_count: entry.event_count, + crash_found: entry.crash_found, + diagnosis_top: entry.diagnosis_top.clone(), + } +} + +fn to_log_event(event: &Value, fallback_seq: u64) -> LogEvent { + LogEvent { + seq: event + .get("seq") + .and_then(Value::as_u64) + .unwrap_or(fallback_seq), + ts: event + .get("ts") + .and_then(Value::as_str) + .unwrap_or_default() + .to_string(), + t_ms: event.get("t_ms").and_then(Value::as_u64).unwrap_or(0), + kind: event + .get("kind") + .and_then(Value::as_str) + .unwrap_or_default() + .to_string(), + payload: event.get("payload").cloned().unwrap_or(Value::Null), + } +} + +impl GameSessionPort for CoreSessions { + fn list_sessions( + &self, + limit: usize, + instance_id: Option<&str>, + ) -> PortResult> { + 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; + + fn seed_session(root: &Path) { + let game_dir = root.join("game"); + std::fs::create_dir_all(&game_dir).expect("建目录"); + let entry = json!({ + "v": 1, + "session_id": "20261029T124501-9f3c2a", + "instance_id": "inst-1", + "instance_name": "1.20.1 Forge", + "game_version": "1.20.1", + "started_at": "2026-10-29T12:45:01.123Z", + "ended_at": "2026-10-29T12:46:31.123Z", + "duration_ms": 90000, + "exit_code": 1, + "exit_type": "application_error", + "silent_failure": false, + "window_detected": true, + "event_count": 2, + "log_path": "20261029T124501-9f3c2a.jsonl", + "crash_found": true, + "diagnosis_top": "integrity.forge_missing_library" + }); + std::fs::write(game_dir.join("index.jsonl"), format!("{entry}\n")).expect("写索引"); + let events = [ + json!({"seq":0,"ts":"2026-10-29T12:45:01.123Z","t_ms":0,"kind":"stdout","payload":{"line":"hi","level":"info"}}), + json!({"seq":1,"ts":"2026-10-29T12:45:02.123Z","t_ms":1000,"kind":"stderr","payload":{"line":"boom","level":"error"}}), + ]; + let text: String = events + .iter() + .map(|event| format!("{event}\n")) + .collect::(); + std::fs::write(game_dir.join("20261029T124501-9f3c2a.jsonl"), text).expect("写事件"); + } + + #[test] + fn lists_and_slices_a_session() { + let root = std::env::temp_dir().join(format!("ull-mcp-sessions-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&root); + seed_session(&root); + + let port = CoreSessions::new(root.clone()); + let sessions = port.list_sessions(10, None).expect("应能列出"); + assert_eq!(sessions.len(), 1); + assert_eq!(sessions[0].exit_code, Some(1)); + assert!(sessions[0].crash_found); + + let page = port + .read_log( + "20261029T124501", + &LogQuery { + max_events: 1, + kinds: vec!["stderr".to_string()], + ..LogQuery::default() + }, + ) + .expect("应能读"); + assert_eq!(page.total_events, 2); + assert_eq!(page.events.len(), 1); + assert_eq!(page.events[0].kind, "stderr"); + assert!(page.kind_counts.contains_key("stdout")); + + let _ = std::fs::remove_dir_all(&root); + } +} diff --git a/crates/cli/src/commands/agent/ports/setting.rs b/crates/cli/src/commands/agent/ports/setting.rs new file mode 100644 index 0000000..46f846b --- /dev/null +++ b/crates/cli/src/commands/agent/ports/setting.rs @@ -0,0 +1,211 @@ +//! 配置端口：`core::setting` 的直译（**唯一真相源**在 core，这里不复制校验规则）。 +//! +//! 三条纪律： +//! 1. 每次调用都重新 `SettingStore::load`——外部 MCP 客户端可能刚改了配置， +//! 缓存一份快照会让审计里的 `old` 骗人； +//! 2. **敏感值一律掩码**（M12 `Sensitivity::High` + agent 的凭据词表两道）： +//! 工具结果会回灌模型、也可能发往远端 LLM，AI 只需要知道「这个键是什么、怎么改」； +//! 3. **落点与 `ull config` 同源**（分流规则仍只在 `crate::context` 一处）：数据根键 +//! 读写便携目录那份 `launcher.json`，其余键读写解析后的数据根。只持一份路径时 +//! standard / `--data-dir` 模式下 AI 改 `core.data_mode` 会「写了没反应」 +//! （finding 20261031-worker-chore40-improve-agent-settingport-core-ai）。 + +use std::path::{Path, PathBuf}; + +use serde_json::{json, Map, Value}; +use unlucky_agent::confirm::Sensitivity; +use unlucky_agent::port::{PortResult, SettingChange, SettingKey, SettingPort}; +use unlucky_core::setting::keys::launcher_schema; +use unlucky_core::setting::spec::{Sensitivity as CoreSensitivity, ValueKind}; +use unlucky_core::setting::store::{SaveOutcome, SettingStore, SkipReason}; + +use crate::context::is_data_root_key; + +/// 掩码占位（与 CLI `config get` 同一串，读输出的人不用学两套）。 +pub const MASK: &str = ""; + +/// 把 `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/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..316cf53 --- /dev/null +++ b/crates/cli/src/commands/config.rs @@ -0,0 +1,341 @@ +//! `config get|set`：走 `core::setting` 的 schema API（单一真相源）。 +//! +//! # 落点（M40：与数据根解析同源） +//! +//! - **数据根键**（[`DATA_ROOT_KEYS`]：`core.data_mode` / `core.data_custom_root` / +//! `core.launcher_home` / `core.game_home`）→ 便携目录那份 `launcher.json` +//! （`/.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 = ""; + +/// `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 { + let path = ctx.setting_path_for(key); + let store = SettingStore::load(&path, launcher_schema()); + let schema = store.doc().schema().clone(); + + let Some(value) = store.effective(key) else { + return Err( + CliError::user("unknown_key", format!("配置键 `{key}` 不在 schema 里")) + .with_hint("`%prog% config get`（不带键）可以看到全部生效键"), + ); + }; + + let sensitive = is_sensitive(&schema, key); + let hidden = sensitive && !show_secret; + let shown = if hidden { + Value::String(MASK.to_string()) + } else { + value.clone() + }; + let problems = render_problems(&store); + let data = json!({ + "key": key, + "value": shown, + "redacted": hidden, + "sensitive": sensitive, + "path": path.display().to_string(), + "problems": problems, + }); + let mut human = vec![format!( + "{key} = {}{}", + render_value(&shown), + if hidden { + "（敏感键；加 --show-secret 显示明文）" + } else { + "" + } + )]; + human.push(format!("来自 {}", path.display())); + for problem in &problems { + human.push(format!("问题：{problem}")); + } + human.extend(source_note(ctx, key)); + Ok(Report::new(data, human)) +} + +/// 无键全量 dump：以数据根那份为底，`core.*` 数据根键换成便携目录那份的生效值。 +fn dump(ctx: &Ctx, show_secret: bool) -> Result { + 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)); + for problem in &problems { + human.push(format!("问题：{problem}")); + } + if masked { + human.push("（敏感值已掩码；加 --show-secret 显示明文）".to_string()); + } + Ok(Report::new( + json!({ + "path": path.display().to_string(), + "core_path": core_path.as_ref().map(|core| core.display().to_string()), + "config": document, + "redacted": masked, + "problems": problems, + "data_root": { + "mode": ctx.data.mode.as_str(), + "launcher_home": ctx.data.launcher_home.display().to_string(), + "game_home": ctx.data.game_home.display().to_string(), + }, + }), + human, + )) +} + +/// `ull config set `。 +/// +/// 敏感键的**旧值回显要掩码**（新值是用户刚敲进来的，照常回显）。 +/// +/// # Errors +/// +/// 键不在 schema、值不合法、文件只读/不可读、写盘失败时返回用户错误。 +pub fn set(ctx: &Ctx, key: &str, raw: &str) -> Result { + let path = ctx.setting_path_for(key); + let mut store = SettingStore::load(&path, launcher_schema()); + let sensitive = is_sensitive(store.doc().schema(), key); + let value = parse_value(raw); + let old = store.effective(key).cloned().map(|old| { + if sensitive { + Value::String(MASK.to_string()) + } else { + old + } + }); + store.set(key, value.clone()).map_err(|error| { + CliError::user("config_set", error.to_string()) + .with_hint(format!("键与取值范围见 {}", path.display())) + })?; + + let outcome = store.save().map_err(|error| { + CliError::user( + "config_save", + format!("写 {} 失败：{error}", path.display()), + ) + })?; + match &outcome { + SaveOutcome::Saved(saved) => { + let data = json!({ + "key": key, + "old": old, + "new": value, + "saved": saved.display().to_string(), + }); + let mut human = vec![ + format!( + "{key} = {}（原值 {}）", + render_value(&value), + render_value(&old.unwrap_or(Value::Null)) + ), + format!("已保存：{}", saved.display()), + ]; + human.extend(source_note(ctx, key)); + Ok(Report::new(data, human)) + } + SaveOutcome::Skipped(SkipReason::NotDirty) => Ok(Report::new( + json!({ "key": key, "new": value, "saved": null }), + vec![format!("{key} 已经是该值，未写盘")], + )), + SaveOutcome::Skipped(reason) => { + let error = CliError::user( + "config_read_only", + format!("{} 当前不可写（{}）", path.display(), reason.as_str()), + ); + // 不可写常常不是权限问题，而是文件内容让加载降级（`$schema` 认不出 / 版本更高）。 + let problems = render_problems(&store); + Err(if problems.is_empty() { + error.with_hint("修好文件权限/内容后重试") + } else { + error.with_hint(problems.join("；")) + }) + } + } +} + +/// 数据根键的落点说明（其余键不需要：它们的落点就是数据根本身）。 +fn source_note(ctx: &Ctx, key: &str) -> Option { + 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/tests.rs b/crates/cli/src/commands/config/tests.rs new file mode 100644 index 0000000..62a7a22 --- /dev/null +++ b/crates/cli/src/commands/config/tests.rs @@ -0,0 +1,256 @@ +//! [`super`] 的单测：数据根键与其余键的落点分流、dump 合并、`problems` 通道。 + +use std::path::{Path, PathBuf}; +use std::sync::atomic::{AtomicU64, Ordering}; +use std::time::{SystemTime, UNIX_EPOCH}; + +use serde_json::{json, Value}; + +use super::{dump, get, set}; +use crate::cli::Globals; +use crate::context::Ctx; + +/// 一次性临时目录（`Drop` 时清理；cli 没有 dev-dependency 的 tempfile）。 +struct TempDir(PathBuf); + +impl TempDir { + fn new(tag: &str) -> Self { + static COUNTER: AtomicU64 = AtomicU64::new(0); + let nanos = SystemTime::now() + .duration_since(UNIX_EPOCH) + .map_or(0, |duration| duration.as_nanos()); + let seq = COUNTER.fetch_add(1, Ordering::Relaxed); + let path = std::env::temp_dir().join(format!( + "ull-config-test-{tag}-{}-{seq}-{nanos}", + std::process::id() + )); + std::fs::create_dir_all(&path).expect("建临时目录"); + Self(path) + } + + fn path(&self) -> &Path { + &self.0 + } +} + +impl Drop for TempDir { + fn drop(&mut self) { + let _ = std::fs::remove_dir_all(&self.0); + } +} + +/// 正确的 `$schema`（写成真前缀，加载才不会降级）。 +fn schema_url() -> String { + use unlucky_core::setting::keys::launcher_version; + use unlucky_core::setting::schema::{SchemaId, SchemaRef}; + SchemaRef::new(SchemaId::LAUNCHER, launcher_version()).url() +} + +fn write_json(path: &Path, value: &Value) { + if let Some(parent) = path.parent() { + std::fs::create_dir_all(parent).expect("建目录"); + } + std::fs::write(path, value.to_string()).expect("写配置"); +} + +fn read_json(path: &Path) -> Value { + let bytes = std::fs::read(path).unwrap_or_else(|e| panic!("读 {} 失败：{e}", path.display())); + serde_json::from_slice(&bytes).expect("合法 JSON") +} + +fn ctx_with(globals: Globals, exe_dir: &Path) -> Ctx { + Ctx::resolve_in(&globals, Some(exe_dir.to_path_buf())).expect("解析数据根") +} + +/// 便携模式：两个落点是同一份文件，`core.data_mode` 改了立刻是生效值。 +#[test] +fn portable_mode_keeps_core_keys_in_one_file() { + let temp = TempDir::new("portable"); + let ctx = ctx_with(Globals::default(), temp.path()); + assert_eq!(ctx.data.mode.as_str(), "portable"); + assert_eq!( + ctx.setting_path_for("core.data_mode"), + ctx.launcher_config(), + "便携模式下两份路径本来就该重合" + ); + + set(&ctx, "core.data_mode", "standard").expect("写 core.data_mode"); + let file = temp + .path() + .join(".ULL") + .join("config") + .join("launcher.json"); + assert!(file.is_file(), "应落在 {}", file.display()); + assert_eq!(read_json(&file)["core"]["data_mode"], json!("standard")); + + let report = get(&ctx, Some("core.data_mode"), true).expect("读回来"); + // `core.*` 在 schema 里标了 `AiPolicy::sensitive()`（High），读路径默认掩码成 + // ``，所以要看生效值得像用户那样加 `--show-secret`。 + assert_eq!(report.data["value"], json!("standard")); + assert_eq!( + report.data["path"], + json!(file.display().to_string()), + "read 与 write 必须同一份" + ); +} + +/// standard 模式：数据根键走便携目录那份（与解析同源），其余键走数据根。 +#[test] +fn standard_mode_routes_core_keys_to_the_portable_file() { + let temp = TempDir::new("standard"); + let exe = temp.path().join("exe"); + let portable = exe.join(".ULL").join("config").join("launcher.json"); + let launcher_home = temp.path().join("lhome"); + write_json( + &portable, + &json!({ + "$schema": schema_url(), + "schemaVersion": 1, + "core": { + "data_mode": "standard", + "launcher_home": launcher_home.display().to_string(), + }, + }), + ); + + let ctx = ctx_with(Globals::default(), &exe); + assert_eq!(ctx.data.mode.as_str(), "standard"); + assert_eq!(ctx.data.launcher_home, launcher_home); + assert_ne!( + ctx.setting_path_for("core.data_mode"), + ctx.launcher_config() + ); + + let report = get(&ctx, Some("core.data_mode"), true).expect("读 core.data_mode"); + assert_eq!( + report.data["value"], + json!("standard"), + "get 展示的必须是真正生效的值" + ); + assert_eq!(report.data["path"], json!(portable.display().to_string())); + + // 普通键仍写数据根。 + set(&ctx, "download.concurrency", "16").expect("写 download.concurrency"); + let core_file = ctx.launcher_config(); + assert_eq!(read_json(&core_file)["download"]["concurrency"], json!(16)); + + // 数据根键写便携目录那份，且不动数据根那份的 core.*。 + set(&ctx, "core.data_mode", "portable").expect("写 core.data_mode"); + assert_eq!(read_json(&portable)["core"]["data_mode"], json!("portable")); + assert!( + read_json(&core_file)["core"].get("data_mode").is_none(), + "数据根那份不该被写入 core.data_mode" + ); +} + +/// `--data-dir` 模式：数据根由命令行钉死，core.* 仍落便携目录那份并给出提示。 +#[test] +fn data_dir_flag_routes_core_keys_to_portable_and_says_so() { + let temp = TempDir::new("datadir"); + let exe = temp.path().join("exe"); + std::fs::create_dir_all(&exe).expect("建 exe 目录"); + let data = temp.path().join("data"); + let globals = Globals { + data_dir: Some(data.clone()), + ..Globals::default() + }; + let ctx = ctx_with(globals, &exe); + assert_eq!(ctx.data.mode.as_str(), "custom"); + assert_eq!(ctx.data.launcher_home, data.join(".ULL")); + + let portable = exe.join(".ULL").join("config").join("launcher.json"); + set(&ctx, "core.data_mode", "standard").expect("写 core.data_mode"); + assert!(portable.is_file(), "应落在 {}", portable.display()); + assert!(!data + .join(".ULL") + .join("config") + .join("launcher.json") + .exists()); + + let report = get(&ctx, Some("core.data_mode"), true).expect("读回来"); + assert_eq!(report.data["value"], json!("standard")); + assert!( + report.human.iter().any(|line| line.contains("--data-dir")), + "{:?}", + report.human + ); +} + +/// 全量 dump：`core.*` 取便携目录那份的生效值，并标明两份文件与数据根。 +#[test] +fn dump_merges_core_keys_from_the_portable_file() { + let temp = TempDir::new("dump"); + let exe = temp.path().join("exe"); + let portable = exe.join(".ULL").join("config").join("launcher.json"); + let launcher_home = temp.path().join("home2"); + write_json( + &portable, + &json!({ + "$schema": schema_url(), + "schemaVersion": 1, + "core": { + "data_mode": "standard", + "launcher_home": launcher_home.display().to_string(), + }, + }), + ); + // 数据根那份写一个普通键（默认值不落盘，dump 里只有文件里真有的键）。 + write_json( + &launcher_home.join("config").join("launcher.json"), + &json!({ + "$schema": schema_url(), + "schemaVersion": 1, + "download": { "concurrency": 4 }, + }), + ); + let ctx = ctx_with(Globals::default(), &exe); + + let report = dump(&ctx, true).expect("全量 dump"); + assert_eq!( + report.data["config"]["core"]["data_mode"], + json!("standard") + ); + assert_eq!( + report.data["core_path"], + json!(portable.display().to_string()) + ); + assert_eq!(report.data["data_root"]["mode"], json!("standard")); + assert_eq!( + report.data["config"]["download"]["concurrency"], + json!(4), + "非 core.* 键仍取数据根那份" + ); +} + +/// 认不出的 `$schema` 前缀：值照读 + `problems` 里有 UnknownSchema，不再静默回落。 +#[test] +fn unknown_schema_prefix_warns_and_still_shows_file_values() { + let temp = TempDir::new("badschema"); + let exe = temp.path().join("exe"); + let portable = exe.join(".ULL").join("config").join("launcher.json"); + write_json( + &portable, + &json!({ + "$schema": "https://unlucky-launcher.local/schema/launcher/1.2.0.json", + "schemaVersion": 1, + "core": { "data_mode": "portable" }, + "download": { "concurrency": 32 }, + }), + ); + let ctx = ctx_with(Globals::default(), &exe); + + let report = get(&ctx, Some("download.concurrency"), false).expect("读普通键"); + assert_eq!(report.data["value"], json!(32), "值不该被回落成默认 8"); + let problems = report.data["problems"].as_array().expect("problems 数组"); + assert!( + problems + .iter() + .any(|problem| problem.as_str().is_some_and(|p| p.contains("$schema"))), + "{problems:?}" + ); + assert!( + report.human.iter().any(|line| line.contains("$schema")), + "{:?}", + report.human + ); +} diff --git a/crates/cli/src/commands/identity.rs b/crates/cli/src/commands/identity.rs new file mode 100644 index 0000000..3944f17 --- /dev/null +++ b/crates/cli/src/commands/identity.rs @@ -0,0 +1,216 @@ +//! `ull launch` 的账户选择：三轨账户 → [`AuthPlaceholders`]（唯一的身份出口）。 +//! +//! 选择规则（headless 没有交互，必须确定）： +//! - `--account `：按玩家名 / 登录名 / 条目 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..4a7fb7c --- /dev/null +++ b/crates/cli/src/commands/install/loader.rs @@ -0,0 +1,159 @@ +//! `ull install --loader [--loader-version ]`：加载器层的编排。 +//! +//! ```text +//! LoaderSource::resolve（官方 meta：版本列表 → profile JSON / installer profile） +//! → LoaderInstallPlan::build（纯计算：库清单 + loader 版本 JSON 落点） +//! → [--dry-run 到此为止，但多带一段 processors 计划] +//! → 原版已装？否 → vanilla::plan_and_install（先装原版） +//! → 需要 installer？→ 依赖库 → 选 Java → 串行跑 processors（M35） +//! → execute（loader 库并发下载 → 全量就绪才写 versions//.json） +//! → register（实例 versionId 指向 loader 版本） +//! ``` +//! +//! 「先装原版」是**硬前置**：loader 版本 JSON 只声明 `inheritsFrom`，jar 与资源都在原版那层， +//! 原版缺失时启动链必然断裂。已装则跳过（`is_version_installed` 判据 = 版本 JSON 在盘上）。 +//! +//! processors 段的顺序也是硬约束：**先跑 processors，再写版本 JSON**。版本清单存在是 +//! "这版装完了"的判据，抢在 processors 前写会留下一个启动必崩却被报成已安装的实例。 + +use unlucky_core::addon::loader::{ + LoaderError, LoaderInstallPlan, LoaderKind, LoaderPlanInput, LoaderSource, +}; +use unlucky_core::download::blocking::block_on; +use unlucky_core::download::cache::now_ms; +use unlucky_core::game::arguments::Environment; +use unlucky_core::game::install::execute; + +use super::report_loader::ProcessorSection; +use super::{ + build_engine, ensure_name_free, failure_error, loader_processors, map_install_error, + register_instance, report, report_loader, vanilla, CONCURRENCY, +}; +use crate::cli::InstallArgs; +use crate::context::Ctx; +use crate::error::CliError; +use crate::output::Report; + +/// 执行加载器安装。 +/// +/// # Errors +/// +/// 用法错误、加载器未知/不支持、元数据读取失败、原版装不上、库下载失败、 +/// installer processors 失败、实例登记失败。 +pub(super) fn run(ctx: &Ctx, args: &InstallArgs, kind: LoaderKind) -> Result { + let version = args.version.trim().to_string(); + if version.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 release = block_on(async { + let source = LoaderSource::new(&engine, &meta_cache); + source + .resolve(kind, &version, args.loader_version.as_deref()) + .await + }) + .map_err(|error: LoaderError| map_loader_error(&error, ctx))?; + + let name = args + .name + .clone() + .filter(|name| !name.trim().is_empty()) + .unwrap_or_else(|| release.version_id.clone()); + ensure_name_free(ctx, &name, &release.version_id)?; + + let plan = LoaderInstallPlan::build(LoaderPlanInput { + layout: &game, + release: &release, + environment: &Environment::host(), + vanilla_installed: game.is_version_installed(&version), + }); + let processor_plan = loader_processors::plan(ctx, &release)?; + + if args.dry_run { + let section = processor_plan.as_ref().map(|plan| ProcessorSection { + plan, + libraries: None, + run: None, + skipped: false, + }); + return Ok(report_loader::build( + ctx, &engine, now, true, &plan, None, None, &name, section, + )); + } + + if plan.vanilla_install_needed { + let (_, vanilla_report) = vanilla::plan_and_install( + ctx, + &engine, + &version, + false, + args.progress, + args.json_progress, + )?; + if let Some(report) = &vanilla_report { + if !report.is_complete() { + return Err(failure_error(report, ctx)); + } + } + } + + // installer processors 段：版本 JSON 已在盘上 = 上一轮早已跑完，整段跳过。 + let mut processor_libs = None; + let mut processor_run = None; + let mut processor_skipped = false; + if let Some(processor_plan) = &processor_plan { + if game.is_version_installed(&release.version_id) { + processor_skipped = true; + } else { + let (libraries, run) = loader_processors::execute(ctx, &engine, processor_plan, args)?; + processor_libs = Some(libraries); + processor_run = Some(run); + } + } + + let sink = report::progress_sink(args.progress, args.json_progress, plan.files().len()); + let install_report = block_on(execute(&engine, &plan.install, CONCURRENCY, sink)) + .map_err(|error| map_install_error(&error, ctx))?; + if !install_report.is_complete() { + return Err(failure_error(&install_report, ctx)); + } + + let registration = register_instance(ctx, &name, &release.version_id)?; + + let section = processor_plan + .as_ref() + .map(|processor_plan| ProcessorSection { + plan: processor_plan, + libraries: processor_libs.as_ref(), + run: processor_run.as_ref(), + skipped: processor_skipped, + }); + Ok(report_loader::build( + ctx, + &engine, + now, + false, + &plan, + Some(&install_report), + Some(®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) +} diff --git a/crates/cli/src/commands/install/loader_processors.rs b/crates/cli/src/commands/install/loader_processors.rs new file mode 100644 index 0000000..60d1347 --- /dev/null +++ b/crates/cli/src/commands/install/loader_processors.rs @@ -0,0 +1,181 @@ +//! 加载器的 installer processors 段（M35）：依赖库下载 → 选 Java → 串行执行。 +//! +//! 只在 `LoaderSupport::RequiresInstaller` 的版本上出现（Forge 1.13~1.20.x 主流段、 +//! NeoForge 1.20.5+）。其余加载器（Fabric/Quilt、Forge spec 0）走纯 json 路线，这一段整块跳过。 +//! +//! ```text +//! ProcessorPlan::build（core，纯计算：变量表 + 每步命令行 + 依赖库清单） +//! → download_libraries（M27 引擎：镜像/健康度/退避/校验） +//! → select_java（M33 解析链：托管 > JAVA_HOME > PATH > 扫盘） +//! → run（串行 java -cp，产物存在性硬校验、摘要软校验） +//! ``` +//! +//! 顺序上与版本 JSON 的关系是**硬约束**：processors 全部成功之后才让 M27 的 `execute` +//! 写 `versions//.json`——那份清单是"这版装完了"的判据，抢在 processors 前写会 +//! 留下一个启动必崩却被报成"已安装"的实例。 + +use std::sync::Arc; + +use unlucky_core::addon::loader::processors::{ + self, ProcessorError, ProcessorPlan, ProcessorPlanInput, ProcessorRun, StepOutcome, StepSink, +}; +use unlucky_core::addon::loader::LoaderRelease; +use unlucky_core::download::blocking::block_on; +use unlucky_core::download::DownloadEngine; +use unlucky_core::game::arguments::Environment; +use unlucky_core::game::install::InstallReport; + +use super::{failure_error, report, CONCURRENCY}; +use crate::cli::InstallArgs; +use crate::context::Ctx; +use crate::error::CliError; +use crate::output::progress_line; + +/// 组执行计划；不需要跑 installer 的加载器返回 `None`。 +/// +/// # Errors +/// +/// install profile 的 `data` 表/`processors` 形状不对时返回 `processor_plan` 错误。 +pub(super) fn plan(ctx: &Ctx, release: &LoaderRelease) -> Result, CliError> { + if !release.requires_installer() { + return Ok(None); + } + let (Some(profile), Some(installer)) = ( + release.install_profile.as_ref(), + release.installer.as_deref(), + ) else { + return Err(CliError::user( + "loader_metadata", + format!( + "{} {} 需要跑 installer processors，但没拿到 install profile / installer 路径", + release.kind.label(), + release.loader_version + ), + ) + .with_hint("重跑一次（元数据缓存可能不完整）")); + }; + let game = ctx.game(); + let scratch = ctx + .layout() + .cache() + .join("processors") + .join(safe_name(&release.version_id)); + let plan = ProcessorPlan::build(ProcessorPlanInput { + kind: release.kind, + mc_version: &release.mc_version, + version_id: &release.version_id, + profile, + layout: &game, + installer, + scratch: &scratch, + environment: &Environment::host(), + }) + .map_err(map_processor_error)?; + Ok(Some(plan)) +} + +/// 下载依赖库 + 执行 processors。 +/// +/// # Errors +/// +/// 依赖库下载失败（稳定码沿用 `install_*`）、找不到可用 Java、processor 非零退出、 +/// 产物没落盘。 +pub(super) fn execute( + ctx: &Ctx, + engine: &DownloadEngine, + plan: &ProcessorPlan, + args: &InstallArgs, +) -> Result<(InstallReport, ProcessorRun), CliError> { + let sink = report::progress_sink(args.progress, args.json_progress, plan.libraries.len()); + let libraries = block_on(processors::download_libraries( + engine, + &plan.libraries, + CONCURRENCY, + sink, + )); + if !libraries.is_complete() { + return Err(failure_error(&libraries, ctx)); + } + + let managed = ctx.layout().java_managed(); + let Some(java) = processors::select_java(&managed, &plan.java_requirement) else { + return Err(CliError::user( + "processor_java_missing", + format!( + "跑 installer processors 需要 {}，但一个可用的 Java 都没找到", + plan.java_requirement.describe() + ), + ) + .with_hint(format!( + "`%prog% java install {}` 装一个托管 JDK，或把 JAVA_HOME 指向可用的 JDK（托管目录 {}）", + plan.java_requirement.minimum, + managed.display() + ))); + }; + let sink = step_sink(args.progress, args.json_progress, plan.step_count()); + let run = processors::run(plan, &java, sink).map_err(map_processor_error)?; + Ok((libraries, run)) +} + +/// 每步一行的实时进度（只写 stderr）。 +fn step_sink(enabled: bool, json_mode: bool, total: usize) -> Option { + 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..2d3553f --- /dev/null +++ b/crates/cli/src/commands/install/mod.rs @@ -0,0 +1,151 @@ +//! `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） +//! ``` +//! +//! CLI 只做四件事：建下载引擎、把计划/结果排版成人读与 `--json` 两种形态 +//! （[`report`] / [`report_loader`]）、把错误翻译成稳定错误码、往 stderr 打实时进度。 +//! 所有版本/继承/库/下载逻辑都在 core（CLI 不复制任何路径或镜像规则）。 + +mod loader; +mod loader_processors; +mod report; +mod report_loader; +mod vanilla; + +use std::sync::Arc; + +use unlucky_core::addon::loader::LoaderKind; +use unlucky_core::download::cache::now_ms; +use unlucky_core::download::region::{decide_from, load_cached, store_cached}; +use unlucky_core::download::region_system::detect_signals; +use unlucky_core::download::{ + ContentCache, DownloadEngine, DownloadErrorKind, EngineConfig, HealthRegistry, MirrorTable, +}; +use unlucky_core::game::install::{InstallError, InstallReport, Registration}; + +use crate::cli::InstallArgs; +use crate::context::Ctx; +use crate::error::CliError; +use crate::output::Report; + +/// 文件级并发上限：资源是海量小文件，16 路足够压满带宽又不至于打爆镜像。 +pub(super) const CONCURRENCY: usize = 16; + +/// 执行 `install`：按 `--loader` 分发。 +/// +/// # Errors +/// +/// 用法错误、加载器未知、版本不存在、网络失败、校验不符、写盘失败、实例清单损坏。 +pub fn run(ctx: &Ctx, args: &InstallArgs) -> Result { + match args + .loader + .as_deref() + .map(str::trim) + .filter(|value| !value.is_empty()) + { + None | Some("vanilla") | Some("none") => vanilla::run(ctx, args), + Some(raw) => match LoaderKind::parse(raw) { + Some(kind) => loader::run(ctx, args, kind), + None => Err( + CliError::user("loader_unknown", format!("未知加载器 `{raw}`")) + .with_hint("--loader 取值：vanilla / fabric / quilt / neoforge / forge"), + ), + }, + } +} + +/// 登记实例（幂等）：`profiles.json` + `config/instances/.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/`，地区判定走 24h 缓存 + 环境信号。 +/// +/// 地区判定**不做网络探测**（P2 首版；探测开关属设置层接线）， +/// 因此中文环境默认镜像优先、其它环境直连——与 D7 的"不探测时"约定一致。 +pub(super) fn build_engine(ctx: &Ctx) -> DownloadEngine { + let layout = ctx.layout(); + let cache_root = layout.cache(); + let now = now_ms(); + let region_path = cache_root.join("region.json"); + let region = load_cached(®ion_path, now).unwrap_or_else(|| { + let profile = decide_from(&detect_signals(), now); + let _ = store_cached(®ion_path, &profile); + profile + }); + DownloadEngine::new( + EngineConfig::default(), + Arc::new(MirrorTable::builtin()), + Arc::new(region), + Arc::new(HealthRegistry::open_in(&cache_root, now)), + Arc::new(ContentCache::open(&cache_root)), + ) +} + +/// 同名但绑定别的版本 → 冲突；同名同版本视为重装（复用实例，允许）。 +pub(super) fn ensure_name_free(ctx: &Ctx, name: &str, version: &str) -> Result<(), CliError> { + let profiles = super::instances::read_profiles(ctx)?; + let conflict = profiles + .profiles + .iter() + .find(|profile| profile.name == name && profile.version_id != version); + match conflict { + Some(profile) => Err(CliError::user( + "instance_exists", + format!("同名实例已存在：{name}（绑定版本 {}）", profile.version_id), + ) + .with_hint("用 --name 换个名字，或 `%prog% instances list` 看看现有实例")), + None => Ok(()), + } +} + +/// 安装期错误 → CLI 错误（保留稳定错误码与提示）。 +pub(super) fn map_install_error(error: &InstallError, ctx: &Ctx) -> CliError { + let hint = match error.hint() { + Some(hint) => format!("{hint}（游戏根：{}）", ctx.game().root().display()), + None => format!("游戏根：{}", ctx.game().root().display()), + }; + CliError::user(error.kind().as_str(), error.message().to_string()).with_hint(hint) +} + +/// 有文件失败 → 按"最严重的失败类别"给稳定码，并列出前几条明细。 +pub(super) fn failure_error(report: &InstallReport, ctx: &Ctx) -> CliError { + let code = match report.failure_kind() { + Some(DownloadErrorKind::Integrity) => "install_integrity", + Some(DownloadErrorKind::Io) => "install_io", + _ => "install_network", + }; + let mut message = format!( + "{} 个文件没下成（共 {} 个）", + report.failed(), + report.files.len() + ); + for outcome in report.failures(3) { + if let Some(failure) = &outcome.failure { + message.push_str(&format!("；{}：{}", outcome.name, failure.message)); + } + } + CliError::user(code, message).with_hint(format!( + "重跑 `%prog% install` 会续传并跳过已就绪文件；游戏根 {}", + ctx.game().root().display() + )) +} diff --git a/crates/cli/src/commands/install/report.rs b/crates/cli/src/commands/install/report.rs new file mode 100644 index 0000000..af04893 --- /dev/null +++ b/crates/cli/src/commands/install/report.rs @@ -0,0 +1,262 @@ +//! 安装结果的两种呈现形态：人类可读行 + `--json` 载荷，外加 stderr 实时进度。 +//! +//! 拆出来是因为 `install` 的流程（规划 → 下载 → 登记）与排版彼此独立： +//! 前者要能读懂，后者要能被脚本断言。`--dry-run` 与真实安装共用同一份排版， +//! 差别只是多出逐文件清单与源选择。 + +use std::sync::atomic::{AtomicUsize, Ordering}; +use std::sync::Arc; + +use serde_json::json; +use unlucky_core::download::DownloadEngine; +use unlucky_core::game::install::{ + FileOutcome, InstallPlan, InstallReport, ProgressSink, Registration, +}; + +use crate::context::Ctx; +use crate::output::{progress_line, Report}; + +/// 每处理多少个文件打一行进度（3000 个资源下约 90 行，够用又不刷屏）。 +const PROGRESS_EVERY: usize = 32; + +/// 进度里最多逐条打印几条失败（其余交给最终错误汇总）。 +const MAX_PROGRESS_FAILURES: usize = 5; + +/// 实时进度回调（只写 stderr，不污染 `--json` 的 stdout）。 +/// +/// 两种形态：人类模式打文本行；`--json` 模式打 **JSONL**（一行一条事件，`event` 字段分流）， +/// 这样脚本既能吃 stdout 的最终信封，也能实时跟进而不必解析文本。 +/// +/// 失败行只打前几条：整源不可达时会一口气失败上千个文件，全打出来既没用又淹没原因。 +pub fn progress_sink(enabled: bool, json: bool, total: usize) -> Option { + if !enabled { + return None; + } + let done = Arc::new(AtomicUsize::new(0)); + let failures = Arc::new(AtomicUsize::new(0)); + Some(Arc::new(move |outcome: &FileOutcome| { + let index = done.fetch_add(1, Ordering::Relaxed) + 1; + if let Some(failure) = &outcome.failure { + let seen = failures.fetch_add(1, Ordering::Relaxed); + if seen < MAX_PROGRESS_FAILURES { + emit( + json, + json!({ + "event": "file_failed", + "done": index, + "total": total, + "name": outcome.name, + "role": outcome.role.as_str(), + "kind": failure.kind.as_str(), + "message": failure.message, + }), + &format!("失败 {index}/{total} {}：{}", outcome.name, failure.message), + ); + } else if seen == MAX_PROGRESS_FAILURES { + emit( + json, + json!({"event": "progress_truncated", "suppressed_after": MAX_PROGRESS_FAILURES}), + "（更多失败不再逐条打印，见最终错误汇总）", + ); + } + return; + } + if index.is_multiple_of(PROGRESS_EVERY) || index == total { + emit( + json, + json!({"event": "progress", "done": index, "total": total}), + &format!("下载 {index}/{total}"), + ); + } + })) +} + +/// 一条进度：JSONL 模式打序列化后的一行，人类模式打短文本。 +fn emit(json_mode: bool, record: serde_json::Value, text: &str) { + if json_mode { + progress_line(&record.to_string()); + } else { + progress_line(text); + } +} + +/// 排版一次安装结果。 +#[allow(clippy::too_many_arguments)] +pub fn build( + ctx: &Ctx, + engine: &DownloadEngine, + now: u64, + dry_run: bool, + plan: &InstallPlan, + report: Option<&InstallReport>, + registration: Option<&Registration>, + name: &str, + version: &str, +) -> Report { + let samples = if dry_run { + plan.source_samples(engine, now) + } else { + Vec::new() + }; + let mut data = json!({ + "dry_run": dry_run, + "version_id": plan.version_id, + "jar_id": plan.jar_id, + "game_root": plan.game_root.display().to_string(), + "plan": plan.summary_json(), + "result": report.map(|report| json!({ + "downloaded": report.downloaded(), + "skipped": report.skipped(), + "failed": report.failed(), + "bytes": report.bytes(), + "version_json": report.version_json.as_ref().map(|path| path.display().to_string()), + "warnings": report.warnings, + "files": report.files.iter().map(outcome_json).collect::>(), + })), + "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(" → ") + )); + } + for warning in &plan.warnings { + human.push(format!("告警: {warning}")); + } + if let Some(report) = report { + human.push(format!( + "下载 {} 个 / 跳过 {} 个已就绪 / 失败 {} 个（本次 {}）", + report.downloaded(), + report.skipped(), + report.failed(), + human_bytes(report.bytes()) + )); + if let Some(path) = &report.version_json { + human.push(format!("版本清单: {}", path.display())); + } + } + match registration { + Some(registration) => human.push(format!( + "已登记实例 {}（{}）→ 版本 {}（{}）", + name, + registration.profile.id.as_str(), + version, + if registration.created { + "新建" + } else { + "已存在，复用" + } + )), + None => human.push("（--dry-run：未下载任何文件，未登记实例）".to_string()), + } + human +} + +/// 字节 → 人读（MB/GB 一位小数，KB 取整；不做假精度）。 +pub fn human_bytes(bytes: u64) -> String { + const KB: u64 = 1024; + const MB: u64 = 1024 * KB; + const GB: u64 = 1024 * MB; + if bytes >= GB { + format!("{:.1} GB", bytes as f64 / GB as f64) + } else if bytes >= MB { + format!("{:.1} MB", bytes as f64 / MB as f64) + } else if bytes >= KB { + format!("{} KB", bytes / KB) + } else { + format!("{bytes} B") + } +} + +#[cfg(test)] +mod tests { + use super::human_bytes; + + #[test] + fn formats_sizes_without_fake_precision() { + assert_eq!(human_bytes(0), "0 B"); + assert_eq!(human_bytes(1023), "1023 B"); + assert_eq!(human_bytes(1024), "1 KB"); + assert_eq!(human_bytes(1024 * 1024), "1.0 MB"); + assert_eq!(human_bytes(3 * 1024 * 1024 * 1024), "3.0 GB"); + } +} diff --git a/crates/cli/src/commands/install/report_loader.rs b/crates/cli/src/commands/install/report_loader.rs new file mode 100644 index 0000000..d94d215 --- /dev/null +++ b/crates/cli/src/commands/install/report_loader.rs @@ -0,0 +1,274 @@ +//! 加载器安装的呈现形态（人类可读行 + `--json` 载荷）。 +//! +//! 与 [`super::report`] 的分工：那边是"原版安装"（客户端 jar + 资源 + 库），这边是 +//! "叠在原版上的 loader 层"（只有库）。共用同一套进度回调与字节格式化。 + +use serde_json::json; +use unlucky_core::addon::loader::processors::{ProcessorPlan, ProcessorRun}; +use unlucky_core::addon::loader::LoaderInstallPlan; +use unlucky_core::download::DownloadEngine; +use unlucky_core::game::install::{InstallReport, Registration}; + +use super::report::human_bytes; +use crate::context::Ctx; +use crate::output::Report; + +/// processors 段（M35）的报告输入：计划 + 依赖库下载结果 + 执行结果。 +/// +/// `--dry-run` 只有 `plan`；幂等跳过时 `libraries`/`run` 都是 `None` 且 `skipped = true`。 +pub struct ProcessorSection<'a> { + /// 执行计划（dry-run 也带上：将执行的 processor 清单 + 所需 Java）。 + pub plan: &'a ProcessorPlan, + /// processor 依赖库的下载结果。 + pub libraries: Option<&'a InstallReport>, + /// 执行结果。 + pub run: Option<&'a ProcessorRun>, + /// 整段跳过（版本 JSON 已在盘上 = processors 早已跑完）。 + pub skipped: bool, +} + +/// 排版一次加载器安装结果。 +/// +/// 参数多是因为载荷本身就多：计划（loader 版本 + 库）、processors 段、执行结果、实例登记、 +/// `--dry-run` 的源选择样本。拆成结构体会让调用方多写十行，不如保持扁平。 +#[allow(clippy::too_many_arguments)] +pub fn build( + ctx: &Ctx, + engine: &DownloadEngine, + now: u64, + dry_run: bool, + plan: &LoaderInstallPlan, + report: Option<&InstallReport>, + registration: Option<&Registration>, + name: &str, + processors: Option>, +) -> Report { + let samples = if dry_run { + plan.install.source_samples(engine, now) + } else { + Vec::new() + }; + let mut data = json!({ + "dry_run": dry_run, + "loader": plan.release.to_json(), + "vanilla_install_needed": plan.vanilla_install_needed, + "game_root": plan.install.game_root.display().to_string(), + "plan": plan.summary_json(), + "result": report.map(|report| json!({ + "downloaded": report.downloaded(), + "skipped": report.skipped(), + "failed": report.failed(), + "bytes": report.bytes(), + "version_json": report.version_json.as_ref().map(|path| path.display().to_string()), + "warnings": report.warnings, + })), + "instance": registration.map(|registration| json!({ + "id": registration.profile.id.as_str(), + "name": registration.profile.name, + "version_id": registration.profile.version_id, + "created": registration.created, + "config_path": registration.config_path.display().to_string(), + "profiles_path": ctx.profiles_config().display().to_string(), + })), + }); + if dry_run { + data["files"] = json!(plan.install.files_json()); + data["sources"] = json!(samples); + } + if let Some(section) = &processors { + data["processors"] = processor_json(section); + } + + Report::new( + data, + human_lines( + dry_run, + plan, + report, + registration, + &samples, + name, + processors.as_ref(), + ), + ) +} + +/// processors 段的 JSON 载荷（计划 + 依赖库结果 + 逐步骤结果）。 +fn processor_json(section: &ProcessorSection<'_>) -> serde_json::Value { + let mut node = section.plan.to_json(); + if let Some(object) = node.as_object_mut() { + object.insert("skipped".to_string(), json!(section.skipped)); + object.insert( + "libraries_result".to_string(), + json!(section.libraries.map(|report| json!({ + "downloaded": report.downloaded(), + "skipped": report.skipped(), + "failed": report.failed(), + "bytes": report.bytes(), + }))), + ); + object.insert( + "run".to_string(), + json!(section.run.map(ProcessorRun::to_json)), + ); + } + node +} + +fn human_lines( + dry_run: bool, + plan: &LoaderInstallPlan, + report: Option<&InstallReport>, + registration: Option<&Registration>, + samples: &[serde_json::Value], + name: &str, + processors: Option<&ProcessorSection<'_>>, +) -> Vec { + let release = &plan.release; + let mut human = Vec::new(); + human.push(format!( + "{} {}《{} {}》（继承原版 {}，主类 {}）", + if dry_run { + "加载器安装计划" + } else { + "已安装加载器" + }, + release.kind.label(), + release.mc_version, + release.loader_version, + release.mc_version, + release.version_json.main_class.as_deref().unwrap_or("?"), + )); + human.push(format!( + " 版本 id {} → {}", + release.version_id, + plan.install.version_json_path.display() + )); + human.push(format!( + " 原版 {}", + if plan.vanilla_install_needed { + "未安装：执行时先装原版" + } else { + "已安装：跳过" + } + )); + let (total_bytes, unknown) = plan.install.total_bytes(); + human.push(format!( + " loader 库 {} 个 / {}{}", + plan.install.file_count(), + human_bytes(total_bytes), + if unknown > 0 { + format!(" + {unknown} 个大小未知") + } else { + String::new() + } + )); + for sample in samples { + let sources: Vec<&str> = sample["candidates"] + .as_array() + .map(|list| { + list.iter() + .filter_map(|candidate| candidate["source"].as_str()) + .collect() + }) + .unwrap_or_default(); + human.push(format!( + " 源选择 {} → {}", + sample["label"].as_str().unwrap_or_default(), + sources.join(" → ") + )); + } + for warning in plan.warnings() { + human.push(format!("告警: {warning}")); + } + if let Some(section) = processors { + human.extend(processor_lines(section)); + } + if let Some(report) = report { + human.push(format!( + "下载 {} 个 / 跳过 {} 个已就绪 / 失败 {} 个（本次 {}）", + report.downloaded(), + report.skipped(), + report.failed(), + human_bytes(report.bytes()) + )); + if let Some(path) = &report.version_json { + human.push(format!("loader 版本清单: {}", path.display())); + } + } + match registration { + Some(registration) => human.push(format!( + "已登记实例 {}（{}）→ 版本 {}（{}）", + name, + registration.profile.id.as_str(), + registration.profile.version_id, + if registration.created { + "新建" + } else { + "已存在，复用" + } + )), + None => human.push("（--dry-run：未下载任何文件，未登记实例）".to_string()), + } + human +} + +/// processors 段的人读行（计划 / 依赖库 / 逐步骤 / 告警）。 +fn processor_lines(section: &ProcessorSection<'_>) -> Vec { + let plan = section.plan; + let mut lines = Vec::new(); + lines.push(format!( + " installer processors {} 步，需要 {}（installer {}）", + plan.step_count(), + plan.java_requirement.describe(), + plan.installer.display() + )); + if section.skipped { + lines.push(" 版本清单已存在：processors 整段跳过（幂等）".to_string()); + } + if let Some(libraries) = section.libraries { + lines.push(format!( + " processor 依赖库 {} 个：下载 {} / 跳过 {} / 失败 {}", + plan.libraries.len(), + libraries.downloaded(), + libraries.skipped(), + libraries.failed() + )); + } + if let Some(run) = section.run { + lines.push(format!( + " Java {}（{}）{}", + run.java + .major + .map_or_else(|| "未知".to_string(), |major| major.to_string()), + run.java.origin.as_str(), + run.java.binary.display() + )); + let total = run.steps.len(); + for step in &run.steps { + lines.push(format!( + " [{}/{}] {} → {}{}", + step.index, + total, + step.label, + if step.status.as_str() == "skipped" { + "跳过（产物已就绪）".to_string() + } else { + format!("执行 {} ms", step.elapsed_ms) + }, + if step.outputs > 0 { + format!("（产物 {} 个）", step.outputs) + } else { + String::new() + } + )); + } + for warning in &run.warnings { + lines.push(format!(" 告警: {warning}")); + } + } + for warning in &plan.warnings { + lines.push(format!(" 告警: {warning}")); + } + lines +} diff --git a/crates/cli/src/commands/install/vanilla.rs b/crates/cli/src/commands/install/vanilla.rs new file mode 100644 index 0000000..b0a074a --- /dev/null +++ b/crates/cli/src/commands/install/vanilla.rs @@ -0,0 +1,160 @@ +//! `ull install `（无加载器）：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, 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 = report::progress_sink(progress, json_progress, plan.file_count()); + let report = execute(engine, &plan, CONCURRENCY, sink).await?; + Ok(Attempt { + plan, + report: Some(report), + }) + }) + .map(|attempt| (attempt.plan, attempt.report)) + .map_err(|error: InstallError| map_install_error(&error, ctx)) +} + +/// 一次安装尝试的产物（`--dry-run` 只有计划）。 +struct Attempt { + plan: InstallPlan, + report: Option, +} diff --git a/crates/cli/src/commands/instances.rs b/crates/cli/src/commands/instances.rs new file mode 100644 index 0000000..95a059d --- /dev/null +++ b/crates/cli/src/commands/instances.rs @@ -0,0 +1,90 @@ +//! `instances list`：实例与已安装版本的总览。 +//! +//! 安装/登记在 [`super::install`]；这里只读（`profiles.json` + `versions/` 的存在性）。 +//! 读 `profiles.json` 的实现委托给 `core::game::install::instance`，避免 CLI 自带一份 +//! 解析逻辑（同一份文件两处解析迟早会漂移）。 + +use std::path::PathBuf; + +use serde_json::{json, Value}; +use unlucky_core::game::install::instance::read_profiles as read_profiles_from_layout; +use unlucky_core::game::ProfileList; + +use crate::context::Ctx; +use crate::error::CliError; +use crate::output::Report; + +/// `ull instances list`。 +/// +/// # Errors +/// +/// `profiles.json` 读不了或解析失败时返回用户错误。 +pub fn list(ctx: &Ctx) -> Result { + 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, + })); + } + + 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()) +} diff --git a/crates/cli/src/commands/java.rs b/crates/cli/src/commands/java.rs new file mode 100644 index 0000000..1ab3622 --- /dev/null +++ b/crates/cli/src/commands/java.rs @@ -0,0 +1,365 @@ +//! Java 运行时：`ull java list` / `install` / `vendors`（D13 v1 + D23 v2）。 +//! +//! 四件事：建下载引擎、把 core 的结果排成人读与 `--json` 两种形态、把错误翻成稳定码、 +//! 从设置里取 JDK 的落点与发行版优先级。探测/下载/解压/映射/回退链全在 `core::game::java`。 +//! +//! D23 之后的三个用户可见变化： +//! +//! 1. **落点可选**：`java.installRoot` 设了就装到那里；否则 Standard 数据模式装到 +//! `%APPDATA%\Java\<发行方>\<版本>\`（mac/Linux 见 `game::java::location`）， +//! Portable 仍在数据根 `java-managed/`（v1 布局不变）； +//! 2. **发行版可选**：`--vendor temurin|oracle|microsoft|zulu` 钉死一家；不给就按 +//! `java.vendorPriority` → 地区默认序跑回退链，降级原因进 `--json` 的 `chain` 块； +//! 3. **`java vendors`** 一眼看清四家的可用性、镜像与当前顺序。 + +use std::path::{Path, PathBuf}; +use std::sync::Arc; + +use serde_json::{json, Value}; +use unlucky_core::download::blocking::block_on; +use unlucky_core::download::cache::now_ms; +use unlucky_core::download::region::{decide_from, load_cached, store_cached}; +use unlucky_core::download::region_system::detect_signals; +use unlucky_core::download::{ + ContentCache, DownloadEngine, EngineConfig, HealthRegistry, MirrorTable, RegionProfile, +}; +use unlucky_core::game::java::{ + self, location, vendor, InstallRequest, JavaOrigin, JavaRuntime, JdkVendor, LocationMode, + DEFAULT_MAJOR, +}; +use unlucky_core::launch::request::JavaSelection; +use unlucky_core::platform::paths::ProcessEnv; +use unlucky_core::setting::keys::launcher_schema; +use unlucky_core::setting::store::SettingStore; + +use crate::context::Ctx; +use crate::error::CliError; +use crate::output::Report; + +pub use super::java_launch::{resolve_for_launch, LaunchJava}; +pub use super::java_vendors::vendors; + +/// 可自动安装的最老大版本（再老的 Temurin 没有 GA 产物）。 +const MIN_INSTALLABLE_MAJOR: u32 = 8; + +/// 装配用的 Java 选择（`--java` > `JAVA_HOME` > PATH 上的 `java`）。 +/// +/// `snapshot::prepare` 调它拿 [`JavaSelection`]；真正的来源优先级在 +/// [`resolve_for_launch`] 里求值（那一步还会看托管目录与版本要求）。 +#[must_use] +pub fn selection(explicit: Option<&Path>) -> JavaSelection { + let (binary, origin) = match explicit { + Some(path) => (path.to_path_buf(), JavaOrigin::Instance), + None => match env_java() { + Some(binary) => (binary, JavaOrigin::JavaHome), + None => (PathBuf::from(java::java_binary_name()), JavaOrigin::Path), + }, + }; + let runtime = java::probe(&binary, origin); + JavaSelection::new(binary, runtime.major.unwrap_or(DEFAULT_MAJOR), runtime.bits) +} + +/// 托管 JDK 可能存在的全部安装根（Portable 数据根 + Standard/Custom 落点，D23 后不止一个）。 +#[must_use] +pub fn managed_roots(ctx: &Ctx) -> Vec { + 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()) +} + +/// 建下载引擎：内容寻址缓存落 `.ULL/cache/`，地区判定走 24h 缓存 + 环境信号。 +fn build_engine(ctx: &Ctx) -> DownloadEngine { + let layout = ctx.layout(); + let cache_root = layout.cache(); + let now = now_ms(); + let region_path = cache_root.join("region.json"); + let region = load_cached(®ion_path, now).unwrap_or_else(|| { + let profile = decide_from(&detect_signals(), now); + let _ = store_cached(®ion_path, &profile); + profile + }); + DownloadEngine::new( + EngineConfig::default(), + Arc::new(MirrorTable::builtin()), + Arc::new(region), + Arc::new(HealthRegistry::open_in(&cache_root, now)), + Arc::new(ContentCache::open(&cache_root)), + ) +} + +/// JDK 下载/解压错误 → CLI 错误（保留稳定码与提示）。 +fn map_java_error(error: java::JavaError) -> CliError { + let cli = CliError::user(error.code(), error.message().to_string()); + match error.hint() { + Some(hint) => cli.with_hint(hint.to_string()), + None => cli, + } +} + +/// `JAVA_HOME/bin/java`（存在才返回）。 +fn env_java() -> Option { + let home = std::env::var_os("JAVA_HOME")?; + let binary = PathBuf::from(home) + .join("bin") + .join(java::java_binary_name()); + binary.is_file().then_some(binary) +} + +/// 运行时 → 展示标签（托管项带上 vendor）。 +fn source_label(runtime: &JavaRuntime) -> String { + match &runtime.vendor { + Some(vendor) => format!("{} · {vendor}", runtime.origin.as_str()), + None => runtime.origin.as_str().to_string(), + } +} + +/// 当前地区档案（`java vendors` 展示「国内/国外」口径；也给 GUI 复用）。 +#[must_use] +pub fn region_profile(ctx: &Ctx) -> RegionProfile { + build_engine(ctx).region().clone() +} diff --git a/crates/cli/src/commands/java_launch.rs b/crates/cli/src/commands/java_launch.rs new file mode 100644 index 0000000..16f374d --- /dev/null +++ b/crates/cli/src/commands/java_launch.rs @@ -0,0 +1,129 @@ +//! 启动期的 Java 解析（`ull launch` 用）：实例覆盖 > 托管匹配 > 系统。 +//! +//! 从 `commands/java.rs` 拆出来（那边还要放 list/install/vendors，超 400 行硬上限）。 +//! 这里的职责只有两条：①按 D13 的优先链挑一个 Java；②把结果整理成 `--json` 块与告警行。 +//! 真正「谁优先」的判定在 `core::game::java::probe` / `select`（纯函数），本文件只做装配。 + +use std::path::{Path, PathBuf}; + +use serde_json::{json, Value}; +use unlucky_core::game::java::{self, JavaMismatch, JavaOrigin, JavaRequirement, JavaRuntime}; + +use crate::context::Ctx; + +/// 启动期的 Java 解析结果。 +#[derive(Debug, Clone)] +pub struct LaunchJava { + /// 喂给 `PlanInput.java` 的显式覆盖；`None` = 让 `snapshot::prepare` 按系统兜底。 + pub override_path: Option, + /// 实际选中的运行时。 + pub runtime: Option, + /// 目标版本对 Java 的要求。 + pub requirement: JavaRequirement, + /// 不符说明（只提示，不阻断）。 + pub mismatch: Option, +} + +impl LaunchJava { + /// `--json` 的 `java` 块（app 层 GUI 弹窗 P1 后直接吃这份数据）。 + #[must_use] + pub fn to_json(&self) -> Value { + let runtime = self.runtime.as_ref(); + json!({ + "binary": runtime.map(|runtime| runtime.binary.display().to_string()), + "major": runtime.and_then(|runtime| runtime.major), + "bits": runtime.map(|runtime| runtime.bits), + "source": runtime.map(|runtime| runtime.origin.as_str()), + "vendor": runtime.and_then(|runtime| runtime.vendor.clone()), + "required": self.requirement.describe(), + "required_major": self.requirement.minimum, + "requirement_source": self.requirement.source.as_str(), + "mismatch": self.mismatch.map(|mismatch| json!({ + "code": mismatch.code(), + "message": mismatch.message(), + })), + }) + } + + /// 告警行（dry-run 与真启动都输出）。 + /// + /// 两类：①用户指定的 Java 探测不出来（路径写错了，静默退回默认版本会很难查）； + /// ②Java 与版本要求不符（D13：提示，不阻断）。 + #[must_use] + pub fn warnings(&self) -> Vec { + let mut warnings = Vec::new(); + if let Some(runtime) = &self.runtime { + if runtime.major.is_none() { + warnings.push(format!( + "探测不到 {} 的 `java -version` 输出（路径可能不对）", + runtime.binary.display() + )); + } + } + if let Some(mismatch) = self.mismatch { + warnings.push(mismatch.message()); + } + warnings + } + + /// 人读一行（Java 来源 + 要求）。 + #[must_use] + pub fn summary(&self) -> String { + let source = self + .runtime + .as_ref() + .map_or("未探测到", |runtime| runtime.origin.as_str()); + let version = self + .runtime + .as_ref() + .and_then(|runtime| runtime.major) + .map_or_else(|| "未知".to_string(), |major| major.to_string()); + format!( + "Java {version}（{source}）· 该版本要求 {}", + self.requirement.describe() + ) + } +} + +/// 解析启动用的 Java：实例覆盖 > 托管匹配 > 系统。 +/// +/// 覆盖优先级的求值顺序写在 `core::game::java::probe`（纯函数，可注入候选）； +/// 这里只负责「实例覆盖单独成路」与「把结果钉成路径」。 +#[must_use] +pub fn resolve_for_launch(ctx: &Ctx, version_id: &str, explicit: Option<&Path>) -> LaunchJava { + let requirement = java::requirement_for_version(&ctx.game(), version_id); + let (runtime, mismatch) = match explicit { + Some(path) => { + let runtime = java::probe(path, JavaOrigin::Instance); + let mismatch = runtime + .major + .and_then(|major| java::check(major, &requirement)); + (Some(runtime), mismatch) + } + None => { + // 先看托管 + 环境变量；都不满足要求才去扫盘（别为了一次启动白跑 N 次 java -version）。 + // 托管区可能不止一个根（Portable 与 Standard/Custom 并存，D23）。 + let roots = super::java::managed_roots(ctx); + let mut candidates = java::discover_managed_roots(&roots); + candidates.extend(java::system_candidates()); + let mut resolution = java::resolve(&candidates, &requirement); + if resolution.mismatch.is_some() { + candidates.extend(java::standard_candidates()); + resolution = java::resolve(&java::discover::dedupe(candidates), &requirement); + } + (resolution.runtime, resolution.mismatch) + } + }; + // 托管 JDK 要钉死路径（用户 PATH 上的 java 可能正是我们要避开的那一个）； + // 系统来源交回 `snapshot::prepare` 的 `selection()` 兜底，避免重复实现一遍环境判断。 + let override_path = match &runtime { + Some(runtime) if runtime.origin == JavaOrigin::Managed => Some(runtime.binary.clone()), + _ => explicit.map(Path::to_path_buf), + }; + LaunchJava { + override_path, + runtime, + requirement, + mismatch, + } +} diff --git a/crates/cli/src/commands/java_vendors.rs b/crates/cli/src/commands/java_vendors.rs new file mode 100644 index 0000000..96cfb22 --- /dev/null +++ b/crates/cli/src/commands/java_vendors.rs @@ -0,0 +1,141 @@ +//! `ull java vendors`：四家发行版的可用性 / 镜像 / 当前优先级顺序（D23）。 +//! +//! 从 `commands/java.rs` 拆出来（那边 list/install 已经占满一屏）。这里只读不写： +//! 不联网、不改配置，把 `mirrors.json` 的表与设置里的优先级排成一张人读 + `--json` 的对照表。 +//! +//! 存在的意义是**可观测**：用户问「国内为什么默认走 Oracle 而不是微软」时，命令要能直接答 +//! （顺序 + 每家的镜像与实测吞吐），而不是让人翻文档。 + +use serde_json::{json, Value}; +use unlucky_core::download::MirrorTable; +use unlucky_core::game::java::{vendor, JdkVendor}; + +use super::java::{region_profile, JavaSettings}; +use crate::context::Ctx; +use crate::error::CliError; +use crate::output::Report; + +/// `ull java vendors`。 +/// +/// # Errors +/// +/// 设置文件坏掉时退化为默认值；命令本身不产生用户错误。 +pub fn vendors(ctx: &Ctx) -> Result { + let settings = JavaSettings::load(ctx); + let domestic = region_profile(ctx).is_domestic(); + let order = vendor::order(&settings.priority, domestic); + let table = MirrorTable::builtin(); + let rows: Vec = 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(), + }; + 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..8340651 --- /dev/null +++ b/crates/cli/src/commands/launch.rs @@ -0,0 +1,377 @@ +//! `ull launch [--dry-run]`（D18：`--dry-run` 只打印组装后的命令行）。 +//! +//! D20 的隔离档位在**这里**落成 `--gameDir`：本命令按覆盖链 +//! （临时参数 > 实例 `isolation` > 全局 `instances.mode`）派生出运行目录， +//! 交给 [`snapshot::prepare`] 装进 `LaunchDirs.game_dir`（占位符 `${game_directory}` +//! 与子进程 CWD 都取这个值），并在启动时做一次切换检测（只探测、不迁移）。 + +use std::path::PathBuf; + +use serde_json::json; +use unlucky_core::game::install::instance::{ + read_instance_config, write_instance_config, InstanceConfig, Isolation, +}; +use unlucky_core::game::isolation::{derive_game_dir, observe_mode, IsolationMode}; +use unlucky_core::game::ProfileList; +use unlucky_core::launch::time::{format_rfc3339_millis, now}; +use unlucky_core::launch::{LaunchError, Launcher, LauncherConfig}; +use unlucky_core::setting::keys::launcher_schema; +use unlucky_core::setting::store::SettingStore; + +use crate::cli::LaunchArgs; +use crate::context::Ctx; +use crate::error::CliError; +use crate::output::Report; + +use super::identity::{self, Identity}; +use super::snapshot::{self, PlanInput}; + +/// 执行 `launch`。 +/// +/// # Errors +/// +/// 实例/版本不存在、版本 JSON 不可用、命令行组装失败、进程起不来时返回用户错误。 +pub fn run(ctx: &Ctx, args: &LaunchArgs) -> Result { + let profiles = super::instances::read_profiles(ctx)?; + let game = ctx.game(); + let profile = profiles + .profiles + .iter() + .find(|profile| profile.id.as_str() == args.instance || profile.name == args.instance); + + let (input, instance_found) = match profile { + Some(profile) => ( + PlanInput { + version_id: profile.version_id.clone(), + instance_id: profile.id.as_str().to_string(), + instance_name: profile.name.clone(), + game_dir: profile.game_dir.clone(), + java: args.java.clone().or_else(|| profile.java_path.clone()), + username: args.username.clone(), + max_memory: args.max_memory, + ..PlanInput::default() + }, + true, + ), + None => { + // 也接受「直接给版本 id」：没有实例档案时按版本跑一次（脚本化常见）。 + if !game.is_version_installed(&args.instance) { + return Err(CliError::user( + "not_found", + format!( + "既没有实例 `{}`，也没有版本 `{}`", + args.instance, args.instance + ), + ) + .with_hint(instance_hint(&profiles))); + } + ( + PlanInput { + version_id: args.instance.clone(), + instance_name: args.instance.clone(), + java: args.java.clone(), + username: args.username.clone(), + max_memory: args.max_memory, + ..PlanInput::default() + }, + false, + ) + } + }; + + // 实例存在性先确认，再解析身份：微软轨解析身份会联网刷新令牌（有副作用）， + // 不该在一个注定 not_found 的启动上白跑一遍、更不该顺手改写凭据。 + let identity = identity::resolve( + ctx, + args.account.as_deref(), + args.username.as_deref(), + args.dry_run, + )?; + let input = PlanInput { + auth: Some(identity.placeholders.clone()), + ..input + }; + let isolation = resolve_isolation(ctx, profile, &input, args.dry_run)?; + let input = PlanInput { + // 派生结果就是 `--gameDir` 的取值（覆盖链已求值完）。 + game_dir: Some(isolation.game_dir.clone()), + ..input + }; + + // D13：实例覆盖 > 托管匹配 > 系统。托管命中时把路径钉死交给 `snapshot::prepare`。 + let java = super::java::resolve_for_launch(ctx, &input.version_id, input.java.as_deref()); + let input = PlanInput { + java: java.override_path.clone(), + ..input + }; + + let plan = snapshot::prepare(ctx, &input)?; + let config = LauncherConfig::new(ctx.sessions_root()) + .with_launcher(super::meta::LAUNCHER_NAME, env!("CARGO_PKG_VERSION")); + let launcher = Launcher::new(config); + let mut human = Vec::new(); + human.push(format!( + "隔离档位 {}（来源 {}）· 运行目录 {}", + isolation.isolation.as_str(), + isolation.source.as_str(), + isolation.game_dir.display() + )); + if let Some(warning) = &isolation.warning { + human.push(format!("提示: {warning}")); + } + human.push(identity_line(&identity)); + for note in &identity.notes { + human.push(format!("提示: {note}")); + } + human.push(java.summary()); + for warning in java.warnings() { + human.push(format!("告警: {warning}")); + } + + if args.dry_run { + let dry = launcher + .dry_run(&plan.request) + .map_err(|error| map_launch_error(&error, ctx))?; + let mut lines = vec![dry.line().to_string()]; + lines.push(format!( + "（--dry-run：未启动进程 · classpath {} 项 · 编码 {}）", + dry.classpath_entries, dry.encoding + )); + if let Some(natives) = &dry.natives { + lines.push(format!("natives：{}", natives.summary())); + } + let mut warnings = dry.warnings.clone(); + warnings.extend(java.warnings()); + // 人读行里 Java 告警已经在上面打过一次，这里只补 `dry_run` 自己新发现的。 + for warning in &dry.warnings { + lines.push(format!("告警: {warning}")); + } + human.extend(lines); + let natives = dry.natives.as_ref().map(|natives| { + json!({ + "dir": natives.dir.display().to_string(), + "files": natives.files, + "skipped": natives.skipped, + "ignored": natives.ignored, + "jars": natives.jars, + "custom": natives.custom, + "up_to_date": natives.up_to_date, + "era": natives.era.as_str(), + }) + }); + let data = json!({ + "dry_run": true, + "instance_found": instance_found, + "version_id": plan.version_id, + "isolation": isolation.isolation.as_str(), + "isolation_source": isolation.source.as_str(), + "game_dir": isolation.game_dir.display().to_string(), + "mode_change_warning": isolation.warning, + "account": account_json(&identity), + "java": java.to_json(), + "program": dry.program.display().to_string(), + "argv": dry.argv, + "display": dry.display, + "classpath_entries": dry.classpath_entries, + "encoding": dry.encoding, + "warnings": warnings, + "natives": natives, + "adapter_warnings": plan.warnings, + }); + return Ok(Report::new(data, human)); + } + + let handle = launcher + .launch(&plan.request) + .map_err(|error| map_launch_error(&error, ctx))?; + let data = json!({ + "dry_run": false, + "instance_found": instance_found, + "isolation": isolation.isolation.as_str(), + "isolation_source": isolation.source.as_str(), + "game_dir": isolation.game_dir.display().to_string(), + "mode_change_warning": isolation.warning, + "account": account_json(&identity), + "java": java.to_json(), + "warnings": java.warnings(), + "session_id": handle.session_id, + "log_path": handle.log_path.display().to_string(), + "exit_code": handle.exit.code, + "exit_type": handle.exit.exit_type.as_str(), + "uptime_ms": handle.uptime_ms, + "summary": handle.exit.summary(), + "artifacts": handle.artifacts.iter().map(|artifact| artifact.path.display().to_string()).collect::>(), + "adapter_warnings": plan.warnings, + }); + human.push(format!( + "会话 {} 结束：{}", + handle.session_id, + handle.exit.summary() + )); + human.push(format!("事件流: {}", handle.log_path.display())); + Ok(Report::new(data, human)) +} + +/// 隔离派生的结果（运行目录 + 生效档位 + 提示）。 +struct IsolationPlan { + /// 生效运行目录（喂 `--gameDir`）。 + game_dir: PathBuf, + /// 生效档位。 + isolation: Isolation, + /// 档位来自哪一层（`temporary` / `instance` / `global`）。 + source: unlucky_core::game::IsolationSource, + /// 切换检测提示（两侧都有内容时；`None` = 不必提示）。 + warning: Option, +} + +/// 按覆盖链派生运行目录，并在启动时做一次切换检测。 +/// +/// 覆盖链：临时参数（`ull launch` 暂无该 flag，留 `None`） > 实例 `isolation` > 全局 `instances.mode`。 +/// 切换检测只探测 `mods/saves/config` 的条目数并写进实例文件的 `lastModeChange`， +/// **不迁移任何数据**（D20 定案）；提示只展示一次（`warned` 落盘）。 +/// +/// 遗留实例（`profiles.json` 有档案、`config/instances/.json` 还没有——M27 之前的形态） +/// 会在**首次真启动**时补建基线文件：否则这批「最可能撞上存档消失」的用户永远拿不到提示。 +/// `--dry-run` 仍然一个字节都不写。 +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() +} + +fn map_launch_error(error: &LaunchError, ctx: &Ctx) -> CliError { + let hint = format!("版本本体目录：{}", ctx.game().versions_dir().display()); + CliError::user("launch", error.to_string()).with_hint(hint) +} + +fn instance_hint(profiles: &ProfileList) -> String { + if profiles.profiles.is_empty() { + "用 `%prog% instances list` 查看实例，或 `%prog% install ` 登记一个".to_string() + } else { + let names: Vec<&str> = profiles + .profiles + .iter() + .map(|profile| profile.name.as_str()) + .collect(); + format!("可用实例：{}", names.join("、")) + } +} + +/// 人读一行：本次用谁的身份启动。 +fn identity_line(identity: &Identity) -> String { + match &identity.account { + Some(meta) => format!( + "账户 {}（{}）· UUID {}", + meta.display_name(), + meta.kind.label(), + identity.placeholders.uuid + ), + None => format!( + "账户 离线占位 {}（未登记账户）", + identity.placeholders.player_name + ), + } +} + +/// `--json` 里的身份块（**只有可公开字段**，token 永远不出现）。 +fn account_json(identity: &Identity) -> serde_json::Value { + match &identity.account { + Some(meta) => json!({ + "name": meta.display_name(), + "kind": meta.kind.as_str(), + "profile_id": identity.placeholders.uuid, + "account_id": meta.id.as_str(), + "registered": true, + }), + None => json!({ + "name": identity.placeholders.player_name, + "kind": "offline-placeholder", + "profile_id": identity.placeholders.uuid, + "registered": false, + }), + } +} diff --git a/crates/cli/src/commands/meta.rs b/crates/cli/src/commands/meta.rs new file mode 100644 index 0000000..49dafa9 --- /dev/null +++ b/crates/cli/src/commands/meta.rs @@ -0,0 +1,68 @@ +//! 元命令：`--version` / 无子命令 / `help`。 + +use serde_json::json; + +use crate::cli::{help, program}; +use crate::os; +use crate::output::Report; + +/// 启动器名（`${launcher_name}` 与 `--version` 输出共用）。 +pub const LAUNCHER_NAME: &str = "UnluckyLauncher"; + +/// 版本 + 系统摘要（`ull --version`，D19 §5-2 要求附带 os 摘要）。 +/// +/// 探测走 `core::platform::os_info::current()`（进程内缓存），未达基线时附带升级指引。 +/// 自称的名字取 argv[0]（M82）：GUI 二进制调进来时是 `unlucky-launcher`，`ull` 自己跑时仍是 `ull`。 +#[must_use] +pub fn version() -> Report { + let info = os::detect(); + let invoked_as = program::name(); + let data = json!({ + "name": invoked_as, + "package": env!("CARGO_PKG_NAME"), + "version": env!("CARGO_PKG_VERSION"), + "os": os::to_json(&info), + }); + let mut human = vec![ + format!( + "{invoked_as} {}（{}）", + env!("CARGO_PKG_VERSION"), + env!("CARGO_PKG_NAME") + ), + format!("os: {}", os::summary_line(&info)), + ]; + human.extend(os::notes(&info)); + Report::new(data, human) +} + +/// 无子命令：版本摘要 + 帮助（用户原话「无子命令时 --version + --help」）。 +#[must_use] +pub fn welcome() -> Report { + let version_report = version(); + let mut human = version_report.human; + let text = general_help(); + human.push(String::new()); + human.extend(text.lines().map(str::to_string)); + let mut data = version_report.data; + data["help"] = json!(text); + Report::new(data, human) +} + +/// 帮助（`ull help <命令>` 给该命令，未知主题退回总帮助）。 +#[must_use] +pub fn help(topic: Option<&str>) -> Report { + let text = match topic.and_then(help::topic) { + Some(text) => program::fill(text), + None => general_help(), + }; + let data = json!({ + "topic": topic, + "text": text, + }); + Report::new(data, text.lines().map(str::to_string).collect()) +} + +/// 总帮助，按被调用的二进制名自述（`ull` 自己跑时逐字不变）。 +fn general_help() -> String { + program::fill(help::general()) +} diff --git a/crates/cli/src/commands/mod.rs b/crates/cli/src/commands/mod.rs new file mode 100644 index 0000000..b422684 --- /dev/null +++ b/crates/cli/src/commands/mod.rs @@ -0,0 +1,224 @@ +//! 命令分发：命令模型 → 具体实现，并统一挂上环境提示。 + +pub mod accounts; +pub mod agent; +pub mod config; +pub mod identity; +pub mod install; +pub mod instances; +pub mod java; +pub mod java_launch; +pub mod java_vendors; +pub mod launch; +pub mod meta; +pub mod pack; +pub mod sessions; +pub mod snapshot; + +use crate::cli::{Command, Globals, Invocation}; +use crate::context::Ctx; +use crate::error::CliError; +use crate::output::{Outcome, Report}; + +/// 执行一条已解析的命令。 +/// +/// # Errors +/// +/// 用法/数据根/目标不存在等用户错误，或序列化失配等内部错误。 +pub fn run(invocation: &Invocation) -> Result { + match &invocation.command { + // 这三条不需要数据根（`--version` 在不达基线的机器上也要能跑，用于诊断）。 + Command::Welcome => Ok(Outcome::new(meta::welcome())), + Command::Version => Ok(Outcome::new(meta::version())), + Command::Help(topic) => Ok(Outcome::new(meta::help(topic.as_deref()))), + Command::InstancesList => with_ctx(&invocation.globals, instances::list), + Command::Install(args) => with_ctx(&invocation.globals, |ctx| install::run(ctx, args)), + Command::PackImport(args) => { + with_ctx_outcome(&invocation.globals, |ctx| pack::run(ctx, args)) + } + Command::Launch(args) => with_ctx(&invocation.globals, |ctx| launch::run(ctx, args)), + Command::SessionsList { limit } => { + with_ctx(&invocation.globals, |ctx| sessions::list(ctx, *limit)) + } + Command::Logs(args) => with_ctx(&invocation.globals, |ctx| sessions::logs(ctx, args)), + Command::Diag(args) => with_ctx(&invocation.globals, |ctx| sessions::diag(ctx, args)), + Command::ConfigGet(args) => with_ctx(&invocation.globals, |ctx| { + config::get(ctx, args.key.as_deref(), args.show_secret) + }), + Command::ConfigSet(args) => with_ctx(&invocation.globals, |ctx| { + config::set(ctx, &args.key, &args.value) + }), + Command::JavaList => with_ctx(&invocation.globals, java::list), + Command::JavaInstall { major, vendor } => with_ctx(&invocation.globals, |ctx| { + java::install(ctx, *major, *vendor) + }), + Command::JavaVendors => with_ctx(&invocation.globals, java::vendors), + Command::AccountsList => with_ctx(&invocation.globals, accounts::list), + Command::AccountsAdd(args) => with_ctx(&invocation.globals, |ctx| accounts::add(ctx, args)), + Command::AccountsRemove { name } => { + with_ctx(&invocation.globals, |ctx| accounts::remove(ctx, name)) + } + // `AgentServe` 由 `runner::run` 提前分流（stdio 形态下 stdout 就是协议流， + // 不能走「先返回 Report 再打印」的路径）；这里只兜住「有人直接调 commands::run」。 + Command::AgentServe(_) => Err(CliError::usage( + "agent serve 必须在进程入口直接运行（runner 会提前分流）", + )), + Command::AgentConfig { port } => { + with_ctx(&invocation.globals, |ctx| agent::config_report(ctx, *port)) + } + } +} + +/// `core::auth` 的错误 → CLI 错误（保留稳定机读码；文案已是人话，这里只补「下一步」）。 +/// +/// 集中一处的原因：账户相关命令（`accounts *`）与 `launch` 的身份解析要为**同一批** +/// 错误给出一致的码与提示——两处各写一份必然会漂。 +pub(crate) fn map_auth_error(error: unlucky_core::auth::AuthError) -> CliError { + use unlucky_core::auth::body; + use unlucky_core::auth::AuthError; + let hint = match &error { + AuthError::Canceled => Some("登录被取消，可以重跑一次".to_string()), + AuthError::Timeout { .. } => { + Some("重新执行 `%prog% accounts add msa` 拿新的用户码".to_string()) + } + AuthError::CredentialExpired => Some("重新登录：%prog% accounts add msa".to_string()), + // M117：id 缺失是「没配置」，不是「没实现」。hint 里给**能照抄的命令**（两条路： + // 运行期一次性的、构建期烘进二进制的），别只丢一个变量名让用户自己猜。 + AuthError::Unsupported(_) => Some(format!( + "先配 Azure 公共客户端 id（id 不进仓库）：\ +`{env}= %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..b762652 --- /dev/null +++ b/crates/cli/src/commands/pack.rs @@ -0,0 +1,246 @@ +//! `pack import `：整合包导入（M111）。 +//! +//! 逻辑**全在** `core::addon::import`：本文件只做三件事——参数落地、下载引擎接线、两种输出。 +//! 之所以坚持这一层很薄，是因为 M113 的导入页要复用的是 core 的 `import_pack` + `ImportReport`， +//! 不是这里的打印逻辑。 +//! +//! # 三态退出码（脚本契约） +//! +//! | `data.status` | 退出码 | 含义 | +//! |---------------|--------|------| +//! | `success` | `0` | 全部落地、无冲突 | +//! | `partial` | `3` | 有缺文件或有保留用户文件的冲突（实例可用但不完整） | +//! | `failed` | `1` | 致命失败，**已整包回滚** | +//! +//! `--json` 的信封在三种状态下**都是** `{"ok":true,"data":{…}}`（命令跑完了），分流看 +//! `data.status` / `data.error.code` 或退出码；`ok:false` 只用于"命令没跑起来"（参数错、 +//! 数据根不可用），与其它命令一致。 + +use std::path::Path; +use std::sync::{Arc, Mutex}; + +use serde_json::json; +use unlucky_core::addon::import::{ + import_pack, ConflictChoice, ConflictPolicy, DownloadEngineFetcher, FileAction, ImportProgress, + ImportReport, ImportRequest, ImportStatus, +}; +use unlucky_core::download::blocking::block_on; +use unlucky_core::download::cache::now_ms; +use unlucky_core::download::region::{decide_from, load_cached, store_cached}; +use unlucky_core::download::region_system::detect_signals; +use unlucky_core::download::{ + ContentCache, DownloadEngine, EngineConfig, HealthRegistry, MirrorTable, +}; + +use crate::cli::PackImportArgs; +use crate::context::Ctx; +use crate::error::CliError; +use crate::output::{Outcome, Report}; + +/// `ull pack import`。 +/// +/// # Errors +/// +/// 整合包路径不存在（用户错误）。导入本身的失败**不是** `Err`：它走三态报告 + 退出码。 +pub fn run(ctx: &Ctx, args: &PackImportArgs) -> Result { + if !args.path.exists() { + return Err(CliError::user( + "not_found", + format!("整合包不存在：{}", args.path.display()), + ) + .with_hint("给 .zip / .mrpack 文件，或 MultiMC·Prism 的实例目录")); + } + let target = args + .target + .clone() + .unwrap_or_else(|| ctx.game().root().to_path_buf()); + + let stages: Arc>> = Arc::new(Mutex::new(Vec::new())); + let recorder = Arc::clone(&stages); + let sink: unlucky_core::addon::ImportProgressSink = + Arc::new(move |progress: &ImportProgress| { + if let Ok(mut seen) = recorder.lock() { + if seen.last().copied() != Some(progress.stage.as_str()) { + seen.push(progress.stage.as_str()); + } + } + }); + + let engine = build_engine(ctx); + let fetcher = DownloadEngineFetcher::new(&engine); + let layout = ctx.layout(); + let mut request = ImportRequest::new(&args.path, &target) + .with_fetcher(&fetcher) + .with_progress(sink); + if args.overwrite { + request = request.with_conflict_policy(ConflictPolicy::Overwrite); + } + if !args.no_register { + request = request.with_registration(&layout, args.name.as_deref()); + } + + let report = block_on(import_pack(&request)); + let seen = stages.lock().map(|seen| seen.clone()).unwrap_or_default(); + Ok(outcome(ctx, &report, &target, &seen, args)) +} + +/// 组装 `Outcome`（三态 → 退出码 + 两种输出）。 +fn outcome( + ctx: &Ctx, + report: &ImportReport, + target: &Path, + stages: &[&'static str], + args: &PackImportArgs, +) -> Outcome { + let mut data = serde_json::to_value(report).unwrap_or_else(|_| { + json!({ + "status": report.status.as_str(), + "error": {"code": "serialize", "message": "报告序列化失败"}, + }) + }); + if let Some(object) = data.as_object_mut() { + object.insert("target".to_string(), json!(target.display().to_string())); + object.insert("stages".to_string(), json!(stages)); + object.insert("status_key".to_string(), json!(report.status.message_key())); + object.insert("installed_files".to_string(), json!(report.installed())); + object.insert( + "target_is_default".to_string(), + json!(args.target.is_none()), + ); + } + + let mut human: Vec = Vec::new(); + human.push(format!( + "整合包 {}（{}）→ {}{}", + report.pack_name.as_deref().unwrap_or("<未读成>"), + report.format.as_deref().unwrap_or("-"), + target.display(), + if args.target.is_none() { + "（缺省 = 数据根的共享游戏目录）" + } else { + "" + } + )); + if !stages.is_empty() { + human.push(format!("阶段：{}", stages.join(" → "))); + } + human.push(format!( + "结果：{} 文件 新{} / 覆盖{} / 跳过{} / 保留{} 冲突 {} 缺文件 {}", + status_label(report), + count_action(report, FileAction::Installed), + count_action(report, FileAction::Replaced), + count_action(report, FileAction::SkippedIdentical), + count_action(report, FileAction::KeptUser), + report.conflicts.len(), + report.missing.len(), + )); + if let Some(loader) = &report.loader { + human.push(format!( + "加载器：{} {}（版本 id {}）", + loader.kind.label(), + loader.loader_version, + loader.version_id + )); + if let Some(version_id) = &report.version_id { + if !ctx.game().is_version_installed(version_id) { + human.push(format!( + "提示：{version_id} 还没安装，启动前先跑 `%prog% install` 装它" + )); + } + } + } + if let Some(memory) = report.max_memory_mb { + human.push(format!("内存：{memory} MB（来自 instance.cfg）")); + } + for component in &report.rejected_components { + human.push(format!( + "未支持的 component：{} {}（{}）", + component.uid, + component.version.as_deref().unwrap_or("-"), + component.message_key + )); + } + for conflict in &report.conflicts { + human.push(format!( + "冲突：{}（{}，已{}）", + conflict.path, + conflict.message_key, + match conflict.choice { + ConflictChoice::KeepUser => "保留你的文件", + ConflictChoice::Overwrite => "按包覆盖", + } + )); + } + for missing in &report.missing { + human.push(format!( + "缺文件：{}（{}：{}）", + missing.display, missing.message_key, missing.detail + )); + } + if let Some(registered) = &report.registered { + human.push(format!( + "已登记实例 {}（{}）{}", + registered.name, + registered.version_id, + if registered.created { + "" + } else { + "·复用已有档案" + } + )); + } + if let Some(error) = &report.error { + human.push(format!("错误：{}（{}）", error.message(), error.code())); + if let Some(hint) = error.hint() { + human.push(format!("提示：{hint}")); + } + if report.rolled_back { + human.push("已整包回滚：目标目录与导入前一致".to_string()); + } else if let Some(rollback) = &report.rollback { + human.push(format!( + "回滚未完整：{} 项没回去（详见 --json 的 rollback.failed）", + rollback.failure_count() + )); + } + } + + Outcome::new(Report { data, human }).with_exit_code(report.status.exit_code()) +} + +/// 状态的人读名。**失败要按回滚是否干净分叉**：不完整时不能说"已回滚"。 +fn status_label(report: &ImportReport) -> &'static str { + match report.status { + ImportStatus::Success => "成功", + ImportStatus::Partial => "部分成功", + ImportStatus::Failed if report.rolled_back => "失败（已回滚）", + ImportStatus::Failed => "失败（回滚不完整）", + } +} + +fn count_action(report: &ImportReport, action: FileAction) -> usize { + report + .files + .iter() + .filter(|file| file.action == action) + .count() +} + +/// 与 `install` 共用同一套引擎构造（镜像 / 地区 / 健康度 / 内容缓存）。 +fn build_engine(ctx: &Ctx) -> DownloadEngine { + let layout = ctx.layout(); + let cache_root = layout.cache(); + let now = now_ms(); + let region_path = cache_root.join("region.json"); + let region = load_cached(®ion_path, now).unwrap_or_else(|| { + let profile = decide_from(&detect_signals(), now); + let _ = store_cached(®ion_path, &profile); + profile + }); + DownloadEngine::new( + EngineConfig::default(), + Arc::new(MirrorTable::builtin()), + Arc::new(region), + Arc::new(HealthRegistry::open_in(&cache_root, now)), + Arc::new(ContentCache::open(&cache_root)), + ) +} diff --git a/crates/cli/src/commands/sessions.rs b/crates/cli/src/commands/sessions.rs new file mode 100644 index 0000000..e8865c0 --- /dev/null +++ b/crates/cli/src/commands/sessions.rs @@ -0,0 +1,292 @@ +//! `sessions list` / `logs` / `diag`：读 M18 的会话索引与 JSONL 事件流。 +//! +//! 数据源形状见 `DevDocs/SubAgentsTalk/launch-接口约定.md` §2/§5： +//! - `/game/index.jsonl`：一会话一行摘要（同 id 取最后一行，倒序）； +//! - `/game/.jsonl`：事件流（`kind` + `payload`）。 +//! +//! `diag` 把「退出信号 + stdout/stderr 文本」喂给 M15 的内嵌规则集，输出结构化结论。 + +use std::path::Path; + +use serde_json::{json, Value}; +use unlucky_core::diagnose::collectors::{ExitSignal, SignalOrigin}; +use unlucky_core::diagnose::engine::{Diagnoser, DiagnosisInput}; +use unlucky_core::diagnose::loader::RuleLoader; +use unlucky_core::launch::session_index::{self, SessionIndexEntry}; + +use crate::cli::{DiagArgs, LogsArgs}; +use crate::context::Ctx; +use crate::error::CliError; +use crate::output::Report; + +/// `ull sessions list [--limit N]`。 +/// +/// # Errors +/// +/// 索引文件读不了时返回用户错误（不存在 = 空列表）。 +pub fn list(ctx: &Ctx, limit: usize) -> Result { + let index = ctx.session_index(); + let entries = session_index::read_all(&index) + .map_err(|error| CliError::io("读会话索引", &index, &error))?; + let shown: Vec<&SessionIndexEntry> = entries.iter().take(limit).collect(); + + let rows: Vec = shown + .iter() + .map(|entry| { + json!({ + "session_id": entry.session_id, + "instance_id": entry.instance_id, + "instance_name": entry.instance_name, + "game_version": entry.game_version, + "started_at": entry.started_at, + "ended_at": entry.ended_at, + "duration_ms": entry.duration_ms, + "exit_code": entry.exit_code, + "exit_type": entry.exit_type, + "silent_failure": entry.silent_failure, + "window_detected": entry.window_detected, + "crash_found": entry.crash_found, + "diagnosis_top": entry.diagnosis_top, + }) + }) + .collect(); + + let mut human = vec![format!( + "会话 {} 条（索引 {}）", + shown.len(), + index.display() + )]; + if shown.is_empty() { + human.push(" （空）先用 `%prog% launch <实例>` 跑一局".to_string()); + } + for entry in &shown { + human.push(format!( + " {} {} {} {} {}", + entry.session_id, + entry.instance_name, + entry.game_version, + entry.started_at, + exit_label(entry), + )); + } + + Ok(Report::new(json!({ "sessions": rows }), human)) +} + +/// `ull logs [--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]`：规则引擎诊断。 +/// +/// # 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 mut stdout_lines: Vec<&str> = Vec::new(); + let mut stderr_lines: Vec<&str> = Vec::new(); + let mut error_lines: u32 = 0; + for event in &events { + let Some(line) = event.pointer("/payload/line").and_then(Value::as_str) else { + continue; + }; + match event.get("kind").and_then(Value::as_str) { + Some("stdout") => stdout_lines.push(line), + Some("stderr") => { + stderr_lines.push(line); + if event.pointer("/payload/level").and_then(Value::as_str) == Some("error") { + error_lines += 1; + } + } + _ => {} + } + } + let stdout_text = tail_join(&stdout_lines, args.tail); + let stderr_text = tail_join(&stderr_lines, args.tail); + + let exit = ExitSignal::classify( + entry.exit_code, + Some(entry.duration_ms), + error_lines, + &stderr_text, + ); + let mut input = DiagnosisInput::new().with_exit(exit); + if !stdout_text.is_empty() { + input.push_text(SignalOrigin::Stdout, stdout_text); + } + if !stderr_text.is_empty() { + input.push_text(SignalOrigin::Stderr, stderr_text); + } + + let loader = RuleLoader::embedded(); + let diagnoser = Diagnoser::new(loader.rule_set().rules().to_vec()); + let report = diagnoser.analyze(&input); + let record = serde_json::to_value(report.to_record()) + .map_err(|error| CliError::internal("diagnosis_serialize", error.to_string()))?; + + let mut human = vec![format!( + "会话 {} · {} · {} · {}", + entry.session_id, + entry.instance_name, + entry.game_version, + exit_label(&entry) + )]; + match report.primary() { + Some(finding) => { + human.push(format!("主因: {}", finding.message)); + if let Some(detail) = &finding.detail { + human.push(format!("说明: {detail}")); + } + for evidence in finding.evidence.iter().take(3) { + human.push(format!("证据: {}", evidence.render())); + } + } + None => human.push("规则引擎没有得出确定结论（needs_more_info）".to_string()), + } + human.push(format!( + "规则评估 {} 条 · 结论 {} 条 · 次生 {} 条", + report.rules_evaluated, + report.findings.len(), + report.secondary.len() + )); + let human: Vec = human + .iter() + .map(|line| unlucky_agent::redact::redact_text(line)) + .collect(); + + let payload = redact_value(&json!({ + "session_id": entry.session_id, + "instance_id": entry.instance_id, + "game_version": entry.game_version, + "exit": { + "code": entry.exit_code, + "exit_type": entry.exit_type, + "silent_failure": entry.silent_failure, + "duration_ms": entry.duration_ms, + }, + "diagnosis": record, + })); + Ok(Report::new(payload, human)) +} + +fn find_entry(ctx: &Ctx, key: &str) -> Result { + let index = ctx.session_index(); + let entries = session_index::read_all(&index) + .map_err(|error| CliError::io("读会话索引", &index, &error))?; + if let Some(entry) = entries.iter().find(|entry| entry.session_id == key) { + return Ok(entry.clone()); + } + let matches: Vec<&SessionIndexEntry> = entries + .iter() + .filter(|entry| entry.session_id.starts_with(key)) + .collect(); + match matches.as_slice() { + [only] => Ok((*only).clone()), + [] => Err( + CliError::user("session_not_found", format!("找不到会话 `{key}`")) + .with_hint(format!("索引文件：{}", index.display())), + ), + _ => Err(CliError::user( + "session_ambiguous", + format!("`{key}` 匹配到 {} 个会话，请给更长的前缀", matches.len()), + )), + } +} + +fn event_path(ctx: &Ctx, entry: &SessionIndexEntry) -> std::path::PathBuf { + ctx.sessions_root().join("game").join(&entry.log_path) +} + +fn read_events(path: &Path) -> Result, 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 tail_join(lines: &[&str], tail: usize) -> String { + let start = lines.len().saturating_sub(tail.max(1)); + let mut text = lines[start..].join("\n"); + if !text.is_empty() { + text.push('\n'); + } + text +} + +fn render_event(event: &Value) -> String { + let ts = event.get("ts").and_then(Value::as_str).unwrap_or(""); + let kind = event.get("kind").and_then(Value::as_str).unwrap_or("?"); + let detail = event + .pointer("/payload/line") + .and_then(Value::as_str) + .or_else(|| event.pointer("/payload/summary").and_then(Value::as_str)) + .unwrap_or_default(); + format!("[{ts}] {kind} {detail}") +} + +/// 递归脱敏任意 JSON（所有字符串过 `redact_text`：主目录用户名段 + Bearer 令牌）。 +fn redact_value(value: &Value) -> Value { + match value { + Value::String(text) => Value::String(unlucky_agent::redact::redact_text(text)), + Value::Array(items) => Value::Array(items.iter().map(redact_value).collect()), + Value::Object(map) => Value::Object( + map.iter() + .map(|(key, child)| (key.clone(), redact_value(child))) + .collect(), + ), + other => other.clone(), + } +} + +fn exit_label(entry: &SessionIndexEntry) -> String { + let code = entry + .exit_code + .map_or_else(|| "无退出码".to_string(), |code| format!("退出码 {code}")); + let exit_type = entry + .exit_type + .clone() + .unwrap_or_else(|| "unknown".to_string()); + let silent = if entry.silent_failure { + " · 静默失败" + } else { + "" + }; + format!("{code}/{exit_type}{silent}") +} diff --git a/crates/cli/src/commands/snapshot.rs b/crates/cli/src/commands/snapshot.rs new file mode 100644 index 0000000..b37fd9a --- /dev/null +++ b/crates/cli/src/commands/snapshot.rs @@ -0,0 +1,205 @@ +//! 实例 → [`LaunchRequest`] 的装配：launch 命令与 `--dry-run` 共用这一段。 +//! +//! 全部走 core 的既有公共面（`game::resolve` / `arguments.expand` / `GameLayout` / +//! `launch::adapter::build_request`），CLI 不复制任何继承/参数展开逻辑。 + +use std::path::PathBuf; + +use crate::context::Ctx; +use crate::error::CliError; +use unlucky_core::game::arguments::Environment; +use unlucky_core::game::{self, ProfileId, VersionJson}; +use unlucky_core::launch::adapter::{ + self, AdapterOptions, AdapterWarning, LibraryInput, SnapshotInput, +}; +use unlucky_core::launch::request::{AuthPlaceholders, LaunchRequest, MemoryOptions}; + +/// 装配输入（来自命令行 + 实例档案）。 +#[derive(Debug, Clone, Default)] +pub struct PlanInput { + /// 版本 id（实例绑定的 `versions//`）。 + 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) || library.native_classifier(&environment).is_some() { + continue; + } + let Ok(coordinate) = library.coordinate() else { + continue; + }; + let path = if library.is_local() { + game.version_library(&version_id, &coordinate) + } else { + game.library(&coordinate) + }; + libraries.push(LibraryInput::new(path, library.name.clone())); + } + + // natives 分类器构件（≤1.18.2 才有）：收集口径归 core，CLI 只搬运。 + let natives = unlucky_core::launch::natives::collect( + &game, + &version_id, + resolved.libraries.as_deref().unwrap_or_default(), + &environment, + ); + + let jar_id = resolved.jar.clone().unwrap_or_else(|| version_id.clone()); + let primary_jar = game.version_jar(&jar_id); + // 运行目录：调用方（`ull launch`）已按隔离覆盖链派生；`None` 兜底到游戏根 + // （库/其它消费者直接构造 `PlanInput` 时保持旧行为）。 + let game_dir = input + .game_dir + .clone() + .unwrap_or_else(|| ctx.data.game_home.clone()); + let assets_root = game.assets_dir(); + let assets_index = resolved + .assets + .clone() + .or_else(|| resolved.asset_index.as_ref().map(|index| index.id.clone())); + + let snapshot = SnapshotInput { + version_id: &version_id, + version_name: Some(&input.instance_name), + version_type: None, + game_version: None, + main_class: resolved.main_class.as_deref(), + jvm_arguments: &expanded.jvm, + game_arguments: &expanded.game, + legacy_arguments: resolved.minecraft_arguments.as_deref(), + libraries: &libraries, + natives: &natives, + primary_jar, + game_dir, + assets_index: assets_index.as_deref(), + natives_dir: game.natives_dir(&version_id), + library_dir: game.libraries_dir(), + assets_root: assets_root.clone(), + game_assets: assets_root, + }; + + let options = AdapterOptions { + java: super::java::selection(input.java.as_deref()), + memory: MemoryOptions { + min_mb: None, + max_mb: input.max_memory, + }, + auth: input.auth.clone().unwrap_or_else(|| AuthPlaceholders { + player_name: input + .username + .clone() + .unwrap_or_else(|| "Player".to_string()), + uuid: ProfileId::generate().as_str().replace('-', ""), + user_type: "legacy".to_string(), + user_properties: "{}".to_string(), + ..AuthPlaceholders::default() + }), + launcher_name: super::meta::LAUNCHER_NAME.to_string(), + launcher_version: env!("CARGO_PKG_VERSION").to_string(), + language: "zh-CN".to_string(), + ..AdapterOptions::strict() + }; + + let output = adapter::build_request(&snapshot, options); + let warnings = output.warnings.iter().map(describe_warning).collect(); + let mut request = output.request; + // 会话索引要用实例身份（adapter 默认拿版本 id/名）。 + if !input.instance_id.is_empty() { + request.instance.id = input.instance_id.clone(); + } + request.instance.name = input.instance_name.clone(); + + Ok(Plan { + version_id, + request, + warnings, + }) +} + +fn read_version_json(path: &std::path::Path) -> Result { + let text = match std::fs::read_to_string(path) { + Ok(text) => text, + Err(error) if error.kind() == std::io::ErrorKind::NotFound => { + return Err(CliError::user( + "version_missing", + format!("版本 JSON 不存在：{}", path.display()), + ) + .with_hint("先准备好版本本体文件（下载装配属 P1 后续 mission）")); + } + Err(error) => return Err(CliError::io("读版本 JSON", path, &error)), + }; + VersionJson::from_json_str(&text) + .map_err(|error| CliError::user("version_parse", format!("{}：{error}", path.display()))) +} + +/// 适配层告警 → 人读一行（`AdapterWarning` 没有 Display，这里集中翻译）。 +fn describe_warning(warning: &AdapterWarning) -> String { + match warning { + AdapterWarning::MissingLibrary { name, path } => { + format!("缺少库文件 {name}（{}）", path.display()) + } + AdapterWarning::MissingGameArguments => { + "版本 JSON 既没有 arguments.game 也没有 minecraftArguments".to_string() + } + AdapterWarning::MissingAssetsIndex => { + "版本 JSON 没有资源索引 id（${assets_index_name} 为空）".to_string() + } + AdapterWarning::MissingMainClass => "版本 JSON 没有 mainClass".to_string(), + AdapterWarning::MissingNativeJar { name, path } => { + format!("缺少 natives 构件 {name}（{}）", path.display()) + } + } +} diff --git a/crates/cli/src/context.rs b/crates/cli/src/context.rs new file mode 100644 index 0000000..1ae4b90 --- /dev/null +++ b/crates/cli/src/context.rs @@ -0,0 +1,238 @@ +//! 数据根解析与目录视图。 +//! +//! 三模式（D6 / `04-data-and-config.md` §1）全部交给 `core::platform::data_dir`： +//! - `--data-dir ` → 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() + } + + /// 会话根（`/agent/sessions`，launch 的事件流与索引都在这下面）。 + #[must_use] + pub fn sessions_root(&self) -> PathBuf { + self.layout().agent_sessions() + } + + /// 账户数据目录（`data/auth/`：`accounts.json` + `credentials.dat`）。 + #[must_use] + pub fn auth_data(&self) -> PathBuf { + self.layout().auth_data() + } + + /// 会话索引文件（`/game/index.jsonl`）。 + #[must_use] + pub fn session_index(&self) -> PathBuf { + unlucky_core::launch::session_index::index_path(&self.sessions_root()) + } + + /// D19/D21：低于基线（Win10+ / macOS 12+ / Linux 达标）时拒绝执行。 + /// + /// # Errors + /// + /// 系统不支持时返回 `unsupported_os` 用户错误（文案与核心自检同一份）。 + pub fn ensure_supported(&self) -> Result<(), CliError> { + let check = os::check(); + if check.is_usable() { + return Ok(()); + } + Err(CliError::user("unsupported_os", check.message) + .with_hint(format!("最低要求：{}", os::BASELINE))) + } + + /// 环境级提示（低于基线时的升级指引；一等基线时为空）。 + #[must_use] + pub fn notes(&self) -> Vec { + 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/error.rs b/crates/cli/src/error.rs new file mode 100644 index 0000000..9416e32 --- /dev/null +++ b/crates/cli/src/error.rs @@ -0,0 +1,165 @@ +//! 错误形状与退出码。 +//! +//! 约定（10-cli-design.md §3）：**0 成功 / 1 用户错误 / 2 内部错误**。 +//! 用户错误 = 用法错、目标不存在、环境不支持、依赖模块未接线； +//! 内部错误 = 不该发生的事（序列化失配等），脚本见到 2 应该当 bug 报。 + +use std::fmt; + +use serde_json::{json, Value}; + +/// 退出码：成功。 +pub const EXIT_OK: i32 = 0; +/// 退出码：用户错误。 +pub const EXIT_USER: i32 = 1; +/// 退出码：内部错误。 +pub const EXIT_INTERNAL: i32 = 2; + +/// 错误大类（决定退出码）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum ErrorKind { + /// 用户侧问题：改参数/改环境可解决。 + User, + /// 内部问题：不该发生，应报 bug。 + Internal, +} + +impl ErrorKind { + /// 稳定名（`--json` 输出用）。 + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::User => "user", + Self::Internal => "internal", + } + } + + /// 对应的进程退出码。 + #[must_use] + pub const fn exit_code(self) -> i32 { + match self { + Self::User => EXIT_USER, + Self::Internal => EXIT_INTERNAL, + } + } +} + +/// 一条 CLI 错误。 +/// +/// `code` 是给脚本的稳定机读标识（`usage` / `not_found` / `unsupported_os` …）， +/// `message` 是给人看的中文说明，`hint` 是「下一步该做什么」。 +#[derive(Debug, Clone)] +pub struct CliError { + kind: ErrorKind, + code: &'static str, + message: String, + hint: Option, +} + +/// 把模板里的程序名占位符渲染掉（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, + } + } + + /// 用户错误，带稳定 code。 + #[must_use] + pub fn user(code: &'static str, message: impl Into) -> Self { + Self { + kind: ErrorKind::User, + code, + message: render(message), + hint: None, + } + } + + /// 内部错误，带稳定 code。 + #[must_use] + pub fn internal(code: &'static str, message: impl Into) -> Self { + Self { + kind: ErrorKind::Internal, + code, + message: render(message), + hint: None, + } + } + + /// IO 失败（读配置/读写会话文件）：按用户错误处理，路径进消息。 + #[must_use] + pub fn io(op: &str, path: &std::path::Path, error: &std::io::Error) -> Self { + Self::user("io", format!("{op}失败：{}（{error}）", path.display())) + } + + /// 补一句提示。 + #[must_use] + pub fn with_hint(mut self, hint: impl Into) -> Self { + self.hint = Some(render(hint)); + self + } + + /// 错误大类。 + #[must_use] + pub const fn kind(&self) -> ErrorKind { + self.kind + } + + /// 稳定错误码。 + #[must_use] + pub const fn code(&self) -> &'static str { + self.code + } + + /// 人类可读说明。 + #[must_use] + pub fn message(&self) -> &str { + &self.message + } + + /// 下一步提示。 + #[must_use] + pub fn hint(&self) -> Option<&str> { + self.hint.as_deref() + } + + /// 进程退出码。 + #[must_use] + pub const fn exit_code(&self) -> i32 { + self.kind.exit_code() + } + + /// `--json` 里的错误对象。 + #[must_use] + pub fn to_json(&self) -> Value { + let mut error = json!({ + "code": self.code, + "kind": self.kind.as_str(), + "message": self.message, + }); + if let Some(hint) = &self.hint { + error["hint"] = Value::String(hint.clone()); + } + json!({ "ok": false, "error": error }) + } +} + +impl fmt::Display for CliError { + fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { + write!(formatter, "{}", self.message) + } +} + +impl std::error::Error for CliError {} diff --git a/crates/cli/src/lib.rs b/crates/cli/src/lib.rs new file mode 100644 index 0000000..cdd8dcf --- /dev/null +++ b/crates/cli/src/lib.rs @@ -0,0 +1,27 @@ +//! Unlucky-Launcher 命令行（`unlucky_cli`）：`ull` 二进制的可测试内核。 +//! +//! 设计定稿：`DevDocs/PlanDoc/10-cli-design.md`（D18）—— core 是零 UI 纯库， +//! CLI 只是与 Slint GUI 平级的第二个消费者，因此**本 crate 不依赖任何 UI 框架**。 +//! +//! 分层： +//! - [`cli`]：手写参数解析（不引 clap）+ 命令模型 + 帮助文案； +//! - [`commands`]：每个子命令一个函数，输入 [`context::Ctx`]，输出 [`output::Report`]； +//! - [`context`]：数据根解析（三模式 / `--data-dir` 覆盖）与目录视图； +//! - [`os`]：系统摘要与 D19/D21 支持级别（事实来自 core::platform::os_info，这里只做呈现）； +//! - [`output`]：人类可读 + `--json` 双格式输出； +//! - [`error`]：错误形状与退出码（0 成功 / 1 用户错误 / 2 内部错误）。 +//! +//! 可测试性：入口是 [`run`]，参数是 `&[String]`，输出写进两个 `&mut dyn Write`， +//! 返回值就是进程退出码——集成测试因此不需要真的起子进程也能覆盖三条通道。 + +#![forbid(unsafe_code)] + +pub mod cli; +pub mod commands; +pub mod context; +pub mod error; +pub mod os; +pub mod output; +pub mod runner; + +pub use runner::run; diff --git a/crates/cli/src/main.rs b/crates/cli/src/main.rs new file mode 100644 index 0000000..28afe48 --- /dev/null +++ b/crates/cli/src/main.rs @@ -0,0 +1,9 @@ +//! `ull` 二进制入口：把真实 stdio 交给 [`unlucky_cli::run`]，退出码照传。 + +fn main() { + let args: Vec = 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/agent_mcp_stdio_test.rs b/crates/cli/tests/agent_mcp_stdio_test.rs new file mode 100644 index 0000000..2600454 --- /dev/null +++ b/crates/cli/tests/agent_mcp_stdio_test.rs @@ -0,0 +1,185 @@ +//! 真机验收：起 `ull agent serve --stdio`，用裸 JSON-RPC 走一遍握手 → 列工具 → 调用。 +//! +//! 这是 M39 任务 5 的自动化形态：**不引任何 MCP 客户端库**，直接按协议喂行给子进程。 +//! stdio 形态是 llama.cpp 内置 MCP client 的入口，它的 stdout 必须是纯 JSON-RPC—— +//! 本测试顺带守住「stdout 里没有多余输出」这条最容易破的约束。 + +use std::io::{BufRead, BufReader, Write}; +use std::path::{Path, PathBuf}; +use std::process::{Command, Stdio}; + +use serde_json::{json, Value}; + +fn data_dir(tag: &str) -> PathBuf { + let dir = std::env::temp_dir().join(format!("ull-agent-stdio-{tag}-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&dir); + std::fs::create_dir_all(&dir).expect("建临时数据根"); + dir +} + +struct Session { + child: std::process::Child, + stdin: std::process::ChildStdin, + stdout: std::io::Lines>, +} + +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); +} 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_test.rs b/crates/cli/tests/java_test.rs new file mode 100644 index 0000000..c1570ae --- /dev/null +++ b/crates/cli/tests/java_test.rs @@ -0,0 +1,197 @@ +//! `ull java list` / `ull java install` / `ull launch` 的 Java 选择（D13）CLI 端。 +//! +//! 不联网：`install` 只测参数校验与稳定错误码；`launch --dry-run` 断言 `java` 块的结构 +//! 与「实例覆盖优先」——真正的下载/解压由 `core::game::java` 的测试与本机验收覆盖。 + +#[path = "support/mod.rs"] +mod support; + +use support::{parse_json, run_cli, write_version, TempDir}; + +/// 一个可组装的版本 id。 +const VERSION: &str = "1.20.1"; + +#[test] +fn java_list_reports_the_managed_root() { + let dir = TempDir::new("java-list"); + let (code, stdout, stderr) = run_cli(&["--json", "--data-dir", &dir.arg(), "java", "list"]); + assert_eq!(code, 0, "stderr: {stderr}"); + let envelope = parse_json(&stdout); + let json = &envelope["data"]; + assert!( + json["managed_root"] + .as_str() + .is_some_and(|root| root.ends_with("java-managed")), + "managed_root 应是 data/java-managed：{json}" + ); + // D23：多根扫描 + 落点模式要说清（`--data-dir` 是 custom 数据模式 → portable 落点）。 + assert!( + json["managed_roots"] + .as_array() + .is_some_and(|roots| !roots.is_empty()), + "{json}" + ); + assert_eq!(json["install"]["mode"], "portable", "{json}"); + assert!( + json["install"]["root"] + .as_str() + .is_some_and(|root| root.ends_with("java-managed")), + "落点根应是数据根里的 java-managed：{json}" + ); + assert!(json["candidates"].is_array(), "{json}"); +} + +#[test] +fn java_vendors_lists_the_four_vendors_with_the_current_order() { + let dir = TempDir::new("java-vendors"); + let (code, stdout, stderr) = run_cli(&["--json", "--data-dir", &dir.arg(), "java", "vendors"]); + assert_eq!(code, 0, "stderr: {stderr}"); + let envelope = parse_json(&stdout); + let json = &envelope["data"]; + let order: Vec<&str> = json["order"] + .as_array() + .expect("order 数组") + .iter() + .filter_map(|item| item.as_str()) + .collect(); + assert_eq!(order.len(), 4, "{json}"); + assert!(order.contains(&"temurin"), "{json}"); + assert!(order.contains(&"oracle"), "{json}"); + assert!(order.contains(&"microsoft"), "{json}"); + assert!(order.contains(&"zulu"), "{json}"); + // 本机时区/语言决定 domestic/global，两种默认序都合法，但来源必须明示。 + let source = json["priority_source"].as_str().unwrap_or("?"); + assert_eq!( + source, "region_default", + "没设 java.vendorPriority 时：{json}" + ); + let vendors = json["vendors"].as_array().expect("vendors 数组"); + assert_eq!(vendors.len(), 4); + let microsoft = vendors + .iter() + .find(|row| row["vendor"] == "microsoft") + .expect("应有 microsoft 行"); + assert_eq!( + microsoft["supported"].as_array().map(Vec::len), + Some(4), + "MS 只发 25/21/17/11：{microsoft}" + ); + assert!( + microsoft["sources"] + .as_array() + .is_some_and(|sources| !sources.is_empty()), + "MS 的源（aka.ms → VS CDN）要列出来：{microsoft}" + ); +} + +#[test] +fn java_install_rejects_an_unknown_vendor_without_network() { + let dir = TempDir::new("java-vendor-bad"); + let (code, stdout, _stderr) = run_cli(&[ + "--json", + "--data-dir", + &dir.arg(), + "java", + "install", + "21", + "--vendor", + "graalvm", + ]); + assert_eq!(code, 1); + let envelope = parse_json(&stdout); + assert_eq!(envelope["error"]["code"], "usage", "{envelope}"); +} + +#[test] +fn java_install_rejects_an_absurd_major_without_network() { + let dir = TempDir::new("java-install"); + let (code, stdout, _stderr) = + run_cli(&["--json", "--data-dir", &dir.arg(), "java", "install", "4"]); + assert_eq!(code, 1); + let envelope = parse_json(&stdout); + assert_eq!(envelope["error"]["code"], "usage", "{envelope}"); +} + +#[test] +fn launch_dry_run_reports_the_java_requirement_of_the_version() { + let dir = TempDir::new("java-launch"); + write_version(dir.path(), VERSION); + let (code, stdout, stderr) = run_cli(&[ + "--json", + "--data-dir", + &dir.arg(), + "launch", + VERSION, + "--dry-run", + ]); + assert_eq!(code, 0, "stderr: {stderr}"); + let envelope = parse_json(&stdout); + let json = &envelope["data"]; + let java = &json["java"]; + // 1.20.1 的清单没写 javaVersion → 静态表兜底 17。 + assert_eq!(java["required_major"], 17, "{json}"); + assert_eq!(java["requirement_source"], "table", "{json}"); + assert_eq!(json["version_id"], VERSION); + // `source` 只可能是探测到的来源之一（本机未必装了 Java）。 + let source = java["source"].as_str().unwrap_or("none"); + assert!( + ["instance", "managed", "JAVA_HOME", "PATH", "none"].contains(&source), + "意外的来源：{source}" + ); +} + +#[test] +fn instance_java_override_wins_over_the_system_java() { + let dir = TempDir::new("java-override"); + write_version(dir.path(), VERSION); + // 故意给一个不存在的路径：只要能进 `source=instance` 就说明覆盖优先级生效 + // （探测失败只影响 major，不该把用户指定的路径换成系统 Java）。 + let fake = dir.path().join("some-jdk").join("bin").join("java"); + let (code, stdout, stderr) = run_cli(&[ + "--json", + "--data-dir", + &dir.arg(), + "launch", + VERSION, + "--dry-run", + "--java", + &fake.display().to_string(), + ]); + assert_eq!(code, 0, "stderr: {stderr}"); + let envelope = parse_json(&stdout); + let json = &envelope["data"]; + assert_eq!(json["java"]["source"], "instance", "{json}"); + assert_eq!( + json["java"]["binary"].as_str(), + Some(fake.display().to_string().as_str()) + ); +} + +#[test] +fn legacy_version_requires_java_8_and_flags_a_newer_runtime() { + let dir = TempDir::new("java-legacy"); + write_version(dir.path(), "1.12.2"); + let (code, stdout, stderr) = run_cli(&[ + "--json", + "--data-dir", + &dir.arg(), + "launch", + "1.12.2", + "--dry-run", + ]); + assert_eq!(code, 0, "stderr: {stderr}"); + let envelope = parse_json(&stdout); + let json = &envelope["data"]; + assert_eq!(json["java"]["required_major"], 8, "{json}"); + assert_eq!(json["java"]["required"], "Java 8", "{json}"); + // 本机若有比 8 新的 Java，必须给出 java_too_new 告警（不能只靠「最低版本」）。 + if let Some(code) = json["java"]["mismatch"]["code"].as_str() { + assert!(code == "java_too_new" || code == "java_too_old", "{json}"); + assert!( + json["warnings"] + .as_array() + .is_some_and(|warnings| !warnings.is_empty()), + "不符时必须进 warnings：{json}" + ); + } +} diff --git a/crates/cli/tests/os_test.rs b/crates/cli/tests/os_test.rs new file mode 100644 index 0000000..086da5f --- /dev/null +++ b/crates/cli/tests/os_test.rs @@ -0,0 +1,115 @@ +//! D19/D21 支持基线：core 的纯判定函数 + CLI 的呈现层（注入样本，不动真机）。 + +use unlucky_cli::os; +use unlucky_core::platform::linux_caps::{GlProbe, SessionKind}; +use unlucky_core::platform::os_info::{ + self, linux_level, macos_level, support_level_for, windows_level, OsFamily, OsInfo, + SupportLevel, +}; +use unlucky_core::platform::vk_probe::VkProbe; + +/// 手工构造一份样本系统信息（字段全是探测事实，等级用 core 的纯函数算）。 +fn sample(family: OsFamily, version: Option<(u32, u32)>, product: &str) -> OsInfo { + let version_string = + version.map_or_else(String::new, |(major, minor)| format!("{major}.{minor}")); + OsInfo { + family, + arch: "x86_64".to_string(), + major_minor: version, + build: None, + product: product.to_string(), + version_string, + session: SessionKind::Unknown, + gl: GlProbe::Unknown, + vk: VkProbe::Unknown, + kernel: None, + glibc: None, + support_level: support_level_for(family, version, None, None), + } +} + +#[test] +fn windows_samples_below_win10_are_unsupported() { + // D21 用户拍板「直接 win10 起步」：Win8.1 / 8 / 7 及更旧一律不支持。 + assert_eq!(windows_level(Some((6, 1))), SupportLevel::Unsupported); // Win7 + assert_eq!(windows_level(Some((6, 2))), SupportLevel::Unsupported); // Win8 + assert_eq!(windows_level(Some((6, 3))), SupportLevel::Unsupported); // Win8.1 + assert_eq!(windows_level(Some((5, 1))), SupportLevel::Unsupported); // XP + assert_eq!(windows_level(Some((10, 0))), SupportLevel::One); // Win10 + + // 探不到版本 → 保守判不支持（不能因为"探不到"就放行）。 + assert_eq!(windows_level(None), SupportLevel::Unsupported); +} + +#[test] +fn macos_and_linux_samples() { + assert_eq!(macos_level(Some(11)), SupportLevel::Unsupported); + assert_eq!(macos_level(Some(12)), SupportLevel::One); + assert_eq!(macos_level(None), SupportLevel::Unsupported); + // Linux：内核/glibc 探得到但过低 → 不支持；取不到（容器/musl/Termux）不阻塞。 + assert_eq!(linux_level(Some((2, 6)), None), SupportLevel::Unsupported); + assert_eq!(linux_level(None, Some((2, 12))), SupportLevel::Unsupported); + assert_eq!(linux_level(Some((6, 8)), Some((2, 39))), SupportLevel::One); + assert_eq!(linux_level(None, None), SupportLevel::One); +} + +#[test] +fn unsupported_sample_renders_upgrade_hint() { + let info = sample(OsFamily::Windows, Some((6, 3)), "Windows 8.1"); + + assert!(!info.support_level.is_usable()); + let line = os::summary_line(&info); + assert!(line.contains("Windows 8.1"), "{line}"); + assert!(line.contains("6.3"), "{line}"); + assert!(line.contains("不支持"), "{line}"); + + let notes = os::notes(&info); + assert_eq!(notes.len(), 1); + assert!(notes[0].contains("Windows 10 或更高版本"), "{notes:?}"); + + // 文案是中英双语（core 同一份措辞），脚本只读 --json。 + let message = info.describe().combined(); + assert!(message.contains("Windows 10 或更高版本"), "{message}"); + assert!(message.contains("Windows 10 or newer"), "{message}"); + + let value = os::to_json(&info); + assert_eq!(value["family"], "windows"); + assert_eq!(value["product"], "Windows 8.1"); + assert_eq!(value["support"], "unsupported"); + assert_eq!(value["major_minor"], "6.3"); +} + +#[test] +fn supported_sample_has_no_notes() { + let info = sample(OsFamily::Windows, Some((10, 0)), "Windows 11"); + assert!(info.support_level.is_usable()); + assert!(os::notes(&info).is_empty()); + assert!(os::summary_line(&info).contains("满足最低要求")); + assert_eq!(os::to_json(&info)["support"], "one"); +} + +#[test] +fn missing_version_is_reported_as_null_not_zero() { + // 探不到版本时 `version` 是 null（脚本按 null 判定"未探测"），而不是空串。 + let info = sample(OsFamily::Windows, None, "Windows"); + let value = os::to_json(&info); + assert!(value["version"].is_null()); + assert!(value["major_minor"].is_null()); + assert_eq!(value["support"], "unsupported"); + assert!(os::summary_line(&info).contains("版本未知")); +} + +#[test] +fn real_detect_matches_core_cache() { + // 真机上 CLI 的摘要必须就是 core 的缓存快照（同一份事实，不做二次加工）。 + let info = os::detect(); + assert_eq!(&info, os_info::current()); + assert!(!info.arch.is_empty()); + assert!(!info.product.is_empty()); + // 自检形态与事实一致。 + let check = os::check(); + assert_eq!(check.level, info.support_level); + assert_eq!(check.os, info); + assert_eq!(check.is_usable(), info.support_level.is_usable()); + assert!(check.message.contains(&info.product), "{}", check.message); +} diff --git a/crates/cli/tests/output_test.rs b/crates/cli/tests/output_test.rs new file mode 100644 index 0000000..862842c --- /dev/null +++ b/crates/cli/tests/output_test.rs @@ -0,0 +1,295 @@ +//! `--json` 输出形状与真实 core 轻量路径（只读命令 + dry-run）。 + +#[path = "support/mod.rs"] +mod support; + +use support::{parse_json, run_cli, write_profiles, write_session, write_version, TempDir}; + +#[test] +fn version_json_has_os_summary() { + let (code, stdout, _) = run_cli(&["--version", "--json"]); + assert_eq!(code, 0); + let value = parse_json(&stdout); + assert_eq!(value["ok"], true); + // M82：自称的名字跟着被调用的二进制走（test harness 里是测试二进制名，`ull` 里是 `ull`）； + // argv[0] → 名字的映射由 cli::program 的单测钉死。 + assert_eq!( + value["data"]["name"], + unlucky_cli::cli::program::name(), + "{stdout}" + ); + assert_eq!(value["data"]["version"], env!("CARGO_PKG_VERSION")); + // D19/D21：os 对象来自 core::platform::os_info（family + 两档 support）。 + assert!(value["data"]["os"]["family"].is_string()); + let support = value["data"]["os"]["support"].as_str().unwrap_or_default(); + assert!(matches!(support, "one" | "unsupported"), "{support}"); +} + +#[test] +fn welcome_without_subcommand_prints_version_and_help() { + let (code, stdout, _) = run_cli(&[]); + assert_eq!(code, 0); + // banner 用被调用的二进制名（M82），不写死 `ull`。 + let banner = format!("{} ", unlucky_cli::cli::program::name()); + assert!(stdout.starts_with(&banner), "{stdout}"); + assert!(stdout.contains("用法:"), "{stdout}"); + + let (code, stdout, _) = run_cli(&["--json"]); + assert_eq!(code, 0); + let value = parse_json(&stdout); + assert!(value["data"]["help"] + .as_str() + .unwrap_or_default() + .contains("用法:")); +} + +#[test] +fn instances_list_json_shape() { + let dir = TempDir::new("instances"); + write_version(dir.path(), "1.20.1"); + write_profiles(dir.path(), &[("生存服", "1.20.1"), ("空实例", "1.19.4")]); + + let (code, stdout, _) = run_cli(&["instances", "list", "--json", "--data-dir", &dir.arg()]); + assert_eq!(code, 0); + let value = parse_json(&stdout); + let instances = value["data"]["instances"] + .as_array() + .expect("instances 数组"); + assert_eq!(instances.len(), 2); + assert_eq!(instances[0]["name"], "生存服"); + assert_eq!(instances[0]["version_present"], true); + assert_eq!(instances[1]["version_present"], false); + let installed = value["data"]["installed_versions"] + .as_array() + .expect("已安装版本"); + assert_eq!(installed.len(), 1); + assert_eq!(installed[0], "1.20.1"); +} + +#[test] +fn install_rejects_unknown_loader_before_touching_network() { + let dir = TempDir::new("install-loader"); + let (code, stdout, _) = run_cli(&[ + "install", + "1.20.1", + "--loader", + "liteloader", + "--json", + "--data-dir", + &dir.arg(), + ]); + assert_eq!(code, 1, "未知加载器是用户错误"); + let value = parse_json(&stdout); + assert_eq!(value["error"]["code"], "loader_unknown"); + assert!( + !dir.path() + .join(".ULL") + .join("config") + .join("profiles.json") + .exists(), + "拒绝时不该登记任何实例" + ); +} + +#[test] +fn install_reports_name_conflict_without_downloading() { + let dir = TempDir::new("install-conflict"); + write_profiles(dir.path(), &[("生存服", "1.19.4")]); + + // 同名但绑定别的版本 → 冲突，且这一步在联网/下载之前就返回。 + let (code, stdout, _) = run_cli(&[ + "install", + "1.20.1", + "--name", + "生存服", + "--json", + "--data-dir", + &dir.arg(), + ]); + assert_eq!(code, 1); + let value = parse_json(&stdout); + assert_eq!(value["error"]["code"], "instance_exists"); + assert!( + value["error"]["message"] + .as_str() + .unwrap_or_default() + .contains("1.19.4"), + "错误里应说明冲突版本：{stdout}" + ); +} + +#[test] +fn install_requires_a_version_id() { + let dir = TempDir::new("install-empty"); + let (code, _, stderr) = run_cli(&["install", " ", "--data-dir", &dir.arg()]); + assert_eq!(code, 1); + assert!(stderr.contains("版本 id"), "stderr={stderr}"); +} + +#[test] +fn launch_dry_run_prints_assembled_command() { + let dir = TempDir::new("dryrun"); + write_version(dir.path(), "1.20.1"); + write_profiles(dir.path(), &[("生存服", "1.20.1")]); + + let (code, stdout, _) = run_cli(&[ + "launch", + "生存服", + "--dry-run", + "--username", + "Steve", + "--max-memory", + "2048", + "--json", + "--data-dir", + &dir.arg(), + ]); + assert_eq!(code, 0, "{stdout}"); + let value = parse_json(&stdout); + let data = &value["data"]; + assert_eq!(data["dry_run"], true); + assert_eq!(data["instance_found"], true); + let argv = data["argv"].as_array().expect("argv 数组"); + let joined = argv + .iter() + .filter_map(|item| item.as_str()) + .collect::>() + .join(" "); + assert!(joined.contains("-Xmx2048"), "{joined}"); + assert!( + joined.contains("net.minecraft.client.main.Main"), + "{joined}" + ); + assert!(joined.contains("--username Steve"), "{joined}"); + // 凭据绝不落到 dry-run 输出里。 + assert!(!joined.contains("accessToken "), "{joined}"); + assert!(data["classpath_entries"].as_u64().unwrap_or(0) >= 1); +} + +#[test] +fn sessions_logs_and_diag_read_the_index() { + let dir = TempDir::new("sessions"); + let sid = write_session(dir.path()); + + let (code, stdout, _) = run_cli(&["sessions", "list", "--json", "--data-dir", &dir.arg()]); + assert_eq!(code, 0); + let value = parse_json(&stdout); + let sessions = value["data"]["sessions"].as_array().expect("sessions 数组"); + assert_eq!(sessions.len(), 1); + assert_eq!(sessions[0]["session_id"], sid); + assert_eq!(sessions[0]["exit_code"], 1); + + let (code, stdout, _) = run_cli(&[ + "logs", + &sid, + "--tail", + "1", + "--json", + "--data-dir", + &dir.arg(), + ]); + assert_eq!(code, 0); + let value = parse_json(&stdout); + let events = value["data"]["events"].as_array().expect("events 数组"); + assert_eq!(events.len(), 1); + assert_eq!(events[0]["kind"], "stderr"); + + // 前缀匹配唯一即可（脚本里手打全 id 太长）。 + let (code, stdout, _) = run_cli(&["diag", "20261030", "--json", "--data-dir", &dir.arg()]); + assert_eq!(code, 0, "{stdout}"); + let value = parse_json(&stdout); + assert_eq!(value["data"]["session_id"], sid); + let candidates = value["data"]["diagnosis"]["candidates"] + .as_array() + .expect("candidates 数组"); + assert!(!candidates.is_empty(), "OOM 日志应命中规则：{stdout}"); + assert_eq!(value["data"]["diagnosis"]["needs_more_info"], false); +} + +#[test] +fn logs_json_payload_is_redacted_like_human_output() { + // P2-1：`--json` 是机器消费路径，不该比人类输出拿到更多原文（主目录用户名段）。 + let dir = TempDir::new("logs-redact"); + let sid = write_session(dir.path()); + let events = dir + .path() + .join(".ULL") + .join("data") + .join("agent") + .join("sessions") + .join("game") + .join(format!("{sid}.jsonl")); + let extra = serde_json::json!({ + "v": 1, "seq": 9, "ts": "2026-10-30T10:15:07Z", "t_ms": 6000, + "kind": "stdout", "session_id": sid, + "payload": { "line": r"cat C:\Users\Bob\secret.txt failed", "level": "info" } + }); + let mut text = std::fs::read_to_string(&events).expect("读事件流"); + text.push_str(&serde_json::to_string(&extra).expect("序列化事件")); + text.push('\n'); + std::fs::write(&events, text).expect("写事件流"); + + let (code, stdout, stderr) = run_cli(&["logs", &sid, "--json", "--data-dir", &dir.arg()]); + assert_eq!(code, 0, "{stderr}"); + assert!(!stdout.contains("Bob"), "JSON 载荷泄出用户名：{stdout}"); + assert!(stdout.contains("***"), "JSON 载荷未脱敏：{stdout}"); +} + +#[test] +fn config_get_set_round_trip() { + let dir = TempDir::new("config"); + let data_dir = dir.arg(); + + let (code, stdout, _) = run_cli(&[ + "config", + "get", + "ui.language", + "--json", + "--data-dir", + &data_dir, + ]); + assert_eq!(code, 0); + let value = parse_json(&stdout); + assert_eq!(value["data"]["key"], "ui.language"); + assert_eq!(value["data"]["value"], "zh_cn"); + + let (code, stdout, _) = run_cli(&[ + "config", + "set", + "ui.language", + "en_us", + "--json", + "--data-dir", + &data_dir, + ]); + assert_eq!(code, 0, "{stdout}"); + let value = parse_json(&stdout); + assert_eq!(value["data"]["old"], "zh_cn"); + assert_eq!(value["data"]["new"], "en_us"); + + let (_, stdout, _) = run_cli(&[ + "config", + "get", + "ui.language", + "--json", + "--data-dir", + &data_dir, + ]); + assert_eq!(parse_json(&stdout)["data"]["value"], "en_us"); +} + +#[test] +fn error_envelope_shape() { + let dir = TempDir::new("errors"); + let (code, stdout, _) = run_cli(&["launch", "nope", "--json", "--data-dir", &dir.arg()]); + assert_eq!(code, 1); + let value = parse_json(&stdout); + assert_eq!(value["ok"], false); + assert_eq!(value["error"]["code"], "not_found"); + assert_eq!(value["error"]["kind"], "user"); + assert!(value["error"]["message"] + .as_str() + .unwrap_or_default() + .contains("nope")); + assert!(value["error"]["hint"].is_string()); +} diff --git a/crates/cli/tests/pack_test.rs b/crates/cli/tests/pack_test.rs new file mode 100644 index 0000000..196b8b1 --- /dev/null +++ b/crates/cli/tests/pack_test.rs @@ -0,0 +1,199 @@ +//! `ull pack import` 的三态契约：退出码 0 / 3 / 1 + `--json` 信封恒有结构。 +//! +//! **全部离线、全部不依赖 zip**： +//! +//! - MultiMC / Prism 的真实形态就是**目录**，直接拷 → `0`； +//! - mrpack 也能以**目录**打开（`PackArchive` 对目录与 zip 一视同仁），造一条 `downloads` 为空的 +//! `files[]` 条目 ⇒ 补不出来 ⇒ `3`，不会发任何请求； +//! - 坏包用**一个不是 zip 的普通文件** ⇒ 开包即拒 ⇒ `1`（具体的恶意样本分类在 core 的 +//! `addon/tests/import_failures.rs`，这里只钉 CLI 的退出码与 JSON 契约）。 + +#[path = "support/mod.rs"] +mod support; + +use std::path::{Path, PathBuf}; + +use serde_json::Value; +use support::{run_cli, TempDir}; + +/// 写一个文件（自动建父目录）。 +fn write_file(path: &Path, bytes: &[u8]) { + if let Some(parent) = path.parent() { + std::fs::create_dir_all(parent).expect("建目录"); + } + std::fs::write(path, bytes).expect("写文件"); +} + +/// 造一个最小 MultiMC / Prism 实例目录。 +fn multimc_instance(root: &Path) -> PathBuf { + let instance = root.join("mmc"); + write_file( + &instance.join("mmc-pack.json"), + br#"{"formatVersion": 1, "components": [ + {"uid": "net.minecraft", "version": "1.20.1"}, + {"uid": "net.fabricmc.fabric-loader", "version": "0.15.11"}, + {"uid": "org.lwjgl3", "version": "3.3.2"}]}"#, + ); + write_file( + &instance.join("instance.cfg"), + b"InstanceType=OneSix\nname=cli pack\n", + ); + write_file(&instance.join(".minecraft/mods/a.jar"), b"jar bytes"); + instance +} + +/// 造一个目录形式的 mrpack：一条远端条目，但 `downloads` 为空（补不出来 ⇒ 缺文件）。 +fn mrpack_directory(root: &Path) -> PathBuf { + let source = root.join("mr-src"); + write_file( + &source.join("modrinth.index.json"), + br#"{"game": "minecraft", "formatVersion": 1, "versionId": "1.0.0", + "name": "cli mrpack", "summary": "dir-form mrpack", + "files": [{"path": "mods/ghost.jar", + "hashes": {"sha1": "0123456789abcdef0123456789abcdef01234567", + "sha512": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}, + "env": {"client": "required", "server": "required"}, + "downloads": [], "fileSize": 11}], + "dependencies": {"minecraft": "1.20.1", "fabric-loader": "0.15.11"}}"#, + ); + write_file(&source.join("overrides/config/known.toml"), b"k = 1\n"); + source +} + +fn parse_json(stdout: &str) -> Value { + serde_json::from_str(stdout) + .unwrap_or_else(|error| panic!("stdout 不是合法 JSON（{error}）：{stdout}")) +} + +#[test] +fn imports_a_multimc_instance_and_exits_zero() { + let data = TempDir::new("pack-ok"); + let source = multimc_instance(data.path()); + let target = data.path().join("inst"); + let (code, stdout, stderr) = run_cli(&[ + "pack", + "import", + &source.display().to_string(), + "--target", + &target.display().to_string(), + "--data-dir", + &data.arg(), + "--no-register", + "--json", + ]); + + assert_eq!(code, 0, "stdout={stdout} stderr={stderr}"); + let value = parse_json(&stdout); + assert_eq!(value["ok"], Value::Bool(true)); + assert_eq!(value["data"]["status"], Value::String("success".into())); + assert_eq!(value["data"]["format"], Value::String("multimc".into())); + assert_eq!( + value["data"]["loader"]["kind"], + Value::String("fabric".into()) + ); + // 走过的阶段都记下来了。 + let stages = value["data"]["stages"].as_array().expect("stages 数组"); + assert!(stages.iter().any(|stage| stage == "probe"), "{stages:?}"); + assert!(stages.iter().any(|stage| stage == "commit"), "{stages:?}"); + // 内容真的落地了。 + assert_eq!( + std::fs::read(target.join("mods/a.jar")).expect("a.jar"), + b"jar bytes" + ); + // 未支持的 component 逐项进 JSON。 + assert_eq!( + value["data"]["rejected_components"][0]["uid"], + Value::String("org.lwjgl3".into()) + ); +} + +#[test] +fn missing_files_make_it_partial_and_exit_three() { + let data = TempDir::new("pack-partial"); + let source = mrpack_directory(data.path()); + let target = data.path().join("inst"); + let (code, stdout, stderr) = run_cli(&[ + "pack", + "import", + &source.display().to_string(), + "--target", + &target.display().to_string(), + "--data-dir", + &data.arg(), + "--no-register", + "--json", + ]); + + assert_eq!( + code, 3, + "部分成功是 3，不是 0/1：stdout={stdout} stderr={stderr}" + ); + let value = parse_json(&stdout); + assert_eq!(value["data"]["status"], Value::String("partial".into())); + assert_eq!( + value["data"]["missing"].as_array().map(Vec::len), + Some(1), + "补不出来的条目要如实记缺：{stdout}" + ); + // 覆盖内容照装。 + assert!(target.join("config/known.toml").is_file()); +} + +#[test] +fn failed_import_exits_one_and_still_emits_structured_json() { + let data = TempDir::new("pack-fail"); + let pack = data.path().join("broken.zip"); + // 一个根本不是 zip 的文件：开包即拒。 + write_file(&pack, b"this is not a zip archive"); + + let target = data.path().join("inst"); + let (code, stdout, stderr) = run_cli(&[ + "pack", + "import", + &pack.display().to_string(), + "--target", + &target.display().to_string(), + "--data-dir", + &data.arg(), + "--no-register", + "--json", + ]); + + assert_eq!(code, 1, "stdout={stdout} stderr={stderr}"); + // 失败也**必须**是结构化 JSON（不抛栈、不打人类可读文本到 stdout）。 + let value = parse_json(&stdout); + assert_eq!(value["ok"], Value::Bool(true)); + assert_eq!(value["data"]["status"], Value::String("failed".into())); + assert!( + value["data"]["error"]["code"].is_string(), + "失败要带稳定码：{stdout}" + ); + assert_eq!(value["data"]["rolled_back"], Value::Bool(true)); + // 零残留。 + assert!(!target.exists(), "致命失败后目标目录必须不存在"); + // 失败也不是"崩了"：stderr 里不该出现 panic 之类的栈信息。 + assert!(!stderr.contains("panicked"), "{stderr}"); +} + +#[test] +fn other_commands_still_exit_zero() { + // `Outcome::exit_code` 是给 pack import 用的；其它命令的行为不许变。 + let data = TempDir::new("pack-regression"); + let (code, stdout, _) = run_cli(&["instances", "list", "--data-dir", &data.arg()]); + assert_eq!(code, 0, "{stdout}"); + let (code, _, _) = run_cli(&["--help"]); + assert_eq!(code, 0); + let (code, _, _) = run_cli(&["config", "get", "--data-dir", &data.arg()]); + assert_eq!(code, 0); +} + +#[test] +fn help_lists_the_pack_command() { + let (code, stdout, _) = run_cli(&["help", "pack"]); + assert_eq!(code, 0); + assert!(stdout.contains("pack import"), "{stdout}"); + assert!(stdout.contains("部分成功"), "{stdout}"); + let (code, stdout, _) = run_cli(&["--help"]); + assert_eq!(code, 0); + assert!(stdout.contains("pack import"), "总帮助里也要有：{stdout}"); +} diff --git a/crates/cli/tests/parse_test.rs b/crates/cli/tests/parse_test.rs new file mode 100644 index 0000000..62a17cb --- /dev/null +++ b/crates/cli/tests/parse_test.rs @@ -0,0 +1,338 @@ +//! 子命令解析：手写解析器的语法契约。 + +#[path = "support/mod.rs"] +mod support; + +use unlucky_cli::cli::{parse, AccountsAddKind, Command, Globals}; +use unlucky_cli::error::ErrorKind; + +fn invoke(args: &[&str]) -> unlucky_cli::cli::Invocation { + let owned: Vec = args.iter().map(|arg| arg.to_string()).collect(); + parse(&owned).unwrap_or_else(|error| panic!("解析失败：{error}")) +} + +#[test] +fn no_args_is_welcome() { + let invocation = invoke(&[]); + assert_eq!(invocation.command, Command::Welcome); + assert_eq!(invocation.globals, Globals::default()); +} + +#[test] +fn version_flags() { + assert_eq!(invoke(&["--version"]).command, Command::Version); + assert_eq!(invoke(&["-V"]).command, Command::Version); + assert_eq!(invoke(&["version"]).command, Command::Version); +} + +#[test] +fn help_takes_topic_from_positional() { + assert_eq!(invoke(&["--help"]).command, Command::Help(None)); + assert_eq!( + invoke(&["--help", "launch"]).command, + Command::Help(Some("launch".to_string())) + ); + assert_eq!( + invoke(&["help", "config"]).command, + Command::Help(Some("config".to_string())) + ); +} + +#[test] +fn globals_are_position_independent() { + let invocation = invoke(&["instances", "list", "--json", "--quiet"]); + assert_eq!(invocation.command, Command::InstancesList); + assert!(invocation.globals.json); + assert!(invocation.globals.quiet); + + let before = invoke(&["--json", "instances", "list"]); + assert!(before.globals.json); + assert_eq!(before.command, Command::InstancesList); +} + +#[test] +fn data_dir_accepts_both_forms() { + assert_eq!( + invoke(&["--data-dir", "/tmp/ull", "instances", "list"]) + .globals + .data_dir, + Some(std::path::PathBuf::from("/tmp/ull")) + ); + assert_eq!( + invoke(&["instances", "list", "--data-dir=/tmp/ull"]) + .globals + .data_dir, + Some(std::path::PathBuf::from("/tmp/ull")) + ); +} + +#[test] +fn install_flags() { + let Command::Install(args) = + invoke(&["install", "1.20.1", "--loader", "vanilla", "--name=x"]).command + else { + panic!("应为 install"); + }; + assert_eq!(args.version, "1.20.1"); + assert_eq!(args.loader.as_deref(), Some("vanilla")); + assert_eq!(args.name.as_deref(), Some("x")); + assert!(!args.dry_run); + assert!(args.progress, "人类模式默认打实时进度"); +} + +#[test] +fn install_loader_version_flag() { + let Command::Install(args) = invoke(&[ + "install", + "1.20.1", + "--loader", + "fabric", + "--loader-version", + "0.15.11", + ]) + .command + else { + panic!("应为 install"); + }; + assert_eq!(args.loader.as_deref(), Some("fabric")); + assert_eq!(args.loader_version.as_deref(), Some("0.15.11")); + // 不带该 flag 时为 None（由 core 取官方默认版本）。 + let Command::Install(default) = invoke(&["install", "1.20.1"]).command else { + panic!("应为 install"); + }; + assert!(default.loader_version.is_none()); +} + +#[test] +fn install_dry_run_flag_and_progress_suppression() { + let Command::Install(args) = invoke(&["install", "1.20.1", "--dry-run"]).command else { + panic!("应为 install"); + }; + assert!(args.dry_run); + assert!(args.progress); + assert!(!args.json_progress, "人类模式打文本进度"); + + // `--json`：stderr 换成 JSONL 进度（stdout 仍是单个信封）。 + let Command::Install(args) = invoke(&["--json", "install", "1.20.1"]).command else { + panic!("应为 install"); + }; + assert!(args.progress); + assert!(args.json_progress); + + // `--quiet`：一律不打进度。 + let Command::Install(args) = invoke(&["install", "1.20.1", "-q"]).command else { + panic!("应为 install"); + }; + assert!(!args.progress); + assert!(!args.dry_run); +} + +#[test] +fn launch_flags_and_defaults() { + let Command::Launch(args) = invoke(&["launch", "生存服"]).command else { + panic!("应为 launch"); + }; + assert_eq!(args.instance, "生存服"); + assert!(!args.dry_run); + assert_eq!(args.java, None); + assert_eq!(args.max_memory, None); + + let Command::Launch(args) = invoke(&[ + "launch", + "生存服", + "--dry-run", + "--java", + "/opt/jdk/bin/java", + "--username", + "Steve", + "--max-memory", + "4096", + ]) + .command + else { + panic!("应为 launch"); + }; + assert!(args.dry_run); + assert_eq!(args.username.as_deref(), Some("Steve")); + assert_eq!(args.max_memory, Some(4096)); +} + +#[test] +fn accounts_subcommands() { + assert_eq!(invoke(&["accounts"]).command, Command::AccountsList); + assert_eq!(invoke(&["accounts", "list"]).command, Command::AccountsList); + + let Command::AccountsAdd(args) = invoke(&["accounts", "add", "offline", "Steve"]).command + else { + panic!("应为 accounts add offline"); + }; + assert_eq!(args.kind, AccountsAddKind::Offline); + assert_eq!(args.name.as_deref(), Some("Steve")); + + let Command::AccountsAdd(args) = invoke(&["accounts", "add", "msa"]).command else { + panic!("应为 accounts add msa"); + }; + assert_eq!(args.kind, AccountsAddKind::Microsoft); + assert_eq!(args.name, None); + + let Command::AccountsRemove { name } = invoke(&["accounts", "remove", "Steve"]).command else { + panic!("应为 accounts remove"); + }; + assert_eq!(name, "Steve"); +} + +#[test] +fn launch_account_flag() { + let Command::Launch(args) = invoke(&["launch", "生存服", "--account", "Steve"]).command + else { + panic!("应为 launch"); + }; + assert_eq!(args.account.as_deref(), Some("Steve")); + assert_eq!(args.username, None); +} + +#[test] +fn logs_and_diag_default_tails() { + let Command::Logs(args) = invoke(&["logs", "abc"]).command else { + panic!("应为 logs"); + }; + assert_eq!(args.tail, 200); + + let Command::Diag(args) = invoke(&["diag", "abc", "--tail", "10"]).command else { + panic!("应为 diag"); + }; + assert_eq!(args.tail, 10); +} + +#[test] +fn config_get_set_forms() { + let Command::ConfigGet(args) = invoke(&["config", "get"]).command else { + panic!("应为 config get"); + }; + assert_eq!(args.key, None); + assert!(!args.show_secret); + + let Command::ConfigGet(args) = + invoke(&["config", "get", "ui.language", "--show-secret"]).command + else { + panic!("应为 config get"); + }; + assert_eq!(args.key.as_deref(), Some("ui.language")); + assert!(args.show_secret); + + let Command::ConfigSet(args) = invoke(&["config", "set", "ui.language", "en_us"]).command + else { + panic!("应为 config set"); + }; + assert_eq!(args.key, "ui.language"); + assert_eq!(args.value, "en_us"); +} + +#[test] +fn java_subcommands() { + assert_eq!(invoke(&["java"]).command, Command::JavaList); + assert_eq!(invoke(&["java", "list"]).command, Command::JavaList); + assert_eq!( + invoke(&["java", "install", "21"]).command, + Command::JavaInstall { + major: 21, + vendor: None + } + ); + // D23：`--vendor` 钉死发行版（别名也认），`java vendors` 列出四家。 + assert_eq!( + invoke(&["java", "install", "21", "--vendor", "oracle"]).command, + Command::JavaInstall { + major: 21, + vendor: Some(unlucky_core::game::java::JdkVendor::Oracle), + } + ); + assert_eq!( + invoke(&["java", "install", "17", "--vendor", "adoptium"]).command, + Command::JavaInstall { + major: 17, + vendor: Some(unlucky_core::game::java::JdkVendor::Temurin), + } + ); + assert_eq!(invoke(&["java", "vendors"]).command, Command::JavaVendors); +} + +#[test] +fn usage_errors_are_user_errors() { + let cases: &[&[&str]] = &[ + &["frobnicate"], + &["install"], + &["launch"], + &["launch", "a", "b"], + &["instances", "list", "--nope"], + &["install", "1.20.1", "--dry-run=1"], + &["config", "set", "only-key"], + &["java", "install", "abc"], + &["--data-dir"], + &["sessions", "watch"], + &["accounts", "add"], + &["accounts", "add", "offline"], + &["accounts", "add", "authlib"], + &["accounts", "remove"], + &["accounts", "frobnicate"], + ]; + for args in cases { + let owned: Vec = 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", + ] { + assert!( + unlucky_cli::cli::help::topic(topic).is_some(), + "缺少 {topic} 的帮助" + ); + } + assert!(unlucky_cli::cli::help::topic("nope").is_none()); +} diff --git a/crates/cli/tests/support/mod.rs b/crates/cli/tests/support/mod.rs new file mode 100644 index 0000000..a14e011 --- /dev/null +++ b/crates/cli/tests/support/mod.rs @@ -0,0 +1,159 @@ +//! 集成测试共用夹具：临时数据根、命令执行器、最小版本 JSON / 会话索引。 +//! +//! 每个测试目标都会整份编译本文件但只用其中一部分，因此这里放开 dead_code。 +#![allow(dead_code)] + +use std::path::{Path, PathBuf}; +use std::sync::atomic::{AtomicU64, Ordering}; +use std::time::{SystemTime, UNIX_EPOCH}; + +/// 一次性临时目录（`Drop` 时清理）。 +pub struct TempDir { + path: PathBuf, +} + +impl TempDir { + /// 建一个唯一目录。 + pub fn new(tag: &str) -> Self { + static COUNTER: AtomicU64 = AtomicU64::new(0); + let nanos = SystemTime::now() + .duration_since(UNIX_EPOCH) + .map_or(0, |duration| duration.as_nanos()); + let seq = COUNTER.fetch_add(1, Ordering::Relaxed); + let path = std::env::temp_dir().join(format!( + "ull-cli-test-{tag}-{}-{seq}-{nanos}", + std::process::id() + )); + std::fs::create_dir_all(&path).expect("创建临时目录"); + Self { path } + } + + /// 目录路径。 + pub fn path(&self) -> &Path { + &self.path + } + + /// 目录的字符串形式（喂给 `--data-dir`）。 + pub fn arg(&self) -> String { + self.path.display().to_string() + } +} + +impl Drop for TempDir { + fn drop(&mut self) { + let _ = std::fs::remove_dir_all(&self.path); + } +} + +/// 跑一次 CLI，返回（退出码, stdout, stderr）。 +pub fn run_cli(args: &[&str]) -> (i32, String, String) { + let owned: Vec = 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。 +pub fn write_session(data_root: &Path) -> String { + let sid = "20261030T101500-abcdef"; + let dir = data_root + .join(".ULL") + .join("data") + .join("agent") + .join("sessions") + .join("game"); + std::fs::create_dir_all(&dir).expect("创建会话目录"); + let events = [ + serde_json::json!({"v":1,"seq":0,"ts":"2026-10-30T10:15:00Z","t_ms":0,"kind":"session_start","session_id":sid,"payload":{"instance_name":"生存服","game_version":"1.20.1"}}), + serde_json::json!({"v":1,"seq":1,"ts":"2026-10-30T10:15:02Z","t_ms":1500,"kind":"stdout","session_id":sid,"payload":{"line":"[main/INFO]: Loading Minecraft 1.20.1","level":"info"}}), + serde_json::json!({"v":1,"seq":2,"ts":"2026-10-30T10:15:05Z","t_ms":4200,"kind":"stderr","session_id":sid,"payload":{"line":"java.lang.OutOfMemoryError: Java heap space","level":"error"}}), + ]; + let mut text = String::new(); + for event in events { + text.push_str(&serde_json::to_string(&event).expect("序列化事件")); + text.push('\n'); + } + std::fs::write(dir.join(format!("{sid}.jsonl")), text).expect("写事件流"); + let entry = serde_json::json!({ + "v": 1, + "session_id": sid, + "instance_id": "11111111-2222-4333-8444-555555555555", + "instance_name": "生存服", + "game_version": "1.20.1", + "started_at": "2026-10-30T10:15:00Z", + "ended_at": "2026-10-30T10:15:06Z", + "duration_ms": 5000, + "exit_code": 1, + "exit_type": "application_error", + "silent_failure": false, + "window_detected": false, + "event_count": 3, + "log_path": format!("{sid}.jsonl"), + "crash_found": false, + "diagnosis_top": null + }); + std::fs::write( + dir.join("index.jsonl"), + format!("{}\n", serde_json::to_string(&entry).expect("序列化索引")), + ) + .expect("写会话索引"); + sid.to_string() +} diff --git a/crates/core/Cargo.toml b/crates/core/Cargo.toml new file mode 100644 index 0000000..d39441e --- /dev/null +++ b/crates/core/Cargo.toml @@ -0,0 +1,74 @@ +[package] +name = "unlucky-core" +description = "Unlucky-Launcher 领域库：纯逻辑，零 UI 依赖（D3 架构纪律）" +version.workspace = true +edition.workspace = true +license.workspace = true +authors.workspace = true +repository.workspace = true +rust-version.workspace = true +publish.workspace = true + +# 零 UI 依赖是硬约束：这里只允许纯逻辑/协议/IO 类依赖（serde/tokio/reqwest 等后续按模块加）， +# 任何时候都不得出现 slint / egui / iced / winit / gtk / javafx —— CI 的 core-no-ui job 守门。 +[dependencies] +# M15（core::diagnose）预接线：59 条规则正则、规则 YAML 解析、诊断输出序列化。 +# 真正使用方是 crates/core/src/diagnose/ 下的 collectors/engine/hs_err/loader/rules（M15 落地）。 +regex.workspace = true +serde.workspace = true +serde_json.workspace = true +serde_yaml_ng.workspace = true + +# M13（core::download）预接线：HTTP / 异步运行时 / 流 / 哈希校验。 +reqwest.workspace = true +tokio.workspace = true +futures-util.workspace = true +sha1.workspace = true +sha2.workspace = true +zip.workspace = true +# M31（core::auth）：离线 UUID = MD5 v3（与 HMCL / 服务端 nameUUIDFromBytes 对拍）。 +md-5.workspace = true +# M33（core::game::java）预接线：tar.gz 解压（Temurin 的 Linux/macOS 产物）。 +flate2.workspace = true +tar.workspace = true + +# M13 的 8 个下载测试 target（文件由 M13 阶段 B 用真实用例覆盖；脚手架期是占位）。 +# `tests/download/support/mod.rs` 是被各 test include 的公共夹具，不单独注册。 +[[test]] +name = "backoff" +path = "tests/download/backoff_test.rs" + +[[test]] +name = "health" +path = "tests/download/health_test.rs" + +[[test]] +name = "mirrors" +path = "tests/download/mirrors_test.rs" + +[[test]] +name = "region" +path = "tests/download/region_test.rs" + +[[test]] +name = "cache" +path = "tests/download/cache_test.rs" + +[[test]] +name = "chunked" +path = "tests/download/chunked_test.rs" + +[[test]] +name = "resume" +path = "tests/download/resume_test.rs" + +[[test]] +name = "engine_mock" +path = "tests/download/engine_mock_test.rs" + +[[test]] +name = "partfile" +path = "tests/download/partfile_test.rs" + +[lints] +workspace = true diff --git a/crates/core/src/addon/export.rs b/crates/core/src/addon/export.rs new file mode 100644 index 0000000..7068744 --- /dev/null +++ b/crates/core/src/addon/export.rs @@ -0,0 +1,65 @@ +//! 整合包**导出**（M112）：实例目录 → `.mrpack`（优先）/ CurseForge `manifest.json`（次之）。 +//! +//! 设计依据：`DevDocs/PlanDoc/08-mod-and-recommend.md` §2（D10）、 +//! `DevDocs/SubAgentsTalk/addon-整合包导入导出对接要点.md` §4（导出八条），格式模型与安全闸 +//! 是 M110 的 [`crate::addon::pack`]，本模块**只消费，不重写**。 +//! +//! # 一句话口径：不认识的 mod 不能丢、不能编 +//! +//! 用户原话（M112 任务书）：「要么能证明它可被远程替代，要么就必须内联进 `overrides/` 并在 +//! 结果里逐条报告」。落到代码就是三分类，**没有第四类**： +//! +//! | 分类 | 判据 | 产物 | +//! |------|------|------| +//! | 远程引用（[`FileClass::Remote`]） | 目标格式**能表达**它 + 某个目录（[`RemoteCatalog`]）**能证明**它的身份 | 清单 `files[]` 一条 | +//! | 内联（[`FileClass::Inline`]） | 证明不了，或证明了但目标格式表达不了 | 进 `overrides/`，原字节照搬 | +//! | 跳过（[`FileClass::Skipped`]） | 读不了 / 是符号链接 / 路径不安全 | 不写进包，**逐条**进报告 | +//! +//! 「能证明」用两条独立查询（契约 §4.4 的顺序）：**Modrinth SHA-1** → +//! [`RemoteCatalog::modrinth_by_sha1`]；**CurseForge 指纹**（[`crate::addon::pack::curseforge::fingerprint`]） +//! → [`RemoteCatalog::curseforge_by_fingerprint`]。两条都命中时两条直链都进 `downloads[]` +//! （HMCL 同款，兼容面更大）。**没有网络时**用 [`OfflineCatalog`]：所有文件都内联，包照样完整可导入 +//! ——这不是降级失败，是"证明不了就内联"的正面行为。 +//! +//! # 每条格式决策落在哪（tower 定案，别按任务书原话改回去） +//! +//! 1. **`.disabled` 走路径后缀**（`mods/x.jar.disabled`），不是 `env.client=optional`：后者只是 +//! "安装时可取消勾选"，装回来默认仍然启用 ⇒ 跨启动器不保真。官方 Modrinth 导出也是后缀。 +//! 2. **覆盖目录一律 `overrides/`**（不用 HMCL 那套 `client-overrides/`）：Modrinth 官方与 +//! Prism 都用它，兼容面最大。分侧语义在本轮导出里不产生（实例目录本身不分侧）。 +//! 3. **`game` + `dependencies` 从实例快照取**，绝不只写 `minecraft` 漏加载器：快照来自 +//! `versions//.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..1b6e274 --- /dev/null +++ b/crates/core/src/addon/export/scan.rs @@ -0,0 +1,189 @@ +//! 实例目录扫描：把"磁盘上有什么"变成 [`LocalFile`] 表（路径 + 字节数 + SHA-1 + 禁用位）。 +//! +//! # 扫哪些目录（写死白名单，不是"排除法"） +//! +//! 默认只扫 [`DEFAULT_CONTENT_ROOTS`] 这 8 个内容目录：`mods` / `config` / `defaultconfigs` / +//! `scripts` / `resourcepacks` / `shaderpacks` / `kubejs` / `openloader`。 +//! +//! 为什么用白名单而不是"排除 `versions/` `libraries/` `assets/`"： +//! +//! - 那三个目录是**启动器/游戏自己管的**（版本 JSON、依赖库、资源对象），塞进整合包只会让包 +//! 变成几 GB，且与"远程可替代"完全无关； +//! - `journals` `logs/` `crash-reports/` `saves/` `screenshots/` `backups/` **不属于**整合包内容 +//! （社区导出器一致不打包它们）； +//! - 排除法是"忘了就漏"的写法：以后实例里出现新目录（`.mixin.out`、`essential`…）会被静默打进去。 +//! +//! 白名单之外的东西**不是丢了**——它们本来就不该在整合包里。要打别的目录，用 +//! [`crate::addon::export::ExportRequest::with_content_roots`] 显式加。 +//! +//! # 内容目录里的一切都收（认不出的 mod 不能丢） +//! +//! 白名单目录里**不按扩展名过滤**：`mods/` 下的 `.jar`、`.jar.disabled`、`.jar.old`、 +//! `.ds_store`、社区自造后缀，一律按文件收。丢掉"我不认识的东西"正是用户点名不许的。 +//! +//! # 禁用它只看路径后缀 +//! +//! `x.jar` / `x.jar.disabled` / `x.jar.old` / `x.jar.disabled.old` 四种里，含 `.disabled` +//! （中间可能夹 `.old`）的才算禁用；`.old` 单独出现只是"旧版本残留"，原样保留、语义不变。 +//! 后缀**原样进包**——这是官方 Modrinth 导出的表达，也是唯一跨启动器保真的那条 +//! （`env.client=optional` 不是禁用，见 `crate::addon::pack::manifest::PackFile::disabled`）。 +//! +//! # 安全 +//! +//! 每条相对路径都要过 [`normalize_file`]（七条规则）才进表；不过的记 +//! [`SkipReason::UnsafePath`]。符号链接**不跟随**，记 [`SkipReason::SymbolicLink`] +//! （导出包里出现符号链接条目，解压端会把它当内容写出来）。 + +use std::path::{Path, PathBuf}; + +use super::report::FileReason; +use crate::addon::pack::path::{normalize_dir, normalize_file}; +use crate::download::types::HashAlgo; +use crate::download::verify::digest_file; + +/// 包内唯一的覆盖目录名（Modrinth 官方与 Prism 都用它，兼容面最大）。 +pub const OVERRIDES_DIR: &str = "overrides"; + +/// 默认扫的 8 个内容目录。 +pub const DEFAULT_CONTENT_ROOTS: [&str; 8] = [ + "mods", + "config", + "defaultconfigs", + "scripts", + "resourcepacks", + "shaderpacks", + "kubejs", + "openloader", +]; + +/// 一个待判定的本地文件。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct LocalFile { + /// 实例内相对路径（`/` 分隔，含 `.disabled` / `.old` 后缀，与磁盘上一致）。 + pub path: String, + /// 磁盘上的绝对路径（导出时按这个读字节）。 + pub disk: PathBuf, + /// 字节数。 + pub bytes: u64, + /// 内容 SHA-1（小写十六进制）。 + pub sha1: String, + /// 是否禁用态（路径后缀含 `.disabled`）。 + pub disabled: bool, +} + +/// 一个没能进包的文件，与它为什么没进。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct SkippedLocal { + /// 实例内相对路径（过不了规整时给原始串）。 + pub path: String, + /// 原因。 + pub reason: FileReason, +} + +/// 扫描一个实例目录，返回（可导出的文件表，跳过表），两张表都按路径排序。 +/// +/// 内容目录不存在不算错（空实例导出空包是合法的，只是报告里一个文件都没有）。 +#[must_use] +pub fn scan_instance(root: &Path, content_roots: &[String]) -> (Vec, 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` 这种"禁用 + 旧残留"组合）。 +#[must_use] +pub fn is_disabled_path(path: &str) -> bool { + let lowered = path.trim_end().to_ascii_lowercase(); + let without_old = lowered.strip_suffix(".old").unwrap_or(&lowered); + without_old.ends_with(".disabled") +} diff --git a/crates/core/src/addon/export/snapshot.rs b/crates/core/src/addon/export/snapshot.rs new file mode 100644 index 0000000..c733a99 --- /dev/null +++ b/crates/core/src/addon/export/snapshot.rs @@ -0,0 +1,209 @@ +//! 实例快照：`game` 与 `dependencies` 的唯一来源（**不解析实例 id 字符串**）。 +//! +//! # 为什么要读版本 JSON 而不是拆 `versions/` 的名字 +//! +//! 实例 id 的形状是社区约定，不是规范：`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..201b67f --- /dev/null +++ b/crates/core/src/addon/import.rs @@ -0,0 +1,179 @@ +//! 整合包**导入**（M111）：CurseForge `manifest.json` / Modrinth `.mrpack` / MultiMC·Prism 实例 +//! → 一个可启动的实例目录。 +//! +//! 设计依据：`DevDocs/PlanDoc/08-mod-and-recommend.md` §2（D10）、 +//! `DevDocs/PlanDoc/research/18-modpack-formats*.md`（字段清单，A/B 级来源）、 +//! `DevDocs/SubAgentsTalk/addon-整合包导入导出对接要点.md`（施工口径）。 +//! 格式模型与安全闸是 M110 的 [`crate::addon::pack`]：本模块**只消费，不重写**。 +//! +//! # 三条硬要求落在哪 +//! +//! | 要求 | 落点 | +//! |------|------| +//! | overrides 哈希**三方合并**（不静默覆盖用户改动） | [`merge`] 的判据 + [`baseline`] 的 base 侧 | +//! | 两阶段补全 + **失败分级**（仅"缺文件"可容忍） | [`pipeline`] 的顺序 + [`report::MissingFile`] 与 [`error::ImportError`] 的分工 | +//! | 路径穿越**双检** | 开包时 M110 [`crate::addon::pack::PackArchive::open`]，落地时 [`stage`] 的 `normalize_file` + `starts_with` 复核 | +//! +//! # 三种格式的语义（tower 定案，与 HMCL 相反的两条要记住） +//! +//! - **mrpack**：`overrides/` 与 `client-overrides/` 都解压，**后者胜**（Modrinth 官方客户端语义； +//! HMCL 恰好相反）；`server-overrides/` 客户端**不解压**；其余同名路径无官方优先级 ⇒ 按侧 +//! 优先级落地，不自创排序。 +//! - **CF**：溢出目录名取自清单 `overrides` 字段；`files[]` 只有 `projectID/fileID`，要 CF API +//! 才能补出文件名/地址——仓库里还没有 CF 客户端（D10 §5），因此这部分条目的**当前正确行为** +//! 是记成 `missing`（`Partial`），**绝不猜 `edge.forgecdn.net` 那类 URL**。 +//! - **MultiMC / Prism**：`mmc-pack.json` 的 `formatVersion` 必须恰为 `1`（M110 的读者会拒绝 +//! 其余值）；`.minecraft/` 直拷；非加载器 component（`org.lwjgl3` 等）**逐项**进 +//! [`report::RejectedComponent`]，不静默丢；只有导入，没有导出。 +//! +//! # `.disabled` 只按路径后缀 +//! +//! `x.jar` / `x.jar.disabled` / `x.jar.old` / `x.jar.disabled.old` 四种变体都识别，后缀**原样 +//! 保留**；`.old` 只识别与保留（不清除、不改名、不当回滚语义）。`env.client=optional` **不是** +//! 禁用——"可选"的语义是"安装时可取消勾选"，装回来默认仍然启用，两者不是一回事。 +//! +//! # 用法 +//! +//! ```ignore +//! let engine = /* core::download::DownloadEngine */; +//! let fetcher = DownloadEngineFetcher::new(&engine); +//! let request = ImportRequest::new(pack_path, instance_dir) +//! .with_fetcher(&fetcher) +//! .with_registration(&launcher_layout, None); +//! let report = download::blocking::block_on(import_pack(&request)); +//! match report.status { /* Success / Partial / Failed */ } +//! ``` +//! +//! # 刻意不做的事（分工边界） +//! +//! - **不删除**整合包升级后不再包含的文件：磁盘上的 `mods/` 里可能有用户自己装的模组， +//! 删旧文件是"清理"而不是"导入"（要做得先有"这个文件是整合包装的"的完整账本 + 用户确认）； +//! - **不装加载器**：只把清单翻译成 [`report::LoaderTarget`]（`kind` + 原版版本 + 加载器版本 +//! + 版本 id），真正的元数据解析/库下载仍是 `addon::loader` + `game::install` 的既有路径； +//! - **不碰 UI 类型**：core 零 UI 依赖（`core-no-ui` 门禁），报告只出现 `String` / `&'static str`； +//! - **不绕过下载引擎**：所有网络只经 [`fetch::PackFetcher`]，生产实现只有 +//! [`fetch::DownloadEngineFetcher`]（走 `core::download`）。 +//! +//! # 没验的部分（真实世界的欠账，报告里同样登记） +//! +//! 真实 CF / MultiMC 导出物（夹具是手造的）、超大包（>2G）、Windows 之外的平台、断网中途、 +//! 磁盘满、真实 CurseForge `files[]` 补全（缺 CF 客户端，见 [`fetch`] 的说明）。 + +pub mod baseline; +pub mod error; +pub mod fetch; +pub mod merge; +pub mod phase; +pub mod pipeline; +pub mod plan; +pub mod report; +pub mod stage; + +pub use baseline::{PackBaseline, BASELINE_FILE}; +pub use error::{ImportError, ImportErrorKind}; +pub use fetch::{ + CurseFileMeta, DownloadEngineFetcher, FetchError, FetchErrorKind, FetchFuture, FetchRequest, + FetchedFile, PackFetcher, +}; +pub use merge::{MergeAction, MergeDecision}; +pub use pipeline::baseline_relative; +pub use plan::{ImportPlan, PlanOverride, PlanRemote, SuffixVariant}; +pub use report::{ + keys, ConflictChoice, ConflictFile, ConflictReason, FileAction, FileSource, ImportIssue, + ImportProgress, ImportProgressSink, ImportReport, ImportStage, ImportStatus, ImportedFile, + LoaderTarget, MissingFile, MissingReason, RegisteredInstance, RejectedComponent, +}; +pub use stage::{RollbackOutcome, Staging}; + +use std::path::Path; + +use crate::addon::pack::PackLimits; +use crate::platform::layout::LauncherLayout; + +/// 冲突处置策略（默认保留用户文件）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub enum ConflictPolicy { + /// 保留用户那一侧（不覆盖、不补回被删的文件），冲突逐条进报告。 + #[default] + KeepUser, + /// 用包内内容覆盖（用户明确要求"整合包说了算"）。 + Overwrite, +} + +/// 一次导入请求。 +pub struct ImportRequest<'a> { + /// 包路径：zip（`.zip` / `.mrpack`）或 MultiMC 实例目录。 + pub pack: &'a Path, + /// 目标实例的游戏目录（`mods/` 直接在其下）。 + pub target: &'a Path, + /// 远端补全 + 下载；`None` = 离线导入（远端条目全部记成 `missing`）。 + pub fetcher: Option<&'a dyn PackFetcher>, + /// 数据根布局；给了才登记实例（`profiles.json`）。 + pub register: Option<&'a LauncherLayout>, + /// 实例展示名（缺省用包名）。 + pub instance_name: Option<&'a str>, + /// 冲突策略。 + pub conflict_policy: ConflictPolicy, + /// 包读取限额（条数 / 单条体积 / 解压总量）。 + pub limits: PackLimits, + /// 进度回调。 + pub progress: Option, +} + +impl<'a> ImportRequest<'a> { + /// 最小请求（离线、不登记、保留用户文件、默认限额）。 + #[must_use] + pub fn new(pack: &'a Path, target: &'a Path) -> Self { + Self { + pack, + target, + fetcher: None, + register: None, + instance_name: None, + conflict_policy: ConflictPolicy::KeepUser, + limits: PackLimits::default(), + progress: None, + } + } + + /// 挂上远端补全 / 下载。 + #[must_use] + pub fn with_fetcher(mut self, fetcher: &'a dyn PackFetcher) -> Self { + self.fetcher = Some(fetcher); + self + } + + /// 挂上实例登记（`name` 为 `None` 时用包名）。 + #[must_use] + pub fn with_registration(mut self, layout: &'a LauncherLayout, name: Option<&'a str>) -> Self { + self.register = Some(layout); + self.instance_name = name; + self + } + + /// 改冲突策略。 + #[must_use] + pub fn with_conflict_policy(mut self, policy: ConflictPolicy) -> Self { + self.conflict_policy = policy; + self + } + + /// 改读取限额。 + #[must_use] + pub fn with_limits(mut self, limits: PackLimits) -> Self { + self.limits = limits; + self + } + + /// 挂进度回调。 + #[must_use] + pub fn with_progress(mut self, sink: ImportProgressSink) -> Self { + self.progress = Some(sink); + self + } +} + +/// 导入一个整合包。**永不返回 `Err`**：三态与逐项原因都在 [`ImportReport`] 里。 +pub async fn import_pack(request: &ImportRequest<'_>) -> ImportReport { + pipeline::run(request).await +} diff --git a/crates/core/src/addon/import/baseline.rs b/crates/core/src/addon/import/baseline.rs new file mode 100644 index 0000000..db49a12 --- /dev/null +++ b/crates/core/src/addon/import/baseline.rs @@ -0,0 +1,162 @@ +//! 三方合并的 **base 侧**：上次导入写下的"包给的哈希"。 +//! +//! # 为什么必须落盘 +//! +//! 三方合并的三个输入是：`theirs`（这次包里给的）、`ours`（磁盘现状）、`base`（**上次**包里 +//! 给的）。`base` 不能从这次的包现算——那是 `theirs`；也不能从磁盘现算——那是 `ours`。少了 +//! `base` 就分不清两种截然不同的事实： +//! +//! - 磁盘内容 ≠ 新包内容，且磁盘内容 == 上次包内容 ⇒ **整合包升级**，该覆盖（用户没动过）； +//! - 磁盘内容 ≠ 新包内容，且磁盘内容 ≠ 上次包内容 ⇒ **用户改过**，不许静默覆盖。 +//! +//! 所以第一次导入就在实例根写一份基线；没有基线时（首次导入 / 用户手动塞进来的文件 / 基线 +//! 属于别的整合包）一律按"磁盘上已有同名文件"处理 —— 不覆盖、进冲突清单（最安全的一侧）。 +//! +//! # 落点：**唯一来源是 [`crate::game::layout::GameLayout::ull_root`]** +//! +//! `<实例根>/.ull/pack-baseline.json`（游戏根内的启动器私有目录）。 +//! +//! 这里有个踩过的坑（复审 r5 P1-1）：基线最初写成 `<实例根>/.ULL/…`（用了 +//! [`crate::platform::layout::LAUNCHER_HOME_DIR`]，那是**启动器数据根**的名字，在 exe/portable +//! 那一层），而读侧用 `GameLayout::ull_root()`（`<实例根>/.ull`，小写，实例**游戏根**内的 +//! 私有目录）。Windows / macOS 的大小写不敏感文件系统上两者是同一个文件，本机全绿；ext4 上 +//! 是两个文件 ⇒ 基线永远读不到（`UserModified`/`UserDeleted` 永不出现）。 +//! +//! 现在**读写都从 `ull_root()` 派生**：绝对路径 [`PackBaseline::path`]，相对路径 +//! [`PackBaseline::relative_path`]，两者由 `addon/tests/import_merge.rs` 的一条断言钉死 +//! （`path(root) == root.join(relative_path())`）——这条在大小写敏感的系统上也抓得住。 +//! +//! # 包身份 +//! +//! 基线记包名与格式；下次导入发现"基线属于另一个包"时**不拿它当 base**（否则跨包导入同一 +//! 目录会把别人的哈希当成本次包的历史），而是降级成"无基线"并如实告警。 +//! +//! 基线里存的是**包声明的哈希**（不是磁盘实际哈希）：用户改过的文件在基线里仍是包的值， +//! 下次导入才会继续判成"用户改过"，而不会被"上次也是改动值"洗白。`.disabled` / `.old` +//! 后缀按原样进键名（后缀是路径的一部分，不附加语义）。 +//! +//! 读失败**不是**致命错误：基线坏了最多退化成"全部按 pre-existing 冲突处理"（保留用户文件）， +//! 比"因为读不出基线就整包回滚"合理。 + +use std::collections::BTreeMap; +use std::path::{Path, PathBuf}; + +use serde::{Deserialize, Serialize}; + +use crate::game::layout::GameLayout; + +/// 基线文件名。 +pub const BASELINE_FILE: &str = "pack-baseline.json"; +/// 基线 schema 版本。 +pub const BASELINE_SCHEMA: u32 = 1; + +/// 上次导入写下的包声明哈希表。 +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct PackBaseline { + /// schema 版本（迁移链入口）。 + #[serde(default = "default_schema")] + pub schema_version: u32, + /// 上次导入的包名（诊断 + 包身份判据）。 + #[serde(default)] + pub pack_name: String, + /// 上次导入命中的格式 id（包身份判据的另一半）。 + #[serde(default)] + pub format: String, + /// 实例内相对路径 → 包声明的 SHA-1。 + #[serde(default)] + pub files: BTreeMap, +} + +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/error.rs b/crates/core/src/addon/import/error.rs new file mode 100644 index 0000000..600a977 --- /dev/null +++ b/crates/core/src/addon/import/error.rs @@ -0,0 +1,204 @@ +//! 导入链路的**致命**失败分类（能容忍的缺文件不在这里，它们在 +//! [`super::report::MissingFile`] 里逐条记账）。 +//! +//! # 为什么要跟 `MissingFile` 分开 +//! +//! D10 §2 的失败分级只有一条判据：**这个错误是不是"某个文件搞不到"**。 +//! +//! | 情形 | 处置 | 落在哪 | +//! |------|------|--------| +//! | 某个远端文件下载失败 / 补全不出地址 / 没有网络 | 容忍，实例照装，状态降级 `Partial` | [`super::report::MissingFile`] | +//! | 路径穿越 / 符号链接 / 超限额 / 清单坏 / 本地 IO / 摘要不符 | **整包回滚**，目标目录零残留 | 本模块 | +//! +//! 因此 [`ImportError`] 只描述**必须回滚**的失败；能容忍的东西一旦也塞进来，调用方就再也 +//! 分不清"该重试"和"该报恶意包"了。 +//! +//! # 稳定码 +//! +//! 包相关六类**直接沿用 M110 的码**（`pack_unsupported` / `pack_metadata` / +//! `pack_traversal` / `pack_symlink` / `pack_limits` / `pack_io`），不另起一套同义词： +//! 同一个事实在 CLI、日志、事件流里只能有一个字符串。导入独有的三类加 `import_` 前缀。 + +use std::fmt; + +use super::super::pack::{PackError, PackErrorKind}; +use super::fetch::{FetchError, FetchErrorKind}; + +/// 导入失败大类（稳定码进 `--json` 的 `error.code` 与日志，**不要改名**）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum ImportErrorKind { + /// 透传 M110 的六类包错误（稳定码沿用 `pack_*`）。 + Pack(PackErrorKind), + /// 下载到的内容与清单声明的摘要/大小**不符**（`import_integrity`）。 + Integrity, + /// 远端补全/下载在**致命**情形下失败（`import_fetch`；本地 IO 归 `pack_io`）。 + Fetch, + /// 清单里的加载器信息不足以组出安装计划（`import_loader`）。 + Loader, + /// 实例登记失败（`import_instance`）。 + Instance, +} + +impl ImportErrorKind { + /// 稳定字符串 id（进 `--json` 与日志）。 + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::Pack(kind) => kind.as_str(), + Self::Integrity => "import_integrity", + Self::Fetch => "import_fetch", + Self::Loader => "import_loader", + Self::Instance => "import_instance", + } + } + + /// 人读大类名（报告表格用）。 + #[must_use] + pub const fn label(self) -> &'static str { + match self { + Self::Pack(kind) => pack_label(kind), + Self::Integrity => "内容与清单不符", + Self::Fetch => "远端补全失败", + Self::Loader => "加载器信息不足", + Self::Instance => "实例登记失败", + } + } +} + +/// M110 六个大类的人读名（与 `PackErrorKind` 的稳定码一一对应，不另起一套枚举）。 +const fn pack_label(kind: PackErrorKind) -> &'static str { + match kind { + PackErrorKind::Unsupported => "格式不支持", + PackErrorKind::Metadata => "清单损坏", + PackErrorKind::Traversal => "路径穿越", + PackErrorKind::Symlink => "符号链接条目", + PackErrorKind::Limits => "超出安全限额", + PackErrorKind::Io => "本地 IO 失败", + } +} + +/// 一次**必须回滚**的导入失败。 +#[derive(Debug, Clone)] +pub struct ImportError { + kind: ImportErrorKind, + message: String, + hint: Option, +} + +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::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..3017224 --- /dev/null +++ b/crates/core/src/addon/import/fetch.rs @@ -0,0 +1,234 @@ +//! 远端补全与下载的**注入点**：导入管线自己不碰网络，只认这个 trait。 +//! +//! # 为什么是 trait 而不是直接调 `DownloadEngine` +//! +//! 三条理由，每条都对应一个真实麻烦： +//! +//! 1. **测试不能联网**：三种格式的端到端用例必须离线跑（CI 没有网，也不该有）； +//! 2. **CurseForge 的 `files[]` 补全还没有客户端**：CF 官方清单只有 `projectID/fileID`， +//! 要 `x-api-key` 的 `api.curseforge.com/v1/mods//files/` 才能换出文件名与地址。 +//! 仓库里没有这个客户端（D10 §5 规划中），而 [`crate::download::DownloadRequest`] **没有 +//! 自定义 header 字段**——硬塞进去会把"补不出来"伪装成"网络失败"。所以默认实现诚实地 +//! 返回 [`FetchErrorKind::Unsupported`]（= 可容忍的"搞不到"，进报告的 `missing`）， +//! **绝不猜下载 URL**：猜出来的地址一旦 404，用户看到的是"导入失败"而不是"这条暂时补不了"； +//! 3. **依赖方向**：`addon` 属于更高层的领域逻辑，让它直接持有一个 `DownloadEngine` 会把 +//! 镜像/健康度/地区档案这些下载侧策略涌进导入链路。 +//! +//! # 生产实现只走 `core::download` +//! +//! [`DownloadEngineFetcher`] 是本 crate 里**唯一**的生产实现，它只做一件事：把 +//! [`FetchRequest`] 翻译成 [`crate::download::DownloadRequest`] 交给引擎（镜像展开、退避、 +//! 续传、边下边算都在引擎里）。导入链路里**没有**第二个 `reqwest::Client`。 + +use std::future::Future; +use std::path::Path; +use std::pin::Pin; + +use crate::download::{ + DownloadEngine, DownloadError, DownloadErrorKind, DownloadRequest, Integrity, ResourceKind, +}; + +/// "搞不到"的成因（**分级判据只在这里**）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum FetchErrorKind { + /// 源上确实没有（404 / 文件被删）。 + NotFound, + /// 网络侧失败（超时、连不上、所有候选源都失败）。 + Network, + /// 本地 IO（写盘失败、磁盘满）。 + Io, + /// 内容与声明的摘要不符。 + Integrity, + /// 这条路走不通（CF 无客户端 / 没有可用下载地址）。 + Unsupported, +} + +impl FetchErrorKind { + /// 稳定字符串 id。 + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::NotFound => "fetch_not_found", + Self::Network => "fetch_network", + Self::Io => "fetch_io", + Self::Integrity => "fetch_integrity", + Self::Unsupported => "fetch_unsupported", + } + } + + /// 是否属于"某个文件搞不到"（可容忍，实例照装）。 + #[must_use] + pub const fn is_tolerable(self) -> bool { + matches!(self, Self::NotFound | Self::Network | Self::Unsupported) + } +} + +/// 一次取数失败。 +#[derive(Debug, Clone)] +pub struct FetchError { + kind: FetchErrorKind, + message: String, +} + +impl FetchError { + /// 构造。 + #[must_use] + pub fn new(kind: FetchErrorKind, message: impl Into) -> 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 { + let kind = match error.kind { + DownloadErrorKind::NotFound => FetchErrorKind::NotFound, + DownloadErrorKind::Integrity => FetchErrorKind::Integrity, + DownloadErrorKind::Io => FetchErrorKind::Io, + DownloadErrorKind::InvalidRequest => FetchErrorKind::Unsupported, + DownloadErrorKind::ServerError + | DownloadErrorKind::Timeout + | DownloadErrorKind::Network + | DownloadErrorKind::RangeUnsupported + | DownloadErrorKind::AllSourcesFailed => FetchErrorKind::Network, + }; + Self::new(kind, error.message) + } +} + +/// trait 方法返回的装箱 future（core 不引 `async-trait`，手写 `Pin>` 即可）。 +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, +} + +/// 一次文件下载请求。 +#[derive(Debug, Clone, Copy)] +pub struct FetchRequest<'a> { + /// 逻辑下载地址（官方源）。 + pub url: &'a str, + /// 落盘路径（导入器给的**暂存**路径，不是最终实例路径）。 + pub dest: &'a Path, + /// 期望 SHA-1（清单声明的）。 + pub sha1: Option<&'a str>, + /// 期望字节数。 + pub size: Option, +} + +/// 一次下载的产物。 +#[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}）；当前版本没有，本条记为缺文件" + ))) + }) + } + + /// 把 `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 fetch_file<'a>( + &'a self, + request: FetchRequest<'a>, + ) -> FetchFuture<'a, Result> { + Box::pin(async move { + let mut download = DownloadRequest::new( + ResourceKind::ModFile, + request.url, + request.dest.to_path_buf(), + ); + // 摘要长度不对就当"没给"：引擎白跑一趟网络比这更贵。 + if let Some(sha1) = request.sha1 { + let integrity = Integrity::sha1(sha1); + if integrity.is_well_formed() { + download.integrity = Some(integrity); + } + } + download.expected_size = request.size; + let outcome = self.engine.download(download).await?; + Ok(FetchedFile { + bytes: outcome.bytes, + }) + }) + } +} diff --git a/crates/core/src/addon/import/merge.rs b/crates/core/src/addon/import/merge.rs new file mode 100644 index 0000000..95c6775 --- /dev/null +++ b/crates/core/src/addon/import/merge.rs @@ -0,0 +1,139 @@ +//! overrides 三方合并的**判据**（纯函数，无 IO）：包内原值 / 磁盘现状 / 基线哈希。 +//! +//! # 一张表看完全部情形 +//! +//! 记 `T` = 包内声明（theirs）、`B` = 基线（base，上次导入的包声明）、`D` = 磁盘现状（ours）。 +//! `D` 为 `None` 表示文件不存在。 +//! +//! | `D` | `B` | 关系 | 结论 | 理由 | +//! |-----|-----|------|------|------| +//! | 无 | 无 | — | [`MergeAction::Install`] | 全新文件，没有可保护的东西 | +//! | 无 | 有 | `B` 任意 | [`MergeAction::KeepUser`] + `UserDeleted` | 用户删过：**不许**偷偷装回来 | +//! | 有 | 无 | `D == T` | [`MergeAction::SkipIdentical`] | 内容一样，写盘是浪费 | +//! | 有 | 无 | `D != T` | [`MergeAction::KeepUser`] + `PreExisting` | 没有基线可判 ⇒ 当用户已有内容 | +//! | 有 | 有 | `D == T` | [`MergeAction::SkipIdentical`] | 已经是最新 | +//! | 有 | 有 | `D == B` | [`MergeAction::Install`] | 用户没动过 ⇒ 整合包升级，覆盖是对的 | +//! | 有 | 有 | `D != B` | [`MergeAction::KeepUser`] + `UserModified` | 用户改过：**不许**静默覆盖 | +//! +//! 两条"不许"就是任务里的硬要求（"不得直接盖掉用户改过的文件"）。判据只此一处： +//! `ImportRequest::conflict_policy = Overwrite` 时，`KeepUser` 才会被判据的调用方翻成 +//! [`MergeAction::Install`]，**判据本身不读策略**——这样"哪些情形算冲突"与"冲突怎么处置" +//! 是两个可独立验证的事实。 +//! +//! # `.disabled` / `.old` 不参与判据 +//! +//! 后缀是路径的一部分（`mods/x.jar.disabled` 与 `mods/x.jar` 是**两个文件**），所以它们 +//! 天然按不同键各自走上面的表。不给 `.old` 附加"清理/回滚"语义（tower 定案：只识别与保留）。 + +use super::report::ConflictReason; + +/// 判据给出的动作（策略开关在调用方）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum MergeAction { + /// 写入包内内容（新建或覆盖）。 + Install, + /// 磁盘内容已经与包内一致，什么都不做。 + SkipIdentical, + /// 保留用户那一侧（不写盘）。 + KeepUser, +} + +/// 一次判定。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct MergeDecision { + /// 动作。 + pub action: MergeAction, + /// 算冲突时的成因（`None` = 不是冲突）。 + pub reason: Option, +} + +impl MergeDecision { + const fn plain(action: MergeAction) -> Self { + Self { + action, + reason: None, + } + } + + const fn conflict(reason: ConflictReason) -> Self { + Self { + action: MergeAction::KeepUser, + reason: Some(reason), + } + } + + /// 是否冲突（与最终处置无关）。 + #[must_use] + pub const fn is_conflict(self) -> bool { + self.reason.is_some() + } +} + +/// 三方合并判据。 +#[must_use] +pub fn decide(pack_sha1: &str, base_sha1: Option<&str>, disk_sha1: Option<&str>) -> MergeDecision { + match (disk_sha1, base_sha1) { + // 磁盘上没有这个文件。 + (None, None) => MergeDecision::plain(MergeAction::Install), + (None, Some(_)) => MergeDecision::conflict(ConflictReason::UserDeleted), + // 磁盘上有。 + (Some(disk), _) if disk == pack_sha1 => MergeDecision::plain(MergeAction::SkipIdentical), + (Some(_), None) => MergeDecision::conflict(ConflictReason::PreExisting), + (Some(disk), Some(base)) if disk == base => MergeDecision::plain(MergeAction::Install), + (Some(_), Some(_)) => MergeDecision::conflict(ConflictReason::UserModified), + } +} + +#[cfg(test)] +mod tests { + use super::*; + + const T: &str = "aaaa"; + const B: &str = "bbbb"; + + #[test] + fn fresh_file_is_installed() { + let decision = decide(T, None, None); + assert_eq!(decision.action, MergeAction::Install); + assert!(!decision.is_conflict()); + } + + #[test] + fn untouched_file_is_replaced_on_upgrade() { + // 磁盘 == 基线（用户没动过）⇒ 整合包升级，覆盖。 + let decision = decide(T, Some(B), Some(B)); + assert_eq!(decision.action, MergeAction::Install); + assert!(!decision.is_conflict()); + } + + #[test] + fn user_modification_is_a_conflict() { + let decision = decide(T, Some(B), Some("cccc")); + assert_eq!(decision.action, MergeAction::KeepUser); + assert_eq!(decision.reason, Some(ConflictReason::UserModified)); + } + + #[test] + fn user_deletion_is_a_conflict() { + let decision = decide(T, Some(B), None); + assert_eq!(decision.action, MergeAction::KeepUser); + assert_eq!(decision.reason, Some(ConflictReason::UserDeleted)); + } + + #[test] + fn pre_existing_without_baseline_is_a_conflict() { + let decision = decide(T, None, Some("dddd")); + assert_eq!(decision.action, MergeAction::KeepUser); + assert_eq!(decision.reason, Some(ConflictReason::PreExisting)); + } + + #[test] + fn identical_content_is_skipped() { + // 无论有没有基线，磁盘与包内一致就不写。 + assert_eq!(decide(T, None, Some(T)).action, MergeAction::SkipIdentical); + assert_eq!( + decide(T, Some(B), Some(T)).action, + MergeAction::SkipIdentical + ); + } +} diff --git a/crates/core/src/addon/import/phase.rs b/crates/core/src/addon/import/phase.rs new file mode 100644 index 0000000..1d24268 --- /dev/null +++ b/crates/core/src/addon/import/phase.rs @@ -0,0 +1,379 @@ +//! 两个落盘阶段的实现：**覆盖内容解压** 与 **远端补全下载**（共用同一张三方合并表）。 +//! +//! 拆出来是为了让 `pipeline.rs` 只剩"顺序与收尾"：阶段实现里看得见"每个文件怎么判"， +//! 编排里看得见"什么时候回滚"。 + +use std::path::Path; + +use super::super::pack::{PackArchive, PackError}; +use super::baseline::PackBaseline; +use super::error::ImportError; +use super::fetch::{FetchError, FetchRequest}; +use super::merge::{self, MergeAction}; +use super::pipeline::tell; +use super::plan::{curse_class_dir, ImportPlan, PlanRemote}; +use super::report::{ + ConflictChoice, ConflictFile, ConflictReason, FileAction, ImportReport, ImportStage, + ImportedFile, MissingFile, MissingReason, +}; +use super::stage::Staging; +use super::ImportRequest; +use crate::download::verify::{self, digest_bytes}; +use crate::download::HashAlgo; + +/// 阶段一：覆盖条目落暂存 + 三方合并。 +pub(crate) async fn extract_overrides( + request: &ImportRequest<'_>, + archive: &PackArchive, + plan: &ImportPlan, + baseline: &PackBaseline, + staging: &Staging, + report: &mut ImportReport, + next: &mut PackBaseline, +) -> Result<(), ImportError> { + let total = plan.overrides.len(); + let target = staging.target().to_path_buf(); + for (index, entry) in plan.overrides.iter().enumerate() { + tell( + &request.progress, + ImportStage::Extract, + index, + total, + Some(entry.path.clone()), + ); + let name = format!("{}/{}", entry.dir, entry.path); + let bytes = archive.read(&name)?.ok_or_else(|| { + ImportError::from(PackError::metadata(format!( + "清单列了 {name}，但包里读不到这个条目（声明与实际不符）" + ))) + })?; + // 用**实测**摘要而不是模型里记的那个：模型可能来自外部构造。 + let pack_sha1 = digest_bytes(HashAlgo::Sha1, &bytes); + next.insert(entry.path.clone(), pack_sha1.clone()); + let disk = disk_sha1(&target.join(&entry.path))?; + let decision = merge::decide(&pack_sha1, baseline.sha1(&entry.path), disk.as_deref()); + let (action, choice) = settle(decision, disk.is_some(), request.conflict_policy); + if let Some(reason) = decision.reason { + report.conflicts.push(conflict( + entry.path.clone(), + reason, + choice, + &pack_sha1, + bytes.len() as u64, + baseline.sha1(&entry.path).map(str::to_string), + disk, + )); + } + if action.wrote() { + staging.write(&entry.path, &bytes)?; + report.bytes_written += bytes.len() as u64; + } + report.files.push(ImportedFile { + path: entry.path.clone(), + source: entry.source, + sha1: Some(pack_sha1), + bytes: bytes.len() as u64, + disabled: entry.disabled, + action, + note: entry.note.clone(), + }); + } + Ok(()) +} + +/// 阶段二：远端条目补全 + 下载 + 同一张合并表。 +pub(crate) async fn fetch_remote( + request: &ImportRequest<'_>, + plan: &ImportPlan, + baseline: &PackBaseline, + staging: &Staging, + report: &mut ImportReport, + next: &mut PackBaseline, +) -> Result<(), ImportError> { + let total = plan.remote.len(); + let target = staging.target().to_path_buf(); + for (index, entry) in plan.remote.iter().enumerate() { + let display = entry.path.clone().unwrap_or_else(|| entry.file.key()); + tell( + &request.progress, + ImportStage::Fetch, + index, + total, + Some(display), + ); + let Some(resolved) = resolve(request, entry).await? else { + report + .missing + .push(missing_for(entry, request.fetcher.is_some())); + continue; + }; + let disk = disk_sha1(&target.join(&resolved.path))?; + // 有声明摘要就能先判合并：命中"保留用户 / 已一致"时**不必下载**（省一次网络）。 + if let Some(declared) = resolved.sha1.clone() { + let decision = merge::decide(&declared, baseline.sha1(&resolved.path), disk.as_deref()); + let (action, choice) = settle(decision, disk.is_some(), request.conflict_policy); + if !action.wrote() { + next.insert(resolved.path.clone(), declared.clone()); + if let Some(reason) = decision.reason { + report.conflicts.push(conflict( + resolved.path.clone(), + reason, + choice, + &declared, + resolved.size.unwrap_or(0), + baseline.sha1(&resolved.path).map(str::to_string), + disk.clone(), + )); + } + report.files.push(ImportedFile { + path: resolved.path, + source: entry.source, + sha1: Some(declared), + bytes: resolved.size.unwrap_or(0), + disabled: entry.disabled, + action, + note: None, + }); + continue; + } + } + let dest = staging.dest_for(&resolved.path)?; + let fetched = match request.fetcher { + Some(fetcher) => { + fetcher + .fetch_file(FetchRequest { + url: &resolved.url, + dest: &dest, + sha1: resolved.sha1.as_deref(), + size: resolved.size, + }) + .await + } + None => Err(FetchError::unsupported("本次导入没有 fetcher（离线）")), + }; + let fetched = match fetched { + Ok(fetched) => fetched, + Err(error) if error.kind().is_tolerable() => { + report.missing.push(missing_from_error( + &resolved.path, + entry, + MissingReason::FetchFailed, + error.message(), + )); + continue; + } + Err(error) => return Err(error.into()), + }; + let pack_sha1 = digest_file(&dest)?; + if let Some(declared) = resolved.sha1.as_deref() { + if !verify::matches(declared, &pack_sha1) { + // 摘要不符 = 内容坏了 / 被换过，**不许**当成"暂时搞不到"混过去。 + return Err(ImportError::integrity(format!( + "{} 的摘要与清单声明不符（声明 {declared}，实际 {pack_sha1}）", + resolved.path + ))); + } + } + let decision = merge::decide(&pack_sha1, baseline.sha1(&resolved.path), disk.as_deref()); + let (action, choice) = settle(decision, disk.is_some(), request.conflict_policy); + if let Some(reason) = decision.reason { + report.conflicts.push(conflict( + resolved.path.clone(), + reason, + choice, + &pack_sha1, + fetched.bytes, + baseline.sha1(&resolved.path).map(str::to_string), + disk, + )); + } + if action.wrote() { + report.bytes_written += fetched.bytes; + } else { + staging.discard(&resolved.path)?; + } + next.insert(resolved.path.clone(), pack_sha1.clone()); + report.files.push(ImportedFile { + path: resolved.path, + source: entry.source, + sha1: Some(pack_sha1), + bytes: fetched.bytes, + disabled: entry.disabled, + action, + note: None, + }); + } + Ok(()) +} + +/// 一个已解析出"路径 + 地址"的远端条目。 +struct Resolved { + path: String, + url: String, + sha1: Option, + 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), + size: entry.file.size, + })); + } + // CurseForge：只有 projectID/fileID，必须靠 CF API 补全（当前默认不支持 ⇒ 如实记缺）。 + let (Some(project_id), Some(file_id)) = (entry.file.project_id, entry.file.file_id) else { + return Ok(None); + }; + let Some(fetcher) = request.fetcher else { + return Ok(None); + }; + let meta = match fetcher.curse_file(project_id, file_id).await { + Ok(meta) => meta, + Err(error) if error.kind().is_tolerable() => return Ok(None), + Err(error) => return Err(error.into()), + }; + let (Some(url), Some(dir)) = ( + meta.url.clone().filter(|url| !url.trim().is_empty()), + meta.class_id.and_then(curse_class_dir), + ) else { + // 作者关了 API 分发 / classId 认不出 ⇒ **不猜**目录、不猜 URL。 + return Ok(None); + }; + Ok(Some(Resolved { + path: format!("{dir}/{}", meta.file_name), + url, + sha1: meta.sha1, + size: meta.size, + })) +} + +/// 合并判定 + 策略 → 实际动作。 +fn settle( + decision: merge::MergeDecision, + disk_exists: bool, + policy: super::ConflictPolicy, +) -> (FileAction, ConflictChoice) { + let overwrite = policy == super::ConflictPolicy::Overwrite; + match decision.action { + MergeAction::Install => ( + if disk_exists { + FileAction::Replaced + } else { + FileAction::Installed + }, + ConflictChoice::Overwrite, + ), + MergeAction::SkipIdentical => (FileAction::SkippedIdentical, ConflictChoice::KeepUser), + MergeAction::KeepUser if overwrite => ( + if disk_exists { + FileAction::Replaced + } else { + FileAction::Installed + }, + ConflictChoice::Overwrite, + ), + MergeAction::KeepUser => (FileAction::KeptUser, ConflictChoice::KeepUser), + } +} + +/// 组装一条冲突记录。 +fn conflict( + path: String, + reason: ConflictReason, + choice: ConflictChoice, + pack_sha1: &str, + pack_size: u64, + base_sha1: Option, + 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, + } +} + +/// 组装一条缺失记录（条目本身补不出来）。 +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/pipeline.rs b/crates/core/src/addon/import/pipeline.rs new file mode 100644 index 0000000..22c2d04 --- /dev/null +++ b/crates/core/src/addon/import/pipeline.rs @@ -0,0 +1,389 @@ +//! 导入编排：**读取清单 → 解压覆盖内容 → 补全下载 → 落地 → 登记**，每步都可中断、可失败、可重试。 +//! +//! # 两阶段落盘（任务硬要求） +//! +//! 先落 `overrides/`（离线、包内自带），再去补远端文件。顺序不是审美问题： +//! +//! - 覆盖内容是最可能被用户改过的那部分——先判定冲突，才能在"用户改过"时**既不覆盖**也不 +//! 白下载同名文件（远端条目走同一张三方合并表，冲突就直接跳过下载）； +//! - 远端补全是唯一会失败于网络的一步，放最后意味着"网络不通"最多让结果变成 `Partial`， +//! 不会让已经解好的覆盖内容白干。 +//! +//! # 失败分级（判据只在一处：是不是"某个文件搞不到"） +//! +//! | 失败 | 结果 | +//! |------|------| +//! | 开包/探测/读清单/组计划失败（穿越、符号链接、限额、清单坏） | `Failed`，临时目录删掉，目标目录零残留 | +//! | 某条远端文件摸不到（离线 / CF 无客户端 / 404） | `Partial`，逐条进 `missing`，实例照装 | +//! | 下载到的内容与声明摘要不符 | `Failed`（这是**损坏或被换过**，不是"暂时搞不到"） | +//! | 本地写盘失败 | `Failed` | +//! | 实例登记失败 | `Failed`（连内容一起回滚，不留"有目录没档案"的半个实例；回滚不完整时如实列出） | +//! +//! **回滚也要如实**：回滚本身可能失败（文件被占用、权限），这时 `rolled_back` 为 `false` +//! 并在 `rollback.failed` 里逐项列出——不许在"可能没回干净"时宣称一致。 +//! +//! # 可重试 +//! +//! 失败后目标目录与导入前一致（或明确告诉你哪几项没回去），重跑同一个包是安全的；成功后再跑 +//! 一遍会靠基线里的哈希走"跳过 / 已一致"路径，不会重复写盘。 + +use super::super::pack::{PackArchive, PackError, PackRegistry}; +use super::baseline::PackBaseline; +use super::error::ImportError; +use super::phase; +use super::plan::ImportPlan; +use super::report::{ + keys, ImportIssue, ImportProgress, ImportReport, ImportStage, RegisteredInstance, +}; +use super::stage::{RollbackOutcome, Staging}; +use super::ImportRequest; + +/// 跑一次导入。**永不返回 `Err`**：所有失败都在报告的三态里。 +pub async fn run(request: &ImportRequest<'_>) -> ImportReport { + let mut report = ImportReport::empty(request.target.to_path_buf()); + + tell(&request.progress, ImportStage::Probe, 0, 0, None); + let (archive, plan) = match probe_and_plan(request) { + Ok(pair) => pair, + Err(error) => return abandoned(report, error), + }; + account_plan(&mut report, &plan); + + let baseline = load_baseline(request.target, &plan, &mut report); + let staging = match Staging::begin(request.target) { + Ok(staging) => staging, + Err(error) => return abandoned(report, error), + }; + + let mut next = baseline.clone(); + let staged = async { + phase::extract_overrides( + request, + &archive, + &plan, + &baseline, + &staging, + &mut report, + &mut next, + ) + .await?; + phase::fetch_remote(request, &plan, &baseline, &staging, &mut report, &mut next).await?; + write_baseline(&staging, &plan, &next) + } + .await; + if let Err(error) = staged { + staging.abort(); + return abandoned(report, error); + } + + // 引擎的续传残片（`.ullpart-*`）与 meta 不是整合包内容，提交前剔掉。 + match staging.purge_engine_artifacts() { + Ok(0) => {} + Ok(removed) => report.warnings.push(ImportIssue::new( + keys::NOTE_ENGINE_ARTIFACTS_DROPPED, + format!("提交前剔除了 {removed} 个下载引擎的中间产物（.ullpart-* / .ullmeta.json）"), + )), + Err(error) => { + staging.abort(); + return abandoned(report, error); + } + } + + tell(&request.progress, ImportStage::Commit, 0, 0, None); + let guard = match staging.commit() { + Ok(guard) => guard, + Err(failure) => return record_rollback(failed(report, failure.error), failure.rollback), + }; + + if let Some(layout) = request.register { + tell(&request.progress, ImportStage::Register, 0, 0, None); + let name = request + .instance_name + .filter(|name| !name.trim().is_empty()) + .unwrap_or(plan.manifest.name.as_str()); + match crate::game::install::register(layout, name, &plan.version_id, None) { + Ok(registration) => { + report.registered = Some(RegisteredInstance { + id: registration.profile.id.as_str().to_string(), + name: registration.profile.name.clone(), + version_id: registration.profile.version_id.clone(), + created: registration.created, + }); + report.warnings.push(ImportIssue::new( + keys::NOTE_REGISTERED, + format!( + "已登记实例 {:?}（{}）", + registration.profile.name, plan.version_id + ), + )); + } + Err(error) => { + // 内容落盘了但档案没建起来 = 用户看不见的半个实例 ⇒ 连内容一起回滚。 + let outcome = guard.rollback(); + return record_rollback( + failed(report, ImportError::instance(error.to_string())), + outcome, + ); + } + } + } + guard.finish(); + + report.finish_status(); + report +} + +/// 开包 + 探测 + 组计划（任何失败都是 `Failed`）。 +fn probe_and_plan(request: &ImportRequest<'_>) -> Result<(PackArchive, ImportPlan), ImportError> { + // 路径穿越双检 + 符号链接 + 条数/体积限额都在 `open` 里一次做完（M110 的 `archive`）。 + let archive = PackArchive::open(request.pack, request.limits)?; + let (format, manifest) = PackRegistry::builtin().read(&archive)?; + let plan = ImportPlan::build(&archive, format.id(), manifest)?; + Ok((archive, plan)) +} + +/// 把计划里的静态信息抄进报告。 +fn account_plan(report: &mut ImportReport, plan: &ImportPlan) { + report.format = Some(plan.format.clone()); + report.pack_name = Some(plan.manifest.name.clone()); + report.pack_version = plan.manifest.version.clone(); + report.game_version = Some(plan.mc_version.clone()); + report.loader = plan.loader.clone(); + report.version_id = Some(plan.version_id.clone()); + report.max_memory_mb = plan.max_memory_mb; + report.rejected_components.clone_from(&plan.rejected); + report.warnings.extend(plan.notes.iter().cloned()); +} + +/// 读三方合并的 base 侧：没有 / 读不出来 / **属于别的包** 三条路都不致命。 +/// +/// "属于别的包"要单独说一句：同一目录先后导入两个整合包时，若拿别人的基线当 base，用户改过 +/// 的文件会被判成"整合包升级"而**被静默覆盖**。所以身份不符时降级成"没有基线"并告警。 +fn load_baseline( + target: &std::path::Path, + plan: &ImportPlan, + report: &mut ImportReport, +) -> PackBaseline { + match PackBaseline::load(target) { + Ok(baseline) => { + if baseline.matches_pack(&plan.format, &plan.manifest.name) { + return baseline; + } + report.warnings.push(ImportIssue::new( + keys::NOTE_BASELINE_PACK_MISMATCH, + format!( + "基线属于另一个整合包（{} / {:?}），本次按「没有基线」处理：磁盘上同名文件一律算用户已有内容", + if baseline.format.is_empty() { + "?" + } else { + &baseline.format + }, + baseline.pack_name + ), + )); + PackBaseline::default() + } + Err(reason) => { + report.warnings.push(ImportIssue::new( + keys::NOTE_BASELINE_UNREADABLE, + format!( + "基线读不出来，本次按「没有基线」处理（磁盘上同名文件一律算用户已有内容）：{reason}" + ), + )); + PackBaseline::default() + } + } +} + +/// 把一次回滚的结果写进报告：**文案与机器位同源**，只有完整回滚才宣称"与导入前一致"。 +fn record_rollback(mut report: ImportReport, outcome: RollbackOutcome) -> ImportReport { + if outcome.is_complete() { + report.rolled_back = true; + report.warnings.push(ImportIssue::new( + keys::ROLLBACK_DONE, + format!( + "已回滚 {} 项：目标目录恢复为导入前的样子（{}）", + outcome.attempted, + report.target.display() + ), + )); + } else { + report.rolled_back = false; + report.warnings.push(ImportIssue::new( + keys::NOTE_ROLLBACK_INCOMPLETE, + format!( + "有 {} 项未能回滚（目标目录可能与导入前不同）：{}", + outcome.failure_count(), + outcome.failed.join("；") + ), + )); + } + report.rollback = Some(outcome); + report +} + +/// 基线作为**最后一个暂存文件**写进去：它跟同一个事务一起提交 / 回滚。 +fn write_baseline( + staging: &Staging, + plan: &ImportPlan, + next: &PackBaseline, +) -> Result<(), ImportError> { + let mut baseline = next.clone(); + baseline.pack_name.clone_from(&plan.manifest.name); + baseline.format.clone_from(&plan.format); + let bytes = baseline.to_bytes().map_err(PackError::io)?; + staging.write(&baseline_relative(), &bytes)?; + Ok(()) +} + +/// 基线相对实例根的路径（`<根>/.ull/pack-baseline.json`；与读侧同源，见 +/// [`PackBaseline::relative_path`]）。 +#[must_use] +pub fn baseline_relative() -> String { + PackBaseline::relative_path() + .to_string_lossy() + .replace('\\', "/") +} + +/// 发一条进度事件（`sink` 为 `None` 时什么都不做）。 +pub(super) fn tell( + sink: &Option, + stage: ImportStage, + done: usize, + total: usize, + current: Option, +) { + if let Some(sink) = sink { + sink(&ImportProgress { + stage, + done, + total, + current, + }); + } +} + +/// 失败收尾：**只落错误，不宣称目标目录状态**。 +/// +/// 口径由调用方补：从未写过目标目录 ⇒ [`abandoned`]；已经写过 ⇒ [`record_rollback`]。 +/// 早先这里无条件推"目标目录保持导入前的样子"，而随后的 `record_rollback` 可能再推 +/// "有 N 项未能回滚"——同一份 warnings 自相矛盾（复审 r6 抓到）。 +fn failed(mut report: ImportReport, error: ImportError) -> ImportReport { + report.rolled_back = false; + report.fail(error); + report +} + +/// 失败发生在**碰目标目录之前**（暂存目录已清）：这时才可以宣称"目标目录未被写入"。 +fn abandoned(report: ImportReport, error: ImportError) -> ImportReport { + let mut report = failed(report, error); + report.rolled_back = true; + report.warnings.push(ImportIssue::new( + keys::ROLLBACK_DONE, + format!( + "导入失败，已清理临时目录；目标目录未被写入（{}）", + report.target.display() + ), + )); + report +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::addon::import::ImportStatus; + + fn base() -> ImportReport { + ImportReport::empty(std::path::PathBuf::from("instance")) + } + + fn messages(report: &ImportReport) -> Vec<&str> { + report + .warnings + .iter() + .map(|note| note.message.as_str()) + .collect() + } + + fn incomplete() -> RollbackOutcome { + RollbackOutcome { + attempted: 3, + failed: vec!["删除 config/a.toml 失败：拒绝访问".to_string()], + } + } + + #[test] + fn incomplete_rollback_never_claims_the_target_is_untouched() { + // 复审 r6 第 1 条：机器位（rolled_back=false）诚实，文案位也必须诚实——同一份 warnings + // 里不许同时出现"保持导入前的样子"与"有 N 项未能回滚"。 + let report = record_rollback(failed(base(), ImportError::fetch("提交失败")), incomplete()); + + assert_eq!(report.status, ImportStatus::Failed); + assert!(!report.rolled_back, "回滚不完整时不许宣称一致"); + assert_eq!( + report.rollback.as_ref().map(RollbackOutcome::failure_count), + Some(1) + ); + let messages = messages(&report); + assert!( + messages + .iter() + .any(|line| line.contains("未能回滚") && line.contains("config/a.toml")), + "失败项要逐条列出：{messages:?}" + ); + assert!( + !messages.iter().any(|line| line.contains("保持导入前的样子") + || line.contains("未被写入") + || line.contains("恢复为导入前的样子")), + "回滚不完整却宣称一致（自相矛盾）：{messages:?}" + ); + } + + #[test] + fn complete_rollback_claims_consistency_exactly_once() { + let report = record_rollback( + failed(base(), ImportError::fetch("提交失败")), + RollbackOutcome { + attempted: 2, + failed: Vec::new(), + }, + ); + + assert!(report.rolled_back); + assert_eq!( + report.rollback.as_ref().map(RollbackOutcome::failure_count), + Some(0) + ); + let messages = messages(&report); + assert!( + messages + .iter() + .any(|line| line.contains("恢复为导入前的样子")), + "{messages:?}" + ); + assert!( + !messages.iter().any(|line| line.contains("未能回滚")), + "{messages:?}" + ); + } + + #[test] + fn pre_commit_failure_claims_untouched_only_via_abandoned() { + // `failed()` 本身不宣称任何目标目录状态；"从未写过目标目录"这条口径只由 `abandoned()` 给。 + let bare = failed(base(), ImportError::fetch("开包失败")); + assert!(!bare.rolled_back); + assert!(bare.rollback.is_none()); + assert!(!messages(&bare) + .iter() + .any(|line| line.contains("保持导入前的样子") || line.contains("未被写入"))); + + let report = abandoned(base(), ImportError::fetch("开包失败")); + assert!(report.rolled_back); + assert!(report.rollback.is_none()); + let messages = messages(&report); + assert!( + messages.iter().any(|line| line.contains("未被写入")), + "{messages:?}" + ); + } +} diff --git a/crates/core/src/addon/import/plan.rs b/crates/core/src/addon/import/plan.rs new file mode 100644 index 0000000..f9d5631 --- /dev/null +++ b/crates/core/src/addon/import/plan.rs @@ -0,0 +1,373 @@ +//! 清单 → **导入计划**：把三种格式的差异在进解压器之前全部拍平。 +//! +//! 计划是纯计算（只额外读一次 `instance.cfg`），产出四张表：覆盖条目、远端条目、 +//! 加载器计划输入、被拒绝的 component。落盘与合并都不在这里。 +//! +//! # 三种格式的语义在这层定死 +//! +//! | 事 | CurseForge | Modrinth | MultiMC / Prism | +//! |----|-----------|----------|-----------------| +//! | 覆盖目录 | 清单点名的**一个**目录（任意名字） | `overrides/` + `client-overrides/`（`server-overrides/` **不解压**） | `.minecraft/` | +//! | 同名冲突 | 不存在（单目录） | `client-overrides` **胜** `overrides`（Modrinth 官方客户端语义；与 HMCL 相反） | 不存在 | +//! | 远端条目 | `projectID/fileID`，**无路径无地址** ⇒ 必须补全 | 自带 `path`/`downloads`/`hashes` | 没有远端条目（内容就是目录） | +//! | 加载器 | `modLoaders[].id`（`neoforge-1.20.1-47.1.106` 的版本段**带 MC 前缀**） | `dependencies` 的键 | `components[].uid` | +//! # 三处"不许自创"的边界 +//! +//! 1. **覆盖目录的优先级只按侧**：`overrides/` 先、`client-overrides/` 后（后者胜）。同一 +//! 目录内的条目顺序**不重要**——M110 的 [`crate::addon::pack::PackOverrides::files`] 按路径 +//! 排序，zip 条目顺序没有保留；而同一目录内路径唯一，所以"按 zip 条目顺序落盘"与"按路径 +//! 排序落盘"在无重复时等价。有重复（跨目录）时由侧优先级决定，不靠条目顺序。 +//! 2. **`.disabled` 只认路径后缀**（官方 Modrinth 表达），`.old` **只识别与保留**（不清不删 +//! 不改名）。`env.client=optional` **不是**禁用（"可选"＝安装时可取消勾选）。判据在 +//! [`paths`]。 +//! 3. **MultiMC 的非加载器 component 逐项进报告**（`org.lwjgl3` / `net.fabricmc.intermediary` +//! / 社区自定义 uid）：静默丢它们等于"看起来装好了、其实少了补丁层"。 + +pub mod paths; + +pub use paths::{curse_class_dir, strip_mc_prefix, suffix_note, suffix_variant, SuffixVariant}; + +use super::super::pack::{ + curseforge, multimc, EnvSupport, PackArchive, PackError, PackFile, PackLoader, PackManifest, + PackOverrides, PackSide, +}; +use super::error::ImportError; +use super::report::{keys, FileSource, ImportIssue, LoaderTarget, RejectedComponent}; + +/// 一条要落地的覆盖条目。 +#[derive(Debug, Clone)] +pub struct PlanOverride { + /// 包内目录前缀（读包时拼 `/`）。 + 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, +} + +/// 一条要补全/下载的远端条目。 +#[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 ordered_overrides(&manifest) { + if group.side == PackSide::Server { + // Modrinth 官方客户端安装器就不解压 server-overrides/（A 级来源： + // install_mrpack.rs 的 strip_prefix 链只有 overrides/ 与 client-overrides/）。 + skipped_server_files += group.files.len(); + continue; + } + for file in &group.files { + let variant = suffix_variant(&file.path); + overrides.push(PlanOverride { + dir: group.dir.clone(), + path: file.path.clone(), + source: FileSource::from_side(group.side), + sha1: file.sha1.clone(), + size: file.size, + disabled: variant.is_disabled(), + note: suffix_note(variant, &file.path), + }); + } + } + if skipped_server_files > 0 { + notes.push(ImportIssue::new( + keys::NOTE_SERVER_OVERRIDES_SKIPPED, + format!( + "server-overrides/ 里的 {skipped_server_files} 个文件是服务端内容，客户端导入不解压（Modrinth 官方语义）" + ), + )); + } + + let mut remote: Vec = Vec::new(); + let source = if format_id == curseforge::ID { + FileSource::CurseForge + } else { + FileSource::Modrinth + }; + for file in &manifest.files { + if file.client == EnvSupport::Unsupported { + notes.push( + ImportIssue::new( + keys::NOTE_ENV_UNSUPPORTED, + "env.client=unsupported：客户端不需要这个文件，跳过".to_string(), + ) + .with_path(file.path.clone().unwrap_or_else(|| file.key())), + ); + continue; + } + let variant = file + .path + .as_deref() + .map_or(SuffixVariant::Plain, suffix_variant); + if file.client == EnvSupport::Optional { + notes.push( + ImportIssue::new( + keys::NOTE_OPTIONAL_FILE, + "env.client=optional：可选条目照常安装（「可选」不等于「禁用」）" + .to_string(), + ) + .with_path(file.path.clone().unwrap_or_else(|| file.key())), + ); + } + if let Some(note) = file + .path + .as_deref() + .and_then(|path| suffix_note(variant, path)) + { + notes.push(note); + } + remote.push(PlanRemote { + path: file.path.clone(), + source, + disabled: variant.is_disabled(), + file: file.clone(), + }); + } + + let max_memory_mb = if format_id == multimc::ID { + instance_memory(pack, &mut notes)? + } else { + None + }; + + Ok(Self { + format: format_id.to_string(), + manifest, + mc_version, + loader, + version_id, + rejected, + notes, + overrides, + remote, + max_memory_mb, + }) + } +} + +/// 覆盖目录按侧排序：`Both`（`overrides/`）先、`Client`（`client-overrides/`）后 = 后者胜。 +fn ordered_overrides(manifest: &PackManifest) -> Vec<&PackOverrides> { + let mut groups: Vec<&PackOverrides> = manifest.overrides.iter().collect(); + groups.sort_by_key(|group| match group.side { + PackSide::Both => 0_u8, + PackSide::Client => 1, + PackSide::Server => 2, + }); + groups +} + +/// 选一个加载器并翻译成 [`LoaderTarget`]。 +fn select_loader( + manifest: &PackManifest, + mc_version: &str, + format_id: &str, + notes: &mut Vec, + 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/paths.rs b/crates/core/src/addon/import/plan/paths.rs new file mode 100644 index 0000000..366596e --- /dev/null +++ b/crates/core/src/addon/import/plan/paths.rs @@ -0,0 +1,160 @@ +//! 路径与版本号的小判据（纯函数）：`.disabled` / `.old` 后缀变体与注记、CF 类别目录、MC 版本前缀。 +//! +//! 拆出来是因为它们是**格式事实**而非管线逻辑：`.disabled` 只按路径后缀（tower 定案，不用 +//! `env.client=optional`）、`.old` 只识别与保留（不清不删）、CF 的 `classId` 认不出就不猜。 + +use super::super::report::{keys, ImportIssue}; + +/// 路径后缀变体（`.disabled` / `.old` 的四种组合）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum SuffixVariant { + /// `mods/x.jar`。 + Plain, + /// `mods/x.jar.disabled`（官方 Modrinth 的禁用表达）。 + Disabled, + /// `mods/x.jar.old`（HMCL 生态常见：旧版本残留）。 + Old, + /// `mods/x.jar.disabled.old`。 + DisabledOld, +} + +impl SuffixVariant { + /// 是否禁用态。 + #[must_use] + pub const fn is_disabled(self) -> bool { + matches!(self, Self::Disabled | Self::DisabledOld) + } + + /// 是否带 `.old`（只用于报告，不附加清理语义）。 + #[must_use] + pub const fn is_old(self) -> bool { + matches!(self, Self::Old | Self::DisabledOld) + } +} + +/// 识别四种路径后缀变体。 +#[must_use] +pub fn suffix_variant(path: &str) -> SuffixVariant { + let lowered = path.trim_end().to_ascii_lowercase(); + let stripped = lowered.strip_suffix(".old").unwrap_or(&lowered); + let old = stripped.len() != lowered.len(); + let disabled = stripped.ends_with(".disabled"); + match (disabled, old) { + (false, false) => SuffixVariant::Plain, + (true, false) => SuffixVariant::Disabled, + (false, true) => SuffixVariant::Old, + (true, true) => SuffixVariant::DisabledOld, + } +} + +/// 后缀注记（`.disabled` / `.old`）：进报告，告诉用户"这个名字我们是认得的"。 +#[must_use] +pub fn suffix_note(variant: SuffixVariant, path: &str) -> Option { + 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/report.rs b/crates/core/src/addon/import/report.rs new file mode 100644 index 0000000..9181c2d --- /dev/null +++ b/crates/core/src/addon/import/report.rs @@ -0,0 +1,243 @@ +//! 导入结果：**三态 + 逐项原因**，给 CLI 的 `--json` 与 M109/M113 的页面直接消费。 +//! +//! # 三态不是"成功/失败"两态（M111 任务原文要求） +//! +//! | 状态 | 判据 | 退出码（CLI） | +//! |------|------|---------------| +//! | [`ImportStatus::Success`] | 清单里每条文件都落地、没有冲突 | `0` | +//! | [`ImportStatus::Partial`] | 有"搞不到"的文件（[`MissingFile`]）或有保留用户文件的冲突（[`ConflictFile`]） | `3` | +//! | [`ImportStatus::Failed`] | 致命错误（[`ImportError`]），**已整包回滚** | `1` | +//! +//! 把"部分成功"记成 `Success` 是这条管线最容易犯的错：用户会以为 mods 齐了，启动才发现缺 +//! 依赖。所以 [`ImportReport::finish_status`] 是**唯一**算状态的地方，字段私有语义由它收敛。 +//! +//! # 分文件 +//! +//! - [`keys`]：文案 key 常量表（稳定字符串，含 `ALL` 守门表）； +//! - [`items`]：条目类型（一条文件 / 一条冲突 / 一条缺失 / 一个 component / 加载器目标）； +//! - 本文件：三态、阶段、进度、以及总的 [`ImportReport`]。 + +pub mod items; +pub mod keys; + +pub use items::{ + ConflictChoice, ConflictFile, ConflictReason, FileAction, FileSource, ImportIssue, + ImportedFile, LoaderTarget, MissingFile, MissingReason, RegisteredInstance, RejectedComponent, +}; + +use std::path::PathBuf; + +use serde::Serialize; + +use super::error::ImportError; +use super::stage::RollbackOutcome; + +/// 导入三态。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)] +#[serde(rename_all = "snake_case")] +pub enum ImportStatus { + /// 全部落地、无冲突。 + Success, + /// 有缺文件或有冲突（内容不完整，但实例可用）。 + Partial, + /// 致命失败，已整包回滚。 + Failed, +} + +impl ImportStatus { + /// 稳定字符串 id。 + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::Success => "success", + Self::Partial => "partial", + Self::Failed => "failed", + } + } + + /// 文案 key。 + #[must_use] + pub const fn message_key(self) -> &'static str { + match self { + Self::Success => keys::STATUS_SUCCESS, + Self::Partial => keys::STATUS_PARTIAL, + Self::Failed => keys::STATUS_FAILED, + } + } + + /// CLI 退出码：`0` / `3` / `1`（`2` 留给内部错误，`1` 与用法错误同码但 JSON 里可区分）。 + #[must_use] + pub const fn exit_code(self) -> i32 { + match self { + Self::Success => 0, + Self::Partial => 3, + Self::Failed => 1, + } + } +} + +/// 导入阶段（进度回调按这个分组）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize)] +#[serde(rename_all = "snake_case")] +pub enum ImportStage { + /// 读取清单（开包 + 安全四检 + 探测 + 读成模型）。 + Probe, + /// 解压 / 三方合并覆盖内容。 + Extract, + /// 补全并下载远端文件。 + Fetch, + /// 落地（临时目录 rename 或 journal 合并）。 + Commit, + /// 登记实例。 + Register, +} + +impl ImportStage { + /// 稳定字符串 id。 + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::Probe => "probe", + Self::Extract => "extract", + Self::Fetch => "fetch", + Self::Commit => "commit", + Self::Register => "register", + } + } + + /// 文案 key。 + #[must_use] + pub const fn message_key(self) -> &'static str { + match self { + Self::Probe => keys::STAGE_PROBE, + Self::Extract => keys::STAGE_EXTRACT, + Self::Fetch => keys::STAGE_FETCH, + Self::Commit => keys::STAGE_COMMIT, + Self::Register => keys::STAGE_REGISTER, + } + } +} + +/// 一条进度事件（同步回调，跨线程安全）。 +#[derive(Debug, Clone, Serialize)] +pub struct ImportProgress { + /// 当前阶段。 + pub stage: ImportStage, + /// 阶段内已完成条目数。 + pub done: usize, + /// 阶段内总条目数（未知时为 0）。 + pub total: usize, + /// 当前条目的实例内路径（阶段刚开始时为 `None`）。 + pub current: Option, +} + +/// 进度回调。 +pub type ImportProgressSink = std::sync::Arc; + +/// 一次导入的完整结果。 +#[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; + } +} diff --git a/crates/core/src/addon/import/report/items.rs b/crates/core/src/addon/import/report/items.rs new file mode 100644 index 0000000..9434a93 --- /dev/null +++ b/crates/core/src/addon/import/report/items.rs @@ -0,0 +1,265 @@ +//! 报告里的**条目类型**：一条文件、一条冲突、一条缺失、一个 component、一个加载器目标。 + +use serde::Serialize; + +use super::keys; +use crate::addon::loader::LoaderKind; +use crate::addon::pack::PackSide; + +/// 一条文件来自哪里。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)] +#[serde(rename_all = "snake_case")] +pub enum FileSource { + /// 包内 `overrides/`（或 CF 清单点名的那个目录 / MultiMC 的 `.minecraft/`）。 + Overrides, + /// 包内 `client-overrides/`。 + ClientOverrides, + /// CurseForge `files[]` 条目（靠 projectID/fileID 补全）。 + CurseForge, + /// Modrinth `files[]` 条目（清单自带 path + downloads）。 + Modrinth, +} + +impl FileSource { + /// 从覆盖目录的侧别取来源。 + #[must_use] + pub const fn from_side(side: PackSide) -> Self { + match side { + PackSide::Both => Self::Overrides, + PackSide::Client => Self::ClientOverrides, + // 服务端覆盖在客户端导入里不会落地（见 `plan` 的侧别优先级）。 + PackSide::Server => Self::Overrides, + } + } +} + +/// 一个文件本次被怎么处理。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)] +#[serde(rename_all = "snake_case")] +pub enum FileAction { + /// 新写入（磁盘上原本没有）。 + Installed, + /// 覆盖写入（用户没改过，整合包升级）。 + Replaced, + /// 磁盘内容与包内一致，没动。 + SkippedIdentical, + /// 用户改过 / 删过，按策略保留了用户那一侧。 + KeptUser, +} + +impl FileAction { + /// 是否真的写了盘。 + #[must_use] + pub const fn wrote(self) -> bool { + matches!(self, Self::Installed | Self::Replaced) + } +} + +/// 冲突的成因。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)] +#[serde(rename_all = "snake_case")] +pub enum ConflictReason { + /// 基线里记过这个文件，磁盘内容与基线不同 ⇒ 用户改过。 + UserModified, + /// 基线里记过这个文件，磁盘上却没了 ⇒ 用户删过。 + UserDeleted, + /// 没有基线可判，磁盘上本来就有同名文件。 + PreExisting, +} + +impl ConflictReason { + /// 文案 key。 + #[must_use] + pub const fn message_key(self) -> &'static str { + match self { + Self::UserModified => keys::CONFLICT_USER_MODIFIED, + Self::UserDeleted => keys::CONFLICT_USER_DELETED, + Self::PreExisting => keys::CONFLICT_PRE_EXISTING, + } + } +} + +/// 冲突实际采用的处置（由 [`super::super::ConflictPolicy`] 决定）。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)] +#[serde(rename_all = "snake_case")] +pub enum ConflictChoice { + /// 保留用户侧（不写盘）。 + KeepUser, + /// 用包内内容覆盖（用户选了"覆盖"）。 + Overwrite, +} + +/// 一条冲突（"无法判定时给可选择的冲突清单"就是这张表）。 +#[derive(Debug, Clone, Serialize)] +pub struct ConflictFile { + /// 实例内相对路径。 + pub path: String, + /// 成因。 + pub reason: ConflictReason, + /// 本次实际采用的一侧。 + pub choice: ConflictChoice, + /// 文案 key（= `reason.message_key()`）。 + pub message_key: &'static str, + /// 包内声明的 SHA-1。 + pub pack_sha1: String, + /// 包内声明的字节数。 + pub pack_size: u64, + /// 上次导入写下的 SHA-1（没有基线时 `None`）。 + pub base_sha1: Option, + /// 磁盘现状的 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..e373a37 --- /dev/null +++ b/crates/core/src/addon/import/report/keys.rs @@ -0,0 +1,105 @@ +//! 文案 key 常量表（**稳定字符串**，M109/M113 的页面按这些字符串查本地化文案）。 +//! +//! core 不出现面向用户的成品文案（诊断信息除外）；三态/阶段/缺失/冲突/注记各自带一个 key， +//! 逐条原因也在报告条目里（`message_key` 字段）。 +//! +//! `ALL` 是"没有死常量"的守门用表：`addon/tests/import_report.rs` 会核对 +//! ①常量定义集合 == `ALL`（不多不少）；②每个常量除了定义与 `ALL` 里的列举之外，至少还有 +//! 一处真实引用。任何一条不满足就失败——避免这张表腐烂成"看着齐全、其实没人用"。 + +/// 阶段：读取清单。 +pub const STAGE_PROBE: &str = "pack.import.stage.probe"; +/// 阶段：解压覆盖内容。 +pub const STAGE_EXTRACT: &str = "pack.import.stage.extract"; +/// 阶段：补全缺失文件。 +pub const STAGE_FETCH: &str = "pack.import.stage.fetch"; +/// 阶段：落地（rename / journal）。 +pub const STAGE_COMMIT: &str = "pack.import.stage.commit"; +/// 阶段：登记实例。 +pub const STAGE_REGISTER: &str = "pack.import.stage.register"; + +/// 状态：成功。 +pub const STATUS_SUCCESS: &str = "pack.import.status.success"; +/// 状态：部分成功。 +pub const STATUS_PARTIAL: &str = "pack.import.status.partial"; +/// 状态：失败（是否回滚干净看 `ImportReport::rolled_back`）。 +pub const STATUS_FAILED: &str = "pack.import.status.failed"; + +/// 注记：`server-overrides/` 客户端不解压。 +pub const NOTE_SERVER_OVERRIDES_SKIPPED: &str = "pack.import.note.server_overrides_skipped"; +/// 注记：`dependencies` 里不认识的键（`parchment` 之类）。 +pub const NOTE_UNKNOWN_DEPENDENCY: &str = "pack.import.note.unknown_dependency"; +/// 注记：`env.client=unsupported` 的条目被跳过。 +pub const NOTE_ENV_UNSUPPORTED: &str = "pack.import.note.env_unsupported"; +/// 注记：路径以 `.disabled` 结尾（禁用态，按原后缀落地）。 +pub const NOTE_DISABLED_SUFFIX: &str = "pack.import.note.disabled_suffix"; +/// 注记：路径以 `.old` 结尾（只识别与保留，不加语义）。 +pub const NOTE_OLD_SUFFIX: &str = "pack.import.note.old_suffix"; +/// 注记：`env.client=optional`（"可选"不等于"禁用"，照装）。 +pub const NOTE_OPTIONAL_FILE: &str = "pack.import.note.optional_file"; +/// 注记：清单里有多个加载器，只按 primary/第一条组计划。 +pub const NOTE_LOADER_MULTIPLE: &str = "pack.import.note.loader_multiple"; +/// 注记：实例已登记。 +pub const NOTE_REGISTERED: &str = "pack.import.note.registered"; +/// 注记：从 `instance.cfg` 取到了内存设置。 +pub const NOTE_INSTANCE_CFG_MEMORY: &str = "pack.import.note.instance_cfg_memory"; +/// 注记：基线文件读不出来（本次按"没有基线"处理）。 +pub const NOTE_BASELINE_UNREADABLE: &str = "pack.import.note.baseline_unreadable"; +/// 注记：基线属于**另一个整合包**（本次按"没有基线"处理）。 +pub const NOTE_BASELINE_PACK_MISMATCH: &str = "pack.import.note.baseline_pack_mismatch"; +/// 注记：提交前清掉了下载引擎的中间产物（`.ullpart-*` / `.ullmeta.json`）。 +pub const NOTE_ENGINE_ARTIFACTS_DROPPED: &str = "pack.import.note.engine_artifacts_dropped"; +/// 注记：回滚**未完整完成**（逐项列失败，`rolled_back` 为 false）。 +pub const NOTE_ROLLBACK_INCOMPLETE: &str = "pack.import.note.rollback_incomplete"; + +/// 缺失：调用方没给 fetcher（离线导入）。 +pub const MISSING_OFFLINE: &str = "pack.import.missing.offline"; +/// 缺失：条目本身补不出下载地址（CF `files[]` 缺 API 客户端 / `downloads` 为空）。 +pub const MISSING_NO_SOURCE: &str = "pack.import.missing.no_source"; +/// 缺失：下载/补全尝试过但失败（404 / 网络）。 +pub const MISSING_FETCH_FAILED: &str = "pack.import.missing.fetch_failed"; + +/// 冲突：用户改过这个文件。 +pub const CONFLICT_USER_MODIFIED: &str = "pack.import.conflict.user_modified"; +/// 冲突：用户删过这个文件。 +pub const CONFLICT_USER_DELETED: &str = "pack.import.conflict.user_deleted"; +/// 冲突：磁盘上本来就有同名内容（没有基线可判）。 +pub const CONFLICT_PRE_EXISTING: &str = "pack.import.conflict.pre_existing"; + +/// MultiMC 不支持的 component（逐项列出）。 +pub const REJECTED_COMPONENT: &str = "pack.import.rejected.component"; +/// 致命失败后已完成回滚（目标目录零残留）。 +pub const ROLLBACK_DONE: &str = "pack.import.rollback.done"; + +/// 全部 key（守门断言"没有死常量"用）。 +pub const ALL: &[&str] = &[ + STAGE_PROBE, + STAGE_EXTRACT, + STAGE_FETCH, + STAGE_COMMIT, + STAGE_REGISTER, + STATUS_SUCCESS, + STATUS_PARTIAL, + STATUS_FAILED, + NOTE_SERVER_OVERRIDES_SKIPPED, + NOTE_UNKNOWN_DEPENDENCY, + NOTE_ENV_UNSUPPORTED, + NOTE_DISABLED_SUFFIX, + NOTE_OLD_SUFFIX, + NOTE_OPTIONAL_FILE, + NOTE_LOADER_MULTIPLE, + NOTE_REGISTERED, + NOTE_INSTANCE_CFG_MEMORY, + NOTE_BASELINE_UNREADABLE, + NOTE_BASELINE_PACK_MISMATCH, + NOTE_ENGINE_ARTIFACTS_DROPPED, + NOTE_ROLLBACK_INCOMPLETE, + MISSING_OFFLINE, + MISSING_NO_SOURCE, + MISSING_FETCH_FAILED, + CONFLICT_USER_MODIFIED, + CONFLICT_USER_DELETED, + CONFLICT_PRE_EXISTING, + REJECTED_COMPONENT, + ROLLBACK_DONE, +]; diff --git a/crates/core/src/addon/import/stage.rs b/crates/core/src/addon/import/stage.rs new file mode 100644 index 0000000..23dee9d --- /dev/null +++ b/crates/core/src/addon/import/stage.rs @@ -0,0 +1,334 @@ +//! 落地事务：**临时目录 + rename**，合并态用 journal 回滚（回滚细节在 [`commit`]）。 +//! +//! # 两种起点，两条事务路径 +//! +//! | 起点 | 做法 | 失败后的样子 | +//! |------|------|--------------| +//! | 目标目录不存在 / 是空目录（全新导入） | 在**同卷兄弟目录**里把整个实例建好，最后一次 `rename` 到位 | 目标目录**从未出现**（rename 是原子的） | +//! | 目标目录已有内容（升级 / 重导） | 逐文件 `rename` 进目标；被替换的旧文件先改名成 `.ullbak-` 当备份 | journal 逆序回滚：新文件删掉、旧备份改回原名 | +//! +//! 为什么全新导入不逐文件搬：逐文件搬意味着"搬到一半失败"会留下一个**看起来存在**的 +//! 半个实例，而 `rename` 一个目录是单步原子操作——失败就只有"没有"这一种结果。 +//! +//! # 两道路径检查都在这层再走一遍 +//! +//! 第一道是 M110 的 [`normalize_file`]（七条写死规则：空名 / `\0` / `\` / `:` / 前导 `/` / +//! 任何 `..` 段 / 规整后为空），第二道是**落盘前的 `starts_with` 复核**（Modrinth 官方安装器 +//! 同款做法：`install_mrpack.rs:169-170` 按 `strip_prefix(instance_root)` 再判一次）。 +//! 模型可能来自外部构造，`zip` 侧的双检挡不住"调用方直接塞了个 `../x` 进来"。 + +pub mod commit; + +pub use commit::{CommitFailure, CommitGuard, RollbackOutcome}; + +use std::path::{Path, PathBuf}; +use std::sync::atomic::{AtomicU64, Ordering}; + +use super::super::pack::path::normalize_file; +use super::super::pack::PackError; +use super::error::ImportError; +use crate::platform::atomic::write_atomic; + +use crate::download::atomic::{META_SUFFIX, PART_SUFFIX}; +use commit::{rollback_merge, Applied}; + +/// 临时目录名里的进程内序号（同一进程并发导入不撞名）。 +static SEQ: AtomicU64 = AtomicU64::new(0); + +/// 目标目录的起点形态。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(super) enum Mode { + /// 全新：整目录 rename。 + Fresh, + /// 合并：逐文件 rename + journal。 + Merge, +} + +/// 一个进行中的落地事务。 +#[derive(Debug)] +pub struct Staging { + target: PathBuf, + temp: PathBuf, + mode: Mode, + /// 本次是否由我们创建了目标目录的父目录（回滚时顺手清掉，避免"空壳目录"残留）。 + created_parent: bool, +} + +impl Staging { + /// 开一个事务（临时目录立刻建好，目标目录此刻一个字节都没动）。 + /// + /// # Errors + /// + /// 目标路径是文件、父目录建不出来、临时目录建不出来时返回 `pack_io`。 + pub fn begin(target: &Path) -> Result { + 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`** 的守卫（析构即回滚）。 + /// + /// # Errors + /// + /// `rename` 失败、合并态逐文件搬动失败。**回滚已经在这条路径上做过**，其结果连同错误 + /// 一起返回（[`CommitFailure::rollback`]）：调用方必须把它写进报告，不许假设"失败 = 已回滚干净"。 + pub fn commit(self) -> Result { + match self.mode { + Mode::Fresh => match std::fs::rename(&self.temp, &self.target) { + Ok(()) => Ok(CommitGuard::fresh(self.target.clone(), self.temp.clone())), + Err(error) => { + self.abort_inner(); + Err(CommitFailure::io( + format!( + "把 {} 改名成 {} 失败：{error}", + self.temp.display(), + self.target.display() + ), + RollbackOutcome::default(), + )) + } + }, + Mode::Merge => { + let mut applied: Vec = Vec::new(); + match self.apply_merge(&mut applied) { + Ok(()) => Ok(CommitGuard::merge( + self.target.clone(), + self.temp.clone(), + applied, + )), + Err(error) => { + let rollback = rollback_merge(&mut applied); + self.abort_inner(); + Err(CommitFailure::new(error, rollback)) + } + } + } + } + } + + /// 删掉暂存目录里的**下载引擎中间产物**（续传 part 与 meta），返回删掉的个数。 + /// + /// 为什么必须在提交前删：引擎在下载失败时**故意**保留 `.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) + } + + /// 合并态：把临时目录里的文件逐个搬进目标目录（每个都带备份）。 + fn apply_merge(&self, applied: &mut Vec) -> Result<(), ImportError> { + let mut staged: Vec = Vec::new(); + collect_files(&self.temp, &mut staged)?; + staged.sort(); + for source in staged { + let relative = source + .strip_prefix(&self.temp) + .map_err(|_| io_error(format!("暂存路径不在临时目录里：{}", source.display())))?; + let relative_text = relative.to_string_lossy().replace('\\', "/"); + // 搬动前再规整一次（第三道，防"临时目录里被塞了奇怪的名字"）。 + let normalized = normalize_file(&relative_text)?; + let dest = self.target.join(&normalized); + if !dest.starts_with(&self.target) { + return Err(PackError::traversal(format!( + "落地路径越出实例目录：{relative_text:?}" + )) + .into()); + } + if let Some(parent) = dest.parent() { + std::fs::create_dir_all(parent) + .map_err(|error| io_error(format!("建 {} 失败：{error}", parent.display())))?; + } + let backup = if dest.exists() { + let backup = commit::backup_path(&dest); + std::fs::rename(&dest, &backup).map_err(|error| { + io_error(format!( + "备份 {} → {} 失败：{error}", + dest.display(), + backup.display() + )) + })?; + Some(backup) + } else { + None + }; + applied.push(Applied { + dest: dest.clone(), + backup, + moved: false, + }); + std::fs::rename(&source, &dest).map_err(|error| { + io_error(format!( + "把 {} 搬到 {} 失败：{error}", + source.display(), + dest.display() + )) + })?; + if let Some(last) = applied.last_mut() { + last.moved = true; + } + } + Ok(()) + } +} + +/// 引擎中间产物的文件名判据（`.ullpart` 在中段、`.ullmeta.json` 在结尾）。 +#[must_use] +pub fn is_engine_artifact(path: &Path) -> bool { + let Some(name) = path.file_name().and_then(|name| name.to_str()) else { + return false; + }; + name.ends_with(META_SUFFIX) || name.contains(PART_SUFFIX) +} + +/// 递归收集目录下的全部文件（绝对路径）。 +fn collect_files(dir: &Path, out: &mut Vec) -> 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..25a1e38 --- /dev/null +++ b/crates/core/src/addon/import/stage/commit.rs @@ -0,0 +1,290 @@ +//! 提交守卫、回滚与**回滚本身失败的记账**：`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) +} + +/// 一次**失败的回滚**（提交阶段失败时连同错误一起交回调用方）。 +/// +/// `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..ec28c57 --- /dev/null +++ b/crates/core/src/addon/loader/fabric.rs @@ -0,0 +1,247 @@ +//! Fabric 系（Fabric / Quilt）：官方 meta → loader 版本 JSON。 +//! +//! 依据 `DevDocs/analyse/05-modloader-modpack.md` §1.4：这两个加载器**没有 installer**， +//! `meta.fabricmc.net` / `meta.quiltmc.org` 直接给 launcher 可用的 profile JSON， +//! 所以安装 = "把 profile 收成我们的版本 JSON + 补库"，没有任何子进程。 +//! +//! 本文件是**纯函数**（不进网络）：URL 拼装与 JSON 归一化分开写，测试直接喂离线夹具。 +//! +//! # 归一化做了三件容易被上游坑的事 +//! +//! 1. **`jar` 钉成原版 id**：profile 通常不写 `jar`，而 `game::inherit::resolve` 在缺 `jar` +//! 时会把 `jar` 兜底成**自身 id**——那会让启动去找 `versions//.jar` +//! （不存在）。这里显式写 `jar = <原版 id>`，让继承链正确地回到原版 jar。 +//! 2. **`mainClass` 断言**：缺主类就不是一份能启动的清单，宁可在安装期报 metadata， +//! 也不要装出一个起不来的实例（HMCL 同款防御，analyse/05 §1.4）。 +//! 3. **扁平 `sha1`/`size` 提升成 `downloads.artifact`**：Fabric profile 的库把摘要写在 +//! 库对象顶层，M27 的库展开只认 `downloads.artifact`。不提上来的后果是"没有校验值 → +//! 存在即信"，重装时无法识别被截断的库文件。 + +use std::collections::BTreeMap; + +use serde::{Deserialize, Serialize}; + +use super::plan::{LoaderRelease, LoaderSupport}; +use super::{LoaderError, LoaderKind}; +use crate::game::library::{Library, LibraryDownloads}; +use crate::game::manifest::{DownloadInfo, VersionJson}; + +/// Fabric 官方 meta 根（BMCLAPI 有对应镜像规则 `bmclapi-fabric-meta`）。 +pub const FABRIC_META: &str = "https://meta.fabricmc.net/v2"; +/// Quilt 官方 meta 根（同上，`bmclapi-quilt-meta`）。 +pub const QUILT_META: &str = "https://meta.quiltmc.org/v3"; + +/// meta 根地址（按加载器）。 +#[must_use] +pub fn meta_base(kind: LoaderKind) -> &'static str { + match kind { + LoaderKind::Quilt => QUILT_META, + _ => FABRIC_META, + } +} + +/// 该原版版本可用的加载器版本列表地址。 +#[must_use] +pub fn loader_list_url(kind: LoaderKind, mc_version: &str) -> String { + format!("{}/versions/loader/{mc_version}", meta_base(kind)) +} + +/// 指定加载器版本的 launcher profile 地址（官方直出可用的版本 JSON）。 +#[must_use] +pub fn profile_url(kind: LoaderKind, mc_version: &str, loader_version: &str) -> String { + format!( + "{}/versions/loader/{mc_version}/{loader_version}/profile/json", + meta_base(kind) + ) +} + +/// 列表里的一个加载器版本。 +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct LoaderEntry { + /// 版本号（`0.15.11`）。 + #[serde(default)] + pub version: String, + /// 是否稳定版（Quilt 的列表不带这个键，缺省按稳定处理）。 + #[serde(default = "default_true")] + pub stable: bool, + /// Maven 坐标（`net.fabricmc:fabric-loader:0.15.11`）。 + #[serde(default)] + pub maven: String, +} + +const fn default_true() -> bool { + true +} + +/// 列表响应的一行（`[{ "loader": {…}, "intermediary": {…}, … }]`）。 +#[derive(Debug, Deserialize)] +struct ListRow { + #[serde(default)] + loader: Option, +} + +/// 解析版本列表（最新的排在前，与官方顺序一致——**不重排**）。 +/// +/// # 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(), + loader_version: loader_version.to_string(), + version_id, + version_json, + support: LoaderSupport::JsonRoute, + installer: None, + install_profile: None, + warnings, + }) +} + +/// 把库对象顶层的 `sha1`/`size` 提升成 `downloads.artifact`（Fabric profile 的写法）。 +fn lift_flat_digest(library: &mut Library) { + if library.downloads.is_some() { + return; + } + let Some(base) = library + .url + .as_deref() + .filter(|url| !url.is_empty()) + .map(str::to_string) + else { + return; + }; + let Ok(relative) = library.relative_path() else { + return; + }; + let sha1 = library + .extra + .get("sha1") + .and_then(serde_json::Value::as_str) + .map(str::to_string); + let size = library + .extra + .get("size") + .and_then(serde_json::Value::as_u64); + let path = relative.to_string_lossy().replace('\\', "/"); + let url = if base.ends_with('/') { + format!("{base}{path}") + } else { + format!("{base}/{path}") + }; + library.downloads = Some(LibraryDownloads { + artifact: Some(DownloadInfo { + id: None, + sha1, + size, + url: Some(url), + path: Some(path), + }), + classifiers: BTreeMap::new(), + }); +} + +/// loader 本体库必须在列表里：缺了就补一条（并用告警说明），别装出个"没有 loader"的实例。 +fn ensure_loader_library( + kind: LoaderKind, + loader_version: &str, + libraries: &mut Vec, + warnings: &mut Vec, +) { + let (group, artifact) = match kind { + LoaderKind::Quilt => ("org.quiltmc", "quilt-loader"), + _ => ("net.fabricmc", "fabric-loader"), + }; + let present = libraries.iter().any(|library| { + library + .coordinate() + .is_ok_and(|coordinate| coordinate.group == group && coordinate.artifact == artifact) + }); + if present { + return; + } + let maven_base = match kind { + LoaderKind::Quilt => "https://maven.quiltmc.org/repository/release/", + _ => "https://maven.fabricmc.net/", + }; + libraries.push(Library { + name: format!("{group}:{artifact}:{loader_version}"), + url: Some(maven_base.to_string()), + ..Library::default() + }); + warnings.push(format!( + "{} {loader_version} 的 profile 没带 {group}:{artifact}：已按 maven 坐标补一条（缺库会让游戏起不来）", + kind.label() + )); +} diff --git a/crates/core/src/addon/loader/forge.rs b/crates/core/src/addon/loader/forge.rs new file mode 100644 index 0000000..76c0ee5 --- /dev/null +++ b/crates/core/src/addon/loader/forge.rs @@ -0,0 +1,280 @@ +//! NeoForge / Forge：installer 内的 install profile → loader 版本 JSON。 +//! +//! 依据 `DevDocs/analyse/05-modloader-modpack.md` §1.2/§1.3：Forge 有两代 installer 协议， +//! NeoForge 是 fork（早期与 Forge 完全同构）。判据也在那儿：install profile 有没有 +//! `spec` / processors、有没有独立的 `version.json`。maven 坐标与版本表在 [`super::maven`]。 +//! +//! # 本模块的取舍（为什么只做一部分） +//! +//! 这两家都**不发**launcher 直接可用的 profile，只发 installer jar；能纯 json 化到什么程度 +//! 取决于 installer 声明的处理器： +//! +//! | install profile 形状 | 实测样例 | 本模块结论 | +//! |----------------------|----------|-----------| +//! | `spec: 1` + 有 client 侧 processors | Forge 1.20.1-47.2.0、NeoForge 21.1.80 | [`LoaderSupport::RequiresInstaller`] | +//! | `spec: 0` + 无 processors + 内嵌 `version.json` | Forge 1.12.2-14.23.5.2860 | [`LoaderSupport::JsonRoute`] | +//! | 只有内联 `versionInfo`（+ `install.filePath` 解包） | 1.12.2 之前的老重建版 | 明确 unsupported | +//! +//! 第一类必须跑 `java -cp … installertools …` 才能产出 `client-slim/extra` 等打补丁产物 +//! （processor 的 `data` 变量表里有 `MC_SLIM`/`MC_EXTRA`/`PATCHED`），解析结果因此带上 +//! [`LoaderSupport::RequiresInstaller`] 标记 + install profile 本体，交给 +//! [`super::processors`]（M35 执行器）真跑；这里的**判定**仍只管「要不要跑 installer」。 +//! +//! 第二类的本体 jar 在 version.json 里 `url` 是空串，且**官方 maven 只发布 `-universal` +//! classifier**（无 classifier 路径官方 404，只有 BMCLAPI 的 302 别名兜底）—— +//! 补救见 [`fill_missing_urls`]，URL 带 classifier、磁盘落点保持官方 installer 的原样。 +//! +//! # 一条容易踩的坑：processor 的库不进启动 classpath +//! +//! install profile 自带的 `libraries` 是**processor 依赖**（installertools/srgutils…）， +//! 它们不属于游戏 classpath。把它们并进 loader 版本 JSON 会让启动多加载一堆无关 jar， +//! 因此这里只记数量进告警、绝不合并；真下载它们的是 [`super::processors`]。 + +use std::collections::BTreeMap; + +use serde::Deserialize; + +use super::maven; +use super::plan::{LoaderRelease, LoaderSupport}; +use super::{LoaderError, LoaderKind}; +use crate::game::library::Library; +use crate::game::manifest::VersionJson; + +pub use super::processors::spec::{Datum, Processor}; + +/// 老协议 installer 的 `install` 段（`filePath` 指向内嵌的 universal jar）。 +#[derive(Debug, Clone, Default, Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct LegacyInstall { + /// 内嵌 jar 在 installer 里的相对路径。 + #[serde(default)] + pub file_path: Option, +} + +/// 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(), + 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/maven.rs b/crates/core/src/addon/loader/maven.rs new file mode 100644 index 0000000..898e2f4 --- /dev/null +++ b/crates/core/src/addon/loader/maven.rs @@ -0,0 +1,173 @@ +//! Maven 坐标与版本表（Forge / NeoForge）：版本列表地址、版本选择、installer 地址。 +//! +//! 与 [`super::forge`] 的分工：这里只管"maven 上有什么版本、jar 在哪"， +//! 那边只管"installer 里的 profile 怎么变成版本 JSON"。 +//! +//! 镜像：两家 maven 都在 D7 镜像表里有 BMCLAPI 规则（`bmclapi-neoforge` / +//! `bmclapi-forge-maven-net`），所以这里一律**写官方地址**，重写交给 `core::download` +//! 的镜像展开（与 M27 的"不拼镜像 URL"纪律一致）。 + +use super::LoaderKind; + +/// NeoForge maven 根（规则 `bmclapi-neoforge` 把 `/releases` 重写到 `/maven`）。 +pub const NEOFORGE_MAVEN: &str = "https://maven.neoforged.net/releases"; +/// Forge maven 根（规则 `bmclapi-forge-maven-net`）。 +pub const FORGE_MAVEN: &str = "https://maven.minecraftforge.net"; +/// NeoForge 唯一走 Forge 布局的原版版本（1.20.1 是"NeoForge 还叫 forge 的时候"）。 +pub const NEOFORGE_FORGE_LAYOUT_MC: &str = "1.20.1"; + +/// maven 根地址。 +#[must_use] +pub fn base(kind: LoaderKind) -> &'static str { + match kind { + LoaderKind::NeoForge => NEOFORGE_MAVEN, + _ => FORGE_MAVEN, + } +} + +/// 该原版版本对应的 `maven-metadata.xml` 地址。 +#[must_use] +pub fn metadata_url(kind: LoaderKind, mc_version: &str) -> String { + let (root, path) = match kind { + LoaderKind::NeoForge if mc_version == NEOFORGE_FORGE_LAYOUT_MC => { + (NEOFORGE_MAVEN, "net/neoforged/forge") + } + LoaderKind::NeoForge => (NEOFORGE_MAVEN, "net/neoforged/neoforge"), + _ => (FORGE_MAVEN, "net/minecraftforge/forge"), + }; + format!("{root}/{path}/maven-metadata.xml") +} + +/// installer jar 地址。 +#[must_use] +pub fn installer_url(kind: LoaderKind, mc_version: &str, maven_version: &str) -> String { + let (root, path, file) = match kind { + LoaderKind::NeoForge if mc_version == NEOFORGE_FORGE_LAYOUT_MC => ( + NEOFORGE_MAVEN, + "net/neoforged/forge", + format!("forge-{maven_version}-installer.jar"), + ), + LoaderKind::NeoForge => ( + NEOFORGE_MAVEN, + "net/neoforged/neoforge", + format!("neoforge-{maven_version}-installer.jar"), + ), + _ => ( + FORGE_MAVEN, + "net/minecraftforge/forge", + format!("forge-{maven_version}-installer.jar"), + ), + }; + format!("{root}/{path}/{maven_version}/{file}") +} + +/// 扫 maven-metadata.xml 里的 `` 值。 +/// +/// 故意不引 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 版本是否属于该原版版本。 +#[must_use] +pub fn matches_mc(kind: LoaderKind, mc_version: &str, version: &str) -> bool { + match kind { + LoaderKind::NeoForge if mc_version == NEOFORGE_FORGE_LAYOUT_MC => { + version.starts_with(&format!("{mc_version}-")) + } + LoaderKind::NeoForge => neoforge_mc_version(version).as_deref() == Some(mc_version), + _ => version.starts_with(&format!("{mc_version}-")), + } +} + +/// 从 maven 版本表里挑出属于该原版版本的加载器版本（**升序**，末尾最好）。 +#[must_use] +pub fn select_versions(kind: LoaderKind, mc_version: &str, versions: &[String]) -> Vec { + 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 版本，原样返回。 +#[must_use] +pub fn normalize_maven_version(kind: LoaderKind, mc_version: &str, raw: &str) -> String { + let raw = raw.trim(); + let needs_prefix = match kind { + LoaderKind::NeoForge => mc_version == NEOFORGE_FORGE_LAYOUT_MC, + _ => true, + }; + if needs_prefix && !raw.starts_with(&format!("{mc_version}-")) { + format!("{mc_version}-{raw}") + } else { + raw.to_string() + } +} + +/// 用户视角的加载器版本号（Forge 去掉原版前缀，NeoForge 原样）。 +#[must_use] +pub fn display_loader_version(kind: LoaderKind, mc_version: &str, maven_version: &str) -> String { + match kind { + LoaderKind::NeoForge if mc_version != NEOFORGE_FORGE_LAYOUT_MC => maven_version.to_string(), + _ => maven_version + .strip_prefix(&format!("{mc_version}-")) + .unwrap_or(maven_version) + .to_string(), + } +} + +/// 版本号 → 可比较的数字键（非数字段按 0，保证不 panic）。 +fn numeric_key(version: &str) -> Vec { + 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..29d0367 --- /dev/null +++ b/crates/core/src/addon/loader/meta.rs @@ -0,0 +1,242 @@ +//! 加载器元数据的网络层：版本列表 + 官方 profile/installer → [`LoaderRelease`]。 +//! +//! 分工与 M27 的 [`crate::game::install::RemoteSource`] 一样：**只发请求、只解析**， +//! 不写游戏目录（installer jar 落 `.ULL/cache/meta/` 作离线复用），镜像/退避/health 全在 +//! `core::download` 的引擎里（我们一律递**官方地址**，重写由镜像表负责）。 +//! +//! 两族的取数路径完全不同： +//! +//! ```text +//! Fabric / Quilt : meta API → profile/json（官方直出可用版本 JSON） +//! NeoForge/Forge : maven-metadata.xml → installer jar → 读 install_profile.json + version.json +//! ``` + +use std::fs::File; +use std::path::{Path, PathBuf}; + +use zip::ZipArchive; + +use super::fabric; +use super::forge::{self, InstallProfile}; +use super::maven; +use super::plan::LoaderRelease; +use super::{LoaderError, LoaderKind}; +use crate::download::{DownloadEngine, DownloadRequest, ResourceKind}; +use crate::game::manifest::VersionJson; + +/// installer jar 的缓存文件名前缀（超长/含 `+` 的版本串会被规整成安全文件名）。 +const INSTALLER_TAG: &str = "installer"; + +/// 远端加载器元数据来源。 +pub struct LoaderSource<'a> { + engine: &'a DownloadEngine, + meta_cache: &'a Path, +} + +impl<'a> LoaderSource<'a> { + /// 绑定下载引擎与元数据缓存目录（`.ULL/cache/meta/`）。 + #[must_use] + pub fn new(engine: &'a DownloadEngine, meta_cache: &'a Path) -> Self { + Self { engine, meta_cache } + } + + /// 取该原版版本可用的加载器版本列表（**最新在前**）。 + /// + /// # Errors + /// + /// 网络失败、元数据解析失败、该原版版本没有加载器版本时返回 [`LoaderError`]。 + pub async fn loader_versions( + &self, + kind: LoaderKind, + mc_version: &str, + ) -> Result, LoaderError> { + if kind.is_fabric_family() { + let url = fabric::loader_list_url(kind, mc_version); + let body = self.fetch_text(&url).await?; + let entries = fabric::parse_loader_list(kind, &body)?; + return Ok(entries.into_iter().map(|entry| entry.version).collect()); + } + let url = maven::metadata_url(kind, mc_version); + let body = self.fetch_text(&url).await?; + let all = maven::parse_metadata_versions(&body); + // maven 表是升序的，统一成"最新在前"。 + let mut picked = maven::select_versions(kind, mc_version, &all); + picked.reverse(); + if picked.is_empty() { + return Err(LoaderError::not_found(format!( + "{} 在 {} 上没有可用版本（maven 表 {} 条，全部与该原版版本不匹配）", + kind.label(), + mc_version, + all.len() + ))); + } + Ok(picked) + } + + /// 解析一个加载器版本（`loader_version` 为 `None` 时取官方默认：Fabric 系取首个稳定版， + /// maven 系取该原版版本下最新的一版）。 + /// + /// # Errors + /// + /// 网络失败、版本不存在、installer 缺 profile、协议不受支持时返回 [`LoaderError`]。 + pub async fn resolve( + &self, + kind: LoaderKind, + mc_version: &str, + loader_version: Option<&str>, + ) -> Result { + let requested = loader_version + .map(str::trim) + .filter(|value| !value.is_empty()); + if kind.is_fabric_family() { + let version = match requested { + Some(version) => version.to_string(), + None => { + let url = fabric::loader_list_url(kind, mc_version); + let body = self.fetch_text(&url).await?; + let entries = fabric::parse_loader_list(kind, &body)?; + fabric::pick_default(&entries) + .map(|entry| entry.version.clone()) + .ok_or_else(|| { + LoaderError::not_found(format!("{} 没有可用的加载器版本", kind.label())) + })? + } + }; + let url = fabric::profile_url(kind, mc_version, &version); + let body = self.fetch_text(&url).await?; + return fabric::build_release(kind, mc_version, &version, &body); + } + + let maven_version = match requested { + Some(raw) => maven::normalize_maven_version(kind, mc_version, raw), + None => self + .loader_versions(kind, mc_version) + .await? + .into_iter() + .next() + .ok_or_else(|| { + LoaderError::not_found(format!("{} 没有可用的加载器版本", kind.label())) + })?, + }; + let url = maven::installer_url(kind, mc_version, &maven_version); + let path = self.installer_path(kind, &maven_version); + let jar = self.fetch_installer(&url, &path).await?; + let (profile, embedded) = read_installer(&jar)?; + let mut release = forge::build_release( + kind, + mc_version, + &maven_version, + &profile, + embedded.as_ref(), + )?; + // M35 执行器要的两样东西：installer 本体（跑 processor 与解包）与它声明的 profile。 + release.installer = Some(jar); + Ok(release) + } + + /// installer jar 的本地缓存路径（`+`/非法字符规整成 `_`）。 + fn installer_path(&self, kind: LoaderKind, maven_version: &str) -> PathBuf { + let safe: String = maven_version + .chars() + .map(|ch| { + if ch.is_ascii_alphanumeric() || matches!(ch, '.' | '-' | '_') { + ch + } else { + '_' + } + }) + .collect(); + self.meta_cache + .join(format!("{}-{safe}-{INSTALLER_TAG}.jar", kind.as_str())) + } + + /// 取 installer jar：本地缓存里有可读的 zip 就直接用（离线复用），否则下载。 + async fn fetch_installer(&self, url: &str, path: &Path) -> Result { + 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 { + let dest = self.meta_cache.join("loader-meta.bin"); + let bytes = self + .engine + .download_bytes(DownloadRequest::new( + ResourceKind::VersionManifest, + url, + dest, + )) + .await?; + String::from_utf8(bytes) + .map_err(|_| LoaderError::metadata(format!("元数据不是 UTF-8：{url}"))) + } +} + +/// 读 installer jar 里的 `install_profile.json` 与内嵌的版本 JSON。 +/// +/// 内嵌版本 JSON 的路径来自 profile 的 `json` 字段（通常 `/version.json`）； +/// 该条目不存在时返回 `None`，由 [`forge::build_release`] 判定为 unsupported。 +/// +/// # Errors +/// +/// 不是合法 zip、缺 `install_profile.json`、profile/版本 JSON 无法解析时返回 metadata 错误。 +pub fn read_installer(path: &Path) -> Result<(InstallProfile, Option), 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..d8eee17 --- /dev/null +++ b/crates/core/src/addon/loader/mod.rs @@ -0,0 +1,249 @@ +//! 加载器安装（Fabric / Quilt / NeoForge / Forge）：官方元数据 → loader 版本 JSON → 补库清单。 +//! +//! 设计输入：`DevDocs/PlanDoc/08-mod-and-recommend.md` §1（D10 加载器安装）、 +//! `DevDocs/analyse/05-modloader-modpack.md` §1（五加载器安装协议、`patch + priority` 主线）。 +//! +//! # 与 M27 安装层的关系（不复制粘贴，只叠一层） +//! +//! 加载器不是"另一个版本"，而是**叠在已装原版之上的一个 `inheritsFrom` 层**： +//! +//! ```text +//! versions/1.20.1/1.20.1.json 原版（M27 负责装） +//! versions/1.20.1-fabric-0.15.11/…json loader 层：inheritsFrom=1.20.1 + 主类 + loader 库 +//! ``` +//! +//! 因此本模块**只做两件事**：①把官方元数据翻译成一份 loader 版本 JSON； +//! ②把它的库列表交给 [`crate::game::install::libraries`] 展开成下载计划。 +//! 落盘、跳过判定、实例登记一律复用 M27（[`crate::game::install::execute`] / `register`）， +//! 不另起一套下载/写盘逻辑。 +//! +//! # 三条路线（按"能不能不跑 java 就装出来"分类，而不是按加载器名字） +//! +//! | 路线 | 加载器 | 做法 | +//! |------|--------|------| +//! | [`LoaderSupport::JsonRoute`] | Fabric / Quilt | 官方 meta 直接给 launcher 用的 profile JSON | +//! | [`LoaderSupport::JsonRoute`] | Forge spec-0（如 1.12.2 重建版） | installer 里的 `version.json` + 库清单，universal jar 走 maven 直取 | +//! | [`LoaderSupport::RequiresInstaller`] | Forge spec≥1 / NeoForge | installer 声明了 client 侧 processors（拆包/映射），**必须外调 java** | +//! +//! 第三类本期只出**明确 unsupported**：版本 JSON 与库清单仍照常生成（`--dry-run` 可看）， +//! 但真装会被拒——半成品实例比明确报错更糟（沿 M27 §7「如实告知」的纪律）。 +//! 老协议 installer（内联 `versionInfo` + universal jar 解包，≈1.12.2 之前的重建版）同样归 unsupported。 + +pub mod fabric; +pub mod forge; +pub mod maven; +pub mod meta; +pub mod plan; +pub mod processors; + +#[cfg(test)] +mod tests; + +pub use meta::LoaderSource; +pub use plan::{LoaderInstallPlan, LoaderPlanInput, LoaderRelease, LoaderSupport}; + +use std::fmt; + +use crate::download::{DownloadError, DownloadErrorKind}; + +/// 支持的加载器种类。 +/// +/// `vanilla` / `none` **不在这里**：那是"不装加载器"，由 CLI 走 M27 的原版路径。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)] +pub enum LoaderKind { + /// Fabric（`meta.fabricmc.net`，纯 meta，无 installer）。 + Fabric, + /// Quilt（`meta.quiltmc.org`，与 Fabric 同构）。 + Quilt, + /// NeoForge（`maven.neoforged.net`，installer 内嵌 install profile）。 + NeoForge, + /// Forge（`maven.minecraftforge.net`，两代 installer 协议）。 + Forge, +} + +impl LoaderKind { + /// 解析命令行里的加载器名（大小写不敏感；`neo-forge` 是 Modrinth 的另一种拼法）。 + #[must_use] + pub fn parse(raw: &str) -> Option { + match raw.trim().to_ascii_lowercase().as_str() { + "fabric" => Some(Self::Fabric), + "quilt" => Some(Self::Quilt), + "neoforge" | "neo-forge" => Some(Self::NeoForge), + "forge" => Some(Self::Forge), + _ => None, + } + } + + /// 稳定字符串 id（进版本 id、JSON 输出与日志，**不要改名**）。 + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::Fabric => "fabric", + Self::Quilt => "quilt", + Self::NeoForge => "neoforge", + Self::Forge => "forge", + } + } + + /// 人读名称。 + #[must_use] + pub const fn label(self) -> &'static str { + match self { + Self::Fabric => "Fabric", + Self::Quilt => "Quilt", + Self::NeoForge => "NeoForge", + Self::Forge => "Forge", + } + } + + /// 是否属于 Fabric 系（纯 meta、profile JSON 直接可用）。 + #[must_use] + pub const fn is_fabric_family(self) -> bool { + matches!(self, Self::Fabric | Self::Quilt) + } + + /// 全部加载器（CLI 的 `--loader` 枚举提示用）。 + #[must_use] + pub const fn all() -> &'static [Self] { + &[Self::Fabric, Self::Quilt, Self::NeoForge, Self::Forge] + } + + /// loader 版本 id 的词根：`--`（`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/plan.rs b/crates/core/src/addon/loader/plan.rs new file mode 100644 index 0000000..dc8aae8 --- /dev/null +++ b/crates/core/src/addon/loader/plan.rs @@ -0,0 +1,235 @@ +//! 加载器安装计划：一份 loader 版本 JSON + 需要补下载的库清单。 +//! +//! 计划层与网络层分开：网络在 [`super::meta`]，这里只做**纯计算**——把已经解析好的 +//! loader 版本 JSON 交给 [`crate::game::install::libraries`] 展开成待下载文件，再包成 +//! M27 的 [`InstallPlan`]（落盘/跳过判定/原子写版本 JSON 全部沿用同一套实现）。 +//! +//! 为什么不直接调 [`InstallPlan::build`]：那是"装一个完整原版版本"的入口（客户端 jar + +//! 资源索引 + 逐对象），而 loader 层**只有库**——jar 与资源都由 `inheritsFrom` 的原版提供。 +//! 直接组 [`InstallPlan`] 的字段既省掉一堆"没有 jar"的告警，又不复制任何路径规则。 + +use std::path::PathBuf; + +use serde_json::{json, Value}; + +use super::forge::InstallProfile; +use super::LoaderKind; +use crate::game::arguments::Environment; +use crate::game::install::libraries; +use crate::game::install::{InstallPlan, PlanFile}; +use crate::game::layout::GameLayout; +use crate::game::manifest::VersionJson; + +/// 加载器版本的可用路线（判据是"能不能不跑 java 就装出来"，不是加载器名字）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum LoaderSupport { + /// 纯元数据/纯下载路线：不跑任何外部进程。 + JsonRoute, + /// 官方 installer 声明了必须先跑的 processors（拆包/映射），走 M35 执行器外调 java。 + RequiresInstaller { + /// 人读原因（含该版本声明的 processors 数量与作用）。 + reason: String, + }, +} + +impl LoaderSupport { + /// 稳定字符串 id（JSON 输出用）。 + #[must_use] + pub const fn as_str(&self) -> &'static str { + match self { + Self::JsonRoute => "json_route", + Self::RequiresInstaller { .. } => "requires_installer", + } + } + + /// 是否可真正安装（两条路线都走到了：processors 走 M35 执行器）。 + #[must_use] + pub const fn is_installable(&self) -> bool { + true + } + + /// 是否要外调 java 跑 installer processors。 + #[must_use] + pub const fn requires_installer(&self) -> bool { + matches!(self, Self::RequiresInstaller { .. }) + } + + /// JSON 视图。 + #[must_use] + pub fn to_json(&self) -> Value { + match self { + Self::JsonRoute => json!({"mode": self.as_str(), "requires_installer": false}), + Self::RequiresInstaller { reason } => { + json!({"mode": self.as_str(), "requires_installer": true, "reason": reason}) + } + } + } +} + +/// 一次解析出来的加载器版本（网络层产物，计划层的输入）。 +#[derive(Debug, Clone)] +pub struct LoaderRelease { + /// 加载器种类。 + pub kind: LoaderKind, + /// 目标原版版本（`inheritsFrom` 的父版本 id）。 + pub mc_version: String, + /// 加载器自身版本号（`0.15.11` / `47.2.0` / `21.1.80`）。 + pub loader_version: String, + /// 生成的 loader 版本 id（`1.20.1-fabric-0.15.11`，即 `versions//` 的目录名）。 + pub version_id: String, + /// loader 版本 JSON（`inheritsFrom` 指向原版）。 + pub version_json: VersionJson, + /// 可走哪条路线。 + pub support: LoaderSupport, + /// installer jar 的磁盘路径（M35 执行器的输入；Fabric 系为 `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() + } + + /// 是否要外调 java 跑 installer processors。 + #[must_use] + pub const fn requires_installer(&self) -> bool { + self.support.requires_installer() + } + + /// 需要 installer 时的原因（`JsonRoute` 返回 `None`）。 + #[must_use] + pub fn installer_reason(&self) -> Option<&str> { + match &self.support { + LoaderSupport::JsonRoute => None, + LoaderSupport::RequiresInstaller { reason } => Some(reason), + } + } + + /// JSON 视图（`--dry-run` 与诊断共用）。 + #[must_use] + pub fn to_json(&self) -> Value { + json!({ + "kind": self.kind.as_str(), + "label": self.kind.label(), + "mc_version": self.mc_version, + "loader_version": self.loader_version, + "version_id": self.version_id, + "inherits_from": self.version_json.inherits_from, + "jar": self.version_json.jar, + "main_class": self.version_json.main_class, + "libraries": self.version_json.libraries.as_ref().map_or(0, Vec::len), + "support": self.support.to_json(), + "warnings": self.warnings, + }) + } +} + +/// [`LoaderInstallPlan::build`] 的输入。 +pub struct LoaderPlanInput<'a> { + /// 游戏目录布局（`versions/` `libraries/` 的路径规则）。 + pub layout: &'a GameLayout, + /// 已解析的加载器版本。 + pub release: &'a LoaderRelease, + /// 规则求值环境（OS / 架构 / 特性开关）。 + pub environment: &'a Environment, + /// 原版的 `versions//.json` 是否已在盘上。 + pub vanilla_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「宁可给出可修复的骨架，也不静默假装成功」一致。 + #[must_use] + pub fn build(input: LoaderPlanInput<'_>) -> Self { + let release = input.release; + let (files, library_warnings) = libraries::plan( + input.layout, + &release.version_id, + release + .version_json + .libraries + .as_deref() + .unwrap_or_default(), + input.environment, + ); + + let mut warnings = release.warnings.clone(); + warnings.extend(library_warnings); + if let Some(reason) = release.installer_reason() { + warnings.push(format!("需要外调 java 跑 installer processors：{reason}")); + } + if !input.vanilla_installed { + warnings.push(format!( + "原版 {} 尚未安装：执行时会先装原版再叠加载器", + release.mc_version + )); + } + + let install = InstallPlan { + version_id: release.version_id.clone(), + // jar 来自原版层（生成的 loader JSON 已把 `jar` 钉成原版 id）。 + jar_id: release.mc_version.clone(), + game_root: input.layout.root().to_path_buf(), + version_json_path: input.layout.version_json(&release.version_id), + files, + version_json: release.version_json.clone(), + prefetched: Vec::new(), + warnings, + }; + + Self { + release: release.clone(), + install, + vanilla_install_needed: !input.vanilla_installed, + } + } + + /// 计划里的待下载文件。 + #[must_use] + pub fn files(&self) -> &[PlanFile] { + &self.install.files + } + + /// 告警（含"原版未装""本期不能真装"）。 + #[must_use] + pub fn warnings(&self) -> &[String] { + &self.install.warnings + } + + /// 汇总 JSON（`--dry-run` 的主载荷）。 + #[must_use] + pub fn summary_json(&self) -> Value { + let mut summary = self.install.summary_json(); + if let Some(object) = summary.as_object_mut() { + object.insert("loader".to_string(), self.release.to_json()); + object.insert( + "vanilla_install_needed".to_string(), + json!(self.vanilla_install_needed), + ); + } + summary + } +} diff --git a/crates/core/src/addon/loader/processors/download.rs b/crates/core/src/addon/loader/processors/download.rs new file mode 100644 index 0000000..a9e39ba --- /dev/null +++ b/crates/core/src/addon/loader/processors/download.rs @@ -0,0 +1,83 @@ +//! processor 依赖库的下载：把 [`ProcessorPlan::libraries`] 交给 M27 的下载引擎。 +//! +//! 为什么不直接复用 `game::install::execute`：那个入口在**全量就绪后写版本 JSON**， +//! 而 processors 的产物要先于版本清单落盘（版本 JSON 存在 = 这版真装完了）。 +//! 所以这里只借它的**逐文件跳过判定**（`current_bytes`：摘要 → 大小 → 存在即信） +//! 与结果类型，下载本身仍走同一个引擎——镜像、健康度、退避、续传一条不少。 + +use futures_util::stream::{self, StreamExt}; + +use crate::download::DownloadEngine; +use crate::game::install::execute::current_bytes; +use crate::game::install::{ + FileFailure, FileOutcome, FileStatus, InstallReport, PlanFile, ProgressSink, +}; + +/// 并发下载 processor 依赖库（`concurrency` 上限，引擎内部另有信号量）。 +/// +/// 失败**不**中断：与 M27 一致，逐文件结构化返回，由调用方决定是否继续。 +pub async fn download_libraries( + engine: &DownloadEngine, + files: &[PlanFile], + concurrency: usize, + sink: Option, +) -> 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, + 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..0c2029c --- /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::process::Command; +use std::sync::Arc; +use std::time::Instant; + +use serde_json::{json, Value}; + +use super::error::ProcessorError; +use super::jar::read_main_class; +use super::plan::{ProcessorPlan, ProcessorStep}; +use super::prepare::prepare; +use super::text::{host_redactor, non_empty, tail}; +use crate::download::verify; +use crate::download::HashAlgo; +use crate::game::java::{self, JavaRequirement, JavaRuntime}; +use crate::launch::redact::Redactor; + +/// 一步的结局。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum StepStatus { + /// 产物已就绪（SHA-1 命中），整步跳过。 + Skipped, + /// 真的起了一次 java。 + Executed, +} + +impl StepStatus { + /// 稳定字符串 id（`--json` 用）。 + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::Skipped => "skipped", + Self::Executed => "executed", + } + } +} + +/// 一步的执行结果。 +#[derive(Debug, Clone)] +pub struct StepOutcome { + /// 序号（从 1 起）。 + pub index: usize, + /// jar 的 maven 坐标。 + pub label: String, + /// 结局。 + pub status: StepStatus, + /// 产物个数。 + pub outputs: usize, + /// 耗时（毫秒；跳过时为 0）。 + pub elapsed_ms: u128, + /// stdout 尾巴（已脱敏，可能为空）。 + pub stdout_tail: Option, + /// 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 = Command::new(&runtime.binary) + .arg("-cp") + .arg(&classpath) + .arg(&main_class) + .args(&step.args) + .current_dir(&plan.scratch) + .output() + .map_err(|error| { + ProcessorError::io(format!( + "起 java 失败（{}）：{error}", + runtime.binary.display() + )) + .with_hint( + "确认 `ull java list` 里的路径可用，或用 `ull java install ` 装一个托管 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/maven.rs b/crates/core/src/addon/loader/tests/maven.rs new file mode 100644 index 0000000..2d30b12 --- /dev/null +++ b/crates/core/src/addon/loader/tests/maven.rs @@ -0,0 +1,134 @@ +//! maven 版本表：XML 扫描、NeoForge 版本反解、版本挑选、installer 地址。 + +use crate::addon::loader::maven::{ + display_loader_version, installer_url, matches_mc, metadata_url, neoforge_mc_version, + normalize_maven_version, parse_metadata_versions, select_versions, +}; +use crate::addon::loader::LoaderKind; + +/// 裁剪过的 maven-metadata.xml（真实结构，只留 `` 列表）。 +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") + .ends_with("net/neoforged/forge/maven-metadata.xml")); + assert!(metadata_url(LoaderKind::NeoForge, "1.21.1") + .ends_with("net/neoforged/neoforge/maven-metadata.xml")); + assert!(metadata_url(LoaderKind::Forge, "1.20.1") + .ends_with("net/minecraftforge/forge/maven-metadata.xml")); + + let versions = vec!["1.20.1-47.1.106".to_string(), "1.20.1-47.1.90".to_string()]; + let picked = select_versions(LoaderKind::NeoForge, "1.20.1", &versions); + assert_eq!(picked.len(), 2); + assert_eq!( + display_loader_version(LoaderKind::NeoForge, "1.20.1", "1.20.1-47.1.106"), + "47.1.106" + ); +} + +#[test] +fn versions_are_normalized_and_displayed() { + // Forge：用户给 "47.2.0"，maven 上是 "1.20.1-47.2.0"。 + assert_eq!( + normalize_maven_version(LoaderKind::Forge, "1.20.1", "47.2.0"), + "1.20.1-47.2.0" + ); + assert_eq!( + normalize_maven_version(LoaderKind::Forge, "1.20.1", "1.20.1-47.2.0"), + "1.20.1-47.2.0" + ); + assert_eq!( + display_loader_version(LoaderKind::Forge, "1.20.1", "1.20.1-47.2.0"), + "47.2.0" + ); + // NeoForge（非 1.20.1 布局）本身就是完整 maven 版本。 + assert_eq!( + normalize_maven_version(LoaderKind::NeoForge, "1.21.1", "21.1.80"), + "21.1.80" + ); + assert_eq!( + display_loader_version(LoaderKind::NeoForge, "1.21.1", "21.1.80"), + "21.1.80" + ); +} + +#[test] +fn installer_urls_point_at_official_maven() { + assert_eq!( + installer_url(LoaderKind::Forge, "1.20.1", "1.20.1-47.2.0"), + "https://maven.minecraftforge.net/net/minecraftforge/forge/1.20.1-47.2.0/forge-1.20.1-47.2.0-installer.jar" + ); + assert_eq!( + installer_url(LoaderKind::NeoForge, "1.21.1", "21.1.80"), + "https://maven.neoforged.net/releases/net/neoforged/neoforge/21.1.80/neoforge-21.1.80-installer.jar" + ); + // 1.20.1 的 NeoForge 走 forge 布局（文件名也是 forge-）。 + assert_eq!( + installer_url(LoaderKind::NeoForge, "1.20.1", "1.20.1-47.1.106"), + "https://maven.neoforged.net/releases/net/neoforged/forge/1.20.1-47.1.106/forge-1.20.1-47.1.106-installer.jar" + ); +} diff --git a/crates/core/src/addon/loader/tests/mod.rs b/crates/core/src/addon/loader/tests/mod.rs new file mode 100644 index 0000000..4d2f93f --- /dev/null +++ b/crates/core/src/addon/loader/tests/mod.rs @@ -0,0 +1,56 @@ +//! `addon::loader` 的单元测试：离线夹具对拍 + 镜像选择 + unsupported 判定。 +//! +//! 刻意**不打真实网络**：JSON 归一化、版本表挑选、镜像候选、计划形状全是纯计算。 +//! 夹具是官方响应的**裁剪版**（保留形状与关键字段，去掉几百行库与 base64 图标）。 + +mod fabric; +mod forge; +mod maven; +mod plan; + +/// 裁剪过的 Fabric `/profile/json`（1.20.1 + fabric-loader 0.15.11）。 +pub(crate) const FABRIC_PROFILE: &str = r#"{ + "id": "fabric-loader-0.15.11-1.20.1", + "inheritsFrom": "1.20.1", + "releaseTime": "2026-10-29T10:25:18+0000", + "time": "2026-10-29T10:25:18+0000", + "type": "release", + "mainClass": "net.fabricmc.loader.impl.launch.knot.KnotClient", + "arguments": {"game": [], "jvm": ["-DFabricMcEmu= net.minecraft.client.main.Main "]}, + "libraries": [ + {"name": "org.ow2.asm:asm:9.6", "url": "https://maven.fabricmc.net/", + "sha1": "aa205cf0a06dbd8e04ece91c0b37c3f5d567546a", "size": 123598}, + {"name": "net.fabricmc:sponge-mixin:0.13.3+mixin.0.8.5", "url": "https://maven.fabricmc.net/"}, + {"name": "net.fabricmc:intermediary:1.20.1", "url": "https://maven.fabricmc.net/"}, + {"name": "net.fabricmc:fabric-loader:0.15.11", "url": "https://maven.fabricmc.net/"} + ] +}"#; + +/// 裁剪过的 Quilt `/profile/json`（1.20.1 + quilt-loader 0.20.0-beta.9）。 +pub(crate) const QUILT_PROFILE: &str = r#"{ + "id": "quilt-loader-0.20.0-beta.9-1.20.1", + "inheritsFrom": "1.20.1", + "type": "release", + "mainClass": "org.quiltmc.loader.impl.launch.knot.KnotClient", + "arguments": {"game": []}, + "libraries": [ + {"name": "net.fabricmc:tiny-mappings-parser:0.3.0+build.17", "url": "https://maven.fabricmc.net/"}, + {"name": "org.quiltmc:quilt-json5:1.0.4+final", "url": "https://maven.quiltmc.org/repository/release/"}, + {"name": "org.quiltmc:quilt-loader:0.20.0-beta.9", "url": "https://maven.quiltmc.org/repository/release/"} + ] +}"#; + +/// 原版 1.20.1 的**已裁剪**版本 JSON（继承链解析的父层）。 +pub(crate) const VANILLA_1201: &str = r#"{ + "id": "1.20.1", + "type": "release", + "mainClass": "net.minecraft.client.main.Main", + "assets": "5", + "assetIndex": {"id": "5", "sha1": "0000", "size": 1, + "url": "https://piston-meta.mojang.com/v1/packages/5.json"}, + "downloads": {"client": {"sha1": "1111", "size": 2, + "url": "https://piston-data.mojang.com/v1/objects/1/client.jar"}}, + "libraries": [ + {"name": "com.mojang:brigadier:1.0.18", "url": "https://libraries.minecraft.net/"} + ] +}"#; diff --git a/crates/core/src/addon/loader/tests/plan.rs b/crates/core/src/addon/loader/tests/plan.rs new file mode 100644 index 0000000..fbe193e --- /dev/null +++ b/crates/core/src/addon/loader/tests/plan.rs @@ -0,0 +1,192 @@ +//! 计划形状 / 继承链两级解析 / 镜像选择。 + +use std::collections::BTreeMap; + +use super::{FABRIC_PROFILE, VANILLA_1201}; +use crate::addon::loader::fabric::{build_release, loader_list_url, profile_url}; +use crate::addon::loader::maven; +use crate::addon::loader::{ + LoaderInstallPlan, LoaderKind, LoaderPlanInput, LoaderRelease, LoaderSupport, +}; +use crate::download::mirrors::MirrorTable; +use crate::download::region::RegionProfile; +use crate::download::types::ResourceKind; +use crate::game::arguments::Environment; +use crate::game::install::FileRole; +use crate::game::{inherit, layout::GameLayout, VersionJson}; + +fn fabric_release() -> LoaderRelease { + build_release(LoaderKind::Fabric, "1.20.1", "0.15.11", FABRIC_PROFILE).expect("夹具应可归一化") +} + +fn environment() -> Environment { + Environment { + os: "windows".to_string(), + os_version: String::new(), + arch: "x86_64".to_string(), + ..Environment::host() + } +} + +#[test] +fn plan_contains_only_loader_libraries() { + let layout = GameLayout::new("/g/.minecraft"); + let release = fabric_release(); + let plan = LoaderInstallPlan::build(LoaderPlanInput { + layout: &layout, + release: &release, + environment: &environment(), + vanilla_installed: false, + }); + + assert_eq!(plan.install.version_id, "1.20.1-fabric-0.15.11"); + // jar 与资源归原版层，loader 计划里只有库。 + assert_eq!(plan.install.jar_id, "1.20.1"); + assert!(plan + .files() + .iter() + .all(|file| file.role == FileRole::Library)); + assert!( + plan.files() + .iter() + .any(|file| file.name.contains("fabric-loader")), + "缺 fabric-loader：{:?}", + plan.files().iter().map(|f| &f.name).collect::>() + ); + assert!(plan.install.version_json_path.ends_with( + std::path::Path::new("versions") + .join("1.20.1-fabric-0.15.11") + .join("1.20.1-fabric-0.15.11.json") + )); + // 只下 loader 那几个库，不该冒出资产/客户端 jar。 + assert!(plan.install.file_count() >= 4); + assert!(plan.install.client_jar().is_none()); +} + +#[test] +fn plan_marks_missing_vanilla_and_unsupported() { + let layout = GameLayout::new("/g/.minecraft"); + let release = fabric_release(); + let plan = LoaderInstallPlan::build(LoaderPlanInput { + layout: &layout, + release: &release, + environment: &environment(), + vanilla_installed: false, + }); + assert!(plan.vanilla_install_needed); + assert!(plan + .warnings() + .iter() + .any(|warning| warning.contains("原版 1.20.1 尚未安装"))); + + let installed = LoaderInstallPlan::build(LoaderPlanInput { + layout: &layout, + release: &release, + environment: &environment(), + vanilla_installed: true, + }); + assert!(!installed.vanilla_install_needed); + + // 把 support 改成"需要 installer"，计划里要出现"要外调 java"的告警（M35 起可真装）。 + let mut blocked = fabric_release(); + blocked.support = LoaderSupport::RequiresInstaller { + reason: "需要 processors".to_string(), + }; + let plan = LoaderInstallPlan::build(LoaderPlanInput { + layout: &layout, + release: &blocked, + environment: &environment(), + vanilla_installed: true, + }); + assert!(plan + .warnings() + .iter() + .any(|warning| warning.contains("需要外调 java 跑 installer processors"))); +} + +#[test] +fn summary_json_carries_loader_block() { + let layout = GameLayout::new("/g/.minecraft"); + let release = fabric_release(); + let plan = LoaderInstallPlan::build(LoaderPlanInput { + layout: &layout, + release: &release, + environment: &environment(), + vanilla_installed: true, + }); + let summary = plan.summary_json(); + assert_eq!(summary["loader"]["kind"], "fabric"); + assert_eq!(summary["loader"]["version_id"], "1.20.1-fabric-0.15.11"); + assert_eq!(summary["loader"]["support"]["mode"], "json_route"); + assert_eq!(summary["loader"]["inherits_from"], "1.20.1"); + assert_eq!(summary["vanilla_install_needed"], false); +} + +#[test] +fn loader_json_resolves_two_level_chain() { + // loader → 原版 两级继承：解析后必须是扁平的、jar 指原版、库两侧合并。 + let vanilla = VersionJson::from_json_str(VANILLA_1201).expect("原版夹具"); + let loader = fabric_release().version_json; + let mut table: BTreeMap = BTreeMap::new(); + table.insert("1.20.1".to_string(), vanilla); + table.insert("1.20.1-fabric-0.15.11".to_string(), loader.clone()); + + let resolved = inherit::resolve(&table, &loader).expect("两级链应可解析"); + assert!(resolved.is_resolved()); + assert_eq!(resolved.inherits_from, None); + assert_eq!(resolved.jar.as_deref(), Some("1.20.1")); + assert_eq!( + resolved.main_class.as_deref(), + Some("net.fabricmc.loader.impl.launch.knot.KnotClient") + ); + // 资源来自原版层。 + assert_eq!(resolved.assets.as_deref(), Some("5")); + assert!(resolved.client_jar().is_some()); + // 库两层的并集（父在前，子在后）。 + let libraries = resolved.libraries.expect("应有库"); + assert_eq!(libraries.len(), 5); + assert_eq!(libraries[0].name, "com.mojang:brigadier:1.0.18"); +} + +#[test] +fn loader_meta_and_maven_urls_hit_bmclapi_mirrors() { + let table = MirrorTable::builtin(); + let mirror_first = RegionProfile::mirror_first(0); + + let fabric_meta = loader_list_url(LoaderKind::Fabric, "1.20.1"); + let candidates = table.expand(&fabric_meta, ResourceKind::VersionManifest, &mirror_first); + let sources: Vec<&str> = candidates.iter().map(|c| c.source.as_str()).collect(); + assert_eq!( + sources.first(), + Some(&"bmclapi"), + "镜像优先时应先走 BMCLAPI" + ); + assert!(candidates.iter().any(|candidate| candidate + .url + .contains("/fabric-meta/v2/versions/loader/1.20.1"))); + + let quilt_profile = profile_url(LoaderKind::Quilt, "1.20.1", "0.20.0-beta.9"); + let candidates = table.expand(&quilt_profile, ResourceKind::VersionManifest, &mirror_first); + assert_eq!(candidates[0].source, "bmclapi"); + assert!(candidates[0].url.contains("/quilt-meta/")); + + let neoforge_installer = maven::installer_url(LoaderKind::NeoForge, "1.21.1", "21.1.80"); + let candidates = table.expand(&neoforge_installer, ResourceKind::Library, &mirror_first); + assert_eq!(candidates[0].source, "bmclapi"); + assert!(candidates[0] + .url + .starts_with("https://bmclapi2.bangbang93.com/maven/net/neoforged/neoforge/")); + + let forge_meta = maven::metadata_url(LoaderKind::Forge, "1.20.1"); + let candidates = table.expand(&forge_meta, ResourceKind::VersionManifest, &mirror_first); + assert_eq!(candidates[0].source, "bmclapi"); + assert!(candidates[0] + .url + .starts_with("https://bmclapi2.bangbang93.com/maven/net/minecraftforge/forge/")); + + // 直连模式：官方在前，镜像只兜底。 + let direct = RegionProfile::direct(0); + let candidates = table.expand(&fabric_meta, ResourceKind::VersionManifest, &direct); + assert_eq!(candidates[0].source, "official"); + assert_eq!(candidates[0].url, fabric_meta); +} diff --git a/crates/core/src/addon/mod.rs b/crates/core/src/addon/mod.rs new file mode 100644 index 0000000..8cd9ca0 --- /dev/null +++ b/crates/core/src/addon/mod.rs @@ -0,0 +1,48 @@ +//! Mod 与整合包：加载器安装（Fabric/Quilt/NeoForge/Forge）、整合包双格式导入导出、 +//! 本地 Mod 管理、CurseForge / Modrinth 客户端。 +//! +//! 设计定稿：`DevDocs/PlanDoc/08-mod-and-recommend.md`（决策 D10）。 +//! 安全要点：整合包路径穿越双检；AI 推荐走「结构化过滤在前 + LLM 排序在后 + 来源链接防幻觉」。 +//! +//! # 当前公共面 +//! +//! - [`loader`]（P2 · M32）：加载器安装——官方元数据 → 带 `inheritsFrom` 的 loader 版本 JSON +//! → 补库清单，落盘与实例登记复用 `core::game::install`（M27）。 +//! - [`pack`]（P2 · M110）：整合包的**格式无关模型**与**格式扩展点**——CF / Modrinth / MultiMC +//! 三种格式的探测与读取、CF / mrpack 的渲染与导出、zip 安全读取（穿越双检 / 符号链接 / +//! 条数体积上限）。 +//! - [`import`]（P2 · M111）：**导入管线**——三种格式 → 实例目录：跨段落地、overrides 三方 +//! 合并（保用户改动）、两阶段补全与失败分级、临时目录 + rename/journal 回滚、结构化报告。 +//! 导出（M112）另起模块。 +//! - [`export`]（P2 · M112）：**导出管线**——实例目录 → `.mrpack`（优先）/ CF `manifest.json`。 +//! 逐文件判定「能否被远程替代」（Modrinth SHA-1 + CF 指纹），判定不了的**内联进 `overrides/`** +//! 并逐条进报告；`.disabled` 用路径后缀；`game`/`dependencies` 从实例快照取。 +//! MultiMC/Prism **只导入不导出**（有意省略）。 +//! +//! 规划中：本地 mod 管理（D10 §3）、CF/Modrinth 客户端（§5）。 + +pub mod export; +pub mod import; +pub mod loader; +pub mod pack; + +pub use export::{ + export_instance, ExportFile, ExportReport, ExportRequest, FileClass, FileReason, RemoteCatalog, + RemoteHit, +}; +pub use import::{ + import_pack, ConflictFile, ConflictPolicy, ImportError, ImportErrorKind, ImportProgress, + ImportProgressSink, ImportReport, ImportRequest, ImportStage, ImportStatus, ImportedFile, + MissingFile, PackBaseline, PackFetcher, RejectedComponent, +}; +pub use loader::{ + LoaderError, LoaderErrorKind, LoaderInstallPlan, LoaderKind, LoaderPlanInput, LoaderRelease, + LoaderSource, LoaderSupport, +}; +pub use pack::{ + EnvSupport, PackArchive, PackError, PackErrorKind, PackFile, PackFormat, PackLimits, + PackLoader, PackManifest, PackOverrides, PackRegistry, PackResult, PackSide, +}; + +#[cfg(test)] +mod tests; diff --git a/crates/core/src/addon/pack.rs b/crates/core/src/addon/pack.rs new file mode 100644 index 0000000..a308012 --- /dev/null +++ b/crates/core/src/addon/pack.rs @@ -0,0 +1,71 @@ +//! 整合包的**格式无关模型**与**格式扩展点**（M110）。导入/导出管线（M111/M112）建在这上面。 +//! +//! 设计定稿：`DevDocs/PlanDoc/08-mod-and-recommend.md` §2（D10），格式细节来自 +//! `DevDocs/analyse/05-modloader-modpack-p2.md` §2.1–§2.3（HMCL 源码级拆解，A 级来源）。 +//! +//! # 本模块只做三件事 +//! +//! | 层 | 模块 | 职责 | +//! |----|------|------| +//! | 安全读取 | [`archive`] | 目录与 zip 统一成"规整过的条目表"：路径穿越双检、符号链接拒绝、条数/体积上限 | +//! | 格式 | [`format`] | [`format::PackFormat`] trait + [`format::PackRegistry`]：探测、读、渲染、写，**优先级写死** | +//! | 模型 | [`manifest`] | [`manifest::PackManifest`]：包名/版本/作者/游戏版本/加载器/文件条目/覆盖目录，未知字段原样保留 | +//! +//! 三个内置格式：[`curseforge`]（`manifest.json`，可读可写）、[`modrinth`]（`.mrpack`，可读可写）、 +//! [`multimc`]（`mmc-pack.json`，**只读**）。 +//! +//! # 导出面的边界（r1 之后写死） +//! +//! 默认 [`format::PackFormat::write`] **只保证同格式往返**：覆盖目录按模型原样搬， +//! 不做目录映射 / `side` 分派 / 加载器 id 规范化 / `extra` 分桶（都属于 M112）。 +//! 表达不了的时候由 [`format::PackFormat::check_overrides`] 直接报 `pack_unsupported`， +//! 而不是产出一个"成功但内容为空"的包。 +//! +//! # 刻意不做的事（分工边界） +//! +//! - **不发网络请求**：CF 的 `projectID/fileID` → 文件名/URL 补全属于 M111（要用 CF API 与 +//! MurmurHash2 指纹），本模块只把"缺什么"如实记成 `None`； +//! - **不落盘解压**：`archive` 只读，不写实例目录。overrides 的三方合并（base/theirs/ours） +//! 是 M111 的解压器职责，本模块提供它要的输入：每条覆盖文件的实例内相对路径 + SHA-1； +//! - **不碰 UI 类型**：core 零 UI 依赖（`core-no-ui` 门禁），这里连 `String` 之外的表现层 +//! 类型都不出现； +//! - **不猜格式**：探测顺序写死在 [`format::PackRegistry::builtin`]，同一份包命中多格式时 +//! 用固定的注册顺序选，并把其余命中记进 [`format::PackMatch::also_matched`]。 +//! +//! # 安全（每条都有恶意样本测试，见 `tests/safety.rs`） +//! +//! 路径穿越判据是**两条独立检查**：①本模块的 [`path::normalize_file`]（七条写死的规则： +//! 空名/`\0`/`\`/`:`/前导 `/`/任何 `..` 段/规整后为空）；②`zip` crate 的 +//! `enclosed_name()`（按 Windows 规则解析盘符、NTFS 数据流、保留设备名）。 +//! 为什么不能只留一条：`enclosed_name()` 允许"深度 0 的根目录"，也就是 `"/etc/passwd"` +//! 它会放行；反过来，本模块的规则不认 Windows 保留设备名。**两条都过才算安全**。 +//! +//! # 测试夹具的来源（不许把"看起来像"当真实） +//! +//! `tests/fixtures.rs` 里的 CF / mrpack / MultiMC 三个包**全部是手造的**：字段取自 +//! analyse/05 记录的 HMCL 解析器形状（A 级来源），内容是为了覆盖边界而编的（含一个刻意的 +//! 损坏文件：截断的 `config/broken.toml`、半截 `mods/half.jar`、零字节 `mods/broken.jar`）。 +//! **没有一个来自真实导出**——本任务环境离线，没有真实整合包样本可对照。真实样本的字段 +//! 偏移风险因此只能由 M111/M115（格式字段盘点）在拿到真包后回收，报告里已登记这条欠账。 + +pub mod archive; +pub mod curseforge; +pub mod error; +pub mod format; +pub mod manifest; +pub mod modrinth; +pub mod multimc; +pub mod path; + +#[cfg(test)] +mod tests; + +pub use archive::{PackArchive, PackEntryInfo, PackLimits, ReadBudget}; +pub use curseforge::CurseForge; +pub use error::{PackError, PackErrorKind, PackResult}; +pub use format::{PackFormat, PackMatch, PackPayload, PackRegistry}; +pub use manifest::{ + EnvSupport, OverrideFile, PackFile, PackLoader, PackManifest, PackOverrides, PackSide, +}; +pub use modrinth::Modrinth; +pub use multimc::MultiMc; diff --git a/crates/core/src/addon/pack/archive.rs b/crates/core/src/addon/pack/archive.rs new file mode 100644 index 0000000..3a231a3 --- /dev/null +++ b/crates/core/src/addon/pack/archive.rs @@ -0,0 +1,298 @@ +//! 打包输入的安全读取层：[`PackArchive`] 把"目录"与"zip"统一成"一组规整过的条目"。 +//! +//! # 为什么要有这一层 +//! +//! 格式探测器要能对**目录**（MultiMC 实例、已解开的整合包）与**zip**（`.zip` / `.mrpack`） +//! 一视同仁地问"有没有 `modrinth.index.json`"，而安全判据只有一份实现才不会漂。 +//! +//! # 安全判据（每条都有恶意样本测试，见 `tests/safety.rs`） +//! +//! | 威胁 | 做法 | +//! |------|------| +//! | 路径穿越（`../x`、`/etc/x`、`C:\x`、`a\..\b`、`file:ads`） | 条目名过 [`normalize_file`]（第一检，平台无关的七条规则），再过 `zip` crate 的 `enclosed_name()`（第二检，**按 Windows 规则**解析盘符/ADS/保留设备名）；任一拒绝即整包拒绝 | +//! | 符号链接条目 | `unix_mode()` 的 `S_IFLNK` 位命中即拒绝（Windows 上无合法用途；解压器会把目标当内容写出来） | +//! | 条目数爆炸 | [`PackLimits::max_entries`]，打开时按中央目录长度先判 | +//! | 解压体积爆炸（zip 炸弹） | [`PackLimits::max_uncompressed_bytes`] 累计 + [`PackLimits::max_entry_bytes`] 单条目；**读取时**再按实际读出的字节数封顶（中央目录里声明的大小可以撒谎） | +//! | 同名条目（`./a` 与 `a` 规整后撞车） | 规整后的名字重复即拒绝 | +//! +//! **两条检查各补一条对方没有的规则**（谁也不能省）： +//! +//! - 第一检管**平台无关**的形状：空名、`\0`、`\`、`:`、前导 `/`、任何 `..` 段。 +//! `enclosed_name()` 在这一点上更松——它允许"深度 0 处的根目录"，也就是 `"/etc/passwd"` +//! 会返回 `Some("/etc/passwd")`，绝对路径必须由我们先干掉。 +//! - 第二检管 **Win32 命名空间**：DOS 设备名（`CON` / `NUL` / `AUX` / `COM1..9` / `LPT1..9`）、 +//! 结尾的点或空格（`a.`、`a `）、`< > " | ? *` 与控制字符。这些第一检全放行，而它们会让 +//! 落盘时撞到设备、或与另一个名字等价。第二检只在 **Windows 宿主**上生效（`zip` 的 +//! `cfg(windows)` 分支），所以 `tests/safety.rs` 里对应的用例也是 `#[cfg(windows)]`。 +//! +//! 也就是说：`CON` / `NUL` 这类在 Windows 上**是拦的**（由第二检），非 Windows 宿主上不拦 +//! （那里它们只是普通文件名，拦了反而拒掉合法包）。 + +use std::cell::RefCell; +use std::collections::HashMap; +use std::fs::File; +use std::io::Read; +use std::path::{Path, PathBuf}; + +use serde_json::Value; +use zip::ZipArchive; + +use super::error::{PackError, PackResult}; +use super::manifest::OverrideFile; +use super::path::normalize_dir; +use crate::download::types::HashAlgo; +use crate::download::verify::{self, Hasher}; + +pub mod entry; +pub mod limits; +mod open; + +pub use entry::PackEntryInfo; +pub use limits::{ + PackLimits, ReadBudget, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_ENTRY_BYTES, + DEFAULT_MAX_UNCOMPRESSED_BYTES, +}; + +use limits::read_capped; + +/// 输入来源。 +pub(super) enum Source { + /// 目录（MultiMC 实例、已解开的包）。 + Dir, + /// zip（`.zip` / `.mrpack`）。`RefCell` 让只读方法能取 `&mut ZipArchive`（解压需要）。 + Zip(RefCell>), +} + +/// 一个已校验的整合包输入（目录或 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..03dbc11 --- /dev/null +++ b/crates/core/src/addon/pack/archive/limits.rs @@ -0,0 +1,167 @@ +//! 读取限额：条目数 / 解压总体积 / 单条目，以及两处封顶实现。 +//! +//! # 两阶段限额（打开 vs 读取） +//! +//! 打开阶段（[`check_limits`]）只能拿**中央目录声明的大小**做判断——它会撒谎。 +//! 因此读取阶段还有第二道：单条目按实际读出字节封顶（[`read_capped`]），批量读取 +//! （[`super::PackArchive::override_files`]）再按**累计实际字节**从 [`ReadBudget`] 里扣减。 +//! 没有预算的批量读取等于把 `max_uncompressed_bytes` 降级成"每条单独算"——一个 2 万条目、 +//! 每条声明 1 字节却解出几十 MiB 的包能把 CPU/时间耗在这里（r1 p3-4）。 + +use std::cell::Cell; +use std::io::Read; + +use super::super::error::{PackError, PackResult}; + +/// 默认条目数上限（一个巨型整合包 ≈ 数千条，2 万条已经很宽）。 +pub const DEFAULT_MAX_ENTRIES: usize = 20_000; +/// 默认解压总体积上限（512 MiB；`.mrpack` 的 `overrides` 通常几十 MiB）。 +pub const DEFAULT_MAX_UNCOMPRESSED_BYTES: u64 = 512 * 1024 * 1024; +/// 默认单条目上限（64 MiB；最大的 mod 也不过十几 MiB）。 +pub const DEFAULT_MAX_ENTRY_BYTES: u64 = 64 * 1024 * 1024; + +/// 包读取限额。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct PackLimits { + /// 条目数上限。 + pub max_entries: usize, + /// 解压总体积上限。 + pub max_uncompressed_bytes: u64, + /// 单条目上限。 + pub max_entry_bytes: u64, +} + +impl PackLimits { + /// 三档显式给值（测试与"可疑包"复查用）。 + #[must_use] + pub const fn new( + max_entries: usize, + max_uncompressed_bytes: u64, + max_entry_bytes: u64, + ) -> Self { + Self { + max_entries, + max_uncompressed_bytes, + max_entry_bytes, + } + } +} + +impl Default for PackLimits { + fn default() -> Self { + Self { + max_entries: DEFAULT_MAX_ENTRIES, + max_uncompressed_bytes: DEFAULT_MAX_UNCOMPRESSED_BYTES, + max_entry_bytes: DEFAULT_MAX_ENTRY_BYTES, + } + } +} + +/// 一次批量读取的**累计**预算（读取阶段，按实际读出的字节扣减）。 +/// +/// 作用域是"拿到它的那次扫描"：`PackArchive::override_files` 每次调用新建一份， +/// 所以要跨多次调用共享额度（例如整包只给一份 `max_uncompressed_bytes`）， +/// 必须由调用方自建一个并交给 `override_files_with`（r2 p3-b）。 +/// +/// 为什么需要它：中央目录声明的大小可以撒谎，单个条目也被限制在 +/// [`PackLimits::max_entry_bytes`]，但"很多条各自合规"累起来仍可能远超 +/// `max_uncompressed_bytes`。批量读取（`override_files`）持有一个预算，边读边扣。 +#[derive(Debug)] +pub struct ReadBudget { + remaining: Cell, +} + +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..43cb9d4 --- /dev/null +++ b/crates/core/src/addon/pack/format.rs @@ -0,0 +1,391 @@ +//! 格式扩展点：[`PackFormat`] trait + 注册表 [`PackRegistry`] + **写死的探测优先级**。 +//! +//! # 可扩展性的判据是测试，不是文档 +//! +//! `tests/extend.rs` 里有一个只有几十行的假格式 `ToyFormat`（单文件、`toy.json` 当清单）： +//! 它**只加一行注册**（`PackRegistry::builtin().with(&TOY)`）就能被探测、读取、渲染、写回， +//! 不改模型、不改 CurseForge / Modrinth / MultiMC 任何一行。这是"社区标准加一个格式"的 +//! 最小代价证明。 +//! +//! # 探测优先级写死在这里，顺序由注册表 `Vec` 位置决定 +//! +//! [`PackRegistry::builtin`] 的顺序：**CurseForge → Modrinth → MultiMC**。 +//! +//! - 跟 HMCL 对这三种格式的相对次序一致（`ModpackHelper.readModpackManifest`：Curse 在 +//! Modrinth 前、Modrinth 在 MultiMC 前），减少与社区工具的行为差异； +//! - 每个格式的 `detect` 都带**形状校验**（CF 要 `manifestType: minecraftModpack`、mrpack 要 +//! `formatVersion` + `files` 数组、MultiMC 要 `components` 非空），所以名字很泛的 +//! `manifest.json` 不会把 `.mrpack` 抢走； +//! - 同一份包同时命中多个格式时，[`PackMatch::also_matched`] 会记下其余命中，调用方可以提示 +//! "这包不标准"——不做静默判定，也不做自动合并； +//! - [`PackRegistry::register`] 追加到**末尾**（= 最低优先级），所以测试里改一行顺序就能 +//! 证明"优先级来自注册表顺序"（`tests/detect.rs` 有一条反序注册的用例）。 +//! +//! # 写：默认实现**只保证同格式往返**（这条是给 M111/M112 的边界声明） +//! +//! 默认实现（[`PackFormat::write`]）替所有格式做同一件事：写清单 entry（[`PackFormat::render`] +//! 的产物）+ 把 `manifest.overrides` 的 `(dir, side, files)` **原样**搬进 zip。因此新格式只要 +//! 实现 `metadata_entry` + `render` 就同时获得导出能力；只读格式（MultiMC）不实现 +//! `metadata_entry`，写会得到明确的 `crate::addon::pack::error::PackErrorKind::Unsupported`。 +//! +//! **它不做目标格式映射**，具体缺四件事（都属于 M112，别以为这一层已经做了）： +//! +//! 1. **目录名映射**：mrpack 的覆盖目录名由 `side` 决定（`overrides` / `client-overrides` / +//! `server-overrides`），CF 只有一个 `overrides`（名字由清单给）。`check_overrides` 只保证 +//! "布局表达不了就报错"，不负责改名； +//! 2. **`side` 合并/分派**：CF 表达不了 Client/Server 分侧，现在是**拒**而不是合并； +//! 3. **加载器 id 规范化**：CF 要 `forge-47.2.0` / `fabric-0.15.11`，mrpack 要 +//! `forge` / `fabric-loader` 这类键。`render` 只按模型里的 `raw`/`kind` 写，跨格式转出来的 +//! id 形态可能不被目标平台接受（尤其 MultiMC 的 `net.fabricmc.fabric-loader`）； +//! 4. **`extra` 不按格式分桶**：模型只有一份未知字段集合，跨格式导出会把别的格式的未知键 +//! 一起带过去。 +//! +//! 换句话说：`X.read` → `X.write` 是可靠往返（有逐字段相等的测试）；`X.read` → `Y.write` +//! 要么被 `check_overrides` 拒掉，要么"结构合法但语义不完整"。**要跨格式导出，先做映射。** +//! +//! # 映射层已经在了（M112） +//! +//! [`crate::addon::export`] 就是那层映射：它把实例目录扫成模型（覆盖目录统一到 `overrides/`、 +//! 禁用位落成路径后缀 `.disabled`、`dependencies` 从实例快照取），再用 +//! [`PackPayload::with_sources`] 把"包内条目名 → 实例里的源文件"交给本模块写盘。所以本文件 +//! 仍然不做映射（那是格式之上的事），但"跨格式导出无路可走"已经不再成立。 + +use std::fmt::Debug; +use std::fs::File; +use std::io::Write; +use std::path::{Path, PathBuf}; + +use super::archive::PackArchive; +use super::curseforge; +use super::error::{PackError, PackResult}; +use super::manifest::PackManifest; +use super::modrinth; +use super::multimc; +use super::path::{normalize_dir, normalize_file}; + +mod payload; + +/// 导出时的覆盖内容来源在 [`payload`] 子模块里（`payload.rs`，与本文件拆开是为了守 400 行）： +/// [`PackPayload::metadata_only`] 只写清单、[`PackPayload::from_root`] 按 +/// `//` 取文件、[`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` 出清单；④写进**临时文件**再 `rename` 到 `target`（失败不留半个包）。 + /// + /// # 只保证同格式往返（写给 M111/M112） + /// + /// 默认 `write` 的覆盖目录策略是"把 `manifest.overrides` 里 `(dir, side, files)` + /// 原样再打一遍"，也就是"读出来的包按原样打包"。它**不做**目标格式的目录映射、`side` + /// 分派、加载器 id 规范化，也**不按格式分桶** `extra`。所以： + /// + /// - 同格式往返（`X.read` → `X.write`）可靠，有逐字段相等的测试； + /// - 跨格式导出（`X.read` → `Y.write`）在布局不同时被 [`Self::check_overrides`] 拒掉； + /// 但"布局恰好兼容、语义不兼容"的部分（加载器 id 形态、`extra` 里别的格式的未知键） + /// **仍会被原样带过去**——那是 M112 的活，这一层不替谁做映射。 + fn write( + &self, + manifest: &PackManifest, + payload: PackPayload<'_>, + target: &Path, + ) -> PackResult<()> { + let Some(entry) = self.metadata_entry() else { + return Err(PackError::unsupported(format!( + "格式 {}（{}）只支持读取，不支持导出", + self.id(), + self.label() + )) + .with_hint("导出请选 Modrinth（.mrpack）或 CurseForge 格式")); + }; + // 先判"能不能表达"，再碰磁盘：跨格式导出宁可报错，也不产出空包。 + self.check_overrides(manifest)?; + // 模型可能来自外部构造：搬内容前把每条路径重查一遍。 + manifest.check_paths()?; + let json = self.render(manifest)?; + // 临时文件 + rename：中途失败时目标路径上不会留下"看起来能用"的半个 zip（r1 p3-1）。 + let temp = temporary_path(target); + match write_container(self.id(), entry, &json, manifest, payload, &temp) { + Ok(()) => std::fs::rename(&temp, target).map_err(|error| { + let _ = std::fs::remove_file(&temp); + PackError::io(format!( + "把 {} 改名成 {} 失败：{error}", + temp.display(), + target.display() + )) + }), + Err(error) => { + let _ = std::fs::remove_file(&temp); + Err(error) + } + } + } +} + +/// 临时文件路径（与目标同目录，`rename` 才能原子替换）。 +fn temporary_path(target: &Path) -> PathBuf { + let mut name = target.file_name().map_or_else( + || std::ffi::OsString::from("pack"), + std::ffi::OsStr::to_os_string, + ); + name.push(format!(".{}.part", std::process::id())); + target.with_file_name(name) +} + +/// 真正写 zip 的那一段（失败了由调用方删临时文件）。 +fn write_container( + format_id: &str, + entry: &'static str, + json: &str, + manifest: &PackManifest, + payload: PackPayload<'_>, + temp: &Path, +) -> PackResult<()> { + let file = File::create(temp) + .map_err(|error| PackError::io(format!("创建 {} 失败：{error}", temp.display())))?; + let mut writer = zip::ZipWriter::new(file); + let options = zip::write::SimpleFileOptions::default() + .compression_method(zip::CompressionMethod::Deflated) + .unix_permissions(0o644); + writer + .start_file(entry, options) + .map_err(|error| PackError::io(format!("写 {entry} 失败：{error}")))?; + writer + .write_all(json.as_bytes()) + .map_err(|error| PackError::io(format!("写 {entry} 失败：{error}")))?; + // 未压缩总量封顶在 ZIP64 阈值（≈4 GiB）：Modrinth 官方导出也是这样拒绝的，而不是 + // 静默截断（HMCL 那边 `(int)` 截断只打 warning 是反面教材）。临时文件由调用方删。 + let mut total = json.len() as u64; + for group in &manifest.overrides { + let dir = normalize_dir(&group.dir)?; + for override_file in &group.files { + let path = normalize_file(&override_file.path)?; + let name = format!("{dir}/{path}"); + let source = match payload.source_for(&name) { + Some(source) => source.to_path_buf(), + None => { + let Some(root) = payload.root() else { + return Err(PackError::unsupported(format!( + "导出需要覆盖内容（{name}），但既没有来源映射也没有 payload 根目录" + ))); + }; + root.join(&dir).join(&path) + } + }; + let bytes = std::fs::read(&source).map_err(|error| { + PackError::io(format!("读覆盖文件 {} 失败：{error}", source.display())) + })?; + total += bytes.len() as u64; + if total >= zip::ZIP64_BYTES_THR { + return Err(PackError::limits(format!( + "包体未压缩总量已超过 {} 字节（ZIP64 阈值），拒绝写出一个需要 ZIP64 的整合包", + zip::ZIP64_BYTES_THR + )) + .with_hint("把超大的覆盖文件移出实例后再导出；mrpack/CF 都不接受 ZIP64")); + } + writer + .start_file(name.clone(), options) + .map_err(|error| PackError::io(format!("写 {name} 失败：{error}")))?; + writer + .write_all(&bytes) + .map_err(|error| PackError::io(format!("写 {name} 失败：{error}")))?; + } + } + writer + .finish() + .map_err(|error| PackError::io(format!("收尾 zip 失败：{error}（格式 {format_id}）")))?; + Ok(()) +} + +/// 一次探测的结果。 +#[derive(Debug, Clone)] +pub struct PackMatch { + format: &'static dyn PackFormat, + evidence: &'static str, + also_matched: Vec<&'static str>, +} + +impl PackMatch { + /// 选中的格式。 + #[must_use] + pub fn format(&self) -> &'static dyn PackFormat { + self.format + } + + /// 命中的证据条目名（探测器凭哪个文件认领的，进日志用）。 + #[must_use] + pub fn evidence(&self) -> &'static str { + self.evidence + } + + /// 同样命中的其它格式 id（探测顺序里排在后面的那些）。 + #[must_use] + pub fn also_matched(&self) -> &[&'static str] { + &self.also_matched + } + + /// 是否有"多格式同时命中"的歧义（不标准包）。 + #[must_use] + pub fn is_ambiguous(&self) -> bool { + !self.also_matched.is_empty() + } +} + +/// 格式注册表：**顺序即优先级**。 +#[derive(Debug, Clone, Default)] +pub struct PackRegistry { + formats: Vec<&'static dyn PackFormat>, +} + +impl PackRegistry { + /// 一个都没有的注册表（测试"没有格式认领"用）。 + #[must_use] + pub fn empty() -> Self { + Self { + formats: Vec::new(), + } + } + + /// 内置三格式，顺序即优先级：CurseForge → Modrinth → MultiMC。 + #[must_use] + pub fn builtin() -> Self { + Self { + formats: vec![ + &curseforge::CURSEFORGE, + &modrinth::MODRINTH, + &multimc::MULTIMC, + ], + } + } + + /// 追加一种格式（追加 = 最低优先级）。加一种格式真的只要这一行。 + pub fn register(&mut self, format: &'static dyn PackFormat) { + self.formats.push(format); + } + + /// 链式注册。 + #[must_use] + pub fn with(mut self, format: &'static dyn PackFormat) -> Self { + self.register(format); + self + } + + /// 按优先级列出格式 id。 + #[must_use] + pub fn ids(&self) -> Vec<&'static str> { + self.formats.iter().map(|format| format.id()).collect() + } + + /// 按 id 找格式。 + #[must_use] + pub fn get(&self, id: &str) -> Option<&'static dyn PackFormat> { + self.formats + .iter() + .copied() + .find(|format| format.id() == id) + } + + /// 全部命中的格式 id（诊断"这包不标准"用；**只看命中**，单个格式的读错误被忽略—— + /// 要区分"包坏了"与"不认识"请用 [`Self::detect`]）。 + #[must_use] + pub fn detect_all(&self, pack: &PackArchive) -> Vec<&'static str> { + self.formats + .iter() + .filter(|format| matches!(format.detect(pack), Ok(Some(_)))) + .map(|format| format.id()) + .collect() + } + + /// 按优先级选第一个命中的格式。 + /// + /// 错误语义（M111 的失败分级依赖这两条的区别）： + /// + /// - **一个都不命中、但某个格式的清单读不出来** → 返回那个格式的错误 + /// （`pack_metadata` 一类：包坏了，换格式也没用）； + /// - **一个都不命中、也没有任何格式的清单在场** → `pack_unsupported` + /// （真的不认识这份包）； + /// - 命中优先于失败：包里躺着一份别人的坏 `manifest.json` 不影响真的 `.mrpack` 被认出来。 + pub fn detect(&self, pack: &PackArchive) -> PackResult { + 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/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..2692169 --- /dev/null +++ b/crates/core/src/addon/pack/tests/detect.rs @@ -0,0 +1,223 @@ +//! 探测优先级：顺序写死在注册表里，用例把"谁赢"和"为什么赢"都钉住。 +//! +//! 判据分三层，缺一层都可能被"看起来对"糊过去： +//! 1. 内置顺序本身（[`PackRegistry::ids`]）； +//! 2. 同一份包命中多格式时选谁（含 `also_matched` 记录的其它命中）； +//! 3. **换一下注册顺序，赢家跟着换**——这才证明优先级来自注册表，而不是代码里散落的 if。 + +use super::{fixtures, temp_root, write_zip}; +use crate::addon::pack::archive::PackArchive; +use crate::addon::pack::curseforge::CURSEFORGE; +use crate::addon::pack::error::PackErrorKind; +use crate::addon::pack::format::{PackFormat, PackRegistry}; +use crate::addon::pack::modrinth::MODRINTH; +use crate::addon::pack::multimc::MULTIMC; + +const CF_MANIFEST: &[u8] = br#"{"manifestType":"minecraftModpack","manifestVersion":1, + "name":"hybrid pack","version":"1.0","minecraft":{"version":"1.20.1"},"files":[]}"#; + +const MR_INDEX: &[u8] = br#"{"game":"minecraft","formatVersion":1,"versionId":"1.0", + "name":"hybrid pack","files":[],"dependencies":{"minecraft":"1.20.1"}}"#; + +const MMC_PACK: &[u8] = + br#"{"formatVersion":1,"components":[{"uid":"net.minecraft","version":"1.20.1"}]}"#; + +/// 同时带三种身份标记的"不标准包"。 +fn hybrid_pack(tag: &str) -> std::path::PathBuf { + let target = temp_root(tag).join("hybrid.zip"); + write_zip( + &target, + &[ + ("manifest.json", CF_MANIFEST), + ("modrinth.index.json", MR_INDEX), + ("mmc-pack.json", MMC_PACK), + ("overrides/config/x.toml", &b"x = 1\n"[..]), + ], + ); + target +} + +#[test] +fn builtin_priority_is_pinned() { + assert_eq!( + PackRegistry::builtin().ids(), + vec!["curseforge", "modrinth", "multimc"], + "探测顺序是决策，不是实现细节：改了要连着报告与测试一起改" + ); +} + +#[test] +fn curseforge_wins_when_a_pack_carries_every_marker() { + let pack = PackArchive::open_default(hybrid_pack("detect-hybrid")).expect("打开混合包"); + let matched = PackRegistry::builtin().detect(&pack).expect("要能选出格式"); + assert_eq!(matched.format().id(), "curseforge"); + assert_eq!( + matched.also_matched().to_vec(), + vec!["modrinth", "multimc"], + "其余命中必须可见（调用方据此提示「这包不标准」）" + ); + assert!(matched.is_ambiguous()); +} + +#[test] +fn a_plain_manifest_json_does_not_claim_curseforge() { + // `manifest.json` 这名字太泛：形状不符就不能认领，否则 mrpack 会被抢走。 + let target = temp_root("detect-plain").join("plain.zip"); + write_zip( + &target, + &[ + ("manifest.json", &br#"{"hello":"world"}"#[..]), + ("modrinth.index.json", MR_INDEX), + ], + ); + let pack = PackArchive::open_default(&target).expect("打开包"); + let matched = PackRegistry::builtin().detect(&pack).expect("要能选出格式"); + assert_eq!(matched.format().id(), "modrinth"); + assert!(matched.also_matched().is_empty(), "CF 不该被「泛名」骗到"); +} + +#[test] +fn registration_order_decides_the_winner() { + // 同一份包同时有 CF 与 mrpack 标记：只换注册顺序，赢家就该换。 + let target = temp_root("detect-order").join("both.zip"); + write_zip( + &target, + &[ + ("manifest.json", CF_MANIFEST), + ("modrinth.index.json", MR_INDEX), + ], + ); + let pack = PackArchive::open_default(&target).expect("打开双标记包"); + + let builtin = PackRegistry::builtin() + .detect(&pack) + .expect("默认顺序要能选"); + assert_eq!(builtin.format().id(), "curseforge"); + assert_eq!(builtin.also_matched().to_vec(), vec!["modrinth"]); + + let reversed = PackRegistry::empty().with(&MODRINTH).with(&CURSEFORGE); + let matched = reversed.detect(&pack).expect("反序注册也要能选"); + assert_eq!( + matched.format().id(), + "modrinth", + "反序注册后 Modrinth 排第一，就该它赢" + ); + assert_eq!(matched.also_matched().to_vec(), vec!["curseforge"]); +} + +#[test] +fn unknown_package_is_rejected_with_the_list_of_tried_formats() { + let target = temp_root("detect-unknown").join("unknown.zip"); + write_zip(&target, &[("readme.txt", &b"nothing to see"[..])]); + let pack = PackArchive::open_default(&target).expect("打开包"); + assert!(PackRegistry::builtin().detect_all(&pack).is_empty()); + let error = PackRegistry::builtin() + .detect(&pack) + .expect_err("没有格式认领就必须报错"); + assert_eq!(error.kind(), PackErrorKind::Unsupported); + for id in ["curseforge", "modrinth", "multimc"] { + assert!( + error.message().contains(id), + "错误里要列出试过哪些格式，实际：{}", + error.message() + ); + } +} + +#[test] +fn multimc_needs_a_non_empty_component_graph() { + let target = temp_root("detect-mmc-empty").join("empty-mmc.zip"); + write_zip( + &target, + &[( + "mmc-pack.json", + &br#"{"formatVersion":1,"components":[]}"#[..], + )], + ); + let pack = PackArchive::open_default(&target).expect("打开包"); + assert_eq!( + MULTIMC.detect(&pack).expect("mmc-pack.json 可读"), + None, + "空 components 是空壳，不能当 MultiMC 实例" + ); + assert_eq!( + PackRegistry::builtin() + .detect(&pack) + .expect_err("不该有格式认领") + .kind(), + PackErrorKind::Unsupported + ); +} + +#[test] +fn multimc_instance_directory_is_detected() { + let root = fixtures::multimc("detect-mmc-dir"); + let pack = PackArchive::open_default(&root).expect("打开实例目录"); + let matched = PackRegistry::builtin() + .detect(&pack) + .expect("目录形式也要能探测"); + assert_eq!(matched.format().id(), "multimc"); + assert!(!matched.is_ambiguous()); +} + +#[test] +fn a_corrupt_manifest_is_a_metadata_error_not_unsupported() { + // r1 p3-2：清单在、但读不出来 = 包坏了（`pack_metadata`）。之前三个 detect 都用 + // `.ok().flatten()` 吞掉解析错误，结果被报成「没有格式认领」——M111 的失败分级会据此 + // 把"可以重下文件"的包判成"不支持"。 + let target = temp_root("corrupt-manifest").join("bad.zip"); + write_zip(&target, &[("manifest.json", &br#"{"name": "#[..])]); + let pack = PackArchive::open_default(&target).expect("zip 本身可读"); + + let error = PackRegistry::builtin() + .detect(&pack) + .expect_err("坏清单必须报错"); + assert_eq!(error.kind(), PackErrorKind::Metadata, "{error}"); + assert!( + !error.message().contains("没有格式认领"), + "不许把「包坏了」说成「不认识」：{}", + error.message() + ); +} + +#[test] +fn a_corrupt_foreign_manifest_does_not_hide_a_valid_mrpack() { + // 命中优先于失败：包里躺着一份别人的坏 manifest.json，不该让真 mrpack 也变得不可用。 + let target = temp_root("corrupt-foreign").join("mixed.zip"); + write_zip( + &target, + &[ + ("manifest.json", &br#"{"name": "#[..]), + ("modrinth.index.json", MR_INDEX), + ], + ); + let pack = PackArchive::open_default(&target).expect("zip 本身可读"); + let matched = PackRegistry::builtin() + .detect(&pack) + .expect("mrpack 命中应当优先于其它格式的坏文件"); + assert_eq!(matched.format().id(), "modrinth"); + assert!(matched.also_matched().is_empty(), "CF 没命中（它坏了）"); +} + +#[test] +fn a_missing_manifest_is_not_an_error() { + // 反向对照：**没有** `manifest.json` 是"不是 CF"，不是"包坏了"。 + let target = temp_root("no-manifest").join("mmc.zip"); + write_zip( + &target, + &[( + "mmc-pack.json", + &br#"{"formatVersion":1,"components":[{"uid":"net.minecraft","version":"1.20.1"}]}"#[..], + )], + ); + let pack = PackArchive::open_default(&target).expect("zip 本身可读"); + assert_eq!(CURSEFORGE.detect(&pack).expect("缺清单不是错误"), None); + assert_eq!( + PackRegistry::builtin() + .detect(&pack) + .expect("MultiMC 应当命中") + .format() + .id(), + "multimc" + ); +} diff --git a/crates/core/src/addon/pack/tests/export.rs b/crates/core/src/addon/pack/tests/export.rs new file mode 100644 index 0000000..14ab2aa --- /dev/null +++ b/crates/core/src/addon/pack/tests/export.rs @@ -0,0 +1,156 @@ +//! 导出面的安全闸（r1 p2-1 / p3-1）：**跨格式导出必须被拒，失败不留半个包**。 +//! +//! 这一组不测"映射是否做对"（那是 M112），只测"表达不了的时候会不会静默产出空包"。 + +use super::{fixtures, temp_root}; +use crate::addon::pack::archive::PackArchive; +use crate::addon::pack::curseforge::CURSEFORGE; +use crate::addon::pack::error::PackErrorKind; +use crate::addon::pack::format::{PackFormat, PackPayload}; +use crate::addon::pack::manifest::{OverrideFile, PackManifest, PackOverrides, PackSide}; +use crate::addon::pack::modrinth::MODRINTH; +use crate::addon::pack::multimc::MULTIMC; + +#[test] +fn a_multimc_instance_cannot_be_written_as_mrpack() { + // r1 p2-1 实测过的那条：MultiMC 模型写 mrpack 会返回 Ok，但覆盖内容落在 `.minecraft/...`， + // mrpack 导入器只解压 overrides / client-overrides / server-overrides ⇒ mods 数量为 0。 + // 现在必须在写第一个字节之前就拒。 + let root = fixtures::multimc("export-mmc-mr"); + let pack = PackArchive::open_default(&root).expect("打开实例目录"); + let mut manifest = MULTIMC.read(&pack).expect("读 MultiMC 清单"); + manifest.version = Some("1.0.0".to_string()); // mrpack 需要 versionId，别让别的错误顶包 + + let target = root.with_file_name("cross.mrpack"); + let error = MODRINTH + .write(&manifest, PackPayload::from_root(&root), &target) + .expect_err("跨格式导出必须被拒，不能产出 mods 为 0 的包"); + assert_eq!(error.kind(), PackErrorKind::Unsupported, "{error}"); + assert!( + error.message().contains(".minecraft"), + "错误要说清是哪个目录表达不了：{}", + error.message() + ); + assert!(error.hint().is_some(), "要给下一步提示（目录映射属 M112）"); + assert!(!target.exists(), "被拒时不许留下目标文件"); +} + +#[test] +fn an_mrpack_with_split_sides_cannot_be_written_as_curseforge() { + // CF 只有一个 `overrides` 目录字段，表达不了 client/server 分侧；现在是拒，不是猜。 + let fixture = fixtures::modrinth("export-mr-cf"); + let pack = PackArchive::open_default(&fixture.zip).expect("打开 mrpack 夹具"); + let manifest = MODRINTH.read(&pack).expect("读 mrpack 清单"); + + let target = fixture.zip.with_file_name("cross.zip"); + let error = CURSEFORGE + .write(&manifest, PackPayload::from_root(&fixture.dir), &target) + .expect_err("CF 表达不了分侧覆盖目录"); + assert_eq!(error.kind(), PackErrorKind::Unsupported, "{error}"); + assert!( + error.message().contains("client"), + "错误要指出被拒的是哪一侧：{}", + error.message() + ); + assert!(!target.exists(), "被拒时不许留下目标文件"); +} + +#[test] +fn curseforge_refuses_more_than_one_both_side_group() { + // CF 的 `overrides` 只有一个字段：两个 Both 组必然有一个不被清单声明（静默丢内容）。 + let mut manifest = PackManifest::new("两个 Both 组"); + manifest.minecraft = Some("1.20.1".to_string()); + manifest + .overrides + .push(PackOverrides::new("overrides", PackSide::Both)); + manifest + .overrides + .push(PackOverrides::new("extra-overrides", PackSide::Both)); + + let target = temp_root("export-cf-two").join("out.zip"); + let error = CURSEFORGE + .write(&manifest, PackPayload::metadata_only(), &target) + .expect_err("多出来的 Both 组会被清单漏掉，必须拒"); + assert_eq!(error.kind(), PackErrorKind::Unsupported, "{error}"); + assert!(!target.exists(), "被拒时不许留下目标文件"); +} + +#[test] +fn a_failed_export_leaves_neither_a_half_pack_nor_a_temp_file() { + // r1 p3-1：清单写完了、覆盖文件读不出来 → 目标路径与临时文件都不许留。 + let mut manifest = PackManifest::new("缺覆盖文件的模型"); + manifest.minecraft = Some("1.20.1".to_string()); + manifest.overrides.push(PackOverrides { + dir: "overrides".to_string(), + side: PackSide::Both, + files: vec![OverrideFile { + path: "mods/missing.jar".to_string(), + sha1: "0".repeat(40), + size: 1, + }], + }); + + let root = temp_root("export-half"); + std::fs::create_dir_all(&root).expect("建目录"); + let target = root.join("out.zip"); + let error = CURSEFORGE + .write(&manifest, PackPayload::from_root(&root), &target) + .expect_err("覆盖文件不存在时必须失败"); + assert_eq!(error.kind(), PackErrorKind::Io, "{error}"); + assert!(!target.exists(), "失败后目标路径不许存在"); + + let leftovers: Vec = std::fs::read_dir(&root) + .expect("列目录") + .filter_map(Result::ok) + .map(|entry| entry.file_name().to_string_lossy().to_string()) + .collect(); + assert!( + leftovers.is_empty(), + "临时文件没清干净（p3-1 回退）：{leftovers:?}" + ); +} + +#[test] +fn same_format_export_is_still_allowed() { + // 反向对照：这两条闸不能把同格式往返也挡掉（那是 r1 明确要保住的）。 + let fixture = fixtures::curseforge("export-same-cf"); + let pack = PackArchive::open_default(&fixture.zip).expect("打开 CF 夹具"); + let manifest = CURSEFORGE.read(&pack).expect("读 CF 清单"); + CURSEFORGE + .check_overrides(&manifest) + .expect("CF 自己读出来的模型必须能被 CF 表达"); + + let fixture = fixtures::modrinth("export-same-mr"); + let pack = PackArchive::open_default(&fixture.zip).expect("打开 mrpack 夹具"); + let manifest = MODRINTH.read(&pack).expect("读 mrpack 清单"); + MODRINTH + .check_overrides(&manifest) + .expect("mrpack 自己读出来的模型必须能被 mrpack 表达"); +} + +#[test] +fn mrpack_refuses_two_override_groups_for_the_same_side() { + // r2 p3-a：mrpack 的「每侧只能有一个覆盖目录」分支此前零测试（删掉它 59 条全绿）。 + // 目录名检查管不到这里：两个组的 `dir` 都合法，区别只在于同一侧出现了两次。 + let mut manifest = PackManifest::new("同侧两个覆盖目录"); + manifest.version = Some("1.0.0".to_string()); + manifest.minecraft = Some("1.20.1".to_string()); + manifest + .overrides + .push(PackOverrides::new("overrides", PackSide::Both)); + manifest + .overrides + .push(PackOverrides::new("overrides", PackSide::Both)); + + let target = temp_root("export-mr-same-side").join("out.mrpack"); + let error = MODRINTH + .write(&manifest, PackPayload::metadata_only(), &target) + .expect_err("同一侧两个覆盖目录必须拒"); + assert_eq!(error.kind(), PackErrorKind::Unsupported, "{error}"); + assert!( + error.message().contains("每个侧只能有一个覆盖目录"), + "错误要指出是「同侧重复」而不是「目录名不对」：{}", + error.message() + ); + assert!(!target.exists(), "被拒时不许留下目标文件"); +} diff --git a/crates/core/src/addon/pack/tests/export_harness.rs b/crates/core/src/addon/pack/tests/export_harness.rs new file mode 100644 index 0000000..a6d4bcb --- /dev/null +++ b/crates/core/src/addon/pack/tests/export_harness.rs @@ -0,0 +1,121 @@ +//! 导出测试的共用夹具（M112）：实例目录、`versions/` 版本层、假的远端目录。 +//! +//! 这里的东西**只给测试用**：本仓库没有 Modrinth/CF 客户端（要网络与 key），所以远端查表一律 +//! 由 [`StubCatalog`] 注入；实例目录手造成"M111 导入产物"的形状（内容目录 + 版本 JSON）。 + +use std::cell::RefCell; +use std::collections::BTreeMap; +use std::path::{Path, PathBuf}; + +use super::{temp_root, write_file}; +use crate::addon::export::catalog::{RemoteCatalog, RemoteHit}; +use crate::addon::export::scan::{scan_instance, DEFAULT_CONTENT_ROOTS}; +use crate::addon::pack::curseforge::fingerprint; + +pub(super) const VANILLA_LAYER: &str = r#"{"id": "1.20.1", "libraries": []}"#; +pub(super) const FABRIC_LAYER: &str = r#"{ + "id": "1.20.1-fabric-0.15.11", + "inheritsFrom": "1.20.1", + "libraries": [{"name": "net.fabricmc:fabric-loader:0.15.11"}] +}"#; +pub(super) const NEOFORGE_LAYER: &str = r#"{ + "id": "1.20.1-neoforge-47.1.106", + "inheritsFrom": "1.20.1", + "libraries": [ + {"name": "net.neoforged:neoforge:1.20.1-47.1.106"}, + {"name": "net.fancymodloader:loader:3.0.5"} + ] +}"#; +pub(super) const FORGE_LAYER: &str = r#"{ + "id": "1.20.1-forge-47.2.0", + "inheritsFrom": "1.20.1", + "libraries": [{"name": "net.minecraftforge:forge:1.20.1-47.2.0:universal"}] +}"#; + +/// 内容目录清单（与导出默认值同一份）。 +pub(super) fn defaults() -> Vec { + 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) -> PathBuf { + let root = temp_root(tag).join("game"); + write_layer(&root, "1.20.1", VANILLA_LAYER); + write_layer(&root, "1.20.1-fabric-0.15.11", FABRIC_LAYER); + write_file(&root.join("mods/jei.jar"), b"PK\x03\x04 jei body"); + write_file(&root.join("mods/off.jar.disabled"), b"PK\x03\x04 off body"); + write_file(&root.join("config/known.toml"), b"key = \"value\"\n"); + write_file(&root.join("logs/latest.log"), b"not pack content\n"); + root +} + +/// 一个 NeoForge 1.20.1 实例目录（CF `modLoaders[].id` 的 MC 前缀特例用它）。 +pub(super) fn neoforge_instance(tag: &str) -> PathBuf { + let root = temp_root(tag).join("game"); + write_layer(&root, "1.20.1", VANILLA_LAYER); + write_layer(&root, "1.20.1-neoforge-47.1.106", NEOFORGE_LAYER); + write_file(&root.join("mods/jei.jar"), b"PK\x03\x04 jei body"); + root +} + +/// 目录里的一个文件（路径 + SHA-1 + CF 指纹），与 `scan_instance` 同源。 +pub(super) fn digests(root: &Path, path: &str) -> (String, u32) { + let (locals, _) = scan_instance(root, &defaults()); + let local = locals + .iter() + .find(|file| file.path == path) + .unwrap_or_else(|| panic!("夹具里没有 {path}")); + let value = fingerprint::fingerprint_file(&local.disk).expect("算指纹"); + (local.sha1.clone(), value) +} + +/// 一个能写进 mrpack 的 Modrinth 命中（sha1 + sha512 + 直链）。 +pub(super) fn modrinth_hit(sha1: &str, url: &str) -> RemoteHit { + let mut hashes = BTreeMap::new(); + hashes.insert("sha1".to_string(), sha1.to_string()); + hashes.insert("sha512".to_string(), "a".repeat(128)); + RemoteHit::modrinth(vec![url.to_string()], hashes, Some(11)) +} + +/// 一个**假**的远端目录：查表结果由测试塞，调用过的指纹记下来（哨兵值那条分支靠它断言）。 +#[derive(Default)] +pub(super) struct StubCatalog { + modrinth: BTreeMap, + 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..6e052c4 --- /dev/null +++ b/crates/core/src/addon/pack/tests/export_pipeline.rs @@ -0,0 +1,370 @@ +//! 导出管线（M112）：三分类、`.disabled` 路径后缀、`game`/`dependencies` 来自实例快照。 +//! +//! 夹具在 [`super::export_harness`]：手造的实例目录（形状与 M111 导入产物一致）+ +//! 注入式假远端目录（本仓库没有 Modrinth/CF 客户端，测试也不许联网）。 + +use std::collections::BTreeMap; +use std::io::Read; +use std::path::Path; + +use super::export_harness::{ + defaults, digests, fabric_instance, modrinth_hit, neoforge_instance, StubCatalog, +}; +use super::{temp_root, write_file}; +use crate::addon::export::classify::classify_with; +use crate::addon::export::scan::{is_disabled_path, scan_instance}; +use crate::addon::export::{export_instance, ExportRequest, FileClass, FileReason, RemoteHit}; +use crate::addon::pack::archive::PackArchive; +use crate::addon::pack::curseforge::{fingerprint, CURSEFORGE}; +use crate::addon::pack::error::PackErrorKind; +use crate::addon::pack::format::PackFormat; +use crate::addon::pack::manifest::{PackFile, PackManifest}; +use crate::addon::pack::modrinth::MODRINTH; +use crate::addon::LoaderKind; + +fn entry_names(path: &Path) -> Vec { + let pack = PackArchive::open_default(path).expect("打开 zip"); + pack.entries() + .iter() + .map(|entry| entry.name().to_string()) + .collect() +} + +#[test] +fn offline_mrpack_export_inlines_every_file_with_its_suffix() { + let root = fabric_instance("export-offline-mr"); + let target = root.with_file_name("offline.mrpack"); + let report = + export_instance(&ExportRequest::new(&root, &target, &MODRINTH)).expect("离线导出必须成功"); + + assert_eq!(report.format, "modrinth"); + assert_eq!(report.remote_count(), 0); + assert_eq!(report.inline_count(), 3, "{:?}", report.files); + assert_eq!(report.skipped_count(), 0); + assert!(report.is_complete()); + assert!(report.bytes > 0, "包路径与字节数必须结构化给出"); + assert_eq!(report.minecraft.as_deref(), Some("1.20.1")); + assert_eq!(report.loaders, vec!["fabric-loader 0.15.11".to_string()]); + + let pack = PackArchive::open_default(&target).expect("打开导出的包"); + let manifest = MODRINTH.read(&pack).expect("读回 mrpack"); + assert_eq!(manifest.name, "game"); + assert_eq!(manifest.version.as_deref(), Some("1.0.0")); + assert_eq!(manifest.minecraft.as_deref(), Some("1.20.1")); + let loader = manifest.loader(LoaderKind::Fabric).expect("加载器不能漏"); + assert_eq!(loader.version.as_deref(), Some("0.15.11")); + + let paths: Vec<&str> = manifest + .override_files() + .map(|(_, file)| file.path.as_str()) + .collect(); + assert_eq!( + paths, + vec!["config/known.toml", "mods/jei.jar", "mods/off.jar.disabled"], + "三个内容文件都要在 overrides/ 里，禁用位保留后缀" + ); + assert!(pack.has_entry("overrides/mods/off.jar.disabled")); + assert!( + !pack.has_entry("overrides/logs/latest.log"), + "白名单外（logs/）不打包" + ); +} + +#[test] +fn mrpack_index_declares_game_and_every_dependency() { + let root = fabric_instance("export-index-mr"); + let target = root.with_file_name("index.mrpack"); + export_instance(&ExportRequest::new(&root, &target, &MODRINTH)).expect("导出"); + + let pack = PackArchive::open_default(&target).expect("打开"); + let index = pack + .read_json("modrinth.index.json") + .expect("读清单") + .expect("有清单"); + assert_eq!(index["game"], "minecraft"); + assert_eq!(index["formatVersion"], 1); + assert_eq!(index["name"], "game"); + assert_eq!(index["dependencies"]["minecraft"], "1.20.1"); + assert_eq!( + index["dependencies"]["fabric-loader"], "0.15.11", + "只写 minecraft 漏加载器是本任务点名的不许" + ); + assert!(index["files"].as_array().is_some_and(Vec::is_empty)); +} + +#[test] +fn a_modrinth_hit_becomes_a_files_entry_with_both_catalogs_urls() { + let root = fabric_instance("export-remote-mr"); + let (sha1, value) = digests(&root, "mods/jei.jar"); + let catalog = StubCatalog::default() + .with_modrinth( + &sha1, + modrinth_hit(&sha1, "https://cdn.modrinth.com/data/x/jei.jar"), + ) + .with_curse( + value, + RemoteHit::curseforge(238_222, 5_102_025) + .with_download("https://edge.forgecdn.net/files/5102/025/jei.jar"), + ); + let target = root.with_file_name("remote.mrpack"); + let report = + export_instance(&ExportRequest::new(&root, &target, &MODRINTH).with_catalog(&catalog)) + .expect("导出"); + + assert_eq!(report.remote_count(), 1); + let entry = report + .files + .iter() + .find(|file| file.path == "mods/jei.jar") + .expect("jei 在报告里"); + assert_eq!(entry.class, FileClass::Remote); + assert_eq!(entry.reason, FileReason::ModrinthSha1); + assert_eq!( + entry.downloads.len(), + 2, + "两条目录的直链都要写进 downloads[]" + ); + + let pack = PackArchive::open_default(&target).expect("打开"); + let manifest = MODRINTH.read(&pack).expect("读回"); + assert_eq!(manifest.files.len(), 1); + let file = &manifest.files[0]; + assert_eq!(file.path.as_deref(), Some("mods/jei.jar")); + assert_eq!(file.downloads.len(), 2); + assert_eq!(file.sha512().map(str::len), Some(128)); + assert_eq!( + file.sha1(), + Some(sha1.as_str()), + "本地实测的 sha1 要覆盖目录给的值" + ); + assert_eq!(file.size, Some(13), "字节数按磁盘实测"); + assert_eq!(manifest.override_files().count(), 2, "另外两个文件仍然内联"); +} + +#[test] +fn a_hit_without_sha512_is_inlined_with_a_reason() { + let root = fabric_instance("export-no-sha512"); + let (sha1, _) = digests(&root, "mods/jei.jar"); + let mut hashes = BTreeMap::new(); + hashes.insert("sha1".to_string(), sha1.clone()); + let catalog = StubCatalog::default().with_modrinth( + &sha1, + RemoteHit::modrinth( + vec!["https://cdn.modrinth.com/data/x/jei.jar".into()], + hashes, + None, + ), + ); + let target = root.with_file_name("no-sha512.mrpack"); + let report = + export_instance(&ExportRequest::new(&root, &target, &MODRINTH).with_catalog(&catalog)) + .expect("导出"); + + let entry = report + .files + .iter() + .find(|file| file.path == "mods/jei.jar") + .expect("jei"); + assert_eq!(entry.class, FileClass::Inline); + assert_eq!(entry.reason, FileReason::MissingSha512); + assert_eq!(report.remote_count(), 0); +} + +#[test] +fn a_curseforge_only_hit_cannot_be_written_into_an_mrpack() { + let root = fabric_instance("export-curse-only"); + let (_, value) = digests(&root, "mods/jei.jar"); + let catalog = + StubCatalog::default().with_curse(value, RemoteHit::curseforge(238_222, 5_102_025)); + let target = root.with_file_name("curse-only.mrpack"); + let report = + export_instance(&ExportRequest::new(&root, &target, &MODRINTH).with_catalog(&catalog)) + .expect("导出"); + + let entry = report + .files + .iter() + .find(|file| file.path == "mods/jei.jar") + .expect("jei"); + assert_eq!(entry.reason, FileReason::CurseOnlyMatch); + assert_eq!(entry.class, FileClass::Inline); +} + +#[test] +fn curseforge_export_writes_only_known_project_and_file_ids() { + let root = fabric_instance("export-cf"); + let (_, value) = digests(&root, "mods/jei.jar"); + let catalog = + StubCatalog::default().with_curse(value, RemoteHit::curseforge(238_222, 5_102_025)); + let target = root.with_file_name("pack.zip"); + let report = + export_instance(&ExportRequest::new(&root, &target, &CURSEFORGE).with_catalog(&catalog)) + .expect("导出"); + + assert_eq!(report.format, "curseforge"); + let reasons: Vec<(String, FileReason)> = report + .files + .iter() + .map(|file| (file.path.clone(), file.reason)) + .collect(); + assert_eq!( + reasons, + vec![ + ("config/known.toml".to_string(), FileReason::NoRemoteMatch), + ( + "mods/jei.jar".to_string(), + FileReason::CurseForgeFingerprint + ), + ( + "mods/off.jar.disabled".to_string(), + FileReason::DisabledNotExpressible + ), + ] + ); + + let pack = PackArchive::open_default(&target).expect("打开"); + let manifest = CURSEFORGE.read(&pack).expect("读回 CF 清单"); + assert_eq!(manifest.files.len(), 1, "files[] 只写能确定 id 的项"); + assert_eq!(manifest.files[0].project_id, Some(238_222)); + assert_eq!(manifest.files[0].file_id, Some(5_102_025)); + let names = entry_names(&target); + assert!(names.contains(&"overrides/mods/off.jar.disabled".to_string())); + assert!(names.contains(&"overrides/config/known.toml".to_string())); +} + +#[test] +fn curseforge_modloaders_use_the_official_id_shape() { + let root = neoforge_instance("export-cf-neo"); + let target = root.with_file_name("neo.zip"); + export_instance(&ExportRequest::new(&root, &target, &CURSEFORGE)).expect("导出"); + let pack = PackArchive::open_default(&target).expect("打开"); + let manifest = pack + .read_json("manifest.json") + .expect("读清单") + .expect("有清单"); + assert_eq!(manifest["minecraft"]["version"], "1.20.1"); + assert_eq!( + manifest["minecraft"]["modLoaders"][0]["id"], "neoforge-1.20.1-47.1.106", + "CF 官方导出在 1.20.1 上把 MC 版本拼回 NeoForge 版本号" + ); + assert_eq!(manifest["minecraft"]["modLoaders"][0]["primary"], true); + + let root = fabric_instance("export-cf-fabric"); + let target = root.with_file_name("fabric.zip"); + export_instance(&ExportRequest::new(&root, &target, &CURSEFORGE)).expect("导出"); + let pack = PackArchive::open_default(&target).expect("打开"); + let manifest = pack + .read_json("manifest.json") + .expect("读清单") + .expect("有清单"); + assert_eq!( + manifest["minecraft"]["modLoaders"][0]["id"], + "fabric-0.15.11" + ); + assert_eq!(manifest["overrides"], "overrides"); +} + +#[test] +fn the_sentinel_fingerprint_never_reaches_the_catalog() { + let root = fabric_instance("export-sentinel"); + let (locals, _) = scan_instance(&root, &defaults()); + let local = locals + .iter() + .find(|file| file.path == "mods/jei.jar") + .expect("jei"); + let catalog = StubCatalog::default() + .with_curse(fingerprint::SENTINEL, RemoteHit::curseforge(1, 2)) + .with_curse(12345, RemoteHit::curseforge(1, 2)); + + let (reason, hit) = classify_with(local, &catalog, true, Some(fingerprint::SENTINEL)); + assert_eq!(reason, FileReason::NoRemoteMatch); + assert!(hit.is_none()); + assert!( + catalog.curse_calls().is_empty(), + "哨兵值必须短路，不能拿去查表（HMCL issue #4597 的误命中）" + ); + + // 对照：真实指纹会去查表。 + let (reason, hit) = classify_with(local, &catalog, true, Some(12345)); + assert_eq!(catalog.curse_calls(), vec![12345]); + assert_eq!(reason, FileReason::CurseForgeFingerprint, "塞了 id 就命中"); + assert!(hit.is_some()); +} + +#[test] +fn a_disabled_file_is_still_disabled_after_a_round_trip_through_the_package() { + // 任务要求的那条：禁用文件导出后仍能被"重新导入"且保持禁用。 + // 本轮没有 M111 的导入器（M111 未合并），所以"重新导入"= 把包里的 overrides 解出来 + + // 重新扫一遍实例目录：扫出来的 disabled 位必须是 true。 + let root = fabric_instance("export-disabled"); + let target = root.with_file_name("disabled.mrpack"); + export_instance(&ExportRequest::new(&root, &target, &MODRINTH)).expect("导出"); + + let again = temp_root("export-disabled-reimport"); + let file = std::fs::File::open(&target).expect("打开包"); + let mut archive = zip::ZipArchive::new(file).expect("读 zip"); + for index in 0..archive.len() { + let mut entry = archive.by_index(index).expect("条目"); + let name = entry.name().expect("条目名").to_string(); + let Some(relative) = name.strip_prefix("overrides/") else { + continue; + }; + let mut bytes = Vec::new(); + entry.read_to_end(&mut bytes).expect("读条目内容"); + write_file(&again.join(relative), &bytes); + } + + let (locals, skipped) = scan_instance(&again, &defaults()); + assert!(skipped.is_empty(), "{skipped:?}"); + let disabled: Vec<&str> = locals + .iter() + .filter(|file| file.disabled) + .map(|file| file.path.as_str()) + .collect(); + assert_eq!(disabled, vec!["mods/off.jar.disabled"]); + assert!(is_disabled_path("mods/off.jar.disabled.old")); + assert!( + !is_disabled_path("mods/off.jar.old"), + "`.old` 只是旧残留，不是禁用" + ); +} + +#[test] +fn a_file_bigger_than_u32_is_a_named_limits_error() { + // 真造一个 4 GiB 文件不现实：直接测格式层的那条闸（它是唯一写 `fileSize` 的地方）。 + let mut manifest = PackManifest::new("超大文件"); + manifest.version = Some("1.0.0".to_string()); + manifest.minecraft = Some("1.20.1".to_string()); + let mut hashes = BTreeMap::new(); + hashes.insert("sha512".to_string(), "b".repeat(128)); + manifest.files.push(PackFile { + path: Some("mods/huge.jar".to_string()), + hashes, + downloads: vec!["https://cdn.modrinth.com/data/x/huge.jar".to_string()], + size: Some(u64::from(u32::MAX) + 1), + ..PackFile::default() + }); + + let error = MODRINTH.render(&manifest).expect_err("超限必须报错"); + assert_eq!(error.kind(), PackErrorKind::Limits); + assert!(error.message().contains("fileSize"), "{error}"); +} + +#[test] +fn content_roots_can_be_extended_without_touching_the_pipeline() { + // 「社区标准的扩展性」的最小证明：加一个目录不用改管线。 + let root = fabric_instance("export-extra-root"); + write_file(&root.join("custom/extra.txt"), b"extra content\n"); + let target = root.with_file_name("extra.mrpack"); + let mut roots = defaults(); + roots.push("custom".to_string()); + let report = + export_instance(&ExportRequest::new(&root, &target, &MODRINTH).with_content_roots(roots)) + .expect("导出"); + assert!(report + .files + .iter() + .any(|file| file.path == "custom/extra.txt")); + let pack = PackArchive::open_default(&target).expect("打开"); + assert!(pack.has_entry("overrides/custom/extra.txt")); +} diff --git a/crates/core/src/addon/pack/tests/export_roundtrip.rs b/crates/core/src/addon/pack/tests/export_roundtrip.rs new file mode 100644 index 0000000..fb28874 --- /dev/null +++ b/crates/core/src/addon/pack/tests/export_roundtrip.rs @@ -0,0 +1,280 @@ +//! 往返保真（M112）：用 M110 的三种格式夹具做「读出来 → 摆成实例 → 导出 → 再读」。 +//! +//! # 为什么不是 `import_pack → export → import_pack` +//! +//! M111 的导入管线**还没合并进本分支**（它在复审中）。所以这里的"导入"是 M110 的 +//! `PackFormat::read` + 一个**形状与 M111 导入产物一致**的实例目录（`mods/`、`config/`、 +//! `versions//.json`）。真端到端欠账在 M112 报告里登记：M111 合并后要补一条 +//! `import_pack → export → import_pack`。 +//! +//! # 允许的差异（逐条显式列出，别让后来人以为是 bug） +//! +//! | 方向 | 差异 | 原因 | +//! |------|------|------| +//! | CF → mrpack | `files[]` 的 `projectID/fileID` 条目全丢 | CF 的 `files[]` **没有路径**，磁盘上无法复原成文件；导出侧只能看到磁盘，看不见"清单里说该有但没落地"的条目 | +//! | CF → mrpack | `author` / `minecraft.recommendedRam` 等扩展字段丢 | mrpack 没有这些字段（`extra` 不跨格式搬） | +//! | mrpack → mrpack | 认不出的 dependency 键（`parchment`）丢 | 快照只从版本 JSON 的库坐标来；`parchment` 没有对应库 | +//! | mrpack → mrpack | `files[]` 的条目要靠"文件真的在磁盘上"才会再写回去 | 读出来的模型里那两条是远程条目、本地没有字节；再导出时以磁盘为准 | +//! | MultiMC → mrpack | 非加载器组件（`org.lwjgl3`）不进 `dependencies` | 它不是加载器；mrpack 的 `dependencies` 只表达 loader | + +use std::path::{Path, PathBuf}; + +use super::export_harness::{ + defaults, modrinth_hit, write_layer, StubCatalog, FORGE_LAYER, VANILLA_LAYER, +}; +use super::{fixtures, temp_root, write_file}; +use crate::addon::export::snapshot::{InstanceSnapshot, SnapshotLoader}; +use crate::addon::export::{export_instance, ExportRequest}; +use crate::addon::pack::archive::PackArchive; +use crate::addon::pack::curseforge::CURSEFORGE; +use crate::addon::pack::format::PackFormat; +use crate::addon::pack::manifest::{PackManifest, PackSide}; +use crate::addon::pack::modrinth::MODRINTH; +use crate::addon::pack::multimc::MULTIMC; +use crate::addon::LoaderKind; + +/// 把夹具里的覆盖内容铺成一个实例目录（`/`），并写一份版本 JSON。 +fn instance_from(fixture_dir: &Path, manifest: &PackManifest, tag: &str) -> PathBuf { + let game = temp_root(tag).join("game"); + for (_, file) in manifest.override_files() { + let group = manifest + .overrides + .iter() + .find(|group| group.files.iter().any(|each| each.path == file.path)) + .expect("找到文件所属的组"); + let source = fixture_dir.join(&group.dir).join(&file.path); + let bytes = std::fs::read(&source).unwrap_or_else(|error| { + panic!("读夹具 {} 失败：{error}", source.display()); + }); + write_file(&game.join(&file.path), &bytes); + } + write_layer(&game, "1.20.1", VANILLA_LAYER); + game +} + +/// 一个「读出来的 mrpack」的文件集合，按路径排序（比较用）。 +fn override_paths(manifest: &PackManifest) -> Vec { + 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 = temp_root("rt-mmc-unpacked"); + for entry in pack.entries() { + let name = entry.name(); + let Some(relative) = name.strip_prefix("overrides/") else { + continue; + }; + let bytes = pack.read(name).expect("读条目").expect("有条目"); + write_file(&unpacked.join(relative), &bytes); + } + for relative in ["config/known.toml", "mods/broken.jar", "mods/example.jar"] { + assert!( + unpacked.join(relative).is_file(), + "{relative} 没进包（内容丢了）" + ); + } +} + +#[test] +fn a_same_format_export_is_still_allowed_and_byte_stable() { + // 反向对照：新管线不能把 M110 的同格式往返弄坏（r1 明确要保住的能力）。 + let fixture = fixtures::curseforge("rt-same-cf"); + let pack = PackArchive::open_default(&fixture.zip).expect("打开 CF 夹具"); + let original = CURSEFORGE.read(&pack).expect("读 CF 清单"); + let game = instance_from(&fixture.dir, &original, "rt-same-cf-game"); + write_layer(&game, "1.20.1-forge-47.2.0", FORGE_LAYER); + + let target = game.with_file_name("same.zip"); + export_instance( + &ExportRequest::new(&game, &target, &CURSEFORGE) + .with_name(original.name.clone()) + .with_version(original.version.clone().unwrap_or_default()) + .with_version_id("1.20.1-forge-47.2.0"), + ) + .expect("导出"); + let pack = PackArchive::open_default(&target).expect("打开导出结果"); + let again = CURSEFORGE.read(&pack).expect("再读回来"); + assert_eq!(again.name, original.name); + assert_eq!(again.minecraft, original.minecraft); + assert_eq!( + again + .loader(LoaderKind::Forge) + .and_then(|loader| loader.version.clone()), + Some("47.2.0".to_string()) + ); + assert_eq!(override_paths(&again), override_paths(&original)); + assert_eq!( + again + .overrides_for(PackSide::Both) + .map(|group| group.dir.clone()), + Some("overrides".to_string()) + ); +} diff --git a/crates/core/src/addon/pack/tests/extend.rs b/crates/core/src/addon/pack/tests/extend.rs new file mode 100644 index 0000000..f7554ab --- /dev/null +++ b/crates/core/src/addon/pack/tests/extend.rs @@ -0,0 +1,172 @@ +//! 扩展点判据：加一个假格式（**一个文件、一条注册**）就能被探测与读写， +//! 且不碰模型、不碰 CurseForge / Modrinth / MultiMC 任何一行。 +//! +//! 这里刻意不写"文档说它可扩展"，而是真的实现一个 `toy.json` 格式走完整条链： +//! 注册 → 探测 → 读 → 渲染 → 写 → 再读。 + +use serde_json::{json, Value}; + +use super::{temp_root, write_file, write_zip}; +use crate::addon::pack::archive::PackArchive; +use crate::addon::pack::curseforge::CURSEFORGE; +use crate::addon::pack::error::{PackError, PackErrorKind, PackResult}; +use crate::addon::pack::format::{PackFormat, PackPayload, PackRegistry}; +use crate::addon::pack::manifest::{PackFile, PackManifest}; + +/// 测试专用假格式：`toy.json` = `{"name": …, "minecraft": …, "mods": ["mods/a.jar"]}`。 +/// +/// 全部实现加起来不到 40 行——这就是"社区加一个新格式"的代价上限。 +#[derive(Debug)] +struct ToyFormat; + +/// 注册表要的是 `&'static dyn PackFormat`，所以用 `static`。 +static TOY: ToyFormat = ToyFormat; + +impl PackFormat for ToyFormat { + fn id(&self) -> &'static str { + "toy" + } + + fn label(&self) -> &'static str { + "Toy（测试专用假格式）" + } + + fn metadata_entry(&self) -> Option<&'static str> { + Some("toy.json") + } + + fn detect(&self, pack: &PackArchive) -> PackResult> { + 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) -> std::path::PathBuf { + let dir = temp_root(tag).join("toy"); + write_file( + &dir.join("toy.json"), + br#"{"name":"Toy Pack","minecraft":"1.21","mods":["mods/a.jar","mods/b.jar"]}"#, + ); + dir +} + +#[test] +fn a_new_format_needs_one_registration_line() { + let dir = toy_pack("extend-register"); + let pack = PackArchive::open_default(&dir).expect("打开 toy 包"); + + // ① 没注册时：内置三格式都不认它（证明它不是"顺手"被认出来的）。 + let error = PackRegistry::builtin() + .detect(&pack) + .expect_err("内置格式不该认领 toy 包"); + assert_eq!(error.kind(), PackErrorKind::Unsupported); + + // ② 加一行注册。 + let registry = PackRegistry::builtin().with(&TOY); + + // ③ 探测得到。 + let matched = registry.detect(&pack).expect("注册后就该探测到"); + assert_eq!(matched.format().id(), "toy"); + assert!(!matched.is_ambiguous()); + + // ④ 读得到。 + let manifest = matched.format().read(&pack).expect("读 toy 清单"); + assert_eq!(manifest.name, "Toy Pack"); + assert_eq!(manifest.minecraft.as_deref(), Some("1.21")); + assert_eq!(manifest.files.len(), 2); + + // ⑤ 渲染 + 写（默认 write 实现直接用 metadata_entry + render，不用重写一遍 zip 逻辑）。 + let rendered = matched.format().render(&manifest).expect("渲染 toy 清单"); + assert!(rendered.contains("Toy Pack")); + + let target = dir.with_file_name("toy.zip"); + matched + .format() + .write(&manifest, PackPayload::metadata_only(), &target) + .expect("导出 toy 包"); + + // ⑥ 再读回来必须一样。 + let written = PackArchive::open_default(&target).expect("打开导出的 toy 包"); + let reread = matched.format().read(&written).expect("再读 toy 清单"); + assert_eq!(reread, manifest); +} + +#[test] +fn appending_a_format_never_steals_existing_packs() { + // 同一份包同时有 CF 清单与 toy 清单。 + let root = temp_root("extend-priority"); + let target = root.join("both.zip"); + write_zip( + &target, + &[ + ( + "manifest.json", + &br#"{"manifestType":"minecraftModpack","manifestVersion":1, + "name":"real cf pack","minecraft":{"version":"1.20.1"},"files":[]}"#[..], + ), + ( + "toy.json", + &br#"{"name":"Toy shadow","minecraft":"1.21","mods":[]}"#[..], + ), + ], + ); + let pack = PackArchive::open_default(&target).expect("打开包"); + + // 追加到末尾 = 最低优先级：老包的行为不变，但歧义要看得见。 + let appended = PackRegistry::builtin().with(&TOY); + let matched = appended.detect(&pack).expect("探测"); + assert_eq!(matched.format().id(), "curseforge"); + assert_eq!(matched.also_matched().to_vec(), vec!["toy"]); + + // 反过来排到最前，就该 toy 赢——注册顺序就是优先级。 + let front = PackRegistry::empty().with(&TOY).with(&CURSEFORGE); + let matched = front.detect(&pack).expect("探测"); + assert_eq!(matched.format().id(), "toy"); + assert_eq!(matched.also_matched().to_vec(), vec!["curseforge"]); +} diff --git a/crates/core/src/addon/pack/tests/fixtures.rs b/crates/core/src/addon/pack/tests/fixtures.rs new file mode 100644 index 0000000..565f4df --- /dev/null +++ b/crates/core/src/addon/pack/tests/fixtures.rs @@ -0,0 +1,185 @@ +//! 本地夹具：CurseForge / Modrinth / MultiMC 三种格式各一个最小但**形状真实**的包。 +//! +//! # 来源声明（不许把"看起来像"当真实） +//! +//! | 夹具 | 来源 | 说明 | +//! |------|------|------| +//! | [`curseforge`] | **手造** | 字段取自 analyse/05 §2.2（HMCL `CurseManifest` / `CurseManifestFile`）；内容与数值是编的 | +//! | [`modrinth`] | **手造** | 字段取自 analyse/05 §2.3（HMCL `ModrinthManifest`）；`hashes` 里的摘要是**形状正确的占位值**，不对应任何真实文件 | +//! | [`multimc`] | **手造** | 字段取自 analyse/05 §2.6（HMCL `MultiMCModpackProvider`）；组件表比真实 Prism 实例小得多 | +//! +//! **没有一个来自真实导出**：本任务环境离线、仓库里也没有真实整合包样本。真实导出物的字段 +//! 偏移风险只能等 M111/M115 拿到真包后回收（报告里已登记这条欠账）。 +//! +//! # 刻意造的坏文件（导入器不许崩、也不许悄悄丢掉） +//! +//! - CF：`overrides/config/broken.toml` —— 截断的 TOML（引号未闭合、段落未收尾）； +//! - mrpack：`overrides/mods/half.jar` —— 只有半个 zip 头； +//! - MultiMC：`.minecraft/mods/broken.jar` —— 零字节。 +//! +//! 三种损坏都是**覆盖目录里的文件**：它们没有清单声明的摘要可比，读包时只能如实记下实际 +//! SHA-1/大小（三方合并的 base 侧就是这么来的），谁想"校验并修掉"必须另做判断。 + +use std::path::PathBuf; + +use super::{temp_root, write_file, zip_dir}; + +/// 一个既有源目录（可当导出 payload）又有打好的 zip 的夹具。 +pub(crate) struct Fixture { + /// 源目录（zip 的内容来源，也是 `PackPayload::from_root` 的根）。 + pub dir: PathBuf, + /// 打好的包。 + pub zip: PathBuf, +} + +/// CF 夹具的包名。 +pub(crate) const CF_NAME: &str = "M110 手造 CurseForge 包"; +/// CF 夹具里那个坏文件的内容。 +pub(crate) const CF_BROKEN: &[u8] = b"broken = \"unterminated\n[section\n"; +/// mrpack 夹具的包名。 +pub(crate) const MR_NAME: &str = "M110 手造 Modrinth 包"; +/// mrpack 夹具里那个半截 jar 的内容。 +pub(crate) const MR_HALF_JAR: &[u8] = b"PK\x03\x04half"; +/// MultiMC 夹具的实例名（写在 `instance.cfg`）。 +pub(crate) const MMC_NAME: &str = "M110 手造 MultiMC 实例"; + +/// 手造的 SHA-1 占位值（40 位十六进制）。 +const FAKE_SHA1: &str = "0123456789abcdef0123456789abcdef01234567"; +/// 手造的 SHA-256 占位值（64 位十六进制）。 +const FAKE_SHA256: &str = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"; +/// 手造的 SHA-512 占位值（128 位十六进制）。 +const FAKE_SHA512: &str = concat!( + "0123456789abcdef", + "0123456789abcdef", + "0123456789abcdef", + "0123456789abcdef", + "0123456789abcdef", + "0123456789abcdef", + "0123456789abcdef", + "0123456789abcdef" +); + +const CF_MANIFEST: &str = r#"{ + "manifestType": "minecraftModpack", + "manifestVersion": 1, + "name": "M110 手造 CurseForge 包", + "version": "1.0.0", + "author": "AskaEth", + "overrides": "overrides", + "minecraft": { + "version": "1.20.1", + "modLoaders": [{"id": "forge-47.2.0", "primary": true}], + "recommendedRam": 4096 + }, + "files": [ + {"projectID": 238222, "fileID": 5102025, "required": true}, + {"projectID": 306612, "fileID": 4587454, "required": false} + ], + "customCommunityField": {"since": 2, "note": "社区新增字段，必须原样回写"} +} +"#; + +fn mrpack_index() -> String { + format!( + r#"{{ + "game": "minecraft", + "formatVersion": 1, + "versionId": "2.0.0", + "name": "{MR_NAME}", + "summary": "手造夹具：只验证形状与边界，不是真实导出", + "files": [ + {{ + "path": "mods/jei.jar", + "hashes": {{"sha1": "{FAKE_SHA1}", "sha256": "{FAKE_SHA256}", "sha512": "{FAKE_SHA512}"}}, + "env": {{"client": "required", "server": "unsupported"}}, + "downloads": ["https://cdn.modrinth.com/data/AANobbMI/versions/abc/jei.jar"], + "fileSize": 1234567, + "customFileField": "社区新增字段" + }}, + {{ + "path": "mods/optional.jar", + "hashes": {{"sha1": "{FAKE_SHA1}", "sha512": "{FAKE_SHA512}"}}, + "env": {{"client": "optional", "server": "unsupported"}}, + "downloads": ["https://cdn.modrinth.com/data/opt/versions/x/optional.jar"], + "fileSize": 11 + }} + ], + "dependencies": {{ + "minecraft": "1.20.1", + "fabric-loader": "0.15.11", + "parchment": "2023.09.03" + }}, + "customPackField": [1, 2, 3] +}} +"# + ) +} + +const MMC_PACK: &str = r#"{ + "formatVersion": 1, + "components": [ + {"uid": "net.minecraft", "version": "1.20.1", "important": true, "cachedName": "1.20.1"}, + {"uid": "net.fabricmc.fabric-loader", "version": "0.15.11"}, + {"uid": "org.lwjgl3", "version": "3.3.2"} + ], + "customComponentGraphField": true +} +"#; + +const MMC_INSTANCE: &str = "InstanceType=OneSix\nname=M110 手造 MultiMC 实例\niconKey=default\n"; + +/// CurseForge 夹具（`manifest.json` + `overrides/`，含一个截断的 TOML）。 +pub(crate) fn curseforge(tag: &str) -> Fixture { + let root = temp_root(tag); + let dir = root.join("src"); + write_file(&dir.join("manifest.json"), CF_MANIFEST.as_bytes()); + write_file( + &dir.join("overrides/mods/example.jar"), + b"PK\x03\x04 hand-made jar stub", + ); + write_file( + &dir.join("overrides/config/known.toml"), + b"key = \"value\"\n", + ); + write_file(&dir.join("overrides/config/broken.toml"), CF_BROKEN); + let zip = root.join("pack.zip"); + zip_dir(&dir, &zip); + Fixture { dir, zip } +} + +/// Modrinth 夹具（`modrinth.index.json` + 三个覆盖目录，含一个半截 jar）。 +pub(crate) fn modrinth(tag: &str) -> Fixture { + let root = temp_root(tag); + let dir = root.join("src"); + write_file(&dir.join("modrinth.index.json"), mrpack_index().as_bytes()); + write_file(&dir.join("overrides/mods/half.jar"), MR_HALF_JAR); + write_file(&dir.join("overrides/config/known.toml"), b"shared = true\n"); + write_file( + &dir.join("client-overrides/config/client-only.toml"), + b"client = true\n", + ); + write_file( + &dir.join("server-overrides/config/server.properties"), + b"online-mode=true\n", + ); + let zip = root.join("pack.mrpack"); + zip_dir(&dir, &zip); + Fixture { dir, zip } +} + +/// MultiMC 夹具：**目录形式**（真实形态就是实例目录，不是 zip），含一个零字节 jar。 +pub(crate) fn multimc(tag: &str) -> PathBuf { + let root = temp_root(tag).join("instance"); + write_file(&root.join("mmc-pack.json"), MMC_PACK.as_bytes()); + write_file(&root.join("instance.cfg"), MMC_INSTANCE.as_bytes()); + write_file( + &root.join(".minecraft/mods/example.jar"), + b"PK\x03\x04 hand-made jar stub", + ); + write_file(&root.join(".minecraft/mods/broken.jar"), b""); + write_file( + &root.join(".minecraft/config/known.toml"), + b"key = \"value\"\n", + ); + root +} diff --git a/crates/core/src/addon/pack/tests/mod.rs b/crates/core/src/addon/pack/tests/mod.rs new file mode 100644 index 0000000..d4458ee --- /dev/null +++ b/crates/core/src/addon/pack/tests/mod.rs @@ -0,0 +1,107 @@ +//! `addon::pack` 的单元测试：夹具读回、未知字段往返、探测优先级、扩展点、恶意样本。 +//! +//! **全部离线**：没有网络调用，也没有真实整合包样本（见 `fixtures` 的来源声明）。 + +mod detect; +mod export; +mod export_harness; +mod export_pipeline; +mod export_roundtrip; +mod extend; +mod fixtures; +mod model; +mod roundtrip; +mod safety; +mod unknown_fields; + +use std::fs::File; +use std::io::Write; +use std::path::{Path, PathBuf}; +use std::sync::atomic::{AtomicU64, Ordering}; + +/// 本次进程内唯一的临时根目录（沿用仓库既有约定：不引 `tempfile`）。 +pub(crate) fn temp_root(tag: &str) -> PathBuf { + static COUNTER: AtomicU64 = AtomicU64::new(0); + let unique = COUNTER.fetch_add(1, Ordering::Relaxed); + std::env::temp_dir().join(format!("ull-pack-{}-{tag}-{unique}", std::process::id())) +} + +/// 写一个夹具文件（自动建父目录）。 +pub(crate) fn write_file(path: &Path, bytes: &[u8]) { + if let Some(parent) = path.parent() { + std::fs::create_dir_all(parent).expect("建夹具目录"); + } + std::fs::write(path, bytes).expect("写夹具文件"); +} + +/// 把一个目录打成 zip（`Stored` 压缩，方便测试直接改字节）。 +pub(crate) fn zip_dir(source: &Path, target: &Path) { + if let Some(parent) = target.parent() { + std::fs::create_dir_all(parent).expect("建 zip 目录"); + } + let file = File::create(target).expect("建 zip"); + let mut writer = zip::ZipWriter::new(file); + let options = + zip::write::SimpleFileOptions::default().compression_method(zip::CompressionMethod::Stored); + let mut pending = vec![PathBuf::new()]; + while let Some(relative) = pending.pop() { + let dir = source.join(&relative); + let mut children: Vec<_> = std::fs::read_dir(&dir) + .expect("读夹具目录") + .collect::, _>>() + .expect("目录项"); + children.sort_by_key(std::fs::DirEntry::file_name); + for child in children { + let relative = relative.join(child.file_name()); + if child.file_type().expect("夹具类型").is_dir() { + pending.push(relative); + continue; + } + let bytes = std::fs::read(child.path()).expect("读夹具文件"); + let entry = relative.to_string_lossy().replace('\\', "/"); + writer.start_file(entry, options).expect("写 zip 条目"); + writer.write_all(&bytes).expect("写 zip 内容"); + } + } + writer.finish().expect("收尾 zip"); +} + +/// 用一张显式条目表打 zip（恶意样本用）。 +pub(crate) fn write_zip(target: &Path, entries: &[(&str, &[u8])]) { + if let Some(parent) = target.parent() { + std::fs::create_dir_all(parent).expect("建 zip 目录"); + } + let file = File::create(target).expect("建 zip"); + let mut writer = zip::ZipWriter::new(file); + let options = + zip::write::SimpleFileOptions::default().compression_method(zip::CompressionMethod::Stored); + for (name, bytes) in entries { + writer.start_file(*name, options).expect("写 zip 条目"); + writer.write_all(bytes).expect("写 zip 内容"); + } + writer.finish().expect("收尾 zip"); +} + +/// 打一个带**符号链接条目**的 zip（`S_IFLNK` + 目标当内容，与真实恶意包同构）。 +pub(crate) fn write_zip_with_symlink( + target: &Path, + entries: &[(&str, &[u8])], + link_name: &str, + link_target: &str, +) { + if let Some(parent) = target.parent() { + std::fs::create_dir_all(parent).expect("建 zip 目录"); + } + let file = File::create(target).expect("建 zip"); + let mut writer = zip::ZipWriter::new(file); + let options = + zip::write::SimpleFileOptions::default().compression_method(zip::CompressionMethod::Stored); + for (name, bytes) in entries { + writer.start_file(*name, options).expect("写 zip 条目"); + writer.write_all(bytes).expect("写 zip 内容"); + } + writer + .add_symlink(link_name, link_target, options) + .expect("写符号链接条目"); + writer.finish().expect("收尾 zip"); +} diff --git a/crates/core/src/addon/pack/tests/model.rs b/crates/core/src/addon/pack/tests/model.rs new file mode 100644 index 0000000..ad229a2 --- /dev/null +++ b/crates/core/src/addon/pack/tests/model.rs @@ -0,0 +1,111 @@ +//! 模型级辅助与读取预算：r1 p2-2（跨侧重名）与 p3-4（批量读取的累计限额）。 + +use super::fixtures; +use crate::addon::pack::archive::{PackArchive, ReadBudget}; +use crate::addon::pack::error::PackErrorKind; +use crate::addon::pack::manifest::{OverrideFile, PackManifest, PackOverrides, PackSide}; + +fn file(path: &str, sha1: &str, size: u64) -> OverrideFile { + OverrideFile { + path: path.to_string(), + sha1: sha1.to_string(), + size, + } +} + +#[test] +fn duplicate_override_paths_counts_across_sides_not_per_side() { + // r1 p2-2：mrpack 的真实冲突是 `overrides`(Both) 与 `client-overrides`(Client) 撞同一路径， + // 按 `(side, path)` 计数时两侧键天然不同 ⇒ 永远返回空表。 + let mut both = PackOverrides::new("overrides", PackSide::Both); + both.files.push(file("config/x.toml", "a", 1)); + both.files.push(file("config/only-both.toml", "b", 1)); + let mut client = PackOverrides::new("client-overrides", PackSide::Client); + client.files.push(file("config/x.toml", "c", 2)); + let mut server = PackOverrides::new("server-overrides", PackSide::Server); + server.files.push(file("config/only-server.toml", "d", 3)); + let manifest = PackManifest { + overrides: vec![both, client, server], + ..PackManifest::default() + }; + + assert_eq!( + manifest.duplicate_override_paths(), + vec![( + "config/x.toml".to_string(), + vec![PackSide::Both, PackSide::Client], + 2 + )], + "只报真正撞车的路径，并给出涉及的侧与条目份数" + ); +} + +#[test] +fn duplicate_override_paths_still_reports_two_groups_on_the_same_side() { + // r2 p2-2：上一版按侧去重，把这半能力换掉了 —— 两个 Both 组撞同一路径实测返回 `[]`。 + // 现在判据是「侧数 > 1 || 条份数 > 侧数」，两种冲突同时报得出来。 + let mut first = PackOverrides::new("overrides", PackSide::Both); + first.files.push(file("config/x.toml", "a", 1)); + let mut second = PackOverrides::new("extra-overrides", PackSide::Both); + second.files.push(file("config/x.toml", "b", 2)); + let manifest = PackManifest { + overrides: vec![first, second], + ..PackManifest::default() + }; + assert_eq!( + manifest.duplicate_override_paths(), + vec![("config/x.toml".to_string(), vec![PackSide::Both], 2)], + "同侧两个组撞同一路径必须报（侧集合只有一个，份数是 2）" + ); +} + +#[test] +fn duplicate_override_paths_reports_the_same_path_twice_inside_one_group() { + // 同侧撞车的另一种形态：一个组里同一路径列了两次（模型被合并出来时会出现）。 + let mut group = PackOverrides::new("overrides", PackSide::Both); + group.files.push(file("config/x.toml", "a", 1)); + group.files.push(file("config/x.toml", "b", 2)); + let manifest = PackManifest { + overrides: vec![group], + ..PackManifest::default() + }; + assert_eq!( + manifest.duplicate_override_paths(), + vec![("config/x.toml".to_string(), vec![PackSide::Both], 2)] + ); +} + +#[test] +fn duplicate_override_paths_is_empty_when_nothing_collides() { + let mut both = PackOverrides::new("overrides", PackSide::Both); + both.files.push(file("config/a.toml", "a", 1)); + let mut client = PackOverrides::new("client-overrides", PackSide::Client); + client.files.push(file("config/b.toml", "b", 1)); + let manifest = PackManifest { + overrides: vec![both, client], + ..PackManifest::default() + }; + assert!(manifest.duplicate_override_paths().is_empty()); +} + +#[test] +fn a_batch_scan_spends_one_cumulative_budget() { + // r1 p3-4：打开阶段只能看声明大小；批量读取（override_files）必须按**实际字节**累计扣减， + // 否则"很多条各自合规"累起来就能绕过 `max_uncompressed_bytes`（CPU/时间 DoS）。 + let fixture = fixtures::modrinth("budget"); + let pack = PackArchive::open_default(&fixture.zip).expect("打开 mrpack 夹具"); + + let generous = ReadBudget::new(1024 * 1024); + let files = pack + .override_files_with("overrides", &generous) + .expect("预算够时必须成功"); + assert_eq!(files.len(), 2); + + // 预算只有 4 字节：第一个文件（config/known.toml，15 字节）就该把预算吃穿。 + let tight = ReadBudget::new(4); + let error = pack + .override_files_with("overrides", &tight) + .expect_err("累计预算必须生效"); + assert_eq!(error.kind(), PackErrorKind::Limits, "{error}"); + assert_eq!(tight.remaining(), 0, "失败后预算不该被退回"); +} diff --git a/crates/core/src/addon/pack/tests/roundtrip.rs b/crates/core/src/addon/pack/tests/roundtrip.rs new file mode 100644 index 0000000..6e891ce --- /dev/null +++ b/crates/core/src/addon/pack/tests/roundtrip.rs @@ -0,0 +1,306 @@ +//! 读回模型 + "导出后再读"的往返一致性：**未知字段不丢**就在这些断言里被钉住。 + +use serde_json::json; + +use super::fixtures; +use crate::addon::pack::archive::PackArchive; +use crate::addon::pack::curseforge::CURSEFORGE; +use crate::addon::pack::error::PackErrorKind; +use crate::addon::pack::format::{PackFormat, PackPayload, PackRegistry}; +use crate::addon::pack::manifest::{EnvSupport, PackManifest, PackSide}; +use crate::addon::pack::modrinth::MODRINTH; +use crate::addon::pack::multimc::MULTIMC; +use crate::addon::LoaderKind; +use crate::download::{verify, HashAlgo}; + +fn sha1_hex(bytes: &[u8]) -> String { + verify::digest_bytes(HashAlgo::Sha1, bytes) +} + +#[test] +fn curseforge_reads_into_model() { + let fixture = fixtures::curseforge("cf-read"); + let pack = PackArchive::open_default(&fixture.zip).expect("打开 CF 夹具"); + let manifest = CURSEFORGE.read(&pack).expect("读 CF 清单"); + + assert_eq!(manifest.name, fixtures::CF_NAME); + assert_eq!(manifest.version.as_deref(), Some("1.0.0")); + assert_eq!(manifest.author.as_deref(), Some("AskaEth")); + assert_eq!(manifest.summary, None, "CF 没有 summary 字段"); + assert_eq!(manifest.minecraft.as_deref(), Some("1.20.1")); + assert_eq!(manifest.game, None, "CF 没有 game 字段"); + assert_eq!(manifest.format_version, Some(1)); + + assert_eq!(manifest.loaders.len(), 1); + let loader = &manifest.loaders[0]; + assert_eq!(loader.raw, "forge-47.2.0"); + assert_eq!(loader.kind, Some(LoaderKind::Forge)); + assert_eq!(loader.version.as_deref(), Some("47.2.0")); + assert!(loader.primary, "primary=true 必须保住"); + + // CF 官方 files[] 没有路径/URL/摘要：模型如实记成 None，不猜。 + assert_eq!(manifest.files.len(), 2); + let required = &manifest.files[0]; + assert_eq!(required.project_id, Some(238222)); + assert_eq!(required.file_id, Some(5102025)); + assert_eq!(required.path, None); + assert_eq!(required.client, EnvSupport::Required); + assert_eq!(required.key(), "curseforge:238222:5102025"); + let optional = &manifest.files[1]; + assert_eq!( + optional.client, + EnvSupport::Optional, + "required=false → Optional" + ); + assert_eq!(optional.server, EnvSupport::Optional); + + // 覆盖目录：3 个文件，含那个刻意截断的 TOML（它没有清单摘要可比，只能记实测值）。 + assert_eq!(manifest.overrides.len(), 1); + let group = &manifest.overrides[0]; + assert_eq!(group.dir, "overrides"); + assert_eq!(group.side, PackSide::Both); + assert_eq!(group.files.len(), 3); + let broken = group.find("config/broken.toml").expect("坏文件也要进清单"); + assert_eq!(broken.size, fixtures::CF_BROKEN.len() as u64); + assert_eq!(broken.sha1, sha1_hex(fixtures::CF_BROKEN)); + + // 未知字段：顶层与 `minecraft` 对象各一处。 + assert_eq!(manifest.extra["customCommunityField"]["since"], json!(2)); + assert_eq!(manifest.minecraft_extra["recommendedRam"], json!(4096)); +} + +#[test] +fn curseforge_export_round_trips_unknown_fields() { + let fixture = fixtures::curseforge("cf-roundtrip"); + let pack = PackArchive::open_default(&fixture.zip).expect("打开 CF 夹具"); + let manifest = CURSEFORGE.read(&pack).expect("读 CF 清单"); + + let target = fixture.zip.with_file_name("rewritten.zip"); + CURSEFORGE + .write(&manifest, PackPayload::from_root(&fixture.dir), &target) + .expect("导出 CF 包"); + + let written = PackArchive::open_default(&target).expect("打开导出的 CF 包"); + let reread = CURSEFORGE.read(&written).expect("再读导出的 CF 包"); + assert_eq!(reread, manifest, "导出→再读必须逐字段相等（含未知字段）"); + assert_eq!( + reread.extra["customCommunityField"]["note"], + json!("社区新增字段，必须原样回写") + ); + assert_eq!(reread.minecraft_extra["recommendedRam"], json!(4096)); +} + +#[test] +fn modrinth_reads_into_model() { + let fixture = fixtures::modrinth("mr-read"); + let pack = PackArchive::open_default(&fixture.zip).expect("打开 mrpack 夹具"); + let manifest = MODRINTH.read(&pack).expect("读 mrpack 清单"); + + assert_eq!(manifest.name, fixtures::MR_NAME); + assert_eq!(manifest.version.as_deref(), Some("2.0.0")); + assert_eq!( + manifest.summary.as_deref(), + Some("手造夹具：只验证形状与边界，不是真实导出") + ); + assert_eq!(manifest.game.as_deref(), Some("minecraft")); + assert_eq!(manifest.minecraft.as_deref(), Some("1.20.1")); + assert_eq!(manifest.author, None, "mrpack 没有 author 字段"); + + // `dependencies` 里非 minecraft 的每条都成一条加载器依赖（认不出的也保留）。 + assert_eq!(manifest.loaders.len(), 2); + let fabric = manifest + .loader(LoaderKind::Fabric) + .expect("要认出 fabric-loader"); + assert_eq!(fabric.raw, "fabric-loader"); + assert_eq!(fabric.version.as_deref(), Some("0.15.11")); + assert!(fabric.primary); + let parchment = manifest + .loaders + .iter() + .find(|loader| loader.raw == "parchment") + .expect("社区键也要保留"); + assert_eq!(parchment.kind, None); + assert_eq!(parchment.version.as_deref(), Some("2023.09.03")); + + assert_eq!(manifest.files.len(), 2); + let jei = &manifest.files[0]; + assert_eq!(jei.path.as_deref(), Some("mods/jei.jar")); + assert_eq!(jei.size, Some(1_234_567)); + assert_eq!(jei.client, EnvSupport::Required); + assert_eq!(jei.server, EnvSupport::Unsupported); + assert_eq!(jei.downloads.len(), 1); + assert!(jei.hashes.contains_key("sha256"), "整张摘要表都要留着"); + assert!(jei.sha512().is_some()); + assert!(jei.key().starts_with("modrinth:")); + assert_eq!(jei.extra["customFileField"], json!("社区新增字段")); + let optional = &manifest.files[1]; + assert!(optional.client.is_optional(), "env.client=optional 要保住"); + + // 三个覆盖目录各成一侧。 + assert_eq!(manifest.overrides.len(), 3); + let both = manifest.overrides_for(PackSide::Both).expect("overrides"); + assert_eq!(both.files.len(), 2); + let client = manifest + .overrides_for(PackSide::Client) + .expect("client-overrides"); + assert_eq!(client.files.len(), 1); + let server = manifest + .overrides_for(PackSide::Server) + .expect("server-overrides"); + assert_eq!(server.files.len(), 1); + let half = both.find("mods/half.jar").expect("半截 jar 也要进清单"); + assert_eq!(half.size, fixtures::MR_HALF_JAR.len() as u64); + assert_eq!(half.sha1, sha1_hex(fixtures::MR_HALF_JAR)); + + assert_eq!(manifest.extra["customPackField"], json!([1, 2, 3])); +} + +#[test] +fn modrinth_export_round_trips_unknown_fields() { + let fixture = fixtures::modrinth("mr-roundtrip"); + let pack = PackArchive::open_default(&fixture.zip).expect("打开 mrpack 夹具"); + let manifest = MODRINTH.read(&pack).expect("读 mrpack 清单"); + + let target = fixture.zip.with_file_name("rewritten.mrpack"); + MODRINTH + .write(&manifest, PackPayload::from_root(&fixture.dir), &target) + .expect("导出 mrpack"); + + let written = PackArchive::open_default(&target).expect("打开导出的 mrpack"); + let reread = MODRINTH.read(&written).expect("再读导出的 mrpack"); + assert_eq!(reread, manifest, "导出→再读必须逐字段相等（含未知字段）"); + assert_eq!(reread.extra["customPackField"], json!([1, 2, 3])); +} + +#[test] +fn multimc_reads_instance_directory() { + let root = fixtures::multimc("mmc-read"); + let pack = PackArchive::open_default(&root).expect("打开 MultiMC 实例目录"); + assert!(pack.is_dir_source()); + let manifest = MULTIMC.read(&pack).expect("读 MultiMC 清单"); + + assert_eq!(manifest.name, fixtures::MMC_NAME, "包名来自 instance.cfg"); + assert_eq!(manifest.minecraft.as_deref(), Some("1.20.1")); + assert_eq!(manifest.game.as_deref(), Some("minecraft")); + assert_eq!(manifest.format_version, Some(1)); + assert_eq!(manifest.version, None, "MultiMC 的实例没有包版本"); + + let fabric = manifest + .loader(LoaderKind::Fabric) + .expect("组件 uid 要翻译成加载器"); + assert_eq!(fabric.raw, "net.fabricmc.fabric-loader"); + assert_eq!(fabric.version.as_deref(), Some("0.15.11")); + assert!(fabric.primary); + assert!( + manifest + .loaders + .iter() + .any(|loader| loader.raw == "org.lwjgl3"), + "认不出的组件也要保留" + ); + + assert!(manifest.files.is_empty(), "MultiMC 没有远端条目"); + let content = manifest + .overrides_for(PackSide::Both) + .expect(".minecraft 当覆盖目录"); + assert_eq!(content.dir, ".minecraft"); + let broken = content + .find("mods/broken.jar") + .expect("零字节 jar 也要进清单"); + assert_eq!(broken.size, 0); + assert_eq!(broken.sha1, sha1_hex(b"")); + assert_eq!(content.files.len(), 3); + assert_eq!(manifest.extra["customComponentGraphField"], json!(true)); +} + +#[test] +fn multimc_export_is_refused() { + let root = super::temp_root("mmc-write"); + let target = root.join("out.zip"); + let manifest = PackManifest::new("whatever"); + let error = MULTIMC + .write(&manifest, PackPayload::metadata_only(), &target) + .expect_err("MultiMC 格式不支持导出"); + assert_eq!(error.kind(), PackErrorKind::Unsupported); + assert!(!target.exists(), "拒绝导出时不该留下半个文件"); +} + +#[test] +fn registry_read_reports_matched_format() { + let fixture = fixtures::curseforge("registry-read"); + let pack = PackArchive::open_default(&fixture.zip).expect("打开 CF 夹具"); + let (format, manifest) = PackRegistry::builtin().read(&pack).expect("探测 + 读"); + assert_eq!(format.id(), "curseforge"); + assert_eq!(manifest.name, fixtures::CF_NAME); +} + +#[test] +fn curseforge_without_name_is_a_metadata_error() { + let root = super::temp_root("cf-noname"); + let target = root.join("nope.zip"); + super::write_zip( + &target, + &[( + "manifest.json", + &br#"{"manifestType":"minecraftModpack","minecraft":{"version":"1.20.1"}}"#[..], + )], + ); + let pack = PackArchive::open_default(&target).expect("zip 本身可读"); + assert_eq!( + CURSEFORGE.detect(&pack).expect("清单可读"), + Some("manifest.json"), + "形状对得上就该被探测到" + ); + let error = CURSEFORGE.read(&pack).expect_err("缺 name 必须报错"); + assert_eq!(error.kind(), PackErrorKind::Metadata); +} + +#[test] +fn disabled_entries_export_as_path_suffix_on_mrpack_and_required_false_on_curseforge() { + // 禁用位（M115 调研 §字段缺口 2 / §8.1）在两边的落法不同，且都不该靠"猜"： + // mrpack → `files[].path` 结尾 `.disabled`（官方导出的表达，**不是** env.client=optional： + // 后者只是"安装时可取消勾选"，装回来默认仍然启用 ⇒ 跨启动器不保真）； + // CF → 没有原生表达，格式层只能写 `required: false`（Prism 同款）；导出**管线**更严： + // 禁用文件直接内联进 overrides/ 并保留后缀（见 export::pipeline 的 DisabledNotExpressible）。 + let cf = fixtures::curseforge("disabled-cf"); + let pack = PackArchive::open_default(&cf.zip).expect("打开 CF 夹具"); + let mut manifest = CURSEFORGE.read(&pack).expect("读 CF 清单"); + assert!(!manifest.files[0].disabled, "读包不会凭空造出禁用位"); + manifest.files[0].disabled = true; + let target = cf.zip.with_file_name("disabled.zip"); + CURSEFORGE + .write(&manifest, PackPayload::from_root(&cf.dir), &target) + .expect("导出 CF"); + let written = PackArchive::open_default(&target).expect("打开导出的 CF 包"); + let reread = CURSEFORGE.read(&written).expect("再读 CF"); + assert_eq!( + reread.files[0].client, + EnvSupport::Optional, + "CF 没有禁用表达，格式层只能落 required=false" + ); + + let mr = fixtures::modrinth("disabled-mr"); + let pack = PackArchive::open_default(&mr.zip).expect("打开 mrpack 夹具"); + let mut manifest = MODRINTH.read(&pack).expect("读 mrpack 清单"); + assert!( + !manifest.files[1].disabled, + "env.client=optional 是「可选」，不是「禁用」：两个事实不合并" + ); + manifest.files[0].disabled = true; + let target = mr.zip.with_file_name("disabled.mrpack"); + MODRINTH + .write(&manifest, PackPayload::from_root(&mr.dir), &target) + .expect("导出 mrpack"); + let written = PackArchive::open_default(&target).expect("打开导出的 mrpack"); + let reread = MODRINTH.read(&written).expect("再读 mrpack"); + assert_eq!( + reread.files[0].path.as_deref(), + Some("mods/jei.jar.disabled"), + "禁用靠路径后缀表达（官方导出的做法，跨启动器保真）" + ); + assert_eq!( + reread.files[0].client, + EnvSupport::Required, + "禁用不再被翻译成 env.client=optional（tower 定案）" + ); +} diff --git a/crates/core/src/addon/pack/tests/safety.rs b/crates/core/src/addon/pack/tests/safety.rs new file mode 100644 index 0000000..dad4f55 --- /dev/null +++ b/crates/core/src/addon/pack/tests/safety.rs @@ -0,0 +1,312 @@ +//! 恶意样本：每条安全判据都配一条"会失败的包"，而不是靠注释保证。 +//! +//! 覆盖：路径穿越四类形状（`..` / 绝对路径 / 反斜杠 / 盘符）、符号链接条目、条目数上限、 +//! 解压总体积上限、单条目上限、规整后重名、篡改载荷（CRC 不符）、以及**清单字段里的**穿越 +//! （mrpack `files[].path`、CF `overrides`）。 + +use std::path::{Path, PathBuf}; + +use super::{temp_root, write_zip, write_zip_with_symlink}; +use crate::addon::pack::archive::{PackArchive, PackLimits}; +use crate::addon::pack::curseforge::CURSEFORGE; +use crate::addon::pack::error::PackErrorKind; +use crate::addon::pack::format::PackFormat; +use crate::addon::pack::manifest::{PackLoader, PackManifest, PackOverrides, PackSide}; +use crate::addon::pack::modrinth::MODRINTH; + +/// 打一个只有一条恶意条目的 zip。 +fn single_entry(tag: &str, name: &str) -> PathBuf { + let target = temp_root(tag).join("evil.zip"); + write_zip(&target, &[(name, &b"payload"[..])]); + target +} + +fn open_error(target: &Path) -> crate::addon::pack::error::PackError { + PackArchive::open_default(target).expect_err("恶意包必须被拒") +} + +#[test] +fn rejects_parent_directory_entries() { + let target = single_entry("trav-parent", "../evil.txt"); + let error = open_error(&target); + assert_eq!( + error.kind(), + PackErrorKind::Traversal, + "{}", + error.message() + ); +} + +#[test] +fn rejects_absolute_entries() { + let target = single_entry("trav-absolute", "/etc/passwd"); + let error = open_error(&target); + assert_eq!( + error.kind(), + PackErrorKind::Traversal, + "{}", + error.message() + ); +} + +#[test] +fn rejects_backslash_separators() { + // Win32 把 `\` 当分隔符：按 `/` 切是"一个普通名字"，落盘却跳三层。 + let target = single_entry("trav-backslash", "mods\\..\\..\\evil.jar"); + let error = open_error(&target); + assert_eq!( + error.kind(), + PackErrorKind::Traversal, + "{}", + error.message() + ); +} + +#[test] +fn rejects_drive_letter_and_ads_entries() { + for (tag, name) in [ + ("trav-drive", "C:/Windows/evil.dll"), + ("trav-ads", "mods/jei.jar:Zone.Identifier"), + ] { + let target = single_entry(tag, name); + let error = open_error(&target); + assert_eq!( + error.kind(), + PackErrorKind::Traversal, + "{name}: {}", + error.message() + ); + } +} + +#[test] +fn rejects_symlink_entries() { + let target = temp_root("symlink").join("link.zip"); + write_zip_with_symlink( + &target, + &[("readme.txt", &b"x"[..])], + "mods/evil.jar", + "../../../etc/passwd", + ); + let error = open_error(&target); + assert_eq!(error.kind(), PackErrorKind::Symlink, "{}", error.message()); +} + +#[test] +fn rejects_too_many_entries() { + let target = temp_root("limit-count").join("many.zip"); + write_zip( + &target, + &[ + ("a.txt", &b"1"[..]), + ("b.txt", &b"2"[..]), + ("c.txt", &b"3"[..]), + ("d.txt", &b"4"[..]), + ], + ); + let error = PackArchive::open(&target, PackLimits::new(3, 1024 * 1024, 1024 * 1024)) + .expect_err("条目数超限必须拒"); + assert_eq!(error.kind(), PackErrorKind::Limits, "{}", error.message()); +} + +#[test] +fn rejects_uncompressed_volume_over_limit() { + let target = temp_root("limit-volume").join("big.zip"); + let payload = vec![b'a'; 4096]; + write_zip( + &target, + &[("a.bin", payload.as_slice()), ("b.bin", payload.as_slice())], + ); + let error = PackArchive::open(&target, PackLimits::new(16, 4096, 4096)) + .expect_err("解压总体积超限必须拒"); + assert_eq!(error.kind(), PackErrorKind::Limits, "{}", error.message()); +} + +#[test] +fn rejects_a_single_oversized_entry() { + let target = temp_root("limit-entry").join("big.zip"); + let payload = vec![b'a'; 2048]; + write_zip(&target, &[("a.bin", payload.as_slice())]); + let error = PackArchive::open(&target, PackLimits::new(16, 1024 * 1024, 512)) + .expect_err("单条目超限必须拒"); + assert_eq!(error.kind(), PackErrorKind::Limits, "{}", error.message()); +} + +#[test] +fn rejects_names_that_collide_after_normalization() { + // `./a.txt` 与 `a.txt` 规整后同名：留着就是"读到的和落盘的"不是同一个文件的经典混淆。 + let target = temp_root("dup-name").join("dup.zip"); + write_zip(&target, &[("./a.txt", &b"1"[..]), ("a.txt", &b"2"[..])]); + let error = open_error(&target); + assert_eq!(error.kind(), PackErrorKind::Metadata, "{}", error.message()); +} + +#[test] +fn a_tampered_payload_is_not_silently_accepted() { + // 中央目录没问题、数据被改过（CRC 不符）：打开能过，读内容必须报错。 + const MARKER: &[u8] = b"UNIQUE-PAYLOAD-MARKER"; + let target = temp_root("tampered").join("tampered.zip"); + write_zip( + &target, + &[ + ( + "manifest.json", + br#"{"manifestType":"minecraftModpack","manifestVersion":1, + "name":"tampered pack","minecraft":{"version":"1.20.1"},"files":[], + "overrides":"overrides"}"#, + ), + ("overrides/config/bad.toml", MARKER), + ], + ); + let mut bytes = std::fs::read(&target).expect("读 zip"); + let at = bytes + .windows(MARKER.len()) + .position(|window| window == MARKER) + .expect("找得到载荷"); + bytes[at] = b'X'; + std::fs::write(&target, bytes).expect("写回 zip"); + + let pack = PackArchive::open_default(&target).expect("中央目录完好，打开该成功"); + let error = pack + .read("overrides/config/bad.toml") + .expect_err("载荷被改过，读内容必须失败"); + assert!( + matches!(error.kind(), PackErrorKind::Io | PackErrorKind::Metadata), + "实际大类：{:?}（{}）", + error.kind(), + error.message() + ); + // 整包读取会算覆盖文件的 SHA-1，因此也必须失败，而不是"算出一个错的哈希"。 + assert!(CURSEFORGE.read(&pack).is_err()); +} + +#[test] +fn mrpack_file_path_traversal_is_rejected() { + let target = temp_root("mr-trav").join("evil.mrpack"); + let index = r#"{"game":"minecraft","formatVersion":1,"versionId":"1.0","name":"evil pack", + "files":[{"path":"../evil.jar", + "hashes":{"sha512":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}, + "downloads":["https://example.invalid/evil.jar"]}], + "dependencies":{"minecraft":"1.20.1"}}"#; + write_zip(&target, &[("modrinth.index.json", index.as_bytes())]); + let pack = PackArchive::open_default(&target).expect("zip 本身可读"); + let error = MODRINTH.read(&pack).expect_err("清单里的穿越路径必须拒"); + assert_eq!( + error.kind(), + PackErrorKind::Traversal, + "{}", + error.message() + ); +} + +#[test] +fn curseforge_overrides_dir_traversal_is_rejected() { + let target = temp_root("cf-trav").join("evil.zip"); + write_zip( + &target, + &[( + "manifest.json", + br#"{"manifestType":"minecraftModpack","manifestVersion":1,"name":"evil pack", + "minecraft":{"version":"1.20.1"},"files":[],"overrides":"../../etc"}"#, + )], + ); + let pack = PackArchive::open_default(&target).expect("zip 本身可读"); + let error = CURSEFORGE + .read(&pack) + .expect_err("overrides 目录指向包外必须拒"); + assert_eq!( + error.kind(), + PackErrorKind::Traversal, + "{}", + error.message() + ); +} + +#[test] +fn write_side_path_check_catches_hand_built_models() { + // 模型可能不是我们读出来的（UI/AI 手搓）：导出前必须再查一遍。 + let mut manifest = PackManifest::new("手搓模型"); + manifest.overrides.push(PackOverrides { + dir: "overrides".to_string(), + side: PackSide::Both, + files: Vec::new(), + }); + manifest + .loaders + .push(PackLoader::parse_curse("forge-47.2.0", true)); + assert!(manifest.check_paths().is_ok()); + + manifest.overrides[0].dir = "../escape".to_string(); + assert_eq!( + manifest + .check_paths() + .expect_err("越界目录必须被写侧检查拦下") + .kind(), + PackErrorKind::Traversal + ); +} + +#[test] +fn missing_package_is_an_io_error() { + let target = temp_root("missing").join("does-not-exist.zip"); + let error = open_error(&target); + assert_eq!(error.kind(), PackErrorKind::Io, "{}", error.message()); +} + +#[test] +fn directory_source_rejects_symlinks_when_the_platform_can_make_them() { + // Windows 建符号链接需要开发者模式/管理员：建不出来就跳过，但绝不静默当通过。 + #[cfg(unix)] + { + let root = temp_root("dir-symlink").join("instance"); + std::fs::create_dir_all(&root).expect("建目录"); + std::fs::write(root.join("mmc-pack.json"), b"{}").expect("写文件"); + std::os::unix::fs::symlink("/etc/passwd", root.join("escape")).expect("建符号链接"); + let error = open_error(&root); + assert_eq!(error.kind(), PackErrorKind::Symlink, "{}", error.message()); + } + #[cfg(not(unix))] + { + eprintln!( + "跳过：当前平台建符号链接需要额外权限（目录侧的检查逻辑与 zip 侧共用同一条判据）" + ); + } +} + +#[test] +#[cfg(windows)] +fn the_second_check_catches_windows_device_names_and_dot_suffixes() { + // r1 p2-3：第一检（平台无关的七条）对这些名字是**放行**的，拦下它们的是第二检 + // `enclosed_name()` 的 Win32 命名空间规则（DOS 设备名、结尾点/空格、`< > " | ? *`）。 + // 删掉第二检，这条用例必须红——这是「双检各有一条恶意样本」的第二条。 + for (tag, name) in [ + ("dev-con", "CON"), + ("dev-nul-nested", "mods/NUL"), + ("dev-com1", "COM1.txt"), + ("dev-trailing-dot", "a."), + ("dev-trailing-space", "mods/b "), + ("dev-wildcard", "mods/*.jar"), + ] { + let target = single_entry(tag, name); + let error = open_error(&target); + assert_eq!( + error.kind(), + PackErrorKind::Traversal, + "{name}: {}", + error.message() + ); + assert!( + error.message().contains("enclosed_name"), + "{name} 必须是被第二检拦下的（不然这条用例钉错了地方）：{}", + error.message() + ); + } + + // 对照：第一检对这些名字没有任何意见（所以它们只能靠第二检）。 + for name in ["CON", "mods/NUL", "a.", "mods/b ", "mods/*.jar"] { + assert!( + crate::addon::pack::path::normalize_file(name).is_ok(), + "第一检不该拦 {name}（拦了这条用例就失去意义）" + ); + } +} diff --git a/crates/core/src/addon/pack/tests/unknown_fields.rs b/crates/core/src/addon/pack/tests/unknown_fields.rs new file mode 100644 index 0000000..bc7fa79 --- /dev/null +++ b/crates/core/src/addon/pack/tests/unknown_fields.rs @@ -0,0 +1,113 @@ +//! 「未知字段不丢」的三处条目级 flatten（r1 p3-3）：`env_extra`、CF `files[].extra`、 +//! `PackLoader::extra`。三处实现本来是对的，但此前一条断言都没有——而它们恰好是 M115 点名的 +//! HMCL 回写 `fileName`/`url` 的位置。每条都走「读 → render → 写整包 → 再读逐字段相等」。 + +use serde_json::json; + +use crate::addon::pack::archive::PackArchive; +use crate::addon::pack::curseforge::CURSEFORGE; +use crate::addon::pack::format::{PackFormat, PackPayload}; +use crate::addon::pack::modrinth::MODRINTH; + +#[test] +fn mrpack_env_unknown_keys_survive_read_write_reread() { + // r1 p3-3 的一处：`files[].env` 里的未知键（`env_extra`）此前没有任何断言。 + let root = super::temp_root("env-extra"); + let dir = root.join("src"); + super::write_file( + &dir.join("modrinth.index.json"), + br#"{"game":"minecraft","formatVersion":1,"versionId":"1.0","name":"env extra keys", + "files":[{"path":"mods/a.jar", + "hashes":{"sha512":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}, + "env":{"client":"required","server":"unsupported","customEnvKey":{"k":1}}, + "downloads":["https://example.invalid/a.jar"]}], + "dependencies":{"minecraft":"1.20.1"}}"#, + ); + let zip = root.join("pack.mrpack"); + super::zip_dir(&dir, &zip); + + let pack = PackArchive::open_default(&zip).expect("打开包"); + let manifest = MODRINTH.read(&pack).expect("读 mrpack 清单"); + assert_eq!(manifest.files[0].env_extra["customEnvKey"], json!({"k": 1})); + + let target = root.join("out.mrpack"); + MODRINTH + .write(&manifest, PackPayload::metadata_only(), &target) + .expect("导出 mrpack"); + let reread = MODRINTH + .read(&PackArchive::open_default(&target).expect("打开导出包")) + .expect("再读"); + assert_eq!(reread, manifest, "env 里的未知键必须原样回写"); + assert_eq!(reread.files[0].env_extra["customEnvKey"], json!({"k": 1})); +} + +#[test] +fn curseforge_file_unknown_keys_survive_read_write_reread() { + // r1 p3-3 的另一处：CF `files[].fileName` / `url` 是 HMCL 补全后回写的扩展点。 + let root = super::temp_root("cf-file-extra"); + let dir = root.join("src"); + super::write_file( + &dir.join("manifest.json"), + br#"{"manifestType":"minecraftModpack","manifestVersion":1,"name":"files extra keys", + "version":"1.0","minecraft":{"version":"1.20.1","modLoaders":[{"id":"forge-47.2.0","primary":true}]}, + "files":[{"projectID":238222,"fileID":5102025,"required":true, + "fileName":"jei-1.20.1-15.2.0.27.jar", + "url":"https://edge.forgecdn.net/files/5102/25/jei.jar"}]}"#, + ); + let zip = root.join("pack.zip"); + super::zip_dir(&dir, &zip); + + let pack = PackArchive::open_default(&zip).expect("打开包"); + let manifest = CURSEFORGE.read(&pack).expect("读 CF 清单"); + assert_eq!( + manifest.files[0].extra["fileName"], + json!("jei-1.20.1-15.2.0.27.jar") + ); + assert_eq!( + manifest.files[0].extra["url"], + json!("https://edge.forgecdn.net/files/5102/25/jei.jar") + ); + + let target = root.join("out.zip"); + CURSEFORGE + .write(&manifest, PackPayload::metadata_only(), &target) + .expect("导出 CF"); + let reread = CURSEFORGE + .read(&PackArchive::open_default(&target).expect("打开导出包")) + .expect("再读"); + assert_eq!(reread, manifest, "files[] 里的未知键必须原样回写"); +} + +#[test] +fn curseforge_loader_unknown_keys_survive_read_write_reread() { + // r1 p3-3 的第三处：`modLoaders[]` 里的未知键（`PackLoader::extra`）。 + let root = super::temp_root("cf-loader-extra"); + let dir = root.join("src"); + super::write_file( + &dir.join("manifest.json"), + br#"{"manifestType":"minecraftModpack","manifestVersion":1,"name":"loader extra keys", + "version":"1.0", + "minecraft":{"version":"1.20.1", + "modLoaders":[{"id":"forge-47.2.0","primary":true,"cachedName":"Forge 47.2.0"}]}, + "files":[]}"#, + ); + let zip = root.join("pack.zip"); + super::zip_dir(&dir, &zip); + + let pack = PackArchive::open_default(&zip).expect("打开包"); + let manifest = CURSEFORGE.read(&pack).expect("读 CF 清单"); + assert_eq!( + manifest.loaders[0].extra["cachedName"], + json!("Forge 47.2.0") + ); + + let target = root.join("out.zip"); + CURSEFORGE + .write(&manifest, PackPayload::metadata_only(), &target) + .expect("导出 CF"); + let reread = CURSEFORGE + .read(&PackArchive::open_default(&target).expect("打开导出包")) + .expect("再读"); + assert_eq!(reread, manifest, "modLoaders[] 里的未知键必须原样回写"); + assert_eq!(reread.loaders[0].extra["cachedName"], json!("Forge 47.2.0")); +} diff --git a/crates/core/src/addon/tests/import_curseforge.rs b/crates/core/src/addon/tests/import_curseforge.rs new file mode 100644 index 0000000..03d6d8c --- /dev/null +++ b/crates/core/src/addon/tests/import_curseforge.rs @@ -0,0 +1,134 @@ +//! CurseForge `manifest.json` 端到端导入（离线，stub fetcher 充当 CF API + CDN）。 +//! +//! 夹具是 M110 的手造包（`fixtures::curseforge`）：`overrides/` 里有一个**刻意的截断 TOML** +//! （`config/broken.toml`）与一个假 jar。导入器不许因为坏内容崩，也不许悄悄丢掉它们。 + +use crate::addon::import::{import_pack, ImportRequest, ImportStatus}; +use crate::addon::loader::LoaderKind; +use crate::download::blocking::block_on; + +use super::support::{curse_meta, StubFetcher, CURSE_URL}; +use super::{fixtures, list_tree, read_text, temp_root}; + +/// CF 夹具里那两个条目补全出来的内容。 +const CURSE_BYTES: &[u8] = b"stub curse file bytes"; + +#[test] +fn imports_curseforge_pack_end_to_end() { + let fixture = fixtures::curseforge("cf-e2e"); + let target = temp_root("cf-e2e-out").join("instance"); + let fetcher = StubFetcher::new() + .with_curse(238222, 5102025, curse_meta("jei.jar", CURSE_BYTES)) + .with_curse(306612, 4587454, curse_meta("fabric-api.jar", CURSE_BYTES)) + .with_file(CURSE_URL, CURSE_BYTES); + + let request = ImportRequest::new(&fixture.zip, &target).with_fetcher(&fetcher); + let report = block_on(import_pack(&request)); + + assert_eq!( + report.status, + ImportStatus::Success, + "状态 {:?}，缺文件 {:?}，冲突 {:?}，错误 {:?}", + report.status, + report.missing, + report.conflicts, + report.error + ); + assert_eq!(report.format.as_deref(), Some("curseforge")); + assert_eq!(report.pack_name.as_deref(), Some(fixtures::CF_NAME)); + assert_eq!(report.pack_version.as_deref(), Some("1.0.0")); + assert_eq!(report.game_version.as_deref(), Some("1.20.1")); + assert!(!report.rolled_back); + + // 加载器被翻译成 addon::loader 的三元组（不另写一套安装逻辑）。 + let loader = report.loader.as_ref().expect("CF 夹具带 forge"); + assert_eq!(loader.kind, LoaderKind::Forge); + assert_eq!(loader.loader_version, "47.2.0"); + assert_eq!(loader.version_id, "1.20.1-forge-47.2.0"); + assert_eq!( + loader.resolve_args(), + (LoaderKind::Forge, "1.20.1", "47.2.0") + ); + assert_eq!(report.version_id.as_deref(), Some("1.20.1-forge-47.2.0")); + + // 覆盖内容（`overrides/` 的内容铺到实例根，不多一层目录）。 + assert!(read_text(&target.join("config/known.toml")).contains("key")); + // 刻意的截断 TOML 必须原样落地：导入器不是校验器，不许因为内容坏就丢文件。 + assert_eq!( + read_text(&target.join("config/broken.toml")), + String::from_utf8_lossy(fixtures::CF_BROKEN) + ); + // 两个 CF 条目都被补全 + 下载（文件名与目录都来自 CF 元数据）。 + assert_eq!( + std::fs::read(target.join("mods/jei.jar")).expect("jei.jar"), + CURSE_BYTES + ); + assert_eq!( + std::fs::read(target.join("mods/fabric-api.jar")).expect("fabric-api.jar"), + CURSE_BYTES + ); + assert_eq!( + fetcher.calls(), + vec![CURSE_URL.to_string(), CURSE_URL.to_string()] + ); + + // 基线写进去了（下次导入的 base 侧）。 + let baseline = read_text(&target.join(super::baseline_rel())); + assert!(baseline.contains("mods/jei.jar"), "基线：{baseline}"); + assert!(baseline.contains("config/known.toml"), "基线：{baseline}"); + + assert_eq!( + list_tree(&target), + vec![ + super::baseline_rel(), + "config/broken.toml".to_string(), + "config/known.toml".to_string(), + "mods/example.jar".to_string(), + "mods/fabric-api.jar".to_string(), + "mods/jei.jar".to_string(), + ] + ); +} + +#[test] +fn offline_curseforge_import_is_partial_not_success() { + // 没有 fetcher ⇒ CF 的 files[] 一条都补不出来。这**不是**失败，也**不许**记成成功。 + let fixture = fixtures::curseforge("cf-offline"); + let target = temp_root("cf-offline-out").join("instance"); + let request = ImportRequest::new(&fixture.zip, &target); + let report = block_on(import_pack(&request)); + + assert_eq!(report.status, ImportStatus::Partial); + assert_eq!(report.missing.len(), 2, "{:?}", report.missing); + assert!(report + .missing + .iter() + .all(|missing| missing.message_key == crate::addon::import::keys::MISSING_OFFLINE)); + // 覆盖内容照装（离线不影响包内自带的内容）。 + assert!(target.join("config/known.toml").is_file()); + assert!(!target.join("mods/jei.jar").exists()); + // 3 = Partial 的退出码（CLI 契约）。 + assert_eq!(report.status.exit_code(), 3); +} + +#[test] +fn curseforge_meta_without_download_url_is_missing_not_guessed() { + // CF 作者可以关掉 API 分发（`downloadUrl` 为 null）：我们**不猜** URL，只如实记缺。 + let fixture = fixtures::curseforge("cf-nourl"); + let target = temp_root("cf-nourl-out").join("instance"); + let mut meta = curse_meta("jei.jar", CURSE_BYTES); + meta.url = None; + let fetcher = StubFetcher::new() + .with_curse(238222, 5102025, meta) + .with_file(CURSE_URL, CURSE_BYTES); + let request = ImportRequest::new(&fixture.zip, &target).with_fetcher(&fetcher); + let report = block_on(import_pack(&request)); + + assert_eq!(report.status, ImportStatus::Partial); + assert!(report + .missing + .iter() + .any(|missing| missing.message_key == crate::addon::import::keys::MISSING_NO_SOURCE)); + // 没有发出任何下载请求。 + assert!(fetcher.calls().is_empty(), "{:?}", fetcher.calls()); +} diff --git a/crates/core/src/addon/tests/import_failures.rs b/crates/core/src/addon/tests/import_failures.rs new file mode 100644 index 0000000..57e8511 --- /dev/null +++ b/crates/core/src/addon/tests/import_failures.rs @@ -0,0 +1,254 @@ +//! **必须先失败**的样本：四条恶意/坏包 + 两条"证明双检真的在导入链上跑"的用例。 +//! +//! # 复审要的那张表 +//! +//! | 样本 | 期望结果 | 断言在哪 | +//! |------|----------|----------| +//! | 路径穿越条目（`../evil.jar`） | `Failed` + `pack_traversal` + 目标目录零残留 | [`traversal_entry_rolls_back_with_zero_residue`] | +//! | 符号链接条目 | `Failed` + `pack_symlink` + 零残留 | [`symlink_entry_rolls_back_with_zero_residue`] | +//! | 损坏清单（非法 JSON） | `Failed` + `pack_metadata` + 零残留 | [`corrupt_manifest_rolls_back_with_zero_residue`] | +//! | 声明与实际不符（sha1 不符） | `Failed` + `import_integrity` + 零残留 | [`declared_hash_mismatch_rolls_back_everything`] | +//! +//! # 零残留的验证方式 +//! +//! [`assert_clean`]：①目标目录不存在；②目标目录的父目录里没有 `.ull-import-*` 临时目录 +//! （临时目录是"事务没收拾干净"的唯一痕迹）；③合并态用例另外断言目标目录内容与导入前 +//! **逐项相同**。三条合起来就是"失败后既没有半个实例，也没有残留垃圾"。 +//! +//! # 两条双检证明 +//! +//! 路径穿越是**两条独立检查**（M110 `pack::path::normalize_file` + `zip` 的 +//! `enclosed_name()`）。要证明两条都真的接在导入链上，得各给一条**只有其中一条能拦**的样本： +//! +//! - 绝对路径 `/etc/passwd`：`enclosed_name()` 在深度 0 处**放行**（它允许根目录），只有第一检 +//! 能拦 ⇒ 它失败就说明第一检活着； +//! - Windows 设备名 `NUL`：第一检七条规则全放行，只有第二检（按 Win32 命名空间解析）能拦 +//! ⇒ 它失败就说明第二检活着（该用例仅在 Windows 宿主上有效，与 M110 的用例同构）。 + +use std::path::Path; + +use crate::addon::import::{import_pack, ImportRequest, ImportStatus}; +use crate::download::blocking::block_on; + +use super::support::{StubFetcher, JEI_BYTES, JEI_PLACEHOLDER_URL, OPTIONAL_PLACEHOLDER_URL}; +use super::{ + fixtures, list_tree, read_text, temp_root, write_file, write_zip, write_zip_with_symlink, +}; + +/// 一份形状合法的最小 CF 清单（恶意包要能被"探测成功"，失败必须发生在它该发生的阶段）。 +const CF_MANIFEST: &[u8] = br#"{"manifestType": "minecraftModpack", "manifestVersion": 1, + "name": "evil", "version": "1.0.0", "overrides": "overrides", + "minecraft": {"version": "1.20.1", "modLoaders": []}, "files": []}"#; + +/// 断言"目标目录零残留"：目录不存在、父目录里没有临时目录。 +fn assert_clean(target: &Path) { + assert!( + !target.exists(), + "目标目录必须不存在（零残留），实际：{:?}", + list_tree(target) + ); + let parent = target.parent().expect("target 有父目录"); + if let Ok(entries) = std::fs::read_dir(parent) { + for entry in entries.flatten() { + let name = entry.file_name().to_string_lossy().to_string(); + assert!(!name.contains(".ull-import-"), "临时目录没清掉：{name}"); + } + } +} + +fn failing(tag: &str, entries: &[(&str, &[u8])]) -> (std::path::PathBuf, std::path::PathBuf) { + let root = temp_root(tag); + let pack = root.join("evil.zip"); + write_zip(&pack, entries); + let target = root.join("instance"); + (pack, target) +} + +#[test] +fn traversal_entry_rolls_back_with_zero_residue() { + let (pack, target) = failing( + "fail-traversal", + &[("manifest.json", CF_MANIFEST), ("../evil.jar", b"payload")], + ); + let report = block_on(import_pack(&ImportRequest::new(&pack, &target))); + + assert_eq!(report.status, ImportStatus::Failed); + assert_eq!( + report.error.as_ref().expect("具名错误").code(), + "pack_traversal" + ); + assert!(report.rolled_back); + assert_clean(&target); + assert_eq!(report.status.exit_code(), 1); +} + +#[test] +fn absolute_entry_proves_the_first_check_is_live() { + // `enclosed_name()` 会放行深度 0 的绝对路径，只有 `normalize_file` 能拦。 + let (pack, target) = failing( + "fail-absolute", + &[ + ("manifest.json", CF_MANIFEST), + ("/etc/passwd", b"root::0:0"), + ], + ); + let report = block_on(import_pack(&ImportRequest::new(&pack, &target))); + + assert_eq!(report.status, ImportStatus::Failed); + assert_eq!( + report.error.as_ref().expect("具名错误").code(), + "pack_traversal" + ); + assert_clean(&target); +} + +#[cfg(windows)] +#[test] +fn windows_device_name_proves_the_second_check_is_live() { + // `NUL` 过得了第一检的七条规则，只有 `zip` 的 `enclosed_name()`（Win32 命名空间）会拦。 + let (pack, target) = failing( + "fail-device", + &[("manifest.json", CF_MANIFEST), ("mods/NUL", b"x")], + ); + let report = block_on(import_pack(&ImportRequest::new(&pack, &target))); + + assert_eq!(report.status, ImportStatus::Failed); + assert_eq!( + report.error.as_ref().expect("具名错误").code(), + "pack_traversal" + ); + assert_clean(&target); +} + +#[test] +fn symlink_entry_rolls_back_with_zero_residue() { + let root = temp_root("fail-symlink"); + let pack = root.join("evil.zip"); + let entries: [(&str, &[u8]); 1] = [("manifest.json", CF_MANIFEST)]; + write_zip_with_symlink(&pack, &entries, "mods/evil.jar", "../../../etc/passwd"); + let target = root.join("instance"); + + let report = block_on(import_pack(&ImportRequest::new(&pack, &target))); + assert_eq!(report.status, ImportStatus::Failed); + assert_eq!( + report.error.as_ref().expect("具名错误").code(), + "pack_symlink" + ); + assert_clean(&target); +} + +#[test] +fn corrupt_manifest_rolls_back_with_zero_residue() { + let (pack, target) = failing( + "fail-json", + &[ + ("manifest.json", b"{\"manifestType\": \"minecraftModpack\","), + ("overrides/config/a.toml", b"k = 1\n"), + ], + ); + let report = block_on(import_pack(&ImportRequest::new(&pack, &target))); + + assert_eq!(report.status, ImportStatus::Failed); + let code = report.error.as_ref().expect("具名错误").code(); + assert!( + code == "pack_metadata" || code == "pack_unsupported", + "坏 JSON 要报成因，实际 {code}" + ); + assert_clean(&target); +} + +#[test] +fn declared_hash_mismatch_rolls_back_everything() { + // 原始 M110 夹具：`hashes.sha1` 是形状正确的**占位值**，必然不等于 stub 给的字节。 + // 这是"声明与实际不符"——它**不是**"暂时搞不到"，必须整包回滚。 + let fixture = fixtures::modrinth("fail-integrity"); + let root = temp_root("fail-integrity-out"); + let target = root.join("instance"); + let fetcher = StubFetcher::new() + .with_file(JEI_PLACEHOLDER_URL, JEI_BYTES) + .with_file(OPTIONAL_PLACEHOLDER_URL, b"stub optional"); + let report = block_on(import_pack( + &ImportRequest::new(&fixture.zip, &target).with_fetcher(&fetcher), + )); + + assert_eq!( + report.status, + ImportStatus::Failed, + "缺文件 {:?}", + report.missing + ); + assert_eq!( + report.error.as_ref().expect("具名错误").code(), + "import_integrity" + ); + assert!(report.rolled_back); + assert_clean(&target); +} + +#[test] +fn fatal_error_in_merge_mode_leaves_the_target_untouched() { + // 目标目录已有内容（升级/重导）：致命错误时**只**清临时目录，不动目标目录。 + let (pack, target) = failing( + "fail-merge", + &[("manifest.json", CF_MANIFEST), ("../evil.jar", b"payload")], + ); + write_file(&target.join("keep.txt"), b"untouched"); + write_file(&target.join("mods/mine.jar"), b"mine"); + let before = list_tree(&target); + + let report = block_on(import_pack(&ImportRequest::new(&pack, &target))); + + assert_eq!(report.status, ImportStatus::Failed); + assert!(report.rolled_back); + assert_eq!(list_tree(&target), before, "目标目录必须逐项不变"); + assert_eq!( + std::fs::read(target.join("keep.txt")).expect("keep.txt"), + b"untouched" + ); +} + +#[test] +fn commit_failure_rolls_back_partially_applied_files() { + // 让合并态的**提交阶段**在中途失败：目标文件要被替换时必须先备份成 + // `.ullbak-`，而那个位置已被一个**非空目录**占住 ⇒ `rename(dest → backup)` + // 必然失败（文件改不成非空目录，Windows / Unix 一致）。 + // 这覆盖 journal 回滚 + `Drop` 兜底：前半截已经搬进去的文件（基线排最前）必须被撤回。 + let root = temp_root("fail-commit"); + let source = fixtures::multimc("fail-commit-src"); + let target = root.join("instance"); + let first = block_on(import_pack(&ImportRequest::new(&source, &target))); + assert_eq!(first.status, ImportStatus::Success, "{:?}", first.error); + + // 新版本包内容变了（用户没动过 ⇒ 判据是 Install，会被暂存并尝试替换）。 + write_file( + &source.join(".minecraft/config/known.toml"), + b"key = \"v2\"\n", + ); + // 备份位置被非空目录占住。 + let blocker = target.join(format!("config/known.toml.ullbak-{}", std::process::id())); + write_file(&blocker.join("blocker.txt"), b"block"); + let before = list_tree(&target); + + let second = block_on(import_pack(&ImportRequest::new(&source, &target))); + + assert_eq!( + second.status, + ImportStatus::Failed, + "提交阶段失败必须整包回滚" + ); + assert_eq!( + second.error.as_ref().expect("具名错误").code(), + "pack_io", + "{}", + second.error.as_ref().expect("具名错误").message() + ); + assert!(second.rolled_back); + assert_eq!(list_tree(&target), before, "目标目录必须逐项回到导入前"); + // 提交阶段排在最前面的基线被成功搬入又被撤回：内容仍是第一次导入的那份。 + assert!(target.join(super::baseline_rel()).is_file()); + assert_eq!( + read_text(&target.join("config/known.toml")), + "key = \"value\"\n", + "旧内容必须还在（新内容没落地）" + ); +} diff --git a/crates/core/src/addon/tests/import_merge.rs b/crates/core/src/addon/tests/import_merge.rs new file mode 100644 index 0000000..64cd84a --- /dev/null +++ b/crates/core/src/addon/tests/import_merge.rs @@ -0,0 +1,293 @@ +//! overrides 三方合并的**行为**测试：用户改过 / 用户删过 / 没动过 / 没有基线 / 侧优先级。 +//! +//! 判据本身（纯函数）在 `import::merge` 的单元测试里；这里验证的是"判据真的接在管线上了"： +//! 真写盘、真重导、真读回内容。 + +use crate::addon::import::{ + import_pack, ConflictChoice, ConflictPolicy, ConflictReason, FileAction, ImportRequest, + ImportStatus, +}; +use crate::download::blocking::block_on; + +use super::support::mrpack_stub; +use super::{list_tree, read_text, temp_root, write_file, zip_dir}; + +use crate::addon::import::{PackBaseline, BASELINE_FILE}; + +#[test] +fn user_modified_file_is_kept_and_reported() { + let (fixture, fetcher) = mrpack_stub("merge-modified"); + let target = temp_root("merge-modified-out").join("instance"); + let first = block_on(import_pack( + &ImportRequest::new(&fixture.zip, &target).with_fetcher(&fetcher), + )); + assert_eq!(first.status, ImportStatus::Success, "{:?}", first.error); + + // 用户动手改了一个包内文件。 + write_file(&target.join("config/known.toml"), b"shared = false\n"); + let second = block_on(import_pack( + &ImportRequest::new(&fixture.zip, &target).with_fetcher(&fetcher), + )); + + assert_eq!( + second.status, + ImportStatus::Partial, + "保留用户文件 ⇒ 部分成功" + ); + assert_eq!(second.conflicts.len(), 1, "{:?}", second.conflicts); + let conflict = &second.conflicts[0]; + assert_eq!(conflict.path, "config/known.toml"); + assert_eq!(conflict.reason, ConflictReason::UserModified); + assert_eq!(conflict.choice, ConflictChoice::KeepUser); + assert_eq!( + conflict.message_key, + crate::addon::import::keys::CONFLICT_USER_MODIFIED + ); + assert!(conflict.base_sha1.is_some(), "基线里应有上次的哈希"); + assert!(conflict.disk_sha1.is_some()); + // 磁盘内容没被盖掉。 + assert_eq!( + read_text(&target.join("config/known.toml")), + "shared = false\n" + ); + // 报告里这条的结局是"保留用户"。 + assert!(second + .files + .iter() + .any(|file| file.path == "config/known.toml" && file.action == FileAction::KeptUser)); + assert_eq!(second.status.exit_code(), 3); +} + +#[test] +fn user_deleted_file_is_not_restored() { + let (fixture, fetcher) = mrpack_stub("merge-deleted"); + let target = temp_root("merge-deleted-out").join("instance"); + let first = block_on(import_pack( + &ImportRequest::new(&fixture.zip, &target).with_fetcher(&fetcher), + )); + assert_eq!(first.status, ImportStatus::Success, "{:?}", first.error); + + // 用户删了一个包内文件。 + std::fs::remove_file(target.join("mods/half.jar")).expect("删夹具文件"); + let second = block_on(import_pack( + &ImportRequest::new(&fixture.zip, &target).with_fetcher(&fetcher), + )); + + assert_eq!(second.status, ImportStatus::Partial); + let conflict = second + .conflicts + .iter() + .find(|conflict| conflict.path == "mods/half.jar") + .expect("删除也要进冲突清单"); + assert_eq!(conflict.reason, ConflictReason::UserDeleted); + assert_eq!(conflict.choice, ConflictChoice::KeepUser); + assert_eq!(conflict.disk_sha1, None); + assert!( + !target.join("mods/half.jar").exists(), + "用户删掉的文件不许偷偷装回来" + ); +} + +#[test] +fn untouched_file_is_upgraded_by_a_newer_pack() { + let (fixture, fetcher) = mrpack_stub("merge-upgrade"); + let target = temp_root("merge-upgrade-out").join("instance"); + let first = block_on(import_pack( + &ImportRequest::new(&fixture.zip, &target).with_fetcher(&fetcher), + )); + assert_eq!(first.status, ImportStatus::Success, "{:?}", first.error); + + // 新版本包：同一个路径，内容变了；用户没动过。 + write_file( + &fixture.dir.join("overrides/config/known.toml"), + b"shared = 2\n", + ); + zip_dir(&fixture.dir, &fixture.zip); + let second = block_on(import_pack( + &ImportRequest::new(&fixture.zip, &target).with_fetcher(&fetcher), + )); + + assert_eq!( + second.status, + ImportStatus::Success, + "未改过的文件升级不算冲突" + ); + assert!(second.conflicts.is_empty(), "{:?}", second.conflicts); + assert_eq!(read_text(&target.join("config/known.toml")), "shared = 2\n"); + assert!(second + .files + .iter() + .any(|file| file.path == "config/known.toml" && file.action == FileAction::Replaced)); +} + +#[test] +fn pre_existing_file_without_baseline_is_kept() { + let (fixture, fetcher) = mrpack_stub("merge-existing"); + let target = temp_root("merge-existing-out").join("instance"); + // 首次导入前磁盘上就有同名文件：没有基线可判 ⇒ 最安全的一侧（不覆盖）。 + write_file(&target.join("config/known.toml"), b"mine\n"); + let report = block_on(import_pack( + &ImportRequest::new(&fixture.zip, &target).with_fetcher(&fetcher), + )); + + assert_eq!(report.status, ImportStatus::Partial); + let conflict = report + .conflicts + .iter() + .find(|conflict| conflict.path == "config/known.toml") + .expect("要有冲突清单"); + assert_eq!(conflict.reason, ConflictReason::PreExisting); + assert!(conflict.base_sha1.is_none()); + assert_eq!(read_text(&target.join("config/known.toml")), "mine\n"); +} + +#[test] +fn overwrite_policy_replaces_user_file_and_reports_the_choice() { + let (fixture, fetcher) = mrpack_stub("merge-overwrite"); + let target = temp_root("merge-overwrite-out").join("instance"); + let first = block_on(import_pack( + &ImportRequest::new(&fixture.zip, &target).with_fetcher(&fetcher), + )); + assert_eq!(first.status, ImportStatus::Success, "{:?}", first.error); + write_file(&target.join("config/known.toml"), b"shared = false\n"); + + let report = block_on(import_pack( + &ImportRequest::new(&fixture.zip, &target) + .with_fetcher(&fetcher) + .with_conflict_policy(ConflictPolicy::Overwrite), + )); + + assert_eq!(report.status, ImportStatus::Success, "覆盖后结果是干净的"); + let conflict = report + .conflicts + .iter() + .find(|conflict| conflict.path == "config/known.toml") + .expect("冲突仍要记账"); + assert_eq!(conflict.reason, ConflictReason::UserModified); + assert_eq!(conflict.choice, ConflictChoice::Overwrite); + assert_eq!( + read_text(&target.join("config/known.toml")), + "shared = true\n" + ); +} + +#[test] +fn client_overrides_wins_over_overrides() { + // Modrinth 官方客户端语义：`client-overrides/` 后写 = 胜（HMCL 恰好相反）。 + let root = temp_root("merge-priority"); + let dir = root.join("src"); + write_file( + &dir.join("modrinth.index.json"), + br#"{"game": "minecraft", "formatVersion": 1, "versionId": "1.0.0", + "name": "dup", "files": [], "dependencies": {"minecraft": "1.20.1"}}"#, + ); + write_file(&dir.join("overrides/config/dup.toml"), b"from-overrides\n"); + write_file( + &dir.join("client-overrides/config/dup.toml"), + b"from-client\n", + ); + write_file( + &dir.join("server-overrides/config/dup.toml"), + b"from-server\n", + ); + let pack = root.join("pack.mrpack"); + zip_dir(&dir, &pack); + + let target = root.join("instance"); + let report = block_on(import_pack(&ImportRequest::new(&pack, &target))); + + assert_eq!(report.status, ImportStatus::Success, "{:?}", report.error); + assert_eq!(read_text(&target.join("config/dup.toml")), "from-client\n"); + assert!( + report.conflicts.is_empty(), + "侧优先级不是冲突：{:?}", + report.conflicts + ); +} + +#[test] +fn baseline_read_and_write_paths_are_the_same_file() { + // 复审 r5 P1-1 的回归钉：读侧（`PackBaseline::path`）与写侧（`relative_path` 拼 root） + // **必须解析到同一个路径**。只测"读得到"在大小写不敏感的系统上会假绿。 + let root = temp_root("baseline-path").join("instance"); + let read = PackBaseline::path(&root); + let write = root.join(PackBaseline::relative_path()); + assert_eq!(read, write, "读写必须是同一个文件：{read:?} vs {write:?}"); + // 相对路径的唯一来源是 `GameLayout::ull_root()`（游戏根内的 `.ull/`），不是启动器数据根。 + assert_eq!( + PackBaseline::relative_path(), + std::path::PathBuf::from(".ull").join(BASELINE_FILE) + ); + assert_eq!( + read.parent(), + Some( + crate::game::layout::GameLayout::new(&root) + .ull_root() + .as_path() + ) + ); + // 写侧（pipeline 提交时用的相对路径）必须同源；`.ULL` 是**启动器数据根**的名字， + // 出现在实例内路径里就是 P1-1 那个 bug（大小写敏感的系统上会变成两个文件）。 + let write_side = crate::addon::import::baseline_relative(); + assert_eq!( + write_side, + PackBaseline::relative_path() + .to_string_lossy() + .replace('\\', "/"), + "写侧必须从同一个来源派生" + ); + assert!( + !write_side.contains(".ULL"), + "实例内路径不许用启动器数据根的 `.ULL`：{write_side}" + ); +} + +#[test] +fn baseline_of_another_pack_is_not_used_as_base() { + // 同一目录先后导入两个整合包：别人的基线当 base 会把"用户改过"误判成"整合包升级"而静默覆盖。 + let root = temp_root("merge-identity"); + let source = super::fixtures::multimc("merge-identity-a"); + let target = root.join("instance"); + let first = block_on(import_pack(&ImportRequest::new(&source, &target))); + assert_eq!(first.status, ImportStatus::Success, "{:?}", first.error); + // 用户改了一个包内文件。 + write_file(&target.join("mods/example.jar"), b"mine"); + + // 另一个包（名字不同 + 同名文件内容不同）导进同一目录。 + let other = root.join("other"); + write_file( + &other.join("mmc-pack.json"), + br#"{"formatVersion": 1, "components": [ + {"uid": "net.minecraft", "version": "1.20.1"}, + {"uid": "net.fabricmc.fabric-loader", "version": "0.15.11"}]}"#, + ); + write_file( + &other.join("instance.cfg"), + "InstanceType=OneSix\nname=另一个包\n".as_bytes(), + ); + write_file(&other.join(".minecraft/mods/example.jar"), b"pack B jar"); + let report = block_on(import_pack(&ImportRequest::new(&other, &target))); + + assert!( + report + .warnings + .iter() + .any(|note| note.message_key == crate::addon::import::keys::NOTE_BASELINE_PACK_MISMATCH), + "跨包基线要具名告警：{:?}", + report.warnings + ); + let conflict = report + .conflicts + .iter() + .find(|conflict| conflict.path == "mods/example.jar") + .expect("要有冲突"); + assert_eq!( + conflict.reason, + ConflictReason::PreExisting, + "别人的基线不能拿来判 user_modified" + ); + assert!(conflict.base_sha1.is_none(), "身份不符时基线应被忽略"); + assert_eq!(read_text(&target.join("mods/example.jar")), "mine"); + assert_eq!(report.status, ImportStatus::Partial); + assert!(list_tree(&target).contains(&"mods/example.jar".to_string())); +} diff --git a/crates/core/src/addon/tests/import_modrinth.rs b/crates/core/src/addon/tests/import_modrinth.rs new file mode 100644 index 0000000..0dbb934 --- /dev/null +++ b/crates/core/src/addon/tests/import_modrinth.rs @@ -0,0 +1,178 @@ +//! Modrinth `.mrpack` 端到端导入：三目录优先级、`.disabled` 后缀、依赖翻译。 +//! +//! 成功路径吃 [`super::support::mrpack_stub`]（同一份 M110 夹具，只把 `sha1`/`downloads` +//! 换成真实值）；"声明与实际不符"那条用例用**原始**夹具，见 `import_failures.rs`。 + +use crate::addon::import::{import_pack, keys, ImportRequest, ImportStatus}; +use crate::addon::loader::LoaderKind; +use crate::download::blocking::block_on; + +use super::support::{mrpack_stub, JEI_BYTES, OPTIONAL_BYTES}; +use super::{fixtures, list_tree, read_text, temp_root}; + +#[test] +fn imports_mrpack_end_to_end() { + let (fixture, fetcher) = mrpack_stub("mr-e2e"); + let target = temp_root("mr-e2e-out").join("instance"); + let request = ImportRequest::new(&fixture.zip, &target).with_fetcher(&fetcher); + let report = block_on(import_pack(&request)); + + assert_eq!( + report.status, + ImportStatus::Success, + "缺文件 {:?} 冲突 {:?} 错误 {:?}", + report.missing, + report.conflicts, + report.error + ); + assert_eq!(report.format.as_deref(), Some("modrinth")); + assert_eq!(report.pack_name.as_deref(), Some(fixtures::MR_NAME)); + assert_eq!(report.pack_version.as_deref(), Some("2.0.0")); + assert_eq!(report.game_version.as_deref(), Some("1.20.1")); + + let loader = report.loader.as_ref().expect("mrpack 带 fabric-loader"); + assert_eq!(loader.kind, LoaderKind::Fabric); + assert_eq!(loader.loader_version, "0.15.11"); + assert_eq!(loader.version_id, "1.20.1-fabric-0.15.11"); + + // 覆盖内容：`overrides/` + `client-overrides/` 落地，`server-overrides/` **不落地**。 + assert_eq!( + std::fs::read(target.join("mods/half.jar")).expect("half.jar"), + fixtures::MR_HALF_JAR + ); + assert!(target.join("config/known.toml").is_file()); + assert!(target.join("config/client-only.toml").is_file()); + assert!( + !target.join("config/server.properties").exists(), + "server-overrides/ 客户端不许解压（Modrinth 官方语义）" + ); + + // 远端条目：路径与地址都在清单里，内容来自 stub。 + assert_eq!( + std::fs::read(target.join("mods/jei.jar")).expect("jei.jar"), + JEI_BYTES + ); + assert_eq!( + std::fs::read(target.join("mods/optional.jar")).expect("optional.jar"), + OPTIONAL_BYTES + ); + + // 三条注记：服务端覆盖被跳过 / 不认识的依赖键 / 可选条目不等于禁用。 + let note_keys: Vec<&str> = report + .warnings + .iter() + .map(|note| note.message_key) + .collect(); + assert!( + note_keys.contains(&keys::NOTE_SERVER_OVERRIDES_SKIPPED), + "{note_keys:?}" + ); + assert!( + note_keys.contains(&keys::NOTE_UNKNOWN_DEPENDENCY), + "parchment 这类键要如实告警：{note_keys:?}" + ); + assert!( + note_keys.contains(&keys::NOTE_OPTIONAL_FILE), + "env.client=optional 要提示但照装：{note_keys:?}" + ); + + assert_eq!( + list_tree(&target), + vec![ + super::baseline_rel(), + "config/client-only.toml".to_string(), + "config/known.toml".to_string(), + "mods/half.jar".to_string(), + "mods/jei.jar".to_string(), + "mods/optional.jar".to_string(), + ] + ); +} + +#[test] +fn engine_artifacts_never_reach_the_instance() { + // 引擎在下载失败时故意留下 `.ullpart--` 与 `.ullmeta.json` + // 供下次续传；它们躺在暂存目录里，提交前必须剔掉，否则会变成实例里的"内容"。 + let (fixture, fetcher) = mrpack_stub("mr-artifacts"); + let fetcher = fetcher.with_engine_artifacts(); + let target = temp_root("mr-artifacts-out").join("instance"); + let report = block_on(import_pack( + &ImportRequest::new(&fixture.zip, &target).with_fetcher(&fetcher), + )); + + assert_eq!(report.status, ImportStatus::Success, "{:?}", report.error); + let tree = list_tree(&target); + assert!( + tree.iter() + .all(|path| !path.contains(".ullpart") && !path.contains(".ullmeta")), + "中间产物不许进实例：{tree:?}" + ); + assert!( + report + .warnings + .iter() + .any(|note| note.message_key == keys::NOTE_ENGINE_ARTIFACTS_DROPPED), + "剔除了就该留一条注记：{:?}", + report.warnings + ); +} + +#[test] +fn disabled_suffix_is_preserved_verbatim() { + // 四种 `.disabled` / `.old` 变体都按原后缀落地，不改名、不清理（tower 定案）。 + let (fixture, fetcher) = mrpack_stub("mr-disabled"); + super::write_file( + &fixture.dir.join("overrides/mods/variant.jar.disabled"), + b"disabled bytes", + ); + super::write_file( + &fixture.dir.join("overrides/mods/variant.jar.disabled.old"), + b"disabled old bytes", + ); + super::write_file( + &fixture.dir.join("overrides/mods/variant.jar.old"), + b"old bytes", + ); + super::zip_dir(&fixture.dir, &fixture.zip); + + let target = temp_root("mr-disabled-out").join("instance"); + let request = ImportRequest::new(&fixture.zip, &target).with_fetcher(&fetcher); + let report = block_on(import_pack(&request)); + + assert_eq!(report.status, ImportStatus::Success, "{:?}", report.error); + for name in [ + "mods/variant.jar.disabled", + "mods/variant.jar.disabled.old", + "mods/variant.jar.old", + ] { + assert!(target.join(name).is_file(), "{name} 应当按原后缀落地"); + } + // 禁用位从后缀读出来，`.old` 不被当成禁用。 + let disabled: Vec<(&str, bool)> = report + .files + .iter() + .filter(|file| file.path.starts_with("mods/variant")) + .map(|file| (file.path.as_str(), file.disabled)) + .collect(); + assert_eq!( + disabled, + vec![ + ("mods/variant.jar.disabled", true), + ("mods/variant.jar.disabled.old", true), + ("mods/variant.jar.old", false), + ] + ); + let note_keys: Vec<&str> = report + .files + .iter() + .filter(|file| file.path.starts_with("mods/variant")) + .filter_map(|file| file.note.as_ref().map(|note| note.message_key)) + .collect(); + assert!( + note_keys.contains(&keys::NOTE_DISABLED_SUFFIX), + "{note_keys:?}" + ); + assert!(note_keys.contains(&keys::NOTE_OLD_SUFFIX), "{note_keys:?}"); + // 报告里的内容仍是原文（没有"读出来再写一遍"导致的空白变化）。 + assert_eq!(read_text(&target.join("mods/variant.jar.old")), "old bytes"); +} diff --git a/crates/core/src/addon/tests/import_multimc.rs b/crates/core/src/addon/tests/import_multimc.rs new file mode 100644 index 0000000..170b82e --- /dev/null +++ b/crates/core/src/addon/tests/import_multimc.rs @@ -0,0 +1,210 @@ +//! MultiMC / Prism 实例目录导入：`.minecraft/` 直拷、component 逐项交代、`instance.cfg` 取内存。 + +use serde_json::Value; + +use crate::addon::import::{import_pack, keys, ImportRequest, ImportStatus}; +use crate::addon::loader::LoaderKind; +use crate::download::blocking::block_on; + +use super::{fixtures, list_tree, read_text, temp_root, write_file}; + +#[test] +fn imports_multimc_instance_end_to_end() { + let source = fixtures::multimc("mmc-e2e"); + let target = temp_root("mmc-e2e-out").join("instance"); + let request = ImportRequest::new(&source, &target); + let report = block_on(import_pack(&request)); + + assert_eq!(report.status, ImportStatus::Success, "{:?}", report.error); + assert_eq!(report.format.as_deref(), Some("multimc")); + assert_eq!(report.pack_name.as_deref(), Some(fixtures::MMC_NAME)); + assert_eq!(report.game_version.as_deref(), Some("1.20.1")); + let loader = report.loader.as_ref().expect("fabric-loader 组件"); + assert_eq!(loader.kind, LoaderKind::Fabric); + assert_eq!(loader.loader_version, "0.15.11"); + assert_eq!(loader.version_id, "1.20.1-fabric-0.15.11"); + // MultiMC 没有远端条目：内容就是目录。 + assert!(report.missing.is_empty()); + assert!(report + .files + .iter() + .all(|file| file.source == crate::addon::import::FileSource::Overrides)); + + // `.minecraft/` 直拷到实例根（不多一层 `.minecraft/`），零字节 jar 也照拷。 + assert_eq!( + std::fs::read(target.join("mods/example.jar")).expect("example.jar"), + b"PK\x03\x04 hand-made jar stub" + ); + assert_eq!( + std::fs::metadata(target.join("mods/broken.jar")) + .expect("broken.jar") + .len(), + 0, + "零字节 jar 是夹具刻意造的：导入器不许悄悄丢掉它" + ); + assert!(target.join("config/known.toml").is_file()); + assert_eq!( + list_tree(&target), + vec![ + super::baseline_rel(), + "config/known.toml".to_string(), + "mods/broken.jar".to_string(), + "mods/example.jar".to_string(), + ] + ); +} + +#[test] +fn unsupported_components_are_listed_one_by_one_not_dropped() { + let source = fixtures::multimc("mmc-components"); + let target = temp_root("mmc-components-out").join("instance"); + let request = ImportRequest::new(&source, &target); + let report = block_on(import_pack(&request)); + + // 夹具里的 `org.lwjgl3` 不是加载器 ⇒ 必须逐项进"未支持清单"。 + assert_eq!( + report.rejected_components.len(), + 1, + "{:?}", + report.rejected_components + ); + let rejected = &report.rejected_components[0]; + assert_eq!(rejected.uid, "org.lwjgl3"); + assert_eq!(rejected.version.as_deref(), Some("3.3.2")); + assert_eq!(rejected.message_key, keys::REJECTED_COMPONENT); + + // **不静默丢**的断言：`mmc-pack.json` 里每一个 component 都能在报告里找到归宿。 + let pack: Value = + serde_json::from_str(&read_text(&source.join("mmc-pack.json"))).expect("解析 mmc-pack"); + let components = pack["components"].as_array().expect("components 数组"); + assert!(!components.is_empty()); + for component in components { + let uid = component["uid"].as_str().expect("uid"); + let version = component["version"].as_str().expect("version"); + if uid == "net.minecraft" { + assert_eq!( + report.game_version.as_deref(), + Some(version), + "{uid} 要变成游戏版本" + ); + continue; + } + let as_loader = report + .loader + .as_ref() + .is_some_and(|loader| loader.raw == uid); + let as_rejected = report + .rejected_components + .iter() + .any(|rejected| rejected.uid == uid); + assert!( + as_loader || as_rejected, + "component {uid} 既没成为加载器、也没进未支持清单（= 静默丢了）" + ); + } +} + +#[test] +fn reads_memory_from_instance_cfg_only_when_override_memory_is_on() { + let root = temp_root("mmc-mem"); + let source = root.join("instance"); + write_file( + &source.join("mmc-pack.json"), + br#"{"formatVersion": 1, "components": [ + {"uid": "net.minecraft", "version": "1.20.1"}, + {"uid": "net.fabricmc.fabric-loader", "version": "0.15.11"}]}"#, + ); + write_file( + &source.join("instance.cfg"), + b"InstanceType=OneSix\nname=mem pack\nOverrideMemory=true\nMaxMemAlloc=6144\nMinMemAlloc=1024\n", + ); + write_file(&source.join(".minecraft/mods/a.jar"), b"jar"); + + let target = temp_root("mmc-mem-out").join("instance"); + let report = block_on(import_pack(&ImportRequest::new(&source, &target))); + assert_eq!(report.max_memory_mb, Some(6144), "{:?}", report.error); + assert!(report + .warnings + .iter() + .any(|note| note.message_key == keys::NOTE_INSTANCE_CFG_MEMORY)); + + // 开关没开时不采用（只看值不看开关会误判）。 + let gated = root.join("gated"); + write_file( + &gated.join("mmc-pack.json"), + br#"{"formatVersion": 1, "components": [ + {"uid": "net.minecraft", "version": "1.20.1"}]}"#, + ); + write_file( + &gated.join("instance.cfg"), + b"InstanceType=OneSix\nname=gated\nOverrideMemory=false\nMaxMemAlloc=6144\n", + ); + write_file(&gated.join(".minecraft/mods/a.jar"), b"jar"); + let gated_target = temp_root("mmc-mem-gated-out").join("instance"); + let gated_report = block_on(import_pack(&ImportRequest::new(&gated, &gated_target))); + assert_eq!(gated_report.max_memory_mb, None); + assert!(gated_report + .warnings + .iter() + .any(|note| note.message_key == keys::NOTE_INSTANCE_CFG_MEMORY)); +} + +#[test] +fn registers_the_instance_when_a_launcher_layout_is_given() { + // 登记阶段（读取清单 → 解压 → 补全 → 落地 → **注册实例**）的 happy path： + // 内容落盘后写 profiles.json + config/instances/.json。 + let root = temp_root("mmc-register"); + let source = fixtures::multimc("mmc-register-src"); + let target = root.join("instance"); + let home = root.join("data"); + let layout = crate::platform::layout::LauncherLayout::new(&home); + let request = ImportRequest::new(&source, &target).with_registration(&layout, Some("my pack")); + let report = block_on(import_pack(&request)); + + assert_eq!(report.status, ImportStatus::Success, "{:?}", report.error); + let registered = report.registered.as_ref().expect("要登记实例"); + assert_eq!(registered.name, "my pack"); + assert_eq!(registered.version_id, "1.20.1-fabric-0.15.11"); + assert!(registered.created); + // profiles.json 真的写出来了，且指回同一个版本 id。 + let profiles = crate::game::install::instance::read_profiles(&layout).expect("读档案"); + assert_eq!(profiles.profiles.len(), 1); + assert_eq!(profiles.profiles[0].version_id, "1.20.1-fabric-0.15.11"); + assert_eq!(profiles.profiles[0].name, "my pack"); + assert!(report + .warnings + .iter() + .any(|note| note.message_key == keys::NOTE_REGISTERED)); + assert!(report.rollback.is_none(), "成功路径不该有回滚记录"); +} + +#[test] +fn rejects_mmc_pack_with_other_format_version() { + // Prism 的规矩：`formatVersion` 必须恰为 1，否则整份丢弃（不是降级解析）。 + let root = temp_root("mmc-v2"); + let source = root.join("instance"); + write_file( + &source.join("mmc-pack.json"), + br#"{"formatVersion": 2, "components": [ + {"uid": "net.minecraft", "version": "1.20.1"}]}"#, + ); + write_file( + &source.join("instance.cfg"), + b"InstanceType=OneSix\nname=v2\n", + ); + write_file(&source.join(".minecraft/mods/a.jar"), b"jar"); + + let target = temp_root("mmc-v2-out").join("instance"); + let report = block_on(import_pack(&ImportRequest::new(&source, &target))); + + assert_eq!(report.status, ImportStatus::Failed); + let error = report.error.as_ref().expect("必须有具名错误"); + assert_eq!(error.code(), "pack_metadata"); + assert!( + error.message().contains("formatVersion"), + "{}", + error.message() + ); + assert!(report.rolled_back); + super::assert_absent(&target); +} diff --git a/crates/core/src/addon/tests/import_report.rs b/crates/core/src/addon/tests/import_report.rs new file mode 100644 index 0000000..8c63dd3 --- /dev/null +++ b/crates/core/src/addon/tests/import_report.rs @@ -0,0 +1,159 @@ +//! 报告的**契约**测试：三态退出码、JSON 形状、文案 key 表没有死常量。 + +use serde_json::Value; + +use crate::addon::import::{ + import_pack, keys, ImportRequest, ImportStage, ImportStatus, MissingReason, +}; +use crate::download::blocking::block_on; + +use super::support::mrpack_stub; +use super::temp_root; + +#[test] +fn status_maps_to_three_distinct_exit_codes() { + // CLI 契约：0 = Success，3 = Partial，1 = Failed（2 留给内部错误）。 + assert_eq!(ImportStatus::Success.exit_code(), 0); + assert_eq!(ImportStatus::Partial.exit_code(), 3); + assert_eq!(ImportStatus::Failed.exit_code(), 1); + // 每个状态都有独立文案 key。 + let mut keyed = vec![ + ImportStatus::Success.message_key(), + ImportStatus::Partial.message_key(), + ImportStatus::Failed.message_key(), + ]; + keyed.sort_unstable(); + keyed.dedup(); + assert_eq!(keyed.len(), 3); + // 五个阶段也各有 key，且都能进报告。 + let stages = [ + ImportStage::Probe, + ImportStage::Extract, + ImportStage::Fetch, + ImportStage::Commit, + ImportStage::Register, + ]; + assert_eq!(stages.len(), 5); + for stage in stages { + assert!(keys::ALL.contains(&stage.message_key()), "{:?}", stage); + } +} + +#[test] +fn report_serialises_to_stable_json_with_structured_error() { + // 失败也要输出结构化 JSON（不抛栈）：`status` / `error.code` / `rolled_back` 一个不少。 + let root = temp_root("report-json"); + let pack = root.join("evil.zip"); + super::write_zip(&pack, &[("manifest.json", b"{\"manifestType\":")]); + let target = root.join("instance"); + let report = block_on(import_pack(&ImportRequest::new(&pack, &target))); + + let value: Value = serde_json::to_value(&report).expect("报告要能序列化"); + assert_eq!(value["status"], Value::String("failed".to_string())); + assert_eq!(value["rolled_back"], Value::Bool(true)); + let error = value["error"].as_object().expect("error 是对象"); + assert!(error["code"].is_string(), "{error:?}"); + assert!(error["message"].is_string(), "{error:?}"); + assert_eq!(report.status.exit_code(), 1); +} + +#[test] +fn successful_report_serialises_counts_and_loader() { + let (fixture, fetcher) = mrpack_stub("report-ok"); + let target = temp_root("report-ok-out").join("instance"); + let report = block_on(import_pack( + &ImportRequest::new(&fixture.zip, &target).with_fetcher(&fetcher), + )); + assert_eq!(report.status, ImportStatus::Success, "{:?}", report.error); + + let value: Value = serde_json::to_value(&report).expect("序列化"); + assert_eq!(value["status"], Value::String("success".to_string())); + assert_eq!(value["format"], Value::String("modrinth".to_string())); + assert_eq!(value["loader"]["kind"], Value::String("fabric".to_string())); + assert_eq!( + value["loader"]["version_id"], + Value::String("1.20.1-fabric-0.15.11".to_string()) + ); + assert!(value["files"] + .as_array() + .is_some_and(|files| !files.is_empty())); + assert!(value["conflicts"].as_array().is_some_and(Vec::is_empty)); + assert!(value["missing"].as_array().is_some_and(Vec::is_empty)); +} + +#[test] +fn every_message_key_is_referenced_somewhere() { + // 防"死常量表"：keys 模块里每个常量除了**定义**与 `ALL` 里的**一处**列举，至少还要有 + // 一处真实引用（`keys::X` 或同模块里的 `X`）。少于此数就说明它没人用。 + let table = key_table(); + let mut values: Vec<&str> = table.iter().map(|(_, value)| value.as_str()).collect(); + values.sort_unstable(); + let mut declared = keys::ALL.to_vec(); + declared.sort_unstable(); + assert_eq!(values, declared, "keys::ALL 与常量定义不一致"); + + let sources = SOURCES.concat(); + let mut dead: Vec<&str> = Vec::new(); + for (name, value) in &table { + let hits = sources.matches(name.as_str()).count(); + assert!( + hits >= 3, + "key {name}（{value}）只出现 {hits} 次，像是死常量" + ); + if hits < 3 { + dead.push(name); + } + } + assert!(dead.is_empty(), "{dead:?}"); +} + +#[test] +fn reason_enums_carry_their_own_keys() { + for reason in [ + MissingReason::Offline, + MissingReason::NoSource, + MissingReason::FetchFailed, + ] { + assert!(keys::ALL.contains(&reason.message_key()), "{reason:?}"); + } +} + +/// 导入模块的全部源码（key 引用计数用）。 +const SOURCES: &[&str] = &[ + include_str!("../import.rs"), + include_str!("../import/error.rs"), + include_str!("../import/report.rs"), + include_str!("../import/report/keys.rs"), + include_str!("../import/report/items.rs"), + include_str!("../import/plan/paths.rs"), + include_str!("../import/stage/commit.rs"), + include_str!("../import/baseline.rs"), + include_str!("../import/fetch.rs"), + include_str!("../import/merge.rs"), + include_str!("../import/phase.rs"), + include_str!("../import/pipeline.rs"), + include_str!("../import/plan.rs"), + include_str!("../import/stage.rs"), + include_str!("../mod.rs"), +]; + +/// 从 `keys` 模块的源码里解析出 `(常量名, 常量值)` 表（不手抄第二份清单）。 +fn key_table() -> Vec<(String, String)> { + let source = include_str!("../import/report/keys.rs"); + let mut out = Vec::new(); + for line in source.lines() { + let line = line.trim(); + let Some(rest) = line.strip_prefix("pub const ") else { + continue; + }; + let Some((name, tail)) = rest.split_once(": &str = \"") else { + continue; + }; + let Some((value, _)) = tail.split_once('"') else { + continue; + }; + out.push((name.to_string(), value.to_string())); + } + assert!(!out.is_empty(), "没有解析到任何 key 常量"); + out +} diff --git a/crates/core/src/addon/tests/mod.rs b/crates/core/src/addon/tests/mod.rs new file mode 100644 index 0000000..6823527 --- /dev/null +++ b/crates/core/src/addon/tests/mod.rs @@ -0,0 +1,175 @@ +//! `addon` 的**导入管线**测试（M111）：三格式端到端 + 三方合并 + 必须先失败的恶意样本。 +//! +//! # 夹具来源 +//! +//! [`fixtures`] 不是本目录的文件，而是用 `#[path]` 直接吃 M110 的 +//! `addon/pack/tests/fixtures.rs`——**同一份手造包只维护一处**。它的来源声明也在那边： +//! 三份 CF / mrpack / MultiMC 包全部手造（字段取自 analyse/05 的 HMCL 解析器形状）， +//! 没有一个来自真实导出；`mods/half.jar` / `config/broken.toml` / `mods/broken.jar` +//! 是刻意造的坏文件（导入器不许崩，也不许悄悄丢）。 +//! +//! 为了让 `mod` 路径上的 `use super::{temp_root, write_file, zip_dir}` 解析得到，本文件把 +//! 这三个辅助函数放在与 `addon/pack/tests/mod.rs` 同名同形的位置。 +//! +//! # 全部离线 +//! +//! 网络一律走 [`support::StubFetcher`]（内存里的假文件），没有一个用例发请求。 + +// `fixtures.rs` 被 `addon::pack::tests` 与本目录**同时**编译（同一份手造包只维护一处）， +// 所以 clippy 的 `duplicate_mod` 在这里是刻意为之：改成两份副本才是真的错。 +#[allow(clippy::duplicate_mod)] +#[path = "../pack/tests/fixtures.rs"] +mod fixtures; +mod import_curseforge; +mod import_failures; +mod import_merge; +mod import_modrinth; +mod import_multimc; +mod import_report; +mod support; + +use std::fs::File; +use std::io::Write; +use std::path::{Path, PathBuf}; +use std::sync::atomic::{AtomicU64, Ordering}; + +/// 本次进程内唯一的临时根目录（沿用仓库既有约定：不引 `tempfile`）。 +pub(crate) fn temp_root(tag: &str) -> PathBuf { + static COUNTER: AtomicU64 = AtomicU64::new(0); + let unique = COUNTER.fetch_add(1, Ordering::Relaxed); + std::env::temp_dir().join(format!("ull-import-{}-{tag}-{unique}", std::process::id())) +} + +/// 写一个文件（自动建父目录）。 +pub(crate) fn write_file(path: &Path, bytes: &[u8]) { + if let Some(parent) = path.parent() { + std::fs::create_dir_all(parent).expect("建目录"); + } + std::fs::write(path, bytes).expect("写文件"); +} + +/// 把一个目录打成 zip（`Stored`，方便断言字节）。 +pub(crate) fn zip_dir(source: &Path, target: &Path) { + if let Some(parent) = target.parent() { + std::fs::create_dir_all(parent).expect("建 zip 目录"); + } + let file = File::create(target).expect("建 zip"); + let mut writer = zip::ZipWriter::new(file); + let options = + zip::write::SimpleFileOptions::default().compression_method(zip::CompressionMethod::Stored); + let mut pending = vec![PathBuf::new()]; + while let Some(relative) = pending.pop() { + let dir = source.join(&relative); + let mut children: Vec<_> = std::fs::read_dir(&dir) + .expect("读目录") + .collect::, _>>() + .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/support.rs b/crates/core/src/addon/tests/support.rs new file mode 100644 index 0000000..e795797 --- /dev/null +++ b/crates/core/src/addon/tests/support.rs @@ -0,0 +1,208 @@ +//! 测试替身：内存里的远端（零网络）+ 把 M110 的 mrpack 夹具改成"声明与实际一致"的帮助器。 +//! +//! # 为什么要改哈希 +//! +//! M110 的 mrpack 夹具里 `hashes` 是**形状正确的占位值**（`0123456789abcdef…`），不对应任何 +//! 真实字节——那份夹具的用途是"读得出、写得回"，不是"能装上"。导入链要校验"声明与实际 +//! 是否相符"，所以： +//! +//! - **成功路径**用 [`mrpack_stub`]：沿用同一份夹具目录，只把 `sha1` 换成真实摘要、把 +//! `downloads` 换成 `stub://` 地址（`sha512` 是占位值不影响：导入只校验 `sha1`， +//! 而 M110 的读者只校验 `sha512` 的**形状**）； +//! - **声明与实际不符**用原始夹具：占位 `sha1` 一定不等于实际字节 ⇒ 必须 `Failed`。 +//! +//! 两件事用同一份夹具，比手搓两个包更能说明"判据真的在跑"。 + +use std::collections::BTreeMap; +use std::sync::Mutex; + +use serde_json::json; + +use super::super::import::{CurseFileMeta, FetchFuture, FetchRequest, FetchedFile, PackFetcher}; +use super::fixtures; +use super::fixtures::Fixture; +use super::{write_file, zip_dir}; +use crate::download::verify::digest_bytes; +use crate::download::HashAlgo; + +/// 成功路径上 `mods/jei.jar` 的内容。 +pub(crate) const JEI_BYTES: &[u8] = b"stub jei jar: not a real jar, just bytes"; +/// 成功路径上 `mods/optional.jar` 的内容。 +pub(crate) const OPTIONAL_BYTES: &[u8] = b"stub optional"; +/// 成功路径上两个文件的下载地址。 +pub(crate) const JEI_URL: &str = "stub://mods/jei.jar"; +/// 第二个文件的下载地址。 +pub(crate) const OPTIONAL_URL: &str = "stub://mods/optional.jar"; +/// CF 夹具里两个条目的补全地址（stub）。 +pub(crate) const CURSE_URL: &str = "stub://curse/jei.jar"; +/// M110 mrpack 夹具里 `mods/jei.jar` 的**占位**下载地址（原始夹具用，配的是假哈希）。 +pub(crate) const JEI_PLACEHOLDER_URL: &str = + "https://cdn.modrinth.com/data/AANobbMI/versions/abc/jei.jar"; +/// M110 mrpack 夹具里 `mods/optional.jar` 的**占位**下载地址。 +pub(crate) const OPTIONAL_PLACEHOLDER_URL: &str = + "https://cdn.modrinth.com/data/opt/versions/x/optional.jar"; + +/// 一个字节的 SHA-1（小写十六进制）。 +pub(crate) fn sha1(bytes: &[u8]) -> String { + digest_bytes(HashAlgo::Sha1, bytes) +} + +/// 内存 fetcher：按 URL / (project, file) 查表，写盘后回成功。 +pub(crate) struct StubFetcher { + files: BTreeMap>, + curse: BTreeMap<(i64, i64), CurseFileMeta>, + /// 被请求过的 URL（断言"没白下载"用）。 + calls: Mutex>, + /// 是否像真引擎那样在目标旁边留下续传残片（`.ullpart-*` / `.ullmeta.json`）。 + artifacts: bool, +} + +impl StubFetcher { + /// 空表。 + pub(crate) fn new() -> Self { + Self { + files: BTreeMap::new(), + curse: BTreeMap::new(), + calls: Mutex::new(Vec::new()), + artifacts: false, + } + } + + /// 挂一个可下载的地址。 + pub(crate) fn with_file(mut self, url: &str, bytes: &[u8]) -> Self { + self.files.insert(url.to_string(), bytes.to_vec()); + self + } + + /// 挂一条 CurseForge 元数据。 + pub(crate) fn with_curse(mut self, project_id: i64, file_id: i64, meta: CurseFileMeta) -> Self { + self.curse.insert((project_id, file_id), meta); + self + } + + /// 像真引擎那样在每次"下载"后留下续传残片与 meta（用来钉"中间产物不许进实例"）。 + pub(crate) fn with_engine_artifacts(mut self) -> Self { + self.artifacts = true; + self + } + + /// 被请求过的 URL 列表。 + pub(crate) fn calls(&self) -> Vec { + 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 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..6757829 --- /dev/null +++ b/crates/core/src/auth/microsoft/authcode.rs @@ -0,0 +1,284 @@ +//! 授权码流（`research/08` §3 方案 A）：授权 URL 构造 + code 换 token + 整链编排。 +//! +//! 与设备码流的分工：**只多一跳**——拿 MS access_token 的方式不同，往后的 +//! XBL → XSTS → login_with_xbox → entitlements → profile 与刷新链完全复用 +//! （[`super::chain::complete_chain`]），所以两条流的凭据存储与刷新语义天然一致。 +//! +//! # 三个硬性细节（都是「抄错就失败」的那一类） +//! +//! 1. **租户 `consumers`**：授权页与 token 端点都走 `login.microsoftonline.com/consumers/…`， +//! 换成 `common`/AAD 租户 id 时 `XboxLive.signin` 直接被拒（`research/08` §2 约束 1）。 +//! 2. **重定向 URI 严格一致**：`http://localhost:{port}/auth` —— 授权 URL 里的、 +//! token 请求体里的、本地服务器实际监听的必须是**同一个字符串**（含端口与路径）， +//! 所以本模块只从 [`RedirectUri`] 取这一个来源。 +//! 3. **`prompt=select_account`**：不带这个参数，用户会被静默塞进上一次的账号（坑 6）。 +//! +//! scope 与设备码流共用 [`super::flow::SCOPE`]（`XboxLive.signin offline_access`）。 + +use std::fmt; +use std::time::{Duration, SystemTime, UNIX_EPOCH}; + +use reqwest::Client; + +use crate::auth::error::AuthResult; +use crate::auth::http::post_form; +use crate::auth::secret::Secret; + +use super::callback::{CallbackServer, REDIRECT_PATH}; +use super::chain::complete_chain; +use super::endpoints::MicrosoftEndpoints; +use super::flow::{oauth_error, tokens_from, OAuthTokens, SCOPE}; +use super::now_ms; +use super::session::MicrosoftSession; + +/// 授权码 grant 类型。 +pub const AUTHORIZATION_CODE_GRANT: &str = "authorization_code"; +/// 默认等回调的时间预算（用户要开浏览器、登录、点同意）。 +pub const DEFAULT_CALLBACK_TIMEOUT: Duration = Duration::from_secs(300); +/// 默认的端口绑定尝试次数。 +pub const DEFAULT_BIND_ATTEMPTS: u8 = 3; + +/// 回填到授权 URL 与 token 请求里的重定向 URI（**唯一来源**）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct RedirectUri { + port: u16, + url: String, +} + +impl RedirectUri { + /// 按实际绑定的端口构造 `http://localhost:{port}/auth`。 + /// + /// 用 `localhost` 而不是 `127.0.0.1`：微软对两者处理不一致（`research/08` 坑 5）。 + #[must_use] + pub fn new(port: u16) -> Self { + Self { + port, + url: format!("http://localhost:{port}{REDIRECT_PATH}"), + } + } + + /// 端口。 + #[must_use] + pub fn port(&self) -> u16 { + self.port + } + + /// URI 字面量（授权 URL 与 token 请求共用，保证逐字节一致）。 + #[must_use] + pub fn as_str(&self) -> &str { + &self.url + } +} + +impl fmt::Display for RedirectUri { + fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { + formatter.write_str(&self.url) + } +} + +/// 授权码流的运行参数（生产用 [`AuthCodePolicy::default`]，测试压短超时/固定端口）。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct AuthCodePolicy { + /// 等浏览器回调的上限。 + pub callback_timeout: Duration, + /// 端口绑定尝试次数（`>= 1`）。 + pub bind_attempts: u8, + /// 固定端口（`None` = 由内核分配，生产路径）。 + pub port: Option, + /// 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), +{ + let state = policy.state.clone().unwrap_or_else(nonce); + let server = CallbackServer::bind(policy.port, policy.bind_attempts, state.clone()).await?; + let redirect_uri = RedirectUri::new(server.port()); + present(&AuthCodePrompt { + authorization_url: authorization_url(endpoints, client_id, &redirect_uri, &state), + redirect_uri: redirect_uri.as_str().to_string(), + timeout: policy.callback_timeout, + }); + let code = server.wait_for_code(policy.callback_timeout).await?; + let tokens = exchange_code( + client, + endpoints, + client_id, + &Secret::new(code), + &redirect_uri, + ) + .await?; + complete_chain(client, endpoints, tokens, now_ms()).await +} + +/// 每次登录一个 `state`（不用于加密，只用来把迟到的旧回调挡掉）。 +/// +/// 128 位（两个独立随机种子的 SipHash 输出拼接）：RFC 6749 §10.10 建议 `state` 至少 +/// 128 位熵，挡住「猜到 state 就能伪造回调」这类攻击面。 +fn nonce() -> String { + use std::collections::hash_map::RandomState; + use std::hash::{BuildHasher, Hasher}; + + let nanos = SystemTime::now() + .duration_since(UNIX_EPOCH) + .map(|since| since.as_nanos()) + .unwrap_or(0); + let mut halves = [String::new(), String::new()]; + for half in &mut halves { + // 每次 `RandomState::new()` 都是独立随机种子 → 两段各 64 位、彼此不可推。 + let mut hasher = RandomState::new().build_hasher(); + hasher.write_u128(nanos); + hasher.write_u32(std::process::id()); + *half = format!("{:016x}", hasher.finish()); + } + format!("{}{}", halves[0], halves[1]) +} + +/// 百分号编码（RFC 3986 unreserved 之外一律转义；空格用 `%20` 而不是 `+`）。 +fn encode(raw: &str) -> String { + let mut out = String::with_capacity(raw.len()); + for byte in raw.bytes() { + match byte { + b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'.' | b'_' | b'~' => { + out.push(char::from(byte)); + } + _ => out.push_str(&format!("%{byte:02X}")), + } + } + out +} + +#[cfg(test)] +mod tests { + use super::{authorization_url, encode, RedirectUri, AUTHORIZATION_CODE_GRANT}; + use crate::auth::microsoft::MicrosoftEndpoints; + + #[test] + fn redirect_uri_is_localhost_with_exact_port_and_path() { + let uri = RedirectUri::new(51_234); + assert_eq!(uri.as_str(), "http://localhost:51234/auth"); + assert_eq!(uri.port(), 51_234); + assert_eq!(uri.to_string(), uri.as_str()); + } + + #[test] + fn authorization_url_matches_research_08_vector() { + let endpoints = MicrosoftEndpoints::consumers(); + let uri = RedirectUri::new(8_080); + let url = authorization_url(&endpoints, "0000-client", &uri, "state-123"); + assert_eq!( + url, + "https://login.microsoftonline.com/consumers/oauth2/v2.0/authorize\ +?client_id=0000-client&response_type=code\ +&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Fauth\ +&scope=XboxLive.signin%20offline_access&prompt=select_account&state=state-123" + ); + // 三个硬性细节各断言一遍，改坏了立刻知道是哪一条。 + assert!(url.contains("/consumers/oauth2/v2.0/authorize")); + assert!(url.contains("prompt=select_account")); + assert!(url.contains("scope=XboxLive.signin%20offline_access")); + } + + #[test] + fn encode_escapes_everything_but_unreserved() { + assert_eq!(encode("abc-._~09"), "abc-._~09"); + assert_eq!(encode("a b/c:"), "a%20b%2Fc%3A"); + } + + #[test] + fn grant_type_is_the_standard_one() { + assert_eq!(AUTHORIZATION_CODE_GRANT, "authorization_code"); + } + + #[test] + fn generated_state_has_128_bits_of_entropy() { + let first = super::nonce(); + let second = super::nonce(); + assert_eq!(first.len(), 32, "128 位 = 32 个 hex 字符：{first}"); + assert!(first.chars().all(|c| c.is_ascii_hexdigit()), "{first}"); + assert_ne!(first, second, "每次登录的 state 必须不同"); + } +} diff --git a/crates/core/src/auth/microsoft/callback.rs b/crates/core/src/auth/microsoft/callback.rs new file mode 100644 index 0000000..2e8a27c --- /dev/null +++ b/crates/core/src/auth/microsoft/callback.rs @@ -0,0 +1,346 @@ +//! 授权码流的本地回调服务器（`research/08` §3 方案 A：HMCL 主流做法）。 +//! +//! 只干一件事：等浏览器把 `?code=` 送到 `http://localhost:{port}/auth`，把 code 交出去。 +//! 协议面故意压到最小（只认一个 GET 路径、只回一个静态页），这样它能被单测直接驱动。 +//! +//! # 四条容易踩的细节 +//! +//! 1. **重定向 URI 用 `localhost`，监听绑 `127.0.0.1`**：微软对 `localhost` 与 `127.0.0.1` +//! 处理不一致（坑 5），URI 只能写前者；浏览器把 `localhost` 解析到 `::1` 时会被拒一次 +//! 再回落 IPv4，Chrome/Edge 都走这条回退，所以只绑 v4 就够。 +//! 2. **端口由内核分配**（绑定 `:0`），端口被占时按 `attempts` 重试；授权 URL 里的 +//! `redirect_uri` 必须用**最终绑到的端口**回填，换 token 时再原样带上（URI 严格一致）。 +//! 3. **非 `/auth` 的请求（`/favicon.ico`、浏览器预连）回 404 后继续等**：让一个 favicon +//! 把整次登录判成失败是最容易犯的错。 +//! 4. **`state` 不匹配的请求一律回 400 后继续等**——包括带 `error=` 的那些：旧标签页的 +//! 迟到回调不该打断新的登录，更要紧的是 RFC 6749 §4.1.2.1 / RFC 9207 要求**错误响应同样 +//! 要校验 `state`**；否则任何人 `GET /auth?error=access_denied` 就能静默中止别人的登录。 +//! 真正的超时由调用方的时间预算兜底。 + +use std::time::Duration; + +use tokio::io::{AsyncReadExt, AsyncWriteExt}; +use tokio::net::{TcpListener, TcpStream}; + +use crate::auth::error::{AuthError, AuthResult}; + +/// 回调路径（重定向 URI 的路径段）。 +pub const REDIRECT_PATH: &str = "/auth"; +/// 一次回调请求最多读这么多字节（超了就丢弃连接，防被灌内存）。 +pub const MAX_REQUEST_HEAD: usize = 8 * 1024; +/// 端口被占用时的重试间隔。 +const RETRY_DELAY: Duration = Duration::from_millis(20); +/// 单条连接读完请求头的上限（浏览器/预连不把请求头发完时不能把整个登录卡死）。 +const REQUEST_READ_TIMEOUT: Duration = Duration::from_secs(5); + +const SUCCESS_PAGE: &str = "\ +登录完成\ +

登录完成

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

"; +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 { + let wanted = port.unwrap_or(0); + let attempts = attempts.max(1); + let mut last = String::new(); + for attempt in 0..attempts { + match TcpListener::bind(("127.0.0.1", wanted)).await { + Ok(listener) => { + let port = listener + .local_addr() + .map_err(|error| AuthError::network("localhost", error.to_string()))? + .port(); + return Ok(Self { + listener, + port, + state: state.into(), + }); + } + Err(error) => { + last = error.to_string(); + if attempt + 1 < attempts { + tokio::time::sleep(RETRY_DELAY).await; + } + } + } + } + let what = if wanted == 0 { + "本地回调端口分配失败".to_string() + } else { + format!("本地回调端口 {wanted} 绑定失败（重试 {attempts} 次）") + }; + Err(AuthError::network("localhost", format!("{what}：{last}"))) + } + + /// 实际端口（回填 `redirect_uri` 用）。 + #[must_use] + pub fn port(&self) -> u16 { + self.port + } + + /// 本次登录的 `state`（授权 URL 与回调校验共用）。 + #[must_use] + pub fn state(&self) -> &str { + &self.state + } + + /// 等浏览器把 code 送到 `/auth`，最多等 `timeout`。 + /// + /// # Errors + /// + /// 超时（[`AuthError::Timeout`]）、用户在授权页点了取消（[`AuthError::Canceled`]）、 + /// 授权页回了别的 `error`（[`AuthError::Denied`]）、socket 出错（[`AuthError::Network`]）。 + pub async fn wait_for_code(self, timeout: Duration) -> AuthResult { + 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..d7194fb --- /dev/null +++ b/crates/core/src/auth/microsoft/client_id.rs @@ -0,0 +1,248 @@ +//! Azure 公共客户端 id 的**配置状态**：从哪来、配没配、启动日志那一行长什么样。 +//! +//! ## 为什么单独一块（M117） +//! +//! 这个 id 不进仓库（用户定案），所以它可以来自两处：运行期环境变量 [`CLIENT_ID_ENV`]， +//! 或构建期 `option_env!` 注入（[`CLIENT_ID_BUILD`]）。**两处都没有**时登录是「没配置」， +//! 不是「没实现」——这两件事在用户眼里完全不同，文案与日志都必须分清： +//! +//! | 现象 | 该说什么 | +//! |---|---| +//! | 两处都没配 | [`MISSING_CLIENT_ID_MESSAGE`]：未配置 + 怎么配（含可照抄的命令） | +//! | 配了但登录失败 | 走 `AuthError` 的正常分流（网络/拒绝/无拥有权…），**不许**再提「未实现」 | +//! +//! [`ClientIdStatus::log_line`] 是给启动日志的那一行：`[auth] msa client_id=… source=…`。 +//! 有了它，「未配置」与「配了但登录失败」在日志里一眼可分，不用再猜。 +//! +//! 本模块**零网络**：只读环境变量与编译期常量，连 HTTP 客户端都不建。 + +/// 运行期环境变量名（配 client id）。 +pub const CLIENT_ID_ENV: &str = "ULL_MSA_CLIENT_ID"; + +/// 构建期可注入的 client id（`ULL_MSA_CLIENT_ID= cargo build`）。 +pub const CLIENT_ID_BUILD: Option<&str> = option_env!("ULL_MSA_CLIENT_ID"); + +/// 两处都没配时给用户看的那句话（CLI / GUI / 启动日志共用，**不含任何真实 id**）。 +/// +/// 措辞纪律（M117）：说「未配置」，不说「未支持」——登录链路是完整的，缺的只是这一项； +/// 并且句子里带**可照抄的命令**，因为失败横幅往往是用户唯一会看到的那段字。 +pub const MISSING_CLIENT_ID_MESSAGE: &str = + "微软登录未配置：缺少 Azure 公共客户端 id（登录功能已实现，只差这一项配置）。\ +构建时注入：`ULL_MSA_CLIENT_ID= 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)] +mod tests { + use std::sync::Mutex; + + use super::{ + client_id_status, resolve_client_id, ClientIdSource, CLIENT_ID_BUILD, CLIENT_ID_ENV, + MISSING_CLIENT_ID_MESSAGE, + }; + use crate::auth::error::AuthError; + use crate::auth::microsoft::MicrosoftAuth; + + /// 环境变量是**进程级**的：动它的用例必须串行，否则并行跑会互相摘/设，结论随机。 + static ENV_LOCK: Mutex<()> = Mutex::new(()); + + /// 用例结束后把环境变量还原（panic 也还原：`Drop` 跑得到）。 + struct EnvGuard { + saved: Option, + } + + 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 时唯一合法（本仓库 CI/本地都不注入，走不到这里）。 + Ok(_) => assert!( + CLIENT_ID_BUILD.is_some_and(|value| !value.trim().is_empty()), + "没配 id 却构造成功" + ), + Err(other) => panic!("应是 Unsupported，实际 {other:?}"), + } + } + + #[test] + fn env_client_id_wins_over_build_and_the_log_says_so() { + let _lock = ENV_LOCK.lock().unwrap_or_else(|error| error.into_inner()); + let _guard = EnvGuard::set("0000-test-env-id"); + + let (id, source) = resolve_client_id().expect("环境变量给了 id"); + assert_eq!(id, "0000-test-env-id"); + // 两者都存在时环境变量优先，且**不告警**，但来源必须是 env。 + assert_eq!(source, ClientIdSource::Env); + + let status = client_id_status(); + assert!(status.is_configured()); + assert_eq!(status.source(), Some(ClientIdSource::Env)); + assert_eq!( + status.log_line(), + "[auth] msa client_id=configured source=env" + ); + + // 有 id 时**不再报配置错误**：只验到「进得了登录流程的入口」为止， + // `from_env` 本身零网络（它只建 reqwest 客户端，不发请求）。 + let auth = MicrosoftAuth::from_env().expect("配了 id 就该构造成功"); + assert!(auth.endpoints().profile.contains("minecraftservices.com")); + } + + #[test] + fn missing_client_id_log_line_is_machine_readable() { + let _lock = ENV_LOCK.lock().unwrap_or_else(|error| error.into_inner()); + let _guard = EnvGuard::clear(); + if CLIENT_ID_BUILD.is_some_and(|value| !value.trim().is_empty()) { + // 构建期注入过 id：这条没有「缺配置」可言，跳过。 + return; + } + let status = client_id_status(); + assert!(!status.is_configured()); + assert_eq!(status.source(), None); + assert_eq!( + status.log_line(), + "[auth] msa client_id=missing source=none" + ); + } + + #[test] + fn blank_env_value_counts_as_missing() { + // 抓得住：`ULL_MSA_CLIENT_ID=""`（空串/全空白）被当成配好了，进而拿空 id 去联网。 + let _lock = ENV_LOCK.lock().unwrap_or_else(|error| error.into_inner()); + let _guard = EnvGuard::set(" "); + if CLIENT_ID_BUILD.is_some_and(|value| !value.trim().is_empty()) { + assert_eq!( + resolve_client_id().map(|(_, source)| source), + Some(ClientIdSource::Build), + "空白环境变量必须让位给构建期注入" + ); + } else { + assert!(resolve_client_id().is_none()); + } + } +} diff --git a/crates/core/src/auth/microsoft/endpoints.rs b/crates/core/src/auth/microsoft/endpoints.rs new file mode 100644 index 0000000..bea5f1c --- /dev/null +++ b/crates/core/src/auth/microsoft/endpoints.rs @@ -0,0 +1,132 @@ +//! 微软端点表：**直连**（不走镜像，承 mission Context 与 `analyse/04` §4 的端点族区分）。 +//! +//! 两条流**共用同一个端点族**（`research/08` §2 硬性约束 1：租户只能用 `consumers`）： +//! - 设备码流：`devicecode` + `token`； +//! - 授权码流：`authorize`（浏览器打开）+ 同一个 `token`（`grant_type=authorization_code`）。 +//! +//! 都走 `login.microsoftonline.com/consumers/oauth2/v2.0/*`：用 `common` 或 AAD 租户 id +//! 拿 `XboxLive.signin` 会直接被拒（`analyse/04` §4 的「第一个坑」）。 +//! +//! 端点集中成一张表是为了**测试可替换**：整表指向一个进程内 mock 服务器即可覆盖全链， +//! 生产默认走 [`MicrosoftEndpoints::consumers`]。 + +/// 微软账户 OAuth 与 Xbox / Minecraft 服务端点。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct MicrosoftEndpoints { + /// 设备码申请（`POST`，表单 `client_id` + `scope`）。 + pub device_code: String, + /// 授权码流的授权页（`GET`，浏览器打开；`research/08` §3 方案 A）。 + pub authorize: String, + /// 换 token / 刷新 token / 授权码换 token（`POST`，表单）。 + pub token: String, + /// Xbox Live 用户认证（`POST` JSON）。 + pub xbl_authenticate: String, + /// XSTS 授权（`POST` JSON；无 Xbox 档案时回 **401** 带 `XErr`）。 + pub xsts_authorize: String, + /// `login_with_xbox`（`POST` JSON，`identityToken = "XBL3.0 x=;"`）。 + 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/mod.rs b/crates/core/src/auth/microsoft/mod.rs new file mode 100644 index 0000000..ec8c3af --- /dev/null +++ b/crates/core/src/auth/microsoft/mod.rs @@ -0,0 +1,366 @@ +//! 微软轨：device-code 与授权码（浏览器）两条登录流 + 会话/刷新语义 +//! （`PlanDoc/07-accounts.md` §1、`analyse/04` §4–§5、`research/08` §3）。 +//! +//! 分六块，各管一件事： +//! - [`client_id`]：Azure 公共客户端 id 的**配置状态**（来源 / 配没配 / 启动日志那一行，零网络）； +//! - [`session`]：`MicrosoftSession`（凭据载荷）与**刷新判定**（纯函数，可脱离网络单测）； +//! - [`endpoints`]：端点表（生产 = 微软消费版直连；测试 = 整表指向 mock）； +//! - [`flow`]：device-code 发起 / 轮询 / refresh（OAuth 层）； +//! - [`authcode`] + [`callback`]：授权码流（授权 URL + 本地 HTTP 回调服务器 + code 换 token）； +//! - [`chain`]：XBL → XSTS → login_with_xbox → entitlements → profile（Xbox/MC 层）。 +//! +//! 两条流只差「怎么拿到 MS access_token」：拿到之后都进同一个 [`chain::complete_chain`]， +//! 落盘/刷新也共用 [`MicrosoftSession`]，所以 GUI 账户页的两颗按钮不会长出两套凭据语义。 +//! +//! # client id 从哪来 +//! +//! 两条流都必须带一个**已在 Azure 注册的公共客户端 id**（且租户是 `consumers`、 +//! 重定向 URI 登记为 `http://localhost`）。HMCL 把它烘进 jar 的 +//! manifest（`hmcl.microsoft.auth.id`），我们同理：二进制里不硬编码，改由 +//! `ULL_MSA_CLIENT_ID`（运行期）或构建期 `option_env!` 提供。没有配时 +//! [`MicrosoftAuth::from_env`] 返回 [`AuthError::Unsupported`]，文案是 +//! [`client_id::MISSING_CLIENT_ID_MESSAGE`]（「未配置」+ 怎么配，见 [`client_id`]）—— +//! 这比编一个假 id 让用户看到 `invalid_client` 诚实。 +//! +//! 措辞纪律（M117）：id 缺失是**没配置**，不是「本期未支持」。判定与那行启动日志都在 +//! [`client_id`]，本模块只消费结论。 + +pub mod authcode; +pub mod callback; +pub mod chain; +pub mod client_id; +pub mod endpoints; +pub mod flow; + +pub mod session; + +pub use authcode::{AuthCodePolicy, AuthCodePrompt, RedirectUri}; +pub use callback::CallbackServer; +// client id 的判定与启动日志行留一层 re-export：调用方（CLI / GUI / 启动日志）只认 +// `auth::microsoft::*` 这一条路径，不必知道它是单独一块（M117）。 +pub use client_id::{ + client_id_status, resolve_client_id, ClientIdSource, ClientIdStatus, CLIENT_ID_BUILD, + CLIENT_ID_ENV, MISSING_CLIENT_ID_MESSAGE, +}; +pub use endpoints::MicrosoftEndpoints; +pub use flow::{DeviceCodePrompt, PollPolicy}; +pub use session::{MicrosoftSession, RefreshDecision, RefreshReason, USER_TYPE_MSA}; + +use std::time::{SystemTime, UNIX_EPOCH}; + +use reqwest::Client; + +use crate::auth::error::{AuthError, AuthResult}; +use crate::auth::journal::{AuthFailureEvent, AuthJournal}; +use crate::download::config::EngineConfig; +use crate::download::http::build_client; + +/// 微软账户登录/刷新。 +#[derive(Debug, Clone)] +pub struct MicrosoftAuth { + client: Client, + client_id: String, + endpoints: MicrosoftEndpoints, + poll: PollPolicy, + authcode: AuthCodePolicy, + journal: Option, +} + +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(), + 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 + } + + /// 当前端点表。 + #[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")); + } + + #[test] + fn now_ms_is_sane() { + // 2020-01-01 之后、2100 之前（防止本地时钟/单位抄错）。 + let now = now_ms(); + assert!(now > 1_577_836_800_000); + assert!(now < 4_102_444_800_000); + } +} diff --git a/crates/core/src/auth/microsoft/session.rs b/crates/core/src/auth/microsoft/session.rs new file mode 100644 index 0000000..b6df49b --- /dev/null +++ b/crates/core/src/auth/microsoft/session.rs @@ -0,0 +1,231 @@ +//! 微软会话与刷新语义：**HMCL 三层判定的类型化版本**（`analyse/04` §5.3 / §3.5 / §8.4）。 +//! +//! 三层判定原样平移： +//! 1. `has_profile_name()`：没有玩家名就没法启动（`--username` 不能为空）； +//! 2. `not_after`：本地时间戳过期即视为未登录（省一次网络）； +//! 3. 进程内 `authenticated` 标记归宿主（GUI/CLI）持有，不在本类型里。 +//! +//! 关键语义（照 HMCL，别自己发明）： +//! - 存下来的 `refresh_token` 是 **Live（MSA）** 的，`access_token` 是 **Minecraft** 的； +//! - 刷新 = 整条链重跑（Live refresh → XBL → XSTS → login_with_xbox → entitlements → profile）， +//! 不存在「只刷 MC token」的捷径； +//! - `profile_name` 属于**可变的私有缓存**（2022 年后允许改名），元数据里只留不可变的 profileID。 + +use serde::{Deserialize, Serialize}; + +use crate::auth::error::{AuthError, AuthResult}; +use crate::auth::secret::Secret; +use crate::launch::request::AuthPlaceholders; + +/// 微软账户的 launch 用户类型（`AuthInfo.USER_TYPE_MSA`）。 +pub const USER_TYPE_MSA: &str = "msa"; + +/// 一次成功登录后的会话（= 该账户的凭据载荷）。 +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct MicrosoftSession { + /// Minecraft 档案 UUID（32 位无连字符）。**不可变**。 + pub profile_id: String, + /// 玩家名（可空串：磁盘恢复允许「有档案但名字未知」，登录时补齐）。 + #[serde(default)] + pub profile_name: String, + /// MC token 类型（`Bearer`）。 + pub token_type: String, + /// Minecraft access token。 + pub access_token: Secret, + /// Live refresh token（轮换：每次刷新都会被新值整体覆盖）。 + pub refresh_token: Secret, + /// MC token 过期时刻（Unix 毫秒；0 = 未知 → 强制刷新）。 + pub not_after_ms: u64, + /// Xbox user id（`XUID`，诊断/排障用，非凭据）。 + pub user_id: Option, +} + +/// 过期判定的结论。 +#[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..d026f43 --- /dev/null +++ b/crates/core/src/diagnose/mod.rs @@ -0,0 +1,17 @@ +//! 崩溃诊断：五类信号采集（含 hs_err_pid 解析）、YAML 规则引擎（59 条规则起步，可热更新）、 +//! exit0 静默失败检测、结构化诊断结论。 +//! +//! 设计定稿：`DevDocs/PlanDoc/06-launch-and-diagnostics.md` §2（采集 / 规则 / 流水线）。 +//! 定位：规则引擎为主、AI 补位；AI 拿到的应是「规则结论 + 相关片段」而非裸日志 +//! （`DevDocs/PlanDoc/02-ai-agent-design.md` §3.2）。 +//! +//! 规划中的公共面（M15）：信号采集、规则匹配、诊断报告、规则热加载。 + +// 只有这五个顶层模块；子模块（collectors 下的 signals/sources/environment、engine 下的 +// finding/synthetic、hs_err 下的 hs_err_report、rules 下的 fix_action/fix_params）由各自的 +// 父文件用 #[path] 声明。这里**不要**重复声明，否则同一文件会被编译成两份不同类型。 +pub mod collectors; +pub mod engine; +pub mod hs_err; +pub mod loader; +pub mod rules; diff --git a/crates/core/src/diagnose/rules.d/fabric.yaml b/crates/core/src/diagnose/rules.d/fabric.yaml new file mode 100644 index 0000000..9a9db85 --- /dev/null +++ b/crates/core/src/diagnose/rules.d/fabric.yaml @@ -0,0 +1,141 @@ +# 规则库 · Fabric mod 解析（8 条） +# 移植自 HMCL CrashReportAnalyzer.Rule 的 Fabric 组（analyse/02 §7.3 第 5 组）。 +# Fabric 的 ModResolutionException 家族特征：异常后面跟一段以 " - " 开头的列表， +# 因此这些规则用 file scope（跨行）。 +version: 1 +category: fabric +rules: + - id: fabric.mod_resolution + severity: critical + scope: file + pattern: 'ModResolutionException: (?(.*)[\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/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..1a3c4f2
--- /dev/null
+++ b/crates/core/src/download/blocking.rs
@@ -0,0 +1,55 @@
+//! 同步桥：让**非 async 宿主**驱动异步下载引擎。
+//!
+//! `core::download` 的引擎是异步的（tokio + reqwest），GUI 侧自带运行时；
+//! 但 headless 消费者（`crates/cli` 的 `ull`）不依赖 tokio，也不该为一次安装
+//! 把整个异步运行时依赖树拉进 CLI 的 manifest（D18：CLI 依赖树保持干净）。
+//!
+//! 因此把「建一个短命运行时 + 跑完整段 future」这两件事收在 core 里：
+//!
+//! ```ignore
+//! let outcome = unlucky_core::download::blocking::block_on(async { /* 规划 + 下载 */ });
+//! ```
+//!
+//! 约定：**整段**安装流程包在一次 `block_on` 里（同一个运行时），不要每次下载都建一个——
+//! reqwest 的连接池绑定在创建它的运行时上，跨运行时会退化甚至报「dispatch task is gone」。
+//!
+//! 这是给「单线程 CLI」用的逃生口，不是通用设施：app 层请直接用原生异步。
+
+use std::future::Future;
+
+/// 在一个临时 tokio 多线程运行时上跑完 `future`。
+///
+/// 运行时随调用结束销毁，因此适合「一条命令一次阻塞」的 CLI 生命周期。
+///
+/// # Panics
+///
+/// 运行时建不起来（系统资源耗尽）时 panic：此时进程已无法继续，早点暴露比静默降级好。
+/// 在已有 tokio 运行时上下文里调用同样会 panic（tokio 不允许嵌套 `block_on`）。
+pub fn block_on(future: F) -> F::Output {
+    let runtime = tokio::runtime::Builder::new_multi_thread()
+        .worker_threads(2)
+        .thread_name("ull-blocking")
+        .enable_all()
+        .build()
+        .expect("创建 tokio 运行时失败（内存/线程资源不足）");
+    runtime.block_on(future)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::block_on;
+
+    #[test]
+    fn drives_a_plain_future_to_completion() {
+        assert_eq!(block_on(async { 1 + 1 }), 2);
+    }
+
+    #[test]
+    fn drives_tokio_timers() {
+        let start = std::time::Instant::now();
+        block_on(async {
+            tokio::time::sleep(std::time::Duration::from_millis(5)).await;
+        });
+        assert!(start.elapsed() >= std::time::Duration::from_millis(5));
+    }
+}
diff --git a/crates/core/src/download/bytes.rs b/crates/core/src/download/bytes.rs
new file mode 100644
index 0000000..f191f51
--- /dev/null
+++ b/crates/core/src/download/bytes.rs
@@ -0,0 +1,138 @@
+//! 内存下载：版本清单 / 版本 JSON / 资源索引这类「小文本」资源。
+//!
+//! 与文件下载共用候选源、退避与健康度逻辑，但不续传、不分块——它们要么很小，
+//! 要么强时效（`ETag` 语义比续传更合适）。
+
+use std::time::Instant;
+
+use super::cache::now_ms;
+use super::engine::{millis, DownloadEngine};
+use super::error::{DownloadError, DownloadErrorKind};
+use super::http;
+use super::progress::ProgressEvent;
+use super::types::{Candidate, DownloadId, DownloadRequest};
+use super::verify;
+
+/// 内存下载的上限（manifest 类资源不该有几十 MB；防御恶意镜像把人撑爆）。
+pub const MAX_IN_MEMORY_BYTES: u64 = 64 * 1024 * 1024;
+
+impl DownloadEngine {
+    /// 内存下载（版本清单 / 版本 JSON / 索引等小文本资源）。
+    pub async fn download_bytes(&self, req: DownloadRequest) -> Result, 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();
+
+        for candidate in &plan {
+            // 与文件下载同一套规则：冷却中/刚出冷却的源只给一次探测机会。
+            let max_attempts = self.attempts_for(&candidate.source, req.kind, now_ms());
+            for attempt in 0..max_attempts {
+                match self.fetch_bytes(&req, candidate).await {
+                    Ok(bytes) => {
+                        self.health.record_success(
+                            &candidate.source,
+                            req.kind,
+                            started.elapsed(),
+                            now_ms(),
+                        );
+                        self.emit(ProgressEvent::Completed {
+                            id,
+                            bytes: bytes.len() as u64,
+                            from_cache: false,
+                            source: candidate.source.clone(),
+                            elapsed_ms: millis(started.elapsed()),
+                        });
+                        self.flush_health();
+                        return Ok(bytes);
+                    }
+                    Err(err) => {
+                        self.health.record_failure(
+                            &candidate.source,
+                            req.kind,
+                            &err.message,
+                            now_ms(),
+                        );
+                        let retry = err.kind.is_retryable() && attempt + 1 < max_attempts;
+                        let delay = self.next_delay(attempt);
+                        self.emit(ProgressEvent::SourceFailed {
+                            id,
+                            source: candidate.source.clone(),
+                            reason: err.message.clone(),
+                            attempt,
+                            will_retry: retry,
+                            retry_in_ms: if retry { millis(delay) } else { 0 },
+                        });
+                        if !retry {
+                            suppressed.push(format!("{}: {}", candidate.source, err.message));
+                            break;
+                        }
+                        tokio::time::sleep(delay).await;
+                    }
+                }
+            }
+        }
+
+        self.flush_health();
+        Err(DownloadError::new(
+            DownloadErrorKind::AllSourcesFailed,
+            format!("所有候选源都取不到文本资源：{}", req.url),
+        )
+        .with_suppressed(suppressed))
+    }
+
+    async fn fetch_bytes(
+        &self,
+        req: &DownloadRequest,
+        candidate: &Candidate,
+    ) -> Result, 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..8fcf892
--- /dev/null
+++ b/crates/core/src/download/config.rs
@@ -0,0 +1,46 @@
+//! 引擎配置：设置层（core::setting）直接映射到这里。
+
+use std::time::Duration;
+
+use super::backoff::BackoffPolicy;
+use super::chunked::ChunkedConfig;
+use super::types::ResumePolicy;
+
+/// 引擎配置。
+#[derive(Debug, Clone)]
+pub struct EngineConfig {
+    /// 全局并发许可数（tokio `Semaphore`），默认 64。
+    pub max_concurrency: usize,
+    /// 每个源的尝试次数上限，默认 3。
+    pub max_attempts_per_source: u32,
+    /// 连接超时，默认 10s。
+    pub connect_timeout: Duration,
+    /// 单次读超时（读空闲判定，不是整体超时），默认 30s。
+    pub read_timeout: Duration,
+    /// User-Agent。
+    pub user_agent: String,
+    /// 进度事件节流间隔，默认 250ms。
+    pub progress_throttle: Duration,
+    /// 退避策略。
+    pub backoff: BackoffPolicy,
+    /// 分块下载配置。
+    pub chunked: ChunkedConfig,
+    /// 默认续传策略（请求级 `Never` 优先级更高）。
+    pub resume: ResumePolicy,
+}
+
+impl Default for EngineConfig {
+    fn default() -> Self {
+        Self {
+            max_concurrency: 64,
+            max_attempts_per_source: 3,
+            connect_timeout: Duration::from_secs(10),
+            read_timeout: Duration::from_secs(30),
+            user_agent: concat!("UnluckyLauncher/", env!("CARGO_PKG_VERSION")).to_string(),
+            progress_throttle: Duration::from_millis(250),
+            backoff: BackoffPolicy::default(),
+            chunked: ChunkedConfig::default(),
+            resume: ResumePolicy::Conservative,
+        }
+    }
+}
diff --git a/crates/core/src/download/engine.rs b/crates/core/src/download/engine.rs
new file mode 100644
index 0000000..1c73895
--- /dev/null
+++ b/crates/core/src/download/engine.rs
@@ -0,0 +1,397 @@
+//! 下载引擎：编排层。
+//!
+//! 一次 `download()` 的固定剧情：
+//!
+//! ```text
+//! 校验请求 → 内容寻址缓存直取（零网络）
+//!          → 候选规划（镜像表展开 + 健康度排序）
+//!          → Semaphore 限流
+//!          → 候选源外循环（换源），每源内循环（指数退避 + 抖动）
+//!              → 续传判定（保守）→ 单连接 / 多连接分块 → 流式校验 → 原子落盘
+//!          → 失败则保留中间文件供下次续传
+//! ```
+//!
+//! 最后一步保留的是**本会话命名的**中间文件（`.ullpart--`，不再固定
+//! 叫 `.ullpart`）：下次（甚至下次启动、重启后再下同一个文件）由 `PartFile::for_dest`
+//! 在目标目录里认领它并改名成新的会话名，续传判定照旧。详细身份规则见 `atomic.rs` 模块头的
+//! 「中间文件的身份」。
+//!
+//! 具体传输细节在 `transfer.rs`，错误分类在 `http.rs`，本文件只负责顺序与策略。
+
+use std::path::Path;
+use std::sync::Arc;
+use std::time::{Duration, Instant};
+
+use tokio::sync::Semaphore;
+
+use super::atomic::PartFile;
+use super::backoff::Jitter;
+use super::cache::{now_ms, ContentCache};
+use super::config::EngineConfig;
+use super::error::{DownloadError, DownloadErrorKind};
+use super::health::HealthRegistry;
+use super::http;
+use super::mirrors::MirrorTable;
+use super::progress::{ProgressEmitter, ProgressEvent};
+use super::region::RegionProfile;
+use super::types::{
+    Candidate, DownloadId, DownloadOutcome, DownloadRequest, ResourceKind, ResumePolicy,
+    SOURCE_OFFICIAL,
+};
+
+/// 一次成功尝试的产物描述。
+pub(crate) struct AttemptOk {
+    /// 文件总字节数。
+    pub bytes: u64,
+    /// 续传起点（0 = 从头下）。
+    pub resumed_from: u64,
+}
+
+/// 下载引擎（`Arc` 后全局共享；内部无状态以外的可变数据只有抖动源）。
+#[derive(Debug)]
+pub struct DownloadEngine {
+    pub(crate) http: reqwest::Client,
+    pub(crate) cfg: EngineConfig,
+    pub(crate) progress: ProgressEmitter,
+    pub(crate) health: Arc,
+    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());
+        let sem = Arc::new(Semaphore::new(cfg.max_concurrency.max(1)));
+        let seed = now_ms() ^ (u64::from(cfg.max_concurrency as u32) << 32);
+        Self {
+            http,
+            cfg,
+            progress: ProgressEmitter::silent(),
+            health,
+            cache,
+            jitter: std::sync::Mutex::new(Jitter::new(seed)),
+            mirrors,
+            region,
+            sem,
+        }
+    }
+
+    /// 挂上进度事件发射器。
+    #[must_use]
+    pub fn with_progress(mut self, progress: ProgressEmitter) -> Self {
+        self.progress = progress;
+        self
+    }
+
+    /// 配置。
+    #[must_use]
+    pub fn config(&self) -> &EngineConfig {
+        &self.cfg
+    }
+
+    /// HTTP 客户端（同一条连接池与超时配置）。
+    ///
+    /// 给「一锤子查询」用——例如 Adoptium 的版本查询（`core::game::java::api`）：
+    /// 没必要为了一个 GET 再造一个 client，代理/超时/证书栈都在这里统一。
+    #[must_use]
+    pub fn client(&self) -> &reqwest::Client {
+        &self.http
+    }
+
+    /// 当前地区档案（设置页展示）。
+    #[must_use]
+    pub fn region(&self) -> &RegionProfile {
+        &self.region
+    }
+
+    /// 镜像表（`game::java` 的 Oracle / MS / Zulu 分发表在这里查）。
+    #[must_use]
+    pub fn mirrors(&self) -> &MirrorTable {
+        &self.mirrors
+    }
+
+    /// 健康度注册表（诊断页）。
+    #[must_use]
+    pub fn health(&self) -> &HealthRegistry {
+        &self.health
+    }
+
+    /// 内容寻址缓存。
+    #[must_use]
+    pub fn cache(&self) -> &ContentCache {
+        &self.cache
+    }
+
+    /// 候选规划：镜像展开 → 官方位置保持不变 → 其余按健康度排序。
+    #[must_use]
+    pub fn plan(&self, req: &DownloadRequest, now_ms: u64) -> Vec {
+        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(),
+                            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 次（这次就是「恢复探测」，失败会重新冷却）；
+    /// * 刚出冷却、还没洗白 → 也只给 1 次（`is_probe()`，别让死源每次到期都吃满 3 次）；
+    /// * 正常 → 配置的 `max_attempts_per_source`。
+    pub(crate) fn attempts_for(&self, source: &str, kind: ResourceKind, now_ms: u64) -> u32 {
+        let health = self.health.health_of(source, kind);
+        if health.is_cooling_down(now_ms) || health.is_probe(now_ms) {
+            1
+        } else {
+            self.cfg.max_attempts_per_source.max(1)
+        }
+    }
+
+    /// 一次下载收尾时把健康度节流落盘（对齐 `cache.persist()` 的位置，但带节流）。
+    pub(crate) fn flush_health(&self) {
+        let _ = self.health.flush(now_ms());
+    }
+
+    pub(crate) fn next_delay(&self, attempt: u32) -> Duration {
+        let mut jitter = self
+            .jitter
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner());
+        self.cfg.backoff.next_delay(attempt, &mut jitter)
+    }
+
+    pub(crate) fn emit(&self, event: ProgressEvent) {
+        self.progress.emit(event);
+    }
+}
+
+/// 缓存命中时把文件变成工作副本（硬链接优先，跨卷退化为复制）。
+fn materialize(source: &Path, dest: &Path) -> std::io::Result {
+    if let Some(parent) = dest.parent() {
+        if !parent.as_os_str().is_empty() {
+            std::fs::create_dir_all(parent)?;
+        }
+    }
+    if dest.exists() {
+        let _ = std::fs::remove_file(dest);
+    }
+    if std::fs::hard_link(source, dest).is_err() {
+        std::fs::copy(source, dest)?;
+    }
+    Ok(std::fs::metadata(dest)?.len())
+}
+
+pub(crate) fn millis(duration: Duration) -> u64 {
+    u64::try_from(duration.as_millis()).unwrap_or(u64::MAX)
+}
diff --git a/crates/core/src/download/error.rs b/crates/core/src/download/error.rs
new file mode 100644
index 0000000..ed5f6cc
--- /dev/null
+++ b/crates/core/src/download/error.rs
@@ -0,0 +1,125 @@
+//! 下载错误：三态分类（同源重试 / 立刻换源 / 整体失败）+ 失败摘要。
+//!
+//! core 不引 `thiserror`（P0 阶段少一个依赖），手写 `Display`/`Error` 足够。
+
+use std::fmt;
+
+use serde::{Deserialize, Serialize};
+
+/// 错误分类：决定「同源重试」「立刻换源」还是「整体失败」。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum DownloadErrorKind {
+    /// 请求本身不合法（不重试）。
+    InvalidRequest,
+    /// 404/410/403：该源没有这个资源，立刻换源。
+    NotFound,
+    /// 5xx / 429：同源退避重试。
+    ServerError,
+    /// 超时：同源退避重试，多次后换源。
+    Timeout,
+    /// 连接/传输层错误。
+    Network,
+    /// 校验不符：同源重试一次后换源（可能是镜像内容不一致）。
+    Integrity,
+    /// 服务器不支持 Range（内部用于退化单连接，不向上暴露为失败）。
+    RangeUnsupported,
+    /// 本地 IO 错误（不重试）。
+    Io,
+    /// 所有候选源都失败。
+    AllSourcesFailed,
+}
+
+impl DownloadErrorKind {
+    /// 稳定字符串 id。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::InvalidRequest => "invalid_request",
+            Self::NotFound => "not_found",
+            Self::ServerError => "server_error",
+            Self::Timeout => "timeout",
+            Self::Network => "network",
+            Self::Integrity => "integrity",
+            Self::RangeUnsupported => "range_unsupported",
+            Self::Io => "io",
+            Self::AllSourcesFailed => "all_sources_failed",
+        }
+    }
+
+    /// 是否值得在同源上退避重试。
+    #[must_use]
+    pub const fn is_retryable(self) -> bool {
+        matches!(
+            self,
+            Self::ServerError | Self::Timeout | Self::Network | Self::Integrity
+        )
+    }
+}
+
+/// 下载错误。
+#[derive(Debug, Clone)]
+pub struct DownloadError {
+    /// 分类。
+    pub kind: DownloadErrorKind,
+    /// 出错的源（整体失败时为 `None`）。
+    pub source: Option,
+    /// 人类可读描述。
+    pub message: String,
+    /// 已经尝试的次数（含本次）。
+    pub attempts: usize,
+    /// 其它候选源的失败摘要，便于诊断「到底哪一层挂了」。
+    pub suppressed: Vec,
+}
+
+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(),
+        }
+    }
+
+    /// 标注出错的源。
+    #[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
+    }
+}
+
+impl fmt::Display for DownloadError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match &self.source {
+            Some(source) => write!(
+                f,
+                "[{}] {}（源 {}）",
+                self.kind.as_str(),
+                self.message,
+                source
+            ),
+            None => write!(f, "[{}] {}", self.kind.as_str(), self.message),
+        }
+    }
+}
+
+impl std::error::Error for DownloadError {}
diff --git a/crates/core/src/download/health.rs b/crates/core/src/download/health.rs
new file mode 100644
index 0000000..d3f6169
--- /dev/null
+++ b/crates/core/src/download/health.rs
@@ -0,0 +1,399 @@
+//! 源健康度记忆：`源 × 资源类型` 的 EMA RTT / 失败率 / 连续失败。
+//!
+//! HMCL 没有这一层（analyse/03 §8.4 的「下载快」一栏是纯并发 + 缓存），于是同一台机器上
+//! 一个常年 502 的镜像会被每个文件重试一遍。这里的规则：
+//!
+//! * 连续 **3** 次失败 → 冷却 **10 分钟**，期间该源排到最后（仍保留为兜底候选）；
+//! * 冷却结束后自动进入**恢复探测**：下一次尝试就是一次探测，成功即清零回队，失败则重新冷却；
+//! * 记录持久化到 `cache/health.json`（原子写），进程重启后仍然生效：
+//!   **冷却状态迁移时立刻落盘**（进入/退出冷却这种罕见事件），其余变化标脏，
+//!   由引擎在一次 `download()` / `download_bytes()` 收尾时 `flush()` 节流落盘，
+//!   避免「批量下 3000 个资源 = 3000 次原子写」；
+//! * 排序打分 = EMA RTT + 失败率惩罚 + 连续失败惩罚，冷却中的源加一个大惩罚。
+
+use std::collections::HashMap;
+use std::io;
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::Mutex;
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
+
+use serde::{Deserialize, Serialize};
+
+use super::health_store;
+use super::types::{Candidate, ResourceKind, SOURCE_OFFICIAL};
+
+/// 连续失败多少次进入冷却。
+pub const FAILURE_THRESHOLD: u32 = 3;
+/// 冷却时长（毫秒）：连续失败后的冷板凳时间。
+pub const COOLDOWN_MS: u64 = 10 * 60 * 1000;
+/// EMA 的平滑系数（0.3 意味着新样本占 30%）。
+pub const EMA_ALPHA: f64 = 0.3;
+/// 冷板凳/未知源的基础打分。
+pub const SCORE_UNKNOWN: f64 = 400.0;
+/// 落盘节流：两次 flush 之间的最小间隔（毫秒）。
+pub const SAVE_THROTTLE_MS: u64 = 5_000;
+/// 冷却中的惩罚项。
+pub const SCORE_COOLDOWN_PENALTY: f64 = 1_000.0;
+
+/// 健康度的记忆键：一个源在一种资源类型上的表现是独立的。
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub struct HealthKey {
+    /// 源标识（`official` / `bmclapi` / `tuna` …）。
+    pub source: String,
+    /// 资源类型。
+    pub kind: ResourceKind,
+}
+
+impl HealthKey {
+    /// 构造键。
+    #[must_use]
+    pub fn new(source: impl Into, 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..6e6fd66
--- /dev/null
+++ b/crates/core/src/download/http.rs
@@ -0,0 +1,183 @@
+//! HTTP 薄封装：客户端构造、错误分类、响应头读取。
+//!
+//! 关键取舍：
+//! * **`Accept-Encoding: identity`** —— 下载要按字节对齐做 Range/校验，gzip 会让
+//!   `Content-Length` 与实际写入量打架（HMCL 为此专门写了按解压后偏移计数的
+//!   `HttpResumeContext`，analyse/03 §5.4），我们直接从协议层绕开这个问题；
+//! * 重定向上限 20 跳（承 HMCL），跳转后仍按最终 URL 做 host 校验由调用方负责；
+//! * 错误分类只做「同源重试 / 立刻换源 / 整体失败」三态，不做细颗粒映射。
+
+use reqwest::header::{
+    HeaderMap, HeaderName, ACCEPT_ENCODING, CONTENT_LENGTH, CONTENT_TYPE, ETAG, LAST_MODIFIED,
+};
+use reqwest::redirect::Policy;
+
+use super::config::EngineConfig;
+use super::error::{DownloadError, DownloadErrorKind};
+
+/// 重定向上限（承 HMCL 的 20 跳）。
+pub const MAX_REDIRECTS: usize = 20;
+
+/// 构造共享的 `reqwest::Client`（连接池、超时、重定向策略一次定好）。
+pub fn build_client(cfg: &EngineConfig) -> Result {
+    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};
+
+    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);
+    }
+}
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..8075108
--- /dev/null
+++ b/crates/core/src/download/mirrors.json
@@ -0,0 +1,169 @@
+{
+  "version": 3,
+  "notes": [
+    "v3（D23/M36）：adoptium 表收敛到清华 TUNA 一家（其余院校实测 404，登记保留但 enabled=false）；新增 oracle_openjdk / microsoft_openjdk / zulu 三张表，供 game::java 的三发行版回退链使用。",
+    "华为云 / 腾讯云 / 阿里云没有 Adoptium 镜像：华为云门户对任意不存在的路径都回 200 + 12KB HTML（假阳性，M34 实测），腾讯云 /v1/source.js 与华为云 /v1/repositories 的权威清单里都没有 JDK 项。据此不再登记 adoptium.huaweicloud。",
+    "oracle_openjdk 的目录与文件名与 download.java.net 完全同构，但 hash 段（f2283984656d49d69e91c558476027ac）不可推导——候选 URL 只能来自对镜像目录页的解析，禁止拼装。",
+    "microsoft_openjdk 没有国内镜像，也没有 GitHub 资产（api.github.com 的 microsoft/openjdk releases 里 assets 全空）；唯一渠道是 aka.ms 模板 301 → download.visualstudio.microsoft.com（国内约 400 KB/s）。",
+    "zulu 的 API size 字段与真实字节数差 133 B，只能用于展示；校验一律用 sha256_hash。"
+  ],
+  "gh_proxies": [
+    {
+      "id": "gh-proxy",
+      "name": "gh-proxy.com",
+      "prefix": "https://gh-proxy.com/",
+      "enabled": true
+    }
+  ],
+  "adoptium": [
+    {
+      "id": "tuna",
+      "name": "清华 TUNA",
+      "base": "https://mirrors.tuna.tsinghua.edu.cn/Adoptium",
+      "enabled": true,
+      "latest_only": true
+    },
+    {
+      "id": "ustc",
+      "name": "中科大 USTC（无 Adoptium 目录树：只有 deb/rpm/releases，实测 404）",
+      "base": "https://mirrors.ustc.edu.cn/adoptium",
+      "enabled": false
+    },
+    {
+      "id": "sjtu",
+      "name": "上交 SJTU（无 Adoptium 目录树，实测 404）",
+      "base": "https://mirror.sjtu.edu.cn/adoptium",
+      "enabled": false
+    },
+    {
+      "id": "bfsu",
+      "name": "北外 BFSU（无 Adoptium 目录树，实测 404）",
+      "base": "https://mirrors.bfsu.edu.cn/Adoptium",
+      "enabled": false
+    },
+    {
+      "id": "nju",
+      "name": "南大 NJU（adoptium 路径实测 404；/openjdk/ 走 oracle_openjdk 表）",
+      "base": "https://mirror.nju.edu.cn/adoptium",
+      "enabled": false
+    },
+    {
+      "id": "zju",
+      "name": "浙大 ZJU（无 Adoptium 目录树，实测 404 搜索页）",
+      "base": "https://mirrors.zju.edu.cn/adoptium",
+      "enabled": false
+    },
+    {
+      "id": "163",
+      "name": "网易 163（无 Adoptium 目录树，实测 404 且 18 秒才回）",
+      "base": "https://mirrors.163.com/adoptium",
+      "enabled": false
+    }
+  ],
+  "oracle_openjdk": [
+    {
+      "id": "huawei",
+      "name": "华为云",
+      "base": "https://mirrors.huaweicloud.com/openjdk",
+      "enabled": true,
+      "speed": "11.5MB/s",
+      "note": "逐字节忠实镜像（21.0.2 = 201328186 B 与官方一致）；目录页是 Apache 列表，带 
；归档旁有 .sha256"
+    },
+    {
+      "id": "nju",
+      "name": "南大 NJU",
+      "base": "https://mirror.nju.edu.cn/openjdk",
+      "enabled": true,
+      "speed": "8.3MB/s",
+      "note": "需先吃一次 bcheck cookie（裸 GET 是 302 回自己）；健康度会把它排在华为云之后，失败即降级"
+    }
+  ],
+  "microsoft_openjdk": {
+    "list": "https://learn.microsoft.com/java/openjdk/download",
+    "template": "https://aka.ms/download-jdk/microsoft-jdk-{version}-{os}-{arch}.zip",
+    "sha256_template": "https://aka.ms/download-jdk/microsoft-jdk-{version}-{os}-{arch}.zip.sha256sum.txt",
+    "majors": [25, 21, 17, 11],
+    "domestic_mirrors": [],
+    "measured_speed": "398KB/s"
+  },
+  "zulu": {
+    "api": "https://api.azul.com/metadata/v1/zulu/packages/",
+    "detail": "https://api.azul.com/metadata/v1/zulu/packages/{uuid}",
+    "cdn_host": "cdn.azul.com",
+    "measured_speed": "3.3MB/s",
+    "size_field_reliable": false
+  },
+  "rules": [
+    {
+      "id": "bmclapi-launchermeta",
+      "from": "https://launchermeta.mojang.com",
+      "to": "https://bmclapi2.bangbang93.com"
+    },
+    {
+      "id": "bmclapi-piston-meta",
+      "from": "https://piston-meta.mojang.com",
+      "to": "https://bmclapi2.bangbang93.com"
+    },
+    {
+      "id": "bmclapi-piston-data",
+      "from": "https://piston-data.mojang.com",
+      "to": "https://bmclapi2.bangbang93.com"
+    },
+    {
+      "id": "bmclapi-launcher",
+      "from": "https://launcher.mojang.com",
+      "to": "https://bmclapi2.bangbang93.com"
+    },
+    {
+      "id": "bmclapi-libraries",
+      "from": "https://libraries.minecraft.net",
+      "to": "https://bmclapi2.bangbang93.com"
+    },
+    {
+      "id": "bmclapi-assets-objects",
+      "from": "https://resources.download.minecraft.net",
+      "to": "https://bmclapi2.bangbang93.com",
+      "inject": "/assets"
+    },
+    {
+      "id": "bmclapi-forge-maven",
+      "from": "https://files.minecraftforge.net/maven",
+      "to": "https://bmclapi2.bangbang93.com/maven"
+    },
+    {
+      "id": "bmclapi-forge-maven-net",
+      "from": "https://maven.minecraftforge.net",
+      "to": "https://bmclapi2.bangbang93.com/maven"
+    },
+    {
+      "id": "bmclapi-neoforge",
+      "from": "https://maven.neoforged.net/releases",
+      "to": "https://bmclapi2.bangbang93.com/maven"
+    },
+    {
+      "id": "bmclapi-fabric-meta",
+      "from": "https://meta.fabricmc.net",
+      "to": "https://bmclapi2.bangbang93.com/fabric-meta"
+    },
+    {
+      "id": "bmclapi-fabric-maven",
+      "from": "https://maven.fabricmc.net",
+      "to": "https://bmclapi2.bangbang93.com/maven"
+    },
+    {
+      "id": "bmclapi-quilt-meta",
+      "from": "https://meta.quiltmc.org",
+      "to": "https://bmclapi2.bangbang93.com/quilt-meta"
+    },
+    {
+      "id": "bmclapi-liteloader",
+      "from": "https://dl.liteloader.com/versions",
+      "to": "https://bmclapi2.bangbang93.com/maven"
+    },
+    {
+      "id": "bmclapi-authlib-injector",
+      "from": "https://authlib-injector.yushi.moe",
+      "to": "https://bmclapi2.bangbang93.com/mirrors/authlib-injector"
+    }
+  ]
+}
diff --git a/crates/core/src/download/mirrors.rs b/crates/core/src/download/mirrors.rs
new file mode 100644
index 0000000..e16b6cb
--- /dev/null
+++ b/crates/core/src/download/mirrors.rs
@@ -0,0 +1,386 @@
+//! 镜像清单与 URL 前缀重写。
+//!
+//! 内置清单 `mirrors.json` 随源码嵌入（`include_str!`），发行后可由设置层追加自定义规则。
+//! 重写语义承 analyse/03 §5.2 的「前缀替换而非全量重写」——保留子路径，因此 `/libraries`、
+//! `/maven`、`/fabric-meta` 这类子路径天然兼容；`inject` 用于补上路径形状不同的场景
+//! （资源对象：官方 `/`，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 类前缀。
+    #[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);
+    }
+
+    /// 覆盖 gh-proxy 前缀（设置项）；传 `None` 表示不默认启用。
+    pub fn set_gh_proxy(&mut self, prefix: Option<&str>) {
+        match prefix {
+            Some(prefix) => {
+                if let Some(proxy) = self.gh_proxies.first_mut() {
+                    proxy.prefix = prefix.to_string();
+                    proxy.enabled = true;
+                } else {
+                    self.gh_proxies.push(GhProxy {
+                        id: "gh-proxy".to_string(),
+                        name: "自定义 gh-proxy".to_string(),
+                        prefix: prefix.to_string(),
+                        enabled: true,
+                    });
+                }
+            }
+            None => {
+                for proxy in &mut self.gh_proxies {
+                    proxy.enabled = false;
+                }
+            }
+        }
+    }
+
+    /// 找到第一条命中的前缀规则。
+    #[must_use]
+    pub fn prefix_rule_for(&self, url: &str, kind: ResourceKind) -> Option<&PrefixRule> {
+        self.rules.iter().find(|rule| rule.matches(url, kind))
+    }
+
+    /// 清单里第一个启用的 gh-proxy 前缀（默认值来源；设置层用它初始化地区档案）。
+    #[must_use]
+    pub fn default_gh_proxy(&self) -> Option<&str> {
+        self.gh_proxies
+            .iter()
+            .find(|proxy| proxy.enabled && !proxy.prefix.is_empty())
+            .map(|proxy| proxy.prefix.as_str())
+    }
+
+    /// GitHub host 且允许时套 gh-proxy 前缀。
+    ///
+    /// **生效前缀的唯一真相源是 `region.gh_proxy`**（设置层/地区判定写入，`None` = 用户关闭）。
+    /// 表格里的 `gh_proxies` 只是「已知可用前缀」清单，配合 `default_gh_proxy()` 给设置做默认值。
+    #[must_use]
+    pub fn gh_proxy_candidates(&self, url: &str, region: &RegionProfile) -> Vec {
+        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..a66155a
--- /dev/null
+++ b/crates/core/src/download/mod.rs
@@ -0,0 +1,90 @@
+//! 下载引擎：多源健康度、指数退避、分层下载（大文件分块）、边下边算、原子落盘。
+//!
+//! 设计定稿：`DevDocs/PlanDoc/05-download-and-mirrors.md`（决策 D7）。
+//! 镜像清单随更新可刷新（BMCLAPI / TUNA / USTC / SJTU / gh-proxy），
+//! 地区自动判定 = 时区 + 语言 + 网络探测组合信号，可手动覆盖。
+//!
+//! 与其它模块的契约：`DownloadRequest` / 进度事件的类型需与 game、agent 对齐
+//! （`DevDocs/SubAgentsTalk/README.md` 的对齐点）。
+//!
+//! # 公共面
+//!
+//! 调用方只需要三件套：构造 [`DownloadRequest`] → [`DownloadEngine::download`] →
+//! 消费 [`ProgressEvent`]。「用哪个镜像、要不要续传、开几条连接、失败重试几次」
+//! 全部由引擎内部决定，调用方既不拼镜像 URL 也不写重试循环。
+//!
+//! 其余构件（镜像表 / 地区档案 / 健康度 / 内容寻址缓存 / 续传元数据）都作为
+//! 可注入对象暴露出来：设置层要把它们接进 schema，诊断页要直接读它们的状态，
+//! 测试要能把它们换成确定性的假件。
+//!
+//! # 分层
+//!
+//! ```text
+//! engine        编排：缓存直取 → 候选规划 → 限流 → 候选外循环 / 退避内循环
+//! transfer      单连接尝试（续传 + 流式校验）
+//! transfer_chunk 多连接分块编排
+//! chunked       分块规划 / Range 语义 / 单块抓取
+//! mirrors       镜像清单 + URL 前缀重写      adoptium  JDK 院校镜像
+//! region        时区 + 语言 + 探测 → 直连/镜像优先
+//! health        源 × 资源类型的健康度记忆
+//! cache         内容寻址缓存（记录信任）      atomic    落盘守卫 / 原子写
+//! resume        保守续传判定                  verify    流式摘要
+//! progress      事件流                        error     错误分类
+//! ```
+//!
+//! 落盘守卫（[`PartFile`]）中间文件名是 `.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 health;
+pub mod jdk_sources;
+pub mod mirrors;
+pub mod progress;
+pub mod region;
+pub mod region_system;
+pub mod resume;
+pub mod types;
+pub mod verify;
+
+// 内部实现细节：只在 download 模块内（含 crate 内）可见，不承诺兼容性。
+pub(crate) mod atomic;
+pub(crate) mod bytes;
+pub(crate) mod health_store;
+pub(crate) mod http;
+pub(crate) mod transfer;
+pub(crate) mod transfer_chunk;
+
+pub use self::adoptium::{AdoptiumArtifact, JdkFlavor};
+pub use self::atomic::{PartFile, ADOPT_MIN_AGE, META_SUFFIX, ORPHAN_MAX_AGE, PART_SUFFIX};
+pub use self::backoff::{BackoffPolicy, Jitter};
+pub use self::blocking::block_on;
+pub use self::cache::{CacheRecord, CacheStats, ContentCache};
+pub use self::chunked::{ByteRange, ChunkedConfig, RangeSupport};
+pub use self::config::EngineConfig;
+pub use self::engine::DownloadEngine;
+pub use self::error::{DownloadError, DownloadErrorKind};
+pub use self::health::{HealthKey, HealthRegistry, SourceHealth};
+pub use self::jdk_sources::{MsOpenJdkTable, OracleMirror, ZuluTable};
+pub use self::mirrors::{direct_source_id, AdoptiumMirror, GhProxy, MirrorTable, PrefixRule};
+pub use self::progress::{ProgressEmitter, ProgressEvent, ProgressThrottle};
+pub use self::region::{RegionMode, RegionProfile, RegionTrigger, Signals};
+pub use self::region_system::detect_signals;
+pub use self::resume::{RestartReason, ResumeDecision, ResumeMeta};
+pub use self::types::{
+    Candidate, DownloadId, DownloadOutcome, DownloadRequest, HashAlgo, Integrity, ResourceKind,
+    ResumePolicy, SOURCE_OFFICIAL,
+};
+pub use self::verify::Hasher;
diff --git a/crates/core/src/download/progress.rs b/crates/core/src/download/progress.rs
new file mode 100644
index 0000000..4dea5f0
--- /dev/null
+++ b/crates/core/src/download/progress.rs
@@ -0,0 +1,197 @@
+//! 进度事件与发射器。
+//!
+//! 事件是「字节级 + 文件级」双层的载体（设计文档 §5）：文件级由 `Started/Completed/Failed`
+//! 表达，字节级由节流后的 `Progress` 表达。`total_bytes` 未知时给 `None`——不做假进度。
+
+use std::time::{Duration, Instant};
+
+use serde::{Deserialize, Serialize};
+use tokio::sync::mpsc::{self, UnboundedReceiver, UnboundedSender};
+
+use super::error::DownloadErrorKind;
+use super::types::{DownloadId, HashAlgo, ResourceKind};
+
+/// 一条下载进度事件。
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "event", rename_all = "snake_case")]
+pub enum ProgressEvent {
+    /// 开始一次下载（含候选数量与总字节预算）。
+    Started {
+        /// 关联 id。
+        id: DownloadId,
+        /// 资源类型。
+        kind: ResourceKind,
+        /// 逻辑 URL。
+        url: String,
+        /// 落盘路径。
+        dest: String,
+        /// 候选源数量。
+        candidates: usize,
+        /// 总字节数（未知为 `None`）。
+        total_bytes: Option,
+    },
+    /// 字节级进度（节流后）。
+    Progress {
+        /// 关联 id。
+        id: DownloadId,
+        /// 已下载字节。
+        downloaded: u64,
+        /// 总字节数（未知为 `None`）。
+        total_bytes: Option,
+    },
+    /// 某个源失败（单次尝试）。
+    SourceFailed {
+        /// 关联 id。
+        id: DownloadId,
+        /// 源标识。
+        source: String,
+        /// 失败原因（短描述）。
+        reason: String,
+        /// 第几次尝试（从 0 起）。
+        attempt: u32,
+        /// 是否还会在同源重试。
+        will_retry: bool,
+        /// 下次重试的等待毫秒数。
+        retry_in_ms: u64,
+    },
+    /// 切换到下一个候选源。
+    SourceSwitched {
+        /// 关联 id。
+        id: DownloadId,
+        /// 原源。
+        from: String,
+        /// 新源。
+        to: String,
+    },
+    /// 进入校验阶段。
+    Verifying {
+        /// 关联 id。
+        id: DownloadId,
+        /// 算法。
+        algo: HashAlgo,
+        /// 期望摘要前缀（8 位，够定位又不太啰嗦）。
+        expected_prefix: String,
+    },
+    /// 下载成功。
+    Completed {
+        /// 关联 id。
+        id: DownloadId,
+        /// 字节数。
+        bytes: u64,
+        /// 是否命中内容寻址缓存。
+        from_cache: bool,
+        /// 成功的源。
+        source: String,
+        /// 耗时毫秒。
+        elapsed_ms: u64,
+    },
+    /// 下载失败（所有候选源都失败或不可重试）。
+    Failed {
+        /// 关联 id。
+        id: DownloadId,
+        /// 错误分类。
+        kind: DownloadErrorKind,
+        /// 错误描述。
+        message: String,
+    },
+}
+
+impl ProgressEvent {
+    /// 事件归属的下载 id。
+    #[must_use]
+    pub const fn id(&self) -> DownloadId {
+        match self {
+            Self::Started { id, .. }
+            | Self::Progress { id, .. }
+            | Self::SourceFailed { id, .. }
+            | Self::SourceSwitched { id, .. }
+            | Self::Verifying { id, .. }
+            | Self::Completed { id, .. }
+            | Self::Failed { id, .. } => *id,
+        }
+    }
+}
+
+/// 进度发射器：没有接收端时退化为空操作（core 不关心谁在听）。
+#[derive(Debug, Clone, Default)]
+pub struct ProgressEmitter {
+    tx: Option>,
+}
+
+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..eb60e48
--- /dev/null
+++ b/crates/core/src/download/region_system.rs
@@ -0,0 +1,158 @@
+//! 地区判定的**系统级**信号补充：环境变量之外的那一半（D23「国内用户默认都走镜像」）。
+//!
+//! 为什么需要它：`Signals::from_env` 只读 `TZ` / `LANG` / `LC_*`。Windows 上这三个通常**全是空的**
+//! ——中文版 Windows 既不设 `TZ` 也不设 `LANG`，于是「国内机器」被误判成国外，
+//! D23 定下的国内默认序（Temurin→Oracle→MS）就拿不到了。本机实测就是这个现象。
+//!
+//! 补法（只在环境变量没给出答案时才做，且读不到就静默跳过）：
+//!
+//! | 平台 | 时区 | 语言 |
+//! | --- | --- | --- |
+//! | Windows | `tzutil /g` → `China Standard Time` | `reg query` 的 `LocaleName` → `zh-CN` |
+//! | 其它 | 不补（Unix 一般都有 `LANG`，`/etc/localtime` 解析成本不划算） | 同左 |
+//!
+//! 两个纪律：①**不引依赖**——`tzutil` / `reg` 都是系统自带，`discover.rs` 早就有 `reg query`
+//! 的先例；②**不做网络探测**——探测（google 可达性）仍由调用方决定开不开。
+
+use std::process::Command;
+
+use super::region::{Signals, GREATER_CHINA_TIMEZONES};
+
+/// Windows 时区显示名里能判成「大中华区」的关键词（`tzutil /g` 的输出形态）。
+const GREATER_CHINA_ZONE_HINTS: &[&str] = &[
+    "China Standard Time",
+    "Taipei Standard Time",
+    "Hong Kong Standard Time",
+    "Ulaanbaatar",
+];
+
+/// 系统级信号（环境变量之外；读不到就是空信号）。
+#[must_use]
+pub fn system_signals() -> Signals {
+    let mut signals = Signals::default();
+    if !cfg!(windows) {
+        return signals;
+    }
+    if let Some(zone) = windows_timezone() {
+        if zone_in_greater_china(&zone) {
+            // 折成 IANA 名，和 `Signals::from_env` 的取值空间保持一致。
+            signals.timezone = Some("Asia/Shanghai".to_string());
+        }
+    }
+    if let Some(locale) = windows_locale() {
+        signals.languages.push(locale);
+    }
+    signals
+}
+
+/// 环境变量信号 + 系统级信号（系统级只补空缺，不覆盖环境变量）。
+#[must_use]
+pub fn detect_signals() -> Signals {
+    let mut signals = Signals::from_env();
+    let system = system_signals();
+    if signals.timezone.is_none() {
+        signals.timezone = system.timezone;
+    }
+    for language in system.languages {
+        if !signals.languages.contains(&language) {
+            signals.languages.push(language);
+        }
+    }
+    signals
+}
+
+/// `tzutil /g` 的输出（失败为 `None`）。
+#[must_use]
+pub fn windows_timezone() -> Option {
+    let output = Command::new("tzutil").arg("/g").output().ok()?;
+    if !output.status.success() {
+        return None;
+    }
+    let text = String::from_utf8_lossy(&output.stdout).trim().to_string();
+    (!text.is_empty()).then_some(text)
+}
+
+/// 系统的 locale 名（`HKCU\Control Panel\International` 的 `LocaleName`）。
+#[must_use]
+pub fn windows_locale() -> Option {
+    let output = Command::new("reg")
+        .args([
+            "query",
+            "HKCU\\Control Panel\\International",
+            "/v",
+            "LocaleName",
+        ])
+        .output()
+        .ok()?;
+    if !output.status.success() {
+        return None;
+    }
+    let stdout = String::from_utf8_lossy(&output.stdout).into_owned();
+    parse_reg_locale_name(&stdout)
+}
+
+/// 从 `reg query` 的输出里取 `LocaleName` 的值（`    LocaleName    REG_SZ    zh-CN`）。
+#[must_use]
+pub fn parse_reg_locale_name(stdout: &str) -> Option {
+    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/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/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..2760ac4
--- /dev/null
+++ b/crates/core/src/game/inherit.rs
@@ -0,0 +1,198 @@
+//! `inheritsFrom` 继承解析、逐字段合并语义、patch 优先级排序。
+//!
+//! 依据：`DevDocs/analyse/03-version-download.md` §4.3（`resolve()`）、§4.4（merge 语义表）、
+//! §4.5（patch 生命周期）。
+//!
+//! 与 HMCL 的三处**有意差异**（都在 §4.3 的对照里）：
+//! 1. **成环即报错**（[`GameError::CircularInheritance`]）而不是"断链后降级启动"：
+//!    静默降级会让用户拿到"能启动但缺库"的实例，宁可明确告知清单坏了。
+//! 2. **缺失父版本报错**（[`GameError::MissingParent`]），与 HMCL 的
+//!    `NoSuchGameInstanceException` 一致。
+//! 3. 不实现 `toPatch()` 的"把已解析父层固化进 patches"优化——P0 实例数量小，
+//!    每次启动重算继承链（毫秒级）；等有性能证据再加缓存。
+
+use std::collections::BTreeMap;
+
+use super::arguments::Arguments;
+use super::error::GameError;
+use super::manifest::VersionJson;
+
+/// 父版本来源（仓库快照或测试里的内存表）。
+pub trait VersionSource {
+    /// 按 id 取一份版本 JSON；不存在返回 `None`。
+    ///
+    /// 实现方应自行处理 IO 错误——把失败转成 `None` 会让"父版本缺失"和"读盘失败"
+    /// 混为一谈，因此读盘失败的实现应当在调用 [`resolve`] 前就把它暴露给用户。
+    fn load(&self, id: &str) -> Option;
+}
+
+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 维持。
+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..f5c380a
--- /dev/null
+++ b/crates/core/src/game/install/execute.rs
@@ -0,0 +1,339 @@
+//! 落盘执行：跳过判定 → 并发下载（引擎负责镜像/退避/续传/校验）→ 原子写版本 JSON。
+//!
+//! 依据：`DevDocs/analyse/03-version-download.md` §6.9（完整性修复路径的"存在即信"分级）、
+//! `DevDocs/PlanDoc/05-download-and-mirrors.md` §2（按资源类型分层）、§5（静态展开并行度）。
+//!
+//! # 跳过判定（幂等的地基）
+//!
+//! 判据分三级，与 analyse/03 §6.9 的思路一致：
+//! - 有 sha1 → **重算摘要比对**（唯一可信判据；代价是读一遍盘）；
+//! - 无 sha1 有大小 → 只比大小（清单没给摘要时退一步）；
+//! - 两者都没有 → 存在即信（HMCL 同类做法，留给后续"一键修复"补校验）。
+//!
+//! 跳过不写盘、不进网络，因此"重复 install 同版本"第二次几乎零成本。
+//!
+//! # 失败策略
+//!
+//! **不整体回滚**：已下好的共享层文件（libraries/assets）留在原地复用，失败信息逐文件结构化
+//! 返回，由调用方决定是重试、还是只提示"缺哪几个文件"。这与 analyse/03 §6.3 的"宁可给出
+//! 可修复的骨架"一致，但**版本清单与实例登记只在全量成功后才写**，不会出现半实例。
+//!
+//! # 取消（M105：GUI 的「取消安装」要**真停**）
+//!
+//! [`execute`] 与 CLI 的契约**一字不变**（不传取消标志 = 今天的行为）；
+//! 取消走 [`execute_with_cancel`]，判据三条：
+//!
+//! 1. **不再起新文件**：流里**每个 item 的第一句**就看标志，置位直接返回 `None` ⇒
+//!    那些 item **连 `install_one` 都不进**（不发请求、不算整文件 sha1、不回调 `sink`）。
+//!    这一句不能挪到 `select` 的右支：`select` 先轮询左支，左支第一次 poll 就把
+//!    `engine.download(…)` 派出去了（复审 P2-1 就是从这条抓出来的）。
+//! 2. **在飞的文件就地掐断**：`install_one` 与「取消 future」`select` 赛跑，
+//!    取消赢就 drop 掉下载 future —— reqwest 的响应流随之关闭（socket 断开），
+//!    `.ullpart` 由 [`PartFile`](crate::download::PartFile) 的 `Drop` 清掉（不留半截垃圾）。
+//! 3. **半成品不许变成品**：取消后不再写版本 JSON，返回
+//!    [`InstallErrorKind::Cancelled`](super::InstallErrorKind)，调用方（presenter）据此把阶段
+//!    记成「已取消」而不是「失败」。
+//!
+//! 于是取消延迟 = **一个数据块的唤醒**（不是「等一个文件下完」，也不是「等这一段跑完」）。
+//!
+//! ## 固有边界（复审要求留档，别把它当 bug 修）
+//!
+//! `buffer_unordered(concurrency)` 在取消那一刻**已经有最多 `concurrency`（GUI 传 16）个 future
+//! 被拉起来了**，它们已经过了第 1 条那道门。所以最坏情况下这 16 个文件里：
+//!
+//! - **盘上已就绪的**（第一 poll 就 `Ready`）会照常「跑完」并被回调一次 `sink` ——
+//!   presenter 侧靠**安装代次**（`CoreHost::install_epoch`）把这些回调带来的进度事件丢掉，
+//!   所以面板不会因此复燃；
+//! - **真在下载的**会在同一次 poll 的右支被取消掉（future drop、连接关掉、`.ullpart` 清掉）。
+//!
+//! 也就是说：**「取消之后一个字节都不会再写」这句话只对「还没被拉起的 item」成立**；
+//! 在飞的 16 个里已就绪的那些仍会走完自己的回调。要连这一步都收掉，得让
+//! `buffer_unordered` 支持「取消即清空队列」，本轮不做（不在 M105 的验收口径里）。
+
+use std::future::poll_fn;
+use std::path::Path;
+use std::pin::pin;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::task::Poll;
+
+use futures_util::future::{select, Either};
+use futures_util::stream::{self, StreamExt};
+
+use super::plan::PlanFile;
+use super::{InstallError, InstallErrorKind, InstallPlan};
+use crate::download::verify;
+use crate::download::{DownloadEngine, DownloadError, DownloadErrorKind, HashAlgo};
+use crate::platform::atomic::write_atomic;
+
+pub use super::report::{FileFailure, FileOutcome, FileStatus, InstallReport, ProgressSink};
+
+/// 执行安装计划。
+///
+/// 具体步骤：
+/// 1. 规划期已取到的元数据（资源索引，见 [`InstallPlan::prefetch`]）先原子落盘，零网络；
+/// 2. 其余文件并发下载（`concurrency` 上限，引擎内部另有信号量），每个文件带进度回调；
+/// 3. **全量就绪**才写 `versions//.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 version_json = if complete {
+        write_version_json(&plan.version_json_path, plan)?;
+        Some(plan.version_json_path.clone())
+    } else {
+        None
+    };
+
+    Ok(InstallReport {
+        files: outcomes,
+        version_json,
+        warnings: plan.warnings.clone(),
+    })
+}
+
+/// 标志是否已置位（`None` = 没有取消通道，永远 false）。
+///
+/// 用 `SeqCst` 与 presenter 侧 `store` 的强度一致：这里不是性能热点（每个文件一次），
+/// 换更强的顺序只买一个「不给自己留疑问」。
+fn is_cancelled(cancel: Option<&AtomicBool>) -> bool {
+    cancel.is_some_and(|flag| flag.load(Ordering::SeqCst))
+}
+
+/// 取消 future：标志一置位就 `Ready`，否则永远 `Pending`（不注册 waker）。
+///
+/// 为什么敢用「不注册 waker 的 Pending」：它只跟下载 future 一起被 `select` 轮询，
+/// 下载每读到一个数据块就会唤醒 executor、连带重新 poll 这个 future，所以取消延迟
+/// 天然是「一个数据块」；真正卡死的连接另有读超时兜底（`chunked` 的 30 s）。
+async fn cancelled(flag: &AtomicBool) {
+    poll_fn(|_| {
+        if flag.load(Ordering::SeqCst) {
+            Poll::Ready(())
+        } else {
+            Poll::Pending
+        }
+    })
+    .await;
+}
+
+/// 取消的稳定错误（大类 `Cancelled`，不是失败）。
+fn cancelled_error() -> InstallError {
+    InstallError::new(
+        InstallErrorKind::Cancelled,
+        "已取消：剩下的文件没有开始下载，已下好的文件保留（重装续用）",
+    )
+}
+
+/// 单文件：先判"已就绪"，否则走引擎下载。
+async fn install_one(engine: &DownloadEngine, file: &PlanFile) -> FileOutcome {
+    if let Some(bytes) = current_bytes(file) {
+        return FileOutcome {
+            role: file.role,
+            name: file.name.clone(),
+            dest: file.dest.clone(),
+            status: FileStatus::Skipped,
+            bytes,
+            source: None,
+            failure: None,
+        };
+    }
+    match engine.download(file.request()).await {
+        Ok(outcome) => FileOutcome {
+            role: file.role,
+            name: file.name.clone(),
+            dest: file.dest.clone(),
+            status: FileStatus::Downloaded,
+            bytes: outcome.bytes,
+            source: Some(outcome.source),
+            failure: None,
+        },
+        Err(error) => FileOutcome {
+            role: file.role,
+            name: file.name.clone(),
+            dest: file.dest.clone(),
+            status: FileStatus::Failed,
+            bytes: 0,
+            source: None,
+            failure: Some(describe(&error)),
+        },
+    }
+}
+
+/// 文件已就绪则返回盘上大小（跳过判定，见模块文档的三级分级）。
+#[must_use]
+pub fn current_bytes(file: &PlanFile) -> Option {
+    if !file.dest.is_file() {
+        return None;
+    }
+    let size = std::fs::metadata(&file.dest).ok()?.len();
+    match file.sha1.as_deref().filter(|hex| !hex.is_empty()) {
+        Some(expected) => {
+            let actual = verify::digest_file(&file.dest, HashAlgo::Sha1).ok()?;
+            verify::matches(expected, &actual).then_some(size)
+        }
+        None => match file.size {
+            Some(expected) => (size == expected).then_some(size),
+            // 没有摘要也没有大小：存在即信（后续"一键修复"再补校验）。
+            None => Some(size),
+        },
+    }
+}
+
+/// 写解析后的版本清单（原子写）。
+fn write_version_json(path: &Path, plan: &InstallPlan) -> Result<(), super::InstallError> {
+    let text = plan.version_json.to_json_string().map_err(|error| {
+        super::InstallError::new(super::InstallErrorKind::Metadata, error.to_string())
+    })?;
+    write_atomic(path, text.as_bytes())
+        .map_err(|error| super::InstallError::new(super::InstallErrorKind::Io, error.to_string()))
+}
+
+fn describe(error: &DownloadError) -> FileFailure {
+    FileFailure {
+        kind: error.kind,
+        message: error.message.clone(),
+    }
+}
diff --git a/crates/core/src/game/install/instance.rs b/crates/core/src/game/install/instance.rs
new file mode 100644
index 0000000..8fa0aa3
--- /dev/null
+++ b/crates/core/src/game/install/instance.rs
@@ -0,0 +1,351 @@
+//! 实例登记：`config/profiles.json` + `config/instances/.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 一旦写进档案就是稳定的）。
+
+use std::collections::BTreeMap;
+use std::path::PathBuf;
+
+use serde::{Deserialize, Serialize};
+
+use super::super::error::GameError;
+use super::super::isolation::{IsolationMode, ModeChange, ModeChangeWarning};
+use super::super::profiles::{InstanceProfile, ProfileList};
+use crate::platform::atomic::write_atomic;
+use crate::platform::layout::LauncherLayout;
+
+/// 每实例设置文件的 schema 版本。
+///
+/// 与 `setting::instance_keys::instance_version` 的 minor 对应：D20 加了 `lastModeChange`，
+/// 老文件缺这个键即「没切换过」，不需要迁移步骤。
+pub const INSTANCE_CONFIG_VERSION: u32 = 1;
+
+/// 版本隔离档位（`isolation`）。
+///
+/// 缺省 `inherit` **不是**这个枚举的一个值，而是"键不存在"（[`InstanceConfig::isolation`]
+/// 为 `None`）——这样稀疏序列化天然表达"跟随全局"。
+///
+/// 派生规则见 [`crate::game::isolation::derive_game_dir`]：`isolated` → `versions//`、
+/// `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,
+    /// 上次隔离档位切换的记录（`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(),
+            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))
+    }
+}
+
+/// 一次登记的结果。
+#[derive(Debug, Clone)]
+pub struct Registration {
+    /// 档案（新建或复用）。
+    pub profile: InstanceProfile,
+    /// 每实例设置文件路径。
+    pub config_path: PathBuf,
+    /// 是否新建（`false` = 已有同版本同名的实例，直接复用）。
+    pub created: bool,
+}
+
+/// 登记一个实例（幂等）。
+///
+/// 行为：
+/// 1. 已有"同 `version_id` + 同展示名"的档案 → 复用（`created = false`），只补写缺失的设置文件；
+/// 2. 否则新建档案（稳定 UUID）→ 写 `profiles.json` → 写 `config/instances/.json`。
+///
+/// `created_at` 由调用方给（core::game 不碰时钟格式；CLI 用 `launch::time` 的 RFC3339）。
+///
+/// # Errors
+///
+/// 读/写 `profiles.json`、实例 id 不合法、原子写失败。
+pub fn register(
+    layout: &LauncherLayout,
+    name: &str,
+    version_id: &str,
+    created_at: Option<&str>,
+) -> Result {
+    let mut profiles = read_profiles(layout)?;
+    let existing = profiles
+        .profiles
+        .iter()
+        .find(|profile| profile.version_id == version_id && profile.name == name)
+        .cloned();
+
+    if let Some(profile) = existing {
+        let config_path = instance_config_path(layout, profile.id.as_str())?;
+        // 老档案可能还没有设置文件（早期 CLI 只写 profiles.json），这里补齐。
+        if !config_path.is_file() {
+            write_instance_config(
+                layout,
+                &InstanceConfig::new(profile.id.as_str(), version_id),
+            )?;
+        }
+        return Ok(Registration {
+            profile,
+            config_path,
+            created: false,
+        });
+    }
+
+    let mut profile = InstanceProfile::new(name, version_id);
+    profile.created_at = created_at.map(str::to_string);
+    let id = profile.id.as_str().to_string();
+    profiles.upsert(profile.clone());
+    write_profiles(layout, &profiles)?;
+
+    let config_path = write_instance_config(layout, &InstanceConfig::new(id, version_id))?;
+    Ok(Registration {
+        profile,
+        config_path,
+        created: true,
+    })
+}
+
+/// 读实例清单（文件缺失 = 空列表，不算错误）。
+///
+/// # Errors
+///
+/// 读盘失败、非 UTF-8 或 JSON 非法。
+pub fn read_profiles(layout: &LauncherLayout) -> Result {
+    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/libraries.rs b/crates/core/src/game/install/libraries.rs
new file mode 100644
index 0000000..6638c38
--- /dev/null
+++ b/crates/core/src/game/install/libraries.rs
@@ -0,0 +1,258 @@
+//! 依赖库展开：主构件 + natives 分类器构件 → 待下载文件。
+//!
+//! 依据：`DevDocs/analyse/03-version-download.md` §6.4（libraries 含 natives 规则）、
+//! §6.8（目录布局速查）。
+//!
+//! 三条容易踩的规则：
+//! 1. **主构件与 natives 构件都要下**：老版本（lwjgl 2.x）一条库里同时有
+//!    `downloads.artifact` 与 `natives` 表，HMCL 也是两者都取；
+//! 2. **路径优先用 JSON 给的 `path`**（Mojang 权威值），缺了才按 Maven 坐标推导；
+//! 3. **`hint=local` 的库落到实例私有目录** `versions//libraries/`，其余一律进
+//!    恒共享的 `libraries/`（D20：任何模式都不按实例复制）。
+
+use std::path::{Path, PathBuf};
+
+use super::super::arguments::Environment;
+use super::super::layout::GameLayout;
+use super::super::library::Library;
+use super::plan::{FileRole, PlanFile};
+use crate::download::ResourceKind;
+
+/// 没写 `url` 的库兜底用的 Maven 基址（Mojang 官方库仓）。
+pub const DEFAULT_MAVEN_BASE: &str = "https://libraries.minecraft.net/";
+
+/// 展开一层（已合并）清单里的库列表。
+///
+/// 返回（文件清单，人读告警）。告警不致命：缺下载地址的库会被跳过并告知，
+/// 让用户知道"缺哪个文件"而不是拿到一个静默不完整的实例。
+#[must_use]
+pub fn plan(
+    layout: &GameLayout,
+    version_id: &str,
+    libraries: &[Library],
+    environment: &Environment,
+) -> (Vec, Vec) {
+    let mut files = Vec::new();
+    let mut warnings = Vec::new();
+
+    for library in libraries {
+        if !library.applies(environment) {
+            continue;
+        }
+        if library.coordinate().is_err() {
+            warnings.push(format!("库坐标不合法，已跳过：{}", library.name));
+            continue;
+        }
+        let Ok(relative) = library.relative_path() else {
+            warnings.push(format!("库路径推导失败，已跳过：{}", library.name));
+            continue;
+        };
+        let dest = library_dest(layout, version_id, library, &relative);
+
+        match library.artifact() {
+            Some(artifact) if artifact.has_url() => files.push(PlanFile {
+                role: FileRole::Library,
+                name: library.name.clone(),
+                url: artifact.url.clone().unwrap_or_default(),
+                sha1: artifact.sha1.clone(),
+                size: artifact.size,
+                dest,
+                resource: ResourceKind::Library,
+            }),
+            // natives-only 库（1.6 时代的 `lwjgl-platform` / `jinput-platform`）**没有主构件**，
+            // 只要 `downloads.classifiers`。这里若按坐标硬拼 URL 会拼出一个不存在的 jar
+            // （实测：官方与 BMCLAPI 双双 404）。判据是 `natives` 在场。
+            None if library.natives.is_some() => {}
+            // 魔改/现代 loader 的库常见"只给 name 不给 downloads"，按坐标拼仓库地址。
+            _ => files.push(PlanFile {
+                role: FileRole::Library,
+                name: library.name.clone(),
+                url: maven_url(library, &relative),
+                sha1: None,
+                size: None,
+                dest,
+                resource: ResourceKind::Library,
+            }),
+        }
+
+        // natives 分类器构件（存在才下；解压发生在启动期，不归安装管）。
+        let Some(classifier) = library.native_classifier(environment) else {
+            continue;
+        };
+        let Some(artifact) = library.native_artifact(&classifier) else {
+            warnings.push(format!(
+                "{} 的 natives 分类器 {classifier} 没有下载信息，已跳过",
+                library.name
+            ));
+            continue;
+        };
+        let Ok(native_relative) = library.native_relative_path(&classifier) else {
+            warnings.push(format!("{} 的 natives 路径推导失败，已跳过", library.name));
+            continue;
+        };
+        if !artifact.has_url() {
+            warnings.push(format!(
+                "{} 的 natives 构件 {classifier} 没有下载地址，已跳过",
+                library.name
+            ));
+            continue;
+        }
+        files.push(PlanFile {
+            role: FileRole::Native,
+            name: format!("{}:{classifier}", library.name),
+            url: artifact.url.clone().unwrap_or_default(),
+            sha1: artifact.sha1.clone(),
+            size: artifact.size,
+            dest: layout.libraries_dir().join(native_relative),
+            resource: ResourceKind::Library,
+        });
+    }
+
+    (files, warnings)
+}
+
+/// 库文件落点：实例私有（`hint=local`）或恒共享 `libraries/`。
+fn library_dest(
+    layout: &GameLayout,
+    version_id: &str,
+    library: &Library,
+    relative: &Path,
+) -> PathBuf {
+    if library.is_local() {
+        layout.version_libraries_dir(version_id).join(relative)
+    } else {
+        layout.libraries_dir().join(relative)
+    }
+}
+
+/// 按库声明（或默认）的 Maven 基址拼下载地址。
+fn maven_url(library: &Library, relative: &Path) -> String {
+    let base = library
+        .url
+        .as_deref()
+        .map(str::trim)
+        .filter(|base| !base.is_empty())
+        .unwrap_or(DEFAULT_MAVEN_BASE);
+    let path = relative.to_string_lossy().replace('\\', "/");
+    if base.ends_with('/') {
+        format!("{base}{path}")
+    } else {
+        format!("{base}/{path}")
+    }
+}
+
+/// 供上层判错用：库展开不产生硬失败，缺地址一律降级成告警。
+#[cfg(test)]
+mod tests {
+    use super::plan;
+    use crate::game::arguments::Environment;
+    use crate::game::layout::GameLayout;
+    use crate::game::library::Library;
+
+    fn environment() -> Environment {
+        Environment {
+            os: "windows".to_string(),
+            os_version: String::new(),
+            arch: "x86_64".to_string(),
+            ..Environment::host()
+        }
+    }
+
+    fn library_with_artifact(json: &str) -> Library {
+        serde_json::from_str(json).expect("库 JSON 应可解析")
+    }
+
+    #[test]
+    fn plans_artifact_at_maven_path() {
+        let library = library_with_artifact(
+            r#"{"name":"org.ow2.asm:asm:9.6","downloads":{"artifact":{"path":"org/ow2/asm/asm/9.6/asm-9.6.jar","sha1":"aa","size":122,"url":"https://libraries.minecraft.net/org/ow2/asm/asm/9.6/asm-9.6.jar"}}}"#,
+        );
+        let layout = GameLayout::new("/g/.minecraft");
+        let (files, warnings) = plan(&layout, "1.20.1", &[library], &environment());
+        assert!(warnings.is_empty());
+        assert_eq!(files.len(), 1);
+        assert_eq!(files[0].sha1.as_deref(), Some("aa"));
+        assert_eq!(files[0].size, Some(122));
+        assert!(files[0]
+            .dest
+            .ends_with("libraries/org/ow2/asm/asm/9.6/asm-9.6.jar"));
+    }
+
+    #[test]
+    fn natives_only_library_plans_no_artifact() {
+        // 1.6 时代的 lwjgl-platform / jinput-platform：有 natives 表、只有 classifiers，
+        // **没有 downloads.artifact**。按坐标硬拼主构件会拼出不存在的 jar（实测双源 404）。
+        let library = library_with_artifact(
+            r#"{"name":"org.lwjgl.lwjgl:lwjgl-platform:2.9.0",
+                "natives":{"windows":"natives-windows","linux":"natives-linux","osx":"natives-osx"},
+                "downloads":{"classifiers":{"natives-windows":{"path":"org/lwjgl/lwjgl/lwjgl-platform/2.9.0/lwjgl-platform-2.9.0-natives-windows.jar","sha1":"3f11","size":609967,"url":"https://libraries.minecraft.net/natives-windows.jar"}}}}"#,
+        );
+        let layout = GameLayout::new("/g/.minecraft");
+        let (files, warnings) = plan(&layout, "1.6.4", &[library], &environment());
+        assert!(warnings.is_empty(), "不该有告警：{warnings:?}");
+        assert_eq!(files.len(), 1, "只应有 natives 构件：{files:?}");
+        assert_eq!(files[0].role.as_str(), "native");
+        assert_eq!(files[0].sha1.as_deref(), Some("3f11"));
+    }
+
+    #[test]
+    fn plans_both_artifact_and_native_jar() {
+        let library = library_with_artifact(
+            r#"{"name":"org.lwjgl.lwjgl:lwjgl-platform:2.9.4","natives":{"windows":"natives-windows"},
+                "downloads":{"artifact":{"path":"org/lwjgl/lwjgl/lwjgl-platform/2.9.4/lwjgl-platform-2.9.4.jar","sha1":"bb","size":1,"url":"https://libraries.minecraft.net/a.jar"},
+                "classifiers":{"natives-windows":{"path":"org/lwjgl/lwjgl/lwjgl-platform/2.9.4/lwjgl-platform-2.9.4-natives-windows.jar","sha1":"cc","size":2,"url":"https://libraries.minecraft.net/b.jar"}}}}"#,
+        );
+        let layout = GameLayout::new("/g/.minecraft");
+        let (files, _) = plan(&layout, "1.7.10", &[library], &environment());
+        assert_eq!(files.len(), 2);
+        let native = files
+            .iter()
+            .find(|f| f.role.as_str() == "native")
+            .expect("应有 natives 构件");
+        assert_eq!(native.sha1.as_deref(), Some("cc"));
+        assert!(native
+            .dest
+            .ends_with("lwjgl-platform-2.9.4-natives-windows.jar"));
+    }
+
+    #[test]
+    fn derives_url_for_libraries_without_downloads() {
+        let library = library_with_artifact(
+            r#"{"name":"net.minecraftforge:forge:1.20.1-47.2.0:universal","url":"https://maven.minecraftforge.net/"}"#,
+        );
+        let layout = GameLayout::new("/g/.minecraft");
+        let (files, warnings) = plan(&layout, "1.20.1-forge", &[library], &environment());
+        assert!(warnings.is_empty());
+        assert_eq!(files.len(), 1);
+        assert_eq!(
+            files[0].url,
+            "https://maven.minecraftforge.net/net/minecraftforge/forge/1.20.1-47.2.0/forge-1.20.1-47.2.0-universal.jar"
+        );
+        assert!(files[0].sha1.is_none());
+    }
+
+    #[test]
+    fn skips_libraries_filtered_by_rules() {
+        let library = library_with_artifact(
+            r#"{"name":"org.lwjgl:lwjgl:3.3.2","rules":[{"action":"allow","os":{"name":"linux"}}],
+                "downloads":{"artifact":{"url":"https://libraries.minecraft.net/x.jar","sha1":"dd"}}}"#,
+        );
+        let layout = GameLayout::new("/g/.minecraft");
+        let (files, _) = plan(&layout, "1.20.1", &[library], &environment());
+        assert!(files.is_empty());
+    }
+
+    #[test]
+    fn local_hint_libraries_land_in_instance_dir() {
+        let library = library_with_artifact(
+            r#"{"name":"net.minecraftforge:forge:1.20.1-47.2.0","hint":"local",
+                "downloads":{"artifact":{"path":"net/minecraftforge/forge/1.20.1-47.2.0.jar","url":"https://libraries.minecraft.net/y.jar"}}}"#,
+        );
+        let layout = GameLayout::new("/g/.minecraft");
+        let (files, _) = plan(&layout, "inst", &[library], &environment());
+        assert_eq!(files.len(), 1);
+        assert!(files[0]
+            .dest
+            .ends_with("versions/inst/libraries/net/minecraftforge/forge/1.20.1-47.2.0.jar"));
+    }
+}
diff --git a/crates/core/src/game/install/mod.rs b/crates/core/src/game/install/mod.rs
new file mode 100644
index 0000000..63a3358
--- /dev/null
+++ b/crates/core/src/game/install/mod.rs
@@ -0,0 +1,193 @@
+//! 安装层：版本链 → 下载计划 → 分区落盘 → 实例登记（P2 核心闭环「装一个版本并启动它」）。
+//!
+//! 设计输入：`DevDocs/analyse/03-version-download.md` §6（逐类资源拆解）、
+//! `DevDocs/PlanDoc/04-data-and-config.md` §4（D20 实例模型）、§2（`.ULL/` 四分区）、
+//! `DevDocs/PlanDoc/05-download-and-mirrors.md` §2（分层下载策略）、
+//! `DevDocs/PlanDoc/research/04-launcher-configs.md` §5（实例键草案）。
+//!
+//! # 分工（每层只做一件事，谁都不越界）
+//!
+//! ```text
+//! source    网络：版本清单（带 TTL 缓存）→ 版本 JSON 链 → 资源索引      （异步）
+//! plan      纯计算：清单 + 索引 → InstallPlan（文件清单 / 总大小 / 角色）  （同步、可 dry-run）
+//! execute   落盘：逐文件跳过判定 + 下载引擎 + 原子写版本 JSON            （异步）
+//! instance  登记：profiles.json + config/instances/.json（稀疏、幂等）（同步）
+//! ```
+//!
+//! # 三条硬约定
+//!
+//! 1. **恒共享层**（D20）：`versions/` `assets/` `libraries/` 一律进游戏根，任何模式都不按实例复制；
+//! 2. **幂等**：重复装同一版本不重复下载（按 sha1 跳过）、不重复建实例（按 `versionId` 复用档案）；
+//! 3. **如实告知**：清单缺件（旧版无 `downloads.client` / 无 `assetIndex`）只降级成计划告警，
+//!    不静默假装成功，也不编造 URL。
+//!
+//! # 同步宿主怎么用
+//!
+//! `crates/cli` 不依赖 tokio：整段「规划 + 下载」包在一次
+//! [`crate::download::blocking::block_on`] 里，见 `ull install` 的实现。
+
+pub mod assets;
+pub mod execute;
+pub mod instance;
+pub mod libraries;
+pub mod plan;
+pub mod plan_view;
+mod report;
+pub mod source;
+
+use std::fmt;
+
+pub use assets::{AssetIndex, AssetObject, ASSET_OBJECT_BASE};
+pub use execute::{execute, execute_with_cancel};
+pub use instance::{register, InstanceConfig, Registration};
+pub use plan::{FileRole, InstallPlan, PlanFile, PlanInput};
+pub use report::{FileFailure, FileOutcome, FileStatus, InstallReport, ProgressSink};
+pub use source::{ManifestFreshness, RemoteSource, MANIFEST_TTL_MS};
+
+use crate::download::{DownloadError, DownloadErrorKind};
+use crate::game::error::GameError;
+
+/// 安装失败的大类（CLI 据此给稳定错误码，脚本可分流）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum InstallErrorKind {
+    /// 版本 id 在官方清单与本地仓库里都不存在。
+    VersionNotFound,
+    /// 网络侧失败（所有候选源都失败 / 超时 / 连接错误）。
+    Network,
+    /// 内容校验不符（镜像给了错内容）。
+    Integrity,
+    /// 本地 IO（写盘失败、目录权限）。
+    Io,
+    /// 元数据解析失败（清单/版本 JSON/资源索引坏了）。
+    Metadata,
+    /// 用户取消（`execute_with_cancel` 看到取消标志；不是失败，也不是网络问题）。
+    ///
+    /// CLI 永远走 [`execute`]（不传取消标志），所以这个大类只可能从 GUI 的取消路径出来。
+    Cancelled,
+}
+
+impl InstallErrorKind {
+    /// 稳定字符串 id（进 `--json` 的 `error.code`）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::VersionNotFound => "install_version_not_found",
+            Self::Network => "install_network",
+            Self::Integrity => "install_integrity",
+            Self::Io => "install_io",
+            Self::Metadata => "install_metadata",
+            Self::Cancelled => "install_cancelled",
+        }
+    }
+}
+
+/// 安装期错误：大类 + 人读说明 + 可选提示。
+#[derive(Debug, Clone)]
+pub struct InstallError {
+    kind: InstallErrorKind,
+    message: String,
+    hint: Option,
+}
+
+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/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..576b4ad
--- /dev/null
+++ b/crates/core/src/game/install/report.rs
@@ -0,0 +1,154 @@
+//! 安装报告与进度回调的形状（M105 从 `execute.rs` 搬出，守 400 行硬线）。
+//!
+//! 纯数据 + 纯方法：`execute.rs`（执行）与 CLI（汇总打印）都读它，谁也不改它。
+//! 搬移是**逐字**的，只有 `use` 断了回来（原来靠 `execute.rs` 的 import 活着）。
+
+use std::path::PathBuf;
+use std::sync::Arc;
+
+use crate::download::DownloadErrorKind;
+
+use super::plan::FileRole;
+
+/// 单个文件的结局。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum FileStatus {
+    /// 本次真的下载（或从缓存直取）并落盘。
+    Downloaded,
+    /// 已存在且校验通过，跳过。
+    Skipped,
+    /// 失败（原因在 [`FileOutcome::failure`]）。
+    Failed,
+}
+
+impl FileStatus {
+    /// 稳定字符串 id。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Downloaded => "downloaded",
+            Self::Skipped => "skipped",
+            Self::Failed => "failed",
+        }
+    }
+}
+
+/// 一次失败的分类信息（调用方据此给 `install_network` / `install_integrity` 等稳定码）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct FileFailure {
+    /// 下载错误分类。
+    pub kind: DownloadErrorKind,
+    /// 人读说明。
+    pub message: String,
+}
+
+/// 一个文件的执行结果。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct FileOutcome {
+    /// 角色。
+    pub role: FileRole,
+    /// 人读标识。
+    pub name: String,
+    /// 落盘路径。
+    pub dest: std::path::PathBuf,
+    /// 结局。
+    pub status: FileStatus,
+    /// 实际字节数（跳过时为盘上大小）。
+    pub bytes: u64,
+    /// 成功的源标识（`bmclapi` / `official` / `cache` / `metadata`）。
+    pub source: Option,
+    /// 失败详情。
+    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;
+
+/// 一次安装的执行结果。
+#[derive(Debug, Clone)]
+pub struct InstallReport {
+    /// 逐文件结果（顺序不保证，按角色/大小汇总即可）。
+    pub files: Vec,
+    /// 版本清单落盘路径；`None` = 有文件失败，故意没写（见 `execute` 的说明）。
+    pub version_json: 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..881ce3d
--- /dev/null
+++ b/crates/core/src/game/install/tests/execute.rs
@@ -0,0 +1,397 @@
+//! 落盘执行：跳过判定（三级）、幂等重装、预取元数据落盘、失败分类聚合。
+//!
+//! 全部用例都**已把文件放好**或**只做纯函数判定**，因此不发网络请求。
+
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering};
+use std::sync::Arc;
+
+use crate::download::verify;
+use crate::download::ResourceKind;
+use crate::download::{
+    ContentCache, DownloadEngine, DownloadErrorKind, EngineConfig, HashAlgo, HealthRegistry,
+    MirrorTable, RegionProfile,
+};
+use crate::game::arguments::Environment;
+use crate::game::install::assets::{AssetIndex, AssetObject};
+use crate::game::install::execute::{
+    current_bytes, execute, execute_with_cancel, FileOutcome, FileStatus,
+};
+use crate::game::install::plan::{FileRole, InstallPlan, PlanFile, PlanInput};
+use crate::game::layout::GameLayout;
+use crate::game::manifest::VersionJson;
+
+fn temp_root(tag: &str) -> PathBuf {
+    static COUNTER: AtomicU64 = AtomicU64::new(0);
+    let unique = COUNTER.fetch_add(1, Ordering::Relaxed);
+    std::env::temp_dir().join(format!(
+        "ull-install-exec-{}-{tag}-{unique}",
+        std::process::id()
+    ))
+}
+
+fn engine(root: &Path) -> DownloadEngine {
+    DownloadEngine::new(
+        EngineConfig::default(),
+        Arc::new(MirrorTable::builtin()),
+        Arc::new(RegionProfile::direct(0)),
+        Arc::new(HealthRegistry::in_memory()),
+        Arc::new(ContentCache::open(root.join("cache"))),
+    )
+}
+
+fn sha1_of(bytes: &[u8]) -> String {
+    verify::digest_bytes(HashAlgo::Sha1, bytes)
+}
+
+fn write_file(path: &Path, bytes: &[u8]) {
+    std::fs::create_dir_all(path.parent().expect("有父目录")).expect("建目录");
+    std::fs::write(path, bytes).expect("写文件");
+}
+
+#[test]
+fn current_bytes_matches_by_sha1_then_size_then_existence() {
+    let root = temp_root("current");
+    let payload = b"client jar payload";
+    let dest: PathBuf = root.join("versions/1.20.1/1.20.1.jar");
+    write_file(&dest, payload);
+
+    let with_sha1 = PlanFile {
+        role: FileRole::ClientJar,
+        name: "1.20.1".to_string(),
+        url: "https://example.invalid/x.jar".to_string(),
+        sha1: Some(sha1_of(payload)),
+        size: Some(payload.len() as u64),
+        dest: dest.clone(),
+        resource: ResourceKind::ClientJar,
+    };
+    assert_eq!(current_bytes(&with_sha1), Some(payload.len() as u64));
+
+    let wrong_sha1 = PlanFile {
+        sha1: Some("0".repeat(40)),
+        ..with_sha1.clone()
+    };
+    assert_eq!(current_bytes(&wrong_sha1), None, "sha1 不符必须重下");
+
+    let size_only = PlanFile {
+        sha1: None,
+        size: Some(payload.len() as u64),
+        ..with_sha1.clone()
+    };
+    assert_eq!(current_bytes(&size_only), Some(payload.len() as u64));
+
+    let size_mismatch = PlanFile {
+        sha1: None,
+        size: Some(1),
+        ..with_sha1.clone()
+    };
+    assert_eq!(current_bytes(&size_mismatch), None);
+
+    let bare = PlanFile {
+        sha1: None,
+        size: None,
+        ..with_sha1.clone()
+    };
+    assert_eq!(current_bytes(&bare), Some(payload.len() as u64), "存在即信");
+
+    let missing = PlanFile {
+        dest: root.join("nope.jar"),
+        ..with_sha1
+    };
+    assert_eq!(current_bytes(&missing), None);
+    std::fs::remove_dir_all(&root).ok();
+}
+
+/// 一份"客户端 jar 已存在"的清单 + 计划，用于幂等与跳过用例。
+fn plan_with_existing_jar(root: &Path) -> (InstallPlan, Vec) {
+    let payload = b"already installed client jar".to_vec();
+    let layout = GameLayout::new(root);
+    let sha1 = sha1_of(&payload);
+    write_file(&layout.version_jar("1.20.1"), &payload);
+
+    let resolved = VersionJson::from_json_str(&format!(
+        r#"{{"id": "1.20.1", "mainClass": "net.minecraft.client.main.Main",
+            "downloads": {{"client": {{"sha1": "{sha1}", "size": {}, "url": "https://piston-data.mojang.com/v1/objects/{sha1}/client.jar"}}}}}}"#,
+        payload.len()
+    ))
+    .expect("清单应可解析");
+
+    let plan = InstallPlan::build(PlanInput {
+        layout: &layout,
+        version_id: "1.20.1",
+        resolved: &resolved,
+        asset_index: None,
+        environment: &Environment::host(),
+    })
+    .expect("组计划应成功");
+    (plan, payload)
+}
+
+#[tokio::test]
+async fn skips_existing_files_and_writes_version_json() {
+    let root = temp_root("skip");
+    let (plan, payload) = plan_with_existing_jar(&root);
+    let engine = engine(&root);
+    let calls = Arc::new(AtomicUsize::new(0));
+    let sink_calls = Arc::clone(&calls);
+
+    let report = execute(
+        &engine,
+        &plan,
+        4,
+        Some(Arc::new(move |_outcome: &FileOutcome| {
+            sink_calls.fetch_add(1, Ordering::Relaxed);
+        })),
+    )
+    .await
+    .expect("执行应成功");
+
+    assert!(report.is_complete());
+    assert_eq!(report.downloaded(), 0, "已存在且校验通过的文件不该重下");
+    assert_eq!(report.skipped(), 1);
+    assert_eq!(report.bytes(), 0);
+    assert_eq!(calls.load(Ordering::Relaxed), 1, "每个文件回调一次");
+
+    // 版本清单必须落盘且能被重新解析。
+    let version_json = report.version_json.clone().expect("全量成功应写版本清单");
+    let text = std::fs::read_to_string(&version_json).expect("版本清单应已写盘");
+    let written = VersionJson::from_json_str(&text).expect("写出的清单应可解析");
+    assert_eq!(written.id.as_deref(), Some("1.20.1"));
+    assert_eq!(
+        written.main_class.as_deref(),
+        Some("net.minecraft.client.main.Main")
+    );
+
+    // 盘上内容没被改动（跳过 = 不动文件）。
+    assert_eq!(
+        std::fs::read(GameLayout::new(&root).version_jar("1.20.1")).expect("读 jar"),
+        payload
+    );
+    std::fs::remove_dir_all(&root).ok();
+}
+
+/// **取消：一个文件都不下、版本清单不落盘**（M105 的「半成品不许变成品」）。
+///
+/// 标志**开工前**就置位 ⇒ 走「一个文件都不起」那条路，全程零网络（所以这条能进 CI，
+/// 真网络的那条在 `crates/presenter/src/host/cancel_tests.rs`，`#[ignore]` 守着）。
+///
+/// 抓得住：取消返回 `Cancelled` 大类、`version_json` 没写、盘上没多出 jar。
+/// 抓不住：在飞的文件被掐断的那一刻（那要真网络 + 真字节流，见 presenter 的实测装置）。
+#[tokio::test]
+async fn cancelling_before_the_first_file_downloads_nothing_and_writes_no_manifest() {
+    let root = temp_root("cancel");
+    let layout = GameLayout::new(&root);
+    // jar **不在**盘上：真跑就会去下（本用例不许它跑起来）
+    let sha1 = "3f".repeat(20);
+    let resolved = VersionJson::from_json_str(&format!(
+        r#"{{"id": "1.20.1", "mainClass": "net.minecraft.client.main.Main",
+            "downloads": {{"client": {{"sha1": "{sha1}", "size": 32, "url": "https://piston-data.mojang.com/v1/objects/{sha1}/client.jar"}}}}}}"#
+    ))
+    .expect("清单应可解析");
+    let plan = InstallPlan::build(PlanInput {
+        layout: &layout,
+        version_id: "1.20.1",
+        resolved: &resolved,
+        asset_index: None,
+        environment: &Environment::host(),
+    })
+    .expect("组计划应成功");
+
+    let cancel = std::sync::atomic::AtomicBool::new(true);
+    let error = execute_with_cancel(&engine(&root), &plan, 4, None, Some(&cancel))
+        .await
+        .expect_err("取消了就不要返回 report");
+    assert_eq!(
+        error.kind(),
+        crate::game::install::InstallErrorKind::Cancelled,
+        "取消是独立大类，不是网络/IO 失败"
+    );
+    assert!(
+        !plan.version_json_path.is_file(),
+        "取消后不许落版本清单（否则半成品会被当成已安装）"
+    );
+    assert!(!layout.version_jar("1.20.1").is_file(), "一个文件都不该下");
+    std::fs::remove_dir_all(&root).ok();
+}
+
+#[tokio::test]
+async fn reinstalling_twice_is_idempotent() {
+    let root = temp_root("idempotent");
+    let (plan, _) = plan_with_existing_jar(&root);
+    let engine = engine(&root);
+    let first = execute(&engine, &plan, 2, None).await.expect("第一次");
+    let second = execute(&engine, &plan, 2, None).await.expect("第二次");
+
+    assert!(first.is_complete() && second.is_complete());
+    assert_eq!(second.downloaded(), 0);
+    assert_eq!(second.skipped(), second.files.len());
+    std::fs::remove_dir_all(&root).ok();
+}
+
+#[tokio::test]
+async fn prefetched_metadata_is_written_without_network() {
+    let root = temp_root("prefetch");
+    let layout = GameLayout::new(&root);
+    let hash = "0f9d6b1c0d5f4e3b2a1908070605040302010f0e";
+    // 规划期"已经下载到内存"的资源索引字节（sha1 必须与清单声明一致，否则跳过判定不成立）。
+    let index_bytes = br#"{"objects":{}}"#.to_vec();
+    let index_sha1 = sha1_of(&index_bytes);
+    let resolved = VersionJson::from_json_str(&format!(
+        r#"{{"id": "1.20.1", "assetIndex": {{"id": "17", "sha1": "{index_sha1}", "size": {}, "url": "https://piston-meta.mojang.com/v1/packages/{index_sha1}/17.json"}}}}"#,
+        index_bytes.len()
+    ))
+    .expect("清单应可解析");
+    let mut index = AssetIndex::default();
+    index.objects.insert(
+        "minecraft/lang/zh_cn.json".to_string(),
+        AssetObject {
+            hash: hash.to_string(),
+            size: 3,
+        },
+    );
+
+    let mut plan = InstallPlan::build(PlanInput {
+        layout: &layout,
+        version_id: "1.20.1",
+        resolved: &resolved,
+        asset_index: Some(&index),
+        environment: &Environment::host(),
+    })
+    .expect("组计划应成功");
+
+    let index_dest = layout.asset_index("17");
+    plan.prefetch(index_dest.clone(), index_bytes.clone());
+
+    // 只跑索引这一个文件：把资源对象从计划里摘掉，避免真发网络请求。
+    plan.files.retain(|file| file.role != FileRole::Asset);
+    let engine = engine(&root);
+    let report = execute(&engine, &plan, 2, None).await.expect("执行应成功");
+
+    assert!(report.is_complete(), "不该有失败：{:?}", report.failures(3));
+    assert_eq!(report.downloaded(), 1);
+    assert_eq!(
+        std::fs::read(&index_dest).expect("索引应已写盘"),
+        index_bytes
+    );
+    let outcome = report
+        .files
+        .iter()
+        .find(|file| file.dest == index_dest)
+        .expect("应有索引结果");
+    assert_eq!(outcome.source.as_deref(), Some("metadata"));
+
+    // 重跑：索引已在盘上且 sha1 一致 → 跳过，不重写、不算"下载"。
+    let again = execute(&engine, &plan, 2, None).await.expect("第二次");
+    assert_eq!(again.downloaded(), 0, "重装不该再写索引");
+    assert_eq!(again.skipped(), 1);
+    std::fs::remove_dir_all(&root).ok();
+}
+
+#[test]
+fn failure_kind_prefers_integrity() {
+    let failed = |kind: DownloadErrorKind| FileOutcome {
+        role: FileRole::Asset,
+        name: "x".to_string(),
+        dest: PathBuf::from("/x"),
+        status: FileStatus::Failed,
+        bytes: 0,
+        source: None,
+        failure: Some(crate::game::install::FileFailure {
+            kind,
+            message: "boom".to_string(),
+        }),
+    };
+    let report = crate::game::install::InstallReport {
+        files: vec![
+            failed(DownloadErrorKind::AllSourcesFailed),
+            failed(DownloadErrorKind::Integrity),
+        ],
+        version_json: None,
+        warnings: Vec::new(),
+    };
+    assert_eq!(report.failed(), 2);
+    assert!(!report.is_complete());
+    assert_eq!(report.failure_kind(), Some(DownloadErrorKind::Integrity));
+    assert_eq!(report.failures(1).len(), 1);
+}
+
+/// **取消之后，剩下的文件连 `install_one` 都不许进**（复审 P2-1 的守门，p1）。
+///
+/// 现场（修前）：标志检查只写在 `select` 的右支，而 `select` 先轮询左支 —— 左支第一次 poll
+/// 就把 `engine.download(…)` 派出去了。于是取消后 `buffer_unordered` 立刻让出槽位、流继续被拉，
+/// **每一个剩余 item 都会各发一次整文件 sha1 + 一次请求**，1.20.1 那种四位数文件的 plan 会一直
+/// 走到列表末尾；盘上已就绪的文件第一 poll 就 `Ready` ⇒ 还会各回调一次 `sink`。
+///
+/// 这条用例把它钉成可数的东西：三个文件全在盘上（`install_one` 直接判 Skipped、零网络），
+/// 并发 1，`sink` 第一次回调时置取消标志 —— 于是「取消后还剩几个文件被处理」= `sink` 的调用次数。
+/// 修好后必须是 **1**（只有第一个），修前是 **3**。
+///
+/// 抓得住：`async move` 开头那句 `if is_cancelled(cancel) { return None; }` 被删掉/挪到 `select` 右支。
+/// 抓不住：在飞的那一个文件被掐断的时机（那要真字节流，见 presenter 的真网络装置）。
+#[tokio::test]
+async fn cancelling_mid_run_stops_creating_remaining_files() {
+    let root = temp_root("cancel-mid");
+    let layout = GameLayout::new(&root);
+    let jar = b"client jar payload".to_vec();
+    let sha1 = sha1_of(&jar);
+    write_file(&layout.version_jar("1.20.1"), &jar);
+    let resolved = VersionJson::from_json_str(&format!(
+        r#"{{"id": "1.20.1", "mainClass": "net.minecraft.client.main.Main",
+            "downloads": {{"client": {{"sha1": "{sha1}", "size": {}, "url": "https://piston-data.mojang.com/v1/objects/{sha1}/client.jar"}}}}}}"#,
+        jar.len()
+    ))
+    .expect("清单应可解析");
+    let mut plan = InstallPlan::build(PlanInput {
+        layout: &layout,
+        version_id: "1.20.1",
+        resolved: &resolved,
+        asset_index: None,
+        environment: &Environment::host(),
+    })
+    .expect("组计划应成功");
+
+    // 再挂两个"已在盘上"的库文件：内容与声明的 sha1 一致 ⇒ 跳过判定成立、零网络。
+    for name in ["org.example:a:1.0", "org.example:b:1.0"] {
+        let bytes = format!("payload for {name}").into_bytes();
+        let dest = root
+            .join("libraries")
+            .join(format!("{}.jar", name.replace(':', "-")));
+        write_file(&dest, &bytes);
+        plan.files.push(PlanFile {
+            role: FileRole::Library,
+            name: name.to_string(),
+            url: format!("https://example.invalid/{name}.jar"),
+            sha1: Some(sha1_of(&bytes)),
+            size: Some(bytes.len() as u64),
+            dest,
+            resource: ResourceKind::Library,
+        });
+    }
+    assert_eq!(plan.files.len(), 3, "三个文件全在盘上 ⇒ 全程零网络");
+
+    let seen = Arc::new(AtomicUsize::new(0));
+    // `sink` 是 `Fn + 'static`，所以标志也必须 `Arc` 进来；第一次回调就置取消。
+    let flag = Arc::new(std::sync::atomic::AtomicBool::new(false));
+    let sink_seen = Arc::clone(&seen);
+    let sink_flag = Arc::clone(&flag);
+    let sink: crate::game::install::ProgressSink = Arc::new(move |_outcome: &FileOutcome| {
+        sink_seen.fetch_add(1, Ordering::SeqCst);
+        sink_flag.store(true, Ordering::SeqCst);
+    });
+
+    let error = execute_with_cancel(&engine(&root), &plan, 1, Some(sink), Some(flag.as_ref()))
+        .await
+        .expect_err("取消之后不许返回成功 report");
+    assert_eq!(
+        error.kind(),
+        crate::game::install::InstallErrorKind::Cancelled
+    );
+    assert_eq!(
+        seen.load(Ordering::SeqCst),
+        1,
+        "取消只该让**第一个**文件走完回调；剩下的 item 必须连 install_one 都不进\
+         （修前这里会是 3：每个剩余文件各多算一次 sha1、各多发一次请求）"
+    );
+    assert!(!plan.version_json_path.is_file(), "取消后不许落版本清单");
+    std::fs::remove_dir_all(&root).ok();
+}
diff --git a/crates/core/src/game/install/tests/instance.rs b/crates/core/src/game/install/tests/instance.rs
new file mode 100644
index 0000000..797859c
--- /dev/null
+++ b/crates/core/src/game/install/tests/instance.rs
@@ -0,0 +1,122 @@
+//! 实例登记：幂等（同版本同名复用）、`isolation: inherit` 不落盘、两份文件各就各位。
+
+use std::path::PathBuf;
+
+use crate::game::install::instance::{
+    read_instance_config, read_profiles, register, InstanceConfig, Isolation,
+};
+use crate::platform::layout::LauncherLayout;
+
+fn temp_layout(tag: &str) -> (LauncherLayout, PathBuf) {
+    let unique = format!(
+        "{}-{}-{tag}",
+        std::process::id(),
+        std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .map(|d| d.as_nanos())
+            .unwrap_or(0)
+    );
+    let root = std::env::temp_dir().join(format!("ull-install-instance-{unique}"));
+    let layout = LauncherLayout::new(&root);
+    layout.ensure().expect("建四分区");
+    (layout, root)
+}
+
+#[test]
+fn registers_profile_and_sparse_instance_config() {
+    let (layout, root) = temp_layout("new");
+    let registration = register(
+        &layout,
+        "1.20.1",
+        "1.20.1",
+        Some("2026-10-30T00:00:00.000Z"),
+    )
+    .expect("登记应成功");
+    assert!(registration.created);
+    assert!(
+        registration.profile.id.is_uuid_shaped(),
+        "实例 id 必须是稳定 UUID 形状"
+    );
+    assert!(registration.config_path.is_file());
+
+    let profiles = read_profiles(&layout).expect("读实例清单");
+    assert_eq!(profiles.len(), 1);
+    assert_eq!(profiles.profiles[0].version_id, "1.20.1");
+    assert_eq!(
+        profiles.profiles[0].created_at.as_deref(),
+        Some("2026-10-30T00:00:00.000Z")
+    );
+
+    // 每实例设置：id / versionId / schemaVersion 在，isolation 缺省不落盘。
+    let text = std::fs::read_to_string(®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/mod.rs b/crates/core/src/game/install/tests/mod.rs
new file mode 100644
index 0000000..21cecbe
--- /dev/null
+++ b/crates/core/src/game/install/tests/mod.rs
@@ -0,0 +1,8 @@
+//! `game::install` 的单元测试：计划正确性 / 跳过与幂等 / 实例登记。
+//!
+//! 刻意**不打真实网络**：计划是纯计算，跳过判定只看盘，实例登记只看文件系统。
+//! 需要"引擎"的用例只要求它"不联网也能跑"（全部文件已就位 → 全跳过）。
+
+mod execute;
+mod instance;
+mod plan;
diff --git a/crates/core/src/game/install/tests/plan.rs b/crates/core/src/game/install/tests/plan.rs
new file mode 100644
index 0000000..dddf582
--- /dev/null
+++ b/crates/core/src/game/install/tests/plan.rs
@@ -0,0 +1,285 @@
+//! 计划正确性：多级继承折叠后的文件清单、URL/sha1/落点逐项、JSON 形状。
+
+use std::sync::atomic::{AtomicU64, Ordering};
+
+use crate::game::arguments::Environment;
+use crate::game::inherit::resolve;
+use crate::game::install::assets::{AssetIndex, AssetObject};
+use crate::game::install::plan::{FileRole, InstallPlan, PlanInput};
+use crate::game::layout::GameLayout;
+use crate::game::manifest::VersionJson;
+
+fn temp_root(tag: &str) -> std::path::PathBuf {
+    static COUNTER: AtomicU64 = AtomicU64::new(0);
+    let unique = COUNTER.fetch_add(1, Ordering::Relaxed);
+    std::env::temp_dir().join(format!(
+        "ull-install-plan-{}-{tag}-{unique}",
+        std::process::id()
+    ))
+}
+
+/// 三层继承：base（客户端 jar + 资源索引 + 库）← mid（库）← top（库）。
+fn resolved_three_levels() -> VersionJson {
+    let base = VersionJson::from_json_str(
+        r#"{
+            "id": "base",
+            "mainClass": "net.minecraft.client.main.Main",
+            "downloads": {"client": {"sha1": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "size": 100, "url": "https://piston-data.mojang.com/v1/objects/aa/client.jar"}},
+            "assetIndex": {"id": "17", "sha1": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "size": 200, "totalSize": 300, "url": "https://piston-meta.mojang.com/v1/packages/bb/17.json"},
+            "assets": "17",
+            "libraries": [
+                {"name": "org.ow2.asm:asm:9.6", "downloads": {"artifact": {"path": "org/ow2/asm/asm/9.6/asm-9.6.jar", "sha1": "c1", "size": 11, "url": "https://libraries.minecraft.net/org/ow2/asm/asm/9.6/asm-9.6.jar"}}},
+                {"name": "org.lwjgl:lwjgl:3.3.2", "rules": [{"action": "allow", "os": {"name": "linux"}}], "downloads": {"artifact": {"url": "https://libraries.minecraft.net/lwjgl-linux-only.jar", "sha1": "c2", "size": 5}}}
+            ]
+        }"#,
+    )
+    .expect("base 清单应可解析");
+    let mid = VersionJson::from_json_str(
+        r#"{"id": "mid", "inheritsFrom": "base", "libraries": [
+            {"name": "net.minecraftforge:forge:1.20.1-47.2.0", "downloads": {"artifact": {"path": "net/minecraftforge/forge/1.20.1-47.2.0/forge-1.20.1-47.2.0.jar", "sha1": "c3", "size": 22, "url": "https://maven.minecraftforge.net/forge.jar"}}}
+        ]}"#,
+    )
+    .expect("mid 清单应可解析");
+    let top = VersionJson::from_json_str(
+        r#"{"id": "top", "inheritsFrom": "mid", "libraries": [
+            {"name": "top.patch:core:1.0", "downloads": {"artifact": {"path": "top/patch/core/1.0/core-1.0.jar", "sha1": "c4", "size": 33, "url": "https://example.invalid/core-1.0.jar"}}}
+        ], "logging": {"client": {"argument": "-Dlog4j.configurationFile=${path}", "file": {"id": "client-1.12.xml", "sha1": "dd", "size": 44, "url": "https://piston-data.mojang.com/v1/objects/dd/client-1.12.xml"}}}}"#,
+    )
+    .expect("top 清单应可解析");
+
+    let mut table = std::collections::BTreeMap::new();
+    table.insert("base".to_string(), base);
+    table.insert("mid".to_string(), mid);
+    table.insert("top".to_string(), top.clone());
+    resolve(&table, &top).expect("三层继承应解析成功")
+}
+
+fn asset_index() -> AssetIndex {
+    let mut index = AssetIndex::default();
+    index.objects.insert(
+        "minecraft/lang/zh_cn.json".to_string(),
+        AssetObject {
+            hash: "0f9d6b1c0d5f4e3b2a1908070605040302010f0e".to_string(),
+            size: 55,
+        },
+    );
+    index
+}
+
+fn build(layout: &GameLayout, resolved: &VersionJson, index: Option<&AssetIndex>) -> InstallPlan {
+    InstallPlan::build(PlanInput {
+        layout,
+        version_id: "top",
+        resolved,
+        asset_index: index,
+        environment: &Environment::host(),
+    })
+    .expect("组计划应成功")
+}
+
+#[test]
+fn folds_inheritance_chain_into_one_plan() {
+    let root = temp_root("chain");
+    let layout = GameLayout::new(&root);
+    let resolved = resolved_three_levels();
+    // 三层库都保留（父在前、子在后，去重后按角色/路径排序）。
+    assert_eq!(resolved.libraries.as_ref().map(Vec::len), Some(4));
+
+    let index = asset_index();
+    let plan = build(&layout, &resolved, Some(&index));
+
+    // 客户端 jar 1 + 库 4（linux 规则那条在 Windows 上被过滤）+ 索引 1 + 资源 1 + 日志配置 1。
+    let host_linux = Environment::host().os == "linux";
+    let expected_libraries = if host_linux { 4 } else { 3 };
+    assert_eq!(
+        plan.by_role()
+            .get(&FileRole::ClientJar)
+            .map(|entry| entry.0),
+        Some(1)
+    );
+    assert_eq!(
+        plan.by_role().get(&FileRole::Library).map(|entry| entry.0),
+        Some(expected_libraries)
+    );
+    assert_eq!(
+        plan.by_role()
+            .get(&FileRole::AssetIndex)
+            .map(|entry| entry.0),
+        Some(1)
+    );
+    assert_eq!(
+        plan.by_role().get(&FileRole::Asset).map(|entry| entry.0),
+        Some(1)
+    );
+    assert_eq!(
+        plan.by_role()
+            .get(&FileRole::LogConfig)
+            .map(|entry| entry.0),
+        Some(1)
+    );
+    assert!(plan.warnings.is_empty(), "不应有告警：{:?}", plan.warnings);
+    std::fs::remove_dir_all(&root).ok();
+}
+
+#[test]
+fn client_jar_lands_in_version_dir_with_manifest_hash() {
+    let root = temp_root("jar");
+    let layout = GameLayout::new(&root);
+    let resolved = resolved_three_levels();
+    let plan = build(&layout, &resolved, None);
+
+    let jar = plan
+        .files
+        .iter()
+        .find(|file| file.role == FileRole::ClientJar)
+        .expect("应有客户端 jar");
+    assert_eq!(plan.jar_id, "top");
+    assert!(jar.dest.ends_with("versions/top/top.jar"));
+    assert_eq!(
+        jar.sha1.as_deref(),
+        Some("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
+    );
+    assert_eq!(jar.size, Some(100));
+    assert_eq!(
+        jar.url,
+        "https://piston-data.mojang.com/v1/objects/aa/client.jar"
+    );
+    std::fs::remove_dir_all(&root).ok();
+}
+
+#[test]
+fn asset_object_paths_and_hashes_are_exact() {
+    let root = temp_root("assets");
+    let layout = GameLayout::new(&root);
+    let resolved = resolved_three_levels();
+    let index = asset_index();
+    let plan = build(&layout, &resolved, Some(&index));
+
+    let object = plan
+        .files
+        .iter()
+        .find(|file| file.role == FileRole::Asset)
+        .expect("应有资源对象");
+    assert_eq!(
+        object.url,
+        "https://resources.download.minecraft.net/0f/0f9d6b1c0d5f4e3b2a1908070605040302010f0e"
+    );
+    assert_eq!(
+        object.sha1.as_deref(),
+        Some("0f9d6b1c0d5f4e3b2a1908070605040302010f0e")
+    );
+    assert_eq!(object.size, Some(55));
+    assert!(object
+        .dest
+        .ends_with("assets/objects/0f/0f9d6b1c0d5f4e3b2a1908070605040302010f0e"));
+
+    let index_file = plan
+        .files
+        .iter()
+        .find(|file| file.role == FileRole::AssetIndex)
+        .expect("应有资源索引");
+    assert!(index_file.dest.ends_with("assets/indexes/17.json"));
+    assert_eq!(
+        index_file.sha1.as_deref(),
+        Some("bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb")
+    );
+    std::fs::remove_dir_all(&root).ok();
+}
+
+#[test]
+fn shares_libraries_across_versions_and_sums_totals() {
+    let root = temp_root("totals");
+    let layout = GameLayout::new(&root);
+    let resolved = resolved_three_levels();
+    let index = asset_index();
+    let plan = build(&layout, &resolved, Some(&index));
+
+    let (total, unknown) = plan.total_bytes();
+    // jar 100 + 索引 200 + 资源 55 + 日志 44 + 各库大小（host 上生效的那几条）。
+    assert_eq!(unknown, 0);
+    assert!(total >= 399, "总大小应至少含 jar+索引+资源+日志：{total}");
+
+    // 库落恒共享层（不是实例私有）。
+    for file in plan
+        .files
+        .iter()
+        .filter(|file| file.role == FileRole::Library)
+    {
+        assert!(file.dest.starts_with(root.join("libraries")));
+    }
+    std::fs::remove_dir_all(&root).ok();
+}
+
+#[test]
+fn warns_instead_of_inventing_urls_for_legacy_manifests() {
+    let root = temp_root("legacy");
+    let layout = GameLayout::new(&root);
+    let legacy = VersionJson::from_json_str(r#"{"id": "c0.30_01c", "assets": "legacy"}"#)
+        .expect("旧清单应可解析");
+    let plan = build(&layout, &legacy, None);
+
+    assert!(plan.files.is_empty(), "旧清单没有可下文件");
+    assert_eq!(
+        plan.warnings.len(),
+        2,
+        "应分别告警缺 jar 与缺索引：{:?}",
+        plan.warnings
+    );
+    assert!(plan.warnings.iter().any(|w| w.contains("downloads.client")));
+    assert!(plan.warnings.iter().any(|w| w.contains("assetIndex")));
+    std::fs::remove_dir_all(&root).ok();
+}
+
+#[test]
+fn json_shape_is_stable_for_dry_run_consumers() {
+    let root = temp_root("json");
+    let layout = GameLayout::new(&root);
+    let resolved = resolved_three_levels();
+    let index = asset_index();
+    let plan = build(&layout, &resolved, Some(&index));
+
+    let summary = plan.summary_json();
+    assert_eq!(summary["version_id"], "top");
+    assert_eq!(summary["jar_id"], "top");
+    assert_eq!(summary["file_count"], plan.file_count());
+    assert!(summary["total_bytes"].as_u64().unwrap_or(0) > 0);
+    assert!(summary["by_role"]["client_jar"]["files"].as_u64() == Some(1));
+    assert!(summary["warnings"].is_array());
+
+    let files = plan.files_json();
+    assert_eq!(files.len(), plan.file_count());
+    for row in &files {
+        assert!(row["role"].as_str().is_some());
+        assert!(row["url"].as_str().is_some());
+        assert!(row["dest"].as_str().is_some());
+        assert!(row["resource"].as_str().is_some());
+    }
+    std::fs::remove_dir_all(&root).ok();
+}
+
+#[test]
+fn deduplicates_same_destination_and_prefers_hashed_copy() {
+    let root = temp_root("dedupe");
+    let layout = GameLayout::new(&root);
+    let resolved = VersionJson::from_json_str(
+        r#"{"id": "1.20.1", "libraries": [
+            {"name": "a.b:c:1", "downloads": {"artifact": {"path": "a/b/c/1/c-1.jar", "url": "https://libraries.minecraft.net/c-1.jar"}}},
+            {"name": "a.b:c:1", "downloads": {"artifact": {"path": "a/b/c/1/c-1.jar", "sha1": "ff", "size": 9, "url": "https://libraries.minecraft.net/c-1.jar"}}}
+        ]}"#,
+    )
+    .expect("清单应可解析");
+    let plan = build(&layout, &resolved, None);
+
+    let libraries: Vec<_> = plan
+        .files
+        .iter()
+        .filter(|file| file.role == FileRole::Library)
+        .collect();
+    assert_eq!(libraries.len(), 1, "同一落点只应留一条");
+    assert_eq!(
+        libraries[0].sha1.as_deref(),
+        Some("ff"),
+        "应保留带 sha1 的那条"
+    );
+    std::fs::remove_dir_all(&root).ok();
+}
diff --git a/crates/core/src/game/isolation.rs b/crates/core/src/game/isolation.rs
new file mode 100644
index 0000000..e575962
--- /dev/null
+++ b/crates/core/src/game/isolation.rs
@@ -0,0 +1,345 @@
+//! 实例隔离档位的**派生**与**切换检测**（D20 定案）。
+//!
+//! 依据：`DevDocs/PlanDoc/research/04-launcher-configs.md` §5.1-§5.2（键草案 + 切换检测）、
+//! `DevDocs/analyse/07-settings-packaging-update.md` §2.4（HMCL 用 `runningDirectory` 覆盖表达隔离）、
+//! `DevDocs/PlanDoc/04-data-and-config.md` §4（实例模型）。
+//!
+//! # D20 的语义（用户定案，不可改）
+//!
+//! - **默认隔离**：全局 `instances.mode` 默认 `isolated`，用户可手动切 `shared`；
+//! - **恒共享层不可配**：`versions/` `assets/` `libraries/` 永远在游戏根，隔离只改**运行目录**
+//!   （= `--gameDir` 的取值 + 进程 CWD），见 [`SHARED_LAYERS`]；
+//! - **切换不迁移 + 双侧内容提示**：切档只改路径语义，不动任何数据；两侧都有内容时提示
+//!   （[`ModeChange::take_warning`]），避免「存档消失」错觉。
+//!
+//! # 覆盖链（三层，左优先）
+//!
+//! ```text
+//! 临时启动参数（--game-dir 之类）  >  实例 isolation  >  全局 instances.mode
+//! ```
+//!
+//! `isolation` 的 `inherit` 不是第四个档位，而是「键不存在」→ 落到全局（[`IsolationMode`]）；
+//! 这样改全局对存量实例立即生效，不需要迁移（research/04 §5.3 的 PCL2 反面教材）。
+//!
+//! 本模块只做**纯路径计算 + 只读探测**：不建目录、不搬文件、不写配置。
+
+use std::path::{Path, PathBuf};
+
+use serde::{Deserialize, Serialize};
+
+use super::error::GameError;
+use super::install::instance::{InstanceConfig, Isolation};
+use super::layout::GameLayout;
+
+/// 恒共享层（任何隔离档位都不按实例复制；natives 例外，按实例解包）。
+pub const SHARED_LAYERS: &[&str] = &["versions", "assets", "libraries"];
+
+/// 切换检测探测的三类内容目录（两家启动器一致：只关心玩家数据）。
+pub const PROBED_CONTENT_DIRS: &[&str] = &["mods", "saves", "config"];
+
+/// 全局默认隔离模式（`launcher.json` 的 `instances.mode`）。
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum IsolationMode {
+    /// 每实例运行目录 = `versions//`（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/discover.rs b/crates/core/src/game/java/discover.rs
new file mode 100644
index 0000000..b44a3e5
--- /dev/null
+++ b/crates/core/src/game/java/discover.rs
@@ -0,0 +1,326 @@
+//! 标准安装位置扫描 + 全部发现源的合并去重（`java list` 的「系统发现」半边）。
+//!
+//! 只认 `JAVA_HOME`/`PATH` 会漏掉最常见的一类用户：**用 MSI 装的 Temurin / Microsoft OpenJDK
+//! 不设环境变量**（安装器只登记开始菜单）。HMCL 的 `JavaManager.searchAllJavaInRepository`
+//! 与 PCL 的 `JavaUtils.SearchFolders` 都扫这些位置，本模块照同一思路：
+//!
+//! | 平台 | 扫描位置 |
+//! | --- | --- |
+//! | Windows | `%ProgramFiles%\{Java, Eclipse Adoptium, Microsoft, Zulu, Amazon Corretto, BellSoft, Semeru}\*`（含 `ProgramFiles(x86)` / `ProgramW6432` 变体，WOW64 才看得到 32 位安装）、`%APPDATA%\.minecraft\runtime\*`（**官方启动器装的运行时**，跨产品兼容）、`HKLM\SOFTWARE\JavaSoft\JDK`（老 Oracle 写的，新版发行版通常没有→容错跳过） |
+//! | Linux | `/usr/lib/jvm/*`、`/usr/java/*` |
+//! | macOS | `/Library/Java/JavaVirtualMachines/*.jdk/Contents/Home` |
+//!
+//! 三个纪律：
+//!
+//! 1. **目录不存在是常态**（本机实测 `%APPDATA%\.minecraft\runtime` 与 `JavaSoft\JDK` 都没有），
+//!    一律静默跳过，绝不报错；
+//! 2. **同一路径多来源命中只列一次**，保留优先级高者（`JAVA_HOME` 指向 Program Files 里的
+//!    JDK 时，用户看到的是 `JAVA_HOME` 而不是 `system`）；
+//! 3. **扫描只在需要时才做**：`java list` 全扫；启动路径上先看托管+环境，不满足才扫盘
+//!    （别为了一次启动白跑 N 次 `java -version`）。
+
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+use super::extract::java_binary_name;
+use super::probe::{self, discover_managed_roots, system_candidates, JavaOrigin, JavaRuntime};
+
+/// 全部发现源（托管 → `JAVA_HOME` → `PATH` → 标准安装位置），已按路径去重。
+#[must_use]
+pub fn candidates(managed_root: &Path) -> Vec {
+    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 {
+    let mut roots = Vec::new();
+    if cfg!(windows) {
+        for variable in ["ProgramW6432", "ProgramFiles", "ProgramFiles(x86)"] {
+            let Some(base) = std::env::var_os(variable) else {
+                continue;
+            };
+            let base = PathBuf::from(base);
+            for vendor in WINDOWS_VENDOR_DIRS {
+                roots.extend(child_dirs(&base.join(vendor)));
+            }
+        }
+        if let Some(appdata) = std::env::var_os("APPDATA") {
+            roots.extend(child_dirs(
+                &PathBuf::from(appdata).join(".minecraft").join("runtime"),
+            ));
+        }
+    } else if cfg!(target_os = "macos") {
+        for entry in child_dirs(Path::new("/Library/Java/JavaVirtualMachines")) {
+            // `*.jdk/Contents/Home`（`java_home` 语义）。
+            let home = entry.join("Contents").join("Home");
+            roots.push(if home.is_dir() { home } else { entry });
+        }
+    } else {
+        for base in ["/usr/lib/jvm", "/usr/java"] {
+            roots.extend(child_dirs(Path::new(base)));
+        }
+    }
+    roots.sort();
+    roots.dedup();
+    roots
+}
+
+/// Windows 各发行版的安装父目录（每种下面按子目录名当版本）。
+const WINDOWS_VENDOR_DIRS: &[&str] = &[
+    "Java",
+    "Eclipse Adoptium",
+    "Microsoft",
+    "Zulu",
+    "Amazon Corretto",
+    "BellSoft",
+    "Semeru",
+];
+
+/// 列一个目录的直接子目录（不存在/无权限一律空）。
+fn child_dirs(dir: &Path) -> Vec {
+    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) = Command::new("reg")
+            .args(["query", "HKLM\\SOFTWARE\\JavaSoft\\JDK", "/s", "/reg:"])
+            .arg(view)
+            .output()
+        else {
+            continue;
+        };
+        if !output.status.success() {
+            continue;
+        }
+        homes.extend(parse_java_home(&String::from_utf8_lossy(&output.stdout)));
+    }
+    homes.sort();
+    homes.dedup();
+    homes
+}
+
+/// 从 `reg query /s` 的输出里抠出 `JavaHome` 的值（纯函数，便于用真实输出做单测）。
+#[must_use]
+pub fn parse_java_home(output: &str) -> Vec {
+    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};
+
+    fn runtime(path: &str, origin: JavaOrigin) -> JavaRuntime {
+        JavaRuntime {
+            binary: std::path::PathBuf::from(path),
+            origin,
+            version: None,
+            major: Some(21),
+            bits: 64,
+            vendor: None,
+        }
+    }
+
+    #[test]
+    fn dedupe_keeps_the_higher_priority_source() {
+        let list = vec![
+            runtime(
+                "C:/Program Files/Java/jdk-21/bin/java.exe",
+                JavaOrigin::JavaHome,
+            ),
+            runtime(
+                "C:\\Program Files\\Java\\jdk-21\\bin\\java.exe",
+                JavaOrigin::System,
+            ),
+            runtime(
+                "C:/Program Files/Zulu/zulu-17/bin/java.exe",
+                JavaOrigin::System,
+            ),
+        ];
+        let kept = dedupe(list);
+        assert_eq!(kept.len(), 2);
+        assert_eq!(kept[0].origin, JavaOrigin::JavaHome, "重复路径保留高优先级");
+    }
+
+    #[test]
+    fn path_key_normalises_separators_on_every_platform() {
+        // 平台无关的不变量：同一条 `bin/java` 用 `/` 还是 `\` 拼出来，键必须相同。
+        // （M49：原来这里只在 Windows 上成立，Linux 上 `\` 原样留着 → 断言挂。）
+        let forward = path_key(std::path::Path::new("C:/a/b/java.exe"));
+        let backward = path_key(std::path::Path::new("C:\\a\\b\\java.exe"));
+        assert_eq!(forward, backward);
+        assert!(
+            !forward.contains('\\'),
+            "键里不该残留反斜杠（与平台无关）：{forward}"
+        );
+        assert!(
+            !forward.starts_with(r"\\"),
+            "`\\\\?\\` 前缀不进键：{forward}"
+        );
+    }
+
+    #[test]
+    fn one_install_normalises_to_one_key_whatever_the_spelling() {
+        // 回归钉子：`JAVA_HOME` 与扫盘常对同一个 java 给出不同写法，四种拼法必须同键。
+        let spellings = [
+            "C:/Program Files/Java/jdk-21/bin/java.exe",
+            r"C:\Program Files\Java\jdk-21\bin\java.exe",
+            r"\\?\C:\Program Files\Java\jdk-21\bin\java.exe",
+            r"C:\Program Files\Java\jdk-21/bin/java.exe",
+        ];
+        let key = path_key(std::path::Path::new(spellings[0]));
+        for spelling in spellings {
+            assert_eq!(
+                path_key(std::path::Path::new(spelling)),
+                key,
+                "同一安装的两种写法必须同键：{spelling}"
+            );
+        }
+    }
+
+    #[test]
+    fn path_key_folds_case_only_where_the_filesystem_does() {
+        // 大小写折叠跟平台走，两侧都钉住：NTFS 不区分大小写 → 折；
+        // POSIX 上 `Java` 与 `java` 是两个目录 → 不折（折了会把两份真实安装误并）。
+        let upper = path_key(std::path::Path::new(
+            "C:/Program Files/Java/jdk-21/bin/java.exe",
+        ));
+        let lower = path_key(std::path::Path::new(
+            "c:/program files/java/jdk-21/bin/java.exe",
+        ));
+        if cfg!(windows) {
+            assert_eq!(upper, lower, "Windows：大小写不同的同一路径应同键");
+        } else {
+            assert_ne!(upper, lower, "POSIX：大小写是有效区别，不应同键");
+        }
+    }
+
+    #[test]
+    fn parses_real_reg_query_output() {
+        // 实测形态（`reg query HKLM\SOFTWARE\JavaSoft\JDK /s`）。
+        let output = "\r\nHKEY_LOCAL_MACHINE\\SOFTWARE\\JavaSoft\\JDK\r\n    CurrentVersion    REG_SZ    1.8\r\n\r\nHKEY_LOCAL_MACHINE\\SOFTWARE\\JavaSoft\\JDK\\1.8\r\n    JavaHome    REG_SZ    C:\\Program Files\\Java\\jdk1.8.0_402\r\n";
+        let homes = parse_java_home(output);
+        assert_eq!(
+            homes,
+            vec![std::path::PathBuf::from(
+                r"C:\Program Files\Java\jdk1.8.0_402"
+            )]
+        );
+    }
+
+    #[test]
+    fn missing_registry_key_is_not_an_error() {
+        assert!(parse_java_home("错误: 系统找不到指定的注册表项或值。\r\n").is_empty());
+    }
+
+    #[test]
+    fn standard_roots_never_panic_on_missing_directories() {
+        // 本机大概率缺若干目录；这里只要求「能跑、不 panic」。
+        let roots = standard_roots();
+        assert!(roots.iter().all(|root| !root.as_os_str().is_empty()));
+    }
+}
diff --git a/crates/core/src/game/java/error.rs b/crates/core/src/game/java/error.rs
new file mode 100644
index 0000000..0cdc3d5
--- /dev/null
+++ b/crates/core/src/game/java/error.rs
@@ -0,0 +1,138 @@
+//! Java 管理模块的错误形状：稳定分类 + 人读说明 + 下一步提示。
+//!
+//! 与 `core::game::install::InstallError` 同一个套路（分类进 `--json` 的 `error.code`，
+//! 说明给人看，提示告诉用户下一步做什么），只是没有复用那个类型——安装层的错误语义
+//! 绑在版本本体上，JDK 下载的失败面（API 不可达 / 无对应产物 / 解压后跑不起来）不一样。
+
+use std::fmt;
+
+use crate::download::{DownloadError, DownloadErrorKind};
+
+/// 失败大类（CLI 映射成稳定错误码，脚本可分流）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum JavaErrorKind {
+    /// 网络侧：Adoptium API 不可达，或所有候选镜像源都失败。
+    Network,
+    /// 元数据不认识：API 返回体缺字段、空列表、要的大版本没有 GA 产物。
+    Metadata,
+    /// 摘要校验不符（镜像给了错内容）或 API 没给可用的 sha256。
+    Integrity,
+    /// 本地 IO：建目录 / 解压 / 落盘。
+    Io,
+    /// 当前平台没有对应的 Temurin 产物（架构不认识等）。
+    Unsupported,
+    /// 装完探测不到可用 java（解压成功但跑不起来 / 版本不符）。
+    Probe,
+}
+
+impl JavaErrorKind {
+    /// 稳定字符串 id（进 `--json` 的 `error.code`）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Network => "java_network",
+            Self::Metadata => "java_metadata",
+            Self::Integrity => "java_integrity",
+            Self::Io => "java_io",
+            Self::Unsupported => "java_unsupported",
+            Self::Probe => "java_probe",
+        }
+    }
+}
+
+/// Java 管理期错误。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct JavaError {
+    kind: JavaErrorKind,
+    message: String,
+    hint: Option,
+}
+
+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..654dbc6
--- /dev/null
+++ b/crates/core/src/game/java/install.rs
@@ -0,0 +1,379 @@
+//! 托管 JDK 安装编排：发行版回退链 → 下载引擎 → 解压 → `java -version` 验证。
+//!
+//! ```text
+//! vendor::order(用户优先级, 地区)                  D23 的尝试顺序
+//!   → source::fetch(vendor, major)                查到该家最新 GA（Temurin/Oracle/MS/Zulu）
+//!   → location::JavaInstallRoot::jdk_dir          按落点模式算目录
+//!   → [戳记 sha256 相同 && bin/java 在] 复用      幂等的第一层
+//!   → engine.download(JavaRuntime 请求)           镜像/健康度/退避/续传/边下边算全在引擎
+//!   → extract::extract_archive                    zip / tar.gz + 幂等戳记
+//!   → probe::probe(bin/java -version)             幂等的第二层，也是「装完真能用」的证据
+//! ```
+//!
+//! **回退的粒度是发行版**（D23）：该家没有这个大版本、镜像全 4xx、sha256 取不到、下载校验失败，
+//! 都记一条降级原因然后换下一家；只有全部失败才整体报错，错误里带上每一跳的原因。
+//!
+//! 这一步**不拼任何镜像 URL**（Oracle 的哈希段不可推导，见 `oracle` 模块）：Temurin 的
+//! GitHub 直链交给 `MirrorTable::expand` 展开成院校镜像，Oracle/MS/Zulu 的链接由各自模块
+//! 从目录页/模板/API 拿到最终形态，引擎只负责「把这个 URL 下下来并校验」。
+
+use std::path::{Path, PathBuf};
+
+use super::error::{io_error, JavaError, JavaErrorKind};
+use super::extract;
+use super::location::{JavaInstallRoot, LocationMode};
+use super::probe::{self, JavaOrigin, JavaRuntime};
+use super::release::JdkRelease;
+use super::source::{self, ChainLog};
+use super::target::AdoptiumTarget;
+use super::vendor::{self, JdkVendor};
+use crate::download::{DownloadEngine, DownloadRequest, ResourceKind};
+
+/// 归档缓存目录名（在安装根下；托管目录扫描跳过它）。
+pub use super::location::CACHE_DIR;
+
+/// 一次安装请求。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct InstallRequest {
+    /// 目标大版本。
+    pub major: u32,
+    /// 钉死某一家发行版（`--vendor`）；`None` = 按回退链自己选。
+    pub vendor: Option,
+    /// 用户优先级（`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 target = AdoptiumTarget::host()?;
+    let domestic = engine.region().is_domestic();
+    let priority = request.order(domestic);
+    let mut chain = ChainLog::new();
+    let mut reasons: Vec = Vec::new();
+    // 清掉上次中断留下的 .staging-* 与空壳（只碰我们自己的形状，见 location 模块）。
+    let _ = super::location::cleanup_orphans(&location.root);
+
+    for candidate in &priority {
+        let vendor = *candidate;
+        if !vendor.supports(request.major) {
+            let reason = format!(
+                "不支持 Java {}（{} 只发 {}）",
+                request.major,
+                vendor.id(),
+                majors_text(vendor)
+            );
+            chain.skip(vendor, reason.clone());
+            reasons.push(format!("{}：{reason}", vendor.id()));
+            continue;
+        }
+        let release = match source::fetch(engine, vendor, request.major, target).await {
+            Ok(release) => release,
+            Err(error) => {
+                chain.failed(vendor, error.message().to_string());
+                reasons.push(format!("{}：{}", vendor.id(), error.message()));
+                continue;
+            }
+        };
+        match install_one(engine, location, &release).await {
+            Ok(prepared) => {
+                chain.hit(vendor, format!("命中 {}", release.summary()));
+                return Ok(InstalledJdk {
+                    major: release.major,
+                    vendor,
+                    release,
+                    root: prepared.root,
+                    mode: location.mode,
+                    archive: prepared.archive,
+                    runtime: prepared.runtime,
+                    downloaded: prepared.downloaded,
+                    bytes: prepared.bytes,
+                    files: prepared.files,
+                    extracted: prepared.extracted,
+                    chain,
+                });
+            }
+            Err(error) => {
+                chain.failed(vendor, error.message().to_string());
+                reasons.push(format!("{}：{}", vendor.id(), error.message()));
+            }
+        }
+    }
+
+    Err(JavaError::new(
+        JavaErrorKind::Metadata,
+        format!(
+            "没有装成 Java {}（试过 {}）：{}",
+            request.major,
+            priority.len(),
+            reasons.join("；")
+        ),
+    )
+    .with_hint("`ull java vendors` 看各发行版的可用性；或手动装 JDK 后设 JAVA_HOME"))
+}
+
+/// 某一家的中间结果（把七元组元组换成具名结构，读起来才不费劲）。
+struct Prepared {
+    root: PathBuf,
+    archive: PathBuf,
+    runtime: JavaRuntime,
+    downloaded: Option,
+    bytes: u64,
+    files: usize,
+    extracted: bool,
+}
+
+/// 装某一家的那一份（下载 → 解压 → 探测）。
+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(),
+    })
+}
+
+/// 只做规划不落盘：返回将要安装的版本、目标目录与「是否已经装好」。
+///
+/// # 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("/")
+}
+
+fn note(message: &str) {
+    if cfg!(debug_assertions) {
+        eprintln!("[ull::game::java] {message}");
+    } else {
+        let _ = message;
+    }
+}
diff --git a/crates/core/src/game/java/location.rs b/crates/core/src/game/java/location.rs
new file mode 100644
index 0000000..21fac8b
--- /dev/null
+++ b/crates/core/src/game/java/location.rs
@@ -0,0 +1,335 @@
+//! 托管 JDK 的落点模式（D23 三模式，与 D6 数据目录三模式对齐）。
+//!
+//! | 模式 | 落点 | 说明 |
+//! | --- | --- | --- |
+//! | Portable | `<数据根>/.ULL/data/java-managed/jdk--/` | 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/mapping.rs b/crates/core/src/game/java/mapping.rs
new file mode 100644
index 0000000..930b889
--- /dev/null
+++ b/crates/core/src/game/java/mapping.rs
@@ -0,0 +1,376 @@
+//! MC 版本 ↔ Java 版本映射（平移 HMCL 约束体系）+ 不符检查。
+//!
+//! 依据 `DevDocs/analyse/02-launch-pipeline.md` §5.4（HMCL `GameJavaVersion.getMinimumJavaVersion`）
+//! 与 §3.1 的强制约束清单（`JavaVersionConstraint` 的 `isMandatory` 项）。两条权威叠加：
+//!
+//! | MC 版本 | 最低 | 最高 | 出处 |
+//! | --- | --- | --- | --- |
+//! | ≥ 26.1 | 25 | — | `java-runtime-epsilon` |
+//! | ≥ 1.20.5 | 21 | — | `java-runtime-delta` |
+//! | ≥ 1.18 | 17 | — | `java-runtime-beta` |
+//! | ≥ 1.17 | 16 | — | `java-runtime-alpha` |
+//! | ≥ 1.13 | 8 | — | `jre-legacy` |
+//! | < 1.13 | 8 | **8** | `LAUNCH_WRAPPER`：LaunchWrapper 的 `URLClassLoader` 只能吃 Java 8 |
+//!
+//! **版本 JSON 优先**：装了 1.17 的玩家看的是 Mojang 自己写的 `javaVersion.majorVersion`
+//! （1.17 就是 16），静态表只在清单没写时兜底——这也是 HMCL 的 `GAME_JSON` 强制项语义。
+//!
+//! 上限（`maximum`）只对老版本存在：1.12.2 用 Java 17 会直接
+//! `UnsupportedClassVersionError`-级别的失败（启动器侧是 LaunchWrapper 假设），
+//! 所以「1.12.2 + Java 21」要被判成不符，而不是「19 以上都能跑」。
+
+use std::cmp::Ordering;
+
+use super::super::inherit::resolve;
+use super::super::layout::GameLayout;
+use super::super::manifest::{JavaVersion, VersionJson};
+
+/// 要求来源（`--json` 的 `requirement_source`）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RequirementSource {
+    /// 版本 JSON 的 `javaVersion`（含继承链解析）。
+    Manifest,
+    /// 静态表（HMCL 约束体系的平移）。
+    Table,
+}
+
+impl RequirementSource {
+    /// 稳定字符串 id。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Manifest => "manifest",
+            Self::Table => "table",
+        }
+    }
+}
+
+/// 一个版本对 Java 的要求（闭区间）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct JavaRequirement {
+    /// 最低主版本号（`21`）。
+    pub minimum: u32,
+    /// 最高主版本号（`Some(8)` = 只能用 8 及以下）。
+    pub maximum: Option,
+    /// 来源。
+    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),
+        }
+    }
+}
+
+/// 不符的两种形态（D13：只提示，不阻断）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum JavaMismatch {
+    /// Java 太低。
+    TooOld {
+        /// 需要的最低主版本。
+        required: u32,
+        /// 实际主版本。
+        actual: u32,
+    },
+    /// Java 太高（老版本只能用 8）。
+    TooNew {
+        /// 允许的最高主版本。
+        maximum: u32,
+        /// 实际主版本。
+        actual: u32,
+    },
+}
+
+impl JavaMismatch {
+    /// 稳定字符串 id（`--json` 的 `mismatch.code`）。
+    #[must_use]
+    pub const fn code(self) -> &'static str {
+        match self {
+            Self::TooOld { .. } => "java_too_old",
+            Self::TooNew { .. } => "java_too_new",
+        }
+    }
+
+    /// 人读说明（GUI 弹窗 P1 后直接复用这句）。
+    #[must_use]
+    pub fn message(self) -> String {
+        match self {
+            Self::TooOld { required, actual } => format!(
+                "该版本需要 Java {required} 及以上，当前用的是 Java {actual}（大概率起不来）"
+            ),
+            Self::TooNew { maximum, actual } => format!(
+                "该版本只能用 Java {maximum} 及以下，当前用的是 Java {actual}（老加载器吃不了新 class 文件）"
+            ),
+        }
+    }
+}
+
+/// 判需求与实际是否相符（`None` = 相符）。
+#[must_use]
+pub fn check(actual: u32, required: &JavaRequirement) -> Option {
+    if actual < required.minimum {
+        return Some(JavaMismatch::TooOld {
+            required: required.minimum,
+            actual,
+        });
+    }
+    if let Some(maximum) = required.maximum {
+        if actual > maximum {
+            return Some(JavaMismatch::TooNew { maximum, actual });
+        }
+    }
+    None
+}
+
+/// 静态表：MC 版本 → Java 要求。
+///
+/// 无法解析的版本（周快照 `20w14a`、魔改 id）只给下限 `8`、不设上限——
+/// 宁可漏判一次，也不要把「Java 21 + 1.20 快照」误锁成「必须降到 8」。
+#[must_use]
+pub fn requirement_for(mc_version: &str) -> JavaRequirement {
+    let parts = version_parts(mc_version);
+    if parts.is_empty() {
+        return JavaRequirement::table(8, None);
+    }
+    if at_least(&parts, &[26, 1]) {
+        return JavaRequirement::table(25, None);
+    }
+    if at_least(&parts, &[1, 20, 5]) {
+        return JavaRequirement::table(21, None);
+    }
+    if at_least(&parts, &[1, 18]) {
+        return JavaRequirement::table(17, None);
+    }
+    if at_least(&parts, &[1, 17]) {
+        return JavaRequirement::table(16, None);
+    }
+    if at_least(&parts, &[1, 13]) {
+        return JavaRequirement::table(8, None);
+    }
+    JavaRequirement::table(8, Some(8))
+}
+
+/// 静态表的最低位（`recommended_major("1.20.5") == 21`）。
+#[must_use]
+pub fn recommended_major(mc_version: &str) -> u32 {
+    requirement_for(mc_version).minimum
+}
+
+/// 版本 JSON 的 `javaVersion` → 要求（字段缺失或为 0 时返回 `None`）。
+///
+/// Mojang 这个字段给的是**最低**要求（`majorVersion: 21` 表示 21 起跳），
+/// 不声明上限——所以这里 `maximum` 恒为 `None`；上限由 [`requirement_for`] 补
+/// （见 [`requirement_for_version`] 的合成说明）。
+#[must_use]
+pub fn requirement_from_manifest(java: &JavaVersion) -> Option {
+    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::{check, recommended_major, requirement_for, JavaMismatch, 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 check_reports_both_directions() {
+        let modern = JavaRequirement::table(21, None);
+        assert_eq!(check(21, &modern), None);
+        assert_eq!(check(25, &modern), None);
+        assert_eq!(
+            check(17, &modern),
+            Some(JavaMismatch::TooOld {
+                required: 21,
+                actual: 17
+            })
+        );
+        let legacy = JavaRequirement::table(8, Some(8));
+        assert_eq!(check(8, &legacy), None);
+        assert_eq!(
+            check(21, &legacy),
+            Some(JavaMismatch::TooNew {
+                maximum: 8,
+                actual: 21
+            })
+        );
+        assert_eq!(legacy.describe(), "Java 8");
+        assert_eq!(modern.describe(), "Java 21+");
+        assert_eq!(JavaRequirement::table(8, Some(16)).describe(), "Java 8–16");
+    }
+
+    #[test]
+    fn mismatch_messages_name_both_sides() {
+        let message = JavaMismatch::TooOld {
+            required: 21,
+            actual: 8,
+        }
+        .message();
+        assert!(message.contains("Java 21"));
+        assert!(message.contains("Java 8"));
+        assert_eq!(
+            JavaMismatch::TooNew {
+                maximum: 8,
+                actual: 21
+            }
+            .code(),
+            "java_too_new"
+        );
+    }
+}
diff --git a/crates/core/src/game/java/microsoft.rs b/crates/core/src/game/java/microsoft.rs
new file mode 100644
index 0000000..957c59c
--- /dev/null
+++ b/crates/core/src/game/java/microsoft.rs
@@ -0,0 +1,261 @@
+//! Microsoft OpenJDK：`aka.ms` 模板下载 + 成对 `.sha256sum.txt` 校验。
+//!
+//! 分发形态与 Temurin / Oracle 都不同（research/06 §3.2）：
+//!
+//! ```text
+//! 下载   https://aka.ms/download-jdk/microsoft-jdk-{version}-{os}-{arch}.zip
+//!        → 301 → https://download.visualstudio.microsoft.com/download/pr/{guid}/{hash}/{同名}
+//! 校验   https://aka.ms/download-jdk/<同一文件名>.sha256sum.txt   # "  "
+//! ```
+//!
+//! 三条硬事实（都影响实现）：
+//!
+//! 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/mod.rs b/crates/core/src/game/java/mod.rs
new file mode 100644
index 0000000..45e0110
--- /dev/null
+++ b/crates/core/src/game/java/mod.rs
@@ -0,0 +1,90 @@
+//! Java 运行时管理（D13 v1 → D23 v2）：托管 JDK 的查询 / 下载 / 解压 / 探测，以及 MC↔Java 映射。
+//!
+//! ```text
+//! target    宿主平台 → Adoptium 的 os/arch（Win=zip、Linux/mac=tar.gz）
+//! vendor    四家发行版与用户可调的优先级链（国内 Temurin→Oracle→MS / 国外 Temurin→MS→Oracle）
+//! api       Temurin：api.adoptium.net 查询最新 GA → (github 直链, sha256, size)
+//! oracle    Oracle OpenJDK：镜像目录页解析（hash 段不可推导，禁止拼 URL）+ .sha256
+//! microsoft MS OpenJDK：aka.ms 模板 + 内置四段版本快照 + .sha256sum.txt
+//! zulu      Azul Zulu：两跳 JSON API（列表 → 详情）+ CDN 直链（第四备选）
+//! source    发行版分派 + 回退链记录（命中与降级原因进事件流）
+//! location  落点三模式（Portable / Standard / Custom）+ 孤儿目录清理
+//! release   一次版本查询的统一产物（vendor 原生版本串 + 归档 + sha256 + 大小）
+//! net       版本查询用的极小 GET 文本工具（下载不走这里）
+//! install   编排：回退链 → 下载引擎（镜像/健康度/退避）→ 解压 → 探测验证
+//! extract   zip / tar.gz 解压 + 顶层目录剥离 + 幂等戳记 + zip-slip 防护
+//! probe     java -version 探测、托管目录扫描（两种布局都认）
+//! discover  标准安装位置扫描（Program Files 系 / 官方启动器 runtime / 注册表 / /usr/lib/jvm）+ 去重
+//! select    启动选 Java 的**纯**优先链（满足要求优先，再按来源）
+//! mapping   MC↔Java 静态表（HMCL `GameJavaVersion`）+ 版本 JSON 优先 + 不符检查
+//! ```
+//!
+//! # 三条边界
+//!
+//! 1. **不碰网络细节**：包下载一律交 `core::download` 的引擎，本模块不写重试循环
+//!    （`MirrorTable::expand` 负责 Temurin 的镜像展开；Oracle 的目录解析在 `oracle`）；
+//! 2. **不弹窗**：不符检查只产出数据（[`JavaMismatch`]），提示交给 CLI 的告警行与 GUI；
+//! 3. **不改启动策略**：「用哪个 Java 启动」是启动期的派生结果，不落盘；落盘的是**装到哪**
+//!    （[`JavaInstallRoot`]，由 `java.installRoot` + 数据目录模式决定）。
+//!
+//! # 托管布局（D23 后两种并存）
+//!
+//! ```text
+//! Portable：data/java-managed/
+//! ├── .cache/OpenJDK21U-jdk_x64_windows_hotspot_21.0.13_9.zip   归档缓存（可删）
+//! └── jdk-21-temurin/                                          一个 major+vendor 一份（永不改）
+//!     ├── .ull-jdk.json                                        戳记（幂等判据）
+//!     └── bin/java[.exe]
+//!
+//! Standard / Custom：%APPDATA%\Java\\\     （mac/Linux 见 location 模块）
+//! ```
+
+pub mod api;
+pub mod discover;
+pub mod error;
+pub mod extract;
+pub mod install;
+pub mod location;
+pub mod mapping;
+pub mod microsoft;
+pub mod net;
+pub mod oracle;
+pub mod probe;
+pub mod release;
+pub mod select;
+pub mod source;
+pub mod target;
+pub mod vendor;
+pub mod zulu;
+
+pub use self::api::{
+    latest_url, parse_latest, JdkArchive, JdkRelease, ADOPTIUM_API_BASE, JDK_VENDOR,
+};
+pub use self::discover::{
+    candidates, candidates_in_roots, scan_java_binaries, standard_candidates, standard_roots,
+};
+pub use self::error::{JavaError, JavaErrorKind};
+pub use self::extract::{
+    extract_archive, is_ready, java_binary, java_binary_name, read_stamp, ExtractReport, JdkStamp,
+    STAMP_FILE,
+};
+pub use self::install::{
+    archive_path, archive_request, chain_order, install, managed_root_dir, plan, InstallRequest,
+    InstalledJdk,
+};
+pub use self::location::{
+    cleanup_orphans, sanitize_version, scan_roots, CleanupReport, JavaInstallRoot, LocationMode,
+};
+pub use self::mapping::{
+    check, recommended_major, requirement_for, requirement_for_version, JavaMismatch,
+    JavaRequirement, RequirementSource,
+};
+pub use self::probe::{
+    discover_managed, discover_managed_roots, managed_dir_name, parse_managed_dir, probe,
+    resolve_on_path, system_candidates, JavaOrigin, JavaRuntime, DEFAULT_MAJOR,
+};
+pub use self::release::parse_sha256_text;
+pub use self::select::{pick, resolve, JavaResolution};
+pub use self::source::{ChainLog, VendorAttempt};
+pub use self::target::AdoptiumTarget;
+pub use self::vendor::{order as vendor_order, JdkVendor, VENDOR_IDS};
diff --git a/crates/core/src/game/java/net.rs b/crates/core/src/game/java/net.rs
new file mode 100644
index 0000000..991d994
--- /dev/null
+++ b/crates/core/src/game/java/net.rs
@@ -0,0 +1,60 @@
+//! 版本查询用的极小 HTTP 取文本工具（四家发行版的「一锤子 GET」共用）。
+//!
+//! 只有一件事：GET → 状态分类 → 整段文本。**下载不走这里**（那归 `core::download` 引擎），
+//! 所以没有重试、没有镜像展开、没有进度事件——查清单失败就直接把错误抛给发行版回退链，
+//! 让它换下一家（这是 D23「vendor 级失败自动降下一 vendor」的最短路径）。
+
+use super::error::{JavaError, JavaErrorKind};
+
+/// 取一段文本（`what` 是给用户看的名词，例如「华为云 openjdk 目录」）。
+///
+/// # Errors
+///
+/// 连不上 / 超时 → [`JavaErrorKind::Network`]；404 或 410 → [`JavaErrorKind::Metadata`]
+/// （「这个东西上游没有」比「网络坏了」更准确，回退链据此换 vendor 而不是重试同一条）。
+pub async fn get_text(
+    client: &reqwest::Client,
+    url: &str,
+    what: &str,
+) -> Result {
+    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..5dee6eb
--- /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 std::process::Command;
+
+use super::extract::{java_binary_name, read_stamp};
+use super::vendor::JdkVendor;
+
+/// 缺省 Java 主版本（探测不到任何东西时的保守值，D13：JDK 17 基准）。
+pub const DEFAULT_MAJOR: u32 = 17;
+
+/// 托管目录名前缀。
+pub const MANAGED_PREFIX: &str = "jdk-";
+
+/// 一个 Java 运行时的来源。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub enum JavaOrigin {
+    /// 实例覆盖（`--java` 参数或实例档案的 `javaPath`）。
+    Instance,
+    /// 托管目录（`ull java install` 装的）。
+    Managed,
+    /// `JAVA_HOME`。
+    JavaHome,
+    /// `PATH` 上的 `java`。
+    Path,
+    /// 标准安装位置扫出来的（MSI 装的 Temurin / 官方启动器的 `runtime/` / 注册表等）。
+    System,
+}
+
+impl JavaOrigin {
+    /// 稳定字符串 id（`--json` 的 `source` 字段）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Instance => "instance",
+            Self::Managed => "managed",
+            Self::JavaHome => "JAVA_HOME",
+            Self::Path => "PATH",
+            Self::System => "system",
+        }
+    }
+
+    /// 展示类别（`--json` 的 `source_category`）：GUI 用它分组，不必区分 `JAVA_HOME`/`PATH`。
+    #[must_use]
+    pub const fn category(self) -> &'static str {
+        match self {
+            Self::Instance => "instance",
+            Self::Managed => "managed",
+            Self::JavaHome | Self::Path => "env",
+            Self::System => "system",
+        }
+    }
+
+    /// 同档内的优先序（小者优先）。
+    ///
+    /// 「环境变量」先于「扫盘」：用户显式设过的 `JAVA_HOME`/`PATH` 是意图表达，
+    /// 盘上扫出来的只是候选（HMCL/PCL 也是这个顺序）。
+    #[must_use]
+    pub const fn rank(self) -> u8 {
+        match self {
+            Self::Instance => 0,
+            Self::Managed => 1,
+            Self::JavaHome => 2,
+            Self::Path => 3,
+            Self::System => 4,
+        }
+    }
+}
+
+/// 一个探测到的 Java 运行时。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct JavaRuntime {
+    /// 可执行文件。
+    pub binary: PathBuf,
+    /// 来源。
+    pub origin: JavaOrigin,
+    /// `java -version` 的首行（含 `version` 字样）。
+    pub version: Option,
+    /// 主版本号（`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) = Command::new(binary).arg("-version").output() else {
+        return runtime;
+    };
+    let mut text = String::from_utf8_lossy(&output.stderr).into_owned();
+    text.push_str(&String::from_utf8_lossy(&output.stdout));
+    if let Some((line, major)) = parse_version_output(&text) {
+        runtime.major = Some(major);
+        runtime.version = Some(line);
+        runtime.bits = bits_of(&text);
+    }
+    runtime
+}
+
+/// 扫描一个安装根里的托管 JDK，逐个探测。
+///
+/// **两种布局都要认**（D23 之后同时存在）：
+///
+/// ```text
+/// /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/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..496a0fd
--- /dev/null
+++ b/crates/core/src/game/java/select.rs
@@ -0,0 +1,160 @@
+//! 「启动选哪个 Java」的**纯**优先链（D13）。
+//!
+//! 优先级：实例覆盖（`--java` / 档案 `javaPath`）> 托管目录里**满足要求**的 JDK >
+//! `JAVA_HOME` > `PATH`。实例覆盖由调用方单独判（用户明确指定了就不参与打分），
+//! 这里只处理「一堆已探测的候选 + 一个要求」的挑选。
+//!
+//! 挑选规则（比「机械按来源排序」更贴近用户预期）：
+//!
+//! 1. **满足要求的候选优先**——1.12.2 只能用 Java 8，托管的 21 再新也不能选；
+//! 2. 同档内按来源：托管 > `JAVA_HOME` > `PATH`（D13：托管目录是启动器的地盘，
+//!    用户 PATH 上的 java 可能是另一个 JDK 的残留）；
+//! 3. 全都不满足时仍给一个（按来源优先取最好那个），并报不符——**提示而不是拒绝**。
+//!
+//! 抽成纯函数是为了可测：测试注入「托管 21 + PATH 8」这类组合，不必真装 JDK。
+
+use super::mapping::{check, JavaMismatch, JavaRequirement};
+use super::probe::{JavaRuntime, DEFAULT_MAJOR};
+
+/// 一次启动的 Java 选择结果。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct JavaResolution {
+    /// 选中的运行时（一个候选都没有时 `None`）。
+    pub runtime: Option,
+    /// 目标版本对 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()
+    }
+}
+
+/// 从候选里挑一个：满足要求的优先，同档内按来源优先序。
+#[must_use]
+pub fn pick<'a>(
+    candidates: &'a [JavaRuntime],
+    required: &JavaRequirement,
+) -> Option<&'a JavaRuntime> {
+    candidates.iter().min_by_key(|runtime| {
+        let ok = runtime
+            .major
+            .is_some_and(|major| required.satisfied_by(major));
+        // 先排「不满足」（`ok=false` 的 key 大），再排来源优先序。
+        (!ok, runtime.origin.rank())
+    })
+}
+
+/// 挑 + 判不符。
+#[must_use]
+pub fn resolve(candidates: &[JavaRuntime], required: &JavaRequirement) -> JavaResolution {
+    let runtime = pick(candidates, required).cloned();
+    let mismatch = runtime
+        .as_ref()
+        .and_then(|runtime| runtime.major)
+        .and_then(|major| check(major, required));
+    JavaResolution {
+        runtime,
+        required: required.clone(),
+        mismatch,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::resolve;
+    use crate::game::java::mapping::{JavaRequirement, RequirementSource};
+    use crate::game::java::probe::{JavaOrigin, JavaRuntime, DEFAULT_MAJOR};
+
+    fn runtime(major: u32, origin: JavaOrigin) -> JavaRuntime {
+        JavaRuntime {
+            binary: std::path::PathBuf::from(format!("java{major}")),
+            origin,
+            version: Some(format!("openjdk version \"{major}.0.1\"")),
+            major: Some(major),
+            bits: 64,
+            vendor: None,
+        }
+    }
+
+    fn at_least(minimum: u32) -> JavaRequirement {
+        JavaRequirement::new(minimum, None, RequirementSource::Table)
+    }
+
+    #[test]
+    fn satisfying_managed_runtime_beats_mismatching_system_java() {
+        let candidates = [
+            runtime(8, JavaOrigin::Path),
+            runtime(21, JavaOrigin::Managed),
+        ];
+        let picked = resolve(&candidates, &at_least(17));
+        assert_eq!(picked.major(), 21);
+        assert!(picked.is_satisfied());
+    }
+
+    #[test]
+    fn satisfying_system_java_beats_mismatching_managed() {
+        // 1.12.2 只能 Java 8：托管的 21 不满足，PATH 上的 8 满足 → 选 8。
+        let required = JavaRequirement::new(8, Some(8), RequirementSource::Table);
+        let candidates = [
+            runtime(21, JavaOrigin::Managed),
+            runtime(8, JavaOrigin::Path),
+        ];
+        let picked = resolve(&candidates, &required);
+        assert_eq!(picked.major(), 8);
+        assert!(picked.is_satisfied());
+    }
+
+    #[test]
+    fn managed_wins_when_both_satisfy() {
+        let candidates = [
+            runtime(21, JavaOrigin::Path),
+            runtime(17, JavaOrigin::JavaHome),
+            runtime(17, JavaOrigin::Managed),
+        ];
+        assert_eq!(resolve(&candidates, &at_least(17)).major(), 17);
+    }
+
+    #[test]
+    fn java_home_beats_path_when_both_satisfy() {
+        let candidates = [
+            runtime(21, JavaOrigin::Path),
+            runtime(21, JavaOrigin::JavaHome),
+        ];
+        let picked = resolve(&candidates, &at_least(21));
+        assert_eq!(
+            picked.runtime.map(|runtime| runtime.origin),
+            Some(JavaOrigin::JavaHome)
+        );
+    }
+
+    #[test]
+    fn no_candidate_keeps_the_default_and_reports_no_mismatch() {
+        let picked = resolve(&[], &at_least(21));
+        assert_eq!(picked.major(), DEFAULT_MAJOR);
+        assert!(picked.runtime.is_none());
+        assert!(picked.is_satisfied());
+    }
+
+    #[test]
+    fn mismatch_is_reported_when_nothing_fits() {
+        let candidates = [runtime(8, JavaOrigin::Path)];
+        let picked = resolve(&candidates, &at_least(21));
+        assert_eq!(picked.major(), 8);
+        let mismatch = picked.mismatch.expect("应报不符");
+        assert_eq!(mismatch.code(), "java_too_old");
+    }
+}
diff --git a/crates/core/src/game/java/source.rs b/crates/core/src/game/java/source.rs
new file mode 100644
index 0000000..112691f
--- /dev/null
+++ b/crates/core/src/game/java/source.rs
@@ -0,0 +1,199 @@
+//! 版本查询的发行版分派 + 回退链记录（D23）。
+//!
+//! 两件事：
+//!
+//! 1. [`fetch`]：把一次「某发行版某大版本的最新 GA」查询分派给对应实现——
+//!    Temurin 走 `api.adoptium.net`（v1 既有），Oracle / MS / Zulu 各走自己的源表；
+//! 2. [`ChainLog`]：按用户优先级依次尝试时，**每一跳的结果与降级原因**都记下来。
+//!    这份记录直接进 `--json` 与事件流，是「为什么最后装的是 MS 而不是 Temurin」的唯一解释。
+//!
+//! 回退的粒度是**发行版级**（D23 原话）：版本不存在、镜像全 4xx、校验失败都算这一家失败，
+//! 换下一家；同一家内部的镜像换源（TUNA→官方、华为云→南大）仍然归 `core::download` 引擎管。
+
+use super::api;
+use super::error::JavaError;
+use super::microsoft;
+use super::oracle;
+use super::release::JdkRelease;
+use super::target::AdoptiumTarget;
+use super::vendor::JdkVendor;
+use super::zulu;
+use crate::download::DownloadEngine;
+
+/// 查一次「某发行版某大版本的最新 GA」。
+///
+/// # Errors
+///
+/// 平台无产物、清单不可达、该家没有这个大版本、校验缺失时返回错误——调用方据此降级。
+pub async fn fetch(
+    engine: &DownloadEngine,
+    vendor: JdkVendor,
+    major: u32,
+    target: AdoptiumTarget,
+) -> Result {
+    let client = engine.client();
+    let table = engine.mirrors();
+    match vendor {
+        JdkVendor::Temurin => api::fetch_latest(client, major, target).await,
+        JdkVendor::Oracle => oracle::fetch_latest(client, table, major, target).await,
+        JdkVendor::Microsoft => {
+            let table = table.microsoft_openjdk().ok_or_else(|| {
+                JavaError::new(
+                    super::error::JavaErrorKind::Metadata,
+                    "镜像清单里没有 microsoft_openjdk 表",
+                )
+                .with_hint("升级 mirrors.json 到 v3，或改用 --vendor temurin")
+            })?;
+            microsoft::fetch_latest(client, table, major, target).await
+        }
+        JdkVendor::Zulu => {
+            let table = table.zulu().ok_or_else(|| {
+                JavaError::new(
+                    super::error::JavaErrorKind::Metadata,
+                    "镜像清单里没有 zulu 表",
+                )
+                .with_hint("升级 mirrors.json 到 v3，或改用 --vendor temurin")
+            })?;
+            zulu::fetch_latest(client, table, major, target).await
+        }
+    }
+}
+
+/// 一跳的结果。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct VendorAttempt {
+    /// 尝试的发行版。
+    pub vendor: JdkVendor,
+    /// 是否命中（成功拿到可下载的归档）。
+    pub ok: bool,
+    /// 命中/降级的一句话原因（`"命中"` / `"没有 8 的 GA（只发 11/17/21/25）"`）。
+    pub detail: String,
+}
+
+impl VendorAttempt {
+    /// `--json` 形状。
+    #[must_use]
+    pub fn to_json(&self) -> serde_json::Value {
+        serde_json::json!({
+            "vendor": self.vendor.id(),
+            "ok": self.ok,
+            "detail": self.detail,
+        })
+    }
+}
+
+/// 一条回退链的执行记录。
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct ChainLog {
+    attempts: Vec,
+}
+
+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/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/vendor.rs b/crates/core/src/game/java/vendor.rs
new file mode 100644
index 0000000..76dd270
--- /dev/null
+++ b/crates/core/src/game/java/vendor.rs
@@ -0,0 +1,219 @@
+//! JDK 发行版（vendor）抽象与用户可调优先级链（D23）。
+//!
+//! 四家发行版的**默认顺序按地区分区**（用户定案 + research/06 §5.1 实测修正）：
+//!
+//! ```text
+//! 国内：Temurin(TUNA) → Oracle OpenJDK(华为云→南大) → MS OpenJDK(境外 CDN) → Zulu
+//! 国外：Temurin        → MS OpenJDK                 → Oracle OpenJDK       → Zulu
+//! ```
+//!
+//! 国内把 Oracle 提到 MS 之前的依据是实测差 28×（Oracle 国内 11.5 MB/s vs MS 410 KB/s）；
+//! 用户原话是「Temurin → MS → Oracle」，但同一句话里给了「优先级可调」，所以这只是默认值，
+//! 设置键 `java.vendorPriority` 可以整体覆盖（D23 定稿）。
+//!
+//! 这里的表只描述**能力与顺序**，不碰网络：怎么查、怎么下在 `oracle` / `microsoft` /
+//! `zulu` / `api`（Temurin）四个模块里。
+
+/// 设置键 `java.vendorPriority` 的允许值（顺序即默认序的覆盖来源）。
+pub const VENDOR_IDS: &[&str] = &["temurin", "oracle", "microsoft", "zulu"];
+
+/// 一家 JDK 发行版。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub enum JdkVendor {
+    /// Eclipse Temurin（Adoptium），v1 唯一实现。
+    Temurin,
+    /// Oracle OpenJDK（`download.java.net` GA，只发首个 GA + ≤2 个 update）。
+    Oracle,
+    /// Microsoft OpenJDK（`aka.ms` 模板 + VS CDN，无 8）。
+    Microsoft,
+    /// Azul Zulu（第四备选，API 元数据 + CDN 直链）。
+    Zulu,
+}
+
+impl JdkVendor {
+    /// 全部发行版（枚举顺序，不是优先级顺序）。
+    pub const ALL: [Self; 4] = [Self::Temurin, Self::Oracle, Self::Microsoft, Self::Zulu];
+
+    /// 稳定 id（目录名段、`--vendor` 取值、设置值、JSON 字段）。
+    #[must_use]
+    pub const fn id(self) -> &'static str {
+        match self {
+            Self::Temurin => "temurin",
+            Self::Oracle => "oracle",
+            Self::Microsoft => "microsoft",
+            Self::Zulu => "zulu",
+        }
+    }
+
+    /// 展示名（人读输出 + `java vendors`）。
+    #[must_use]
+    pub const fn display(self) -> &'static str {
+        match self {
+            Self::Temurin => "Eclipse Temurin",
+            Self::Oracle => "Oracle OpenJDK",
+            Self::Microsoft => "Microsoft OpenJDK",
+            Self::Zulu => "Azul Zulu",
+        }
+    }
+
+    /// 解析 `--vendor` / 设置值（容忍常见别名，大小写不敏感）。
+    #[must_use]
+    pub fn parse(text: &str) -> Option {
+        match text.trim().to_ascii_lowercase().as_str() {
+            "temurin" | "adoptium" | "eclipse" | "eclipse-temurin" => Some(Self::Temurin),
+            "oracle" | "oracle_openjdk" | "openjdk" | "java.net" => Some(Self::Oracle),
+            "microsoft" | "ms" | "msopenjdk" | "ms_openjdk" | "microsoft-openjdk" => {
+                Some(Self::Microsoft)
+            }
+            "zulu" | "azul" => Some(Self::Zulu),
+            _ => None,
+        }
+    }
+
+    /// 该发行版能不能装这个大版本。
+    ///
+    /// Temurin / Zulu 覆盖 8 起的全部 GA；Oracle 的 archive 从 9 起（8 由 Temurin 负责）；
+    /// MS 只发 11/17/21/25（**已停发 8**，官方页面直接让去下 Temurin 8）。
+    #[must_use]
+    pub const fn supports(self, major: u32) -> bool {
+        match self {
+            Self::Temurin | Self::Zulu => major >= 8,
+            Self::Oracle => major >= 9,
+            Self::Microsoft => matches!(major, 11 | 17 | 21 | 25),
+        }
+    }
+
+    /// 已知在发的 GA 大版本（`java vendors` 展示与设置页提示用；不是硬上限）。
+    #[must_use]
+    pub const fn hint_majors(self) -> &'static [u32] {
+        match self {
+            Self::Temurin => &[8, 11, 17, 21, 25],
+            Self::Oracle => &[17, 21, 25],
+            Self::Microsoft => &[11, 17, 21, 25],
+            Self::Zulu => &[8, 11, 17, 21, 25],
+        }
+    }
+
+    /// 国内默认序（用户定案 + 实测修正）。
+    #[must_use]
+    pub const fn domestic_default() -> [Self; 4] {
+        [Self::Temurin, Self::Oracle, Self::Microsoft, Self::Zulu]
+    }
+
+    /// 国外默认序（用户原话顺序）。
+    #[must_use]
+    pub const fn global_default() -> [Self; 4] {
+        [Self::Temurin, Self::Microsoft, Self::Oracle, Self::Zulu]
+    }
+
+    /// 按地区取默认序。
+    #[must_use]
+    pub const fn default_order(domestic: bool) -> [Self; 4] {
+        if domestic {
+            Self::domestic_default()
+        } else {
+            Self::global_default()
+        }
+    }
+}
+
+/// 用户优先级（设置值）→ 实际尝试顺序。
+///
+/// 语义刻意做成「**补集追加**」而不是「必须写全」：用户写了 `["oracle"]` 就只把 oracle 提上来，
+/// 其余按地区默认序跟在后面。理由——写全四家是负担，漏写更不该等于「其余不试」。
+#[must_use]
+pub fn order(priority: &[JdkVendor], domestic: bool) -> Vec {
+    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/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..230c4b9
--- /dev/null
+++ b/crates/core/src/game/library.rs
@@ -0,0 +1,213 @@
+//! 依赖库模型：Maven 坐标、natives 选择、库文件相对路径。
+//!
+//! 依据：`DevDocs/analyse/03-version-download.md` §6.4（libraries 含 natives 规则）、
+//! §6.8（目录布局速查）。
+//!
+//! 这里只做"数据 → 路径/候选"的纯计算，**不碰网络与文件系统**：
+//! 真正的下载归 `core::download`，放置归 [`super::layout`]。
+
+use std::collections::BTreeMap;
+use std::path::PathBuf;
+
+use serde::{Deserialize, Serialize};
+
+use super::arguments::{rules_allow, Environment, Rule};
+use super::error::GameError;
+use super::manifest::DownloadInfo;
+
+/// 一条依赖库。
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Library {
+    /// Maven 坐标 `group:artifact:version[:classifier][@ext]`。
+    #[serde(default)]
+    pub name: String,
+    /// 下载信息；老 JSON/魔改 JSON 可能没有。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub downloads: Option,
+    /// 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`）。
+    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 {
+            ""
+        };
+        Some(raw.replace("${arch}", arch))
+    }
+
+    /// natives 构件下载信息（按分类器查 `downloads.classifiers`）。
+    pub fn native_artifact(&self, classifier: &str) -> Option<&DownloadInfo> {
+        self.downloads.as_ref()?.classifiers.get(classifier)
+    }
+
+    /// 主构件相对 `libraries/` 的路径。
+    ///
+    /// 优先用 JSON 里给出的 `artifact.path`（Mojang 官方的权威值），否则按坐标推导。
+    pub fn relative_path(&self) -> Result {
+        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/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..e05e441
--- /dev/null
+++ b/crates/core/src/game/mod.rs
@@ -0,0 +1,64 @@
+//! 版本与实例仓库：不可变快照 + 单写者草稿、版本 JSON 继承解析、实例目录布局。
+//!
+//! 设计定稿：`DevDocs/PlanDoc/04-data-and-config.md` §4（实例模型）、
+//! `DevDocs/PlanDoc/01-tech-stack-and-architecture.md` §3（Snapshot/Draft 纪律），
+//! 源证据 `DevDocs/analyse/01-architecture-overview.md` §3.3。
+//!
+//! 与其它模块的契约：快照（Snapshot）类型与继承解析结果要与 launch 对齐
+//! （`DevDocs/SubAgentsTalk/README.md` 的对齐点；详细约定见 `SubAgentsTalk/game-接口约定.md`）。
+//!
+//! 公共面（M14）：
+//! - 版本清单：[`VersionList`] / [`RemoteVersion`] / [`ReleaseType`] / [`VersionCategory`]，
+//!   外加内嵌补充清单 [`unlisted`]；
+//! - 版本 JSON 与继承：[`VersionJson`]、[`resolve`]、[`merge`]、[`apply_patches`]；
+//! - 参数与库：[`Arguments`] / [`Environment`] / [`Rule`]、[`Library`] / [`MavenCoordinate`]；
+//! - 能力位：[`capability`]（版本 JSON 库表 → `has_vulkan_backend`）；
+//! - 实例：目录布局 [`GameLayout`]、档案 [`ProfileList`] / [`InstanceProfile`] / [`ProfileId`]；
+//! - 发布：快照仓库 [`Store`] / [`Snapshot`] / [`Draft`]。
+//!
+//! 安装层（M27，[`install`]）：版本链 → 下载计划 → 分区落盘 → 实例登记。
+//! 它把上面这些"模型"串成可执行的流程，但**自己不碰 UI、不拼镜像 URL**：
+//! 下载全部交给 `core::download` 的引擎（镜像/健康度/续传/校验都在那边）。
+//!
+//! Java 管理（M33，[`java`]）：托管 JDK 的查询/下载/解压/探测（`.ULL/data/java-managed/`）
+//! 与 MC↔Java 映射表。同样只借 `core::download` 的引擎做下载，自己不拼镜像 URL。
+//!
+//! 模块分工按"数据形状 / 纯计算 / 状态"切开，任何模块都不碰网络与 UI：
+//! 下载归 `core::download`、进程归 `core::launch`、配置落盘归 `core::setting`。
+
+pub mod arguments;
+pub mod capability;
+pub mod error;
+pub mod inherit;
+pub mod install;
+pub mod isolation;
+pub mod java;
+pub mod layout;
+pub mod library;
+pub mod manifest;
+pub mod profiles;
+pub mod snapshot;
+pub mod unlisted;
+pub mod version;
+
+pub use arguments::{rules_allow, Arguments, Environment, ExpandedArguments, Rule, RuleAction};
+pub use capability::{
+    is_vulkan_library, library_names_have_vulkan, VersionCapabilities, VULKAN_LIBRARY_ARTIFACT,
+    VULKAN_LIBRARY_GROUP,
+};
+pub use error::GameError;
+pub use inherit::{apply_patches, merge, resolve, sorted_patches, VersionSource};
+pub use isolation::{
+    derive_game_dir, observe_mode, probe_both_sides, probe_side, Derivation, IsolationMode,
+    IsolationSource, ModeChange, ModeChangeProbe, ModeChangeWarning, SideContent,
+    PROBED_CONTENT_DIRS, SHARED_LAYERS,
+};
+pub use layout::GameLayout;
+pub use library::{Library, MavenCoordinate};
+pub use manifest::{AssetIndexRef, DownloadInfo, Downloads, JavaVersion, Logging, VersionJson};
+pub use profiles::{InstanceProfile, ProfileId, ProfileList, PROFILE_SCHEMA_VERSION};
+pub use snapshot::{Draft, Snapshot, Store};
+pub use version::{
+    LatestVersions, ReleaseType, RemoteVersion, VersionCategory, VersionList,
+    VERSION_MANIFEST_V2_URL,
+};
diff --git a/crates/core/src/game/profiles.rs b/crates/core/src/game/profiles.rs
new file mode 100644
index 0000000..db222db
--- /dev/null
+++ b/crates/core/src/game/profiles.rs
@@ -0,0 +1,244 @@
+//! 实例清单（`profiles.json`）模型：稳定 UUID + 实例档案。
+//!
+//! 依据：`DevDocs/PlanDoc/04-data-and-config.md` §4（实例模型预告）、§2（`.ULL/config/profiles.json`）。
+//!
+//! 两条硬约束（来自 analyse/01 §7.6 的教训）：
+//! 1. **实例 id 用稳定 UUID，不用路径**——路径会变（用户挪目录、迁移数据目录），
+//!    而 id 一旦写进档案就不能变；
+//! 2. 档案只存**绑定关系**（版本 id、独立目录、Java 覆盖），不存派生的绝对路径结论；
+//!    全局/实例/临时三层设置的合并归 `core::setting`，这里不重复。
+//!
+//! 落盘归 `core::setting` 的原子写 + schema 迁移（M12），本模块只提供模型与不变量。
+
+use std::collections::BTreeMap;
+use std::fmt;
+use std::path::PathBuf;
+use std::str::FromStr;
+use std::sync::atomic::{AtomicU64, Ordering};
+
+use serde::{Deserialize, Serialize};
+
+/// `profiles.json` 的 schema 版本（迁移链由 `core::setting` 驱动）。
+pub const PROFILE_SCHEMA_VERSION: u32 = 1;
+
+/// 实例 id：UUID 形状的稳定标识。
+#[derive(Debug, Clone, Default, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
+#[serde(transparent)]
+pub struct ProfileId(String);
+
+impl ProfileId {
+    /// 生成一个新 id（v4 形状）。
+    ///
+    /// **不是密码学随机**：由纳秒时间戳 + 进程 id + 进程内计数器经 SplitMix64 混合而来，
+    /// 足以保证单机唯一；删除实例后不复用即可。真要密码学随机，阶段 B 引 `uuid` crate。
+    pub fn generate() -> Self {
+        static COUNTER: AtomicU64 = AtomicU64::new(0);
+
+        let nanos = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .map_or(0, |d| d.as_nanos() as u64);
+        let seq = COUNTER.fetch_add(1, Ordering::Relaxed);
+        let mut seed = nanos ^ u64::from(std::process::id()).rotate_left(17) ^ seq.rotate_left(41);
+
+        let mut bytes = [0u8; 16];
+        for chunk in bytes.chunks_mut(8) {
+            seed = split_mix64(seed);
+            let source = seed.to_le_bytes();
+            chunk.copy_from_slice(&source[..chunk.len()]);
+        }
+        // RFC 4122 v4 形状：版本位 + 变体位。
+        bytes[6] = (bytes[6] & 0x0F) | 0x40;
+        bytes[8] = (bytes[8] & 0x3F) | 0x80;
+
+        let mut hex = String::with_capacity(36);
+        for (index, byte) in bytes.iter().enumerate() {
+            if matches!(index, 4 | 6 | 8 | 10) {
+                hex.push('-');
+            }
+            hex.push_str(&format!("{byte:02x}"));
+        }
+        Self(hex)
+    }
+
+    /// 从字符串构造（不校验，用于读回历史档案；校验用 [`ProfileId::is_uuid_shaped`]）。
+    pub fn new(raw: impl Into) -> 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/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_scan.rs b/crates/core/src/launch/crash_scan.rs
new file mode 100644
index 0000000..66da94b
--- /dev/null
+++ b/crates/core/src/launch/crash_scan.rs
@@ -0,0 +1,152 @@
+//! 崩溃现场扫描：`crash-reports/*.txt`、`hs_err_pid*.log`、`logs/latest.log`。
+//!
+//! 按 `DevDocs/SubAgentsTalk/launch-接口约定.md` §3：`crash_found` 事件的 `path` 是
+//! **权威字段**（M15 按路径自己读盘，`excerpt` 仅供人读）。所以这里只做“找到并给出路径”，
+//! 不做解析——解析（hs_err 的失败帧/内存段）是 M15 的 `hs_err` 解析器。
+//!
+//! 只收**本次会话之后**动过的文件（`since` = 进程启动时刻），避免把上一局的崩溃报告
+//! 算到这一局头上（这是 HMCL 会犯的错）。
+
+use std::path::{Path, PathBuf};
+use std::time::{Duration, SystemTime};
+
+/// 崩溃现场文件来源。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum CrashSource {
+    /// `crash-reports/crash-*.txt`（游戏自己写的权威 Description + 栈）。
+    CrashReport,
+    /// JVM 致命错误 `hs_err_pid*.log`（HMCL 完全不解析的空白区）。
+    HsErr,
+    /// `logs/latest.log`（内存缓冲不够长时的兜底全文）。
+    LatestLog,
+}
+
+impl CrashSource {
+    /// 事件流里的字符串。
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::CrashReport => "crash_report",
+            Self::HsErr => "hs_err",
+            Self::LatestLog => "latest_log",
+        }
+    }
+}
+
+/// 一个现场文件。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CrashArtifact {
+    /// 来源类型。
+    pub source: CrashSource,
+    /// 绝对/相对路径（交给 M15）。
+    pub path: PathBuf,
+    /// 供人读的开头片段（`latest.log` 不给，太大）。见 `DevDocs/SubAgentsTalk/launch-接口约定.md` §4（写入前脱敏）。
+    pub excerpt: Option,
+}
+
+/// 默认摘录上限（字符）。
+pub const MAX_EXCERPT_CHARS: usize = 2000;
+
+/// 扫描一次运行目录，返回按修改时间倒序的现场文件（最多 `limit` 个）。
+///
+/// `since` 之前的文件视为上一局遗留，忽略；给 `since` 留 1 秒容差以吸收文件系统时间精度。
+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 let Some(artifact) = latest_log(run_dir, since) {
+        let modified = artifact_time(&artifact.path).unwrap_or(since);
+        found.push((modified, artifact));
+    }
+
+    found.sort_by_key(|item| std::cmp::Reverse(item.0));
+    found
+        .into_iter()
+        .take(limit)
+        .map(|(_, artifact)| artifact)
+        .collect()
+}
+
+fn collect_matching(
+    dir: &Path,
+    source: CrashSource,
+    since: SystemTime,
+    out: &mut Vec<(SystemTime, CrashArtifact)>,
+) {
+    let Ok(entries) = std::fs::read_dir(dir) else {
+        return;
+    };
+    for entry in entries.flatten() {
+        let path = entry.path();
+        if !is_candidate(&path, source) {
+            continue;
+        }
+        let Some(modified) = artifact_time(&path) else {
+            continue;
+        };
+        if modified < since {
+            continue;
+        }
+        out.push((
+            modified,
+            CrashArtifact {
+                source,
+                path: path.clone(),
+                excerpt: read_excerpt(&path, MAX_EXCERPT_CHARS),
+            },
+        ));
+    }
+}
+
+fn is_candidate(path: &Path, source: CrashSource) -> bool {
+    if !path.is_file() {
+        return false;
+    }
+    let name = path
+        .file_name()
+        .map(|name| name.to_string_lossy().to_ascii_lowercase())
+        .unwrap_or_default();
+    match source {
+        CrashSource::CrashReport => name.ends_with(".txt"),
+        CrashSource::HsErr => name.starts_with("hs_err_pid") && name.ends_with(".log"),
+        CrashSource::LatestLog => false,
+    }
+}
+
+fn latest_log(run_dir: &Path, since: SystemTime) -> Option {
+    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)
+}
diff --git a/crates/core/src/launch/defaults.rs b/crates/core/src/launch/defaults.rs
new file mode 100644
index 0000000..ffcc157
--- /dev/null
+++ b/crates/core/src/launch/defaults.rs
@@ -0,0 +1,203 @@
+//! 默认参数表：JVM 优化、编码、log4j、禁用参数、环境变量。
+//!
+//! 平移自 `analyse/02` §4.3（自动优化）、§4.4（编码/Log4j）、§4.1 #33（禁用参数）、
+//! §4.10（环境变量）。所有函数都是纯函数——同样的输入永远给同样的参数，便于快照测试。
+
+use crate::launch::platform::OsFamily;
+use crate::launch::request::{LaunchRequest, ModLoaderKind, RendererOptions, Resolution};
+
+/// 旧版清单的默认 JVM 参数（`analyse/02` §4.7 的 `DEFAULT_JVM_ARGUMENTS`）。
+///
+/// 现代清单把这两项写在自己的 `arguments.jvm` 里，只有 legacy 需要补。
+pub fn legacy_jvm_arguments() -> Vec {
+    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");
+    }
+    if os == OsFamily::MacOs {
+        if let Some(icd) = &req.renderer.vulkan_icd {
+            set_env(&mut env, "VK_ICD_FILENAMES", &icd.display().to_string());
+            set_env(&mut env, "VK_DRIVER_FILES", &icd.display().to_string());
+        }
+    }
+    match req.mod_loader {
+        ModLoaderKind::Forge => set_env(&mut env, "FORGE_INSTALL", "1"),
+        ModLoaderKind::NeoForge => set_env(&mut env, "NEOFORGE_INSTALL", "1"),
+        ModLoaderKind::Fabric => set_env(&mut env, "FABRIC_INSTALL", "1"),
+        ModLoaderKind::Quilt => set_env(&mut env, "QUILT_INSTALL", "1"),
+        ModLoaderKind::LiteLoader => set_env(&mut env, "LITELOADER_INSTALL", "1"),
+        ModLoaderKind::OptiFine | ModLoaderKind::Vanilla => {}
+    }
+    for (key, value) in &req.user.environment {
+        set_env(&mut env, key, value);
+    }
+    env
+}
+
+fn set_env(env: &mut Vec<(String, String)>, key: &str, value: &str) {
+    if let Some(slot) = env.iter_mut().find(|(existing, _)| existing == key) {
+        slot.1 = value.to_string();
+    } else {
+        env.push((key.to_string(), value.to_string()));
+    }
+}
diff --git a/crates/core/src/launch/diagnosis_hook.rs b/crates/core/src/launch/diagnosis_hook.rs
new file mode 100644
index 0000000..889c7c6
--- /dev/null
+++ b/crates/core/src/launch/diagnosis_hook.rs
@@ -0,0 +1,97 @@
+//! 诊断挂钩：launch 与 M15（`core::diagnose`）之间的唯一接缝。
+//!
+//! 分工（`DevDocs/SubAgentsTalk/launch-接口约定.md` §3）：**launch 报事实、M15 下结论**。
+//! launch 在进程结束后把「退出判定 + 日志环形缓冲 + 崩溃现场文件 + 环境快照」打包成
+//! [`DiagnosisRequest`] 交给挂钩；挂钩返回结构化 payload（`candidates[]` 等），由 launch
+//! 脱敏后写进同一个 JSONL（单一真相源）。
+//!
+//! 这样 M15 不需要 import launch 的类型，launch 也不需要 import diagnose 的类型——
+//! 阶段 B 的 diagnose 尚未合并，P0 先用 [`NoopDiagnosis`] 占位。
+
+use std::path::PathBuf;
+
+use serde_json::Value;
+
+use crate::launch::crash_scan::CrashArtifact;
+use crate::launch::exit_analysis::ExitAnalysis;
+use crate::launch::pump::LogLine;
+
+/// 诊断挂钩。
+pub trait DiagnosisHook: Send + Sync {
+    /// 需要诊断时调用；返回 `None` 表示“这次没有结论”（事件流里就不会有 `diagnosis` 事件）。
+    fn analyze(&self, request: &DiagnosisRequest) -> Option;
+}
+
+/// 空挂钩：不诊断（占位 / 用户关闭 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..1d5d435
--- /dev/null
+++ b/crates/core/src/launch/error.rs
@@ -0,0 +1,165 @@
+//! launch 模块统一错误类型。
+//!
+//! 设计依据：`DevDocs/PlanDoc/06-launch-and-diagnostics.md` §1、`analyse/02` §8.4-3
+//! （缺库/缺组件必须结构化报错并显式失败，而不是交给运行时 `NoClassDefFoundError`）。
+
+use std::fmt;
+use std::path::PathBuf;
+
+/// launch 相关操作的统一结果类型。
+pub type Result = 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,
+    },
+}
+
+impl fmt::Display for LaunchError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Assembly(err) => write!(f, "命令行组装失败：{err}"),
+            Self::Io { op, path, source } => {
+                write!(f, "{op} 失败（{}）：{source}", path.display())
+            }
+            Self::Spawn { program, source } => {
+                write!(f, "启动进程失败（{}）：{source}", program.display())
+            }
+            Self::Session { path, reason } => {
+                write!(f, "会话事件流错误（{}）：{reason}", path.display())
+            }
+            Self::Kill { pid, source } => {
+                write!(f, "结束进程树失败（pid {pid}）：{source}")
+            }
+        }
+    }
+}
+
+impl std::error::Error for LaunchError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            Self::Assembly(err) => Some(err),
+            Self::Io { source, .. } | Self::Spawn { source, .. } | Self::Kill { source, .. } => {
+                Some(source)
+            }
+            Self::Session { .. } => None,
+        }
+    }
+}
+
+impl From for LaunchError {
+    fn from(err: AssemblyError) -> Self {
+        Self::Assembly(err)
+    }
+}
diff --git a/crates/core/src/launch/exit_analysis.rs b/crates/core/src/launch/exit_analysis.rs
new file mode 100644
index 0000000..a4bc842
--- /dev/null
+++ b/crates/core/src/launch/exit_analysis.rs
@@ -0,0 +1,264 @@
+//! 退出分析：退出码语义 + `exit 0` 静默失败检测。
+//!
+//! 平移自 `analyse/02` §6.3/§7.2（`ExitWaiter` 的三源判定），并按 §8.4-2 / §7.10-10 做两处升级：
+//!
+//! 1. **完整退出码表**：不只认 Linux 的 `137`，Windows 的 NTSTATUS
+//!    （`0xC0000005` 等）也要能说清是什么；
+//! 2. **静默失败单独立标**：退出码 0 但存活 <30s 或 stderr 带错误特征时标记
+//!    `silent_failure`——HMCL 会判 NORMAL 放过（LaunchWrapper 吞异常后 `exit 0` 是
+//!    真实存在的失败形态）。
+
+use crate::launch::pump::LogLine;
+
+/// 退出判定类型。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ExitType {
+    /// 正常退出。
+    Normal,
+    /// 应用层崩溃（游戏起来了但崩了）。
+    ApplicationError,
+    /// JVM 都没起来（`-Xmx` 过大、JVM 参数非法等）。
+    JvmError,
+    /// 被 `SIGKILL` 结束（POSIX 137）。
+    SigKill,
+    /// 被 `SIGTERM` 结束（POSIX 143）。
+    SigTerm,
+    /// 被启动器主动结束（用户点取消 / 看门狗强制）。
+    Killed,
+    /// 等待被中断。
+    Interrupted,
+}
+
+impl ExitType {
+    /// 事件流里的字符串形式（与 M15 `ExitType` 刻意保持一致）。
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Normal => "normal",
+            Self::ApplicationError => "application_error",
+            Self::JvmError => "jvm_error",
+            Self::SigKill => "sigkill",
+            Self::SigTerm => "sigterm",
+            Self::Killed => "killed",
+            Self::Interrupted => "interrupted",
+        }
+    }
+
+    /// 是否属于“非正常退出”。
+    pub fn is_abnormal(self) -> bool {
+        self != Self::Normal
+    }
+}
+
+/// JVM 未能启动的三条关键字（`analyse/02` §7.2）。
+pub const JVM_FAILURE_KEYWORDS: &[&str] = &[
+    "Could not create the Java Virtual Machine.",
+    "Error occurred during initialization of VM",
+    "A fatal exception has occurred. Program will exit.",
+];
+
+/// 应用层崩溃的五条关键字（`analyse/02` §7.2，覆盖三种崩法）。
+pub const CRASH_KEYWORDS: &[&str] = &[
+    "Crash report saved to",
+    "Could not save crash report to",
+    "This crash report has been saved to:",
+    "Unable to launch",
+    "An exception was thrown, the game will display an error screen and halt.",
+];
+
+/// 静默失败的存活阈值（毫秒）：<30s 视为“没真正跑起来”。
+pub const SHORT_LIVED_MS: u64 = 30_000;
+
+/// 退出分析的输入。
+#[derive(Debug, Clone, Copy)]
+pub struct ExitSignals<'a> {
+    /// 退出码。
+    pub code: i32,
+    /// 进程存活毫秒数。
+    pub uptime_ms: u64,
+    /// 环形缓冲里的日志行。
+    pub lines: &'a [LogLine],
+    /// 是否启动器主动结束。
+    pub killed: bool,
+    /// 等待是否被中断。
+    pub interrupted: bool,
+    /// 是否 POSIX（决定 137/143 是否按信号解读）。
+    pub is_posix: bool,
+}
+
+impl<'a> ExitSignals<'a> {
+    /// 构造。
+    pub fn new(code: i32, uptime_ms: u64, lines: &'a [LogLine]) -> Self {
+        Self {
+            code,
+            uptime_ms,
+            lines,
+            killed: false,
+            interrupted: false,
+            is_posix: cfg!(unix),
+        }
+    }
+}
+
+/// 静默失败标记。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct SilentFailure {
+    /// 存活时间过短。
+    pub short_lived: bool,
+    /// stderr/日志里有错误特征。
+    pub error_output: bool,
+}
+
+impl SilentFailure {
+    /// 人读说明。
+    pub fn describe(&self) -> String {
+        match (self.short_lived, self.error_output) {
+            (true, true) => "退出码 0，但存活不足 30 秒且输出含错误特征".to_string(),
+            (true, false) => "退出码 0，但存活不足 30 秒".to_string(),
+            (false, true) => "退出码 0，但输出含错误特征".to_string(),
+            (false, false) => "退出码 0".to_string(),
+        }
+    }
+}
+
+/// 退出分析结果（`exit` 事件的 payload 来源）。
+#[derive(Debug, Clone)]
+pub struct ExitAnalysis {
+    /// 退出码。
+    pub code: i32,
+    /// 判定类型。
+    pub exit_type: ExitType,
+    /// 存活毫秒数。
+    pub uptime_ms: u64,
+    /// 错误级日志行数。
+    pub error_lines: u32,
+    /// 命中的崩溃关键字。
+    pub crash_keywords: Vec,
+    /// 命中的 JVM 失败关键字。
+    pub jvm_keywords: Vec,
+    /// 静默失败标记（仅 `Normal` 时可能非空）。
+    pub silent_failure: Option,
+    /// Windows NTSTATUS 解释（例 `0xC0000005 ACCESS_VIOLATION`）。
+    pub windows_status: Option,
+    /// 是否应该进入诊断流水线（M15）。
+    pub needs_diagnosis: bool,
+}
+
+impl ExitAnalysis {
+    /// 一句话摘要（UI/agent 可直接展示）。
+    pub fn summary(&self) -> String {
+        let mut text = format!(
+            "退出码 {}（{}），存活 {:.1}s，错误行 {}",
+            self.code,
+            self.exit_type.as_str(),
+            self.uptime_ms as f64 / 1000.0,
+            self.error_lines
+        );
+        if let Some(status) = &self.windows_status {
+            text.push_str(&format!("，{status}"));
+        }
+        if !self.crash_keywords.is_empty() {
+            text.push_str(&format!("，崩溃关键字 {}", self.crash_keywords.len()));
+        }
+        if let Some(silent) = &self.silent_failure {
+            text.push_str(&format!("，{}", silent.describe()));
+        }
+        text
+    }
+}
+
+/// 做退出分析。
+pub fn analyze(signals: &ExitSignals<'_>) -> ExitAnalysis {
+    let error_lines = signals.lines.iter().filter(|line| line.is_error()).count();
+    let crash_keywords = matched_keywords(signals.lines, CRASH_KEYWORDS);
+    let jvm_keywords = matched_keywords(signals.lines, JVM_FAILURE_KEYWORDS);
+    let error_output = signals
+        .lines
+        .iter()
+        .any(|line| line.is_error() && looks_like_failure(&line.text));
+
+    let exit_type = if signals.interrupted {
+        ExitType::Interrupted
+    } else if signals.killed {
+        ExitType::Killed
+    } else if signals.code != 0 && !jvm_keywords.is_empty() {
+        ExitType::JvmError
+    } else if signals.is_posix && signals.code == 137 {
+        ExitType::SigKill
+    } else if signals.is_posix && signals.code == 143 {
+        ExitType::SigTerm
+    } else if signals.code != 0 || !crash_keywords.is_empty() {
+        ExitType::ApplicationError
+    } else {
+        ExitType::Normal
+    };
+
+    let silent_failure = if exit_type == ExitType::Normal {
+        let short_lived = signals.uptime_ms < SHORT_LIVED_MS;
+        if short_lived || error_output {
+            Some(SilentFailure {
+                short_lived,
+                error_output,
+            })
+        } else {
+            None
+        }
+    } else {
+        None
+    };
+
+    ExitAnalysis {
+        code: signals.code,
+        exit_type,
+        uptime_ms: signals.uptime_ms,
+        error_lines: u32::try_from(error_lines).unwrap_or(u32::MAX),
+        crash_keywords: crash_keywords.clone(),
+        jvm_keywords,
+        silent_failure,
+        windows_status: windows_status_name(signals.code),
+        needs_diagnosis: exit_type.is_abnormal()
+            || silent_failure.is_some()
+            || !crash_keywords.is_empty(),
+    }
+}
+
+/// Windows NTSTATUS → 解释。
+pub fn windows_status_name(code: i32) -> Option {
+    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/launch_session.rs b/crates/core/src/launch/launch_session.rs
new file mode 100644
index 0000000..529a406
--- /dev/null
+++ b/crates/core/src/launch/launch_session.rs
@@ -0,0 +1,329 @@
+//! 运行中的启动会话与收尾流水线。
+//!
+//! 一次启动的生命周期（`DevDocs/PlanDoc/06-launch-and-diagnostics.md` §1 的第 7~10 阶段）：
+//! `spawn` → 用户可能 [`LaunchSession::stop`] → [`LaunchSession::finish`]
+//! （等进程 → 等日志泵（有预算）→ 退出分析 → 扫崩溃现场 → 诊断挂钩 → 写事件 + 索引）。
+
+use std::path::{Path, PathBuf};
+use std::sync::Arc;
+use std::time::SystemTime;
+
+use serde_json::Value;
+
+use crate::launch::args_table::AssembledCommand;
+use crate::launch::crash_scan::{self, CrashArtifact};
+use crate::launch::diagnosis_hook::{DiagnosisHook, DiagnosisRequest};
+use crate::launch::error::Result;
+use crate::launch::exit_analysis::{self, ExitAnalysis, ExitSignals};
+use crate::launch::launcher::LauncherConfig;
+use crate::launch::process::{self, RunningProcess};
+use crate::launch::pump::{LineSink, LogLine};
+use crate::launch::redact::Redactor;
+use crate::launch::request::LaunchRequest;
+use crate::launch::session::{EndReason, SessionSink};
+use crate::launch::session_index::SessionIndexEntry;
+
+/// 一次运行中的启动会话。
+pub struct LaunchSession {
+    config: LauncherConfig,
+    hook: Arc,
+    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()
+    }
+}
+
+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()
+    }
+
+    /// 收尾：等进程 → 等日志泵 → 退出分析 → 现场扫描 → 诊断 → 事件 + 索引。
+    pub fn finish(mut self) -> Result {
+        let status = self.process.wait()?;
+        let code = process::exit_code(&status);
+        // uptime 必须在等日志泵之前取（泵的等待预算不算进游戏存活时间）。
+        let uptime_ms = self.process.uptime_ms();
+        let verdict = self.process.supervise();
+        let pump_stalled = !verdict.is_complete();
+        let lines = self.process.lines();
+
+        let mut signals = ExitSignals::new(code, uptime_ms, &lines);
+        signals.killed = self.killed;
+        signals.is_posix = self.config.platform.os.is_posix();
+        let exit = exit_analysis::analyze(&signals);
+
+        let artifacts = self.collect_artifacts();
+        // 脱敏只算一次：诊断包与 `SessionHandle::redacted_argv()` 共用。
+        let redacted_argv = self.redactor.scrub_all(&self.command.argv());
+        let diagnosis_request = self.build_diagnosis_request(
+            &exit,
+            &lines,
+            &artifacts,
+            uptime_ms,
+            redacted_argv.clone(),
+        );
+        let should_diagnose = exit.needs_diagnosis || !artifacts.is_empty();
+        let diagnosis = if should_diagnose {
+            self.hook.analyze(&diagnosis_request)
+        } else {
+            None
+        };
+
+        let mut event_write_errors = Vec::new();
+        let mut diagnostics = None;
+        let mut index = None;
+        let end_reason = if self.killed {
+            EndReason::Killed
+        } else {
+            EndReason::Exit
+        };
+        let completed = self.sink.with_writer(|writer| {
+            if let Err(err) = writer.exit(&exit) {
+                event_write_errors.push(err.to_string());
+            }
+            for artifact in &artifacts {
+                let result = writer.crash_found(
+                    artifact.source.as_str(),
+                    &artifact.path,
+                    artifact.excerpt.as_deref(),
+                );
+                if let Err(err) = result {
+                    event_write_errors.push(err.to_string());
+                }
+            }
+            if let Some(record) = diagnosis {
+                if let Err(err) = writer.diagnosis(record.clone()) {
+                    event_write_errors.push(err.to_string());
+                }
+                diagnostics = Some(record);
+            }
+            match writer.finish(end_reason) {
+                Ok(entry) => index = Some(entry),
+                Err(err) => event_write_errors.push(err.to_string()),
+            }
+        });
+        if completed.is_none() {
+            event_write_errors.push("会话写入器不可用（锁中毒）".to_string());
+        }
+
+        Ok(SessionHandle {
+            session_id: self.session_id,
+            log_path: self.log_path,
+            command: self.command,
+            redacted_argv,
+            exit,
+            diagnostics,
+            index,
+            artifacts,
+            uptime_ms,
+            pump_stalled,
+            event_write_errors,
+        })
+    }
+
+    fn collect_artifacts(&self) -> Vec {
+        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()
+        }
+    }
+}
+
+/// 一次启动的结果。
+#[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 {
+    /// 脱敏后的完整 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
+    }
+
+    /// 一句话摘要。
+    pub fn summary(&self) -> String {
+        let mut text = format!("会话 {}：{}", self.session_id, self.exit.summary());
+        if self.pump_stalled {
+            text.push_str("；日志泵超时");
+        }
+        if let Some(top) = &self.diagnostics {
+            if let Some(id) = top
+                .get("candidates")
+                .and_then(Value::as_array)
+                .and_then(|items| items.first())
+                .and_then(|item| item.get("id"))
+                .and_then(Value::as_str)
+            {
+                text.push_str(&format!("；诊断首因 {id}"));
+            }
+        }
+        text
+    }
+}
diff --git a/crates/core/src/launch/launcher.rs b/crates/core/src/launch/launcher.rs
new file mode 100644
index 0000000..ea023b6
--- /dev/null
+++ b/crates/core/src/launch/launcher.rs
@@ -0,0 +1,298 @@
+//! 顶层启动管线：组装 → 会话 → 进程 → 退出分析 → 诊断 → 索引。
+//!
+//! 对应 `DevDocs/PlanDoc/06-launch-and-diagnostics.md` §1 的 10 阶段：
+//! 1~2（快照/账户）由调用方与 `adapter` 完成，3（Java 选择）由 D13 给出 `JavaSelection`，
+//! 4（组件就绪检查）由 download/game 给出 `missing_components`，6（环境准备的 natives 段）
+//! 由 [`crate::launch::natives`] 在本模块收口，5、7~10 见下。
+//!
+//! 两个入口：
+//! - [`Launcher::dry_run`]（D18 接线点）：只组装、不 spawn、不写会话文件，返回完整命令行；
+//! - [`Launcher::launch`]：完整跑一局，返回 [`SessionHandle`]（退出判定 + 诊断结论 + 索引条目）。
+//!
+//! 阶段 B 说明：diagnose（M15）尚未合并，诊断走 [`DiagnosisHook`] 接缝，默认 [`NoopDiagnosis`]。
+
+use std::path::PathBuf;
+use std::sync::Arc;
+use std::time::Instant;
+
+use crate::launch::args_table::{assemble, AssembledCommand};
+use crate::launch::diagnosis_hook::{DiagnosisHook, NoopDiagnosis};
+use crate::launch::error::{AssemblyError, Result};
+use crate::launch::launch_session::{LaunchSession, SessionHandle};
+use crate::launch::natives::{self, NativesReport};
+use crate::launch::platform::PlatformCtx;
+use crate::launch::process::{ProcessConfig, RunningProcess};
+use crate::launch::redact::Redactor;
+use crate::launch::request::LaunchRequest;
+use crate::launch::session::{EndReason, SessionMeta, SessionSink, SessionWriter};
+
+/// 启动器配置。
+#[derive(Debug, Clone)]
+pub struct LauncherConfig {
+    /// 会话文件根目录（`/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
+    }
+}
+
+/// `--dry-run` 的输出（D18）：完整命令行，但**不 spawn、不写会话文件**。
+///
+/// 会做的事与真实启动**一致到「环境准备」为止**：natives 解压照做（幂等，`natives` 字段
+/// 回报结果），因为「装完能不能起」的一半答案就在「native 库有没有落地」上。
+#[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`）。
+    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> {
+        if request.dirs.natives_dir.as_os_str().is_empty() {
+            return Ok(None);
+        }
+        natives::extract(&request.dirs.natives_dir, &request.natives)
+            .map(Some)
+            .map_err(|err| AssemblyError::NativesExtraction {
+                message: err.message(),
+            })
+            .map_err(Into::into)
+    }
+
+    /// D18：组装完整命令行并返回，**不 spawn 进程、不写会话文件**。
+    ///
+    /// 供 `unlucky-launcher --dry-run ` 打印一行命令行后退出；
+    /// accessToken 已脱敏（绝不把凭据打到终端/日志里）。
+    pub fn dry_run(&self, request: &LaunchRequest) -> Result {
+        let natives = self.prepare_environment(request)?;
+        let command = self.plan(request)?;
+        let redactor = self.redactor(request);
+        let warnings = command
+            .warnings
+            .iter()
+            .map(ToString::to_string)
+            .collect::>();
+        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 主入口）。
+    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/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..02db942
--- /dev/null
+++ b/crates/core/src/launch/mod.rs
@@ -0,0 +1,75 @@
+//! 启动管线：10 阶段命令行组装、Java 选择、子进程管理、结构化 JSONL 事件流。
+//!
+//! 设计定稿：`DevDocs/PlanDoc/06-launch-and-diagnostics.md` §1（管线）与 §3（事件流），
+//! Java 侧约束见 `DevDocs/PlanDoc/01d-language-choice.md` §3（JDK 17 基准 + 版本映射提示）。
+//!
+//! 事件流是 core → app 的唯一启动反馈通道（另一条是快照发布），
+//! 不做 200ms 批量刷 UI 式的隐式耦合。
+//!
+//! # 公共面
+//!
+//! - [`Launcher`]：`dry_run`（D18，只组装命令行）、`spawn`/`launch`（完整管线）；
+//! - [`LaunchRequest`] 是命令行组装的**纯数据输入**，由 [`adapter`] 从 game 快照映射而来；
+//! - [`AssembledCommand`] 是组装结果（program + argv + classpath + 环境变量 + 告警）；
+//! - 事件流（[`session`]）与索引（[`session_index`]）是 M15 诊断采集器与
+//!   M16 `read_game_log`/`list_game_sessions` 的数据源，schema 见
+//!   `DevDocs/SubAgentsTalk/launch-接口约定.md`；
+//! - [`DiagnosisHook`] 是接 M15 的唯一接缝（launch 报事实、M15 下结论）。
+//!
+//! # 与 HMCL 的三处差异（`analyse/02` §8.5）
+//!
+//! 1. `exit 0` 静默失败单独立标（[`exit_analysis`]）；
+//! 2. 日志泵 join 有预算（[`watchdog`]），进程树三段式回收（[`tree_kill`]，P1 换 Job Object）；
+//! 3. 窗口出现检测带启发式名称/耗时/证据（[`window_detect`]）。
+//!
+//! 零 UI 依赖：本模块只产出结构化事件与纯数据，不 import 任何 UI 类型。
+
+pub mod adapter;
+pub mod args_table;
+pub mod argument;
+pub mod command_builder;
+pub mod crash_scan;
+pub mod defaults;
+pub mod diagnosis_hook;
+pub mod error;
+pub mod exit_analysis;
+pub mod game_args;
+pub mod game_version;
+pub mod jvm_args;
+pub mod launch_session;
+pub mod launcher;
+pub mod log_level;
+pub mod natives;
+pub mod placeholders;
+pub mod platform;
+pub mod process;
+pub mod pump;
+pub mod redact;
+pub mod request;
+pub mod session;
+pub mod session_index;
+pub mod session_meta;
+pub mod session_payload;
+pub mod session_sink;
+pub mod sink;
+pub mod time;
+pub mod tree_kill;
+pub mod watchdog;
+pub mod window_detect;
+
+pub use adapter::{
+    build_request, AdapterOptions, AdapterOutput, AdapterWarning, LibraryInput, SnapshotInput,
+};
+pub use args_table::{assemble, AssembledCommand, AssemblyWarning};
+pub use crash_scan::{CrashArtifact, CrashSource};
+pub use diagnosis_hook::{DiagnosisHook, DiagnosisRequest, NoopDiagnosis};
+pub use error::{LaunchError, MissingComponent, Result};
+pub use exit_analysis::{ExitAnalysis, ExitType, SilentFailure};
+pub use launch_session::{LaunchSession, SessionHandle};
+pub use launcher::{DryRun, Launcher, LauncherConfig};
+pub use natives::{NativeJar, NativesEra, NativesPlan, NativesReport};
+pub use process::{ProcessConfig, RunningProcess};
+pub use request::LaunchRequest;
+pub use session::{EndReason, SessionMeta, SessionSink, SessionWriter};
+pub use session_index::SessionIndexEntry;
+pub use sink::{CompositeSink, CountingSink, FnSink};
diff --git a/crates/core/src/launch/natives/jar.rs b/crates/core/src/launch/natives/jar.rs
new file mode 100644
index 0000000..5e8c559
--- /dev/null
+++ b/crates/core/src/launch/natives/jar.rs
@@ -0,0 +1,250 @@
+//! natives jar 的读取细节：zip 遍历、条目筛选、目录清理、戳记读写。
+//!
+//! 与 [`super`] 的分工：`super` 管「计划与报告」，这里管「怎么把一个 jar 里的原生库落到盘上」。
+
+use std::fs::{self, File};
+use std::io;
+use std::path::{Path, PathBuf};
+use std::time::UNIX_EPOCH;
+
+use serde::{Deserialize, Serialize};
+use zip::ZipArchive;
+
+use super::{NativeJar, NativesError, NativesReport, STAMP_FILE};
+
+/// 戳记 schema 版本（改字段语义才升）。
+const STAMP_VERSION: u8 = 1;
+
+/// 内置排除前缀：Mojang 清单惯例，manifest 没写 `extract` 规则时也这么办。
+const DEFAULT_EXCLUDES: &[&str] = &["META-INF/"];
+
+/// 原生库扩展名白名单（Windows / Linux / macOS；`jnilib` 是 JDK6 时代的老 mac 后缀）。
+const NATIVE_EXTENSIONS: &[&str] = &["dll", "so", "dylib", "jnilib"];
+
+/// 签名 / 校验附属文件扩展名：即使在 natives jar 根目录也绝不落地。
+const SIGNATURE_EXTENSIONS: &[&str] = &["sf", "rsa", "dsa", "ec", "asc", "sha1", "sha256", "git"];
+
+/// 戳记的一条：源 jar 的「路径 + 字节数 + mtime」指纹。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub(crate) struct JarStamp {
+    /// 源 jar 绝对路径（同一目录换了别的版本时必须能区分开）。
+    pub path: String,
+    /// 字节数。
+    pub len: u64,
+    /// 修改时间（Unix 毫秒；读不到时 0，等价于「每次都当它变了」）。
+    pub mtime_ms: u64,
+}
+
+/// 目录戳记文件内容。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub(crate) struct Stamp {
+    v: u8,
+    files: usize,
+    jars: Vec,
+}
+
+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,
+    }
+}
+
+/// 解压单个 jar：排除前缀 → 原生库白名单 → zip-slip 防护 → 落盘。
+pub(crate) fn extract_jar(
+    native: &NativeJar,
+    dir: &Path,
+    report: &mut NativesReport,
+) -> Result<(), NativesError> {
+    let file = File::open(&native.path)
+        .map_err(|source| io_error("open_native_jar", &native.path, source))?;
+    let mut archive = ZipArchive::new(file).map_err(|err| NativesError::Zip {
+        path: native.path.clone(),
+        reason: err.to_string(),
+    })?;
+    let excludes: Vec<&str> = DEFAULT_EXCLUDES
+        .iter()
+        .copied()
+        .chain(native.exclude.iter().map(String::as_str))
+        .collect();
+
+    for index in 0..archive.len() {
+        let mut entry = archive.by_index(index).map_err(|err| NativesError::Zip {
+            path: native.path.clone(),
+            reason: err.to_string(),
+        })?;
+        if entry.is_dir() {
+            continue;
+        }
+        // `enclosed_name` 拒绝 `..` / 绝对路径条目（zip-slip）。
+        let Some(relative) = entry.enclosed_name() else {
+            report.ignored += 1;
+            continue;
+        };
+        let name = relative.to_string_lossy().replace('\\', "/");
+        if !should_extract(&name, &excludes) {
+            report.ignored += 1;
+            continue;
+        }
+        let dest = dir.join(&relative);
+        if let Some(parent) = dest.parent() {
+            fs::create_dir_all(parent)
+                .map_err(|source| io_error("create_natives_subdir", parent, source))?;
+        }
+        let mut out =
+            File::create(&dest).map_err(|source| io_error("create_native_file", &dest, source))?;
+        io::copy(&mut entry, &mut out)
+            .map_err(|source| io_error("write_native_file", &dest, source))?;
+        report.files += 1;
+    }
+    Ok(())
+}
+
+/// 该条目要不要解压：排除前缀命中、签名文件、非原生库扩展名 → 跳过。
+pub(crate) fn should_extract(name: &str, excludes: &[&str]) -> bool {
+    if excludes.iter().any(|prefix| name.starts_with(prefix)) {
+        return false;
+    }
+    let lower = name.to_ascii_lowercase();
+    let extension = lower.rsplit_once('.').map(|(_, ext)| ext).unwrap_or("");
+    if SIGNATURE_EXTENSIONS.contains(&extension) {
+        return false;
+    }
+    NATIVE_EXTENSIONS.contains(&extension)
+}
+
+/// 清掉目录里已有的原生库与戳记（尽力而为：删不掉的留着，后面覆盖写会报错）。
+pub(crate) fn clear_natives(dir: &Path) {
+    let Ok(entries) = fs::read_dir(dir) else {
+        return;
+    };
+    for entry in entries.flatten() {
+        let path = entry.path();
+        if path.is_dir() {
+            continue;
+        }
+        let name = path
+            .file_name()
+            .map(|name| name.to_string_lossy().to_ascii_lowercase())
+            .unwrap_or_default();
+        if name == STAMP_FILE {
+            let _ = fs::remove_file(&path);
+            continue;
+        }
+        let is_native = name
+            .rsplit_once('.')
+            .map(|(_, ext)| NATIVE_EXTENSIONS.contains(&ext))
+            .unwrap_or(false);
+        if is_native {
+            let _ = fs::remove_file(&path);
+        }
+    }
+}
+
+/// 源 jar 指纹（路径 + 字节数 + mtime）。
+pub(crate) fn jar_stamps(jars: &[NativeJar]) -> Vec {
+    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..a57e83c
--- /dev/null
+++ b/crates/core/src/launch/natives/mod.rs
@@ -0,0 +1,355 @@
+//! natives 解压：把版本链里的 natives 分类器构件解到 `versions//natives/`。
+//!
+//! 这是 10 阶段管线里**第 6 段「环境准备」**的落盘部分（`PlanDoc/06` §1），发生顺序在
+//! 命令行组装之前（HMCL 也在组装期做：`DefaultLauncher.decompressNatives`，
+//! `analyse/03` §6.4-(7)），因此 `--dry-run` 也能验证「装完到底能不能起」。
+//!
+//! # 三个时代（`SubAgentsTalk/launch-natives-解压与时代分界.md`，piston-meta 实测）
+//!
+//! | 版本区间 | natives 形态 | 谁负责 `-Djava.library.path` |
+//! |---|---|---|
+//! | ≤1.12.2（LWJGL 2.9） | `natives` 表 + `downloads.classifiers` | 启动器补（`defaults::legacy_jvm_arguments`） |
+//! | 1.13–1.18.2（LWJGL 3.1/3.2） | 同上（另有同坐标的主构件条目） | 清单自己写 `arguments.jvm` |
+//! | 1.19+（LWJGL 3.3） | **没有 `natives` 表**：natives jar 是普通 classpath 库 | 清单写 4 个目录属性，LWJGL 运行期自解压 |
+//!
+//! 所以三个时代走**同一条代码路径**：有 jar 就解压，没 jar 就只把目录建出来
+//! （1.19+ 的 `-Dorg.lwjgl.system.SharedLibraryExtractPath` 指向它；目录不存在时
+//! LWJGL 会静默走到「找不到 native」）。
+//!
+//! # 幂等
+//!
+//! 解压完在目录里写一份戳记 [`jar::STAMP_FILE`]（每个源 jar 的路径 + 字节数 + mtime）。
+//! 下次启动：戳记与当前 jar 集完全一致 → 目录视为就绪，**不读 jar、不写盘**直接跳过；
+//! 不一致（换版本 / 库升级 / 用户删了目录）→ 清掉旧原生库再全量解压，避免两代 dll
+//! 混在同一个 `java.library.path` 里（HMCL 也是每次清目录，这里只把「没变就不动」补上）。
+
+pub(crate) mod jar;
+
+use std::path::{Path, PathBuf};
+
+use crate::game::arguments::Environment;
+use crate::game::layout::GameLayout;
+use crate::game::library::Library;
+use crate::launch::natives::jar::{
+    clear_natives, extract_jar, jar_stamps, read_stamp, write_stamp,
+};
+
+/// 戳记文件名：放在 natives 目录里，跟着目录一起删 / 建。
+///
+/// 公开出来是为了「一键修复」类功能能认出自己的痕迹（判断目录里哪些文件是我们解出来的）。
+pub const STAMP_FILE: &str = ".ull-natives.json";
+
+/// 一个待解压的 natives 构件（版本链里 `natives` 分类器命中的 jar）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct NativeJar {
+    /// 磁盘路径（`libraries//.../--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()
+    }
+}
+
+/// 解压结果（进 `natives_extracted` 事件与 `--dry-run` 输出）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct NativesReport {
+    /// 目标目录。
+    pub dir: PathBuf,
+    /// 时代。
+    pub era: NativesEra,
+    /// 参与的 jar 数。
+    pub jars: usize,
+    /// 本次写盘的原生库文件数。
+    pub files: usize,
+    /// 按戳记跳过、未重新解压的文件数（= 上次解压的文件数）。
+    pub skipped: usize,
+    /// 被排除 / 非原生库而忽略的条目数（`META-INF/`、签名文件）。
+    pub ignored: usize,
+    /// 目录是否用户自定义。
+    pub custom: bool,
+    /// 是否按戳记判定「目录已就绪」而整体跳过。
+    pub up_to_date: bool,
+}
+
+impl NativesReport {
+    /// 人读一行（CLI / 日志用）。
+    pub fn summary(&self) -> String {
+        if self.jars == 0 {
+            return format!(
+                "natives 目录已就绪（该版本无需解压，LWJGL 运行期自取）→ {}",
+                self.dir.display()
+            );
+        }
+        if self.up_to_date {
+            return format!(
+                "natives 已就绪（{} 个原生库，{} 个 jar 未变）",
+                self.skipped, self.jars
+            );
+        }
+        format!(
+            "natives 解压 {} 个原生库（{} 个 jar，忽略 {} 个条目）→ {}",
+            self.files,
+            self.jars,
+            self.ignored,
+            self.dir.display()
+        )
+    }
+}
+
+/// 解压失败原因。
+#[derive(Debug)]
+pub enum NativesError {
+    /// 目标目录为空（调用方漏填 `natives_dir`）。
+    NoDir,
+    /// 文件系统操作失败。
+    Io {
+        /// 操作名。
+        op: &'static str,
+        /// 相关路径。
+        path: PathBuf,
+        /// 底层错误。
+        source: std::io::Error,
+    },
+    /// natives jar 打不开 / 不是合法 zip（下载损坏的最常见形态）。
+    Zip {
+        /// jar 路径。
+        path: PathBuf,
+        /// 原因。
+        reason: String,
+    },
+}
+
+impl NativesError {
+    /// 一行人读描述。
+    pub fn message(&self) -> String {
+        match self {
+            Self::NoDir => "natives 目录未配置（natives_dir 为空）".to_string(),
+            Self::Io { op, path, source } => {
+                format!("{op} 失败（{}）：{source}", path.display())
+            }
+            Self::Zip { path, reason } => {
+                format!(
+                    "natives jar 无法作为 zip 打开（{}）：{reason}",
+                    path.display()
+                )
+            }
+        }
+    }
+}
+
+impl std::fmt::Display for NativesError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(&self.message())
+    }
+}
+
+impl std::error::Error for NativesError {}
+
+/// 从版本链库表收集 natives 分类器构件（adapter / app / CLI 共用这一段，别各写一份）。
+///
+/// 口径与安装层 `game::install::libraries::plan` **除 `hint=local` 落点外**逐条对齐：
+/// 1. 先按环境过滤（`Library::applies`）；
+/// 2. `natives` 表命中当前 OS 才取分类器（1.19+ 没有 `natives` 表 → 返回空表）；
+/// 3. 落点优先用清单 `downloads.classifiers..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
+}
+
+/// 解压一个计划（幂等：目录与源 jar 都没变时零写盘）。
+///
+/// # 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,
+    };
+    // 1.19+ 没有 jar 也要建目录：LWJGL 3.3 往 SharedLibraryExtractPath 里解压。
+    std::fs::create_dir_all(dir)
+        .map_err(|source| jar::io_error("create_natives_dir", dir, source))?;
+    if plan.jars.is_empty() {
+        report.up_to_date = true;
+        return Ok(report);
+    }
+
+    let stamps = jar_stamps(&plan.jars);
+    if let Some(stamp) = read_stamp(dir) {
+        if stamp.matches(&stamps) {
+            report.up_to_date = true;
+            report.skipped = stamp.files();
+            return Ok(report);
+        }
+    }
+
+    // 源变了：先清旧原生库（避免两代 dll 混在同一个 java.library.path 里），再全量解。
+    clear_natives(dir);
+    for native in &plan.jars {
+        extract_jar(native, dir, &mut report)?;
+    }
+    write_stamp(dir, report.files, &stamps)?;
+    Ok(report)
+}
diff --git a/crates/core/src/launch/placeholders.rs b/crates/core/src/launch/placeholders.rs
new file mode 100644
index 0000000..b99f42b
--- /dev/null
+++ b/crates/core/src/launch/placeholders.rs
@@ -0,0 +1,173 @@
+//! 参数占位符字典与替换。
+//!
+//! 占位符清单平移自 `analyse/02` §4.8（`DefaultLauncher.getConfigurations()`）：
+//! 版本清单里的 `arguments.*` 用 `${...}` 引用运行时值，启动器负责在组装时替换。
+//! 替换语义与 HMCL 一致：**单遍、不递归**；未定义的占位符原样保留（便于发现清单漏项）。
+
+use std::collections::BTreeMap;
+use std::path::Path;
+
+use crate::launch::platform::PlatformCtx;
+use crate::launch::request::LaunchRequest;
+
+/// 我们支持的占位符键（不含 `${}` 包裹）。
+pub const PLACEHOLDER_KEYS: &[&str] = &[
+    "auth_player_name",
+    "auth_session",
+    "auth_access_token",
+    "auth_uuid",
+    "user_type",
+    "user_properties",
+    "version_name",
+    "version_type",
+    "profile_name",
+    "game_directory",
+    "assets_index_name",
+    "game_assets",
+    "assets_root",
+    "natives_directory",
+    "classpath",
+    "classpath_separator",
+    "launcher_name",
+    "launcher_version",
+    "library_directory",
+    "libraries_directory",
+    "primary_jar",
+    "primary_jar_name",
+    "file_separator",
+    "resolution_width",
+    "resolution_height",
+    "language",
+];
+
+/// 占位符表。
+#[derive(Debug, Clone, Default)]
+pub struct PlaceholderMap {
+    entries: BTreeMap,
+}
+
+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()
+    }
+
+    /// 单遍替换 `${key}`；未定义键原样保留。
+    pub fn render(&self, template: &str) -> String {
+        if !template.contains("${") {
+            return template.to_string();
+        }
+        let mut out = String::with_capacity(template.len() + 16);
+        let mut rest = template;
+        while let Some(start) = rest.find("${") {
+            out.push_str(&rest[..start]);
+            let after = &rest[start + 2..];
+            match after.find('}') {
+                Some(end) => {
+                    let key = &after[..end];
+                    match self.entries.get(key) {
+                        Some(value) => out.push_str(value),
+                        None => {
+                            out.push_str("${");
+                            out.push_str(key);
+                            out.push('}');
+                        }
+                    }
+                    rest = &after[end + 1..];
+                }
+                None => {
+                    out.push_str(&rest[start..]);
+                    rest = "";
+                }
+            }
+        }
+        out.push_str(rest);
+        out
+    }
+
+    /// 由启动请求构造完整占位符表。
+    pub fn from_request(req: &LaunchRequest, ctx: &PlatformCtx) -> Self {
+        let mut map = Self::new();
+        let auth = &req.auth;
+        map.insert("auth_player_name", auth.player_name.clone());
+        map.insert("auth_session", auth.access_token.clone());
+        map.insert("auth_access_token", auth.access_token.clone());
+        map.insert("auth_uuid", auth.uuid.clone());
+        map.insert("user_type", auth.user_type.clone());
+        map.insert("user_properties", auth.user_properties.clone());
+
+        map.insert("version_name", req.instance.name.clone());
+        map.insert("version_type", req.instance.version_type.clone());
+        map.insert("profile_name", req.instance.id.clone());
+
+        let dirs = &req.dirs;
+        map.insert("game_directory", path_str(&dirs.game_dir));
+        map.insert("assets_index_name", dirs.assets_index.clone());
+        map.insert("game_assets", path_str(&dirs.game_assets));
+        map.insert("assets_root", path_str(&dirs.assets_root));
+        map.insert("natives_directory", path_str(&dirs.natives_dir));
+        map.insert(
+            "classpath",
+            join_classpath(&req.classpath, ctx.path_separator()),
+        );
+        map.insert("classpath_separator", ctx.path_separator().to_string());
+        map.insert("launcher_name", req.launcher.name.clone());
+        map.insert("launcher_version", req.launcher.version.clone());
+        map.insert("library_directory", path_str(&dirs.library_dir));
+        map.insert("libraries_directory", path_str(&dirs.library_dir));
+        map.insert("primary_jar", path_str(&dirs.primary_jar));
+        map.insert(
+            "primary_jar_name",
+            dirs.primary_jar
+                .file_name()
+                .map(|name| name.to_string_lossy().into_owned())
+                .unwrap_or_default(),
+        );
+        map.insert("file_separator", ctx.file_separator().to_string());
+        match &req.resolution {
+            Some(res) => {
+                map.insert("resolution_width", res.width.to_string());
+                map.insert("resolution_height", res.height.to_string());
+            }
+            None => {
+                map.insert("resolution_width", String::new());
+                map.insert("resolution_height", String::new());
+            }
+        }
+        map.insert("language", req.language.clone());
+        map
+    }
+}
+
+/// 按平台分隔符拼接 classpath。
+pub fn join_classpath(paths: &[std::path::PathBuf], separator: char) -> String {
+    paths
+        .iter()
+        .map(|path| path.display().to_string())
+        .collect::>()
+        .join(&separator.to_string())
+}
+
+fn path_str(path: &Path) -> String {
+    path.display().to_string()
+}
diff --git a/crates/core/src/launch/platform.rs b/crates/core/src/launch/platform.rs
new file mode 100644
index 0000000..435b4a0
--- /dev/null
+++ b/crates/core/src/launch/platform.rs
@@ -0,0 +1,95 @@
+//! 平台上下文：命令行组装与进程管理需要知道的操作系统事实。
+//!
+//! 依据 `analyse/02` §4.1（Linux/macOS `nice`）、§4.4（原生编码）、§4.6（原生库路径）、
+//! §4.10（环境变量，`APPDATA` 重定向只在 Windows 有意义）。
+//!
+//! `os_version` 不再是空占位：`current()` 从 [`crate::platform::os_info`] 的运行期探测取值，
+//! 清单里带 `rules.os.version` 的参数项因此能真正命中（D19 · `PlanDoc/11-os-detection.md` §2）。
+
+use std::path::PathBuf;
+
+pub use crate::platform::os_info::OsFamily;
+
+/// 平台上下文。
+#[derive(Debug, Clone)]
+pub struct PlatformCtx {
+    /// 操作系统家族。
+    pub os: OsFamily,
+    /// `rules.os.arch` 用的架构名。
+    pub arch: String,
+    /// 系统原生编码（`-Dfile.encoding` 的默认值来源）。
+    pub native_charset: String,
+    /// 主目录（脱敏与 `-Duser.home` 用）。
+    pub home_dir: Option,
+    /// 系统版本串（`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..79a9582
--- /dev/null
+++ b/crates/core/src/launch/process.rs
@@ -0,0 +1,231 @@
+//! 进程管理：spawn + stdout/stderr 泵 + 进程树回收。
+//!
+//! 对应 `analyse/02` §6 的四条线程模型（`stdout-pump` / `stderr-pump` / `exit-waiter`），
+//! 但线程生命周期的收尾由 [`crate::launch::watchdog`] 兜底，不无条件 `join`。
+//!
+//! 本模块只管“把命令行跑起来并收集输出”，不做组件检查、不做诊断——
+//! 那些是 `launch` 上层流水线（阶段B）与 M15 的职责。
+
+use std::path::{Path, PathBuf};
+use std::process::{Child, Command, ExitStatus, Stdio};
+use std::sync::{Arc, Mutex};
+use std::time::{Duration, Instant};
+
+use crate::launch::args_table::AssembledCommand;
+use crate::launch::error::{LaunchError, Result};
+use crate::launch::pump::{LineSink, LogLine, PumpGroup, RingBuffer, RingBufferConfig};
+use crate::launch::tree_kill;
+use crate::launch::watchdog::{self, PumpVerdict, WatchdogConfig};
+
+/// 强制结束后等进程消失的预算。
+const FORCE_KILL_BUDGET: Duration = Duration::from_secs(5);
+/// 轮询进程状态的间隔。
+const POLL_INTERVAL: Duration = Duration::from_millis(20);
+
+/// 进程管理配置。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct ProcessConfig {
+    /// 日志泵等待预算。
+    pub watchdog: WatchdogConfig,
+    /// 停止时温和关闭的宽限期。
+    pub graceful_stop: Duration,
+    /// 环形缓冲配置。
+    pub buffer: RingBufferConfig,
+}
+
+impl Default for ProcessConfig {
+    fn default() -> Self {
+        Self {
+            watchdog: WatchdogConfig::default(),
+            graceful_stop: Duration::from_secs(3),
+            buffer: RingBufferConfig::default(),
+        }
+    }
+}
+
+/// 已启动的游戏进程。
+#[derive(Debug)]
+pub struct RunningProcess {
+    child: Child,
+    pump: PumpGroup,
+    buffer: Arc>,
+    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,
+        })
+    }
+
+    /// 进程退出后，按预算收尾日志泵。
+    pub fn supervise(&mut self) -> PumpVerdict {
+        watchdog::wait_for_pumps(&mut self.pump, &self.config.watchdog)
+    }
+
+    /// 进程是否仍在运行。
+    pub fn is_running(&mut self) -> bool {
+        matches!(self.child.try_wait(), Ok(None))
+    }
+
+    /// 三段式停止整棵进程树（温和 → 宽限 → 强制）。
+    ///
+    /// 判定标准是**进程是否真的没了**，不是 `taskkill`/`kill` 的退出码：
+    /// 外部命令对“已经退出的进程”会返回非 0（Windows 上 `taskkill` 报 128），
+    /// 把它当失败会误报——尤其是温和阶段已经把进程关掉的情况。
+    pub fn stop(&mut self) -> Result<()> {
+        if !self.is_running() {
+            return Ok(());
+        }
+        let _ = tree_kill::terminate(self.pid);
+        if self.wait_until_exit(self.config.graceful_stop) {
+            return Ok(());
+        }
+        let _ = tree_kill::force_kill(self.pid);
+        if self.wait_until_exit(FORCE_KILL_BUDGET) {
+            return Ok(());
+        }
+        Err(LaunchError::Kill {
+            pid: self.pid,
+            source: std::io::Error::other("强制结束后进程仍在运行"),
+        })
+    }
+
+    /// 直接强杀（看门狗/崩溃兜底路径）。
+    pub fn force_kill(&mut self) -> Result<()> {
+        if !self.is_running() {
+            return Ok(());
+        }
+        let _ = tree_kill::force_kill(self.pid);
+        if self.wait_until_exit(FORCE_KILL_BUDGET) {
+            Ok(())
+        } else {
+            Err(LaunchError::Kill {
+                pid: self.pid,
+                source: std::io::Error::other("强制结束后进程仍在运行"),
+            })
+        }
+    }
+
+    fn wait_until_exit(&mut self, budget: Duration) -> bool {
+        let deadline = Instant::now() + budget;
+        loop {
+            match self.child.try_wait() {
+                Ok(Some(_)) => return true,
+                Ok(None) => {}
+                Err(_) => return false,
+            }
+            if Instant::now() >= deadline {
+                return false;
+            }
+            std::thread::sleep(POLL_INTERVAL);
+        }
+    }
+}
+
+/// 从退出状态取整数退出码。
+///
+/// POSIX 上被子进程信号杀死没有 `code()`，按 shell 惯例补 `128 + signal`
+/// （`SIGKILL` → 137、`SIGTERM` → 143，与 `analyse/02` 附录 C 一致）。
+pub fn exit_code(status: &ExitStatus) -> i32 {
+    if let Some(code) = status.code() {
+        return code;
+    }
+    #[cfg(unix)]
+    {
+        use std::os::unix::process::ExitStatusExt;
+        if let Some(signal) = status.signal() {
+            return 128 + signal;
+        }
+    }
+    -1
+}
diff --git a/crates/core/src/launch/pump.rs b/crates/core/src/launch/pump.rs
new file mode 100644
index 0000000..f7fd684
--- /dev/null
+++ b/crates/core/src/launch/pump.rs
@@ -0,0 +1,379 @@
+//! stdout/stderr 泵与日志环形缓冲。
+//!
+//! 平移自 `analyse/02` §6.1/§6.2（`StreamPump` + `ManagedProcess.lines`），并补两处改进：
+//! 缓冲按“行数 + 字节数”双上限（§8.4-9），且命中 `Exception|Error|Caused by|OutOfMemory`
+//! 的关键行**不随环形淘汰**——2000 行截断会把根因行挤掉（§7.10-3）。
+//!
+//! 解码：我们强制给子进程下发 `-Dstdout.encoding=UTF-8`（`-Dsun.stdout.encoding`
+//! for Java <19），因此泵按 UTF-8 宽松解码；用户把编码改成 GBK 时会出现替换字符，
+//! 阶段B 再视需要引入 `encoding_rs`（记录在 `launch-接口约定.md` §7）。
+
+use std::collections::VecDeque;
+use std::io::{BufRead, BufReader, Read};
+use std::process::{ChildStderr, ChildStdout};
+use std::sync::mpsc::{self, Receiver, Sender};
+use std::sync::{Arc, Mutex};
+use std::thread::{self, JoinHandle};
+use std::time::{Duration, Instant};
+
+use crate::launch::log_level;
+
+/// 默认环形缓冲行数（与 HMCL 一致）。
+pub const DEFAULT_MAX_LINES: usize = 2000;
+/// 默认环形缓冲字节上限。
+pub const DEFAULT_MAX_BYTES: usize = 4 * 1024 * 1024;
+/// 单行最大字符数（超出截断并标注，避免单行撑爆事件流）。
+pub const MAX_LINE_CHARS: usize = 8192;
+
+/// 输出流。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Stream {
+    /// 标准输出。
+    Stdout,
+    /// 标准错误。
+    Stderr,
+}
+
+impl Stream {
+    /// 事件流里的字符串形式（`"stdout"` / `"stderr"`）。
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Stdout => "stdout",
+            Self::Stderr => "stderr",
+        }
+    }
+
+    /// 是否标准错误。
+    pub fn is_stderr(self) -> bool {
+        self == Self::Stderr
+    }
+}
+
+/// 一行日志。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct LogLine {
+    /// 来源流。
+    pub stream: Stream,
+    /// 文本（已去行尾、超长已截断）。
+    pub text: String,
+}
+
+impl LogLine {
+    /// 构造。
+    pub fn new(stream: Stream, text: impl Into) -> 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..78b7425
--- /dev/null
+++ b/crates/core/src/launch/redact.rs
@@ -0,0 +1,299 @@
+//! 日志与事件流的脱敏（写入前执行，落盘即脱敏）。
+//!
+//! 规则见 `DevDocs/SubAgentsTalk/launch-接口约定.md` §4：
+//! token 整串替换、用户主目录替换、长度 ≥64 的不透明串（base64/hex token）替换。
+//! 依据 `analyse/02` §6.4 / §8.4-5（HMCL 只过滤 access token，我们要求导出前全量脱敏）。
+//!
+//! 第四条规则（M40 从 `auth::body` 上提）：**带点 token** 整串替换。JWT 形状是
+//! `header.payload.signature`（XSTS/XBL 票据正是这个），点号把连续段切开，单看
+//! 「连续不透明串 ≥64」这条会整串原样放过。规则只在这里实现一份，所有调用方
+//! （launch 会话 / 诊断 / auth 错误摘要 …）共用，避免各自补一套后漂移。
+
+use std::borrow::Cow;
+use std::path::Path;
+
+use serde_json::Value;
+
+/// access token / session token 的替换标记。
+pub const TOKEN_PLACEHOLDER: &str = "";
+/// 用户主目录的替换标记。
+pub const HOME_PLACEHOLDER: &str = "";
+/// 形似 token 的长不透明串的替换标记。
+pub const OPAQUE_PLACEHOLDER: &str = "";
+
+/// 判定“像 token”的最短连续长度。
+const MAX_OPAQUE_RUN: usize = 64;
+/// 「带点 token」（JWT 三段式）判定的最短总长。
+const DOTTED_TOKEN_MIN_TOTAL: usize = 40;
+/// 「带点 token」每一段的最短长度（挡住 `Service.Unavailable.today` 这类正常文案）。
+const DOTTED_TOKEN_MIN_SEGMENT: usize = 8;
+
+/// 脱敏器：持有需要抹掉的敏感值（token、主目录）。
+#[derive(Debug, Clone, Default)]
+pub struct Redactor {
+    secrets: Vec,
+    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 run = 0usize;
+    for ch in text.chars() {
+        if is_opaque_char(ch) {
+            run += 1;
+            if run >= MAX_OPAQUE_RUN {
+                return true;
+            }
+        } else {
+            run = 0;
+        }
+    }
+    false
+}
+
+/// 把长度 ≥64 的不透明串替换成 [`OPAQUE_PLACEHOLDER`]。
+pub fn mask_opaque(text: &str) -> String {
+    let mut out = String::with_capacity(text.len());
+    let mut run_start: Option = None;
+    for (idx, ch) in text.char_indices() {
+        if is_opaque_char(ch) {
+            if run_start.is_none() {
+                run_start = Some(idx);
+            }
+        } else {
+            if let Some(start) = run_start.take() {
+                push_masked(&mut out, &text[start..idx]);
+            }
+            out.push(ch);
+        }
+    }
+    if let Some(start) = run_start {
+        push_masked(&mut out, &text[start..]);
+    }
+    out
+}
+
+fn push_masked(out: &mut String, run: &str) {
+    if run.len() >= MAX_OPAQUE_RUN {
+        out.push_str(OPAQUE_PLACEHOLDER);
+    } else {
+        out.push_str(run);
+    }
+}
+
+fn is_opaque_char(ch: char) -> bool {
+    ch.is_ascii_alphanumeric() || matches!(ch, '+' | '/' | '=' | '_' | '-')
+}
+
+/// 文本里是否含「带点 token」（≥3 段、每段 ≥8、总长 ≥40）。
+pub fn has_dotted_token(text: &str) -> bool {
+    let mut start: Option = None;
+    for (idx, ch) in text.char_indices() {
+        if is_dotted_token_char(ch) {
+            start.get_or_insert(idx);
+            continue;
+        }
+        if let Some(from) = start.take() {
+            if is_dotted_token(&text[from..idx]) {
+                return true;
+            }
+        }
+    }
+    start.is_some_and(|from| is_dotted_token(&text[from..]))
+}
+
+/// 把「带点 token」整串替换成 [`TOKEN_PLACEHOLDER`]（段外文本原样保留）。
+pub fn mask_dotted_tokens(text: &str) -> String {
+    let mut out = String::with_capacity(text.len());
+    let mut start: Option = None;
+    for (idx, ch) in text.char_indices() {
+        if is_dotted_token_char(ch) {
+            start.get_or_insert(idx);
+            continue;
+        }
+        if let Some(from) = start.take() {
+            push_dotted(&mut out, &text[from..idx]);
+        }
+        out.push(ch);
+    }
+    if let Some(from) = start {
+        push_dotted(&mut out, &text[from..]);
+    }
+    out
+}
+
+fn push_dotted(out: &mut String, run: &str) {
+    if is_dotted_token(run) {
+        out.push_str(TOKEN_PLACEHOLDER);
+    } else {
+        out.push_str(run);
+    }
+}
+
+/// 「带点 token」的字符集：比不透明串多一个 `.`（JWT 的分段符）。
+fn is_dotted_token_char(ch: char) -> bool {
+    is_opaque_char(ch) || ch == '.'
+}
+
+/// 单段连写（无空白）的串是否像 JWT：段数 ≥3、每段 ≥8 字节、总长 ≥40。
+fn is_dotted_token(run: &str) -> bool {
+    run.len() >= DOTTED_TOKEN_MIN_TOTAL
+        && run.split('.').count() >= 3
+        && run
+            .split('.')
+            .all(|segment| segment.len() >= DOTTED_TOKEN_MIN_SEGMENT)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// 真实形状的 JWT（header.payload.signature，三段各 ≥8）。
+    const JWT: &str = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.c2lnbmF0dXJlLXZhbHVlLXRoYXQtaXMtbG9uZy1lbm91Z2g";
+
+    #[test]
+    fn jwt_token_is_masked_without_any_registered_secret() {
+        let scrubbed = Redactor::new().scrub(JWT).into_owned();
+        assert!(scrubbed.contains(TOKEN_PLACEHOLDER), "{scrubbed}");
+        assert!(!scrubbed.contains("eyJhbGci"), "{scrubbed}");
+
+        // 嵌在别的内容里也只换 token 本体。
+        let masked = Redactor::new()
+            .scrub(&format!("authorization: Bearer {JWT}, retry=1"))
+            .into_owned();
+        assert_eq!(
+            masked,
+            format!("authorization: Bearer {TOKEN_PLACEHOLDER}, retry=1")
+        );
+    }
+
+    #[test]
+    fn dotted_token_rule_does_not_eat_normal_text() {
+        // 分段太短、总长不够、段数不够：三种都不算 token。
+        for text in [
+            "Service.Unavailable.today",
+            "1.2.0",
+            "xbl.xsts.entitlements.profile",
+            "eyJhbGciOiJIUzI1NiJ9.short.abc",
+        ] {
+            assert!(!has_dotted_token(text), "{text}");
+            assert_eq!(Redactor::new().scrub(text), text, "{text}");
+        }
+    }
+
+    #[test]
+    fn existing_rules_still_apply() {
+        let redactor = Redactor::new()
+            .with_secret("SECRET-TOKEN-123456")
+            .with_home_str("/home/alice");
+        let scrubbed = redactor
+            .scrub("/home/alice/game.log: token=SECRET-TOKEN-123456")
+            .into_owned();
+        assert!(scrubbed.contains(HOME_PLACEHOLDER), "{scrubbed}");
+        assert!(scrubbed.contains(TOKEN_PLACEHOLDER), "{scrubbed}");
+        assert!(
+            !scrubbed.contains("alice") && !scrubbed.contains("SECRET"),
+            "{scrubbed}"
+        );
+
+        // 没有点号的长不透明串仍走 ≥64 规则，替换标记也不同。
+        let long = "A".repeat(MAX_OPAQUE_RUN);
+        assert!(has_opaque_run(&long));
+        assert!(!has_dotted_token(&long));
+        assert_eq!(
+            Redactor::new().scrub(&long).into_owned(),
+            OPAQUE_PLACEHOLDER.to_string()
+        );
+    }
+}
diff --git a/crates/core/src/launch/request.rs b/crates/core/src/launch/request.rs
new file mode 100644
index 0000000..6a4f54d
--- /dev/null
+++ b/crates/core/src/launch/request.rs
@@ -0,0 +1,358 @@
+//! 启动请求：命令行组装的输入模型（纯数据，无 IO，便于快照测试）。
+//!
+//! 与 `crate::game` / `crate::download` 的映射关系见
+//! `DevDocs/SubAgentsTalk/launch-接口约定.md` §6：launch 阶段只消费本结构，
+//! 由薄适配层把 game 的快照搬进来，避免 launch 对 manifest 类型产生编译期依赖。
+
+use std::path::PathBuf;
+
+use crate::launch::argument::ArgumentEntry;
+use crate::launch::error::MissingComponent;
+use crate::launch::game_version::GameVersion;
+use crate::launch::natives::NativesPlan;
+
+/// 实例信息。
+#[derive(Debug, Clone, Default)]
+pub struct InstanceInfo {
+    /// 实例/版本 id（稳定 UUID 或版本目录名）。
+    pub id: String,
+    /// 展示名（`${version_name}`）。
+    pub name: String,
+    /// 游戏版本号（分支门限用）。
+    pub version: GameVersion,
+    /// 版本类型（`release` / `snapshot`；`${version_type}`）。
+    pub version_type: String,
+}
+
+/// 启动器自身信息（`${launcher_name}` / `${launcher_version}`）。
+#[derive(Debug, Clone, Default)]
+pub struct LauncherInfo {
+    /// 名称。
+    pub name: String,
+    /// 版本。
+    pub version: String,
+}
+
+/// 选定的 Java 运行时。
+#[derive(Debug, Clone, Default)]
+pub struct JavaSelection {
+    /// `java` 可执行文件路径。
+    pub binary: PathBuf,
+    /// 主版本号（8 / 17 / 21 / 25 …）。
+    pub major: u32,
+    /// 位数（32 / 64）。
+    pub bits: u32,
+}
+
+impl JavaSelection {
+    /// 构造。
+    pub fn new(binary: impl Into, 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` 为分类器构件清单）。
+    ///
+    /// 解压发生在**组装期**（`Launcher::dry_run`/`spawn` 的「环境准备」段），
+    /// 见 [`crate::launch::natives`] 与 `SubAgentsTalk/launch-natives-解压与时代分界.md`。
+    pub natives: NativesPlan,
+    /// 账户。
+    pub auth: AuthPlaceholders,
+    /// 用户参数。
+    pub user: UserArgs,
+    /// 特性开关。
+    pub features: FeatureSet,
+    /// 分辨率（`None` 表示不指定）。
+    pub resolution: Option,
+    /// 一键进入。
+    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..54c4989
--- /dev/null
+++ b/crates/core/src/launch/session.rs
@@ -0,0 +1,375 @@
+//! 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 产出、由本模块落盘。
+
+use std::fs::{self, File, OpenOptions};
+use std::io::{BufWriter, Write};
+use std::path::{Path, PathBuf};
+
+use serde::Serialize;
+use serde_json::Value;
+
+use crate::launch::args_table::AssembledCommand;
+use crate::launch::error::{AssemblyError, LaunchError, Result};
+use crate::launch::exit_analysis::ExitAnalysis;
+use crate::launch::natives::NativesReport;
+use crate::launch::pump::{LogLine, Stream};
+use crate::launch::redact::Redactor;
+use crate::launch::session_index::{self, SessionIndexEntry};
+use crate::launch::session_payload as payload;
+use crate::launch::time::{self, SessionClock};
+use crate::launch::window_detect::Detection;
+
+/// 事件 schema 版本。
+pub const SCHEMA_VERSION: u8 = 1;
+
+/// 事件类型。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum EventKind {
+    /// 会话开始。
+    SessionStart,
+    /// Java 选择结果。
+    JavaSelected,
+    /// 命令行组装完成。
+    CmdBuilt,
+    /// natives 解压结果。
+    NativesExtracted,
+    /// 启动前失败（没有进程）。
+    AssemblyFailed,
+    /// 进程已启动。
+    ProcStart,
+    /// stdout 行。
+    Stdout,
+    /// stderr 行。
+    Stderr,
+    /// 检测到游戏窗口。
+    WindowDetected,
+    /// 进程退出。
+    Exit,
+    /// 发现崩溃报告 / hs_err。
+    CrashFound,
+    /// 诊断结论（M15 产出）。
+    Diagnosis,
+    /// 被主动结束。
+    Killed,
+    /// 会话结束。
+    SessionEnd,
+}
+
+impl EventKind {
+    /// JSONL 里的 `kind` 字符串。
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::SessionStart => "session_start",
+            Self::JavaSelected => "java_selected",
+            Self::CmdBuilt => "cmd_built",
+            Self::NativesExtracted => "natives_extracted",
+            Self::AssemblyFailed => "assembly_failed",
+            Self::ProcStart => "proc_start",
+            Self::Stdout => "stdout",
+            Self::Stderr => "stderr",
+            Self::WindowDetected => "window_detected",
+            Self::Exit => "exit",
+            Self::CrashFound => "crash_found",
+            Self::Diagnosis => "diagnosis",
+            Self::Killed => "killed",
+            Self::SessionEnd => "session_end",
+        }
+    }
+}
+
+/// 会话结束原因。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum EndReason {
+    /// 进程自然退出。
+    Exit,
+    /// 被主动结束。
+    Killed,
+    /// 启动前失败（组装/组件检查）。
+    AssemblyFailed,
+    /// 进程派生失败。
+    SpawnFailed,
+}
+
+impl EndReason {
+    /// JSONL 里的 `reason` 字符串。
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Exit => "exit",
+            Self::Killed => "killed",
+            Self::AssemblyFailed => "assembly_failed",
+            Self::SpawnFailed => "spawn_failed",
+        }
+    }
+}
+
+pub use crate::launch::session_meta::SessionMeta;
+pub use crate::launch::session_sink::SessionSink;
+
+#[derive(Serialize)]
+struct EventLine<'a> {
+    v: u8,
+    seq: u64,
+    ts: String,
+    t_ms: u64,
+    kind: &'a str,
+    session_id: &'a str,
+    payload: &'a Value,
+}
+
+/// 会话事件流写入器。
+#[derive(Debug)]
+pub struct SessionWriter {
+    session_id: String,
+    clock: SessionClock,
+    file: BufWriter,
+    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,
+    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,
+            finished: false,
+        })
+    }
+
+    /// 会话 id。
+    pub fn session_id(&self) -> &str {
+        &self.session_id
+    }
+
+    /// 事件文件路径。
+    pub fn path(&self) -> &Path {
+        &self.path
+    }
+
+    /// 已写入事件数。
+    pub fn event_count(&self) -> u64 {
+        self.event_count
+    }
+
+    /// 是否已结束。
+    pub fn is_finished(&self) -> bool {
+        self.finished
+    }
+
+    /// 写一条事件。
+    pub fn record(&mut self, kind: EventKind, payload: Value) -> Result<()> {
+        let seq = self.seq;
+        let line = EventLine {
+            v: SCHEMA_VERSION,
+            seq,
+            ts: self.clock.now_iso(),
+            t_ms: self.clock.elapsed_ms(),
+            kind: kind.as_str(),
+            session_id: &self.session_id,
+            payload: &payload,
+        };
+        let serialized = serde_json::to_string(&line).map_err(|err| LaunchError::Session {
+            path: self.path.clone(),
+            reason: err.to_string(),
+        })?;
+        self.file
+            .write_all(serialized.as_bytes())
+            .and_then(|()| self.file.write_all(b"\n"))
+            .and_then(|()| self.file.flush())
+            .map_err(|source| LaunchError::Io {
+                op: "write_session_event",
+                path: self.path.clone(),
+                source,
+            })?;
+        self.seq += 1;
+        self.event_count += 1;
+        Ok(())
+    }
+
+    /// `session_start`。
+    pub fn session_start(&mut self) -> Result<()> {
+        let payload = payload::session_start(&self.meta, SCHEMA_VERSION);
+        self.record(EventKind::SessionStart, payload)
+    }
+
+    /// `cmd_built`：完整 argv（已脱敏）+ classpath 摘要。
+    pub fn cmd_built(&mut self, command: &AssembledCommand) -> Result<()> {
+        let payload = payload::cmd_built(command, &self.redactor);
+        self.record(EventKind::CmdBuilt, payload)
+    }
+
+    /// `assembly_failed`：启动前失败，附结构化缺失清单（M15 据此下结论）。
+    pub fn assembly_failed(&mut self, error: &AssemblyError) -> Result<()> {
+        let payload = payload::assembly_failed(error);
+        self.record(EventKind::AssemblyFailed, payload)
+    }
+
+    /// `proc_start`。
+    pub fn proc_start(&mut self, pid: u32) -> Result<()> {
+        let payload = payload::proc_start(pid, &self.clock.now_iso());
+        self.record(EventKind::ProcStart, payload)
+    }
+
+    /// `natives_extracted`：natives 解压结果（启动期 `UnsatisfiedLinkError` 的第一嫌疑）。
+    pub fn natives_extracted(&mut self, report: &NativesReport) -> Result<()> {
+        let payload = payload::natives_extracted(report, &self.redactor);
+        self.record(EventKind::NativesExtracted, payload)
+    }
+
+    /// `stdout` / `stderr` 行事件。
+    pub fn line(&mut self, line: &LogLine) -> Result<()> {
+        let kind = match line.stream {
+            Stream::Stdout => EventKind::Stdout,
+            Stream::Stderr => EventKind::Stderr,
+        };
+        let text = self.redactor.scrub(&line.text).into_owned();
+        let payload = payload::log_line(&text, line.level());
+        self.record(kind, payload)
+    }
+
+    /// `window_detected`。
+    pub fn window_detected(&mut self, detection: &Detection) -> Result<()> {
+        self.window_detected = true;
+        let payload = payload::window_detected(detection, &self.redactor);
+        self.record(EventKind::WindowDetected, payload)
+    }
+
+    /// 是否已检测到游戏窗口（索引摘要用）。
+    pub fn is_window_detected(&self) -> bool {
+        self.window_detected
+    }
+
+    /// `killed`。
+    pub fn killed(&mut self, by: &str, signal: Option<&str>) -> Result<()> {
+        let payload = payload::killed(by, signal);
+        self.record(EventKind::Killed, payload)
+    }
+
+    /// `exit`。
+    pub fn exit(&mut self, analysis: &ExitAnalysis) -> Result<()> {
+        self.exit_code = Some(analysis.code);
+        self.exit_type = Some(analysis.exit_type.as_str().to_string());
+        self.silent_failure = analysis.silent_failure.is_some();
+        let payload = payload::exit(analysis);
+        self.record(EventKind::Exit, payload)
+    }
+
+    /// `crash_found`：以 `path` 为权威字段（M15 自己读盘）。
+    pub fn crash_found(&mut self, source: &str, path: &Path, excerpt: Option<&str>) -> Result<()> {
+        self.crash_found = true;
+        let payload = payload::crash_found(source, path, excerpt, &self.redactor);
+        self.record(EventKind::CrashFound, payload)
+    }
+
+    /// `diagnosis`：M15 产出的结构化结论，由 launch 脱敏后落盘（单一真相源）。
+    ///
+    /// M15 会按 `crash_found.path` 自己读盘再组 payload，崩溃报告/`latest.log` 里的
+    /// 用户主目录路径与 token 会由此带进结论，所以这里必须再过一遍 [`Redactor`]
+    /// （只改字符串，字段名/数值/布尔不动——`launch-接口约定.md` §9.3）。
+    pub fn diagnosis(&mut self, record: Value) -> Result<()> {
+        let record = self.redactor.scrub_json(&record);
+        if self.diagnosis_top.is_none() {
+            self.diagnosis_top = record
+                .get("candidates")
+                .and_then(Value::as_array)
+                .and_then(|items| items.first())
+                .and_then(|item| item.get("id"))
+                .and_then(Value::as_str)
+                .map(str::to_string);
+        }
+        self.record(EventKind::Diagnosis, record)
+    }
+
+    /// `session_end` + 追加索引，返回索引条目。
+    pub fn finish(&mut self, reason: EndReason) -> Result {
+        let duration_ms = self.clock.elapsed_ms();
+        let payload = payload::session_end(reason.as_str(), duration_ms);
+        self.record(EventKind::SessionEnd, payload)?;
+        self.finished = true;
+        let entry = SessionIndexEntry {
+            v: SCHEMA_VERSION,
+            session_id: self.session_id.clone(),
+            instance_id: self.meta.instance_id.clone(),
+            instance_name: self.meta.instance_name.clone(),
+            game_version: self.meta.game_version.clone(),
+            started_at: self.started_at.clone(),
+            ended_at: self.clock.now_iso(),
+            duration_ms,
+            exit_code: self.exit_code,
+            exit_type: self.exit_type.clone(),
+            silent_failure: self.silent_failure,
+            window_detected: self.window_detected,
+            event_count: self.event_count,
+            log_path: format!("game/{}.jsonl", self.session_id),
+            crash_found: self.crash_found,
+            diagnosis_top: self.diagnosis_top.clone(),
+        };
+        session_index::append(&self.index_path, &entry).map_err(|source| LaunchError::Io {
+            op: "append_session_index",
+            path: self.index_path.clone(),
+            source,
+        })?;
+        Ok(entry)
+    }
+}
diff --git a/crates/core/src/launch/session_index.rs b/crates/core/src/launch/session_index.rs
new file mode 100644
index 0000000..4dfc47d
--- /dev/null
+++ b/crates/core/src/launch/session_index.rs
@@ -0,0 +1,120 @@
+//! 会话记录索引：`list_game_sessions` 的数据源。
+//!
+//! 文件：`/game/index.jsonl`，每会话一行摘要，会话结束时追加。
+//! 读取约定（`DevDocs/SubAgentsTalk/launch-接口约定.md` §2）：同一 `session_id`
+//! 可能出现多行（崩溃后重写索引），读取方**按 id 去重取最后一行**，再按 `started_at` 倒序。
+
+use std::fs::{File, OpenOptions};
+use std::io::{BufRead, BufReader, Write};
+use std::path::{Path, PathBuf};
+
+use serde::{Deserialize, Serialize};
+
+/// 索引条目的 schema 版本。
+pub const INDEX_VERSION: u8 = 1;
+
+/// 一次会话的摘要。
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct SessionIndexEntry {
+    /// schema 版本。
+    #[serde(default)]
+    pub v: u8,
+    /// 会话 id。
+    pub session_id: String,
+    /// 实例 id。
+    pub instance_id: String,
+    /// 实例名。
+    pub instance_name: String,
+    /// 游戏版本。
+    pub game_version: String,
+    /// 开始时间（RFC3339 UTC）。
+    pub started_at: String,
+    /// 结束时间（RFC3339 UTC）。
+    pub ended_at: String,
+    /// 时长毫秒。
+    pub duration_ms: u64,
+    /// 退出码（未跑到进程时为 `None`）。
+    pub exit_code: Option,
+    /// 退出判定字符串。
+    pub exit_type: Option,
+    /// 是否静默失败。
+    pub silent_failure: bool,
+    /// 是否检测到游戏窗口。
+    pub window_detected: bool,
+    /// 事件条数。
+    pub event_count: u64,
+    /// 相对 `game/` 的日志文件名。
+    pub log_path: String,
+    /// 是否抓到崩溃报告/hs_err。
+    pub crash_found: bool,
+    /// 诊断首因（M15 写入的第一个候选 id）。
+    pub diagnosis_top: Option,
+}
+
+/// 索引文件路径（`/game/index.jsonl`）。
+pub fn index_path(sessions_root: &Path) -> PathBuf {
+    sessions_root.join("game").join("index.jsonl")
+}
+
+/// 追加一行摘要。
+pub fn append(index: &Path, entry: &SessionIndexEntry) -> std::io::Result<()> {
+    if let Some(parent) = index.parent() {
+        std::fs::create_dir_all(parent)?;
+    }
+    let mut file = OpenOptions::new().create(true).append(true).open(index)?;
+    let line = serde_json::to_string(entry)
+        .map_err(|err| std::io::Error::other(format!("序列化索引失败：{err}")))?;
+    file.write_all(line.as_bytes())?;
+    file.write_all(b"\n")?;
+    file.flush()
+}
+
+/// 读取全部条目（同一 id 取最后一行，按开始时间倒序）。
+pub fn read_all(index: &Path) -> std::io::Result> {
+    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_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..712b28e
--- /dev/null
+++ b/crates/core/src/launch/session_sink.rs
@@ -0,0 +1,64 @@
+//! 把会话事件流接到日志泵上：逐行落盘 + 自动窗口出现检测。
+//!
+//! 放在单独文件是为了让 [`crate::launch::session`] 保持“只写事件、只管索引”的单一职责，
+//! 也避免单文件超过 400 行的硬约束。
+
+use std::sync::Mutex;
+
+use crate::launch::pump::{LineSink, LogLine};
+use crate::launch::session::SessionWriter;
+use crate::launch::window_detect::WindowDetector;
+
+/// 会话日志 sink。
+#[derive(Debug)]
+pub struct SessionSink {
+    writer: Mutex,
+    detector: Mutex,
+}
+
+impl SessionSink {
+    /// 以进程启动时刻为窗口检测起点。
+    pub fn new(writer: SessionWriter) -> Self {
+        Self {
+            writer: Mutex::new(writer),
+            detector: Mutex::new(WindowDetector::new()),
+        }
+    }
+
+    /// 指定窗口检测计时起点（进程 spawn 时刻）。
+    pub fn with_start(writer: SessionWriter, started_at: std::time::Instant) -> Self {
+        Self {
+            writer: Mutex::new(writer),
+            detector: Mutex::new(WindowDetector::with_start(started_at)),
+        }
+    }
+
+    /// 借用写入器（退出分析、结束会话等需要可变访问的场合）。
+    pub fn with_writer(&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,
+        }
+    }
+}
+
+impl LineSink for SessionSink {
+    fn on_line(&self, line: &LogLine) {
+        let detection = match self.detector.lock() {
+            Ok(mut detector) => detector.observe(&line.text),
+            Err(_) => None,
+        };
+        let Ok(mut writer) = self.writer.lock() else {
+            return;
+        };
+        if let Some(detection) = detection {
+            let _ = writer.window_detected(&detection);
+        }
+        let _ = writer.line(line);
+    }
+}
diff --git a/crates/core/src/launch/sink.rs b/crates/core/src/launch/sink.rs
new file mode 100644
index 0000000..8b5809a
--- /dev/null
+++ b/crates/core/src/launch/sink.rs
@@ -0,0 +1,138 @@
+//! 日志 sink 组合：把同一个进程的输出同时喂给多个消费者。
+//!
+//! 设计依据 `DevDocs/SubAgentsTalk/launch-接口约定.md` §3（单一真相源）与 tower 批复的
+//! “复合 sink”方案：会话事件流（落盘）是必需的一个 sink，M15 采集器 / UI 日志页 /
+//! 测试断言各自挂自己的 sink，彼此不感知。
+//!
+//! 接 M15 的姿态：diagnose 不解析 jsonl、也不 import launch 类型，所以它只需要一个
+//! `FnSink` 包一层 `LogBuffer::push(stream, line)`；这里只提供通用的组合原语。
+
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::Arc;
+
+use crate::launch::pump::{LineSink, LogLine, Stream};
+
+/// 把一条日志广播给多个 sink（顺序 = 注册顺序）。
+#[derive(Default)]
+pub struct CompositeSink {
+    sinks: Vec>,
+}
+
+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/time.rs b/crates/core/src/launch/time.rs
new file mode 100644
index 0000000..39f1ead
--- /dev/null
+++ b/crates/core/src/launch/time.rs
@@ -0,0 +1,118 @@
+//! 时间工具：RFC3339（毫秒，UTC）格式化与会话时钟。
+//!
+//! 会话事件流的 `ts` / `t_ms` 字段由这里产出（schema 见
+//! `DevDocs/SubAgentsTalk/launch-接口约定.md` §2）。
+//! 只用 `std::time`，不引入 chrono/time 依赖。
+
+use std::time::{Instant, SystemTime, UNIX_EPOCH};
+
+/// 把 `SystemTime` 格式化成 RFC3339 UTC 毫秒精度串，例 `2026-10-29T12:45:01.123Z`。
+///
+/// 早于 Unix 纪元的时间按纪元处理（不会 panic：事件流宁可有 1970 的时间戳也不能丢事件）。
+pub fn format_rfc3339_millis(time: SystemTime) -> String {
+    let since_epoch = time.duration_since(UNIX_EPOCH).unwrap_or_default();
+    let secs = since_epoch.as_secs();
+    let millis = since_epoch.subsec_millis();
+    let days = i64::try_from(secs / 86_400).unwrap_or(i64::MAX);
+    let secs_of_day = secs % 86_400;
+    let (year, month, day) = civil_from_days(days);
+    let hour = secs_of_day / 3_600;
+    let minute = (secs_of_day % 3_600) / 60;
+    let second = secs_of_day % 60;
+    format!("{year:04}-{month:02}-{day:02}T{hour:02}:{minute:02}:{second:02}.{millis:03}Z")
+}
+
+/// 当前墙上时间（便于测试替换的单一入口）。
+pub fn now() -> SystemTime {
+    SystemTime::now()
+}
+
+/// 由“自 1970-01-01 起的天数”还原公历年月日（Howard Hinnant 的 civil_from_days）。
+pub fn civil_from_days(days: i64) -> (i64, u32, u32) {
+    let z = days + 719_468;
+    let era = if z >= 0 { z } else { z - 146_096 } / 146_097;
+    let doe = z - era * 146_097;
+    let yoe = (doe - doe / 1_460 + doe / 36_524 - doe / 146_096) / 365;
+    let year = yoe + era * 400;
+    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
+    let mp = (5 * doy + 2) / 153;
+    let day = doy - (153 * mp + 2) / 5 + 1;
+    let month = if mp < 10 { mp + 3 } else { mp - 9 };
+    let year = if month <= 2 { year + 1 } else { year };
+    (
+        year,
+        u32::try_from(month).unwrap_or(1),
+        u32::try_from(day).unwrap_or(1),
+    )
+}
+
+/// 会话时钟：同时记录单调时刻（`t_ms`）与墙上时刻（`ts`）。
+#[derive(Debug, Clone)]
+pub struct SessionClock {
+    start_instant: Instant,
+    started_at: SystemTime,
+}
+
+impl SessionClock {
+    /// 以“现在”为起点创建时钟。
+    pub fn start_new() -> Self {
+        Self {
+            start_instant: Instant::now(),
+            started_at: now(),
+        }
+    }
+
+    /// 用给定的墙上时间与单调时刻创建（测试可注入）。
+    pub fn started_at(start_instant: Instant, started_at: SystemTime) -> Self {
+        Self {
+            start_instant,
+            started_at,
+        }
+    }
+
+    /// 会话开始的墙上时间。
+    pub fn started_at_wall(&self) -> SystemTime {
+        self.started_at
+    }
+
+    /// 会话开始时刻的 RFC3339 串。
+    pub fn started_at_iso(&self) -> String {
+        format_rfc3339_millis(self.started_at)
+    }
+
+    /// 距会话开始的毫秒数（`t_ms`）。
+    pub fn elapsed_ms(&self) -> u64 {
+        u64::try_from(self.start_instant.elapsed().as_millis()).unwrap_or(u64::MAX)
+    }
+
+    /// 当前墙上时间的 RFC3339 串（`ts`）。
+    pub fn now_iso(&self) -> String {
+        format_rfc3339_millis(now())
+    }
+}
+
+impl Default for SessionClock {
+    fn default() -> Self {
+        Self::start_new()
+    }
+}
+
+/// 生成会话 id：`YYYYMMDDTHHMMSS-<6 位十六进制>`。
+///
+/// 十六进制段由墙上时间与 pid 混合而来——不引入 rand 依赖，同一秒同一进程内也能区分
+/// （调用方可在冲突时追加序号）。
+pub fn make_session_id(wall: SystemTime, pid: u32) -> String {
+    let since_epoch = wall.duration_since(UNIX_EPOCH).unwrap_or_default();
+    let secs = since_epoch.as_secs();
+    let days = i64::try_from(secs / 86_400).unwrap_or(i64::MAX);
+    let (year, month, day) = civil_from_days(days);
+    let secs_of_day = secs % 86_400;
+    let hour = secs_of_day / 3_600;
+    let minute = (secs_of_day % 3_600) / 60;
+    let second = secs_of_day % 60;
+    let mut hash: u64 = u64::from(since_epoch.subsec_nanos()).wrapping_add(u64::from(pid));
+    hash ^= secs.rotate_left(17);
+    hash = hash.wrapping_mul(0x9E37_79B9_7F4A_7C15);
+    let suffix = (hash >> 40) & 0xFF_FFFF;
+    format!("{year:04}{month:02}{day:02}T{hour:02}{minute:02}{second:02}-{suffix:06x}")
+}
diff --git a/crates/core/src/launch/tree_kill.rs b/crates/core/src/launch/tree_kill.rs
new file mode 100644
index 0000000..278a0ba
--- /dev/null
+++ b/crates/core/src/launch/tree_kill.rs
@@ -0,0 +1,195 @@
+//! 进程树回收：`SIGTERM → 宽限 → SIGKILL` 三段式关闭。
+//!
+//! HMCL 只 `process.destroy()` 单进程（`analyse/02` §6.8），子进程会残留、日志尾部丢失。
+//! 这里做进程**树**回收：
+//!
+//! - Windows：`taskkill /T /F /PID`（`/T` 递归子树）。P0 不引入 `windows-sys`，因此没有
+//!   Job Object——Job Object（`JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE`）留 P1，替换点就在本文件
+//!   （tower 已批准，见 `launch-接口约定.md` §7-1）。
+//! - POSIX：子进程由 [`crate::launch::process`] 用 `CommandExt::process_group(0)` 放进**自己的**
+//!   进程组（与 Windows 的 `CREATE_NEW_PROCESS_GROUP` 对称，std 1.64+ 的安全 API），因此
+//!   `kill -TERM -- -` 一次覆盖整棵子树 → 宽限 → `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` 轮询），本模块只提供发送动作。
+
+use std::io;
+use std::process::Command;
+
+/// 温和关闭（Windows 无 `/F`；POSIX `SIGTERM`）。
+pub fn terminate(pid: u32) -> io::Result<()> {
+    check_pid(pid)?;
+    imp::signal(pid, false)
+}
+
+/// 强制关闭（Windows `/F`；POSIX `SIGKILL`），并尽量覆盖整棵进程树。
+pub fn force_kill(pid: u32) -> io::Result<()> {
+    check_pid(pid)?;
+    imp::signal(pid, true)
+}
+
+/// 三段式：温和 → 宽限 → 强制。返回**强制阶段**的结果（温和阶段失败不致命）。
+///
+/// 注意：返回值不代表“进程已经死了”（见模块注释）。需要准确判定请用
+/// [`crate::launch::process::RunningProcess::stop`]。
+pub fn kill_tree(pid: u32, grace: std::time::Duration) -> io::Result<()> {
+    check_pid(pid)?;
+    let _ = terminate(pid);
+    if !grace.is_zero() {
+        std::thread::sleep(grace);
+    }
+    force_kill(pid)
+}
+
+/// `pid` 0 意味着“当前进程组”（POSIX `kill` 的 `-0`）——绝不能顺手发出去。
+fn check_pid(pid: u32) -> io::Result<()> {
+    if pid == 0 {
+        return Err(io::Error::new(
+            io::ErrorKind::InvalidInput,
+            "无效的 pid 0：拒绝向当前进程组发信号",
+        ));
+    }
+    Ok(())
+}
+
+/// 允许组杀的进程组号；`None` = 只能发单 pid。
+///
+/// 三重校验，任一不过就退回单 pid：
+/// 1. 目标必须是它自己进程组的组长（`pgid == pid`）——否则 `-` 指的不是“它的”子树；
+/// 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 = Command::new("ps")
+        .args(["-o", "pgid=", "-p", &pid.to_string()])
+        .output()
+        .ok()?;
+    if !output.status.success() {
+        return None;
+    }
+    String::from_utf8_lossy(&output.stdout).trim().parse().ok()
+}
+
+#[cfg(windows)]
+mod imp {
+    use super::*;
+    use std::os::windows::process::CommandExt;
+
+    /// 不弹控制台窗口（否则 kill 子进程会闪一个黑框）。
+    const CREATE_NO_WINDOW: u32 = 0x0800_0000;
+
+    pub(super) fn signal(pid: u32, force: bool) -> io::Result<()> {
+        let mut command = Command::new("taskkill");
+        command.arg("/PID").arg(pid.to_string()).arg("/T");
+        if force {
+            command.arg("/F");
+        }
+        command.creation_flags(CREATE_NO_WINDOW);
+        let status = command
+            .stdout(std::process::Stdio::null())
+            .stderr(std::process::Stdio::null())
+            .status()?;
+        if status.success() {
+            Ok(())
+        } else {
+            // taskkill 对已退出的进程返回非 0，这不值得中断关闭流程。
+            Err(io::Error::other(format!("taskkill 退出码 {status}")))
+        }
+    }
+}
+
+#[cfg(unix)]
+mod imp {
+    use super::*;
+
+    pub(super) fn signal(pid: u32, force: bool) -> io::Result<()> {
+        let flag = if force { "-KILL" } else { "-TERM" };
+        let mut delivered = false;
+        // 验过的独立进程组：一次覆盖组长 + 它的全部后代。
+        if let Some(pgid) = group_kill_target(pid) {
+            let group = format!("-{pgid}");
+            delivered |= run_kill(flag, &["--", &group])?;
+        }
+        // 单 pid 兜底永远执行：组杀不可用/进程已不在组里时靠它。
+        let single = pid.to_string();
+        delivered |= run_kill(flag, &[&single])?;
+        if delivered {
+            Ok(())
+        } else {
+            // 常见于“进程已经退出”，不值得中断关闭流程；但绝不谎报成功。
+            Err(io::Error::other(format!(
+                "kill {flag} {pid} 没有送达（进程可能已退出）"
+            )))
+        }
+    }
+
+    /// 发一发 `kill  `，返回是否送达。
+    ///
+    /// `kill` 不存在时给**明确**错误而不是静默失败：否则调用方只会看到“进程仍在运行”，
+    /// 排查方向会被带偏（M48 之前的红灯就是这么来的）。
+    fn run_kill(flag: &str, args: &[&str]) -> io::Result {
+        match Command::new("kill")
+            .arg(flag)
+            .args(args)
+            .stdout(std::process::Stdio::null())
+            .stderr(std::process::Stdio::null())
+            .status()
+        {
+            Ok(status) => Ok(status.success()),
+            Err(err) if err.kind() == io::ErrorKind::NotFound => Err(io::Error::new(
+                io::ErrorKind::NotFound,
+                "找不到 kill 命令：POSIX 进程树回收依赖 procps（Linux）或系统自带 kill（macOS/BSD）",
+            )),
+            Err(err) => Err(err),
+        }
+    }
+}
+
+#[cfg(not(any(windows, unix)))]
+mod imp {
+    use super::*;
+
+    pub(super) fn signal(_pid: u32, _force: bool) -> io::Result<()> {
+        Err(io::Error::other("当前平台不支持进程树 kill"))
+    }
+}
diff --git a/crates/core/src/launch/watchdog.rs b/crates/core/src/launch/watchdog.rs
new file mode 100644
index 0000000..745ef53
--- /dev/null
+++ b/crates/core/src/launch/watchdog.rs
@@ -0,0 +1,71 @@
+//! 看门狗：给 pump 的 join 加超时。
+//!
+//! HMCL 的 `ExitWaiter` 在 `waitFor()` 之后无条件 `join` 两条泵线程
+//! （`analyse/02` §6.1、§8.5）：若子进程自己不关闭 stdout（例如它又拉起了不退出的
+//! 子进程），`onExit` 永远不回调，UI 卡在“正在启动”。这里把“等日志落盘”改成
+//! 有预算的等待——超时就带着已收集到的日志继续做退出分析，绝不无限等待。
+
+use std::time::Duration;
+
+use crate::launch::pump::{PumpCompletion, PumpGroup, Stream};
+
+/// 看门狗配置。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct WatchdogConfig {
+    /// 进程退出后等待日志泵结束的预算。
+    pub pump_timeout: Duration,
+}
+
+impl Default for WatchdogConfig {
+    fn default() -> Self {
+        Self {
+            pump_timeout: Duration::from_secs(10),
+        }
+    }
+}
+
+/// 看门狗判定。
+#[derive(Debug, Clone)]
+pub enum PumpVerdict {
+    /// 两条流都正常结束。
+    Complete(PumpCompletion),
+    /// 超时：仍有流未结束（附带是哪几条）。
+    Stalled {
+        /// 等待结果（含已完成流与行数）。
+        completion: PumpCompletion,
+        /// 卡住的流。
+        streams: Vec,
+        /// 等待了多久。
+        waited: Duration,
+    },
+}
+
+impl PumpVerdict {
+    /// 是否一切正常。
+    pub fn is_complete(&self) -> bool {
+        matches!(self, Self::Complete(_))
+    }
+
+    /// 等待结果（两种情形都有）。
+    pub fn completion(&self) -> &PumpCompletion {
+        match self {
+            Self::Complete(completion) => completion,
+            Self::Stalled { completion, .. } => completion,
+        }
+    }
+}
+
+/// 用配置里的预算等待日志泵结束。
+pub fn wait_for_pumps(group: &mut PumpGroup, config: &WatchdogConfig) -> PumpVerdict {
+    let completion = group.wait(config.pump_timeout);
+    if completion.is_complete() {
+        PumpVerdict::Complete(completion)
+    } else {
+        let streams = completion.stalled.clone();
+        PumpVerdict::Stalled {
+            completion,
+            streams,
+            waited: config.pump_timeout,
+        }
+    }
+}
diff --git a/crates/core/src/launch/window_detect.rs b/crates/core/src/launch/window_detect.rs
new file mode 100644
index 0000000..1a1a667
--- /dev/null
+++ b/crates/core/src/launch/window_detect.rs
@@ -0,0 +1,86 @@
+//! “游戏窗口是否出现”的检测（日志启发式）。
+//!
+//! HMCL 只看两条小写子串（`analyse/02` §6.5：`lwjgl version` / `lwjgl openal`），
+//! 换日志格式就失效。v1 保持同样的启发式但做成**可扩展模式表 + 命中证据 + 耗时**，
+//! 这样 `window_detected` 事件能告诉 AI“靠哪一行判定的、花了多久”；
+//! 进程/窗口级信号（Windows `EnumWindows` 按 PID）留 P1（`PlanDoc/06` §1 升级点 3）。
+
+use std::time::Instant;
+
+/// 一次成功检测。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Detection {
+    /// 启发式名称（事件流 `window_detected.heuristic`）。
+    pub heuristic: String,
+    /// 从进程启动到命中的毫秒数。
+    pub took_ms: u64,
+    /// 命中的日志行（事件流 `evidence`）。
+    pub evidence: String,
+}
+
+/// 启发式模式表：（小写子串，启发式名称）。
+pub const HEURISTICS: &[(&str, &str)] = &[
+    ("lwjgl version", "lwjgl_version"),
+    ("lwjgl openal", "lwjgl_openal"),
+    ("sound engine started", "sound_engine"),
+];
+
+/// 窗口检测器。
+#[derive(Debug, Clone)]
+pub struct WindowDetector {
+    started_at: Instant,
+    detection: Option,
+}
+
+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()
+    }
+}
diff --git a/crates/core/src/lib.rs b/crates/core/src/lib.rs
new file mode 100644
index 0000000..16966bf
--- /dev/null
+++ b/crates/core/src/lib.rs
@@ -0,0 +1,24 @@
+//! Unlucky-Launcher 领域库（`unlucky_core`）。
+//!
+//! 本 crate **零 UI 依赖**：UI 框架（Slint）只允许出现在 `crates/app`。
+//! 这是对 HMCL「HMCLCore 34 处 import javafx」架构债的正面修正，
+//! 由 `.github/workflows/guards.yml` 的 `core-no-ui` job 在 CI 守门。
+//!
+//! core 对 UI 的回调只有三条通道（见 `DevDocs/PlanDoc/01-tech-stack-and-architecture.md` §3）：
+//! 1. 不可变快照发布；2. 事件流（启动/下载/诊断 JSONL 事件）；3. 注入的显示服务接口（进度/确认）。
+//!
+//! 设计定稿索引：`DevDocs/PlanDoc/00-master-architecture.md`。
+//! 各模块的设计文档在对应 `mod.rs` 的模块注释里点名。
+//!
+//! 当前状态：P0 脚手架，只有模块骨架与设计注释，实现按 M12–M15/M18 分批落地。
+
+#![forbid(unsafe_code)]
+
+pub mod addon;
+pub mod auth;
+pub mod diagnose;
+pub mod download;
+pub mod game;
+pub mod launch;
+pub mod platform;
+pub mod setting;
diff --git a/crates/core/src/platform/atomic.rs b/crates/core/src/platform/atomic.rs
new file mode 100644
index 0000000..9448a84
--- /dev/null
+++ b/crates/core/src/platform/atomic.rs
@@ -0,0 +1,79 @@
+//! 原子写：临时文件 → fsync → rename。
+//!
+//! 出处：`DevDocs/analyse/07-settings-packaging-update.md` §1.6（HMCL `FileUtils.saveSafely`：
+//! 写 tmp + `Files.move(REPLACE_EXISTING)`）。配置与下载落盘都该走这里，禁止直接 `fs::write`。
+//!
+//! `std::fs::rename` 在 Unix 与 Windows 上都是「替换式」语义
+//! （Windows 侧 std 用 `MoveFileExW(MOVEFILE_REPLACE_EXISTING)`），因此不需要先删目标文件。
+
+use std::io::{self, Write};
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+
+use super::error::{io_at, PlatformError, PlatformResult};
+
+/// 同进程内的 tmp 名去重计数器。
+static TMP_COUNTER: AtomicU64 = AtomicU64::new(0);
+
+/// 原子地把 `bytes` 写到 `path`（父目录不存在会创建）。
+///
+/// # Errors
+/// 建目录、写临时文件、fsync、rename 任一步失败都返回 [`PlatformError::Io`]，
+/// 且失败时会尽力清理临时文件，不留垃圾。
+pub fn write_atomic(path: &Path, bytes: &[u8]) -> PlatformResult<()> {
+    let parent = path.parent().unwrap_or_else(|| Path::new(""));
+    if !parent.as_os_str().is_empty() {
+        std::fs::create_dir_all(parent).map_err(io_at(parent))?;
+    }
+
+    let tmp = tmp_path(path);
+    let write_result = (|| -> io::Result<()> {
+        let mut file = std::fs::File::create(&tmp)?;
+        file.write_all(bytes)?;
+        file.sync_all()?;
+        Ok(())
+    })();
+    if let Err(source) = write_result {
+        std::fs::remove_file(&tmp).ok();
+        return Err(PlatformError::Io { path: tmp, source });
+    }
+
+    if let Err(source) = std::fs::rename(&tmp, path) {
+        std::fs::remove_file(&tmp).ok();
+        return Err(PlatformError::Io {
+            path: path.to_path_buf(),
+            source,
+        });
+    }
+    Ok(())
+}
+
+/// 读文件；不存在返回 `None`，其它错误照原样上报（用于区分「没配过」和「读不了」）。
+///
+/// # Errors
+/// 除 `NotFound` 以外的读失败返回 [`PlatformError::Io`]。
+pub fn read_optional(path: &Path) -> PlatformResult>> {
+    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/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..146a011
--- /dev/null
+++ b/crates/core/src/platform/layout.rs
@@ -0,0 +1,223 @@
+//! `.ULL/` 四分区布局——所有模块取路径的唯一入口，禁止各自手拼路径。
+//!
+//! 布局依据 `DevDocs/PlanDoc/04-data-and-config.md` §2（承 HMCL 四分区）：
+//! `config/`（schema 化 JSON）、`data/`（可重建但优先保留）、`cache/`（随时可删）、`logs/`。
+
+use std::path::{Path, PathBuf};
+
+use super::error::{io_at, PlatformError, PlatformResult};
+
+/// Portable 模式下启动器数据目录名（exe 同目录）。
+pub const LAUNCHER_HOME_DIR: &str = ".ULL";
+/// 游戏数据目录名。
+pub const GAME_HOME_DIR: &str = ".minecraft";
+/// 分区：配置。
+pub const CONFIG_DIR: &str = "config";
+/// 分区：状态数据。
+pub const DATA_DIR: &str = "data";
+/// 分区：纯缓存。
+pub const CACHE_DIR: &str = "cache";
+/// 分区：启动器日志。
+pub const LOGS_DIR: &str = "logs";
+
+/// 全局设置文件名。
+pub const LAUNCHER_CONFIG_FILE: &str = "launcher.json";
+/// 实例档案列表文件名。
+pub const PROFILES_CONFIG_FILE: &str = "profiles.json";
+/// 每实例设置所在子目录。
+pub const INSTANCES_DIR: &str = "instances";
+/// 迁移后留在旧目录的指针文件名。
+pub const REDIRECT_FILE: &str = "redirect.json";
+/// 目录迁移收据文件名（写在目标 `config/`）。
+pub const MIGRATION_RECEIPT_FILE: &str = "migration-receipt.json";
+
+/// `.ULL/` 下的四个分区。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub enum Partition {
+    /// `config/`：配置（迁移时优先搬）。
+    Config,
+    /// `data/`：状态数据（不可丢）。
+    Data,
+    /// `cache/`：纯缓存（可丢，迁移可选）。
+    Cache,
+    /// `logs/`：启动器日志。
+    Logs,
+}
+
+impl Partition {
+    /// 全部四个分区。
+    pub const ALL: [Self; 4] = [Self::Config, Self::Data, Self::Cache, Self::Logs];
+
+    /// 分区目录名。
+    #[must_use]
+    pub const fn dir_name(&self) -> &'static str {
+        match self {
+            Self::Config => CONFIG_DIR,
+            Self::Data => DATA_DIR,
+            Self::Cache => CACHE_DIR,
+            Self::Logs => LOGS_DIR,
+        }
+    }
+
+    /// 稳定名（日志 / 收据用）。
+    #[must_use]
+    pub const fn as_str(&self) -> &'static str {
+        self.dir_name()
+    }
+
+    /// 是否为可丢弃分区（迁移时可跳过）。
+    #[must_use]
+    pub const fn is_disposable(&self) -> bool {
+        matches!(self, Self::Cache)
+    }
+}
+
+/// 一个 launcher home（`.ULL` 的等价物）的路径视图。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct LauncherLayout {
+    home: PathBuf,
+}
+
+impl LauncherLayout {
+    /// 绑定到某个 home 目录（不创建任何东西，创建用 [`Self::ensure`]）。
+    #[must_use]
+    pub fn new(home: impl Into) -> 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")
+    }
+
+    /// `data/agent/sessions/`——AI 会话 jsonl 与审计日志。
+    #[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..3397e9d
--- /dev/null
+++ b/crates/core/src/platform/linux_caps.rs
@@ -0,0 +1,225 @@
+//! Linux 探测：**能力**而非版本号（D19 · `PlanDoc/11-os-detection.md` §2）。
+//!
+//! 发行版版本对能不能跑没有意义，所以这里分三类事实：
+//! - `/etc/os-release` 的 `PRETTY_NAME` —— **仅供显示/日志**；
+//! - 内核 release（`/proc/sys/kernel/osrelease`，退化 `uname -r`）—— 喂 MC 的
+//!   `rules.os.version`，同时给出最低内核判定用的 `major.minor`；
+//! - 能力探测：图形会话类型（Wayland / X11 / 无显示）与 GL 能力钩子（见 [`probe_gl`]）。
+//!
+//! glibc 版本用 `ldd --version` 探测（musl / Termux 上取不到，此时不阻塞）。
+//! fontconfig 可用性与 `xdg-desktop-portal` 同理留到 app 层（字体回退、主题跟随、文件选择器），
+//! core 只报环境事实，不做渲染后端决策。
+//! 解析函数是纯函数且跨平台编译，单测用注入样本覆盖（见 `tests/platform/`）。
+
+/// 图形会话类型（`Unknown` 是派生默认值：未探测）。
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub enum SessionKind {
+    /// Wayland 会话（`WAYLAND_DISPLAY` 或 `XDG_SESSION_TYPE=wayland`）。
+    Wayland,
+    /// X11 会话（`DISPLAY` 或 `XDG_SESSION_TYPE=x11`）。
+    X11,
+    /// 没有图形会话（服务器 / 容器 / SSH）。GUI 用不了，CLI 照常。
+    Headless,
+    /// 未探测（非 Linux 平台，或探测未执行）。
+    #[default]
+    Unknown,
+}
+
+impl SessionKind {
+    /// 简短名（日志用）。
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Wayland => "wayland",
+            Self::X11 => "x11",
+            Self::Headless => "headless",
+            Self::Unknown => "unknown",
+        }
+    }
+
+    /// 是否存在可用的显示服务器。
+    pub fn has_display(self) -> bool {
+        matches!(self, Self::Wayland | Self::X11)
+    }
+}
+
+/// GL/EGL 能力探测结果。
+///
+/// P1 只留钩子：真探测要 `dlopen("libEGL.so")` + `eglQueryString`，那是 FFI，
+/// 而 core 是 `#![forbid(unsafe_code)]`；因此真实探测放在 app 层「渲染后端选择」里做，
+/// core 只负责把 `Unknown` 如实报出来，不阻塞任何流程。
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub enum GlProbe {
+    /// 未探测（P1 常态）。
+    #[default]
+    Unknown,
+    /// 有可用的 GL/EGL。
+    Available,
+    /// 没有可用 GL（调用方应降级到软渲染）。
+    Missing,
+}
+
+impl GlProbe {
+    /// 简短名（日志用）。
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Unknown => "unknown",
+            Self::Available => "available",
+            Self::Missing => "missing",
+        }
+    }
+}
+
+/// Linux 探测结果。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct LinuxCaps {
+    /// 发行版展示名（`PRETTY_NAME`，仅显示）。
+    pub distro: Option,
+    /// 内核 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 {
+    use std::process::Command;
+    let output = Command::new(program).args(args).output().ok()?;
+    if output.stdout.is_empty() {
+        return None;
+    }
+    Some(String::from_utf8_lossy(&output.stdout).into_owned())
+}
diff --git a/crates/core/src/platform/macos_version.rs b/crates/core/src/platform/macos_version.rs
new file mode 100644
index 0000000..bc18447
--- /dev/null
+++ b/crates/core/src/platform/macos_version.rs
@@ -0,0 +1,100 @@
+//! macOS 探测：产品版本 + 运行架构（D19 · `PlanDoc/11-os-detection.md` §2）。
+//!
+//! - 产品版本：`sw_vers -productVersion` → `12.3.1`（最低部署目标判定 + MC `os.version` 规则）；
+//! - 运行架构：`sysctl -n hw.optional.arm64` 输出 `1` 表示**当前运行在 Apple Silicon 上**
+//!   （关键：Rosetta 2 下 `cfg!(target_arch)` 仍是 `x86_64`，但原生渲染路径与 MC 原生库
+//!   要的是真实架构，所以必须运行期探）；
+//! - 内核版本：`uname -r`（`22.4.0`）只进日志，不参与判定。
+//!
+//! 解析函数是纯函数且跨平台编译，单测用注入样本覆盖（见 `tests/platform/`）。
+
+/// macOS 版本 + 运行架构。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct MacOsVersion {
+    /// 主版本号（macOS 12 Monterey = 12）。
+    pub major: u32,
+    /// 次版本号。
+    pub minor: u32,
+    /// 补丁号。
+    pub patch: u32,
+    /// 是否运行在 Apple Silicon（含 Rosetta 2 场景）。
+    pub arm64: bool,
+}
+
+impl MacOsVersion {
+    /// 构造。
+    pub fn new(major: u32, minor: u32, patch: u32, arm64: bool) -> Self {
+        Self {
+            major,
+            minor,
+            patch,
+            arm64,
+        }
+    }
+
+    /// 产品版本串（`rules.os.version` 用，例如 `12.3.1`）。
+    pub fn version_string(&self) -> String {
+        format!("{}.{}.{}", self.major, self.minor, self.patch)
+    }
+
+    /// 展示名（`macOS 12.3.1 (arm64)`）。
+    pub fn display_name(&self) -> String {
+        let arch = if self.arm64 { "arm64" } else { "x86_64" };
+        format!("macOS {} ({arch})", self.version_string())
+    }
+
+    /// `rules.os.arch` 取值：Apple Silicon 上必须是 `arm64`。
+    pub fn runtime_arch(&self) -> &'static str {
+        if self.arm64 {
+            "arm64"
+        } else {
+            "x86_64"
+        }
+    }
+}
+
+/// 真实探测；非 macOS 平台恒为 `None`。
+#[cfg(target_os = "macos")]
+pub fn probe() -> Option {
+    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 {
+    use std::process::Command;
+    let output = Command::new(program).args(args).output().ok()?;
+    if !output.status.success() || output.stdout.is_empty() {
+        return None;
+    }
+    Some(String::from_utf8_lossy(&output.stdout).into_owned())
+}
diff --git a/crates/core/src/platform/mod.rs b/crates/core/src/platform/mod.rs
new file mode 100644
index 0000000..5691acb
--- /dev/null
+++ b/crates/core/src/platform/mod.rs
@@ -0,0 +1,46 @@
+//! OS 抽象层：路径规则、平台目录差异、进程与文件锁、软渲染/显示能力探测辅助。
+//!
+//! 设计定稿：`DevDocs/PlanDoc/04-data-and-config.md` §1–§2（三模式路径与 `.ULL` 四分区）。
+//! Win7 单独适配（决策 D11）在此收敛平台差异判断，避免散落各模块打补丁。
+//!
+//! 公共面（M12 已落地）：
+//! - [`paths`]：宿主平台族与标准目录探测（环境变量可注入），可搬运路径字符串；
+//! - [`layout`]：`.ULL/` 四分区（config/data/cache/logs）与各已知路径的唯一入口；
+//! - [`data_dir`]：三模式数据目录解析（Portable 默认 / Standard / Custom + 高级覆盖）；
+//! - [`redirect`]：迁移后留在旧目录的 `redirect.json` 指针（防便携盘旧目录被再次初始化）；
+//! - [`receipt`]：迁移收据（源指纹防重放）；
+//! - [`dir_migration`]：数据目录迁移（分区逐个搬 + 失败逆序回滚）；
+//! - [`atomic`]：原子写（tmp → fsync → rename）；[`hash`]：迁移收据用的 SHA-256。
+//!
+//! 运行期系统探测（M20 / D19 · `11-os-detection.md`）：
+//! - [`os_info`]：`OsInfo` 快照 + 最低支持判定（One / Unsupported，基线 **Windows 10+ /
+//!   macOS 12+ / Linux 达标**）+ 启动自检；
+//! - [`windows_version`]：真实 `major.minor.build`（注册表 `CurrentBuildNumber` 快路径 →
+//!   整键 `CurrentVersion` 家族 → `cmd /c ver` 兜底）；
+//! - [`macos_version`]：`sw_vers` 产品版本 + `sysctl hw.optional.arm64` 运行架构；
+//! - [`linux_caps`]：发行版（仅显示）+ 内核 release（喂 `os.version`）+ 会话/GL 能力探测；
+//! - [`vk_probe`]：Vulkan 能力的安全层探测（loader 文件 / ICD 注册 / 环境变量，无 `unsafe`）；
+//! - [`theme_probe`]：系统主题（浅色/深色）探测，供主题三态的 `auto` 初始化对齐与兜底跟随。
+//! - [`wallpaper`]：桌面壁纸**路径探测**（D38 配色三级优先里第②级的输入）。本模块只做路径
+//!   探测——不解码图片、不取色、不生成调色板，莫奈取色与三级降级在 `crates/design` 的
+//!   后续 mission。
+//!
+//! 尚未落地（后续 mission）：文件锁、进程工具、真实 GL/Vulkan 能力探测（钩子见
+//! [`linux_caps::probe_gl`] 与 [`vk_probe::probe_vk`]，FFI 受限，实际探测归 app 层渲染后端选择）。
+
+pub mod atomic;
+pub mod data_dir;
+pub mod dir_migration;
+pub mod error;
+pub mod hash;
+pub mod layout;
+pub mod linux_caps;
+pub mod macos_version;
+pub mod os_info;
+pub mod paths;
+pub mod receipt;
+pub mod redirect;
+pub mod theme_probe;
+pub mod vk_probe;
+pub mod wallpaper;
+pub mod windows_version;
diff --git a/crates/core/src/platform/os_info.rs b/crates/core/src/platform/os_info.rs
new file mode 100644
index 0000000..70a9eb9
--- /dev/null
+++ b/crates/core/src/platform/os_info.rs
@@ -0,0 +1,388 @@
+//! 运行期系统探测与最低支持判定（D19 · `DevDocs/PlanDoc/11-os-detection.md`）。
+//!
+//! 事实通道按平台分流（各文件里的 `probe()`）：[`windows_version`] 注册表 `CurrentBuildNumber`
+//! 快路径 → 整键 `CurrentVersion` 家族 → `cmd /c ver` 兜底；[`macos_version`] `sw_vers` +
+//! `sysctl`；[`linux_caps`] `/etc/os-release`（仅显示）+ 内核 release + 会话/GL 能力探测。
+//! 不用 `RtlGetVersion` FFI 是因为 core 是 `#![forbid(unsafe_code)]`，而这些路径读的是同一份
+//! 真实事实，代价只是一次性几十毫秒。
+//!
+//! 支持基线（用户拍板）：**Windows 10 起、macOS 12 起、Linux（内核/glibc 达标）**。
+//! 因此等级只有两档：[`SupportLevel::One`] 与 [`SupportLevel::Unsupported`]——Win8.1/8/7
+//! 不承诺 GUI，也不承诺 CLI（识别出旧版本正是为了报「不支持」）。
+//!
+//! 入口：[`detect`]（真探）· [`current`]（进程内缓存）· [`check`]（CLI 启动自检）；
+//! 等级映射是纯函数（[`support_level_for`] 及三平台分解），单测用注入式假数据覆盖。
+
+use std::sync::OnceLock;
+
+use crate::platform::linux_caps::{self, GlProbe, SessionKind};
+use crate::platform::macos_version;
+use crate::platform::vk_probe::{self, VkProbe};
+use crate::platform::windows_version;
+
+/// 最低支持的 Windows 版本（10.0 = Windows 10，build 10240 起）。
+pub const MIN_WINDOWS: (u32, u32) = (10, 0);
+/// 最低支持的 macOS 主版本（Slint / winit 的现实部署下限，见 D19 §4）。
+pub const MIN_MACOS_MAJOR: u32 = 12;
+/// 最低 Linux 内核（Rust std 的 Linux 下限）。
+pub const MIN_LINUX_KERNEL: (u32, u32) = (3, 2);
+/// 最低 glibc（`x86_64-unknown-linux-gnu` 构建产物能跑的下限）。
+pub const MIN_GLIBC: (u32, u32) = (2, 17);
+
+/// 操作系统家族。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum OsFamily {
+    /// Windows。
+    Windows,
+    /// macOS。
+    MacOs,
+    /// Linux 及其它 POSIX 系统。
+    Linux,
+}
+
+impl OsFamily {
+    /// 当前编译目标的系统家族。
+    pub fn current() -> Self {
+        if cfg!(target_os = "windows") {
+            Self::Windows
+        } else if cfg!(target_os = "macos") {
+            Self::MacOs
+        } else {
+            Self::Linux
+        }
+    }
+
+    /// Mojang 清单里 `rules.os.name` 的取值。
+    pub fn manifest_name(self) -> &'static str {
+        match self {
+            Self::Windows => "windows",
+            Self::MacOs => "osx",
+            Self::Linux => "linux",
+        }
+    }
+
+    /// `rules.os.arch` 的取值（按编译目标；Apple Silicon 的真实架构另见
+    /// [`MacOsVersion::runtime_arch`](crate::platform::macos_version::MacOsVersion::runtime_arch)）。
+    pub fn manifest_arch(self) -> &'static str {
+        if cfg!(target_arch = "x86_64") {
+            "x86_64"
+        } else if cfg!(target_arch = "x86") {
+            "x86"
+        } else if cfg!(target_arch = "aarch64") {
+            "arm64"
+        } else {
+            "unknown"
+        }
+    }
+
+    /// 是否为 POSIX 系统（决定 `nice`、进程组 kill 等分支）。
+    pub fn is_posix(self) -> bool {
+        !matches!(self, Self::Windows)
+    }
+}
+
+/// 支持等级（两档：满足基线 / 不满足）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SupportLevel {
+    /// 一等：基线以上（Windows 10+ / macOS 12+ / Linux 达标），GUI + CLI。
+    One,
+    /// 不支持：低于基线，启动时拒绝并给升级指引。
+    Unsupported,
+}
+
+impl SupportLevel {
+    /// 简短名（日志/事件用）。
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::One => "one",
+            Self::Unsupported => "unsupported",
+        }
+    }
+
+    /// 是否允许运行。
+    pub fn is_usable(self) -> bool {
+        matches!(self, Self::One)
+    }
+}
+
+/// 运行期系统信息（不可变快照，可跨线程共享；字段全是探测出来的事实）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct OsInfo {
+    /// 系统家族。
+    pub family: OsFamily,
+    /// `rules.os.arch` 用的架构名。
+    pub arch: String,
+    /// 版本 `major.minor`（探测失败为 `None`）。
+    pub major_minor: Option<(u32, u32)>,
+    /// 构建号（Windows build，其它平台 `None`）。
+    pub build: Option,
+    /// 展示名（`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/theme_probe.rs b/crates/core/src/platform/theme_probe.rs
new file mode 100644
index 0000000..e1216de
--- /dev/null
+++ b/crates/core/src/platform/theme_probe.rs
@@ -0,0 +1,182 @@
+//! 系统主题（浅色/深色）探测：给主题三态的 `auto` 模式做**初始化对齐**与后端不支持时的兜底跟随。
+//!
+//! 出处：`DevDocs/PlanDoc/09-ui-layout.md` §2「主题模式三态」（D17 用户定案：Win/mac 用 Slint
+//! `Palette.color-scheme` 原生跟随 OS 热切；Linux 依 DE 的 xdg-desktop-portal，缺省回落浅色并
+//! 允许手动钉死）。Slint 后端会在运行期自己监听 OS 主题变化，所以这里**只补两件事**：
+//!
+//! 1. 启动时先读一次真实系统主题，避免「auto 模式下首帧按浅色画、几百毫秒后突然翻黑」的闪变；
+//! 2. 后端把 `Palette.color-scheme` 报成 `unknown`（无 portal 的 Linux / 软渲染后端）时，
+//!    由 app 轮询本模块把系统主题补上，`auto` 仍然可用。
+//!
+//! 与 platform 层其他探测一致（见 [`super::windows_version`]）：core 是 `#![forbid(unsafe_code)]`，
+//! 一律走外部命令 + 纯函数解析。解析函数跨平台编译，任意宿主都能单测（`tests/platform/theme_cases.rs`）。
+
+/// 系统主题三态。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SystemTheme {
+    /// 浅色。
+    Light,
+    /// 深色。
+    Dark,
+    /// 读不到（无桌面环境 / 命令缺失 / 输出无法解析）。
+    Unknown,
+}
+
+impl SystemTheme {
+    /// 稳定名（日志用）。
+    #[must_use]
+    pub const fn as_str(&self) -> &'static str {
+        match self {
+            Self::Light => "light",
+            Self::Dark => "dark",
+            Self::Unknown => "unknown",
+        }
+    }
+
+    /// 是否深色（`Unknown` 为 `None`，调用方决定回落）。
+    #[must_use]
+    pub const fn is_dark(&self) -> Option {
+        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 {
+    use std::process::Command;
+    let output = Command::new(program).args(args).output().ok()?;
+    if output.stdout.is_empty() {
+        return None;
+    }
+    Some(String::from_utf8_lossy(&output.stdout).into_owned())
+}
diff --git a/crates/core/src/platform/vk_probe.rs b/crates/core/src/platform/vk_probe.rs
new file mode 100644
index 0000000..25a817e
--- /dev/null
+++ b/crates/core/src/platform/vk_probe.rs
@@ -0,0 +1,305 @@
+//! Vulkan 能力探测的**安全层**（无 `unsafe`，无 FFI）：只报可观测事实，不下「能不能玩」的结论。
+//!
+//! 依据 `DevDocs/PlanDoc/research/05-mc-vulkan.md`（M26）§2.3 与 §4.3：
+//! MC 的 Vulkan 后端在 Windows/Linux 上**不打包** `vulkan-1.dll` / `libvulkan.so.1`，
+//! 而是运行期去加载系统的 loader（natives 只给 macOS 发 MoltenVK）。所以「版本支持 Vulkan」
+//! 与「这台机器能跑 Vulkan」是两件事，前置探测不可省。
+//!
+//! 分工照抄 [`super::linux_caps::probe_gl`]：core 只做「文件存在性 / 注册表 / 环境变量 /
+//! 标准目录」这一层，真探测（建 instance、枚举物理设备、查 `VK 1.2` +
+//! `VK_KHR_dynamic_rendering` + `VK_KHR_push_descriptor` 三项硬门槛）归 app 层。
+//!
+//! # ⚠️ 注册表键缺失 ≠ 没有 Vulkan（真机证据）
+//!
+//! 实测机（Windows 11 + AMD 独显，Vulkan 1.3.217 可用）上
+//! `HKLM\SOFTWARE\Khronos\Vulkan\Drivers` **压根不存在**——ICD 由 loader 自己按
+//! `%SystemRoot%\System32` 与驱动安装目录自寻。因此该键只作**加分项**（[`VkProbe::Available`]），
+//! 缺失时降级为 [`VkProbe::LoaderOnly`]、**绝不**判 [`VkProbe::Missing`]。
+//!
+//! 解析函数是纯函数且跨平台编译，单测用注入样本覆盖三平台（见 `tests/platform/vk_cases.rs`）。
+
+use std::path::{Path, PathBuf};
+
+use crate::platform::os_info::OsFamily;
+
+/// Windows 上的 Vulkan loader 文件名（系统目录内）。
+pub const WINDOWS_LOADER: &str = "vulkan-1.dll";
+
+/// `HKLM\SOFTWARE\Khronos\Vulkan\Drivers`：显式 ICD 注册键（**只作加分**，见模块文档）。
+///
+/// ICD 注册为这个键下的**值**（值名 = manifest 绝对路径，数据是 `dword:00000000`），
+/// 不是子键（Vulkan-Loader `LoaderDriverInterface.md` 的 Windows 驱动发现一节）。
+pub const VULKAN_DRIVERS_KEY: &str = r"HKLM\SOFTWARE\Khronos\Vulkan\Drivers";
+
+/// 同一个键在 `reg query` 输出里的**键头行**形态。
+///
+/// `reg query` 即使传入缩写 hive 名（`HKLM`），输出也用完整 hive 名
+/// （`HKEY_LOCAL_MACHINE`）且不带尾反斜杠——解析时必须按这个形态比对。
+pub const VULKAN_DRIVERS_KEY_HEADER: &str = r"HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\Vulkan\Drivers";
+
+/// Khronos loader 认的 ICD 路径环境变量（旧名在前，新名在后）。
+pub const ICD_ENV_VARS: &[&str] = &["VK_ICD_FILENAMES", "VK_DRIVER_FILES"];
+
+/// Linux 的 ICD 清单目录（`*.json`，loader 启动时按此枚举驱动）。
+pub const ICD_DIRS: &[&str] = &[
+    "/usr/share/vulkan/icd.d",
+    "/usr/local/share/vulkan/icd.d",
+    "/etc/vulkan/icd.d",
+];
+
+/// Vulkan 能力（四档；`Unknown` 是派生默认值，「没探过」不等于「没有」）。
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub enum VkProbe {
+    /// 未探测（非探测路径构造的快照）。
+    #[default]
+    Unknown,
+    /// loader 在，但没有看到任何 ICD 注册信号。
+    ///
+    /// **不是**「没有 Vulkan」：Windows 上注册表键缺失是常态（模块文档的真机证据），
+    /// 设备是否存在要靠 app 层的真探测确认。
+    LoaderOnly,
+    /// loader + 驱动信号都在（或 macOS 上 MoltenVK 在场）——大概率可用。
+    Available,
+    /// 连 loader 都找不到：Vulkan 后端一定起不来。
+    Missing,
+}
+
+impl VkProbe {
+    /// 简短名（日志/摘要行用）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Unknown => "unknown",
+            Self::LoaderOnly => "loader_only",
+            Self::Available => "available",
+            Self::Missing => "missing",
+        }
+    }
+
+    /// loader 是否在场（`Available` 与 `LoaderOnly` 都为真）。
+    #[must_use]
+    pub const fn has_loader(self) -> bool {
+        matches!(self, Self::Available | Self::LoaderOnly)
+    }
+
+    /// 是否已能确定「这台机器跑不了 Vulkan」（只有 [`Self::Missing`]）。
+    #[must_use]
+    pub const fn is_missing(self) -> bool {
+        matches!(self, Self::Missing)
+    }
+
+    /// 是否足够确定「可以用 Vulkan」（只有 [`Self::Available`]）。
+    ///
+    /// UI/建议路径用它可以保守一点：`LoaderOnly` 应当提示「先试一次再说」而不是承诺可用。
+    #[must_use]
+    pub const fn is_available(self) -> bool {
+        matches!(self, Self::Available)
+    }
+}
+
+/// 平台无关的探测证据（单测直接注入，不读真机）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct VkEvidence {
+    /// 系统家族（决定判定口径）。
+    pub family: OsFamily,
+    /// loader 文件是否找到（`vulkan-1.dll` / `libvulkan.so.1` / `libvulkan.1.dylib` / MoltenVK）。
+    pub loader_present: bool,
+    /// 是否看到驱动信号：Windows 注册表键、Linux 的 ICD 目录/环境变量、macOS 无此项。
+    pub icd_signal: bool,
+}
+
+impl VkEvidence {
+    /// 构造。
+    #[must_use]
+    pub const fn new(family: OsFamily, loader_present: bool, icd_signal: bool) -> Self {
+        Self {
+            family,
+            loader_present,
+            icd_signal,
+        }
+    }
+}
+
+/// 证据 → 结论（纯函数，三平台共用；macOS 单独口径见函数体注释）。
+#[must_use]
+pub fn classify(evidence: VkEvidence) -> VkProbe {
+    if evidence.family == OsFamily::MacOs {
+        // macOS 没有系统 Vulkan：LWJGL 自带的 MoltenVK 既是 loader 又是 ICD（Vulkan→Metal 翻译），
+        // 所以「MoltenVK/libvulkan.1.dylib 在」本身就是可用证据，没有 LoaderOnly 这一档。
+        return if evidence.loader_present {
+            VkProbe::Available
+        } else {
+            VkProbe::Missing
+        };
+    }
+    if !evidence.loader_present {
+        return VkProbe::Missing;
+    }
+    if evidence.icd_signal {
+        VkProbe::Available
+    } else {
+        // 注册表键缺失是常态，只降级不否定（模块文档的真机证据）。
+        VkProbe::LoaderOnly
+    }
+}
+
+/// 探测当前机器的 Vulkan 能力（一次性，结果由 [`crate::platform::os_info::current`] 缓存）。
+#[must_use]
+pub fn probe_vk() -> VkProbe {
+    classify(probe_evidence())
+}
+
+/// 采集当前机器的探测证据（真读盘/注册表；单测请直接用 [`classify`]）。
+#[must_use]
+pub fn probe_evidence() -> VkEvidence {
+    let family = OsFamily::current();
+    VkEvidence::new(family, loader_present(family), icd_signal(family))
+}
+
+/// loader 候选绝对路径（按平台；`SystemRoot` 缺失时回落到 `C:\Windows`）。
+#[must_use]
+pub fn loader_candidates(family: OsFamily) -> Vec {
+    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 {
+    use std::process::Command;
+    let output = Command::new(program).args(args).output().ok()?;
+    if output.stdout.is_empty() {
+        return None;
+    }
+    Some(String::from_utf8_lossy(&output.stdout).into_owned())
+}
diff --git a/crates/core/src/platform/wallpaper.rs b/crates/core/src/platform/wallpaper.rs
new file mode 100644
index 0000000..03e803a
--- /dev/null
+++ b/crates/core/src/platform/wallpaper.rs
@@ -0,0 +1,358 @@
+//! 桌面壁纸**路径探测**（D38 配色三级优先里的第②级输入）。
+//!
+//! 用户原话（D38，2026-11-01）：「如果用户设置了启动器背景图，则使用莫奈取色从背景图取，
+//! 没有背景图时用户也可以开启莫奈取色，此时从桌面壁纸取色。」本模块只承担中间那一级的
+//! **输入**：按可信度给出「这台机器的桌面壁纸可能是哪个文件」的有序候选列表。
+//!
+//! # 边界（只做路径探测）
+//!
+//! - **不解码图片、不取色、不生成调色板**。莫奈取色本身、D38 三级降级、
+//!   「取色失败回落到色卡当前选择 + 设置页可读提示」都在 `crates/design` 的后续 mission。
+//! - 全部找不到时返回**空列表**（[`WallpaperProbe::is_empty`]）而不是错误：没有桌面壁纸是
+//!   正常状态（服务器、无桌面环境、壁纸是纯色），调用方按 D38 直接落到第③级色卡。
+//! - **零 `unsafe`、零 FFI**（core 是 `#![forbid(unsafe_code)]`）：不用
+//!   `SystemParametersInfo(SPI_GETDESKWALLPAPER)`、不碰 win32 注册表 API，全部走文件读取与
+//!   `reg.exe` / `gsettings` / `defaults` 子进程——与 [`super::theme_probe`]、
+//!   [`super::windows_version`] 同一套路子。
+//!
+//! # 分层与可测性
+//!
+//! - 采集逻辑按平台分文件（`windows` / `linux` / `macos` 子模块），**无条件编译**、不按
+//!   `cfg` 裁剪：CI 是 Linux，Windows / macOS 的夹具用例同样要能在那里跑；
+//! - 平台分流只发生在 [`detect_with`] 一处；
+//! - 外部 IO 全部经 [`ProbeIo`]（文件内容 / 文件头 / 目录列表 / 子进程）与
+//!   [`EnvSource`]（环境变量表）注入，[`detect`] 只是把它们换成真实实现。
+//!
+//! # 什么算「候选壁纸」
+//!
+//! 只收「归一化后是绝对路径 + 文件头认得出是图片」的条目（魔数集合见 `parse` 子模块的
+//! `looks_like_image`）。这条校验既挡掉过期配置里指向已删除文件的路径，也挡掉 macOS
+//! 二进制 plist 字符串扫描出的碎片串。
+
+use std::path::PathBuf;
+
+use crate::platform::paths::{EnvSource, Platform, ProcessEnv};
+
+use self::io::{HostIo, HostRoots, ProbeIo};
+use self::parse::{looks_like_image, normalize_path};
+
+mod io;
+mod linux;
+mod macos;
+mod parse;
+mod windows;
+
+/// 读文件头做魔数嗅探时的字节数（够 `ftyp` 分支与文本 SVG 头）。
+const IMAGE_HEAD_LEN: usize = 512;
+
+/// 一个候选壁纸是**怎么被找到的**：平台 + 桌面环境标识。
+///
+/// 标识只表示「这条路径从哪个通道读出来」，不承诺该通道一定存在（读不到就走下一个）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SourceKind {
+    /// Windows：`%APPDATA%\Microsoft\Windows\Themes\TranscodedWallpaper`（系统转码后的当前壁纸）。
+    WindowsTranscoded,
+    /// Windows：`HKCU\Software\Microsoft\Windows\CurrentVersion\Themes` 的 `CurrentTheme`
+    /// 指向的 `.theme`（Win10+ 落在 `%LOCALAPPDATA%\Microsoft\Windows\Themes\Custom.theme`）。
+    ///
+    /// 这是**当前生效**的那份主题，比 `%APPDATA%` 下的主题包可靠得多。
+    WindowsCurrentTheme,
+    /// Windows：`%APPDATA%\Microsoft\Windows\Themes\*.theme` 里的 `Wallpaper=` 行。
+    ///
+    /// 用户另存的主题包（不一定被启用），只作最后一档兜底。
+    WindowsThemeFile,
+    /// Windows：注册表 `HKCU\Control Panel\Desktop` 的 `WallPaper` 值（`reg.exe` 子进程）。
+    WindowsRegistry,
+    /// Linux · GNOME：`gsettings get org.gnome.desktop.background picture-uri`(`-dark`)。
+    Gnome,
+    /// Linux · KDE Plasma：`plasma-org.kde.plasma.desktop-appletsrc` 的 `Image=` 行。
+    Kde,
+    /// Linux · swaybg / hyprpaper 配置里的 wallpaper 行。
+    WlrootsCompositor,
+    /// Linux · XFCE：`xfce4-desktop.xml` 的 `last-image` / `image-path` 属性。
+    Xfce,
+    /// macOS：`com.apple.wallpaper/Store/Index.plist` 里的 file URL / 绝对路径串。
+    MacOsStore,
+    /// macOS：`defaults read com.apple.desktop Background`（老式每屏壁纸设置）。
+    MacOsDesktopDefaults,
+}
+
+impl SourceKind {
+    /// 稳定标识（日志 / 设置页提示用）。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::WindowsTranscoded => "windows-transcoded",
+            Self::WindowsCurrentTheme => "windows-current-theme",
+            Self::WindowsThemeFile => "windows-theme-file",
+            Self::WindowsRegistry => "windows-registry",
+            Self::Gnome => "linux-gnome",
+            Self::Kde => "linux-kde",
+            Self::WlrootsCompositor => "linux-wlroots",
+            Self::Xfce => "linux-xfce",
+            Self::MacOsStore => "macos-store",
+            Self::MacOsDesktopDefaults => "macos-desktop-defaults",
+        }
+    }
+
+    /// 这条通道属于哪个平台族。
+    #[must_use]
+    pub const fn platform(self) -> Platform {
+        match self {
+            Self::WindowsTranscoded
+            | Self::WindowsCurrentTheme
+            | Self::WindowsThemeFile
+            | Self::WindowsRegistry => Platform::Windows,
+            Self::MacOsStore | Self::MacOsDesktopDefaults => Platform::MacOs,
+            Self::Gnome | Self::Kde | Self::WlrootsCompositor | Self::Xfce => Platform::Linux,
+        }
+    }
+}
+
+/// 一个候选壁纸来源。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct WallpaperSource {
+    /// 通道标识（平台 + 桌面环境）。
+    pub kind: SourceKind,
+    /// 归一化后的绝对路径。
+    pub path: PathBuf,
+    /// 原始证据：配置文件 / 注册表键 / 命令行，用于日志与设置页的「从哪读到的」。
+    pub evidence: String,
+}
+
+/// 探测结果：有序候选列表 + 各步失败原因。
+///
+/// 列表**不是** `Result`：找不到壁纸不是错误，见模块文档的边界一节。
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct WallpaperProbe {
+    sources: Vec,
+    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..3655957
--- /dev/null
+++ b/crates/core/src/platform/wallpaper/io.rs
@@ -0,0 +1,297 @@
+//! 壁纸探测要用的外部 IO：文件读取、文件头、目录列表、子进程，以及宿主根目录。
+//!
+//! 生产实现是 [`HostIo`]，测试实现是 `fake::FakeIo`（固定夹具，不碰真机壁纸）。
+//! 这一层的存在只为把「外部世界」变成注入参数，不含任何平台判断。
+
+use std::path::{Path, PathBuf};
+
+use crate::platform::paths::EnvSource;
+
+/// 探测需要的外部世界：四个方法覆盖三平台的全部读法。
+pub trait ProbeIo {
+    /// 读整个文件并按 UTF-8 lossy 转文本。
+    ///
+    /// 二进制 plist 也走这里：路径串本身是可读 ASCII，坏字节会被替换成 U+FFFD 而不影响
+    /// 路径串的完整性（macOS 的 `Index.plist` 就是 bplist00）。
+    fn read_text(&self, path: &Path) -> Option;
+
+    /// 读文件头最多 `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 = std::process::Command::new(program)
+            .args(args)
+            .output()
+            .ok()?;
+        // `Command::output` 对非零退出同样返回 `Ok`，所以退出码要单独判：三条命令
+        // （`reg.exe` / `gsettings` / `defaults`）出错时都走 stderr，只看 stdout 会把
+        // 「查不到」和「命令失败」混成一种，调用方的原因文案就名不副实了。
+        if !output.status.success() || output.stdout.is_empty() {
+            return None;
+        }
+        Some(String::from_utf8_lossy(&output.stdout).into_owned())
+    }
+}
+
+/// 探测要用的宿主根目录（全部由环境变量表推出，因此测试可以整体替换）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct HostRoots {
+    /// 用户主目录（`HOME`，退 `USERPROFILE`）。
+    pub home: PathBuf,
+    /// Windows `%APPDATA%`（退 `~/AppData/Roaming`）；其它平台用不到，但仍填上以免分支取空。
+    pub app_data: PathBuf,
+    /// Windows `%LOCALAPPDATA%`（退 `~/AppData/Local`）：Win10+ 的「当前主题」
+    /// `Custom.theme` 落在这一侧。
+    pub local_app_data: PathBuf,
+    /// `$XDG_CONFIG_HOME`（仅接受绝对路径），退 `~/.config`。
+    pub config_home: PathBuf,
+    /// Windows `%SystemRoot%`（`.theme` 里 `Wallpaper=%SystemRoot%\...` 展开用），无则不展开。
+    pub system_root: Option,
+}
+
+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";
+    const LOCAL_APP_DATA: &str = "C:/Users/u/AppData/Local";
+    const DESKTOP_QUERY: &str = "reg.exe query HKCU\\Control Panel\\Desktop /v WallPaper";
+    const THEMES_QUERY: &str =
+        "reg.exe query HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Themes /v CurrentTheme";
+    const CUSTOM_THEME: &str = r"C:\Users\u\AppData\Local\Microsoft\Windows\Themes\Custom.theme";
+
+    fn env() -> MapEnv {
+        MapEnv::new()
+            .with("HOME", "C:/Users/u")
+            .with("APPDATA", APP_DATA)
+            .with("LOCALAPPDATA", LOCAL_APP_DATA)
+            .with("SYSTEMROOT", "C:/Windows")
+    }
+
+    fn roots() -> HostRoots {
+        HostRoots::from_env(&env()).expect("HOME 已给")
+    }
+
+    /// 夹具用**生产代码同一个拼法**造路径，所以 Windows / Linux 宿主上都能对上
+    /// （另有一条字面量断言盯着这个拼法本身，见 `transcoded_wallpaper_hit_comes_first`）。
+    fn themes() -> PathBuf {
+        themes_dir(&roots())
+    }
+
+    #[test]
+    fn transcoded_wallpaper_hit_comes_first() {
+        let io = FakeIo::new().with_image(themes().join("TranscodedWallpaper"));
+        let probe = detect_with(&io, &env(), Platform::Windows);
+        assert_eq!(probe.len(), 1, "{:?}", probe.notes());
+        let best = probe.best().expect("有候选");
+        assert_eq!(best.kind, SourceKind::WindowsTranscoded);
+        assert_eq!(best.path, themes().join("TranscodedWallpaper"));
+        // 字面量：夹具路径是拿生产代码的构造函数造出来的，这条断言防止两边一起拼错。
+        assert_eq!(
+            best.path,
+            PathBuf::from(
+                "C:/Users/u/AppData/Roaming/Microsoft/Windows/Themes/TranscodedWallpaper"
+            )
+        );
+        assert!(best.evidence.contains("TranscodedWallpaper"));
+    }
+
+    #[test]
+    fn current_theme_is_read_from_local_app_data() {
+        // Win10+ 的真机形态：%APPDATA% 下没有 .theme，当前主题在 %LOCALAPPDATA%。
+        let io = FakeIo::new()
+            .with_command(
+                THEMES_QUERY,
+                &format!("    CurrentTheme    REG_SZ    {CUSTOM_THEME}\r\n"),
+            )
+            .with_file(
+                CUSTOM_THEME,
+                "[Control Panel\\Desktop]\r\nWallpaper=%SystemRoot%\\web\\wallpaper\\Windows\\img0.jpg\r\n",
+            )
+            .with_image("C:/Windows\\web\\wallpaper\\Windows\\img0.jpg");
+        let probe = detect_with(&io, &env(), Platform::Windows);
+        assert_eq!(probe.len(), 1, "{:?}", probe.notes());
+        let best = probe.best().expect("有候选");
+        assert_eq!(best.kind, SourceKind::WindowsCurrentTheme);
+        assert_eq!(
+            best.path,
+            PathBuf::from("C:/Windows\\web\\wallpaper\\Windows\\img0.jpg")
+        );
+        assert!(best.evidence.contains("CurrentTheme"), "{}", best.evidence);
+        assert!(best.evidence.contains("Windows\\Themes\\Custom.theme"));
+    }
+
+    #[test]
+    fn current_theme_expands_local_app_data_env_var() {
+        let io = FakeIo::new()
+            .with_command(
+                THEMES_QUERY,
+                "    CurrentTheme    REG_SZ    %LOCALAPPDATA%\\Microsoft\\Windows\\Themes\\Custom.theme\r\n",
+            )
+            .with_file(
+                CUSTOM_THEME,
+                "Wallpaper=C:\\Users\\u\\Pictures\\a.jpg\r\n",
+            )
+            .with_image(r"C:\Users\u\Pictures\a.jpg");
+        let probe = detect_with(&io, &env(), Platform::Windows);
+        assert_eq!(probe.len(), 1, "{:?}", probe.notes());
+        assert_eq!(
+            probe.best().expect("有候选").kind,
+            SourceKind::WindowsCurrentTheme
+        );
+    }
+
+    #[test]
+    fn authority_order_puts_saved_packages_last() {
+        // 四步全在场，路径互不相同：顺序必须是 转码副本 > 当前主题 > 注册表 > 另存包。
+        let package = themes().join("a.theme");
+        let io = FakeIo::new()
+            .with_image(themes().join("TranscodedWallpaper"))
+            .with_command(
+                THEMES_QUERY,
+                &format!("    CurrentTheme    REG_SZ    {CUSTOM_THEME}\r\n"),
+            )
+            .with_file(
+                CUSTOM_THEME,
+                "Wallpaper=C:\\Users\\u\\Pictures\\one.jpg\r\n",
+            )
+            .with_command(
+                DESKTOP_QUERY,
+                "    WallPaper    REG_SZ    C:\\Users\\u\\Pictures\\two.jpg\r\n",
+            )
+            .with_dir(themes(), &["a.theme", "b.theme", "notes.txt"])
+            .with_file(
+                package.clone(),
+                "Wallpaper=%SystemRoot%\\web\\wallpaper\\three.jpg\r\n",
+            )
+            .with_image(r"C:\Users\u\Pictures\one.jpg")
+            .with_image(r"C:\Users\u\Pictures\two.jpg")
+            .with_image("C:/Windows\\web\\wallpaper\\three.jpg");
+        let probe = detect_with(&io, &env(), Platform::Windows);
+        let seen: Vec<(SourceKind, String)> = probe
+            .iter()
+            .map(|source| (source.kind, source.path.display().to_string()))
+            .collect();
+        assert_eq!(seen.len(), 4, "{:?}", probe.notes());
+        assert_eq!(seen[0].0, SourceKind::WindowsTranscoded);
+        assert_eq!(seen[1].0, SourceKind::WindowsCurrentTheme);
+        assert_eq!(seen[2].0, SourceKind::WindowsRegistry);
+        assert_eq!(seen[3].0, SourceKind::WindowsThemeFile);
+        // 兜底档在 evidence 里如实标明「可能未启用」，调用方据此可降权。
+        assert!(
+            probe.sources()[3].evidence.contains("可能未启用"),
+            "{}",
+            probe.sources()[3].evidence
+        );
+    }
+
+    #[test]
+    fn everything_missing_returns_empty_with_reasons() {
+        let probe = detect_with(&FakeIo::new(), &env(), Platform::Windows);
+        assert!(probe.is_empty(), "全部失败要返回空列表而不是错误");
+        let notes = probe.notes().join("\n");
+        assert!(notes.contains("reg query"), "注册表失败要留原因：{notes}");
+        assert!(
+            notes.contains("CurrentTheme"),
+            "当前主题失败要留原因：{notes}"
+        );
+        assert!(
+            notes.contains("TranscodedWallpaper"),
+            "转码副本缺失要留原因：{notes}"
+        );
+    }
+
+    #[test]
+    fn same_path_from_two_steps_is_deduped() {
+        let transcoded = themes().join("TranscodedWallpaper");
+        let registry_value = transcoded.display().to_string().to_ascii_uppercase();
+        let io = FakeIo::new()
+            .with_image(&transcoded)
+            // 注册表指向同一个文件，大小写还不同（Windows 路径大小写不敏感）。
+            .with_command(
+                DESKTOP_QUERY,
+                &format!("    WallPaper    REG_SZ    {registry_value}\r\n"),
+            );
+        let probe = detect_with(&io, &env(), Platform::Windows);
+        assert_eq!(probe.len(), 1, "{:?}", probe.sources());
+        assert_eq!(
+            probe.best().expect("有候选").kind,
+            SourceKind::WindowsTranscoded
+        );
+    }
+}
diff --git a/crates/core/src/platform/wallpaper/windows/parse.rs b/crates/core/src/platform/wallpaper/windows/parse.rs
new file mode 100644
index 0000000..c737e72
--- /dev/null
+++ b/crates/core/src/platform/wallpaper/windows/parse.rs
@@ -0,0 +1,100 @@
+//! Windows 侧的纯解析函数：`.theme` 的 `Wallpaper=` 行与 `reg query` 输出的取值。
+//!
+//! 单独一个文件只为守住「单文件 ≤400 行」（`guards.yml` 的 file-size 闸）：这里没有任何
+//! IO，全部是纯函数，跨平台编译，夹具用例覆盖在文件尾部。
+
+/// 取 `.theme` 文本里所有 `Wallpaper=` 行的值（键名大小写不敏感，值去首尾空白）。
+///
+/// `.theme` 是 INI：`[Control Panel\Desktop]` 段下的 `Wallpaper=...`。`Wallpaper` 这个键名
+/// 本身不随系统语言变（Windows 只本地化少数键），所以直接按 ASCII 比对。
+pub(super) fn parse_theme_wallpaper(text: &str) -> Vec {
+    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..bc9fd9b
--- /dev/null
+++ b/crates/core/src/platform/windows_version.rs
@@ -0,0 +1,215 @@
+//! Windows 版本探测：真实的 `major.minor.build`（D19 · `PlanDoc/11-os-detection.md` §2）。
+//!
+//! 数据源（从快到慢，探测发生在启动路径上）：
+//!
+//! 1. `reg query ... /v CurrentBuildNumber` 取 build 号，由 [`from_build`] 反推 `major.minor`
+//!    （build 号在版本族内单调；实测单值查询约 50ms，整键查询约 150ms）；
+//! 2. 整键 `HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion`：Win10+ 有
+//!    `CurrentMajorVersionNumber` / `CurrentMinorVersionNumber`（REG_DWORD，`reg query` 以
+//!    `0x..` 十六进制输出），Win7 / 8 / 8.1 只有 `CurrentVersion`（`6.1` / `6.2` / `6.3`，
+//!    Win10+ 上它是过期值）；
+//! 3. 兜底 `cmd /c ver`：输出 `Microsoft Windows [Version 10.0.19045.4046]`（中文系统为
+//!    `[版本 …]`）。只取方括号内的数字段，因此与系统语言无关。
+//!
+//! # 为什么不用 `RtlGetVersion`
+//!
+//! D19 原文方案是 `RtlGetVersion`（ntdll），但 core 是 `#![forbid(unsafe_code)]`
+//! （`lib.rs`，D3 架构纪律 + workspace lint `unsafe_code = deny`），FFI 一律不可用。
+//! 上面两条路径读的是同一份真实事实（`cmd.exe` 自带 manifest，报真实版本，不受
+//! `GetVersionEx` 兼容层欺骗），差别只是启动时一次性几毫秒 —— 结果由
+//! [`crate::platform::os_info::current`] 缓存，不会重复付这个代价。
+//!
+//! 解析函数是纯函数且**跨平台编译**，单测用注入样本覆盖各版本输出（见 `tests/platform/`）。
+
+/// Windows 11 的起始 build 号（22H2 之前就有 22000）。
+pub const WIN11_MIN_BUILD: u32 = 22_000;
+
+/// 存放版本值的注册表键。
+pub const VERSION_KEY: &str = r"HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion";
+
+/// Windows 真实版本。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct WindowsVersion {
+    /// 主版本号（Win7 = 6，Win10/11 = 10）。
+    pub major: u32,
+    /// 次版本号（Win7 = 1，Win10/11 = 0）。
+    pub minor: u32,
+    /// 构建号（Win7 SP1 = 7601，Win10 22H2 = 19045，Win11 = 22000+）。
+    pub build: u32,
+}
+
+impl WindowsVersion {
+    /// 构造。
+    pub fn new(major: u32, minor: u32, build: u32) -> Self {
+        Self {
+            major,
+            minor,
+            build,
+        }
+    }
+
+    /// `major.minor` 元组（最低版本判定用）。
+    pub fn major_minor(&self) -> (u32, u32) {
+        (self.major, self.minor)
+    }
+
+    /// 版本串（`rules.os.version` 用，例如 `10.0.19045`）。
+    pub fn version_string(&self) -> String {
+        format!("{}.{}.{}", self.major, self.minor, self.build)
+    }
+
+    /// 产品名（由版本号推导，不用本地化的注册表 `ProductName`）。
+    pub fn display_name(&self) -> &'static str {
+        match self.major_minor() {
+            (10, _) if self.build >= WIN11_MIN_BUILD => "Windows 11",
+            (10, _) => "Windows 10",
+            (6, 3) => "Windows 8.1",
+            (6, 2) => "Windows 8",
+            (6, 1) => "Windows 7",
+            (6, 0) => "Windows Vista",
+            (5, _) => "Windows XP",
+            _ => "Windows",
+        }
+    }
+}
+
+/// 真实探测；非 Windows 平台恒为 `None`。
+///
+/// 三档，从快到慢（探测在启动路径上，实测整键 `reg query` 会枚举上百个子键，约 150ms：
+/// 单值查询约 50ms）：
+/// 1. `reg query ... /v CurrentBuildNumber` 取 build，再由 [`from_build`] 反推 `major.minor`；
+/// 2. 整键查询（Win7 的 `CurrentVersion`、Win10+ 的数字键都在这里解析，见 [`parse_reg_query`]）；
+/// 3. `cmd /c ver`（注册表被策略禁用时的兜底）。
+#[cfg(target_os = "windows")]
+pub fn probe() -> Option {
+    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 {
+    use std::process::Command;
+    let output = Command::new(program).args(args).output().ok()?;
+    if output.stdout.is_empty() {
+        return None;
+    }
+    Some(String::from_utf8_lossy(&output.stdout).into_owned())
+}
diff --git a/crates/core/src/setting/appearance/mod.rs b/crates/core/src/setting/appearance/mod.rs
new file mode 100644
index 0000000..e104f57
--- /dev/null
+++ b/crates/core/src/setting/appearance/mod.rs
@@ -0,0 +1,307 @@
+//! 「外观（高级）」配置簇的读写（D17 · `09-ui-layout.md` §2 G6 + §111 约束）。
+//!
+//! 为什么放在 core：主题令牌的**取值与校验**是配置事实，视觉实现（Slint 侧）只消费结果。
+//! 分层纪律要求 core 零 UI 依赖——本文件只认 `appearance.*` 这些键与它们的取值形状，
+//! 不认任何像素/控件（[`super::keys`] 登记同一份键表，两边由 `tests/setting/appearance_keys.rs` 固定）。
+//!
+//! 设计约束（09 §111）：一切高级特性**默认关闭**（出厂 Metro 纯色）；全部走 D6 schema
+//! （AI 可写白名单内，可被 agent 调节）。因此默认值必须等于「什么都没开」的出厂态：
+//! `panel_alpha = 1.0`、`glass = false`、`bg_image_enabled = false`、`accent` 空串（= 出厂 accent）。
+//!
+//! P4 追加的三个「下层键」（M91 / D34·D36·D37·D38，同样是**出厂即可见**的默认值）：
+//!
+//! | 键 | 取值 | 出厂 | 本模块负责 / 不负责 |
+//! |---|---|---|---|
+//! | `appearance.window_opacity` | `0.08..=1.0` | `1.0` | 负责钳位；**不**调 FFI（落点在 `app-iced` 的 win32 层） |
+//! | `appearance.titlebar_mode` | `auto` / `always` / `never` | `auto` | 只存值；`auto` 的判定属于 UI 侧（WCHROME-IMPL） |
+//! | `appearance.palette_source` | `background-image` / `wallpaper` / `preset` | `preset` | 只存档位；三级编排在 `unlucky-design`（D38） |
+//! | `appearance.window_corner` | `system` / `square` | `system` | 只存策略；「这台机器能不能圆」的判定在 `app-iced` 的 `platform`（M116） |
+//!
+//! 非法枚举**不报错**但也**不静默**：[`diagnostics`] 给出「读到什么 → 生效什么」的可读说明。
+
+use serde_json::Value;
+
+use super::document::SettingDocument;
+use super::store::SettingStore;
+
+mod modes;
+
+pub use modes::{
+    diagnostics, AppearanceDiagnostic, PaletteSource, TitlebarMode, WindowCorner, PALETTE_SOURCES,
+    TITLEBAR_MODES, WINDOW_CORNERS,
+};
+
+#[cfg(test)]
+mod tests;
+
+/// `appearance.bg_fill` 的允许值（09 §101：cover / contain / tile）。**顺序即 UI 分段控件的顺序**。
+pub const BG_FILLS: &[&str] = &["cover", "contain", "tile"];
+
+/// 出厂强调色（Metro 蓝，D14）；`appearance.accent_color` 为空串时用它。
+pub const DEFAULT_ACCENT: &str = "#0078D4";
+
+/// `appearance.panel_alpha` 下限：再低前景就压不住背景图（09 §111「对比度检查提示」的硬底）。
+pub const PANEL_ALPHA_MIN: f64 = 0.4;
+/// `appearance.bg_dim` 下限（0 = 不暗化，允许但设置页会提示对比度风险）。
+pub const BG_DIM_MIN: f64 = 0.0;
+/// `appearance.bg_dim` 上限：再高背景图基本看不见，等于关掉。
+pub const BG_DIM_MAX: f64 = 0.95;
+
+/// `appearance.window_opacity` 下限（D36 定案 0.08）：这是**整窗** α 的硬底。
+///
+/// 为什么不是 0：α = 0 时窗口内容整体不可见 = 整窗穿透，用户会以为程序卡死/消失了。
+/// 0.08 是「几乎看不见但仍能点到」的最后一档，比它更低不给设置。面板 α（[`PANEL_ALPHA_MIN`]）
+/// 是另一回事，两者互不推导。
+pub const WINDOW_ALPHA_MIN: f64 = 0.08;
+
+/// 背景图填充模式。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum BgFill {
+    /// 等比铺满、裁切溢出（默认：不露底色）
+    #[default]
+    Cover,
+    /// 等比完整显示、留底色
+    Contain,
+    /// 原始尺寸平铺
+    Tile,
+}
+
+impl BgFill {
+    /// 落盘取值。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Cover => "cover",
+            Self::Contain => "contain",
+            Self::Tile => "tile",
+        }
+    }
+
+    /// 从落盘取值解析；未知值按 `cover` 兜底（手改坏配置也不崩）。
+    #[must_use]
+    pub fn from_key_value(value: &str) -> Self {
+        match value {
+            "contain" => Self::Contain,
+            "tile" => Self::Tile,
+            _ => Self::Cover,
+        }
+    }
+}
+
+/// 外观（高级）配置簇：**只是取值快照**，读写都走 [`super::store::SettingStore`]。
+#[derive(Debug, Clone, PartialEq)]
+pub struct Appearance {
+    /// 主题三态：`auto` / `light` / `dark`（与 `prefs::ThemeMode` 同名同值）。
+    pub theme_mode: String,
+    /// 自定义窗口背景图开关（默认关）。
+    pub bg_image_enabled: bool,
+    /// 背景图路径（PNG；空 = 未设置）。
+    pub bg_image: String,
+    /// 背景图填充模式。
+    pub bg_fill: BgFill,
+    /// 叠加暗化层强度 0.0~0.95（越大前景越清晰）。
+    pub bg_dim: f64,
+    /// 全局面板半透明度 0.4~1.0（1.0 = 出厂不透明）。
+    pub panel_alpha: f64,
+    /// 玻璃拟态卡片（预生成模糊背景层）。
+    pub glass: bool,
+    /// 自定义强调色 `#RRGGBB`（空串 = 出厂 [`DEFAULT_ACCENT`]）。
+    pub accent_color: String,
+    /// 整窗透明度 [`WINDOW_ALPHA_MIN`]~1.0（1.0 = 出厂完全不透明；D36）。
+    ///
+    /// 只管取值：真正的窗口 α 由 `unlucky-app-iced` 的 win32 层调
+    /// `SetLayeredWindowAttributes(LWA_ALPHA)` 落地，core 不碰 FFI。
+    pub window_opacity: f64,
+    /// 标题栏三态（D37）。`auto` 怎么判定属于 UI 侧，core 只存用户的选择。
+    pub titlebar_mode: TitlebarMode,
+    /// 配色来源档（D38 三级；默认 [`PaletteSource::Preset`] = 内置色卡）。
+    pub palette_source: PaletteSource,
+    /// 窗口外框圆角策略（M116；默认 [`WindowCorner::System`] = 跟随系统）。
+    ///
+    /// 只管用户要什么：真能不能圆由平台决定（Win11/Server 2025 走 DWM，Win10 保持直角），
+    /// 判定在 `unlucky-app-iced` 的 `platform`，core 不探测系统。
+    pub window_corner: WindowCorner,
+}
+
+impl Default for Appearance {
+    fn default() -> Self {
+        Self {
+            theme_mode: "auto".to_owned(),
+            bg_image_enabled: false,
+            bg_image: String::new(),
+            bg_fill: BgFill::Cover,
+            bg_dim: 0.35,
+            panel_alpha: 1.0,
+            glass: false,
+            accent_color: String::new(),
+            window_opacity: 1.0,
+            titlebar_mode: TitlebarMode::Auto,
+            palette_source: PaletteSource::Preset,
+            window_corner: WindowCorner::System,
+        }
+    }
+}
+
+impl Appearance {
+    /// 从配置文档读一份快照（文件值 → 默认值；坏值按默认值兜底，绝不 panic）。
+    #[must_use]
+    pub fn read(doc: &SettingDocument) -> Self {
+        let default = Self::default();
+        let text = |key: &str| doc.effective_str(key).map(str::to_owned);
+        let boolean = |key: &str| doc.effective(key).and_then(Value::as_bool);
+        let number = |key: &str| doc.effective(key).and_then(Value::as_f64);
+
+        Self {
+            theme_mode: text("appearance.theme_mode").unwrap_or(default.theme_mode),
+            bg_image_enabled: boolean("appearance.bg_image_enabled").unwrap_or(false),
+            bg_image: text("appearance.bg_image").unwrap_or_default(),
+            bg_fill: text("appearance.bg_fill")
+                .map_or(default.bg_fill, |value| BgFill::from_key_value(&value)),
+            bg_dim: number("appearance.bg_dim")
+                .map_or(default.bg_dim, |value| clamp(value, BG_DIM_MIN, BG_DIM_MAX)),
+            panel_alpha: number("appearance.panel_alpha").map_or(default.panel_alpha, |value| {
+                clamp(value, PANEL_ALPHA_MIN, 1.0)
+            }),
+            glass: boolean("appearance.glass").unwrap_or(false),
+            accent_color: text("appearance.accent_color")
+                .map(|value| normalize_hex(&value).unwrap_or_default())
+                .unwrap_or_default(),
+            window_opacity: number("appearance.window_opacity")
+                .map_or(default.window_opacity, |value| {
+                    clamp(value, WINDOW_ALPHA_MIN, 1.0)
+                }),
+            titlebar_mode: text("appearance.titlebar_mode")
+                .map_or(default.titlebar_mode, |value| {
+                    TitlebarMode::from_key_value(&value)
+                }),
+            palette_source: text("appearance.palette_source")
+                .map_or(default.palette_source, |value| {
+                    PaletteSource::from_key_value(&value)
+                }),
+            window_corner: text("appearance.window_corner")
+                .map_or(default.window_corner, |value| {
+                    WindowCorner::from_key_value(&value)
+                }),
+        }
+    }
+
+    /// 从 store 读（配置读写的统一入口）。
+    #[must_use]
+    pub fn from_store(store: &SettingStore) -> Self {
+        Self::read(store.doc())
+    }
+
+    /// 实际生效的强调色：未自定义时回落到出厂 accent。
+    #[must_use]
+    pub fn accent_or_default(&self) -> &str {
+        if self.accent_color.is_empty() {
+            DEFAULT_ACCENT
+        } else {
+            &self.accent_color
+        }
+    }
+
+    /// 背景图是否真的会用上（开关打开 **且** 路径非空）。
+    #[must_use]
+    pub fn bg_image_active(&self) -> bool {
+        self.bg_image_enabled && !self.bg_image.trim().is_empty()
+    }
+
+    /// 写回一组键（调用方负责 `save()`；默认值不落盘由 `SettingDocument` 决定）。
+    ///
+    /// 值先过一遍规范化：`bg_fill` 认枚举、`bg_dim`/`panel_alpha` 夹到范围内、
+    /// `accent_color` 只接受 `#RRGGBB`（空串表示清掉自定义）。
+    ///
+    /// # Errors
+    /// 键值被 schema 拒绝（只读文件 / 未知键 / 越界）时返回 [`super::error::SettingError`]。
+    pub fn write(&self, store: &mut SettingStore) -> super::error::SettingResult<()> {
+        store.set(
+            "appearance.theme_mode",
+            Value::from(self.theme_mode.as_str()),
+        )?;
+        store.set(
+            "appearance.bg_image_enabled",
+            Value::from(self.bg_image_enabled),
+        )?;
+        store.set("appearance.bg_image", Value::from(self.bg_image.as_str()))?;
+        store.set("appearance.bg_fill", Value::from(self.bg_fill.as_str()))?;
+        store.set(
+            "appearance.bg_dim",
+            Value::from(clamp(self.bg_dim, BG_DIM_MIN, BG_DIM_MAX)),
+        )?;
+        store.set(
+            "appearance.panel_alpha",
+            Value::from(clamp(self.panel_alpha, PANEL_ALPHA_MIN, 1.0)),
+        )?;
+        store.set("appearance.glass", Value::from(self.glass))?;
+        store.set(
+            "appearance.accent_color",
+            Value::from(self.accent_color.as_str()),
+        )?;
+        // 越界钳位而不是报错（D36）：α 的下限是硬底，不许把窗口写到穿透；
+        // 上限 1.0 = 完全不透明。非法枚举（titlebar_mode / palette_source）由
+        // `as_str()` 保证永远是合法字面量，不会写坏文件。
+        store.set(
+            "appearance.window_opacity",
+            Value::from(clamp(self.window_opacity, WINDOW_ALPHA_MIN, 1.0)),
+        )?;
+        store.set(
+            "appearance.titlebar_mode",
+            Value::from(self.titlebar_mode.as_str()),
+        )?;
+        store.set(
+            "appearance.palette_source",
+            Value::from(self.palette_source.as_str()),
+        )?;
+        store.set(
+            "appearance.window_corner",
+            Value::from(self.window_corner.as_str()),
+        )?;
+        Ok(())
+    }
+}
+
+/// `#RRGGBB` 规范化（大写、去空格）；不合法返回 `None`。
+#[must_use]
+pub fn normalize_hex(text: &str) -> Option {
+    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..2535618
--- /dev/null
+++ b/crates/core/src/setting/catalog.rs
@@ -0,0 +1,195 @@
+//! 一份配置文件的键目录：[`SettingSchema`] 把 key → 元数据查表能力收拢在一处。
+//!
+//! 与 [`super::spec`] 的分工：`spec` 定义「一个键长什么样」，这里定义「一份文件的键集合」，
+//! 并对外提供 AI 白名单 / 校验 / 工具 JSON Schema 投影（M16 `ToolSpec` 直接吃这份投影）。
+
+use std::collections::BTreeSet;
+
+use serde_json::{json, Map, Value};
+
+use super::error::{SettingError, SettingResult};
+use super::schema::{SchemaId, SchemaRef, SchemaVersion};
+use super::spec::{Sensitivity, SettingSpec};
+
+/// 一份配置文件里所有键的集合。
+#[derive(Debug, Clone, PartialEq)]
+pub struct SettingSchema {
+    id: SchemaId,
+    version: SchemaVersion,
+    specs: Vec,
+}
+
+impl SettingSchema {
+    /// 空 schema。
+    #[must_use]
+    pub fn new(id: SchemaId, version: SchemaVersion) -> Self {
+        Self {
+            id,
+            version,
+            specs: Vec::new(),
+        }
+    }
+
+    /// 链式加一个键（重复键直接 panic —— 这是编译期就该发现的表写错）。
+    #[must_use]
+    pub fn with(mut self, spec: SettingSpec) -> Self {
+        assert!(
+            !self.specs.iter().any(|existing| existing.key == spec.key),
+            "重复的配置键: {}",
+            spec.key
+        );
+        self.specs.push(spec);
+        self
+    }
+
+    /// 种类。
+    #[must_use]
+    pub const fn id(&self) -> SchemaId {
+        self.id
+    }
+
+    /// 版本。
+    #[must_use]
+    pub const fn version(&self) -> SchemaVersion {
+        self.version
+    }
+
+    /// `$schema` 标识。
+    #[must_use]
+    pub const fn schema_ref(&self) -> SchemaRef {
+        SchemaRef::new(self.id, self.version)
+    }
+
+    /// 全部键元数据。
+    #[must_use]
+    pub fn specs(&self) -> &[SettingSpec] {
+        &self.specs
+    }
+
+    /// 按键名取元数据。
+    #[must_use]
+    pub fn spec(&self, key: &str) -> Option<&SettingSpec> {
+        self.specs.iter().find(|spec| spec.key == key)
+    }
+
+    /// 是否定义了该键。
+    #[must_use]
+    pub fn is_known(&self, key: &str) -> bool {
+        self.spec(key).is_some()
+    }
+
+    /// 是否是某个已知键的**前缀路径**（用于区分「嵌套对象」与「陌生整棵子树」）。
+    #[must_use]
+    pub fn has_prefix(&self, segments: &[&str]) -> bool {
+        let mut prefix = segments.join(".");
+        prefix.push('.');
+        self.specs.iter().any(|spec| spec.key.starts_with(&prefix))
+    }
+
+    /// 默认值。
+    #[must_use]
+    pub fn default_value(&self, key: &str) -> Option<&Value> {
+        self.spec(key).map(|spec| &spec.default)
+    }
+
+    /// 校验一个键值对。
+    ///
+    /// # Errors
+    /// 未定义的键 → [`SettingError::UnknownKey`]；值不合法 → [`SettingError::InvalidValue`]。
+    pub fn validate(&self, key: &str, value: &Value) -> SettingResult<()> {
+        let spec = self.spec(key).ok_or_else(|| SettingError::UnknownKey {
+            key: key.to_owned(),
+        })?;
+        spec.kind
+            .check(value)
+            .map_err(|reason| SettingError::InvalidValue {
+                key: key.to_owned(),
+                reason,
+            })
+    }
+
+    /// AI 可写键白名单（供 M16 `set_config` 前置检查）。
+    #[must_use]
+    pub fn ai_writable_keys(&self) -> Vec<&'static str> {
+        self.specs
+            .iter()
+            .filter(|spec| spec.ai.writable && !spec.is_deprecated())
+            .map(|spec| spec.key)
+            .collect()
+    }
+
+    /// AI 是否允许写该键（未定义的键 = 不允许）。
+    #[must_use]
+    pub fn accepts_ai_write(&self, key: &str) -> bool {
+        self.spec(key)
+            .is_some_and(|spec| spec.ai.writable && !spec.is_deprecated())
+    }
+
+    /// 已废弃键清单（只读兼容，不再落盘）。
+    #[must_use]
+    pub fn deprecated_keys(&self) -> Vec<&'static str> {
+        self.specs
+            .iter()
+            .filter(|spec| spec.is_deprecated())
+            .map(|spec| spec.key)
+            .collect()
+    }
+
+    /// 某键的替代键（不是废弃键则 `None`）。
+    #[must_use]
+    pub fn replacement_of(&self, key: &str) -> Option<&'static str> {
+        self.spec(key)?.deprecated.map(|info| info.replaced_by)
+    }
+
+    /// 敏感分级。
+    #[must_use]
+    pub fn sensitivity(&self, key: &str) -> Option {
+        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..aaa7948
--- /dev/null
+++ b/crates/core/src/setting/instance_keys.rs
@@ -0,0 +1,155 @@
+//! `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"];
+
+/// 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 白名单，拼错即校验失败）",
+        ))
+        .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(),
+            "该次切换的提示是否已展示过（保证切换后首次启动只提示一次）",
+        ))
+}
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..5e31902
--- /dev/null
+++ b/crates/core/src/setting/keys.rs
@@ -0,0 +1,398 @@
+//! `config/launcher.json` 的键表（全局设置）。
+//!
+//! 键名与默认值对齐 `DevDocs/PlanDoc/04-data-and-config.md` §2-§3 与 `05/06/07/08` 各专题；
+//! AI 可写 + 敏感分级按 `02-ai-agent-design.md` §3.1 的边界落：**密钥类一律 locked**。
+
+use super::catalog::SettingSchema;
+use super::schema::{SchemaId, SchemaVersion};
+use super::spec::{AiPolicy, SettingSpec};
+
+/// `core.data_mode` 允许值。
+pub const DATA_MODES: &[&str] = &["portable", "standard", "custom"];
+/// `download.region` 允许值。
+pub const REGIONS: &[&str] = &["auto", "cn", "global"];
+/// `download.mirror_preference` 允许值。
+pub const MIRROR_PREFERENCES: &[&str] = &["auto", "official", "mirror"];
+/// `download.proxy_mode` 允许值。
+pub const PROXY_MODES: &[&str] = &["none", "system", "manual"];
+/// `ai.provider` 允许值。
+pub const AI_PROVIDERS: &[&str] = &["openai_compatible", "anthropic", "ollama", "disabled"];
+/// `ui.language` 允许值。
+pub const LANGUAGES: &[&str] = &["zh_cn", "en_us"];
+/// `appearance.theme_mode` 允许值（D17 定案：auto/light/dark）。
+pub const THEME_MODES: &[&str] = &["auto", "light", "dark"];
+/// `ui.theme` 的旧允许值（该键已废弃，仅读兼容，不再落盘）。
+pub const LEGACY_THEMES: &[&str] = &["system", "metro_light", "metro_dark"];
+/// 旧 `ui.theme` 值 → 新 `appearance.theme_mode` 值（tower 键冲突裁决的读兼容映射）。
+pub const THEME_ALIASES: &[(&str, &str)] = &[
+    ("system", "auto"),
+    ("metro_light", "light"),
+    ("metro_dark", "dark"),
+];
+/// `log.level` 允许值。
+pub const LOG_LEVELS: &[&str] = &["error", "warn", "info", "debug", "trace"];
+/// `instances.mode` 允许值（D20 定案：默认隔离，用户可手动切共享）。
+pub const INSTANCE_MODES: &[&str] = &["isolated", "shared"];
+/// `java.installRoot` 未设置时的哨兵（空串 = 按数据目录模式派生落点）。
+pub const JAVA_INSTALL_ROOT_UNSET: &str = "";
+/// `java.vendorPriority` 的允许值（D23：四家发行版，顺序即优先级）。
+///
+/// 与 `crate::game::java::vendor::VENDOR_IDS` 必须是同一份集合——setting 层不依赖 game 层
+/// （分层纪律），一致性由 `tests/setting/java_install_keys.rs` 的契约测试固定。
+pub const JDK_VENDORS: &[&str] = &["temurin", "oracle", "microsoft", "zulu"];
+
+/// launcher.json 当前 schema 版本。
+///
+/// `1.1.0` 登记 D20 实例隔离键（`instances.mode` 等）。
+/// `1.2.0` 登记 D23 的 JDK 落点与发行版优先级键（`java.installRoot` / `java.vendorPriority`）：
+/// 同样只推 minor、不强制迁移——[`super::document`] 的「默认值不落盘」让老文件缺键即取默认，
+/// 迁移链（按 major 走）不需要新步骤；`1.1.0 → 1.2.0` 的差异只体现在文件里出现新键之后。
+/// `1.3.0` 登记 D17 的「外观（高级）」P1 键（`appearance.bg_image*` / `panel_alpha` / `glass` /
+/// `accent_color`）：同一套纯增量语义——出厂全默认（高级特性全关）即等于老文件缺键。
+/// `1.4.0` 登记 P4 的外观下层三键（`appearance.window_opacity` / `titlebar_mode` /
+/// `palette_source`，M91 · D36/D37/D38）：仍然只推 minor、不加迁移步骤——三者的出厂值
+/// （不透明 / auto / 内置色卡）正是「老文件没有这些键」时的等价物。
+/// `1.5.0` 登记 M116 的窗口圆角策略（`appearance.window_corner`，出厂 `system`）：
+/// 同一套纯增量语义——**新读旧**：老文件缺该键 ⇒ 读默认 `system` ⇒ 跟随系统，与写进文件后行为一致。
+///
+/// **旧读新（方向相反，措辞必须精确）**：1.4.0 的客户端读 1.5.0 的文件时，
+/// [`super::schema::SchemaCompat::check_url`] 走 `found.minor > expected.minor` →
+/// `ReadOnlyPreserveSchema` → [`super::schema::SchemaCompat::access`] → `FileAccess::ReadOnly`。
+/// 也就是说**整份配置对它只读**（值照读、`store.set` 一律 `SettingError::ReadOnly`、
+/// `save` 跳过），不是「只是少一档」。这是 minor 提升的既定代价——也正是这条键必须推 minor
+/// 而不是偷偷塞进 1.4.0 的原因：回退到旧版本会出现「设置改不动」，而原因只在
+/// `$schema` 那一行里，不看版本号无从排查。
+#[must_use]
+pub fn launcher_version() -> SchemaVersion {
+    SchemaVersion::new(1, 5, 0)
+}
+
+/// `config/launcher.json` 的 schema。
+#[must_use]
+pub fn launcher_schema() -> SettingSchema {
+    SettingSchema::new(SchemaId::LAUNCHER, launcher_version())
+        .with(SettingSpec::enumeration(
+            "core.data_mode",
+            "portable",
+            DATA_MODES,
+            AiPolicy::sensitive(),
+            "数据目录模式：portable（exe 旁）/ standard（系统标准目录）/ custom（自定义）",
+        ))
+        .with(SettingSpec::path(
+            "core.data_custom_root",
+            AiPolicy::sensitive(),
+            "custom 模式的根目录（必须是绝对路径）",
+        ))
+        .with(SettingSpec::path(
+            "core.launcher_home",
+            AiPolicy::sensitive(),
+            "显式覆盖启动器数据目录（.ULL 的等价物）",
+        ))
+        .with(SettingSpec::path(
+            "core.game_home",
+            AiPolicy::sensitive(),
+            "游戏目录（.minecraft），与数据目录分离指定",
+        ))
+        // D20（research/04 §5.1）：只留一个全局默认档，实例级 override 在
+        // `instance_keys::instance_schema`（`isolation`），派生逻辑在 `game::isolation`。
+        .with(SettingSpec::enumeration(
+            "instances.mode",
+            "isolated",
+            INSTANCE_MODES,
+            AiPolicy::sensitive(),
+            "实例默认隔离模式：isolated（运行目录派生 versions/<版本 id>，D20 默认）/ shared（所有实例共用 .minecraft 根）",
+        ))
+        .with(SettingSpec::int(
+            "download.concurrency",
+            8,
+            (1, 256),
+            AiPolicy::silent(),
+            "下载并发数",
+        ))
+        .with(SettingSpec::int(
+            "download.retry_limit",
+            3,
+            (0, 10),
+            AiPolicy::silent(),
+            "单个文件重试次数",
+        ))
+        .with(SettingSpec::enumeration(
+            "download.region",
+            "auto",
+            REGIONS,
+            AiPolicy::audited(),
+            "下载地区判定：auto（时区+语言+探测）/ cn / global",
+        ))
+        .with(SettingSpec::enumeration(
+            "download.mirror_preference",
+            "auto",
+            MIRROR_PREFERENCES,
+            AiPolicy::audited(),
+            "镜像偏好：auto（健康度评分）/ official（官方源优先）/ mirror（镜像优先）",
+        ))
+        .with(SettingSpec::enumeration(
+            "download.proxy_mode",
+            "none",
+            PROXY_MODES,
+            AiPolicy::sensitive(),
+            "代理模式：none / system / manual",
+        ))
+        .with(SettingSpec::text(
+            "download.proxy_url",
+            "",
+            512,
+            AiPolicy::sensitive(),
+            "manual 代理地址（如 http://127.0.0.1:7890）",
+        ))
+        .with(SettingSpec::path(
+            "java.selected_path",
+            AiPolicy::sensitive(),
+            "用户选定的 Java 可执行文件路径",
+        ))
+        .with(SettingSpec::bool(
+            "java.auto_install",
+            true,
+            AiPolicy::audited(),
+            "缺 Java 时自动下载（D13 基准 JDK17）",
+        ))
+        // D23：托管 JDK 的落点三模式。语义在 `game::java::location`：
+        // 未设置（空串）→ 按 `core.data_mode` 派生（Portable 数据根 / Standard 系统目录）；
+        // 设置了 → 覆盖前两者，按 `/` 分层。
+        .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（空 = 出厂 #0078D4；accent 令牌全域生效）",
+        ))
+        // M91（P4 / D36·D37·D38）：「外观下层」三键——只登记取值与范围，判定与落地都在 UI 侧。
+        // 分级同 D17 那批（audited/Medium）：纯视觉、可一键复原，但要留审计痕迹。
+        .with(SettingSpec::float(
+            "appearance.window_opacity",
+            1.0,
+            (super::appearance::WINDOW_ALPHA_MIN, 1.0),
+            AiPolicy::audited(),
+            "整窗透明度 0.08~1.0（1.0 = 完全不透明；下限 0.08 是为了不把窗口写到穿透，D36）",
+        ))
+        .with(SettingSpec::enumeration(
+            "appearance.titlebar_mode",
+            "auto",
+            super::appearance::TITLEBAR_MODES,
+            AiPolicy::audited(),
+            "标题栏三态：auto（按合成器判定）/ always（总是自绘）/ never（合成器已装饰），默认 auto（D37）",
+        ))
+        .with(SettingSpec::enumeration(
+            "appearance.palette_source",
+            "preset",
+            super::appearance::PALETTE_SOURCES,
+            AiPolicy::audited(),
+            "配色来源档（D38 三级）：background-image（背景图取色）/ wallpaper（桌面壁纸取色）/ preset（内置色卡，默认）",
+        ))
+        // M116：窗口外框圆角策略。只有两档（system / square）——系统不暴露圆角半径，
+        // 「固定 8/12/16」只能是自绘圆角，而自绘圆角在无边框 + 整窗 α 上要裁内容层，
+        // 会连标题栏三键与缩放热区一起裁掉（用户定案 2026-11-03）。
+        .with(SettingSpec::enumeration(
+            "appearance.window_corner",
+            "system",
+            super::appearance::WINDOW_CORNERS,
+            AiPolicy::audited(),
+            "窗口圆角：system（跟随系统：Win11/Server 2025 走 DWM，Win10 保持直角）/ square（总是直角），默认 system",
+        ))
+        // 已废弃：D17 定案 appearance.theme_mode 为准（旧值读兼容映射，写永远走新键）。
+        .with(
+            SettingSpec::new(
+                "ui.theme",
+                super::spec::ValueKind::Enum(LEGACY_THEMES),
+                serde_json::Value::Null,
+                AiPolicy::retired(),
+                "【已废弃】改用 appearance.theme_mode；旧值读兼容：system→auto / metro_light→light / metro_dark→dark",
+            )
+            .deprecated("appearance.theme_mode", THEME_ALIASES),
+        )
+        .with(SettingSpec::float(
+            "ui.scale",
+            1.0,
+            (0.75, 2.0),
+            AiPolicy::silent(),
+            "界面缩放系数",
+        ))
+        .with(SettingSpec::int(
+            "ui.window.width",
+            1280,
+            (320, 16384),
+            AiPolicy::silent(),
+            "主窗口宽度（逻辑像素）",
+        ))
+        .with(SettingSpec::int(
+            "ui.window.height",
+            800,
+            (200, 16384),
+            AiPolicy::silent(),
+            "主窗口高度（逻辑像素）",
+        ))
+        .with(SettingSpec::enumeration(
+            "log.level",
+            "info",
+            LOG_LEVELS,
+            AiPolicy::audited(),
+            "启动器日志级别",
+        ))
+}
diff --git a/crates/core/src/setting/migrate.rs b/crates/core/src/setting/migrate.rs
new file mode 100644
index 0000000..03bd13a
--- /dev/null
+++ b/crates/core/src/setting/migrate.rs
@@ -0,0 +1,222 @@
+//! 迁移链：`schemaVersion N → N+1` 顺序迁移框架 + 收据闸门（防重放）。
+//!
+//! 出处：`DevDocs/PlanDoc/04-data-and-config.md` §3（迁移链 + 迁移收据）、
+//! `DevDocs/analyse/07-settings-packaging-update.md` §1.8（收据存源文件 `sourceSHA256`）。
+//!
+//! 与 HMCL 的差别：HMCL 完全靠 `$schema` 字段做兼容、迁移只处理遗留格式；ULL 在这之上补一条
+//! 「major 逐级迁移链」——每一步只跨一个 major，缺环/重复/逆序在 `push` 时就报错，
+//! 避免出现「跳版迁移脚本」这种组合爆炸。
+
+use std::path::Path;
+
+use serde_json::{Map, Value};
+
+use crate::platform::error::PlatformResult;
+use crate::platform::receipt::{self, MigrationReceipt, ReplayDecision};
+
+use super::error::{SettingError, SettingResult};
+use super::schema::{SchemaVersion, SCHEMA_VERSION_KEY};
+
+/// 一步迁移。实现者只管把 `root` 从 `from` 改造成 `to`。
+pub trait SettingMigration: Send + Sync {
+    /// 起始版本。
+    fn from(&self) -> SchemaVersion;
+    /// 目标版本（必须等于 `from.next_major()`）。
+    fn to(&self) -> SchemaVersion;
+    /// 一句话说明（进日志与迁移报告）。
+    fn describe(&self) -> &'static str;
+    /// 就地改 JSON 对象；`Err(String)` 会被包成 [`SettingError::Migration`]。
+    ///
+    /// # Errors
+    /// 结构不符合预期（该有的键没有/类型不对）时返回原因。
+    fn apply(&self, root: &mut Map) -> 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..f968aae
--- /dev/null
+++ b/crates/core/src/setting/mod.rs
@@ -0,0 +1,36 @@
+//! 配置与数据目录：三模式数据根（Portable 默认 / Standard / Custom）、schema 化配置、原子写、迁移收据。
+//!
+//! 设计定稿：`DevDocs/PlanDoc/04-data-and-config.md`（决策 D6）。
+//! 刻意把 setting 放在 core 而不是 UI 层——这是 HMCL 的架构债
+//! （`DevDocs/analyse/01-architecture-overview.md` §3.5），我们反过来做。
+//!
+//! 与其它模块的契约：所有模块的配置读写统一走本模块的 schema API，
+//! 模块自有配置键需先在 `DevDocs/SubAgentsTalk/` 报备（见该目录 README 的对齐点）。
+//! 暴露给各模块的签名清单见 `DevDocs/SubAgentsTalk/setting-接口约定.md`。
+//!
+//! 公共面（M12 已落地）：
+//! - [`schema`]：`$schema` / `schemaVersion` 标识、8 态兼容判定 → 三档访问权；
+//! - [`spec`] + [`catalog`]：键元数据（类型/范围、默认值）与键目录；
+//! - [`policy`]：AI 可写白名单与敏感分级（`setting::spec::AiPolicy` 仍是兼容别名）；
+//! - [`keys`] / [`instance_keys`]：`launcher.json`、`profiles.json`、`instances/.json` 的键表；
+//! - [`appearance`]：D17「外观（高级）」键簇的取值快照与校验（主题三态 / 背景图 / 面板透明度 /
+//!   玻璃拟态 / 强调色）；
+//! - [`document`]：内存文档（点分键、脏字段、未知字段保留、默认值不落盘）；
+//! - [`store`]：单文件加载降级 + 原子保存 + 坏文件备份；
+//! - [`save`] / [`save_worker`]：200ms 去抖攒批与后台保存线程；
+//! - [`migrate`]：`schemaVersion N → N+1` 迁移链 + 收据闸门。
+
+pub mod appearance;
+pub mod catalog;
+pub mod document;
+pub mod error;
+pub mod instance_keys;
+pub mod json_path;
+pub mod keys;
+pub mod migrate;
+pub mod policy;
+pub mod save;
+pub mod save_worker;
+pub mod schema;
+pub mod spec;
+pub mod store;
diff --git a/crates/core/src/setting/policy.rs b/crates/core/src/setting/policy.rs
new file mode 100644
index 0000000..f071ace
--- /dev/null
+++ b/crates/core/src/setting/policy.rs
@@ -0,0 +1,92 @@
+//! 键的 AI 边界：可写白名单与敏感分级（弹窗确认）。
+//!
+//! 出处：`DevDocs/PlanDoc/02-ai-agent-design.md` §3.1（AI 安全边界：白名单 + 类型/范围校验 +
+//! 分级确认）、`DevDocs/PlanDoc/04-data-and-config.md` §3（schema 化）。
+//!
+//! 从 [`super::spec`] 拆出来的原因很实际：`spec.rs` 摸到 400 行硬上限（`guards.yml` 的
+//! file-size 门禁），而「策略」与「键的形状」本来就是两件事。
+
+/// 敏感分级：决定 AI 改这个键时要不要弹窗。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub enum Sensitivity {
+    /// 普通键：静默生效。
+    Low,
+    /// 静默生效但审计标记（便于回看「AI 动过什么」）。
+    Medium,
+    /// 敏感键：必须 UI 弹窗确认。
+    High,
+}
+
+impl Sensitivity {
+    /// 稳定名。
+    #[must_use]
+    pub const fn as_str(&self) -> &'static str {
+        match self {
+            Self::Low => "low",
+            Self::Medium => "medium",
+            Self::High => "high",
+        }
+    }
+
+    /// 是否必须人工确认。
+    #[must_use]
+    pub const fn requires_confirmation(&self) -> bool {
+        matches!(self, Self::High)
+    }
+}
+
+/// 一个键的 AI 可写策略。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct AiPolicy {
+    /// AI 是否允许写这个键（白名单）。
+    pub writable: bool,
+    /// 敏感分级。
+    pub sensitivity: Sensitivity,
+}
+
+impl AiPolicy {
+    /// 普通键：AI 可写，静默生效。
+    #[must_use]
+    pub const fn silent() -> Self {
+        Self {
+            writable: true,
+            sensitivity: Sensitivity::Low,
+        }
+    }
+
+    /// 可写但要审计标记。
+    #[must_use]
+    pub const fn audited() -> Self {
+        Self {
+            writable: true,
+            sensitivity: Sensitivity::Medium,
+        }
+    }
+
+    /// 可写但必须弹窗确认（java 路径 / 数据目录 / 代理 / AI 端点 / 隔离档位）。
+    #[must_use]
+    pub const fn sensitive() -> Self {
+        Self {
+            writable: true,
+            sensitivity: Sensitivity::High,
+        }
+    }
+
+    /// 已废弃键：AI 不可写，读兼容映射到替代键后由替代键承担策略。
+    #[must_use]
+    pub const fn retired() -> Self {
+        Self {
+            writable: false,
+            sensitivity: Sensitivity::Low,
+        }
+    }
+
+    /// 锁死：AI 永远不能写（凭据/密钥，D9「AI 永不触凭据」）。
+    #[must_use]
+    pub const fn locked() -> Self {
+        Self {
+            writable: false,
+            sensitivity: Sensitivity::High,
+        }
+    }
+}
diff --git a/crates/core/src/setting/save.rs b/crates/core/src/setting/save.rs
new file mode 100644
index 0000000..679469d
--- /dev/null
+++ b/crates/core/src/setting/save.rs
@@ -0,0 +1,217 @@
+//! 保存通道的**去抖攒批**部分（纯逻辑，可注入时钟，确定性单测）。
+//!
+//! 出处：`DevDocs/analyse/07-settings-packaging-update.md` §1.6（HMCL `FileSaver`）：
+//! 入队 → 消费线程先 `sleep(200ms)` 等更多改动 → 全量 drain 去重 → 逐条 `saveSync`（tmp + move）。
+//! 效果：一次窗口拖拽只产生一次写盘，而不是 60 次。
+//!
+//! 分层：本文件只管「什么时候写、写什么」；真正落盘由 [`JobSink`] 决定
+//! （生产用 [`AtomicSink`]，测试用记录型 sink）。
+
+use std::collections::BTreeMap;
+use std::path::{Path, PathBuf};
+use std::time::{Duration, Instant};
+
+use super::error::SettingResult;
+
+/// 默认去抖窗口（analyse/07 §1.6 的 200ms）。
+pub const DEFAULT_DEBOUNCE: Duration = Duration::from_millis(200);
+
+/// 一条待写任务。
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct Pending {
+    payload: Vec,
+    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/tests/auth/auth_failure_journal.rs b/crates/core/tests/auth/auth_failure_journal.rs
new file mode 100644
index 0000000..a7e6755
--- /dev/null
+++ b/crates/core/tests/auth/auth_failure_journal.rs
@@ -0,0 +1,151 @@
+//! M38：认证失败事件落盘（`.ULL/logs/auth.jsonl`）与凭据红线。
+//!
+//! 验收场景：`ull accounts add msa` 失败后，终端文案会滚走；日志区里要留下
+//! 一行结构化记录（`code` / `detail_code` / `status` / `content_type` / `body_kind` /
+//! 已脱敏摘要），且**不含任何 token**。便携数据根还没初始化时先补建 `logs/`。
+
+use serde_json::json;
+use unlucky_core::auth::{AuthError, AuthFailureEvent, AuthJournal, BodyKind};
+
+use crate::support::{
+    assert_no_credentials, auth_for, expired_session, full_routes, routes_until_login, temp_dir,
+    AuthMock, MockReply, HTML_BLOCK_PAGE,
+};
+
+const JWT: &str = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.c2lnbmF0dXJlLXZhbHVlLXRoYXQtaXMtbG9uZy1lbm91Z2g";
+
+#[tokio::test]
+async fn body_digest_never_carries_credentials() {
+    let mut routes = routes_until_login();
+    routes.push((
+        "/login_with_xbox",
+        vec![MockReply::json_status(
+            403,
+            json!({ "error": "DENIED", "echo": "xsts-token-value", "jwt": JWT }),
+        )],
+    ));
+    let mock = AuthMock::start(routes).await;
+    let error = auth_for(&mock.base())
+        .device_code_login(|_| {})
+        .await
+        .expect_err("应失败");
+
+    let message = error.message();
+    assert_no_credentials(&message);
+    // 长不透明串（JWT）必须打码，别把 token 回显抄进摘要。
+    assert!(!message.contains("eyJhbGci"), "JWT 必须脱敏：{message}");
+    assert!(message.contains("redacted"), "{message}");
+
+    // 事件层同样不落凭据。
+    let event = AuthFailureEvent::of("device_code_login", &error);
+    let json = event.to_json().to_string();
+    assert_no_credentials(&json);
+    assert!(!json.contains("eyJhbGci"), "{json}");
+    assert!(json.contains("login_with_xbox_403"), "{json}");
+    mock.stop();
+}
+
+#[tokio::test]
+async fn failure_journal_initializes_logs_and_records_the_403() {
+    let root = temp_dir("diag-journal");
+    let logs = root.join(".ULL").join("logs");
+    let journal = AuthJournal::in_logs_dir(&logs);
+    assert!(!logs.exists(), "模拟未初始化的便携数据根");
+
+    let mut routes = routes_until_login();
+    routes.push((
+        "/login_with_xbox",
+        vec![MockReply::html(403, HTML_BLOCK_PAGE)],
+    ));
+    let mock = AuthMock::start(routes).await;
+    let error = auth_for(&mock.base())
+        .with_journal(Some(journal.clone()))
+        .device_code_login(|_| {})
+        .await
+        .expect_err("应失败");
+
+    let text = std::fs::read_to_string(journal.path()).expect("失败日志必须落盘");
+    let lines: Vec<&str> = text.lines().collect();
+    assert_eq!(lines.len(), 1, "一次失败一条记录：{text}");
+    let record: serde_json::Value = serde_json::from_str(lines[0]).expect("合法 JSONL");
+    assert_eq!(record["event"], "auth_failure");
+    assert_eq!(record["level"], "error");
+    assert_eq!(record["scope"], "device_code_login");
+    assert_eq!(record["step"], "login_with_xbox");
+    assert_eq!(record["detail_code"], "login_with_xbox_non_json");
+    assert_eq!(record["status"], 403);
+    assert_eq!(record["body_kind"], "html");
+    assert_eq!(record["transient"], true);
+    assert_eq!(
+        record["message"],
+        error.message(),
+        "事件里的文案要与返回的错误一致"
+    );
+    assert_no_credentials(&text);
+    mock.stop();
+    let _ = std::fs::remove_dir_all(&root);
+}
+
+#[tokio::test]
+async fn journal_event_shape_covers_non_chain_errors() {
+    let event = AuthFailureEvent::of("refresh", &AuthError::Canceled);
+    assert_eq!(event.detail_code, "canceled");
+    assert_eq!(event.step, None);
+    assert_eq!(event.status, None);
+    assert_eq!(event.body_kind, None);
+    assert!(!event.transient);
+    assert_eq!(event.to_json()["scope"], "refresh");
+
+    let detail = unlucky_core::auth::ResponseDetail {
+        step: "profile".to_string(),
+        what: "拉取 Minecraft 档案被拒".to_string(),
+        status: 401,
+        content_type: Some("application/json".to_string()),
+        kind: BodyKind::Json,
+        server_message: Some("Unauthorized".to_string()),
+        digest: "{\"error\":\"Unauthorized\"}".to_string(),
+    };
+    let chain = AuthFailureEvent::of("device_code_login", &AuthError::Response(Box::new(detail)));
+    assert_eq!(chain.step.as_deref(), Some("profile"));
+    assert_eq!(chain.detail_code, "profile_401");
+    assert_eq!(chain.status, Some(401));
+    assert!(!chain.transient, "JSON 拒绝不是可重试的网络问题");
+}
+
+#[tokio::test]
+async fn successful_login_writes_no_journal_and_refresh_failures_do() {
+    let root = temp_dir("diag-journal-ok");
+    let journal = AuthJournal::in_logs_dir(root.join("logs"));
+
+    // 成功：不落盘。
+    let mock = AuthMock::start(full_routes()).await;
+    auth_for(&mock.base())
+        .with_journal(Some(journal.clone()))
+        .device_code_login(|_| {})
+        .await
+        .expect("应登录成功");
+    assert!(!journal.path().exists(), "成功路径不写失败日志");
+    mock.stop();
+
+    // 刷新失败：落一条（凭据被撤销 = 要人重新登录）。
+    let failing = AuthMock::start(vec![(
+        "/token",
+        vec![MockReply::json_status(
+            400,
+            json!({ "error": "invalid_grant", "error_description": "AADSTS70000" }),
+        )],
+    )])
+    .await;
+    let error = auth_for(&failing.base())
+        .with_journal(Some(journal.clone()))
+        .refresh(&expired_session())
+        .await
+        .expect_err("应失败");
+    assert!(error.is_credential_expired());
+    let text = std::fs::read_to_string(journal.path()).expect("刷新失败也要落盘");
+    assert_eq!(text.lines().count(), 1, "{text}");
+    assert!(text.contains("refresh"), "{text}");
+    assert!(text.contains("credential_expired"), "{text}");
+    failing.stop();
+    let _ = std::fs::remove_dir_all(&root);
+}
diff --git a/crates/core/tests/auth/authlib_api.rs b/crates/core/tests/auth/authlib_api.rs
new file mode 100644
index 0000000..dcdb8d7
--- /dev/null
+++ b/crates/core/tests/auth/authlib_api.rs
@@ -0,0 +1,307 @@
+//! Yggdrasil（authlib-injector）四动作的报文级对接：登录 / 刷新 / 校验 / 注销。
+
+use serde_json::json;
+use unlucky_core::auth::authlib::{
+    AuthlibAuth, AuthlibEndpoints, AuthlibProfile, AuthlibServerMeta, AuthlibSession,
+};
+use unlucky_core::auth::{AuthError, Secret};
+
+use crate::support::{AuthMock, MockReply};
+
+const API_ROOT: &str = "https://example.invalid/api/yggdrasil/";
+const PROFILE_ID: &str = "0123456789abcdef0123456789abcdef";
+
+fn paths() -> (&'static str, &'static str, &'static str, &'static str) {
+    (
+        "/api/yggdrasil/authserver/authenticate",
+        "/api/yggdrasil/authserver/refresh",
+        "/api/yggdrasil/authserver/validate",
+        "/api/yggdrasil/authserver/invalidate",
+    )
+}
+
+/// 把 API 根改指到 mock（`base` 代替 https://example.invalid）。
+fn mock_root(mock: &AuthMock) -> String {
+    format!("{}/api/yggdrasil", mock.base())
+}
+
+fn session() -> AuthlibSession {
+    AuthlibSession {
+        access_token: Secret::new("access-token-value"),
+        client_token: Secret::new("client-token-value"),
+        selected_profile: Some(AuthlibProfile {
+            id: PROFILE_ID.to_string(),
+            name: "Steve".to_string(),
+        }),
+    }
+}
+
+#[tokio::test]
+async fn authenticate_sends_the_canonical_body() {
+    let (authenticate, _, _, _) = paths();
+    let mock = AuthMock::start(vec![(
+        authenticate,
+        vec![MockReply::json(json!({
+            "accessToken": "access-token-value",
+            "clientToken": "client-token-value",
+            "selectedProfile": { "id": PROFILE_ID, "name": "Steve" }
+        }))],
+    )])
+    .await;
+    let auth = AuthlibAuth::new().expect("构造");
+    let login = auth
+        .authenticate(
+            &mock_root(&mock),
+            "steve@example.com",
+            &Secret::new("hunter2-password"),
+            &Secret::new("client-token-value"),
+        )
+        .await
+        .expect("登录成功");
+
+    assert_eq!(login.access_token.expose(), "access-token-value");
+    assert_eq!(login.client_token.expose(), "client-token-value");
+    assert!(login.has_profile());
+    assert_eq!(
+        login.selected_profile.as_ref().map(|p| p.name.as_str()),
+        Some("Steve")
+    );
+
+    let body = &mock.bodies_on(authenticate)[0];
+    assert!(
+        body.contains("\"agent\":{\"name\":\"Minecraft\",\"version\":1}"),
+        "{body}"
+    );
+    assert!(body.contains("\"requestUser\":true"), "{body}");
+    assert!(
+        body.contains("\"username\":\"steve@example.com\""),
+        "{body}"
+    );
+    assert!(
+        body.contains("\"clientToken\":\"client-token-value\""),
+        "{body}"
+    );
+    // 密码确实发了（否则登录不了），但会话 Debug 里看不到它。
+    assert!(body.contains("hunter2-password"));
+    assert!(!format!("{login:?}").contains("hunter2-password"));
+    mock.stop();
+}
+
+#[tokio::test]
+async fn wrong_password_is_denied_with_server_message() {
+    let (authenticate, _, _, _) = paths();
+    let mock = AuthMock::start(vec![(
+        authenticate,
+        vec![MockReply::json_status(
+            403,
+            json!({
+                "error": "ForbiddenOperationException",
+                "errorMessage": "Invalid credentials. Invalid username or password."
+            }),
+        )],
+    )])
+    .await;
+    let auth = AuthlibAuth::new().expect("构造");
+    let error = auth
+        .authenticate(
+            &mock_root(&mock),
+            "steve",
+            &Secret::new("wrong"),
+            &Secret::new("client-token-value"),
+        )
+        .await
+        .expect_err("应失败");
+    match error {
+        AuthError::Denied { code, description } => {
+            assert_eq!(code, "ForbiddenOperationException");
+            assert!(description.contains("Invalid credentials"));
+        }
+        other => panic!("应是 Denied，实际 {other:?}"),
+    }
+    mock.stop();
+}
+
+#[tokio::test]
+async fn server_must_echo_the_client_token() {
+    let (authenticate, _, _, _) = paths();
+    let mock = AuthMock::start(vec![(
+        authenticate,
+        vec![MockReply::json(json!({
+            "accessToken": "access-token-value",
+            "clientToken": "someone-elses-token",
+            "selectedProfile": { "id": PROFILE_ID, "name": "Steve" }
+        }))],
+    )])
+    .await;
+    let auth = AuthlibAuth::new().expect("构造");
+    let error = auth
+        .authenticate(
+            &mock_root(&mock),
+            "steve",
+            &Secret::new("pw"),
+            &Secret::new("client-token-value"),
+        )
+        .await
+        .expect_err("应拒绝");
+    assert_eq!(error.code(), "malformed");
+    assert!(
+        error.message().contains("clientToken"),
+        "{}",
+        error.message()
+    );
+    mock.stop();
+}
+
+#[tokio::test]
+async fn refresh_can_select_a_character() {
+    let (_, refresh, _, _) = paths();
+    let mock = AuthMock::start(vec![(
+        refresh,
+        vec![MockReply::json(json!({
+            "accessToken": "access-token-2",
+            "clientToken": "client-token-value",
+            "selectedProfile": { "id": PROFILE_ID, "name": "Alex" }
+        }))],
+    )])
+    .await;
+    let auth = AuthlibAuth::new().expect("构造");
+    let wanted = AuthlibProfile {
+        id: PROFILE_ID.to_string(),
+        name: "Alex".to_string(),
+    };
+    let refreshed = auth
+        .refresh(&mock_root(&mock), &session(), Some(&wanted))
+        .await
+        .expect("刷新成功");
+    assert_eq!(refreshed.access_token.expose(), "access-token-2");
+    assert_eq!(refreshed.selected_profile.expect("角色").name, "Alex");
+    // 新的 refresh_token 不存在于 Yggdrasil：clientToken 保持不变。
+    assert_eq!(refreshed.client_token.expose(), "client-token-value");
+
+    let body = &mock.bodies_on(refresh)[0];
+    assert!(body.contains("\"selectedProfile\":{\"id\":\"0123456789abcdef0123456789abcdef\""));
+    assert!(body.contains("\"accessToken\":\"access-token-value\""));
+    mock.stop();
+}
+
+#[tokio::test]
+async fn refresh_that_did_not_switch_character_is_malformed() {
+    let (_, refresh, _, _) = paths();
+    let mock = AuthMock::start(vec![(
+        refresh,
+        vec![MockReply::json(json!({
+            "accessToken": "access-token-2",
+            "clientToken": "client-token-value",
+            "selectedProfile": { "id": PROFILE_ID, "name": "Steve" }
+        }))],
+    )])
+    .await;
+    let auth = AuthlibAuth::new().expect("构造");
+    let wanted = AuthlibProfile {
+        id: "ffffffffffffffffffffffffffffffff".to_string(),
+        name: "Ghost".to_string(),
+    };
+    let error = auth
+        .refresh(&mock_root(&mock), &session(), Some(&wanted))
+        .await
+        .expect_err("应失败");
+    assert_eq!(error.code(), "malformed");
+    mock.stop();
+}
+
+#[tokio::test]
+async fn forbidden_on_refresh_means_credential_expired() {
+    let (_, refresh, _, _) = paths();
+    let mock = AuthMock::start(vec![(
+        refresh,
+        vec![MockReply::json_status(
+            403,
+            json!({ "error": "ForbiddenOperationException", "errorMessage": "Invalid token." }),
+        )],
+    )])
+    .await;
+    let auth = AuthlibAuth::new().expect("构造");
+    let error = auth
+        .refresh(&mock_root(&mock), &session(), None)
+        .await
+        .expect_err("应失败");
+    assert!(error.is_credential_expired(), "{error:?}");
+    mock.stop();
+}
+
+#[tokio::test]
+async fn validate_distinguishes_invalid_token_from_server_trouble() {
+    let (_, _, validate, _) = paths();
+    // 空体 200 → 有效
+    let ok = AuthMock::start(vec![(validate, vec![MockReply::status(200)])]).await;
+    let auth = AuthlibAuth::new().expect("构造");
+    assert!(auth
+        .validate(&mock_root(&ok), &session())
+        .await
+        .expect("有效"));
+    ok.stop();
+
+    // 403 ForbiddenOperationException → 无效（返回值 false，不抛错）
+    let invalid = AuthMock::start(vec![(
+        validate,
+        vec![MockReply::json_status(
+            403,
+            json!({ "error": "ForbiddenOperationException", "errorMessage": "Invalid token." }),
+        )],
+    )])
+    .await;
+    assert!(!auth
+        .validate(&mock_root(&invalid), &session())
+        .await
+        .expect("无效"));
+    invalid.stop();
+
+    // 500 → 服务器问题，必须抛错（调用方才会重试而不是刷新）
+    let broken = AuthMock::start(vec![(validate, vec![MockReply::status(500)])]).await;
+    let error = auth
+        .validate(&mock_root(&broken), &session())
+        .await
+        .expect_err("应失败");
+    assert_eq!(error.code(), "network");
+    broken.stop();
+}
+
+#[tokio::test]
+async fn invalidate_tolerates_already_invalid_tokens() {
+    let (_, _, _, invalidate) = paths();
+    let auth = AuthlibAuth::new().expect("构造");
+    let ok = AuthMock::start(vec![(invalidate, vec![MockReply::status(200)])]).await;
+    auth.invalidate(&mock_root(&ok), &session())
+        .await
+        .expect("注销成功");
+    ok.stop();
+
+    let gone = AuthMock::start(vec![(
+        invalidate,
+        vec![MockReply::json_status(
+            403,
+            json!({ "error": "ForbiddenOperationException" }),
+        )],
+    )])
+    .await;
+    auth.invalidate(&mock_root(&gone), &session())
+        .await
+        .expect("已失效也算成功");
+    gone.stop();
+}
+
+#[test]
+fn endpoints_and_metadata_stay_in_sync_with_the_protocol() {
+    let endpoints = AuthlibEndpoints::from_api_root(API_ROOT).expect("端点");
+    assert_eq!(
+        endpoints.authenticate,
+        format!("{API_ROOT}authserver/authenticate")
+    );
+    let meta = AuthlibServerMeta::from_value(&json!({
+        "meta": { "serverName": "Example", "feature.non_email_login": true },
+        "skinDomains": ["example.invalid"]
+    }));
+    assert_eq!(meta.name.as_deref(), Some("Example"));
+    assert!(meta.non_email_login);
+    assert_eq!(meta.skin_domains, vec!["example.invalid".to_string()]);
+}
diff --git a/crates/core/tests/auth/main.rs b/crates/core/tests/auth/main.rs
new file mode 100644
index 0000000..6fba1e5
--- /dev/null
+++ b/crates/core/tests/auth/main.rs
@@ -0,0 +1,21 @@
+//! `core::auth` 的集成测试入口。
+//!
+//! 每个子模块对应 mission 的一项验收：
+//! - `offline_uuid`：离线 UUID 与 JDK（= HMCL 算法）**逐字节对拍**的已知向量；
+//! - `store_separation`：元数据/凭据分文件、原子写、写序、容错与孤儿清理；
+//! - `microsoft_flow`：device-code 全链（含 pending / slow_down / 取消 / 超时 / XErr）；
+//! - `microsoft_authcode`：授权码流（本地回调服务器 / 授权 URL 向量 / code 换链 / 403 诊断）；
+//! - `microsoft_diagnostics`：非 2xx 正文诊断（JSON/HTML/空体分流）+ 失败日志落盘（M38）；
+//! - `microsoft_refresh`：refresh 轮换、profile 变脸防线、validate 语义、404 二义；
+//! - `authlib_api`：Yggdrasil 四动作的报文级对接。
+
+mod support;
+
+mod auth_failure_journal;
+mod authlib_api;
+mod microsoft_authcode;
+mod microsoft_diagnostics;
+mod microsoft_flow;
+mod microsoft_refresh;
+mod offline_uuid;
+mod store_separation;
diff --git a/crates/core/tests/auth/microsoft_authcode.rs b/crates/core/tests/auth/microsoft_authcode.rs
new file mode 100644
index 0000000..303101c
--- /dev/null
+++ b/crates/core/tests/auth/microsoft_authcode.rs
@@ -0,0 +1,295 @@
+//! 授权码流（`research/08` §3 方案 A）：本地回调服务器 + 授权 URL + code 换链。
+//!
+//! 覆盖验收口径：授权码换到 MS token → XBL → XSTS 全通；白名单未批前
+//! `login_with_xbox` 的 403 只要求**诊断文案正确**（M38 版），不绕过。
+
+use std::time::Duration;
+
+use serde_json::json;
+use unlucky_core::auth::microsoft::{
+    AuthCodePolicy, AuthCodePrompt, CallbackServer, MicrosoftAuth, MicrosoftEndpoints,
+};
+use unlucky_core::auth::AuthError;
+
+use crate::support::{full_routes, response_of, AuthMock, MockReply};
+
+const CLIENT_ID: &str = "test-client-id";
+
+fn policy(state: &str, timeout_ms: u64) -> AuthCodePolicy {
+    AuthCodePolicy {
+        callback_timeout: Duration::from_millis(timeout_ms),
+        bind_attempts: 3,
+        port: None,
+        state: Some(state.to_string()),
+    }
+}
+
+/// 模拟浏览器：把 `code` 送到本地回调地址（真发一次 HTTP，走 localhost 解析）。
+async fn deliver(redirect_uri: &str, query: &str) {
+    let url = format!("{redirect_uri}?{query}");
+    // 回调服务器可能在 accept 中，给一拍让绑定先落地。
+    tokio::time::sleep(Duration::from_millis(10)).await;
+    let response = reqwest::get(&url).await.expect("浏览器回调");
+    assert_eq!(response.status(), 200, "回调页应回 200");
+    let page = response.text().await.expect("回调页正文");
+    assert!(page.contains("登录完成"), "回调页应是给用户看的完成页");
+}
+
+#[tokio::test]
+async fn authcode_login_completes_the_chain() {
+    let mock = AuthMock::start(full_routes()).await;
+    let auth = MicrosoftAuth::new(CLIENT_ID)
+        .expect("构造")
+        .with_endpoints(MicrosoftEndpoints::all_on(&mock.base()))
+        .with_authcode_policy(policy("state-abc", 5_000));
+
+    let mut prompted: Option = 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_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/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_test.rs b/crates/core/tests/download/engine_mock_test.rs
new file mode 100644
index 0000000..528e664
--- /dev/null
+++ b/crates/core/tests/download/engine_mock_test.rs
@@ -0,0 +1,350 @@
+//! 引擎端到端（mock 源）：成功 / 退避重试 / 换源 / 校验失败 / 缓存命中 / 断点续传。
+//!
+//! 用 `tests/download/support` 里的进程内 HTTP 服务器，不发真实网络请求。
+
+mod support;
+
+use std::path::PathBuf;
+use std::sync::Arc;
+use std::time::Duration;
+
+use unlucky_core::download::backoff::BackoffPolicy;
+use unlucky_core::download::cache::ContentCache;
+use unlucky_core::download::chunked::ChunkedConfig;
+use unlucky_core::download::config::EngineConfig;
+use unlucky_core::download::engine::DownloadEngine;
+use unlucky_core::download::error::DownloadErrorKind;
+use unlucky_core::download::health::HealthRegistry;
+use unlucky_core::download::mirrors::{MirrorTable, PrefixRule};
+use unlucky_core::download::progress::{ProgressEmitter, ProgressEvent};
+use unlucky_core::download::region::RegionProfile;
+use unlucky_core::download::resume::ResumeMeta;
+use unlucky_core::download::types::{DownloadRequest, HashAlgo, ResourceKind};
+
+use support::{sha1_hex, temp_dir, MockResponse, MockServer};
+
+fn fast_config(attempts: u32) -> EngineConfig {
+    EngineConfig {
+        max_attempts_per_source: attempts,
+        backoff: BackoffPolicy {
+            base_ms: 1,
+            max_ms: 2,
+            jitter_ratio: 0.0,
+            max_attempts: attempts,
+        },
+        connect_timeout: Duration::from_secs(5),
+        read_timeout: Duration::from_secs(5),
+        chunked: ChunkedConfig::disabled(),
+        ..EngineConfig::default()
+    }
+}
+
+struct Harness {
+    engine: DownloadEngine,
+    dir: PathBuf,
+}
+
+fn harness(cfg: EngineConfig, table: MirrorTable, region: RegionProfile, tag: &str) -> Harness {
+    let dir = temp_dir(tag);
+    let cache = Arc::new(ContentCache::open(dir.join("cache")));
+    let health = Arc::new(HealthRegistry::in_memory());
+    let engine = DownloadEngine::new(cfg, Arc::new(table), Arc::new(region), health, cache);
+    Harness { engine, dir }
+}
+
+fn direct_region() -> RegionProfile {
+    RegionProfile::direct(0)
+}
+
+#[tokio::test]
+async fn downloads_verifies_and_leaves_no_part_file() {
+    let payload = b"unlucky launcher payload".to_vec();
+    let server = MockServer::start(vec![MockResponse::ok(payload.clone())]).await;
+    let url = server.url("/client.jar");
+    let harness = harness(
+        fast_config(2),
+        MirrorTable::builtin(),
+        direct_region(),
+        "engine-ok",
+    );
+    let dest = harness.dir.join("versions/1.20.1/client.jar");
+
+    let request = DownloadRequest::new(ResourceKind::ClientJar, url.as_str(), &dest)
+        .with_sha1(sha1_hex(&payload))
+        .with_size(payload.len() as u64);
+    let outcome = harness.engine.download(request).await.expect("下载应成功");
+
+    assert_eq!(outcome.bytes, payload.len() as u64);
+    assert!(!outcome.from_cache);
+    assert_eq!(outcome.resumed_from, 0);
+    assert_eq!(std::fs::read(&dest).unwrap(), payload);
+    let version_dir = harness.dir.join("versions/1.20.1");
+    assert!(
+        support::part_files(&version_dir).is_empty(),
+        "中间文件必须被提交掉：{:?}",
+        support::part_files(&version_dir)
+    );
+    server.stop();
+}
+
+#[tokio::test]
+async fn retries_same_source_after_server_error() {
+    let payload = b"retry me".to_vec();
+    let server = MockServer::start(vec![
+        MockResponse::status(503),
+        MockResponse::ok(payload.clone()),
+    ])
+    .await;
+    let url = server.url("/lib.jar");
+    let harness = harness(
+        fast_config(3),
+        MirrorTable::builtin(),
+        direct_region(),
+        "engine-retry",
+    );
+    let dest = harness.dir.join("lib.jar");
+
+    let outcome = harness
+        .engine
+        .download(
+            DownloadRequest::new(ResourceKind::Library, url.as_str(), &dest)
+                .with_sha1(sha1_hex(&payload)),
+        )
+        .await
+        .expect("退避后应成功");
+    assert_eq!(outcome.bytes, payload.len() as u64);
+    assert_eq!(server.hits(), 2, "第一次 503 之后应重试一次");
+    server.stop();
+}
+
+#[tokio::test]
+async fn switches_to_official_when_mirror_keeps_failing() {
+    let payload = b"official wins".to_vec();
+    let official = MockServer::start(vec![MockResponse::ok(payload.clone())]).await;
+    let mirror = MockServer::start(vec![
+        MockResponse::status(500),
+        MockResponse::status(500),
+        MockResponse::status(500),
+    ])
+    .await;
+
+    let mut table = MirrorTable::builtin();
+    let official_prefix = format!("http://127.0.0.1:{}", official.port());
+    let mirror_prefix = format!("http://localhost:{}", mirror.port());
+    table.add_custom_rule(PrefixRule::new(
+        "mock-mirror",
+        official_prefix,
+        mirror_prefix,
+    ));
+
+    let harness = harness(
+        fast_config(2),
+        table,
+        RegionProfile::mirror_first(0),
+        "engine-switch",
+    );
+    let dest = harness.dir.join("client.jar");
+    let url = official.url("/client.jar");
+
+    let outcome = harness
+        .engine
+        .download(
+            DownloadRequest::new(ResourceKind::ClientJar, url.as_str(), &dest)
+                .with_sha1(sha1_hex(&payload)),
+        )
+        .await
+        .expect("镜像全挂后应切到官方");
+    assert_eq!(outcome.source, "official");
+    assert_eq!(std::fs::read(&dest).unwrap(), payload);
+    assert_eq!(mirror.hits(), 2, "每个源最多尝试 max_attempts 次");
+    official.stop();
+    mirror.stop();
+}
+
+#[tokio::test]
+async fn rejects_wrong_checksum_and_falls_back() {
+    let payload = b"the real jar".to_vec();
+    let official = MockServer::start(vec![MockResponse::ok(payload.clone())]).await;
+    let mirror = MockServer::start(vec![MockResponse::ok(b"tampered by mirror".to_vec())]).await;
+
+    let mut table = MirrorTable::builtin();
+    table.add_custom_rule(PrefixRule::new(
+        "mock-mirror",
+        format!("http://127.0.0.1:{}", official.port()),
+        format!("http://localhost:{}", mirror.port()),
+    ));
+
+    let harness = harness(
+        fast_config(1),
+        table,
+        RegionProfile::mirror_first(0),
+        "engine-checksum",
+    );
+    let dest = harness.dir.join("client.jar");
+    let url = official.url("/client.jar");
+
+    let outcome = harness
+        .engine
+        .download(
+            DownloadRequest::new(ResourceKind::ClientJar, url.as_str(), &dest)
+                .with_sha1(sha1_hex(&payload))
+                .with_size(payload.len() as u64),
+        )
+        .await
+        .expect("校验失败应换源而不是交付坏文件");
+    assert_eq!(outcome.source, "official");
+    assert_eq!(std::fs::read(&dest).unwrap(), payload);
+    assert!(mirror.hits() >= 1);
+    official.stop();
+    mirror.stop();
+}
+
+#[tokio::test]
+async fn second_download_hits_content_cache_without_network() {
+    let payload = b"cached payload".to_vec();
+    let server = MockServer::start(vec![
+        MockResponse::ok(payload.clone()),
+        MockResponse::ok(payload.clone()),
+    ])
+    .await;
+    let url = server.url("/lib.jar");
+    let harness = harness(
+        fast_config(2),
+        MirrorTable::builtin(),
+        direct_region(),
+        "engine-cache",
+    );
+    let integrity = sha1_hex(&payload);
+
+    let first = harness
+        .engine
+        .download(
+            DownloadRequest::new(
+                ResourceKind::Library,
+                url.as_str(),
+                harness.dir.join("a/lib.jar"),
+            )
+            .with_sha1(integrity.as_str()),
+        )
+        .await
+        .expect("首次下载失败");
+    assert!(!first.from_cache);
+
+    let hits_after_first = server.hits();
+    let second = harness
+        .engine
+        .download(
+            DownloadRequest::new(
+                ResourceKind::Library,
+                url.as_str(),
+                harness.dir.join("b/lib.jar"),
+            )
+            .with_sha1(integrity.as_str()),
+        )
+        .await
+        .expect("缓存命中失败");
+    assert!(second.from_cache);
+    assert_eq!(second.bytes, payload.len() as u64);
+    assert_eq!(server.hits(), hits_after_first, "缓存命中不能再发请求");
+    assert_eq!(
+        std::fs::read(harness.dir.join("b/lib.jar")).unwrap(),
+        payload
+    );
+    server.stop();
+}
+
+#[tokio::test]
+async fn resumes_from_existing_part_file() {
+    let payload = b"0123456789abcdefghij".to_vec();
+    let split = 8_usize;
+    let server = MockServer::start(vec![MockResponse::ok(payload.clone())]).await;
+    let url = server.url("/client.jar");
+    let harness = harness(
+        fast_config(2),
+        MirrorTable::builtin(),
+        direct_region(),
+        "engine-resume",
+    );
+    let dest = harness.dir.join("client.jar");
+    let part = harness.dir.join("client.jar.ullpart");
+    let meta_path = harness.dir.join("client.jar.ullpart.ullmeta.json");
+
+    std::fs::write(&part, &payload[..split]).unwrap();
+    ResumeMeta {
+        url: url.clone(),
+        etag: Some("\"v1\"".to_string()),
+        last_modified: None,
+        total: Some(payload.len() as u64),
+        algo: HashAlgo::Sha1,
+        hash: sha1_hex(&payload),
+        saved_at_ms: 1,
+    }
+    .save(&meta_path)
+    .expect("写续传元数据失败");
+
+    let outcome = harness
+        .engine
+        .download(
+            DownloadRequest::new(ResourceKind::ClientJar, url.as_str(), &dest)
+                .with_sha1(sha1_hex(&payload))
+                .with_size(payload.len() as u64),
+        )
+        .await
+        .expect("续传失败");
+
+    assert_eq!(outcome.resumed_from, split as u64, "应从已有偏移续传");
+    assert_eq!(std::fs::read(&dest).unwrap(), payload);
+    assert_eq!(server.hits(), 1);
+    server.stop();
+}
+
+#[tokio::test]
+async fn reports_progress_events_and_errors_when_all_sources_fail() {
+    let server = MockServer::start(vec![
+        MockResponse::status(500),
+        MockResponse::status(500),
+        MockResponse::status(500),
+        MockResponse::status(500),
+    ])
+    .await;
+    let url = server.url("/dead.jar");
+    let dir = temp_dir("engine-fail");
+    let cache = Arc::new(ContentCache::open(dir.join("cache")));
+    let (emitter, mut events) = ProgressEmitter::channel();
+    let engine = DownloadEngine::new(
+        fast_config(1),
+        Arc::new(MirrorTable::builtin()),
+        Arc::new(direct_region()),
+        Arc::new(HealthRegistry::in_memory()),
+        cache,
+    )
+    .with_progress(emitter);
+
+    let error = engine
+        .download(DownloadRequest::new(
+            ResourceKind::Library,
+            url.as_str(),
+            dir.join("dead.jar"),
+        ))
+        .await
+        .expect_err("所有源都 500 时必须失败");
+    assert_eq!(error.kind, DownloadErrorKind::AllSourcesFailed);
+
+    let mut started = false;
+    let mut failed_source = false;
+    while let Ok(event) = events.try_recv() {
+        match event {
+            ProgressEvent::Started { candidates, .. } => {
+                started = true;
+                assert!(candidates >= 1);
+            }
+            ProgressEvent::SourceFailed { will_retry, .. } => {
+                failed_source = true;
+                assert!(!will_retry, "单次尝试用尽后不应再声明重试");
+            }
+            _ => {}
+        }
+    }
+    assert!(started && failed_source, "进度事件缺失");
+    server.stop();
+}
diff --git a/crates/core/tests/download/health_test.rs b/crates/core/tests/download/health_test.rs
new file mode 100644
index 0000000..3899cb9
--- /dev/null
+++ b/crates/core/tests/download/health_test.rs
@@ -0,0 +1,268 @@
+//! 健康度记忆的单测：冷却、恢复探测、排序、持久化 + 引擎驱动的落盘接线。
+
+mod support;
+
+use std::sync::Arc;
+use std::time::Duration;
+
+use unlucky_core::download::backoff::BackoffPolicy;
+use unlucky_core::download::cache::{now_ms, ContentCache};
+use unlucky_core::download::config::EngineConfig;
+use unlucky_core::download::engine::DownloadEngine;
+use unlucky_core::download::error::DownloadErrorKind;
+use unlucky_core::download::health::{
+    HealthRegistry, SourceHealth, COOLDOWN_MS, FAILURE_THRESHOLD,
+};
+use unlucky_core::download::mirrors::MirrorTable;
+use unlucky_core::download::region::RegionProfile;
+use unlucky_core::download::types::{Candidate, DownloadRequest, ResourceKind, SOURCE_OFFICIAL};
+
+use support::{MockResponse, MockServer};
+
+const NOW: u64 = 1_000_000;
+
+fn registry() -> HealthRegistry {
+    HealthRegistry::in_memory()
+}
+
+#[test]
+fn fresh_source_is_neutral_not_penalized() {
+    let health = SourceHealth::default();
+    assert!(!health.is_cooling_down(NOW));
+    assert_eq!(health.failure_rate(), 0.0);
+    // 未知源必须是中间分，不能比刚成功的源更优先。
+    let healthy = SourceHealth {
+        samples: 3,
+        successes: 3,
+        ema_rtt_ms: 120.0,
+        ..SourceHealth::default()
+    };
+    assert!(healthy.score(NOW) < health.score(NOW));
+}
+
+#[test]
+fn three_consecutive_failures_trigger_cooldown() {
+    let mut health = SourceHealth::default();
+    for _ in 0..FAILURE_THRESHOLD {
+        health.record_failure("HTTP 502", NOW);
+    }
+    assert!(health.is_cooling_down(NOW));
+    assert!(health.is_cooling_down(NOW + COOLDOWN_MS - 1));
+    // 冷却到期后不再是冷却态，而是「可以探测」。
+    assert!(!health.is_cooling_down(NOW + COOLDOWN_MS));
+    assert!(health.is_probe(NOW + COOLDOWN_MS));
+    // 冷却中的源排序惩罚要明显高于健康源。
+    assert!(health.score(NOW) >= 1_000.0);
+}
+
+#[test]
+fn missing_artifact_is_recorded_without_cooling_down() {
+    // 院校镜像只留最新补丁：请求旧补丁必然 404，不能把源判成「坏」。
+    let mut health = SourceHealth::default();
+    for _ in 0..(FAILURE_THRESHOLD * 2) {
+        health.record_missing("HTTP 404", NOW);
+    }
+    assert!(!health.is_cooling_down(NOW), "4xx 不进冷却");
+    assert!(!health.is_probe(NOW), "4xx 不该产生恢复探测状态");
+    assert_eq!(health.failures, 0, "4xx 不计失败次数");
+    assert_eq!(health.not_found, u64::from(FAILURE_THRESHOLD * 2));
+    assert_eq!(health.failure_rate(), 0.0);
+    assert!(health.last_error.is_some(), "诊断仍要留痕");
+    // 打分不应被 404 拉高（仍是未知源的中位分）。
+    assert_eq!(health.score(NOW), SourceHealth::default().score(NOW));
+    assert_eq!(
+        health.score(NOW),
+        unlucky_core::download::health::SCORE_UNKNOWN
+    );
+}
+
+#[test]
+fn not_found_ageing_does_not_persist_a_cooldown() {
+    let registry = HealthRegistry::in_memory();
+    for _ in 0..10 {
+        registry.record_missing("tuna", ResourceKind::JavaRuntime, "HTTP 404", NOW);
+    }
+    let health = registry.health_of("tuna", ResourceKind::JavaRuntime);
+    assert!(!health.is_cooling_down(NOW));
+    assert_eq!(health.not_found, 10);
+    assert_eq!(health.consecutive_failures, 0);
+}
+
+#[test]
+fn probe_failure_re_arms_cooldown_and_success_clears_it() {
+    let mut health = SourceHealth::default();
+    for _ in 0..FAILURE_THRESHOLD {
+        health.record_failure("timeout", NOW);
+    }
+    let after_cooldown = NOW + COOLDOWN_MS + 1;
+    assert!(!health.is_cooling_down(after_cooldown));
+    // 探测再一次失败 → 立即重新冷却。
+    health.record_failure("timeout again", after_cooldown);
+    assert!(health.is_cooling_down(after_cooldown));
+
+    // 成功则全部清零。
+    health.record_success(90, after_cooldown + 1);
+    assert!(!health.is_cooling_down(after_cooldown + 1));
+    assert!(!health.is_probe(after_cooldown + 1));
+    assert_eq!(health.consecutive_failures, 0);
+    assert_eq!(health.cooldown_until_ms, 0);
+    assert_eq!(health.last_error, None);
+}
+
+#[test]
+fn ema_smooths_latency_and_counts_samples() {
+    let mut health = SourceHealth::default();
+    health.record_success(100, NOW);
+    assert_eq!(health.ema_rtt_ms, 100.0);
+    health.record_success(200, NOW);
+    // 0.3 * 200 + 0.7 * 100 = 130
+    assert!((health.ema_rtt_ms - 130.0).abs() < 1e-9);
+    assert_eq!(health.samples, 2);
+    assert_eq!(health.successes, 2);
+}
+
+#[test]
+fn failure_rate_counts_both_sides() {
+    let mut health = SourceHealth::default();
+    health.record_success(50, NOW);
+    health.record_failure("boom", NOW);
+    assert!((health.failure_rate() - 0.5).abs() < 1e-9);
+}
+
+#[test]
+fn registry_ranks_healthy_first_and_cooling_last() {
+    let registry = registry();
+    for _ in 0..FAILURE_THRESHOLD {
+        registry.record_failure("mirror-b", ResourceKind::ClientJar, "HTTP 500", NOW);
+    }
+    registry.record_success(
+        "mirror-a",
+        ResourceKind::ClientJar,
+        Duration::from_millis(80),
+        NOW,
+    );
+
+    let candidates = vec![
+        Candidate::new("mirror-b", "https://b.example/file"),
+        Candidate::new("unknown", "https://u.example/file"),
+        Candidate::new("mirror-a", "https://a.example/file"),
+    ];
+    let ranked = registry.rank(&candidates, ResourceKind::ClientJar, NOW);
+    assert_eq!(ranked[0].source, "mirror-a");
+    assert_eq!(ranked[1].source, "unknown");
+    assert_eq!(
+        ranked[2].source, "mirror-b",
+        "冷却中的源排最后但仍保留为兜底"
+    );
+}
+
+#[test]
+fn health_is_tracked_per_resource_kind() {
+    let registry = registry();
+    for _ in 0..FAILURE_THRESHOLD {
+        registry.record_failure("bmclapi", ResourceKind::Asset, "404", NOW);
+    }
+    assert!(registry.is_cooling_down("bmclapi", ResourceKind::Asset, NOW));
+    // 另一种资源类型不受影响（资产挂了不代表 JDK 也挂）。
+    assert!(!registry.is_cooling_down("bmclapi", ResourceKind::JavaRuntime, NOW));
+}
+
+#[test]
+fn persistence_roundtrip_and_age_pruning() {
+    let dir = std::env::temp_dir().join(format!("ull-health-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    std::fs::create_dir_all(&dir).unwrap();
+    let path = dir.join("health.json");
+
+    let registry = HealthRegistry::open(&path, 7 * 24 * 3600 * 1000, NOW);
+    registry.record_failure("bmclapi", ResourceKind::Library, "HTTP 503", NOW);
+    registry.record_success(
+        "official",
+        ResourceKind::Library,
+        Duration::from_millis(55),
+        NOW,
+    );
+    registry.save().expect("持久化失败");
+
+    let reloaded = HealthRegistry::open(&path, 7 * 24 * 3600 * 1000, NOW + 1_000);
+    assert_eq!(reloaded.snapshot().len(), 2);
+    assert_eq!(
+        reloaded
+            .health_of("bmclapi", ResourceKind::Library)
+            .failures,
+        1
+    );
+    assert!(
+        reloaded
+            .health_of("official", ResourceKind::Library)
+            .ema_rtt_ms
+            > 0.0
+    );
+
+    // 超出最大保留期 → 丢弃旧记录（缓存目录被长时间放着的情况）。
+    let pruned = HealthRegistry::open(&path, 10, NOW + 60_000);
+    assert!(pruned.snapshot().is_empty());
+
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+/// P1 回归：健康度必须由**引擎的生产路径**落盘——下载→（模拟进程退出）→重开 registry，
+/// 冷却状态与失败计数都要还在，否则「连续 3 败冷却 10 分钟」每轮启动从零学起。
+#[tokio::test]
+async fn engine_persists_health_so_a_restart_keeps_the_cooldown() {
+    let failed = || MockResponse::status(500);
+    let server = MockServer::start(vec![failed(), failed(), failed(), failed()]).await;
+    let url = server.url("/lib.jar");
+    let dir = support::temp_dir("health-engine-persist");
+    let path = dir.join("cache/health.json");
+    let now = now_ms();
+    let max_age_ms = 7 * 24 * 3600 * 1000;
+
+    let registry = Arc::new(HealthRegistry::open(&path, max_age_ms, now));
+    let engine = DownloadEngine::new(
+        EngineConfig {
+            max_attempts_per_source: FAILURE_THRESHOLD,
+            backoff: BackoffPolicy {
+                base_ms: 1,
+                max_ms: 2,
+                jitter_ratio: 0.0,
+                max_attempts: FAILURE_THRESHOLD,
+            },
+            ..EngineConfig::default()
+        },
+        Arc::new(MirrorTable::builtin()),
+        Arc::new(RegionProfile::direct(0)),
+        Arc::clone(®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..61c0696
--- /dev/null
+++ b/crates/core/tests/download/mirrors_test.rs
@@ -0,0 +1,281 @@
+//! 镜像清单与前缀重写的单测（纯字符串，无网络）。
+
+use unlucky_core::download::adoptium::{parse_adoptium_artifact, JdkFlavor};
+use unlucky_core::download::mirrors::{host_of, source_id_for, MirrorTable, PrefixRule};
+use unlucky_core::download::region::RegionProfile;
+use unlucky_core::download::types::ResourceKind;
+
+const LIBRARIES_URL: &str =
+    "https://libraries.minecraft.net/com/google/guava/guava/32.0.0/guava-32.0.0.jar";
+const ASSET_URL: &str = "https://resources.download.minecraft.net/ab/abcdef0123456789";
+const GITHUB_URL: &str =
+    "https://github.com/AskaEth/Unlucky-Launcher/releases/download/v1.0.0/ull-windows-x64.exe";
+const ADOPTIUM_URL: &str = "https://github.com/adoptium/temurin17-binaries/releases/download/JDK17.0.13%2B11/OpenJDK17U-jdk_x64_windows_hotspot_17.0.13_11.zip";
+
+#[test]
+fn builtin_table_is_embedded_and_complete() {
+    let table = MirrorTable::builtin();
+    assert!(table.version >= 1);
+    assert!(table.rules.len() >= 10, "内置规则太少");
+    assert!(table.adoptium.len() >= 3, "院校镜像至少要 TUNA/USTC/SJTU");
+    assert!(!table.gh_proxies.is_empty());
+    assert!(table.gh_proxies[0].prefix.starts_with("https://gh-proxy"));
+}
+
+#[test]
+fn prefix_rule_preserves_sub_path() {
+    let table = MirrorTable::builtin();
+    let rule = table
+        .prefix_rule_for(LIBRARIES_URL, ResourceKind::Library)
+        .expect("libraries 规则缺失");
+    let candidate = rule.apply(LIBRARIES_URL).expect("重写失败");
+    assert_eq!(candidate.source, "bmclapi");
+    assert_eq!(
+        candidate.url,
+        LIBRARIES_URL.replace(
+            "https://libraries.minecraft.net",
+            "https://bmclapi2.bangbang93.com"
+        )
+    );
+}
+
+#[test]
+fn asset_rule_injects_path_prefix() {
+    let table = MirrorTable::builtin();
+    let candidate = table
+        .prefix_rule_for(ASSET_URL, ResourceKind::Asset)
+        .and_then(|rule| rule.apply(ASSET_URL))
+        .expect("资源对象规则缺失");
+    assert_eq!(
+        candidate.url,
+        "https://bmclapi2.bangbang93.com/assets/ab/abcdef0123456789"
+    );
+}
+
+#[test]
+fn direct_mode_puts_official_first() {
+    let table = MirrorTable::builtin();
+    let region = RegionProfile::direct(0);
+    let candidates = table.expand(LIBRARIES_URL, ResourceKind::Library, ®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}"));
+
+    // 清单给设置做默认值。
+    assert_eq!(table.default_gh_proxy(), Some("https://gh-proxy.com/"));
+}
+
+#[test]
+fn adoptium_artifact_parsing_and_mirror_ordering() {
+    let parsed = parse_adoptium_artifact(ADOPTIUM_URL).expect("解析 Temurin 产物名失败");
+    assert_eq!(parsed.major, "17");
+    assert_eq!(parsed.flavor, JdkFlavor::Jdk);
+    assert_eq!(parsed.arch, "x64");
+    assert_eq!(parsed.os, "windows");
+    assert!(parsed.filename.starts_with("OpenJDK17U-jdk_x64_windows"));
+
+    let table = MirrorTable::builtin();
+    let region = RegionProfile::mirror_first(0);
+    let candidates = table.expand(ADOPTIUM_URL, ResourceKind::JavaRuntime, ®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..0647e22
--- /dev/null
+++ b/crates/core/tests/game/java_vendor_chain.rs
@@ -0,0 +1,183 @@
+//! D23 发行版回退链：地区默认序、用户优先级覆盖、能力过滤、mirrors v3 三张新表。
+//!
+//! 全部离线：只跑纯函数与清单解析，不发一个请求。
+//! 真机验收（TUNA 装 17 / 华为云装 Oracle 21 / `%APPDATA%` 落点）见 mission 报告。
+
+use unlucky_core::download::MirrorTable;
+use unlucky_core::game::java::install::chain_order;
+use unlucky_core::game::java::release::{parse_sha256_text, JdkArchive, JdkRelease};
+use unlucky_core::game::java::vendor::{ids, order, parse_priority, JdkVendor, VENDOR_IDS};
+use unlucky_core::game::java::InstallRequest;
+
+fn vendors(items: &[&str]) -> Vec {
+    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"]);
+    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..c861b6b
--- /dev/null
+++ b/crates/core/tests/launch/exit_cases.rs
@@ -0,0 +1,169 @@
+//! 退出分析测试：退出码语义 + `exit 0` 静默失败（`analyse/02` §6.3 §7.2 §7.10-10）。
+
+use crate::prelude::*;
+
+fn line(stream: Stream, text: &str) -> LogLine {
+    LogLine::new(stream, text)
+}
+
+fn analyze(
+    code: i32,
+    uptime_ms: u64,
+    lines: &[LogLine],
+    posix: bool,
+) -> unlucky_core::launch::exit_analysis::ExitAnalysis {
+    let mut signals = exit_analysis::ExitSignals::new(code, uptime_ms, lines);
+    signals.is_posix = posix;
+    exit_analysis::analyze(&signals)
+}
+
+#[test]
+fn clean_long_run_is_normal() {
+    let lines = vec![line(
+        Stream::Stdout,
+        "[12:00:00] [Render thread/INFO]: started",
+    )];
+    let analysis = analyze(0, 120_000, &lines, true);
+    assert_eq!(analysis.exit_type, ExitType::Normal);
+    assert!(analysis.silent_failure.is_none());
+    assert!(!analysis.needs_diagnosis);
+}
+
+#[test]
+fn exit_zero_short_lived_is_silent_failure() {
+    let lines = vec![line(Stream::Stdout, "Stopping!")];
+    let analysis = analyze(0, 8_000, &lines, true);
+    assert_eq!(analysis.exit_type, ExitType::Normal);
+    let silent = analysis.silent_failure.expect("应标记静默失败");
+    assert!(silent.short_lived);
+    assert!(!silent.error_output);
+    assert!(analysis.needs_diagnosis, "静默失败必须进诊断流水线");
+}
+
+#[test]
+fn exit_zero_with_error_output_is_silent_failure() {
+    let lines = vec![
+        line(Stream::Stdout, "[12:00:00] [main/INFO]: loading"),
+        line(
+            Stream::Stderr,
+            "java.lang.RuntimeException: mixin apply failed",
+        ),
+    ];
+    let analysis = analyze(0, 90_000, &lines, true);
+    assert_eq!(analysis.exit_type, ExitType::Normal);
+    let silent = analysis.silent_failure.expect("应标记静默失败");
+    assert!(silent.error_output);
+    assert!(!silent.short_lived);
+    assert!(silent.describe().contains("错误特征"));
+    assert_eq!(analysis.error_lines, 1);
+}
+
+#[test]
+fn jvm_keywords_take_precedence() {
+    let lines = vec![line(
+        Stream::Stderr,
+        "Error occurred during initialization of VM",
+    )];
+    let analysis = analyze(1, 500, &lines, true);
+    assert_eq!(analysis.exit_type, ExitType::JvmError);
+    assert_eq!(analysis.jvm_keywords.len(), 1);
+    assert!(analysis.needs_diagnosis);
+}
+
+#[test]
+fn nonzero_without_keywords_is_application_error() {
+    let lines = vec![line(Stream::Stdout, "[12:00:00] [main/INFO]: hi")];
+    let analysis = analyze(1, 40_000, &lines, true);
+    assert_eq!(analysis.exit_type, ExitType::ApplicationError);
+    assert!(analysis.needs_diagnosis);
+}
+
+#[test]
+fn crash_keywords_promote_exit_zero() {
+    let lines = vec![line(
+        Stream::Stdout,
+        "[12:00:00] [Render thread/ERROR]: Crash report saved to ./crash-reports/crash-1.txt",
+    )];
+    let analysis = analyze(0, 60_000, &lines, true);
+    assert_eq!(analysis.exit_type, ExitType::ApplicationError);
+    assert_eq!(analysis.crash_keywords.len(), 1);
+    assert!(
+        analysis.silent_failure.is_none(),
+        "已判异常就不再是静默失败"
+    );
+}
+
+#[test]
+fn posix_signals_are_recognized() {
+    assert_eq!(analyze(137, 60_000, &[], true).exit_type, ExitType::SigKill);
+    assert_eq!(analyze(143, 60_000, &[], true).exit_type, ExitType::SigTerm);
+    // Windows 上 137 没有信号语义，按应用错误处理。
+    assert_eq!(
+        analyze(137, 60_000, &[], false).exit_type,
+        ExitType::ApplicationError
+    );
+}
+
+#[test]
+fn windows_ntstatus_is_explained() {
+    let analysis = analyze(-1_073_741_819, 60_000, &[], false);
+    assert_eq!(analysis.exit_type, ExitType::ApplicationError);
+    assert_eq!(
+        analysis.windows_status.as_deref(),
+        Some("0xC0000005 ACCESS_VIOLATION")
+    );
+
+    let dll = analyze(-1_073_741_515, 60_000, &[], false);
+    assert_eq!(
+        dll.windows_status.as_deref(),
+        Some("0xC0000135 DLL_NOT_FOUND")
+    );
+
+    // 0xC000013A = STATUS_CONTROL_C_EXIT（控制台 Ctrl+C / 关窗口），十进制 -1073741510。
+    let control_c = analyze(-1_073_741_510, 60_000, &[], false);
+    assert_eq!(
+        control_c.windows_status.as_deref(),
+        Some("0xC000013A CONTROL_C_EXIT")
+    );
+    // 回归：-1073741743 其实是 0xC0000051，不得被当成 CONTROL_C_EXIT。
+    assert!(analyze(-1_073_741_743, 60_000, &[], false)
+        .windows_status
+        .is_none());
+}
+
+#[test]
+fn killed_and_interrupted_override_exit_code() {
+    let mut signals = exit_analysis::ExitSignals::new(1, 5_000, &[]);
+    signals.killed = true;
+    assert_eq!(exit_analysis::analyze(&signals).exit_type, ExitType::Killed);
+
+    let mut signals = exit_analysis::ExitSignals::new(1, 5_000, &[]);
+    signals.interrupted = true;
+    assert_eq!(
+        exit_analysis::analyze(&signals).exit_type,
+        ExitType::Interrupted
+    );
+}
+
+#[test]
+fn exit_type_strings_match_contract() {
+    // 与 M15 刻意保持一致的字符串集合（`launch-接口约定.md` §3）。
+    assert_eq!(ExitType::Normal.as_str(), "normal");
+    assert_eq!(ExitType::ApplicationError.as_str(), "application_error");
+    assert_eq!(ExitType::JvmError.as_str(), "jvm_error");
+    assert_eq!(ExitType::SigKill.as_str(), "sigkill");
+    assert_eq!(ExitType::SigTerm.as_str(), "sigterm");
+    assert_eq!(ExitType::Killed.as_str(), "killed");
+    assert_eq!(ExitType::Interrupted.as_str(), "interrupted");
+    assert!(!ExitType::Normal.is_abnormal());
+    assert!(ExitType::JvmError.is_abnormal());
+}
+
+#[test]
+fn summary_is_human_readable() {
+    let analysis = analyze(-1_073_741_819, 61_500, &[], false);
+    let summary = analysis.summary();
+    assert!(summary.contains("-1073741819"));
+    assert!(summary.contains("61.5s"));
+    assert!(summary.contains("ACCESS_VIOLATION"));
+}
diff --git a/crates/core/tests/launch/graphics_backend_cases.rs b/crates/core/tests/launch/graphics_backend_cases.rs
new file mode 100644
index 0000000..d8c5759
--- /dev/null
+++ b/crates/core/tests/launch/graphics_backend_cases.rs
@@ -0,0 +1,147 @@
+//! `--graphicsBackend` 的两套判据（能力位 vs 精确版本门）与周快照放行。
+//!
+//! 事实基线（`research/05-mc-vulkan.md` §3.2/§4.2，实测）：
+//! - `--graphicsBackend` 从 **26.2-snapshot-2**（2026-04-09）才有；
+//! - `org.lwjgl:lwjgl-vulkan` 从 **26.2-snapshot-1**（2026-04-07）就有 —— 差两天；
+//! - 周快照（`26w14a`）无法与 `26.2-snapshot-N` 排序，只能靠库表判。
+//!
+//! 结论：能力位**不能**替代精确版本门，两者的分工是本文件的断言对象。
+
+use unlucky_core::launch::game_args::{graphics_backend_allowed, GRAPHICS_BACKEND_MIN_VERSION};
+
+use crate::prelude::*;
+
+#[test]
+fn known_versions_use_the_exact_threshold_and_ignore_the_capability_bit() {
+    // 26.2-snapshot-1：有 Vulkan 库却没有参数，绝不能因为能力位放行
+    // （jopt-simple 未开 allowsUnrecognizedOptions，未声明选项会让游戏直接起不来）。
+    assert!(!graphics_backend_allowed(
+        &GameVersion::parse("26.2-snapshot-1"),
+        true
+    ));
+    assert!(!graphics_backend_allowed(
+        &GameVersion::parse("26.2-snapshot-1"),
+        false
+    ));
+    // 门限上的那一版起放行（能力位无关）。
+    assert!(graphics_backend_allowed(
+        &GameVersion::parse(GRAPHICS_BACKEND_MIN_VERSION),
+        false
+    ));
+    assert!(graphics_backend_allowed(&GameVersion::parse("26.2"), false));
+    assert!(graphics_backend_allowed(&GameVersion::parse("26.3"), false));
+    // 可解析的老版本：能力位再真也不放行。
+    assert!(!graphics_backend_allowed(
+        &GameVersion::parse("1.20.1"),
+        true
+    ));
+}
+
+#[test]
+fn weekly_snapshots_fall_back_to_the_capability_bit() {
+    let weekly = GameVersion::parse("26w14a");
+    assert!(!weekly.is_known(), "周快照不做数字排序（不猜）");
+    assert!(weekly.is_weekly_snapshot());
+
+    // 26.1 线（含周快照）没有 lwjgl-vulkan → 丢弃，和以前一样。
+    assert!(!graphics_backend_allowed(&weekly, false));
+    // 带 Vulkan 库的周快照（26.2 之后的周快照）→ 不再一律丢弃（这就是被修的误伤）。
+    assert!(graphics_backend_allowed(&weekly, true));
+    assert!(graphics_backend_allowed(
+        &GameVersion::parse("26w30a"),
+        true
+    ));
+}
+
+#[test]
+fn non_weekly_unknown_versions_are_still_dropped() {
+    // 第三方自定义版本串没有可依据的语义，能力位为真也不猜。
+    let custom = GameVersion::parse("custom-build");
+    assert!(!custom.is_known());
+    assert!(!custom.is_weekly_snapshot());
+    assert!(!graphics_backend_allowed(&custom, true));
+    assert!(!graphics_backend_allowed(&GameVersion::default(), true));
+}
+
+#[test]
+fn weekly_snapshot_shape_is_parsed_narrowly() {
+    for shape in ["20w14a", "26w14a", "26W14A", "12w01a"] {
+        assert!(
+            GameVersion::parse(shape).is_weekly_snapshot(),
+            "{shape} 应识别为周快照"
+        );
+    }
+    for other in ["26.2-snapshot-1", "26w14", "26ww14a", "w14a", "26w14ab", ""] {
+        assert!(
+            !GameVersion::parse(other).is_weekly_snapshot(),
+            "{other} 不该被当成周快照"
+        );
+    }
+}
+
+#[test]
+fn assemble_lets_a_vulkan_weekly_snapshot_through() {
+    let (request, ctx) = weekly_request("26w30a", true);
+    let assembled = assemble(&request, &ctx).expect("组装应成功");
+    assert!(
+        assembled
+            .args
+            .windows(2)
+            .any(|pair| pair[0] == "--graphicsBackend" && pair[1] == "vulkan"),
+        "带 Vulkan 库的周快照应下发 --graphicsBackend：{:?}",
+        assembled.args
+    );
+    assert!(!assembled
+        .warnings
+        .iter()
+        .any(|warning| matches!(warning, AssemblyWarning::GraphicsBackendSkipped { .. })));
+}
+
+#[test]
+fn assemble_still_drops_it_for_a_pre_vulkan_weekly_snapshot() {
+    let (request, ctx) = weekly_request("26w14a", false);
+    let assembled = assemble(&request, &ctx).expect("组装应成功");
+    assert!(!assembled.args.iter().any(|arg| arg == "--graphicsBackend"));
+    assert!(assembled
+        .warnings
+        .iter()
+        .any(|warning| matches!(warning, AssemblyWarning::GraphicsBackendSkipped { .. })));
+}
+
+#[test]
+fn adapter_derives_the_capability_bit_from_the_library_names() {
+    let dir = temp_dir("adapter-vulkan-capability");
+    let with_vulkan = vec![
+        LibraryInput::new(dir.join("libraries/lwjgl.jar"), "org.lwjgl:lwjgl:3.4.3"),
+        LibraryInput::new(
+            dir.join("libraries/lwjgl-vulkan.jar"),
+            "org.lwjgl:lwjgl-vulkan:3.4.3",
+        ),
+    ];
+    let without_vulkan = vec![LibraryInput::new(
+        dir.join("libraries/lwjgl.jar"),
+        "org.lwjgl:lwjgl:3.4.3",
+    )];
+
+    for (libraries, expected) in [(&with_vulkan, true), (&without_vulkan, false)] {
+        let snapshot = SnapshotInput {
+            main_class: Some("net.minecraft.client.main.Main"),
+            libraries,
+            ..SnapshotInput::minimal("26.3", "")
+        };
+        let output = build_request(&snapshot, AdapterOptions::strict());
+        assert_eq!(
+            output.request.manifest.has_vulkan_backend, expected,
+            "库表 {libraries:?} 的能力位判定不对"
+        );
+    }
+}
+
+/// 一个只关心 `--graphicsBackend` 的请求（周快照版本 + 指定能力位）。
+fn weekly_request(version: &str, has_vulkan_backend: bool) -> (LaunchRequest, PlatformCtx) {
+    let (mut request, ctx) = legacy_forge_request();
+    request.instance.version = GameVersion::parse(version);
+    request.manifest.has_vulkan_backend = has_vulkan_backend;
+    request.graphics_backend = Some("vulkan".to_string());
+    (request, ctx)
+}
diff --git a/crates/core/tests/launch/main.rs b/crates/core/tests/launch/main.rs
new file mode 100644
index 0000000..f6d53ac
--- /dev/null
+++ b/crates/core/tests/launch/main.rs
@@ -0,0 +1,16 @@
+//! launch 模块集成测试入口（`cargo test --test launch`）。
+
+mod adapter_cases;
+mod cmdline_snapshot;
+mod command_builder_cases;
+mod exit_cases;
+mod graphics_backend_cases;
+mod natives_args_cases;
+mod natives_cases;
+mod pipeline_cases;
+mod prelude;
+mod process_smoke;
+mod pump_buffer;
+mod session_events;
+mod sink_cases;
+mod tree_kill_cases;
diff --git a/crates/core/tests/launch/natives_args_cases.rs b/crates/core/tests/launch/natives_args_cases.rs
new file mode 100644
index 0000000..027345a
--- /dev/null
+++ b/crates/core/tests/launch/natives_args_cases.rs
@@ -0,0 +1,136 @@
+//! natives 时代分界与参数接线：清单口径收集、`-Djava.library.path` 归属、1.19+ 四个目录属性。
+//!
+//! 抽取行为本身在 `natives_cases.rs`；这里只验「参数从哪来、收集口径对不对」。
+
+use unlucky_core::launch::natives;
+
+use crate::prelude::*;
+
+/// 参数接线：legacy 清单没有 `arguments.jvm`，`-Djava.library.path` 由启动器补且只补一次。
+#[test]
+fn legacy_manifest_gets_single_java_library_path() {
+    let (request, ctx) = legacy_forge_request();
+    let command = assemble(&request, &ctx).expect("组装应成功");
+    let natives = request.dirs.natives_dir.display().to_string();
+    let library_path: Vec<&String> = command
+        .args
+        .iter()
+        .filter(|arg| arg.starts_with("-Djava.library.path="))
+        .collect();
+    assert_eq!(library_path.len(), 1, "legacy 只该有一条：{library_path:?}");
+    assert_eq!(library_path[0], &format!("-Djava.library.path={natives}"));
+}
+
+/// 参数接线：1.13+ 清单自带 `-Djava.library.path=${natives_directory}`，启动器不得重复注入。
+#[test]
+fn modern_manifest_keeps_its_own_library_path_once() {
+    let (mut request, ctx) = legacy_forge_request();
+    let natives = request.dirs.natives_dir.display().to_string();
+    request.manifest.jvm = vec![
+        ArgumentEntry::plain(["-Djava.library.path=${natives_directory}".to_string()]),
+        ArgumentEntry::plain(["-cp".to_string(), "${classpath}".to_string()]),
+    ];
+    request.manifest.legacy_arguments = None;
+    let command = assemble(&request, &ctx).expect("组装应成功");
+    let library_path: Vec<&String> = command
+        .args
+        .iter()
+        .filter(|arg| arg.starts_with("-Djava.library.path="))
+        .collect();
+    assert_eq!(library_path.len(), 1, "清单 + 默认值不该叠加");
+    assert_eq!(library_path[0], &format!("-Djava.library.path={natives}"));
+}
+
+/// 参数接线：1.19+ 的四个目录属性都要渲染到同一目录（LWJGL 3.3 运行期往那里解压）。
+#[test]
+fn classpath_native_era_renders_all_four_directory_properties() {
+    let (mut request, ctx) = legacy_forge_request();
+    let natives = request.dirs.natives_dir.display().to_string();
+    request.manifest.jvm = vec![ArgumentEntry::plain([
+        "-Djava.library.path=${natives_directory}".to_string(),
+        "-Djna.tmpdir=${natives_directory}".to_string(),
+        "-Dorg.lwjgl.system.SharedLibraryExtractPath=${natives_directory}".to_string(),
+        "-Dio.netty.native.workdir=${natives_directory}".to_string(),
+    ])];
+    request.manifest.legacy_arguments = None;
+    let command = assemble(&request, &ctx).expect("组装应成功");
+    for key in [
+        "-Djava.library.path=",
+        "-Djna.tmpdir=",
+        "-Dorg.lwjgl.system.SharedLibraryExtractPath=",
+        "-Dio.netty.native.workdir=",
+    ] {
+        assert!(
+            command
+                .args
+                .iter()
+                .any(|arg| arg == &format!("{key}{natives}")),
+            "缺少 {key}{natives}：{:?}",
+            command.args
+        );
+    }
+}
+
+/// 收集口径：`natives` 表按 OS 命中 → 分类器 jar；1.19+ 无表 → 空；
+/// `hint=local` 走实例私有目录（HMCL `analyse/03` §6.8 口径）。
+///
+/// 注意：安装层当前的 natives 分类器分支**不认** `hint=local`（走共享 `libraries/`），
+/// 所以这一条断言测的是 `collect` 的正确行为，不是「与安装层一致」——见
+/// `collect` 文档里的已知缺口说明。
+#[test]
+fn collect_picks_classifier_jars_per_environment() {
+    use unlucky_core::game::{Environment, GameLayout, Library};
+
+    let libraries: Vec = 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..d289cc2
--- /dev/null
+++ b/crates/core/tests/launch/natives_cases.rs
@@ -0,0 +1,281 @@
+//! natives 解压（`launch::natives`）的用例：解析正确性 / 排除项 / 幂等 / 时代参数 / 事件流。
+//!
+//! 假 jar 用 `zip` 的 Stored 模式现造（不依赖真下载），真机验收另有人工步骤。
+
+use std::fs::File;
+use std::io::Write;
+use std::path::{Path, PathBuf};
+
+use zip::write::SimpleFileOptions;
+use zip::{CompressionMethod, ZipWriter};
+
+use unlucky_core::launch::natives::{self, NativeJar, NativesEra, NativesPlan, STAMP_FILE};
+
+use crate::prelude::*;
+
+/// 造一个 natives jar：`entries` 是（条目名, 内容）。
+fn make_jar(path: &Path, entries: &[(&str, &[u8])]) {
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent).expect("建 jar 目录");
+    }
+    let file = File::create(path).expect("建 jar");
+    let mut writer = ZipWriter::new(file);
+    let options = SimpleFileOptions::default().compression_method(CompressionMethod::Stored);
+    for (name, bytes) in entries {
+        writer.start_file(*name, options).expect("写条目");
+        writer.write_all(bytes).expect("写条目内容");
+    }
+    writer.finish().expect("收尾 jar");
+}
+
+/// 一份 1.16.5 风格的 natives jar 的条目集（原生库 + 该被排除的噪音）。
+fn lwjgl_jar_entries() -> Vec<(&'static str, &'static [u8])> {
+    vec![
+        ("lwjgl.dll", b"DLL-BYTES".as_slice()),
+        ("OpenAL.dll", b"OPENAL-BYTES".as_slice()),
+        ("META-INF/MANIFEST.MF", b"manifest".as_slice()),
+        ("META-INF/LWJGL.SF", b"signature".as_slice()),
+        ("lwjgl.dll.sha1", b"deadbeef".as_slice()),
+        ("README.txt", b"noise".as_slice()),
+    ]
+}
+
+fn plan(jars: Vec) -> NativesPlan {
+    NativesPlan::new(jars)
+}
+
+#[test]
+fn extracts_native_libraries_and_drops_noise() {
+    let root = temp_dir("natives-extract");
+    let jar = root.join("libraries/lwjgl-natives-windows.jar");
+    make_jar(&jar, &lwjgl_jar_entries());
+    let target = root.join("versions/1.16.5/natives");
+
+    let report =
+        natives::extract(&target, &plan(vec![NativeJar::new(&jar, "lwjgl")])).expect("解压应成功");
+
+    assert_eq!(report.files, 2, "只该解出两个原生库：{report:?}");
+    assert!(!report.up_to_date);
+    assert_eq!(report.jars, 1);
+    // META-INF/ 两条 + .sha1 + README.txt。
+    assert_eq!(report.ignored, 4, "噪音条目数：{report:?}");
+    assert_eq!(
+        std::fs::read(target.join("lwjgl.dll")).expect("读 dll"),
+        b"DLL-BYTES"
+    );
+    assert!(target.join("OpenAL.dll").is_file());
+    assert!(!target.join("META-INF").exists(), "META-INF/ 不该落地");
+    assert!(!target.join("lwjgl.dll.sha1").exists(), "签名文件不该落地");
+    assert!(!target.join("README.txt").exists(), "非原生库不该落地");
+    assert!(target.join(STAMP_FILE).is_file(), "应写戳记");
+}
+
+#[test]
+fn second_run_is_idempotent_and_source_change_reextracts() {
+    let root = temp_dir("natives-idempotent");
+    let jar = root.join("natives-windows.jar");
+    make_jar(&jar, &[("lwjgl.dll", b"V1".as_slice())]);
+    let target = root.join("natives");
+    let extract_plan = plan(vec![NativeJar::new(&jar, "lwjgl")]);
+
+    let first = natives::extract(&target, &extract_plan).expect("首次解压");
+    assert_eq!(first.files, 1);
+    assert!(!first.up_to_date);
+
+    // 第二次：戳记命中，零写盘（文件 mtime 不变）。
+    let before = std::fs::metadata(target.join("lwjgl.dll"))
+        .expect("stat")
+        .modified()
+        .expect("mtime");
+    let second = natives::extract(&target, &extract_plan).expect("二次解压");
+    assert!(second.up_to_date, "应判定目录已就绪：{second:?}");
+    assert_eq!(second.files, 0);
+    assert_eq!(second.skipped, 1);
+    let after = std::fs::metadata(target.join("lwjgl.dll"))
+        .expect("stat")
+        .modified()
+        .expect("mtime");
+    assert_eq!(before, after, "幂等路径不该重写文件");
+
+    // 源 jar 变了（内容 + 长度都变）：必须重解，且旧的原生库被清掉。
+    make_jar(&jar, &[("lwjgl.dll", b"V2-LONGER".as_slice())]);
+    let third = natives::extract(&target, &extract_plan).expect("三次解压");
+    assert!(!third.up_to_date, "源变了必须重解：{third:?}");
+    assert_eq!(
+        std::fs::read(target.join("lwjgl.dll")).expect("读 dll"),
+        b"V2-LONGER"
+    );
+}
+
+#[test]
+fn stale_native_libraries_are_cleaned_before_reextract() {
+    let root = temp_dir("natives-clean");
+    let jar = root.join("natives-windows.jar");
+    make_jar(&jar, &[("lwjgl.dll", b"NEW".as_slice())]);
+    let target = root.join("natives");
+    std::fs::create_dir_all(&target).expect("建目录");
+    // 上一代遗留（旧版本 / 旧 loader 解出来的），必须清掉，否则两代 dll 混在 java.library.path 里。
+    std::fs::write(target.join("old-lwjgl.dll"), b"stale").expect("写旧 dll");
+    std::fs::write(target.join("keep-me.txt"), b"user file").expect("写用户文件");
+
+    natives::extract(&target, &plan(vec![NativeJar::new(&jar, "lwjgl")])).expect("解压");
+
+    assert!(!target.join("old-lwjgl.dll").exists(), "旧原生库应被清理");
+    assert!(target.join("keep-me.txt").is_file(), "非原生库文件不该被删");
+    assert!(target.join("lwjgl.dll").is_file());
+}
+
+#[test]
+fn empty_plan_still_creates_directory_for_1_19() {
+    // 1.19+ 没有 natives 分类器：目录仍要存在（SharedLibraryExtractPath 指向它）。
+    let root = temp_dir("natives-empty");
+    let target = root.join("versions/1.21.4/natives");
+    let report = natives::extract(&target, &NativesPlan::default()).expect("建目录");
+    assert!(target.is_dir());
+    assert!(report.up_to_date);
+    assert_eq!(report.files, 0);
+    assert_eq!(report.jars, 0);
+    assert_eq!(
+        report.era,
+        NativesEra::ClasspathNative,
+        "默认时代（无 jar）"
+    );
+}
+
+#[test]
+fn missing_directory_is_an_error_not_a_silent_pass() {
+    let plan = NativesPlan::new(vec![NativeJar::new("x.jar", "x")]);
+    let err = natives::extract(Path::new(""), &plan).expect_err("空目录必须报错");
+    assert!(err.message().contains("natives 目录"), "{err}");
+}
+
+#[test]
+fn broken_jar_reports_zip_error() {
+    let root = temp_dir("natives-broken");
+    let jar = root.join("natives-broken.jar");
+    std::fs::write(&jar, b"not a zip at all").expect("写坏 jar");
+    let target = root.join("natives");
+    let err = natives::extract(&target, &plan(vec![NativeJar::new(&jar, "broken")]))
+        .expect_err("坏 jar 必须报错");
+    assert!(err.message().contains("zip"), "错误应点明 zip：{err}");
+}
+
+#[test]
+fn era_detect_covers_three_generations() {
+    assert_eq!(NativesEra::detect(0, 3), NativesEra::Legacy);
+    assert_eq!(NativesEra::detect(9, 3), NativesEra::Lwjgl3);
+    assert_eq!(NativesEra::detect(9, 0), NativesEra::ClasspathNative);
+    assert_eq!(NativesEra::Legacy.as_str(), "legacy");
+    assert_eq!(NativesEra::Lwjgl3.as_str(), "lwjgl3");
+    assert_eq!(NativesEra::ClasspathNative.as_str(), "classpath_native");
+}
+
+/// 事件流：`natives_extracted` 落盘字段与接口约定一致（dir/files/skipped/custom）。
+#[test]
+fn natives_extracted_event_carries_report_fields() {
+    let root = temp_dir("natives-event");
+    let jar = root.join("natives-windows.jar");
+    make_jar(&jar, &[("lwjgl.dll", b"DLL".as_slice())]);
+    let target = root.join("natives");
+    let report =
+        natives::extract(&target, &plan(vec![NativeJar::new(&jar, "lwjgl")])).expect("解压");
+
+    let sessions = temp_sessions_root("natives-event-sessions");
+    let mut writer = SessionWriter::create(
+        &sessions,
+        SessionMeta::new("inst", "1.16.5", "1.16.5"),
+        Redactor::new(),
+    )
+    .expect("建会话");
+    writer.natives_extracted(&report).expect("写事件");
+    let path = writer.path().to_path_buf();
+    writer.finish(EndReason::Exit).expect("收尾");
+
+    let events = read_events(&path);
+    let event = events
+        .iter()
+        .find(|event| event["kind"] == "natives_extracted")
+        .expect("应有 natives_extracted 事件");
+    let payload = &event["payload"];
+    assert_eq!(payload["files"], 1);
+    assert_eq!(payload["skipped"], 0);
+    assert_eq!(payload["custom"], false);
+    assert_eq!(payload["jars"], 1);
+    assert_eq!(payload["up_to_date"], false);
+    assert_eq!(payload["era"], "lwjgl3");
+    assert!(payload["dir"]
+        .as_str()
+        .expect("dir 是字符串")
+        .ends_with("natives"));
+}
+
+/// `--dry-run` 也做环境准备：第二次跑要看到 up_to_date（真机验收的判定依据）。
+#[test]
+fn dry_run_prepares_natives_and_is_idempotent() {
+    let root = temp_dir("natives-dry-run");
+    let jar = root.join("natives-windows.jar");
+    make_jar(&jar, &[("lwjgl.dll", b"DLL".as_slice())]);
+    let natives_dir: PathBuf = root.join("versions/1.16.5/natives");
+
+    let (mut request, _) = legacy_forge_request();
+    request.dirs.natives_dir = natives_dir.clone();
+    request.natives = NativesPlan::new(vec![NativeJar::new(&jar, "lwjgl")]);
+    request.manifest.legacy_arguments = Some("--username ${auth_player_name}".to_string());
+
+    let sessions = temp_sessions_root("natives-dry-run-sessions");
+    let launcher = Launcher::new(LauncherConfig::new(&sessions));
+
+    let first = launcher.dry_run(&request).expect("首次 dry-run");
+    let report = first.natives.expect("应有 natives 报告");
+    assert_eq!(report.files, 1, "{report:?}");
+    assert!(!report.up_to_date);
+    assert!(natives_dir.join("lwjgl.dll").is_file());
+
+    let second = launcher.dry_run(&request).expect("二次 dry-run");
+    let report = second.natives.expect("应有 natives 报告");
+    assert!(report.up_to_date, "第二次应命中戳记：{report:?}");
+    assert_eq!(report.skipped, 1);
+}
+
+/// 缺 natives jar：适配层当成组件缺失（组装前显式失败），而不是等到 UnsatisfiedLinkError。
+#[test]
+fn missing_native_jar_becomes_missing_component() {
+    let (mut request, ctx) = legacy_forge_request();
+    request.natives = NativesPlan::new(vec![NativeJar::new(
+        "C:/mc/libraries/missing-natives-windows.jar",
+        "org.lwjgl:lwjgl:3.2.2:natives-windows",
+    )]);
+    // 直接验证适配层：给一个不存在的 natives jar，严格模式应产出 MissingNativeJar 告警。
+    let libraries: Vec = request
+        .classpath
+        .iter()
+        .map(|path| LibraryInput::new(path.clone(), "x"))
+        .collect();
+    let natives = request.natives.jars.clone();
+    let snapshot = SnapshotInput {
+        version_id: "1.16.5",
+        main_class: Some("net.minecraft.client.main.Main"),
+        libraries: &libraries,
+        natives: &natives,
+        ..SnapshotInput::minimal("1.16.5", "net.minecraft.client.main.Main")
+    };
+    let options = AdapterOptions {
+        java: JavaSelection::new("C:/java/bin/java.exe", 17, 64),
+        ..AdapterOptions::strict()
+    };
+    let output = build_request(&snapshot, options);
+    assert!(
+        output
+            .warnings
+            .iter()
+            .any(|warning| matches!(warning, AdapterWarning::MissingNativeJar { .. })),
+        "应有 MissingNativeJar 告警：{:?}",
+        output.warnings
+    );
+    assert_eq!(output.request.natives.era, NativesEra::Legacy);
+    // 组装按既有语义直接失败（missing_components 非空）。
+    assert!(matches!(
+        assemble(&output.request, &ctx).err(),
+        Some(LaunchError::Assembly(AssemblyError::MissingComponents(_)))
+    ));
+}
diff --git a/crates/core/tests/launch/pipeline_cases.rs b/crates/core/tests/launch/pipeline_cases.rs
new file mode 100644
index 0000000..b14020f
--- /dev/null
+++ b/crates/core/tests/launch/pipeline_cases.rs
@@ -0,0 +1,347 @@
+//! 顶层启动管线测试：dry-run（D18）、完整会话、停止、组装失败、崩溃现场。
+//!
+//! 真进程来自 shell（`cmd /C` 或 `sh -c`），所以这些是端到端用例：
+//! 命令行组装 → 事件流落盘 → 退出判定 → 诊断挂钩 → 索引。
+
+use std::path::PathBuf;
+use std::sync::{Arc, Mutex};
+use std::time::Duration;
+
+use serde_json::json;
+
+use crate::prelude::*;
+
+/// 记录调用并返回固定结论的诊断挂钩。
+#[derive(Default)]
+struct RecordingHook {
+    calls: Mutex>,
+}
+
+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() -> String {
+    #[cfg(windows)]
+    {
+        "ping -n 30 127.0.0.1 >nul".to_string()
+    }
+    #[cfg(not(windows))]
+    {
+        "sleep 30".to_string()
+    }
+}
+
+#[test]
+fn dry_run_returns_command_without_spawning_or_writing() {
+    let sessions = temp_sessions_root("dry");
+    let run_dir = temp_dir("dry-run");
+    let launcher = launcher(&sessions, None);
+    let (request, _) = shell_request(&echo_script(), &run_dir);
+
+    let dry: DryRun = launcher.dry_run(&request).expect("dry-run 应成功");
+    assert!(!dry.argv.is_empty());
+    assert!(
+        dry.display.contains("fake-java")
+            || dry.display.contains("cmd")
+            || dry.display.contains("/bin/sh")
+    );
+    assert!(
+        dry.display.contains(""),
+        "命令行必须脱敏：{}",
+        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);
+
+    let mut session = launcher.spawn(&request).expect("spawn 应成功");
+    assert!(session.pid() > 0);
+    session.stop().expect("停止应成功");
+    let handle = session.finish().expect("收尾应成功");
+
+    assert_eq!(handle.exit.exit_type, ExitType::Killed);
+    assert!(!handle.succeeded());
+    let events = read_events(&handle.log_path);
+    let kinds: Vec<&str> = events
+        .iter()
+        .filter_map(|event| event["kind"].as_str())
+        .collect();
+    assert!(kinds.contains(&"killed"), "应记录 killed 事件：{kinds:?}");
+    let index = session_index::read_all(&session_index::index_path(&sessions)).expect("读索引");
+    assert_eq!(index.len(), 1);
+    assert_eq!(index[0].exit_type.as_deref(), Some("killed"));
+}
+
+#[test]
+fn pipeline_assembly_failure_still_writes_evidence() {
+    let sessions = temp_sessions_root("assembly-fail");
+    let run_dir = temp_dir("assembly-fail-run");
+    let launcher = launcher(&sessions, None);
+    let (mut request, _) = shell_request(&echo_script(), &run_dir);
+    request.missing_components = vec![MissingComponent::named("org.lwjgl:lwjgl:3.3.1")];
+
+    let error = launcher.spawn(&request).expect_err("缺组件必须启动前失败");
+    assert!(matches!(
+        error,
+        LaunchError::Assembly(AssemblyError::MissingComponents(_))
+    ));
+
+    let game_dir = sessions.join("game");
+    let files: Vec = 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..a24d2b5
--- /dev/null
+++ b/crates/core/tests/launch/prelude.rs
@@ -0,0 +1,149 @@
+//! 测试共用设施。
+//!
+//! **crate 名只在本文件出现**（tower 定案 `unlucky_core`；若 M11 改包名，只改这里）。
+
+use std::path::PathBuf;
+
+pub use unlucky_core::launch::args_table::{assemble, AssembledCommand, AssemblyWarning};
+pub use unlucky_core::launch::argument::{ArgumentEntry, Rule};
+pub use unlucky_core::launch::command_builder::{self, CommandBuilder};
+pub use unlucky_core::launch::error::{AssemblyError, LaunchError, MissingComponent};
+pub use unlucky_core::launch::exit_analysis::{self, ExitType};
+pub use unlucky_core::launch::game_version::GameVersion;
+pub use unlucky_core::launch::log_level::{self, Level};
+pub use unlucky_core::launch::platform::{OsFamily, PlatformCtx};
+pub use unlucky_core::launch::pump::{LineSink, LogLine, RingBuffer, RingBufferConfig, Stream};
+pub use unlucky_core::launch::redact::{Redactor, TOKEN_PLACEHOLDER};
+pub use unlucky_core::launch::request::*;
+pub use unlucky_core::launch::session::{EndReason, SessionMeta, SessionSink, SessionWriter};
+pub use unlucky_core::launch::session_index;
+pub use unlucky_core::launch::window_detect::WindowDetector;
+
+pub use unlucky_core::launch::adapter::{
+    build_request, AdapterOptions, AdapterWarning, LibraryInput, SnapshotInput,
+};
+pub use unlucky_core::launch::crash_scan::CrashSource;
+pub use unlucky_core::launch::diagnosis_hook::{DiagnosisHook, DiagnosisRequest};
+pub use unlucky_core::launch::launch_session::SessionHandle;
+pub use unlucky_core::launch::launcher::{DryRun, Launcher, LauncherConfig};
+pub use unlucky_core::launch::process::ProcessConfig;
+pub use unlucky_core::launch::sink::{CompositeSink, CountingSink, FnSink};
+
+/// 断言 argv 逐项相等，失败时打印全部实际值。
+pub fn assert_argv(command: &AssembledCommand, expected: &[&str]) {
+    let actual = command.argv();
+    if actual.len() != expected.len() {
+        panic!(
+            "argv 长度 {} != 期望 {}\n实际:\n{:#?}",
+            actual.len(),
+            expected.len(),
+            actual
+        );
+    }
+    for (index, (actual, expected)) in actual.iter().zip(expected.iter()).enumerate() {
+        assert_eq!(actual, expected, "第 {index} 个参数不同");
+    }
+}
+
+/// 一个“1.12.2 + Forge”的基准请求（Windows/x86_64）。
+pub fn legacy_forge_request() -> (LaunchRequest, PlatformCtx) {
+    let ctx = PlatformCtx::new(OsFamily::Windows, "x86_64");
+    let request = LaunchRequest {
+        instance: InstanceInfo {
+            id: "inst-1".to_string(),
+            name: "1.12.2-Forge".to_string(),
+            version: GameVersion::parse("1.12.2"),
+            version_type: "release".to_string(),
+        },
+        launcher: LauncherInfo {
+            name: "UnluckyLauncher".to_string(),
+            version: "0.1.0".to_string(),
+        },
+        java: JavaSelection::new("C:/java/bin/java.exe", 17, 64),
+        memory: MemoryOptions {
+            min_mb: Some(1024),
+            max_mb: Some(4096),
+        },
+        manifest: ManifestArgs {
+            main_class: Some("net.minecraft.launchwrapper.Launch".to_string()),
+            ..ManifestArgs::default()
+        },
+        dirs: LaunchDirs {
+            game_dir: PathBuf::from("C:/mc"),
+            assets_root: PathBuf::from("C:/mc/assets"),
+            game_assets: PathBuf::from("C:/mc/assets/virtual/legacy"),
+            assets_index: "1.12".to_string(),
+            natives_dir: PathBuf::from("C:/mc/versions/1.12.2/natives-windows-x86_64"),
+            library_dir: PathBuf::from("C:/mc/libraries"),
+            primary_jar: PathBuf::from("C:/mc/versions/1.12.2/1.12.2.jar"),
+        },
+        classpath: vec![
+            PathBuf::from("C:/mc/libraries/a.jar"),
+            PathBuf::from("C:/mc/libraries/b.jar"),
+        ],
+        auth: AuthPlaceholders {
+            player_name: "Steve".to_string(),
+            uuid: "0123456789abcdef0123456789abcdef".to_string(),
+            access_token: "SECRET-TOKEN-123456".to_string(),
+            user_type: "msa".to_string(),
+            user_properties: "{}".to_string(),
+        },
+        log4j: Log4jOptions {
+            enabled: true,
+            config_file: Some(PathBuf::from("C:/mc/log4j2.xml")),
+            debug: false,
+        },
+        // 大部分断言只关心“命令骨架”，优化参数会淹没差异；需要时单独打开。
+        optimization: OptimizationOptions {
+            enabled: false,
+            physical_memory_mb: None,
+        },
+        language: "zh-CN".to_string(),
+        features: FeatureSet {
+            has_custom_resolution: true,
+            ..FeatureSet::default()
+        },
+        resolution: Some(Resolution {
+            width: 854,
+            height: 480,
+        }),
+        ..LaunchRequest::default()
+    };
+    (request, ctx)
+}
+
+/// 一个唯一的临时目录（不自动清理，便于失败时排查；OS 会回收）。
+pub fn temp_dir(name: &str) -> PathBuf {
+    let nanos = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|value| value.as_nanos())
+        .unwrap_or_default();
+    let dir =
+        std::env::temp_dir().join(format!("ull-launch-{name}-{}-{nanos}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    std::fs::create_dir_all(&dir).expect("创建临时目录");
+    dir
+}
+
+/// 一个唯一的临时会话根目录（测试结束不自动清理，便于失败时排查；OS 会回收）。
+pub fn temp_sessions_root(name: &str) -> PathBuf {
+    let nanos = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|value| value.as_nanos())
+        .unwrap_or_default();
+    let root = std::env::temp_dir().join(format!(
+        "ull-launch-test-{name}-{}-{nanos}",
+        std::process::id()
+    ));
+    let _ = std::fs::remove_dir_all(&root);
+    root
+}
+
+/// 读回 jsonl 的每一行并解析成 JSON。
+pub fn read_events(path: &std::path::Path) -> Vec {
+    let text = std::fs::read_to_string(path).expect("读取会话文件");
+    text.lines()
+        .filter(|line| !line.trim().is_empty())
+        .map(|line| serde_json::from_str(line).expect("解析事件行"))
+        .collect()
+}
diff --git a/crates/core/tests/launch/process_smoke.rs b/crates/core/tests/launch/process_smoke.rs
new file mode 100644
index 0000000..fcf959b
--- /dev/null
+++ b/crates/core/tests/launch/process_smoke.rs
@@ -0,0 +1,167 @@
+//! 进程冒烟测试：真实 spawn 一个 shell，验证泵、退出码、进程树 kill。
+//!
+//! 这些用例跑的是真进程（不是 mock），是“事件流 + 退出分析 + 树 kill”端到端的最小证据。
+
+use std::path::PathBuf;
+use std::sync::Arc;
+use std::time::Duration;
+
+use crate::prelude::*;
+
+use unlucky_core::launch::process::{self, ProcessConfig, RunningProcess};
+use unlucky_core::launch::pump::{LineSink, NullSink};
+
+fn shell_command(script: &str) -> AssembledCommand {
+    #[cfg(windows)]
+    let (program, args) = (
+        "cmd".to_string(),
+        vec!["/C".to_string(), script.to_string()],
+    );
+    #[cfg(not(windows))]
+    let (program, args) = (
+        "/bin/sh".to_string(),
+        vec!["-c".to_string(), script.to_string()],
+    );
+    AssembledCommand {
+        program: PathBuf::from(program),
+        args,
+        classpath: Vec::new(),
+        encoding: "UTF-8".to_string(),
+        memory: MemoryOptions::default(),
+        env: Vec::new(),
+        warnings: Vec::new(),
+        main_class: String::new(),
+    }
+}
+
+fn config() -> ProcessConfig {
+    ProcessConfig {
+        graceful_stop: Duration::from_millis(200),
+        ..ProcessConfig::default()
+    }
+}
+
+#[test]
+fn spawn_collects_both_streams_and_exit_code() {
+    let root = temp_sessions_root("smoke");
+    let meta = SessionMeta::new("inst-1", "smoke", "1.20.1");
+    let writer =
+        SessionWriter::create_with_id(&root, "smoke-1", meta, Redactor::new()).expect("创建会话");
+    let path = writer.path().to_path_buf();
+    let sink = Arc::new(SessionSink::new(writer));
+
+    let mut child = RunningProcess::spawn(
+        &shell_command("echo hello-from-stdout & echo hello-from-stderr 1>&2"),
+        None,
+        sink.clone(),
+        config(),
+    )
+    .expect("spawn 应成功");
+
+    let status = child.wait().expect("wait 应成功");
+    assert_eq!(process::exit_code(&status), 0);
+    assert!(child.pid() > 0);
+
+    let verdict = child.supervise();
+    assert!(verdict.is_complete(), "两条流都应在预算内结束");
+
+    let texts: Vec = 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/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..c235bd9
--- /dev/null
+++ b/crates/core/tests/setting/appearance_keys.rs
@@ -0,0 +1,204 @@
+//! 「外观（高级）」键簇（`setting::appearance` + `keys::launcher_schema` 的 appearance.* 段）。
+//!
+//! 守三条设计约束（09-ui-layout §111）：
+//! 1. 一切高级特性**默认关闭**（出厂 Metro 纯色）——默认值即出厂态；
+//! 2. 全部走 D6 schema 且 **AI 可写**（白名单内，可被 agent 调节）；
+//! 3. 值域有硬边界（滑条夹取），坏值/手改配置不崩（回落默认）。
+
+use serde_json::json;
+use unlucky_core::setting::appearance::{
+    hex_to_rgb, normalize_hex, relative_luminance, Appearance, BgFill, DEFAULT_ACCENT,
+    PANEL_ALPHA_MIN,
+};
+use unlucky_core::setting::document::SettingDocument;
+use unlucky_core::setting::keys::{launcher_schema, launcher_version};
+use unlucky_core::setting::spec::ValueKind;
+
+fn doc(raw: serde_json::Value) -> SettingDocument {
+    SettingDocument::load(&launcher_schema(), &raw).0
+}
+
+#[test]
+fn factory_defaults_are_all_advanced_features_off() {
+    let appearance = Appearance::from_store(&unlucky_core::setting::store::SettingStore::load(
+        std::env::temp_dir().join(format!("ull-appearance-none-{}.json", std::process::id())),
+        launcher_schema(),
+    ));
+    assert_eq!(appearance.theme_mode, "auto", "D17：出厂跟随系统");
+    assert!(!appearance.bg_image_enabled, "背景图默认关");
+    assert!(!appearance.bg_image_active());
+    assert_eq!(appearance.bg_fill, BgFill::Cover);
+    assert_eq!(appearance.panel_alpha, 1.0, "出厂完全不透明（Metro 纯色）");
+    assert!(!appearance.glass, "玻璃拟态默认关");
+    assert_eq!(appearance.accent_color, "", "空串 = 未自定义");
+    assert_eq!(appearance.accent_or_default(), DEFAULT_ACCENT);
+}
+
+#[test]
+fn reading_a_configured_document_reflects_each_key() {
+    let document = doc(json!({
+        "appearance": {
+            "theme_mode": "dark",
+            "bg_image_enabled": true,
+            "bg_image": "D:/wall/paper.png",
+            "bg_fill": "tile",
+            "bg_dim": 0.6,
+            "panel_alpha": 0.8,
+            "glass": true,
+            "accent_color": "#ff5722",
+        }
+    }));
+    let appearance = Appearance::read(&document);
+    assert_eq!(appearance.theme_mode, "dark");
+    assert!(appearance.bg_image_active());
+    assert_eq!(appearance.bg_image, "D:/wall/paper.png");
+    assert_eq!(appearance.bg_fill, BgFill::Tile);
+    assert!((appearance.bg_dim - 0.6).abs() < 1e-9);
+    assert!((appearance.panel_alpha - 0.8).abs() < 1e-9);
+    assert!(appearance.glass);
+    assert_eq!(appearance.accent_color, "#FF5722", "读入即规范化大写");
+    assert_eq!(appearance.accent_or_default(), "#FF5722");
+}
+
+#[test]
+fn bad_values_fall_back_instead_of_panicking() {
+    // 手改坏的配置：枚举拼错 / 开关类型错 / accent 不是 #RRGGBB。
+    let document = doc(json!({
+        "appearance": {
+            "bg_fill": "stretch",
+            "bg_image_enabled": "yes",
+            "accent_color": "rebeccapurple",
+        }
+    }));
+    let appearance = Appearance::read(&document);
+    assert_eq!(appearance.bg_fill, BgFill::Cover);
+    assert!(!appearance.bg_image_enabled);
+    assert_eq!(appearance.accent_color, "");
+    assert_eq!(appearance.accent_or_default(), DEFAULT_ACCENT);
+}
+
+#[test]
+fn panel_alpha_is_clamped_to_the_contrast_floor() {
+    // schema 下限 0.4；读侧再夹一次（挡手改文件绕过 schema 的情况）。
+    let document = doc(json!({ "appearance": { "panel_alpha": 0.05 } }));
+    assert!((Appearance::read(&document).panel_alpha - PANEL_ALPHA_MIN).abs() < 1e-9);
+}
+
+#[test]
+fn appearance_keys_are_all_ai_writable_and_registered() {
+    let schema = launcher_schema();
+    // 主题三态是 D17 已定案的最轻量键（silent/Low），其余高级键留审计痕迹（audited/Medium）。
+    let audited_keys = [
+        "appearance.bg_image_enabled",
+        "appearance.bg_image",
+        "appearance.bg_fill",
+        "appearance.bg_dim",
+        "appearance.panel_alpha",
+        "appearance.glass",
+        "appearance.accent_color",
+        // M91（D36/D37/D38）的外观下层三键，同样 audited。
+        "appearance.window_opacity",
+        "appearance.titlebar_mode",
+        "appearance.palette_source",
+    ];
+    for key in audited_keys {
+        let spec = schema.spec(key).unwrap_or_else(|| panic!("{key} 必须登记"));
+        assert!(spec.ai.writable, "{key} 必须在 AI 可写白名单内");
+        // 纯视觉、可一键复原 → 不要求弹窗确认（High 级留给凭据/数据根/代理）。
+        assert!(
+            !spec.ai.sensitivity.requires_confirmation(),
+            "{key} 不该要确认"
+        );
+        assert_eq!(
+            spec.ai.sensitivity.as_str(),
+            "medium",
+            "{key} 要留审计痕迹（AI 改过什么可回看）"
+        );
+    }
+    // 主题三态仍是 silent（D17 已定案的最轻量键）。
+    assert_eq!(
+        schema
+            .spec("appearance.theme_mode")
+            .unwrap()
+            .ai
+            .sensitivity
+            .as_str(),
+        "low"
+    );
+}
+
+#[test]
+fn schema_registration_shape_is_right() {
+    assert_eq!(
+        launcher_version().minor,
+        5,
+        "1.5.0 登记 M116 的窗口圆角策略键"
+    );
+    let schema = launcher_schema();
+    assert_eq!(
+        schema.spec("appearance.bg_fill").unwrap().kind,
+        ValueKind::Enum(&["cover", "contain", "tile"])
+    );
+    assert!(matches!(
+        schema.spec("appearance.panel_alpha").unwrap().kind,
+        ValueKind::Float { min, max } if (min - PANEL_ALPHA_MIN).abs() < 1e-9 && (max - 1.0).abs() < 1e-9
+    ));
+    assert_eq!(
+        schema.spec("appearance.accent_color").unwrap().kind,
+        ValueKind::Text { max_len: 9 },
+        "#RRGGBB 最多 7 字符，留 9 容错带井号与空白"
+    );
+    // 默认值 = 出厂态
+    assert_eq!(
+        schema.spec("appearance.panel_alpha").unwrap().default,
+        serde_json::Value::from(1.0)
+    );
+    assert_eq!(
+        schema.spec("appearance.glass").unwrap().default,
+        serde_json::Value::from(false)
+    );
+}
+
+#[test]
+fn write_round_trips_through_the_store() {
+    let temp =
+        std::env::temp_dir().join(format!("ull-appearance-{}-{}", std::process::id(), line!()));
+    std::fs::create_dir_all(temp.join("config")).expect("临时目录");
+    let path = temp.join("config/launcher.json");
+    let _ = std::fs::remove_file(&path);
+
+    let mut store = unlucky_core::setting::store::SettingStore::load(&path, launcher_schema());
+    let mut appearance = Appearance::from_store(&store);
+    appearance.theme_mode = "dark".to_owned();
+    appearance.panel_alpha = 0.8;
+    appearance.bg_image_enabled = true;
+    appearance.bg_image = "D:/wall/p.png".to_owned();
+    appearance.accent_color = "#0f6cbd".to_owned();
+    appearance.write(&mut store).expect("写外观键");
+    store.save().expect("落盘");
+
+    let reloaded = Appearance::from_store(&unlucky_core::setting::store::SettingStore::load(
+        &path,
+        launcher_schema(),
+    ));
+    assert_eq!(reloaded.theme_mode, "dark");
+    assert!((reloaded.panel_alpha - 0.8).abs() < 1e-9);
+    assert!(reloaded.bg_image_active());
+    assert_eq!(reloaded.accent_color, "#0F6CBD");
+
+    std::fs::remove_dir_all(&temp).ok();
+}
+
+#[test]
+fn hex_helpers_validate_and_convert() {
+    assert_eq!(normalize_hex(" 0f6cbd "), Some("#0F6CBD".to_owned()));
+    assert_eq!(normalize_hex("#0F6CBD"), Some("#0F6CBD".to_owned()));
+    assert_eq!(normalize_hex("#0F6CB"), None);
+    assert_eq!(normalize_hex("#GGGGGG"), None);
+    assert_eq!(hex_to_rgb("#0078D4"), Some((0x00, 0x78, 0xD4)));
+    // WCAG 相对亮度：纯黑 0、纯白 1、Metro 蓝居中偏暗。
+    assert!(relative_luminance("#000000").unwrap().abs() < 1e-9);
+    assert!((relative_luminance("#FFFFFF").unwrap() - 1.0).abs() < 1e-9);
+    let metro = relative_luminance(DEFAULT_ACCENT).unwrap();
+    assert!(metro > 0.05 && metro < 0.3, "Metro 蓝亮度 {metro}");
+}
diff --git a/crates/core/tests/setting/atomic_write.rs b/crates/core/tests/setting/atomic_write.rs
new file mode 100644
index 0000000..bd39df2
--- /dev/null
+++ b/crates/core/tests/setting/atomic_write.rs
@@ -0,0 +1,49 @@
+//! 原子写：覆盖语义、父目录创建、不留临时文件、可选读。
+
+use unlucky_core::platform::atomic::{read_optional, tmp_path, write_atomic};
+
+use crate::common::{dir_entries, TempDir};
+
+#[test]
+fn writes_and_replaces_in_place() {
+    let temp = TempDir::new("atomic");
+    let path = temp.child("config/launcher.json");
+
+    write_atomic(&path, b"{\"a\":1}").expect("首次写");
+    assert_eq!(temp.read("config/launcher.json"), "{\"a\":1}");
+
+    write_atomic(&path, b"{\"a\":2}").expect("覆盖写");
+    assert_eq!(temp.read("config/launcher.json"), "{\"a\":2}");
+
+    // 目录里只该有目标文件，临时文件必须被改名掉。
+    assert_eq!(dir_entries(&temp.child("config")), vec!["launcher.json"]);
+}
+
+#[test]
+fn read_optional_distinguishes_missing_from_failure() {
+    let temp = TempDir::new("atomic-read");
+    let path = temp.child("nope.json");
+    assert!(read_optional(&path).expect("读缺失文件").is_none());
+
+    temp.write("here.json", "内容");
+    let bytes = read_optional(&temp.child("here.json"))
+        .expect("读文件")
+        .expect("有内容");
+    assert_eq!(bytes, "内容".as_bytes());
+}
+
+#[test]
+fn tmp_name_stays_in_same_directory() {
+    let temp = TempDir::new("atomic-tmp");
+    let path = temp.child("config/profiles.json");
+    let tmp = tmp_path(&path);
+    assert_eq!(
+        tmp.parent(),
+        path.parent(),
+        "临时文件必须同目录（rename 才原子）"
+    );
+    assert_ne!(tmp, path);
+    let first = tmp_path(&path);
+    let second = tmp_path(&path);
+    assert_ne!(first, second, "并发写要能拿到不同的临时名");
+}
diff --git a/crates/core/tests/setting/common.rs b/crates/core/tests/setting/common.rs
new file mode 100644
index 0000000..4975416
--- /dev/null
+++ b/crates/core/tests/setting/common.rs
@@ -0,0 +1,81 @@
+//! 测试公用小工具（临时目录 + 文件读写）。
+//!
+//! 不引 `tempfile`：M11 的依赖面只有 serde/serde_json，测试自己管临时目录。
+
+#![allow(dead_code)]
+
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+
+static COUNTER: AtomicU64 = AtomicU64::new(0);
+
+/// 进程内唯一的临时目录，`Drop` 时递归删除。
+pub struct TempDir {
+    path: PathBuf,
+}
+
+impl TempDir {
+    /// 建一个临时目录。
+    pub fn new(label: &str) -> Self {
+        let index = COUNTER.fetch_add(1, Ordering::Relaxed);
+        let path = std::env::temp_dir().join(format!(
+            "ull-setting-{label}-{}-{index}",
+            std::process::id()
+        ));
+        std::fs::remove_dir_all(&path).ok();
+        std::fs::create_dir_all(&path).expect("创建临时目录");
+        Self { path }
+    }
+
+    /// 根路径。
+    pub fn path(&self) -> &Path {
+        &self.path
+    }
+
+    /// 拼接子路径（不创建）。
+    pub fn child(&self, name: &str) -> PathBuf {
+        self.path.join(name)
+    }
+
+    /// 写一个文件（自动建父目录）。
+    pub fn write(&self, name: &str, contents: &str) -> PathBuf {
+        let path = self.child(name);
+        if let Some(parent) = path.parent() {
+            std::fs::create_dir_all(parent).expect("创建父目录");
+        }
+        std::fs::write(&path, contents).expect("写文件");
+        path
+    }
+
+    /// 读一个文件。
+    pub fn read(&self, name: &str) -> String {
+        std::fs::read_to_string(self.child(name)).expect("读文件")
+    }
+
+    /// 子路径是否存在。
+    pub fn exists(&self, name: &str) -> bool {
+        self.child(name).exists()
+    }
+}
+
+impl Drop for TempDir {
+    fn drop(&mut self) {
+        std::fs::remove_dir_all(&self.path).ok();
+    }
+}
+
+/// 目录里的文件名（排序后返回，便于断言没留下临时文件）。
+pub fn dir_entries(dir: &Path) -> Vec {
+    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..eab24cd
--- /dev/null
+++ b/crates/core/tests/setting/isolation_keys.rs
@@ -0,0 +1,251 @@
+//! D20 隔离键的 schema 契约：全局 `instances.mode`、实例 `isolation`、`lastModeChange`、
+//! 恒共享层不可配、旧配置缺键即默认值（不需要迁移步骤）。
+
+use serde_json::json;
+use unlucky_core::game::install::instance::{InstanceConfig, Isolation, OverrideKey};
+use unlucky_core::game::isolation::{observe_mode, IsolationMode};
+use unlucky_core::game::GameLayout;
+use unlucky_core::setting::document::{LoadProblem, RenderMode, SettingDocument};
+use unlucky_core::setting::instance_keys::{
+    instance_schema, instance_version, ISOLATION_OVERRIDES, ISOLATION_RESOLVED, OVERRIDE_KEYS,
+};
+use unlucky_core::setting::keys::{launcher_schema, launcher_version, INSTANCE_MODES};
+use unlucky_core::setting::schema::{SchemaId, SchemaVersion};
+use unlucky_core::setting::spec::{Sensitivity, ValueKind};
+use unlucky_core::setting::store::SettingStore;
+
+use super::common::TempDir;
+
+#[test]
+fn global_mode_key_defaults_to_isolated() {
+    let schema = launcher_schema();
+    let spec = schema.spec("instances.mode").expect("instances.mode 键");
+    assert_eq!(spec.default, json!("isolated"), "D20 默认隔离");
+    assert_eq!(spec.kind, ValueKind::Enum(INSTANCE_MODES));
+    assert_eq!(
+        spec.ai.sensitivity,
+        Sensitivity::High,
+        "切档会改变存档可见性，AI 改必须弹窗确认"
+    );
+    assert!(schema.validate("instances.mode", &json!("shared")).is_ok());
+    assert!(schema
+        .validate("instances.mode", &json!("isolated"))
+        .is_ok());
+    assert!(schema
+        .validate("instances.mode", &json!("per_version"))
+        .is_err());
+    assert!(schema.validate("instances.mode", &json!("custom")).is_err());
+}
+
+#[test]
+fn shared_layers_are_not_configurable() {
+    let schema = launcher_schema();
+    for key in ["shared.versions", "shared.assets", "shared.libraries"] {
+        assert!(
+            !schema.is_known(key),
+            "{key} 是恒共享层，不该出现在可配键表里"
+        );
+    }
+}
+
+#[test]
+fn instance_isolation_defaults_to_inherit() {
+    let schema = instance_schema();
+    let spec = schema.spec("isolation").expect("isolation 键");
+    assert_eq!(spec.default, json!("inherit"));
+    assert_eq!(spec.kind, ValueKind::Enum(ISOLATION_OVERRIDES));
+    for value in ["inherit", "isolated", "shared", "custom"] {
+        assert!(
+            schema.validate("isolation", &json!(value)).is_ok(),
+            "{value}"
+        );
+    }
+    assert!(schema.validate("isolation", &json!("per_version")).is_err());
+}
+
+#[test]
+fn inherit_never_reaches_the_file() {
+    // 默认值不落盘：空文档渲染出来只应该有 $schema / schemaVersion。
+    let schema = instance_schema();
+    let (document, problems) = SettingDocument::load(&schema, &json!({}));
+    assert!(problems.is_empty(), "{problems:?}");
+    let rendered = document.render(RenderMode::Full);
+    assert!(rendered.get("isolation").is_none(), "{rendered}");
+    assert!(rendered.get("lastModeChange").is_none(), "{rendered}");
+    let dirty = document.render(RenderMode::DirtyOnly);
+    assert!(dirty.get("isolation").is_none(), "{dirty}");
+}
+
+#[test]
+fn last_mode_change_keys_are_bookkeeping_only() {
+    let schema = instance_schema();
+    for key in [
+        "lastModeChange.at",
+        "lastModeChange.from",
+        "lastModeChange.to",
+        "lastModeChange.probe.isolatedSide",
+        "lastModeChange.probe.sharedSide",
+        "lastModeChange.warned",
+    ] {
+        assert!(schema.is_known(key), "{key} 必须登记");
+        assert!(!schema.accepts_ai_write(key), "{key} 不许 AI 写");
+    }
+    assert!(schema
+        .validate("lastModeChange.probe.isolatedSide", &json!(12))
+        .is_ok());
+    assert!(schema
+        .validate("lastModeChange.probe.isolatedSide", &json!(-1))
+        .is_err());
+    assert!(schema
+        .validate("lastModeChange.warned", &json!(true))
+        .is_ok());
+    assert!(schema.validate("lastModeChange.warned", &json!(1)).is_err());
+    assert!(schema
+        .validate("lastModeChange.from", &json!("shared"))
+        .is_ok());
+    assert!(schema
+        .validate("lastModeChange.from", &json!("inherit"))
+        .is_err());
+    assert_eq!(ISOLATION_RESOLVED, ["isolated", "shared", "custom"]);
+}
+
+#[test]
+fn overrides_key_is_an_enum_whitelist() {
+    let schema = instance_schema();
+    assert!(schema.validate("overrides", &json!([])).is_ok());
+    assert!(schema
+        .validate("overrides", &json!(["maxMemory", "runningDirectory"]))
+        .is_ok());
+    assert!(
+        schema
+            .validate("overrides", &json!(["max_memory"]))
+            .is_err(),
+        "旧 snake_case 拼写不许过（拼错会静默失效）"
+    );
+    assert!(schema.validate("overrides", &json!([1])).is_err());
+    assert_eq!(OVERRIDE_KEYS, ["maxMemory", "javaType", "runningDirectory"]);
+}
+
+#[test]
+fn schema_versions_register_the_new_keys_without_migration() {
+    // 1.5.0 登记 M116 的窗口圆角策略键（1.4.0 = M91 外观下层三键，1.3.0 = D17「外观（高级）」，
+    // 1.2.0 = D23 的 JDK 落点/优先级键）。
+    assert_eq!(launcher_version(), SchemaVersion::new(1, 5, 0));
+    assert_eq!(instance_version(), SchemaVersion::new(1, 1, 0));
+    assert_eq!(launcher_schema().id(), SchemaId::LAUNCHER);
+    // major 仍是 1：迁移链（按 major 走）不需要新步骤，老文件缺键即默认值。
+    assert_eq!(launcher_version().major, 1);
+    assert_eq!(instance_version().major, 1);
+}
+
+#[test]
+fn old_launcher_file_without_new_keys_loads_with_defaults() {
+    let temp = std::env::temp_dir().join(format!(
+        "ull-setting-d20-{}-{}",
+        std::process::id(),
+        std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .map_or(0, |d| d.as_nanos())
+    ));
+    std::fs::create_dir_all(&temp).expect("临时目录");
+    let path = temp.join("launcher.json");
+    // 旧版本写的文件：只有 $schema 1.0.0 和一个老键，没有 instances.mode。
+    std::fs::write(
+        &path,
+        serde_json::to_vec_pretty(&json!({
+            "$schema": "https://schemas.unlucky-launcher.dev/ull/launcher/1.0.0",
+            "schemaVersion": 1,
+            "ui": { "scale": 1.25 }
+        }))
+        .expect("序列化"),
+    )
+    .expect("写文件");
+
+    let store = SettingStore::load(&path, launcher_schema());
+    assert!(store.access().can_read(), "1.0.0 文件必须可读");
+    assert!(store.problems().is_empty(), "{:?}", store.problems());
+    assert_eq!(
+        store.doc().effective_str("instances.mode"),
+        Some("isolated"),
+        "缺键取 D20 默认值"
+    );
+    assert_eq!(store.doc().effective_f64("ui.scale"), Some(1.25));
+    let _ = std::fs::remove_dir_all(&temp);
+}
+
+#[test]
+fn setting_lists_agree_with_the_game_enums() {
+    // schema 白名单与 game 侧枚举必须一一对应（两处字面量漂移就是静默不生效）。
+    let mut modes: Vec<&str> = [IsolationMode::Isolated, IsolationMode::Shared]
+        .iter()
+        .map(|mode| mode.as_str())
+        .collect();
+    modes.sort_unstable();
+    let mut declared = INSTANCE_MODES.to_vec();
+    declared.sort_unstable();
+    assert_eq!(modes, declared);
+
+    for value in ISOLATION_OVERRIDES
+        .iter()
+        .filter(|value| **value != "inherit")
+    {
+        assert!(
+            Isolation::parse(value).is_some(),
+            "{value} 在 game 侧解析不出来"
+        );
+        assert_eq!(Isolation::parse(value).map(Isolation::as_str), Some(*value));
+    }
+    for value in ISOLATION_RESOLVED {
+        assert!(Isolation::parse(value).is_some(), "{value}");
+    }
+}
+
+#[test]
+fn writer_output_loads_without_unknown_or_invalid_keys() {
+    // 回归 P2-1（review r1）：写入者（InstanceConfig + observe_mode）产出的键必须被 schema 全认。
+    // 之前 `lastModeChange.warned` 没登记，document 层会把真实文件标成 UnknownKey——
+    // 这正是「schema 只做写入者白名单视图」这条契约的裂缝。
+    let temp = TempDir::new("d20-writer-shape");
+    let game = GameLayout::new(temp.child("game"));
+    let mut config = InstanceConfig::new("11111111-2222-4333-8444-555555555555", "1.20.1");
+    config.isolation = Some(Isolation::Custom);
+    config.game_dir = Some(temp.child("elsewhere"));
+    config.overrides = vec![OverrideKey::MaxMemory];
+    observe_mode(
+        &mut config,
+        &game,
+        "2026-10-30T00:00:00Z",
+        Isolation::Custom,
+    )
+    .expect("观察");
+
+    let raw: serde_json::Value =
+        serde_json::from_str(&config.to_json_string().expect("序列化")).expect("合法 JSON");
+    // 写入者确实输出了 warned（P2-1 的前提）。
+    assert_eq!(raw["lastModeChange"]["warned"], json!(true));
+
+    let (document, problems) = SettingDocument::load(&instance_schema(), &raw);
+    let mut unknown: Vec = 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..90f2881
--- /dev/null
+++ b/crates/core/tests/setting/java_install_keys.rs
@@ -0,0 +1,119 @@
+//! D23 新增的两个设置键：`java.installRoot` / `java.vendorPriority`。
+//!
+//! 三件事要说清：
+//! 1. 两个键都登记在 launcher schema 里（`ull config get` 能看到、AI 白名单受策略约束）；
+//! 2. `java.vendorPriority` 的允许值集合与 `game::java::vendor::VENDOR_IDS` **同源**
+//!    （setting 层不依赖 game 层，靠这条契约测试固定，避免两处漂移）；
+//! 3. schema 版本推到 1.2.0 但 major 仍为 1 → 不需要迁移步骤（默认值不落盘）。
+
+use serde_json::json;
+use unlucky_core::game::java::vendor::VENDOR_IDS;
+use unlucky_core::setting::keys::{
+    launcher_schema, launcher_version, JAVA_INSTALL_ROOT_UNSET, JDK_VENDORS,
+};
+use unlucky_core::setting::schema::{SchemaId, SchemaRef, SchemaVersion};
+use unlucky_core::setting::store::SettingStore;
+
+#[test]
+fn both_d23_keys_are_registered_with_their_defaults() {
+    let schema = launcher_schema();
+    assert_eq!(
+        schema.default_value("java.installRoot"),
+        Some(&json!(JAVA_INSTALL_ROOT_UNSET))
+    );
+    assert_eq!(
+        schema.default_value("java.vendorPriority"),
+        Some(&json!([]))
+    );
+    // 空串/空数组都有明确语义：installRoot 空 = 按数据目录模式派生；
+    // vendorPriority 空 = 按地区默认序（国内 Temurin→Oracle→MS→Zulu）。
+    assert!(schema.spec("java.installRoot").is_some());
+    assert!(schema.spec("java.vendorPriority").is_some());
+}
+
+#[test]
+fn vendor_priority_whitelist_matches_the_vendor_module() {
+    assert_eq!(JDK_VENDORS, VENDOR_IDS, "两处必须同一份集合");
+    let schema = launcher_schema();
+    assert!(schema
+        .validate("java.vendorPriority", &json!(["oracle"]))
+        .is_ok());
+    assert!(schema
+        .validate("java.vendorPriority", &json!(["temurin", "zulu"]))
+        .is_ok());
+    assert!(schema
+        .validate("java.vendorPriority", &json!(["graalvm"]))
+        .is_err());
+    assert!(schema
+        .validate("java.vendorPriority", &json!([1, 2]))
+        .is_err());
+    assert!(schema
+        .validate("java.vendorPriority", &json!("microsoft"))
+        .is_err());
+}
+
+#[test]
+fn install_root_accepts_a_path_and_keeps_empty_as_unset() {
+    let schema = launcher_schema();
+    assert!(schema
+        .validate("java.installRoot", &json!("D:/jdk"))
+        .is_ok());
+    // 空串就是默认值，语义是「没设覆盖键」（不是错误）：所以类型是 text 而不是 path
+    // （Path 类型不接受空串，而这里需要一个合法的「未设置」值）。
+    assert!(schema.validate("java.installRoot", &json!("")).is_ok());
+    assert!(schema.validate("java.installRoot", &json!(5)).is_err());
+}
+
+#[test]
+fn schema_version_bumps_minor_only_so_no_migration_step_is_needed() {
+    assert_eq!(launcher_version(), SchemaVersion::new(1, 5, 0));
+    assert_eq!(
+        launcher_version().major,
+        1,
+        "major 不变 → 迁移链（按 major 走）不需要新步骤"
+    );
+}
+
+#[test]
+fn an_old_config_file_without_the_new_keys_still_loads() {
+    let dir = std::env::temp_dir().join(format!(
+        "ull-java-keys-{}-{}",
+        std::process::id(),
+        std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .map_or(0, |elapsed| elapsed.as_nanos())
+    ));
+    std::fs::create_dir_all(&dir).expect("建临时目录");
+    let path = dir.join("launcher.json");
+    // 1.1.0 的文件（真实 $schema 前缀）：没有 java.installRoot / java.vendorPriority，
+    // 且 core.data_mode 故意写非默认值 standard —— 证明值是「读出来的」不是「默认值撞上的」。
+    let old_url = SchemaRef::new(SchemaId::LAUNCHER, SchemaVersion::new(1, 1, 0)).url();
+    std::fs::write(
+        &path,
+        format!(r#"{{"$schema":"{old_url}","schemaVersion":1,"core":{{"data_mode":"standard"}}}}"#),
+    )
+    .expect("写旧配置");
+
+    let store = SettingStore::load(&path, launcher_schema());
+    assert_eq!(
+        store.doc().effective_str("core.data_mode"),
+        Some("standard"),
+        "旧文件的值必须照读（不是碰巧等于默认值）"
+    );
+    // 缺键取默认值，不报错、不写盘（「默认值不落盘」）。
+    assert_eq!(
+        store.doc().effective_str("java.installRoot"),
+        Some(JAVA_INSTALL_ROOT_UNSET)
+    );
+    assert_eq!(
+        store.effective("java.vendorPriority"),
+        Some(&json!([])),
+        "缺键 → 空数组 → 按地区默认序"
+    );
+    assert!(
+        store.problems().is_empty(),
+        "只缺新键不算问题：{:?}",
+        store.problems()
+    );
+    let _ = std::fs::remove_dir_all(&dir);
+}
diff --git a/crates/core/tests/setting/layout.rs b/crates/core/tests/setting/layout.rs
new file mode 100644
index 0000000..897099b
--- /dev/null
+++ b/crates/core/tests/setting/layout.rs
@@ -0,0 +1,128 @@
+//! 四分区布局、路径拼接、实例 id 白名单、可搬运路径字符串。
+
+use std::path::PathBuf;
+
+use unlucky_core::platform::layout::{
+    is_valid_instance_id, LauncherLayout, Partition, CONFIG_DIR, GAME_HOME_DIR, INSTANCES_DIR,
+    LAUNCHER_CONFIG_FILE, LAUNCHER_HOME_DIR, MIGRATION_RECEIPT_FILE, PROFILES_CONFIG_FILE,
+    REDIRECT_FILE,
+};
+
+use crate::common::TempDir;
+
+#[test]
+fn home_dir_names_match_design() {
+    assert_eq!(LAUNCHER_HOME_DIR, ".ULL");
+    assert_eq!(GAME_HOME_DIR, ".minecraft");
+    assert_eq!(CONFIG_DIR, "config");
+    assert_eq!(INSTANCES_DIR, "instances");
+    assert_eq!(LAUNCHER_CONFIG_FILE, "launcher.json");
+    assert_eq!(PROFILES_CONFIG_FILE, "profiles.json");
+    assert_eq!(REDIRECT_FILE, "redirect.json");
+    assert_eq!(MIGRATION_RECEIPT_FILE, "migration-receipt.json");
+}
+
+#[test]
+fn exposes_four_partitions() {
+    let layout = LauncherLayout::new("/home/u/.ULL");
+    assert_eq!(layout.home(), std::path::Path::new("/home/u/.ULL"));
+    assert_eq!(layout.config(), PathBuf::from("/home/u/.ULL/config"));
+    assert_eq!(layout.data(), PathBuf::from("/home/u/.ULL/data"));
+    assert_eq!(layout.cache(), PathBuf::from("/home/u/.ULL/cache"));
+    assert_eq!(layout.logs(), PathBuf::from("/home/u/.ULL/logs"));
+
+    assert_eq!(Partition::ALL.len(), 4);
+    assert_eq!(Partition::Config.dir_name(), "config");
+    assert!(Partition::Cache.is_disposable());
+    assert!(!Partition::Config.is_disposable());
+}
+
+#[test]
+fn builds_config_and_cache_paths() {
+    let layout = LauncherLayout::new("/home/u/.ULL");
+    assert_eq!(
+        layout.launcher_config(),
+        PathBuf::from("/home/u/.ULL/config/launcher.json")
+    );
+    assert_eq!(
+        layout.profiles_config(),
+        PathBuf::from("/home/u/.ULL/config/profiles.json")
+    );
+    assert_eq!(
+        layout.sha1_cache("ab"),
+        PathBuf::from("/home/u/.ULL/cache/sha1/ab")
+    );
+    assert_eq!(
+        layout.etag_cache(),
+        PathBuf::from("/home/u/.ULL/cache/etag.json")
+    );
+    assert_eq!(
+        layout.meta_cache(),
+        PathBuf::from("/home/u/.ULL/cache/meta")
+    );
+    assert_eq!(
+        layout.java_managed(),
+        PathBuf::from("/home/u/.ULL/data/java-managed")
+    );
+    assert_eq!(layout.auth_data(), PathBuf::from("/home/u/.ULL/data/auth"));
+    assert_eq!(
+        layout.agent_sessions(),
+        PathBuf::from("/home/u/.ULL/data/agent/sessions")
+    );
+    assert_eq!(
+        layout.redirect_path(),
+        PathBuf::from("/home/u/.ULL/redirect.json")
+    );
+    assert_eq!(
+        layout.migration_receipt(),
+        PathBuf::from("/home/u/.ULL/config/migration-receipt.json")
+    );
+}
+
+#[test]
+fn instance_config_rejects_path_traversal() {
+    let layout = LauncherLayout::new("/home/u/.ULL");
+    let id = "6f9619ff-8b86-d011-b42d-00c04fc964ff";
+    assert!(is_valid_instance_id(id));
+    assert_eq!(
+        layout.instance_config(id).expect("合法 id"),
+        PathBuf::from(format!("/home/u/.ULL/config/instances/{id}.json"))
+    );
+    assert!(layout.instance_config("../escape").is_err());
+    assert!(layout.instance_config("").is_err());
+    assert!(layout.instance_config("a/b").is_err());
+}
+
+#[test]
+fn ensure_creates_all_partitions() {
+    let temp = TempDir::new("layout");
+    let layout = LauncherLayout::new(temp.child(".ULL"));
+    layout.ensure().expect("建目录");
+    for partition in Partition::ALL {
+        assert!(
+            layout.partition(partition).is_dir(),
+            "{}",
+            partition.as_str()
+        );
+    }
+}
+
+#[test]
+fn portable_path_strings_keep_absolute_and_normalise_relative() {
+    use unlucky_core::platform::paths::{from_portable_string, to_portable_string};
+
+    assert_eq!(
+        to_portable_string(std::path::Path::new(".minecraft")),
+        ".minecraft"
+    );
+    assert_eq!(
+        to_portable_string(std::path::Path::new("versions\\1.20.1")),
+        "versions/1.20.1"
+    );
+    let absolute = std::env::temp_dir();
+    assert_eq!(to_portable_string(&absolute), absolute.to_string_lossy());
+    assert_eq!(
+        from_portable_string("versions/1.20.1"),
+        PathBuf::from("versions/1.20.1")
+    );
+}
diff --git a/crates/core/tests/setting/main.rs b/crates/core/tests/setting/main.rs
new file mode 100644
index 0000000..4f54b61
--- /dev/null
+++ b/crates/core/tests/setting/main.rs
@@ -0,0 +1,21 @@
+//! M12（core::setting + platform）集成测试入口。
+//!
+//! cargo 把 `tests//main.rs` 识别为独立的 test target（target 名 = `setting`），
+//! 因此本目录下每个子模块就是一个测试主题，避免单文件超过 400 行。
+
+mod appearance_keys;
+mod atomic_write;
+mod common;
+mod debounce;
+mod deprecated_keys;
+mod dir_migration;
+mod dirs;
+mod document;
+mod isolation_keys;
+mod java_install_keys;
+mod layout;
+mod migration_chain;
+mod redirect;
+mod schema_compat;
+mod spec_ai;
+mod store;
diff --git a/crates/core/tests/setting/migration_chain.rs b/crates/core/tests/setting/migration_chain.rs
new file mode 100644
index 0000000..3b03401
--- /dev/null
+++ b/crates/core/tests/setting/migration_chain.rs
@@ -0,0 +1,295 @@
+//! 迁移链：N→N+1 顺序校验、真实迁移跑通、收据闸门防重放、store 接线。
+
+use std::path::PathBuf;
+
+use serde_json::{json, Map, Value};
+use unlucky_core::platform::receipt::{
+    decide, fingerprint_bytes, fingerprint_file, read as read_receipt, MigrationReceipt,
+    ReceiptKind, ReplayDecision,
+};
+use unlucky_core::setting::catalog::SettingSchema;
+use unlucky_core::setting::migrate::{
+    MigrationChain, MigrationGate, MigrationReport, SettingMigration,
+};
+use unlucky_core::setting::schema::{
+    SchemaId, SchemaRef, SchemaVersion, SCHEMA_KEY, SCHEMA_VERSION_KEY,
+};
+use unlucky_core::setting::spec::{AiPolicy, SettingSpec};
+use unlucky_core::setting::store::SettingStore;
+
+use crate::common::TempDir;
+
+/// 1.0.0 → 2.0.0：`download.concurrency` 改名 `download.threads`。
+struct RenameThreads;
+
+impl SettingMigration for RenameThreads {
+    fn from(&self) -> SchemaVersion {
+        SchemaVersion::new(1, 0, 0)
+    }
+
+    fn to(&self) -> SchemaVersion {
+        SchemaVersion::new(2, 0, 0)
+    }
+
+    fn describe(&self) -> &'static str {
+        "download.concurrency → download.threads"
+    }
+
+    fn apply(&self, root: &mut Map) -> 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/design/Cargo.toml b/crates/design/Cargo.toml
new file mode 100644
index 0000000..6fcad9a
--- /dev/null
+++ b/crates/design/Cargo.toml
@@ -0,0 +1,19 @@
+[package]
+name = "unlucky-design"
+description = "Unlucky-Launcher 设计令牌：M3 Expressive 色彩/排版/形状/高程/动效/图标，纯数据 + 纯函数，零 UI 依赖"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+authors.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+publish.workspace = true
+
+# 零 UI 依赖是硬约束（D3 纪律 + M61）：本 crate 是渲染无关的**数据与纯函数**，
+# 不得出现 iced / slint / winit / wgpu / gtk / egui / tauri 等 UI 或渲染框架，
+# 也不引入任何第三方 crate（连 serde 都不加——序列化由消费方适配层自己做）。
+# 证据命令：cargo tree -p unlucky-design --edges normal
+[dependencies]
+
+[lints]
+workspace = true
diff --git a/crates/design/src/color/cam16.rs b/crates/design/src/color/cam16.rs
new file mode 100644
index 0000000..3a0650c
--- /dev/null
+++ b/crates/design/src/color/cam16.rs
@@ -0,0 +1,120 @@
+//! CAM16 正向换算：sRGB 色值 → CAM16 的 **hue**（色相角）与 **chroma**（彩度）。
+//!
+//! HCT = **H**ue / **C**hroma from CAM16 + **T**one from `L*`。这里只实现 M3 用到的方向
+//! （色值 → hue/chroma）；反向（hue/chroma/tone → 色值）在 [`super::hct_solver`] 里按官方
+//! 求解器内联实现——两边如果各写一份，数值会对不上。
+//!
+//! 照搬 `java/hct/Cam16.java`（Apache-2.0，见 `NOTICE`），逐行对应，包括 `Math.signum` 的
+//! 「零返回 0」这种 Java 语义差别（见 [`space::signum`]）。
+
+use super::space::{self, signum};
+use super::viewing_conditions::{default_conditions, ViewingConditions};
+use super::Color;
+
+/// XYZ → CAM16 的「锥体响应」矩阵。
+pub(crate) const XYZ_TO_CAM16_RGB: [[f64; 3]; 3] = [
+    [0.401_288, 0.650_173, -0.051_461],
+    [-0.250_268, 1.204_414, 0.045_854],
+    [-0.002_079, 0.048_952, 0.953_127],
+];
+
+/// CAM16 里 M3 真正用到的两个坐标（`J` 明度不参与 HCT，HCT 的 tone 走 `L*`）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub(crate) struct Cam16 {
+    /// 色相角（度，`0..360`）。
+    pub(crate) hue: f64,
+    /// 彩度（无上限；sRGB 立方体内最大值约 130）。
+    pub(crate) chroma: f64,
+}
+
+impl Cam16 {
+    /// 从色值取 CAM16 色相/彩度（默认 sRGB 观察条件）。
+    pub(crate) fn from_color(color: Color) -> Self {
+        Self::from_xyz(space::xyz_from_color(color), default_conditions())
+    }
+
+    /// 从 XYZ 取 CAM16 色相/彩度。
+    pub(crate) fn from_xyz(xyz: [f64; 3], vc: &ViewingConditions) -> Self {
+        let [r_t, g_t, b_t] = space::matrix_multiply(xyz, XYZ_TO_CAM16_RGB);
+
+        // 折扣光源（色适应）
+        let r_d = vc.rgb_d[0] * r_t;
+        let g_d = vc.rgb_d[1] * g_t;
+        let b_d = vc.rgb_d[2] * b_t;
+
+        // 非线性压缩（视觉响应）
+        let r_af = (vc.fl * r_d.abs() / 100.0).powf(0.42);
+        let g_af = (vc.fl * g_d.abs() / 100.0).powf(0.42);
+        let b_af = (vc.fl * b_d.abs() / 100.0).powf(0.42);
+        let r_a = signum(r_d) * 400.0 * r_af / (r_af + 27.13);
+        let g_a = signum(g_d) * 400.0 * g_af / (g_af + 27.13);
+        let b_a = signum(b_d) * 400.0 * b_af / (b_af + 27.13);
+
+        // 红绿 / 黄蓝对立通道
+        let a = (11.0 * r_a - 12.0 * g_a + b_a) / 11.0;
+        let b = (r_a + g_a - 2.0 * b_a) / 9.0;
+
+        // 辅助量
+        let u = (20.0 * r_a + 20.0 * g_a + 21.0 * b_a) / 20.0;
+        let p2 = (40.0 * r_a + 20.0 * g_a + b_a) / 20.0;
+
+        let hue = space::sanitize_degrees(b.atan2(a).to_degrees());
+        let ac = p2 * vc.nbb;
+        let j = 100.0 * (ac / vc.aw).powf(vc.c * vc.z);
+
+        // 彩度：eHue 的 20.14° 断点是官方原样（把橙红段挪到 0 附近做插值）
+        let hue_prime = if hue < 20.14 { hue + 360.0 } else { hue };
+        let e_hue = 0.25 * ((hue_prime.to_radians() + 2.0).cos() + 3.8);
+        let p1 = 50_000.0 / 13.0 * e_hue * vc.nc * vc.ncb;
+        let t = p1 * a.hypot(b) / (u + 0.305);
+        let alpha = (1.64 - 0.29_f64.powf(vc.n)).powf(0.73) * t.powf(0.9);
+        let chroma = alpha * (j / 100.0).sqrt();
+
+        Self { hue, chroma }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn primaries_have_the_official_hue_angles() {
+        // 官方 material-color-utilities 对纯红/绿/蓝解出的 CAM16 色相（Java 实测）。
+        let cases = [
+            (Color::rgb(255, 0, 0), 27.408_225, 113.357_887),
+            (Color::rgb(0, 255, 0), 142.139_894, 108.410_061),
+            (Color::rgb(0, 0, 255), 282.788_18, 87.230_694),
+        ];
+        for (color, hue, chroma) in cases {
+            let cam = Cam16::from_color(color);
+            assert!(
+                (cam.hue - hue).abs() < 1.0e-4,
+                "{} 的 hue 是 {}，官方 {hue}",
+                color.to_hex(),
+                cam.hue
+            );
+            assert!(
+                (cam.chroma - chroma).abs() < 1.0e-4,
+                "{} 的 chroma 是 {}，官方 {chroma}",
+                color.to_hex(),
+                cam.chroma
+            );
+        }
+    }
+
+    #[test]
+    fn gray_has_near_zero_chroma() {
+        for value in [16_u8, 64, 128, 200] {
+            let cam = Cam16::from_color(Color::rgb(value, value, value));
+            assert!(cam.chroma < 2.5, "灰 {value} 的彩度 {}", cam.chroma);
+        }
+    }
+
+    #[test]
+    fn black_is_finite() {
+        let cam = Cam16::from_color(Color::BLACK);
+        assert!(cam.hue.is_finite() && cam.chroma.is_finite());
+        assert_eq!(cam.chroma, 0.0);
+    }
+}
diff --git a/crates/design/src/color/critical_planes.rs b/crates/design/src/color/critical_planes.rs
new file mode 100644
index 0000000..46a72aa
--- /dev/null
+++ b/crates/design/src/color/critical_planes.rs
@@ -0,0 +1,77 @@
+//! 官方 `HctSolver.CRITICAL_PLANES` 表（255 项，**原样搬运**）。
+//!
+//! 这不是可以推导的常数集：它是 HCT 求解器在 sRGB 立方体上按 `Y` 找边界、再做色相二分时的
+//! 「关键平面」索引表，由 Google 的脚本一次性生成后冻结。逐值复制是唯一忠实的做法——
+//! 表错了，极端 tone（深色/浅色端）的颜色会偏一两个通道。
+//!
+//! 来源：`material-color-utilities/java/hct/HctSolver.java`（Apache-2.0），见仓库根 `NOTICE`。
+
+/// sRGB 立方体上按 `Y` 递增排序的关键平面（线性 RGB 0..=100 标度）。
+///
+/// 手写密度由 `#[rustfmt::skip]` 保住：这张表是数据，不是代码，一列一个数会撑到 266 行。
+#[rustfmt::skip]
+pub(crate) const CRITICAL_PLANES: [f64; 255] = [
+    0.015176349177441876, 0.045529047532325624, 0.07588174588720938, 0.10623444424209313,
+    0.13658714259697685, 0.16693984095186062, 0.19729253930674434, 0.2276452376616281,
+    0.2579979360165119, 0.28835063437139563, 0.3188300904430532, 0.350925934958123,
+    0.3848314933096426, 0.42057480301049466, 0.458183274052838, 0.4976837250274023,
+    0.5391024159806381, 0.5824650784040898, 0.6277969426914107, 0.6751227633498623,
+    0.7244668422128921, 0.775853049866786, 0.829304845476233, 0.8848452951698498,
+    0.942497089126609, 1.0022825574869039, 1.0642236851973577, 1.1283421258858297,
+    1.1946592148522128, 1.2631959812511864, 1.3339731595349034, 1.407011200216447,
+    1.4823302800086415, 1.5599503113873272, 1.6398909516233677, 1.7221716113234105,
+    1.8068114625156377, 1.8938294463134073, 1.9832442801866852, 2.075074464868551,
+    2.1693382909216234, 2.2660538449872063, 2.36523901573795, 2.4669114995532007,
+    2.5710888059345764, 2.6777882626779785, 2.7870270208169257, 2.898822059350997,
+    3.0131901897720907, 3.1301480604002863, 3.2497121605402226, 3.3718988244681087,
+    3.4967242352587946, 3.624204428461639, 3.754355295633311, 3.887192587735158,
+    4.022731918402185, 4.160988767090289, 4.301978482107941, 4.445716283538092,
+    4.592217266055746, 4.741496401646282, 4.893568542229298, 5.048448422192488,
+    5.20615066083972, 5.3666897647573375, 5.5300801301023865, 5.696336044816294,
+    5.865471690767354, 6.037501145825082, 6.212438385869475, 6.390297286737924,
+    6.571091626112461, 6.7548350853498045, 6.941541251256611, 7.131223617812143,
+    7.323895587840543, 7.5195704746346665, 7.7182615035334345, 7.919981813454504,
+    8.124744458384042, 8.332562408825165, 8.543448553206703, 8.757415699253682,
+    8.974476575321063, 9.194643831691977, 9.417930041841839, 9.644347703669503,
+    9.873909240696694, 10.106627003236781, 10.342513269534024, 10.58158024687427,
+    10.8238400726681, 11.069304815507364, 11.317986476196008, 11.569896988756009,
+    11.825048221409341, 12.083451977536606, 12.345119996613247, 12.610063955123938,
+    12.878295467455942, 13.149826086772048, 13.42466730586372, 13.702830557985108,
+    13.984327217668513, 14.269168601521828, 14.55736596900856, 14.848930523210871,
+    15.143873411576273, 15.44220572664832, 15.743938506781891, 16.04908273684337,
+    16.35764934889634, 16.66964922287304, 16.985093187232053, 17.30399201960269,
+    17.62635644741625, 17.95219714852476, 18.281524751807332, 18.614349837764564,
+    18.95068293910138, 19.290534541298456, 19.633915083172692, 19.98083495742689,
+    20.331304511189067, 20.685334046541502, 21.042933821039977, 21.404114048223256,
+    21.76888489811322, 22.137256497705877, 22.50923893145328, 22.884842241736916,
+    23.264076429332462, 23.6469514538663, 24.033477234264016, 24.42366364919083,
+    24.817520537484558, 25.21505769858089, 25.61628489293138, 26.021211842414342,
+    26.429848230738664, 26.842203703840827, 27.258287870275353, 27.678110301598522,
+    28.10168053274597, 28.529008062403893, 28.96010235337422, 29.39497283293396,
+    29.83362889318845, 30.276079891419332, 30.722335150426627, 31.172403958865512,
+    31.62629557157785, 32.08401920991837, 32.54558406207592, 33.010999283389665,
+    33.4802739966603, 33.953417292456834, 34.430438229418264, 34.911345834551085,
+    35.39614910352207, 35.88485700094671, 36.37747846067349, 36.87402238606382,
+    37.37449765026789, 37.87891309649659, 38.38727753828926, 38.89959975977785,
+    39.41588851594697, 39.93615253289054, 40.460400508064545, 40.98864111053629,
+    41.520882981230194, 42.05713473317016, 42.597404951718396, 43.141702194811224,
+    43.6900349931913, 44.24241185063697, 44.798841244188324, 45.35933162437017,
+    45.92389141541209, 46.49252901546552, 47.065252796817916, 47.64207110610409,
+    48.22299226451468, 48.808024568002054, 49.3971762874833, 49.9904556690408,
+    50.587870934119984, 51.189430279724725, 51.79514187861014, 52.40501387947288,
+    53.0190544071392, 53.637271562750364, 54.259673423945976, 54.88626804504493,
+    55.517063457223934, 56.15206766869424, 56.79128866487574, 57.43473440856916,
+    58.08241284012621, 58.734331877617365, 59.39049941699807, 60.05092333227251,
+    60.715611475655585, 61.38457167773311, 62.057811747619894, 62.7353394731159,
+    63.417162620860914, 64.10328893648692, 64.79372614476921, 65.48848194977529,
+    66.18756403501224, 66.89098006357258, 67.59873767827808, 68.31084450182222,
+    69.02730813691093, 69.74813616640164, 70.47333615344107, 71.20291564160104,
+    71.93688215501312, 72.67524319850172, 73.41800625771542, 74.16517879925733,
+    74.9167682708136, 75.67278210128072, 76.43322770089146, 77.1981124613393, 77.96744375590167,
+    78.74122893956174, 79.51947534912904, 80.30219030335869, 81.08938110306934,
+    81.88105503125999, 82.67721935322541, 83.4778813166706, 84.28304815182372,
+    85.09272707154808, 85.90692527145302, 86.72564993000343, 87.54890820862819,
+    88.3767072518277, 89.2090541872801, 90.04595612594655, 90.88742016217518, 91.73345337380438,
+    92.58406282226491, 93.43925555268066, 94.29903859396902, 95.16341895893969,
+    96.03240364439274, 96.9059996312159, 97.78421388448044, 98.6670533535366, 99.55452497210776,
+];
diff --git a/crates/design/src/color/hct.rs b/crates/design/src/color/hct.rs
new file mode 100644
index 0000000..228446d
--- /dev/null
+++ b/crates/design/src/color/hct.rs
@@ -0,0 +1,160 @@
+//! **HCT** 色彩空间：色相/彩度取自 CAM16，亮度取自 CIELAB 的 `L*`（即 M3 的 tone）。
+//!
+//! 为什么不是 OKLab/HSL：`L*` 与人眼感知线性的**对比度**直接挂钩（`Y` 是它的单调函数），
+//! 所以「tone 差 40 ⇒ 对比度 ≥ 3:1」「tone 差 50 ⇒ ≥ 4.5:1」这类性质在 HCT 里是恒等式，
+//! 换任何种子色都成立。CAM16 的色相/彩度则保证「同一条调色板只有一种色相」在感知上也是真的。
+//!
+//! 语义与官方 `java/hct/Hct.java` 一致：`Hct` 的真身是那个 **8 bit 色值**，`hue/chroma/tone`
+//! 是它的测量值。所以 [`Hct::from_components`] 解出来的 `tone` 可能比请求值差一点点
+//! （例如请求 tone 40、实测 40.08），官方也是这样——请求值只是求解目标。
+//!
+//! 来源：`material-color-utilities`（Apache-2.0），见仓库根 `NOTICE`。
+
+use super::space;
+use super::{cam16::Cam16, hct_solver, Color};
+
+/// 一个色值的 HCT 坐标。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Hct {
+    /// CAM16 色相角（度，`0..360`）。
+    pub hue: f64,
+    /// CAM16 彩度（无上限；sRGB 立方体内约 0..=130）。
+    pub chroma: f64,
+    /// CIELAB `L*`（0 = 黑 / 100 = 白）——M3 里叫 **tone**。
+    pub tone: f64,
+    /// 这个坐标对应的 8 bit 色值（HCT 的真身）。
+    color: Color,
+}
+
+impl Hct {
+    /// 量一个色值的 HCT 坐标。
+    pub fn from_color(color: Color) -> Self {
+        let cam = Cam16::from_color(color);
+        Self {
+            hue: cam.hue,
+            chroma: cam.chroma,
+            tone: space::lstar_from_color(color),
+            color,
+        }
+    }
+
+    /// 解 HCT 方程：给定色相/彩度/tone，求最接近的 sRGB 色值。
+    ///
+    /// 彩度装不下时**只压彩度**（色相与 tone 保住），这就是 M3 的 gamut 映射；
+    /// 返回值的 `tone` 是实测值，可能与 `tone` 参数相差千分之几。
+    pub fn from_components(hue: f64, chroma: f64, tone: f64) -> Self {
+        Self::from_color(hct_solver::solve_to_color(hue, chroma, tone))
+    }
+
+    /// 该坐标对应的色值。
+    pub fn to_color(self) -> Color {
+        self.color
+    }
+
+    /// 色相是否落在「黄」段（官方 `TonalPalette` 的 tone 99 特例用它）。
+    pub fn is_yellow(hue: f64) -> bool {
+        (105.0..125.0).contains(&hue)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// 官方 Java 实测的种子色 HCT 坐标（`hct.Count` 打印，APCA/CAM16 D65 默认条件）。
+    const SEED_HCT: [(&str, f64, f64, f64); 6] = [
+        ("#6750A4", 298.980_997, 47.856_526, 40.083_244),
+        ("#FF0000", 27.408_225, 113.357_887, 53.232_882),
+        ("#00FF00", 142.139_894, 108.410_061, 87.737_033),
+        ("#0000FF", 282.788_18, 87.230_694, 32.302_587),
+        ("#6E7C8A", 245.036_867, 14.675_86, 51.342_101),
+        ("#D000FF", 324.929_26, 99.544_477, 52.542_037),
+    ];
+
+    #[test]
+    fn seed_coordinates_match_official() {
+        for (hex, hue, chroma, tone) in SEED_HCT {
+            let hct = Hct::from_color(Color::from_hex(hex).expect("合法 hex"));
+            assert!((hct.hue - hue).abs() < 1.0e-4, "{hex} hue {}", hct.hue);
+            assert!(
+                (hct.chroma - chroma).abs() < 1.0e-4,
+                "{hex} chroma {}",
+                hct.chroma
+            );
+            assert!((hct.tone - tone).abs() < 1.0e-4, "{hex} tone {}", hct.tone);
+        }
+    }
+
+    #[test]
+    fn solver_reproduces_official_hexes() {
+        // 官方 Java 实测（`hct.Probe`）：同一组 (h, c, t) 必须解出同一个 hex。
+        let cases = [
+            (95.0, 36.0, 40.0, "#705D0D"),
+            (298.98, 36.0, 90.0, "#E9DDFF"),
+            (25.0, 84.0, 80.0, "#FFB4AB"),
+            (245.0, 16.0, 80.0, "#B8C8D9"),
+            (245.0, 42.0, 30.0, "#004B72"),
+            (10.0, 120.0, 5.0, "#2C000A"),
+            (245.0, 4.0, 30.0, "#45474A"),
+        ];
+        for (hue, chroma, tone, hex) in cases {
+            assert_eq!(
+                hct_solver::solve_to_color(hue, chroma, tone).to_hex(),
+                hex,
+                "HCT({hue}, {chroma}, {tone}) 与官方不一致"
+            );
+        }
+    }
+
+    #[test]
+    fn solver_keeps_hue_and_tone_when_chroma_is_available() {
+        for (hue, chroma, tone) in [
+            (95.0, 36.0, 40.0),
+            (298.98, 36.0, 90.0),
+            (245.0, 42.0, 30.0),
+            (25.0, 84.0, 80.0),
+            (245.0, 16.0, 80.0),
+        ] {
+            let solved = Hct::from_components(hue, chroma, tone);
+            assert_eq!(
+                solved.to_color(),
+                hct_solver::solve_to_color(hue, chroma, tone)
+            );
+            assert!(
+                (solved.tone - tone).abs() < 1.0,
+                "tone {} vs {tone}",
+                solved.tone
+            );
+            let delta = (solved.hue - hue)
+                .abs()
+                .min(360.0 - (solved.hue - hue).abs());
+            assert!(delta < 1.0, "色相 {} vs {hue}", solved.hue);
+            assert!(
+                solved.chroma <= chroma + 1.0,
+                "彩度反被拉高：{}",
+                solved.chroma
+            );
+        }
+    }
+
+    #[test]
+    fn low_chroma_hue_is_ill_conditioned_even_officially() {
+        // 彩度 8 在 tone 30 上，8 bit 量化会让 CAM16 色相跳 6°——官方同样如此
+        // （Java 实测 HCT(245,8,30) → #42474E / hue 251.5965）。这条钉的是「别去修它」。
+        let solved = Hct::from_components(245.0, 8.0, 30.0);
+        assert_eq!(solved.to_color().to_hex(), "#42474E");
+        assert!(
+            (solved.hue - 251.596_498).abs() < 1.0e-4,
+            "hue {}",
+            solved.hue
+        );
+    }
+
+    #[test]
+    fn yellow_band_matches_official_definition() {
+        assert!(Hct::is_yellow(105.0));
+        assert!(Hct::is_yellow(124.9));
+        assert!(!Hct::is_yellow(125.0));
+        assert!(!Hct::is_yellow(104.9));
+    }
+}
diff --git a/crates/design/src/color/hct_solver.rs b/crates/design/src/color/hct_solver.rs
new file mode 100644
index 0000000..02f11e2
--- /dev/null
+++ b/crates/design/src/color/hct_solver.rs
@@ -0,0 +1,311 @@
+//! HCT 求解器：给定 `(hue, chroma, tone)` 求 sRGB 色值——**这就是 M3 的 gamut 映射**。
+//!
+//! M3 不做「越界就硬裁」：它先假设色域足够，用 Newton 迭代解出线性 RGB；只有当解落进 sRGB
+//! 立方体之外时，才退到「在色调平面（`Y` 恒定）上沿色相二分」，把彩度压到该色相能取到的最大值，
+//! **色相与 tone 都保持不变**。所以深色/浅色端的颜色是「变灰」而不是「变色」。
+//!
+//! 照搬 `java/hct/HctSolver.java`（Apache-2.0，见 `NOTICE`）：两段（Newton + 二分）、
+//! 迭代次数、`100.01` 这类边界容差都一致。关键平面表见 [`super::critical_planes`]。
+
+use super::space::{self, signum};
+use super::viewing_conditions::default_conditions;
+use super::Color;
+
+/// 线性 RGB → 「折扣光源」标度的矩阵（求解器内联版，与 [`super::cam16`] 等价但省一次除法）。
+const SCALED_DISCOUNT_FROM_LINRGB: [[f64; 3]; 3] = [
+    [
+        0.001_200_833_568_784_504,
+        0.002_389_694_492_170_889,
+        0.000_279_574_288_586_112_4,
+    ],
+    [
+        0.000_589_108_665_137_599_9,
+        0.002_978_550_257_343_875_8,
+        0.000_327_066_610_400_839_8,
+    ],
+    [
+        0.000_101_466_924_916_405_72,
+        0.000_536_421_435_918_669_4,
+        0.003_297_940_177_071_207_6,
+    ],
+];
+
+/// 「折扣光源」标度 → 线性 RGB（[`SCALED_DISCOUNT_FROM_LINRGB`] 的逆）。
+const LINRGB_FROM_SCALED_DISCOUNT: [[f64; 3]; 3] = [
+    [
+        1_373.219_870_959_423_1,
+        -1_100.425_119_075_482_1,
+        -7.278_681_089_101_213,
+    ],
+    [
+        -271.815_969_077_903,
+        559.658_046_594_073_3,
+        -32.460_474_827_911_94,
+    ],
+    [
+        1.962_289_959_966_566_6,
+        -57.173_814_538_844_006,
+        308.723_319_781_238_5,
+    ],
+];
+
+/// 线性 RGB 的 `Y` 权重（Rec.709 亮度系数）。
+const Y_FROM_LINRGB: [f64; 3] = [0.2126, 0.7152, 0.0722];
+
+/// `(hue, chroma, tone)` → 色值。彩度取不到时压到该色相/色调下的最大值（色相与 tone 不变）。
+pub(crate) fn solve_to_color(hue_degrees: f64, chroma: f64, lstar: f64) -> Color {
+    // 端点与极低彩度直接走灰：官方用同一断点，保证 tone 0/100 是纯黑/纯白。
+    if chroma < 0.0001 || lstar < 0.0001 || lstar > 99.9999 {
+        return space::color_from_lstar(lstar);
+    }
+    let hue_radians = space::sanitize_degrees(hue_degrees).to_radians();
+    let y = space::y_from_lstar(lstar);
+    if let Some(exact) = find_result_by_j(hue_radians, chroma, y) {
+        return exact;
+    }
+    space::color_from_linrgb(bisect_to_limit(y, hue_radians))
+}
+
+/// 牛顿迭代直接解（色域内能解出来时，这条路径是精确解）。
+fn find_result_by_j(hue_radians: f64, chroma: f64, y: f64) -> Option {
+    let vc = default_conditions();
+    let mut j = y.sqrt() * 11.0;
+    let t_inner_coeff = 1.0 / (1.64 - 0.29_f64.powf(vc.n)).powf(0.73);
+    let e_hue = 0.25 * ((hue_radians + 2.0).cos() + 3.8);
+    let p1 = e_hue * (50_000.0 / 13.0) * vc.nc * vc.ncb;
+    let h_sin = hue_radians.sin();
+    let h_cos = hue_radians.cos();
+    for round in 0..5 {
+        let j_normalized = j / 100.0;
+        let alpha = if chroma == 0.0 || j == 0.0 {
+            0.0
+        } else {
+            chroma / j_normalized.sqrt()
+        };
+        let t = (alpha * t_inner_coeff).powf(1.0 / 0.9);
+        let ac = vc.aw * j_normalized.powf(1.0 / vc.c / vc.z);
+        let p2 = ac / vc.nbb;
+        let gamma = 23.0 * (p2 + 0.305) * t / (23.0 * p1 + 11.0 * t * h_cos + 108.0 * t * h_sin);
+        let a = gamma * h_cos;
+        let b = gamma * h_sin;
+        let r_a = (460.0 * p2 + 451.0 * a + 288.0 * b) / 1403.0;
+        let g_a = (460.0 * p2 - 891.0 * a - 261.0 * b) / 1403.0;
+        let b_a = (460.0 * p2 - 220.0 * a - 6300.0 * b) / 1403.0;
+        let linrgb = space::matrix_multiply(
+            [
+                inverse_chromatic_adaptation(r_a),
+                inverse_chromatic_adaptation(g_a),
+                inverse_chromatic_adaptation(b_a),
+            ],
+            LINRGB_FROM_SCALED_DISCOUNT,
+        );
+        if linrgb[0] < 0.0 || linrgb[1] < 0.0 || linrgb[2] < 0.0 {
+            return None;
+        }
+        let f_nj = Y_FROM_LINRGB[0] * linrgb[0]
+            + Y_FROM_LINRGB[1] * linrgb[1]
+            + Y_FROM_LINRGB[2] * linrgb[2];
+        if f_nj <= 0.0 {
+            return None;
+        }
+        if round == 4 || (f_nj - y).abs() < 0.002 {
+            if linrgb[0] > 100.01 || linrgb[1] > 100.01 || linrgb[2] > 100.01 {
+                return None;
+            }
+            return Some(space::color_from_linrgb(linrgb));
+        }
+        // Newton：用 2 * fn(j) / j 近似 fn'(j)
+        j -= (f_nj - y) * j / (2.0 * f_nj);
+    }
+    None
+}
+
+/// 色域外时的兜底：在 `Y` 恒定的平面上按色相二分，取边界上的颜色。
+fn bisect_to_limit(y: f64, target_hue: f64) -> [f64; 3] {
+    let (mut left, mut right) = bisect_to_segment(y, target_hue);
+    let mut left_hue = hue_of(left);
+    for axis in 0..3 {
+        if left[axis] == right[axis] {
+            continue;
+        }
+        let (mut l_plane, mut r_plane) = if left[axis] < right[axis] {
+            (
+                critical_plane_below(space::true_delinearized(left[axis])),
+                critical_plane_above(space::true_delinearized(right[axis])),
+            )
+        } else {
+            (
+                critical_plane_above(space::true_delinearized(left[axis])),
+                critical_plane_below(space::true_delinearized(right[axis])),
+            )
+        };
+        for _ in 0..8 {
+            if (r_plane - l_plane).abs() <= 1 {
+                break;
+            }
+            let m_plane = ((f64::from(l_plane) + f64::from(r_plane)) / 2.0).floor() as i32;
+            let coordinate = super::critical_planes::CRITICAL_PLANES[m_plane as usize];
+            let mid = set_coordinate(left, coordinate, right, axis);
+            let mid_hue = hue_of(mid);
+            if are_in_cyclic_order(left_hue, target_hue, mid_hue) {
+                right = mid;
+                r_plane = m_plane;
+            } else {
+                left = mid;
+                left_hue = mid_hue;
+                l_plane = m_plane;
+            }
+        }
+    }
+    midpoint(left, right)
+}
+
+/// 找到包含目标色相的边界线段（sRGB 立方体与 `Y` 平面的交是多边形）。
+fn bisect_to_segment(y: f64, target_hue: f64) -> ([f64; 3], [f64; 3]) {
+    let mut left = [-1.0_f64; 3];
+    let mut right = left;
+    let mut left_hue = 0.0;
+    let mut initialized = false;
+    let mut uncut = true;
+    for n in 0..12 {
+        let Some(mid) = nth_vertex(y, n) else {
+            continue;
+        };
+        let mid_hue = hue_of(mid);
+        if !initialized {
+            initialized = true;
+            left = mid;
+            right = mid;
+            left_hue = mid_hue;
+            continue;
+        }
+        if uncut || are_in_cyclic_order(left_hue, mid_hue, hue_of(right)) {
+            uncut = false;
+            if are_in_cyclic_order(left_hue, target_hue, mid_hue) {
+                right = mid;
+            } else {
+                left = mid;
+                left_hue = mid_hue;
+            }
+        }
+    }
+    (left, right)
+}
+
+/// `Y` 平面与立方体的第 `n` 个顶点（不在立方体内返回 `None`）。
+fn nth_vertex(y: f64, n: usize) -> Option<[f64; 3]> {
+    let [k_r, k_g, k_b] = Y_FROM_LINRGB;
+    let coord_a = if n % 4 <= 1 { 0.0 } else { 100.0 };
+    let coord_b = if n.is_multiple_of(2) { 0.0 } else { 100.0 };
+    let vertex = if n < 4 {
+        let (g, b) = (coord_a, coord_b);
+        [((y - g * k_g - b * k_b) / k_r), g, b]
+    } else if n < 8 {
+        let (b, r) = (coord_a, coord_b);
+        [r, ((y - r * k_r - b * k_b) / k_g), b]
+    } else {
+        let (r, g) = (coord_a, coord_b);
+        [r, g, ((y - r * k_r - g * k_g) / k_b)]
+    };
+    if vertex.iter().all(|c| (0.0..=100.0).contains(c)) {
+        Some(vertex)
+    } else {
+        None
+    }
+}
+
+/// 线性 RGB 的色相（弧度，未归一）。
+fn hue_of(linrgb: [f64; 3]) -> f64 {
+    let scaled = space::matrix_multiply(linrgb, SCALED_DISCOUNT_FROM_LINRGB);
+    let r_a = chromatic_adaptation(scaled[0]);
+    let g_a = chromatic_adaptation(scaled[1]);
+    let b_a = chromatic_adaptation(scaled[2]);
+    let a = (11.0 * r_a - 12.0 * g_a + b_a) / 11.0;
+    let b = (r_a + g_a - 2.0 * b_a) / 9.0;
+    b.atan2(a)
+}
+
+/// 角度上 `b` 是否落在 `a → c` 的前进区间内。
+fn are_in_cyclic_order(a: f64, b: f64, c: f64) -> bool {
+    space::sanitize_radians(b - a) < space::sanitize_radians(c - a)
+}
+
+/// 把线段 `source → target` 在 `axis` 上截到 `coordinate`。
+fn set_coordinate(source: [f64; 3], coordinate: f64, target: [f64; 3], axis: usize) -> [f64; 3] {
+    let t = (coordinate - source[axis]) / (target[axis] - source[axis]);
+    [
+        source[0] + (target[0] - source[0]) * t,
+        source[1] + (target[1] - source[1]) * t,
+        source[2] + (target[2] - source[2]) * t,
+    ]
+}
+
+/// 线段中点。
+fn midpoint(a: [f64; 3], b: [f64; 3]) -> [f64; 3] {
+    [
+        (a[0] + b[0]) / 2.0,
+        (a[1] + b[1]) / 2.0,
+        (a[2] + b[2]) / 2.0,
+    ]
+}
+
+/// 非线性压缩的正向（与 CAM16 里那段同公式）。
+fn chromatic_adaptation(component: f64) -> f64 {
+    let af = component.abs().powf(0.42);
+    signum(component) * 400.0 * af / (af + 27.13)
+}
+
+/// 非线性压缩的逆。
+fn inverse_chromatic_adaptation(adapted: f64) -> f64 {
+    let adapted_abs = adapted.abs();
+    let base = (27.13 * adapted_abs / (400.0 - adapted_abs)).max(0.0);
+    signum(adapted) * base.powf(1.0 / 0.42)
+}
+
+/// 关键平面索引：向下取（官方 `(int) Math.floor(x - 0.5)`）。
+fn critical_plane_below(x: f64) -> i32 {
+    (x - 0.5).floor() as i32
+}
+
+/// 关键平面索引：向上取（官方 `(int) Math.ceil(x - 0.5)`）。
+fn critical_plane_above(x: f64) -> i32 {
+    (x - 0.5).ceil() as i32
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn in_gamut_requests_are_met_exactly() {
+        // 官方 Java 实测：HCT(95, 36, 40) → #705D0D。
+        assert_eq!(solve_to_color(95.0, 36.0, 40.0).to_hex(), "#705D0D");
+        assert_eq!(solve_to_color(25.0, 84.0, 40.0).to_hex(), "#BA1A1A");
+        assert_eq!(solve_to_color(95.0, 36.0, 90.0).to_hex(), "#FCE186");
+    }
+
+    #[test]
+    fn out_of_gamut_requests_keep_hue_and_tone() {
+        // 请求 chroma 200（sRGB 装不下）：官方只在彩度上退让，色相与 tone 必须保住。
+        let color = solve_to_color(200.0, 200.0, 70.0);
+        assert_eq!(color.to_hex(), "#00BEC3");
+        let hct = super::super::Hct::from_color(color);
+        assert!((hct.tone - 70.0).abs() < 1.0, "tone 掉了：{}", hct.tone);
+        assert!(
+            (hct.hue - 200.0).abs() < 1.0,
+            "色相偏了：{}（应 ≈200）",
+            hct.hue
+        );
+        assert!(hct.chroma < 200.0);
+    }
+
+    #[test]
+    fn neutral_requests_return_exact_grays() {
+        for lstar in [0.0_f64, 4.0, 10.0, 50.0, 87.0, 98.0, 100.0] {
+            let color = solve_to_color(120.0, 0.0, lstar);
+            assert!(color.r == color.g && color.g == color.b, "{:?}", color);
+        }
+        assert_eq!(solve_to_color(0.0, 0.0, 0.0), Color::BLACK);
+        assert_eq!(solve_to_color(0.0, 0.0, 100.0), Color::WHITE);
+    }
+}
diff --git a/crates/design/src/color/mod.rs b/crates/design/src/color/mod.rs
new file mode 100644
index 0000000..ec027ef
--- /dev/null
+++ b/crates/design/src/color/mod.rs
@@ -0,0 +1,335 @@
+//! # 色彩令牌（M3 color roles）
+//!
+//! 49 个 M3 语义色角色 × light/dark 两套，全部由**一个种子色**派生（[`Palettes`]），
+//! 再按官方 tone 映射表解析成具体色值（[`Scheme`]）。
+//!
+//! ```no_run
+//! use unlucky_design::color::{Color, Role, Scheme, SchemeFlavor};
+//!
+//! let light = Scheme::baseline(SchemeFlavor::Light);
+//! let surface = light.get(Role::Surface);
+//! let on_surface = light.get(Role::OnSurface);
+//! assert!(on_surface.contrast_ratio(surface) > 4.5);
+//!
+//! // 用户自定义强调色：表面中性色不动，只换强调族。
+//! let custom = Scheme::from_accent(SchemeFlavor::Light, Color::from_hex("#006A5C").unwrap());
+//! assert_eq!(custom.get(Role::Surface), surface);
+//! ```
+//!
+//! ## 口径声明：真 HCT，不是近似
+//!
+//! 标准 M3 的调色板建在 **HCT**（CAM16 色相/彩度 + CIELAB 的 `L*`）上。本模块**就是**那套算法：
+//! CAM16 正换算（`cam16` 模块）取色相/彩度，`L*` 取 tone，色域外走官方的 `HctSolver`
+//! （`hct_solver` 模块：Newton 迭代 + 色调平面上的色相二分，**只压彩度、不硬裁**）。
+//!
+//! | 轴 | 标准 M3 | 本实现 | 一致性 |
+//! |---|---|---|---|
+//! | tone | CIELAB `L*` | CIELAB `L*`（同一个 `Y` 轴） | 逐值一致 |
+//! | 色相 / 彩度 | CAM16 | CAM16（D65 默认观察条件） | 逐值一致（误差 < 1e-4） |
+//! | gamut 映射 | `HctSolver` | 同一套两段求解器，关键平面表原样搬运 | 逐通道一致 |
+//! | 调色板彩度 | Tonal Spot 变体：36 / 16 / 24 / 6 / 8，error 25°/84 | 同（primary/secondary/tertiary/neutral-variant/error 逐值一致） | 逐值一致 |
+//! | 中性彩度 | 6（几乎无色） | 官方口径 6；**产品默认用 12**（有意偏离，见下节「出厂默认色」） | 仅此处偏离 |
+//! | 角色 tone 表 | ColorSpec2021 | 同（49 角色 × light/dark） | 逐值一致 |
+//!
+//! 对齐证据在 `tests/official_baseline.rs` 与 `tests/official_accent.rs`：期望值全部由
+//! `material-color-utilities`（官方 Java 实现，Apache-2.0）跑出来，**每通道误差 ≤1** 才通过。
+//! 所以本 crate 可以对外说「M3 动态取色（Tonal Spot 变体 / standard 对比度）」。
+//!
+//! ## 未实现的部分（gap 登记，别以为已经有）
+//!
+//! | 能力 | 官方叫什么 | 状态 |
+//! |---|---|---|
+//! | 对比度三档（default/medium/high） | `ContrastCurve` + `contrastLevel` | **未实现**：只做 `contrastLevel = 0`。在 0 档下官方那层「tone 差对 + 对比度修正」机制的输入全是常数，等价于本模块的静态 tone 表（已由对齐测试反证） |
+//! | 其他配色变体 | `Vibrant` / `Expressive` / `Fidelity` / `Content` / `Monochrome` / `Neutral` / `Rainbow` / `FruitSalad` / `CMF` | **未实现**：只有 `TonalSpot`（M3 默认、也是 Material Theme Builder 默认） |
+//! | 壁纸多色取色 | `QuantizerCelebi` / `Score` / 多 source 色 | **单种子部分已实现**：量化（5 bit 直方图 + CIELAB k-means）与 `Score` 挑主色在 [`crate::palette`]（M87）。**多 source 色**（一张图出 4 个种子、每个 `*_container` 换色相）仍未实现——产品口径是「一套主题一个强调色」（D38） |
+//! | 换观察条件 | `Hct.inViewingConditions` | **未实现**：只有 sRGB 屏的默认条件（D65 / 200 lux / 背景 `L* 50`） |
+//!
+//! ## 「自定义强调色」与官方 `from_seed` 的关系
+//!
+//! 官方 `SchemeTonalSpot(accent)` 会把**中性表面也染上**种子的色相；本项目的产品语义是
+//! 「换强调色不该让整个窗口底色变脏」，所以 [`Scheme::from_accent`] 只换 primary/secondary/
+//! tertiary 三族，中性色与 error 保持基线。强调族的色值与官方 `from_seed(accent)` 逐个对得上
+//! （`tests/official_accent.rs`，8 个种子 × 12 个强调族角色 × 2 模式 = 192 项）。
+//!
+//! ## 出厂默认色（M70：浅冷天蓝）——含**两处**有意偏离（同一处偏离的两半）
+//!
+//! 产品默认不走官方紫，而是「浅冷天蓝」。默认值收在两个常量里，**换默认只改这两行**
+//! （用户 2026-11-01 拍板采用候选 **④ 天蓝**；③ 浅冷天蓝 `#87CEEB` 留作备选，值仍 pin 在
+//! `tests/skyseed_candidates.rs`）：
+//!
+//! | 项 | 当前值 | 官方值 | 说明 |
+//! |---|---|---|---|
+//! | [`palettes::DEFAULT_SEED`] | `#3C8DBC`（CAM16 hue ≈ 240°） | `#6750A4`（[`palettes::BASELINE_SEED`]） | 种子只贡献**色相**（CAM16 240°）；种子彩度会被 Tonal Spot 丢掉 |
+//! | [`palettes::DEFAULT_NEUTRAL_CHROMA`]（neutral） | `12` | `6` | 让 surface / surface-container-* 带淡蓝调 |
+//! | 联动的 neutral-variant | `14` | `8`（**绝对值**；官方不是「neutral + 2」） | `outline` / `outline-variant` / `surface-variant` 一起偏蓝（light `outline` = `#6A7985` 就是 14 彩度的口径） |
+//!
+//! **定位（D38）**：这套默认只是「**莫奈关闭时的出厂预选色卡**」（首次启动、用户还没选过色卡时
+//! 用的那一套），**不是唯一的配色来源**。用户的配色来源有三级优先：① 启动器背景图取色（Monet）
+//! → ② 桌面壁纸取色 → ③ 莫奈关闭（默认）时从内置多套色卡里选。取色（量化 + 挑主色）、内置色卡库
+//! 与三级回落都在 [`crate::palette`]（M87 落地，D40 分层）；**本模块只负责**「给定种子 + 中性彩度，
+//! 派生出 49 个角色」，不碰像素、不碰路径、不碰回落决策。
+//!
+//! > ⚠️ **有意偏离登记（两处，同一处偏离的两半）**：
+//! >
+//! > 1. **neutral 彩度 `6 → 12`**。理由＝产品要「浅冷」的冷调表面：官方 6 的表面几乎无色，单靠换
+//! >    种子做不到「浅」——primary 的 tone 被官方钉在 40，种子再浅主色也还是中蓝，所以「浅」只能
+//! >    落在中性色上。
+//! > 2. **neutral-variant 彩度 `8 → 14`**。这是第 1 条的连带结果：官方
+//! >    `getNeutralVariantPalette` 写死的是**绝对值 8**（不是「neutral + 2」这种相对式），
+//! >    本实现为了让层次不倒挂，让它跟着 neutral 联动（`nv = neutral + 2`）。若把 nv 钉回 8，
+//! >    表面（12）会比中性变体（8）更「有色」，破坏官方的「neutral < neutral-variant」层次。
+//! >    影响面不只表面：`outline` / `outline-variant` / `surface-variant` 三个角色一起偏蓝。
+//! >
+//! > 除这两处外全部走官方常数（primary 36 / secondary 16 / tertiary 24 且色相 +60° /
+//! > error 25°·84），tone 表与 gamut 映射一行未动；[`Scheme::official_baseline`] 仍是官方的
+//! > 6（neutral）/ 8（neutral-variant）口径。
+//!
+//! 官方口径的锚点仍然完整保留：[`Scheme::official_baseline`]（种子 `#6750A4` + 中性 6）
+//! 是 `tests/official_baseline.rs` 的对账入口，98 项仍是每通道 ≤1；
+//! `tests/skyseed_candidates.rs` 把四档候选（保守蓝 / 冷调蓝 / 浅冷蓝 / 天蓝）的色值逐个 pin 住，
+//! 换默认时它会指着要改的行。
+//!
+//! ✅ 默认色已由用户 2026-11-01 拍板：**④ 天蓝 `#3C8DBC`**。备选 ③ 浅冷蓝 `#87CEEB`
+//! （主色偏青 `#0C6780`）仍在候选表里，换回去只需改 [`palettes::DEFAULT_SEED`] 一行。
+//!
+//! ## 对比度纪律（WCAG AA）
+//!
+//! - 所有 `on-*` 与其承载色（`*-container`、`primary`、`surface`）都满足 **≥ 4.5:1**；
+//!   这一条由 `tests/contrast_aa.rs` 全表验证，且因为 tone 轴固定，**换任何种子色都成立**
+//!   （WCAG 对比度只取决于相对亮度，而 tone 直接钉住 `L*`；中性彩度同理，
+//!   `sky_seed_candidates_meet_wcag_aa` 逐档验证了 M70 的四档候选：4 档 × 2 模式 × 26 对 = 208 项）。
+//! - 例外（显式登记，非缺陷）：
+//!   - [`Role::Outline`] 对 [`Role::Surface`]：M3 定义的**非文字**元素（输入框描边），
+//!     目标 3:1，实测 light 4.26:1 / dark 5.89:1；
+//!   - [`Role::OutlineVariant`] 对 [`Role::Surface`]：纯装饰分隔线，M3 不要求对比度下限；
+//!   - [`Role::SurfaceVariant`]：它是**容器**色（不是前景），不参与对比度门禁。
+//! - 禁用态按 M3 的 alpha 叠加（[`state::DISABLED_CONTENT_ALPHA`]），刻意低于 AA。
+
+pub mod hct;
+pub mod palettes;
+pub mod roles;
+pub mod scheme;
+pub mod state;
+pub mod tonal;
+
+mod cam16;
+mod critical_planes;
+mod hct_solver;
+// `pub(crate)`：取色量化（`crate::palette::quantize`）要在 CIELAB 里算簇距离，复用同一套换算。
+pub(crate) mod space;
+mod viewing_conditions;
+
+pub use hct::Hct;
+pub use palettes::{
+    PaletteSlot, Palettes, BASELINE_SEED, DEFAULT_NEUTRAL_CHROMA, DEFAULT_SEED, NEUTRAL_HUE_DEG,
+};
+pub use roles::Role;
+pub use scheme::{Scheme, SchemeFlavor, SCRIM_ALPHA, SHADOW_ALPHA};
+pub use state::StateLayer;
+pub use tonal::TonalPalette;
+
+/// sRGB 颜色（8 bit/通道 + alpha），刻意不用第三方颜色类型：本 crate 零依赖。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct Color {
+    /// 红通道。
+    pub r: u8,
+    /// 绿通道。
+    pub g: u8,
+    /// 蓝通道。
+    pub b: u8,
+    /// alpha（0 = 全透明，255 = 不透明）。
+    pub a: u8,
+}
+
+impl Color {
+    /// 不透明颜色。
+    pub const fn rgb(r: u8, g: u8, b: u8) -> Self {
+        Self { r, g, b, a: 255 }
+    }
+
+    /// 带 alpha 的颜色（`a` 为 0..=255）。
+    pub const fn rgba(r: u8, g: u8, b: u8, a: u8) -> Self {
+        Self { r, g, b, a }
+    }
+
+    /// 纯黑。
+    pub const BLACK: Color = Color::rgb(0, 0, 0);
+    /// 纯白。
+    pub const WHITE: Color = Color::rgb(255, 255, 255);
+
+    /// 从 `#RRGGBB` / `#RGB` / `#AARRGGBB` 解析（不合法返回 `None`）。
+    ///
+    /// 只给配置读取与测试用——UI 代码里**不许出现色字面量**，一律走 [`Role`]。
+    pub fn from_hex(text: &str) -> Option {
+        let hex = text.trim().trim_start_matches('#');
+        let parse = |s: &str| u8::from_str_radix(s, 16).ok();
+        match hex.len() {
+            3 => {
+                let d = |i: usize| {
+                    let v = parse(&hex[i..i + 1])?;
+                    Some(v * 17)
+                };
+                Some(Self::rgb(d(0)?, d(1)?, d(2)?))
+            }
+            6 => Some(Self::rgb(
+                parse(&hex[0..2])?,
+                parse(&hex[2..4])?,
+                parse(&hex[4..6])?,
+            )),
+            8 => Some(Self::rgba(
+                parse(&hex[2..4])?,
+                parse(&hex[4..6])?,
+                parse(&hex[6..8])?,
+                parse(&hex[0..2])?,
+            )),
+            _ => None,
+        }
+    }
+
+    /// 不透明部分转 `#RRGGBB`（alpha < 255 时附 `#AARRGGBB` 形式）。
+    pub fn to_hex(self) -> String {
+        if self.a == 255 {
+            format!("#{:02X}{:02X}{:02X}", self.r, self.g, self.b)
+        } else {
+            format!("#{:02X}{:02X}{:02X}{:02X}", self.a, self.r, self.g, self.b)
+        }
+    }
+
+    /// 改 alpha（`alpha` 0..1，越界夹取）。
+    pub fn with_alpha(self, alpha: f32) -> Self {
+        Self {
+            a: (alpha.clamp(0.0, 1.0) * 255.0).round() as u8,
+            ..self
+        }
+    }
+
+    /// alpha 归一化到 0..1。
+    pub fn alpha(self) -> f32 {
+        f32::from(self.a) / 255.0
+    }
+
+    /// 是否完全不透明。
+    pub fn is_opaque(self) -> bool {
+        self.a == 255
+    }
+
+    /// WCAG 相对亮度（0..1，即 XYZ 的 `Y` 除以 100）。
+    ///
+    /// 与 WCAG 2.x 的定义同一条 `Y` 轴（Rec.709 系数 0.2126/0.7152/0.0722），
+    /// 所以 [`Color::contrast_ratio`] 就是标准对比度公式。
+    pub fn relative_luminance(self) -> f32 {
+        (space::xyz_from_color(self)[1] / 100.0) as f32
+    }
+
+    /// CIELAB `L*`（0..100）——这就是 M3 的 **tone**。
+    ///
+    /// 调色板按这条轴生成，验收也按这条轴断言；想知道某个色值「是几号 tone」就用它。
+    pub fn lstar(self) -> f32 {
+        space::lstar_from_color(self) as f32
+    }
+
+    /// WCAG 对比度（1..21）。`self` 与 `other` 都不透明时才严格；带 alpha 时先算「不计 alpha」的值。
+    pub fn contrast_ratio(self, other: Self) -> f32 {
+        let a = self.relative_luminance();
+        let b = other.relative_luminance();
+        let (hi, lo) = if a > b { (a, b) } else { (b, a) };
+        (hi + 0.05) / (lo + 0.05)
+    }
+
+    /// alpha 合成：`self` 叠在 `bg` 之上，返回不透明结果。
+    ///
+    /// 这是 M3 状态层/禁用态/遮罩的唯一合成口径（非预乘 alpha）。
+    pub fn over(self, bg: Self) -> Self {
+        let sa = self.alpha();
+        if sa >= 1.0 {
+            return self;
+        }
+        let blend = |fg: u8, b: u8| {
+            let v = f32::from(fg) * sa + f32::from(b) * (1.0 - sa);
+            v.round().clamp(0.0, 255.0) as u8
+        };
+        let a = sa + bg.alpha() * (1.0 - sa);
+        Self {
+            r: blend(self.r, bg.r),
+            g: blend(self.g, bg.g),
+            b: blend(self.b, bg.b),
+            a: (a * 255.0).round().clamp(0.0, 255.0) as u8,
+        }
+    }
+
+    /// 两色线性插值（`t` 0..1），用于动画中间帧（GPU 路径的 shape morph 用得上）。
+    pub fn lerp(self, other: Self, t: f32) -> Self {
+        let t = t.clamp(0.0, 1.0);
+        let mix = |a: u8, b: u8| {
+            (f32::from(a) + (f32::from(b) - f32::from(a)) * t)
+                .round()
+                .clamp(0.0, 255.0) as u8
+        };
+        Self {
+            r: mix(self.r, other.r),
+            g: mix(self.g, other.g),
+            b: mix(self.b, other.b),
+            a: mix(self.a, other.a),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn hex_roundtrip() {
+        let c = Color::from_hex("#6750A4").expect("合法 hex");
+        assert_eq!(c, Color::rgb(0x67, 0x50, 0xA4));
+        assert_eq!(c.to_hex(), "#6750A4");
+        assert_eq!(Color::from_hex("6750a4"), Some(c));
+        assert_eq!(Color::from_hex("#FFF"), Some(Color::WHITE));
+        assert_eq!(Color::from_hex("#80FF0000").map(|c| c.a), Some(0x80));
+        assert_eq!(Color::from_hex("#12345"), None);
+        assert_eq!(Color::from_hex("zzzzzz"), None);
+    }
+
+    #[test]
+    fn contrast_extremes() {
+        assert!((Color::BLACK.contrast_ratio(Color::WHITE) - 21.0).abs() < 0.01);
+        assert!((Color::WHITE.contrast_ratio(Color::WHITE) - 1.0).abs() < 0.001);
+    }
+
+    #[test]
+    fn over_composites_correctly() {
+        let black_50 = Color::BLACK.with_alpha(0.5);
+        let got = black_50.over(Color::WHITE);
+        // with_alpha 量化到 128/255 = 0.50196，所以结果落在 127（不是 128）。
+        assert_eq!((got.r, got.a), (127, 255));
+    }
+
+    #[test]
+    fn lerp_hits_endpoints() {
+        let a = Color::rgb(0, 0, 0);
+        let b = Color::rgb(255, 255, 255);
+        assert_eq!(a.lerp(b, 0.0), a);
+        assert_eq!(a.lerp(b, 1.0), b);
+        assert_eq!(a.lerp(b, 0.5).r, 128);
+    }
+
+    #[test]
+    fn lstar_anchors_at_the_ends() {
+        assert!(Color::BLACK.lstar().abs() < 1.0e-3);
+        assert!((Color::WHITE.lstar() - 100.0).abs() < 1.0e-3);
+        // 中灰（sRGB 128）的 L* 是 53.6 左右，不是 50——这正是「L* 不是 sRGB 编码值」的证据。
+        let mid = Color::rgb(128, 128, 128).lstar();
+        assert!((mid - 53.585).abs() < 0.01, "中灰 L* = {mid}");
+    }
+
+    #[test]
+    fn tone_delta_implies_contrast_floor() {
+        // M3 的招牌性质：tone 差 50 ⇒ 对比度 ≥ 4.5:1（与色相/彩度无关）。
+        for (low, high) in [(10.0_f64, 60.0), (30.0, 80.0), (40.0, 90.0), (20.0, 70.0)] {
+            let a = space::color_from_lstar(low);
+            let b = space::color_from_lstar(high);
+            let ratio = a.contrast_ratio(b);
+            assert!(ratio >= 4.5, "tone {low}→{high} 只有 {ratio:.2}");
+        }
+    }
+}
diff --git a/crates/design/src/color/palettes.rs b/crates/design/src/color/palettes.rs
new file mode 100644
index 0000000..e2a492e
--- /dev/null
+++ b/crates/design/src/color/palettes.rs
@@ -0,0 +1,400 @@
+//! 六条 tone 调色板的集合（M3 scheme 的原料）。
+//!
+//! 角色 → 调色板槽位 → tone 的三段映射在 [`super::scheme`]；这里只负责「种子 → 六条调色板」，
+//! 以及**官方 Tonal Spot 变体**的彩度常数。
+//!
+//! 彩度值来自 `material-color-utilities` 的 `ColorSpec2021.get*Palette(Variant.TONAL_SPOT)`
+//! （Apache-2.0，见 `NOTICE`）：primary 恒定 **36**、secondary **16**、tertiary **24**
+//! （色相 +60°）、neutral **6**、neutral-variant **8**、error 固定色相 **25** 彩度 **84**。
+//! 注意 primary 的 36 与种子自身的彩度无关——这是官方口径：Tonal Spot 是「镇静」变体，
+//! 再鲜艳的种子也会被收到 36，再灰的种子也会被提到 36。
+//!
+//! ## 两个入口：官方口径 vs 产品默认（M70）
+//!
+//! | 入口 | 种子 | 中性彩度 | 用途 |
+//! |---|---|---|---|
+//! | [`Palettes::official_baseline`] / [`super::Scheme::official_baseline`] | [`BASELINE_SEED`]（`#6750A4`） | 6（官方） | 与官方 Java 实现逐角色对齐的**锚点**，`tests/official_baseline.rs` 用它 |
+//! | [`Palettes::baseline`] / [`super::Scheme::baseline`] | [`DEFAULT_SEED`] | [`DEFAULT_NEUTRAL_CHROMA`] | **产品出厂默认**（消费方拿到的就是它） |
+//!
+//! 换默认色只改 [`DEFAULT_SEED`] 与 [`DEFAULT_NEUTRAL_CHROMA`] 两行常量（中性彩度不动就只改一行），
+//! 然后重跑 `tests/skyseed_candidates.rs` 的 pin（它会打印新值并指出哪几行要同步）。
+//! 官方锚点不受影响——**算法没动，动的只是入参**。
+//!
+//! ⚠️ 中性彩度 6 → 12 是**有意偏离**官方 Tonal Spot（理由：产品要「浅冷」的冷调表面），
+//! 偏离登记见 [`super`] 模块文档的「出厂默认色」小节。
+
+use super::tonal::TonalPalette;
+use super::Color;
+
+/// M3 baseline 种子色（与 material-color-utilities 的默认基线同值）。
+///
+/// **不是**产品默认色——产品默认见 [`DEFAULT_SEED`]。
+pub const BASELINE_SEED: Color = Color::rgb(0x67, 0x50, 0xA4);
+
+/// 产品出厂默认种子色 —— M70 候选④「天蓝」，**用户 2026-11-01 拍板采用**。
+///
+/// `#3C8DBC`（CAM16 hue ≈ 239.5°，主色 `#236488`）。注意种子的彩度（42.6）会被 Tonal Spot
+/// 丢掉——主色板的彩度恒为 36，种子只贡献**色相**。
+///
+/// ## 定位（D38）：这是「莫奈关闭时的出厂预选色卡」，不是唯一的配色来源
+///
+/// 用户定了三级优先的配色来源：① 启动器背景图取色（Monet）→ ② 桌面壁纸取色 → ③ 莫奈关闭
+/// （默认）时用户从内置多套色卡里选。本常量 + [`DEFAULT_NEUTRAL_CHROMA`] 只定义**第三级里
+/// 出厂预选的那一套**（首次启动、用户没选过色卡时的那一套；`palette::DEFAULT_CARD` 的种子即本值）。
+///
+/// 取色（量化 + 挑主色）、内置色卡库与三级回落都在 [`crate::palette`]（M87，分层见 D40）；
+/// 本模块只负责「给定种子 + 中性彩度，派生出 49 个角色」。
+pub const DEFAULT_SEED: Color = Color::rgb(0x3C, 0x8D, 0xBC);
+
+/// 产品出厂默认的中性调色板彩度（官方 Tonal Spot 是 6，这里 12 = **有意偏离**）。
+///
+/// 官方 6 让表面几乎无色；12 让 surface / surface-container-* 带一层淡蓝调，
+/// 这是「浅冷天蓝」唯一能落在表面上的手段（primary 的 tone 被官方钉在 40，
+/// 种子再浅也变不成浅蓝）。
+///
+/// **数值安全区间 `6..=13`，产品取 12**：neutral-variant 跟 neutral 联动（`nv = neutral + 2`），
+/// 13 时 nv = 15 仍低于 secondary 的 16；**14 才会撞上**（nv = 16 = secondary），届时要一并改
+/// `NEUTRAL_VARIANT_OFFSET`（私有常量）的规则。nv 的那一半偏离见 `color` 模块文档的偏离登记。
+///
+/// 同样只服务于「出厂预选色卡」（D38 第三级），不约束将来的取色结果。
+/// 内置多套色卡落地时每张卡各带自己的中性彩度（`palette::Card::neutral_chroma`），八张卡
+/// 当前都取本值；再加上中性**色相**固定为 [`NEUTRAL_HUE_DEG`]（D43），八张卡的表面色因此
+/// 逐值相同——切卡只换强调色。
+pub const DEFAULT_NEUTRAL_CHROMA: f64 = 12.0;
+
+/// 中性调色板的**固定色相**（度）——内置色卡共用它，动态取色不用它（D43）。
+///
+/// ## 出处：这就是「天蓝」档当前用的那个中性色相
+///
+/// 值等于 [`DEFAULT_SEED`]（`#3C8DBC`）的 CAM16 色相 **239.51420577630955°**。天蓝档的中性
+/// 调色板本来就是这个色相（`from_seed_with_neutral_chroma` 让中性色跟着种子走），所以它是
+/// **沿用**，不是「另选一个冷调」：`Card::scheme` 换用它之后天蓝卡的 49 个角色必须逐值不变
+/// （`tests/card_neutral.rs` 钉着）。
+///
+/// ## 为什么要有这个常量（D43）
+///
+/// 八张卡原先走 TonalSpot 的「中性色也跟种子染色」，切卡连窗口底色一起换调子：浅色档
+/// `surface` 的实测 CAM16 彩度从 **1.29（rose）跨到 12.03（teal）**——tone 98 处暖相色域装
+/// 不下彩度 12，「请求值 12」在暖相上只能兑现 1.29，9 倍跳变让用户觉得「每张卡都像换了个
+/// 应用」。D43 的处置：**色卡固定中性色相、只换强调色**；动态取色（背景图 / 壁纸）保留逐色
+/// 染色，那才是用户要的 Monet 体验。所以本常量只服务色卡路径，**不要**传给 `Seed::scheme`。
+///
+/// ⚠️ 换 [`DEFAULT_SEED`] 时本常量会「过期」：`neutral_hue_is_the_default_seed_hue` 用
+/// 1e-9° 容差钉住两者的绑定（**不用 `to_bits` 位相等**——色相来自跨平台有末位差的 `atan2`），
+/// 改了种子它就红——那时要想清楚是「色卡跟着新默认色走」（照抄新色相）还是「色卡保持这条
+/// 冷调」（改成显式例外），别静默漂移。
+pub const NEUTRAL_HUE_DEG: f64 = 239.514_205_776_309_55;
+
+/// 调色板槽位（M3 的六条 tonal palette）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum PaletteSlot {
+    /// 主调色板（种子色相，彩度 36）。
+    Primary,
+    /// 次调色板（同色相，彩度 16）。
+    Secondary,
+    /// 第三调色板（种子色相 +60°，彩度 24）。
+    Tertiary,
+    /// 中性调色板（色相跟种子；**色卡路径**例外——固定为 [`NEUTRAL_HUE_DEG`]，D43。
+    /// 官方彩度 6，产品默认 12——见 [`DEFAULT_NEUTRAL_CHROMA`]）。
+    Neutral,
+    /// 中性变体调色板（色相同 neutral，彩度 = neutral + 2；官方 8，产品默认 14）。
+    NeutralVariant,
+    /// 错误调色板（固定红相 25°，彩度 84）。
+    Error,
+}
+
+/// Tonal Spot 的 primary 彩度（官方常数，与种子彩度无关）。
+const PRIMARY_CHROMA: f64 = 36.0;
+/// secondary 彩度。
+const SECONDARY_CHROMA: f64 = 16.0;
+/// tertiary 彩度。
+const TERTIARY_CHROMA: f64 = 24.0;
+/// 官方 Tonal Spot 的 neutral 彩度（几乎是灰）。产品默认用 [`DEFAULT_NEUTRAL_CHROMA`]。
+const TONAL_SPOT_NEUTRAL_CHROMA: f64 = 6.0;
+/// neutral-variant 相对 neutral 的彩度偏移。
+///
+/// ⚠️ 官方 `getNeutralVariantPalette` 写死的是**绝对值 8**，**不是**「neutral + 2」这种相对式；
+/// 本实现选择让 neutral-variant 随 neutral 联动，于是产品默认（neutral 12）取到 **14**。
+/// 这是**有意偏离**的另一半（见 `color` 模块文档的偏离登记），不是官方口径——
+/// 官方的 6 / 8 由 [`Palettes::official_baseline`] 原样保留。
+const NEUTRAL_VARIANT_OFFSET: f64 = 2.0;
+/// error 的色相（HCT 红相）。
+const ERROR_HUE_DEG: f64 = 25.0;
+/// error 的彩度。
+const ERROR_CHROMA: f64 = 84.0;
+/// tertiary 相对种子的色相偏移。
+const TERTIARY_HUE_SHIFT_DEG: f64 = 60.0;
+
+/// 一套完整的六条调色板。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Palettes {
+    /// 主要调色板。
+    pub primary: TonalPalette,
+    /// 次要调色板。
+    pub secondary: TonalPalette,
+    /// 第三调色板。
+    pub tertiary: TonalPalette,
+    /// 中性调色板。
+    pub neutral: TonalPalette,
+    /// 中性变体调色板。
+    pub neutral_variant: TonalPalette,
+    /// 错误调色板。
+    pub error: TonalPalette,
+}
+
+impl Palettes {
+    /// **产品出厂默认**：种子 [`DEFAULT_SEED`] + 中性彩度 [`DEFAULT_NEUTRAL_CHROMA`]。
+    ///
+    /// 消费方（`DesignTokens::baseline`、iced 适配层）拿到的就是这套，所以产品默认色
+    /// 只需要改那两个常量。
+    pub fn baseline() -> Self {
+        Self::from_seed_with_neutral_chroma(DEFAULT_SEED, DEFAULT_NEUTRAL_CHROMA)
+    }
+
+    /// **官方基线的锚点**：种子 [`BASELINE_SEED`] + 官方中性彩度 6（等价官方
+    /// `SchemeTonalSpot(0xFF6750A4)`）。只给对齐测试与文档表格用。
+    pub fn official_baseline() -> Self {
+        Self::from_seed(BASELINE_SEED)
+    }
+
+    /// 从一个种子色派生全套调色板（官方 Tonal Spot 变体，中性彩度取官方 6）。
+    pub fn from_seed(seed: Color) -> Self {
+        Self::from_seed_with_neutral_chroma(seed, TONAL_SPOT_NEUTRAL_CHROMA)
+    }
+
+    /// 从一个种子色派生，并显式指定中性调色板彩度（`6.0` 即官方 Tonal Spot）。
+    ///
+    /// ⚠️ **调用方负责传 `6.0..=13.0`（产品取 12）**。本函数**不做范围校验**，越界的表现是
+    /// 静默退化而不是 panic：
+    /// - `neutral_chroma < 0` 或 `NaN` → 彩度被夹到 0（`TonalPalette::new` 里 `.max(0.0)`），
+    ///   得到一套纯灰的表面（surface ≈ `#F9F9F9`），**不报错**；
+    /// - `neutral_chroma >= 14` → neutral-variant（= neutral + 2）够到甚至超过 secondary 的 16，
+    ///   「中性 < 中性变体 < 次色」的层次被破坏（描边会明显发蓝）。
+    ///
+    /// 除 neutral / neutral-variant 外**全部走官方常数**：primary 恒定 36、secondary 16、
+    /// tertiary 24（色相 +60°）、error 固定 25°/84。所以这条入口不绕算法，只是把「官方写死在
+    /// `getNeutralPalette` / `getNeutralVariantPalette` 里的那两个数」变成可调入参
+    /// （neutral-variant 这里取相对式 `neutral + 2`，属**有意偏离**，见 `NEUTRAL_VARIANT_OFFSET`）。
+    pub fn from_seed_with_neutral_chroma(seed: Color, neutral_chroma: f64) -> Self {
+        let hue = super::Hct::from_color(seed).hue;
+        Self::tonal_spot(hue, neutral_chroma)
+    }
+
+    /// 只换强调色：primary/secondary/tertiary 跟着新强调色的色相走，
+    /// **表面中性色与错误色保持不变**。
+    ///
+    /// 这是本项目的产品语义（换强调色不该让整个窗口底色变脏，见 `DesignTokens::with_accent`）：
+    /// 强调族的色值与官方 `from_seed(accent)` 逐个对得上，中性表面则仍走基线——
+    /// 官方 `from_seed` 会把中性色也染上种子的色相，那是「整窗染色」，不是我们要的。
+    pub fn with_accent(self, accent: Color) -> Self {
+        let hue = super::Hct::from_color(accent).hue;
+        Self {
+            primary: TonalPalette::new(hue, PRIMARY_CHROMA),
+            secondary: TonalPalette::new(hue, SECONDARY_CHROMA),
+            tertiary: TonalPalette::new(hue + TERTIARY_HUE_SHIFT_DEG, TERTIARY_CHROMA),
+            ..self
+        }
+    }
+
+    /// **内置色卡的派生入口（D43）**：强调三族跟 `accent` 的色相走，中性族（含
+    /// neutral-variant）**固定在 `neutral_hue_deg`**。
+    ///
+    /// 与 [`Palettes::from_seed_with_neutral_chroma`]（TonalSpot，中性色跟着种子染色）的唯一
+    /// 差别是中性族色相；与 [`Palettes::with_accent`] 的差别是中性族可以整体搬到一个不属于
+    /// 基线的色相上（`with_accent` 只能沿用 `self` 的中性族）。
+    ///
+    /// 产品用法：色卡路径传 [`NEUTRAL_HUE_DEG`]（= 出厂默认种子的中性色相），于是八张卡的
+    /// 表面色完全相同，只有强调色在换。**取色路径不要用本函数**——D43 明确保留「按图像种子
+    /// 逐色染色」的 Monet 体验（见 [`crate::palette::resolve`]）。
+    pub fn accent_on_fixed_neutral(
+        accent: Color,
+        neutral_hue_deg: f64,
+        neutral_chroma: f64,
+    ) -> Self {
+        let hue = super::Hct::from_color(accent).hue;
+        Self::tonal_spot_with_neutral(hue, neutral_hue_deg, neutral_chroma)
+    }
+
+    /// 官方 Tonal Spot 的六条调色板（色相来自种子，彩度取官方常数，neutral 可调）。
+    fn tonal_spot(hue: f64, neutral_chroma: f64) -> Self {
+        Self::tonal_spot_with_neutral(hue, hue, neutral_chroma)
+    }
+
+    /// 同一套 Tonal Spot，但**中性族（neutral / neutral-variant）的色相可以与种子不同**。
+    ///
+    /// 这是 D43「内置色卡固定中性色相」的实现核心：强调三族跟 `accent_hue`，表面族跟
+    /// `neutral_hue`。其余彩度常数、error 族、tone 表一行未动。
+    fn tonal_spot_with_neutral(accent_hue: f64, neutral_hue: f64, neutral_chroma: f64) -> Self {
+        Self {
+            primary: TonalPalette::new(accent_hue, PRIMARY_CHROMA),
+            secondary: TonalPalette::new(accent_hue, SECONDARY_CHROMA),
+            tertiary: TonalPalette::new(accent_hue + TERTIARY_HUE_SHIFT_DEG, TERTIARY_CHROMA),
+            neutral: TonalPalette::new(neutral_hue, neutral_chroma),
+            neutral_variant: TonalPalette::new(
+                neutral_hue,
+                neutral_chroma + NEUTRAL_VARIANT_OFFSET,
+            ),
+            error: TonalPalette::new(ERROR_HUE_DEG, ERROR_CHROMA),
+        }
+    }
+
+    /// 按槽位取调色板。
+    pub fn slot(&self, slot: PaletteSlot) -> TonalPalette {
+        match slot {
+            PaletteSlot::Primary => self.primary,
+            PaletteSlot::Secondary => self.secondary,
+            PaletteSlot::Tertiary => self.tertiary,
+            PaletteSlot::Neutral => self.neutral,
+            PaletteSlot::NeutralVariant => self.neutral_variant,
+            PaletteSlot::Error => self.error,
+        }
+    }
+
+    /// 方案级取色：槽位 + tone → 色值。
+    pub fn tone(&self, slot: PaletteSlot, tone: f64) -> Color {
+        self.slot(slot).tone(tone)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn official_baseline_uses_the_official_tonal_spot_chromas() {
+        let palettes = Palettes::official_baseline();
+        assert_eq!(palettes.primary.chroma(), 36.0);
+        assert_eq!(palettes.secondary.chroma(), 16.0);
+        assert_eq!(palettes.tertiary.chroma(), 24.0);
+        assert_eq!(palettes.neutral.chroma(), 6.0);
+        assert_eq!(palettes.neutral_variant.chroma(), 8.0);
+        assert_eq!(palettes.error.hue_deg(), 25.0);
+        assert_eq!(palettes.error.chroma(), 84.0);
+    }
+
+    #[test]
+    fn product_default_only_moves_the_named_knobs() {
+        // 产品默认与官方锚点的差别必须**只**在种子色相与中性彩度两处：
+        // primary/secondary/tertiary/error 的取法一模一样（算法没动）。
+        let official = Palettes::official_baseline();
+        let product = Palettes::baseline();
+        assert_eq!(product.primary.chroma(), official.primary.chroma());
+        assert_eq!(product.secondary.chroma(), official.secondary.chroma());
+        assert_eq!(product.tertiary.chroma(), official.tertiary.chroma());
+        assert_eq!(product.error, official.error);
+        assert_eq!(product.neutral.chroma(), DEFAULT_NEUTRAL_CHROMA);
+        assert_eq!(
+            product.neutral_variant.chroma(),
+            DEFAULT_NEUTRAL_CHROMA + NEUTRAL_VARIANT_OFFSET
+        );
+        let seed = super::super::Hct::from_color(DEFAULT_SEED);
+        assert!((product.primary.hue_deg() - seed.hue).abs() < 1.0e-9);
+    }
+
+    #[test]
+    fn neutral_chroma_knob_keeps_the_official_ordering() {
+        // 官方关系 neutral(6) < neutral-variant(8) < secondary(16) 在安全区间里必须一直成立，
+        // 否则「表面比次色还艳」或两族撞色。
+        for neutral in [6.0, 8.0, 10.0, 12.0] {
+            let p = Palettes::from_seed_with_neutral_chroma(DEFAULT_SEED, neutral);
+            assert!(p.neutral.chroma() < p.neutral_variant.chroma());
+            assert!(p.neutral_variant.chroma() < p.secondary.chroma());
+            // 中性彩度不影响 tone 轴：tone 98 的 surface 仍是最亮的那个。
+            let surface = p.tone(PaletteSlot::Neutral, 98.0);
+            assert!(surface.relative_luminance() > 0.9);
+        }
+    }
+
+    #[test]
+    fn product_default_neutral_chroma_is_a_registered_deviation() {
+        // 官方 neutral / neutral-variant 是 6 / 8；产品默认是 12 / 14。
+        // 这**不是官方口径**，是「有意偏离」（见 `color` 模块文档的偏离登记）。
+        // 想把 nv 拉回官方绝对值 8 的人，请先改登记再改这里：直接钉成 8 会让表面（12）
+        // 比中性变体（8）更「有色」，破坏官方的 neutral < neutral-variant 层次。
+        let product = Palettes::baseline();
+        assert_eq!(product.neutral.chroma(), 12.0, "产品默认 neutral 彩度");
+        assert_eq!(
+            product.neutral_variant.chroma(),
+            14.0,
+            "产品默认的 neutral-variant 彩度 14 是**有意偏离**（官方绝对值 8），改前先更新偏离登记"
+        );
+        let official = Palettes::official_baseline();
+        assert_eq!(official.neutral.chroma(), 6.0, "官方锚点仍是 6");
+        assert_eq!(
+            official.neutral_variant.chroma(),
+            8.0,
+            "官方锚点仍是绝对值 8（不是 neutral + 2 的相对式）"
+        );
+    }
+
+    #[test]
+    fn baseline_hue_comes_from_the_seed() {
+        let palettes = Palettes::official_baseline();
+        let seed = super::super::Hct::from_color(BASELINE_SEED);
+        assert!((palettes.primary.hue_deg() - seed.hue).abs() < 1.0e-9);
+        assert!((palettes.neutral.hue_deg() - seed.hue).abs() < 1.0e-9);
+        assert!((palettes.tertiary.hue_deg() - (seed.hue + 60.0)).abs() < 1.0e-9);
+    }
+
+    #[test]
+    fn seed_chroma_never_leaks_into_the_primary_ramp() {
+        // 官方口径：Tonal Spot 的彩度是常数，纯灰种子也会得到彩度 36 的主色板。
+        let gray = Palettes::from_seed(Color::rgb(0x6E, 0x6E, 0x6E));
+        assert_eq!(gray.primary.chroma(), 36.0);
+        let hot = Palettes::from_seed(Color::rgb(0xFF, 0x00, 0x00));
+        assert_eq!(hot.primary.chroma(), 36.0);
+    }
+
+    #[test]
+    fn accent_override_keeps_surfaces_and_error() {
+        let base = Palettes::baseline();
+        let swapped = base.with_accent(Color::rgb(0x00, 0x6A, 0x5C));
+        assert_eq!(swapped.neutral, base.neutral);
+        assert_eq!(swapped.neutral_variant, base.neutral_variant);
+        assert_eq!(swapped.error, base.error);
+        assert_ne!(swapped.primary.hue_deg(), base.primary.hue_deg());
+        assert_eq!(swapped.primary.chroma(), 36.0);
+    }
+
+    #[test]
+    fn neutral_hue_is_the_default_seed_hue() {
+        // D43 的绑定器。用 1e-9° 容差而非 `to_bits()` 位相等：色相来自 `atan2()`，glibc 与
+        // UCRT 理论可差 1 ulp（~1e-14°），位相等会在另一个 OS 的 CI 上红；这条要抓的是「换了
+        // `DEFAULT_SEED` 却没复核常量」（偏几十度）。「逐值不变」的位相等钉子在同平台的
+        // `card_neutral.rs::sky_card_is_bit_identical_to_the_product_baseline`（两个算出的值
+        // 互比，不涉及跨平台字面量）。
+        let seed_hue = super::super::Hct::from_color(DEFAULT_SEED).hue;
+        assert!(
+            (NEUTRAL_HUE_DEG - seed_hue).abs() < 1.0e-9,
+            "NEUTRAL_HUE_DEG = {NEUTRAL_HUE_DEG:?} 与 DEFAULT_SEED 的色相 {seed_hue:?} \
+             相差超过 1e-9°（换默认种子时：要么照抄新色相，要么把这里改成显式例外）"
+        );
+    }
+
+    #[test]
+    fn accent_on_fixed_neutral_only_moves_the_neutral_hue() {
+        let official = Palettes::official_baseline();
+        // 中性色相 = 基线色相时，与官方的 from_seed 完全等价（不放宽算法）。
+        let same = Palettes::accent_on_fixed_neutral(DEFAULT_SEED, NEUTRAL_HUE_DEG, 12.0);
+        let per_seed = Palettes::from_seed_with_neutral_chroma(DEFAULT_SEED, 12.0);
+        assert_eq!(
+            same, per_seed,
+            "中性色相取种子色相时必须与 TonalSpot 逐项相同"
+        );
+
+        // 换一个中性色相：只有中性两族的色相动，彩度与强调族一律不动。
+        let moved = Palettes::accent_on_fixed_neutral(DEFAULT_SEED, 120.0, 12.0);
+        assert_eq!(moved.primary, per_seed.primary);
+        assert_eq!(moved.secondary, per_seed.secondary);
+        assert_eq!(moved.tertiary, per_seed.tertiary);
+        assert_eq!(moved.error, per_seed.error);
+        assert_eq!(moved.neutral.chroma(), per_seed.neutral.chroma());
+        assert_eq!(
+            moved.neutral_variant.chroma(),
+            per_seed.neutral_variant.chroma()
+        );
+        assert_eq!(moved.neutral.hue_deg(), 120.0);
+        assert_eq!(moved.neutral_variant.hue_deg(), 120.0);
+        assert_eq!(moved.primary.chroma(), official.primary.chroma());
+    }
+}
diff --git a/crates/design/src/color/roles.rs b/crates/design/src/color/roles.rs
new file mode 100644
index 0000000..4466cb7
--- /dev/null
+++ b/crates/design/src/color/roles.rs
@@ -0,0 +1,276 @@
+//! M3 语义色角色：`Role` 枚举是**唯一的名字清单**（49 个，M3 基础集全覆盖）。
+//!
+//! 后续 iced 页面不许另起名字（如 `bg-card` / `fg-primary`）——Fluent 时代的旧名到此为止，
+//! 要表达「卡片底」就用 [`Role::SurfaceContainerLow`]，要表达「次要文字」就用
+//! [`Role::OnSurfaceVariant`]（对应关系见 `DevDocs/SubAgentsTalk/design-令牌约定.md`）。
+
+/// M3 语义色角色（49 个）。
+///
+/// 顺序即 [`Role::ALL`] 的顺序，也是 [`super::Scheme`] 内部数组的下标：
+/// **只允许在末尾追加**，插到中间会静默改变已存盘的颜色映射。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub enum Role {
+    /// 主色：主操作填充、选中指示。
+    Primary,
+    /// 主色之上的前景（文字/图标）。
+    OnPrimary,
+    /// 主色容器：次级强调块、选中片。
+    PrimaryContainer,
+    /// 主色容器之上的前景。
+    OnPrimaryContainer,
+    /// 次色：低频强调、图表。
+    Secondary,
+    /// 次色之上的前景。
+    OnSecondary,
+    /// 次色容器。
+    SecondaryContainer,
+    /// 次色容器之上的前景。
+    OnSecondaryContainer,
+    /// 第三色：与主/次形成对比的装饰强调。
+    Tertiary,
+    /// 第三色之上的前景。
+    OnTertiary,
+    /// 第三色容器。
+    TertiaryContainer,
+    /// 第三色容器之上的前景。
+    OnTertiaryContainer,
+    /// 错误色：错误文字、危险操作填充。
+    Error,
+    /// 错误色之上的前景。
+    OnError,
+    /// 错误容器：错误提示底。
+    ErrorContainer,
+    /// 错误容器之上的前景。
+    OnErrorContainer,
+    /// 表面：窗口/内容底色（M3 最新口径里取代 background）。
+    Surface,
+    /// 表面之上的主体文字。
+    OnSurface,
+    /// 表面变体：中性分隔/次级容器（**不是**文字色）。
+    SurfaceVariant,
+    /// 表面变体之上的次级文字/图标。
+    OnSurfaceVariant,
+    /// 背景（M3 已并入 surface，保留以兼容旧值）。
+    Background,
+    /// 背景之上的文本（同上，保留兼容）。
+    OnBackground,
+    /// 变暗的表面（模态背后的压暗层）。
+    SurfaceDim,
+    /// 变亮的表面（深色下的抬高底）。
+    SurfaceBright,
+    /// 最低层容器（比 surface 更低）。
+    SurfaceContainerLowest,
+    /// 低层容器：卡片。
+    SurfaceContainerLow,
+    /// 标准容器：卡片/面板。
+    SurfaceContainer,
+    /// 高层容器：浮层。
+    SurfaceContainerHigh,
+    /// 最高层容器：对话框/菜单。
+    SurfaceContainerHighest,
+    /// 描边：输入框边框等（非文字，3:1 即可）。
+    Outline,
+    /// 弱描边：分隔线（纯装饰）。
+    OutlineVariant,
+    /// 反相表面：Snackbar / Tooltip 底。
+    InverseSurface,
+    /// 反相表面之上的文字。
+    InverseOnSurface,
+    /// 反相表面之上的强调。
+    InversePrimary,
+    /// 阴影色（通常带 alpha，见 [`super::Scheme::shadow`]）。
+    Shadow,
+    /// 遮罩色（模态背景，通常带 alpha）。
+    Scrim,
+    /// 表面着色（M3 旧规范的 elevation tint，现已被 surface container 取代）。
+    SurfaceTint,
+    /// 固定主色（深浅模式同值，用于需要跨模式稳定的块）。
+    PrimaryFixed,
+    /// 固定主色的暗档。
+    PrimaryFixedDim,
+    /// 固定主色之上的前景。
+    OnPrimaryFixed,
+    /// 固定主色暗档之上的前景。
+    OnPrimaryFixedVariant,
+    /// 固定次色。
+    SecondaryFixed,
+    /// 固定次色的暗档。
+    SecondaryFixedDim,
+    /// 固定次色之上的前景。
+    OnSecondaryFixed,
+    /// 固定次色暗档之上的前景。
+    OnSecondaryFixedVariant,
+    /// 固定第三色。
+    TertiaryFixed,
+    /// 固定第三色的暗档。
+    TertiaryFixedDim,
+    /// 固定第三色之上的前景。
+    OnTertiaryFixed,
+    /// 固定第三色暗档之上的前景。
+    OnTertiaryFixedVariant,
+}
+
+impl Role {
+    /// 全部 49 个角色，按 `Role as usize` 顺序排列。
+    pub const ALL: [Role; 49] = [
+        Role::Primary,
+        Role::OnPrimary,
+        Role::PrimaryContainer,
+        Role::OnPrimaryContainer,
+        Role::Secondary,
+        Role::OnSecondary,
+        Role::SecondaryContainer,
+        Role::OnSecondaryContainer,
+        Role::Tertiary,
+        Role::OnTertiary,
+        Role::TertiaryContainer,
+        Role::OnTertiaryContainer,
+        Role::Error,
+        Role::OnError,
+        Role::ErrorContainer,
+        Role::OnErrorContainer,
+        Role::Surface,
+        Role::OnSurface,
+        Role::SurfaceVariant,
+        Role::OnSurfaceVariant,
+        Role::Background,
+        Role::OnBackground,
+        Role::SurfaceDim,
+        Role::SurfaceBright,
+        Role::SurfaceContainerLowest,
+        Role::SurfaceContainerLow,
+        Role::SurfaceContainer,
+        Role::SurfaceContainerHigh,
+        Role::SurfaceContainerHighest,
+        Role::Outline,
+        Role::OutlineVariant,
+        Role::InverseSurface,
+        Role::InverseOnSurface,
+        Role::InversePrimary,
+        Role::Shadow,
+        Role::Scrim,
+        Role::SurfaceTint,
+        Role::PrimaryFixed,
+        Role::PrimaryFixedDim,
+        Role::OnPrimaryFixed,
+        Role::OnPrimaryFixedVariant,
+        Role::SecondaryFixed,
+        Role::SecondaryFixedDim,
+        Role::OnSecondaryFixed,
+        Role::OnSecondaryFixedVariant,
+        Role::TertiaryFixed,
+        Role::TertiaryFixedDim,
+        Role::OnTertiaryFixed,
+        Role::OnTertiaryFixedVariant,
+    ];
+
+    /// 稳定字符串名（kebab-case），用于日志、配置、快照对拍与文档表格。
+    pub const fn name(self) -> &'static str {
+        match self {
+            Role::Primary => "primary",
+            Role::OnPrimary => "on-primary",
+            Role::PrimaryContainer => "primary-container",
+            Role::OnPrimaryContainer => "on-primary-container",
+            Role::Secondary => "secondary",
+            Role::OnSecondary => "on-secondary",
+            Role::SecondaryContainer => "secondary-container",
+            Role::OnSecondaryContainer => "on-secondary-container",
+            Role::Tertiary => "tertiary",
+            Role::OnTertiary => "on-tertiary",
+            Role::TertiaryContainer => "tertiary-container",
+            Role::OnTertiaryContainer => "on-tertiary-container",
+            Role::Error => "error",
+            Role::OnError => "on-error",
+            Role::ErrorContainer => "error-container",
+            Role::OnErrorContainer => "on-error-container",
+            Role::Surface => "surface",
+            Role::OnSurface => "on-surface",
+            Role::SurfaceVariant => "surface-variant",
+            Role::OnSurfaceVariant => "on-surface-variant",
+            Role::Background => "background",
+            Role::OnBackground => "on-background",
+            Role::SurfaceDim => "surface-dim",
+            Role::SurfaceBright => "surface-bright",
+            Role::SurfaceContainerLowest => "surface-container-lowest",
+            Role::SurfaceContainerLow => "surface-container-low",
+            Role::SurfaceContainer => "surface-container",
+            Role::SurfaceContainerHigh => "surface-container-high",
+            Role::SurfaceContainerHighest => "surface-container-highest",
+            Role::Outline => "outline",
+            Role::OutlineVariant => "outline-variant",
+            Role::InverseSurface => "inverse-surface",
+            Role::InverseOnSurface => "inverse-on-surface",
+            Role::InversePrimary => "inverse-primary",
+            Role::Shadow => "shadow",
+            Role::Scrim => "scrim",
+            Role::SurfaceTint => "surface-tint",
+            Role::PrimaryFixed => "primary-fixed",
+            Role::PrimaryFixedDim => "primary-fixed-dim",
+            Role::OnPrimaryFixed => "on-primary-fixed",
+            Role::OnPrimaryFixedVariant => "on-primary-fixed-variant",
+            Role::SecondaryFixed => "secondary-fixed",
+            Role::SecondaryFixedDim => "secondary-fixed-dim",
+            Role::OnSecondaryFixed => "on-secondary-fixed",
+            Role::OnSecondaryFixedVariant => "on-secondary-fixed-variant",
+            Role::TertiaryFixed => "tertiary-fixed",
+            Role::TertiaryFixedDim => "tertiary-fixed-dim",
+            Role::OnTertiaryFixed => "on-tertiary-fixed",
+            Role::OnTertiaryFixedVariant => "on-tertiary-fixed-variant",
+        }
+    }
+
+    /// 该角色是否是「文字/图标前景色」（`on-*` 与 `inverse-on-surface` 一类）。
+    ///
+    /// 用于对比度门禁区分两类要求：前景对容器 ≥ 4.5:1（WCAG AA 正文），
+    /// 非文字元素 ≥ 3:1。
+    pub const fn is_foreground(self) -> bool {
+        matches!(
+            self,
+            Role::OnPrimary
+                | Role::OnPrimaryContainer
+                | Role::OnSecondary
+                | Role::OnSecondaryContainer
+                | Role::OnTertiary
+                | Role::OnTertiaryContainer
+                | Role::OnError
+                | Role::OnErrorContainer
+                | Role::OnSurface
+                | Role::OnSurfaceVariant
+                | Role::OnBackground
+                | Role::InverseOnSurface
+                | Role::InversePrimary
+                | Role::OnPrimaryFixed
+                | Role::OnPrimaryFixedVariant
+                | Role::OnSecondaryFixed
+                | Role::OnSecondaryFixedVariant
+                | Role::OnTertiaryFixed
+                | Role::OnTertiaryFixedVariant
+        )
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn all_is_in_enum_order() {
+        for (i, role) in Role::ALL.iter().enumerate() {
+            assert_eq!(*role as usize, i, "Role::ALL 顺序必须等于枚举声明顺序");
+        }
+    }
+
+    #[test]
+    fn names_are_unique_and_kebab() {
+        let mut seen = std::collections::BTreeSet::new();
+        for role in Role::ALL {
+            let name = role.name();
+            assert!(seen.insert(name), "角色名重复：{name}");
+            assert!(
+                name.chars()
+                    .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-'),
+                "角色名必须是 kebab-case：{name}"
+            );
+        }
+    }
+}
diff --git a/crates/design/src/color/scheme.rs b/crates/design/src/color/scheme.rs
new file mode 100644
index 0000000..68892f8
--- /dev/null
+++ b/crates/design/src/color/scheme.rs
@@ -0,0 +1,342 @@
+//! 一套完整的 M3 语义色方案（`Scheme`）：角色 → 调色板槽位 → tone 的三段映射。
+//!
+//! tone 表取自 **ColorSpec2021** 的官方映射（`MaterialDynamicColors` 的 light/dark 两列，
+//! 见 `NOTICE`）。固定角色（`*-fixed*`）深浅同值，因为它们的用途就是「跨模式稳定」。
+//!
+//! ## 只实现了 contrast level = 0（standard）
+//!
+//! 官方的 `ColorSpec2021.getTone()` 还有一层机制：`toneDeltaPair`（成对角色保持 tone 差）
+//! 与 `ContrastCurve`（按对比度等级修正 tone）。在 **contrastLevel = 0** 下这层机制的输入
+//! 全部是常数：`ContrastCurve.get(0)` 恒等于 normal 档的 tone，而「背景 tone」也都是本表里的
+//! 常数，所以它对 49 个角色的调整结果**就是这张表本身**。测试
+//! `tests/official_baseline.rs` 用官方 Java 实现的逐角色输出反证了这一点（每通道误差 ≤1）：
+//! 表错一格，对齐测试就会红。三档对比度（medium/high）不在本 crate 范围内，见
+//! [`super`] 的 gap 登记。
+
+use super::palettes::{PaletteSlot, Palettes};
+use super::roles::Role;
+use super::Color;
+
+/// 深浅模式。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum SchemeFlavor {
+    /// 浅色（亮底暗字）。
+    Light,
+    /// 深色（暗底亮字）。
+    Dark,
+}
+
+impl SchemeFlavor {
+    /// 是否深色模式。
+    pub const fn is_dark(self) -> bool {
+        matches!(self, SchemeFlavor::Dark)
+    }
+
+    /// 反过来那一个。
+    pub const fn toggled(self) -> Self {
+        match self {
+            SchemeFlavor::Light => SchemeFlavor::Dark,
+            SchemeFlavor::Dark => SchemeFlavor::Light,
+        }
+    }
+
+    /// 稳定字符串名（`light` / `dark`），写配置与日志用。
+    pub const fn name(self) -> &'static str {
+        match self {
+            SchemeFlavor::Light => "light",
+            SchemeFlavor::Dark => "dark",
+        }
+    }
+}
+
+/// 阴影色透明度（M3 阴影 = 纯黑 + 这个 alpha；绘制阴影时叠在背景上）。
+pub const SHADOW_ALPHA: f32 = 0.20;
+/// 遮罩色透明度（模态背景压暗层）。
+pub const SCRIM_ALPHA: f32 = 0.32;
+
+/// 一条「角色 → 槽位 + tone」映射。
+struct ToneRow {
+    role: Role,
+    slot: PaletteSlot,
+    light: f64,
+    dark: f64,
+}
+
+/// 49 个角色的 tone 映射表（ColorSpec2021），**下标必须等于 `Role as usize`**（由测试钉死）。
+const TONE_TABLE: [ToneRow; 49] = [
+    row(Role::Primary, PaletteSlot::Primary, 40.0, 80.0),
+    row(Role::OnPrimary, PaletteSlot::Primary, 100.0, 20.0),
+    row(Role::PrimaryContainer, PaletteSlot::Primary, 90.0, 30.0),
+    row(Role::OnPrimaryContainer, PaletteSlot::Primary, 30.0, 90.0),
+    row(Role::Secondary, PaletteSlot::Secondary, 40.0, 80.0),
+    row(Role::OnSecondary, PaletteSlot::Secondary, 100.0, 20.0),
+    row(Role::SecondaryContainer, PaletteSlot::Secondary, 90.0, 30.0),
+    row(
+        Role::OnSecondaryContainer,
+        PaletteSlot::Secondary,
+        30.0,
+        90.0,
+    ),
+    row(Role::Tertiary, PaletteSlot::Tertiary, 40.0, 80.0),
+    row(Role::OnTertiary, PaletteSlot::Tertiary, 100.0, 20.0),
+    row(Role::TertiaryContainer, PaletteSlot::Tertiary, 90.0, 30.0),
+    row(Role::OnTertiaryContainer, PaletteSlot::Tertiary, 30.0, 90.0),
+    row(Role::Error, PaletteSlot::Error, 40.0, 80.0),
+    row(Role::OnError, PaletteSlot::Error, 100.0, 20.0),
+    row(Role::ErrorContainer, PaletteSlot::Error, 90.0, 30.0),
+    row(Role::OnErrorContainer, PaletteSlot::Error, 30.0, 90.0),
+    row(Role::Surface, PaletteSlot::Neutral, 98.0, 6.0),
+    row(Role::OnSurface, PaletteSlot::Neutral, 10.0, 90.0),
+    row(
+        Role::SurfaceVariant,
+        PaletteSlot::NeutralVariant,
+        90.0,
+        30.0,
+    ),
+    row(
+        Role::OnSurfaceVariant,
+        PaletteSlot::NeutralVariant,
+        30.0,
+        80.0,
+    ),
+    row(Role::Background, PaletteSlot::Neutral, 98.0, 6.0),
+    row(Role::OnBackground, PaletteSlot::Neutral, 10.0, 90.0),
+    row(Role::SurfaceDim, PaletteSlot::Neutral, 87.0, 6.0),
+    row(Role::SurfaceBright, PaletteSlot::Neutral, 98.0, 24.0),
+    row(
+        Role::SurfaceContainerLowest,
+        PaletteSlot::Neutral,
+        100.0,
+        4.0,
+    ),
+    row(Role::SurfaceContainerLow, PaletteSlot::Neutral, 96.0, 10.0),
+    row(Role::SurfaceContainer, PaletteSlot::Neutral, 94.0, 12.0),
+    row(Role::SurfaceContainerHigh, PaletteSlot::Neutral, 92.0, 17.0),
+    row(
+        Role::SurfaceContainerHighest,
+        PaletteSlot::Neutral,
+        90.0,
+        22.0,
+    ),
+    row(Role::Outline, PaletteSlot::NeutralVariant, 50.0, 60.0),
+    row(
+        Role::OutlineVariant,
+        PaletteSlot::NeutralVariant,
+        80.0,
+        30.0,
+    ),
+    row(Role::InverseSurface, PaletteSlot::Neutral, 20.0, 90.0),
+    row(Role::InverseOnSurface, PaletteSlot::Neutral, 95.0, 20.0),
+    row(Role::InversePrimary, PaletteSlot::Primary, 80.0, 40.0),
+    row(Role::Shadow, PaletteSlot::Neutral, 0.0, 0.0),
+    row(Role::Scrim, PaletteSlot::Neutral, 0.0, 0.0),
+    row(Role::SurfaceTint, PaletteSlot::Primary, 40.0, 80.0),
+    row(Role::PrimaryFixed, PaletteSlot::Primary, 90.0, 90.0),
+    row(Role::PrimaryFixedDim, PaletteSlot::Primary, 80.0, 80.0),
+    row(Role::OnPrimaryFixed, PaletteSlot::Primary, 10.0, 10.0),
+    row(
+        Role::OnPrimaryFixedVariant,
+        PaletteSlot::Primary,
+        30.0,
+        30.0,
+    ),
+    row(Role::SecondaryFixed, PaletteSlot::Secondary, 90.0, 90.0),
+    row(Role::SecondaryFixedDim, PaletteSlot::Secondary, 80.0, 80.0),
+    row(Role::OnSecondaryFixed, PaletteSlot::Secondary, 10.0, 10.0),
+    row(
+        Role::OnSecondaryFixedVariant,
+        PaletteSlot::Secondary,
+        30.0,
+        30.0,
+    ),
+    row(Role::TertiaryFixed, PaletteSlot::Tertiary, 90.0, 90.0),
+    row(Role::TertiaryFixedDim, PaletteSlot::Tertiary, 80.0, 80.0),
+    row(Role::OnTertiaryFixed, PaletteSlot::Tertiary, 10.0, 10.0),
+    row(
+        Role::OnTertiaryFixedVariant,
+        PaletteSlot::Tertiary,
+        30.0,
+        30.0,
+    ),
+];
+
+/// `const` 友好的行构造器（数组初始化里不能调用非 const fn 之外的东西）。
+const fn row(role: Role, slot: PaletteSlot, light: f64, dark: f64) -> ToneRow {
+    ToneRow {
+        role,
+        slot,
+        light,
+        dark,
+    }
+}
+
+/// 一套语义色（49 个角色，全部已解析成具体颜色）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Scheme {
+    flavor: SchemeFlavor,
+    colors: [Color; 49],
+}
+
+impl Scheme {
+    /// **产品出厂默认方案**（种子 [`super::palettes::DEFAULT_SEED`] + 中性彩度
+    /// [`super::palettes::DEFAULT_NEUTRAL_CHROMA`]，见 [`Palettes::baseline`]）。
+    pub fn baseline(flavor: SchemeFlavor) -> Self {
+        Self::from_palettes(&Palettes::baseline(), flavor)
+    }
+
+    /// **官方基线锚点**（种子 `#6750A4` + 官方中性彩度 6，等价官方
+    /// `SchemeTonalSpot(0xFF6750A4)`）。
+    ///
+    /// 与 [`Scheme::baseline`] 的区别只有入参：算法、tone 表、gamut 映射完全同一条路径，
+    /// 所以 `tests/official_baseline.rs` 拿它跟官方 Java 输出逐角色对账。
+    pub fn official_baseline(flavor: SchemeFlavor) -> Self {
+        Self::from_palettes(&Palettes::official_baseline(), flavor)
+    }
+
+    /// 指定种子色的方案（表面色与强调色同源，等价官方 `SchemeTonalSpot`）。
+    pub fn from_seed(flavor: SchemeFlavor, seed: Color) -> Self {
+        Self::from_palettes(&Palettes::from_seed(seed), flavor)
+    }
+
+    /// 只覆盖强调色（表面中性色仍走基线，见 [`Palettes::with_accent`]）。
+    pub fn from_accent(flavor: SchemeFlavor, accent: Color) -> Self {
+        Self::from_palettes(&Palettes::baseline().with_accent(accent), flavor)
+    }
+
+    /// 直接从调色板集合构建（高级入口：整仓测试与自定义 scheme 用）。
+    pub fn from_palettes(palettes: &Palettes, flavor: SchemeFlavor) -> Self {
+        let colors = std::array::from_fn(|i| {
+            let entry = &TONE_TABLE[i];
+            palettes.tone(entry.slot, Scheme::tone_of(entry.role, flavor))
+        });
+        Self { flavor, colors }
+    }
+
+    /// 从 49 个已解析色值直接构造（**底层入口**，下标必须等于 `Role as usize`）。
+    ///
+    /// 只给两类调用方用：
+    /// 1. `palette::wcag` 的对比度收敛——它按角色替换个别色值后要重新组装成一套方案；
+    /// 2. 测试——要能构造「故意不达标」的方案，比较度校验器才有反证。
+    ///
+    /// 常规路径一律走 [`Scheme::from_palettes`]：那样色值才是 tone 表的推导结果，
+    /// 而不是随手塞进来的数。
+    pub fn from_colors(flavor: SchemeFlavor, colors: [Color; 49]) -> Self {
+        Self { flavor, colors }
+    }
+
+    /// 该角色在指定模式下的 tone 值（M3 语义；文档表格、调试与测试用）。
+    pub fn tone_of(role: Role, flavor: SchemeFlavor) -> f64 {
+        let entry = &TONE_TABLE[role as usize];
+        debug_assert_eq!(entry.role, role, "TONE_TABLE 下标必须等于角色序号");
+        match flavor {
+            SchemeFlavor::Light => entry.light,
+            SchemeFlavor::Dark => entry.dark,
+        }
+    }
+
+    /// 取角色色值。
+    pub fn get(&self, role: Role) -> Color {
+        self.colors[role as usize]
+    }
+
+    /// 当前模式。
+    pub fn flavor(&self) -> SchemeFlavor {
+        self.flavor
+    }
+
+    /// 按角色顺序遍历（`for (role, color) in scheme.iter()`）。
+    pub fn iter(&self) -> impl Iterator + '_ {
+        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/lib.rs b/crates/design/src/lib.rs
new file mode 100644
index 0000000..f479ac1
--- /dev/null
+++ b/crates/design/src/lib.rs
@@ -0,0 +1,147 @@
+//! # unlucky-design · ULL 设计令牌唯一真源
+//!
+//! 视觉基线 = **Material 3 Expressive**（D26 锁定，风格与框架不再更换）。这个 crate 只装
+//! **渲染无关的数据与纯函数**：色彩角色、排版 ramp、形状刻度、高程、动效参数、图标几何。
+//! 它不依赖任何 UI / 渲染框架（iced / slint / winit / wgpu / gtk …），也不依赖任何第三方 crate，
+//! 因此 iced 迁移、CLI、甚至离屏截图工具都能吃同一套值——这是「UI 整体性」的地基。
+//!
+//! ## 边界（谁负责什么）
+//!
+//! | 层 | 负责 | 不负责 |
+//! |---|---|---|
+//! | `unlucky-design`（本 crate） | 令牌的值与它们之间的纯函数关系（tone→色、type role→字号/行高/字重、shape→半径、spring→时长） | 布局、控件、绘制、字体加载、图片、动画驱动 |
+//! | iced 适配层（后续 mission） | 把令牌翻成 iced 的类型（`Color` / `Length` / `Font` / 动画时钟） | 自己发明新令牌名或新取值 |
+//! | 页面 mission | 消费令牌与 [`component_map`] 的档位约定 | 硬编码色值 / 字号 / 半径 / 时长 |
+//!
+//! ## 分模块
+//!
+//! - [`color`]：M3 语义色角色（49 个）× light/dark 双套 + tone 调色板（**真 HCT**：CAM16 色相/彩度
+//!   + CIELAB `L*`，官方 `ColorSpec2021` tone 表，与官方 Java 实现逐通道对齐——口径见模块文档）
+//! - [`palette`]：配色来源（D38/D40）——图片像素 → 种子 → 完整方案（Monet 式量化 + 打分）、
+//!   内置色卡、三级优先与失败回落、对比度收敛。**只吃已解码的像素**，解码在 `crates/palette-extract`
+//! - [`typography`]：M3 type scale 15 档 + 三平台字体族回退栈
+//! - [`shape`]：M3 Expressive 形状刻度 + shape morph 数据 + [`shape::ComponentRadius`]（微控件圆角层，D32）
+//! - [`elevation`]：elevation level 与 surface tint / surface container 规则
+//! - [`motion`]：时长、easing（可采样）、Expressive 弹簧参数
+//! - [`spacing`]：4px 栅格、骨架尺寸（原 `metrics.slint` 的框架无关部分）、[`stroke::HAIRLINE`]（一像素线）
+//! - [`icons`]：24 网格图标几何（SVG path 字符串）+ 描边语义
+//! - [`component_map`]：组件 → 档位映射表（哪个组件用哪档形状/高程/动效/字体）
+//!   + [`component_map::ComponentMetrics`]（控件内部微几何，与 `LayoutMetrics` 分工见该模块文档）
+//!
+//! ## 最小用法
+//!
+//! ```
+//! use unlucky_design::color::{Role, Scheme, SchemeFlavor};
+//! use unlucky_design::typography::{FontFamily, Platform, TypeRole};
+//!
+//! let light = Scheme::baseline(SchemeFlavor::Light);
+//! let ratio = light.contrast(Role::OnSurface, Role::Surface);
+//! assert!(ratio >= 4.5, "正文对表面必须满足 WCAG AA");
+//!
+//! let title = TypeRole::TitleLarge.style();
+//! assert_eq!(title.size_px, 22.0);
+//! let stack = Platform::current().font_stack(FontFamily::Display);
+//! assert!(!stack.is_empty());
+//! ```
+//!
+//! ## baseline MD3 vs M3 Expressive 差异清单
+//!
+//! 「M3 Expressive」不是「M3 换皮」——它真的加了一批令牌。本 crate 两代都提供，差异如下
+//! （来源等级：**A** = androidx 源码 / 官方 token 文件；**B** = m3.material.io 文档表格；**C** = 社区转述）。
+//!
+//! | 领域 | baseline MD3 | M3 Expressive 新增/不同 | 本 crate 落点 | 等级 |
+//! |---|---|---|---|---|
+//! | 排版 | 15 档 type role，只有 Regular/Medium 两种字重档 | **每档多一条 `*Emphasized`**：字号/行高不变，字重升到 Medium(500) 或 Bold(700)，字距按表微调（display-large −0.2→0、body-large 0.5→0.15、title-medium 0.2→0.15、body-medium 0.2→0.25） | [`typography::TypeRole::emphasized`]（官方值）；[`typography::TypeRole::emphasized_simplified`] 是我们的「只加一档字重」简化规则，**非官方** | A |
+//! | 形状 | ExtraSmall 4 / Small 8 / Medium 12 / Large 16 / **ExtraLarge 28** / Full | 多出 **LargeIncreased 20 / ExtraLargeIncreased 32 / ExtraExtraLarge 48**，并引入 **shape morph**（按下/选中时档位之间弹性过渡） | [`shape::ShapeScale`]（10 档）+ [`shape::ShapeMorph`] + [`component_map`] 的 `morph` 列 | A |
+//! | 动效 | 16 档 duration + 7 条 cubic-bezier easing（时间驱动） | 把弹簧打包成 **standard / expressive 两套方案**，每套各有 spatial（位移，会回弹）与 effects（颜色/透明度，不回弹）× fast/default/slow。standard spatial ζ=0.9（k 1400/700/300），expressive spatial ζ=0.6~0.8（k 800/380/200），effects 两套同值 ζ=1.0（k 3800/1600/800） | [`motion::spring`] 的 **方案 × 类别 × 速度**二维表（12 格，`StandardMotionTokens`/`ExpressiveMotionTokens` 原值）+ 9 个具名常量；duration/easing 两代共用 | A |
+//! | 组件尺寸 | 触控目标 48dp（无障碍下限本来就是 48） | Expressive 把按钮/列表的整体节奏放大（列表项 56/72/88），并明确 48dp 为**可点下限** | [`spacing::LayoutMetrics::DESKTOP`]：`touch_target = 48`（照规范）+ `control_height = 40`（可见高度，上下各 4px 内边距凑满 48）+ `row_height`/`nav_item_height` = 44、`titlebar_height` = 48（M63 §1.4+R13 的桌面档） | A/B |
+//! | 字体 | 只有 400/500/700 的「概念」字重，没规定字体族要覆盖几档 | Expressive 的强调档**真的会要 700**（label-*、title-medium/small），中文字体覆盖差异巨大：雅黑只有 400/700（无 500）、苹方到 600 断（无 700）、Noto/思源可变字体全覆盖 | [`typography::FontFace`] 的 `WeightCoverage`（可变区间 / 静态表）+ [`typography::Platform::resolve_weight`] 纯函数给出「原生 / 最近档 / 合成加粗」三档结论 | B |
+//! | 色彩 | 49 个角色（primary/secondary/tertiary/error 族、surface-container 系、`*-fixed*` 系、outline、inverse、scrim/shadow） | **没有新增颜色角色**；变化在用法：surface-container 系（Lowest…Highest）取代旧的 elevation tint 叠色，表达层级 | [`color::Role`] 全 49 个；[`elevation::Elevation::surface_role`] 给出层级映射，`deprecated_tint_alpha` 保留旧口径作对照 | A |
+//! | 高程 | Level0..5 = 0/1/3/6/8/12dp | 数值不变；组件默认值不同（卡片 L0、菜单 L2、对话框 L3，见 [`component_map`]） | [`elevation::Elevation`] | A |
+//!
+//! ### 两条由此衍生的项目纪律
+//!
+//! 1. **shape morph 是克制的状态信号，不是每屏装饰**：Expressive 官方鼓励「形状即状态」，但
+//!    桌面端信息密度高，圆角到处变会显得凌乱（社区已有人批评控制中心这么做）。本项目的约束是
+//!    **一屏最多 1 处形变、且只用于状态切换信号**；静态元素一律用 [`shape::ShapeScale`] 的固定档。
+//!    [`component_map`] 的 `morph` 列就是允许清单——不在表里的组件不许自己加形变。
+//! 2. **中文字重必须真的有三档**：Expressive 的 700 落在中文字体上，雅黑缺 500、苹方缺 700，
+//!    缺档就走「合成加粗」= 观感廉价。所以字体栈带 `WeightCoverage`，并在
+//!    [`typography::Platform::resolve_weight`] 里把降级路径显式化（合成加粗是最后一档）。
+//!
+//! 已知与文档的 0.05px 级差异：Compose 这一代 `TypeScaleTokens` 的 tracking 与 m3.material.io
+//! 网页表格不同（display-large −0.2 vs −0.25、body-medium 0.2 vs 0.25、title-medium 0.2 vs 0.15），
+//! 本项目**跟 Compose**（那是真正渲染出来的值，A 级）。
+//!
+//! ## 未支持的官方能力（gap 登记，不要以为已经有了）
+//!
+//! - **对比度等级**：Android 16 的「默认 / 中 / 高」三档对比度本 crate **不支持**。将来扩法是
+//!   **按等级偏移角色 tone 表**（例如高对比把 `on-*` 与承载色的 tone 差拉大 5~10），
+//!   而不是新增一批角色——`Role` 的数量保持 49 不变，`Scheme` 多一个 `contrast_level` 维度。
+//!   （M63 的 G4 只说「高对比模式走 CPU 档」，那是渲染档位，不等价于支持对比度等级。）
+//! - **动态壁纸取色**：M3 的多色种子派生（一张图出 4 个 source color、`*_container` 各自换色相）
+//!   未实现。本模块只取**一个**主色种子（D38 的产品口径：整套主题一个强调色），
+//!   实现落在 [`palette`]。
+//! - **M3 的 elevation tint 叠色**：现行 M3 已改用 surface-container 表达层级，旧的
+//!   `deprecated_tint_alpha()` 只为读旧稿保留。
+
+#![forbid(unsafe_code)]
+
+pub mod color;
+pub mod component_map;
+pub mod elevation;
+pub mod icons;
+pub mod motion;
+pub mod palette;
+pub mod shape;
+pub mod spacing;
+pub mod typography;
+
+pub use color::{Color, Role, Scheme, SchemeFlavor};
+pub use motion::MotionScale;
+pub use palette::{Card, CardKey, Level as SourceLevel, Provenance, Seed};
+pub use spacing::stroke;
+pub use typography::TypeRole;
+
+/// 设计令牌的整体入口：一份「当前该长什么样」的聚合快照。
+///
+/// iced 适配层只持有这个结构（深浅切换 = 重新 `DesignTokens::baseline(mode)`），
+/// 不要在适配层里缓存散装色值——那样深浅热切会有一半画对一半画错。
+#[derive(Debug, Clone, Copy)]
+pub struct DesignTokens {
+    /// 当前深浅模式。
+    pub flavor: SchemeFlavor,
+    /// 当前模式的 M3 语义色角色全表。
+    pub colors: Scheme,
+    /// 动效时长的全局缩放（`1.0` = 标准；用户关掉动画时适配层传 `0.0`）。
+    pub motion_scale: MotionScale,
+}
+
+impl DesignTokens {
+    /// 按模式给一套**产品默认**令牌：种子 `#3C8DBC`（M70 ④ 天蓝，用户 2026-11-01 拍板）
+    /// + 中性彩度 12，即 `color::palettes::DEFAULT_SEED` / `DEFAULT_NEUTRAL_CHROMA`。
+    ///
+    /// 想要**官方 M3 baseline** 口径（种子 `#6750A4` + 中性彩度 6 / neutral-variant 8）请走
+    /// `color::Scheme::official_baseline(flavor)`——两条路径的算法完全相同，只差入参。
+    pub fn baseline(flavor: SchemeFlavor) -> Self {
+        Self {
+            flavor,
+            colors: Scheme::baseline(flavor),
+            motion_scale: MotionScale::STANDARD,
+        }
+    }
+
+    /// 按用户强调色重建一套令牌（表面中性色仍走 baseline，强调色只驱动 primary/secondary/tertiary）。
+    pub fn with_accent(flavor: SchemeFlavor, accent: Color) -> Self {
+        Self {
+            flavor,
+            colors: Scheme::from_accent(flavor, accent),
+            motion_scale: MotionScale::STANDARD,
+        }
+    }
+
+    /// 便捷取色：`tokens.color(Role::Surface)`。
+    pub fn color(&self, role: Role) -> Color {
+        self.colors.get(role)
+    }
+}
diff --git a/crates/design/src/motion/mod.rs b/crates/design/src/motion/mod.rs
new file mode 100644
index 0000000..df59e11
--- /dev/null
+++ b/crates/design/src/motion/mod.rs
@@ -0,0 +1,308 @@
+//! 动效令牌：时长、缓动（可采样）、M3 Expressive 弹簧参数。
+//!
+//! 三件东西分开表达，因为适配层要的接口不同：
+//! - [`DurationToken`]：M3 的 short/medium/long/extra-long 十六档，给「固定时长 + easing」用；
+//! - [`Easing`]：cubic-bezier 曲线，纯函数采样（适配层自己决定帧率）；
+//! - [`Spring`]（见 [`spring`]）：Expressive 的物理参数（stiffness/damping/mass），
+//!   可用于实时求解或预估时长。
+//!
+//! **CPU / 减少动效路径**：把 [`MotionScale`] 设成 [`MotionScale::NONE`]，
+//! 所有时长归零、`Easing::sample` 仍返回 0/1 端值（适配层按 `t >= 1` 直接落终态）。
+
+mod spring;
+
+pub use spring::{
+    spring, MotionScale, MotionSchemeKind, Spring, SpringCategory, SpringSpeed,
+    SPRING_EFFECTS_DEFAULT, SPRING_EFFECTS_FAST, SPRING_EFFECTS_SLOW,
+    SPRING_EXPRESSIVE_SPATIAL_DEFAULT, SPRING_EXPRESSIVE_SPATIAL_FAST,
+    SPRING_EXPRESSIVE_SPATIAL_SLOW, SPRING_STANDARD_SPATIAL_DEFAULT, SPRING_STANDARD_SPATIAL_FAST,
+    SPRING_STANDARD_SPATIAL_SLOW,
+};
+
+/// 动效时长档位（M3 动效令牌，单位毫秒）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum DurationToken {
+    /// 50ms：最小状态回弹。
+    Short1,
+    /// 100ms：小图标/勾选。
+    Short2,
+    /// 150ms：开关、小尺寸 fade。
+    Short3,
+    /// 200ms：按钮状态、hover。
+    Short4,
+    /// 250ms：小卡片展开。
+    Medium1,
+    /// 300ms：导航指示条、tab 切换。
+    Medium2,
+    /// 350ms：卡片展开、列表重排。
+    Medium3,
+    /// 400ms：面板开合。
+    Medium4,
+    /// 450ms：页面切换。
+    Long1,
+    /// 500ms：大面板进出。
+    Long2,
+    /// 550ms：全屏浮层。
+    Long3,
+    /// 600ms：对话框进出。
+    Long4,
+    /// 700ms：结构化过渡。
+    ExtraLong1,
+    /// 800ms：结构化过渡。
+    ExtraLong2,
+    /// 900ms：结构化过渡。
+    ExtraLong3,
+    /// 1000ms：整屏形变（shape morph 的慢档）。
+    ExtraLong4,
+}
+
+impl DurationToken {
+    /// 毫秒值。
+    pub const fn ms(self) -> u32 {
+        match self {
+            DurationToken::Short1 => 50,
+            DurationToken::Short2 => 100,
+            DurationToken::Short3 => 150,
+            DurationToken::Short4 => 200,
+            DurationToken::Medium1 => 250,
+            DurationToken::Medium2 => 300,
+            DurationToken::Medium3 => 350,
+            DurationToken::Medium4 => 400,
+            DurationToken::Long1 => 450,
+            DurationToken::Long2 => 500,
+            DurationToken::Long3 => 550,
+            DurationToken::Long4 => 600,
+            DurationToken::ExtraLong1 => 700,
+            DurationToken::ExtraLong2 => 800,
+            DurationToken::ExtraLong3 => 900,
+            DurationToken::ExtraLong4 => 1000,
+        }
+    }
+
+    /// 稳定字符串名（`short1` … `extra-long4`），写配置与日志用。
+    pub const fn name(self) -> &'static str {
+        match self {
+            DurationToken::Short1 => "short1",
+            DurationToken::Short2 => "short2",
+            DurationToken::Short3 => "short3",
+            DurationToken::Short4 => "short4",
+            DurationToken::Medium1 => "medium1",
+            DurationToken::Medium2 => "medium2",
+            DurationToken::Medium3 => "medium3",
+            DurationToken::Medium4 => "medium4",
+            DurationToken::Long1 => "long1",
+            DurationToken::Long2 => "long2",
+            DurationToken::Long3 => "long3",
+            DurationToken::Long4 => "long4",
+            DurationToken::ExtraLong1 => "extra-long1",
+            DurationToken::ExtraLong2 => "extra-long2",
+            DurationToken::ExtraLong3 => "extra-long3",
+            DurationToken::ExtraLong4 => "extra-long4",
+        }
+    }
+}
+
+/// 三次贝塞尔缓动曲线（CSS `cubic-bezier` 同样的参数含义）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct CubicBezier {
+    /// 控制点 1 的 x（0..1）。
+    pub x1: f32,
+    /// 控制点 1 的 y。
+    pub y1: f32,
+    /// 控制点 2 的 x（0..1）。
+    pub x2: f32,
+    /// 控制点 2 的 y。
+    pub y2: f32,
+}
+
+impl CubicBezier {
+    /// 线性。
+    pub const LINEAR: Self = Self {
+        x1: 0.0,
+        y1: 0.0,
+        x2: 1.0,
+        y2: 1.0,
+    };
+
+    /// 给定时间参数 `t`（0..1），返回进度（0..1，标准曲线不越界）。
+    pub fn sample(self, t: f32) -> f32 {
+        let t = t.clamp(0.0, 1.0);
+        if t == 0.0 || t == 1.0 {
+            return t;
+        }
+        // 二分求 x(s) = t 的曲线参数 s，再取 y(s)。
+        let mut lo = 0.0_f32;
+        let mut hi = 1.0_f32;
+        let mut s = t;
+        for _ in 0..24 {
+            s = 0.5 * (lo + hi);
+            let x = bezier_axis(self.x1, self.x2, s);
+            if x < t {
+                lo = s;
+            } else {
+                hi = s;
+            }
+        }
+        bezier_axis(self.y1, self.y2, s)
+    }
+}
+
+/// 一维三次贝塞尔：端点固定为 0/1，控制点为 `c1`/`c2`。
+fn bezier_axis(c1: f32, c2: f32, s: f32) -> f32 {
+    let u = 1.0 - s;
+    3.0 * u * u * s * c1 + 3.0 * u * s * s * c2 + s * s * s
+}
+
+/// M3 缓动档位（值取自 Material 动效令牌）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum Easing {
+    /// 线性（进度指示器）。
+    Linear,
+    /// 标准：起止都平滑。
+    Standard,
+    /// 标准减速：进场（出现在屏幕上）。
+    StandardDecelerate,
+    /// 标准加速：退场。
+    StandardAccelerate,
+    /// 强调：注意力转移的主曲线。
+    Emphasized,
+    /// 强调减速：强调类进场。
+    EmphasizedDecelerate,
+    /// 强调加速：强调类退场。
+    EmphasizedAccelerate,
+}
+
+impl Easing {
+    /// 曲线参数。
+    pub const fn curve(self) -> CubicBezier {
+        match self {
+            Easing::Linear => CubicBezier::LINEAR,
+            Easing::Standard | Easing::Emphasized => CubicBezier {
+                x1: 0.2,
+                y1: 0.0,
+                x2: 0.0,
+                y2: 1.0,
+            },
+            Easing::StandardDecelerate => CubicBezier {
+                x1: 0.0,
+                y1: 0.0,
+                x2: 0.0,
+                y2: 1.0,
+            },
+            Easing::StandardAccelerate => CubicBezier {
+                x1: 0.3,
+                y1: 0.0,
+                x2: 1.0,
+                y2: 1.0,
+            },
+            Easing::EmphasizedDecelerate => CubicBezier {
+                x1: 0.05,
+                y1: 0.7,
+                x2: 0.1,
+                y2: 1.0,
+            },
+            Easing::EmphasizedAccelerate => CubicBezier {
+                x1: 0.3,
+                y1: 0.0,
+                x2: 0.8,
+                y2: 0.15,
+            },
+        }
+    }
+
+    /// 采样：`t` 0..1 → 进度 0..1。
+    pub fn sample(self, t: f32) -> f32 {
+        self.curve().sample(t)
+    }
+
+    /// 该曲线搭配的常用时长（我们的组件映射口径，非规范值）。
+    pub const fn default_duration(self) -> DurationToken {
+        match self {
+            Easing::Linear => DurationToken::Long2,
+            _ => DurationToken::Medium2,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const ALL_EASINGS: [Easing; 7] = [
+        Easing::Linear,
+        Easing::Standard,
+        Easing::StandardDecelerate,
+        Easing::StandardAccelerate,
+        Easing::Emphasized,
+        Easing::EmphasizedDecelerate,
+        Easing::EmphasizedAccelerate,
+    ];
+
+    #[test]
+    fn durations_are_monotone() {
+        let ladder = [
+            DurationToken::Short1,
+            DurationToken::Short2,
+            DurationToken::Short3,
+            DurationToken::Short4,
+            DurationToken::Medium1,
+            DurationToken::Medium2,
+            DurationToken::Medium3,
+            DurationToken::Medium4,
+            DurationToken::Long1,
+            DurationToken::Long2,
+            DurationToken::Long3,
+            DurationToken::Long4,
+            DurationToken::ExtraLong1,
+            DurationToken::ExtraLong2,
+            DurationToken::ExtraLong3,
+            DurationToken::ExtraLong4,
+        ];
+        assert_eq!(ladder.len(), 16);
+        for pair in ladder.windows(2) {
+            assert!(pair[0].ms() < pair[1].ms());
+        }
+        assert_eq!(DurationToken::Short1.ms(), 50);
+        assert_eq!(DurationToken::ExtraLong4.ms(), 1000);
+        // 名字唯一
+        let mut names = std::collections::BTreeSet::new();
+        for token in ladder {
+            assert!(names.insert(token.name()), "时长名重复：{}", token.name());
+        }
+    }
+
+    #[test]
+    fn easing_hits_endpoints_and_stays_in_range() {
+        for easing in ALL_EASINGS {
+            assert!(
+                (easing.sample(0.0) - 0.0).abs() < 1.0e-6,
+                "{easing:?} 起点不为 0"
+            );
+            assert!(
+                (easing.sample(1.0) - 1.0).abs() < 1.0e-6,
+                "{easing:?} 终点不为 1"
+            );
+            let mut prev = 0.0;
+            for step in 1..=20 {
+                let v = easing.sample(step as f32 / 20.0);
+                assert!((-0.001..=1.001).contains(&v), "{easing:?} 采样越界：{v}");
+                assert!(v + 1.0e-3 >= prev, "{easing:?} 采样非单调：{prev} → {v}");
+                prev = v;
+            }
+        }
+    }
+
+    #[test]
+    fn emphasized_decelerate_is_faster_early_than_accelerate() {
+        let early_decel = Easing::EmphasizedDecelerate.sample(0.25);
+        let early_accel = Easing::EmphasizedAccelerate.sample(0.25);
+        assert!(early_decel > early_accel);
+    }
+
+    #[test]
+    fn default_durations_are_registered_tokens() {
+        for easing in ALL_EASINGS {
+            assert!(easing.default_duration().ms() >= 250);
+        }
+    }
+}
diff --git a/crates/design/src/motion/spring.rs b/crates/design/src/motion/spring.rs
new file mode 100644
index 0000000..6baa0c0
--- /dev/null
+++ b/crates/design/src/motion/spring.rs
@@ -0,0 +1,380 @@
+//! 弹簧参数（M3 Expressive 动效的物理表达）与动效时长缩放。
+//!
+//! **来源 A 级**：`androidx.compose.material3.tokens.ExpressiveMotionTokens`（v0_14_0）给出六组
+//! `Spring{Damping, Stiffness}`——注意 Compose 的 `Damping` 是**阻尼比 ζ**（不是绝对阻尼系数），
+//! 所以本模块的 [`Spring`] 也按 (stiffness, damping_ratio, mass) 存，两者可直接对照。
+//! 阶跃响应用标准二阶系统闭式解（欠阻尼 / 临界 / 过阻尼三分支），是纯数学、无状态。
+
+/// 弹簧参数（Compose 口径：刚度 + 阻尼比 + 质量）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Spring {
+    /// 刚度 k（越大越快）。
+    pub stiffness: f32,
+    /// 阻尼比 ζ（1.0 = 临界阻尼，< 1 会轻微弹过）。
+    pub damping_ratio: f32,
+    /// 质量 m。
+    pub mass: f32,
+}
+
+impl Spring {
+    /// 按 M3 令牌口径构造（刚度 + 阻尼比 + 质量）。
+    pub const fn from_ratio(stiffness: f32, damping_ratio: f32, mass: f32) -> Self {
+        Self {
+            stiffness,
+            damping_ratio,
+            mass,
+        }
+    }
+
+    /// 自然角频率 ωn（rad/s）。
+    pub fn natural_frequency(self) -> f32 {
+        (self.stiffness / self.mass).sqrt()
+    }
+
+    /// 绝对阻尼系数 c = 2·ζ·√(k·m)（需要喂给「阻尼系数」式积分器时用）。
+    pub fn damping_coefficient(self) -> f32 {
+        2.0 * self.damping_ratio * (self.stiffness * self.mass).sqrt()
+    }
+
+    /// 阶跃响应：`t_ms` 毫秒后的进度（0..1，欠阻尼时会轻微超过 1 = 回弹）。
+    pub fn sample(self, t_ms: f32) -> f32 {
+        if t_ms <= 0.0 {
+            return 0.0;
+        }
+        let t = t_ms / 1000.0;
+        let wn = self.natural_frequency();
+        let zeta = self.damping_ratio;
+        if wn <= 0.0 {
+            return 1.0;
+        }
+        if zeta < 1.0 {
+            let wd = wn * (1.0 - zeta * zeta).sqrt();
+            let decay = (-zeta * wn * t).exp();
+            1.0 - decay * ((wd * t).cos() + (zeta * wn / wd) * (wd * t).sin())
+        } else if (zeta - 1.0).abs() < 1.0e-4 {
+            let decay = (-wn * t).exp();
+            1.0 - decay * (1.0 + wn * t)
+        } else {
+            let root = (zeta * zeta - 1.0).sqrt();
+            let r1 = -wn * (zeta - root);
+            let r2 = -wn * (zeta + root);
+            let denom = r2 - r1;
+            if denom.abs() < f32::EPSILON {
+                return 1.0;
+            }
+            1.0 - (r2 * (r1 * t).exp() - r1 * (r2 * t).exp()) / denom
+        }
+    }
+
+    /// 收敛到 `threshold`（0.1% 是常用的「停下来」判定）所需毫秒数。
+    pub fn settle_ms(self, threshold: f32) -> f32 {
+        let wn = self.natural_frequency();
+        let zeta = self.damping_ratio;
+        if wn <= 0.0 {
+            return 0.0;
+        }
+        let thr = threshold.clamp(1.0e-6, 0.5);
+        let seconds = if zeta < 1.0 {
+            let wd = (1.0 - zeta * zeta).sqrt().max(1.0e-4);
+            -(thr * wd).ln() / (zeta * wn)
+        } else if (zeta - 1.0).abs() < 1.0e-4 {
+            -(thr).ln() / wn
+        } else {
+            let root = (zeta * zeta - 1.0).sqrt();
+            let slow = wn * (zeta - root);
+            -(thr).ln() / slow
+        };
+        (seconds * 1000.0).max(0.0)
+    }
+}
+
+/// 动效方案（Expressive 把弹簧打包成 standard / expressive **两套**，不是一组）。
+///
+/// - [`MotionSchemeKind::Standard`]：保守、几乎不弹（spatial ζ=0.9）；
+/// - [`MotionSchemeKind::Expressive`]：D26 的视觉基线，回弹明显（spatial ζ=0.6~0.8）。
+///
+/// `effects`（透明度/颜色类）在两套方案里数值相同——效应类不该有可见回弹。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum MotionSchemeKind {
+    /// 标准方案（保守）。
+    Standard,
+    /// Expressive 方案（本项目默认）。
+    Expressive,
+}
+
+/// 弹簧类别：空间类管**位移/尺寸**，效应类管**颜色/透明度**。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum SpringCategory {
+    /// 位移/尺寸（会产生可见回弹）。
+    Spatial,
+    /// 颜色/透明度（不允许过冲）。
+    Effects,
+}
+
+/// 弹簧速度档。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum SpringSpeed {
+    /// 快速：hover/press、小元素。
+    Fast,
+    /// 默认：面板、卡片、按下形变。
+    Default,
+    /// 慢速：大位移（>120px 的面板/抽屉）。
+    Slow,
+}
+
+/// 二维表查询：`方案 × 类别 × 速度 → 弹簧`（A 级：`StandardMotionTokens` 与
+/// `ExpressiveMotionTokens`，经 `MotionScheme.standard()/expressive()` 组装）。
+pub const fn spring(
+    scheme: MotionSchemeKind,
+    category: SpringCategory,
+    speed: SpringSpeed,
+) -> Spring {
+    use MotionSchemeKind::{Expressive, Standard};
+    use SpringCategory::{Effects, Spatial};
+    use SpringSpeed::{Default, Fast, Slow};
+    match (scheme, category, speed) {
+        (Standard, Spatial, Fast) => Spring::from_ratio(1400.0, 0.9, 1.0),
+        (Standard, Spatial, Default) => Spring::from_ratio(700.0, 0.9, 1.0),
+        (Standard, Spatial, Slow) => Spring::from_ratio(300.0, 0.9, 1.0),
+        (Expressive, Spatial, Fast) => Spring::from_ratio(800.0, 0.6, 1.0),
+        (Expressive, Spatial, Default) => Spring::from_ratio(380.0, 0.8, 1.0),
+        (Expressive, Spatial, Slow) => Spring::from_ratio(200.0, 0.8, 1.0),
+        // effects 两套同值：ζ=1.0（临界阻尼，不过冲）。
+        (_, Effects, Fast) => Spring::from_ratio(3800.0, 1.0, 1.0),
+        (_, Effects, Default) => Spring::from_ratio(1600.0, 1.0, 1.0),
+        (_, Effects, Slow) => Spring::from_ratio(800.0, 1.0, 1.0),
+    }
+}
+
+/// 标准方案 · 空间 · 快速。
+pub const SPRING_STANDARD_SPATIAL_FAST: Spring = spring(
+    MotionSchemeKind::Standard,
+    SpringCategory::Spatial,
+    SpringSpeed::Fast,
+);
+/// 标准方案 · 空间 · 默认。
+pub const SPRING_STANDARD_SPATIAL_DEFAULT: Spring = spring(
+    MotionSchemeKind::Standard,
+    SpringCategory::Spatial,
+    SpringSpeed::Default,
+);
+/// 标准方案 · 空间 · 慢速。
+pub const SPRING_STANDARD_SPATIAL_SLOW: Spring = spring(
+    MotionSchemeKind::Standard,
+    SpringCategory::Spatial,
+    SpringSpeed::Slow,
+);
+/// Expressive 方案 · 空间 · 快速（D26 基线的默认选择）。
+pub const SPRING_EXPRESSIVE_SPATIAL_FAST: Spring = spring(
+    MotionSchemeKind::Expressive,
+    SpringCategory::Spatial,
+    SpringSpeed::Fast,
+);
+/// Expressive 方案 · 空间 · 默认：面板、卡片、按下形变。
+pub const SPRING_EXPRESSIVE_SPATIAL_DEFAULT: Spring = spring(
+    MotionSchemeKind::Expressive,
+    SpringCategory::Spatial,
+    SpringSpeed::Default,
+);
+/// Expressive 方案 · 空间 · 慢速：大位移（>120px）。
+pub const SPRING_EXPRESSIVE_SPATIAL_SLOW: Spring = spring(
+    MotionSchemeKind::Expressive,
+    SpringCategory::Spatial,
+    SpringSpeed::Slow,
+);
+/// 效应类 · 快速（两套方案同值）：hover/press 颜色。
+pub const SPRING_EFFECTS_FAST: Spring = spring(
+    MotionSchemeKind::Expressive,
+    SpringCategory::Effects,
+    SpringSpeed::Fast,
+);
+/// 效应类 · 默认（两套方案同值）。
+pub const SPRING_EFFECTS_DEFAULT: Spring = spring(
+    MotionSchemeKind::Expressive,
+    SpringCategory::Effects,
+    SpringSpeed::Default,
+);
+/// 效应类 · 慢速（两套方案同值）。
+pub const SPRING_EFFECTS_SLOW: Spring = spring(
+    MotionSchemeKind::Expressive,
+    SpringCategory::Effects,
+    SpringSpeed::Slow,
+);
+
+/// 动效时长的全局缩放（用户「减少动效」/CPU 路径关动画时用）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct MotionScale {
+    factor: f32,
+}
+
+impl MotionScale {
+    /// 标准（1.0）。
+    pub const STANDARD: MotionScale = MotionScale { factor: 1.0 };
+    /// 关闭动效（时长归零；适配层应直接落终态）。
+    pub const NONE: MotionScale = MotionScale { factor: 0.0 };
+    /// 半速（弱动效机器/低帧率兜底）。
+    pub const HALF: MotionScale = MotionScale { factor: 0.5 };
+
+    /// 自定义缩放（夹取到 0.0..=1.0；不放大，避免慢到不可用）。
+    pub fn new(factor: f32) -> Self {
+        Self {
+            factor: factor.clamp(0.0, 1.0),
+        }
+    }
+
+    /// 缩放系数。
+    pub fn factor(self) -> f32 {
+        self.factor
+    }
+
+    /// 是否完全关闭（适配层据此跳过动画）。
+    pub fn is_off(self) -> bool {
+        self.factor <= 0.0
+    }
+
+    /// 把某一档时长换算成实际毫秒。
+    pub fn ms(self, token: super::DurationToken) -> f32 {
+        token.ms() as f32 * self.factor
+    }
+
+    /// 把弹簧的收敛时间换算成实际毫秒。
+    pub fn spring_ms(self, spring: Spring) -> f32 {
+        spring.settle_ms(0.001) * self.factor
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::motion::DurationToken;
+
+    const PRESETS: [Spring; 9] = [
+        SPRING_STANDARD_SPATIAL_FAST,
+        SPRING_STANDARD_SPATIAL_DEFAULT,
+        SPRING_STANDARD_SPATIAL_SLOW,
+        SPRING_EXPRESSIVE_SPATIAL_FAST,
+        SPRING_EXPRESSIVE_SPATIAL_DEFAULT,
+        SPRING_EXPRESSIVE_SPATIAL_SLOW,
+        SPRING_EFFECTS_FAST,
+        SPRING_EFFECTS_DEFAULT,
+        SPRING_EFFECTS_SLOW,
+    ];
+
+    #[test]
+    fn every_cell_of_the_two_dimensional_table_resolves() {
+        for scheme in [MotionSchemeKind::Standard, MotionSchemeKind::Expressive] {
+            for category in [SpringCategory::Spatial, SpringCategory::Effects] {
+                for speed in [SpringSpeed::Fast, SpringSpeed::Default, SpringSpeed::Slow] {
+                    let spring = spring(scheme, category, speed);
+                    assert!(spring.stiffness > 0.0);
+                    assert!(spring.damping_ratio > 0.0);
+                }
+            }
+        }
+        // effects 两套方案同值（效应类不该有可见回弹差异）。
+        for speed in [SpringSpeed::Fast, SpringSpeed::Default, SpringSpeed::Slow] {
+            assert_eq!(
+                spring(MotionSchemeKind::Standard, SpringCategory::Effects, speed),
+                spring(MotionSchemeKind::Expressive, SpringCategory::Effects, speed)
+            );
+        }
+        // expressive 的空间类更弹（阻尼比更低）。
+        for speed in [SpringSpeed::Fast, SpringSpeed::Default, SpringSpeed::Slow] {
+            assert!(
+                spring(MotionSchemeKind::Expressive, SpringCategory::Spatial, speed).damping_ratio
+                    < spring(MotionSchemeKind::Standard, SpringCategory::Spatial, speed)
+                        .damping_ratio
+            );
+        }
+    }
+
+    #[test]
+    fn spring_presets_behave() {
+        for spring in PRESETS {
+            assert_eq!(spring.sample(0.0), 0.0);
+            let settle = spring.settle_ms(0.001);
+            assert!(
+                (60.0..1500.0).contains(&settle),
+                "收敛时间 {settle}ms 不合理（k={} ζ={}）",
+                spring.stiffness,
+                spring.damping_ratio
+            );
+            let end = spring.sample(settle);
+            assert!((end - 1.0).abs() < 0.01, "收敛后应回到 1.0，实测 {end}");
+        }
+    }
+
+    #[test]
+    fn effects_presets_are_critically_damped_and_never_overshoot() {
+        for spring in [
+            SPRING_EFFECTS_FAST,
+            SPRING_EFFECTS_DEFAULT,
+            SPRING_EFFECTS_SLOW,
+        ] {
+            assert!((spring.damping_ratio - 1.0).abs() < 1.0e-6);
+            for step in 1..=60 {
+                let v = spring.sample(step as f32 * 5.0);
+                assert!(v <= 1.0 + 1.0e-3, "效应类弹簧不应过冲：{v}");
+            }
+        }
+    }
+
+    #[test]
+    fn spatial_presets_overdamp_into_settle_without_wild_overshoot() {
+        for spring in [
+            SPRING_EXPRESSIVE_SPATIAL_FAST,
+            SPRING_EXPRESSIVE_SPATIAL_DEFAULT,
+            SPRING_EXPRESSIVE_SPATIAL_SLOW,
+        ] {
+            assert!(
+                spring.damping_ratio < 1.0,
+                "空间类弹簧欠阻尼（允许轻微过冲）"
+            );
+            let mut peak: f32 = 0.0;
+            for step in 1..=200 {
+                peak = peak.max(spring.sample(step as f32 * 2.0));
+            }
+            assert!(peak < 1.15, "过冲 {peak} 太大");
+        }
+    }
+
+    #[test]
+    fn critically_damped_spring_does_not_overshoot() {
+        let wn = SPRING_EXPRESSIVE_SPATIAL_DEFAULT.natural_frequency();
+        let critical = Spring::from_ratio(wn * wn, 1.0, 1.0);
+        for step in 1..=40 {
+            let v = critical.sample(step as f32 * 5.0);
+            assert!(v <= 1.0 + 1.0e-3, "临界阻尼不应过冲：{v}");
+        }
+    }
+
+    #[test]
+    fn overdamped_spring_converges_slowly_without_overshoot() {
+        let wn = SPRING_EXPRESSIVE_SPATIAL_DEFAULT.natural_frequency();
+        let over = Spring::from_ratio(wn * wn, 2.0, 1.0);
+        let settle = over.settle_ms(0.001);
+        assert!((over.sample(settle) - 1.0).abs() < 0.01);
+        for step in 1..=40 {
+            assert!(over.sample(step as f32 * 10.0) <= 1.0 + 1.0e-3);
+        }
+    }
+
+    #[test]
+    fn damping_coefficient_matches_ratio() {
+        let spring = SPRING_EXPRESSIVE_SPATIAL_DEFAULT;
+        let c = spring.damping_coefficient();
+        let zeta = c / (2.0 * (spring.stiffness * spring.mass).sqrt());
+        assert!((zeta - spring.damping_ratio).abs() < 1.0e-5);
+    }
+
+    #[test]
+    fn motion_scale_scales_or_kills_duration() {
+        assert_eq!(MotionScale::STANDARD.ms(DurationToken::Medium2), 300.0);
+        assert_eq!(MotionScale::HALF.ms(DurationToken::Medium2), 150.0);
+        assert_eq!(MotionScale::NONE.ms(DurationToken::Medium2), 0.0);
+        assert!(MotionScale::NONE.is_off());
+        assert_eq!(MotionScale::new(5.0).factor(), 1.0);
+        assert_eq!(MotionScale::new(-1.0).factor(), 0.0);
+        assert!(MotionScale::STANDARD.spring_ms(SPRING_EXPRESSIVE_SPATIAL_DEFAULT) > 0.0);
+    }
+}
diff --git a/crates/design/src/palette/card.rs b/crates/design/src/palette/card.rs
new file mode 100644
index 0000000..30104aa
--- /dev/null
+++ b/crates/design/src/palette/card.rs
@@ -0,0 +1,340 @@
+//! 内置色卡（D38 第三级）：用户在「关闭莫奈取色」时手动选的那几张。
+//!
+//! ## `key` 是持久化键，命名就此定死
+//!
+//! 每张卡的 [`Card::key`] 会被写进用户设置（settings 里存字符串），**改了就等于把用户的选择
+//! 抹成出厂默认**。所以：
+//!
+//! - 只用小写 ASCII + 单段单词，不带动词、不带颜色数值（`sky`，不是 `blue_3c8dbc`）；
+//! - 显示名（[`Card::name`]）可以改、可以本地化，`key` 不许改；
+//! - 新卡只能**追加**，旧卡永不删除（删了老用户的选择会静默失效 → 见
+//!   [`CardKey::from_key`] 的回落口径）；
+//! - `card.rs` 的 `card_keys_are_stable_and_unique` 把 8 个 key 逐字钉住——谁改谁红
+//!   （测试就在本文件末尾的 `tests` 模块里，没有独立的 `palette/tests.rs`）。
+//!
+//! ## 换卡只换强调色：中性色相固定（D43）
+//!
+//! 八张卡共用**一个**中性色相 [`NEUTRAL_HUE_DEG`]（= 出厂默认种子 `#3C8DBC` 的 CAM16 色相
+//! 239.51°，出处见该常量的文档），中性彩度都取 [`DEFAULT_NEUTRAL_CHROMA`]（12，M70 的「浅冷」口径）。
+//! 于是这份契约是逐值可验的：
+//!
+//! - **表面与描边**（`surface` / `surface-container-*` / `background` / `inverse-surface` /
+//!   `outline` / `outline-variant` / `surface-variant`）**八张卡逐值相同**——切卡不动窗口底色；
+//! - **只有强调族**（`primary` / `secondary` / `tertiary` 及其 container、`on-*`、`inverse-primary`、
+//!   `*-fixed*`、`surface-tint`）跟着卡走；
+//! - **天蓝卡（出厂默认）与 [`crate::color::Scheme::baseline`] 逐值相同**：固定的中性色相本来
+//!   就等于天蓝档的中性色相，所以这是「沿用」而非「另选一个冷调」（M70 定案的不动点）。
+//!
+//! 为什么不再让中性色跟着种子染色：TonalSpot 下八张卡的中性色相 = 种子色相，浅色档 `surface`
+//! 实测 CAM16 彩度从 **1.29（rose）跨到 12.03（teal）**——tone 98 处暖相色域装不下彩度 12，
+//! 同一个「请求值」在暖相上只兑现 1.29。9 倍的底色跳变让用户在设置页逐张试色时觉得「每张卡
+//! 都像换了个应用」（M87 实测，D43 据此定案）。现在八张卡的 `surface` 是同一个色值，
+//! 那 9 倍差由 `tests/card_neutral.rs` 断言为 1 倍。
+//!
+//! ⚠️ **只对色卡路径成立**：动态取色（启动器背景图 / 桌面壁纸）仍然让中性色跟着图像种子染色，
+//! 那是用户要的 Monet 体验（D38）。见 [`super::resolve`] 的 `try_level`：两条路径刻意不同，
+//! 别「统一处理」（`tests/card_neutral.rs` 有反证用例）。
+//!
+//! ## 卡与取色的关系（D38）
+//!
+//! 取色成功时，**当前选中的卡仍然参与生成**，但只贡献中性**彩度**（表面色的浓淡）；
+//! 色相由图像种子决定。所以卡片不是「只在第三级才用到」的备胎，它的固定中性色相
+//! **不会**出现在取色方案里。
+
+use super::wcag;
+use crate::color::{
+    Color, Palettes, Scheme, SchemeFlavor, DEFAULT_NEUTRAL_CHROMA, NEUTRAL_HUE_DEG,
+};
+
+/// 一张内置色卡。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Card {
+    /// 持久化键（写进用户设置，**不许改**）。
+    pub key: &'static str,
+    /// 显示名（可改、可本地化）。
+    pub name: &'static str,
+    /// 种子色（只贡献色相；Tonal Spot 会把彩度收到 36）。
+    pub seed: Color,
+    /// 中性调色板彩度（表面色的浓淡；色相固定为 [`NEUTRAL_HUE_DEG`]，见模块文档的 D43 契约）。
+    pub neutral_chroma: f64,
+}
+
+impl Card {
+    /// 用这张卡生成一套方案（与取色路径同一条生成器，只差两处入参：中性色相固定为
+    /// [`NEUTRAL_HUE_DEG`]、强调色来自卡而不是图像）。
+    pub fn scheme(self, flavor: SchemeFlavor) -> Scheme {
+        Scheme::from_palettes(
+            &Palettes::accent_on_fixed_neutral(self.seed, NEUTRAL_HUE_DEG, self.neutral_chroma),
+            flavor,
+        )
+    }
+
+    /// 这张卡的 `on-primary` 对 `primary` 的实测对比度。
+    ///
+    /// 设置页可以直接显示成「对比度 {:.2}:1」。**2026-11 实测（8 张卡）**：
+    /// 浅色档 **6.43~6.49**、深色档 **7.70~7.75**——两种模式都远高于 WCAG AA 的 4.5:1。
+    ///
+    /// 这两个区间**被测试钉住**（不是口头声明）：`every_card_scheme_meets_wcag_aa` 对每张卡
+    /// 断言「下限 [`wcag::AA_TEXT`] + 落在上述区间内」，所以将来改种子/调色板常数把比值
+    /// 拖出区间会当场红——文档里的数字与测试同源。要改数值请连测试区间一起改。
+    pub fn primary_contrast(self, flavor: SchemeFlavor) -> f32 {
+        let scheme = self.scheme(flavor);
+        scheme.contrast(crate::color::Role::OnPrimary, crate::color::Role::Primary)
+    }
+}
+
+/// 全部内置色卡（下标 0 = 出厂默认）。
+///
+/// 色相在 CAM16 色环上大致均匀铺开（蓝 240 / 紫 299 / 绿 155 / 橙 65 / 红 10 / 青 185 /
+/// 暮蓝 ~275 / 橄榄绿 ~110），让用户「随便挑一张都不会撞色」。`palette::card` 的单测
+/// `cards_are_visually_distinct` 钉住「相邻色相间隔 ≥ 20°」。
+pub const CARDS: [Card; 8] = [
+    Card {
+        key: "sky",
+        name: "天蓝",
+        // M70 定案 ④（`palettes::DEFAULT_SEED` 同值）。改这张卡 = 改产品默认色，见 M70 文档。
+        seed: Color::rgb(0x3C, 0x8D, 0xBC),
+        neutral_chroma: DEFAULT_NEUTRAL_CHROMA,
+    },
+    Card {
+        key: "lavender",
+        name: "薰衣草紫",
+        // 官方 M3 baseline 种子，和 `Scheme::official_baseline` 同色，便于对照官方截图。
+        seed: Color::rgb(0x67, 0x50, 0xA4),
+        neutral_chroma: DEFAULT_NEUTRAL_CHROMA,
+    },
+    Card {
+        key: "forest",
+        name: "森林绿",
+        seed: Color::rgb(0x2E, 0x7D, 0x4F),
+        neutral_chroma: DEFAULT_NEUTRAL_CHROMA,
+    },
+    Card {
+        key: "amber",
+        name: "琥珀橙",
+        seed: Color::rgb(0xB2, 0x6A, 0x00),
+        neutral_chroma: DEFAULT_NEUTRAL_CHROMA,
+    },
+    Card {
+        key: "rose",
+        name: "玫瑰红",
+        seed: Color::rgb(0xB2, 0x3A, 0x48),
+        neutral_chroma: DEFAULT_NEUTRAL_CHROMA,
+    },
+    Card {
+        key: "teal",
+        name: "青碧",
+        seed: Color::rgb(0x00, 0x79, 0x6B),
+        neutral_chroma: DEFAULT_NEUTRAL_CHROMA,
+    },
+    Card {
+        key: "dusk",
+        name: "暮蓝",
+        seed: Color::rgb(0x4A, 0x5A, 0x9C),
+        neutral_chroma: DEFAULT_NEUTRAL_CHROMA,
+    },
+    Card {
+        key: "olive",
+        name: "橄榄绿",
+        // 刻意**没有**「纯灰/石板灰」卡：D40 已实测，零彩度种子的 CAM16 色相恒为 209.49°
+        // （不是「无色」，而是固定的青），极低彩度段色相还是噪声放大器。所以「想要无彩色界面」
+        // 不能靠一张灰卡实现——那需要一个饱和度/对比度维度（未来若做，是另一条轴，不是色卡）。
+        seed: Color::rgb(0x5F, 0x6B, 0x2E),
+        neutral_chroma: DEFAULT_NEUTRAL_CHROMA,
+    },
+];
+
+/// 出厂默认卡（首次启动、用户没选过卡时的那一张）。
+pub const DEFAULT_CARD: Card = CARDS[0];
+
+/// 色卡的类型化键（`Card::key` 的枚举形态）。
+///
+/// 加了它是因为「存字符串」这件事必须只有一处口径：设置读回来时走 [`CardKey::from_key`]，
+/// 写出去时走 [`CardKey::key`]，两边不会漂。新卡追加在末尾，**不重排**。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
+pub enum CardKey {
+    /// 天蓝（出厂默认，M70 ④）。
+    Sky,
+    /// 薰衣草紫（官方 M3 baseline）。
+    Lavender,
+    /// 森林绿。
+    Forest,
+    /// 琥珀橙。
+    Amber,
+    /// 玫瑰红。
+    Rose,
+    /// 青碧。
+    Teal,
+    /// 暮蓝。
+    Dusk,
+    /// 橄榄绿。
+    Olive,
+}
+
+impl CardKey {
+    /// 全部键（顺序与 [`CARDS`] 一致）。
+    pub const ALL: [CardKey; 8] = [
+        CardKey::Sky,
+        CardKey::Lavender,
+        CardKey::Forest,
+        CardKey::Amber,
+        CardKey::Rose,
+        CardKey::Teal,
+        CardKey::Dusk,
+        CardKey::Olive,
+    ];
+
+    /// 持久化键（与 [`Card::key`] 逐字相同）。
+    pub const fn key(self) -> &'static str {
+        CARDS[self.index()].key
+    }
+
+    /// 这张卡。
+    pub const fn card(self) -> Card {
+        CARDS[self.index()]
+    }
+
+    /// 显示名。
+    pub const fn name(self) -> &'static str {
+        CARDS[self.index()].name
+    }
+
+    const fn index(self) -> usize {
+        match self {
+            CardKey::Sky => 0,
+            CardKey::Lavender => 1,
+            CardKey::Forest => 2,
+            CardKey::Amber => 3,
+            CardKey::Rose => 4,
+            CardKey::Teal => 5,
+            CardKey::Dusk => 6,
+            CardKey::Olive => 7,
+        }
+    }
+
+    /// 从持久化键解析；**未知键返回 `None`**（调用方回落 [`DEFAULT_CARD`] 并可以提示
+    /// 「设置里的色卡名已失效」——绝不静默当成默认卡用掉，那样用户会以为设置没保存）。
+    pub fn from_key(key: &str) -> Option {
+        Self::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..c5e2f39
--- /dev/null
+++ b/crates/design/src/palette/mod.rs
@@ -0,0 +1,60 @@
+//! # 配色来源（D38 / D40）：图片取色 · 内置色卡 · 三级回落 · WCAG 收敛
+//!
+//! 用户在 2026-11-01 定的配色来源是三级（D38）：
+//!
+//! ```text
+//! ① 启动器背景图取色（用户设了背景图时）
+//!    ↓ 没有背景图 / 取色失败
+//! ② 桌面壁纸取色（用户开了「莫奈取色」但没设背景图时）
+//!    ↓ 没有壁纸 / 取色失败 / 对比度收敛失败
+//! ③ 内置色卡（用户手动选的那张；没选过就是出厂默认「天蓝」）
+//! ```
+//!
+//! 取色失败**不静默**：本模块的 [`Provenance`] 会把「最终用了哪一级」和「前几级为什么没用」
+//! 都带回来，设置页据此显示提示；解码失败也在里面（它不在这里发生，但原因是这里记录的）。
+//! 契约（UI 怎么调、文案怎么映射）见 `DevDocs/SubAgentsTalk/palette-source-contract.md`。
+//!
+//! ## 分层（D40）：本模块只做纯数学
+//!
+//! | 层 | 在哪 | 职责 | 依赖 |
+//! |---|---|---|---|
+//! | 纯数学 | **本模块**（`crates/design`） | 像素 → 种子 → 49 角色；色卡；回落决策；对比度收敛 | 无（零第三方依赖） |
+//! | 解码 | `crates/palette-extract` | 路径/字节 → RGBA 像素 | `image`（唯一引入处） |
+//! | 调用侧 | 后续 appearance/settings mission | 拿路径、把 [`Provenance`] 变文案 | UI 框架 |
+//!
+//! 所以本模块的「图片输入」永远是**已经解码好的像素**，从来没有路径、没有 IO。
+//!
+//! ## 四个部分
+//!
+//! - [`seed`]：`seed_from_rgba(pixels, w, h)`（D40 的入口形状）。量化在 [`quantize`]，
+//!   挑主色在 [`score`]——**不是取平均色**，理由见 [`quantize`] 的模块文档。
+//! - [`card`]：内置色卡（≥6 张，含出厂默认「天蓝」）。卡的 `key` 是**持久化键**，写进用户设置。
+//! - [`wcag`]：对任意一套方案跑对比度断言；不达标就沿 tone 轴修正，并记录「改了什么」。
+//! - [`resolve`]：纯函数 `resolve_source(...) -> (Scheme, Provenance)`，实现三级优先与回落。
+//!
+//! ## D40 的两条实测事实（不是风格偏好，是物理事实）
+//!
+//! 1. **零彩度种子的 CAM16 色相是常数 209.49°**，不是 NaN。所以「灰白壁纸」硬取色会得到
+//!    一个凭空上色的青色（`#006874`），且极低彩度段色相是噪声放大器（`#808080` → 209.5°、
+//!    `#7A7C7E` → 231.2°）。→ [`seed::MIN_SEED_CHROMA`] = 8 的种子彩度门槛，低于它就回落色卡。
+//! 2. **动态色也必须过 WCAG**。候选色卡的 208 项门禁（`tests/contrast_aa.rs`）不覆盖取色结果，
+//!    所以 [`wcag`] 对**任何**来源的方案都跑同一套检查，不达标就收敛或回落。
+
+pub mod card;
+pub mod resolve;
+pub mod seed;
+pub mod wcag;
+
+mod quantize;
+mod score;
+
+pub use card::{Card, CardKey, CARDS, DEFAULT_CARD};
+pub use resolve::{resolve_source, ImageInput, ImageSource, Level, Outcome, Provenance, Skip};
+pub use seed::{
+    analyze_rgba, seed_from_rgba, Failure, Seed, MAX_SAMPLES, MIN_PIXELS, MIN_SEED_CHROMA,
+    MUTED_SEED_CHROMA,
+};
+pub use wcag::{converge, Adjustment, WcagReport, AA_NON_TEXT, AA_TEXT, TEXT_PAIRS};
+
+/// 一套方案的来源层级（[`Level`] 的别名，读起来更清楚）。
+pub use resolve::Level as SourceLevel;
diff --git a/crates/design/src/palette/quantize.rs b/crates/design/src/palette/quantize.rs
new file mode 100644
index 0000000..365cd93
--- /dev/null
+++ b/crates/design/src/palette/quantize.rs
@@ -0,0 +1,338 @@
+//! 像素 → 主色簇：Monet（Material You）取色管线里**量化那一半**（打分那一半在 [`super::score`]）。
+//!
+//! ## 为什么不是「取平均色」
+//!
+//! 平均色是两个独立错误的合成：
+//!
+//! 1. **它不存在的颜色**。平均会把「天空 60% + 树叶 30% + 纯白 10%」混成一块脏灰绿，
+//!    这个色值在图上**一个像素都不是**，拿它当种子，用户看到的整套配色跟壁纸不像。
+//! 2. **它没有「主色」概念**。一张 95% 是米白、5% 是珊瑚的图，平均色几乎等于米白，
+//!    而人眼记住的、能当强调色用的是那 5%。官方 Monet 的立场正好相反：**按面积 + 彩度
+//!    挑一个「有人气又有色」的代表色**（`Score`），不是把整体摊平。
+//!
+//! ## 采用的策略（三层）
+//!
+//! | 步 | 做什么 | 官方对应 | 等级 |
+//! |---|---|---|---|
+//! | 1 | 5 bit/通道直方图（32³ = 32768 桶），桶内记像素数与各通道原值和 | `QuantizerWu` 的 `INDEX_BITS = 5` | A |
+//! | 2 | 桶当带权点，在 **CIELAB** 里跑 k-means（≤10 轮；簇心用线性 RGB 加权均值更新） | `QuantizerWsmeans`（`MAX_ITERATIONS = 10`、`MIN_DELTA_E = 3.0`） | A（结构）/ B（用直方图桶代替 Wu 的分割盒播种） |
+//! | 3 | 每簇的代表色 = 簇内像素最多的那个桶里**像素的原值平均** | `QuantizerCelebi` = 量化 + `Score` | A（管线）/ B（代表色取桶内均值） |
+//!
+//! 也就是说：本模块 = `QuantizerCelebi` 的形状（直方图量化 + k-means 精修），
+//! 与官方的差别在**播种方式**——官方用 `QuantizerWu` 的动态规划分割盒当初始簇心，
+//! 这里用「像素数最多的 24 个桶」。差别可测量（见各模块单测：5% 面积的强调色簇不会被
+//! 95% 的底色吞掉），换来的是一条可全单测、零依赖、确定性的实现。
+//!
+//! ## 代表色为什么要「桶内原值平均」而不是桶中心
+//!
+//! 只取桶中心（5 bit 量化点）会让纯色 `#3C8DBC` 的图取出 `#3B8BBB`——量化误差 1~3/通道。
+//! 单看数字无所谓，但这是**用户能看出来**的：「我选的是这个蓝，凭什么给我的强调色差一点？」
+//! 桶内原值平均对纯色图精确等于输入色（误差 0），对复杂图就是该桶的真实均值，
+//! 仍然不是「全图平均色」（只有一个桶那么多像素参与）。
+//!
+//! ## 来源等级
+//!
+//! - **A**：`material-color-utilities`（Apache-2.0）里确实有 `QuantizerWu` / `QuantizerWsmeans` /
+//!   `QuantizerCelebi` / `Score` 四个类，且 `INDEX_BITS = 5`、`MAX_ITERATIONS = 10`、
+//!   `MIN_DELTA_E = 3.0` 是官方常数——这些是「照抄口径」的部分。
+//! - **B**：用「top-N 桶」代替 Wu 的分割盒当播种；代表色取桶内原值均值。
+//! - **C**：不做。拿不准的常数一律写成带注释的「我们的选择」，不假装是官方值。
+
+use crate::color::space;
+use crate::color::Color;
+
+/// 每通道保留的位数：官方 `QuantizerWu` 用 5 bit/通道。
+pub(crate) const INDEX_BITS: u32 = 5;
+/// 直方图桶数（32³）。
+const BIN_COUNT: usize = 1 << (INDEX_BITS as usize * 3);
+/// 每通道的右移量（8 − 5 = 3）。
+const SHIFT: u32 = 8 - INDEX_BITS;
+/// k-means 最多迭代轮数（官方 `QuantizerWsmeans.MAX_ITERATIONS`）。
+const MAX_ITERATIONS: usize = 10;
+/// 收敛阈值：簇心在 CIELAB 里移动小于这个距离就停（官方 `MIN_DELTA_E`）。
+const MIN_DELTA_E: f64 = 3.0;
+/// 最多保留的簇数（喂给打分的候选数量）。官方 `Score` 通常拿到 256 个候选；
+/// 24 个足够覆盖「底色 + 两三个强调色簇」，也让色相直方图不被噪声塞满。
+pub(crate) const MAX_CLUSTERS: usize = 24;
+
+/// 一个主色簇：图里**真实存在**的颜色 + 被归到它名下的像素数。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) struct Cluster {
+    /// 簇的代表色（簇内像素最多的桶里，像素原值的平均）。
+    pub color: Color,
+    /// 归到这个簇的采样像素数。
+    pub population: u32,
+}
+
+/// 一个非空桶。
+#[derive(Debug, Clone, Copy)]
+struct Bin {
+    index: usize,
+    color: Color,
+    count: u32,
+}
+
+/// 把采样像素量化成主色簇（按像素数降序，同数按色值排序 → 结果确定）。
+pub(crate) fn quantize(samples: &[Color]) -> Vec {
+    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/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..fe2e4a1
--- /dev/null
+++ b/crates/design/src/shape.rs
@@ -0,0 +1,313 @@
+//! M3 Expressive 形状刻度 + shape morph 数据。
+//!
+//! 形状是「唯一真源」的一部分：组件不许写裸半径（`border_radius(8)`），一律引用
+//! [`ShapeScale`]；需要动起来的（按下、选中、展开）用 [`ShapeMorph`] 的 from→to 数据。
+//!
+//! ## 圆角分两层（D32）
+//!
+//! 官方实现与官方刻度表并不总一致：Checkbox 的圆角是 **2dp**，但 `ShapeScale` 的刻度是
+//! `{0,4,8,12,16,20,28,32,48,full}`——2 不在里面。D32 的判决是**分层**而不是放宽判据：
+//!
+//! - **容器级**（卡片、弹窗、抽屉、按钮、面板、输入框外壳）只许用 [`ShapeScale`] 的刻度值；
+//! - **微控件级**（≤24dp 的 Checkbox 等）用 [`ComponentRadius`] 的白名单值。
+//!
+//! 一个元素该查哪一层由 [`radius_layer_for`] 判定（按尺寸，唯一入口）；微控件层取值走
+//! [`ComponentRadius::radius_px`]，**尺寸超界时返回 `None`**——这不是文档约定，是签名保证。
+//!
+//! ## 窗口**外框**圆角不在这里（M116）
+//!
+//! `ShapeScale` 管的是**我们画的东西**：卡片、按钮、浮层、面板。窗口的最外层圆角由操作系统
+//! 决定（Win11 / Server 2025 走 DWM 合成器，macOS 走 `layer.cornerRadius`，X11/Wayland 看合成器），
+//! 系统**不暴露**那个半径值，我们也不自己定一个数字（用户定案：不做 8/12/16 档）。
+//! 所以窗口圆角没有令牌：判据在 `unlucky-app-iced` 的 `platform::plan_corner`，
+//! 落点在 `platform/win32/transparency`。
+//!
+//! 反过来说：**别**为了「让窗口看起来是圆的」去给根容器加 `ShapeScale::ExtraLarge`——那会把
+//! 四角裁掉内容（背景图/标题栏底色露出方角），而外框仍然是方的。
+
+use crate::motion::Spring;
+
+/// M3 形状刻度（含 Expressive 新增档）。
+///
+/// 基础档（M3）：none 0 / extra-small 4 / small 8 / medium 12 / large 16 / extra-large 28 / full。
+/// Expressive 新增档：`large-increased` 20 / `extra-large-increased` 32 / `extra-extra-large` 48。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum ShapeScale {
+    /// 直角（0dp）：仅用于贴边容器/分隔。
+    None,
+    /// 4dp：小控件（chip、小徽标）。
+    ExtraSmall,
+    /// 8dp：控件（按钮、输入框、菜单项）。
+    Small,
+    /// 12dp：卡片、列表容器（Expressive 里卡片默认升到这一档）。
+    Medium,
+    /// 16dp：大卡片、面板。
+    Large,
+    /// 20dp（Expressive）：按下/选中时的「胀开」档。
+    LargeIncreased,
+    /// 28dp：浮层、对话框。
+    ExtraLarge,
+    /// 32dp（Expressive）：大浮层、FAB 展开态。
+    ExtraLargeIncreased,
+    /// 48dp（Expressive）：超大容器、模态全屏卡。
+    ExtraExtraLarge,
+    /// 药丸/圆：按边长取半径一半（导航指示条、头像、switch 轨道）。
+    Full,
+}
+
+impl ShapeScale {
+    /// 半径（dp；[`ShapeScale::Full`] 返回 `f32::INFINITY`，由 [`ShapeScale::radius_px`] 折算）。
+    pub const fn dp(self) -> f32 {
+        match self {
+            ShapeScale::None => 0.0,
+            ShapeScale::ExtraSmall => 4.0,
+            ShapeScale::Small => 8.0,
+            ShapeScale::Medium => 12.0,
+            ShapeScale::Large => 16.0,
+            ShapeScale::LargeIncreased => 20.0,
+            ShapeScale::ExtraLarge => 28.0,
+            ShapeScale::ExtraLargeIncreased => 32.0,
+            ShapeScale::ExtraExtraLarge => 48.0,
+            ShapeScale::Full => f32::INFINITY,
+        }
+    }
+
+    /// 实际渲染半径：`Full` 取边长一半，其余不超过边长一半（避免方角变圆角溢出）。
+    pub fn radius_px(self, size_px: f32) -> f32 {
+        let half = size_px.max(0.0) / 2.0;
+        if self == ShapeScale::Full {
+            half
+        } else {
+            self.dp().min(half)
+        }
+    }
+
+    /// 是否是 Expressive 才有的档位（基础 M3 没有）。
+    pub const fn is_expressive(self) -> bool {
+        matches!(
+            self,
+            ShapeScale::LargeIncreased
+                | ShapeScale::ExtraLargeIncreased
+                | ShapeScale::ExtraExtraLarge
+        )
+    }
+
+    /// 在形状阶梯上的序号（0 = None，9 = Full），用于断言形变方向是「胀开」而不是「收紧」。
+    pub const fn rank(self) -> u8 {
+        match self {
+            ShapeScale::None => 0,
+            ShapeScale::ExtraSmall => 1,
+            ShapeScale::Small => 2,
+            ShapeScale::Medium => 3,
+            ShapeScale::Large => 4,
+            ShapeScale::LargeIncreased => 5,
+            ShapeScale::ExtraLarge => 6,
+            ShapeScale::ExtraLargeIncreased => 7,
+            ShapeScale::ExtraExtraLarge => 8,
+            ShapeScale::Full => 9,
+        }
+    }
+}
+
+/// 微控件（≤24dp）的尺寸上限（dp）。
+///
+/// 超过这条线的元素属**容器级**，圆角必须查 [`ShapeScale`] 的严格刻度；[`ComponentRadius`]
+/// 只在这条线以内有效——由 [`ComponentRadius::radius_px`] 在运行期拦住（传大尺寸拿不到微半径）。
+/// 24 这个门槛不是官方数字，是 D32 给「微控件」划的界（Checkbox 20、指示点、徽标都在以内）。
+pub const MICRO_CONTROL_MAX_SIZE: f32 = 24.0;
+
+/// 微控件圆角（D32 第二层）：**来源官方组件实现，不是 [`ShapeScale`] 的成员**。
+///
+/// 为什么要有这一层：官方 Checkbox 的圆角是 **2dp**（`Checkbox.kt:738 RadiusSize = 2.dp`，
+/// `CheckboxTokens.ContainerShape = RoundedCornerShape(2)`），而 M3 形状刻度只有
+/// `{0,4,8,12,16,20,28,32,48,full}`。把 2 塞进刻度会废掉「无任意圆角」这条守门（D30 rubric K1），
+/// 不收又只能在组件里抄 `2.0` 字面量。D32 的判决是**分层**，不是放宽：
+///
+/// | 层 | 管什么 | 取值 |
+/// |---|---|---|
+/// | [`ShapeScale`] | 容器级：卡片/弹窗/抽屉/按钮/面板/输入框外壳 | 严格刻度，不许自造 |
+/// | `ComponentRadius` | 微控件级：Checkbox 等 ≤24dp 的元素 | 白名单，当前只有 [`ComponentRadius::Micro`] |
+///
+/// 用法：先 [`radius_layer_for`] 判层，微控件再 `radius_px(size)`。**返回 `None` 说明尺寸超界，
+/// 必须改查 [`ShapeScale`]**，不许把微半径硬套到容器上。
+///
+/// 公开的**唯一取值口是 [`ComponentRadius::radius_px`]**（带尺寸闸）：本类型的 `dp()` 是
+/// `pub(crate)`，故意不对外开放——否则任何调用方都能无条件拿到 `2.0`，「只许 ≤24dp」就成了
+/// 自觉而不是约束（D32 的原意是拦住，不是提醒）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum ComponentRadius {
+    /// 2dp：官方 Checkbox 容器圆角。
+    Micro,
+}
+
+impl ComponentRadius {
+    /// 白名单里的全部微半径（D32 当前只有一项；加值必须先在 `design-令牌约定` 登记）。
+    ///
+    /// 枚举得出的只是**变体**（`Micro` 这个名字），拿不到数值——取值必须走 [`Self::radius_px`]。
+    pub const ALL: [ComponentRadius; 1] = [ComponentRadius::Micro];
+
+    /// 半径（dp）。**`pub(crate)`：crate 内推导与自己用，不对外开放。**
+    ///
+    /// 对任何尺寸都返回同一个数，所以它天然绕开 D32 的尺寸闸；对外只留
+    /// [`Self::radius_px`]（`Option`，>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/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..1c095dd
--- /dev/null
+++ b/crates/i18n/src/bridge.rs
@@ -0,0 +1,184 @@
+//! 文案边界（示例契约）：core / presenter 的**状态**怎么进 UI。
+//!
+//! ## 现状（为什么需要这份契约）
+//!
+//! UI 文案硬编码英文，而 `core` / `presenter` 产出的状态串是中文，于是界面上已经出现
+//! `Launch failed · exit0 静默失败` 这种**一句话里中英混排**的东西，加载器徽标也在 `原版` / `Fabric`
+//! 之间混用。根因不是「译文不够」，是**边界没划**：谁产出文案、谁负责翻译，没有规则。
+//!
+//! ## 三条规则
+//!
+//! **R1 · UI 侧不产生文案，只翻译 key。**
+//!    UI 不许把片段拼成句子（`"Launch failed · " + reason`），也不许写中文字面量。
+//!    一句话 = 一个 key（[`crate::catalog`]），带变量的用 `{name}` 交给
+//!    [`crate::catalog::Catalog::render`]。拼接一旦发生，任何一套语言都拼不对（语序、标点、
+//!    量词都不一样），而且混排会立刻出现在截图里。
+//!
+//! **R2 · core 的中文串不进 UI。**
+//!    core / presenter 的中文（`原版`、`静默失败（exit 0 但游戏没起来）`、
+//!    `缺少库文件 foo.jar（…）`）是**日志 / CLI / 诊断报告**的文案，不是界面文案。
+//!    界面只能通过两条合法通道拿到「要显示什么」：
+//!    1. **结构化出口**（首选）：枚举 / DTO 字段 → 映射到 [`crate::Key`]。
+//!       例：`presenter::dto::LoaderKind::as_str()` 的稳定 id（`vanilla` / `fabric`）→
+//!       [`crate::Key::LoaderVanilla`]；`LogOutcome` 三态 → `LaunchOutcome*` 三 key。
+//!       好处是**新增一个枚举变体时编译器会逼你补映射**（`match` 非穷尽即报错）。
+//!    2. **过渡表**（[`classify`]）：只覆盖「已知会漏到界面的少数几个串」，逐条硬编码。
+//!       它是**债**，不是终点——新出现的未知串一律走第三条。
+//!
+//! **R3 · 认不出的串，不许画原文。**
+//!    [`CoreText::Untranslated`] 就是那种情况：UI 只许显示 [`crate::Key::CoreTextUntranslated`]
+//!    这个**故意难看**的兜底（`[system text not translated]`），并把原文写进日志。
+//!    这条比「先画上去以后再翻」严格，是因为后者永远不会被回头修——难看才会被修。
+//!    同时它是一件**上游缺陷的证据**：说明 core 欠一个结构化出口，应当报 finding 而不是在 UI 贴创可贴。
+//!
+//! ## 品牌专名（唯一的豁免）
+//!
+//! `Fabric` / `Forge` / `NeoForge` / `Quilt` / `OptiFine` / `LiteLoader` 是专有名词，**不翻译**
+//! （翻成「锻造」就没人认识了）。它们可以原样显示，但必须经 [`CoreText::Brand`] 判定——
+//! 也就是说「原样显示」是一个**显式决定**，不是「反正没译文就画原文」的默认行为。
+//!
+//! ## 诚实边界（抓得住什么 / 抓不住什么）
+//!
+//! - **抓得住**：本表里列到的串（映射正确、未知串不被放行）；
+//! - **抓不住**：core 明天新加一句中文——本 crate 不依赖 core（零依赖纪律），没有跨 crate 的一致性检查。
+//!   那条只能靠「core 侧只给枚举」的纪律 + 后续在 `crates/presenter` 里加一条守门测试
+//!   （例如：`*_view` 的字符串字段不许含 CJK 字符）。
+
+use crate::catalog::Key;
+
+/// 一段来自 `core` / `presenter` 的显示文本该怎么处理。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum CoreText {
+    /// 品牌专名：原样显示（不翻译，见模块文档的豁免）。
+    Brand(&'static str),
+    /// 有对应 key：按当前语言取词。
+    Key(Key),
+    /// 不认识：只许显示 [`Key::CoreTextUntranslated`]，原文进日志。
+    Untranslated,
+}
+
+/// 已知会漏到界面的中文状态串 → key。
+///
+/// 每一条都得在 `crates/presenter` / `crates/core` 里找得到出处（注释里给位置），
+/// 不许凭想象加——凭空加的条目会让 [`classify`] 假装覆盖了实际没覆盖的东西。
+const LEGACY_STATUS: &[(&str, Key)] = &[
+    // `presenter::dto::instances::LoaderKind::label()` / `host::launch::loader_label()`
+    ("原版", Key::LoaderVanilla),
+    // `presenter::host::job.rs`：`LogOutcome::SilentFail` 的展示文字
+    ("静默失败（exit 0 但游戏没起来）", Key::LaunchOutcomeSilent),
+    // `presenter::mock_data.rs` 里的演示数据
+    ("exit0 静默失败", Key::LaunchOutcomeSilent),
+];
+
+/// 品牌专名（原样显示；**不得**翻译或拼进句子，UI 拼装仍然禁止）。
+const BRANDS: &[&str] = &[
+    "Fabric",
+    "Forge",
+    "NeoForge",
+    "Quilt",
+    "OptiFine",
+    "LiteLoader",
+];
+
+/// 契约总入口：core / presenter 的显示文本 → 该画什么。
+///
+/// 这是**示例契约**：形状（三分类 + 未知不放行）比表里的具体条目重要，接线 mission 按这个形状
+/// 把每条 UI 路径改过来，条目随上游结构化出口的落地逐条删掉。
+#[must_use]
+pub fn classify(text: &str) -> CoreText {
+    let trimmed = text.trim();
+    if trimmed.is_empty() {
+        return CoreText::Untranslated;
+    }
+
+    if let Some((_, key)) = LEGACY_STATUS.iter().find(|(legacy, _)| *legacy == trimmed) {
+        return CoreText::Key(*key);
+    }
+
+    if let Some(brand) = BRANDS.iter().find(|brand| **brand == trimmed) {
+        return CoreText::Brand(brand);
+    }
+
+    // `Fabric 0.16.5` 这类「品牌 + 版本号」也是合法显示：品牌之后只跟一个版本号时放行。
+    // 注意这里是**保守**放行：只有「一个词 + 空格 + 版本号」的形状才算，含中文的串绝不会进来。
+    if let Some((head, tail)) = trimmed.split_once(' ') {
+        if let Some(brand) = BRANDS.iter().find(|brand| **brand == head) {
+            if !tail.is_empty() && !tail.contains(char::is_whitespace) && !tail.chars().any(is_cjk)
+            {
+                return CoreText::Brand(brand);
+            }
+        }
+    }
+
+    CoreText::Untranslated
+}
+
+/// 是否 CJK 字符（`classify` 的保守放行判据用）。
+fn is_cjk(ch: char) -> bool {
+    // 0x2E80..=0x9FFF 已含 CJK 部首 / 假名 / 统一表意文字与 0x3000 段的中文标点，不再单列。
+    matches!(ch as u32, 0x2E80..=0x9FFF | 0xF900..=0xFAFF | 0xFF00..=0xFFEF)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn known_chinese_status_strings_map_to_keys() {
+        // 抓得住：过渡表条目的映射写错（把「原版」映到别的 key），以及「同一段意思两个 key」的漂移。
+        // 抓不住：core 那边改了这个中文串的措辞——那时这里会落到 Untranslated（**故意的**，
+        //         让漏译可见，而不是继续拿旧文案糊过去）。
+        assert_eq!(classify("原版"), CoreText::Key(Key::LoaderVanilla));
+        assert_eq!(
+            classify("静默失败（exit 0 但游戏没起来）"),
+            CoreText::Key(Key::LaunchOutcomeSilent)
+        );
+        assert_eq!(
+            classify("exit0 静默失败"),
+            CoreText::Key(Key::LaunchOutcomeSilent)
+        );
+        assert_eq!(
+            classify(" 原版 "),
+            CoreText::Key(Key::LoaderVanilla),
+            "前后空白要吃掉"
+        );
+    }
+
+    #[test]
+    fn brands_pass_through_and_are_never_translated() {
+        // 抓得住：品牌名被当成待翻译文案（`Fabric` → 某个 key 的译文就没人认识它了），
+        //         以及「品牌 + 版本号」这种合法徽标被判成未翻译。
+        // 抓不住：品牌名与版本号之间该用什么分隔（M3 令牌 / 排版层的事，不是本契约的事）。
+        assert_eq!(classify("Fabric"), CoreText::Brand("Fabric"));
+        assert_eq!(classify("Fabric 0.16.5"), CoreText::Brand("Fabric"));
+        assert_eq!(classify("NeoForge 21.1.72"), CoreText::Brand("NeoForge"));
+        assert_eq!(classify("Fabric 中文"), CoreText::Untranslated);
+        assert_eq!(classify("Fabric 0.16.5 beta"), CoreText::Untranslated);
+        assert_eq!(classify("FabricX"), CoreText::Untranslated);
+    }
+
+    #[test]
+    fn unknown_core_prose_is_refused_instead_of_printed_raw() {
+        // 抓得住：R3——未知中文（core 的诊断prose、`describe_warning` 的拼句）被放行到界面，
+        //         那正是 `Launch failed · exit0 静默失败` 这类混排的来源。
+        // 抓不住：UI 拿到 Untranslated 之后有没有真的只显示兜底（页面侧测试 + 截图验收）。
+        let leaks = [
+            "缺少库文件 lwjgl.jar（C:\\Users\\x\\.minecraft\\libs\\lwjgl.jar）",
+            "版本 JSON 没有 mainClass",
+            "退出码为 0 但疑似静默失败（3 条错误行）：游戏可能刚起来就被 mod 异常终止",
+            "",
+            "   ",
+        ];
+        for leak in leaks {
+            assert_eq!(classify(leak), CoreText::Untranslated, "{leak}");
+        }
+    }
+
+    #[test]
+    fn classify_never_returns_a_raw_unknown_string() {
+        // 抓得住：将来给 `CoreText` 加了「原样字符串」变体（那等于把 R3 废掉）。
+        // 抓不住：枚举里已有变体被误用——那要靠调用点 review。
+        let odd = "some untranslated english";
+        assert_eq!(classify(odd), CoreText::Untranslated);
+    }
+}
diff --git a/crates/i18n/src/catalog.rs b/crates/i18n/src/catalog.rs
new file mode 100644
index 0000000..3f76194
--- /dev/null
+++ b/crates/i18n/src/catalog.rs
@@ -0,0 +1,342 @@
+//! 消息目录：`Key` 枚举 + 中英两套常量表 + 取词 / 占位符渲染 / 缺译诊断。
+//!
+//! ## 为什么 key 是枚举而不是字符串
+//!
+//! 字符串 key（`"nav.instances"`）拼错了编译器一声不响，运行时才知道——本仓的说法是「运行时静默回落」。
+//! 枚举 key 把这类错误前移到**编译期**：`Key::NavInstance`（真名是 `NavInstances`）直接
+//! `error[E0599]`，不可能跑到运行时。
+//!
+//! **这里没有守卫测试**：曾经写过一个 `compile_fail` 文档测试想守这条，但复审实测它对
+//! 「把 `Key` 换成字符串包装类型」这类变异仍然全绿——它守的是「这段代码编译不过」，而不是
+//! 「编译期校验还在」。说不清真假的守卫比没有更糟，所以删了；这条纪律只靠枚举这个事实本身。
+//!
+//! ## 为什么两套译文写在**同一行**
+//!
+//! ```ignore
+//! NavInstances => ("Instances", "实例"),
+//! ```
+//!
+//! 一行就是「一个 key 的全部语言」。于是「加了 key 忘了译文」在结构上不可能发生——这比「运行时发现
+//! 缺译再诊断」更强。缺译诊断（[`Catalog::diagnose`]）因此有两个真实用途：
+//!
+//! 1. **注入目录**：后续 mission 用 [`Catalog::from_entries`] 加第三套（繁体 / 更多语言）时，
+//!    表格是手写的，缺条目的风险回来了；
+//! 2. **回归守门**：万一有人把这张表改回「两套各写一遍」，[`Catalog::missing`] 的守卫测试立刻红。
+//!
+//! ## 按域拆开（M99 `SETTINGSFRAME`）
+//!
+//! 条目表原先整张写在本文件里，而**设置页正文接下来由四条 mission 并行接**（java / download /
+//! language+appearance / ai+about），每条都要往这张表里加一批 key——同一张表就是四条线的冲突点。
+//! 现在一个域一个文件（`catalog/<域>.rs`），本文件只留：`catalog!` 宏、装配链、[`Catalog`] 与对外 API。
+//!
+//! | 文件 | 域 | 谁会长它 |
+//! |---|---|---|
+//! | [`nav`] / [`instances`] / [`loader`] / [`launch`] / [`font`] / [`core_text`] | 页面与运行时文案 | 各自页面 |
+//! | [`download`] / [`logs`] | 下载页 / 日志页（M94 / M95） | 那两页 |
+//! | `settings/`（`general` / `appearance` / `java` / `download` / `ai`） | 设置页，**一个分组一个文件** | 设置页四条线 |
+//! | [`general`] | 设置页 General 分组的**真控件**文案（语言选择器三档 + 主题/启动页/关闭三行） | M106 `I18NFOLLOW`（挂在链尾，既有顺序不动） |
+//!
+//! ### 域文件的形状（加 key 时照抄）
+//!
+//! ```ignore
+//! macro_rules! <域>_entries {
+//!     ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+//!         $next! { $($rest,)* {
+//!             $($acc)*
+//!             NavInstances => ("Instances", "实例"),
+//!         } }
+//!     };
+//! }
+//! pub(super) use <域>_entries;
+//! ```
+//!
+//! 它把本域条目**追加**到累积表 `$acc` 之后，再把「还没装配的域」原样交给 `$next`——最后交给
+//! [`finish`]，由它把整张表喂给 [`catalog!`]。**为什么非得这么绕**：`macro_rules!` 不能在
+//! 宏参数里展开另一个宏（`catalog! { nav_entries!() }` 只会把 `nav_entries!()` 当成普通 token），
+//! 也不能用元变量当宏名（`macro_rules! $name` 非法），所以只能「回调链」式累积。代价是每个域文件
+//! 都要重抄上面那 6 行签名——这是 `macro_rules!` 的固有成本，不是可以省掉的样板。
+//!
+//! ### 拆开之后仍然只有一个真相源
+//!
+//! 装配顺序写在下面那条调用里，**它等于 `Key` 的声明顺序**；[`golden`] 把拆分前那份
+//! `key -> (en, zh-CN)` 全量逐字节钉住（连顺序一起钉），所以「搬丢一条 / 两条互抄 / 顺序被调换」
+//! 都会红。
+//!
+//! ## 缺译时给什么
+//!
+//! **不回落**（绝不拿另一种语言顶替，用户会看到「一半英文一半中文」的界面而不自知）：
+//!
+//! - [`Catalog::get`] → `None`（严格调用方用它）；
+//! - [`Catalog::text`] → [`MISSING`]（`⟪missing⟫`，UI 上刺眼但一眼可辨）；
+//! - [`Catalog::render`] → `⟪missing:KeyName⟫`（带上 key 名，方便照着日志补译）。
+
+use crate::lang::Lang;
+
+/// 缺译占位符（`text()` 的返回；故意刺眼——宁可难看，也不许静默顶替）。
+pub const MISSING: &str = "⟪missing⟫";
+
+/// 生成 `Key` 枚举 + 两套常量表（一行 = 一个 key 的全部语言）。
+macro_rules! catalog {
+    ($($variant:ident => ($en:literal, $zh:literal)),+ $(,)?) => {
+        /// 可翻译文案的 key。**不存在时编译失败**（枚举变体名即契约）。
+        #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
+        pub enum Key {
+            $(
+                #[doc = concat!("en: `", $en, "` / zh-CN: `", $zh, "`")]
+                $variant,
+            )+
+        }
+
+        impl Key {
+            /// 全部 key（缺译诊断与完整性测试的遍历源）。
+            pub const ALL: &'static [Key] = &[$(Key::$variant),+];
+
+            /// 变体名（日志 / 缺译诊断里用来指认 key；不是文案）。
+            #[must_use]
+            pub const fn name(self) -> &'static str {
+                match self {
+                    $(Key::$variant => stringify!($variant),)+
+                }
+            }
+        }
+
+        const EN: &[(Key, &str)] = &[$((Key::$variant, $en)),+];
+        const ZH_CN: &[(Key, &str)] = &[$((Key::$variant, $zh)),+];
+    };
+}
+
+// --------------------------------------------------------------- 域装配
+
+/// 链的终点：把累积起来的所有条目交给 [`catalog!`]，生成 `Key` 与两张表。
+macro_rules! finish {
+    ({ $($acc:tt)* }) => { catalog! { $($acc)* } };
+}
+
+mod account;
+mod agent;
+mod content;
+mod core_text;
+mod download;
+mod font;
+mod general;
+mod instances;
+mod launch;
+mod loader;
+mod logs;
+mod nav;
+mod settings;
+
+/// 拆分前的 `key -> (en, zh-CN)` **逐字快照**（金表）。
+///
+/// ## 它是什么
+///
+/// M99 把 `catalog.rs` 的单张条目表按域拆到 `catalog/<域>.rs` 之后，这 72 行就是「拆分前那一份」
+/// 的原样导出：由拆分前的 `Catalog::of(En)` / `Catalog::of(ZhCn)` 逐条 `println!` 出来，
+/// 再原封不动抄进来（生成方式见 `tests.rs` 里 `split_keeps_every_translation` 的注释）。
+/// M108 在它上面改了 3 条（`NavDownload` / `DownloadTitle` / `DownloadSubtitle`）、追加了 1 条
+/// （`NavDownloadExpanded`）；M105/M106/M107 各自追加的条目也都在，整表现在是 138 条。
+///
+/// ## 为什么不是「数条数」
+///
+/// 条数相等抓不住任何一种真会发生的坏法：某条译文在搬移时被漏掉、另一条被复制两次，条数照旧。
+/// 这张表比的是**全量、逐字节、按声明顺序**的三元组，于是下面四种坏法都会红：
+///
+/// | 坏法 | 红在哪 |
+/// |---|---|
+/// | 某个 key 整条被搬丢 | 条数不等 / 该行 key 名对不上 |
+/// | 两条 key 的译文互抄（同 key 被覆盖到别的译文） | 该行 en 或 zh 不等 |
+/// | 某条译文改了一个字符 | 该行不等（`assert_eq!` 带原文） |
+/// | 域的顺序被调换（`Key` 的 `Ord` 与导出表顺序都靠它） | 该行 key 名对不上 |
+///
+/// **抓不住**：译文本身翻得对不对（金表是「拆分前」的快照，它只能证明「没变」）。
+///
+/// ## M108 更新了三条、新增了一条（版本管理改名）
+///
+/// 用户令（2026-11-04）把这页的显示名从「下载 / Downloads」改成「版本管理 / Version management」：
+/// [`Key::NavDownload`] / [`Key::DownloadTitle`] / [`Key::DownloadSubtitle`]
+/// 三条译文按令改掉，并**新增** [`Key::NavDownloadExpanded`]（240 展开态的全标签，
+/// 88 轨放不下 18 字符的英文，见 `catalog/nav.rs` 的「两条 key」一节）。
+///
+/// 其余各行仍逐字节等于拆分前那份快照——也就是说这张表现在证明的是「除这几条按令改过的，
+/// 其余一字未动」，不再是「整表一字未动」。
+///
+/// ## M120 动了实例页那一族（1 条改译文 + 1 条删除 + 28 条新增）
+///
+/// 实例页的文案以前是英文基线字面量，M120 全搬进 `catalog/instances.rs`。那一族在装配链
+/// **第 2 位**（紧跟 nav），所以这批行是**插在中间**的，不是文件末尾追加：
+///
+/// | 动作 | 条目 |
+/// |---|---|
+/// | 改译文 | [`Key::InstancesEmptyBody`]（换成详情列真正画的那句） |
+/// | 删除 | `InstancesLastPlayed`（M117 加的整句，从未接线；页面是「标签 + 值」的元信息卡） |
+/// | 新增 | `InstancesTitle` … `InstancesStageWindow`（页头 / 动作 / 空态 / 元信息标签与值 / 隔离档位 / 运行状态 / 阶段，共 28 条） |
+///
+/// 位置跟着族走这个事实本身就是判据：金表是 `Key::ALL` 的逐 index 镜像，
+/// 「为把新 key 排到文件末尾而去重排别人的族」会让这里整片红。
+#[cfg(test)]
+mod golden;
+
+#[cfg(test)]
+mod tests;
+
+use account::account_entries;
+use agent::agent_entries;
+use content::content_entries;
+use core_text::core_text_entries;
+use download::{download_entries, version_entries};
+use font::font_entries;
+use general::general_entries;
+use instances::instances_entries;
+use launch::launch_entries;
+use loader::loader_entries;
+use logs::logs_entries;
+use nav::nav_entries;
+use settings::{
+    settings_ai_entries, settings_appearance_entries, settings_download_entries,
+    settings_general_entries, settings_java_entries,
+};
+
+// 装配顺序 = `Key` 的声明顺序。**与拆分前逐条一致**，动它等于动 `Key` 的 `Ord` 与导出表顺序，
+// 金表（`catalog/golden.rs`）会红。设置页那五个域按页面上的分组顺序排，中间三个现在是空的。
+nav_entries! {
+    instances_entries,
+    loader_entries,
+    launch_entries,
+    font_entries,
+    settings_general_entries,
+    settings_appearance_entries,
+    settings_java_entries,
+    settings_download_entries,
+    settings_ai_entries,
+    core_text_entries,
+    download_entries,
+    logs_entries,
+    agent_entries,
+    general_entries,
+    // M107：版本管理页的侧栏 / 搜索文案**追加在链尾**（金表只追加不重排，理由见
+    // `catalog/download.rs` 里 `version_entries` 的文档）。M104 的 `agent_entries` 与 M106 的
+    // `general_entries` 已经在 main 上占了链尾，所以本域排在它们**之后**：
+    // `Key::ALL` 顺序 = 金表顺序 = 先 main 的全部域，再 version。
+    version_entries,
+    // M109：内容库页。与 M107 同一条纪律——本域排在 main 已占住的链尾**之后**，
+    // 于是 `Key::ALL` 顺序 = 金表顺序 = 先 main 的全部域，再 version，最后 content。
+    content_entries,
+    // M114：账户页。同理**追加在 main 已占住的链尾之后**（先 content 再 account），
+    // 金表只追加不重排。
+    account_entries,
+    finish,
+    {}
+}
+
+/// 一套语言的目录（不可变；`Copy`，随手传值）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Catalog {
+    lang: Lang,
+    entries: &'static [(Key, &'static str)],
+}
+
+impl Catalog {
+    /// 内置目录。
+    #[must_use]
+    pub const fn of(lang: Lang) -> Catalog {
+        let entries: &'static [(Key, &'static str)] = match lang {
+            Lang::En => EN,
+            Lang::ZhCn => ZH_CN,
+        };
+        Catalog { lang, entries }
+    }
+
+    /// 用外部表构造目录（给后续 mission 的第三套语言 / 测试注入用）。
+    #[must_use]
+    pub const fn from_entries(lang: Lang, entries: &'static [(Key, &'static str)]) -> Catalog {
+        Catalog { lang, entries }
+    }
+
+    /// 这套目录是哪种语言。
+    #[must_use]
+    pub const fn lang(&self) -> Lang {
+        self.lang
+    }
+
+    /// 严格取词：缺译就是 `None`（**不回落**到别的语言）。
+    #[must_use]
+    pub fn get(&self, key: Key) -> Option<&'static str> {
+        self.entries
+            .iter()
+            .find(|(entry, _)| *entry == key)
+            .map(|(_, text)| *text)
+    }
+
+    /// 这套目录的全部条目（声明顺序）。给导出 / 校对工具与完整性守门测试用。
+    #[must_use]
+    pub const fn entries(&self) -> &'static [(Key, &'static str)] {
+        self.entries
+    }
+
+    /// 取词（UI 便利路径）：缺译返回 [`MISSING`]。
+    #[must_use]
+    pub fn text(&self, key: Key) -> &'static str {
+        self.get(key).unwrap_or(MISSING)
+    }
+
+    /// 带变量的句子：把 `{name}` 换掉。
+    ///
+    /// 参数没给全时**占位符原样留在文案里**（`Launch failed (exit {code})`），不 panic、不猜空串——
+    /// 缺参在截图上一眼可见，比静默变成 `exit ` 好查。
+    #[must_use]
+    pub fn render(&self, key: Key, args: &[(&str, &str)]) -> String {
+        let Some(template) = self.get(key) else {
+            return format!("⟪missing:{}⟫", key.name());
+        };
+
+        let mut out = template.to_owned();
+        for (name, value) in args {
+            out = out.replace(&format!("{{{name}}}"), value);
+        }
+        out
+    }
+
+    /// 缺译的 key（自带语言里从来是空；注入目录与回归守门才用得上）。
+    #[must_use]
+    pub fn missing(&self) -> Vec {
+        Key::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..a597fa8
--- /dev/null
+++ b/crates/i18n/src/catalog/account.rs
@@ -0,0 +1,113 @@
+//! 账户页文案（M114 三轨：微软正版 / 第三方皮肤站 / 本地档案）。
+//!
+//! 域文件的形状见 [`crate::catalog`] 的「域装配」一节。本域**追加在装配链末尾**，
+//! 所以金表（`catalog::golden`）里这批 key 也排在最后。
+//!
+//! ## 口径（不许改写成别的说法）
+//!
+//! 本地档案的说明必须带「仅本地/隔离网络测试用，无法连接启用正版验证的服务器」——
+//! 这是 README 已定的口径（`AccountTrackOfflineBody` / `AccountOfflineWarning` 两处都写全），
+//! 不许写成「兼容旧启动器迁移」这种暗示能进正版服的说法。
+//!
+//! 文案里**没有任何 token 字样**：账户页从不展示凭据（M114 审核红线），
+//! 「密码只用于这一次登录」这条提示是唯一提到密码的地方。
+
+macro_rules! account_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* {
+            $($acc)*
+            // ── 页头 / 列表
+            AccountTitle => ("Accounts", "账户"),
+            AccountSubtitle => ("Microsoft, third-party skin servers and local profiles", "微软正版、第三方皮肤站与本地档案"),
+            AccountListTitle => ("All accounts", "全部账户"),
+            AccountAddedOn => ("Added {date}", "添加于 {date}"),
+            AccountActiveChip => ("Active", "当前"),
+            AccountSwitch => ("Use for launch", "切换为启动账户"),
+            AccountRelogin => ("Sign in again", "重新登录"),
+            AccountRemove => ("Remove", "删除"),
+            AccountKindMicrosoft => ("Microsoft", "微软正版"),
+            AccountKindAuthlib => ("Third-party skin server", "第三方皮肤站"),
+            AccountKindOffline => ("Local profile", "本地档案"),
+            AccountServer => ("Server {server}", "服务器 {server}"),
+            // ── 空态
+            AccountEmptyTitle => ("No accounts yet", "还没有账户"),
+            AccountEmptyBody => ("Add a Microsoft account, a third-party skin server account, or a local profile.", "添加微软正版账户、第三方皮肤站账户，或建一个本地档案。"),
+            AccountEmptyAction => ("Add an account", "添加账户"),
+            // ── 三条轨道的入口卡
+            AccountTrackMicrosoftTitle => ("Microsoft account", "微软正版"),
+            AccountTrackMicrosoftBody => ("Sign in with a device code or in your browser. Online servers require this kind of account.", "用设备码或浏览器登录。联机服务器必须用这种账户。"),
+            AccountTrackAuthlibTitle => ("Third-party skin server", "第三方皮肤站"),
+            AccountTrackAuthlibBody => ("An authlib-injector compatible server (LittleSkin and friends) brings its own skins and capes.", "兼容 authlib-injector 的皮肤站（如 LittleSkin）自带皮肤与披风。"),
+            AccountTrackOfflineTitle => ("Local profile", "本地档案"),
+            AccountTrackOfflineBody => ("Local / isolated-network testing only — it cannot join servers that require a genuine Minecraft account.", "仅本地/隔离网络测试用，无法连接启用正版验证的服务器。"),
+            AccountTrackOpen => ("Sign in", "登录"),
+            AccountTrackCreate => ("Create profile", "创建档案"),
+            AccountDialogClose => ("Close", "关闭"),
+            // ── 本地档案表单
+            AccountOfflineNameLabel => ("Profile name", "档案名"),
+            AccountOfflineNameHint => ("3–16 letters, digits or underscore", "3–16 位字母、数字或下划线"),
+            AccountOfflineSubmit => ("Create profile", "创建档案"),
+            AccountOfflineWarning => ("Local / isolated-network testing only — it cannot join servers that require a genuine Minecraft account.", "仅本地/隔离网络测试用，无法连接启用正版验证的服务器。"),
+            // ── 微软登录面板（设备码 / 授权码）
+            AccountDeviceCodeLabel => ("Enter this code", "输入这个用户码"),
+            AccountDeviceCodeCopy => ("Copy code", "复制用户码"),
+            AccountDeviceLinkCopy => ("Copy link", "复制链接"),
+            AccountDeviceCountdown => ("{time} left", "剩 {time}"),
+            AccountDeviceExpired => ("This code has expired. Start again for a fresh one.", "这个用户码已过期，重新开始换一个新的。"),
+            AccountDeviceRetry => ("Try again", "重试"),
+            AccountDeviceCancel => ("Cancel", "取消"),
+            AccountDeviceBrowser => ("Sign in with browser", "用浏览器登录"),
+            AccountDeviceUseCode => ("Use a device code instead", "改用设备码"),
+            // ── 第三方站表单
+            AccountServerLabel => ("Server address", "服务器地址"),
+            AccountServerHint => ("API root, e.g. https://littleskin.cn/api/yggdrasil/", "API 根，例：https://littleskin.cn/api/yggdrasil/"),
+            AccountServerProbe => ("Check server", "校验服务器"),
+            AccountLoginNameLabel => ("Email or username", "邮箱或用户名"),
+            AccountPasswordLabel => ("Password", "密码"),
+            AccountPasswordHint => ("Used once for this sign-in. It is never stored.", "只在这次登录里用一次，不会保存。"),
+            AccountAuthlibSubmit => ("Sign in", "登录"),
+            AccountAuthlibIdleHint => ("The server is checked automatically when you sign in; Check server only does it up front.", "登录时会自动校验服务器；「校验服务器」只是提前跑一遍。"),
+            // ── 皮肤区
+            AccountSkinTitle => ("Skin", "皮肤"),
+            AccountSkinNone => ("No skin available", "没有可用皮肤"),
+            AccountSkinHint => ("Skins come from the account's own server; nothing is generated locally.", "皮肤来自账户自己的服务器，本地不生成任何假皮肤。"),
+            // ── 导航轨底部头像
+            AccountRailSignedOut => ("Not signed in", "未登录"),
+            AccountDeviceHint => ("Open the link in your browser and enter the code above.", "在浏览器里打开链接，输入上面的用户码。"),
+            AccountDeviceBrowserHint => ("Finish the sign-in in the browser window we just opened; the link below also works.", "在我们刚打开的浏览器窗口里完成登录；下面的链接也能手动打开。"),
+            AccountServerChecking => ("Checking the server…", "正在校验服务器…"),
+            AccountServerOk => ("Server {server} is ready", "服务器 {server} 可用"),
+            AccountLoginFailed => ("Sign-in failed", "登录失败"),
+            AccountCurrentTitle => ("Current account", "当前账户"),
+            // ── 失败原因码（M114 r2：后端只给码，文案在这里；原文只进日志）
+            AccountFailureCode => ("Code: {code}", "代码：{code}"),
+            AccountFailureDenied => ("The server refused this sign-in (access denied).", "服务器拒绝了这次登录（拒绝访问）。"),
+            AccountFailureWhitelist => ("Microsoft has not approved this launcher's app registration yet. An administrator has to accept the app, then try again.", "微软还没批准本启动器的应用注册：需要管理员同意该应用后再试。"),
+            AccountFailureUnreachable => ("Could not reach the server. Check the network connection or the address, then try again.", "连不上服务器：检查网络或地址后重试。"),
+            AccountFailureNotAuthlib => ("This address does not look like an authlib-injector server (the API root usually ends with /api/yggdrasil/).", "这个地址不像 authlib-injector 服务器（API 根通常以 /api/yggdrasil/ 结尾）。"),
+            AccountFailureBadCredentials => ("The server rejected the username or password.", "服务器不认这个用户名或密码。"),
+            AccountFailureNoProfile => ("The account has no Minecraft profile on this server yet. Create the character on the server first.", "这个账号在该服务器上还没有角色：先在皮肤站里创建角色。"),
+            AccountFailureStore => ("Could not save the account to disk.", "账户没能写到磁盘上。"),
+            AccountFailureOther => ("The sign-in failed. The full reason is in the launcher log.", "登录失败，完整原因在启动器日志里。"),
+            AccountDeviceRequesting => ("Contacting Microsoft…", "正在联系微软…"),
+            AccountLoginSucceeded => ("Signed in as {name}", "已登录 {name}"),
+            // ── 账户页横幅（添加/删除/切换的结果；页面上真实可见，不是 toast）
+            AccountNoticeAdded => ("Added {name}", "已添加 {name}"),
+            AccountNoticeRemoved => ("Removed {name}", "已删除 {name}"),
+            AccountNoticeSwitched => ("{name} will be used for the next launch", "{name} 将作为下次启动的账户"),
+            AccountNoticeOfflineNameInvalid => ("Profile names must be 3–16 letters, digits or underscores.", "档案名必须是 3–16 位字母、数字或下划线。"),
+            AccountNoticeAccountExists => ("An account with that name already exists.", "同名账户已经存在。"),
+            AccountNoticeStoreFailed => ("Could not save the account store. Check the disk and try again.", "账户库写不进去：检查磁盘后重试。"),
+            AccountNoticeNotFound => ("That account no longer exists.", "这个账户已经不在了。"),
+            AccountNoticeOther => ("The account action failed. The full reason is in the launcher log.", "账户操作失败，完整原因在启动器日志里。"),
+            AccountNoticeDismiss => ("Dismiss", "关闭"),
+            AccountNoticeTitleFailed => ("Account action failed", "账户操作失败"),
+            AccountNoticeTitleDone => ("Account updated", "账户已更新"),
+            // ── 重新登录的引导
+            AccountHintAuthlibReauth => ("Enter the password again for {server}.", "请输入 {server} 的密码。"),
+            AccountHintOfflineNoRelogin => ("Local profiles have no server account to sign in again — create a new profile instead.", "本地档案没有可重新登录的服务器账户，请新建一个档案。"),
+        } }
+    };
+}
+
+pub(crate) use account_entries;
diff --git a/crates/i18n/src/catalog/agent.rs b/crates/i18n/src/catalog/agent.rs
new file mode 100644
index 0000000..22dac43
--- /dev/null
+++ b/crates/i18n/src/catalog/agent.rs
@@ -0,0 +1,66 @@
+//! AI 助手栏 / AI 独立页的文案（M104 `AGENTRAIL`）。
+//!
+//! 这两处**共用同一套会话视图**（`crates/app-iced/src/pages/agent/`），所以文案也只在这里出现一次：
+//! 栏上的折叠/拆出、页上的收回、两处都要的发送/中断/空会话引导。
+//!
+//! 域文件的形状见 [`crate::catalog`] 的「域装配」一节：本宏把条目**追加**到 `$acc` 之后，
+//! 再把「还没装配的域」原样交给 `$next`。条目顺序 = `Key` 的声明顺序（金表 `catalog::golden` 守门）。
+//!
+//! **新增 key 时按顺序追加在最后**：金表是「拆分前那份表的逐字快照」，重排既有行会让它红。
+
+macro_rules! agent_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* {
+            $($acc)*
+            // ── AI 助手（右栗 + 独立页共用）
+            AgentTitle => ("Assistant", "助手"),
+            // M119 r1 复审 P2-1：这条一度被改成中性的「会话」，理由是「跑什么后端由端点标签说」——
+            // 但端点标签在壳里根本不存在，于是默认配置下用户看到的是一个像是接上了模型的助手。
+            // 现在把诚实的话写回来，而且它是**常驻**的（标题下就一行，不点也能看到）。
+            AgentSubtitle => ("Simulated assistant · no real model is connected", "模拟助手 · 还没接真实模型"),
+            AgentCollapse => ("Collapse", "收起"),
+            AgentDetach => ("Pop out", "拆出"),
+            AgentDock => ("Dock back", "收回"),
+            AgentOpen => ("Open assistant", "打开助手"),
+            AgentStripLabel => ("AI", "助手"),
+            AgentSend => ("Send", "发送"),
+            AgentStop => ("Stop", "中断"),
+            // 输入框上再说一次：用户真要动手的位置就在这儿
+            AgentPlaceholder => ("Message the simulated assistant…", "给模拟助手发消息…"),
+            AgentEmptyTitle => ("Nothing in this session yet", "这个会话还没有内容"),
+            // 空会话是最容易被误读的一屏（没有人说过话，很容易以为是「连上了但还没问」）
+            AgentEmptyBody => ("Ask about instances, downloads or logs. This assistant is simulated: no real model is connected.", "可以问实例、下载或日志。当前是模拟助手，没有接真实模型。"),
+            AgentNotePending => ("Placeholder shell: your message is kept here, nothing was sent to a model.", "占位外壳：消息留在这里，没有发给任何模型。"),
+            AgentNoteStopped => ("Stopped by you.", "你中断了这次回复。"),
+            AgentUnread => ("{count} unread", "{count} 条未读"),
+            AgentResize => ("Drag to resize the assistant rail", "拖动调整助手栏宽度"),
+            AgentWidthLabel => ("Width {width}", "宽度 {width}"),
+            AgentRoleYou => ("You", "你"),
+            AgentRoleAssistant => ("Assistant", "助手"),
+            AgentRoleNotice => ("Notice", "提示"),
+            // ── M119：失败态与写操作确认（接线后才有；`AgentRail::error` / `rail.confirm`）
+            //
+            // 为什么必须成 key：任务要求「presenter 出错时 UI 显示**具名**错误」，
+            // 而 M106 立的规矩是界面文案一律走 catalog——没有键就只能硬编码中英。
+            AgentErrorTitle => ("Assistant error", "助手出错"),
+            AgentErrorUnavailable => ("Couldn't reach the assistant backend. Check the endpoint, then try again.", "连不上助手后端：检查端点后重试。"),
+            AgentErrorNotImplemented => ("This assistant request isn't wired up yet.", "这个助手请求还没接线。"),
+            AgentConfirmRequest => ("The assistant wants to change something: {summary}", "助手想改一项设置：{summary}"),
+            AgentConfirmAllow => ("Allow", "允许"),
+            AgentConfirmDeny => ("Deny", "拒绝"),
+            // 头部常驻小标记（P2-1）：与副标题/占位符互为冗余，三个位置都能看到「这是模拟」
+            AgentSimulated => ("Simulated", "模拟"),
+            // ── M119 r2：三处文案的**真实态**配对（模拟态用上面那三条已有的 key）
+            //
+            // 复审 r2 的 P2-1：上一轮只有标题胶囊由 `simulated` 驱动，副标题/占位符/空态正文是
+            // 无条件取词，而那三条译文里写着「模拟 / 没接真实模型」——接上真 transport 之后
+            // 这三句会**反方向**地留着。现在配成对：`simulated == true` 走模拟态，
+            // `false` 走这三条中性话（`pages/agent/tests/disclaimer.rs` 钉住四处一起变）。
+            AgentSubtitleReal => ("Conversation", "会话"),
+            AgentPlaceholderReal => ("Message the assistant…", "给助手发消息…"),
+            AgentEmptyBodyReal => ("Ask about instances, downloads or logs.", "可以问实例、下载或日志。"),
+        } }
+    };
+}
+
+pub(crate) use agent_entries;
diff --git a/crates/i18n/src/catalog/content.rs b/crates/i18n/src/catalog/content.rs
new file mode 100644
index 0000000..0f492a8
--- /dev/null
+++ b/crates/i18n/src/catalog/content.rs
@@ -0,0 +1,269 @@
+//! 内容库文案（M109 `CONTENTDL`）。
+//!
+//! 一句话一个 key：带变量的句子用 `{name}`，页面只做 [`crate::Catalog::render`]，不拼片段。
+//!
+//! ## 三条口径
+//!
+//! 1. **只说能做的事**：整合包那条写的是「要等导入管线」，不是「稍后自动支持」；
+//! 2. **站名也进词表**：`Modrinth` / `CurseForge` 的**中文译文必须与英文不同**
+//!    （`catalog/tests.rs` 的 `chinese_catalog_is_actually_chinese` 会红），所以中文写成「Modrinth 源」；
+//! 3. **禁用态要能解释自己**：`ContentIncompatible*` / `ContentModpackNotReady` 就是禁用按钮旁边那几句话——
+//!    没有它们，禁用就等于「点了没反应」。
+//!
+//! 域文件的形状见 `crate::catalog` 的「域装配」一节。
+
+macro_rules! content_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* {
+            $($acc)*
+            // --- content library page (M109) ---
+            ContentTitle => ("Content", "内容库"),
+            ContentSubtitle => (
+                "Modpacks, mods, resource packs and shaders",
+                "整合包、Mod、资源包与光影"
+            ),
+            ContentSectionVersions => ("Version management", "版本管理"),
+            ContentSectionContent => ("Content library", "内容库"),
+            ContentKindModpack => ("Modpacks", "整合包"),
+            ContentKindMod => ("Mods", "Mod"),
+            ContentKindResourcepack => ("Resource packs", "资源包"),
+            ContentKindShader => ("Shaders", "光影"),
+            ContentSourceModrinth => ("Modrinth", "Modrinth 源"),
+            ContentSourceCurseforge => ("CurseForge", "CurseForge 源"),
+            ContentSortRelevance => ("Relevance", "相关度"),
+            ContentSortDownloads => ("Downloads", "下载量"),
+            ContentSortNewest => ("Newest", "最新发布"),
+            ContentSortUpdated => ("Recently updated", "最近更新"),
+            ContentSearchPlaceholder => ("Search content…", "搜索内容…"),
+            ContentSearch => ("Search", "搜索"),
+            ContentFilterVersion => ("Game version", "游戏版本"),
+            ContentFilterLoader => ("Loader", "加载器"),
+            ContentFilterAny => ("Any", "不限"),
+            ContentCount => ("{count} results", "{count} 个结果"),
+            ContentLoading => ("Loading content…", "正在加载内容…"),
+            ContentLoadingHint => (
+                "Results come from the network; nothing is cached offline yet.",
+                "结果来自网络，暂时没有离线缓存。"
+            ),
+            ContentEmptyTitle => ("Nothing matched", "没有匹配的内容"),
+            ContentEmptyBody => (
+                "Try another keyword, or clear a filter.",
+                "换个关键词，或清掉一个筛选条件。"
+            ),
+            ContentFailedTitle => ("Could not load content", "内容加载失败"),
+            ContentFailedBody => ("Check the network, then retry.", "检查网络后重试。"),
+            ContentRetry => ("Retry", "重试"),
+            ContentLoadMore => ("Load more", "加载更多"),
+            ContentNoMore => ("No more results", "没有更多了"),
+            ContentDetailEmpty => (
+                "Pick an item to see what it supports.",
+                "选一个项目看它支持什么。"
+            ),
+            ContentDetailDownloads => ("{count} downloads", "下载量 {count}"),
+            ContentDetailUpdated => ("Updated {date}", "更新于 {date}"),
+            ContentDetailLoaders => ("Loaders: {list}", "加载器：{list}"),
+            ContentDetailVersions => ("Game versions: {list}", "游戏版本：{list}"),
+            ContentInstall => ("Install into instance", "装入实例"),
+            ContentTargetInstance => ("Target instance", "目标实例"),
+            ContentNoInstances => ("No instance to install into", "没有可装入的实例"),
+            ContentIncompatibleVersion => (
+                "Needs {version}; this instance runs {actual}",
+                "需要 {version}，该实例运行的是 {actual}"
+            ),
+            ContentIncompatibleLoader => ("Not built for {loader}", "不支持 {loader}"),
+            ContentModpackNotReady => (
+                "Installing modpacks from the library into an instance is not available yet",
+                "从内容库一键安装整合包到实例还没做（本地的包可以直接导入）"
+            ),
+            ContentSourceUnavailable => (
+                "CurseForge needs an API key: add one in Settings",
+                "CurseForge 需要在设置里配置密钥才能搜索"
+            ),
+            ContentSourceNotWired => (
+                "Installing from CurseForge is not available yet",
+                "CurseForge 来源的安装尚未开放"
+            ),
+            // --- M113: pack import / export（PACKUI）---
+            PackTitle => ("Modpack import & export", "整合包导入 / 导出"),
+            PackImportTitle => ("Import a modpack", "导入整合包"),
+            PackDropHint => (
+                "Drop a .mrpack, .zip or a MultiMC/Prism instance folder here",
+                "把 .mrpack / .zip 或 MultiMC·Prism 实例目录拖到这里"
+            ),
+            PackDropActive => ("Release to probe the pack", "松手开始探测"),
+            PackNoDialog => (
+                "This build has no system file picker: drag the file in, or paste its path below.",
+                "本版没有系统文件选择框：请把文件拖进来，或在下面粘贴路径。"
+            ),
+            PackPathLabel => ("Pack path", "整合包路径"),
+            PackPathPlaceholder => (
+                "D:\\packs\\Better MC.mrpack",
+                "D:\\整合包\\更好的MC.mrpack"
+            ),
+            PackImportAction => ("Import", "导入"),
+            PackCancel => ("Cancel import", "取消导入"),
+            PackDismiss => ("Dismiss", "关闭"),
+            PackTargetLabel => ("Install into", "装到实例"),
+            PackTargetNew => ("New instance", "新建实例"),
+            PackInstanceName => ("Instance name", "实例名"),
+            PackStageLine => ("Step {index}/{total} · {stage}", "步骤 {index}/{total} · {stage}"),
+            PackStageProbe => ("Reading the manifest", "读取清单"),
+            PackStageExtract => ("Unpacking overrides", "解包覆盖内容"),
+            PackStageFetch => ("Fetching missing files", "补下载文件"),
+            PackStageCommit => ("Writing files", "落地写盘"),
+            PackStageRegister => ("Registering the instance", "登记实例"),
+            PackProbeTitle => (
+                "This pack is almost a known format",
+                "这个包差一点就是已知格式"
+            ),
+            PackProbeLooksLike => (
+                "Looks like {format}, but missing: {missing}",
+                "看起来像 {format}，但缺：{missing}"
+            ),
+            PackProbeUnknown => (
+                "No known format claims this pack",
+                "没有任何已知格式认领这个包"
+            ),
+            PackProbeSaw => ("Found in the pack: {saw}", "包里看到：{saw}"),
+            PackProbeNothing => ("nothing recognisable", "没有可识别的东西"),
+            PackStatusSuccess => ("Imported", "已导入"),
+            PackStatusPartial => ("Imported with gaps", "导入完成，但有缺口"),
+            PackStatusFailed => ("Import failed — rolled back", "导入失败 —— 已整包回滚"),
+            PackReportWritten => ("Files written: {count} · {bytes}", "{count} 个文件已写盘 · {bytes}"),
+            PackReportMissing => (
+                "Could not fetch (tolerated): {count}",
+                "有 {count} 个文件没搞到（可容忍）"
+            ),
+            PackReportConflicts => (
+                "Conflicts: {count}",
+                "冲突：{count} 个"
+            ),
+            PackReportRejected => (
+                "The client does not support these: {count}",
+                "这些组件客户端不支持：{count} 个"
+            ),
+            PackReportRejectedNote => ("not supported by the client", "客户端不支持"),
+            PackCancelled => (
+                "Import keeps running in the background — this result is discarded. Files already written stay.",
+                "导入会在后台继续跑完 —— 本次结果作废；已经写下的文件会留下。"
+            ),
+            PackOverwriteAction => ("Re-import, the pack wins", "以包为准重新导入"),
+            PackOverwriteNote => (
+                "Keeping both (renamed) is not supported yet: the import pipeline has one global conflict policy and no per-file decision channel.",
+                "「两者都留（改名）」暂不支持：导入管线只有一套全局冲突策略，没有逐文件决策通道。"
+            ),
+            PackMissingOffline => ("offline import", "离线导入"),
+            PackMissingNoSource => (
+                "no download source available yet",
+                "暂时拿不到下载地址"
+            ),
+            PackMissingFetchFailed => ("download failed: {detail}", "下载失败：{detail}"),
+            PackFatalTitle => (
+                "Rolled back — nothing was left behind",
+                "已回滚 —— 目标目录零残留"
+            ),
+            PackFatalHint => ("What to try next", "下一步可以试"),
+            PackConflictUserModified => ("you changed it", "你改过"),
+            PackConflictUserDeleted => ("you deleted it", "你删过"),
+            PackConflictPreExisting => ("was already there", "本来就在"),
+            PackChoiceKeepUser => ("kept yours", "保留我的"),
+            PackChoiceOverwrite => ("pack version used", "用包里的"),
+            PackConflictHashes => (
+                "pack {pack} · base {base} · disk {disk}",
+                "包内 {pack} · 基线 {base} · 磁盘 {disk}"
+            ),
+            PackConflictDetail => ("Hashes", "三方哈希"),
+            PackFormatModrinth => ("Modrinth .mrpack", "Modrinth 的 .mrpack"),
+            PackFormatCurseforge => ("CurseForge manifest", "CurseForge 清单"),
+            PackFormatMultimc => ("MultiMC / Prism instance", "MultiMC·Prism 实例"),
+            PackExportTitle => ("Export this instance", "导出这个实例"),
+            PackExportOpen => ("Export…", "导出…"),
+            PackExportFormat => ("Format", "格式"),
+            PackExportName => ("Pack name", "包名"),
+            PackExportVersion => ("Version", "版本"),
+            PackExportOutput => ("Save to", "保存到"),
+            PackExportOutputPlaceholder => (
+                "empty = suggested path",
+                "留空 = 自动给一个路径"
+            ),
+            PackExportPrecheck => ("Dry run", "预检"),
+            PackExportConfirm => ("Write the pack", "确认写盘"),
+            PackExportAbort => ("Back", "返回"),
+            PackExportMultimcNote => (
+                "MultiMC/Prism can only be imported, not exported (by design).",
+                "MultiMC·Prism 只能导入、不能导出（有意省略）。"
+            ),
+            PackExportDone => ("Wrote {path} · {bytes}", "已写出 {path} · {bytes}"),
+            PackExportFailed => ("Export failed: {reason}", "导出失败：{reason}"),
+            PackExportPending => ("Scanning the instance…", "正在扫描实例…"),
+            PackPreviewHead => (
+                "Will inline {inline} files · cannot export: {skipped}",
+                "将内联 {inline} 个文件 · 无法导出 {skipped} 项"
+            ),
+            PackPreviewRemote => (
+                "{count} files can be referenced remotely",
+                "{count} 个文件可走远程引用"
+            ),
+            PackPreviewInlineBytes => (
+                "{bytes} copied into overrides/",
+                "{bytes} 会原样拷进 overrides/"
+            ),
+            PackPreviewInlineTitle => (
+                "Copied into overrides/ (first {shown}):",
+                "原样拷进 overrides/（只列前 {shown} 个）："
+            ),
+            PackPreviewSkippedTitle => (
+                "Not in the pack: {count}",
+                "没进包：{count} 项"
+            ),
+            PackPreviewNotes => ("Known losses", "已知损失"),
+            PackPreviewTarget => ("Will be written to {path}", "将写到 {path}"),
+            PackPreviewMore => (
+                "…and {count} more files (not shown here)",
+                "…还有 {count} 个文件（这里不展开）"
+            ),
+            PackPreviewComplete => ("Nothing is left out", "没有遗漏任何文件"),
+            PackPreviewIncomplete => (
+                "Some files will not be in the pack",
+                "有文件不会进包"
+            ),
+            PackReasonModrinthSha1 => ("Modrinth match (SHA-1)", "Modrinth 命中（SHA-1）"),
+            PackReasonCurseFingerprint => (
+                "CurseForge match (fingerprint)",
+                "CurseForge 命中（文件指纹）"
+            ),
+            PackReasonNoRemoteMatch => (
+                "unknown to both catalogs, inlined",
+                "两个目录都不认识，已内联"
+            ),
+            PackReasonCurseOnly => (
+                "only CurseForge knows it, this format cannot use it, inlined",
+                "只有 CF 认识，目标格式用不上，已内联"
+            ),
+            PackReasonModrinthOnly => (
+                "only Modrinth knows it, the CF manifest cannot use it, inlined",
+                "只有 Modrinth 认识，CF 清单用不上，已内联"
+            ),
+            PackReasonMissingSha512 => (
+                "the catalogue entry has no sha512 hash, inlined",
+                "命中缺 sha512，已内联"
+            ),
+            PackReasonMissingCurseIds => (
+                "the catalogue entry has no CurseForge ids, inlined",
+                "命中缺 projectID/fileID，已内联"
+            ),
+            PackReasonDisabled => (
+                "disabled file, this format cannot express it (.disabled kept)",
+                "禁用文件，目标格式表达不了（保留 .disabled）"
+            ),
+            PackReasonSymlink => ("symbolic link, skipped", "符号链接，已跳过"),
+            PackReasonUnsafePath => (
+                "path fails the pack path rules, skipped",
+                "路径过不了包内规整，已跳过"
+            ),
+            PackReasonUnreadable => ("cannot read it, skipped", "读不出来，已跳过"),
+        } }
+    };
+}
+
+pub(crate) use content_entries;
diff --git a/crates/i18n/src/catalog/core_text.rs b/crates/i18n/src/catalog/core_text.rs
new file mode 100644
index 0000000..e7ad863
--- /dev/null
+++ b/crates/i18n/src/catalog/core_text.rs
@@ -0,0 +1,15 @@
+//! core / presenter 只给了中文串、UI 又不许画原文时的兜底文案（口径见 [`crate::bridge`]）。
+//!
+//! 域文件的形状见 [`crate::catalog`] 的「域装配」一节。
+
+macro_rules! core_text_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* {
+            $($acc)*
+            // ── core / presenter 只给了中文串、UI 又不许画原文时的兜底（见 `bridge`）
+            CoreTextUntranslated => ("[system text not translated]", "［未翻译的系统文案］"),
+        } }
+    };
+}
+
+pub(crate) use core_text_entries;
diff --git a/crates/i18n/src/catalog/download.rs b/crates/i18n/src/catalog/download.rs
new file mode 100644
index 0000000..b6614e4
--- /dev/null
+++ b/crates/i18n/src/catalog/download.rs
@@ -0,0 +1,150 @@
+//! 版本管理页文案（M94 建页时叫「下载页」，M108 起显示名改成「版本管理」）。
+//!
+//! 一句话一个 key：带变量的句子用 `{name}`，页面只做 [`crate::Catalog::render`]，不拼片段
+//! （[`crate::bridge`] 的规矩 1）。
+//!
+//! 文案口径（M94 r1 / P2-2）：**只说这个页面真能做到的动作**（切分类、刷新、看日志），
+//! 不写「稍后会自动重试」这类 UI 没有的能力，也不拿文案去补功能。
+//!
+//! **「下载」字样不许再指向这一页**（M108 用户令）：这一页管的是「版本与加载器」，用户点它
+//! 不是为了下载点什么。唯一的例外是 [`Key::DownloadStageDownloading`]——那是安装流程里**真在
+//! 传文件**的那一步，说的不是页面身份而是当时的动作，留着才对（守门见 `pages/tests.rs` 的
+//! `the_download_route_is_presented_as_version_management`，它把本域每条 key 的两种语言都扫一遍）。
+//!
+//! 域文件的形状见 [`crate::catalog`] 的「域装配」一节。
+
+macro_rules! download_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* {
+            $($acc)*
+            // --- version management page (M94; renamed in M108) ---
+            DownloadTitle => ("Version management", "版本管理"),
+            // 例外说明（M108 复审 p3）：副标题承诺「安装、升级、修复」，但页面目前只有
+            // 「选版本 → 安装」一条路，「修复」与「加载器选择」都还没有入口
+            // （`InstallView::of` 连 `InstallProgressView.loader` 都没读）。
+            // 这是用户令（2026-11-04）定的口径，能力由 M105 / M113 补齐；
+            // 补齐之前不许拿这句话当已实现功能宣传。
+            DownloadSubtitle => (
+                "Manage versions and loaders: install, upgrade, repair",
+                "管理版本与加载器：安装、升级、修复"
+            ),
+            DownloadRefresh => ("Refresh", "刷新"),
+            DownloadInstall => ("Install", "安装"),
+            DownloadCancel => ("Cancel install", "取消安装"),
+            DownloadInstalled => ("Installed", "已安装"),
+            DownloadCount => ("{count} versions", "{count} 个版本"),
+            DownloadRowSupporting => ("{kind} · released {date}", "{kind} · 发布于 {date}"),
+            DownloadSelectHint => ("Pick a version, then install", "选一个版本再安装"),
+            DownloadLoading => ("Loading versions…", "正在加载版本列表…"),
+            DownloadLoadingHint => (
+                "If this stays here, press Refresh in the top right.",
+                "如果一直停在这里，点右上角的刷新。"
+            ),
+            DownloadEmptyTitle => ("No versions to show", "没有可显示的版本"),
+            DownloadEmptyBody => (
+                "Pick another category, or refresh the list.",
+                "换一个分类，或刷新一次列表。"
+            ),
+            DownloadCategoryAll => ("All", "全部"),
+            DownloadCategoryRelease => ("Release", "正式版"),
+            DownloadCategorySnapshot => ("Snapshot", "预览版"),
+            DownloadCategoryAncient => ("Ancient", "远古版"),
+            DownloadStagePlanning => ("Planning", "解析版本"),
+            DownloadStageDownloading => ("Downloading files", "下载文件"),
+            DownloadStageInstalling => ("Building the version", "生成版本"),
+            DownloadStageRegistering => ("Registering the instance", "登记实例"),
+            DownloadStageDone => ("Done", "已完成"),
+            DownloadStageFailed => ("Install failed", "安装失败"),
+            DownloadStageCancelled => ("Install cancelled", "安装已取消"),
+            DownloadProgress => (
+                "{done}/{total} files",
+                "{done}/{total} 文件"
+            ),
+            DownloadProgressUnknown => ("Waiting for the first file…", "等第一个文件…"),
+            // 速率与剩余时间是两个独立短语，各占一个 key（`DownloadRate` 只负责把它们排成一行）
+            DownloadRate => ("{speed} · {eta}", "{speed}，{eta}"),
+            DownloadEtaSecs => ("{secs}s left", "剩 {secs}s"),
+            DownloadEtaMins => ("{mins}m{secs}s left", "剩 {mins}m{secs}s"),
+            DownloadFailedHint => (
+                "The Logs page has the full reason.",
+                "完整原因在日志页。"
+            ),
+            DownloadOpenLogs => ("Open logs", "打开日志"),
+            DownloadDismiss => ("Dismiss", "关闭"),
+            // --- 安装选项（M105）---
+            DownloadOptionsTitle => ("Install options", "安装选项"),
+            DownloadOptionsLoaderVersion => ("Loader version", "加载器版本"),
+            DownloadOptionsLoaderVersionsLoading => (
+                "Fetching loader versions…",
+                "正在获取加载器版本…"
+            ),
+            DownloadOptionsLoaderVersionsFailed => (
+                "Could not fetch loader versions: {reason}",
+                "取不到加载器版本：{reason}"
+            ),
+            DownloadOptionsLoaderVersionsEmpty => (
+                "No loader builds published for {version}",
+                "官方没有为 {version} 发布加载器版本"
+            ),
+            DownloadOptionsInstanceName => ("Instance name", "实例名"),
+            DownloadOptionsInstanceNameHint => (
+                "Empty = use the version id",
+                "留空就用版本号"
+            ),
+            DownloadOptionsIncompatible => (
+                "{loader} has no builds for {version}",
+                "{loader} 没有适配 {version} 的构建"
+            ),
+            DownloadOptionsNeedsAtLeast => (
+                "{loader} needs Minecraft {min} or newer",
+                "{loader} 需要 Minecraft {min} 或更新"
+            ),
+            DownloadCancelled => (
+                "Install cancelled — finished files are kept, the instance was not created",
+                "安装已取消 —— 已下好的文件保留，实例未登记"
+            ),
+        } }
+    };
+}
+
+pub(crate) use download_entries;
+
+/// **M107 版本管理页**的侧栏 / 搜索文案。
+///
+/// 为什么单独一个宏、并**接在装配链最后**：`catalog/golden.rs` 是「`Key` 声明顺序 × 译文」的逐字节
+/// 快照，M107 的纪律是**只追加不重排**。把新 key 插在 `download_entries` 中间会让 `Key::ALL`
+/// 的顺序在 `DownloadDismiss` 与 `LogsSubtitleIdle` 之间断开，金表就得整体重排（那正是要避免的
+/// 风险）。追加在链尾 ⇒ 新 key 落在 `Key::ALL` 末尾 ⇒ 金表末尾追加同样几行即可。
+macro_rules! version_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* {
+            $($acc)*
+            // --- version management page (M107) ---
+            VersionRailTitle => ("Version type", "版本类型"),
+            VersionMajorTitle => ("Major version", "主版本"),
+            VersionMajorAll => ("All versions", "全部版本"),
+            VersionSearchPlaceholder => ("Search version numbers", "搜版本号"),
+            VersionSearchClear => ("Clear search", "清空搜索"),
+            VersionSearchHits => ("{count} matches", "{count} 个匹配"),
+            VersionSearchEmptyTitle => ("No matching versions", "没有匹配的版本"),
+            VersionSearchEmptyBody => (
+                "Try a shorter piece of the number — 1.21, 24w, a1.",
+                "试试更短的片段 — 1.21、24w、a1。"
+            ),
+            VersionSearchElsewhere => (
+                "{count} versions match, but they are in another type.",
+                "有 {count} 个版本匹配，但它们在别的类型里。"
+            ),
+            VersionSearchElsewhereAction => ("Show all types", "看全部类型"),
+            // --- M107 r2：复数口径与「在别处」的标题（追加在域尾 ⇒ `Key::ALL` 顺序只增不动） ---
+            VersionSearchHitsOne => ("1 match", "1 个匹配"),
+            VersionSearchElsewhereTitle => ("Found in another type", "在别的类型里找到了"),
+            VersionSearchElsewhereOne => (
+                "1 version matches, but it is in another type.",
+                "有 1 个版本匹配，但它在别的类型里。"
+            ),
+        } }
+    };
+}
+
+pub(crate) use version_entries;
diff --git a/crates/i18n/src/catalog/font.rs b/crates/i18n/src/catalog/font.rs
new file mode 100644
index 0000000..4fc8f70
--- /dev/null
+++ b/crates/i18n/src/catalog/font.rs
@@ -0,0 +1,24 @@
+//! 中文字体文案（D28）：中文环境缺字体时的下载提示 / 失败回退。
+//!
+//! 域文件的形状见 [`crate::catalog`] 的「域装配」一节。
+
+macro_rules! font_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* {
+            $($acc)*
+            // ── 中文字体（D28：中文环境缺字体时的下载提示 / 失败回退）
+            FontCjkNeedsDownload => (
+                "No Chinese font found on this system. Download an open-source (OFL) Chinese font?",
+                "系统里没找到中文字体。要下载一套开源（OFL）中文字体吗？"
+            ),
+            FontCjkDownloading => ("Downloading Chinese font… {percent}%", "正在下载中文字体… {percent}%"),
+            FontCjkDownloadFailed => (
+                "Chinese font download failed; the interface stays in English.",
+                "中文字体下载失败，界面暂时保持英文。"
+            ),
+            FontCjkReady => ("Chinese font ready: {family}", "中文字体已就绪：{family}"),
+        } }
+    };
+}
+
+pub(crate) use font_entries;
diff --git a/crates/i18n/src/catalog/general.rs b/crates/i18n/src/catalog/general.rs
new file mode 100644
index 0000000..8724c3a
--- /dev/null
+++ b/crates/i18n/src/catalog/general.rs
@@ -0,0 +1,60 @@
+//! 设置页 General 分组**真控件**的文案（M106 `I18NFOLLOW`）：语言选择器 + 其余三行。
+//!
+//! ## 与 `catalog/settings/general.rs` 的分工
+//!
+//! `catalog/settings/general.rs`（M99 建的）只有两条**标题**（[`SettingsLanguage`] /
+//! [`SettingsLanguageHint`]），是设置页五域装配的一部分；本文件是 M106 接真控件时新增的
+//! **选择器文案**：三档选项名、选中后的「界面当前使用」回显，以及 General 分组里另外三行
+//! （主题 / 启动页 / 关闭按钮）。
+//!
+//! 为什么要分两个文件：`catalog.rs` 的装配链是**追加**式的，新域挂在链尾就不会动到既有
+//! `Key` 的顺序（= `catalog/golden.rs` 那张逐字节金表）。两个文件同属 General 分组，读代码时
+//! 按「标题 vs 选项」区分即可；真要合并也是一个文件搬十行的活，不急着在接线的 mission 里做。
+//!
+//! ## 选项名为什么不是「语言自称」
+//!
+//! 常见做法是三档都写 `简体中文` / `English` 这样的自称。这里没有：`catalog/tests.rs` 有一条
+//! `chinese_catalog_is_actually_chinese`（英文表与中文表逐 key 必须不同），自称会让「中文表里
+//! 写着 English」被判成漏译。所以选项名**跟着界面语言走**：中文界面「跟随系统 / 简体中文 / 英文」，
+//! 英文界面 "Follow system / Chinese (Simplified) / English"——这也是多数启动器的做法。
+//!
+//! 域文件的形状见 [`crate::catalog`] 的「域装配」一节。
+
+macro_rules! general_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* {
+            $($acc)*
+            // ── General 分组（语言选择器 + 其余三行）
+            SettingsLanguageFollowSystem => ("Follow system", "跟随系统"),
+            SettingsLanguageZhCn => ("Chinese (Simplified)", "简体中文"),
+            SettingsLanguageEn => ("English", "英文"),
+            SettingsLanguageEffective => ("Interface right now: {language}", "界面当前使用：{language}"),
+            SettingsTheme => ("Theme", "主题"),
+            SettingsThemeFollowSystem => ("Follow system", "跟随系统"),
+            SettingsStartupPage => ("Startup page", "启动页"),
+            SettingsStartupInstances => ("Instances", "实例"),
+            SettingsCloseButton => ("Close button", "关闭按钮"),
+            SettingsCloseToTray => ("Exit to tray", "退出到托盘"),
+            // 设置页页头（M106）：标题复用 `NavSettings`，这三条是副标题与两个动作。
+            SettingsSubtitle => ("Launcher behaviour, Java runtimes and download sources", "启动器行为、Java 运行时与下载源"),
+            SettingsResetSection => ("Reset section", "重置本组"),
+            SettingsSave => ("Save", "保存"),
+            // 第五条导航项（M106 给导航轨补的最后一条）。放在本域而不是 `catalog/nav.rs`：
+            // 金表按**位置**逐字节比，插进 nav 域会把既有 4 条导航行整体平移一位。
+            NavAi => ("Assistant", "助手"),
+            // 设置页左列的分组名（M106）。`Group.name` 是**id**（测试按它认组），显示名走这里。
+            SettingsGroupGeneral => ("General", "通用"),
+            SettingsGroupAppearance => ("Appearance", "外观"),
+            SettingsGroupJava => ("Java", "Java 运行时"),
+            SettingsGroupDownloads => ("Downloads", "下载"),
+            // 逐实例覆盖的空态（M106）
+            SettingsOverridesEmptyTitle => ("No per-instance overrides", "没有逐实例覆盖"),
+            SettingsOverridesEmptyBody => ("Overrides let one instance keep its own Java runtime, memory or JVM flags while the rest of the launcher keeps the defaults above.", "逐实例覆盖让某个实例保留自己的 Java 运行时、内存或 JVM 参数，其余实例沿用上面的默认值。"),
+            SettingsOverridesAdd => ("Add override", "新增覆盖"),
+            // `Route::Agent` 的回退卡正文（M106：`app/view.rs` 里最后一条硬编码英文）
+            AgentFallbackBody => ("The assistant page is not built yet. Chat lives in the docked panel once the AI mission lands; this screen is the M68 skeleton fallback.", "助手页还没做。AI 接线落地后对话会出现在右侧停靠面板；这一屏是 M68 的骨架回退。"),
+        } }
+    };
+}
+
+pub(super) use general_entries;
diff --git a/crates/i18n/src/catalog/golden.rs b/crates/i18n/src/catalog/golden.rs
new file mode 100644
index 0000000..9b24afb
--- /dev/null
+++ b/crates/i18n/src/catalog/golden.rs
@@ -0,0 +1,399 @@
+//! 金表的**表数据**（`Key::ALL` 顺序 × (en, zh-CN) 的逐字快照）。「为什么有这张表、它抓得住
+//! 什么」全在 `catalog.rs` 的 `mod golden;` 文档里——本文件只放数据，是因为每加一条 key 就多一行。
+
+/// 拆分前 `Key::ALL` 的顺序 × (en, zh-CN)。第一列是变体名（`Key::name()` 的返回值）。
+pub(super) const GOLDEN: &[(&str, &str, &str)] = &[
+    ("NavInstances", "Instances", "实例"),
+    ("NavDownload", "Versions", "版本管理"),
+    ("NavDownloadExpanded", "Version management", "版本管理"),
+    ("NavLogs", "Logs", "日志"),
+    ("NavSettings", "Settings", "设置"),
+    ("InstancesNew", "New instance", "新建实例"),
+    ("InstancesImport", "Import", "导入"),
+    ("InstancesBack", "Back to instances", "返回实例列表"),
+    ("InstancesPlay", "Play", "启动"),
+    ("InstancesEmptyTitle", "No instance selected", "未选择实例"),
+    ("InstancesEmptyBody", "Pick an instance on the left to see its version, loader and launch options.", "在左侧选择一个实例，查看它的版本、加载器与启动选项。"),
+    ("InstancesTitle", "Instances", "实例"),
+    ("InstancesSubtitle", "Local versions and their mod loaders", "本地版本与它们的模组加载器"),
+    ("InstancesAllTitle", "ALL INSTANCES", "全部实例"),
+    ("InstancesStop", "Stop", "停止"),
+    ("InstancesDuplicate", "Duplicate", "复制"),
+    ("InstancesOpenFolder", "Open folder", "打开文件夹"),
+    ("InstancesDelete", "Delete", "删除"),
+    ("InstancesNarrowNote", "Below 840 px the list and the detail share one column, so opening an instance replaces this screen (full-page switch). Widen the window to see both panes again.", "窗口窄于 840 像素时，列表与详情共用一列：打开一个实例会整页替换这一屏（整页切换）。把窗口拉宽就能重新同时看见两栏。"),
+    ("InstancesMetaVersion", "VERSION", "版本"),
+    ("InstancesMetaLoader", "LOADER", "加载器"),
+    ("InstancesMetaMemory", "MEMORY", "内存"),
+    ("InstancesMetaJava", "JAVA", "Java"),
+    ("InstancesMetaMods", "MODS", "模组"),
+    ("InstancesMetaIsolation", "ISOLATION", "隔离方式"),
+    ("InstancesMetaVersionId", "VERSION ID", "版本标识"),
+    ("InstancesMetaFiles", "FILES", "文件"),
+    ("InstancesMetaLastPlayed", "LAST PLAYED", "上次游玩"),
+    ("InstancesPresentOnDisk", "Present on disk", "已在磁盘上"),
+    ("InstancesMissing", "Missing", "缺失"),
+    ("InstancesNeverPlayed", "Never", "从未游玩"),
+    ("InstancesIsolationIsolated", "Isolated", "独立目录"),
+    ("InstancesIsolationShared", "Shared", "共用目录"),
+    ("InstancesRunning", "Running · pid {pid}", "运行中 · pid {pid}"),
+    ("InstancesFailed", "Launch failed · {reason}", "启动失败 · {reason}"),
+    ("InstancesStageDownload", "Downloading", "下载中"),
+    ("InstancesStageVerify", "Verifying", "校验中"),
+    ("InstancesStageLaunch", "Starting", "启动中"),
+    ("InstancesStageWindow", "Waiting for window", "等待游戏窗口"),
+    ("LoaderVanilla", "Vanilla", "原版"),
+    ("LaunchOutcomeNormal", "Finished normally", "正常结束"),
+    ("LaunchOutcomeCrash", "The game crashed", "游戏崩溃"),
+    ("LaunchOutcomeSilent", "Suspected silent failure: exit code 0, but the game never really started", "疑似静默失败：退出码 0，但游戏没真正跑起来"),
+    ("LaunchFailedWithCode", "Launch failed (exit {code}): {reason}", "启动失败（退出码 {code}）：{reason}"),
+    ("LaunchMsaNotConfigured", "Microsoft sign-in is not configured: it needs an Azure public client id (the login flow itself is implemented). Build with ULL_MSA_CLIENT_ID=, 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.", "切换界面语言。显示中文需要中文字体。"),
+    ("SettingsAppearanceCorner", "Window corners", "窗口圆角"),
+    ("SettingsAppearanceCornerSystem", "Follow system", "跟随系统"),
+    ("SettingsAppearanceCornerSquare", "Square", "直角"),
+    ("SettingsAppearanceCornerHint", "On Windows 11 and Server 2025 we ask the system for rounded corners; Windows 10 keeps square corners. On macOS and Linux the desktop's own rules apply. We never draw corners ourselves.", "Windows 11 与 Windows Server 2025 上我们请求系统处理外框圆角；Windows 10 保持直角；macOS 与 Linux 交给桌面合成器自己的规则；我们不自己画圆角。"),
+    ("SettingsAppearanceCornerSuspended", "Not in effect right now: window transparency is below 100%. Setting it back to 100% restores the rounded corners.", "当前因整窗透明度不生效：把整窗透明度调回 100% 圆角即恢复。"),
+    ("CoreTextUntranslated", "[system text not translated]", "［未翻译的系统文案］"),
+    ("DownloadTitle", "Version management", "版本管理"),
+    ("DownloadSubtitle", "Manage versions and loaders: install, upgrade, repair", "管理版本与加载器：安装、升级、修复"),
+    ("DownloadRefresh", "Refresh", "刷新"),
+    ("DownloadInstall", "Install", "安装"),
+    ("DownloadCancel", "Cancel install", "取消安装"),
+    ("DownloadInstalled", "Installed", "已安装"),
+    ("DownloadCount", "{count} versions", "{count} 个版本"),
+    ("DownloadRowSupporting", "{kind} · released {date}", "{kind} · 发布于 {date}"),
+    ("DownloadSelectHint", "Pick a version, then install", "选一个版本再安装"),
+    ("DownloadLoading", "Loading versions…", "正在加载版本列表…"),
+    ("DownloadLoadingHint", "If this stays here, press Refresh in the top right.", "如果一直停在这里，点右上角的刷新。"),
+    ("DownloadEmptyTitle", "No versions to show", "没有可显示的版本"),
+    ("DownloadEmptyBody", "Pick another category, or refresh the list.", "换一个分类，或刷新一次列表。"),
+    ("DownloadCategoryAll", "All", "全部"),
+    ("DownloadCategoryRelease", "Release", "正式版"),
+    ("DownloadCategorySnapshot", "Snapshot", "预览版"),
+    ("DownloadCategoryAncient", "Ancient", "远古版"),
+    ("DownloadStagePlanning", "Planning", "解析版本"),
+    ("DownloadStageDownloading", "Downloading files", "下载文件"),
+    ("DownloadStageInstalling", "Building the version", "生成版本"),
+    ("DownloadStageRegistering", "Registering the instance", "登记实例"),
+    ("DownloadStageDone", "Done", "已完成"),
+    ("DownloadStageFailed", "Install failed", "安装失败"),
+    ("DownloadStageCancelled", "Install cancelled", "安装已取消"),
+    ("DownloadProgress", "{done}/{total} files", "{done}/{total} 文件"),
+    ("DownloadProgressUnknown", "Waiting for the first file…", "等第一个文件…"),
+    ("DownloadRate", "{speed} · {eta}", "{speed}，{eta}"),
+    ("DownloadEtaSecs", "{secs}s left", "剩 {secs}s"),
+    ("DownloadEtaMins", "{mins}m{secs}s left", "剩 {mins}m{secs}s"),
+    ("DownloadFailedHint", "The Logs page has the full reason.", "完整原因在日志页。"),
+    ("DownloadOpenLogs", "Open logs", "打开日志"),
+    ("DownloadDismiss", "Dismiss", "关闭"),
+    ("DownloadOptionsTitle", "Install options", "安装选项"),
+    ("DownloadOptionsLoaderVersion", "Loader version", "加载器版本"),
+    ("DownloadOptionsLoaderVersionsLoading", "Fetching loader versions…", "正在获取加载器版本…"),
+    ("DownloadOptionsLoaderVersionsFailed", "Could not fetch loader versions: {reason}", "取不到加载器版本：{reason}"),
+    ("DownloadOptionsLoaderVersionsEmpty", "No loader builds published for {version}", "官方没有为 {version} 发布加载器版本"),
+    ("DownloadOptionsInstanceName", "Instance name", "实例名"),
+    ("DownloadOptionsInstanceNameHint", "Empty = use the version id", "留空就用版本号"),
+    ("DownloadOptionsIncompatible", "{loader} has no builds for {version}", "{loader} 没有适配 {version} 的构建"),
+    ("DownloadOptionsNeedsAtLeast", "{loader} needs Minecraft {min} or newer", "{loader} 需要 Minecraft {min} 或更新"),
+    ("DownloadCancelled", "Install cancelled — finished files are kept, the instance was not created", "安装已取消 —— 已下好的文件保留，实例未登记"),
+    ("LogsSubtitleIdle", "Nothing is running right now", "当前没有运行中的实例"),
+    ("LogsStatus", "{instance} · {when} · {outcome}", "{instance}｜{when}｜{outcome}"),
+    ("LogsOpenFolder", "Open folder", "打开目录"),
+    ("LogsClear", "Clear", "清空"),
+    ("LogsOutputTitle", "OUTPUT", "输出"),
+    ("LogsDiagnosisTitle", "DIAGNOSIS", "诊断"),
+    ("LogsConfidenceHigh", "HIGH CONFIDENCE", "高置信度"),
+    ("LogsConfidenceMedium", "MEDIUM CONFIDENCE", "中置信度"),
+    ("LogsConfidenceLow", "LOW CONFIDENCE", "低置信度"),
+    ("LogsSubtitleLive", "Running now — logs stream as they arrive", "正在运行 — 日志实时滚动"),
+    ("LogsConfidence", "Confidence {percent}%", "置信度 {percent}%"),
+    ("LogsSuggestedFix", "Suggested fix", "建议动作"),
+    ("LogsSummaryLabel", "One-line summary", "一行摘要"),
+    ("LogsCopySummary", "Copy summary", "复制摘要"),
+    ("LogsEmptyTitle", "No output yet", "还没有输出"),
+    ("LogsEmptyBody", "Logs stream here while the launcher or the game is running. Pick an instance and start it to see the first lines.", "启动器或游戏运行时，日志会实时出现在这里。选择一个实例并启动，就能看到第一批日志。"),
+    ("LogsEmptyAction", "Choose an instance", "选择实例"),
+    ("AgentTitle", "Assistant", "助手"),
+    ("AgentSubtitle", "Simulated assistant · no real model is connected", "模拟助手 · 还没接真实模型"),
+    ("AgentCollapse", "Collapse", "收起"),
+    ("AgentDetach", "Pop out", "拆出"),
+    ("AgentDock", "Dock back", "收回"),
+    ("AgentOpen", "Open assistant", "打开助手"),
+    ("AgentStripLabel", "AI", "助手"),
+    ("AgentSend", "Send", "发送"),
+    ("AgentStop", "Stop", "中断"),
+    ("AgentPlaceholder", "Message the simulated assistant…", "给模拟助手发消息…"),
+    ("AgentEmptyTitle", "Nothing in this session yet", "这个会话还没有内容"),
+    ("AgentEmptyBody", "Ask about instances, downloads or logs. This assistant is simulated: no real model is connected.", "可以问实例、下载或日志。当前是模拟助手，没有接真实模型。"),
+    ("AgentNotePending", "Placeholder shell: your message is kept here, nothing was sent to a model.", "占位外壳：消息留在这里，没有发给任何模型。"),
+    ("AgentNoteStopped", "Stopped by you.", "你中断了这次回复。"),
+    ("AgentUnread", "{count} unread", "{count} 条未读"),
+    ("AgentResize", "Drag to resize the assistant rail", "拖动调整助手栏宽度"),
+    ("AgentWidthLabel", "Width {width}", "宽度 {width}"),
+    ("AgentRoleYou", "You", "你"),
+    ("AgentRoleAssistant", "Assistant", "助手"),
+    ("AgentRoleNotice", "Notice", "提示"),
+    ("AgentErrorTitle", "Assistant error", "助手出错"),
+    ("AgentErrorUnavailable", "Couldn't reach the assistant backend. Check the endpoint, then try again.", "连不上助手后端：检查端点后重试。"),
+    ("AgentErrorNotImplemented", "This assistant request isn't wired up yet.", "这个助手请求还没接线。"),
+    ("AgentConfirmRequest", "The assistant wants to change something: {summary}", "助手想改一项设置：{summary}"),
+    ("AgentConfirmAllow", "Allow", "允许"),
+    ("AgentConfirmDeny", "Deny", "拒绝"),
+    ("AgentSimulated", "Simulated", "模拟"),
+    ("AgentSubtitleReal", "Conversation", "会话"),
+    ("AgentPlaceholderReal", "Message the assistant…", "给助手发消息…"),
+    ("AgentEmptyBodyReal", "Ask about instances, downloads or logs.", "可以问实例、下载或日志。"),
+    // ── M106 `I18NFOLLOW`：General 分组真控件（语言选择器 + 其余三行）。**只追加在链尾**，
+    //    上一行到 `LogsEmptyAction` 的既有顺序一字未动（金表要证明的正是这件事）。
+    ("SettingsLanguageFollowSystem", "Follow system", "跟随系统"),
+    ("SettingsLanguageZhCn", "Chinese (Simplified)", "简体中文"),
+    ("SettingsLanguageEn", "English", "英文"),
+    ("SettingsLanguageEffective", "Interface right now: {language}", "界面当前使用：{language}"),
+    ("SettingsTheme", "Theme", "主题"),
+    ("SettingsThemeFollowSystem", "Follow system", "跟随系统"),
+    ("SettingsStartupPage", "Startup page", "启动页"),
+    ("SettingsStartupInstances", "Instances", "实例"),
+    ("SettingsCloseButton", "Close button", "关闭按钮"),
+    ("SettingsCloseToTray", "Exit to tray", "退出到托盘"),
+    ("SettingsSubtitle", "Launcher behaviour, Java runtimes and download sources", "启动器行为、Java 运行时与下载源"),
+    ("SettingsResetSection", "Reset section", "重置本组"),
+    ("SettingsSave", "Save", "保存"),
+    ("NavAi", "Assistant", "助手"),
+    ("SettingsGroupGeneral", "General", "通用"),
+    ("SettingsGroupAppearance", "Appearance", "外观"),
+    ("SettingsGroupJava", "Java", "Java 运行时"),
+    ("SettingsGroupDownloads", "Downloads", "下载"),
+    ("SettingsOverridesEmptyTitle", "No per-instance overrides", "没有逐实例覆盖"),
+    ("SettingsOverridesEmptyBody", "Overrides let one instance keep its own Java runtime, memory or JVM flags while the rest of the launcher keeps the defaults above.", "逐实例覆盖让某个实例保留自己的 Java 运行时、内存或 JVM 参数，其余实例沿用上面的默认值。"),
+    ("SettingsOverridesAdd", "Add override", "新增覆盖"),
+    ("AgentFallbackBody", "The assistant page is not built yet. Chat lives in the docked panel once the AI mission lands; this screen is the M68 skeleton fallback.", "助手页还没做。AI 接线落地后对话会出现在右侧停靠面板；这一屏是 M68 的骨架回退。"),
+    // --- M107 版本管理页（追加在链尾：`Key::ALL` 顺序 = 金表顺序） ---
+    ("VersionRailTitle", "Version type", "版本类型"),
+    ("VersionMajorTitle", "Major version", "主版本"),
+    ("VersionMajorAll", "All versions", "全部版本"),
+    ("VersionSearchPlaceholder", "Search version numbers", "搜版本号"),
+    ("VersionSearchClear", "Clear search", "清空搜索"),
+    ("VersionSearchHits", "{count} matches", "{count} 个匹配"),
+    ("VersionSearchEmptyTitle", "No matching versions", "没有匹配的版本"),
+    ("VersionSearchEmptyBody", "Try a shorter piece of the number — 1.21, 24w, a1.", "试试更短的片段 — 1.21、24w、a1。"),
+    ("VersionSearchElsewhere", "{count} versions match, but they are in another type.", "有 {count} 个版本匹配，但它们在别的类型里。"),
+    ("VersionSearchElsewhereAction", "Show all types", "看全部类型"),
+    // --- M107 r2（追加在末尾：`Key::ALL` 顺序 = 金表顺序） ---
+    ("VersionSearchHitsOne", "1 match", "1 个匹配"),
+    ("VersionSearchElsewhereTitle", "Found in another type", "在别的类型里找到了"),
+    ("VersionSearchElsewhereOne", "1 version matches, but it is in another type.", "有 1 个版本匹配，但它在别的类型里。"),
+    // --- M109 内容库页（同样追加在链尾：`Key::ALL` 顺序 = 金表顺序） ---
+    ("ContentTitle", "Content", "内容库"),
+    ("ContentSubtitle", "Modpacks, mods, resource packs and shaders", "整合包、Mod、资源包与光影"),
+    ("ContentSectionVersions", "Version management", "版本管理"),
+    ("ContentSectionContent", "Content library", "内容库"),
+    ("ContentKindModpack", "Modpacks", "整合包"),
+    ("ContentKindMod", "Mods", "Mod"),
+    ("ContentKindResourcepack", "Resource packs", "资源包"),
+    ("ContentKindShader", "Shaders", "光影"),
+    ("ContentSourceModrinth", "Modrinth", "Modrinth 源"),
+    ("ContentSourceCurseforge", "CurseForge", "CurseForge 源"),
+    ("ContentSortRelevance", "Relevance", "相关度"),
+    ("ContentSortDownloads", "Downloads", "下载量"),
+    ("ContentSortNewest", "Newest", "最新发布"),
+    ("ContentSortUpdated", "Recently updated", "最近更新"),
+    ("ContentSearchPlaceholder", "Search content…", "搜索内容…"),
+    ("ContentSearch", "Search", "搜索"),
+    ("ContentFilterVersion", "Game version", "游戏版本"),
+    ("ContentFilterLoader", "Loader", "加载器"),
+    ("ContentFilterAny", "Any", "不限"),
+    ("ContentCount", "{count} results", "{count} 个结果"),
+    ("ContentLoading", "Loading content…", "正在加载内容…"),
+    ("ContentLoadingHint", "Results come from the network; nothing is cached offline yet.", "结果来自网络，暂时没有离线缓存。"),
+    ("ContentEmptyTitle", "Nothing matched", "没有匹配的内容"),
+    ("ContentEmptyBody", "Try another keyword, or clear a filter.", "换个关键词，或清掉一个筛选条件。"),
+    ("ContentFailedTitle", "Could not load content", "内容加载失败"),
+    ("ContentFailedBody", "Check the network, then retry.", "检查网络后重试。"),
+    ("ContentRetry", "Retry", "重试"),
+    ("ContentLoadMore", "Load more", "加载更多"),
+    ("ContentNoMore", "No more results", "没有更多了"),
+    ("ContentDetailEmpty", "Pick an item to see what it supports.", "选一个项目看它支持什么。"),
+    ("ContentDetailDownloads", "{count} downloads", "下载量 {count}"),
+    ("ContentDetailUpdated", "Updated {date}", "更新于 {date}"),
+    ("ContentDetailLoaders", "Loaders: {list}", "加载器：{list}"),
+    ("ContentDetailVersions", "Game versions: {list}", "游戏版本：{list}"),
+    ("ContentInstall", "Install into instance", "装入实例"),
+    ("ContentTargetInstance", "Target instance", "目标实例"),
+    ("ContentNoInstances", "No instance to install into", "没有可装入的实例"),
+    ("ContentIncompatibleVersion", "Needs {version}; this instance runs {actual}", "需要 {version}，该实例运行的是 {actual}"),
+    ("ContentIncompatibleLoader", "Not built for {loader}", "不支持 {loader}"),
+    ("ContentModpackNotReady", "Installing modpacks from the library into an instance is not available yet", "从内容库一键安装整合包到实例还没做（本地的包可以直接导入）"),
+    ("ContentSourceUnavailable", "CurseForge needs an API key: add one in Settings", "CurseForge 需要在设置里配置密钥才能搜索"),
+    ("ContentSourceNotWired", "Installing from CurseForge is not available yet", "CurseForge 来源的安装尚未开放"),
+    ("PackTitle", "Modpack import & export", "整合包导入 / 导出"),
+    ("PackImportTitle", "Import a modpack", "导入整合包"),
+    ("PackDropHint", "Drop a .mrpack, .zip or a MultiMC/Prism instance folder here", "把 .mrpack / .zip 或 MultiMC·Prism 实例目录拖到这里"),
+    ("PackDropActive", "Release to probe the pack", "松手开始探测"),
+    ("PackNoDialog", "This build has no system file picker: drag the file in, or paste its path below.", "本版没有系统文件选择框：请把文件拖进来，或在下面粘贴路径。"),
+    ("PackPathLabel", "Pack path", "整合包路径"),
+    ("PackPathPlaceholder", "D:\\packs\\Better MC.mrpack", "D:\\整合包\\更好的MC.mrpack"),
+    ("PackImportAction", "Import", "导入"),
+    ("PackCancel", "Cancel import", "取消导入"),
+    ("PackDismiss", "Dismiss", "关闭"),
+    ("PackTargetLabel", "Install into", "装到实例"),
+    ("PackTargetNew", "New instance", "新建实例"),
+    ("PackInstanceName", "Instance name", "实例名"),
+    ("PackStageLine", "Step {index}/{total} · {stage}", "步骤 {index}/{total} · {stage}"),
+    ("PackStageProbe", "Reading the manifest", "读取清单"),
+    ("PackStageExtract", "Unpacking overrides", "解包覆盖内容"),
+    ("PackStageFetch", "Fetching missing files", "补下载文件"),
+    ("PackStageCommit", "Writing files", "落地写盘"),
+    ("PackStageRegister", "Registering the instance", "登记实例"),
+    ("PackProbeTitle", "This pack is almost a known format", "这个包差一点就是已知格式"),
+    ("PackProbeLooksLike", "Looks like {format}, but missing: {missing}", "看起来像 {format}，但缺：{missing}"),
+    ("PackProbeUnknown", "No known format claims this pack", "没有任何已知格式认领这个包"),
+    ("PackProbeSaw", "Found in the pack: {saw}", "包里看到：{saw}"),
+    ("PackProbeNothing", "nothing recognisable", "没有可识别的东西"),
+    ("PackStatusSuccess", "Imported", "已导入"),
+    ("PackStatusPartial", "Imported with gaps", "导入完成，但有缺口"),
+    ("PackStatusFailed", "Import failed — rolled back", "导入失败 —— 已整包回滚"),
+    ("PackReportWritten", "Files written: {count} · {bytes}", "{count} 个文件已写盘 · {bytes}"),
+    ("PackReportMissing", "Could not fetch (tolerated): {count}", "有 {count} 个文件没搞到（可容忍）"),
+    ("PackReportConflicts", "Conflicts: {count}", "冲突：{count} 个"),
+    ("PackReportRejected", "The client does not support these: {count}", "这些组件客户端不支持：{count} 个"),
+    ("PackReportRejectedNote", "not supported by the client", "客户端不支持"),
+    ("PackCancelled", "Import keeps running in the background — this result is discarded. Files already written stay.", "导入会在后台继续跑完 —— 本次结果作废；已经写下的文件会留下。"),
+    ("PackOverwriteAction", "Re-import, the pack wins", "以包为准重新导入"),
+    ("PackOverwriteNote", "Keeping both (renamed) is not supported yet: the import pipeline has one global conflict policy and no per-file decision channel.", "「两者都留（改名）」暂不支持：导入管线只有一套全局冲突策略，没有逐文件决策通道。"),
+    ("PackMissingOffline", "offline import", "离线导入"),
+    ("PackMissingNoSource", "no download source available yet", "暂时拿不到下载地址"),
+    ("PackMissingFetchFailed", "download failed: {detail}", "下载失败：{detail}"),
+    ("PackFatalTitle", "Rolled back — nothing was left behind", "已回滚 —— 目标目录零残留"),
+    ("PackFatalHint", "What to try next", "下一步可以试"),
+    ("PackConflictUserModified", "you changed it", "你改过"),
+    ("PackConflictUserDeleted", "you deleted it", "你删过"),
+    ("PackConflictPreExisting", "was already there", "本来就在"),
+    ("PackChoiceKeepUser", "kept yours", "保留我的"),
+    ("PackChoiceOverwrite", "pack version used", "用包里的"),
+    ("PackConflictHashes", "pack {pack} · base {base} · disk {disk}", "包内 {pack} · 基线 {base} · 磁盘 {disk}"),
+    ("PackConflictDetail", "Hashes", "三方哈希"),
+    ("PackFormatModrinth", "Modrinth .mrpack", "Modrinth 的 .mrpack"),
+    ("PackFormatCurseforge", "CurseForge manifest", "CurseForge 清单"),
+    ("PackFormatMultimc", "MultiMC / Prism instance", "MultiMC·Prism 实例"),
+    ("PackExportTitle", "Export this instance", "导出这个实例"),
+    ("PackExportOpen", "Export…", "导出…"),
+    ("PackExportFormat", "Format", "格式"),
+    ("PackExportName", "Pack name", "包名"),
+    ("PackExportVersion", "Version", "版本"),
+    ("PackExportOutput", "Save to", "保存到"),
+    ("PackExportOutputPlaceholder", "empty = suggested path", "留空 = 自动给一个路径"),
+    ("PackExportPrecheck", "Dry run", "预检"),
+    ("PackExportConfirm", "Write the pack", "确认写盘"),
+    ("PackExportAbort", "Back", "返回"),
+    ("PackExportMultimcNote", "MultiMC/Prism can only be imported, not exported (by design).", "MultiMC·Prism 只能导入、不能导出（有意省略）。"),
+    ("PackExportDone", "Wrote {path} · {bytes}", "已写出 {path} · {bytes}"),
+    ("PackExportFailed", "Export failed: {reason}", "导出失败：{reason}"),
+    ("PackExportPending", "Scanning the instance…", "正在扫描实例…"),
+    ("PackPreviewHead", "Will inline {inline} files · cannot export: {skipped}", "将内联 {inline} 个文件 · 无法导出 {skipped} 项"),
+    ("PackPreviewRemote", "{count} files can be referenced remotely", "{count} 个文件可走远程引用"),
+    ("PackPreviewInlineBytes", "{bytes} copied into overrides/", "{bytes} 会原样拷进 overrides/"),
+    ("PackPreviewInlineTitle", "Copied into overrides/ (first {shown}):", "原样拷进 overrides/（只列前 {shown} 个）："),
+    ("PackPreviewSkippedTitle", "Not in the pack: {count}", "没进包：{count} 项"),
+    ("PackPreviewNotes", "Known losses", "已知损失"),
+    ("PackPreviewTarget", "Will be written to {path}", "将写到 {path}"),
+    ("PackPreviewMore", "…and {count} more files (not shown here)", "…还有 {count} 个文件（这里不展开）"),
+    ("PackPreviewComplete", "Nothing is left out", "没有遗漏任何文件"),
+    ("PackPreviewIncomplete", "Some files will not be in the pack", "有文件不会进包"),
+    ("PackReasonModrinthSha1", "Modrinth match (SHA-1)", "Modrinth 命中（SHA-1）"),
+    ("PackReasonCurseFingerprint", "CurseForge match (fingerprint)", "CurseForge 命中（文件指纹）"),
+    ("PackReasonNoRemoteMatch", "unknown to both catalogs, inlined", "两个目录都不认识，已内联"),
+    ("PackReasonCurseOnly", "only CurseForge knows it, this format cannot use it, inlined", "只有 CF 认识，目标格式用不上，已内联"),
+    ("PackReasonModrinthOnly", "only Modrinth knows it, the CF manifest cannot use it, inlined", "只有 Modrinth 认识，CF 清单用不上，已内联"),
+    ("PackReasonMissingSha512", "the catalogue entry has no sha512 hash, inlined", "命中缺 sha512，已内联"),
+    ("PackReasonMissingCurseIds", "the catalogue entry has no CurseForge ids, inlined", "命中缺 projectID/fileID，已内联"),
+    ("PackReasonDisabled", "disabled file, this format cannot express it (.disabled kept)", "禁用文件，目标格式表达不了（保留 .disabled）"),
+    ("PackReasonSymlink", "symbolic link, skipped", "符号链接，已跳过"),
+    ("PackReasonUnsafePath", "path fails the pack path rules, skipped", "路径过不了包内规整，已跳过"),
+    ("PackReasonUnreadable", "cannot read it, skipped", "读不出来，已跳过"),
+    // ── M114 账户页：追加在 main 的全部域之后（金表只追加不重排）
+    ("AccountTitle", "Accounts", "账户"),
+    ("AccountSubtitle", "Microsoft, third-party skin servers and local profiles", "微软正版、第三方皮肤站与本地档案"),
+    ("AccountListTitle", "All accounts", "全部账户"),
+    ("AccountAddedOn", "Added {date}", "添加于 {date}"),
+    ("AccountActiveChip", "Active", "当前"),
+    ("AccountSwitch", "Use for launch", "切换为启动账户"),
+    ("AccountRelogin", "Sign in again", "重新登录"),
+    ("AccountRemove", "Remove", "删除"),
+    ("AccountKindMicrosoft", "Microsoft", "微软正版"),
+    ("AccountKindAuthlib", "Third-party skin server", "第三方皮肤站"),
+    ("AccountKindOffline", "Local profile", "本地档案"),
+    ("AccountServer", "Server {server}", "服务器 {server}"),
+    ("AccountEmptyTitle", "No accounts yet", "还没有账户"),
+    ("AccountEmptyBody", "Add a Microsoft account, a third-party skin server account, or a local profile.", "添加微软正版账户、第三方皮肤站账户，或建一个本地档案。"),
+    ("AccountEmptyAction", "Add an account", "添加账户"),
+    ("AccountTrackMicrosoftTitle", "Microsoft account", "微软正版"),
+    ("AccountTrackMicrosoftBody", "Sign in with a device code or in your browser. Online servers require this kind of account.", "用设备码或浏览器登录。联机服务器必须用这种账户。"),
+    ("AccountTrackAuthlibTitle", "Third-party skin server", "第三方皮肤站"),
+    ("AccountTrackAuthlibBody", "An authlib-injector compatible server (LittleSkin and friends) brings its own skins and capes.", "兼容 authlib-injector 的皮肤站（如 LittleSkin）自带皮肤与披风。"),
+    ("AccountTrackOfflineTitle", "Local profile", "本地档案"),
+    ("AccountTrackOfflineBody", "Local / isolated-network testing only — it cannot join servers that require a genuine Minecraft account.", "仅本地/隔离网络测试用，无法连接启用正版验证的服务器。"),
+    ("AccountTrackOpen", "Sign in", "登录"),
+    ("AccountTrackCreate", "Create profile", "创建档案"),
+    ("AccountDialogClose", "Close", "关闭"),
+    ("AccountOfflineNameLabel", "Profile name", "档案名"),
+    ("AccountOfflineNameHint", "3–16 letters, digits or underscore", "3–16 位字母、数字或下划线"),
+    ("AccountOfflineSubmit", "Create profile", "创建档案"),
+    ("AccountOfflineWarning", "Local / isolated-network testing only — it cannot join servers that require a genuine Minecraft account.", "仅本地/隔离网络测试用，无法连接启用正版验证的服务器。"),
+    ("AccountDeviceCodeLabel", "Enter this code", "输入这个用户码"),
+    ("AccountDeviceCodeCopy", "Copy code", "复制用户码"),
+    ("AccountDeviceLinkCopy", "Copy link", "复制链接"),
+    ("AccountDeviceCountdown", "{time} left", "剩 {time}"),
+    ("AccountDeviceExpired", "This code has expired. Start again for a fresh one.", "这个用户码已过期，重新开始换一个新的。"),
+    ("AccountDeviceRetry", "Try again", "重试"),
+    ("AccountDeviceCancel", "Cancel", "取消"),
+    ("AccountDeviceBrowser", "Sign in with browser", "用浏览器登录"),
+    ("AccountDeviceUseCode", "Use a device code instead", "改用设备码"),
+    ("AccountServerLabel", "Server address", "服务器地址"),
+    ("AccountServerHint", "API root, e.g. https://littleskin.cn/api/yggdrasil/", "API 根，例：https://littleskin.cn/api/yggdrasil/"),
+    ("AccountServerProbe", "Check server", "校验服务器"),
+    ("AccountLoginNameLabel", "Email or username", "邮箱或用户名"),
+    ("AccountPasswordLabel", "Password", "密码"),
+    ("AccountPasswordHint", "Used once for this sign-in. It is never stored.", "只在这次登录里用一次，不会保存。"),
+    ("AccountAuthlibSubmit", "Sign in", "登录"),
+    ("AccountAuthlibIdleHint", "The server is checked automatically when you sign in; Check server only does it up front.", "登录时会自动校验服务器；「校验服务器」只是提前跑一遍。"),
+    ("AccountSkinTitle", "Skin", "皮肤"),
+    ("AccountSkinNone", "No skin available", "没有可用皮肤"),
+    ("AccountSkinHint", "Skins come from the account's own server; nothing is generated locally.", "皮肤来自账户自己的服务器，本地不生成任何假皮肤。"),
+    ("AccountRailSignedOut", "Not signed in", "未登录"),
+    ("AccountDeviceHint", "Open the link in your browser and enter the code above.", "在浏览器里打开链接，输入上面的用户码。"),
+    ("AccountDeviceBrowserHint", "Finish the sign-in in the browser window we just opened; the link below also works.", "在我们刚打开的浏览器窗口里完成登录；下面的链接也能手动打开。"),
+    ("AccountServerChecking", "Checking the server…", "正在校验服务器…"),
+    ("AccountServerOk", "Server {server} is ready", "服务器 {server} 可用"),
+    ("AccountLoginFailed", "Sign-in failed", "登录失败"),
+    ("AccountCurrentTitle", "Current account", "当前账户"),
+    ("AccountFailureCode", "Code: {code}", "代码：{code}"),
+    ("AccountFailureDenied", "The server refused this sign-in (access denied).", "服务器拒绝了这次登录（拒绝访问）。"),
+    ("AccountFailureWhitelist", "Microsoft has not approved this launcher's app registration yet. An administrator has to accept the app, then try again.", "微软还没批准本启动器的应用注册：需要管理员同意该应用后再试。"),
+    ("AccountFailureUnreachable", "Could not reach the server. Check the network connection or the address, then try again.", "连不上服务器：检查网络或地址后重试。"),
+    ("AccountFailureNotAuthlib", "This address does not look like an authlib-injector server (the API root usually ends with /api/yggdrasil/).", "这个地址不像 authlib-injector 服务器（API 根通常以 /api/yggdrasil/ 结尾）。"),
+    ("AccountFailureBadCredentials", "The server rejected the username or password.", "服务器不认这个用户名或密码。"),
+    ("AccountFailureNoProfile", "The account has no Minecraft profile on this server yet. Create the character on the server first.", "这个账号在该服务器上还没有角色：先在皮肤站里创建角色。"),
+    ("AccountFailureStore", "Could not save the account to disk.", "账户没能写到磁盘上。"),
+    ("AccountFailureOther", "The sign-in failed. The full reason is in the launcher log.", "登录失败，完整原因在启动器日志里。"),
+    ("AccountDeviceRequesting", "Contacting Microsoft…", "正在联系微软…"),
+    ("AccountLoginSucceeded", "Signed in as {name}", "已登录 {name}"),
+    ("AccountNoticeAdded", "Added {name}", "已添加 {name}"),
+    ("AccountNoticeRemoved", "Removed {name}", "已删除 {name}"),
+    ("AccountNoticeSwitched", "{name} will be used for the next launch", "{name} 将作为下次启动的账户"),
+    ("AccountNoticeOfflineNameInvalid", "Profile names must be 3–16 letters, digits or underscores.", "档案名必须是 3–16 位字母、数字或下划线。"),
+    ("AccountNoticeAccountExists", "An account with that name already exists.", "同名账户已经存在。"),
+    ("AccountNoticeStoreFailed", "Could not save the account store. Check the disk and try again.", "账户库写不进去：检查磁盘后重试。"),
+    ("AccountNoticeNotFound", "That account no longer exists.", "这个账户已经不在了。"),
+    ("AccountNoticeOther", "The account action failed. The full reason is in the launcher log.", "账户操作失败，完整原因在启动器日志里。"),
+    ("AccountNoticeDismiss", "Dismiss", "关闭"),
+    ("AccountNoticeTitleFailed", "Account action failed", "账户操作失败"),
+    ("AccountNoticeTitleDone", "Account updated", "账户已更新"),
+    ("AccountHintAuthlibReauth", "Enter the password again for {server}.", "请输入 {server} 的密码。"),
+    ("AccountHintOfflineNoRelogin", "Local profiles have no server account to sign in again — create a new profile instead.", "本地档案没有可重新登录的服务器账户，请新建一个档案。"),
+];
diff --git a/crates/i18n/src/catalog/instances.rs b/crates/i18n/src/catalog/instances.rs
new file mode 100644
index 0000000..9bbb84f
--- /dev/null
+++ b/crates/i18n/src/catalog/instances.rs
@@ -0,0 +1,85 @@
+//! 实例页文案：页头、列表列头、详情动作、元信息卡的标签与值、运行状态与启动阶段。
+//!
+//! 域文件的形状见 [`crate::catalog`] 的「域装配」一节。
+//!
+//! ## 这一族在装配链的**第 2 位**（M120 钉住）
+//!
+//! `instances_entries!` 紧跟 `nav_entries!`，所以本族的 key 落在 `Key::ALL` 的前段、
+//! `LoaderVanilla` 之前。M120 的新 key 因此**追加在本域末尾**（= `InstancesEmptyBody` 之后），
+//! 既没插到别的族中间，也没为了「排在文件末尾」去重排别人的族：
+//! 金表（[`crate::catalog::golden`]）是 `Key::ALL` 的逐 index 镜像，位置跟着族走。
+//!
+//! ## M120 之前这七条全是**死 key**
+//!
+//! M117 加 `InstancesNew` / `InstancesImport` / `InstancesBack` / `InstancesPlay` /
+//! `InstancesLastPlayed` / `InstancesEmptyTitle` / `InstancesEmptyBody` 时，实例页并没有接它们
+//! ——页面上还是英文基线字面量（`"New instance"` / `"ALL INSTANCES"` / `"Present on disk"`…）。
+//! M120 一次接完，同时：
+//!
+//! - `InstancesEmptyBody` 的译文换成详情列真正画的那句（原来那句是「看详情」的泛说）；
+//! - **`InstancesLastPlayed` 删掉**：它的形状是「上一次游玩 {when}」这种整句，而页面上是
+//!   元信息卡（标签 `LAST PLAYED` + 值 `2026-10-29 19:22 UTC`，或值 `Never`）。留着它只会
+//!   多出一条没人用的 key，所以拆成 [`Key::InstancesMetaLastPlayed`]（标签）与
+//!   [`Key::InstancesNeverPlayed`]（值）。
+//!
+//! ## 两条口径（复审会盯）
+//!
+//! 1. **品牌与技术标识不翻译**：`Java`（元信息标签的值域）与 `pid`（进程号）原样保留两套语言；
+//! 2. **数字与分隔符不随语言变形**：[`Key::InstancesRunning`] 的中英都写成
+//!    `… · pid {pid}`，只有前半句换了；`{pid}` 之外一个字都不许动（`pages/instances/tests/i18n.rs`
+//!    用「中英同位置取占位符 + 数字原样」的断言钉这条）。
+
+macro_rules! instances_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* {
+            $($acc)*
+            // ── 实例页（M117 的七条：其中 `InstancesLastPlayed` 见模块文档，M120 删除）
+            InstancesNew => ("New instance", "新建实例"),
+            InstancesImport => ("Import", "导入"),
+            InstancesBack => ("Back to instances", "返回实例列表"),
+            InstancesPlay => ("Play", "启动"),
+            InstancesEmptyTitle => ("No instance selected", "未选择实例"),
+            InstancesEmptyBody => ("Pick an instance on the left to see its version, loader and launch options.", "在左侧选择一个实例，查看它的版本、加载器与启动选项。"),
+            // ── 页头与列表列头（M120）
+            InstancesTitle => ("Instances", "实例"),
+            InstancesSubtitle => ("Local versions and their mod loaders", "本地版本与它们的模组加载器"),
+            InstancesAllTitle => ("ALL INSTANCES", "全部实例"),
+            // ── 详情动作（M120）
+            InstancesStop => ("Stop", "停止"),
+            InstancesDuplicate => ("Duplicate", "复制"),
+            InstancesOpenFolder => ("Open folder", "打开文件夹"),
+            InstancesDelete => ("Delete", "删除"),
+            InstancesNarrowNote => (
+                "Below 840 px the list and the detail share one column, so opening an instance replaces this screen (full-page switch). Widen the window to see both panes again.",
+                "窗口窄于 840 像素时，列表与详情共用一列：打开一个实例会整页替换这一屏（整页切换）。把窗口拉宽就能重新同时看见两栏。"
+            ),
+            // ── 元信息卡的标签（M120；`Java` 是品牌名，两套语言都写 Java）
+            InstancesMetaVersion => ("VERSION", "版本"),
+            InstancesMetaLoader => ("LOADER", "加载器"),
+            InstancesMetaMemory => ("MEMORY", "内存"),
+            InstancesMetaJava => ("JAVA", "Java"),
+            InstancesMetaMods => ("MODS", "模组"),
+            InstancesMetaIsolation => ("ISOLATION", "隔离方式"),
+            InstancesMetaVersionId => ("VERSION ID", "版本标识"),
+            InstancesMetaFiles => ("FILES", "文件"),
+            InstancesMetaLastPlayed => ("LAST PLAYED", "上次游玩"),
+            // ── 元信息卡的值（M120）
+            InstancesPresentOnDisk => ("Present on disk", "已在磁盘上"),
+            InstancesMissing => ("Missing", "缺失"),
+            InstancesNeverPlayed => ("Never", "从未游玩"),
+            // 隔离档位的两个稳定 id（`core::game::IsolationMode::as_str`）→ 人话。
+            // 白名单只覆盖真实存在的这两档；`inherit` / `custom` / 未知值原样上屏（不猜）。
+            InstancesIsolationIsolated => ("Isolated", "独立目录"),
+            InstancesIsolationShared => ("Shared", "共用目录"),
+            // ── 运行状态与启动阶段（M120；数字与分隔符不随语言变形）
+            InstancesRunning => ("Running · pid {pid}", "运行中 · pid {pid}"),
+            InstancesFailed => ("Launch failed · {reason}", "启动失败 · {reason}"),
+            InstancesStageDownload => ("Downloading", "下载中"),
+            InstancesStageVerify => ("Verifying", "校验中"),
+            InstancesStageLaunch => ("Starting", "启动中"),
+            InstancesStageWindow => ("Waiting for window", "等待游戏窗口"),
+        } }
+    };
+}
+
+pub(crate) use instances_entries;
diff --git a/crates/i18n/src/catalog/launch.rs b/crates/i18n/src/catalog/launch.rs
new file mode 100644
index 0000000..1559355
--- /dev/null
+++ b/crates/i18n/src/catalog/launch.rs
@@ -0,0 +1,59 @@
+//! 启动结局文案：一句话 = 一个 key（原来 UI 把 `"Launch failed"` 与 core 的「静默失败」拼成一句话）。
+//!
+//! 域文件的形状见 [`crate::catalog`] 的「域装配」一节。
+
+macro_rules! launch_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* {
+            $($acc)*
+            // ── 启动结局（原来 UI 把 "Launch failed" 与 core 的「静默失败」拼成一句话，现在一句话 = 一个 key）
+            LaunchOutcomeNormal => ("Finished normally", "正常结束"),
+            LaunchOutcomeCrash => ("The game crashed", "游戏崩溃"),
+            LaunchOutcomeSilent => (
+                "Suspected silent failure: exit code 0, but the game never really started",
+                "疑似静默失败：退出码 0，但游戏没真正跑起来"
+            ),
+            LaunchFailedWithCode => ("Launch failed (exit {code}): {reason}", "启动失败（退出码 {code}）：{reason}"),
+            // M117：微软轨的 client id 没配是**配置缺失**，不是「本期未支持」。这句话是那条
+            // 启动失败文案的**双语口径**（真源在 `core::auth::microsoft` 的
+            // `MISSING_CLIENT_ID_MESSAGE`，中文逐字一致；英文这条给 En 界面用）。
+            // 判据：中英都点名 `ULL_MSA_CLIENT_ID` 并给出构建期注入这条路，且**不许**出现
+            // 「unsupported / 未支持」——用户实跑就是被那句误导读成「功能没做」。
+            LaunchMsaNotConfigured => (
+                "Microsoft sign-in is not configured: it needs an Azure public client id (the login flow itself is implemented). Build with ULL_MSA_CLIENT_ID=, 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..14716b3
--- /dev/null
+++ b/crates/i18n/src/catalog/logs.rs
@@ -0,0 +1,40 @@
+//! 日志页文案（M95）。
+//!
+//! 日志页的**界面文案**（标题 / 按钮 / 分组名 / 空态）。诊断结论的正文不在这里：
+//! 那是规则表 `rules.d/*.yaml` 的输出（数据），见 `pages/logs/diagnostic.rs` 的模块文档。
+//!
+//! `LogsStatus` 是**模板**：中英差别落在分隔符上（中文用全角竖线——`·` 是外来符号，
+//! 中文正文里偏挤；这也让「中文目录必须与英文不同」这条守卫成立，不是为过测试硬造差异）。
+//!
+//! 域文件的形状见 [`crate::catalog`] 的「域装配」一节。
+
+macro_rules! logs_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* {
+            $($acc)*
+            // --- logs page (M95) ---
+            LogsSubtitleIdle => ("Nothing is running right now", "当前没有运行中的实例"),
+            LogsStatus => ("{instance} · {when} · {outcome}", "{instance}｜{when}｜{outcome}"),
+            LogsOpenFolder => ("Open folder", "打开目录"),
+            LogsClear => ("Clear", "清空"),
+            LogsOutputTitle => ("OUTPUT", "输出"),
+            LogsDiagnosisTitle => ("DIAGNOSIS", "诊断"),
+            LogsConfidenceHigh => ("HIGH CONFIDENCE", "高置信度"),
+            LogsConfidenceMedium => ("MEDIUM CONFIDENCE", "中置信度"),
+            LogsConfidenceLow => ("LOW CONFIDENCE", "低置信度"),
+            LogsSubtitleLive => ("Running now — logs stream as they arrive", "正在运行 — 日志实时滚动"),
+            LogsConfidence => ("Confidence {percent}%", "置信度 {percent}%"),
+            LogsSuggestedFix => ("Suggested fix", "建议动作"),
+            LogsSummaryLabel => ("One-line summary", "一行摘要"),
+            LogsCopySummary => ("Copy summary", "复制摘要"),
+            LogsEmptyTitle => ("No output yet", "还没有输出"),
+            LogsEmptyBody => (
+                "Logs stream here while the launcher or the game is running. Pick an instance and start it to see the first lines.",
+                "启动器或游戏运行时，日志会实时出现在这里。选择一个实例并启动，就能看到第一批日志。"
+            ),
+            LogsEmptyAction => ("Choose an instance", "选择实例"),
+        } }
+    };
+}
+
+pub(crate) use logs_entries;
diff --git a/crates/i18n/src/catalog/nav.rs b/crates/i18n/src/catalog/nav.rs
new file mode 100644
index 0000000..4b48360
--- /dev/null
+++ b/crates/i18n/src/catalog/nav.rs
@@ -0,0 +1,42 @@
+//! 导航文案：四个一级页。AI 独立页没有导航高亮项（`Route::Agent.nav()` 是 `None`），所以没有 key。
+//!
+//! 域文件的形状见 [`crate::catalog`] 的「域装配」一节：本宏把条目**追加**到 `$acc` 之后，
+//! 再把「还没装配的域」原样交给 `$next`。条目顺序 = `Key` 的声明顺序（金表 `catalog::golden` 守门）。
+//!
+//! **显示名与标识符不同名**（M108）：`NavDownload` 这条说的是「版本管理」，而它指向的仍是
+//! `Route::Download` / `NavSection::Download`。用户令（2026-11-04）只改**显示层**：全仓重命名
+//! 标识符会与在途的多条线全面撞车，收益只在观感，所以标识符改名后置。
+//!
+//! ## 为什么「版本管理」有两条 key（M108）
+//!
+//! D33 定死了导航两态：**88 收起轨 ⇄ 240 展开抽屉**。88px 里塞得下中文「版本管理」（4 字 ≈48px），
+//! 但塞不下英文 `Version management`（18 字符 ≈101px > 88）——那会变成截断或两行，两个都是视觉缺陷
+//! （两行还要把项高从 52 抬到 68，等于为一个词改全局导航节奏）。
+//!
+//! 所以按**容器宽度**分两条：
+//!
+//! | key | 用在哪 | en | zh-CN |
+//! |---|---|---|---|
+//! | [`NavDownload`] | 88 收起轨（`shell/nav.rs` / `pages/nav.rs`） | `Versions` | 版本管理 |
+//! | [`NavDownloadExpanded`] | 240 展开抽屉（D33 的展开态） | `Version management` | 版本管理 |
+//!
+//! 中文两条**故意同值**：48px 放得下就没有理由为「对称」砍短（那是视觉缺陷，不是风格）。
+//! 英文短名选 `Versions` 而不是 `Versions list` / `Downloads`：单一词最省宽度，且不与「下载」
+//! （真在传文件的动作、设置页的下载分组）混淆。切换点只有 [`crate::catalog`] 的调用方一处，
+//! 见 `pages/nav.rs` 的 `label_key`。
+
+macro_rules! nav_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* {
+            $($acc)*
+            // ── 导航轨（`pages::Route` 的四项）
+            NavInstances => ("Instances", "实例"),
+            NavDownload => ("Versions", "版本管理"),
+            NavDownloadExpanded => ("Version management", "版本管理"),
+            NavLogs => ("Logs", "日志"),
+            NavSettings => ("Settings", "设置"),
+        } }
+    };
+}
+
+pub(crate) use nav_entries;
diff --git a/crates/i18n/src/catalog/settings/ai.rs b/crates/i18n/src/catalog/settings/ai.rs
new file mode 100644
index 0000000..17f2514
--- /dev/null
+++ b/crates/i18n/src/catalog/settings/ai.rs
@@ -0,0 +1,13 @@
+//! 设置页「AI / About」分组文案：**预留**（页面上还没有这个分组，见 `pages/settings/mod.rs` 的
+//! 分组注册表）。
+//!
+//! 加 key 时把条目写进 `$($acc)*` 后面即可（形状见 [`crate::catalog`] 的「域装配」一节）。
+//! 现在没有条目，所以本宏是**空转移器**：只把累积表原样交给下一个域。
+
+macro_rules! settings_ai_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* { $($acc)* } }
+    };
+}
+
+pub(crate) use settings_ai_entries;
diff --git a/crates/i18n/src/catalog/settings/appearance.rs b/crates/i18n/src/catalog/settings/appearance.rs
new file mode 100644
index 0000000..907e9a2
--- /dev/null
+++ b/crates/i18n/src/catalog/settings/appearance.rs
@@ -0,0 +1,35 @@
+//! 设置页「Appearance」分组文案（M116 首次落地：窗口圆角一档）。
+//!
+//! 加 key 时把条目写进 `$($acc)*` 后面即可（形状见 [`crate::catalog`] 的「域装配」一节）。
+//!
+//! ## 为什么只有圆角这一组的 key
+//!
+//! 本分组的既有控件（整窗/面板透明度、背景图、配色来源……）是 M93 落的，文案是英文基线字面量
+//! （`pages/appearance/section.rs`）。M116 新增的圆角档位**从一开始就走词表**（tower 口径：
+//! 设置项文案不许硬编码），所以这里先只有它这一组；老控件接词表归 i18n 接线 mission。
+//!
+//! ## 文案口径（不许暗示所有平台一致）
+//!
+//! 用户定案：Win11 / Server 2025 开系统圆角，Win10 可以不开，其他系统按窗口合成器的默认规则。
+//! 所以说明句必须写清「谁负责画圆」而不是「我们支持圆角」——后半句在 Win10 上是假的。
+
+macro_rules! settings_appearance_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* {
+            $($acc)*
+            SettingsAppearanceCorner => ("Window corners", "窗口圆角"),
+            SettingsAppearanceCornerSystem => ("Follow system", "跟随系统"),
+            SettingsAppearanceCornerSquare => ("Square", "直角"),
+            SettingsAppearanceCornerHint => (
+                "On Windows 11 and Server 2025 we ask the system for rounded corners; Windows 10 keeps square corners. On macOS and Linux the desktop's own rules apply. We never draw corners ourselves.",
+                "Windows 11 与 Windows Server 2025 上我们请求系统处理外框圆角；Windows 10 保持直角；macOS 与 Linux 交给桌面合成器自己的规则；我们不自己画圆角。"
+            ),
+            SettingsAppearanceCornerSuspended => (
+                "Not in effect right now: window transparency is below 100%. Setting it back to 100% restores the rounded corners.",
+                "当前因整窗透明度不生效：把整窗透明度调回 100% 圆角即恢复。"
+            ),
+        } }
+    };
+}
+
+pub(crate) use settings_appearance_entries;
diff --git a/crates/i18n/src/catalog/settings/download.rs b/crates/i18n/src/catalog/settings/download.rs
new file mode 100644
index 0000000..49163e3
--- /dev/null
+++ b/crates/i18n/src/catalog/settings/download.rs
@@ -0,0 +1,12 @@
+//! 设置页「Downloads」分组文案：**预留**（页面侧的真控件还没接）。
+//!
+//! 加 key 时把条目写进 `$($acc)*` 后面即可（形状见 [`crate::catalog`] 的「域装配」一节）。
+//! 现在没有条目，所以本宏是**空转移器**：只把累积表原样交给下一个域。
+
+macro_rules! settings_download_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* { $($acc)* } }
+    };
+}
+
+pub(crate) use settings_download_entries;
diff --git a/crates/i18n/src/catalog/settings/general.rs b/crates/i18n/src/catalog/settings/general.rs
new file mode 100644
index 0000000..ba523cf
--- /dev/null
+++ b/crates/i18n/src/catalog/settings/general.rs
@@ -0,0 +1,19 @@
+//! 设置页「General」分组文案：语言（Theme / Startup page / Close button 的 key 还没建）。
+//!
+//! 域文件的形状见 [`crate::catalog`] 的「域装配」一节。
+
+macro_rules! settings_general_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* {
+            $($acc)*
+            // ── 设置
+            SettingsLanguage => ("Language", "界面语言"),
+            SettingsLanguageHint => (
+                "Switches the interface language. Chinese text needs a Chinese font.",
+                "切换界面语言。显示中文需要中文字体。"
+            ),
+        } }
+    };
+}
+
+pub(crate) use settings_general_entries;
diff --git a/crates/i18n/src/catalog/settings/java.rs b/crates/i18n/src/catalog/settings/java.rs
new file mode 100644
index 0000000..db75b75
--- /dev/null
+++ b/crates/i18n/src/catalog/settings/java.rs
@@ -0,0 +1,12 @@
+//! 设置页「Java」分组文案：**预留**（页面侧的真控件还没接）。
+//!
+//! 加 key 时把条目写进 `$($acc)*` 后面即可（形状见 [`crate::catalog`] 的「域装配」一节）。
+//! 现在没有条目，所以本宏是**空转移器**：只把累积表原样交给下一个域。
+
+macro_rules! settings_java_entries {
+    ($next:ident, $($rest:ident,)* { $($acc:tt)* }) => {
+        $next! { $($rest,)* { $($acc)* } }
+    };
+}
+
+pub(crate) use settings_java_entries;
diff --git a/crates/i18n/src/catalog/settings/mod.rs b/crates/i18n/src/catalog/settings/mod.rs
new file mode 100644
index 0000000..b2746d9
--- /dev/null
+++ b/crates/i18n/src/catalog/settings/mod.rs
@@ -0,0 +1,28 @@
+//! 设置页文案：**一个分组一个文件**，与页面侧的 `pages/settings/**` 同构。
+//!
+//! 为什么拆到这个粒度：设置页正文接下来由四条并行 mission 分别接（java / download /
+//! language+appearance / ai+about），它们都会往设置页加 key。一个分组一个文件之后，每条线只改
+//! 自己那个文件，`catalog.rs` 的装配链一行都不用动（链里已经把这五个域接好了）。
+//!
+//! | 文件 | 分组（`pages/settings` 的 `GROUPS`） | 现状 |
+//! |---|---|---|
+//! | [`general`] | General（Language / Theme / Startup page / Close button） | 2 条 key（语言） |
+//! | [`appearance`] | Appearance（Density / Corner style / Motion / Text scale） | 预留，暂无 key |
+//! | [`java`] | Java（Runtime / Default memory / JVM arguments） | 预留，暂无 key |
+//! | [`download`] | Downloads（Preferred source / Concurrency / Verify checksums） | 预留，暂无 key |
+//! | [`ai`] | AI / About（页面上还没有这个分组） | 预留，暂无 key |
+//!
+//! 「预留」的文件里是**空转移器**（只把累积表原样交给下一个域）：加 key 时把条目写进它
+//! `$($acc)*` 后面即可——签名不用改，`catalog.rs` 不用碰，跨线零冲突。
+
+mod ai;
+mod appearance;
+mod download;
+mod general;
+mod java;
+
+pub(crate) use ai::settings_ai_entries;
+pub(crate) use appearance::settings_appearance_entries;
+pub(crate) use download::settings_download_entries;
+pub(crate) use general::settings_general_entries;
+pub(crate) use java::settings_java_entries;
diff --git a/crates/i18n/src/catalog/tests.rs b/crates/i18n/src/catalog/tests.rs
new file mode 100644
index 0000000..1518e4c
--- /dev/null
+++ b/crates/i18n/src/catalog/tests.rs
@@ -0,0 +1,203 @@
+//! `Catalog` 的守门测试（从 `catalog.rs` 原样搬出来：那边已经贴着 400 行硬上限，
+//! 而页面每加一批 key 都要在这个模块里占一行）。
+//!
+//! **零改动搬运**：用例、注释、断言一字未动；`use super::*` 指向的仍是 `crate::catalog`。
+//! M94（下载页）与 M95（日志页）几乎同时撞到这堵墙、各自搬了一次：两条 branch 的**用例部分
+//! 逐字相同**（解冲突时按 M94 那份合并，测试数量 7 条不变）。
+
+use super::*;
+
+/// 手写一套**故意缺条**的目录（不经过 `catalog!`，模拟后续 mission 的注入表）。
+const PARTIAL_ZH: &[(Key, &str)] = &[
+    (Key::NavInstances, "实例"),
+    (Key::NavLogs, "日志"),
+    (Key::NavSettings, "设置"),
+    (Key::NavDownload, "下载"),
+    (Key::InstancesNew, "新建实例"),
+    (Key::InstancesImport, "导入"),
+    (Key::InstancesBack, "返回实例列表"),
+    (Key::InstancesPlay, "启动"),
+    (Key::InstancesEmptyTitle, "未选择实例"),
+    (
+        Key::InstancesEmptyBody,
+        "在左侧选择一个实例，查看它的版本、加载器与启动选项。",
+    ),
+    (Key::LoaderVanilla, "原版"),
+    (Key::LaunchOutcomeNormal, "正常结束"),
+    (Key::LaunchOutcomeCrash, "游戏崩溃"),
+    // 缺：LaunchOutcomeSilent / LaunchFailedWithCode / FontCjk* / Settings* / CoreTextUntranslated
+];
+
+#[test]
+fn built_in_catalogs_have_every_key() {
+    // 抓得住：`catalog!` 的成对生成被绕开（有人改回「两套各写一遍」并漏了一条 / 抄重了一条）。
+    //         判据是**集合相等**：`Key` 枚举拦住了「表里有、枚举没有」，这里拦反方向。
+    // 抓不住：译文对不对（这只能是人工 / 后续的语言审查）。
+    for lang in Lang::ALL {
+        let catalog = Catalog::of(*lang);
+        assert_eq!(catalog.missing(), Vec::new(), "{}", catalog.lang().tag());
+        assert_eq!(catalog.diagnose(), None);
+
+        let mut keys = catalog
+            .entries()
+            .iter()
+            .map(|(key, _)| *key)
+            .collect::>();
+        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::GOLDEN.len(),
+        "key 条数与拆分前不一致（某条被搬丢，或多出来一条）"
+    );
+
+    for (index, expected) in super::golden::GOLDEN.iter().enumerate() {
+        let got = actual[index];
+        assert_eq!(
+            got.0, expected.0,
+            "第 {index} 条的 key 变了：拆分的域顺序被打乱，或某条被搬到了别处"
+        );
+        assert_eq!(got.1, expected.1, "{} 的英文译文变了", expected.0);
+        assert_eq!(got.2, expected.2, "{} 的中文译文变了", expected.0);
+    }
+}
diff --git a/crates/i18n/src/choice.rs b/crates/i18n/src/choice.rs
new file mode 100644
index 0000000..f503a01
--- /dev/null
+++ b/crates/i18n/src/choice.rs
@@ -0,0 +1,258 @@
+//! 设置页的**界面语言档位**（M106 `I18NFOLLOW`）：跟随系统 / 手选某一门。
+//!
+//! ## 为什么单独一个文件
+//!
+//! `lang.rs` 讲的是「系统说哪种语言」（locale → [`Lang`] 的探测，M92），本文件讲的是「用户要哪种
+//! 语言」——两者的判据不一样：探测只能尽量理解别人给的字符串，档位是我们自己写进配置的，写错就该
+//! 暴露。放在一起会让 `lang.rs` 顶破 400 行（任务书那条硬线要求按功能拆文件）。
+//!
+//! ## D28 的判定顺序（整条挂在 [`LangChoice::resolve`] 上）
+//!
+//! **手选 > 系统语言 > 环境变量 > 英文**。最后一级「英文」不是偷懒：纯英文环境不扫、不下载中文
+//! 字体（零额外体积 / 零网络），这条由 [`crate::font::decide`] 兜住，真值表见下面
+//! `english_never_needs_a_chinese_font_and_chinese_always_resolves_one`。
+//!
+//! ## 「跟随系统」怎么表达
+//!
+//! **不写 `ui.language` 这个键**（[`LangChoice::setting_value`] 返回 `None`）。不写哨兵值是因为
+//! 两件事：① schema 的允许值只有 `zh_cn` / `en_us`（`core::setting::keys::LANGUAGES`），写别的
+//! 会被枚举校验拒掉；② 读的那一头（`SettingBridge::load_ui_language`）只认显式值，所以「键不存在」
+//! 与「用户选了跟随系统」本来就是同一件事。
+
+use crate::catalog::Key;
+use crate::lang::{resolve, Detection, Lang, LocaleSource, ORIGIN_SETTING};
+
+/// 设置页「界面语言」的三档选择。
+///
+/// 为什么不是 `Option`：`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..fb04985
--- /dev/null
+++ b/crates/i18n/src/font.rs
@@ -0,0 +1,331 @@
+//! 中文字体策略（D28 后半）：**只做判据，不联网**。
+//!
+//! ## 三句话
+//!
+//! 1. **英文环境不要字体**：`Lang::En` → [`Strategy::NotNeeded`]，与系统里装了什么无关。
+//!    D28 原话是「纯英文环境不用管（零额外体积/零网络）」，这条是本模块最重要的断言。
+//! 2. **中文环境先扫系统**：候选族名单见 [`CJK_FAMILIES`]，命中即用（[`Strategy::System`]）。
+//! 3. **扫不到才说要下载**：[`Strategy::NeedsDownload`] 是一个**信号**，不是动作——
+//!    真正下载由注入的 [`Fetcher`] 实现，本 mission 不写网络实现（D28 的 CDN 下载是后续 mission）。
+//!
+//! ## 扫描为什么在 UI 壳层而不是这里
+//!
+//! 真扫系统字体要 FontConfig / DirectWrite / iced 的 `font_system()`——任何一条都会把 iced 或平台
+//! SDK 拉进本 crate，破掉零依赖纪律。所以本模块只收一个 `installed: &dyn Fn(&str) -> bool`
+//! （iced 版实现在 `crates/app-iced/src/fonts/cjk.rs`），单测用假闭包，脱机可跑。
+//!
+//! ## 诚实边界（抓得住什么 / 抓不住什么）
+//!
+//! - **抓得住**：语言 → 是否需要中文 → 系统里有没有候选族 → 要不要下载 这条链路的判定；
+//! - **抓不住**：①**族名存在 ≠ 字形覆盖**——`fontdb` 里挂着一个叫 `SimSun` 的族也可能是个残缺子集，
+//!   真判据要用 `ttf-parser` 查 cmap（M60 Q3 的 spike 做过，本 mission 不引依赖）；
+//!   ②下载下来的字节怎么注册进 iced 的字体系统——iced 0.14 有 `iced::font::load(bytes) -> Task`
+//!   可在运行时注册（已核对上游源码），但「什么时候调、失败怎么回退、和启动日志怎么对账」
+//!   属于下载 mission，本 crate 不碰。
+
+use crate::lang::Lang;
+
+/// 已知的系统 CJK 族（Windows / macOS / Linux，按「观感优先」排序，命中第一个就用）。
+///
+/// 只收**简体**优先的常见族；`Microsoft JhengHei` 这类繁体族留在名单里垫底——
+/// 仓内只有一套中文目录（简体），繁体用户看简体的观感仍好过看英文。
+pub const CJK_FAMILIES: &[&str] = &[
+    // Windows 10/11
+    "Microsoft YaHei UI",
+    "Microsoft YaHei",
+    "DengXian",
+    "SimHei",
+    "SimSun",
+    "Microsoft JhengHei",
+    // macOS
+    "PingFang SC",
+    "Hiragino Sans GB",
+    "Heiti SC",
+    "Songti SC",
+    // Linux
+    "Noto Sans CJK SC",
+    "Noto Sans SC",
+    "Source Han Sans SC",
+    "Source Han Sans CN",
+    "Sarasa Gothic SC",
+    "WenQuanYi Micro Hei",
+    "Droid Sans Fallback",
+];
+
+/// 中文字体必须覆盖的字重（M-决定日志 ③：Android 16 的可变思源黑体缺 100–400，
+/// 而 M3 Expressive 的 emphasized 档要 700 ⇒ 「400 / 500 / 700 至少三档」）。
+pub const REQUIRED_WEIGHTS: &[u16] = &[400, 500, 700];
+
+/// 可下载字体的来源。本 mission **不 pin URL/哈希**——见 [`Source::PendingPin`]。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Source {
+    /// 待下载 mission 钉死：确切 URL + `sha256` + 子集范围（简体常用字 + 标点），
+    /// 并按 [`REQUIRED_WEIGHTS`] 覆盖 400/500/700。**故意不写一个随手想出来的 URL**：
+    /// 猜错的 CDN 路径会被后面所有人当事实用。
+    PendingPin,
+}
+
+/// 一套可下载的 CJK 字体描述（不含 URL / 哈希，原因见 [`Source`]）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct CjkFont {
+    /// 族名（下载并注册后，`Font` 用它取字）。
+    pub family: &'static str,
+    /// 许可证（必须是 OFL / Apache 这类可再分发的；D28 明令不得内置 Segoe）。
+    pub license: &'static str,
+    /// 这套字体可用的字重。
+    pub weights: &'static [u16],
+    /// 下载源（尚未钉死）。
+    pub source: Source,
+}
+
+/// 缺字体时的默认方案：Noto Sans SC（OFL-1.1）。
+pub const NOTO_SANS_SC: CjkFont = CjkFont {
+    family: "Noto Sans SC",
+    license: "OFL-1.1",
+    weights: &[300, 400, 500, 700, 900],
+    source: Source::PendingPin,
+};
+
+/// 字体策略结论。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Strategy {
+    /// 不需要中文字体（英文环境）。
+    NotNeeded,
+    /// 系统里已有可用族，直接用。
+    System {
+        /// 命中的族名。
+        family: &'static str,
+    },
+    /// 需要下载（本模块只发信号，不联网）。
+    NeedsDownload(&'static CjkFont),
+    /// 探测不出（拿不到系统字体库）——**不等于**「需下载」：不许凭猜测去下载。
+    Unprobeable,
+}
+
+impl Strategy {
+    /// 一行日志片段（`cjk=system:"Microsoft YaHei"` / `cjk=needs-download(Noto Sans SC)` …）。
+    #[must_use]
+    pub fn describe(&self) -> String {
+        match self {
+            Strategy::NotNeeded => "cjk=not-needed".to_owned(),
+            Strategy::System { family } => format!("cjk=system:\"{family}\""),
+            Strategy::NeedsDownload(font) => format!("cjk=needs-download({})", font.family),
+            Strategy::Unprobeable => "cjk=unprobeable".to_owned(),
+        }
+    }
+}
+
+/// 判据（纯函数）：语言 + 「某族装没装」→ 策略。
+///
+/// `installed` 由调用方提供（iced 版查系统字体库，单测给假闭包）。
+#[must_use]
+pub fn decide(lang: Lang, installed: &dyn Fn(&str) -> bool) -> Strategy {
+    if lang != Lang::ZhCn {
+        // D28：纯英文环境不加载任何中文字体，也不下载。
+        return Strategy::NotNeeded;
+    }
+
+    CJK_FAMILIES
+        .iter()
+        .copied()
+        .find(|family| installed(family))
+        .map_or(Strategy::NeedsDownload(&NOTO_SANS_SC), |family| {
+            Strategy::System { family }
+        })
+}
+
+/// 字体下载器接口（**注入式**；本 mission 没有网络实现）。
+pub trait Fetcher {
+    /// 取一套字体（返回原始字节，装进字体系统是调用方的事）。
+    ///
+    /// # Errors
+    /// 网络失败 / 校验失败等人话错误。
+    fn fetch(&self, font: &'static CjkFont) -> Result, FetchError>;
+}
+
+/// 下载失败的分类（给 UI 决定要不要重试；分类少是故意的）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum FetchError {
+    /// 网络层失败（超时 / 连不上 / 非 2xx）。
+    Network(String),
+    /// 校验失败（哈希 / 长度不符，或不是字体文件）。
+    Integrity(String),
+}
+
+/// [`ensure`] 的结局。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Fetched {
+    /// 本来就不需要（英文环境）。
+    NothingToDo,
+    /// 系统已有，直接用。
+    AlreadySystem {
+        /// 命中的族名。
+        family: &'static str,
+    },
+    /// 下载成功，拿到字节（交给调用方注册）。
+    Downloaded(Vec),
+    /// 探测不出，什么都没做。
+    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)]
+mod tests {
+    use super::*;
+    use std::cell::Cell;
+
+    fn only(installed: &'static [&'static str]) -> impl Fn(&str) -> bool {
+        move |family| installed.contains(&family)
+    }
+
+    /// 假下载器：记录调用次数，避免「悄悄联网」这种事在单测里被放过。
+    struct FakeFetcher {
+        calls: Cell,
+        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!(font.source, Source::PendingPin, "URL/哈希留给下载 mission");
+        assert_eq!(strategy.describe(), "cjk=needs-download(Noto Sans SC)");
+    }
+
+    #[test]
+    fn download_fonts_cover_the_required_weights() {
+        // 抓得住：将来换了字体却没覆盖 400/500/700（M3 Expressive 的 emphasized 档要 700）。
+        // 抓不住：字重是可变轴还是静态子集（那要看下载 mission 选的文件，本 crate 只有元数据）。
+        for weight in REQUIRED_WEIGHTS {
+            assert!(
+                NOTO_SANS_SC.weights.contains(weight),
+                "缺 {weight} 档：{:?}",
+                NOTO_SANS_SC.weights
+            );
+        }
+    }
+
+    #[test]
+    fn ensure_only_touches_the_fetcher_when_download_is_needed() {
+        // 抓得住：英文环境/系统已有字体时**仍然调了下载器**（= 偷跑网络请求）；
+        // 也抓得住下载失败被吞掉（错误必须原样透出）。
+        // 抓不住：真实现的网络行为（本 crate 没有网络实现，这正是不联网的证据）。
+        let idle = FakeFetcher::new(Ok(vec![1, 2, 3]));
+        assert_eq!(ensure(Strategy::NotNeeded, &idle), Ok(Fetched::NothingToDo));
+        assert_eq!(
+            ensure(Strategy::System { family: "SimSun" }, &idle),
+            Ok(Fetched::AlreadySystem { family: "SimSun" })
+        );
+        assert_eq!(ensure(Strategy::Unprobeable, &idle), Ok(Fetched::Unknown));
+        assert_eq!(idle.calls.get(), 0, "这三种情况都不许联网");
+
+        let ok = FakeFetcher::new(Ok(vec![9; 4]));
+        assert_eq!(
+            ensure(Strategy::NeedsDownload(&NOTO_SANS_SC), &ok),
+            Ok(Fetched::Downloaded(vec![9; 4]))
+        );
+        assert_eq!(ok.calls.get(), 1);
+        assert_eq!(ok.seen.get(), Some("Noto Sans SC"));
+
+        let broken = FakeFetcher::new(Err(FetchError::Network("超时".to_owned())));
+        assert_eq!(
+            ensure(Strategy::NeedsDownload(&NOTO_SANS_SC), &broken),
+            Err(FetchError::Network("超时".to_owned()))
+        );
+    }
+
+    #[test]
+    fn strategy_describe_is_one_line_for_every_case() {
+        // 抓得住：日志片段里混进换行（启动日志是按行解析的）。
+        // 抓不住：这些片段是否真的被打印（app-iced 的启动路径在那边测）。
+        let cases = [
+            Strategy::NotNeeded,
+            Strategy::System { family: "SimSun" },
+            Strategy::NeedsDownload(&NOTO_SANS_SC),
+            Strategy::Unprobeable,
+        ];
+        for case in cases {
+            let line = case.describe();
+            assert_eq!(line.lines().count(), 1, "{line}");
+            assert!(line.starts_with("cjk="), "{line}");
+        }
+        assert_eq!(Strategy::NotNeeded.describe(), "cjk=not-needed");
+        assert_eq!(Strategy::Unprobeable.describe(), "cjk=unprobeable");
+    }
+}
diff --git a/crates/i18n/src/lang.rs b/crates/i18n/src/lang.rs
new file mode 100644
index 0000000..a38fcc0
--- /dev/null
+++ b/crates/i18n/src/lang.rs
@@ -0,0 +1,387 @@
+//! 语言与系统 locale 探测（D28 前半）。
+//!
+//! ## 判据只有两条
+//!
+//! 1. **中文环境**（`zh*` 任意变体）→ [`Lang::ZhCn`]；
+//! 2. **其它一切**（`en*`、`ja*`、`fr*`、`C`、`POSIX`、变量缺失、解析不了）→ [`Lang::En`]。
+//!
+//! 「其它一切 → 英文」不是偷懒：D28 的原话是「纯英文环境不用管」，而把 ja/fr/de 猜成中文才是真错
+//! （会连带触发中文字体下载）。宁可给一个英文界面，也不给一个语种错误的中文界面。
+//!
+//! ## 为什么 locale 源要能注入
+//!
+//! [`detect`] 的形状是 `detect(&dyn LocaleSource)`，[`EnvLocale`] 只是其中一个实现。这样
+//! **单测不依赖跑测试那台机器的 locale**（真值表测试在 [`lang`] 自己的 `tests` 里跑固定输入），
+//! 后续 mission 加「Win32 `GetUserDefaultLocaleName`」或「读配置里的 `ui.language`」也只是再实现一遍
+//! 这个 trait。
+//!
+//! ## 优先级（[`resolve`]）
+//!
+//! **`ui.language` 显式值 > 平台源 > POSIX 环境变量 > 英文**。本 crate 只有 [`EnvLocale`]
+//! 一个具体实现——平台真值源（Windows 注册表那一路）在 UI 壳层，因为读注册表要开子进程，
+//! 而本 crate 的纪律是不碰外部世界。
+//!
+//! ## 诚实边界（抓得住什么 / 抓不住什么）
+//!
+//! - **抓得住**：环境变量字符串 → 语言的映射（含 `zh_CN.UTF-8` / `zh-Hans-CN` / 大小写 / 修饰符）；
+//!   变量优先级（`LC_ALL` > `LC_MESSAGES` > `LANG`）；[`resolve`] 的四级优先级；
+//! - **抓不住**：**Windows 上这三个变量通常都不存在**——那条路的真值源是
+//!   `crates/app-iced/src/platform/locale.rs`（`reg.exe` 读注册表，零 FFI），
+//!   它不在本 crate 里（本 crate 零依赖、不 spawn 进程）。所以「Windows 上拿不到语言」
+//!   这件事只在**没有接线平台源**时成立，接线后由 `resolve` 的二级兜住。
+//!   配置里的 `ui.language` 读取属于设置层接线（本 crate 只提供 [`Lang::from_setting`] 与
+//!   [`resolve`] 的形状）。
+
+use std::env;
+
+use crate::catalog::Catalog;
+
+/// 界面语言。目前只有中英两套（D28 的「至少 zh-CN / en-US」）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
+pub enum Lang {
+    /// 英文（默认；未知 locale 也落在这里）。
+    En,
+    /// 简体中文。
+    ZhCn,
+}
+
+impl Lang {
+    /// 全部语言（顺序即设置页下拉框的顺序）。
+    pub const ALL: &'static [Lang] = &[Lang::En, Lang::ZhCn];
+
+    /// BCP-47 标签（日志 / 字体请求里用；`zh-CN` 是本 crate 唯一的中文标识）。
+    #[must_use]
+    pub const fn tag(self) -> &'static str {
+        match self {
+            Lang::En => "en",
+            Lang::ZhCn => "zh-CN",
+        }
+    }
+
+    /// 配置值（`core::setting::keys::LANGUAGES` 的同一份词表）。
+    #[must_use]
+    pub const fn setting_value(self) -> &'static str {
+        match self {
+            Lang::En => "en_us",
+            Lang::ZhCn => "zh_cn",
+        }
+    }
+
+    /// 解析**配置值**（严格）：只认 [`Lang::setting_value`] 那两个字符串。
+    ///
+    /// 与宽松的 [`Lang::from_locale`] 分工明确：配置是我们自己写进去的，写错就该暴露（`None` 让设置层
+    /// 报错），而不是悄悄换成别的语言；系统 locale 是别人给的，只能尽量理解。
+    #[must_use]
+    pub fn from_setting(value: &str) -> Option {
+        Lang::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..1177c1f
--- /dev/null
+++ b/crates/palette-extract/Cargo.toml
@@ -0,0 +1,32 @@
+[package]
+name = "unlucky-palette-extract"
+description = "配色取色的解码适配层（D40 第 2 层）：图片路径/字节 → RGBA 像素 → unlucky-design 的种子"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+authors.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+publish.workspace = true
+
+# 分层纪律（D40）：`crates/design` 保持零第三方依赖，**图片解码只能在这里**。
+# 本 crate 的职责边界很窄：解码 + 限尺寸 + 把像素交给 design，不碰 UI、不碰设置、不碰壁纸探测。
+[dependencies]
+unlucky-design = { path = "../design", version = "0.2" }
+
+# 只开两个编解码器（MIT OR Apache-2.0，deny.toml 白名单内）：
+# - png：启动器背景图最常见的无损格式，也是截图通道用的格式；
+# - jpeg：Windows 壁纸与用户照片的绝对主力（不引它等于「取色对一半用户不可用」）；
+# - bmp：Windows 壁纸的真会出现（M73 的探测只读注册表/`.theme` 里的路径，**不筛扩展名**），
+#   而 `image` 的 `bmp` 是独立 feature 且**无额外传递依赖**（`bmp = []`），代价≈0。
+# 不开 `default-features`（默认会拖进 rayon + avif/ravif + webp + tiff + gif + exr + qoi
+# 等一整套编码器，体积与审计面都翻倍）；不开 webp/tiff/avif 是因为 M73 拿到的格式只有
+# png/jpg/bmp 三类，等真有人需要再单开一个 feature。
+image = { workspace = true, default-features = false, features = [
+    "png",
+    "jpeg",
+    "bmp",
+] }
+
+[lints]
+workspace = true
diff --git a/crates/palette-extract/src/lib.rs b/crates/palette-extract/src/lib.rs
new file mode 100644
index 0000000..ab38838
--- /dev/null
+++ b/crates/palette-extract/src/lib.rs
@@ -0,0 +1,217 @@
+//! # 配色取色的解码适配层（D40 三层里的第 2 层）
+//!
+//! 本 crate 只做一件事：**图片路径 / 字节 → RGBA 像素 → `unlucky_design` 的种子色**。
+//!
+//! ```no_run
+//! use unlucky_palette_extract::{input, load};
+//! use unlucky_design::palette::{resolve_source, CardKey};
+//! use unlucky_design::color::SchemeFlavor;
+//!
+//! // ① 读用户设的启动器背景图（失败不 panic，失败状态会原样进 Provenance）
+//! let background = load("D:/Pictures/bg.png");
+//! let (scheme, provenance) = resolve_source(
+//!     Some(input(&background)),
+//!     None,                       // ② 桌面壁纸：本次不启用
+//!     Some(CardKey::Sky),         // ③ 用户选中的色卡 = 回落目标
+//!     SchemeFlavor::Light,
+//! );
+//! println!("{:?} / {:?}", provenance.level, provenance.hint_key());
+//! ```
+//!
+//! ## 为什么解码要单独成 crate（D40）
+//!
+//! `crates/design` 的卖点是「零第三方依赖」（`cargo tree -p unlucky-design` 单行），而图片解码
+//! 必然拉依赖。把 `image` 塞进 design 会让那句卖点变成假话，所以：
+//!
+//! | 层 | crate | 依赖 | 职责 |
+//! |---|---|---|---|
+//! | 1 纯数学 | `unlucky-design` | 无 | 像素/种子 → 49 角色方案、色卡、回落决策、对比度收敛 |
+//! | 2 解码 | **本 crate** | `image`（png + jpeg） | 路径/字节 → RGBA 像素；限尺寸；错误分类 |
+//! | 3 调用侧 | 后续 appearance/settings mission | UI 框架 | 拿路径、把 `Provenance` 变文案 |
+//!
+//! ## 为什么选 `image`（而不是 `png` + `zune-jpeg` 各接一个）
+//!
+//! 1. **仓库里已经有它**：`crates/app-iced` 的截图通道用 `image`（png）。同一份依赖只编译一次，
+//!    版本由 workspace 的 `image = "0.25"` 统一钉住，`cargo deny` 的许可面不新增条目。
+//! 2. **格式嗅探现成**：`ImageReader::with_guessed_format()` 按魔数判格式，用户把 `.jpg`
+//!    改成 `.png` 也能读（壁纸文件被改名的概率不低）。
+//! 3. **有 `Limits`**：可以在解码前拒绝「头里写着 40000×40000」的 PNG（压缩炸弹），
+//!    单接 `png` crate 也要自己写这层判断。
+//!
+//! 许可：`image` 是 `MIT OR Apache-2.0`，在 `deny.toml` 白名单内（`[licenses].allow`）。
+//!
+//! ## 体积影响（`image` 只开 png + jpeg + bmp，关掉 default-features）
+//!
+//! 拉进的传递依赖就这几个：`png`（+ `fdeflate`/`miniz_oxide`/`crc32fast`/`flate2` 已在树里）、
+//! `zune-jpeg` + `zune-core`、`byteorder-lite`、`num-traits`、`moxcms`/`pxfm`（色彩转换）。
+//! `bmp` 是 `image` 的独立 feature 且**不带任何传递依赖**（`bmp = []`），加它只是因为
+//! M73 的 Windows 壁纸探测不筛扩展名、`.bmp` 壁纸真会出现。
+//! 关掉的默认特性里有 `rayon`（省一个线程池）、`avif`/`ravif`（最大的一个，编解码器整套）、
+//! `webp`/`tiff`/`gif`/`exr`/`qoi`/`hdr`/`dds`/`ff`。实测增量见 M87 报告（`cargo tree` 前后对比）。
+//!
+//! ## 两条硬纪律
+//!
+//! 1. **解码后才交出去**：送进 `unlucky_design` 的像素最多 [`MAX_EDGE`] 边长（默认 256）。
+//!    取色只需要色彩分布，不需要分辨率；一张 4K 壁纸缩到 256×144 后量化结果与全分辨率
+//!    在肉眼层面一致，内存却从 33MB 掉到 147KB。`crates/design` 里还有第二道块平均降采样
+//!    （防御式：直接调 design 的调用方也能拿到有界开销）。
+//! 2. **失败不 panic、不 return 默认色**：解码失败只变成 [`ExtractError`]，
+//!    [`input`] 把它翻成 `ImageInput::Undecodable` 交给 `resolve_source`，
+//!    由后者回落色卡并在 `Provenance` 里留下原因。**不许**在这里「读不到就给个蓝色」。
+
+use std::io::Cursor;
+use std::path::Path;
+
+use unlucky_design::palette::{self, ImageInput, ImageSource, Seed};
+
+/// 交给 `unlucky_design` 前允许的最大边长（像素）。
+///
+/// 256 的依据：量化器自己只采 65536 个点（≈256²），再大的图在 `crates/design` 里也会被
+/// 块平均降采样；提前缩小只是省内存与解码时间。可预测、可测试（见 `tests.rs`）。
+pub const MAX_EDGE: u32 = 256;
+
+/// 解码**之前**允许的图片头尺寸上限。
+///
+/// 4K 壁纸是 3840×2160，8K 是 7680×4320；16384 留出 2 倍余量，同时挡住「头里写着
+/// 40000×40000」的解压炸弹（否则解码器会先按头分配几十 GB）。
+const MAX_SOURCE_EDGE: u32 = 16_384;
+
+/// 解码后的 RGBA8 图像（行主序，`width × height × 4` 字节）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Rgba8 {
+    width: u32,
+    height: u32,
+    pixels: Vec,
+}
+
+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(
+    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)?;
+    let rgba = decoded.to_rgba8();
+    let (width, height) = (rgba.width(), rgba.height());
+    let scaled = if width.max(height) > MAX_EDGE {
+        // 等比缩到长边 = MAX_EDGE。`thumbnail` 是整数快速采样，对取色（只关心色彩分布）
+        // 足够，且比 Lanczos 快一个量级。
+        let factor = f64::from(MAX_EDGE) / f64::from(width.max(height));
+        let target_width = ((f64::from(width) * factor).round() as u32).max(1);
+        let target_height = ((f64::from(height) * factor).round() as u32).max(1);
+        image::imageops::thumbnail(&rgba, target_width, target_height)
+    } else {
+        rgba
+    };
+    Ok(Rgba8 {
+        width: scaled.width(),
+        height: scaled.height(),
+        pixels: scaled.into_raw(),
+    })
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/palette-extract/src/tests.rs b/crates/palette-extract/src/tests.rs
new file mode 100644
index 0000000..dc17050
--- /dev/null
+++ b/crates/palette-extract/src/tests.rs
@@ -0,0 +1,189 @@
+//! 解码适配层的单测：真 PNG / 真 JPEG 字节进，种子或**具体错误**出。
+//!
+//! 这里刻意不 mock 解码器：本 crate 存在的意义就是「真解码」，mock 掉它等于不测。
+//! 测试用内存里的字节（`encode_*` 现造），不依赖任何外部素材文件。
+
+use std::io::Cursor;
+
+use super::*;
+use image::{DynamicImage, ImageFormat, Rgba, RgbaImage};
+
+fn solid_image(width: u32, height: u32, rgb: [u8; 3]) -> RgbaImage {
+    RgbaImage::from_pixel(width, height, Rgba([rgb[0], rgb[1], rgb[2], 0xFF]))
+}
+
+fn encode_png(image: &RgbaImage) -> Vec {
+    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"),
+    }
+}
diff --git a/crates/presenter/Cargo.toml b/crates/presenter/Cargo.toml
new file mode 100644
index 0000000..38160c4
--- /dev/null
+++ b/crates/presenter/Cargo.toml
@@ -0,0 +1,28 @@
+[package]
+name = "unlucky-presenter"
+description = "Unlucky-Launcher 的 UI 框架无关宿主层：DTO / 状态 reducer / host 业务装配，Slint 版与 iced 版共用"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+authors.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+publish.workspace = true
+
+# 零 UI 框架依赖是硬约束（M85 / D26）：本 crate 是 Slint 版（`crates/app`）与 iced 版
+# （`crates/app-iced`）共用的宿主层，任何时候都不得出现 Slint / iced / winit / gtk / egui 等
+# UI 或渲染框架，也不得出现「把窗口属性灌进去」这种绑定代码。
+# 证据命令写在 `crates/app/Cargo.toml` 的注释里（那个文件允许出现框架名，本 crate 的守门
+# 命令本身在自家 grep 范围内会把自己抓出来，所以那两条命令刻意不放在这里）。
+[dependencies]
+# 跨边界 DTO 必须可序列化（AGENTS §6）：事件与快照是 IPC 契约，序列化能力由 derive 钉住。
+serde.workspace = true
+# host 层要读 core 设置/事件里的 JSON 值。
+serde_json.workspace = true
+
+# 边界（01c §5 / D3）：presenter 只经 DTO 消费 core，**不 import core 的领域类型到 DTO 里**。
+# host 是 core 的快照/事件流与本 crate DTO 之间的唯一翻译层，所以它需要 core。
+unlucky-core = { path = "../core", version = "0.2" }
+
+[lints]
+workspace = true
diff --git a/crates/presenter/src/agent.rs b/crates/presenter/src/agent.rs
new file mode 100644
index 0000000..ef0c3cd
--- /dev/null
+++ b/crates/presenter/src/agent.rs
@@ -0,0 +1,311 @@
+//! AI 助手（D16 双形态）的 presenter 门面：视图模型 + 提交/确认 + 裁决审计。
+//!
+//! # 1. 这一层为什么单独存在
+//!
+//! UI 壳（右侧常驻栏 = AGENTRAIL）只做两件事：读 [`AgentRail`] 画、把点击翻成这五个方法。
+//! 会话怎么攒、未读怎么算、YOLO 怎么裁决、审计记什么，全在这里与
+//! [`crate::state::AppState::apply_agent`]，壳里不重复实现——否则两形态（栏 / 页）会各写一套
+//! 而漂移。
+//!
+//! ```text
+//! UI 壳 ──agent_submit/agent_confirm/agent_mark_read──► Presenter ──AgentTransport──► 后端
+//!    ▲                                                     │
+//!    └────────── agent_rail()（只读视图模型）◄──────────────┘  events → AppState::apply
+//! ```
+//!
+//! # 2. 与 UI 壳的契约（签名已定，改名要先报 tower）
+//!
+//! ```text
+//! Presenter::agent_rail(&self) -> &AgentRail
+//! Presenter::agent_submit(&mut self, text: String) -> Result<(), String>
+//! Presenter::agent_mark_read(&mut self)
+//! Presenter::agent_confirm(&mut self, accept: bool)
+//! ```
+//!
+//! # 3. 铁律落点（AGENTS §6）
+//!
+//! - **AI 永不接触账户凭据**：事件里没有凭据字段；文本一律过 [`rail::scrub_text`]（第二道防线）。
+//! - **写配置受 schema 白名单约束**：白名单在 agent 侧工具层，presenter 只负责「把确认问出来」。
+//! - **敏感键分级确认，YOLO 只跳确认且审计照记**：[`Presenter::agent_confirm`] 在 YOLO 下
+//!   一律放行，但**照样**记一条 [`AuditEntry`]（`yolo = true, confirmed = false`）——不静默跳过。
+//!
+//! # 4. 没做的事（P1 再接）
+//!
+//! - 真实后端：本模块只认 [`AgentTransport`] 端口，`rig` 那侧由 host 装配时实现；
+//! - 落盘审计：agent 侧 `brain::exec` → `audit` 才是权威记录，这里的 [`AuditEntry`] 只是
+//!   本进程内、给 UI 看的裁决镜像（`presenter.audit()`）；
+//! - 流式时序：端口是同步返回事件分片的（便于单测），真实实现是异步推流。
+
+use crate::dto::{AppEvent, Sensitivity};
+use crate::prefs::UiPrefs;
+use crate::router::Route;
+use crate::state::AppState;
+
+pub mod mock;
+pub mod rail;
+
+use rail::scrub_text;
+pub use rail::AgentRail;
+
+#[cfg(test)]
+mod tests;
+#[cfg(test)]
+#[path = "agent/tests_red_line.rs"]
+mod tests_red_line;
+
+/// 裁决记录上限（只留最近若干条；权威审计不在这里）。
+pub const MAX_AUDIT_ENTRIES: usize = 256;
+
+/// 一次确认的结局。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ConfirmVerdict {
+    /// 放行（用户点了允许，或 YOLO 自动放行）
+    Approved,
+    /// 拒绝（工具调用会带「用户拒绝」回到模型）
+    Denied,
+}
+
+impl ConfirmVerdict {
+    /// 是否放行。
+    #[must_use]
+    pub fn is_approved(self) -> bool {
+        matches!(self, Self::Approved)
+    }
+}
+
+/// 一条确认裁决的审计记录。
+///
+/// `yolo` 与 `confirmed` 必须分开记：`yolo = true, confirmed = false`（自动放行）与
+/// `yolo = false, confirmed = true`（用户亲手点的允许）在事故复盘里是完全不同的两件事。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AuditEntry {
+    /// 请求 id（与 `AgentEvent::ConfirmRequested` 同一个）
+    pub request_id: String,
+    /// 工具名
+    pub tool: String,
+    /// 敏感等级
+    pub sensitivity: Sensitivity,
+    /// 结局
+    pub verdict: ConfirmVerdict,
+    /// 是否运行在 YOLO 模式
+    pub yolo: bool,
+    /// 是否经过用户确认（YOLO 下恒为 false）
+    pub confirmed: bool,
+}
+
+/// agent 后端端口：presenter 不认 `rig` / 异步运行时的具体类型（依赖方向见 crate 文档）。
+///
+/// 方法同步返回事件分片是刻意的：真实后端在后台线程里跑，事件经
+/// [`crate::dto::Backend::drain_events`] 回流；端口这层只表达「一轮输入会产生哪些事件」，
+/// 这样单测可以不碰定时器与网络。
+pub trait AgentTransport {
+    /// 用户提交一句话。
+    ///
+    /// `history` 是当前 rail 的只读快照（真实后端要靠它拼上下文，mock 靠它算消息下标）。
+    /// 返回的事件分片由 [`Presenter`] 顺序 `apply`；`Err` 表示这一轮根本没起来（不产生事件）。
+    fn submit(&mut self, text: &str, history: &AgentRail) -> Result, 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..eda6885
--- /dev/null
+++ b/crates/presenter/src/dto/accounts.rs
@@ -0,0 +1,395 @@
+//! 账户页 DTO：三条轨道的统一抽象 + 微软登录（设备码 / 授权码浏览器）的可见状态。
+//!
+//! **凭据红线**：本模块（以及整个 `crate::dto`）只有 [`AccountView`] 这种公开字段视图。
+//! `core::auth` 的 `Credentials` / `MicrosoftSession` / token 永远不进 app 层——
+//! host 侧在拿到账户快照的那一刻就丢掉凭据，只留「能显示什么」。
+//!
+//! | 文件 | 职责 |
+//! |---|---|
+//! | 本文件 | 账户/登录**可见状态**（全部是可上屏字段） |
+//! | [`redact`] | 形状脱敏：JWT / 不透明串 / `token=...` 一律抹掉（第二道脱敏器） |
+//! | `tests` | 契约 round-trip + 凭据红线的入口断言 |
+
+mod failure;
+mod kind;
+mod name;
+mod redact;
+#[cfg(test)]
+#[path = "accounts/tests.rs"]
+mod tests;
+
+pub use failure::{AccountNotice, AccountNoticeCode, LoginFailure};
+pub use kind::AccountKind;
+pub use name::valid_offline_name;
+pub use redact::{looks_like_jwt, redact, REDACTED};
+
+use serde::{Deserialize, Serialize};
+
+/// 账户列表行（**只含可公开字段**）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct AccountView {
+    /// 稳定 id（`account:...`）
+    pub id: String,
+    /// 展示名
+    pub name: String,
+    /// 轨道
+    pub kind: AccountKind,
+    /// 档案 UUID（公开）
+    pub profile_id: String,
+    /// 登录名（微软轨才有；可空）
+    pub login_name: String,
+    /// 创建时间展示串（`2026-10-31 20:12`）
+    ///
+    /// 口径：core 的 `AccountMeta` 只有 `created_at_ms`，**没有 last-used**，所以列表上贴的是
+    /// 「添加于 {created}」，不伪造「最近使用」（缺口登记在 M114 报告）。
+    pub created: String,
+    /// 是否是当前启动使用的账户
+    pub active: bool,
+    /// 第三方轨的认证服务器 API 根（其余轨为空串）
+    #[serde(default)]
+    pub server_url: String,
+    /// 皮肤原图（第三方轨才可能有；`None` = 没有/没取到，UI 退回首字母块）
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub skin: Option,
+}
+
+impl AccountView {
+    /// 首字母块上的字：展示名第一个非空字符（大写化），空名字回落 `?`。
+    ///
+    /// 放在 DTO 而不是页面里，是为了「没有皮肤时画什么」这件事只有一处判据，两个 UI 版一致。
+    #[must_use]
+    pub fn monogram(&self) -> String {
+        self.name
+            .chars()
+            .find(|c| !c.is_whitespace())
+            .map(|c| c.to_uppercase().to_string())
+            .unwrap_or_else(|| "?".to_string())
+    }
+
+    /// 首字母块的取色索引（0..6）：由 `profile_id` 稳定推导，同一个人每次都是同一个色块。
+    #[must_use]
+    pub fn monogram_tone(&self) -> u8 {
+        let mut hash: u32 = 2_166_136_261;
+        for byte in self.profile_id.as_bytes() {
+            hash ^= u32::from(*byte);
+            hash = hash.wrapping_mul(16_777_619);
+        }
+        u8::try_from(hash % 6).unwrap_or(0)
+    }
+}
+
+/// 一张皮肤原图。
+///
+/// **停在「原图」这一层是刻意的**：presenter 不引入图片解码依赖（`presenter-no-ui` +
+/// 依赖极简），裁剪/缩放/取首字母块都由 UI 层自己做。离线轨永远没有它——没有皮肤就不给假皮肤。
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct SkinImage {
+    /// PNG 字节（Minecraft 皮肤：64×64 或旧版 64×32）
+    pub png: Vec,
+    /// 来源 URL（**只进取证日志，不上屏**）
+    pub source: String,
+}
+
+impl SkinImage {
+    /// 是否有可用字节（0 字节等同没有皮肤）。
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.png.is_empty()
+    }
+}
+
+/// 微软登录阶段（UI 据此切换面板；两条流共用）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum DeviceLoginPhase {
+    /// 没有登录在进行
+    Idle,
+    /// 正在向微软申请设备码（短暂）
+    Requesting,
+    /// 已拿到用户码，等待用户在浏览器完成
+    Waiting,
+    /// 成功（账户已入库）
+    Succeeded,
+    /// 失败（原因在 `message`，已脱敏）
+    Failed,
+}
+
+impl DeviceLoginPhase {
+    /// 面板是否要显示（非 Idle 都显示）。
+    pub fn visible(self) -> bool {
+        !matches!(self, Self::Idle)
+    }
+
+    /// 是否还在跑（Requesting / Waiting）。
+    pub fn busy(self) -> bool {
+        matches!(self, Self::Requesting | Self::Waiting)
+    }
+}
+
+/// 设备码登录的可见状态。
+///
+/// `user_code` / `verification_uri` 来自 `core::auth::microsoft::DeviceCodePrompt`——
+/// 它们本来就是给用户看的，不是凭据。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct DeviceLoginView {
+    /// 阶段
+    pub phase: DeviceLoginPhase,
+    /// 用户码（`ABCD-EFGH`）
+    pub user_code: String,
+    /// 验证地址（`https://www.microsoft.com/link`）
+    pub verification_uri: String,
+    /// 二维码内容（= 带码的链接；GUI 用文本展示，终端可直接打开）
+    pub qr_link: String,
+    /// 有效期（秒；0 = 未知）
+    pub expires_in: u64,
+    /// 状态/错误文案（**失败时是原始诊断，只进日志，不上屏**）
+    pub message: String,
+    /// 失败原因码（`None` = 不是失败态 / 未分类）
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub failure: Option,
+    /// 成功后入库的账户展示名
+    pub account_name: String,
+}
+
+impl Default for DeviceLoginView {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl DeviceLoginView {
+    /// 空闲态。
+    pub fn new() -> Self {
+        Self {
+            phase: DeviceLoginPhase::Idle,
+            user_code: String::new(),
+            verification_uri: String::new(),
+            qr_link: String::new(),
+            expires_in: 0,
+            message: String::new(),
+            failure: None,
+            account_name: String::new(),
+        }
+    }
+
+    /// 已拿到用户码（`present` 回调时刻）。
+    pub fn waiting(
+        user_code: &str,
+        verification_uri: &str,
+        expires_in: u64,
+        qr_hint: &str,
+    ) -> Self {
+        let qr_link = if qr_hint.is_empty() {
+            format!("{verification_uri}?code={user_code}")
+        } else {
+            qr_hint.to_string()
+        };
+        Self {
+            phase: DeviceLoginPhase::Waiting,
+            user_code: user_code.to_string(),
+            verification_uri: verification_uri.to_string(),
+            qr_link,
+            expires_in,
+            message: format!(
+                "在浏览器打开 {verification_uri} 并输入用户码 {user_code}（{} 秒内有效）",
+                expires_in
+            ),
+            failure: None,
+            account_name: String::new(),
+        }
+    }
+
+    /// 授权码流：本地回调已就绪、浏览器已拉起（`present` 回调时刻）。
+    ///
+    /// 面板不展示用户码，改展示**可复制的授权链接**（用户可能需要在另一台设备/
+    /// 另一个浏览器里手动打开）；`warning` 是「浏览器没拉起来」这类非致命提示。
+    pub fn browser_waiting(
+        authorization_url: &str,
+        expires_in: u64,
+        warning: Option<&str>,
+    ) -> Self {
+        let mut message = format!(
+            "已在系统浏览器打开微软登录页，请完成授权（{} 秒内有效）；没弹出就把下面的链接粘到浏览器里",
+            expires_in.max(1)
+        );
+        if let Some(warning) = warning {
+            message.push_str(&format!("（{}）", redact(warning)));
+        }
+        Self {
+            phase: DeviceLoginPhase::Waiting,
+            user_code: String::new(),
+            verification_uri: authorization_url.to_string(),
+            qr_link: authorization_url.to_string(),
+            expires_in,
+            message,
+            failure: None,
+            account_name: String::new(),
+        }
+    }
+
+    /// 失败态（文案在入口就脱敏：错误原文里可能带着服务端回显的 token）。
+    pub fn failed(message: impl Into) -> 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 的
+/// `AuthlibAuth::authenticate` 调用栈里，host 取走即弃——不入账户库、不进日志、
+/// 不进任何回程 DTO。所以本类型只有一个方向（UI → host），回程只有 [`AuthlibLoginView`]。
+#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct AuthlibRequest {
+    /// 认证服务器地址（用户原样输入；host 侧 `normalize_api_root` 规范化）
+    pub server: String,
+    /// 登录名（邮箱或用户名）
+    pub login: String,
+    /// 密码（只在本调用栈里出现）
+    pub password: String,
+}
+
+/// **手写 `Debug`**：任何 `{:?}`（日志/panic 消息/测试失败输出）都不得带出明文密码。
+impl std::fmt::Debug for AuthlibRequest {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("AuthlibRequest")
+            .field("server", &redact(&self.server))
+            .field("login", &redact(&self.login))
+            .field("password", &REDACTED)
+            .finish()
+    }
+}
+
+impl AuthlibRequest {
+    /// 构造。
+    pub fn new(
+        server: impl Into,
+        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..3d60ffe
--- /dev/null
+++ b/crates/presenter/src/dto/accounts/failure.rs
@@ -0,0 +1,132 @@
+//! 失败原因码与账户页横幅（M114 r2 / 复审 P1-1、P2-2）。
+//!
+//! ## 为什么这一层必须有
+//!
+//! core/presenter 的诊断串是中文人话。把它们直接画到英文界面上，就是复审 r1 那条 p1
+//! （「全英文界面里整句中文」）。根因不是 catalog 缺条目，而是**后端诊断串没有结构**：
+//! 页面除了原样画没有别的选择。
+//!
+//! 这里补的就是那个缺环——把「失败属于哪一类」「这次操作的结果是什么」变成**枚举**。
+//! 页面据 `code()` 选 i18n key 出标题 + 正文 + 一行 `Code: …`；原始诊断留在 `message` /
+//! `detail` 里，**只进日志与详细信息，不上屏**。
+//!
+//! 约束：`code()` 一律 ascii 且**不随语言变**（日志、测试、用户报障都靠它对齐）。
+
+use serde::{Deserialize, Serialize};
+
+use super::redact;
+
+/// 登录失败的**结构化原因码**（M114 r2 / 复审 P1-1）。
+///
+/// 为什么要有它：core/presenter 的诊断串是中文人话，**直接上屏**会让英文界面里出现整句中文
+/// （复审 r1 的 p1）。这里把「失败属于哪一类」变成**可判据的枚举**，页面据码选 i18n key 出
+/// 标题 + 正文 + 一个稳定 code；原始诊断只留在 `message` 里进日志/详细信息，**不上屏**。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum LoginFailure {
+    /// 服务器/微软明确拒绝（403、OAuth `error`、XErr）
+    Denied,
+    /// 应用注册还没获批（AADSTS7000218 一类「白名单未批」）
+    NotWhitelisted,
+    /// 网络不可达 / 超时
+    Unreachable,
+    /// 目标地址不是 authlib-injector 服务器（响应不是服务发现 JSON）
+    NotAuthlibServer,
+    /// 服务器拒绝了这个账号（密码错 / 账号不存在）
+    BadCredentials,
+    /// 服务器没有返回角色（账号还没创建角色）
+    NoProfile,
+    /// 落盘失败（账户库读写）
+    StoreFailed,
+    /// 其它（未知原因；原文只在 `message`）
+    Other,
+}
+
+impl LoginFailure {
+    /// 稳定的 ascii code（日志 / 页面「Code: …」/ 测试断言都用它，**不随语言变**）。
+    #[must_use]
+    pub const fn code(self) -> &'static str {
+        match self {
+            Self::Denied => "denied",
+            Self::NotWhitelisted => "whitelist_pending",
+            Self::Unreachable => "unreachable",
+            Self::NotAuthlibServer => "not_authlib_server",
+            Self::BadCredentials => "bad_credentials",
+            Self::NoProfile => "no_profile",
+            Self::StoreFailed => "store_failed",
+            Self::Other => "other",
+        }
+    }
+}
+
+/// 账户页的**一次性横幅**（添加/删除/切换的结果；页面据 `code` 选 i18n）。
+///
+/// 为什么不是 toast：app-iced 不渲染 toast（复审 r1 P2-2 实锤），发 toast 等于用户什么都看不到。
+/// 横幅是页面上的真实控件，用户点了「Create profile」失败后一定看得见。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct AccountNotice {
+    /// 结果码（决定标题/正文/颜色）
+    pub code: AccountNoticeCode,
+    /// 涉及的账户名或服务器（拼进文案；可为空）
+    pub subject: String,
+    /// 原始诊断（已脱敏；**只进日志/详细信息，不上屏**）
+    pub detail: String,
+}
+
+impl AccountNotice {
+    /// 构造。
+    pub fn new(
+        code: AccountNoticeCode,
+        subject: impl Into,
+        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/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..8693d57
--- /dev/null
+++ b/crates/presenter/src/dto/content.rs
@@ -0,0 +1,366 @@
+//! 内容库 DTO（M109 `CONTENTDL`）：Modrinth / CurseForge 上「整合包 / Mod / 资源包 / 光影」的
+//! **检索**与**装入指定实例**。
+//!
+//! ## 为什么这些类型在 presenter 而不是 core
+//!
+//! D3 / 01c §5：UI 只经 `crate::dto` 消费后端，跨边界类型必须可序列化。而**检索本身**
+//! （HTTP + 两个站点的 JSON 方言）今天落在 `crate::host::addon`：`crates/core` 的 `addon` 模块
+//! 只有加载器安装与整合包**格式**解析，没有 CF / Modrinth 的 API 客户端（M111 才做导入管线）。
+//! 所以这是「宿主层临时落点」的契约面——长期应下沉到 `core::addon`，届时这里只留薄 DTO。
+//!
+//! 两个形状是**故意**的：
+//!
+//! - [`ContentHit::game_versions`] / [`ContentHit::loaders`] 来自检索结果的 facets ⇒ 页面在用户
+//!   **点之前**就能判「装不装得上」（任务书第 3 条），不用点完才报错；
+//! - [`ContentKind::dir`] 的 `None`（整合包）是「按钮禁用」的**唯一**判据，不是一个文案开关。
+//!
+//! ## 密钥纪律（任务书第 5 条）
+//!
+//! CurseForge 的 `X-API-KEY` 从环境变量 `ULL_CF_API_KEY` 读，**不进仓库、不进 DTO、不进日志**。
+//! 这里只有 [`ContentResults::curseforge`] 一个 `bool`：源可用与否。
+//! 于是「密钥泄漏」在类型层就不可能——本 crate 没有任何字段能装下它。
+
+use serde::{Deserialize, Serialize};
+
+use crate::dto::{InstanceId, LoaderKind};
+
+/// 内容类型（内容库页左侧那四条一级侧栏）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum ContentKind {
+    /// 整合包（Modpack）
+    Modpack,
+    /// Mod
+    Mod,
+    /// 资源包（Resource pack）
+    Resourcepack,
+    /// 光影（Shader pack）
+    Shader,
+}
+
+impl ContentKind {
+    /// 四条侧栏的声明顺序（= 画出来的顺序）。
+    pub const ALL: [ContentKind; 4] = [
+        ContentKind::Modpack,
+        ContentKind::Mod,
+        ContentKind::Resourcepack,
+        ContentKind::Shader,
+    ];
+
+    /// 稳定 slug（日志 / 文件名 / 命令行参数用，**不要改名**）。
+    #[must_use]
+    pub const fn slug(self) -> &'static str {
+        match self {
+            Self::Modpack => "modpack",
+            Self::Mod => "mod",
+            Self::Resourcepack => "resourcepack",
+            Self::Shader => "shader",
+        }
+    }
+
+    /// Modrinth 的 `project_type` facet 值。
+    #[must_use]
+    pub const fn modrinth_type(self) -> &'static str {
+        match self {
+            Self::Modpack => "modpack",
+            Self::Mod => "mod",
+            Self::Resourcepack => "resourcepack",
+            Self::Shader => "shader",
+        }
+    }
+
+    /// 装入实例时的落盘目录（相对运行目录）；`None` = 不是「一个文件进一个目录」这种语义。
+    ///
+    /// 整合包没有目录：它要走 core 的导入管线（解压 + 补全 + 登记实例），那是 M111 的活，
+    /// 所以这里是 `None`——**按钮禁用由这个 `None` 驱动**，不是靠一句文案。
+    #[must_use]
+    pub const fn dir(self) -> Option<&'static str> {
+        match self {
+            Self::Modpack => None,
+            Self::Mod => Some("mods"),
+            Self::Resourcepack => Some("resourcepacks"),
+            Self::Shader => Some("shaderpacks"),
+        }
+    }
+
+    /// CurseForge 的 `classId`（CF API 的类目字段；数值是官方文档里的固定值）。
+    #[must_use]
+    pub const fn curseforge_class(self) -> u32 {
+        match self {
+            Self::Modpack => 4471,
+            Self::Mod => 6,
+            Self::Resourcepack => 12,
+            Self::Shader => 6552,
+        }
+    }
+}
+
+/// 内容来源。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum ContentSource {
+    /// Modrinth（无需 API key，默认源）
+    Modrinth,
+    /// CurseForge（需要 `ULL_CF_API_KEY`）
+    Curseforge,
+}
+
+impl ContentSource {
+    /// 两个来源的声明顺序（= 筛选条顺序）。
+    pub const ALL: [ContentSource; 2] = [ContentSource::Modrinth, ContentSource::Curseforge];
+
+    /// 稳定 slug。
+    #[must_use]
+    pub const fn slug(self) -> &'static str {
+        match self {
+            Self::Modrinth => "modrinth",
+            Self::Curseforge => "curseforge",
+        }
+    }
+}
+
+/// 排序方式（两个站点的官方排序项，口径对齐后再映射到各自参数）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum ContentSort {
+    /// 相关度（Modrinth `relevance`；CF 没有对应项，退回热度）
+    Relevance,
+    /// 下载量
+    Downloads,
+    /// 最新发布
+    Newest,
+    /// 最近更新
+    Updated,
+}
+
+impl ContentSort {
+    /// 四种排序的声明顺序。
+    pub const ALL: [ContentSort; 4] = [
+        ContentSort::Relevance,
+        ContentSort::Downloads,
+        ContentSort::Newest,
+        ContentSort::Updated,
+    ];
+
+    /// Modrinth `/v2/search` 的 `index` 参数值。
+    #[must_use]
+    pub const fn modrinth_index(self) -> &'static str {
+        match self {
+            Self::Relevance => "relevance",
+            Self::Downloads => "downloads",
+            Self::Newest => "newest",
+            Self::Updated => "updated",
+        }
+    }
+
+    /// CurseForge 的 `sortField`（1 = 热度，2 = 更新，3 = 发布，4 = 名称）。
+    #[must_use]
+    pub const fn curseforge_field(self) -> u32 {
+        match self {
+            Self::Relevance | Self::Downloads => 1,
+            Self::Newest => 3,
+            Self::Updated => 2,
+        }
+    }
+}
+
+/// 加载器 → Modrinth 的 loader facet 值；`None` = 该加载器没有对应 facet（原版等）。
+#[must_use]
+pub const fn loader_facet(loader: LoaderKind) -> Option<&'static str> {
+    match loader {
+        LoaderKind::Fabric => Some("fabric"),
+        LoaderKind::Quilt => Some("quilt"),
+        LoaderKind::Forge => Some("forge"),
+        LoaderKind::NeoForge => Some("neoforge"),
+        LoaderKind::Vanilla | LoaderKind::OptiFine | LoaderKind::LiteLoader => None,
+    }
+}
+
+/// 一次检索请求（**页面把它整份发出去**，不做本地过滤之外的乐观处理）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ContentQuery {
+    /// 内容类型
+    pub kind: ContentKind,
+    /// 来源
+    pub source: ContentSource,
+    /// 关键词（空串 = 不带 `query` 参数，即「按热度浏览」）
+    pub text: String,
+    /// 游戏版本过滤（`None` = 不过滤）
+    pub game_version: Option,
+    /// 加载器过滤（`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,
+}
+
+/// 内容库页的状态（M109）：**检索条件 + 最近一批结果 + 请求态**。
+///
+/// 条件为什么也存在这里：页面层不持有业务状态是老纪律（同 `download_query`）；换页只挪游标、
+/// 条件只有一份，才不会出现「筛选条说的是 A、列表画的是 B」。
+#[derive(Debug, Clone, PartialEq)]
+pub struct ContentState {
+    /// 当前检索条件（游标也在里面：换页就是换一份 `query`）
+    pub query: ContentQuery,
+    /// 最近一批结果（`None` = 还没拉过）
+    pub results: Option,
+    /// 有请求在飞（页面画加载态的依据；命中项只由事件写进来，不做乐观回显）
+    pub pending: bool,
+    /// 最近一次失败的原文（`None` = 没失败）
+    pub failed: Option,
+    /// **最近一页**是否装满（`hits.len() >= limit`）。
+    ///
+    /// 为什么不是「累计条数够一页」：分页是**累加**到 `results.hits` 里的，累计值在第 2 页之后
+    /// 必然 ≥ limit ⇒ 用累计判会得到「has_more 恒真」：加载更多永不消失、「没有更多了」在真实
+    /// 翻页路径上不可达，而且每点一次白发一次网络请求（复审 P1-2）。所以这一位单独记。
+    pub last_page_filled: bool,
+}
+
+impl Default for ContentState {
+    fn default() -> Self {
+        Self {
+            query: ContentQuery::first(ContentKind::Mod),
+            results: None,
+            pending: false,
+            failed: None,
+            last_page_filled: false,
+        }
+    }
+}
+
+impl ContentState {
+    /// 这批结果还算当前条件吗（`false` = 迟到的事件，丢掉，不许覆盖新的筛选结果）。
+    #[must_use]
+    pub fn accepts(&self, results: &ContentResults) -> bool {
+        results.query.same_filters(&self.query)
+    }
+}
+#[cfg(test)]
+mod tests;
diff --git a/crates/presenter/src/dto/content/tests.rs b/crates/presenter/src/dto/content/tests.rs
new file mode 100644
index 0000000..daed624
--- /dev/null
+++ b/crates/presenter/src/dto/content/tests.rs
@@ -0,0 +1,87 @@
+//! 内容库 DTO 的守门测试（M109）。从 `dto/content.rs` 拆出：那个文件已贴 400 行硬上限。
+
+use super::*;
+
+fn hit(game_versions: Vec, 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..c4508a7
--- /dev/null
+++ b/crates/presenter/src/dto/events.rs
@@ -0,0 +1,338 @@
+//! 事件与指令：core/agent → app 的事件队列，app → core/agent 的用户意图。
+//!
+//! 三条通道（01c §5）：①不可变快照发布（`*Changed` 整体替换）②事件流（`LogAppended` /
+//! `InstallProgress` / `DeviceLoginChanged`）③注入的显示服务（先落成事件，见 `DialogRequested`）。
+//! 全部类型 `Serialize + Deserialize`：这是 IPC 契约（AGENTS §6）。
+
+use serde::{Deserialize, Serialize};
+
+use crate::dialogs::{DialogId, DialogRequest};
+use crate::dto::CreateRequest;
+use crate::dto::{
+    // 主线（M109 的 Content* / M113 的 Pack*）与 M114 的 Authlib*/AccountNotice 的并集。
+    AccountNotice,
+    AccountView,
+    AgentEvent,
+    AuthlibLoginView,
+    AuthlibRequest,
+    ContentInstallRequest,
+    ContentQuery,
+    ContentResults,
+    DeviceLoginView,
+    DiagnosisReport,
+    InstallProgressView,
+    InstanceId,
+    InstanceRuntime,
+    InstanceSummary,
+    JavaPageView,
+    LoaderKind,
+    LogLine,
+    LogOutcome,
+    LogSession,
+    NoticeView,
+    PackCommand,
+    PackEvent,
+    SessionId,
+    SettingGroupView,
+    VersionCategory,
+    VersionSummary,
+};
+use crate::toast::Toast;
+
+/// 启动会话的一段实时日志（host 尾随 JSONL 后按批次发）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct LiveLogBatch {
+    /// 会话 id
+    pub session: SessionId,
+    /// 新增行
+    pub lines: Vec,
+    /// 会话是否还在跑（false = 收尾，可以触发诊断/刷新列表）
+    pub running: bool,
+}
+
+/// 一次启动收尾（磁贴状态回写 + 日志页会话列表刷新）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct LaunchFinished {
+    /// 实例 id
+    pub id: InstanceId,
+    /// 会话 id
+    pub session: SessionId,
+    /// 结局
+    pub outcome: LogOutcome,
+    /// 一句人读结论（`正常退出` / `崩溃（exit 1）` / `启动失败：…`）
+    pub summary: String,
+}
+
+/// core 侧事件（不可变快照发布 + 事件流，01c §5 的三条通道之二）。
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub enum CoreEvent {
+    /// 实例列表整体刷新
+    InstancesChanged(Vec),
+    /// 单个实例运行时状态变化（启动进度/运行中/失败）
+    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）：一句人读原因（没网 / 站点限速 / 缺密钥）
+    ContentFailed(String),
+    // M113: import/export
+    /// 导入/导出（M113）：进度、结果、探测诊断、导出预检（子枚举见 [`PackEvent`]）
+    Pack(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,
+    },
+    /// 刷新日志会话列表
+    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),
+    // M113: import/export
+    /// 整合包导入/导出（M113）：导入 / 预检 / 确认写盘 / 关面板（子枚举见 [`PackCommand`]）
+    Pack(Box),
+}
+
+impl AppCommand {
+    /// 构造「切换隔离档位」指令（磁贴/详情页共用）。
+    pub fn set_isolation(id: &str, mode: &str) -> Self {
+        Self::SetIsolation {
+            id: id.to_string(),
+            mode: mode.to_string(),
+        }
+    }
+}
+
+/// 后端通道：core/agent host 实现它；[`crate::mock::MockBackend`] 验证通道语义。
+///
+/// 轮询模型（而非回调）是为了让 Slint 的定时器成为唯一调度者，
+/// 避免跨线程回调里碰 Slint 模型。
+pub trait Backend {
+    /// 取走自上次调用以来积压的事件（FIFO，不可丢序号）。
+    fn drain_events(&mut self) -> Vec;
+
+    /// 下发一条用户意图。
+    fn dispatch(&mut self, command: AppCommand);
+
+    /// 时间推进（真实后端在这里收后台线程的结果并尾随日志）。
+    fn tick(&mut self, elapsed: std::time::Duration) {
+        let _ = elapsed;
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::dto::{AccountKind, DeviceLoginPhase, InstallStage};
+
+    #[test]
+    fn events_are_serializable_ipc_contracts() {
+        let event = AppEvent::Core(CoreEvent::InstallProgress(Some(InstallProgressView {
+            stage: InstallStage::Downloading,
+            files_done: 3,
+            files_total: 9,
+            ..InstallProgressView::new()
+        })));
+        let text = serde_json::to_string(&event).expect("序列化");
+        let back: AppEvent = serde_json::from_str(&text).expect("反序列化");
+        assert_eq!(back, event);
+
+        let account = AppEvent::Core(CoreEvent::AccountsChanged(vec![AccountView {
+            id: "account:1".to_string(),
+            name: "Steve".to_string(),
+            kind: AccountKind::Offline,
+            profile_id: "0f8f".to_string(),
+            login_name: String::new(),
+            created: "2026-10-31 20:12".to_string(),
+            active: true,
+            server_url: String::new(),
+            skin: None,
+        }]));
+        let text = serde_json::to_string(&account).expect("序列化");
+        let back: AppEvent = serde_json::from_str(&text).expect("反序列化");
+        assert_eq!(back, account);
+        // 凭据永不跨界：序列化文本里没有 token 类字段
+        assert!(!text.to_lowercase().contains("token"));
+    }
+
+    #[test]
+    fn commands_round_trip() {
+        let command = AppCommand::CreateInstance(CreateRequest {
+            version: "1.20.4".to_string(),
+            loader: crate::dto::LoaderKind::Fabric,
+            loader_version: "0.16.5".to_string(),
+            name: "生存".to_string(),
+        });
+        let text = serde_json::to_string(&command).expect("序列化");
+        let back: AppCommand = serde_json::from_str(&text).expect("反序列化");
+        assert_eq!(back, command);
+
+        let login = AppCommand::StartDeviceLogin;
+        assert_eq!(
+            serde_json::from_str::(&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..a960a22
--- /dev/null
+++ b/crates/presenter/src/dto/install.rs
@@ -0,0 +1,249 @@
+//! 安装进度 DTO：下载页与新建向导共用的「一个安装任务」视图。
+//!
+//! 只放聚合量（文件计数 / 字节 / 速度 / 剩余时间）+ 一行状态文案：
+//! 逐文件的明细留在 core 的 `InstallReport`，UI 不需要也不该持有。
+//! 速度与 ETA 由 host 依据相邻两次字节数差分算（core 的事件只给绝对值）。
+
+use serde::{Deserialize, Serialize};
+
+/// 安装阶段。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum InstallStage {
+    /// 解析版本清单 / 规划文件（联网取 metadata）
+    Planning,
+    /// 下载并校验文件
+    Downloading,
+    /// 落版本 JSON / 跑安装器
+    Installing,
+    /// 登记实例
+    Registering,
+    /// 完成
+    Done,
+    /// 失败
+    Failed,
+    /// 用户取消
+    Cancelled,
+}
+
+impl InstallStage {
+    /// 阶段文案。
+    pub fn label(self) -> &'static str {
+        match self {
+            Self::Planning => "解析版本",
+            Self::Downloading => "下载文件",
+            Self::Installing => "生成版本",
+            Self::Registering => "登记实例",
+            Self::Done => "已完成",
+            Self::Failed => "失败",
+            Self::Cancelled => "已取消",
+        }
+    }
+
+    /// 是否已经收尾（Done/Failed/Cancelled）。
+    pub fn is_terminal(self) -> bool {
+        matches!(self, Self::Done | Self::Failed | Self::Cancelled)
+    }
+}
+
+/// 一次安装的进度快照。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct InstallProgressView {
+    /// 目标版本 id
+    pub version: String,
+    /// 实例名（默认 = 版本 id）
+    pub instance: String,
+    /// 加载器徽标文字（`原版` / `Fabric 0.16.5`）
+    pub loader: String,
+    /// 阶段
+    pub stage: InstallStage,
+    /// 已完成文件数
+    pub files_done: u64,
+    /// 文件总数
+    pub files_total: u64,
+    /// 已下载字节
+    pub bytes_done: u64,
+    /// 总字节（0 = 未知）
+    pub bytes_total: u64,
+    /// 当前速度（字节/秒；0 = 未知）
+    pub speed_bps: u64,
+    /// 剩余秒数（0 = 未知）
+    pub eta_secs: u64,
+    /// 状态/错误文案
+    pub message: String,
+}
+
+impl Default for InstallProgressView {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl InstallProgressView {
+    /// 规划中的空快照。
+    pub fn new() -> Self {
+        Self {
+            version: String::new(),
+            instance: String::new(),
+            loader: String::new(),
+            stage: InstallStage::Planning,
+            files_done: 0,
+            files_total: 0,
+            bytes_done: 0,
+            bytes_total: 0,
+            speed_bps: 0,
+            eta_secs: 0,
+            message: String::new(),
+        }
+    }
+
+    /// 起一个任务的快照。
+    pub fn start(version: &str, instance: &str, loader: &str) -> Self {
+        Self {
+            version: version.to_string(),
+            instance: instance.to_string(),
+            loader: loader.to_string(),
+            stage: InstallStage::Planning,
+            message: "正在解析版本清单…".to_string(),
+            ..Self::new()
+        }
+    }
+
+    /// 整体进度 0.0~1.0（优先文件计数，其次字节；都没有时 0）。
+    pub fn ratio(&self) -> f32 {
+        if self.files_total > 0 {
+            (self.files_done as f32 / self.files_total as f32).clamp(0.0, 1.0)
+        } else if self.bytes_total > 0 {
+            (self.bytes_done as f32 / self.bytes_total as f32).clamp(0.0, 1.0)
+        } else {
+            0.0
+        }
+    }
+
+    /// 进度是否已知（未知时进度条转不确定态）。
+    pub fn is_known(&self) -> bool {
+        self.files_total > 0 || self.bytes_total > 0
+    }
+
+    /// 速度文案（`1.2 MB/s`；未知给空串）。
+    pub fn speed_label(&self) -> String {
+        if self.speed_bps == 0 {
+            return String::new();
+        }
+        format!("{}/s", human_bytes(self.speed_bps))
+    }
+
+    /// 剩余时间文案（`剩 12s`；未知给空串）。
+    pub fn eta_label(&self) -> String {
+        if self.eta_secs == 0 {
+            return String::new();
+        }
+        if self.eta_secs >= 60 {
+            format!("剩 {}m{:02}s", self.eta_secs / 60, self.eta_secs % 60)
+        } else {
+            format!("剩 {}s", self.eta_secs)
+        }
+    }
+
+    /// 文件计数文案（`128/512 文件`）。
+    pub fn files_label(&self) -> String {
+        if self.files_total == 0 {
+            return String::new();
+        }
+        format!("{}/{} 文件", self.files_done, self.files_total)
+    }
+}
+
+/// 字节数 → 人读（`1.2 MB`）。
+pub fn human_bytes(bytes: u64) -> String {
+    const UNITS: [&str; 5] = ["B", "KB", "MB", "GB", "TB"];
+    let mut value = bytes as f64;
+    let mut unit = 0;
+    while value >= 1024.0 && unit + 1 < UNITS.len() {
+        value /= 1024.0;
+        unit += 1;
+    }
+    if unit == 0 {
+        format!("{bytes} B")
+    } else {
+        format!("{value:.1} {}", UNITS[unit])
+    }
+}
+
+/// 用相邻两次采样算速度与 ETA（`None` = 本次无法计算，保持上次值）。
+pub fn derive_speed(
+    previous: (u64, std::time::Instant),
+    current: (u64, std::time::Instant),
+    bytes_total: u64,
+) -> Option<(u64, u64)> {
+    let elapsed = current.1.saturating_duration_since(previous.1);
+    if elapsed.as_millis() < 50 {
+        return None;
+    }
+    let delta = current.0.saturating_sub(previous.0);
+    if delta == 0 {
+        return None;
+    }
+    let elapsed_ms = u64::try_from(elapsed.as_millis()).unwrap_or(u64::MAX);
+    let speed = delta.saturating_mul(1000) / elapsed_ms.max(1);
+    let eta = if bytes_total > current.0 && speed > 0 {
+        (bytes_total - current.0) / speed
+    } else {
+        0
+    };
+    Some((speed, eta))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::time::{Duration, Instant};
+
+    #[test]
+    fn ratio_prefers_file_counts() {
+        let mut view = InstallProgressView::start("1.20.4", "1.20.4", "原版");
+        assert_eq!(view.ratio(), 0.0);
+        assert!(!view.is_known());
+
+        view.files_total = 4;
+        view.files_done = 1;
+        view.bytes_total = 1000;
+        view.bytes_done = 900;
+        assert!((view.ratio() - 0.25).abs() < f32::EPSILON);
+        assert!(view.is_known());
+        assert_eq!(view.files_label(), "1/4 文件");
+    }
+
+    #[test]
+    fn speed_and_eta_labels_are_human_readable() {
+        let view = InstallProgressView {
+            speed_bps: 1_258_291,
+            eta_secs: 75,
+            ..InstallProgressView::new()
+        };
+        assert_eq!(view.speed_label(), "1.2 MB/s");
+        assert_eq!(view.eta_label(), "剩 1m15s");
+        assert_eq!(InstallProgressView::new().speed_label(), "");
+    }
+
+    #[test]
+    fn derive_speed_needs_a_measurable_delta() {
+        let start = Instant::now();
+        let previous = (0, start);
+        // 间隔太短 → 不算
+        assert!(derive_speed(previous, (500, start + Duration::from_millis(10)), 1000).is_none());
+        // 正常差分：1s 下 500 字节 → 500 B/s，剩 500 字节 → 1s
+        let (speed, eta) =
+            derive_speed(previous, (500, start + Duration::from_secs(1)), 1000).expect("应能算");
+        assert_eq!(speed, 500);
+        assert_eq!(eta, 1);
+    }
+
+    #[test]
+    fn terminal_stages() {
+        assert!(InstallStage::Done.is_terminal());
+        assert!(InstallStage::Failed.is_terminal());
+        assert!(!InstallStage::Downloading.is_terminal());
+        assert_eq!(human_bytes(512), "512 B");
+        assert_eq!(human_bytes(2048), "2.0 KB");
+    }
+}
diff --git a/crates/presenter/src/dto/instances.rs b/crates/presenter/src/dto/instances.rs
new file mode 100644
index 0000000..47b9078
--- /dev/null
+++ b/crates/presenter/src/dto/instances.rs
@@ -0,0 +1,296 @@
+//! 实例相关 DTO：磁贴与列表视图的唯一数据源。
+
+use serde::{Deserialize, Serialize};
+
+use std::path::PathBuf;
+
+/// 实例标识：core::game 生成的稳定 id，app 视为不透明字符串。
+pub type InstanceId = String;
+
+/// 加载器种类（磁贴徽标 + 详情页版本链）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum LoaderKind {
+    /// 原版（无加载器）
+    Vanilla,
+    /// Fabric
+    Fabric,
+    /// Quilt
+    Quilt,
+    /// Forge
+    Forge,
+    /// NeoForge
+    NeoForge,
+    /// OptiFine
+    OptiFine,
+    /// LiteLoader
+    LiteLoader,
+}
+
+impl LoaderKind {
+    /// 徽标显示文字。
+    pub fn label(self) -> &'static str {
+        match self {
+            Self::Vanilla => "原版",
+            Self::Fabric => "Fabric",
+            Self::Quilt => "Quilt",
+            Self::Forge => "Forge",
+            Self::NeoForge => "NeoForge",
+            Self::OptiFine => "OptiFine",
+            Self::LiteLoader => "LiteLoader",
+        }
+    }
+
+    /// 稳定 id（`vanilla` / `fabric` / …；GUI 与 CLI 的 `--loader` 同词表）。
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Vanilla => "vanilla",
+            Self::Fabric => "fabric",
+            Self::Quilt => "quilt",
+            Self::Forge => "forge",
+            Self::NeoForge => "neoforge",
+            Self::OptiFine => "optifine",
+            Self::LiteLoader => "liteloader",
+        }
+    }
+
+    /// 从稳定 id 解析（未知给 `None`，由调用方决定报错文案）。
+    pub fn parse(raw: &str) -> Option {
+        Some(match raw.trim().to_ascii_lowercase().as_str() {
+            "vanilla" | "none" | "" => Self::Vanilla,
+            "fabric" => Self::Fabric,
+            "quilt" => Self::Quilt,
+            "forge" => Self::Forge,
+            "neoforge" => Self::NeoForge,
+            "optifine" => Self::OptiFine,
+            "liteloader" => Self::LiteLoader,
+            _ => return None,
+        })
+    }
+
+    /// 向导里的可选加载器（顺序即展示顺序）。
+    pub fn wizard_choices() -> [Self; 5] {
+        [
+            Self::Vanilla,
+            Self::Fabric,
+            Self::Quilt,
+            Self::Forge,
+            Self::NeoForge,
+        ]
+    }
+}
+
+/// 加载器 + 版本（例如 Fabric 0.16.5）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct LoaderInfo {
+    /// 加载器种类
+    pub kind: LoaderKind,
+    /// 加载器版本号；原版为空串
+    pub version: String,
+}
+
+impl Default for LoaderInfo {
+    fn default() -> Self {
+        Self {
+            kind: LoaderKind::Vanilla,
+            version: String::new(),
+        }
+    }
+}
+
+impl LoaderInfo {
+    /// 徽标文字：原版只写「原版」，装加载器时写「Fabric 0.16.5」。
+    pub fn badge(&self) -> String {
+        if self.kind == LoaderKind::Vanilla || self.version.is_empty() {
+            self.kind.label().to_string()
+        } else {
+            format!("{} {}", self.kind.label(), self.version)
+        }
+    }
+}
+
+/// 字节进度；`total == 0` 表示总量未知（UI 转不确定态）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
+pub struct Progress {
+    /// 已完成量
+    pub done: u64,
+    /// 总量；0 = 未知
+    pub total: u64,
+}
+
+impl Progress {
+    /// 0.0~1.0；未知总量返回 0.0。
+    pub fn ratio(self) -> f32 {
+        if self.total == 0 {
+            0.0
+        } else {
+            (self.done as f32 / self.total as f32).clamp(0.0, 1.0)
+        }
+    }
+
+    /// 总量是否已知。
+    pub fn is_known(self) -> bool {
+        self.total > 0
+    }
+}
+
+/// 启动管线阶段（磁贴进度环的文案来源；D8 的 10 阶段在 P1 细化）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum LaunchStage {
+    /// 下载资源
+    Download,
+    /// 校验文件
+    Verify,
+    /// 组装命令行并拉起进程
+    Launch,
+    /// 进程已起、等待游戏窗口（M28 的窗口检测阶段）
+    Window,
+}
+
+impl LaunchStage {
+    /// 磁贴上的阶段文案。
+    pub fn label(self) -> &'static str {
+        match self {
+            Self::Download => "下载资源",
+            Self::Verify => "校验文件",
+            Self::Launch => "组装命令行",
+            Self::Window => "等待窗口",
+        }
+    }
+}
+
+/// 实例运行时状态（磁贴的四种外观）。
+#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
+pub enum InstanceRuntime {
+    /// 空闲
+    #[default]
+    Idle,
+    /// 启动管线进行中
+    Busy {
+        /// 当前阶段
+        stage: LaunchStage,
+        /// 该阶段进度
+        progress: Progress,
+    },
+    /// 游戏进程存活
+    Running {
+        /// 进程号（停止/诊断用）
+        pid: u32,
+    },
+    /// 上次启动失败（磁贴显示「重试」）
+    Failed {
+        /// 失败原因（用户可见文案）
+        reason: String,
+    },
+}
+
+/// 实例摘要：磁贴/列表视图唯一数据源。
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct InstanceSummary {
+    /// 稳定 id
+    pub id: InstanceId,
+    /// 显示名
+    pub name: String,
+    /// 游戏版本（如 1.20.4）
+    pub mc_version: String,
+    /// 加载器信息
+    pub loader: LoaderInfo,
+    /// ISO-8601 UTC 最后游玩时间；None = 从未启动
+    pub last_played: Option,
+    /// 运行时状态
+    pub runtime: InstanceRuntime,
+    /// 实例图标路径（P0 直接给路径；P1 换成 core 提供的图像句柄）
+    pub icon: Option,
+    /// 隔离档位（`isolated` / `shared` / `custom`；未知为空）
+    pub isolation: String,
+    /// 该实例绑定的版本 id（详情页/启动用）
+    pub version_id: String,
+    /// 版本本体是否在盘上（缺载荷时磁贴亮黄条）
+    pub version_present: bool,
+}
+
+/// 新建实例向导提交给 host 的请求（已通过向导校验）。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct CreateRequest {
+    /// 目标原版版本 id（`1.20.4`）
+    pub version: String,
+    /// 加载器
+    pub loader: LoaderKind,
+    /// 加载器版本（空 = 让 core 取最新）
+    pub loader_version: String,
+    /// 实例名（空 = 用版本 id / 加载器版本 id）
+    pub name: String,
+}
+
+impl CreateRequest {
+    /// 实际使用的实例名。
+    pub fn instance_name(&self) -> String {
+        if self.name.trim().is_empty() {
+            self.version.clone()
+        } else {
+            self.name.trim().to_string()
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn loader_badges_and_ids() {
+        let vanilla = LoaderInfo::default();
+        assert_eq!(vanilla.badge(), "原版");
+        let fabric = LoaderInfo {
+            kind: LoaderKind::Fabric,
+            version: "0.16.5".to_string(),
+        };
+        assert_eq!(fabric.badge(), "Fabric 0.16.5");
+        for kind in LoaderKind::wizard_choices() {
+            assert_eq!(LoaderKind::parse(kind.as_str()), Some(kind));
+        }
+        assert_eq!(LoaderKind::parse("fabric"), Some(LoaderKind::Fabric));
+        assert_eq!(LoaderKind::parse("unknown"), None);
+    }
+
+    #[test]
+    fn progress_ratio_handles_unknown_total() {
+        assert_eq!(Progress { done: 1, total: 0 }.ratio(), 0.0);
+        assert!((Progress { done: 1, total: 4 }.ratio() - 0.25).abs() < f32::EPSILON);
+    }
+
+    #[test]
+    fn create_request_defaults_name_to_version() {
+        let request = CreateRequest {
+            version: "1.20.4".to_string(),
+            loader: LoaderKind::Vanilla,
+            loader_version: String::new(),
+            name: "  ".to_string(),
+        };
+        assert_eq!(request.instance_name(), "1.20.4");
+    }
+
+    #[test]
+    fn instance_summary_is_serde_round_trip_safe() {
+        let instance = InstanceSummary {
+            id: "inst-1".to_string(),
+            name: "生存".to_string(),
+            mc_version: "1.20.4".to_string(),
+            loader: LoaderInfo {
+                kind: LoaderKind::Fabric,
+                version: "0.16.5".to_string(),
+            },
+            last_played: Some("2026-10-31T12:00:00.000Z".to_string()),
+            runtime: InstanceRuntime::Busy {
+                stage: LaunchStage::Window,
+                progress: Progress { done: 1, total: 2 },
+            },
+            icon: None,
+            isolation: "isolated".to_string(),
+            version_id: "1.20.4".to_string(),
+            version_present: true,
+        };
+        let text = serde_json::to_string(&instance).expect("序列化");
+        let back: InstanceSummary = serde_json::from_str(&text).expect("反序列化");
+        assert_eq!(back, instance);
+    }
+}
diff --git a/crates/presenter/src/dto/java.rs b/crates/presenter/src/dto/java.rs
new file mode 100644
index 0000000..dad588f
--- /dev/null
+++ b/crates/presenter/src/dto/java.rs
@@ -0,0 +1,234 @@
+//! Java 页 DTO：四家发行版、回退链可视化与本地运行时清单（D23/D13）。
+//!
+//! 回退链是「可观测性」的载体：安装失败时用户要能看见「Temurin 跳过 → Oracle 失败 →
+//! Microsoft 命中」这条链，而不是只拿到一句「下载失败」。链的每一步由 host 从
+//! `core::game::java::source::ChainLog` 翻译过来。
+
+use serde::{Deserialize, Serialize};
+
+/// 一家发行版的展示行。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct JavaVendorView {
+    /// 稳定 id（`temurin` / `oracle` / `microsoft` / `zulu`）
+    pub id: String,
+    /// 展示名
+    pub display: String,
+    /// 优先级序号（1 起）
+    pub rank: u32,
+    /// 支持的 Java 大版本摘要（`21/17/11`）
+    pub majors: String,
+    /// 可用源（镜像 + 吞吐备注）
+    pub sources: Vec,
+    /// 是否已装过这家（托管目录里有现成的）
+    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/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..7c6f7ed
--- /dev/null
+++ b/crates/presenter/src/dto/mod.rs
@@ -0,0 +1,59 @@
+//! presenter ↔ core/agent 的 IPC 边界（01c §5 纪律）。
+//!
+//! 这里只允许出现「扁平 DTO / 事件 / 指令」：本 crate 的 DTO 里不得出现 `unlucky_core::*`
+//! 或 `use unlucky_agent::*` 的内部类型。core/agent 侧的 host 层负责把自身类型翻译成本模块的类型，
+//! 反向的 [`AppCommand`] 也一样。P0 阶段由 [`crate::mock`] 的假后端实现 [`Backend`] 驱动骨架，
+//! P3 起由 [`crate::host`] 的真实后端驱动全部页面。
+//!
+//! 结构：**按领域拆子模块**（instances / versions / logs / agent / accounts / java /
+//! settings / install / notices / content / events），全量 `pub use` 出去，调用方依旧写
+//! `crate::dto::InstanceSummary` 这类路径。
+//! 契约说明（字段口径、事件顺序、错误语义）见 `DevDocs/SubAgentsTalk/app-DTO通道约定.md`；
+//! UI 侧的唯一入口与 iced 接线用法见 crate 文档（`src/lib.rs`）。
+//!
+//! 全部跨界类型 `Serialize + Deserialize`（AGENTS §6）：事件与快照是 IPC 契约，
+//! 序列化能力由 derive 钉住，`dto` 的单测做 round-trip 断言。
+
+mod accounts;
+mod agent;
+mod content;
+mod events;
+mod install;
+mod instances;
+mod java;
+mod logs;
+mod notices;
+// M113: import/export —— 整合包导入/导出的 DTO（M111/M112 管线的 IPC 面）
+mod pack;
+mod settings;
+mod versions;
+
+pub use accounts::{
+    looks_like_jwt, redact, valid_offline_name, AccountKind, AccountNotice, AccountNoticeCode,
+    AccountView, AuthlibLoginView, AuthlibRequest, DeviceLoginPhase, DeviceLoginView, LoginFailure,
+    SkinImage, REDACTED,
+};
+pub use agent::{AgentEvent, ChatMessage, ChatRole, ConfirmRequest, Sensitivity, ToolCallView};
+pub use content::{
+    loader_facet, ContentHit, ContentInstallRequest, ContentKind, ContentQuery, ContentResults,
+    ContentSort, ContentSource, ContentState,
+};
+pub use events::{AppCommand, AppEvent, Backend, CoreEvent, LaunchFinished, LiveLogBatch};
+pub use install::{derive_speed, human_bytes, InstallProgressView, InstallStage};
+pub use instances::{
+    CreateRequest, InstanceId, InstanceRuntime, InstanceSummary, LaunchStage, LoaderInfo,
+    LoaderKind, Progress,
+};
+pub use java::{JavaChainOutcome, JavaChainStep, JavaPageView, JavaRuntimeView, JavaVendorView};
+pub use logs::{Diagnosis, DiagnosisReport, LogLevel, LogLine, LogOutcome, LogSession, SessionId};
+pub use notices::{NoticeLevel, NoticeView};
+// M113: import/export
+pub use pack::{
+    ConflictChoiceView, ConflictFileView, ConflictReasonView, ExportClassView, ExportDoneView,
+    ExportFileView, ExportPreviewView, ExportReasonView, ExportRequestView, ExportState,
+    FileActionView, ImportErrorView, ImportProgressView, ImportReportView, ImportRequestView,
+    ImportStageView, ImportState, ImportStatusView, ImportedFileView, MissingFileView,
+    MissingReasonView, PackCommand, PackEvent, PackFormatView, PackState, ProbeView,
+};
+pub use settings::{SettingControl, SettingGroupView, SettingRowView};
+pub use versions::{AncientKind, VersionCategory, VersionKind, VersionSummary};
diff --git a/crates/presenter/src/dto/notices.rs b/crates/presenter/src/dto/notices.rs
new file mode 100644
index 0000000..36e0ac4
--- /dev/null
+++ b/crates/presenter/src/dto/notices.rs
@@ -0,0 +1,73 @@
+//! 横幅通知 DTO：实例页/下载页顶部的「需要注意」提示条。
+//!
+//! 与 Toast 的分工：Toast 是「刚才发生了什么」（3 秒消失），通知条是
+//! 「现在需要你处理」（用户点了才收）。隔离模式切换提示（M30 `ModeChangeWarning`）
+//! 与启动失败都用它。
+
+use serde::{Deserialize, Serialize};
+
+/// 通知级别。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum NoticeLevel {
+    /// 一般信息
+    Info,
+    /// 需要留意（黄条）
+    Warn,
+    /// 失败（红条）
+    Error,
+}
+
+impl NoticeLevel {
+    /// 级别文案（无障碍/测试用）。
+    pub fn label(self) -> &'static str {
+        match self {
+            Self::Info => "信息",
+            Self::Warn => "注意",
+            Self::Error => "错误",
+        }
+    }
+}
+
+/// 一条通知。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct NoticeView {
+    /// 稳定 id（关闭时按它移除）
+    pub id: String,
+    /// 级别
+    pub level: NoticeLevel,
+    /// 标题
+    pub title: String,
+    /// 正文
+    pub body: String,
+}
+
+impl NoticeView {
+    /// 建一条。
+    pub fn new(id: &str, level: NoticeLevel, title: &str, body: &str) -> Self {
+        Self {
+            id: id.to_string(),
+            level,
+            title: title.to_string(),
+            body: body.to_string(),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn notices_are_serde_round_trip_safe() {
+        let notice = NoticeView::new(
+            "isolation:demo",
+            NoticeLevel::Warn,
+            "隔离模式已切换",
+            "旧目录里还有 mods/saves",
+        );
+        let text = serde_json::to_string(¬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..7fbd1fb
--- /dev/null
+++ b/crates/presenter/src/dto/pack.rs
@@ -0,0 +1,51 @@
+//! 整合包导入/导出 DTO（M113 `PACKUI`）：把 M111/M112 的管线结果搬过 IPC 边界。
+//!
+//! ## 为什么这里几乎是 core 报告的逐字段镜像
+//!
+//! `crate::dto` 的规矩（见 `dto/mod.rs`）：**不得出现 `unlucky_core::*` 类型**，跨边界类型必须
+//! `Serialize + Deserialize`。所以这里一面不引 core，一面又不许「按 UI 方便重新发明一套语义」——
+//! 三态、阶段、分类、原因全部**逐条对应** `core::addon::import::report` 与
+//! `core::addon::export::report`，只把 `&'static str` 的稳定码换成人读串、把 `PathBuf` 落成
+//! 页面能显示的形态。翻译（core 类型 → 本模块）发生在 `host::addon`，页面侧不认识 core。
+//!
+//! 三条不许在翻译时丢的东西：
+//!
+//! 1. **三态**（[`ImportStatusView`]）：`Partial` 不是 `Success`。把「缺了 3 个文件」说成成功，
+//!    用户会在启动后才发现缺依赖；
+//! 2. **容忍 / 致命的分野**：[`MissingFileView`] 是「搞不到某个文件」（实例可用），
+//!    [`ImportErrorView`] 是「已整包回滚」（实例零残留）。UI 必须让这两类**视觉可区分**；
+//! 3. **导出的三分类**（[`ExportClassView`]）：`Inline` 是「证明不了可被远程替代，原字节进
+//!    `overrides/`」，`Skipped` 是「压根没进包」。`skipped > 0` 意味着包**不完整**。
+//!
+//! ## 文件分工（守 400 行）
+//!
+//! | 文件 | 职责 |
+//! |---|---|
+//! | [`format`] | [`PackFormatView`]（三个格式 + slug 对齐） |
+//! | [`import`] | 请求 / 进度 / 三态 / 逐项原因 / 探测诊断 |
+//! | [`conflict`] | 冲突成因、处置、三方哈希 |
+//! | [`export`] | 三分类 / 逐条原因 / 预检 |
+//!
+//! ## 冲突：默认一侧永远是用户那一侧
+//!
+//! [`ImportRequestView::overwrite`] 缺省 `false` = `ConflictPolicy::KeepUser`。这是 M113 的硬线：
+//! **绝不默认覆盖用户改过的文件**。
+
+mod conflict;
+mod event;
+mod export;
+mod format;
+mod import;
+
+pub use conflict::{ConflictChoiceView, ConflictFileView, ConflictReasonView};
+pub use event::{PackCommand, PackEvent, PackState};
+pub use export::{
+    ExportClassView, ExportDoneView, ExportFileView, ExportPreviewView, ExportReasonView,
+    ExportRequestView, ExportState,
+};
+pub use format::PackFormatView;
+pub use import::{
+    FileActionView, ImportErrorView, ImportProgressView, ImportReportView, ImportRequestView,
+    ImportStageView, ImportState, ImportStatusView, ImportedFileView, MissingFileView,
+    MissingReasonView, ProbeView,
+};
diff --git a/crates/presenter/src/dto/pack/conflict.rs b/crates/presenter/src/dto/pack/conflict.rs
new file mode 100644
index 0000000..e5c07f1
--- /dev/null
+++ b/crates/presenter/src/dto/pack/conflict.rs
@@ -0,0 +1,71 @@
+//! 冲突的 DTO：成因、本次处置、以及三方哈希的那一条账。
+//!
+//! 三条判据与 core 的 `ConflictReason` 一一对应；`choice` 是**事后记录**（本次实际怎么处置的），
+//! 不是「逐文件决策通道」——core 今天没有那种通道（`ConflictPolicy` 是整次导入一个全局档）。
+//! 「默认保留用户那一侧」这条硬线在 `ImportRequestView::overwrite` 缺省 `false` 上。
+
+use serde::{Deserialize, Serialize};
+
+/// 冲突成因（core 的三条判据）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ConflictReasonView {
+    /// 基线里记过，磁盘内容与基线不同 ⇒ 用户改过。
+    UserModified,
+    /// 基线里记过，磁盘上却没了 ⇒ 用户删过。
+    UserDeleted,
+    /// 没有基线可判，磁盘上本来就有同名文件。
+    PreExisting,
+}
+
+impl ConflictReasonView {
+    /// 从 core 的 id 反解。
+    #[must_use]
+    pub fn from_slug(slug: &str) -> Option {
+        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..61b0038
--- /dev/null
+++ b/crates/presenter/src/dto/pack/event.rs
@@ -0,0 +1,128 @@
+//! 导入/导出的**指令、事件与面板状态**（M113）：`AppCommand::Pack` / `CoreEvent::Pack` 的载荷。
+//!
+//! ## 为什么整条流程只占一个枚举变体
+//!
+//! `AppCommand` / `CoreEvent` / `HostTask` 是这条装配链上最拥挤的三个枚举（M106/M107/M108/M109/M114
+//! 都在往里加变体）。所以导入导出**不各占一个变体**，而是各自一个 [`PackCommand`] / [`PackEvent`]
+//! 子枚举、外面只多一层包装：共享枚举里只多一行，rebase 时不用替别人定序。
+//!
+//! ## 取消是**界面级**的，不是管线级的（如实写）
+//!
+//! core 的 `import_pack` 没有取消令牌（`ImportRequest` 里没有 cancel 字段，`progress` 回调是
+//! 纯通知、拿不到控制流）。所以「取消导入」在本轮的含义是：
+//!
+//! 1. 立刻把面板收回（[`PackEvent::Progress`] 传 `None`）；
+//! 2. **丢弃**这一次运行之后回来的事件（代次比较，与 M105 的安装取消同一套做法）；
+//! 3. 后台那次导入会继续跑到结束——**它不会因为点了取消而停手**。
+//!
+//! 这条必须在报告里如实登记：把它写成「真的停下来了」就是撒谎。
+//!
+//! ## 事件 → 状态只有一条路
+//!
+//! [`PackState::apply`] 是**唯一**的写入点（与 `AppState::apply` 同一条纪律）：页面读到的进度、
+//! 报告、预检都只能从事件来，页面自己不做乐观回显。
+
+use serde::{Deserialize, Serialize};
+
+use crate::dto::pack::{
+    ExportDoneView, ExportPreviewView, ExportRequestView, ExportState, ImportProgressView,
+    ImportReportView, ImportRequestView, ImportState, ProbeView,
+};
+
+/// app → host 的导入/导出意图。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum PackCommand {
+    /// 开始导入（目标实例已选好；`instance` 为 `None` = 按 `instance_name` 新建目录）
+    Import(Box),
+    /// 跑**预检**（只扫描分类，**不写盘**）
+    Export(Box),
+    /// 确认写盘。载荷是**预检时那一份请求**，不是页面当前字段——否则「预检 A、写 B」。
+    Confirm(Box),
+    /// 关掉面板（导入结果 / 探测诊断 / 导出预检都收起来，回到入口态）
+    Dismiss,
+}
+
+/// host → app 的导入/导出事件。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum PackEvent {
+    /// 导入进度（`None` = 收回面板：取消，或流程已经给出结果）
+    Progress(Option>),
+    /// 导入结果（三态 + 逐项原因；致命失败也走它，`report.error` 里有原因）
+    Report(Box),
+    /// 探测失败：这个包看起来像什么、缺哪个标记文件
+    Probe(Box),
+    /// 导出预检结果
+    Preview(Box),
+    /// 导出写盘完成
+    Exported(Box),
+    /// 导出/预检在 host 侧失败（实例找不到、目录派生失败……一句人读原因）
+    ExportFailed(String),
+    /// 用户取消了导入：面板收回，但后台那次导入会跑完（core 没有取消令牌），
+    /// 所以留一位给界面说清「还在跑、结果作废」。
+    Cancelled,
+    /// 关掉所有面板
+    Cleared,
+}
+
+/// 导入/导出两个面板的状态（`AppState::pack` 的全部内容）。
+#[derive(Debug, Clone, PartialEq, Default)]
+pub struct PackState {
+    /// 导入侧（进度 / 结果 / 探测诊断）
+    pub import: ImportState,
+    /// 导出侧（预检 / 完成 / 失败）
+    pub export: ExportState,
+}
+
+impl PackState {
+    /// 事件 → 状态（**唯一**写入点）。
+    pub fn apply(&mut self, event: PackEvent) {
+        match event {
+            PackEvent::Progress(progress) => {
+                self.import.progress = progress.map(|progress| *progress);
+            }
+            PackEvent::Report(report) => {
+                // 结果到了：进度面板让位，探测诊断作废（这一轮已经有结论了）
+                self.import.progress = None;
+                self.import.probe = None;
+                self.import.report = Some(*report);
+            }
+            PackEvent::Probe(probe) => {
+                self.import.progress = None;
+                self.import.report = None;
+                self.import.probe = Some(*probe);
+            }
+            PackEvent::Preview(preview) => {
+                self.export.pending = false;
+                self.export.failed = None;
+                self.export.done = None;
+                self.export.preview = Some(*preview);
+            }
+            PackEvent::Exported(done) => {
+                self.export.pending = false;
+                self.export.failed = None;
+                // 写完之后预检就过期了：留着会让用户以为「还能再点一次确认」
+                self.export.preview = None;
+                self.export.done = Some(*done);
+            }
+            PackEvent::ExportFailed(reason) => {
+                self.export.pending = false;
+                self.export.failed = Some(reason);
+            }
+            PackEvent::Cancelled => {
+                self.import.progress = None;
+                self.import.cancelled = true;
+            }
+            PackEvent::Cleared => {
+                self.import = ImportState::default();
+                self.export = ExportState::default();
+            }
+        }
+    }
+
+    /// 记下「这次预检是对着哪份请求做的」（确认写盘时原样发回）。
+    pub fn set_export_request(&mut self, request: ExportRequestView) {
+        self.export.request = Some(request);
+        self.export.pending = true;
+        self.export.failed = None;
+    }
+}
diff --git a/crates/presenter/src/dto/pack/export.rs b/crates/presenter/src/dto/pack/export.rs
new file mode 100644
index 0000000..3ec6941
--- /dev/null
+++ b/crates/presenter/src/dto/pack/export.rs
@@ -0,0 +1,221 @@
+//! 导出侧 DTO：三分类 + 逐条原因 + **预检**（不写盘）。
+//!
+//! `ExportReasonView::class()` 是「原因 → 归类」的**唯一**映射处（与 core 同一条判据）；
+//! 预检（[`ExportPreviewView`]）与写盘结果用同一套计数方法，于是「将内联 N / 无法导出 M」
+//! 与最终报告的 N/M 同源。
+
+use std::path::PathBuf;
+
+use serde::{Deserialize, Serialize};
+
+use crate::dto::InstanceId;
+
+use super::format::PackFormatView;
+
+/// 导出时一条文件的归类。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ExportClassView {
+    /// 写进清单 `files[]`（靠远端引用代替本地字节）。
+    Remote,
+    /// 写进 `overrides/`（原字节照搬）。
+    Inline,
+    /// 没进包（读不了 / 符号链接 / 路径不安全）。
+    Skipped,
+}
+
+impl ExportClassView {
+    /// 从 core 的 id 反解。
+    #[must_use]
+    pub fn from_slug(slug: &str) -> Option {
+        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..2109558
--- /dev/null
+++ b/crates/presenter/src/dto/pack/import.rs
@@ -0,0 +1,341 @@
+//! 导入侧 DTO：请求、进度、三态、逐项原因、探测诊断。
+//!
+//! 三态（`Success` / `Partial` / `Failed`）与 core 一一对应，**`Partial` 不是 `Success`**；
+//! 容忍域（[`MissingFileView`]）与致命域（[`ImportErrorView`]）分属不同类型，UI 不可能混成一个列表。
+
+use std::path::PathBuf;
+
+use serde::{Deserialize, Serialize};
+
+use crate::dto::InstanceId;
+
+use super::conflict::ConflictFileView;
+use super::format::PackFormatView;
+
+/// 导入阶段（与 core 的 `ImportStage` 一一对应）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
+pub enum ImportStageView {
+    /// 读取清单（开包 + 安全四检 + 探测）。
+    Probe,
+    /// 解压 / 三方合并覆盖内容。
+    Extract,
+    /// 补全并下载远端文件。
+    Fetch,
+    /// 落地。
+    Commit,
+    /// 登记实例。
+    Register,
+}
+
+impl ImportStageView {
+    /// 五个阶段的声明顺序（= 进度条上的先后）。
+    pub const ALL: [ImportStageView; 5] = [
+        ImportStageView::Probe,
+        ImportStageView::Extract,
+        ImportStageView::Fetch,
+        ImportStageView::Commit,
+        ImportStageView::Register,
+    ];
+
+    /// 稳定 slug。
+    #[must_use]
+    pub const fn slug(self) -> &'static str {
+        match self {
+            Self::Probe => "probe",
+            Self::Extract => "extract",
+            Self::Fetch => "fetch",
+            Self::Commit => "commit",
+            Self::Register => "register",
+        }
+    }
+
+    /// 从 core 的 id 反解。
+    #[must_use]
+    pub fn from_slug(slug: &str) -> Option {
+        Self::ALL.into_iter().find(|stage| stage.slug() == slug)
+    }
+
+    /// 这一阶段有没有「逐文件」的进度（`Probe` 只看清单，没条目可数）。
+    #[must_use]
+    pub const fn counts_files(self) -> bool {
+        !matches!(self, Self::Probe)
+    }
+}
+
+/// 导入三态（`Partial` **不是** `Success`）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ImportStatusView {
+    /// 全部落地、无冲突。
+    Success,
+    /// 有缺文件或有冲突（内容不完整，但实例可用）。
+    Partial,
+    /// 致命失败，**已整包回滚**。
+    Failed,
+}
+
+impl ImportStatusView {
+    /// 稳定 slug。
+    #[must_use]
+    pub const fn slug(self) -> &'static str {
+        match self {
+            Self::Success => "success",
+            Self::Partial => "partial",
+            Self::Failed => "failed",
+        }
+    }
+
+    /// 从 core 的 id 反解。
+    #[must_use]
+    pub fn from_slug(slug: &str) -> Option {
+        match slug {
+            "success" => Some(Self::Success),
+            "partial" => Some(Self::Partial),
+            "failed" => Some(Self::Failed),
+            _ => None,
+        }
+    }
+
+    /// 实例可用吗（`Success` / `Partial` 都是「装上了」）。
+    #[must_use]
+    pub const fn installed(self) -> bool {
+        !matches!(self, Self::Failed)
+    }
+}
+
+/// 一条落地文件本次被怎么处理。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum FileActionView {
+    /// 新写入。
+    Installed,
+    /// 覆盖写入（用户没改过）。
+    Replaced,
+    /// 与包内一致，没动。
+    SkippedIdentical,
+    /// 用户改过 / 删过，按策略保留了用户那一侧。
+    KeptUser,
+}
+
+impl FileActionView {
+    /// 从 core 的 id 反解。
+    #[must_use]
+    pub fn from_slug(slug: &str) -> Option {
+        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,
+    /// 冲突翻档：`false`（**默认**）= 保留用户那一侧；`true` = 以包为准覆盖。
+    ///
+    /// 页面上把 `true` 那条写成「以包为准重新导入」，并且**只在用户显式点过之后**才发。
+    pub overwrite: bool,
+}
+
+/// 一条导入进度。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ImportProgressView {
+    /// 阶段。
+    pub stage: ImportStageView,
+    /// 阶段内已完成条目数。
+    pub done: u32,
+    /// 阶段内总条目数（`0` = 未知）。
+    pub total: u32,
+    /// 当前条目的实例内路径（阶段刚开始时为 `None`）。
+    pub current: Option,
+    /// 包名（面板标题那一行）。
+    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,
+}
+
+/// 一次**已整包回滚**的致命失败。
+#[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` 里）。
+    pub rolled_back: bool,
+}
+
+impl ImportReportView {
+    /// 真正写盘的文件条数。
+    #[must_use]
+    pub fn written(&self) -> usize {
+        self.files.iter().filter(|file| file.action.wrote()).count()
+    }
+
+    /// 要用户看一眼的东西条数（冲突 + 缺文件 + 被拒 component）。
+    #[must_use]
+    pub fn issue_count(&self) -> usize {
+        self.conflicts.len() + self.missing.len() + self.rejected.len()
+    }
+}
+
+/// 探测失败的**具名**诊断：「看起来像 X，但缺 Y」。
+///
+/// 为什么不由 core 给：core 的 `detect` 只回答「谁认领」，一个都不认领时只回一句
+/// `pack_unsupported` + 试过哪些格式。而用户手里那个包往往**差一点点**就是某个已知格式
+/// （CF 导出漏了 `manifest.json`、mrpack 被浏览器改名成 `.zip` 后解压丢了 index）。
+/// 判断「像哪个」要看包内到底有哪些标记文件，这是宿主层拿着 `PackArchive` 才看得见的事。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ProbeView {
+    /// 最像哪个格式（`None` = 三个都不像）。
+    pub looks_like: Option,
+    /// 该格式**缺**的标记文件（逐条，按判据顺序）。
+    pub missing: Vec,
+    /// 包里实际看到的标记（逐条）。
+    pub saw: Vec,
+    /// 一句兜底说明（也是 core 的原文：试过哪些格式）。
+    pub detail: String,
+}
+
+/// 导入侧的宿主状态（`AppState::import` 的全部内容）。
+#[derive(Debug, Clone, PartialEq, Default)]
+pub struct ImportState {
+    /// 正在跑的进度（`None` = 没在跑）。
+    pub progress: Option,
+    /// 用户点了取消（M113 r1）：**面板收回但后台还在跑**，所以这一位要留在界面上——
+    /// 否则用户会以为「没建成」，回头再导一次就撞「directory already exists」。
+    pub cancelled: bool,
+    /// 最近一次的结果（`None` = 还没导过）。
+    pub report: Option,
+    /// 探测失败的具名诊断（有它就让用户看清「像 X 缺 Y」，而不是一句「无法识别」）。
+    pub probe: Option,
+}
diff --git a/crates/presenter/src/dto/settings.rs b/crates/presenter/src/dto/settings.rs
new file mode 100644
index 0000000..428decc
--- /dev/null
+++ b/crates/presenter/src/dto/settings.rs
@@ -0,0 +1,220 @@
+//! 设置页 DTO：设置分组的通用行模型。
+//!
+//! 「行」是 UI 与 `core::setting` schema 之间的唯一形状：一行 = 一个键 + 一种控件 +
+//! 当前值。写回走 [`crate::dto::AppCommand::SetSetting`]，由 host 用 `SettingStore::set`
+//! 落盘（不自己拼 JSON、不另立配置文件，`AGENTS §6`）。
+
+use serde::{Deserialize, Serialize};
+
+/// 控件类型（决定设置页画什么）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum SettingControl {
+    /// 开关
+    Toggle,
+    /// 分段单选（`options` + `selected`）
+    Choice,
+    /// 单行文本（`value_text`）
+    Text,
+    /// 只读展示（当前路径/当前版本这类）
+    ReadOnly,
+    /// 动作按钮（`action` 给回调 id）
+    Action,
+}
+
+/// 一行设置。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct SettingRowView {
+    /// schema 键（`download.concurrency`）
+    pub key: String,
+    /// 行标题
+    pub label: String,
+    /// 说明/当前值附注
+    pub description: String,
+    /// 控件
+    pub control: SettingControl,
+    /// 开关值
+    pub flag: bool,
+    /// 单选序号
+    pub selected: i32,
+    /// 单选项文案
+    pub options: Vec,
+    /// 文本值
+    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/versions.rs b/crates/presenter/src/dto/versions.rs
new file mode 100644
index 0000000..844c6e6
--- /dev/null
+++ b/crates/presenter/src/dto/versions.rs
@@ -0,0 +1,62 @@
+//! 下载页 DTO：版本列表与分类（含远古版子类，D16/Q24-4）。
+
+use serde::{Deserialize, Serialize};
+
+/// 版本类型（远古版按 unlisted-versions 的分类拆开）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum VersionKind {
+    /// 正式版
+    Release,
+    /// 预览版（snapshot）
+    Snapshot,
+    /// 远古版（带子类）
+    Ancient(AncientKind),
+}
+
+/// 远古版子类。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum AncientKind {
+    /// classic（rd-*）
+    Classic,
+    /// old_alpha（a1.*）
+    OldAlpha,
+    /// old_beta（b1.*）
+    OldBeta,
+    /// 未列入官方清单的远古版汇总
+    Unlisted,
+}
+
+impl VersionKind {
+    /// 是否属于「远古版」——列表行要加警示徽标。
+    pub fn is_ancient(self) -> bool {
+        matches!(self, Self::Ancient(_))
+    }
+}
+
+/// 下载页版本行。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct VersionSummary {
+    /// 版本 id（如 `1.20.4` / `rd-132211`）
+    pub id: String,
+    /// 版本类型
+    pub kind: VersionKind,
+    /// 发布日期（ISO-8601 日期部分）
+    pub released: String,
+    /// 本地是否已安装（行尾显示「已装」）
+    pub installed: bool,
+}
+
+/// 下载页左侧分类（页内常驻侧栏的选中项）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum VersionCategory {
+    /// 正式版
+    Release,
+    /// 预览版
+    Snapshot,
+    /// 远古版某子类
+    Ancient(AncientKind),
+    /// 整合包（P1）
+    Modpack,
+    /// Mod（P1）
+    Mod,
+}
diff --git a/crates/presenter/src/host/accounts.rs b/crates/presenter/src/host/accounts.rs
new file mode 100644
index 0000000..8e3b613
--- /dev/null
+++ b/crates/presenter/src/host/accounts.rs
@@ -0,0 +1,382 @@
+//! 账户：三轨统一列表（只读公开字段）+ 离线新增 + 删除/切换 + 微软登录（两条流）。
+//!
+//! 凭据红线（D9）：`Credentials` / `MicrosoftSession` 只在本模块与 `launch.rs` 里出现，
+//! 出口一律是 [`AccountView`] / [`DeviceLoginView`]。
+//!
+//! 两条登录流：授权码（[`start_browser_login`]，GUI 默认：拉起系统浏览器 + 本地回调，
+//! `research/08` §3 方案 A）与设备码（[`start_login`]，无浏览器/CLI 场景）。除了「怎么拿到
+//! MS access_token」之外完全共用：同一个取消槽位、同一段账户入库、同一个刷新链。
+//!
+//! 取消语义：轮询/等回调都跑在 `core` 里、没有取消钩子，所以取消只把面板收回；线程收尾时
+//! 若发现「已取消」就不入库（避免用户点了取消却凭空多出一个账户）。
+
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+
+use unlucky_core::auth::account::Credentials;
+use unlucky_core::auth::microsoft::{now_ms, MicrosoftAuth, MicrosoftSession};
+use unlucky_core::auth::offline::offline_meta;
+use unlucky_core::auth::{AccountStore, AuthResult};
+use unlucky_core::download::blocking::block_on;
+
+use crate::dto::CoreEvent;
+use crate::dto::{
+    valid_offline_name, AccountKind, AccountNotice, AccountNoticeCode, AccountView,
+    DeviceLoginView, LoginFailure,
+};
+
+use super::env::HostEnv;
+use super::job::{spawn, HostTask, JobSender};
+use super::opener;
+
+/// 第三方轨（服务发现 / 密码登录 / 皮肤抓取）。
+pub mod authlib;
+
+mod refresh;
+
+mod failure;
+
+pub use failure::AccountFailure;
+
+use failure::classify;
+
+pub use authlib::{fetch_skin, spawn_probe, start_login as start_authlib_login};
+
+impl super::CoreHost {
+    /// 推一条账户页横幅（一次性操作结果；页面渲染后由用户关掉）。
+    pub(super) fn notice(&mut self, code: AccountNoticeCode, subject: &str, detail: &str) {
+        self.send(CoreEvent::AccountNoticeChanged(Some(AccountNotice::new(
+            code, subject, detail,
+        ))));
+    }
+
+    /// 账户写操作失败：**原文进日志**，页面只拿结构化码 + 主题名。
+    pub(super) fn notice_failure(&mut self, failure: AccountFailure, subject: &str) {
+        eprintln!(
+            "[accounts] 操作失败（{}，subject={subject}）：{}",
+            failure.code.code(),
+            failure.detail
+        );
+        self.notice(failure.code, subject, &failure.detail);
+    }
+}
+
+/// 账户列表（公开字段）。
+pub fn accounts(env: &HostEnv, active: Option<&str>) -> Vec {
+    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, Default)]
+pub struct LoginJob {
+    /// 用户点了取消（线程收尾时据此丢弃结果）
+    pub cancelled: Arc,
+}
+
+impl LoginJob {
+    /// 新建一个未取消的句柄。
+    pub fn new() -> Self {
+        Self {
+            cancelled: Arc::new(AtomicBool::new(false)),
+        }
+    }
+
+    /// 取消。
+    pub fn cancel(&self) {
+        self.cancelled.store(true, Ordering::SeqCst);
+    }
+
+    /// 是否已取消。
+    pub fn is_cancelled(&self) -> bool {
+        self.cancelled.load(Ordering::SeqCst)
+    }
+}
+
+/// 起一次设备码登录（后台线程；`present` 时刻发 Waiting 事件）。
+pub fn start_login(env: HostEnv, tx: JobSender, job: LoginJob) {
+    spawn("msa-login", move || {
+        let auth = match microsoft_auth(&env) {
+            Ok(auth) => auth,
+            Err(message) => return fail(&tx, LoginFailure::Other, message),
+        };
+        let tx_prompt = tx.clone();
+        let result = block_on(auth.device_code_login(|prompt| {
+            let _ = tx_prompt.send(HostTask::Login(Box::new(DeviceLoginView::waiting(
+                &prompt.user_code,
+                &prompt.verification_uri,
+                prompt.expires_in.as_secs(),
+                &format!("{}#{}", prompt.verification_uri, prompt.user_code),
+            ))));
+        }));
+        finish(&env, &tx, &job, result);
+    });
+}
+
+/// 起一次授权码登录（后台线程：绑本地端口 → 拉起系统默认浏览器 → 等回调 → 换链）。
+///
+/// 与设备码流共用同一个 [`LoginJob`] 取消槽位、同一段账户入库逻辑，所以两条流的
+/// 凭据/刷新语义完全一致（`core` 侧也共用 [`unlucky_core::auth::MicrosoftSession`]）。
+pub fn start_browser_login(env: HostEnv, tx: JobSender, job: LoginJob) {
+    spawn("msa-authcode", move || {
+        let auth = match microsoft_auth(&env) {
+            Ok(auth) => auth,
+            Err(message) => return fail(&tx, LoginFailure::Other, message),
+        };
+        let tx_prompt = tx.clone();
+        let result = block_on(auth.authcode_login(|prompt| {
+            // 浏览器拉不起来不是致命错误：面板里还有可复制的授权链接。
+            let opened = opener::open_url(&prompt.authorization_url);
+            let _ = tx_prompt.send(HostTask::Login(Box::new(DeviceLoginView::browser_waiting(
+                &prompt.authorization_url,
+                prompt.timeout.as_secs(),
+                opened.err().as_deref(),
+            ))));
+        }));
+        finish(&env, &tx, &job, result);
+    });
+}
+
+/// 生产入口的 `MicrosoftAuth`：client id 取环境/构建期，失败日志落 `<数据根>/logs/`。
+fn microsoft_auth(env: &HostEnv) -> Result {
+    MicrosoftAuth::from_env()
+        .map(|auth| {
+            auth.with_journal(Some(unlucky_core::auth::AuthJournal::in_logs_dir(
+                env.layout.logs(),
+            )))
+        })
+        .map_err(|error| error.to_string())
+}
+
+/// 失败收尾（带**原因码**）：原文进日志，页面据码出 i18n（复审 r1 P1-1）。
+fn fail(tx: &JobSender, failure: LoginFailure, detail: impl Into) {
+    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)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use unlucky_core::auth::AuthError;
+
+    use super::failure::mentions_whitelist;
+
+    #[test]
+    fn time_display_matches_known_timestamps() {
+        assert_eq!(display_ms(0), "");
+        // 1_769_000_000_000 ms = 2026-01-21T12:53:20Z（取整到分钟）
+        assert_eq!(display_ms(1_769_000_000_000), "2026-01-21 12:53");
+    }
+
+    #[test]
+    fn offline_add_list_remove_round_trips() {
+        let dir = std::env::temp_dir().join(format!("ull-host-accounts-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        let env = HostEnv::at_root(&dir);
+        std::fs::create_dir_all(env.layout.auth_data()).expect("auth 目录");
+
+        let name = add_offline(&env, "Steve").expect("加账户");
+        assert_eq!(name, "Steve");
+        let list = accounts(&env, None);
+        assert_eq!(list.len(), 1);
+        assert_eq!(list[0].kind, AccountKind::Offline);
+        assert!(!list[0].active);
+
+        let active = accounts(&env, Some(list[0].id.as_str()));
+        assert!(active[0].active);
+
+        let removed = remove(&env, "Steve").expect("删账户");
+        assert_eq!(removed, "Steve");
+        assert!(accounts(&env, None).is_empty());
+        assert!(add_offline(&env, "  ").is_err());
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    #[test]
+    fn failure_codes_are_classified_from_variants_not_chinese_text() {
+        assert_eq!(
+            classify(&AuthError::Network {
+                url: "https://x".to_string(),
+                detail: "dns".to_string()
+            }),
+            LoginFailure::Unreachable
+        );
+        assert_eq!(
+            classify(&AuthError::Denied {
+                code: "AADSTS7000218".to_string(),
+                description: "request body must contain client_assertion".to_string(),
+            }),
+            LoginFailure::NotWhitelisted
+        );
+        assert_eq!(
+            classify(&AuthError::Denied {
+                code: "invalid_grant".to_string(),
+                description: "bad".to_string(),
+            }),
+            LoginFailure::Denied
+        );
+        assert_eq!(classify(&AuthError::Canceled), LoginFailure::Other);
+        assert!(mentions_whitelist("AADSTS7000218"));
+        assert!(!mentions_whitelist("invalid_grant"));
+    }
+
+    #[test]
+    fn offline_name_rule_matches_the_ui_contract() {
+        assert!(valid_offline_name("Steve"));
+        assert!(valid_offline_name("a_1"));
+        assert!(!valid_offline_name("ab"), "太短");
+        assert!(!valid_offline_name("中文名字"), "非 ascii");
+        assert!(!valid_offline_name("has space"));
+        assert!(!valid_offline_name("x"));
+    }
+
+    #[test]
+    fn a_bad_offline_name_is_classified_not_stringified() {
+        let dir =
+            std::env::temp_dir().join(format!("ull-host-accounts-name-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        let env = HostEnv::at_root(&dir);
+        std::fs::create_dir_all(env.layout.auth_data()).expect("auth 目录");
+        let failure = add_offline(&env, "ab").expect_err("太短要报错");
+        assert_eq!(failure.code, AccountNoticeCode::OfflineNameInvalid);
+        assert!(!failure.detail.is_empty());
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    #[test]
+    fn login_job_cancel_flag_is_shared() {
+        let job = LoginJob::new();
+        let clone = job.clone();
+        assert!(!clone.is_cancelled());
+        job.cancel();
+        assert!(clone.is_cancelled());
+    }
+}
diff --git a/crates/presenter/src/host/accounts/authlib.rs b/crates/presenter/src/host/accounts/authlib.rs
new file mode 100644
index 0000000..6f708b4
--- /dev/null
+++ b/crates/presenter/src/host/accounts/authlib.rs
@@ -0,0 +1,337 @@
+//! 第三方轨（authlib-injector）：服务发现校验、密码登录、皮肤原图抓取。
+//!
+//! 全部跑在后台线程里（网络），出口只有 [`AuthlibLoginView`] / [`SkinImage`]——
+//! 密码与 accessToken 在调用栈里就地丢弃，永不进 DTO 回程（M114 凭据红线）。
+//!
+//! ## 三条流的坐标
+//!
+//! | 动作 | 端点 | 产出 |
+//! |---|---|---|
+//! | 服务发现（「校验」按钮） | `GET {apiRoot}` | 服务器名 / skinDomains（`meta` 缺失即判「不是认证服务器」） |
+//! | 登录 | `POST {apiRoot}authserver/authenticate` | `AuthlibSession`（入库，不外传） |
+//! | 皮肤 | `GET {apiRoot}sessionserver/session/minecraft/profile/{uuid}` → textures → 皮肤 URL | 皮肤 PNG 原图 |
+//!
+//! `core::download::http::build_client` 是唯一的 HTTP 基座（复用下载器的客户端配置），
+//! 所以本 crate **不新增任何依赖**（`presenter-no-ui` 与依赖最小化同时成立）。
+
+use unlucky_core::auth::account::{AccountKind as CoreAccountKind, AccountMeta, Credentials};
+use unlucky_core::auth::authlib::{
+    normalize_api_root, AuthlibAuth, AuthlibServerMeta, AuthlibSession,
+};
+use unlucky_core::auth::microsoft::now_ms;
+use unlucky_core::auth::{AccountStore, Secret};
+use unlucky_core::download::blocking::block_on;
+
+use crate::dto::{AuthlibLoginView, AuthlibRequest, LoginFailure, SkinImage};
+
+mod util;
+
+pub use util::scrub_known;
+
+use util::{base64_decode, client_token, get_bytes, get_text};
+
+use super::super::env::HostEnv;
+use super::super::job::{spawn, HostTask, JobSender};
+use super::LoginJob;
+
+/// 校验认证服务器地址（「校验」按钮的后端）。
+///
+/// # Errors
+///
+/// 地址不合法、网络不可达、HTTP 非 2xx、响应不是 authlib-injector 的服务发现 JSON 时，
+/// 返回**具名**的用户可读文案（这是任务要求的「失败态 + 具名错误」）。
+pub fn probe_authlib(env: &HostEnv, input: &str) -> Result<(String, AuthlibServerMeta), Failure> {
+    let api_root = normalize_api_root(input)
+        .map_err(|error| Failure::new(LoginFailure::Other, error.to_string()))?;
+    let (status, text) =
+        get_text(env, &api_root).map_err(|error| Failure::new(LoginFailure::Unreachable, error))?;
+    if !(200..300).contains(&status) {
+        return Err(Failure::new(
+            LoginFailure::NotAuthlibServer,
+            format!("服务器返回 HTTP {status}（{api_root} 不像可用的 authlib 认证服务器）"),
+        ));
+    }
+    let value: serde_json::Value = serde_json::from_str(&text).map_err(|_| {
+        Failure::new(
+            LoginFailure::NotAuthlibServer,
+            format!("响应不是 JSON：{api_root} —— 可能填成了网页地址，而不是 API 根（通常以 /api/yggdrasil/ 结尾）"),
+        )
+    })?;
+    if value.get("meta").is_none() && value.get("skinDomains").is_none() {
+        return Err(Failure::new(
+            LoginFailure::NotAuthlibServer,
+            "响应里没有 meta / skinDomains：这看起来不是 authlib-injector 服务器",
+        ));
+    }
+    let meta = AuthlibServerMeta::from_value(&value);
+    Ok((api_root, meta))
+}
+
+/// 第三方轨的失败：**原因码 + 原文**（原文进日志，页面据码出 i18n）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Failure {
+    /// 原因码
+    pub code: LoginFailure,
+    /// 原始诊断（已脱敏）
+    pub detail: String,
+}
+
+impl Failure {
+    fn new(code: LoginFailure, detail: impl Into) -> 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/refresh.rs b/crates/presenter/src/host/accounts/refresh.rs
new file mode 100644
index 0000000..cb805d6
--- /dev/null
+++ b/crates/presenter/src/host/accounts/refresh.rs
@@ -0,0 +1,66 @@
+//! 账户列表的刷新与皮肤抓取（`impl CoreHost` 的这一段，从 `host/mod.rs` 拆出来守 400 行）。
+//!
+//! 为什么在这里：`host/mod.rs` 在 M109/M113 之后已经贴着 400 行硬线，而这三段是**账户专属**
+//! 的编排（读账户库 → 盖皮肤 → 起抓取线程）。放回 `host/accounts.rs` 也不行——那个文件同样
+//! 380 行。归属仍是 accounts（`mod accounts { mod refresh; }`），只是按功能再分一层。
+
+use crate::dto::{AccountKind, CoreEvent};
+
+use super::super::{accounts, job, CoreHost, HostTask};
+
+impl CoreHost {
+    pub(in crate::host) fn refresh_accounts(&mut self) {
+        self.accounts = accounts::accounts(&self.env, self.active_account.as_deref());
+        if self.active_account.is_none() {
+            // 默认选中第一个账户（没有账户时保持 None = 离线占位）
+            self.active_account = self.accounts.first().map(|account| account.id.clone());
+            self.accounts = accounts::accounts(&self.env, self.active_account.as_deref());
+        }
+        self.attach_skins();
+        self.request_skins();
+        self.send(CoreEvent::AccountsChanged(self.accounts.clone()));
+    }
+
+    /// 把已抓到的皮肤盖到账户视图上。
+    ///
+    /// 只盖第三方轨：离线档案没有皮肤，微软轨不做真头像（M114 口径）——
+    /// 「没有皮肤就画首字母块」，绝不给假皮肤/白块。
+    pub(in crate::host) fn attach_skins(&mut self) {
+        for account in &mut self.accounts {
+            if account.kind != AccountKind::Authlib {
+                account.skin = None;
+                continue;
+            }
+            if let Some(skin) = self.skins.get(&account.id) {
+                account.skin = skin.clone();
+            }
+        }
+    }
+
+    /// 给还没抓过皮肤的第三方轨账户起后台抓取（每个账户只抓一次）。
+    ///
+    /// 抓不到就记 `None`：错误在面板上不显示（皮肤是装饰，不是业务失败），但也不会重试刷屏。
+    fn request_skins(&mut self) {
+        let mut pending = Vec::new();
+        for account in &self.accounts {
+            if account.kind != AccountKind::Authlib || account.server_url.trim().is_empty() {
+                continue;
+            }
+            if self.skin_requested.insert(account.id.clone()) {
+                pending.push((
+                    account.id.clone(),
+                    account.server_url.clone(),
+                    account.profile_id.clone(),
+                ));
+            }
+        }
+        for (id, server, profile) in pending {
+            let tx = self.tx.clone();
+            let env = self.env.clone();
+            job::spawn("account-skin", move || {
+                let skin = accounts::fetch_skin(&env, &server, &profile).ok();
+                let _ = tx.send(HostTask::Avatar { id, skin });
+            });
+        }
+    }
+}
diff --git a/crates/presenter/src/host/addon.rs b/crates/presenter/src/host/addon.rs
new file mode 100644
index 0000000..37e3b58
--- /dev/null
+++ b/crates/presenter/src/host/addon.rs
@@ -0,0 +1,106 @@
+//! 内容库的宿主实现（M109 `CONTENTDL`）：**检索** + **装进指定实例**。
+//!
+//! ## 为什么这些代码在 presenter 而不是 core（临时落点，必须写清）
+//!
+//! `crates/core` 的 `addon` 模块今天只有两件事：加载器安装（`addon::loader`）与整合包**格式**
+//! 解析（`addon::pack`，M110）。它**没有** CurseForge / Modrinth 的 API 客户端，也没有
+//! 「远程整合包一键装进实例」的管线（M111/M112 才做）。而任务书的硬约束是「UI 层不许自己发
+//! HTTP，新增能力一律经 presenter 的 host 转发」——所以本轮把客户端放在这里。
+//!
+//! **长期应下沉到 `core::addon`**（已报 finding）：那时本模块只剩「DTO ↔ 领域类型」的翻译，
+//! 与 `host/versions.rs` 现在的角色一样。
+//!
+//! ## 三条纪律
+//!
+//! | 纪律 | 落点 |
+//! |---|---|
+//! | 网络只在后台线程 | [`spawn_search`] / [`spawn_install`] 走 `job::spawn`，UI 线程只收事件 |
+//! | Modrinth 走 core 的下载引擎 | `addon/http.rs` 的 `download_bytes` 路径带**信号量限流 + 源健康度 + 指数退避**，不另写重试循环 |
+//! | 密钥不进仓库 / 日志 | CF 的 `X-API-KEY` 只从 `ULL_CF_API_KEY` 读，日志只打 `set`/`unset`，DTO 里只有一个 `bool` |
+//!
+//! ## 模块
+//!
+//! | 文件 | 职责 |
+//! |---|---|
+//! | [`sources`] | 两个站点的 JSON 方言 → [`crate::dto::ContentHit`] |
+//! | `http` | 取文本：无 header 走引擎、带 header 走 client + 退避、百分号编码 |
+//! | `install` | 一键装入：解析文件 → 下载到实例目录 → 进度回流 |
+//!
+//! ## 整合包与 CF 的边界（都写进报告）
+//!
+//! - 整合包**不做**「一键装入」：`ContentKind::Modpack.dir()` 是 `None`，UI 侧按钮禁用带原因，
+//!   host 侧再挡一次（就算绕过 UI 发指令也只回一条 `Failed`）。真流程是 M111 的导入管线。
+//! - CurseForge 本轮只做**检索**（需要用户配 `ULL_CF_API_KEY`），文件解析未接通。
+
+mod http;
+mod install;
+// M113: import/export —— 整合包导入/导出（拆成子目录：父文件只留既有内容 + mod）
+mod pack;
+mod sources;
+
+pub(super) use pack::{cancel_pack, pack_epoch};
+
+#[cfg(test)]
+mod tests;
+
+use std::sync::atomic::AtomicBool;
+use std::sync::Arc;
+
+use crate::dto::{ContentQuery, ContentResults};
+
+use super::env::HostEnv;
+use super::job::{spawn, HostTask, JobSender};
+
+/// 日志里只出现这两种状态，**永远不打密钥本身**。
+const KEY_UNSET: &str = "ULL_CF_API_KEY unset（CurseForge 源不可用）";
+const KEY_SET: &str = "ULL_CF_API_KEY set（CurseForge 源可用）";
+
+/// CurseForge 的密钥（环境变量；空串 / 空白按「没配」处理）。
+///
+/// 为什么不放设置项：core 的 `setting` schema 不在本 mission 的 scope（已登记 finding）。
+/// 环境变量这条路至少满足「不进仓库、不进日志」两条硬要求。
+fn curseforge_key() -> Option {
+    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)));
+    });
+}
+
+/// 后台「装进指定实例」。
+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/http.rs b/crates/presenter/src/host/addon/http.rs
new file mode 100644
index 0000000..07d73ec
--- /dev/null
+++ b/crates/presenter/src/host/addon/http.rs
@@ -0,0 +1,123 @@
+//! HTTP 取文本（内容库唯一的网络出口）。
+//!
+//! ## 两条路径，为什么不是一条
+//!
+//! | 请求 | 走哪 | 拿到什么 |
+//! |---|---|---|
+//! | 无自定义 header（Modrinth 的全部请求） | [`DownloadEngine::download_bytes`] | **信号量限流 + 源健康度 + 指数退避 + 分类错误**，全是 core 现成的 |
+//! | 带 header（只有 CurseForge 的 `X-API-KEY`） | `engine.client()` 直发 | 引擎的请求体没有 header 字段，只能自己发；代价是这条路径自己带一个 429/5xx 退避 |
+//!
+//! ## 密钥纪律
+//!
+//! 带 header 的那条路径**只把 header 值喂给请求**：不进日志、不进错误串。错误串里只有 URL
+//! （CF 的 URL 不含密钥）与状态码。
+
+use std::time::Duration;
+
+use unlucky_core::download::blocking::block_on;
+use unlucky_core::download::{DownloadRequest, ResourceKind};
+
+use super::super::env::HostEnv;
+
+/// 站点要求的 User-Agent（Modrinth 明文要求带联系方式，否则限流）。
+pub(super) const USER_AGENT: &str =
+    "Unlucky-Launcher/0.1 (+https://github.com/AskaEth/Unlucky-Launcher)";
+
+/// 最多重试次数（含首次）。
+const ATTEMPTS: u32 = 3;
+
+/// 取一段文本（JSON 原文）。
+pub(super) fn get(env: &HostEnv, url: &str, headers: &[(&str, &str)]) -> Result {
+    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);
+    let owned: Vec<(String, String)> = headers
+        .iter()
+        .map(|(name, value)| ((*name).to_string(), (*value).to_string()))
+        .collect();
+
+    for attempt in 0..ATTEMPTS {
+        let result = block_on(async {
+            let mut builder = engine.client().get(url).header("User-Agent", USER_AGENT);
+            for (name, value) in &owned {
+                builder = builder.header(name.as_str(), value.as_str());
+            }
+            let response = builder.send().await.map_err(|error| error.to_string())?;
+            let status = response.status();
+            if status.is_success() {
+                return response.text().await.map_err(|error| error.to_string());
+            }
+            let retry = response
+                .headers()
+                .get("retry-after")
+                .and_then(|value| value.to_str().ok())
+                .and_then(|value| value.parse::().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
+}
diff --git a/crates/presenter/src/host/addon/install.rs b/crates/presenter/src/host/addon/install.rs
new file mode 100644
index 0000000..be4d5db
--- /dev/null
+++ b/crates/presenter/src/host/addon/install.rs
@@ -0,0 +1,252 @@
+//! 「一键装入指定实例」（M109）。
+//!
+//! ## 它到底做了什么（诚实版）
+//!
+//! | 内容类型 | 做什么 | 状态 |
+//! |---|---|---|
+//! | Mod / 资源包 / 光影 | 解析「该项目下匹配目标实例（版本 + 加载器）的那个文件」→ core 下载引擎下载到实例运行目录的 `mods/` `resourcepacks/` `shaderpacks/` → 进度经 `InstallProgressView` 回流（**复用下载页那块面板**） | 已接 |
+//! | 整合包 | 一律 `Failed` + 一句原因 | **未做**：core 没有「远程整合包装进实例」的管线（M111） |
+//! | CurseForge 文件解析 | 一律 `Failed` + 一句原因 | **未做**：需要带 key 的文件端点，本轮只做了 CF 的**检索** |
+//!
+//! ## 为什么进度只有阶段级，没有字节条
+//!
+//! 字节级进度要走 `ProgressEmitter`（core 的 tokio 广播），而 presenter 的依赖表里没有
+//! `tokio` / `futures-util`（`Cargo.toml` 不在本 mission 的 scope），拿不到接收端的 `recv()`。
+//! 所以这里给的是**阶段 + 文件名**（`Planning` → `Downloading` → `Done`/`Failed`），
+//! 面板在「进度未知」时本来就只画一行说明、不画条（`download/install.rs` 的既定口径）。
+//! 已登记为后续项：presenter 补 `futures-util` 之后换成字节级。
+
+use std::path::PathBuf;
+use std::sync::atomic::{AtomicBool, Ordering};
+
+use unlucky_core::download::blocking::block_on;
+use unlucky_core::download::{DownloadRequest, ResourceKind};
+use unlucky_core::game::install::instance::read_instance_config;
+use unlucky_core::game::isolation::derive_game_dir;
+
+use crate::dto::{
+    loader_facet, ContentInstallRequest, ContentSource, InstallProgressView, InstallStage,
+    InstanceSummary,
+};
+
+use super::super::env::HostEnv;
+use super::super::job::{HostTask, JobSender};
+use super::http::{encode, get};
+use super::sources::MODRINTH;
+
+/// 跑一次装入（同步；由 [`super::spawn_install`] 放进后台线程）。
+pub(super) fn install(
+    env: &HostEnv,
+    tx: &JobSender,
+    request: &ContentInstallRequest,
+    cancel: &AtomicBool,
+    epoch: u64,
+) {
+    let mut progress = InstallProgressView {
+        version: request.title.clone(),
+        instance: request.instance.clone(),
+        loader: request.loader.label().to_string(),
+        files_total: 1,
+        ..InstallProgressView::new()
+    };
+
+    // 整合包：core 没有这条管线（M111），**不**假装能装。UI 侧按钮本来就是禁用的，
+    // 这里再挡一次是为了「绕过 UI 直接发指令」也不会静默做半件事。
+    if request.kind.dir().is_none() {
+        fail(
+            tx,
+            progress,
+            "整合包安装尚未开放；内容库对整合包只做检索",
+            epoch,
+        );
+        return;
+    }
+
+    let _ = tx.send(HostTask::Install {
+        progress: Box::new(progress.clone()),
+        epoch,
+    });
+    match run(env, request, cancel, &mut progress, tx, epoch) {
+        Ok(done) => {
+            progress.stage = InstallStage::Done;
+            progress.files_done = 1;
+            progress.message = done;
+            let _ = tx.send(HostTask::InstallDone {
+                progress: Box::new(progress),
+                result: Ok(request.title.clone()),
+                epoch,
+            });
+        }
+        Err(reason) => {
+            progress.stage = if cancel.load(Ordering::SeqCst) {
+                InstallStage::Cancelled
+            } else {
+                InstallStage::Failed
+            };
+            let _ = tx.send(HostTask::InstallDone {
+                progress: Box::new(progress),
+                result: Err(reason),
+                epoch,
+            });
+        }
+    }
+}
+
+fn fail(tx: &JobSender, mut progress: InstallProgressView, reason: &str, epoch: u64) {
+    progress.stage = InstallStage::Failed;
+    progress.message = reason.to_string();
+    let _ = tx.send(HostTask::InstallDone {
+        progress: Box::new(progress),
+        result: Err(reason.to_string()),
+        epoch,
+    });
+}
+
+/// 真正干活的那一段，返回一句人读的落盘描述。
+fn run(
+    env: &HostEnv,
+    request: &ContentInstallRequest,
+    cancel: &AtomicBool,
+    progress: &mut InstallProgressView,
+    tx: &JobSender,
+    epoch: u64,
+) -> Result {
+    let instance = find_instance(env, &request.instance)?;
+    let game_dir = game_dir_of(env, &instance)?;
+    let dir = request
+        .kind
+        .dir()
+        .ok_or_else(|| "该内容类型不支持单文件装入".to_string())?;
+    let target_dir = game_dir.join(dir);
+    std::fs::create_dir_all(&target_dir)
+        .map_err(|error| format!("建目录 {} 失败：{error}", target_dir.display()))?;
+
+    let file = resolve_file(env, request)?;
+    if cancel.load(Ordering::SeqCst) {
+        return Err("已取消（下载开始前）".to_string());
+    }
+    progress.stage = InstallStage::Downloading;
+    progress.message = file.name.clone();
+    let _ = tx.send(HostTask::Install {
+        progress: Box::new(progress.clone()),
+        epoch,
+    });
+
+    let dest = target_dir.join(&file.name);
+    let mut download = DownloadRequest::new(ResourceKind::ModFile, file.url, dest.clone());
+    if let Some(sha1) = file.sha1.as_deref().filter(|hex| !hex.is_empty()) {
+        download = download.with_sha1(sha1);
+    }
+    block_on(super::super::engine::engine(env).download(download))
+        .map_err(|error| format!("下载失败：{error}"))?;
+    Ok(format!("{}（{}）", file.name, dest.display()))
+}
+
+fn find_instance(env: &HostEnv, id: &str) -> Result {
+    super::super::game::instances(env)
+        .into_iter()
+        .find(|instance| instance.id == id)
+        .ok_or_else(|| format!("找不到实例 {id}"))
+}
+
+/// 实例的运行目录（D20 覆盖链：实例 `isolation` > 全局 `instances.mode`）。
+fn game_dir_of(env: &HostEnv, instance: &InstanceSummary) -> Result {
+    let global = super::super::game::global_mode(env);
+    let config = read_instance_config(&env.layout, &instance.id)
+        .map_err(|error| format!("读实例设置失败：{error}"))?;
+    derive_game_dir(
+        &env.game,
+        &instance.version_id,
+        global,
+        config.as_ref(),
+        None,
+    )
+    .map(|derivation| derivation.game_dir)
+    .map_err(|error| format!("隔离目录派生失败：{error}"))
+}
+
+/// 要下载的那个文件。
+struct RemoteFile {
+    url: String,
+    name: String,
+    sha1: Option,
+}
+
+/// 解析「这个项目下最适合目标实例的那个文件」。
+fn resolve_file(env: &HostEnv, request: &ContentInstallRequest) -> Result {
+    match request.source {
+        ContentSource::Modrinth => modrinth_file(env, request),
+        ContentSource::Curseforge => Err(
+            "CurseForge 的文件解析未接通（要带 key 的文件端点；见报告「没验的部分」）".to_string(),
+        ),
+    }
+}
+
+fn modrinth_file(env: &HostEnv, request: &ContentInstallRequest) -> Result {
+    let mut url = format!(
+        "{MODRINTH}/project/{}/version?game_versions={}",
+        request.project,
+        encode(&format!("[\"{}\"]", request.game_version))
+    );
+    if let Some(facet) = loader_facet(request.loader) {
+        url.push_str(&format!("&loaders={}", encode(&format!("[\"{facet}\"]"))));
+    }
+    let body = get(env, &url, &[])?;
+    let json: serde_json::Value = serde_json::from_str(&body)
+        .map_err(|error| format!("Modrinth 版本列表不是合法 JSON：{error}"))?;
+    let versions = json
+        .as_array()
+        .ok_or_else(|| "Modrinth 版本列表不是数组".to_string())?;
+    let first = versions
+        .first()
+        .ok_or_else(|| "这个项目没有匹配目标实例（版本 / 加载器）的文件".to_string())?;
+    let files = first
+        .get("files")
+        .and_then(serde_json::Value::as_array)
+        .ok_or_else(|| "版本里没有 files".to_string())?;
+    // 显式选 `primary: true`（Modrinth 官方口径）：取第一个会拿到 sources jar 这类坑
+    let file = files
+        .iter()
+        .find(|file| {
+            file.get("primary")
+                .and_then(serde_json::Value::as_bool)
+                .unwrap_or(false)
+        })
+        .or_else(|| files.first())
+        .ok_or_else(|| "版本里没有可用文件".to_string())?;
+
+    let url = file
+        .get("url")
+        .and_then(serde_json::Value::as_str)
+        .ok_or_else(|| "文件没有 url".to_string())?;
+    let name = file
+        .get("filename")
+        .and_then(serde_json::Value::as_str)
+        .ok_or_else(|| "文件没有 filename".to_string())?;
+    let sha1 = file
+        .get("hashes")
+        .and_then(|hashes| hashes.get("sha1"))
+        .and_then(serde_json::Value::as_str)
+        .map(ToString::to_string);
+    Ok(RemoteFile {
+        url: url.to_string(),
+        name: safe_file_name(name),
+        sha1,
+    })
+}
+
+/// 只留文件名本身：站点给的名字可能带路径分隔符，落盘前必须砍掉
+/// （与 `core::addon::pack::path` 的穿越双检同一条纪律）。
+pub(super) fn safe_file_name(raw: &str) -> String {
+    let name = raw
+        .rsplit(['/', '\\'])
+        .next()
+        .unwrap_or(raw)
+        .trim()
+        .to_string();
+    if name.is_empty() || name == "." || name == ".." {
+        "download.bin".to_string()
+    } else {
+        name
+    }
+}
diff --git a/crates/presenter/src/host/addon/pack.rs b/crates/presenter/src/host/addon/pack.rs
new file mode 100644
index 0000000..3137a4b
--- /dev/null
+++ b/crates/presenter/src/host/addon/pack.rs
@@ -0,0 +1,290 @@
+//! 整合包**导入 / 导出**（M113 `PACKUI`）：把 M111/M112 的管线接到内容库页上。
+//!
+//! ## 这里只做「解析目标 + 翻译 + 转发」
+//!
+//! 真正的活全在 core：`addon::import::import_pack`（三种格式 → 实例目录）与
+//! `addon::export::{scan_instance, export_instance}`（实例目录 → `.mrpack` / CF 清单）。
+//! 本模块不重新判定任何东西——三态、逐项原因、三分类全部**逐字段照搬** core 的报告
+//! （[`convert`]），于是「UI 说的」与「管线干的」是同一份事实。
+//!
+//! ## 文件分工（守 400 行）
+//!
+//! | 文件 | 职责 |
+//! |---|---|
+//! | 本文件 | `CoreHost::pack` 落点 + 取消标记 + 三条 spawn 共用的目标解析 |
+//! | [`import`] | 后台导入（探测 → 目标目录 → 管线 → 报告） |
+//! | [`export`] | 后台预检（不写盘）与后台写盘 |
+//! | [`convert`] | core 报告 → DTO（逐字段照搬）+ 小工具 |
+//! | [`diagnose`] | 探测诊断：「看起来像 X，但缺 Y」 |
+//!
+//! ## 导出预检与写盘用同一套判据
+//!
+//! core 的 `export_instance` 没有 dry-run 入口（已报 finding）。预检用 `scan_instance` +
+//! 「离线目录 ⇒ 一律内联」这条事实拼出来：`RemoteCatalog` 目前只有 `OfflineCatalog`，
+//! 所以每个可扫文件都证明不了可被远程替代 ⇒ 内联；`SkippedLocal` 就是「无法导出」。
+//! `tests::preview_counts_match_the_written_report` 用真管线钉住这个等式。
+//!
+//! ## 取消是**界面级**的
+//!
+//! [`cancel_pack`] 置模块级标记 + `dispatch` 里的 `CancelInstall` 把代次 +1：
+//!
+//! 1. 面板立刻收回（不是等后台回一句话）；
+//! 2. 这一轮之后回来的事件因代次不符被 `handle` 丢掉；
+//! 3. **后台那次导入会继续跑到结束**——core 的 `ImportRequest` 没有取消令牌，进度回调也拿不到
+//!    控制流。所以「取消」的真实含义是「不再显示、结果作废」，不是「把它停手」。要真停必须给
+//!    core 加 cancel token（已登记 finding，报告里同样划出来）；
+//! 4. **提示语不能借用安装那条**（复审 r1 P1-2）：下载页的取消 toast 写着「实例未创建」，
+//!    而导入会把实例**登记上**。所以 `cancel_pack()` 回一个「刚才有没有导入在跑」，
+//!    `dispatch` 据此改发 [`crate::dto::PackEvent::Cancelled`]，界面上换成
+//!    「导入会在后台继续跑完 —— 本次结果作废」这句。
+
+mod convert;
+mod diagnose;
+mod export;
+mod import;
+
+#[cfg(test)]
+mod tests;
+
+use std::path::PathBuf;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex};
+
+use unlucky_core::addon::export::{read_instance_snapshot, InstanceSnapshot};
+use unlucky_core::addon::pack::PackFormat;
+use unlucky_core::game::install::instance::read_instance_config;
+use unlucky_core::game::isolation::derive_game_dir;
+
+use crate::dto::{
+    CoreEvent, ExportRequestView, ImportProgressView, InstanceId, PackCommand, PackEvent,
+    PackFormatView,
+};
+
+use super::super::env::HostEnv;
+use super::super::job::{HostTask, JobSender};
+
+/// pack 的**每 host** 状态：代次 + 在跑计数 + 本次运行的取消标记。
+///
+/// ## 为什么不是裸静态量（复审 r2 P3-6 要的那句回答）
+///
+/// 裸静态量是**跨 host 共享**的。生产路径只有一个 host 所以看不出来，但测试里两个 host 会互相
+/// 干扰 —— 本轮实测撞到过：`host/cancel_tests` 派一次 `CancelInstall` 就把我这条用例在飞的导入
+/// 事件按代次丢了。键取 `LauncherLayout::home()`（每个测试的临时根都不同），于是各自独立：
+///
+/// - **代次**：每个 host 一条，`handle` 只跟**自己这个 host** 的当前值比；
+/// - **在跑计数**：一张计数表（每个 host 一格），由 [`InFlight`] 的 `Drop` 维护；
+/// - **取消标记**：每个 host 一份 `Arc`，导入线程拿克隆，`cancel_pack` 置位。
+///
+/// 为什么不挪进 `CoreHost`：那要给 `host/mod.rs` 加字段（不在本 mission 的 scope）。这张表等价，
+/// 只是把「每 host 的字段」放在模块里；`host/mod.rs` 一旦进 scope，搬过去只是把这张表删掉。
+#[derive(Default, Clone, Copy)]
+struct HostPackState {
+    epoch: u64,
+    in_flight: usize,
+}
+
+static PACK_STATE: Mutex> = 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 的取消**
+/// （后台会跑完并登记实例，见模块文档），所以不能复用下载页那条「安装已取消、实例未创建」。
+pub(in crate::host) fn cancel_pack(env: &HostEnv) -> bool {
+    let key = host_key(env);
+    {
+        let table = PACK_CANCEL
+            .lock()
+            .unwrap_or_else(|poison| poison.into_inner());
+        if let Some((_, cancel)) = table.iter().find(|(name, _)| *name == key) {
+            cancel.store(true, Ordering::SeqCst);
+        }
+    }
+    bump_pack_epoch(env);
+    in_flight(env) > 0
+}
+
+/// 这个 host 新一次导入的取消标记（挂进表里供 [`cancel_pack`] 用）。
+fn fresh_cancel(env: &HostEnv) -> Arc {
+    let cancel = Arc::new(AtomicBool::new(false));
+    let key = host_key(env);
+    let mut table = PACK_CANCEL
+        .lock()
+        .unwrap_or_else(|poison| poison.into_inner());
+    match table.iter_mut().find(|(name, _)| *name == key) {
+        Some((_, slot)) => *slot = Arc::clone(&cancel),
+        None => table.push((key, Arc::clone(&cancel))),
+    }
+    cancel
+}
+
+/// `AppCommand::Pack` 的落点（M113）。
+impl super::super::CoreHost {
+    pub(crate) fn pack(&mut self, command: PackCommand) {
+        let epoch = pack_epoch(&self.env);
+        match command {
+            PackCommand::Import(request) => {
+                let cancel = fresh_cancel(&self.env);
+                // 句柄在**派发点**就计上，随线程一起结束（含早退与 panic）
+                let guard = InFlight::begin(&self.env);
+                // 先把面板点亮：用户点了就有反应，不等后台回第一条进度
+                let name = request
+                    .instance_name
+                    .clone()
+                    .or_else(|| request.instance.clone())
+                    .unwrap_or_default();
+                self.send(CoreEvent::Pack(Box::new(PackEvent::Progress(Some(
+                    Box::new(ImportProgressView::new(name)),
+                )))));
+                import::spawn_import(
+                    self.env.clone(),
+                    self.tx.clone(),
+                    *request,
+                    epoch,
+                    cancel,
+                    guard,
+                );
+            }
+            PackCommand::Export(request) => {
+                export::spawn_preview(self.env.clone(), self.tx.clone(), *request, epoch);
+            }
+            PackCommand::Confirm(request) => {
+                export::spawn_write(self.env.clone(), self.tx.clone(), *request, epoch);
+            }
+            PackCommand::Dismiss => {
+                // 只作废 pack 自己的代次：**不碰** `install_epoch`（那是下载页安装的命门）
+                cancel_pack(&self.env);
+                self.send(CoreEvent::Pack(Box::new(PackEvent::Cleared)));
+            }
+        }
+    }
+}
+
+/// 后台任务 → host 的一跳（三个 spawn 共用）。
+pub(super) fn send(tx: &JobSender, epoch: u64, event: PackEvent) {
+    let _ = tx.send(HostTask::Pack {
+        event: Box::new(event),
+        epoch,
+    });
+}
+
+/// 实例 → 运行目录（与 `addon/install.rs` 同一条派生：实例隔离档 > 全局档）。
+pub(super) fn instance_root(env: &HostEnv, id: &InstanceId) -> Result {
+    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..ec19cbf
--- /dev/null
+++ b/crates/presenter/src/host/addon/pack/convert.rs
@@ -0,0 +1,256 @@
+//! core 报告 → DTO（M113）：**逐字段照搬，不重算任何结论**。
+//!
+//! 这一层的唯一职责是翻译：三态、五阶段、四种处置、三种冲突成因、十一种导出原因，
+//! 全部一一对应。任何一个「顺手换算一下」都会让 UI 说的和管线干的不是一回事，
+//! 所以这里没有一处 re-derive（唯一例外是把 `&'static str` 的稳定码换成人读串）。
+//!
+//! 翻译用的是 core 的稳定 slug（`as_str()`）+ DTO 的 `from_slug()`，
+//! 于是「翻译表」本身就是一份可审计的清单：core 加了新变体，`from_slug` 返回 `None`
+//! 时这里会落到一个有名字的兜底，而不是悄悄画成别的意思。
+
+use std::path::{Path, PathBuf};
+
+use unlucky_core::addon::export::{ExportReport, FileClass, FileReason};
+use unlucky_core::addon::import::{
+    ConflictChoice, ConflictFile, ConflictReason, FileAction, ImportError, ImportProgress,
+    ImportReport, LoaderTarget, MissingReason,
+};
+
+use crate::dto::{
+    ConflictChoiceView, ConflictFileView, ConflictReasonView, ExportClassView, ExportDoneView,
+    ExportReasonView, FileActionView, ImportErrorView, ImportProgressView, ImportReportView,
+    ImportStageView, ImportStatusView, ImportedFileView, MissingFileView, MissingReasonView,
+    PackFormatView,
+};
+
+/// 一次导入结果 → DTO。
+pub(super) fn report_view(report: &ImportReport, target: &Path) -> ImportReportView {
+    ImportReportView {
+        status: ImportStatusView::from_slug(report.status.as_str())
+            .unwrap_or(ImportStatusView::Failed),
+        format: report.format.as_deref().and_then(PackFormatView::from_slug),
+        pack_name: report.pack_name.clone(),
+        pack_version: report.pack_version.clone(),
+        game_version: report.game_version.clone(),
+        loader: report.loader.as_ref().map(loader_label),
+        version_id: report.version_id.clone(),
+        target: target.to_path_buf(),
+        files: report
+            .files
+            .iter()
+            .map(|file| ImportedFileView {
+                path: file.path.clone(),
+                action: action_view(file.action),
+                bytes: file.bytes,
+            })
+            .collect(),
+        conflicts: report.conflicts.iter().map(conflict_view).collect(),
+        missing: report
+            .missing
+            .iter()
+            .map(|file| MissingFileView {
+                path: file.path.clone(),
+                display: file.display.clone(),
+                reason: missing_view(file.reason),
+                detail: file.detail.clone(),
+            })
+            .collect(),
+        rejected: report
+            .rejected_components
+            .iter()
+            .map(|component| match &component.version {
+                Some(version) => format!("{} {version}", component.uid),
+                None => component.uid.clone(),
+            })
+            .collect(),
+        warnings: report
+            .warnings
+            .iter()
+            .map(|issue| issue.message.clone())
+            .collect(),
+        error: report.error.as_ref().map(error_view),
+        registered: report
+            .registered
+            .as_ref()
+            .map(|registered| registered.name.clone()),
+        bytes_written: report.bytes_written,
+        rolled_back: report.rolled_back,
+    }
+}
+
+/// 一次导出结果 → DTO。
+pub(super) fn done_view(report: &ExportReport) -> ExportDoneView {
+    ExportDoneView {
+        path: report.path.clone(),
+        bytes: report.bytes,
+        remote: u32::try_from(report.remote_count()).unwrap_or(u32::MAX),
+        inline: u32::try_from(report.inline_count()).unwrap_or(u32::MAX),
+        skipped: u32::try_from(report.skipped_count()).unwrap_or(u32::MAX),
+    }
+}
+
+/// 一条导入进度 → DTO。
+pub(super) fn progress_view(progress: &ImportProgress, pack: &str) -> ImportProgressView {
+    ImportProgressView {
+        stage: ImportStageView::from_slug(progress.stage.as_str())
+            .unwrap_or(ImportStageView::Probe),
+        done: u32::try_from(progress.done).unwrap_or(u32::MAX),
+        total: u32::try_from(progress.total).unwrap_or(u32::MAX),
+        current: progress.current.clone(),
+        pack: pack.to_string(),
+    }
+}
+
+/// 致命失败 → DTO（稳定码原样带走，日志与 `--json` 用的是同一串）。
+fn error_view(error: &ImportError) -> ImportErrorView {
+    ImportErrorView {
+        code: error.kind().as_str().to_string(),
+        label: error.kind().label().to_string(),
+        message: error.message().to_string(),
+        hint: error.hint().map(str::to_string),
+    }
+}
+
+fn conflict_view(file: &ConflictFile) -> ConflictFileView {
+    ConflictFileView {
+        path: file.path.clone(),
+        reason: match file.reason {
+            ConflictReason::UserModified => ConflictReasonView::UserModified,
+            ConflictReason::UserDeleted => ConflictReasonView::UserDeleted,
+            ConflictReason::PreExisting => ConflictReasonView::PreExisting,
+        },
+        choice: match file.choice {
+            ConflictChoice::KeepUser => ConflictChoiceView::KeepUser,
+            ConflictChoice::Overwrite => ConflictChoiceView::Overwrite,
+        },
+        pack_sha1: file.pack_sha1.clone(),
+        base_sha1: file.base_sha1.clone(),
+        disk_sha1: file.disk_sha1.clone(),
+        pack_size: file.pack_size,
+    }
+}
+
+const fn action_view(action: FileAction) -> FileActionView {
+    match action {
+        FileAction::Installed => FileActionView::Installed,
+        FileAction::Replaced => FileActionView::Replaced,
+        FileAction::SkippedIdentical => FileActionView::SkippedIdentical,
+        FileAction::KeptUser => FileActionView::KeptUser,
+    }
+}
+
+const fn missing_view(reason: MissingReason) -> MissingReasonView {
+    match reason {
+        MissingReason::Offline => MissingReasonView::Offline,
+        MissingReason::NoSource => MissingReasonView::NoSource,
+        MissingReason::FetchFailed => MissingReasonView::FetchFailed,
+    }
+}
+
+pub(super) fn reason_view(reason: FileReason) -> ExportReasonView {
+    ExportReasonView::from_slug(reason.as_str()).unwrap_or(ExportReasonView::Unreadable)
+}
+
+pub(super) fn class_view(class: FileClass) -> ExportClassView {
+    match class {
+        FileClass::Remote => ExportClassView::Remote,
+        FileClass::Inline => ExportClassView::Inline,
+        FileClass::Skipped => ExportClassView::Skipped,
+    }
+}
+
+/// 加载器 → 人读串（`fabric-loader 0.15.11` / `vanilla 1.20.1`）。
+fn loader_label(target: &LoaderTarget) -> String {
+    format!("{} {}", target.kind.as_str(), target.loader_version)
+}
+
+/// 「命令跑起来了，但目标实例不可用」这类**host 侧**失败的报告。
+///
+/// 仍然走三态里的 `Failed`：界面只有一种失败形状，用户不用学第二套。
+/// `target` 是**目标实例目录**（不知道就给空路径），不是包路径（复审 r1 P2-9 顺手纠的 DTO 语义）。
+pub(super) fn failed_report(
+    target: PathBuf,
+    pack: &Path,
+    code: &str,
+    label: &str,
+    message: &str,
+) -> ImportReportView {
+    ImportReportView {
+        status: ImportStatusView::Failed,
+        format: None,
+        pack_name: Some(pack_stem(pack)),
+        pack_version: None,
+        game_version: None,
+        loader: None,
+        version_id: None,
+        target,
+        files: Vec::new(),
+        conflicts: Vec::new(),
+        missing: Vec::new(),
+        rejected: Vec::new(),
+        warnings: Vec::new(),
+        error: Some(ImportErrorView {
+            code: code.to_string(),
+            label: label.to_string(),
+            message: message.to_string(),
+            hint: None,
+        }),
+        registered: None,
+        bytes_written: 0,
+        rolled_back: true,
+    }
+}
+
+/// 包文件名（`Better MC.mrpack` → `Better MC`）。
+pub(super) fn pack_stem(pack: &Path) -> String {
+    pack.file_stem()
+        .map(|stem| stem.to_string_lossy().to_string())
+        .unwrap_or_else(|| "imported-pack".to_string())
+}
+
+/// **实例目录名**：ASCII 化 + 必要时补一段内容哈希。
+///
+/// 判据（复审 r2 P2-2 之后与注释对齐）：名字里**只含** ASCII 字母数字、空格、`-`、`_` 时
+/// 保持原样（空格折成 `-`，`Better MC` → `Better-MC`）；**一旦折过别的字符**（中文、`.`、
+/// 括号……）就补 `-`，用原名的哈希保住区分度 —— 否则「我的整合包」「另一个整合包」
+/// 都会得到 `pack`，第二个中文名导入直接撞「directory already exists」。
+pub(super) fn dir_name(name: &str) -> String {
+    let base = slug(name);
+    let faithful = !name.is_empty()
+        && name
+            .chars()
+            .all(|ch| ch.is_ascii_alphanumeric() || ch == '-' || ch == '_' || ch == ' ');
+    if faithful {
+        base
+    } else {
+        format!("{base}-{}", hash8(name))
+    }
+}
+
+/// FNV-1a 64 → 8 位十六进制（只要稳定、短、不需要密码学强度）。
+fn hash8(text: &str) -> String {
+    let mut hash: u64 = 0xcbf2_9ce4_8422_2325;
+    for byte in text.as_bytes() {
+        hash ^= u64::from(*byte);
+        hash = hash.wrapping_mul(0x0000_0100_0000_01b3);
+    }
+    format!("{:08x}", hash as u32)
+}
+
+/// 目录/文件名用的 slug（只留 ASCII 字母数字与 `-` / `_`，其余折成 `-`）。
+pub(super) fn slug(text: &str) -> String {
+    let mut out = String::new();
+    for ch in text.chars() {
+        if ch.is_ascii_alphanumeric() || ch == '-' || ch == '_' {
+            out.push(ch);
+        } else if !out.ends_with('-') {
+            out.push('-');
+        }
+    }
+    let trimmed = out.trim_matches('-').to_string();
+    if trimmed.is_empty() {
+        "pack".to_string()
+    } else {
+        trimmed
+    }
+}
diff --git a/crates/presenter/src/host/addon/pack/diagnose.rs b/crates/presenter/src/host/addon/pack/diagnose.rs
new file mode 100644
index 0000000..ca178cb
--- /dev/null
+++ b/crates/presenter/src/host/addon/pack/diagnose.rs
@@ -0,0 +1,104 @@
+//! 探测诊断（M113）：「这个包**看起来像** X，但**缺** Y」。
+//!
+//! ## 为什么由 host 判，不引 core 改动
+//!
+//! core 的 `PackRegistry::detect` 只回答「谁认领」，一个都不认领时只给一句
+//! `pack_unsupported` + 「试过哪些格式」。而用户手里那个包往往**差一点点**就是某个已知格式
+//! （CF 导出漏了 `manifest.json`、mrpack 被浏览器改名成 `.zip` 后解压丢了 index）。
+//! 判断「像哪个」要看包内到底有哪些标记文件，这是宿主层拿着 `PackArchive` 才看得见的事。
+//!
+//! ## 判据只有标记文件的有无（不看文件名）
+//!
+//! | 格式 | 标记 | 邻居（有它但没标记 ⇒ 「像它」） |
+//! |---|---|---|
+//! | CurseForge | `manifest.json` | `overrides/` · `mods/` |
+//! | Modrinth | `modrinth.index.json` | `overrides/` |
+//! | MultiMC / Prism | `mmc-pack.json` | `instance.cfg` · `.minecraft/` |
+//!
+//! `saw` 只留前 5 条有代表性的标记：长路径往界面里倒会把版面撑破（塔台复审提过）。
+//! 一个标记都没认出来时 `saw` 为空，由界面显示「nothing recognisable」而不是一行空白。
+
+use std::path::Path;
+
+use unlucky_core::addon::pack::{PackArchive, PackLimits, PackRegistry};
+
+use crate::dto::{PackFormatView, ProbeView};
+
+/// 诊断一个包（`None` = 有个格式认领它，正常走管线）。
+pub(super) fn of(pack: &Path) -> Option {
+    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..10f5c2c
--- /dev/null
+++ b/crates/presenter/src/host/addon/pack/import.rs
@@ -0,0 +1,176 @@
+//! 后台导入（M113）：探测 → 目标目录 → core 的 `import_pack` → 报告。
+//!
+//! 三条纪律：
+//!
+//! 1. **探测失败不空跑管线**：先做具名诊断（[`super::diagnose`]），失败就只回 `Probe` 事件；
+//! 2. **默认档永远是 `KeepUser`**：只有 `request.overwrite == true` 才换成 `Overwrite`；
+//! 3. **取消后不再打扰界面**：进度回调与最终报告都先看取消标记。
+
+use std::path::PathBuf;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+
+use unlucky_core::addon::import::{
+    import_pack, ConflictPolicy, DownloadEngineFetcher, ImportProgress, ImportProgressSink,
+    ImportRequest,
+};
+use unlucky_core::download::blocking::block_on;
+
+use crate::dto::{ImportRequestView, PackEvent};
+use unlucky_core::addon::import::ImportStatus;
+
+use super::super::super::env::HostEnv;
+use super::super::super::job::{spawn, JobSender};
+use super::convert;
+use super::send;
+
+/// 起一个后台导入线程。
+pub(super) fn spawn_import(
+    env: HostEnv,
+    tx: JobSender,
+    request: ImportRequestView,
+    epoch: u64,
+    cancel: Arc,
+    inflight: super::InFlight,
+) {
+    spawn("pack-import", move || {
+        // 句柄跟着这次运行走到**出口**：正常收尾、两条早退、panic 展开都会 drop ⇒ 计数减一。
+        // 以前是手工 `finished()` 放在 `block_on()` 之后，两条早退路径直接漏掉（复审 r2 P2-1）。
+        let _inflight = inflight;
+        run(&env, &tx, &request, epoch, cancel);
+    });
+}
+
+pub(super) fn run(
+    env: &HostEnv,
+    tx: &JobSender,
+    request: &ImportRequestView,
+    epoch: u64,
+    cancel: Arc,
+) {
+    // 探测先过一遍：失败就只给具名诊断（「看起来像 X，但缺 Y」），不空跑一遍管线
+    if let Some(probe) = super::diagnose::of(&request.pack) {
+        send(tx, epoch, PackEvent::Probe(Box::new(probe)));
+        return;
+    }
+    let (target, register) = match target_of(env, request) {
+        Ok(target) => target,
+        Err(reason) => {
+            send(
+                tx,
+                epoch,
+                PackEvent::Report(Box::new(convert::failed_report(
+                    // 目标目录不可用 ⇒ 如实给空路径（不把包路径冒充成实例目录）
+                    PathBuf::new(),
+                    &request.pack,
+                    "import_host",
+                    "Target instance is not usable",
+                    &reason,
+                ))),
+            );
+            return;
+        }
+    };
+
+    let pack_name = request
+        .instance_name
+        .clone()
+        .unwrap_or_else(|| convert::pack_stem(&request.pack));
+    let progress_tx = tx.clone();
+    let progress_name = pack_name.clone();
+    let cancel_flag = Arc::clone(&cancel);
+    let sink: ImportProgressSink = Arc::new(move |progress: &ImportProgress| {
+        if cancel_flag.load(Ordering::SeqCst) {
+            return;
+        }
+        send(
+            &progress_tx,
+            epoch,
+            PackEvent::Progress(Some(Box::new(convert::progress_view(
+                progress,
+                &progress_name,
+            )))),
+        );
+    });
+
+    let engine = super::super::super::engine::engine(env);
+    let fetcher = DownloadEngineFetcher::new(&engine);
+    let mut core_request = ImportRequest::new(&request.pack, &target)
+        .with_fetcher(&fetcher)
+        .with_progress(sink);
+    if request.overwrite {
+        core_request = core_request.with_conflict_policy(ConflictPolicy::Overwrite);
+    }
+    if register {
+        core_request = core_request.with_registration(&env.layout, Some(&pack_name));
+    }
+
+    let report = block_on(import_pack(&core_request));
+    if report.status == ImportStatus::Failed && register {
+        // 失败已回滚，但**目录是我们建的**、core 只清文件不清目录 ⇒ 不清掉的话
+        // 下一次重试会撞「directory already exists」（复审 r1 P2-9）。
+        remove_if_empty(&target);
+    }
+    if cancel.load(Ordering::SeqCst) {
+        // 取消之后不再打扰界面（面板已经收回，代次也已经作废）。
+        // 注意：后台这一步**已经跑完**（core 没有取消令牌），实例可能已被登记 ——
+        // 所以取消的提示语必须说「还在后台跑」，不能说「实例未创建」。
+        return;
+    }
+    send(
+        tx,
+        epoch,
+        PackEvent::Report(Box::new(convert::report_view(&report, &target))),
+    );
+}
+
+/// 目录里没有东西就删掉（失败回滚后的收尾；非空一律不动）。
+fn remove_if_empty(dir: &std::path::Path) {
+    let empty = std::fs::read_dir(dir)
+        .map(|mut entries| entries.next().is_none())
+        .unwrap_or(false);
+    if empty {
+        let _ = std::fs::remove_dir(dir);
+    }
+}
+
+/// 导入目标：`(目录, 是否登记新实例)`。
+///
+/// - 选了实例 ⇒ 它的运行目录，**不登记**（已经是一条实例记录）；
+/// - 没选实例 ⇒ `/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));
+            let target = env
+                .layout
+                .data()
+                .join("instances")
+                .join(convert::dir_name(&name));
+            if target.exists() {
+                // 空目录（多半是上一次失败的残留）**可以复用**，否则重试永远报「已存在」
+                let mut entries = std::fs::read_dir(&target)
+                    .map_err(|error| format!("read instance dir failed: {error}"))?;
+                if entries.next().is_some() {
+                    return Err(format!(
+                        "directory already exists and is not empty: {}",
+                        target.display()
+                    ));
+                }
+            } else {
+                std::fs::create_dir_all(&target)
+                    .map_err(|error| format!("create dir failed: {error}"))?;
+            }
+            Ok((target, true))
+        }
+    }
+}
diff --git a/crates/presenter/src/host/addon/pack/tests.rs b/crates/presenter/src/host/addon/pack/tests.rs
new file mode 100644
index 0000000..b9127fe
--- /dev/null
+++ b/crates/presenter/src/host/addon/pack/tests.rs
@@ -0,0 +1,389 @@
+//! M113 的证据（都跑真管线 / 真 host，不用假数据）：
+//!
+//! | 用例 | 钉住什么 |
+//! |---|---|
+//! | [`bad_packs_get_a_named_diagnosis`] | 坏包必须有具名失败，不是静默、不是 panic |
+//! | [`preview_counts_match_the_written_report`] | 预检的 N/M 与最终报告**逐项相等** |
+//! | [`a_real_pack_runs_through_the_pipeline_end_to_end`] | 正常包能走完管线并落盘 |
+//! | [`chinese_instance_names_get_distinct_directories`] | 中文实例名不会塌成同一个目录 |
+//! | [`a_failed_new_instance_directory_can_be_reused_for_retry`] | 失败残留的空目录不挡重试 |
+//! | [`pack_epoch_is_per_host_and_is_its_own_counter`] | 代次按 host 分开，不再跨 host 串扰 |
+//! | [`a_failed_import_releases_the_in_flight_flag_and_keeps_install_cancel_intact`] | 早退路径放回「在跑」计数，取消安装仍是安装的取消 |
+//!
+//! 夹具（临时目录、写文件、泵 host）在 [`harness`]。
+
+mod harness;
+
+use harness::{pack_events, pump, pump_until, temp_dir, write};
+
+use unlucky_core::addon::export::{
+    export_instance, scan_instance, ExportRequest, InstanceSnapshot, OfflineCatalog,
+    DEFAULT_CONTENT_ROOTS,
+};
+
+use crate::dto::{ExportClassView, ExportRequestView, PackFormatView};
+
+#[test]
+fn bad_packs_get_a_named_diagnosis() {
+    let dir = temp_dir("badpack");
+
+    // ① 把文本文件改名成 .mrpack：连 zip 都不是
+    let fake = dir.join("fake.mrpack");
+    write(&fake, b"this is not a zip");
+    let probe = super::diagnose::of(&fake).expect("打不开的包必须有诊断");
+    assert!(
+        !probe.detail.is_empty(),
+        "诊断要给一句具体原因（不是空字符串）"
+    );
+    assert!(
+        probe.detail.to_lowercase().contains("archive") || probe.detail.contains("zip"),
+        "诊断要说清是哪一步失败：{}",
+        probe.detail
+    );
+
+    // ② 目录形态：有 overrides/、没有 manifest.json ⇒ 「像 CF，缺 manifest.json」
+    let dir_pack = dir.join("half");
+    write(&dir_pack.join("overrides").join("options.txt"), b"fov=90\n");
+    if let Some(probe) = super::diagnose::of(&dir_pack) {
+        assert!(
+            !probe.saw.is_empty(),
+            "看到了 overrides/ 就该说出来（saw 不能为空）"
+        );
+        if probe.looks_like.is_some() {
+            assert!(
+                !probe.missing.is_empty(),
+                "说「像某个格式」就必须说出缺哪个标记文件"
+            );
+        }
+    }
+}
+
+#[test]
+fn preview_counts_match_the_written_report() {
+    let dir = temp_dir("export-eq");
+    let root = dir.join("instance");
+    write(&root.join("mods").join("sodium.jar"), &[0x11; 4096]);
+    write(&root.join("mods").join("lithium.jar"), &[0x22; 2048]);
+    write(&root.join("mods").join("old.jar.disabled"), &[0x33; 512]);
+    write(&root.join("config").join("options.txt"), b"fov=90\n");
+    // 白名单之外的目录不该被扫（否则「将内联 N」会虚高）
+    write(&root.join("logs").join("latest.log"), b"noise\n");
+
+    let request = ExportRequestView {
+        instance: "survival".to_string(),
+        format: PackFormatView::Modrinth,
+        name: "Survival".to_string(),
+        version: "1.0.0".to_string(),
+        target: Some(dir.join("out.mrpack")),
+    };
+    let env_root = dir.join("data");
+    std::fs::create_dir_all(&env_root).expect("env");
+    let env = crate::host::HostEnv::at_root(&env_root);
+
+    // 预检（不写盘）
+    let preview = super::export::preview_of(&root, &env, &request);
+
+    // 真写盘：用同一套判据（离线目录 + 默认内容目录 + 直接给的快照）
+    let snapshot = InstanceSnapshot {
+        game_version: "1.20.1".to_string(),
+        loaders: Vec::new(),
+    };
+    let target = dir.join("out.mrpack");
+    let core_request = ExportRequest::new(
+        &root,
+        &target,
+        &unlucky_core::addon::pack::modrinth::MODRINTH,
+    )
+    .with_name("Survival")
+    .with_version("1.0.0")
+    .with_catalog(&OfflineCatalog)
+    .with_snapshot(&snapshot);
+    let report = export_instance(&core_request).expect("导出应当成功");
+
+    // 三个计数逐项相等（塔台要求：不是「大致对」）
+    assert_eq!(
+        preview.inline_count(),
+        report.inline_count(),
+        "内联条数不一致：预检 {} vs 报告 {}",
+        preview.inline_count(),
+        report.inline_count()
+    );
+    assert_eq!(
+        preview.skipped_count(),
+        report.skipped_count(),
+        "无法导出条数不一致"
+    );
+    assert_eq!(
+        preview.remote_count(),
+        report.remote_count(),
+        "远程引用条数不一致"
+    );
+
+    // 逐条：同一个路径在两边必须是同一个类
+    for file in &preview.files {
+        let written = report
+            .files
+            .iter()
+            .find(|candidate| candidate.path == file.path)
+            .unwrap_or_else(|| panic!("预检多出一条：{}", file.path));
+        let expected = match file.class {
+            ExportClassView::Remote => unlucky_core::addon::export::FileClass::Remote,
+            ExportClassView::Inline => unlucky_core::addon::export::FileClass::Inline,
+            ExportClassView::Skipped => unlucky_core::addon::export::FileClass::Skipped,
+        };
+        assert_eq!(written.class, expected, "{} 的归类不一致", file.path);
+    }
+
+    // 白名单外的 logs/ 不许进包（防「扫太宽」把预检数字弄虚）
+    assert!(
+        !report
+            .files
+            .iter()
+            .any(|file| file.path.starts_with("logs/")),
+        "logs/ 不该被扫进整合包"
+    );
+
+    // 同时钉一条：`scan_instance` 的口径就是预览用的那一套
+    let roots: Vec = DEFAULT_CONTENT_ROOTS
+        .iter()
+        .map(|entry| (*entry).to_string())
+        .collect();
+    let (files, skipped) = scan_instance(&root, &roots);
+    assert_eq!(files.len(), preview.inline_count());
+    assert_eq!(skipped.len(), preview.skipped_count());
+
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+#[test]
+fn a_real_pack_runs_through_the_pipeline_end_to_end() {
+    // 真管线端到端：造一个 MultiMC 实例目录当「包」（目录形态不需要 zip 写入器），
+    // 走 `import::run` 的**真**路径，看事件流里有没有「进度 + 结果」、文件有没有落地。
+    let dir = temp_dir("import-e2e");
+    let source = dir.join("Better MC");
+    write(
+        &source.join("mmc-pack.json"),
+        br#"{"formatVersion": 1, "components": [
+            {"uid": "net.minecraft", "version": "1.20.1"},
+            {"uid": "net.fabricmc.fabric-loader", "version": "0.15.11"}]}"#,
+    );
+    write(&source.join(".minecraft/mods/sodium.jar"), &[0x11; 1024]);
+    write(&source.join(".minecraft/config/options.txt"), b"fov=90\n");
+
+    let data = dir.join("data");
+    std::fs::create_dir_all(&data).expect("data root");
+    let env = crate::host::HostEnv::at_root(&data);
+
+    let (tx, rx) = crate::host::job::channel();
+    let request = crate::dto::ImportRequestView {
+        pack: source,
+        instance: None,
+        instance_name: Some("Imported Pack".to_string()),
+        overwrite: false,
+    };
+    super::import::run(
+        &env,
+        &tx,
+        &request,
+        7,
+        std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false)),
+    );
+    drop(tx);
+
+    let mut progress = 0usize;
+    let mut report = None;
+    for task in rx.iter() {
+        match task {
+            crate::host::job::HostTask::Pack { event, epoch } => {
+                assert_eq!(epoch, 7, "代次必须原样带回（取消判定靠它）");
+                match *event {
+                    crate::dto::PackEvent::Progress(Some(_)) => progress += 1,
+                    crate::dto::PackEvent::Report(view) => report = Some(*view),
+                    other => panic!("意料之外的事件：{other:?}"),
+                }
+            }
+            other => panic!("意料之外的任务：{other:?}"),
+        }
+    }
+
+    assert!(progress > 0, "至少要有一条进度事件");
+    let report = report.expect("必须有结果事件");
+    assert_ne!(
+        report.status,
+        crate::dto::ImportStatusView::Failed,
+        "正常包不该失败：{:?}",
+        report.error
+    );
+    assert_eq!(
+        report.format,
+        Some(crate::dto::PackFormatView::Multimc),
+        "应当认成 MultiMC 格式"
+    );
+    assert!(
+        report.written() > 0,
+        "报告里要至少有写盘的文件：{:?}",
+        report.files
+    );
+    // 落盘位置以**报告里的 target** 为准（那是 host 真算出来的目录，界面显示的也是它）
+    let landed = &report.target;
+    assert!(
+        landed.join("mods/sodium.jar").is_file(),
+        "文件没有落到实例目录：{}",
+        landed.display()
+    );
+
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+#[test]
+fn chinese_instance_names_get_distinct_directories() {
+    // 复审 r1 P2-8：slug() 只留 ASCII，中文名会全塌成 `pack`，第二个就撞目录
+    let first = super::convert::dir_name("我的整合包");
+    let second = super::convert::dir_name("另一个整合包");
+    assert_ne!(first, second, "两个不同的中文名必须得到不同目录");
+    assert_eq!(
+        first,
+        super::convert::dir_name("我的整合包"),
+        "同一个名字要稳定（不然重试会漂到新目录）"
+    );
+    assert!(first.starts_with("pack-"), "退化时要留可读前缀：{first}");
+
+    // 判据与注释对齐（复审 r2 P2-2）：只含 ASCII 字母数字/空格/`-`/`_` ⇒ 保持原样
+    assert_eq!(super::convert::dir_name("Better-MC"), "Better-MC");
+    assert_eq!(
+        super::convert::dir_name("Better MC"),
+        "Better-MC",
+        "空格折成 `-`、**不加**哈希"
+    );
+    assert_eq!(
+        super::convert::dir_name("pack"),
+        "pack",
+        "名字就叫 pack 也保留"
+    );
+
+    // 折过**别的**字符（这里是 `.`）就必须补哈希，否则不同名字会撞同一个目录
+    let versioned = super::convert::dir_name("Survival 1.20.1");
+    assert!(versioned.starts_with("Survival-1-20-1-"), "{versioned}");
+    assert_ne!(versioned, "Survival-1-20-1", "折过 `.` 就要补哈希");
+}
+
+#[test]
+fn a_failed_new_instance_directory_can_be_reused_for_retry() {
+    // 复审 r1 P2-9：失败回滚留下空目录时会挡住重试
+    let dir = temp_dir("retry");
+    let data = dir.join("data");
+    std::fs::create_dir_all(&data).expect("data root");
+    let env = crate::host::HostEnv::at_root(&data);
+
+    let request = crate::dto::ImportRequestView {
+        pack: dir.join("whatever.mrpack"),
+        instance: None,
+        instance_name: Some("Retry Me".to_string()),
+        overwrite: false,
+    };
+
+    // 第一次：目录不存在 ⇒ 建出来
+    let (first, register) = super::import::target_of(&env, &request).expect("首次应当可以建目录");
+    assert!(register);
+    assert!(first.is_dir());
+
+    // 第二次（模拟上一次失败留下的空目录）⇒ 复用，而不是报「已存在」
+    let (second, _) = super::import::target_of(&env, &request).expect("空目录应当可复用");
+    assert_eq!(first, second);
+
+    // 目录里已经有东西 ⇒ 拒绝（不能往别人的实例里倒）
+    std::fs::write(second.join("marker.txt"), b"x").expect("write");
+    assert!(
+        super::import::target_of(&env, &request).is_err(),
+        "非空目录必须拒绝"
+    );
+
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+#[test]
+fn pack_epoch_is_per_host_and_is_its_own_counter() {
+    // 复审 r2 P3-6：代次**按 host** 分开（不再是跨 host 共享的裸静态量）。
+    // 两个 host（两个临时根）各 bump 一次，互不影响 —— 这正是并行测试串扰的根因。
+    let one = temp_dir("epoch-one");
+    let two = temp_dir("epoch-two");
+    let env_one = crate::host::HostEnv::at_root(one.join("data"));
+    let env_two = crate::host::HostEnv::at_root(two.join("data"));
+
+    let before_one = super::pack_epoch(&env_one);
+    let before_two = super::pack_epoch(&env_two);
+    super::bump_pack_epoch(&env_one);
+    assert_eq!(
+        super::pack_epoch(&env_one),
+        before_one.wrapping_add(1),
+        "自己这个 host 的代次 +1"
+    );
+    assert_eq!(
+        super::pack_epoch(&env_two),
+        before_two,
+        "**另一个** host 的代次不受影响（P3-6 的根因）"
+    );
+    assert_eq!(super::in_flight(&env_two), 0, "在跑计数也是每 host 一份");
+
+    let _ = std::fs::remove_dir_all(&one);
+    let _ = std::fs::remove_dir_all(&two);
+}
+
+#[test]
+fn a_failed_import_releases_the_in_flight_flag_and_keeps_install_cancel_intact() {
+    // 复审 r2 P2-1 的护栏：早退路径必须把「在跑」计数放回去，否则之后**下载页**的
+    // 「取消安装」会被当成导入取消（不发 `InstallCancelled`，还给内容库画一句假话）。
+    use crate::dto::{
+        AppCommand, AppEvent, Backend, CoreEvent, ImportRequestView, PackCommand, PackEvent,
+    };
+
+    let dir = temp_dir("inflight-guard");
+    let data = dir.join("data");
+    std::fs::create_dir_all(&data).expect("data root");
+    let host_env = crate::host::HostEnv::at_root(&data);
+    let mut host = crate::host::CoreHost::headless(host_env.clone());
+
+    // ① 派一次**必然早退**的导入：包文件不存在 ⇒ 探测当场失败，根本不进管线
+    host.dispatch(AppCommand::Pack(Box::new(PackCommand::Import(Box::new(
+        ImportRequestView {
+            pack: dir.join("missing.mrpack"),
+            instance: None,
+            instance_name: Some("Guess".to_string()),
+            overwrite: false,
+        },
+    )))));
+    let events = pump_until(&mut host, |all| {
+        pack_events(all)
+            .iter()
+            .any(|event| matches!(event, PackEvent::Probe(_)))
+    });
+    assert!(
+        pack_events(&events)
+            .iter()
+            .any(|event| matches!(event, PackEvent::Probe(_))),
+        "坏包必须给出探测诊断（而不是静默）；实际收到 {events:?}"
+    );
+    assert_eq!(
+        super::in_flight(&host_env),
+        0,
+        "早退之后「在跑」计数必须归零（RAII guard 负责，不靠手工 finished）"
+    );
+
+    // ② 此后下载页的「取消安装」必须照常发 `InstallCancelled`，且**不能**冒出 pack 的取消
+    host.dispatch(AppCommand::CancelInstall);
+    let events = pump(&mut host);
+    assert!(
+        events
+            .iter()
+            .any(|event| matches!(event, AppEvent::Core(CoreEvent::InstallCancelled))),
+        "没有导入在跑时，取消安装必须照常给回执（否则用户点了取消毫无反应）"
+    );
+    assert!(
+        !pack_events(&events)
+            .iter()
+            .any(|event| matches!(event, PackEvent::Cancelled)),
+        "此刻没有导入在跑，不该给内容库发「导入还在后台跑」"
+    );
+
+    let _ = std::fs::remove_dir_all(&dir);
+}
diff --git a/crates/presenter/src/host/addon/pack/tests/harness.rs b/crates/presenter/src/host/addon/pack/tests/harness.rs
new file mode 100644
index 0000000..4376f32
--- /dev/null
+++ b/crates/presenter/src/host/addon/pack/tests/harness.rs
@@ -0,0 +1,56 @@
+//! pack 用例的共用夹具：临时目录、文件写入、host 泵。
+//!
+//! 拆出去只为一件事：`tests.rs` 已经 429 行（超 400 硬线），而这些 helper 与任何一条断言无关。
+//! `tests.rs` 里各条用例的「抓得住什么」写在用例自己的注释里，这里只放机械动作。
+
+use std::path::PathBuf;
+
+/// 每个用例一个独立临时目录（用完删）。
+pub(super) fn temp_dir(name: &str) -> PathBuf {
+    let dir = std::env::temp_dir().join(format!("ull-m113-{name}-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    std::fs::create_dir_all(&dir).expect("temp dir");
+    dir
+}
+
+pub(super) fn write(path: &std::path::Path, bytes: &[u8]) {
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent).expect("parent");
+    }
+    std::fs::write(path, bytes).expect("write");
+}
+
+/// 泵一次 host：把后台任务收成事件并取走。
+pub(super) fn pump(host: &mut crate::host::CoreHost) -> Vec {
+    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/sources.rs b/crates/presenter/src/host/addon/sources.rs
new file mode 100644
index 0000000..19bfd40
--- /dev/null
+++ b/crates/presenter/src/host/addon/sources.rs
@@ -0,0 +1,262 @@
+//! 两个站点的检索方言（M109）：把各自的 JSON 翻成 [`ContentHit`]。
+//!
+//! 两个站点在**同一件事上用的字段名完全不同**，所以这里每个站点一段、各自带注释：
+//!
+//! | 语义 | Modrinth `/v2/search` | CurseForge `/v1/mods/search` |
+//! |---|---|---|
+//! | 项目 id | `project_id`（base62） | `id`（数字） |
+//! | 标题 / 简介 | `title` / `description` | `name` / `summary` |
+//! | 下载量 | `downloads` | `downloadCount` |
+//! | 游戏版本 | `versions` | `latestFilesIndexes[].gameVersion` |
+//! | 加载器 | `categories` 里混着的 `fabric`/`forge`/… | `latestFilesIndexes[].modLoader`（数字枚举） |
+//!
+//! 加载器那一行是最容易抄错的地方：Modrinth 的 `categories` 同时装着 `optimization` 这种**分类标签**，
+//! 直接整份当加载器用，画面上就会多出「optimization」这种假加载器（`sources/tests` 钉住了这一条）。
+
+use serde_json::Value;
+
+use crate::dto::{
+    loader_facet, ContentHit, ContentKind, ContentQuery, ContentResults, ContentSource,
+};
+
+use super::super::env::HostEnv;
+use super::curseforge_ready;
+use super::http::{encode, get};
+
+/// Modrinth v2 的根（无需 key）。
+pub(super) const MODRINTH: &str = "https://api.modrinth.com/v2";
+/// CurseForge v1 的根（需要 `X-API-KEY`）。
+pub(super) const CURSEFORGE: &str = "https://api.curseforge.com/v1";
+/// CurseForge 的「Minecraft」gameId（官方固定值）。
+const CF_MINECRAFT: u32 = 432;
+
+/// 检索分派。
+pub(super) fn search(env: &HostEnv, query: &ContentQuery) -> Result {
+    match query.source {
+        ContentSource::Modrinth => modrinth(env, query),
+        ContentSource::Curseforge => curseforge(env, query),
+    }
+}
+
+// --------------------------------------------------------------- Modrinth
+
+fn modrinth(env: &HostEnv, query: &ContentQuery) -> Result {
+    let mut facets = vec![format!("[\"project_type:{}\"]", query.kind.modrinth_type())];
+    if let Some(version) = &query.game_version {
+        facets.push(format!("[\"versions:{version}\"]"));
+    }
+    if let Some(facet) = query.loader.and_then(loader_facet) {
+        facets.push(format!("[\"categories:{facet}\"]"));
+    }
+
+    let mut url = format!(
+        "{MODRINTH}/search?limit={}&offset={}&index={}&facets={}",
+        query.limit.min(100),
+        query.offset,
+        query.sort.modrinth_index(),
+        encode(&format!("[{}]", facets.join(",")))
+    );
+    if !query.text.trim().is_empty() {
+        url.push_str(&format!("&query={}", encode(query.text.trim())));
+    }
+
+    let body = get(env, &url, &[])?;
+    let json: Value = serde_json::from_str(&body)
+        .map_err(|error| format!("Modrinth 返回的不是合法 JSON：{error}"))?;
+    let hits = json
+        .get("hits")
+        .and_then(Value::as_array)
+        .ok_or_else(|| "Modrinth 返回里没有 hits 字段".to_string())?
+        .iter()
+        .map(modrinth_hit)
+        .collect::>();
+
+    Ok(ContentResults {
+        query: query.clone(),
+        hits,
+        total: u32_of(&json, "total_hits"),
+        curseforge: curseforge_ready(),
+    })
+}
+
+/// 一条 Modrinth 命中项 → DTO（缺字段一律给空/零，**不**编造）。
+fn modrinth_hit(value: &Value) -> ContentHit {
+    let loaders = strings(value, "categories")
+        .into_iter()
+        // `categories` 混着加载器与分类标签：只留已知的四个加载器
+        .filter(|tag| matches!(tag.as_str(), "fabric" | "forge" | "neoforge" | "quilt"))
+        .collect();
+
+    ContentHit {
+        id: text(value, "project_id"),
+        slug: text(value, "slug"),
+        title: text(value, "title"),
+        summary: text(value, "description"),
+        author: text(value, "author"),
+        downloads: u64_of(value, "downloads"),
+        updated: date_part(&text(value, "updated")),
+        source: ContentSource::Modrinth,
+        game_versions: strings(value, "versions"),
+        loaders,
+        icon: optional_text(value, "icon_url"),
+    }
+}
+
+// --------------------------------------------------------------- CurseForge
+
+fn curseforge(env: &HostEnv, query: &ContentQuery) -> Result {
+    let Some(key) = super::curseforge_key() else {
+        return Err("CurseForge 需要 API key（ULL_CF_API_KEY 未设置）".to_string());
+    };
+    let mut url = format!(
+        "{CURSEFORGE}/mods/search?gameId={CF_MINECRAFT}&classId={}&index={}&pageSize={}&sortField={}&sortOrder=desc",
+        query.kind.curseforge_class(),
+        query.offset,
+        query.limit.min(50),
+        query.sort.curseforge_field()
+    );
+    if !query.text.trim().is_empty() {
+        url.push_str(&format!("&searchFilter={}", encode(query.text.trim())));
+    }
+    if let Some(version) = &query.game_version {
+        url.push_str(&format!("&gameVersion={}", encode(version)));
+    }
+
+    let body = get(env, &url, &[("x-api-key", key.as_str())])?;
+    let json: Value = serde_json::from_str(&body)
+        .map_err(|error| format!("CurseForge 返回的不是合法 JSON：{error}"))?;
+    let hits = json
+        .get("data")
+        .and_then(Value::as_array)
+        .ok_or_else(|| "CurseForge 返回里没有 data 字段".to_string())?
+        .iter()
+        .map(curseforge_hit)
+        .collect::>();
+
+    Ok(ContentResults {
+        query: query.clone(),
+        hits,
+        total: json
+            .get("pagination")
+            .map(|pagination| u64_of(pagination, "totalCount"))
+            .and_then(|value| u32::try_from(value).ok())
+            .unwrap_or(0),
+        curseforge: true,
+    })
+}
+
+/// 一条 CF 命中项 → DTO。加载器只能从 `latestFilesIndexes[].modLoader` 的数字枚举反推。
+fn curseforge_hit(value: &Value) -> ContentHit {
+    let mut game_versions: Vec = 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 optional_text(value: &Value, key: &str) -> Option {
+    value
+        .get(key)
+        .and_then(Value::as_str)
+        .filter(|text| !text.is_empty())
+        .map(ToString::to_string)
+}
+
+/// 取字符串数组（缺 / 类型不对 ⇒ 空 vec）。
+fn strings(value: &Value, key: &str) -> Vec {
+    value
+        .get(key)
+        .and_then(Value::as_array)
+        .map(|items| {
+            items
+                .iter()
+                .filter_map(|item| item.as_str().map(ToString::to_string))
+                .collect()
+        })
+        .unwrap_or_default()
+}
+
+fn u64_of(value: &Value, key: &str) -> u64 {
+    value.get(key).and_then(Value::as_u64).unwrap_or(0)
+}
+
+fn u32_of(value: &Value, key: &str) -> u32 {
+    u32::try_from(u64_of(value, key)).unwrap_or(0)
+}
+
+/// ISO-8601 → 日期部分（`2024-05-01T…` → `2024-05-01`；短串原样返回）。
+pub(super) fn date_part(raw: &str) -> String {
+    raw.get(..10).unwrap_or(raw).to_string()
+}
+
+/// 类型名只用来钉住「四条侧栏都在」的常量没被改乱（检索本身按 `kind` 走 facet）。
+#[must_use]
+pub(super) fn all_kinds() -> [ContentKind; 4] {
+    ContentKind::ALL
+}
diff --git a/crates/presenter/src/host/addon/tests.rs b/crates/presenter/src/host/addon/tests.rs
new file mode 100644
index 0000000..0d4a135
--- /dev/null
+++ b/crates/presenter/src/host/addon/tests.rs
@@ -0,0 +1,85 @@
+//! 内容库宿主的守门测试（M109）：编码、文件名穿越、退避判定、两个站点的方言映射。
+
+use std::time::Duration;
+
+use super::http::{encode, retry_after, retryable};
+use super::install::safe_file_name;
+use super::sources::{all_kinds, curseforge_loader, date_part};
+use crate::dto::ContentKind;
+
+#[test]
+fn percent_encoding_keeps_the_query_readable_and_escapes_the_rest() {
+    assert_eq!(encode("1.20.1"), "1.20.1");
+    assert_eq!(
+        encode("[\"versions:1.20.1\"]"),
+        "%5B%22versions%3A1.20.1%22%5D"
+    );
+    assert_eq!(encode("中文"), "%E4%B8%AD%E6%96%87");
+    assert_eq!(encode("a b"), "a%20b");
+}
+
+#[test]
+fn file_names_never_carry_a_path() {
+    // 抓得住：站点给的 `../../evil.jar` 落到实例目录之外（穿越）。
+    assert_eq!(safe_file_name("sodium.jar"), "sodium.jar");
+    assert_eq!(safe_file_name("../../evil.jar"), "evil.jar");
+    assert_eq!(safe_file_name("mods\\jei.jar"), "jei.jar");
+    assert_eq!(safe_file_name(".."), "download.bin");
+    assert_eq!(safe_file_name(""), "download.bin");
+}
+
+#[test]
+fn dates_are_sliced_not_guessed() {
+    assert_eq!(date_part("2024-05-01T12:00:00Z"), "2024-05-01");
+    assert_eq!(date_part("2024-05"), "2024-05");
+    assert_eq!(date_part(""), "");
+}
+
+#[test]
+fn only_rate_limited_and_transient_failures_are_retried() {
+    assert!(retryable("HTTP 429 (retry_after=Some(3))"));
+    assert!(retryable("HTTP 503 (retry_after=None)"));
+    assert!(!retryable("HTTP 404 (retry_after=None)"));
+    assert!(
+        !retryable("HTTP 401 (retry_after=None)"),
+        "密钥错重试只会更糟"
+    );
+}
+
+#[test]
+fn retry_after_prefers_the_server_and_falls_back_to_exponential() {
+    assert_eq!(
+        retry_after("HTTP 429 (retry_after=Some(7))", 0),
+        Duration::from_secs(7)
+    );
+    assert_eq!(
+        retry_after("HTTP 429 (retry_after=None)", 0),
+        Duration::from_secs(1)
+    );
+    assert_eq!(
+        retry_after("HTTP 429 (retry_after=None)", 2),
+        Duration::from_secs(4)
+    );
+    // 服务端要得再多也不等超过 30s（交互与截图不能被一次退避挂死）
+    assert_eq!(
+        retry_after("HTTP 429 (retry_after=Some(900))", 0),
+        Duration::from_secs(30)
+    );
+}
+
+#[test]
+fn curseforge_loader_ids_follow_the_official_enum() {
+    assert_eq!(curseforge_loader(1), Some("forge"));
+    assert_eq!(curseforge_loader(4), Some("fabric"));
+    assert_eq!(curseforge_loader(5), Some("quilt"));
+    assert_eq!(curseforge_loader(6), Some("neoforge"));
+    assert_eq!(curseforge_loader(99), None);
+}
+
+#[test]
+fn the_four_content_kinds_are_the_four_side_entries() {
+    assert_eq!(
+        all_kinds().map(ContentKind::slug),
+        ["modpack", "mod", "resourcepack", "shader"]
+    );
+}
diff --git a/crates/presenter/src/host/cancel_tests.rs b/crates/presenter/src/host/cancel_tests.rs
new file mode 100644
index 0000000..c044e1b
--- /dev/null
+++ b/crates/presenter/src/host/cancel_tests.rs
@@ -0,0 +1,344 @@
+//! 取消安装的**实测装置**（M105）。
+//!
+//! ## 为什么这条测试要真起一次安装
+//!
+//! 「点取消没反应」有三种可能的断点，读码分不出来：
+//! ① 按钮/消息链断了（不派 `AppCommand::CancelInstall`）；
+//! ② host 收下取消后，**还在跑的任务**继续发进度事件，把面板又点亮（面板闪一下又回来）；
+//! ③ 取消根本停不下传输（M105 之前 core 的 `execute` 没有取消入参，下载线程会跑到段尾）。
+//!
+//! ①② 能靠单测的假事件流抓；③ 只有真起一次安装、真取消、真量「取消之后还在发生什么」才抓得到。
+//! 修完之后 ①②③ 都有守门：① 是 app 层的消息测试，② 是下面那条 CI 可跑的
+//! [`progress_from_a_cancelled_job_is_dropped`]，③ 就是本用例（真网络）。
+//!
+//! 所以这一条是**真网络**用例：`#[ignore]` 守着（CI 不跑），人工跑：
+//!
+//! ```text
+//! cargo test -p unlucky-presenter --test '' -- real_install --ignored --nocapture
+//! # 或（等价，本用例在 lib 测试里）
+//! cargo test -p unlucky-presenter real_install_cancel -- --ignored --nocapture
+//! ```
+//!
+//! ## 它量什么（三样里能抓住的两样）
+//!
+//! | 现象 | 怎么量 | 抓住什么 / 抓不住什么 |
+//! |---|---|---|
+//! | 进度还在推进 | 取消后收到的 `InstallProgress(Some)` 条数与 `files_done` 增量 | 抓得住「UI 侧还在被事件喂」；抓不住事件之外的后台动作 |
+//! | 断点文件 | `/**/*.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("已取消".to_string()),
+        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..533f15c
--- /dev/null
+++ b/crates/presenter/src/host/dispatch.rs
@@ -0,0 +1,248 @@
+//! `CoreHost::dispatch` 的指令实现（从 `host/mod.rs` 拆出，守 400 行上限）。
+//!
+//! 父模块的私有字段对子模块可见，所以这里直接读写 `self.env` / `self.tx` 等。
+
+use crate::dto::{
+    AccountNoticeCode, AppCommand, Backend, CoreEvent, CreateRequest, LoaderKind, PackEvent,
+};
+use crate::toast::ToastKind;
+
+use super::accounts::{self, LoginJob};
+use super::{
+    addon, game, install, java, launch, loader_versions, logs, settings, versions, CoreHost,
+};
+
+impl CoreHost {
+    /// 下发一条用户意图（`Backend::dispatch` 的实现体）。
+    pub(super) fn dispatch_command(&mut self, command: AppCommand) {
+        self.dispatch_inner(command);
+    }
+}
+impl CoreHost {
+    /// 指令分发（见 `dispatch_command`）。
+    fn dispatch_inner(&mut self, command: AppCommand) {
+        match command {
+            AppCommand::RefreshAll => self.refresh_all(),
+            AppCommand::LaunchInstance(id) => self.start_launch(&id),
+            AppCommand::StopInstance(id) => match self.running_pid(&id) {
+                Some(pid) => match launch::stop(pid) {
+                    Ok(()) => self.toast(ToastKind::Info, "已请求停止游戏进程"),
+                    Err(reason) => self.toast(ToastKind::Error, reason),
+                },
+                None => self.toast(ToastKind::Warn, "这个实例当前没有在跑"),
+            },
+            AppCommand::ListVersions(_) => versions::spawn_list(self.env.clone(), self.tx.clone()),
+            AppCommand::ListLoaderVersions { kind, mc_version } => {
+                loader_versions::spawn_list(self.env.clone(), self.tx.clone(), kind, mc_version);
+            }
+            AppCommand::InstallVersion(version) => {
+                let cancel = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
+                self.install_cancel = Some(std::sync::Arc::clone(&cancel));
+                let epoch = self.next_install_epoch();
+                install::spawn_install(
+                    self.env.clone(),
+                    self.tx.clone(),
+                    CreateRequest {
+                        name: version.clone(),
+                        version,
+                        loader: LoaderKind::Vanilla,
+                        loader_version: String::new(),
+                    },
+                    cancel,
+                    epoch,
+                );
+            }
+            AppCommand::CreateInstance(request) => {
+                let cancel = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
+                self.install_cancel = Some(std::sync::Arc::clone(&cancel));
+                let epoch = self.next_install_epoch();
+                install::spawn_install(self.env.clone(), self.tx.clone(), request, cancel, epoch);
+            }
+            AppCommand::CancelInstall => {
+                // 取消的三级语义（M105 实测后定稿，见 `install::CANCELLED`）：
+                // ① **面板立刻收回**（不等后台，用户点了就有反应）；
+                // ② **作废旧任务的代次**：后台线程是异步停的（取消延迟 = 一个数据块），
+                //    它带回来的进度事件一律因代次不符被 `handle` 丢掉——面板不会被重新点亮。
+                //    这是「点了没反应」的真根因：以前生效了又被旧事件盖回去；
+                // ③ 后台线程经 `install::run` 的取消检查停在段边界、**绝不登记实例**，
+                //    core 的 `execute_with_cancel` 还会就地掐断在飞的那个文件。
+                //
+                // 为什么不在这里 join 后台线程：UI 线程绝不能为了「等它停」而阻塞
+                // （一个数据块的延迟在人眼下就是「立刻」，但足以让 UI 卡住一帧以上）。
+                if let Some(cancel) = &self.install_cancel {
+                    cancel.store(true, std::sync::atomic::Ordering::SeqCst);
+                }
+                // M113: import/export —— 同一块面板的「取消」对导入也生效：立标记 + 作废 pack 代次
+                // 返回值告诉我们「刚才有没有导入在跑」：有的话**不能**再发 install 那条取消信号
+                // （它说的是「安装已取消、实例未创建」，而导入会在后台跑完并登记实例）。
+                let pack_was_running = addon::cancel_pack(&self.env);
+                if pack_was_running {
+                    self.send(CoreEvent::Pack(Box::new(PackEvent::Cancelled)));
+                }
+                self.install_epoch = self.install_epoch.wrapping_add(1);
+                self.install = None;
+                self.send(CoreEvent::InstallProgress(None));
+                // 只发信号、不发文案（复审 P2-2）：presenter 没有 i18n 依赖，
+                // 写死的中文会和页面语言打架。提示语由 app 层按 `Key` 现求。
+                // 导入在跑时不发这条：下载页那条文案说的是「实例未创建」，对导入是撒谎。
+                if !pack_was_running {
+                    self.send(CoreEvent::InstallCancelled);
+                }
+            }
+            AppCommand::SetIsolation { id, mode } => {
+                match game::set_isolation(&self.env, &id, &mode) {
+                    Ok(()) => {
+                        self.toast(ToastKind::Success, "隔离档位已更新");
+                        self.refresh_instances();
+                    }
+                    Err(reason) => self.toast(ToastKind::Error, reason),
+                }
+            }
+            AppCommand::RefreshLogSessions => {
+                self.send(CoreEvent::LogSessionsChanged(logs::sessions(&self.env)));
+            }
+            AppCommand::OpenLogSession(id) => self.open_session(&id),
+            AppCommand::ImportCrashLog(path) => match logs::analyze_crash_file(&path) {
+                Ok((label, report)) => {
+                    self.send(CoreEvent::DiagnosisReady(report));
+                    self.toast(ToastKind::Info, label);
+                }
+                Err(reason) => self.toast(ToastKind::Warn, reason),
+            },
+            // 账户增删切：结果走**页面横幅**（`AccountNoticeChanged`），不发 toast——
+            // app-iced 不渲染 toast，发出去等于用户什么都看不到（复审 r1 P2-2）。
+            AppCommand::AddOfflineAccount(name) => match accounts::add_offline(&self.env, &name) {
+                Ok(display) => {
+                    self.notice(AccountNoticeCode::Added, &display, "");
+                    self.refresh_accounts();
+                }
+                Err(failure) => {
+                    self.notice_failure(failure, &name);
+                    self.refresh_accounts();
+                }
+            },
+            AppCommand::RemoveAccount(key) => match accounts::remove(&self.env, &key) {
+                Ok(display) => {
+                    if self.active_account.as_deref() == Some(key.as_str()) {
+                        self.active_account = None;
+                    }
+                    self.notice(AccountNoticeCode::Removed, &display, "");
+                    self.refresh_accounts();
+                }
+                Err(failure) => {
+                    self.notice_failure(failure, &key);
+                    self.refresh_accounts();
+                }
+            },
+            AppCommand::SwitchAccount(id) => {
+                let name = self
+                    .accounts
+                    .iter()
+                    .find(|account| account.id == id)
+                    .map_or_else(|| id.clone(), |account| account.name.clone());
+                self.active_account = Some(id);
+                self.refresh_accounts();
+                self.notice(AccountNoticeCode::Switched, &name, "");
+            }
+            AppCommand::DismissAccountNotice => {
+                self.send(CoreEvent::AccountNoticeChanged(None));
+            }
+            AppCommand::StartDeviceLogin => {
+                self.login = Some(LoginJob::new());
+                let job = self.login.clone().unwrap_or_default();
+                self.send(CoreEvent::DeviceLoginChanged(crate::dto::DeviceLoginView {
+                    phase: crate::dto::DeviceLoginPhase::Requesting,
+                    message: "正在向微软申请设备码…".to_string(),
+                    ..crate::dto::DeviceLoginView::new()
+                }));
+                accounts::start_login(self.env.clone(), self.tx.clone(), job);
+            }
+            AppCommand::StartBrowserLogin => {
+                self.login = Some(LoginJob::new());
+                let job = self.login.clone().unwrap_or_default();
+                self.send(CoreEvent::DeviceLoginChanged(crate::dto::DeviceLoginView {
+                    phase: crate::dto::DeviceLoginPhase::Requesting,
+                    message: "正在准备浏览器登录（本地回调端口）…".to_string(),
+                    ..crate::dto::DeviceLoginView::new()
+                }));
+                accounts::start_browser_login(self.env.clone(), self.tx.clone(), job);
+            }
+            AppCommand::CancelDeviceLogin => {
+                if let Some(job) = &self.login {
+                    job.cancel();
+                }
+                self.login = None;
+                // 第三方轨的面板也归这条「关掉登录面板」：两条轨都不该留一个转不完的圈
+                if let Some(job) = &self.authlib {
+                    job.cancel();
+                }
+                self.authlib = None;
+                self.send(CoreEvent::DeviceLoginChanged(
+                    crate::dto::DeviceLoginView::new(),
+                ));
+                self.send(CoreEvent::AuthlibLoginChanged(
+                    crate::dto::AuthlibLoginView::new(),
+                ));
+            }
+            AppCommand::AddAuthlibAccount(request) => {
+                self.authlib = Some(LoginJob::new());
+                let job = self.authlib.clone().unwrap_or_default();
+                self.send(CoreEvent::AuthlibLoginChanged(
+                    crate::dto::AuthlibLoginView::running(&request.server, "正在校验服务器地址…"),
+                ));
+                accounts::start_authlib_login(self.env.clone(), self.tx.clone(), job, request);
+            }
+            AppCommand::ProbeAuthlibServer(server) => {
+                // 只探活：后台线程跑服务发现，结果回到同一条 `AuthlibLoginChanged`
+                let env = self.env.clone();
+                let tx = self.tx.clone();
+                accounts::spawn_probe(env, tx, server);
+            }
+            AppCommand::InstallJava(vendor) => {
+                self.java_busy = true;
+                self.java_message = format!("正在安装 Java（{vendor}）…");
+                self.refresh_java();
+                java::spawn_install(
+                    self.env.clone(),
+                    self.tx.clone(),
+                    unlucky_core::game::java::JdkVendor::parse(&vendor),
+                );
+            }
+            AppCommand::SetSetting { key, value } => match settings::set(&self.env, &key, &value) {
+                Ok(()) => {
+                    self.send(CoreEvent::SettingsChanged(settings::groups(&self.env)));
+                    self.java_chain.clear();
+                    self.refresh_java();
+                }
+                Err(reason) => self.toast(ToastKind::Error, reason),
+            },
+            AppCommand::DismissNotice(id) => {
+                self.notices.retain(|notice| notice.id != id);
+                self.send(CoreEvent::NoticesChanged(self.notices.clone()));
+            }
+            // M109：内容库检索（网络在后台线程，结果经 `HostTask::Content` 回来）
+            AppCommand::SearchContent(query) => {
+                addon::spawn_search(self.env.clone(), self.tx.clone(), query);
+            }
+            // M109：把某个内容项目装进指定实例。取消标记与安装面板共用同一条路
+            // （`CancelInstall` 会把标记置位，下载在阶段边界收尾）。
+            // M113: import/export —— 导入 / 预检 / 确认写盘 / 关面板
+            AppCommand::Pack(command) => self.pack(*command),
+            AppCommand::InstallContent(request) => {
+                let cancel = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
+                self.install_cancel = Some(std::sync::Arc::clone(&cancel));
+                // 代次与版本安装共用同一条路（M105 的形状）：取消/被顶掉之后，旧任务带回来的
+                // 进度事件一律被 `handle` 丢掉，内容库种的这次安装不会把面板重新点亮。
+                let epoch = self.next_install_epoch();
+                addon::spawn_install(self.env.clone(), self.tx.clone(), *request, cancel, epoch);
+            }
+            // AI 对话：agent 的 GUI host 未落地前用脚本回复（不接真实模型）
+            other @ (AppCommand::AskAgent(_) | AppCommand::StopAgent | AppCommand::SetYolo(_)) => {
+                self.chat.dispatch(other);
+                for event in self.chat.drain_events() {
+                    self.events.push_back(event);
+                }
+            }
+        }
+    }
+}
diff --git a/crates/presenter/src/host/engine.rs b/crates/presenter/src/host/engine.rs
new file mode 100644
index 0000000..03bf98d
--- /dev/null
+++ b/crates/presenter/src/host/engine.rs
@@ -0,0 +1,126 @@
+//! 下载引擎与 Java 落点的装配（versions / install / java 三个任务共用）。
+//!
+//! 与 CLI `install::build_engine` 同源：内容寻址缓存落 `.ULL/cache/`，地区判定走
+//! 24h 缓存 + 环境信号（**不做网络探测**，与 D7 的「不探测时」约定一致）。
+
+use std::path::PathBuf;
+use std::sync::Arc;
+
+use unlucky_core::download::cache::now_ms;
+use unlucky_core::download::region::{decide_from, load_cached, store_cached};
+use unlucky_core::download::region_system::detect_signals;
+use unlucky_core::download::{
+    ContentCache, DownloadEngine, EngineConfig, HealthRegistry, MirrorTable,
+};
+use unlucky_core::game::java::vendor::JdkVendor;
+use unlucky_core::game::java::{self, JavaInstallRoot};
+use unlucky_core::platform::paths::ProcessEnv;
+
+use super::env::HostEnv;
+
+/// 建下载引擎（缓存/健康度/地区判定都在数据根里）。
+pub fn engine(env: &HostEnv) -> DownloadEngine {
+    let cache_root = env.layout.cache();
+    let now = now_ms();
+    let region_path = cache_root.join("region.json");
+    let region = load_cached(®ion_path, now).unwrap_or_else(|| {
+        let profile = decide_from(&detect_signals(), now);
+        let _ = store_cached(®ion_path, &profile);
+        profile
+    });
+    DownloadEngine::new(
+        EngineConfig::default(),
+        Arc::new(MirrorTable::builtin()),
+        Arc::new(region),
+        Arc::new(HealthRegistry::open_in(&cache_root, now)),
+        Arc::new(ContentCache::open(&cache_root)),
+    )
+}
+
+/// 是否国内网络（决定默认发行版顺序与镜像优先级）。
+pub fn domestic(env: &HostEnv) -> bool {
+    engine(env).region().is_domestic()
+}
+
+/// 设置里的 `java.vendorPriority`（空 = 按地区默认序）。
+pub fn java_priority(env: &HostEnv) -> Vec {
+    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::*;
+
+    #[test]
+    fn engine_uses_the_data_root_cache() {
+        let dir = std::env::temp_dir().join(format!("ull-host-engine-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        let env = HostEnv::at_root(&dir);
+        std::fs::create_dir_all(env.layout.cache()).expect("cache");
+        let engine = engine(&env);
+        assert_eq!(engine.config().max_concurrency, 64);
+        // 地区判定不联网：只读缓存/信号
+        let _ = domestic(&env);
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    #[test]
+    fn java_merge_priority_reads_settings() {
+        let dir = std::env::temp_dir().join(format!("ull-host-engine-p-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        let env = HostEnv::at_root(&dir);
+        std::fs::create_dir_all(env.layout.config()).expect("config");
+        std::fs::write(
+            env.launcher_config(),
+            r#"{"java":{"vendorPriority":["zulu"]}}"#,
+        )
+        .expect("写配置");
+        assert_eq!(java_priority(&env), vec![JdkVendor::Zulu]);
+        std::fs::remove_dir_all(&dir).ok();
+    }
+}
diff --git a/crates/presenter/src/host/env.rs b/crates/presenter/src/host/env.rs
new file mode 100644
index 0000000..a1b6fd7
--- /dev/null
+++ b/crates/presenter/src/host/env.rs
@@ -0,0 +1,170 @@
+//! host 的环境快照：一份 `ResolvedData` + 由其派生的布局视图。
+//!
+//! app 自己不解析三模式数据根（那是 `core::platform::data_dir` 的活）；这里只做两件事：
+//! ①按「exe 同级便携 `launcher.json` 的 `core.*` 四键」拼请求；②把解析结果与
+//! `Platform` / `DataMode` 打成一个可克隆的结构，交给后台线程。
+//!
+//! 截图/演示通道用 [`HostEnv::at_root`] 直接钉一个根（`/.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,
+        })
+    }
+
+    /// 由解析结果建环境。
+    pub fn from_data(data: ResolvedData) -> Self {
+        Self {
+            layout: data.layout(),
+            game: GameLayout::new(data.game_home.clone()),
+            platform: Platform::current(),
+            data,
+        }
+    }
+
+    /// `config/launcher.json` 路径。
+    pub fn launcher_config(&self) -> PathBuf {
+        self.layout.launcher_config()
+    }
+
+    /// 设置存储（每次现读一份；写操作自己 save）。
+    pub fn store(&self) -> SettingStore {
+        SettingStore::load(self.launcher_config(), launcher_schema())
+    }
+
+    /// 启动会话根（`.ULL/data/agent/sessions`）。
+    pub fn sessions_root(&self) -> PathBuf {
+        self.layout.agent_sessions()
+    }
+
+    /// 数据目录模式。
+    pub fn mode(&self) -> DataMode {
+        self.data.mode
+    }
+
+    /// 人读一行（设置页「数据」分组展示）。
+    pub fn data_line(&self) -> String {
+        format!(
+            "{} · 启动器 {} · 游戏 {}",
+            self.data.mode,
+            self.data.launcher_home.display(),
+            self.data.game_home.display()
+        )
+    }
+}
+
+/// 便携目录那份 `launcher.json` → 数据根请求（只读 `core.*` 四键）。
+pub(crate) fn request_from_portable(exe_dir: &Path) -> DataDirRequest {
+    let mut request = DataDirRequest::default();
+    let path = portable_config_path(exe_dir);
+    if !path.is_file() {
+        return request;
+    }
+    let store = SettingStore::load(&path, launcher_schema());
+    let text = |key: &str| store.doc().effective_str(key).map(str::to_string);
+    if let Some(mode) = text(DATA_ROOT_KEYS[0]).as_deref().and_then(DataMode::parse) {
+        request.mode = mode;
+    }
+    if let Some(root) = text(DATA_ROOT_KEYS[1]) {
+        request.custom_root = Some(PathBuf::from(root));
+    }
+    if let Some(home) = text(DATA_ROOT_KEYS[2]) {
+        request.launcher_home = Some(PathBuf::from(home));
+    }
+    if let Some(home) = text(DATA_ROOT_KEYS[3]) {
+        request.game_home = Some(PathBuf::from(home));
+    }
+    request
+}
+
+/// `/.ULL/config/launcher.json`。
+pub(crate) fn portable_config_path(exe_dir: &Path) -> PathBuf {
+    LauncherLayout::new(exe_dir.join(".ULL")).launcher_config()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn at_root_splits_launcher_and_game_homes() {
+        let env = HostEnv::at_root("D:/tmp/ull-demo");
+        assert_eq!(env.layout.home(), Path::new("D:/tmp/ull-demo/.ULL"));
+        assert_eq!(env.game.root(), Path::new("D:/tmp/ull-demo/.minecraft"));
+        assert_eq!(env.mode(), DataMode::Portable);
+        assert!(env.data_line().contains("portable"));
+    }
+
+    #[test]
+    fn portable_request_reads_core_keys_only_when_file_exists() {
+        let dir = std::env::temp_dir().join(format!("ull-host-env-{}", std::process::id()));
+        std::fs::create_dir_all(dir.join(".ULL/config")).expect("建目录");
+        let request = request_from_portable(&dir);
+        assert_eq!(request, DataDirRequest::default());
+
+        std::fs::write(
+            portable_config_path(&dir),
+            r#"{"core":{"data_mode":"custom","data_custom_root":"D:/data/ull"}}"#,
+        )
+        .expect("写配置");
+        let request = request_from_portable(&dir);
+        assert_eq!(request.mode, DataMode::Custom);
+        assert_eq!(
+            request.custom_root.as_deref(),
+            Some(Path::new("D:/data/ull"))
+        );
+        std::fs::remove_dir_all(&dir).ok();
+    }
+}
diff --git a/crates/presenter/src/host/game.rs b/crates/presenter/src/host/game.rs
new file mode 100644
index 0000000..7960b3b
--- /dev/null
+++ b/crates/presenter/src/host/game.rs
@@ -0,0 +1,260 @@
+//! 实例快照：`profiles.json` + 版本 JSON + 会话索引 + 实例设置 → [`InstanceSummary`]。
+//!
+//! 「磁贴上的每个字」都在这里翻译完：版本号取自继承链根、加载器取自版本 id 前缀、
+//! 最后游玩时间取自会话索引、隔离档位取自实例设置（缺省跟全局 `instances.mode`）。
+
+use std::collections::BTreeMap;
+use std::path::Path;
+
+use unlucky_core::game::install::instance::{
+    read_instance_config, read_profiles, write_instance_config,
+};
+use unlucky_core::game::isolation::IsolationMode;
+use unlucky_core::game::{ProfileList, VersionJson};
+use unlucky_core::launch::session_index;
+
+use crate::dto::{
+    InstanceRuntime, InstanceSummary, LoaderInfo, LoaderKind, NoticeLevel, NoticeView,
+};
+
+use super::env::HostEnv;
+
+/// 全局默认隔离档位（`instances.mode`；缺键/坏值按 D20 默认 `isolated`）。
+pub fn global_mode(env: &HostEnv) -> IsolationMode {
+    env.store()
+        .doc()
+        .effective_str("instances.mode")
+        .and_then(IsolationMode::parse)
+        .unwrap_or_default()
+}
+
+/// 读实例清单（文件缺失 = 空列表，不是错误）。
+pub fn profiles(env: &HostEnv) -> ProfileList {
+    read_profiles(&env.layout).unwrap_or_default()
+}
+
+/// 全会话索引里「每个实例最近一次启动」的时间串。
+pub fn last_played(env: &HostEnv) -> BTreeMap {
+    let index = session_index::index_path(&env.sessions_root());
+    let entries = session_index::read_all(&index).unwrap_or_default();
+    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 → 加载器（HMCL 同款命名口径：`1.20.1-forge-47.2.0` / `fabric-loader-0.16.5-1.20.1`）。
+pub fn loader_from_id(version_id: &str) -> LoaderInfo {
+    let lower = version_id.to_ascii_lowercase();
+    let grab = |marker: &str| -> String {
+        lower
+            .split_once(marker)
+            .map(|(_, rest)| rest.trim_start_matches('-').to_string())
+            .unwrap_or_default()
+    };
+    let (kind, version) = if lower.contains("neoforge") {
+        (LoaderKind::NeoForge, grab("neoforge-"))
+    } else if lower.contains("fabric-loader") {
+        (LoaderKind::Fabric, grab("fabric-loader-"))
+    } else if lower.contains("quilt-loader") {
+        (LoaderKind::Quilt, grab("quilt-loader-"))
+    } else if lower.contains("forge") {
+        (LoaderKind::Forge, grab("forge-"))
+    } else if lower.contains("optifine") {
+        (LoaderKind::OptiFine, grab("optifine"))
+    } else if lower.contains("liteloader") {
+        (LoaderKind::LiteLoader, grab("liteloader-"))
+    } else {
+        (LoaderKind::Vanilla, String::new())
+    };
+    LoaderInfo { kind, version }
+}
+
+/// 实例的隔离档位（实例文件优先，缺省显示全局档位）。
+pub fn isolation_of(env: &HostEnv, id: &str) -> String {
+    let global = global_mode(env);
+    match read_instance_config(&env.layout, id) {
+        Ok(Some(config)) => config.effective_isolation(global).as_str().to_string(),
+        _ => global.as_str().to_string(),
+    }
+}
+
+/// 实例快照。
+pub fn instances(env: &HostEnv) -> Vec {
+    let profiles = profiles(env);
+    let played = last_played(env);
+    profiles
+        .profiles
+        .iter()
+        .map(|profile| {
+            let version_id = profile.version_id.clone();
+            let (mc_version, loader) = describe_version(env, &version_id);
+            InstanceSummary {
+                id: profile.id.as_str().to_string(),
+                name: profile.name.clone(),
+                mc_version,
+                loader,
+                last_played: played.get(profile.id.as_str()).cloned(),
+                runtime: InstanceRuntime::Idle,
+                icon: None,
+                isolation: isolation_of(env, profile.id.as_str()),
+                version_present: env.game.is_version_installed(&version_id),
+                version_id,
+            }
+        })
+        .collect()
+}
+
+/// 改实例隔离档位（写实例设置文件；不动任何数据）。
+///
+/// # Errors
+///
+/// 实例不存在、文件读不了/写不了时返回用户可读文案。
+pub fn set_isolation(env: &HostEnv, id: &str, mode: &str) -> Result<(), String> {
+    let parsed = IsolationMode::parse(mode)
+        .ok_or_else(|| format!("未知隔离档位 `{mode}`（isolated / shared）"))?;
+    let profiles = profiles(env);
+    let profile = profiles
+        .profiles
+        .iter()
+        .find(|profile| profile.id.as_str() == id)
+        .ok_or_else(|| format!("找不到实例 `{id}`"))?;
+    let mut config = read_instance_config(&env.layout, id)
+        .map_err(|error| format!("读实例设置失败：{error}"))?
+        .unwrap_or_else(|| {
+            unlucky_core::game::install::instance::InstanceConfig::new(
+                profile.id.as_str(),
+                &profile.version_id,
+            )
+        });
+    config.isolation = Some(match parsed {
+        IsolationMode::Isolated => unlucky_core::game::install::instance::Isolation::Isolated,
+        IsolationMode::Shared => unlucky_core::game::install::instance::Isolation::Shared,
+    });
+    write_instance_config(&env.layout, &config)
+        .map(|_| ())
+        .map_err(|error| format!("写实例设置失败：{error}"))
+}
+
+/// 启动前的切换检测：把 M30 的 `ModeChangeWarning` 翻成横幅通知。
+///
+/// 只在真启动时调用（会写 `lastModeChange.warned`，保证同一次切换只提示一次）。
+pub fn mode_change_notice(env: &HostEnv, id: &str) -> Option {
+    let mut config = read_instance_config(&env.layout, id).ok()??;
+    let warning = config.take_mode_change_warning()?;
+    let _ = write_instance_config(&env.layout, &config);
+    Some(NoticeView::new(
+        &format!("isolation:{id}"),
+        NoticeLevel::Warn,
+        "隔离档位已切换",
+        &warning.message(),
+    ))
+}
+
+/// 建目录（数据根首次运行时）。
+pub fn ensure_root(env: &HostEnv) {
+    let _ = env.layout.ensure();
+    let _ = std::fs::create_dir_all(env.game.root());
+}
+
+/// 版本本体目录是否存在（启动前快速判断）。
+pub fn version_present(env: &HostEnv, version_id: &str) -> bool {
+    env.game.is_version_installed(version_id)
+}
+
+/// 路径显示成短串（通知/错误文案用）。
+pub fn short_path(path: &Path) -> String {
+    path.display().to_string()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn loader_parsing_covers_all_shapes() {
+        let cases = [
+            ("1.20.4", LoaderKind::Vanilla, ""),
+            (
+                "fabric-loader-0.16.5-1.20.1",
+                LoaderKind::Fabric,
+                "0.16.5-1.20.1",
+            ),
+            (
+                "quilt-loader-0.24.0-1.20.1",
+                LoaderKind::Quilt,
+                "0.24.0-1.20.1",
+            ),
+            ("1.20.1-forge-47.2.0", LoaderKind::Forge, "47.2.0"),
+            ("1.21.1-neoforge-21.1.80", LoaderKind::NeoForge, "21.1.80"),
+        ];
+        for (id, kind, version) in cases {
+            let info = loader_from_id(id);
+            assert_eq!(info.kind, kind, "{id}");
+            assert_eq!(info.version, version, "{id}");
+            assert!(!info.badge().is_empty());
+        }
+    }
+
+    #[test]
+    fn isolation_write_then_read_round_trips() {
+        let dir = std::env::temp_dir().join(format!("ull-host-game-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        let env = HostEnv::at_root(&dir);
+        std::fs::create_dir_all(env.layout.config()).expect("config 目录");
+
+        // 直接建一份 profiles.json（register 需要版本本体，这里只测隔离写读）
+        let profiles = ProfileList {
+            profiles: vec![unlucky_core::game::InstanceProfile {
+                id: unlucky_core::game::ProfileId::generate(),
+                name: "demo".to_string(),
+                version_id: "1.20.1".to_string(),
+                game_dir: None,
+                running_dir: None,
+                java_path: None,
+                created_at: None,
+                last_played_at: None,
+                extra: BTreeMap::new(),
+            }],
+            ..ProfileList::default()
+        };
+        unlucky_core::game::install::instance::write_profiles(&env.layout, &profiles)
+            .expect("写清单");
+        let id = profiles.profiles[0].id.as_str().to_string();
+
+        assert_eq!(isolation_of(&env, &id), "isolated");
+        set_isolation(&env, &id, "shared").expect("切档位");
+        assert_eq!(isolation_of(&env, &id), "shared");
+        assert!(set_isolation(&env, &id, "nope").is_err());
+        std::fs::remove_dir_all(&dir).ok();
+    }
+}
diff --git a/crates/presenter/src/host/handle.rs b/crates/presenter/src/host/handle.rs
new file mode 100644
index 0000000..d203296
--- /dev/null
+++ b/crates/presenter/src/host/handle.rs
@@ -0,0 +1,206 @@
+//! `HostTask` → `CoreEvent` 的翻译（从 `host/mod.rs` 拆出，守 400 行硬限）。
+//!
+//! 父模块的私有字段对子模块可见，所以这里直接读写 `self.tx` / `self.launches` 等。
+
+use crate::dto::{AppEvent, CoreEvent, InstanceRuntime, LogOutcome, PackEvent};
+use crate::toast::ToastKind;
+
+use super::{addon, logs, CoreHost, HostTask, LiveLaunch};
+
+impl CoreHost {
+    /// 后台消息 → 事件。
+    pub(super) fn handle(&mut self, task: HostTask) {
+        match task {
+            HostTask::Versions(Ok(versions)) => self.send(CoreEvent::VersionListChanged(versions)),
+            HostTask::Versions(Err(reason)) => {
+                self.toast(ToastKind::Warn, format!("拉取版本清单失败：{reason}"));
+            }
+            HostTask::LoaderVersions {
+                kind,
+                mc_version,
+                result,
+            } => {
+                // 失败既要落进快照（页面禁用确认 + 显示具名原因），也要一条 Toast：
+                // 用户可能正盯着上面的版本列表，下拉那一行的红字容易被忽略。
+                if let Err(reason) = &result {
+                    self.toast(
+                        ToastKind::Warn,
+                        format!("取不到 {} 的加载器版本：{reason}", kind.label()),
+                    );
+                }
+                self.send(CoreEvent::LoaderVersions {
+                    kind,
+                    mc_version,
+                    result,
+                });
+            }
+            // M109：内容库检索。`Err` 不弹 toast——页面自己有失败态（四态之一），
+            // toast 只做「顺手提一句」会把可重试的错误变成一次性噪音。
+            HostTask::Content(result) => match *result {
+                Ok(results) => self.send(CoreEvent::ContentResults(Box::new(results))),
+                Err(reason) => self.send(CoreEvent::ContentFailed(reason)),
+            },
+            // M113: import/export —— 导入/导出事件带代次，取消后回来的旧事件一律丢掉
+            HostTask::Pack { event, epoch } => {
+                // pack 用**自己**的代次（复审 r1 P2-7）：共用安装的计数器会让
+                // 「关一次导入面板」把下载页正在跑的安装静默丢掉。
+                if epoch != addon::pack_epoch(&self.env) {
+                    return;
+                }
+                // 导入成功可能登记了新实例：与 `InstallDone` 同一条刷新（复审 r1 P2-1），
+                // 否则新实例要等下一次无关的 `RefreshAll` 才出现在实例页与目标 chips 里。
+                if matches!(*event, PackEvent::Report(_)) {
+                    self.refresh_instances();
+                }
+                self.send(CoreEvent::Pack(event));
+            }
+            // M105 的形状（代次丢包）为准：旧任务（已取消 / 被下一轮顶掉）的进度一律丢掉。
+            // 这是「点了取消没反应」的根因：取消时 `InstallProgress(None)` 刚把面板收回，
+            // 旧任务的下一条「下载中」事件立刻又把它点亮。
+            HostTask::Install { progress, epoch } => {
+                if epoch != self.install_epoch {
+                    return;
+                }
+                self.install = Some(*progress.clone());
+                self.send(CoreEvent::InstallProgress(Some(*progress)));
+            }
+            HostTask::InstallDone {
+                progress,
+                result,
+                epoch,
+            } => {
+                // 收尾同样看代次：取消之后那次「已取消」的收尾不该再动面板（面板早就回弹了），
+                // 也不该清掉**新一轮**安装的取消句柄。
+                if epoch != self.install_epoch {
+                    return;
+                }
+                self.install_cancel = None;
+                self.install = Some(*progress.clone());
+                self.send(CoreEvent::InstallProgress(Some(*progress)));
+                match result {
+                    Ok(_) => {
+                        self.refresh_instances();
+                        self.send(CoreEvent::LogSessionsChanged(logs::sessions(&self.env)));
+                    }
+                    Err(reason) => self.toast(ToastKind::Error, reason),
+                }
+            }
+            HostTask::Accounts(accounts) => {
+                self.accounts = accounts.clone();
+                self.send(CoreEvent::AccountsChanged(accounts));
+                self.refresh_instances();
+            }
+            HostTask::Login(view) => self.send(CoreEvent::DeviceLoginChanged(*view)),
+            HostTask::Authlib(view) => self.send(CoreEvent::AuthlibLoginChanged(*view)),
+            HostTask::Avatar { id, skin } => {
+                // 抓到/没抓到都记下来（`None` = 试过了，不再重试），再把列表盖好发出去
+                self.skins.insert(id, skin);
+                self.attach_skins();
+                self.send(CoreEvent::AccountsChanged(self.accounts.clone()));
+            }
+            HostTask::Java(page) => self.send(CoreEvent::JavaChanged(*page)),
+            HostTask::Logs {
+                sessions,
+                lines,
+                diagnosis,
+            } => {
+                self.send(CoreEvent::LogSessionsChanged(sessions));
+                self.send(CoreEvent::LogLinesChanged(lines));
+                if let Some(report) = diagnosis {
+                    self.send(CoreEvent::DiagnosisReady(report));
+                }
+            }
+            HostTask::Sessions(sessions) => self.send(CoreEvent::LogSessionsChanged(sessions)),
+            HostTask::Tail(batch) => {
+                if batch.running {
+                    self.send(CoreEvent::LogLinesChanged(batch.lines));
+                } else {
+                    self.send(CoreEvent::LogAppended(*batch));
+                }
+            }
+            HostTask::LaunchStarted {
+                id,
+                session_id,
+                pid,
+            } => {
+                self.pending.remove(&id);
+                self.failed.remove(&id);
+                self.launches.retain(|live| live.instance != id);
+                self.launches.push(LiveLaunch {
+                    instance: id.clone(),
+                    session: session_id.clone(),
+                    pid,
+                });
+                // 实时尾随一次只跟一场（下载页/日志页共用一个滚动窗口）；
+                // 已有别的实例在尾随时不抢占——它的日志仍在 JSONL 里，收尾后可回放。
+                if self.tail.session().is_none() {
+                    self.tail.attach(
+                        self.env
+                            .sessions_root()
+                            .join("game")
+                            .join(format!("{session_id}.jsonl")),
+                        &session_id,
+                    );
+                }
+                self.send(CoreEvent::InstanceRuntimeChanged {
+                    id,
+                    runtime: InstanceRuntime::Running { pid },
+                });
+            }
+            HostTask::Runtime { id, runtime } => {
+                self.send(CoreEvent::InstanceRuntimeChanged { id, runtime });
+            }
+            HostTask::LaunchEnd(finished) => {
+                // 收尾可能发生在 LaunchStarted 之前（build_request / spawn 失败只发
+                // LaunchEnd）：pending 必须在这里也清掉，否则 in_flight 恒真、该实例
+                // 本会话内再也起不来。
+                self.pending.remove(&finished.id);
+                self.launches.retain(|live| live.instance != finished.id);
+                let runtime = if finished.outcome == LogOutcome::Ok {
+                    self.failed.remove(&finished.id);
+                    InstanceRuntime::Idle
+                } else {
+                    // 记住失败原因：随后的 refresh_instances 会重建快照，
+                    // 不记的话磁贴的「失败/重试」外观会被 Idle 盖掉。
+                    self.failed
+                        .insert(finished.id.clone(), finished.summary.clone());
+                    InstanceRuntime::Failed {
+                        reason: finished.summary.clone(),
+                    }
+                };
+                self.send(CoreEvent::InstanceRuntimeChanged {
+                    id: finished.id.clone(),
+                    runtime,
+                });
+                self.send(CoreEvent::LaunchFinished((*finished).clone()));
+                // 只拆自己那场的尾随：并发时另一实例的实时日志不该被这次收尾掐掉。
+                if self.tail.session() == Some(finished.session.as_str()) {
+                    self.tail.detach();
+                }
+                self.send(CoreEvent::LogSessionsChanged(logs::sessions(&self.env)));
+                self.refresh_instances();
+            }
+            HostTask::Crash(report) => {
+                self.send(CoreEvent::DiagnosisReady(*report));
+            }
+            HostTask::Notice(notice) => self.push_notice(*notice),
+            HostTask::Toast(toast) => self.events.push_back(AppEvent::Toast(*toast)),
+        }
+    }
+
+    /// 尾随运行中会话（每 `TAIL_POLL_TICKS` 拍一次）。
+    pub(super) fn poll_tail(&mut self) {
+        let Some((session, lines)) = self.tail.poll() else {
+            return;
+        };
+        if lines.is_empty() {
+            return;
+        }
+        let running = self.launches.iter().any(|live| live.session == session);
+        self.send(CoreEvent::LogAppended(crate::dto::LiveLogBatch {
+            session,
+            lines,
+            running,
+        }));
+    }
+}
diff --git a/crates/presenter/src/host/identity.rs b/crates/presenter/src/host/identity.rs
new file mode 100644
index 0000000..fd5df29
--- /dev/null
+++ b/crates/presenter/src/host/identity.rs
@@ -0,0 +1,103 @@
+//! 启动身份：选中账户 → `AuthPlaceholders`（**凭据只在这里读，读完即丢**）+ 收尾结局映射。
+//!
+//! 与 CLI `commands/identity.rs` 同源：微软轨过期就静默续期并回写凭据（refresh_token 轮换，
+//! 旧值作废）；零账户回落离线占位，保证没有账户时照样能启动。
+
+use unlucky_core::auth::account::{AccountKind, Credentials};
+use unlucky_core::auth::microsoft::MicrosoftAuth;
+use unlucky_core::auth::offline::offline_login;
+use unlucky_core::auth::AccountStore;
+use unlucky_core::download::blocking::block_on;
+use unlucky_core::game::ProfileId;
+use unlucky_core::launch::request::AuthPlaceholders;
+
+use crate::dto::LogOutcome;
+
+use super::env::HostEnv;
+
+/// 把选中账户翻成启动占位符（**凭据只在这里读，读完即丢**）。
+///
+/// 微软轨：过期就静默续期并回写凭据（refresh_token 轮换，旧值作废）。
+///
+/// # Errors
+///
+/// 账户不存在/凭据类型不符/令牌过期且刷新失败时返回用户可读文案。
+pub fn resolve(env: &HostEnv, account: Option<&str>) -> Result<(AuthPlaceholders, String), String> {
+    let store = AccountStore::open(env.layout.auth_data());
+    let chosen = match account {
+        Some(key) => store
+            .find(key)
+            .cloned()
+            .ok_or_else(|| format!("找不到账户 `{key}`"))?,
+        None => match store.accounts() {
+            [] => {
+                let uuid = ProfileId::generate().as_str().replace('-', "");
+                return Ok((
+                    AuthPlaceholders {
+                        player_name: "Player".to_string(),
+                        uuid,
+                        user_type: "legacy".to_string(),
+                        user_properties: "{}".to_string(),
+                        ..AuthPlaceholders::default()
+                    },
+                    "未登录账户，按离线占位启动".to_string(),
+                ));
+            }
+            [only] => only.clone(),
+            many => return Err(format!("有 {} 个账户，请在账户页选一个再启动", many.len())),
+        },
+    };
+    let line = format!("账户 {}（{}）", chosen.display_name(), chosen.kind.label());
+    match chosen.kind {
+        AccountKind::Offline => {
+            let placeholders =
+                offline_login(&chosen).map_err(|error| format!("离线账户解析失败：{error}"))?;
+            Ok((placeholders, line))
+        }
+        AccountKind::Microsoft => {
+            let Some(Credentials::Microsoft(session)) = store.credentials(&chosen.id) else {
+                return Err(format!(
+                    "账户 {} 的微软凭据缺失或类型不符，请重新登录",
+                    chosen.display_name()
+                ));
+            };
+            let auth =
+                MicrosoftAuth::from_env().map_err(|error| format!("微软登录不可用：{error}"))?;
+            let (fresh, _) = block_on(auth.ensure_fresh(session))
+                .map_err(|error| format!("微软令牌刷新失败：{error}"))?;
+            if &fresh != session {
+                // refresh_token 已轮换：立刻回写，旧值作废。
+                let mut store = AccountStore::open(env.layout.auth_data());
+                let _ = store.update_credentials(&chosen.id, Credentials::Microsoft(fresh.clone()));
+                let _ = store.save();
+            }
+            let placeholders = fresh
+                .to_placeholders()
+                .map_err(|error| format!("微软身份转换失败：{error}"))?;
+            Ok((placeholders, line))
+        }
+        AccountKind::AuthlibInjector => {
+            let Some(Credentials::AuthlibInjector(session)) = store.credentials(&chosen.id) else {
+                return Err(format!(
+                    "账户 {} 的第三方凭据缺失或类型不符",
+                    chosen.display_name()
+                ));
+            };
+            let placeholders = session
+                .to_placeholders()
+                .map_err(|error| format!("第三方身份转换失败：{error}"))?;
+            Ok((placeholders, line))
+        }
+    }
+}
+
+/// `SessionHandle` → 日志页的三种结局。
+pub fn outcome_of(handle: &unlucky_core::launch::SessionHandle) -> LogOutcome {
+    if handle.exit.silent_failure.is_some() {
+        LogOutcome::SilentFail
+    } else if handle.succeeded() {
+        LogOutcome::Ok
+    } else {
+        LogOutcome::Crashed
+    }
+}
diff --git a/crates/presenter/src/host/install.rs b/crates/presenter/src/host/install.rs
new file mode 100644
index 0000000..a8f404d
--- /dev/null
+++ b/crates/presenter/src/host/install.rs
@@ -0,0 +1,283 @@
+//! 安装：新建实例向导 / 下载页「安装」→ core 安装管线 → 登记实例。
+//!
+//! 与 CLI `ull install` 同序：`RemoteSource::resolve → InstallPlan::build → execute → register`。
+//! Forge/NeoForge 多一段 installer processors（[`super::install_processors`]）：
+//! `ProcessorPlan::build → 依赖库下载 → 选 Java → 串行 java -cp`，**跑完才写版本 JSON**。
+//! 差异只在线程模型：进度经 [`super::job::HostTask::Install`] 回流（文件计数 + 字节 + 速度/ETA），
+//! 且整段跑在后台线程里（`block_on` 不占 UI 线程）。
+//!
+//! 加载器范围：原版 + Fabric/Quilt/Forge/NeoForge（四家，与 CLI 对齐）。OptiFine/LiteLoader
+//! 两家 core 侧都还没有安装管线，仍在 GUI 里显式拒装并说清去哪装。
+//! 失败一律落 `.ULL/logs/install.log`（[`super::install_journal`]），文案里带日志路径。
+
+use std::path::PathBuf;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+
+use unlucky_core::game::install::{InstallError, InstallReport};
+
+use crate::dto::{CreateRequest, InstallStage, LoaderKind};
+use crate::toast::{Toast, ToastKind};
+
+use super::env::HostEnv;
+use super::install_journal::Journal;
+use super::install_processors;
+use super::job::{spawn, HostTask, JobSender};
+use super::meter::Meter;
+
+mod routes;
+
+use routes::{install_loader, install_vanilla};
+
+/// 文件级并发上限（与 CLI 同值：16 路压满带宽又不至于打爆镜像）。
+pub const CONCURRENCY: usize = 16;
+
+/// 用户取消的稳定文案。
+///
+/// 三件事一句话说清（D21 的口径：半成品不许冒充成品，断点材料不留在半截状态）：
+/// ① 怎么停的（`execute_with_cancel` 不再起新文件，在飞的那个就地掐断）；
+/// ② 什么被留着（**已经下完**的文件，重装续用）；
+/// ③ 什么一定没发生（实例未登记、版本清单没落盘；在飞文件的 `.ullpart` 由 `PartFile::Drop` 清掉）。
+pub const CANCELLED: &str =
+    "已取消：剩下的文件没有开始下载，已下好的文件保留（重装续用），实例未登记";
+
+/// 一次安装任务的运行上下文（后台线程内一路传下去，免得每个函数排七八个参数）。
+struct Job<'a> {
+    env: &'a HostEnv,
+    tx: &'a JobSender,
+    meter: &'a Arc>,
+    cancel: &'a Arc,
+    journal: &'a Journal,
+}
+
+impl Job<'_> {
+    /// processor 段的进度出口（同一套 channel/meter/journal）。
+    fn reporter(&self) -> install_processors::Reporter<'_> {
+        install_processors::Reporter {
+            tx: self.tx,
+            meter: self.meter,
+            journal: self.journal,
+        }
+    }
+}
+
+/// 加载器徽标（`原版` / `Fabric 0.16.5`）。
+pub fn loader_label(kind: LoaderKind, version: &str) -> String {
+    if kind == LoaderKind::Vanilla || version.trim().is_empty() {
+        kind.label().to_string()
+    } else {
+        format!("{} {}", kind.label(), version)
+    }
+}
+
+/// GUI 侧支持的加载器（五选：原版 + 四家加载器，与 CLI 的 `--loader` 词表一致）。
+///
+/// 写成穷举 `matches!` 而不是 `true`：将来 core 加了第六种加载器，这里默认拒绝，
+/// 由 [`unsupported_reason`] 给出明确说法，而不是让它走进不属于它的安装分支。
+pub fn supported(kind: LoaderKind) -> bool {
+    matches!(
+        kind,
+        LoaderKind::Vanilla
+            | LoaderKind::Fabric
+            | LoaderKind::Quilt
+            | LoaderKind::Forge
+            | LoaderKind::NeoForge
+    )
+}
+
+/// 不支持的加载器 → 给用户的可执行建议。
+pub fn unsupported_reason(kind: LoaderKind) -> String {
+    format!(
+        "{} 还没有接入安装管线（目前支持原版 + Fabric/Quilt/Forge/NeoForge）；请先在实例页导入已有版本，或换成受支持的加载器。",
+        kind.label()
+    )
+}
+
+/// 后台安装（向导提交 / 下载页行内安装共用）。
+///
+/// `epoch` 是本次任务的代次（[`super::CoreHost`] 的 `install_epoch`）：它随每条进度回流，
+/// 让 host 丢掉「已被取消 / 被下一轮顶掉」的旧任务的后续事件。
+pub fn spawn_install(
+    env: HostEnv,
+    tx: JobSender,
+    request: CreateRequest,
+    cancel: Arc,
+    epoch: u64,
+) {
+    spawn("install", move || {
+        let meter = Arc::new(std::sync::Mutex::new(Meter::new(&request, epoch)));
+        let journal = Journal::open(&env);
+        journal.line(&format!(
+            "—— 开始安装 {}（{} {}）——",
+            request.instance_name(),
+            loader_label(request.loader, ""),
+            request.version
+        ));
+        let job = Job {
+            env: &env,
+            tx: &tx,
+            meter: &meter,
+            cancel: &cancel,
+            journal: &journal,
+        };
+        let result = run(&job, &request);
+        let mut progress = meter
+            .lock()
+            .map(|guard| guard.progress.clone())
+            .unwrap_or_else(|_| Meter::new(&request, epoch).progress);
+        match result {
+            Ok(name) => {
+                journal.line(&format!("完成：实例 {name} 已登记"));
+                progress.stage = InstallStage::Done;
+                progress.files_done = progress.files_total;
+                progress.message = format!("已安装 {name}（{}）", progress.loader);
+                let _ = tx.send(HostTask::InstallDone {
+                    progress: Box::new(progress),
+                    result: Ok(name),
+                    epoch,
+                });
+                let _ = tx.send(HostTask::Toast(Box::new(Toast {
+                    id: 0,
+                    kind: ToastKind::Success,
+                    text: "安装完成，实例已登记".to_string(),
+                    remaining_ms: 0,
+                })));
+            }
+            Err(reason) => {
+                let cancelled = reason == CANCELLED;
+                progress.stage = if cancelled {
+                    InstallStage::Cancelled
+                } else {
+                    InstallStage::Failed
+                };
+                // 失败文案带上日志路径：面板只有一行、Toast 4 秒就消失，
+                // 装日志是用户事后能自己回看的唯一渠道（进度板之外）。
+                let text = if cancelled {
+                    journal.line(CANCELLED);
+                    reason
+                } else {
+                    journal.line(&format!("安装未完成：{reason}"));
+                    format!("{reason}（日志：{}）", journal.path().display())
+                };
+                progress.message.clone_from(&text);
+                let _ = tx.send(HostTask::InstallDone {
+                    progress: Box::new(progress),
+                    result: Err(text),
+                    epoch,
+                });
+            }
+        }
+    });
+}
+
+/// 真安装（同步跑完，调用方在后台线程里）。
+fn run(job: &Job<'_>, request: &CreateRequest) -> Result {
+    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..22f00bf
--- /dev/null
+++ b/crates/presenter/src/host/install/routes.rs
@@ -0,0 +1,183 @@
+//! 两条安装路线（原版 / 加载器）——M105 从 `install.rs` 搬出，守 400 行硬线。
+//!
+//! 搬移是**纯搬移**：函数体一行没改，只多了本文件自己的 `use`。
+//! 父模块（`install`）的私有项对子模块可见，所以 `Job` / `CANCELLED` / `job_error` /
+//! `ensure_complete` / `sink_for` 一律不重新导出，直接用。
+
+use std::sync::atomic::Ordering;
+use std::sync::Arc;
+
+use unlucky_core::addon::loader::{
+    LoaderInstallPlan, LoaderKind as CoreLoaderKind, LoaderPlanInput, LoaderSource,
+};
+use unlucky_core::download::blocking::block_on;
+use unlucky_core::download::cache::now_ms;
+use unlucky_core::download::DownloadEngine;
+use unlucky_core::game::arguments::Environment;
+use unlucky_core::game::install::{execute_with_cancel, InstallPlan, PlanInput, RemoteSource};
+
+use crate::dto::{CreateRequest, InstallStage, LoaderKind};
+
+use super::super::install_processors::{self, StageInput};
+use super::super::meter::sink_for;
+use super::{ensure_complete, install_error, job_error, Job, CANCELLED, CONCURRENCY};
+
+/// 原版安装（`resolve → plan → [prefetch 资源索引] → execute`）。
+pub(super) fn install_vanilla(
+    job: &Job<'_>,
+    engine: &DownloadEngine,
+    request: &CreateRequest,
+) -> Result {
+    let env = job.env;
+    let version = request.version.trim();
+    let meta_cache = env.layout.meta_cache();
+    let now = now_ms();
+    let sink = sink_for(job.tx.clone(), Arc::clone(job.meter));
+    block_on(async {
+        let source = RemoteSource::new(engine, &env.game, &meta_cache, now);
+        let resolved = source.resolve(version).await.map_err(install_error)?;
+        let fetched = match resolved
+            .asset_index
+            .as_ref()
+            .filter(|index| index.url.is_some())
+        {
+            Some(reference) => {
+                let (index, bytes) = source.asset_index(reference).await.map_err(install_error)?;
+                Some((index, env.game.asset_index(&reference.id), bytes))
+            }
+            None => None,
+        };
+        let mut plan = InstallPlan::build(PlanInput {
+            layout: &env.game,
+            version_id: version,
+            resolved: &resolved,
+            asset_index: fetched.as_ref().map(|(index, _, _)| index),
+            environment: &Environment::host(),
+        })
+        .map_err(|error| error.to_string())?;
+        if let Some((_, dest, bytes)) = fetched {
+            plan.prefetch(dest, bytes);
+        }
+        if !plan.is_installable() {
+            return Err(format!(
+                "版本 {version} 装不全：{}",
+                plan.warnings.join("；")
+            ));
+        }
+        let (bytes_total, _) = plan.total_bytes();
+        {
+            let mut guard = job.meter.lock().map_err(|_| "进度锁失效".to_string())?;
+            guard.progress.files_total = u64::try_from(plan.file_count()).unwrap_or(u64::MAX);
+            guard.progress.bytes_total = bytes_total;
+            guard.stage(
+                InstallStage::Downloading,
+                &format!("开始下载 {} 个文件…", plan.file_count()),
+            );
+        }
+        if job.cancel.load(Ordering::SeqCst) {
+            return Err(CANCELLED.to_string());
+        }
+        let report = execute_with_cancel(
+            engine,
+            &plan,
+            CONCURRENCY,
+            Some(sink),
+            Some(job.cancel.as_ref()),
+        )
+        .await
+        .map_err(|error| job_error(job, error))?;
+        ensure_complete(&report)?;
+        Ok::(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(),
+        vanilla_installed: env.game.is_version_installed(version),
+    });
+    if plan.vanilla_install_needed {
+        let mut vanilla = request.clone();
+        vanilla.loader = LoaderKind::Vanilla;
+        install_vanilla(job, engine, &vanilla)?;
+    }
+    // 两段（加载器库 + 处理器依赖库）在动手前一次预记账：进度条只走一条单调曲线，
+    // 处理器依赖库下完不会先满格、再在加载器库开始时回落到一半。
+    {
+        let mut guard = job.meter.lock().map_err(|_| "进度锁失效".to_string())?;
+        let (bytes, _) = plan.install.total_bytes();
+        guard.expect(plan.files().len(), bytes);
+    }
+    // Forge/NeoForge：installer processors 必须先跑完，`execute` 才允许写版本 JSON。
+    if release.requires_installer() {
+        let input = StageInput {
+            kind: release.kind,
+            mc_version: &release.mc_version,
+            version_id: &release.version_id,
+            profile: release.install_profile.as_ref(),
+            installer: release.installer.as_deref(),
+            installed: env.game.is_version_installed(&release.version_id),
+        };
+        // `None` = 这一版不需要跑处理器（版本 JSON 已在盘上 / profile 没有 client 侧步骤），
+        // 进度与日志都由处理器段自己写全，这里只消费返回值。
+        let _ = install_processors::stage(
+            env,
+            engine,
+            &input,
+            &install_processors::CORE,
+            &job.reporter(),
+            job.cancel,
+        )?;
+    }
+    {
+        let mut guard = job.meter.lock().map_err(|_| "进度锁失效".to_string())?;
+        guard.stage(
+            InstallStage::Downloading,
+            &format!("开始下载加载器库（{} 个文件）…", plan.files().len()),
+        );
+    }
+    if job.cancel.load(Ordering::SeqCst) {
+        return Err(CANCELLED.to_string());
+    }
+    let sink = sink_for(job.tx.clone(), Arc::clone(job.meter));
+    let report = block_on(async {
+        execute_with_cancel(
+            engine,
+            &plan.install,
+            CONCURRENCY,
+            Some(sink),
+            Some(job.cancel.as_ref()),
+        )
+        .await
+    })
+    .map_err(|error| job_error(job, error))?;
+    ensure_complete(&report)?;
+    Ok(release.version_id)
+}
diff --git a/crates/presenter/src/host/install_journal.rs b/crates/presenter/src/host/install_journal.rs
new file mode 100644
index 0000000..37d3776
--- /dev/null
+++ b/crates/presenter/src/host/install_journal.rs
@@ -0,0 +1,79 @@
+//! 安装过程的可回溯日志（`.ULL/logs/install.log`，一轮一行）。
+//!
+//! 起因（M45）：Forge/NeoForge 装失败时，GUI 只有一行 Toast，processor 的 stderr 尾部
+//! 与「哪一步挂了」在面板一关就没了。这里把安装过程按行追加到 `.ULL/logs/`
+//! （与 `auth.jsonl` 同一分区），失败文案里带上日志路径，用户能自己回看。
+//!
+//! 三条纪律（与 auth 日志同源）：
+//! 1. **只追加**，不轮转、不截断（体积由「一行一条、只记诊断字段」控制）；
+//! 2. **只记诊断字段**：阶段、processor 坐标、退出码、已脱敏的 stderr 尾部（core 侧脱敏）；
+//! 3. **写盘尽力而为**：开不了文件就静默跳过，绝不让日志失败连累安装。
+
+use std::io::Write;
+use std::path::{Path, PathBuf};
+
+use unlucky_core::launch::time;
+
+use super::env::HostEnv;
+
+/// 日志文件名（在 `.ULL/logs/` 下）。
+pub const INSTALL_LOG_FILE: &str = "install.log";
+
+/// 一轮安装的日志句柄（`Clone` 很便宜：只有一个路径）。
+#[derive(Debug, Clone)]
+pub struct Journal {
+    path: PathBuf,
+}
+
+impl Journal {
+    /// 按数据根打开（`logs/` 不存在就补建；建不出来只是没有日志）。
+    pub fn open(env: &HostEnv) -> Self {
+        let dir = env.layout.logs();
+        let _ = std::fs::create_dir_all(&dir);
+        Self {
+            path: dir.join(INSTALL_LOG_FILE),
+        }
+    }
+
+    /// 日志路径（失败文案里给用户看）。
+    pub fn path(&self) -> &Path {
+        &self.path
+    }
+
+    /// 追加一行（自动补 RFC3339 时间戳；写失败静默）。
+    pub fn line(&self, text: &str) {
+        let Ok(mut file) = std::fs::OpenOptions::new()
+            .create(true)
+            .append(true)
+            .open(&self.path)
+        else {
+            return;
+        };
+        let _ = writeln!(
+            file,
+            "[{}] {text}",
+            time::format_rfc3339_millis(time::now())
+        );
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn lines_are_appended_with_a_timestamp() {
+        let root = std::env::temp_dir().join(format!("ull-install-journal-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&root);
+        let env = HostEnv::at_root(&root);
+        let journal = Journal::open(&env);
+        journal.line("第一行");
+        journal.line("第二行");
+        let text = std::fs::read_to_string(journal.path()).expect("日志存在");
+        assert!(text.contains("第一行") && text.contains("第二行"), "{text}");
+        assert_eq!(text.lines().count(), 2);
+        assert!(text.starts_with("[2"), "带时间戳：{text}");
+        assert_eq!(journal.path(), env.layout.logs().join(INSTALL_LOG_FILE));
+        std::fs::remove_dir_all(&root).ok();
+    }
+}
diff --git a/crates/presenter/src/host/install_processors.rs b/crates/presenter/src/host/install_processors.rs
new file mode 100644
index 0000000..8e47554
--- /dev/null
+++ b/crates/presenter/src/host/install_processors.rs
@@ -0,0 +1,382 @@
+//! Forge / NeoForge 的 installer processors 段（M45：GUI 与 CLI 行为对齐）。
+//!
+//! 顺序与 CLI `ull install --loader forge` 完全一致（`crates/cli/src/commands/install/
+//! loader_processors.rs`），只是把进度接到 GUI 的回流通道上：
+//!
+//! ```text
+//! ProcessorPlan::build（纯计算：变量表 + 每步 java -cp + 依赖库清单）
+//!   → download_libraries（M27 引擎；进度回流 HostTask::Install）
+//!   → select_java（M33 解析链：托管 > JAVA_HOME > PATH > 扫盘）
+//!   → run（串行 java -cp；每步一条面板文案 + 一行装日志）
+//! ```
+//!
+//! 四条硬约束（与 CLI 同源，GUI 侧一条都不放宽）：
+//!
+//! 1. **processors 跑完才允许写版本 JSON**：版本清单存在 = 这版装完了，抢在 processors
+//!    前写会留下启动必崩却被报成"已安装"的实例（顺序由 `install_loader` 保证）；
+//! 2. **幂等**：版本 JSON 已在盘上 = 上一轮跑完了，整段跳过；
+//! 3. **取消在阶段边界生效**：处理器阶段是原子段（串行外调 java，进程内没有取消钩子），
+//!    进入前与退出后各查一次 `cancel`；
+//! 4. **失败不静默**：结构化文案（带 `processor_*` 大类码）+ 装日志一行一条，由调用方
+//!    再补 Toast（`HostTask::InstallDone` 的既有通路）。
+//!
+//! 执行后端走 [`Backend`]：真实实现 [`CoreBackend`] 直接转调 core，单测注入 fake，
+//! 因此「计划怎么组、Java 找不到怎么说、依赖库下漏怎么报」都能在没有网络/没有 JDK
+//! 的机器上断言。
+
+use std::path::Path;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex};
+
+use unlucky_core::addon::loader::forge::InstallProfile;
+use unlucky_core::addon::loader::processors::{
+    self, ProcessorError, ProcessorPlan, ProcessorPlanInput, ProcessorRun, StepOutcome, StepSink,
+    StepStatus,
+};
+use unlucky_core::addon::loader::LoaderKind as CoreLoaderKind;
+use unlucky_core::download::blocking::block_on;
+use unlucky_core::download::DownloadEngine;
+use unlucky_core::game::arguments::Environment;
+use unlucky_core::game::install::{InstallReport, PlanFile, ProgressSink};
+use unlucky_core::game::java::{JavaRequirement, JavaRuntime};
+
+use crate::dto::InstallStage;
+
+use super::env::HostEnv;
+use super::install::{CANCELLED, CONCURRENCY};
+use super::install_journal::Journal;
+use super::job::{HostTask, JobSender};
+use super::meter::{sink_for, Meter};
+
+/// 真实后端（无状态，可以放静态里复用）。
+pub(super) const CORE: CoreBackend = CoreBackend;
+
+/// processors 段需要的输入（从 `LoaderRelease` 摘出来，便于单测构造）。
+pub(super) struct StageInput<'a> {
+    /// 加载器种类（补库时 maven 基址的兜底来源）。
+    pub kind: CoreLoaderKind,
+    /// 目标原版版本。
+    pub mc_version: &'a str,
+    /// loader 版本 id（依赖库落点 + 临时目录名）。
+    pub version_id: &'a str,
+    /// installer 里读出来的 install profile（`requires_installer` 为真时必须有）。
+    pub profile: Option<&'a InstallProfile>,
+    /// installer jar 的磁盘路径。
+    pub installer: Option<&'a Path>,
+    /// 版本 JSON 已在盘上 = 上一轮跑完了，整段跳过（幂等）。
+    pub installed: bool,
+}
+
+/// processors 段的执行后端（真实实现转调 core；单测注入 fake）。
+pub(super) trait Backend {
+    /// 下载 processor 依赖库（M27 引擎：镜像/健康度/退避/校验）。
+    fn download_libraries(
+        &self,
+        engine: &DownloadEngine,
+        files: &[PlanFile],
+        sink: Option,
+    ) -> 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..83ae946
--- /dev/null
+++ b/crates/presenter/src/host/install_processors_fixture.rs
@@ -0,0 +1,272 @@
+//! installer processors 段的单测夹具（拆文件守 400 行上限）。
+//!
+//! 不需要网络、不需要 JDK、不真的起 java：`Harness` 给一个临时数据根 + 进度通道，
+//! `Fake` 回放预置的下载/Java/执行结果并记录被调顺序与组出来的命令行。
+
+use std::cell::RefCell;
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
+use std::sync::mpsc::Receiver;
+use std::sync::{Arc, Mutex};
+
+use unlucky_core::addon::loader::forge::{InstallProfile, Processor};
+use unlucky_core::addon::loader::processors::{
+    ProcessorError, ProcessorPlan, ProcessorRun, StepOutcome, StepSink, StepStatus,
+};
+use unlucky_core::addon::loader::LoaderKind as CoreLoaderKind;
+use unlucky_core::download::{DownloadEngine, DownloadErrorKind};
+use unlucky_core::game::install::{
+    FileFailure, FileOutcome, FileStatus, InstallReport, PlanFile, ProgressSink,
+};
+use unlucky_core::game::java::{JavaOrigin, JavaRequirement, JavaRuntime};
+
+use super::{Backend, Reporter, StageInput};
+use crate::dto::{CreateRequest, LoaderKind};
+use crate::host::env::HostEnv;
+use crate::host::install_journal::Journal;
+use crate::host::job::{channel, HostTask, JobSender};
+use crate::host::meter::Meter;
+
+static SEQ: AtomicUsize = AtomicUsize::new(0);
+
+/// 一步的计划视图（序号 / 坐标 / 参数 / classpath 条数）。
+pub(super) type StepView = (usize, String, Vec, usize);
+
+/// 一段 cases 的公共环境：临时数据根 + 引擎 + 进度通道。
+pub(super) struct Harness {
+    dir: PathBuf,
+    pub(super) env: HostEnv,
+    pub(super) engine: DownloadEngine,
+    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,
+            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..dc22eed
--- /dev/null
+++ b/crates/presenter/src/host/install_processors_tests.rs
@@ -0,0 +1,213 @@
+//! host/install_processors.rs 的单测（拆文件守 400 行上限）。
+//!
+//! 夹具在 [`super::fixture`]：这里只断言「计划怎么组」「找不到 Java 怎么说」
+//! 「哪一步挂了怎么报」「进度文案长什么样」。
+
+use std::path::PathBuf;
+
+use unlucky_core::addon::loader::forge::InstallProfile;
+use unlucky_core::addon::loader::processors::{ProcessorError, StepStatus};
+use unlucky_core::addon::loader::LoaderKind as CoreLoaderKind;
+use unlucky_core::download::DownloadErrorKind;
+use unlucky_core::game::install::{FileFailure, FileOutcome, FileRole, FileStatus, InstallReport};
+use unlucky_core::game::java::JavaRequirement;
+
+use super::fixture::{input, installer, outcome, profile, Fake, Harness};
+use super::{diagnostic, java_missing, libraries_failed, stage, step_line, StageInput};
+
+#[test]
+fn step_line_names_the_step_and_marks_the_outcome() {
+    let executed = step_line(&outcome(StepStatus::Executed), 9);
+    assert_eq!(
+        executed,
+        "installer 处理器 3/9：net.minecraftforge:installertools:1.3.0（1234 ms）"
+    );
+    let skipped = step_line(&outcome(StepStatus::Skipped), 9);
+    assert!(skipped.contains("产物已就绪"), "{skipped}");
+}
+
+#[test]
+fn diagnostic_keeps_the_stable_code_and_the_hint() {
+    let failed = ProcessorError::failed("net.minecraftforge:installertools:1.3.0", "1", "boom")
+        .with_hint("确认 Java 版本与磁盘权限");
+    let text = diagnostic(&failed);
+    assert!(text.contains("processor_failed"), "{text}");
+    assert!(text.contains("退出码 1"), "{text}");
+    assert!(text.contains("boom"), "stderr 尾部要留：{text}");
+    assert!(text.contains("建议：确认 Java 版本"), "{text}");
+
+    let plan = diagnostic(&ProcessorError::plan("install profile 缺 `jar`"));
+    assert!(plan.contains("processor_plan"), "{plan}");
+}
+
+#[test]
+fn java_missing_points_at_the_java_page() {
+    let managed = PathBuf::from("/tmp/.ULL/java");
+    let text = java_missing(&JavaRequirement::table(21, None), &managed);
+    assert!(text.contains("Java 21+"), "{text}");
+    assert!(text.contains("Java」页"), "{text}");
+    assert!(text.contains("JAVA_HOME"), "{text}");
+    assert!(text.contains(&managed.display().to_string()), "{text}");
+}
+
+#[test]
+fn libraries_failed_lists_at_most_three() {
+    let files: Vec = (0..4)
+        .map(|index| FileOutcome {
+            role: FileRole::Library,
+            name: format!("lib{index}.jar"),
+            dest: PathBuf::from(format!("lib{index}.jar")),
+            status: FileStatus::Failed,
+            bytes: 0,
+            source: None,
+            failure: Some(FileFailure {
+                kind: DownloadErrorKind::Network,
+                message: "连接超时".to_string(),
+            }),
+        })
+        .collect();
+    let report = InstallReport {
+        files,
+        version_json: None,
+        warnings: Vec::new(),
+    };
+    let text = libraries_failed(&report);
+    assert!(text.contains("4 个失败，共 4 个"), "{text}");
+    assert!(text.contains("lib0.jar"), "{text}");
+    assert!(!text.contains("lib3.jar"), "最多列三条：{text}");
+}
+
+#[test]
+fn stage_skips_when_the_version_json_is_already_there() {
+    let h = Harness::new();
+    let installer = installer();
+    let profile = profile();
+    let mut input = input(&profile, &installer);
+    input.installed = true;
+    let fake = Fake::new();
+    let result = stage(&h.env, &h.engine, &input, &fake, &h.reporter(), &h.cancel);
+    assert!(matches!(result, Ok(None)));
+    assert!(fake.calls().is_empty(), "已装完就不该再动网络/Java");
+    assert!(h.log().contains("跳过 installer processors"), "{}", h.log());
+}
+
+#[test]
+fn stage_skips_an_empty_processor_list() {
+    let h = Harness::new();
+    let installer = installer();
+    let profile = InstallProfile::default();
+    let input = input(&profile, &installer);
+    let fake = Fake::new();
+    let result = stage(&h.env, &h.engine, &input, &fake, &h.reporter(), &h.cancel);
+    assert!(matches!(result, Ok(None)), "没有 processor 就没这段");
+    assert!(fake.calls().is_empty());
+}
+
+#[test]
+fn stage_reports_missing_installer_metadata() {
+    let h = Harness::new();
+    let input = StageInput {
+        kind: CoreLoaderKind::Forge,
+        mc_version: "1.20.1",
+        version_id: "1.20.1-forge-47.2.0",
+        profile: None,
+        installer: None,
+        installed: false,
+    };
+    let fake = Fake::new();
+    let err = stage(&h.env, &h.engine, &input, &fake, &h.reporter(), &h.cancel).unwrap_err();
+    assert!(err.contains("install profile"), "{err}");
+    assert!(h.log().contains("失败："), "{}", h.log());
+}
+
+#[test]
+fn stage_builds_the_command_line_from_the_install_profile() {
+    let h = Harness::new();
+    let installer = installer();
+    let profile = profile();
+    let input = input(&profile, &installer);
+    let fake = Fake::new();
+    let run = stage(&h.env, &h.engine, &input, &fake, &h.reporter(), &h.cancel)
+        .expect("stage 成功")
+        .expect("应当真的跑了 processors");
+    assert_eq!(run.executed(), 1);
+    let steps = fake.steps();
+    assert_eq!(steps.len(), 1);
+    let (index, label, args, classpath) = &steps[0];
+    assert_eq!(*index, 1);
+    assert_eq!(label, "net.minecraftforge:installertools:1.3.0");
+    assert_eq!(args, &vec!["--task".to_string(), "MCP_DATA".to_string()]);
+    assert_eq!(*classpath, 1, "jar 自己不在 -cp 里（拼命令行时才补）");
+    assert_eq!(fake.calls(), vec!["libraries", "java", "run"]);
+    let messages = h.messages();
+    assert!(
+        messages.iter().any(|m| m.contains("installer 处理器 1/1")),
+        "面板要看到当前处理器：{messages:?}"
+    );
+    assert!(
+        messages
+            .last()
+            .is_some_and(|m| m.contains("正在写入版本清单")),
+        "{messages:?}"
+    );
+    assert!(
+        h.log().contains("processors 完成：执行 1 步"),
+        "{}",
+        h.log()
+    );
+}
+
+#[test]
+fn stage_fails_loudly_without_a_usable_java() {
+    let h = Harness::new();
+    let installer = installer();
+    let profile = profile();
+    let input = input(&profile, &installer);
+    let mut fake = Fake::new();
+    fake.java = None;
+    let err = stage(&h.env, &h.engine, &input, &fake, &h.reporter(), &h.cancel).unwrap_err();
+    assert!(err.contains("Java"), "{err}");
+    assert!(err.contains("托管目录"), "{err}");
+    assert_eq!(
+        fake.calls(),
+        vec!["libraries", "java"],
+        "没 Java 就不该起进程"
+    );
+    assert!(h.log().contains("失败："), "{}", h.log());
+}
+
+#[test]
+fn stage_fails_loudly_when_a_processor_exits_nonzero() {
+    let h = Harness::new();
+    let installer = installer();
+    let profile = profile();
+    let input = input(&profile, &installer);
+    let mut fake = Fake::new();
+    fake.run_error = Some(ProcessorError::failed(
+        "net.minecraftforge:installertools:1.3.0",
+        "1",
+        "java.lang.NoSuchMethodError",
+    ));
+    let err = stage(&h.env, &h.engine, &input, &fake, &h.reporter(), &h.cancel).unwrap_err();
+    assert!(err.contains("processor_failed"), "{err}");
+    assert!(err.contains("NoSuchMethodError"), "{err}");
+    let log = h.log();
+    assert!(log.contains("失败："), "{log}");
+    assert!(log.contains("NoSuchMethodError"), "日志要能回溯：{log}");
+}
+
+#[test]
+fn stage_reports_incomplete_library_downloads() {
+    let h = Harness::new();
+    let installer = installer();
+    let profile = profile();
+    let input = input(&profile, &installer);
+    let mut fake = Fake::new();
+    fake.libraries_ok = false;
+    let err = stage(&h.env, &h.engine, &input, &fake, &h.reporter(), &h.cancel).unwrap_err();
+    assert!(err.contains("依赖库没下全"), "{err}");
+    assert!(err.contains("连接超时"), "{err}");
+    assert_eq!(fake.calls(), vec!["libraries"], "库没下全就别去选 Java");
+    let progress = h.meter.lock().expect("进度锁").progress.clone();
+    assert!(progress.files_total >= 2, "依赖库要计入文件总数");
+}
diff --git a/crates/presenter/src/host/install_tests.rs b/crates/presenter/src/host/install_tests.rs
new file mode 100644
index 0000000..06dacbd
--- /dev/null
+++ b/crates/presenter/src/host/install_tests.rs
@@ -0,0 +1,218 @@
+//! host/install.rs 的单测（拆文件守 400 行上限）。
+
+use std::path::PathBuf;
+use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
+use std::sync::{Arc, Mutex};
+
+use unlucky_core::game::install::{FileOutcome, FileRole, FileStatus};
+
+use super::{loader_label, run, supported, unsupported_reason, Job};
+use crate::dto::{CreateRequest, LoaderKind};
+use crate::host::env::HostEnv;
+use crate::host::install_journal::Journal;
+use crate::host::job::{channel, JobSender};
+use crate::host::meter::Meter;
+
+static SEQ: AtomicUsize = AtomicUsize::new(0);
+
+/// 一个装在临时根里的任务上下文（只走「联网前就返回」的用例）。
+struct Fixture {
+    dir: PathBuf,
+    env: HostEnv,
+    tx: JobSender,
+    meter: Arc>,
+    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,
+    ] {
+        assert!(supported(kind), "{} 应当受支持", kind.label());
+    }
+    // 这两家 core 侧还没有安装管线，仍然显式拒装并说清去哪装。
+    for kind in [LoaderKind::OptiFine, LoaderKind::LiteLoader] {
+        assert!(!supported(kind), "{} 不该被当成可装", kind.label());
+        let reason = unsupported_reason(kind);
+        assert!(reason.contains(kind.label()), "{reason}");
+        assert!(reason.contains("还没有接入"), "{reason}");
+    }
+}
+
+#[test]
+fn forge_install_is_no_longer_refused_at_the_door() {
+    // 旧文案是把用户赶去终端跑 `ull install`；M45 之后 GUI 与 CLI 同一条路径。
+    assert!(supported(LoaderKind::Forge));
+    assert!(supported(LoaderKind::NeoForge));
+    assert_eq!(loader_label(LoaderKind::Forge, "47.2.0"), "Forge 47.2.0");
+    assert_eq!(
+        loader_label(LoaderKind::NeoForge, "21.1.80"),
+        "NeoForge 21.1.80"
+    );
+}
+
+#[test]
+fn meter_counts_files_and_skips_skipped_bytes() {
+    let request = CreateRequest {
+        version: "1.20.4".to_string(),
+        loader: LoaderKind::Fabric,
+        loader_version: "0.16.5".to_string(),
+        name: "生存".to_string(),
+    };
+    let mut meter = Meter::new(&request, 1);
+    assert_eq!(meter.progress.loader, "Fabric 0.16.5");
+    assert_eq!(meter.progress.instance, "生存");
+    meter.progress.files_total = 2;
+
+    let mut outcome = FileOutcome {
+        role: FileRole::Library,
+        name: "a.jar".to_string(),
+        dest: PathBuf::from("a.jar"),
+        status: FileStatus::Downloaded,
+        bytes: 100,
+        source: Some("bmclapi".to_string()),
+        failure: None,
+    };
+    meter.note(&outcome);
+    assert_eq!(meter.progress.files_done, 1);
+    assert_eq!(meter.progress.bytes_done, 100);
+
+    outcome.status = FileStatus::Skipped;
+    outcome.bytes = 500;
+    meter.note(&outcome);
+    assert_eq!(meter.progress.files_done, 2);
+    assert_eq!(meter.progress.bytes_done, 100, "跳过的文件不计入已下载字节");
+    assert!((meter.progress.ratio() - 1.0).abs() < f32::EPSILON);
+}
+
+#[test]
+fn empty_version_is_rejected_before_network() {
+    let request = request(LoaderKind::Vanilla, "");
+    let fixture = Fixture::new(&request);
+    let err = run(&fixture.job(), &request).unwrap_err();
+    assert!(err.contains("没有选择版本"), "{err}");
+}
+
+#[test]
+fn unsupported_loader_is_rejected_before_network() {
+    let request = request(LoaderKind::OptiFine, "1.20.1");
+    let fixture = Fixture::new(&request);
+    let err = run(&fixture.job(), &request).unwrap_err();
+    assert!(err.contains("还没有接入"), "{err}");
+}
diff --git a/crates/presenter/src/host/java.rs b/crates/presenter/src/host/java.rs
new file mode 100644
index 0000000..71229bb
--- /dev/null
+++ b/crates/presenter/src/host/java.rs
@@ -0,0 +1,304 @@
+//! Java 页：四家发行版 + 回退链可视化 + 本地运行时 + 托管 JDK 安装。
+//!
+//! 回退链的两态：
+//! - **计划链**（还没装）：按生效顺序铺一排「待尝试」，让用户先看清会按什么顺序找；
+//! - **真实链**（装过一次/装失败）：`core::game::java::ChainLog` 的每跳结局与原因。
+//!
+//! 安装走 `java::install`（core 自己跑回退链），host 只负责把 `ChainLog` 翻成 DTO。
+
+use unlucky_core::game::java::probe::JavaOrigin;
+use unlucky_core::game::java::source::ChainLog;
+use unlucky_core::game::java::{self, JdkVendor};
+
+use crate::dto::{JavaChainOutcome, JavaChainStep, JavaPageView, JavaRuntimeView, JavaVendorView};
+
+use super::env::HostEnv;
+use super::job::{spawn, HostTask, JobSender};
+
+/// 托管 JDK 的默认目标大版本（D13 基准 JDK17）。
+pub const DEFAULT_JDK_MAJOR: u32 = 17;
+
+/// 该装哪个大版本：取第一个实例版本的要求，没有实例就给 17。
+pub fn target_major(env: &HostEnv) -> u32 {
+    let profiles = super::game::profiles(env);
+    profiles
+        .profiles
+        .first()
+        .map(|profile| {
+            java::requirement_for_version(&env.game, &profile.version_id)
+                .minimum
+                .max(8)
+        })
+        .unwrap_or(DEFAULT_JDK_MAJOR)
+}
+
+/// 四家发行版的展示行（镜像与吞吐口径与 CLI `ull java vendors` 一致）。
+pub fn vendors(env: &HostEnv, installed_vendors: &[String]) -> Vec {
+    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(),
+    }
+}
+
+/// 本地运行时（托管 / 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..74b497c
--- /dev/null
+++ b/crates/presenter/src/host/job.rs
@@ -0,0 +1,198 @@
+//! 后台任务的回流消息：`HostTask` 是唯一「线程 → host」的载荷。
+//!
+//! 线程只做 core 调用（网络/磁盘），产出的都是 `crate::dto` 的 DTO；
+//! host 的 `tick` 把它们翻成 [`crate::dto::CoreEvent`]。
+//! 这样「跨线程传的是什么」在一处看全，也不会出现半成品领域类型漏回 UI。
+
+use std::sync::mpsc::{Receiver, Sender};
+
+use crate::dto::{
+    // 主线（M109 ContentResults / M105 LoaderKind / M113 PackEvent）与 M114 的账户轨并集。
+    AccountView,
+    AuthlibLoginView,
+    ContentResults,
+    DeviceLoginView,
+    DiagnosisReport,
+    InstallProgressView,
+    InstanceId,
+    InstanceRuntime,
+    JavaPageView,
+    LaunchFinished,
+    LiveLogBatch,
+    LoaderKind,
+    LogLine,
+    LogOutcome,
+    LogSession,
+    NoticeView,
+    PackEvent,
+    SessionId,
+    SkinImage,
+    VersionSummary,
+};
+use crate::toast::Toast;
+
+/// 后台任务 → host 的消息。
+#[derive(Debug, Clone, PartialEq)]
+pub enum HostTask {
+    /// 版本清单（下载页）
+    Versions(Result, String>),
+    /// 加载器版本清单（下载页「安装选项」的下拉）
+    LoaderVersions {
+        /// 加载器种类
+        kind: LoaderKind,
+        /// 目标原版版本（缓存键的一部分，回传原样）
+        mc_version: String,
+        /// `Ok(最新在前)` / `Err(人读原因)`
+        result: Result, String>,
+    },
+    /// 内容库检索（M109；`Err` = 一句人读原因）
+    Content(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,
+    },
+    /// 安装进度（高频，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),
+}
+
+/// 后台线程用的发送端（`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}"))
+}
+
+/// 人读一行「启动结束」。
+pub fn launch_summary(outcome: LogOutcome, exit_code: Option) -> String {
+    match outcome {
+        LogOutcome::Ok => "正常退出".to_string(),
+        LogOutcome::Crashed => match exit_code {
+            Some(code) => format!("崩溃（exit {code}）"),
+            None => "崩溃".to_string(),
+        },
+        LogOutcome::SilentFail => "静默失败（exit 0 但游戏没起来）".to_string(),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn channel_carries_tasks_across_threads() {
+        let (tx, rx) = channel();
+        let handle = spawn("test", move || {
+            tx.send(HostTask::Toast(Box::new(Toast {
+                id: 1,
+                kind: crate::toast::ToastKind::Info,
+                text: "hi".to_string(),
+                remaining_ms: 0,
+            })))
+            .expect("发送");
+        });
+        handle.join().expect("线程结束");
+        let task = rx.recv().expect("收到");
+        assert!(matches!(task, HostTask::Toast(toast) if toast.text == "hi"));
+    }
+
+    #[test]
+    fn launch_summary_names_the_outcome() {
+        assert_eq!(launch_summary(LogOutcome::Ok, Some(0)), "正常退出");
+        assert_eq!(
+            launch_summary(LogOutcome::Crashed, Some(1)),
+            "崩溃（exit 1）"
+        );
+        assert!(launch_summary(LogOutcome::SilentFail, Some(0)).contains("静默"));
+    }
+}
diff --git a/crates/presenter/src/host/launch.rs b/crates/presenter/src/host/launch.rs
new file mode 100644
index 0000000..48b2175
--- /dev/null
+++ b/crates/presenter/src/host/launch.rs
@@ -0,0 +1,353 @@
+//! 启动全链：实例 → `LaunchRequest` → 子进程 → JSONL 事件流（GUI 版）。
+//!
+//! 与 CLI `ull launch` 同源同序（`core` 的 `game::resolve` / `arguments.expand` /
+//! `launch::adapter::build_request` / `Launcher::spawn`），差异只有两处：
+//! - **不阻塞 UI**：装配与等待都在后台线程里，进度/日志经 [`super::job::HostTask`] 回流；
+//! - **身份来自 GUI 选中的账户**（`AccountStore` → `AuthPlaceholders`），凭据只在
+//!   本模块内被读一次，绝不进 DTO。
+//!
+//! 停止：`kill_tree(pid)`（core 的三段式进程树回收），`finish()` 会照常收尾写索引。
+
+use std::path::PathBuf;
+
+use unlucky_core::game::arguments::Environment;
+use unlucky_core::game::install::instance::read_instance_config;
+use unlucky_core::game::isolation::{derive_game_dir, observe_mode, IsolationMode};
+use unlucky_core::game::{self, VersionJson};
+use unlucky_core::launch::adapter::{
+    self, AdapterOptions, AdapterWarning, LibraryInput, SnapshotInput,
+};
+use unlucky_core::launch::request::{JavaSelection, LaunchRequest, MemoryOptions};
+use unlucky_core::launch::time::{format_rfc3339_millis, now};
+use unlucky_core::launch::tree_kill;
+use unlucky_core::launch::{Launcher, LauncherConfig};
+use unlucky_core::platform::paths::ProcessEnv;
+
+use crate::dto::{
+    InstanceId, InstanceRuntime, LaunchFinished, LaunchStage, LoaderKind, LogOutcome, Progress,
+};
+
+use super::env::HostEnv;
+use super::job::{launch_summary, HostTask, JobSender};
+
+/// 启动器名（与 CLI `meta::LAUNCHER_NAME` 同值）。
+pub const LAUNCHER_NAME: &str = "Unlucky Launcher";
+
+/// 一次启动需要的实例信息。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct LaunchTarget {
+    /// 实例 id
+    pub id: InstanceId,
+    /// 实例名
+    pub name: String,
+    /// 绑定的版本 id
+    pub version_id: String,
+    /// 账户 id（`None` = 离线占位）
+    pub account: Option,
+}
+
+/// 选中并用起来的 Java（`summary` 给 UI 一行提示）。
+pub struct JavaPick {
+    /// 交给 adapter 的选择
+    pub selection: JavaSelection,
+    /// 人读一行
+    pub summary: String,
+}
+
+/// 选一个能用的 Java：托管 > JAVA_HOME > PATH（`core::game::java` 的探测与优先级）。
+pub fn pick_java(env: &HostEnv, version_id: &str) -> JavaPick {
+    let store = env.store();
+    let install_root = store
+        .doc()
+        .effective_str("java.installRoot")
+        .map(str::trim)
+        .filter(|text| !text.is_empty())
+        .map(PathBuf::from);
+    let roots = unlucky_core::game::java::location::scan_roots(
+        env.mode(),
+        &env.layout,
+        install_root.as_deref(),
+        env.platform,
+        &ProcessEnv,
+    );
+    let candidates = unlucky_core::game::java::candidates_in_roots(&roots);
+    let required = unlucky_core::game::java::requirement_for_version(&env.game, version_id);
+    let picked = unlucky_core::game::java::pick(&candidates, &required).cloned();
+    match picked {
+        Some(runtime) => {
+            let major = runtime
+                .major
+                .unwrap_or(unlucky_core::game::java::DEFAULT_MAJOR);
+            let summary = format!(
+                "Java {}（{}{}）",
+                runtime.version.clone().unwrap_or_else(|| major.to_string()),
+                runtime.origin.category(),
+                runtime
+                    .vendor
+                    .as_ref()
+                    .map(|vendor| format!(" · {vendor}"))
+                    .unwrap_or_default()
+            );
+            JavaPick {
+                selection: JavaSelection::new(runtime.binary, major, runtime.bits),
+                summary,
+            }
+        }
+        None => {
+            let binary = PathBuf::from(unlucky_core::game::java::java_binary_name());
+            let major = required.minimum;
+            JavaPick {
+                selection: JavaSelection::new(binary, major, 64),
+                summary: format!("PATH 上的 Java（未探测到版本，按 Java {major} 启动）"),
+            }
+        }
+    }
+}
+
+/// 装配 [`LaunchRequest`]（与 CLI `snapshot::prepare` 同序）。
+///
+/// # Errors
+///
+/// 版本 JSON 缺失/非法、继承链断裂、隔离派生失败时返回用户可读文案。
+pub fn build_request(
+    env: &HostEnv,
+    target: &LaunchTarget,
+) -> Result<(LaunchRequest, Vec), String> {
+    let version_id = target.version_id.clone();
+    let manifest_path = env.game.version_json(&version_id);
+    let text = std::fs::read_to_string(&manifest_path)
+        .map_err(|error| format!("读版本 JSON 失败 {}：{error}", manifest_path.display()))?;
+    let manifest =
+        VersionJson::from_json_str(&text).map_err(|error| format!("版本 JSON 非法：{error}"))?;
+    let source = |id: &str| -> Option {
+        std::fs::read_to_string(env.game.version_json(id))
+            .ok()
+            .and_then(|text| VersionJson::from_json_str(&text).ok())
+    };
+    let resolved =
+        game::resolve(&source, &manifest).map_err(|error| format!("解析继承链失败：{error}"))?;
+
+    let environment = Environment::host();
+    let expanded = resolved
+        .arguments
+        .as_ref()
+        .map(|arguments| arguments.expand(&environment))
+        .unwrap_or_default();
+
+    let mut libraries: Vec = Vec::new();
+    for library in resolved.libraries.as_deref().unwrap_or_default() {
+        if !library.applies(&environment) || library.native_classifier(&environment).is_some() {
+            continue;
+        }
+        let Ok(coordinate) = library.coordinate() else {
+            continue;
+        };
+        let path = if library.is_local() {
+            env.game.version_library(&version_id, &coordinate)
+        } else {
+            env.game.library(&coordinate)
+        };
+        libraries.push(LibraryInput::new(path, library.name.clone()));
+    }
+    let natives = unlucky_core::launch::natives::collect(
+        &env.game,
+        &version_id,
+        resolved.libraries.as_deref().unwrap_or_default(),
+        &environment,
+    );
+
+    let game_dir = run_dir(env, target)?;
+    let jar_id = resolved.jar.clone().unwrap_or_else(|| version_id.clone());
+    let assets_root = env.game.assets_dir();
+    let assets_index = resolved
+        .assets
+        .clone()
+        .or_else(|| resolved.asset_index.as_ref().map(|index| index.id.clone()));
+    let snapshot = SnapshotInput {
+        version_id: &version_id,
+        version_name: Some(&target.name),
+        version_type: None,
+        game_version: None,
+        main_class: resolved.main_class.as_deref(),
+        jvm_arguments: &expanded.jvm,
+        game_arguments: &expanded.game,
+        legacy_arguments: resolved.minecraft_arguments.as_deref(),
+        libraries: &libraries,
+        natives: &natives,
+        primary_jar: env.game.version_jar(&jar_id),
+        game_dir,
+        assets_index: assets_index.as_deref(),
+        natives_dir: env.game.natives_dir(&version_id),
+        library_dir: env.game.libraries_dir(),
+        assets_root: assets_root.clone(),
+        game_assets: assets_root,
+    };
+
+    let java = pick_java(env, &version_id);
+    let (auth, identity_line) = super::identity::resolve(env, target.account.as_deref())?;
+    let memory = env
+        .store()
+        .effective("java.default_memory_mb")
+        .and_then(serde_json::Value::as_u64)
+        .and_then(|value| u32::try_from(value).ok());
+    let options = AdapterOptions {
+        java: java.selection,
+        memory: MemoryOptions {
+            min_mb: None,
+            max_mb: memory,
+        },
+        auth,
+        launcher_name: LAUNCHER_NAME.to_string(),
+        launcher_version: env!("CARGO_PKG_VERSION").to_string(),
+        language: "zh-CN".to_string(),
+        ..AdapterOptions::strict()
+    };
+    let output = adapter::build_request(&snapshot, options);
+    let mut warnings: Vec = output.warnings.iter().map(describe_warning).collect();
+    warnings.push(java.summary);
+    warnings.push(identity_line);
+    let mut request = output.request;
+    request.instance.id = target.id.clone();
+    request.instance.name = target.name.clone();
+    Ok((request, warnings))
+}
+
+/// 派生运行目录（D20 覆盖链：实例 `isolation` > 全局 `instances.mode`）。
+fn run_dir(env: &HostEnv, target: &LaunchTarget) -> Result {
+    let global = super::game::global_mode(env);
+    let config = read_instance_config(&env.layout, &target.id)
+        .map_err(|error| format!("读实例设置失败：{error}"))?;
+    let derivation = derive_game_dir(&env.game, &target.version_id, global, config.as_ref(), None)
+        .map_err(|error| format!("隔离目录派生失败：{error}"))?;
+    if let Some(mut config) = config {
+        let at = format_rfc3339_millis(now());
+        if observe_mode(&mut config, &env.game, &at, derivation.isolation).unwrap_or(false) {
+            let _ =
+                unlucky_core::game::install::instance::write_instance_config(&env.layout, &config);
+        }
+    }
+    Ok(derivation.game_dir)
+}
+
+/// 起一次启动（后台线程；进度/日志/收尾全部走 `HostTask`）。
+pub fn start(env: HostEnv, tx: JobSender, target: LaunchTarget) {
+    let id = target.id.clone();
+    let tx_progress = tx.clone();
+    super::job::spawn("launch", move || {
+        let _ = tx_progress.send(HostTask::Runtime {
+            id: id.clone(),
+            runtime: InstanceRuntime::Busy {
+                stage: LaunchStage::Launch,
+                progress: Progress { done: 0, total: 1 },
+            },
+        });
+        let (request, warnings) = match build_request(&env, &target) {
+            Ok(ok) => ok,
+            Err(reason) => {
+                let _ = tx.send(HostTask::LaunchEnd(Box::new(LaunchFinished {
+                    id,
+                    session: String::new(),
+                    outcome: LogOutcome::Crashed,
+                    summary: format!("启动失败：{reason}"),
+                })));
+                return;
+            }
+        };
+        for warning in &warnings {
+            let _ = tx.send(HostTask::Notice(Box::new(crate::dto::NoticeView::new(
+                &format!("launch-warn:{}", target.id),
+                crate::dto::NoticeLevel::Info,
+                "启动提示",
+                warning,
+            ))));
+        }
+        let config = LauncherConfig::new(env.sessions_root())
+            .with_launcher(LAUNCHER_NAME, env!("CARGO_PKG_VERSION"));
+        let session = match Launcher::new(config).spawn(&request) {
+            Ok(session) => session,
+            Err(error) => {
+                let _ = tx.send(HostTask::LaunchEnd(Box::new(LaunchFinished {
+                    id,
+                    session: String::new(),
+                    outcome: LogOutcome::Crashed,
+                    summary: format!("启动失败：{error}"),
+                })));
+                return;
+            }
+        };
+        let session_id = session.session_id().to_string();
+        let pid = session.pid();
+        let _ = tx.send(HostTask::LaunchStarted {
+            id: id.clone(),
+            session_id: session_id.clone(),
+            pid,
+        });
+        let _ = tx.send(HostTask::Runtime {
+            id: id.clone(),
+            runtime: InstanceRuntime::Running { pid },
+        });
+        match session.finish() {
+            Ok(handle) => {
+                let outcome = super::identity::outcome_of(&handle);
+                let _ = tx.send(HostTask::LaunchEnd(Box::new(LaunchFinished {
+                    id,
+                    session: session_id,
+                    outcome,
+                    summary: format!(
+                        "{}（{}，{:.1}s）",
+                        launch_summary(outcome, Some(handle.exit.code)),
+                        handle.exit.exit_type.as_str(),
+                        handle.uptime_ms as f64 / 1000.0
+                    ),
+                })));
+            }
+            Err(error) => {
+                let _ = tx.send(HostTask::LaunchEnd(Box::new(LaunchFinished {
+                    id,
+                    session: session_id,
+                    outcome: LogOutcome::SilentFail,
+                    summary: format!("启动收尾失败：{error}"),
+                })));
+            }
+        }
+    });
+}
+
+/// 停止一次启动（按 pid 回收进程树；`finish()` 会在后台线程里照常收尾）。
+pub fn stop(pid: u32) -> Result<(), String> {
+    tree_kill::kill_tree(pid, std::time::Duration::from_secs(3))
+        .map_err(|error| format!("停止进程 {pid} 失败：{error}"))
+}
+
+/// 适配层告警 → 人读一行。
+fn describe_warning(warning: &AdapterWarning) -> String {
+    match warning {
+        AdapterWarning::MissingLibrary { name, path } => {
+            format!("缺少库文件 {name}（{}）", path.display())
+        }
+        AdapterWarning::MissingGameArguments => "版本 JSON 没有游戏参数".to_string(),
+        AdapterWarning::MissingAssetsIndex => "版本 JSON 没有资源索引".to_string(),
+        AdapterWarning::MissingMainClass => "版本 JSON 没有 mainClass".to_string(),
+        AdapterWarning::MissingNativeJar { name, path } => {
+            format!("缺少 natives 构件 {name}（{}）", path.display())
+        }
+    }
+}
+
+/// 加载器 → 适配层的模组加载器标记（GUI 只用于显示，不改命令行）。
+pub fn loader_label(kind: LoaderKind) -> &'static str {
+    match kind {
+        LoaderKind::Vanilla => "原版",
+        LoaderKind::Fabric => "Fabric",
+        LoaderKind::Quilt => "Quilt",
+        LoaderKind::Forge => "Forge",
+        LoaderKind::NeoForge => "NeoForge",
+        LoaderKind::OptiFine => "OptiFine",
+        LoaderKind::LiteLoader => "LiteLoader",
+    }
+}
+
+/// 隔离档位的展示串（`isolated` / `shared`）。
+pub fn isolation_label(mode: IsolationMode) -> &'static str {
+    mode.as_str()
+}
diff --git a/crates/presenter/src/host/launch_state_tests.rs b/crates/presenter/src/host/launch_state_tests.rs
new file mode 100644
index 0000000..bbb230d
--- /dev/null
+++ b/crates/presenter/src/host/launch_state_tests.rs
@@ -0,0 +1,267 @@
+//! host 启动状态机单测（P2-1/P2-2 的回归网）。
+//!
+//! 覆盖三件事：
+//! 1. `running_pid` 按实例 id 取 pid（并发启动不会把 A 的停止键指到 B）；
+//! 2. 重复启动守卫（`launches` 已落盘 + `pending` 窗口两态都要挡）；
+//! 3. `refresh_instances` 重建快照后仍保留真实运行时（Running / Busy / Failed）。
+
+use unlucky_core::game::install::instance::write_profiles;
+use unlucky_core::game::{InstanceProfile, ProfileId, ProfileList};
+
+use super::*;
+use crate::dto::{LaunchFinished, LogOutcome};
+use crate::toast::ToastKind;
+
+/// 临时数据根守卫：测试结束（含断言 panic）时把目录删掉，不留空壳。
+struct TempRoot(std::path::PathBuf);
+
+impl Drop for TempRoot {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_dir_all(&self.0);
+    }
+}
+
+/// 建一个只有一条实例档案的数据根，返回 `(host, instance_id, 守卫)`。
+fn host_with_instance(label: &str) -> (CoreHost, String, TempRoot) {
+    let dir = std::env::temp_dir().join(format!(
+        "ull-host-launch-{label}-{}-{}",
+        std::process::id(),
+        line!()
+    ));
+    let _ = std::fs::remove_dir_all(&dir);
+    let env = HostEnv::at_root(&dir);
+    std::fs::create_dir_all(env.layout.config()).expect("config 目录");
+
+    let profile = InstanceProfile {
+        id: ProfileId::generate(),
+        name: "demo".to_string(),
+        version_id: "1.20.1".to_string(),
+        game_dir: None,
+        running_dir: None,
+        java_path: None,
+        created_at: None,
+        last_played_at: None,
+        extra: std::collections::BTreeMap::new(),
+    };
+    let id = profile.id.as_str().to_string();
+    let profiles = ProfileList {
+        profiles: vec![profile],
+        ..ProfileList::default()
+    };
+    write_profiles(&env.layout, &profiles).expect("写 profiles");
+    (CoreHost::headless(env), id, TempRoot(dir))
+}
+
+fn live(instance: &str, session: &str, pid: u32) -> LiveLaunch {
+    LiveLaunch {
+        instance: instance.to_string(),
+        session: session.to_string(),
+        pid,
+    }
+}
+
+#[test]
+fn running_pid_is_per_instance_not_a_single_slot() {
+    let (mut host, id, _root) = host_with_instance("pid");
+    host.launches.push(live("a", "s-a", 111));
+    host.launches.push(live("b", "s-b", 222));
+
+    assert_eq!(host.running_pid("a"), Some(111));
+    assert_eq!(host.running_pid("b"), Some(222));
+    assert_eq!(
+        host.running_pid("c"),
+        None,
+        "没启动过的实例不该拿到别人的 pid"
+    );
+
+    // A 收尾后只影响 A：这正是 review r1 P2-1 的场景（旧实现共用一个槽位）。
+    host.launches.retain(|entry| entry.instance != "a");
+    assert_eq!(host.running_pid("a"), None);
+    assert_eq!(host.running_pid("b"), Some(222));
+
+    // 落盘实例默认是 Idle，兜底分支不误报。
+    assert_eq!(host.running_pid(&id), None);
+}
+
+#[test]
+fn duplicate_launch_is_rejected_before_spawning() {
+    let (mut host, id, _root) = host_with_instance("dup");
+    let _ = host.drain_events();
+    host.launches.push(live(&id, "s", 111));
+
+    host.start_launch(&id);
+
+    let events = host.drain_events();
+    assert!(
+        !events.iter().any(|event| matches!(
+            event,
+            AppEvent::Core(CoreEvent::InstanceRuntimeChanged { .. })
+        )),
+        "已在运行/启动中的实例不该再发 Busy（那会起第二个进程）"
+    );
+    assert!(
+        events
+            .iter()
+            .any(|event| matches!(event, AppEvent::Toast(toast) if toast.kind == ToastKind::Warn)),
+        "至少要给用户一条「已经在启动/运行中」的提示"
+    );
+    assert_eq!(host.launches.len(), 1, "启动表不该被重复启动污染");
+}
+
+#[test]
+fn pending_window_also_blocks_a_second_launch() {
+    let (mut host, id, _root) = host_with_instance("pending");
+    // 走 start_launch 用的同一个入口，模拟「已受理、后台线程还没回报 LaunchStarted」。
+    host.mark_pending(&id);
+    assert!(host.in_flight(&id));
+
+    let _ = host.drain_events();
+    host.start_launch(&id);
+    let events = host.drain_events();
+    assert!(
+        !events.iter().any(|event| matches!(
+            event,
+            AppEvent::Core(CoreEvent::InstanceRuntimeChanged { .. })
+        )),
+        "pending 窗口内重复点启动必须被挡住"
+    );
+    assert_eq!(host.pending.len(), 1);
+}
+
+#[test]
+fn launch_started_registers_and_launch_end_clears() {
+    let (mut host, id, _root) = host_with_instance("cycle");
+    host.mark_pending(&id);
+
+    host.handle(HostTask::LaunchStarted {
+        id: id.clone(),
+        session_id: "20261031T120000-abcd12".to_string(),
+        pid: 4_242,
+    });
+    assert!(!host.pending.contains(&id), "回报后 pending 要清掉");
+    assert_eq!(host.running_pid(&id), Some(4_242));
+
+    host.handle(HostTask::LaunchEnd(Box::new(LaunchFinished {
+        id: id.clone(),
+        session: "20261031T120000-abcd12".to_string(),
+        outcome: LogOutcome::Ok,
+        summary: "正常退出".to_string(),
+    })));
+    assert!(host.launches.is_empty(), "收尾后启动表要清空");
+    assert!(!host.failed.contains_key(&id));
+    assert_eq!(host.running_pid(&id), None);
+}
+
+#[test]
+fn refresh_keeps_running_instances_running() {
+    let (mut host, id, _root) = host_with_instance("refresh-run");
+    host.launches.push(live(&id, "s", 4_242));
+    let _ = host.drain_events();
+
+    host.refresh_instances();
+
+    let instance = instances_from_events(host.drain_events())
+        .into_iter()
+        .find(|instance| instance.id == id)
+        .expect("刷新后应有该实例");
+    assert_eq!(
+        instance.runtime,
+        InstanceRuntime::Running { pid: 4_242 },
+        "刷新（装版本/账户变更/别的实例收尾）不能把在跑实例打回 Idle"
+    );
+}
+
+#[test]
+fn refresh_keeps_pending_as_busy_and_failed_as_failed() {
+    let (mut host, id, _root) = host_with_instance("refresh-busy");
+
+    // Busy：走 start_launch 用的同一个入口（mark_pending），而不是直接改字段。
+    host.mark_pending(&id);
+    let pending = instances_from_events({
+        host.refresh_instances();
+        host.drain_events()
+    })
+    .into_iter()
+    .find(|instance| instance.id == id)
+    .expect("实例存在");
+    assert!(matches!(
+        pending.runtime,
+        InstanceRuntime::Busy {
+            stage: crate::dto::LaunchStage::Launch,
+            ..
+        }
+    ));
+
+    // Failed：走唯一真实写入路径 LaunchEnd（不是手动塞 failed 表）。
+    host.handle(HostTask::LaunchEnd(Box::new(LaunchFinished {
+        id: id.clone(),
+        session: "20261031T120000-dead01".to_string(),
+        outcome: LogOutcome::Crashed,
+        summary: "崩溃（exit 1）".to_string(),
+    })));
+    assert!(!host.pending.contains(&id), "LaunchEnd 必须清 pending");
+    assert!(!host.in_flight(&id), "收尾后该实例要能被重新启动");
+
+    let failed = instances_from_events({
+        host.refresh_instances();
+        host.drain_events()
+    })
+    .into_iter()
+    .find(|instance| instance.id == id)
+    .expect("实例存在");
+    assert_eq!(
+        failed.runtime,
+        InstanceRuntime::Failed {
+            reason: "崩溃（exit 1）".to_string()
+        },
+        "失败原因要经得住一次刷新（否则磁贴的「重试」外观会被 Idle 盖掉）"
+    );
+}
+
+#[test]
+fn launch_end_before_launch_started_still_releases_the_instance() {
+    let (mut host, id, _root) = host_with_instance("fail-early");
+    // build_request / spawn 失败的现场：start_launch 已标 pending、后台线程只发 LaunchEnd。
+    host.mark_pending(&id);
+    assert!(host.in_flight(&id));
+
+    host.handle(HostTask::LaunchEnd(Box::new(LaunchFinished {
+        id: id.clone(),
+        session: String::new(),
+        outcome: LogOutcome::Crashed,
+        summary: "启动失败：找不到 Java".to_string(),
+    })));
+
+    assert!(
+        !host.pending.contains(&id),
+        "LaunchEnd 早于 LaunchStarted 时也必须清 pending（否则该实例本会话再也起不来）"
+    );
+    assert!(!host.in_flight(&id), "失败后要能重试");
+
+    let failed = instances_from_events({
+        host.refresh_instances();
+        host.drain_events()
+    })
+    .into_iter()
+    .find(|instance| instance.id == id)
+    .expect("实例存在");
+    assert_eq!(
+        failed.runtime,
+        InstanceRuntime::Failed {
+            reason: "启动失败：找不到 Java".to_string()
+        },
+        "早失败也要在磁贴上留下「失败/重试」，不能被 Idle 盖掉"
+    );
+}
+
+/// 从事件队列里取最后一次 `InstancesChanged`。
+fn instances_from_events(events: Vec) -> 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..f9fd901
--- /dev/null
+++ b/crates/presenter/src/host/logs.rs
@@ -0,0 +1,342 @@
+//! 日志 / 诊断：会话索引 → 会话列表，事件 JSONL → 日志行，规则引擎 → 诊断卡片。
+//!
+//! 与 CLI `ull logs` / `ull diagnose` 同源（`launch::session_index` + `diagnose` 规则引擎）：
+//! 「同一份 jsonl 的两种读法」只有这一处实现（M39 ports/events.rs 的设计）。
+//! 实时滚动 = host 每拍尾随启动会话的 JSONL（只读新增字节），不额外开第二条事件通道。
+
+use std::io::{Read, Seek, SeekFrom};
+use std::path::{Path, PathBuf};
+
+use serde_json::Value;
+use unlucky_core::diagnose::collectors::{ExitSignal, SignalOrigin};
+use unlucky_core::diagnose::engine::{Diagnoser, DiagnosisInput};
+use unlucky_core::diagnose::loader::RuleLoader;
+use unlucky_core::launch::session_index::{self, SessionIndexEntry};
+
+use crate::dto::{
+    Diagnosis, DiagnosisReport, LogLevel, LogLine, LogOutcome, LogSession, SessionId,
+};
+
+use super::env::HostEnv;
+
+/// 送进规则引擎的默认尾巴行数（与 CLI 同值，避免两条路看到不同证据）。
+pub const DEFAULT_TAIL: usize = 2000;
+
+/// 日志页一次最多渲染的行数（超出的截断，避免大文件把 UI 拖死）。
+pub const MAX_RENDERED_LINES: usize = 2_000;
+
+/// 会话索引目录（`.ULL/data/agent/sessions`）。
+pub fn root(env: &HostEnv) -> PathBuf {
+    env.sessions_root()
+}
+
+/// 会话列表（新→旧）。
+pub fn sessions(env: &HostEnv) -> Vec {
+    let index = session_index::index_path(&root(env));
+    let mut entries = session_index::read_all(&index).unwrap_or_default();
+    entries.sort_by(|a, b| b.started_at.cmp(&a.started_at));
+    entries.iter().map(session_of).collect()
+}
+
+/// 索引条目 → 左栏会话行。
+pub fn session_of(entry: &SessionIndexEntry) -> LogSession {
+    LogSession {
+        id: entry.session_id.clone(),
+        instance: if entry.instance_name.is_empty() {
+            entry.instance_id.clone()
+        } else {
+            entry.instance_name.clone()
+        },
+        when: display_time(&entry.started_at),
+        outcome: outcome_of(entry),
+        duration_secs: entry.duration_ms / 1000,
+    }
+}
+
+/// 结局：静默失败 > 崩溃（非 0 / crash_found） > 正常。
+pub fn outcome_of(entry: &SessionIndexEntry) -> LogOutcome {
+    if entry.silent_failure {
+        LogOutcome::SilentFail
+    } else if entry.crash_found
+        || entry.exit_code.is_some_and(|code| code != 0)
+        || (entry.exit_code.is_none() && !entry.ended_at.is_empty())
+    {
+        LogOutcome::Crashed
+    } else {
+        LogOutcome::Ok
+    }
+}
+
+/// `2026-10-29T19:22:45.123Z` → `10-29 19:22`。
+pub fn display_time(started_at: &str) -> String {
+    let body = started_at.trim_end_matches('Z');
+    let Some((date, time)) = body.split_once('T') else {
+        return started_at.to_string();
+    };
+    let date = date.get(5..).unwrap_or(date);
+    let time = time.get(..5).unwrap_or(time);
+    format!("{date} {time}")
+}
+
+/// 事件流文件路径（`/game/`）。
+pub fn event_path(env: &HostEnv, entry: &SessionIndexEntry) -> PathBuf {
+    root(env).join("game").join(&entry.log_path)
+}
+
+/// 会话 id 或唯一前缀 → 索引条目。
+fn find(env: &HostEnv, key: &str) -> Option {
+    let index = session_index::index_path(&root(env));
+    let entries = session_index::read_all(&index).ok()?;
+    if let Some(exact) = entries.iter().find(|entry| entry.session_id == key) {
+        return Some(exact.clone());
+    }
+    entries
+        .iter()
+        .find(|entry| entry.session_id.starts_with(key))
+        .cloned()
+}
+
+/// 事件 JSON → 一行日志（`stdout`/`stderr` 的 `payload.line`）。
+pub fn line_of(event: &Value) -> Option {
+    let text = event.pointer("/payload/line").and_then(Value::as_str)?;
+    let kind = event
+        .get("kind")
+        .and_then(Value::as_str)
+        .unwrap_or_default();
+    let level = match event
+        .pointer("/payload/level")
+        .and_then(Value::as_str)
+        .unwrap_or_default()
+    {
+        "error" => LogLevel::Error,
+        "warn" | "warning" => LogLevel::Warn,
+        "debug" | "trace" => LogLevel::Debug,
+        _ => {
+            if kind == "stderr" {
+                LogLevel::Warn
+            } else {
+                LogLevel::Info
+            }
+        }
+    };
+    Some(LogLine {
+        text: text.to_string(),
+        level,
+    })
+}
+
+/// 整个事件流 → 日志行（解析失败的行跳过，容忍被 kill 时截断的尾行）。
+pub fn read_lines(path: &Path) -> Vec {
+    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())
+        .filter_map(|event| line_of(&event))
+        .collect()
+}
+
+/// 打开一个会话：日志行 + 规则引擎结论。
+pub fn open(env: &HostEnv, key: &str) -> (Vec, Option) {
+    let Some(entry) = find(env, key) else {
+        return (Vec::new(), None);
+    };
+    let path = event_path(env, &entry);
+    let lines = read_lines(&path);
+    let diagnosis = diagnose_lines(&entry, &lines);
+    (lines, diagnosis)
+}
+
+/// 规则引擎跑一遍（**规则先跑，模型补位**：这里只出规则结论）。
+pub fn diagnose_lines(entry: &SessionIndexEntry, lines: &[LogLine]) -> Option {
+    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 {
+    let index = session_index::index_path(&root(env));
+    session_index::read_all(&index)
+        .unwrap_or_default()
+        .iter()
+        .any(|entry| entry.session_id == session && !entry.ended_at.is_empty())
+}
+
+#[cfg(test)]
+#[path = "logs_tests.rs"]
+mod tests;
diff --git a/crates/presenter/src/host/logs_tests.rs b/crates/presenter/src/host/logs_tests.rs
new file mode 100644
index 0000000..ccbb6a3
--- /dev/null
+++ b/crates/presenter/src/host/logs_tests.rs
@@ -0,0 +1,86 @@
+//! host/logs.rs 的单测（拆文件守 400 行上限）。
+
+use super::*;
+
+#[test]
+fn time_display_and_outcomes() {
+    assert_eq!(display_time("2026-10-29T19:22:45.123Z"), "10-29 19:22");
+    assert_eq!(display_time("nope"), "nope");
+    let mut entry = SessionIndexEntry {
+        v: 1,
+        session_id: "s".to_string(),
+        instance_id: String::new(),
+        instance_name: String::new(),
+        game_version: String::new(),
+        started_at: String::new(),
+        ended_at: "2026-10-29T19:22:45Z".to_string(),
+        duration_ms: 1000,
+        exit_code: Some(0),
+        exit_type: Some("normal".to_string()),
+        silent_failure: false,
+        window_detected: true,
+        event_count: 1,
+        log_path: "s.jsonl".to_string(),
+        crash_found: false,
+        diagnosis_top: None,
+    };
+    assert_eq!(outcome_of(&entry), LogOutcome::Ok);
+    entry.exit_code = Some(1);
+    assert_eq!(outcome_of(&entry), LogOutcome::Crashed);
+    entry.silent_failure = true;
+    assert_eq!(outcome_of(&entry), LogOutcome::SilentFail);
+}
+
+#[test]
+fn lines_map_levels_and_skip_non_line_events() {
+    let stdout = serde_json::json!({"kind":"stdout","payload":{"line":"hi","level":"info"}});
+    assert_eq!(line_of(&stdout).unwrap().level, LogLevel::Info);
+    let stderr = serde_json::json!({"kind":"stderr","payload":{"line":"boom","level":"error"}});
+    assert_eq!(line_of(&stderr).unwrap().level, LogLevel::Error);
+    let other = serde_json::json!({"kind":"cmd_built","payload":{"argv":[]}});
+    assert!(line_of(&other).is_none());
+}
+
+#[test]
+fn tail_only_consumes_complete_lines() {
+    let dir = std::env::temp_dir().join(format!("ull-host-tail-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    std::fs::create_dir_all(&dir).expect("目录");
+    let path = dir.join("s.jsonl");
+    std::fs::write(
+        &path,
+        "{\"kind\":\"stdout\",\"payload\":{\"line\":\"one\"}}\n",
+    )
+    .expect("写");
+    let mut tail = Tail::default();
+    tail.attach(path.clone(), "s");
+    let (session, lines) = tail.poll().expect("首拍有新行");
+    assert_eq!(session, "s");
+    assert_eq!(lines.len(), 1);
+    assert!(tail.poll().is_none(), "没有新增就不该再产出");
+
+    // 半行不消费
+    let mut text = std::fs::read_to_string(&path).expect("读");
+    text.push_str("{\"kind\":\"stdout\",\"payload\":{\"line\":\"tw");
+    std::fs::write(&path, text).expect("写");
+    assert!(tail.poll().is_none(), "半个 JSON 行不能解析");
+    let mut text = std::fs::read_to_string(&path).expect("读");
+    text.push_str("o\"}}\n");
+    std::fs::write(&path, text).expect("写");
+    let (_, lines) = tail.poll().expect("补全后应产出");
+    assert_eq!(lines[0].text, "two");
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+#[test]
+fn crash_import_reports_missing_file() {
+    let err = analyze_crash_file("D:/definitely/missing/hs_err_pid1.log").unwrap_err();
+    assert!(err.contains("找不到崩溃日志"), "{err}");
+}
+
+#[test]
+fn confidence_percent_is_rounded_and_clamped() {
+    assert_eq!(confidence_percent(0.923), 92);
+    assert_eq!(confidence_percent(-1.0), 0);
+    assert_eq!(confidence_percent(2.0), 100);
+}
diff --git a/crates/presenter/src/host/meter.rs b/crates/presenter/src/host/meter.rs
new file mode 100644
index 0000000..d42c0c5
--- /dev/null
+++ b/crates/presenter/src/host/meter.rs
@@ -0,0 +1,89 @@
+//! 安装进度的记账器（文件计数 / 字节 / 速度 / ETA）。
+//!
+//! `execute` 的文件级回调已经把每个文件的结局给了我们，这里只做聚合；
+//! 速度用相邻两次采样的字节差算（core 的事件只给绝对值）。
+
+use std::sync::Arc;
+use std::time::Instant;
+
+use unlucky_core::game::install::{FileOutcome, FileStatus, ProgressSink};
+
+use crate::dto::{derive_speed, CreateRequest, InstallProgressView, InstallStage};
+
+use super::install::loader_label;
+use super::job::{HostTask, JobSender};
+/// 一次安装的上下文（进度回调共享）。
+pub(super) struct Meter {
+    pub(super) progress: InstallProgressView,
+    /// 任务代次：随每条进度一起回流，让 host 能丢掉「已被取消/被顶掉的旧任务」的事件。
+    ///
+    /// 记在记账器上而不是每条 `HostTask` 现传：所有发送点都已经持有这把锁并读 `progress`，
+    /// 于是代次与它描述的那份进度**永远同源**（不会出现「新代次的进度配旧代次的标签」）。
+    pub(super) epoch: u64,
+    previous: Option<(u64, Instant)>,
+}
+
+impl Meter {
+    pub(super) fn new(request: &CreateRequest, epoch: u64) -> Self {
+        Self {
+            progress: InstallProgressView::start(
+                &request.version,
+                &request.instance_name(),
+                &loader_label(request.loader, &request.loader_version),
+            ),
+            epoch,
+            previous: None,
+        }
+    }
+
+    /// 换阶段（重置速度采样）。
+    pub(super) fn stage(&mut self, stage: InstallStage, message: &str) {
+        self.progress.stage = stage;
+        self.progress.message = message.to_string();
+        self.previous = None;
+    }
+
+    /// 预记账一段待下载的文件（文件数 + 字节）。
+    ///
+    /// 一次安装可能分几段（原版 / 处理器依赖库 / 加载器库）：每段开工前都先记账，
+    /// 整条进度曲线才是单调的——某一段下完不会先到 100%，再因为下一段的文件被计入而回落。
+    pub(super) fn expect(&mut self, files: usize, bytes: u64) {
+        let files = u64::try_from(files).unwrap_or(u64::MAX);
+        self.progress.files_total = self.progress.files_total.saturating_add(files);
+        self.progress.bytes_total = self.progress.bytes_total.saturating_add(bytes);
+    }
+
+    /// 记账一个文件的结局。
+    pub(super) fn note(&mut self, outcome: &FileOutcome) {
+        self.progress.files_done += 1;
+        if outcome.status != FileStatus::Skipped {
+            self.progress.bytes_done = self.progress.bytes_done.saturating_add(outcome.bytes);
+        }
+        let now = Instant::now();
+        if let Some(previous) = self.previous {
+            if let Some((speed, eta)) = derive_speed(
+                previous,
+                (self.progress.bytes_done, now),
+                self.progress.bytes_total,
+            ) {
+                self.progress.speed_bps = speed;
+                self.progress.eta_secs = eta;
+            }
+        }
+        self.previous = Some((self.progress.bytes_done, now));
+    }
+}
+
+/// 进度 sink（`execute` 的文件级回调）。
+pub(super) fn sink_for(tx: JobSender, meter: Arc>) -> ProgressSink {
+    Arc::new(move |outcome: &FileOutcome| {
+        let Ok(mut meter) = meter.lock() else {
+            return;
+        };
+        meter.note(outcome);
+        let _ = tx.send(HostTask::Install {
+            progress: Box::new(meter.progress.clone()),
+            epoch: meter.epoch,
+        });
+    })
+}
diff --git a/crates/presenter/src/host/mod.rs b/crates/presenter/src/host/mod.rs
new file mode 100644
index 0000000..ed55b51
--- /dev/null
+++ b/crates/presenter/src/host/mod.rs
@@ -0,0 +1,366 @@
+//! 真实后端：把 core（game/launch/install/auth/java/diagnose/setting）装配成 GUI 的 host。
+//!
+//! 边界：本模块是**整个 presenter crate 里唯一**允许 `use unlucky_core::…` 的地方（连同
+//! `settings_bridge`）；出口只有 [`crate::dto`] 的快照/事件。线程模型：
+//!
+//! ```text
+//! dispatch(AppCommand) ──► 立即动作（读盘/写设置）或 spawn 后台线程
+//! 后台线程 ──HostTask──► rx ──tick()──► CoreEvent ──► state.apply()
+//! tick() 另外每 ~600ms 尾随一次运行中会话的 JSONL（实时日志滚动）
+//! ```
+//!
+//! AI 对话暂时仍由 [`MockBackend`] 提供脚本回复（agent 的 GUI host 是后续 mission）；
+//! 其余页面全部走真实 core。
+
+mod accounts;
+mod addon;
+mod dispatch;
+mod engine;
+pub mod env;
+mod game;
+mod handle;
+mod identity;
+mod install;
+mod install_journal;
+mod install_processors;
+mod java;
+mod job;
+mod launch;
+mod loader_versions;
+mod logs;
+mod meter;
+mod opener;
+mod settings;
+mod versions;
+
+use std::collections::{BTreeMap, BTreeSet, VecDeque};
+use std::time::Duration;
+
+use crate::dto::{
+    AccountView, AppCommand, AppEvent, Backend, CoreEvent, DiagnosisReport, InstallProgressView,
+    InstanceRuntime, JavaChainStep, NoticeView, SkinImage,
+};
+use crate::mock::MockBackend;
+use crate::toast::{Toast, ToastKind};
+
+use accounts::LoginJob;
+pub use env::HostEnv;
+use job::{HostTask, JobReceiver, JobSender};
+
+/// 每拍最多处理的后台消息数（防止一次 tick 吃掉整帧预算）。
+const MAX_TASKS_PER_TICK: usize = 64;
+
+/// 实时日志尾随间隔（拍数，33ms/拍 → 约 600ms 一次）。
+const TAIL_POLL_TICKS: u64 = 18;
+
+/// 一次在跑的启动（并发启动时按实例 id 区分，停止/尾随都不会串到别的实例）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct LiveLaunch {
+    instance: String,
+    session: String,
+    pid: u32,
+}
+
+/// 真实 host。
+pub struct CoreHost {
+    env: HostEnv,
+    events: VecDeque,
+    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,
+}
+
+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);
+        let mut host = Self {
+            env,
+            events: VecDeque::new(),
+            tx,
+            rx,
+            ticks: 0,
+            active_account: None,
+            accounts: Vec::new(),
+            login: None,
+            authlib: None,
+            skins: BTreeMap::new(),
+            skin_requested: BTreeSet::new(),
+            java_chain: Vec::new(),
+            java_busy: false,
+            java_message: String::new(),
+            install: None,
+            notices: Vec::new(),
+            launches: Vec::new(),
+            pending: BTreeSet::new(),
+            failed: BTreeMap::new(),
+            tail: logs::Tail::default(),
+            chat: MockBackend::default(),
+            install_cancel: None,
+            install_epoch: 0,
+        };
+        if refresh {
+            host.refresh_all();
+        }
+        // M109：CF 源可用与否只在装配时打一行（**不含密钥内容**，见 `addon` 模块文档）。
+        addon::log_curseforge_state();
+        host
+    }
+
+    /// 数据根（截图/诊断展示用）。
+    pub fn env(&self) -> &HostEnv {
+        &self.env
+    }
+
+    fn send(&mut self, event: CoreEvent) {
+        self.events.push_back(AppEvent::Core(event));
+    }
+
+    /// 开一轮安装：代次 +1 并把新代次交出去（后台线程随每条进度带回来）。
+    ///
+    /// 返回**新**代次而不是旧代次：调用方拿它去 `spawn_install`，于是「谁是新任务」只有一处答案。
+    fn next_install_epoch(&mut self) -> u64 {
+        self.install_epoch = self.install_epoch.wrapping_add(1);
+        self.install_epoch
+    }
+
+    fn toast(&mut self, kind: ToastKind, text: impl Into) {
+        self.events.push_back(AppEvent::Toast(Toast {
+            id: 0,
+            kind,
+            text: text.into(),
+            remaining_ms: 0,
+        }));
+    }
+
+    /// 全量刷新：实例 / 会话 / 账户 / 设置 / Java，并触发一次版本清单拉取。
+    pub fn refresh_all(&mut self) {
+        self.refresh_instances();
+        self.send(CoreEvent::LogSessionsChanged(logs::sessions(&self.env)));
+        self.refresh_accounts();
+        self.send(CoreEvent::SettingsChanged(settings::groups(&self.env)));
+        self.refresh_java();
+        versions::spawn_list(self.env.clone(), self.tx.clone());
+    }
+
+    /// 重建实例快照，并把**真实运行时**盖回去。
+    ///
+    /// `game::instances` 只读盘（每条都是 `Idle`），所以在跑的实例必须在重建后按
+    /// host 自己的启动表覆写 `Running{pid}`/`Busy`，否则任意一次刷新（装版本成功、
+    /// 加删账户、另一实例收尾）都会把磁贴打回 Idle：停止键与「运行中」条消失，
+    /// 进程还在跑却再也停不下来。
+    fn refresh_instances(&mut self) {
+        let mut instances = game::instances(&self.env);
+        for instance in &mut instances {
+            if let Some(live) = self
+                .launches
+                .iter()
+                .find(|live| live.instance == instance.id)
+            {
+                instance.runtime = InstanceRuntime::Running { pid: live.pid };
+            } else if self.pending.contains(&instance.id) {
+                instance.runtime = InstanceRuntime::Busy {
+                    stage: crate::dto::LaunchStage::Launch,
+                    progress: crate::dto::Progress { done: 0, total: 1 },
+                };
+            } else if let Some(reason) = self.failed.get(&instance.id) {
+                instance.runtime = InstanceRuntime::Failed {
+                    reason: reason.clone(),
+                };
+            }
+        }
+        self.send(CoreEvent::InstancesChanged(instances));
+    }
+
+    fn refresh_java(&mut self) {
+        let page = java::page(
+            &self.env,
+            self.java_chain.clone(),
+            self.java_busy,
+            &self.java_message,
+        );
+        self.send(CoreEvent::JavaChanged(page));
+    }
+
+    fn push_notice(&mut self, notice: NoticeView) {
+        self.notices.retain(|existing| existing.id != notice.id);
+        self.notices.push(notice);
+        self.send(CoreEvent::NoticesChanged(self.notices.clone()));
+    }
+
+    /// 打开一个会话（日志行 + 诊断）。
+    fn open_session(&mut self, id: &str) {
+        let (lines, diagnosis) = logs::open(&self.env, id);
+        self.send(CoreEvent::LogLinesChanged(lines));
+        self.send(CoreEvent::DiagnosisReady(diagnosis.unwrap_or(
+            DiagnosisReport {
+                session: id.to_string(),
+                diagnosis: crate::dto::Diagnosis {
+                    rule: String::new(),
+                    title: "该会话没有命中已知规则".to_string(),
+                    confidence: 0,
+                    hint: "可点「让 AI 详解」把日志交给模型进一步分析".to_string(),
+                    fix: None,
+                },
+            },
+        )));
+    }
+
+    /// 由实例名/版本 id 找启动目标。
+    fn launch_target(&self, id: &str) -> Option {
+        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/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/settings.rs b/crates/presenter/src/host/settings.rs
new file mode 100644
index 0000000..5e45361
--- /dev/null
+++ b/crates/presenter/src/host/settings.rs
@@ -0,0 +1,399 @@
+//! 设置页分组：按 `core::setting` schema 的键生成行，写回走 `SettingStore::set`。
+//!
+//! 三件纪律（AGENTS §6）：
+//! 1. 读写同一份 `<数据根>/config/launcher.json`（与 `ull config set` / AI `set_config` 同源）；
+//! 2. 不自己拼 JSON，也不绕 schema（非法键/越界值由 `store.set` 拒绝）；
+//! 3. 这里只认「键名 + 字符串值」，领域语义留在 core。
+//!
+//! 分组 id 与设置页子导航同名：`download` / `java` / `data` / `ai` / `mcp`。
+
+use serde_json::Value;
+use unlucky_core::game::java::JdkVendor;
+use unlucky_core::setting::spec::ValueKind;
+
+use crate::dto::{SettingGroupView, SettingRowView};
+
+use super::env::HostEnv;
+
+/// 全部设置分组（设置页右栏一次拿全，切分组不再请求）。
+pub fn groups(env: &HostEnv) -> Vec {
+    vec![
+        download_group(env),
+        java_group(env),
+        data_group(env),
+        ai_group(env),
+        mcp_group(env),
+    ]
+}
+
+/// 读一个键的字符串值（缺省给空串）。
+fn text(env: &HostEnv, key: &str) -> String {
+    env.store()
+        .doc()
+        .effective_str(key)
+        .unwrap_or_default()
+        .to_string()
+}
+
+/// 读一个键的整数（缺省给 `fallback`）。
+fn int(env: &HostEnv, key: &str, fallback: i64) -> i64 {
+    env.store()
+        .effective(key)
+        .and_then(Value::as_i64)
+        .unwrap_or(fallback)
+}
+
+/// 读一个键的布尔（缺省给 `fallback`）。
+fn flag(env: &HostEnv, key: &str, fallback: bool) -> bool {
+    env.store()
+        .effective(key)
+        .and_then(Value::as_bool)
+        .unwrap_or(fallback)
+}
+
+/// 枚举值在选项表里的序号（找不到给 0）。
+fn selected(options: &[&str], value: &str) -> i32 {
+    options
+        .iter()
+        .position(|option| *option == value)
+        .map(|index| i32::try_from(index).unwrap_or(0))
+        .unwrap_or(0)
+}
+
+/// 下载（D7）：并发/重试/地区/镜像偏好/代理。
+fn download_group(env: &HostEnv) -> SettingGroupView {
+    let concurrency = int(env, "download.concurrency", 8).to_string();
+    let retry = int(env, "download.retry_limit", 3).to_string();
+    let concurrency_options = ["4", "8", "16"];
+    let retry_options = ["0", "1", "3", "5"];
+    let regions = ["auto", "cn", "global"];
+    let mirrors = ["auto", "official", "mirror"];
+    let proxies = ["none", "system", "manual"];
+    let region_value = text(env, "download.region");
+    let mirror_value = text(env, "download.mirror_preference");
+    let proxy_value = text(env, "download.proxy_mode");
+    SettingGroupView::new("download", "下载与镜像（D7）")
+        .with(SettingRowView::choice(
+            "download.concurrency",
+            "并发数",
+            "同时下载的文件数（海量小文件，16 路足够压满带宽）",
+            &concurrency_options,
+            selected(&concurrency_options, &concurrency),
+        ))
+        .with(SettingRowView::choice(
+            "download.retry_limit",
+            "单文件重试次数",
+            "失败后换源重试的上限",
+            &retry_options,
+            selected(&retry_options, &retry),
+        ))
+        .with(SettingRowView::choice(
+            "download.region",
+            "地区判定",
+            "auto = 时区+语言+探测；决定是否优先国内镜像",
+            ®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"),
+        ))
+        .with(SettingRowView::action(
+            "download.action.detect_region",
+            "重新检测地区",
+            "清掉 24h 地区缓存，下次下载重新判定",
+            "detect_region",
+        ))
+}
+
+/// Java（D13/D23）：自动安装/内存/选路/发行版优先级。
+fn java_group(env: &HostEnv) -> SettingGroupView {
+    let memory = int(env, "java.default_memory_mb", 2048).to_string();
+    let memory_options = ["1024", "2048", "4096", "8192"];
+    let priority: Vec = 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 三模式）。
+fn data_group(env: &HostEnv) -> SettingGroupView {
+    let modes = ["portable", "standard", "custom"];
+    let mode = env.mode().as_str().to_string();
+    SettingGroupView::new("data", "数据目录（D6 三模式）")
+        .with(SettingRowView::choice(
+            "core.data_mode",
+            "存储模式",
+            "便携（运行目录）/ 标准（系统应用数据目录）/ 自定义",
+            &modes,
+            selected(&modes, &mode),
+        ))
+        .with(SettingRowView::text(
+            "core.data_custom_root",
+            "自定义根目录",
+            "custom 模式生效（绝对路径）",
+            &text(env, "core.data_custom_root"),
+        ))
+        .with(SettingRowView::read_only(
+            "启动器数据目录",
+            &env.data.launcher_home.display().to_string(),
+        ))
+        .with(SettingRowView::read_only(
+            "游戏目录",
+            &env.data.game_home.display().to_string(),
+        ))
+        .with(SettingRowView::read_only(
+            "生效模式",
+            &format!("{}（改数据根需重启启动器）", env.mode()),
+        ))
+}
+
+/// AI（D4）：开关/端点/模型/YOLO。
+fn ai_group(env: &HostEnv) -> SettingGroupView {
+    let providers = ["openai_compatible", "anthropic", "ollama"];
+    let provider = text(env, "ai.provider");
+    SettingGroupView::new("ai", "AI 助手（D4）")
+        .with(SettingRowView::toggle(
+            "ai.enabled",
+            "启用 AI 助手",
+            "关闭后规则引擎诊断仍可用",
+            flag(env, "ai.enabled", true),
+        ))
+        .with(SettingRowView::choice(
+            "ai.provider",
+            "模型端点",
+            "OpenAI 兼容（含本地 llama.cpp）/ Anthropic / Ollama",
+            &providers,
+            selected(
+                &providers,
+                if provider.is_empty() {
+                    "openai_compatible"
+                } else {
+                    &provider
+                },
+            ),
+        ))
+        .with(SettingRowView::text(
+            "ai.base_url",
+            "端点 base_url",
+            "如 http://127.0.0.1:8080/v1",
+            &text(env, "ai.base_url"),
+        ))
+        .with(SettingRowView::text(
+            "ai.model",
+            "模型名",
+            "如 deepseek-chat",
+            &text(env, "ai.model"),
+        ))
+        .with(SettingRowView::toggle(
+            "ai.yolo",
+            "YOLO 模式",
+            "跳过确认弹窗（审计照记；账户/凭据操作永不 YOLO）",
+            flag(env, "ai.yolo", false),
+        ))
+}
+
+/// M39 的对外 MCP server（默认关、默认只读）。
+fn mcp_group(env: &HostEnv) -> SettingGroupView {
+    let port = int(env, "agent.mcp.port", 47_823);
+    SettingGroupView::new("mcp", "MCP server（M39）")
+        .with(SettingRowView::toggle(
+            "agent.mcp.enabled",
+            "对外提供 MCP server",
+            "127.0.0.1 上的 Streamable HTTP（stdio 需显式启动）",
+            flag(env, "agent.mcp.enabled", false),
+        ))
+        .with(SettingRowView::text(
+            "agent.mcp.port",
+            "端口",
+            "1024~65535，只绑 127.0.0.1",
+            &port.to_string(),
+        ))
+        .with(SettingRowView::toggle(
+            "agent.mcp.allow_write",
+            "允许外部客户端写配置",
+            "默认只读；写仍受 schema 白名单与分级确认约束",
+            flag(env, "agent.mcp.allow_write", false),
+        ))
+        .with(SettingRowView::read_only(
+            "客户端地址",
+            &format!("http://127.0.0.1:{port}/mcp（令牌见 agent.mcp.token，AI 不可写）"),
+        ))
+}
+
+/// 写一条设置。`value` 是字符串形态，按 schema 键的类型转换后交 `store.set`。
+///
+/// # Errors
+///
+/// 未知键、值类型不符、越界、落盘失败时返回用户可读文案。
+pub fn set(env: &HostEnv, key: &str, value: &str) -> Result<(), String> {
+    if key == "download.action.detect_region" {
+        return detect_region(env);
+    }
+    let parsed = parse_value(key, value)?;
+    let mut store = env.store();
+    store
+        .set(key, parsed)
+        .map_err(|error| format!("设置 {key} 失败：{error}"))?;
+    store
+        .save()
+        .map_err(|error| format!("保存设置失败：{error}"))?;
+    Ok(())
+}
+
+/// 键 → 正确类型的 JSON 值（schema 会再校验范围/枚举）。
+///
+/// **按 schema 的 `ValueKind` 取类型，不硬编码键名**（复审 P1-1）：原先是「硬编码 Int/Bool
+/// 键名，其余当字符串」，于是 `appearance.window_opacity`（Float）被当 String 送进 `store.set`，
+/// schema 的 `as_f64()` 返回 `None` ⇒ `InvalidValue` ⇒ **`save()` 不执行**（重启回旧值 + 弹 toast）。
+/// 现在新增任何 Float/Int/Bool 键都自动正确；集合级守门是
+/// `every_float_key_in_the_schema_can_be_written_back`。
+fn parse_value(key: &str, value: &str) -> Result {
+    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 地区缓存（下次建引擎重新判定）。
+fn detect_region(env: &HostEnv) -> Result<(), String> {
+    let path = env.layout.cache().join("region.json");
+    if path.is_file() {
+        std::fs::remove_file(&path).map_err(|error| format!("清地区缓存失败：{error}"))?;
+    }
+    Ok(())
+}
+
+/// 设置页「重置发行版优先级」用（清空 enum_list）。
+///
+/// # Errors
+///
+/// 落盘失败时返回用户可读文案。
+pub fn clear_vendor_priority(env: &HostEnv) -> Result<(), String> {
+    let mut store = env.store();
+    store
+        .set("java.vendorPriority", Value::Array(Vec::new()))
+        .and_then(|()| store.save())
+        .map_err(|error| format!("清空发行版优先级失败：{error}"))?;
+    let _ = JdkVendor::ALL;
+    Ok(())
+}
+
+#[cfg(test)]
+#[path = "settings_tests.rs"]
+mod tests;
diff --git a/crates/presenter/src/host/settings_tests.rs b/crates/presenter/src/host/settings_tests.rs
new file mode 100644
index 0000000..0cabb39
--- /dev/null
+++ b/crates/presenter/src/host/settings_tests.rs
@@ -0,0 +1,163 @@
+//! host/settings.rs 的单测（拆文件守 400 行上限）。
+
+use super::*;
+
+fn env_in(dir: &std::path::Path) -> HostEnv {
+    std::fs::create_dir_all(dir.join(".ULL/config")).expect("config");
+    HostEnv::at_root(dir)
+}
+
+#[test]
+fn groups_cover_the_six_required_areas() {
+    let dir = std::env::temp_dir().join(format!("ull-host-settings-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    let env = env_in(&dir);
+    let groups = groups(&env);
+    let ids: Vec<&str> = groups.iter().map(|group| group.id.as_str()).collect();
+    assert_eq!(ids, vec!["download", "java", "data", "ai", "mcp"]);
+    let keys: Vec<&str> = groups
+        .iter()
+        .flat_map(|group| group.rows.iter())
+        .map(|row| row.key.as_str())
+        .collect();
+    for key in [
+        "download.region",
+        "download.mirror_preference",
+        "java.default_memory_mb",
+        "core.data_mode",
+        "agent.mcp.enabled",
+        "agent.mcp.port",
+        "ai.base_url",
+    ] {
+        assert!(keys.contains(&key), "缺少 {key}");
+    }
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+#[test]
+fn set_parses_types_and_persists() {
+    let dir = std::env::temp_dir().join(format!("ull-host-settings-w-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    let env = env_in(&dir);
+
+    set(&env, "download.concurrency", "16").expect("写并发");
+    set(&env, "agent.mcp.enabled", "true").expect("写开关");
+    set(&env, "agent.mcp.port", "48000").expect("写端口");
+    set(&env, "download.region", "cn").expect("写地区");
+
+    let groups = groups(&env);
+    let row = |key: &str| {
+        groups
+            .iter()
+            .flat_map(|g| g.rows.iter())
+            .find(|r| r.key == key)
+            .cloned()
+    };
+    assert_eq!(row("download.concurrency").unwrap().selected, 2);
+    assert!(row("agent.mcp.enabled").unwrap().flag);
+    assert_eq!(row("agent.mcp.port").unwrap().value_text, "48000");
+    assert_eq!(row("download.region").unwrap().selected, 1);
+
+    assert!(set(&env, "download.concurrency", "abc").is_err());
+    assert!(set(&env, "agent.mcp.enabled", "maybe").is_err());
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+#[test]
+fn detect_region_action_removes_cache() {
+    let dir = std::env::temp_dir().join(format!("ull-host-settings-r-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    let env = env_in(&dir);
+    let path = env.layout.cache().join("region.json");
+    std::fs::create_dir_all(env.layout.cache()).expect("cache");
+    std::fs::write(&path, "{}").expect("写缓存");
+    set(&env, "download.action.detect_region", "").expect("检测");
+    assert!(!path.exists());
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+/// **P1-1 的回归**：整窗透明度是 `ValueKind::Float` 的键，`SetSetting` 的载荷是字符串。
+///
+/// 历史（复审 r1 P1-1）：`parse_value` 只认硬编码的 Int/Bool 键名，Float 键被当成字符串交给
+/// `store.set`，schema 的 `as_f64()` 对 String 返回 None ⇒ `InvalidValue` ⇒ **`save()` 不执行**，
+/// 于是 α 只在内存生效、重启回旧值，且每次拖动弹一条 Error toast。
+///
+/// 抓得住：`set` → 落盘 → **新开一个 store（= 模拟重启）** 读回同一值。
+/// 抓不住：UI 侧是否真的把滑块接到 `SetSetting`（由 `app` 侧的 `on_appearance` 测试管）。
+#[test]
+fn float_key_round_trips_through_set_setting() {
+    let dir = std::env::temp_dir().join(format!("ull-host-settings-float-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    let env = env_in(&dir);
+
+    set(&env, "appearance.window_opacity", "0.8").expect("写整窗透明度");
+    set(&env, "appearance.panel_alpha", "0.55").expect("写面板透明度");
+
+    // 新开一个 store：从磁盘重新加载（等价「重启进程」）。
+    let reopened = env.store();
+    assert_eq!(
+        reopened.doc().effective_f64("appearance.window_opacity"),
+        Some(0.8)
+    );
+    assert_eq!(
+        reopened.doc().effective_f64("appearance.panel_alpha"),
+        Some(0.55)
+    );
+
+    // 越界仍然被 schema 拒绝（钳位在 core 的读侧，写侧是拒绝）。
+    assert!(set(&env, "appearance.window_opacity", "0.0").is_err());
+    // 非数字报人话，而不是「期望数字，实际是 \"abc\"」这种 schema 原话。
+    assert!(set(&env, "appearance.window_opacity", "abc").is_err());
+    assert!(set(&env, "appearance.window_opacity", "NaN").is_err());
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+/// **集合级守门（复审 P1-1 要求的那条）**：schema 里**每一个** `ValueKind::Float` 的键都必须
+/// 能被 `SetSetting` 写回，而不只是 `window_opacity`。
+///
+/// 为什么这条比单键测试重要：下次谁再加一个 Float 键（比如玻璃强度、模糊半径），
+/// 只要 `parse_value` 又退化成「硬编码表」，这里立刻红——单键测试抓不住新键。
+///
+/// 抓得住：类型解析与 `save()` 是否真的执行（读回是**新开 store**，走磁盘）。
+/// 抓不住：UI 控件是否接上了这些键（那是各页面的接线测试）。
+#[test]
+fn every_float_key_in_the_schema_can_be_written_back() {
+    let dir =
+        std::env::temp_dir().join(format!("ull-host-settings-allfloat-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    let env = env_in(&dir);
+
+    let schema = unlucky_core::setting::keys::launcher_schema();
+    let mut checked = 0_usize;
+    for spec in schema.specs() {
+        let unlucky_core::setting::spec::ValueKind::Float { min, max } = spec.kind else {
+            continue;
+        };
+        // 取一个落在 [min, max] 内的值（0.5 是多数区间的好选择，落不进时取中点）。
+        let target = if (min..=max).contains(&0.5) {
+            0.5
+        } else {
+            (min + max) / 2.0
+        };
+        set(&env, spec.key, &format!("{target}"))
+            .unwrap_or_else(|error| panic!("Float 键 {} 写不回：{error}", spec.key));
+        let reread = env
+            .store()
+            .doc()
+            .effective_f64(spec.key)
+            .unwrap_or_else(|| panic!("Float 键 {} 写完后读不到", spec.key));
+        assert!(
+            (reread - target).abs() < 1e-9,
+            "Float 键 {} 写 {target} 读回 {reread}",
+            spec.key
+        );
+        checked += 1;
+    }
+
+    assert!(
+        checked >= 3,
+        "schema 里 Float 键只剩 {checked} 个：本断言要求 ≥3（window_opacity / panel_alpha / bg_dim / ui.scale）。\
+         若是有意删减，请同步更新这条断言"
+    );
+    std::fs::remove_dir_all(&dir).ok();
+}
diff --git a/crates/presenter/src/host/versions.rs b/crates/presenter/src/host/versions.rs
new file mode 100644
index 0000000..32ddde4
--- /dev/null
+++ b/crates/presenter/src/host/versions.rs
@@ -0,0 +1,173 @@
+//! 版本清单（下载页）：远端 manifest（12h 缓存）+ 内嵌 unlisted 清单 → 分类好的行。
+//!
+//! 分类口径抄 analyse/03 §2.4：官方 `type` 决定 release/snapshot/远古；远古再按 id
+//! 前缀拆 classic（`rd-*`）/ old_alpha（`a*`）/ old_beta（`b*`），其余归 unlisted 汇总。
+//! 拉取失败但有旧缓存时用旧缓存（离线可用），全无才报错。
+
+use std::collections::BTreeSet;
+
+use unlucky_core::download::blocking::block_on;
+use unlucky_core::download::cache::now_ms;
+use unlucky_core::game::install::RemoteSource;
+use unlucky_core::game::unlisted;
+use unlucky_core::game::version::{ReleaseType, RemoteVersion};
+
+use crate::dto::{AncientKind, VersionKind, VersionSummary};
+
+use super::env::HostEnv;
+use super::job::{spawn, HostTask, JobSender};
+
+/// 版本 id / 官方类型 → 下载页的四种归类。
+pub fn kind_of(id: &str, release_type: ReleaseType) -> VersionKind {
+    match release_type {
+        ReleaseType::Release => VersionKind::Release,
+        ReleaseType::Snapshot | ReleaseType::Pending | ReleaseType::Unobfuscated => {
+            VersionKind::Snapshot
+        }
+        ReleaseType::OldAlpha | ReleaseType::OldBeta | ReleaseType::Modified => {
+            VersionKind::Ancient(ancient_kind(id))
+        }
+        ReleaseType::Unknown => {
+            if id.starts_with("rd-") || id.starts_with("a") || id.starts_with("b") {
+                VersionKind::Ancient(ancient_kind(id))
+            } else {
+                VersionKind::Release
+            }
+        }
+    }
+}
+
+/// 远古版子类（`rd-*` → classic；`a1.*` → old_alpha；`b1.*` → old_beta；其余 unlisted）。
+pub fn ancient_kind(id: &str) -> AncientKind {
+    if id.starts_with("rd-") || id.starts_with("inf-") {
+        AncientKind::Classic
+    } else if id.starts_with("a1.") || id.starts_with("a0.") || id.starts_with('a') {
+        AncientKind::OldAlpha
+    } else if id.starts_with("b1.") || id.starts_with('b') {
+        AncientKind::OldBeta
+    } else {
+        AncientKind::Unlisted
+    }
+}
+
+/// 发布日期取 `releaseTime` 的日期部分（缺失时退回 `time`，再退回空串）。
+fn released_of(version: &RemoteVersion) -> String {
+    version
+        .release_time
+        .as_deref()
+        .or(version.time.as_deref())
+        .map(|text| text.get(..10).unwrap_or(text).to_string())
+        .unwrap_or_default()
+}
+
+/// 拉清单并翻译成 DTO（安装状态按盘上版本判定）。
+fn fetch(env: &HostEnv) -> Result, 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..8c8d669
--- /dev/null
+++ b/crates/presenter/src/lib.rs
@@ -0,0 +1,120 @@
+//! Unlucky-Launcher 的 **UI 框架无关宿主层**（presenter）。
+//!
+//! # 1. 这层为什么存在
+//!
+//! D26 的技术路线是「用 iced 重写 UI」。重写只应该换掉**渲染**，不该重写业务装配——
+//! 本 crate 就是被两个 UI 版共用的那一半：Slint 版（`crates/app`）与 iced 版
+//! （`crates/app-iced`）都从这里取 DTO、状态 reducer 与 host。Slint 退役后只剩 iced
+//! 依赖它，本 crate 不受影响。
+//!
+//! 判据（M85 已核）：这套代码原本住在 `crates/app/src`，但 `host/`（25 个文件）、
+//! `state.rs`、`settings_bridge.rs`、`dto/` 里**没有一处** UI 框架符号；它们依赖的只有
+//! 标准库、serde 与 `unlucky-core`。把它们留在 UI crate 里等于让 iced 重写跟着重写一遍
+//! 约 5400 行，白担行为漂移的风险。
+//!
+//! # 2. 对外表面（UI 侧的唯一入口）
+//!
+//! ```text
+//! host::CoreHost ──impl Backend──► dto::AppEvent ──► state::AppState::apply ──► dto 快照
+//!        ▲                                              │
+//!        └──────────── dto::AppCommand ◄────────────────┘
+//! ```
+//!
+//! | 模块 | 入口 | UI 侧怎么用 |
+//! | ---- | ---- | ----------- |
+//! | [`dto`] | [`dto::Backend`] / [`dto::AppCommand`] / [`dto::AppEvent`] / 各 `*View` 快照 | 派发指令、消费事件、把快照字段映射成视图模型 |
+//! | [`host`] | [`host::CoreHost`]（实现 [`dto::Backend`]）、[`host::HostEnv`] | 进程启动时构造一次，之后只当 `Box` 用 |
+//! | [`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`、`loader_label`
+// 等）。它们原本住在 `crates/app` 里，由那边的 crate 级 `#![allow(dead_code)]` 一并放开；
+// 搬进 lib 之后「pub 但模块私有」会被判成死码。逐条 `#[allow]` 会把噪音藏进实现细节，
+// 这里沿用同一条策略统一放开，接线完成后再删掉本行暴露真死码。
+#![allow(dead_code)]
+
+pub mod agent;
+pub mod backend;
+pub mod dialogs;
+pub mod dto;
+pub mod host;
+pub mod mock;
+pub mod mock_data;
+pub mod prefs;
+pub mod router;
+pub mod settings_bridge;
+mod settings_bridge_lang;
+pub mod state;
+pub mod theme;
+pub mod toast;
+pub mod wizard;
diff --git a/crates/presenter/src/mock.rs b/crates/presenter/src/mock.rs
new file mode 100644
index 0000000..9ad3ea7
--- /dev/null
+++ b/crates/presenter/src/mock.rs
@@ -0,0 +1,399 @@
+//! P0 假后端：用脚本化事件驱动骨架，验证 app ↔ core/agent 通道语义。
+//!
+//! 覆盖四条通道：实例运行状态（磁贴进度环）、AI 流式会话（含工具调用）、
+//! 对话框队列（进度对话框）、Toast。阶段 B 里由真正的 core/agent host 替换
+//! [`MockBackend`]，[`crate::dto::Backend`] 之上的 state/reducer 不动。
+//! 假数据本体在 [`crate::mock_data`]。
+
+use std::collections::VecDeque;
+use std::time::Duration;
+
+use crate::dialogs::{DialogKind, DialogRequest, DialogSource};
+use crate::dto::{
+    AgentEvent, AppCommand, AppEvent, Backend, ChatMessage, ChatRole, CoreEvent, InstanceId,
+    InstanceRuntime, LaunchStage, Progress,
+};
+use crate::mock_data::{mock_log_lines, mock_log_sessions, mock_versions};
+use crate::toast::{Toast, ToastKind};
+
+#[path = "mock/accounts.rs"]
+mod accounts_screen;
+#[path = "mock/instances.rs"]
+mod instances_screen;
+
+/// 启动脚本：按时间推进 download → verify → launch → running。
+#[derive(Debug)]
+struct LaunchScript {
+    id: InstanceId,
+    elapsed_ms: u64,
+}
+
+/// AI 流式脚本：每条提问回一段可切分的话 + 一次工具调用。
+#[derive(Debug)]
+struct ChatScript {
+    elapsed_ms: u64,
+    chunks: VecDeque,
+    /// 流式助手消息在 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..edc1fd9
--- /dev/null
+++ b/crates/presenter/src/mock_data.rs
@@ -0,0 +1,238 @@
+//! P0 假数据：实例 / 版本 / 日志 / 诊断 / 工具调用样例。
+//!
+//! 只被 [`crate::mock`] 与阶段 B 的 main.rs 使用；真实后端接入后整文件可删。
+
+use crate::dto::{
+    AncientKind, ChatMessage, ChatRole, Diagnosis, DiagnosisReport, InstanceRuntime,
+    InstanceSummary, LoaderInfo, LoaderKind, LogLevel, LogLine, LogOutcome, LogSession, SessionId,
+    ToolCallView, VersionCategory, VersionKind, VersionSummary,
+};
+
+/// P0 演示实例：覆盖空闲 / 失败两种磁贴状态（运行中由启动脚本产生）。
+pub fn mock_instances() -> Vec {
+    vec![
+        InstanceSummary {
+            id: "survival".to_string(),
+            name: "生存整合包".to_string(),
+            mc_version: "1.20.4".to_string(),
+            loader: LoaderInfo {
+                kind: LoaderKind::Fabric,
+                version: "0.16.5".to_string(),
+            },
+            last_played: Some("2026-10-29T19:22:00Z".to_string()),
+            runtime: InstanceRuntime::Idle,
+            icon: None,
+            isolation: "isolated".to_string(),
+            version_id: "1.20.4".to_string(),
+            version_present: true,
+        },
+        InstanceSummary {
+            id: "vanilla-latest".to_string(),
+            name: "原版最新".to_string(),
+            mc_version: "1.21.9".to_string(),
+            loader: LoaderInfo {
+                kind: LoaderKind::Vanilla,
+                version: String::new(),
+            },
+            last_played: Some("2026-10-28T21:03:00Z".to_string()),
+            runtime: InstanceRuntime::Idle,
+            icon: None,
+            isolation: "isolated".to_string(),
+            version_id: "1.21.9".to_string(),
+            version_present: true,
+        },
+        InstanceSummary {
+            id: "ancient-1.7.10".to_string(),
+            name: "远古 1.7.10".to_string(),
+            mc_version: "1.7.10".to_string(),
+            loader: LoaderInfo {
+                kind: LoaderKind::Forge,
+                version: "10.13.4.1614".to_string(),
+            },
+            last_played: None,
+            runtime: InstanceRuntime::Idle,
+            icon: None,
+            isolation: "shared".to_string(),
+            version_id: "1.7.10".to_string(),
+            version_present: false,
+        },
+        InstanceSummary {
+            id: "modded-dev".to_string(),
+            name: "开发测试".to_string(),
+            mc_version: "1.21.1".to_string(),
+            loader: LoaderInfo {
+                kind: LoaderKind::NeoForge,
+                version: "21.1.72".to_string(),
+            },
+            last_played: Some("2026-10-27T12:40:00Z".to_string()),
+            runtime: InstanceRuntime::Failed {
+                reason: "exit0 静默失败".to_string(),
+            },
+            icon: None,
+            isolation: "isolated".to_string(),
+            version_id: "1.21.1-neoforge-21.1.72".to_string(),
+            version_present: true,
+        },
+    ]
+}
+
+/// P0 演示版本列表（含远古版三子类，验证分类侧栏与警示徽标）。
+pub fn mock_versions() -> Vec {
+    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()
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::dto::{AncientKind, VersionCategory, VersionKind};
+    use crate::mock_data::{mock_instances, mock_versions_for};
+
+    #[test]
+    fn mock_instances_cover_the_tile_states() {
+        let instances = mock_instances();
+        assert_eq!(instances.len(), 4);
+        assert!(instances.iter().any(|instance| matches!(
+            instance.runtime,
+            crate::dto::InstanceRuntime::Failed { .. }
+        )));
+    }
+
+    #[test]
+    fn versions_are_filtered_by_category() {
+        let release = mock_versions_for(VersionCategory::Release);
+        assert!(release
+            .iter()
+            .all(|version| version.kind == VersionKind::Release));
+        assert_eq!(release.len(), 3);
+
+        let classic = mock_versions_for(VersionCategory::Ancient(AncientKind::Classic));
+        assert_eq!(classic.len(), 1);
+        assert_eq!(classic[0].id, "rd-132211");
+
+        assert!(mock_versions_for(VersionCategory::Mod).is_empty());
+    }
+}
diff --git a/crates/presenter/src/prefs.rs b/crates/presenter/src/prefs.rs
new file mode 100644
index 0000000..a0dc13a
--- /dev/null
+++ b/crates/presenter/src/prefs.rs
@@ -0,0 +1,333 @@
+//! UI 偏好项与持久化键登记（导航折叠、AI 栏折叠、磁贴尺寸、视图、主题三态与外观四件、下载分类）。
+//!
+//! 偏好不自己写盘：core::setting 的 schema 按 [`keys::ALL`] 登记这些键，
+//! app 启动时读一次、变更时写回（跨模块约定见 `DevDocs/SubAgentsTalk/app-DTO通道约定.md`）。
+//! 落盘实现是 [`crate::settings_bridge`]（同一份 `config/launcher.json`，与 `ull config set` 同源），
+//! 主题三态 + `appearance.*` 高级键已接（M41）；其余 UI 偏好键仍只在内存里（后续 mission 接）。
+
+/// 背景图填充模式（09 §101）。直接复用 core 的枚举：取值与落盘词表只有一处真相。
+pub use unlucky_core::setting::appearance::BgFill;
+
+pub use unlucky_core::setting::appearance::PALETTE_SOURCES;
+/// 外观下层的三张表/常量（D36·D37·D38）：复用 core 的定义，一处真相。
+///
+/// [`WINDOW_ALPHA_MIN`] 还要给 `unlucky-app-iced` 的 win32 α 层用（它只依赖本 crate，不直接依赖
+/// core）：窗口 α 的硬底必须与设置侧同源，两边各写一个 `0.08` 迟早会漂。
+///
+/// 同理 [`PANEL_ALPHA_MIN`]（0.4）与 [`BG_DIM_MAX`]（0.95）也在这里重导出：M93 的 UI 侧要按它们
+/// 钳位滑块与暗化，而 `app-iced` 不直接依赖 core——不重导出就只能各抄一份字面量。
+pub use unlucky_core::setting::appearance::{
+    PaletteSource, TitlebarMode, WindowCorner, BG_DIM_MAX, PANEL_ALPHA_MIN, WINDOW_ALPHA_MIN,
+    WINDOW_CORNERS,
+};
+
+/// 系统版本探测（M116）：Windows 侧「能不能用 DWM 圆角」的判据要 build 号，而
+/// `unlucky-app-iced` 不直接依赖 `unlucky-core`（分层：UI → presenter → core），
+/// 所以在这里做**唯一一次**重导出，`platform` 只认 [`WindowsVersion`]。
+///
+/// [`WIN11_MIN_BUILD`] = 22000：Win11 与 Server 2025 共用同一内核判据（M116 实测本机
+/// Server 2025 build 26100 落在这条线之上）。
+pub use unlucky_core::platform::windows_version::{
+    probe as probe_windows_version, WindowsVersion, WIN11_MIN_BUILD,
+};
+
+use crate::dto::VersionCategory;
+
+/// 预设强调色板（09 §104）。**必须**与 UI 侧设置页「外观」分组的色板控件同序同值：
+/// UI 侧只回传索引，十六进制串由这张表给出（一处真相）。
+pub const ACCENT_PRESETS: [&str; 8] = [
+    "#0078D4", "#0F6CBD", "#107C10", "#9D5D00", "#C42B1C", "#8764B8", "#C239B3", "#00B7C3",
+];
+
+/// 磁贴尺寸（Q24-3：小 6 列 / 中 4 列 / 大 3 列）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum TileSize {
+    /// 小：6 列，只留图标/名字/启动键
+    Small,
+    /// 中：4 列（D16 默认）
+    #[default]
+    Medium,
+    /// 大：3 列，显示完整徽标与最后游玩时间
+    Large,
+}
+
+impl TileSize {
+    /// 该尺寸对应的网格列数。
+    pub fn columns(self) -> usize {
+        match self {
+            Self::Small => 6,
+            Self::Medium => 4,
+            Self::Large => 3,
+        }
+    }
+
+    /// 设置页/实例页分段控件的文案。
+    pub fn label(self) -> &'static str {
+        match self {
+            Self::Small => "小",
+            Self::Medium => "中",
+            Self::Large => "大",
+        }
+    }
+}
+
+/// 实例页视图模式。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum InstanceView {
+    /// 磁贴网格（默认）
+    #[default]
+    Tiles,
+    /// 紧凑列表
+    List,
+}
+
+/// 主题三态（D17，P0 交付）：`appearance.theme_mode ∈ {light, dark, auto}`，出厂 auto。
+///
+/// `auto` = 跟随系统（由 UI 侧的令牌层读系统调色板，随 OS 热更；探测口径见
+/// [`crate::theme::system_theme_value`]）；`light` / `dark` 钉死**自绘体系**的取值。
+/// 三个取值怎么变成框架颜色是 UI 侧的事，本 crate 只给语义。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum ThemeMode {
+    /// 跟随系统（默认）
+    #[default]
+    Auto,
+    /// 强制浅色
+    Light,
+    /// 强制深色
+    Dark,
+}
+
+impl ThemeMode {
+    /// 落盘取值（`appearance.theme_mode`）：`auto` / `light` / `dark`。
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Auto => "auto",
+            Self::Light => "light",
+            Self::Dark => "dark",
+        }
+    }
+
+    /// 从落盘取值解析；未知值按 `auto` 兜底（配置被手改坏也不崩）。
+    pub fn from_key_value(value: &str) -> Self {
+        match value {
+            "light" => Self::Light,
+            "dark" => Self::Dark,
+            _ => Self::Auto,
+        }
+    }
+}
+
+/// 09 §101-104「外观（高级）」四件的取值快照（出厂全部关闭）。
+///
+/// 与 `unlucky_core::setting::appearance::Appearance` 一一对应，但字段类型是 UI 侧好用的
+/// `f32`/`String`；落盘由 [`crate::settings_bridge`] 转成 schema 键。
+#[derive(Debug, Clone, PartialEq, Default)]
+pub struct AppearancePrefs {
+    /// 背景图总开关
+    pub bg_image_enabled: bool,
+    /// 背景图路径（PNG；空 = 未设置）
+    pub bg_image: String,
+    /// 填充模式
+    pub bg_fill: BgFill,
+    /// 暗化层强度 0.0~0.9
+    pub bg_dim: f32,
+    /// 面板半透明度 0.4~1.0
+    pub panel_alpha: f32,
+    /// 玻璃拟态卡片
+    pub glass: bool,
+    /// 自定义强调色 `#RRGGBB`；空 = 出厂 [#0078D4]
+    pub accent_color: String,
+}
+
+impl AppearancePrefs {
+    /// 出厂态：Metro 纯色，四个高级特性全关。
+    pub fn factory() -> Self {
+        Self {
+            bg_image_enabled: false,
+            bg_image: String::new(),
+            bg_fill: BgFill::Cover,
+            bg_dim: 0.35,
+            panel_alpha: 1.0,
+            glass: false,
+            accent_color: String::new(),
+        }
+    }
+
+    /// 背景图是否真的生效（开关打开且路径非空）。
+    pub fn bg_active(&self) -> bool {
+        self.bg_image_enabled && !self.bg_image.trim().is_empty()
+    }
+
+    /// 规范化写入强调色：`#RRGGBB` 才接受（空串 = 恢复出厂）。
+    ///
+    /// 返回 `false` 表示输入不合法（调用方据此亮设置页的 warn 行，不改现状）。
+    pub fn set_accent(&mut self, text: &str) -> bool {
+        let trimmed = text.trim();
+        if trimmed.is_empty() {
+            self.accent_color.clear();
+            return true;
+        }
+        match unlucky_core::setting::appearance::normalize_hex(trimmed) {
+            Some(hex) => {
+                self.accent_color = hex;
+                true
+            }
+            None => false,
+        }
+    }
+
+    /// 用预设色板第 `index` 个颜色（越界忽略）。
+    pub fn set_accent_preset(&mut self, index: usize) -> bool {
+        match ACCENT_PRESETS.get(index) {
+            Some(hex) => self.set_accent(hex),
+            None => false,
+        }
+    }
+}
+
+/// 外观下层的**只读**快照：整窗 α / 标题栏三态 / 配色来源 / 窗口圆角（D36·D37·D38 · M116）。
+///
+/// 不并进 [`AppearancePrefs`] 的两个理由：那个结构体由 `settings_bridge` 逐字段字面量
+/// 构造（加字段就得改那边），且这**四个**键只读不写——落盘仍走 core 的 `Appearance::write`。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct AppearanceBase {
+    /// 整窗透明度 [`WINDOW_ALPHA_MIN`]~1.0（1.0 = 完全不透明）
+    pub window_opacity: f32,
+    /// 标题栏三态（`auto` 的具体判定属于 UI 侧，本 crate 只给值）
+    pub titlebar_mode: TitlebarMode,
+    /// 配色来源档（三级编排在 `unlucky-design`，本 crate 只给值）
+    pub palette_source: PaletteSource,
+    /// 窗口外框圆角策略（M116：`system` / `square`；能不能圆由平台决定）
+    pub window_corner: WindowCorner,
+}
+
+impl AppearanceBase {
+    /// 出厂态：不透明 / `auto` / 内置色卡 / 跟随系统圆角。
+    #[must_use]
+    pub fn factory() -> Self {
+        Self {
+            window_opacity: 1.0,
+            titlebar_mode: TitlebarMode::Auto,
+            palette_source: PaletteSource::Preset,
+            window_corner: WindowCorner::System,
+        }
+    }
+
+    /// 从配置文档读一份快照：缺键 → 出厂默认、越界 → 钳位、非法枚举 → 回落。
+    ///
+    /// 三条语义都在 core 里落地（本函数只搬运，不重新判一遍）。
+    #[must_use]
+    pub fn from_document(doc: &unlucky_core::setting::document::SettingDocument) -> Self {
+        let appearance = unlucky_core::setting::appearance::Appearance::read(doc);
+        Self {
+            window_opacity: appearance.window_opacity as f32,
+            titlebar_mode: appearance.titlebar_mode,
+            palette_source: appearance.palette_source,
+            window_corner: appearance.window_corner,
+        }
+    }
+
+    /// 整窗 α 是否需要真的落到窗口上（1.0 = 不透明，调 FFI 纯属多余）。
+    #[must_use]
+    pub fn is_transparent(&self) -> bool {
+        self.window_opacity < 1.0
+    }
+}
+
+/// 需要跨会话记忆的 UI 偏好。
+///
+/// 注意：`Eq` 不成立（[`AppearancePrefs`] 带 `f32` 滑条值），用到的地方按 `PartialEq` 比。
+#[derive(Debug, Clone, PartialEq)]
+pub struct UiPrefs {
+    /// 左侧导航栏折叠成图标条
+    pub nav_collapsed: bool,
+    /// 右侧 AI 栏折叠成 icon 轨
+    pub ai_collapsed: bool,
+    /// 磁贴尺寸
+    pub tile_size: TileSize,
+    /// 实例页视图
+    pub instance_view: InstanceView,
+    /// 主题模式
+    pub theme: ThemeMode,
+    /// 外观（高级）四件（09 §101-104）
+    pub appearance: AppearancePrefs,
+    /// 下载页选中的分类
+    pub download_category: VersionCategory,
+}
+
+impl Default for UiPrefs {
+    fn default() -> Self {
+        Self {
+            nav_collapsed: false,
+            ai_collapsed: false,
+            // D16 默认中磁贴（4 列）
+            tile_size: TileSize::Medium,
+            instance_view: InstanceView::Tiles,
+            theme: ThemeMode::Auto,
+            appearance: AppearancePrefs::factory(),
+            download_category: VersionCategory::Release,
+        }
+    }
+}
+
+/// 持久化键名登记（core::setting schema 按此注册；改名等于迁移，慎动）。
+pub mod keys {
+    /// 导航栏折叠
+    pub const NAV_COLLAPSED: &str = "ui.nav.collapsed";
+    /// AI 栏折叠
+    pub const AI_COLLAPSED: &str = "ui.ai.collapsed";
+    /// 磁贴尺寸
+    pub const TILE_SIZE: &str = "ui.instances.tile_size";
+    /// 实例页视图（磁贴/列表）
+    pub const INSTANCE_VIEW: &str = "ui.instances.view";
+    /// 主题三态（D17；与设置页「外观」分组同名，取值见 [`super::ThemeMode::as_str`]）
+    pub const THEME_MODE: &str = "appearance.theme_mode";
+    /// 背景图开关（09 §101）
+    pub const BG_IMAGE_ENABLED: &str = "appearance.bg_image_enabled";
+    /// 背景图路径
+    pub const BG_IMAGE: &str = "appearance.bg_image";
+    /// 背景图填充模式
+    pub const BG_FILL: &str = "appearance.bg_fill";
+    /// 暗化层强度
+    pub const BG_DIM: &str = "appearance.bg_dim";
+    /// 面板半透明度（09 §102）
+    pub const PANEL_ALPHA: &str = "appearance.panel_alpha";
+    /// 玻璃拟态卡片（09 §103）
+    pub const GLASS: &str = "appearance.glass";
+    /// 自定义强调色（09 §104）
+    pub const ACCENT_COLOR: &str = "appearance.accent_color";
+    /// 下载页分类
+    pub const DOWNLOAD_CATEGORY: &str = "ui.download.category";
+    /// 整窗透明度（D36；下限见 [`super::WINDOW_ALPHA_MIN`]）
+    pub const WINDOW_OPACITY: &str = "appearance.window_opacity";
+    /// 标题栏三态（D37）
+    pub const TITLEBAR_MODE: &str = "appearance.titlebar_mode";
+    /// 配色来源档（D38）
+    pub const PALETTE_SOURCE: &str = "appearance.palette_source";
+    /// 窗口圆角策略（M116；`system` / `square`）
+    pub const WINDOW_CORNER: &str = "appearance.window_corner";
+
+    /// 本模块登记的全部键（自检/迁移用）。
+    pub const ALL: [&str; 17] = [
+        NAV_COLLAPSED,
+        AI_COLLAPSED,
+        TILE_SIZE,
+        INSTANCE_VIEW,
+        THEME_MODE,
+        BG_IMAGE_ENABLED,
+        BG_IMAGE,
+        BG_FILL,
+        BG_DIM,
+        PANEL_ALPHA,
+        GLASS,
+        ACCENT_COLOR,
+        DOWNLOAD_CATEGORY,
+        WINDOW_OPACITY,
+        TITLEBAR_MODE,
+        PALETTE_SOURCE,
+        WINDOW_CORNER,
+    ];
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/presenter/src/prefs/tests.rs b/crates/presenter/src/prefs/tests.rs
new file mode 100644
index 0000000..2cb058d
--- /dev/null
+++ b/crates/presenter/src/prefs/tests.rs
@@ -0,0 +1,109 @@
+//! `prefs` 的单测（拆文件守 400 行上限；结构体与 re-export 一律留在 `prefs.rs`）。
+
+use super::{
+    keys, AppearanceBase, InstanceView, PaletteSource, ThemeMode, TileSize, TitlebarMode, UiPrefs,
+    WindowCorner, WINDOW_ALPHA_MIN,
+};
+
+#[test]
+fn defaults_match_d16() {
+    let prefs = UiPrefs::default();
+    assert_eq!(prefs.tile_size, TileSize::Medium);
+    assert_eq!(prefs.tile_size.columns(), 4);
+    assert_eq!(prefs.instance_view, InstanceView::Tiles);
+    assert_eq!(prefs.theme, ThemeMode::Auto);
+    assert_eq!(prefs.theme.as_str(), "auto");
+    assert!(!prefs.nav_collapsed);
+    assert!(!prefs.ai_collapsed);
+}
+
+#[test]
+fn tile_size_columns_follow_q24() {
+    assert_eq!(TileSize::Small.columns(), 6);
+    assert_eq!(TileSize::Medium.columns(), 4);
+    assert_eq!(TileSize::Large.columns(), 3);
+}
+
+#[test]
+fn theme_mode_round_trips_through_key_values() {
+    for mode in [ThemeMode::Auto, ThemeMode::Light, ThemeMode::Dark] {
+        assert_eq!(ThemeMode::from_key_value(mode.as_str()), mode);
+    }
+    // 坏值兜底
+    assert_eq!(ThemeMode::from_key_value("solarized"), ThemeMode::Auto);
+}
+
+#[test]
+fn pref_keys_are_unique() {
+    let mut keys = keys::ALL.to_vec();
+    let total = keys.len();
+    keys.sort_unstable();
+    keys.dedup();
+    assert_eq!(keys.len(), total);
+}
+
+fn base_of(raw: serde_json::Value) -> AppearanceBase {
+    let schema = unlucky_core::setting::keys::launcher_schema();
+    let (doc, _) = unlucky_core::setting::document::SettingDocument::load(&schema, &raw);
+    AppearanceBase::from_document(&doc)
+}
+
+#[test]
+fn appearance_base_missing_keys_use_factory() {
+    let base = base_of(serde_json::json!({}));
+    assert_eq!(
+        base,
+        AppearanceBase::factory(),
+        "缺键 → 出厂态（不透明 / auto / preset）"
+    );
+    assert!(!base.is_transparent(), "出厂不透明 → 不下发窗口 α");
+}
+
+#[test]
+fn appearance_base_clamps_out_of_range_opacity() {
+    for raw in [0.0, 0.02, -1.0] {
+        let base = base_of(serde_json::json!({ "appearance": { "window_opacity": raw } }));
+        assert_eq!(
+            base.window_opacity, WINDOW_ALPHA_MIN as f32,
+            "raw={raw} 应夹到下限"
+        );
+    }
+    for (raw, want) in [(0.6, 0.6), (3.0, 1.0)] {
+        let base = base_of(serde_json::json!({ "appearance": { "window_opacity": raw } }));
+        assert_eq!(base.window_opacity, want, "raw={raw}");
+    }
+}
+
+#[test]
+fn appearance_base_illegal_enums_fall_back_and_legal_ones_read_through() {
+    let bad = base_of(serde_json::json!({
+        "appearance": { "titlebar_mode": "allways", "palette_source": "desktop" }
+    }));
+    assert_eq!(bad.titlebar_mode, TitlebarMode::Auto, "非法 → auto");
+    assert_eq!(bad.palette_source, PaletteSource::Preset, "非法 → preset");
+    // 合法值必须照读：否则「回落」测试会因为实现恒回默认而假绿。
+    let good = base_of(serde_json::json!({
+        "appearance": { "titlebar_mode": "never", "palette_source": "wallpaper" }
+    }));
+    assert_eq!(good.titlebar_mode, TitlebarMode::Never);
+    assert_eq!(good.palette_source, PaletteSource::Wallpaper);
+}
+
+/// **M116**：`appearance.window_corner` 的读侧——缺键 = 跟随系统、写 `square` 读回 `square`。
+///
+/// 抓得住：`AppearanceBase::from_document` 漏搬这一格（那会让设置页永远显示「跟随系统」，
+/// 用户点了直角重启后又变回去）。
+/// 抓不住：这台机器能不能真圆（`app-iced` 的 `platform::plan_corner` 管）。
+#[test]
+fn window_corner_round_trips_through_the_document() {
+    assert_eq!(
+        base_of(serde_json::json!({})).window_corner,
+        WindowCorner::System,
+        "缺键 → 出厂跟随系统"
+    );
+    let square = base_of(serde_json::json!({ "appearance": { "window_corner": "square" } }));
+    assert_eq!(square.window_corner, WindowCorner::Square);
+    // 坏值：core 侧落到 system（并留诊断），这里只钉 UI 侧看到的值。
+    let broken = base_of(serde_json::json!({ "appearance": { "window_corner": "rounded" } }));
+    assert_eq!(broken.window_corner, WindowCorner::System);
+}
diff --git a/crates/presenter/src/router.rs b/crates/presenter/src/router.rs
new file mode 100644
index 0000000..5a38e21
--- /dev/null
+++ b/crates/presenter/src/router.rs
@@ -0,0 +1,200 @@
+//! 页面路由与 AI 助手栏形态（09 §1 / D16）。
+//!
+//! 栈语义抄 HMCL 的导航栈：**顶层页面互相替换**（实例/下载/日志/设置），
+//! 子页面（实例详情、AI 独立页）压栈，`back()` 逐层回退。
+//! 本模块刻意不依赖 Slint 类型，便于单元测试；UI 侧枚举映射在 main.rs 的转换层做。
+
+use crate::dto::InstanceId;
+
+/// 一级导航项（左侧导航栏高亮单位）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum NavSection {
+    /// 实例
+    Instances,
+    /// 下载 / 版本管理 + 内容库（M109：内容库复用这一项，不新增第 6 个图标）
+    Download,
+    /// 日志
+    Logs,
+    /// 设置
+    Settings,
+}
+
+/// 页面路由。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Route {
+    /// G1 实例页（主页）
+    Instances,
+    /// G2 下载页（M107/M108 起是「版本管理」）
+    Download,
+    /// 内容库（M109）：整合包 / Mod / 资源包 / 光影，来源 Modrinth / CurseForge
+    ///
+    /// 它是**顶层页**（跟版本管理一样整栈替换），但高亮复用 [`NavSection::Download`]：
+    /// 用户令「下载页只负责下载整合包和Mod/光影」⇒ 同一入口下两块内容，不是一个新图标。
+    Content,
+    /// G3 日志页
+    Logs,
+    /// G6 设置页
+    Settings,
+    /// G7 账户页（三轨登录：微软正版 / 第三方皮肤站 / 本地档案）
+    ///
+    /// 一级页，但**不进主序列**：入口是导航轨底部的头像位（`shell/nav.rs`），
+    /// 所以 [`Route::nav`] 对它返回 `None`（不点亮四个主项中的任何一个）。
+    Accounts,
+    /// 实例详情（G4）：从磁贴点进来，返回时回到实例页
+    Detail(InstanceId),
+    /// AI 助手独立页（D16 双形态之一）
+    Agent,
+}
+
+impl Route {
+    /// 是否是一级导航页（互相替换，不进栈）。
+    pub fn is_top_level(&self) -> bool {
+        matches!(
+            self,
+            // M109 的 `Content` 与 M114 的 `Accounts` 都是一级页：两个都留。
+            Self::Instances
+                | Self::Download
+                | Self::Content
+                | Self::Logs
+                | Self::Settings
+                | Self::Accounts
+        )
+    }
+
+    /// 该路由高亮哪个导航项（None = 没有导航项高亮，如 AI 独立页）。
+    pub fn nav(&self) -> Option {
+        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..3b9021c
--- /dev/null
+++ b/crates/presenter/src/settings_bridge.rs
@@ -0,0 +1,352 @@
+//! 设置持久化桥：把 UI 偏好落到 `core::setting` 的 schema 文件里，并支持**外部热改热切**。
+//!
+//! 三条纪律（`DevDocs/SubAgentsTalk/app-DTO通道约定.md` §6 / AGENTS §6）：
+//!
+//! 1. **不另立配置文件**：读写的就是 `ull config set/get` 与 AI `set_config` 用的那一份
+//!    `/config/launcher.json`（`core::platform::data_dir` 解析数据根、`layout` 给路径）；
+//! 2. **不自己拼 JSON**：一律过 `core::setting::store::SettingStore`（schema 校验 + 原子写）；
+//! 3. **不 import 领域类型**：跨边界只看「键名 + 取值」，领域模型留在 core。
+//!
+//! 热切：文件 `mtime` 变了就整份重读（AI / CLI 改完下一拍即生效），见 [`SettingsBridge::reload_if_changed`]。
+
+use std::path::{Path, PathBuf};
+use std::time::SystemTime;
+
+use unlucky_core::platform::data_dir::{DataDirRequest, DataMode, Resolver};
+use unlucky_core::platform::layout::LauncherLayout;
+use unlucky_core::platform::paths::Platform;
+use unlucky_core::setting::appearance::Appearance;
+use unlucky_core::setting::keys::launcher_schema;
+use unlucky_core::setting::store::SettingStore;
+
+use crate::prefs::{AppearanceBase, AppearancePrefs, ThemeMode};
+
+/// 数据根配置键（决定 `launcher.json` 落在哪个数据目录；与 CLI 的 `DATA_ROOT_KEYS` 同源同义）。
+const DATA_ROOT_KEYS: [&str; 4] = [
+    "core.data_mode",
+    "core.data_custom_root",
+    "core.launcher_home",
+    "core.game_home",
+];
+
+/// 设置文件桥（一个进程一份）。
+#[derive(Debug)]
+pub struct SettingsBridge {
+    /// `config/launcher.json`；`None` = 数据根解析不出来（内存态运行，不落盘）
+    pub(super) path: Option,
+    /// 设置文档（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 卡住，诊断走日志）。
+    pub fn persist(&mut self, appearance: &AppearancePrefs, theme: ThemeMode) {
+        let Some(store) = self.store.as_mut() else {
+            return;
+        };
+        let mut snapshot = Appearance::from_store(store);
+        snapshot.theme_mode = theme.as_str().to_owned();
+        snapshot.bg_image_enabled = appearance.bg_image_enabled;
+        snapshot.bg_image = appearance.bg_image.clone();
+        snapshot.bg_fill = appearance.bg_fill;
+        snapshot.bg_dim = f64::from(appearance.bg_dim);
+        snapshot.panel_alpha = f64::from(appearance.panel_alpha);
+        snapshot.glass = appearance.glass;
+        snapshot.accent_color = appearance.accent_color.clone();
+        if snapshot.write(store).is_err() {
+            return;
+        }
+        let _ = store.save();
+        if let Some(path) = self.path() {
+            self.last_mtime = mtime(path);
+        }
+    }
+
+    /// 文件被外部（AI / `ull config set`）改过就重读；返回新的生效值。
+    ///
+    /// `mtime` 采样不到（某些文件系统精度/权限）时返回 `None`，退化为「只在启动时读一次」。
+    pub fn reload_if_changed(&mut self) -> Option<(AppearancePrefs, ThemeMode)> {
+        let path = self.path.clone()?;
+        let current = mtime(&path);
+        if current.is_none() || current == self.last_mtime {
+            return None;
+        }
+        self.last_mtime = current;
+        let store = self.store.as_mut()?;
+        store.reload();
+        Some(self.load())
+    }
+}
+
+/// 数据根解析 → `config/launcher.json`。
+///
+/// 与 CLI 同一套语义：先读便携目录那份 `launcher.json` 的 `core.*`（数据根决定键），
+/// 再交 `Resolver` 解析（含 `redirect.json` 跟随）。任何一步失败都退回内存态。
+fn resolve_config_path() -> Option {
+    let exe_dir = std::env::current_exe()
+        .ok()
+        .and_then(|path| path.parent().map(Path::to_path_buf));
+    let exe_dir = exe_dir?;
+    let request = request_from_portable(&exe_dir);
+    let resolver = Resolver::new(Platform::current(), Some(exe_dir.clone()));
+    match resolver.resolve_default(&request) {
+        Ok(resolved) => Some(resolved.layout().launcher_config()),
+        // 连 exe 目录都解析不了（极端情况）：仍旧用便携落点，至少设置能存下来
+        Err(_) => Some(LauncherLayout::new(exe_dir.join(".ULL")).launcher_config()),
+    }
+}
+
+/// 便携目录那份 `launcher.json` → 三模式请求（只读 `core.*` 四个键）。
+fn request_from_portable(exe_dir: &Path) -> DataDirRequest {
+    let mut request = DataDirRequest::default();
+    let path = portable_config_path(exe_dir);
+    if !path.is_file() {
+        return request;
+    }
+    let store = SettingStore::load(&path, launcher_schema());
+    let text = |key: &str| store.doc().effective_str(key).map(str::to_string);
+    if let Some(mode) = text(DATA_ROOT_KEYS[0]).as_deref().and_then(DataMode::parse) {
+        request.mode = mode;
+    }
+    if let Some(root) = text(DATA_ROOT_KEYS[1]) {
+        request.custom_root = Some(PathBuf::from(root));
+    }
+    if let Some(home) = text(DATA_ROOT_KEYS[2]) {
+        request.launcher_home = Some(PathBuf::from(home));
+    }
+    if let Some(home) = text(DATA_ROOT_KEYS[3]) {
+        request.game_home = Some(PathBuf::from(home));
+    }
+    request
+}
+
+/// `/.ULL/config/launcher.json`。
+fn portable_config_path(exe_dir: &Path) -> PathBuf {
+    LauncherLayout::new(exe_dir.join(".ULL")).launcher_config()
+}
+
+fn mtime(path: &Path) -> Option {
+    std::fs::metadata(path).ok()?.modified().ok()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::prefs::PaletteSource;
+    use unlucky_core::setting::appearance::BgFill;
+
+    fn temp_config(label: &str) -> PathBuf {
+        let dir = std::env::temp_dir().join(format!(
+            "ull-bridge-{label}-{}-{}",
+            std::process::id(),
+            line!()
+        ));
+        std::fs::create_dir_all(dir.join("config")).expect("临时目录");
+        let path = dir.join("config/launcher.json");
+        let _ = std::fs::remove_file(&path);
+        path
+    }
+
+    #[test]
+    fn factory_defaults_when_file_missing() {
+        let path = temp_config("factory");
+        let bridge = SettingsBridge::with_path(&path);
+        let (appearance, theme) = bridge.load();
+        assert_eq!(appearance, AppearancePrefs::factory());
+        assert_eq!(theme, ThemeMode::Auto);
+        assert!(!path.exists(), "只读不写：缺文件不该被创建");
+        std::fs::remove_dir_all(path.parent().unwrap().parent().unwrap()).ok();
+    }
+
+    #[test]
+    fn persist_then_reload_round_trips() {
+        let path = temp_config("roundtrip");
+        let mut bridge = SettingsBridge::with_path(&path);
+        let mut appearance = AppearancePrefs::factory();
+        appearance.bg_image_enabled = true;
+        appearance.bg_image = "D:/wall/p.png".to_owned();
+        appearance.bg_fill = BgFill::Contain;
+        appearance.bg_dim = 0.5;
+        appearance.panel_alpha = 0.8;
+        appearance.glass = true;
+        assert!(appearance.set_accent("#0f6cbd"));
+        bridge.persist(&appearance, ThemeMode::Dark);
+
+        let reloaded = SettingsBridge::with_path(&path);
+        let (value, theme) = reloaded.load();
+        assert_eq!(value, appearance);
+        assert_eq!(theme, ThemeMode::Dark);
+        std::fs::remove_dir_all(path.parent().unwrap().parent().unwrap()).ok();
+    }
+
+    #[test]
+    fn external_edit_is_picked_up_by_reload() {
+        let path = temp_config("hotreload");
+        let mut bridge = SettingsBridge::with_path(&path);
+        // 先落一份（建立 mtime 基线）
+        bridge.persist(&AppearancePrefs::factory(), ThemeMode::Light);
+        assert!(bridge.reload_if_changed().is_none(), "自己写完不该报告变更");
+
+        // 模拟外部写入（AI / `ull config set`）：改主题 + 打开背景图
+        let mut external = SettingsBridge::with_path(&path);
+        let mut appearance = AppearancePrefs::factory();
+        appearance.bg_image_enabled = true;
+        appearance.bg_image = "D:/wall/x.png".to_owned();
+        external.persist(&appearance, ThemeMode::Dark);
+
+        // mtime 精度：有的文件系统 1s 粒度，这里显式等到时间戳变化
+        for _ in 0..50 {
+            if let Some((value, theme)) = bridge.reload_if_changed() {
+                assert_eq!(theme, ThemeMode::Dark);
+                assert!(value.bg_image_enabled);
+                assert_eq!(value.bg_image, "D:/wall/x.png");
+                std::fs::remove_dir_all(path.parent().unwrap().parent().unwrap()).ok();
+                return;
+            }
+            std::thread::sleep(std::time::Duration::from_millis(20));
+        }
+        panic!("外部修改没有被 mtime 热切捕获");
+    }
+
+    #[test]
+    fn accent_preset_and_validation() {
+        let mut appearance = AppearancePrefs::factory();
+        assert_eq!(appearance.accent_color, "");
+        assert!(appearance.set_accent_preset(1));
+        assert_eq!(appearance.accent_color, "#0F6CBD");
+        assert!(!appearance.set_accent("not-a-color"), "非法输入不改现状");
+        assert_eq!(appearance.accent_color, "#0F6CBD");
+        assert!(appearance.set_accent(""), "空串恢复出厂");
+        assert_eq!(appearance.accent_color, "");
+        assert!(!appearance.set_accent_preset(99));
+    }
+
+    #[test]
+    fn bg_active_needs_both_switch_and_path() {
+        let mut appearance = AppearancePrefs::factory();
+        appearance.bg_image = "D:/wall/p.png".to_owned();
+        assert!(!appearance.bg_active(), "开关没开不算生效");
+        appearance.bg_image_enabled = true;
+        assert!(appearance.bg_active());
+        appearance.bg_image.clear();
+        assert!(!appearance.bg_active(), "路径空也不算生效");
+    }
+
+    /// `load_base()` 是「重启后读回整窗 α / 配色来源 / 窗口圆角」的唯一通道（M93 · M116）。
+    ///
+    /// 抓得住：①文件里写着 `window_opacity=0.6` / `palette_source=wallpaper` 时能被**新开的**
+    /// bridge 读到（= 重启语义）；②缺键时回出厂（1.0 / preset），而不是 `0.0` 或随机档。
+    /// 抓不住：UI 侧是否真的用它来下发窗口 α（那由 `app-iced` 的日志与单测证明）。
+    #[test]
+    fn load_base_reads_the_four_read_only_keys_and_defaults_when_missing() {
+        let path = temp_config("base");
+        // 文件由「外部写者」（CLI / AI / 设置页的 SetSetting）产生，这里直接落 JSON。
+        std::fs::write(
+            &path,
+            r#"{"appearance":{"theme_mode":"dark","window_opacity":0.6,"palette_source":"wallpaper","panel_alpha":0.5}}"#,
+        )
+        .expect("写配置文件");
+
+        let bridge = SettingsBridge::with_path(&path);
+        let base = bridge.load_base();
+        assert_eq!(base.window_opacity, 0.6, "重启后读回整窗 α");
+        assert_eq!(base.palette_source, PaletteSource::Wallpaper);
+        assert!(base.is_transparent());
+
+        // 缺键 → 出厂值（与 `AppearanceBase::factory()` 逐字段相等）。
+        let empty = path.with_file_name("launcher-empty.json");
+        std::fs::write(&empty, "{}").expect("写空配置");
+        let factory = SettingsBridge::with_path(&empty).load_base();
+        assert_eq!(factory, AppearanceBase::factory());
+        assert_eq!(factory.window_opacity, 1.0);
+        assert_eq!(factory.palette_source, PaletteSource::Preset);
+
+        // 数据根解析不出来的内存态桥也要给得出出厂值（不 panic、不返回 0）。
+        assert_eq!(
+            SettingsBridge::memory_only().load_base(),
+            AppearanceBase::factory()
+        );
+
+        std::fs::remove_dir_all(path.parent().unwrap().parent().unwrap()).ok();
+    }
+}
diff --git a/crates/presenter/src/settings_bridge_lang.rs b/crates/presenter/src/settings_bridge_lang.rs
new file mode 100644
index 0000000..b433302
--- /dev/null
+++ b/crates/presenter/src/settings_bridge_lang.rs
@@ -0,0 +1,150 @@
+//! 界面语言这一个键的读写（M106）：`ui.language` 的**显式值**。
+//!
+//! ## 为什么单独一个文件
+//!
+//! `settings_bridge.rs` 是外观 / 主题 / 数据根那一摊的落点，已经贴着 400 行硬线；语言的读写只有
+//! 两个方法 + 一个「删键」辅助，独立出来之后两边都还能长。`impl SettingsBridge` 写在别的模块是
+//! Rust 允许的（同一 crate 的固有实现），只需要主文件把三个字段放成 `pub(super)`。
+//!
+//! ## 两条判据（都跟 schema 的默认值有关）
+//!
+//! 1. **读的是显式值**，不是 `effective_str`：`ui.language` 的 schema 默认值是 `zh_cn`，用它会把
+//!    「没配过」读成「用户手选中文」——英文机器一启动就被强行切成中文（D28 违约）。
+//! 2. **「跟随系统」= 删掉这个键**，不是写哨兵值：允许值只有 `zh_cn` / `en_us`（枚举校验会拒别的），
+//!    而「跟随系统」的语义本来就是「没有显式选择」。
+//!
+//! 这两条都在 `.tower/comms/findings/` 里登了记（建议把 schema 默认值改成 `null` 或加
+//! `follow_system` 取值，那时本文件的删键路径可以简化成一次 `store.set`）。
+
+use unlucky_core::setting::document::SettingDocument;
+use unlucky_core::setting::keys::launcher_schema;
+use unlucky_core::setting::store::SettingStore;
+
+use crate::settings_bridge::SettingsBridge;
+
+/// 界面语言键（M106）：`zh_cn` / `en_us`（允许值见 `core::setting::keys::LANGUAGES`）。
+///
+/// **不写这个键 = 跟随系统**，所以它没有「system」这种取值，见 [`SettingsBridge::persist_ui_language`]。
+const UI_LANGUAGE: &str = "ui.language";
+
+impl SettingsBridge {
+    /// 配置里 `ui.language` 的**显式值**（M106）：`None` = 没写过 = **跟随系统**。
+    ///
+    /// 不用 `effective_str`：那会把 schema 默认值（`zh_cn`）当成「用户手选中文」，于是**没配过**
+    /// 的英文机器会一启动就被强行切成中文（D28 的「纯英文环境不用管」直接违约）。
+    #[must_use]
+    pub fn load_ui_language(&self) -> Option {
+        let store = self.store.as_ref()?;
+        store
+            .doc()
+            .get(UI_LANGUAGE)
+            .and_then(serde_json::Value::as_str)
+            .map(str::to_owned)
+    }
+
+    /// 写 `ui.language`：`Some("zh_cn")` / `Some("en_us")` 手选，`None` = **跟随系统 = 删键**。
+    ///
+    /// 返回是否真的落盘（只读 / 内存态时是 `false`，配置写不进去不该把 UI 卡住）。
+    pub fn persist_ui_language(&mut self, value: Option<&str>) -> bool {
+        let Some(store) = self.store.as_mut() else {
+            return false;
+        };
+        let changed = match value {
+            Some(language) => store
+                .set(UI_LANGUAGE, serde_json::Value::String(language.to_owned()))
+                .is_ok(),
+            None => store.doc().get(UI_LANGUAGE).is_some() && remove_ui_language(store),
+        };
+        if !changed {
+            return false;
+        }
+        let saved = store.save().is_ok();
+        if let Some(path) = self.path() {
+            self.last_mtime = std::fs::metadata(path)
+                .ok()
+                .and_then(|meta| meta.modified().ok());
+        }
+        saved
+    }
+}
+
+/// 把 `ui.language` 从文档里摘掉：`SettingDocument` 没有 remove API，而落盘写的是**全量视图**，
+/// 所以把全量视图里的那个键去掉再 load 回一份文档就等价于删键（用户手写的未知键也原样带回）。
+fn remove_ui_language(store: &mut SettingStore) -> bool {
+    let mut value = store.doc().to_value();
+    let removed = value
+        .get_mut("ui")
+        .and_then(serde_json::Value::as_object_mut)
+        .and_then(|ui| ui.remove("language"))
+        .is_some();
+    if !removed {
+        return false;
+    }
+
+    let (mut doc, _problems) = SettingDocument::load(&launcher_schema(), &value);
+    // 落盘的闸门是 `is_dirty()`（`write_document` 写全量视图，不是脏字段补丁）。
+    doc.mark_all_dirty();
+    *store.doc_mut() = doc;
+    true
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::path::PathBuf;
+
+    fn temp_config(label: &str) -> PathBuf {
+        let dir = std::env::temp_dir().join(format!(
+            "ull-bridge-lang-{label}-{}-{}",
+            std::process::id(),
+            line!()
+        ));
+        std::fs::create_dir_all(dir.join("config")).expect("临时目录");
+        let path = dir.join("config/launcher.json");
+        let _ = std::fs::remove_file(&path);
+        path
+    }
+
+    /// 抓得住：①把 `effective_str` 当读法（英文机器没配过 → 被默认值 `zh_cn` 强行切成中文）；
+    /// ②「跟随系统」写成哨兵值（枚举校验会拒、下次启动会撒谎）；③删键时连别的键一起删。
+    /// 抓不住：UI 是否真的按这个值选目录（那是 `app-iced/src/ui/lang.rs` 的往返测试）。
+    #[test]
+    fn ui_language_round_trips_and_follow_system_removes_only_that_key() {
+        let path = temp_config("roundtrip");
+        std::fs::write(
+            &path,
+            r#"{"appearance":{"theme_mode":"dark"},"custom":{"keep":true}}"#,
+        )
+        .expect("写配置");
+
+        // 没写过 = 跟随系统（不是默认值 zh_cn）
+        let bridge = SettingsBridge::with_path(&path);
+        assert_eq!(bridge.load_ui_language(), None);
+
+        // 手选落盘 → 新开的 bridge（= 重启）读得回
+        let mut bridge = SettingsBridge::with_path(&path);
+        assert!(bridge.persist_ui_language(Some("zh_cn")));
+        assert_eq!(
+            SettingsBridge::with_path(&path)
+                .load_ui_language()
+                .as_deref(),
+            Some("zh_cn")
+        );
+
+        // 切回跟随系统 = 删键，且别的键一个不动
+        let mut bridge = SettingsBridge::with_path(&path);
+        assert!(bridge.persist_ui_language(None));
+        assert_eq!(SettingsBridge::with_path(&path).load_ui_language(), None);
+        let text = std::fs::read_to_string(&path).expect("读配置");
+        assert!(text.contains("theme_mode"), "外观键被删了：{text}");
+        assert!(text.contains("custom"), "用户手写的未知键被删了：{text}");
+
+        // 幂等：没有键可删 = 没有落盘
+        let mut bridge = SettingsBridge::with_path(&path);
+        assert!(!bridge.persist_ui_language(None));
+
+        // 内存态桥不许 panic
+        assert_eq!(SettingsBridge::memory_only().load_ui_language(), None);
+        std::fs::remove_dir_all(path.parent().unwrap().parent().unwrap()).ok();
+    }
+}
diff --git a/crates/presenter/src/state.rs b/crates/presenter/src/state.rs
new file mode 100644
index 0000000..a3b6518
--- /dev/null
+++ b/crates/presenter/src/state.rs
@@ -0,0 +1,387 @@
+//! UI 状态与 reducer：UI 框架只负责渲染，所有状态变更都汇聚到 [`AppState::apply`]。
+//!
+//! 数据流向：mock/host 后端 → [`crate::dto::AppEvent`] 队列 → `apply` → 状态字段 → UI 属性。
+//! 偏好项在 [`crate::prefs`] 里登记了持久化键名，core::setting 的 schema 落地后按这些键读写。
+
+use crate::agent::AgentRail;
+use crate::dialogs::DialogQueue;
+use crate::dto::{
+    // 主线（M105 的 `LoaderKind` / M113 的 `PackState`）与 M114 的 `AuthlibLoginView` 并集。
+    AccountView,
+    AgentEvent,
+    AppEvent,
+    AuthlibLoginView,
+    CoreEvent,
+    DeviceLoginView,
+    DiagnosisReport,
+    InstallProgressView,
+    InstanceRuntime,
+    InstanceSummary,
+    JavaPageView,
+    LoaderKind,
+    LogLine,
+    LogSession,
+    NoticeView,
+    PackState,
+    Progress,
+    SettingGroupView,
+    VersionSummary,
+};
+use crate::prefs::UiPrefs;
+// 内容库的视图态与其 DTO 放一起（`dto/content.rs`），路径 `state::ContentState` 不变。
+pub use crate::dto::ContentState;
+use crate::router::{AiPanelMode, Route, Router};
+use crate::toast::{ToastCenter, ToastKind};
+use crate::wizard::WizardState;
+
+// 账户/登录状态（倒计时、上屏前二次脱敏）拆在 `state/accounts.rs`，守 400 行硬线。
+//
+// `AiSession` 不再存在：M104 把它换成了 `crate::agent::AgentRail`（agent 栏的视图模型），
+// 所以这里没有 `mod ai;` / `pub use ai::AiSession;`——M114 r1 曾把旧结构搬到 `state/ai.rs`，
+// 该文件已随 rebase 删除，**以 main 的 agent 契约为准**。
+mod accounts;
+mod live;
+mod tiles;
+
+pub use live::MAX_LIVE_LINES;
+pub use tiles::{grid_positions, TileCell};
+
+/// 一份加载器版本清单查询的结果（`Ok` = 最新在前；`Err` = 人读原因）。
+pub type LoaderVersions = Result, 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,
+    /// 加载器版本清单（下载页「安装选项」的下拉；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,
+    /// 新建实例向导
+    pub wizard: WizardState,
+    /// 正在实时尾随的会话
+    pub live_session: Option,
+    /// 内容库（M109）：条件 / 结果 / 请求态
+    pub content: ContentState,
+    /// 整合包导入/导出：进度 / 结果 / 探测诊断 / 导出预检（M113）
+    pub pack: PackState,
+}
+
+impl Default for AppState {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl AppState {
+    /// 空状态（数据由后端事件填充，P0 是 mock）。
+    pub fn new() -> Self {
+        Self {
+            prefs: UiPrefs::default(),
+            router: Router::new(),
+            instances: Vec::new(),
+            versions: Vec::new(),
+            log_sessions: Vec::new(),
+            log_lines: Vec::new(),
+            diagnosis: None,
+            selected_session: None,
+            ai: AgentRail::new(),
+            dialogs: DialogQueue::new(),
+            toasts: ToastCenter::new(),
+            instance_query: String::new(),
+            installed_only: false,
+            download_query: String::new(),
+            accounts: Vec::new(),
+            device_login: DeviceLoginView::new(),
+            authlib_login: AuthlibLoginView::new(),
+            device_login_started: None,
+            account_notice: None,
+            java: JavaPageView::new(),
+            install: None,
+            install_cancelled: 0,
+            loader_versions: std::collections::HashMap::new(),
+            settings_groups: Vec::new(),
+            settings_tab: "download".to_string(),
+            notices: Vec::new(),
+            wizard: WizardState::new(),
+            live_session: None,
+            content: ContentState::default(),
+            pack: PackState::default(),
+        }
+    }
+
+    /// 某 (加载器, 原版版本) 的加载器版本清单。
+    ///
+    /// `None` = 还没查过（页面据此派一次 `AppCommand::ListLoaderVersions` 并显示「正在获取…」）；
+    /// `Some(Err(..))` = 查过但拿不到（页面显示具名原因并**禁掉确认**）。
+    #[must_use]
+    pub fn loader_versions_for(
+        &self,
+        kind: LoaderKind,
+        mc_version: &str,
+    ) -> Option<&LoaderVersions> {
+        self.loader_versions.get(kind.as_str())?.get(mc_version)
+    }
+
+    /// 当前页面。
+    pub fn route(&self) -> &Route {
+        self.router.route()
+    }
+
+    /// 跳转（一级页替换、子页面压栈；去 AI 独立页时自动展开 AI 栏偏好）。
+    pub fn navigate(&mut self, route: Route) {
+        if route == Route::Agent {
+            self.prefs.ai_collapsed = false;
+            // 用户正在看 AI 页：攒下的未读立刻算已读（红点不该在眼前亮着）
+            self.ai.mark_read();
+        }
+        self.router.navigate(route);
+    }
+
+    /// 回退一层。
+    pub fn back(&mut self) -> bool {
+        self.router.back()
+    }
+
+    /// AI 栏当前形态（跟着路由走）。
+    pub fn ai_mode(&self) -> AiPanelMode {
+        self.router.ai_mode()
+    }
+
+    /// 应用一条事件（唯一状态变更入口）。
+    pub fn apply(&mut self, event: AppEvent) {
+        match event {
+            AppEvent::Core(core) => self.apply_core(core),
+            AppEvent::Agent(agent) => self.apply_agent(agent),
+            AppEvent::DialogRequested(request) => {
+                self.dialogs.push_request(request);
+            }
+            AppEvent::DialogClosed(id) => {
+                self.dialogs.close(id);
+            }
+            AppEvent::Toast(toast) => {
+                self.toasts.push_request(toast);
+            }
+        }
+    }
+
+    /// core 事件。
+    pub fn apply_core(&mut self, event: CoreEvent) {
+        match event {
+            CoreEvent::InstancesChanged(instances) => self.instances = instances,
+            CoreEvent::InstanceRuntimeChanged { id, runtime } => {
+                if let Some(instance) = self.instances.iter_mut().find(|item| item.id == id) {
+                    instance.runtime = runtime;
+                }
+            }
+            CoreEvent::VersionListChanged(versions) => self.versions = versions,
+            CoreEvent::LogSessionsChanged(sessions) => self.log_sessions = sessions,
+            CoreEvent::LogLinesChanged(lines) => {
+                self.log_lines = lines;
+                self.live_session = None;
+            }
+            CoreEvent::LogAppended(batch) => self.append_live_lines(&batch),
+            CoreEvent::LaunchFinished(finished) => {
+                self.live_session = None;
+                self.selected_session = Some(finished.session.clone());
+                let kind = if finished.outcome == crate::dto::LogOutcome::Ok {
+                    ToastKind::Success
+                } else {
+                    ToastKind::Error
+                };
+                self.toasts.push(kind, finished.summary);
+            }
+            CoreEvent::DiagnosisReady(report) => self.diagnosis = Some(report),
+            CoreEvent::AccountsChanged(accounts) => self.accounts = accounts,
+            CoreEvent::DeviceLoginChanged(view) => self.apply_device_login(view),
+            CoreEvent::AuthlibLoginChanged(view) => self.apply_authlib_login(view),
+            CoreEvent::AccountNoticeChanged(notice) => self.account_notice = notice,
+            CoreEvent::JavaChanged(page) => self.java = page,
+            CoreEvent::InstallProgress(progress) => match progress {
+                Some(progress) => {
+                    let terminal = progress.stage.is_terminal();
+                    self.install = Some(progress);
+                    if terminal {
+                        self.wizard.open = false;
+                        self.wizard.submitting = false;
+                    }
+                }
+                None => self.install = None,
+            },
+            CoreEvent::InstallCancelled => {
+                self.install_cancelled = self.install_cancelled.saturating_add(1);
+            }
+            CoreEvent::SettingsChanged(groups) => self.settings_groups = groups,
+            CoreEvent::LoaderVersions {
+                kind,
+                mc_version,
+                result,
+            } => {
+                self.loader_versions
+                    .entry(kind.as_str())
+                    .or_default()
+                    .insert(mc_version, result);
+            }
+            CoreEvent::NoticesChanged(notices) => self.notices = notices,
+            // M113: import/export
+            CoreEvent::Pack(event) => self.pack.apply(*event),
+            CoreEvent::ContentResults(results) => self.apply_content(*results),
+            CoreEvent::ContentFailed(reason) => {
+                self.content.pending = false;
+                self.content.failed = Some(reason);
+            }
+        }
+    }
+
+    /// agent 事件 → AI 栏视图模型（投影规则见 [`crate::agent::rail`]）。
+    ///
+    /// 未读规则：栏不可见时，助手侧新内容（助手/工具消息、错误、待确认请求）逐条累加 `unread`；
+    /// 用户自己说的话与纯增量不算。栏可见时到达的内容直接算已读（红点不该在眼前亮着）。
+    pub fn apply_agent(&mut self, event: AgentEvent) {
+        let visible = self.agent_rail_visible();
+        let fresh = self.ai.ingest(&event);
+        if fresh {
+            if visible {
+                self.ai.mark_read();
+            } else {
+                self.ai.unread = self.ai.unread.saturating_add(1);
+            }
+        }
+    }
+
+    /// AI 栏此刻是否「在用户眼前」。
+    ///
+    /// 独立页形态（栈顶是 `Route::Agent`）必然可见；停靠形态下只有收成 icon 轨才算离开——
+    /// 右侧常驻栏在任何一级页面都挂着，用户扫一眼就能看到。
+    #[must_use]
+    pub fn agent_rail_visible(&self) -> bool {
+        self.ai_mode() == AiPanelMode::Page || !self.prefs.ai_collapsed
+    }
+
+    /// 按搜索词过滤后的磁贴网格（顺序稳定 = 实例列表顺序）。
+    pub fn tiles(&self) -> Vec> {
+        let query = self.instance_query.trim().to_lowercase();
+        let filtered: Vec<&InstanceSummary> = self
+            .instances
+            .iter()
+            .filter(|instance| query.is_empty() || instance.name.to_lowercase().contains(&query))
+            .collect();
+        let positions = grid_positions(filtered.len(), self.prefs.tile_size.columns());
+        filtered
+            .into_iter()
+            .zip(positions)
+            .map(|(instance, (row, col))| TileCell { instance, row, col })
+            .collect()
+    }
+
+    /// 运行中的实例（实例页顶部迷你状态条）。
+    pub fn running(&self) -> Vec<&InstanceSummary> {
+        self.instances
+            .iter()
+            .filter(|instance| {
+                matches!(
+                    instance.runtime,
+                    InstanceRuntime::Running { .. } | InstanceRuntime::Busy { .. }
+                )
+            })
+            .collect()
+    }
+
+    /// 覆盖某实例的启动进度（mock / 真实后端共用同一入口）。
+    pub fn set_progress(&mut self, id: &str, progress: Progress) {
+        if let Some(instance) = self.instances.iter_mut().find(|item| item.id == id) {
+            if let InstanceRuntime::Busy {
+                progress: current, ..
+            } = &mut instance.runtime
+            {
+                *current = progress;
+            }
+        }
+    }
+
+    /// 折叠/展开导航栏。
+    pub fn toggle_nav(&mut self) {
+        self.prefs.nav_collapsed = !self.prefs.nav_collapsed;
+    }
+
+    /// 折叠/展开 AI 栏；若正处在独立页形态则先收回侧栏。
+    pub fn toggle_ai(&mut self) {
+        if self.route() == &Route::Agent {
+            self.router.back();
+            self.prefs.ai_collapsed = false;
+            return;
+        }
+        self.prefs.ai_collapsed = !self.prefs.ai_collapsed;
+        if !self.prefs.ai_collapsed {
+            // 展开常驻栏 = 用户在看它
+            self.ai.mark_read();
+        }
+    }
+}
+
+#[cfg(test)]
+#[path = "state_tests.rs"]
+mod tests;
+
+mod content;
+
+#[cfg(test)]
+mod content_tests;
diff --git a/crates/presenter/src/state/accounts.rs b/crates/presenter/src/state/accounts.rs
new file mode 100644
index 0000000..df78016
--- /dev/null
+++ b/crates/presenter/src/state/accounts.rs
@@ -0,0 +1,193 @@
+//! 账户/登录状态：事件落地（含**上屏前再脱敏**）、设备码倒计时、当前账户查询。
+//!
+//! 从 `state.rs` 拆出来守 400 行硬线；`AppState` 的字段仍在那个文件里，
+//! 这里只加它的 `impl`（同一个 crate 的固有 impl 可以拆在多个文件）。
+
+use std::time::Instant;
+
+use crate::dto::{AccountView, AuthlibLoginView, DeviceLoginPhase, DeviceLoginView, REDACTED};
+
+use super::AppState;
+
+impl AppState {
+    /// 微软登录状态落地。
+    ///
+    /// **凭据红线（M114）**：这里对 `message` 再做一次形状脱敏。DTO 的构造器已经脱过一遍，
+    /// 但状态层是**所有**事件都要过的唯一闸口——将来谁新加一个构造器忘了脱敏，也不会把
+    /// 服务端回显的 token 画到面板上。脱敏是幂等的，重复做没有代价。
+    pub fn apply_device_login(&mut self, mut view: DeviceLoginView) {
+        view.message = crate::dto::redact(&view.message);
+        view.account_name = crate::dto::redact(&view.account_name);
+        // 这里**不发 toast**：presenter 是共享宿主层，写什么语言都不对（复审 r1 P1-1）。
+        // 成败反馈由页面自己画（登录面板的 Succeeded/Failed 态 + 账户页横幅），文案走 i18n。
+        match view.phase {
+            DeviceLoginPhase::Succeeded => {
+                self.device_login_started = None;
+            }
+            DeviceLoginPhase::Failed => {
+                self.device_login_started = None;
+            }
+            DeviceLoginPhase::Waiting => {
+                // 每次进入等待态都重记起点：换流/重试之后倒计时必须从头算
+                if self.device_login.phase != DeviceLoginPhase::Waiting
+                    || self.device_login.user_code != view.user_code
+                {
+                    self.device_login_started = Some(Instant::now());
+                }
+            }
+            DeviceLoginPhase::Idle | DeviceLoginPhase::Requesting => {
+                self.device_login_started = None;
+            }
+        }
+        self.device_login = view;
+    }
+
+    /// 第三方轨登录状态落地（同样在状态层再脱敏一遍）。
+    pub fn apply_authlib_login(&mut self, mut view: AuthlibLoginView) {
+        view.message = crate::dto::redact(&view.message);
+        view.server_name = crate::dto::redact(&view.server_name);
+        // 同 `apply_device_login`：不发 toast，成败由页面按 i18n 画。
+        self.authlib_login = view;
+    }
+
+    /// 设备码/授权码还剩几秒（`None` = 没有在等 / 不知道有效期）。
+    ///
+    /// 纯计算 + 一个起点，UI 侧每秒重问一次就能画出倒计时——这也让「过期」成为**可观测**的
+    /// 状态（任务要求：设备码不得只转圈，过期要显示「已过期，重试」）。
+    pub fn device_code_remaining(&self) -> Option {
+        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/content.rs b/crates/presenter/src/state/content.rs
new file mode 100644
index 0000000..d4ca6c7
--- /dev/null
+++ b/crates/presenter/src/state/content.rs
@@ -0,0 +1,45 @@
+//! 内容库的状态机（M109）：结果落地与条件提交两件事。
+//!
+//! 从 `state.rs` 拆出（那个文件重新合流 M105 之后贴着 400 行上限）。放在 `impl AppState` 的
+//! **另一个 impl 块**里，路径与可见性都不变：`apply_core` 直接调 `self.apply_content(..)`。
+
+use crate::dto::{ContentQuery, ContentResults};
+
+use super::AppState;
+
+impl AppState {
+    /// 内容库结果落地（M109）：同条件换页 ⇒ **追加**；换条件 ⇒ **整批替换**；迟到 ⇒ 丢掉。
+    ///
+    /// 这三条就是「列表画的永远是当前筛选条件」的全部保证——页面自己没有过滤逻辑，也没有第二份真相。
+    pub(super) fn apply_content(&mut self, results: ContentResults) {
+        self.content.pending = false;
+        self.content.failed = None;
+        if !self.content.accepts(&results) {
+            // 迟到的一批：用户已经改了条件，覆盖上去就会出现「筛选条说 A、列表是 B」。
+            return;
+        }
+        // **先**按「这一页装没装满」记一位，再把它并进累计列表（复审 P1-2：判据不能读累计值）。
+        self.content.last_page_filled = results.has_more();
+        match &mut self.content.results {
+            Some(current) if results.query.offset > 0 => {
+                current.hits.extend(results.hits);
+                current.total = results.total;
+                current.curseforge = results.curseforge;
+                current.query = results.query;
+            }
+            _ => self.content.results = Some(results),
+        }
+    }
+
+    /// 记下新的检索条件并进入「请求在飞」态（指令由调用方随后 dispatch）。
+    pub fn set_content_query(&mut self, query: ContentQuery) {
+        self.content.pending = true;
+        self.content.failed = None;
+        if query.offset == 0 {
+            self.content.last_page_filled = false;
+            // 换条件（不是换页）：先把旧结果清掉，否则加载态会画出上一批命中项。
+            self.content.results = None;
+        }
+        self.content.query = query;
+    }
+}
diff --git a/crates/presenter/src/state/content_tests.rs b/crates/presenter/src/state/content_tests.rs
new file mode 100644
index 0000000..e2c612b
--- /dev/null
+++ b/crates/presenter/src/state/content_tests.rs
@@ -0,0 +1,130 @@
+//! 内容库状态机的守门测试（M109；复审 P1-2 的补课）。
+//!
+//! 从 `state.rs` 拆出（那个文件贴 400 行硬上限）。钉的是**翻页判据**：
+//! `has_more` 必须读「最近一页是否装满」，不能读累计条数——否则第 2 页之后恒真。
+
+use crate::dto::{
+    AppEvent, ContentHit, ContentKind, ContentQuery, ContentResults, ContentSource, CoreEvent,
+};
+
+use super::AppState;
+
+fn hit(index: usize) -> ContentHit {
+    ContentHit {
+        id: format!("p{index}"),
+        slug: format!("p{index}"),
+        title: format!("Project {index}"),
+        summary: "s".to_string(),
+        author: "a".to_string(),
+        downloads: 0,
+        updated: "2026-01-01".to_string(),
+        source: ContentSource::Modrinth,
+        game_versions: vec!["1.20.1".to_string()],
+        loaders: vec!["fabric".to_string()],
+        icon: None,
+    }
+}
+
+/// 造一页结果：`offset` 是游标，`count` 是这一页实际回来几条。
+fn page(offset: u32, count: u32) -> ContentResults {
+    let mut query = ContentQuery::first(ContentKind::Mod);
+    query.offset = offset;
+    ContentResults {
+        query,
+        hits: (0..count)
+            .map(|index| hit(offset as usize + index as usize))
+            .collect(),
+        total: 999,
+        curseforge: false,
+    }
+}
+
+fn apply(state: &mut AppState, results: ContentResults) {
+    state.apply(AppEvent::Core(CoreEvent::ContentResults(Box::new(results))));
+}
+
+/// 复审 P1-2 的第一条：装满一页 ⇒ 还有更多；下一（末）页不满 ⇒ 没有了。
+#[test]
+fn a_short_last_page_clears_has_more() {
+    let mut state = AppState::new();
+    let limit = ContentQuery::first(ContentKind::Mod).limit;
+
+    apply(&mut state, page(0, limit));
+    assert!(state.content.last_page_filled, "首页装满 ⇒ 还有下一页");
+    assert_eq!(
+        state.content.results.as_ref().map_or(0, |r| r.hits.len()),
+        limit as usize
+    );
+
+    // 末页只回来 3 条：累计 23 条「够一页了」，但**这一页**没装满 ⇒ 没有更多
+    apply(&mut state, page(limit, 3));
+    assert!(
+        !state.content.last_page_filled,
+        "末页不满 ⇒ 不许说还有更多（判据不能读累计条数）"
+    );
+    assert_eq!(
+        state.content.results.as_ref().map_or(0, |r| r.hits.len()),
+        limit as usize + 3,
+        "命中项仍然要累加"
+    );
+}
+
+/// 复审 P1-2 的第二条：再点一次，回来的空页仍然是「没有更多」。
+#[test]
+fn an_empty_last_page_keeps_has_more_false() {
+    let mut state = AppState::new();
+    let limit = ContentQuery::first(ContentKind::Mod).limit;
+
+    apply(&mut state, page(0, limit));
+    apply(&mut state, page(limit, 0));
+    assert!(!state.content.last_page_filled, "空页 ⇒ 没有更多");
+
+    // 用户又点了一次「加载更多」：空页不会把状态翻回真
+    apply(&mut state, page(limit + limit, 0));
+    assert!(
+        !state.content.last_page_filled,
+        "再点一次空页 ⇒ 仍然没有更多"
+    );
+    assert_eq!(
+        state.content.results.as_ref().map_or(0, |r| r.hits.len()),
+        limit as usize,
+        "空页不改变列表内容"
+    );
+}
+
+/// 换条件（offset 回到 0）时把「最近一页装满」清掉：不然新条件的第一帧就会画「没有更多了」。
+#[test]
+fn changing_the_query_resets_the_page_flag() {
+    let mut state = AppState::new();
+    let limit = ContentQuery::first(ContentKind::Mod).limit;
+
+    apply(&mut state, page(0, limit));
+    assert!(state.content.last_page_filled);
+
+    let mut query = ContentQuery::first(ContentKind::Mod);
+    query.text = "sodium".to_string();
+    state.set_content_query(query);
+    assert!(!state.content.last_page_filled, "换条件 ⇒ 清掉上一批的判据");
+    assert!(state.content.pending);
+    assert!(
+        state.content.results.is_none(),
+        "换条件要清列表（不然加载态画旧命中项）"
+    );
+}
+
+/// 迟到的一批不许改写判据（用户已经换了条件）。
+#[test]
+fn a_stale_batch_does_not_touch_the_page_flag() {
+    let mut state = AppState::new();
+    let limit = ContentQuery::first(ContentKind::Mod).limit;
+
+    apply(&mut state, page(0, limit));
+    let mut query = ContentQuery::first(ContentKind::Mod);
+    query.text = "sodium".to_string();
+    state.set_content_query(query);
+
+    // 旧条件的一页这时才回来：既不改结果，也不改「还有更多」
+    apply(&mut state, page(limit, 5));
+    assert!(!state.content.last_page_filled);
+    assert!(state.content.results.is_none(), "迟到的一批被丢掉");
+}
diff --git a/crates/presenter/src/state/live.rs b/crates/presenter/src/state/live.rs
new file mode 100644
index 0000000..15d2a57
--- /dev/null
+++ b/crates/presenter/src/state/live.rs
@@ -0,0 +1,30 @@
+//! 实时日志的滚动窗口（从 `state.rs` 搬出，守 400 行硬线）。
+//!
+//! 纯搬移：常量与 `append_live_lines` 一字未改；`state.rs` 用 `pub use` 再导出
+//! [`MAX_LIVE_LINES`]，老路径 `crate::state::MAX_LIVE_LINES` 继续可用。
+
+use super::AppState;
+
+/// 实时日志最多保留的行数（滚动窗口；更多行由日志页的筛选/历史会话承担）。
+pub const MAX_LIVE_LINES: usize = 2_000;
+
+impl AppState {
+    /// 实时日志增量：只追加，封顶 [`MAX_LIVE_LINES`] 行（滚动窗口）。
+    pub(super) fn append_live_lines(&mut self, batch: &crate::dto::LiveLogBatch) {
+        if self
+            .live_session
+            .as_deref()
+            .is_some_and(|session| session != batch.session)
+        {
+            // 换了一个会话在跑：清掉上一场的行，避免两场日志混在一起
+            self.log_lines.clear();
+        }
+        self.live_session = batch.running.then(|| batch.session.clone());
+        self.selected_session = Some(batch.session.clone());
+        self.log_lines.extend(batch.lines.iter().cloned());
+        if self.log_lines.len() > MAX_LIVE_LINES {
+            let drop = self.log_lines.len() - MAX_LIVE_LINES;
+            self.log_lines.drain(..drop);
+        }
+    }
+}
diff --git a/crates/presenter/src/state/tiles.rs b/crates/presenter/src/state/tiles.rs
new file mode 100644
index 0000000..da8988b
--- /dev/null
+++ b/crates/presenter/src/state/tiles.rs
@@ -0,0 +1,27 @@
+//! 磁贴网格的纯函数与单元类型（从 `state.rs` 原样搬出，守 400 行硬线）。
+//!
+//! **纯搬移**：类型、函数、文档一字未改，只是换了文件；`state.rs` 用 `pub use` 再导出，
+//! 于是 `crate::state::{TileCell, grid_positions}` 这两个老路径继续可用。
+
+use crate::dto::InstanceSummary;
+
+/// 磁贴网格单元：位置由 [`grid_positions`] 算好，UI 侧只消费 row/col。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct TileCell<'a> {
+    /// 实例数据
+    pub instance: &'a InstanceSummary,
+    /// 网格行号（0 起）
+    pub row: usize,
+    /// 网格列号（0 起）
+    pub col: usize,
+}
+
+/// 纯函数：把 n 个磁贴摊到 `columns` 列的网格上，返回 `(row, col)`。
+///
+/// 特意放在 Rust 侧：声明式 UI 的表达式里做整数除法容易引出隐式浮点，且这段逻辑可以单测。
+pub fn grid_positions(count: usize, columns: usize) -> Vec<(usize, usize)> {
+    let columns = columns.max(1);
+    (0..count)
+        .map(|index| (index / columns, index % columns))
+        .collect()
+}
diff --git a/crates/presenter/src/state_tests.rs b/crates/presenter/src/state_tests.rs
new file mode 100644
index 0000000..e1a4358
--- /dev/null
+++ b/crates/presenter/src/state_tests.rs
@@ -0,0 +1,371 @@
+//! state.rs 的单元测试（拆文件保持单文件 ≤400 行）。
+
+use super::{grid_positions, AppState};
+use crate::agent::AgentRail;
+use crate::dialogs::{DialogKind, DialogRequest, DialogSource};
+use crate::dto::{
+    AgentEvent, AppEvent, ChatMessage, ChatRole, CoreEvent, Diagnosis, DiagnosisReport,
+    InstanceRuntime, InstanceSummary, LoaderInfo, LoaderKind,
+};
+use crate::prefs::TileSize;
+use crate::router::Route;
+use crate::toast::Toast;
+use crate::toast::ToastKind;
+
+fn instance(id: &str, name: &str) -> InstanceSummary {
+    InstanceSummary {
+        id: id.to_string(),
+        name: name.to_string(),
+        mc_version: "1.20.4".to_string(),
+        loader: LoaderInfo {
+            kind: LoaderKind::Fabric,
+            version: "0.16.5".to_string(),
+        },
+        last_played: None,
+        runtime: InstanceRuntime::Idle,
+        icon: None,
+        isolation: "isolated".to_string(),
+        version_id: "1.20.4".to_string(),
+        version_present: true,
+    }
+}
+
+#[test]
+fn grid_positions_wrap_by_column_count() {
+    assert_eq!(grid_positions(0, 4), vec![]);
+    assert_eq!(grid_positions(3, 2), vec![(0, 0), (0, 1), (1, 0)]);
+    // columns == 0 时按 1 列兜底，不允许除零
+    assert_eq!(grid_positions(2, 0), vec![(0, 0), (1, 0)]);
+}
+
+#[test]
+fn tiles_follow_tile_size_and_search() {
+    let mut state = AppState::new();
+    state.instances = vec![
+        instance("a", "生存"),
+        instance("b", "创造"),
+        instance("c", "Demo"),
+    ];
+
+    assert_eq!(state.tiles().len(), 3);
+    assert_eq!((state.tiles()[2].row, state.tiles()[2].col), (0, 2));
+
+    state.prefs.tile_size = TileSize::Large;
+    assert_eq!((state.tiles()[2].row, state.tiles()[2].col), (0, 2));
+
+    state.prefs.tile_size = TileSize::Small;
+    assert_eq!(state.tiles().len(), 3);
+
+    state.instance_query = "demo".to_string();
+    let tiles = state.tiles();
+    assert_eq!(tiles.len(), 1);
+    assert_eq!(tiles[0].instance.id, "c");
+    assert_eq!((tiles[0].row, tiles[0].col), (0, 0));
+}
+
+#[test]
+fn tiles_reflow_when_tile_size_shrinks() {
+    let mut state = AppState::new();
+    state.instances = (0..8)
+        .map(|i| instance(&format!("i{i}"), &format!("实例{i}")))
+        .collect();
+
+    state.prefs.tile_size = TileSize::Medium;
+    let medium_rows = state.tiles().iter().map(|cell| cell.row).max();
+
+    state.prefs.tile_size = TileSize::Small;
+    let small_rows = state.tiles().iter().map(|cell| cell.row).max();
+
+    assert_eq!(medium_rows, Some(1)); // 8 / 4 列 = 2 行
+    assert_eq!(small_rows, Some(1)); // 8 / 6 列 = 2 行
+}
+
+#[test]
+fn runtime_events_update_the_matching_instance() {
+    let mut state = AppState::new();
+    state.instances = vec![instance("a", "生存"), instance("b", "创造")];
+
+    state.apply(AppEvent::Core(CoreEvent::InstanceRuntimeChanged {
+        id: "b".to_string(),
+        runtime: InstanceRuntime::Running { pid: 42 },
+    }));
+
+    assert_eq!(state.instances[0].runtime, InstanceRuntime::Idle);
+    assert_eq!(
+        state.instances[1].runtime,
+        InstanceRuntime::Running { pid: 42 }
+    );
+    assert_eq!(state.running().len(), 1);
+    assert_eq!(state.running()[0].id, "b");
+}
+
+#[test]
+fn progress_events_only_touch_busy_instances() {
+    let mut state = AppState::new();
+    state.instances = vec![instance("a", "生存")];
+    state.instances[0].runtime = InstanceRuntime::Busy {
+        stage: crate::dto::LaunchStage::Download,
+        progress: crate::dto::Progress {
+            done: 0,
+            total: 100,
+        },
+    };
+
+    state.set_progress(
+        "a",
+        crate::dto::Progress {
+            done: 50,
+            total: 100,
+        },
+    );
+    match &state.instances[0].runtime {
+        InstanceRuntime::Busy { progress, .. } => {
+            assert!((progress.ratio() - 0.5).abs() < f32::EPSILON);
+        }
+        other => panic!("unexpected runtime: {other:?}"),
+    }
+
+    // 不存在的 id / 非 Busy 状态不改变任何东西
+    state.set_progress("missing", crate::dto::Progress { done: 1, total: 1 });
+    assert_eq!(state.instances.len(), 1);
+}
+
+#[test]
+fn ai_stream_deltas_accumulate_and_finish() {
+    let mut state = AppState::new();
+    state.apply(AppEvent::Agent(AgentEvent::MessageAppended(
+        ChatMessage::user("怎么装 1.20.4"),
+    )));
+    state.apply(AppEvent::Agent(AgentEvent::MessageAppended(
+        ChatMessage::assistant_stream(),
+    )));
+    assert_eq!(state.ai.messages.len(), 2);
+    assert!(state.ai.streaming);
+    assert_eq!(state.ai.messages[1].role, ChatRole::Assistant);
+
+    state.apply(AppEvent::Agent(AgentEvent::MessageDelta {
+        index: 1,
+        delta: "先".to_string(),
+    }));
+    state.apply(AppEvent::Agent(AgentEvent::MessageDelta {
+        index: 1,
+        delta: "下载".to_string(),
+    }));
+    state.apply(AppEvent::Agent(AgentEvent::MessageFinished { index: 1 }));
+
+    assert_eq!(state.ai.messages[1].text, "先下载");
+    assert!(!state.ai.messages[1].streaming);
+    assert!(!state.ai.streaming);
+}
+
+#[test]
+fn ai_session_finish_stream_clears_every_flag() {
+    let mut session = AgentRail::new();
+    session.messages.push(ChatMessage::user("hi"));
+    session.messages.push(ChatMessage::assistant_stream());
+    session.finish_stream();
+    assert!(session.messages.iter().all(|message| !message.streaming));
+    assert!(!session.streaming);
+    assert!(!session.busy);
+}
+
+#[test]
+fn tool_call_finish_updates_the_last_matching_message() {
+    let mut state = AppState::new();
+    state.apply(AppEvent::Agent(AgentEvent::ToolCallStarted {
+        name: "get_config".to_string(),
+        summary: "读取设置".to_string(),
+    }));
+    state.apply(AppEvent::Agent(AgentEvent::ToolCallFinished {
+        name: "get_config".to_string(),
+        ok: true,
+        summary: "读取到 3 项".to_string(),
+    }));
+
+    let tool = &state.ai.messages[0];
+    assert_eq!(tool.role, ChatRole::Tool);
+    assert_eq!(tool.text, "读取到 3 项");
+    assert!(!tool.streaming);
+    assert!(tool.tool.as_ref().is_some_and(|call| call.ok));
+}
+
+#[test]
+fn dialogs_and_toasts_flow_through_apply() {
+    let mut state = AppState::new();
+    state.apply(AppEvent::DialogRequested(DialogRequest {
+        id: 42,
+        source: DialogSource::UserAction,
+        title: "AI 想修改内存".to_string(),
+        body: "改为 8G".to_string(),
+        kind: DialogKind::Confirm {
+            primary: "允许".to_string(),
+            secondary: "拒绝".to_string(),
+        },
+    }));
+    state.apply(AppEvent::Toast(Toast {
+        id: 0,
+        kind: ToastKind::Success,
+        text: "下载完成".to_string(),
+        remaining_ms: 0,
+    }));
+
+    assert_eq!(state.dialogs.pending_len(), 0);
+    // id 归生产者：队列原样保留，DialogClosed(42) 才能命中同一条
+    assert_eq!(state.dialogs.current().map(|dialog| dialog.id), Some(42));
+    assert_eq!(state.toasts.len(), 1);
+
+    state.apply(AppEvent::DialogClosed(42));
+    assert!(state.dialogs.is_empty());
+}
+
+#[test]
+fn navigate_to_agent_page_expands_the_ai_panel() {
+    let mut state = AppState::new();
+    state.prefs.ai_collapsed = true;
+    state.navigate(Route::Agent);
+    assert_eq!(state.route(), &Route::Agent);
+    assert_eq!(state.ai_mode(), crate::router::AiPanelMode::Page);
+    assert!(!state.prefs.ai_collapsed);
+}
+
+#[test]
+fn toggling_ai_from_the_page_form_docks_it_again() {
+    let mut state = AppState::new();
+    state.navigate(Route::Agent);
+    state.toggle_ai();
+    assert_eq!(state.route(), &Route::Instances);
+    assert_eq!(state.ai_mode(), crate::router::AiPanelMode::Docked);
+    assert!(!state.prefs.ai_collapsed);
+
+    state.toggle_ai();
+    assert!(state.prefs.ai_collapsed);
+}
+
+#[test]
+fn failed_event_settles_streaming_and_keeps_the_evidence() {
+    let mut state = AppState::new();
+    state.apply(AppEvent::Agent(AgentEvent::MessageAppended(
+        ChatMessage::assistant_stream(),
+    )));
+    state.apply(AppEvent::Agent(AgentEvent::MessageDelta {
+        index: 0,
+        delta: "我先读一下".to_string(),
+    }));
+    state.apply(AppEvent::Agent(AgentEvent::Failed {
+        message: "provider 断流：read timeout".to_string(),
+    }));
+
+    // 抓得住：已到的增量不丢、流式标记收敛、错误进横幅也进会话历史
+    assert_eq!(state.ai.messages[0].text, "我先读一下");
+    assert!(!state.ai.messages[0].streaming);
+    assert!(!state.ai.streaming);
+    assert!(!state.ai.busy);
+    assert_eq!(
+        state.ai.error.as_deref(),
+        Some("provider 断流：read timeout")
+    );
+    assert_eq!(state.ai.messages[1].role, ChatRole::System);
+    // 抓不住：这里不判断错误归因（那是 core::diagnose 的事）
+}
+
+#[test]
+fn confirm_request_keeps_the_shell_busy_until_it_resolves() {
+    // 分工：这条钉 state 层的「待确认 ⇒ busy」与 `ConfirmResolved` 收敛；
+    // presenter 层的同名守卫是 `agent::tests::pending_confirm_forces_busy_without_yolo`
+    // （r1 P2-2：那条曾因 ToolCallStarted 顺手置真而空过，已改成先 finish_stream 再断言）。
+    let mut state = AppState::new();
+    state.apply(AppEvent::Agent(AgentEvent::ConfirmRequested {
+        request: confirm_request("req-1"),
+    }));
+    assert!(state.ai.busy, "有待确认时 UI 必须禁用输入");
+    assert_eq!(
+        state.ai.confirm.as_ref().map(|request| request.id.as_str()),
+        Some("req-1")
+    );
+
+    // 别处已裁决（重放/超时）：僵尸弹窗必须收掉
+    state.apply(AppEvent::Agent(AgentEvent::ConfirmResolved {
+        id: "req-1".to_string(),
+    }));
+    assert!(!state.ai.busy);
+    assert!(state.ai.confirm.is_none());
+}
+
+#[test]
+fn unread_counts_only_while_the_rail_is_out_of_sight() {
+    let mut state = AppState::new();
+    // 展开的常驻栏在任何页面都挂着：到达即已读
+    assert!(state.agent_rail_visible());
+    state.apply(AppEvent::Agent(AgentEvent::MessageAppended(
+        ChatMessage::assistant_stream(),
+    )));
+    assert_eq!(state.ai.unread, 0);
+
+    // 收成 icon 轨 = 用户看不见
+    state.prefs.ai_collapsed = true;
+    assert!(!state.agent_rail_visible());
+    state.apply(AppEvent::Agent(AgentEvent::MessageDelta {
+        index: 0,
+        delta: "长回复".to_string(),
+    }));
+    assert_eq!(state.ai.unread, 0, "增量属于同一条消息，不重复计数");
+    state.apply(AppEvent::Agent(AgentEvent::ToolCallStarted {
+        name: "read_game_log".to_string(),
+        summary: "读取日志".to_string(),
+    }));
+    assert_eq!(state.ai.unread, 1);
+
+    // 展开栏 = 用户在看它，未读立刻归零
+    state.toggle_ai();
+    assert_eq!(state.ai.unread, 0);
+
+    // 独立页形态永远算可见
+    state.navigate(Route::Agent);
+    assert!(state.agent_rail_visible());
+}
+
+#[test]
+fn user_messages_never_count_as_unread() {
+    let mut state = AppState::new();
+    state.prefs.ai_collapsed = true;
+    state.apply(AppEvent::Agent(AgentEvent::MessageAppended(
+        ChatMessage::user("我自己说的话"),
+    )));
+    assert_eq!(state.ai.unread, 0);
+}
+
+/// 待确认请求样例（High 级写操作）。
+fn confirm_request(id: &str) -> crate::dto::ConfirmRequest {
+    crate::dto::ConfirmRequest {
+        id: id.to_string(),
+        tool: "set_config".to_string(),
+        summary: "把下载并发 64 → 16".to_string(),
+        details: serde_json::json!({ "path": "download.concurrency" }),
+        sensitivity: crate::dto::Sensitivity::High,
+    }
+}
+
+#[test]
+fn toggle_nav_flips_the_pref() {
+    let mut state = AppState::new();
+    state.toggle_nav();
+    assert!(state.prefs.nav_collapsed);
+    state.toggle_nav();
+    assert!(!state.prefs.nav_collapsed);
+}
+
+#[test]
+fn diagnosis_report_lands_on_state() {
+    let mut state = AppState::new();
+    state.apply(AppEvent::Core(CoreEvent::DiagnosisReady(DiagnosisReport {
+        session: "s1".to_string(),
+        diagnosis: Diagnosis {
+            rule: "gpu.driver_old".to_string(),
+            title: "显卡驱动过旧".to_string(),
+            confidence: 92,
+            hint: "升级驱动".to_string(),
+            fix: Some("open_driver_page".to_string()),
+        },
+    })));
+    assert!(state.diagnosis.is_some());
+}
diff --git a/crates/presenter/src/theme.rs b/crates/presenter/src/theme.rs
new file mode 100644
index 0000000..08c798c
--- /dev/null
+++ b/crates/presenter/src/theme.rs
@@ -0,0 +1,165 @@
+//! 主题与外观的**纯**判据：轮询节拍、背景图缓存键与量化、系统主题取值。
+//!
+//! 这一层原本混在 `crates/app` 的 `ui_bind.rs` / `theme_runtime.rs` 里，与「把值灌进窗口属性」
+//! 的绑定代码缠在一起，于是两个 UI 版都得各写一遍。抽到这里的只有**判据**：什么时候该重读配置、
+//! 什么时候该重建背景图、系统主题该报哪个值。灌属性仍然由 UI 侧做，本模块不碰任何框架类型。
+
+use crate::prefs::BgFill;
+
+/// 配置热切轮询间隔（拍数，33ms/拍 → 约 1s 一次 `mtime` 比对，AI/CLI 改完下一拍即生效）。
+pub const CONFIG_POLL_TICKS: u64 = 30;
+
+/// 系统主题兜底轮询间隔（拍数）：只在 `auto` 且后端不认识系统主题时启动（约 3s）。
+pub const SYSTEM_THEME_POLL_TICKS: u64 = 90;
+
+/// tile 模式重建画布的窗口尺寸粒度（像素）：避免拖动窗口时反复重算平铺画布。
+pub const TILE_REGENERATE_STEP: u32 = 128;
+
+/// 系统主题取值（UI 侧根组件属性就用这三个值：0 未知 / 1 浅色 / 2 深色）。
+pub const SYSTEM_THEME_UNKNOWN: i32 = 0;
+/// 浅色。
+pub const SYSTEM_THEME_LIGHT: i32 = 1;
+/// 深色。
+pub const SYSTEM_THEME_DARK: i32 = 2;
+
+/// 背景图加工输入（值相同就不重新解码）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BackgroundKey {
+    /// 背景图路径
+    pub path: String,
+    /// 填充模式
+    pub fill: BgFill,
+    /// tile 用的窗口尺寸（按 [`TILE_REGENERATE_STEP`] 量化；cover/contain 恒为 (0, 0)）
+    pub viewport: (u32, u32),
+}
+
+/// 本拍是否该比对一次配置文件 `mtime`（热切的采样点）。
+pub fn config_poll_due(ticks: u64) -> bool {
+    ticks.is_multiple_of(CONFIG_POLL_TICKS)
+}
+
+/// 本拍是否该兜底探测系统主题。
+///
+/// 启动时先探一次（`probed == false`），之后只在「主题是 auto + 后端不认识系统主题」时
+/// 按 [`SYSTEM_THEME_POLL_TICKS`] 兜底轮询。
+pub fn system_theme_poll_due(probed: bool, auto: bool, backend_known: bool, ticks: u64) -> bool {
+    !probed || (auto && !backend_known && ticks.is_multiple_of(SYSTEM_THEME_POLL_TICKS))
+}
+
+/// 系统主题取值（纯映射，便于单测）。
+pub fn system_theme_code(theme: unlucky_core::platform::theme_probe::SystemTheme) -> i32 {
+    use unlucky_core::platform::theme_probe::SystemTheme;
+    match theme {
+        SystemTheme::Light => SYSTEM_THEME_LIGHT,
+        SystemTheme::Dark => SYSTEM_THEME_DARK,
+        SystemTheme::Unknown => SYSTEM_THEME_UNKNOWN,
+    }
+}
+
+/// 探测本机系统主题并给出 UI 侧属性值。
+pub fn system_theme_value() -> i32 {
+    system_theme_code(unlucky_core::platform::theme_probe::probe())
+}
+
+/// tile 画布的窗口尺寸（量化到 [`TILE_REGENERATE_STEP`]，避免拖动窗口时反复重算）。
+///
+/// 非 tile 模式恒为 (0, 0)：cover/contain 不依赖窗口尺寸，缩放只让渲染器拉伸。
+pub fn tile_viewport(fill: BgFill, size: (u32, u32)) -> (u32, u32) {
+    if fill != BgFill::Tile {
+        return (0, 0);
+    }
+    (
+        size.0 / TILE_REGENERATE_STEP * TILE_REGENERATE_STEP,
+        size.1 / TILE_REGENERATE_STEP * TILE_REGENERATE_STEP,
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{
+        config_poll_due, system_theme_code, system_theme_poll_due, tile_viewport, BackgroundKey,
+        CONFIG_POLL_TICKS, SYSTEM_THEME_DARK, SYSTEM_THEME_LIGHT, SYSTEM_THEME_POLL_TICKS,
+        SYSTEM_THEME_UNKNOWN, TILE_REGENERATE_STEP,
+    };
+    use crate::prefs::BgFill;
+    use unlucky_core::platform::theme_probe::SystemTheme;
+
+    #[test]
+    fn config_poll_fires_every_interval() {
+        assert!(config_poll_due(0));
+        assert!(!config_poll_due(1));
+        assert!(config_poll_due(CONFIG_POLL_TICKS));
+        assert!(!config_poll_due(CONFIG_POLL_TICKS + 1));
+    }
+
+    #[test]
+    fn system_theme_probe_backs_off_after_first_read() {
+        // 启动时无条件探一次
+        assert!(system_theme_poll_due(false, false, true, 1));
+        // 探过、主题非 auto：不再轮询
+        assert!(!system_theme_poll_due(
+            true,
+            false,
+            false,
+            SYSTEM_THEME_POLL_TICKS
+        ));
+        // 探过、auto、后端认识系统主题：不再轮询
+        assert!(!system_theme_poll_due(
+            true,
+            true,
+            true,
+            SYSTEM_THEME_POLL_TICKS
+        ));
+        // 探过、auto、后端不认识：按间隔兜底
+        assert!(!system_theme_poll_due(
+            true,
+            true,
+            false,
+            SYSTEM_THEME_POLL_TICKS - 1
+        ));
+        assert!(system_theme_poll_due(
+            true,
+            true,
+            false,
+            SYSTEM_THEME_POLL_TICKS
+        ));
+    }
+
+    #[test]
+    fn system_theme_codes_are_stable() {
+        assert_eq!(
+            system_theme_code(SystemTheme::Unknown),
+            SYSTEM_THEME_UNKNOWN
+        );
+        assert_eq!(system_theme_code(SystemTheme::Light), SYSTEM_THEME_LIGHT);
+        assert_eq!(system_theme_code(SystemTheme::Dark), SYSTEM_THEME_DARK);
+    }
+
+    #[test]
+    fn tile_viewport_quantizes_and_ignores_other_fills() {
+        assert_eq!(tile_viewport(BgFill::Cover, (1180, 760)), (0, 0));
+        assert_eq!(tile_viewport(BgFill::Contain, (1180, 760)), (0, 0));
+        let (width, height) = tile_viewport(BgFill::Tile, (1180, 760));
+        assert_eq!(width % TILE_REGENERATE_STEP, 0);
+        assert_eq!(height % TILE_REGENERATE_STEP, 0);
+        assert_eq!((width, height), (1152, 640));
+    }
+
+    #[test]
+    fn background_key_compares_by_value() {
+        let key = BackgroundKey {
+            path: "a.png".to_string(),
+            fill: BgFill::Tile,
+            viewport: (256, 256),
+        };
+        assert_eq!(key.clone(), key);
+        assert_ne!(
+            key,
+            BackgroundKey {
+                path: "a.png".to_string(),
+                fill: BgFill::Tile,
+                viewport: (128, 256),
+            }
+        );
+    }
+}
diff --git a/crates/presenter/src/toast.rs b/crates/presenter/src/toast.rs
new file mode 100644
index 0000000..d2d9bd3
--- /dev/null
+++ b/crates/presenter/src/toast.rs
@@ -0,0 +1,154 @@
+//! Toast 中心：右下角非阻塞提示（下载完成 / 复制成功 / 后台任务结论）。
+//!
+//! 与模态对话框队列（[`crate::dialogs`]）分开：Toast 不阻塞、不排序、可叠加，
+//! 只做「先进先出 + 上限裁剪 + TTL 到期」。UI 侧由 Rust 定时器每帧调用 [`ToastCenter::expire`]。
+
+use serde::{Deserialize, Serialize};
+
+/// Toast 标识。
+pub type ToastId = u64;
+
+/// Toast 语义色。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ToastKind {
+    /// 一般信息
+    Info,
+    /// 成功
+    Success,
+    /// 警告
+    Warn,
+    /// 错误
+    Error,
+}
+
+/// 一条 Toast；`remaining_ms` 由 [`ToastCenter::expire`] 递减。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Toast {
+    /// 队列内唯一 id（由 [`ToastCenter::push_request`] 重新编号）
+    pub id: ToastId,
+    /// 语义色
+    pub kind: ToastKind,
+    /// 提示文案
+    pub text: String,
+    /// 剩余存活毫秒（0 = 用默认 TTL，入队时补）
+    pub remaining_ms: u64,
+}
+
+/// Toast 中心：先进先出，超出上限丢最旧的。
+#[derive(Debug)]
+pub struct ToastCenter {
+    items: Vec,
+    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/packaging/README.md b/packaging/README.md
new file mode 100644
index 0000000..0408af6
--- /dev/null
+++ b/packaging/README.md
@@ -0,0 +1,401 @@
+# 打包与发布工程（packaging/）
+
+单一真相源：**单文件产物矩阵 + 发布契约**。`.github/workflows/release.yml` 按本文实现，
+`packaging/make_artifacts.py` 是本地与 CI **共用**的打包脚本（同一份代码 → 同一套目录布局）。
+本目录只放发布工程资产（脚本 / 说明 / 发布说明模板），不参与任何 crate 的编译。
+
+## 1. 产物矩阵
+
+| 槽位 | 产物文件名 | 形态 | 归档内容 |
+|------|-----------|------|---------|
+| `windows-x64` | `unlucky-launcher__windows_x64.exe` | **裸 exe**（双击即用） | exe 单文件；三份合规文本作为并列 Release 资产 |
+| `windows-arm64` | `unlucky-launcher__windows_arm64.exe` | **裸 exe**（同 x64 策略） | 同上；在 x64 宿主上交叉编译到 `aarch64-pc-windows-msvc` |
+| `linux-x64` | `unlucky-launcher__linux_x64.tar.gz` | 单二进制归档 | `unlucky-launcher` + `LICENSE` + `NOTICE` + `README.md` |
+| `linux-arm64` | `unlucky-launcher__linux_arm64.tar.gz` | 单二进制归档（原生 ARM64 runner 构建） | 同上 |
+| `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` 可直吃） |
+
+约定细节：
+
+- **产物命名**：`<名字>_<版本号>_<平台>_<架构>`，下划线分段、**不带实现细节字样**（不出现 `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.0`，文件名是 `0.2.0`）——由脚本统一裁剪。
+- UNIX 归档内 `mtime`/`uid`/`gid` 归零、权限固定（二进制 0755、文本 0644），
+  同源构建的 sha256 不受打包时刻影响。
+- **架构不靠猜**：脚本打包前回读二进制的可执行文件头（PE 机器码 / ELF `e_machine` /
+  Mach-O `cputype`），与槽位声明的架构不符即失败——交叉槽位（x64 宿主产 arm64 exe）不会
+  出现"名字是 arm64、内容还是 x64"的假产物。
+
+## 2. 版本来源（唯一真相源）
+
+版本号只有一个来源：**`Cargo.toml` 的 `[workspace.package] version`**。
+
+- `` 由 `make_artifacts.py` 通过 `cargo metadata --no-deps` 读出（不是正则扒文件），
+  任何一个 workspace member 版本不一致时直接失败。
+- 带 tag 构建时（CI）额外传 `--version "$TAG"`：脚本裁剪 `v` 后与 `Cargo.toml` 交叉校验，
+  **不一致即失败**——避免出现 tag 说 0.2.0、产物里写 0.1.0 的发布事故。
+- `ull --version` 必报同一版本（脚本打包前跑一次冒烟 `ull --version` 断言版本串在其中），
+  这是 `env!("CARGO_PKG_VERSION")` 的实际输出，不是估算。
+- 发布流程：先改 `Cargo.toml` 版本 + 提交 → `git tag v` → 推送 tag 触发流水线。
+
+## 3. 怎么构建
+
+### 本地（当前平台）
+
+```bash
+cargo build --release --locked                 # 产出 target/release/{unlucky-launcher-iced,ull}（M118：Slint 版不再进 workspace）
+cargo build --profile fast --bins              # 只是想快点看到画面/跑测试：快档（§6），产物在 target/fast/
+python packaging/make_artifacts.py --out dist  # 产物落在 dist/，含 SHA256SUMS.txt
+python packaging/make_artifacts.py --version v0.2.0   # 顺带校验版本一致性
+python packaging/make_artifacts.py --no-smoke         # 跳过 ull --version 冒烟
+```
+
+脚本按宿主自动判定槽位（Windows x64 / Windows arm64 / Linux x64 / Linux arm64 / macOS arm64 /
+macOS x64），其它组合直接报错退出——不在矩阵里的平台不出"凑合能跑"的产物。
+
+交叉构建（例如在 x64 宿主上产 Windows arm64 产物）靠两个参数把"产物根"和"槽位"显式喂进去，
+脚本不去猜宿主与产物是不是同一架构：
+
+```bash
+rustup target add aarch64-pc-windows-msvc
+cargo build --release --locked --target aarch64-pc-windows-msvc \
+  --bin unlucky-launcher-iced --bin ull   # 不用 --bins：矩阵只发 GUI + ull；GUI 的构建产物名是 iced 的 bin（M118）
+python packaging/make_artifacts.py --slot windows-arm64 \
+  --build-dir target/aarch64-pc-windows-msvc/release --out dist
+```
+
+`--slot` 与宿主槽位不一致时，`ull --version` 冒烟会**自动跳过并打印原因**（arm64 产物在 x64
+宿主机上根本执行不了；拿"跳过"当通过是假证据，所以跳过永远带原因）——那条路径的验证只能落在
+CI 真机上：`windows-arm64` 由 cross 构建产物 + M50 的 dumpbin 导入表门禁覆盖，`linux-arm64`
+由 `ubuntu-22.04-arm` 原生 runner 上真跑冒烟覆盖。
+
+### CI（四平台六槽位矩阵）
+
+`.github/workflows/release.yml`：
+
+- 触发：`push` tag `v*`；`workflow_dispatch` 只构建不发布（验证矩阵仍编得过）。
+  `inputs.prerelease` **只在 tag ref 上 dispatch 才可达**——Actions 页面的 "Run workflow" 只能选分支，
+  要跑 tag 得 `gh workflow run release.yml --ref v0.2.0`。分支 ref 的 dispatch 与 push 一样被
+  `release` job 的 `if: github.ref_type == 'tag'` 挡在发布之外，所以「dispatch 只构建不发布」
+  与「dispatch 能关 pre-release」是两条互不冲突的规则。
+- 矩阵（六槽位；`matrix.build_dir` 参数化产物根，脚本不再假设产物一定在 `target/release`）：
+  `windows-latest` x64（MSVC + `-C target-feature=+crt-static`）、`windows-latest` **交叉编译**到
+  `aarch64-pc-windows-msvc`（产物在 `target/aarch64-pc-windows-msvc/release`）、`ubuntu-22.04`
+  （glibc 2.35 地板）、`ubuntu-22.04-arm`（原生 ARM64 runner，**与 x64 同 2.35 地板**）、`macos-latest`（arm64）、
+  `macos-15-intel`（Intel x64；`macos-13` 已下线，`macos-26-intel` 为更新替位）。
+- 每个槽位 `cargo build --release --locked`（交叉槽位多两步：`rustup target add` + ARM64 库体检
+  ——查 VC 的 `lib/arm64/libcmt.lib`（`+crt-static` 靠它）与 SDK 的 `um/arm64/kernel32.lib`，
+  缺了直接给出"给 VS 加 `VC.Tools.ARM64` 或改用原生 `windows-11-arm`"的可执行提示）→
+  `make_artifacts.py --slot … --build-dir …` → 归档内容自检 → 上传 artifact。
+- `release` job：下载全部 artifact → 重算一份全量 `SHA256SUMS.txt` → 用 `packaging/release-notes.md`
+  模板渲染支持矩阵 → `gh release create`（**pre-release 默认开**：首建时 `push` 触发按 pre-release，`workflow_dispatch` 可关）。
+- **同一 tag 重跑幂等**：`gh release view` 命中已存在的 Release 时改走 `gh release upload --clobber`
+  + `gh release edit`，覆盖资产与说明而不是再 `create`（`create` 遇已存在会失败，把流水线最后一步染红）。
+- **pre-release 标记只按显式输入断言**：`gh release edit` 分支在默认重跑（`push` 触发的 Re-run，
+  `inputs.prerelease` 为空）时**不传** `--prerelease`，所以重跑**不会**翻转标记；只有 tag ref 上的
+  `workflow_dispatch` 显式给了输入才断言——`prerelease=true` → `--prerelease`，`prerelease=false` →
+  `--prerelease=false`。要改标记两条路等价且互不打架：① 走流水线
+  `gh workflow run release.yml --ref v0.2.0 -f prerelease=false`（会落到 edit 分支显式断言）
+  ② 直接 `gh release edit  --prerelease=false`（不经流水线；后续默认重跑不碰该标记，
+  不会被翻回去）。首建（`create`）仍保持「pre-release 默认开」的老契约，空输入按 `true` 处理。
+
+Windows 为什么用 MSVC 静态 CRT 而不是本机这套 GNU 工具链：两者都属"标准工具链"（D21），
+但发布产物要**不依赖 VC++ 可再发行包**，`+crt-static` 把 CRT 静态链进 exe，Win10+ 的 UCRT 本身是
+系统组件，于是 exe 真正单文件可拷走。GNU 交叉产物在 CI 上还要拉 MinGW 链接器，收益为零。
+
+## 4. 每平台运行时依赖
+
+### Windows x64（Win10/11）
+
+| 依赖 | 来源 | 说明 |
+|------|------|------|
+| `KERNEL32` / `USER32` / `GDI32` / `ADVAPI32` / `SHELL32` / `ole32` / `WS2_32` … | 系统 | Win10+ 一律自带 |
+| `ucrtbase` / `api-ms-win-crt-*`（UCRT） | 系统 | Win10+ 内置，**不需要** VC++ 可再发行包 |
+| MSVC 运行时（`VCRUNTIME140` / `MSVCP140`） | **无** | `+crt-static` 静态链接，故不需要可再发行包 |
+| OpenGL（`opengl32`） | 系统 | 只在 GL 渲染路径用；缺失走软渲染 |
+
+本机（GNU 工具链）实测导入表证据见 §7。
+
+### Windows ARM64（Win11 on ARM）
+
+产物形态与门禁跟 x64 一模一样（裸 exe + 静态 CRT + dumpbin 导入表硬门禁），差别只在**怎么编**：
+CI 在 `windows-latest`（x64 宿主）上交叉编译到 `aarch64-pc-windows-msvc`，产物落在
+`target/aarch64-pc-windows-msvc/release`（由 `matrix.build_dir` 注入，脚本不硬编码路径）。
+GitHub 文档（2026）已把 `windows-11-arm` / `windows-11-vs2026-arm` 列为公开仓库**免费**的标准
+arm64 runner，原生路线可行；本流水线仍选交叉编译，因为①双 Windows 槽位共用同一套已验证镜像与
+工具链、②M50 的 dumpbin 定位链取的是 `Hostx64/x64/dumpbin.exe`（读 ARM64 PE 的导入表没问题），
+原生 ARM 宿主上那条链得再补 `Hostarm64` 分支——不为一个槽位放宽刚立的门禁。
+
+运行时依赖与 x64 同表（UCRT 是 Win11 ARM 的系统组件，`+crt-static` 静态链 CRT，不需要可再发行包）。
+游戏侧如实说：**启动器原生运行**；Temurin 没有 windows-aarch64 产物，Microsoft OpenJDK 有该
+发行版（core 的 `microsoft` 源按 `-` 拼名，命名已覆盖），但 Minecraft 本体没有
+Windows ARM64 原生库（Mojang/LWJGL 只发 x64/x86），实际游玩仍走系统 x64 模拟层 + x64 JDK。
+所以本槽位只承诺「启动器产物」支持，不替 Java/游戏管理做架构级承诺。
+
+### Linux x64
+
+| 依赖 | 说明 |
+|------|------|
+| glibc ≥ 2.35 | 由 `ubuntu-22.04` 构建决定；更老的发行版请自行重建或等 musl 版 |
+| `libxkbcommon.so.0` | winit 键盘处理 |
+| `libfontconfig.so.1` + `libfreetype.so.6` | 文本渲染 |
+| `libGL.so.1` / `libEGL.so.1` | Slint 版：femtovg 的 GL 渲染；iced 版：wgpu 的 GL/EGL 后端（**推断，未实测**）。两者缺失都退到 CPU 软渲染（tiny-skia） |
+| `libxcb.so.1` / `libX11.so.6` | X11 后端（Wayland 会话下也需 XWayland 相关库） |
+| `libwayland-client.so.0` | Wayland 后端 |
+
+Debian/Ubuntu 一行：`sudo apt install libxkbcommon0 fontconfig libgl1 libegl1 libxcb1 libx11-6 libwayland-client0`。
+运行期**不需要** `-dev` 包、不需要 Java（Java 是启动游戏时才由启动器自己管理的东西）。
+
+**M118（D26）口径**：除上表里标注「推断，未实测」的那一行外，这张表与下面这条结论都是 **Slint 版 GUI** 的实测记录（M82：`readelf -d` + `ldd` + `nm -D`）；iced 版（`crates/app-iced`）的 `DT_NEEDED` / `dlopen` 集合**尚未重测**，请按「同一族库、细节待验」读，别当成 iced 版的实测承诺。
+仍然成立的部分：上表是**开窗**要用的库，不是进程启动门槛——实测（§7.4，Slint 版）除 `libfontconfig.so.1` 外它们**都不在** ELF 的 `DT_NEEDED` 里，由 `dlopen` 在开窗那一刻才加载，所以没有 X11 / Wayland / GL 的机器上 `unlucky-launcher instances list` 照样跑得起来，`ull` 连 fontconfig 都不需要。
+arm64 侧同理（同一份依赖树；历史口径里的「winit + femtovg」中 femtovg 只属于 Slint 版）。
+
+### Linux arm64（aarch64）
+
+依赖与 x64 完全同一套（`libxkbcommon` / `fontconfig` / `libGL` / `libxcb` / `libwayland-client`），
+**glibc 地板也相同**：arm64 槽位跑在原生 `ubuntu-22.04-arm` runner 上，地板 = **2.35**，与 x64
+用的 `ubuntu-22.04` 一致。选 22.04 而不是 24.04 就是为了这个地板——24.04 的 glibc 更高，会把
+Debian 12（2.36）、Raspberry Pi OS Bookworm（2.36）这些实际在跑的 ARM 发行版挡在门外。
+要抬地板（例如将来 ARM 生态整体上移）换 `release.yml` 里那个槽位的 `os` 即可，脚本与产物名都不用动；
+`ubuntu-24.04-arm` / `ubuntu-26.04-arm` 都是同一家族的标准公开仓库标签（4C/16GB、免费不限量）。
+
+### macOS 12+
+
+| 依赖 | 说明 |
+|------|------|
+| 系统框架（Cocoa / Metal / IOKit / Security …） | 由操作系统提供，无第三方动态库 |
+| `libSystem` | 系统 |
+
+macOS 产物是**裸二进制**而非 `.app` bundle：符合单文件承诺，但没有 Dock 图标、Finder 双击不生效，
+从终端启动（README 里给了 `xattr -d com.apple.quarantine` 的 Gatekeeper 解法）。
+签名/公证（需 Apple Developer 账号）与 `.app` 打包是后续工作，不做假承诺。
+
+## 5. 软渲染兜底（无 GPU / 老驱动 / 远程桌面）
+
+M118（D26）：以下是**历史实现（Slint 版，默认 `renderer-femtovg`/GL）**的兜底路径，已不在默认构建与发布矩阵内（`crates/app` 被 workspace `exclude`，源码仅作参考、不编译）。现役 GUI 是 iced 版：`unlucky-launcher-iced --software-renderer`（= `ICED_BACKEND=tiny-skia`）走 tiny-skia 光栅化。v0.1.0 的产物仍认下面两条：
+
+```bash
+unlucky-launcher --software-renderer                     # 启动参数（本仓库解析后设 SLINT_BACKEND）
+SLINT_BACKEND=winit-software unlucky-launcher            # 环境变量（Slint 原生开关）
+```
+
+- 参数解析在 `crates/app/src/main.rs` 的 `apply_renderer_flag()`，只认完全相等的 `--software-renderer`。
+- 软渲染是 CPU 光栅化，无 GPU 也能出图；代价是动画与大窗口重绘更慢（Metro 纯色界面影响有限）。
+- 截图通道 `--screenshot `：历史实现 `crates/app/src/screenshot.rs`，现役 `crates/app-iced/src/shot/`；
+  软渲染下照样出图，是 CI 与远程机唯一可靠的"真出图"证据（发布冒烟见 §7，本机实跑 `--software-renderer --screenshot`）。
+
+## 6. Cargo 构建档位（release 体积档 / fast 速度档）
+
+| 档位 | 用在哪 | opt-level | lto | codegen-units | panic |
+|------|--------|-----------|-----|---------------|-------|
+| `release` | 发布 / 验收产物 | `"z"`（workspace 自身 crate） | `fat` | 1 | `abort` |
+| `release.package."*"` | 同上，**只作用于依赖** | `"z"` | 不可覆盖 | 16 | 继承 |
+| `fast` | 日常迭代、本机跑测试 | 2 | `thin` | 16 | `unwind` |
+
+- **`release` 是体积档**：`fat` + 单 CGU 换来实测 GUI −10.8% / CLI −18.7%（§7.1）。变慢的根源在 `codegen-units = 1`
+  （单 CGU → LTO 只一个线程可跑；`fat` 只管"跨 crate 全量参与"，不等于单线程），375 个 crate 排队链接就是十几分钟的量。
+- **`release.package."*"` 放宽的只有并行度，不是 opt-level**：实测把依赖 opt-level 抬到 3 反而**又慢 29.6%
+  又大 19~24%**（§7.1），所以保持 `"z"`、只把 `codegen-units` 放到 16。package 覆盖**只允许调优化强度**：
+  `panic` / `lto` / `rpath` 写进去 cargo 直接报错，`strip` 会改变整个二进制的运行时行为——都不许出现。
+- **`fast` 是速度档，不是发布物**：`thin` LTO + 16 CGU 可并行，`opt-level = 2` 介于 `z` 与 3 之间。
+  `panic = "unwind"` 是给**编出来的二进制**留的（`release` 是 `abort`，`inherits` 会照抄）；`cargo test`
+  **不**依赖它——cargo 对 test 目标自己强制 unwind（实测 release/abort 档下 `cargo test --profile release`
+  照跑、23 个测试全过，test 单元的 rustc 参数里没有 `-Cpanic=`）。要看这行是否生效，比 `cargo build -v`
+  的 rustc 参数：release 有 `panic=abort`、fast 没有。它继承 `strip="symbols"`，所以能 unwind 但**没有符号
+  回溯**——要栈回溯就给 fast 档加 `strip = false`，代价是体积再涨。
+- **`fast` 在机械盘机器上冷编译并无收益**（比 release 还慢、体积 2.3 倍，§7.1），价值在 SSD 机器与增量重编。
+- **`[profile.fast.package."*"]` 是承重墙**：`inherits` 会把 release 的 package 覆盖一起带过来（实测：删掉它，fast 档外部依赖静默退回 `"z"`），必须存在。
+- 本地开发迭代走 `cargo build`（dev profile）不受影响，但 **`ci.yml` 每次 push/PR 都跑
+  `cargo build --workspace --release`**，会实打实吃这份 fat LTO 的链接时间——CI 慢的一部分是 release 档构建。
+
+## 7. 实测（本机，不是估算）
+
+构建环境：rustc 1.99.1 stable / `x86_64-pc-windows-gnu`（MinGW 链接器）。§7.2/§7.3 的早数字是另有 worker 并发做全量 debug 构建时测的（偏悲观）；§7.1 的三行 M96 数据是空载冷编译。
+
+**本节以下所有输出里的 `0.1.0` 都是当时那次运行的真实输出（workspace 版本那时是 `0.1.0`），属实测记录，不随后续版本号改动而回填**；当前版本见 `Cargo.toml` 的 `[workspace.package] version`。§2 的校验机制不依赖任何写死的数字，改版本号不会让它失效。
+
+### 7.1 体积与冷构建耗时（实测字节数，不是估算）
+
+| 档位 | `unlucky-launcher.exe` | `unlucky-launcher-iced.exe` | `ull.exe` | 冷构建耗时 |
+|------|-----------------------|----------------------------|-----------|-----------|
+| `release`，`thin`（M46 前） | 16,366,080 B = 15.61 MiB | 未测（当时无 iced 版） | 7,572,992 B = 7.22 MiB | 11m52s |
+| `release`，`fat`，依赖全 `"z"`（M46，改前） | **14,595,584 B = 13.92 MiB** | 未测 | **6,157,824 B = 5.87 MiB** | 9m27s（增量） |
+| `release`，`fat` + 依赖 opt-3 / cu16（M96 试过的那版，**已否**） | 20,407,296 B = 19.46 MiB | 18,371,584 B = 17.52 MiB | 7,743,488 B = 7.38 MiB | 22m45s（冷） |
+| `release`，`fat` + 依赖 `"z"` / cu16（**M96 起，发布档**） | **16,479,232 B = 15.72 MiB** | **13,910,528 B = 13.27 MiB** | **6,256,128 B = 5.97 MiB** | **16m01s（冷）** |
+| `fast`，`thin` + cu16（M96 起，日常档） | 38,182,400 B = 36.41 MiB | 33,570,304 B = 32.02 MiB | 15,967,744 B = 15.23 MiB | 24m27s（冷） |
+
+测量条件（M96 三行）：12 核 / `x86_64-pc-windows-gnu` / `-j 4`，源码机械盘、`CARGO_TARGET_DIR` 在 SSD，均为**删空 target 后的
+冷编译**、同机同晚无并发负载；M46 两行是更早提交上的数字（依赖已热 / 另有并发），**跨行比耗时没意义**。
+① **依赖 opt-level 从 3 退回 `"z"` 又快 29.6% 又小 19~24%**（两臂同为 cu16，唯一自变量是 opt-level）——抬 opt-level 是拿编译时间和体积换运行期；
+`cu1 → cu16` 的收益本轮**没有同条件对照**，未归因。② `fast` **冷编译比 `release` 还慢**（24m27s vs 16m01s）、体积 2.3 倍，瓶颈在两个大 UI
+crate + 链接 + 机械盘 IO——定位是 **SSD 机器与增量重编**，不是冷编译加速。体积归因：GUI 相对旧基线 +12.9%（13.92 → 15.72 MiB）里
+「代码增长」与「依赖 cu16」**未分离**；`ull` 只 +1.7%，在 +1~3% 口径内。体积构成（**M118 前的 Slint 版，历史数**）：Slint 运行时（双渲染器 + winit/accesskit/托盘）+ rustls/reqwest + rig/rmcp/axum 为主，`ull` 更小是 D18（CLI 零 UI 依赖）的结果。
+
+### 7.2 冒烟（真跑，2026-10-31 夜间 + 11-01 早，本机 Win11 26100）
+
+| 命令 | 实测结果 |
+|------|---------|
+| `ull.exe --version` | 输出 `ull 0.1.0（unlucky-cli）` + `os: Windows 11 · 10.0.26100（x86_64）· 满足最低要求`，exit 0 —— 版本与 workspace `0.1.0` 一致 |
+| `unlucky-launcher.exe --software-renderer --screenshot … --data-dir …`（Slint 版，历史实测） | exit 0，产出 1180×760 PNG（3,588,298 B）；看图确认 Metro 实例页（侧栏/搜索/空态/AI 助手面板）正常渲染 → **软渲染路径真的能出图**，不依赖 GL |
+| `unlucky-launcher.exe --version` | **无输出**，8 秒后被 timeout 杀掉（exit 124）——GUI 当时不解析 `--version`，会直接开窗口。M82 后已修（走 CLI 分发，见 §10-1）|
+
+### 7.3 打包验证（本机 Windows 槽位真跑）
+
+```
+smoke: ull.exe --version -> 0.1.0 (ok)
+artifact: unlucky-launcher-0.1.0-windows-x64.exe  13.92 MiB  sha256=d4954c62…c3570
+sums:     SHA256SUMS.txt
+$ sha256sum -c SHA256SUMS.txt
+unlucky-launcher-0.1.0-windows-x64.exe: OK
+```
+
+版本守卫也实测过：`--version v9.9.9` 时脚本以 `tag/version mismatch: requested 9.9.9, Cargo.toml says 0.1.0` 失败退出（exit 1）。
+
+UNIX 归档的可复现性单独取证（本机 Windows 槽位只走裸 exe 分支，tar 路径要另测）：
+reviewer-packaging 在 M46 review 里连续调 `stage_archive()` 两次 → **两次 sha256 完全一致**
+`a99d6e9e727cd7e390434c566a15978451f340858fa89836e2f63790bbc392f8`；成员 `mtime=0`、
+`uid=gid=0`、`uname/gname` 为空、`mode` 0755（二进制）/ 0644（文本），gzip header 的 mtime 字段是
+`00000000`，归档内单顶层目录且含 `LICENSE`/`NOTICE`/`README.md`。
+即"同源构建 → 同 sha256"在 tar 路径上成立，不随打包时刻漂移（见 §1 的约定细节）。
+
+### 7.4 运行时依赖证据（PE 导入表 / ELF `DT_NEEDED`）
+
+`objdump -p target/release/unlucky-launcher.exe` 共 42 条 DLL 导入记录、33 个不同名字（大小写各记一次），全部是 Windows 自带：
+`KERNEL32/USER32/GDI32/ADVAPI32/SHELL32/SHLWAPI/ole32/oleaut32/combase/comctl32/dwmapi/dwrite/imm32/
+uxtheme/uiautomationcore/opengl32/ws2_32/bcrypt/bcryptprimitives/ntdll` + 一组 `api-ms-win-crt-*`（UCRT API set）。
+
+**没有** `VCRUNTIME140.dll` / `MSVCP140.dll` 这类 MSVC 可再发行包依赖，也没有 `libwinpthread-1.dll` /
+`libgcc_s_*.dll` 之类 MinGW 运行时 —— 即"拷走一个 exe 就能跑"（Win10+ 自带 UCRT）。
+CI 的 MSVC `+crt-static` 产物同理（静态 CRT）；`release.yml` 里用 `dumpbin -dependents` 把这条变成硬门禁，
+两侧都 fail、没有降级分支：**出现 VCRUNTIME/MSVCP/ucrtbase 就 fail**，**找不到 dumpbin 同样 fail**
+（`windows-latest` 自带 VS 工具链，基本找得到；"找不到就跳过"等于让门禁在最需要它的时候失效）。
+总之不允许"悄悄要用户装可再发行包"。
+注意：本机只装了 GNU 工具链，MSVC 那个槽位的产物本身**没有在本机验证过**，由 CI 首跑验证。
+
+Linux 侧同一件事的对照（M82 实测：`readelf -d` + `ldd` + `nm -D`，容器内 Debian 12 glibc 2.36；被测的是 **Slint 版 GUI，历史实测**）：Slint
+GUI 的 ELF `DT_NEEDED` 只有 `libfontconfig.so.1` / `libgcc_s.so.1` / `libm.so.6` / `libc.so.6` /
+`ld-linux-x86-64.so.2`；`libX11` / `libxcb` / `libxkbcommon` / `libwayland-client` / `libGL` / `libEGL`
+**都不在**导入表里，而是以字符串形式由 `dlopen` 在开窗那一刻加载（`nm -D` 可见 `U dlopen@GLIBC_2.34` /
+`dlsym` / `dlclose`）。所以 §4 那张「开窗要的库」不是启动前提，缺了也不影响进程起来跑 CLI；
+`ull` 的 `DT_NEEDED` 连 fontconfig 都没有，只剩 glibc 那一组。
+
+**补一次真跑（M82 复审在 `debian:bookworm-slim` 上做的）**：镜像里 X11 / wayland / GL / EGL / xkbcommon /
+libxcb 条目数 = 0，只把 fontconfig 那 7 个 `.so` 放进 `LD_LIBRARY_PATH`，跑**改动后**的二进制 → `--version`
+与 `--help` exit 0、`instances list --json` 合法 JSON exit 0、`lst` exit 1 且带提示；`readelf -d` 复核仍是
+恰好 5 条 `DT_NEEDED`（无 `libstdc++`、无任何图形库），`ull` 4 条 —— 即「能跑完子命令」是实测，不是推论。
+
+### 7.5 arm64 槽位的本机验证（脚本层取证，不假装跑得动 arm64 二进制）
+
+本机没有 ARM 机器，也不具备 MSVC ARM64 链接库组合，所以只做**能真实证明的东西**（`python` 直接加载
+`packaging/make_artifacts.py` 调函数 + 走 CLI 全流程，证据见下）：
+
+| 取证项 | 结果 |
+|--------|------|
+| 宿主判定注入 | `win32/AMD64`→`windows-x64`、`win32/ARM64`→`windows-arm64`、`linux/x86_64`→`linux-x64`、`linux/aarch64`→`linux-arm64`、`linux/arm64`→`linux-arm64`、`darwin/arm64`→`macos-arm64`、`darwin/x86_64`→`macos-x64`、`freebsd/riscv64`→exit 1 |
+| 文件头架构识别 | 真 `unlucky-launcher.exe`→`x64`；合成 PE `0xAA64`→`arm64` / `0x8664`→`x64`；ELF `0xB7`→`arm64` / `0x3E`→`x64`；Mach-O `0x0100000C`→`arm64` / `0x01000007`→`x64`；垃圾字节→`None`（拒绝出包） |
+| `windows-arm64` stub 全流程 | 把真 exe 的 PE 机器码改成 ARM64 当 stub：`arch: … -> arm64 (ok for windows-arm64)`、`smoke: skipped (host is windows-x64, artifact is windows-arm64)`、产物 `unlucky-launcher-0.1.0-windows-arm64.exe` 14.01 MiB，`SHA256SUMS.txt` 行名一致 |
+| 架构守卫真拦 | x64 二进制冒充 `--slot windows-arm64` → exit 1：`is a x64 binary but slot windows-arm64 says arm64` |
+| `linux-arm64` stub 归档 | 成员 `unlucky-launcher-0.1.0-linux-arm64/{LICENSE,NOTICE,README.md,unlucky-launcher}`，权限 0644/0755、`uid=gid=0`、mtime 0、gzip 头 mtime 字段 `00 00 00 00`；连调两次 sha256 完全一致（`f949d0f5…`）→ 可复现规则与 x64 同源 |
+| `windows-x64` 原生回归 | `arch: … -> x64`、`smoke: ull.exe --version -> 0.1.0 (ok)`、产物 14.01 MiB、`sha256sum -c SHA256SUMS.txt` OK（这一次用的是当前工作树的二进制，与 §7.3 那次不是同一次构建，sha256 自然不同） |
+
+**没在本地验证、只能由 CI 补的**：`windows-arm64` 的交叉链接与真实 ARM64 导入表、`linux-arm64` 在
+原生 arm64 runner 上的真跑。本机连 `raw.githubusercontent.com` 都解析不了，所以 runner 镜像里到底装没装
+ARM64 的 MSVC 库**没法在这里查证**——`release.yml` 为此加了一道链接前的体检（查 `libcmt.lib` 与
+`um/arm64/kernel32.lib`，缺了直接给"加 `VC.Tools.ARM64` 组件或改原生 runner"的提示），首跑即见分晓。
+merge 后由 tower 重指 tag 重跑流水线，两槽位进 `SHA256SUMS.txt` 即算闭环。
+
+## 8. 发行合规
+
+- `LICENSE`（Apache-2.0 全文）与 `NOTICE`（含 Slint Royalty-Free 2.0 义务说明）随包分发，
+  三份文本在 UNIX 归档内、在 Windows 侧作为并列 Release 资产。
+- Slint 的 RF 2.0 义务：关于页保留 `AboutSlint` 部件（已在 UI 内），不得移除；
+  选 RF 分支即不触发 GPL 分支义务（见 `deny.toml` 的许可证白名单注释）。
+- **M118 后这条义务只跟着已发布的 `v0.1.0` 资产走**：`crates/app` 已被 workspace `exclude`，发布矩阵里再没有链接 Slint 的二进制，新的 iced 版产物不链接 Slint；`deny.toml` 那条 RF-2.0 allow 因此暂时是死条目（不删，留给将来真有别的路径引入 Slint 时兜底）。
+- `README.md`（英文主版）随包分发；中文版 `README.zh-CN.md` 留在仓库不进包（避免包体噪音）。
+- 依赖许可门禁不变：`deny.toml` 白名单（Apache-2.0 / MIT / BSD / Zlib / BSL-1.0 / ISC / CC0 / Unlicense /
+  Unicode-3.0 / CDLA-Permissive-2.0 / Slint-RF-2.0）。发布任务不新增任何依赖。
+- 发布产物不含游戏本体、不含 JRE、不含任何账号数据；`ull`/GUI 的数据目录在用户侧生成。
+
+## 9. 支持矩阵（对外口径，与 release-notes 模板逐行一致）
+
+| 平台 | 级别 | 运行时要求 |
+|------|------|-----------|
+| Windows 10/11 x64 | 一等 | 无（UCRT 系统自带） |
+| Windows 11 ARM64 | 一等（启动器产物） | 无额外库；启动器原生运行，游戏本体走系统 x64 模拟层 + x64 JDK |
+| macOS 12+（arm64 / x64） | 一等 | 无第三方库；未签名需去 quarantine |
+| Linux x64 X11 | 一等 | glibc 2.35+、xkbcommon、fontconfig、libGL、xcb |
+| Linux x64 Wayland | 支持 | 上述 + wayland-client |
+| Linux arm64 X11 | 一等 | glibc 2.35+（`ubuntu-22.04-arm` 原生构建，**与 x64 同地板**）、xkbcommon、fontconfig、libGL、xcb |
+| Linux arm64 Wayland | 支持 | 上述 + wayland-client |
+| Windows 8.1/8/7 | 不支持 | 基线已上调（D21） |
+| Android Termux + X11 | 试验级（不承诺） | 仅 CLI（源码自建），GUI 未验证，不在本发布矩阵内 |
+
+`packaging/release-notes.md` 的 "Support matrix" 表与上表逐行对应（英文版，Termux 行同样标注
+experimental / not part of this release matrix）——改一边必须同步另一边，否则标题里的"一致"就是假话。
+
+两个 arm64 槽位都是**正式发布槽位**（产物进 Release、进 `SHA256SUMS.txt`、release job 的六槽位齐全性
+检查会拦下缺失），不要跟 Termux 那行混为一谈：Termux 是"源码自建的实验级旁路"，Linux arm64 是
+"原生 runner 编、原生跑"的一等产物。
+
+## 10. 已知边界 / 后续
+
+1. **GUI 的 `--version` 已解决**（M82）：`unlucky-launcher --version` 现在命中子命令分发，输出与
+   `ull --version` 同一条版本 + 系统摘要后退出，不再开窗。§7.2 里「无输出、8 秒后被 timeout 杀掉」那行
+   是**改之前**的实测记录，留作对照。版本自证的另外两条（产物名里的 ``、tag 交叉校验）不变。
+2. **签名/公证**：Windows 无 Authenticode、macOS 无 codesign/notarize（都要证书/开发者账号），
+   当前以 SHA256SUMS + Release 说明作为完整性参考。
+3. **macOS `.app` bundle / `.dmg`**：与单文件承诺冲突，暂不做；若用户要 Dock 图标再单开 mission。
+4. **Linux musl 静态版**：可彻底摆脱 glibc 地板，但 Slint 在 musl 上需额外验证，未纳入本矩阵。
+5. **`ull` 已随包**（M82 起）：每个槽位与 GUI 并列发一份裸 `ull`，进同一份 `SHA256SUMS.txt`，矩阵
+   完整性检查按「GUI 与 CLI 各自都要有」分开查（`release.yml`）。等 CI 首跑确认这条在真流水线上有效。
+6. **本机 GNU 链接器的已知无害告警**：`cargo build --release`（GNU 工具链）会打一行
+   `warning: linker stderr: corrupt .drectve at end of def file`，来自 MinGW `ld` 对 `.drectve` 段的
+   老式抱怨，不影响产物（体积/导入表/冒烟均已实测正常）；CI 的 MSVC 槽位不会出现这条。
+7. **两个 arm64 槽位本机跑不了**：本机是 x64 Windows，既没有 ARM 机器也没有 MSVC 的 ARM64 链接库
+   组合，`windows-arm64` / `linux-arm64` 的**真实产物只能由 CI 出**：前者靠 `dumpbin -dependents`
+   的静态 CRT 门禁 + 架构校验，后者在 `ubuntu-22.04-arm` 上真跑 `ull --version` 冒烟。
+   本机能做且已做的是脚本层取证（见 §7.5）：宿主判定注入（`win32/ARM64`、`linux/aarch64` 等全槽位）、
+   可执行文件头架构识别（真 x64 exe + 合成 PE/ELF/Mach-O 头）、以及把真 exe 的 PE 机器码改成 ARM64
+   当 stub 走完命名/校验/归档全流程 —— 不假装能在 x64 上执行 arm64 二进制。
+8. **M82 的体积/首帧没重量**：改的时候本机三个 worker 同时在编（全量 release profile 要 400+ crate），
+   这两个数留给空闲窗口补。结构性判断（**不是实测**）：分发发生在 `MainWindow::new()` 与后端探测之前，
+   GUI 路径只多一次 argv 解析，所以首帧成本没有增加的理由；CLI 路径的耗时则天然与首帧无关。
+
+## 11. CI 运行时冒烟（Linux 真渲染一帧）
+
+**细节与依据在 [`packaging/ci-runtime-smoke.md`](ci-runtime-smoke.md)**（本节再增长也往那里写，两个文件都必须 ≤400 行）。
+
+`ci.yml` 的 `runtime-smoke` job 在 `ubuntu-latest` 上补第一份**真实图形环境**运行证据：装 `xvfb` + 软渲染
+依赖 + 字体，用 `xvfb-run` 起 GUI 进程，走既有进程内截图通道渲出一帧 PNG，再对**像素本身**断言
+（退出码 0 / PNG 尺寸 / 非空白三项，artifact `runtime-smoke-screenshot`）。
+
+要点三条：
+
+- 只看退出码不够：PNG 是进程自己编码写出的，「合法 PNG + 退出码 0」不等于画面有内容，像素断言是纵深防御；
+  而「完全没有字体」与「非软渲染」这两种失效都是**硬失败**（panic / 报错，不产生 PNG；review 实测），运行步就红。
+- 闸门下限 ≈「至少画出一条标题栏」（review 实测切片仍 pass）：证明「场景被真实渲染过」，**不证明界面元素齐全，
+  更不证明视觉正确**——视觉靠人眼看 artifact。
+- 只覆盖 Linux x64；macOS 是 dispatch-only 探针（无实测证据），Windows 已有本机人眼验收。
+
+**本地复跑**：`bash packaging/linux-smoke-docker.sh . D:/tmp/ull-smoke`（输出目录别写 `/tmp`，Git Bash 下会静默落进 Docker VM；脚本内部用 `cygpath -m` 归一并回显真实路径）。**M118 提醒**：该脚本仍按 Slint 版 bin `unlucky-launcher` 编译与启动（`linux-smoke-docker.sh:81/83/88`），而 `crates/app` 已被 workspace `exclude`，**这条命令现在会失败**。
+在它把 bin 换成 `unlucky-launcher-iced` 之前，本地要复刻请直接照 `ci.yml` 的 runtime-smoke 三步手跑：`cargo build --bin unlucky-launcher-iced --locked` → `xvfb-run … --software-renderer --screenshot  --data-dir ` → `python3 packaging/check_screenshot.py  --json`。
+
+## 12. 文件清单
+
+| 文件 | 作用 | 行数上限 |
+|------|------|---------|
+| `packaging/README.md` | 本文：矩阵/依赖/版本/合规契约 | ≤400 |
+| `packaging/make_artifacts.py` | 打包与校验（本地 + CI 共用） | ≤400 |
+| `packaging/release-notes.md` | GitHub Release 说明模板（`{{VERSION}}` / `{{SUMS}}` 占位） | ≤400 |
+| `packaging/check_screenshot.py` | 截图非空白判定（CI 门禁 + 本地手动跑，零第三方依赖） | ≤400 |
+| `packaging/ci-runtime-smoke.md` | §11 的细节：断言口径/阈值依据/失效模式/复跑 | ≤400 |
+| `packaging/linux-smoke-docker.sh` | 本地复跑 `runtime-smoke`（Docker + xvfb） | ≤400 |
+| `.github/workflows/release.yml` | tag 触发 → 矩阵构建 → Release | ≤400 |
diff --git a/packaging/check_screenshot.py b/packaging/check_screenshot.py
new file mode 100644
index 0000000..4f02b7f
--- /dev/null
+++ b/packaging/check_screenshot.py
@@ -0,0 +1,317 @@
+#!/usr/bin/env python3
+"""截图「不是一帧空白」判定：CI 运行时冒烟的门禁脚本（零第三方依赖）。
+
+为什么需要它：`--screenshot` 的 PNG 是进程自己编码写出的，只要流程走到 `take_snapshot` 就会得到
+「合法 PNG + 退出码 0」；像素断言是**纵深防御**，守的是「进程活着、写出合法 PNG，但场景几乎没画」这一档。
+本机可复现的两种失效都是硬失败（运行步就红，不必等像素断言）：①完全没有字体 → fontique panic
+（退出码 101，不产生 PNG）；②不是软渲染（默认 femtovg）→ `take_snapshot is not supported by this
+FemtoVG backend`（退出码 1）。其余「渲染器出图但内容没上去」的情形本机暂无样本，属防御性设计。
+
+三个判据（阈值依据见 `--selftest` 与 packaging/ci-runtime-smoke.md）：
+
+- `unique_colors`：唯一色数。全白 / 全黑图 = 1；真实 UI 数百到上千。
+- `luma_stddev`：亮度标准差。纯色图 = 0；真实 UI 有面板/文字/渐变的明暗层次。
+- `edge_ratio`：**强边缘像素占比**——水平相邻像素对里亮度差 ≥8 的比例。纯色图 = 0；真实 UI 的文字与
+  边框占千分之几到百分之几。用它而不是「平均亮度差」：空数据目录的主界面 57% 是同一片底色，
+  平均差会被大片平面稀释（实测只有 0.4），而强边缘占比只数真正的边界，跨主题/跨字体都稳定。
+
+只用 Python 标准库：`zlib` 解压 PNG 的 deflate 流，自己反过滤（filter 0~4）。
+不引 Pillow 是因为 CI 不该为了「看一张图」多装一套图像栈（也符合项目的依赖白名单纪律）。
+
+用法::
+
+    python packaging/check_screenshot.py shot.png            # 判定，退出码 0/1
+    python packaging/check_screenshot.py shot.png --json     # 机器可读（CI 日志用）
+    python packaging/check_screenshot.py --selftest          # 打印阈值依据的两组数值
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import struct
+import sys
+import tempfile
+import zlib
+from collections import Counter
+from pathlib import Path
+
+PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
+
+# 判定阈值。两侧数值实测（M62 本机 Docker + xvfb + Windows 历史截图）：
+# - 真实帧：唯一色 342~2352、亮度σ 19.45~27.46、强边缘占比 0.0076~0.0433（最弱是 Linux 空数据主界面）；
+# - 人为纯色帧：1 / 0.0 / 0.0。
+# 阈值取在两者之间、贴近真实下限的 1/5~1/8：换主题/换字体/换窗口尺寸都不会误报，空白帧一定红。
+DEFAULT_MIN_UNIQUE = 64
+DEFAULT_MIN_STDDEV = 3.0
+DEFAULT_MIN_EDGE_RATIO = 0.001
+
+# 「强边缘」的亮度差门槛：≥8/255 肉眼即视为一条边界；抗锯齿造成的 1~2 级抖动不算。
+EDGE_LUMA_DELTA = 8
+
+# PNG 颜色类型 → 每像素通道数（调色板 3 走索引，需要 PLTE，本脚本不解）
+CHANNELS_BY_COLOR_TYPE = {0: 1, 2: 3, 4: 2, 6: 4}
+
+
+class PngError(Exception):
+    """PNG 结构不受支持或损坏。"""
+
+
+def _iter_chunks(data: bytes):
+    """按 PNG 规范切块：长度(4) + 类型(4) + 数据 + CRC(4)。"""
+    offset = len(PNG_SIGNATURE)
+    while offset + 12 <= len(data):
+        (length,) = struct.unpack(">I", data[offset : offset + 4])
+        yield data[offset + 4 : offset + 8], data[offset + 8 : offset + 8 + length]
+        offset += 12 + length
+
+
+def _unfilter(kind: int, line: bytearray, prev: bytearray, bpp: int) -> None:
+    """就地把一条扫描线反过滤（PNG 规范 §9.2 的五个过滤类型）。"""
+    if kind == 0:
+        return
+    if kind == 1:  # Sub：加上左边
+        for index in range(bpp, len(line)):
+            line[index] = (line[index] + line[index - bpp]) & 0xFF
+    elif kind == 2:  # Up：加上正上方
+        for index in range(len(line)):
+            line[index] = (line[index] + prev[index]) & 0xFF
+    elif kind == 3:  # Average：加上 (左 + 上) // 2
+        for index in range(len(line)):
+            left = line[index - bpp] if index >= bpp else 0
+            line[index] = (line[index] + ((left + prev[index]) >> 1)) & 0xFF
+    elif kind == 4:  # Paeth：加上 Paeth 预测子
+        for index in range(len(line)):
+            left = line[index - bpp] if index >= bpp else 0
+            up = prev[index]
+            upper_left = prev[index - bpp] if index >= bpp else 0
+            estimate = left + up - upper_left
+            dist_left = abs(estimate - left)
+            dist_up = abs(estimate - up)
+            dist_corner = abs(estimate - upper_left)
+            if dist_left <= dist_up and dist_left <= dist_corner:
+                predictor = left
+            elif dist_up <= dist_corner:
+                predictor = up
+            else:
+                predictor = upper_left
+            line[index] = (line[index] + predictor) & 0xFF
+    else:
+        raise PngError(f"未知的行过滤类型 {kind}")
+
+
+def decode_png(path: Path) -> tuple[int, int, list[bytearray], int]:
+    """读 8bit 非隔行 PNG，返回 (宽, 高, 每行原始字节, 通道数)。"""
+    data = path.read_bytes()
+    if not data.startswith(PNG_SIGNATURE):
+        raise PngError(f"{path} 不是 PNG（签名不符，可能是 0 字节文件或半截写入）")
+
+    width = height = depth = color_type = interlace = None
+    compressed = bytearray()
+    for kind, body in _iter_chunks(data):
+        if kind == b"IHDR":
+            width, height, depth, color_type, _, _, interlace = struct.unpack(">IIBBBBB", body)
+        elif kind == b"IDAT":
+            compressed.extend(body)
+        elif kind == b"IEND":
+            break
+
+    if width is None or height is None:
+        raise PngError("缺 IHDR 块")
+    if interlace:
+        raise PngError("不支持隔行（Adam7）PNG")
+    if depth != 8:
+        raise PngError(f"只支持 8bit PNG，实际 {depth}bit")
+    channels = CHANNELS_BY_COLOR_TYPE.get(color_type)
+    if channels is None:
+        raise PngError(f"不支持的颜色类型 {color_type}（调色板 PNG 请先转成 RGB/RGBA）")
+
+    raw = zlib.decompress(bytes(compressed))
+    stride = width * channels
+    if len(raw) < (stride + 1) * height:
+        raise PngError(f"像素数据不足：期望 {(stride + 1) * height} 字节，实际 {len(raw)}")
+
+    rows: list[bytearray] = []
+    previous = bytearray(stride)
+    offset = 0
+    for _ in range(height):
+        kind = raw[offset]
+        offset += 1
+        line = bytearray(raw[offset : offset + stride])
+        offset += stride
+        _unfilter(kind, line, previous, channels)
+        rows.append(line)
+        previous = line
+    return width, height, rows, channels
+
+
+def measure(width: int, height: int, rows: list[bytearray], channels: int) -> dict:
+    """统计「这帧图里有没有信息」的三项指标。"""
+    colors: Counter[int] = Counter()
+    luma_sum = 0
+    luma_square_sum = 0
+    strong_edges = 0
+    pair_count = 0
+
+    for row in rows:
+        previous_luma = None
+        for x in range(width):
+            base = x * channels
+            if channels >= 3:
+                red, green, blue = row[base], row[base + 1], row[base + 2]
+            else:
+                red = green = blue = row[base]
+            colors[(red << 16) | (green << 8) | blue] += 1
+            # 整数亮度（ITU-R BT.601 系数），避免浮点误差影响阈值比较
+            luma = (red * 299 + green * 587 + blue * 114) // 1000
+            luma_sum += luma
+            luma_square_sum += luma * luma
+            if previous_luma is not None:
+                pair_count += 1
+                if abs(luma - previous_luma) >= EDGE_LUMA_DELTA:
+                    strong_edges += 1
+            previous_luma = luma
+
+    total = width * height
+    mean = luma_sum / total if total else 0.0
+    variance = max(luma_square_sum / total - mean * mean, 0.0) if total else 0.0
+    top_color, top_count = colors.most_common(1)[0] if colors else (0, 0)
+    return {
+        "width": width,
+        "height": height,
+        "pixels": total,
+        "unique_colors": len(colors),
+        "top_color": f"#{top_color:06x}",
+        "top_color_share": round(top_count / total, 4) if total else 0.0,
+        "luma_mean": round(mean, 2),
+        "luma_stddev": round(math.sqrt(variance), 2),
+        "edge_ratio": round(strong_edges / pair_count, 5) if pair_count else 0.0,
+    }
+
+
+def verdict(
+    stats: dict, min_unique: int, min_stddev: float, min_edge_ratio: float
+) -> list[str]:
+    """把指标折成「失败原因清单」；空清单 = 通过。"""
+    problems = []
+    if stats["pixels"] <= 0:
+        problems.append("图像尺寸为 0（宽或高是 0）")
+        return problems
+    if stats["unique_colors"] < min_unique:
+        problems.append(
+            f"唯一色数 {stats['unique_colors']} < 阈值 {min_unique}（像纯色/空白帧）"
+        )
+    if stats["luma_stddev"] < min_stddev:
+        problems.append(
+            f"亮度标准差 {stats['luma_stddev']} < 阈值 {min_stddev}（整帧明暗无层次）"
+        )
+    if stats["edge_ratio"] < min_edge_ratio:
+        problems.append(
+            f"强边缘占比 {stats['edge_ratio']} < 阈值 {min_edge_ratio}（没有边界/文字的迹象）"
+        )
+    return problems
+
+
+def encode_png(width: int, height: int, rgb_row) -> bytes:
+    """最小 PNG 编码器（8bit RGB、filter 0、zlib 压缩）——只给 `--selftest` 造样图。"""
+    raw = bytearray()
+    for y in range(height):
+        raw.append(0)
+        raw.extend(rgb_row(y))
+    out = bytearray(PNG_SIGNATURE)
+    for kind, body in (
+        (b"IHDR", struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0)),
+        (b"IDAT", zlib.compress(bytes(raw), 6)),
+        (b"IEND", b""),
+    ):
+        out.extend(struct.pack(">I", len(body)))
+        out.extend(kind)
+        out.extend(body)
+        out.extend(struct.pack(">I", zlib.crc32(kind + body) & 0xFFFFFFFF))
+    return bytes(out)
+
+
+def selftest() -> int:
+    """造两张对照样图跑一遍，打印阈值依据的两组数值。
+
+    - 全白 / 全黑：模拟「窗口起来了但一个像素都没画」的空白帧；
+    - 一像素黑边框 + 中部一条横线：最弱的「有内容」下限（远弱于真实 UI）。
+    """
+    width, height = 1180, 760
+    cases = {
+        "flat-white": lambda y: b"\xff" * (width * 3),
+        "flat-black": lambda y: b"\x00" * (width * 3),
+        "border-line": lambda y: b"".join(
+            b"\x00\x00\x00"
+            if (y in (0, height - 1) or x in (0, width - 1) or y == height // 2)
+            else b"\xff\xff\xff"
+            for x in range(width)
+        ),
+    }
+    with tempfile.TemporaryDirectory() as tmp:
+        for name, describe in cases.items():
+            path = Path(tmp) / f"{name}.png"
+            path.write_bytes(encode_png(width, height, describe))
+            stats = measure(*decode_png(path))
+            failed = verdict(
+                stats, DEFAULT_MIN_UNIQUE, DEFAULT_MIN_STDDEV, DEFAULT_MIN_EDGE_RATIO
+            )
+            print(
+                json.dumps(
+                    {
+                        "case": name,
+                        "unique_colors": stats["unique_colors"],
+                        "luma_stddev": stats["luma_stddev"],
+                        "edge_ratio": stats["edge_ratio"],
+                        "verdict": "fail" if failed else "pass",
+                    },
+                    ensure_ascii=False,
+                )
+            )
+    return 0
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description="截图非空白判定（CI 运行时冒烟门禁）")
+    parser.add_argument("png", nargs="?", type=Path, help="待判定的 PNG 路径")
+    parser.add_argument("--json", action="store_true", help="以 JSON 输出统计结果")
+    parser.add_argument("--min-unique", type=int, default=DEFAULT_MIN_UNIQUE, help="唯一色数下限")
+    parser.add_argument("--min-stddev", type=float, default=DEFAULT_MIN_STDDEV, help="亮度标准差下限")
+    parser.add_argument(
+        "--min-edge-ratio", type=float, default=DEFAULT_MIN_EDGE_RATIO, help="强边缘占比下限"
+    )
+    parser.add_argument("--selftest", action="store_true", help="打印阈值依据的对照数值后退出")
+    args = parser.parse_args(argv)
+
+    if args.selftest:
+        return selftest()
+    if args.png is None:
+        parser.error("需要给出 PNG 路径（或 --selftest）")
+
+    try:
+        stats = measure(*decode_png(args.png))
+    except (PngError, OSError, zlib.error) as error:
+        print(f"[fail] 读不出截图 {args.png}: {error}", file=sys.stderr)
+        return 1
+
+    problems = verdict(stats, args.min_unique, args.min_stddev, args.min_edge_ratio)
+    if args.json:
+        print(json.dumps({**stats, "problems": problems}, ensure_ascii=False))
+    else:
+        print(
+            f"{args.png}: {stats['width']}x{stats['height']} "
+            f"唯一色 {stats['unique_colors']} 亮度σ {stats['luma_stddev']} "
+            f"强边缘 {stats['edge_ratio']} 主色 {stats['top_color']}"
+            f"({stats['top_color_share'] * 100:.1f}%)"
+        )
+    if problems:
+        for problem in problems:
+            print(f"[fail] {problem}", file=sys.stderr)
+        return 1
+    print("[ok] 截图非空白")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))
diff --git a/packaging/ci-runtime-smoke.md b/packaging/ci-runtime-smoke.md
new file mode 100644
index 0000000..c0de61b
--- /dev/null
+++ b/packaging/ci-runtime-smoke.md
@@ -0,0 +1,78 @@
+# CI 运行时冒烟（Linux 真渲染一帧）
+
+`packaging/README.md` §11 是本节的索引；细节在这里。为什么拆：本节要写阈值依据、失效模式与复跑口径，
+塞回 README 会撞 400 行硬门禁——**两文件都必须 ≤400 行**，任一边再增长就再拆一节。
+
+「编得过」≠「跑得起来」。`ci.yml` 的 `runtime-smoke` job 在 `ubuntu-latest` 上补第一份**真实图形环境**
+运行证据：装 `xvfb`（虚拟 X 服务器）+ 软渲染依赖 + 字体，用 `xvfb-run` 把 GUI 进程拉起来，走既有的
+进程内截图通道（`--software-renderer --screenshot  --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/linux-smoke-docker.sh b/packaging/linux-smoke-docker.sh
new file mode 100644
index 0000000..9d08aff
--- /dev/null
+++ b/packaging/linux-smoke-docker.sh
@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# 本地复跑 `.github/workflows/ci.yml` 的 `runtime-smoke` job：Linux + Xvfb + 软渲染截图。
+#
+# 为什么要有这条脚本：CI 的 runtime-smoke 在 GitHub 的 ubuntu-latest 上跑，
+# 但「改动这个 job 的人」需要在没有 Linux 桌面的开发机上先自证一遍——否则改的就是没人验过的 YAML。
+# 本脚本在 Docker 里复刻 job 的步骤（同样的 apt 依赖、同样的构建、同样的 xvfb-run 命令），
+# 并把截图与判定结果留在宿主目录，供人眼与 `check_screenshot.py` 复核。
+#
+# 用法：
+#   bash packaging/linux-smoke-docker.sh [仓库根目录] [输出目录]
+#   ULL_SMOKE_SKIP_BUILD=1 bash packaging/linux-smoke-docker.sh   # 复用缓存的二进制
+#
+# 说明（诚实边界）：
+# - 基础镜像 `rust:1-bookworm` 是 **Debian 12（glibc 2.36）**，官方 runner 是 **Ubuntu 24.04（glibc 2.39）**。
+#   两者图形栈（X11/xvfb/Mesa 软渲染）来源不同，因此本脚本证明的是「Linux 上这条通道能真跑出图」，
+#   不能代替官方 runner 的首跑验证。
+# - 国内网络慢时可换 TUNA 镜像：脚本默认就用 TUNA 的 Debian 源（`ULL_APT_MIRROR` 可覆盖）。
+
+set -euo pipefail
+
+repo_root=$(cd "${1:-.}" && pwd)
+out_dir=${2:-ull-smoke}
+image=${ULL_SMOKE_IMAGE:-ull-linux-smoke:bookworm}
+cargo_volume=${ULL_CARGO_VOLUME:-ull-cargo-reg}
+target_volume=${ULL_CARGO_TARGET_VOLUME:-ull-linux-target}
+apt_mirror=${ULL_APT_MIRROR:-https://mirrors.tuna.tsinghua.edu.cn}
+rustup_mirror=${ULL_RUSTUP_MIRROR:-https://mirrors.tuna.tsinghua.edu.cn/rustup}
+
+mkdir -p "$out_dir"
+out_dir=$(cd "$out_dir" && pwd)
+# Git Bash 里 /tmp、/d/x 都是 MSYS 虚拟路径：直接喂给 `docker -v` 会被当成 Linux VM 内的路径，
+# 结果「脚本说成功、宿主机什么都没有」。有 cygpath 就统一转成 Windows 混合路径（D:/x）并回显真实位置。
+if command -v cygpath >/dev/null 2>&1; then
+  repo_root=$(cygpath -m "$repo_root")
+  out_dir=$(cygpath -m "$out_dir")
+fi
+echo "== 仓库: $repo_root"
+echo "== 输出: $out_dir（截图 $out_dir/runtime-smoke.png）"
+
+# 1) 构建镜像：rust 工具链 + xvfb + 图形栈编译依赖 + 字体（软渲染器要从系统字体库取字形）
+if ! docker image inspect "$image" >/dev/null 2>&1 || [ "${ULL_SMOKE_REBUILD_IMAGE:-0}" = "1" ]; then
+  context=$(mktemp -d)
+  trap 'rm -rf "$context"' EXIT
+  cat >"$context/Dockerfile" <_windows_x64.exe      (bare exe, no zip)
+    Windows arm64   unlucky-launcher__windows_arm64.exe    (bare exe, cross-built)
+    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
+
+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.
+
+Slot and build directory are overridable because a cross build's binaries live in
+`target//release` and the build host (x64) is not the artifact (arm64): CI
+passes both from its matrix, and the executable header is read back so a binary can
+never be shipped under a slot name it was not built for.
+
+Usage:
+    cargo build --release --locked
+    python3 packaging/make_artifacts.py [--version v0.2.0] [--out dist] [--no-smoke]
+    # cross build (arm64 exe from an x64 host):
+    python3 packaging/make_artifacts.py --slot windows-arm64 \\
+        --build-dir target/aarch64-pc-windows-msvc/release
+"""
+
+from __future__ import annotations
+
+import argparse
+import gzip
+import hashlib
+import json
+import platform
+import shutil
+import subprocess
+import sys
+import tarfile
+from pathlib import Path
+from typing import NoReturn
+
+# M118（D26）：GUI 的**构建产物**名是 iced 版的 `unlucky-launcher-iced`。旧值 `unlucky-launcher`
+# 是 `crates/app`（Slint 退役树）的 bin —— 那棵树已被根 Cargo.toml `exclude`，再也不产出它了。
+# **对外**文件名仍叫 `unlucky-launcher`：下载链接 / SHA256SUMS / README 都绑着这个名字，
+# 改名是「翻牌」那一步的事，不是打包这一步的事。所以刻意拆成两个常量：
+# 找文件用 LAUNCHER_BIN，落盘（tar 内文件名 / exe 资产名）用 LAUNCHER_ASSET。
+LAUNCHER_BIN = "unlucky-launcher-iced"
+LAUNCHER_ASSET = "unlucky-launcher"
+CLI_BIN = "ull"
+# 随包分发的合规文本（仓库根目录）；英文主版 README 是对外分发口径。
+COMPLIANCE_DOCS = ("LICENSE", "NOTICE", "README.md")
+SUMS_NAME = "SHA256SUMS.txt"
+DEFAULT_BUILD_DIR = "target/release"
+
+# 发布矩阵：槽位 -> (OS 家族, 架构, 产物形态)。键名即产物文件名里的槽位段，
+# 单一真相源是 packaging/README.md §1；未知槽位一律拒绝，不出"凑合能跑"的产物。
+SLOTS = {
+    "windows-x64": ("windows", "x64", "exe"),
+    "windows-arm64": ("windows", "arm64", "exe"),
+    "linux-x64": ("linux", "x64", "tar"),
+    "linux-arm64": ("linux", "arm64", "tar"),
+    "macos-arm64": ("macos", "arm64", "tar"),
+    "macos-x64": ("macos", "x64", "tar"),
+}
+# `sys.platform` / `platform.machine()` 的别名归一（aarch64 与 arm64 是同一架构的两种叫法）。
+OS_FAMILIES = (("win", "windows"), ("linux", "linux"), ("darwin", "macos"))
+MACHINE_ALIASES = {"amd64": "x64", "x86_64": "x64", "aarch64": "arm64", "arm64": "arm64"}
+# 可执行文件头里的机器码 -> 架构（PE / ELF / Mach-O）。
+IMAGE_ARCH = {
+    ("pe", 0x8664): "x64",
+    ("pe", 0xAA64): "arm64",
+    ("elf", 0x3E): "x64",
+    ("elf", 0xB7): "arm64",
+    ("macho", 0x01000007): "x64",
+    ("macho", 0x0100000C): "arm64",
+}
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+
+
+def fail(message: str) -> NoReturn:
+    print(f"error: {message}", file=sys.stderr)
+    raise SystemExit(1)
+
+
+def workspace_version() -> str:
+    """Read `[workspace.package] version` through cargo itself (single source of truth)."""
+    try:
+        raw = subprocess.run(
+            ["cargo", "metadata", "--no-deps", "--format-version", "1"],
+            cwd=REPO_ROOT,
+            check=True,
+            capture_output=True,
+            text=True,
+            # Windows 默认 GBK：cargo 的 package description 是中文，不显式指定会解码失败。
+            encoding="utf-8",
+            errors="replace",
+        ).stdout
+    except (OSError, subprocess.CalledProcessError) as exc:
+        fail(f"cargo metadata failed: {exc}")
+    packages = json.loads(raw)["packages"]
+    versions = {pkg["version"] for pkg in packages}
+    if len(versions) != 1:
+        fail(f"workspace members disagree on version: {sorted(versions)}")
+    return versions.pop()
+
+
+def host_slot(os_name: str | None = None, machine: str | None = None) -> str:
+    """Map the build host to a matrix slot.
+
+    Both arguments are injectable so the mapping can be exercised for a host we do not
+    own (no ARM machine here); they default to the real ones.
+    """
+    os_name = (sys.platform if os_name is None else os_name).lower()
+    raw_machine = platform.machine() if machine is None else machine
+    arch = MACHINE_ALIASES.get(raw_machine.lower())
+    family = next((fam for prefix, fam in OS_FAMILIES if os_name.startswith(prefix)), None)
+    for slot, (slot_os, slot_arch, _) in SLOTS.items():
+        if (slot_os, slot_arch) == (family, arch):
+            return slot
+    # 报错带**原始**取值而不是归一后的 None：`riscv64` 这类不认识的架构得在诊断里看得见。
+    fail(f"unsupported build host {os_name}/{raw_machine}; matrix is {' / '.join(SLOTS)}")
+
+
+def binary(name: str, build_dir: Path, family: str) -> Path:
+    path = build_dir / (f"{name}.exe" if family == "windows" else name)
+    if not path.is_file():
+        fail(f"missing {path}; run `cargo build --release --locked` first")
+    return path
+
+
+def image_arch(path: Path) -> str | None:
+    """Architecture stamped into the executable header, or `None` if unreadable."""
+    with path.open("rb") as handle:
+        head = handle.read(0x40)
+        if head[:4] == b"\x7fELF":
+            order = "little" if head[5] == 1 else "big"
+            return IMAGE_ARCH.get(("elf", int.from_bytes(head[18:20], order)))
+        if head[:2] == b"MZ":
+            handle.seek(int.from_bytes(head[0x3C:0x40], "little"))
+            pe = handle.read(6)
+            if pe[:4] == b"PE\0\0":
+                return IMAGE_ARCH.get(("pe", int.from_bytes(pe[4:6], "little")))
+            return None
+        if head[:4] == b"\xcf\xfa\xed\xfe":  # thin 64-bit little-endian Mach-O
+            return IMAGE_ARCH.get(("macho", int.from_bytes(head[4:8], "little")))
+    return None
+
+
+def verify_arch(path: Path, slot: str) -> None:
+    """Prove the binary really is built for the slot it is about to be named after."""
+    want = SLOTS[slot][1]
+    got = image_arch(path)
+    if got is None:
+        fail(f"cannot read the machine type of {path}; refusing to ship an unverified binary")
+    if got != want:
+        fail(f"{path} is a {got} binary but slot {slot} says {want}")
+    print(f"arch:     {path.name} -> {got} (ok for {slot})")
+
+
+def smoke_version(cli: Path, version: str) -> None:
+    """`ull --version` must report the workspace version (guards tag/version drift)."""
+    proc = subprocess.run(
+        [str(cli), "--version"],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+    out = (proc.stdout or "") + (proc.stderr or "")
+    if proc.returncode != 0:
+        fail(f"`{cli.name} --version` exited {proc.returncode}: {out.strip()}")
+    if version not in out:
+        fail(f"`{cli.name} --version` does not report {version}: {out.strip()}")
+    print(f"smoke:    {cli.name} --version -> {version} (ok)")
+
+
+def sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def write_sums(out_dir: Path, assets: list[Path]) -> Path:
+    sums = out_dir / SUMS_NAME
+    lines = [f"{sha256(path)}  {path.name}" for path in sorted(assets)]
+    sums.write_text("\n".join(lines) + "\n", encoding="utf-8", newline="\n")
+    return sums
+
+
+def asset_stem(name: str, version: str, slot: str) -> str:
+    """`___` — 产物命名的唯一真相源。
+
+    用户令（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")
+    args = parser.parse_args()
+
+    version = workspace_version()
+    if args.version:
+        expected = args.version[1:] if args.version.startswith("v") else args.version
+        if expected != version:
+            fail(f"tag/version mismatch: requested {expected}, Cargo.toml says {version}")
+    native = host_slot()
+    slot = args.slot or native
+    family, _, kind = SLOTS[slot]
+    build_dir = Path(args.build_dir)
+    if not build_dir.is_absolute():
+        build_dir = REPO_ROOT / build_dir
+    launcher = binary(LAUNCHER_BIN, build_dir, family)
+    verify_arch(launcher, slot)
+    # 跨槽位产物（宿主 x64 / 目标 arm64）在本机根本执行不了，冒烟只能等 CI 真机；
+    # 拿"跳过了"当通过是假证据，所以把跳过原因原样打出来。
+    if args.no_smoke or slot != native:
+        reason = "--no-smoke" if args.no_smoke else f"host is {native}, artifact is {slot}"
+        print(f"smoke:    skipped ({reason})")
+    else:
+        smoke_version(binary(CLI_BIN, build_dir, family), version)
+
+    out_dir = Path(args.out)
+    if not out_dir.is_absolute():
+        out_dir = REPO_ROOT / out_dir
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    if kind == "exe":
+        asset = out_dir / f"{asset_stem(LAUNCHER_ASSET, version, slot)}.exe"
+        shutil.copy2(launcher, asset)
+    else:
+        asset = stage_archive(out_dir, slot, version, launcher)
+    # CLI 与 GUI 同一矩阵槽位、各自独立资产：架构同样回读文件头校验，不给 arm64 槽位混进 x64 的 ull。
+    cli = binary(CLI_BIN, build_dir, family)
+    verify_arch(cli, slot)
+    cli_asset = stage_cli(out_dir, version, slot, cli)
+
+    sums = write_sums(out_dir, [asset, cli_asset])
+    for item in (asset, cli_asset):
+        size_mb = item.stat().st_size / (1024 * 1024)
+        print(f"artifact: {item.name}  {size_mb:.2f} MiB  sha256={sha256(item)}")
+    print(f"sums:     {sums.name}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/packaging/release-notes.md b/packaging/release-notes.md
new file mode 100644
index 0000000..7d6c63b
--- /dev/null
+++ b/packaging/release-notes.md
@@ -0,0 +1,124 @@
+# Unlucky Launcher {{VERSION}}
+
+Rust-native **single-file** Minecraft launcher: iced 0.14 + Material 3 Expressive UI, built-in AI agent
+(chat / config edits / crash diagnosis) and an MCP server other agent tools can attach to.
+No WebView, no bundled runtime, no JRE download needed to start the launcher itself.
+
+## Downloads
+
+| Platform | Asset | Notes |
+| --- | --- | --- |
+| Windows 10/11 x64 | `unlucky-launcher-{{VERSION}}-windows-x64.exe` | single exe, double-click to run |
+| Windows 11 ARM64 | `unlucky-launcher-{{VERSION}}-windows-arm64.exe` | single exe, runs natively on ARM64 Windows |
+| Linux x64 (X11/Wayland) | `unlucky-launcher-{{VERSION}}-linux-x64.tar.gz` | single binary inside, no installer |
+| Linux arm64 (X11/Wayland) | `unlucky-launcher-{{VERSION}}-linux-arm64.tar.gz` | single binary inside; needs glibc 2.35+ |
+| macOS 12+ Apple Silicon | `unlucky-launcher-{{VERSION}}-macos-arm64.tar.gz` | single binary inside, no installer |
+| macOS 12+ Intel | `unlucky-launcher-{{VERSION}}-macos-x64.tar.gz` | single binary inside, no installer |
+
+`LICENSE`, `NOTICE` and `README.md` ship in every archive; on Windows they are attached to
+this release next to the `.exe` (a lone exe cannot carry them), so the license terms travel
+with the download on every platform.
+
+Every slot also ships the command line as its own small asset — `ull-{{VERSION}}-`
+(`.exe` on Windows):
+
+```bash
+chmod +x ull-{{VERSION}}-linux-x64             # Release 资产不带可执行位，先补上
+./ull-{{VERSION}}-linux-x64 instances list     # servers / CI / Termux: no graphics stack needed
+unlucky-launcher instances list                # desktops: the GUI binary answers the same commands
+```
+
+`ull` runs `instances`, `install`, `launch`, `accounts`, `sessions`, `logs`, `diag`, `config`,
+`java` and `agent`, and links no graphics library at all. The GUI binary accepts the same set
+before it ever opens a window, so on a machine with a desktop you do not need `ull`.
+
+## Support matrix
+
+| Platform | Level | Runtime requirements |
+| --- | --- | --- |
+| Windows 10/11 x64 | first class | nothing beyond the OS (UCRT is part of Win10+) |
+| Windows 11 ARM64 | first class (launcher artifact) | nothing extra; launcher runs natively, the game itself runs through the OS x64 emulation layer with an x64 JDK |
+| macOS 12+ (arm64 / x64) | first class | nothing; unsigned build, see Gatekeeper note |
+| Linux x64, X11 | first class | `libxkbcommon`, `fontconfig`, `libGL` (or software renderer), `libxcb` |
+| Linux x64, Wayland | supported | `wayland-client`, `libxkbcommon`, plus the X11 set for XWayland apps |
+| Linux arm64, X11 | first class | glibc 2.35+ (built on `ubuntu-22.04-arm`, same floor as x64), `libxkbcommon`, `fontconfig`, `libGL`, `libxcb` |
+| Linux arm64, Wayland | supported | the above plus `wayland-client` |
+| Windows 8.1/8/7 | unsupported | baseline was raised to Win10 (decision D21) |
+| Android — Termux + X11 | experimental, not promised | CLI only (the `ull` asset, or build from source), GUI unverified; not part of this release matrix |
+
+Both arm64 rows are **formally released slots** (the assets ship in this release and in
+`SHA256SUMS.txt`), not the experimental Termux path: Linux arm64 is built and smoke-tested on a
+native ARM64 runner, Windows ARM64 is cross-built with the same static-CRT gate as x64.
+
+## Install
+
+**Windows** — put the `.exe` anywhere and run it (pick `-windows-arm64.exe` on ARM64 Windows,
+`-windows-x64.exe` everywhere else). Portable data lives next to the exe when a
+`portable.marker` file is present, otherwise under `%APPDATA%`.
+
+**Linux**
+
+```bash
+tar -xzf unlucky-launcher-{{VERSION}}-linux-x64.tar.gz   # use linux-arm64 on aarch64
+cd unlucky-launcher-{{VERSION}}-linux-x64                # ditto
+chmod +x unlucky-launcher && ./unlucky-launcher
+```
+
+**macOS**
+
+```bash
+tar -xzf unlucky-launcher-{{VERSION}}-macos-arm64.tar.gz
+cd unlucky-launcher-{{VERSION}}-macos-arm64
+xattr -d com.apple.quarantine unlucky-launcher   # unsigned build, Gatekeeper quarantine
+chmod +x unlucky-launcher && ./unlucky-launcher
+```
+
+## No GPU? Software renderer
+
+The UI renders through `wgpu` (GPU) and falls back to the `tiny-skia` CPU rasteriser when no usable
+adapter is present. Force the CPU path on any machine with:
+
+```bash
+unlucky-launcher --software-renderer          # the documented switch
+unlucky-launcher --renderer=cpu               # equivalent: pick the CPU renderer explicitly
+```
+
+## Verify the download
+
+```bash
+# Linux / macOS
+sha256sum -c SHA256SUMS.txt --ignore-missing
+# Windows (PowerShell)
+Get-FileHash .\unlucky-launcher-{{VERSION}}-windows-x64.exe -Algorithm SHA256
+```
+
+## Checksums
+
+```
+{{SUMS}}
+```
+
+## Known limitations of this build
+
+- Microsoft (MSA) account login depends on a Mojang app-id whitelist that is still pending;
+  until it is granted, use offline accounts or authlib-injector (the 403 is reported with a
+  readable diagnostic instead of a silent failure).
+- Binaries are not code-signed / notarized yet: Windows SmartScreen and macOS Gatekeeper warn
+  on first launch. Checksums above are the integrity reference for now.
+- macOS ships the bare binary (single-file promise), not a `.app` bundle: no Dock icon or
+  Finder double-click — launch it from a terminal.
+
+## License
+
+Apache-2.0. Third-party notices are in `NOTICE`. Unlucky Launcher is not affiliated with Mojang or
+Microsoft; it does not ship game files.
+
+## UI framework in this build
+
+Every asset in this release is built from the iced UI (`crates/app-iced`, iced 0.14, MIT) — no Slint
+code is linked into it. The earlier Slint UI (`crates/app`) stays in the repository as historical
+source only: excluded from the cargo workspace, not built, not part of any asset here and not part of
+the release matrix. It did ship in the previous `v0.1.0` release; that release's Slint Royalty-Free
+2.0 attribution remains where it was published, and no asset in this build carries that obligation.
+There is deliberately no "Made with Slint" badge on this page: the obligation follows a Slint-linked
+binary, and this release has none.
diff --git a/rust-toolchain.toml b/rust-toolchain.toml
new file mode 100644
index 0000000..ab71de3
--- /dev/null
+++ b/rust-toolchain.toml
@@ -0,0 +1,6 @@
+[toolchain]
+# 全仓统一 stable，不在仓库内钉死具体小版本（CI 与本地同样走 stable 解析）。
+# 各平台（Win10+ / macOS / Linux）共用本文件，不按平台另起工具链。
+channel = "stable"
+profile = "minimal"
+components = ["rustfmt", "clippy"]