@seeed-studio/solution-cli 0.3.2 → 0.4.1

package/README.md

@@ -1,151 +1,199 @@
 # @seeed-studio/solution-cli
 
-Zero-friction installer, CLI suite, and AI Agent Skill for **SenseCraft Edge IoT Solutions & Hardware Ecosystem** (reComputer Jetson, reCamera, SenseCAP, Grove Vision AI, ESP32).
+Install the signed Rust deployment engine and the `solution-cli` AI Agent Skill for Seeed edge IoT solutions and hardware.
 
-Compatible with **Claude Code, Codex, Google Antigravity (AGY), Work Buddy, and CodeBuddy**.
+## 1. Quick Start: Install to Your Agent (快速安装与宿主配置)
 
-> 📖 **专属完整使用指南**：如果您需要系统了解本 CLI 的独特使用场景、详细命令参数、多 Agent 宿主集成以及各阶段具体产出物，请直接查阅独立手册：[**SenseCraft Solution CLI 使用与集成全景指南 (docs/cli-guide.md)**](docs/cli-guide.md)。
+**推荐方式：npm 全局安装并挂载到指定 Agent**
+（将 `solution-cli` 注册到系统全局 PATH，Agent 在对话中调用方案/硬件查询毫秒级响应，避免因 PATH 缺失导致的报错重试）：
 
----
+| 目标 AI 宿主 | 专属安装命令（直接复制发给 AI 或在终端运行） | 技能挂载路径 |
+|---|---|---|
+| **豆包工作 (Doubao Work)** | `npm install -g @seeed-studio/solution-cli && solution-cli install --agent doubao` | `~/.doubao/skills` |
+| **Claude Code** | `npm install -g @seeed-studio/solution-cli && solution-cli install --agent claude` | `~/.claude/skills` |
+| **OpenAI Codex** | `npm install -g @seeed-studio/solution-cli && solution-cli install --agent codex` | `~/.agents/skills` 或 `~/.codex/skills` |
+| **Google Antigravity** | `npm install -g @seeed-studio/solution-cli && solution-cli install --agent antigravity` | `~/.gemini/config/skills` |
+| **WorkBuddy** | `npm install -g @seeed-studio/solution-cli && solution-cli install --agent workbuddy` | `~/.workbuddy/skills` |
+| **CodeBuddy** | `npm install -g @seeed-studio/solution-cli && solution-cli install --agent codebuddy` | `~/.codebuddy/skills` |
+| **Hermes Agent** | `npm install -g @seeed-studio/solution-cli && solution-cli install --agent hermes` | `$HERMES_HOME/skills` (默认 `~/.hermes/skills`) |
+| **全部 Agent (全量检测)** | `npm install -g @seeed-studio/solution-cli && solution-cli install --agent all` | 上述全部已检测目录 |
+| **自定义路径 (如 Cursor)** | `npm install -g @seeed-studio/solution-cli && solution-cli install --skills-dir <路径>` | `<自定义路径>/solution-cli` |
 
-## 1. Quick Start & Agent Installation
+> [!TIP]
+> - **为什么使用 `npm install -g`？** 全局安装后，系统内已有 `solution-cli` 命令。AI Agent 在后续对话中调用方案与硬件查询无需每次通过网络重新下载包，避免产生 `command not found: solution-cli` 报错。
+> - **发给 AI 助手**：直接复制上表中对应的专属命令发给你的 AI 助手（例如对豆包说：*“请帮我运行：`npm install -g @seeed-studio/solution-cli && solution-cli install --agent doubao`”*）。
+> - **免全局安装（npx 备选）**：若无系统全局 npm 写入权限，仍可使用 npx 免全局安装：`npx -y @seeed-studio/solution-cli install --agent <id>`。
+> - **国内镜像延迟排查**：若遇 npm 同步延迟，可在命令末尾加上 `--registry=https://registry.npmjs.org/`。
 
-Install the underlying engine and configure the AI Agent Skill with one command:
+### 开发者本地源码部署
+
+在克隆的代码仓库根目录下，直接使用本地源码将 Skill 挂载到指定 Agent，无需发布或下载 npm 包：
 
 ```bash
-npx -y @seeed-studio/solution-cli@latest install --agent workbuddy -y
+node bin/cli.js install --agent <doubao|claude|codex|antigravity|codebuddy>
 ```
 
-This example targets WorkBuddy explicitly. Replace `workbuddy` with the current
-Agent ID for another host. Use `npx -y @seeed-studio/solution-cli@latest install`
-for the interactive form: when one or more Agents are detected, pressing Enter
-selects all detected Agents, while entering the corresponding number selects one
-host. In non-interactive mode, `install -y` without `--agent` also selects all
-detected Agents when any are detected. If none are detected, these defaults still
-use the CLI's default target set; pass `--agent <agent-id>` to control the scope
-explicitly.
-
-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.
-
-Automatic reuse/upgrade rules start with publicly published solution-cli 0.3.1.
-A latest release or signature failure stops before changing the
-Engine or skills; an offline host must use a valid explicit local Engine path.
-
-The interactive form remains available when prompts are wanted:
+### 免安装即时查询
+
+无需安装任何依赖，可直接使用 `npx` 随用随走：
 
 ```bash
-npx -y @seeed-studio/solution-cli@latest install
+npx -y @seeed-studio/solution-cli hub search "农业"
+npx -y @seeed-studio/solution-cli product query recomputer_j40 --json
 ```
 
-### Supported AI Agent Harnesses
-- **Claude Code**: `~/.claude/skills/solution-cli`
-- **Codex / OpenAI**: `~/.agents/skills/solution-cli` or `~/.codex/skills/solution-cli`
-- **Google Antigravity (AGY)**: `~/.gemini/config/skills/solution-cli`
-- **Work Buddy / Workbody**: `~/.workbuddy/skills/solution-cli`
-- **CodeBuddy**: `~/.codebuddy/skills/solution-cli`
+## 2. How to Deploy a Solution (方案部署指南)
+
+方案部署支持**本地部署（Local Docker，最简且无需 SSH 密钥）**与**远程部署（Remote SSH 密钥认证）**。
+
+### 部署 4 步走流程 (SOP)
+
+1. **查找方案**：
+   ```bash
+   solution-cli hub search "农业" --json
+   ```
+2. **读取方案部署规格与预设**：
+   ```bash
+   sensecraft-engine deploy-info <solution-id> --lang zh
+   ```
+3. **准备部署参数文件** `./.sensecraft-work/body.json`：
+   - **本地部署（推荐快速体验，Localhost Docker）**：
+     ```json
+     {
+       "solution_id": "<solution-id>",
+       "preset_id": "default",
+       "selected_devices": ["host_device"],
+       "device_connections": {
+         "host_device": {
+           "target": "local_host",
+           "target_type": "local"
+         }
+       }
+     }
+     ```
+   - **远程边缘设备部署（SSH 密钥认证）**：
+     ```json
+     {
+       "solution_id": "<solution-id>",
+       "preset_id": "default",
+       "selected_devices": ["host_device"],
+       "device_connections": {
+         "host_device": {
+           "target": "remote_edge",
+           "target_type": "remote",
+           "host": "192.168.1.50",
+           "username": "seeed",
+           "key_file": "~/.ssh/id_ed25519"
+         }
+       }
+     }
+     ```
+4. **一键执行部署并查看状态**：
+   ```bash
+   # 验证与执行部署
+   sensecraft-engine deploy --params ./.sensecraft-work/body.json --yes
+
+   # 查询部署进度与容器日志
+   sensecraft-engine status <deployment-id> --json
+   sensecraft-engine logs <deployment-id>
+   ```
+
+## 3. CLI Command Reference
+
+| Command | Purpose |
+|---|---|
+| `solution-cli install --agent <agent-id> -y` | Install or update the signed Engine and Skill |
+| `solution-cli hub search "<query>" --json` | Find solution scenarios and reference designs |
+| `solution-cli product query <family-id> --json` | Read hardware family specifications |
+| `solution-cli product accessories <family-id> --json` | Check required and compatible accessories |
+| `solution-cli status` | Show Engine, content, and Skill state |
+| `solution-cli doctor --json` | Check OS, permissions, Docker, PATH, and ledger |
+| `sensecraft-engine solution list --json` | List locally available deployable solutions |
+| `sensecraft-engine deploy-info <id> --lang en` | Read presets, devices, targets, and required values |
+| `sensecraft-engine deploy --params ./.sensecraft-work/body.json --yes --detach --lang en` | Start an approved deployment |
+| `sensecraft-engine status <deployment-id> --json` | Poll a detached deployment |
+| `sensecraft-engine logs <deployment-id> --since <N>` | Read deployment events |
 
----
+The Engine binary remains named `sensecraft-engine` for compatibility; the user-facing package and Skill are `solution-cli`. See [the deployment reference](skills/solution-cli/references/deploy.md) before applying changes to a device.
 
-## 2. CLI Command Reference
+### Catalog relationships and links
 
-The `solution-cli` provides unified commands for discovery, BOM calculation, device diagnostics, and engine execution:
+The catalog separates four things that should not be treated as synonyms:
 
-| 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 Solution CLI skills using the installation ledger. |
-| `sensecraft-engine <subcommand>` | Direct proxy to the underlying high-performance Rust execution engine. |
+- **Scenario** is the business landing page and points to related Tech pages and Reference Designs.
+- **Tech** is an independently owned technology page. It is not the Wiki for an RD.
+- **Reference Design (RD)** is the concrete architecture and product design. It may have a deployment document and presets.
+- **Deployable content** is the RD's mapped deployment document. A landing page or RD without a valid mapping is informational and cannot be assumed deployable.
+
+Use the compact catalog flow instead of reading manifests or writing a parser:
 
----
+```bash
+solution-cli hub list --type reference_design --locale en --page 1 --limit 50 --json
+solution-cli hub get <id> --locale en --section overview --json
+solution-cli hub get <id> --locale en --section links --json
+solution-cli hub get <id> --locale en --section architecture --json
+solution-cli hub get <id> --locale en --section products --json
+solution-cli hub get <id> --locale en --section deployment --json
+```
 
-## 3. How the AI Agent Uses the Skill
+Follow `next_page` for a complete bundled snapshot. Use `search` for a
+specific request, then `get` for the selected records and only the sections
+needed to answer it. The three production landing hosts are locale-specific:
+English `www.seeed.cc`, Chinese `www.seeedstudio.com.cn`, and Japanese
+`www.seeed.co.jp`. Use the URLs returned by `hub get --section links`; do not
+construct Wiki, CDN, or translated URLs from an ID. A translated body may
+fall back to another content language while its production page remains
+published, so report the returned content language separately.
 
-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**:
+For deployment, confirm the RD mapping with the local Engine:
 
+```bash
+sensecraft-engine deploy-info <solution-id> --lang en
 ```
-[ Tier 1: 方案咨询与工况诊断 ]
-  Agent 讲透方案业务价值与边缘推理机制 ➔ 依据领域诊断知识库提出 2~3 个关键工况问题 ➔ 给出带静默 UTM 的落地页与源码出口
-         │
-         ▼
-[ Tier 2: 硬件选型与配件 BOM 校验 ]
-  运行配件评估引擎 ➔ 严格区分【必需配件】(电源适配器) 与【可选配件】(安装支架/天线) ➔ 规避物理插头/电压/引脚不兼容
-         │
-         ▼
-[ Tier 3: 设备管理与在线参数修改 ]
-  查询活跃部署 ➔ 读取 reconfigurable: true 字段 ➔ 零重装无损热更新 (如在线修改 MQTT Broker 地址或检测阈值)
-         │
-         ▼
-[ Tier 4: 本地二次开发与自研模型 ]
-  获取官方 GitHub 仓库 ➔ 引导本地代码克隆与模型转换 (trtexec / TensorRT) ➔ 通过 --solutions-dir 驱动本地开发联调闭环
-```
+
+The Hub record describes the published design; `deploy-info` confirms the
+actual local deployment document and presets.
+
+Links and metadata only locate content. To answer a capability, architecture,
+or product question, read the selected `description`, `architecture`, or
+`products` section. Open the exact returned production page or image when it
+matters to the answer. Treat a relative asset path as readable only when its
+signed local content is present; otherwise report the source asset as
+unavailable.
+
+## 4. How the AI Agent Uses the Skill
+
+The Skill maps ordinary language to four stages:
+
+1. **Consultation**: search the catalog and clarify the customer's scenario.
+2. **Hardware selection**: check device families, accessories, and physical compatibility.
+3. **Precheck and deployment**: read `deploy-info`, fill required values, run validation, show side effects, then ask before applying.
+4. **Verification and troubleshooting**: follow deployment status and logs, verify services, and diagnose failures.
+
+For deployment, the Agent must use the installed Engine's absolute path when it is injected into the Skill. For catalog or product queries, use `solution-cli`; if it is not on `PATH`, use `npx @seeed-studio/solution-cli <command>`. Windows native local Docker is unsupported; use a Linux Docker host over SSH. macOS local Docker requires a running Docker Desktop daemon. The CLI does not install Docker Desktop or silently grant `sudo`.
 
 ### 常见自然语言对话范例
 
 #### 范例 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 标记的购买链接，杜绝编造第三方型号。
+
+用户可以直接描述客户需求。Agent 先搜索方案，解释匹配原因，再询问供电、设备、网络和部署位置等缺失信息；没有明确部署确认时不执行部署。
+
+#### 范例 2：硬件配置与配件推荐（查配置、推荐配件、防止买错）
+
+用户询问某个设备（如 reComputer、Watcher）的参数，或询问“买这台主机还需要配什么配件”。Agent 使用 `product query` 和 `product accessories` 查出真实硬件规格，区分必须买的配件（如电源线）和可选配件（如天线/外壳/摄像头），并自动校验接口与频段兼容性，直接给出官方配件清单。
 
 #### 范例 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` 进行本地快速调测。
+用户可以描述要修改的已部署参数。Agent 先读取当前部署和可修改字段，确认目标设备与变更范围，再按设备管理接口执行获得批准的修改。
 
----
+#### 范例 4：二次开发与自研模型替换 (Secondary Dev)
 
-## 4. 技术架构亮点
+用户可以要求源码、模型替换或本地方案调试。Agent 应读取对应方案的开发文档和 `--solutions-dir` 规则，并在部署前展示改动。
 
-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 射频天线接头校验，从源头杜绝硬件烧板与返工风险。
+## 5. 技术架构亮点
 
----
+`solution-cli` 是 npm 安装入口，签名 Rust Engine 负责跨平台查询、预检查、部署状态和日志；方案内容按版本校验后进入本地缓存。在线目录查询失败时，Skill 和 CLI 可使用已安装的本地内容与知识库完成支持的离线查询。
 
-## 5. 开源协议
+## 6. 开源协议
 
 Apache-2.0 © Seeed Studio