merge: integrate OGScope branch stack / 合并 OGScope 分支栈

docs/API_ARCHITECTURE.md

@@ -17,6 +17,7 @@
 1. 业务逻辑放在 `domain/*` 或 `core/application/*`，`routes.py` 仅做 HTTP 适配。
 2. 对外稳定能力使用 `/api/core/v1/*`；开发者域使用 `/api/dev/*`。
 3. 同步更新契约文档：`docs/contracts/core-rest-v1.md` / `core-rest-v1_EN.md`，`dev-rest-v1.md` / `dev-rest-v1_EN.md`。
+4. 若新增调试页字段、相机遥测或分析结果 `overlay_ext`，同时更新 `docs/DEBUG_CONSOLE.md` / `DEBUG_CONSOLE_EN.md`。
 
 开发板部署总览见 [开发指南](development/README.md)（[English](development/README_EN.md)）。提交前自检见下文第 5 节。
 
@@ -90,6 +91,7 @@ HTTP Request
    - `docs/contracts/core-rest-v1.md`、`docs/contracts/core-rest-v1_EN.md`
    - `docs/contracts/dev-rest-v1.md`、`docs/contracts/dev-rest-v1_EN.md`
    - `docs/contracts/core-compatibility-matrix.md`（若涉及版本/路径策略）
+7. 调试控制台字段、相机管线遥测与分析扩展字段已同步到调试文档。
 
 ## 6) 快速验证命令
 

docs/API_ARCHITECTURE_EN.md

@@ -17,6 +17,7 @@ For system-level architecture (core boundary, user vs developer surfaces, operat
 1. Keep business logic in `domain/*` or `core/application/*`; `routes.py` handles HTTP adaptation only.
 2. Stable surface: `/api/core/v1/*`; developer surface: `/api/dev/*`.
 3. Update contract docs: `docs/contracts/core-rest-v1.md` / `core-rest-v1_EN.md`, `dev-rest-v1.md` / `dev-rest-v1_EN.md`.
+4. When adding debug-console fields, camera telemetry, or analysis-result `overlay_ext`, also update `docs/DEBUG_CONSOLE.md` / `DEBUG_CONSOLE_EN.md`.
 
 Board deployment overview: [Development Guide](development/README_EN.md) | [中文](development/README.md). Pre-submit checks: section 5 below.
 
@@ -90,6 +91,7 @@ Before API changes, confirm:
    - `docs/contracts/core-rest-v1.md` / `docs/contracts/core-rest-v1_EN.md`
    - `docs/contracts/dev-rest-v1.md` / `docs/contracts/dev-rest-v1_EN.md`
    - `docs/contracts/core-compatibility-matrix.md` (when versioning/path policy changes)
+7. Debug-console fields, camera-pipeline telemetry, and analysis extension fields are reflected in debug documentation.
 
 ## 6) Quick verification commands
 

docs/DEBUG_CONSOLE.md

@@ -9,9 +9,9 @@ OGScope 调试控制台是一个专为开发者设计的相机调试工具，提
 ## 🚀 功能特性
 
 ### 📷 实时预览
-- 15fps 实时相机预览
+- 低内存板优先的实时相机预览，目标帧率由 `preview_target_fps` 与运行时节流共同决定
 - 支持启动/停止预览
-- 实时状态显示
+- 实时状态显示：采集帧率、预览帧率、曝光、消费者数量、编码器与内存压力
 
 ### 📸 拍摄控制
 - **单张拍摄**: 拍摄高质量照片并自动保存
@@ -23,6 +23,10 @@ OGScope 调试控制台是一个专为开发者设计的相机调试工具，提
 - **曝光时间**: 1ms - 100ms (微秒级调节)
 - **模拟增益**: 1x - 16x (0.1x步进)
 - **数字增益**: 1x - 4x (0.1x步进)
+- **白平衡**: `auto` / `manual` / `night`，手动模式可设置红/蓝增益
+- **自动曝光上限**: `camera_auto_exposure_max_us` 控制暗场最长帧周期
+- **防闪烁与降噪**: 支持 AE flicker 与语义降噪模式
+- **预览编码器**: `auto` / `turbojpeg` / `opencv`
 - **实时应用**: 参数修改立即生效
 - **一键重置**: 恢复到默认设置
 
@@ -157,6 +161,21 @@ python -m ogscope.web.app
 - `POST /api/dev/debug/camera/settings` - 更新相机设置
 - `POST /api/dev/debug/camera/reset` - 重置到默认设置
 
+当前相机状态还会返回调试字段：
+
+| 字段 | 说明 |
+|------|------|
+| `sensor_target_fps` / `preview_target_fps` | 传感器与预览目标帧率 |
+| `actual_capture_fps` / `actual_preview_fps` | 实测采集与预览帧率 |
+| `actual_exposure_us` / `frame_duration_us` | 当前曝光与帧周期 |
+| `preview_consumers` / `analysis_consumers` / `recording_consumers` | 预览、分析、录制消费者数量 |
+| `jpeg_average_encode_ms` / `jpeg_cached_bytes` | JPEG 编码耗时与缓存大小 |
+| `throttle_reason` | 当前节流原因，例如低内存或无消费者 |
+| `process_rss_kb` / `process_swap_kb` / `cma_free_kb` | 进程内存、swap 与 CMA 可用量 |
+| `preview_encoder` / `jpeg_source_format` | 当前预览编码器和输入格式 |
+| `camera_driver` / `camera_backend` | 相机驱动与后端名称 |
+| `lores_enabled` / `lores_available` / `lores_width` / `lores_height` / `lores_format` | 低分辨率辅助流状态 |
+
 ### 预设管理
 - `GET /api/dev/debug/camera/presets` - 获取预设列表
 - `POST /api/dev/debug/camera/presets` - 保存预设
@@ -192,6 +211,26 @@ python scripts/test_debug_console.py --test deps
 2. **权限要求**: 相机访问需要适当的系统权限
 3. **存储空间**: 确保有足够的存储空间保存拍摄文件
 4. **网络访问**: 调试控制台通过Web界面访问，确保网络连接正常
+5. **32 位系统**: OpenCV、SciPy、PyTurboJPEG 在 32 位系统上可能没有合适 wheel，优先使用系统包或 piwheels；低内存板建议降低预览帧率并启用自动编码器选择。
+
+## 🧩 相机管线配置
+
+这些配置可通过环境变量或配置文件进入运行时。名称与 `ogscope/config.py` 一致：
+
+| 配置 | 默认 | 说明 |
+|------|------|------|
+| `camera_idle_shutdown_sec` | `20.0` | 无消费者后相机热驻留时间，超时后释放采集 |
+| `camera_frame_stale_timeout_sec` | `5.0` | 超过该时间没有成功帧时重新探测 |
+| `camera_white_balance_mode` | `auto` | `auto` / `manual` / `night` |
+| `camera_white_balance_gain_r` / `camera_white_balance_gain_b` | `1.0` | 手动白平衡红/蓝增益 |
+| `camera_night_mode` | `false` | 启动时应用夜间白平衡标记 |
+| `camera_auto_exposure_max_us` | `2000000` | 自动曝光最长帧周期，暗场允许降低帧率 |
+| `camera_ae_flicker_mode` | `off` | `off` / `50hz` / `60hz` |
+| `camera_noise_reduction_mode` | `fast` | `off` / `fast` / `high_quality` |
+| `camera_lores_enabled` | `true` | 启用低分辨率辅助流统计 |
+| `camera_lores_width` / `camera_lores_height` | `320` / `240` | 低分辨率辅助流尺寸 |
+| `camera_lores_format` | `YUV420` | 低分辨率辅助流格式 |
+| `preview_encoder` | `auto` | `auto` / `turbojpeg` / `opencv` |
 
 ## 🐛 故障排除
 

docs/DEBUG_CONSOLE_EN.md

@@ -9,9 +9,9 @@ The OGScope debug console is a developer-focused camera tool: live preview, capt
 ## Features
 
 ### Live preview
-- ~15 fps live preview
+- Low-memory-board-friendly live preview. Effective FPS is governed by `preview_target_fps` and runtime throttling.
 - Start/stop preview
-- Live status
+- Live status: capture FPS, preview FPS, exposure, consumers, encoder, and memory pressure
 
 ### Capture
 - **Still capture**: high-quality photos with auto-save
@@ -23,6 +23,10 @@ The OGScope debug console is a developer-focused camera tool: live preview, capt
 - **Exposure**: 1ms–100ms (fine steps)
 - **Analog gain**: 1x–16x (0.1x steps)
 - **Digital gain**: 1x–4x (0.1x steps)
+- **White balance**: `auto` / `manual` / `night`; manual mode exposes red/blue gains
+- **Auto-exposure ceiling**: `camera_auto_exposure_max_us` controls the longest dark-field frame duration
+- **Flicker and noise reduction**: AE flicker and semantic noise-reduction modes
+- **Preview encoder**: `auto` / `turbojpeg` / `opencv`
 - **Apply immediately**: changes take effect at once
 - **Reset**: restore defaults
 
@@ -121,6 +125,21 @@ Browser: `http://localhost:8000/debug`
 - `POST /api/dev/debug/camera/settings`
 - `POST /api/dev/debug/camera/reset`
 
+Camera status also exposes diagnostic fields:
+
+| Field | Meaning |
+|-------|---------|
+| `sensor_target_fps` / `preview_target_fps` | Sensor and preview target FPS |
+| `actual_capture_fps` / `actual_preview_fps` | Measured capture and preview FPS |
+| `actual_exposure_us` / `frame_duration_us` | Current exposure and frame duration |
+| `preview_consumers` / `analysis_consumers` / `recording_consumers` | Preview, analysis, and recording consumers |
+| `jpeg_average_encode_ms` / `jpeg_cached_bytes` | JPEG encode time and cached bytes |
+| `throttle_reason` | Current throttle reason, for example low memory or no consumers |
+| `process_rss_kb` / `process_swap_kb` / `cma_free_kb` | Process memory, swap, and CMA free memory |
+| `preview_encoder` / `jpeg_source_format` | Selected preview encoder and input format |
+| `camera_driver` / `camera_backend` | Camera driver and backend names |
+| `lores_enabled` / `lores_available` / `lores_width` / `lores_height` / `lores_format` | Low-resolution helper stream state |
+
 ### Presets
 - `GET /api/dev/debug/camera/presets`
 - `POST /api/dev/debug/camera/presets`
@@ -147,6 +166,26 @@ python scripts/test_debug_console.py --test deps
 2. **Permissions**: camera access for the service user.
 3. **Disk**: ensure free space for captures.
 4. **Network**: Web UI requires reachable HTTP port.
+5. **32-bit OS**: OpenCV, SciPy, and PyTurboJPEG may not have suitable wheels. Prefer distro packages or piwheels, and use lower preview FPS plus automatic encoder selection on low-memory boards.
+
+## Camera Pipeline Configuration
+
+These settings enter runtime through environment variables or config files. Names match `ogscope/config.py`:
+
+| Setting | Default | Meaning |
+|---------|---------|---------|
+| `camera_idle_shutdown_sec` | `20.0` | Warm-idle timeout after the last consumer |
+| `camera_frame_stale_timeout_sec` | `5.0` | Re-probe when no successful frame arrives within this duration |
+| `camera_white_balance_mode` | `auto` | `auto` / `manual` / `night` |
+| `camera_white_balance_gain_r` / `camera_white_balance_gain_b` | `1.0` | Manual white-balance red/blue gains |
+| `camera_night_mode` | `false` | Apply night white-balance flag at startup |
+| `camera_auto_exposure_max_us` | `2000000` | Longest AE frame duration for dark fields |
+| `camera_ae_flicker_mode` | `off` | `off` / `50hz` / `60hz` |
+| `camera_noise_reduction_mode` | `fast` | `off` / `fast` / `high_quality` |
+| `camera_lores_enabled` | `true` | Enable the low-resolution helper stream |
+| `camera_lores_width` / `camera_lores_height` | `320` / `240` | Low-resolution helper stream size |
+| `camera_lores_format` | `YUV420` | Low-resolution helper stream format |
+| `preview_encoder` | `auto` | `auto` / `turbojpeg` / `opencv` |
 
 ## Troubleshooting
 

docs/architecture/OGSCOPE_SYSTEM_ARCHITECTURE_BILINGUAL.md

@@ -54,7 +54,6 @@ flowchart TD
   subgraph peripheralLayer["外围硬件层 / Peripheral Hardware Layer"]
     cameraHw["相机 / Camera IMX327"]
     wifiHw["网络模块 / WiFi and NetworkManager"]
-    gpioHw["应急GPIO / Emergency GPIO"]
     magnetometerHw["磁力计（规划） / Magnetometer (Planned)"]
     gpsHw["GPS（规划） / GPS (Planned)"]
     gyroHw["陀螺仪（规划） / Gyroscope (Planned)"]

docs/contracts/core-rest-v1.md

@@ -55,18 +55,20 @@
 - `GET /api/core/v1/system/status`
 - 响应：
   - `success: bool`
-  - `health: str`
+  - `health: str`（`healthy` | `degraded`）
+  - `health_reasons: string[]`（降级时的稳定原因码，如 `camera_not_connected`、`network_wifi_not_configured`；`healthy` 时为空数组）
   - `version: str`
   - `capabilities: object`
   - `system: object`
   - `camera: object`（相机在线与运行态摘要）
-  - `network: object`（WiFi 模式/信号/连接态）
+  - `network: object`（WiFi 模式/信号/连接态；含 `managed_by`、`in_health_scope`；subordinate 或最小部署未配 WiFi 时为 `delegated`，**不参与** `health`）
   - `sensors: object`（温度/CPU/内存等核心传感状态）
 
 ### 5) Camera Runtime & Preview (MJPEG / single-frame)
 
 - `GET /api/core/v1/camera/status`
-  - 返回相机连接状态、流状态与 runtime overrides
+  - 返回相机连接状态、流状态、runtime overrides 与可选 `ambient_hint`
+  - `ambient_hint` 是环境亮度建议遥测，供上层设备做显示/交互策略参考；典型字段包括 `available`、`dark_score`（0.0 明亮到 1.0 昏暗）、`lux`、`exposure_us`、`digital_gain`
 - `POST /api/core/v1/camera/start`
 - `POST /api/core/v1/camera/stop`
 
@@ -96,4 +98,4 @@ MJPEG 连续视频流与流控状态、单帧 JPEG 预览（轮询、`since_fram
 
 - `4xx`：请求参数非法、契约字段校验失败。
 - `5xx`：内部运行异常或底层能力不可用。
-- 契约版本路径固定为 `/v1/`。新增字段以可选形式扩展，不破坏既有消费者。
+- 契约版本路径固定为 `/v1/`。新增字段以可选形式扩展，不破坏既有消费者。

docs/contracts/core-rest-v1_EN.md

@@ -55,17 +55,19 @@ This document defines the **minimal stable REST surface** for callers integratin
 - `GET /api/core/v1/system/status`
 - Response:
   - `success: bool`
-  - `health: str`
+  - `health: str` (`healthy` | `degraded`)
+  - `health_reasons: string[]` — stable degradation codes when not healthy (e.g. `camera_not_connected`, `network_wifi_not_configured`); empty when `healthy`
   - `version: str`
   - `capabilities: object`
   - `system: object`
   - `camera: object` — camera online and runtime summary
-  - `network: object` — WiFi mode / signal / connection state
+  - `network: object` — WiFi mode / signal / connection; includes `managed_by`, `in_health_scope`; when subordinate or minimal deploy without OGScope WiFi config, status is `delegated` and **does not** affect `health`
   - `sensors: object` — temperature / CPU / memory, etc.
 
 ### 5) Camera Runtime & Preview (MJPEG / single-frame)
 
-- `GET /api/core/v1/camera/status` — connection, stream state, runtime overrides
+- `GET /api/core/v1/camera/status` — connection, stream state, runtime overrides, and optional `ambient_hint`
+  - `ambient_hint` is advisory ambient-light telemetry for upstream display/interaction policy. Typical fields: `available`, `dark_score` (0.0 bright to 1.0 dark), `lux`, `exposure_us`, `digital_gain`
 - `POST /api/core/v1/camera/start`
 - `POST /api/core/v1/camera/stop`
 

docs/contracts/dev-rest-v1.md

@@ -16,6 +16,41 @@
 - 分析实验：`/api/dev/analysis/*`
   - 素材池、实验记录、离线/在线解算与参数试验
 
+## 调试相机状态
+
+- `GET /api/dev/debug/camera/status`
+  - 用途：开发者调试页与板端性能排查。
+  - 典型字段：
+    - `sensor_target_fps` / `preview_target_fps`：传感器与预览目标帧率
+    - `actual_capture_fps` / `actual_preview_fps`：运行时采集与预览实际帧率
+    - `actual_exposure_us` / `frame_duration_us`：曝光与帧时长遥测
+    - `preview_consumers` / `analysis_consumers` / `recording_consumers`：消费者数量
+    - `jpeg_average_encode_ms` / `jpeg_cached_bytes` / `jpeg_encode_failures`：JPEG 编码健康度
+    - `throttle_reason`：运行时降速原因，空值表示未主动降速
+    - `process_rss_kb` / `process_swap_kb` / `cma_free_kb`：低内存板排查指标
+    - `preview_encoder` / `jpeg_source_format`：当前预览编码器与源格式
+    - `camera_driver` / `camera_backend`：相机驱动与后端
+    - `lores_enabled` / `lores_available` / `lores_width` / `lores_height` / `lores_format`：低分辨率支路状态
+
+### 相机调试设置
+
+- `POST /api/dev/debug/camera/settings`
+  - 用途：开发调试 UI 的增量设置入口，不属于稳定对外契约。
+  - 近期字段包括：
+    - `whiteBalanceMode`、`whiteBalanceGainR`、`whiteBalanceGainB`
+    - `autoExposureMaxUs`
+    - `aeFlickerMode`
+    - `noiseReductionMode`
+    - `previewEncoder`
+
+## 分析实验扩展
+
+- `POST /api/dev/analysis/solve/frame`
+- `POST /api/dev/analysis/solve/frame_upload`
+  - 请求可选 `enable_polar_guide`。
+  - 响应中的 `overlay_ext.polar_guide` 是实验性极轴引导叠加数据，用于开发 UI 验证，不属于 `core/v1` 稳定字段。
+  - `overlay_ext.labels_topn` 与 `overlay_ext.polar_guide` 可独立存在；调用方应按可选字段处理。
+
 ## 文档入口
 
 - 标准接口文档：`/docs`（默认）

docs/contracts/dev-rest-v1_EN.md

@@ -16,6 +16,41 @@ This document describes OGScope **developer-domain** APIs (internal). They are *
 - Analysis lab: `/api/dev/analysis/*`
   - Asset pool, experiment records, offline/online solving and parameter trials
 
+## Debug camera status
+
+- `GET /api/dev/debug/camera/status`
+  - Purpose: developer console diagnostics and board-side performance triage.
+  - Typical fields:
+    - `sensor_target_fps` / `preview_target_fps`: sensor and preview target FPS
+    - `actual_capture_fps` / `actual_preview_fps`: runtime capture and preview FPS
+    - `actual_exposure_us` / `frame_duration_us`: exposure and frame-duration telemetry
+    - `preview_consumers` / `analysis_consumers` / `recording_consumers`: active consumers
+    - `jpeg_average_encode_ms` / `jpeg_cached_bytes` / `jpeg_encode_failures`: JPEG encoder health
+    - `throttle_reason`: runtime throttling reason; empty means no active throttling
+    - `process_rss_kb` / `process_swap_kb` / `cma_free_kb`: low-memory-board diagnostics
+    - `preview_encoder` / `jpeg_source_format`: active preview encoder and source format
+    - `camera_driver` / `camera_backend`: camera driver and backend
+    - `lores_enabled` / `lores_available` / `lores_width` / `lores_height` / `lores_format`: low-resolution stream status
+
+### Debug camera settings
+
+- `POST /api/dev/debug/camera/settings`
+  - Purpose: incremental settings endpoint for the developer UI; not part of the stable external contract.
+  - Recent fields include:
+    - `whiteBalanceMode`, `whiteBalanceGainR`, `whiteBalanceGainB`
+    - `autoExposureMaxUs`
+    - `aeFlickerMode`
+    - `noiseReductionMode`
+    - `previewEncoder`
+
+## Analysis lab extensions
+
+- `POST /api/dev/analysis/solve/frame`
+- `POST /api/dev/analysis/solve/frame_upload`
+  - Request may include optional `enable_polar_guide`.
+  - `overlay_ext.polar_guide` in the response is experimental polar-guide overlay data for developer UI validation; it is not a stable `core/v1` field.
+  - `overlay_ext.labels_topn` and `overlay_ext.polar_guide` are independent optional fields; callers must handle either one being absent.
+
 ## Documentation entrypoints
 
 - Standard OpenAPI: `/docs` (default)

docs/contracts/subordinate-mode.md

@@ -42,6 +42,11 @@ OGScope 支持两种硬件平面角色：
 - **业务调用**：上层集成方 → OGScope `REST /api/core/v1/*`（详见 [core-rest-v1](core-rest-v1.md)）。
 - **传感器委托**：OGScope → 外部传感器服务 `UDS JSON-RPC`（详见 [hardware-plane-uds-v1](hardware-plane-uds-v1.md)）。
 
+## 健康状态（health）
+
+- subordinate 或最小部署未配置 OGScope WiFi 脚本/连接名时，`GET /api/core/v1/system/status` 的 `network` 块为 `managed_by: external`（或 standalone 未配时为 `unconfigured`）、`status: delegated`，**不参与** `health` / `health_reasons` 计算。
+- 此时 `health` 仅反映 OGScope 职责内子系统（当前主要为相机）；上层集成方应自行监控网络。
+
 ## 版本与兼容
 
 - 契约以增量扩展为主；破坏性变更须更新本文档与 [core-compatibility-matrix](core-compatibility-matrix.md)。