Foundation Gate F0 · Evidence before product code
先证明连接、指标与开销，再冻结 Perfowl 产品基座
Mac + Cloud 架构方向和 F0 范围已经批准。本计划把 F0 拆成可复现的设备矩阵、实验、数据产物、判定标准和停止条件；执行完成前不启动 M0 产品工程骨架。
Decision
F0 的通过含义
F0 不是做出一个能画曲线的 Demo，而是决定哪些能力可以进入产品承诺。
每个指标必须同时明确 source、raw field、raw unit、canonical unit、scope、刷新周期、版本范围、工具开销、质量条件和 Unsupported 行为；任何未通过项只能保持 Experimental、改用中性名称或退出 M1。
本轮仍不属于产品开发。
允许创建一次性实验脚本、固定 fixture 和分析表，但它们不能直接进入产品目录或被宣称为正式 Collector。F0 报告通过后，再提交 M0 文件级开发计划并等待批准。
1 Stack
只验证 pymobiledevice3
3 Runs
关键场景至少三轮
60 min
正式长会话门禁
主要输出
兼容矩阵、Metric Registry、Route ADR、真值对照、开销报告、原始 fixture、授权交付结论。
失败也必须可用
失败项保留错误、版本和原始数据；不把缺值写成 0，也不为了过门禁修改结论。
Frozen inputs
执行前冻结的信息
| 项目 | 执行时记录 | 用途 |
|---|---|---|
| Perfowl | Git commit、方案/计划版本 | 保证实验结果对应明确设计基线 |
| Codesign4QC | Git commit；参考起点当前为 d75c729 | 区分参考实现与后续工作区变化 |
| pymobiledevice3 | 精确版本、commit、Python、依赖锁与 LICENSE | 协议和 tunnel 行为具有版本敏感性 |
| Apple 工具 | macOS build、Xcode build、xctrace version、active developer directory | Trace 模板和导出 Schema 依赖 Xcode |
| 设备 | UDID 哈希、型号、芯片、RAM、iOS build、刷新率、Developer Mode | 建立可比较键，避免泄露原始 UDID |
| 目标 App | Bundle ID、版本/build、可调试性、安装来源、二进制 UUID | 区分自有测试版、商店版和游戏样本 |
| PerfDog | 客户端版本、账号套餐能力、指标设置、报告链接/导出 | 产品与指标对照必须固定被比较版本 |
所有命令、环境和结果写入单次实验 manifest；敏感账号、密码、token、原始 UDID 不进入仓库。
Test matrix
最小覆盖矩阵
Host 与系统
| 通道 | 最低配置 | 优先级 | 通过意义 |
|---|---|---|---|
| H1 主 Host | Apple Silicon Mac + 项目目标 macOS + 当前目标 Xcode | 必须 | 首发采集、打包和 xctrace 的正式基线 |
| H2 兼容 Host | 另一代 Apple Silicon 或目标最低 macOS | 必须定义 | 验证 OS/Xcode 下限而不是只验证开发机 |
| H3 Intel | Intel Mac + 目标最低 macOS | 条件项 | 只有产品确认 Universal 分发时进入正式矩阵 |
iOS 连接通道
| 通道 | 系统范围 | 预期 Route | 必须验证 |
|---|---|---|---|
| D1 Legacy | iOS 16.x 或首版最低支持版本 | Lockdown / usbmux | 发现、DDI、DVT、断连与重绑 |
| D2 Early 17 | iOS 17.0–17.3.1 | 受控 privileged tunneld | 一次性设置、权限、冷启动、重启和错误恢复 |
| D3 Modern | iOS 17.4+ | macOS native/no-root 优先 | 无管理员权限、与 Xcode 共存、fallback 记录 |
| D4 Current | 执行时最新正式 iOS | 由 capability 探测决定 | 避免只支持历史系统；记录全部原始属性 |
显示与目标 App
| Fixture | 要求 | 覆盖场景 |
|---|---|---|
| A1 可控 Fixture | 自有可调试 App，可稳定制造 idle、CPU、内存、30/60/120 FPS、网络与重启 | 字段、单位、方向性、阈值和异常注入 |
| A2 商店 App | App Store 正常安装，不重签、不修改 | 无侵入能力边界、目标进程与 xctrace 限制 |
| A3 游戏/高刷新样本 | 允许稳定复现场景，至少覆盖 60 Hz 与 120 Hz 设备 | FPS/GPU scope、动态刷新率和 PerfDog 对照 |
矩阵缺设备时的处理。
不以模拟器替代真机，不用另一个 iOS 大版本推断目标版本。缺少的通道标记 Not Tested，并从首版支持范围删除或等设备补齐。
Common method
统一实验方法
- 固定环境
关闭非必要 Host 任务，记录电源、设备温度、屏幕亮度、网络、刷新率、充电状态和冷却时间；每轮实验开始前保存环境快照。
- 先单工具、后同场
先分别运行 pymobiledevice3、Xcode/Instruments、PerfDog，再在确认可行后同场；避免一开始就把互相干扰当成指标误差。
- 预热—测量—冷却
每个稳定场景固定预热、正式测量和冷却区间；关键指标至少三轮，保存每轮而不是只挑最好结果。
- 共同 Marker
用可控 Fixture 的场景切换或屏幕录制事件建立共同时间点；每个来源同时保存 source、host receive 和 wall time。
- 原始优先
先保存 DVT raw row、属性列表、PerfDog 导出和 Trace，再生成归一化指标；禁止只留截图、平均值或最终 CSV。
- 盲判质量
先按预设规则计算，再查看工具名称；不根据期望结果事后更换单位或删除异常轮次。
Experiment catalogue
F0 实验清单
| ID | 实验 | 方法 | 通过条件 | 产物 |
|---|---|---|---|---|
| F0-00 | 授权与交付形态 | 冻结依赖、修改方式、独立进程/随包分发、许可证与源码履行路径 | 形成可执行的 GPL-3.0 交付结论；未通过则禁止正式 App/DMG 打包 | License ADR、依赖清单、NOTICE 草案 |
| F0-01 | 设备发现与 Route | D1–D4 各执行冷启动、热启动、锁屏/解锁、拔插、Mac 休眠和服务重启 | 实际 route 可见；成功/失败均有稳定 code 和 action；不出现静默 fallback | Route matrix、连接耗时、原始诊断 |
| F0-02 | App/进程身份 | 枚举 App/进程，覆盖未启动、前台、后台、退出、重启和 PID 复用 | bundle/executable/PID/start/generation 可对账；累计指标不跨 generation | Target fixtures、重绑时间线 |
| F0-03 | CPU 口径 | A1 制造 idle、单核、双核和短峰值；分别与 Xcode/PerfDog 对照 | 确认 normalized/non-normalized；三轮方向一致；候选发布阈值为稳态绝对偏差 ≤5 个百分点，否则保持 Experimental | Raw fields、公式、误差分布、Metric ADR |
| F0-04 | Memory 口径 | 分段申请/释放内存并保持平台；对比 physFootprint、resident 与 Xcode/PerfDog | UI 名称绑定明确字段；稳态候选偏差 ≤max(5%, 20 MiB)；增长/释放方向三轮一致 | 内存阶梯、字段映射、OOM 相关边界 |
| F0-05 | FPS/GPU scope | 30/60/120 FPS、静止、前后台切换和覆盖层场景；与 PerfDog/Trace 对齐 | 证明 foreground-device 或 target scope；稳定 FPS 候选中位差 ≤1 FPS；无法取得逐帧事件时不发布 FrameTime/Jank | 刷新率矩阵、GPU raw scale、前台归属证据 |
| F0-06 | Network | 固定上传/下载字节、短连接、长连接、前后台和其他 App 干扰 | 确认 process/device scope 和累计字段；已知载荷候选累计偏差 ≤10%；无法证明时只展示原始连接事件 | 流量对账、连接事件、差分规则 |
| F0-07 | Energy/Thermal | 空闲、CPU/GPU/Network 压力、充电与非充电条件；对照 Xcode Energy/thermal state | 只发布可证明的相对 score 或 thermal state；没有物理校准就不显示瓦特/毫安时 | 字段、等级、刷新周期和 Unsupported 矩阵 |
| F0-08 | 日志/Crash/截图 | 目标日志过滤、普通退出、真实 Crash/Jetsam 样本、截图开关和频率实验 | 日志 scope 明确；Crash 以实际报告为准；截图影响量化并默认关闭 | 日志/Crash fixtures、截图开销表 |
| F0-09 | xctrace 增强与并发 | 固定模板单独录制，再与 DVT 同场；保存 TOC、Trace、模板和版本 | 基础采集无断流且关键指标偏移不超过自身三轮波动才允许并发；否则采用独立增强 Run | Trace fixtures、并发 ADR、Schema 选择器 |
| F0-10 | 工具自身开销 | 无工具、pymobiledevice3、PerfDog、xctrace、DVT+xctrace 分别执行相同 Fixture | Host CPU/RSS、目标 CPU/FPS/thermal 差异完整可见；M1 基础模式候选目标为目标 CPU ≤2pp、稳定 FPS ≤1 的额外影响 | Host/Device 开销报告、模式分级 |
| F0-11 | 长时与恢复 | 正式 60 分钟采集，加入 App 重启、断线、慢盘、网络断开与恢复 | accepted=persisted、writer failure=0、无未解释 sequence gap；UI/队列有界；结束后产物完整 | 60 分钟 Session、质量快照、恢复时间线 |
| F0-12 | Schema 与回放 | 从原始数据重建 normalized event、统计和离线报告；注入未知字段和缺失字段 | 未知字段保留、缺值非 0、分析可重算、同输入结果确定、旧 fixture 可读 | Schema v1、golden fixtures、重建报告 |
表中误差值是进入首版同名指标的候选门槛，不是对 pymobiledevice3 或 PerfDog 精度的预先结论。若参考工具本身三轮波动超过门槛，先报告不可比较，而不是强行判 Fail。
Paid PerfDog baseline
付费账号的使用范围
需要读取
- 当前 Mac 客户端版本与完整 iOS 指标列表。
- 每项指标的名称、单位、帮助说明、USB/Wi-Fi 和版本限制。
- 开始、暂停、继续、结束、Marker、Label、保存上传和本地回放。
- 单次 Web 报告、区间统计、任务、比较、导出、分享和异常状态。
需要产出
- A1/A2/A3 各一份原始导出、单次报告和对应录屏。
- CPU、Memory、FPS/GPU、Network 的同场设置截图与数据文件。
- App 重启、断连、指标灰置、短测试和上传失败样本。
- 逐屏交互台账，仅描述行为，不复制厂商素材进入产品。
账号边界。
使用已登录浏览器会话，不读取或保存密码、Cookie、token。若需要上传 Perfowl 生成的 fixture 到第三方账号，必须在上传前单独确认具体文件和目的。
Evidence package
每个实验的标准产物
docs/validation/results/f0/<experiment-id>/
├── manifest.json # 环境、版本、设备/App 哈希、命令与时间
├── procedure.md # 可复现步骤与偏差说明
├── raw/ # DVT、PerfDog、xctrace、系统日志原始证据
├── normalized/ # 版本化映射后的中间数据
├── analysis/ # 误差、统计、图表和质量计数
├── checksums.txt # 原始 Artifact 哈希
└── conclusion.md # Pass / Experimental / Unsupported / Blocked| 证据等级 | 定义 | 可支持的结论 |
|---|---|---|
| E0 | 官方文档、API/源码静态入口 | 能力可能存在，不能证明当前设备可用 |
| E1 | 本机命令/Schema 冒烟或固定 fixture | 入口与解析可运行，不能证明指标准确 |
| E2 | 真机单轮、原始数据和明确版本 | 该组合可用，不能证明重复性和误差 |
| E3 | 三轮真机对照、误差与开销完整 | 可进入指定支持矩阵和 Metric Registry |
| E4 | 60 分钟、异常恢复、打包环境与回放通过 | 可进入 M1 产品化计划 |
Pass and stop rules
总体通过条件与停止条件
F0 Pass
- pymobiledevice3 在承诺矩阵无阻断性连接缺口。
- P0 指标形成 Metric Registry，且每项达到 E3。
- 基础模式工具开销、60 分钟稳定性和恢复达到 E4。
- xctrace 并发形成明确 Allow/Separate 结论。
- 授权和随包交付结论可执行。
- 原始 fixture、兼容矩阵和报告可复现。
立即停止并回到决策
- 目标首发 iOS 通道无法稳定建立 DVT。
- CPU/Memory/FPS 关键指标无法确认单位或 scope。
- 基础采集显著改变被测 App 性能且无法降级。
- GPL-3.0 交付方案不满足产品交付要求。
- 同一来源三轮结果不可重复，或原始数据无法保留。
- 需要改包、注入或默认 WDA 才能达到首版承诺。
部分通过。
单项失败不自动拖垮全部 F0。可将该指标降为 Experimental/Unsupported 或从 M1 删除；但连接、App/进程、CPU、Footprint Memory、Session 完整性、工具开销和授权交付属于基座 P0，任一阻断都不能进入 M0。
Execution order
执行顺序
| 批次 | 实验 | 依赖 | 停止点 |
|---|---|---|---|
| A 静态门禁 | F0-00、版本冻结、设备/Fixture 清单 | 无需真机 | 授权或材料不具备时先停 |
| B 连接与身份 | F0-01、F0-02 | D1–D4 可用设备 | iOS 16 USB 只读冒烟 Partial / E2；Fixture 构建 PASS，签名 Blocked；完成动态 Route/重绑定后再开指标 |
| C 核心指标 | F0-03、04、05、06、07、08 | A1 + Xcode + PerfDog 样本 | 逐指标形成 Metric ADR |
| D 增强与开销 | F0-09、F0-10 | 核心指标基线已稳定 | 决定 xctrace 并发策略 |
| E 产品化门禁 | F0-11、F0-12 | 正式候选字段与 route 冻结 | 产出最终 F0 报告并申请 M0 |
Required resources
执行前需要提供或确认的资源
- 目标支持范围
首版最低 macOS、是否支持 Intel、最低 iOS，以及当前可用设备对应 D1–D4 哪些通道。
- 可控 Fixture
用于 CPU、内存、FPS、网络和重启的自有测试 App；若不存在，需要先单独批准创建测试 Fixture。
- PerfDog 资料
你准备提供的官方文档地址，以及方便进行只读对照的付费账号已登录窗口。
- 真机操作窗口
明确允许连接哪些设备、是否允许开启 Developer Mode/挂载镜像、是否允许运行 xctrace，以及设备数据保留边界。
Execution approval
本计划的批准边界
2026-09-01 用户已批准执行 F0，A 批次已完成。
静态门禁结论、版本冻结、GPL-3.0 交付边界、Host/Fixture 清单和 B 批次进入条件见 《Gate F0 · A 批次静态门禁结果 v1》。
B 批次已开始但尚未通过。
已对当前 USB iOS 16.6.1 设备完成只读发现、Lockdown、App/进程和 DVT 冒烟，详见 《B 批次连接冒烟结果 v1》；Fixture 已完成未签名 Release arm64 构建，但因缺 Apple Development 身份及匹配 profile 而停在签名，详见 《Fixture 构建与签名结果 v1》。
当前新增的 Fixture 是 Gate F0 受控测试产物，不是正式 Collector。本轮未开发 Mac App、后端或 Web，也未安装 Fixture，未启动指标流、xctrace 录制或 PerfDog 对照。
依据
- Perfowl Mac + Cloud 基座方案 v1 — 已批准的产品、技术栈、范围和阶段门禁。
- Perfowl 无侵入底层能力决策 v1 — pymobiledevice3 主链、xctrace 增强和指标边界。
- Codesign4QC 性能采集专项分析 — 参考实现、长会话证据和需修正问题。
- Apple Instruments 专项调研 — Trace、模板、xctrace 和证据边界。
- PerfDog 官方客户端说明 — iOS 指标、无侵入工作流和 Web 管理。
- pymobiledevice3 iOS 17+ tunnel 指南 — route 与权限矩阵。
- pymobiledevice3 DVT API — Sysmontap、Graphics、Network、Energy 等入口。