独立帧来源管理与默认全指标采集改造方案

1. 本轮任务、基线与结论

Owner要求：先制定详细方案；FTime激活与启动指标解耦；默认勾选所有当前满足采集条件的指标，包含启动与截图，用户明确取消才排除，尽最大能力采集。

本批唯一类型为devlog / plan，承担方案制定与实施准备，不代替独立指标验收。本批只交付方案与文档，不修改产品代码，不操作手机，不启动录制，不生成新App包。正式验收保持55/66、余11项暂停；Build234仍是原安装版本。方案状态partial表示尚未实现、资源及E4门开放，不是产品已具备新行为。

• 实施工作树：/Users/itreenewbee/.codex/worktrees/perfowl-metric-comparison-20261028/perfowl。
• 分支：codex/metric-comparison-round2-20261028；方案起点HEAD：58215dd7188b6a0816b2ad308fb5d5b20592a7ee。
• 本地main为b64c1e46；不切换、不合并、不修改主工作树，不夹带未跟踪证据或其他设计文件。
• 延续首段缺失修复、第二轮采集合同及五项反馈修复，不覆盖历史结论。

决策摘要：独立帧来源管理器＋设备级CoreProfile租约；全量采集意图减明确取消项＋能力解析；运行与报告共用来源分段账本。不以删除一个条件判断替代生命周期改造。

1.1 已确认交互边界

Owner已明确回复：“下次测试生效，当前测试计划不变”。因此采集设置修改从下一Session生效，当前Session不变，界面明确提示；仅隐藏图表不改变采集。本批不增加运行中计划修订或即时停源功能，不设逐批Owner审批门槛。

2. 已核实的问题与影响（E1）

源代码定位：Swift的WorkbenchModels.swift、CapturePlan.swift、PerformanceSessionController.swift、SessionStoragePolicy.swift、PerfowlWorkbenchView.swift；Sidecar的capture_plan.py、source_preparation.py、realtime.py、display_performance.py、frame_derivation.py。实施前重新核对准确符号与调用点，不依赖可能过期的注释。

既有证据只解释问题，不等于新方案验证：最近会话ActivityTrace有22499条消息但FrameLifetime匹配0；CP有427次presentation、425个interval、2个epoch，FTime覆盖25/58槽。历史CP某配置约18.76MiB/s，属于负载风险线索，不是本方案每台设备的实测流量。

3. 需求与边界

不在本批实现Hitch、Hang、响应延迟或新的FPS折算，不将FTime倒数替换实际FPS，不改启动candidate.v9或Total设备时钟口径，不自动恢复暂停验收，不以截图作为帧真值。

4. 默认全指标：意图、资格和实际执行分离

4.1 唯一解析模型

定义Registry已实现集合R、用户显式排除集合X、截图意图S：

desiredMetricIDs = R - X
desiredScreenshot = not screenshotExplicitlyExcluded
eligibility = evaluate(desired, device/app/route/power/capability revision)
execution = eligible sources + bounded probes for pending sources
result = requested / excluded / collected / missing-with-reason

desired不因失败或暂不可用被删掉；eligible不是“本次成功有值”。report-only指标按其原始依赖派生，不逐项打开服务。已实现不等于正式验收通过，candidate仍保留candidate质量。

意图持久化为版本化CollectionIntent：policy=all-eligible.v2、标准化的excludedMetricIDs、screenshotsExcluded及preference revision。界面组取消映射成当前组全部真实ID；另存排除组ID，未来同组新增指标继承该组取消，避免升级偷偷恢复。迁移.fps/.frameTime到现有display组，显示折叠/隐藏偏好不进入排除集。

• 新安装：排除集为空；所有组意图on，当前有条件的组显示已选可采，待条件项显示已选待准备/条件原因。
• 旧设置：只迁移有明确“用户取消”证据的记录；历史低成本默认正选集合不推断成用户主动取消其他项。保留原设置备份和migrationVersion，只迁移一次，不每次启动重置。
• 暂不具备条件的行仍可取消采集意图，不能因为行灰掉而失去取消入口。状态标签与勾选状态分开。
• “恢复默认”清空明确排除，重新解析能力，不执行手机动作，不立即启动录制。
• 新指标、新设备能力、连接恢复不清空排除；Registry升级仅下一新Session纳入新ID。
• 全部数值取消、只选截图：v2支持requestedMetricIDs=[]且screenshotsEnabled=true，不打开数值源；全部取消则Start不可用并提示“至少选择一项采集内容”，不偷偷恢复默认。

4.2 能力与条件账本

每个指标/附件至少记录：intent、eligibilityState、reasonCode、required/alternativeSourceIDs、依赖target/route/power、capabilityRevision、observedAt、generation。状态为eligible / pending / unsupported / not-applicable / temporarily-unavailable / failed / resource-limited / user-excluded，严格区分能力、适用性、采集故障和人为取消。

缓存以设备连接generation＋系统/服务schema＋route＋target＋power revision为键；连接、目标、route/power变更触发相关节点失效，不对每条sample全量探测。明确unsupported在当前generation/schema内缓存；失败仅允许下一次用户Prepare/新连接重新探测，不形成后台重试风暴。动态电源条件更新来自已有状态事件/原有低频采样，不增加高频轮询。

Session冻结的是用户意图和策略版本；能力解析是独立有revision的运行账本。Session内条件恢复，可启用冻结意图内的来源，记录准确启用时点与首点warmup；不回填此前缺口。不将能力变化伪装成用户修改计划。若共享源不支持安全重配置，本Session明确deferred-to-next-session，不重启整个采集器。

4.3 逐类采集依赖清单

下表取自当前ios-platform-profiles.candidate.v1.json/metricSourceContracts，是现状基线，不是已完成v2改造或全部E4可用的承诺。P0应产出逐ID的machine-readable allOf/anyOf依赖表及资格测试；表内固定数量由Registry一致性检查锁定。

4.4 启动与截图的副作用

默认选启动不等于在连接、Prepare、勾选时启动/终止App。只在用户明确按Start且所选启动模式要求时执行现有受控启动；界面在Start前说明该模式会重新启动目标。观察现有前台模式不为了“尽力全采”擅自切App、杀进程或制造一次启动。AI在本方案阶段不执行手机动作。

截图统一以CapturePlan.screenshotsEnabled为实际采集总开关：默认采集且保存序列；preview仅决定展示，不反向开启截屏。选中截图但关闭preview仍保存；取消截图时worker、设备请求、JPEG编码、预览刷新及落盘均不启动，已完成历史文件不删除。兼容CLI、prepared及普通Start三条入口，includeScreenshots和旧storage policy不得覆盖显式取消。保留既有1s网格、异步有界编码与JPEG策略，本批不提高频率。

4.5 共享源与禁止采集的精确定义

共享Sysmontap/ActivityTrace可能随其他已选指标返回附带字段。取消项不再申请专用服务、添加专属字段、派生、发布或进入指标导出；若底层支持字段裁剪，应裁剪。底层不可拆的原生共享消息可以随所需源保留在原始证据中，记录incidental，不宣称线上绝不收到一个相关字节。源以消费者引用计数管理，取消FTime不能停掉仍被P95/refresh/jitter或其他指标使用的AT。反之无消费者时应停止专用源并取得stop回执。

5. 独立帧源架构

CollectionIntent + Registry + CapabilityLedger
                    |
             frozen CapturePlan v2
                    |
       metric dependency/source resolver
        |                        |
 normal shared sources      FrameSourceManager
                             |           |
                 shared ActivityTrace   CoreProfileLeaseCoordinator
                                         |                |
                                     startup owner     frame owner
                             \           /
                     FrameSourceSegmentLedger
                               |
              realtime / sealing / report / export

5.1 组件与合同

1. FrameDemand：由真实依赖解析needsFTime / needsATWindowStats / needsFPS，报告帧统计依赖也计入。只要需要FTime/其指定帧派生即能独立请求帧路；FPS-only不自动开启CP。依赖图明确allOf、anyOf、可选补充源，不能再以prepared sources任意一个交集代表全部准备。
2. FrameSourceManager：生命周期start / onSourceEvidence / onFailure / onLease / stop；单写者任务处理状态转换。状态及事件带generation、epoch、planHash；过期回执丢弃并计数。
3. CoreProfileLeaseCoordinator：同设备generation最多一个kperf/CoreProfile录制owner。startup和frame提交请求，串行执行configure/start/stop/drain/lease release；不创建两个互相覆盖的tap。
4. FrameSourceSegmentLedger：增量追加来源选择和质量证据，live与offline共用。不得以某来源是否出现过一条raw数据决定整个Session来源。

frame-only配置复用现有launch_trace.py的帧模板构造，订阅PresentedFrame所需的最小已证过滤，不默认使用完整启动过滤或全量kdebug。现有subclass与exact-debug-id配置应分别保留版本/filters/config hash，并以同场payload、raw和覆盖比较；exact过滤也不能仅凭过滤名就宣称低流量。未证明更优前不顺带变更startup C0模板。

新增模块可采用frame_source_manager.py和coreprofile_lease.py，名称实施时可调整并记偏差；避免整体重写realtime.py。共享AT复用已有订阅，不为FTime重复开同服务。

5.2 默认选源与健康状态

初始优先ActivityTrace FrameLifetime；这是兼容当前路径的决策，不是已经证明所有设备最准确/最轻的结论。CoreProfile PresentedFrame为独立候选路线，不以是否勾选启动作为资格。

健康状态：idle → subscribing → observing → healthy；错误可进入degraded → fallback-pending → healthy(candidate)或failed/resource-limited。healthy建议资格为同target/clock/epoch连续3个有效相邻interval；此阈值是待测策略，不增加3帧均值，不把第1/2个合法值删掉。首次有效数值可在健康资格完成前按既有质量输出，subscription-active与numeric-valid分开。

• 收到消息、白名单匹配、首个孤立结束点都不是有效间隔证明。
• 静态界面无新帧不自动判坏；无运动证据时保持observing/idle-without-evidence并呈现missing，而非0。
• 明确连接、订阅、schema、时钟/身份错误可触发一次fallback。
• 默认全采包含FTime时，8s观察后若AT尚未资格化且CP能力与资源准入成立，可做一次有界CP资格探测；原因是“AT证据不足，探测候选”，不是判定静态场景丢帧。若有已有动态活动线索，可提前进入该调查；线索本身不派生FTime。
• 探测得到至少一个合法CP间隔后可选择CP candidate段；8s内静态无间隔只结束首次资格等待，标记observing/insufficient-evidence，不凭无帧判源坏。若订阅、schema、时钟及资源准入成立，CP可继续有界接收，等待后续真实帧，不因静态首屏使整场后续FTime失效；停止条件是用户Session结束、源错误或明确资源超限。该持续观察资格须经P3资源门验证，未验证的配置只开放显式受控诊断，不宣称默认持续能力。
• 一旦本Session选择CP，晚到AT不自动抢回，防止来回切换；仍可保留AT供其他指标。AT已健康则不保留多余CP frame录制。
• 每generation最多一次自动向CP降级/探测，不能因消息抖动重开generation规避上限；真实重连才重置。重连还须遵循上层已有退避与次数上限。

5.3 与启动并存

启动完成后不为帧重复launch目标；frame等待租约期间其他源继续，不用host时间填补空档。startup失败/取消也必须释放租约；若停止未确认，标记lease-quarantined并阻止新CP启动，健康源继续，禁止两个owner赌并发。启动期间若AT已健康，frame无需接管CP。中途不得用启动需求抢占已运行frame并偷偷重启App；另一次受控启动是新Session或后续明确支持的操作，不在本批实现。

6. 指标公式与质量合同（先入档，实施不改公式）

FTime metricID为ios.frame.time，scope为foreground-device，Registry unit为milliseconds（界面/公式以ms表示），保留候选来源/归属边界，不包装成目标进程逐帧物理真值。

6.1 ActivityTrace FrameLifetime

沿用display_performance.py现有条件：前驱严格衔接prev_mach == last_end_mach，同一身份/epoch/display/foreground，refresh interval有效。

delta_ns = ((end_mach - prev_mach) * numer) // denom
FTime_ms = round(delta_ns / 1_000_000, 6)

首点warmup；不相邻/非正/乱序点不输出正常值；大于12个refresh周期按既有source-gap语义处理，不称为确认丢帧。具体raw字段schema、时钟桥和关联键沿用现有解析器及Canonical指标页，实施前以固定fixture锁定。

6.2 CoreProfile PresentedFrame

沿用frame_derivation.py的PresentedFrame debug ID 0x31800318：

timestamp_ns = (mach_ticks * numer) // denom
FTime_ms = (timestamp_ns - previous_timestamp_ns) / 1_000_000

相同epoch内相邻有效presentation成对；首点warmup，非递增点为out-of-order；继续candidate。CP的设备/连接/配置身份校验不能冒充逐帧目标进程归属；若原始事件未携带可证明的归属，继续foreground-device及candidate边界，不把租约配置目标当作每帧target证明。该路径“先每点转ns再作差”与AT“先差再转ns”可有取整差异，本批不合并公式或宣称精度等价。

6.3 分段和缺值

每次切源/重连/时钟或归属变化均开启新epoch，清前驱，首点warmup。禁止跨来源、epoch或身份作差；不回填/插值/用FPS倒数补FTime；missing与合法0仍按各指标原合同。CP FTime不得替代AT专属P95/refresh/jitter，缺独立证据则这些指标missing；不把CP间隔同时算成另一个源的重复帧。

Ledger逐段记录sourceID / generation / epoch / start-end / reason / identity-validation / clock / algorithmVersion / candidate / gap / counters；引用有限诊断而不是复制原始载荷。新实时、封存、CSV/Excel统一按已选段读数。跨AT/CP等价性门未关闭前，不生成混源整段帧统计：可按来源段展示，现有汇总留空并保留原因；单源完整段沿用既有统计。普通报告维持既有面向用户的简明表现，诊断/raw保留全部证据，不把内部字段堆到用户主界面。

旧Session无ledger时走版本化legacy reader，保持历史公式与结果，不用新策略重写历史原件。新旧算法版本和source contract先更新唯一Canonical指标知识页，再进入代码；不新建一串版本知识页。

7. CapturePlan v2与跨语言迁移

选用schema v2，不原地改变v1 canonical/hash。Swift/Python继续支持v1读取与原hash；新Session写v2，sidecar握手明确支持版本，旧sidecar遇v2返回版本不匹配且提示更新，不偷偷降成不同语义计划。

v2保留requestedMetricIDs为冻结desired数值集合，保留startup/screenshots显式布尔及Registry hash；新增selectionPolicyVersion、intentRevision、标准化excludedMetricIDs/excludedGroupIDs、frameSourcePolicyVersion。完整字段表、缺省、canonical排序、枚举及null规则在P0先以Swift/Python共享golden JSON冻结。排除字段与requested集合冲突直接拒绝；unknown ID不默默丢弃。

能力结果和动态来源账本不进冻结plan hash，独立保存并引用planHash、capabilityRevision及epoch。startupEnabled须与请求启动ID一致；截图单独开关，不由storage preview反算。v2允许截图only空数值集合；v1保持非空合同。制品reader和导出器按schema分发，canonical hash测试至少覆盖v1原golden、v2完整/截图only、乱序/重复标准化、非法冲突、unknown版本。

8. 性能、资源、并发和超时门禁

以下均为实施目标/拟定门槛，非实测通过值。P0先测同规模基线，若既有实际chunk上界与拟定限值冲突，须在代码前追加原因与预算决策，不能直接扩大无界队列。

上述阶段保守串行合计上界：运输准备12s＋AT资格观察8s＋租约等待最多19s（startup 15s＋drain 4s）＋fallback完成20s＝59s；实际阶段可重叠，但不以重叠保证更快。租约等待到期记录deferred/lease-unavailable，其他源不等待；此数只约束该控制链，不包含用户外部操作及既有封存阶段。实施须同时测全Session首响应与结束耗时。

默认尽力不是无限耗资源。实际超预算时只停止问题专用源，标注resource-limited、已收字节与时间，保留用户意图，不伪装不支持或用户取消；所有其他健康指标继续。持续CP默认策略开放前，必须有同设备受控场景资源比较；若仍接近历史高流量，不将它描述为轻量持续采集，也不以静默关闭FTime交差。

流量同时区分DTX服务接收payload bytes、raw写盘bytes、实际USB/网络链路bytes。前两者可内部计数，链路测不到则明确未测，禁止用payload冒充线速；报告MiB/s、MiB/min和预计小时量，区分derived-only/full raw及截图。截图按实际JPEG尺寸×实际成功张数统计，不预设固定压缩比例。

8.1 基准矩阵与执行时间预算

1. 同一固定raw分别运行baseline与candidate，各3次，报告中位数、最差与原始收据。样本覆盖60s、1h、4h时间跨度及60/120/240事件每秒重放；离线加速重放衡量吞吐，不冒充连续4小时内存稳定。
2. 最坏输入覆盖既有真实最大CP chunk、stackshot与截图JPEG并发、发布1Hz、source错序/断连/stop；记录首响应、长任务完成、p50/p95/max延迟、CPU、RSS、队列峰值、落盘量和missing/drop。
3. 管理器单测/契约测试目标分钟级，聚焦回归预算≤10min，全量回归按当前实测基线单列；每个基准子进程最长120s、批次最长15min，超时保留失败回执，不自动反复重跑。
4. Owner许可的新鲜E4分静态前台基线、受控动态、长稳各组，比较AT-only、CP-only、自动策略及全默认；阶段性计划15min、1h、4h实时时长，不在本方案阶段执行。AI不自动滑动/切App。
5. 测试前磁盘≥10GiB且≥预计新增量两倍；按实际接收率预测下一检查前增长，预计触线就提前停止新采集。首次、每批后、持续期间每30min检查；保留raw/失败证据，不按年龄删除。

9. 实施拆分、文件范围与交付物

上述P0–P4是本改造子批次，不改变站点总阶段P6。各批实际修改、偏差、测试、剩余门追加到本文带日期Implementation/Validation Update；不写“代码完成”等于指标验收完成。无批量全目录重构，不改Hitch与其他指标公式。

10. 必测矩阵

当前回归参考：最近Python/native3097项有1失败、1错误已在旧基线复现；Swift438项、12skip、0失败。实施前复跑匹配范围并固定错误签名；语义改变导致旧默认选择断言失效，应按新合同更新对应断言，不删测/跳过充绿。与本批无关的原始数据失败单列，不擅自扩修。

11. 回滚与验收门

• 以版本化selection/frame policy开关隔离新策略；回滚不删除排除偏好，不把用户取消项复位，不重写既有Session/raw。
• App与Sidecar必须同版本交付；回退旧包时恢复对应policy reader，必要回滚保留私有目录，不并行安装第二个标准App。
• 自动策略资源或正确性门失败：保留独立frame和诊断证据，不静默宣称完成；局部停用新策略并在实施记录给出修正决策。
• E1设计/静态、E2软件/制品、E3环境、E4新真机分别报告；正式55/66与剩11项不由本批软件结果自动更改。
• 产品实现交付按AGENTS要求窄提交、双远程同SHA、签名/公证/staple/Gatekeeper、独立安装与SHA；延续Owner既有公证暂缓指示时明确partial，不声称正式可分发。GPL门保持独立，不由公证代替。
• 标准安装只在/Applications/Perfowl.app，先确认实际空闲退出。当前方案交付不换包、不安装。

12. 文档、发布与执行交接

本批计划登记时间线及handoff，新增不可变HTML快照；仅描述计划，不修改知识库、首页指标计数或55/66状态。实施涉及公式/来源/质量变更时，同批更新唯一Canonical指标页、知识总览、首页及C1–C7联动，先文档后代码。生产发布遵守来源权威门，不从feature/WIP绕过发布保护。

下一Implementation执行指令（计划文档先行；不表示独立验收已通过）：

> 在本任务metric-comparison工作树，以58215dd7及本方案文档提交为基线，按本文P0→P4顺序实现“独立帧来源管理＋默认全量意图减用户排除”。先冻结v2合同、能力依赖及基准；所有服务入口遵守排除，截图preview不得反向开启采集；startup/frame共享独占租约，live/report共用分段来源。按Owner已确认的下一Session生效，不擅自实现运行中计划修订。不扩至Hitch/Hang或其他公式，不操作手机，不恢复11项验收、不碰原主树或无关WIP。每批在本文追加实际修改/偏差/验证/遗留，返回窄提交与双远程状态、基准和测试收据、真实制品/签名状态及Owner复测步骤；自测结论不代替Lead独立验收。

13. Validation Update · 2026-10-29（方案批次）

已重新核对工作树HEAD、main ref、源代码核心门控及默认集合，保留所有原有未跟踪文件。本批尚无产品实现或新真机证据。完整文档、归档、站点与交付检查以本节后续实际记录和私有收据为准；待执行结果不预写成功。