@seeed-studio/solution-cli 0.1.0 → 0.3.0

package/docs/cli-guide.md

@@ -0,0 +1,264 @@
+# SenseCraft Solution CLI 使用与集成全景指南
+*(SenseCraft Solution CLI & AI Agent Skill Guide)*
+
+> **定位**：本文档专门面向**方案架构师、现场应用工程师 (FAE)、嵌入式开发者以及 AI Agent (Claude Code / Codex / Antigravity / Work Buddy)**，系统性说明 `@seeed-studio/solution-cli` 的独特应用场景、安装流程、各功能指令的具体使用方式以及核心产出物。
+
+---
+
+## 目录
+
+1. [独特使用场景与核心价值](#1-独特使用场景与核心价值)
+2. [安装与 Agent 技能挂载](#2-安装与-agent-技能挂载)
+3. [核心功能、使用方法与具体产出](#3-核心功能使用方法与具体产出)
+   - [场景一：方案探索与工况诊断 (Hub Search)](#场景一方案探索与工况诊断-hub-search)
+   - [场景二：硬件产品规格与配件防呆评估 (Product & BOM)](#场景二硬件产品规格与配件防呆评估-product--bom)
+   - [场景三：设备状态感知与参数热修改 (Device Management)](#场景三设备状态感知与参数热修改-device-management)
+   - [场景四：自研模型替换与本地二次开发 (Secondary Dev)](#场景四自研模型替换与本地二次开发-secondary-dev)
+4. [双轨运行机制：在线直连与离线托底](#4-双轨运行机制在线直连与离线托底)
+5. [常见问题与环境自检 (Doctor)](#5-常见问题与环境自检-doctor)
+
+---
+
+## 1. 独特使用场景与核心价值
+
+在传统边缘物联网与 AI 项目落地过程中，开发者通常面临以下痛点：
+- **方案选型盲目**：不清楚现场环境（集中还是分散、有无现有监控摄像头、有无市电）对硬件架构的致命影响；
+- **配件采购踩坑**：工控机买回后发现电源电压不符（如 12V 误插 19V 算力板）、DC 插头尺寸不对（5.5x2.1mm 插不进 5.5x2.5mm）、M.2 接口插槽类型搞混（Key-M 固态插不进 Key-E Wi-Fi 槽）；
+- **参数变更成本高**：改个 MQTT Broker 地址或算法置信度阈值就需要重新编译镜像或重装整套系统；
+- **AI Agent 缺乏边缘硬件感知**：纯大模型对话缺乏真实物理世界的接口约束，容易凭空编造不存在的硬件型号或非官方链接。
+
+`@seeed-studio/solution-cli` 正是为解决这一系列问题而生，它具有三大独特角色：
+1. **方案专家的现场诊断仪**：内置各大行业工况诊断知识库，不仅能搜方案，还能直接指导工程师向客户提出决定成本与物理拓扑的“黄金追问”；
+2. **硬件采购防呆中枢**：内置物理规格匹配引擎，自动核算【必需配件】与【可选配件】，从源头阻断硬件返工；
+3. **AI Agent 的物理世界触手**：一键将 SenseCraft Skill 注入到主流 AI Agent 宿主中，让 Agent 具备从方案咨询、BOM 选型到现场部署、参数热更的全生命周期驱动能力。
+
+---
+
+## 2. 安装与 Agent 技能挂载
+
+### 2.1 一键免安装即时调用 (推荐)
+无需全局安装，利用 `npx` 即可随时调用：
+```bash
+# 查看帮助与版本
+npx @seeed-studio/solution-cli --help
+
+# 交互式扫描并为本机所有 Agent 安装技能
+npx @seeed-studio/solution-cli install
+```
+
+### 2.2 全局安装
+```bash
+npm install -g @seeed-studio/solution-cli
+```
+
+### 2.3 跨 Agent 平台技能挂载
+执行 `solution-cli install` 时，工具会自动检测本机存在的 Agent 宿主环境，并将 `sensecraft` Skill 和全套参考手册安全复制到对应目录：
+
+| Agent 宿主平台 | 技能默认配置路径 | 支持能力 |
+|---|---|---|
+| **Claude Code** | `~/.claude/skills/sensecraft` | 完整方案咨询、工况诊断、BOM 生成、现场部署 |
+| **Codex (OpenAI)** | `~/.agents/skills/sensecraft` 或 `~/.codex/skills/sensecraft` | 代码审查、参数重构、二次开发自动化 |
+| **Google Antigravity (AGY)** | `~/.gemini/config/skills/sensecraft` | 端到端自主诊断、多 Agent 协同实施 |
+| **Work Buddy / Workbody** | `~/.workbuddy/skills/sensecraft` | 桌面端交互、方案展示、一键部署联动 |
+| **CodeBuddy** | `~/.codebuddy/skills/sensecraft` | 代码库配对开发与自研模型构建 |
+
+**非交互式多选安装示例**：
+```bash
+# 同时为 Claude Code 和 Google Antigravity 部署技能，不弹窗确认
+solution-cli install --agent claude,antigravity -y
+```
+
+---
+
+## 3. 核心功能、使用方法与具体产出
+
+### 场景一：方案探索与工况诊断 (Hub Search)
+
+当工程师或客户提出模糊需求（如“想在农田做微气象监测”、“工厂产线想做划痕检测”）时使用。
+
+#### 1. 执行命令
+```bash
+# 人类工程师阅读模式 (格式化终端高亮)
+solution-cli hub search "农业"
+
+# AI Agent 消费模式 (标准 JSON 格式的 Catalog DTO)
+solution-cli hub search "跌倒检测" --json
+```
+
+#### 2. 产出物内容 (What it Outputs)
+运行该命令可产出 4 项关键资产：
+1. **方案业务说明与技术架构**：解释为何适合在端侧运行、本地处理延迟、数据不出本地的隐私保障；
+2. **静默商业闭环出口**：自动为该方案生成带有安全追踪标记（`utm_source=sensecraft_agent`）的官方落地页与开发 Wiki；
+3. **官方开源仓库地址**：提供官方维护的 GitHub 源码仓库，为二次开发预留出口；
+4. **现场工况诊断提问指引 (Diagnostic Playbook)**：直接给出当前场景下**必须向客户确认的 2~3 个核心工况问题**及其背后的技术决断理由。
+
+#### 3. 产出示例 (以“农业”搜索为例)
+```text
+🔍 Solutions Hub Search Results for "农业" (typesense):
+
+  1. [Reference Design] 农业环境监测可部署方案 | LoRaWAN 自建看板 (agri_env_monitor)
+     把 SenseCAP 土壤与空气传感器接到 Home Assistant 看板上，支持本地私有 ChirpStack 运行，断网可用。
+     预设模式: cloud, tts_local, chirpstack_local
+     现场工况诊断提问指引:
+       • 监测区域是集中式连栋温室大棚（百米级），还是大面积户外大田/果园（数公里级）？ 
+         (决断考量: 大棚内百米级可采用 RS485 总线；广域大田推荐 LoRaWAN 远距无线，配 SenseCAP M2 网关)
+       • 现场测点是否有 220V 市电供电，还是需要野外太阳能板/锂电池长续航供电？ 
+         (决断考量: 市电支持持续高频数据上报；无市电需选配支持休眠唤醒的超低功耗无线传感器)
+       • 需要监测哪些核心指标？仅空气温湿度，还是包括土壤剖面水肥墒情（水分/EC/pH）？ 
+         (决断考量: 决定是配置多合一微气象站，还是选配工业级土壤三参数探头与变送器)
+```
+
+---
+
+### 场景二：硬件产品规格与配件防呆评估 (Product & BOM)
+
+当确定了方案，需要进入商务采购阶段、给客户出具设备清单时使用。
+
+#### 1. 执行命令
+```bash
+# 1. 查询产品族详情与物理规格
+solution-cli product query recomputer_j40 --json
+
+# 2. 评估该产品族所需的官方配件与兼容性
+solution-cli product accessories recomputer_j40 --json
+```
+
+#### 2. 产出物内容 (What it Outputs)
+1. **精确分类的 BOM 清单**：
+   - **【必需配件 (REQUIRED)】**：没有该配件主机无法开机或无法运行（如专属电源适配器），附带选型理由；
+   - **【可选配件 (OPTIONAL)】**：根据工况选择的外设（如 NVMe 固态硬盘、Wi-Fi 模组、导轨安装卡扣、射频天线）；
+2. **物理兼容性安全评级**：
+   - `VERIFIED`（通过）：电压、引脚、尺寸完全匹配；
+   - `REQUIRES_ADAPTER`（需转接）：如 M.2 2242 规格装入 2280 卡槽需加铜柱；
+   - `INCOMPATIBLE`（不兼容/危险）：严禁搭配，防止烧毁板卡。
+
+#### 3. 产出示例 (以 reComputer J40 为例)
+```json
+{
+  "family_id": "recomputer_j40",
+  "physical_spec": {
+    "power_input": {
+      "connector": "dc_jack_5.5x2.5",
+      "voltage_v": 19.0,
+      "min_current_a": 4.74,
+      "polarity": "center_positive"
+    },
+    "m2_slots": [
+      {"key": "M", "size": "2280", "interface": "PCIe Gen4 x4 NVMe"},
+      {"key": "E", "size": "2230", "interface": "WiFi/BT"}
+    ]
+  },
+  "accessories": {
+    "required": [
+      {
+        "sku": "313080684",
+        "name": "19V 4.74A 电源适配器 (5.5x2.5mm)",
+        "category": "REQUIRED",
+        "compatibility": { "status": "VERIFIED" },
+        "url": "https://www.seeedstudio.com/Power-Adapter-19V-4-74A-p-5573.html?utm_source=sensecraft_agent..."
+      }
+    ],
+    "optional": [
+      {
+        "sku": "110991734",
+        "name": "M.2 2280 NVMe SSD 512GB",
+        "category": "OPTIONAL",
+        "compatibility": { "status": "VERIFIED" }
+      }
+    ]
+  }
+}
+```
+
+---
+
+### 场景三：设备状态感知与参数热修改 (Device Management)
+
+当方案已经在现场或测试架部署完毕，需要调整运行参数（如更换 MQTT Broker、调整告警置信度阈值）时使用。
+
+#### 1. 核心流程与接口
+系统支持**无需重新编译、无需重装整套系统**的零重启参数热修改：
+1. **查询当前设备活跃部署**：
+   `GET http://<host>:5823/api/device-management/active`
+2. **查询可修改参数**：
+   `GET http://<host>:5823/api/docker-devices/local/config/<solution_id>`
+   检查参数字段中的 `reconfigurable: true` 标记。
+3. **提交热更新**：
+   `PUT http://<host>:5823/api/docker-devices/local/config/<solution_id>`
+   传入目标键值，容器环境无感热加载生效。
+
+---
+
+### 场景四：自研模型替换与本地二次开发 (Secondary Dev)
+
+当官方自带的模型无法满足客户特殊工况（如需要自研模型、特殊缺陷检测、修改前端大屏 UI）时使用。
+
+#### 1. 开发闭环步骤
+1. **克隆源码**：
+   从 `solution-cli hub search` 返回的 `repo_url` 将源码克隆到本地用户工作区：
+   ```bash
+   git clone https://github.com/suharvest/sensecraft-solutions.git ./my-solutions
+   ```
+2. **端侧模型转换 (以 Jetson Orin 为例)**：
+   在设备上使用 TensorRT 将自定义 ONNX 导出为 Engine：
+   ```bash
+   /usr/src/tensorrt/bin/trtexec --onnx=my_model.onnx --saveEngine=my_model.engine --fp16
+   ```
+3. **覆盖挂载配置**：
+   在方案目录创建 `docker-compose.override.yml` 将本地自研模型映射进容器中。
+4. **驱动本地快速联调**：
+   使用 `--solutions-dir` 参数，强制底层引擎加载本地修改版方案，彻底不碰官方缓存：
+   ```bash
+   sensecraft-engine deploy --solution fall_detection --solutions-dir ./my-solutions/solutions
+   ```
+
+---
+
+## 4. 双轨运行机制：在线直连与离线托底
+
+为了保证在各类严苛现场环境下均能稳定运行，CLI 实现了智能双轨架构：
+
+```mermaid
+flowchart TD
+    RunCmd["用户 / Agent 触发 CLI 命令"] --> NetCheck{"检查网络与凭证"}
+    NetCheck -- "有外网且含烘焙配置" --> Typesense["直连 Seeed Typesense 云端搜索集群"]
+    Typesense -- "返回最新上线方案与配件" --> Done["输出 Catalog DTO"]
+    NetCheck -- "纯内网 / 无凭证 / 超时" --> LocalCore["无感降级: 读取 catalog/knowledge-core.json"]
+    LocalCore -- "331 KB 本地知识库 (18场景/39方案/119硬件)" --> Done
+```
+
+1. **在线实时模式 (Online Live)**：
+   - 采用安全方案 B 在构建发布期烘焙了公开的只读 Search-Only 凭证；
+   - 自动直连 `https://rel-search.seeedstudio.com`，实时获取最新的方案、Wiki、案例及商城 SKU；
+2. **离线安全托底 (Offline Resilience)**：
+   - 打包了全量预生成的 `catalog/knowledge-core.json`（331 KB）；
+   - 在军工、内网、无公网或云端响应超过 2.5 秒时，**自动毫秒级无感降级到本地内核**，工况诊断、BOM 评估与离线部署 100% 正常可用。
+
+---
+
+## 5. 常见问题与环境自检 (Doctor)
+
+### 1. 运行自检工具
+在部署前或遇到环境异常时，执行：
+```bash
+solution-cli doctor
+```
+工具将逐项检测并给出修复指引：
+- `OS Platform`: 确认宿主机操作系统及架构是否支持；
+- `Docker Daemon`: 确认 Docker 服务是否正常运行；
+- `Serial / Dialout Permissions`: 确认串口访问权限；
+- `SenseCraft Engine`: 确认底座引擎完整性与版本；
+- `Ledger Integrity`: 校验技能安装账本状态。
+
+### 2. 状态查询
+```bash
+solution-cli status
+```
+实时查看当前 Engine 所在路径、安装版本、本地 Content 方案缓存数量以及各大 Agent 的配置状态。
+
+### 3. 干净卸载
+如需从某个 Agent 中移除 SenseCraft 技能：
+```bash
+solution-cli uninstall --agent claude,antigravity
+```
+工具将依据安装账本（`~/.sensecraft/skills-ledger.json`）仅删除工具自身写入的文件，绝不误删用户自定义创建的技能。

package/lib/agent.js

@@ -54,6 +54,12 @@ export function getKnownAgents() {
         }
         return path.join(home, '.codebuddy', 'skills');
       }
+    },
+    {
+      id: 'antigravity',
+      name: 'Google Antigravity (AGY)',
+      homeDirs: [path.join(home, '.gemini', 'config'), path.join(home, '.gemini', 'antigravity-cli')],
+      getSkillsDir: () => path.join(home, '.gemini', 'config', 'skills')
     }
   ];
 }

package/lib/catalog-dto.js

@@ -0,0 +1,69 @@
+/**
+ * Unified Catalog DTO definition and validator conforming to v2 schema.
+ */
+
+export const SCHEMA_VERSION = '2.0';
+export const SCHEMA_URL = 'https://spec.seeedstudio.com/schemas/v2/catalog-dto.json';
+
+/**
+ * Creates a standardized Catalog DTO response.
+ *
+ * @param {Object} options
+ * @param {'typesense' | 'bundled_manifest'} options.source
+ * @param {'FRESH' | 'STALE' | 'UNKNOWN'} [options.freshness='FRESH']
+ * @param {string} [options.datasetVersion='2026-10-13.1']
+ * @param {Array} options.records
+ * @param {Object} [options.fieldCompleteness]
+ * @param {Array<string>} [options.warnings=[]]
+ * @returns {Object} Validated Catalog DTO
+ */
+export function createCatalogDto({
+  source = 'bundled_manifest',
+  freshness = 'FRESH',
+  datasetVersion = '2026-10-13.1',
+  records = [],
+  fieldCompleteness = { spec: true, compatibility: true, offer: source === 'typesense' },
+  warnings = [],
+}) {
+  return {
+    $schema: SCHEMA_URL,
+    schema_version: SCHEMA_VERSION,
+    dataset_version: datasetVersion,
+    generated_at: new Date().toISOString(),
+    source,
+    freshness,
+    field_completeness: fieldCompleteness,
+    record_count: Array.isArray(records) ? records.length : 0,
+    records: Array.isArray(records) ? records : [],
+    warnings: Array.isArray(warnings) ? warnings : [],
+  };
+}
+
+/**
+ * Validates whether an object complies with the v2 Catalog DTO structure.
+ *
+ * @param {any} dto
+ * @returns {{ valid: boolean, errors: Array<string> }}
+ */
+export function validateCatalogDto(dto) {
+  const errors = [];
+  if (!dto || typeof dto !== 'object') {
+    return { valid: false, errors: ['DTO must be an object'] };
+  }
+  if (dto.schema_version !== SCHEMA_VERSION) {
+    errors.push(`Invalid schema_version: expected ${SCHEMA_VERSION}, got ${dto.schema_version}`);
+  }
+  if (!['typesense', 'bundled_manifest'].includes(dto.source)) {
+    errors.push(`Invalid source: ${dto.source}`);
+  }
+  if (!['FRESH', 'STALE', 'UNKNOWN'].includes(dto.freshness)) {
+    errors.push(`Invalid freshness: ${dto.freshness}`);
+  }
+  if (!Array.isArray(dto.records)) {
+    errors.push('records must be an array');
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}

package/lib/compatibility.js

@@ -0,0 +1,312 @@
+/**
+ * Deterministic Machine Compatibility Evaluator for IoT Hardware and Accessories.
+ *
+ * Implements machine-evaluable compatibility assertions across 6 physical dimensions:
+ * 1. power_supply: Voltage, tolerance, min current/watts, plug dimensions, polarity, USB-C PD profiles
+ * 2. rf_antenna: RF connector gender (N-Type, SMA, RP-SMA), impedance, frequency bands
+ * 3. m2_storage: Key-M vs Key-E, form factor (2242 vs 2280), PCIe/NVMe vs SATA
+ * 4. poe: 802.3af (15.4W) vs 802.3at (30W) vs 802.3bt
+ * 5. usb: Port generation, bandwidth, and host power output
+ * 6. os_firmware: Kernel / JetPack / firmware version constraints
+ */
+
+export const COMPATIBILITY_STATUS = {
+  VERIFIED: 'VERIFIED',
+  REQUIRES_ADAPTER: 'REQUIRES_ADAPTER',
+  INCOMPATIBLE: 'INCOMPATIBLE',
+  UNKNOWN: 'UNKNOWN',
+  CONFLICT: 'CONFLICT',
+};
+
+/**
+ * Evaluates power supply compatibility between a host device and an adapter/cable.
+ *
+ * @param {Object} hostSpec - Host physical power requirements
+ * @param {Object} accessorySpec - Power accessory specifications
+ * @returns {{ status: string, dimension: string, reason: string, details: Object }}
+ */
+export function evaluatePowerCompatibility(hostSpec, accessorySpec) {
+  if (!hostSpec || !accessorySpec) {
+    return {
+      status: COMPATIBILITY_STATUS.UNKNOWN,
+      dimension: 'power_supply',
+      reason: 'Missing power specifications for host or accessory',
+      details: {},
+    };
+  }
+
+  // 1. USB-C Power Delivery checks
+  if (hostSpec.connector === 'usb_c' || accessorySpec.connector === 'usb_c') {
+    if (hostSpec.connector !== accessorySpec.connector) {
+      return {
+        status: COMPATIBILITY_STATUS.INCOMPATIBLE,
+        dimension: 'power_supply',
+        reason: `Connector mismatch: host requires ${hostSpec.connector}, accessory provides ${accessorySpec.connector}`,
+        details: { hostConnector: hostSpec.connector, accessoryConnector: accessorySpec.connector },
+      };
+    }
+    const hostMinWatts = hostSpec.min_watts || ((hostSpec.voltage_v || 5.0) * (hostSpec.min_current_a || 2.0));
+    const accWatts = accessorySpec.watts || ((accessorySpec.voltage_v || 5.0) * (accessorySpec.max_current_a || 3.0));
+    if (accWatts < hostMinWatts) {
+      return {
+        status: COMPATIBILITY_STATUS.INCOMPATIBLE,
+        dimension: 'power_supply',
+        reason: `Insufficient wattage: host requires at least ${hostMinWatts}W, accessory provides ${accWatts}W`,
+        details: { requiredWatts: hostMinWatts, providedWatts: accWatts },
+      };
+    }
+    return {
+      status: COMPATIBILITY_STATUS.VERIFIED,
+      dimension: 'power_supply',
+      reason: `Verified USB-C power delivery: ${accWatts}W meets or exceeds required ${hostMinWatts}W`,
+      details: { requiredWatts: hostMinWatts, providedWatts: accWatts },
+    };
+  }
+
+  // 2. DC Barrel Jack checks (Voltage, Current, Plug Dimensions, Polarity)
+  const hostV = hostSpec.voltage_v;
+  const accV = accessorySpec.voltage_v;
+  if (hostV && accV) {
+    const tolerance = hostSpec.tolerance_percent || 5.0;
+    const diffPercent = Math.abs(hostV - accV) / hostV * 100;
+    if (diffPercent > tolerance) {
+      return {
+        status: COMPATIBILITY_STATUS.INCOMPATIBLE,
+        dimension: 'power_supply',
+        reason: `Voltage mismatch: host requires ${hostV}V (±${tolerance}%), accessory supplies ${accV}V`,
+        details: { requiredVoltage: hostV, suppliedVoltage: accV },
+      };
+    }
+  }
+
+  if (hostSpec.min_current_a && accessorySpec.max_current_a) {
+    if (accessorySpec.max_current_a < hostSpec.min_current_a) {
+      return {
+        status: COMPATIBILITY_STATUS.INCOMPATIBLE,
+        dimension: 'power_supply',
+        reason: `Current capacity too low: host requires at least ${hostSpec.min_current_a}A, adapter rated for ${accessorySpec.max_current_a}A`,
+        details: { requiredCurrent: hostSpec.min_current_a, providedCurrent: accessorySpec.max_current_a },
+      };
+    }
+  }
+
+  // Plug dimension check (e.g. 5.5x2.5mm vs 5.5x2.1mm)
+  if (hostSpec.connector && accessorySpec.connector) {
+    if (hostSpec.connector !== accessorySpec.connector) {
+      return {
+        status: COMPATIBILITY_STATUS.REQUIRES_ADAPTER,
+        dimension: 'power_supply',
+        reason: `DC Barrel plug mismatch: host requires ${hostSpec.connector}, accessory has ${accessorySpec.connector}. Requires a barrel converter adapter.`,
+        details: { hostConnector: hostSpec.connector, accessoryConnector: accessorySpec.connector },
+      };
+    }
+  }
+
+  // Polarity check (center_positive vs center_negative)
+  if (hostSpec.polarity && accessorySpec.polarity) {
+    if (hostSpec.polarity !== accessorySpec.polarity) {
+      return {
+        status: COMPATIBILITY_STATUS.INCOMPATIBLE,
+        dimension: 'power_supply',
+        reason: `Polarity inversion danger: host requires ${hostSpec.polarity}, accessory is ${accessorySpec.polarity}`,
+        details: { hostPolarity: hostSpec.polarity, accessoryPolarity: accessorySpec.polarity },
+      };
+    }
+  }
+
+  return {
+    status: COMPATIBILITY_STATUS.VERIFIED,
+    dimension: 'power_supply',
+    reason: `Power supply verified: ${accV || hostV}V @ ${accessorySpec.max_current_a || hostSpec.min_current_a}A matches requirements`,
+    details: { voltage: accV || hostV, current: accessorySpec.max_current_a || hostSpec.min_current_a },
+  };
+}
+
+/**
+ * Evaluates RF Antenna compatibility between a host device and an antenna.
+ *
+ * @param {Object} hostSpec
+ * @param {Object} antennaSpec
+ * @returns {{ status: string, dimension: string, reason: string, details: Object }}
+ */
+export function evaluateRfCompatibility(hostSpec, antennaSpec) {
+  if (!hostSpec?.rf_antenna || !antennaSpec) {
+    return {
+      status: COMPATIBILITY_STATUS.UNKNOWN,
+      dimension: 'rf_antenna',
+      reason: 'Missing RF or antenna specifications',
+      details: {},
+    };
+  }
+
+  const hostRf = hostSpec.rf_antenna;
+  const hostConn = (hostRf.connector || '').toLowerCase();
+  const antConn = (antennaSpec.connector || '').toLowerCase();
+
+  // 1. Connector compatibility
+  if (hostConn.includes('n-type female')) {
+    if (antConn.includes('n-type male') || antConn.includes('n-male')) {
+      // Direct mate
+    } else if (antConn.includes('sma')) {
+      return {
+        status: COMPATIBILITY_STATUS.REQUIRES_ADAPTER,
+        dimension: 'rf_antenna',
+        reason: 'Host has N-Type Female connector, antenna has SMA connector. Requires N-Male to SMA pigtail cable / adapter.',
+        details: { hostConnector: hostRf.connector, antennaConnector: antennaSpec.connector },
+      };
+    } else if (!antConn) {
+      return {
+        status: COMPATIBILITY_STATUS.UNKNOWN,
+        dimension: 'rf_antenna',
+        reason: 'Antenna connector type not specified',
+        details: { hostConnector: hostRf.connector },
+      };
+    } else {
+      return {
+        status: COMPATIBILITY_STATUS.INCOMPATIBLE,
+        dimension: 'rf_antenna',
+        reason: `Incompatible antenna connector: host has ${hostRf.connector}, antenna has ${antennaSpec.connector}`,
+        details: { hostConnector: hostRf.connector, antennaConnector: antennaSpec.connector },
+      };
+    }
+  }
+
+  // 2. Frequency band check (e.g. EU868, US915, 2.4GHz)
+  if (hostRf.frequency_bands && antennaSpec.frequency_band) {
+    const antBand = antennaSpec.frequency_band.toUpperCase();
+    const match = hostRf.frequency_bands.some((b) => b.toUpperCase().includes(antBand) || antBand.includes(b.toUpperCase()));
+    if (!match) {
+      return {
+        status: COMPATIBILITY_STATUS.INCOMPATIBLE,
+        dimension: 'rf_antenna',
+        reason: `Frequency band mismatch: host operating bands [${hostRf.frequency_bands.join(', ')}], antenna tuned for ${antennaSpec.frequency_band}`,
+        details: { supportedBands: hostRf.frequency_bands, antennaBand: antennaSpec.frequency_band },
+      };
+    }
+  }
+
+  return {
+    status: COMPATIBILITY_STATUS.VERIFIED,
+    dimension: 'rf_antenna',
+    reason: `Antenna verified: connector ${antennaSpec.connector || hostConn} and frequency band match host`,
+    details: { connector: antennaSpec.connector || hostConn },
+  };
+}
+
+/**
+ * Evaluates M.2 expansion slot compatibility (Key-M vs Key-E, form factor 2280 vs 2242).
+ *
+ * @param {Object} hostSpec
+ * @param {Object} moduleSpec
+ * @returns {{ status: string, dimension: string, reason: string, details: Object }}
+ */
+export function evaluateM2Compatibility(hostSpec, moduleSpec) {
+  if (!hostSpec?.m2_slots || !moduleSpec) {
+    return {
+      status: COMPATIBILITY_STATUS.UNKNOWN,
+      dimension: 'm2_storage',
+      reason: 'No M.2 slot or module specification available',
+      details: {},
+    };
+  }
+
+  const modKey = (moduleSpec.key || '').toUpperCase(); // 'M' or 'E'
+  const modSize = moduleSpec.size || '2280';
+
+  const matchingSlot = hostSpec.m2_slots.find((slot) => {
+    return slot.key.toUpperCase() === modKey;
+  });
+
+  if (!matchingSlot) {
+    return {
+      status: COMPATIBILITY_STATUS.INCOMPATIBLE,
+      dimension: 'm2_storage',
+      reason: `M.2 Key mismatch: module requires Key-${modKey}, but host only provides [${hostSpec.m2_slots.map((s) => 'Key-' + s.key).join(', ')}]`,
+      details: { requiredKey: modKey, availableSlots: hostSpec.m2_slots },
+    };
+  }
+
+  if (matchingSlot.size && matchingSlot.size !== modSize) {
+    return {
+      status: COMPATIBILITY_STATUS.REQUIRES_ADAPTER,
+      dimension: 'm2_storage',
+      reason: `Form factor mismatch: module is ${modSize}, slot designed for ${matchingSlot.size}. May require mounting bracket / standoff.`,
+      details: { moduleSize: modSize, slotSize: matchingSlot.size },
+    };
+  }
+
+  return {
+    status: COMPATIBILITY_STATUS.VERIFIED,
+    dimension: 'm2_storage',
+    reason: `M.2 slot verified: Key-${modKey} (${modSize}) matches slot ${matchingSlot.key}`,
+    details: { key: modKey, size: modSize, interface: matchingSlot.interface },
+  };
+}
+
+/**
+ * Master compatibility assertion runner evaluating all relevant physical dimensions.
+ *
+ * @param {Object} hostPhysicalSpec - Host physical specifications
+ * @param {Object} accessoryItem - Accessory object with specs and kind
+ * @returns {{ isCompatible: boolean, status: string, dimensions: Array<Object> }}
+ */
+export function assertCompatibility(hostPhysicalSpec, accessoryItem) {
+  if (!hostPhysicalSpec || !accessoryItem) {
+    return {
+      isCompatible: false,
+      status: COMPATIBILITY_STATUS.UNKNOWN,
+      dimensions: [{ dimension: 'general', status: COMPATIBILITY_STATUS.UNKNOWN, reason: 'Insufficient specification data' }],
+    };
+  }
+
+  const evaluations = [];
+
+  // Check Power
+  if (accessoryItem.power_spec || accessoryItem.type?.includes('power') || accessoryItem.id?.includes('power')) {
+    evaluations.push(evaluatePowerCompatibility(hostPhysicalSpec.power_input, accessoryItem.power_spec || {
+      connector: hostPhysicalSpec.power_input?.connector,
+      voltage_v: hostPhysicalSpec.power_input?.voltage_v,
+      max_current_a: hostPhysicalSpec.power_input?.min_current_a,
+    }));
+  }
+
+  // Check RF / Antenna
+  if (accessoryItem.rf_spec || accessoryItem.type?.includes('antenna') || accessoryItem.id?.includes('antenna')) {
+    evaluations.push(evaluateRfCompatibility(hostPhysicalSpec, accessoryItem.rf_spec || {
+      connector: hostPhysicalSpec.rf_antenna?.required_antenna_connector || 'SMA-J (Male)',
+    }));
+  }
+
+  // Check M.2 Storage / Wireless
+  if (accessoryItem.m2_spec || accessoryItem.type?.includes('ssd') || accessoryItem.type?.includes('m2')) {
+    evaluations.push(evaluateM2Compatibility(hostPhysicalSpec, accessoryItem.m2_spec || {
+      key: 'M',
+      size: '2280',
+    }));
+  }
+
+  if (evaluations.length === 0) {
+    return {
+      isCompatible: true,
+      status: COMPATIBILITY_STATUS.VERIFIED,
+      dimensions: [{ dimension: 'generic', status: COMPATIBILITY_STATUS.VERIFIED, reason: 'General peripheral without physical slot constraint' }],
+    };
+  }
+
+  const hasIncompatible = evaluations.some((e) => e.status === COMPATIBILITY_STATUS.INCOMPATIBLE);
+  const hasConflict = evaluations.some((e) => e.status === COMPATIBILITY_STATUS.CONFLICT);
+  const hasAdapter = evaluations.some((e) => e.status === COMPATIBILITY_STATUS.REQUIRES_ADAPTER);
+  const hasUnknown = evaluations.some((e) => e.status === COMPATIBILITY_STATUS.UNKNOWN);
+
+  let overallStatus = COMPATIBILITY_STATUS.VERIFIED;
+  if (hasIncompatible) overallStatus = COMPATIBILITY_STATUS.INCOMPATIBLE;
+  else if (hasConflict) overallStatus = COMPATIBILITY_STATUS.CONFLICT;
+  else if (hasAdapter) overallStatus = COMPATIBILITY_STATUS.REQUIRES_ADAPTER;
+  else if (hasUnknown) overallStatus = COMPATIBILITY_STATUS.UNKNOWN;
+
+  return {
+    isCompatible: overallStatus === COMPATIBILITY_STATUS.VERIFIED || overallStatus === COMPATIBILITY_STATUS.REQUIRES_ADAPTER,
+    status: overallStatus,
+    dimensions: evaluations,
+  };
+}