KanadeK/savedelta

# SaveDelta **改变一个细节。精准定位应用将其存储在何处。** SaveDelta 会在一次有意的更改前后捕获应用程序状态， 然后在最实用的粒度上解释 delta（差异）： - JSON 内部的 `$.player.gold: 100 → 250`； - SQLite 内部添加的 `inventory[id=3]`； - ZIP 容器内部更改的 `meta.json`； - 未知二进制存档内部的 `0x24: 64 00 00 00 → FA 00 00 00`。 它专为游戏 modder、QA 工程师、迁移测试人员、支持团队， 以及任何对未公开的本地格式进行逆向工程的人而构建。输入内容永远不会 被修改，不会上传任何文件，并且 CLI 具有**零运行时依赖**。 ## 60秒内查看效果 ``` git clone https://github.com/KanadeK/savedelta.git cd savedelta python -m pip install -e . savedelta demo savedelta-demo ``` 打开 `savedelta-demo/report.html`。生成的演示包含真实的 JSON、INI、 SQLite、ZIP 和二进制状态更改，以及重命名、添加和删除操作。 想要单个可下载文件？从最新的 Release 获取 `savedelta.pyz`： ``` python savedelta.pyz demo savedelta-demo ``` ## 真实工作流 在更改某个设置之前捕获目录： ``` savedelta snapshot "/path/to/save-folder" -o before.sdelta ``` 在游戏或应用中准确地更改一个细节，保存，然后再次捕获： ``` savedelta snapshot "/path/to/save-folder" -o after.sdelta ``` 比较快照。如果您知道可见值从 100 变成了 250， 告诉 SaveDelta；它将对可能的二进制字段和精确的结构化路径进行排名： ``` savedelta diff before.sdelta after.sdelta \ --expect 100:250 \ --format html \ --output report.html ``` 您也可以直接比较两个现有的文件或目录： ``` savedelta diff save-old.dat save-new.dat --expect 100:250 savedelta diff state-before/ state-after/ --format json > delta.json ``` ## 它能理解什么 | 输入 | 分析 | |---|---| | 文件和目录 | 添加、删除、修改、保持不变，以及内容相同的重命名检测 | | `.sdelta` 快照 | 便携式基于 ZIP 的捕获，包含哈希、生成的成员名称和可检查的清单 | | JSON | 递归的类 JSONPath 值更改和精确的预期值匹配 | | TOML | 结构化的 table、array、key、value 和类型更改 | | INI / CFG | Section 和保留大小写的 option 更改 | | 文本 | 编码检测、行统计和有界统一 diff | | SQLite | Schema 对象、table、行数、primary-key/rowid 行更改 | | ZIP | 成员添加/删除/修改、元数据，以及对更改成员的有界深度分析 | | 未知二进制 | 更改范围、大小偏移、熵、ASCII 预览、字节直方图、数字字段候选 | 数字字段定位支持有符号和无符号整数，以及小端和大端布局的 32/64 位 浮点数。每个候选都包含偏移量、类型、端序、字节表示和可解释的置信度分数。 ## 为什么还要一个 diff 工具？ 优秀的工具已经解决了这个问题的部分需求： [ImHex](https://github.com/WerWolv/ImHex) 是一个完整的十六进制工作台， [biodiff](https://github.com/8051Enthusiast/biodiff) 用于对齐两个二进制文件， [Regshot](https://github.com/Seabreg/Regshot) 用于比较 Windows 注册表 快照，而 SQLite 内置了 [`sqldiff`](https://sqlite.org/sqldiff.html) 用于数据库间的 SQL 比较。 SaveDelta 旨在填补它们之间缺失的工作流： | 功能 | SaveDelta | 十六进制编辑器 | Regshot | `sqldiff` | |---|:---:|:---:|:---:|:---:| | 一个便携的前后捕获 | ✅ | — | 仅限 Windows | — | | 混合目录格式 | ✅ | — | 面向元数据 | — | | 结构化的 JSON/TOML/INI 路径 | ✅ | — | — | — | | SQLite 行级解释 | ✅ | — | — | ✅ | | 未知二进制范围映射 | ✅ | ✅ | — | — | | “100 变成 250”字段定位器 | ✅ | 手动 | — | — | | 独立的 HTML + JSON 报告 | ✅ | 各异 | ✅ | SQL | | 零运行时依赖 | ✅ | — | 原生应用 | 原生二进制 | 目标不是取代十六进制编辑器。而是让您在打开它之前，从“某些东西改变了” 快速找到最小、最有用的候选列表。 ## 命令 ### `snapshot` ``` savedelta snapshot SOURCE -o OUTPUT.sdelta --ignore GLOB repeatable custom exclusion --no-default-ignore include lock/temp files --store disable compression --json machine-readable statistics ``` 默认排除 `.git`、`.DS_Store`、`Thumbs.db`、lock 文件和常见的 临时文件后缀。Symlink 将被跳过并报告。 ### `diff` ``` savedelta diff BEFORE AFTER --format text|json|html --output PATH --expect FROM:TO repeatable; decimal, hex, or float --max-file-bytes 64MiB --max-details 300 --max-sqlite-rows 5000 --no-renames --fail-on-change ``` 当存在差异时，`--fail-on-change` 会返回退出代码 `1`，这使 SaveDelta 可用作 CI 策略检查。预期失败和无效输入 返回 `2`。 ### `inspect` ``` savedelta inspect save.dat savedelta inspect world.db --format json ``` 在不更改输入的情况下显示格式、大小、SHA-256、熵、文本编码、可打印的二进制字符串、 SQLite 对象或 ZIP 清单。 ### `demo` ``` savedelta demo savedelta-demo savedelta demo savedelta-demo --force --json ``` 生成完全合成的数据。不捆绑任何专有游戏文件。 ## 报告 - **文本** 紧凑且适合终端。 - **JSON** 遵循 [`docs/report.schema.json`](docs/report.schema.json) 中的版本化 schema。 - **HTML** 是一个可打印、响应式、独立的文件，包含字节热力图、 结构化表、SQLite 行和预期值候选。 HTML 渲染器会转义每个派生自输入的字符串，没有 JavaScript 或 网络资源，并应用严格的 Content Security Policy。 ## 安全与限制 对于分析的输入，SaveDelta 是只读的。它将 SQLite 字节复制 到临时文件，并以仅查询模式打开它们；它在内存中检查 ZIP 成员 而无需解压；快照使用生成的存档成员名称，因此 原始路径不会成为提取路径。 默认有意限制了昂贵的操作： - 每个更改文件 64 MiB 的深度分析限制； - 每个 SQLite table 5,000 行扫描限制； - 20,000 个 ZIP 条目和 512 MiB 的扩展元数据预算； - 2 MiB 和 20 个成员的嵌套 ZIP 分析限制； - 每个更改文件 300 个详细项目。 仅对您信任的文件增加限制。有关完整的 威胁模型，请参阅 [`docs/SECURITY_MODEL.md`](docs/SECURITY_MODEL.md)。 ## 开发与验收 ``` python -m pip install -e . python scripts/check.py python -m unittest discover -s tests -v python scripts/smoke_test.py python scripts/build_zipapp.py python dist/savedelta.pyz --version python -m pip wheel . --no-deps -w dist/wheel ``` 验收路径有意独立于外部服务和 第三方 Python 包。 如果检查失败，请使用 [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md) 中的确切修复流程：重现最小的 失败命令，保留输入，添加回归测试，修复有界 分析器，并重新运行整个验收序列。 ## 项目结构图 ``` src/savedelta/ source.py live files and portable snapshot loading snapshot.py atomic .sdelta creation compare.py file pairing, rename detection, analyzer dispatch structured.py JSON/TOML/INI structural changes sqlitediff.py read-only schema and row comparison zipdiff.py bounded archive member analysis binary.py byte ranges, entropy, numeric field location report.py text, JSON, and self-contained HTML cli.py snapshot, diff, inspect, and demo commands ``` 设计细节位于 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) 中。 ## 路线图 - 针对社区拥有的存档格式的可插拔 parser； - 针对偏移 block 的内容定义的二进制对齐； - 可选的 Windows 注册表捕获适配器； - 带有显式验证和备份的补丁导出； - 报告到 ImHex 的书签转换； - 签名快照和可重现的捕获模式。 有关范围明确的里程碑，请参阅 [`docs/ROADMAP.md`](docs/ROADMAP.md)。 ## 贡献 特别欢迎合成测试夹具、开放格式的 parser、Windows/macOS 测试和报告 无障碍改进。在打开 pull request 之前，请阅读 [`CONTRIBUTING.md`](CONTRIBUTING.md)。 ## 许可证 [MIT](LICENSE) © 2026 KanadeK

标签：Homebrew安装, 多模态安全, 文档结构分析, 逆向工具