RuViewWiFi-DensePose 系统API 规范详解从 REST 端点、WebSocket 流式协议到鉴权与外部集成【免费下载链接】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/RuViewRuView 的前身是一套名为 InvisPose 的 WiFi 人体姿态估计系统它基于 WiFi CSIChannel State Information信号、通过神经网络实现不依赖摄像头的密集人体姿态感知。其 API 规范定义在 plans/phase1-specification/api-spec.md从 REST 端点、WebSocket 流式协议、数据模型 Schema、鉴权授权、外部集成MQTT/Webhook/Restream、错误处理、限流、版本化到验收标准共 11 个章节是理解系统对外可编程接口的权威骨架。本文将围绕该规范逐章深入解读并结合仓库内源码如 pose 观测 Schema、ESP32 CSI 节点、MQTT 验证脚本补充实现细节让读者既能读懂规范也能对照真实工程落地。1. 文档定位与系统概览api-spec.md 是一份面向开发者的接口契约文档Version 1.0状态 Draft定义了 WiFi-DensePose 系统全部程序化接口涵盖姿态数据访问、系统控制、实时流式分发、外部集成以及鉴权/授权机制。规范全文由三块构成REST API姿态数据端点latest / history / query、系统控制端点status / start / stop、配置管理端点GET/PUT /config、领域特定端点healthcare / retail analyticsWebSocket 协议/ws/pose实时姿态流、/ws/alerts告警流含订阅管理横切面规范数据模型 Schema、JWT/API Key 鉴权与作用域、MQTT/Webhook/Restream 集成、错误码、限流、版本化与验收标准。系统的上游是 WiFi 路由器3×3 MIMO→ CSI 接收模块 → 神经网络流水线 → 姿态估计引擎 → API 服务 → Web 仪表盘另有配置管理模块。在 RuView 仓库中这一链路已有真实落地配套 plans/phase1-specification/technical-spec.md 给出了 CSI 采集10–30Hz 采样率、相位解卷绕、背景相减等预处理流程plans/phase1-specification/functional-spec.md 定义了功能需求跌倒检测、多领域适配、隐私保护感知。2. REST API 端点详解所有端点均要求 Bearer Token 鉴权路径前缀设计上支持/api/v1/版本化见第 9 节。2.1 姿态数据端点GET /pose/latest —— 最新姿态返回最近一次推理结果frame_id单调递增processing_time_ms暴露推理耗时persons数组内含检测置信度、边界框、关键点与 dense pose 的 UV 坐标metadata携带环境 ID、路由器数量与信号质量。错误响应覆盖 404无数据、503系统未初始化、401未鉴权。规范对每一节都内嵌了测试注释如// TEST: Verify latest pose endpoint returns valid pose data structure暗示接口与测试用例强绑定。GET /pose/history —— 历史姿态查询参数start_time/end_timeISO 8601、limit默认 100上限 1000、person_id、confidence_threshold0.0–1.0。响应使用游标分页next_cursor为 base64 编码的 opaque token配合total_count/has_more支持深分页。POST /pose/query —— 复杂查询请求体支持时间范围、多条件过滤人数、置信度、活动类型如 walking/standing与聚合hourly_summary、person_count、avg_confidence响应中的query_metadata给出执行耗时、扫描记录数与缓存命中情况。2.2 系统控制端点GET /system/status返回运行状态、运行时长、版本以及componentscsi_receiver 数据速率/丢包率、neural_network 推理耗时/GPU 利用率、tracking 活动轨迹数/轨迹质量、hardwareCPU/内存/GPU/磁盘占用、network已连接路由器、信号强度、干扰水平POST /system/start接受domainhealthcare/retail/security/general、environment_id、calibration_required返回初始化步骤进度hardware_initialization → model_loading与预计就绪时间POST /system/stop支持force与save_state返回优雅停机步骤进度data_pipeline_stop → model_unloading。对应仓库中校准流程可参考 aether-arena/calibration/ 及 docs/calibration-guide.md。2.3 配置管理端点GET /config返回完整配置树domain、environment含 calibration_timestamp、detectionconfidence_threshold 默认 0.7、max_persons 默认 5、tracking_enabled 默认 true、alertsfall_detection 灵敏度/通知延迟、inactivity_detection 阈值、streamingrestream/websocket/mqtt 开关。PUT /config支持部分更新响应返回changes_applied点路径列表如detection.confidence_threshold、restart_required与validation_warnings。2.4 领域专属端点GET /analytics/healthcare跌倒事件计数与详情严重度、响应时间、活动时长汇总步行/坐/躺/站、移动性评分GET /analytics/retail客流量峰值时段/平均停留、分区域到访与停留、转化漏斗入口→商品互动→结账。从仓库源码看RuView 已提供与这些领域能力对应的实际资产Home Assistant 蓝色清单模板如 examples/ha-blueprints/07-fall-risk-escalation.yaml、examples/ha-blueprints/01-notify-on-possible-distress.yaml覆盖跌倒检测与告警通知examples/lovelace/03-healthcare-aal-view.yaml 提供医护视图姿态观测的机器可读 Schema 定义于 docs/schemas/pose-observation-v2.schema.json其joints固定 17 个关键点、每个关节带position_m、covariance_m2、confidence与visibility枚举与本文第 4 节的 Keypoint 模型高度对应。3. WebSocket 实时流式协议WebSocket 端点ws://host:port/ws/pose鉴权可通过查询参数或请求头传递 token。连接建立服务端返回connection_established消息含client_id、server_time与supported_protocols如pose_v1、alerts_v1订阅管理客户端发送subscribechannel 为pose_updates或alerts可带min_confidence、person_ids过滤服务端回subscription_confirmed含subscription_id数据推送pose_update消息帧 ID、persons、metadatasystem_status周期性推送处理 FPS、活跃人数、系统健康度alert消息含alert_id、alert_typefall_detection/intrusion、severity、位置与actions_required。仓库中 ADR-055 已明确“Sensing 页面通过 WebSocket 连接捆绑服务器端点”见 docs/adr/ADR-055-integrated-sensing-server.md说明实时姿态流在 RuView 中属于既定架构方向。需要指出的是这份 api-spec 属于 Phase 1 规划文档Status: Draft目前仓库并未包含该 FastAPI 服务的完整实现源码其 WebSocket 帧契约的设计先例可参考 Rust 侧的 ADR-136 流式引擎docs/adr/ADR-136-ruview-streaming-engine-frame-contracts.md后者以CsiFrame/FrameMeta统一 CSI、CIR、Doppler 帧类型并用 BLAKE3 witness 保证确定性回放可作为本规范实时流的底层数据契约参考。4. 数据模型与 Schema规范给出四类核心模型与配置 SchemaJSON Schema draft-07Person Modelid、confidence0.0–1.0、bounding_box引用 BoundingBox 定义、keypoints数组、dense_pose、tracking_info必填字段为 id/confidence/bounding_box/keypointsKeypoint Modelname枚举严格限定 17 个关键点nose、左右眼/耳/肩/肘/腕/髋/膝/踝x/y、confidence、visibleDense Pose Modelbody_parts数组每项含part_id、part_name、uv_coordinates二维坐标对、confidenceSystem Configuration Schemadomain枚举healthcare/retail/security/generalenvironment必填 id/namedetection含置信度阈值0.0–1.0默认 0.7、max_persons1–10默认 5、tracking_enabled默认 true。仓库提供了与之对应的实装 Schemadocs/schemas/pose-observation-v2.schema.json 中joints数组强制minItems17/maxItems17关节kind枚举与 Keypoint Model 的 17 点命名完全一致且比规划文档更进一步额外引入timestamp_ns、sensor_epoch、sourcesensor_id/authenticated/replay_protected对应鉴权与防重放、modelid/artifact_hash对应模型溯源与covariance_m2不确定性建模。这体现了从“规划接口”到“可验证数据契约”的演进。5. 鉴权与授权Bearer TokenJWTAuthorization: Bearer token默认 24 小时过期payload 含sub、iat、exp、scope数组与domainAPI KeyX-API-Key: api_key用于服务间通信作用域限定在特定端点授权作用域pose:read、pose:stream、system:control、system:status、config:read、config:write、alerts:manage、admin:full领域化访问控制healthcare 域附加 HIPAA 合规要求、retail 域保护客户隐私、security 域增强审计日志、general 域使用标准控制。规范要求对敏感操作记录审计日志。RuView 仓库对“可信身份与防重放”有更强的实装要求pose-observation-v2.schema.json的source.authenticated与source.replay_protected字段要求每条观测标注传感器身份与防重放状态docs/adr/ADR-305-authenticated-sensor-identity.md、docs/adr/ADR-327-governed-action-intents-and-witness-receipts.md 等 ADR 延续了“证据可溯源”的主线。若按本规范实现 REST 服务建议在 JWT 中至少携带sub用户/服务标识与scope并以domain字段驱动领域级策略。6. 外部集成 API6.1 MQTT 集成主题树采用wifi-densepose/根前缀分四组pose/person/{person_id}单人数据、summary聚合、raw原始帧alerts/fall_detection、intrusion、systemstatus/system、hardware、networkanalytics/healthcare、retail、security。消息格式示例单人姿态消息timestamp/person_id/confidence/keypoints/activity/location与告警消息alert_id/type/severity/location/confidence。仓库中 MQTT 已有真实验证脚本 scripts/validate-esp32-mqtt.sh该脚本先本地拉起mosquittobrokerallow_anonymous、日志输出到 stdout再用mosquitto_sub -t homeassistant/#捕获主题、解析并核对覆盖矩阵最后用mosquitto_pub发健康检查消息验证 HA 发现主题与至少一条状态主题。这说明 MQTT 主题契约在本仓库以 Home Assistant 集成为主要消费方参见 docs/integrations/home-assistant.md 与 docs/adr/ADR-115-home-assistant-integration.md。6.2 Webhook 集成POST /webhooks注册回调端点指定url、订阅事件fall_detection、person_detected 等、鉴权方式bearer token与重试策略max_retries3、retry_delay_seconds5。事件载荷统一包裹webhook_id、event_type、timestamp、data与metadataenvironment_id、system_version。6.3 Restream 集成POST /streaming/restream配置多平台直播youtube/twitch/facebook含视频参数分辨率 1280x720、30fps、bitrate 2500与叠加层show_keypoints/show_confidence/show_person_ids/transparent 背景GET /streaming/status返回各平台连接状态、观看人数、运行时长与视频统计fps、bitrate、丢帧数。这一能力与仓库可视化组件如 ui/observatory/属于同一展示链路属于规划中的对外广播能力。7. 错误处理与状态码成功200 / 201 / 202 / 204客户端错误400参数非法、401未鉴权/凭证无效、403权限不足、404资源不存在、409冲突如系统已在运行、422校验失败、429限流服务端错误500 / 502 / 503系统未就绪或过载/ 504。错误响应采用统一信封error.code机器可读如POSE_DATA_NOT_FOUND、VALIDATION_ERROR、message、details含请求范围与可用范围、字段级错误field_errors、timestamp、request_id便于链路追踪。这种格式与 RuView 强调的“证据可追溯”精神一致——每条错误都能定位到具体请求。8. 限流与性能指标限流配置REST 每 API Key 每小时 1000 请求WebSocket 每 IP 100 连接流式每账户 10 并发流Webhook 每端点每小时 10000 事件。限流响应头X-RateLimit-Limit/X-RateLimit-Remaining/X-RateLimit-Reset/X-RateLimit-Window。性能目标95 百分位姿态端点 100ms、系统控制 500ms、配置更新 200ms、WebSocket 消息 50ms吞吐目标REST 1 万 req/s、WebSocket 1000 并发连接、姿态更新 30 FPS/流、告警端到端 1s。这些是规划目标需要实装后通过压力测试验证读者不应将其视为已测量数据。9. API 版本化与兼容性URL 版本化当前/api/v1/未来/api/v2/、/api/v3/保持向后兼容Header 版本化Accept: application/vnd.wifi-densepose.v1json、API-Version: 1.0弃用策略提前 6 个月通知、弃用后支持 12 个月、提供迁移文档与工具弃用响应头Deprecation: true、SunsetRFC 850 格式、Link指向 successor-version。仓库侧对版本契约的重视在 docs/adr/ADR-298-model-release-sanity-gates.md模型发布门禁等 ADR 中均有体现可视为版本兼容纪律的旁证。10. 测试与验证策略测试类别单元测试单端点、集成测试端到端工作流、性能测试负载/压力、安全测试鉴权授权、契约测试Schema 校验。测试数据管理合成姿态数据、真实 CSI 录制数据、Mock 外部服务、隔离测试环境。文档测试要求 OpenAPI 规范合规、示例可执行、链接可用、代码示例可运行。仓库中与之呼应的测试资产docs/schemas/pose-observation-v2.schema.json 本身可作契约测试基准aether-arena/fixtures/ 提供 smoke 预测/分割 JSON 与期望 hashaether-arena/calibration/test_calibration.py 与 aether-arena/calibration/test_cog_calibration.py 覆盖校准回归scripts/validate-esp32-mqtt.sh 是集成级验证脚本。11. 验收标准功能验收所有端点实现可用、响应符合 Schema、鉴权授权生效、WebSocket 流 50ms 延迟性能验收95 百分位响应达标、吞吐达标、限流正确、可扩展集成验收MQTT/Webhook/Restream 可用、错误处理完备、文档完整准确、自动化测试覆盖。12. 落地路径与仓库对照api-spec.md 是 Phase 1 的规划蓝图Draft 状态仓库目前以“文档契约先行、实现分阶段落地”的方式推进。若要在 RuView 中实现这套 API可参考以下对照关系规范章节仓库对应资产说明4 数据模型docs/schemas/pose-observation-v2.schema.json17 关节、置信度、协方差、传感器身份已实装2.2 系统状态scripts/ruview-sensing-server.py、scripts/check_health.py传感服务器与健康检查脚本6.1 MQTTscripts/validate-esp32-mqtt.sh、docs/integrations/home-assistant.mdHA 主题契约与验证脚本2.1 姿态数据aether-arena/calibration/infer.py、aether-arena/fixtures/推理与 fixtures3 WebSocketdocs/adr/ADR-055-integrated-sensing-server.md、docs/adr/ADR-136-ruview-streaming-engine-frame-contracts.md流式架构与帧契约5 鉴权docs/adr/ADR-305-authenticated-sensor-identity.md、docs/adr/ADR-141-bfld-privacy-control-plane-modes-attestation.md传感器身份与隐私控制面整体而言这份 API 规范的价值在于它把“WiFi 无摄像头感知”从研究原型抽象成一套标准化的产品级接口——REST 面向读写与查询、WebSocket 面向低延迟实时分发、MQTT/Webhook 面向外部系统对接、JWT/Scope 面向多租户多领域授权。结合 RuView 仓库已有的 Schema、MQTT 验证脚本与 ADR 证据链开发者可以此规范为蓝本在 RuView 传感链路上逐步落地可验证的对外 API 服务。【免费下载链接】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（WiFi-DensePose 系统）API 规范详解：从 REST 端点、WebSocket 流式协议到鉴权与外部集成
RuViewWiFi-DensePose 系统API 规范详解从 REST 端点、WebSocket 流式协议到鉴权与外部集成【免费下载链接】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/RuViewRuView 的前身是一套名为 InvisPose 的 WiFi 人体姿态估计系统它基于 WiFi CSIChannel State Information信号、通过神经网络实现不依赖摄像头的密集人体姿态感知。其 API 规范定义在 plans/phase1-specification/api-spec.md从 REST 端点、WebSocket 流式协议、数据模型 Schema、鉴权授权、外部集成MQTT/Webhook/Restream、错误处理、限流、版本化到验收标准共 11 个章节是理解系统对外可编程接口的权威骨架。本文将围绕该规范逐章深入解读并结合仓库内源码如 pose 观测 Schema、ESP32 CSI 节点、MQTT 验证脚本补充实现细节让读者既能读懂规范也能对照真实工程落地。1. 文档定位与系统概览api-spec.md 是一份面向开发者的接口契约文档Version 1.0状态 Draft定义了 WiFi-DensePose 系统全部程序化接口涵盖姿态数据访问、系统控制、实时流式分发、外部集成以及鉴权/授权机制。规范全文由三块构成REST API姿态数据端点latest / history / query、系统控制端点status / start / stop、配置管理端点GET/PUT /config、领域特定端点healthcare / retail analyticsWebSocket 协议/ws/pose实时姿态流、/ws/alerts告警流含订阅管理横切面规范数据模型 Schema、JWT/API Key 鉴权与作用域、MQTT/Webhook/Restream 集成、错误码、限流、版本化与验收标准。系统的上游是 WiFi 路由器3×3 MIMO→ CSI 接收模块 → 神经网络流水线 → 姿态估计引擎 → API 服务 → Web 仪表盘另有配置管理模块。在 RuView 仓库中这一链路已有真实落地配套 plans/phase1-specification/technical-spec.md 给出了 CSI 采集10–30Hz 采样率、相位解卷绕、背景相减等预处理流程plans/phase1-specification/functional-spec.md 定义了功能需求跌倒检测、多领域适配、隐私保护感知。2. REST API 端点详解所有端点均要求 Bearer Token 鉴权路径前缀设计上支持/api/v1/版本化见第 9 节。2.1 姿态数据端点GET /pose/latest —— 最新姿态返回最近一次推理结果frame_id单调递增processing_time_ms暴露推理耗时persons数组内含检测置信度、边界框、关键点与 dense pose 的 UV 坐标metadata携带环境 ID、路由器数量与信号质量。错误响应覆盖 404无数据、503系统未初始化、401未鉴权。规范对每一节都内嵌了测试注释如// TEST: Verify latest pose endpoint returns valid pose data structure暗示接口与测试用例强绑定。GET /pose/history —— 历史姿态查询参数start_time/end_timeISO 8601、limit默认 100上限 1000、person_id、confidence_threshold0.0–1.0。响应使用游标分页next_cursor为 base64 编码的 opaque token配合total_count/has_more支持深分页。POST /pose/query —— 复杂查询请求体支持时间范围、多条件过滤人数、置信度、活动类型如 walking/standing与聚合hourly_summary、person_count、avg_confidence响应中的query_metadata给出执行耗时、扫描记录数与缓存命中情况。2.2 系统控制端点GET /system/status返回运行状态、运行时长、版本以及componentscsi_receiver 数据速率/丢包率、neural_network 推理耗时/GPU 利用率、tracking 活动轨迹数/轨迹质量、hardwareCPU/内存/GPU/磁盘占用、network已连接路由器、信号强度、干扰水平POST /system/start接受domainhealthcare/retail/security/general、environment_id、calibration_required返回初始化步骤进度hardware_initialization → model_loading与预计就绪时间POST /system/stop支持force与save_state返回优雅停机步骤进度data_pipeline_stop → model_unloading。对应仓库中校准流程可参考 aether-arena/calibration/ 及 docs/calibration-guide.md。2.3 配置管理端点GET /config返回完整配置树domain、environment含 calibration_timestamp、detectionconfidence_threshold 默认 0.7、max_persons 默认 5、tracking_enabled 默认 true、alertsfall_detection 灵敏度/通知延迟、inactivity_detection 阈值、streamingrestream/websocket/mqtt 开关。PUT /config支持部分更新响应返回changes_applied点路径列表如detection.confidence_threshold、restart_required与validation_warnings。2.4 领域专属端点GET /analytics/healthcare跌倒事件计数与详情严重度、响应时间、活动时长汇总步行/坐/躺/站、移动性评分GET /analytics/retail客流量峰值时段/平均停留、分区域到访与停留、转化漏斗入口→商品互动→结账。从仓库源码看RuView 已提供与这些领域能力对应的实际资产Home Assistant 蓝色清单模板如 examples/ha-blueprints/07-fall-risk-escalation.yaml、examples/ha-blueprints/01-notify-on-possible-distress.yaml覆盖跌倒检测与告警通知examples/lovelace/03-healthcare-aal-view.yaml 提供医护视图姿态观测的机器可读 Schema 定义于 docs/schemas/pose-observation-v2.schema.json其joints固定 17 个关键点、每个关节带position_m、covariance_m2、confidence与visibility枚举与本文第 4 节的 Keypoint 模型高度对应。3. WebSocket 实时流式协议WebSocket 端点ws://host:port/ws/pose鉴权可通过查询参数或请求头传递 token。连接建立服务端返回connection_established消息含client_id、server_time与supported_protocols如pose_v1、alerts_v1订阅管理客户端发送subscribechannel 为pose_updates或alerts可带min_confidence、person_ids过滤服务端回subscription_confirmed含subscription_id数据推送pose_update消息帧 ID、persons、metadatasystem_status周期性推送处理 FPS、活跃人数、系统健康度alert消息含alert_id、alert_typefall_detection/intrusion、severity、位置与actions_required。仓库中 ADR-055 已明确“Sensing 页面通过 WebSocket 连接捆绑服务器端点”见 docs/adr/ADR-055-integrated-sensing-server.md说明实时姿态流在 RuView 中属于既定架构方向。需要指出的是这份 api-spec 属于 Phase 1 规划文档Status: Draft目前仓库并未包含该 FastAPI 服务的完整实现源码其 WebSocket 帧契约的设计先例可参考 Rust 侧的 ADR-136 流式引擎docs/adr/ADR-136-ruview-streaming-engine-frame-contracts.md后者以CsiFrame/FrameMeta统一 CSI、CIR、Doppler 帧类型并用 BLAKE3 witness 保证确定性回放可作为本规范实时流的底层数据契约参考。4. 数据模型与 Schema规范给出四类核心模型与配置 SchemaJSON Schema draft-07Person Modelid、confidence0.0–1.0、bounding_box引用 BoundingBox 定义、keypoints数组、dense_pose、tracking_info必填字段为 id/confidence/bounding_box/keypointsKeypoint Modelname枚举严格限定 17 个关键点nose、左右眼/耳/肩/肘/腕/髋/膝/踝x/y、confidence、visibleDense Pose Modelbody_parts数组每项含part_id、part_name、uv_coordinates二维坐标对、confidenceSystem Configuration Schemadomain枚举healthcare/retail/security/generalenvironment必填 id/namedetection含置信度阈值0.0–1.0默认 0.7、max_persons1–10默认 5、tracking_enabled默认 true。仓库提供了与之对应的实装 Schemadocs/schemas/pose-observation-v2.schema.json 中joints数组强制minItems17/maxItems17关节kind枚举与 Keypoint Model 的 17 点命名完全一致且比规划文档更进一步额外引入timestamp_ns、sensor_epoch、sourcesensor_id/authenticated/replay_protected对应鉴权与防重放、modelid/artifact_hash对应模型溯源与covariance_m2不确定性建模。这体现了从“规划接口”到“可验证数据契约”的演进。5. 鉴权与授权Bearer TokenJWTAuthorization: Bearer token默认 24 小时过期payload 含sub、iat、exp、scope数组与domainAPI KeyX-API-Key: api_key用于服务间通信作用域限定在特定端点授权作用域pose:read、pose:stream、system:control、system:status、config:read、config:write、alerts:manage、admin:full领域化访问控制healthcare 域附加 HIPAA 合规要求、retail 域保护客户隐私、security 域增强审计日志、general 域使用标准控制。规范要求对敏感操作记录审计日志。RuView 仓库对“可信身份与防重放”有更强的实装要求pose-observation-v2.schema.json的source.authenticated与source.replay_protected字段要求每条观测标注传感器身份与防重放状态docs/adr/ADR-305-authenticated-sensor-identity.md、docs/adr/ADR-327-governed-action-intents-and-witness-receipts.md 等 ADR 延续了“证据可溯源”的主线。若按本规范实现 REST 服务建议在 JWT 中至少携带sub用户/服务标识与scope并以domain字段驱动领域级策略。6. 外部集成 API6.1 MQTT 集成主题树采用wifi-densepose/根前缀分四组pose/person/{person_id}单人数据、summary聚合、raw原始帧alerts/fall_detection、intrusion、systemstatus/system、hardware、networkanalytics/healthcare、retail、security。消息格式示例单人姿态消息timestamp/person_id/confidence/keypoints/activity/location与告警消息alert_id/type/severity/location/confidence。仓库中 MQTT 已有真实验证脚本 scripts/validate-esp32-mqtt.sh该脚本先本地拉起mosquittobrokerallow_anonymous、日志输出到 stdout再用mosquitto_sub -t homeassistant/#捕获主题、解析并核对覆盖矩阵最后用mosquitto_pub发健康检查消息验证 HA 发现主题与至少一条状态主题。这说明 MQTT 主题契约在本仓库以 Home Assistant 集成为主要消费方参见 docs/integrations/home-assistant.md 与 docs/adr/ADR-115-home-assistant-integration.md。6.2 Webhook 集成POST /webhooks注册回调端点指定url、订阅事件fall_detection、person_detected 等、鉴权方式bearer token与重试策略max_retries3、retry_delay_seconds5。事件载荷统一包裹webhook_id、event_type、timestamp、data与metadataenvironment_id、system_version。6.3 Restream 集成POST /streaming/restream配置多平台直播youtube/twitch/facebook含视频参数分辨率 1280x720、30fps、bitrate 2500与叠加层show_keypoints/show_confidence/show_person_ids/transparent 背景GET /streaming/status返回各平台连接状态、观看人数、运行时长与视频统计fps、bitrate、丢帧数。这一能力与仓库可视化组件如 ui/observatory/属于同一展示链路属于规划中的对外广播能力。7. 错误处理与状态码成功200 / 201 / 202 / 204客户端错误400参数非法、401未鉴权/凭证无效、403权限不足、404资源不存在、409冲突如系统已在运行、422校验失败、429限流服务端错误500 / 502 / 503系统未就绪或过载/ 504。错误响应采用统一信封error.code机器可读如POSE_DATA_NOT_FOUND、VALIDATION_ERROR、message、details含请求范围与可用范围、字段级错误field_errors、timestamp、request_id便于链路追踪。这种格式与 RuView 强调的“证据可追溯”精神一致——每条错误都能定位到具体请求。8. 限流与性能指标限流配置REST 每 API Key 每小时 1000 请求WebSocket 每 IP 100 连接流式每账户 10 并发流Webhook 每端点每小时 10000 事件。限流响应头X-RateLimit-Limit/X-RateLimit-Remaining/X-RateLimit-Reset/X-RateLimit-Window。性能目标95 百分位姿态端点 100ms、系统控制 500ms、配置更新 200ms、WebSocket 消息 50ms吞吐目标REST 1 万 req/s、WebSocket 1000 并发连接、姿态更新 30 FPS/流、告警端到端 1s。这些是规划目标需要实装后通过压力测试验证读者不应将其视为已测量数据。9. API 版本化与兼容性URL 版本化当前/api/v1/未来/api/v2/、/api/v3/保持向后兼容Header 版本化Accept: application/vnd.wifi-densepose.v1json、API-Version: 1.0弃用策略提前 6 个月通知、弃用后支持 12 个月、提供迁移文档与工具弃用响应头Deprecation: true、SunsetRFC 850 格式、Link指向 successor-version。仓库侧对版本契约的重视在 docs/adr/ADR-298-model-release-sanity-gates.md模型发布门禁等 ADR 中均有体现可视为版本兼容纪律的旁证。10. 测试与验证策略测试类别单元测试单端点、集成测试端到端工作流、性能测试负载/压力、安全测试鉴权授权、契约测试Schema 校验。测试数据管理合成姿态数据、真实 CSI 录制数据、Mock 外部服务、隔离测试环境。文档测试要求 OpenAPI 规范合规、示例可执行、链接可用、代码示例可运行。仓库中与之呼应的测试资产docs/schemas/pose-observation-v2.schema.json 本身可作契约测试基准aether-arena/fixtures/ 提供 smoke 预测/分割 JSON 与期望 hashaether-arena/calibration/test_calibration.py 与 aether-arena/calibration/test_cog_calibration.py 覆盖校准回归scripts/validate-esp32-mqtt.sh 是集成级验证脚本。11. 验收标准功能验收所有端点实现可用、响应符合 Schema、鉴权授权生效、WebSocket 流 50ms 延迟性能验收95 百分位响应达标、吞吐达标、限流正确、可扩展集成验收MQTT/Webhook/Restream 可用、错误处理完备、文档完整准确、自动化测试覆盖。12. 落地路径与仓库对照api-spec.md 是 Phase 1 的规划蓝图Draft 状态仓库目前以“文档契约先行、实现分阶段落地”的方式推进。若要在 RuView 中实现这套 API可参考以下对照关系规范章节仓库对应资产说明4 数据模型docs/schemas/pose-observation-v2.schema.json17 关节、置信度、协方差、传感器身份已实装2.2 系统状态scripts/ruview-sensing-server.py、scripts/check_health.py传感服务器与健康检查脚本6.1 MQTTscripts/validate-esp32-mqtt.sh、docs/integrations/home-assistant.mdHA 主题契约与验证脚本2.1 姿态数据aether-arena/calibration/infer.py、aether-arena/fixtures/推理与 fixtures3 WebSocketdocs/adr/ADR-055-integrated-sensing-server.md、docs/adr/ADR-136-ruview-streaming-engine-frame-contracts.md流式架构与帧契约5 鉴权docs/adr/ADR-305-authenticated-sensor-identity.md、docs/adr/ADR-141-bfld-privacy-control-plane-modes-attestation.md传感器身份与隐私控制面整体而言这份 API 规范的价值在于它把“WiFi 无摄像头感知”从研究原型抽象成一套标准化的产品级接口——REST 面向读写与查询、WebSocket 面向低延迟实时分发、MQTT/Webhook 面向外部系统对接、JWT/Scope 面向多租户多领域授权。结合 RuView 仓库已有的 Schema、MQTT 验证脚本与 ADR 证据链开发者可以此规范为蓝本在 RuView 传感链路上逐步落地可验证的对外 API 服务。【免费下载链接】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），仅供参考