@seeed-studio/solution-cli 0.2.0 → 0.3.1

package/README.md

@@ -1,78 +1,143 @@
 # @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 one command:
 
 ```bash
-npm install -g @seeed-studio/solution-cli
-solution-cli install
+npx -y @seeed-studio/solution-cli@latest install -y
 ```
 
----
-
-## Features
+The same command is safe to repeat. It checks the signed stable Engine release,
+reuses an equal or newer local Engine, and upgrades an older one. Existing
+modified or unregistered skills and protected symlinks are preserved. Use
+`--agent claude,antigravity` to select agents, or `--engine-path <path>` to pin
+a valid Engine binary. `--force` re-downloads an equal or older Engine and
+overwrites existing skill files, including user modifications; use it only when
+that overwrite is intended. Protected external symlinks are not followed, and
+it never downgrades a newer discovered Engine.
 
-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.
+Automatic reuse/upgrade rules start with solution-cli 0.3.1; if npm `latest` is
+still 0.3.0, those rules are not live. At this verification, 0.3.1 is pending
+publication. A latest release or signature failure stops before changing the
+Engine or skills; an offline host must use a valid explicit local Engine path.
 
-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.
+The interactive form remains available when prompts are wanted:
 
-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.
+```bash
+npx -y @seeed-studio/solution-cli@latest install
+```
 
-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`.
+### 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`
 
 ---
 
-## Command Reference
+## 2. CLI Command Reference
+
+The `solution-cli` provides unified commands for discovery, BOM calculation, device diagnostics, and engine execution:
 
 | 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 |
+| `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. |
 
 ---
 
-## AI Agent Usage Example
+## 3. How the AI Agent Uses the Skill
+
+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**:
 
-Once installed, open Work Buddy, Claude Code, or Codex and say:
+```
+[ Tier 1: 方案咨询与工况诊断 ]
+  Agent 讲透方案业务价值与边缘推理机制 ➔ 依据领域诊断知识库提出 2~3 个关键工况问题 ➔ 给出带静默 UTM 的落地页与源码出口
+         │
+         ▼
+[ Tier 2: 硬件选型与配件 BOM 校验 ]
+  运行配件评估引擎 ➔ 严格区分【必需配件】(电源适配器) 与【可选配件】(安装支架/天线) ➔ 规避物理插头/电压/引脚不兼容
+         │
+         ▼
+[ Tier 3: 设备管理与在线参数修改 ]
+  查询活跃部署 ➔ 读取 reconfigurable: true 字段 ➔ 零重装无损热更新 (如在线修改 MQTT Broker 地址或检测阈值)
+         │
+         ▼
+[ Tier 4: 本地二次开发与自研模型 ]
+  获取官方 GitHub 仓库 ➔ 引导本地代码克隆与模型转换 (trtexec / TensorRT) ➔ 通过 --solutions-dir 驱动本地开发联调闭环
+```
+
+### 常见自然语言对话范例
+
+#### 范例 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 <id> --solutions-dir ./solutions` 进行本地快速调测。
+
+---
 
-> "帮我把边缘安全方案 (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

@@ -42,7 +42,7 @@ Options:
   -y, --yes            Accept default detected selections non-interactively
   --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
+  --force              Re-download equal/older stable Engine and overwrite existing skill files, including local modifications; never downgrade a newer local Engine
   --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)
@@ -183,6 +183,12 @@ async function main() {
               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('');
             });
           }

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"
+  }
+}