外观
Session 历史会话回放与统一时间轴：用一条派生坐标还原测试现场
2026-10-28展示更新： 普通用户报告直接展示指标、单位、均值、趋势和截图，不显示内部质量码、算法版本或可靠性标签。下文时间轴质量模型用于解释原件／诊断语义，继续保留在内部数据中；移除用户标签不改变测量值、有效性规则或原件。新导出采用PerfDog样例双表结构与截图ZIP，完整合同见文末本次增量；当前处于软件实现阶段，不代表新增真机校准。
对于偶发性性能问题（如"某次滑动时偶发掉帧，但再次测试难以复现"），事后复盘能力至关重要。
Perfowl 内置了完整的 Session 历史会话回放与审查（Session Review & Replay） 引擎。所有监控指标、系统工况、截图与标注都会被投影到同一条产品 timeline 坐标（SessionTimeline）上，测试人员可以像播放视频一样拖动游标查看历史测试现场；这条坐标本身是派生视图，不是新的性能指标，也不会改写原始事件的追加顺序。
1. 时间轴坐标是怎样构建的（不是"统一纳秒硬件时钟"）
事实澄清
不同 source 本身使用不同的 clock domain（Host Monotonic、Device Mach、Source-native Cocoa 时间戳等），Perfowl 没有把它们统一成同一个纳秒硬件时钟；SessionTimeline 只是在产品层面把已有的时间戳投影到一条便于回放/游标对齐的坐标上，且明确区分了这条投影的可信程度。
SessionTimelineBuilder（MacApp/Sources/PerfowlCore/SessionTimeline.swift）的规则：
text
若 Session 内全部事件都携带有效的 hostReceiveMonotonicNs
→ 以首个事件为锚点，elapsedSeconds = (event.monotonic - anchor.monotonic) / 1e9
→ 该点标记为 valid（如检测到 monotonic 比前一个点更小，标记为 out-of-order，整条时间轴质量降级为 degraded）
否则（旧归档缺少该字段，或字段为兼容哨兵 0）
→ 整条 Session 统一回退到 wall-clock：elapsedSeconds = event.wallTimestamp - anchor.wallTimestamp
→ 该点标记为 estimated
若全部事件都没有可用坐标 → 时间轴质量为 missing关键约束（p4-session-review-timeline.md）：一个 Session 只选一种时钟，不允许在同一条时间轴里混用 monotonic 锚点与 wall-time fallback——那样会在缺失字段处产生难以解释的时间断层。乱序点会被保留而不是被丢弃或重排，只是标注质量并让整条时间轴降级，这样原始 Raw 事件的追加顺序（证据本身）始终不受播放视图影响。
2. 时间轴质量状态
| 状态 | 含义 |
|---|---|
valid | 全部事件有 monotonic 坐标且顺序正常 |
estimated | 回退到 wall-clock 锚点（旧归档或字段缺失） |
degraded | 检测到乱序事件，仍保留原始顺序但降级标注 |
missing | 空 Session 或全部事件都没有可用坐标 |
不要把"回退到 wall-clock 的 estimated"或"检测到乱序的 degraded"当作错误——它们是如实的质量标注，目的是让使用者知道这条坐标的可信程度，而不是掩盖真实情况伪装成统一的高精度时钟。
3. 实时工作台 60 秒视口 vs 历史全量审查
| 视图模式 | 呈现策略 | 适用场景 |
|---|---|---|
| 实时采集视口 (Live View) | 采用 60 秒平滑滚动视口：0~60 秒平铺展示，超过 60 秒后窗口自动向左匀速推移，保持展现最新一分钟的实时波形 | 观察当前实时压测表现，捕捉刚刚发生的突发卡顿或尖峰 |
| 历史会话审查 (Review View) | 展开 全量物理时间轴：支持从 0 秒一直拖拽到测试结束（即使测试持续 2 小时），全量波形完整呈现 | 测试完成后的精细化复盘、区间框选统计、多指标交叉比对 |
4. 常见复盘审查实战技巧
- 区间框选统计 (Range Selection)： 在 Review 视图中，可以鼠标框选任意时间区间（例如专门框选“用户在购物车结算的 20 秒”），系统自动重新计算该区间的平均 FPS、Jank 次数与 CPU 均值，实现业务模块的精准切片分析。
- 游标悬停联动 (Crosshair Sync)： 在任何一条指标曲线（如 FrameTime）上悬停鼠标游标，垂直参考线会自动贯穿全屏的所有指标（APP CPU、Footprint、Network、GPU）以及底部的截图时间轴，一眼看清该时刻的全部系统状态。
- 标记跳转 (Note Navigation)： 点击测试过程中打下的任何一条 Note 标注，游标瞬间跳转至该操作时刻，快速定位业务操作的起始点。
5. 相关指南深入阅读
2026-10-26 · 原生结果报告统计合同（session-report-summary.v1）
以下是本次实施依据，尚待当前版本测试，不把早期回看设想视为已经可用。沿用session-timeline.v1坐标，区间采用半开[a,b)；全程额外纳入最后一个时刻的全部记录。来源代际、scope、unit或质量变化分段，不跨缺口补值。游标只显示容差内实际采样点及其时间偏差；缺值与重置边界不借前值填充。
对每个明确单位和scope的采样系列，设符合原指标numeric质量合同的有限值集合为V：采样均值sum(V)/count(V)，最小/最大min(V)/max(V)；无有效数值均为null。允许的candidate单独计数，未知质量不参与；合法0保留。可用点比例count(V)/记录点数，记录点数0时为null；这不代表连续时间覆盖率。运算保持原精度，展示取整不回流计算。bytes以MiB显示时除以1048576，bytes/s以KiB/s显示时除以1024，导出保留原单位原数值。
全程FrameTime P95不能由滚动P95的均值或再取分位得到；Jank、Smooth、1%Low等派生值不从展示曲线重建。已有Collector封存报告值仅在其原窗口及版本下展示，区间无完整合法输入则明确“不支持区间重算”。速率不默认积分成总字节，Energy cost不转换为mW。截图取已持久化附件，显示真实时间/偏差，不是逐帧真值；未保存截图不从工作台内存补入历史。
原始Session与用户标注分开存储；标注绑定源摘要，源变化不得静默沿用旧标注和已核验状态。完成、partial/failed、文件核验、候选与Owner验收范围分别显示。正式55/66与本次报告数据状态互不替代。
来源：原生结果中心方案，E1设计合同；实际证据见该文后续增量。
2026-10-26 · 原生结果窗口使用（内部试用）
本机内部版227把采集结束后的结果放到独立原生窗口。停止确认后先显示整理中，保存成功才读取；同一Session只自动打开一次，关闭不会因迟到消息再弹出，历史列表可主动重开。窗口中按分类查看，图上悬停/点击固定游标，拖拽框选后摘要与图表使用相同区间；最小宽度自动收起右检查器。Cmd+F找指标、Cmd+E导出CSV、Cmd+0恢复全程，左右键逐样本，Esc取消临时选择。
只展示已保存截图，并显示与游标的实际偏差；未保存预览不会写入历史。备注和阶段存储于独立用户分析目录，绑定manifest、规范化事件、计划及Collector报告/收据的内容摘要，源变化后保留旧标注而不静默套用。CSV导出原单位的全点与采样统计；PDF为中文分页摘要。Collector派生结果仅在全程原窗口显示，选区不据展示曲线猜算Jank/P95等指标；历史列表摘要在重新打开核对来源前明确未复核。
参考线采用report-reference-crossing.v1：前点≤线、后点>线且两点数值合法、连续同段时记录后点，可跳转；跨缺值、目标/来源代际断点不生成跨越，显示的是采样窗口而非逐帧发生时间。这只是用户观察条件，不是性能验收阈值或因果诊断。
E2测试覆盖保存成功/失败、统计边界、导出和标注，主机原生窗口测试覆盖一小时/四小时及30分钟180张附件；未做新的手机E4自动开窗测试、强制冷缓存或多窗口总峰值验证。Raw未独立核验、正式55/66及11项暂停分别显示，结果窗口不增加任何指标验收结论。
| 版本 | 日期 | 变化 | 来源 |
|---|---|---|---|
| session-report-summary.v1 | 2026-10-26 | 规范化采样区间/质量/单位、独立结果窗与备注导出；无逐帧输入不重建派生量 | 实现与验证 |
| report-reference-crossing.v1 | 2026-10-26 | 同段相邻合法采样的用户参考线上穿定位，不插值 | 同上 |
2026-10-26 · 复盘时先确认摘要在统计什么
报告采样均值、Collector来源Stat、逐帧会话派生值分开解释：先对齐区间/质量/点数/单位和版本，再比较数值。CPU单核100%口径可超过100%，不能不核有效核心数就与别的工具百分比相比；同一Session的CPU/内存两类摘要目前还有逐源核查待办，不把差异一律解释为取整。跨设备旧报告用于提出问题，不能据此给出误差结论。
历史UI、CSV/PDF保存成功仅证明对应消费者/导出链路，不能替代Raw独立审计、参考资格或手机Stop后自动开窗E4。没有启用的Energy/温度留空；未保存内存截图不混入历史证据；保存终态成功才可标ready。先核Session完整性，再看曲线/截图/标注，不把“已展示”写成“已校准”。
版本历史增量：2026-10-26，补采样/来源统计差异、空值与证据层级的阅读方法；本批E1，报告产品能力仍按已有E2/主机E3及开放E4门说明。月度复盘与来源索引 · 实验判断方法
2026-10-28 · 第二轮内部试用的报告合同
默认报告session-report-summary.v2：应用CPU是整机容量100%刻度，Footprint采用均值，MiB/KiB/s单位明确。CSV逐样本附实际来源/算法，摘要附有效点数及首末有效端点，端点跨度不是完整覆盖率。Collector高频源统计与已记录帧片段诊断另列，不代替产品1Hz均值；单次Core启动事件仅在全范围导出，not-applicable为空。旧逐事件CSV v4保留原CPU列并追加容量CPU/核数/原刻度及来源字典。实时截图预览开关下次Session生效，若同时保存截图则仍采集保存；完全OFF对照需同时取消保存。旧会话不写回、不伪造缺少的逐点来源。正式55/66、11项暂停，用户第二轮真机效果与精度仍待验证。方案、实现与证据。
2026-10-28 · 用户报告与Excel导出合同
本次仅新增展示／导出适配，版本perfdog-layout.report-export.v1；源指标和session-report-summary.v2不改。来源：实施方案。
- 一个Session对应
all（基本信息、29列统计、44列逐秒明细）和@FrameInfo两个sheet，以及同stem的截图ZIP。未建立三列帧字段映射时帧表数据为空；不以1Hz序列构造帧真值。 - 原始字段与映射：AppCPU=原始
cpuUsage / explicit cpuCoreCount；TotalCPU=显式normalized整机值；FPS=产品framesPerSecond；Memory=Footprint；Real/Virtual/Available各用已有同名scope的字节源，XcodeMemory缺严格映射留空。逐核按源数组顺序，仅填样例六列。GPU用已有前台Render/Tiler/Device，CPU/GPU能耗保留source-native-cost的源单位，未知或暂停列为空。磁盘样例字段未证明是速率还是累计，故不把bytes/s填入ReadDiskBytes/WriteDiskBytes；Wakeups/CSwitch未证明是每秒或累计，同样留空。不存在的Jank分档、Smooth等保留空列。 - 单位：Excel带MB的列均bytes÷1,000,000，KB/s均bytes/s÷1000；既有UI的MiB、KiB/s仍分别÷1,048,576、÷1024，单位明确。底层字段及Registry 原始单位不变，只有同单位的值要求相同。
- 汇总：有效1Hz产品点算术均值
sum(x_i)/N；峰值max(x_i)；FPS≥18/25、CPU≤60/80为有效点中满足条件的比例×100。源字段的有效性／scope／unit约束沿用ReportBuilder；缺失不补0、重置点不借值、合法0保留。网络合计仅在同一点上行和下行均有效时求和再平均，不加两个覆盖不同的平均值。没有有效点则空，不做时间外推或累计流量积分。Std/Var、MedRange、Drop、每10分钟流量与其他未闭合算法统计为空，不凭列名发明算法。 - 时间：
time=elapsedSeconds×1000，保留真实间隔；absTime=已记录wallTimestamp的Unix毫秒，缺失留空；单次启动事件只填一次，未知选区映射不借用全程事件。Session耗时仅从正向单调时钟端点差得出，缺证据不以文件日期推测。 - 精度：源双精度不取整；显示默认2位小数，时间ms／次数显示整数。百分比是0–100数值，不再乘Excel百分比格式。每轮均值先算，再做三轮等权均值；无效轮不填0，保留实际轮数。
- 截图：真实采集图按时间排序连续编号，最长边≤640，旋转正确、去EXIF但不自动修改像素内容；保存前可预览和选择是否包含。
ScreenShot仅引用相对时间差≤2秒的最近真实图，等距取较早图；无图或不包含时单元格空且ZIP为空。截图时间映射写入非展示custom XML，仍与真实Session绑定。 - 用户字段默认没有可靠性徽标；内部candidate/source/quality和不可变原件保留，不扩大11项暂停指标的采集范围。用户备注按文本存储，不当Excel公式；内置元信息不输出设备身份或路径。像素隐私由保存前预览确认，不把去EXIF等同自动脱敏。
以上为E1已固定合同，软件验证／资源与环境打开证据后续追加；不代表跨工具测量精度通过。
2026-10-28 · 已实现范围与试用方法
普通报告直接展示用户名称、平均／最低／峰值，默认应用CPU为整机100%刻度，不显示内部或可靠性徽标；原始记录与开发者诊断保留不变。默认“导出报告”保存Excel＋截图ZIP，CSV简明统计／PDF摘要仍可选，完整CSV在开发者模式。要ZIP含图片，需在采集前选择ScreenShot保存；实时预览本身不等于保存，旧会话没有附件时ZIP为空。
all第6行增加FPS／CPU／内存／应用网络概览，不移动29项统计与44项明细表头；空白表示本次无对应值，不补零。@FrameInfo首批保留空数据区。E2已做软件、真实旧数据导出及独立复算，E3已同址安装内部230；不代表跨工具精度或新手机E4。长Session加载／游标及600–3600张大图导出仍有未达预算项，办公软件实开兼容尚待补充；详见来源记录，不把短试用结果外推长稳。
| 版本 | 日期 | 变化 | 来源 |
|---|---|---|---|
| perfdog-layout.report-export.v1 | 2026-10-28 | 用户词汇、CPU容量刻度、有效点均值、MB／KB适配、固定双表与截图成套导出；来源算法不改、未知留空 | 实施、资源与内部安装收据 |
2026-10-28 · 第二轮报告交互及截图节拍
- 左侧顺序：概览、启动、CPU 与调度、内存、画面表现、GPU、网络与磁盘、能耗、标记。概览上方仍为重点均值卡，下方包含全部用户可见曲线与启动结果，不再另设全部指标。
- 截图轨迹上方书签按钮打开备注与阶段；已有时间标记和用户阶段显示为小书签，点击定位/选择范围。全局备注不伪造采集时间。
- 单击截图定位时刻，双击轨迹/右侧截图等比查看大图；左右按钮/方向键切换，关闭或Esc返回。读取原保存附件（最长边1800px），而非放大缩略图；缺附件显示占位。
- 新截图保存为JPEG，1800px/quality0.75；编码在写入actor外执行，与每秒指标写入分离。截图目标1秒固定主机时钟网格，超时跳过已错失时槽、不突发补拍；真实设备请求过慢仍会不达1Hz，不复制图片补齐。
- 图表X轴保持原主机接收时间，连续性按成对的采集端host publication间隔判断；原始记录不重写。源间隔真实缺口、身份变化和缺值仍断线，接收延迟本身不再伪装源丢点。此为
sample-publication-cadence.v1，不修改均值和导出时间，更不替代启动Total设备时钟。
来源：第二轮反馈修复，仅软件/内部试用证据，真机节拍及持续帧覆盖另测。
2026-10-28 · 专业Excel与报告层级
启动总耗时保留首屏，各阶段默认折叠；时刻详情按分析分类双列显示。概览和画面表现可查看Jank、Stutter、1% Low、Smooth等已保存帧统计。产品每秒FPS均值和帧区间平均FPS是不同总体，不互相替换。
Excel默认打开“概览”，按分类纵向展示结果与统计范围；“趋势”含FPS、应用CPU和内存三张原生图；“all”保持原29统计列与44逐秒列；“@FrameInfo”提供已封存逐帧数据（time相对首个已记录帧，区别于all的会话时间）。选区没有逐帧时钟桥接时不借用全程帧值；缺项留空，不是0。截图ZIP仍与Excel成套导出。该格式为内部试用版本，Office实开及资源余门见本批记录。
2026-10-28 · 当前紧凑版导出（替代上节四页格式）
Excel仅含“概览”和“详细数据”：概览上方有本次保存的应用、设备和测试起止信息，下方为启动总耗时、CPU、内存、FPS及卡顿等重要统计；详细数据纵向列出本次有记录的全部普通用户指标及简短解释。平均统一写在分类标题，启动总项和阶段分层，缺值留空。概览一页打印、详细数据一页宽分页，保持可读字号。逐秒/逐帧原件仍保留在会话和既有诊断导出中，不在紧凑表内横向铺列；截图ZIP继续配套。
设备名称来自采集当时保存的会话计划，不使用匿名常量或当前连接设备代填。host端“进程运行/前台就绪”观测延迟不属于设备端启动分解，普通报告不再混列。此为展示与导出合同变化，未改采集值或启动总耗时公式；软件/旧数据核对不等于手机精度验收。当前实施与限制。