RuView wifi-densepose-wifiscan 源码解析：基于 Rust 的多 BSSID WiFi 扫描与人体感知管道

导读

wifi-densepose-wifiscan 是 RuView / WiFi-DensePose Rust 工作区中负责 BSSID Acquisition（BSSID 采集） 有界上下文的纯 Rust crate（版本 0.3.2）。它把 Windows 环境下 netsh wlan show networks mode=bssid 的文本输出解析成结构化观测数据，维护跨扫描稳定的 BSSID 注册表，并把多 AP 的 RSSI 信号聚合为带时间戳的 MultiApFrame 伪 CSI 帧，供运动检测、呼吸估算、注意力加权与指纹匹配等下游感知管道消费。读完本文，你将掌握该 crate 的领域模型、三层扫描适配器（Tier 1 netsh / Tier 2 wlanapi / 跨平台 iw）、BssidRegistry 的 Welford 在线统计与子载波映射机制，以及 WindowsWifiPipeline 的 8 阶段信号处理链路，并能在自己的项目中直接落地使用。

一、背景：从单 RSSI 瓶颈到多 BSSID 空间分集

1.1 单 RSSI 模式的数据赤字

根据 ADR-022 设计文档，旧版 Windows WiFi 感知模式每 500ms 启动一次 netsh wlan show interfaces 子进程，只能从已连接 AP 提取一个 RSSI 百分比值，形成所谓的"伪单子载波"帧：1 个幅度值、0 个相位信息、约 2Hz 有效采样率、无空间分集。相比 ESP32 路径的 56 子载波 I/Q 数据（100Hz+），存在约 2800 倍的数据缺口，难以支撑有意义的 DensePose 估算。

1.2 多 BSSID 即伪子载波

普通 Windows WiFi 环境通过 netsh wlan show networks mode=bssid 可以暴露 10~30+ 个 BSSID（ADR-022 记录的真实测试：Intel Wi-Fi 7 BE201 320MHz 适配器可见 23 个 BSSID，覆盖 2.4GHz/5GHz 双频段与 802.11n/ac/ax 多种无线制式）。每个 BSSID 的信号都经过不同的物理传播路径，人体对每条路径的反射/吸收/衍射各不相同，因此多 BSSID 观测构成了等价于伪子载波的空间分集——这正是本 crate 的核心设计前提。

1.3 三级保真度提升路线

层级	方法	子载波数	采样率	实现
现状	netsh show interfaces	1	~2 Hz	子进程
Tier 1	netsh show networks mode=bssid	20+	~2 Hz	解析多 BSSID 输出（本 crate NetshBssidScanner）
Tier 2	Windows WLAN API（wlanapi.dll FFI）	20+	实测，10-20 Hz	原生 FFI 免子进程（本 crate WlanApiScanner）
Tier 3	Intel Wi-Fi Sensing SDK（802.11bf）	56+	100 Hz	厂商 SDK，ADR 中推迟

本 crate 覆盖 Tier 1 与 Tier 2，其中 Tier 2 的实际采样率由 wlanapi_scanner.rs 中的 benchmark() 在运行机器上实测得出，而非写死宣称。

二、crate 结构、特性开关与安全约束

2.1 目录架构

v2/crates/wifi-densepose-wifiscan/src/
  lib.rs            -- 重导出与特性门控
  domain/
    bssid.rs        -- BssidId、BssidObservation、BandType、RadioType
    registry.rs     -- BssidRegistry、BssidEntry、BssidMeta、RunningStats
    frame.rs        -- MultiApFrame（多 BSSID 聚合帧）
    result.rs       -- EnhancedSensingResult 及子类型
  port/
    scan_port.rs    -- WlanScanPort trait（平台抽象）
  adapter/
    netsh_scanner.rs    -- Tier 1：解析 netsh 输出
    wlanapi_scanner.rs  -- Tier 2：原生 WLAN API + netsh 回退
    wlanapi_native.rs   -- wlanapi.dll FFI（仅 Windows 编译）
    macos_scanner.rs    -- macOS CoreWLAN（ADR-025）
    linux_scanner.rs    -- Linux `iw dev <iface> scan`
  pipeline/
    predictive_gate.rs    -- 阶段1：EMA 残差门控
    attention_weighter.rs -- 阶段2：softmax 点积注意力
    correlator.rs         -- 阶段3：Pearson 相关与聚类
    motion_estimator.rs   -- 阶段4：加权方差运动估计
    breathing_extractor.rs-- 阶段5：带通 + 过零呼吸提取
    quality_gate.rs       -- 阶段6：ruQu 三过滤器
    fingerprint_matcher.rs-- 阶段7：ModernHopfield 指纹匹配
    orchestrator.rs       -- 阶段8：全管道编排器
  error.rs          -- WifiScanError

lib.rs 在 crate 根统一重导出全部关键类型，并针对 macOS/Linux 使用 #[cfg(target_os = ...)] 门控对应平台解析函数，确保跨平台可编译。

2.2 Feature Flags

Flag	默认	说明
serde	是	领域类型启用序列化
pipeline	是	启用 WindowsWifiPipeline 感知编排
wlanapi	否	启用 Tier 2 异步扫描（tokio，Windows WLAN API）

default = ["serde", "pipeline"]；wlanapi 会引入 tokio 依赖。值得注意的是 windows-sys（版本 0.59，Win32_Foundation 与 Win32_NetworkManagement_WiFi 特性）仅声明在 [target.'cfg(windows)'.dependencies] 下，非 Windows 平台完全不参与编译。

2.3 安全策略：unsafe 的最小化隔离

Cargo.toml 中 unsafe_code = "deny"（而非 forbid），唯一豁免是经过审计的 wlanapi_native 模块——它通过 #[allow(unsafe_code)] 为 wlanapi.dll FFI 调用重新启用 unsafe。也就是说：除 Tier 2 原生 FFI 单点外，整个 crate 保持无 unsafe 的纯 Rust 实现，README 中宣传的 #[forbid(unsafe_code)] 精神由此落实。

三、快速上手：解析 netsh 输出并注册 BSSID

3.1 最小可用示例

use wifi_densepose_wifiscan::{
    NetshBssidScanner, BssidRegistry, WlanScanPort,
};

// 直接解析 netsh 输出字符串（任何平台都可用于测试）
let netsh_output = "..."; // `netsh wlan show networks mode=bssid` 的输出
let observations = wifi_densepose_wifiscan::parse_netsh_output(netsh_output)?;

// 注册观测到注册表
let mut registry = BssidRegistry::default();
for obs in &observations {
    registry.update(std::slice::from_ref(obs));
}

println!("Tracking {} access points", registry.len());

启用 pipeline 特性后（默认开启），可直接驱动感知管道：

use wifi_densepose_wifiscan::WindowsWifiPipeline;

let mut pipeline = WindowsWifiPipeline::new();
// 将 MultiApFrame 送入管道，得到 EnhancedSensingResult
let frame = registry.to_multi_ap_frame();
let result = pipeline.process(&frame);

在真实 Windows 机器上，可以直接用 NetshBssidScanner::scan_sync() 一步完成"执行 netsh + 解析"（见 netsh_scanner.rs），它内部等价于运行 netsh wlan show networks mode=bssid 并捕获 stdout；非 Windows 平台会返回 WifiScanError::ProcessError。

3.2 WlanScanPort：六边形架构的端口抽象

scan_port.rs 定义了平台无关的驱动侧端口：

pub trait WlanScanPort: Send + Sync {
    /// 执行一次扫描，返回当前所有可见 BSSID
    fn scan(&self) -> Result<Vec<BssidObservation>, WifiScanError>;
    /// 返回当前已连接的 BSSID（如果有）
    fn connected(&self) -> Result<Option<BssidObservation>, WifiScanError>;
}

NetshBssidScanner、WlanApiScanner、MacosCoreWlanScanner、LinuxIwScanner 都是该端口的适配器实现，调用方只需面向 trait 编程即可无缝切换扫描后端。

四、领域模型：从 BSSID 值对象到观测记录

4.1 BssidId：6 字节 MAC 值对象

BSSID 值对象 用 pub struct BssidId(pub [u8; 6]) 包装 IEEE 802.11 MAC 地址，提供：

• BssidId::from_bytes(&[u8])：字节切片构造，长度非 6 返回 WifiScanError::InvalidMac；
• BssidId::parse("aa:bb:cc:dd:ee:ff")：冒号分隔十六进制字符串解析，格式错误返回 MacParseFailed；
• Display 实现输出小写冒号分隔格式。

两个 BssidId 在 MAC 字节相等时相等，是注册表查询与子载波映射的主键。

4.2 BandType 与 RadioType 枚举

pub enum BandType { Band2_4GHz, Band5GHz, Band6GHz }
pub enum RadioType { N /* 802.11n */, Ac /* 802.11ac */, Ax /* 802.11ax */, Be /* 802.11be */ }

• BandType::from_channel(channel) 按信道号推断频段：1..=14 → 2.4GHz，32..=177 → 5GHz，其余 → 6GHz；
• RadioType::from_netsh_str("802.11ax") 解析 netsh 的无线制式字符串，同时兼容 "wi-fi 6" 等别名，无法识别返回 None。

4.3 BssidObservation：单次观测值对象

pub struct BssidObservation {
    pub bssid: BssidId,
    pub rssi_dbm: f64,       // dBm，典型 -30 ~ -90
    pub signal_pct: f64,     // 驱动报告的 0-100 百分比
    pub channel: u8,
    pub band: BandType,
    pub radio_type: RadioType,
    pub ssid: String,        // 隐藏网络可能为空
    pub timestamp: Instant,
}

它附带三个关键转换函数（与 Windows WLAN API 语义对齐，且有单元测试锁定）：

函数	公式	语义
pct_to_dbm(pct)	(pct / 2) - 100	百分比 → dBm，100% → -50dBm，0% → -100dBm
rssi_to_amplitude(rssi)	10^((rssi + 100) / 20)	dBm → 线性幅度，-100dBm → 1.0，-80dBm → 10.0
pseudo_phase()	(channel / 48) * π	信道号 → [0, π] 伪相位，为下游期望相位数据的环节提供兼容

线性幅度与伪相位正是把"RSSI 扫描"包装成"伪 CSI 帧"的桥梁（测试见 bssid.rs 内嵌测试）。

五、BssidRegistry：聚合根与子载波映射

5.1 Welford 在线统计

registry.rs 中的 RunningStats 实现 Welford 在线算法：只需维护 count、mean、m2 三个状态即可增量计算均值、总体方差/样本方差、标准差，无需保存全部历史。这使它能够逐 BSSID 区分"身体相关方差"与"静态背景"——高方差 BSSID 的信号受人体运动调制，低方差则是静态 AP（测试用例用 8 个样本验证均值 5.0、总体方差 4.0、样本方差 32/7）。

5.2 BssidEntry：带历史环的实体

每个被追踪 BSSID 对应一个 BssidEntry：

• history: VecDeque<f64>：容量 128 的 RSSI 环形缓冲，供时序分析（相关器、呼吸提取器消费）；
• stats: RunningStats：全生命周期 Welford 统计；
• meta：首次观测时捕获的 SSID/信道/频段/制式元数据（信道/频段/制式随观测更新，SSID 仅在有值时覆盖）；
• subcarrier_idx: Option<usize>：在伪子载波映射中的稳定索引。

5.3 聚合根行为与默认参数

参数	默认值	说明
DEFAULT_MAX_BSSIDS	32	最大追踪 BSSID 数（即最大伪子载波数），BssidRegistry::new(max_bssids, expiry_secs) 可定制
DEFAULT_EXPIRY_SECS	30	BSSID 超过 30 秒未观测即过期移除

update(&[BssidObservation]) 的核心流程：

1. 更新/插入：已存在则 record() 推进统计与历史；新 BSSID 在容量内注册并按下标顺序分配子载波索引；容量已满时静默忽略（源码注释指出未来可替换为"驱逐最低方差"的智能策略）；
2. 过期清理：超过过期窗口的条目被移除，并重建子载波映射、按序重新编号，保持相对顺序稳定；
3. 测试覆盖了追踪新 BSSID、更新既有统计、容量限制（第 3 个被忽略）等场景。

5.4 to_multi_ap_frame：注册表 → 伪 CSI 帧

to_multi_ap_frame() 把当前注册表快照编码为 MultiApFrame：每个子载波槽位填充最新 RSSI、线性幅度、伪相位、Welford 方差与历史环。采样率由 estimate_sample_rate() 估算：条目数 ≥4 时用 观测次数 / 时间跨度，否则回退 2Hz（Tier 1 netsh 的典型速率）。测试验证 2 个 BSSID 场景下 -60dBm 的幅度大于 -70dBm。

六、MultiApFrame：多 BSSID 聚合帧

frame.rs 定义的 MultiApFrame 是某一时刻全部 BSSID 观测的快照，也是信号智能管道（ADR-022 的有界上下文 2）的输入：

字段	含义
bssid_count	BSSID（伪子载波）数量
rssi_dbm	每 BSSID 的 dBm 值，索引与子载波映射一致
amplitudes	10^((rssi+100)/20) 线性幅度
phases	(channel/48)*π 伪相位，提供空间分集信息
per_bssid_variance	每 BSSID 方差，高值=身体调制，低值=静态背景
histories	每 BSSID 历史环，供相关与谱分析
sample_rate_hz	估算有效采样率：Tier 1 ~2Hz，Tier 2 ~10-20Hz（实测）
timestamp	帧构建时刻

便捷方法：is_sufficient(min_bssids)（与 WindowsWifiConfig::min_bssids 配合）、max_amplitude()、mean_rssi()、total_variance()（全 BSSID 方差之和，与环境变化/人体存在正相关）。空帧被优雅处理：最大幅度 0.0、均值 NEG_INFINITY、is_sufficient 恒 false。

七、平台适配器详解

7.1 Tier 1：NetshBssidScanner（Windows）

NetshBssidScanner 有意保持同步设计——不实现异步 trait，避免不需要异步的调用方被拖入异步运行时；需要异步时用 tokio::task::spawn_blocking 包装即可。解析器 parse_netsh_output() 逐行状态机工作，示例输入：

SSID 1 : MyNetwork
    Network type            : Infrastructure
    Authentication          : WPA2-Personal
    Encryption              : CCMP
    BSSID 1                 : aa:bb:cc:dd:ee:ff
         Signal             : 84%
         Radio type         : 802.11ax
         Band               : 5 GHz
         Channel            : 36

解析规则与健壮性要点（均有测试覆盖）：

• split_kv 用 " : "（空格-冒号-空格）作为分隔符，避免误切 MAC 与含冒号 SSID 内部的冒号（测试：My:Weird:SSID 完整保留）；
• 缺失字段回退默认值：Signal 缺省 0%（→ -100dBm）、Channel 缺省 0、RadioType 缺省 802.11n、Band 由信道推断；
• 无法解析的 MAC 块被丢弃但后续块继续解析（测试：not-a-mac 被跳过，第二个 BSSID 正常产出）；
• 未知/本地化行静默跳过，容忍 CRLF、Interface name 头、There are no wireless networks in range 等场景；
• 同一次扫描的全部观测共享同一 Instant 时间戳；
• 完整示例含 3 个 SSID 5 个 BSSID 的三频段输出（2.4/5/6GHz，含 802.11be/6GHz）也能正确解析。

7.2 Tier 2：WlanApiScanner（Windows，原生优先）

wlanapi_scanner.rs 的实现策略是原生优先、netsh 回退：

• 原生路径 scan_native() 走 WlanOpenHandle → WlanEnumInterfaces → WlanGetNetworkBssList FFI，读取驱动缓存的 BSS 列表，无 netsh.exe 子进程；其速率受 WLAN 服务 IPC 约束，实测而非宣称，并提供 benchmark(iterations) 方法在运行机器上测量每秒扫描次数、平均 BSSID 数与所用后端；
• 原生不可用（非 Windows 或 WLAN 服务报错）时透明回退到 Tier 1 netsh，调用方在 Windows 上总能拿到结果；仅当不存在任何后端时才返回类型化 WifiScanError::Unsupported；
• ScanMetrics 累计扫描次数、总观测 BSSID 数、最近扫描耗时、估算速率与 native_scans 计数，方便调用方验证原生路径确实生效；
• wlanapi 特性下通过 tokio::task::spawn_blocking 提供 scan_async()。

7.3 跨平台适配器

• macOS（ADR-025）：MacosCoreWlanScanner 调用 CoreWLAN Swift 辅助程序，parse_macos_scan_output() 解析输出，#[cfg(target_os = "macos")] 门控；
• Linux：linux_scanner.rs 执行 iw dev <iface> scan（需 CAP_NET_ADMIN，通常 root），或用 scan dump 读取缓存结果以规避 root 权限（可能返回陈旧数据）；with_interface() 指定接口名（如 wlan0、wlp2s0）。

7.4 错误类型体系

error.rs 的 WifiScanError 覆盖完整错误面：MAC 无效/解析失败、扫描失败、BSSID 数量不足（InsufficientBssids）、注册表未找到、子载波映射已满、RSSI 越界（期望 [-120, 0]）、操作不支持、子进程/解析错误。所有变体实现 Display 与 std::error::Error，便于 ? 传播与日志记录。

八、WindowsWifiPipeline：8 阶段感知管道

pipeline/orchestrator.rs 中的 WindowsWifiPipeline 是 ADR-022 3.2 节描述的领域服务，把 7 个阶段组件编排为一次 process(&MultiApFrame) -> EnhancedSensingResult 调用：

阶段	组件	职责
1	PredictiveGate	EMA 残差门控，抑制无人体交互的静态 BSSID；静态环境直接返回空结果
2	AttentionWeighter	softmax 点积注意力，学习环境中最"身体敏感"的 BSSID
3	BssidCorrelator	跨 BSSID Pearson 相关与聚类，识别受同一人体影响的 BSSID 簇
4	MultiApMotionEstimator	加权方差 + EMA 运动估计
5	CoarseBreathingExtractor	带通滤波（呼吸频带）+ 过零检测；仅在运动等级 Minimal 时启用
6	QualityGate	ruQu 三过滤器（结构/漂移/证据），产出 Permit/Warn/Deny 判定
7	FingerprintMatcher	ModernHopfield 模板匹配（余弦相似度），姿态分类
8	WindowsWifiPipeline	编排以上全部阶段

8.1 PipelineConfig 默认参数

参数	默认值	说明
max_bssids	32	BSSID 槽位上限
gate_threshold	0.05	阶段1 残差门控阈值
correlation_window	30	阶段3 相关窗口（帧数）
correlation_threshold	0.7	共变分类相关阈值
min_bssids	3	有效帧所需最少 BSSID 数
enable_breathing	true	是否启用阶段5
enable_fingerprint	true	是否启用阶段7
sample_rate	2.0	采样率（Hz），喂给呼吸提取器

process() 的完整调用链：帧先检查 min_bssids（不足则返回 verdict: Deny 的空结果）；首帧且启用指纹时用当前幅度初始化默认模板；随后依次执行门控 → 注意力 → 相关 → 运动 → 呼吸 → 质量门 → 指纹分类。身体敏感 BSSID 定义为注意力权重超过均值 1.5 倍的条目，其数量被计入呼吸估算的 bssid_count。

8.2 附加 API

• store_fingerprint(pattern, label)：注册参考姿态指纹模板（维度须匹配 max_bssids）；
• reset()：重置全部管道状态（门控/相关/运动/呼吸/质量/指纹）；
• frame_count()：已处理帧计数；
• 内嵌吞吐基准测试断言管道处理速度 >100 帧/秒（10,000 帧基准用例）。

九、EnhancedSensingResult：感知输出契约

result.rs 定义了管道的输出值对象：

9.1 MotionLevel 分级阈值

MotionLevel::from_score(score) 将归一化运动评分 [0.0, 1.0] 映射为粗粒度等级（阈值可在 PipelineConfig 覆盖）：

评分区间	等级	含义
< 0.05	None	无显著方差变化，房间可能为空
< 0.20	Minimal	静止人员（呼吸、轻微动作）
< 0.60	Moderate	慢速移动（行走、手势）
≥ 0.60	High	剧烈/快速运动

9.2 其余字段语义

• MotionEstimate { score, level, contributing_bssids }：量化运动估计；
• BreathingEstimate { rate_bpm, confidence, bssid_count }：成人静息呼吸 12-20 BPM，仅当运动为 Minimal 且 ≥3 个身体相关 BSSID 时有效——Tier 1 约 2Hz 的低采样率限制了其精度（文档明确声明）；
• PostureClass { Empty, Standing, Sitting, LyingDown, Walking, Unknown }：基于 Hopfield 模板匹配的姿态分类；
• SignalQuality { score, bssid_count, spectral_gap, mean_rssi_dbm }：spectral_gap 来自 BSSID 相关图谱，大间隙表示良好信号分离；
• Verdict { Permit, Warn, Deny }：质量门最终判定（ruQu 三过滤器：结构完整性、统计漂移显著性、证据累积）。

十、依赖生态与后续阅读

本 crate 在 v2 Rust 工作区（Rust 1.85+）中的定位及关联 crate（见 v2/crates/README.md）：

Crate	角色
wifi-densepose-signal	高级 CSI 信号处理（SpotFi、FarSense、Widar 3.0 等 6 种算法）
wifi-densepose-vitals	CSI 生命体征提取（呼吸 6-30 BPM、心率 40-120 BPM）
wifi-densepose-hardware	ESP32 等硬件接口
wifi-densepose-mat	基于多 AP 数据的灾害检测

MultiApFrame 与 EnhancedSensingResult 被设计为与 ESP32 路径共用同一套 SensingUpdate/Esp32Frame 消息契约（见 ADR-022 的 Sensing Output 有界上下文），因此下游 UI 与存储层无需区分信号来源。

十一、构建与测试

在仓库根目录运行（工作区成员 crate）：

cargo build -p wifi-densepose-wifiscan
cargo test  -p wifi-densepose-wifiscan        # 运行全部领域/适配器/管道测试
cargo build -p wifi-densepose-wifiscan --features wlanapi   # 启用 Tier 2 异步

测试覆盖了 BSSID 解析的全部边界（空输出、本地化消息、隐藏 SSID、Unicode SSID、CRLF、三频段、默认值回退、畸形行）与管道行为（帧数递增、静态信号被门控、重置清空状态、吞吐基准）。注意：NetshBssidScanner::scan_sync() 与 WlanApiScanner 原生路径依赖真实 Windows 环境，非 Windows 平台请使用 parse_netsh_output() 配合样例文本进行解析验证。

十二、许可证

MIT OR Apache-2.0 双许可，与工作区其余 crate 一致。

结语

wifi-densepose-wifiscan 以严谨的 DDD 分层（值对象 → 聚合根 → 端口 → 适配器 → 领域服务）把"多 BSSID 扫描"这一朴素事实转化为可复用的感知基础设施：Welford 在线统计让逐 BSSID 方差成为运动/存在检测的廉价特征，子载波映射让 RSSI 扫描无缝接入伪 CSI 管道，三级平台适配器则保证了从 Windows 到 macOS/Linux 的平滑迁移。无论是接入 Wi-Fi 人体感知应用，还是借鉴其"端口-适配器 + 无 unsafe 隔离"的工程实践，这个 crate 都是值得研读的参考实现。