Perfowl Collector Core 单 DTX 基座与版本冻结决策 ​

批次结论 ​

Perfowl 不再把 pymobiledevice3 与 py-ios-device 设计为两个并行运行的采集 Provider。新基座定为 Perfowl Collector Core：以 pymobiledevice3 作为唯一设备连接、Tunnel、RSD 和 DTX 内核，在同一个 DvtProvider / DTXConnection 上补充 Perfowl 自己的深度采集 Adapter；py-ios-device 仅作为深度协议、字段、解码器与反例算法的冻结研究来源。

这意味着“结合两个库的优势”不是合并两套 socket、线程和生命周期，而是：

1. 保留 pymobiledevice3 的现代连接与 DTX 实现；
2. 将 py-ios-device 多出的 Channel、selector、配置、raw schema 和解码知识迁移为 Perfowl Adapter；
3. 所有 raw event 进入 Perfowl 自己的质量层和 Metric Engine；
4. 相同指标只选择一个 Session 级主源，禁止同一曲线混用两种口径。

本批只完成版本冻结、静态能力对照、架构与升级门禁，证据等级是 E1。没有修改 MacApp/、没有替换当前 Collector，也没有产生新版真机可用结论。

冻结版本 ​

“最新”只用于进入候选评估。正式基线始终固定精确版本、commit、依赖锁和 hash，不追随浮动 latest。

为什么以 pymobiledevice3 为内核 ​

冻结源码显示，pymobiledevice3 v11.3.1 已有：

• 设备发现、配对、Lockdown、Developer image、RSD 与 iOS 17+ Tunnel 路由；
• 支持预构建 DTXConnection 的 DvtProvider，可以让多个 service wrapper 复用同一 transport；
• Sysmontap、Graphics、NetworkMonitor、EnergyMonitor、Notifications、CoreProfileSessionTap、Screenshot 与 ProcessControl；
• 通用 TapChannel 以及 async service / notification 分发模型。

py-ios-device 的独特价值集中在深度采集与解析：

• NetworkStatistics 按 PID 的 debug gauge 调用；
• CoreProfile/KDebug 的事件识别、逐帧和生命周期解析线索；
• Metal GPU 的设备 schema、counter 配置和流解码；
• App Launch Lifecycle 阶段解析；
• 已知算法反例，例如旧代码中曾出现固定 time factor、实验性 GPU 解析与直接输出最终 Jank。

因此，复制 py-ios-device 的整个连接层只会重复 USBMux、Lockdown、RemoteLockdown 和 DTX，并增加抢读与关闭顺序风险；迁移其深度协议知识才是有增量价值的部分。

目标架构 ​

Perfowl Mac App
  └── IPC
      └── Perfowl Collector Sidecar
          └── Perfowl Collector Core
              ├── DeviceGateway                     [pymobiledevice3]
              │   ├── USBMux / Pairing / Lockdown
              │   ├── Developer image
              │   └── RSD / Tunnel route
              ├── DtxSessionOwner                   [唯一所有者]
              │   ├── DvtProvider
              │   ├── DTXConnection
              │   ├── Channel Router
              │   └── request / reply / event dispatcher
              ├── CollectorAdapter
              │   ├── SysmonAdapter
              │   ├── GraphicsAdapter
              │   ├── DeviceNetworkAdapter
              │   ├── CoreProfileAdapter
              │   ├── ProcessNetworkAdapter
              │   ├── EnergyAdapter
              │   ├── GPUCounterAdapter
              │   └── LifecycleAdapter
              ├── Raw Event + Quality Layer
              └── Metric Engine

不变约束 ​

• 一个 DeviceSession 只有一个 DtxSessionOwner；
• 只有底层 DTXConnection 可以读取 transport；Adapter 只消费按 channel 分发的数据；
• Mac App、Session Schema 和 UI 不引用两上游库的类或输出格式；
• Adapter 输出 raw fact，不直接发布 FPS、Jank、Energy 或 StartupTiming；
• Session 开始后固定 source plan；不静默切源；
• 缺失、断流、重连、重置和未知 schema 显式标记，缺值不写成 0。

新库的稳定接口 ​

DeviceGateway ​

负责设备、应用与连接路线，不暴露 pymobiledevice3 对象到 UI：

discoverDevices() -> DeviceSnapshot[]
listApplications(deviceKey) -> ApplicationSnapshot[]
openSession(deviceKey) -> DeviceSession
probeCapabilities(session) -> CapabilitySnapshot

DtxSessionOwner ​

负责唯一 DTX 生命周期：

openChannel(identifier, serviceType)
invoke(channel, selector, arguments, replyPolicy)
subscribe(channel, eventKind)
close(reason)

必须具备 bounded queue、channel 级丢包计数、请求超时、停止顺序、重连 generation 和 backpressure 记录。

CollectorAdapter ​

每项采集能力遵守同一协议：

adapterID / adapterVersion
requiredCapabilities
probe(session) -> supported | unsupported(reason) | candidate(reason)
prepare(target, options)
start()
rawEvents()
stop()

RawEventEnvelope ​

最小审计字段：

eventType
service / channel / selector
transportSource / adapterID / adapterVersion
upstreamVersion / upstreamCommit
deviceMachTimestamp / machNumer / machDenom
hostReceiveMonotonicNs / wallTimestamp
targetPID / targetGeneration / identityStatus
scope / rawUnit
rawPayload / rawPayloadHash
decodeStatus / quality / droppedEventCount / reconnectGeneration

重叠指标如何选择“支持最好”的方式 ​

选择单位是“原始数据源 + Adapter + 公式版本”，不是库名。每个指标先建立候选集，再按同一 Fixture、同一设备、同一 App、同一时间窗 A/B。

硬门槛 ​

任一项不满足就不能成为默认源：

• Bundle ID → PID → process generation 身份闭环；
• scope 与 unit 可以从协议和实验同时证明；
• warmup、counter reset、进程重启与 missing 不转 0；
• 30 分钟采集无不可解释断流，stop 后无残留 reader；
• iOS 版本不支持时 fail-closed；
• raw 可保存、可脱机重放、可追溯到 Adapter 与算法版本。

评分模型 ​

同分时优先顺序：pymobiledevice3 已有 wrapper → Perfowl 基于 pymobiledevice3 DTX 的自有 Adapter → 更复杂的自有 decoder。py-ios-device 的最终格式化指标不直接成为候选。

初始来源决策 ​

iOS 15+ 路线 ​

升级风险 ​

当前 Collector 直接依赖旧版同步 RemoteServer、MessageAux、Tap、DvtSecureSocketProxyService 和自定义 DVTEventPump。v11.3.1 已转向 async DvtProvider / DTXConnection / DTXService，因此升级会触及：

1. 连接创建与关闭方式；
2. ProcessControl / DeviceInfo 请求响应；
3. Sysmontap、Graphics 与 Network 的读取方式；
4. Sidecar 主循环和取消模型；
5. PyInstaller hidden imports 与双架构打包；
6. 现有 raw fixture 的兼容和 provenance 字段。

升级必须建立并行的 legacy-4.21.3 与 core-11.3.1 Adapter，通过门禁前不删除旧链，也不把当前默认源直接切到新版。

实施批次与批准边界 ​

下一次产品代码批准建议限定为 CORE-1。它只建立新核心接口、锁定依赖和离线测试，不切换用户当前可用链路；完成并提交后再单独批准 CORE-2。

许可与分发门禁 ​

pymobiledevice3 标注 GPL-3.0-or-later，py-ios-device 仓库包含 GPL-3.0 许可证。直接复制、修改或组合源码时，新库的许可证、对应源码、修改声明、NOTICE、安装信息与 Mac App 聚合/衍生边界需要正式法务结论。独立 Sidecar 与 IPC 是工程隔离，不自动形成许可豁免。

当前决策允许内部 E1/E2/E4 实验；对外 App/DMG 分发仍保持 Hold。

证据来源 ​

• pymobiledevice3 v11.3.1
• pymobiledevice3 DVT API
• pymobiledevice3 iOS 17+ Tunnel 指南
• py-ios-device 源码与能力说明
• py-ios-device 2.4.25 发布包

冻结归档：Perfowl Collector Core 单 DTX 基座决策归档。