refactor: use gradients without default images

Author: LevelDownRefine

README.md

@@ -35,6 +35,5 @@ tools/、deploy/   # 跨项目构建、打包、发布工具
 
 - Rust GUI：`launcher-rust.bat`；隔离演示配置加 `--demo`。
 - Python GUI：`launcher.bat`，或 `uv run python -m gui.launcher`。
-- Python 后端：`uv run --directory python-backend python -m src.headless serve --stdio`。
 
 构建与测试见 [TESTING.md](TESTING.md)，Rust 说明见 [rust-gui/README.md](rust-gui/README.md)。

docs/rust-feasibility/headless-cli.md

@@ -97,7 +97,7 @@ stdin/stdout 使用 UTF-8 JSON Lines，每行一个请求或响应，立即 flus
 
 协议层校验信封、方法白名单、参数对象及必填/允许的字段，不复制业务取值校验。
 
-壁纸来源优先级为自定义、脚本声明、助手默认；缺失自定义文件返回 gradient，不覆盖用户选择。
+壁纸来源优先级为自定义、脚本声明，无图片时使用渐变；缺失自定义文件返回 gradient，不覆盖用户选择。
 图片解码/EXIF 方向/缩放由前端完成，缓存写盘仍经 service。缓存最多 4 MiB，路径由服务生成；
 token 包含规范化源路径、大小及修改时间。视频首帧缓存沿用原 Qt 的哈希与命名。
 保存与反读独立，前端保留失败草稿，不因刷新失败再次保存。自动背景和显式编辑分别命名，

python-backend/src/utils/utils_wallpaper.py

@@ -102,7 +102,7 @@ def save_video_preview(source_path: str, cache_path: str, data: bytes) -> bool:
 
 
 def wallpaper_view(script_name: str) -> dict:
-    """按自定义、脚本声明、助手默认的顺序解析；缺失自定义文件走渐变。"""
+    """按自定义、脚本声明的顺序解析；无可用图片时使用渐变。"""
     script = get_script(script_name)
     if script is None:
         raise InvalidWallpaper("脚本已不存在，请刷新列表")
@@ -123,9 +123,7 @@ def wallpaper_view(script_name: str) -> dict:
                 candidate = os.path.join(root, relative)
                 if os.path.isfile(candidate):
                     source = candidate
-        if not source:
-            source = resolve_script_path("assets/ds.jpg")
-    source = os.path.abspath(source)
+    source = os.path.abspath(source) if source else ""
     mode = (
         "video" if os.path.splitext(source)[1].lower() in VIDEO_EXTENSIONS else "image"
     )

python-backend/tests/config/test_set_config.py

@@ -495,7 +495,10 @@ def test_unknown_process_returns_none(self):
     def test_known_process_dispatches(self):
         factory = MagicMock()
         factory.return_value.get_game_exe_path.return_value = "D:/Game/game.exe"
-        with patch.dict(set_config._CONFIGS, {"ok-ww": factory}, clear=True):
+        with (
+            patch.dict(set_config._CONFIGS, {"ok-ww": factory}, clear=True),
+            patch.object(set_config, "get_script_game_path", return_value=""),
+        ):
             self.assertEqual(set_config.get_game_exe_path("ok-ww"), "D:/Game/game.exe")
         factory.assert_called_once_with()
         factory.return_value.get_game_exe_path.assert_called_once_with()

python-backend/tests/tools/test_release_package.py

@@ -33,7 +33,7 @@ def setUp(self):
             "config/weekly.example.yml": "weekly_start: {}\n",
             "config/daily_task_list.yml": "日常: []\n",
             "config/script_resources.yml": "version: 1\nscripts: {}\n",
-            "assets/ds.jpg": "image",
+            "assets/ds.ico": "icon",
             "src/gui/qml/main.qml": "Window {}",
         }
         for name, content in self.resources.items():
@@ -165,7 +165,7 @@ def test_embedded_icons_stay_in_source_and_out_of_both_packages(self):
                 manifest = release.load_manifest(package, verify=True)
                 self.assertNotIn("assets/icons/home.png", manifest["files"])
                 self.assertFalse((package / "assets/icons").exists())
-                self.assertTrue((package / "assets/ds.jpg").is_file())
+                self.assertTrue((package / "assets/ds.ico").is_file())
                 output = self.package / f"{frontend}.zip"
                 release.archive_package(self.root, package, output)
                 with zipfile.ZipFile(output) as archive:

python-backend/tests/tools/test_rust_gui.py

@@ -16,6 +16,7 @@ def test_demo_uses_generated_config_and_static_declarations_only(self):
             root = Path(temporary)
             with patch("tools.run_rust_gui.shutil.copytree") as source_copy:
                 prepare_demo(root)
+            self.assertFalse((root / "assets/ds.jpg").exists())
             self.assertEqual(source_copy.call_count, 2)
             backend, runner = source_copy.call_args_list
             self.assertEqual(backend.args[1], root / "python-backend/src")

python-backend/tests/utils/test_utils_wallpaper.py

@@ -157,13 +157,16 @@ def setUp(self):
         )
         (self.root / "config").mkdir()
         (self.root / "assets").mkdir()
-        self.default = self.root / "assets/ds.jpg"
-        self.default.write_bytes(b"default")
+        self.image = self.root / "assets/custom.jpg"
+        self.image.write_bytes(b"custom")
 
     def test_priority_and_missing_custom_do_not_fall_back_to_another_image(self):
-        self.assertEqual(
-            wallpaper.wallpaper_view("script")["source"], str(self.default)
-        )
+        legacy = self.root / "assets/ds.jpg"
+        legacy.write_bytes(b"old bundled background")
+        state = wallpaper.wallpaper_view("script")
+        self.assertEqual(state["mode"], "gradient")
+        self.assertEqual(state["source"], "")
+        self.assertIsNone(state["token"])
         native = self.root / "native.png"
         native.write_bytes(b"native")
         self.relative.return_value = "native.png"
@@ -179,27 +182,28 @@ def test_priority_and_missing_custom_do_not_fall_back_to_another_image(self):
 
     def test_save_reset_preserve_other_script_and_source_files(self):
         save_wallpapers({"other": "unchanged.png"})
-        wallpaper.set_wallpaper("script", str(self.default))
+        wallpaper.set_wallpaper("script", str(self.image))
         self.assertEqual(
-            load_wallpapers(), {"other": "unchanged.png", "script": str(self.default)}
+            load_wallpapers(), {"other": "unchanged.png", "script": str(self.image)}
         )
         wallpaper.set_wallpaper("script", None)
         self.assertEqual(load_wallpapers(), {"other": "unchanged.png"})
-        self.assertEqual(self.default.read_bytes(), b"default")
+        self.assertEqual(self.image.read_bytes(), b"custom")
         before = (self.root / "config/wallpaper.json").read_bytes()
         for path in ("", "missing.png", str(self.root), "bad.exe"):
             with self.subTest(path=path), self.assertRaises(wallpaper.InvalidWallpaper):
                 wallpaper.set_wallpaper("script", path)
         self.assertEqual((self.root / "config/wallpaper.json").read_bytes(), before)
 
     def test_cache_uses_current_source_identity_and_rejects_stale_data(self):
+        wallpaper.set_wallpaper("script", str(self.image))
         state = wallpaper.wallpaper_view("script")
         jpeg = base64.b64encode(b"\xff\xd8test\xff\xd9").decode()
         self.assertTrue(wallpaper.save_wallpaper_cache("script", state["token"], jpeg))
         cache = Path(wallpaper.wallpaper_view("script")["cache"])
         self.assertEqual(cache.parent, self.root / "config/wallpaper_cache")
         self.assertEqual(cache.read_bytes(), b"\xff\xd8test\xff\xd9")
-        self.default.write_bytes(b"changed source")
+        self.image.write_bytes(b"changed source")
         self.assertIsNone(wallpaper.wallpaper_view("script")["cache"])
         self.assertFalse(wallpaper.save_wallpaper_cache("script", state["token"], jpeg))
         for invalid in ("not base64", base64.b64encode(b"not jpeg").decode()):

python-gui/src/gui/controllers/background.py

@@ -19,9 +19,6 @@
 
 logger = logging.getLogger(__name__)
 
-# 兜底背景：脚本未配置背景图时使用（相对项目根）
-DEFAULT_BG = "assets/ds.jpg"
-
 # 自定义壁纸缓存：用户选图时按最长边压到 WALLPAPER_MAX_SIDE 后存于
 # config/wallpaper_cache/<script_name>.jpg，resolve_bg 优先返回缓存，避免大图
 # 直接进 GPU 纹理（与 main.qml 的 sourceSize 互补）。视频首帧也复用此尺寸上限。
@@ -79,14 +76,17 @@ def background_version(self) -> int:
         return self._bg_version
 
     def resolve_bg(self, game: dict) -> str | None:
-        """返回该脚本应使用的背景路径（自定义壁纸缓存 → 自定义壁纸 → 脚本背景 → DEFAULT_BG）。
+        """返回该脚本应使用的背景路径（自定义壁纸缓存 → 自定义壁纸 → 脚本背景）。
 
         文件不存在返回 None（走渐变兜底）。
 
         Args:
             game: 当前脚本数据。
         """
-        resolved = resolve_script_path(self._wallpaper_for(game))
+        path = self._wallpaper_for(game)
+        if not path:
+            return None
+        resolved = resolve_script_path(path)
         if not os.path.isfile(resolved):
             return None
         return resolved
@@ -98,7 +98,7 @@ def _script_background(self, script_name: str) -> str:
             script_name: 脚本标识名。
 
         Returns:
-            背景图绝对路径；未适配/未声明/文件缺失 → 空字符串（交 DEFAULT_BG 兜底）。
+            背景图绝对路径；未适配/未声明/文件缺失 → 空字符串（使用渐变背景）。
         """
         rel = get_background_rel_path(script_name)
         if not rel:
@@ -110,7 +110,7 @@ def _script_background(self, script_name: str) -> str:
         return path if os.path.isfile(path) else ""
 
     def _wallpaper_for(self, game: dict) -> str:
-        """解析某脚本应使用的背景路径：定位源（自定义壁纸 → 脚本背景图 → DEFAULT_BG），
+        """解析某脚本应使用的背景路径：定位源（自定义壁纸 → 脚本背景图），
         并判定图像/视频。图像交给 _build_wallpaper_cache 确保缓存，视频直接用源路径。
         resolve_bg 负责 resolve + isfile 守卫。
 
@@ -120,7 +120,7 @@ def _wallpaper_for(self, game: dict) -> str:
         script_name = game["script_name"]
         wallpapers = self.read_wallpapers()
         if script_name not in wallpapers:
-            return self._script_background(script_name) or DEFAULT_BG
+            return self._script_background(script_name)
         src_path = wallpapers[script_name]
         if not os.path.isfile(src_path):
             return src_path  # 源图缺失：交回 resolve_bg 的 isfile 守卫，走渐变兜底

python-gui/tests/exe/test_image_formats_exe.py

@@ -21,9 +21,6 @@
     "imageformats",
 )
 
-# 与 src/gui/controllers/background.py 的 DEFAULT_BG 一致（脚本未声明背景时的兜底图）
-DEFAULT_BG = "assets/ds.jpg"
-
 # 扩展名 → 提供该格式解码能力的 Qt 图片插件。
 # png / bmp 等由 Qt 内建支持，不需要插件，故不在表内。
 _EXT_PLUGIN = {
@@ -40,12 +37,12 @@
 
 
 def _declared_backgrounds() -> dict[str, str]:
-    """收集项目声明用到的背景图：脚本标识 → 相对路径（含兜底图）。
+    """收集项目声明用到的背景图：脚本标识 → 相对路径。
 
     Returns:
-        脚本标识到背景图相对路径的映射；兜底图以键 ``__default__`` 表示。
+        脚本标识到背景图相对路径的映射。
     """
-    backgrounds = {"__default__": DEFAULT_BG}
+    backgrounds = {}
     for name in set_config._CONFIGS:
         rel = get_background_rel_path(name)
         if rel:
@@ -103,7 +100,9 @@ def test_packaged_plugins_decode_declared_backgrounds(self):
         QCoreApplication.setLibraryPaths([os.path.dirname(IMAGEFORMATS)])
 
         samples = {
-            "qjpeg.dll": os.path.join(package_dir(), DEFAULT_BG),
+            "qjpeg.dll": os.path.join(
+                PROJECT_ROOT, "python-gui", "tests", "fixtures", "background.jpg"
+            ),
             "qwebp.dll": os.path.join(
                 PROJECT_ROOT, "python-gui", "tests", "fixtures", "background.webp"
             ),