P4 Session Review 时间轴基础

批次结论

本批次为 Session Review / Timeline Foundation 的第一步：在不改写原始 Session 事件顺序的前提下，为回放、跨指标游标、窗口筛选和后续截图标注建立统一的 elapsed 时间坐标。实现已通过 Swift 全量测试（49/49，E2）；尚未接入工作台 UI、Session Store 的回放入口或真实设备截图链路。

本批次交付

• SessionTimelinePointQuality：valid、estimated、out-of-order。
• SessionTimelineQuality：missing、valid、estimated、degraded。
• SessionTimelineBuilder：优先使用 Host monotonic receive time；兼容旧归档的 0 哨兵并统一回退到 wall clock。
• SessionTimeline.playbackPoints：按 elapsed 升序播放，相同时间按原始 ordinal 稳定排序；缺失坐标排在有坐标点之后。
• points(in:)：在播放坐标上做闭区间窗口查询。
• 乱序点保留、标注质量并降级时间轴，不重排或覆盖 raw Session 事实。

数据与算法口径

时间轴不是新的性能指标，而是所有指标曲线、截图、标注和导出可以共用的坐标层。具体公式、单位与缺失处理见Session 回放与时间轴。

关键约束：

1. 一个 Session 只选择一种时钟，禁止在同一条时间轴中混用 monotonic anchor 与 wall-time fallback。
2. 任何无法建立坐标的点保持空值，并携带质量原因；不填充 0。
3. raw 事件追加顺序是证据，playback 排序只是派生视图。
4. 发生回退、乱序或源缺失时，质量状态随时间轴进入导出与后续报告。

验证证据（E2）

检查项	结果
Swift 全量测试	49/49 通过
monotonic 单调坐标	通过
wall clock fallback	通过，质量为 estimated
乱序事件保留与 playback 排序	通过，时间轴质量为 degraded
空 Session	通过，质量为 missing
真机逐帧源 / 截图 / UI 回放	本批次未执行

未完成与下一步

1. 在真实 Session Store 上构建回放索引，并让报告读取同一时间轴。
2. 接入截图采集与低频截图事件，统一使用 elapsedSeconds 做标注定位。
3. 取得 DVT Graphics / xctrace 的逐帧样本后，将 FRAME-1 派生结果挂到同一时间轴；在 E4 真机证据前不将候选 Jank 发布为已对齐指标。
4. 增加导出格式（JSONL / CSV）中的时间轴质量、算法版本与时钟来源字段。

变更范围

• MacApp/Sources/PerfowlCore/SessionTimeline.swift
• MacApp/Tests/PerfowlCoreTests/SessionTimelineTests.swift
• site/knowledge/guides/session-replay.md
• site/.vitepress/config.ts
• site/knowledge/index.md
• site/devlog/index.md