P4 Session 截图、标注与导出实施

批次结论

P4 的可复查产物已经接入本地 Session：ScreenShot 可选开关、低频 PNG 附件、时间轴标注、Review 回放和 JSONL / CSV 导出均已形成闭环。Swift 全量测试 61/61、Python 全量测试 22/22，SwiftPM 构建和 VitePress 构建通过（E2）。最终 x86_64 App 已重新打包，内置 Collector 与 pymobiledevice3 均通过签名校验；当前连接设备上的截图与短采集也已复测（E4）。原生 UI 全链路点击仍是独立门禁，未把缺少点击录证的部分描述为 E4。

交付范围

ScreenShot

• 指标选择器中的 ScreenShot 现在为可选项；开始 Session 时把选择冻结到 session-plan.json.screenshotEnabled。
• 启用后由 PerformanceSessionController 启动一个 1 秒节拍的截图任务；未启用时不发起截图请求。
• 空闲工作台在设备就绪后以 1 秒节拍刷新预览；Session 开始后停止空闲预览，由 Session 任务独占截图写入，避免同一设备 DVT 并发。
• DeviceScreenshotRequestGate 对不同客户端实例也提供 FIFO 串行化；PNG 签名、文件大小和附件路径在 Review 加载时再次校验。
• 失败、取消、设备断开或非 PNG 返回只落事件元数据和原因，不创建文件、不显示上一张图片冒充当前点。

标注与回放

• 采集中的“标注”入口只接受去除首尾空白后的非空文本。
• Note 是 append-only eventType=note 事件，带创建时间、Host monotonic 时间和 generation；停止 Session 前等待异步写入完成。
• 截图、Note、样本共用 session-timeline.v1 的 elapsed 坐标，Review 的指标图、事件列表和截图卡片按同一坐标回放。

导出

• Review 提供 JSONL / CSV 菜单，并显示保存成功或失败反馈。
• JSONL 第一行固定为 recordType=export_meta，包含 session-export.v1、session-timeline.v1、时钟来源、锚点和时间轴质量。
• CSV 使用同一组元数据列；数值固定六位小数、缺失留空、合法零保持 0.000000，文本按 RFC 4180 规则转义。
• 导出只读派生，不改写 Session 原始 raw/、events/ 或附件。

兼容与回归

• PerformanceSessionPlan.screenshotEnabled 对旧版 session-plan.json 缺失字段按 false 解码，历史会话可以继续打开。
• PerformanceSessionStore 对有效截图要求相对路径、有效 PNG 和 byteCount 一致；失败事件没有附件时不会被误判为损坏。
• Collector Supervisor 在短生命周期 Sidecar 退出时先排空 stdout/stderr，避免最终 hello / stopped 记录因管道调度竞态丢失。
• 新增 Session 计划兼容、截图附件、Note/时间轴、Controller 真正截图开关和设备预览状态测试。

证据与未关门项

检查	结果	证据
Swift 全量测试	61/61	E2
Python 全量测试	22/22	E2
SwiftPM App 编译	通过	E2
VitePress 构建	通过，归档同步 58 个文件	E2
x86_64 Sidecar	Mach-O 产物与 runtime 生成，App 内置文件存在	E2
x86_64 Perfowl.app	App、内置 Collector 与 pymobiledevice3 均完成 codesign --verify --deep --strict	E2
当前 USB 设备 User App 列表	最终 App 内置工具只读读取 46 条结构化记录	E4
当前 USB 设备 DVT 截图	最终 App 内置工具返回有效 PNG，1170 × 2532，2,580,871 bytes	E4
最终 App 内置 Collector	目标 App A 只读短采集 10 个样本，return code 0；首点按协议为 warmup	E4
原生 UI 点击闭环	选择设备/App → 勾选 ScreenShot → 开始 → 标注 → 停止 → Review → 导出	E4 门禁开放

仍未在本批次宣称的能力：逐帧 Display/Hitches 真值、云端上传、截图与指标的服务端报告，以及 iOS 17+ 真机矩阵。它们分别由 P3、P7 和发布/兼容性门禁承接。