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

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

crates/core/src/addon/import.rs

@@ -0,0 +1,271 @@
+//! 整合包**导入**（M111）：CurseForge `manifest.json` / Modrinth `.mrpack` / MultiMC·Prism 实例
+//! → 一个可启动的实例目录。
+//!
+//! 设计依据：`DevDocs/PlanDoc/08-mod-and-recommend.md` §2（D10）、
+//! `DevDocs/PlanDoc/research/18-modpack-formats*.md`（字段清单，A/B 级来源）、
+//! `DevDocs/SubAgentsTalk/addon-整合包导入导出对接要点.md`（施工口径）。
+//! 格式模型与安全闸是 M110 的 [`crate::addon::pack`]：本模块**只消费，不重写**。
+//!
+//! # 逐文件冲突决策（M160）：预检 → 用户点头 → 导入
+//!
+//! | 步骤 | 入口 | 写盘吗 |
+//! |------|------|--------|
+//! | 预检：算出"哪几个文件会盖掉用户的" | [`scan_pack`] | **不写**（只读盘算摘要） |
+//! | 用户点「全部保留 / 全部覆盖 / 逐项」 | [`ConflictDecisions`] | — |
+//! | 导入 | [`import_pack`] | 写（按决策处置冲突） |
+//!
+//! 三条硬口径（改它们之前先看 [`scan`] 与 [`decision`] 的模块文档）：
+//!
+//! 1. 进冲突清单的**只有**"目标里已存在同名普通文件且内容（SHA-1）不同"的路径；内容相同、
+//!    目标不存在、以及用户删过的文件都不打扰用户；
+//! 2. 决策按**路径**给，逐项优先于整批档，整批档缺省 = 保留；
+//! 3. 缺省**绝不覆盖**：没收到决策的冲突一律保留用户那一侧（[`ConflictChoice::default`]）。
+//!
+//! # 三条硬要求落在哪
+//!
+//! | 要求 | 落点 |
+//! |------|------|
+//! | overrides 哈希**三方合并**（不静默覆盖用户改动） | [`merge`] 的判据 + [`baseline`] 的 base 侧 |
+//! | 两阶段补全 + **失败分级**（仅"缺文件"可容忍） | [`pipeline`] 的顺序 + [`report::MissingFile`] 与 [`error::ImportError`] 的分工 |
+//! | 路径穿越**双检** | 开包时 M110 [`crate::addon::pack::PackArchive::open`]，落地时 [`stage`] 的 `normalize_file` + `starts_with` 复核 |
+//!
+//! # 取消（M195）：每条停下路线都回滚，且**取消不是失败**
+//!
+//! 用户点「取消」之后管线真的停手：每个阶段边界与长循环内都有检查点，取消后目标目录与导入前
+//! 一致（先写临时目录、最后 `rename` / journal 合并），**不登记实例**。结果类型单列一档
+//! [`ImportStatus::Cancelled`]（`error` 为空、CLI 退出码 `130`、UI 不弹红），与
+//! [`ImportStatus::Failed`] 是两条路。逐段检查点表（含"哪几段没有检查点、为什么"）在
+//! [`cancel`] 模块文档里。
+//!
+//! # 三种格式的语义（tower 定案，与 HMCL 相反的两条要记住）
+//!
+//! - **mrpack**：`overrides/` 与 `client-overrides/` 都解压，**后者胜**（Modrinth 官方客户端语义；
+//!   HMCL 恰好相反）；`server-overrides/` 客户端**不解压**；其余同名路径无官方优先级 ⇒ 按侧
+//!   优先级落地，不自创排序。**同一实例路径被本包多份声明命中时**（跨侧或同侧重复），
+//!   逐条算清楚：胜者按上面这条规则定，被遮蔽的那条不读字节、只留一条
+//!   `pack.import.note.override_shadowed` 注记说明「谁赢了 / 两份内容是否逐字节相同」
+//!   （见 [`plan::Shadowed`]）。一路径一行，不再出现"两条 Installed、前一条没落地"。
+//! - **CF**：溢出目录名取自清单 `overrides` 字段；`files[]` 只有 `projectID/fileID`，要 CF API
+//!   才能补出文件名/地址——仓库里还没有 CF 客户端（D10 §5），因此这部分条目的**当前正确行为**
+//!   是记成 `missing`（`Partial`），**绝不猜 `edge.forgecdn.net` 那类 URL**。
+//! - **MultiMC / Prism**：`mmc-pack.json` 的 `formatVersion` 必须恰为 `1`（M110 的读者会拒绝
+//!   其余值）；`.minecraft/` 直拷；非加载器 component（`org.lwjgl3` 等）**逐项**进
+//!   [`report::RejectedComponent`]，不静默丢；只有导入，没有导出。
+//!
+//! # `.disabled` 只按路径后缀
+//!
+//! `x.jar` / `x.jar.disabled` / `x.jar.old` / `x.jar.disabled.old` 四种变体都识别，后缀**原样
+//! 保留**；`.old` 只识别与保留（不清除、不改名、不当回滚语义）。`env.client=optional` **不是**
+//! 禁用——"可选"的语义是"安装时可取消勾选"，装回来默认仍然启用，两者不是一回事。
+//!
+//! # 用法
+//!
+//! ```ignore
+//! let engine = /* core::download::DownloadEngine */;
+//! let fetcher = DownloadEngineFetcher::new(&engine);
+//! let cancel = ImportCancel::new(); // 交给「取消」按钮：cancel.cancel()
+//! let request = ImportRequest::new(pack_path, instance_dir)
+//!     .with_fetcher(&fetcher)
+//!     .with_cancel(&cancel)
+//!     .with_registration(&launcher_layout, None);
+//! let report = download::blocking::block_on(import_pack(&request));
+//! match report.status { /* Success / Partial / Failed / Cancelled */ }
+//! ```
+//!
+//! # 刻意不做的事（分工边界）
+//!
+//! - **不删除**整合包升级后不再包含的文件：磁盘上的 `mods/` 里可能有用户自己装的模组，
+//!   删旧文件是"清理"而不是"导入"（要做得先有"这个文件是整合包装的"的完整账本 + 用户确认）；
+//! - **不装加载器**：只把清单翻译成 [`report::LoaderTarget`]（`kind` + 原版版本 + 加载器版本
+//!   + 版本 id），真正的元数据解析/库下载仍是 `addon::loader` + `game::install` 的既有路径；
+//! - **不碰 UI 类型**：core 零 UI 依赖（`core-no-ui` 门禁），报告只出现 `String` / `&'static str`；
+//! - **不绕过下载引擎**：所有网络只经 [`fetch::PackFetcher`]，生产实现只有
+//!   [`fetch::DownloadEngineFetcher`]（走 `core::download`）。
+//!
+//! # 没验的部分（真实世界的欠账，报告里同样登记）
+//!
+//! 真实 CF / MultiMC 导出物（夹具是手造的）、超大包（>2G）、Windows 之外的平台、断网中途、
+//! 磁盘满、真实 CurseForge `files[]` 补全（缺 CF 客户端，见 [`fetch`] 的说明）。
+//!
+//! 取消这一条另有三个欠账（M195 报告同样登记）：①超大整合包（几千文件 / 数 GB）在真实磁盘
+//! 上的**取消响应延迟**没测——最坏要等"当前这一条文件读完/下完 + 一次回滚"；②**单条下载在飞
+//! 不可中断**（[`fetch::PackFetcher`] 没有取消参数），只能等它返回；③macOS / Linux 未验。
+
+pub mod baseline;
+pub mod cancel;
+pub(crate) mod complete;
+pub mod decision;
+pub mod error;
+pub mod fetch;
+pub mod merge;
+pub mod phase;
+pub mod pipeline;
+pub mod plan;
+pub(crate) mod prepare;
+pub mod report;
+pub mod scan;
+pub mod stage;
+
+pub use baseline::{PackBaseline, BASELINE_FILE};
+pub use cancel::ImportCancel;
+pub use decision::ConflictDecisions;
+pub use error::{ImportError, ImportErrorKind};
+pub use fetch::{
+    CurseFileMeta, DownloadEngineFetcher, FetchError, FetchErrorKind, FetchFuture, FetchRequest,
+    FetchedFile, ModrinthFileMeta, PackFetcher,
+};
+pub use merge::{MergeAction, MergeDecision};
+pub use plan::{ImportPlan, PlanOverride, PlanRemote, Shadowed, SuffixVariant};
+pub use prepare::baseline_relative;
+pub use report::{
+    keys, ConflictChoice, ConflictFile, ConflictReason, FileAction, FileSource, ImportIssue,
+    ImportProgress, ImportProgressSink, ImportReport, ImportStage, ImportStatus, ImportedFile,
+    LoaderTarget, MissingFile, MissingReason, RegisteredInstance, RejectedComponent,
+};
+pub use scan::{scan_pack, scan_pack_online, ImportConflict, ImportScan};
+pub use stage::{RollbackOutcome, Staging};
+
+use std::path::Path;
+
+use crate::addon::pack::PackLimits;
+use crate::platform::layout::LauncherLayout;
+
+/// 整次导入的**缺省**冲突档（逐项决策见 [`ConflictDecisions`]）。
+///
+/// 保留这个名字是因为 CLI 已经按它调用（`pack import --overwrite`）；语义上它就是
+/// [`ConflictDecisions::default_choice`] 的构造器：
+///
+/// - [`ConflictPolicy::KeepUser`]（缺省）= 逐项决策的缺省档是"保留"；
+/// - [`ConflictPolicy::Overwrite`] = 逐项决策的缺省档是"覆盖"。
+///
+/// **逐项决策优先于它**，所以"整批覆盖 + 某几条保留"是可表达的。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum ConflictPolicy {
+    /// 保留用户那一侧（不覆盖、不补回被删的文件），冲突逐条进报告。
+    #[default]
+    KeepUser,
+    /// 用包内内容覆盖（用户明确要求"整合包说了算"）。
+    Overwrite,
+}
+
+impl ConflictPolicy {
+    /// 对应的逐项决策缺省档。
+    #[must_use]
+    const fn choice(self) -> ConflictChoice {
+        match self {
+            Self::KeepUser => ConflictChoice::KeepUser,
+            Self::Overwrite => ConflictChoice::Overwrite,
+        }
+    }
+}
+
+/// 一次导入请求。
+pub struct ImportRequest<'a> {
+    /// 包路径：zip（`.zip` / `.mrpack`）或 MultiMC 实例目录。
+    pub pack: &'a Path,
+    /// 目标实例的游戏目录（`mods/` 直接在其下）。
+    pub target: &'a Path,
+    /// 远端补全 + 下载；`None` = 离线导入（远端条目全部记成 `missing`）。
+    pub fetcher: Option<&'a dyn PackFetcher>,
+    /// 数据根布局；给了才登记实例（`profiles.json`）。
+    pub register: Option<&'a LauncherLayout>,
+    /// 实例展示名（缺省用包名）。
+    pub instance_name: Option<&'a str>,
+    /// 逐文件冲突决策（含整批缺省档，**缺省 = 全部保留**）。
+    pub decisions: ConflictDecisions,
+    /// 取消令牌；缺省是永不取消的独立令牌（没挂令牌的调用方不必写 `Option`）。
+    ///
+    /// 语义与检查点位置见 [`cancel`] 模块文档：取消后**不得**留下半包 / 覆盖已有实例，也不许
+    /// 登记实例；判据是报告里的 [`report::ImportStatus::Cancelled`]（**不是**失败）。
+    pub cancel: ImportCancel,
+    /// 包读取限额（条数 / 单条体积 / 解压总量）。
+    pub limits: PackLimits,
+    /// 进度回调。
+    pub progress: Option<ImportProgressSink>,
+}
+
+impl<'a> ImportRequest<'a> {
+    /// 最小请求（离线、不登记、保留用户文件、默认限额）。
+    #[must_use]
+    pub fn new(pack: &'a Path, target: &'a Path) -> Self {
+        Self {
+            pack,
+            target,
+            fetcher: None,
+            register: None,
+            instance_name: None,
+            decisions: ConflictDecisions::default(),
+            cancel: ImportCancel::default(),
+            limits: PackLimits::default(),
+            progress: None,
+        }
+    }
+
+    /// 挂上远端补全 / 下载。
+    #[must_use]
+    pub fn with_fetcher(mut self, fetcher: &'a dyn PackFetcher) -> Self {
+        self.fetcher = Some(fetcher);
+        self
+    }
+
+    /// 挂上实例登记（`name` 为 `None` 时用包名）。
+    #[must_use]
+    pub fn with_registration(mut self, layout: &'a LauncherLayout, name: Option<&'a str>) -> Self {
+        self.register = Some(layout);
+        self.instance_name = name;
+        self
+    }
+
+    /// 整批缺省档（逐项决策仍然优先）。
+    #[must_use]
+    pub fn with_conflict_policy(mut self, policy: ConflictPolicy) -> Self {
+        self.decisions = std::mem::take(&mut self.decisions).with_default(policy.choice());
+        self
+    }
+
+    /// 整表逐文件决策（「全部保留 / 全部覆盖 / 逐项」三条入口的产物）。
+    #[must_use]
+    pub fn with_decisions(mut self, decisions: ConflictDecisions) -> Self {
+        self.decisions = decisions;
+        self
+    }
+
+    /// 挂一条逐项决策（链式，便于测试与命令行逐条给）。
+    #[must_use]
+    pub fn with_decision(mut self, path: impl Into<String>, choice: ConflictChoice) -> Self {
+        self.decisions.set(path, choice);
+        self
+    }
+
+    /// 改读取限额。
+    #[must_use]
+    pub fn with_limits(mut self, limits: PackLimits) -> Self {
+        self.limits = limits;
+        self
+    }
+
+    /// 挂进度回调。
+    #[must_use]
+    pub fn with_progress(mut self, sink: ImportProgressSink) -> Self {
+        self.progress = Some(sink);
+        self
+    }
+
+    /// 挂取消令牌（与调用方手里的那份**共享同一个开关**）。
+    ///
+    /// 取消的结果是 [`ImportStatus`] 里的 `Cancelled`（不是失败）；停在哪一段、哪些段落没有
+    /// 检查点，见 [`cancel`] 模块文档的逐段表。
+    #[must_use]
+    pub fn with_cancel(mut self, token: &ImportCancel) -> Self {
+        self.cancel = token.clone();
+        self
+    }
+}
+
+/// 导入一个整合包。**永不返回 `Err`**：三态 + 取消 + 逐项原因都在 [`ImportReport`] 里。
+pub async fn import_pack(request: &ImportRequest<'_>) -> ImportReport {
+    pipeline::run(request).await
+}
+
+#[cfg(test)]
+mod cancel_tests;