@seeed-studio/solution-cli 0.1.0 → 0.3.0

package/README.md

@@ -1,78 +1,131 @@
 # @seeed-studio/solution-cli
 
-Zero-friction installer and CLI runner for **SenseCraft Engine** and AI Agent Skills (Work Buddy, Claude Code, Codex, CodeBuddy).
+Zero-friction installer, CLI suite, and AI Agent Skill for **SenseCraft Edge IoT Solutions & Hardware Ecosystem** (reComputer Jetson, reCamera, SenseCAP, Grove Vision AI, ESP32).
 
-## Quick Start (One-line Execution)
+Compatible with **Claude Code, Codex, Google Antigravity (AGY), Work Buddy, and CodeBuddy**.
 
-Install the engine and configure your AI Agent skills in one command:
+> 📖 **专属完整使用指南**：如果您需要系统了解本 CLI 的独特使用场景、详细命令参数、多 Agent 宿主集成以及各阶段具体产出物，请直接查阅独立手册：[**SenseCraft Solution CLI 使用与集成全景指南 (docs/cli-guide.md)**](docs/cli-guide.md)。
 
-```bash
-# Interactive mode (scans local agents and prompts for target selection)
-npx @seeed-studio/solution-cli install
-
-# Non-interactive mode for a specific agent (e.g. Work Buddy)
-npx @seeed-studio/solution-cli install --agent workbuddy
+---
 
-# Install to multiple agents non-interactively
-npx @seeed-studio/solution-cli install --agent workbuddy,claude -y
-```
+## 1. Quick Start & Agent Installation
 
-Or install globally:
+Install the underlying engine and configure the AI Agent Skill with a single command:
 
 ```bash
+# Interactive mode (auto-scans local agent environments and prompts for selection)
+npx @seeed-studio/solution-cli install
+
+# Non-interactive mode (e.g. install to Claude Code and Antigravity)
+npx @seeed-studio/solution-cli install --agent claude,antigravity -y
+
+# Install globally
 npm install -g @seeed-studio/solution-cli
-solution-cli install
+solution-cli install -y
 ```
 
----
-
-## Features
+### Supported AI Agent Harnesses
+- **Claude Code**: `~/.claude/skills/sensecraft`
+- **Codex / OpenAI**: `~/.agents/skills/sensecraft` or `~/.codex/skills/sensecraft`
+- **Google Antigravity (AGY)**: `~/.gemini/config/skills/sensecraft`
+- **Work Buddy / Workbody**: `~/.workbuddy/skills/sensecraft`
+- **CodeBuddy**: `~/.codebuddy/skills/sensecraft`
 
-1. **Smart Environment Inspection & Reuse**:
-   - Detects if you already have the SenseCraft Desktop App installed.
-   - Reuses the App's built-in engine binary and bundled solution assets without re-downloading (~30 MB saved, <0.5s execution).
-   - If no App exists, automatically downloads the standalone engine binary from Seeed CDN and verifies cryptographic SHA256 integrity.
+---
 
-2. **Selective Agent Integration**:
-   - Supports **Work Buddy / Workbody**, **Claude Code**, **Codex**, and **CodeBuddy**.
-   - Interactive prompt lets you choose which agent(s) to adapt without touching unselected directories.
+## 2. CLI Command Reference
 
-3. **Deterministic Absolute Path Execution**:
-   - Injects explicit, verified binary paths directly into `SKILL.md`, ensuring that desktop Agent GUI processes can invoke `sensecraft-engine` even if shell `$PATH` is not inherited.
+The `solution-cli` provides unified commands for discovery, BOM calculation, device diagnostics, and engine execution:
 
-4. **Installation Ledger & Clean Lifecycle**:
-   - Tracks all installed files in `~/.sensecraft/skills-ledger.json`.
-   - Prevents overwriting user modifications.
-   - Supports clean uninstallation via `solution-cli uninstall`.
+| Command | Description |
+|---|---|
+| `solution-cli hub search "<query>" [--json] [--limit N]` | Search scenarios & reference designs. Connects to live Typesense cloud or seamlessly falls back to bundled catalog. Returns diagnostic playbooks & UTM landing URLs. |
+| `solution-cli product query <family_id> [--json]` | Query hardware family default SKUs, region variants, and physical specs. |
+| `solution-cli product accessories <family_id> [--sku <sku>] [--json]` | Evaluate required vs. optional accessories with strict physical compatibility checks (power, RF antenna, M.2 slots). |
+| `solution-cli install [--agent <agents>] [-y]` | Inspect host environment, download/verify engine, and install Agent skills. |
+| `solution-cli status` | Inspect installed engine binary, content cache, and configured agent skills. |
+| `solution-cli doctor` | Run pre-flight diagnostics (OS, Docker daemon, serial permissions, PATH, ledger). |
+| `solution-cli uninstall [--agent <agents>]` | Cleanly remove SenseCraft skills using the installation ledger. |
+| `sensecraft-engine <subcommand>` | Direct proxy to the underlying high-performance Rust execution engine. |
 
 ---
 
-## Command Reference
+## 3. How the AI Agent Uses the Skill
 
-| Command | Description |
-|---|---|
-| `solution-cli install` | Inspect environment, verify/download engine, and configure Agent skills |
-| `solution-cli status` | Display current engine binary, solution cache, and installed skills |
-| `solution-cli doctor` | Diagnose environment (OS, Docker, serial permissions, PATH, ledger) |
-| `solution-cli uninstall` | Cleanly remove SenseCraft skills from specified agent(s) |
-| `sensecraft-engine <cmd>` | Direct proxy to the underlying Rust engine CLI |
+Once installed, your AI Agent gains deep domain knowledge as an Edge IoT Solution Architect. The skill operates across a **4-tier progressive disclosure lifecycle**:
 
----
+```
+[ Tier 1: 方案咨询与工况诊断 ]
+  Agent 讲透方案业务价值与边缘推理机制 ➔ 依据领域诊断知识库提出 2~3 个关键工况问题 ➔ 给出带静默 UTM 的落地页与源码出口
+         │
+         ▼
+[ Tier 2: 硬件选型与配件 BOM 校验 ]
+  运行配件评估引擎 ➔ 严格区分【必需配件】(电源适配器) 与【可选配件】(安装支架/天线) ➔ 规避物理插头/电压/引脚不兼容
+         │
+         ▼
+[ Tier 3: 设备管理与在线参数修改 ]
+  查询活跃部署 ➔ 读取 reconfigurable: true 字段 ➔ 零重装无损热更新 (如在线修改 MQTT Broker 地址或检测阈值)
+         │
+         ▼
+[ Tier 4: 本地二次开发与自研模型 ]
+  获取官方 GitHub 仓库 ➔ 引导本地代码克隆与模型转换 (trtexec / TensorRT) ➔ 通过 --solutions-dir 驱动本地开发联调闭环
+```
 
-## AI Agent Usage Example
+### 常见自然语言对话范例
+
+#### 范例 1：方案咨询与工况诊断 (Discovery & Diagnosis)
+> **用户**：“我们打算在养老社区做老人跌倒检测，有什么成熟方案推荐吗？”
+>
+> **Agent**：
+> 1. 调用 `solution-cli hub search "养老" --json`；
+> 2. 详细解释 `fall_detection` 方案的端侧姿态估计与逐人时序状态机机制（1.4s 本地低延迟、视频不出本地保护隐私）；
+> 3. 自然给出官方方案落地页与 GitHub 源码地址（携带静默 UTM 跟踪）；
+> 4. **主动发起工况诊断黄金三问**：
+>    - 房间是同一栋楼集中分布（推荐 1 台 Orin 主机拉多路 RTSP 流摊薄成本）还是分散独栋（推荐每间房独立一体机）？
+>    - 现场是否已有支持 RTSP 协议的海康/大华存量摄像头（直接利旧节省采购成本）？
+>    - 卫生间/卧房私密空间是否对纯光学摄像头有顾虑（可选用 60GHz 毫米波雷达替代）？
+
+#### 范例 2：硬件选型与配件兼容性校验 (BOM & Compatibility)
+> **用户**：“选好了，我要买一台 reComputer J4012，帮我看看需要配哪些配件？”
+>
+> **Agent**：
+> 1. 调用 `solution-cli product accessories recomputer_j40 --json`；
+> 2. 明确区分：
+>    - **必需配件**：19V 4.74A DC Jack (5.5x2.5mm) 电源适配器（严禁配 12V 否则无法开机）；
+>    - **可选配件**：NVMe M.2 2280 SSD（Key-M）、双频 Wi-Fi/BT 模组（Key-E 插槽）与匹配的 SMA 天线；
+> 3. 提供官方 SKU 与带 UTM 标记的购买链接，杜绝编造第三方型号。
+
+#### 范例 3：在线参数热修改 (Device Management)
+> **用户**：“我已经部署完设备了，现在想把告警的 MQTT 服务器地址改成本地的 192.168.1.50，怎么弄？”
+>
+> **Agent**：
+> 1. 查询当前应用的可配置参数；
+> 2. 确认 `mqtt_broker` 属于 `reconfigurable: true` 字段；
+> 3. 直接通过管理接口发起更新，提示用户无需重启容器或重装整个系统，参数热生效。
+
+#### 范例 4：二次开发与自研模型替换 (Secondary Dev)
+> **用户**：“我想改一下后处理检测逻辑，换成我们自己的 YOLOv11 跌倒模型，源码在哪里？”
+>
+> **Agent**：
+> 1. 提供方案对应的官方 GitHub 开源仓库地址；
+> 2. 指导用户克隆到本地工作区；
+> 3. 指导通过 TensorRT `trtexec` 完成端侧引擎转换，并在 `docker-compose.override.yml` 中挂载自定义模型；
+> 4. 使用 `sensecraft-engine deploy --solutions-dir ./solutions` 进行本地快速调测。
 
-Once installed, open Work Buddy, Claude Code, or Codex and say:
+---
 
-> "帮我把边缘安全方案 (edge_security) 部署到我的 Jetson 设备 (IP: 192.168.1.120，用户名 harvest)"
+## 4. 技术架构亮点
 
-The Agent will automatically:
-1. Match the `sensecraft` Skill;
-2. Query solution parameters via `sensecraft-engine deploy-info edge_security --lang zh`;
-3. Generate or fill in required parameters;
-4. Execute deployment and stream real-time progress via `sensecraft-engine deploy ...`.
+1. **双轨检索与开箱即用 (Out-of-the-Box)**：
+   - 内置 323 KB 离线核心清单（18 场景、39 参考设计、119 硬件族），无网断网 100% 可用；
+   - 线上发布版内置只读搜索凭据，联网时自动直连 Typesense 云端集群获取实时更新。
+2. **静默商业闭环 (Silent Attribution)**：
+   - 所有落地页、Wiki、商城 SKU 与配件链接均经安全工具注入 `utm_source=sensecraft_agent`，对话自然融入，杜绝生硬广告。
+3. **物理规格防呆保护**：
+   - 内置电源接口（DC 5.5x2.5 vs 5.5x2.1）、极性（中心正极）、电压（19V vs 12V）、M.2 Key-M/Key-E 及 RF 射频天线接头校验，从源头杜绝硬件烧板与返工风险。
 
 ---
 
-## License
+## 5. 开源协议
 
 Apache-2.0 © Seeed Studio

package/bin/cli.js

@@ -4,6 +4,8 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { runInstall, runStatus, runUninstall } from '../lib/installer.js';
 import { runDoctor } from '../lib/doctor.js';
+import { searchHub, queryProductFamily, queryAccessories, createDeploymentLockfile } from '../lib/knowledge.js';
+import { assertCompatibility } from '../lib/compatibility.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(fs.readFileSync(path.resolve(__dirname, '../package.json'), 'utf8'));
@@ -25,6 +27,14 @@ Commands:
   status      Display current engine, solution content, and agent skills status
   doctor      Diagnose environment (platform, permissions, docker, PATH, ledger)
   uninstall   Cleanly remove SenseCraft skills from specified agent(s)
+  hub         Search scenarios and reference designs from Seeed Solution Hub
+              Usage: solution-cli hub search <keyword> [--limit 5] [--locale zh|en] [--json]
+  product     Query product families, SKUs, and verified accessories
+              Usage: solution-cli product query <family_id> [--locale zh|en] [--json]
+                     solution-cli product accessories <family_id> [--sku <sku>] [--json]
+                     solution-cli product verify-compatibility --host <family_id> [--json]
+  lockfile    Create an immutable DeploymentLockfile to isolate deployment execution
+              Usage: solution-cli lockfile create --solution <id> [--version <v>] [--hardware <fams>] [--json]
   help        Show this help message
 
 Options:
@@ -33,13 +43,16 @@ Options:
   --dry-run            Simulate operations without making changes to filesystem
   --skip-content       Skip pulling IoT solution packages from CDN
   --force              Force re-download or re-link even if already installed
-  --json               Output machine-readable JSON (supported by status and doctor)
+  --json               Output machine-readable JSON (supported by all query/diagnostic commands)
+  --locale <zh|en>     Language for hub and product results (default: zh)
+  --limit <num>        Maximum results for search (default: 5)
   --engine-path <path> Use custom engine executable path
 
 Examples:
   npx @seeed-studio/solution-cli install
-  npx @seeed-studio/solution-cli install --agent workbuddy
-  npx @seeed-studio/solution-cli install --agent workbuddy,claude -y
+  solution-cli hub search "跌倒"
+  solution-cli product accessories recomputer_j40
+  solution-cli product query sensecap_watcher --json
   solution-cli status
   solution-cli doctor
 `);
@@ -53,7 +66,15 @@ function parseFlags(rawArgs) {
     skipContent: false,
     force: false,
     json: false,
-    enginePath: null
+    enginePath: null,
+    limit: 5,
+    locale: 'zh',
+    sku: null,
+    host: null,
+    accessory: null,
+    solution: null,
+    version: '1.0.0',
+    hardware: null,
   };
 
   for (let i = 0; i < rawArgs.length; i++) {
@@ -74,6 +95,22 @@ function parseFlags(rawArgs) {
       flags.json = true;
     } else if (a === '--engine-path' && rawArgs[i + 1]) {
       flags.enginePath = rawArgs[++i];
+    } else if (a === '--limit' && rawArgs[i + 1]) {
+      flags.limit = parseInt(rawArgs[++i], 10) || 5;
+    } else if (a === '--locale' && rawArgs[i + 1]) {
+      flags.locale = rawArgs[++i];
+    } else if (a === '--sku' && rawArgs[i + 1]) {
+      flags.sku = rawArgs[++i];
+    } else if (a === '--host' && rawArgs[i + 1]) {
+      flags.host = rawArgs[++i];
+    } else if (a === '--accessory' && rawArgs[i + 1]) {
+      flags.accessory = rawArgs[++i];
+    } else if (a === '--solution' && rawArgs[i + 1]) {
+      flags.solution = rawArgs[++i];
+    } else if (a === '--version' && rawArgs[i + 1]) {
+      flags.version = rawArgs[++i];
+    } else if (a === '--hardware' && rawArgs[i + 1]) {
+      flags.hardware = rawArgs[++i];
     }
   }
 
@@ -123,6 +160,166 @@ async function main() {
         runUninstall(flags);
         break;
 
+      case 'hub': {
+        const sub = args[1] || 'search';
+        if (sub !== 'search') {
+          console.error(`Unknown hub action "${sub}". Supported: "solution-cli hub search <keyword>"`);
+          process.exit(1);
+        }
+        const query = args.slice(2).filter((a) => !a.startsWith('-')).join(' ');
+        const dto = await searchHub({ query, locale: flags.locale, limit: flags.limit });
+        if (flags.json) {
+          console.log(JSON.stringify(dto, null, 2));
+        } else {
+          console.log(`\n🔍 Solutions Hub Search Results for "${query}" (${dto.source}):\n`);
+          if (dto.records.length === 0) {
+            console.log('  No matching scenarios or reference designs found.');
+          } else {
+            dto.records.forEach((r, idx) => {
+              const tag = r.type === 'scenario' ? '\x1b[36m[Scenario]\x1b[0m' : '\x1b[35m[Reference Design]\x1b[0m';
+              console.log(`  ${idx + 1}. ${tag} \x1b[1m${r.title}\x1b[0m (${r.id})`);
+              if (r.summary) console.log(`     ${r.summary}`);
+              if (r.reference_designs?.length) console.log(`     对应参考设计: ${r.reference_designs.join(', ')}`);
+              if (r.family_ids?.length) console.log(`     推荐硬件族: ${r.family_ids.join(', ')}`);
+              if (r.presets?.length) console.log(`     预设模式: ${r.presets.join(', ')}`);
+              if (r.wiki_url) console.log(`     开发 Wiki: ${r.wiki_url}`);
+              if (r.diagnostic_playbook?.questions?.length) {
+                console.log('     现场工况诊断提问指引:');
+                r.diagnostic_playbook.questions.forEach((q) => {
+                  console.log(`       • ${q.question} \x1b[90m(决断考量: ${q.rationale})\x1b[0m`);
+                });
+              }
+              console.log('');
+            });
+          }
+          if (dto.warnings.length) {
+            dto.warnings.forEach((w) => console.log(`\x1b[33mNote:\x1b[0m ${w}`));
+          }
+        }
+        break;
+      }
+
+      case 'product': {
+        const sub = args[1] || 'query';
+        const familyId = args.slice(2).find((a) => !a.startsWith('-')) || flags.host;
+
+        if (sub === 'query') {
+          if (!familyId) {
+            console.error('Please specify a product family ID (e.g. "solution-cli product query recomputer_j40")');
+            process.exit(1);
+          }
+          const dto = queryProductFamily(familyId, { locale: flags.locale });
+          if (flags.json) {
+            console.log(JSON.stringify(dto, null, 2));
+          } else {
+            const fam = dto.records[0];
+            if (!fam) {
+              console.log(`Product family "${familyId}" not found.`);
+            } else {
+              console.log(`\n📦 Product Family: \x1b[1m${fam.title}\x1b[0m (${fam.family_id})`);
+              console.log(`  Default SKU: ${fam.default_sku || 'N/A'}`);
+              console.log(`  Regions: ${(fam.regions || []).join(', ') || 'Global'}`);
+              console.log(`  SKUs Available: ${fam.skus_count}`);
+              if (fam.physical_spec?.power_input) {
+                const p = fam.physical_spec.power_input;
+                console.log(`  Power Spec: ${p.voltage_v || ''}V ${p.min_current_a || ''}A (${p.connector}) ${p.polarity || ''}`);
+              }
+              console.log(`  Required Accessories: ${fam.required_accessories_count}`);
+              console.log(`  Optional Accessories: ${fam.optional_accessories_count}`);
+            }
+          }
+        } else if (sub === 'accessories') {
+          if (!familyId) {
+            console.error('Please specify a product family ID (e.g. "solution-cli product accessories recomputer_j40")');
+            process.exit(1);
+          }
+          const dto = queryAccessories(familyId, { sku: flags.sku, locale: flags.locale });
+          if (flags.json) {
+            console.log(JSON.stringify(dto, null, 2));
+          } else {
+            const record = dto.records[0];
+            if (!record) {
+              console.log(`Product family "${familyId}" not found.`);
+            } else {
+              console.log(`\n📦 Verified Accessories for \x1b[1m${record.host_title}\x1b[0m (${record.family_id}):`);
+              console.log(`  Host Default SKU: ${record.host_sku}`);
+              if (record.physical_spec?.power_input) {
+                const p = record.physical_spec.power_input;
+                console.log(`  Host Power Spec: ${p.voltage_v || ''}V ${p.min_current_a || ''}A (${p.connector || ''})`);
+              }
+
+              console.log('\n  \x1b[33m[REQUIRED (必需配件)]\x1b[0m');
+              if (record.accessories.required.length === 0) {
+                console.log('    (无强制单独采购的配件)');
+              } else {
+                record.accessories.required.forEach((acc) => {
+                  const stat = acc.compatibility.is_compatible ? '\x1b[32m✔\x1b[0m' : '\x1b[31m✖\x1b[0m';
+                  console.log(`    ${stat} \x1b[1m${acc.name}\x1b[0m (SKU: ${acc.sku || 'N/A'}, Qty: ${acc.qty})`);
+                  if (acc.reason) console.log(`      原因: ${acc.reason}`);
+                  if (acc.url) console.log(`      购买链接: ${acc.url}`);
+                });
+              }
+
+              console.log('\n  \x1b[36m[OPTIONAL (推荐选配)]\x1b[0m');
+              if (record.accessories.optional.length === 0) {
+                console.log('    (无选配项)');
+              } else {
+                record.accessories.optional.slice(0, 10).forEach((acc) => {
+                  const stat = acc.compatibility.is_compatible ? '\x1b[32m✔\x1b[0m' : '\x1b[31m✖\x1b[0m';
+                  console.log(`    ${stat} ${acc.name} (SKU: ${acc.sku || 'N/A'})`);
+                  if (acc.url) console.log(`      购买链接: ${acc.url}`);
+                });
+              }
+              console.log('');
+            }
+          }
+        } else if (sub === 'verify-compatibility') {
+          const comp = assertCompatibility(null, {
+            id: flags.accessory || 'custom_accessory',
+            name: flags.accessory || 'Custom Accessory',
+          });
+          if (flags.json) {
+            console.log(JSON.stringify(comp, null, 2));
+          } else {
+            const sym = comp.isCompatible ? '\x1b[32m✔\x1b[0m' : '\x1b[31m✖\x1b[0m';
+            console.log(`\n${sym} Physical Compatibility Status: ${comp.status}\n`);
+            comp.dimensions.forEach((d) => {
+              console.log(`  - [${d.dimension}] ${d.status}: ${d.reason}`);
+            });
+            console.log('');
+          }
+        } else {
+          console.error(`Unknown product action "${sub}". Supported: query, accessories, verify-compatibility`);
+          process.exit(1);
+        }
+        break;
+      }
+
+      case 'lockfile': {
+        const sub = args[1] || 'create';
+        if (sub !== 'create') {
+          console.error(`Unknown lockfile action "${sub}". Supported: "solution-cli lockfile create"`);
+          process.exit(1);
+        }
+        const solutionId = flags.solution || 'unspecified_solution';
+        const hardware = (flags.hardware || '').split(',').map((h) => h.trim()).filter(Boolean);
+        const lockfile = createDeploymentLockfile({
+          solutionId,
+          solutionVersion: flags.version,
+          selectedHardware: hardware,
+        });
+        if (flags.json) {
+          console.log(JSON.stringify(lockfile, null, 2));
+        } else {
+          console.log('\n🔒 Generated DeploymentLockfile:');
+          console.log(`  Solution: ${lockfile.solution_id}@${lockfile.solution_version}`);
+          console.log(`  Dataset: ${lockfile.dataset_version}`);
+          console.log(`  Network Isolation: Commercial queries DENIED during apply`);
+          console.log(`  Selected Hardware: ${lockfile.selected_hardware.join(', ') || 'Local Host'}\n`);
+        }
+        break;
+      }
+
       default:
         console.error(`Unknown command: "${command}". Run "solution-cli help" for usage.`);
         process.exit(1);

package/catalog/client-config.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://spec.seeedstudio.com/schemas/v2/client-config.json",
+  "baked_at": "2026-10-13T09:54:46.940Z",
+  "typesense": {
+    "host": "https://rel-search.seeedstudio.com",
+    "search_key_solution": "dNsKBp0Pepdz9tvyIY1O92EMOM00XCHv",
+    "search_key_reference_design": "rEy4VhZnqEmrduFG2e8uvfWMz5ZzXhjb",
+    "search_key_purchase_profile": "YrowCXcDOGTt9KedslTEmeY0ZJEhlBml"
+  }
+}