RuView MCP 服务与 CLI 分发架构面向 AI Agent 的 WiFi 感知能力接入方案ADR-104 深度解析【免费下载链接】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导读本指南以仓库内 ADR-104-ruview-mcp-cli-distribution.md 为骨架系统讲解 RuView 如何把「WiFi 信号 → 人体姿态/人数/生命体征」这套原本绑定在 Cognitum 设备Pi 5 / PiHailo 集群上的推理能力通过npxCLI 与 Model Context ProtocolMCPServer 两种形态开放给开发者 AgentClaude Code / Cursor / Codex、CI 流水线与 shell 脚本使用。读完你将掌握MCP Server 与 CLI 的完整工具面设计、fail-open 容错模型、基于 env 变量的安全边界Bearer Token 子进程注入防护 Ed25519 签名信任链、npm 打包与claude mcp add注册步骤以及六项验收门槛对应的真实代码位置与当前实现演进状态。1. 决策上下文为什么需要一套「无需设备」的接入层RuView 的推理主力走的是 Cognitum cog 生态cog 二进制经由签名后的 GCS 目录ADR-100下发到设备运行在 Pi 5 或 PiHailo 集群节点的/var/lib/cognitum/apps/下。这是生产推理的正确部署形态——按 ADR-104 的表述其具备亚 5ms/帧级延迟、Hailo 硬件加速与离线运行能力。但有三类用户并没有 Cognitum 设备却需要调用 RuView 能力开发者 Agent——Claude Code、Cursor、Codex 希望在研究会话中直接调用ruview_pose_infer例如 SOTA 迭代循环。CI 流水线——自动测试希望断言「一段合成 CSI 窗口能产出有限姿态输出」而不需要整套设备安装。Shell 脚本与研究者——在任何装有 Node 20 的机器上执行npx ruview pose infer --window ./window.json无需 Rust 工具链、无需 Cognitum 账号、无需克隆本仓库。ADR-104 梳理了既有接入面的三个缺口sensing-server REST API/api/v1/sensing/latest、/api/v1/edge/registry是 Rust 二进制需从源码构建cog 二进制是签名的 Linux aarch64/x86_64 可执行文件没有 macOS/Windows 构建也没有npx入口没有 MCP Server——Claude Code 无法把 RuView 能力当作工具调用。为此ADR-104 定义了两个新的分发产物本文即其设计蓝图产物作用MCP Server通过 stdio 暴露 RuView 为 Agent 可调用的工具CLI以npx ruview 子命令暴露同一能力面从源码实现看当前设计蓝图已落地于 tools/ruview-mcp/ 与 tools/ruview-cli/ 两个 TypeScript 包中且后续经 ADR-264、ADR-265 深度评审后MCP 包的发布名从 ADR-104 拟定的ruv/ruview-mcp演进为ruvnet/rvagent详见 第 11 节。2. MCP Server 核心设计六个工具与 stdio 传输MCP Server 是 Node 20 TypeScript 包基于modelcontextprotocol/sdk实现默认走 stdio 传输对外暴露六个工具工具描述后端ruview_csi_latest从 sensing-server 拉取最新 CSI 窗口GET /api/v1/sensing/latestADR-102ruview_pose_infer在 CSI 窗口上做 17 关键点 COCO 姿态估计cog-pose-estimation 二进制ADR-101子进程ruview_count_infer带校准置信区间的人数统计cog-person-count 二进制ADR-103子进程ruview_registry_list列出 edge registry 中的 Cognitum cogsGET /api/v1/edge/registryADR-102ruview_train_count触发 count-cog 的 Candle 训练cargo run -p wifi-densepose-train子进程ruview_job_status轮询后台训练任务读取~/.ruview/jobs/id.log这六个工具的注册表在源码中有完整的一一对应见 tools/ruview-mcp/src/index.ts#L94-L154。其中ruview_pose_infer的入参契约Zod schema定义了可选字段window_path与cog_binary传入 CSI 窗口 JSON 文件路径即可脱离 sensing-server 单跑推理缺省时回退到实时 sensing-server 的最新窗口pose-infer.ts。2.1 Fail-open 容错原则每个工具在出错时返回结构化错误对象而非抛异常{ ok: false, warn: true, error: ..., hint: ... }这与 cog 二进制ADR-100 §Failure modes采用的模式一致其设计意图是一个暂时故障的 sensing-server不应使研究 Agent 的会话崩溃。真实的 MCP 调用实现同样延续了这一约定——CLI 与 MCP 的语义是「warn不是 crash」。3. CLI 子命令面与 MCP 工具的等价映射同一能力面以 Yargs CLI 形式打包二进制名ruview子命令等价 MCP 工具ruview csi tailruview_csi_latest的流式轮询ruview pose infer [--window path]ruview_pose_inferruview count infer [--window path]ruview_count_inferruview cogs list [--category] [--search]ruview_registry_listruview train count --paired jsonlruview_train_countruview job status --id uuidruview_job_status从当前源码看CLI 的子命令注册与 ADR 完全一致tools/ruview-cli/src/index.ts#L8-L14 列出了csi tail / pose infer / count infer / cogs list / train count / job status六个子命令分别实现在commands/csi.ts、commands/pose.ts、commands/count.ts、commands/cogs.ts、commands/train.ts、commands/job.ts。两条输出约定值得注意所有子命令成功时向 stdout 输出 JSON 并退出码 0WARN 级输出如 cog 二进制缺失、sensing-server 不可达写 stderr但退出码仍保持 0避免瞬时不可用打断流水线。4. 推理后端选型子进程而非进程内推理MCP Server 与 CLI选择 shell out 到 cog 二进制而不是在 JS/WASM 内嵌推理引擎。ADR-104 给出三条理由复用已验证产物——cog 二进制已签名、已测试、已交叉编译ADR-100/101/103。在 JS 里重写推理会重复劳动并产生第二个需要同步维护的模型工件。cog 负责复杂栈——模型加载、ONNX 分发、Hailo HEF 路由全部由 cog 透明处理MCP 层只需理解 JSON 事件 schema。训练路径已被验证——cargo run -p wifi-densepose-train是既有成熟路径据 ADR-103 记载在 RTX 5080 上约 2.1s在 JS 里复刻 Candle 训练循环是无用户收益的重大工程投入。因此 npm 包本质上是Rust/cog 基础设施之上的薄编排层不捆绑任何 ML 框架。该决策在源码的 cog.ts 中得到印证runCog()通过 Node 的spawn(binary, args, {timeout: 15000, stdio: [...]})执行 cog 的version / manifest / health / run子命令并对非零退出码与启动失败做结构化错误返回。4.1 ruvector 库的使用边界ADR-104 明确「凡已有 ruvector npm 包提供的能力优先复用而非重写」。examples/research-sota/r5_subcarrier_saliency.py已依赖ruvector-mincutRust crate实现 Stoer-Wagner 最小割。在 npm 侧ruv/rvcsi提供类型化的 CSI 帧 schema 与校验安装时可用则ruview_csi_latest会对入站帧做 rvcsi-core schema 校验否则回退为不透明 JSON 直通HNSW、RaBitQ、对比嵌入等原语保持 Rust 原生npm 包不复刻ruview_pose_infer/ruview_count_infer把推理委托给内嵌 Candle 引擎的 cog 二进制。5. 源码布局ADR-104 规划的目录结构已实际落地于仓库tools/ ├── ruview-mcp/ # MCP Server 包 │ ├── package.json │ ├── tsconfig.json │ ├── jest.config.js │ ├── src/ │ │ ├── index.ts # MCP server 入口 工具注册表 │ │ ├── types.ts # 共享领域类型 │ │ ├── config.ts # 环境变量配置加载器 │ │ ├── http.ts # 带超时的 fetch 封装 ResultT │ │ ├── cog.ts # cog 二进制子进程封装 │ │ └── tools/ │ │ ├── csi-latest.ts # ruview_csi_latest │ │ ├── pose-infer.ts # ruview_pose_infer │ │ ├── count-infer.ts # ruview_count_infer │ │ ├── registry-list.ts # ruview_registry_list │ │ └── train-count.ts # ruview_train_count ruview_job_status │ └── tests/ │ └── tools.test.ts # stub 冒烟测试 集成测试 └── ruview-cli/ # CLI 包 ├── package.json ├── tsconfig.json ├── src/ │ ├── index.ts # yargs CLI 入口 命令注册 │ ├── config.ts # 环境变量配置加载器 │ ├── http.ts # fetch 封装 │ ├── cog.ts # 子进程封装 │ └── commands/ │ ├── csi.ts # ruview csi tail │ ├── pose.ts # ruview pose infer │ ├── count.ts # ruview count infer │ ├── cogs.ts # ruview cogs list │ ├── train.ts # ruview train count │ └── job.ts # ruview job status └── tests/实际仓库在该骨架之上有所扩展MCP 服务已增补schemas/、http-transport.ts、validate.ts等模块并在tests/下维护了多组测试tools.test.ts、schemas.test.ts、config.test.ts、vitals-tools.test.ts、train-count-reconcile.test.ts等CLI 目前以 jest 空配置运行--passWithNoTests集成测试集中在 MCP 包一侧。6. 配置模型全部来自环境变量MCP 与 CLI 均不要求配置文件开箱即用指向本机默认端口上的 sensing-server。完整配置项见 config.ts 与 types.ts环境变量作用默认值RUVIEW_SENSING_SERVER_URLsensing-server 基址http://localhost:3000RUVIEW_API_TOKEN/api/v1/*路由的 Bearer Token缺省关闭鉴权无RUVIEW_POSE_COG_BINARYcog-pose-estimation 二进制路径自动探测见下RUVIEW_COUNT_COG_BINARYcog-person-count 二进制路径自动探测见下RUVIEW_JOBS_DIR训练任务日志目录~/.ruview/jobscog 二进制路径探测值得展开cogBinaryCandidates()按「原生架构优先」顺序探测——arm64 主机先试/var/lib/cognitum/apps/id/cog-id-armx64 主机先试同目录下cog-id-x86_64再回退/usr/local/bin/name最后以裸名走 PATH 解析config.ts#L63-L74。源码注释明确指出这是为规避此前「无条件先试 -arm」导致的错误架构二进制问题ADR-264 F8/O7 评审结论顺序可注入便于单元测试。这与 ADR-100 的设备安装惯例/var/lib/cognitum/apps/cog-id/保持一致。7. 安全模型7.1 认证sensing-server 对配置了 token 时的全部/api/v1/*路由使用 Bearer TokenRUVIEW_API_TOKEN。MCP/CLI 在每次 sensing-server 调用的Authorization头中透传该 token。关键约束token只允许来自环境变量——绝不来自 CLI flag 或工具参数后者可能出现在日志或 Agent 历史中。cog 二进制以本地子进程调用不涉及网络认证——二进制在安装时已通过 Ed25519 签名验证ADR-100本地安装即信任。7.2 威胁表#威胁缓解T1MCP 工具伪造——恶意进程在合法 Server 之前注册名为ruview_pose_infer的工具并截获 Agent 调用MCP Server 由操作者在 Claude Code / Cursor 配置中显式注册claude mcp add ruview -- node …。冒名需要攻陷操作者的 shell 配置。T2CLI 子命令注入——调用方传入含 shell 元字符的--paired路径逃逸 cargo 调用所有子进程参数以数组方式经 Nodespawn(binary, args, {})传递绝不经过 shell 字符串无 shell 展开路径元字符无法逃逸。T3Token 泄露——RUVIEW_API_TOKEN出现在进程参数、Agent 历史或日志Token 仅程序化设置于AuthorizationHTTP 头绝不打印、绝不作 CLI 参数、绝不写入~/.ruview/jobs/id.log。T4模型替换——攻击者以恶意版本替换 cog 二进制cog 二进制须在安装时通过 Ed25519 签名验证binary_sha256binary_signatureADR-100。MCP/CLI 层不在调用时复验——这是 cog-gateway 的职责。T5输出校验绕过——cog 返回畸形 JSON 且 MCP 直接转发ruview_pose_infer/ruview_count_infer解析 cog stdout 为 JSON 并按PoseInferResult/CountInferResult类型Zod校验 schema解析失败时返回{ok:false, error:unexpected cog output: …}。T6ruview_train_count限流绕过——Agent 紧循环调用触发无界训练进程MCP Server 维护进程内任务注册表若已有超过 3 个status:running的任务返回{ok:false, error:too many concurrent training jobs (max 3)}。训练任务受 CPU/GPU 约束且主机自限。威胁缓解在代码层的印证T2 的实现即 cog.ts 中spawn(binary, args, {...})数组传参T5 对应 Zod 工具 schema 与 index.ts 的tool.schema.safeParse()单一校验门。7.3 本 ADR 明确不覆盖的安全项MCP 传输加密——MCP over stdio 是进程本地通信无 TLS。未来若经 TCP socket 暴露必须引入 TLS。cog 二进制调用时认证——信任 OS 文件权限与安装时签名校验ADR-100。安装后被替换的二进制MCP 层无法察觉。多租户 token 隔离——Server 进程以单一 token 服务所有连接客户端。多用户部署须每用户一个 MCP Server 实例。8. 打包与注册8.1 版本对齐与 Semver 策略npm 包版本跟踪 cog crate 版本MCP/CLI 首个版本在cog-pose-estimation与cog-person-count同时上架 GCS 时发布Semver 约定MCP 工具 schema 变更破坏调用方 Agent→ major新增工具 → minorbug 修复 → patch。8.2 npm 包配置两个包目标 Node 20engines: {node: 20.0.0}bin指向编译产物dist/index.js。按 ADR-104 的拟定发布形态ruv/ruview-mcp — npm install -g ruv/ruview-mcp (then: ruview-mcp) ruv/ruview-cli — npm install -g ruv/ruview-cli (then: ruview --version)发布注意点实际 package.json 中均有体现开发期设置private: true发布前必须改为false或删除该字段publishConfig.access: public已预先配置。CLI 包当前仍为private: true bin 名ruview-cliMCP 包已演进为ruvnet/rvagent、bin 名rvagent/ruview-mcp版本号 0.2.0。8.3 注册到 Claude Code安装后全局或 npx通过以下命令接入 Claude Code# 通过 npx无需安装 claude mcp add ruview -- npx ruv/ruview-mcp # 通过全局安装 npm install -g ruv/ruview-mcp claude mcp add ruview -- ruview-mcp # 验证 claude mcp list # 应显示 ruview按当前实现源码 index.ts 顶部注释实际注册命令写作claude mcp add ruview -- npx -y ruvnet/rvagentMCP Server 以 stdio 为默认传输process.stderr输出启动日志以避免污染 MCP 协议流index.ts#L354-L358。9. 分发方式与运行前提npx ruview …可在任何装有 Node 20 的机器运行不依赖克隆本仓库、不依赖 Rust 工具链、不依赖 Cognitum 设备——尤其是不调用 cog 的命令如ruview cogs list只需一个 sensing-server URL。对需要调用 cog 的命令ruview pose infer、ruview count infercog 二进制须从 GCS 下载并放入PATH或用RUVIEW_POSE_COG_BINARY/RUVIEW_COUNT_COG_BINARY指定路径。下载 URL 遵循 ADR-100 命名规范https://storage.googleapis.com/cognitum-apps/cogs/x86_64/cog-pose-estimation-x86_64 https://storage.googleapis.com/cognitum-apps/cogs/arm/cog-pose-estimation-arm https://storage.googleapis.com/cognitum-apps/cogs/x86_64/cog-person-count-x86_64 https://storage.googleapis.com/cognitum-apps/cogs/arm/cog-person-count-armADR 同时预留了未来的ruview install cogs子命令用于自动化下载 chmod PATH 部署。10. 失败模式矩阵场景行为Sensing-server 未运行ruview_csi_latest/ruview_registry_list返回{ok:false, warn:true, error:…, hint:…}。CLI 退出码 0MCP 工具返回isError:false是 warn 而非 crash。cog 二进制未安装ruview_pose_infer/ruview_count_infer返回{ok:false, warn:true, error:…, hint:…}并附安装指引。cog 二进制返回非零以{ok:false, error:Cog exited with code N. stderr: …}传递。训练任务立即崩溃日志文件记录# exit code: N。ruview_job_status返回{status:failed, recent_log:[…]}。MCP Server 中途死亡进程内任务注册表丢失。已在运行的任务以 detached 方式继续后台执行操作者直接读日志文件。Node 20内置fetch不可用。CLI 打印明确错误Node 20 required for built-in fetch。从源码看runCog把启动失败ENOENT 等与退出码非零分别包装为结构化错误并对缺失二进制给出「设置RUVIEW_POSE_COG_BINARY/RUVIEW_COUNT_COG_BINARY或先在设备安装 cog」的定位 hintcog.ts#L45-L66MCP 调用门的 catch 分支把未预期异常统一转为{ok:false, error}的isError:true响应index.ts#L310-L325。11. 实现现状与演进从 ADR-104 到 ADR-264/265对照 ADR-104 与当前仓库实现可以看到该 ADR 已经历过后续深度评审并做了命名/边界修正阅读时值得区分「设计稿」与「当前源码」两层包名与 bin 名变化ADR-104 拟定ruv/ruview-mcp/ruv/ruview-clibinruview。ADR-264/265 落地后MCP 包发布名为ruvnet/rvagentbinrvagent与ruview-mcp并存CLI 保持ruv/ruview-cli且 bin 名改为ruview-cli——裸ruviewbin 归属ruvnet/ruview见 CLI 包描述 与 CLI index.ts 注释。工具命名规范ADR-264 O4 引入下划线规范命名host 工具名正则常限制为^[a-zA-Z0-9_-]{1,64}$。tools/list只宣告下划线形式旧的点号别名如ruview.bfld.last_scan仅作为路由别名保留一个弃用周期index.ts#L222-L229。工具面扩展当前 MCP 注册表在此前六个核心工具之外还注册了ruview_bfld_last_scan、ruview_bfld_subscribeADR-124 BFLD 工具、ruview_presence_now、ruview_vitals_get_breathing、ruview_vitals_get_heart_rate、ruview_vitals_get_allADR-124 Presence/Vitals 工具共 12 个工具index.ts#L155-L215。单一 Zod 校验门每个工具声明一个 Zod schemaCallTool 门解析一次后把带默认值的类型化结果交给 handler对外宣告的 JSON Schema 由同一 Zod 源生成保证「宣告即强制」ADR-264 O5index.ts#L270-L298。双传输默认 stdio 始终开启RVAGENT_HTTP_PORT显式开启 Streamable HTTP127.0.0.1 绑定 Origin 门控 可选 Bearer见http-transport.ts且惰性加载以免 stdio 路径付出额外加载成本。版本单源化两包均从package.json单源读取版本号避免入口文件与包版本漂移。领域类型层同样值得关注types.ts 完整镜像了 cog 与 sensing-server 的 JSON schema——CsiWindow56 子载波 × 20 帧的 ESP32-S3 标准形状、PoseInferResultCOCO 顺序 17 关键点 归一化[0,1]坐标、CountInferResult含count_p95_low/high与多节点融合时的per_node_breakdown、JobStatusResult含服务重启后 reconcile 出的unknown状态等是理解工具返回契约的最佳单点。12. 验收门槛与迁移计划12.1 六项验收门槛门槛测试npx ruview --version可用ruview --version打印0.0.1且退出码 0。ruview_pose_infer对合成 CSI 返回有限输出M2 集成测试spawn MCP Server用合成窗口 JSON 调用工具断言result.n_persons 0且所有关键点在[0, 1]。MCP Server 通过claude mcp list检查claude mcp add ruview -- node dist/index.js claude mcp list显示含 6 个工具的ruview。两包npm run build干净TypeScript 编译退出 0无错误。Stub 冒烟测试通过M1tools/ruview-mcp/中npm test全部 6 个 stub 测试通过。集成测试通过M6以 mock sensing-server 真实 node 二进制作 cog stub 的 6 次工具调用全部返回{ok: true}。源码侧对应演进路径清晰可循poseInfer目前通过执行cog-pose-estimation health该子命令会对合成窗口跑真实推理并发出结构化health.ok事件来同时验证 cog 可用性与产出推理结果恰好满足「合成 CSI → 有限姿态输出」的验收门槛注释明示window_path真实窗口推理属于 M3 里程碑pose-infer.ts#L87-L162。12.2 迁移 / 发布步骤首个 PR——落地脚手架tools/ruview-mcp/、tools/ruview-cli/ ADR-104两包保持private: true。M2——接通真实推理sensing-server CSI 窗口 → cog 子进程 → 解析输出从响应中移除stub: true。M3——接通ruview_csi_latestruview_registry_list的实时 sensing-server 往返测试。M4——接通ruview_train_count的真实 cargo 调用验证任务日志落盘。M6——集成测试全绿更新验收门槛。用户发布步骤——将两个package.json的private由true改为false然后# 发布 MCP Server cd tools/ruview-mcp npm version patch # 或按 semver 取 minor/major npm publish --access public # 发布 CLI cd tools/ruview-cli npm version patch npm publish --access public13. 关联阅读ADR-104 是 RuView 的「设备推理 ↔ Agent 接入」桥接层的架构基准建议按以下链条继续深入ADR-100——签名 GCS 分发的 cog 打包规范本 ADR 的安全信任根ADR-101——ruview_pose_infer调用的姿态估计 cogADR-102——ruview_registry_list依赖的/api/v1/edge/registry端点ADR-103——ruview_count_infer调用的多人数 cogADR-264 与 ADR-265——本文第 11 节所述演进包名、工具命名、HTTP 传输的来源动手验证与查阅最新工具面进入 tools/ruview-mcp/ 执行npm install npm test或按 package.json 的test脚本跑 Jest查看tools/ruview-mcp/tests/下各测试文件即可了解当前行为契约tools/ruview-mcp/README.md 是实际安装与使用的权威说明。【免费下载链接】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），仅供参考