mufanq/sts2-save-rebuild
GitHub: mufanq/sts2-save-rebuild
一款用于从历史文件重建《Slay the Spire 2》可加载存档并绕过 Steam Cloud 删除机制的逆向工具。
Stars: 0 | Forks: 0
# sts2-save-rebuild
[](https://www.python.org/downloads/)
[](LICENSE)
[](#)
用于重构可加载的 `current_run.save` / `current_run_mp.save` 的工具包
适用于《Slay the Spire 2》，基于游戏已完成对局的历史文件生成可加载的存档，配合必要的 Steam Cloud 技巧实现实际部署。
此工具最初源于一次多人联机死亡导致未完成进度被抹除的救援任务。游戏会为每个完成的运行保留 `.run` 历史记录，但在死亡时会删除活动存档。事实证明，配合一个已知良好的模板存档，历史记录本身已足够重建一个接近死亡前状态的可加载存档。
## ⚠️ 阅读前须知 — 操作前务必了解
以下内容均源于实际踩坑经验，若跳过可能导致数小时损失。
### Steam Cloud 并非可靠帮手
1. **游戏内进程级云同步会抹除未在 Steam 云清单中的本地存档**。`CloudSaveStore.SyncCloudToLocalInternal` 在每次启动时运行；“不在远程 → 删除本地”的分支在菜单渲染前就已执行。简单的“将重建文件放入存档文件夹”会静默失败。
2. **仅 Steam 离线模式无法阻止此行为**。Steam 的 `ISteamRemoteStorage` API 使用本地云缓存，无论在线或离线均返回相同结果。必须使用 (a) 应用级云禁用或 (b) 欺骗 Steam 清单，详见 `docs/steam-cloud-bypass.md`。
3. **在游戏属性中禁用云需要完全重启 Steam**。许多人以为禁用了云，但 Steam 未重新加载设置仍会向游戏报告 `app: True`。请完全退出托盘图标中的 Steam（不只是关闭窗口），并确认任务管理器中 `steam.exe` 已消失后再重新启动。
4. **死亡会同步清除云存档**。游戏调用 `DeleteCurrentMultiplayerRun()` 会同时删除本地与云端副本。云不是防死亡的备份，只有 `history/*.run` 文件得以保留。
### SSD 与 TRIM 的现实
5. **在启用 TRIM 的现代 NVMe SSD 上，删除几分钟后的文件实质上不可恢复**。Samsung 990 PRO 的垃圾回收会积极清零 TRIM 块。若删除已发生数小时，请直接采用下方的历史重建路径，不要浪费时间使用 Recuva/PhotoRec。
### 不要破坏可用存档
6. **运行任何操作前请先创建快照**。`recover_mp_run.py` 会自动执行冷备份，但若手动使用底层脚本，请先运行 `scripts/snapshot.py`。`--apply` 标志会覆盖文件；请先备份。
7. **若游戏弹出“报告错误”按钮，请勿点击**。应点击“忽略 / 无视”。报告可能包含你的重建存档，开发者可识别为手动编辑。
### 作用范围
8. **重建的存档拥有全新的 RNG 状态**。即将出现的商店、卡牌奖励、随机事件将与原进程不同；等级、种子、牌组、遗物、生命值、金币、地图位置等得以保留 —— “下一随机抽取”之后的结果属于平行宇宙。若需字节级一致的重放，需要无头 STS2 模拟器，这不在本工具范围内。
8. **多人客户端无法恢复任何内容**。仅主机写入 `current_run_mp.save`；若你只是联机参与者，存档仅存在于主机本地。
10. **持续保护建议安装 [Rewind](https://www.nexusmods.com/slaythespire2/mods/211)**。该工具是事后救援手段，而 Rewind 模组维护独立的检查点存储，完全绕过死亡清除流程，更适合日常保护。
## 你能找回什么
| 字段 | 是否可恢复 |
|---|---|
| 角色、牌组、遗物、药水 | 是 |
| 生命值、金币、最大生命值 | 是（来自死亡前最后的地图点统计数据） |
| 升阶、修饰符、游戏模式、种子 | 是 |
| 地图位置、路径、已遇事件 | 是（通过 `map_point_history`） |
| 下一商店/抽取的 RNG 状态 | **否** — 平行宇宙 |
| 共享遗物池进度 | 否 |
| 地图涂鸦（随手画） | 否 |
| 中途战斗 / 事件中状态 | 否 |
重建的存档将在地图点边界处恢复（默认死亡遭遇前）。运气线字段将被重置，你不会获得与原进程完全相同的商店报价或卡牌抽取，但装备、进度与位置得以保留。
## 目录结构
```
sts2_save/ library
paths.py locate saves / cloud mirror / vdf on disk
rebuild.py rebuild SerializableRun from RunHistory
validate.py schema match against a known-good template
steam_vdf.py inject entries into remotecache.vdf
snapshot.py cold backup helper
cli/ thin wrappers wired to `sts2-*` entry points
docs/ technical write-ups
examples/ scenario walkthroughs
.claude/skills/ Claude Code skill definition
pyproject.toml console_scripts + build metadata
```
## 系统要求
- Windows（Steam 存档路径为 Windows 专属）
- Python 3.10+
- 核心工具包无需 Python 依赖
可选依赖：
- `pyautogui` + `pygetwindow` 用于 UI 启动测试（非重建必需）
## 安装
```
git clone https://github.com/mufanq/sts2-save-rebuild
cd sts2-save-rebuild
pip install .
```
此命令将安装五个控制台命令：
| 命令 | 用途 |
|---|---|
| `sts2-recover-mp` | 端到端流程（推荐） |
| `sts2-rebuild` | 单个存档重建 |
| `sts2-validate` | 对模板进行架构校验 |
| `sts2-snapshot` | 冷备份 |
| `sts2-inject-vdf` | 注入条目到 Steam 云清单 |
## 快速上手 — 今晚恢复多人联机死亡
```
# 1. 完全退出 Steam（托盘图标 -> 退出 — 不要仅关闭窗口）
# 2. 运行端到端流水线
sts2-recover-mp --backup-dir "C:/my-sts2-backups"
# 3. 以离线模式启动 Steam，启动游戏，打开多人游戏。
# “继续”按钮应出现并加载您的死亡前状态。
```
执行顺序如下：
1. 将整个存档树冷备份到 `--backup-dir`。
2. 选择最新的 `history/*.run` 作为源文件。
3. 选择一个多人联机模板（优先使用活动的 `current_run_mp.save`，其次为最新的 `*.VAL.corrupt` 变体，最后 fallback 到单人存档）。
4. 调用 `rebuild` 并传入 `--snapshot-offset 1`（表示死亡前状态）。
5. 对重建后的 JSON 结构进行静态校验，确保符合模板。
6. 将重建文件镜像到 Steam 的 `userdata/.../remote/` 目录并保持相同时间戳。
7. 注入条目到 `remotecache.vdf`，使 Steam 的云与本地同步逻辑认为该文件已在云中，从而跳过删除分支。
## 为何需要这些 Steam Cloud 操作？
游戏在启动时拥有自己的进程级云同步逻辑（`CloudSaveStore.SyncCloudToLocalInternal`）。若其发现本地文件不在 Steam 云清单中，会在每次启动时 **删除该文件及其 `.backup`**。仅将重建文件放入存档文件夹不足以应对下一次启动。
社区尝试过的绕过方式：
| 方法 | 是否有效 |
|---|---|
| 取消“保持存档在 Steam 云中” + 完全重启 Steam | **是** — 最干净的做法，但必须完全退出 Steam |
| Steam 客户端“离线模式” | **否** — 游戏内进程同步仍会运行 |
| 防火墙阻止 Steam | 不稳定；Steam 可能拒绝启动 |
| 编辑 `remotecache.vdf` 使 Steam 报告文件已在云中 | **是**，且为本工具所采用。必须配合离线模式以阻止 Steam 与 Valve 服务器校验 |
详见 `docs/steam-cloud-bypass.md` 获取完整机制。
## 手动使用（跳过一键流程）
```
# 仅重建，在模板旁边写入下一步
sts2-rebuild `
--history "$env:APPDATA\SlayTheSpire2\steam\\modded\profile1\saves\history\1776390784.run" `
--template "$env:APPDATA\SlayTheSpire2\steam\\modded\profile1\saves\current_run_mp.save" `
--snapshot-offset 1 `
--output "./rebuilt.save"
# 验证形状是否匹配模板
sts2-validate `
--template "$env:APPDATA\SlayTheSpire2\...\current_run_mp.save" `
--rebuilt "./rebuilt.save"
# 注入到 Steam 的云清单（Steam 必须完全退出）
sts2-inject-vdf `
--vdf "C:\Program Files (x86)\Steam\userdata\\2868840\remotecache.vdf" `
--file-local "$env:APPDATA\SlayTheSpire2\...\current_run_mp.save" `
--relative-key "modded/profile1/saves/current_run_mp.save" `
--with-backup
```
未安装也可直接运行模块：
```
python -m sts2_save.cli.rebuild --history ... --template ...
```
## 安全性
没有任何操作是“魔法可逆”的，但工具已尽力保护数据：
- `sts2-recover-mp` 在修改前始终执行冷备份。
- `sts2-inject-vdf` 会在原文件旁写入带时间戳的 `.bak_` 备份。
- `sts2-rebuild` 默认输出到新文件；`--apply` 模式会将原文件移至 `.pre_rebuild_`。
你随时可以将备份放回原目录。若游戏拒绝加载重建存档，它通常会重命名为 `*.MIG.corrupt` 或 `*.VAL.corrupt` —— 两者均为合法 JSON，可与模板比对以诊断问题。
## 重要注意事项
- **TRIM 后无法恢复。** 若你的存档在数小时前被删除，现代 SSD 上的不可恢复数据意味着此工具无效；该工具从 `history/*.run` 重建，而游戏会保留这些文件。
- **架构迁移。** 游戏的 `SerializableRun` 架构从 v9 迁移至 v16。`rebuild` 使用模板绕过迁移以通过严格 JSON 反序列化。若模板版本远低于当前游戏版本，请尝试更新模板。
- **多人联机专用。** 重建的多人存档通过 `CanonicalizeSave`，玩家 `net_id` 被保留；你的联机伙伴需重新加入你主持的房间 —— 存档仅携带最终队伍状态。
- **这是反向工程的变通方案，非受支持路径。** 不要用于破坏他人游戏体验，也需预期未来更新可能破坏架构假设。
## 在 Claude / Claude Code 中使用
包含一个技能定义文件 `.claude/skills/sts2-save-rebuild.md`。
若使用 Claude Code，请将该文件复制到项目中的 `.claude/skills/` 目录（或软链接整个仓库），助手即可根据“丢失存档”或“如何恢复多人联机存档”等请求识别并调用工具包。
技能文件编码了完整决策树：单人 vs 多人 vs 客户端、SSD-TRIM 考量、Steam Cloud 前提条件（必须完全退出 Steam）以及部署后说明（离线模式启动）。同时列出了重建失败时的日志模式与重命名后缀及其根本原因映射。
## 许可与署名
- 本仓库代码采用 MIT 许可。
- Slay the Spire 2 © Mega Crit Games。本工具不传播任何游戏资产、代码或反编译输出，仅读取玩家拥有的存档文件并生成符合相同 JSON 架构的替换文件。若未拥有游戏，请勿使用本工具。
## 链接
- Rewind 模组（Nexus #211） — 更长期的防护：https://www.nexusmods.com/slaythespire2/mods/211
- STS2Saves 模组（Nexus #459） — 存档管理：https://www.nexusmods.com/slaythespire2/mods/459
- ModSmith 的反编译指南（若需阅读源码）：https://cpimhoff.github.io/Sts2-ModSmith/docs/setup/decompile.html
标签：Python 3.10, Python 工具, run history, savefile, Slay the Spire 2, Steam Cloud 绕过, Steam 同步绕过, 云资产清单, 历史文件恢复, 数据重构, 文件重建, 本地缓存, 游戏存档修复, 游戏存档管理, 游戏开发, 游戏数据恢复, 逆向工具, 逆向工程