RuView（WiFi DensePose）技术全指南：WiFi CSI 驱动的无摄像头人体感知、生命体征与边缘传感

2026-09-08 16:32:49作者：秋阔奎Evelyn

π RuView turns commodity WiFi signals into real-time spatial intelligence, vital sign monitoring, and presence detection — all without a single pixel of video.

项目地址：https://gitcode.com/GitHub_Trending/wi/RuView

本文是 RuView（WiFi DensePose）仓库的完整技术参考，核心素材来自仓库扩展文档 docs/readme-details.md（原 README 中剥离出的详细章节），并辅以源码、固件、脚本与配置文件交叉印证。RuView 将日常 WiFi 信号转化为实时空间智能：无需任何摄像头画面，即可穿透墙壁感知人体姿态、呼吸与心跳，并可部署在 ESP32 这类廉价边缘设备上。读完本文，你将掌握：如何用 Docker / 源码 / pip 一条龙装好系统，如何 3 条命令跑通 Python API、REST 与 WebSocket，如何烧录并配网 ESP32-S3 传感器节点，如何下载开箱即用的预训练模型，以及 CLI、RVF 模型容器、17 个传感应用与测试验证的完整用法。

一、项目概览：能做什么

RuView 的核心主张是"仅用房间里已有的 WiFi 信号看人"。原始信道状态信息（CSI）被实时解析为三类输出：姿态（17 COCO 关键点）、生命体征（呼吸 6–30 BPM、心率 40–120 BPM）与运动量。

仓库扩展文档将其能力整理为三层能力模型：

层	能力	说明
🔒 传感	隐私优先	只用 WiFi 追踪姿态，不存任何视频帧
💓 传感	生命体征	无穿戴测量呼吸（6–30 次/分）与心率（40–120 bpm）
👥 传感	多人	多目标独立姿态+体征；56 子载波单 AP 物理上限约 3–5 人，多 AP 可扩展（ADR-029）
🧱 传感	穿墙	WiFi 穿透墙体、家具与废墟（WiFi-Mat）
📡 传感	多静态网格	4–6 个低成本节点组成 360° 覆盖，12+ 重叠信号路径（ADR-029、ADR-030、ADR-031）
🧠 智能	自学习	从裸 CSI 自监督学习，无标签自举（ADR-024）
🌍 智能	跨环境泛化	域对抗训练剥离环境偏置，模型跨房间/跨硬件迁移（ADR-027）
⚡ 性能	实时/边缘	文档记载 Rust 管线单帧 18.47 µs、约 54,000 fps，模型可量化到 KB 级放进 ESP32 SRAM

技术栈为 Rust（主运行时可执行程序 + 15 crate 工作区）与 Python（legacy v1 验证与 API），推理后端覆盖 ONNX / PyTorch / Candle，并可编译为 WASM 在浏览器运行。工作区成员清单见 v2/Cargo.toml（其中已声明 wifi-densepose-pointcloud）。

⚠️ 阅读提示：仓库自身对若干早期性能数字做过正式撤回（详见下文第七节的 "精度撤回" 段落），引用本文数据时应以该声明为准。

二、最新能力：多传感器实时稠密点云（`ruview-pointcloud`）

仓库最新（文档 "Latest Additions" 首条）能力是实时三维点云融合：把摄像头深度、WiFi CSI 与 mmWave 雷达同时流进一个统一空间模型。

传感器	数据	融合方式
摄像头	MiDaS 单目深度（GPU）	640×480 → 每帧 19,200+ 深度点
ESP32 CSI	ADR-018 二进制帧（UDP）	RF 断层成像 → 8×8×4 占用网格
WiFlow 姿态	CSI 推算 17 COCO 关键点	骨架叠加到点云
生命体征	CSI 相位推算呼吸率	每 60 秒同步到 ruOS "大脑"
运动	CSI 幅度方差	自适应采集帧率（静止时跳过深度计算）

构建与启动（工作区 crate，位于 v2/crates/wifi-densepose-pointcloud，src 下含 main.rs、camera.rs、depth.rs、fusion.rs、csi_pipeline.rs、pointcloud.rs、stream.rs、training.rs、brain_bridge.rs）：

cd v2
cargo build --release -p wifi-densepose-pointcloud
./target/release/ruview-pointcloud serve --bind 127.0.0.1:9880
# 打开 http://localhost:9880 查看实时 3D 点云

CLI 命令族（与 main.rs 中 Commands 枚举一一对应）：

ruview-pointcloud demo                            # 合成演示：写出 demo_pointcloud.ply + demo_splats.json
ruview-pointcloud serve --bind 127.0.0.1:9880     # 实时服务 + Three.js 查看器
ruview-pointcloud capture --output room.ply       # 捕获为 PLY
ruview-pointcloud train                           # 深度标定 + DPO 配对
ruview-pointcloud cameras                         # 列出可用摄像头
ruview-pointcloud csi-test --count 100            # 发送测试 CSI 帧
ruview-pointcloud fingerprint office --seconds 5  # 录制命名 CSI 房间指纹

安全默认值：HTTP/查看器服务默认只绑定回环地址 127.0.0.1:9880，把摄像头/CSI/体征暴露到 0.0.0.0 属显式选择。大脑（ruOS brain）URL 默认 http://127.0.0.1:9876，可通过环境变量 RUVIEW_BRAIN_URL 或 serve/train 子命令的 --brain 标志覆盖。

两条重要的诚实标注（来自仓库文档，务必阅读）：

姿态叠加目前使用幅度能量启发式（heuristic_pose_from_amplitude），并非已训练的 WiFlow 推理——真正的 ONNX/Candle 推理被列为后续工作；
大脑同步在 brain_bridge.rs 中实现为每 60 秒调用一次 sync_to_brain：把运动、体征（呼吸在 5–35 BPM 区间内才写入）、骨架、占用等汇总为 spatial-motion/spatial-vitals 类记忆条目，供 Agent 推理。文档记载管线 22 ms、API 905 req/s、20 帧即可重建约 4 万体素的房间模型。

三、安装：五条路径

3.1 引导式安装器

./install.sh

安装器执行 7 步：系统检测 → 工具链检查 → WiFi 硬件扫描 → 配置档推荐 → 依赖安装 → 构建 → 验证。

配置档	安装内容	大小	要求
`verify`	仅管线验证	~5 MB	Python 3.8+
`python`	完整 Python API 服务+传感	~500 MB	Python 3.8+
`rust`	Rust 管线（约 810x 加速）	~200 MB	Rust 1.70+
`browser`	浏览器内执行 WASM	~10 MB	Rust + wasm-pack
`iot`	ESP32 传感网格+聚合器	视情况	Rust + ESP-IDF
`docker`	Docker 化部署	~1 GB	Docker
`field`	WiFi-Mat 灾害救援套件	~62 MB	Rust + wasm-pack
`full`	全量	~2 GB	全工具链

# 非交互安装
./install.sh --profile rust --yes

# 仅做硬件探测
./install.sh --check-only

3.2 源码与 pip

# Rust（主路径）
cd v2
cargo build --release
cargo test --workspace

# Python（legacy v1）
pip install -r requirements.txt
pip install -e .

# 或直接 pip 安装发布包
pip install wifi-densepose
pip install wifi-densepose[gpu]   # GPU 加速
pip install wifi-densepose[all]   # 全部可选依赖

Python 包源码位于 python/wifi_densepose（含 .pyi 类型桩与 .typed 标记），导入路径即 from wifi_densepose import WiFiDensePose。

3.3 Docker

# Rust 传感服务（132 MB，推荐）
docker pull ruvnet/wifi-densepose:latest
docker run -p 3000:3000 -p 3001:3001 -p 5005:5005/udp ruvnet/wifi-densepose:latest

# Python 管线（569 MB）
docker pull ruvnet/wifi-densepose:python
docker run -p 8765:8765 -p 8080:8080 ruvnet/wifi-densepose:python

# 二者一起（仓库含 docker/docker-compose.yml）
cd docker && docker compose up

# 导出 RVF 模型
docker run --rm -v $(pwd):/out ruvnet/wifi-densepose:latest --export-rvf /out/model.rvf

镜像	标签	平台	端口
`ruvnet/wifi-densepose`	`latest`, `rust`	linux/amd64、linux/arm64	3000(REST)、3001(WS)、5005/udp(ESP32)
`ruvnet/wifi-densepose`	`python`	linux/amd64	8765(WS)、8080(UI)

3.4 系统要求

Rust ≥ 1.70（主运行时）；Python ≥ 3.8；OS 支持 Linux（Ubuntu 18.04+）、macOS 10.15+、Windows 10+；内存最低 4 GB、推荐 8 GB+；磁盘预留 2 GB；可选带 CSI 能力的 WiFi 网卡；GPU（NVIDIA CUDA / Apple Metal）可选。

3.5 Rust crate 化拆包

工作区共有 15 个 crate 发布到 crates.io，可通过 cargo add 单独引用，例如：

cargo add wifi-densepose-core       # 类型、trait、错误
cargo add wifi-densepose-signal     # CSI 信号处理（6 个 SOTA 算法）
cargo add wifi-densepose-nn         # 神经推理（ONNX/PyTorch/Candle）
cargo add wifi-densepose-vitals     # 体征提取（呼吸+心率）
cargo add wifi-densepose-mat        # 灾害响应（MAT 幸存者检测）
cargo add wifi-densepose-hardware   # ESP32/Intel 5300/Atheros 传感器
cargo add wifi-densepose-train      # 训练管线（MM-Fi 数据集）
cargo add wifi-densepose-wifiscan   # 多 BSSID WiFi 扫描
cargo add wifi-densepose-ruvector   # RuVector v2.0.4 集成层（[ADR-017](https://gitcode.com/GitHub_Trending/wi/RuView/blob/c4021f98846cb03759140dcb265b157082b2ef81/docs/adr/ADR-017-ruvector-signal-mat-integration.md?utm_source=gitcode_repo_files)）

其余 crate：wifi-densepose-wasm、wifi-densepose-sensing-server（Axum UDP 摄取 + WebSocket 广播）、wifi-densepose-cli、wifi-densepose-api、wifi-densepose-config、wifi-densepose-db（PostgreSQL/SQLite/Redis）。wifi-densepose-pointcloud 与 wifi-densepose-geo（Sentinel-2/SRTM/OSM 地理上下文）目前仅在仓库工作区内。另有独立的 rUv Neural 12-crate 脑网络分析工作区。

四、三命令快速开始

1) 启动（Docker 或源码）

docker pull ruvnet/wifi-densepose:latest
docker run -p 3000:3000 ruvnet/wifi-densepose:latest
# 或：./install.sh --profile rust --yes

2) Python 客户端

from wifi_densepose import WiFiDensePose

system = WiFiDensePose()
system.start()
poses = system.get_latest_poses()
print(f"Detected {len(poses)} persons")
system.stop()

3) REST API

curl http://localhost:3000/health                # 健康检查
curl http://localhost:3000/api/v1/sensing/latest # 最新传感帧
curl http://localhost:3000/api/v1/vital-signs    # 生命体征
curl http://localhost:3000/api/v1/pose/current   # 姿态
curl http://localhost:3000/api/v1/info           # 服务信息

4) 实时 WebSocket

import asyncio, websockets, json

async def stream():
    async with websockets.connect("ws://localhost:3001/ws/sensing") as ws:
        async for msg in ws:
            data = json.loads(msg)
            print(f"Persons: {len(data.get('persons', []))}")

asyncio.run(stream())

注意端口差异：Docker 默认 HTTP 3000/WS 3001；二进制程序默认 HTTP 8080/WS 8765，可用 --http-port/--ws-port 覆盖。

五、ESP32-S3 硬件管线（ADR-018）

5.1 板级指标与架构

单块约 $9 的 ESP32-S3 以 28 Hz 捕获 WiFi 信号经 UDP 上传；亦可完全独立运行——板载检测存在性、呼吸、心率与跌倒，无需任何服务器。

ESP32-S3 节点                     UDP/5005         主机服务（可选）
┌───────────────────────┐      ──────────>      ┌──────────────────────┐
│ 28 Hz 捕获 WiFi 信号  │      二进制帧          │ 解析帧 / 可视化姿态  │
│ 单帧最多 192 子载波    │  或 32 字节体征包      │ 记录 CSI / REST+WS   │
│ 板载（可选）：存在性   │                       └──────────────────────┘
│ 呼吸+心率 / 跌倒 / WASM│
└───────────────────────┘

指标	实测值
CSI 帧率	28.5 Hz（信道 5、BW20）
每帧子载波	64 / 128 / 192（随 WiFi 模式）
UDP 延迟	局域网 <1 ms
存在性检测距离	穿墙 3 m 可靠
固件体积	990 KB（8 MB flash）/ 773 KB（4 MB flash）
上电就绪	约 3.9 秒

5.2 烧录与配置（无需编译工具链，用发布二进制）

# 8MB flash 板（最常见）
python -m esptool --chip esp32s3 --port COM7 --baud 460800 \
  write_flash --flash-mode dio --flash-size 8MB --flash-freq 80m \
  0x0 bootloader.bin 0x8000 partition-table.bin \
  0xf000 ota_data_initial.bin 0x20000 esp32-csi-node.bin

# 4MB flash 板（如 ESP32-S3 SuperMini 4MB）
python -m esptool --chip esp32s3 --port COM7 --baud 460800 \
  write_flash --flash-mode dio --flash-size 4MB --flash-freq 80m \
  0x0 bootloader.bin 0x8000 partition-table-4mb.bin \
  0xF000 ota_data_initial.bin 0x20000 esp32-csi-node-4mb.bin

# 配置 WiFi 凭据与服务器地址（写入 flash，掉电不丢）
python firmware/esp32-csi-node/provision.py --port COM7 \
  --ssid "YourWiFi" --password "secret" --target-ip 192.168.1.20

# 可选：启动主机服务可视化
cargo run -p wifi-densepose-sensing-server -- --http-port 3000 --source auto
# 打开 http://localhost:3000

配置逻辑集中在固件侧 provision.py（该目录附带 tests/test_provision.py 与 tests/test_provision_state.py，覆盖参数解析与持久化状态）。

5.3 多节点网格（TDM）

3–6 节点时分复用轮流发射可显著提升精度与覆盖：

# 3 节点网格的 0 号节点
python firmware/esp32-csi-node/provision.py --port COM7 \
  --ssid "YourWiFi" --password "secret" --target-ip 192.168.1.20 \
  --node-id 0 --tdm-slot 0 --tdm-total 3

# 1 号节点
python firmware/esp32-csi-node/provision.py --port COM8 \
  --ssid "YourWiFi" --password "secret" --target-ip 192.168.1.20 \
  --node-id 1 --tdm-slot 1 --tdm-total 3

节点还可跨 WiFi 信道（1/6/11）跳频增加传感带宽（ADR-029）。

5.4 Cognitum Seed 集成（ADR-069）

ESP32 桥接 Cognitum Seed 后获得持久向量库、kNN 搜索、见证链与 AI 可访问的 MCP 代理：

ESP32-S3 ($9) ──UDP──> 主机桥接 ──HTTPS──> Cognitum Seed
 CSI 采集              seed_csi_bridge.py     RVF 向量存储
 8 维特征 @1 Hz                               kNN 相似度检索
 体征 + 存在性                                Ed25519 见证链
                                              114 工具 MCP 代理

export SEED_TOKEN="your-pairing-token"
python scripts/seed_csi_bridge.py \
  --seed-url https://169.254.42.1:8443 --token "$SEED_TOKEN" --validate

python scripts/seed_csi_bridge.py --token "$SEED_TOKEN" --stats

8 维特征向量（均归一化到 [0.0, 1.0]）包含：存在性、运动、呼吸率、心率、相位方差、人数、跌倒检测与 RSSI。全架构见 ADR-069。

5.5 板载智能分级（v0.3.0-alpha 起）

Alpha 固件可本地分析信号，缺省关闭以保持向后兼容：

级别	行为	占用 RAM
0	关闭——仅流原始 CSI（同 v0.2.0）	0 KB
1	信号清洗 + 子载波优选 + 压缩（省 30–50% 带宽）	~30 KB
2	全部 1 级 + 存在性、呼吸/心率、跌倒检测	~33 KB
3	全部 2 级 + 自定义 WASM 模块（手势、入侵检测等 63+，见 docs/edge-modules）	~160 KB/模块

免重刷启用（只重新 provision）：

# 已烧录节点开启 2 级（体征）
python firmware/esp32-csi-node/provision.py --port COM7 \
  --ssid "YourWiFi" --password "secret" --target-ip 192.168.1.20 \
  --edge-tier 2

# 微调阈值（fall-thresh 单位 1/1000，15000 = 15.0 rad/s²）
python firmware/esp32-csi-node/provision.py --port COM7 \
  --edge-tier 2 --vital-int 500 --fall-thresh 15000 --subk-count 16

开启 2 级后节点每秒发送一条 32 字节体征包：存在性、运动级、呼吸 BPM、心率 BPM、置信度、跌倒告警标志与占用人数。固件细节见 firmware/esp32-csi-node/README.md、ADR-039 与 ADR-044。

六、信号处理与传感

6.1 六大 SOTA 信号算法（ADR-014）

全部实现在 wifi-densepose-signal crate 内，确定性测试、零 mock：

算法	作用	解决什么问题	数学核心
共轭相乘	`H₁[k]×conj(H₂[k])` 配对相乘	抵消 CFO/SFO/包检测时延导致的相位污染，只保留环境相位差（SpotFi）	`CSI_ratio[k]=H₁[k]*conj(H₂[k])`
Hampel 滤波	用"中位数±缩放 MAD"替换离群点	均值/方差被离群点本身污染，中位数抗 50% 污染	`σ̂=1.4826×MAD`
Fresnel 区模型	按 TX-RX-人体几何预测呼吸信号出现位置	过零点计数在多径环境失效	`ΔΦ=2π·2Δd/λ`
CSI 频谱图	每子载波滑窗 FFT(STFT)→时频矩阵	呼吸 0.2–0.4 Hz、走动 1–2 Hz，2D 结构可喂 CNN	`S[t,f]=
子载波优选	按运动灵敏度方差比排序取 top-K	部分子载波落在多径零点，优选后 SNR 提升 6–10 dB	`sensitivity=var_motion/var_static`
体速分布 BVP	跨子载波多普勒速度分布	域无关特征，作为跨环境识别的基（Widar 3.0）	`BVP[v,t]=Σ

处理顺序：原始 CSI → 共轭相乘（相位清洗）→ Hampel（去离群）→ 子载波优选（top-K）→ CSI 频谱图（时频）→ Fresnel 模型（呼吸）+ BVP（活动）。数学推导见 ADR-014。

6.2 生命体征检测（ADR-021）

能力	范围	方法
呼吸率	6–30 BPM（0.1–0.5 Hz）	带通滤波 + FFT 峰值
心率	40–120 BPM（0.8–2.0 Hz）	带通滤波 + FFT 峰值
采样率	20 Hz（ESP32 CSI）	实时流式
置信度	每项 0.0–1.0	频谱相干性 + 信号质量

./target/release/sensing-server --source simulate --http-port 3000 --ws-port 3001 --ui-path ../../ui
curl http://localhost:3000/api/v1/vital-signs

6.3 WiFi 扫描域（ADR-022/025）

Windows/macOS/Linux 的 8 级 RSSI 管线：预测门控 → 注意力加权 → 空间相关 → 运动估计 → 呼吸提取（亚 Hz 振荡）→ 质量门控 → 指纹匹配 → 编排融合。验证：

cargo test -p wifi-densepose-wifiscan

6.4 WiFi-Mat：灾害响应（ADR-001）

WiFi 可穿透非金属废墟（混凝土/木材/石膏板），wifi-densepose-mat crate（139 测试）通过 CSI 检测废墟下幸存者、用 START 分级并估计 3D 位置：

能力	实现	目标
呼吸检测	带通 0.07–1.0 Hz + Fresnel 建模 5–10 mm 胸位移	4–60 BPM、<500 ms
心跳检测	微多普勒相位提取	ruvector-temporal-tensor
3D 定位	多 AP 三角化 + CSI 指纹 + 分层深度估计	穿透 3–5 m
START 分级	呼吸+运动+体征集成投票 → P1–P4	假阴 <1%

分级规则：Immediate(红/有呼吸无运动/P1)、Delayed(黄/运动+呼吸稳定体征/P2)、Minor(绿/强烈运动/P3)、Deceased(黑/连续 30 分钟无体征/P4)。部署形态支持便携、分布式、无人机与车载。安全保证为 fail-safe 默认、多算法冗余投票、完整审计与离线可用。用户指南见 docs/wifi-mat-user-guide.md，域模型见 docs/ddd/wifi-mat-domain-model.md。

七、模型与训练

7.1 RVF 单文件模型容器

RVF（RuVector Format）把模型权重、HNSW 索引、量化码本、SONA 增量与 WASM 推理运行时打包成单个自包含二进制：

部署目标	量化	体积	加载	用途
ESP32/IoT	int4	~0.7 MB	<5 ms（A 层）	存在性+呼吸
移动/WebView	int8	~6 MB	~200 ms（B 层）	手机端姿态
浏览器 WASM	int8	~10 MB	~500 ms（B 层）	浏览器演示
现场（WiFi-Mat）	fp16	~62 MB	~2 s（C 层）	全量 DensePose+分级
服务器/云	f32	50+ MB	~3 s（C 层）	训练+全量推理

关键属性：分段二进制格式（20+ 段类型、每段 CRC32 完整性）；三层渐进加载（A：清单+入口 <5 ms → B：热权重+邻接 100 ms–1 s → C：全图秒级）；Ed25519 训练证明（数据到模型的链式溯源）；分层量化 f32/f16/int8/int4 带 SIMD 距离计算。CLI 关联 --export-rvf/--load-rvf/--save-rvf/--model/--progressive。命令见 ADR-023。

./target/release/sensing-server --export-rvf wifi-densepose-v1.rvf
./target/release/sensing-server --model wifi-densepose-v1.rvf --progressive
docker run --rm -v $(pwd):/out ruvnet/wifi-densepose:latest --export-rvf /out/model.rvf

7.2 训练与 SONA 自适应

纯 Rust 8 相训练管线（文档记载约 7,832 行、零外部 ML 依赖），目标是把 CSI 特征矩阵映射为 17 COCO 关键点 + DensePose UV：

相	模块	作用
1	`dataset.rs`	MM-Fi `.npy` + Wi-Pose `.mat` 加载、子载波重采样（114→56、30→56）
2	`graph_transformer.rs`	COCO BodyGraph（17 关键点/16 边）、天线图、多头 CrossAttention、GCN 消息传递
3	`trainer.rs`	6 项复合损失（MSE/CE/UV/时序/骨骼/对称）、SGD+momentum、cosine+warmup、PCK/OKS
4	`sona.rs`	LoRA 适配器、EWC++ Fisher 正则、EnvironmentDetector（3-sigma 漂移）
5	`sparse_inference.rs`	热/冷神经元分区、SparseLinear 跳冷行、INT8/FP16
6	`rvf_pipeline.rs`	三层渐进加载、HNSW 索引、OverlayGraph
7	`rvf_container.rs`	容器格式、6+ 段类型、CRC32
8	`main.rs`	`--train`/`--model`/`--progressive` 接线

三层数据策略：①MM-Fi+Wi-Pose 公开数据集预训练（跨环境泛化）；②ESP32 CSI + 相机伪标签微调（环境多径适配）；③SONA 微适配（rank-4 微 LoRA + EWC++，无灾难性遗忘的设备端持续学习）。

SONA 四件套：微 LoRA（参数少 100 倍→能跑 ESP32）、EWC++（用 Fisher 惩罚改动重要权重→跨房间不忘旧知识）、EnvironmentDetector（3-sigma 特征漂移自动触发适配）、best-epoch 快照（避免导出过拟合末轮参数）。

./target/release/sensing-server --train --dataset data/ --dataset-type mmfi --epochs 100
./target/release/sensing-server --train --dataset data/ --epochs 100 --save-rvf model.rvf
docker run --rm -v $(pwd)/data:/data ruvnet/wifi-densepose:latest \
  --train --dataset /data --epochs 100 --export-rvf /data/model.rvf

7.3 RuVector 智力层

RuVector 5 个直接依赖 crate 替换手调阈值：

AI 能力	替换什么	crate
自优化信道选择	换房间即失效的手调阈值	`ruvector-mincut`
注意力信号清洗	漏掉微弱呼吸的固定能量阈值	`ruvector-attn-mincut`
学习式信号融合	一条坏信道污染全局的简单平均	`ruvector-attention`
物理定位	昂贵的非线性求解器	`ruvector-solver`
O(1) 幸存者三角化	O(N³) 矩阵求逆	`ruvector-solver`（Neumann 级数）
75% 内存压缩	13.4 MB 呼吸缓冲	`ruvector-temporal-tensor`

另有 6 个 vendored crate（ruvector-core、ruvector-gnn、ruvector-graph-transformer、ruvector-sparse-inference、ruvector-nervous-system、ruvector-coherence）供训练与推理使用。集成点共 7 个，见 ADR-017。

7.4 预训练模型（v0.6.0）：零训练开箱即用

文档称模型基于 8 小时隔夜采集的 60,630 个真实样本训练，只需下载即可用：

模型	体积	用途
`model.safetensors`	48 KB	对比编码器——128 维嵌入（存在性/活动/环境）
`model-q4.bin`	8 KB	4-bit 量化——可放入 ESP32-S3 SRAM
`model-q2.bin`	4 KB	2-bit 超紧凑
`presence-head.json`	2.6 KB	存在性检测头
`node-1.json`/`node-2.json`	21 KB	逐房间 LoRA 适配器（换房间即换）

pip install huggingface_hub
huggingface-cli download ruv/ruview --local-dir models/

# 或接入管线自行重训/评测
node scripts/train-ruvllm.js --data data/recordings/*.csi.jsonl
node scripts/benchmark-ruvllm.js --model models/csi-ruvllm

文档所载实测（Apple M4 Pro、隔夜数据重训）：嵌入质量 82.3% held-out 时序三元组、单嵌入推理 0.008 ms、吞吐 164,183 嵌入/秒、4-bit 8 KB 体积。注意：文档同时明确撤回早期 "100% presence" 说法（单类录音所致），"100% accurate presence head" 等早期数字应以该撤回为准。

7.5 v0.7.0 相机真值训练 + 精度撤回

v0.7.0 引入 MediaPipe + 真实 ESP32 CSI 的相机监督姿态训练：

能力	说明	ADR
相机真值采集	MediaPipe PoseLandmarker 30fps 抓 17 COCO 关键点，与 ESP32 CSI 同步	ADR-079
ruvector 子载波选择	基于方差 top-K，输入降 50%（70→35）	ADR-079 O6
Stoer-Wagner 最小割	分人子载波聚类（多人训练）	ADR-079 O8
可扩展 WiFlow 模型	4 档：lite(189K)→small(474K)→medium(800K)→full(7.7M)	ADR-079

# 并行采集（相机 + ESP32）
python scripts/collect-ground-truth.py --duration 300 --preview
python scripts/record-csi-udp.py --duration 300

# 对齐 CSI 窗口与相机关键点
node scripts/align-ground-truth.js --gt data/ground-truth/*.jsonl --csi data/recordings/*.csi.jsonl

# 训练 WiFlow（从小档起步，随数据增长升档）
node scripts/train-wiflow-supervised.js --data data/paired/*.jsonl --scale lite

# 评测
node scripts/eval-wiflow.js --model models/wiflow-real/wiflow-v1.json --data data/paired/*.jsonl

精度撤回（2026-06-10，务必引用）：此前的 "92.9% PCK@20" 已被正式撤回——对保留评测集（69 样本）的法证复查发现，该分数是用非躯干归一化的绝对阈值在近静态帧上评出，而 trivial 均值预测器在该协议下可得 100%；同一评测集上经躯干归一化的 PCK@20 约 19%（即退化预测器）。当前没有任何已发布的相机监督 PCK@20 指标。历史训练记录（评测损失 0.082、骨骼约束 0.008、训练 19 分钟、模型 974 KB）为撤回前协议产物。

7.6 跨环境泛化（ADR-027，Project MERIDIAN）

机制	原理
梯度反转层	对抗分类器猜信号来源房间，主网络学欺骗它 → 丢弃房间捷径
几何编码器（FiLM）	收发端位置傅里叶编码 → 每层 scale+shift 条件注入
硬件归一化器	任意芯片组 CSI 重采样为规范 56 子载波 + 标准化幅度
虚拟域增强	随机房间尺度/墙反射/散射体/噪声谱合成大量虚拟环境
快速适配（TTT）	对比式测试时训练 + LoRA 权重生成 → 零样本到场自调
跨域评测器	逐环境留一法 PCK/OKS，证明泛化而非记忆

安全加固：校准缓冲有界（≤10,000 帧）、adapt() 返回 Result 不 panic、原子实例计数器、增强参数零除防护。详见 ADR-027。

7.7 多静态传感（ADR-029/030/031，RuvSense）+ CRV 六阶段

4 个 ESP32-S3 节点提供 12 条 TX-RX 测量链路覆盖 360°；每节点依次发射（TDM）、跨信道 1/6/11 跳频；相干性门控（Accept/PredictOnly/Reject/Recalibrate）自动拒噪。RuvSense 域模型见 docs/ddd/ruvsense-domain-model.md。验收标准：躯干关键点抖动 <30 mm RMS、10 分钟 0 次身份互换、20 Hz 更新、3 m 处呼吸 SNR >10 dB。

CRV（Coordinate Remote Viewing）六阶段信号线把 CRV 方法论映射为 CSI 处理：I 意念图（超球嵌入）→ II 感官（多头注意力）→ III 维度（GNN 拓扑）→ IV 情感/AOL（SNN 相干门控）→ V 审问（可微搜索）→ VI 3D 模型（MinCut 分区），并提供跨会话收敛用于跨房间身份连续性。

八、系统架构速览

文档给出了三张 mermaid 图：端到端数据流（硬件层 → 摄取 → 信号处理（RuVector v2.0.4）→ 神经管线 → 体征 → REST/WS/Analytics/UI）、信号处理细节（原始 I/Q → 相位清洗 → 子载波智能 → 特征提取 → 输出）、部署拓扑（ESP32 网格 UDP:5005 → Rust 传感服务 :3000/:3001 → 浏览器/移动/仪表盘/家庭自动化）。关键组件到 crate 的映射：聚合器 wifi-densepose-hardware；信号处理器 wifi-densepose-signal；子载波选择 ruvector-mincut+ruvector-attn-mincut；Fresnel 求解 ruvector-solver；图 Transformer wifi-densepose-train；体征 wifi-densepose-signal；REST wifi-densepose-sensing-server；分析 wifi-densepose-mat；Web UI 位于 ui/。

九、CLI 与 API 参考

9.1 Rust 传感服务主 CLI

./target/release/sensing-server --source simulate --ui-path ../../ui   # 模拟数据，无需硬件
./target/release/sensing-server --source esp32 --udp-port 5005        # ESP32 硬件
./target/release/sensing-server --source wifi                          # Windows WiFi RSSI
./target/release/sensing-server --benchmark                            # 体征基准（1000 帧）
./target/release/sensing-server --export-rvf model.rvf                 # 导出 RVF
./target/release/sensing-server --train --dataset data/ --epochs 100   # 训练
./target/release/sensing-server --model wifi-densepose-v1.rvf --progressive

标志	说明
`--source`	数据源：`auto`/`wifi`/`esp32`/`simulate`
`--http-port`	HTTP（默认 8080，Docker 内 3000）
`--ws-port`	WebSocket（默认 8765，Docker 内 3001）
`--udp-port`	ESP32 CSI UDP 口（默认 5005）
`--benchmark`	跑 1000 帧体征基准后退出
`--export-rvf`	导出 RVF 容器后退出
`--load-rvf`	从 RVF 载入配置
`--save-rvf`	关机时保存模型状态
`--model`	载入已训练 `.rvf` 推理
`--progressive`	渐进加载（A 层即时启动）
`--train`/`--dataset`/`--epochs`	训练及参数

9.2 REST / WebSocket

GET  /api/v1/sensing              # 最新传感帧
GET  /api/v1/vital-signs          # 呼吸、心率、置信度
GET  /api/v1/bssid                # 多 BSSID 注册表
GET  /api/v1/model/layers         # 渐进加载状态
GET  /api/v1/model/sona/profiles  # SONA 配置档
POST /api/v1/model/sona/activate  # 激活 SONA 配置档

WebSocket：ws://localhost:3001/ws/sensing（实时传感+体征）。

9.3 Python legacy CLI（v1）

wifi-densepose start                 # 启动 API 服务
wifi-densepose -c config.yaml start  # 自定义配置
wifi-densepose -v start              # 详细日志
wifi-densepose status / stop
wifi-densepose config show
wifi-densepose db init
wifi-densepose tasks list

十、17 个传感应用速查（单 ESP32 即可运行）

所有脚本均支持 --replay data/recordings/*.csi.jsonl 离线重放与 --json 程序化输出：

健康与安老：睡眠监测 node scripts/sleep-monitor.js（睡眠分期/效率/睡眠图）；呼吸暂停 node scripts/apnea-detector.js（>10 s 暂停、AHI 评分）；压力 node scripts/stress-monitor.js（HRV、LF/HF）；步态 node scripts/gait-analyzer.js（步频/步态不对称/震颤）。

环境与安防：人数统计 node scripts/mincut-person-counter.js（修复 #348，原先恒为 4）；房间指纹 node scripts/room-fingerprint.js；物体识别 node scripts/material-detector.js（子载波零点变化）；设备指纹 node scripts/device-fingerprint.js。

多频网格（需 --hop-channels 配网）：RF 断层成像 node scripts/rf-tomography.js；被动雷达 node scripts/passive-radar.js（借邻居 AP 作双基雷达照射源）；材质分类 node scripts/material-classifier.js（金属/水/木/玻璃）；穿墙检测 node scripts/through-wall-detector.js。

v0.5.5 起的传感扩展脚本也归于此族：

node scripts/rf-scan.js --port 5006 --duration 30          # 实时 RF 频谱扫描
node scripts/mincut-person-counter.js --port 5006           # 正确人数统计
node scripts/snn-csi-processor.js --port 5006               # SNN STDP 实时适配
node scripts/csi-spectrogram.js --replay data/recordings/*.csi.jsonl  # CNN 频谱图嵌入
node scripts/train-wiflow.js --data data/recordings/*.csi.jsonl       # WiFlow 姿态训练
python firmware/esp32-csi-node/provision.py --port COM9 --hop-channels "1,6,11"  # 跳频

对应 ADR：SNN ADR-074、MinCut ADR-075、CNN 频谱图嵌入 ADR-076、WiFlow ADR-072、多频网格 ADR-073。ruvllm 训练族另见 collect-training-data.py/train-camera-free.js（相机无关 17 关键点姿态，PIR+RSSI+振动+子载波非对称特征）等脚本。

十一、测试与验证

cd v2 && cargo test --workspace          # Rust 主测试集
cargo test -p wifi-densepose-sensing-server
./target/release/sensing-server --benchmark
python -m pytest archive/v1/tests/ -v    # Python（legacy v1）
./verify                                  # 无硬件管线验证

套件	测试数	覆盖
sensing-server lib	147	图 Transformer、trainer、SONA、稀疏推理、RVF
sensing-server bin	48	CLI 集成、WebSocket、REST
RVF 集成	16	容器构建/读取/渐进加载
体征集成	18	FFT 检测、呼吸、心跳
wifi-densepose-signal	83	SOTA 算法、Doppler、Fresnel
wifi-densepose-mat	139	灾害响应、分级、定位
wifi-densepose-wifiscan	91	8 级 RSSI 管线

无硬件时代可用 --source simulate 做全栈模拟。固件侧可借助 QEMU 平台（ADR-061，9 层测试：mock CSI → 单节点 UART 校验 → 多节点 TDM/TAP → GDB → 覆盖率 → fuzz → NVS 矩阵 → 快照回归 → 混沌注入，对应脚本 scripts/qemu-esp32s3-test.sh、scripts/qemu-mesh-test.sh、scripts/qemu-chaos-test.sh、scripts/qemu_swarm.py 等）以及无硬件见证包验证（bash scripts/generate-witness-bundle.sh）。

十二、部署与运行环境变量

docker run -p 3000:3000 -p 3001:3001 -p 5005:5005/udp ruvnet/wifi-densepose:latest
cd docker && docker compose up     # 双镜像一键起

环境变量	默认	作用
`RUST_LOG`	-	日志级别（如 `info`）
`WIFI_INTERFACE`	-	RSSI 用 WiFi 网卡（如 `wlan0`）
`POSE_CONFIDENCE_THRESHOLD`	0.7	最低置信度
`POSE_MAX_PERSONS`	10	最大跟踪人数
`RUVIEW_BRAIN_URL`	`http://127.0.0.1:9876`	ruOS 大脑地址（点云服务）

十三、性能基准（仓库自测声明）

指标	数值
体征检测	11,665 fps（86 µs/帧）
全 CSI 管线	54,000 fps（18.47 µs/帧）
运动检测	186 ns（对比 Python 约 5,400x）
Docker 镜像	132 MB（Rust）
内存占用	~100 MB
测试数	542+

Rust v2 相对 Python v1 的对比如下（文档记载）：CSI 预处理约 1000x、相位清洗约 780x、特征提取约 890x、运动检测约 5400x、全管线约 810x；镜像 569 MB→132 MB、测试 41→542+、WASM 从无到支持。此类数字为仓库内 cargo bench 声明，引用时应注明测量环境与协议。点云模块自述 22 ms 管线与 905 req/s 同样属于仓库声明的实测范畴。

十四、版本脉络（changelog 要点）

v3.2.0：24 个热加载 WASM 边缘智能模块（no_std → wasm32）、板载 DTW 手势学习、EWC++ 终身学习、AI 安全模块、8 节点自愈网格。
v3.1.0：RuvSense 多静态感知（TDM/跳频/相干门控/Kalman re-ID）、持久场模型（SVD/断层成像/意图预测）、ADR-031 跨视角融合、CRV 六阶段集成、ADR-032/032a 网格安全（HMAC/SipHash/QUIC TLS 1.3）。
v3.0.0：AETHER 对比嵌入模型、RuVector AI 骨架（7 集成点）、macOS CoreWLAN/Linux iw 适配器、Docker 镜像发布、MERIDIAN 跨环境泛化。
v2.0.0：完整 Rust 传感服务、6 大 SOTA 算法、WiFi-Mat、ESP32 硬件、引导式安装器、Three.js 可视化。

完整的逐版本变更记录在 CHANGELOG.md；许可证见 LICENSE。