Perfowl 第一版基座：Mac 负责可信采集，Cloud 负责长期记录与报告

Decision

结论先行

ADR-002

架构决策记录

Assumptions

第一版设计假设与容量边界

当单 Workspace 的日 Run、单 Run 事件量、报告查询延迟或 Worker 积压达到实际阈值时，再基于观测结果拆分处理服务或引入 ClickHouse；API 与 Artifact 契约保持不变。

Options considered

关键方案取舍

Version 1 boundary

第一版能力边界

Codesign4QC extraction

Codesign4QC 如何进入 Perfowl

Mac client

Mac 客户端分层

Collector contract

pymobiledevice3 Sidecar 设计

Deep diagnosis

xctrace 增强链

Offline-first artifact

本地 Session 包与事实模型

Perfowl Sessions/<session-id>/
├── manifest.json                 # 身份、状态、版本、开始/结束、失败原因
├── session-plan.json             # 开始前冻结的目标、指标、选项与开销预算
├── capabilities.json             # 设备、route、DVT/xctrace、实际支持项
├── metric-registry.json          # metric ID、单位、scope、来源、算法版本
├── events/
│   ├── events-000001.jsonl       # append-only 统一事件 Chunk
│   └── events-000002.jsonl
├── raw/
│   ├── collector-000001.jsonl    # 未归一化 Sidecar 事实
│   └── sidecar.stderr.log
├── annotations.json              # Marker、场景、pause gap
├── quality.json                  # drop/gap/reorder/writer/clock/route 质量
├── analysis/
│   ├── summary.json              # 可重建摘要
│   └── lod/                      # 本地回放多分辨率曲线缓存
├── traces/<trace-id>/            # .trace、TOC、导出与诊断
├── upload.json                   # serverRunID、分块哈希与重试状态
└── checksums.json                # 不可变 Artifact SHA-256

Metric Definition 最小字段

{
  "id": "ios.process.cpu.non_normalized",
  "displayName": "App CPU",
  "unit": "percent",
  "scope": "process",
  "source": "dvt.sysmontap",
  "aggregation": ["avg", "p50", "p95", "max"],
  "definitionVersion": "1",
  "support": "validated | experimental | unsupported",
  "qualityRequirements": ["target_bound", "unit_verified"]
}

Cloud foundation

后端与 Web 报告架构

后端模块

核心 API 契约

Domain model

云端核心数据模型

Security & privacy

安全、隐私与数据生命周期

PerfDog-like workflow

Mac 产品信息架构与交互

1. 登录与项目

   登录后选择 Workspace/Project；token 已缓存且网络中断时仍允许本地采集，结束后进入待上传队列。

2. 连接设备

   顶部设备选择器展示连接、Trust、Developer Mode、DDI、Tunnel 和 iOS 版本；问题直接给出下一步，不只显示“连接失败”。

3. 选择 App/进程

   按 App 名、Bundle ID、运行状态筛选；默认绑定主进程，支持目标退出后按 stable identity 重绑并标出 generation。

4. 配置指标

   左侧指标区采用“采集 / 显示”分离：关闭、采集但隐藏、采集并显示；每项展示 scope、开销和支持等级。

5. 开始测试

   开始前冻结 SessionPlan，显示实际 route 与缺失能力；进入主视图后图表共享时间轴和十字线。

6. 暂停记录与继续

   暂停只停止测试样本写入，保持设备与采集器连接；时间轴写入 pause gap，继续时新建连续片段，避免把空白当成 0。

7. Marker 与场景标签

   单点 Marker 标记事件，场景标签表示时间区间；快捷键、颜色和命名可编辑，所有标注进入统一事实流。

8. 结束与确认

   先停止采集并完成本地 finalize，再弹出名称、Project、备注与“保存并上传”；上传可在后台继续。

9. 历史与回放

   本地记录展示完成/异常/待上传/上传中/云端已就绪；打开后使用与实时页同一图表组件回放。

10. Web 报告

    浏览器展示概览、同步曲线、区间统计、场景、异常证据、数据质量、设备/App 快照和原始 Artifact。

主窗口布局建议

Web report v1

第一版报告结构

State machines

关键状态机

Non-functional requirements

基座质量目标

Delivery gates

建议实施顺序

PerfDog evidence request

付费账号与文档什么时候需要

1. Mac 客户端全流程录屏

   登录、设备连接、App/进程、指标面板、开始/暂停/继续/结束、Marker/Label、区间选择、保存上传和本地回放。

2. 当前付费指标矩阵

   iOS 各指标名称、单位、帮助说明、USB/Wi-Fi 限制、版本/机型限制和错误状态。

3. 真实 Web 报告

   单次报告、区间统计、报告对比、趋势、项目/任务、分享权限、导出格式和处理状态。

4. 真实 Session 与导出

   一份普通 App、一份游戏、一份 App 重启或断连样本；包括本地导出、云端报告和同场 PerfDog 采样。

5. 异常与边界录屏

   设备锁屏、Developer Mode/镜像问题、指标灰置、上传失败、短测试、断线、App 退出和 xctrace 冲突。

账号使用建议通过已经登录的浏览器会话完成，不在文档或聊天中保存密码。你后续提供的官方文档地址将登记到本页“依据”并标注版本/访问日期。

Risk register

最高风险与控制

Approval boundary

已批准的架构决策

当前已新增 Mac App 与 Sidecar 本地采集代码；后端、Web、数据库、上传和部署代码仍未启动。

设计依据

1. Perfowl 无侵入底层能力决策 v1 — pymobiledevice3 主链、xctrace 增强、指标边界与 F0。
2. Perfowl Gate F0 真机能力与指标校准计划 v1 — 设备矩阵、实验清单、误差门槛、证据产物与停止条件。
3. Codesign4QC 性能采集专项分析 — DVT、generation、Schema v2、背压、质量、Session、场景与报告。
4. Apple Instruments 专项调研 — Trace/Template/Instrument、xctrace 和验证基准。
5. PerfDog 官方客户端说明 — 无侵入、Mac/iOS、实时指标、Marker/Label、停止、上传与 Web 管理。
6. PerfDog 官方产品页 — 实时监控、报告分析、全平台与自动化产品方向。
7. pymobiledevice3 iOS 17+ tunnel 指南 — macOS native/no-root 默认路径与 17.0–17.3.1 privileged tunneld 边界。
8. pymobiledevice3 DVT API — Process、Sysmontap、Network、Energy、Graphics、ActivityTrace、CoreProfile 等入口。
9. Apple Xcode command-line tool reference — xctrace 录制、导入、导出与符号化定位。
10. Perfowl 调研与开发规则 — 先分析、批准后开发、HTML 归档和本地提交。