@seeed-studio/solution-cli 0.1.0 → 0.2.0

package/lib/knowledge.js

@@ -0,0 +1,327 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import https from 'node:https';
+import http from 'node:http';
+import { createCatalogDto } from './catalog-dto.js';
+import { assertCompatibility, COMPATIBILITY_STATUS } from './compatibility.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const DATA_FILE = path.join(__dirname, '..', 'catalog', 'knowledge-core.json');
+
+let cachedKnowledgeCore = null;
+
+/**
+ * Loads the bundled offline knowledge core file.
+ *
+ * @returns {Object} Bundled knowledge core data
+ */
+export function loadKnowledgeCore() {
+  if (cachedKnowledgeCore) return cachedKnowledgeCore;
+  if (!fs.existsSync(DATA_FILE)) {
+    throw new Error(`Knowledge core manifest not found at ${DATA_FILE}. Run "npm run build:knowledge" to generate.`);
+  }
+  const raw = fs.readFileSync(DATA_FILE, 'utf-8');
+  cachedKnowledgeCore = JSON.parse(raw);
+  return cachedKnowledgeCore;
+}
+
+/**
+ * Performs an HTTP GET request with a timeout.
+ *
+ * @param {string} urlStr
+ * @param {Object} headers
+ * @param {number} timeoutMs
+ * @returns {Promise<Object>}
+ */
+function fetchJson(urlStr, headers = {}, timeoutMs = 2500) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(urlStr);
+    const client = url.protocol === 'https:' ? https : http;
+    const req = client.get(url, { headers, timeout: timeoutMs }, (res) => {
+      let body = '';
+      res.on('data', (chunk) => { body += chunk; });
+      res.on('end', () => {
+        if (res.statusCode >= 200 && res.statusCode < 300) {
+          try {
+            resolve(JSON.parse(body));
+          } catch (e) {
+            reject(new Error(`Invalid JSON from ${urlStr}: ${e.message}`));
+          }
+        } else {
+          reject(new Error(`HTTP ${res.statusCode} from ${urlStr}`));
+        }
+      });
+    });
+    req.on('timeout', () => {
+      req.destroy();
+      reject(new Error(`Timeout after ${timeoutMs}ms from ${urlStr}`));
+    });
+    req.on('error', reject);
+  });
+}
+
+/**
+ * Searches Seeed Solutions Hub scenarios and reference designs.
+ *
+ * @param {Object} options
+ * @param {string} options.query - Free text search query
+ * @param {'zh' | 'en'} [options.locale='zh'] - Language preference
+ * @param {number} [options.limit=5] - Maximum number of results
+ * @returns {Promise<Object>} Standardized Catalog DTO
+ */
+export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
+  const qLower = (query || '').toLowerCase().trim();
+  const searchKey = process.env.SENSECRAFT_TYPESENSE_PURCHASE_SEARCH_KEY || process.env.TYPESENSE_SEARCH_KEY;
+  const host = process.env.TYPESENSE_HOST || 'https://rel-search.seeedstudio.com';
+
+  // Attempt online Typesense search if key is provided and not explicitly running offline
+  if (searchKey && !process.env.SENSECRAFT_OFFLINE_ONLY) {
+    try {
+      const searchUrl = `${host}/collections/Solution/documents/search?q=${encodeURIComponent(query)}&query_by=title,description,tags&per_page=${limit}`;
+      const data = await fetchJson(searchUrl, { 'X-TYPESENSE-API-KEY': searchKey }, 2500);
+      if (data && Array.isArray(data.hits)) {
+        const records = data.hits.map((hit) => {
+          const doc = hit.document || {};
+          return {
+            type: doc.doc_type || 'scenario',
+            id: doc.id || doc.slug,
+            title: doc.title,
+            summary: doc.summary || doc.description,
+            tags: doc.tags || [],
+            family_ids: doc.family_ids || [],
+            source: 'typesense',
+          };
+        });
+        return createCatalogDto({
+          source: 'typesense',
+          freshness: 'FRESH',
+          records: records.slice(0, limit),
+        });
+      }
+    } catch (err) {
+      // Graceful fallback to offline core with notice
+    }
+  }
+
+  // Offline fallback search over knowledge-core
+  const core = loadKnowledgeCore();
+  const matchedScenarios = [];
+  const matchedRefDesigns = [];
+
+  const tokens = qLower.split(/\s+/).filter(Boolean);
+
+  for (const s of core.scenarios || []) {
+    const haystack = [
+      s.id,
+      s.title?.zh,
+      s.title?.en,
+      s.subtitle?.zh,
+      s.subtitle?.en,
+      s.summary,
+      ...(s.tags || []),
+    ].join(' ').toLowerCase();
+
+    const score = tokens.reduce((acc, token) => (haystack.includes(token) ? acc + 1 : acc), 0);
+    if (tokens.length === 0 || score > 0) {
+      matchedScenarios.push({
+        type: 'scenario',
+        id: s.id,
+        title: s.title?.[locale] || s.title?.zh || s.title?.en || s.id,
+        summary: s.subtitle?.[locale] || s.subtitle?.zh || s.summary || '',
+        tags: s.tags || [],
+        family_ids: s.family_ids || [],
+        reference_designs: s.reference_designs || [],
+        score,
+      });
+    }
+  }
+
+  for (const rd of core.reference_designs || []) {
+    const haystack = [
+      rd.id,
+      rd.title?.zh,
+      rd.title?.en,
+      rd.summary?.zh,
+      rd.summary?.en,
+      ...(rd.presets || []),
+    ].join(' ').toLowerCase();
+
+    const score = tokens.reduce((acc, token) => (haystack.includes(token) ? acc + 1 : acc), 0);
+    if (tokens.length === 0 || score > 0) {
+      matchedRefDesigns.push({
+        type: 'reference_design',
+        id: rd.id,
+        title: rd.title?.[locale] || rd.title?.zh || rd.title?.en || rd.id,
+        summary: rd.summary?.[locale] || rd.summary?.zh || rd.summary?.en || '',
+        presets: rd.presets || [],
+        wiki_url: rd.wiki_url || '',
+        score,
+      });
+    }
+  }
+
+  // Sort by score descending and take top results
+  matchedScenarios.sort((a, b) => b.score - a.score);
+  matchedRefDesigns.sort((a, b) => b.score - a.score);
+
+  const combined = [...matchedScenarios, ...matchedRefDesigns].slice(0, limit);
+
+  return createCatalogDto({
+    source: 'bundled_manifest',
+    freshness: 'FRESH',
+    records: combined,
+    warnings: searchKey
+      ? ['Online Typesense request timed out; fell back to local bundled manifest.']
+      : ['No Typesense API key configured. Displaying verified local catalog.'],
+  });
+}
+
+/**
+ * Queries product family information, SKUs, and official purchase links.
+ *
+ * @param {string} familyId
+ * @param {Object} [options]
+ * @param {string} [options.locale='zh']
+ * @returns {Object} Catalog DTO with product details
+ */
+export function queryProductFamily(familyId, { locale = 'zh' } = {}) {
+  const core = loadKnowledgeCore();
+  const family = core.product_families?.[familyId];
+
+  if (!family) {
+    return createCatalogDto({
+      source: 'bundled_manifest',
+      freshness: 'FRESH',
+      records: [],
+      warnings: [`Product family "${familyId}" not found in local catalog.`],
+    });
+  }
+
+  return createCatalogDto({
+    source: 'bundled_manifest',
+    freshness: 'FRESH',
+    records: [{
+      family_id: family.id,
+      title: family.title?.[locale] || family.title?.zh || family.title?.en || family.id,
+      default_sku: family.default_sku,
+      regions: family.regions || [],
+      skus_count: (family.skus || []).length,
+      skus: (family.skus || []).slice(0, 10),
+      physical_spec: family.physical_spec || null,
+      required_accessories_count: (family.required_accessories || []).length,
+      optional_accessories_count: (family.optional_accessories || []).length,
+    }],
+  });
+}
+
+/**
+ * Queries and verifies accessories for a product family, running physical compatibility checks.
+ *
+ * @param {string} familyId
+ * @param {Object} [options]
+ * @param {string} [options.sku] - Specific host SKU
+ * @param {string} [options.locale='zh']
+ * @returns {Object} Catalog DTO with structured, verified accessories
+ */
+export function queryAccessories(familyId, { sku = null, locale = 'zh' } = {}) {
+  const core = loadKnowledgeCore();
+  const family = core.product_families?.[familyId];
+
+  if (!family) {
+    return createCatalogDto({
+      source: 'bundled_manifest',
+      freshness: 'FRESH',
+      records: [],
+      warnings: [`Product family "${familyId}" not found in local catalog.`],
+    });
+  }
+
+  const hostPhysicalSpec = family.physical_spec || null;
+
+  // Process required accessories
+  const required = (family.required_accessories || []).map((acc) => {
+    const comp = assertCompatibility(hostPhysicalSpec, acc);
+    return {
+      category: 'REQUIRED',
+      id: acc.id,
+      name: acc.name,
+      sku: acc.sku,
+      url: acc.url,
+      qty: acc.qty || 1,
+      reason: acc.reason || 'Required for standard operation',
+      applies_when: acc.applies_when || null,
+      compatibility: {
+        is_compatible: comp.isCompatible,
+        status: comp.status,
+        details: comp.dimensions,
+      },
+    };
+  });
+
+  // Process optional accessories
+  const optional = (family.optional_accessories || []).map((acc) => {
+    const comp = assertCompatibility(hostPhysicalSpec, acc);
+    return {
+      category: 'OPTIONAL',
+      id: acc.id,
+      name: acc.name,
+      sku: acc.sku,
+      url: acc.url,
+      type: acc.type || 'peripheral',
+      compatibility: {
+        is_compatible: comp.isCompatible,
+        status: comp.status,
+        details: comp.dimensions,
+      },
+    };
+  });
+
+  return createCatalogDto({
+    source: 'bundled_manifest',
+    freshness: 'FRESH',
+    records: [{
+      family_id: family.id,
+      host_title: family.title?.[locale] || family.title?.zh || family.title?.en,
+      host_sku: sku || family.default_sku,
+      physical_spec: hostPhysicalSpec,
+      accessories: {
+        required,
+        optional,
+      },
+    }],
+  });
+}
+
+/**
+ * Generates an immutable DeploymentLockfile to isolate deployment apply from external network.
+ *
+ * @param {Object} options
+ * @param {string} options.solutionId
+ * @param {string} options.solutionVersion
+ * @param {Array<string>} options.selectedHardware
+ * @param {Array<Object>} [options.verifiedCompatibility=[]]
+ * @returns {Object} DeploymentLockfile
+ */
+export function createDeploymentLockfile({
+  solutionId,
+  solutionVersion = '1.0.0',
+  selectedHardware = [],
+  verifiedCompatibility = [],
+}) {
+  return {
+    $schema: 'https://spec.seeedstudio.com/schemas/v2/deployment-lock.json',
+    solution_id: solutionId,
+    solution_version: solutionVersion,
+    locked_at: new Date().toISOString(),
+    dataset_version: '2026-10-13.1',
+    selected_hardware: selectedHardware,
+    compatibility_assertions: verifiedCompatibility,
+    unresolved_requirements: [],
+    network_policy: {
+      commercial_queries_allowed: false,
+      apply_isolated: true,
+    },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seeed-studio/solution-cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Zero-friction installer and CLI runner for SenseCraft Engine and AI Agent Skills (Work Buddy, Claude Code, Codex, CodeBuddy)",
   "type": "module",
   "main": "./lib/installer.js",
@@ -17,6 +17,7 @@
   "files": [
     "bin",
     "lib",
+    "catalog",
     "skills",
     "README.md"
   ],

package/skills/sensecraft/SKILL.md

@@ -1,16 +1,23 @@
 ---
 name: sensecraft
-description: Deploy, manage, and troubleshoot SenseCraft / Seeed Studio edge IoT solutions (智慧农业, 摔倒检测, 边缘安全, 智慧仓库, 语音助手, people counting, face recognition 等) on hardware devices (NVIDIA Jetson, Raspberry Pi 树莓派, reComputer, reCamera, SenseCAP Watcher, Grove Vision AI, ESP32) using the `sensecraft-engine` command-line engine (no desktop app needed). Use whenever the user asks to deploy (部署), install (安装方案), test, inspect, or troubleshoot a SenseCraft edge IoT solution or configure devices and sensors. Changing a solution's configuration needs the desktop app (references/app-only.md).
+description: Consult, select, deploy, manage, and troubleshoot SenseCraft / Seeed Studio edge IoT solutions (智慧农业, 摔倒检测, 边缘安全, 智慧仓库, 语音助手, people counting, face recognition 等) and hardware products (reComputer Jetson, reCamera, SenseCAP, Grove Vision AI, ESP32) using the `sensecraft-engine` and `solution-cli` toolset. Use whenever the user asks for edge IoT solutions, hardware recommendations, accessory compatibility, deployment, or troubleshooting.
 ---
 
 # SenseCraft Solution
 
-This skill drives the `sensecraft-engine` command-line engine. It works in any
-agent that can read files and run shell commands. Every step is a
-`sensecraft-engine` command; the engine starts its own background instance when
-a command needs one. Do not call the instance's HTTP port with `curl`: use the
-CLI, and `sensecraft-engine api <METHOD> <path>` for anything without its own
-command.
+This skill drives the `sensecraft-engine` execution engine and `solution-cli` toolset. It operates across the complete lifecycle: **Solution Consultation ➔ Hardware & Accessory BOM Selection ➔ Local Deployment ➔ Self-Healing Diagnostics**.
+
+## Workflow Routing & Progressive Disclosure
+
+Do NOT read all reference files at once. Determine the user's workflow state and intent, then load **at most ONE** reference file on demand:
+
+| User State & Intent | Reference to Load | Primary CLI Tool to Call | Guardrails & Forbidden Actions |
+|---|---|---|---|
+| **DISCOVERY / CONSULT**<br>“我想做防跌倒监控”、“有智慧农场方案吗” | `references/consult-and-select.md` | `solution-cli hub search "<keyword>" --json` | **DO NOT run deploy**; user is exploring scenarios and has not confirmed hardware. |
+| **PROCUREMENT / VERIFY_BOM**<br>“买什么硬件？”、“J4012 需要配什么配件？” | `references/hardware-bom.md` | `solution-cli product accessories <id> --json` | **DO NOT fabricate** third-party SKUs or prices. Always distinguish REQUIRED vs OPTIONAL accessories. |
+| **ONBOARDING / PRECHECK**<br>“设备到了，插上了网线/USB”、“环境自检” | `references/diagnose.md` | `solution-cli doctor` / `sensecraft-engine device scan` | Freeze hardware requirements into DeploymentLockfile before proceeding to apply. |
+| **DEPLOYING / APPLY**<br>“开始安装”、“部署 fall_detection” | `references/deploy.md` | `sensecraft-engine deploy --solution <id>` | **DEPLOYMENT CRITICAL SECTION**: Zero external commercial queries allowed during apply. |
+| **TROUBLESHOOTING**<br>“部署报错”、“黑屏”、“无视频流” | `references/error-catalog.md` | `sensecraft-engine logs` / `solution-cli product verify-compatibility` | Max 3 fix-and-retry rounds. Follow local auto-patching rule. |
 
 Capabilities that need the **SenseCraft Solution desktop app** (editing a
 solution's configuration, the app's `/api/ai/context`, diagnosing through the

package/skills/sensecraft/references/consult-and-select.md

@@ -0,0 +1,56 @@
+# 方案咨询与场景匹配手册 (Consult & Select Guide)
+
+> **定位**：供 AI Agent 在用户处于 **场景探索（DISCOVERY）** 或 **方案咨询（CONSULT）** 时查阅。当用户询问“我想做某某事情”、“有什么物联网方案”、“如何解决 XX 问题”时，使用本手册定位场景、推荐参考设计并对齐硬件族。
+
+---
+
+## 1. 意图识别与场景路由规则
+
+当用户的自然语言输入包含以下关键词时，直接调用 CLI 工具查询相关场景：
+
+| 行业领域 | 触发关键词（中英文） | 对应场景 Slug | 核心参考设计 |
+|---|---|---|---|
+| **智慧养老 / 监护** | 养老、跌倒检测、防摔、老人、呼叫、fall detection, elderly | `elderly-care-monitoring` | `fall_detection` |
+| **智慧农业 / 环境** | 农田、大棚、温湿度、气象、土壤、agriculture, soil, greenhouse | `environment-monitoring` | `agri_env_monitor` |
+| **工业质检 / 缺陷** | 缺陷检测、工业视觉、表面划痕、流水线装配、visual inspection, defect | `industrial-visual-inspection` | `edge_inspection_surface`, `edge_inspection_assembly` |
+| **智慧交通 / 园区** | 车牌识别、停车场、车辆计数、停车位、anpr, license plate, parking | `parking-traffic-vision` | `edge-anpr-plate-recognition` |
+| **边缘语音 / 助手** | 离线语音、大模型音箱、呼救感知、voice ai, audio assistant, respeaker | `conversational-voice-ai` | `home-assistant-local-voice-hub`, `conversational_voice_ai` |
+| **建筑能耗 / 暖通** | 楼宇能耗、电表、水表、空调节能、HVAC, energy retrofit | `building-energy-retrofit` | `building_energy_management` |
+| **室内外定位 / 资产** | 蓝牙信标、资产定位、人员卡片、防丢、GNSS, tracker, beacon, T1000 | `indoor-outdoor-positioning` | `indoor_positioning_ble_lorawan` |
+
+---
+
+## 2. 工具调用标准动作
+
+### 动作一：搜索场景与参考设计
+使用命令：
+```bash
+solution-cli hub search "<用户关键词>" --limit 5 --json
+```
+- **输出结果解释**：
+  - 提取匹配的 `Scenario`（阐述业务场景、痛点、成效）；
+  - 提取推荐的 `Reference Design`（阐述技术路线、预设模式 presets、开发 wiki）；
+  - 提取 `family_ids`（推荐的主板/相机/网关产品族）。
+
+### 动作二：向用户呈现专业方案推荐模板
+在向用户回答时，遵循以下结构化呈现，**严禁一上来就输出 deploy 命令**：
+
+```markdown
+### 💡 方案匹配建议
+
+1. **业务场景**：[场景名称]（如：养老看护）
+   - **痛点与价值**：[简述核心业务价值，如：端侧跌倒检测，1.4s 本地快速判定，视频不出设备彻底保护隐私]
+2. **推荐参考设计**：[参考设计名称]（ID: `fall_detection`）
+   - **技术方案**：[骨骼姿态估计 / MQTT 告警联动]
+   - **预设模式**：[如 recamera, jetson, rk, hailo]
+   - **开发 Wiki**：[官方 Wiki 链接]
+3. **推荐主硬件**：[硬件族列表，如 reComputer J4012, reCamera Pro]
+   - 采购与配件明细可进一步通过硬件选型指引查询。
+```
+
+---
+
+## 3. 防幻觉与守则
+
+1. **禁止编造方案**：如果 `solution-cli hub search` 返回为空，诚实告知用户官方方案库暂无现成参考设计，并基于通用 Jetson / 树莓派 Docker 能力提供定制建议。
+2. **严禁在咨询期直接执行部署**：用户此时通常未采购或未连接硬件。应引导用户进入下一步【硬件选型与配件推荐】（查阅 `references/hardware-bom.md`）。

package/skills/sensecraft/references/hardware-bom.md

@@ -0,0 +1,83 @@
+# 硬件选型与配件推荐准则 (Hardware & BOM Guide)
+
+> **定位**：供 AI Agent 在用户处于 **采购选型（PROCUREMENT）** 或 **BOM 验证（VERIFY_BOM）** 阶段查阅。当用户询问“需要买什么硬件”、“XX 主板需要配什么配件”、“电源/天线怎么选”时使用本手册。
+
+---
+
+## 1. 核心流程：主板 ➔ 必选配件 ➔ 选配传感器/增强件
+
+为用户提供硬件采购清单时，必须严格区分：
+1. **主运算单元（Host Platform）**：如 `recomputer_j40`、`recamera_pro`、`sensecap_m2_gateway`。
+2. **必选配件（REQUIRED Accessories）**：**若缺少则系统物理上无法工作**（如：Super 款未配电源线、网关未配天线、工控机无输入电源端子）。
+3. **选配配件（OPTIONAL Accessories）**：根据具体功能选配（如：存储 SSD、4G 蜂窝网卡、降噪麦克风阵列、云台支架）。
+
+---
+
+## 2. 工具调用标准命令
+
+### 动作一：查询主设备规格与默认 SKU
+```bash
+solution-cli product query <family_id> --json
+```
+- 获取产品族名称、官方默认主 SKU、物理电气规格（电压、电流接口、M.2 槽位等）。
+
+### 动作二：查询经过验证的配件清单
+```bash
+solution-cli product accessories <family_id> --json
+```
+- 输出严格由确定性代码计算物理兼容性的配件清单：
+  - `REQUIRED` 列表：带必买原因（`reason`）、购买 SKU 与直达链接；
+  - `OPTIONAL` 列表：带周边传感器、通信模块、固态硬盘与购买链接。
+
+### 动作三：验证物理配件兼容性
+当用户提到已有某个第三方配件或自制电源/天线时：
+```bash
+solution-cli product verify-compatibility --host <family_id> --accessory "<用户配件描述>" --json
+```
+
+---
+
+## 3. 六大物理兼容性硬红线（严禁大模型自行脑补）
+
+Agent 严禁凭“常识”告知配件通用，必须遵循 CLI 评估结果：
+
+1. **供电 (Power Supply)**：
+   - `recomputer_j40` / `j30` 必须满足 **19V 4.74A (90W)**，DC Jack 规格为 **5.5x2.5mm**（与普通 5.5x2.1mm 路由器插头不兼容）；
+   - USB-C 供电的设备（如 `recamera_2002`、`sensecap_watcher`），必须核对 PD 协议档位与最低电流。
+2. **射频与天线 (RF Antenna)**：
+   - 必须严格区分 **N 型（N-Type）** 与 **SMA**；
+   - 室外网关多为 **N-Type Female（母头）**，天线必须选 **N-Type Male（公头，带针）**，若为 SMA 天线必须提醒用户加购 **N转SMA转接线（Pigtail Cable）**；
+   - 频段必须对齐：欧洲选 `EU868`，北美选 `US915`，亚洲选 `AS923`。
+3. **M.2 扩展卡 (M.2 Key)**：
+   - **Key-M**：仅用于 NVMe SSD（尺寸通常为 2280）；
+   - **Key-E**：仅用于 WiFi / 蓝牙 / AI 加速卡（尺寸通常为 2230）；
+   - 严禁建议用户把 Key-M SSD 插到 Key-E 槽位。
+4. **以太网供电 (PoE)**：
+   - 区分 `802.3af`（15.4W）与 `802.3at`（30W PoE+）。`reCamera Pro` 需保证交换机端口支持 802.3at。
+
+---
+
+## 4. 推荐呈现模板
+
+向用户输出采购清单时，必须使用如下清晰结构：
+
+```markdown
+### 🛒 硬件采购清单建议（BOM）
+
+#### 1. 主计算单元
+- **产品型号**：reComputer J4012（NVIDIA Jetson Orin NX 16GB）
+- **推荐 SKU**：`110110145`
+- **购买链接**：[Seeed 官方商城直达](https://www.seeedstudio.com/...)
+
+#### 2. 必需配件 (REQUIRED - 缺少无法开机)
+- ⚠️ **19V 4.74A 电源适配器** (SKU: `313080684`)
+  - 原因：本主机出厂不配电源适配器，必须单独采购 5.5x2.5mm 19V 适配器。
+  - 购买链接：[购买电源](https://www.seeedstudio.com/...)
+- ⚠️ **国标/美标 AC 三脚电源线** (SKU: `106990470`)
+
+#### 3. 推荐选配 (OPTIONAL - 按需选购)
+- **M.2 NVMe SSD 256GB** (SKU: `112990246`)：用于部署 Docker 容器及缓存模型权重。
+- **reSpeaker 4 麦克风阵列** (SKU: `107990193`)：若需额外实现语音呼救感知功能。
+
+> 收到设备并连接网线/电源后，只需对我说“设备已连接，开始部署”，我将直接为您自动化部署落地！
+```