feat(fetch): multi-source download fallback with mirrors; fetch --runtime all; DOWNLOADS.md manual guide — v0.2.1

Author: ztwzeroo

CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project are documented here. The format follows
 [SemVer](https://semver.org/) with a `0.x` experimental prefix. Evidence links
 point to files in this repository (`docs/`) so the trail is auditable offline.
 
+## [0.2.1] — 2026-09-29
+
+### Added
+
+- **Multi-source download fallback** — `fetch` now tries the official
+  `raw.githubusercontent.com` URL first, then the equivalent `github.com` raw
+  link, and only then community mirrors of the same URLs (default
+  `gh-proxy.com`/`ghproxy.net`, overridable via `DLSS_COMBO_MIRRORS`). All
+  failures list every source tried. We still never redistribute upstream files
+  (`src/dlss_combo/fetch.py`, `tests/test_fetch_sources.py`).
+- **`fetch --runtime all`** — one command downloads both DLSS-G runtimes
+  (310.9 + 310.1) plus the Swapper portable (`src/dlss_combo/cli.py`,
+  `tests/test_fetch_all.py`).
+- **[DOWNLOADS.md](DOWNLOADS.md)** — manual download & placement guide on the
+  repo page: direct upstream links for every file, why NVIDIA SDK terms forbid
+  bundling them into our zips, mirror configuration, integrity notes.
+
 ## [0.2.0] — 2026-09-29
 
 ### Added

DOWNLOADS.md

@@ -0,0 +1,75 @@
+# Downloads & manual file placement
+
+[← Back to the project](README.md)
+
+`dlss-combo fetch` downloads everything below automatically, verifies it, and
+caches it. **This page is the manual fallback** for when scripted downloads are
+impossible. It is also the honest answer to "why isn't everything in one zip":
+
+> The frame-generation DLLs embed **NVIDIA's DLSS-G runtime**, and the Swapper
+> portable app contains NVIDIA's neural-rendering library. NVIDIA's SDK terms do
+> not allow us to redistribute those binaries inside our release packages, so
+> this project links to the **upstream official channels** and fetches from them
+> at install time. We never re-host or modify upstream files.
+
+## 1. Frame-generation kit — [sdli1995/dlssg_for_sm86](https://github.com/sdli1995/dlssg_for_sm86)
+
+GPLv3 source (license declared in the upstream README); the embedded NVIDIA
+runtime inside these DLLs is NVIDIA's, not ours or upstream's to relicense.
+
+Download these files from the repository (paths below are on `main`; `fetch`
+pins the exact commit and records it in `kit.json`):
+
+| Kit file | Runtime 310.9 (repo root) | Runtime 310.1 (repo `310.1/`) |
+|---|---|---|
+| main proxy | [`version.dll`](https://github.com/sdli1995/dlssg_for_sm86/raw/main/version.dll) | [`310.1/version.dll`](https://github.com/sdli1995/dlssg_for_sm86/raw/main/310.1/version.dll) |
+| INI template | [`dlssg_sm86.ini`](https://github.com/sdli1995/dlssg_for_sm86/raw/main/dlssg_sm86.ini) | [`310.1/dlssg_sm86.ini`](https://github.com/sdli1995/dlssg_for_sm86/raw/main/310.1/dlssg_sm86.ini) |
+| alternative names | [`alternatives/winmm.dll`](https://github.com/sdli1995/dlssg_for_sm86/raw/main/alternatives/winmm.dll) · [`d3d12.dll`](https://github.com/sdli1995/dlssg_for_sm86/raw/main/alternatives/d3d12.dll) · [`dbghelp.dll`](https://github.com/sdli1995/dlssg_for_sm86/raw/main/alternatives/dbghelp.dll) · [`dinput8.dll`](https://github.com/sdli1995/dlssg_for_sm86/raw/main/alternatives/dinput8.dll) · [`dxgi.dll`](https://github.com/sdli1995/dlssg_for_sm86/raw/main/alternatives/dxgi.dll) | same names under [`310.1/alternatives/`](https://github.com/sdli1995/dlssg_for_sm86/tree/main/310.1/alternatives) |
+
+Place them so your kit directory looks like (default kit: `~/dlss-combo-kit`):
+
+```text
+<kit>/dlssg/310.9/version.dll
+<kit>/dlssg/310.9/dlssg_sm86.ini
+<kit>/dlssg/310.9/alternatives/{winmm,d3d12,dbghelp,dinput8,dxgi}.dll
+<kit>/dlssg/310.1/…            (same layout)
+```
+
+## 2. Image layer — [DLSS5-Swapper](https://github.com/rakanki911/DLSS5-Swapper) (MIT app)
+
+Download the **portable** build from its
+[latest release](https://github.com/rakanki911/DLSS5-Swapper/releases/latest)
+(`DLSS5Swapper-*-portable.exe`; ignore the Setup installer), then either run it
+directly or let the kit manage it:
+
+```text
+<kit>/swapper/DLSS5Swapper-<version>-portable.exe
+```
+
+## 3. The toolkit itself
+
+Prebuilt `dlss-combo` binaries for Windows x64 and Linux x64 are on our
+[Releases](releases/latest) page with `SHA256SUMS.txt` — that part is our code
+(MIT) and we do ship it.
+
+## Slow or blocked GitHub? Mirrors
+
+`fetch` tries official sources first (`raw.githubusercontent.com`, then
+`github.com/<repo>/raw/…`) and only falls back to community mirrors of those
+same URLs afterwards. You can set your own mirror list:
+
+```bash
+export DLSS_COMBO_MIRRORS="https://your-mirror.example/,https://another.example/"
+```
+
+Default mirrors: `https://gh-proxy.com/`, `https://ghproxy.net/` — they proxy
+the official URLs above; files are still hash-recorded locally on download
+(`kit.json`, local integrity baseline — upstream publishes no checksums for
+these assets, and mirrors are third parties, so treat official sources as the
+source of truth when reachable).
+
+## Integrity
+
+Every file the tool installs is SHA256-recorded at download time and re-verified
+on every later run (`doctor`, reinstall, launch). Manual downloads are accepted
+by `fetch` as cache hits only after the same checks.

README.md

@@ -28,7 +28,7 @@
 
 [Compatibility](#will-it-work-with-my-setup) · [FAQ](#frequently-asked-questions) · [Known issues](docs/STATUS.md) · [Contribute](CONTRIBUTING.md) · [Changelog](CHANGELOG.md) · [Dev log](docs/devlog/2026-09-20.md)
 
-*Prebuilt Windows EXE and Linux binaries ship on the [Releases](../../releases) page — or run from source with Python 3.10+. No upstream DLLs are bundled; components are fetched and checksum-verified at install time.*
+*Prebuilt Windows EXE and Linux binaries ship on the [Releases](../../releases) page — or run from source with Python 3.10+. No upstream DLLs are bundled; components are fetched and checksum-verified at install time. See [Downloads & manual placement](DOWNLOADS.md).*
 
 ## Why this project?
 

README.zh-CN.md

@@ -79,6 +79,9 @@ Target environment: **Windows 10/11 x64, RTX 20 or RTX 30**, and a D3D12 game wi
 
 ## Getting started / 开始使用
 
+所有上游文件由工具自动下载（GitHub 访问不畅时自动回退镜像源，可用 `DLSS_COMBO_MIRRORS` 自定义）；也可按 [手动下载与放置指南](DOWNLOADS.md) 自备文件。
+
+
 The commands below are for experimental testing. Read the known issues and keep an independent backup before writing to any game directory. Not sure which game to start with? See [Recommended test games / 推荐测试游戏](docs/TEST-GAMES.md)（英文 / English）.
 
 以下命令供实验测试使用。向游戏目录写入前，请先阅读已知问题并保留独立备份。不知从哪款游戏开始？参考[推荐测试游戏列表](docs/TEST-GAMES.md)（英文）。

src/dlss_combo/__init__.py

@@ -1,2 +1,2 @@
 """dlss-combo: DLSS 5 画质 + DLSS 帧生成 组合安装编排器。"""
-__version__ = "0.2.0"
+__version__ = "0.2.1"

src/dlss_combo/cli.py

@@ -22,7 +22,7 @@ def _build_parser() -> argparse.ArgumentParser:
 
     pf = sub.add_parser("fetch", help="download/update the kit cache (upstream binaries)")
     pf.add_argument("--kit-dir", type=Path, default=DEFAULT_KIT)
-    pf.add_argument("--runtime", choices=["310.9", "310.1"], default="310.9")
+    pf.add_argument("--runtime", choices=["310.9", "310.1", "all"], default="310.9")
     pf.add_argument("--refresh", action="store_true", help="force re-download")
 
     pi = sub.add_parser("install", help="install the frame-gen layer into a game directory")
@@ -78,8 +78,10 @@ def main(argv: list[str] | None = None) -> int:
         if args.command == "fetch":
             from .fetch import fetch_kit, fetch_swapper
 
-            kit = fetch_kit(args.kit_dir, runtime=args.runtime, refresh=args.refresh)
-            print(f"dlssg kit ready: {kit.root} (commit {kit.dlssg_commit})")
+            runtimes = ("310.9", "310.1") if args.runtime == "all" else (args.runtime,)
+            for runtime in runtimes:
+                kit = fetch_kit(args.kit_dir, runtime=runtime, refresh=args.refresh)
+                print(f"dlssg kit ready: {kit.root} (commit {kit.dlssg_commit})")
             try:
                 sw = fetch_swapper(args.kit_dir, refresh=args.refresh)
                 print(f"DLSS5-Swapper portable ready: {sw.zip_path} ({sw.tag})")

src/dlss_combo/fetch.py

@@ -20,6 +20,58 @@
 DLSSG_REPO = "sdli1995/dlssg_for_sm86"
 RAW_BASE = f"https://raw.githubusercontent.com/{DLSSG_REPO}"
 COMMIT_API = f"https://api.github.com/repos/{DLSSG_REPO}/commits/main"
+
+# 社区镜像（代理 GitHub 官方渠道，仅作最后回退；DLSS_COMBO_MIRRORS 环境变量可覆盖，逗号分隔）
+DEFAULT_MIRRORS: tuple[str, ...] = ("https://gh-proxy.com/", "https://ghproxy.net/")
+_MIRROR_ENV = "DLSS_COMBO_MIRRORS"
+
+
+def _active_mirrors() -> tuple[str, ...]:
+    raw = os.environ.get(_MIRROR_ENV, "")
+    if not raw.strip():
+        return DEFAULT_MIRRORS
+    return tuple(m for m in (s.strip() for s in raw.split(",")) if m)
+
+
+def alternate_urls(url: str) -> list[str]:
+    """同内容的备用下载源：官方 github.com 原始文件链接优先，社区镜像殿后。
+    只处理本工具自己用的 raw.githubusercontent.com 仓库文件与 github.com release
+    资产，其余宿主一律返回空（不做任意 URL 代理）。"""
+    if url.startswith(RAW_BASE):
+        rest = url[len("https://raw.githubusercontent.com/"):]
+        owner, repo, ref, path = rest.split("/", 3)
+        alt = f"https://github.com/{owner}/{repo}/raw/{ref}/{path}"
+        return [alt] + [m + url for m in _active_mirrors()]
+    if url.startswith("https://github.com/") and "/releases/download/" in url:
+        return [m + url for m in _active_mirrors()]
+    return []
+
+
+def fetch_with_fallback(
+    url: str,
+    opener: Callable[[str], bytes] | None = None,
+) -> bytes:
+    """按「官方源 → 官方备用 → 镜像」顺序取回；全部失败时列出所有尝试过的源。"""
+    fetch = opener or _urlopen_bytes
+    attempts: list[str] = []
+    last_error: Exception | None = None
+    for candidate in [url, *alternate_urls(url)]:
+        attempts.append(candidate)
+        try:
+            return fetch(candidate)
+        except Exception as e:  # noqa: BLE001 — 每源失败换下一个，最后统一上报
+            last_error = e
+    tried = "\n  ".join(attempts)
+    raise RuntimeError(
+        f"all download sources failed for {url} — tried primary and alternate sources:\n  {tried}\n"
+        f"last error: {type(last_error).__name__}: {last_error}"
+    )
+
+
+def _urlopen_bytes(url: str) -> bytes:
+    req = urllib.request.Request(url, headers={"User-Agent": "dlss-combo/0.2"})
+    with urllib.request.urlopen(req, timeout=120) as resp:
+        return resp.read()
 ALT_NAMES = ["winmm", "d3d12", "dbghelp", "dinput8", "dxgi"]
 KIT_JSON = "kit.json"
 _SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
@@ -47,9 +99,7 @@ def kit_files(runtime: str) -> dict[str, str]:
 
 
 def _default_fetch(url: str) -> bytes:
-    req = urllib.request.Request(url, headers={"User-Agent": "dlss-combo/0.1"})
-    with urllib.request.urlopen(req, timeout=120) as resp:
-        return resp.read()
+    return fetch_with_fallback(url)
 
 
 def _resolve_commit(fetch_bytes: Callable[[str], bytes]) -> str:

tests/test_fetch_all.py

@@ -0,0 +1,46 @@
+"""`fetch --runtime all` downloads both runtimes plus the Swapper in one command."""
+import json
+
+from dlss_combo.cli import main
+from dlss_combo.fetch import KitInfo, SwapperInfo
+
+
+def test_cli_fetch_runtime_all_fetches_both_runtimes(tmp_path, monkeypatch, capsys):
+    import dlss_combo.fetch as fetch_mod
+
+    kit_calls: list[str] = []
+
+    def fake_fetch_kit(kit_dir, runtime="310.9", refresh=False, fetch_bytes=None):
+        kit_calls.append(runtime)
+        return KitInfo(root=kit_dir / "dlssg" / runtime, dlssg_commit="c" * 40, sha256={})
+
+    def fake_fetch_swapper(kit_dir, refresh=False, fetch_bytes=None):
+        return SwapperInfo(tag="v2.2.8", zip_path=kit_dir / "swapper" / "p.exe")
+
+    monkeypatch.setattr(fetch_mod, "fetch_kit", fake_fetch_kit)
+    monkeypatch.setattr(fetch_mod, "fetch_swapper", fake_fetch_swapper)
+
+    rc = main(["fetch", "--kit-dir", str(tmp_path), "--runtime", "all"])
+
+    assert rc == 0
+    assert kit_calls == ["310.9", "310.1"]
+    out = capsys.readouterr().out
+    assert "310.9" in out and "310.1" in out
+
+
+def test_cli_fetch_runtime_single_stays_single(tmp_path, monkeypatch):
+    import dlss_combo.fetch as fetch_mod
+
+    kit_calls: list[str] = []
+
+    def fake_fetch_kit(kit_dir, runtime="310.9", refresh=False, fetch_bytes=None):
+        kit_calls.append(runtime)
+        return KitInfo(root=kit_dir / "dlssg" / runtime, dlssg_commit="c" * 40, sha256={})
+
+    monkeypatch.setattr(fetch_mod, "fetch_kit", fake_fetch_kit)
+    monkeypatch.setattr(fetch_mod, "fetch_swapper",
+                        lambda k, refresh=False, fetch_bytes=None: SwapperInfo("", k))
+
+    rc = main(["fetch", "--kit-dir", str(tmp_path), "--runtime", "310.1"])
+    assert rc == 0
+    assert kit_calls == ["310.1"]

tests/test_fetch_sources.py

@@ -0,0 +1,79 @@
+"""Multi-source download fallback: official sources first, community mirrors last,
+every failure surfaces what was tried. We never redistribute upstream files — we
+only fetch them from upstream's own channels (mirrors proxy those channels)."""
+import pytest
+
+from dlss_combo.fetch import DEFAULT_MIRRORS, alternate_urls, fetch_with_fallback
+
+RAW = "https://raw.githubusercontent.com/sdli1995/dlssg_for_sm86/abc123def/version.dll"
+ASSET = (
+    "https://github.com/rakanki911/DLSS5-Swapper/releases/download/v2.2.8/"
+    "DLSS5Swapper-2.2.8-portable.exe"
+)
+
+
+def test_alternate_urls_for_raw_file_github_raw_then_mirrors():
+    alts = alternate_urls(RAW)
+    assert alts[0] == "https://github.com/sdli1995/dlssg_for_sm86/raw/abc123def/version.dll"
+    for mirror in DEFAULT_MIRRORS:
+        assert any(a.startswith(mirror) for a in alts), mirror
+    # official alternate comes before every mirror
+    for a in alts[1:]:
+        assert a.startswith(tuple(DEFAULT_MIRRORS)), a
+
+
+def test_alternate_urls_for_release_asset_mirror_prefixes_original():
+    alts = alternate_urls(ASSET)
+    assert any(a.endswith(ASSET) for a in alts)
+    assert not any("/raw/" in a for a in alts)
+
+
+def test_alternate_urls_passthrough_for_unknown_hosts():
+    assert alternate_urls("https://example.com/x.bin") == []
+
+
+def test_fetch_with_fallback_primary_first_when_reachable():
+    calls: list[str] = []
+
+    def opener(url: str) -> bytes:
+        calls.append(url)
+        return b"DATA"
+
+    assert fetch_with_fallback(RAW, opener) == b"DATA"
+    assert calls == [RAW]
+
+
+def test_fetch_with_fallback_falls_through_to_first_working_source():
+    attempts: list[str] = []
+
+    def opener(url: str) -> bytes:
+        attempts.append(url)
+        # 只按域名前缀拦截官方源；镜像 URL 虽含原始 URL 后缀，但域名不同、应放行
+        if url.startswith("https://github.com/") or url.startswith(
+            "https://raw.githubusercontent.com/"
+        ):
+            raise OSError("blocked")
+        return b"MIRROR-DATA"
+
+    assert fetch_with_fallback(RAW, opener) == b"MIRROR-DATA"
+    assert attempts[0] == RAW
+    assert len(attempts) >= 2 and attempts[1] != RAW
+
+
+def test_fetch_with_fallback_all_sources_fail_lists_everything():
+    def opener(url: str) -> bytes:
+        raise OSError("down")
+
+    with pytest.raises(RuntimeError) as ei:
+        fetch_with_fallback(RAW, opener)
+    msg = str(ei.value)
+    assert RAW in msg
+    assert "alternate" in msg
+
+
+def test_mirror_list_overridable_via_env(monkeypatch):
+    monkeypatch.setenv("DLSS_COMBO_MIRRORS", "https://m1.example/,https://m2.example/")
+    alts = alternate_urls(RAW)
+    assert any(a.startswith("https://m1.example/") for a in alts)
+    assert any(a.startswith("https://m2.example/") for a in alts)
+    assert not any(a.startswith(tuple(DEFAULT_MIRRORS)) for a in alts)

tests/test_scaffold.py

@@ -4,7 +4,7 @@
 
 
 def test_package_version_single_source():
-    assert dlss_combo.__version__ == "0.2.0"
+    assert dlss_combo.__version__ == "0.2.1"
     # 安装态（pip/PyInstaller 打包取同一字面量）与包内声明一致
     try:
         assert importlib.metadata.version("dlss-combo") == dlss_combo.__version__