父 roadmap:#197 实施阶段:P0 依赖:无前置子任务 范围:固定 manifest、SQLite 布局、事件与 block 身份语义,提供生产端与读取端共用的校验合同。 ## 功能描述 为分片 SnapshotDB 定义可版本化、可测试的产物协议,同时明确 pt-snap 原生增强格式与当前 msinsight 兼容格式的边界。 ## 使用场景 同一份分片产物需要在 pt-snap 与 msinsight 间交换。仅按事件数拆 SQLite 文件,无法保证目录发现、堆栈读取、缓存复用和生命周期语义一致。 ## 期望的实现方式 - 固定兼容布局:`<原始 snapshot 路径>.msinsight/manifest.json`、`device_<id>/slice_<index:05d>.db`。 - 记录并校验 manifest `schemaVersion=1`、`status`、`sourceFile`、`cacheHash`、`eventsPerSlice`,以及每设备 `eventCount/sliceCount/readySlices/slices`;切片记录包括 `index/startEventId/endEventId/file/ready`。 - 当前 msinsight 要求每设备区间从 0 连续覆盖到 `eventCount-1`。定义非零起点/非连续原始 ID 的策略:明确拒绝兼容输出,或显式重新编号并保留可逆原始 ID 映射,不能静默修改身份。 - 以真实事件位置决定分片容量。负 ID 左边界事件单独标识;事件范围、峰值和真实计数不得被边界事件污染。 - 固定基础 SQLite 表、列顺序、类型与 dictionary 枚举映射。msinsight 通过实际 table 发现事件表,部分 `SELECT *` 按列位置解析,兼容 VIEW 不能替代此合同。 - 定义已解析 block 的跨片稳定身份、未解析/预存 block 的身份及生命周期哨兵值,禁止仅按地址去重。 - pt-snap 增强 metadata、去重 callstack、有序 frame 数据使用可选扩展表或 sidecar;基础协议版本、pt-snap 导入版本、frame 扩展版本分别管理。 - 定义整份数据集、设备、单片、事件范围的查询 scope 与能力声明;外部产物不要求 `pt_snap_metadata` 或辅助引用表。 - 对缺片、重叠区间、非法相对路径、device/表不一致、未知版本、building 状态给出可定位的校验错误;首版完整分析仅接受最终化的 complete 数据集。 ## 验收标准 - [ ] 中英文协议文档包含 manifest 示例、SQLite 列顺序/枚举、事件与生命周期语义。 - [ ] 有共用解析/校验模型及合成有效、无效产物的合同测试。 - [ ] 当前 msinsight 兼容布局通过其真实 manifest 校验规则的对照测试。 - [ ] 非零/非连续 ID、无事件设备、静态 block、负 ID 边界事件的行为有明确决定及测试。 - [ ] 未知增强扩展不影响基础读取;缺少 frames 不得被描述为完整结构化 frame 能力。 ## 参考资源 - pt-snap-cli 本地基线 `09244150ef2a3485aca3d7d23b0f0af0a07f2cb9`;msinsight `101f65b877a267ffd5f66ea3834706057ba243e5`。这些是方案分析基线,实施前应重新核对目标版本。 - https://gitcode.com/Ascend/msinsight:`scripts/MemSnapDump/tools/adaptors/snapshot2db.py`、`tools/adaptors/database/snapshot_db.py`。 - msinsight:`MemSnapshotSliceService.cpp`、`MemSnapshotDatabase.cpp`。 - 关联 #134(v1/v2 只读布局兼容)、#142(能力清单与 overview)。
Activity
codeasier commentedon Oct 4, 2026
Issue review
Reality: 需求成立,属于新增产物协议缺口,并非现有 split 违约:当前只输出 pickle/JSON,再单独导入 DB;原生 v2 使用 callstackId。内存核验表明默认峰值及 overview 包含负 ID,确需明确边界语义。
Reasonableness: 先冻结共享校验合同合理,但不能以最大 ID 推算真实事件数、按地址合并 block 或静默改号。兼容首版可拒绝非零/稀疏 ID;扩展需命名隔离或 sidecar,v1 直接附加原生 callstack 表会触发布局冲突;文本栈不等于结构化 frames。
Boundary: P0 限双语协议、共享模型与合成正反合同测试;明确空设备、生命周期哨兵、缓存身份、路径及状态一致性。生产与跨片查询执行留后续;complete 门槛仅约束新数据集完整分析,保留现有单库兼容。
Evidence:
Limitations: 已读完整原文及全部 0 条评论,本地 HEAD 等于所引基线。仅做静态及无文件写入的内存检查,未运行 pytest 或产物互通测试。msinsight 指定提交本地缺失、远端 C++ 限流,其真实 manifest/列位置规则尚未完整核实,不能宣称兼容通过。
feat(dataset): define sharded SnapshotDB compatibility contract (#198)
fix(docs): preserve dataset source evidence within branding contract (#…
codeasier commentedon Oct 8, 2026
代码已由 #216 合入 origin/main(9 commits 链,tip 7c33464)。按维护决定先关闭本 issue;PR #216 中声明 deferred 的 GUI / C++ server / 安装 wheel 人工验收,以及 #217 系列默认规模不可用问题,另行跟踪。