RuView 部署配置完全指南：从 sdkconfig 到 Cognitum Seed 的逐层调优实战

本文是 RuView 仓库中 ruview-configure 技能文档（plugins/ruview/skills/ruview-configure/SKILL.md）的系统性展开。RuView 将普通 WiFi 信号转化为实时空间智能、生命体征监测与存在检测，而本文聚焦「不改一行代码、只靠配置即可改变整套已部署系统行为」的核心能力：从固件构建期的 sdkconfig 变体，到运行期的 NVS 参数注入（channel/MAC 覆盖、TDM 组网、边缘智能分级），再到 Rust 侧 sensing server 的训练/推理/索引命令、多节点 mesh 与 Cognitum Seed 记忆集成。读完本文，你将掌握一条完整的「provision.py 单行参数 → 全屋多节点感知网格」配置链路，并理解每一层参数在源码中的落地位置与默认值语义。

1. 固件构建期配置：sdkconfig 变体切换

RuView 的 ESP32 固件把「烧进 Flash 就不可再改」的构建级选项放在 sdkconfig 变体文件中，位于 firmware/esp32-csi-node/ 目录。不同板型与 Flash 容量对应不同变体，SKILL.md 给出的三档基准如下：

变体	文件	适用场景
8MB（默认）	firmware/esp32-csi-node/sdkconfig.defaults.template	ESP32-S3 8MB，完整功能集，真实 WiFi CSI
4MB	firmware/esp32-csi-node/sdkconfig.defaults.4mb	ESP32-S3 SuperMini 4MB——禁用显示，双 OTA 槽位（partitions_4mb.csv，每槽约 1.856 MB）
Heltec N16R2	随固件目录分发的 Heltec 板型配置	Heltec 系列板卡

以仓库当前实际内容为准，firmware/esp32-csi-node/ 下现存的可切换变体还包括 sdkconfig.defaults.devkitc、sdkconfig.defaults.esp32c6、sdkconfig.defaults.s3-fair、sdkconfig.defaults.8mb_backup，以及用于 CI/仿真的 sdkconfig.qemu、sdkconfig.coverage；实际分支/发行版本可能额外携带 SKILL.md 中提及的 Heltec 专用文件。

切换方式：将目标变体复制为活动配置后重建固件：

cp firmware/esp32-csi-node/sdkconfig.defaults.<variant> firmware/esp32-csi-node/sdkconfig.defaults
# 然后按 ruview-hardware-setup 流程重新编译烧录

4MB 变体文件头部给出了两种等价构建方式（见 sdkconfig.defaults.4mb）：

cp sdkconfig.defaults.4mb sdkconfig.defaults && idf.py set-target esp32s3 && idf.py build
# 或
idf.py -D SDKCONFIG_DEFAULTS="sdkconfig.defaults.4mb" set-target esp32s3 && idf.py build

1.1 关键构建期选项的源码语义

以 8MB 默认模板 sdkconfig.defaults.template 为例，几个直接影响系统行为的选项：

• CONFIG_ESP_WIFI_CSI_ENABLED=y——WiFi 驱动层启用 CSI（Channel State Information）采集，这是整套感知能力的地基；
• CONFIG_PARTITION_TABLE_CUSTOM=y + CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions_display.csv"——8MB 版使用带显示与 OTA 的自定义分区表（ADR-045）；
• CONFIG_ESPTOOLPY_FLASHSIZE_8MB=y——8MB Quad SPI Flash；
• CONFIG_ESP_MAIN_TASK_STACK_SIZE=8192、CONFIG_FREERTOS_TIMER_TASK_STACK_DEPTH=8192——加大主任务与 FreeRTOS 定时器任务栈。模板注释明确写道：ADR-081 中 adaptive_controller 在 Timer Svc 回调内执行 emit_feature_state 与 stream_sender 的网络 I/O，超过默认 2 KiB 栈深，必须扩容；
• NVS 加密默认关闭（CONFIG_NVS_ENCRYPTION 未设置），仅在向 eFuse 烧写 HMAC 密钥后启用。

4MB 变体则通过 CONFIG_DISPLAY_ENABLE 未设置来禁用显示以节省 Flash，并把分区表切到 partitions_4mb.csv。

⚠️ 实践警告（来自 SKILL.md）：切换构建配置后严禁在 mock 模式下测试——Kconfig fall-threshold 的缺陷只在真实 CSI 数据流下才会暴露，仿真会掩盖此类问题。

2. 运行期设备配置：provision.py 与 NVS 命名空间

运行期配置由 firmware/esp32-csi-node/provision.py 完成：它通过串口把 csi_cfg NVS 命名空间写入设备，让同一份预编译固件无需重编译即可适配不同 WiFi 网络与聚合端。SKILL.md 强调「以 --help 输出为权威依据」：

python firmware/esp32-csi-node/provision.py --help
# Windows 下强制 UTF-8 输出（帮助文本含非 ASCII 字符，cp1252 下会崩溃）：
#  set PYTHONUTF8=1 PYTHONIOENCODING=utf-8

依赖为 pip install 'esptool>=5.0' nvs-partition-gen（或使用 ESP-IDF 自带的 nvs_partition_gen.py）。

2.1 最小可用示例

python firmware/esp32-csi-node/provision.py --port COM8 \
  --ssid "WiFi" --password "secret" \
  --target-ip 192.168.1.20 --target-port 5005 \   # 聚合端 UDP 接收端口（默认 5005）
  --node-id 1 \                                   # 节点 ID，范围 0-255
  --channel 6 --filter-mac AA:BB:CC:DD:EE:FF       # ADR-060：固定信道 + 过滤发射端 MAC

2.2 参数族全表（继承自 SKILL.md 并对照源码核实）

参数族	Flags	说明
WiFi / 汇聚端	--ssid --password --target-ip --target-port(5005) --node-id	--node-id 取值 0-255
TDM 组网	--tdm-slot --tdm-total	0 起始的槽位索引 + 节点总数，多节点 mesh 的时隙划分依据
边缘处理	--edge-tier {0,1,2}	0=关闭，1=统计，2=生命体征（ADR-041 边缘智能）
检测阈值	--pres-thresh(50) --fall-thresh(15000 → 15.0 rad/s²)	高人流区域调高 --fall-thresh 可降低跌倒误报（issue #263）
生命体征	--vital-win(300 帧) --vital-int(1000 ms) --subk-count(32，Top-K 子载波)	相位历史窗口 / 数据包间隔 / 子载波数
信道与跳频	--channel(1-14 / 36-177，覆盖 AP 自动探测) --filter-mac --hop-channels(1,6,11) --hop-dwell(200 ms)	省略 --channel 并设置 --hop-channels 即启用 ADR-073 多频跳频；省略 --filter-mac 则接收所有发射端
Cognitum Seed	--seed-url(http://10.1.10.236) --seed-token(Bearer，来自配对) --zone(lobby)	持久化 RVF 记忆 / kNN / 见证链接入
Swarm 桥接	--swarm-hb(30 s) --swarm-ingest(5 s)	心跳间隔 + 向量摄取间隔
模式	--dry-run(生成 NVS bin 不烧录) --baud(460800) --force-partial	其余见 2.4 节

2.3 参数在源码中的落地位置

对照 provision.py 的 build_nvs_csv()（约 L177-L237），每个 CLI 参数都映射为 csi_cfg 命名空间下的一个 NVS 键，且编码类型明确：

• --ssid/--password/--target-ip → string；--target-port → u16；--node-id/--tdm-slot/--tdm-total/--edge-tier/--subk-count → u8；
• --pres-thresh/--fall-thresh/--vital-win/--vital-int/--swarm-hb/--swarm-ingest → u16；
• --channel → csi_channel（u8）；--filter-mac → 6 字节 blob（hex2bin）；--hop-channels → hop_count（u8）+ chan_list（uint8 blob）+ dwell_ms（u32，来自 --hop-dwell）；
• --seed-url/--seed-token/--zone → string（zone_name）。

输入校验同样发生在脚本内（main 中约 L421-L441）：--tdm-slot 与 --tdm-total 必须成对出现且 slot < total；--channel 必须是 1-14（2.4GHz）或 36-177（5GHz）；--filter-mac 必须是 6 组合法十六进制字节。固件侧，ADR-060 规定：csi_collector_init() 在 WiFi 连接后通过 esp_wifi_sta_get_ap_info() 自动探测 AP 信道作为默认 CSI 信道，仅当 NVS 存在 csi_channel 覆盖时才改用固定值；CSI 回调中若 filter_mac_set 为真，则丢弃与配置 MAC 不匹配的帧（详见 docs/adr/ADR-060-provision-channel-mac-filter.md）。

2.4 重要行为：NVS 命名空间整体替换 vs 增量合并

⚠️ SKILL.md 明确警告：烧录会重写整个 csi_cfg 命名空间——凡是不在命令行传入的键都会被抹掉（issue #391）。必须每次传全量参数，或明知后果地使用 --force-partial；不确定时先从串口启动日志读取设备当前值（adaptive_ctrl / csi_collector 行）。

不过，仓库源码显示 provision.py 已进化出更友好的语义：按端口增量合并（additive-by-default）。脚本 docstring（provision.py）说明：每次调用会先读取本机为同一串口保存的 JSON 状态文件（默认位于用户配置目录下 wifi-densepose/esp32-provision-state/<port>.json），将新 CLI 参数叠加其上，生成并烧录合并后的 NVS，再把合并结果写回状态文件。相关实用参数：

• --reset：先清空本机该串口的状态文件再合并，适合对二手板卡做首次全量配置；
• --state：只打印本次「即将烧录」的合并结果并退出，用于调试哪些键会落到设备上；
• --state-dir：覆盖状态文件目录；
• --dry-run：生成 nvs_provision.bin 不烧录，并同样持久化合并状态，之后可手动 python -m esptool --chip <chip> --port <port> write_flash 0x9000 nvs_provision.bin。

局限也很明确：状态存在于控制机本地，若换一台机器配置同一设备，会从空状态开始——此时需在该次调用中传入希望保留的键，或预置状态文件（设备侧 NVS 回读合并已在 issue #574 跟踪）。

2.5 批量舰队配置：generate_nvs_matrix.py

面向多节点舰队与 QEMU 固件测试矩阵（ADR-061），scripts/generate_nvs_matrix.py 可一次性产出多份 NVS 镜像。其实现刻意采用 subprocess 优先调用 esp_idf_nvs_partition_gen / nvs_partition_gen 模块，再回退到 ESP-IDF 内置脚本——因为该 API 在不同版本间变动频繁。常用参数：

python scripts/generate_nvs_matrix.py --list            # 列出全部预置配置
python scripts/generate_nvs_matrix.py --output-dir out/ --only node_a,node_b
python scripts/generate_nvs_matrix.py --output-dir out/ --csv-only   # 只出 CSV 便于审查

default 配置表示不写 NVS（走 Kconfig 默认值），产出全 0xFF 的空白分区镜像。

3. Sensing Server 运行参数（Rust，v2 工作区）

核心服务是 wifi-densepose-sensing-server crate，运行时参数由 v2/crates/wifi-densepose-sensing-server/src/cli.rs 定义。SKILL.md 给出的常见模式：

cd v2
cargo run -p wifi-densepose-sensing-server -- --help

# 常见模式：
cargo run -p wifi-densepose-sensing-server                                  # 实时接收，默认端口
cargo run -p wifi-densepose-sensing-server -- --pretrain --dataset data/csi/ --pretrain-epochs 50
cargo run -p wifi-densepose-sensing-server -- --train --dataset data/mmfi/ --epochs 100 --save-rvf model.rvf
cargo run -p wifi-densepose-sensing-server -- --model model.rvf --embed
cargo run -p wifi-densepose-sensing-server -- --model model.rvf --build-index env

对照 cli.rs 源码，这些 flag 的默认值与类型如下：

• --udp-port：ESP32 CSI 帧的 UDP 接收端口，默认 5005（与 2.2 节的 --target-port 默认值一致，构成端到端链路）；
• --ui-path：UI 静态文件路径，默认 ../ui；
• --tick-mm/--tick_ms：动画帧间隔 100 ms（约 10 fps 平滑姿态动画）；
• --bind-addr：默认 127.0.0.1，设为 0.0.0.0 暴露到网络，支持 SENSING_BIND_ADDR 环境变量；
• --source：auto / wifi / esp32 / simulate，默认 auto；
• --pretrain + --pretrain-epochs（默认 50）：ADR-024 的自监督对比预训练；
• --train + --dataset + --dataset-type（默认 mmfi，可选 wipose）+ --epochs（默认 100）+ --save-rvf：训练并在退出时导出 RVF 容器；
• --model <path.rvf> + --embed：加载模型提取 CSI 嵌入；--build-index <TYPE>：按 env/activity/temporal/person 构建指纹索引；
• --load-rvf：启动时加载 RVF 容器；--export-rvf：仅导出打包后退出；
• --calibrate：启动即执行现场模型标定（需空房间）；--node-positions：多站融合的节点坐标（x,y,z;x,y,z;...，支持 SENSING_NODE_POSITIONS 环境变量）；
• MQTT 发布器（ADR-115 家居集成）：--mqtt（RUVIEW_MQTT）、--mqtt-host（默认 localhost）、--mqtt-prefix（默认 homeassistant，启用 HA 自动发现）等。

wifiscan 多 BSSID 模式（ADR-022）：同一服务可消费 wifi-densepose-wifiscan crate（v2/crates/wifi-densepose-wifiscan/）的输出，把邻近 AP 当作免费雷达照明源，在无需额外硬件的场景下提升感知覆盖。

4. 边缘智能模块（ADR-041）

SKILL.md 指出：边缘智能是「跑在 ESP32 本机上的小型 Rust/WASM 程序」——无网络、即时响应。每个模块声明其 CSI 特征输入（8 维特征向量）与 RVF 存储目标（Cognitum Seed）；构建期通过固件组件配置决定哪些模块随固件烧入，运行期通过 NVS 键调节各模块阈值。

从 docs/edge-modules/README.md 可以确认模块生态规模与构建方式：共 65 个 WASM 模块、632 个测试，覆盖核心、医疗健康、安防、智慧建筑、零售、工业、信号情报、自适应学习、时空、AI 安全、量子与自主等类别；模块由 v2/crates/wifi-densepose-wasm-edge 编译（cargo build --target wasm32-unknown-unknown --release）。

宿主机镜像脚本是调参利器——它们把边缘模块逻辑用 JS 复刻在宿主机运行，烧录前即可微调阈值。SKILL.md 列出的脚本位于 scripts/：apnea-detector.js、gait-analyzer.js、material-classifier.js、passive-radar.js、mincut-person-counter.js、device-fingerprint.js、mesh-graph-transformer.js、material-detector.js。以 scripts/apnea-detector.js 为例，其 CLI 参数（--apnea-threshold 默认 3.0、--hypopnea-drop 默认 50% 基线下降、--min-duration）与设备端 NVS 阈值一一对应，可先在宿主上对录制的 CSI 流验证判定逻辑，再烧写固件。

5. 多节点 Mesh 组网

SKILL.md 给出的组网要点：

• 2 个以上节点才能产生真正的空间分辨率，所有节点 provision 到同一个 --target-ip 汇聚端；
• TDM 协议 + 信道跳频由 wifi-densepose-hardware crate 协调，实现位于 v2/crates/wifi-densepose-hardware/src/esp32/；
• 跨视角融合见 ruview-advanced-sensing 技能（plugins/ruview/skills/ruview-advanced-sensing/）。

对应到 2.2 节参数表：--tdm-slot/--tdm-total 决定节点在时隙轮转中的位置；--hop-channels/--hop-dwell 决定多频扫描（ADR-073）；配合 --node-id 与统一 sink，多节点即可协同出空间感知。QEMU 下的 mesh 验证流程与配置矩阵见 docs/adr/ADR-061-qemu-esp32s3-firmware-testing.md。

6. Cognitum Seed 集成

Seed 集成让 ESP32 采集的 CSI 流向持久化的空间记忆：桥接层把 CSI 转发给 Cognitum Seed，获得 RVF 持久记忆、跨环境 kNN 检索与 Ed25519 见证链（SKILL.md 注明整机 BOM 约 $140）。SKILL.md 给出的两条直接可用的命令：

node scripts/rf-scan.js --port 5006              # 实时 RF 房间扫描 → Seed
node scripts/snn-csi-processor.js --port 5006    # SNN 实时学习（on-Seed）

接入层配置即 2.2 节参数族中的 --seed-url / --seed-token / --zone：节点把自身归属的 zone 与配对令牌写入 NVS，此后心跳（--swarm-hb，默认 30 s）与向量摄取（--swarm-ingest，默认 5 s）按周期向 Seed 上报。完整预训练流程见 docs/tutorials/cognitum-seed-pretraining.md，能力审计与见证验证见 docs/adr/ADR-028-esp32-capability-audit.md。

7. 应用层配置：API、Docker 与 Dashboard

• API：wifi-densepose-api（Axum）承载 HTTP/WS，其配置经 wifi-densepose-config crate 统一管理；v1 的 Python 服务配置入口为根目录 example.env 与 pyproject.toml（环境变量覆盖优先）；
• Docker：docker run -p 3000:3000 ruvnet/wifi-densepose:latest，环境变量覆盖方式记录在 README.md 与 docker/ 目录；
• Dashboard：Web 仪表盘默认由 sensing server 在 :3000 提供；nvsim 量子传感仿真仪表盘（ADR-092）是独立服务，勿混淆。

8. 参考与延伸阅读

SKILL.md 的 Reference 部分指向仓库核心资料，均已按仓库根路径整理：

• 决策记录：docs/adr/（90+ 篇 ADR）——重点 ADR-022（wifiscan）、ADR-028（能力审计）、ADR-041（边缘模块）、ADR-060（信道/MAC 覆盖）、ADR-061（QEMU + mesh）、ADR-081（自适应 CSI mesh 内核）；
• 固件源码：firmware/esp32-csi-node/——provision 脚本、sdkconfig 变体与分区表均在目录内；
• 服务端源码：v2/crates/wifi-densepose-sensing-server/src/cli.rs；
• 配套技能：plugins/ruview/skills/ 下的 ruview-hardware-setup（烧录构建）、ruview-advanced-sensing（跨视角融合）、ruview-model-training（训练流程）；
• 环境与构建：example.env、Makefile 与根目录 CLAUDE.md（crate 地图、构建环境、QEMU CI 修复说明）。

配置决策速查：改固件行为 → 切 sdkconfig 变体重编译；改单节点运行参数 → provision.py（注意按端口增量合并与全量覆盖两种语义）；改服务端行为 → sensing server CLI/env；要本机即时智能 → 配置边缘 WASM 模块；要空间分辨率 → 多节点 TDM mesh；要长期记忆与多环境检索 → 接入 Cognitum Seed。逐层配置、逐层验证，即可在零代码改动下把一个单节点感知设备演进为完整的多节点空间智能网格。