fix(workshop): 同名替换失败回滚旧音频；建目录失败如实上报（Codex P2 ×2）

## 1. 同扩展名替换：manifest 写失败会留下「新音频 + 旧 manifest」

上一版把「删」放到最后之后还剩一个窗口：同扩展名替换时文件名不变，
os.replace 会把旧音频原地顶掉，而 manifest 还没写。第 2 步失败的话盘上是新音频配
旧 manifest —— 偏偏文件名没变，_resolve_workshop_voice_reference 认为这对有效，
于是新音频配旧的 prefix / 语言 / display_name / provider，而用户收到的是 500。

我上一轮判断过这个残留并接受了（「两个文件都在，能解析」），判轻了：静默的不一致
比响亮的失败糟得多 —— 用户以为什么都没变，实际参考语音已经被换掉了。

修法：顶上去之前先把旧音频原子挪到 `<tmp>.bak`，任何一步失败就挪回原位（旧 manifest
本来就没动过），成功则在 finally 里删掉备份。回到「要么整对换掉、要么整对不动」。

## 2. 建目录失败被吞掉，接口照样报 success

ensure_workshop_folder_exists 把创建失败（只读盘、权限不足）吞成返回 False，而这里
忽略了返回值。配置确实存下来了，所以 success 仍然是 True —— 但不能因此告诉用户目录
也准备好了，那条路径接下来根本用不了。两件事分开报：新增 folder_ready，为 False 时
附一句 warning。

改响应形状是安全的：全仓库搜不到 POST /api/steam/workshop/config 的任何调用方
（与它此前是死代码、没人发现的事实一致）。

## 验证

- 去掉备份/回滚 → test_a_same_extension_replace_rolls_back_when_the_manifest_fails 红
- 忽略 ensure 返回值 → test_a_folder_that_cannot_be_created_is_reported 红
- 另加 test_a_successful_replace_leaves_no_backup_behind：成功路径不许留 .tmp/.bak
- 全量 tests/unit：8946 passed, 45 skipped；守卫 exit 0；docstring 门 exit 0

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: wehos

main_routers/workshop_router/config_files.py

@@ -65,7 +65,7 @@ async def save_workshop_config_api(config_data: dict):
         # 导入与get_workshop_config相同路径的函数，保持一致性
         from utils.workshop_utils import load_workshop_config, save_workshop_config, ensure_workshop_folder_exists
 
-        def _apply_config_transaction() -> dict:
+        def _apply_config_transaction() -> tuple[dict, bool | None]:
             with _WORKSHOP_CONFIG_TRANSACTION_LOCK:
                 # 读也放进锁里：不然两个请求各自读到同一份旧配置、各写各的合并结果，
                 # 后写的那次会把前一次的字段整份盖掉。
@@ -74,16 +74,25 @@ def _apply_config_transaction() -> dict:
                     if key in config_data:
                         merged[key] = config_data[key]
                 save_workshop_config(merged)
+                folder_ready: bool | None = None
                 if merged.get('auto_create_folder', True):
                     # 优先使用user_mod_folder，如果没有则使用default_workshop_folder
                     folder_path = merged.get('user_mod_folder') or merged.get('default_workshop_folder')
                     if folder_path:
-                        ensure_workshop_folder_exists(folder_path)
-                return merged
-
-        workshop_config_data = await asyncio.to_thread(_apply_config_transaction)
-
-        return {"success": True, "config": workshop_config_data}
+                        folder_ready = bool(ensure_workshop_folder_exists(folder_path))
+                return merged, folder_ready
+
+        workshop_config_data, folder_ready = await asyncio.to_thread(_apply_config_transaction)
+
+        # ensure_workshop_folder_exists 把创建失败（只读盘、权限不足）吞成返回 False。
+        # 配置确实存下来了，所以 success 仍然是 True —— 但不能因此告诉用户目录也准备
+        # 好了：那条路径接下来根本用不了。两件事分开报。
+        response = {"success": True, "config": workshop_config_data}
+        if folder_ready is not None:
+            response["folder_ready"] = folder_ready
+            if not folder_ready:
+                response["warning"] = "配置已保存，但指定的工坊目录无法创建（路径只读或权限不足）"
+        return response
     except Exception as e:
         logger.error(f"保存创意工坊配置失败: {str(e)}")
         return {"success": False, "error": str(e)}

main_routers/workshop_router/voice_refs.py

@@ -68,22 +68,40 @@ def _replace_voice_reference(
     destroying a reference the user cannot get back.
     """
     with voice_reference_lock(content_folder):
-        # 1) 新音频先落到同目录的 tmp，fsync 之后再 os.replace 上去。
-        #    失败的话旧的一对纹丝不动 —— 这一步之前不删任何东西。
+        # 1) 新音频先落到同目录的 tmp，fsync 之后再 os.replace 顶上去。
         fd, temp_audio = tempfile.mkstemp(dir=content_folder, suffix='.tmp')
+        backup_audio = None
         try:
             with os.fdopen(fd, 'wb') as f:
                 f.write(audio_bytes)
                 f.flush()
                 os.fsync(f.fileno())
+
+            # 同扩展名替换时，os.replace 会把旧音频原地顶掉 —— 而 manifest 还没写。
+            # 万一第 2 步失败，盘上就是「新音频 + 旧 manifest」，偏偏文件名没变，
+            # _resolve_workshop_voice_reference 会认为这对有效：新音频配旧的
+            # prefix / 语言 / display_name / provider，而用户收到的是 500。静默的
+            # 不一致比响亮的失败糟得多，所以先把旧音频原子挪到一边留作回滚。
+            if os.path.exists(audio_path):
+                backup_audio = f'{temp_audio}.bak'
+                os.replace(audio_path, backup_audio)
+
             os.replace(temp_audio, audio_path)
+
+            # 2) manifest 也是原子替换。走到这里新的一对才算完整可用。
+            atomic_write_json(manifest_path, manifest, ensure_ascii=False, indent=2)
         except BaseException:
+            # 回滚到进来时的状态：旧音频挪回原位，旧 manifest 本来就没动过。
+            if backup_audio is not None and os.path.exists(backup_audio):
+                with suppress(OSError):
+                    os.replace(backup_audio, audio_path)
             with suppress(OSError):
                 os.remove(temp_audio)
             raise
-
-        # 2) manifest 也是原子替换。走到这里新的一对已经完整可用。
-        atomic_write_json(manifest_path, manifest, ensure_ascii=False, indent=2)
+        finally:
+            if backup_audio is not None:
+                with suppress(OSError):
+                    os.remove(backup_audio)
 
         # 3) 最后才清掉「换了扩展名」留下的旧音频（mp3 → wav 这种）。同名的那次
         #    已经被上面的 os.replace 顶掉了。删失败只是留个孤儿文件，不影响这对

tests/unit/test_workshop_cloudsave_disabled.py

@@ -177,3 +177,45 @@ def _ensure(folder):
     assert a_ensures == ["ensure:A:auto=True"], (
         f"A 的 ensure 读到了别人的配置：{order}"
     )
+
+
+@pytest.mark.asyncio
+async def test_a_folder_that_cannot_be_created_is_reported(monkeypatch):
+    """Saving a read-only path must not be reported as fully successful.
+
+    ``ensure_workshop_folder_exists`` swallows the creation failure and returns
+    False. The config itself did persist, so ``success`` stays True — but the
+    response has to say the folder is not usable, or the user is told an
+    unusable workshop path was set up fine.
+    """
+    from main_routers.workshop_router import config_files
+    from utils import workshop_utils
+
+    monkeypatch.setattr(workshop_utils, "load_workshop_config", lambda: {})
+    monkeypatch.setattr(workshop_utils, "save_workshop_config", lambda cfg: None)
+    monkeypatch.setattr(workshop_utils, "ensure_workshop_folder_exists", lambda folder: False)
+
+    result = await config_files.save_workshop_config_api(
+        {"user_mod_folder": "R:/read-only", "auto_create_folder": True}
+    )
+
+    assert result["success"] is True, "配置本身确实存下来了"
+    assert result["folder_ready"] is False
+    assert "warning" in result
+
+
+@pytest.mark.asyncio
+async def test_a_created_folder_reports_ready(monkeypatch):
+    from main_routers.workshop_router import config_files
+    from utils import workshop_utils
+
+    monkeypatch.setattr(workshop_utils, "load_workshop_config", lambda: {})
+    monkeypatch.setattr(workshop_utils, "save_workshop_config", lambda cfg: None)
+    monkeypatch.setattr(workshop_utils, "ensure_workshop_folder_exists", lambda folder: True)
+
+    result = await config_files.save_workshop_config_api(
+        {"user_mod_folder": "C:/mods", "auto_create_folder": True}
+    )
+
+    assert result["folder_ready"] is True
+    assert "warning" not in result

tests/unit/test_workshop_voice_refs.py

@@ -406,3 +406,67 @@ def _boom(src, dst):
     assert (tmp_path / "voice_sample.mp3").read_bytes() == b"old-audio"
     leftovers = [p.name for p in tmp_path.iterdir() if p.name.endswith(".tmp")]
     assert leftovers == [], f"失败路径留下了暂存文件：{leftovers}"
+
+
+def test_a_same_extension_replace_rolls_back_when_the_manifest_fails(tmp_path, monkeypatch):
+    """New audio must not survive under the old manifest.
+
+    Replacing a .wav with another .wav reuses the filename, so os.replace
+    overwrites the old audio before the manifest is written. If the manifest
+    write then fails, resolution still finds a "valid" pair — new audio wearing
+    the old prefix / language / provider — while the upload answered 500. A
+    silent mismatch is worse than a loud failure, so the previous audio is
+    staged aside and restored.
+    """
+    from main_routers.workshop_router import voice_refs
+
+    (tmp_path / "voice_sample.wav").write_bytes(b"old-audio")
+    (tmp_path / WORKSHOP_VOICE_MANIFEST_NAME).write_text(
+        json.dumps({"version": 1, "reference_audio": "voice_sample.wav", "prefix": "old"}),
+        encoding="utf-8",
+    )
+
+    def _boom(*args, **kwargs):
+        raise OSError(28, "No space left on device")
+
+    monkeypatch.setattr(voice_refs, "atomic_write_json", _boom)
+
+    with pytest.raises(OSError):
+        voice_refs._replace_voice_reference(
+            str(tmp_path),
+            str(tmp_path / "voice_sample.wav"),
+            b"new-audio",
+            str(tmp_path / WORKSHOP_VOICE_MANIFEST_NAME),
+            {"version": 1, "reference_audio": "voice_sample.wav", "prefix": "new"},
+        )
+
+    assert (tmp_path / "voice_sample.wav").read_bytes() == b"old-audio", (
+        "新音频留在了旧 manifest 底下——同名替换失败后必须回滚"
+    )
+    assert _manifest(tmp_path)["prefix"] == "old"
+    leftovers = sorted(p.name for p in tmp_path.iterdir() if ".tmp" in p.name)
+    assert leftovers == [], f"失败路径留下了暂存/备份文件：{leftovers}"
+
+
+def test_a_successful_replace_leaves_no_backup_behind(tmp_path):
+    """The staged backup must not outlive a successful swap."""
+    from main_routers.workshop_router import voice_refs
+
+    (tmp_path / "voice_sample.wav").write_bytes(b"old-audio")
+    (tmp_path / WORKSHOP_VOICE_MANIFEST_NAME).write_text(
+        json.dumps({"version": 1, "reference_audio": "voice_sample.wav", "prefix": "old"}),
+        encoding="utf-8",
+    )
+
+    voice_refs._replace_voice_reference(
+        str(tmp_path),
+        str(tmp_path / "voice_sample.wav"),
+        b"new-audio",
+        str(tmp_path / WORKSHOP_VOICE_MANIFEST_NAME),
+        {"version": 1, "reference_audio": "voice_sample.wav", "prefix": "new"},
+    )
+
+    assert (tmp_path / "voice_sample.wav").read_bytes() == b"new-audio"
+    assert _manifest(tmp_path)["prefix"] == "new"
+    leftovers = sorted(p.name for p in tmp_path.iterdir() if ".tmp" in p.name)
+    assert leftovers == [], f"成功路径留下了暂存/备份文件：{leftovers}"