文档中心/实施结果/FRAME-SOURCE-1 逐帧输入契约
输入契约已完成 · 真机源待验证2026-09-04

Implementation Result · FRAME-SOURCE-1

逐帧输入契约已建立，真实 Trace schema 保持待验证

本批次为 FRAME-1 建立可审计的输入边界：JSONL 与 CSV 只有在携带显式时间单位的逐帧记录时才会归一化为 DisplayFrameEvent。秒级 Graphics FPS、无单位的 timestamp 和未知事件类型不会被提升为逐帧真值。

输入归一化已实现质量报告已实现JSONL + CSVxctrace schema 待真机样本

Delivered scope

本批次交付内容

JSONL
显式 frame 记录

支持顶层或 frame 嵌套对象，保留 source、presented、refreshRateHz。

CSV
带单位列解析

支持纳秒、毫秒、秒三类明确列名，并处理引号、逗号和 CRLF。

QUALITY
逐行质量报告

输出 accepted/rejected、错误行、原因和 missing/valid/degraded 状态。

GUARD
防止误判

拒绝把 metrics.framesPerSecond 或裸 timestamp 当作逐帧事件。

RAW
原始输入不改写

解析层只产生归一化事件；原始 Trace/JSONL/CSV 仍由 Session 原始区保存。

HOLD
真实源门禁

当前不绑定特定 xctrace XML schema，等待真机导出样本后再增加适配。

Input contract

允许的记录形状

字段允许形式处理方式
timestampNs / timestamp_ns非负数按纳秒原值使用。
timestampMs / timestamp_ms非负数乘以 1,000,000 后四舍五入为纳秒。
timestampSeconds / timestamp_s非负数乘以 1,000,000,000 后四舍五入为纳秒。
timestamp无单位或未声明单位标记 invalid_timestamp，不生成事件。
kindframe / display-frame / display其他类型（例如 sample）按行标记 unsupported_kind。
presentedtrue/false、1/0、yes/no缺省按 true；非法值标记 invalid_field。
refreshRateHz有限正数或空正数保留；空值保持 nil，非法值标记 invalid_field。

Calculation record

本阶段计算方式（已登记）

timestampNs = round(value) timestampMs = round(value × 1,000,000) timestampSeconds / timestamp_s = round(value × 1,000,000,000) FrameSourceParseReport.quality = missing (accepted = 0) | degraded (accepted > 0 且存在 error) | valid (accepted > 0 且无 error) rejectedCount = error issue 数量 presented 缺省 = true 裸 timestamp = invalid_timestamp（不猜测单位）

归一化之后的事件只携带纳秒时间戳；FrameTime、FPS、Jank、Drop、MedRange、1% Low 和 Stutter 由 FRAME-1 分析引擎按独立算法版本计算。该分层保证单位转换和指标公式都能在文档中复核。

Code location

实现与测试

文件责任状态
MacApp/Sources/PerfowlCore/FrameSource.swiftJSONL/CSV 解析、单位归一化、事件类型约束和逐行质量报告。已实现
MacApp/Tests/PerfowlCoreTests/FrameSourceTests.swift嵌套 JSON、CSV 引号/单位、非法 timestamp 与空输入测试。3 项新增
FramePipeline.swift消费归一化事件并计算候选帧指标。已实现
验证结果：
解析层不访问设备、不启动 xctrace、不修改目标 App；秒级 Graphics FPS 样本不会被转换成伪逐帧事件。

Evidence boundary

当前可确认与待补齐

当前可确认

  • 输入时间单位、事件类型和可选字段均有显式规则。
  • 错误行不会阻塞其他有效行，解析质量可序列化并进入报告。
  • 解析层与分析层解耦，可对同一原始文件重复回放。

仍需真机资料

  • 在当前链接设备上导出 Display/Frame Lifetimes/Hitches 的原始样本。
  • 确认 xctrace XML/表格的真实字段、时间基准和 presented 语义。
  • 将真机样本送入本解析层和 FRAME-1，完成 60/120Hz 同场校准。
产品状态：
FRAME-SOURCE-1 是输入契约与回放基础，不代表已经取得稳定的 xctrace 逐帧源；实时 FrameTime/Jank 继续保持待源状态。

Next gate

进入真实源适配的顺序

  1. 采集真机 Trace：同一设备、前台静止/滚动/动画/人工卡顿各取样本。
  2. 冻结字段映射：记录原始 XML/表格字段、时间单位和 source 标识，更新本页计算表。
  3. 回放校准：使用 FRAME-SOURCE-1 解析后交给 FRAME-1，比较 PerfDog 与 xctrace 同窗口结果。
  4. 实时接入：只有源、公式和误差门禁通过后，才把 FrameTime/Jank 接入 Collector 与 UI。