RuView 插件契约：面向 Claude Code 与 Codex 的 WiFi 感知一体化插件设计（ADR-0001 全解）-育师

RuView 插件契约：面向 Claude Code 与 Codex 的 WiFi 感知一体化插件设计（ADR-0001 全解）

【免费下载链接】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（WiFi-DensePose）是一个横跨 Rustv2/、Pythonarchive/v1/、ESP32 固件与 96+ 份 ADR 的大型双代码库项目，新人与运维人员反复重做同样的工作流：拉起 Docker 演示、烧录并配置 ESP32、运行感知应用、训练姿态模型、执行见证校验。ADR-0001 决定把这些工作流打包成一个可通过 Claude Code 市场发现、并为 Codex 镜像的ruview一体化插件，用"技能（skill）+ 命令（command）+ 代理（agent）"三层结构覆盖从入门到进阶的完整操作面。读完本文，你将掌握该插件的目录契约、命名空间规则、shell-first 技能约束、Codex 命令对齐策略与 smoke 结构校验的全部设计细节，并能在本地直接安装、运行与验证它。

背景：为什么需要插件化

ADR-0001（plugins/ruview/docs/adrs/0001-ruview-plugin-contract.md，状态Proposed，日期 2026-05-11）开篇点明了核心痛点：RuView 项目规模庞大——Rust 侧的v2/crates/、Python 侧的archive/v1/、firmware/esp32-csi-node/固件，以及以docs/adr/下 ADR 序列承载的持续演进决策。反复被重新推导的典型工作流包括：

启动 Docker 演示环境；
烧录并配置一个 ESP32 节点；
运行一个感知应用（存在检测 / 生命体征 / 姿态 / 睡眠 / MAT）；
训练姿态模型（无相机与相机监督两条路线）；
执行见证验证（witness verification）信任流水线。

这些工作流散落在 README、docs、scripts 与 ADR 中，缺乏单一入口。ADR-0001 的目标是把它们打包为一个可发现的 Claude Code 插件（并为 Codex 镜像），覆盖 practical → advanced 的完整梯度。

决策一：单一 mega-plugin，仓库根目录市场清单

ADR 的第一项决策是不拆子插件，而是做一个单一插件ruview，由仓库根目录的.claude-plugin/marketplace.json在市场上挂名：

市场名（marketplace name）为ruview；
插件source指向./plugins/ruview；
清单必须位于仓库根目录，因为Claude Code 只在克隆仓库的根目录查找.claude-plugin/marketplace.json，不会在子目录中查找；
插件的广度不靠子插件组织，而靠skill（技能）组织。

仓库中的 .claude-plugin/marketplace.json 与 ADR 完全一致：

{ "name": "ruview", "description": "RuView Marketplace: Claude Code + Codex plugins for WiFi sensing — configuration, applications, model training, and onboarding, from practical to advanced", "owner": { "name": "ruvnet" }, "plugins": [ { "name": "ruview", "source": "./plugins/ruview", "description": "End-to-end RuView toolkit: getting started, ESP32 hardware setup, configuration, sensing applications ... and witness verification" } ] }

对应地在 Claude Code 中的安装方式为：

/plugin marketplace add ruvnet/RuView /plugin install ruview@ruview

即先把本仓库注册为插件市场，再安装ruview@ruview（市场名ruview、插件名ruview）。

决策二：目录契约（Directory Contract）

ADR 用一棵目录树定义了插件的物理布局，这是整个契约的骨架：

.claude-plugin/marketplace.json # REPO ROOT — 市场名 ruview，插件 source ./plugins/ruview plugins/ruview/.claude-plugin/plugin.json # name, description, version, author, homepage, license, keywords —— 不含 skills/commands/agents 数组 plugins/ruview/skills/<name>/SKILL.md # frontmatter: name, description, allowed-tools plugins/ruview/commands/<name>.md # frontmatter: description (+ argument-hint) plugins/ruview/agents/<name>.md # frontmatter: name, description, model plugins/ruview/docs/adrs/0001-ruview-plugin-contract.md plugins/ruview/scripts/smoke.sh # 结构契约 plugins/ruview/codex/AGENTS.md + codex/README.md + codex/prompts/*.md # Codex 镜像 plugins/ruview/README.md # Compatibility + Namespace coordination + Verification + ADR 章节

技能 / 命令 / 代理是自动发现的——它们刻意不出现在plugin.json中，而是靠目录树约定让 Claude Code 发现。实际仓库的 plugins/ruview/.claude-plugin/plugin.json 验证了这一约定：它只声明name、description、version（当前 0.3.0）、author、homepage、license（MIT）与keywords（ruview、wifi-densepose、wifi-sensing、csi、esp32、pose-estimation、vital-signs、edge-ai、model-training、onboarding 等），没有任何 skills/commands/agents 数组。

值得一提的实现细节：plugin.json中同时声明了一个名为rvagent的mcpServers配置（npx -y @ruvnet/rvagent，默认RVAGENT_SENSING_URL=http://localhost:3000）。这与 ADR 决策三"技能不依赖mcp__claude-flow__*"并不矛盾——ADR 约束的是skill 的allowed-tools，而rvagent是插件额外携带的可选 MCP 服务，用于 rvAgent/RVF 代理流，属于实际代码对 ADR 的演进补充。

按此目录契约，实际仓库当前的内容为：

10 个技能：ruview-quickstart、ruview-hardware-setup、ruview-configure、ruview-applications、ruview-model-training、ruview-advanced-sensing、ruview-cli-api、ruview-mmwave、ruview-verify、ruview-rvagent；
7 个命令：/ruview-start、/ruview-flash、/ruview-provision、/ruview-app、/ruview-train、/ruview-advanced、/ruview-verify；
3 个代理：ruview-onboarding-guide、ruview-config-engineer、ruview-training-engineer。

注意：ADR 正文列出的技能集为 9 个，而仓库实际已增长到 10 个（新增ruview-rvagent），Codex 提示也相应多出ruview-rvagent.md——这是 ADR 处于 Proposed 状态、代码库持续演进的直接证据，smoke 脚本只校验"期望技能集存在"，不阻止新增。

决策三：Shell-first 技能与 allowed-tools 最小化

ADR 明确：技能直接驱动 RuView 自己的工具链——cargo、python、idf.py（经CLAUDE.local.md中的 Windows Python 子进程模式）、docker、node脚本。为此：

allowed-tools被限制为核心工具集Bash Read Write Edit Glob Grep；
不依赖mcp__claude-flow__*工具；
不允许通配符工具（wildcard tools，即*/all tools）；
唯一被引用的外部 CLI 是npx @claude-flow/cli@latest security scan，且仅作为安全变更时的可选步骤。

以 plugins/ruview/skills/ruview-quickstart/SKILL.md 为例，其 frontmatter 为：

--- name: ruview-quickstart description: Onboarding and first-run for RuView (WiFi-DensePose) — Docker demo with simulated data, repo build, and the fastest path to a live sensing dashboard. ... allowed-tools: Bash Read Write Edit Glob Grep ---

该技能给出了三条从零到可运行的路径：

Tier 0（无硬件，2 分钟）：docker pull ruvnet/wifi-densepose:latest后docker run -p 3000:3000 ...，用模拟 CSI 数据体验完整 UI 与 API；
Tier 1（源码构建）：cd v2 && cargo test --workspace --no-default-features（1400+ 测试，约 2 分钟）、cargo check -p wifi-densepose-train --no-default-features，以及确定性 Python 证明python archive/v1/data/proof/verify.py（必须输出VERDICT: PASS；若 numpy/scipy 升级导致哈希漂移，先--generate-hash再复跑）；
Tier 2（真机感知）：cargo run -p wifi-densepose-sensing-server消费 ESP32 UDP CSI 流，配合node scripts/rf-scan.js --port 5006与node scripts/snn-csi-processor.js --port 5006。

技能还明确了硬件边界：ESP32-C3 与初代 ESP32 不受支持（单核无法跑 CSI DSP 流水线），应使用 ESP32-S3（8MB 或 4MB）或 ESP32-C6；单节点空间分辨率有限，建议 2 个以上节点或引入 Cognitum Seed。

决策四：命名空间`ruview-*`

插件声明独占 kebab-case 的ruview-*命名空间，覆盖三类对象：

技能：ruview-quickstart、ruview-hardware-setup、ruview-configure、ruview-applications、ruview-model-training、ruview-advanced-sensing、ruview-cli-api、ruview-mmwave、ruview-verify；
命令：/ruview-start、/ruview-flash、/ruview-provision、/ruview-app、/ruview-train、/ruview-advanced、/ruview-verify；
代理：ruview-onboarding-guide、ruview-config-engineer、ruview-training-engineer。

约束还包括：插件不写入任何claude-flow内存命名空间；与ruflo市场零重叠（ruview-*vsruflo-*）；若两者同时存在，遵循ruflo-agentdbADR-0001 的 "Namespace convention" 章节让位。命名空间约定同时写入 plugins/ruview/README.md 的 "Namespace coordination" 一节，供 smoke 脚本校验其存在。

决策五：Codex 镜像——完整命令对齐

每一个/ruview-*命令都必须有对应的codex/prompts/<name>.md，这是 ADR 对 Codex（OpenAI CLI）镜像的硬性要求：

codex/AGENTS.md携带项目规则；
codex/README.md文档化安装方式；
镜像完整覆盖面向运维的命令（7 个）；
额外的技能与代理没有 Codex 等价物——其知识被折叠进AGENTS.md与 prompt 文件；
smoke 脚本强制执行命令 ↔ prompt 的存在性对齐。

仓库的 plugins/ruview/codex/README.md 给出了安装细节：把 prompt 拷入 Codex 提示目录（mkdir -p ~/.codex/prompts && cp plugins/ruview/codex/prompts/*.md ~/.codex/prompts/），随后即可在 codex TUI 中使用/ruview-start、/ruview-flash、/ruview-app、/ruview-train、/ruview-verify、/ruview-advanced；项目规则则通过符号链接根AGENTS.md或追加相关章节接入。

plugins/ruview/codex/AGENTS.md 进一步界定了 prompt 文件的行为底线：默认只读探索、引用当前仓库路径与已接受的 ADR、保留MEASURED/CLAIMED/SYNTHETIC证据标签、绝不发出沙箱/权限绕过或无人值守的硬件写入、绝不内嵌凭据与机器特定端口、持久性发现需走已评审的 shared-brain 提案流程。它还推荐优先使用已发布且锁版本的适配器而非手拼codex exec参数：

npx @ruvnet/ruview@0.3.1 guidance --topic architecture --query "requested subsystem" npx @ruvnet/ruview@0.3.1 agent run --host codex --repo . --prompt "..." npx @ruvnet/ruview@0.3.1 brain search --query "relevant repository concept"

并以 stdin、可信-C根目录、只读沙箱、临时 JSONL、严格配置、净化环境、限时输出与密钥脱敏为运行前提；写入需同时携带--allow-write与--confirm。

决策六：兼容性表面

ADR 明确了插件面向的目标仓库布局：

Rustv2/crates/、固件firmware/esp32-csi-node/、Pythonarchive/v1/、脚本scripts/、文档docs/adr/；
硬件文档默认 ESP32 串口为COM8，并始终提示读者确认实际端口；
Windows 上 ESP-IDF 构建走CLAUDE.local.md中的 Python 子进程模式（ESP-IDF v5.4 不支持 Git Bash/MSYS2）。

以 plugins/ruview/skills/ruview-hardware-setup/SKILL.md 为佐证，该技能完整覆盖了兼容性边界的落地细节：

设备	Flash	芯片	角色
ESP32-S3（8MB）	8 MB	Xtensa 双核	WiFi CSI 感知节点（默认）
ESP32-S3 SuperMini	4 MB	Xtensa 双核	紧凑 CSI 节点，用`sdkconfig.defaults.4mb`
ESP32-C6 + Seeed MR60BHA2	—	RISC-V + 60 GHz FMCW	mmWave HR/BR/存在检测

不支持：初代 ESP32、ESP32-C3（单核）。技能还特别警告硬币尺寸克隆板（ESP32-S3-Zero、SuperMini 等）在此固件下会持续高电流（WIFI_PS_NONE+edge_tier=2全 DSP 流水线），出现过小型稳压器损坏、重启后无法开机的现场报告，部署后头几分钟需触摸检查温度并保证通风。

Windows 构建的实测命令以 Python 子进程方式剥离MSYSTEM*环境变量后调用 ESP-IDF v5.4 工具链，常见问题排查表包括：MSys/Mingw is no longer supported（需剥离MSYSTEM*）、cmake not found（注意真实路径含版本目录cmake\3.30.2\cmake-3.30.2-windows-x86_64\bin）、无 CSI 帧到接收端（重跑provision.py、--channel对齐 AP、放宽--filter-mac）等。

决策七：smoke 契约（≥13 项检查）

ADR 用 plugins/ruview/scripts/smoke.sh 固化结构契约，运行方式：

bash plugins/ruview/scripts/smoke.sh

脚本以set -u运行，自动解析插件根与仓库根（本文件位于<root>/scripts/smoke.sh），逐项断言，最终输出PASS: N FAIL: M，任一 FAIL 则以退出码 1 结束。其检查面（对应 ADR 的 13 项要求）为：

仓库根.claude-plugin/marketplace.json存在、列出"ruview"、source指向"./plugins/ruview"；
plugin.json含name/description/version；
plugin.json含keywords；
plugin.json不含skills/commands/agents数组（自动发现）；
每个skills/*/SKILL.md含name:+description:+allowed-tools:，且allowed-tools无通配符（*/all tools）；
期望技能集全部存在（脚本内置ruview-quickstart ruview-hardware-setup ruview-configure ruview-applications ruview-model-training ruview-advanced-sensing ruview-cli-api ruview-mmwave ruview-verify九个）；
每个commands/*.md有description:frontmatter；
每个agents/*.md有name:+description:+model:；
README 含## Compatibility与Namespace coordination；
ADR-0001 存在且状态为Status: Proposed；
Codex 镜像存在（codex/AGENTS.md+codex/prompts/*.md）； 11b. 命令 ↔ prompt 对齐：每个commands/<name>.md都有同名codex/prompts/<name>.md；
.claude-plugin/下无错放的 skills/commands/agents（该目录只允许plugin.json）。

其中第 4 项是"自动发现"约定的可执行化，第 11b 项把 Codex 镜像对齐变成了每次提交可回归的机械检查。注意 ADR 只承诺命令↔prompt 的存在性对齐，不校验内容一致性——这是其 Cost 部分明确承认的局限。

影响与代价（Consequences）

正面收益（Good）：

/plugin marketplace add ruvnet/RuView+/plugin install ruview@ruview（或从克隆目录claude --plugin-dir ./plugins/ruview）即可让新人与运维人员获得 RuView 完整工作流表面；
无 MCP server 前置条件（技能自带最小工具集）；
Codex 用户获得同样的运维命令；
smoke 脚本让结构漂移（drift）可见，随时可发现。

代价（Cost）：

mega-plugin 粒度较粗——要么获得全部 9（现 10）个技能，要么一个都没有；
Codex 镜像需手工保持同步，smoke 只查命令↔prompt 的存在性而非内容对齐；
技能干名与命令干名存在碰撞：ruview-verify既是技能又是命令，Claude Code 容忍两者同时解析，但claude plugin details会将其列出两次。

后续事项（Follow-ups）：

若技能集超过舒适浏览规模（当前已 9→10），重新评估"单一 mega-plugin"决策，按生命周期拆分（ruview-edge、ruview-train等）；
为命令与 Codex prompt 增加内容级一致性 lint；
考虑重命名/ruview-verify以消除技能/命令干名碰撞；
若 security-scan 步骤变得关键，为claude-flowCLI 锁定经过测试的 minor 版本；
用实际仓库树核对 RuView 命令的真实参数（sensing-server --help、gcloud-train.sh、provision.py），而非仅依赖 README/scripts。

安装、验证与延伸阅读

安装（Claude Code）：

/plugin marketplace add ruvnet/RuView /plugin install ruview@ruview # 或本地免安装试用： claude --plugin-dir ./plugins/ruview

安装（Codex）：见 plugins/ruview/codex/README.md——拷入~/.codex/prompts/后即可用/ruview-*命令；规则经AGENTS.md接入。

结构验证：

bash plugins/ruview/scripts/smoke.sh

实操延伸：技能目录提供了可直接复用的端到端流程——ruview-quickstart（三档快速起步）、ruview-hardware-setup（固件构建/烧录/配网/串口确认）、ruview-model-training（无相机 WiFlow 姿态、相机监督 ADR-079 92.9% PCK@20、RuVector AETHER 嵌入、MERIDIAN 域泛化、GCloud GPU 训练与 Hugging Face 发布）；命令侧可对照 plugins/ruview/commands/ruview-verify.md 与 plugins/ruview/codex/prompts/ruview-verify.md 理解同一信任流水线在两种 CLI 下的对称实现（tests/proof/bundle/all四种作用域，VERDICT: PASS与 witness bundle 7/7 PASS 为硬性出口条件）。

架构决策索引：plugins/ruview/README.md 的 Architecture Decisions 章节指向本文档；市场清单位于仓库根 .claude-plugin/marketplace.json；插件元数据位于 plugins/ruview/.claude-plugin/plugin.json。本文档状态为 Proposed，代码库已在技能数、Codex 提示与rvagentMCP 服务上超出 ADR 原始列举，阅读时请以仓库实际内容为准。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

RuView 插件契约：面向 Claude Code 与 Codex 的 WiFi 感知一体化插件设计（ADR-0001 全解）