Foundation roadmap · iOS non-invasive
Perfowl 对齐 PerfDog 指标基座开发计划 v1
底层保持 pymobiledevice3 主采集 + xctrace 增强诊断。本计划先解决原始数据保真、指标语义、能力协商和校准，再扩展报告与云端；不会把“字段出现”当作“已对齐”。A / DATA-1、B 系统候选、FRAME-1 离线帧分析层和 FRAME-SOURCE-1 输入契约已完成，B-VAL 与真实逐帧源门禁仍等待前台场景、PerfDog 同时间窗文件和真机源证据。
Architecture decision
底层能力与职责边界
pymobiledevice3设备发现、配对/开发者服务、App/进程、DVT Sysmontap/Graphics/候选 Network 与 Energy，承担实时主链。
Perfowl Collector协议、目标绑定、能力协商、原始事件、时钟与质量信息；禁止在采集层抹掉累计值。
Analysis EngineFrame、Jank、统计、阈值、区间和公式版本；只生成可离线重算的派生指标。
xctraceDisplay/Frame、Time Profiler、Energy、Hitches、GPU Counter 的增强诊断与校准真值，不常驻主链。
核心约束：Raw Event → Metric(version) → Report。
原始源、单位、scope、采样间隔和质量标记必须随 Session 保存；任何公式调整只能重算派生层，不能覆盖原始数据。
Current baseline
当前基座起点
| 层级 | 已经具备 | 当前缺口 |
|---|---|---|
| 端到端可见 | 前台设备 FPS、App CPU、Physical Footprint、TotalCPU、设备级 Network；Collector → Swift → Session → 实时图。 | 都尚未与 PerfDog/Xcode 同场校准，仍应标记 Experimental。 |
| Collector 已输出 | Resident、线程、CSwitch/s、Wakeups/s、磁盘读写/s、Render/Tiler/Device GPU 等。 | 部分未进入 Metric Registry、PerformanceSample、UI、报告；累计 counter 已被提前转成 rate。 |
| 已承接源 | DVT System 原始区块、NetworkMonitor、Graphics；同一 socket 的 DVTEventPump 按 channel 分发。 | Energy/Thermal、Screenshot、xctrace 仍是候选入口；能力、单位、scope 和系统版本矩阵继续扩展。 |
| 关键空白 | 已有 PerfDog 导出样本与官方算法说明，可作验收输入；DATA-1 已补 TotalCPU 和 device Network。 | 逐帧 Display FrameTime、Jank 派生链、分核 CPU UI、可用内存、进程级网络、热、电池、分类 Energy。 |
Implementation update · 2026-09-04
B 系统候选、FRAME-1 与 FRAME-SOURCE-1 已完成
已完成：
在 DATA-1 原始链上加入 TotalCPU raw/candidate 双轨、CPUCount/EnabledCPUs 与 PerCPUUsage 原始向量、iOS 17+ Host/provider route 审计、Session generation 质量统计，以及无第三方依赖的 PerfDog CSV 同时间窗校准脚本。FRAME-1 新增源无关的 DisplayFrameEvent 与 FramePipelineAnalyzer，可离线重算 FrameTime、FPS、Drop、MedRange、Small/Jank/BigJank、1% Low 和 Stutter candidate，并保留原始事件、算法版本与质量状态。FRAME-SOURCE-1 新增带显式单位的 JSONL/CSV 输入归一化、错误行和质量报告，禁止用秒级 Graphics FPS 冒充逐帧事件。
详细实现与测试见 B 批次实施与校准记录、FRAME-1 帧分析引擎基础 和 FRAME-SOURCE-1 逐帧输入契约。当前仍不把 candidate 升级为 Validated：B-VAL 需要前台静止/滚动/动画/上传/下载五场景、PerfDog 三轮同时间窗文件，以及 iOS 17+ 真机路由回包；FRAME-SOURCE 还需要稳定的 Display/Frame Lifetimes/Hitches 逐帧事件。
Capability contract
先建立 capability，再决定界面显示什么
| 字段 | 含义 | 示例 |
|---|---|---|
metricID | 稳定标识，不使用展示名作为协议。 | ios.process.memory.physical_footprint |
availability | available / unavailable / degraded / requires-mode / experimental。 | Wi-Fi Battery=requires-mode；无源 BTemp=unavailable。 |
scope | process / process-group / foreground-device / device / host。 | 当前 Graphics FPS=foreground-device；官方最新 Network=device。 |
source | 采集来源和原字段。 | dvt.sysmontap:physFootprint |
unit | 原始单位与展示换算。 | bytes、percent、count/s、ms、score。 |
version | 派生公式、兼容映射、采集器协议版本。 | jank.perfdog-compatible.v1 |
quality | missing、warmup、counter-reset、late、dropped、estimated。 | 差分 counter 第一帧应 missing，不显示 0。 |
Delivery sequence
八阶段实施顺序
| 阶段 | 目的 / 数据源 | 输出 | 验收与停止条件 |
|---|---|---|---|
| P0 数据保真 | DVT Sysmontap/Graphics 原始回包；设备/Collector 元数据。 | Schema v2、Metric Registry v2、Processes + System 原始区块、累计值与 rate 并存、source/scope/unit/quality。 | 同一 Session 可离线重放并重算；未知字段不丢失。若原始事件不可稳定落盘或 30 分钟出现乱序/断档，停止后续指标开发。 |
| P1 已有源承接 | physFootprint、memResidentSize、threadCount、disk、wakeups、ctxSwitch、Graphics 三项 GPU。 | 完整 Swift 模型、指标选择器、实时图、区间统计、导出列。 | 前台 App 连续 30 分钟；每个值可追到原字段。与 PerfDog/Xcode 的误差需记录，不强行设统一百分比门槛。 |
| P2 System / Network | DVT System 区块、NetworkMonitor 候选、进程/连接关联实验。 | Total CPU raw/candidate、分核数组、Recv/Send；Available Memory 仍待源定义，每项明确 process 或 device scope。 | 纯上传、纯下载、短/长连接、前后台、断连重绑；counter reset 显示 missing。若 PID 归属不可证明，Network 只按 device 输出。 |
| P3 FramePipeline | DVT Graphics/逐帧候选协议；xctrace Display/Frame/Hitches 作校准。 | Display FrameTime、FPS、Drop、MedRange、SmallJank、Jank、BigJank、1% Low、Stutter；原始帧流与算法版本；FRAME-SOURCE-1 JSONL/CSV 输入契约。 | 输入契约与离线候选引擎已实现；仍需 60/120Hz 静止、匀速滚动、持续动画、人工卡顿真机样本。TinyJank/Smooth 在公式不完整时保持 Unsupported。逐帧源若无法稳定获得，暂停兼容算法承诺。 |
| P4 可复查测试 | 统一时钟、DVT Screenshot 候选、用户事件。 | 截图、Label、Note、场景区间、同步十字线、历史回放、HTML/Excel/JSON 导出。 | 任一异常点可回到截图、场景、原始值和算法版本；截图时间偏差可测量。USB/Wi-Fi 限制在界面直示。 |
| P5 热与能耗 | DVT Energy/Thermal 探针、设备电池候选、xctrace Energy/Thermal 校准。 | ThermalStatus、BTemp（若可达）、Battery Current/Voltage/Power、六类 Energy 和 Total Energy。 | 物理量与相对分数严格分开；Battery 仅 Wi-Fi、约 20 秒采样；USB 充电时标记无参考意义。无稳定源时保持 Unsupported。 |
| P6 xctrace 增强 | xctrace 模板与导出表。 | Time Profiler、线程/调用栈、Hitches、GPU Counter、深度报告附件与跳转。 | 独立进程、可取消、失败不影响常规采集；App Store 包、Development 包和系统版本边界分别展示。 |
| P7 Cloud / CI | 本地 Session 包、断点上传、服务端任务与报告模型。 | Case/Task、分享、对比池、团队协作、CLI/CI、MCP/AI 查询接口。 | 离线优先、上传幂等、断点续传、权限隔离；Web 不修改原始数据。必须在 P0–P4 本地闭环稳定后启动。 |
Metric map
PerfDog 指标 → 阶段归属
| 指标族 | 阶段 | 当前基础 | 对齐定义 | 主要风险 |
|---|---|---|---|---|
| FPS / AppCPU / Footprint | P0–P1 | 端到端已通 | 同场校准后升级状态 | scope 和 CPU 归一化歧义 |
| Resident / Thread / Disk / Wakeups / CSwitch / GPU | P0–P1 | 源或 Sidecar 已有 | 原值、rate、单位并存 | 提前筛选和 Swift 字段丢失 |
| Total/Per-core CPU / Available Memory | P2 | System 候选 | 设备级数组与原始字段 | 系统版本动态字段 |
| Network Recv/Send | P2 | 候选入口 | 当前官方按整机 scope | 旧资料写目标进程，需消歧 |
| FrameTime / Jank / 1% Low / Stutter | P3 | 算法资料已确认 | Display FrameTime 派生 | 逐帧数据源和动态刷新率 |
| TinyJank / Smooth | P3 Hold | 定义不完整 | 等待公式或黑盒样本 | 近似实现会造成伪对齐 |
| Screenshot / Label / Note | P4 | 入口候选 | 统一时间轴的一等事件 | 截图模式限制和时间偏差 |
| Thermal / Battery / Energy | P5 | 候选入口 | 模式化 capability | 无稳定公开源、物理量/分数混淆 |
| GPU Counter / Stack / Hitches | P6 | xctrace 增强 | 原始字段 + 趋势展示 | 兼容矩阵和采集开销 |
Quality gates
每阶段共同验收门禁
G-SOURCE
来源门禁
每个指标有 source/key/unit/scope/sample interval；页面命名与协议标识解耦。
G-RAW
保真门禁
原始累计值、原始系统区块和未知字段可落盘，派生值可用版本化算法离线重算。
G-TRUTH
真值门禁
至少与 PerfDog、Xcode Debug Gauge 或 xctrace 中适用的真值来源同场；记录场景、误差分布和不一致解释。
G-MATRIX
兼容门禁
覆盖 iOS 16 与 iOS 17+ 连接路线、60/120Hz、USB/Wi-Fi、前后台和断连重绑；不可用项返回原因。
G-COST
开销门禁
记录 Collector CPU/内存、采样丢失率、时间戳抖动和 60 分钟稳定性；不沿用宣传值代替实测。
G-UX
产品门禁
缺值显示 missing/不可用原因；不显示虚假 0；用户能看到 scope、模式限制和 Experimental 状态。
Approval packages
建议按四张开发批准单执行
| 批准单 | 包含阶段 | 价值 | 进入条件 |
|---|---|---|---|
| A · 采集保真 | P0 + P1 + DATA-1 | 把已有 DVT 能力完整变成可追踪产品指标，是风险最低、收益最高的一批。 | 已批准并实施；详细结果见 DATA-1 记录。 |
| B · 系统与帧体验 | P2 + P3 | 补齐 PerfDog 常规测试核心差距。 | 候选引擎与输入契约已实现；仍需要固定场景对照样本和稳定逐帧源，才能升级为兼容实现。 |
| C · 可复查与能耗 | P4 + P5 | 把实时曲线变成可复盘测试；补模式敏感指标。 | 统一时钟和 capability 完成，且获得 USB/Wi-Fi 对照资料。 |
| D · 深度分析与云 | P6 + P7 | 形成专业诊断、自动化和团队闭环。 | P0–P4 达到稳定门禁后再批准，避免云端放大错误口径。 |
B-VAL 与 REAL-FRAME-SOURCE 是当前双停止点。
下一步提供前台五场景、PerfDog 同时间窗导出、iOS 17+ 真机 route 证据，以及 Display/Frame Lifetimes/Hitches 逐帧回包；FRAME-SOURCE-1 先完成单位与字段归一化，再由 FRAME-1 回放层产出候选误差报告，未通过的字段继续保持 Experimental。
Research inputs
仍需要收集的 PerfDog 资料
- 四组 60 秒固定场景：静止、匀速滚动、持续动画、每 2 秒人工卡顿；提供 Excel、报告截图和采集配置。
- 120Hz 场景：关闭/开启低电量模式，各重复滚动与人工卡顿；用于刷新率和 Jank 边界。
- 网络 scope：同一设备只让目标 App 传输、再让其他 App 传输；导出客户端和 Service 数据，确认整机/进程口径。
- CPU 口径：不同核心数设备运行单线程和多线程满载，同时记录 PerfDog 与 Xcode。
- 模式限制：同一 App 在 USB/Wi-Fi、商店包/Development 包下的可选指标、不可用提示和导出差异。
- 完整 Session 包：Excel 引用的截图原图、原始工程/报告（若支持）、Label/Note 操作录像。
这些资料不阻塞批准单 A；它们决定批准单 B、C 能否从“候选实现”升级为“兼容 PerfDog 的可验收实现”。
Evidence ledger
结论依据与边界
| 依据 | 用于 | 尚未证明 |
|---|---|---|
| PerfDog 官方资料中心 | 指标语义、Service 契约、USB/Wi-Fi 与深度分析限制。 | 未公开算法、当前付费客户端全部行为。 |
| PerfDog 导出样本差距 | 字段、公式复算、现有代码承接差距。 | 跨版本、跨设备和跨采集模式一致性。 |
| Perfowl 源码与 DATA-1 实施结果 | 确认 Collector/Swift/Session/UI 的真实去向、TotalCPU/Network 质量和原始留存。 | 长时稳定、跨系统和 PerfDog 误差。 |
| 当前设备 iOS 16 真机短采集 | 两个匿名目标各 29 个样本；Bundle ID → PID 校验、System/Network 动态值和质量状态可见。 | iOS 17+、120Hz、长时和 PerfDog 同场。 |