Session 截图、标注与导出

本页说明 Perfowl 如何把设备截图、用户标注和指标事件保存到同一份本地 Session，并以可复查的 JSONL / CSV 导出。它们都是追加事实的派生视图，不会改写原始采集数据。

截图

指标选择器中的 ScreenShot 是一个明确的 Session 选项。只有开始测试时勾选它，Session 才会把 screenshotEnabled=true 写入 session-plan.json 并保存截图事件；没有勾选时不会因为空闲预览而把图片写入 Session。

连接设备后，Perfowl 使用 pymobiledevice3 的 DVT screenshot 服务做低频采集，目标频率为 1 秒一次；同一设备最多一个在途请求。有效 PNG 才保存到 screenshots/shot-######.png，截图事件记录 capturedAt、Host monotonic 时间、相对路径、字节数和 valid 质量。空闲工作台也会以 1 秒节拍刷新顶部预览，但开始 Session 后由 Session 任务独占 DVT 请求。

服务超时、设备断开、取消或返回非 PNG 时，事件仍保留 failed / cancelled 质量与原因，路径为空；缺失截图不会转成 0，也不会用上一张图片冒充当前时刻。Review 加载时会再次检查路径位于 Session 目录、PNG 签名和字节数，损坏附件按错误返回。截图文件本身不改变目标 App，属于设备只读服务结果。

标注

标注由测试者输入非空文本后追加为 eventType=note。文本首尾空白会被去掉，空文本不创建事件。标注使用和样本、截图相同的 Host monotonic / wall clock 选择，因此 Review 中的 elapsedSeconds、游标和窗口筛选均来自同一个 session-timeline.v1。

本版本只追加不编辑：历史 Note 保持原文和原始顺序。未来的修改或删除应通过新的 tombstone 事件表达，不覆盖旧行。

导出

JSONL

第一行是导出元数据，之后每行一个事件。元数据包含：

• exportVersion=session-export.v1
• timelineAlgorithmVersion=session-timeline.v1
• clockSource：host-monotonic、wall-clock-estimated 或 missing
• anchorMonotonicNs、anchorWallTimestamp
• timelineQuality：valid、estimated、degraded 或 missing

事件行保留原始事件、ordinal、elapsed 和点质量；截图只引用相对路径，不把 PNG 二进制塞进 JSONL。

CSV

CSV 以同一组元数据列开头，每行对应一个时间轴事件。样本行附带 CPU、内存、FPS、GPU、Network 等现有字段及其 scope、unit、quality；截图行另有 screenshot_path、screenshot_quality、screenshot_error。不存在的指标留空；合法的数值 0 保持 0。小数使用 ASCII .，数值导出固定六位小数，文本和 JSON 使用 RFC 4180 引号规则。

版本与边界

项	当前值
截图契约	screenshot-capture.v1
Note 契约	session-note.v1
导出契约	session-export.v1
时间轴	session-timeline.v1
当前证据	E2：Swift 61/61、Python 22/22、VitePress 与 x86_64 App 构建通过；E4：最终 App 内置工具已复测当前 USB 设备 User App、DVT PNG 和 Collector 短采集；原生 UI 闭环仍需补录

来源批次：P4 Session 截图、标注与导出契约 · 实施记录 · 验收记录。