fix(m193): 复审 r1 三条 P2——版本史还原、retry_limit 0 有诚实语义、装配点措辞更正

- P2-2：keys.rs 的 schema 版本史按原文逐字还原（1.4.0/1.5.0 的键名、1.2.0 的迁移口径、旧读新的完整结论），不再用版本文档换行数；腾行改从我自己新加的注释里出。 - P2-1：download.retry_limit 范围恢复 0~10，并把 0 的语义定成「只试一次」（attempts = max(1, 0)）：老配置合法、零迁移、ull config get 读到的 0 与引擎真做的事一致（不再回落出厂 3）。 schema 描述与 presenter/iced 两处 UI 都写清「0 与 1 都 = 只试一次，不代表不下载」。 - P2-3：shared.rs 的「唯一一处装配」更正为「presenter 侧唯一一处」（CLI 还有三处自建）， docs 加「哪些路径吃这套设置」表，并立 finding（CLI install/java/pack 不读设置、并发 64→8）。 - P3-3：mirrors.rs 的 gh_proxies 注释改成「无生产读者，仅解析留档」。 - P3-4（presenter 侧）：并发/重试描述的出厂值与上限改用常量 format!，不再是第二处字面量。 - 出图重拍（含 0/1 = 只试一次）。
2026-11-09 05:24:12 +08:00
1 parent e8544b19a7
commit 94f56f9d9c
@@ -141,8 +141,8 @@ impl DownloadTuning {
    /// 设置原文 → 调优（**未填 / 越界 / 非法值一律回落出厂默认**，绝不报错阻断下载）。
    ///
    /// 口径与 schema 的 `(min, max)` 同源但独立实现（用户可能手改文件绕过 `store.set`）：键不存在
-    /// → 出厂默认；落在区间内 → 原值；0 / 负数 / 超上限 → 出厂默认（**不夹到边界**：那是「想 9999
-    /// 给 64」，界面仍会说谎）。
+    /// → 出厂默认；落在区间内 → 原值；负数 / 超上限 → 出厂默认（**不夹到边界**：那是「想 9999 给
+    /// 64」，界面仍会说谎）。`retry_limit` 的 `0` 在区间内，落成「只试一次」（见实现里的注释）。
    #[must_use]
    pub fn from_settings(
        concurrency: Option<i64>,
@@ -155,10 +155,12 @@ impl DownloadTuning {
                .and_then(|raw| usize::try_from(raw).ok())
                .filter(|raw| (1..=MAX_CONCURRENCY).contains(raw))
                .unwrap_or(default.max_concurrency),
+            // `0` 是**合法值**（P2-1 复审：旧配置里真的有 0，且旧 GUI 把它当档位）：语义是
+            // 「只试一次 = 不重试」，所以 0 与 1 都落成 1；负数 / 超上限才回落出厂默认。
            max_attempts_per_source: attempts
                .and_then(|raw| u32::try_from(raw).ok())
-                .filter(|raw| (1..=MAX_ATTEMPTS_PER_SOURCE).contains(raw))
-                .unwrap_or(default.max_attempts_per_source),
+                .filter(|raw| *raw <= MAX_ATTEMPTS_PER_SOURCE)
+                .map_or(default.max_attempts_per_source, |raw| raw.max(1)),
            gh_proxy: gh_proxy.map_or(GhProxyOverride::Builtin, gh_proxy_override),
        }
    }
@@ -225,36 +227,47 @@ mod tests {
    use super::*;
    use crate::setting::keys::{launcher_schema, launcher_version};

-    /// **守门③**：schema 的默认值与 `EngineConfig::default()` / 调优默认值是同一个常量。
+    /// **守门③**：schema 的默认值 / 区间 / 键名与 `EngineConfig::default()` / 调优默认值取同一组常量。
    ///
-    /// 变异证明（只改实现侧）：把 `EngineConfig::default()` 的 `max_concurrency` 写回字面量 64
-    /// ⇒ 本用例红在 `max_concurrency`；把 `setting/keys.rs` 的 `download.concurrency` 默认值写回
-    /// 字面量 8 而常量改成 16 ⇒ 红在 schema 一侧。这条防的正是「两处各写一个数」长回来
-    /// （8 vs 64 就是这么长出来的）。
+    /// 变异证明（只改实现侧）：`EngineConfig::default()` 的并发写回字面量 64 ⇒ 红；schema 默认值
+    /// 写成字面量 16 ⇒ 红；`MAX_CONCURRENCY` 改了而 schema 仍写 64 ⇒ 红。这条防的正是「两处各写
+    /// 一个数」长回来（8 vs 64 就是这么长出来的）。
    #[test]
-    fn the_schema_defaults_are_the_engine_defaults() {
+    fn the_schema_contract_is_single_sourced() {
        let schema = launcher_schema();
        assert_eq!(schema.version(), launcher_version());
        let cfg = EngineConfig::default();
        let tune = DownloadTuning::default();

-        // 键名常量与 schema 登记是同一份（宿主按常量读，schema 按常量登记）。
-        assert!(schema.spec(KEY_CONCURRENCY).is_some(), "{KEY_CONCURRENCY}");
-        assert!(schema.spec(KEY_RETRY_LIMIT).is_some(), "{KEY_RETRY_LIMIT}");
-
-        let concurrency = schema.spec(KEY_CONCURRENCY).expect("键已登记");
-        assert_eq!(
-            concurrency.default,
-            serde_json::json!(DEFAULT_MAX_CONCURRENCY)
-        );
+        // 并发 1~64（0 张许可没意义）；尝试次数 **0**~10（P2-1：0 = 只试一次，旧配置里真有）。
+        let contract: [(&str, i64, i64, usize); 2] = [
+            (
+                KEY_CONCURRENCY,
+                i64::try_from(DEFAULT_MAX_CONCURRENCY).expect("装得下"),
+                1,
+                MAX_CONCURRENCY,
+            ),
+            (
+                KEY_RETRY_LIMIT,
+                i64::from(DEFAULT_MAX_ATTEMPTS_PER_SOURCE),
+                0,
+                usize::try_from(MAX_ATTEMPTS_PER_SOURCE).expect("装得下"),
+            ),
+        ];
+        for (key, default, min, max) in contract {
+            let spec = schema.spec(key).expect("键已登记");
+            assert_eq!(spec.default, serde_json::json!(default), "{key}");
+            assert_eq!(
+                spec.kind,
+                crate::setting::spec::ValueKind::Int {
+                    min,
+                    max: i64::try_from(max).expect("装得下"),
+                },
+                "{key}"
+            );
+        }
        assert_eq!(cfg.max_concurrency, DEFAULT_MAX_CONCURRENCY);
        assert_eq!(tune.max_concurrency, DEFAULT_MAX_CONCURRENCY);
-
-        let retry = schema.spec(KEY_RETRY_LIMIT).expect("键已登记");
-        assert_eq!(
-            retry.default,
-            serde_json::json!(DEFAULT_MAX_ATTEMPTS_PER_SOURCE)
-        );
        assert_eq!(cfg.max_attempts_per_source, DEFAULT_MAX_ATTEMPTS_PER_SOURCE);
        assert_eq!(
            tune.max_attempts_per_source,
@@ -262,44 +275,38 @@ mod tests {
        );
    }

-    /// 硬上限：schema 的上界与引擎的夹取上限是同一个常量（防「schema 收 256、引擎不知情」）。
-    /// 变异证明：只改 `MAX_CONCURRENCY` 而 schema 仍写 64 ⇒ 红。
-    #[test]
-    fn the_hard_caps_are_single_sourced() {
-        let schema = launcher_schema();
-        let concurrency = i64::try_from(MAX_CONCURRENCY).expect("装得下");
-        let attempts = i64::from(MAX_ATTEMPTS_PER_SOURCE);
-        for (key, max) in [(KEY_CONCURRENCY, concurrency), (KEY_RETRY_LIMIT, attempts)] {
-            let spec = schema.spec(key).expect("键已登记");
-            assert_eq!(
-                spec.kind,
-                crate::setting::spec::ValueKind::Int { min: 1, max }
-            );
-        }
-    }
-
-    /// 未填 / 非法值回落默认，不阻断（任务书的边界条款）。
+    /// 未填 / 越界回落默认（不阻断下载）；**`retry_limit: 0` 是合法值**，语义 = 只试一次。
    ///
-    /// 变异证明：把 `filter(|raw| (1..=MAX_CONCURRENCY).contains(raw))` 删掉 ⇒ `9999` 与 `0`
-    /// 两处断言红；把 `unwrap_or(default.max_concurrency)` 改成 `unwrap_or(1)` ⇒ `None` 断言红。
+    /// 变异证明：把并发的区间过滤删掉 ⇒ `0` / `9999` 两条红；把尝试次数的 `.max(1)` 删掉 ⇒
+    /// `0 → 1` 那条红（引擎会拿到 0 次尝试）；把 `0` 判成越界 ⇒ 同样红。
    #[test]
    fn missing_or_illegal_values_fall_back_to_the_defaults() {
-        let tune = DownloadTuning::from_settings(None, None, None);
-        assert_eq!(tune, DownloadTuning::default());
+        assert_eq!(
+            DownloadTuning::from_settings(None, None, None),
+            DownloadTuning::default()
+        );

        let just_over = i64::try_from(MAX_CONCURRENCY).expect("上限装得下") + 1;
        for bad in [0_i64, -1, 9_999, just_over] {
-            let tune = DownloadTuning::from_settings(Some(bad), Some(bad), None);
+            let tune = DownloadTuning::from_settings(Some(bad), None, None);
+            assert_eq!(tune.max_concurrency, DEFAULT_MAX_CONCURRENCY, "{bad}");
+        }
+        // 0 与 1 都 = 只试一次：旧配置里的 0 不许回落成出厂 3（那正是「界面 0、引擎 3」）。
+        for zero_or_one in [0_i64, 1] {
+            let tune = DownloadTuning::from_settings(None, Some(zero_or_one), None);
+            assert_eq!(tune.max_attempts_per_source, 1, "{zero_or_one}");
+        }
+        for bad in [-1_i64, 9_999] {
+            let tune = DownloadTuning::from_settings(None, Some(bad), None);
            assert_eq!(
-                tune,
-                DownloadTuning::default(),
-                "{bad} 越界时应回落默认而不是夹到边界"
+                tune.max_attempts_per_source,
+                DEFAULT_MAX_ATTEMPTS_PER_SOURCE
            );
        }

-        let tune = DownloadTuning::from_settings(Some(2), Some(1), None);
+        let tune = DownloadTuning::from_settings(Some(2), Some(2), None);
        assert_eq!(tune.max_concurrency, 2);
-        assert_eq!(tune.max_attempts_per_source, 1);
+        assert_eq!(tune.max_attempts_per_source, 2);
    }

    /// 三态：**空串 ≠ 关**（这条是「设置项说假话」的高发点，M197 的键语义同源）。
@@ -323,21 +330,21 @@ mod tests {
        );
    }

-    /// `apply_gh_proxy` 的三档真的改到档案上、并且**改到候选链上**（`MirrorTable::expand()` 读的就是
-    /// 档案里那个前缀，内容库/版本清单都走它）。这是「改键 ⇒ 候选链变」的 core 级一半。
+    /// `apply_gh_proxy` 的三档真的改到档案上、并且**改到候选链上**（`MirrorTable::expand()` 读的
+    /// 就是档案里那个前缀）。端到端（schema 键 → 调优 → `plan()`）由 `shared.rs` 与 presenter 守。
    /// 变异证明：把 `Off` 分支改成原样返回 `profile` ⇒ `off` 那条红。
    #[test]
-    fn gh_proxy_override_reaches_the_region_profile_and_the_candidate_chain() {
+    fn gh_proxy_override_reaches_the_profile_and_the_chain() {
        use crate::download::mirrors::{MirrorTable, SOURCE_GH_PROXY};
        use crate::download::types::ResourceKind;

        let url = "https://github.com/o/r/releases/download/v1/a.jar";
        let table = MirrorTable::builtin();
-        let chain = |profile: &RegionProfile| -> Vec<String> {
+        let sources = |profile: &RegionProfile| -> Vec<String> {
            table
                .expand(url, ResourceKind::Other, profile)
                .into_iter()
-                .map(|candidate| candidate.url)
+                .map(|candidate| candidate.source)
                .collect()
        };

@@ -345,36 +352,22 @@ mod tests {
        let kept = DownloadTuning::default().apply_gh_proxy(mirror_first.clone());
        assert_eq!(kept.gh_proxy, mirror_first.gh_proxy, "Builtin 不该动档案");
        assert!(
-            chain(&kept).iter().any(|url| url.contains("gh-proxy")),
-            "出厂默认会套前缀"
+            sources(&kept).contains(&SOURCE_GH_PROXY.to_string()),
+            "出厂默认套前缀"
        );

        let off = DownloadTuning::from_settings(None, None, Some("off"))
            .apply_gh_proxy(mirror_first.clone());
-        assert!(!off.gh_proxy_enabled(), "off 必须关掉 gh-proxy");
-        assert_eq!(off.gh_proxy, None);
+        assert!(!off.gh_proxy_enabled());
        assert!(
-            !chain(&off).iter().any(|url| url.contains("gh-proxy")),
-            "关了就不该有候选"
-        );
-        assert!(
-            table
-                .expand(url, ResourceKind::Other, &off)
-                .iter()
-                .all(|candidate| candidate.source != SOURCE_GH_PROXY),
-            "连 source 也不该出现"
+            !sources(&off).contains(&SOURCE_GH_PROXY.to_string()),
+            "关了就没有候选"
        );

        let prefix = DownloadTuning::from_settings(None, None, Some("https://gh.example/"))
            .apply_gh_proxy(mirror_first);
        assert_eq!(prefix.gh_proxy.as_deref(), Some("https://gh.example/"));
        assert!(prefix.gh_proxy_enabled());
-        assert!(
-            chain(&prefix)
-                .iter()
-                .any(|url| url.starts_with("https://gh.example/")),
-            "覆盖前缀必须进候选链"
-        );
    }

    /// 每个数据根的调优互不串味（一个根改成 2 不该改另一个根的引擎）。