Workbench alignment · Product spec
Perfowl 工作台 UI 与指标对齐方案 v1
根据用户提供的四张 PerfDog 客户端参考图，确定 USB 状态反馈、顶部截图、默认三组指标、多曲线模型和右下角指标选择器。UI-1 已批准并完成代码、单测、Release App 构建与签名检查；GUI 运行与真机视觉验收继续独立标记为待补，详见实施记录。
Reference breakdown
参考界面提炼出的结构
SCREEN
USB状态
✓
设备 A 已连接
设备 A 已连接
FPSfps
CPU UsageAPPCpuTotalCPU
NetworkSendRecv
＋
状态浮层是瞬时反馈连接徽标负责持续状态；顶部浮层只在启动发现、连接和断开事件后出现，1 秒后淡出，避免长期遮挡截图。
默认图表不依赖设备选择未选设备也显示 FPS、CPU Usage、Network 的空坐标系与图例，让用户提前知道测试将采什么。
指标选择器不隐藏差距连接后才显示右下角 `＋`；未支持项仍在完整清单中，以禁用态和原因呈现。
参考而非像素复制。
保留参考产品的任务结构、交互位置、指标名称和选择逻辑；颜色、品牌图标、字体和细节继续使用 Perfowl 自有设计语言。
USB status
连接 / 断开提示状态机
启动扫描监听真实设备快照，不因列表缓存触发提示。
事件确认比较稳定设备标识集合，生成 connected / disconnected。
立即显示标题 `USB状态`，设备图标 + 状态文本。
保持 1 秒从事件确认时刻计时；新事件覆盖并重置。
淡出约 180–220 ms；持久状态仍留在标题栏与侧栏。
| 场景 | 文案 | 视觉 | 规则 |
|---|---|---|---|
| 启动时已连接 | 设备 A 已连接 | 蓝色设备 + 青绿色勾 | 首次稳定快照建立后展示一次。 |
| 运行中插入 | 设备 A 已连接 | 蓝色设备 + 青绿色勾 | 设备进入可用集合后展示。 |
| 运行中断开 | 设备 A 已断开 | 灰色设备 + 叉 | 立即清理所选设备/App；采集中按现有中断流程完成或失败。 |
| 启动无设备 | 设备未连接 | 灰色设备 | 只在启动探测完成时出现一次，不按轮询重复弹出。 |
辅助定位建议：perfowl.usb.status-toast。自动化校验必须能观察出现、文案、1 秒保持和最终消失。
Screen context
顶部截图展示区域
| 项目 | 产品规格 | 边界 |
|---|---|---|
| 位置 | Scene 工具栏下方、全部性能曲线上方；USB Toast 覆盖在此区域顶部中央。 | 不挤占左侧设备/App 选择链。 |
| 展示 | 截图按设备原始宽高比 aspectFit 居中，深色留白，不裁切、不拉伸。 | 屏幕旋转后按新尺寸自适应。 |
| 频率 | 首版 1 秒一次。超时保留上一帧并标记“截图已过期”，不闪成黑图。 | 定义为低频截图预览，不宣传为实时视频镜像。 |
| 未连接 | 固定空态：连接设备后显示屏幕截图。 | 默认三组指标仍继续显示为空图。 |
| Session | 默认只在内存中预览；用户勾选 ScreenShot 后才保存媒体文件和时间戳。 | 需记录采集时间、接收时间、文件名、失败原因和相对主时钟偏差。 |
| 资源保护 | 只保留最新预览帧；落盘采用有界队列，截图失败不阻塞性能主采集。 | 验收中单独测量 CPU、内存、带宽和对采样抖动的影响。 |
Default panels
未选择设备时也固定展示的三组指标
| 面板名 | 曲线名 | 当前来源 | 未连接 / 缺源显示 |
|---|---|---|---|
| FPS | fps | DVT Graphics；当前口径是 foreground-device。 | 等待设备；有值后仍标注前台设备范围，校准前保留 Experimental。 |
| CPU Usage | APPCpuTotalCPU | APPCpu 已来自目标进程 Sysmontap；TotalCPU 仅有 rawSystem 候选，尚未规范化。 | APPCpu 等待目标；TotalCPU 显示 Unsupported / 待校准，不画 0。 |
| Network | SendRecv | rawSystem 和 DVT NetworkMonitor 均为候选，当前未进入 Swift/UI。 | 显示 Unsupported / Network source not ready，不画 0。 |
需要先改图表模型。
当前
LiveMetricKind 是“一项一图一曲线”。目标模型应是 MetricPanelDefinition 包含多个 MetricSeriesDefinition，每条曲线独立声明 metricID、颜色、单位、scope、availability 和 quality。Metric selector
右下角 `＋` 与 17 个同名指标
只有设备已连接时显示右下角悬浮 `＋`。点击后打开可滚动的大型指标面板：复选框、彩色圆形图标、名称、说明、能力状态；已选行为蓝色背景。名称严格保持如下拼写与大小写。
✓ScreenShotThe device same screen and synchronous display计划接入 · 1 s
StartupTiming(启动时间)The relevant time consumption of the application startup phase暂未支持
✓FPSThe number of frame rate by the process each second已接入
Frame TimeThe time between frames to be rendered暂未支持
CPU Core UsageThe percentage of the CPU for each core暂未支持
✓CPU UsageThe percentage of the CPU used by the process部分支持
Memory UsageThe amount of memory used by the process已接入
GPU UsageThe percentage of the GPU used by the process范围待校准
CSwitchThe number of process context switches by the process each second已接入
WakeupsThe number of thread wakeups by the process each second已接入
Battery TemperatureThe size of the battery temperature暂未支持
DiskThe assessed physical disk performance metrics of the process已接入
Thermal StatusCurrent thermal status of the device暂未支持
✓NetworkThe number of bytes received or send by the process each second候选源
BatteryThe amount of battery energy used by the total process暂未支持
Energy UsageThe details of battery energy used by the app暂未支持
GPU CounterDetailed information of various GPU counters, in-depth analysis of GPU暂未支持
参考图中的模式提示应保留在说明区：Frame Time 为 USB / 系统版本敏感；Wakeups 为系统版本敏感；Battery 为 Wi-Fi 模式；Energy Usage 为 USB 模式。最终文案以真实 capability 结果为准，不能仅按静态版本号点亮。
Capability matrix
当前支持情况与补齐路径
| 指标 | 状态 | 当前证据 / 口径 | 补齐方式 |
|---|---|---|---|
| FPS | 已接入 | DVT Graphics → Collector → Swift → Session → UI；目前属于前台设备范围。 | 保留 scope 提示，与 PerfDog/xctrace 同场校准后再升级为对齐状态。 |
| CPU Usage | 部分支持 | APPCpu 已接入；TotalCPU 仅 rawSystem 候选。 | 保存/探测 System 原字段，明确 0–100 或按核心累计口径，规范化 TotalCPU 并校准。 |
| Memory Usage | 已接入 | Physical Footprint、Resident Memory 已有。 | 顶层名称统一为 Memory Usage；首选 Physical Footprint，Resident 留作明细，记录单位和 scope。 |
| GPU Usage | 部分支持 | Device/Renderer/Tiler GPU 已接入，但来自前台设备 Graphics。 | 面板明确 foreground-device；与参考产品确认是否为进程 GPU，未证明前不改成 process。 |
| CSwitch / Wakeups | 已接入 | 目标进程累计计数与每秒速率已进入模型。 | 只需名称、组合图、质量态与版本 capability 对齐。 |
| Disk | 已接入 | Read / Write 累计值与每秒速率已具备。 | 合并为 Disk 面板的 Read、Write 两条曲线；counter reset 第一帧显示 missing。 |
| ScreenShot | 入口候选 | 本机依赖存在 Screenshot.get_screenshot()，尚未进入产品链。 | 新增 Sidecar adapter、1 秒有界采样、内存预览、可选 Session 媒体落盘和统一时钟。 |
| Network | 入口候选 | rawSystem 有候选；DVT NetworkMonitor 提供连接/PID/收发字节候选，尚未规范化。 | 先做整机与 PID 归属实验；能证明进程归属才标 process，否则只按 device scope 输出 Send/Recv。 |
| StartupTiming(启动时间) | 暂未支持 | 当前测试要求用户自行启动目标 App，没有冷启动计时协议。 | 增加显式冷启动模式、生命周期事件和启动阶段时间轴；用 xctrace App Launch 做校准。 |
| Frame Time | 暂未支持 | 只有秒级 FPS，不能反推出逐帧时间。 | 寻找稳定逐帧 DVT/CoreProfile 源，保存原始 frame timestamp/duration；用 xctrace Display/Hitches 校准。 |
| CPU Core Usage | 暂未支持 | 尚未把 System 分核字段映射为动态序列。 | 探测 Sysmontap 分核数组；不足时用 CoreProfile/xctrace 增强，并按设备核心拓扑建序列。 |
| Battery Temperature | 暂未支持 | 没有已验证的稳定只读源。 | 验证 Diagnostics/IORegistry 候选、版本和权限；无稳定入口继续返回 Unsupported。 |
| Thermal Status | 暂未支持 | 尚未完成原始枚举和系统语义映射。 | 探测 Energy/Notifications/Diagnostics，保存原始枚举码并与系统 thermal state 校准。 |
| Battery | 暂未支持 | 模式敏感，USB 充电会扭曲耗电观察。 | 建立 Wi-Fi 低频 Current/Voltage/Power 通道；USB 模式直接给出 unavailable 原因。 |
| Energy Usage | 暂未支持 | DVT EnergyMonitor 是候选，尚未接入；分数不等于物理能量。 | 按 PID 接入分类和 Total 相对分数，保存原始类别；与 xctrace Energy 对照并明确单位。 |
| GPU Counter | 暂未支持 | 常规 Graphics 只有利用率，没有详细 Counter。 | 作为 CoreProfile/xctrace 增强模式实现，建立 SoC/iOS/Xcode 兼容矩阵和版本化 Registry。 |
额外已有字段不作为同级指标名展示。
Thread Count、Resident Memory 等继续保留在原始数据和明细层；在用户要求“名称与 PerfDog 一致”的前提下，不新增竞争性的顶层指标名称。
Delivery plan
建议的开发批次
UI-1
结构先落地，不接假数据
USB Toast、截图空态、默认三图、多曲线图表模型、右下角 `＋`、17 项选择器和 Unsupported 状态。单测覆盖默认名称、事件计时和缺值不为 0。
DATA-1
默认指标真正可用
承接 rawSystem 的 TotalCPU，接入 Network Send/Recv，补齐 scope/unit/quality。真机做 CPU 单/多线程、纯上传/下载、前后台、断连重绑。
SHOT-1
截图低频预览
接入 Screenshot adapter、1 秒内存预览、可选落盘、主时钟关联和资源开销门禁。
NAME-1
已有源完整改名/分组
Memory Usage、GPU Usage、CSwitch、Wakeups、Disk 按参考名称进入选择器；来源范围和质量提示不因改名丢失。
ADV-1
高级与模式敏感指标
Frame Time、CPU Core Usage、StartupTiming、Thermal/Battery/Energy、GPU Counter 分项实验，通过一个能力再开放一个。
Acceptance gates
开发验收标准
- UI：未连接也看到三张默认图；连接后 `＋` 出现；断开后 `＋` 消失；17 个名称逐字匹配本页。
- Toast：启动已连接、运行中插入、运行中断开各一次；从事件确认到淡出可重复测量，目标为 1 秒保持 + 短淡出。
- 数据：CPU Usage 和 Network 支持同图多曲线；无样本、第一帧、counter reset、源失败均不出现伪 0。
- 截图：横竖屏不拉伸；1 秒预览不中断性能采集；禁用 ScreenShot 后不向 Session 写媒体。
- 构建：Swift 单测、Sidecar 测试、Debug/Release 构建分别记录；静态通过不代替界面运行证据。
- 真机：在当前连接设备上完成设备/App 选择、状态浮层、截图、开始/停止、Session；业务 App 名、设备名、UDID、Bundle ID、PID 只留在本地验收证据，不进入公开文档。
UI-1 已实施，下一个停止点是 DATA-1。
本批只搭好真实状态与能力容器，没有把 TotalCPU、Network、截图候选值伪装成已支持。补录 GUI/真机视觉验收后，再批准 DATA-1 接入 TotalCPU 与 Network Send/Recv。
Evidence
依据与证据边界
| 依据 | 本页使用范围 | 未证明 |
|---|---|---|
| 用户提供的四张 PerfDog 界面截图 | USB 浮层位置/层级、连接与断开视觉、右下角 `＋`、指标行结构、名称及模式提示。 | 截图没有证明每项在当前设备/系统上的底层数据源和计算口径。 |
Perfowl 当前源码 @ 33cac26 | 确认当前单曲线模型、12 项 LiveMetricKind、rawSystem 已保存、当前默认指标和缺失 UI。 | 未执行的新设计尚无构建或运行证据。 |
| 指标对齐开发计划 | 底层来源、阶段排序、capability、scope、quality 和真机门禁。 | 候选源不等于已支持。 |