RuView cog-ha-matter 全解析把 Home Assistant Matter 集成打包成 Cognitum Seed 可安装 CogADR-116【免费下载链接】RuViewπ 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 架构决策ADR-116cog-ha-matter的技术全景解读。RuView 用普通 WiFi 信号做空间智能、生命体征监测与人员存在检测不依赖任何摄像头像素而本文聚焦其中一层关键交付形态如何把 ADR-115 已经实现的 Home Assistant Matter MQTT 集成从聚合器上的一个--mqtt启动开关升级为Cognitum Seed 生态里可一键安装、可签名分发、带防篡改审计见证链的一等公民 cog。读完你会掌握cog 与 flag 两种形态的取舍、crate 的真实 CLI 与 mDNS TXT 契约、SHA-256 Ed25519 见证链的实现与安全加固细节、基于 Makefile 的构建/签名/发布流水线以及 Matter/HACS/监管等八项研究结论如何影响 v1 功能范围与分阶段落地计划。核心结论先说这是一个Proposed提案状态但已实质落地大部分脚手架的 ADR——研究档案 P1 完成crate 脚手架P2编译与测试通过P3 已完成对 ADR-115 发布者的薄封装接线P4 的 mDNS 通告与 Ed25519 见证链部分已经进入 crate 并配有大量单元测试。文中所有实现细节均可在仓库对应源码中核实。1. 背景与动机为什么需要一个 cog而不是保留开关就够了1.1 现有能力的边界RuView 的 Home Assistant Matter 集成最初由 ADR-115home-assistant-integration 以--mqttflag 形式落在wifi-densepose-sensing-server上这是一个运行在 Pi / Linux 主机上的 Rust 二进制消费来自 ESP32 传感器舰队的 UDP 帧然后向任意 Home Assistant 安装发布 MQTT 消息供其自动发现。它工作的前提是用户自己会去安装并运行这个 sensing-server 二进制。也就是说HAMatter 当时是聚合器的一种配置而不是用户能随手丢进现有舰队的可安装制品。1.2 填补的空白Cognitum Seed cog 目录Cognitum Seed 本身已经有一个 cog 目录生态——打包好的 Seed 应用cog-pose-estimation、cog-quantum-vitals、cog-person-matching等任何人可以从app-registry.json安装。但这 100 多个 cog 里没有cog-ha-matter这正是 ADR-116 要关闭的缺口。打包先例是 ADR-101cog-pose-estimation在 GCS 上发布签名的 aarch64 x86_64 二进制并附带权重 blob——HA cog 期望复用同一形态。1.3 决策对比flag 与 cog 的差异ADR-116 §1.1 给出了一张非常清晰的对比表决定了本 ADR 的走向维度--mqttflagsensing-servercog-ha-matterSeed cog分发手动安装 Rust 二进制app-registry.json列表一键安装发现无mDNS / cog 浏览器更新手动经 cog 运行时的 OTA见证无Ed25519 见证链本地 AI外部本地 ruvllm RuVector1.4 本 ADR不是什么边界声明不弃用--mqttflag该 flag 继续服务没有 Seed 的 Pi / Linux 部署cog 是 Seed 原生选项二者并存。不移植 HA-MIND / HA-DISCO 逻辑到另一种语言Rust crate 已存在cog 是把它包装成可安装制品并叠加 Seed 特有表面见证、RuVector、ruvllm 驱动的阈值。不发布 Matter SDKADR-115 §9.10 已把 matter-rs SDK 接线推迟到 v0.7.1本 ADR 延续该推迟聚焦 cog 打包与一等 Seed 集成Matter Bridge 模式在 SDK 就绪后于 v0.8 交付。2. 决策核心cog-ha-matter 的四个技术表面决策是构建cog-ha-matter由四个技术面组成。其中实体面与 ADR-115 完全一致以保证 HA 侧行为同构其余三个是 Seed 原生增强。2.1 核心实体面与 ADR-115 一致21 实体/节点cog 会通过 MQTT auto-discovery 重新发布每节点 21 个实体11 个原始测量 10 个语义原语这样无论状态源是 Seed cog 还是外部 sensing-serverHome Assistant 安装看到的行为完全一致。仓库内 cog/app-registry-entry.json 的描述也印证了这条语义Adds 10 semantic primitivessomeone_sleeping, possible_distress, fall_risk_elevated, ...on top of the 11 raw measurements。2.2 Seed 原生增强面ADR-116 §2.2 列出五点其中已部分落地、部分推迟到 v0.7/v0.8自包含 MQTT broker可选v0.7 推迟——用户没跑 mosquitto 时 cog 可在cognitum-seed.local:1883内嵌 broker 直接充当 HA 端点。v1 范围表把它排在末尾增加约 2 MB 二进制 ACL 配置面而大多数 HA 安装自带 broker故 v0.7 交付。crate 常量 lib.rs 中的DEFAULT_EMBEDDED_BROKER_PORT 1883与 main.rs 的--mqtt-port默认值即为该端口的占位。mDNS 服务通告——_ruview-ha._tcp让 HA 的 discovery 集成免配置找到 Seed。这一半已在 P4 落地为真实代码见 §5。RuVector 支撑的语义原语阈值——用 SONA 适配的 RuVector 模型替代静态semantic-thresholds.yaml按户学习阈值匹配 Seed 的本地优先 AI 叙事。状态为 pending。Ed25519 见证链——每个状态迁移用 Seed 签名记录供养老/监管部署审计。这一半已在 P4 落地见 §6。OTA 固件协调——cog 管理网格内 ESP32-C6 节点的固件升级依托 ADR-110 substrate。规划中。2.3 Matter 维度依赖研究结论决策暂缓Matter Bridge vs Matter Device、Seed 的 ESP32-S3 上跑 Thread Border Router 的可行性、CSA 认证路径、哪些 Matter 设备类映射哪些实体——这四问交给研究档案结论落在 §3cog 的 Matter 功能集随之暂缓确定。2.4 多 Seed 联邦相邻房间多个 Seed 通过三层机制协同ESP-NOW meshADR-110 substrate做时间对齐mDNS做服务发现见证链复制做跨 Seed 事件溯源。要点是ADR-110 提供了≤100 µs 的跨板时间同步本 ADR 用它做两件事——跨 Seed 事件去重一次跌倒只发一条告警和多房间轨迹重建一名住户房间 A → 走廊 → 房间 B。联邦模型是 ADR-110 mesh substrate 在应用层的自然延伸。3. 八项研究结论Matter / Thread / HACS / 认证 / 监管的取舍依据ADR-116 §3 引用完整档案 docs/research/ADR-116-ha-matter-cog-research.md。该档案共 8 章、30 引文、给出 v1 范围排序。八个研究问题的结论如下Matter Bridge vs Matter RootCommissionerMatter 1.4 在 cluster0x0406revision 5上引入了带RFSensing特性位的OccupancySensor (0x0107)设备类——这正是 WiFi-CSI 感知的正确设备类Matter 1.4.2 没有也不会有 health/vitals cluster。Seed 充当 Bridge含 N 个动态 OccupancySensor 端点而非 Commissioner——C6 感知节点只有 320 KB SRAM 且无 PSRAM无法承担 commission 角色只做 Accessory。Thread Border RouterESP32-C6 单芯片 TBR 已被社区验证可行唯一的配置步骤是CONFIG_OPENTHREAD_BORDER_ROUTERy。ADR-110 的c6_timesync.c已经初始化了 802.15.4——TBR 只差一个 Kconfig 开关。真实价值HA 的 Improv 风格配网无需独立 Thread 边界路由器盒子。HACS 的价值增量config flowUI 配置向导、Repairs API结构化错误卡片、重新认证、诊断导出、类型化服务动作set_privacy_mode、calibrate_zone、i18n 翻译。Bronze 是最低门槛Goldrepairs diagnostics reconfiguration是目标从hacs.integration_blueprint模板起步。CSA 认证首年约 $30–42k约 $22.5k 会员年费 $10–19k ATL 实验室费用。v1 可跳过以 Works with HA 名义发布v0.9 拿到 HACS 采纳数据后再评估 CSA。Cog 资源预算Seed 设备上128 MB RAM / 15% CPUPi 5 Hailo-10 变体余量更大。10 KB 的 INT8 语义原语分类器无需 PSRAM。作为长生命周期监督进程capability scopes 为network.mqtt network.matter api.ruview_vitals。ruvllm RuVector 延迟ruvllm-esp32v0.3.3 证实 SONA 自适应在每次查询 100 µs内完成。8→10 的 INT8 分类器量化后约 10 KB。按户阈值调优通过 HA 点赞/踩反馈做 LoRA 式梯度步——不经过云端就能解决用户第一抱怨误报。HIPAA / FDAFDA 2026 年 1 月 General Wellness 指南明确将 HR/睡眠/活动异常告警归类为wellness 设备只要不做诊断性宣传即不在 FDA 管辖内。落地要点把跌倒检测表述为 **activity anomaly notification活动异常通知**而非跌倒诊断--privacy-modeaudit-only 层只发 SHA-256 摘要、不发 MQTT 状态构成技术性 PHI 屏障OccupancySensor (0x0107)设备类让产品停留在与智能人体传感器相同的监管类别。竞品护城河研究档案 §6 逐一对比了 Aqara FP300/FP2、TOMMY、ESPectre、Frigate、RoomMe。以档案的实体目录对比表为据RuView 的 HR/BR、17 关键点姿态、10 个语义原语、见证链、SONA 自适应在竞品中无对应能力——例如 Aqara FP3002025 年 11 月只有 5 个实体无人计数、无生命体征、无跌倒检测TOMMY 只有区域、无生命体征、闭源付费ESPectre 仅运动检测。需要强调的是上述第 8 条属于研究档案中对公开竞品的陈述性对比引用的是该档案 §6 的表格内容并非本仓库的实测性能结论。4. v1 范围按构建成本 × 用户影响排序ADR-116 §4 与档案 §8 的Recommended Scope一致把 v1 功能按优先级排列#功能成本影响阶段1--privacy-modeaudit-only 层不发 MQTT 状态、Seed 上只存 SHA-256 摘要约 1 周覆盖养老 / GDPR 部署P32Seed cog manifest Ed25519 签名 store 列表约 1–2 周实现一键分发P2 P83本地 SONA 微调闭环HA 反馈 → LoRA 梯度步约 2–3 周降低误报解决头号用户抱怨P54HACS gold 级集成config flow repairs diagnostics约 4–6 周为主流用户移除 MQTT 前置条件P9独立仓库5Matter BridgeOccupancySensor 动态端点约 6–8 周Apple Home / Google Home / Alexa 原生接入v0.8专项 sprint6cog 内嵌 MQTT brokerrumqttd约 1 周无需外部 broker但每套 HA 都有 mosquitto/内置v0.7 推迟约 2 MB 二进制 ACL 配置面4.1 实施阶段总表阶段范围状态P1研究档案8 节、30 引文、v1 范围已排序✅ 完成P2Cog crate 脚手架v2/crates/cog-ha-matter/Cargo.toml src/{lib,main,manifest}.rs、workspace 成员、CLI 参数、--print-manifest、2 个 manifest 单测✅ 完成cargo checkcargo test通过P3包装现有 ADR-115 MQTT 发布者为 cog 入口✅ wiring 完成main.rs经runtime::spawn_publisher启动publisher::spawn持有broadcast::SenderVitalsSnapshot等待 Ctrl-C无需 broker 的 live-handle 测试通过P3.5 待办订阅 sensing-server/v1/snapshotWS 并注入 channelP4Seed 原生增强mDNS、witness嵌入式 broker 推迟✅ shipped——mDNS 记录构建 ServiceInfo 转换 live responder 接入main.rs_ruview-ha._tcp即开即用--no-mdns供受限网络witness 为哈希链 JSONL 文件持久化 链级验证 Ed25519 签名P5RuVector 阈值学习SONA 自适应pendingP6多 Seed 联邦跨 Seed 去重 见证pendingP7Matter Bridge 模式依赖 matter-rs / esp-matter 就绪pendingP8Cog 签名 app-registry.json列表 Seed Store 条目pendingP9HACS 集成仓库HA 侧安装路径pendingP10Witness bundle CSA 风格规格合规检查pending5. 代码落地全景crate 结构与可运行 CLI5.1 模块布局crate 根目录为v2/crates/cog-ha-matter/源码模块划分如下文件职责src/main.rs二进制入口刻意保持精简便于 cog 运行时与测试直接调用库代码src/lib.rs常量与表面声明COG_ID、mDNS 服务类型、默认端口、六大增强面注释src/runtime.rs无副作用 builder把 CLI 转成 ADR-115publisher::spawn需要的输入mDNS responder 的 live handlesrc/mdns.rsmDNS 通告记录的纯 builder RFC 6763 TXT 契约src/manifest.rsCogManifest 的类型化视图与manifest.template.json对齐src/witness.rsSHA-256 哈希链原语含 canonical bytes 编码src/witness_signing.rsEd25519 签名层verify_strict caller-pinned keyCargo.toml依赖清单lib.rs定义的关键常量lib.rsCOG_ID ha-matter——Seed 的app-registry.json与 manifest 使用该 idMDNS_SERVICE_TYPE _ruview-ha._tcpDEFAULT_CONTROL_PORT 9180——cog 本地 HTTP 控制面/health、/api/v1/cog/status区别于 MQTT broker 端口DEFAULT_EMBEDDED_BROKER_PORT 1883——内嵌 broker 的默认端口。依赖上Cargo.tomlcog 直接依赖 ADR-115 的发布核心wifi-densepose-sensing-serverdefault-features falsefeatures [mqtt]、wifi-densepose-hardwareADR-110 substrate 桥接、sha2与ed25519-dalek见证链、mdns-sd 0.11纯 Rust zeroconf daemon。5.2 CLI 参数全表从 main.rs 与 app-registry-entry.json 的config块可以拿到完整、可运行的参数契约后者是 Seed 控制面生成配置表单的数据源两者必须保持一致参数类型默认值说明--sensing-urlstringhttp://127.0.0.1:3000本地 sensing-server 地址cog 从这里拉取VitalsSnapshot再经 MQTT/Matter 转发--mqtt-hoststring127.0.0.1MQTT broker 主机缺省时 cog 可在 1883 上起内嵌 rumqttdv1 仅外部 broker--mqtt-portinteger1883即DEFAULT_EMBEDDED_BROKER_PORTbroker 端口app-registry 中 min1, max65535--privacy-modebooleanfalse在线上剥离生物特征只发布语义原语。任何有非租户居住者的部署都应以它为默认--print-manifestbooleanfalse打印 cog 将向 Seed 控制面自报的 manifest 后退出供构建期签名器使用--mdns-hostnamestringcog-ha-matter.local.mDNS 主机名须以.local.结尾RFC 6762默认让 HA discovery 在 localhost 上也能发现 dev cog--mdns-ipv4string127.0.0.1LAN 可达 IPv4mDNS responder 通告它HA 据此回连 MQTT Matter Bridge--no-mdnsbooleanfalse跳过 mDNS responder。适用于容器化 CI组播 bind 被过滤或多 cog 实例同机场景5.3 启动流程main.rs 的接线顺序main.rs 的运行时接线可以概括为五步解析 CLIclap derive记录启动日志若--print-manifest以模板占位符构造CogManifestid、version、binary_url 带{{ARCH}}槽并打印后退出——该 manifest 在构建期由 Makefile 替换版本与架构后签名P3构造CogIdentity::default_for_build()node_id 取cog-ha-matter-{pid}保证同机多实例不抢 MQTT 会话调用runtime::build_publisher_inputs生成 MQTT 配置与 discovery 记录打开容量 256 的broadcast::channel::VitalsSnapshot再经runtime::spawn_publisher把 ADR-115 发布者作为 tokio 任务拉起P4非--no-mdns时构建 mDNS 服务并start_mdns_responder注册通告——失败只降级记 warn 并回退到手动 HA 配置不视为致命错误tokio::select!等待 Ctrl-C 或 publisher 任务意外退出_mdns_handle析构时会发出 mDNS goodbye 包让 HA 干净地看到服务下线。5.4 runtime 层的工程细节为什么这样做runtime.rs 是全 crate 最值得读的架构课文件其注释与测试直接记录了 ADR-115 集成测试的事后教训MQTTclient_id必须按进程唯一§Lessons复用 client_id 会导致 broker 踢掉上一会话、发布者陷入无限重连。cog 因此把client_id派生为ha-matter-{node_id}runtime.rs 的对应单测client_id_includes_node_id_for_session_uniqueness锁死该行为builder 保持纯函数、无 I/OmDNS responder / 控制面P4可以从不同来源Seed 控制配置、JSON POST构建同样的输入而无需经过 clapDEFAULT_STATE_CHANNEL_CAPACITY 256runtime.rs与 sensing-server 自身默认一致避免多 Seed 联邦 / mesh 重同步的突发负载下发布者成为瓶颈且有default_state_channel_capacity_is_reasonable测试防止回退via_device必须通告 cog 的id让设备在 HA 设备注册表中显示为 Seed 桥接下的设备对应 ADR-101/ADR-102 的每 cog 约定TLS 默认关闭v1 仅 LAN无公网 brokertls_defaults_to_off_for_v1_lan_only测试锁定该默认值v0.8 Matter Bridge 交付时再接线。6. mDNS 通告与 TXT 记录契约6.1 通告结构mdns 模块把通告什么纯数据 builder与如何通告responder分离MdnsService是 wire-format 双胞胎to_service_info是到mdns_sd::ServiceInfo的纯转换真正的组播 socket 由runtime::start_mdns_responder负责。这样响应库可以随时替换而通告内容、TXT 键位均由命名测试锁死——漂移会在测试期炸掉而不是静默破坏部署。6.2 TXT 记录契约RFC 6763HA 的 discovery 集成靠读 TXT 记录来把 manifest 绑定到某个homeassistant.integrationzeroconf 钩子。cog 发布的最小 TXT 集合如下见 mdns.rs 文档注释与build_mdns_serviceKeyValue用途cog_idha-matter与其它 RuView cog 区分cog_versionCARGO_PKG_VERSIONHA Repairs 据此提示升级node_ididentity 的 node idHA 设备注册表主键mqtt_portu16 字符串告诉 HA 到哪里连 cog 的 MQTT broker内嵌或外部privacy1/0为1时 HA config flow 默认把关生物特征实体protoruview-ha/1协议版本auto-discovery 有破坏性变更时递增三个值得注意的实现约束TXT 记录按键排序保证跨重建的字节级稳定RFC 6763 §6.4 虽然把顺序定义为实现相关但锁死顺序利于审计——txt_records_are_sorted_for_byte_stable_advertisement测试守护TXT 里不允许出现任何生物特征 / PIIhr_bpm、br_bpm、pose 坐标、ssid、经纬度、MAC、RSSI 都被禁止——因为 TXT 明文广播、被动扫描器可采集txt_carries_no_biometric_or_pii_keys测试把它们列为黑名单控制端口走服务记录SRV 的 port 字段 9180而 MQTT 端口走 TXT 记录二者不会被误换——control_port_field_holds_control_not_mqtt_port测试防止未来重构把 broker 端口错当成控制面端口通告。7. Ed25519 见证链实现、密码学细节与安全加固这是 P4 已 shipped 的另一半也是 ADR-262 P2 计划复用的签名链因此 ADR-116 §4.1 对它做了专门的 crypto/security review。7.1 为什么哈希链而非 Merkle 树witness 模块的注释给出了直白理由cog 以语义原语状态迁移的速率产事件——稳态下每分钟几个跌倒检测 / 房间迁移等事件期间几十个。这个速率下线性扫描完全够用Merkle 的 O(log n) 包含证明复杂度留给未来链跨度数天时的更高 tier。7.2 单事件结构每条见证事件WitnessEvent字段零基seq严格单调有空洞说明链被截断、prev_hash首条为GENESIS [0u8; 32]、Unix 秒时间戳调用方注入以便测试确定性、稳定的kind标签如fall_risk_elevated、bed_exit、privacy_mode_toggled、不透明payload字节典型为已发 MQTT 状态消息的 JSON供审计者反推 HA 被告知了什么、以及本事件哈希this_hash。7.3 canonical bytes 编码防拼接伪造的关键WitnessChain::append是唯一的变更入口哈希对象是确定性 canonical 字节格式为witness.rsDOMAIN_TAG | prev_hash[32] | seq:u64-be | ts:u64-be | kind_len:u32-be | kind | payload_len:u32-be | payload**长度前缀length-prefix**让(abc,def)与(ab,cdef)产生不同哈希——经典拼接伪造在编码层即被阻断有单测canonical_bytes_length_prefixing_prevents_ambiguity锁证定宽字段自定界域标签domain tagWITNESS_DOMAIN_TAG bcog-ha-matter/witness-event/v1\x00是 CHM-WIT-01 的修复产物见下带版本且以 NUL 结尾未来迁移Blake3、增字段、Merkle tier可 bump 标签而不是与 v1 bundle 静默碰撞。7.4 链级验证与 JSONL 持久化WitnessChain::verify()逐事件重算this_hash、核对prev_hash衔接、检查seq从 0 起无空洞返回 auditor 友好的WitnessVerifyErrorSeqGap/PrevHashMismatch/HashMismatchread_jsonl逐行解析from_jsonl_line先重验存储哈希篡改 bundle 直接触发WitnessParseError::HashMismatch而非悄悄加载伪造事件随后做端到端链验证错误都带 1-indexed 行号JSONL 字段序按字母序锁定kind, payload_hex, prev_hash, seq, this_hash, timestamp_unix_s保证审计者对整个 bundle 做归档哈希时不因重建字段重排而失效。7.5 签名层与安全审查结论签名层witness_signing.rs与哈希链分离理由哈希链可在不链接ed25519-dalek的情况下用于 wasm 浏览器端审计验证变体密钥轮换只作废签名、不作废链签名面小到一次能读完。sign_event签的正是witness::hash_event哈希的那份 canonical 字节——签名同时承诺整个事件kind/payload/ts/seq/prev_hash与链位置经prev_hash把已签名事件拼到另一条链上必然验签失败。verify_signature有两点刻意设计走verify_strict而非宽松verifyCHM-WIT-02 加固审计链上签名即证明因此必须拒绝非规范编码与小阶公钥RFC 8032 strict得到每事件唯一规范签名的性质。这不是防伪修复——验签密钥是调用方钉死的绝不从事件里读verify-before-trust key pinningverify_signature把验证公钥当参数传入read_jsonl会重推每个哈希并做链验证。ADR-116 §4.1 的审查结论以审查记录为据可以归纳为引擎 bug 类缺失良好结果附字节级证据此前审查过同类 sibling 引擎把操作者可影响的字符串做无框架首尾拼接后签名/哈希的 bug 类本 crate 中不存在——两个变长操作者可影响字段kind、payload均带长度前缀编码是单射的Ed25519 签名签的与 SHA-256 链提交的是同一份字节manifest 的binary_signature是构建期Makefile对单个定长binary_sha256十六进制值所做不在 crate 内CHM-WIT-01已修复——补域分离标签引擎修复方子本要求域标签 长度前缀原实现有长度前缀缺域标签。现加入带版本、NUL 结尾的WITNESS_DOMAIN_TAG使见证消息永远不会被重放为共享密钥设施的另一 Ed25519 上下文的消息尤其 manifest 签名。见证字节按设计变更旧磁盘哈希/签名作废验证过安全仓库内没有 crate 以编程方式消费 cog-ha-matter 见证字节CHM-WIT-02已加固——verify_signature用verify_strict确认干净附证据key 处理crate 从不生成/存储/记录/序列化签名私钥仅有文档化的测试专用固定种子生产密钥来自 Seed 安全存储、确定性定位字节、确定性 Ed25519、字母序锁定的 JSONL 字段序、排序 TXT 记录——无 HashMap/浮点不确定性进摘要、fail-closed 解析结构化错误无 panicmain.rs 不读不受信文件/路径。测试量佐证ADR 记录cog-ha-matter --no-default-features下测试数64 → 680 失败CHM-WIT-01 由witness.rs/witness_signing.rs中 4 个旧编码必失败测试钉住CHM-WIT-02 由 key-pinning 测试守护。8. 打包与发布流水线Makefile 驱动的 build / sign / uploadcog 打包目录 cog/ 有三个关键文件。manifest.template.json是带{{VERSION}}/{{ARCH}}槽位的构建期模板Makefile 镜像cog-pose-estimation/cog/Makefile使 Seed 运行时对两类 cog 一视同仁cognitum cog install ha-matter与cognitum cog install pose-estimation同构。8.1 目标一览Makefile 目标动作make build同时构建 aarch64aarch64-unknown-linux-gnu与 x86_64 两个 release 二进制并拷到dist/make sign为每个架构写.sha256旁车文件Ed25519 签名步骤标注为 TODO待COGNITUM_OWNER_SIGNING_KEY配置进 CImake uploadgsutil cp dist/* gs://cognitum-apps/cogs/{arm,x86_64}/make manifestcargo run -p cog-ha-matter --release -- --print-manifest输出 Seed 将记录的 manifestmake releasebuild sign upload manifest串起来的完整发布流水线make verify对每个架构核对sha256sum与旁车文件是否一致make clean清理dist/8.2 签名路径与清单契约Manifest 的类型化视图在 src/manifest.rs8 个必填字段字段语义id稳定 cog idha-matter会成为 Seed 上/var/lib/cognitum/apps/id/的目录名versionSemVer发布时由 Makefile 从cargo pkgid提取binary_urlSeed 拉取二进制的位置带{{ARCH}}槽arm/x86_64binary_bytes二进制字节数构建期wc -c后填入binary_sha256二进制 SHA-256小写十六进制、无0xSeed 在 exec() 前验证binary_signature对binary_sha256的 Ed25519 签名base64。未签名 dev 构建可为空app-registry.json所列 cog 必填installed_at安装时刻 Unix 时间戳Seed 在安装/升级成功后盖章statusinstalled/upgrading/degraded/removed之一crate 携带该类型化视图的原因manifest.rs 注释是让 cog 能向 Seed 控制面/api/v1/cog/status自报 manifest且构建期模板与运行时序列化器之间的格式漂移由命名测试触发——manifest_round_trip_matches_template即锁定 JSON wire 形态八个字段无多余。Seed 侧 install 校验按 ADR-100 契约执行。8.3 发布边界诚实标注值得注意的是Makefile 的sign目标目前对签名本身是 no-op——COGNITUM_OWNER_SIGNING_KEY的配置与cog-pose-estimation是同一条 TODO因此 dev cog 以未签名状态发布app-registry.json中以binary_signature: 列出。正式app-registry.json属于 cognitum-one 仓库而非本仓库见 cog/README.md 的 PR 说明。9. 研究档案补充Surface A/B/C 架构与前沿特性研究档案 §3 给出了 cog 的三种对外表面可用于理解同一份感知数据如何多渠道出口Surface A — MQTT bridge连接用户配置的 Mosquitto broker或 Seed 内部 broker把 Seedruview-vitals-worker端口 50054的遥测重发为 HA auto-discovery 消息复用 ADR-115 的 HA-DISCO 逻辑但作为 Seed 原生 cog 运行无需用户另跑 sensing-servercog 注册ha_mqttMCP 工具供其它 cog 的自动化调用Surface B — Matter bridge把 Seed 包装为 Matter Accessory Bridge一个 Fabric 节点 N 个动态端点每感知区一个。设备类映射存在 →OccupancySensor (0x0107)OccupancySensing (0x0406)RFSensing特性位 BooleanState (0x0045)跌倒 →ContactSensor (0x0015)事件源语义触发后 5 秒自复位人数 → Bridge 根端点上厂商自定义数值属性cluster0xFFF1_xxxx命名空间。Seed 的 AMOLED 屏直接显示 Matter 配网 QR 码Surface C — HA HACS 集成可选custom_components/wifi_densepose/Python 包直连 Seed REST API/api/v1/bearer token 来自 cognitum-agent承载 config flow、实体、repairs、diagnostics。档案 §3.3 明确了协议优先级MQTT 为一级、Matter 为二级——MQTT 到本地 HA 风险更低、路径更快无需 Matter SDK 链接、无需 CSA 认证、复用现成 HA-DISCO 逻辑Matter 直发要求 Seed 持有合法 Fabric 证书、管理运营凭据、处理 rekey开发与 QA 成本约 3–4 倍。这与 ADR-115 的双协议决策一致但现在原生在 cog 内。档案 §8 还列出若干前沿特性本 ADR §4 v1 范围表的依据来源多房间存在交接状态机消除鬼影占用、结合 HA 能耗实体做 energy disaggregationphantom_load_candidate、以及上文 §4 已覆盖的三档隐私模式none/semantic默认 /audit-only。10. 结合源码的验证路径怎么亲手确认本文结论本文所有实现性结论都能在当前仓库中复查读决策与档案ADR-116 全文 研究档案并回看上游 ADR-115MQTT publisher 与 21 实体、ADR-110C6 mesh / 时间同步 substrate、ADR-101 与 ADR-102cog 打包/注册先例核对 CLI 与常量main.rs 的 clap 参数与 app-registry-entry.json 的config键一致跑测试验证行为在v2/workspace 下对 crate 执行cargo test -p cog-ha-matter可复现 §5–§7 提到的命名测试client_id 唯一性、TXT PII 黑名单、canonical 编码单射性、链验证捕获篡改、签名 key-pinning 等——源码注释显示每个测试都对应一条真实事故或契约查看构建契约cog/Makefile 的 build/sign/upload/manifest 目标与 cog/README.md 的本地 dry-run 说明make build make sign make manifest。需要声明的前提与限制crate 仍处 P2–P4 实质交付阶段P5 起的 RuVector 阈值学习、P6 联邦、P7 Matter Bridge、P8 正式注册、P9 HACS 均为 pending嵌入式 broker 与 Matter Bridge 分别推迟至 v0.7 / v0.8签名密钥尚未配置进 CI当前 dev 构建未签名。结语ADR-116 是一个决策先行、脚手架紧随其后的典型范例它以一份 8 章研究档案回答了 Matter/HACS/认证/监管四个高风险问题把HAMatter 集成该长什么样收敛成一份可排序的 v1 范围随后在v2/crates/cog-ha-matter里把范围中的高优先项manifest 自报、--print-manifest、ADR-115 发布者包装、mDNS auto-discovery、Ed25519 见证链落成可编译、可测试、带完整安全审查记录的 Rust 代码。对希望理解感知能力如何以可安装制品形态进入智能家居生态的读者从 ADR-116 出发沿本文第 10 节的路径读源码是信息密度最高的一条路线。【免费下载链接】RuViewπ 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
RuView cog-ha-matter 全解析：把 Home Assistant + Matter 集成打包成 Cognitum Seed 可安装 Cog（ADR-116）
RuView cog-ha-matter 全解析把 Home Assistant Matter 集成打包成 Cognitum Seed 可安装 CogADR-116【免费下载链接】RuViewπ 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 架构决策ADR-116cog-ha-matter的技术全景解读。RuView 用普通 WiFi 信号做空间智能、生命体征监测与人员存在检测不依赖任何摄像头像素而本文聚焦其中一层关键交付形态如何把 ADR-115 已经实现的 Home Assistant Matter MQTT 集成从聚合器上的一个--mqtt启动开关升级为Cognitum Seed 生态里可一键安装、可签名分发、带防篡改审计见证链的一等公民 cog。读完你会掌握cog 与 flag 两种形态的取舍、crate 的真实 CLI 与 mDNS TXT 契约、SHA-256 Ed25519 见证链的实现与安全加固细节、基于 Makefile 的构建/签名/发布流水线以及 Matter/HACS/监管等八项研究结论如何影响 v1 功能范围与分阶段落地计划。核心结论先说这是一个Proposed提案状态但已实质落地大部分脚手架的 ADR——研究档案 P1 完成crate 脚手架P2编译与测试通过P3 已完成对 ADR-115 发布者的薄封装接线P4 的 mDNS 通告与 Ed25519 见证链部分已经进入 crate 并配有大量单元测试。文中所有实现细节均可在仓库对应源码中核实。1. 背景与动机为什么需要一个 cog而不是保留开关就够了1.1 现有能力的边界RuView 的 Home Assistant Matter 集成最初由 ADR-115home-assistant-integration 以--mqttflag 形式落在wifi-densepose-sensing-server上这是一个运行在 Pi / Linux 主机上的 Rust 二进制消费来自 ESP32 传感器舰队的 UDP 帧然后向任意 Home Assistant 安装发布 MQTT 消息供其自动发现。它工作的前提是用户自己会去安装并运行这个 sensing-server 二进制。也就是说HAMatter 当时是聚合器的一种配置而不是用户能随手丢进现有舰队的可安装制品。1.2 填补的空白Cognitum Seed cog 目录Cognitum Seed 本身已经有一个 cog 目录生态——打包好的 Seed 应用cog-pose-estimation、cog-quantum-vitals、cog-person-matching等任何人可以从app-registry.json安装。但这 100 多个 cog 里没有cog-ha-matter这正是 ADR-116 要关闭的缺口。打包先例是 ADR-101cog-pose-estimation在 GCS 上发布签名的 aarch64 x86_64 二进制并附带权重 blob——HA cog 期望复用同一形态。1.3 决策对比flag 与 cog 的差异ADR-116 §1.1 给出了一张非常清晰的对比表决定了本 ADR 的走向维度--mqttflagsensing-servercog-ha-matterSeed cog分发手动安装 Rust 二进制app-registry.json列表一键安装发现无mDNS / cog 浏览器更新手动经 cog 运行时的 OTA见证无Ed25519 见证链本地 AI外部本地 ruvllm RuVector1.4 本 ADR不是什么边界声明不弃用--mqttflag该 flag 继续服务没有 Seed 的 Pi / Linux 部署cog 是 Seed 原生选项二者并存。不移植 HA-MIND / HA-DISCO 逻辑到另一种语言Rust crate 已存在cog 是把它包装成可安装制品并叠加 Seed 特有表面见证、RuVector、ruvllm 驱动的阈值。不发布 Matter SDKADR-115 §9.10 已把 matter-rs SDK 接线推迟到 v0.7.1本 ADR 延续该推迟聚焦 cog 打包与一等 Seed 集成Matter Bridge 模式在 SDK 就绪后于 v0.8 交付。2. 决策核心cog-ha-matter 的四个技术表面决策是构建cog-ha-matter由四个技术面组成。其中实体面与 ADR-115 完全一致以保证 HA 侧行为同构其余三个是 Seed 原生增强。2.1 核心实体面与 ADR-115 一致21 实体/节点cog 会通过 MQTT auto-discovery 重新发布每节点 21 个实体11 个原始测量 10 个语义原语这样无论状态源是 Seed cog 还是外部 sensing-serverHome Assistant 安装看到的行为完全一致。仓库内 cog/app-registry-entry.json 的描述也印证了这条语义Adds 10 semantic primitivessomeone_sleeping, possible_distress, fall_risk_elevated, ...on top of the 11 raw measurements。2.2 Seed 原生增强面ADR-116 §2.2 列出五点其中已部分落地、部分推迟到 v0.7/v0.8自包含 MQTT broker可选v0.7 推迟——用户没跑 mosquitto 时 cog 可在cognitum-seed.local:1883内嵌 broker 直接充当 HA 端点。v1 范围表把它排在末尾增加约 2 MB 二进制 ACL 配置面而大多数 HA 安装自带 broker故 v0.7 交付。crate 常量 lib.rs 中的DEFAULT_EMBEDDED_BROKER_PORT 1883与 main.rs 的--mqtt-port默认值即为该端口的占位。mDNS 服务通告——_ruview-ha._tcp让 HA 的 discovery 集成免配置找到 Seed。这一半已在 P4 落地为真实代码见 §5。RuVector 支撑的语义原语阈值——用 SONA 适配的 RuVector 模型替代静态semantic-thresholds.yaml按户学习阈值匹配 Seed 的本地优先 AI 叙事。状态为 pending。Ed25519 见证链——每个状态迁移用 Seed 签名记录供养老/监管部署审计。这一半已在 P4 落地见 §6。OTA 固件协调——cog 管理网格内 ESP32-C6 节点的固件升级依托 ADR-110 substrate。规划中。2.3 Matter 维度依赖研究结论决策暂缓Matter Bridge vs Matter Device、Seed 的 ESP32-S3 上跑 Thread Border Router 的可行性、CSA 认证路径、哪些 Matter 设备类映射哪些实体——这四问交给研究档案结论落在 §3cog 的 Matter 功能集随之暂缓确定。2.4 多 Seed 联邦相邻房间多个 Seed 通过三层机制协同ESP-NOW meshADR-110 substrate做时间对齐mDNS做服务发现见证链复制做跨 Seed 事件溯源。要点是ADR-110 提供了≤100 µs 的跨板时间同步本 ADR 用它做两件事——跨 Seed 事件去重一次跌倒只发一条告警和多房间轨迹重建一名住户房间 A → 走廊 → 房间 B。联邦模型是 ADR-110 mesh substrate 在应用层的自然延伸。3. 八项研究结论Matter / Thread / HACS / 认证 / 监管的取舍依据ADR-116 §3 引用完整档案 docs/research/ADR-116-ha-matter-cog-research.md。该档案共 8 章、30 引文、给出 v1 范围排序。八个研究问题的结论如下Matter Bridge vs Matter RootCommissionerMatter 1.4 在 cluster0x0406revision 5上引入了带RFSensing特性位的OccupancySensor (0x0107)设备类——这正是 WiFi-CSI 感知的正确设备类Matter 1.4.2 没有也不会有 health/vitals cluster。Seed 充当 Bridge含 N 个动态 OccupancySensor 端点而非 Commissioner——C6 感知节点只有 320 KB SRAM 且无 PSRAM无法承担 commission 角色只做 Accessory。Thread Border RouterESP32-C6 单芯片 TBR 已被社区验证可行唯一的配置步骤是CONFIG_OPENTHREAD_BORDER_ROUTERy。ADR-110 的c6_timesync.c已经初始化了 802.15.4——TBR 只差一个 Kconfig 开关。真实价值HA 的 Improv 风格配网无需独立 Thread 边界路由器盒子。HACS 的价值增量config flowUI 配置向导、Repairs API结构化错误卡片、重新认证、诊断导出、类型化服务动作set_privacy_mode、calibrate_zone、i18n 翻译。Bronze 是最低门槛Goldrepairs diagnostics reconfiguration是目标从hacs.integration_blueprint模板起步。CSA 认证首年约 $30–42k约 $22.5k 会员年费 $10–19k ATL 实验室费用。v1 可跳过以 Works with HA 名义发布v0.9 拿到 HACS 采纳数据后再评估 CSA。Cog 资源预算Seed 设备上128 MB RAM / 15% CPUPi 5 Hailo-10 变体余量更大。10 KB 的 INT8 语义原语分类器无需 PSRAM。作为长生命周期监督进程capability scopes 为network.mqtt network.matter api.ruview_vitals。ruvllm RuVector 延迟ruvllm-esp32v0.3.3 证实 SONA 自适应在每次查询 100 µs内完成。8→10 的 INT8 分类器量化后约 10 KB。按户阈值调优通过 HA 点赞/踩反馈做 LoRA 式梯度步——不经过云端就能解决用户第一抱怨误报。HIPAA / FDAFDA 2026 年 1 月 General Wellness 指南明确将 HR/睡眠/活动异常告警归类为wellness 设备只要不做诊断性宣传即不在 FDA 管辖内。落地要点把跌倒检测表述为 **activity anomaly notification活动异常通知**而非跌倒诊断--privacy-modeaudit-only 层只发 SHA-256 摘要、不发 MQTT 状态构成技术性 PHI 屏障OccupancySensor (0x0107)设备类让产品停留在与智能人体传感器相同的监管类别。竞品护城河研究档案 §6 逐一对比了 Aqara FP300/FP2、TOMMY、ESPectre、Frigate、RoomMe。以档案的实体目录对比表为据RuView 的 HR/BR、17 关键点姿态、10 个语义原语、见证链、SONA 自适应在竞品中无对应能力——例如 Aqara FP3002025 年 11 月只有 5 个实体无人计数、无生命体征、无跌倒检测TOMMY 只有区域、无生命体征、闭源付费ESPectre 仅运动检测。需要强调的是上述第 8 条属于研究档案中对公开竞品的陈述性对比引用的是该档案 §6 的表格内容并非本仓库的实测性能结论。4. v1 范围按构建成本 × 用户影响排序ADR-116 §4 与档案 §8 的Recommended Scope一致把 v1 功能按优先级排列#功能成本影响阶段1--privacy-modeaudit-only 层不发 MQTT 状态、Seed 上只存 SHA-256 摘要约 1 周覆盖养老 / GDPR 部署P32Seed cog manifest Ed25519 签名 store 列表约 1–2 周实现一键分发P2 P83本地 SONA 微调闭环HA 反馈 → LoRA 梯度步约 2–3 周降低误报解决头号用户抱怨P54HACS gold 级集成config flow repairs diagnostics约 4–6 周为主流用户移除 MQTT 前置条件P9独立仓库5Matter BridgeOccupancySensor 动态端点约 6–8 周Apple Home / Google Home / Alexa 原生接入v0.8专项 sprint6cog 内嵌 MQTT brokerrumqttd约 1 周无需外部 broker但每套 HA 都有 mosquitto/内置v0.7 推迟约 2 MB 二进制 ACL 配置面4.1 实施阶段总表阶段范围状态P1研究档案8 节、30 引文、v1 范围已排序✅ 完成P2Cog crate 脚手架v2/crates/cog-ha-matter/Cargo.toml src/{lib,main,manifest}.rs、workspace 成员、CLI 参数、--print-manifest、2 个 manifest 单测✅ 完成cargo checkcargo test通过P3包装现有 ADR-115 MQTT 发布者为 cog 入口✅ wiring 完成main.rs经runtime::spawn_publisher启动publisher::spawn持有broadcast::SenderVitalsSnapshot等待 Ctrl-C无需 broker 的 live-handle 测试通过P3.5 待办订阅 sensing-server/v1/snapshotWS 并注入 channelP4Seed 原生增强mDNS、witness嵌入式 broker 推迟✅ shipped——mDNS 记录构建 ServiceInfo 转换 live responder 接入main.rs_ruview-ha._tcp即开即用--no-mdns供受限网络witness 为哈希链 JSONL 文件持久化 链级验证 Ed25519 签名P5RuVector 阈值学习SONA 自适应pendingP6多 Seed 联邦跨 Seed 去重 见证pendingP7Matter Bridge 模式依赖 matter-rs / esp-matter 就绪pendingP8Cog 签名 app-registry.json列表 Seed Store 条目pendingP9HACS 集成仓库HA 侧安装路径pendingP10Witness bundle CSA 风格规格合规检查pending5. 代码落地全景crate 结构与可运行 CLI5.1 模块布局crate 根目录为v2/crates/cog-ha-matter/源码模块划分如下文件职责src/main.rs二进制入口刻意保持精简便于 cog 运行时与测试直接调用库代码src/lib.rs常量与表面声明COG_ID、mDNS 服务类型、默认端口、六大增强面注释src/runtime.rs无副作用 builder把 CLI 转成 ADR-115publisher::spawn需要的输入mDNS responder 的 live handlesrc/mdns.rsmDNS 通告记录的纯 builder RFC 6763 TXT 契约src/manifest.rsCogManifest 的类型化视图与manifest.template.json对齐src/witness.rsSHA-256 哈希链原语含 canonical bytes 编码src/witness_signing.rsEd25519 签名层verify_strict caller-pinned keyCargo.toml依赖清单lib.rs定义的关键常量lib.rsCOG_ID ha-matter——Seed 的app-registry.json与 manifest 使用该 idMDNS_SERVICE_TYPE _ruview-ha._tcpDEFAULT_CONTROL_PORT 9180——cog 本地 HTTP 控制面/health、/api/v1/cog/status区别于 MQTT broker 端口DEFAULT_EMBEDDED_BROKER_PORT 1883——内嵌 broker 的默认端口。依赖上Cargo.tomlcog 直接依赖 ADR-115 的发布核心wifi-densepose-sensing-serverdefault-features falsefeatures [mqtt]、wifi-densepose-hardwareADR-110 substrate 桥接、sha2与ed25519-dalek见证链、mdns-sd 0.11纯 Rust zeroconf daemon。5.2 CLI 参数全表从 main.rs 与 app-registry-entry.json 的config块可以拿到完整、可运行的参数契约后者是 Seed 控制面生成配置表单的数据源两者必须保持一致参数类型默认值说明--sensing-urlstringhttp://127.0.0.1:3000本地 sensing-server 地址cog 从这里拉取VitalsSnapshot再经 MQTT/Matter 转发--mqtt-hoststring127.0.0.1MQTT broker 主机缺省时 cog 可在 1883 上起内嵌 rumqttdv1 仅外部 broker--mqtt-portinteger1883即DEFAULT_EMBEDDED_BROKER_PORTbroker 端口app-registry 中 min1, max65535--privacy-modebooleanfalse在线上剥离生物特征只发布语义原语。任何有非租户居住者的部署都应以它为默认--print-manifestbooleanfalse打印 cog 将向 Seed 控制面自报的 manifest 后退出供构建期签名器使用--mdns-hostnamestringcog-ha-matter.local.mDNS 主机名须以.local.结尾RFC 6762默认让 HA discovery 在 localhost 上也能发现 dev cog--mdns-ipv4string127.0.0.1LAN 可达 IPv4mDNS responder 通告它HA 据此回连 MQTT Matter Bridge--no-mdnsbooleanfalse跳过 mDNS responder。适用于容器化 CI组播 bind 被过滤或多 cog 实例同机场景5.3 启动流程main.rs 的接线顺序main.rs 的运行时接线可以概括为五步解析 CLIclap derive记录启动日志若--print-manifest以模板占位符构造CogManifestid、version、binary_url 带{{ARCH}}槽并打印后退出——该 manifest 在构建期由 Makefile 替换版本与架构后签名P3构造CogIdentity::default_for_build()node_id 取cog-ha-matter-{pid}保证同机多实例不抢 MQTT 会话调用runtime::build_publisher_inputs生成 MQTT 配置与 discovery 记录打开容量 256 的broadcast::channel::VitalsSnapshot再经runtime::spawn_publisher把 ADR-115 发布者作为 tokio 任务拉起P4非--no-mdns时构建 mDNS 服务并start_mdns_responder注册通告——失败只降级记 warn 并回退到手动 HA 配置不视为致命错误tokio::select!等待 Ctrl-C 或 publisher 任务意外退出_mdns_handle析构时会发出 mDNS goodbye 包让 HA 干净地看到服务下线。5.4 runtime 层的工程细节为什么这样做runtime.rs 是全 crate 最值得读的架构课文件其注释与测试直接记录了 ADR-115 集成测试的事后教训MQTTclient_id必须按进程唯一§Lessons复用 client_id 会导致 broker 踢掉上一会话、发布者陷入无限重连。cog 因此把client_id派生为ha-matter-{node_id}runtime.rs 的对应单测client_id_includes_node_id_for_session_uniqueness锁死该行为builder 保持纯函数、无 I/OmDNS responder / 控制面P4可以从不同来源Seed 控制配置、JSON POST构建同样的输入而无需经过 clapDEFAULT_STATE_CHANNEL_CAPACITY 256runtime.rs与 sensing-server 自身默认一致避免多 Seed 联邦 / mesh 重同步的突发负载下发布者成为瓶颈且有default_state_channel_capacity_is_reasonable测试防止回退via_device必须通告 cog 的id让设备在 HA 设备注册表中显示为 Seed 桥接下的设备对应 ADR-101/ADR-102 的每 cog 约定TLS 默认关闭v1 仅 LAN无公网 brokertls_defaults_to_off_for_v1_lan_only测试锁定该默认值v0.8 Matter Bridge 交付时再接线。6. mDNS 通告与 TXT 记录契约6.1 通告结构mdns 模块把通告什么纯数据 builder与如何通告responder分离MdnsService是 wire-format 双胞胎to_service_info是到mdns_sd::ServiceInfo的纯转换真正的组播 socket 由runtime::start_mdns_responder负责。这样响应库可以随时替换而通告内容、TXT 键位均由命名测试锁死——漂移会在测试期炸掉而不是静默破坏部署。6.2 TXT 记录契约RFC 6763HA 的 discovery 集成靠读 TXT 记录来把 manifest 绑定到某个homeassistant.integrationzeroconf 钩子。cog 发布的最小 TXT 集合如下见 mdns.rs 文档注释与build_mdns_serviceKeyValue用途cog_idha-matter与其它 RuView cog 区分cog_versionCARGO_PKG_VERSIONHA Repairs 据此提示升级node_ididentity 的 node idHA 设备注册表主键mqtt_portu16 字符串告诉 HA 到哪里连 cog 的 MQTT broker内嵌或外部privacy1/0为1时 HA config flow 默认把关生物特征实体protoruview-ha/1协议版本auto-discovery 有破坏性变更时递增三个值得注意的实现约束TXT 记录按键排序保证跨重建的字节级稳定RFC 6763 §6.4 虽然把顺序定义为实现相关但锁死顺序利于审计——txt_records_are_sorted_for_byte_stable_advertisement测试守护TXT 里不允许出现任何生物特征 / PIIhr_bpm、br_bpm、pose 坐标、ssid、经纬度、MAC、RSSI 都被禁止——因为 TXT 明文广播、被动扫描器可采集txt_carries_no_biometric_or_pii_keys测试把它们列为黑名单控制端口走服务记录SRV 的 port 字段 9180而 MQTT 端口走 TXT 记录二者不会被误换——control_port_field_holds_control_not_mqtt_port测试防止未来重构把 broker 端口错当成控制面端口通告。7. Ed25519 见证链实现、密码学细节与安全加固这是 P4 已 shipped 的另一半也是 ADR-262 P2 计划复用的签名链因此 ADR-116 §4.1 对它做了专门的 crypto/security review。7.1 为什么哈希链而非 Merkle 树witness 模块的注释给出了直白理由cog 以语义原语状态迁移的速率产事件——稳态下每分钟几个跌倒检测 / 房间迁移等事件期间几十个。这个速率下线性扫描完全够用Merkle 的 O(log n) 包含证明复杂度留给未来链跨度数天时的更高 tier。7.2 单事件结构每条见证事件WitnessEvent字段零基seq严格单调有空洞说明链被截断、prev_hash首条为GENESIS [0u8; 32]、Unix 秒时间戳调用方注入以便测试确定性、稳定的kind标签如fall_risk_elevated、bed_exit、privacy_mode_toggled、不透明payload字节典型为已发 MQTT 状态消息的 JSON供审计者反推 HA 被告知了什么、以及本事件哈希this_hash。7.3 canonical bytes 编码防拼接伪造的关键WitnessChain::append是唯一的变更入口哈希对象是确定性 canonical 字节格式为witness.rsDOMAIN_TAG | prev_hash[32] | seq:u64-be | ts:u64-be | kind_len:u32-be | kind | payload_len:u32-be | payload**长度前缀length-prefix**让(abc,def)与(ab,cdef)产生不同哈希——经典拼接伪造在编码层即被阻断有单测canonical_bytes_length_prefixing_prevents_ambiguity锁证定宽字段自定界域标签domain tagWITNESS_DOMAIN_TAG bcog-ha-matter/witness-event/v1\x00是 CHM-WIT-01 的修复产物见下带版本且以 NUL 结尾未来迁移Blake3、增字段、Merkle tier可 bump 标签而不是与 v1 bundle 静默碰撞。7.4 链级验证与 JSONL 持久化WitnessChain::verify()逐事件重算this_hash、核对prev_hash衔接、检查seq从 0 起无空洞返回 auditor 友好的WitnessVerifyErrorSeqGap/PrevHashMismatch/HashMismatchread_jsonl逐行解析from_jsonl_line先重验存储哈希篡改 bundle 直接触发WitnessParseError::HashMismatch而非悄悄加载伪造事件随后做端到端链验证错误都带 1-indexed 行号JSONL 字段序按字母序锁定kind, payload_hex, prev_hash, seq, this_hash, timestamp_unix_s保证审计者对整个 bundle 做归档哈希时不因重建字段重排而失效。7.5 签名层与安全审查结论签名层witness_signing.rs与哈希链分离理由哈希链可在不链接ed25519-dalek的情况下用于 wasm 浏览器端审计验证变体密钥轮换只作废签名、不作废链签名面小到一次能读完。sign_event签的正是witness::hash_event哈希的那份 canonical 字节——签名同时承诺整个事件kind/payload/ts/seq/prev_hash与链位置经prev_hash把已签名事件拼到另一条链上必然验签失败。verify_signature有两点刻意设计走verify_strict而非宽松verifyCHM-WIT-02 加固审计链上签名即证明因此必须拒绝非规范编码与小阶公钥RFC 8032 strict得到每事件唯一规范签名的性质。这不是防伪修复——验签密钥是调用方钉死的绝不从事件里读verify-before-trust key pinningverify_signature把验证公钥当参数传入read_jsonl会重推每个哈希并做链验证。ADR-116 §4.1 的审查结论以审查记录为据可以归纳为引擎 bug 类缺失良好结果附字节级证据此前审查过同类 sibling 引擎把操作者可影响的字符串做无框架首尾拼接后签名/哈希的 bug 类本 crate 中不存在——两个变长操作者可影响字段kind、payload均带长度前缀编码是单射的Ed25519 签名签的与 SHA-256 链提交的是同一份字节manifest 的binary_signature是构建期Makefile对单个定长binary_sha256十六进制值所做不在 crate 内CHM-WIT-01已修复——补域分离标签引擎修复方子本要求域标签 长度前缀原实现有长度前缀缺域标签。现加入带版本、NUL 结尾的WITNESS_DOMAIN_TAG使见证消息永远不会被重放为共享密钥设施的另一 Ed25519 上下文的消息尤其 manifest 签名。见证字节按设计变更旧磁盘哈希/签名作废验证过安全仓库内没有 crate 以编程方式消费 cog-ha-matter 见证字节CHM-WIT-02已加固——verify_signature用verify_strict确认干净附证据key 处理crate 从不生成/存储/记录/序列化签名私钥仅有文档化的测试专用固定种子生产密钥来自 Seed 安全存储、确定性定位字节、确定性 Ed25519、字母序锁定的 JSONL 字段序、排序 TXT 记录——无 HashMap/浮点不确定性进摘要、fail-closed 解析结构化错误无 panicmain.rs 不读不受信文件/路径。测试量佐证ADR 记录cog-ha-matter --no-default-features下测试数64 → 680 失败CHM-WIT-01 由witness.rs/witness_signing.rs中 4 个旧编码必失败测试钉住CHM-WIT-02 由 key-pinning 测试守护。8. 打包与发布流水线Makefile 驱动的 build / sign / uploadcog 打包目录 cog/ 有三个关键文件。manifest.template.json是带{{VERSION}}/{{ARCH}}槽位的构建期模板Makefile 镜像cog-pose-estimation/cog/Makefile使 Seed 运行时对两类 cog 一视同仁cognitum cog install ha-matter与cognitum cog install pose-estimation同构。8.1 目标一览Makefile 目标动作make build同时构建 aarch64aarch64-unknown-linux-gnu与 x86_64 两个 release 二进制并拷到dist/make sign为每个架构写.sha256旁车文件Ed25519 签名步骤标注为 TODO待COGNITUM_OWNER_SIGNING_KEY配置进 CImake uploadgsutil cp dist/* gs://cognitum-apps/cogs/{arm,x86_64}/make manifestcargo run -p cog-ha-matter --release -- --print-manifest输出 Seed 将记录的 manifestmake releasebuild sign upload manifest串起来的完整发布流水线make verify对每个架构核对sha256sum与旁车文件是否一致make clean清理dist/8.2 签名路径与清单契约Manifest 的类型化视图在 src/manifest.rs8 个必填字段字段语义id稳定 cog idha-matter会成为 Seed 上/var/lib/cognitum/apps/id/的目录名versionSemVer发布时由 Makefile 从cargo pkgid提取binary_urlSeed 拉取二进制的位置带{{ARCH}}槽arm/x86_64binary_bytes二进制字节数构建期wc -c后填入binary_sha256二进制 SHA-256小写十六进制、无0xSeed 在 exec() 前验证binary_signature对binary_sha256的 Ed25519 签名base64。未签名 dev 构建可为空app-registry.json所列 cog 必填installed_at安装时刻 Unix 时间戳Seed 在安装/升级成功后盖章statusinstalled/upgrading/degraded/removed之一crate 携带该类型化视图的原因manifest.rs 注释是让 cog 能向 Seed 控制面/api/v1/cog/status自报 manifest且构建期模板与运行时序列化器之间的格式漂移由命名测试触发——manifest_round_trip_matches_template即锁定 JSON wire 形态八个字段无多余。Seed 侧 install 校验按 ADR-100 契约执行。8.3 发布边界诚实标注值得注意的是Makefile 的sign目标目前对签名本身是 no-op——COGNITUM_OWNER_SIGNING_KEY的配置与cog-pose-estimation是同一条 TODO因此 dev cog 以未签名状态发布app-registry.json中以binary_signature: 列出。正式app-registry.json属于 cognitum-one 仓库而非本仓库见 cog/README.md 的 PR 说明。9. 研究档案补充Surface A/B/C 架构与前沿特性研究档案 §3 给出了 cog 的三种对外表面可用于理解同一份感知数据如何多渠道出口Surface A — MQTT bridge连接用户配置的 Mosquitto broker或 Seed 内部 broker把 Seedruview-vitals-worker端口 50054的遥测重发为 HA auto-discovery 消息复用 ADR-115 的 HA-DISCO 逻辑但作为 Seed 原生 cog 运行无需用户另跑 sensing-servercog 注册ha_mqttMCP 工具供其它 cog 的自动化调用Surface B — Matter bridge把 Seed 包装为 Matter Accessory Bridge一个 Fabric 节点 N 个动态端点每感知区一个。设备类映射存在 →OccupancySensor (0x0107)OccupancySensing (0x0406)RFSensing特性位 BooleanState (0x0045)跌倒 →ContactSensor (0x0015)事件源语义触发后 5 秒自复位人数 → Bridge 根端点上厂商自定义数值属性cluster0xFFF1_xxxx命名空间。Seed 的 AMOLED 屏直接显示 Matter 配网 QR 码Surface C — HA HACS 集成可选custom_components/wifi_densepose/Python 包直连 Seed REST API/api/v1/bearer token 来自 cognitum-agent承载 config flow、实体、repairs、diagnostics。档案 §3.3 明确了协议优先级MQTT 为一级、Matter 为二级——MQTT 到本地 HA 风险更低、路径更快无需 Matter SDK 链接、无需 CSA 认证、复用现成 HA-DISCO 逻辑Matter 直发要求 Seed 持有合法 Fabric 证书、管理运营凭据、处理 rekey开发与 QA 成本约 3–4 倍。这与 ADR-115 的双协议决策一致但现在原生在 cog 内。档案 §8 还列出若干前沿特性本 ADR §4 v1 范围表的依据来源多房间存在交接状态机消除鬼影占用、结合 HA 能耗实体做 energy disaggregationphantom_load_candidate、以及上文 §4 已覆盖的三档隐私模式none/semantic默认 /audit-only。10. 结合源码的验证路径怎么亲手确认本文结论本文所有实现性结论都能在当前仓库中复查读决策与档案ADR-116 全文 研究档案并回看上游 ADR-115MQTT publisher 与 21 实体、ADR-110C6 mesh / 时间同步 substrate、ADR-101 与 ADR-102cog 打包/注册先例核对 CLI 与常量main.rs 的 clap 参数与 app-registry-entry.json 的config键一致跑测试验证行为在v2/workspace 下对 crate 执行cargo test -p cog-ha-matter可复现 §5–§7 提到的命名测试client_id 唯一性、TXT PII 黑名单、canonical 编码单射性、链验证捕获篡改、签名 key-pinning 等——源码注释显示每个测试都对应一条真实事故或契约查看构建契约cog/Makefile 的 build/sign/upload/manifest 目标与 cog/README.md 的本地 dry-run 说明make build make sign make manifest。需要声明的前提与限制crate 仍处 P2–P4 实质交付阶段P5 起的 RuVector 阈值学习、P6 联邦、P7 Matter Bridge、P8 正式注册、P9 HACS 均为 pending嵌入式 broker 与 Matter Bridge 分别推迟至 v0.7 / v0.8签名密钥尚未配置进 CI当前 dev 构建未签名。结语ADR-116 是一个决策先行、脚手架紧随其后的典型范例它以一份 8 章研究档案回答了 Matter/HACS/认证/监管四个高风险问题把HAMatter 集成该长什么样收敛成一份可排序的 v1 范围随后在v2/crates/cog-ha-matter里把范围中的高优先项manifest 自报、--print-manifest、ADR-115 发布者包装、mDNS auto-discovery、Ed25519 见证链落成可编译、可测试、带完整安全审查记录的 Rust 代码。对希望理解感知能力如何以可安装制品形态进入智能家居生态的读者从 ADR-116 出发沿本文第 10 节的路径读源码是信息密度最高的一条路线。【免费下载链接】RuViewπ 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
