用途与实际影响
这项功能怎样使用
为什么需要它
虚拟网卡叠加、CPU 口径混用、探针陈旧、无游戏帧被写成 0 FPS，都会让漂亮面板给出错误判断。
举个实际例子
我问“开着 Tailscale 和虚拟机时，这个网速数字还准吗？”系统只认唯一的物理公网出口；如果分不清，就直接显示网络数据不可用，绝不会把几张虚拟网卡相加成一个离谱数字。
最后我会得到什么
机箱屏每秒更新主要状态，较慢的程序排行另更新；每个值都知道来自哪里、多久前取得。没有可靠来源时显示等待或不可用，而不是一个看似正常的零。
正常时
来源明确且新鲜时显示实际值。
发现问题时
一个来源过期或明显错误时只让该项失效，其他可信数值继续显示。
入口不可用或证据不足时
真实物理网口或传感器分不清时留空，不把虚拟设备数值相加。
从哪里开始
平时直接看机箱屏；读数疑似不对时，在已接入项目的本机 AI 对话中说出指标和当时的程序。
需要准备什么
- 疑问指标与时间
- 物理网卡、游戏或虚拟设备情况
从开始到拿到结果
- 1
追溯这个读数的来源
系统核对当时的物理网卡、游戏或桌面帧来源，以及读数有没有过期。
- 2
查值从哪来
系统核对物理网口、TimeAudit 帧源及各探针的新鲜度。
- 3
显示可信状态
交回真实值或不可用原因；分不清来源时留空，不相加虚拟网卡或把桌面帧当游戏成绩。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
9月7日87项指标回归和依赖检查通过；实时采集值仍由各来源负责，未逐项对照外部仪表关键规则与设计选择
当前源码优先使用 PDH % Processor Utility（处理器效用率）；旧文档中的 Processor Time 说法属于待修漂移，不能反向覆盖运行实现。
物理公网只统计明确出口，虚拟接口不重复计数。
进程排行从 1 秒主循环分离，避免重扫描拖慢屏幕。
新鲜且明确 gated_idle 才是正常等待；starting 是启动中，waiting_frames 是有渲染但无匹配帧，缺状态、陈旧和来源错误不能混成空闲。
本模块用到的名词
- PDH（Windows 性能计数器）
- 当前代码从这里优先取得 % Processor Utility（处理器效用率），并保留来源与失败状态。
- physical egress（物理公网出口）
- 真实承载上网流量的物理接口，不含隧道或虚拟交换接口。
- fresh / stale（新鲜 / 陈旧）
- 值是否在允许时间内更新；陈旧值可显示但不能冒充当前。
专业定义
把硬件、物理公网、磁盘、天气、FPS、前台和进程排行汇成带新鲜度与 trust（可信度）的本地快照，来源不确定时失败关闭。
解决什么
解决来源混加、不同口径同名、慢采集阻塞主循环、无值清零和陈旧值冒充实时。
当前怎样实现
- metrics_agent.py 通过 loopback HTTP 提供有界 snapshot。
- top_processes_helper.py 每 3 秒独立采样并写有界 JSON。
- 物理网络按接口身份筛选，TUN、虚拟化和小型虚拟盘按合同排除。
- TimeAudit 只提供可选 FPS 事实，本项目经 PostgreSQL 的 `fact_system_hardware` 读取数值、`fps_capture_status` 与 `fps_capture_detail`，不直接连接或启停 RTSS，也不复制长期数据库。
- 当前上游先选 RTSS 精确前台、RTSS 最近前台、已启用 Wallpaper 桌面渲染器和唯一新鲜帧；映射不可用才启动 PresentMon 后备。`metrics_agent.py` 把 gated_idle 映射为 idle、starting 映射为 connecting、waiting_frames 映射为 error，并另行核对数据库样本年龄。
执行流程
- 1
发现并读取各数据源。
- 2
按来源口径归一化和过滤。
- 3
计算新鲜度、状态与 trust。
- 4
返回 snapshot；慢排行异步更新。
- 5
渲染层只消费已标注结果。
边界
- 天气、网络质量和功耗可能包含外部来源或估算。
- FPS 来自 TimeAudit 的 RTSS 优先 / PresentMon 后备链；本项目只读其 PostgreSQL 结果，不拥有帧源、RTSS 运行或历史。允许桌面渲染帧时，正 FPS 不自动代表游戏成绩。
- 进程名和技术指标可公开；具体通知正文和凭据值不进入快照页面。
失败与恢复
- 物理公网出口歧义
- 失败关闭，不叠加多个候选。
- TimeAudit 样本新鲜且明确为 gated_idle
- 显示正常等待游戏帧，不用 0 FPS 冒充已取得帧。
- TimeAudit 返回 waiting_frames、source_unavailable、error、缺采集状态或样本过旧
- 显示相应采集异常、来源不足或陈旧；不因为数值为 0 就判健康，不由副屏另启帧源。
- 慢来源超过 deadline
- 使用最后一份好快照并降低 trust，主渲染不等待。
真实入口
E:\Projects\Tools\TURZX-SideScreen\tools\turzx_side_screen\metrics_agent.py主 snapshot 与来源可信度
E:\Projects\Tools\TURZX-SideScreen\tools\turzx_side_screen\top_processes_helper.py3 秒进程排行
E:\Projects\Tools\TURZX-SideScreen\tools\turzx_side_screen\test_metrics_agent.py84 项指标口径、并发快照锁与失败回归
E:\Projects\Tools\TURZX-SideScreen\docs\architecture.md数据来源与节拍合同
如何验证
- 9月7日a4d8e22完整软件回归中，test_metrics_agent.py运行87项并通过；8月31日84项为较早历史验收。
- check-runtime 确认 Python 3.11 与 TimeAudit 读取依赖就绪。
- 没有逐项对照实体传感器或外部仪表，真实值准确度仍按来源解释。
与其他模块的关系
安装与换机模块提供当前机私有来源配置；本模块为机箱屏渲染和 HS2 硬件告警提供当前值，TimeAudit 继续拥有长期历史。