Release PGU5-Core v2.1.1

.gitignore

@@ -3,6 +3,7 @@ __pycache__/
 run.log
 captures/
 backups/
+runtime/
 .vscode/
 .codex/
 

AGENTS.md

@@ -20,7 +20,7 @@ Windows 侧密码 SSH 自动化使用 Paramiko。编辑中文时必须保持 UTF
 
 ## 项目边界
 
-- 当前应用版本和发布标签均为 `v2.0.5`。
+- 当前应用版本和发布标签均为 `v2.1.1`。
 - 版本字符串始终保留前导 `v`。
 - 序列号使用 `PGU5A-` 加大写以太网 MAC。
 - Core 不包含 PLC/Modbus、运动、水肥、业务自动化、计划任务、业务路径、Hikrobot/MVS/GenICam 或任何应用专属身份。
@@ -39,7 +39,7 @@ Windows 侧密码 SSH 自动化使用 Paramiko。编辑中文时必须保持 UTF
 http://107.173.157.41:3000/clear/PGU5-Core.git
 ```
 
-现场配置是实际设备配置。发布时如果用户要求提交当前现场状态，应保留并审查配置差异，不得直接丢弃。
+现场配置是实际设备配置。每次提交、推送或发布前都必须重新读取 `192.168.101.172:/root/PGU5-Core/pgu5a_config.json`，以当前调试机运行参数为提交基线，不得直接丢弃现场差异。密码、AuthKey、令牌等设备私有认证值只保留在现场，不写入公开仓库；部署时也不得用公开配置覆盖这些值。
 
 ## 服务
 
@@ -58,7 +58,7 @@ OLED 是独立服务，OLED 故障不得影响主服务。
 - `pgu5a_base.py` 内嵌 HTML、CSS 和 JavaScript，没有独立前端构建。
 - 前端修改后提取脚本做 JavaScript 语法检查；一个语法错误会导致时钟、按钮和状态刷新同时失效。
 - UI 保持紧凑、现场可操作，移动端不得横向溢出，DCL 必须完整显示画面。
-- 管理中心“多光谱控制”页面通过 `GET/POST /api/ms602/detection` 管理开流检测时长、抖动和撕裂检测；保存后必须持久化并立即更新运行中的 worker，不得重启整机或全部通道。
+- 管理中心“多光谱控制”页面通过 `GET/POST /api/ms602/detection` 管理开流检测时长、抖动、撕裂和帧率检测；保存后必须持久化并立即更新运行中的 worker，不得重启整机或全部通道。
 - 配置写入保持格式化 UTF-8 JSON 和一个结尾换行。
 - 不进行与用户请求无关的大范围重构。
 
@@ -71,9 +71,14 @@ OLED 是独立服务，OLED 故障不得影响主服务。
 - 每个通道的检测样本、截止时间和代次必须独立并受锁保护，旧开流代次的计算结果不得影响新通道实例。
 - 抖动位移是在 `160x100` 检测样本上计算，现场 720 上下抖动实测约为 `0.04..0.20` 像素；不得恢复按原始分辨率误设的 `0.4` 最小位移和 `2.0` 累计位移。
 - 撕裂检测同时使用跨帧低相关度大帧差和单帧横向/纵向梯度比例，避免已经撕裂且持续撕裂时因缺少连续切换而漏检。
+- 启动窗口内的大幅位移按次数检测，极大位移单次触发；默认阈值分别为 `0.8`、`2` 次和 `1.0`，只恢复对应通道。
+- 帧率检测是持续运行的轻量监控，不属于昂贵图像分析窗口；默认低于 `2.0 FPS` 连续 `2` 次后只重连对应通道，正常间隔必须清空连续异常次数。
+- MS602 保存必须拒绝缺失、恢复中、过期或跨通道时间偏差过大的帧组；默认 `frame_max_age_sec=2.0`、`frame_max_skew_sec=1.0`。
+- 通道打开后在启动检测完成前使用 `CHECKING`，通过后才转为 `CONNECTED`。
 - `last_jitter_trigger_*` 和 `last_integrity_trigger_*` 必须跨通道重开保留，便于区分真实故障与阈值误判；保存检测参数不得清空已完成窗口的诊断证据。
 - M3Lite 使用 GPIO 8 异步唤醒；UVC-RGB 使用 GPIO 9 异步唤醒。
 - UVC-RGB 在视频节点消失、被替换或持续无新帧时重连。
+- DCL 默认严格自动发现 `ClearDCLXXXXX` 视频设备名称；`camera_name` 仅作为兼容优先提示，不得要求换机时必须修改公开配置。
 - 休眠递增 `sensor_wake_token`，取消旧延时唤醒线程。
 - 定时保存或保存队列工作时暂停自动休眠。
 
@@ -84,7 +89,7 @@ OLED 是独立服务，OLED 故障不得影响主服务。
 | M3 startup NUC check | `3.0 s` |
 | M3 wake delay | `2.0 s` |
 | UVC-RGB wake delay | `1.0 s` |
-| MS602 open stagger | `0.5 s` |
+| MS602 open stagger | `0.3 s` |
 | MS602 startup detection | `5.0 s` |
 
 ## M3/L640 控制

API.md

@@ -1,6 +1,6 @@
 # PGU5-Core API
 
-本文档对应 PGU5-Core `v2.0.5`，以 `pgu5a_base.py` 中的实际路由为准。
+本文档对应 PGU5-Core `v2.1.1`，以 `pgu5a_base.py` 中的实际路由为准。
 
 ## 基本约定
 
@@ -47,7 +47,7 @@
 | `/api/syncthing/identity-init/status` | Syncthing 身份初始化进度 |
 | `/api/ota/status` | OTA 当前状态 |
 | `/api/m3/control` | M3/L640 热成像 USB 控制状态 |
-| `/api/ms602/detection` | MS602 抖动、撕裂检测参数和六通道诊断 |
+| `/api/ms602/detection` | MS602 抖动、撕裂、帧率检测参数和六通道诊断 |
 | `/api/ssh/read` | 读取 Web SSH PTY 输出 |
 | `/api/config` | 读取当前 JSON 配置文本 |
 | `/api/logs` | 获取内存运行日志 |
@@ -77,7 +77,7 @@
 | `/api/sensors/power` | 唤醒或休眠传感器 |
 | `/api/sensors/auto_sleep` | 设置自动休眠时间 |
 | `/api/m3/auto_nuc` | 设置并保存自动 NUC |
-| `/api/ms602/detection` | 保存并立即应用 MS602 抖动、撕裂检测参数 |
+| `/api/ms602/detection` | 保存并立即应用 MS602 抖动、撕裂、帧率检测参数 |
 | `/api/network/scan` | 扫描 Wi-Fi |
 | `/api/network/ap` | 修改 AP |
 | `/api/network/sta/connect` | 连接 STA |
@@ -258,7 +258,7 @@ curl -X POST http://127.0.0.1:8080/api/save -d "target=all"
   "used_gb": 118.0,
   "total_gb": 238.5,
   "refresh_ms": 5000,
-  "app_version": "v2.0.5",
+  "app_version": "v2.1.1",
   "auto_cleanup": {}
 }
 ```
@@ -412,13 +412,21 @@ curl -X POST http://127.0.0.1:8080/api/files/download \
     "jitter_window_sec": 3.0,
     "jitter_cancellation_ratio": 0.35,
     "jitter_total_shift_min": 0.35,
+    "jitter_large_shift_min": 0.8,
+    "jitter_large_shift_events": 2,
+    "jitter_extreme_shift_min": 1.0,
     "frame_integrity_detection_enabled": true,
     "frame_integrity_phase_response_min": 0.55,
     "frame_integrity_delta_min": 8.0,
     "frame_integrity_restart_events": 2,
     "frame_integrity_window_sec": 3.0,
     "frame_tearing_gradient_ratio_min": 2.0,
-    "frame_tearing_row_diff_min": 5.5
+    "frame_tearing_row_diff_min": 5.5,
+    "frame_rate_detection_enabled": true,
+    "frame_rate_min": 2.0,
+    "frame_rate_memory": 2,
+    "frame_max_age_sec": 2.0,
+    "frame_max_skew_sec": 1.0
   },
   "channels": {
     "480": {
@@ -427,6 +435,10 @@ curl -X POST http://127.0.0.1:8080/api/files/download \
       "restart_count": 1,
       "jitter_count": 0,
       "frame_integrity_count": 1,
+      "frame_rate_count": 0,
+      "frame_rate_fps": 8.1,
+      "frame_rate_low_streak": 0,
+      "frame_rate_result": "ok",
       "detection_active": false,
       "detection_remaining_sec": 0.0,
       "detection_result": "passed",
@@ -459,6 +471,9 @@ curl -X POST http://127.0.0.1:8080/api/files/download \
 | `jitter_window_sec` | `1.0..30.0` | 抖动统计窗口，秒 |
 | `jitter_cancellation_ratio` | `0.05..0.8` | 来回位移抵消比例阈值 |
 | `jitter_total_shift_min` | `0.05..50.0` | 累计位移阈值 |
+| `jitter_large_shift_min` | `0.1..20.0` | 启动窗口内大幅垂直位移阈值 |
+| `jitter_large_shift_events` | `1..20` | 大幅位移累计达到此次数后恢复当前通道 |
+| `jitter_extreme_shift_min` | `0.1..20.0` | 单次极大垂直位移阈值，必须不小于大幅位移阈值 |
 | `frame_integrity_detection_enabled` | 布尔值 | 开关撕裂检测 |
 | `frame_integrity_phase_response_min` | `0.1..0.95` | 相位相关度阈值；调高更敏感 |
 | `frame_integrity_delta_min` | `1.0..100.0` | 帧差阈值；调低更敏感 |
@@ -466,10 +481,15 @@ curl -X POST http://127.0.0.1:8080/api/files/download \
 | `frame_integrity_window_sec` | `1.0..30.0` | 撕裂统计窗口，秒 |
 | `frame_tearing_gradient_ratio_min` | `1.1..5.0` | 单帧纵向变化与横向变化的比例阈值 |
 | `frame_tearing_row_diff_min` | `1.0..30.0` | 单帧横向断层强度阈值 |
+| `frame_rate_detection_enabled` | 布尔值 | 开关运行期轻量帧率检测 |
+| `frame_rate_min` | `0.1..60.0` | 单通道最低成功读帧 FPS |
+| `frame_rate_memory` | `1..20` | 连续低帧率间隔达到此次数后恢复当前通道 |
+
+`frame_max_age_sec` 和 `frame_max_skew_sec` 用于保存前校验六通道帧组是否新鲜、时间是否足够同步。它们当前通过配置文件管理，不由检测页面修改。
 
 保存成功后先写入 `pgu5a_config.json`，再更新运行中的 MS602 worker 并清空当前检测样本。参数立即用于仍在进行的开流自检；已经通过的通道不会因为保存配置而重新开始检测。该操作不重启服务、不重启整机，也不会主动重启正常通道。
 
-每个通道只在首次启动、休眠唤醒或错误重连后开启独立检测窗口。窗口结束且未触发异常时，`detection_result` 变为 `passed`，后续预览帧在进入灰度转换、缩放、相位相关和帧差计算前直接返回。检测触发时只请求重启对应通道；通道重新打开后自动进入新一轮检测。
+每个通道只在首次启动、休眠唤醒或错误重连后开启独立图像检测窗口。窗口结束且未触发异常时，`detection_result` 变为 `passed`，后续预览帧在进入灰度转换、缩放、相位相关和帧差计算前直接返回。帧率检测只记录成功读帧间隔，运行期间持续生效；低帧率累计达到阈值时也只请求重启对应通道。
 
 管理中心诊断表只显示 `device_index` 的数字节点编号，例如 `12`；API 仍返回完整的 `device_index` 和通道状态消息，后台设备路径与相机打开逻辑不变。
 
@@ -660,7 +680,7 @@ POST /api/ssh/close
 
 ```json
 {
-  "open_stagger_sec": 0.5,
+  "open_stagger_sec": 0.3,
   "read_fail_restart_count": 5,
   "channel_reconnect_delay_sec": 0.8,
   "startup_detection_window_sec": 5.0,
@@ -672,17 +692,27 @@ POST /api/ssh/close
   "jitter_window_sec": 3.0,
   "jitter_cancellation_ratio": 0.35,
   "jitter_total_shift_min": 0.35,
+  "jitter_large_shift_min": 0.8,
+  "jitter_large_shift_events": 2,
+  "jitter_extreme_shift_min": 1.0,
   "frame_integrity_detection_enabled": true,
   "frame_integrity_phase_response_min": 0.55,
   "frame_integrity_delta_min": 8.0,
   "frame_integrity_restart_events": 2,
   "frame_integrity_window_sec": 3.0,
   "frame_tearing_gradient_ratio_min": 2.0,
-  "frame_tearing_row_diff_min": 5.5
+  "frame_tearing_row_diff_min": 5.5,
+  "frame_rate_detection_enabled": true,
+  "frame_rate_min": 2.0,
+  "frame_rate_memory": 2,
+  "frame_max_age_sec": 2.0,
+  "frame_max_skew_sec": 1.0
 }
 ```
 
-小幅反向垂直抖动继续使用位移方向、抵消比例和累计位移判断，位移值基于 `160x100` 检测样本。对于画面撕裂、错行等坏帧，检测器同时统计跨帧低相位相关度大帧差，以及单帧横向断层梯度；在开流检测窗口内达到阈值后只重启对应 MS602 通道。`ms602_channels` 会附带检测是否运行、剩余秒数、结果、实际分析帧数、恢复计数、相位相关度、帧差和断层指标等诊断字段。`last_jitter_trigger_*` 与 `last_integrity_trigger_*` 保留最近一次触发证据，通道重新打开和保存配置后仍可用于诊断。
+小幅反向垂直抖动继续使用位移方向、抵消比例和累计位移判断，位移值基于 `160x100` 检测样本。大幅位移按窗口内次数判断，极大位移单次即可触发。对于画面撕裂、错行等坏帧，检测器同时统计跨帧低相位相关度大帧差，以及单帧横向断层梯度；这些昂贵分析只在开流检测窗口运行。帧率监控持续记录成功读帧间隔，连续低 FPS 时只重启对应 MS602 通道。`ms602_channels` 会附带检测状态、恢复计数、相位相关度、帧差、断层、当前 FPS 和低帧率连续次数等诊断字段。
+
+`dcl.auto_detect=true` 时运行时严格匹配 `ClearDCLXXXXX` 视频设备名称。`dcl.camera_name` 如存在仅作为优先提示；未配置或更换设备时无需修改发布配置。
 
 ### 服务和电源接口
 

README.md

@@ -7,8 +7,8 @@ PGU5-Core 是运行在 Orange Pi 4 Pro 上的 PGU5 开放平台核心程序，
 | 项目 | 当前值 |
 | --- | --- |
 | 产品 | PGU5 开放平台 |
-| 应用版本 | `v2.0.5` |
-| 发布标签 | `v2.0.5` |
+| 应用版本 | `v2.1.1` |
+| 发布标签 | `v2.1.1` |
 | 设备序列号 | `PGU5A-` + 大写以太网 MAC |
 | 现场目录 | `/root/PGU5-Core` |
 | Web | `http://192.168.101.172:8080/` |
@@ -20,14 +20,14 @@ PGU5-Core 是运行在 Orange Pi 4 Pro 上的 PGU5 开放平台核心程序，
 
 当前 Core 功能：
 
-- MS602 六通道采集、预览、保存，以及开流自检阶段的小幅反向抖动、低相关度撕裂帧和读帧失败独立通道恢复。
+- MS602 六通道采集、预览、保存，以及开流自检阶段的小幅反向抖动、大幅/极大位移、低相关度撕裂帧检测和持续低成本帧率监控；异常时只恢复对应通道。
 - M3Lite 热成像采集、温度数据保存和 PyUSB 控制。
-- DCL 与 UVC-RGB/IMX766 采集、预览和保存。
+- DCL 严格按 `ClearDCLXXXXX` 序列号名称自动发现；DCL 与 UVC-RGB/IMX766 均支持采集、预览和保存。
 - 单次保存、在线定时保存、保存队列和自动休眠。
 - 文件浏览、预览、ZIP 下载、后台永久删除和空间自动清理。
 - AP、STA、以太网、HS/Headscale 和 Syncthing 管理。
 - Web SSH、配置编辑、服务重启、安全关机和 OTA。
-- 管理中心提供多光谱控制页，可开关并调节小抖动与撕裂检测，保存后即时生效并持久化，同时查看六通道实时恢复诊断。
+- 管理中心提供多光谱控制页，可开关并调节小抖动、大幅/极大位移、撕裂和帧率检测，保存后即时生效并持久化，同时查看六通道实时恢复诊断。
 - 独立 OLED、DS3231 和 NVMe 服务。
 
 不属于 Core 的功能：
@@ -37,6 +37,15 @@ PGU5-Core 是运行在 Orange Pi 4 Pro 上的 PGU5 开放平台核心程序，
 - Hikrobot/MVS/GenICam。
 - 任何应用专属产品身份、业务页面或部署路径。
 
+## v2.1.1
+
+- 同步 `v2.0.5..v2.1.1` 通用平台能力，不包含 PLC、运动、水肥、业务自动化、计划任务或 MVS/GenICam。
+- MS602 新增启动期大幅/极大垂直位移检测，解决短时高幅跳动画面可能越过小抖动上限而漏检的问题。
+- MS602 新增持续低成本单通道帧率监控；连续低于阈值时只重连对应波段，不持续执行灰度缩放、相位相关或撕裂分析。
+- 开流后先显示 `CHECKING`，通过启动检测窗口后再转为 `CONNECTED`，避免画面尚未完成自检时过早显示正常。
+- DCL 支持严格 `ClearDCLXXXXX` 名称自动发现，现场 `camera_name` 仅作为优先提示，不再是换机必须修改的绑定项。
+- DCL 预览宽度同步为 `720`，刷新间隔调整为 `350ms`，在提升预览细节的同时控制浏览器和网络刷新负载。
+
 ## v2.0.5
 
 - 多光谱六通道诊断表的“设备”列仅显示视频节点编号，例如 `/dev/video12` 显示为 `12`，减少现场界面的实现细节。
@@ -77,7 +86,7 @@ PGU5-Core 是运行在 Orange Pi 4 Pro 上的 PGU5 开放平台核心程序，
 | `backups/config/` | 配置编辑器备份，不提交 |
 | `backups/ota_state.json` | OTA 运行状态，不提交 |
 
-现场 `pgu5a_config.json` 是配置事实来源，不应当作普通本地差异丢弃。
+现场 `pgu5a_config.json` 是配置事实来源，不应当作普通本地差异丢弃。每次提交、推送或发布前必须重新读取 `192.168.101.172:/root/PGU5-Core/pgu5a_config.json`，以当前调试机运行参数更新仓库配置。密码、AuthKey、令牌等设备私有认证值只保留在现场，部署时不得使用公开配置覆盖。
 
 ## 服务
 
@@ -94,10 +103,12 @@ PGU5-Core 是运行在 Orange Pi 4 Pro 上的 PGU5 开放平台核心程序，
 ## 相机与电源
 
 - MS602 和 DCL 唤醒时立即启动。
-- MS602 六通道按 `ms602.open_stagger_sec` 间隔启动，当前默认 `0.5` 秒。
-- MS602 每个通道仅在首次启动、休眠唤醒或错误重连后执行开流自检，默认持续 `5.0` 秒；通过后停止灰度、缩放、相位相关和帧差分析，正常取流不再持续承担检测开销。
-- 开流自检期间分别判断小幅反向垂直抖动、跨帧低相关度大帧差和单帧横向断层；达到阈值时只重启受影响通道，并在重新打开后开始新一轮独立自检。
-- 管理中心的“多光谱控制”页面可调整两类检测器的全部判断参数；保存写入 `pgu5a_config.json`，无需重启服务或整机。
+- MS602 六通道按 `ms602.open_stagger_sec` 间隔启动，当前现场值 `0.3` 秒。
+- MS602 每个通道仅在首次启动、休眠唤醒或错误重连后执行昂贵的开流图像自检，默认持续 `5.0` 秒；通过后停止灰度、缩放、相位相关和帧差分析。
+- 开流自检期间判断小幅反向垂直抖动、大幅/极大位移、跨帧低相关度大帧差和单帧横向断层；达到阈值时只重启受影响通道，并在重新打开后开始新一轮独立自检。
+- 轻量帧率监控在通道运行期间持续工作，默认最低 `2.0 FPS`、连续 `2` 次低帧率后恢复对应通道；正常间隔会清空连续异常计数。
+- 保存 MS602 六通道数据前校验缺失、恢复中、过期和跨通道时间偏差，默认最大帧龄 `2.0` 秒、最大时间偏差 `1.0` 秒。
+- 管理中心的“多光谱控制”页面可调整全部检测参数；保存写入 `pgu5a_config.json`，无需重启服务或整机。
 - M3Lite 使用 GPIO 8 延时上电，当前唤醒延迟 `2.0` 秒。
 - UVC-RGB 使用 GPIO 9 延时上电，当前唤醒延迟 `1.0` 秒。
 - 休眠会递增唤醒令牌，取消尚未完成的延时启动。
@@ -108,8 +119,8 @@ PGU5-Core 是运行在 Orange Pi 4 Pro 上的 PGU5 开放平台核心程序，
 界面当前版本来自：
 
 ```python
-APP_VERSION = "v2.0.5"
-APP_RELEASE_TAG = "v2.0.5"
+APP_VERSION = "v2.1.1"
+APP_RELEASE_TAG = "v2.1.1"
 ```
 
 Git 信息只用于诊断。在线升级先检查 Gitea Release，只有发现更新后才启用升级按钮。OTA 状态包括：

pgu5a_config.json

@@ -26,11 +26,11 @@
     "stream_fps": 10,
     "ms602_preview_width": 280,
     "m3lite_preview_width": 320,
-    "dcl_preview_width": 480,
+    "dcl_preview_width": 720,
     "uvc_rgb_preview_width": 240,
     "ms602_refresh_ms": 200,
     "m3lite_refresh_ms": 200,
-    "dcl_refresh_ms": 200,
+    "dcl_refresh_ms": 350,
     "uvc_rgb_refresh_ms": 480,
     "disk_refresh_sec": 5.0,
     "capture_interval_sec": 1.0,
@@ -45,7 +45,7 @@
     "target_fps": 8,
     "gain": 8,
     "d12": 0,
-    "open_stagger_sec": 0.5,
+    "open_stagger_sec": 0.3,
     "read_fail_restart_count": 5,
     "channel_reconnect_delay_sec": 0.8,
     "startup_detection_window_sec": 5.0,
@@ -57,13 +57,21 @@
     "jitter_window_sec": 3.0,
     "jitter_cancellation_ratio": 0.35,
     "jitter_total_shift_min": 0.35,
+    "jitter_large_shift_min": 0.8,
+    "jitter_large_shift_events": 2,
+    "jitter_extreme_shift_min": 1.0,
     "frame_integrity_detection_enabled": true,
     "frame_integrity_phase_response_min": 0.55,
     "frame_integrity_delta_min": 8.0,
     "frame_integrity_restart_events": 2,
     "frame_integrity_window_sec": 3.0,
     "frame_tearing_gradient_ratio_min": 2.0,
-    "frame_tearing_row_diff_min": 5.5
+    "frame_tearing_row_diff_min": 5.5,
+    "frame_rate_detection_enabled": true,
+    "frame_rate_min": 2.0,
+    "frame_rate_memory": 2,
+    "frame_max_age_sec": 2.0,
+    "frame_max_skew_sec": 1.0
   },
   "m3lite": {
     "width": 640,
@@ -83,6 +91,7 @@
     "control_timeout_ms": 2500
   },
   "dcl": {
+    "auto_detect": true,
     "camera_name": "ClearDCL00011",
     "width": 3840,
     "height": 1080,