## 功能描述 将 MemSnapDump `v0.1.0`(SHA `87ea207372e0985790e1a28dab499dccf3c3b9a4`)的完整运行能力收编到 `pt-snap-cli`,由 `pt_snap_cli.snapshot` 作为一等领域模块维护。 本任务需要: - 将当前 `pt_snap_cli.vendor.memsnapdump` 闭包迁移为 first-party 代码; - 补入当前 vendor 闭包缺失的 replay-aware snapshot slicing 能力; - 新增正式产品命令 `pt-snap split`; - 迁入有效的上游测试、fixtures 和中英文文档; - 删除旧 vendor 目录、vendor lint 排除和不准确的 byte-identical attribution; - 不保留 `memsnapdump` package、console script、module entrypoint 或兼容 shim。 本 Issue 是 #74 的阻塞子任务。完成收编后,#74 的 replay 性能优化应基于新的 `pt_snap_cli.snapshot` 命名空间继续实施。 ## 使用场景 MemSnapDump 将停止独立演进并关闭公开仓库。当前 `pt-snap-cli` 只包含最小 vendor 闭包,缺少切片能力、完整测试和准确的治理信息;同时 vendor 树已经包含 SQLite PRAGMA 和查询索引等本地修改,不再符合“无本地修改、与固定 SHA 字节一致”的声明。 如果继续直接在 vendor 树实施 #74,会进一步扩大代码归属、测试覆盖和后续维护风险。先完成一等模块收编,可以建立清晰的所有权、质量门禁和性能优化基线。 ## 期望的实现方式 - 新建 `src/pt_snap_cli/snapshot/`,首阶段保留原 `base/`、`simulate/`、`tools/`、`util/` 内部结构。 - 保留现有 `pt-snap import` 的缓存、metadata、源文件变化检测、临时数据库和原子替换语义。 - 新增 `SplitService` 和 `pt-snap split`,输出可再次 replay 的 pickle/JSON 切片。 - 从上游固定 SHA 补入 `tools/slice_dump`,但不迁入旧 Typer/argparse CLI 和独立 packaging。 - 迁入上游有效行为测试和 5 个真实 snapshot fixtures;删除只验证旧包入口的测试。 - 新增 `PROVENANCE.md`,记录原仓库、tag、固定 SHA、MIT 权利确认和本地修改。 - 将 snapshot 模块纳入 Ruff、Black 和正常 CI 门禁。 - 本阶段只做行为等价迁移,不顺带修复 allocator、数据库生命周期或参数校验问题。 ## 示例 ```shell pt-snap import snapshot.pkl pt-snap split snapshot.pkl --device 0 --slices 4 --max-entries 15000 --output ./slices ``` ## 参考资源 - 父 Issue:#74 - 原仓库:https://github.com/codeasier/MemSnapDump - 固定版本:https://github.com/codeasier/MemSnapDump/tree/87ea207372e0985790e1a28dab499dccf3c3b9a4 ## 验收标准 - [ ] `src/pt_snap_cli/vendor/memsnapdump` 被完整移除 - [ ] 完整运行能力迁入 `pt_snap_cli.snapshot` - [ ] 不提供旧 `memsnapdump` package、命令或 Python API 兼容层 - [ ] `pt-snap import` 的现有行为和数据库契约不回退 - [ ] 新增 `pt-snap split`,pickle/JSON 切片可再次完整 replay - [ ] 普通、expandable、empty-cache、workspace 和 multi-device 行为通过测试 - [ ] 有效上游测试与 5 个 fixtures 完成迁移 - [ ] 中英文 replay、split、数据库文档完成整合,并提示 pickle 仅用于可信输入 - [ ] provenance、MIT 许可和本地修改记录准确 - [ ] `pytest`、`ruff check .`、`black --check .` 通过 - [ ] 构建 wheel 后,`pt-snap import` 与 `pt-snap split` smoke test 通过 - [ ] #74 benchmark harness 可在新命名空间继续运行 ## 非目标 - 不在本任务中实施 #74 的 block detach 性能优化 - 不修复 strict format、正数参数校验或数据库显式 close 等已知问题 - 不导入 MemSnapDump 的 83 个 Git 提交历史
Activity
codeasier commentedon Jul 29, 2026
Verdict: 实质合理,证据充分。
实测确认
1. vendor 已不再"字节一致"于固定 SHA
对照上游
87ea207拉取对应提交,src/pt_snap_cli/vendor/memsnapdump/tools/adaptors/database/snapshot_db.py与上游存在未在 ATTRIBUTION.md 中声明的本地改动:__init__内追加PRAGMA journal_mode = MEMORY、PRAGMA synchronous = OFF、PRAGMA cache_size = -65536create_trace_entry_table/create_block_table各加了一组create_index(allocated/active/reserved、alloc_event_id/free_event_id/size)vendor/memsnapdump/ATTRIBUTION.md当前明文写"None. The vendored code is intended to be byte-identical",与现状不符——这正是本 Issue 要消解的 attribution 漂移。2. 闭包确实缺 replay-aware slicing 能力
上游同 SHA 下还有
src/memsnapdump/tools/slice_dump/{__init__.py,dump.py,hooker.py}与src/memsnapdump/tools/split.py,vendor 闭包内完全没有这两条路径。Issue 中"补入tools/slice_dump,但不迁入旧 Typer/argparse CLI 和独立 packaging"的范围与上游结构对得上——上游cli.py、tools/dump2db.py被显式排除。3. fixtures 与 vendor 测试目前不在仓内
tests/fixtures/snapshots/仅 4 个:memory0.pickle、snapshot_16k_94layers.pickle、snapshot_with_empty_cache.pkl、snapshot_with_multi_devices.pkl。Issue 验收要求的 5 个真实 fixtures(普通/expandable/empty-cache/workspace/multi-device)尚未到齐。tests/下没有tools/、base/、simulate/、util/子目录,无任何 vendor 测试文件;上游对应位置有tests/tools/test_slice_dump*.py等。4.
pt-snap import契约保护到位core/import_service.py+core/snapshot_import_backend.py是稳定适配层(缓存、SHA 校验、原子替换、finalize_temp_db)。把run_dump_to_db从pt_snap_cli.vendor.memsnapdump.tools.adaptors.snapshot2db改到pt_snap_cli.snapshot...是纯路径重写,行为等价迁移可行;Issue 也明确"不修复 strict format、正数参数校验或数据库显式 close",边界合理。5. 与 #74 的依赖顺序成立
#74 的三处优化都打在
vendor/memsnapdump/simulate/{snapshot_mutator,snapshot_lookup,simulated_caching_allocator}.py上;迁出 vendor 后这些文件不再受"字节一致"约束,#74 的 PRAGMA/索引式改动也不会再被 ATTRIBUTION.md 误标。边界核对
Issue 中"不提供旧
memsnapdumppackage、命令或 Python API 兼容层"是有意为之——pyproject.toml 里pt-snap是唯一 console script,memsnapdump这个名字从未在 API 表面出现过,无需保留兼容层。建议(仅 PR 描述层面,不改代码)
diff -ru中 PRAGMA + 索引那段(~14 行),让 reviewer 一眼看出 attribution 在被修复而非新引入差异;PROVENANCE.md写明"继承自pt_snap_cli.vendor.memsnapdump的本地修改"具体是哪几条(journal_mode/synchronous/cache_size+ 6 条create_index),避免 [FEATURE] 优化 import 路径数据结构,消除 segment/blocks 操作的 O(N²) 退化(子任务 #72-2) #74 的 SortedList 优化后被误读为上游漂移。codeasier commentedon Aug 5, 2026
Superseded by #81 (merged in
717e3ca).PR #81 已合入 main,对照本 Issue 的 12 条验收标准逐项核对均满足:
src/pt_snap_cli/vendor/memsnapdump已完整移除,运行能力迁入pt_snap_cli.snapshot一等模块memsnapdumppackage、命令或兼容层pt-snap import行为通过tests/core/test_import_service.py验证未回退pt-snap split(core/split_service.py+ CLI),切片可再次 replay,由tests/core/test_split_service.py覆盖tests/snapshot/下 14 个测试文件 + 5 类 fixtures 验证docs/{en,zh}/splitting.md+ quickstart 双语文档整合,含 pickle 仅用于可信输入提示src/pt_snap_cli/snapshot/PROVENANCE.md+docs/legal/memsnapdump-mit-relicensing.md+ provenance CI 脚本记录准确pytest/ruff check ./black --check .通过(PR 描述:565 passed, 1 xfail)benchmarks/baseline_import.py已建立 first-party 命名空间基线,[FEATURE] 优化 import 路径数据结构,消除 segment/blocks 操作的 O(N²) 退化(子任务 #72-2) #74 可基于此继续实施PR review 提出的 3 条 finding 已由后续 fix commit(
d00053d、fcaabda)处理。本 Issue 作为 #74 的阻塞子任务已完成,关闭以解锁 #74 后续推进。