feat(app-iced): M109 CONTENTDL —— 内容库页（整合包/Mod/资源包/光影）

用户令「下载页只负责下载整合包和Mod/光影」：新开一页做**内容发现与装入**，
检索走 Modrinth（优先，无需 key）/ CurseForge（`ULL_CF_API_KEY` 环境变量，日志只打
set/unset），装入走 core 的下载引擎真下到实例目录，进度/取消/失败复用下载页那块安装面板。

- **入口（B1）**：`Route::Content` 是新顶层路由，但 `Route::nav()` 复用 `NavSection::Download`
  ——导航轨仍五项，页头右上是「版本管理 | 内容库」一级切换（版本管理页也加了同一个切换，
  否则内容库只有 `ULL_START_ROUTE` 能到）
- **页内四条一级侧栏**（`pages/content/layout.rs` 四档几何：992/856/648 三个门槛都是
  「Σ栏宽 + 间距」算出来的）：整合包 / Mod / 资源包 / 光影；标签栏 200（`Resource packs`
  比 M107 的版本类型名长，140 会切字，已登记偏离）
- **筛选**：关键词（草稿 + 显式「搜索」按钮，不逐字打网络）、来源、游戏版本、加载器
  （Fabric/Forge/NeoForge/Quilt）、排序；**分页**（「加载更多」）而不是无限滚动——快照只有一个槽、
  翻页要看得见、状态要可截图复现
- **四态**：加载 / 空 / 失败 / 有数据 + 「没有更多了」；筛选条在任何状态下都在（加载中藏筛选条
  等于把入口收走）
- **一键装入**：`Content::blockers()` 是纯函数——版本不匹配、加载器不匹配、没有目标实例、
  整合包缺管线**四条原因逐条**给出，按钮点之前就禁用；判定与画法分开（model/tests 直接钉）
- **整合包今天不可装**：`ContentKind::Modpack.dir()` 是 `None`，UI 禁用 + 说明，host 侧再挡
  一次（绕过 UI 也只会回一条 Failed）。真流程是 M111 的导入管线
- **零 UI 网络**：`presenter/host/addon.rs` + `addon/{sources,http,install}.rs`；无 header 的请求走
  core 的 `download_bytes`（信号量限流 + 健康度 + 退避全现成），带 `X-API-KEY` 的只有 CF 一条，
  自带 429/5xx 退避（优先吃 `Retry-After`，封顶 30s）；密钥不进 DTO/日志/仓库
- 文案 41 条中英进 `crates/i18n`（新域接在装配链末尾 ⇒ `Key::ALL` 与金表只追加）
- 演示数据 `ContentHit → Hit::of` 与产品路径同源（格式化不会两套），`ULL_CONTENT_KIND` /
  `ULL_CONTENT_STATE` 供出图矩阵选类型与状态

取证：`DevDocs/artifacts/m109/`（10 张：四类内容 × 浅/深 + 搜索无结果 + 加载器不兼容禁用）

门禁：fmt ✓ / clippy `-D warnings`（三 crate）✓ / app-iced 450+6、presenter 170、i18n 24 全绿；
`cargo tree` 两条零 UI 门禁仍空；全部改动文件 ≤400 行。

crates/presenter/src/host/addon/http.rs

@@ -0,0 +1,123 @@
+//! HTTP 取文本（内容库唯一的网络出口）。
+//!
+//! ## 两条路径，为什么不是一条
+//!
+//! | 请求 | 走哪 | 拿到什么 |
+//! |---|---|---|
+//! | 无自定义 header（Modrinth 的全部请求） | [`DownloadEngine::download_bytes`] | **信号量限流 + 源健康度 + 指数退避 + 分类错误**，全是 core 现成的 |
+//! | 带 header（只有 CurseForge 的 `X-API-KEY`） | `engine.client()` 直发 | 引擎的请求体没有 header 字段，只能自己发；代价是这条路径自己带一个 429/5xx 退避 |
+//!
+//! ## 密钥纪律
+//!
+//! 带 header 的那条路径**只把 header 值喂给请求**：不进日志、不进错误串。错误串里只有 URL
+//! （CF 的 URL 不含密钥）与状态码。
+
+use std::time::Duration;
+
+use unlucky_core::download::blocking::block_on;
+use unlucky_core::download::{DownloadRequest, ResourceKind};
+
+use super::super::env::HostEnv;
+
+/// 站点要求的 User-Agent（Modrinth 明文要求带联系方式，否则限流）。
+pub(super) const USER_AGENT: &str =
+    "Unlucky-Launcher/0.1 (+https://github.com/AskaEth/Unlucky-Launcher)";
+
+/// 最多重试次数（含首次）。
+const ATTEMPTS: u32 = 3;
+
+/// 取一段文本（JSON 原文）。
+pub(super) fn get(env: &HostEnv, url: &str, headers: &[(&str, &str)]) -> Result<String, String> {
+    if headers.is_empty() {
+        get_via_engine(env, url)
+    } else {
+        get_with_headers(env, url, headers)
+    }
+}
+
+/// core 的下载引擎：限流与退避都在里面，这里只负责「URL → 文本」。
+fn get_via_engine(env: &HostEnv, url: &str) -> Result<String, String> {
+    let engine = super::super::engine::engine(env);
+    let dir = env.layout.cache().join("content");
+    std::fs::create_dir_all(&dir).map_err(|error| format!("建缓存目录失败：{error}"))?;
+    let request = DownloadRequest::new(ResourceKind::Other, url, dir.join("response.json"));
+    let bytes = block_on(engine.download_bytes(request))
+        .map_err(|error| format!("请求 {url} 失败：{error}"))?;
+    String::from_utf8(bytes).map_err(|error| format!("响应不是 UTF-8：{error}"))
+}
+
+/// 带 header 的请求（只有 CF 走这条）：429 / 5xx / 连接类失败按退避重试。
+fn get_with_headers(env: &HostEnv, url: &str, headers: &[(&str, &str)]) -> Result<String, String> {
+    let engine = super::super::engine::engine(env);
+    let owned: Vec<(String, String)> = headers
+        .iter()
+        .map(|(name, value)| ((*name).to_string(), (*value).to_string()))
+        .collect();
+
+    for attempt in 0..ATTEMPTS {
+        let result = block_on(async {
+            let mut builder = engine.client().get(url).header("User-Agent", USER_AGENT);
+            for (name, value) in &owned {
+                builder = builder.header(name.as_str(), value.as_str());
+            }
+            let response = builder.send().await.map_err(|error| error.to_string())?;
+            let status = response.status();
+            if status.is_success() {
+                return response.text().await.map_err(|error| error.to_string());
+            }
+            let retry = response
+                .headers()
+                .get("retry-after")
+                .and_then(|value| value.to_str().ok())
+                .and_then(|value| value.parse::<u64>().ok());
+            Err(format!("HTTP {} (retry_after={retry:?})", status.as_u16()))
+        });
+
+        match result {
+            Ok(body) => return Ok(body),
+            Err(reason) if attempt + 1 < ATTEMPTS && retryable(&reason) => {
+                std::thread::sleep(retry_after(&reason, attempt));
+            }
+            Err(reason) => return Err(format!("请求 {url} 失败：{reason}")),
+        }
+    }
+    Err(format!("请求 {url} 失败：重试用尽"))
+}
+
+/// 这个失败值得再试一次吗（429 / 5xx / 连接类；**401/403/404 一律不重试**，重试只会更糟）。
+pub(super) fn retryable(reason: &str) -> bool {
+    reason.contains("HTTP 429")
+        || reason.contains("HTTP 500")
+        || reason.contains("HTTP 502")
+        || reason.contains("HTTP 503")
+        || reason.contains("HTTP 504")
+        || reason.contains("error sending request")
+        || reason.contains("timed out")
+}
+
+/// 退避时长：优先吃服务端给的 `Retry-After`（封顶 30s），否则指数退避（1s、2s、4s）。
+pub(super) fn retry_after(reason: &str, attempt: u32) -> Duration {
+    let parsed = reason
+        .split("retry_after=Some(")
+        .nth(1)
+        .and_then(|rest| rest.split(')').next())
+        .and_then(|value| value.parse::<u64>().ok());
+    match parsed {
+        Some(secs) => Duration::from_secs(secs.min(30)),
+        None => Duration::from_secs(1u64 << attempt.min(4)),
+    }
+}
+
+/// 最小百分号编码（query 串用；不为一件小事引第三方 crate）。
+pub(super) fn encode(raw: &str) -> String {
+    let mut out = String::with_capacity(raw.len());
+    for byte in raw.bytes() {
+        match byte {
+            b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'.' | b'_' | b'~' => {
+                out.push(char::from(byte));
+            }
+            _ => out.push_str(&format!("%{byte:02X}")),
+        }
+    }
+    out
+}

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,
+            "整合包安装管线未落地（M111）；内容库对整合包只做检索",
+            epoch,
+        );
+        return;
+    }
+
+    let _ = tx.send(HostTask::Install {
+        progress: Box::new(progress.clone()),
+        epoch,
+    });
+    match run(env, request, cancel, &mut progress, tx, epoch) {
+        Ok(done) => {
+            progress.stage = InstallStage::Done;
+            progress.files_done = 1;
+            progress.message = done;
+            let _ = tx.send(HostTask::InstallDone {
+                progress: Box::new(progress),
+                result: Ok(request.title.clone()),
+                epoch,
+            });
+        }
+        Err(reason) => {
+            progress.stage = if cancel.load(Ordering::SeqCst) {
+                InstallStage::Cancelled
+            } else {
+                InstallStage::Failed
+            };
+            let _ = tx.send(HostTask::InstallDone {
+                progress: Box::new(progress),
+                result: Err(reason),
+                epoch,
+            });
+        }
+    }
+}
+
+fn fail(tx: &JobSender, mut progress: InstallProgressView, reason: &str, epoch: u64) {
+    progress.stage = InstallStage::Failed;
+    progress.message = reason.to_string();
+    let _ = tx.send(HostTask::InstallDone {
+        progress: Box::new(progress),
+        result: Err(reason.to_string()),
+        epoch,
+    });
+}
+
+/// 真正干活的那一段，返回一句人读的落盘描述。
+fn run(
+    env: &HostEnv,
+    request: &ContentInstallRequest,
+    cancel: &AtomicBool,
+    progress: &mut InstallProgressView,
+    tx: &JobSender,
+    epoch: u64,
+) -> Result<String, String> {
+    let instance = find_instance(env, &request.instance)?;
+    let game_dir = game_dir_of(env, &instance)?;
+    let dir = request
+        .kind
+        .dir()
+        .ok_or_else(|| "该内容类型不支持单文件装入".to_string())?;
+    let target_dir = game_dir.join(dir);
+    std::fs::create_dir_all(&target_dir)
+        .map_err(|error| format!("建目录 {} 失败：{error}", target_dir.display()))?;
+
+    let file = resolve_file(env, request)?;
+    if cancel.load(Ordering::SeqCst) {
+        return Err("已取消（下载开始前）".to_string());
+    }
+    progress.stage = InstallStage::Downloading;
+    progress.message = file.name.clone();
+    let _ = tx.send(HostTask::Install {
+        progress: Box::new(progress.clone()),
+        epoch,
+    });
+
+    let dest = target_dir.join(&file.name);
+    let mut download = DownloadRequest::new(ResourceKind::ModFile, file.url, dest.clone());
+    if let Some(sha1) = file.sha1.as_deref().filter(|hex| !hex.is_empty()) {
+        download = download.with_sha1(sha1);
+    }
+    block_on(super::super::engine::engine(env).download(download))
+        .map_err(|error| format!("下载失败：{error}"))?;
+    Ok(format!("{}（{}）", file.name, dest.display()))
+}
+
+fn find_instance(env: &HostEnv, id: &str) -> Result<InstanceSummary, String> {
+    super::super::game::instances(env)
+        .into_iter()
+        .find(|instance| instance.id == id)
+        .ok_or_else(|| format!("找不到实例 {id}"))
+}
+
+/// 实例的运行目录（D20 覆盖链：实例 `isolation` > 全局 `instances.mode`）。
+fn game_dir_of(env: &HostEnv, instance: &InstanceSummary) -> Result<PathBuf, String> {
+    let global = super::super::game::global_mode(env);
+    let config = read_instance_config(&env.layout, &instance.id)
+        .map_err(|error| format!("读实例设置失败：{error}"))?;
+    derive_game_dir(
+        &env.game,
+        &instance.version_id,
+        global,
+        config.as_ref(),
+        None,
+    )
+    .map(|derivation| derivation.game_dir)
+    .map_err(|error| format!("隔离目录派生失败：{error}"))
+}
+
+/// 要下载的那个文件。
+struct RemoteFile {
+    url: String,
+    name: String,
+    sha1: Option<String>,
+}
+
+/// 解析「这个项目下最适合目标实例的那个文件」。
+fn resolve_file(env: &HostEnv, request: &ContentInstallRequest) -> Result<RemoteFile, String> {
+    match request.source {
+        ContentSource::Modrinth => modrinth_file(env, request),
+        ContentSource::Curseforge => Err(
+            "CurseForge 的文件解析未接通（要带 key 的文件端点；见报告「没验的部分」）".to_string(),
+        ),
+    }
+}
+
+fn modrinth_file(env: &HostEnv, request: &ContentInstallRequest) -> Result<RemoteFile, String> {
+    let mut url = format!(
+        "{MODRINTH}/project/{}/version?game_versions={}",
+        request.project,
+        encode(&format!("[\"{}\"]", request.game_version))
+    );
+    if let Some(facet) = loader_facet(request.loader) {
+        url.push_str(&format!("&loaders={}", encode(&format!("[\"{facet}\"]"))));
+    }
+    let body = get(env, &url, &[])?;
+    let json: serde_json::Value = serde_json::from_str(&body)
+        .map_err(|error| format!("Modrinth 版本列表不是合法 JSON：{error}"))?;
+    let versions = json
+        .as_array()
+        .ok_or_else(|| "Modrinth 版本列表不是数组".to_string())?;
+    let first = versions
+        .first()
+        .ok_or_else(|| "这个项目没有匹配目标实例（版本 / 加载器）的文件".to_string())?;
+    let files = first
+        .get("files")
+        .and_then(serde_json::Value::as_array)
+        .ok_or_else(|| "版本里没有 files".to_string())?;
+    // 显式选 `primary: true`（Modrinth 官方口径）：取第一个会拿到 sources jar 这类坑
+    let file = files
+        .iter()
+        .find(|file| {
+            file.get("primary")
+                .and_then(serde_json::Value::as_bool)
+                .unwrap_or(false)
+        })
+        .or_else(|| files.first())
+        .ok_or_else(|| "版本里没有可用文件".to_string())?;
+
+    let url = file
+        .get("url")
+        .and_then(serde_json::Value::as_str)
+        .ok_or_else(|| "文件没有 url".to_string())?;
+    let name = file
+        .get("filename")
+        .and_then(serde_json::Value::as_str)
+        .ok_or_else(|| "文件没有 filename".to_string())?;
+    let sha1 = file
+        .get("hashes")
+        .and_then(|hashes| hashes.get("sha1"))
+        .and_then(serde_json::Value::as_str)
+        .map(ToString::to_string);
+    Ok(RemoteFile {
+        url: url.to_string(),
+        name: safe_file_name(name),
+        sha1,
+    })
+}
+
+/// 只留文件名本身：站点给的名字可能带路径分隔符，落盘前必须砍掉
+/// （与 `core::addon::pack::path` 的穿越双检同一条纪律）。
+pub(super) fn safe_file_name(raw: &str) -> String {
+    let name = raw
+        .rsplit(['/', '\\'])
+        .next()
+        .unwrap_or(raw)
+        .trim()
+        .to_string();
+    if name.is_empty() || name == "." || name == ".." {
+        "download.bin".to_string()
+    } else {
+        name
+    }
+}

crates/presenter/src/host/addon/sources.rs

@@ -0,0 +1,262 @@
+//! 两个站点的检索方言（M109）：把各自的 JSON 翻成 [`ContentHit`]。
+//!
+//! 两个站点在**同一件事上用的字段名完全不同**，所以这里每个站点一段、各自带注释：
+//!
+//! | 语义 | Modrinth `/v2/search` | CurseForge `/v1/mods/search` |
+//! |---|---|---|
+//! | 项目 id | `project_id`（base62） | `id`（数字） |
+//! | 标题 / 简介 | `title` / `description` | `name` / `summary` |
+//! | 下载量 | `downloads` | `downloadCount` |
+//! | 游戏版本 | `versions` | `latestFilesIndexes[].gameVersion` |
+//! | 加载器 | `categories` 里混着的 `fabric`/`forge`/… | `latestFilesIndexes[].modLoader`（数字枚举） |
+//!
+//! 加载器那一行是最容易抄错的地方：Modrinth 的 `categories` 同时装着 `optimization` 这种**分类标签**，
+//! 直接整份当加载器用，画面上就会多出「optimization」这种假加载器（`sources/tests` 钉住了这一条）。
+
+use serde_json::Value;
+
+use crate::dto::{
+    loader_facet, ContentHit, ContentKind, ContentQuery, ContentResults, ContentSource,
+};
+
+use super::super::env::HostEnv;
+use super::curseforge_ready;
+use super::http::{encode, get};
+
+/// Modrinth v2 的根（无需 key）。
+pub(super) const MODRINTH: &str = "https://api.modrinth.com/v2";
+/// CurseForge v1 的根（需要 `X-API-KEY`）。
+pub(super) const CURSEFORGE: &str = "https://api.curseforge.com/v1";
+/// CurseForge 的「Minecraft」gameId（官方固定值）。
+const CF_MINECRAFT: u32 = 432;
+
+/// 检索分派。
+pub(super) fn search(env: &HostEnv, query: &ContentQuery) -> Result<ContentResults, String> {
+    match query.source {
+        ContentSource::Modrinth => modrinth(env, query),
+        ContentSource::Curseforge => curseforge(env, query),
+    }
+}
+
+// --------------------------------------------------------------- Modrinth
+
+fn modrinth(env: &HostEnv, query: &ContentQuery) -> Result<ContentResults, String> {
+    let mut facets = vec![format!("[\"project_type:{}\"]", query.kind.modrinth_type())];
+    if let Some(version) = &query.game_version {
+        facets.push(format!("[\"versions:{version}\"]"));
+    }
+    if let Some(facet) = query.loader.and_then(loader_facet) {
+        facets.push(format!("[\"categories:{facet}\"]"));
+    }
+
+    let mut url = format!(
+        "{MODRINTH}/search?limit={}&offset={}&index={}&facets={}",
+        query.limit.min(100),
+        query.offset,
+        query.sort.modrinth_index(),
+        encode(&format!("[{}]", facets.join(",")))
+    );
+    if !query.text.trim().is_empty() {
+        url.push_str(&format!("&query={}", encode(query.text.trim())));
+    }
+
+    let body = get(env, &url, &[])?;
+    let json: Value = serde_json::from_str(&body)
+        .map_err(|error| format!("Modrinth 返回的不是合法 JSON：{error}"))?;
+    let hits = json
+        .get("hits")
+        .and_then(Value::as_array)
+        .ok_or_else(|| "Modrinth 返回里没有 hits 字段".to_string())?
+        .iter()
+        .map(modrinth_hit)
+        .collect::<Vec<_>>();
+
+    Ok(ContentResults {
+        query: query.clone(),
+        hits,
+        total: u32_of(&json, "total_hits"),
+        curseforge: curseforge_ready(),
+    })
+}
+
+/// 一条 Modrinth 命中项 → DTO（缺字段一律给空/零，**不**编造）。
+fn modrinth_hit(value: &Value) -> ContentHit {
+    let loaders = strings(value, "categories")
+        .into_iter()
+        // `categories` 混着加载器与分类标签：只留已知的四个加载器
+        .filter(|tag| matches!(tag.as_str(), "fabric" | "forge" | "neoforge" | "quilt"))
+        .collect();
+
+    ContentHit {
+        id: text(value, "project_id"),
+        slug: text(value, "slug"),
+        title: text(value, "title"),
+        summary: text(value, "description"),
+        author: text(value, "author"),
+        downloads: u64_of(value, "downloads"),
+        updated: date_part(&text(value, "updated")),
+        source: ContentSource::Modrinth,
+        game_versions: strings(value, "versions"),
+        loaders,
+        icon: optional_text(value, "icon_url"),
+    }
+}
+
+// --------------------------------------------------------------- CurseForge
+
+fn curseforge(env: &HostEnv, query: &ContentQuery) -> Result<ContentResults, String> {
+    let Some(key) = super::curseforge_key() else {
+        return Err("CurseForge 需要 API key（ULL_CF_API_KEY 未设置）".to_string());
+    };
+    let mut url = format!(
+        "{CURSEFORGE}/mods/search?gameId={CF_MINECRAFT}&classId={}&index={}&pageSize={}&sortField={}&sortOrder=desc",
+        query.kind.curseforge_class(),
+        query.offset,
+        query.limit.min(50),
+        query.sort.curseforge_field()
+    );
+    if !query.text.trim().is_empty() {
+        url.push_str(&format!("&searchFilter={}", encode(query.text.trim())));
+    }
+    if let Some(version) = &query.game_version {
+        url.push_str(&format!("&gameVersion={}", encode(version)));
+    }
+
+    let body = get(env, &url, &[("x-api-key", key.as_str())])?;
+    let json: Value = serde_json::from_str(&body)
+        .map_err(|error| format!("CurseForge 返回的不是合法 JSON：{error}"))?;
+    let hits = json
+        .get("data")
+        .and_then(Value::as_array)
+        .ok_or_else(|| "CurseForge 返回里没有 data 字段".to_string())?
+        .iter()
+        .map(curseforge_hit)
+        .collect::<Vec<_>>();
+
+    Ok(ContentResults {
+        query: query.clone(),
+        hits,
+        total: json
+            .get("pagination")
+            .map(|pagination| u64_of(pagination, "totalCount"))
+            .and_then(|value| u32::try_from(value).ok())
+            .unwrap_or(0),
+        curseforge: true,
+    })
+}
+
+/// 一条 CF 命中项 → DTO。加载器只能从 `latestFilesIndexes[].modLoader` 的数字枚举反推。
+fn curseforge_hit(value: &Value) -> ContentHit {
+    let mut game_versions: Vec<String> = Vec::new();
+    let mut loaders: Vec<String> = Vec::new();
+    if let Some(indexes) = value.get("latestFilesIndexes").and_then(Value::as_array) {
+        for entry in indexes {
+            if let Some(version) = entry.get("gameVersion").and_then(Value::as_str) {
+                if !game_versions.iter().any(|item| item == version) {
+                    game_versions.push(version.to_string());
+                }
+            }
+            if let Some(loader) = entry
+                .get("modLoader")
+                .and_then(Value::as_u64)
+                .and_then(curseforge_loader)
+            {
+                if !loaders.iter().any(|item| item == loader) {
+                    loaders.push(loader.to_string());
+                }
+            }
+        }
+    }
+    let author = value
+        .get("authors")
+        .and_then(Value::as_array)
+        .and_then(|items| items.first())
+        .map(|entry| text(entry, "name"))
+        .unwrap_or_default();
+
+    ContentHit {
+        id: value
+            .get("id")
+            .and_then(Value::as_u64)
+            .map(|id| id.to_string())
+            .unwrap_or_default(),
+        slug: text(value, "slug"),
+        title: text(value, "name"),
+        summary: text(value, "summary"),
+        author,
+        downloads: u64_of(value, "downloadCount"),
+        updated: date_part(&text(value, "dateModified")),
+        source: ContentSource::Curseforge,
+        game_versions,
+        loaders,
+        icon: value
+            .get("logo")
+            .and_then(|logo| logo.get("url"))
+            .and_then(Value::as_str)
+            .map(ToString::to_string),
+    }
+}
+
+/// CF 的 `modLoader` 枚举 → Modrinth 口径的 loader 名（1 Forge / 4 Fabric / 5 Quilt / 6 NeoForge）。
+pub(super) fn curseforge_loader(raw: u64) -> Option<&'static str> {
+    match raw {
+        1 => Some("forge"),
+        4 => Some("fabric"),
+        5 => Some("quilt"),
+        6 => Some("neoforge"),
+        _ => None,
+    }
+}
+
+// --------------------------------------------------------------- 小工具
+
+/// 取字符串字段（缺 / 类型不对 ⇒ 空串）。
+fn text(value: &Value, key: &str) -> String {
+    value
+        .get(key)
+        .and_then(Value::as_str)
+        .unwrap_or_default()
+        .to_string()
+}
+
+/// 取可选字符串字段（空串也当没有——站点会给 `""` 表示没图）。
+fn optional_text(value: &Value, key: &str) -> Option<String> {
+    value
+        .get(key)
+        .and_then(Value::as_str)
+        .filter(|text| !text.is_empty())
+        .map(ToString::to_string)
+}
+
+/// 取字符串数组（缺 / 类型不对 ⇒ 空 vec）。
+fn strings(value: &Value, key: &str) -> Vec<String> {
+    value
+        .get(key)
+        .and_then(Value::as_array)
+        .map(|items| {
+            items
+                .iter()
+                .filter_map(|item| item.as_str().map(ToString::to_string))
+                .collect()
+        })
+        .unwrap_or_default()
+}
+
+fn u64_of(value: &Value, key: &str) -> u64 {
+    value.get(key).and_then(Value::as_u64).unwrap_or(0)
+}
+
+fn u32_of(value: &Value, key: &str) -> u32 {
+    u32::try_from(u64_of(value, key)).unwrap_or(0)
+}
+
+/// ISO-8601 → 日期部分（`2024-05-01T…` → `2024-05-01`；短串原样返回）。
+pub(super) fn date_part(raw: &str) -> String {
+    raw.get(..10).unwrap_or(raw).to_string()
+}
+
+/// 类型名只用来钉住「四条侧栏都在」的常量没被改乱（检索本身按 `kind` 走 facet）。
+#[must_use]
+pub(super) fn all_kinds() -> [ContentKind; 4] {
+    ContentKind::ALL
+}

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"]
+    );
+}