文档中心/产品方案/Perfowl 成熟方案 v1
已暂停2026-09-01

Architecture 01 · iOS-first Performance Platform

Perfowl 产品成熟方案 v1：先建立可信 iOS 性能闭环，再逐层对齐 PerfDog

这份方案把 client_perf、Codesign4QC、Apple Instruments、DVT 开源生态和 PerfDog 产品调研合并为一套可长期演进的产品架构，同时明确哪些决策已经成熟、哪些仍需真实设备与样本才能定案。

历史草案 · 已暂停等待无侵入底层决策不可作为开发依据

Decision

决策结论

2026-09-01 状态更新：本方案已暂停。
产品已明确为无侵入测试，决策顺序调整为“先确定底层能力，再设计架构”。本草案包含 Extension/Probe 等不符合当前边界的内容，仅保留为历史记录。后续以 《Perfowl 无侵入底层能力决策 v1》 为前置依据，确认后再整体修订架构。
历史草案当时的判断（当前不生效）。
原草案曾采用 iOS-first、General Monitoring + Deep Diagnosis 双模式及 DVT + xctrace + Extension 混合路线。由于 Extension 不符合当前无侵入边界，相关结论必须在底层能力确认后重做。
现有调研尚不足以批准正式采集开发。
采集主实现、FrameTime/Jank 数据源、GPU 单位、CPU/内存口径、60/90/120Hz 动态刷新率、iOS 版本兼容和工具自身开销都缺同场证据。因此方案在 Gate 0：真值与可行性验证 暂停；Gate 0 通过后再提交实施计划。
iOS-first
首个产品范围
2 Modes
通用监控 + 深度诊断
3 Sources
DVT + xctrace + Extension

开发启动条件

Gate 0 的指标对照、采集器对比、兼容矩阵和开销实验全部出具可复现报告。

首版成功标准

可信、稳定、可解释、可回放，而不是先追求七平台、云端和 AI 功能数量。

ADR-001

架构决策记录

项目决定
状态Proposed · 等待 Gate 0 证据和用户批准
产品范围第一阶段只做 macOS Host + iOS 真机，先覆盖通用 App/游戏性能监控主路径
采集架构DVT GeneralCollector 负责持续实时指标；xctrace TraceAdapter 负责按需深度诊断；ExtensionSDK 负责业务语义
数据原则原始数据 append-only；Normalized Metric 与 Analysis 可重算；所有指标携带来源、单位、方法版本和质量
交付形态原生 macOS 桌面端为第一入口；本地 Service/CLI 在稳定桌面主链路后开放；云端最后建设
关键后果架构可容纳采集器替换和跨平台 Adapter，但前期需要投入统一时钟、能力矩阵、Session Schema 和验证实验室

Product contract

目标、用户与边界

目标用户

性能测试、客户端开发、游戏研发、质量平台和设备实验室团队；既支持手工探索，也支持自动化回归。

核心任务

连接设备 → 选择 App/进程 → 选择模板 → 采集并标记场景 → 定位异常区间 → 对比基线 → 导出可追踪报告。

首版范围

iOS CPU、内存、FPS 趋势、GPU、网络累计量、线程/唤醒等基础指标；实时曲线、Marker/Scene、Session 回放、报告和质量状态。

后续范围

FrameTime/Jank、启动、日志/Crash/Jetsam、Time Profiler、Hitches、GPU Counter、网络事务、能耗、CLI/CI、多设备和 Extension。

明确后置

Android/PC/主机、云组织/RBAC、MCP、Skills 和 AI 分析。它们依赖稳定的数据本体，不进入第一阶段关键路径。

非目标

不照搬 PerfDog 页面结构，不把厂商算法当绝对真值，不用 Simulator 结果代表真机，不用“有曲线”代替数据可信度。

Reuse map

当前基座能力如何进入 Perfowl

输入可复用思想需要重做进入模块
client_perfgo-ios + py-ios-device 组合、每设备长连接、任务/标签/对比、原始数据归档采样调度、生命周期、数据模型、错误状态、安装可用性与统计DeviceRuntime 参考、用户工作流参考
Codesign4QCprovider 隔离、PID 重绑 generation、Schema v2、优先级背压、质量计数、Session、Marker、离线报告GPU 单位、多场景规则、指标请求注册、时钟和高频报告内存GeneralCollector、EventPipeline、SessionStore 核心参考
Apple InstrumentsTemplate/Instrument、Trace/Run、Track/Detail/Inspector、原始与 Modeler 分离、Profile→Fix→Verifyxctrace 实时化假设、固定 XPath、对第三方 App 源码级诊断预期TraceAdapter、分析体验与验证基准
pymobiledevice3现代 DVT、iOS 17+ tunnel、Sysmontap/Graphics/Network/Energy/Core Profile持续流、自动化并存、断连、版本和分发回归GeneralCollector 默认候选
go-ios跨平台二进制、设备与 tunnel 控制、Sysmontap复杂 DTX payload、持续 Core Profile 与版本兼容DeviceRuntime/Collector 备选候选
py-ios-device120Hz、Jank、网络、生命周期、GPU Counter 的实现线索原始事件、算法和真值证据FrameLab 研究输入，不直接进入产品
PerfDog 公开接口Service、CLI、报告上传、Label/Note、自定义指标和多设备工作流内部实现、算法与精度需独立验证产品能力目标与外部 API 参考

High-level architecture

总体架构：单机分层、采集器可替换

Perfowl Desktop设备、任务、实时曲线、回放、对比、报告、诊断中心
Session Orchestrator状态机、能力协商、模板、进程绑定、生命周期
Collector Supervisorsidecar 启停、心跳、重试、背压、故障隔离
Source AdaptersDVT General / xctrace Deep / Extension / Screenshot / Log
Event Pipeline时钟映射、标准化、质量、不可变事件、派生指标
Session StoreManifest、Chunk、SQLite Index、Trace、截图、报告

建议宿主技术

  • 桌面端：Swift + SwiftUI 负责应用壳和业务状态；高密度时间线使用独立 ChartRenderer 协议，先以 Canvas/AppKit 实现并通过十万点交互基准决定是否下沉 Metal。
  • 核心领域：纯 Swift Package，包含 Session、Metric Registry、Query、Analysis、Rule、Report；不依赖具体 UI，后续 Desktop/CLI/Service 共用。
  • 采集 Sidecar：通过稳定的 Protobuf 契约与 Host 隔离。Gate 0 默认比较 pymobiledevice3 与 go-ios，不在业务代码中暴露任一库的数据结构。
  • xctrace：复用用户系统中可用的 Xcode，作为可选 Deep Adapter；不存在或版本不支持时返回明确 capability 状态。
  • 外部接口：MVP 后开放本机 gRPC Service 与 CLI；内部 Sidecar IPC 优先使用 Unix Domain Socket + length-delimited Protobuf，默认不监听局域网。

Module boundaries

模块职责与禁止越界

模块职责输入 / 输出禁止承担
DeviceRuntimeHotplug、配对、Developer Mode、DDI、iOS 17+ tunnel、App/进程枚举DeviceCapabilitySnapshot、连接状态指标算法和 UI 展示
SessionOrchestrator创建 Run、选择模板、绑定设备/App/进程、协调所有 CollectorSessionPlan → SessionState/Event解析私有协议细节
CollectorSupervisor进程隔离、心跳、取消、超时、重启预算、stderr 诊断、版本/哈希CollectorCommand ↔ CollectorEnvelope静默重试和丢弃错误
GeneralCollectorSysmontap/Graphics 等持续指标、进程重绑、raw eventSourceEvent + CapabilityJank/Pass/Fail 结论
TraceAdapterxctrace record/export/symbolicate、Trace 产物与 Schema 快照TracePlan → Artifact/Event强行提供低延迟实时曲线
ExtensionGateway接收 Marker、Interval、Scene、Custom Metric 与引擎数据ExtensionEvent影响基础采集成败
ClockSync保留设备/Host/Collector 原始时钟，估计映射、偏差与误差ClockSample → ClockModel覆盖原始时间戳
EventPipeline验证 Envelope、优先级背压、顺序/Gap、规范化、批量持久化SourceEvent → Raw/Metric/Quality Event把 unsupported/missing 写成 0
MetricRegistry定义 ID、scope、source、unit、methodVersion、转换和兼容规则MetricDefinition根据 UI 文案猜单位
AnalysisEngine区间统计、分位数、Frame/Jank、规则、基线和异常关联Raw Event + ModelVersion → Derived Event修改原始数据
SessionStoreappend-only Chunk、索引、截图/日志/Trace、校验和、迁移Session Artifact把 HTML/CSV 当唯一事实源
Query/Chart窗口查询、极值保留下采样、十字线、区间联动、质量 OverlayQuery → Series/Annotation自行重新定义指标算法
ReportEngine离线 HTML、JSON 摘要、CSV、对比结论和证据链接Session + Analysis → Report省略质量/口径/样本不足

Canonical data contract

统一事件、指标和 Session 数据模型

事件 Envelope 最小字段

字段组字段说明
身份schemaVersion、eventId、sessionId、runId支持幂等、升级和多轮次
来源sourceId、collectorVersion、deviceId、processIdentity、generation进程重启后代际隔离
时钟sourceMonotonicNs、hostMonotonicNs、wallClockNs、clockModelId、clockErrorNs保留原始时钟和映射误差
序列sequence、priority、payloadType检测 Gap、乱序、重复和背压
质量status、ageNs、coverage、errorCodeOK/Stale/Missing/Unsupported/Error 不与数值混合

Metric Definition

每个指标必须定义 metricId、显示名、domain、scope、source、rawUnit、canonicalUnit、normalization、aggregation、methodVersion、supportedPredicate、expectedCadence、qualityPolicy。CPU 原始多核值与 normalized 值、GPU 0–1 与 0–100、Footprint 与 Resident 均使用不同字段或明确转换，禁止同名覆盖。

Session 目录

路径内容事实等级
manifest.json产品/Schema/设备/App/Collector/Xcode/模板/能力/时钟/结束原因会话契约
events/*.pfevent分块、长度前缀 Protobuf、校验和、append-only 原始与标准事件权威原始数据
index.sqlite时间范围、事件类型、Metric、Scene、Artifact 索引；WAL 写入可重建索引
artifacts/截图、日志、Crash/Jetsam、xctrace Trace、符号和诊断包关联证据
analysis/带 modelVersion 的派生指标、规则结果和比较结果可重算
reports/离线 HTML、JSON 摘要、CSV展示产物

Lifecycle and recovery

关键状态机

设备状态

disconnected → detected → trusted → developerReady → tunnelReady → available。任一步失败都保留可行动原因；重连后重新发布 capability snapshot。

Session 状态

draft → validating → preparing → recording → stopping → finalizing → completed，旁路状态为 degraded / failed / cancelled。崩溃重启后允许从持久化状态 Finalize。

Collector 状态

idle → starting → handshaking → streaming → recovering → stopped。每个 Collector 有重启预算、心跳超时、最后序列和最后错误。

进程绑定

bundle/executable → pid + startTime + generation。PID 消失后先发 ProcessEnded，再重绑并增加 generation；累计量不跨 generation 差分。

Product experience

产品信息架构与主流程

页面用户任务关键设计
设备中心识别设备、信任/开发模式/tunnel、查看能力和故障不只显示“在线”；展示 ready/degraded/unsupported 和修复动作
新建测试选设备、App/进程、模板、指标、截图、时长、场景与重复轮次预估开销和能力冲突；启动前生成不可变 SessionPlan
实时监控观察曲线、设备画面、Marker/Scene、进程重启、数据质量Overview + Track；十字线联动；Stale/Gap/重连直接覆盖在时间线
Session 回放缩放、区间统计、查看截图/日志/Trace、重新分析Detail + Inspector；任何结论可回到原始事件、单位和算法版本
对比实验版本、机型、Run、场景和区间对比只比较兼容口径；显示绝对值、相对变化、样本量和置信状态
报告中心生成、归档、分享离线报告摘要、异常、场景、曲线、质量、环境、方法版本和证据包
诊断中心查看 Sidecar/Xcode/工具版本、哈希、日志和兼容矩阵一键导出故障包；用户数据与工具诊断分目录

Non-functional requirements

可靠性、性能与验收目标

维度首版目标验证方式
会话稳定性60 分钟基础会话无 writer failure；所有 Gap、重连和降级均显式记录至少两代 iOS 路由、三轮压力与断连注入
数据完整性accepted = persisted；重复/乱序/sequence gap 有计数；异常退出可 Finalize事件压力、Host kill、磁盘满、Sidecar crash fixture
采样延迟1 Hz 基础指标 source→UI p95 ≤ 1.5 秒；不把延迟样本伪装成当前值设备/Host 双时间戳与队列阶段测量
时间准确性保留 device/host 原时钟；跨源映射误差可见；Frame 算法优先在同一设备时钟计算Clock round-trip、漂移与长会话实验
自身开销以“不开采集”基线比较 Host CPU/内存、设备 CPU/FPS/能耗；阈值由 Gate 0 确认静止、动画、压力三场景，每场景多轮置信区间
恢复短暂断连自动进入 recovering；恢复后新 generation；超过预算明确 failed/degraded拔插、tunnel 重启、App 重启、设备锁屏
大数据交互十万点 Session 首屏和缩放保持可操作；图表不加载全部原始事件到 UI查询窗口、极值保留下采样和内存基准
可迁移旧 Session 原始事件不重写；索引与 Analysis 可重建；未知字段保留至少两版 Schema 双向读取 fixture
离线交付采集、回放和 HTML 报告不依赖公网；Sidecar 版本、架构、签名和哈希可诊断干净用户目录、源码目录移走、arm64/x86_64 分别验证

Stage gates

分阶段实施与严格门禁

阶段交付范围进入条件退出条件状态
G0 真值与可行性四类 Instruments Trace、DVT 候选对比、CPU/Memory/Frame/GPU 对照、开销与兼容矩阵本方案获批并具备设备/样本数据源、主采集器、口径和首版支持矩阵都有可复现证据当前暂停点
M1 iOS General MVP设备、App/进程、CPU/Memory/FPS 趋势/GPU、实时曲线、Marker、Session、回放、报告G0 全部通过60 分钟稳定、断连/重启恢复、质量可见、离线安装验收未开始
M2 Frame ExperienceFrameTime、Jank/BigJank/SmallJank、刷新率、Hitch 对照逐帧 source 和算法 fixture 已确定60/90/120Hz、动态刷新率和已知卡顿样本可复现、可解释未开始
M3 Automation & CompareCLI、Local Service、CI 门禁、多设备租约、基线/场景/版本对比M1/M2 Schema 稳定批量任务可取消/恢复；CI 返回明确状态和证据包未开始
M4 Deep & Extensionxctrace Trace、日志/Crash/Jetsam、GPU Counter、网络/能耗、SDKTrace Schema 和时钟关联稳定异常区间可关联栈、日志、场景和截图；增强失败不影响基础采集未开始
M5 Platform & CloudAndroid/PC/主机、团队/RBAC、私有部署、MCP/Skills/AIiOS 产品与外部 API 经真实团队使用稳定另立 ADR，不在本方案预先锁死实现后置

Gate 0 evidence plan

当前暂停：Gate 0 还缺的关键证据

缺口最小实验决定什么缺少时的处理
Frame 原始数据源60Hz/120Hz 的静止、滚动、动画、人工卡顿；Instruments Display/Frame Lifetimes/Hitches + DVT + PerfDog 同场FrameTime、FPS、Jank/SmallJank 的 source 与算法首版只保留 FPS 趋势，不发布 Jank
采集主实现pymobiledevice3 与 go-ios 在 iOS 16、17+、18+ 上比较建链、字段、延迟、断连、并发、60 分钟资源GeneralCollector 主/备实现保持 Sidecar Contract，不在 Host 固化库
CPU/Memory/GPU 口径同一 App 场景对照 Xcode Gauge/Instruments、PerfDog 与 DVT rawcanonical unit、normalization 和 UI 名称指标标记 Experimental，不进入门禁
xctrace SchemaTime Profiler、Animation Hitches、Game Performance、Allocations 各固定 Trace/TOC/XPathTraceAdapter 首版范围和版本键Deep Diagnosis 后置，不阻塞 M1
工具自身开销不开采集、DVT 基础、截图、xctrace、Extension 分层对照默认模板、采样率和开销提示高开销能力默认关闭
产品行为基准PerfDog 当前版本的设备连接、新建测试、实时页、Marker/Scene、Session、对比、报告、错误状态录屏与样例工作流对齐范围与可用性基线先完成 Perfowl 自洽流程，不追像素级复制

Material request

建议你补充寻找的资料方向

  1. PerfDog 真实产品资料

    当前桌面端完整操作录屏；设备/App/进程选择；实时曲线与十字线；Marker/Label/Scene；多轮测试；报告详情、对比和导出；断连、无权限、指标不支持等错误状态。最好附一份真实 Session 导出和报告。

  2. PerfDog Service / CLI 契约

    当前帮助文档、命令输出、protobuf/API 定义、数据流样本、设备/任务状态码、多设备并行示例、网络模板和报告上传 Payload。已有官方 Demo 之外，优先找实际版本的接口说明。

  3. Apple Instruments 真机 Trace 样本

    同一个测试 App 在 iOS 16、17、18+ 与 60/120Hz 设备上的 Time Profiler、Animation Hitches、Game Performance、Allocations Trace；每份样本记录 Xcode 版本、设备、系统、场景和时间点。

  4. 可控测试 App 与场景

    准备一个可制造 CPU 峰值、内存增长/释放、主线程 50/100/200ms 阻塞、不同帧节奏、GPU 压力、网络吞吐与 App 重启的 fixture App；每个开关有确定时间和预期。

  5. DVT 原始事件样本

    保存未归一化 Sysmontap、Graphics、Network、Energy/Core Profile 原始消息和属性列表，不只保存最终 CSV；覆盖首样本、空字段、进程重启、断连和 tunnel 重建。

  6. 目标支持矩阵

    明确首版必须支持的 Mac 芯片、macOS、iPhone 型号、iOS 版本、刷新率、USB/Wi‑Fi、普通 App/游戏/App Extension，以及用户是否具备 Xcode。没有该矩阵，兼容范围会持续漂移。

Risk register

最高风险与控制方式

风险概率/影响控制触发后的降级
iOS 私有 DVT 协议随版本变化高 / 高Adapter 隔离、capability snapshot、原始 fixture、双候选实现、兼容矩阵明确 unsupported；保留 xctrace 深度模式
Frame/Jank 算法与 PerfDog 不一致高 / 高同场真值、算法版本、公开公式 fixture、原始 Frame 保留仅展示 Frame/FPS，不发布同名 Jank
采集影响被测 App中 / 高按能力标记开销等级；截图、Trace、Counter 分层开启；基线实验自动切换 General Lite 模板
xctrace/Xcode Schema 漂移高 / 中TOC-first、版本化解析器、Trace fixture、原文件保留Trace 可打开但暂停结构化分析
长会话内存/磁盘膨胀中 / 高Chunk、窗口索引、流式统计、保留策略、磁盘预算停止高频 Artifact，基础事件继续并标记降级
双 Sidecar 技术栈维护成本中 / 中Gate 0 只选一个主实现；统一协议；另一个只保留验证 Adapter移除备选，不影响 Session Schema
过早建设云与 AI高 / 高M5 明确后置；每阶段由数据与用户证据进入冻结平台层，回到指标和工作流

Approval boundary

本次建议批准的范围

只建议批准 Gate 0 调研与实验方案，不建议批准 M1 产品开发。
Gate 0 产出应包括：设备/系统矩阵、四类 Instruments Trace fixture、DVT 双候选实测、CPU/Memory/Frame/GPU 指标映射、工具开销、PerfDog 产品行为样本，以及最终的 Collector/Metric ADR。完成后再按项目规则提交详细开发计划。

本方案是架构与产品设计文件。没有新增采集代码、桌面端代码、Sidecar、数据库或产品构建产物。

设计依据

  1. client_perf iOS 专项分析 — 原型链路、长连接、任务和需要重做的边界。
  2. Codesign4QC 性能采集专项分析 — DVT、Schema v2、背压、质量、Session、Marker 与报告。
  3. Apple Instruments 专项调研 — Trace/Run、Template/Instrument、xctrace 和混合架构。
  4. Instruments 生态与 PerfDog 复刻差距 — 开源候选、PerfDog 能力地图和差距矩阵。
  5. Perfowl 调研与开发规则 — 先分析、批准后开发、HTML 归档和本地提交。