ruvnet--ruview/README.md

<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/ruvnet/RuView) · [上游 README](https://github.com/ruvnet/RuView/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

# π RuView

<p align="center">
  <a href="https://cognitum.one/seed">
    <img src="assets/ruview-seed.png" alt="RuView - WiFi DensePose" width="100%">
  </a>
</p>
<p align="center">
  <a href="https://cognitum.one/seed">
    <img src="assets/seed.png" alt="Cognitum Seed" width="100%">
  </a>
</p>

## **用 WiFi 看穿墙壁** ##

**将普通 WiFi 变为空间智能/感知系统。** 检测人员、测量呼吸与心率、追踪移动、监控房间——穿墙、无光环境，无需摄像头或可穿戴设备。纯物理原理。

原生支持四大智能家居生态：通过 HA-DISCO MQTT 发布器接入 **[Home Assistant](docs/integrations/home-assistant.md)**，以可发现的 HAP-1.1 桥接器接入 **[Apple Home 和 HomePod](docs/user-guide-apple-homepod.md)**，通过同一 HA 桥或 [Matter](docs/adr/ADR-122-bfld-ruview-ha-matter-exposure.md) 端点接入 **[Google Home](docs/integrations/home-assistant.md)** 和 **[Amazon Alexa](docs/integrations/home-assistant.md)**。Siri、Google Assistant 和 Alexa 无需自定义技能即可按房间语音查询人员存在与生命体征。

[![Works with Home Assistant](https://img.shields.io/badge/Works%20with-Home%20Assistant-blue?logo=home-assistant&logoColor=white&labelColor=41BDF5)](docs/integrations/home-assistant.md) [![Works with Matter](https://img.shields.io/badge/Works%20with-Matter-blue?labelColor=4285F4)](docs/adr/ADR-122-bfld-ruview-ha-matter-exposure.md) [![Works with Apple Home](https://img.shields.io/badge/Works%20with-Apple%20Home-black?logo=apple)](docs/user-guide-apple-homepod.md) [![Works with Google Home](https://img.shields.io/badge/Works%20with-Google%20Home-blue?logo=googlehome)](docs/integrations/home-assistant.md) [![Works with Alexa](https://img.shields.io/badge/Works%20with-Alexa-blue?logo=amazon&logoColor=white&labelColor=00CAFF)](docs/integrations/home-assistant.md)

> 通过一个 `--mqtt` 标志即可**嵌入任何 Home Assistant** 安装。或者作为 Matter 桥接器配对到 **Apple Home / Google Home / Alexa / SmartThings**。每个节点提供 21 个实体（11 个原始信号 + 10 个推断语义状态：有人入睡、可能遇险、房间活跃、老人活动异常、会议进行中、卫生间占用、跌倒风险升高、离床、无移动、跨房间移动），外加 3 个入门级 HA Blueprint。参见 [`docs/integrations/home-assistant.md`](docs/integrations/home-assistant.md) · [ADR-115](docs/adr/ADR-115-home-assistant-integration.md)。

### π RuView 是一个将无线电信号转化为空间智能的 WiFi 感知平台。

每个 WiFi 路由器早已用无线电波填满你的空间。当人员移动、呼吸甚至静坐时，都会以可测量的方式扰动这些电波。RuView 通过低成本 ESP32 传感器捕获信道状态信息（CSI）来捕捉这些扰动，并将其转化为可操作的数据：谁在那里、他们在做什么、以及他们是否安好。

**可感知的内容：**
- **存在与占用检测**——穿墙检测人员、统计人数、追踪进出
- **生命体征**——呼吸频率与心率，无接触式测量，睡眠或静坐时均可
- **活动识别**——行走、坐姿、手势、跌倒——基于时间序列 CSI 模式
- **环境映射**——射频指纹识别房间、检测家具移动、发现新物体
- **睡眠质量**——夜间监测，含睡眠阶段分类与呼吸暂停筛查

基于 [RuVector](https://github.com/ruvnet/ruvector/)) 和 [Cognitum Seed](https://cognitum.one),)，RuView 完全运行在边缘硬件上——ESP32 网状网络（每节点低至 9 美元）配合 Cognitum Seed 提供持久化内存、加密证明和 AI 集成。无需云服务、无需摄像头、无需互联网。

系统使用脉冲神经网络（Spiking Neural Networks）在本地学习每个环境，30 秒内即可自适应，并通过跨 6 个 WiFi 信道的多频网状扫描，将邻居的路由器用作免费的雷达发射源。每次测量均通过 Ed25519 见证链进行加密证明。

RuView 将普通 WiFi 变为非接触式传感器。一块 9 美元的 ESP32 板卡读取房间内人员身上的无线电反射信号，一个发布在 Hugging Face [`ruvnet/wifi-densepose-pretrained`](https://huggingface.co/ruvnet/wifi-densepose-pretrained)) 上的小型预训练模型——告诉你谁在那里、呼吸状况如何、心率趋势如何。该模型仅占用 8 KB（4 位量化），在 Raspberry Pi 上微秒级运行。（[v2 编码器](https://huggingface.co/ruvnet/wifi-densepose-pretrained)) 报告了诚实、无标签的独立测试**时间三元组准确率为 82.3%**——较原始 66.4% 有所提升；此前的"100% 存在检测"数据基于单类别录制测得，已撤回并由本数据替代。）无需摄像头、无需可穿戴设备、无需用户手机上的应用。

### 专为低功耗边缘应用打造

[边缘模块](#edge-intelligence-adr-041) 是直接在 ESP32 传感器上运行的小型程序——无需互联网、无需云服务费用、即时响应。

[![Rust 1.85+](https://img.shields.io/badge/rust-1.85+-orange.svg)](https://www.rust-lang.org/))
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT))
[![Tests: 1463](https://img.shields.io/badge/tests-1463%20passed-brightgreen.svg)](https://github.com/ruvnet/RuView))
[![Docker: multi-arch](https://img.shields.io/badge/docker-amd64%20%2B%20arm64-blue.svg)](https://hub.docker.com/r/ruvnet/wifi-densepose))
[![Vital Signs](https://img.shields.io/badge/vital%20signs-breathing%20%2B%20heartbeat-red.svg)](#vital-sign-detection))
[![ESP32 Ready](https://img.shields.io/badge/ESP32--S3-CSI%20streaming-purple.svg)](#esp32-s3-hardware-pipeline))
[![crates.io](https://img.shields.io/crates/v/wifi-densepose-ruvector.svg)](https://crates.io/crates/wifi-densepose-ruvector))
[![Downloads](https://img.shields.io/badge/downloads-10M%2B-brightgreen.svg)](#-edge-module-catalog))

 
> | 功能 | 方式 | 速度/规模 |
> |------|------|----------|
> | 🫁 **呼吸频率** | 对包裹相位进行 0.1–0.5 Hz 带通滤波、循环方差、过零 BPM（[#593](https://github.com/ruvnet/RuView/issues/593)))） | 6–30 BPM，实时 |
> | 💓 **心率** | 0.8–2.0 Hz 带通滤波、过零 BPM | 40–120 BPM，实时 |
> | 👤 **存在检测** | Hugging Face 上的训练头部（[`ruvnet/wifi-densepose-pretrained`](https://huggingface.co/ruvnet/wifi-densepose-pretrained);)，v2 编码器 = 82.3% 独立测试时间三元组准确率，诚实重新基准测试）+ 无需模型的相位方差回退方案 | < 1 ms，约 30 秒环境校准 |
> | 🧬 **CSI 嵌入** | 发布在 Hugging Face 的 128 维对比编码器，4 位量化变体仅 8 KB | M4 Pro 上 **164,183 嵌入/秒** |
> | 🦴 **17 关键点姿态估计** | `cog-pose-estimation` Cog v0.0.1——GCS 上已签名的 aarch64 + x86_64 二进制文件，通过 Candle 加载 `pose_v1.safetensors`。在 RTX 5080 上 2.1 秒即可从配对数据训练自己的模型（[ADR-101](docs/adr/ADR-101-pose-estimation-cog.md)、[基准测试](docs/benchmarks/pose-estimation-cog.md)）。**MM-Fi 上 SOTA：** [`ruvnet/wifi-densepose-mmfi-pose`](https://huggingface.co/ruvnet/wifi-densepose-mmfi-pose)) 在匹配的 MM-Fi `random_split` 协议上达到 **82.69% 躯干 PCK@20**（集成 83.59%），超越 MultiFormer（72.25%）和 CSI2Pose（68.41%）——经自我纠正，可在 [AetherArena](https://huggingface.co/spaces/ruvnet/aether-arena)) 上审计 | Pi 5 上冷启动 8.4 ms |
> | 🚶 **运动/活动** | 运动频带功率 + 相位加速度 | 实时 |
> | 🤸 **跌倒检测** | 相位加速度阈值 + 3 帧防抖 + 5 秒冷却（[#263](https://github.com/ruvnet/RuView/issues/263)))） | < 200 ms |
> | 🧮 **多人计数** | 自适应 P95 归一化 + 运行时可调去重因子（`/api/v1/config/dedup-factor`，[#491](https://github.com/ruvnet/RuView/pull/491)).)）。提供 6 个专门的学习型计数器 Cog：`occupancy-zones`、`elevator-count`、`queue-length`、`customer-flow`、`clean-room`、`person-matching` | 实时，自校准 |
> | 🌍 **世界模型预测** | OccWorld TransVQVAE——15 帧未来占用预测，209 ms 推理，RTX 5080 上 3.4 GB VRAM；使用 `occworld_retrain.py` 在你的空间微调（[ADR-147](docs/adr/ADR-147-nvidia-cosmos-world-foundation-model-integration.md)） | 15 帧 × 200×200×16 体素 |
> | 🧱 **穿墙感知** | 菲涅尔区几何 + 多径建模 | 最远约 5 m，依信号而定 |
> | 🧠 **边缘智能** | **105 个 Cog 目录**（[ADR-102](docs/adr/ADR-102-edge-module-registry.md)）从 `app-registry.json` 实时提供——涵盖健康、安防、建筑、零售、工业、科研、AI、集群、信号、网络和开发模块。可选 Cognitum Seed 增加持久化向量存储 + kNN + 见证链 | 物料清单总计 140 美元 |
> | 🎯 **无摄像头预训练** | 自监督对比编码器，60K 帧上 1220 万步训练，发布在 Hugging Face | M4 Pro 上重训练 84 秒/epoch |
> | 📷 **摄像头监督微调** | MediaPipe + ESP32 CSI 配对训练，RTX 5080 上端到端 Candle 流水线（[ADR-079](docs/adr/ADR-079-camera-supervised-pose-finetune.md)） | 400 epoch 仅 2.1 秒（约 5 ms/epoch） |
> | 📡 **多频网状网络** | 跨 6 个频段的信道跳频、TDM 时隙调度（[ADR-029](docs/adr/ADR-029-multifrequency-mesh.md)） | 3 倍感知带宽 |
> | 🌐 **3D 点云融合** | 摄像头深度（MiDaS）+ WiFi CSI + 毫米波雷达 → 统一空间模型 | 22 ms 流水线 · 每帧 19K+ 点 |
>
> 浏览完整的 105 模块目录（含实用描述、规模和难度），请参见下方 [🧩 边缘模块目录](#-edge-module-catalog)，或访问 [seed.cognitum.one/store](https://seed.cognitum.one/store).)
>
> 🤗 **预训练权重**：从 [`ruvnet/wifi-densepose-pretrained`](https://huggingface.co/ruvnet/wifi-densepose-pretrained)) 下载——参见下方 [加载预训练模型](#loading-the-pretrained-model) 一行命令即可完成设置。

```bash
# Option 1: Docker (simulated data, no hardware needed)
docker pull ruvnet/wifi-densepose:latest
docker run -p 3000:3000 ruvnet/wifi-densepose:latest
# Open http://localhost:3000

# Option 2a: Live sensing with ESP32-S3 hardware ($9)
# Flash firmware, provision WiFi, and start sensing:
python -m esptool --chip esp32s3 --port COM9 --baud 460800 \
  write_flash 0x0 bootloader.bin 0x8000 partition-table.bin \
  0xf000 ota_data_initial.bin 0x20000 esp32-csi-node.bin
python firmware/esp32-csi-node/provision.py --port COM9 \
  --ssid "YourWiFi" --password "secret" --target-ip 192.168.1.20

# Option 2b: WiFi 6 + 802.15.4 research sensing with ESP32-C6 ($6-10, ADR-110)
# Same csi-node firmware compiled for the C6 target — picks up the C6
# overlay (sdkconfig.defaults.esp32c6) automatically.
cd firmware/esp32-csi-node
idf.py set-target esp32c6 && idf.py build
idf.py -p COM6 flash
# C6 boot extras (vs S3): HE-LTF subcarrier tagging in ADR-018 bytes 18-19,
#   802.15.4 mesh time-sync on channel 15, TWT setup when the AP supports it,
#   opt-in LP-core wake-on-motion for ~5 µA battery seed nodes.
# v0.6.7 adds: real LP-core RISC-V motion-gate program (debounce + motion
#   counter) and a Wi-Fi 6 soft-AP with TWT Responder so two C6 boards can
#   benchmark real iTWT without buying an 11ax router. Both default off,
#   flip CONFIG_C6_{LP_CORE,SOFTAP_HE}_ENABLE to turn them on.

# Option 3: Full system with Cognitum Seed ($140)
# ESP32 streams CSI → bridge forwards to Seed for persistent storage + kNN + witness chain
node scripts/rf-scan.js --port 5006           # Live RF room scan
node scripts/snn-csi-processor.js --port 5006  # SNN real-time learning
node scripts/mincut-person-counter.js --port 5006  # Correct person counting

# Option 4: Python — live on PyPI (ADR-117)
pip install ruview                        # or: pip install wifi-densepose
# Both ship the same compiled PyO3 wheel (~250 KB, abi3-py310, Linux/macOS/Windows).
# Add [client] for the asyncio WebSocket + paho-mqtt clients:
pip install "ruview[client]"              # or: pip install "wifi-densepose[client]"

# from ruview import BreathingExtractor, HeartRateExtractor   # equivalent to:
# from wifi_densepose import BreathingExtractor, HeartRateExtractor
# from ruview.client import SensingClient, RuViewMqttClient
```

[![PyPI ruview](https://img.shields.io/pypi/v/ruview?label=ruview)](https://pypi.org/project/ruview/) [![PyPI wifi-densepose](https://img.shields.io/pypi/v/wifi-densepose?label=wifi-densepose)](https://pypi.org/project/wifi-densepose/)

> [!NOTE]
> **建议使用支持 CSI 的硬件。** 存在检测、生命体征、穿墙感知及所有高级能力均需要来自 ESP32-S3（$9）或研究型 NIC 的信道状态信息（Channel State Information，CSI）。Docker 镜像使用模拟数据运行以供评估。消费级 WiFi 笔记本电脑仅提供基于 RSSI 的存在检测。

> **实时 CSI 采集的硬件选项**：
>
> | 选项 | 硬件 | 成本 | 完整 CSI | 能力 |
> |--------|----------|------|----------|-------------|
> | **ESP32 + Cognitum Seed**（推荐） | ESP32-S3 + [Cognitum Seed](https://cognitum.one) | ~$140 | 是 | 存在检测、运动、呼吸、心率、跌倒检测、多人计数、17 关键点姿态（已签名 Cog 二进制）、105-cog 目录、持久化向量存储、kNN 搜索、witness 链、MCP 代理 |
> | **ESP32 Mesh** | 3-6× ESP32-S3 + WiFi 路由器 | ~$54 | 是 | 与上述相同的能力，但不包含持久化内存功能 |
> | **ESP32-C6 研究节点**（[ADR-110](docs/adr/ADR-110-esp32-c6-firmware-extension.md)、[witness](docs/WITNESS-LOG-110.md)、[reviewer guide](docs/ADR-110-REVIEW-GUIDE.md)、[firmware v0.7.0](https://github.com/ruvnet/RuView/releases/tag/v0.7.0-esp32)) | ESP32-C6-DevKit（$6–10） | ~$10 | 是（支持 Wi-Fi 6） | 与 S3 相同的 CSI 流水线，采用双目标固件。**固件端 ADR-110 基板现已关闭**（v0.7.0）：ESP-NOW 跨板 mesh 在 5 分钟双板浸泡测试中量化结果为 **99.56% 匹配 / 104 µs 平滑偏移标准差 / 3.95× EMA 抑制**（witness §A0.10），32 字节 UDP 同步包，支持操作员可调节奏（§A0.12），ADR-018 字节 19 位 4 线路修复源自可用的 ESP-NOW 路径（§A0.13）。线路格式已就绪，可在 ADR-018 字节 18-19 中进行 HE-LTF PPDU 标记（固件编码器 + Rust + Python 解码器已通过 23 个单元测试完成端到端验证）。LP-core 运动门控 RISC-V 程序以及带 TWT Responder 的 Wi-Fi 6 soft-AP 均作为可选代码路径提供（默认关闭）。**需硬件配合方可测量**：HE-LTF 实时子载波采集需要 11ax AP（IDF v5.4 不暴露 AP 端 HE 配置 — §A0.6）；约 5 µA LP-core 休眠需要 INA 仪表才能采集；IDF v5.4 中 802.15.4 原始 RX 不可用（变通方案：ESP-NOW 传输，已交付并测量）。有关实测与宣称部分的划分，请参阅 witness 日志。 |
> | **研究型 NIC** | Intel 5300 / Atheros AR9580 | ~$50-100 | 是 | 完整 CSI，支持 3x3 MIMO |
> | **任意 WiFi** | Windows、macOS 或 Linux 笔记本电脑 | $0 | 否 | 仅 RSSI：粗略的存在与运动检测（参见 [教程 #36](https://github.com/ruvnet/RuView/issues/36)) |
>
> 没有硬件？可使用确定性参考信号验证信号处理流水线：`python archive/v1/data/proof/verify.py`
>
---


  <a href="https://ruvnet.github.io/RuView/">
    <img src="assets/v2-screen.png" alt="WiFi DensePose — 实时姿态检测与设置指南" width="800">
  </a>
  <br>
  <em>来自 WiFi CSI 信号的实时姿态骨架 — 无需摄像头，无需可穿戴设备</em>
  <br><br>
  <a href="https://ruvnet.github.io/RuView/"><strong>▶ 实时观测台演示</strong></a>
  &nbsp;|&nbsp;
  <a href="https://ruvnet.github.io/RuView/pose-fusion.html"><strong>▶ 双模态姿态融合演示</strong></a>
  &nbsp;|&nbsp;
  <a href="https://ruvnet.github.io/RuView/pointcloud/"><strong>▶ 实时 3D 点云</strong></a>
  &nbsp;|&nbsp;
  <a href="https://ruvnet.github.io/RuView/three.js/"><strong>▶ three.js 演示（5 个）</strong></a>

> [服务器](#-quick-start) 对于可视化与聚合是可选的 — ESP32 可[独立运行](#esp32-s3-hardware-pipeline)，用于存在检测、生命体征与跌倒告警。
>
> **实时 ESP32 流水线**：连接 ESP32-S3 节点 → 运行 [sensing server](#sensing-server) → 打开 [姿态融合演示](https://ruvnet.github.io/RuView/pose-fusion.html) 进行实时双模态姿态估计（网络摄像头 + WiFi CSI）。参见 [ADR-059](docs/adr/ADR-059-live-esp32-csi-pipeline.md)。
>
> **three.js 场景画廊**位于 [`/three.js/`](https://ruvnet.github.io/RuView/three.js/) — 五个逐步丰富的 ADR-097 演示：helpers、cinematic、GLTF skinned、FBX skinned，以及由 ESP32 CSI 驱动的实时 MediaPipe→Mixamo 重定向流。演示 04 和 05 需要本地 Mixamo `X Bot.fbx`（许可边界 — 未再分发）。


## 🤗 Hugging Face 上的预训练模型

预训练 CSI 权重位于 [`ruvnet/wifi-densepose-pretrained`](https://huggingface.co/ruvnet/wifi-densepose-pretrained) — 在 60K 帧 / 610K 对比三元组上训练 12.2M 步，**保留集时间三元组准确率 82.3%**（原始为 66.4%；较早的「100% 存在检测」数字是在单类别录制上测得，已撤回），4-bit 量化版本可放入 8 KB。该发布包含对比 **CSI 编码器**，可生成 128 维嵌入（M4 Pro 上 164,183 emb/s），以及 **存在检测头**。包含按节点的 LoRA 适配器，用于针对特定环境的微调。

```bash
# Download the model bundle
pip install huggingface_hub
huggingface-cli download ruvnet/wifi-densepose-pretrained --local-dir models/wifi-densepose-pretrained
```

**当前可用 vs. 待接线：**

| 使用者 | 使用格式 | 状态 |
|----------|-------------|--------|
| Python 训练 / 评估 / 嵌入提取 | `model.safetensors` | ✅ 可用 — 使用 `safetensors.torch.load_file` 加载 |
| 检查 / 重新导出 bundle | `model.rvf.jsonl`（逐行 JSON） | ✅ 可用 — 纯 JSONL |
| Sensing-server `--model <PATH>` 标志 | binary RVF（`RVFS` magic） | ⚠️ 加载器尚不接受 JSONL 容器 |

**已知差距：** HF 模型以 JSONL RVF 格式发布，但 `v2/crates/wifi-densepose-sensing-server/src/rvf_container.rs` 只解析二进制 RVF 分段格式。将 `--model` 指向 `model.rvf.jsonl` 当前会报错 `invalid magic at offset 0: expected 0x52564653, got 0x7974227B`，线上管道降级为空输出而非回退到启发式模式——因此在 JSONL 适配器就绪（或模型以二进制 RVF 重新发布）之前，**不要**使用 `--model` 运行在线 sensing-server。期间请使用 Python/训练端的权重。

**量化选项**（均在 HF 仓库中）：`model-q2.bin`（4 KB）· `model-q4.bin` ⭐ 推荐（8 KB）· `model-q8.bin`（16 KB）· `model.safetensors` 完整版（48 KB）

独立的 **17 关键点姿态估计模型** 现已发布，地址为 [`ruvnet/wifi-densepose-mmfi-pose`](https://huggingface.co/ruvnet/wifi-densepose-mmfi-pose)——在 MM-Fi 上达到 **82.69% torso-PCK@20**（单模型）/ **83.59%**（3 模型集成 + TTA），在匹配的 `random_split` 协议上超越了此前已发布的 SOTA MultiFormer（72.25%）和 CSI2Pose（68.41%）。详见下方 **结果与验证**。

### 结果与验证

| 内容 | 位置 | 数据 |
|------|------|------|
| **MM-Fi 姿态模型（SOTA）** | [`ruvnet/wifi-densepose-mmfi-pose`](https://huggingface.co/ruvnet/wifi-densepose-mmfi-pose) | 82.69% torso-PCK@20（单模型）· 83.59%（集成 + TTA）· 75K 参数微型变体 74.30% |
| **AetherArena 基准 Space** | [`ruvnet/aether-arena`](https://huggingface.co/spaces/ruvnet/aether-arena) | 自修正、可审计的 MM-Fi 排行榜 |
| **完整 MM-Fi 研究（真实情况）** | [`docs/benchmarks/mmfi-wifi-sensing-study.md`](docs/benchmarks/mmfi-wifi-sensing-study.md) | 姿态 + 动作；零样本跨受试者约 64%，+~30 秒室内校准 → 72.2% |
| **效率前沿** | [`docs/benchmarks/wifi-pose-efficiency-frontier.md`](docs/benchmarks/wifi-pose-efficiency-frontier.md) | 20 KB int4 边缘模型中超越 SOTA 的 WiFi 姿态 |
| **预训练编码器** | [`ruvnet/wifi-densepose-pretrained`](https://huggingface.co/ruvnet/wifi-densepose-pretrained) | 82.3% 留出时间三元组，8 KB int4 |
| **可复现验证（信任终止开关）** | [`archive/v1/data/proof/verify.py`](archive/v1/data/proof/verify.py) + [`expected_features.sha256`](archive/v1/data/proof/expected_features.sha256) | 单命令确定性管道回放（输出与已发布哈希的 SHA-256 比对） |
| **防基准作弊 ADR** | [ADR-168](docs/adr/ADR-168-benchmark-proof.md) | 数据的产生与验证方式 |
| **见证证明** | [`docs/WITNESS-LOG-028.md`](docs/WITNESS-LOG-028.md) | 33 行能力证明矩阵，每项声明附带证据 |

```bash
# Reproduce the deterministic pipeline proof yourself (must print VERDICT: PASS):
python archive/v1/data/proof/verify.py
```

跟踪于 [#509](https://github.com/ruvnet/RuView/issues/509);，参见 [ADR-079](docs/adr/ADR-079-camera-supervised-pose-finetune.md) 阶段 P7–P9 了解摄像头监督微调路径。

## 🧩 边缘模块目录

<details>
<summary><b>🧩 可在 Cognitum 设备上安装的 105 个边缘模块</b>——来自 <code>app-registry.json</code> v2.1.0（更新于 2026-05-13）的实时目录。浏览并安装：<a href="https://seed.cognitum.one/store">seed.cognitum.one/store</a> 或本地设备 <code>http://&lt;appliance&gt;:9000/cogs</code>。</summary>

每个模块都是一个约 400 KB 的小型签名二进制文件，在 Cognitum-V0 设备上与 WiFi-DensePose 感知栈并行运行。目录通过空中（OTA）更新——设备通过 <code>GET /api/v1/edge/registry</code>（[ADR-102](docs/adr/ADR-102-edge-module-registry.md)）获取目录，并在安装前用 Ed25519 签名（[ADR-100](docs/adr/ADR-100-cog-packaging-specification.md)）验证每个二进制文件。

### 🫀 健康——<sub>14 个模块</sub>

| ID | 功能 | 大小 | 难度 |
|----|------|-----:|:----:|
| `air-quality-index` | 使用 CO2 和颗粒物传感器追踪室内空气质量 | 8 KB | 简单 |
| `baby-cry` | 持续中频能量检测器，用于育儿室/婴儿监护。仅音频，无摄像头。 | 451 KB | 简单 |
| `breathing-sync` | 检测两人是否同步呼吸 | 10 KB | 困难 |
| `cardiac-arrhythmia` | 发现不规则心跳和异常心律 | 8 KB | 困难 |
| `cough-detect` | 声音瞬态 + 频谱咳嗽检测器，带 30 秒聚类聚合。呼吸道疾病的早期预警信号。 | 451 KB | 简单 |
| `dream-stage` | 追踪睡眠阶段——浅睡、深睡和做梦 | 14 KB | 困难 |
| `fall-detect` | 基于环境特征流（ESP32 运动/麦克风）的两级冲击 + 静止跌倒检测器。可选的 ruview 模式用于 CSI 姿态增强。 | 402 KB | 简单 |
| `gait-analysis` | 检测行走问题并评估跌倒风险 | 12 KB | 困难 |
| `health-monitor` | 无接触心率、呼吸、睡眠和跌倒警报 | 30 KB | 中 |
| `respiratory-distress` | 呼吸变得费力或危险时发出警报 | 10 KB | 困难 |
| `seizure-detect` | 识别癫痫发作并立即发出警报 | 10 KB | 困难 |
| `sleep-apnea` | 检测睡眠中呼吸停止 | 4 KB | 简单 |
| `snore-monitor` | 周期性低频能量追踪器，用于睡眠质量/呼吸暂停风险趋势分析。睡眠呼吸暂停模块的配套工具。 | 451 KB | 简单 |
| `vital-trend` | 追踪数周内的呼吸和心率趋势 | 6 KB | 中 |

### 🔒 安全——<sub>14 个模块</sub>

| ID | 功能 | 大小 | 难度 |
|----|------|-----:|:----:|
| `audit-logger` | 记录每项操作以符合合规要求——防篡改日志 | 8 KB | 简单 |
| `behavioral-profiler` | 学习正常行为并标记任何异常 | 12 KB | 困难 |
| `fleet-auth` | 跨所有 seed 管理设备证书和访问权限 | 12 KB | 中 |
| `glass-break` | 两级巨响 + 碎裂声检测器。区分玻璃破碎与普通脉冲噪声。 | 451 KB | 简单 |
| `gunshot-detect` | 饱和峰值 + 指数衰减声音检测器，带可选的 ruview CSI 运动下降增强。 | 451 KB | 简单 |
| `intrusion` | 未经授权者进入房间时发出警报 | 6 KB | 中 |
| `intrusion-detect-ml` | 使用机器学习检测网络攻击 | 14 KB | 困难 |
| `loitering` | 有人在某处逗留过久时发出警报 | 3 KB | 简单 |
| `network-firewall` | 按模块阻止未授权的网络访问 | 6 KB | 简单 |
| `panic-motion` | 检测突然的恐慌或异常移动 | 6 KB | 中 |
| `perimeter-breach` | 守护多个区域并显示进入方向 | 10 KB | 中 |
| `prompt-shield` | 阻止对 seed 的信号重放和注入攻击 | 10 KB | 中 |
| `tailgating` | 检测有人尾随持证者潜入 | 6 KB | 中 |
| `weapon-detect` | 检测人身上隐藏的金属物体 | 8 KB | 困难 |

### 🏢 建筑——<sub>11 个模块</sub>

| ID | 功能 | 大小 | 难度 |
|----|------|-----:|:----:|
| `beehive-monitor` | 声音蜂巢状态分类器。通过嗡嗡频带能量 + 混沌度 + 鸣叫自相关检测健康/混乱/失王/分蜂/盗蜂状态。 | 451 KB | 简单 |
| `elevator-count` | 统计电梯内人数 | 8 KB | 中 |
| `energy-audit` | 学习你的日程安排并减少能源浪费 | 6 KB | 中 |
| `frost-warning` | 通过温度趋势 + 露点差阈值提前 6 小时预测霜冻。适用于大田/果园农业。 | 451 KB | 简单 |
| `hvac-presence` | 在你到达时自动开启供暖和制冷 | 3 KB | 简单 |
| `lighting-zones` | 根据人员在房间间的移动自动开关灯 | 4 KB | 简单 |
| `meeting-room` | 显示会议室是否空闲或被占用 | 5 KB | 简单 |
| `occupancy-zones` | 穿墙统计每个房间的人数 | 8 KB | 中 |
| `predictive-maintenance` | 旋转设备的振动谐波分析仪。追踪 F1/2×F1/高阶/边带能量以评估退化严重程度。 | 451 KB | 简单 |
| `smoke-fire` | 多信号烟雾和火灾检测器。融合声音噼啪声、热漂移代理以及可选的 ruview CSI 烟羽特征。不能替代法规要求的烟雾报警器，未通过 UL 认证。 | 451 KB | 简单 |
| `water-leak` | 持续低幅嘶嘶声 + 周期性滴水声音检测器，带多分钟持续门控。两级：疑似→确认。 | 451 KB | 简单 |

USD 预算：$0/$3；剩余 $3 | 每月 $0/$3——总计：$3 | **Token 用量：** 2,350 / 8,000（29%）——无需自托管

### 🛍️ 零售 &mdash; <sub>7 modules</sub>

| ID | 功能 | 大小 | 难度 |
|----|--------------|-----:|:----------:|
| `customer-flow` | 统计各出入口的进出客流量 | 8 KB | Med |
| `dwell-heatmap` | 显示顾客停留时间最长的区域 | 6 KB | Med |
| `package-detect` | 用于门廊/装卸区包裹进出的持续 CSI 偏移检测器。需要 ESP32 CSI ruview 输入。 | 451 KB | Easy |
| `parking-occupancy` | 通过 ESP32 CSI 子载波幅度偏移实现分区停车占用检测。跟踪利用率与每小时周转率。需要 ruview。 | 451 KB | Easy |
| `queue-length` | 估算排队长度与等待时间 | 6 KB | Med |
| `shelf-engagement` | 检测顾客与商品的互动时刻 | 6 KB | Med |
| `table-turnover` | 跟踪餐厅桌位的空闲或占用状态 | 4 KB | Easy |

### 🏭 工业 &mdash; <sub>7 modules</sub>

| ID | 功能 | 大小 | 难度 |
|----|--------------|-----:|:----------:|
| `clean-room` | 在受控环境中强制执行人数上限 | 4 KB | Easy |
| `confined-space` | 监测狭窄空间内作业人员的安全状况 | 5 KB | Med |
| `forklift-proximity` | 叉车过于靠近工人时发出警告 | 10 KB | Hard |
| `livestock-monitor` | 监测动物的痛苦、逃逸或疾病迹象 | 6 KB | Med |
| `ppe-compliance` | Cog 组合层：当 ruview-densepose 在限制区域检测到人员存在，但缺少配套的 PPE 摄像头 cog 确认向量时发出警报。 | 387 KB | Easy |
| `slip-fall-zone` | 跌倒前风险检测器。当运动方差下降、溅水音频以及可选的谨慎步态 CSI 均表明滑倒风险升高时触发。 | 451 KB | Easy |
| `structural-vibration` | 检测建筑物或机器的危险振动 | 8 KB | Hard |

### 🔬 科研 &mdash; <sub>12 modules</sub>

| ID | 功能 | 大小 | 难度 |
|----|--------------|-----:|:----------:|
| `emotion-detect` | 从肢体语言与呼吸中解读压力与平静状态 | 10 KB | Hard |
| `energy-harvester` | 为离网 seed 部署优化太阳能与电池配置 | 6 KB | Med |
| `gesture-language` | 实时识别手语手势 | 12 KB | Hard |
| `ghost-hunter` | 发现无法解释的环境异常——仅供娱乐 | 10 KB | Hard |
| `happiness-score` | 根据运动与情绪信号估算身心健康状况 | 8 KB | Med |
| `hyperbolic-space` | 将数据映射到曲率空间以呈现树状结构 | 12 KB | Hard |
| `music-conductor` | 解读指挥者的手势以识别速度与力度变化 | 12 KB | Hard |
| `plant-growth` | 跟踪植物生长速率与昼夜周期 | 8 KB | Med |
| `rain-detect` | 检测降雨的开始、停止及强度 | 6 KB | Med |
| `ruview-densepose` | 基于 WiFi 的全身姿态跟踪——无需摄像头 | 50 KB | Hard |
| `sound-classifier` | 识别玻璃破碎、警报或婴儿啼哭等声音 | 16 KB | Hard |
| `time-crystal` | 实验性探索重复时间模式的对称性 | 12 KB | Hard |

### 🤖 AI &mdash; <sub>15 modules</sub>

| ID | 功能 | 大小 | 难度 |
|----|--------------|-----:|:----------:|
| `anomaly-attractor` | 学习正常模式并捕捉任何异常 | 10 KB | Hard |
| `cognitive-pipeline` | 面向 Pi Zero 2W 设备端认知事件的 FastGRNN 异常门控 + SmolLM2 稀疏 LLM 推理 | 320 KB | Hard |
| `dtw-gesture-learn` | 通过示例演示教授自定义手势 | 14 KB | Med |
| `ewc-lifelong` | 学习新知识而不遗忘旧知识 | 8 KB | Hard |
| `federated-learning` | 跨 seed 训练 AI，无需共享原始数据 | 18 KB | Hard |
| `goap-autonomy` | 自主规划并执行目标 | 14 KB | Hard |
| `meta-adapt` | 自动调优以获得最佳性能 | 10 KB | Hard |
| `micro-hnsw` | 快速的设备端指纹识别与分类 | 12 KB | Med |
| `neural-trader` | 从实时数据中发现市场模式与趋势 | 20 KB | Hard |
| `pagerank-influence` | 找出群体中最具影响力的人 | 12 KB | Med |
| `pattern-sequence` | 检测日常作息与重复习惯 | 10 KB | Med |
| `rag-local` | 使用 AI 搜索文档——在 seed 上运行 | 14 KB | Med |
| `spiking-tracker` | 受脑启发、可在微型硬件上运行的跟踪器 | 16 KB | Hard |
| `temporal-logic` | 对实时事件流强制执行安全规则 | 12 KB | Hard |
| `time-series-forecast` | 利用历史模式预测传感器趋势 | 12 KB | Med |

### 🐝 蜂群（Swarm） &mdash; <sub>11 modules</sub>

| ID | 功能 | 大小 | 难度 |
|----|--------------|-----:|:----------:|
| `swarm-backup-restore` | 自动将数据备份到其他 seed——一键恢复 | 8 KB | Easy |
| `swarm-cluster-monitor` | 所有 seed 健康与状态的实时仪表板 | 6 KB | Easy |
| `swarm-consensus` | seed 在共同进行关键变更前先投票 | 16 KB | Hard |
| `swarm-delta-sync` | seed 间自动同步数据——仅发送变更 | 8 KB | Med |
| `swarm-deploy` | 一次性在所有 seed 上安装或移除 cog | 10 KB | Med |
| `swarm-distributed-store` | 将数据分布到多个 seed 并统一搜索 | 14 KB | Hard |
| `swarm-edge-orchestrator` | 从单一位置管理所有 ESP32 传感器节点 | 14 KB | Hard |
| `swarm-load-balancer` | 将查询分散到多个 seed，避免单点过载 | 10 KB | Med |
| `swarm-mesh-manager` | 发现、连接并监测网络上的所有 seed | 12 KB | Easy |
| `swarm-mqtt-bridge` | 通过 MQTT 消息在 seed 间共享事件 | 6 KB | Easy |
| `swarm-witness-federation` | 在 seed 间共享防篡改审计追踪 | 12 KB | Hard |

### 📡 信号 &mdash; <sub>6 modules</sub>

| ID | 功能 | 大小 | 难度 |
|----|--------------|-----:|:----------:|
| `coherence-gate` | 过滤噪声信号，保留干净信号 | 8 KB | Med |
| `flash-attention` | 将感知聚焦于特定区域以提高精度 | 12 KB | Med |
| `optimal-transport` | 通过形状感知信号比较测量运动 | 12 KB | Hard |
| `person-matching` | 区分同一房间内的多个人 | 18 KB | Hard |
| `sparse-recovery` | 从部分读数中恢复缺失的信号数据 | 16 KB | Hard |
| `temporal-compress` | 压缩旧数据以节省内存且不损失语义 | 14 KB | Med |

### 🌐 网络 &mdash; <sub>1 modules</sub>

| ID | 功能 | 大小 | 难度 |
|----|--------------|-----:|:----------:|
| `tailscale` | 通过私有 WireGuard 网状网络（Tailscale）从任意位置访问 seed。用户空间模式——无需 root。 | 700 KB | Med |

### 🛠️ 开发者 &mdash; <sub>7 modules</sub>

| ID | 功能 | 大小 | 难度 |
|----|--------------|-----:|:----------:|
| `adversarial` | 检测被篡改或伪造的传感器信号 | 4 KB | Easy |
| `coherence` | 监测多通道信号质量 | 4 KB | Easy |
| `gesture` | cog 的核心手势识别构建块 | 6 KB | Med |
| `interference-search` | 并行搜索多种可能性以快速得出答案 | 14 KB | Hard |
| `psycho-symbolic` | 以多种风格对知识图谱进行推理 | 16 KB | Hard |
| `quantum-coherence` | 用于高级信号状态的量子启发模型 | 16 KB | Hard |
| `self-healing-mesh` | 即使节点掉线也能保持传感器网状网络运行 | 14 KB | Hard |

> ℹ️ 构建你自己的 cog：打包规范见 [ADR-100](docs/adr/ADR-100-cog-packaging-specification.md)。本仓库收录到目录中的首个 cog 位于 [v2/crates/cog-pose-estimation/](v2/crates/cog-pose-estimation/)（17 关键点 WiFi 姿态，[ADR-101](docs/adr/ADR-101-pose-estimation-cog.md)）。

</details>


## 🔬 工作原理

WiFi 路由器向每个房间灌满无线电波。当人移动——甚至呼吸——这些波的散射方式就会不同。WiFi DensePose 读取该散射模式并重建发生了什么：

```
WiFi Router → radio waves pass through room → hit human body → scatter
    ↓
ESP32 mesh (4-6 nodes) captures CSI on channels 1/6/11 via TDM protocol
    ↓
Multi-Band Fusion: 3 channels × 56 subcarriers = 168 virtual subcarriers per link
    ↓
Multistatic Fusion: N×(N-1) links → attention-weighted cross-viewpoint embedding
    ↓
Coherence Gate: accept/reject measurements → stable for days without tuning
    ↓
Signal Processing: Hampel, SpotFi, Fresnel, BVP, spectrogram → clean features
    ↓
AI Backbone (RuVector): attention, graph algorithms, compression, field model
    ↓
Signal-Line Protocol (CRV): 6-stage gestalt → sensory → topology → coherence → search → model
    ↓
Neural Network: processed signals → 17 body keypoints + vital signs + room model
    ↓
Output: real-time pose, breathing, heart rate, room fingerprint, drift alerts
```

无需训练摄像头 —— [自学习系统 (ADR-024)](docs/adr/ADR-024-contrastive-csi-embedding-model.md) 仅从原始 WiFi 数据即可完成引导。[MERIDIAN (ADR-027)](docs/adr/ADR-027-cross-environment-domain-generalization.md) 确保模型在任意房间都能工作，而不仅限于训练所在的房间。

---

## 🏢 用例与应用场景

WiFi 感知可在任何有 WiFi 的地方工作。大多数情况下无需新增硬件 —— 只需在现有接入点上运行软件，或加装一个 $8 的 ESP32 模块即可。由于不使用摄像头，部署方案从设计上即规避了隐私法规（GDPR 视频、HIPAA 成像）的约束。

**扩展能力：** 每个 AP 可区分约 3-5 人（56 个子载波）。多 AP 可线性倍增 —— 4 个 AP 的零售网格可覆盖约 15-20 人。无硬性软件限制；实际上限取决于信号物理特性。

| | WiFi 感知为何胜出 | 传统替代方案 |
|---|----------------------|----------------------|
| 🔒 | **无视频，不受 GDPR/HIPAA 成像法规约束** | 摄像头需知情同意、标识牌、数据留存政策 |
| 🧱 | **可穿透墙壁、货架、障碍物** | 摄像头需每间房间有视线可达 |
| 🌙 | **完全黑暗环境也能工作** | 摄像头需红外或可见光照明 |
| 💰 | **每个区域 $0-$8**（现有 WiFi 或 ESP32） | 摄像头系统：每个区域 $200-$2,000 |
| 🔌 | **WiFi 已无处不在** | PIR/雷达传感器每间房间均需重新布线 |

<details>
<summary><strong>🏥 日常场景</strong> —— 医疗健康、零售、办公、酒店（普通商用 WiFi）</summary>

| 用例 | 功能描述 | 硬件 | 关键指标 | 边缘模块 |
|----------|-------------|----------|------------|-------------|
| **养老照护/辅助生活** | 跌倒检测、夜间活动监测、睡眠呼吸频率 —— 无需穿戴设备配合 | 每个房间 1 个 ESP32-S3（$8） | 跌倒告警 <2s | [睡眠呼吸暂停](docs/edge-modules/medical.md)、[步态分析](docs/edge-modules/medical.md) |
| **医院患者监测** | 对非重症床位持续监测呼吸与心率，无需有线传感器；异常时护士告警 | 每个病区 1-2 个 AP | 呼吸：6-30 BPM | [呼吸窘迫](docs/edge-modules/medical.md)、[心律失常](docs/edge-modules/medical.md) |
| **急诊分诊** | 自动统计就诊人数与候诊时间估算；在候诊区检测患者异常状态（呼吸异常） | 现有医院 WiFi | 人数统计准确率 >95% | [排队长度](docs/edge-modules/retail.md)、[恐慌动作](docs/edge-modules/security.md) |
| **零售客流与动线** | 实时客流量、各区域停留时长、排队长度 —— 无摄像头、无需用户选择加入、符合 GDPR | 现有店内 WiFi + 1 个 ESP32 | 停留分辨率 ~1m | [顾客动线](docs/edge-modules/retail.md)、[停留热力图](docs/edge-modules/retail.md) |
| **办公空间利用** | 哪些工位/会议室实际被占用、会议室爽约、基于实际人员存在优化 HVAC | 现有企业 WiFi | 存在检测延迟 <1s | [会议室](docs/edge-modules/building.md)、[HVAC 存在感知](docs/edge-modules/building.md) |
| **酒店与服务业** | 房间占用无需门磁传感器、迷你吧/卫生间使用模式、空房节能 | 现有酒店 WiFi | HVAC 节能 15-30% | [能耗审计](docs/edge-modules/building.md)、[照明分区](docs/edge-modules/building.md) |
| **餐厅与餐饮服务** | 翻台追踪、后厨人员存在检测、卫生间占用显示 —— 用餐区无摄像头 | 现有 WiFi | 排队等待 ±30s | [翻台追踪](docs/edge-modules/retail.md)、[排队长度](docs/edge-modules/retail.md) |
| **停车场** | 摄像头存在盲区的楼梯间和电梯间行人存在检测；有人逗留时发出安全告警 | 现有 WiFi | 可穿透混凝土墙壁 | [逗留检测](docs/edge-modules/security.md)、[电梯人数](docs/edge-modules/building.md) |

</details>

<details>
<summary><strong>🏟️ 专业场景</strong> —— 活动赛事、健身、教育、市政（支持 CSI 的硬件）</summary>

| 用例 | 功能描述 | 硬件 | 关键指标 | 边缘模块 |
|----------|-------------|----------|------------|-------------|
| **智能家居自动化** | 房间级存在感知触发（灯光、HVAC、音乐），可穿墙工作 —— 无死角，无运动传感器超时问题 | 2-3 个 ESP32-S3 节点（$24） | 穿墙范围 ~5m | [HVAC 存在感知](docs/edge-modules/building.md)、[照明分区](docs/edge-modules/building.md) |
| **健身与运动** | 动作计数、姿态矫正、运动中呼吸节奏 —— 无需穿戴设备、更衣室无摄像头 | 3+ 个 ESP32-S3 网格 | 姿态：17 个关键点 | [呼吸同步](docs/edge-modules/exotic.md)、[步态分析](docs/edge-modules/medical.md) |
| **托育与学校** | 午睡呼吸监测、操场人数统计、限制区域告警 —— 对未成年人保护隐私安全 | 每个区域 2-4 个 ESP32-S3 | 呼吸：±1 BPM | [睡眠呼吸暂停](docs/edge-modules/medical.md)、[周界入侵](docs/edge-modules/security.md) |
| **活动场馆与演唱会** | 人群密度分布、通过呼吸压缩检测踩踏风险、紧急疏散人流追踪 | 多 AP 网格（4-8 个 AP） | 每平方米密度 | [顾客动线](docs/edge-modules/retail.md)、[恐慌动作](docs/edge-modules/security.md) |
| **体育场与竞技场** | 分区占用用于动态定价、特许经营人员配置、紧急疏散人流建模 | 企业级 AP 网格 | 每个 AP 网格 15-20 人 | [停留热力图](docs/edge-modules/retail.md)、[排队长度](docs/edge-modules/retail.md) |
| **宗教场所** | 无需人脸识别的参与人数统计 —— 注重隐私的会众、多房间园区追踪 | 现有 WiFi | 区域级精度 | [电梯人数](docs/edge-modules/building.md)、[能耗审计](docs/edge-modules/building.md) |
| **仓储与物流** | 工人安全区域、叉车接近告警、危险区域人员占用 —— 可穿透货架和托盘 | 工业 AP 网格 | 告警延迟 <500ms | [叉车接近](docs/edge-modules/industrial.md)、[受限空间](docs/edge-modules/industrial.md) |
| **市政基础设施** | 公共卫生间占用（无法使用摄像头）、地铁站台拥挤、应急避难人数统计 | 市政 WiFi + ESP32 | 实时人数统计 | [顾客动线](docs/edge-modules/retail.md)、[逗留检测](docs/edge-modules/security.md) |
| **博物馆与美术馆** | 参观者动线热力图、展品前停留时长、人群瓶颈告警 —— 艺术品旁无摄像头（闪光/盗窃风险） | 现有 WiFi | 区域停留 ±5s | [停留热力图](docs/edge-modules/retail.md)、[展架互动](docs/edge-modules/retail.md) |

</details>

<details>
<summary><strong>🤖 机器人与工业</strong> —— 自主系统、制造业、仿人机器人空间感知</summary>

WiFi 感知为机器人和自主系统提供了一层空间感知能力，可在 LIDAR 和摄像头失效的环境中工作 —— 穿透灰尘、烟雾、雾气及绕过角落。CSI 信号场如同一种"第六感"，用于检测环境中的人类存在，无需视线可达。

| 用例 | 功能描述 | 硬件 | 关键指标 | 边缘模块 |
|----------|-------------|----------|------------|-------------|
| **协作机器人安全区域** | 检测协作机器人附近的人类存在 —— 在接触前自动减速或停止，即使有障碍物遮挡 | 每个单元 2-3 个 ESP32-S3 | 存在检测延迟 <100ms | [叉车接近](docs/edge-modules/industrial.md)、[周界入侵](docs/edge-modules/security.md) |
| **仓储 AMR 导航** | 自主移动机器人感知盲区拐角、货架后方的人类 —— 无 LIDAR 遮挡问题 | 沿通道部署 ESP32 网格 | 穿透货架检测 | [叉车接近](docs/edge-modules/industrial.md)、[逗留检测](docs/edge-modules/security.md) |
| **仿人机器人/人形机器人空间感知** | 为社交机器人提供环境人体姿态感知 —— 检测手势、接近方向和个人空间，无需摄像头始终开启 | 板载 ESP32-S3 模块 | 17 个关键点姿态 | [手势语言](docs/edge-modules/exotic.md)、[情绪检测](docs/edge-modules/exotic.md) |
| **生产线监测** | 各工位工人存在检测、人体工学姿态告警、班次合规人数统计 —— 可穿透设备工作 | 每个区域工业 AP | 姿态 + 呼吸 | [受限空间](docs/edge-modules/industrial.md)、[步态分析](docs/edge-modules/medical.md) |
| **建筑工地安全** | 重型机械周围禁区执行、脚手架跌倒检测、人员人数统计 | 加固型 ESP32 网格 | 告警 <2s，可穿透灰尘 | [恐慌动作](docs/edge-modules/security.md)、[结构振动](docs/edge-modules/industrial.md) |
| **农业机器人** | 在多尘/多雾的田间条件下检测自主收割机附近农场工人，摄像头在此类条件下不可靠 | 防风雨 ESP32 节点 | 开放场地范围 ~10m | [叉车接近](docs/edge-modules/industrial.md)、[降雨检测](docs/edge-modules/exotic.md) |
| **无人机降落区域** | 确认降落区域无人员 —— WiFi 感知可在雨水、灰尘和弱光条件下工作，而朝下摄像头会失效 | 地面 ESP32 节点 | 人员存在：准确率 >95% | [周界入侵](docs/edge-modules/security.md)、[尾随检测](docs/edge-modules/security.md) |
| **洁净室监测** | 人员追踪无需摄像头（摄像头风扇会产生颗粒污染风险）—— 通过姿态检测防护服合规 | 现有洁净室 WiFi | 无颗粒物排放 | [洁净室](docs/edge-modules/industrial.md)、[牲畜监测](docs/edge-modules/industrial.md) |

</details>

<details>
<summary><strong>🔥 极端场景</strong> — 穿墙、灾难、安防、地下</summary>

这些场景利用了 WiFi 穿透固体材料（混凝土、碎石、泥土）的能力——这是任何光学或红外传感器都无法做到的。WiFi-Mat 灾难模块（ADR-001）专为此级别设计。

| 应用场景 | 功能 | 硬件 | 关键指标 | 边缘模块 |
|----------|------|------|----------|----------|
| **搜索与救援（WiFi-Mat）** | 通过呼吸信号检测废墟下的幸存者，START 检伤分类颜色识别，3D 定位 | 便携式 ESP32 网格 + 笔记本电脑 | 穿透 30cm 混凝土 | [呼吸窘迫](docs/edge-modules/medical.md)、[癫痫检测](docs/edge-modules/medical.md) |
| **消防** | 进入前通过烟雾和墙壁定位被困人员；呼吸检测远程确认生命迹象 | 车载便携式网格 | 零可见度环境下工作 | [睡眠呼吸暂停](docs/edge-modules/medical.md)、[恐慌运动](docs/edge-modules/security.md) |
| **监狱与安全设施** | 牢房人员核实、异常状态检测（生命体征异常）、周界感知——无摄像头盲区 | 专用 AP 基础设施 | 24/7 生命体征监测 | [心律失常](docs/edge-modules/medical.md)、[徘徊检测](docs/edge-modules/security.md) |
| **军事/战术** | 穿墙人员检测、房间清场确认、远距离人质生命体征监测 | 定向 WiFi + 自定义固件 | 距离：穿墙 5m | [周界入侵](docs/edge-modules/security.md)、[武器检测](docs/edge-modules/security.md) |
| **边境与周界安防** | 检测隧道内、围栏后、车辆中的人员存在——无源感知，无需主动照明暴露位置 | 隐蔽式 ESP32 网格 | 无源/隐蔽 | [周界入侵](docs/edge-modules/security.md)、[尾随检测](docs/edge-modules/security.md) |
| **矿业与地下工程** | GPS/摄像头失效的隧道中工作人员定位、坍塌后呼吸检测、安全点人员清点 | 加固型 ESP32 网格 | 穿透岩石/泥土 | [密闭空间](docs/edge-modules/industrial.md)、[呼吸窘迫](docs/edge-modules/medical.md) |
| **海事与海军** | 甲板下人员追踪（穿透钢制舱壁，有限距离，需调校）、人员落水检测 | 船舶 WiFi + ESP32 | 穿透 1-2 层舱壁 | [结构振动](docs/edge-modules/industrial.md)、[恐慌运动](docs/edge-modules/security.md) |
| **野生动物研究** | 圈养场或巢穴内非侵入式动物活动监测——无光污染、无视觉干扰 | 防风雨 ESP32 节点 | 零光辐射 | [牲畜监测](docs/edge-modules/industrial.md)、[梦阶段](docs/edge-modules/exotic.md) |

</details>


---

<details>
<summary><strong>🧠 自学习 WiFi AI（ADR-024）</strong> — 自适应识别、自我优化与智能异常检测</summary>

每一个穿过房间的 WiFi 信号都会为该空间留下一枚独特的指纹。WiFi-DensePose 已经能够读取这些指纹来追踪人员，但在此之前，每次读取完成后都会丢弃内部的"理解"。自学习 WiFi AI 则捕获并保存这种理解，将其转化为紧凑、可复用的向量——并针对每个新环境持续自我优化。

**通俗解释：**
- 将任何 WiFi 信号转化为一个 128 位的数字"指纹"，唯一描述房间内正在发生的情况
- 完全通过原始 WiFi 数据自主学习——无需摄像头、无需标注、无需人工监督
- 仅使用 WiFi 即可识别房间、检测入侵者、分类活动（人名身份识别属于实验性、受数据制约的研究能力——见下文，并非已发布功能）
- 在 8 美元的 ESP32 芯片上运行（整个模型仅占用 55 KB 内存）
- 一次计算同时输出人体姿态追踪和环境指纹

**核心能力**

| 能力 | 工作原理 | 为何重要 |
|------|----------|----------|
| **自监督学习** | 模型观察 WiFi 信号，自学"相似"和"不同"的形态，无需任何人工标注数据 | 随处部署——只需插入 WiFi 传感器，等待 10 分钟 |
| **房间识别** | 每个房间产生独特的 WiFi 指纹模式 | 无需 GPS 或信标即可知道某人在哪个房间 |
| **异常检测** | 意外的人员或事件会产生与之前所见都不匹配的指纹 | 自动入侵和跌倒检测，作为免费副产品 |
| **人员重识别** *（实验性，研究阶段）* | 真实的逐通道相似度匹配器（灵魂签名 §3.6，``wifi-densepose-bfld``）；**实测**结果：仅凭 WiFi 心脏+呼吸通道无法区分两个人（差距约 0.0005） | 诚实的研究能力——**不声称识别具体身份**，受数据制约，需 enrollment 和决定性的 AETHER/体共振通道。详见 [#1021](https://github.com/ruvnet/RuView/issues/1021)) |
| **环境自适应** | MicroLoRA 适配器（每个房间 1,792 个参数）为每个新空间微调模型 | 用极少数据适应新房间——比从头训练少 93% |
| **记忆保持** | EWC++ 正则化记住预训练阶段学到的知识 | 切换到新任务不会擦除先前知识 |
| **难例挖掘** | 训练聚焦于最令人困惑的样本，加速学习 | 相同训练数据下获得更高准确率 |

**架构**

```
```
WiFi Signal [56 channels] → Transformer + Graph Neural Network
                                  ├→ 128-dim environment fingerprint (for search + identification)
                                  └→ 17-joint body pose (for human tracking)
```
```

**快速开始**

```
```bash
# Step 1: Learn from raw WiFi data (no labels needed)
cargo run -p wifi-densepose-sensing-server -- --pretrain --dataset data/csi/ --pretrain-epochs 50

# Step 2: Fine-tune with pose labels for full capability
cargo run -p wifi-densepose-sensing-server -- --train --dataset data/mmfi/ --epochs 100 --save-rvf model.rvf

# Step 3: Use the model — extract fingerprints from live WiFi
cargo run -p wifi-densepose-sensing-server -- --model model.rvf --embed

# Step 4: Search — find similar environments or detect anomalies
cargo run -p wifi-densepose-sensing-server -- --model model.rvf --build-index env
```
```

**训练模式**

| 模式 | 所需数据 | 所得结果 |
|------|----------|----------|
| 自监督 | 仅需原始 WiFi 数据 | 理解 WiFi 信号结构的模型 |
| 监督学习 | WiFi 数据 + 人体姿态标签 | 完整姿态追踪 + 环境指纹 |
| 跨模态 | WiFi 数据 + 摄像头画面 | 与视觉理解对齐的指纹 |

**指纹索引类型**

| 索引 | 存储内容 | 实际用途 |
|------|----------|----------|
| ``env_fingerprint`` | 房间平均指纹 | "这是厨房还是卧室？" |
| ``activity_pattern`` | 活动边界 | "有人在做饭、睡觉还是锻炼？" |
| ``temporal_baseline`` | 正常状态 | "这个房间刚刚发生了异常情况" |
| ``person_track`` | 个体运动特征 | "A 刚刚进入了客厅" |

**模型大小**

| 组件 | 参数数量 | 内存占用（ESP32 上） |
|------|----------|----------------------|
| Transformer 骨干网络 | ~28,000 | 28 KB |
| 嵌入投影头 | ~25,000 | 25 KB |
| 每房间 MicroLoRA 适配器 | ~1,800 | 2 KB |
| **合计** | **~55,000** | **55 KB**（可用 520 KB） |

自学习系统构建在 [AI 骨干网络（RuVector）](#ai-backbone-ruvector) 信号处理层之上——注意力机制、图算法和压缩——并在其上层添加对比学习。

完整架构细节请参见 [``docs/adr/ADR-024-contrastive-csi-embedding-model.md``](docs/adr/ADR-024-contrastive-csi-embedding-model.md)。

</details>

## 🧩 Claude Code 与 Codex 插件

RuView 提供了 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 插件（及 Codex 提示词镜像），将整个工作流——包括上手引导、ESP32 设置、配置、感知应用、模型训练、高级多站感知、CLI/API/WASM、毫米波雷达和见证验证——封装为 9 项技能、7 条 `/ruview-*` 命令和 3 个智能体。它位于 [`plugins/ruview/`](plugins/ruview/README.md)；市场清单位于仓库根目录下的 [`.claude-plugin/marketplace.json`](.claude-plugin/marketplace.json)。

```bash
# In Claude Code — add this repo as a plugin marketplace, then install:
/plugin marketplace add ruvnet/RuView
/plugin install ruview@ruview

# Or try it for one session without installing (from a local clone of the repo):
claude --plugin-dir ./plugins/ruview

# Then, in Claude Code:
#   /ruview-start      → onboarding (Docker demo / repo build / live ESP32)
#   /ruview-flash      → build + flash ESP32 firmware
#   /ruview-provision  → provision WiFi creds, sink IP, channel/MAC, mesh slots
#   /ruview-app        → run a sensing application (presence / vitals / pose / sleep / MAT / point cloud)
#   /ruview-train      → train / evaluate / publish a model (incl. GPU on GCloud)
#   /ruview-advanced   → multistatic / tomography / cross-viewpoint / mesh-security
#   /ruview-verify     → tests + deterministic proof + witness bundle
```

**Codex（OpenAI CLI）：** `cp plugins/ruview/codex/prompts/*.md ~/.codex/prompts/` —— 七条 `/ruview-*` 命令被镜像为 Codex 提示词；[`plugins/ruview/codex/AGENTS.md`](plugins/ruview/codex/AGENTS.md) 承载了项目规则。参见 [`plugins/ruview/codex/README.md`](plugins/ruview/codex/README.md)。

验证插件结构：`bash plugins/ruview/scripts/smoke.sh`。完整详情：[`plugins/ruview/README.md`](plugins/ruview/README.md)。

**便携式工具集 —— `npx @ruvnet/ruview`：** 一种更轻量、主机可移植的插件伴侣工具，通过 [MetaHarness](https://www.npmjs.com/package/metaharness) 生成，并依据 [ADR-182](docs/adr/ADR-182-npx-ruview-harness-via-metaharness.md) 加固。它**无需克隆本仓库**即可运行，且支持更多主机（Claude Code、Codex、Copilot、opencode 等），通过 MCP 服务器暴露 RuView 操作工具（`onboard`、`verify`、`node_monitor`、`calibrate`、`node_flash`），此外还内置了项目的 **「实测值 vs 声称值」诚实护栏**（`ruview.claim_check` 会标记未标注或已撤回的"100%"准确率声明）。v0.1：上手/验证/声明检查路径已测试通过（17/17，`verify.py` → 通过）；硬件工具为故障关闭包装器。运行 `npx @ruvnet/ruview` 上手，或 `npx @ruvnet/ruview claim-check --text "…"`。源码：[`harness/ruview/`](harness/ruview/README.md)。

---

## 📖 文档

| 文档 | 说明 |
|----------|-------------|
| [用户指南](docs/user-guide.md) | 分步指南：安装、首次运行、API 使用、硬件设置、训练 |
| [构建指南](docs/build-guide.md) | 从源码构建（Rust 和 Python） |
| [**Home Assistant + Matter 集成**](docs/integrations/home-assistant.md) | **可与 Home Assistant 配合使用**（通过 MQTT 自动发现）+ **可与 Matter 配合使用**（Apple Home / Google Home / Alexa / SmartThings）—— 完整实体目录、3 个入门蓝图、Lovelace 面板、隐私模式、阈值调优（[ADR-115](docs/adr/ADR-115-home-assistant-integration.md)）。 |
| [**BFLD —— 用于检测的波束赋形反馈层**](v2/crates/wifi-densepose-bfld/README.md) | 新的隐私保护型 WiFi 感知层，可测量并从结构上防止 802.11ac/ax 波束赋形反馈信息导致身份泄露。三个类型强制不变量（原始 BFI 永不离开节点，身份嵌入仅驻留于内存，通过基于站点的 BLAKE3 密钥哈希和每日轮换从密码学上杜绝跨站点关联）。提供完整操作接口（`BfldPipeline`、`BfldPipelineHandle`、Soul Signature §3.6 每通道匹配器 `EnrolledMatcher`/`SoulMatchOracle` —— 实验性；命名身份受数据门控，在纯 WiFi 通道上**实测**为不可分离）、MQTT 主题路由器 + HA-DISCO + 可用性 + LWT、3 个操作员 HA 蓝图、两个可运行示例、eclipse-mosquitto:2 CI 服务容器。327+ 测试。[ADR-118](docs/adr/ADR-118-bfld-beamforming-feedback-layer-for-detection.md) 总括 + 子 ADR [119](docs/adr/ADR-119-bfld-frame-format-and-wire-protocol.md)/[120](docs/adr/ADR-120-bfld-privacy-class-and-hash-rotation.md)/[121](docs/adr/ADR-121-bfld-identity-risk-scoring.md)/[122](docs/adr/ADR-122-bfld-ruview-ha-matter-exposure.md)/[123](docs/adr/ADR-123-bfld-capture-path-nexmon-and-esp32.md)。研究报告：[`docs/research/BFLD/`](docs/research/BFLD/)（11 个文件，13,544 词）。 |
| [**SENSE-BRIDGE —— rvagent MCP 服务器**](tools/ruview-mcp/README.md) | 双传输层 MCP 服务器（`@ruvnet/rvagent`），将 RuView 感知栈桥接到 AI 智能体（Claude Code、Cursor、ruflo 群体）。已接入 6 个工具：`ruview.presence.now`、`ruview.vitals.get_{breathing,heart_rate,all}`、`ruview.bfld.last_scan`、`ruview.bfld.subscribe`。stdio + Streamable HTTP（`POST /mcp`、来源验证、Bearer Token 认证、`127.0.0.1` 绑定）。完整 20 个工具的 Zod Schema 桶 + 5 个 RUVIEW-POLICY 治理工具。93 个测试。[ADR-124](docs/adr/ADR-124-rvagent-mcp-ruvector-npm-integration.md)。试用：`npx @ruvnet/rvagent stdio`。 |
| [语义基元 —— 精确率/召回率](docs/integrations/semantic-primitives-metrics.md) | 在留出配对采集集上按基元计算的 F1：someone-sleeping、possible-distress、room-active、elderly-inactivity-anomaly、meeting、bathroom、fall-risk、bed-exit、no-movement、multi-room。 |
| [Claude Code / Codex 插件](plugins/ruview/README.md) | `ruview` 插件 + 市场 —— 技能、`/ruview-*` 命令、智能体和 Codex 提示词镜像 |
| [便携式工具集 —— `npx @ruvnet/ruview`](harness/ruview/README.md) | 经 MetaHarness 生成、主机可移植的 RuView 操作工具集 —— `ruview.*` 个 MCP 工具 + 内置的「实测值 vs 声称值」诚实护栏（[ADR-182](docs/adr/ADR-182-npx-ruview-harness-via-metaharness.md)）。仓库内插件的轻量多主机伴侣。 |
| [架构决策](docs/adr/README.md) | 182 个 ADR —— 每项技术选择的原因，按领域组织（硬件、信号处理、机器学习、平台、基础设施） |
| [领域模型](docs/ddd/README.md) | 8 个 DDD 模型（RuvSense、信号处理、训练流水线、硬件平台、感知服务器、WiFi-Mat、CHCI、rvCSI）—— 限界上下文、聚合、领域事件和统一语言 |
| [rvCSI —— 边缘 RF 感知运行时](https://github.com/ruvnet/rvcsi) | Rust 优先 / TypeScript 可访问 / 硬件抽象的 CSI 运行时：多源摄入（包括来自 **Raspberry Pi 5** / Pi 4 / Pi 3B+ 的实际 nexmon_csi `.pcap` —— CYW43455 / BCM43455c0）→ 验证 → DSP → 类型化事件 → RuVector RF 内存（[ADR-095](docs/adr/ADR-095-rvcsi-edge-rf-sensing-platform.md)、[ADR-096](docs/adr/ADR-096-rvcsi-ffi-crate-layout.md)、[领域模型](docs/ddd/rvcsi-domain-model.md)）。现为独立仓库 —— [`ruvnet/rvcsi`](https://github.com/ruvnet/rvcsi) —— 在本仓库中通过 `vendor/rvcsi` 进行 vendor；crates.io 上有 9 个 `rvcsi-*` crate，npm 上有 `@ruv/rvcsi`，另附 Claude Code 插件。 |
| [桌面应用](v2/crates/wifi-densepose-desktop/README.md) | **开发中** —— 基于 Tauri v2 的桌面应用，用于节点管理、OTA 更新、WASM 部署和 Mesh 可视化 |
| `ruview-swarm` | 无人机集群控制系统（ADR-148）—— 分层 Mesh 拓扑、Raft 共识、MARL、CSI 感知载荷、MAVLink/PX4/ArduPilot 兼容性、Ruflo AI 智能体集成 |
| [医疗示例](examples/medical/README.md) | 通过 60 GHz 毫米波雷达实现非接触式血压、心率、呼吸率测量 —— 硬件仅需 15 美元，无需可穿戴设备 |
| [扩展文档](docs/readme-details.md) | 最新新增、核心功能、安装、快速入门、信号处理、训练、CLI、测试、部署和更新日志 |

---

## 🚧 Beta 软件

> **Beta 软件** —— 正在积极开发中。API 和固件可能发生变更。已知限制：
> - ESP32-C3 和原始 ESP32 不受支持（单核，不足以处理 CSI DSP）
> - 单个 ESP32 部署的空间分辨率有限 —— 请使用 2 个以上节点，或添加 [Cognitum Seed](https://cognitum.one) 以获得最佳效果
> - 无摄像头的姿态估计精度有限（PCK@20 ≈ 2.5%，基于代理标签）—— [摄像头真值训练](docs/adr/ADR-079-camera-ground-truth-training.md)的目标是 **PCK@20 达到 35% 以上**；该流水线已实现，但数据采集和评估阶段（ADR-079 P7–P9）尚待完成。
>
> 欢迎通过 [Issues](https://github.com/ruvnet/RuView/issues). 提交贡献和错误报告。
USD 预算：$0/$3；本月 OpenAI API 评估额度剩余 $3。

## 📄 许可证

MIT 许可证 — 详见 [LICENSE](LICENSE)。

## 🤝 创作者联盟计划

**面向 TikTok · Instagram · YouTube 创作者** — 您推荐的每笔 **Cognitum 销售**均可获得 **25% 佣金**。您已经在制作的 RuFlo、RuView 和 RuVector 视频已获得数百万播放量；现在，通过这些视频带来的订单获得报酬。点击追踪即刻生效，佣金在快速人工审核后激活（通常在 24 小时内）。

[立即申请 → cognitum.one/affiliate](https://cognitum.one/affiliate))

## 📞 支持

[GitHub Issues](https://github.com/ruvnet/RuView/issues)) | [讨论区](https://github.com/ruvnet/RuView/discussions)) | [PyPI](https://pypi.org/project/wifi-densepose/))

---

**WiFi DensePose** — 通过 WiFi 信号进行隐私保护的人体姿态估计。
预算：$0/$3；剩余 $3。

**WeHub** — 我们编写工具，助您构建未来。⚡️