CORE-13 Collector Core 默认实时链切换方案

目标与边界

Mac App 默认启动打包后的 perfowl_collector_core stream，旧 perfowl_collector 只保留为显式 PERFOWL_COLLECTOR_MODE=legacy 回滚。设备发现、User App 枚举、截图与现有 Session UI 不重写。本批不删除旧 Sidecar，不把 TinyJank/Smooth 或秒级 FPS 提升成逐帧真值。

实时协议

Core 输出兼容宿主解码器的 perfowl.collector/1 NDJSON，事件顺序为 hello → ready/capabilities → waiting/target_identity/attached → sample* → stop_requested → stopped。stdin 仅接受同协议 stop/ping；错误走结构化 error 与 stderr。每个 wire event 有独立递增 sequence、UTC timestamp 和 host monotonic ns。

实时指标投影公式

实时 UI 值来自同一条已归档 raw event 经 RawMetricEngine 的不可变公式派生，不另写第二套业务算法：

• gauge：取目标 PID、当前 generation、身份 verified 的有限源值；missing 不沿用前一进程值。
• counter rate：同 PID + generation 的相邻 counter 差 / host monotonic 秒；首点 warmup、负差 counter-reset、非正窗口 invalid-window。
• device network：窗口内 ConnectionUpdateEvent.tx_bytes/rx_bytes 求和 / 相邻 Sysmontap host monotonic 秒；首窗口 warmup。
• process network：net.tx.bytes.delta/net.rx.bytes.delta / 同身份相邻 host monotonic 秒。
• 实时 Network scope：process Send/Recv 同时有效才选 process；否则 device Send/Recv 同时有效才整对回退，禁止混合 scope。
• UI sample cadence：以 Sysmontap raw envelope 为采样锚；Graphics、Network 等异步源使用同 target generation 的最近状态。跨 PID/reconnect 时清空投影缓存。
• 计算层不取整；真实 0 保留；missing/warmup/reset 不写成 0。

Session 与停止

产品 Session 下新增 collector-core/ 子 Session，Core 直接写入 raw-events.jsonl 与 hash manifest。正常停止先停 Adapter、逆序关闭单 DTX owner、fsync/finalize raw，再由同一个 Core 执行 metrics/report/startup/delivery 收口。目标未运行时保持 waiting；目标重启时关闭当前 DTX generation 后重连并重新绑定。

验收

1. Python：投影公式、scope 不混合、控制协议、停止和 raw hash。
2. Swift：默认 Core、显式 legacy 回滚、Core 参数、握手/停止、Core finalize。
3. App：内置 Core/runtime，默认路径为 Core。
4. 真机 E4：设备 A / 目标 App A 完成“选择→开始→动态样本→停止→nested Core manifest→29 Stat→delivery”；identity verified、drop=0、缺值不补 0。
5. 失败时保留旧 Sidecar 回滚，不自动静默降级。

2026-09-05 验收结果

• E2 Python：83/83；Swift：68/68；VitePress 构建通过；git diff --check 通过。
• E2 产物：x86_64 perfowl_collector_core 重建成功；App 包内默认携带 Core 及独立 runtime，ad-hoc 深度签名校验通过。
• E4 匿名真机：设备 A / 目标 App A 在 iOS 16 完成默认 stream链，有 7 个实时 sample，采样间隔 min/median/max = 0.954/0.994/1.078 s，134 条 raw event，32 个 observed metricID，29 项 Stat，identity=verified，drop high water=0，无 error。
• 正常 stop 顺序观察为 stop_requested → raw finalize → metric/report/startup/delivery → stopped；stopped 回传 sample=7、raw=134、Stat=29。
• 本次目标 App A 不在前台，7 个 sample 仅验证进程/设备指标动态值；FPS/GPU 按 not-foreground 保持 missing，没有误归因。

交付边界

CORE-13 已将新 Core 切为 Mac App 默认实时链，旧 Sidecar 只能通过 PERFOWL_COLLECTOR_MODE=legacy 显式回滚。当 Core 不存在时启动 fail closed，不会静默切回旧链。iOS 15 / 17+ / 18+ 真机矩阵、前台 FPS/GPU 人工 UI 录证、逐帧源与公开分发仍是独立门禁。